43 KiB
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 的高维架构沙盘，转化为现场可执行的工程界桩，聚焦于解决：
如何开工
如何分诊
如何限流
如何调用
如何防伪
如何控权
如何熔断
如何回滚
如何验收
如何避免系统自我繁衍
本手册不是方法论宣言，而是运行治理规程。
HiFi Agent Studio 回答：
我们为什么这样做 AI？
什么是高保真 Agent？
什么复杂性不可被降维？
什么责任不可外包？
本手册回答：
一个 Agentic 项目来了，第一步填什么？
开什么档位？
允许哪些 Agent / Skill / Tool？
哪里必须停？
什么产物是真的？
什么产物只是模拟？
什么成本应记入哪本账？
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 模拟与正式执行的边界
绿野仙踪阶段允许人类专家、主控节点或单一模型模拟 Agent，以低成本验证价值流。
但所有此类产物必须被标记为：
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。 默认架构：单节点调用。
红线：
绝对禁止为 Q 域任务编排复杂多体流程。
绝对禁止为单次查询启动委员会、覆盖审计或治理级 Runtime。
示例：
查一个文件路径
确认某个定义
提取某段材料中的事实
查询某个指标
【P】求解 / Problem
核心匮乏：路径缺失。 场景特征：目标明确，但需要工程化转换、拆解、生产或优化。 系统响应：SOP、模板化约束、工具链、批量执行、人工抽检。 默认架构：逻辑轮机或生产工坊。
P 域架构复杂性应优先倾注于：
稳定吞吐
可验证输出
低返工
可复用生产线
格式一致性
上下文压缩
批处理效率
而不是多角色治理。
示例：
长文转分镜
批量生成配音稿
图片提示词生成
文档拆分
素材蒸馏
报价模板生成
标准报告初稿
【I】治理 / Issue
核心匮乏：秩序、共识与责任边界缺失。 场景特征：无唯一最优解，存在隐蔽变量、多方权衡、非遍历性风险或单向门决策。 系统响应：战略透镜、人机回环、预设委员会、Human Gate、权限阻断。 默认架构：Interactive Runtime 或 Governed Runtime。
I 域架构复杂性必须倾注于：
保真度
责任锚定
多视角张力
审计可追踪
人工裁决
反例处理
风险阻断
绝不允许用并发掩盖判断逻辑的脆弱。
示例：
核心立意判定
重大客户方案取舍
战略级评审
高风险心理诊断辅助
不可逆商业决策
模型边界裁决
组织流程重构
1.2 任务性质定性
完成 QPI 后，必须明确当前动作的终极标的。
同一个表面任务，可能属于完全不同的性质。
A. 一次性内容产出
系统运作仅为获取当下的单一结果材料。
示例：
整理一篇 5 万字讨论稿
生成一个视频分镜
提炼一次会议纪要
写一份客户报告初稿
默认要求：
Lite 档
最小充分产物
轻量记录
禁止自动升级为 Runtime 建设
B. 可复用能力沉淀
系统运作为了提炼可跨项目复用的资产。
示例：
把某个提炼方法沉淀为 Skill
把某个专家判断结构沉淀为 Model Card
把某类报告流程沉淀为 Workflow
把旧 Prompt 升级为 CCPE-Lite
默认要求：
Standard 档
资产合约
局部评测
明确下游消费场景
C. 治理级系统建设
系统运作为了构建可长久运行、可审计、可追责、可恢复的 Runtime 或工作台。
示例：
多 Agent 写作评审 Runtime
知识加工 Runtime
客户方案生成与审核工作台
高风险决策辅助系统
Agentic 生产系统
默认要求：
Full 档候选
完整权限矩阵
Invocation Record
Runtime State Protocol
Evaluation Stack
Rollback Protocol
D. 校准与评测任务
系统运作为了修正模型偏差、构建评测集、记录专家反馈、对齐专家判断边界。
示例：
收集专家修改痕迹
构建 100 道标准评测题
分析 AI 与专家判断差异
调整 Agent 的错误分类
建立返工率指标
默认要求：
Calibration Cost 记账
过程数据授权
Evaluation Stack
Expert Attention Budget
E. 探索预演任务
系统运作为了验证新范式、新工具、新调用链路或新组织方式。
示例：
测试 Codex Thread 是否能作为真实 Agent carrier
测试 Claude Code subagent 调用
测试 SuperPowers 对流程的影响
测试新型多 Agent 协作拓扑
默认要求：
Exploration Cost 记账
不得伪装为生产任务
不得承诺稳定交付
必须记录失败边界
1.3 铁律：任务性质不得暗中变轨
如果原始目标只是：
提炼一篇 5 万字文稿
系统绝不能在执行中私自搭建一套：
知识加工园区
多 Agent 治理 Runtime
通用 Skill 生态
完整覆盖审计体系
长期下游 handoff 协议
一旦任务从内容产出滑入系统建设，必须触发 Scope Drift Review。
1.4 档位挂载 / Mode Selector
默认轻量，证据驱动升级。
系统物理操作杆在启动时，必须且只能挂在 Lite 档。 除非出现明确升级证据，否则不得凭借工程师的架构审美、算法崇拜或自动化惯性擅自升档。
Lite 档：默认启动
适用边界：
一次性任务
低法理风险
单源或少量源材料
源材料可被单个高上下文模型完整处理
无需真实多 Agent 独立判断
下游不依赖完整过程审计
控制策略：
单模型或单主控极简闭环
可使用局部 Skill 或工具
不默认唤醒多 Agent 独立沙箱
不默认创建厚重 handoff
不默认做覆盖审计
不默认生成治理级日志
核心产物：
目标输出文件
极简输入记录
关键人工确认点
必要时的抽样检查
禁止事项：
不得自动拉起委员会
不得自动创建 Runtime
不得自动生成厚 topic docs
不得自动做 lossless coverage audit
不得将一次性任务重构为平台建设
Standard 档：证据驱动升级
升级证据：
多源异构材料
明确下游自动化消费依赖
需要可复用 Skill / Workflow / Model Card
用户明确要求能力沉淀
存在局部追踪与复盘需求
需要少量真实 Agent / Worker 调用
控制策略：
结构化上下文编译
有限真实调用
局部 Invocation Record
可复用资产合约
局部评测
关键 Human Gate
核心产物：
Source Pack
Context Pack
Reusable Artifacts
Decision Record
局部追踪日志
目标输出文件
限制：
允许真实 Agent / Worker，但必须限定角色数量、调用目的与产物边界。
允许审计，但必须是 targeted audit，不得自动进入 Full 覆盖审计。
Full 档：极限治理
升级证据：
高法理追责风险
单向门商业决策
外部客户关键交付
多角色真实张力对撞
长期运行 Runtime
强审计需求
不可逆工具执行
生产环境自动化
控制策略：
全规格多智能体编排
Authority Matrix
Runtime State Protocol
完整 Invocation Records
Coverage / Governance Audit
Rollback Protocol
Human Gate Contract
Data Security Policy
核心产物：
完整 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，还包括时间、存储、工具调用和专家注意力。
必须声明：
source_size_estimate
target_mode
token_budget
time_budget
human_attention_budget
storage_budget
tool_call_budget
escalation_threshold
abort_threshold
budget_owner
默认预算倍率：
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 / 内容产出成本
为完成当前用户直接任务所消耗的核心资源。
示例：
蒸馏一篇材料
转译一份分镜
生成一份口播稿
整理一次会议纪要
生成客户报告初稿
System-Building Cost / 系统建设成本
为设计、搭建或重构以下资产所消耗的资源：
Agent
Skill
Runtime
Protocol
Evaluation
Toolchain
Workflow
Model Index
Project Directory
Invocation Standard
示例：
为了蒸馏讨论稿而设计一个通用知识加工 Runtime
为了一次提纲评审而重构多 Agent invocation protocol
为了一个输出流程而建设完整生产线目录体系
Calibration Cost / 校准修复成本
为纠正模型偏差、记录人工反馈、对齐专家判断边界、构建标准评测集所消耗的资源。
示例：
分析 AI 与专家判断差异
收集专家修改痕迹
构建真题评测集
调整错误分类
建立返工率指标
Exploration Cost / 探索预演成本
为了验证新范式、新工具、新平台调用链路或新协作拓扑所消耗的实验性资源。
示例：
测试 Codex Thread 作为真实 Agent carrier
测试 Claude Code subagent
测试 SuperPowers 对流程复杂度的影响
测试 OpenClaw 自动化能力边界
2.2 核算铁律
绝对禁止将系统建设成本伪装为单次任务的内容产出成本。
如果一次任务中实际发生了：
设计新 Runtime
编写通用 Protocol
创建新 Agent / Skill
构建评测栈
设计目录结构
定义 invocation record
构建长期资产
这些消耗必须记入 System-Building Cost，而不是 Content Cost。
系统架构的重工业投入必须光明正大地记入基建账本，以接受长周期 ROI 审计。
2.3 漂移探测触发 / Scope Drift Detection
由于 LLM 内置的规划、反思和补完惯性，轻量级 P 域任务极易在无监督状态下向 I 域治理滑移。
系统必须在管线节点埋入漂移探针。一旦捕捉到以下信号，即刻判定发生任务蔓延。
信号一：基建过度行为
一个被定性为 One-off 的任务，开始出现：
创建通用 Protocol
设计未来复用目录树
撰写与当前产出无关的抽象规则
新增 Agent / Skill / Runtime
升级为长期工作台建设
信号二：并发无序扩张
Lite 档流程开始擅自：
派发多个 Worker
拉起多角色审查委员会
开启并行 coverage audit
创建多个 sub-session
进行未授权的动态 agent routing
信号三：产物交付延宕
用户期待的核心产物迟迟未出现，系统资源却被大量消耗于：
routing log
coverage audit
handoff packet
review report
repair protocol
directory scaffolding
meta-analysis
信号四：预算穿透
当前或预估消耗已超出原定预算阈值，且未主动申报分账。
默认触发条件：
Lite 超过 source_tokens × 30
Standard 超过 source_tokens × 100
任一任务专家注意力消耗超过预设 human_attention_budget
信号五：成功标准变更
任务从：
完成一个结果
变成：
定义一套以后如何持续完成结果的系统
这说明任务性质已经从 Content Output 滑入 System Building。
2.4 漂移处置协议 / Drift Resolution Protocol
一旦漂移探测器被触发，系统必须放弃顺其自然的工程惯性，执行强制介入。
Step 1：挂起进程
立即阻断当前 Agentic Runtime 的继续执行与自我繁衍。
状态切换为：
paused_by_scope_review
Step 2：核心发问
必须回答：
1. 我们现在还是在执行原始内容产出任务吗？
2. 如果不是，是否需要正式立项为系统建设任务？
3. 当前已消耗成本应记入哪一本账？
4. 是否需要调整 Lite / Standard / Full 档位？
5. 原始任务是否仍需先完成？
Step 3：物理分账
若确认任务变轨，必须将此前及后续超额消耗从 Content Cost 中切割，划入：
System-Building Cost
Calibration Cost
Exploration Cost
Step 4：人工授权重启
只有在完成以下动作后，系统方可解除挂起：
重新 QPI 定性
重新 Mode Selector
重新 Budget Contract
重新 Stop Rule
记录 human decision
3. 物理防伪与绝对制动
Execution Authenticity & Stop Rule
缺乏硬约束的 Agentic 环境中，系统极易陷入两种工程灾难：
流程幻觉：主节点伪造执行过程
过度执行：子节点无限繁衍中间产物
本章为自动化管线装配测谎探针与制动系统。
3.1 执行真实性 / Execution Authenticity
多智能体架构的真正价值，来源于不同思维模型在隔离沙箱中产生的真实逻辑张力，而不是单一模型在同一上下文里的文本模拟。
任何被声明为以下来源的正式产物：
独立 Agent
Reviewer
Worker
Auditor
Committee Member
External Participant
必须具备真实调用证据链。
3.2 真实调用证据链 / Invocation Record
最小 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: true / false
human_gate_id_if_applicable
3.3 主控越权阻断
主会话或 Orchestrator 仅被赋予：
调度
路由
聚合综合
状态记录
有限验证
人工确认转译
绝对禁止主会话凭借自身高上下文能力去代写或模拟子节点输出。
若无法拉起真实子线程、外部参与者或 carrier，进程必须进入：
blocked_waiting_for_participant_output
不得用伪造报告填补流程真空。
3.4 模拟标记与沙箱隔离 / Simulation Labeling
当系统因环境限制、调用失败、人类手动干预或流程占位，产生缺乏真实调用证据的产物时，必须实施资产隔离。
所有模拟产物必须包含：
simulation_only: true
formal_output: false
excluded_from_synthesis: true
simulation_reason:
allowed_use:
允许用途：
价值流预演
人工参考草稿
流程设计样例
绿野仙踪验证
禁止用途：
正式 synthesis
客户可见交付
下游自动化依据
模型沉淀依据
审计依据
3.5 最小充分阈值 / Minimum Sufficient Threshold
任何 Runtime 启动前，必须与人类专家确立验收合约。
必须定义：
minimum_viable_output
sufficient_criteria
optional_artifacts
forbidden_artifacts
human_gate_points
budget_limit
stop_condition
Minimum Viable Output
为了满足下游消费，当前任务必须交付的最核心、最少信息量。
示例：
只需视频总纲与分镜骨架，不需要详细配音稿
只需 topic map 与 reusable material units，不需要 full coverage audit
只需 outline review，不需要完整正文写作 Runtime
Sufficient Criteria
一旦达到该状态，即视为已达标。
达标后，Optional Artifacts 默认被剥夺生成权限，除非人类显式授权。
Human Gate Points
提前锚定机器绝对不能自决的单向门。
示例：
是否进入 Full 档
是否采纳红队意见
是否创建 writing project
是否进入 model mining
是否对客户可见
是否执行外部 API
3.6 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
禁止设置无合约的“人工确认”。
Human Gate 输出格式
每个决策记录至少包含：
decision_id:
gate_id:
decision_owner:
accepted_option:
rejected_options:
reason:
risk_notes:
downstream_effect:
rollback_condition:
timestamp:
3.7 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.8 Stop Rule / 绝对停止权
人类意志的最高体现不在于启动自动化，而在于何时决绝地踩下刹车。
Stop Rule 是系统免于冗余完美主义与中间物繁殖的最后防线。
触发条件
一旦出现以下情况，必须触发停止：
已达到 Minimum Sufficient Threshold
触及 Human Gate
预算接近 abort_threshold
发生 Scope Drift
真实 invocation 不可用
工具权限不足
数据安全边界不清
来源保真无法验证
制动执行
系统必须：
停止创建新任务
取消未启动的排队任务
对运行中任务发出 cooperative cancellation
保存当前状态、日志与未完成动作清单
阻断非必要产物继续生成
将状态切换为 blocked_waiting_for_human
对于无法响应 cooperative cancellation 的非关键线程，可执行强制终止。
终止前必须尽可能保存：
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 / 修改
允许在预设范围内修改正式产物。
必须限定：
allowed_paths
allowed_files
allowed_fields
modification_scope
rollback_path
A4 Decide / 裁决
拥有结构性决策权。
行使该权限时，必须同步输出：
decision record
decision rationale
risk notes
downstream effect
A5 Execute / 执行
A5 必须拆分为三个子级。
A5-R Read Tool
A5-W Write Tool
A5-X External Action
A5-R Read Tool
只读工具调用。
示例：
搜索
读取文件
查询数据库
查看日志
读取状态
A5-W Write Tool
写入动作。
示例：
写文件
改代码
更新配置
生成资产
修改目录
保存结果
必须满足：
允许路径
变更日志
diff
回滚策略
A5-X External Action
外部动作。
示例：
发送消息
发布内容
调用客户 API
支付
删除远程资源
修改客户可见状态
触发生产任务
默认禁止自动执行。 必须经过 Human Gate 或 Runtime 级明确授权。
A6 Block / 阻断
最高优先级熔断权限。
一旦触发，系统全线进程挂起，进入：
blocked_waiting_for_human
适用场景：
严重逻辑悖论
法理违规
数据泄漏风险
权限越界
预算穿透
来源不可验证
执行真实性缺失
高风险动作未授权
4.2 最小权限原则 / Least Privilege
Agent 的工具权限必须小于其语言能力。
能分析，不代表能执行。
能建议，不代表能写入。
能生成，不代表能发布。
能理解任务，不代表拥有全目录权限。
任何权限必须按任务最小授权。
禁止：
通用推理 Agent 获得无限工具权限
默认授予全仓库写入权限
默认授予外部 API 权限
默认授予发布权限
默认授予删除权限
4.3 副作用隔离 / Side-effect Isolation
具备写入、发布、删除、外部 API、客户可见输出能力的 Agent，必须满足：
沙箱目录或沙箱环境
明确 allowed_paths
明确 forbidden_paths
dry-run / preview 优先
执行前生成 action plan
执行后生成 action log
支持回滚或人工恢复
高风险动作必须二次确认
4.4 数据分级 / Data Classification
所有输入材料必须标记数据等级。
Public：公开材料
Internal：内部材料
Confidential：客户资料、商业方案、报价、合同、业务数据
Sensitive：个人信息、密钥、账号、财务、法律、医疗、未成年人、内部战略等高敏感数据
不同数据等级决定：
是否允许外发
是否允许进入外部模型
是否需要脱敏
是否允许保存日志
是否允许被用于校准
是否允许进入知识库
4.5 密钥纪律 / Secrets Discipline
任何 Agent、Skill、Runtime 不得：
将 API Key、Token、Cookie、账号密码写入 Prompt
将密钥保存到普通日志
将密钥复制进 Context Pack
将密钥暴露给不需要该权限的子 Agent
将包含密钥的返回结果进入长期知识库
密钥必须通过安全环境变量、密钥管理服务或平台授权通道传递。
4.6 数据外发红线
调用外部模型、外部 API、图片 / 语音 / 视频服务前，必须确认：
数据是否允许外发
是否包含客户资料
是否包含个人信息
是否需要脱敏
第三方是否保存日志
返回结果是否可以保存
是否允许进入训练或校准流程
若无法确认，默认禁止外发。
4.7 过程数据授权 / Process Data Sovereignty
专家修改痕迹、反馈、编辑轨迹、隐性遥测、光标行为、反驳意见，是高价值认知资产，也是高敏感数据。
采集这些数据必须具备：
明确授权
用途边界
最小采集
可撤回机制
隔离存储
保留期限
访问权限
删除机制
禁止以“系统学习”为名，默认吞并专家经验或客户场景数据。
4.8 平台与插件治理 / Platform & Plugin Governance
任何平台、插件、Skill Pack、自动化框架的默认行为，不得覆盖本手册。
当平台默认流程倾向于：
自动创建子线程
自动调用复杂 Skill
自动进入 TDD / Review / Audit
自动补全缺失产物
自动扩展目录结构
自动执行高权限工具
自动将失败流程补成完整故事
系统必须先进行 Mode Selector 与 Scope Review。
项目级白名单
每个项目必须声明：
allowed_skills
blocked_skills
manual_only_skills
allowed_tool_scopes
forbidden_tool_scopes
allowed_external_services
blocked_external_services
非代码任务默认禁用重型软件工程插件
对于以下任务：
知识蒸馏
写作
模型提炼
素材整理
方案分析
研究讨论
概念设计
默认禁止启用重型软件工程流程插件，除非用户明确将任务升级为系统建设或工具开发。
插件输出不得自动成为正式产物
插件生成的输出仍必须经过：
Artifact Contract
Execution Authenticity
Evaluation Stack
Human Gate
Source Fidelity
插件不是治理豁免权。
5. 运行修复与回滚
Retry, Repair & Rollback
Agentic 系统里的失败并不可怕。 真正危险的是无限重试、静默修补、越修越偏和不可回滚。
5.1 重试上限 / Retry Limits
任何自动重试必须有上限。
默认规则：
工具调用失败：最多重试 2 次
格式错误：最多自动修复 2 次
网络/API 临时失败：最多重试 2 次
权限失败：不得自动绕过
推理质量不达标：不得无限重写
外部 API 失败：不得通过更换高风险 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，而不是直接重写。
Repair Plan 必须说明：
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 权限动作必须支持回滚协议。
必须具备：
pre_change_snapshot
diff / action_log
rollback_path
rollback_owner
irreversibility_warning
不可回滚动作必须提前阻断，并要求 Human Gate。
示例：
发布客户可见内容
删除远程资源
发送正式邮件
触发生产 API
修改客户数据库
覆盖正式知识库资产
5.5 修复后的再验证
修复后必须重新通过相关评测层级。
示例：
格式修复后 -> 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
文件很多但不知道哪个是真的，是伪工程化的典型症状。
任何脱离草稿态进入正式资产池的产物，必须声明其生命周期与校验元数据。
正式产物头部必须包含：
artifact_type:
status:
authority:
source_of_truth:
downstream_use:
invalidation_condition:
cost_class:
created_by:
created_at:
last_updated:
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
customer_visible
runtime_executable
simulation_only
excluded_from_synthesis
invalidation_condition
必须说明何时失效。
示例：
上游源文件更新
canonical prompt 更新
用户推翻结构
规则变更
模型版本迁移
客户约束变更
Human Gate 未通过
6.2 运行时成熟度模型 / 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 / 治理态
具备抗审计、法理追责与灾难回滚能力。
适用于：
高风险场景
外部客户严苛交付
长期运行系统
客户可见自动化
不可逆工具执行
成熟度铁律
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 造成结构性失明。
适用边界：
源材料高度连贯
源材料可被高上下文模型完整处理
下游依赖整体结构
若源材料是 mixed source，应先做 macro-topic split。 若源材料是 fragmented source，应采用 flat discovery，不得强行制造层级。
Context Pack 类型
上下文编译器应根据下游目标输出：
source_digest
task_specific_context_pack
role_specific_dispatch_pack
decision_context
evaluation_context
source_index
risk_notes
上下文最小充分原则
上下文包必须足够支撑任务，但不得将所有材料倾倒给所有角色。
主控需要全局状态
执行节点需要任务相关材料
评审节点需要标准、目标与产物
人工决策门需要候选方案、风险与差异摘要
6.4 来源保真与证据索引
Source Fidelity & Evidence Index
任何涉及材料加工、报告生成、知识蒸馏、客户方案、分析结论的 Runtime，必须保留来源索引。
正式输出中的关键判断必须能回溯至：
原始来源
source range / paragraph / block id
参与该判断的 Agent / Worker
该判断是否来自原文、推理、归纳、用户裁决或模型补充
来源铁律
禁止将中间摘要当作新的 source of truth。
禁止把模型综合判断伪装成原始材料事实。
禁止在未标明推理性质的情况下输出确定性结论。
禁止在 source index 缺失时声明 lossless extraction。
判断类型标记
关键判断必须标明类型：
source_fact：原文事实
source_claim：原文主张
inference：模型推理
synthesis：综合归纳
human_decision：人工裁决
external_fact：外部事实
assumption：假设
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 是否可行
human gate 是否记录
liability boundary 是否清晰
data policy 是否合规
6.6 按场景选择评测层级
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 项目开工前，必须回答：
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。
后果：
难维护
难评测
难复用
难追踪
难迁移
2. 流程幻觉
文件齐全，但真实 Agent 没有被调用。
典型症状：
有 report
有 dispatch pack
有目录
有日志
但没有 Invocation Record
3. 治理过载
一次性任务启用 Full Runtime。
典型症状：
5 万字材料
3000 万 tokens
大量 topic docs
大量 audit
大量 handoff
核心产物 ROI 失真
4. 成本混账
把系统建设成本算成内容产出成本。
典型症状：
用户只要一个结果
系统却建设了一个机器
最后把机器成本记到结果上
5. 中间物繁殖
核心产物未交付，系统不断生成：
audit
routing log
handoff
repair note
review report
meta-analysis
6. 上下文倾倒
把所有原始材料一股脑塞给所有 Agent。
后果：
角色污染
判断失焦
token 浪费
source fidelity 降低
7. 权限裸奔
让能推理的 Agent 直接拥有：
写入权限
删除权限
发布权限
外部 API 权限
客户可见输出权限
8. 无评测上线
只凭“我觉得不错”进入生产。
红线：
无 Evaluation Stack，不得声明 Production。
9. 模拟污染
simulation-only 产物进入正式 synthesis。
这是多 Agent 系统的根级污染。
10. 黑盒校准
系统输出错了，但专家不知道如何低成本纠正。
症状：
没有 decision rationale
没有 error category
没有 feedback slot
没有 repair plan
11. 插件篡权
平台插件默认流程覆盖项目治理规则。
症状：
自动开子线程
自动进入重型审查
自动生成无关目录
自动补全失败产物
12. 停止权失效
系统已经达到最小充分产物，却继续生产“看似有用”的附加物。
红线：
系统不得因为还能生成，就继续生成。
8. 附录：标准元数据模板
Appendix: Standard Metadata Templates
8.1 Invocation Record Template
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
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
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
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
runtime_id:
previous_state:
new_state:
trigger:
responsible_actor:
timestamp:
next_allowed_actions:
blocked_reason:
related_artifacts:
notes:
8.6 Cost Ledger Entry Template
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
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 多干点”。
它是把人类专家的判断、责任、隐性经验、材料处理、流程边界和工具权限，装入一台会高速运转的认知反应堆。
因此，本手册的目的不是鼓励自动化，而是给自动化装上：
入口闸门
成本账本
权限阀门
防伪探针
状态仪表
数据隔离
评测探针
回滚绳索
绝对刹车
系统越聪明，越要守规矩。 流程越丝滑，越要看后端废热。 Agent 越能干，越不能让它裸奔。
HiFi Agentic 工程的底线不是“自动完成”，而是：高保真、可校准、可追踪、可停止、可追责。