# 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 工程的底线不是“自动完成”，而是：高保真、可校准、可追踪、可停止、可追责。**