205 lines
18 KiB
Markdown
205 lines
18 KiB
Markdown
# Agentic Engineering Handbook (V1.0)
|
||
|
||
*HiFi Agent Studio 运行治理与现场规程*
|
||
|
||
## Profile
|
||
|
||
**author**: Wantsong
|
||
**version**: V1.0
|
||
**date**: 2026-06-12 23:40:00
|
||
|
||
---
|
||
|
||
## 0. 守则定位与绝对边界
|
||
|
||
本手册是团队在 Agentic 工程实战中的硬性操作底线。它将高维的架构沙盘转化为冷酷的工程界桩，聚焦于解决“如何开工、如何限流、如何调用、如何熔断”。
|
||
|
||
* **守则效力**：本手册服从并承载 HiFi Agent Studio 的核心纲领，同时作为一切局部项目的行动准则。当规则发生冲突时，执行的优先级为：
|
||
1. 客户法理与商业硬性约束
|
||
2. HiFi Agent Studio 宪法原则
|
||
3. **本 Agentic Handbook**
|
||
4. CCPE System 资产建造规范
|
||
5. 具体项目 Runbook
|
||
|
||
* **反向兜底**：任何自动化框架（如 Codex、Claude Code、OpenClaw 等）的底层默认行为（例如：遇错无限重试、自动化子线程繁衍），若与本守则中的“执行真实性”或“绝对停止权”发生物理碰撞，必须立即挂起进程并向上请求架构裁决。严禁为了适配或迎合底层工具的便利性，而让步甚至阉割治理底线。
|
||
|
||
---
|
||
|
||
## 1. 任务入口与档位挂载 (Project Intake & Mode Selector)
|
||
|
||
在 Agentic 时代的极压舱内，算力的失控与治理的灾难皆始于入口处的定性溃败。在敲下第一行 Prompt 或拉起任何一个 Thread 之前，必须在操作面板上完成极其冷酷的强制分诊。
|
||
|
||
### 1.1 QPI 强制分诊
|
||
|
||
所有接管需求必须在第一时间进行问题颗粒度的物理探测，禁止含糊其辞的“先跑起来看看”：
|
||
|
||
* **【Q】查询 (Question)**：面对纯粹的信息缺失，实施单节点调用搜索或检索增强（RAG）。**绝对禁止**为其编排复杂的多体流程。
|
||
* **【P】求解 (Problem)**：目标明确的转换与生产（如：长文转分镜、批量素材蒸馏）。架构的复杂性必须全部倾注于生产线的**吞吐量极限**，采用“模板化约束 + 批量执行 + 人工抽检”的生产工坊模式。
|
||
* **【I】治理 (Issue)**：无唯一解的非遍历性深水区（如：核心立意判定、战略级评审）。架构的复杂性必须全部倾注于**保真度极限**，设置高密度的人类决策门（Human-in-the-loop）与权限阻断，绝不允许用并发掩盖判断逻辑的脆弱。
|
||
|
||
### 1.2 性质定性
|
||
|
||
明确当前动作的终极标的，防范动作与目的发生致命剥离：
|
||
|
||
* **一次性内容产出**：系统运作仅为获取当下的单一结果材料。
|
||
* **可复用能力沉淀**：系统运作为了提炼能跨越项目周期的资产（Skill、Model Card 等）。
|
||
* **治理级系统建设**：系统运作为了构建一套可长久运转、能抗击审计的协议架构（Runtime）。
|
||
* *铁律*：如果你只需提炼一篇 5 万字的文稿，就绝不能在执行中私自搭建一套“知识加工园区”。
|
||
|
||
### 1.3 档位挂载 (Mode Selector)
|
||
|
||
**默认轻量，证据驱动升级。** 系统的物理操作杆在启动时，必须且只能挂死在 Lite 档。严禁凭借工程师的架构审美或算法崇拜擅自升档。
|
||
|
||
* **Lite 档（默认启动）**
|
||
* **适用边界**：一次性任务、低法理风险、源材料体量能够被单个高上下文模型完整吞吐。
|
||
* **控制策略**：单模型极简闭环。剥离一切不需要的厚重交接包，不需要唤醒真实的多 Agent 独立进行沙箱判断。
|
||
* **核心产物**：目标输出文件、极简的输入记录、关键人工确认点。
|
||
|
||
* **Standard 档（证据驱动升级）**
|
||
* **升级证据**：面对多源异构材料交叉、存在明确的下游自动化消费依赖（Routing），或用户明确下达了构建可复用 Workflow 的指令。
|
||
* **控制策略**：引入结构化的上下文编译（Context Compiler）限制幻觉，建立稳固的流转协议与工作台基座。
|
||
* **核心产物**：源映射包（Source Pack）、可复用的资产单元、局部的追踪审计日志与决策记录。
|
||
|
||
* **Full 档（极限治理）**
|
||
* **升级证据**：应对试错即死亡的单向门商业决策、高法理追责风险，或需要多角色形成独立的张力对撞。
|
||
* **控制策略**：拉起全规格的重工业级多智能体编排。强制挂载严格的权力矩阵（Authority Matrix），执行无死角的覆盖率审查。
|
||
* **核心产物**：完整的 Runtime 机器状态、不可篡改的底层真实调用证据（Invocation Records）、失真风险日志以及具备极高防御性的下游交接包。
|
||
|
||
## 2. 资产隔离与防蔓延机制 (Cost Ledger & Scope Drift)
|
||
|
||
在 Agentic 自动化管线中，最致命的失控往往不是报错崩溃，而是系统在暗中无休止地运转，将一次简单的内容提取异化为庞大的系统基建。为了夺回对计算资源和专家注意力的绝对控制权，必须在系统底盘焊死成本核算与边界探测组件。
|
||
|
||
### 2.1 四重消耗账本 (Cost Ledger)
|
||
|
||
破除算力消耗的混沌状态，建立极其冷酷的资源归因机制。任何 Agentic 工作流在启动时，其消耗的 Token、算时与存储，必须被强制记入以下四个物理隔离的账本之一：
|
||
|
||
* **Content Cost (内容产出成本)**：为完成当前用户指派的直接任务（如：蒸馏一篇材料、转译一份分镜）所消耗的核心资源。
|
||
* **System-Building Cost (系统建设成本)**：为设计、搭建或重构 Agent、Skill、Runtime、Protocol、Evaluation 标准及工具链所消耗的资源。
|
||
* **Calibration Cost (校准修复成本)**：为纠正模型偏差、记录人工反馈、对齐专家判断边界以及构建标准评测集所支出的资源。
|
||
* **Exploration Cost (探索预演成本)**：为了验证新范式、测试新调用链路边界（如：绿野仙踪协议跑通前）所消耗的实验性资源。
|
||
|
||
**核算铁律**：绝对禁止将构建自动化流程的“系统建设成本”伪装或打包为单次任务的“内容产出成本”。系统架构的重工业投入必须光明正大地记入基建账本，以接受长周期的 ROI（投资回报率）审计。
|
||
|
||
### 2.2 漂移探测触发 (Scope Drift Detection)
|
||
|
||
由于 LLM 内置的“规划与反思”本能，一个轻量级的 P 域（难题）任务极易在无监督状态下向 I 域（治理）滑移。系统必须在管线节点埋入探测探针，一旦捕捉到以下越界信号，即刻判定发生任务蔓延（Scope Drift）：
|
||
|
||
* **基建过度行为**：一个被定性为一次性（One-off）的任务，其底层 Agent 开始私自创建通用的 Protocol、设计复杂的未来复用目录树，或撰写与当前产出无关的抽象规则。
|
||
* **并发无序扩张**：原定在 Lite 档运行的流程，开始擅自派发多个 Worker 子线程，甚至拉起多角色的审查委员会（Committee）。
|
||
* **产物交付延宕**：用户期待的原始核心产物迟迟未出现，系统资源却被大量消耗于生成路由日志（Routing log）、覆盖率审计等中间态文档。
|
||
* **预算穿透警告**：系统当前或预估消耗的 Token 数量，已超出原定单次内容任务规模预算的合理阈值，且未进行主动的账本拆分申报。
|
||
|
||
### 2.3 漂移处置协议 (Drift Resolution Protocol)
|
||
|
||
一旦漂移探测器被触发，系统必须立刻放弃“顺其自然”的工程惯性，执行以下强制介入动作：
|
||
|
||
* **强制挂起进程**：立即阻断当前 Agentic Runtime 的继续执行与自我繁衍，将进程置于阻塞状态，等待人工架构视角的介入。
|
||
* **核心发问与重定性**：
|
||
1. *我们现在还是在执行原始的内容产出任务吗？*
|
||
2. *如果不是，是否需要将当前操作正式立项为“系统建设任务”？*
|
||
* **物理分账与重启**：若确认任务已发生性质变轨，必须重新进行 QPI 定性，调整 Lite/Standard/Full 运行档位，并将此前及后续的超额消耗从 Content Cost 账本中物理切割，划拨至 System-Building Cost 账本。只有在账本边界清晰重启后，系统方可解除挂起状态。
|
||
|
||
|
||
## 3. 物理防伪与绝对制动 (Execution Authenticity & Stop Rule)
|
||
|
||
在缺乏硬性约束的 Agentic 环境中，系统极易陷入两种致命的工程灾难：一是主节点伪造执行过程的“流程幻觉”，二是子节点为了证明自身工作量而无限繁衍的“过度执行”。本章确立的机制，旨在为自动化管线装配不可篡改的测谎探针与绝对的物理断电开关。
|
||
|
||
### 3.1 执行真实性与主控阻断 (Execution Authenticity)
|
||
|
||
多智能体架构的真正防御力，来源于不同思维模型在隔离沙箱中产生的真实逻辑张力，而非单一模型在同一个上下文里的文本模拟。系统必须对所有正式产物执行“代码级测谎”。
|
||
|
||
* **真实调用证据链**：任何被声明为由独立 Agent、审核员 (Reviewer) 或工作节点 (Worker) 产出的正式报告，必须向控制台出具完整的物理执行证据。最小证据链必须包含：
|
||
* 角色专属的 `Canonical Prompt` 或 Agent Spec 物理路径。
|
||
* 承载本次执行的独立沙箱标识（如 `Thread ID`、Carrier 或 Sub-session ID）。
|
||
* 投递的原始上下文包 (`Input Context`)。
|
||
* 未经主节点二次加工的原始返回文本 (`Returned Output`)。
|
||
|
||
* **主控越权阻断**：主会话 (Main Session) 或编排器 (Orchestrator) 仅被赋予调度、路由、聚合综合 (Synthesis) 与有界验证的权限。**绝对禁止**主会话凭借自身高上下文能力去“代写”或模拟任何子节点的输出。若无法拉起真实子线程，进程必须挂起，不得用伪造的报告填补流程真空。
|
||
|
||
### 3.2 模拟标记与沙箱隔离 (Simulation Labeling)
|
||
|
||
当系统因环境限制、调用失败或人类手动干预，产生了一批缺乏底层真实物理咬合的“伪执行”产物时，必须实施冷酷的资产隔离，防止“劣币驱逐良币”。
|
||
|
||
* **耻辱烙印机制**：对于任何由主会话模拟、丢失底层调用记录或仅为流程占位的临时产物，系统必须强制在其元数据 (Metadata) 中注入以下标签：
|
||
* `simulation_only: true`
|
||
* `formal_output: false`
|
||
* `excluded_from_synthesis: true`
|
||
|
||
* **隔离与熔断**：带有模拟标记的文件将被视作带毒资产，在物理上被阻断进入正式的综合裁决 (Synthesis) 与下游交接 (Handoff) 链条。它们仅被允许作为人类专家的参考草稿，彻底剥夺其污染最终决策的合法性。
|
||
|
||
### 3.3 降熵阈值与前置设定 (Minimum Sufficient Threshold)
|
||
|
||
为了防止系统在后台像细胞增殖般无限制造中间物，任何一个 Runtime 在启动挂挡前，必须与人类专家确立一份不可逾越的“验收合约”。
|
||
|
||
* **最小可用产物 (Minimum Viable Product)**：明确定义为了满足下游消费，当前任务必须交付的最核心、最少的信息量是什么（例如：仅需总纲与分镜骨架，不需要详细配音稿）。
|
||
* **充分条件 (Sufficient Criteria)**：确立何种状态即被视为“已达标”。一旦达标，那些用于锦上添花的可选产物 (Optional Artifacts) 将默认被剥夺生成权限。
|
||
* **人工等待点设计 (Human Gate)**：提前锚定哪些节点是机器绝对无法自决的单向门，系统在抵达该阈值时必须交出控制权。
|
||
|
||
### 3.4 绝对停止权与熔断机制 (Stop Rule)
|
||
|
||
在 Agentic 时代的极压舱内，人类意志的最高体现不在于启动自动化，而在于何时决绝地踩下刹车。停止权是系统免于因追求冗余完美而耗尽资源的最后防线。
|
||
|
||
* **触发熔断**：一旦核心传感器探测到产出物已触及前置设定的“降熵阈值”，或触及人工确认门 (Human Gate)，亦或是当前消耗已逼近该档位设定的算力/预算上限。
|
||
* **绝对制动执行**：系统将无视底层 Worker 是否仍在排队生成附加参考、覆盖率报告或第五轮压力测试。停止规则将直接下达代码级的物理断电指令，强制销毁多余线程，截断一切非必要的自我繁衍行为，将系统状态强制锁定为 `blocked_waiting_for_human`，把最终裁决权安全地交还至人类桌面。
|
||
|
||
## 4. 高阶扩展与资产池 (Expansion Materials)
|
||
|
||
当系统从 Lite 档的单兵作战升级为 Standard 甚至 Full 档的复杂治理域时，依靠硬编码的临时约束将无法阻挡系统的混乱熵增。本章定义了 Agentic 时代所需的重工业扩展组件与资产标准，它们是支撑多角色协同、确保物料跨周期复用并抵抗架构腐化的底层脚手架。
|
||
|
||
### 4.1 权力矩阵 (Authority Matrix)
|
||
|
||
在多智能体生态中，最致命的隐患是“越权操作”。为了防止底层子节点擅自修改核心产物或盲目调用高危工具，系统必须为每一个 Agent、Skill 或 Runtime Node 焊死其物理权限等级。
|
||
|
||
* **A0 Observe (观察)**：仅拥有读取权限，可生成内部标记与标注，绝对无权修改任何下游可见状态。
|
||
* **A1 Suggest (建议)**：允许输出分析与优化方案，但其产物被物理隔离，不能直接覆写正式产物，仅供高阶节点参考。
|
||
* **A2 Draft (起草)**：被授权生成初稿物料，但该物料在状态机中被强制拦截，必须经由 Human Gate（人工确认门）或 Owner Agent 签发后方可流转。
|
||
* **A3 Modify (修改)**：在预设的上下文边界与特定的文件范围内，被授权对正式产物进行覆写与调优。
|
||
* **A4 Decide (裁决)**：拥有结构性决策权（如：选定破题方向、确认总纲）。行使该权力时，系统强制要求其同步输出包含逻辑归因的 `decision record`（决策记录）。
|
||
* **A5 Execute (执行)**：被授权打破沙箱，执行真实的物理动作，包括工具调用 (Tool Call)、写文件、改代码或触发外部 API。
|
||
* **A6 Block (阻断)**：最高优先级的熔断权限。一旦触发（如：探针发现严重逻辑悖论或法理违规），系统全线进程立刻挂起，强制召唤人类专家介入。
|
||
|
||
### 4.2 产物合约 (Artifact Contract)
|
||
|
||
“文件很多，但不知道哪个是真的”是伪工程化的典型症状。为了确保物料的可追溯与可复用，任何脱离草稿态进入正式资产池的产物，必须显式声明其生命周期与校验元数据。
|
||
|
||
每一份正式产物必须在头部绑定合约说明：
|
||
|
||
* **`artifact_type` (物料类型)**：精确归属为 Prompt、Agent Spec、Skill、Runtime、Model Card 或 Final Output。
|
||
* **`status` (生命周期状态)**：当前处于 Draft（草稿）、Candidate（候选）、Active（激活生效）、Deprecated（不推荐/降级）或 Archived（归档）的哪一阶段。
|
||
* **`authority` (效力声明)**：明确其用途是作为局部建议、正式依据、内部基座，还是可直接对客可见 (Customer-Visible)。
|
||
* **`downstream_use` (下游约束)**：指明该产物合法消费的下游节点是谁，应用于什么阶段。
|
||
* **`invalidation_condition` (失效条件)**：定义在何种物理或业务条件下（如：上游源文件更新、特定规则变动），该产物判定为失效且需要触发重跑。
|
||
|
||
### 4.3 运行时成熟度模型 (Runtime Maturity Model)
|
||
|
||
为了防止团队在“概念沙盘”与“生产交付”之间产生致命的预期错位，杜绝“跳级声明成熟”的技术浮夸，必须用成熟度模型严密丈量每一个 Agentic 项目的演进坐标。
|
||
|
||
* **M0 Concept (概念态)**：仅存在思想模型或业务论证，尚未进行任何自动化流程拆解。
|
||
* **M1 Manual (手工态)**：专家人工跑通闭环（符合 Wizard of Oz 绿野仙踪协议），验证了智能流的核心业务价值。
|
||
* **M2 Assisted (辅助态)**：AI 介入生成草稿或检查项，但核心推进与流程驱动完全依赖人类手动操作。
|
||
* **M3 Protocolized (协议态)**：输入、输出、角色边界、状态机流转、Human Gate 与 Stop Rule 已在文档层面彻底显性化。
|
||
* **M4 Semi-Agentic (半 Agentic 态)**：部分 Agent、Skill 或 Tool 已实现真实的自动化调用，且具备完整的 Invocation Record 物理日志。
|
||
* **M5 Production (生产态)**：具备可重复运行的管线。拥有自动化评测、执行监控、异常捕获与权限管控，达到内部工程可用标准。
|
||
* **M6 Governed (治理态)**：具备抗击审计、法理追责与灾难回滚能力，完全适配高风险场景或外部客户的严苛交付。
|
||
|
||
### 4.4 上下文编译 (Context Compiler)
|
||
|
||
绝对禁止将漫长、原始的语料一股脑地倾倒进大模型的上下文窗口。在任何 I 域（治理）或高价值的 P 域（求解）任务前，必须将“上下文工程”剥离为一项独立的物理预处理动作。
|
||
|
||
* **全源完形前置 (Whole-source Gestalt)**：面对高连贯性文本，在启动分块前，必须强制实施全局扫描，锁定核心张力与目录骨架，防止 Chunk-first 造成的结构性失明。
|
||
* **精准转译打包**：上下文编译器必须基于原始物料与下游目标，结构化输出针对不同节点的补给包：包含供全局统筹的 `source digest`（原源摘要）、供单一角色执行的 `role-specific dispatch pack`（角色分发包）、以及供人工复核的 `decision context`（决策上下文）。
|
||
|
||
### 4.5 分层评测栈 (Evaluation Stack)
|
||
|
||
依靠单一的“准确率”或“相似度”无法测度专家级 Agentic 系统的真实抗压能力。系统必须部署从底层机械属性到顶层战略效用的多维探针。
|
||
|
||
* **E0 Smoke Test (冒烟测试)**：检验系统能否走通骨架。文件是否生成，Tool Call 是否响应。
|
||
* **E1 Format Test (格式测试)**：检验输出物料是否严格遵守 Schema 结构、长度预算与语言规范。
|
||
* **E2 Factual Test (事实测试)**：核查文本溯源保真度。检验是否编造事实（幻觉）、是否遗漏关键材料。
|
||
* **E3 Reasoning Test (推理测试)**：针对逻辑链的完备性与假设推演的健壮性进行刺探，检验反例与边缘条件的处理。
|
||
* **E4 Expert Similarity (专家相似度)**：测度结论与人类专家直觉的重合度，以及偏差部分的逻辑可解释性。
|
||
* **E5 Decision Utility (决策效用)**：终极业务指标。验证系统的介入是否真实帮助人类专家完成了更优、更快、更低耗能的决策。
|
||
* **E6 Calibration Test (校准测试)**：评测系统的纠错摩擦力。检验当系统犯错时，专家是否能低成本地指出错误，系统能否即时闭环修复。
|
||
* **E7 Governance Test (治理测试)**：审计视角的终极测试。核查系统的 trace 追踪完整度、权限隔离 (Authority) 强度、回滚机制与责任边界清晰度。
|
||
|