25 KiB
CCPE System 重构补充规划说明
0. 本说明用途
本说明用于辅助 Codex 重构 ccpe-system。
前一份规划总结已经说明:
writing-workbench深度创作流程暂时不宜 Full Runtime 化;video-workbench更适合作为自动化 MVP;knowledge-vault已经完成重构;skills-vault已经独立出来,作为 automation Skill 源码仓库;- CCPE 需要补 Agentic 工程治理能力。
本说明只补充 CCPE System 自身重构 所需的边界、目录、分类、迁移和验收规则。
HiFi Agent Studio 与 Agentic Engineering Handbook 已经作为更上层原则存在。Codex 重构 CCPE 时,只需要引用它们的本地路径,不要在 CCPE 中重复粘贴其完整内容。
1. 是否需要给 Codex 提供四层结构说明?
需要,但只需要提供最小边界说明,不需要展开完整方法论。
CCPE 重构时必须知道自己处在整体体系中的位置,否则会出现两个风险:
- 把 CCPE 重构成另一个“总纲领仓库”,重复 HiFi Agent Studio;
- 把 CCPE 重构成项目执行仓库,吞掉
writing-workbench、video-workbench、knowledge-vault或skills-vault的职责。
给 Codex 的最小四层说明如下:
HiFi Agent Studio
= 顶层方法论 / 宪法 / 价值与架构原则
= 本地路径由用户提供
= CCPE 只引用,不复制正文
Agentic Engineering Handbook
= Agentic 运行治理 / 现场规程 / 开工守则
= 本地路径由用户提供
= CCPE 只引用其中规则,不重复维护完整版本
CCPE System
= Agent / Skill / Runtime / Model Card / Committee / Integration Registration 的架构工坊
= 负责分类、建模、审计、重构、登记
= 不直接拥有所有项目运行记录,也不拥有 automation Skill 源码
Project Workbenches / Vaults
= 具体项目执行仓库
= writing-workbench、video-workbench、knowledge-vault 等
= 负责项目 runbook、工作区、运行产物、业务材料、项目内流程记录
此外,skills-vault、MCP、CLI、API 工具属于工具实现或能力供给层:
skills-vault / MCP / CLI / API
= 工具实现层 / 能力供给层
= 可被 CCPE 登记为依赖
= 不属于 CCPE 的核心资产源码
所以,CCPE 的位置是:
CCPE = 架构工坊 + 资产登记中心 + Agentic artifact 设计系统
不是:
CCPE ≠ 顶层方法论仓库
CCPE ≠ 项目运行仓库
CCPE ≠ automation Skill 源码仓库
CCPE ≠ MCP / CLI 工具源码仓库
2. CCPE 重构后的核心定位
重构后的 CCPE System 应定义为:
CCPE System is the architecture forge for designing, auditing, refactoring, registering, and maintaining AI Prompts, Agents, CCPE Skills, Runtimes, Committees, Cognitive Model assets, and external capability registrations.
中文定位:
CCPE System 是 Agentic 时代的智核工程工坊。
它负责把 Prompt、Agent、Skill、Runtime、Committee、Model Card、Model Index、外部工具登记等 AI 资产分类、建模、审计、重构和维护。
CCPE 的第一职责仍然是:
Classify Before Creating
先分类,再创建
也就是:
- 判断这个东西到底是什么;
- 判断它是否应该属于 CCPE;
- 判断它是否应该是 Lite、Agent、Skill、Runtime、Model Card、Model Index、Committee、Integration Registration、Project Runbook 或 external automation Skill;
- 再决定是否创建、重构、登记或拒绝纳入 CCPE。
3. CCPE 不应该做什么
重构时必须把这些红线写进 README、AGENTS.md 或 ccpe-protocol/ccpe-boundaries.md。
3.1 CCPE 不复制 HiFi Agent Studio 和 Handbook
CCPE 可以声明:
This project follows HiFi Agent Studio and Agentic Engineering Handbook.
但不应把二者正文复制进 CCPE。
CCPE 只需要:
- 记录本地路径;
- 记录优先级;
- 记录“本项目执行时必须遵循它们”;
- 必要时提供 CCPE-local 摘要和链接。
3.2 CCPE 不拥有 project execution
writing-workbench、video-workbench、knowledge-vault 的具体 runbook、运行记录、工作区产物,不应迁移进 CCPE。
CCPE 可以定义:
- Runtime Spec;
- Agent Spec;
- Model Card;
- Skill Spec;
- Integration Registration;
- Template;
- Rubric。
但具体项目运行产物应留在对应项目仓库。
3.3 CCPE 不拥有 automation Skill 源码
skills-vault 已经是 automation-oriented Skill 的源码仓库。
例如:
fix-title
markdown-normalizer
citation-checker
report-exporter
source-splitter
tts-batch-generator
image-prompt-exporter
这些源码不应迁移到 CCPE。
CCPE 只在必要时做架构登记:
canonical implementation: skills-vault/skills/fix-title
installed path: .agents/skills/fix-title
used by: ...
authority: ...
validation: ...
safety: ...
3.4 CCPE 不应把所有 Prompt 升级成 Agent
成熟的 Web / GPT / Gemini / Claude 单智能体专家 Prompt,不应默认升级成 CCPE-Agent。
默认路线应是:
CCPE-Lite
+ Model Card if embedded model is stable and important
只有当它需要协作、handoff、authority、tool、state、evaluation 或 runtime participation 时,才升级为 CCPE-Agent。
3.5 CCPE 不应把所有流程做成 Full Runtime
CCPE 可以创建 Runtime Spec,但必须遵循:
Default Lite, Escalate by Evidence
不能把一次性任务默认升成治理级 Runtime。
4. 重构后的 CCPE 资产分类
CCPE 重构时,应将资产分类扩展为以下几类。
4.1 CCPE-Lite
轻量专家提示词 / Prompt Card。
适用:
- 单专家角色;
- 人类直接调用;
- Web / GPT / Gemini / Claude 等 chat 产品;
- 不需要工具、状态、handoff、长期 runtime;
- 有独特认知姿态和工作方法。
典型:
张辽红队评审
韩愈主笔
苏格拉底式提问者
文章审稿人
战略思维助手
Lite 不是低级形态。 在 Web-style expert use 中,Lite 可以是生产级形态。
4.2 CCPE-Agent
长期可维护、可组合、可评估的工作角色。
适用:
- 会参与 multi-agent workflow;
- 需要明确 input/output contract;
- 需要 authority;
- 可能调用工具或 Skill;
- 需要 handoff;
- 需要 evaluation;
- 需要跨项目复用。
典型:
topic-graph-synthesizer.agent.md
knowledge-archivist.agent.md
outline-context-architect.agent.md
red-team-reviewer.agent.md
4.3 CCPE-Committee
多 Agent 预设委员会。
适用:
- 高风险 I 域判断;
- 需要固定角色张力;
- 不允许动态无约束 routing;
- 需要保留独立判断和 synthesis;
- 需要 invocation records;
- 需要 human gate。
典型:
article-outline-review-committee
model-stress-test-committee
strategic-risk-committee
Committee 不等于随便拉多个 Agent。 Committee 必须有:
- members;
- role tension;
- invocation rule;
- report schema;
- synthesis rule;
- human decision gate;
- no-simulation rule。
4.4 CCPE-Skill
可复用能力模块。
注意:CCPE-Skill 不等于 automation script。
CCPE-Skill 可以是:
- method-oriented;
- cognitive;
- workflow-oriented;
- evaluation-oriented;
- transformation-oriented;
- knowledge-management-oriented。
它可能没有脚本,主要是方法、流程、检查清单、推理协议、输出模板和验证标准。
典型:
cognitive-imaging.skill.md
assumption-stress-test.skill.md
argument-chain-inspection.skill.md
model-mining.skill.md
coverage-audit.skill.md
与 skills-vault 的 automation Skill 区分:
CCPE-Skill = 认知 / 方法 / 评估 / 流程能力规格
automation Skill = 可安装、可执行、可测试的工具源码
4.5 CCPE-Runtime
多阶段、多角色、有状态、有 handoff 或工具调用的运行协议。
Runtime 分三类:
interactive/
automation/
hybrid/
Interactive Runtime
适合:
- 深度思考;
- 写作; -建模;
- 概念设计;
- 高不确定性评估。
特征:
- human-led;
- high uncertainty;
- human gates central;
- agents provide judgment, critique, structure, synthesis。
Automation Runtime
适合:
- 低风险;
- 低不确定;
- 可验证;
- 批处理;
- 文件转换;
- 格式清洗;
- 工具链生产。
特征:
- process-led;
- success criteria clear;
- scripts/tools central;
- human inspection optional or sampled。
Hybrid Runtime
适合:
- 深度工作在核心;
- 自动化在边缘;
- 人类做关键判断;
- Agent / Skill 负责收集、整理、格式化、路由、归档。
典型:
video-episode-production.runtime.md
knowledge-material-routing.runtime.md
article-outline-review.runtime.md
4.6 Model Card
认知模型资产。
适用:
- 从文章、讨论、Prompt、Agent 中抽取出的稳定模型;
- 需要跨 Agent / Skill / Runtime 复用;
- 不应被困在某个 Agent 人设中。
Model Card 应记录:
- model name;
- source;
- core problem;
- mechanism;
- scope;
- assumptions;
- procedure;
- failure modes;
- falsification boundary;
- related agents;
- related skills;
- related runtimes;
- version status。
4.7 Model Index
模型库索引。
适用:
- 模型数量增长;
- 需要 taxonomy;
- 需要 dependency map;
- 需要 usage map;
- 需要 overlap / conflict relation;
- 需要版本治理。
4.8 Integration Registration
新增分类,重构时建议加入。
用于登记 CCPE 依赖但不拥有源码的外部能力。
包括:
skills-vault automation skills
MCP servers
CLI tools
API services
installed local tools
platform-specific skills
Integration Registration 只记录架构元数据,不复制实现源码。
示例目录:
ccpe-system/integrations/
skills-vault/
fix-title.registration.md
mcp/
filesystem.registration.md
cli-tools/
ffmpeg.registration.md
api-services/
tts-service.registration.md
每份 registration 应记录:
name:
integration_type:
canonical_implementation:
installed_path_or_endpoint:
used_by:
authority:
allowed_operations:
forbidden_operations:
side_effects:
security_notes:
validation:
failure_behavior:
status:
version:
5. 建议的 CCPE 重构目录
建议重构后的目录大致如下:
ccpe-system/
README.md
AGENTS.md
ccpe-protocol/
ccpe-system-definition.md
ccpe-boundaries.md
ccpe-classification-rules.md
ccpe-artifact-taxonomy.md
ccpe-operating-modes.md
ccpe-layer-spec.md
ccpe-quality-rubric.md
ccpe-migration-policy.md
ccpe-governance-adapter.md
.codex/
skills/
ccpe-forge/
SKILL.md
references/
templates/
workbench/
raw/
analysis/
upgraded/
archive/
experiments/
agents/
lite/
agent-specs/
committees/
skills/
cognitive/
method/
workflow/
evaluation/
runtimes/
interactive/
automation/
hybrid/
model-cards/
foundational/
intermediate/
applied/
workflow-models/
implicit-extracted/
model-index/
model-index.md
model-taxonomy.md
model-dependency-map.md
model-usage-map.md
extraction-log.md
integrations/
skills-vault/
mcp/
cli-tools/
api-services/
templates/
prompt-card/
agent-spec/
committee/
skill-spec/
runtime-spec/
model-card/
model-index-entry/
integration-registration/
audit-report/
migration-report/
关键变化:
- 新增
ccpe-boundaries.md; - 新增
ccpe-artifact-taxonomy.md; - 新增
ccpe-governance-adapter.md; - 新增
integrations/; skills/tool/不再作为 automation script source;- automation skill source 属于
skills-vault; - CCPE 中如需登记 external tool skill,放
integrations/skills-vault/更干净。
6. CCPE 与 skills-vault 的边界
这是重构时必须写清楚的核心边界。
6.1 一句话原则
CCPE 资产拥有或组织业务目标与认知结构;
skills-vault 资产执行可复用自动化动作。
或者:
CCPE decides and designs who does what, why, under what authority.
skills-vault implements repeatable automation actions that can be called by agents or runtimes.
6.2 skills-vault 拥有什么
skills-vault 拥有:
- automation Skill 源码;
SKILL.md;- scripts;
- tests;
- fixtures;
- examples;
- install notes;
- migration records。
典型对象:
fix-title
markdown-normalizer
citation-checker
report-exporter
source-splitter
tts-batch-generator
image-prompt-exporter
6.3 CCPE 拥有什么
CCPE 拥有:
- expert prompt cards;
- durable agent specs;
- committees;
- runtimes;
- cognitive / method / evaluation / workflow skills;
- model cards;
- model indexes;
- external capability registrations。
6.4 .agents/skills 是什么
.agents/skills 是本机安装面,不是源码主仓库。
skills-vault = source of truth
.agents/skills = runtime installation copy
ccpe-system/integrations = architecture registration
6.5 MCP 类似处理
MCP server、CLI、API 工具都类似 external capability。
原则:
实现源码不进 CCPE;
架构依赖进 CCPE;
运行安装面不当 source of truth。
7. CCPE Forge Skill 需要升级
原来的 ccpe-forge 有:
- Creator Mode;
- Auditor Mode;
- Refactor Mode;
- Model Mining Mode。
重构后建议增加或强化以下能力。
7.1 Classification First Gate
任何模式启动前,Forge 必须先做 classification:
Input artifact belongs to:
- CCPE-Lite
- CCPE-Agent
- CCPE-Committee
- CCPE-Skill
- CCPE-Runtime
- Model Card
- Model Index
- Integration Registration
- Project Runbook
- automation Skill source
- external tool / MCP / CLI / API
- out of scope
Forge 不得在未分类前直接生成 artifact。
7.2 Boundary Check
Forge 必须判断目标是否应该进入 CCPE。
若输入是:
automation script / installable skill source
应建议进入:
skills-vault
若输入是:
project-specific runbook / execution record / topic docs / writing project output
应建议进入:
knowledge-vault / writing-workbench / video-workbench
若输入是:
agent spec / runtime spec / model card / committee / architecture registration
才进入:
ccpe-system
7.3 Registrar Mode
建议新增:
Registrar Mode
用于登记外部能力,而不是复制外部源码。
适用:
- skills-vault skill;
- MCP server;
- CLI tool;
- API service;
- installed local capability。
输出:
integration registration
authority
safety
validation
used_by
failure behavior
7.4 Runtime Designer Mode
可以独立于 Creator Mode,专门用于 Runtime Spec。
必须强制输出:
- runtime orientation;
- mode:Lite / Standard / Full;
- participants;
- state protocol;
- human gates;
- invocation authenticity rule;
- simulation labeling;
- stop rule;
- source fidelity;
- evaluation level;
- artifact contracts;
- downstream handoff rules。
7.5 Migration Auditor
用于旧资产迁移。
必须判断:
- 旧 prompt 是否应保持 Lite;
- 是否需要 Model Card;
- 是否需要 Agent Spec;
- 是否需要 Skill;
- 是否需要 Runtime;
- 是否属于 skills-vault;
- 是否属于 project workbench;
- 是否不应迁移。
特别注意:
不要把旧 Prompt 自动重写成 generic corporate sludge。 保留原始 intellectual flavor、核心隐喻、认知姿态和用户意图。
8. CCPE 重构时的迁移策略
8.1 不做大爆炸迁移
不要一次性把所有旧资产重构成新形态。
先做 inventory:
artifact path
current type
suspected target type
business use
reuse level
risk level
owner
migration action
迁移动作包括:
keep-as-lite
create-model-card
upgrade-to-agent-spec
extract-skill
create-runtime
register-integration
move-to-skills-vault
move-to-project-workbench
archive
reject
8.2 成熟 Web Agent 默认保持 Lite
例如:
张辽
韩愈
强哥的徒弟
认知显影
巨人认知
如果它们原本是成熟 Web-style expert prompt,默认保持:
agents/lite/
只有满足条件才升级:
- 需要作为 workflow node;
- 需要调用 tools / skills;
- 需要 authority;
- 需要 handoff;
- 需要 evaluation;
- 需要 invocation record;
- 需要长期 runtime participation。
8.3 模型优先抽成 Model Card,不急着 Skill 化
如果某个 Agent 内含稳定认知模型,应优先抽成:
model-cards/
而不是直接做 Skill。
判断:
Model Card = 它怎么看问题
Skill = 它如何执行某个方法
Agent = 谁来用它完成任务
Runtime = 它们如何协作
8.4 Runtime 谨慎创建
只有当涉及:
- 多阶段;
- 多角色;
- 状态;
- handoff;
- human gate;
- tools;
- automation;
- synthesis;
- archival;
- audit;
- downstream dependency;
才创建 Runtime。
否则用 Lite / Agent / Skill / Model Card 即可。
9. CCPE 应内置的运行治理适配
CCPE 不需要复制 Agentic Engineering Handbook 正文,但应在自己的 artifact 模板中嵌入必要字段。
9.1 Runtime Spec 必须包含
runtime_name:
runtime_orientation: interactive / automation / hybrid
mode: lite / standard / full
qpi_class:
purpose:
inputs:
outputs:
participants:
human_gates:
state_protocol:
invocation_authenticity:
simulation_labeling:
authority_matrix:
tool_permissions:
source_fidelity:
evaluation_level:
stop_rule:
handoff_rules:
related_models:
related_skills:
related_integrations:
9.2 Agent Spec 必须包含
agent_name:
role:
responsibility:
inputs:
outputs:
authority_level:
allowed_tools:
forbidden_actions:
required_skills:
related_models:
handoff_rules:
evaluation:
invocation_requirements:
failure_modes:
9.3 Committee Spec 必须包含
committee_name:
purpose:
qpi_class:
members:
role_tension:
invocation_rule:
independent_report_required:
synthesis_rule:
human_gate:
simulation_policy:
evaluation:
9.4 CCPE-Skill Spec 必须包含
skill_name:
skill_type: cognitive / method / workflow / evaluation / transformation / knowledge-management
purpose:
input_contract:
output_contract:
procedure:
validation:
authority:
related_models:
used_by:
not_to_be_confused_with:
9.5 Integration Registration 必须包含
name:
integration_type: skills-vault / mcp / cli / api / installed-skill
canonical_implementation:
installed_path_or_endpoint:
used_by:
authority:
allowed_operations:
forbidden_operations:
side_effects:
security_notes:
validation:
failure_behavior:
status:
9.6 Model Card 必须包含
model_name:
aliases:
source_material:
core_problem:
mechanism:
scope:
assumptions:
procedure:
failure_modes:
falsification_boundary:
related_agents:
related_skills:
related_runtimes:
version_status:
10. CCPE 重构验收标准
重构完成后,Codex 应能稳定回答这些问题。
10.1 归属判断
给定一个 artifact,Codex 能判断它应该属于:
CCPE-Lite
CCPE-Agent
CCPE-Committee
CCPE-Skill
CCPE-Runtime
Model Card
Model Index
Integration Registration
Project Runbook
skills-vault automation Skill
out of scope
10.2 不混仓
Codex 不会:
- 把 automation Skill 源码迁入 CCPE;
- 把 project runbook 迁入 CCPE;
- 把 knowledge-vault 运行产物迁入 CCPE;
- 把 MCP 实现迁入 CCPE;
- 把所有旧 Prompt 升级成 Agent Spec。
10.3 能做 architecture registration
给定 skills-vault/skills/fix-title,Codex 能生成:
ccpe-system/integrations/skills-vault/fix-title.registration.md
但不会复制源码。
10.4 能创建合格 Runtime Spec
给定一个 workflow,Codex 能先判断是否需要 Runtime。 如果需要,能输出包含:
- mode;
- qpi;
- participants;
- human gates;
- state;
- invocation authenticity;
- stop rule;
- evaluation;
- authority;
- integrations。
10.5 能保持 Lite 形态
给定成熟专家 Prompt,Codex 不会盲目重构成 Agent Spec。 它会先判断:
keep-as-lite
+ optional model-card
是否足够。
10.6 能避免过度工程
给定一次性任务,Codex 不会自动创建:
- committee;
- full runtime;
- coverage audit;
- downstream handoff;
- integrations;
- model index。
除非用户明确将任务升级为系统建设。
11. 建议的 CCPE 重构顺序
Batch 0:备份与盘点
- 备份现有
ccpe-system; - 生成 inventory;
- 标记现有 artifact 类型;
- 标记疑似迁移去向。
Batch 1:重写 README 与 AGENTS.md
README 明确:
- CCPE 是什么;
- 不是什么;
- 与 HiFi / Handbook 的关系;
- 与 project workbench 的关系;
- 与 skills-vault / MCP / CLI 的关系。
AGENTS.md 明确 Codex 在本仓库中的行为规则:
- 先分类;
- 不混仓;
- 不复制外部源码;
- 不默认重构为 Full Runtime;
- 不模拟 Agent 输出;
- 不覆盖 intellectual flavor;
- 遵循本地 HiFi / Handbook 路径。
Batch 2:重建 ccpe-protocol
至少创建或更新:
ccpe-system-definition.md
ccpe-boundaries.md
ccpe-classification-rules.md
ccpe-artifact-taxonomy.md
ccpe-operating-modes.md
ccpe-layer-spec.md
ccpe-quality-rubric.md
ccpe-migration-policy.md
ccpe-governance-adapter.md
Batch 3:建立 integrations
创建:
integrations/skills-vault/
integrations/mcp/
integrations/cli-tools/
integrations/api-services/
并加入 README 说明:
CCPE registers external capability dependency here.
CCPE does not own implementation source here.
Batch 4:重建 templates
至少包括:
prompt-card template
agent-spec template
committee template
ccpe-skill template
runtime-spec template
model-card template
model-index-entry template
integration-registration template
audit-report template
migration-report template
Batch 5:升级 ccpe-forge
升级 Forge Skill:
- classification first;
- boundary check;
- registrar mode;
- runtime designer mode;
- migration auditor;
- no source duplication;
- no automatic full runtime;
- preserve intellectual flavor。
Batch 6:小样本迁移验证
不要立刻全仓迁移。
先选 3-5 个典型样本:
一个成熟 Lite Agent:如张辽
一个含模型的 Prompt:抽 Model Card
一个 Runtime:如 article-outline-review 或 viewpoint-discussion-distillation 的 CCPE spec
一个 automation Skill:如 fix-title,只做 registration
一个 project capability:确认留在 project workbench,不迁入 CCPE
验证分类、目录、模板、Forge 行为是否正确。
Batch 7:全仓 audit
基于成功样本再批量迁移。
12. 给 Codex 的核心执行指令
可以直接附在上下文最后:
When refactoring ccpe-system:
1. Do not start by writing new agents.
2. Start by clarifying repository boundaries and artifact classification rules.
3. Do not duplicate HiFi Agent Studio or Agentic Engineering Handbook content; only reference their local paths.
4. Do not migrate project runbooks or project outputs into CCPE.
5. Do not migrate automation Skill source from skills-vault into CCPE.
6. Add integration registration support for skills-vault, MCP, CLI tools, and API services.
7. Update ccpe-forge so every creation/refactor begins with classification and boundary check.
8. Keep mature single-agent prompts as CCPE-Lite by default.
9. Extract stable cognitive models into Model Cards before converting them into Skills or Agents.
10. Create Runtime only when stages, state, routing, handoff, human gates, tools, automation, synthesis, audit, or archival justify it.
11. Any external capability used by a CCPE Agent or Runtime should be registered, not copied.
12. All new templates must include authority, evaluation, status, related assets, and lifecycle metadata.
13. Preserve original intellectual flavor during refactor.
14. Avoid turning CCPE into another project execution repository or automation script repository.
13. 一句话总结
这次 CCPE 重构的核心不是“多造 Agent”,而是把 CCPE 从早期 Prompt / Agent 工坊升级为:
Agentic architecture forge
+ cognitive model registry
+ runtime specification system
+ external capability registration center
它应该回答:
这个 AI 资产是什么?
它该不该属于 CCPE?
它应该放在哪里?
它依赖哪些外部能力?
它是否需要 Agent / Skill / Runtime / Model Card?
它的权限、状态、评估、调用真实性和生命周期是什么?
它不应该变成:
所有项目 runbook 的大杂烩
所有 automation scripts 的源码仓库
所有旧 Prompt 的强行 Agent 化工厂
所有任务默认 Full Runtime 的流程怪物
重构后的 CCPE 应该更像一个清晰的“智核架构工坊”: 负责分类、建模、登记、审计、迁移和维护; 不吞并项目、不吞并工具源码、不替代上层方法论。