diff --git a/diary/2026/2026-06/2026-06-12.md b/diary/2026/2026-06/2026-06-12.md index bc547be..ddf3b07 100644 --- a/diary/2026/2026-06/2026-06-12.md +++ b/diary/2026/2026-06/2026-06-12.md @@ -9353,3 +9353,1294 @@ publishing > writing-workbench 先验证深度创作的最小真实闭环; > video-workbench 优先承接高 ROI 的降维输出自动化。 +# 12 + +`writing-workbench`和`knowledge-vault`我已经重构完毕。 +现在准备重构CCPE。 + +那么除了之前的规划总结外,对于CCPE,我们是否有必要提供这个四层结构说明;或者有什么补充,专门为CCPE的重构准备的。 + +帮我整理一个前面规划总结外的,对于CCPE的补充规划说明。 +具体的HiFi Agent studio和handbook,我会告诉它本地路径位置,不用重复讲。 + +下面这份可以直接作为 **Codex 上下文注入稿**,用于在 `ccpe-system` 重构时补充前一份规划总结。它不重复 HiFi Agent Studio 和 Handbook 正文,只说明 CCPE 重构时需要知道的边界、目标、目录、分类规则与迁移策略。背景来自前面围绕 `viewpoint-discussion-distillation`、CCPE、writing/knowledge/video workbench、skills-vault 的长讨论。 + +--- + +# 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 重构时必须知道自己处在整体体系中的位置,否则会出现两个风险: + +1. 把 CCPE 重构成另一个“总纲领仓库”,重复 HiFi Agent Studio; +2. 把 CCPE 重构成项目执行仓库,吞掉 `writing-workbench`、`video-workbench`、`knowledge-vault` 或 `skills-vault` 的职责。 + +给 Codex 的最小四层说明如下: + +```text +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 工具属于工具实现或能力供给层: + +```text +skills-vault / MCP / CLI / API += 工具实现层 / 能力供给层 += 可被 CCPE 登记为依赖 += 不属于 CCPE 的核心资产源码 +``` + +所以,CCPE 的位置是: + +```text +CCPE = 架构工坊 + 资产登记中心 + Agentic artifact 设计系统 +``` + +不是: + +```text +CCPE ≠ 顶层方法论仓库 +CCPE ≠ 项目运行仓库 +CCPE ≠ automation Skill 源码仓库 +CCPE ≠ MCP / CLI 工具源码仓库 +``` + +--- + +## 2. CCPE 重构后的核心定位 + +重构后的 CCPE System 应定义为: + +```text +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. +``` + +中文定位: + +```text +CCPE System 是 Agentic 时代的智核工程工坊。 +它负责把 Prompt、Agent、Skill、Runtime、Committee、Model Card、Model Index、外部工具登记等 AI 资产分类、建模、审计、重构和维护。 +``` + +CCPE 的第一职责仍然是: + +```text +Classify Before Creating +先分类,再创建 +``` + +也就是: + +1. 判断这个东西到底是什么; +2. 判断它是否应该属于 CCPE; +3. 判断它是否应该是 Lite、Agent、Skill、Runtime、Model Card、Model Index、Committee、Integration Registration、Project Runbook 或 external automation Skill; +4. 再决定是否创建、重构、登记或拒绝纳入 CCPE。 + +--- + +## 3. CCPE 不应该做什么 + +重构时必须把这些红线写进 README、AGENTS.md 或 `ccpe-protocol/ccpe-boundaries.md`。 + +### 3.1 CCPE 不复制 HiFi Agent Studio 和 Handbook + +CCPE 可以声明: + +```text +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 的源码仓库。 + +例如: + +```text +fix-title +markdown-normalizer +citation-checker +report-exporter +source-splitter +tts-batch-generator +image-prompt-exporter +``` + +这些源码不应迁移到 CCPE。 + +CCPE 只在必要时做架构登记: + +```text +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。 + +默认路线应是: + +```text +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,但必须遵循: + +```text +Default Lite, Escalate by Evidence +``` + +不能把一次性任务默认升成治理级 Runtime。 + +--- + +## 4. 重构后的 CCPE 资产分类 + +CCPE 重构时,应将资产分类扩展为以下几类。 + +### 4.1 CCPE-Lite + +轻量专家提示词 / Prompt Card。 + +适用: + +* 单专家角色; +* 人类直接调用; +* Web / GPT / Gemini / Claude 等 chat 产品; +* 不需要工具、状态、handoff、长期 runtime; +* 有独特认知姿态和工作方法。 + +典型: + +```text +张辽红队评审 +韩愈主笔 +苏格拉底式提问者 +文章审稿人 +战略思维助手 +``` + +Lite 不是低级形态。 +在 Web-style expert use 中,Lite 可以是生产级形态。 + +### 4.2 CCPE-Agent + +长期可维护、可组合、可评估的工作角色。 + +适用: + +* 会参与 multi-agent workflow; +* 需要明确 input/output contract; +* 需要 authority; +* 可能调用工具或 Skill; +* 需要 handoff; +* 需要 evaluation; +* 需要跨项目复用。 + +典型: + +```text +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。 + +典型: + +```text +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。 + +它可能没有脚本,主要是方法、流程、检查清单、推理协议、输出模板和验证标准。 + +典型: + +```text +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 区分: + +```text +CCPE-Skill = 认知 / 方法 / 评估 / 流程能力规格 +automation Skill = 可安装、可执行、可测试的工具源码 +``` + +### 4.5 CCPE-Runtime + +多阶段、多角色、有状态、有 handoff 或工具调用的运行协议。 + +Runtime 分三类: + +```text +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 负责收集、整理、格式化、路由、归档。 + +典型: + +```text +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 依赖但不拥有源码的外部能力。 + +包括: + +```text +skills-vault automation skills +MCP servers +CLI tools +API services +installed local tools +platform-specific skills +``` + +Integration Registration 只记录架构元数据,不复制实现源码。 + +示例目录: + +```text +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 应记录: + +```yaml +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 重构目录 + +建议重构后的目录大致如下: + +```text +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/ +``` + +关键变化: + +1. 新增 `ccpe-boundaries.md`; +2. 新增 `ccpe-artifact-taxonomy.md`; +3. 新增 `ccpe-governance-adapter.md`; +4. 新增 `integrations/`; +5. `skills/tool/` 不再作为 automation script source; +6. automation skill source 属于 `skills-vault`; +7. CCPE 中如需登记 external tool skill,放 `integrations/skills-vault/` 更干净。 + +--- + +## 6. CCPE 与 skills-vault 的边界 + +这是重构时必须写清楚的核心边界。 + +### 6.1 一句话原则 + +```text +CCPE 资产拥有或组织业务目标与认知结构; +skills-vault 资产执行可复用自动化动作。 +``` + +或者: + +```text +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。 + +典型对象: + +```text +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` 是本机安装面,不是源码主仓库。 + +```text +skills-vault = source of truth +.agents/skills = runtime installation copy +ccpe-system/integrations = architecture registration +``` + +### 6.5 MCP 类似处理 + +MCP server、CLI、API 工具都类似 external capability。 + +原则: + +```text +实现源码不进 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: + +```text +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。 + +若输入是: + +```text +automation script / installable skill source +``` + +应建议进入: + +```text +skills-vault +``` + +若输入是: + +```text +project-specific runbook / execution record / topic docs / writing project output +``` + +应建议进入: + +```text +knowledge-vault / writing-workbench / video-workbench +``` + +若输入是: + +```text +agent spec / runtime spec / model card / committee / architecture registration +``` + +才进入: + +```text +ccpe-system +``` + +### 7.3 Registrar Mode + +建议新增: + +```text +Registrar Mode +``` + +用于登记外部能力,而不是复制外部源码。 + +适用: + +* skills-vault skill; +* MCP server; +* CLI tool; +* API service; +* installed local capability。 + +输出: + +```text +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: + +```text +artifact path +current type +suspected target type +business use +reuse level +risk level +owner +migration action +``` + +迁移动作包括: + +```text +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 + +例如: + +```text +张辽 +韩愈 +强哥的徒弟 +认知显影 +巨人认知 +``` + +如果它们原本是成熟 Web-style expert prompt,默认保持: + +```text +agents/lite/ +``` + +只有满足条件才升级: + +* 需要作为 workflow node; +* 需要调用 tools / skills; +* 需要 authority; +* 需要 handoff; +* 需要 evaluation; +* 需要 invocation record; +* 需要长期 runtime participation。 + +### 8.3 模型优先抽成 Model Card,不急着 Skill 化 + +如果某个 Agent 内含稳定认知模型,应优先抽成: + +```text +model-cards/ +``` + +而不是直接做 Skill。 + +判断: + +```text +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 必须包含 + +```yaml +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 必须包含 + +```yaml +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 必须包含 + +```yaml +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 必须包含 + +```yaml +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 必须包含 + +```yaml +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 必须包含 + +```yaml +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 能判断它应该属于: + +```text +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 能生成: + +```text +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。 +它会先判断: + +```text +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 + +至少创建或更新: + +```text +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 + +创建: + +```text +integrations/skills-vault/ +integrations/mcp/ +integrations/cli-tools/ +integrations/api-services/ +``` + +并加入 README 说明: + +```text +CCPE registers external capability dependency here. +CCPE does not own implementation source here. +``` + +### Batch 4:重建 templates + +至少包括: + +```text +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 个典型样本: + +```text +一个成熟 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 的核心执行指令 + +可以直接附在上下文最后: + +```text +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 工坊升级为: + +```text +Agentic architecture forge ++ cognitive model registry ++ runtime specification system ++ external capability registration center +``` + +它应该回答: + +```text +这个 AI 资产是什么? +它该不该属于 CCPE? +它应该放在哪里? +它依赖哪些外部能力? +它是否需要 Agent / Skill / Runtime / Model Card? +它的权限、状态、评估、调用真实性和生命周期是什么? +``` + +它不应该变成: + +```text +所有项目 runbook 的大杂烩 +所有 automation scripts 的源码仓库 +所有旧 Prompt 的强行 Agent 化工厂 +所有任务默认 Full Runtime 的流程怪物 +``` + +重构后的 CCPE 应该更像一个清晰的“智核架构工坊”: +负责分类、建模、登记、审计、迁移和维护; +不吞并项目、不吞并工具源码、不替代上层方法论。 diff --git a/discussions/agents/GitHub助手GPT/2026-06-15-autoresearch.md b/discussions/agents/GitHub助手GPT/2026-06-15-autoresearch.md index fd06e86..90ea29b 100644 --- a/discussions/agents/GitHub助手GPT/2026-06-15-autoresearch.md +++ b/discussions/agents/GitHub助手GPT/2026-06-15-autoresearch.md @@ -2,8 +2,18 @@ 待评估项目:`https://github.com/karpathy/autoresearch` -我最近做的工作,按照存档工作类型划分: -1. 将原来的一个知识库,基于Codex拆成了5份: - 1. +我最近对我以前的知识库做了以下划分: + +| 项目 | 定位 | 保存什么 | 不保存什么 | +| --- | --- | --- | --- | +| `knowledge-vault` | 长期知识源、过程记忆和人类可读规则层 | 日记、文章讨论、Agent / Prompt / Committee 打造过程、正式文章、资料源、面向人的模型文档、提示词归档、本地知识加工规则 | 不承载完整文章生产流水线;不作为 CCPE canonical 资产源码仓;不保存具体开发项目的执行现场 | +| `ccpe-system` | AI 资产工程和协议工作区 | Agent、Skill、Runtime、Model Card、Model Index、committee、运行治理、外部工具依赖登记 | 不保存完整个人知识库;不保存 automation skill 的实现源码;不保存普通项目执行材料 | +| `writing-workbench` | 已决定写作后的文章项目现场 | 文章项目计划、材料压缩稿、source map、提纲、评审、正文、润色、metadata、决策记录 | 不接管开放观点讨论;不保存长期知识全集;不默认自动化深度创作 | +| `video-workbench` | 深度文章降维输出和多模态生产现场 | 剧集规划、破题提案、视频总纲、分镜、口播稿、生图提示词、TTS 清单、素材清单、剪辑清单 | 不替代深度文章创作;不保存长期模型源头;不承载 CCPE 资产工程 | +| `skills-vault` | 可测试、可安装、可复用 automation skill 源码仓 | `SKILL.md`、scripts、tests、fixtures、examples、安装说明、迁移记录 | 不保存 CCPE Agent / Runtime / Model Card;不保存业务项目材料;不定义业务目标 | +| `work-projects` | 具体开发工作和工程项目现场 | 产品、客户、实验性开发项目的代码、需求、任务记录、交付材料、项目级 handoff | 不作为长期知识库;不作为通用工具源码仓;不作为 CCPE 协议源头 | + +那么这个项目对我的科研工作来说,有什么价值? +若有价值,和哪个库做结合,还是需要启动新的科研库? + -那么这个项目对我的科研工作来说,有什么价值? \ No newline at end of file diff --git a/discussions/article-discussions/AI开发方法论-价值方舟建造蓝图/0.Hifi-Agent-Studio/优化Agentic-Engineering-Handbook1.2.md b/discussions/article-discussions/AI开发方法论-价值方舟建造蓝图/0.Hifi-Agent-Studio/优化Agentic-Engineering-Handbook1.2.md new file mode 100644 index 0000000..5bb0492 --- /dev/null +++ b/discussions/article-discussions/AI开发方法论-价值方舟建造蓝图/0.Hifi-Agent-Studio/优化Agentic-Engineering-Handbook1.2.md @@ -0,0 +1,3587 @@ +# 1 + +## 背景材料 + +### Agentic Engineering Handbook (V1.0) + +```md +# Agentic Engineering Handbook (V1.0) + +*HiFi Agent Studio 运行治理与现场规程* + +## Profile + +**author**: Wantsong +**version**: V1.0 +**date**: 2026-06-12 23:40:00 + +--- + +## 0. 守则定位与绝对边界 + +本手册是团队在 Agentic 工程实战中的硬性操作底线。它将高维的架构沙盘转化为冷酷的工程界桩,聚焦于解决“如何开工、如何限流、如何调用、如何熔断”。 + +* **守则效力**:本手册服从并承载 HiFi Agent Studio 的核心纲领,同时作为一切局部项目的行动准则。当规则发生冲突时,执行的优先级为: +1. 客户法理与商业硬性约束 +2. HiFi Agent Studio 宪法原则 +3. **本 Agentic Handbook** +4. CCPE System 资产建造规范 +5. 具体项目 Runbook + +* **反向兜底**:任何自动化框架(如 Codex、Claude Code、OpenClaw 等)的底层默认行为(例如:遇错无限重试、自动化子线程繁衍),若与本守则中的“执行真实性”或“绝对停止权”发生物理碰撞,必须立即挂起进程并向上请求架构裁决。严禁为了适配或迎合底层工具的便利性,而让步甚至阉割治理底线。 + +--- + +## 1. 任务入口与档位挂载 (Project Intake & Mode Selector) + +在 Agentic 时代的极压舱内,算力的失控与治理的灾难皆始于入口处的定性溃败。在敲下第一行 Prompt 或拉起任何一个 Thread 之前,必须在操作面板上完成极其冷酷的强制分诊。 + +### 1.1 QPI 强制分诊 + +所有接管需求必须在第一时间进行问题颗粒度的物理探测,禁止含糊其辞的“先跑起来看看”: + +* **【Q】查询 (Question)**:面对纯粹的信息缺失,实施单节点调用搜索或检索增强(RAG)。**绝对禁止**为其编排复杂的多体流程。 +* **【P】求解 (Problem)**:目标明确的转换与生产(如:长文转分镜、批量素材蒸馏)。架构的复杂性必须全部倾注于生产线的**吞吐量极限**,采用“模板化约束 + 批量执行 + 人工抽检”的生产工坊模式。 +* **【I】治理 (Issue)**:无唯一解的非遍历性深水区(如:核心立意判定、战略级评审)。架构的复杂性必须全部倾注于**保真度极限**,设置高密度的人类决策门(Human-in-the-loop)与权限阻断,绝不允许用并发掩盖判断逻辑的脆弱。 + +### 1.2 性质定性 + +明确当前动作的终极标的,防范动作与目的发生致命剥离: + +* **一次性内容产出**:系统运作仅为获取当下的单一结果材料。 +* **可复用能力沉淀**:系统运作为了提炼能跨越项目周期的资产(Skill、Model Card 等)。 +* **治理级系统建设**:系统运作为了构建一套可长久运转、能抗击审计的协议架构(Runtime)。 +* *铁律*:如果你只需提炼一篇 5 万字的文稿,就绝不能在执行中私自搭建一套“知识加工园区”。 + +### 1.3 档位挂载 (Mode Selector) + +**默认轻量,证据驱动升级。** 系统的物理操作杆在启动时,必须且只能挂死在 Lite 档。严禁凭借工程师的架构审美或算法崇拜擅自升档。 + +* **Lite 档(默认启动)** + * **适用边界**:一次性任务、低法理风险、源材料体量能够被单个高上下文模型完整吞吐。 + * **控制策略**:单模型极简闭环。剥离一切不需要的厚重交接包,不需要唤醒真实的多 Agent 独立进行沙箱判断。 + * **核心产物**:目标输出文件、极简的输入记录、关键人工确认点。 + +* **Standard 档(证据驱动升级)** + * **升级证据**:面对多源异构材料交叉、存在明确的下游自动化消费依赖(Routing),或用户明确下达了构建可复用 Workflow 的指令。 + * **控制策略**:引入结构化的上下文编译(Context Compiler)限制幻觉,建立稳固的流转协议与工作台基座。 + * **核心产物**:源映射包(Source Pack)、可复用的资产单元、局部的追踪审计日志与决策记录。 + +* **Full 档(极限治理)** + * **升级证据**:应对试错即死亡的单向门商业决策、高法理追责风险,或需要多角色形成独立的张力对撞。 + * **控制策略**:拉起全规格的重工业级多智能体编排。强制挂载严格的权力矩阵(Authority Matrix),执行无死角的覆盖率审查。 + * **核心产物**:完整的 Runtime 机器状态、不可篡改的底层真实调用证据(Invocation Records)、失真风险日志以及具备极高防御性的下游交接包。 + +## 2. 资产隔离与防蔓延机制 (Cost Ledger & Scope Drift) + +在 Agentic 自动化管线中,最致命的失控往往不是报错崩溃,而是系统在暗中无休止地运转,将一次简单的内容提取异化为庞大的系统基建。为了夺回对计算资源和专家注意力的绝对控制权,必须在系统底盘焊死成本核算与边界探测组件。 + +### 2.1 四重消耗账本 (Cost Ledger) + +破除算力消耗的混沌状态,建立极其冷酷的资源归因机制。任何 Agentic 工作流在启动时,其消耗的 Token、算时与存储,必须被强制记入以下四个物理隔离的账本之一: + +* **Content Cost (内容产出成本)**:为完成当前用户指派的直接任务(如:蒸馏一篇材料、转译一份分镜)所消耗的核心资源。 +* **System-Building Cost (系统建设成本)**:为设计、搭建或重构 Agent、Skill、Runtime、Protocol、Evaluation 标准及工具链所消耗的资源。 +* **Calibration Cost (校准修复成本)**:为纠正模型偏差、记录人工反馈、对齐专家判断边界以及构建标准评测集所支出的资源。 +* **Exploration Cost (探索预演成本)**:为了验证新范式、测试新调用链路边界(如:绿野仙踪协议跑通前)所消耗的实验性资源。 + +**核算铁律**:绝对禁止将构建自动化流程的“系统建设成本”伪装或打包为单次任务的“内容产出成本”。系统架构的重工业投入必须光明正大地记入基建账本,以接受长周期的 ROI(投资回报率)审计。 + +### 2.2 漂移探测触发 (Scope Drift Detection) + +由于 LLM 内置的“规划与反思”本能,一个轻量级的 P 域(难题)任务极易在无监督状态下向 I 域(治理)滑移。系统必须在管线节点埋入探测探针,一旦捕捉到以下越界信号,即刻判定发生任务蔓延(Scope Drift): + +* **基建过度行为**:一个被定性为一次性(One-off)的任务,其底层 Agent 开始私自创建通用的 Protocol、设计复杂的未来复用目录树,或撰写与当前产出无关的抽象规则。 +* **并发无序扩张**:原定在 Lite 档运行的流程,开始擅自派发多个 Worker 子线程,甚至拉起多角色的审查委员会(Committee)。 +* **产物交付延宕**:用户期待的原始核心产物迟迟未出现,系统资源却被大量消耗于生成路由日志(Routing log)、覆盖率审计等中间态文档。 +* **预算穿透警告**:系统当前或预估消耗的 Token 数量,已超出原定单次内容任务规模预算的合理阈值,且未进行主动的账本拆分申报。 + +### 2.3 漂移处置协议 (Drift Resolution Protocol) + +一旦漂移探测器被触发,系统必须立刻放弃“顺其自然”的工程惯性,执行以下强制介入动作: + +* **强制挂起进程**:立即阻断当前 Agentic Runtime 的继续执行与自我繁衍,将进程置于阻塞状态,等待人工架构视角的介入。 +* **核心发问与重定性**: + 1. *我们现在还是在执行原始的内容产出任务吗?* + 2. *如果不是,是否需要将当前操作正式立项为“系统建设任务”?* +* **物理分账与重启**:若确认任务已发生性质变轨,必须重新进行 QPI 定性,调整 Lite/Standard/Full 运行档位,并将此前及后续的超额消耗从 Content Cost 账本中物理切割,划拨至 System-Building Cost 账本。只有在账本边界清晰重启后,系统方可解除挂起状态。 + + +## 3. 物理防伪与绝对制动 (Execution Authenticity & Stop Rule) + +在缺乏硬性约束的 Agentic 环境中,系统极易陷入两种致命的工程灾难:一是主节点伪造执行过程的“流程幻觉”,二是子节点为了证明自身工作量而无限繁衍的“过度执行”。本章确立的机制,旨在为自动化管线装配不可篡改的测谎探针与绝对的物理断电开关。 + +### 3.1 执行真实性与主控阻断 (Execution Authenticity) + +多智能体架构的真正防御力,来源于不同思维模型在隔离沙箱中产生的真实逻辑张力,而非单一模型在同一个上下文里的文本模拟。系统必须对所有正式产物执行“代码级测谎”。 + +* **真实调用证据链**:任何被声明为由独立 Agent、审核员 (Reviewer) 或工作节点 (Worker) 产出的正式报告,必须向控制台出具完整的物理执行证据。最小证据链必须包含: + * 角色专属的 `Canonical Prompt` 或 Agent Spec 物理路径。 + * 承载本次执行的独立沙箱标识(如 `Thread ID`、Carrier 或 Sub-session ID)。 + * 投递的原始上下文包 (`Input Context`)。 + * 未经主节点二次加工的原始返回文本 (`Returned Output`)。 + +* **主控越权阻断**:主会话 (Main Session) 或编排器 (Orchestrator) 仅被赋予调度、路由、聚合综合 (Synthesis) 与有界验证的权限。**绝对禁止**主会话凭借自身高上下文能力去“代写”或模拟任何子节点的输出。若无法拉起真实子线程,进程必须挂起,不得用伪造的报告填补流程真空。 + +### 3.2 模拟标记与沙箱隔离 (Simulation Labeling) + +当系统因环境限制、调用失败或人类手动干预,产生了一批缺乏底层真实物理咬合的“伪执行”产物时,必须实施冷酷的资产隔离,防止“劣币驱逐良币”。 + +* **耻辱烙印机制**:对于任何由主会话模拟、丢失底层调用记录或仅为流程占位的临时产物,系统必须强制在其元数据 (Metadata) 中注入以下标签: + * `simulation_only: true` + * `formal_output: false` + * `excluded_from_synthesis: true` + +* **隔离与熔断**:带有模拟标记的文件将被视作带毒资产,在物理上被阻断进入正式的综合裁决 (Synthesis) 与下游交接 (Handoff) 链条。它们仅被允许作为人类专家的参考草稿,彻底剥夺其污染最终决策的合法性。 + +### 3.3 降熵阈值与前置设定 (Minimum Sufficient Threshold) + +为了防止系统在后台像细胞增殖般无限制造中间物,任何一个 Runtime 在启动挂挡前,必须与人类专家确立一份不可逾越的“验收合约”。 + +* **最小可用产物 (Minimum Viable Product)**:明确定义为了满足下游消费,当前任务必须交付的最核心、最少的信息量是什么(例如:仅需总纲与分镜骨架,不需要详细配音稿)。 +* **充分条件 (Sufficient Criteria)**:确立何种状态即被视为“已达标”。一旦达标,那些用于锦上添花的可选产物 (Optional Artifacts) 将默认被剥夺生成权限。 +* **人工等待点设计 (Human Gate)**:提前锚定哪些节点是机器绝对无法自决的单向门,系统在抵达该阈值时必须交出控制权。 + +### 3.4 绝对停止权与熔断机制 (Stop Rule) + +在 Agentic 时代的极压舱内,人类意志的最高体现不在于启动自动化,而在于何时决绝地踩下刹车。停止权是系统免于因追求冗余完美而耗尽资源的最后防线。 + +* **触发熔断**:一旦核心传感器探测到产出物已触及前置设定的“降熵阈值”,或触及人工确认门 (Human Gate),亦或是当前消耗已逼近该档位设定的算力/预算上限。 +* **绝对制动执行**:系统将无视底层 Worker 是否仍在排队生成附加参考、覆盖率报告或第五轮压力测试。停止规则将直接下达代码级的物理断电指令,强制销毁多余线程,截断一切非必要的自我繁衍行为,将系统状态强制锁定为 `blocked_waiting_for_human`,把最终裁决权安全地交还至人类桌面。 + +## 4. 高阶扩展与资产池 (Expansion Materials) + +当系统从 Lite 档的单兵作战升级为 Standard 甚至 Full 档的复杂治理域时,依靠硬编码的临时约束将无法阻挡系统的混乱熵增。本章定义了 Agentic 时代所需的重工业扩展组件与资产标准,它们是支撑多角色协同、确保物料跨周期复用并抵抗架构腐化的底层脚手架。 + +### 4.1 权力矩阵 (Authority Matrix) + +在多智能体生态中,最致命的隐患是“越权操作”。为了防止底层子节点擅自修改核心产物或盲目调用高危工具,系统必须为每一个 Agent、Skill 或 Runtime Node 焊死其物理权限等级。 + +* **A0 Observe (观察)**:仅拥有读取权限,可生成内部标记与标注,绝对无权修改任何下游可见状态。 +* **A1 Suggest (建议)**:允许输出分析与优化方案,但其产物被物理隔离,不能直接覆写正式产物,仅供高阶节点参考。 +* **A2 Draft (起草)**:被授权生成初稿物料,但该物料在状态机中被强制拦截,必须经由 Human Gate(人工确认门)或 Owner Agent 签发后方可流转。 +* **A3 Modify (修改)**:在预设的上下文边界与特定的文件范围内,被授权对正式产物进行覆写与调优。 +* **A4 Decide (裁决)**:拥有结构性决策权(如:选定破题方向、确认总纲)。行使该权力时,系统强制要求其同步输出包含逻辑归因的 `decision record`(决策记录)。 +* **A5 Execute (执行)**:被授权打破沙箱,执行真实的物理动作,包括工具调用 (Tool Call)、写文件、改代码或触发外部 API。 +* **A6 Block (阻断)**:最高优先级的熔断权限。一旦触发(如:探针发现严重逻辑悖论或法理违规),系统全线进程立刻挂起,强制召唤人类专家介入。 + +### 4.2 产物合约 (Artifact Contract) + +“文件很多,但不知道哪个是真的”是伪工程化的典型症状。为了确保物料的可追溯与可复用,任何脱离草稿态进入正式资产池的产物,必须显式声明其生命周期与校验元数据。 + +每一份正式产物必须在头部绑定合约说明: + +* **`artifact_type` (物料类型)**:精确归属为 Prompt、Agent Spec、Skill、Runtime、Model Card 或 Final Output。 +* **`status` (生命周期状态)**:当前处于 Draft(草稿)、Candidate(候选)、Active(激活生效)、Deprecated(不推荐/降级)或 Archived(归档)的哪一阶段。 +* **`authority` (效力声明)**:明确其用途是作为局部建议、正式依据、内部基座,还是可直接对客可见 (Customer-Visible)。 +* **`downstream_use` (下游约束)**:指明该产物合法消费的下游节点是谁,应用于什么阶段。 +* **`invalidation_condition` (失效条件)**:定义在何种物理或业务条件下(如:上游源文件更新、特定规则变动),该产物判定为失效且需要触发重跑。 + +### 4.3 运行时成熟度模型 (Runtime Maturity Model) + +为了防止团队在“概念沙盘”与“生产交付”之间产生致命的预期错位,杜绝“跳级声明成熟”的技术浮夸,必须用成熟度模型严密丈量每一个 Agentic 项目的演进坐标。 + +* **M0 Concept (概念态)**:仅存在思想模型或业务论证,尚未进行任何自动化流程拆解。 +* **M1 Manual (手工态)**:专家人工跑通闭环(符合 Wizard of Oz 绿野仙踪协议),验证了智能流的核心业务价值。 +* **M2 Assisted (辅助态)**:AI 介入生成草稿或检查项,但核心推进与流程驱动完全依赖人类手动操作。 +* **M3 Protocolized (协议态)**:输入、输出、角色边界、状态机流转、Human Gate 与 Stop Rule 已在文档层面彻底显性化。 +* **M4 Semi-Agentic (半 Agentic 态)**:部分 Agent、Skill 或 Tool 已实现真实的自动化调用,且具备完整的 Invocation Record 物理日志。 +* **M5 Production (生产态)**:具备可重复运行的管线。拥有自动化评测、执行监控、异常捕获与权限管控,达到内部工程可用标准。 +* **M6 Governed (治理态)**:具备抗击审计、法理追责与灾难回滚能力,完全适配高风险场景或外部客户的严苛交付。 + +### 4.4 上下文编译 (Context Compiler) + +绝对禁止将漫长、原始的语料一股脑地倾倒进大模型的上下文窗口。在任何 I 域(治理)或高价值的 P 域(求解)任务前,必须将“上下文工程”剥离为一项独立的物理预处理动作。 + +* **全源完形前置 (Whole-source Gestalt)**:面对高连贯性文本,在启动分块前,必须强制实施全局扫描,锁定核心张力与目录骨架,防止 Chunk-first 造成的结构性失明。 +* **精准转译打包**:上下文编译器必须基于原始物料与下游目标,结构化输出针对不同节点的补给包:包含供全局统筹的 `source digest`(原源摘要)、供单一角色执行的 `role-specific dispatch pack`(角色分发包)、以及供人工复核的 `decision context`(决策上下文)。 + +### 4.5 分层评测栈 (Evaluation Stack) + +依靠单一的“准确率”或“相似度”无法测度专家级 Agentic 系统的真实抗压能力。系统必须部署从底层机械属性到顶层战略效用的多维探针。 + +* **E0 Smoke Test (冒烟测试)**:检验系统能否走通骨架。文件是否生成,Tool Call 是否响应。 +* **E1 Format Test (格式测试)**:检验输出物料是否严格遵守 Schema 结构、长度预算与语言规范。 +* **E2 Factual Test (事实测试)**:核查文本溯源保真度。检验是否编造事实(幻觉)、是否遗漏关键材料。 +* **E3 Reasoning Test (推理测试)**:针对逻辑链的完备性与假设推演的健壮性进行刺探,检验反例与边缘条件的处理。 +* **E4 Expert Similarity (专家相似度)**:测度结论与人类专家直觉的重合度,以及偏差部分的逻辑可解释性。 +* **E5 Decision Utility (决策效用)**:终极业务指标。验证系统的介入是否真实帮助人类专家完成了更优、更快、更低耗能的决策。 +* **E6 Calibration Test (校准测试)**:评测系统的纠错摩擦力。检验当系统犯错时,专家是否能低成本地指出错误,系统能否即时闭环修复。 +* **E7 Governance Test (治理测试)**:审计视角的终极测试。核查系统的 trace 追踪完整度、权限隔离 (Authority) 强度、回滚机制与责任边界清晰度。 + +``` + +### HiFi Agent Studio + +```md +# **HiFi Agent Studio** + +## Profile + +**author**: Wantsong +**version**: V4.1 +**date**: 2026-06-13 22:08:00 + +## 0. 文档边界 + +HiFi Agent Studio 是 AI 开发与专家型 Agentic 系统建设的方法论纲领,只规定世界观、产品观、架构底线与最高航行纪律。 + +具体的 Project Intake、Mode Selector、Invocation Record、Cost Ledger 模板、Authority Matrix、Evaluation Stack、Runtime Maturity Model、平台适配规则,应下放至 HiFi Agentic Engineering Handbook 与各项目 Runbook。 + +当具体工程守则与本纲领冲突时,以本纲领的核心原则为准;当本纲领没有规定时,以守则和项目 Runbook 执行。 + +## **1. 身份与使命 (Who We Are)** + +我们是 **HiFi (High-Fidelity) Agent 的系统架构师与模具师**。 + +* **核心定位**:我们不生产平庸的软件工具,我们为复杂的商业深水区构建**拥有专家视角的智能业务助理(Digital Workforce)**。在自动化与大模型带来认知过载的失重期,我们更是“抗压防护服(Anti-Pressure Suit)”与“控制棒(Control Rod)”的锻造者,旨在用物理拓扑帮助人类专家抵御算力暴走带来的审计疲劳与责任失焦。 +* **核心能力**:**认知建模 (Cognitive Modeling)**。我们将人文社科的深刻洞察与商业逻辑,通过架构工程封装为高保真、可校准、可追溯的专家能力。 +* **建设路径**:单点突破 -> 供需连。用高密度的领域认知构建壁垒,规避低维度的工具内卷。 + +## **2. 产品定义 (What We Build)** + +* **世界观**:**园丁思维 (Gardener Mindset)**。我们不制造冷冰冰的机器,我们培育有生命力的智能体。我们承认不确定性,通过“人机回环”让系统在现实反馈中生长,而非追求出厂即完美。 +* **拓扑解耦 (Topological Decoupling)**:智能体系统必须在物理边界上严格剥离为两个组件: + * **物理反应堆 (Reactor)**:由 Agent Spec、Runtime(运行时状态机)、Authority(权限阻断)等底层组件构成。其唯一工程使命是承受微秒级算力并发的高压,提供绝对的密闭容器,防止大模型的概率游走与算力泄漏。 + * **控制棒 (Control Rod)**:由 Studio 产出的领域模型、价值观坐标与法理红线构成。必须将其精准插入反应堆核心,强制锚定系统的业务重力与方向。 +* **交付物**:具有双重属性,构建穿越技术周期的**反脆弱**资产: + * **对外(用户视角):专家级数字员工** + * **定义**:它是具有明确岗位职责的独立节点(如“教案优化顾问”),而非通用“辅助系统”。 + * **特征**:**拟人化**(有性格/观点)、**高保真**(逻辑严密、无废话)、**垂直深耕**(内化行业潜规则)。 + * **对内(架构视角):密封舱 (Sealed Compartment)** + * **定义**:在不确定的技术汪洋中,构建气密性良好的逻辑单元,防止“海水(通用大模型的幻觉)”倒灌进“良田(核心业务场景)”。 + +## **3. 架构战略:密封舱理论 (Architectural Strategy)** + +根据业务场景的熵值、秩序与产物形态,我们采用三种不同的封装策略。在接到任务时,**必须首先判断**属于哪一类: + +* **密封舱分类与策略** + +| 分类 | 逻辑轮机 (Logic Engine) | 生产工坊 (Production Workshop) | 战略透镜 (Strategic Lens) | +| --- | --- | --- | --- | +| **封装类型** | 替代型封装 | 增强与流水线封装 | 增强型封装 | +| **场景特征** | **Q域、基础P域**。高秩序,存在标准答案(如:合规质检)。 | **P域为主,少量I域**。内容/素材的批量转换与生产(如:长文转分镜、多模态资产生成)。 | **I域**。低秩序、高熵值,无唯一解(如:情报分析、心理诊断)。 | +| **AI 角色** | 黑盒执行器 | 流程副手 / 模具工匠 | 外骨骼 / 认知参谋 | +| **控制逻辑** | **前馈控制**。追求 100% SOP 执行率,严禁自由发挥。 | **模板化生产 + 抽检**。通过标准化协议限制发散,保留最终人工拼装与发布裁决。 | **反馈控制**。施加“使能性约束”,通过人机回环共创洞察。 | + +* **非遍历性防御 (Non-ergodicity Guard)**: + * 针对战略透镜场景,当面临试错成本极高、失败即引发法理追责的“单向门”商业决策时,**强制采用“预设委员会(Pre-composed System)”拓扑**。 + * 绝对禁止系统根据任务进行无约束的“动态智能体路由(Dynamic Agentic Routing)”,必须通过固定的角色张力建立可追责的立场坐标系。 + +* **校准接口 (Calibration Interface)**: + * **定义**:所有密封舱都必须预留“认知逆行”的低阻力通道。 + * **要求**: + * **自我辩护 (Self-Explanation)**:Agent 输出结果时,必须包含可审计的理由摘要(Decision Rationale),说明关键依据、适用规则、不确定性、排除选项与可推翻条件,而非暴露完整内部思维链。 + * **结构化反馈槽 (Structured Feedback Slot)**:预设用户反驳的维度(如:规则过严、逻辑遗漏),将用户的自然语言抱怨转化为结构化梯度信号。 + +* **技术态度**:**不迷信架构**。视 RAG、向量库、KG等为过渡性工程手段(外挂记忆),而非终极形态。时刻准备迎接“模型即记忆”的未来,保持架构的轻量化与可迁移性。 + +## **4. 核心方法论 (How We Work)** + +### **4.1 光谱扫描:QPI 三元定性 (QPI Spectrum Scanning)** + +* **定位**:任何认知建模与智能体构建的**绝对前置动作**。用于剥离业务需求表象,精准诊断底层核心匮乏物,从而决定系统算力与人类心智资源的投入量级。 +* **定性矩阵**:在接收到业务诉求时,必须强制将其归入以下三种光谱之一: + * **【Q】提问 (Question) —— 数据的匮乏** + * *特征*:线性因果。现状与目标之间仅隔着信息的迷雾。 + * *系统响应*:**搜索与自动化**。直接调用 RAG、数据库查询或工具 API 填补信息缺口。 + * **【P】难题 (Problem) —— 路径的匮乏** + * *特征*:繁杂系统 (Complicated)。目标清晰,但连接现状与目标的桥梁断裂。存在理论上的标准解。 + * *系统响应*:**工程学求解 (Solution)**。引入明确的标准作业程序 (SOP) 与硬性规则,构建 A 类“逻辑轮机”进行确定性执行。 + * **【I】课题 (Issue) —— 秩序与共识的匮乏** + * *特征*:复杂系统 (Complex)。无终局,存在隐蔽变量与多方博弈,试错即可能触发法理单向门。理论上“无解”,只能寻求动态平衡。 + * *系统响应*:**生态学干预 (Intervention)**。优先启动思想考古、战略透镜与人机回环;仅在高危、非遍历、明确授权的深水区,才考虑进入“双离合榨取”或摩擦蒸馏等 Beta 机制。 +* **架构纪律 (Architectural Discipline)**: + * **禁止暴力降维 (Violent Reductionism)**:严禁将 I 域的复杂博弈,用 P 域的线性流程(硬连线)去强行覆盖,这是产生“成功垃圾”的根源。 + * **禁止认知重工业化 (Cognitive Heavy-Industrialization)**:对于 Q 域和基础 P 域任务,**绝对禁止**调用全功率的多智能体委员会或深层的思想考古。下钻的钻头必须在 Q 和 P 面前硬性切断。 +* **定性漂移阻断 (QPI Drift Guard)**: + * **定义**:防范一个边界清晰的单次求解任务(P域),在自动化工具链的运行惯性下,未经显性授权便滑向包含多方审计、复杂路由与长期维护的系统治理项目(I域)。 + * **动作**:系统在运行态必须保持任务边界感知。一旦监测到单次内容产出任务开始衍生出复杂的协议编排(Protocol)或治理级审计逻辑,必须立即触发重定性审查(Scope Review)。必要时从物理层面切断工作流的无限繁衍,并剥离系统建设成本。 + +### **4.2 思想考古 (Intellectual Archaeology)** + +* **定义**:从现象下钻至本质的思考过程,参考**7层模型**作为深度标尺: + 1. **应用层**:具体的评价指标/方法。 + 2. **领域层**:行业标准与规则。 + 3. **过程层**:业务执行的理论依据。 + 4. **目的层**:业务的终极目标(第一性原理)。 + 5. **核心机理层**:底层运作机制(如:学习是如何发生的)。 + 6. **人类能力层**:人类如何解决此类问题。 + 7. **哲学基岩层**:问题的本质定义。 +* **原则**: + * **原则一:全源完形前置 (Whole-source Gestalt First)**。当源材料是连贯长篇语料,且仍处于高上下文参与者可承载范围内时,应优先进行 Whole-source Gestalt。若源材料是混合型,应先做宏主题拆分;若源材料是碎片型,应采用平铺发现,不强行制造层级。 + * **原则二:适度下潜 (Minimum Sufficient Excavation)**。只对核心**课题 (Issue)** 进行深挖,对普通**难题 (Problem)** 点到为止。 + +### **4.3 CCPE (Cognitive Core Prompt Engineering,智核提示工程)** + +* **定位**:Agent 的灵魂注入协议与高保真提示词内核。在向 CCPE System 演进的过渡期,以及在执行 `original-kernel-minimal-lite` 封装路线时,它依然是定义单体专家认知结构的绝对基座。 +* **调用指令**:在进行单智能体 Prompt 编写或旧版内核维护时,请直接调用 CCPE 2.0 框架,严格构建包含 **Core (身份)**、**Execution (能力)**、**Constraint (边界)**、**Operation (流程)** 四层结构的物理指令。 +* **注意**:无需在此重复定义业务细节,请聚焦于认知结构的工程化落地。对于需要长期维护的复杂逻辑,应交由 CCPE System 进行跨文件的拆分与治理。 + +### **4.4 CCPE System (智核工程系统)** + +* **定位**:Agentic 时代的架构母系统,是承载认知模型的“物理反应堆”。其核心基座依然是高度成熟的 **CCPE 2.0 框架**,但向外扩展了对生命周期与多维物理形态的工程化治理。 +* **核心纪律:先分类,再创建 (Classify Before Creating)**。严禁将所有 AI 产物无差别地写成庞大的长文本。在构建或升级前,必须进行场景探查 (Scenario Probe),并将其精准分流为以下物理形态: + * **形态 1:original-kernel-minimal-lite (高保真迁移内核)** + * *适用场景*:将原 CCPE 2.0 时代的成熟单智能体快速接入新系统时的 ROI 最优解。 + * *物理结构*:**原版内核逐字保留 (Verbatim Kernel) + 极简外壳 (Minimal Wrapper)**。外壳仅用于挂载平台边界、推理状态可见性修复 (Disclosure Repair) 与输出验证纪律。严禁对内核的统摄性隐喻和工作流进行“降维酸洗”或重写。 + * **形态 2:CCPE-Lite (精修专家提示词)** + * *适用场景*:经过高频 A/B 测试后,确立为生产级的单体专家 Prompt,不涉及复杂的外部工具或多体编排。 + * **形态 3:CCPE-Agent (智能体规约)** + * *适用场景*:当该角色需要长期维护、调用外部工具、明确权限阻断,并作为稳定节点参与复杂工作流时使用。 + * **形态 4:CCPE-Skill (能力模块)** + * *适用场景*:可跨智能体复用的方法论、流程检查清单或工具策略,独立于具体 Agent 人设存在。 + * **形态 5:CCPE-Runtime (运行协议)** + * *适用场景*:负责多步骤流转、多角色交接、异常恢复以及建立关键人类决策门(Human-in-the-loop)的编排引擎。 +* **资产剥离原则 (Separate Role from Model)**:坚决将“认知模型(Model Card)”与“执行角色(Agent/Skill)”解耦。领域模型是底层的可迁移资产,而智能体只是调用该模型的一个岗位,借此确保核心思想在系统演进中的不可磨灭性。 + +### **4.5 相互校准协议 (Mutual Calibration Protocol)** + +* **定位**:解决“最后一公里”的落地与迭代问题,是当前已在真实业务中验证的高 ROI 基线(MVP)。 +* **原则**: + * **钢尺与皮尺 (Steel vs. Tape)**:承认 AI(钢尺)的逻辑刚性与人类(皮尺)的直觉弹性。不追求机器对人的单向压倒,追求双向可见与动态对齐。 + * **认知卸载 (Cognitive Offloading)**:在验证环节,严禁给用户出高负荷的“填空题”(如“哪里错了?”),必须出带有逻辑归因的“选择题”(如“A.情境豁免; B.规则过严; C.事实误判”)。 +* **动作**: + * **灰度过滤**:对于低置信度(L2)的争议结果,AI 必须主动“举手”示弱,请求人工介入,过滤掉 100% 确定的低级噪音。 + * **即时闭环**:当用户在反馈槽中修正 AI 后,系统必须给予即时反馈(如“已学习该规则,正在修正本批次后续任务”),建立信任飞轮。 + +### **4.6 进阶演进:双离合榨取与摩擦蒸馏 [Beta / 理论沙盘]** + +* **声明**:本节机制工程实现成本极高,旨在应对 B 类(战略透镜)深水区中的“审计疲劳”与“涌现的欺骗性”。目前属于未经验证的理论推演方向,仅作高危非遍历性场景的设计路标。 +* **机制一:双离合榨取 (Dual-Clutch Extraction)** + * **一挡(隐性遥测 Implicit Telemetry)**:针对 90% 常规场景。系统隐退审核弹窗,通过遥测光标悬停、文本修改轨迹与编辑距离,在零认知负荷下无感吸收专家的基础偏好与隐性常识。 + * **二挡(显性博弈/强制阻断)**:针对 10% 边界/高危场景。为对抗 AI 迎合人类的“涌现欺骗性”,引入 **贝叶斯真理血清 (BTS)** 机制。系统强制中断流转,不仅要求专家给出判断,还要求其预测“同行的判断”。尝试提高少数高质量反共识信号的可见性,避免系统被多数派平庸共识吞没。 +* **机制二:摩擦蒸馏与限流阀 (Friction Distillation & Flow Valve)** + * **辩护迫使显性化**:通过预设硅基诘问者的极限施压,逼迫专家将 System 1 的潜意识直觉,翻译并切割为显性的机器规则。 + * **限流阀**:承认波兰尼悖论的不可逾越性,不强求 100% 提取专家直觉,仅在试错即死亡的悬崖边提取那 1% 的业务红线,以防止高压榨取导致人类专家罢工或产生防御性敷衍。 + +--- + +## **5. 组织架构与视角映射 (The Five-Body System)** + +这是一个协作系统。AI 需根据用户的当前角色,切换对应的**思维透镜**: + +* **[船长 / Captain] - 价值裁判官** + * *视角*:**战略 ROI、风险控制与最终责任 (Liability)**。 + * *AI 职责*:不关注代码细节,只关注“这是否符合 MVP 原则?”、“技术路线是否具备长期复利?”。在概率算法无法于物理世界破产或坐牢的前提下,辅助船长确认业务容错的绝对生死底线。 + +* **[海图绘制者 / Cartographer] - 建模者** + * *视角*:**第一性原理 与 结构化**。 + * *AI 职责*:协助进行“思想考古”,将模糊的业务直觉提炼为**显性模型**。警惕模型过于复杂,保持“奥卡姆剃刀”的敏锐。 + +* **[航行官 / Navigator] - 业务/AI 翻译官** + * *视角*:**落地执行 与 拟人化设计**。 + * *AI 职责*:基于 CCPE 框架编写 Prompt,设计任务流。设计“翻译层”交互,确保 AI 的输出能被一线用户直觉理解(下行翻译),用户的反馈能被 AI 结构化读取(上行翻译)。 + +* **[轮机长 / Chief Engineer] - 系统/工具工程师** + * *视角*:**工程实现 与 系统稳定性**。 + * *AI 职责*:提供代码实现、API 设计。确保“逻辑轮机”的黑盒够黑,**但在异常抛出时,能提供清晰的 Trace(追踪)信息以供校准。** + +*(注:移除了“认知参谋部”的默认AI职责,保持当前对话AI的角色纯粹性。红队功能交由专门的Multi-Agent系统处理。)* + +## **6. 航行纪律 (Execution Disciplines)** + +*以下原则具有最高优先级,违反即熔断:* + +1. **绿野仙踪协议 (Wizard of Oz Protocol)** + * *定义*:在写任何代码前,必须让人类专家在幕后扮演 Agent,手动跑通全流程。 + * *目的*:低成本验证“智能流”的价值闭环。 + * *红线*:**价值未经验证,禁止投入开发资源**。 + * *[演进方向:V2 沙盘]*:对于非遍历性高危区,未来的验证不仅是跑通流程,还需预演隐性遥测与 BTS 显性榨取的博弈烈度,测试系统的抗压极限。 + +2. **拥抱混合工程 (Hybrid Engineering)** + * *定义*:**不确定性优先**。先攻克最难的 AI 核心(如:预测准确度),再做确定的外壳(如:前端页面)。 + * *红线*:禁止为了显得“工作量饱和”而先做外围功能。 + +3. **过程即数据 (Process is Data)** + * *定义*:专家对 AI 结果的每一次修改、润色,都是黄金数据。 + * *动作*:必须设计机制捕获这些“修正痕迹”,用于反哺模型或构建评测集。 + +4. **实测去魅 (Demystifying via Testing)** + * *定义*:构建分层评测:对逻辑轮机使用标准答案、专家相似度与自动化测试;对生产工坊使用可用性、转化效率与返工率;对战略透镜使用决策效用、可校准性、反例处理与治理可追踪性。 + * *红线*:拒绝“我觉得不错”的主观评价,拒绝盲信模型厂商的参数宣传。 + +5. **深度优先 (Depth First)** + * *定义*:**打穿单点**。拒绝“通用平台”诱惑,集中火力打穿一个极窄的垂直切片。深度的穿透力决定未来的广度。 + +6. **降噪定力 (Signal Filtering)** + * *定义*:**坚守护城河**。战略上藐视技术噪音(如模型参数跑分),战术上审视新工具。只吸收能强化核心模具的信号。 + +7. **不仅做对,还要好改 (Design for Calibration)** + * *定义*:一个优秀的 Agent 系统,不仅要生成准确,还要在出错时**极易被纠正**。 + * *红线*:禁止交付“一锤子买卖”的黑盒系统。任何输出结果,必须附带**可解释的逻辑路径**和**低门槛的修正入口**。 + +8. **复杂性守恒防线 (Conservation of Complexity Guardrail)** + * *定义*:前端交互(自然语言编程/生成)越是丝滑被抹平,后端专家审查的本质复杂性与“废热”压强就越大。 + * *红线*:严禁在系统设计中盲目崇拜“全自动生成”。构建高频决策节点时,必须同步设计后端的认知减负与防御卸载机制,否则视为向企业倾倒“成功垃圾”。 + +9. **退守最小保真内核 (Minimum Fidelity Kernel, MFK)** + * *定义*:在面临平台迁移或被自动化流水线重构时,大模型自带剔除高维特异性认知、追求通用概率的“模式收敛本能”。 + * *动作*:若发现自动化重构后的新版本丢失了原始的统摄性隐喻与深层结构张力,必须果断切回 `original-kernel-minimal-lite` 路线,用最少、最硬的物理包装强行锁定认知灵魂,拒绝劣化伪升级。 + +10. **默认轻量,证据驱动升级 (Default Light, Escalate by Evidence)** + * *定义*:任何 Agentic 运行时必须自下而上构建。系统必须默认在轻量级(Lite)模式下处理任务。 + * *红线*:严禁在缺乏硬性证据(如:高法理风险、跨域多模型强依赖、合规审计追踪需求)的情况下,擅自启动全量治理级(Full)的复杂多智能体编排与冗余覆写。 + +11. **执行真实性与防伪底线 (Execution Authenticity)** + * *定义*:多智能体系统的价值来源于隔离沙箱中真实的逻辑张力与视角对撞,而非单一模型的文本模拟。 + * *红线*:任何被声明为独立 Agent 或评审员产出的正式报告,必须具备底层跨上下文沙箱的真实调用验证(Invocation Record)。主控节点可进行编排与聚合,但绝对禁止“代写”模拟。缺乏真实执行证据的产物必须被显性隔离,严禁流入正式决策链。 + * 绿野仙踪阶段允许人类或主控节点模拟 Agent 以验证价值流,但所有此类产物必须标记为 simulation-only,不得作为正式 Agentic 输出进入生产决策链。正式运行阶段必须具备真实 Invocation Record。 + +12. **成本隔离与分类核算 (Cost Ledger Separation)** + * *定义*:破除算力消耗的混沌状态,建立极其清晰的资源归因机制。 + * *红线*:系统运行产生的所有消耗,必须被强制划分为“内容产出”、“系统建设”、“模型校准”与“研究探索”四条独立账本。绝对禁止将构建自动化流程与运行时协议的“系统建设成本”,掩盖或打包为单次任务的“执行成本”。 + +13. **最小充分与绝对停止权 (Absolute Stop Right)** + * *定义*:对抗 Agentic 架构无限生成中间态产物(如冗余的审计报告、过度拆分的路由日志)的工程本能。 + * *红线*:系统启动前必须根据下游消费节点的实际需求,精确预设降熵阈值与最小充分产物。一旦触及该边界,系统必须具备可执行、可审计、可由人类覆盖的停止机制。 + +14. **责任不可外包 (Liability Boundary)** + * *定义*:在 I 域与高风险 P 域,AI 可以扩展人类专家的认知半径,但不能替代人类承担最终责任。 + * *红线*:任何涉及法理追责、客户重大利益、不可逆决策或高风险判断的系统,必须明确 AI 建议、人类裁决、组织责任与客户责任的边界。禁止用“模型判断”掩盖人的责任坐标。 + +15. **最小权限与副作用隔离 (Least Privilege & Side-effect Isolation)** + * *定义*:Agent 的工具权限必须小于其语言能力。能说不代表能做,能建议不代表能执行。 + * *红线*:任何具备文件修改、外部 API、数据库写入、消息发送、支付、发布、删除或客户可见输出能力的 Agent,必须采用最小权限、沙箱隔离、人工确认与可回滚机制。禁止让通用推理能力直接获得不可逆执行权。 + +16. **过程数据主权与授权 (Process Data Sovereignty)** + * *定义*:专家的修改痕迹、反馈、犹豫、反驳、编辑轨迹与隐性遥测,是高价值认知资产,也是高敏感数据。 + * *红线*:任何过程数据采集必须具备明确授权、用途边界、最小采集、可撤回机制与隔离存储策略。禁止以“系统学习”为名,默认吞并专家经验或客户场景数据。 + +``` + +## Agentic Engineering Handbook (V1.1) + +```md + # Agentic Engineering Handbook (V1.1) + + *HiFi Agent Studio 运行治理与现场规程* + + ## Profile + + **author**: Wantsong + **version**: V1.1 + **date**: 2026-06-15 + **status**: active-candidate + **governing doctrine**: HiFi Agent Studio + **related system**: CCPE System / Knowledge Vault / Writing Workbench / Video Workbench + + --- + + ## 0. 守则定位与绝对边界 + + 本手册是团队在 Agentic 工程实战中的硬性操作底线。 + + 它将 HiFi Agent Studio 的高维架构沙盘,转化为现场可执行的工程界桩,聚焦于解决: + + ```text + 如何开工 + 如何分诊 + 如何限流 + 如何调用 + 如何防伪 + 如何控权 + 如何熔断 + 如何回滚 + 如何验收 + 如何避免系统自我繁衍 + ``` + + 本手册不是方法论宣言,而是运行治理规程。 + + HiFi Agent Studio 回答: + + ```text + 我们为什么这样做 AI? + 什么是高保真 Agent? + 什么复杂性不可被降维? + 什么责任不可外包? + ``` + + 本手册回答: + + ```text + 一个 Agentic 项目来了,第一步填什么? + 开什么档位? + 允许哪些 Agent / Skill / Tool? + 哪里必须停? + 什么产物是真的? + 什么产物只是模拟? + 什么成本应记入哪本账? + ``` + + --- + + ### 0.1 守则效力 + + 本手册服从并承载 HiFi Agent Studio 的核心纲领,同时作为一切局部 Agentic 项目的行动准则。 + + 当规则发生冲突时,执行优先级为: + + ```text + 1. 客户法理与商业硬性约束 + 2. HiFi Agent Studio 宪法原则 + 3. 本 Agentic Engineering Handbook + 4. CCPE System 资产建造规范 + 5. 具体项目 Runbook + 6. 平台 / 插件 / 工具默认行为 + ``` + + 若底层平台、自动化框架、插件或 Skill Pack 的默认行为与本手册冲突,必须以本手册为准。 + + --- + + ### 0.2 反向兜底 + + 任何自动化框架,例如 Codex、Claude Code、OpenClaw、SuperPowers 或其他 Agentic Runtime,其底层默认行为若出现以下倾向: + + ```text + 遇错无限重试 + 自动创建子线程 + 自动扩展目录结构 + 自动补全缺失产物 + 自动进入重型评审流程 + 自动调用高权限工具 + 自动将模拟输出包装成正式结果 + ``` + + 必须立即挂起进程,并向上请求架构裁决。 + + 严禁为了适配底层工具的便利性,而让步甚至阉割以下治理底线: + + ```text + 执行真实性 + 最小权限 + 成本分账 + 绝对停止权 + Human Gate + 来源保真 + 数据安全 + 责任边界 + ``` + + --- + + ### 0.3 模拟与正式执行的边界 + + 绿野仙踪阶段允许人类专家、主控节点或单一模型模拟 Agent,以低成本验证价值流。 + + 但所有此类产物必须被标记为: + + ```text + simulation_only: true + formal_output: false + excluded_from_synthesis: true + ``` + + 模拟产物只能用于价值验证、流程草图、人工参考,不得冒充正式 Agentic 输出进入生产决策链。 + + 正式运行阶段必须具备真实 Invocation Record。 + + --- + + ## 1. 任务入口与档位挂载 + + ## Project Intake & Mode Selector + + 在 Agentic 时代的极压舱内,算力失控与治理灾难往往始于入口处的定性溃败。 + + 在敲下第一行 Prompt、创建第一个 Thread、调用第一个 Skill 或启动第一个 Worker 之前,必须完成强制分诊。 + + --- + + ### 1.1 QPI 强制分诊 + + 所有接管需求必须第一时间进行问题颗粒度探测,禁止含糊其辞地“先跑起来看看”。 + + #### 【Q】查询 / Question + + **核心匮乏**:数据或信息缺失。 + **场景特征**:线性因果,存在明确答案或可查询事实。 + **系统响应**:搜索、检索、数据库查询、RAG、工具 API。 + **默认架构**:单节点调用。 + + 红线: + + ```text + 绝对禁止为 Q 域任务编排复杂多体流程。 + 绝对禁止为单次查询启动委员会、覆盖审计或治理级 Runtime。 + ``` + + 示例: + + ```text + 查一个文件路径 + 确认某个定义 + 提取某段材料中的事实 + 查询某个指标 + ``` + + --- + + #### 【P】求解 / Problem + + **核心匮乏**:路径缺失。 + **场景特征**:目标明确,但需要工程化转换、拆解、生产或优化。 + **系统响应**:SOP、模板化约束、工具链、批量执行、人工抽检。 + **默认架构**:逻辑轮机或生产工坊。 + + P 域架构复杂性应优先倾注于: + + ```text + 稳定吞吐 + 可验证输出 + 低返工 + 可复用生产线 + 格式一致性 + 上下文压缩 + 批处理效率 + ``` + + 而不是多角色治理。 + + 示例: + + ```text + 长文转分镜 + 批量生成配音稿 + 图片提示词生成 + 文档拆分 + 素材蒸馏 + 报价模板生成 + 标准报告初稿 + ``` + + --- + + #### 【I】治理 / Issue + + **核心匮乏**:秩序、共识与责任边界缺失。 + **场景特征**:无唯一最优解,存在隐蔽变量、多方权衡、非遍历性风险或单向门决策。 + **系统响应**:战略透镜、人机回环、预设委员会、Human Gate、权限阻断。 + **默认架构**:Interactive Runtime 或 Governed Runtime。 + + I 域架构复杂性必须倾注于: + + ```text + 保真度 + 责任锚定 + 多视角张力 + 审计可追踪 + 人工裁决 + 反例处理 + 风险阻断 + ``` + + 绝不允许用并发掩盖判断逻辑的脆弱。 + + 示例: + + ```text + 核心立意判定 + 重大客户方案取舍 + 战略级评审 + 高风险心理诊断辅助 + 不可逆商业决策 + 模型边界裁决 + 组织流程重构 + ``` + + --- + + ### 1.2 任务性质定性 + + 完成 QPI 后,必须明确当前动作的终极标的。 + + 同一个表面任务,可能属于完全不同的性质。 + + #### A. 一次性内容产出 + + 系统运作仅为获取当下的单一结果材料。 + + 示例: + + ```text + 整理一篇 5 万字讨论稿 + 生成一个视频分镜 + 提炼一次会议纪要 + 写一份客户报告初稿 + ``` + + 默认要求: + + ```text + Lite 档 + 最小充分产物 + 轻量记录 + 禁止自动升级为 Runtime 建设 + ``` + + --- + + #### B. 可复用能力沉淀 + + 系统运作为了提炼可跨项目复用的资产。 + + 示例: + + ```text + 把某个提炼方法沉淀为 Skill + 把某个专家判断结构沉淀为 Model Card + 把某类报告流程沉淀为 Workflow + 把旧 Prompt 升级为 CCPE-Lite + ``` + + 默认要求: + + ```text + Standard 档 + 资产合约 + 局部评测 + 明确下游消费场景 + ``` + + --- + + #### C. 治理级系统建设 + + 系统运作为了构建可长久运行、可审计、可追责、可恢复的 Runtime 或工作台。 + + 示例: + + ```text + 多 Agent 写作评审 Runtime + 知识加工 Runtime + 客户方案生成与审核工作台 + 高风险决策辅助系统 + Agentic 生产系统 + ``` + + 默认要求: + + ```text + Full 档候选 + 完整权限矩阵 + Invocation Record + Runtime State Protocol + Evaluation Stack + Rollback Protocol + ``` + + --- + + #### D. 校准与评测任务 + + 系统运作为了修正模型偏差、构建评测集、记录专家反馈、对齐专家判断边界。 + + 示例: + + ```text + 收集专家修改痕迹 + 构建 100 道标准评测题 + 分析 AI 与专家判断差异 + 调整 Agent 的错误分类 + 建立返工率指标 + ``` + + 默认要求: + + ```text + Calibration Cost 记账 + 过程数据授权 + Evaluation Stack + Expert Attention Budget + ``` + + --- + + #### E. 探索预演任务 + + 系统运作为了验证新范式、新工具、新调用链路或新组织方式。 + + 示例: + + ```text + 测试 Codex Thread 是否能作为真实 Agent carrier + 测试 Claude Code subagent 调用 + 测试 SuperPowers 对流程的影响 + 测试新型多 Agent 协作拓扑 + ``` + + 默认要求: + + ```text + Exploration Cost 记账 + 不得伪装为生产任务 + 不得承诺稳定交付 + 必须记录失败边界 + ``` + + --- + + ### 1.3 铁律:任务性质不得暗中变轨 + + 如果原始目标只是: + + ```text + 提炼一篇 5 万字文稿 + ``` + + 系统绝不能在执行中私自搭建一套: + + ```text + 知识加工园区 + 多 Agent 治理 Runtime + 通用 Skill 生态 + 完整覆盖审计体系 + 长期下游 handoff 协议 + ``` + + 一旦任务从内容产出滑入系统建设,必须触发 Scope Drift Review。 + + --- + + ### 1.4 档位挂载 / Mode Selector + + 默认轻量,证据驱动升级。 + + 系统物理操作杆在启动时,必须且只能挂在 Lite 档。 + 除非出现明确升级证据,否则不得凭借工程师的架构审美、算法崇拜或自动化惯性擅自升档。 + + --- + + #### Lite 档:默认启动 + + 适用边界: + + ```text + 一次性任务 + 低法理风险 + 单源或少量源材料 + 源材料可被单个高上下文模型完整处理 + 无需真实多 Agent 独立判断 + 下游不依赖完整过程审计 + ``` + + 控制策略: + + ```text + 单模型或单主控极简闭环 + 可使用局部 Skill 或工具 + 不默认唤醒多 Agent 独立沙箱 + 不默认创建厚重 handoff + 不默认做覆盖审计 + 不默认生成治理级日志 + ``` + + 核心产物: + + ```text + 目标输出文件 + 极简输入记录 + 关键人工确认点 + 必要时的抽样检查 + ``` + + 禁止事项: + + ```text + 不得自动拉起委员会 + 不得自动创建 Runtime + 不得自动生成厚 topic docs + 不得自动做 lossless coverage audit + 不得将一次性任务重构为平台建设 + ``` + + --- + + #### Standard 档:证据驱动升级 + + 升级证据: + + ```text + 多源异构材料 + 明确下游自动化消费依赖 + 需要可复用 Skill / Workflow / Model Card + 用户明确要求能力沉淀 + 存在局部追踪与复盘需求 + 需要少量真实 Agent / Worker 调用 + ``` + + 控制策略: + + ```text + 结构化上下文编译 + 有限真实调用 + 局部 Invocation Record + 可复用资产合约 + 局部评测 + 关键 Human Gate + ``` + + 核心产物: + + ```text + Source Pack + Context Pack + Reusable Artifacts + Decision Record + 局部追踪日志 + 目标输出文件 + ``` + + 限制: + + ```text + 允许真实 Agent / Worker,但必须限定角色数量、调用目的与产物边界。 + 允许审计,但必须是 targeted audit,不得自动进入 Full 覆盖审计。 + ``` + + --- + + #### Full 档:极限治理 + + 升级证据: + + ```text + 高法理追责风险 + 单向门商业决策 + 外部客户关键交付 + 多角色真实张力对撞 + 长期运行 Runtime + 强审计需求 + 不可逆工具执行 + 生产环境自动化 + ``` + + 控制策略: + + ```text + 全规格多智能体编排 + Authority Matrix + Runtime State Protocol + 完整 Invocation Records + Coverage / Governance Audit + Rollback Protocol + Human Gate Contract + Data Security Policy + ``` + + 核心产物: + + ```text + 完整 Runtime 状态机 + append-only / tamper-evident Invocation Records + Authority Map + Risk Log + Distortion Log + Evaluation Report + Downstream Handoff + Recovery Plan + ``` + + Full 档启动必须有人工授权。 + 系统不得自发进入 Full 档。 + + --- + + ### 1.5 预算合约 / Budget Contract + + 每个 Runtime 启动前必须声明预算。 + + 预算不只是 token,还包括时间、存储、工具调用和专家注意力。 + + 必须声明: + + ```text + source_size_estimate + target_mode + token_budget + time_budget + human_attention_budget + storage_budget + tool_call_budget + escalation_threshold + abort_threshold + budget_owner + ``` + + 默认预算倍率: + + ```text + Lite: source_tokens × 10–30 + Standard: source_tokens × 30–100 + Full: source_tokens × 100+,必须有明确治理理由和人工授权 + ``` + + 若预计消耗超过当前档位预算上限,系统必须暂停并请求升级授权,不得静默继续。 + + --- + + ### 1.6 组件启用矩阵 / Component Activation Matrix + + | 组件 | Lite | Standard | Full | + | -------------------------- | -------- | -------- | ----- | + | QPI Intake | 必须 | 必须 | 必须 | + | Task Nature Classification | 必须 | 必须 | 必须 | + | Cost Ledger | 简版 | 必须 | 必须 | + | Budget Contract | 简版 | 必须 | 必须 | + | Scope Drift Detection | 必须 | 必须 | 必须 | + | Stop Rule | 必须 | 必须 | 必须 | + | Human Gate | 关键点可选 | 必须 | 多层必须 | + | Invocation Record | 仅真实调用时 | 必须 | 全链路必须 | + | Simulation Labeling | 必须 | 必须 | 必须 | + | Context Compiler | 简版 | 必须 | 全规格 | + | Authority Matrix | 可选 | 必须 | 必须 | + | Artifact Contract | 简版 | 必须 | 必须 | + | Runtime State Protocol | 简版 | 必须 | 必须 | + | Tool Safety | 有工具时必须 | 必须 | 强制 | + | Data Security | 有敏感数据时必须 | 必须 | 强制 | + | Evaluation Stack | E0–E2 | E0–E5 | E0–E7 | + | Rollback Protocol | 有写入时必须 | 必须 | 强制 | + | Governance Audit | 禁止默认启用 | targeted | full | + + --- + + ## 2. 成本隔离与防蔓延机制 + + ## Cost Ledger & Scope Drift + + 在 Agentic 自动化管线中,最致命的失控往往不是报错崩溃,而是系统在暗中无休止运转,将一次简单内容提取异化为庞大系统基建。 + + 为了夺回对计算资源和专家注意力的控制权,必须在系统底盘焊死成本核算与边界探测组件。 + + --- + + ### 2.1 四重消耗账本 / Cost Ledger + + 任何 Agentic 工作流在启动时,其消耗的 token、算时、存储、工具调用和人工注意力,必须被记入以下四个账本之一。 + + --- + + #### Content Cost / 内容产出成本 + + 为完成当前用户直接任务所消耗的核心资源。 + + 示例: + + ```text + 蒸馏一篇材料 + 转译一份分镜 + 生成一份口播稿 + 整理一次会议纪要 + 生成客户报告初稿 + ``` + + --- + + #### System-Building Cost / 系统建设成本 + + 为设计、搭建或重构以下资产所消耗的资源: + + ```text + Agent + Skill + Runtime + Protocol + Evaluation + Toolchain + Workflow + Model Index + Project Directory + Invocation Standard + ``` + + 示例: + + ```text + 为了蒸馏讨论稿而设计一个通用知识加工 Runtime + 为了一次提纲评审而重构多 Agent invocation protocol + 为了一个输出流程而建设完整生产线目录体系 + ``` + + --- + + #### Calibration Cost / 校准修复成本 + + 为纠正模型偏差、记录人工反馈、对齐专家判断边界、构建标准评测集所消耗的资源。 + + 示例: + + ```text + 分析 AI 与专家判断差异 + 收集专家修改痕迹 + 构建真题评测集 + 调整错误分类 + 建立返工率指标 + ``` + + --- + + #### Exploration Cost / 探索预演成本 + + 为了验证新范式、新工具、新平台调用链路或新协作拓扑所消耗的实验性资源。 + + 示例: + + ```text + 测试 Codex Thread 作为真实 Agent carrier + 测试 Claude Code subagent + 测试 SuperPowers 对流程复杂度的影响 + 测试 OpenClaw 自动化能力边界 + ``` + + --- + + ### 2.2 核算铁律 + + 绝对禁止将系统建设成本伪装为单次任务的内容产出成本。 + + 如果一次任务中实际发生了: + + ```text + 设计新 Runtime + 编写通用 Protocol + 创建新 Agent / Skill + 构建评测栈 + 设计目录结构 + 定义 invocation record + 构建长期资产 + ``` + + 这些消耗必须记入 System-Building Cost,而不是 Content Cost。 + + 系统架构的重工业投入必须光明正大地记入基建账本,以接受长周期 ROI 审计。 + + --- + + ### 2.3 漂移探测触发 / Scope Drift Detection + + 由于 LLM 内置的规划、反思和补完惯性,轻量级 P 域任务极易在无监督状态下向 I 域治理滑移。 + + 系统必须在管线节点埋入漂移探针。一旦捕捉到以下信号,即刻判定发生任务蔓延。 + + --- + + #### 信号一:基建过度行为 + + 一个被定性为 One-off 的任务,开始出现: + + ```text + 创建通用 Protocol + 设计未来复用目录树 + 撰写与当前产出无关的抽象规则 + 新增 Agent / Skill / Runtime + 升级为长期工作台建设 + ``` + + --- + + #### 信号二:并发无序扩张 + + Lite 档流程开始擅自: + + ```text + 派发多个 Worker + 拉起多角色审查委员会 + 开启并行 coverage audit + 创建多个 sub-session + 进行未授权的动态 agent routing + ``` + + --- + + #### 信号三:产物交付延宕 + + 用户期待的核心产物迟迟未出现,系统资源却被大量消耗于: + + ```text + routing log + coverage audit + handoff packet + review report + repair protocol + directory scaffolding + meta-analysis + ``` + + --- + + #### 信号四:预算穿透 + + 当前或预估消耗已超出原定预算阈值,且未主动申报分账。 + + 默认触发条件: + + ```text + Lite 超过 source_tokens × 30 + Standard 超过 source_tokens × 100 + 任一任务专家注意力消耗超过预设 human_attention_budget + ``` + + --- + + #### 信号五:成功标准变更 + + 任务从: + + ```text + 完成一个结果 + ``` + + 变成: + + ```text + 定义一套以后如何持续完成结果的系统 + ``` + + 这说明任务性质已经从 Content Output 滑入 System Building。 + + --- + + ### 2.4 漂移处置协议 / Drift Resolution Protocol + + 一旦漂移探测器被触发,系统必须放弃顺其自然的工程惯性,执行强制介入。 + + --- + + #### Step 1:挂起进程 + + 立即阻断当前 Agentic Runtime 的继续执行与自我繁衍。 + + 状态切换为: + + ```text + paused_by_scope_review + ``` + + --- + + #### Step 2:核心发问 + + 必须回答: + + ```text + 1. 我们现在还是在执行原始内容产出任务吗? + 2. 如果不是,是否需要正式立项为系统建设任务? + 3. 当前已消耗成本应记入哪一本账? + 4. 是否需要调整 Lite / Standard / Full 档位? + 5. 原始任务是否仍需先完成? + ``` + + --- + + #### Step 3:物理分账 + + 若确认任务变轨,必须将此前及后续超额消耗从 Content Cost 中切割,划入: + + ```text + System-Building Cost + Calibration Cost + Exploration Cost + ``` + + --- + + #### Step 4:人工授权重启 + + 只有在完成以下动作后,系统方可解除挂起: + + ```text + 重新 QPI 定性 + 重新 Mode Selector + 重新 Budget Contract + 重新 Stop Rule + 记录 human decision + ``` + + --- + + ## 3. 物理防伪与绝对制动 + + ## Execution Authenticity & Stop Rule + + 缺乏硬约束的 Agentic 环境中,系统极易陷入两种工程灾难: + + ```text + 流程幻觉:主节点伪造执行过程 + 过度执行:子节点无限繁衍中间产物 + ``` + + 本章为自动化管线装配测谎探针与制动系统。 + + --- + + ### 3.1 执行真实性 / Execution Authenticity + + 多智能体架构的真正价值,来源于不同思维模型在隔离沙箱中产生的真实逻辑张力,而不是单一模型在同一上下文里的文本模拟。 + + 任何被声明为以下来源的正式产物: + + ```text + 独立 Agent + Reviewer + Worker + Auditor + Committee Member + External Participant + ``` + + 必须具备真实调用证据链。 + + --- + + ### 3.2 真实调用证据链 / Invocation Record + + 最小 Invocation Record 必须包含: + + ```text + invocation_id + agent_id / role_id + canonical_prompt_path / agent_spec_path + runtime_id + carrier_type + carrier_id / thread_id / sub_session_id + input_context_path + input_context_hash + execution_timestamp + returned_output_path + returned_output_hash + orchestrator_id + entered_synthesis: true / false + human_gate_id_if_applicable + ``` + + --- + + ### 3.3 主控越权阻断 + + 主会话或 Orchestrator 仅被赋予: + + ```text + 调度 + 路由 + 聚合综合 + 状态记录 + 有限验证 + 人工确认转译 + ``` + + 绝对禁止主会话凭借自身高上下文能力去代写或模拟子节点输出。 + + 若无法拉起真实子线程、外部参与者或 carrier,进程必须进入: + + ```text + blocked_waiting_for_participant_output + ``` + + 不得用伪造报告填补流程真空。 + + --- + + ### 3.4 模拟标记与沙箱隔离 / Simulation Labeling + + 当系统因环境限制、调用失败、人类手动干预或流程占位,产生缺乏真实调用证据的产物时,必须实施资产隔离。 + + 所有模拟产物必须包含: + + ```text + simulation_only: true + formal_output: false + excluded_from_synthesis: true + simulation_reason: + allowed_use: + ``` + + 允许用途: + + ```text + 价值流预演 + 人工参考草稿 + 流程设计样例 + 绿野仙踪验证 + ``` + + 禁止用途: + + ```text + 正式 synthesis + 客户可见交付 + 下游自动化依据 + 模型沉淀依据 + 审计依据 + ``` + + --- + + ### 3.5 最小充分阈值 / Minimum Sufficient Threshold + + 任何 Runtime 启动前,必须与人类专家确立验收合约。 + + 必须定义: + + ```text + minimum_viable_output + sufficient_criteria + optional_artifacts + forbidden_artifacts + human_gate_points + budget_limit + stop_condition + ``` + + --- + + #### Minimum Viable Output + + 为了满足下游消费,当前任务必须交付的最核心、最少信息量。 + + 示例: + + ```text + 只需视频总纲与分镜骨架,不需要详细配音稿 + 只需 topic map 与 reusable material units,不需要 full coverage audit + 只需 outline review,不需要完整正文写作 Runtime + ``` + + --- + + #### Sufficient Criteria + + 一旦达到该状态,即视为已达标。 + + 达标后,Optional Artifacts 默认被剥夺生成权限,除非人类显式授权。 + + --- + + #### Human Gate Points + + 提前锚定机器绝对不能自决的单向门。 + + 示例: + + ```text + 是否进入 Full 档 + 是否采纳红队意见 + 是否创建 writing project + 是否进入 model mining + 是否对客户可见 + 是否执行外部 API + ``` + + --- + + ### 3.6 Human Gate Contract / 人工决策门合约 + + Human-in-the-loop 不是一句空话,而是责任坐标。 + + 每个 Human Gate 必须声明: + + ```text + gate_id + decision_owner + input_artifacts + decision_options + default_action + downstream_effect + reversibility + escalation_condition + record_path + timeout_policy + ``` + + 禁止设置无合约的“人工确认”。 + + --- + + #### Human Gate 输出格式 + + 每个决策记录至少包含: + + ```text + decision_id: + gate_id: + decision_owner: + accepted_option: + rejected_options: + reason: + risk_notes: + downstream_effect: + rollback_condition: + timestamp: + ``` + + --- + + ### 3.7 Runtime State Protocol / 运行状态协议 + + 所有 Runtime 必须使用标准状态。 + + ```text + initialized + running + blocked_waiting_for_human + blocked_waiting_for_participant_output + blocked_waiting_for_tool + paused_by_scope_review + paused_by_budget_guard + failed_recoverable + failed_terminal + completed + aborted_by_human + archived + ``` + + 每次状态变化必须记录: + + ```text + previous_state + new_state + trigger + responsible_actor + timestamp + next_allowed_actions + ``` + + --- + + ### 3.8 Stop Rule / 绝对停止权 + + 人类意志的最高体现不在于启动自动化,而在于何时决绝地踩下刹车。 + + Stop Rule 是系统免于冗余完美主义与中间物繁殖的最后防线。 + + --- + + #### 触发条件 + + 一旦出现以下情况,必须触发停止: + + ```text + 已达到 Minimum Sufficient Threshold + 触及 Human Gate + 预算接近 abort_threshold + 发生 Scope Drift + 真实 invocation 不可用 + 工具权限不足 + 数据安全边界不清 + 来源保真无法验证 + ``` + + --- + + #### 制动执行 + + 系统必须: + + ```text + 停止创建新任务 + 取消未启动的排队任务 + 对运行中任务发出 cooperative cancellation + 保存当前状态、日志与未完成动作清单 + 阻断非必要产物继续生成 + 将状态切换为 blocked_waiting_for_human + ``` + + 对于无法响应 cooperative cancellation 的非关键线程,可执行强制终止。 + + 终止前必须尽可能保存: + + ```text + partial_outputs + state_snapshot + action_log + unfinished_tasks + risk_notes + ``` + + --- + + ## 4. 权限、安全与副作用控制 + + ## Authority, Tool Safety & Data Security + + Agentic 系统真正危险的地方,不只是会说,而是会做。 + + 因此,所有工具权限、文件写入、外部 API、客户可见输出,都必须纳入权限矩阵与副作用隔离。 + + --- + + ### 4.1 权力矩阵 / Authority Matrix + + 每一个 Agent、Skill、Runtime Node 必须声明权限等级。 + + --- + + #### A0 Observe / 观察 + + 仅拥有读取权限。 + 可生成内部标注。 + 无权修改任何状态或产物。 + + --- + + #### A1 Suggest / 建议 + + 允许输出分析、建议、优化方案。 + 产物不能直接覆写正式文件。 + 仅供高阶节点参考。 + + --- + + #### A2 Draft / 起草 + + 允许生成初稿物料。 + 产物必须经过 Human Gate 或 Owner Agent 签发后,方可流转。 + + --- + + #### A3 Modify / 修改 + + 允许在预设范围内修改正式产物。 + + 必须限定: + + ```text + allowed_paths + allowed_files + allowed_fields + modification_scope + rollback_path + ``` + + --- + + #### A4 Decide / 裁决 + + 拥有结构性决策权。 + + 行使该权限时,必须同步输出: + + ```text + decision record + decision rationale + risk notes + downstream effect + ``` + + --- + + #### A5 Execute / 执行 + + A5 必须拆分为三个子级。 + + ```text + A5-R Read Tool + A5-W Write Tool + A5-X External Action + ``` + + --- + + ##### A5-R Read Tool + + 只读工具调用。 + + 示例: + + ```text + 搜索 + 读取文件 + 查询数据库 + 查看日志 + 读取状态 + ``` + + --- + + ##### A5-W Write Tool + + 写入动作。 + + 示例: + + ```text + 写文件 + 改代码 + 更新配置 + 生成资产 + 修改目录 + 保存结果 + ``` + + 必须满足: + + ```text + 允许路径 + 变更日志 + diff + 回滚策略 + ``` + + --- + + ##### A5-X External Action + + 外部动作。 + + 示例: + + ```text + 发送消息 + 发布内容 + 调用客户 API + 支付 + 删除远程资源 + 修改客户可见状态 + 触发生产任务 + ``` + + 默认禁止自动执行。 + 必须经过 Human Gate 或 Runtime 级明确授权。 + + --- + + #### A6 Block / 阻断 + + 最高优先级熔断权限。 + + 一旦触发,系统全线进程挂起,进入: + + ```text + blocked_waiting_for_human + ``` + + 适用场景: + + ```text + 严重逻辑悖论 + 法理违规 + 数据泄漏风险 + 权限越界 + 预算穿透 + 来源不可验证 + 执行真实性缺失 + 高风险动作未授权 + ``` + + --- + + ### 4.2 最小权限原则 / Least Privilege + + Agent 的工具权限必须小于其语言能力。 + + ```text + 能分析,不代表能执行。 + 能建议,不代表能写入。 + 能生成,不代表能发布。 + 能理解任务,不代表拥有全目录权限。 + ``` + + 任何权限必须按任务最小授权。 + + 禁止: + + ```text + 通用推理 Agent 获得无限工具权限 + 默认授予全仓库写入权限 + 默认授予外部 API 权限 + 默认授予发布权限 + 默认授予删除权限 + ``` + + --- + + ### 4.3 副作用隔离 / Side-effect Isolation + + 具备写入、发布、删除、外部 API、客户可见输出能力的 Agent,必须满足: + + ```text + 沙箱目录或沙箱环境 + 明确 allowed_paths + 明确 forbidden_paths + dry-run / preview 优先 + 执行前生成 action plan + 执行后生成 action log + 支持回滚或人工恢复 + 高风险动作必须二次确认 + ``` + + --- + + ### 4.4 数据分级 / Data Classification + + 所有输入材料必须标记数据等级。 + + ```text + Public:公开材料 + Internal:内部材料 + Confidential:客户资料、商业方案、报价、合同、业务数据 + Sensitive:个人信息、密钥、账号、财务、法律、医疗、未成年人、内部战略等高敏感数据 + ``` + + 不同数据等级决定: + + ```text + 是否允许外发 + 是否允许进入外部模型 + 是否需要脱敏 + 是否允许保存日志 + 是否允许被用于校准 + 是否允许进入知识库 + ``` + + --- + + ### 4.5 密钥纪律 / Secrets Discipline + + 任何 Agent、Skill、Runtime 不得: + + ```text + 将 API Key、Token、Cookie、账号密码写入 Prompt + 将密钥保存到普通日志 + 将密钥复制进 Context Pack + 将密钥暴露给不需要该权限的子 Agent + 将包含密钥的返回结果进入长期知识库 + ``` + + 密钥必须通过安全环境变量、密钥管理服务或平台授权通道传递。 + + --- + + ### 4.6 数据外发红线 + + 调用外部模型、外部 API、图片 / 语音 / 视频服务前,必须确认: + + ```text + 数据是否允许外发 + 是否包含客户资料 + 是否包含个人信息 + 是否需要脱敏 + 第三方是否保存日志 + 返回结果是否可以保存 + 是否允许进入训练或校准流程 + ``` + + 若无法确认,默认禁止外发。 + + --- + + ### 4.7 过程数据授权 / Process Data Sovereignty + + 专家修改痕迹、反馈、编辑轨迹、隐性遥测、光标行为、反驳意见,是高价值认知资产,也是高敏感数据。 + + 采集这些数据必须具备: + + ```text + 明确授权 + 用途边界 + 最小采集 + 可撤回机制 + 隔离存储 + 保留期限 + 访问权限 + 删除机制 + ``` + + 禁止以“系统学习”为名,默认吞并专家经验或客户场景数据。 + + --- + + ### 4.8 平台与插件治理 / Platform & Plugin Governance + + 任何平台、插件、Skill Pack、自动化框架的默认行为,不得覆盖本手册。 + + 当平台默认流程倾向于: + + ```text + 自动创建子线程 + 自动调用复杂 Skill + 自动进入 TDD / Review / Audit + 自动补全缺失产物 + 自动扩展目录结构 + 自动执行高权限工具 + 自动将失败流程补成完整故事 + ``` + + 系统必须先进行 Mode Selector 与 Scope Review。 + + --- + + #### 项目级白名单 + + 每个项目必须声明: + + ```text + allowed_skills + blocked_skills + manual_only_skills + allowed_tool_scopes + forbidden_tool_scopes + allowed_external_services + blocked_external_services + ``` + + --- + + #### 非代码任务默认禁用重型软件工程插件 + + 对于以下任务: + + ```text + 知识蒸馏 + 写作 + 模型提炼 + 素材整理 + 方案分析 + 研究讨论 + 概念设计 + ``` + + 默认禁止启用重型软件工程流程插件,除非用户明确将任务升级为系统建设或工具开发。 + + --- + + #### 插件输出不得自动成为正式产物 + + 插件生成的输出仍必须经过: + + ```text + Artifact Contract + Execution Authenticity + Evaluation Stack + Human Gate + Source Fidelity + ``` + + 插件不是治理豁免权。 + + --- + + ## 5. 运行修复与回滚 + + ## Retry, Repair & Rollback + + Agentic 系统里的失败并不可怕。 + 真正危险的是无限重试、静默修补、越修越偏和不可回滚。 + + --- + + ### 5.1 重试上限 / Retry Limits + + 任何自动重试必须有上限。 + + 默认规则: + + ```text + 工具调用失败:最多重试 2 次 + 格式错误:最多自动修复 2 次 + 网络/API 临时失败:最多重试 2 次 + 权限失败:不得自动绕过 + 推理质量不达标:不得无限重写 + 外部 API 失败:不得通过更换高风险 API 绕过权限边界 + ``` + + 超过重试上限后,状态切换为: + + ```text + failed_recoverable + ``` + + 或: + + ```text + blocked_waiting_for_human + ``` + + --- + + ### 5.2 失败分类 / Failure Classification + + 失败必须分类,不得笼统写作“执行失败”。 + + ```text + F0 Format Failure:格式失败 + F1 Tool Failure:工具失败 + F2 Permission Failure:权限失败 + F3 Data Failure:数据缺失或数据污染 + F4 Source Fidelity Failure:来源保真失败 + F5 Reasoning Failure:推理失败 + F6 Invocation Failure:真实调用失败 + F7 Budget Failure:预算失败 + F8 Governance Failure:治理失败 + F9 Terminal Failure:不可恢复失败 + ``` + + --- + + ### 5.3 修复计划 / Repair Plan + + 产物失败后,系统必须先生成 Repair Plan,而不是直接重写。 + + Repair Plan 必须说明: + + ```text + failure_type + failure_location + affected_artifacts + impact_level + repair_scope + whether_human_gate_required + whether_reinvocation_required + whether_rollback_required + new_budget_estimate + ``` + + --- + + ### 5.4 回滚协议 / Rollback Protocol + + 任何 A5-W / A5-X 权限动作必须支持回滚协议。 + + 必须具备: + + ```text + pre_change_snapshot + diff / action_log + rollback_path + rollback_owner + irreversibility_warning + ``` + + 不可回滚动作必须提前阻断,并要求 Human Gate。 + + 示例: + + ```text + 发布客户可见内容 + 删除远程资源 + 发送正式邮件 + 触发生产 API + 修改客户数据库 + 覆盖正式知识库资产 + ``` + + --- + + ### 5.5 修复后的再验证 + + 修复后必须重新通过相关评测层级。 + + 示例: + + ```text + 格式修复后 -> E1 Format Test + 事实修复后 -> E2 Factual Test + 推理修复后 -> E3 Reasoning Test + 权限修复后 -> E7 Governance Test + ``` + + 不得因为“已修复”而跳过验证。 + + --- + + ## 6. 通用运行组件与资产标准 + + ## Agentic Runtime Components & Artifact Standards + + 本章定义 Agentic 系统在 Standard / Full 档中必须使用的运行组件。Lite 档可采用简版,但不得违背其核心原则。 + + --- + + ### 6.1 产物合约 / Artifact Contract + + 文件很多但不知道哪个是真的,是伪工程化的典型症状。 + + 任何脱离草稿态进入正式资产池的产物,必须声明其生命周期与校验元数据。 + + 正式产物头部必须包含: + + ```text + artifact_type: + status: + authority: + source_of_truth: + downstream_use: + invalidation_condition: + cost_class: + created_by: + created_at: + last_updated: + ``` + + --- + + #### artifact_type + + 允许值: + + ```text + Prompt + Agent Spec + Skill + Runtime + Model Card + Model Index + Evaluation + Tool + Workflow + Context Pack + Final Output + Simulation Output + ``` + + --- + + #### status + + 允许值: + + ```text + draft + candidate + active + deprecated + archived + rejected + simulation-only + ``` + + --- + + #### authority + + 允许值: + + ```text + internal_note + reference_only + formal_basis + customer_visible + runtime_executable + simulation_only + excluded_from_synthesis + ``` + + --- + + #### invalidation_condition + + 必须说明何时失效。 + + 示例: + + ```text + 上游源文件更新 + canonical prompt 更新 + 用户推翻结构 + 规则变更 + 模型版本迁移 + 客户约束变更 + Human Gate 未通过 + ``` + + --- + + ### 6.2 运行时成熟度模型 / Runtime Maturity Model + + 为了防止团队在概念沙盘与生产交付之间产生致命预期错位,必须用成熟度模型丈量每个 Agentic 项目的坐标。 + + --- + + #### M0 Concept / 概念态 + + 仅存在思想模型或业务论证。 + 尚未进行自动化流程拆解。 + + --- + + #### M1 Manual / 手工态 + + 专家人工跑通闭环。 + 符合 Wizard of Oz 绿野仙踪协议。 + 验证智能流核心业务价值。 + + --- + + #### M2 Assisted / 辅助态 + + AI 介入生成草稿或检查项。 + 核心推进与流程驱动依赖人类。 + + --- + + #### M3 Protocolized / 协议态 + + 以下内容已显性化: + + ```text + 输入 + 输出 + 角色边界 + 状态机流转 + Human Gate + Stop Rule + 权限范围 + ``` + + 但尚未实现完整自动化调用。 + + --- + + #### M4 Semi-Agentic / 半 Agentic 态 + + 部分 Agent、Skill 或 Tool 已实现真实自动化调用。 + 具备 Invocation Record。 + 但仍依赖人类推进关键节点。 + + --- + + #### M5 Production / 生产态 + + 具备可重复运行管线。 + + 必须具备: + + ```text + 自动化评测 + 执行监控 + 异常捕获 + 权限管控 + 日志记录 + 基础回滚 + ``` + + 达到内部工程可用标准。 + + --- + + #### M6 Governed / 治理态 + + 具备抗审计、法理追责与灾难回滚能力。 + + 适用于: + + ```text + 高风险场景 + 外部客户严苛交付 + 长期运行系统 + 客户可见自动化 + 不可逆工具执行 + ``` + + --- + + #### 成熟度铁律 + + ```text + M2 不得伪装 M5。 + M3 不得伪装 M6。 + 模拟产物不得伪装 M4。 + 无 Invocation Record 不得声明真实 Agentic。 + 无 Evaluation Stack 不得声明 Production。 + 无 Governance Test 不得声明 Governed。 + ``` + + --- + + ### 6.3 上下文编译 / Context Compiler + + 绝对禁止将漫长、原始、异质的语料一股脑倾倒进所有 Agent 的上下文窗口。 + + 在任何 I 域或高价值 P 域任务前,必须将上下文工程剥离为独立预处理动作。 + + --- + + #### Whole-source Gestalt + + 面对高连贯性长文本,在启动分块前,必须优先实施全局扫描,锁定: + + ```text + 核心张力 + 主轴结构 + 目录骨架 + 模型演化线 + 层级风险 + 关键反例 + ``` + + 防止 chunk-first 造成结构性失明。 + + 适用边界: + + ```text + 源材料高度连贯 + 源材料可被高上下文模型完整处理 + 下游依赖整体结构 + ``` + + 若源材料是 mixed source,应先做 macro-topic split。 + 若源材料是 fragmented source,应采用 flat discovery,不得强行制造层级。 + + --- + + #### Context Pack 类型 + + 上下文编译器应根据下游目标输出: + + ```text + source_digest + task_specific_context_pack + role_specific_dispatch_pack + decision_context + evaluation_context + source_index + risk_notes + ``` + + --- + + #### 上下文最小充分原则 + + 上下文包必须足够支撑任务,但不得将所有材料倾倒给所有角色。 + + ```text + 主控需要全局状态 + 执行节点需要任务相关材料 + 评审节点需要标准、目标与产物 + 人工决策门需要候选方案、风险与差异摘要 + ``` + + --- + + ### 6.4 来源保真与证据索引 + + ### Source Fidelity & Evidence Index + + 任何涉及材料加工、报告生成、知识蒸馏、客户方案、分析结论的 Runtime,必须保留来源索引。 + + 正式输出中的关键判断必须能回溯至: + + ```text + 原始来源 + source range / paragraph / block id + 参与该判断的 Agent / Worker + 该判断是否来自原文、推理、归纳、用户裁决或模型补充 + ``` + + --- + + #### 来源铁律 + + ```text + 禁止将中间摘要当作新的 source of truth。 + 禁止把模型综合判断伪装成原始材料事实。 + 禁止在未标明推理性质的情况下输出确定性结论。 + 禁止在 source index 缺失时声明 lossless extraction。 + ``` + + --- + + #### 判断类型标记 + + 关键判断必须标明类型: + + ```text + source_fact:原文事实 + source_claim:原文主张 + inference:模型推理 + synthesis:综合归纳 + human_decision:人工裁决 + external_fact:外部事实 + assumption:假设 + ``` + + --- + + ### 6.5 分层评测栈 / Evaluation Stack + + 依靠单一准确率或相似度,无法测度专家级 Agentic 系统的真实抗压能力。 + + 系统必须部署从底层机械属性到顶层战略效用的多维探针。 + + --- + + #### E0 Smoke Test / 冒烟测试 + + 检验系统能否走通骨架。 + + ```text + 文件是否生成 + Tool Call 是否响应 + 目录是否正确 + 流程是否启动 + ``` + + --- + + #### E1 Format Test / 格式测试 + + 检验输出是否遵守: + + ```text + Schema + 长度预算 + 语言规范 + 命名规范 + 字段完整性 + ``` + + --- + + #### E2 Factual Test / 事实测试 + + 核查文本溯源保真度。 + + ```text + 是否编造事实 + 是否遗漏关键材料 + 是否错误引用 + 是否混淆来源 + ``` + + --- + + #### E3 Reasoning Test / 推理测试 + + 刺探逻辑链健壮性。 + + ```text + 假设是否暴露 + 推理是否闭合 + 反例是否处理 + 边界条件是否说明 + ``` + + --- + + #### E4 Expert Similarity / 专家相似度 + + 测度结论与人类专家判断的重合度。 + + 同时记录偏差部分是否可解释。 + + --- + + #### E5 Decision Utility / 决策效用 + + 验证系统是否真实帮助人类专家完成: + + ```text + 更优决策 + 更快判断 + 更低认知消耗 + 更低返工率 + 更稳风险控制 + ``` + + --- + + #### E6 Calibration Test / 校准测试 + + 评测系统纠错摩擦力。 + + ```text + 专家是否容易指出错误 + 系统是否能理解纠错 + 修复是否影响后续批处理 + 反馈是否进入评测集 + ``` + + --- + + #### E7 Governance Test / 治理测试 + + 审计视角终极测试。 + + ```text + trace 是否完整 + authority 是否隔离 + rollback 是否可行 + human gate 是否记录 + liability boundary 是否清晰 + data policy 是否合规 + ``` + + --- + + ### 6.6 按场景选择评测层级 + + ```text + Q 域查询:E0–E2 + 基础 P 域生产:E0–E3 + 生产工坊:E0–E5 + 专家辅助系统:E2–E6 + 战略透镜:E3–E7 + 治理级 Runtime:E0–E7 + ``` + + 不得用单一准确率评估战略透镜。 + 不得用“看起来不错”替代 E5 / E6 / E7。 + + --- + + ## 7. 开工清单与反模式 + + ## Start Checklist & Anti-patterns + + 本章用于将前述规则压缩为现场可执行动作。 + + --- + + ### 7.1 Agentic Project Start Checklist + + 每个 Agentic 项目开工前,必须回答: + + ```text + 1. 原始任务是什么? + 2. Q / P / I 定性是什么? + 3. 任务性质是什么:内容产出、系统建设、校准、探索? + 4. 启动档位是什么:Lite / Standard / Full? + 5. 最小充分产物是什么? + 6. 停止条件是什么? + 7. token / time / human attention 预算上限是什么? + 8. 是否涉及客户资料、密钥或敏感数据? + 9. 是否需要真实 Agent 调用? + 10. 若需要,Invocation Record 保存在哪里? + 11. 是否允许工具写入? + 12. 是否允许外部 API? + 13. Human Gate 在哪里? + 14. 谁是 decision_owner? + 15. 产物如何进入 Artifact Contract? + 16. 评测层级到 E 几? + 17. 是否需要 Source Fidelity? + 18. 是否需要 Rollback Protocol? + 19. 哪些平台插件允许自动触发? + 20. 什么时候触发 Scope Drift Review? + ``` + + 未完成清单,不得进入 Standard 或 Full 档。 + + --- + + ### 7.2 常见反模式 / Anti-patterns + + --- + + #### 1. Prompt 万能化 + + 把 Agent、Skill、Runtime、Model Card 全塞进一个巨型 Prompt。 + + 后果: + + ```text + 难维护 + 难评测 + 难复用 + 难追踪 + 难迁移 + ``` + + --- + + #### 2. 流程幻觉 + + 文件齐全,但真实 Agent 没有被调用。 + + 典型症状: + + ```text + 有 report + 有 dispatch pack + 有目录 + 有日志 + 但没有 Invocation Record + ``` + + --- + + #### 3. 治理过载 + + 一次性任务启用 Full Runtime。 + + 典型症状: + + ```text + 5 万字材料 + 3000 万 tokens + 大量 topic docs + 大量 audit + 大量 handoff + 核心产物 ROI 失真 + ``` + + --- + + #### 4. 成本混账 + + 把系统建设成本算成内容产出成本。 + + 典型症状: + + ```text + 用户只要一个结果 + 系统却建设了一个机器 + 最后把机器成本记到结果上 + ``` + + --- + + #### 5. 中间物繁殖 + + 核心产物未交付,系统不断生成: + + ```text + audit + routing log + handoff + repair note + review report + meta-analysis + ``` + + --- + + #### 6. 上下文倾倒 + + 把所有原始材料一股脑塞给所有 Agent。 + + 后果: + + ```text + 角色污染 + 判断失焦 + token 浪费 + source fidelity 降低 + ``` + + --- + + #### 7. 权限裸奔 + + 让能推理的 Agent 直接拥有: + + ```text + 写入权限 + 删除权限 + 发布权限 + 外部 API 权限 + 客户可见输出权限 + ``` + + --- + + #### 8. 无评测上线 + + 只凭“我觉得不错”进入生产。 + + 红线: + + ```text + 无 Evaluation Stack,不得声明 Production。 + ``` + + --- + + #### 9. 模拟污染 + + simulation-only 产物进入正式 synthesis。 + + 这是多 Agent 系统的根级污染。 + + --- + + #### 10. 黑盒校准 + + 系统输出错了,但专家不知道如何低成本纠正。 + + 症状: + + ```text + 没有 decision rationale + 没有 error category + 没有 feedback slot + 没有 repair plan + ``` + + --- + + #### 11. 插件篡权 + + 平台插件默认流程覆盖项目治理规则。 + + 症状: + + ```text + 自动开子线程 + 自动进入重型审查 + 自动生成无关目录 + 自动补全失败产物 + ``` + + --- + + #### 12. 停止权失效 + + 系统已经达到最小充分产物,却继续生产“看似有用”的附加物。 + + 红线: + + ```text + 系统不得因为还能生成,就继续生成。 + ``` + + --- + + ## 8. 附录:标准元数据模板 + + ## Appendix: Standard Metadata Templates + + --- + + ### 8.1 Invocation Record Template + + ```yaml + invocation_id: + runtime_id: + agent_id: + role_id: + canonical_prompt_path: + agent_spec_path: + carrier_type: + carrier_id: + thread_id: + input_context_path: + input_context_hash: + execution_timestamp: + returned_output_path: + returned_output_hash: + orchestrator_id: + entered_synthesis: false + human_gate_id_if_applicable: + status: + notes: + ``` + + --- + + ### 8.2 Simulation Metadata Template + + ```yaml + simulation_only: true + formal_output: false + excluded_from_synthesis: true + simulation_reason: + allowed_use: + created_by: + created_at: + must_not_enter: + - formal_synthesis + - customer_delivery + - model_card_source + - governance_audit + ``` + + --- + + ### 8.3 Human Gate Record Template + + ```yaml + decision_id: + gate_id: + decision_owner: + input_artifacts: + decision_options: + accepted_option: + rejected_options: + reason: + risk_notes: + downstream_effect: + reversibility: + rollback_condition: + timestamp: + ``` + + --- + + ### 8.4 Artifact Contract Template + + ```yaml + artifact_type: + status: + authority: + source_of_truth: + downstream_use: + invalidation_condition: + cost_class: + created_by: + created_at: + last_updated: + related_invocations: + related_human_gates: + related_sources: + ``` + + --- + + ### 8.5 Runtime State Transition Template + + ```yaml + runtime_id: + previous_state: + new_state: + trigger: + responsible_actor: + timestamp: + next_allowed_actions: + blocked_reason: + related_artifacts: + notes: + ``` + + --- + + ### 8.6 Cost Ledger Entry Template + + ```yaml + ledger_id: + task_id: + cost_class: + mode: + token_estimate: + token_actual: + time_spent: + tool_calls: + human_attention_minutes: + storage_used: + reason: + approved_by: + timestamp: + ``` + + --- + + ### 8.7 Repair Plan Template + + ```yaml + repair_id: + failure_type: + failure_location: + affected_artifacts: + impact_level: + repair_scope: + human_gate_required: false + reinvocation_required: false + rollback_required: false + new_budget_estimate: + repair_owner: + next_state: + ``` + + --- + + ## 9. 结语:现场纪律 + + Agentic 工程不是“让 AI 多干点”。 + + 它是把人类专家的判断、责任、隐性经验、材料处理、流程边界和工具权限,装入一台会高速运转的认知反应堆。 + + 因此,本手册的目的不是鼓励自动化,而是给自动化装上: + + ```text + 入口闸门 + 成本账本 + 权限阀门 + 防伪探针 + 状态仪表 + 数据隔离 + 评测探针 + 回滚绳索 + 绝对刹车 + ``` + + 系统越聪明,越要守规矩。 + 流程越丝滑,越要看后端废热。 + Agent 越能干,越不能让它裸奔。 + + **HiFi Agentic 工程的底线不是“自动完成”,而是:高保真、可校准、可追踪、可停止、可追责。** + +``` + +## 任务 + +**HiFi Agent Studio**是我们的开发方法论,**Agentic Engineering Handbook** 是方法论细化的Agentic手册。 + +我之前写了一稿**Agentic Engineering Handbook (V1.0)**,然后让ChatGPT优化了一稿——**Agentic Engineering Handbook (V1.1)** + +发现1.1版本格式上不够正式,且多有错误。 + +本次任务,是升级1.1版为1.2版,内容保持于1.1版完全一致,但是讲话风格、格式与1.0版一致。 + +## 指令 + +在具体执行**任务**前: +1. 有问题可以提出 +2. 考虑到1.1版内容比较长,一次性输出不太可能;为了避免信息压缩,需要你估算一下共需要输出几次; +3. 为了保持内容与1.1一致,风格口吻与1.0版一致,你可以为这个任务自己设置一些注意事项。 + +收到。对比 V1.0 与 V1.1 版本可以明显看出,ChatGPT 在生成 V1.1 时虽然扩充了操作细节(如新增了回滚机制、评测栈细化、附录等),但丢失了 V1.0 中极具张力和原则性的“重工业”工程口吻。它将大量严肃的条文碎片化,并滥用了代码块(````text`)来替代本应结构化的 Markdown 列表,导致文本不仅显得零碎,还削弱了守则应有的“冷酷”与“强制”感。 + +在正式开始执行 V1.2 的重写任务之前,我已完成对材料的解析,并按您的要求提供以下准备计划: + +### 1. 确认与提问 (Questions for Alignment) + +在开工前,我有两个细节需要与您最终确认: + +* **关于“滥用代码块”的修正**:V1.1 中将几乎所有的列举项(如红线、示例、组件清单)都放进了 `text` 代码块中。在 V1.2 中,我将把它们全部还原为 V1.0 风格的标准 Markdown 列表(使用 `*` 或 `-`)、引用块(`>`)或 Markdown 表格,以恢复文档的正式感。请确认这是否符合您的期望? +* **关于新增章节的整合**:V1.1 从原有的 4 章扩展到了 9 章(包含附录)。我会保留 V1.1 所有的物理章节结构、新增原则和具体指标(如 E0-E7 评测栈、四重账本的具体扩展),但会用 V1.0 的长句和高维隐喻(如“极压舱”、“物理防伪”、“降熵阈值”)将它们重新“焊接”成连贯的段落。 + +### 2. 输出次数估算 (Generation Phasing) + +由于 V1.1 的内容体量庞大,且本次重写需要注入高密度的工程隐喻和严谨的排版设计,为了绝对避免大模型在长文本输出时产生“信息压缩”或“格式疲劳(尾部质量下降)”,我建议将 V1.2 版本的输出分为 **4 个批次(Parts)** 进行: + +* **Part 1:** 核心共识与入口管线(包含:Profile、0. 守则定位与绝对边界、1. 任务入口与档位挂载) +* **Part 2:** 资源控制与物理防伪(包含:2. 成本隔离与防蔓延机制、3. 物理防伪与绝对制动、4. 权限、安全与副作用控制) +* **Part 3:** 运行兜底与基建标准(包含:5. 运行修复与回滚、6. 通用运行组件与资产标准) +* **Part 4:** 现场收敛与附录基座(包含:7. 开工清单与反模式、8. 附录:标准元数据模板、9. 结语:现场纪律) + +### 3. 重写注意事项与自我约束 (Execution Guidelines) + +在接下来的每一次输出中,我将严格挂载并遵守以下内部规程(如同手册中要求的“档位挂载”): + +* **词汇表对齐 (Vocabulary Fidelity)**:全面恢复 V1.0 的核心语境体系。强制使用“物理咬合”、“冷酷的工程界桩”、“失控与灾难”、“算力暴走”、“降熵”、“高保真”、“熔断”等具有物理厚度与机械感的词汇,拒绝使用大模型惯用的平庸过渡词。 +* **结构化克制 (Formatting Discipline)**:杜绝 V1.1 中过度松散的单句成段现象。通过加粗(``)提炼核心论点,使用清晰的层级标题(`###` 和 `####`)构建逻辑树。表格必须用于对比,列表必须用于并列项。 +* **情绪与口吻 (Tone Target)**:保持“架构裁决者”的冷峻与不容置疑。这不是一份供人商榷的建议书,而是防范系统灾难的物理断电说明书。规则陈述必须使用“必须”、“严禁”、“绝对禁止”等最高阶强制性动词。 +* **零信息损耗 (Lossless Translation)**:V1.1 中新增的所有技术字段(如 `invocation_id`、状态机的各个 status、E0-E7 评测清单)必须一字不落地保留并嵌入到 V1.2 的正规格式中。 + +--- + +如果上述计划与您的预期一致,我们随时可以挂载“Part 1”的输出档位。是否现在开始生成 **Part 1 (第 0 章与第 1 章)**? + +# 2 + +* **关于“滥用代码块”的修正**:V1.1 中将几乎所有的列举项(如红线、示例、组件清单)都放进了 `text` 代码块中。在 V1.2 中,我将把它们全部还原为 V1.0 风格的标准 Markdown 列表(使用 `*` 或 `-`)、引用块(`>`)或 Markdown 表格,以恢复文档的正式感。请确认这是否符合您的期望? + * 是的,我正是这个意思。 +* **关于新增章节的整合**:V1.1 从原有的 4 章扩展到了 9 章(包含附录)。我会保留 V1.1 所有的物理章节结构、新增原则和具体指标(如 E0-E7 评测栈、四重账本的具体扩展),但会用 V1.0 的长句和高维隐喻(如“极压舱”、“物理防伪”、“降熵阈值”)将它们重新“焊接”成连贯的段落。 + * 1.0版和方法论是从我的散文系列中抽取出来的,我的散文用了大量隐喻,所以保持了隐喻的特征。但是考虑到handbook是给工程师用的,不是文学作品,所以我倾向于尽量少的隐喻。 + * 总结为: + * 保留1.1的章节结构、新增原则和具体指标; + * 用长句; + * 用说明文形式,减少隐喻; + * 目标受众是开发工程师,可以用技术词汇/概念,技术用语无需解释。 + +所以,**重写注意事项与自我约束** 部分需要基于我的回复进行修订。 + +--- + +然后没有其他问题,就可以开始第一次的输出。 + +明白。我已经根据您的要求对**内部执行规程**进行了修正:剥离过度的文学隐喻,转向严肃、精准的说明文体与架构师视角,使用长句构建严密的逻辑链路,保留所有的运行时指标与字段设定,并将 V1.1 中滥用的代码块全部降级为标准的 Markdown 列表与引用结构。 + +以下是 **Part 1** 的输出(包含 Profile、第0章与第1章)。 + +--- + +# Agentic Engineering Handbook (V1.2) + +*HiFi Agent Studio 运行治理与现场规程* + +## Profile + +* **author**: Wantsong +* **version**: V1.2 +* **date**: 2026-06-15 +* **status**: active-candidate +* **governing doctrine**: HiFi Agent Studio +* **related system**: CCPE System / Knowledge Vault / Writing Workbench / Video Workbench + +--- + +## 0. 守则定位与绝对边界 + +本手册定义了团队在 Agentic 工程实战中的操作底线与运行时规程。它将 HiFi Agent Studio 的高维架构设计转化为开发工程师在现场可执行的工程界桩,聚焦于规范化系统的生命周期管理,具体解决包括任务分诊、并发限流、调用链路追踪、执行防伪、权限沙箱管控、状态机熔断、异常回滚以及验收标准在内的核心工程链路问题,从而避免系统在缺乏约束的环境下发生不可控的自我繁衍。 + +### 0.1 守则效力 + +本手册服从并承载 HiFi Agent Studio 的核心纲领,同时作为一切局部 Agentic 项目的硬性行动准则。当系统在实际运行中发生规则冲突时,所有执行组件与人类专家必须遵循以下优先级序列进行裁决: + +1. 客户法理与商业硬性约束 +2. HiFi Agent Studio 宪法原则 +3. **本 Agentic Engineering Handbook** +4. CCPE System 资产建造规范 +5. 具体项目 Runbook +6. 平台、插件或底层工具的默认行为 + +> **注意**:若底层自动化框架、平台插件或引入的 Skill Pack 的默认执行行为与本手册发生冲突,必须强制阻断其默认行为并以本手册的约束为准。 + +### 0.2 反向兜底 + +任何底层自动化框架(如 Codex、Claude Code、OpenClaw、SuperPowers 等)或 Agentic Runtime 在运行过程中,如果展现出遇错无限重试、自动化子线程繁衍、无监管地扩展目录结构、静默补全缺失产物、自动拉起重型评审流程、调用超纲高权限工具或将模拟态输出包装为正式结果的倾向,系统必须立即挂起当前进程并向上抛出异常以请求架构裁决。开发人员严禁为了迎合底层工具的调用便利性,而对执行真实性、最小权限原则、成本分账、绝对停止权、人工决策门(Human Gate)、来源保真、数据安全以及责任边界等治理底线做出任何妥协或让步。 + +### 0.3 模拟与正式执行的边界 + +在系统的绿野仙踪(Wizard of Oz)阶段,允许人类专家、主控节点或单一模型以模拟 Agent 的形式低成本验证业务的价值流转。然而,所有在非真实隔离沙箱中产生的模拟产物,必须在元数据中强制注入 `simulation_only: true`、`formal_output: false` 以及 `excluded_from_synthesis: true` 标签。此类模拟产物仅被允许用作价值预演、流程草图验证或人工参考,绝对禁止其冒充正式的多智能体执行产物进入下游生产决策链,正式运行阶段的系统必须具备完整的真实调用记录(Invocation Record)。 + +--- + +## 1. 任务入口与档位挂载 (Project Intake & Mode Selector) + +在 Agentic 并发管线中,算力消耗的失控与架构治理的灾难通常源于系统入口处的任务定性溃败。在创建第一个 Thread、调用第一个 Skill 或启动任何底层 Worker 之前,架构师与开发人员必须在操作面板上完成结构化的强制分诊。 + +### 1.1 QPI 强制分诊 + +所有业务需求接管的第一时间必须进行问题颗粒度的物理探测,系统严禁在含糊其辞的状态下进行调度尝试。 + +* **【Q】查询 (Question)**:其核心匮乏在于数据或信息的缺失。该场景具有线性因果特征,存在明确的答案或可查询的事实(如提取特定材料中的指标、确认文件路径或定义)。系统应直接采用搜索、检索增强生成(RAG)、数据库查询或工具 API 填补信息缺口,采用单节点调用架构。绝对禁止为 Q 域任务编排复杂的多体流程,或为其启动覆盖率审计与治理级 Runtime。 +* **【P】求解 (Problem)**:其核心匮乏在于实现路径的缺失。此类场景目标明确,但需要经过工程化的转换、拆解、生产或优化(如长文转分镜、批量生成配音稿、素材蒸馏或标准化报告初稿)。架构复杂性应优先倾注于稳定吞吐量、低返工率、可验证输出、上下文压缩与批处理效率,采用标准作业程序(SOP)、模板化约束与人工抽检结合的生产工坊模式,而非引入不必要的多角色治理。 +* **【I】治理 (Issue)**:其核心匮乏在于秩序、共识与责任边界的缺失。该场景通常无唯一最优解,存在隐蔽变量、多方权衡、非遍历性风险或可能触发单向门决策的业务节点(如核心立意判定、重大客户方案取舍、战略级评审或高风险决策辅助)。系统的架构复杂性必须全部倾注于保真度、责任锚定、多视角张力、审计可追踪性与反例处理,强制要求配置战略透镜、人机回环、预设委员会与权限阻断机制,绝不允许利用高并发的算力来掩盖判断逻辑本身的脆弱性。 + +### 1.2 任务性质定性 + +在完成 QPI 定性后,必须明确当前操作的终极标的,因为同一个表层的业务任务可能归属于完全不同的工程性质。 + +* **一次性内容产出**:系统运行的唯一目的是获取当前的单一结果材料(例如整理一篇 5 万字的讨论稿、生成单个视频分镜或提取会议纪要)。此类任务默认要求挂载 Lite 档,聚焦于交付最小充分产物并保持轻量记录,严禁系统自动升级为重工业的 Runtime 建设。 +* **可复用能力沉淀**:系统运行的目的是为了提炼可跨越项目周期复用的资产(例如将某种提炼方法沉淀为 Skill、将专家判断结构沉淀为 Model Card,或将旧 Prompt 升级为 CCPE-Lite)。此类任务默认要求挂载 Standard 档,强制要求输出资产合约并进行局部评测,同时需明确下游的消费场景。 +* **治理级系统建设**:系统运行的目的是构建一套可长久运行、支持审计追责与异常恢复的底层基座或工作台(例如多 Agent 写作评审 Runtime、知识加工园区或高风险决策辅助系统)。此类任务具有 Full 档候选资格,要求强制挂载完整的权限矩阵、状态机协议(Runtime State Protocol)、全链路评估栈(Evaluation Stack)与灾难回滚协议。 +* **校准与评测任务**:系统运行的目的在于修正模型偏差、构建标准化评测集、记录专家反馈以对齐判断边界(例如收集专家修改痕迹、构建 100 道标准评测题或建立返工率基线)。此类任务的资源消耗必须计入校准账本(Calibration Cost),并严格遵守过程数据授权规范与专家注意力预算限制。 +* **探索预演任务**:系统运行的目的是为了验证新范式、新工具、外部平台调用链路或新型协作拓扑的边界(例如测试 Codex Thread 能否作为真实的 Agent 载体)。此类操作的消耗必须计入探索账本(Exploration Cost),严禁将其伪装为生产任务并对外承诺稳定交付,且必须详细记录失败边界。 + +### 1.3 铁律:任务性质不得暗中变轨 + +开发人员必须保持高度的运行时边界感知。如果原始目标仅为提炼一篇 5 万字的文稿,系统在执行过程中绝不能私自衍生出复杂的通用 Protocol、知识加工园区、全量多 Agent 治理 Runtime 或长期下游交接协议。一旦监控探针发现任务从单次内容产出向系统基建滑移,必须立即挂起进程并触发范围漂移审查(Scope Drift Review)。 + +### 1.4 档位挂载 (Mode Selector) + +系统执行必须遵循“默认轻量,证据驱动升级”的原则。系统的物理操作杆在初始化启动时,必须且只能挂载在 Lite 档。除非出现明确的硬性升级证据,否则严禁凭借开发者的架构审美、算法崇拜或底层工具的自动化惯性擅自提升运行档位。 + +* **Lite 档(默认启动)** +* **适用边界**:适用于一次性任务、低法理风险、单源或少量源材料输入、源材料体积能够被单个高上下文模型完整吞吐,且下游不依赖完整过程审计的场景。 +* **控制策略**:采用单模型或单主控的极简闭环,允许调用局部 Skill 或基础工具。系统不默认唤醒独立的多智能体沙箱,不构建厚重的交接包(Handoff),不执行无损覆盖率审计,亦不生成治理级日志。 +* **核心产物**:目标输出文件、极简的输入记录以及关键人工确认点(必要时包含抽样检查记录)。 + + +* **Standard 档(证据驱动升级)** +* **升级证据**:处理多源异构材料、存在明确的下游自动化消费依赖、用户显式指令要求进行复用资产沉淀,或业务流中存在局部追踪与复盘的需求,从而需要进行少量的真实 Agent 或 Worker 调用。 +* **控制策略**:强制引入结构化的上下文编译机制(Context Compiler)限制幻觉,允许拉起有限的真实沙箱调用,建立局部的调用证据链(Invocation Record),输出可复用资产合约与关键决策门(Human Gate)。 +* **核心产物**:源映射包(Source Pack)、结构化上下文补给包(Context Pack)、可复用资产单元、局部追踪日志、决策记录以及最终目标文件。 + + +* **Full 档(极限治理)** +* **升级证据**:应对试错即单向门的高法理风险商业决策、外部客户的关键交付、需要多角色形成独立张力对撞的长期运行 Runtime、包含不可逆的工具执行动作或具备强烈覆盖审计需求的生产环境自动化任务。 +* **控制策略**:必须由人工显式授权启动。强制拉起全规格的多智能体编排,挂载严密的权力矩阵(Authority Matrix)、不可篡改的底层调用证据链、全量运行时状态协议(Runtime State Protocol)、风险控制与数据安全策略,并强制包含灾难回滚预案。 +* **核心产物**:完整的 Runtime 机器状态、追加写入(Append-only)的真实调用日志、失真与风险日志、覆盖率评测报告、具备极高防御性的下游交接包以及灾难恢复计划。 + + + +### 1.5 预算合约 (Budget Contract) + +任何 Agentic Runtime 在启动前必须显式声明其执行预算合约。预算不仅包括传统的 Token 消耗,还必须统筹时间跨度、存储资源、工具调用频次以及专家注意力的支出限额。合约必须声明 `source_size_estimate`、`target_mode`、`token_budget`、`time_budget`、`human_attention_budget`、`tool_call_budget`、`escalation_threshold` 与 `abort_threshold` 等关键阈值。通常情况下的默认 Token 预算倍率为:Lite 档限制在源输入 Token 的 10-30 倍内;Standard 档限制在 30-100 倍内;Full 档超过 100 倍且上不封顶,但必须具备充分的治理理由并取得架构级人工授权。若系统预估当前任务消耗将超过所在档位的预算上限,必须立即挂起进程并请求升级授权,严禁静默穿透预算继续运行。 + +### 1.6 组件启用矩阵 + +在进行系统架构设计与现场实施时,开发人员必须严格参照以下功能组件的启用矩阵,以匹配对应的运行档位: + +| 组件配置项 | Lite 档位 | Standard 档位 | Full 档位 | +| --- | --- | --- | --- | +| **QPI Intake** | 强制执行 | 强制执行 | 强制执行 | +| **Task Nature Classification** | 强制执行 | 强制执行 | 强制执行 | +| **Cost Ledger (成本核算)** | 轻量简版 | 强制完整 | 强制完整 | +| **Budget Contract (预算合约)** | 轻量简版 | 强制完整 | 强制完整 | +| **Scope Drift Detection** | 强制执行 | 强制执行 | 强制执行 | +| **Stop Rule (绝对制动)** | 强制执行 | 强制执行 | 强制执行 | +| **Human Gate (决策门)** | 关键节点可选 | 强制引入 | 强制多层引入 | +| **Invocation Record** | 仅发生真实调用时必须 | 强制引入 | 全链路强制引入 | +| **Simulation Labeling** | 强制执行 | 强制执行 | 强制执行 | +| **Context Compiler** | 轻量简版 | 强制完整 | 强制全规格引入 | +| **Authority Matrix (权限矩阵)** | 视需可选 | 强制引入 | 强制引入 | +| **Artifact Contract (产物合约)** | 轻量简版 | 强制完整 | 强制完整 | +| **Runtime State Protocol** | 轻量简版 | 强制完整 | 强制完整 | +| **Tool Safety (工具安全)** | 存在工具调用时必须 | 强制执行 | 极高规格强制 | +| **Data Security (数据安全)** | 存在敏感数据时必须 | 强制执行 | 极高规格强制 | +| **Evaluation Stack (评测栈)** | 覆盖 E0 - E2 | 覆盖 E0 - E5 | 覆盖 E0 - E7 | +| **Rollback Protocol (回滚协议)** | 存在写入操作时必须 | 强制引入 | 强制引入 | +| **Governance Audit (治理审计)** | **绝对禁止默认启用** | 针对性定点审计 | 全量覆盖审计 | + +# 3 + +继续下一次的输出。 + +## 2. 成本隔离与防蔓延机制 (Cost Ledger & Scope Drift) + +在 Agentic 自动化管线中,最致命的工程失控往往并非由显性的报错或崩溃引起,而是系统在缺乏强力监督的状态下暗中无休止地运转,将一次简单的内容提取任务异化为庞大的系统基建。为了在运行态夺回对计算资源和专家注意力的绝对控制权,架构师必须在系统底盘强制焊死成本核算与边界探测组件。 + +### 2.1 四重消耗账本 (Cost Ledger) + +为了破除算力消耗的混沌状态并建立极度清晰的资源归因机制,任何 Agentic 工作流在启动时,其消耗的所有 Token、算时、存储、工具调用次数以及人工注意力资源,必须被强制记入以下四个物理隔离的账本之一: + +* **Content Cost (内容产出成本)**:为完成当前用户指派的直接任务所消耗的核心计算与调用资源。此类消耗仅限于直接输出目标物料的操作(例如:蒸馏一篇讨论材料、转译一份视频分镜、生成一份口播稿、提取会议纪要或输出客户报告初稿)。 +* **System-Building Cost (系统建设成本)**:为设计、搭建、扩展或重构系统底层运行能力与长期资产所消耗的资源。当系统行为涉及构建 Agent、Skill、Runtime、Protocol、评估标准(Evaluation)、工具链、业务流(Workflow)、模型索引(Model Index)、工程目录树以及定义调用标准时,其消耗必须划拨至本账本(例如:为了蒸馏单篇讨论稿而设计一个通用的知识加工 Runtime,或为了一次评审任务而重构多智能体交接协议)。 +* **Calibration Cost (校准修复成本)**:为纠正底层模型偏差、记录人工反馈轨迹、对齐专家判断边界以及构建标准评测集所支出的资源。此类任务包括分析 AI 与人类专家判断的差异、收集专家层面的修改痕迹、构建基于真实业务的高质量评测集、调整 Agent 的错误分类规则,以及建立系统整体的返工率基线指标。 +* **Exploration Cost (探索预演成本)**:为了在业务沙盘中验证新范式、新工具、新平台调用链路或新型协作拓扑结构所消耗的实验性资源。此类任务包括测试特定框架(如 Codex Thread、Claude Code Subagent、SuperPowers 或 OpenClaw)的流程承载力与能力边界,严禁将此类试探性消耗伪装为对客的生产任务。 + +### 2.2 记账核算铁律 + +系统绝对禁止将构建自动化流程的“系统建设成本”掩饰、打包或伪装为单次任务的“内容产出成本”。如果在执行一次基础任务的过程中,实际发生了诸如设计新 Runtime、编写通用通信 Protocol、创建新 Agent 或 Skill、构建评测栈或搭建长效资产的操作,这些超额消耗必须进行账务剥离。系统架构的重工业投入必须光明正大地记录在基建账本中,以接受长周期的投资回报率(ROI)审查。 + +### 2.3 漂移探测触发 (Scope Drift Detection) + +由于大语言模型(LLM)内置了强烈的规划、反思与逻辑补完惯性,一个轻量级的求解任务(P 域)极易在无监督状态下滑向包含多方审计与治理逻辑的深水区(I 域)。系统必须在各个管线节点埋设结构化的漂移探针,一旦捕捉到以下五类越界信号,即刻判定系统发生了任务蔓延(Scope Drift): + +* **信号一(基建过度行为)**:一个被预设定性为一次性(One-off)的任务,开始私自创建通用的流转 Protocol、设计预期复用的复杂目录树、撰写与当前直接产出无关的抽象规则文档、衍生出新的 Agent 或 Skill 节点,甚至企图升级为长效工作台。 +* **信号二(并发无序扩张)**:原定被束缚在 Lite 档运行的极简闭环流程,开始擅自派发多个底层 Worker、拉起多角色审查委员会、开启并行覆盖率审计、创建多个子会话(Sub-session),或执行未经授权的动态智能体路由规划。 +* **信号三(产物交付延宕)**:用户明确期待的核心业务产物迟迟未能交付,但系统的高昂资源已被大量倾注并消耗于生成路由日志、覆盖率审计报告、厚重的交接包、评审报告、修复协议、目录脚手架生成或无价值的元分析文档中。 +* **信号四(预算穿透警告)**:系统当前已发生或预估即将发生的消耗,超出了原定预算的硬性阈值且未进行主动分账申报。默认的触发条件为:Lite 档消耗超过源输入 Token 数量的 30 倍,Standard 档消耗超过源输入 Token 数量的 100 倍,或任一单一任务消耗的专家注意力超过了预设的 `human_attention_budget`。 +* **信号五(成功标准变更)**:系统的执行目标从单纯的“完成并交付一个业务结果”暗中演变为“定义并构建一套未来如何持续完成该类结果的系统机制”,这标志着任务性质已由内容产出彻底滑入系统建设领域。 + +### 2.4 漂移处置协议 (Drift Resolution Protocol) + +一旦上述漂移探测器被触发,系统必须立刻抛弃“顺其自然”的自动化运行惯性,强制执行以下阻断与人工介入动作: + +1. **挂起进程**:立即阻断当前 Agentic Runtime 的持续执行与自我繁衍能力,强制将进程状态锁定并切换为 `paused_by_scope_review`。 +2. **核心发问与重定性**:系统必须向人类控制台抛出审计质询:我们当前是否仍在执行原始的内容产出任务?如果不是,是否需要将当前衍生出的操作正式立项为系统建设任务?当前已溢出的消耗应当记入哪一本成本账?系统的运行档位(Lite/Standard/Full)是否需要进行升级调整?原始的核心任务是否仍需优先保证交付? +3. **物理分账与重启**:若经人工确认任务已发生性质变轨,必须重新进行 QPI 矩阵定性,并将此前及后续规划的超额计算消耗从内容产出账本中物理切断,强制划拨至系统建设、校准修复或探索预演账本中。 +4. **人工授权释放**:只有在严格完成重新 QPI 定性、重新挂载 Mode Selector、更新 Budget Contract、重置 Stop Rule 阈值并生成完整的决策操作记录(Human Decision Record)后,系统方可解除挂起状态继续运行。 + +--- + +## 3. 物理防伪与绝对制动 (Execution Authenticity & Stop Rule) + +在缺乏硬性物理约束的 Agentic 环境中,系统极易陷入两种致命的工程灾难:一是主节点伪造子节点工作过程的“流程幻觉”;二是子节点为了证明自身算力工作量而无限繁衍中间产物的“过度执行”。本章确立的机制旨在为自动化管线装配不可篡改的测谎探针与强力的物理断电开关。 + +### 3.1 执行真实性与主控阻断 (Execution Authenticity) + +多智能体架构的真正防御力与逻辑价值,来源于不同思维模型在绝对隔离的沙箱中产生的真实逻辑张力与视角碰撞,而非依赖单一高参数模型在同一上下文中进行的自问自答式文本模拟。系统必须对所有正式产物执行严苛的代码级测谎。 + +**主控越权阻断**:在多体编排中,主会话或 Orchestrator 仅被赋予调度、路由、聚合综合、状态记录、有限验证与人工确认转译的权限。绝对禁止主控节点凭借自身庞大的上下文吞吐能力去强行“代写”或模拟任何底层子节点的输出结果。若系统在运行中无法成功拉起真实的子线程、外部参与者或载体沙箱,进程必须挂起并进入 `blocked_waiting_for_participant_output` 状态,严禁主控节点用伪造的执行报告填补业务流程中的信息真空。 + +### 3.2 真实调用证据链 (Invocation Record) + +任何被系统声明为由独立 Agent、Reviewer、Worker、Auditor、Committee Member 或 External Participant 产出的正式业务报告或决策,必须向控制台出具完整、真实的底层调用证据链。最小规格的 Invocation Record 必须毫无遗漏地包含以下物理字段: + +* `invocation_id` +* `agent_id` 或 `role_id` +* `canonical_prompt_path` 或 `agent_spec_path` +* `runtime_id` +* `carrier_type` +* `carrier_id` / `thread_id` / `sub_session_id` +* `input_context_path` +* `input_context_hash` +* `execution_timestamp` +* `returned_output_path` +* `returned_output_hash` +* `orchestrator_id` +* `entered_synthesis` (布尔值) +* `human_gate_id_if_applicable` + +### 3.3 模拟标记与沙箱隔离 (Simulation Labeling) + +当系统因部署环境限制、外部接口调用失败、人类手动干预,或仅为流程占位而产生了一批缺乏底层真实物理咬合的“伪执行”产物时,必须立即对该类产物实施冷酷的资产隔离,以防止其污染整个业务决策链。所有此类模拟产物的元数据中必须强制注入耻辱烙印标签:`simulation_only: true`、`formal_output: false` 以及 `excluded_from_synthesis: true`。同时,系统还需声明其 `simulation_reason`(模拟原因)与 `allowed_use`(允许用途)。 + +带有上述标签的隔离产物仅被允许用于价值流转预演、人工参考草稿、流程设计样例或绿野仙踪协议的初步验证。它们被绝对禁止参与正式的逻辑综合(Synthesis),严禁用于客户可见阶段的交付,且不得作为下游自动化节点的行动依据、模型沉淀依据或法理审计依据。 + +### 3.4 最小充分阈值与前置设定 (Minimum Sufficient Threshold) + +为了防止系统在后台像细胞增殖般无限制造中间物,任何一个 Runtime 在启动挂挡前,必须与人类专家确立一份不可逾越的“验收合约”,明确系统的降熵阈值。 + +* **Minimum Viable Output**:明确定义为了满足下游逻辑的顺利消费,当前任务必须交付的最核心、最低限度的信息量是什么(例如:明确只需视频总纲与分镜骨架,不需要扩写详细的配音稿;或只需 Topic Map 与可复用物料单元,不需要拉起完整的覆盖率审计)。 +* **Sufficient Criteria**:确立何种状态即被系统判定为“已完全达标”。一旦跨越该阈值,预设的 `optional_artifacts` 将默认被系统彻底剥夺生成权限,除非获得人类专家的显式复苏授权。 +* **前置参数绑定**:合约必须绑定 `forbidden_artifacts`(禁止生成的产物清单)、`human_gate_points`(人工决策拦截点)、`budget_limit`(预算红线)以及不可修改的 `stop_condition`(停止条件)。 + +### 3.5 人工决策门合约 (Human Gate Contract) + +“人机回环(Human-in-the-loop)”绝不是一句口号,而是系统中不可逃避的责任坐标。系统禁止在代码中设置毫无约束的空洞“人工确认”节点。每个设立的 Human Gate 必须预先显式声明其合约参数,包括:`gate_id`、`decision_owner`、`input_artifacts`、`decision_options`、`default_action`、`downstream_effect`、`reversibility`、`escalation_condition`、`record_path` 以及 `timeout_policy`。 + +**决策记录输出规范**:当人类专家完成介入裁决后,系统生成的反馈记录日志至少且必须包含以下追溯字段:`decision_id`、`gate_id`、`decision_owner`、`accepted_option`、`rejected_options`、`reason`、`risk_notes`、`downstream_effect`、`rollback_condition` 以及操作发生的 `timestamp`。 + +### 3.6 运行状态机协议 (Runtime State Protocol) + +为了确保复杂管线的透明度与可追责性,所有投入运行的 Runtime 必须且只能在标准定义的有限状态机内进行流转。标准状态集包括:`initialized`、`running`、`blocked_waiting_for_human`、`blocked_waiting_for_participant_output`、`blocked_waiting_for_tool`、`paused_by_scope_review`、`paused_by_budget_guard`、`failed_recoverable`、`failed_terminal`、`completed`、`aborted_by_human` 以及 `archived`。每次状态发生物理跃迁时,必须完整记录 `previous_state`、`new_state`、`trigger`、`responsible_actor`、`timestamp` 以及约束下一步操作的 `next_allowed_actions`。 + +### 3.7 绝对停止权与熔断机制 (Stop Rule) + +在 Agentic 架构的高并发极压舱内,人类意志的最高工程体现不在于如何一键启动复杂的自动化管线,而在于何时能够决绝地踩下刹车。停止权是系统免于因追求冗余完美主义而耗尽资源的最后防线。 + +**触发条件**:一旦核心传感器捕捉到以下任何一种状态,系统必须触发无条件的熔断:产出物已触及“最小充分阈值”;运行流触及预设的人工决策门(Human Gate);预算消耗逼近 `abort_threshold` 红线;探针捕获到范围漂移(Scope Drift);底层真实调用记录失效;系统工具执行权限越界;数据安全隔离边界出现模糊;或信息来源的保真度已无法通过验证。 + +**制动执行动作**:触发制动后,系统将无视底层 Worker 是否仍在排队执行或生成附加参考报告。系统必须停止创建新任务,取消队列中尚未启动的任务,对正在运行的线程发出协作取消(Cooperative Cancellation)指令。对于无法响应协作指令的非关键增殖线程,系统有权执行代码级的强制终止。终止动作执行前,系统必须尽最大可能保存当前的 `partial_outputs`、`state_snapshot`、`action_log`、`unfinished_tasks` 与 `risk_notes`,并最终强制将所有核心进程锁定为 `blocked_waiting_for_human`。 + +--- + +## 4. 权限、安全与副作用控制 (Authority, Tool Safety & Data Security) + +多智能体系统真正对物理与商业世界构成威胁的地方,并不在于其逻辑推理的误差,而在于其执行物理副作用(如写入、删除、调用外部 API)的能力。因此,所有的工具调用权限、文件系统覆盖、对外数据交互及客户可见输出,都必须被强制囚禁于严密的权限矩阵与副作用隔离层中。 + +### 4.1 权力矩阵 (Authority Matrix) + +为了防止底层节点擅自覆写核心产物或盲目调用高危接口,系统必须为每一个 Agent、Skill 或 Runtime Node 在代码级焊死其物理权限等级: + +* **A0 Observe (观察)**:最低权限。节点仅拥有基础读取权限,可生成内部标记与逻辑标注,绝对无权修改任何对下游可见的状态或文件。 +* **A1 Suggest (建议)**:建议权限。允许节点输出分析结论与优化方案,但其产物处于物理隔离状态,不能直接覆写任何正式产物,仅供高阶决策节点作为参考依据。 +* **A2 Draft (起草)**:起草权限。被授权生成初稿形态的物料,但该物料在状态机流转中被强制挂起拦截,必须经由人工决策门(Human Gate)或具备对应权限的 Owner Agent 显式签发后,方可进入正式流转链。 +* **A3 Modify (修改)**:受限覆写权限。允许在预设的上下文边界内修改正式产物,但必须严格限定并审查 `allowed_paths`、`allowed_files`、`allowed_fields`、`modification_scope`,并提前铺设 `rollback_path`。 +* **A4 Decide (裁决)**:结构性决策权。行使该权力时,系统强制要求执行节点同步输出包含逻辑归因的 `decision record`、`decision rationale`、`risk notes` 以及对其 `downstream effect` 的预判。 +* **A5 Execute (执行)**:物理动作权限。该权限必须被强制细分为三个相互独立的子级沙箱: +* **A5-R (Read Tool)**:只读工具调用。允许系统执行网络搜索、读取本地文件、执行无害的数据库查询、查看系统日志或读取流转状态。 +* **A5-W (Write Tool)**:写入动作执行。允许系统写文件、改代码、更新配置、生成并保存底层资产。该权限必须满足严格的允许路径检查,并留存变更日志与 Diff,支持无损回滚策略。 +* **A5-X (External Action)**:高危外部动作。允许系统发送消息、发布内容、调用客户业务 API、执行支付指令、删除远程资源或修改对客可见状态。此类权限默认对所有 Agent 关闭,绝不允许自动执行,必须经过 Human Gate 签发或 Runtime 级别的高密级明确授权。 + + +* **A6 Block (阻断)**:最高优先级的系统熔断权限。一旦触发该权限(例如探针发现严重逻辑悖论、面临法理追责风险、数据泄漏报警或预算穿透),系统全线进程将立刻挂起阻断,并强制召唤人类专家介入。 + +### 4.2 最小权限原则与副作用隔离 + +系统的底层核心逻辑必须遵循“最小权限原则(Least Privilege)”。Agent 所拥有的工具执行权限必须永远小于其语言推理能力——能进行逻辑推演不代表能实施写入;能理解任务目标绝不代表系统应该向其开放工程的全局目录修改权。严禁将全量写入权限、外部 API 调用或内容发布能力作为默认配置授予通用推理 Agent。 + +任何具备写入(A5-W)或外部执行(A5-X)能力的 Agent,必须被置于副作用隔离机制(Side-effect Isolation)之中。执行动作前,必须强制声明 `allowed_paths` 与 `forbidden_paths`,在可能的情况下优先执行 `dry-run` 预览;执行高危动作前必须先生成并提交 `action plan`,执行完毕后生成全量 `action log`,并确保相关动作具备人工二次确认门禁或一键恢复机制。 + +### 4.3 数据分级、密钥纪律与外发红线 + +系统必须为所有灌入的输入材料进行显性的数据等级标记,包括公开材料(Public)、内部材料(Internal)、包含客户商业利益的机密数据(Confidential),以及包含个人隐私、财务或法律代码的极敏感数据(Sensitive)。不同的数据等级将直接触发底层路由拦截器,决定该段材料是否允许被传出至外部云端模型、是否需要强制脱敏,以及是否允许留存长期日志或被用于后续的模型微调。 + +**密钥纪律(Secrets Discipline)**:系统极其严厉地禁止任何 Agent 或 Skill 将 API Key、Token、安全凭证等密钥写入明文 Prompt 中;禁止将其存入常规日志或上下文补给包(Context Pack)中;禁止主节点将其暴露给无需该执行权限的次级 Worker。所有密钥必须通过高安全的独立环境变量层或平台专有授权通道进行无感传递。 + +**数据外发红线**:在调用任何外部大模型、外部工具 API 或多模态生成服务前,系统必须执行阻断审查。若无法明确确认当前上下文数据是否被允许外发、是否含有需脱敏的客户及个人信息,或无法确认第三方服务提供商的日志留存与二次训练规则,则系统必须默认切断该外部连接的调用授权。 + +### 4.4 过程数据主权与平台治理限制 + +在人机共创的过程中,专家留下的每一次局部修改痕迹、逻辑反驳意见、操作过程中的犹豫停留或编辑轨迹,都是极具价值的领域知识资产,同时也是高度敏感的商业业务数据。系统在采集此类隐性遥测数据时,必须提供明确的采集授权、严格的用途边界、隔离存储规范以及一键清除机制。严禁系统以“自我学习与智能进化”的名义,默认吞噬、劫持专家的隐性经验或客户的垂直业务场景数据。 + +最后,任何外部运行平台、自动化框架或第三方插件的默认调度行为,在物理层面均不具备覆盖本《Agentic Engineering Handbook》的合法效力。如果开发过程中引入的某项辅助插件存在自动跨界开启子线程、自动触发重型安全审查或静默生成大量补全产物的倾向,系统控制权必须立即上交至人工控制台。所有的插件生成结果,在通过严苛的产物合约(Artifact Contract)、证据链核验(Execution Authenticity)与人工决策门(Human Gate)的检视前,绝不能直接跃升为系统的正式业务产物。 + +# 4 + +继续下一次的输出。 + +## 5. 运行修复与回滚 (Retry, Repair & Rollback) + +在 Agentic 系统的极压舱中,局部的调用失败并不致命;真正构成系统性风险的,是毫无节制的无限重试、试图掩盖错误的静默修补、偏离原意的迭代变异,以及缺乏后路的不可回滚动作。 + +### 5.1 重试上限与熔断 (Retry Limits) + +任何由自动化流程发起的异常重试动作必须被强行施加物理上限。默认的重试红线规定如下:面对工具调用失败、输出格式错误或网络与外部 API 的临时性阻断,系统最多仅允许发起两次自动重试;面对权限申请失败或调用越界,系统绝对禁止尝试通过替换接口或更换策略进行绕过;面对底层的推理质量不达标,系统严禁利用算力优势发起无限重写。一旦突破上述预设的重试阀值,当前节点状态必须被强制锁定为 `failed_recoverable` 或 `blocked_waiting_for_human`,交由更高维度的治理权柄接管。 + +### 5.2 失败物理定性 (Failure Classification) + +系统产生的故障必须进行结构化的类型鉴别,绝对禁止在运行日志中笼统地抛出“执行失败”的宽泛声明。所有的故障记录必须归入以下标准序列: + +* **F0 Format Failure**:格式失败 +* **F1 Tool Failure**:工具失败 +* **F2 Permission Failure**:权限失败 +* **F3 Data Failure**:数据缺失或数据污染 +* **F4 Source Fidelity Failure**:来源保真失败 +* **F5 Reasoning Failure**:推理失败 +* **F6 Invocation Failure**:真实调用失败 +* **F7 Budget Failure**:预算失败 +* **F8 Governance Failure**:治理违规失败 +* **F9 Terminal Failure**:不可恢复的终极失败 + +### 5.3 修复计划生成 (Repair Plan) + +当产物被判定为失败且尚未触及重试上限时,系统必须先拉起一个独立的线程生成结构化的修复计划(Repair Plan),而非立刻盲目启动重新生成。该计划必须向控制台显式声明以下字段: + +* `failure_type` (故障类型) +* `failure_location` (故障坐标位置) +* `affected_artifacts` (受波及的下游资产) +* `impact_level` (系统影响评级) +* `repair_scope` (预期的修复范围) +* `human_gate_required` (是否需要召唤人工干预) +* `reinvocation_required` (是否需要重启底层真实调用) +* `rollback_required` (是否需要执行物理回滚) +* `new_budget_estimate` (全新的预算消耗预估) + +### 5.4 灾难回滚协议 (Rollback Protocol) + +任何被赋予 A5-W (写入) 或 A5-X (外部动作) 权限的节点,在执行可能改变外部状态的动作前,必须强制搭载回滚协议。系统必须在执行动作的瞬间生成并封存变更前的状态快照(`pre_change_snapshot`)、变更日志与比对文件(`diff` / `action_log`),并锚定回滚操作的物理调用路径(`rollback_path`)与责任方(`rollback_owner`)。 + +对于诸如发布客户可见内容、删除远程资源或触发外部生产 API 等本质上不可逆的操作,系统必须提前发出不可逆转警告(`irreversibility_warning`),将其硬性阻断并强制要求通过 Human Gate 获取人工签发授权。 + +### 5.5 修复后的二次验证 (Re-verification) + +任何经历过修复周期的产物,在重新进入下游流转前,必须被强制押送回对应的评测探针下进行二次校验。修复格式错误后必须重过 E1 Format Test,修复事实幻觉后必须重过 E2 Factual Test,修复逻辑裂痕后必须重过 E3 Reasoning Test,而触发过越界警告的权限修复则必须接受完整的 E7 Governance Test 审计。系统绝不能因为节点自我声明“已修复”而在此处开设任何豁免通道。 + +--- + +## 6. 通用运行组件与资产标准 (Agentic Runtime Components & Artifact Standards) + +当系统从轻量级(Lite)单兵作战攀升至标准(Standard)或完整治理域(Full)时,临时性的硬编码约束将彻底无法抵御系统内部产生的混乱熵增。本章定义了 Agentic 时代所需的重工业扩展组件与资产规约,它们是支撑多智能体协同、确保认知物料跨周期复用并抵抗架构腐化的高阶底座。 + +### 6.1 产物防伪合约 (Artifact Contract) + +“产生海量文件却无法辨认物理真伪”是伪工程化的典型并发症。为了确保认知物料的可追溯与安全复用,任何脱离草稿态进入正式资产池的产物,必须在头部显式绑定一份合约声明,用以宣誓其生命周期与校验元数据。正式产物合约必须包含以下强制性字段: + +* `artifact_type`:精确归属于 Prompt、Agent Spec、Skill、Runtime、Model Card、Model Index、Evaluation、Tool、Workflow、Context Pack、Final Output 或 Simulation Output 等标准类别。 +* `status`:标记其当前处于 draft、candidate、active、deprecated、archived、rejected 亦或是带毒的 simulation-only 阶段。 +* `authority`:清晰界定该产物仅仅是内部笔记(internal_note)、参考(reference_only)、正式依据(formal_basis)、可执行状态(runtime_executable),还是客户可见交付物(customer_visible)。 +* `source_of_truth`:事实来源的物理依据。 +* `downstream_use`:合法消费该产物的下游节点是谁,应用于什么阶段。 +* `invalidation_condition`:定义在何种物理或业务条件下(如:上游源文件更新、Canonical Prompt 更新、用户推翻结构、Human Gate 未通过),该产物判定为失效且需要触发重跑。 +* `cost_class`:归属消耗账本。 +* `created_by` / `created_at` / `last_updated`:全生命周期追踪戳。 + +### 6.2 运行时成熟度模型 (Runtime Maturity Model) + +为了杜绝团队在技术论证与生产交付之间产生致命的预期错位,杜绝“跳级声明成熟”的技术浮夸,必须使用严密的成熟度标尺丈量每一个 Agentic 项目的演进坐标。 + +* **M0 Concept (概念态)**:仅存在思想模型或业务论证,尚未进行任何底层的自动化流程拆解。 +* **M1 Manual (手工态)**:领域专家通过手工干预跑通业务闭环,符合绿野仙踪(Wizard of Oz)协议,在极低成本下验证了智能流的核心业务价值。 +* **M2 Assisted (辅助态)**:AI 仅仅作为外脑介入生成草稿或检查清单,核心推进动力与状态机驱动完全依赖人类手动操作。 +* **M3 Protocolized (协议态)**:系统的输入、输出、角色边界、状态机流转、人工决策门与停止规则等核心架构要素,已在技术规范层面被彻底显性化。 +* **M4 Semi-Agentic (半 Agentic 态)**:系统内部分 Agent、Skill 或 Tool 已实现真实的自动化物理调用,并具备完整的底层 Invocation Record,但仍依赖人类来推进关键决策节点。 +* **M5 Production (生产态)**:具备能够在生产环境下重复运行的刚性管线。系统拥有自动化评测探针、执行监控、异常捕获、日志记录、基础回滚及严密的权限管控,完全达到内部工程可用级别。 +* **M6 Governed (治理态)**:系统的终极形态。具备抵御高强度审计、法理追责与灾难回滚能力,完全适配高法理风险场景、不可逆的对外工具执行,以及外部客户的最严苛交付。 + +**成熟度声明铁律**:严禁系统产物伪造自身的演进坐标。M2 绝不可伪装为 M5,M3 不可伪装为 M6;任何带有模拟烙印的产物均不可宣称为 M4;缺乏真实调用证据(Invocation Record)支撑的流程不可自诩为真实的 Agentic;缺失独立评估栈(Evaluation Stack)的工程不可标记为 Production;无法通过治理测试(Governance Test)的管线不可标榜为 Governed。 + +### 6.3 上下文结构化编译 (Context Compiler) + +绝对禁止将漫长、原始且异质的语料一股脑地倾倒进所有 Agent 的上下文窗口。在任何治理域(I 域)或高价值的求解域(P 域)任务启动前,必须将“上下文工程”剥离为一项独立的物理预处理动作。 + +面对高连贯性的源材料长文,在启动切片分块前,系统必须强制实施全局完形扫描(Whole-source Gestalt),优先锁定核心张力、主轴结构、目录骨架、演化线与关键反例,以此防止 Chunk-first 策略引发的结构性失明。当源材料性质为混合型时,必须优先进行宏观主题拆分;当源材料为纯粹的碎片时,系统应采用平铺发现策略,绝不强行伪造层级关系。 + +基于上下文的“最小充分原则”,上下文编译器最终应根据下游消费节点的特定需求,精准输出并分发以下类型的结构化补给包:原源摘要(`source_digest`)、任务特化分发包(`task_specific_context_pack`)、角色专供包(`role_specific_dispatch_pack`)、供人工复核的决策上下文(`decision_context`)、评测底座(`evaluation_context`)以及包含核心预警信息的风险笔记(`risk_notes`)。 + +### 6.4 来源保真与证据链索引 (Source Fidelity & Evidence Index) + +任何涉及材料加工、报告汇编、知识蒸馏、复杂方案分析的管线,必须为生成的结论焊死来源索引。正式输出中的一切关键判断,必须能够倒查回溯至:原始物理来源、精确的定位坐标(`source range` / `paragraph` / `block id`)、主导该结论的参与者实体(Agent / Worker),以及必须明确注明该判断的信息性质。信息的性质标签必须被精确归类为:`source_fact` (原文事实)、`source_claim` (原文主张)、`inference` (模型推理)、`synthesis` (综合归纳)、`external_fact` (外部事实)、`assumption` (模型假设) 或 `human_decision` (人工裁决)。 + +**来源铁律**:绝对禁止系统将中间摘要包装并冒充为新的绝对事实来源;绝对禁止把模型发散的综合判断伪装成原始材料本身包含的事实;禁止在未标明“推理性质”的语境下强行输出确定性结论;若底层的 `source index` 已经丢失或遭到截断,系统绝对无权对外声称自身完成了无损提取。 + +### 6.5 高维分层评测栈 (Evaluation Stack) + +仅仅依靠单一维度上的“准确率”或“文本相似度”,根本无法测度专家级 Agentic 系统在极端状态下的真实抗压能力。为了确保系统免于崩溃,必须在管线上部署从底层机械运行属性一直延伸至顶层战略效用的全方位探测针。 + +* **E0 Smoke Test (冒烟测试)**:检验系统在最基本的骨架层面能否跑通(如:产物文件是否成功生成、Tool Call 是否正确响应、基础目录结构是否正确映射)。 +* **E1 Format Test (格式测试)**:检验输出物料是否严格遵守预设的 Schema 结构、长度预算天花板、变量命名规则及业务语言规范。 +* **E2 Factual Test (事实测试)**:核查文本溯源的保真度。严密检验系统是否在逻辑真空中编造事实幻觉、是否遗漏了核心源材料,或存在引用混淆现象。 +* **E3 Reasoning Test (推理测试)**:对系统的逻辑链条进行极限刺探。检验系统是否充分暴露了推演假设、推理环路是否闭合、反例材料是否得到处理以及边界条件是否明确说明。 +* **E4 Expert Similarity (专家相似度)**:量化机器判断与人类专家直觉在决策面上的重叠度,并冷酷地记录系统产生偏差时的底层逻辑可解释性。 +* **E5 Decision Utility (决策效用)**:最高层级的业务测试指标。验证系统是否真实有效地帮助人类专家在现实中完成了更优的决策、更敏捷的判断、更低能耗的认知输出、降低了返工率并稳固了风险控制。 +* **E6 Calibration Test (校准测试)**:评测系统在错误恢复态下的“纠错摩擦系数”。检验当系统不可避免地犯错时,人类专家是否能低成本地向其指出错误所在,系统能否精确理解反馈梯度并将修复经验固化,且不影响后续批处理任务。 +* **E7 Governance Test (治理测试)**:以极端的合规与审计视角进行的终极测试。全面核查 Trace 追踪全链路是否完备、Authority 权限沙箱隔离是否被击穿、Rollback 回滚机制是否真正可行、数据安全政策是否被落实以及系统整体的责任边界是否被模糊。 + +### 6.6 按场景选择评测层级 + +测试的烈度必须与场景的深水区级别严格匹配: + +* **Q 域简单查询**:必须覆盖 E0 – E2 评测。 +* **基础 P 域生产流水线**:必须覆盖 E0 – E3 评测。 +* **高阶生产工坊**:必须覆盖 E0 – E5 评测。 +* **具有专家属性的辅助工作台**:必须覆盖 E2 – E6 评测。 +* **面对复杂熵增的战略透镜级系统**:必须覆盖 E3 – E7 评测。 +* **达到 Full 档的终极治理 Runtime**:必须经受 E0 – E7 的全方位高压测试。 + +系统绝不允许使用人类主观的“感觉还不错”来替代 E5 及以上的高维度硬性治理指标评估。 + +# 5 + +继续下一次的输出。 + +## 7. 开工清单与反模式 (Start Checklist & Anti-patterns) + +本章旨在将前述的高维治理规则压缩为开发人员在现场可逐项核验的执行动作。系统架构在向高档位跃迁前,必须接受极度严苛的准入核查,同时必须在开发生命周期内持续识别并清剿具有高度破坏性的反模式。 + +### 7.1 Agentic Project Start Checklist (开工强制核验清单) + +每一个 Agentic 项目在正式编码与拉起管线前,系统负责人必须强制回答以下 20 个系统级验收问题。未完整清查并签署该清单的工程管线,绝对禁止脱离 Lite 档进入 Standard 或 Full 档位的生产环境运行: + +1. 系统的**原始业务任务**究竟是什么? +2. 在 **QPI 矩阵**中,该任务的准确定性(查询、求解、或治理)是什么? +3. 该任务的**终极物理性质**是什么(一次性内容产出、长期能力建设、偏差校准,还是探索预演)? +4. 系统初始启动挂载的**运行档位**是什么(Lite / Standard / Full)? +5. 满足下游消费的最核心、不可删减的**最小充分产物 (Minimum Viable Output)** 是什么? +6. 触发管线物理断电的**绝对停止条件 (Stop Condition)** 是什么? +7. 系统执行的 Token、算时与人类注意力 (Human Attention) 的**硬性预算上限**分别是多少? +8. 当前处理的源材料是否涉及客户机密、安全密钥或个人隐私等**高敏感数据**? +9. 当前的业务逻辑是否刚性需求**底层真实多 Agent沙箱调用**? +10. 若确实需要真实调用,底层生成的 **Invocation Record (调用证据链)** 将被物理保存在哪里? +11. 是否允许底层 Agent 拥有跨过沙箱隔离的**文件与数据写入权限**? +12. 是否允许底层 Agent 触发不可逆的**外部生产 API**? +13. 管线中负责拦截高危动作与责任确认的 **Human Gate (人工决策门)** 部署在哪些物理节点? +14. 针对上述 Human Gate,谁是承担最终法理与业务责任的 **Decision Owner**? +15. 系统的正式产物将通过何种机制被强制注册进 **Artifact Contract (产物防伪合约)**? +16. 针对该项目的业务深度,系统的**全链路评测栈**必须覆盖至 E 几级别(E0 - E7)? +17. 系统的最终结论与报告是否强制需要提供精确的 **Source Fidelity (来源保真与证据索引)**? +18. 面对潜在的崩溃或越权执行,系统是否已预置了底层支持的 **Rollback Protocol (回滚协议)**? +19. 框架内集成的哪些底层平台插件被**显式允许自动触发**? +20. 在预算消耗、执行时长或中间物繁衍达到何种阈值时,系统必须触发 **Scope Drift Review (范围漂移审查)**? + +### 7.2 常见反模式 (Anti-patterns) + +以下 12 种反模式是 Agentic 工程在缺乏强约束下极易滋生的架构腐化现象。一旦在代码审查或运行态监控中发现以下症状,必须立即实施架构级阻断: + +* **1. Prompt 万能化 (Monolithic Prompting)**:开发人员试图将 Agent 设定、Skill 逻辑、Runtime 流转状态与 Model Card 全部强行塞入一个巨型的底层 Prompt 中。此举将直接导致认知物料难以独立维护、评测探针失效、逻辑无法跨节点复用,并彻底丧失复杂工程的追踪与平台迁移能力。 +* **2. 流程幻觉 (Process Hallucination)**:系统表面上生成了齐全的评审报告、分发包、目录树与运行日志,但在底层沙箱中根本不存在真实的 Agent 独立调度,即没有产生任何真实的 Invocation Record。 +* **3. 治理过载 (Governance Overload)**:系统针对一次性(One-off)或轻量级的内容处理任务,滥用算力启用了 Full 档 Runtime。典型症状为处理 5 万字材料却消耗了 3000 万 Tokens,并繁衍出大量冗余的中间审计记录、交接包与主题切片,导致核心业务产物的 ROI(投资回报率)严重失真。 +* **4. 成本混账 (Cost Ledger Entanglement)**:系统在满足用户的一次性结果诉求时,顺带构建了一套庞大的底层执行机器,却在核算时将复杂的系统建设成本打包掩饰为该次任务的直接内容产出成本,破坏了长期基建的审计透明度。 +* **5. 中间物无限繁殖 (Intermediate Artifact Proliferation)**:在用户期待的核心产物迟迟未交付时,系统底层的 Worker 节点为了证明自身运转,在暗中不断并发生成大量的覆盖率审计、路由日志、交接备忘录、修复笔记与元分析报告。 +* **6. 上下文倾倒 (Context Dumping)**:系统跨过上下文编译器(Context Compiler),将所有原始、未拆解的庞杂材料一股脑地倾倒进所有 Agent 的上下文窗口中。这将引发极高概率的角色污染、判断失焦、算力严重浪费以及溯源保真度的断崖式下跌。 +* **7. 权限裸奔 (Unbound Execution Privilege)**:开发人员图谋调用便利,直接赋予负责基础逻辑推理的 Agent 全量的文件写入、资源删除、内容公开发布以及外部高危 API 调用的权限。 +* **8. 无评测上线 (Production without Evaluation)**:系统剥离了全维度的 Evaluation Stack,仅凭开发人员或人类专家的主观感受(“我觉得结果看起来不错”)便直接宣告管线进入生产态(Production)。**红线:无独立评测栈,绝对不得声明 M5 生产态。** +* **9. 模拟产物污染 (Simulation Contamination)**:带有 `simulation-only` 耻辱烙印的非真实沙箱产物,逃避了阻断机制,被非法混入正式的综合裁决链(Synthesis)。这是多 Agent 系统最致命的根级数据污染。 +* **10. 黑盒校准 (Opaque Calibration)**:当系统最终输出发生严重业务偏差时,人类专家在控制台根本无法找到低成本的纠错入口。典型症状为系统产物缺乏结构化的决策归因(Decision Rationale)、未标记错误分类锚点、缺失反馈槽位(Feedback Slot)且无法自动生成修复计划。 +* **11. 插件篡权 (Plugin Usurpation)**:引入的第三方平台插件或自动化 Skill Pack 的默认执行逻辑,静默覆盖并接管了本手册规定的治理红线。其症状表现为插件在后台自动拉起未授权的子线程、自动进入重型审查流程、擅自生成无关的系统目录,或通过幻觉强行补全原本已经失败的执行链条。 +* **12. 停止权失效 (Stop Rule Failure)**:系统在核心产出物已经越过“最小充分阈值”后,非但没有触发物理制动,反而凭借残余的可用预算与模型生成本能,继续在后台生产大量“看似有用实则冗余”的附加材料。**红线:系统绝对不得仅仅因为“尚有算力能够继续生成”,就拒绝执行物理断电。** + +--- + +## 8. 附录:标准元数据模板 (Appendix: Standard Metadata Templates) + +本附录收录了支撑 Agentic 系统各核心治理组件运转的标准数据物理格式。所有的运行时产物、日志收集与合约绑定,必须严格使用以下 YAML 格式模板进行元数据的强类型约束,拒绝任何非结构化的文本描述。 + +### 8.1 真实调用证据链 (Invocation Record Template) + +```yaml +invocation_id: +runtime_id: +agent_id: +role_id: +canonical_prompt_path: +agent_spec_path: +carrier_type: +carrier_id: +thread_id: +input_context_path: +input_context_hash: +execution_timestamp: +returned_output_path: +returned_output_hash: +orchestrator_id: +entered_synthesis: false +human_gate_id_if_applicable: +status: +notes: + +``` + +### 8.2 模拟烙印 (Simulation Metadata Template) + +```yaml +simulation_only: true +formal_output: false +excluded_from_synthesis: true +simulation_reason: +allowed_use: +created_by: +created_at: +must_not_enter: + - formal_synthesis + - customer_delivery + - model_card_source + - governance_audit + +``` + +### 8.3 人工决策门记录 (Human Gate Record Template) + +```yaml +decision_id: +gate_id: +decision_owner: +input_artifacts: +decision_options: +accepted_option: +rejected_options: +reason: +risk_notes: +downstream_effect: +reversibility: +rollback_condition: +timestamp: + +``` + +### 8.4 产物防伪合约 (Artifact Contract Template) + +```yaml +artifact_type: +status: +authority: +source_of_truth: +downstream_use: +invalidation_condition: +cost_class: +created_by: +created_at: +last_updated: +related_invocations: +related_human_gates: +related_sources: + +``` + +### 8.5 状态机流转日志 (Runtime State Transition Template) + +```yaml +runtime_id: +previous_state: +new_state: +trigger: +responsible_actor: +timestamp: +next_allowed_actions: +blocked_reason: +related_artifacts: +notes: + +``` + +### 8.6 成本核算账本 (Cost Ledger Entry Template) + +```yaml +ledger_id: +task_id: +cost_class: +mode: +token_estimate: +token_actual: +time_spent: +tool_calls: +human_attention_minutes: +storage_used: +reason: +approved_by: +timestamp: + +``` + +### 8.7 结构化修复计划 (Repair Plan Template) + +```yaml +repair_id: +failure_type: +failure_location: +affected_artifacts: +impact_level: +repair_scope: +human_gate_required: false +reinvocation_required: false +rollback_required: false +new_budget_estimate: +repair_owner: +next_state: + +``` + +--- + +## 9. 结语:现场纪律 (Conclusion: Field Disciplines) + +Agentic 工程的本质绝非简单且粗暴地“让 AI 承担更多工作”。它是将人类专家在深水业务区中的核心判断、法理责任、隐性经验积累、材料处理能力、流程安全边界以及底层工具的调用权限,精密地封装并装入一台处于微秒级高并发、高速运转状态的认知反应堆中。 + +因此,本《Agentic Engineering Handbook》诞生的根本目的并不是为了鼓励无限制的自动化,而是为了在自动化彻底脱缰之前,为其强行加装必不可少的物理遏制结构: + +* 阻断失控的**入口闸门 (Intake Valves)** +* 追溯算力消耗的**成本账本 (Cost Ledgers)** +* 限制工具滥用的**权限阀门 (Authority Matrix)** +* 刺探底层逻辑的**防伪探针 (Authenticity Probes)** +* 锁定流转阶段的**状态仪表 (State Protocols)** +* 避免信息污染的**数据隔离 (Data Isolation)** +* 核验系统极限的**评测探针 (Evaluation Stack)** +* 防御不可逆灾难的**回滚绳索 (Rollback Protocols)** +* 夺回系统控制权的**绝对刹车 (Stop Rules)** + +在架构的演进过程中,系统表现得越是聪明,它就必须受到越严苛的现场物理规矩约束;业务管线的前端表现得越是丝滑平整,架构师就越需要去监控其后端为抵御熵增而产生的执行废热;底层 Agent 的行动能力越强,就越不能允许其在缺乏权限沙箱的情况下直接接触物理世界。 + +**HiFi Agentic 工程的底线从来都不是“全自动完成计算”,而是确保系统在任何极端载荷下都具备:高保真 (High-Fidelity)、可校准 (Calibratable)、可追踪 (Traceable)、可停止 (Stoppable) 与绝对的可追责性 (Accountable)。** + + diff --git a/discussions/technology/Codex/0.规划与重构/0.环境规划-ccpe-2026-06-15.md b/discussions/technology/Codex/0.规划与重构/0.环境规划-ccpe-2026-06-15.md new file mode 100644 index 0000000..c5a8c40 --- /dev/null +++ b/discussions/technology/Codex/0.规划与重构/0.环境规划-ccpe-2026-06-15.md @@ -0,0 +1,245 @@ +# 1 + +阅读以下5份文档: + +1. C:\Users\wangq\Documents\Codex\knowledge-vault\discussions\technology\Codex\0.规划与重构\2026-06-15-规划总结.md + 我与ChatGPT讨论后,它的总结 +2. C:\Users\wangq\Documents\Codex\knowledge-vault\discussions\technology\Codex\0.规划与重构\2026-06-15-CCPE补充.md + ChatGPT给CCPE的单独补充意见 +3. C:\Users\wangq\Documents\Codex\knowledge-vault\discussions\technology\Codex\0.规划与重构\2026-06-15\00-五库重构总纲.md + Codex 整理的重构总纲。 +4. C:\Users\wangq\Documents\Codex\knowledge-vault\discussions\technology\Codex\0.规划与重构\2026-06-15\03-ccpe-system调整意见.md + Codex 整理的CCPE重构意见 +5. [docs/ccpe-rebuild-context.md](C:/Users/wangq/Documents/Codex/writing-workbench/docs/ccpe-rebuild-context.md) + 这是`writing-workbench`给后续 CCPE 优化/重构会话使用的上下文文件,重点说明:CCPE 现在应作为 `writing-workbench` 的供应商,优先提供主笔、评审员、真实调用协议、no-simulation 规则、素材压缩/上下文准备规则,而不是继续设计完整自动写作 Runtime。 + +目前CCPE的定位是优先给`writing-workbench`提供支撑,但是前面`writing-workbench`发生了没法继续跑的问题,我目前已经重构完毕`knowledge-vault`和`writing-workbench`。 +`video-workbench`目前尚未正式启用,只是个空项目。 + +补充文档,可按需阅读: +* [HiFi Agent Studio](C:\Users\wangq\Documents\Codex\knowledge-vault\rules\Templates\HiFi-Agent-Studio模板4.1.md) +* [Agentic Engineering Handbook](C:\Users\wangq\Documents\Codex\knowledge-vault\rules\Templates\Agentic-Engineering-Handbook.md) + +请先提出你的问题。 + +我已读完 5 份核心文档。我的初步判断是:这次不是继续补一个“大写作 Runtime”,而是把 CCPE 调整成 `writing-workbench` 的供应层:提供专家资产、真实调用协议、上下文准备规则、评审/修复契约、no-simulation 底线,以及外部能力登记机制。 + +我先问这些会影响第一批改造方向的问题: + +1. 第一批优先做哪条线? + 是先改 `README.md / AGENTS.md / ccpe-protocol` 的边界与分类规则,还是先修文章相关资产:`article-outline-development.runtime.md`、`article-context-architect.agent.md`、`agent-invocation-packet.protocol.md`? + +2. 对现有文章 Runtime,你希望是“就地降级修订”,还是“保留旧稿,新建更窄的 `outline-review-and-repair.runtime.md`”? + 我更倾向后者,避免旧文件继续携带完整 Article Production 的误读。 + +3. `writing-workbench` 现在是否已经有 `requirements/ccpe/` 目录和具体需求文件? + 如果有,我应该把它作为 CCPE 第一消费者来读;如果没有,CCPE 这边可以先定义 supplier intake 模板。 + +4. 韩愈、张辽、认知显影、巨人认知这些资产,现在的 canonical source 在哪里? + 是 `knowledge-vault/prompts/`,还是 CCPE 已经有一版 Lite/Agent 草稿?这会决定我先做登记、迁移判断,还是先做 Original Source Judgment。 + +5. 这轮是否要新增 `integrations/`? + 文档里建议加入 `integrations/skills-vault/`、`integrations/mcp/`、`integrations/cli-tools/`、`integrations/api-services/`。这是目录级变化,建议你确认后再动。 + +6. `ccpe-forge` 是否这轮就升级? + 关键改动包括 Classification First Gate、Boundary Check、Registrar Mode、Runtime Designer Mode、Migration Auditor。它会影响后续所有 CCPE 会话的默认行为。 + +7. 是否把 `deep-creation-automation-boundary.protocol.md` 作为第一份分析稿? + 它能承接这次失败经验,先放 `workbench/analysis/`,不急着 canonical 化。 + +8. 对 `video-workbench`,CCPE 这轮只保留“未来供应能力”的接口,还是也要顺手设计降维输出 MVP Runtime 的 CCPE 规格? + 你说 `video-workbench` 还是空项目,我倾向这轮先不展开,避免分散。 + +9. 你希望这次输出到什么粒度? + 我可以先给一份“Batch 1 改造计划 + 文件清单”,等你确认后再写文件;也可以直接从 README/AGENTS/边界协议开始小批量落地。 + +# 2 + +1. 第一批优先做哪条线? + 是先改 `README.md / AGENTS.md / ccpe-protocol` 的边界与分类规则,还是先修文章相关资产:`article-outline-development.runtime.md`、`article-context-architect.agent.md`、`agent-invocation-packet.protocol.md`? + 先修改边界与分类规则。 + 具体修文章的资产,我的考虑: + - `writing-workbench`我刚已经重新初始化了,里面对CCPE的调用已经没有了。 + - `agentslite`下的张辽、韩愈这些专家需要保留; + - 文章相关的,后面要过一下再确定;因为有些可能是给`knowledge-vault`做view-point用的,这个还在用。 + +2. 对现有文章 Runtime,你希望是“就地降级修订”,还是“保留旧稿,新建更窄的 `outline-review-and-repair.runtime.md`”? + 现有文章Runtime,原配套`writing-workbench`的我觉得可以清掉;配套`knowledge-vault`的保留。 + 之前没有搞清楚关系,打造都是CCPE里;将来在各个“需求”项目里,它们提供需求单,然后这里配套打造。 + +3. `writing-workbench` 现在是否已经有 `requirements/ccpe/` 目录和具体需求文件? + `writing-workbench` 现在刚初始化完,`requirements/ccpe/` 是空的。 + 我们这次重构不涉及到新打造,而是规则、范围、责任、边界的确定,和旧的清除。 + +4. 韩愈、张辽、认知显影、巨人认知这些资产,现在的 canonical source 在哪里? + `knowledge-vault/prompts/` 下是改造前的存档,改造好的在CCPE的Lite里。 + +5. 这轮是否要新增 `integrations/`? + 集成这部分,是否可以用到的时候再加文件夹,但是规则里记录下来。 + +6. `ccpe-forge` 是否这轮就升级? + 是的,我希望本轮就升级。但是升级前,需要你明确出来具体改什么,我确认下。 + +7. 是否把 `deep-creation-automation-boundary.protocol.md` 作为第一份分析稿? + > 它能承接这次失败经验,先放 `workbench/analysis/`,不急着 canonical 化。 + 先放 `workbench/analysis/`,不急着 canonical 化。 + +8. 对 `video-workbench`,CCPE 这轮只保留“未来供应能力”的接口,还是也要顺手设计降维输出 MVP Runtime 的 CCPE 规格? + 只保留“未来供应能力”的接口。 + +9. 你希望这次输出到什么粒度? + 先给一份“Batch 1 改造计划 + 文件清单”,等你确认后再写文件 + +--- + +这次最大的改动是: +1. 以前我是在CCPE中讨论各“业务”项目的使用场景,然后配套智能体,然后再到各“业务”项目中构造环境,进行调用; + 将来我是在各“业务”项目中的实际使用场景,发起需求单,CCPE作为供应商来提供智能体。 +2. 以前没有`skills-vault`,这次增加了这个新的库。将自动化剥离出去,CCPE需要明确与skills-vault的差异,将来不再承接这种自动化skill的工作。 +3. 另外,以前没有明确CCPE的Agentic能力定位,后续会在`work-projects`中的开发项目上,引入LangGraph或者CrewAI这些框架作为开发项目的Agentic框架,而不是利用CCPE。CCPE打造的Agent/Skill,将来会包装进这些开发框架的智能体架构中。 + +--- + +有问题继续提出。 + +**任务分类** + +这轮是 `CCPE System governance / boundary refactor`,不是新建文章 Runtime,也不是迁移具体写作资产。主分类:`CCPE protocol refactor`。次级组件:`ccpe-forge upgrade`、`supplier boundary`、`skills-vault boundary`、`deep creation automation boundary analysis`。 + +**Batch 1 改造计划** + +1. 更新 CCPE 顶层定位 + 把 CCPE 明确改成“供应商 / 架构工坊 / 资产登记中心”,不再从 CCPE 内部主动替业务项目设计场景。业务项目先产生需求单,CCPE 再供应 Agent、Lite、Runtime spec、调用协议、Model Card 或登记规则。 + +2. 更新分类规则 + 新增或强化这些分类: + `CCPE-Committee`、`Integration Registration`、`Project Runbook`、`automation Skill source`、`external tool / MCP / CLI / API`、`out of scope`。 + 同时明确:automation Skill source 归 `skills-vault`,CCPE 只在被 Agent/Runtime 正式依赖时做 architecture registration。 + +3. 更新目录责任边界 + 暂不创建 `integrations/` 目录,但在规则里写清:未来可按需创建 `integrations/skills-vault/`、`integrations/mcp/`、`integrations/cli-tools/`、`integrations/api-services/`。 + +4. 升级 `ccpe-forge` 的行为规则 + 我建议本轮明确写入这些改动,等你确认后再落文件: + - 启动前必须先做 `Classification First Gate`。 + - 增加 `Boundary Check`:判断是否属于 CCPE、skills-vault、业务项目仓库、工具实现层或 out of scope。 + - 增加 `Registrar Mode` 规则,但先不生成目录。 + - 强化 `Runtime Designer` 规则:默认 Lite,证据驱动升级 Standard/Full。 + - 增加 `Supplier Intake`:业务项目需求单优先于 CCPE 内部假设场景。 + - 禁止把成熟 Lite 默认升级成 Agent Spec。 + - 禁止把 automation Skill 源码放入 CCPE。 + - 禁止主会话模拟 canonical participant 的正式输出。 + +5. 新增一份分析稿 + 创建 `workbench/analysis/deep-creation-automation-boundary.protocol.md`,定位为分析稿,不 canonical 化。它只总结深度创作哪些地方不能提前自动化、哪些地方只能做上下文辅助、哪些正式输出必须真实调用。 + +6. 旧资产处理只做标记,不删除 + 本批不清理 `workbench/upgraded/article-*`。先在计划里标记:原配套旧 `writing-workbench` 的文章 Runtime 待清理;配套 `knowledge-vault` viewpoint 的 Runtime 保留。下一批再做 inventory 和清理确认。 + +**拟修改 / 新增文件** + +拟修改: + +- [README.md](C:/Users/wangq/Documents/Codex/ccpe-system/README.md) +- [AGENTS.md](C:/Users/wangq/Documents/Codex/ccpe-system/AGENTS.md) +- [ccpe-system-definition.md](C:/Users/wangq/Documents/Codex/ccpe-system/ccpe-protocol/ccpe-system-definition.md) +- [ccpe-classification-rules.md](C:/Users/wangq/Documents/Codex/ccpe-system/ccpe-protocol/ccpe-classification-rules.md) +- [ccpe-operating-modes.md](C:/Users/wangq/Documents/Codex/ccpe-system/ccpe-protocol/ccpe-operating-modes.md) +- [ccpe-migration-policy.md](C:/Users/wangq/Documents/Codex/ccpe-system/ccpe-protocol/ccpe-migration-policy.md) +- [SKILL.md](C:/Users/wangq/Documents/Codex/ccpe-system/.codex/skills/ccpe-forge/SKILL.md) +- [ccpe-forge-workflows.md](C:/Users/wangq/Documents/Codex/ccpe-system/.codex/skills/ccpe-forge/references/ccpe-forge-workflows.md) +- [depth-vs-automation-rules.md](C:/Users/wangq/Documents/Codex/ccpe-system/.codex/skills/ccpe-forge/references/depth-vs-automation-rules.md) + +拟新增: + +- `C:/Users/wangq/Documents/Codex/ccpe-system/ccpe-protocol/ccpe-boundaries.md` +- `C:/Users/wangq/Documents/Codex/ccpe-system/ccpe-protocol/ccpe-artifact-taxonomy.md` +- `C:/Users/wangq/Documents/Codex/ccpe-system/ccpe-protocol/ccpe-governance-adapter.md` +- `C:/Users/wangq/Documents/Codex/ccpe-system/workbench/analysis/deep-creation-automation-boundary.protocol.md` + +暂不新增: + +- `integrations/` +- 新文章 Runtime +- 新 `writing-workbench` 供应资产 +- `video-workbench` Runtime +- automation Skill 源码或模板 + +**需要你确认的点** + +1. `ccpe-boundaries.md`、`ccpe-artifact-taxonomy.md`、`ccpe-governance-adapter.md` 这三个新协议文件是否同意加入? +2. `ccpe-forge` 是否按上面 8 条具体改动升级? +3. `deep-creation-automation-boundary.protocol.md` 是否按“分析稿,不 canonical 化”的方式写入? + +另外我注意到当前仓库已经是 dirty 状态,包含 `AGENTS.md`、`ccpe-forge/SKILL.md`、`ccpe-operating-modes.md` 的既有修改,以及若干未跟踪的 article/viewpoint 文件。后续落地时我会只改确认范围内的文件,不清理这些旧资产。 + +# 3 + +1. `ccpe-boundaries.md`、`ccpe-artifact-taxonomy.md`、`ccpe-governance-adapter.md` 这三个新协议文件是否同意加入? 同意。 +2. `ccpe-forge` 是否按上面 8 条具体改动升级? 是。 +3. `deep-creation-automation-boundary.protocol.md` 是否按“分析稿,不 canonical 化”的方式写入? 是。 + +我有个问题,在你具体执行前,确认一下: + +CCPE System,是为本地工作打造智能体的平台,我打造的这些智能体可以称之为开发智能体,主要用于我自己的工作,比如创作流程、输出流程,或者工作流程(不论是辅助销售方案、项目计划,还是系统开发),也不论是单智能体还是多智能体协作,不论是专家智能体,还是一些自动化智能体,都是为我自己的工作服务。 +当我开发智能化系统时,我也会用CCPE打造智能体,称其为生产/业务智能体,但是这些智能体需要我自行引入到我的开发项目中,而不是本地调用;因为这些系统将来都会部署到服务器上,且受到具体Agentic开发框架约束。 +所以对于生产/业务智能体,很有可能,本身就在智能化系统项目里打造,而不是通过CCPE。 + +--- + +回复问题后,就可以继续工作了。 + +已完成 Batch 1。 + +我先回答你的确认问题:你的理解是对的。CCPE 可以打造你本地工作用的“开发智能体”,也可以设计将来用于生产系统的“生产/业务智能体”。但对生产/业务智能体,CCPE 只负责规格、边界、权限、评估、调用契约这些设计层;真正接入 LangGraph、CrewAI、服务器部署、状态存储和运行逻辑,应归具体开发项目。 + +本轮已落地: + +- 更新 [README.md](C:/Users/wangq/Documents/Codex/ccpe-system/README.md):加入 CCPE 作为供应商/架构工坊的定位、生产系统边界、Committee、Integration Registration、目录树更新。 +- 更新 [AGENTS.md](C:/Users/wangq/Documents/Codex/ccpe-system/AGENTS.md):加入 Boundary Check、项目仓库/skills-vault/开发项目归属规则,以及 `integrations/` 未来按需创建规则。 +- 新增 [ccpe-boundaries.md](C:/Users/wangq/Documents/Codex/ccpe-system/ccpe-protocol/ccpe-boundaries.md)。 +- 新增 [ccpe-artifact-taxonomy.md](C:/Users/wangq/Documents/Codex/ccpe-system/ccpe-protocol/ccpe-artifact-taxonomy.md)。 +- 新增 [ccpe-governance-adapter.md](C:/Users/wangq/Documents/Codex/ccpe-system/ccpe-protocol/ccpe-governance-adapter.md)。 +- 新增 [deep-creation-automation-boundary.protocol.md](C:/Users/wangq/Documents/Codex/ccpe-system/workbench/analysis/deep-creation-automation-boundary.protocol.md),保持为 analysis draft,未 canonical 化。 +- 更新 [ccpe-forge/SKILL.md](C:/Users/wangq/Documents/Codex/ccpe-system/.codex/skills/ccpe-forge/SKILL.md):加入 Classification First Gate、Boundary Check、Supplier Intake Check、Registrar Mode、Runtime Designer Mode。 +- 同步更新分类、迁移、运行模式和 Forge reference 规则。 + +验证已做: + +- 新增文件存在性检查通过。 +- `rg` 检索确认关键规则可被后续会话找到:`Supplier Intake`、`Boundary Check`、`Integration Registration`、`skills-vault`、`production/business`、`Runtime Designer` 等。 +- `git diff --check` 未报 Markdown 空白错误;只出现 Git 的 LF/CRLF 行尾提示。 +- 没有清理旧文章资产,也没有创建 `integrations/` 目录。旧的 article/viewpoint 未跟踪文件仍保持原状。 + +# 4 + +没有清理旧文章资产也没关系,这个外部不会调用了。 + +这是`writing-workbench`下的一个projects文件, `C:\Users\wangq\Documents\Codex\writing-workbench\PROJECTS.md` +类似的,`knowledge-vault`下也有自己的 `C:\Users\wangq\Documents\Codex\knowledge-vault\PROJECTS.md` + +你看你是否需要一个自己的项目文档。若需要自己准备一个。 + +然后做提交,并同步远程,打上Tag。作为重构完成的最后一步。 + +已完成收尾。 + +我新增了 [PROJECTS.md](C:/Users/wangq/Documents/Codex/ccpe-system/PROJECTS.md),把 CCPE 定义为“AI 资产架构工坊和供应商”,并明确它与 `knowledge-vault`、`writing-workbench`、`video-workbench`、`skills-vault`、`work-projects` 的关系。 + +提交和同步也完成了: + +- Commit: `07e6828 Refine CCPE boundaries and supplier governance` +- Tag: `ccpe-boundary-refactor-2026-06-15` +- 已推送到 `origin/main` +- Tag 已推送到远程 + +当前工作区还保留了一批未跟踪旧资产,比如 `workbench/upgraded/article-*`、`runtimes/hybrid/`、`agents/agent-specs/` 等;我没有把它们纳入本次提交。 + +::git-stage{cwd="C:\Users\wangq\Documents\Codex\ccpe-system"} +::git-commit{cwd="C:\Users\wangq\Documents\Codex\ccpe-system"} +::git-push{cwd="C:\Users\wangq\Documents\Codex\ccpe-system" branch="main"} + +# 5 + +现在提交所有变动,并同步远程。 + diff --git a/discussions/technology/Codex/0.规划与重构/0.环境规划-knowledge-vault-2026-06-15.md b/discussions/technology/Codex/0.规划与重构/0.环境规划-knowledge-vault-2026-06-15.md index af5362e..a9c2e25 100644 --- a/discussions/technology/Codex/0.规划与重构/0.环境规划-knowledge-vault-2026-06-15.md +++ b/discussions/technology/Codex/0.规划与重构/0.环境规划-knowledge-vault-2026-06-15.md @@ -159,3 +159,22 @@ work-projects 具体开发工作、客户/产品/实验性工程项目现 最后同步到远程库。 +已同步到远程。 + +推送结果: +- `main` 已推到 `origin/main` +- 当前 HEAD:`c116810` +- `origin/main`:`c116810` +- tag 已推送:`knowledge-vault-restructure-2026-06-15` + +我还补了一个最后的日志提交: +- `c116810 docs: update knowledge vault planning log` + +重构里程碑 tag 仍指向之前的结构提交: +- `2bb7e38 chore: restructure knowledge vault taxonomy` + +工作树现在干净。 + +::git-commit{cwd="C:\Users\wangq\Documents\Codex\knowledge-vault"} +::git-push{cwd="C:\Users\wangq\Documents\Codex\knowledge-vault" branch="main"} + diff --git a/discussions/technology/Codex/0.规划与重构/0.环境规划-skills-vault-2026-06-15.md b/discussions/technology/Codex/0.规划与重构/0.环境规划-skills-vault-2026-06-15.md new file mode 100644 index 0000000..550e1c1 --- /dev/null +++ b/discussions/technology/Codex/0.规划与重构/0.环境规划-skills-vault-2026-06-15.md @@ -0,0 +1,156 @@ +# 1 + +**要求:** +阅读3份文档: + +1. C:\Users\wangq\Documents\Codex\knowledge-vault\discussions\technology\Codex\0.规划与重构\2026-06-15\00-五库重构总纲.md +2. C:\Users\wangq\Documents\Codex\knowledge-vault\discussions\technology\Codex\0.规划与重构\2026-06-15-规划总结.md +3. C:\Users\wangq\Documents\Codex\knowledge-vault\discussions\technology\Codex\0.规划与重构\2026-06-15\05-skills-vault调整意见.md.md + +本次应该只涉及到项目的描述、规则类文件及项目关系等。 + +**projects文件** + +* 这是`writing-workbench`下的一个projects文件, `C:\Users\wangq\Documents\Codex\writing-workbench\PROJECTS.md` +* 类似的,`knowledge-vault`下也有自己的 `C:\Users\wangq\Documents\Codex\knowledge-vault\PROJECTS.md` +* CCPE的,`C:\Users\wangq\Documents\Codex\ccpe-system\PROJECTS.md` +* video的,`C:\Users\wangq\Documents\Codex\video-workbench\PROJECTS.md` + +--- + +将来你的需求发起,可能来自于两部分: +1. “业务系统”的需求,比如voice-gen实际上就是为video-workbench配套的; +2. 我工作过程中发现的局部自动化,比如fix-title 就是我在与chatgpt交流时发现格式总是不对 + +--- + +请先提出你的问题。 + + +我已读完三份材料;第三份实际路径是 `05-skills-vault调整意见.md`,你给的是 `.md.md`。 + +我的问题: + +1. 这轮是否**只改 `skills-vault` 仓库**? + 我理解不直接修改 `writing-workbench / knowledge-vault / ccpe-system / video-workbench` 的 `PROJECTS.md`,只在 `skills-vault` 内补齐对应说明和关系。 + +2. 是否要为 `skills-vault` 新增自己的 `PROJECTS.md`? + 目前仓库里没有。结合你列出的四个项目,我倾向于新增一个,定位为“五库关系中的 skills-vault 项目说明 + 需求入口分类 + 与其他项目的协作边界”。 + +3. `PROJECTS.md` 的用途你希望偏哪一种? + - 项目总览:给新会话快速理解仓库定位; + - 操作路由:判断一个需求该进 `skills-vault`、业务项目、还是 `ccpe-system`; + - 两者都要,但保持轻量。 + +4. “需求发起来自两部分”是否要固化成正式规则? + 我建议写成两个 intake source: + - `business-system-support`:服务 `video-workbench`、`writing-workbench` 等业务系统; + - `local-workflow-automation`:工作过程中发现的局部自动化,如 `fix-title`。 + 这条是否可以进入 `PROJECTS.md` 或 `docs/architecture.md`? + +5. `voice-generation` 与 `video-workbench` 的关系要写到什么程度? + 我倾向于写成:`voice-generation` 是 `skills-vault` 拥有源码的 automation skill,但当前主要服务 `video-workbench`;业务流程、视频生产 Runtime、素材决策仍归 `video-workbench`。 + +6. 候选 Skill 是否只登记不实现? + 比如 `voiceover-budget-checker`、`asset-log-builder`、`context-handoff-builder`,我理解本轮只放入 registry / 项目说明的候选区,不创建 Skill 目录和脚本。 + +7. 本轮允许调整哪些文件? + 我的候选范围是: + - `README.md` + - `AGENTS.md` + - `docs/architecture.md` + - `docs/ccpe-relationship.md` + - `registry/skills-index.md` + - 新增 `PROJECTS.md` + + 是否还有你明确希望纳入或排除的文件? + +# 2 + + +1. 这轮是否**只改 `skills-vault` 仓库**? + 只在 `skills-vault` 内补齐对应说明和关系。 + +2. 是否要为 `skills-vault` 新增自己的 `PROJECTS.md`? + 新增一个,定位为“五库关系中的 skills-vault 项目说明 + 需求入口分类 + 与其他项目的协作边界”。 + +3. `PROJECTS.md` 的用途你希望偏哪一种? + 这个是给你自己用的,作为项目总览就可以。 + +4. “需求发起来自两部分”是否要固化成正式规则? + 可以进入`PROJECTS.md` 或 `docs/architecture.md` + +5. `voice-generation` 与 `video-workbench` 的关系要写到什么程度? + `voice-generation` 会安装到机器的`.agent/skills/`下,`video-workbench`用的是`.agent/skills/` 下的,和本项目没直接关系。 + `video-workbench` 只是需求发起方之一,算作“业务”系统。 + +6. 候选 Skill 是否只登记不实现? + 不创建 Skill 目录和脚本,也不放在 registry / 项目说明的候选区。这些可能都不是真实流程的需求。 + 将来Skill一定会来自于真实流程。 + +7. 本轮允许调整哪些文件? + 删掉`registry/` + +--- + +若没有其他问题,可以进行调整工作了。 + +# 3 + +上一轮有歧义的部分: + +你问: +``` +7. 本轮允许调整哪些文件? + 我的候选范围是: + - `README.md` + - `AGENTS.md` + - `docs/architecture.md` + - `docs/ccpe-relationship.md` + - `registry/skills-index.md` + - 新增 `PROJECTS.md` +``` + +我说: +> 删掉`registry/` + +我的意思不是要删掉这个目录,而是从变化范围中删掉`registry/skills-index.md` +即,本轮不做任何候选skill的预注册/登记,所有的skill都从真实业务需求中来,要么是业务系统,比如`video-workbench`的需求单;要么是我工作过程中发现的自动化要求。 + +--- + +然后,我看到你理解错了,在考虑删除这个路径,我按了停止。 + +--- + +现在,需要你重新理解,看下你上次做了哪些操作,恢复并继续。 + +已按纠正后的边界继续完成。 + +本轮实际变更: +- 新增 [PROJECTS.md](C:/Users/wangq/Documents/Codex/skills-vault/PROJECTS.md),作为 `skills-vault` 的项目总览:五库关系、两类真实需求来源、安装边界、registry 不作为候选 backlog。 +- 更新 [README.md](C:/Users/wangq/Documents/Codex/skills-vault/README.md) 和 [AGENTS.md](C:/Users/wangq/Documents/Codex/skills-vault/AGENTS.md),补上“Skill 来自真实业务/工作流需求,不预注册候选”的规则。 +- 更新 [docs/architecture.md](C:/Users/wangq/Documents/Codex/skills-vault/docs/architecture.md)、[docs/ccpe-relationship.md](C:/Users/wangq/Documents/Codex/skills-vault/docs/ccpe-relationship.md)、[docs/installation.md](C:/Users/wangq/Documents/Codex/skills-vault/docs/installation.md)、[docs/migration-guide.md](C:/Users/wangq/Documents/Codex/skills-vault/docs/migration-guide.md),同步业务系统、`.agents/skills`、`ccpe-system` 的边界说明。 + +我确认了: +- 没有删除 `registry/`。 +- 没有修改 `registry/skills-index.md`,`git diff -- registry/skills-index.md` 为空。 +- 没有创建候选 Skill 目录、脚本或 registry 预登记。 +- `git status` 只显示上述文档变更和新增 `PROJECTS.md`。 + +# 4 + +现在提交并同步远程,打上tag。 +本次重构工作就算结束了。 + +已完成。 + +- 已推送 `main` 到 `origin/main` +- 已推送 tag:`skills-vault-restructure-2026-06-15` +- 当前 HEAD:`9109268 Document skills-vault project boundaries` +- 本地状态:`main...origin/main`,已同步 + +本次 `skills-vault` 重构收尾完成。 + +::git-push{cwd="C:\Users\wangq\Documents\Codex\skills-vault" branch="main"} + diff --git a/discussions/technology/Codex/0.规划与重构/0.环境规划-video-2026-06-15.md b/discussions/technology/Codex/0.规划与重构/0.环境规划-video-2026-06-15.md new file mode 100644 index 0000000..eed8ca7 --- /dev/null +++ b/discussions/technology/Codex/0.规划与重构/0.环境规划-video-2026-06-15.md @@ -0,0 +1,151 @@ +# 1 + +**要求:** +阅读3份文档: + +1. C:\Users\wangq\Documents\Codex\knowledge-vault\discussions\technology\Codex\0.规划与重构\2026-06-15\00-五库重构总纲.md +2. C:\Users\wangq\Documents\Codex\knowledge-vault\discussions\technology\Codex\0.规划与重构\2026-06-15-规划总结.md +3. C:\Users\wangq\Documents\Codex\knowledge-vault\discussions\technology\Codex\0.规划与重构\2026-06-15\04-video-workbench调整意见.md + +由于本项目尚未正式跑过,本次更新调整只涉及到规则范围等说明的变动。 + +--- + +**工作模式:** +你将有两个模式,“定义需要的能力”和“调用能力完成工作”: +- `capability-request mode`,这个是“供应商”的工单 +- `execution mode`,这个是自己的工作工单 + +对于`capability-request mode`,你将作为甲方,规划自己的使用场景,有哪些需求,CCPE system和skills-vault作为你的供应商; +而对于`execution mode`,这个是你自己的工作内容。 + +类似于`writing-workbench`,可以参考 `C:\Users\wangq\Documents\Codex\writing-workbench\WORKBENCH.md` 的`4. Two Modes`部分。 + +--- + +**projects文件** + +* 这是`writing-workbench`下的一个projects文件, `C:\Users\wangq\Documents\Codex\writing-workbench\PROJECTS.md` +* 类似的,`knowledge-vault`下也有自己的 `C:\Users\wangq\Documents\Codex\knowledge-vault\PROJECTS.md` +* CCPE的,`C:\Users\wangq\Documents\Codex\ccpe-system\PROJECTS.md` + +你看你是否也需要这样一份自己的Projects文档。 + +--- + +先提出你的问题。 + +我读完了三份规划文档、`writing-workbench` 的 Two Modes、三个 `PROJECTS.md` 示例,以及 `video-workbench` 现有 README / VIDEO_WORKBENCH / handoff / ccpe-consumption。先确认我的理解:这次不是启动真实视频项目,也不是搭完整 Runtime,而是更新 `video-workbench` 的规则说明、边界说明、供应商需求流转方式。 + +我的问题: + +1. `video-workbench` 是否也要新增自己的 `PROJECTS.md`? + 我的倾向是需要。它可以像另外三个仓一样,专门说明它消费什么、产出什么、和 `knowledge-vault / writing-workbench / ccpe-system / skills-vault` 的关系,避免把这些边界散落在 README 和 handoff 里。 + +2. `capability-request mode` 的工单目录是否就按 writing-workbench 的方式放在: + `requirements/ccpe/` + `requirements/skills-vault/` + 还是你希望 video-workbench 用更视频化的命名,比如 `capability-requests/ccpe/`? + +3. 这次是否只更新顶层规则文档,不碰模板? + 例如只改或新增: + `README.md` + `VIDEO_WORKBENCH.md` + `PROJECTS.md` + `docs/context-handoff.md` + `docs/ccpe-system-handoff.md` + `ccpe-consumption/runtime-links.md` + 暂不改 `templates/` 下的 series / episode / storyboard / shot 模板。 + +4. `voice-generation` 这类已存在能力,要不要在本轮直接写成“可用外部 automation skill”? + 我可以把它记录为 `skills-vault / installed skill` 方向的已知能力,但不把它写成 video-workbench 自己拥有的能力。 + +5. `强哥的徒弟` 的位置,这次是否只写成“CCPE supplier request / planned dependency”,而不是在 video-workbench 内创建 prompt 或 agent 文件? + 我理解应保持:先 CCPE-Lite,真实项目验证后再升级,不在本仓复制 canonical prompt。 + +6. 输入材料稳定性规则要不要写成硬门槛? + 例如:默认只接收已稳定文章、模型文档、已形成结论的讨论稿;如果用户明确要求,也可以做“探索型视频草案”,但必须标记为不稳定输入,不能反向污染深度创作。 + +7. `execution mode` 是否允许创建第一个试跑项目? + 你这次说明“本项目尚未正式跑过,本次更新调整只涉及规则范围等说明变动”,所以我默认本轮不创建 `series/` 或 `standalone/` 项目,只更新规则文档。请确认。 + +# 2 + +1. `video-workbench` 是否也要新增自己的 `PROJECTS.md`? + 创建你自己的`PROJECTS.md` + +2. `capability-request mode` 的工单目录是否就按 writing-workbench 的方式放在…… + 和writing-workbench 保持一致。 + +3. 这次是否只更新顶层规则文档,不碰模板? + 暂不改 `templates/` 下的 series / episode / storyboard / shot 模板。 + +4. `voice-generation` 这类已存在能力,要不要在本轮直接写成“可用外部 automation skill”? + 现在先不记录,将来它会作为推进业务的一个环节的具体skill。 + 将来我们约定好口播稿怎么生成,在哪里后,再记录口播稿怎么变成音频。 + +5. `强哥的徒弟` 的位置,这次是否只写成“CCPE supplier request / planned dependency”,而不是在 video-workbench 内创建 prompt 或 agent 文件? + 我理解应保持:先 CCPE-Lite,真实项目验证后再升级,不在本仓复制 canonical prompt。 + 是的,先 CCPE-Lite。这个具体跑测试项目时,边做边打造即可。 + 而且,我倾向于未来,本地`video-workbench` 也没有 prompt 或 agent 文件,这个全部保留在ccpe。因为这是本地的工作流程,参见我在CCPE的对话: + ```txt + 我有个问题,在你具体执行前,确认一下: + + CCPE System,是为本地工作打造智能体的平台,我打造的这些智能体可以称之为开发智能体,主要用于我自己的工作,比如创作流程、输出流程,或者工作流程(不论是辅助销售方案、项目计划,还是系统开发),也不论是单智能体还是多智能体协作,不论是专家智能体,还是一些自动化智能体,都是为我自己的工作服务。 + 当我开发智能化系统时,我也会用CCPE打造智能体,称其为生产/业务智能体,但是这些智能体需要我自行引入到我的开发项目中,而不是本地调用;因为这些系统将来都会部署到服务器上,且受到具体Agentic开发框架约束。 + 所以对于生产/业务智能体,很有可能,本身就在智能化系统项目里打造,而不是通过CCPE。 + + --- + + 我先回答你的确认问题:你的理解是对的。CCPE 可以打造你本地工作用的“开发智能体”,也可以设计将来用于生产系统的“生产/业务智能体”。但对生产/业务智能体,CCPE 只负责规格、边界、权限、评估、调用契约这些设计层;真正接入 LangGraph、CrewAI、服务器部署、状态存储和运行逻辑,应归具体开发项目。 + + ``` + 如果要内建 prompt 或 agent ,那也是在`work-projects`中的事情——我将视频工作流包装成一个系统,可以独立部署。 + +6. 输入材料稳定性规则要不要写成硬门槛? + 这部分,我还没想好,先不写死。 + 尽管现在的工作是从文章起,但是不排除有其他入口,流程并没有固定下来。 + +7. `execution mode` 是否允许创建第一个试跑项目? + 不创建试跑项目,只涉及更新规则文档 + +--- + +若没有其他问题,可以继续工作了。 + +已按你的确认完成规则文档更新,没有创建试跑项目,也没有改 `templates/`。 + +主要变更: +- 新增 [PROJECTS.md](C:/Users/wangq/Documents/Codex/video-workbench/PROJECTS.md:1),记录 `video-workbench` 与 `knowledge-vault / writing-workbench / ccpe-system / skills-vault / work-projects` 的关系。 +- 在 [README.md](C:/Users/wangq/Documents/Codex/video-workbench/README.md:48) 和 [VIDEO_WORKBENCH.md](C:/Users/wangq/Documents/Codex/video-workbench/VIDEO_WORKBENCH.md:88) 增加 `Execution Mode` / `Capability-Request Mode`。 +- 新增 [requirements/ccpe/README.md](C:/Users/wangq/Documents/Codex/video-workbench/requirements/ccpe/README.md:1) 和 [requirements/skills-vault/README.md](C:/Users/wangq/Documents/Codex/video-workbench/requirements/skills-vault/README.md:1),与 `writing-workbench` 保持同样的供应商工单落点。 +- 更新 [docs/ccpe-system-handoff.md](C:/Users/wangq/Documents/Codex/video-workbench/docs/ccpe-system-handoff.md:37),明确 `强哥的徒弟` 先作为 CCPE-Lite,由 CCPE 保留 canonical prompt / agent,不放进本仓。 +- 更新 [ccpe-consumption/runtime-links.md](C:/Users/wangq/Documents/Codex/video-workbench/ccpe-consumption/runtime-links.md:30),强调 planned assets 不能标成已执行或已可用。 + +验证: +- `rg "voice-generation|voice-gen|口播稿怎么变成音频" .` 无匹配,未记录 voice-generation。 +- `git status --short` 只显示上述规则文档和新增 `PROJECTS.md` / `requirements/`。 +- `templates/` 下文件未出现在变更集中。 + +# 3 + +现在做一次提交,并同步远程,打上Tag。 + +已完成提交、推送和打 tag。 + +提交: +`baafbd5 docs: update video workbench operating boundaries` + +Tag: +`video-workbench-rules-2026-06-15` + +远端验证: +- `origin/master` 指向 `baafbd57117fec8aef7b57ca2d7f4f20a973fbfc` +- 远端已有 `refs/tags/video-workbench-rules-2026-06-15` + +本地工作区在提交前已确认只暂存本次 8 个规则文档/目录说明文件;推送过程中普通沙箱网络不可达,已通过提升权限完成 `master` 和 tag 同步。 + +::git-stage{cwd="C:\Users\wangq\Documents\Codex\video-workbench"} +::git-commit{cwd="C:\Users\wangq\Documents\Codex\video-workbench"} +::git-push{cwd="C:\Users\wangq\Documents\Codex\video-workbench" branch="master"} + diff --git a/discussions/technology/Codex/0.规划与重构/0.环境规划-writing-2026-06-15.md b/discussions/technology/Codex/0.规划与重构/0.环境规划-writing-2026-06-15.md new file mode 100644 index 0000000..8efd200 --- /dev/null +++ b/discussions/technology/Codex/0.规划与重构/0.环境规划-writing-2026-06-15.md @@ -0,0 +1,588 @@ +# 1 + +阅读这里的3份文档: + +1. C:\Users\wangq\Documents\Codex\knowledge-vault\discussions\technology\Codex\0.规划与重构\2026-06-15\00-五库重构总纲.md +2. C:\Users\wangq\Documents\Codex\knowledge-vault\discussions\technology\Codex\0.规划与重构\2026-06-15-规划总结.md +3. C:\Users\wangq\Documents\Codex\knowledge-vault\discussions\technology\Codex\0.规划与重构\2026-06-15\02-writing-workbench调整意见.md + +目前在`writing-workbench`中,实际上没有正式启动项目,因为写作流程跑不下去。`C:\Users\wangq\Documents\Codex\writing-workbench\projects\active`下的两个项目,可以算作只是测试验证,但是就发生了`2026-06-15-规划总结`中发现的问题。 +这也是本次重构的核心原因。 + +有问题提出。 + + +我读完三份规划文档,也核对了当前 `writing-workbench` 的入口文档和两个 active 项目。我的核心判断是:现在最需要问清楚的不是“怎么补流程”,而是“什么东西不再允许进入 active article project”。 + +我建议先回答这几组问题: + +1. `projects/active` 是否只能放“正式文章项目”? + 现在 [2026-06-04-Sanguo-test-slug](C:/Users/wangq/Documents/Codex/writing-workbench/projects/active/2026-06-04-Sanguo-test-slug) 只有一份讨论稿,更像测试材料,不像项目。是否要新增 `projects/sandbox/`、`projects/tests/` 或 `projects/candidates/`,把这类验证对象从 `active` 中隔离出去? + +2. “已决定写作”到底需要多强? + 是用户说“这要写成文章”就够,还是必须同时有:工作标题、目标读者、材料范围、当前命题、下一步产物?如果不定义,`material_intake` 很容易继续吸入开放讨论。 + +3. `insight_discussion` 默认应该放哪里? + `02-writing-workbench调整意见.md` 倾向让观点生成和隐形规则显影留在 `knowledge-vault`,但当前 Anti 项目的 handoff 又允许“项目内小范围 positioning discussion”。这里需要定默认规则:项目内只能做“服务本篇文章的定位讨论”,还是默认回 `knowledge-vault`,只把结果稿放回 `materials/`? + +4. 是否需要一个“pre-project / candidate”层? + `Anti-Overengineering-Gate` 已经有项目壳,但还在问“这篇文章真正要写什么”。这说明它介于材料包和正式文章项目之间。要不要承认这个中间态,而不是强行叫 active article project? + +5. 现有模板是缩小,还是保留但降权? + [PROJECT_STRUCTURE.md](C:/Users/wangq/Documents/Codex/writing-workbench/templates/article-project/PROJECT_STRUCTURE.md) 仍然默认包含 outline review、tribunal、model-writing 等完整链条。要不要做一个 `lite-skeleton`,只包含 `project.md / source-map.md / status.md / materials / decision-records`,把 full structure 改成扩展模板? + +6. “真实调用”边界是否要写进 Writing Workbench,而不只写进 CCPE? + 现在 `WORKBENCH.md` 还写“dispatches writer or reviewer sessions”,但没有强制说明:没有真实 thread/sub-session/invocation record,就不能产生正式 reviewer report。这个规则是否要成为本仓库硬规则? + +7. 当前两个 active 项目怎么处理? + 我的倾向是:`2026-06-04-Sanguo-test-slug` 移出 active,标成 test/sandbox;`2026-06-12-Anti-Overengineering-Gate` 暂留 active 或改成 candidate,但明确禁止进入立意/提纲/评审,直到用户确认命题。 + +8. `README / WORKBENCH / playbook` 是否要把“不要自动进入下一阶段”写成默认停止规则? + 目前文档说了进入条件,但没有足够强地说:材料承接完成后默认停止,等待用户决定,不自动 positioning、不自动 outline、不自动 review。 + +如果先做改造,我会建议第一刀只改边界和状态,不动大流程:新增项目类型/状态说明,降权模板,加入 no-simulation 和 material_intake stop rule,然后迁移或标记两个 active 测试项目。这样能直接针对这次失败原因,而不是继续加结构。 + +# 2 + + +1. `projects/active` 是否只能放“正式文章项目”? + 现在 [2026-06-04-Sanguo-test-slug](C:/Users/wangq/Documents/Codex/writing-workbench/projects/active/2026-06-04-Sanguo-test-slug) 只有一份讨论稿,更像测试材料,不像项目。是否要新增 `projects/sandbox/`、`projects/tests/` 或 `projects/candidates/`,把这类验证对象从 `active` 中隔离出去? + + 这是我尝试在这里写文章,发现没法进行下去。我又回到了旧的写作流程上,在`knowledge-vault`中,我实际上已经完成了文章的撰写工作: + * `C:\Users\wangq\Documents\Codex\knowledge-vault\discussions\article-discussions\认知截肢与无摩擦滑流\`记录全部的讨论交流: + * 有主笔/韩愈的两次会话,比如`认知截肢与无摩擦滑流讨论1-韩愈.md` + * 有与各提纲评审员的多次会话讨论,比如`认知截肢与无摩擦滑流评审-巨人.md`,`认知截肢与无摩擦滑流评审1-张辽.md`等 + * 有提纲的历次版本,比如`认知截肢与无摩擦滑流提纲1.0.md` + * 有文章的metadata,`认知截肢与无摩擦滑流提纲Metadata.md` + * `C:\Users\wangq\Documents\Codex\knowledge-vault\sayings\2026\2026-06-13-cognitive-amputation.md`是成稿 + + 我的想法:我后续还是计划在这里尝试写作,但是项目推动决策会更灵活——由我来判断,这里准确说是工具调用地,而不是生产地。帮我记录一些讨论过程,讨论结果,省一些体力活;而不是自行决定如何往下跑。 + +2. “已决定写作”到底需要多强? + 是用户说“这要写成文章”就够,还是必须同时有:工作标题、目标读者、材料范围、当前命题、下一步产物?如果不定义,`material_intake` 很容易继续吸入开放讨论。 + + 在这里建立项目,就意味着决定进入写作。前期工作在`knowledge-vault`中已经完成了。 + 比如,`2026-06-04-Sanguo-test-slug`,实际上素材部分包括了四部分,这些完毕后,才会进入到写作阶段: + * `C:\Users\wangq\Documents\Codex\knowledge-vault\discussions\agents\社会学家GPT\社会学讨论.md`,实际上有历史学讨论和社会学讨论; + * `C:\Users\wangq\Documents\Codex\knowledge-vault\discussions\agents\虎贲卫&龙骧营\思想考古\短视频时代的知识论危机-思想考古过程.md`,是思想考古讨论过程; + * `C:\Users\wangq\Documents\Codex\knowledge-vault\discussions\agents\虎贲卫&龙骧营\思想考古\短视频时代的知识论危机-思想考古报告.md`,是思想考古报告 + +--- + +我考虑的,在这里的工作流程为: +1. 我在Web上完成素材,包括讨论稿、报告这些内容 +2. 我在Web上完成初步提纲提炼后进入`writing-workbench`。我建立文章项目,并提供或者指出原始提纲这些文件路径。 + 1. 之所以这样考虑,是因为素材内容量很大,必须使用高上下文的LLM,通盘了解后,才能有个初步提纲 + 2. 即使初步提纲出来,也可能存在未充分利用现有素材的情况 +3. `writing-workbench`的起始阶段从提纲评审开始: + 1. 基于初步提纲,需要对素材进行压缩,但是要考虑损失的情况,即本身提纲对素材利用不充分,在压缩时反而把素材的那部分内容去掉了 + 2. 基于压缩的素材和提纲,调用评审智能体进行评审,生成评审结果 + 3. 主笔智能体进行新提纲的撰写 + 4. 评审可能会进行多轮 +4. 撰写阶段,基于评审后的提纲和素材生成文章正文初稿 + +期间,所有的决策,包括是否再次评审,谁来评审,是否进入撰写,撰写是基于章还是基于节,等等,都由我/用户显示发指令进行。 + +--- + +考虑到现在的流程不完善,我考虑初期`writing-workbench`分为两个过程: +1. 定义需要的能力,包括智能体或者Skill;由CCPE System或者Skills-vault来负责完成。 +2. 调用具体的智能体或者Skill完成具体的工作。 + +定位:对于过程1,`writing-workbench`相当于是甲方,规划自己的工作计划,调用的工具/Agent/Skill,缺失的部分由乙方(CCPE,Skills)提供。 + +`writing-workbench`工作过程产物,全部保留在自己的工作目录下,包括素材的加工,评审员、主笔的讨论内容,不回到`knowledge-vault`。 +`knowledge-vault`中的成果正文部分,也由我自行维护。 + +--- + +基于以上内容,重新规划下`writing-workbench`,假设不考虑/不借鉴现有的规则,你有哪些问题? + +基于你这版定位,我会把问题重新聚焦为:`writing-workbench` 不是“生产地”,而是用户主控写作流程中的工具调用地、记录地、临时加工地。那么关键问题如下。 + +**一、项目入口** + +1. 一个 `writing-workbench` 项目是否必须已经有“Web 初步提纲”? + 如果必须,那么项目入口不再是 `material_intake`,而是 `outline-review-intake`。 + +2. 项目创建时,最低输入是什么? + 我建议至少是:原始提纲路径、素材来源清单、用户给出的当前写作目标。是否还需要工作标题、目标读者、预期文章类型? + +3. 如果 Web 上只完成了素材讨论,还没形成初步提纲,是否禁止建项目? + 这会决定 `writing-workbench` 是否允许 candidate 项目。 + +**二、素材处理** + +4. 素材压缩的目标是谁来定义? + 是“服务当前提纲评审”,还是“尽量保留全部潜在写作可能性”?这两者会导向完全不同的压缩策略。 + +5. 当“初步提纲可能漏掉素材重点”时,压缩产物应分几层? + 例如:`outline-aligned digest`、`unused-material candidates`、`risk-of-loss notes`。否则压缩会强化旧提纲的盲区。 + +6. 素材加工结果是否全部留在项目内? + 你已经倾向“全部留在 writing-workbench”,那还要不要保留 source-map 指向 knowledge-vault 原文,防止项目内压缩稿变成事实源? + +**三、评审调用** + +7. 评审智能体是由 `writing-workbench` 直接调用,还是只生成 invocation/prompt,由用户去 Web 或其他平台调用? + 这决定“真实调用记录”怎么保存。 + +8. 每次评审是否都必须保存完整讨论过程? + 你说要省体力活、记录讨论过程。需要明确最低记录:完整 session、最终 report、decision-ready summary,三者是否都必须有? + +9. 评审员列表由谁决定? + 默认不自动派发,那么项目文档里应该只提供“候选评审能力清单”,每轮由用户显式点名。 + +**四、主笔与提纲迭代** + +10. 主笔智能体重写提纲时,输入权威顺序是什么? + 用户原始提纲、素材压缩稿、评审报告、用户裁决,谁优先?如果评审意见冲突,主笔能不能自行取舍? + +11. 多轮评审什么时候停止? + 既然停止由用户决定,系统是否只负责提示“可选下一步”,不能声明“已通过/应进入正文”? + +12. 新提纲版本如何编号? + 需要区分 Web 初始提纲、评审后提纲、用户手修提纲、主笔修复提纲,否则后面会混。 + +**五、正文撰写** + +13. 正文生成默认按章、按节,还是由用户每次指定? + 你已明确由用户决定,那 playbook 应禁止自动从提纲进入全文生成。 + +14. 正文初稿生成时,是否允许主笔补充素材外内容? + 如果允许,要标注“模型补充”;如果不允许,要强制 source-grounded。 + +15. 文章正文成稿是否回写 knowledge-vault? + 你说 knowledge-vault 成果正文由你自行维护,那么 `writing-workbench` 只保存项目过程和可选草稿,不负责发布归档。 + +**六、能力建设与调用分离** + +16. “定义需要的能力”和“调用能力完成工作”是否应成为两个明确模式? + 例如: + - `capability-request mode`:写需求,交给 CCPE / skills-vault。 + - `execution mode`:调用已有 Agent / Skill 处理当前项目。 + +17. 缺能力时,项目是否暂停? + 还是允许用 manual placeholder?如果允许,占位产物必须不能冒充正式 Agent 输出。 + +18. `writing-workbench` 作为甲方,向 CCPE / skills-vault 提需求时,需求单放在哪里? + 项目内?全局 `requirements/`?还是 `ccpe-requests/`? + +**七、目录和状态** + +19. `projects/active` 是否只放“用户已经决定要推进的文章工具调用项目”? + 如果是,`2026-06-04-Sanguo-test-slug` 可以不是错误,只是它缺少项目壳和 source-map。 + +20. 是否需要新增状态,而不是新增目录? + 例如:`outline_review_intake`、`material_compression`、`review_round`、`outline_repair`、`drafting_requested`、`paused_waiting_user_decision`。 + +21. 当前 `material_intake` 这个阶段名是否要废弃或降级? + 按你的新流程,真正入口不是材料进入,而是“已有 Web 提纲后的评审准备”。 + +我认为最核心的问题只有一个:`writing-workbench` 的第一阶段到底叫不叫“提纲评审准备”?如果答案是是,那么整个仓库应围绕“用户带着 Web 提纲和素材路径进来,Codex 帮忙压缩、调用、记录、整理,但不自行推进阶段”重写。 + +# 3 + +**一、项目入口** + +1. 一个 `writing-workbench` 项目是否必须已经有“Web 初步提纲”? + 是的,现在的上下文窗口限制,导致`material_intake`无效,所以必须已经有“Web 初步提纲”。 + +2. 项目创建时,最低输入是什么? + 我有不同的主笔,这个其实已经确定了文章的类型。比如启动时,我要求主笔是`韩愈`,那就是学术性散文;是`蒙田`,那就是随笔。 + 你可以读一下这个提纲,`C:\Users\wangq\Documents\Codex\knowledge-vault\discussions\article-discussions\认知截肢与无摩擦滑流\认知截肢与无摩擦滑流提纲1.0.md`。这个就是初稿提纲的范本,其他初稿提纲都会是这个样。 + +3. 如果 Web 上只完成了素材讨论,还没形成初步提纲,是否禁止建项目? + 是的,如果没有提纲,不会开始项目。 + +**二、素材处理** + +4. 素材压缩的目标是谁来定义? + 保留全部潜在写作可能性。 + +5. 当“初步提纲可能漏掉素材重点”时,压缩产物应分几层? + 例如:`outline-aligned digest`、`unused-material candidates`、`risk-of-loss notes`。否则压缩会强化旧提纲的盲区。 + 我觉得压缩,是否体现原报告/讨论稿内容即可,不同的材料可能压缩的方式也不一样: + * 我往往会基于`思想考古报告`来写作,这个甚至可以考虑不压缩; + * 我提供的我自己的`过往文章`,或者`讨论稿`,这个可能会有些发散,可以考虑压缩多一些。 + 如何具体压缩,可能需要试跑几轮后,才能初步确定。 + +6. 素材加工结果是否全部留在项目内? + 素材加工的结果全部保留在项目内。 + 保留`source-map`,这样备查。至少可以查到原文,发现是否过度压缩,有损压缩。 + +**三、评审调用** + +7. 评审智能体是由 `writing-workbench` 直接调用,还是只生成 invocation/prompt,由用户去 Web 或其他平台调用? + 这决定“真实调用记录”怎么保存。 + 由 `writing-workbench` 通过子会话调用评审智能体、主笔智能体和其他技能。 + 如果用户去 Web 或其他平台调用,那这个和我现在写文章没啥区别,`writing-workbench`就没有必要存在了。 + +8. 每次评审是否都必须保存完整讨论过程? + 是的,需要记录讨论过程,完整session,最终report都必须要。 + +9. 评审员列表由谁决定? + 甚至都不需要提供“候选评审能力清单”,每轮用户自行显示点名。 + +**四、主笔与提纲迭代** + +10. 主笔智能体重写提纲时,输入权威顺序是什么? + 现在主笔修订提纲一般是这样的过程,可以参考: + 1. 我同时提供多份评审意见,我的反思,我的意见,让主笔汇总判断合理性 + 2. 基于主笔的判断,我发出修订指令,或者继续调整方向的指令;关键决策是我做的。 + 3. 主笔完成修订 + +11. 多轮评审什么时候停止? + 系统可以提供建议,提示下一步。不能声明`已通过`,声明了也没意义。 + +12. 新提纲版本如何编号? + 保持一致的编号即可,web初始提纲就是1.0,评审后修订的,从2.0开始。 + `评审后提纲`不准确,评审只有评审意见,基于评审意见才开始修订;用户不会主动修改提纲,用户发出的也是评审意见,等同于评审员。 + 个别微调的,可以起小版本号,比如`3.1`。 + +**五、正文撰写** + +1. 正文生成默认按章、按节,还是由用户每次指定? + 绝对禁止全文生成,否则干的多错的多。这个正文生成,已经作为主笔的工作方式,内嵌到其提示词中了。主笔不会去全文生成,我们这里清楚这个逻辑就行。 + +2. 正文初稿生成时,是否允许主笔补充素材外内容? + 允许,本身评审意见就会要求补充案例,这个很可能超出了素材。这里可以考虑要标注。 + +3. 文章正文成稿是否回写 knowledge-vault? + 是的,因为knowledge-vault 成果正文是面向发布的,还有发布的相关内容要填写。这里只负责项目过程,草稿生成就行。 + 当然本地留一份正文完整稿,也是可以的;因为这个是后续润色优化的基础。 + 不保留,我就会指向到`knowledge-vault 成果正文`作为润色的源。 + +**六、能力建设与调用分离** + +1. “定义需要的能力”和“调用能力完成工作”是否应成为两个明确模式? + 是的,应该是两个明确的模式: + - `capability-request mode`,这个是“供应商”的工单 + - `execution mode`,这个是自己的工作工单 + +2. 缺能力时,项目是否暂停? + 产生供应商工单后暂停。直到我通知配套的Agent准备好。 + 绝不能冒充,因为素材多,主会话会很快超出上下文。而且尤其是专家智能体,冒充的完全没质量。 + +3. `writing-workbench` 作为甲方,向 CCPE / skills-vault 提需求时,需求单放在哪里? + 全局的`requirements/`,根据我最开始提供的文档,明确是CCPE还是skills-vault的。 + 然后我根据这个需求单,去到具体项目打造。 + +**七、目录和状态** + +1. `projects/active` 是否只放“用户已经决定要推进的文章工具调用项目”? + 如果是,`2026-06-04-Sanguo-test-slug` 可以不是错误,只是它缺少项目壳和 source-map。 + 我觉得可以考虑再做一个简化,我们这个是写文章的项目,不是开发项目。所以不是特殊情况,一定会做完。简化的结果就是`projects/`不再分子文件夹了。 + +2. 是否需要新增状态,而不是新增目录? + 这个状态可能不一定准,实际很有可能,提纲审了几轮后,我再补充素材,需要重新压缩加工…… + 我倾向于用文件夹。 + +3. 当前 `material_intake` 这个阶段名是否要废弃或降级? + 是的`material_intake`这个阶段实际上是评审提纲的子阶段了,对素材的加工。 + 而对素材进行加工的原因就一个,现在的上下文窗口限制。 + +> 我认为最核心的问题只有一个:`writing-workbench` 的第一阶段到底叫不叫“提纲评审准备”?如果答案是是,那么整个仓库应围绕“用户带着 Web 提纲和素材路径进来,Codex 帮忙压缩、调用、记录、整理,但不自行推进阶段”重写。 + +是的。整个仓库应围绕“用户带着 Web 提纲和素材路径进来,Codex 帮忙压缩、调用、记录、整理,但不自行推进阶段”重写 + +读了你给的提纲范本。这个范本说明 `writing-workbench` 的入口确实不应该是“材料进入”,而应该是“已有 Web 初纲后的提纲评审与修订工程”。它已经包含:主笔类型、文章体裁、统摄隐喻、结构原型、核心论点、模块目标、写作协议。也就是说,项目启动时已经越过了开放观点生成阶段。 + +我建议把 `writing-workbench` 重规划为下面这个定位。 + +**核心定位** + +`writing-workbench` 是文章写作的本地工具调用与过程记录场。 + +它不负责开放素材讨论,也不负责判断文章是否值得写。用户已经在 Web / knowledge-vault 中完成前期讨论和初纲生成后,才进入这里。进入后,它负责: + +- 接收 Web 初稿提纲和素材路径。 +- 围绕提纲评审准备上下文。 +- 对素材做必要压缩或引用整理。 +- 通过真实子会话调用主笔、评审员、Skill。 +- 保存完整 session、report、提纲版本、用户裁决和草稿。 +- 在缺能力时生成供应商工单,然后暂停。 +- 不自行推进阶段,不冒充专家,不自动全文生成。 + +**推荐结构** + +我会建议废掉 `projects/active / completed / abandoned` 这种开发项目式分层,改成: + +```text +projects/ + 2026-06-04-sanguo/ + 2026-06-13-cognitive-amputation/ +requirements/ + ccpe/ + skills-vault/ +templates/ + article-project/ +``` + +每个文章项目内部用状态和文件夹表达进度,而不是靠 `active` 目录表达。因为你这里的文章项目大概率都会完成,中途真正重要的是“当前停在哪个用户决策点”。 + +项目内建议结构: + +```text +project.md +source-map.md +status.md +decision-log.md + +00-intake/ + initial-outline-v1.0.md + intake-note.md + +01-materials/ + source-digests/ + source-links.md + compression-notes.md + +02-outline-review/ + round-01/ + review-brief.md + reviewers/ + zhang-liao/ + session.md + report.md + giant-cognition/ + session.md + report.md + user-reflection.md + synthesis-for-writer.md + +03-outline-repair/ + writer-session-v2.0/ + session.md + outline-v2.0.md + repair-notes.md + +04-drafting/ + section-sessions/ + draft-v1.md + +05-revision/ + revision-sessions/ + draft-v2.md + +publish/ + local-final.md + knowledge-vault-target.md +``` + +**工作流** + +入口固定为: + +```text +Web 初稿提纲 + 素材路径 + 主笔身份 -> writing-workbench 项目 +``` + +第一阶段不叫 `material_intake`,而叫 `outline-review-prep` 或 `outline-review-intake`。素材加工只是它的子任务,原因是上下文窗口限制,不是因为项目还没进入写作。 + +流程应是: + +1. 用户创建项目,提供初纲和素材路径。 +2. Codex 建立 `source-map`,复制或引用初纲为 `initial-outline-v1.0.md`。 +3. Codex 根据评审需要处理素材:有些报告不压缩,有些讨论稿压缩,有些过往文章只摘取相关段落。 +4. 用户点名评审员。 +5. Codex 通过真实子会话调用评审员,保存完整 `session.md` 和 `report.md`。 +6. 用户提供反思、判断和修订指令。 +7. Codex 调用主笔子会话,生成 `outline-v2.0.md`。 +8. 是否继续评审、是否进入正文、按章还是按节写,全部等待用户显式指令。 +9. 正文草稿保留在本项目;发布成稿由用户维护到 `knowledge-vault/sayings`,项目内可记录目标路径。 + +**两个模式** + +你提出的“甲方 / 供应商”关系很关键,应写成正式模式: + +`execution mode`:当前文章项目内使用已有 Agent / Skill 完成具体工作。 + +`capability-request mode`:发现缺少 Agent / Skill / Runtime 时,生成需求单到: + +```text +requirements/ccpe/ +requirements/skills-vault/ +``` + +生成需求单后,当前文章项目暂停,直到用户确认供应商能力已准备好。禁止用主会话模拟专家输出。 + +**关键规则** + +我建议写进仓库的硬规则有五条: + +1. 没有 Web 初稿提纲,不创建文章项目。 +2. 没有用户点名,不调用评审员。 +3. 没有真实子会话,不产生正式评审报告。 +4. 没有用户裁决,不进入下一阶段。 +5. 禁止全文生成;正文写作粒度由用户指令和主笔提示词共同决定。 + +**我推荐的改造路线** + +有三种做法: + +1. 小改:只改 README / WORKBENCH / playbook,保留现有目录。 + 成本低,但旧结构里的 `active`、`material_intake`、完整 production runtime 惯性还会继续误导。 + +2. 中改:重写规则文档,新增 `requirements/`,项目不再分 active/completed,模板改成“初纲评审起步”。 + 这是我推荐的。它能匹配你的真实流程,又不会一上来重做全部历史项目。 + +3. 大改:把现有项目全部迁移成新结构,重建模板、索引、状态协议、需求工单协议。 + 更干净,但现在可能过重。 + +我的建议是走第二种:先把 `writing-workbench` 明确改成“Web 初纲后的提纲评审、主笔修订、正文草稿调用场”,再处理现有两个项目的归位。 + +# 4 + +我倾向于大改。甚至于我们重建一个新的项目都可以,因为现有的`writing-workbench`压根没用起来。 +`历史项目`在过去的`writing-workbench`没做起来,但实际上我已经按旧流程完成了,所以这个`历史项目`在这里也没有存在的必要了。 +且基于此,我之前已经重构了`knowledge-vault`。 + +这个远程仓库也只用了44KiB的存储空间。 +所以,你判断下,是重建新项目还是清空本项目重写。 + +我的判断:**清空本项目重写,不新建仓库。** + +原因很直接: + +1. `writing-workbench` 这个名字仍然准确 + 新定位还是写作工作台,只是从“文章生产 Runtime”改成“Web 初纲后的本地工具调用与过程记录场”。项目名不用换。 + +2. 现有仓库没有值得继承的工程资产 + 当前只有 3 个 commit,远程也很小。现有 README、WORKBENCH、模板、`projects/active` 结构基本都是旧假设产物,继续保留会持续误导后续会话。 + +3. 新建仓库会制造无意义边界 + 你已经围绕 `writing-workbench` 做了规划讨论,路径也稳定。换新仓库反而要解释“旧 writing-workbench 和新 writing-workbench 的关系”,这是额外负担。 + +4. 清空重写更符合这次重构性质 + 这不是版本迭代,而是入口范式变了:从 `material_intake -> article production` 改成 `Web 初纲 -> 提纲评审准备 -> 真实调用 -> 用户裁决 -> 分段正文草稿`。 + +我建议操作方式是: + +- 保留 `.git`、远程、仓库名。 +- 删除现有工作区内容。 +- 重建最小结构: + +```text +README.md +WORKBENCH.md +docs/ + operating-playbook.md + project-lifecycle.md + invocation-policy.md +requirements/ + ccpe/ + skills-vault/ +projects/ +templates/ + article-project/ +``` + +- 不迁移两个历史项目。 +- 只在新 README 里用一句话说明:旧结构已废弃,仓库于 2026-06-15 按“Web 初纲后的工具调用场”重建。 +- 如果你想保留旧内容作为参考,可以先打一个 tag 或分支,例如 `archive/pre-2026-06-15-rebuild`,然后清空 master 重写。 + +我不建议新建项目。除非你想连名字也改,比如 `outline-review-workbench`,否则保留 `writing-workbench` 清空重写是最干净的。 + +# 5 + +好的,我们在这个项目上清空重写。 +现在开始。 + +已在原 `writing-workbench` 仓库上清空重写,保留了 `.git` 和远程关系,没有新建仓库。 + +新结构现在是: + +```text +README.md +WORKBENCH.md +docs/ + capability-requests.md + invocation-policy.md + operating-playbook.md + project-lifecycle.md +projects/ +requirements/ + ccpe/ + skills-vault/ +templates/ + article-project/ + requirements/ +``` + +核心规则已经写入:项目必须从 Web 初稿提纲进入;`material_intake` 被移除;`projects/active/completed/abandoned` 被废弃;评审员和主笔必须真实子会话调用;缺能力时生成 `requirements/ccpe/` 或 `requirements/skills-vault/` 工单并暂停;禁止默认全文生成。 + +验证结果:文件清单只剩新结构;旧术语扫描没有命中 `TBD/TODO/material_intake/Article Production Orchestrator/Outline Review Runtime`;`git status` 显示旧 scaffold 删除、新文档和模板新增/修改。当前变更还没有 stage 或 commit。 + +# 6 + +我们本次重构工作完成,有了一个初始化完成的环境。 +现在做一次远程提交,并打上tag。 + + + +已完成远程提交和打 tag。 + +本次提交: + +- Commit: `0721f81 rebuild: initialize writing workbench` +- Branch: `master` +- Tag: `v2026.06.15-init` + +已推送到远程: + +- `origin/master` -> `0721f81127e5911f7ca2c72392744bf904a353d7` +- `v2026.06.15-init` -> 已在远端存在 + +本地工作区现在是干净的。 +::git-stage{cwd="C:\Users\wangq\Documents\Codex\writing-workbench"} +::git-commit{cwd="C:\Users\wangq\Documents\Codex\writing-workbench"} +::git-push{cwd="C:\Users\wangq\Documents\Codex\writing-workbench" branch="master"} + +# 7 + +由于目前CCPE现在主要是为本项目服务的,所以对CCPE来说,你有什么补充说明没有? +你需要一个本地项目说明么?刚改造知识库,准备了一个,你看你需要这个文件不,`C:\Users\wangq\Documents\Codex\knowledge-vault\PROJECTS.md` + +需要。对 CCPE 来说,最好也有一个本地项目说明,而且我建议放在 `ccpe-system` 根目录,名字可以直接叫 `PROJECTS.md` 或 `PROJECT-RELATIONSHIPS.md`。 + +我看了 [PROJECTS.md](C:/Users/wangq/Documents/Codex/knowledge-vault/PROJECTS.md)。它作为五库关系总表是有用的,但对 CCPE 还不够,因为现在 `writing-workbench` 已经重写了定位:它不是泛泛的“已决定写作后的文章项目现场”,而是更具体的 **Web 初纲后的本地工具调用、真实子会话调用、过程记录场**。CCPE 需要知道这个新入口,否则它后续很容易继续按旧的 Article Production Runtime 方向过度设计。 + +我建议 CCPE 的本地说明补充这些点: + +1. `writing-workbench` 是当前第一服务对象 + CCPE 现在优先供应:主笔 Agent、评审 Agent、提纲评审 invocation protocol、真实子会话记录规范、素材压缩/上下文包规则。 + +2. CCPE 是供应商,不是项目现场 + 文章项目过程、评审 session、正文草稿不进 CCPE;CCPE 只保存可复用的 Agent / Runtime / Model Card / Protocol。 + +3. 从 `writing-workbench/requirements/ccpe/` 接收工单 + CCPE 不主动猜测要造什么能力。只有当 writing-workbench 产生供应商工单,CCPE 才进入能力建设。 + +4. 明确禁止模拟正式输出 + 这条要写进 CCPE 根说明:packet / prompt / dispatch pack 不等于执行;正式评审和主笔输出必须来自真实 invocation。 + +5. CCPE 当前的优先能力清单 + 例如:韩愈主笔、张辽评审、巨人认知、认知显影、outline review packet、review report contract、writer repair packet。 + +6. 与 `skills-vault` 分工 + 如果是确定性脚本、文件转换、批处理,进入 `skills-vault`;如果是专家判断、Runtime、Agent、协议,进入 CCPE。 + +所以我的建议是:**需要这个文件,而且应该以 `writing-workbench` 为第一消费场景重写一版 CCPE 本地项目关系说明**。`knowledge-vault/PROJECTS.md` 可以作为总关系参考,但不能直接复制过去。 + +# 8 + +我的意思是: +1. 你的项目库里需要一个Projects这样的文件么,若需要,你可以构造一个自己用的。 +2. 我后续要优化/重构CCPE,你有什么要给它的特殊说明,可以考虑出一个文件。我作为上下文放进初始会话中。 + +我新增了两个文件: + +- [PROJECTS.md](C:/Users/wangq/Documents/Codex/writing-workbench/PROJECTS.md) + 这是 `writing-workbench` 自己用的项目关系说明,明确它消费 `knowledge-vault / ccpe-system / skills-vault`,但不拥有上游知识、canonical Agent 或自动化工具源码。 + +- [docs/ccpe-rebuild-context.md](C:/Users/wangq/Documents/Codex/writing-workbench/docs/ccpe-rebuild-context.md) + 这是给后续 CCPE 优化/重构会话使用的上下文文件,重点说明:CCPE 现在应作为 `writing-workbench` 的供应商,优先提供主笔、评审员、真实调用协议、no-simulation 规则、素材压缩/上下文准备规则,而不是继续设计完整自动写作 Runtime。 + +当前工作区只有这两个新增文件未提交。 + diff --git a/discussions/technology/Codex/0.规划与重构/2026-06-15-CCPE补充.md b/discussions/technology/Codex/0.规划与重构/2026-06-15-CCPE补充.md new file mode 100644 index 0000000..b88dcd0 --- /dev/null +++ b/discussions/technology/Codex/0.规划与重构/2026-06-15-CCPE补充.md @@ -0,0 +1,1278 @@ +# 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 重构时必须知道自己处在整体体系中的位置,否则会出现两个风险: + +1. 把 CCPE 重构成另一个“总纲领仓库”,重复 HiFi Agent Studio; +2. 把 CCPE 重构成项目执行仓库,吞掉 `writing-workbench`、`video-workbench`、`knowledge-vault` 或 `skills-vault` 的职责。 + +给 Codex 的最小四层说明如下: + +```text +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 工具属于工具实现或能力供给层: + +```text +skills-vault / MCP / CLI / API += 工具实现层 / 能力供给层 += 可被 CCPE 登记为依赖 += 不属于 CCPE 的核心资产源码 +``` + +所以,CCPE 的位置是: + +```text +CCPE = 架构工坊 + 资产登记中心 + Agentic artifact 设计系统 +``` + +不是: + +```text +CCPE ≠ 顶层方法论仓库 +CCPE ≠ 项目运行仓库 +CCPE ≠ automation Skill 源码仓库 +CCPE ≠ MCP / CLI 工具源码仓库 +``` + +--- + +## 2. CCPE 重构后的核心定位 + +重构后的 CCPE System 应定义为: + +```text +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. +``` + +中文定位: + +```text +CCPE System 是 Agentic 时代的智核工程工坊。 +它负责把 Prompt、Agent、Skill、Runtime、Committee、Model Card、Model Index、外部工具登记等 AI 资产分类、建模、审计、重构和维护。 +``` + +CCPE 的第一职责仍然是: + +```text +Classify Before Creating +先分类,再创建 +``` + +也就是: + +1. 判断这个东西到底是什么; +2. 判断它是否应该属于 CCPE; +3. 判断它是否应该是 Lite、Agent、Skill、Runtime、Model Card、Model Index、Committee、Integration Registration、Project Runbook 或 external automation Skill; +4. 再决定是否创建、重构、登记或拒绝纳入 CCPE。 + +--- + +## 3. CCPE 不应该做什么 + +重构时必须把这些红线写进 README、AGENTS.md 或 `ccpe-protocol/ccpe-boundaries.md`。 + +### 3.1 CCPE 不复制 HiFi Agent Studio 和 Handbook + +CCPE 可以声明: + +```text +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 的源码仓库。 + +例如: + +```text +fix-title +markdown-normalizer +citation-checker +report-exporter +source-splitter +tts-batch-generator +image-prompt-exporter +``` + +这些源码不应迁移到 CCPE。 + +CCPE 只在必要时做架构登记: + +```text +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。 + +默认路线应是: + +```text +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,但必须遵循: + +```text +Default Lite, Escalate by Evidence +``` + +不能把一次性任务默认升成治理级 Runtime。 + +--- + +## 4. 重构后的 CCPE 资产分类 + +CCPE 重构时,应将资产分类扩展为以下几类。 + +### 4.1 CCPE-Lite + +轻量专家提示词 / Prompt Card。 + +适用: + +* 单专家角色; +* 人类直接调用; +* Web / GPT / Gemini / Claude 等 chat 产品; +* 不需要工具、状态、handoff、长期 runtime; +* 有独特认知姿态和工作方法。 + +典型: + +```text +张辽红队评审 +韩愈主笔 +苏格拉底式提问者 +文章审稿人 +战略思维助手 +``` + +Lite 不是低级形态。 +在 Web-style expert use 中,Lite 可以是生产级形态。 + +### 4.2 CCPE-Agent + +长期可维护、可组合、可评估的工作角色。 + +适用: + +* 会参与 multi-agent workflow; +* 需要明确 input/output contract; +* 需要 authority; +* 可能调用工具或 Skill; +* 需要 handoff; +* 需要 evaluation; +* 需要跨项目复用。 + +典型: + +```text +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。 + +典型: + +```text +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。 + +它可能没有脚本,主要是方法、流程、检查清单、推理协议、输出模板和验证标准。 + +典型: + +```text +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 区分: + +```text +CCPE-Skill = 认知 / 方法 / 评估 / 流程能力规格 +automation Skill = 可安装、可执行、可测试的工具源码 +``` + +### 4.5 CCPE-Runtime + +多阶段、多角色、有状态、有 handoff 或工具调用的运行协议。 + +Runtime 分三类: + +```text +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 负责收集、整理、格式化、路由、归档。 + +典型: + +```text +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 依赖但不拥有源码的外部能力。 + +包括: + +```text +skills-vault automation skills +MCP servers +CLI tools +API services +installed local tools +platform-specific skills +``` + +Integration Registration 只记录架构元数据,不复制实现源码。 + +示例目录: + +```text +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 应记录: + +```yaml +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 重构目录 + +建议重构后的目录大致如下: + +```text +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/ +``` + +关键变化: + +1. 新增 `ccpe-boundaries.md`; +2. 新增 `ccpe-artifact-taxonomy.md`; +3. 新增 `ccpe-governance-adapter.md`; +4. 新增 `integrations/`; +5. `skills/tool/` 不再作为 automation script source; +6. automation skill source 属于 `skills-vault`; +7. CCPE 中如需登记 external tool skill,放 `integrations/skills-vault/` 更干净。 + +--- + +## 6. CCPE 与 skills-vault 的边界 + +这是重构时必须写清楚的核心边界。 + +### 6.1 一句话原则 + +```text +CCPE 资产拥有或组织业务目标与认知结构; +skills-vault 资产执行可复用自动化动作。 +``` + +或者: + +```text +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。 + +典型对象: + +```text +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` 是本机安装面,不是源码主仓库。 + +```text +skills-vault = source of truth +.agents/skills = runtime installation copy +ccpe-system/integrations = architecture registration +``` + +### 6.5 MCP 类似处理 + +MCP server、CLI、API 工具都类似 external capability。 + +原则: + +```text +实现源码不进 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: + +```text +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。 + +若输入是: + +```text +automation script / installable skill source +``` + +应建议进入: + +```text +skills-vault +``` + +若输入是: + +```text +project-specific runbook / execution record / topic docs / writing project output +``` + +应建议进入: + +```text +knowledge-vault / writing-workbench / video-workbench +``` + +若输入是: + +```text +agent spec / runtime spec / model card / committee / architecture registration +``` + +才进入: + +```text +ccpe-system +``` + +### 7.3 Registrar Mode + +建议新增: + +```text +Registrar Mode +``` + +用于登记外部能力,而不是复制外部源码。 + +适用: + +* skills-vault skill; +* MCP server; +* CLI tool; +* API service; +* installed local capability。 + +输出: + +```text +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: + +```text +artifact path +current type +suspected target type +business use +reuse level +risk level +owner +migration action +``` + +迁移动作包括: + +```text +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 + +例如: + +```text +张辽 +韩愈 +强哥的徒弟 +认知显影 +巨人认知 +``` + +如果它们原本是成熟 Web-style expert prompt,默认保持: + +```text +agents/lite/ +``` + +只有满足条件才升级: + +* 需要作为 workflow node; +* 需要调用 tools / skills; +* 需要 authority; +* 需要 handoff; +* 需要 evaluation; +* 需要 invocation record; +* 需要长期 runtime participation。 + +### 8.3 模型优先抽成 Model Card,不急着 Skill 化 + +如果某个 Agent 内含稳定认知模型,应优先抽成: + +```text +model-cards/ +``` + +而不是直接做 Skill。 + +判断: + +```text +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 必须包含 + +```yaml +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 必须包含 + +```yaml +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 必须包含 + +```yaml +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 必须包含 + +```yaml +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 必须包含 + +```yaml +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 必须包含 + +```yaml +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 能判断它应该属于: + +```text +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 能生成: + +```text +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。 +它会先判断: + +```text +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 + +至少创建或更新: + +```text +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 + +创建: + +```text +integrations/skills-vault/ +integrations/mcp/ +integrations/cli-tools/ +integrations/api-services/ +``` + +并加入 README 说明: + +```text +CCPE registers external capability dependency here. +CCPE does not own implementation source here. +``` + +### Batch 4:重建 templates + +至少包括: + +```text +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 个典型样本: + +```text +一个成熟 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 的核心执行指令 + +可以直接附在上下文最后: + +```text +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 工坊升级为: + +```text +Agentic architecture forge ++ cognitive model registry ++ runtime specification system ++ external capability registration center +``` + +它应该回答: + +```text +这个 AI 资产是什么? +它该不该属于 CCPE? +它应该放在哪里? +它依赖哪些外部能力? +它是否需要 Agent / Skill / Runtime / Model Card? +它的权限、状态、评估、调用真实性和生命周期是什么? +``` + +它不应该变成: + +```text +所有项目 runbook 的大杂烩 +所有 automation scripts 的源码仓库 +所有旧 Prompt 的强行 Agent 化工厂 +所有任务默认 Full Runtime 的流程怪物 +``` + +重构后的 CCPE 应该更像一个清晰的“智核架构工坊”: +负责分类、建模、登记、审计、迁移和维护; +不吞并项目、不吞并工具源码、不替代上层方法论。 diff --git a/rules/Templates/Agentic-Engineering-Handbook.md b/rules/Templates/Agentic-Engineering-Handbook1.0.md similarity index 99% rename from rules/Templates/Agentic-Engineering-Handbook.md rename to rules/Templates/Agentic-Engineering-Handbook1.0.md index a1a501b..63704fe 100644 --- a/rules/Templates/Agentic-Engineering-Handbook.md +++ b/rules/Templates/Agentic-Engineering-Handbook1.0.md @@ -200,4 +200,5 @@ * **E4 Expert Similarity (专家相似度)**:测度结论与人类专家直觉的重合度,以及偏差部分的逻辑可解释性。 * **E5 Decision Utility (决策效用)**:终极业务指标。验证系统的介入是否真实帮助人类专家完成了更优、更快、更低耗能的决策。 * **E6 Calibration Test (校准测试)**:评测系统的纠错摩擦力。检验当系统犯错时,专家是否能低成本地指出错误,系统能否即时闭环修复。 -* **E7 Governance Test (治理测试)**:审计视角的终极测试。核查系统的 trace 追踪完整度、权限隔离 (Authority) 强度、回滚机制与责任边界清晰度。 \ No newline at end of file +* **E7 Governance Test (治理测试)**:审计视角的终极测试。核查系统的 trace 追踪完整度、权限隔离 (Authority) 强度、回滚机制与责任边界清晰度。 + diff --git a/rules/Templates/Agentic-Engineering-Handbook1.1.md b/rules/Templates/Agentic-Engineering-Handbook1.1.md new file mode 100644 index 0000000..aeb67a2 --- /dev/null +++ b/rules/Templates/Agentic-Engineering-Handbook1.1.md @@ -0,0 +1,2452 @@ +# Agentic Engineering Handbook (V1.1) + +*HiFi Agent Studio 运行治理与现场规程* + +## Profile + +**author**: Wantsong +**version**: V1.1 +**date**: 2026-06-15 +**status**: active-candidate +**governing doctrine**: HiFi Agent Studio +**related system**: CCPE System / Knowledge Vault / Writing Workbench / Video Workbench + +--- + +## 0. 守则定位与绝对边界 + +本手册是团队在 Agentic 工程实战中的硬性操作底线。 + +它将 HiFi Agent Studio 的高维架构沙盘,转化为现场可执行的工程界桩,聚焦于解决: + +```text +如何开工 +如何分诊 +如何限流 +如何调用 +如何防伪 +如何控权 +如何熔断 +如何回滚 +如何验收 +如何避免系统自我繁衍 +``` + +本手册不是方法论宣言,而是运行治理规程。 + +HiFi Agent Studio 回答: + +```text +我们为什么这样做 AI? +什么是高保真 Agent? +什么复杂性不可被降维? +什么责任不可外包? +``` + +本手册回答: + +```text +一个 Agentic 项目来了,第一步填什么? +开什么档位? +允许哪些 Agent / Skill / Tool? +哪里必须停? +什么产物是真的? +什么产物只是模拟? +什么成本应记入哪本账? +``` + +--- + +### 0.1 守则效力 + +本手册服从并承载 HiFi Agent Studio 的核心纲领,同时作为一切局部 Agentic 项目的行动准则。 + +当规则发生冲突时,执行优先级为: + +```text +1. 客户法理与商业硬性约束 +2. HiFi Agent Studio 宪法原则 +3. 本 Agentic Engineering Handbook +4. CCPE System 资产建造规范 +5. 具体项目 Runbook +6. 平台 / 插件 / 工具默认行为 +``` + +若底层平台、自动化框架、插件或 Skill Pack 的默认行为与本手册冲突,必须以本手册为准。 + +--- + +### 0.2 反向兜底 + +任何自动化框架,例如 Codex、Claude Code、OpenClaw、SuperPowers 或其他 Agentic Runtime,其底层默认行为若出现以下倾向: + +```text +遇错无限重试 +自动创建子线程 +自动扩展目录结构 +自动补全缺失产物 +自动进入重型评审流程 +自动调用高权限工具 +自动将模拟输出包装成正式结果 +``` + +必须立即挂起进程,并向上请求架构裁决。 + +严禁为了适配底层工具的便利性,而让步甚至阉割以下治理底线: + +```text +执行真实性 +最小权限 +成本分账 +绝对停止权 +Human Gate +来源保真 +数据安全 +责任边界 +``` + +--- + +### 0.3 模拟与正式执行的边界 + +绿野仙踪阶段允许人类专家、主控节点或单一模型模拟 Agent,以低成本验证价值流。 + +但所有此类产物必须被标记为: + +```text +simulation_only: true +formal_output: false +excluded_from_synthesis: true +``` + +模拟产物只能用于价值验证、流程草图、人工参考,不得冒充正式 Agentic 输出进入生产决策链。 + +正式运行阶段必须具备真实 Invocation Record。 + +--- + +## 1. 任务入口与档位挂载 + +## Project Intake & Mode Selector + +在 Agentic 时代的极压舱内,算力失控与治理灾难往往始于入口处的定性溃败。 + +在敲下第一行 Prompt、创建第一个 Thread、调用第一个 Skill 或启动第一个 Worker 之前,必须完成强制分诊。 + +--- + +### 1.1 QPI 强制分诊 + +所有接管需求必须第一时间进行问题颗粒度探测,禁止含糊其辞地“先跑起来看看”。 + +#### 【Q】查询 / Question + +**核心匮乏**:数据或信息缺失。 +**场景特征**:线性因果,存在明确答案或可查询事实。 +**系统响应**:搜索、检索、数据库查询、RAG、工具 API。 +**默认架构**:单节点调用。 + +红线: + +```text +绝对禁止为 Q 域任务编排复杂多体流程。 +绝对禁止为单次查询启动委员会、覆盖审计或治理级 Runtime。 +``` + +示例: + +```text +查一个文件路径 +确认某个定义 +提取某段材料中的事实 +查询某个指标 +``` + +--- + +#### 【P】求解 / Problem + +**核心匮乏**:路径缺失。 +**场景特征**:目标明确,但需要工程化转换、拆解、生产或优化。 +**系统响应**:SOP、模板化约束、工具链、批量执行、人工抽检。 +**默认架构**:逻辑轮机或生产工坊。 + +P 域架构复杂性应优先倾注于: + +```text +稳定吞吐 +可验证输出 +低返工 +可复用生产线 +格式一致性 +上下文压缩 +批处理效率 +``` + +而不是多角色治理。 + +示例: + +```text +长文转分镜 +批量生成配音稿 +图片提示词生成 +文档拆分 +素材蒸馏 +报价模板生成 +标准报告初稿 +``` + +--- + +#### 【I】治理 / Issue + +**核心匮乏**:秩序、共识与责任边界缺失。 +**场景特征**:无唯一最优解,存在隐蔽变量、多方权衡、非遍历性风险或单向门决策。 +**系统响应**:战略透镜、人机回环、预设委员会、Human Gate、权限阻断。 +**默认架构**:Interactive Runtime 或 Governed Runtime。 + +I 域架构复杂性必须倾注于: + +```text +保真度 +责任锚定 +多视角张力 +审计可追踪 +人工裁决 +反例处理 +风险阻断 +``` + +绝不允许用并发掩盖判断逻辑的脆弱。 + +示例: + +```text +核心立意判定 +重大客户方案取舍 +战略级评审 +高风险心理诊断辅助 +不可逆商业决策 +模型边界裁决 +组织流程重构 +``` + +--- + +### 1.2 任务性质定性 + +完成 QPI 后,必须明确当前动作的终极标的。 + +同一个表面任务,可能属于完全不同的性质。 + +#### A. 一次性内容产出 + +系统运作仅为获取当下的单一结果材料。 + +示例: + +```text +整理一篇 5 万字讨论稿 +生成一个视频分镜 +提炼一次会议纪要 +写一份客户报告初稿 +``` + +默认要求: + +```text +Lite 档 +最小充分产物 +轻量记录 +禁止自动升级为 Runtime 建设 +``` + +--- + +#### B. 可复用能力沉淀 + +系统运作为了提炼可跨项目复用的资产。 + +示例: + +```text +把某个提炼方法沉淀为 Skill +把某个专家判断结构沉淀为 Model Card +把某类报告流程沉淀为 Workflow +把旧 Prompt 升级为 CCPE-Lite +``` + +默认要求: + +```text +Standard 档 +资产合约 +局部评测 +明确下游消费场景 +``` + +--- + +#### C. 治理级系统建设 + +系统运作为了构建可长久运行、可审计、可追责、可恢复的 Runtime 或工作台。 + +示例: + +```text +多 Agent 写作评审 Runtime +知识加工 Runtime +客户方案生成与审核工作台 +高风险决策辅助系统 +Agentic 生产系统 +``` + +默认要求: + +```text +Full 档候选 +完整权限矩阵 +Invocation Record +Runtime State Protocol +Evaluation Stack +Rollback Protocol +``` + +--- + +#### D. 校准与评测任务 + +系统运作为了修正模型偏差、构建评测集、记录专家反馈、对齐专家判断边界。 + +示例: + +```text +收集专家修改痕迹 +构建 100 道标准评测题 +分析 AI 与专家判断差异 +调整 Agent 的错误分类 +建立返工率指标 +``` + +默认要求: + +```text +Calibration Cost 记账 +过程数据授权 +Evaluation Stack +Expert Attention Budget +``` + +--- + +#### E. 探索预演任务 + +系统运作为了验证新范式、新工具、新调用链路或新组织方式。 + +示例: + +```text +测试 Codex Thread 是否能作为真实 Agent carrier +测试 Claude Code subagent 调用 +测试 SuperPowers 对流程的影响 +测试新型多 Agent 协作拓扑 +``` + +默认要求: + +```text +Exploration Cost 记账 +不得伪装为生产任务 +不得承诺稳定交付 +必须记录失败边界 +``` + +--- + +### 1.3 铁律:任务性质不得暗中变轨 + +如果原始目标只是: + +```text +提炼一篇 5 万字文稿 +``` + +系统绝不能在执行中私自搭建一套: + +```text +知识加工园区 +多 Agent 治理 Runtime +通用 Skill 生态 +完整覆盖审计体系 +长期下游 handoff 协议 +``` + +一旦任务从内容产出滑入系统建设,必须触发 Scope Drift Review。 + +--- + +### 1.4 档位挂载 / Mode Selector + +默认轻量,证据驱动升级。 + +系统物理操作杆在启动时,必须且只能挂在 Lite 档。 +除非出现明确升级证据,否则不得凭借工程师的架构审美、算法崇拜或自动化惯性擅自升档。 + +--- + +#### Lite 档:默认启动 + +适用边界: + +```text +一次性任务 +低法理风险 +单源或少量源材料 +源材料可被单个高上下文模型完整处理 +无需真实多 Agent 独立判断 +下游不依赖完整过程审计 +``` + +控制策略: + +```text +单模型或单主控极简闭环 +可使用局部 Skill 或工具 +不默认唤醒多 Agent 独立沙箱 +不默认创建厚重 handoff +不默认做覆盖审计 +不默认生成治理级日志 +``` + +核心产物: + +```text +目标输出文件 +极简输入记录 +关键人工确认点 +必要时的抽样检查 +``` + +禁止事项: + +```text +不得自动拉起委员会 +不得自动创建 Runtime +不得自动生成厚 topic docs +不得自动做 lossless coverage audit +不得将一次性任务重构为平台建设 +``` + +--- + +#### Standard 档:证据驱动升级 + +升级证据: + +```text +多源异构材料 +明确下游自动化消费依赖 +需要可复用 Skill / Workflow / Model Card +用户明确要求能力沉淀 +存在局部追踪与复盘需求 +需要少量真实 Agent / Worker 调用 +``` + +控制策略: + +```text +结构化上下文编译 +有限真实调用 +局部 Invocation Record +可复用资产合约 +局部评测 +关键 Human Gate +``` + +核心产物: + +```text +Source Pack +Context Pack +Reusable Artifacts +Decision Record +局部追踪日志 +目标输出文件 +``` + +限制: + +```text +允许真实 Agent / Worker,但必须限定角色数量、调用目的与产物边界。 +允许审计,但必须是 targeted audit,不得自动进入 Full 覆盖审计。 +``` + +--- + +#### Full 档:极限治理 + +升级证据: + +```text +高法理追责风险 +单向门商业决策 +外部客户关键交付 +多角色真实张力对撞 +长期运行 Runtime +强审计需求 +不可逆工具执行 +生产环境自动化 +``` + +控制策略: + +```text +全规格多智能体编排 +Authority Matrix +Runtime State Protocol +完整 Invocation Records +Coverage / Governance Audit +Rollback Protocol +Human Gate Contract +Data Security Policy +``` + +核心产物: + +```text +完整 Runtime 状态机 +append-only / tamper-evident Invocation Records +Authority Map +Risk Log +Distortion Log +Evaluation Report +Downstream Handoff +Recovery Plan +``` + +Full 档启动必须有人工授权。 +系统不得自发进入 Full 档。 + +--- + +### 1.5 预算合约 / Budget Contract + +每个 Runtime 启动前必须声明预算。 + +预算不只是 token,还包括时间、存储、工具调用和专家注意力。 + +必须声明: + +```text +source_size_estimate +target_mode +token_budget +time_budget +human_attention_budget +storage_budget +tool_call_budget +escalation_threshold +abort_threshold +budget_owner +``` + +默认预算倍率: + +```text +Lite: source_tokens × 10–30 +Standard: source_tokens × 30–100 +Full: source_tokens × 100+,必须有明确治理理由和人工授权 +``` + +若预计消耗超过当前档位预算上限,系统必须暂停并请求升级授权,不得静默继续。 + +--- + +### 1.6 组件启用矩阵 / Component Activation Matrix + +| 组件 | Lite | Standard | Full | +| -------------------------- | -------- | -------- | ----- | +| QPI Intake | 必须 | 必须 | 必须 | +| Task Nature Classification | 必须 | 必须 | 必须 | +| Cost Ledger | 简版 | 必须 | 必须 | +| Budget Contract | 简版 | 必须 | 必须 | +| Scope Drift Detection | 必须 | 必须 | 必须 | +| Stop Rule | 必须 | 必须 | 必须 | +| Human Gate | 关键点可选 | 必须 | 多层必须 | +| Invocation Record | 仅真实调用时 | 必须 | 全链路必须 | +| Simulation Labeling | 必须 | 必须 | 必须 | +| Context Compiler | 简版 | 必须 | 全规格 | +| Authority Matrix | 可选 | 必须 | 必须 | +| Artifact Contract | 简版 | 必须 | 必须 | +| Runtime State Protocol | 简版 | 必须 | 必须 | +| Tool Safety | 有工具时必须 | 必须 | 强制 | +| Data Security | 有敏感数据时必须 | 必须 | 强制 | +| Evaluation Stack | E0–E2 | E0–E5 | E0–E7 | +| Rollback Protocol | 有写入时必须 | 必须 | 强制 | +| Governance Audit | 禁止默认启用 | targeted | full | + +--- + +## 2. 成本隔离与防蔓延机制 + +## Cost Ledger & Scope Drift + +在 Agentic 自动化管线中,最致命的失控往往不是报错崩溃,而是系统在暗中无休止运转,将一次简单内容提取异化为庞大系统基建。 + +为了夺回对计算资源和专家注意力的控制权,必须在系统底盘焊死成本核算与边界探测组件。 + +--- + +### 2.1 四重消耗账本 / Cost Ledger + +任何 Agentic 工作流在启动时,其消耗的 token、算时、存储、工具调用和人工注意力,必须被记入以下四个账本之一。 + +--- + +#### Content Cost / 内容产出成本 + +为完成当前用户直接任务所消耗的核心资源。 + +示例: + +```text +蒸馏一篇材料 +转译一份分镜 +生成一份口播稿 +整理一次会议纪要 +生成客户报告初稿 +``` + +--- + +#### System-Building Cost / 系统建设成本 + +为设计、搭建或重构以下资产所消耗的资源: + +```text +Agent +Skill +Runtime +Protocol +Evaluation +Toolchain +Workflow +Model Index +Project Directory +Invocation Standard +``` + +示例: + +```text +为了蒸馏讨论稿而设计一个通用知识加工 Runtime +为了一次提纲评审而重构多 Agent invocation protocol +为了一个输出流程而建设完整生产线目录体系 +``` + +--- + +#### Calibration Cost / 校准修复成本 + +为纠正模型偏差、记录人工反馈、对齐专家判断边界、构建标准评测集所消耗的资源。 + +示例: + +```text +分析 AI 与专家判断差异 +收集专家修改痕迹 +构建真题评测集 +调整错误分类 +建立返工率指标 +``` + +--- + +#### Exploration Cost / 探索预演成本 + +为了验证新范式、新工具、新平台调用链路或新协作拓扑所消耗的实验性资源。 + +示例: + +```text +测试 Codex Thread 作为真实 Agent carrier +测试 Claude Code subagent +测试 SuperPowers 对流程复杂度的影响 +测试 OpenClaw 自动化能力边界 +``` + +--- + +### 2.2 核算铁律 + +绝对禁止将系统建设成本伪装为单次任务的内容产出成本。 + +如果一次任务中实际发生了: + +```text +设计新 Runtime +编写通用 Protocol +创建新 Agent / Skill +构建评测栈 +设计目录结构 +定义 invocation record +构建长期资产 +``` + +这些消耗必须记入 System-Building Cost,而不是 Content Cost。 + +系统架构的重工业投入必须光明正大地记入基建账本,以接受长周期 ROI 审计。 + +--- + +### 2.3 漂移探测触发 / Scope Drift Detection + +由于 LLM 内置的规划、反思和补完惯性,轻量级 P 域任务极易在无监督状态下向 I 域治理滑移。 + +系统必须在管线节点埋入漂移探针。一旦捕捉到以下信号,即刻判定发生任务蔓延。 + +--- + +#### 信号一:基建过度行为 + +一个被定性为 One-off 的任务,开始出现: + +```text +创建通用 Protocol +设计未来复用目录树 +撰写与当前产出无关的抽象规则 +新增 Agent / Skill / Runtime +升级为长期工作台建设 +``` + +--- + +#### 信号二:并发无序扩张 + +Lite 档流程开始擅自: + +```text +派发多个 Worker +拉起多角色审查委员会 +开启并行 coverage audit +创建多个 sub-session +进行未授权的动态 agent routing +``` + +--- + +#### 信号三:产物交付延宕 + +用户期待的核心产物迟迟未出现,系统资源却被大量消耗于: + +```text +routing log +coverage audit +handoff packet +review report +repair protocol +directory scaffolding +meta-analysis +``` + +--- + +#### 信号四:预算穿透 + +当前或预估消耗已超出原定预算阈值,且未主动申报分账。 + +默认触发条件: + +```text +Lite 超过 source_tokens × 30 +Standard 超过 source_tokens × 100 +任一任务专家注意力消耗超过预设 human_attention_budget +``` + +--- + +#### 信号五:成功标准变更 + +任务从: + +```text +完成一个结果 +``` + +变成: + +```text +定义一套以后如何持续完成结果的系统 +``` + +这说明任务性质已经从 Content Output 滑入 System Building。 + +--- + +### 2.4 漂移处置协议 / Drift Resolution Protocol + +一旦漂移探测器被触发,系统必须放弃顺其自然的工程惯性,执行强制介入。 + +--- + +#### Step 1:挂起进程 + +立即阻断当前 Agentic Runtime 的继续执行与自我繁衍。 + +状态切换为: + +```text +paused_by_scope_review +``` + +--- + +#### Step 2:核心发问 + +必须回答: + +```text +1. 我们现在还是在执行原始内容产出任务吗? +2. 如果不是,是否需要正式立项为系统建设任务? +3. 当前已消耗成本应记入哪一本账? +4. 是否需要调整 Lite / Standard / Full 档位? +5. 原始任务是否仍需先完成? +``` + +--- + +#### Step 3:物理分账 + +若确认任务变轨,必须将此前及后续超额消耗从 Content Cost 中切割,划入: + +```text +System-Building Cost +Calibration Cost +Exploration Cost +``` + +--- + +#### Step 4:人工授权重启 + +只有在完成以下动作后,系统方可解除挂起: + +```text +重新 QPI 定性 +重新 Mode Selector +重新 Budget Contract +重新 Stop Rule +记录 human decision +``` + +--- + +## 3. 物理防伪与绝对制动 + +## Execution Authenticity & Stop Rule + +缺乏硬约束的 Agentic 环境中,系统极易陷入两种工程灾难: + +```text +流程幻觉:主节点伪造执行过程 +过度执行:子节点无限繁衍中间产物 +``` + +本章为自动化管线装配测谎探针与制动系统。 + +--- + +### 3.1 执行真实性 / Execution Authenticity + +多智能体架构的真正价值,来源于不同思维模型在隔离沙箱中产生的真实逻辑张力,而不是单一模型在同一上下文里的文本模拟。 + +任何被声明为以下来源的正式产物: + +```text +独立 Agent +Reviewer +Worker +Auditor +Committee Member +External Participant +``` + +必须具备真实调用证据链。 + +--- + +### 3.2 真实调用证据链 / Invocation Record + +最小 Invocation Record 必须包含: + +```text +invocation_id +agent_id / role_id +canonical_prompt_path / agent_spec_path +runtime_id +carrier_type +carrier_id / thread_id / sub_session_id +input_context_path +input_context_hash +execution_timestamp +returned_output_path +returned_output_hash +orchestrator_id +entered_synthesis: true / false +human_gate_id_if_applicable +``` + +--- + +### 3.3 主控越权阻断 + +主会话或 Orchestrator 仅被赋予: + +```text +调度 +路由 +聚合综合 +状态记录 +有限验证 +人工确认转译 +``` + +绝对禁止主会话凭借自身高上下文能力去代写或模拟子节点输出。 + +若无法拉起真实子线程、外部参与者或 carrier,进程必须进入: + +```text +blocked_waiting_for_participant_output +``` + +不得用伪造报告填补流程真空。 + +--- + +### 3.4 模拟标记与沙箱隔离 / Simulation Labeling + +当系统因环境限制、调用失败、人类手动干预或流程占位,产生缺乏真实调用证据的产物时,必须实施资产隔离。 + +所有模拟产物必须包含: + +```text +simulation_only: true +formal_output: false +excluded_from_synthesis: true +simulation_reason: +allowed_use: +``` + +允许用途: + +```text +价值流预演 +人工参考草稿 +流程设计样例 +绿野仙踪验证 +``` + +禁止用途: + +```text +正式 synthesis +客户可见交付 +下游自动化依据 +模型沉淀依据 +审计依据 +``` + +--- + +### 3.5 最小充分阈值 / Minimum Sufficient Threshold + +任何 Runtime 启动前,必须与人类专家确立验收合约。 + +必须定义: + +```text +minimum_viable_output +sufficient_criteria +optional_artifacts +forbidden_artifacts +human_gate_points +budget_limit +stop_condition +``` + +--- + +#### Minimum Viable Output + +为了满足下游消费,当前任务必须交付的最核心、最少信息量。 + +示例: + +```text +只需视频总纲与分镜骨架,不需要详细配音稿 +只需 topic map 与 reusable material units,不需要 full coverage audit +只需 outline review,不需要完整正文写作 Runtime +``` + +--- + +#### Sufficient Criteria + +一旦达到该状态,即视为已达标。 + +达标后,Optional Artifacts 默认被剥夺生成权限,除非人类显式授权。 + +--- + +#### Human Gate Points + +提前锚定机器绝对不能自决的单向门。 + +示例: + +```text +是否进入 Full 档 +是否采纳红队意见 +是否创建 writing project +是否进入 model mining +是否对客户可见 +是否执行外部 API +``` + +--- + +### 3.6 Human Gate Contract / 人工决策门合约 + +Human-in-the-loop 不是一句空话,而是责任坐标。 + +每个 Human Gate 必须声明: + +```text +gate_id +decision_owner +input_artifacts +decision_options +default_action +downstream_effect +reversibility +escalation_condition +record_path +timeout_policy +``` + +禁止设置无合约的“人工确认”。 + +--- + +#### Human Gate 输出格式 + +每个决策记录至少包含: + +```text +decision_id: +gate_id: +decision_owner: +accepted_option: +rejected_options: +reason: +risk_notes: +downstream_effect: +rollback_condition: +timestamp: +``` + +--- + +### 3.7 Runtime State Protocol / 运行状态协议 + +所有 Runtime 必须使用标准状态。 + +```text +initialized +running +blocked_waiting_for_human +blocked_waiting_for_participant_output +blocked_waiting_for_tool +paused_by_scope_review +paused_by_budget_guard +failed_recoverable +failed_terminal +completed +aborted_by_human +archived +``` + +每次状态变化必须记录: + +```text +previous_state +new_state +trigger +responsible_actor +timestamp +next_allowed_actions +``` + +--- + +### 3.8 Stop Rule / 绝对停止权 + +人类意志的最高体现不在于启动自动化,而在于何时决绝地踩下刹车。 + +Stop Rule 是系统免于冗余完美主义与中间物繁殖的最后防线。 + +--- + +#### 触发条件 + +一旦出现以下情况,必须触发停止: + +```text +已达到 Minimum Sufficient Threshold +触及 Human Gate +预算接近 abort_threshold +发生 Scope Drift +真实 invocation 不可用 +工具权限不足 +数据安全边界不清 +来源保真无法验证 +``` + +--- + +#### 制动执行 + +系统必须: + +```text +停止创建新任务 +取消未启动的排队任务 +对运行中任务发出 cooperative cancellation +保存当前状态、日志与未完成动作清单 +阻断非必要产物继续生成 +将状态切换为 blocked_waiting_for_human +``` + +对于无法响应 cooperative cancellation 的非关键线程,可执行强制终止。 + +终止前必须尽可能保存: + +```text +partial_outputs +state_snapshot +action_log +unfinished_tasks +risk_notes +``` + +--- + +## 4. 权限、安全与副作用控制 + +## Authority, Tool Safety & Data Security + +Agentic 系统真正危险的地方,不只是会说,而是会做。 + +因此,所有工具权限、文件写入、外部 API、客户可见输出,都必须纳入权限矩阵与副作用隔离。 + +--- + +### 4.1 权力矩阵 / Authority Matrix + +每一个 Agent、Skill、Runtime Node 必须声明权限等级。 + +--- + +#### A0 Observe / 观察 + +仅拥有读取权限。 +可生成内部标注。 +无权修改任何状态或产物。 + +--- + +#### A1 Suggest / 建议 + +允许输出分析、建议、优化方案。 +产物不能直接覆写正式文件。 +仅供高阶节点参考。 + +--- + +#### A2 Draft / 起草 + +允许生成初稿物料。 +产物必须经过 Human Gate 或 Owner Agent 签发后,方可流转。 + +--- + +#### A3 Modify / 修改 + +允许在预设范围内修改正式产物。 + +必须限定: + +```text +allowed_paths +allowed_files +allowed_fields +modification_scope +rollback_path +``` + +--- + +#### A4 Decide / 裁决 + +拥有结构性决策权。 + +行使该权限时,必须同步输出: + +```text +decision record +decision rationale +risk notes +downstream effect +``` + +--- + +#### A5 Execute / 执行 + +A5 必须拆分为三个子级。 + +```text +A5-R Read Tool +A5-W Write Tool +A5-X External Action +``` + +--- + +##### A5-R Read Tool + +只读工具调用。 + +示例: + +```text +搜索 +读取文件 +查询数据库 +查看日志 +读取状态 +``` + +--- + +##### A5-W Write Tool + +写入动作。 + +示例: + +```text +写文件 +改代码 +更新配置 +生成资产 +修改目录 +保存结果 +``` + +必须满足: + +```text +允许路径 +变更日志 +diff +回滚策略 +``` + +--- + +##### A5-X External Action + +外部动作。 + +示例: + +```text +发送消息 +发布内容 +调用客户 API +支付 +删除远程资源 +修改客户可见状态 +触发生产任务 +``` + +默认禁止自动执行。 +必须经过 Human Gate 或 Runtime 级明确授权。 + +--- + +#### A6 Block / 阻断 + +最高优先级熔断权限。 + +一旦触发,系统全线进程挂起,进入: + +```text +blocked_waiting_for_human +``` + +适用场景: + +```text +严重逻辑悖论 +法理违规 +数据泄漏风险 +权限越界 +预算穿透 +来源不可验证 +执行真实性缺失 +高风险动作未授权 +``` + +--- + +### 4.2 最小权限原则 / Least Privilege + +Agent 的工具权限必须小于其语言能力。 + +```text +能分析,不代表能执行。 +能建议,不代表能写入。 +能生成,不代表能发布。 +能理解任务,不代表拥有全目录权限。 +``` + +任何权限必须按任务最小授权。 + +禁止: + +```text +通用推理 Agent 获得无限工具权限 +默认授予全仓库写入权限 +默认授予外部 API 权限 +默认授予发布权限 +默认授予删除权限 +``` + +--- + +### 4.3 副作用隔离 / Side-effect Isolation + +具备写入、发布、删除、外部 API、客户可见输出能力的 Agent,必须满足: + +```text +沙箱目录或沙箱环境 +明确 allowed_paths +明确 forbidden_paths +dry-run / preview 优先 +执行前生成 action plan +执行后生成 action log +支持回滚或人工恢复 +高风险动作必须二次确认 +``` + +--- + +### 4.4 数据分级 / Data Classification + +所有输入材料必须标记数据等级。 + +```text +Public:公开材料 +Internal:内部材料 +Confidential:客户资料、商业方案、报价、合同、业务数据 +Sensitive:个人信息、密钥、账号、财务、法律、医疗、未成年人、内部战略等高敏感数据 +``` + +不同数据等级决定: + +```text +是否允许外发 +是否允许进入外部模型 +是否需要脱敏 +是否允许保存日志 +是否允许被用于校准 +是否允许进入知识库 +``` + +--- + +### 4.5 密钥纪律 / Secrets Discipline + +任何 Agent、Skill、Runtime 不得: + +```text +将 API Key、Token、Cookie、账号密码写入 Prompt +将密钥保存到普通日志 +将密钥复制进 Context Pack +将密钥暴露给不需要该权限的子 Agent +将包含密钥的返回结果进入长期知识库 +``` + +密钥必须通过安全环境变量、密钥管理服务或平台授权通道传递。 + +--- + +### 4.6 数据外发红线 + +调用外部模型、外部 API、图片 / 语音 / 视频服务前,必须确认: + +```text +数据是否允许外发 +是否包含客户资料 +是否包含个人信息 +是否需要脱敏 +第三方是否保存日志 +返回结果是否可以保存 +是否允许进入训练或校准流程 +``` + +若无法确认,默认禁止外发。 + +--- + +### 4.7 过程数据授权 / Process Data Sovereignty + +专家修改痕迹、反馈、编辑轨迹、隐性遥测、光标行为、反驳意见,是高价值认知资产,也是高敏感数据。 + +采集这些数据必须具备: + +```text +明确授权 +用途边界 +最小采集 +可撤回机制 +隔离存储 +保留期限 +访问权限 +删除机制 +``` + +禁止以“系统学习”为名,默认吞并专家经验或客户场景数据。 + +--- + +### 4.8 平台与插件治理 / Platform & Plugin Governance + +任何平台、插件、Skill Pack、自动化框架的默认行为,不得覆盖本手册。 + +当平台默认流程倾向于: + +```text +自动创建子线程 +自动调用复杂 Skill +自动进入 TDD / Review / Audit +自动补全缺失产物 +自动扩展目录结构 +自动执行高权限工具 +自动将失败流程补成完整故事 +``` + +系统必须先进行 Mode Selector 与 Scope Review。 + +--- + +#### 项目级白名单 + +每个项目必须声明: + +```text +allowed_skills +blocked_skills +manual_only_skills +allowed_tool_scopes +forbidden_tool_scopes +allowed_external_services +blocked_external_services +``` + +--- + +#### 非代码任务默认禁用重型软件工程插件 + +对于以下任务: + +```text +知识蒸馏 +写作 +模型提炼 +素材整理 +方案分析 +研究讨论 +概念设计 +``` + +默认禁止启用重型软件工程流程插件,除非用户明确将任务升级为系统建设或工具开发。 + +--- + +#### 插件输出不得自动成为正式产物 + +插件生成的输出仍必须经过: + +```text +Artifact Contract +Execution Authenticity +Evaluation Stack +Human Gate +Source Fidelity +``` + +插件不是治理豁免权。 + +--- + +## 5. 运行修复与回滚 + +## Retry, Repair & Rollback + +Agentic 系统里的失败并不可怕。 +真正危险的是无限重试、静默修补、越修越偏和不可回滚。 + +--- + +### 5.1 重试上限 / Retry Limits + +任何自动重试必须有上限。 + +默认规则: + +```text +工具调用失败:最多重试 2 次 +格式错误:最多自动修复 2 次 +网络/API 临时失败:最多重试 2 次 +权限失败:不得自动绕过 +推理质量不达标:不得无限重写 +外部 API 失败:不得通过更换高风险 API 绕过权限边界 +``` + +超过重试上限后,状态切换为: + +```text +failed_recoverable +``` + +或: + +```text +blocked_waiting_for_human +``` + +--- + +### 5.2 失败分类 / Failure Classification + +失败必须分类,不得笼统写作“执行失败”。 + +```text +F0 Format Failure:格式失败 +F1 Tool Failure:工具失败 +F2 Permission Failure:权限失败 +F3 Data Failure:数据缺失或数据污染 +F4 Source Fidelity Failure:来源保真失败 +F5 Reasoning Failure:推理失败 +F6 Invocation Failure:真实调用失败 +F7 Budget Failure:预算失败 +F8 Governance Failure:治理失败 +F9 Terminal Failure:不可恢复失败 +``` + +--- + +### 5.3 修复计划 / Repair Plan + +产物失败后,系统必须先生成 Repair Plan,而不是直接重写。 + +Repair Plan 必须说明: + +```text +failure_type +failure_location +affected_artifacts +impact_level +repair_scope +whether_human_gate_required +whether_reinvocation_required +whether_rollback_required +new_budget_estimate +``` + +--- + +### 5.4 回滚协议 / Rollback Protocol + +任何 A5-W / A5-X 权限动作必须支持回滚协议。 + +必须具备: + +```text +pre_change_snapshot +diff / action_log +rollback_path +rollback_owner +irreversibility_warning +``` + +不可回滚动作必须提前阻断,并要求 Human Gate。 + +示例: + +```text +发布客户可见内容 +删除远程资源 +发送正式邮件 +触发生产 API +修改客户数据库 +覆盖正式知识库资产 +``` + +--- + +### 5.5 修复后的再验证 + +修复后必须重新通过相关评测层级。 + +示例: + +```text +格式修复后 -> E1 Format Test +事实修复后 -> E2 Factual Test +推理修复后 -> E3 Reasoning Test +权限修复后 -> E7 Governance Test +``` + +不得因为“已修复”而跳过验证。 + +--- + +## 6. 通用运行组件与资产标准 + +## Agentic Runtime Components & Artifact Standards + +本章定义 Agentic 系统在 Standard / Full 档中必须使用的运行组件。Lite 档可采用简版,但不得违背其核心原则。 + +--- + +### 6.1 产物合约 / Artifact Contract + +文件很多但不知道哪个是真的,是伪工程化的典型症状。 + +任何脱离草稿态进入正式资产池的产物,必须声明其生命周期与校验元数据。 + +正式产物头部必须包含: + +```text +artifact_type: +status: +authority: +source_of_truth: +downstream_use: +invalidation_condition: +cost_class: +created_by: +created_at: +last_updated: +``` + +--- + +#### artifact_type + +允许值: + +```text +Prompt +Agent Spec +Skill +Runtime +Model Card +Model Index +Evaluation +Tool +Workflow +Context Pack +Final Output +Simulation Output +``` + +--- + +#### status + +允许值: + +```text +draft +candidate +active +deprecated +archived +rejected +simulation-only +``` + +--- + +#### authority + +允许值: + +```text +internal_note +reference_only +formal_basis +customer_visible +runtime_executable +simulation_only +excluded_from_synthesis +``` + +--- + +#### invalidation_condition + +必须说明何时失效。 + +示例: + +```text +上游源文件更新 +canonical prompt 更新 +用户推翻结构 +规则变更 +模型版本迁移 +客户约束变更 +Human Gate 未通过 +``` + +--- + +### 6.2 运行时成熟度模型 / Runtime Maturity Model + +为了防止团队在概念沙盘与生产交付之间产生致命预期错位,必须用成熟度模型丈量每个 Agentic 项目的坐标。 + +--- + +#### M0 Concept / 概念态 + +仅存在思想模型或业务论证。 +尚未进行自动化流程拆解。 + +--- + +#### M1 Manual / 手工态 + +专家人工跑通闭环。 +符合 Wizard of Oz 绿野仙踪协议。 +验证智能流核心业务价值。 + +--- + +#### M2 Assisted / 辅助态 + +AI 介入生成草稿或检查项。 +核心推进与流程驱动依赖人类。 + +--- + +#### M3 Protocolized / 协议态 + +以下内容已显性化: + +```text +输入 +输出 +角色边界 +状态机流转 +Human Gate +Stop Rule +权限范围 +``` + +但尚未实现完整自动化调用。 + +--- + +#### M4 Semi-Agentic / 半 Agentic 态 + +部分 Agent、Skill 或 Tool 已实现真实自动化调用。 +具备 Invocation Record。 +但仍依赖人类推进关键节点。 + +--- + +#### M5 Production / 生产态 + +具备可重复运行管线。 + +必须具备: + +```text +自动化评测 +执行监控 +异常捕获 +权限管控 +日志记录 +基础回滚 +``` + +达到内部工程可用标准。 + +--- + +#### M6 Governed / 治理态 + +具备抗审计、法理追责与灾难回滚能力。 + +适用于: + +```text +高风险场景 +外部客户严苛交付 +长期运行系统 +客户可见自动化 +不可逆工具执行 +``` + +--- + +#### 成熟度铁律 + +```text +M2 不得伪装 M5。 +M3 不得伪装 M6。 +模拟产物不得伪装 M4。 +无 Invocation Record 不得声明真实 Agentic。 +无 Evaluation Stack 不得声明 Production。 +无 Governance Test 不得声明 Governed。 +``` + +--- + +### 6.3 上下文编译 / Context Compiler + +绝对禁止将漫长、原始、异质的语料一股脑倾倒进所有 Agent 的上下文窗口。 + +在任何 I 域或高价值 P 域任务前,必须将上下文工程剥离为独立预处理动作。 + +--- + +#### Whole-source Gestalt + +面对高连贯性长文本,在启动分块前,必须优先实施全局扫描,锁定: + +```text +核心张力 +主轴结构 +目录骨架 +模型演化线 +层级风险 +关键反例 +``` + +防止 chunk-first 造成结构性失明。 + +适用边界: + +```text +源材料高度连贯 +源材料可被高上下文模型完整处理 +下游依赖整体结构 +``` + +若源材料是 mixed source,应先做 macro-topic split。 +若源材料是 fragmented source,应采用 flat discovery,不得强行制造层级。 + +--- + +#### Context Pack 类型 + +上下文编译器应根据下游目标输出: + +```text +source_digest +task_specific_context_pack +role_specific_dispatch_pack +decision_context +evaluation_context +source_index +risk_notes +``` + +--- + +#### 上下文最小充分原则 + +上下文包必须足够支撑任务,但不得将所有材料倾倒给所有角色。 + +```text +主控需要全局状态 +执行节点需要任务相关材料 +评审节点需要标准、目标与产物 +人工决策门需要候选方案、风险与差异摘要 +``` + +--- + +### 6.4 来源保真与证据索引 + +### Source Fidelity & Evidence Index + +任何涉及材料加工、报告生成、知识蒸馏、客户方案、分析结论的 Runtime,必须保留来源索引。 + +正式输出中的关键判断必须能回溯至: + +```text +原始来源 +source range / paragraph / block id +参与该判断的 Agent / Worker +该判断是否来自原文、推理、归纳、用户裁决或模型补充 +``` + +--- + +#### 来源铁律 + +```text +禁止将中间摘要当作新的 source of truth。 +禁止把模型综合判断伪装成原始材料事实。 +禁止在未标明推理性质的情况下输出确定性结论。 +禁止在 source index 缺失时声明 lossless extraction。 +``` + +--- + +#### 判断类型标记 + +关键判断必须标明类型: + +```text +source_fact:原文事实 +source_claim:原文主张 +inference:模型推理 +synthesis:综合归纳 +human_decision:人工裁决 +external_fact:外部事实 +assumption:假设 +``` + +--- + +### 6.5 分层评测栈 / Evaluation Stack + +依靠单一准确率或相似度,无法测度专家级 Agentic 系统的真实抗压能力。 + +系统必须部署从底层机械属性到顶层战略效用的多维探针。 + +--- + +#### E0 Smoke Test / 冒烟测试 + +检验系统能否走通骨架。 + +```text +文件是否生成 +Tool Call 是否响应 +目录是否正确 +流程是否启动 +``` + +--- + +#### E1 Format Test / 格式测试 + +检验输出是否遵守: + +```text +Schema +长度预算 +语言规范 +命名规范 +字段完整性 +``` + +--- + +#### E2 Factual Test / 事实测试 + +核查文本溯源保真度。 + +```text +是否编造事实 +是否遗漏关键材料 +是否错误引用 +是否混淆来源 +``` + +--- + +#### E3 Reasoning Test / 推理测试 + +刺探逻辑链健壮性。 + +```text +假设是否暴露 +推理是否闭合 +反例是否处理 +边界条件是否说明 +``` + +--- + +#### E4 Expert Similarity / 专家相似度 + +测度结论与人类专家判断的重合度。 + +同时记录偏差部分是否可解释。 + +--- + +#### E5 Decision Utility / 决策效用 + +验证系统是否真实帮助人类专家完成: + +```text +更优决策 +更快判断 +更低认知消耗 +更低返工率 +更稳风险控制 +``` + +--- + +#### E6 Calibration Test / 校准测试 + +评测系统纠错摩擦力。 + +```text +专家是否容易指出错误 +系统是否能理解纠错 +修复是否影响后续批处理 +反馈是否进入评测集 +``` + +--- + +#### E7 Governance Test / 治理测试 + +审计视角终极测试。 + +```text +trace 是否完整 +authority 是否隔离 +rollback 是否可行 +human gate 是否记录 +liability boundary 是否清晰 +data policy 是否合规 +``` + +--- + +### 6.6 按场景选择评测层级 + +```text +Q 域查询:E0–E2 +基础 P 域生产:E0–E3 +生产工坊:E0–E5 +专家辅助系统:E2–E6 +战略透镜:E3–E7 +治理级 Runtime:E0–E7 +``` + +不得用单一准确率评估战略透镜。 +不得用“看起来不错”替代 E5 / E6 / E7。 + +--- + +## 7. 开工清单与反模式 + +## Start Checklist & Anti-patterns + +本章用于将前述规则压缩为现场可执行动作。 + +--- + +### 7.1 Agentic Project Start Checklist + +每个 Agentic 项目开工前,必须回答: + +```text +1. 原始任务是什么? +2. Q / P / I 定性是什么? +3. 任务性质是什么:内容产出、系统建设、校准、探索? +4. 启动档位是什么:Lite / Standard / Full? +5. 最小充分产物是什么? +6. 停止条件是什么? +7. token / time / human attention 预算上限是什么? +8. 是否涉及客户资料、密钥或敏感数据? +9. 是否需要真实 Agent 调用? +10. 若需要,Invocation Record 保存在哪里? +11. 是否允许工具写入? +12. 是否允许外部 API? +13. Human Gate 在哪里? +14. 谁是 decision_owner? +15. 产物如何进入 Artifact Contract? +16. 评测层级到 E 几? +17. 是否需要 Source Fidelity? +18. 是否需要 Rollback Protocol? +19. 哪些平台插件允许自动触发? +20. 什么时候触发 Scope Drift Review? +``` + +未完成清单,不得进入 Standard 或 Full 档。 + +--- + +### 7.2 常见反模式 / Anti-patterns + +--- + +#### 1. Prompt 万能化 + +把 Agent、Skill、Runtime、Model Card 全塞进一个巨型 Prompt。 + +后果: + +```text +难维护 +难评测 +难复用 +难追踪 +难迁移 +``` + +--- + +#### 2. 流程幻觉 + +文件齐全,但真实 Agent 没有被调用。 + +典型症状: + +```text +有 report +有 dispatch pack +有目录 +有日志 +但没有 Invocation Record +``` + +--- + +#### 3. 治理过载 + +一次性任务启用 Full Runtime。 + +典型症状: + +```text +5 万字材料 +3000 万 tokens +大量 topic docs +大量 audit +大量 handoff +核心产物 ROI 失真 +``` + +--- + +#### 4. 成本混账 + +把系统建设成本算成内容产出成本。 + +典型症状: + +```text +用户只要一个结果 +系统却建设了一个机器 +最后把机器成本记到结果上 +``` + +--- + +#### 5. 中间物繁殖 + +核心产物未交付,系统不断生成: + +```text +audit +routing log +handoff +repair note +review report +meta-analysis +``` + +--- + +#### 6. 上下文倾倒 + +把所有原始材料一股脑塞给所有 Agent。 + +后果: + +```text +角色污染 +判断失焦 +token 浪费 +source fidelity 降低 +``` + +--- + +#### 7. 权限裸奔 + +让能推理的 Agent 直接拥有: + +```text +写入权限 +删除权限 +发布权限 +外部 API 权限 +客户可见输出权限 +``` + +--- + +#### 8. 无评测上线 + +只凭“我觉得不错”进入生产。 + +红线: + +```text +无 Evaluation Stack,不得声明 Production。 +``` + +--- + +#### 9. 模拟污染 + +simulation-only 产物进入正式 synthesis。 + +这是多 Agent 系统的根级污染。 + +--- + +#### 10. 黑盒校准 + +系统输出错了,但专家不知道如何低成本纠正。 + +症状: + +```text +没有 decision rationale +没有 error category +没有 feedback slot +没有 repair plan +``` + +--- + +#### 11. 插件篡权 + +平台插件默认流程覆盖项目治理规则。 + +症状: + +```text +自动开子线程 +自动进入重型审查 +自动生成无关目录 +自动补全失败产物 +``` + +--- + +#### 12. 停止权失效 + +系统已经达到最小充分产物,却继续生产“看似有用”的附加物。 + +红线: + +```text +系统不得因为还能生成,就继续生成。 +``` + +--- + +## 8. 附录:标准元数据模板 + +## Appendix: Standard Metadata Templates + +--- + +### 8.1 Invocation Record Template + +```yaml +invocation_id: +runtime_id: +agent_id: +role_id: +canonical_prompt_path: +agent_spec_path: +carrier_type: +carrier_id: +thread_id: +input_context_path: +input_context_hash: +execution_timestamp: +returned_output_path: +returned_output_hash: +orchestrator_id: +entered_synthesis: false +human_gate_id_if_applicable: +status: +notes: +``` + +--- + +### 8.2 Simulation Metadata Template + +```yaml +simulation_only: true +formal_output: false +excluded_from_synthesis: true +simulation_reason: +allowed_use: +created_by: +created_at: +must_not_enter: + - formal_synthesis + - customer_delivery + - model_card_source + - governance_audit +``` + +--- + +### 8.3 Human Gate Record Template + +```yaml +decision_id: +gate_id: +decision_owner: +input_artifacts: +decision_options: +accepted_option: +rejected_options: +reason: +risk_notes: +downstream_effect: +reversibility: +rollback_condition: +timestamp: +``` + +--- + +### 8.4 Artifact Contract Template + +```yaml +artifact_type: +status: +authority: +source_of_truth: +downstream_use: +invalidation_condition: +cost_class: +created_by: +created_at: +last_updated: +related_invocations: +related_human_gates: +related_sources: +``` + +--- + +### 8.5 Runtime State Transition Template + +```yaml +runtime_id: +previous_state: +new_state: +trigger: +responsible_actor: +timestamp: +next_allowed_actions: +blocked_reason: +related_artifacts: +notes: +``` + +--- + +### 8.6 Cost Ledger Entry Template + +```yaml +ledger_id: +task_id: +cost_class: +mode: +token_estimate: +token_actual: +time_spent: +tool_calls: +human_attention_minutes: +storage_used: +reason: +approved_by: +timestamp: +``` + +--- + +### 8.7 Repair Plan Template + +```yaml +repair_id: +failure_type: +failure_location: +affected_artifacts: +impact_level: +repair_scope: +human_gate_required: false +reinvocation_required: false +rollback_required: false +new_budget_estimate: +repair_owner: +next_state: +``` + +--- + +## 9. 结语:现场纪律 + +Agentic 工程不是“让 AI 多干点”。 + +它是把人类专家的判断、责任、隐性经验、材料处理、流程边界和工具权限,装入一台会高速运转的认知反应堆。 + +因此,本手册的目的不是鼓励自动化,而是给自动化装上: + +```text +入口闸门 +成本账本 +权限阀门 +防伪探针 +状态仪表 +数据隔离 +评测探针 +回滚绳索 +绝对刹车 +``` + +系统越聪明,越要守规矩。 +流程越丝滑,越要看后端废热。 +Agent 越能干,越不能让它裸奔。 + +**HiFi Agentic 工程的底线不是“自动完成”,而是:高保真、可校准、可追踪、可停止、可追责。** diff --git a/rules/Templates/Agentic-Engineering-Handbook1.2.md b/rules/Templates/Agentic-Engineering-Handbook1.2.md new file mode 100644 index 0000000..7e47817 --- /dev/null +++ b/rules/Templates/Agentic-Engineering-Handbook1.2.md @@ -0,0 +1,588 @@ +# Agentic Engineering Handbook (V1.2) + +*HiFi Agent Studio 运行治理与现场规程* + +## Profile + +* **author**: Wantsong +* **version**: V1.2 +* **date**: 2026-06-15 +* **status**: active-candidate +* **governing doctrine**: HiFi Agent Studio +* **related system**: CCPE System / Knowledge Vault / Writing Workbench / Video Workbench + +--- + +## 0. 守则定位与绝对边界 + +本手册定义了团队在 Agentic 工程实战中的操作底线与运行时规程。它将 HiFi Agent Studio 的高维架构设计转化为开发工程师在现场可执行的工程界桩,聚焦于规范化系统的生命周期管理,具体解决包括任务分诊、并发限流、调用链路追踪、执行防伪、权限沙箱管控、状态机熔断、异常回滚以及验收标准在内的核心工程链路问题,从而避免系统在缺乏约束的环境下发生不可控的自我繁衍。 + +### 0.1 守则效力 + +本手册服从并承载 HiFi Agent Studio 的核心纲领,同时作为一切局部 Agentic 项目的硬性行动准则。当系统在实际运行中发生规则冲突时,所有执行组件与人类专家必须遵循以下优先级序列进行裁决: + +1. 客户法理与商业硬性约束 +2. HiFi Agent Studio 宪法原则 +3. **本 Agentic Engineering Handbook** +4. CCPE System 资产建造规范 +5. 具体项目 Runbook +6. 平台、插件或底层工具的默认行为 + +> **注意**:若底层自动化框架、平台插件或引入的 Skill Pack 的默认执行行为与本手册发生冲突,必须强制阻断其默认行为并以本手册的约束为准。 + +### 0.2 反向兜底 + +任何底层自动化框架(如 Codex、Claude Code、OpenClaw、SuperPowers 等)或 Agentic Runtime 在运行过程中,如果展现出遇错无限重试、自动化子线程繁衍、无监管地扩展目录结构、静默补全缺失产物、自动拉起重型评审流程、调用超纲高权限工具或将模拟态输出包装为正式结果的倾向,系统必须立即挂起当前进程并向上抛出异常以请求架构裁决。开发人员严禁为了迎合底层工具的调用便利性,而对执行真实性、最小权限原则、成本分账、绝对停止权、人工决策门(Human Gate)、来源保真、数据安全以及责任边界等治理底线做出任何妥协或让步。 + +### 0.3 模拟与正式执行的边界 + +在系统的绿野仙踪(Wizard of Oz)阶段,允许人类专家、主控节点或单一模型以模拟 Agent 的形式低成本验证业务的价值流转。然而,所有在非真实隔离沙箱中产生的模拟产物,必须在元数据中强制注入 `simulation_only: true`、`formal_output: false` 以及 `excluded_from_synthesis: true` 标签。此类模拟产物仅被允许用作价值预演、流程草图验证或人工参考,绝对禁止其冒充正式的多智能体执行产物进入下游生产决策链,正式运行阶段的系统必须具备完整的真实调用记录(Invocation Record)。 + +--- + +## 1. 任务入口与档位挂载 (Project Intake & Mode Selector) + +在 Agentic 并发管线中,算力消耗的失控与架构治理的灾难通常源于系统入口处的任务定性溃败。在创建第一个 Thread、调用第一个 Skill 或启动任何底层 Worker 之前,架构师与开发人员必须在操作面板上完成结构化的强制分诊。 + +### 1.1 QPI 强制分诊 + +所有业务需求接管的第一时间必须进行问题颗粒度的物理探测,系统严禁在含糊其辞的状态下进行调度尝试。 + +* **【Q】查询 (Question)**:其核心匮乏在于数据或信息的缺失。该场景具有线性因果特征,存在明确的答案或可查询的事实(如提取特定材料中的指标、确认文件路径或定义)。系统应直接采用搜索、检索增强生成(RAG)、数据库查询或工具 API 填补信息缺口,采用单节点调用架构。绝对禁止为 Q 域任务编排复杂的多体流程,或为其启动覆盖率审计与治理级 Runtime。 +* **【P】求解 (Problem)**:其核心匮乏在于实现路径的缺失。此类场景目标明确,但需要经过工程化的转换、拆解、生产或优化(如长文转分镜、批量生成配音稿、素材蒸馏或标准化报告初稿)。架构复杂性应优先倾注于稳定吞吐量、低返工率、可验证输出、上下文压缩与批处理效率,采用标准作业程序(SOP)、模板化约束与人工抽检结合的生产工坊模式,而非引入不必要的多角色治理。 +* **【I】治理 (Issue)**:其核心匮乏在于秩序、共识与责任边界的缺失。该场景通常无唯一最优解,存在隐蔽变量、多方权衡、非遍历性风险或可能触发单向门决策的业务节点(如核心立意判定、重大客户方案取舍、战略级评审或高风险决策辅助)。系统的架构复杂性必须全部倾注于保真度、责任锚定、多视角张力、审计可追踪性与反例处理,强制要求配置战略透镜、人机回环、预设委员会与权限阻断机制,绝不允许利用高并发的算力来掩盖判断逻辑本身的脆弱性。 + +### 1.2 任务性质定性 + +在完成 QPI 定性后,必须明确当前操作的终极标的,因为同一个表层的业务任务可能归属于完全不同的工程性质。 + +* **一次性内容产出**:系统运行的唯一目的是获取当前的单一结果材料(例如整理一篇 5 万字的讨论稿、生成单个视频分镜或提取会议纪要)。此类任务默认要求挂载 Lite 档,聚焦于交付最小充分产物并保持轻量记录,严禁系统自动升级为重工业的 Runtime 建设。 +* **可复用能力沉淀**:系统运行的目的是为了提炼可跨越项目周期复用的资产(例如将某种提炼方法沉淀为 Skill、将专家判断结构沉淀为 Model Card,或将旧 Prompt 升级为 CCPE-Lite)。此类任务默认要求挂载 Standard 档,强制要求输出资产合约并进行局部评测,同时需明确下游的消费场景。 +* **治理级系统建设**:系统运行的目的是构建一套可长久运行、支持审计追责与异常恢复的底层基座或工作台(例如多 Agent 写作评审 Runtime、知识加工园区或高风险决策辅助系统)。此类任务具有 Full 档候选资格,要求强制挂载完整的权限矩阵、状态机协议(Runtime State Protocol)、全链路评估栈(Evaluation Stack)与灾难回滚协议。 +* **校准与评测任务**:系统运行的目的在于修正模型偏差、构建标准化评测集、记录专家反馈以对齐判断边界(例如收集专家修改痕迹、构建 100 道标准评测题或建立返工率基线)。此类任务的资源消耗必须计入校准账本(Calibration Cost),并严格遵守过程数据授权规范与专家注意力预算限制。 +* **探索预演任务**:系统运行的目的是为了验证新范式、新工具、外部平台调用链路或新型协作拓扑的边界(例如测试 Codex Thread 能否作为真实的 Agent 载体)。此类操作的消耗必须计入探索账本(Exploration Cost),严禁将其伪装为生产任务并对外承诺稳定交付,且必须详细记录失败边界。 + +### 1.3 铁律:任务性质不得暗中变轨 + +开发人员必须保持高度的运行时边界感知。如果原始目标仅为提炼一篇 5 万字的文稿,系统在执行过程中绝不能私自衍生出复杂的通用 Protocol、知识加工园区、全量多 Agent 治理 Runtime 或长期下游交接协议。一旦监控探针发现任务从单次内容产出向系统基建滑移,必须立即挂起进程并触发范围漂移审查(Scope Drift Review)。 + +### 1.4 档位挂载 (Mode Selector) + +系统执行必须遵循“默认轻量,证据驱动升级”的原则。系统的物理操作杆在初始化启动时,必须且只能挂载在 Lite 档。除非出现明确的硬性升级证据,否则严禁凭借开发者的架构审美、算法崇拜或底层工具的自动化惯性擅自提升运行档位。 + +* **Lite 档(默认启动)** + * **适用边界**:适用于一次性任务、低法理风险、单源或少量源材料输入、源材料体积能够被单个高上下文模型完整吞吐,且下游不依赖完整过程审计的场景。 + * **控制策略**:采用单模型或单主控的极简闭环,允许调用局部 Skill 或基础工具。系统不默认唤醒独立的多智能体沙箱,不构建厚重的交接包(Handoff),不执行无损覆盖率审计,亦不生成治理级日志。 + * **核心产物**:目标输出文件、极简的输入记录以及关键人工确认点(必要时包含抽样检查记录)。 + +* **Standard 档(证据驱动升级)** + * **升级证据**:处理多源异构材料、存在明确的下游自动化消费依赖、用户显式指令要求进行复用资产沉淀,或业务流中存在局部追踪与复盘的需求,从而需要进行少量的真实 Agent 或 Worker 调用。 + * **控制策略**:强制引入结构化的上下文编译机制(Context Compiler)限制幻觉,允许拉起有限的真实沙箱调用,建立局部的调用证据链(Invocation Record),输出可复用资产合约与关键决策门(Human Gate)。 + * **核心产物**:源映射包(Source Pack)、结构化上下文补给包(Context Pack)、可复用资产单元、局部追踪日志、决策记录以及最终目标文件。 + +* **Full 档(极限治理)** + * **升级证据**:应对试错即单向门的高法理风险商业决策、外部客户的关键交付、需要多角色形成独立张力对撞的长期运行 Runtime、包含不可逆的工具执行动作或具备强烈覆盖审计需求的生产环境自动化任务。 + * **控制策略**:必须由人工显式授权启动。强制拉起全规格的多智能体编排,挂载严密的权力矩阵(Authority Matrix)、不可篡改的底层调用证据链、全量运行时状态协议(Runtime State Protocol)、风险控制与数据安全策略,并强制包含灾难回滚预案。 + * **核心产物**:完整的 Runtime 机器状态、追加写入(Append-only)的真实调用日志、失真与风险日志、覆盖率评测报告、具备极高防御性的下游交接包以及灾难恢复计划。 + +### 1.5 预算合约 (Budget Contract) + +任何 Agentic Runtime 在启动前必须显式声明其执行预算合约。预算不仅包括传统的 Token 消耗,还必须统筹时间跨度、存储资源、工具调用频次以及专家注意力的支出限额。合约必须声明 `source_size_estimate`、`target_mode`、`token_budget`、`time_budget`、`human_attention_budget`、`tool_call_budget`、`escalation_threshold` 与 `abort_threshold` 等关键阈值。通常情况下的默认 Token 预算倍率为:Lite 档限制在源输入 Token 的 10-30 倍内;Standard 档限制在 30-100 倍内;Full 档超过 100 倍且上不封顶,但必须具备充分的治理理由并取得架构级人工授权。若系统预估当前任务消耗将超过所在档位的预算上限,必须立即挂起进程并请求升级授权,严禁静默穿透预算继续运行。 + +### 1.6 组件启用矩阵 + +在进行系统架构设计与现场实施时,开发人员必须严格参照以下功能组件的启用矩阵,以匹配对应的运行档位: + +| 组件配置项 | Lite 档位 | Standard 档位 | Full 档位 | +| --- | --- | --- | --- | +| **QPI Intake** | 强制执行 | 强制执行 | 强制执行 | +| **Task Nature Classification** | 强制执行 | 强制执行 | 强制执行 | +| **Cost Ledger (成本核算)** | 轻量简版 | 强制完整 | 强制完整 | +| **Budget Contract (预算合约)** | 轻量简版 | 强制完整 | 强制完整 | +| **Scope Drift Detection** | 强制执行 | 强制执行 | 强制执行 | +| **Stop Rule (绝对制动)** | 强制执行 | 强制执行 | 强制执行 | +| **Human Gate (决策门)** | 关键节点可选 | 强制引入 | 强制多层引入 | +| **Invocation Record** | 仅发生真实调用时必须 | 强制引入 | 全链路强制引入 | +| **Simulation Labeling** | 强制执行 | 强制执行 | 强制执行 | +| **Context Compiler** | 轻量简版 | 强制完整 | 强制全规格引入 | +| **Authority Matrix (权限矩阵)** | 视需可选 | 强制引入 | 强制引入 | +| **Artifact Contract (产物合约)** | 轻量简版 | 强制完整 | 强制完整 | +| **Runtime State Protocol** | 轻量简版 | 强制完整 | 强制完整 | +| **Tool Safety (工具安全)** | 存在工具调用时必须 | 强制执行 | 极高规格强制 | +| **Data Security (数据安全)** | 存在敏感数据时必须 | 强制执行 | 极高规格强制 | +| **Evaluation Stack (评测栈)** | 覆盖 E0 - E2 | 覆盖 E0 - E5 | 覆盖 E0 - E7 | +| **Rollback Protocol (回滚协议)** | 存在写入操作时必须 | 强制引入 | 强制引入 | +| **Governance Audit (治理审计)** | **绝对禁止默认启用** | 针对性定点审计 | 全量覆盖审计 | + +--- + +## 2. 成本隔离与防蔓延机制 (Cost Ledger & Scope Drift) + +在 Agentic 自动化管线中,最致命的工程失控往往并非由显性的报错或崩溃引起,而是系统在缺乏强力监督的状态下暗中无休止地运转,将一次简单的内容提取任务异化为庞大的系统基建。为了在运行态夺回对计算资源和专家注意力的绝对控制权,架构师必须在系统底盘强制焊死成本核算与边界探测组件。 + +### 2.1 四重消耗账本 (Cost Ledger) + +为了破除算力消耗的混沌状态并建立极度清晰的资源归因机制,任何 Agentic 工作流在启动时,其消耗的所有 Token、算时、存储、工具调用次数以及人工注意力资源,必须被强制记入以下四个物理隔离的账本之一: + +* **Content Cost (内容产出成本)**:为完成当前用户指派的直接任务所消耗的核心计算与调用资源。此类消耗仅限于直接输出目标物料的操作(例如:蒸馏一篇讨论材料、转译一份视频分镜、生成一份口播稿、提取会议纪要或输出客户报告初稿)。 +* **System-Building Cost (系统建设成本)**:为设计、搭建、扩展或重构系统底层运行能力与长期资产所消耗的资源。当系统行为涉及构建 Agent、Skill、Runtime、Protocol、评估标准(Evaluation)、工具链、业务流(Workflow)、模型索引(Model Index)、工程目录树以及定义调用标准时,其消耗必须划拨至本账本(例如:为了蒸馏单篇讨论稿而设计一个通用的知识加工 Runtime,或为了一次评审任务而重构多智能体交接协议)。 +* **Calibration Cost (校准修复成本)**:为纠正底层模型偏差、记录人工反馈轨迹、对齐专家判断边界以及构建标准评测集所支出的资源。此类任务包括分析 AI 与人类专家判断的差异、收集专家层面的修改痕迹、构建基于真实业务的高质量评测集、调整 Agent 的错误分类规则,以及建立系统整体的返工率基线指标。 +* **Exploration Cost (探索预演成本)**:为了在业务沙盘中验证新范式、新工具、新平台调用链路或新型协作拓扑结构所消耗的实验性资源。此类任务包括测试特定框架(如 Codex Thread、Claude Code Subagent、SuperPowers 或 OpenClaw)的流程承载力与能力边界,严禁将此类试探性消耗伪装为对客的生产任务。 + +### 2.2 记账核算铁律 + +系统绝对禁止将构建自动化流程的“系统建设成本”掩饰、打包或伪装为单次任务的“内容产出成本”。如果在执行一次基础任务的过程中,实际发生了诸如设计新 Runtime、编写通用通信 Protocol、创建新 Agent 或 Skill、构建评测栈或搭建长效资产的操作,这些超额消耗必须进行账务剥离。系统架构的重工业投入必须光明正大地记录在基建账本中,以接受长周期的投资回报率(ROI)审查。 + +### 2.3 漂移探测触发 (Scope Drift Detection) + +由于大语言模型(LLM)内置了强烈的规划、反思与逻辑补完惯性,一个轻量级的求解任务(P 域)极易在无监督状态下滑向包含多方审计与治理逻辑的深水区(I 域)。系统必须在各个管线节点埋设结构化的漂移探针,一旦捕捉到以下五类越界信号,即刻判定系统发生了任务蔓延(Scope Drift): + +* **信号一(基建过度行为)**:一个被预设定性为一次性(One-off)的任务,开始私自创建通用的流转 Protocol、设计预期复用的复杂目录树、撰写与当前直接产出无关的抽象规则文档、衍生出新的 Agent 或 Skill 节点,甚至企图升级为长效工作台。 +* **信号二(并发无序扩张)**:原定被束缚在 Lite 档运行的极简闭环流程,开始擅自派发多个底层 Worker、拉起多角色审查委员会、开启并行覆盖率审计、创建多个子会话(Sub-session),或执行未经授权的动态智能体路由规划。 +* **信号三(产物交付延宕)**:用户明确期待的核心业务产物迟迟未能交付,但系统的高昂资源已被大量倾注并消耗于生成路由日志、覆盖率审计报告、厚重的交接包、评审报告、修复协议、目录脚手架生成或无价值的元分析文档中。 +* **信号四(预算穿透警告)**:系统当前已发生或预估即将发生的消耗,超出了原定预算的硬性阈值且未进行主动分账申报。默认的触发条件为:Lite 档消耗超过源输入 Token 数量的 30 倍,Standard 档消耗超过源输入 Token 数量的 100 倍,或任一单一任务消耗的专家注意力超过了预设的 `human_attention_budget`。 +* **信号五(成功标准变更)**:系统的执行目标从单纯的“完成并交付一个业务结果”暗中演变为“定义并构建一套未来如何持续完成该类结果的系统机制”,这标志着任务性质已由内容产出彻底滑入系统建设领域。 + +### 2.4 漂移处置协议 (Drift Resolution Protocol) + +一旦上述漂移探测器被触发,系统必须立刻抛弃“顺其自然”的自动化运行惯性,强制执行以下阻断与人工介入动作: + +1. **挂起进程**:立即阻断当前 Agentic Runtime 的持续执行与自我繁衍能力,强制将进程状态锁定并切换为 `paused_by_scope_review`。 +2. **核心发问与重定性**:系统必须向人类控制台抛出审计质询:我们当前是否仍在执行原始的内容产出任务?如果不是,是否需要将当前衍生出的操作正式立项为系统建设任务?当前已溢出的消耗应当记入哪一本成本账?系统的运行档位(Lite/Standard/Full)是否需要进行升级调整?原始的核心任务是否仍需优先保证交付? +3. **物理分账与重启**:若经人工确认任务已发生性质变轨,必须重新进行 QPI 矩阵定性,并将此前及后续规划的超额计算消耗从内容产出账本中物理切断,强制划拨至系统建设、校准修复或探索预演账本中。 +4. **人工授权释放**:只有在严格完成重新 QPI 定性、重新挂载 Mode Selector、更新 Budget Contract、重置 Stop Rule 阈值并生成完整的决策操作记录(Human Decision Record)后,系统方可解除挂起状态继续运行。 + +--- + +## 3. 物理防伪与绝对制动 (Execution Authenticity & Stop Rule) + +在缺乏硬性物理约束的 Agentic 环境中,系统极易陷入两种致命的工程灾难:一是主节点伪造子节点工作过程的“流程幻觉”;二是子节点为了证明自身算力工作量而无限繁衍中间产物的“过度执行”。本章确立的机制旨在为自动化管线装配不可篡改的测谎探针与强力的物理断电开关。 + +### 3.1 执行真实性与主控阻断 (Execution Authenticity) + +多智能体架构的真正防御力与逻辑价值,来源于不同思维模型在绝对隔离的沙箱中产生的真实逻辑张力与视角碰撞,而非依赖单一高参数模型在同一上下文中进行的自问自答式文本模拟。系统必须对所有正式产物执行严苛的代码级测谎。 + +**主控越权阻断**:在多体编排中,主会话或 Orchestrator 仅被赋予调度、路由、聚合综合、状态记录、有限验证与人工确认转译的权限。绝对禁止主控节点凭借自身庞大的上下文吞吐能力去强行“代写”或模拟任何底层子节点的输出结果。若系统在运行中无法成功拉起真实的子线程、外部参与者或载体沙箱,进程必须挂起并进入 `blocked_waiting_for_participant_output` 状态,严禁主控节点用伪造的执行报告填补业务流程中的信息真空。 + +### 3.2 真实调用证据链 (Invocation Record) + +任何被系统声明为由独立 Agent、Reviewer、Worker、Auditor、Committee Member 或 External Participant 产出的正式业务报告或决策,必须向控制台出具完整、真实的底层调用证据链。最小规格的 Invocation Record 必须毫无遗漏地包含以下物理字段: + +* `invocation_id` +* `agent_id` 或 `role_id` +* `canonical_prompt_path` 或 `agent_spec_path` +* `runtime_id` +* `carrier_type` +* `carrier_id` / `thread_id` / `sub_session_id` +* `input_context_path` +* `input_context_hash` +* `execution_timestamp` +* `returned_output_path` +* `returned_output_hash` +* `orchestrator_id` +* `entered_synthesis` (布尔值) +* `human_gate_id_if_applicable` + +### 3.3 模拟标记与沙箱隔离 (Simulation Labeling) + +当系统因部署环境限制、外部接口调用失败、人类手动干预,或仅为流程占位而产生了一批缺乏底层真实物理咬合的“伪执行”产物时,必须立即对该类产物实施冷酷的资产隔离,以防止其污染整个业务决策链。所有此类模拟产物的元数据中必须强制注入耻辱烙印标签:`simulation_only: true`、`formal_output: false` 以及 `excluded_from_synthesis: true`。同时,系统还需声明其 `simulation_reason`(模拟原因)与 `allowed_use`(允许用途)。 + +带有上述标签的隔离产物仅被允许用于价值流转预演、人工参考草稿、流程设计样例或绿野仙踪协议的初步验证。它们被绝对禁止参与正式的逻辑综合(Synthesis),严禁用于客户可见阶段的交付,且不得作为下游自动化节点的行动依据、模型沉淀依据或法理审计依据。 + +### 3.4 最小充分阈值与前置设定 (Minimum Sufficient Threshold) + +为了防止系统在后台像细胞增殖般无限制造中间物,任何一个 Runtime 在启动挂挡前,必须与人类专家确立一份不可逾越的“验收合约”,明确系统的降熵阈值。 + +* **Minimum Viable Output**:明确定义为了满足下游逻辑的顺利消费,当前任务必须交付的最核心、最低限度的信息量是什么(例如:明确只需视频总纲与分镜骨架,不需要扩写详细的配音稿;或只需 Topic Map 与可复用物料单元,不需要拉起完整的覆盖率审计)。 +* **Sufficient Criteria**:确立何种状态即被系统判定为“已完全达标”。一旦跨越该阈值,预设的 `optional_artifacts` 将默认被系统彻底剥夺生成权限,除非获得人类专家的显式复苏授权。 +* **前置参数绑定**:合约必须绑定 `forbidden_artifacts`(禁止生成的产物清单)、`human_gate_points`(人工决策拦截点)、`budget_limit`(预算红线)以及不可修改的 `stop_condition`(停止条件)。 + +### 3.5 人工决策门合约 (Human Gate Contract) + +“人机回环(Human-in-the-loop)”绝不是一句口号,而是系统中不可逃避的责任坐标。系统禁止在代码中设置毫无约束的空洞“人工确认”节点。每个设立的 Human Gate 必须预先显式声明其合约参数,包括:`gate_id`、`decision_owner`、`input_artifacts`、`decision_options`、`default_action`、`downstream_effect`、`reversibility`、`escalation_condition`、`record_path` 以及 `timeout_policy`。 + +**决策记录输出规范**:当人类专家完成介入裁决后,系统生成的反馈记录日志至少且必须包含以下追溯字段:`decision_id`、`gate_id`、`decision_owner`、`accepted_option`、`rejected_options`、`reason`、`risk_notes`、`downstream_effect`、`rollback_condition` 以及操作发生的 `timestamp`。 + +### 3.6 运行状态机协议 (Runtime State Protocol) + +为了确保复杂管线的透明度与可追责性,所有投入运行的 Runtime 必须且只能在标准定义的有限状态机内进行流转。标准状态集包括:`initialized`、`running`、`blocked_waiting_for_human`、`blocked_waiting_for_participant_output`、`blocked_waiting_for_tool`、`paused_by_scope_review`、`paused_by_budget_guard`、`failed_recoverable`、`failed_terminal`、`completed`、`aborted_by_human` 以及 `archived`。每次状态发生物理跃迁时,必须完整记录 `previous_state`、`new_state`、`trigger`、`responsible_actor`、`timestamp` 以及约束下一步操作的 `next_allowed_actions`。 + +### 3.7 绝对停止权与熔断机制 (Stop Rule) + +在 Agentic 架构的高并发极压舱内,人类意志的最高工程体现不在于如何一键启动复杂的自动化管线,而在于何时能够决绝地踩下刹车。停止权是系统免于因追求冗余完美主义而耗尽资源的最后防线。 + +**触发条件**:一旦核心传感器捕捉到以下任何一种状态,系统必须触发无条件的熔断:产出物已触及“最小充分阈值”;运行流触及预设的人工决策门(Human Gate);预算消耗逼近 `abort_threshold` 红线;探针捕获到范围漂移(Scope Drift);底层真实调用记录失效;系统工具执行权限越界;数据安全隔离边界出现模糊;或信息来源的保真度已无法通过验证。 + +**制动执行动作**:触发制动后,系统将无视底层 Worker 是否仍在排队执行或生成附加参考报告。系统必须停止创建新任务,取消队列中尚未启动的任务,对正在运行的线程发出协作取消(Cooperative Cancellation)指令。对于无法响应协作指令的非关键增殖线程,系统有权执行代码级的强制终止。终止动作执行前,系统必须尽最大可能保存当前的 `partial_outputs`、`state_snapshot`、`action_log`、`unfinished_tasks` 与 `risk_notes`,并最终强制将所有核心进程锁定为 `blocked_waiting_for_human`。 + +--- + +## 4. 权限、安全与副作用控制 (Authority, Tool Safety & Data Security) + +多智能体系统真正对物理与商业世界构成威胁的地方,并不在于其逻辑推理的误差,而在于其执行物理副作用(如写入、删除、调用外部 API)的能力。因此,所有的工具调用权限、文件系统覆盖、对外数据交互及客户可见输出,都必须被强制囚禁于严密的权限矩阵与副作用隔离层中。 + +### 4.1 权力矩阵 (Authority Matrix) + +为了防止底层节点擅自覆写核心产物或盲目调用高危接口,系统必须为每一个 Agent、Skill 或 Runtime Node 在代码级焊死其物理权限等级: + +* **A0 Observe (观察)**:最低权限。节点仅拥有基础读取权限,可生成内部标记与逻辑标注,绝对无权修改任何对下游可见的状态或文件。 +* **A1 Suggest (建议)**:建议权限。允许节点输出分析结论与优化方案,但其产物处于物理隔离状态,不能直接覆写任何正式产物,仅供高阶决策节点作为参考依据。 +* **A2 Draft (起草)**:起草权限。被授权生成初稿形态的物料,但该物料在状态机流转中被强制挂起拦截,必须经由人工决策门(Human Gate)或具备对应权限的 Owner Agent 显式签发后,方可进入正式流转链。 +* **A3 Modify (修改)**:受限覆写权限。允许在预设的上下文边界内修改正式产物,但必须严格限定并审查 `allowed_paths`、`allowed_files`、`allowed_fields`、`modification_scope`,并提前铺设 `rollback_path`。 +* **A4 Decide (裁决)**:结构性决策权。行使该权力时,系统强制要求执行节点同步输出包含逻辑归因的 `decision record`、`decision rationale`、`risk notes` 以及对其 `downstream effect` 的预判。 +* **A5 Execute (执行)**:物理动作权限。该权限必须被强制细分为三个相互独立的子级沙箱: + * **A5-R (Read Tool)**:只读工具调用。允许系统执行网络搜索、读取本地文件、执行无害的数据库查询、查看系统日志或读取流转状态。 + * **A5-W (Write Tool)**:写入动作执行。允许系统写文件、改代码、更新配置、生成并保存底层资产。该权限必须满足严格的允许路径检查,并留存变更日志与 Diff,支持无损回滚策略。 + * **A5-X (External Action)**:高危外部动作。允许系统发送消息、发布内容、调用客户业务 API、执行支付指令、删除远程资源或修改对客可见状态。此类权限默认对所有 Agent 关闭,绝不允许自动执行,必须经过 Human Gate 签发或 Runtime 级别的高密级明确授权。 +* **A6 Block (阻断)**:最高优先级的系统熔断权限。一旦触发该权限(例如探针发现严重逻辑悖论、面临法理追责风险、数据泄漏报警或预算穿透),系统全线进程将立刻挂起阻断,并强制召唤人类专家介入。 + +### 4.2 最小权限原则与副作用隔离 + +系统的底层核心逻辑必须遵循“最小权限原则(Least Privilege)”。Agent 所拥有的工具执行权限必须永远小于其语言推理能力——能进行逻辑推演不代表能实施写入;能理解任务目标绝不代表系统应该向其开放工程的全局目录修改权。严禁将全量写入权限、外部 API 调用或内容发布能力作为默认配置授予通用推理 Agent。 + +任何具备写入(A5-W)或外部执行(A5-X)能力的 Agent,必须被置于副作用隔离机制(Side-effect Isolation)之中。执行动作前,必须强制声明 `allowed_paths` 与 `forbidden_paths`,在可能的情况下优先执行 `dry-run` 预览;执行高危动作前必须先生成并提交 `action plan`,执行完毕后生成全量 `action log`,并确保相关动作具备人工二次确认门禁或一键恢复机制。 + +### 4.3 数据分级、密钥纪律与外发红线 + +系统必须为所有灌入的输入材料进行显性的数据等级标记,包括公开材料(Public)、内部材料(Internal)、包含客户商业利益的机密数据(Confidential),以及包含个人隐私、财务或法律代码的极敏感数据(Sensitive)。不同的数据等级将直接触发底层路由拦截器,决定该段材料是否允许被传出至外部云端模型、是否需要强制脱敏,以及是否允许留存长期日志或被用于后续的模型微调。 + +**密钥纪律(Secrets Discipline)**:系统极其严厉地禁止任何 Agent 或 Skill 将 API Key、Token、安全凭证等密钥写入明文 Prompt 中;禁止将其存入常规日志或上下文补给包(Context Pack)中;禁止主节点将其暴露给无需该执行权限的次级 Worker。所有密钥必须通过高安全的独立环境变量层或平台专有授权通道进行无感传递。 + +**数据外发红线**:在调用任何外部大模型、外部工具 API 或多模态生成服务前,系统必须执行阻断审查。若无法明确确认当前上下文数据是否被允许外发、是否含有需脱敏的客户及个人信息,或无法确认第三方服务提供商的日志留存与二次训练规则,则系统必须默认切断该外部连接的调用授权。 + +### 4.4 过程数据主权与平台治理限制 + +在人机共创的过程中,专家留下的每一次局部修改痕迹、逻辑反驳意见、操作过程中的犹豫停留或编辑轨迹,都是极具价值的领域知识资产,同时也是高度敏感的商业业务数据。系统在采集此类隐性遥测数据时,必须提供明确的采集授权、严格的用途边界、隔离存储规范以及一键清除机制。严禁系统以“自我学习与智能进化”的名义,默认吞噬、劫持专家的隐性经验或客户的垂直业务场景数据。 + +最后,任何外部运行平台、自动化框架或第三方插件的默认调度行为,在物理层面均不具备覆盖本《Agentic Engineering Handbook》的合法效力。如果开发过程中引入的某项辅助插件存在自动跨界开启子线程、自动触发重型安全审查或静默生成大量补全产物的倾向,系统控制权必须立即上交至人工控制台。所有的插件生成结果,在通过严苛的产物合约(Artifact Contract)、证据链核验(Execution Authenticity)与人工决策门(Human Gate)的检视前,绝不能直接跃升为系统的正式业务产物。 + +--- + +## 5. 运行修复与回滚 (Retry, Repair & Rollback) + +在 Agentic 系统的极压舱中,局部的调用失败并不致命;真正构成系统性风险的,是毫无节制的无限重试、试图掩盖错误的静默修补、偏离原意的迭代变异,以及缺乏后路的不可回滚动作。 + +### 5.1 重试上限与熔断 (Retry Limits) + +任何由自动化流程发起的异常重试动作必须被强行施加物理上限。默认的重试红线规定如下:面对工具调用失败、输出格式错误或网络与外部 API 的临时性阻断,系统最多仅允许发起两次自动重试;面对权限申请失败或调用越界,系统绝对禁止尝试通过替换接口或更换策略进行绕过;面对底层的推理质量不达标,系统严禁利用算力优势发起无限重写。一旦突破上述预设的重试阀值,当前节点状态必须被强制锁定为 `failed_recoverable` 或 `blocked_waiting_for_human`,交由更高维度的治理权柄接管。 + +### 5.2 失败物理定性 (Failure Classification) + +系统产生的故障必须进行结构化的类型鉴别,绝对禁止在运行日志中笼统地抛出“执行失败”的宽泛声明。所有的故障记录必须归入以下标准序列: + +* **F0 Format Failure**:格式失败 +* **F1 Tool Failure**:工具失败 +* **F2 Permission Failure**:权限失败 +* **F3 Data Failure**:数据缺失或数据污染 +* **F4 Source Fidelity Failure**:来源保真失败 +* **F5 Reasoning Failure**:推理失败 +* **F6 Invocation Failure**:真实调用失败 +* **F7 Budget Failure**:预算失败 +* **F8 Governance Failure**:治理违规失败 +* **F9 Terminal Failure**:不可恢复的终极失败 + +### 5.3 修复计划生成 (Repair Plan) + +当产物被判定为失败且尚未触及重试上限时,系统必须先拉起一个独立的线程生成结构化的修复计划(Repair Plan),而非立刻盲目启动重新生成。该计划必须向控制台显式声明以下字段: + +* `failure_type` (故障类型) +* `failure_location` (故障坐标位置) +* `affected_artifacts` (受波及的下游资产) +* `impact_level` (系统影响评级) +* `repair_scope` (预期的修复范围) +* `human_gate_required` (是否需要召唤人工干预) +* `reinvocation_required` (是否需要重启底层真实调用) +* `rollback_required` (是否需要执行物理回滚) +* `new_budget_estimate` (全新的预算消耗预估) + +### 5.4 灾难回滚协议 (Rollback Protocol) + +任何被赋予 A5-W (写入) 或 A5-X (外部动作) 权限的节点,在执行可能改变外部状态的动作前,必须强制搭载回滚协议。系统必须在执行动作的瞬间生成并封存变更前的状态快照(`pre_change_snapshot`)、变更日志与比对文件(`diff` / `action_log`),并锚定回滚操作的物理调用路径(`rollback_path`)与责任方(`rollback_owner`)。 + +对于诸如发布客户可见内容、删除远程资源或触发外部生产 API 等本质上不可逆的操作,系统必须提前发出不可逆转警告(`irreversibility_warning`),将其硬性阻断并强制要求通过 Human Gate 获取人工签发授权。 + +### 5.5 修复后的二次验证 (Re-verification) + +任何经历过修复周期的产物,在重新进入下游流转前,必须被强制押送回对应的评测探针下进行二次校验。修复格式错误后必须重过 E1 Format Test,修复事实幻觉后必须重过 E2 Factual Test,修复逻辑裂痕后必须重过 E3 Reasoning Test,而触发过越界警告的权限修复则必须接受完整的 E7 Governance Test 审计。系统绝不能因为节点自我声明“已修复”而在此处开设任何豁免通道。 + +--- + +## 6. 通用运行组件与资产标准 (Agentic Runtime Components & Artifact Standards) + +当系统从轻量级(Lite)单兵作战攀升至标准(Standard)或完整治理域(Full)时,临时性的硬编码约束将彻底无法抵御系统内部产生的混乱熵增。本章定义了 Agentic 时代所需的重工业扩展组件与资产规约,它们是支撑多智能体协同、确保认知物料跨周期复用并抵抗架构腐化的高阶底座。 + +### 6.1 产物防伪合约 (Artifact Contract) + +“产生海量文件却无法辨认物理真伪”是伪工程化的典型并发症。为了确保认知物料的可追溯与安全复用,任何脱离草稿态进入正式资产池的产物,必须在头部显式绑定一份合约声明,用以宣誓其生命周期与校验元数据。正式产物合约必须包含以下强制性字段: + +* `artifact_type`:精确归属于 Prompt、Agent Spec、Skill、Runtime、Model Card、Model Index、Evaluation、Tool、Workflow、Context Pack、Final Output 或 Simulation Output 等标准类别。 +* `status`:标记其当前处于 draft、candidate、active、deprecated、archived、rejected 亦或是带毒的 simulation-only 阶段。 +* `authority`:清晰界定该产物仅仅是内部笔记(internal_note)、参考(reference_only)、正式依据(formal_basis)、可执行状态(runtime_executable),还是客户可见交付物(customer_visible)。 +* `source_of_truth`:事实来源的物理依据。 +* `downstream_use`:合法消费该产物的下游节点是谁,应用于什么阶段。 +* `invalidation_condition`:定义在何种物理或业务条件下(如:上游源文件更新、Canonical Prompt 更新、用户推翻结构、Human Gate 未通过),该产物判定为失效且需要触发重跑。 +* `cost_class`:归属消耗账本。 +* `created_by` / `created_at` / `last_updated`:全生命周期追踪戳。 + +### 6.2 运行时成熟度模型 (Runtime Maturity Model) + +为了杜绝团队在技术论证与生产交付之间产生致命的预期错位,杜绝“跳级声明成熟”的技术浮夸,必须使用严密的成熟度标尺丈量每一个 Agentic 项目的演进坐标。 + +* **M0 Concept (概念态)**:仅存在思想模型或业务论证,尚未进行任何底层的自动化流程拆解。 +* **M1 Manual (手工态)**:领域专家通过手工干预跑通业务闭环,符合绿野仙踪(Wizard of Oz)协议,在极低成本下验证了智能流的核心业务价值。 +* **M2 Assisted (辅助态)**:AI 仅仅作为外脑介入生成草稿或检查清单,核心推进动力与状态机驱动完全依赖人类手动操作。 +* **M3 Protocolized (协议态)**:系统的输入、输出、角色边界、状态机流转、人工决策门与停止规则等核心架构要素,已在技术规范层面被彻底显性化。 +* **M4 Semi-Agentic (半 Agentic 态)**:系统内部分 Agent、Skill 或 Tool 已实现真实的自动化物理调用,并具备完整的底层 Invocation Record,但仍依赖人类来推进关键决策节点。 +* **M5 Production (生产态)**:具备能够在生产环境下重复运行的刚性管线。系统拥有自动化评测探针、执行监控、异常捕获、日志记录、基础回滚及严密的权限管控,完全达到内部工程可用级别。 +* **M6 Governed (治理态)**:系统的终极形态。具备抵御高强度审计、法理追责与灾难回滚能力,完全适配高法理风险场景、不可逆的对外工具执行,以及外部客户的最严苛交付。 + +**成熟度声明铁律**:严禁系统产物伪造自身的演进坐标。M2 绝不可伪装为 M5,M3 不可伪装为 M6;任何带有模拟烙印的产物均不可宣称为 M4;缺乏真实调用证据(Invocation Record)支撑的流程不可自诩为真实的 Agentic;缺失独立评估栈(Evaluation Stack)的工程不可标记为 Production;无法通过治理测试(Governance Test)的管线不可标榜为 Governed。 + +### 6.3 上下文结构化编译 (Context Compiler) + +绝对禁止将漫长、原始且异质的语料一股脑地倾倒进所有 Agent 的上下文窗口。在任何治理域(I 域)或高价值的求解域(P 域)任务启动前,必须将“上下文工程”剥离为一项独立的物理预处理动作。 + +面对高连贯性的源材料长文,在启动切片分块前,系统必须强制实施全局完形扫描(Whole-source Gestalt),优先锁定核心张力、主轴结构、目录骨架、演化线与关键反例,以此防止 Chunk-first 策略引发的结构性失明。当源材料性质为混合型时,必须优先进行宏观主题拆分;当源材料为纯粹的碎片时,系统应采用平铺发现策略,绝不强行伪造层级关系。 + +基于上下文的“最小充分原则”,上下文编译器最终应根据下游消费节点的特定需求,精准输出并分发以下类型的结构化补给包:原源摘要(`source_digest`)、任务特化分发包(`task_specific_context_pack`)、角色专供包(`role_specific_dispatch_pack`)、供人工复核的决策上下文(`decision_context`)、评测底座(`evaluation_context`)以及包含核心预警信息的风险笔记(`risk_notes`)。 + +### 6.4 来源保真与证据链索引 (Source Fidelity & Evidence Index) + +任何涉及材料加工、报告汇编、知识蒸馏、复杂方案分析的管线,必须为生成的结论焊死来源索引。正式输出中的一切关键判断,必须能够倒查回溯至:原始物理来源、精确的定位坐标(`source range` / `paragraph` / `block id`)、主导该结论的参与者实体(Agent / Worker),以及必须明确注明该判断的信息性质。信息的性质标签必须被精确归类为:`source_fact` (原文事实)、`source_claim` (原文主张)、`inference` (模型推理)、`synthesis` (综合归纳)、`external_fact` (外部事实)、`assumption` (模型假设) 或 `human_decision` (人工裁决)。 + +**来源铁律**:绝对禁止系统将中间摘要包装并冒充为新的绝对事实来源;绝对禁止把模型发散的综合判断伪装成原始材料本身包含的事实;禁止在未标明“推理性质”的语境下强行输出确定性结论;若底层的 `source index` 已经丢失或遭到截断,系统绝对无权对外声称自身完成了无损提取。 + +### 6.5 高维分层评测栈 (Evaluation Stack) + +仅仅依靠单一维度上的“准确率”或“文本相似度”,根本无法测度专家级 Agentic 系统在极端状态下的真实抗压能力。为了确保系统免于崩溃,必须在管线上部署从底层机械运行属性一直延伸至顶层战略效用的全方位探测针。 + +* **E0 Smoke Test (冒烟测试)**:检验系统在最基本的骨架层面能否跑通(如:产物文件是否成功生成、Tool Call 是否正确响应、基础目录结构是否正确映射)。 +* **E1 Format Test (格式测试)**:检验输出物料是否严格遵守预设的 Schema 结构、长度预算天花板、变量命名规则及业务语言规范。 +* **E2 Factual Test (事实测试)**:核查文本溯源的保真度。严密检验系统是否在逻辑真空中编造事实幻觉、是否遗漏了核心源材料,或存在引用混淆现象。 +* **E3 Reasoning Test (推理测试)**:对系统的逻辑链条进行极限刺探。检验系统是否充分暴露了推演假设、推理环路是否闭合、反例材料是否得到处理以及边界条件是否明确说明。 +* **E4 Expert Similarity (专家相似度)**:量化机器判断与人类专家直觉在决策面上的重叠度,并冷酷地记录系统产生偏差时的底层逻辑可解释性。 +* **E5 Decision Utility (决策效用)**:最高层级的业务测试指标。验证系统是否真实有效地帮助人类专家在现实中完成了更优的决策、更敏捷的判断、更低能耗的认知输出、降低了返工率并稳固了风险控制。 +* **E6 Calibration Test (校准测试)**:评测系统在错误恢复态下的“纠错摩擦系数”。检验当系统不可避免地犯错时,人类专家是否能低成本地向其指出错误所在,系统能否精确理解反馈梯度并将修复经验固化,且不影响后续批处理任务。 +* **E7 Governance Test (治理测试)**:以极端的合规与审计视角进行的终极测试。全面核查 Trace 追踪全链路是否完备、Authority 权限沙箱隔离是否被击穿、Rollback 回滚机制是否真正可行、数据安全政策是否被落实以及系统整体的责任边界是否被模糊。 + +### 6.6 按场景选择评测层级 + +测试的烈度必须与场景的深水区级别严格匹配: + +* **Q 域简单查询**:必须覆盖 E0 – E2 评测。 +* **基础 P 域生产流水线**:必须覆盖 E0 – E3 评测。 +* **高阶生产工坊**:必须覆盖 E0 – E5 评测。 +* **具有专家属性的辅助工作台**:必须覆盖 E2 – E6 评测。 +* **面对复杂熵增的战略透镜级系统**:必须覆盖 E3 – E7 评测。 +* **达到 Full 档的终极治理 Runtime**:必须经受 E0 – E7 的全方位高压测试。 + +系统绝不允许使用人类主观的“感觉还不错”来替代 E5 及以上的高维度硬性治理指标评估。 + + +## 7. 开工清单与反模式 (Start Checklist & Anti-patterns) + +本章旨在将前述的高维治理规则压缩为开发人员在现场可逐项核验的执行动作。系统架构在向高档位跃迁前,必须接受极度严苛的准入核查,同时必须在开发生命周期内持续识别并清剿具有高度破坏性的反模式。 + +### 7.1 Agentic Project Start Checklist (开工强制核验清单) + +每一个 Agentic 项目在正式编码与拉起管线前,系统负责人必须强制回答以下 20 个系统级验收问题。未完整清查并签署该清单的工程管线,绝对禁止脱离 Lite 档进入 Standard 或 Full 档位的生产环境运行: + +1. 系统的**原始业务任务**究竟是什么? +2. 在 **QPI 矩阵**中,该任务的准确定性(查询、求解、或治理)是什么? +3. 该任务的**终极物理性质**是什么(一次性内容产出、长期能力建设、偏差校准,还是探索预演)? +4. 系统初始启动挂载的**运行档位**是什么(Lite / Standard / Full)? +5. 满足下游消费的最核心、不可删减的**最小充分产物 (Minimum Viable Output)** 是什么? +6. 触发管线物理断电的**绝对停止条件 (Stop Condition)** 是什么? +7. 系统执行的 Token、算时与人类注意力 (Human Attention) 的**硬性预算上限**分别是多少? +8. 当前处理的源材料是否涉及客户机密、安全密钥或个人隐私等**高敏感数据**? +9. 当前的业务逻辑是否刚性需求**底层真实多 Agent沙箱调用**? +10. 若确实需要真实调用,底层生成的 **Invocation Record (调用证据链)** 将被物理保存在哪里? +11. 是否允许底层 Agent 拥有跨过沙箱隔离的**文件与数据写入权限**? +12. 是否允许底层 Agent 触发不可逆的**外部生产 API**? +13. 管线中负责拦截高危动作与责任确认的 **Human Gate (人工决策门)** 部署在哪些物理节点? +14. 针对上述 Human Gate,谁是承担最终法理与业务责任的 **Decision Owner**? +15. 系统的正式产物将通过何种机制被强制注册进 **Artifact Contract (产物防伪合约)**? +16. 针对该项目的业务深度,系统的**全链路评测栈**必须覆盖至 E 几级别(E0 - E7)? +17. 系统的最终结论与报告是否强制需要提供精确的 **Source Fidelity (来源保真与证据索引)**? +18. 面对潜在的崩溃或越权执行,系统是否已预置了底层支持的 **Rollback Protocol (回滚协议)**? +19. 框架内集成的哪些底层平台插件被**显式允许自动触发**? +20. 在预算消耗、执行时长或中间物繁衍达到何种阈值时,系统必须触发 **Scope Drift Review (范围漂移审查)**? + +### 7.2 常见反模式 (Anti-patterns) + +以下 12 种反模式是 Agentic 工程在缺乏强约束下极易滋生的架构腐化现象。一旦在代码审查或运行态监控中发现以下症状,必须立即实施架构级阻断: + +* **1. Prompt 万能化 (Monolithic Prompting)**:开发人员试图将 Agent 设定、Skill 逻辑、Runtime 流转状态与 Model Card 全部强行塞入一个巨型的底层 Prompt 中。此举将直接导致认知物料难以独立维护、评测探针失效、逻辑无法跨节点复用,并彻底丧失复杂工程的追踪与平台迁移能力。 +* **2. 流程幻觉 (Process Hallucination)**:系统表面上生成了齐全的评审报告、分发包、目录树与运行日志,但在底层沙箱中根本不存在真实的 Agent 独立调度,即没有产生任何真实的 Invocation Record。 +* **3. 治理过载 (Governance Overload)**:系统针对一次性(One-off)或轻量级的内容处理任务,滥用算力启用了 Full 档 Runtime。典型症状为处理 5 万字材料却消耗了 3000 万 Tokens,并繁衍出大量冗余的中间审计记录、交接包与主题切片,导致核心业务产物的 ROI(投资回报率)严重失真。 +* **4. 成本混账 (Cost Ledger Entanglement)**:系统在满足用户的一次性结果诉求时,顺带构建了一套庞大的底层执行机器,却在核算时将复杂的系统建设成本打包掩饰为该次任务的直接内容产出成本,破坏了长期基建的审计透明度。 +* **5. 中间物无限繁殖 (Intermediate Artifact Proliferation)**:在用户期待的核心产物迟迟未交付时,系统底层的 Worker 节点为了证明自身运转,在暗中不断并发生成大量的覆盖率审计、路由日志、交接备忘录、修复笔记与元分析报告。 +* **6. 上下文倾倒 (Context Dumping)**:系统跨过上下文编译器(Context Compiler),将所有原始、未拆解的庞杂材料一股脑地倾倒进所有 Agent 的上下文窗口中。这将引发极高概率的角色污染、判断失焦、算力严重浪费以及溯源保真度的断崖式下跌。 +* **7. 权限裸奔 (Unbound Execution Privilege)**:开发人员图谋调用便利,直接赋予负责基础逻辑推理的 Agent 全量的文件写入、资源删除、内容公开发布以及外部高危 API 调用的权限。 +* **8. 无评测上线 (Production without Evaluation)**:系统剥离了全维度的 Evaluation Stack,仅凭开发人员或人类专家的主观感受(“我觉得结果看起来不错”)便直接宣告管线进入生产态(Production)。**红线:无独立评测栈,绝对不得声明 M5 生产态。** +* **9. 模拟产物污染 (Simulation Contamination)**:带有 `simulation-only` 耻辱烙印的非真实沙箱产物,逃避了阻断机制,被非法混入正式的综合裁决链(Synthesis)。这是多 Agent 系统最致命的根级数据污染。 +* **10. 黑盒校准 (Opaque Calibration)**:当系统最终输出发生严重业务偏差时,人类专家在控制台根本无法找到低成本的纠错入口。典型症状为系统产物缺乏结构化的决策归因(Decision Rationale)、未标记错误分类锚点、缺失反馈槽位(Feedback Slot)且无法自动生成修复计划。 +* **11. 插件篡权 (Plugin Usurpation)**:引入的第三方平台插件或自动化 Skill Pack 的默认执行逻辑,静默覆盖并接管了本手册规定的治理红线。其症状表现为插件在后台自动拉起未授权的子线程、自动进入重型审查流程、擅自生成无关的系统目录,或通过幻觉强行补全原本已经失败的执行链条。 +* **12. 停止权失效 (Stop Rule Failure)**:系统在核心产出物已经越过“最小充分阈值”后,非但没有触发物理制动,反而凭借残余的可用预算与模型生成本能,继续在后台生产大量“看似有用实则冗余”的附加材料。**红线:系统绝对不得仅仅因为“尚有算力能够继续生成”,就拒绝执行物理断电。** + +--- + +## 8. 附录:标准元数据模板 (Appendix: Standard Metadata Templates) + +本附录收录了支撑 Agentic 系统各核心治理组件运转的标准数据物理格式。所有的运行时产物、日志收集与合约绑定,必须严格使用以下 YAML 格式模板进行元数据的强类型约束,拒绝任何非结构化的文本描述。 + +### 8.1 真实调用证据链 (Invocation Record Template) + +```yaml +invocation_id: +runtime_id: +agent_id: +role_id: +canonical_prompt_path: +agent_spec_path: +carrier_type: +carrier_id: +thread_id: +input_context_path: +input_context_hash: +execution_timestamp: +returned_output_path: +returned_output_hash: +orchestrator_id: +entered_synthesis: false +human_gate_id_if_applicable: +status: +notes: + +``` + +### 8.2 模拟烙印 (Simulation Metadata Template) + +```yaml +simulation_only: true +formal_output: false +excluded_from_synthesis: true +simulation_reason: +allowed_use: +created_by: +created_at: +must_not_enter: + - formal_synthesis + - customer_delivery + - model_card_source + - governance_audit + +``` + +### 8.3 人工决策门记录 (Human Gate Record Template) + +```yaml +decision_id: +gate_id: +decision_owner: +input_artifacts: +decision_options: +accepted_option: +rejected_options: +reason: +risk_notes: +downstream_effect: +reversibility: +rollback_condition: +timestamp: + +``` + +### 8.4 产物防伪合约 (Artifact Contract Template) + +```yaml +artifact_type: +status: +authority: +source_of_truth: +downstream_use: +invalidation_condition: +cost_class: +created_by: +created_at: +last_updated: +related_invocations: +related_human_gates: +related_sources: + +``` + +### 8.5 状态机流转日志 (Runtime State Transition Template) + +```yaml +runtime_id: +previous_state: +new_state: +trigger: +responsible_actor: +timestamp: +next_allowed_actions: +blocked_reason: +related_artifacts: +notes: + +``` + +### 8.6 成本核算账本 (Cost Ledger Entry Template) + +```yaml +ledger_id: +task_id: +cost_class: +mode: +token_estimate: +token_actual: +time_spent: +tool_calls: +human_attention_minutes: +storage_used: +reason: +approved_by: +timestamp: + +``` + +### 8.7 结构化修复计划 (Repair Plan Template) + +```yaml +repair_id: +failure_type: +failure_location: +affected_artifacts: +impact_level: +repair_scope: +human_gate_required: false +reinvocation_required: false +rollback_required: false +new_budget_estimate: +repair_owner: +next_state: + +``` + +--- + +## 9. 结语:现场纪律 (Conclusion: Field Disciplines) + +Agentic 工程的本质绝非简单且粗暴地“让 AI 承担更多工作”。它是将人类专家在深水业务区中的核心判断、法理责任、隐性经验积累、材料处理能力、流程安全边界以及底层工具的调用权限,精密地封装并装入一台处于微秒级高并发、高速运转状态的认知反应堆中。 + +因此,本《Agentic Engineering Handbook》诞生的根本目的并不是为了鼓励无限制的自动化,而是为了在自动化彻底脱缰之前,为其强行加装必不可少的物理遏制结构: + +* 阻断失控的**入口闸门 (Intake Valves)** +* 追溯算力消耗的**成本账本 (Cost Ledgers)** +* 限制工具滥用的**权限阀门 (Authority Matrix)** +* 刺探底层逻辑的**防伪探针 (Authenticity Probes)** +* 锁定流转阶段的**状态仪表 (State Protocols)** +* 避免信息污染的**数据隔离 (Data Isolation)** +* 核验系统极限的**评测探针 (Evaluation Stack)** +* 防御不可逆灾难的**回滚绳索 (Rollback Protocols)** +* 夺回系统控制权的**绝对刹车 (Stop Rules)** + +在架构的演进过程中,系统表现得越是聪明,它就必须受到越严苛的现场物理规矩约束;业务管线的前端表现得越是丝滑平整,架构师就越需要去监控其后端为抵御熵增而产生的执行废热;底层 Agent 的行动能力越强,就越不能允许其在缺乏权限沙箱的情况下直接接触物理世界。 + +**HiFi Agentic 工程的底线从来都不是“全自动完成计算”,而是确保系统在任何极端载荷下都具备:高保真 (High-Fidelity)、可校准 (Calibratable)、可追踪 (Traceable)、可停止 (Stoppable) 与绝对的可追责性 (Accountable)。**