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