knowledge-vault/rules/Templates/Agentic-Engineering-Handbook1.2.md

# 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)。**