# sofagent Architecture
> v1.7.0 · 2026-10-22（GMT+8）· ✅ 已发版 · 孔放勋
>
> 设计决策记录——从为什么存在、约束层五种能力如何协作，到每个关键决策的工程理由。
>
## 目录
> **阅读地图**：本档分两层——**导读层**（心智模型 / 术语对照 / 能力与状态总览，无章号，速查用、可跳读）+ **编号正文**（§一–§八，**章号即阅读顺序**；三域归属以各章行内标注为准，域序非严格连续——约束层五种能力设计归治理域（§二），判定域落点为 §三 的判定化边界小节，口径见术语对照「工程层 / 判定层 / 治理层」行）。五域→三域映射与口径声明见 [v1.5.3 · 五](./changelog/v1.5/v1.5.3.md)。
**导读层**（先读，无章号）
- [心智模型（先读这个）](#心智模型先读这个)
- [术语对照](#术语对照)
- [能力与状态总览](#能力与状态总览)
- [一、激活链架构（v1.2.5+ Phase 1-4 已交付）](#一激活链架构v125-phase-1-4-已交付)（域一 · FDE 场景层）
- [二、约束层（Harness）设计——一个层，五种能力](#二约束层harness设计一个层五种能力)（域三 · harness 治理层）
- [三、架构设计决策的行业锚点](#三架构设计决策的行业锚点)（域二 · S1M 判定层）
- [四、核心理念与全局设计](#四核心理念与全局设计)（域三 · harness 治理层）
- [五、部署与运行架构](#五部署与运行架构)（域三 · harness 治理层）
- [六、核心设计决策](#六核心设计决策)（域三 · harness 治理层）
- [七、已知局限与未来方向](#七已知局限与未来方向)（域三 · harness 治理层）
- [八、数据层路线建议](#八数据层路线建议)（域三 · harness 治理层）
> 域归属说明：章号即阅读顺序（§一–§八正序）；三域归属以行内标注（域一 · FDE 场景层 / 域二 · S1M 判定层 / 域三 · harness 治理层），三域口径见 [心智模型 · 三域视角](#双层架构约束层与生命周期主框架)。
## 心智模型（先读这个）
> **sofagent 是一个开源 FDE Harness 层**（MIT）——不造 Agent，嵌在成熟 Agent（DSH / OpenClaw / WorkBuddy）与模型层之间做治理：进场把业务判断写成文件（梳理工作流、构建本体图谱、部署 AI 节点），离场后按文件 7×24 执行与审计。架构 = **约束层（一个层五种能力：注入·审计·回溯·沉淀·进化）× 生命周期（诊断 → 激活 → 编排 → 执行 → 进化）**双层。
>**FORGE = 项目内部自迭代工具链（LOOP 流水线），非产品能力**——保证每次变更可审计、可回滚、可进化（本文档后续 FORGE 均指此；术语表见 [WIKI](./WIKI.md)）。
```mermaid
graph TD
A[成熟 Agent 宿主 + 大模型
DSH · OpenClaw · WorkBuddy
90% 智力 · 你自选 · 我们不替代] --> B[约束层
一个层五种能力
约束层 × 生命周期]
B --> C[FDE Harness 层
嵌在 Agent 与模型之间
帮你梳理→部署→离场→AI 节点自己跑]
C --> D[SMB · OPC 的每个人
成为自己业务的 FDE]
```
### 双层架构：约束层与生命周期（主框架）
**三域视角**（产品身份口径，v1.5.3；交付状态：场景域 ✅ 已交付 · 治理域 ✅ 已交付 · 判定域 🚧 施工中——阶段一 v1.6.0 已交付：判据 schema + 36 条判据 + 数据地基）：导读层「双层架构」是**治理域（harness 治理层，已交付）**的架构展开；场景域首句=「**万物皆可 FDEing 的场景框架**」（工程层 FDEing 进场把判断写成文件——业务图谱/本体数据/激活链，详见 [§一 激活链](#一激活链架构v125-phase-1-4-已交付)）；
判定域（S1M 判定层，判据/留痕/举证——28 条规则 × 判定层接管见 [§三 审计规则面的判定化边界](#审计规则面的判定化边界28-条规则--判定层接管)；判定层四阶段施工（阶段一 v1.6.0 交付：判据 schema / 三元组 / 采集与质量门 / 判定头契约 / 零样本基线；余 v1.7.0 校准 → v1.8.0 接线 → v1.9.0 收口；入口排 v1.8.0）。）
三因子↔本架构对位（工程/判定/治理 ↔ 场景/判定/治理域）与五域→三域映射表：[v1.5.3 · 五](./changelog/v1.5/v1.5.3.md)（本档只留指针；架构术语 SSOT 仍是本档 + PHILOSOPHY，见 [WIKI 术语声明](./WIKI.md)）。
**这是理解 sofagent 最关键的一张图**——之前只有「约束层五种能力」（**能力视角**：怎么保证做对）。激活链（四阶段 ACTIVATE→ORCHESTRATE→EXECUTE→SUSTAIN）引入后，产品在「治理」之外多了一条**流程视角**（企业 AI 从诊断到自动运行怎么走）：
| 层 | 是什么 | 视角 | 回答什么问题 |
|---|---|---|---|
| **层 1 · 约束层** | 一个层五种能力（注入·审计·回溯·沉淀·进化） | 能力视角 | 「怎么保证每次执行都做对」 |
| **层 2 · 生命周期** | 诊断 → 激活 → 编排 → 执行 → 进化 | 流程视角 | 「企业 AI 从诊断到自运转怎么走」 |
```mermaid
graph LR
subgraph 层2 · 生命周期（流程视角 · v1.2.5+）
D1[诊断
FDE 四阶段] --> D2[激活 ACTIVATE
交付物→SubAgent]
D2 --> D3[编排 ORCHESTRATE
多 Agent→StateGraph]
D3 --> D4[执行 EXECUTE
DAG + HITL + 审计]
D4 --> D5[进化 SUSTAIN
反思 + 回灌]
D5 -.->|喂下一轮诊断| D1
end
subgraph 层1 · 约束层（能力视角 · 已交付 · 闭环见 §四）
C0[📥 注入
约束注入链·开工前]
C1[🔍 审计
每次变更硬证据]
C2[🔄 回溯
快照·回滚]
C4[📚 沉淀
蒸馏·知识资产]
C3[🧬 进化
反思·知识·优化]
end
D4 -.->|每步审计| C1
C1 -.->|违规拦截·回滚| C2
C2 -.->|回滚后重试| D4
C2 -.->|重试上限| TERM[🛑 终止 + 审计留痕]
D5 -.->|think.md 回写| C3
```
> **约束层为生命周期提供能力，生命周期让约束层有活干**——审计在 EXECUTE 阶段每步把关，进化在 SUSTAIN 阶段吃 think.md 回写。两个模型不是并列关系，是**能力 × 流程的矩阵**：约束层是「怎么保证做对」，生命周期是「让什么跑起来」。**本图只画两层关系**——层 1 内部五能力的闭环拓扑与各自失败出口见 [§四 治理架构](#治理架构约束层五种能力)。
### 补充视角：约束层内部分层与业务概念嵌套
> 以下两个视角是对双层架构内部结构的补充展开，不是独立的架构框架——**双层架构是唯一主框架**。**何时需要哪张图**：产品定位 → 双层架构图；约束层内部组织 → 约束层工程视角；企业业务概念 → 业务概念视角；落地终态 → 四层运行形态图。（生命周期五段 vs 激活链四阶段的对位见下方[相位模型对位表](#相位模型对位表同一套流程的四种切法)。）
**约束层工程视角**——约束层内部按「环境 → 流程 → 反馈」组织：约束层（工作环境：注入链/审计/daemon/data/ToolGate——决定「能做什么」）→ Graph（流程拓扑：编排模块 + LangGraph——决定「下一步去哪」）→ Loop（反馈改进：fresh-eyes/release-gate + sustain——决定「怎么越做越好」），审计趋势回流约束层。
**完整 ASCII 架构图与记忆法见 [WIKI §四·三层嵌套](./WIKI.md#三层嵌套harness--graph--loop)（唯一源 / SSOT）**——本节只做补充说明，不重复维护；修改三层结构请改 WIKI 那份。
**业务概念视角**——从企业用户角度看，同一套系统体现为四个自外向内的嵌套层级：**本体图谱（Ontology Graph）**＝企业全部业务节点与关联的全局拓扑（FDE 第三章，机器读）→ **业务图谱（Workflow Graph）**＝企业全部工作流组成的流程图谱（FDE 第四章，人读）→ **Loop**＝工作流中由 Goal 驱动的闭环执行单元 → Goal＝Loop 的退出条件（exit-gate 判定）。
**工作流（Workflow）由业务节点组成**——业务节点 = AI 节点 + Human 节点（对应 FDE 第四章 三问判定法：从业务节点中识别哪些可 AI 化 → 🔄/⚡ 成为 AI 节点，👤 保持 Human 节点）：
- 🔄 **纯 Loop（AI 节点·自动执行）** — AI 跑完即退出，Goal 达成自动收工
- ⚡ **Loop + Human（AI 节点·强化岗位）** — AI 跑 Loop，Human 在关键环节介入（审批 / 检查 / 兜底）
- 👤 **纯 Human（Human 节点·暂不动）** — 当前不适合上 AI，保持人工
> **Human-in-the-loop 不是「loop 里面塞了人」，而是 workflow 里 loop 节点和 human 节点的协同编排。** 一个 workflow = 一条由不同类型节点串联而成的路径。
举例：采购审批流 = `[🔄 收集报价] → [⚡ 主管审批] → [🔄 生成合同] → [Human 签字]`
### 四层运行形态：企业 AI 从梳理到专属模型
上文双层架构图同时承载「能力视角」（约束层五种能力）与「流程视角」（生命周期五段 ＝ 诊断 + 激活链四阶段 ACTIVATE→ORCHESTRATE→EXECUTE→SUSTAIN，对位见 [相位模型对位表](#相位模型对位表同一套流程的四种切法)）。这张图是**第三个视角——站在企业/客户看完整运行形态**，回答「装上 sofagent 之后，企业 AI 最终长成什么样」：
```mermaid
graph TB
subgraph L1["① 梳理与转换 · ACTIVATE"]
G["Workflow Graph
（多个 workflow 组成的流程图谱）"]
O["Ontology Graph
（ontology 的可理解形态：entity/concept/relations）"]
G -.双图谱并行产出.-> O
end
subgraph L2["② 编排与执行 · ORCHESTRATE"]
C["编译器：Workflow Graph + Ontology Graph
→ 受约束图（AI 可运行节点）"]
C --> ORCH["编排层：LangGraph StateGraph
（确定性 · 长期不动）"]
ORCH --> BE["执行层：ExecutionBackend 接口
DSH 默认 / createReactAgent fallback / 三平台可选"]
end
subgraph L3["③ 插件服务 · EXECUTE"]
P["sofagent plugin
审计 · 验收 · 审批 · 门禁
挂事件域，全域生效"]
end
subgraph L4["④ 底层模型 · SUSTAIN × 商业模型层"]
M["不同 workflow 节点
→ 调用企业专属后训练模型（商业模型层）"]
end
O --> C
BE --> P --> M
M -.治理产生 Trajectory → 训练信号 → 新模型回到治理下灰度.-> L2
```
> 这张图的三处关键精化：
> - **L1 是「双图谱并行产出」不是单向转换**——Workflow Graph 管流转（**人读它理解企业怎么运转**）、Ontology Graph 管语义（**AI 读它理解企业是什么**），两者从同一次 FDE 访谈并行产出、互相校验（SHACL），不是「Workflow Graph 画完再转 Ontology Graph」（转换会丢访谈里的隐性知识）。
>**双图谱术语**：Workflow Graph（人读的运转图）/ Ontology Graph（AI 读的语义图）的完整定义（含「ontology 是哲学定义，加 Graph 才可被理解」的解释）见 [§六 · 四层运行形态的三条决策](#四层运行形态的三条决策)。
>**行业坐标**：Workflow Graph / Ontology Graph / 知识图谱 / 上下文图谱同属「知识层」（描述业务世界），图谱工程（构建·校验·维护图谱的工程实践）属「工程层」——sofagent 的双图谱交付 = 用工程层方法产出知识层资产，行业对标详见 [VALIDATION](./VALIDATION.md)。
> - **L2 是「编排层长期不动 + 执行层可换」两层分离**——编排层 LangGraph StateGraph 长期不换（确定性审计依赖显式图结构；换掉编排层 = 放弃确定性审计，这是架构级取舍而非永久承诺），执行层走 ExecutionBackend 接口：DSH 默认 / createReactAgent fallback / 三平台可选。DSH 是最大的一条河，但「堤修在哪条河上都行」，不把企业命脉押在 developer preview 上。
> - **L3 挂的是「事件域」不是节点**——plugin 装一次即在 tools/result、turn-stopping、approval seam 上全域生效，无需逐节点插桩；独立模式（OpenClaw/WorkBuddy + git diff 审计）永远保留，不依赖 DSH 才成立。
## 术语对照
| 能力 | 英文 | 一句话 |
|---|---|---|
| 📥 注入 | Constraint Injection | 四层约束注入链，Agent 启动前灌入红线 |
| 🔍 审计 | Audit | git diff + 文件变更硬证据审计（v1.1.0 拆独立包） |
| 🔄 回溯 | Restore | 每次审计自动快照，`--revert` 一键回滚 |
| 📚 沉淀 | Distill | 审计轨迹/反思/案例蒸馏成知识资产——进化吃沉淀的产出。沉淀的复利载体是语义（字段含义/口径/边界）不是做题结果；且必须带适用边界，否则旧知识反成污染源 |
| ⚙️ FORGE 工具链 | FORGE Toolchain | LOOP 流水线（内部自迭代用，非对外能力） |
| 🧬 进化 | Evolution | FDE 周度巡检 + 准入门三档分流下的自动进化（deterministic 全自动 / model-judge 采样人审 / human-only 强制 HITL，未登记 fail-closed） |
| 加载链 | Load Chain | Agent 启动时注入的约束文件（又称约束注入链） |
| FDE | Forward Deployed Engineer（前线部署工程师） | 源自 Palantir 交付纪律：工程师驻场客户，掌握完整上下文、打破岗位边界、对结果负责。sofagent 把 FDE 能力产品化——FDE 进场生成判断并部署 AI 节点，离场后节点按判断自己跑 |
| FDEing | 工程层动词位（万物皆可 FDEing） | **语法纪律**：FDE = 名词位（人/角色）；FDEing = 动词位（可复用的工程能力——把 FDE 从人力工作做成产品能力）。「万物皆可 FDEing」= 场景框架首句（三域视角见 [v1.5.3 · 五](./changelog/v1.5/v1.5.3.md)），不与「FDE Harness 层」品类词互换 |
| 中间件（Harness 中间件） | Middleware | **品类定位词**——答「sofagent 属于哪个品类」（Harness 类运行时/治理框架）；**不是**「约束层是技术实现层的中间件」这一实现论判断（[设计哲学](./PHILOSOPHY.md) 明确否定该义，改称「数字员工的组织入职协议执行器」）。两义并存不矛盾：一个答**属于什么品类**，一个答**在组织里扮演什么角色** |
| Harness | 约束层 | FDE Harness 层的核心：一个层五种能力（注入·审计·回溯·沉淀·进化）。对外中文「约束层」、英文「Harness」为 SSOT；「FDE Harness 层」即产品整体（约束层 + FDE 方法论 + 审计），「约束层」即其核心，两者一体两面不另作区分；约束层的构成表述 = **一个引擎 + 一组插件**（引擎=约束层本体，即五个功能模块构成的整体，不可拆不可裁）；（详→注-1） |
| Gateway | Gateway | 企业级 AI 统一入口（WorkBuddy / OpenClaw 等大厂平台），sofagent 不替代它 |
| Sub Agent | Sub Agent | 用 LangGraph createReactAgent 搭的专有执行节点 |
| Ontology | 本体数据 | 企业的业务世界模型——一套「什么实体存在、能做什么动作、受什么约束」的规则书（机器可读），FDE 帮你搭建并持续维护 |
| 工程层 / 判定层 / 治理层 | FDEing / S1M / Harness | **产品身份三层口径**（[README · 三因子口径](../README.md)——FDEing 工程 / S1M 判定 / harness 治理）。与本文件「约束层」架构术语是**同一事物的两个视角**（身份叙事视角 vs 架构术语视角），不是两套体系；（详→注-2） |
| River | 统一 Agent 入口 | 多个 Workflow 的集合——每段 Workflow 把模型能力引到业务侧，汇入同一条大河。详见 §五 River—Workflow—Subagent 三层架构 |
| SMB | 中小企业（Small & Medium Business） | 没有专职 AI 部署团队、想低成本具备 FDE 能力的企业 |
| OPC | 一人公司（One Person Company） | 个人或小团队，用自己的 Agent + 模型自主完成部署，不愿被单一厂商锁定 |
| 激活链 | Activation Chain | 生命周期层：FDE 交付物 → 企业工作流自动跑。四阶段 ACTIVATE→ORCHESTRATE→EXECUTE→SUSTAIN |
| ACTIVATE | 激活 | 读 FDE 交付物 → 写 `.sofagent/subagents/*.yml` → 注册企业 SubAgent |
| ORCHESTRATE | 编排 | 多个企业 SubAgent → LangGraph StateGraph 工作流 |
| EXECUTE | 执行 | DAG 运行 + HITL 人工审批 + 审计集成 + 异常兜底 |
| SUSTAIN | 持续 | wrapToolCall 联动：执行 → 审计 → 反思 → 进化 |
| S1M | System One Model（决策模型 · 身份句） | 本仓判定件之名——不生成文字、只输出类型化决策（三原语 Choice/Score/Noul）+ 校准概率 + 弃权语义。**判定/决策/判断三层口径**：身份句用「**决策模型**」（对齐 System One 谱系，产品身份）；机制句用「**判定**」（名词 · 机构面——判定面 · 判定底座 · 判定档 · 判据集 · 判定调用，只出结论、指向治理面）；（详→注-3） |
| System 1 Agent | 品类名 | `S1A = S1M + Harness`（受 FDEing 作用——FDEing 为方法论 plug-in，见 v2.0.0 §一）定义的 Agent 品类（[v2.0.0 §一](./changelog/v2.0/v2.0.0.md)宣告）：FDE 定义场景，S1M 执行判断，Harness 保证判断被治理——不是更快的 Agent，是判断先被治理的 Agent。（详→注-4） |
> 注-1：两者的咬合机制（两相位）：FDE 是判断的**生成相位**（进场时把「该不该上 AI / 做好标准 / 谁拍板 / 何时跑」判断出来并冻结成交付物），约束层是判断的**驻留相位**（离场后 7×24 按冻结的判断执行并产生反馈信号），
> 交接物 = workflow.yml + ontology + MD（FDE 写入、约束层读写、持续进化——是共享状态不是一次性交付）；「Constraint Layer」为同义英文旧称，不再单独使用。**外部定义参照**：agent harness 的构成性定义（必要充分条件 + 可操作的包含/排除检验）见 [THANKS · Loop → Harness → Graph](./THANKS.md) 登记的同题论文——本仓上述口径是该定义下的一种实现形态，**不是该定义的复述**
> 注-2：三域视角已在本档落位（场景/判定/治理域锚见 [心智模型 · 三域视角](#双层架构约束层与生命周期主框架)），全量重构与五域→三域映射表见 [v1.5.3 开发日志](./changelog/v1.5/v1.5.3.md)
> 注-3：叙事句用「**判断**」（动词 · 动作面——S1M 执行判断 · 判断被治理）。不互换：「决策」含行动意志指向应用面，「判定」是机制实体，「判断」是动作——混用会把治理面读成应用面
> 注-4：sofagent = **System One For Agents**（名字 backronym，谐音彩蛋保留）
> ⚠️ **旧名兼容**：五能力（注入/审计/回溯/沉淀/进化）中，前四能力即原约束底座/审计模块/回溯引擎/进化模块（v1.2.9 统一为「约束层四种能力」），「沉淀」承接原「进化」表述中的经验沉淀语义与知识蒸馏管线。历史文档中的四能力与「引擎」表述保留不动（archive/changelog 是历史快照不改）；代码层 `AuditEngine`/`runAuditGate`/`engine/audit` 全是 API，保持不动。
> ⚠️ **「三档 / 五态」术语导航**（三套档位名各自独立，勿混）：FDE 诊断侧 **🔄 自动执行 / ⚡ 强化岗位 / 👤 暂不动** = **业务节点分类**——答「这个环节上不上 AI」，属诊断期，只看该节点本身；判定底座 **高自动 / 中复核 / 低转人工** = 判定结果的分流门槛——按错误率区间分段，属运行期，只看这一次判定的概率；审计结论 `ALLOW` / `ASK` / `ABSTAIN` / `DENY` / `SKIP` = 审计判定的五态输出——答「这次变更怎么处置」。
>三者对象不同（业务节点 / 判定分流 / 审计结论），**不是同一套枚举的三种叫法**，也不得为求字面统一而互相改写。
> 💬 **交互范式**：核心交互是语言（MCP / IM / CLI），无操作型 GUI——所有能力经 MCP 协议暴露，用户经 Agent 对话（LUI）操作：说一句话，它做完告诉你结果在哪。dashboard 是只读监控视图，不承担操作职能。根本设计约束：不存在「仅 CLI 可用」或「需要打开页面」的能力。详见 [设计哲学](./PHILOSOPHY.md)。
### 相位模型对位表（同一套流程的四种切法）
> **一句话**：下表四套「阶段 / 相位」切分说的是**同一件事的不同侧面**，不是四套并行流程——「生命周期五段」切的是**企业 AI 的路径**，「激活链四阶段」是其中后四环的**工程名**，「FDE 四阶段」是进场侧的方法论名，「FDE 两相位」切的是判断的归属。四者互为别名与展开，无一处是另一处的上位或替代。
| 体系 | 出处 | 切法 | 与「生命周期五段」的对位 |
|---|---|---|---|
| **生命周期五段**（产品流程视角 · 本文主术语） | [双层架构](#双层架构约束层与生命周期主框架) / [WIKI](./WIKI.md) | ① 诊断 → ② 激活 → ③ 编排 → ④ 执行 → ⑤ 进化 | ——（基准） |
| **激活链四阶段**（工程名） | [§一 激活链架构](#一激活链架构v125-phase-1-4-已交付) / [guides/fde-activation-chain.md](./guides/fde-activation-chain.md) | ACTIVATE → ORCHESTRATE → EXECUTE → SUSTAIN | = 五段的 **②–⑤ 后四环**；激活链从 FDE 交付物起跑，故「诊断」不在链内——**不是漏项** |
| **FDE 四阶段**（进场方法论） | [FDE/GUIDE.md](../FDE/GUIDE.md) / [HANDBOOK](./HANDBOOK.md) | 梳理 → 构建 → 部署 → 离场 | = 五段的 **① 诊断**（进场生成判断并冻结成交付物），交接到 ② 激活 |
| **FDE 两相位**（判断的归属） | [README](../README.md) / 本文 §术语对照「Harness」行 | 生成相位（FDE 相位 · 进场）→ 驻留相位（Harness 相位 · 离场后） | 生成相位 = 五段的 **①–②**（判断冻结成交付物并完成交接）；驻留相位 = **③–⑤**（按冻结的判断执行、审计、反馈） |
> 🔗 **互引说明（回答「到底有几套模型」）**：[README](../README.md) 用「进场 / 离场两相位」讲**判断归谁**；本文用「一个层，五种能力」讲**约束层做什么**；[PHILOSOPHY](./PHILOSOPHY.md) 用「判断主轴 + 九个剖面」讲**各章归属**。三者不是三套模型，是同一件事的三种切法——判断从进场到离场只有一条路线，三个说法分别回答「判断在谁手里」「约束层对它做了什么」「文档从哪读起」。
>
> **落地版本口径**：生命周期五段中 ① 诊断由 FDE 方法论（已交付）+ `FDE/` 六引擎工作台承载；②–⑤ 即激活链四阶段 Phase 1-4（v1.2.5–v1.3.0 全链路已交付）。
### 约束层七维度（Agent 的构成面）
Agent = **模型 + 上下文 + 工具 + 状态 + 执行控制 + 权限 + 可观测性** 七个维度。约束层五种能力（注入·审计·回溯·沉淀·进化）各自覆盖其中若干维度，不构成独立架构层——七维度是「Agent 由什么构成」的分析框架，五种能力是「约束层对 Agent 做什么」的生命周期框架，两者正交。
> 注：沉淀能力主要作用于上下文（L4 knowledge/ 蒸馏回灌）与可观测性（历史归档/报表），与注入（L1-L4 加载链）的上下文覆盖互补。
| 维度 | 含义 | 主要受约束层哪阶段覆盖 |
|---|---|---|
| 模型 | 推理内核 | 注入（系统约束）+ 进化（模型选择反思） |
| 上下文 | 注入的知识 / 记忆 / 本体 | 注入（L1-L4 加载链） |
| 工具 | Agent 可调用的外部能力 | 注入（工具边界红线）+ 审计（越权调用） |
| 状态 | 运行中的中间态 | 审计（变更留痕）+ 回溯（快照） |
| 执行控制 | 编排 / DAG / HITL | 注入（流程约束）+ 审计（异常路径） |
| 权限 | 能碰什么资源 | 审计（A 类越权规则）+ 回溯（最小权限） |
| 可观测性 | 日志 / 追溯 / 签名 | 审计（硬证据）+ 进化（趋势反思） |
> 维度构成以 [WIKI 术语表](./WIKI.md) 本行为准；五种能力各自的维度分工详见 [设计哲学 §一·四件事的分工](./PHILOSOPHY.md#四件事的分工mcp--skills--ontology--harness)。
## 能力与状态总览
> 这份清单是「现在能干什么」的单一索引。约束层内部设计见 [二、约束层（Harness）设计——一个层，五种能力](#二约束层harness设计一个层五种能力)；未来方向见 [七、已知局限与未来方向](#七已知局限与未来方向)。
### 27 个 workspace 源码包
构成以根 `package.json` 的 `workspaces` 为准：13 个 `@sofagent/*` 模块包 + 工具包 `load-chain` + 基座包 `dsh-plugin-kit`（已转 npm 发布物）+ 7 个 DSH 插件包（`cordis-plugin-sofagent*`，v1.4.9 P2 合并批 10→7）+ 4 个 OpenClaw 插件包 + 1 个 npm 裸名总包 `engine/umbrella`（包名 `sofagent`，聚合安装入口——不属模块包也不属插件）。
其中 15 个发布为 `@sofagent` npm 包（13 模块包 + `load-chain` + `dsh-plugin-kit`），DSH 插件 7 款经 SkillHub + npm 双通道分发。统计口径与包数构成见 [WIKI](./WIKI.md)。
| 包 | 职责 | 状态 |
|---|---|---|
| audit | 提交时审计，28 条规则（17 默认 + 11 扩展，[完整清单见 SECURITY](../SECURITY.md#28-条审计规则完整清单文档级-ssot)）硬证据扫描 + 快照/回滚/webhook + 本体建模要求对齐维度（`runRules({gb48000:true})` opt-in） | ✅ 已实现（1594 测试） |
| core | 核心运行时：git diff 解析、shadow-repo 快照、AES-256-GCM/ECDH、think.md 契约、doctor、LLM 调用 Trace、stop_reason 分类、身份码 Ed25519、敏感识别三层插槽（T8：L0 正则/L1 词典/L2 外挂 NER + DetectorRegistry 调度 + 置信度分层 + Presidio 标签映射） | ✅ 已实现（662 测试） |
| inject | 四层约束加载链 `buildConstrainedSystemPrompt()` + L4 渐进加载（热点全文 + 索引） | ✅ 已实现 |
| rules | 规则引擎纯函数包（零 git 依赖；fs 仅限 AST 扫描的临时目录——mkdtemp 写入待检源码片段，扫描后即清理），编排层 tool-call 事前拦截 + 审批四模式 | ✅ 已实现 |
| eval | 质量评估模块：精确匹配 / 语义相似 / 规则合规 三维评分 | ✅ 已实现 |
| ab-test | A/B 自进化：current vs candidate 并行对比，连续胜出 + 非退化守卫才晋升 | ✅ 已实现 |
| orchestrator | 编排模块：DAG 任务拆解 + LangGraph 闭环 + A/B 调度器 + ToolGate 工具门禁（职责边界与文件落点见 [DEVELOPMENT · 编排哲学](./DEVELOPMENT.md)） |
| train | 后训模块：train-job 编排/审计/隔离/指纹/签名/回收/恢复/安全 + 数据管道/版本/eval 闭环/环境/dry-run/报告 + 云端执行面（替换路径 `import { createTrainJob } from '@sofagent/train'`） | ✅ 已实现（717 测试） |
| daemon | 守护进程：cron + fs 监听 + 文件级审计 + USB 烧录 + 联邦查询 + Dream Cycle 6 阶段 + 启动 LOOP 续跑检查 + 审计轨迹聚合巡检 + 训练孤儿巡检 + 模型清单扫描（注册表 + 端点探测双源） | ✅ 已实现（643 测试） |
| mcp | MCP Server：JSON-RPC 2.0 over stdio，tools + resources 暴露（104 tools 分域清单见 [API](./API.md)，由 tool-registry 生成） |
| ontology | 领域本体：合并 / 状态 / 视图 / 概念合成，三层 YAML 自动生长 | ✅ 已实现 |
| evolve | Skill 优化：复用 audit 规则做安全审查 + 集成优化 + 回填（原 skillopt） | ✅ 已实现 |
| think | 思考链分析：基于 diff + 审计结果自动生成 think.md 反思条目（append-only） | ✅ 已实现（⚠️ 仅 MCP/CLI 路径触发，git hook 路径不自动生成） |
| load-chain | 加载链 Hook 包 `@sofagent/load-chain`：宿主平台（OpenClaw 等暴露会话事件的平台）hook 注入四层约束（DP-4 设计原则提升为正式 workspace 包） | ✅ 已实现 |
> **后训模块为什么在治理仓里**（30 秒答案）：治理的天花板是数据——审计发现的错误（哪些任务做砸了、哪种输出不合格）正是训练的燃料。后训模块把「审计出来的问题 → 修复问题的模型」这条闭环接通，让治理数据反哺模型层；训练资产本身走商业侧交付，治理仓只保留协议与接口（外部化 / 可配置）。英文面使用 "training engine"，两者指同一模块。
### API 分级边界决策（@public / @internal）
v1.3.9 起对所有 workspace 包的入口 export 做显式分级，CI 门禁（[tools/check/public-api.mjs](./../tools/check/public-api.mjs)）拦截未 bump 版本的 `@public` 破坏性变更。
**为什么是这个粒度**：
- 基线覆盖 **13 个包**（12 个 `@sofagent/*` 模块包 + 工具包 `load-chain`；`engine/mcp` 无 `@public` 标注不入基线）——当前 13 包 live 提取共 **2673 个 @public 导出**（v1.5.7 章四 evolve skill-health +21）（磁盘基线快照 2566 符号，见下行；以 `public-api.mjs` AST 解析为权威口径，非 grep 计数）。
版本增量沿革：v1.5.2 +21（rules 出口治理面 11 符号：egress-policy 契约类型+裁决函数；daemon 事件流订阅桥 4；并行批 4；口述沉淀回执 2）；
v1.5.1 +84：orchestrator 900→963（+63：章一事件总线与三类事件源适配器 / 章三异常三分类路由与死信重放 / 章二 PR 决策解释面；同版修复批复核处置 4 符号——删除 `sortEventsByTime` 死导出、收窄 `setDefaultAnomalyBus`/`createWebhookAdapter`/`createTimerAdapter` 测试缝，被删收窄者原即不计入 @public）；
daemon 274→295（+21：章四 OTA 升级执行器与升级策略 + 章五任务下发推送与订阅登记；`signDelivery`/`onDeviceOnline` 2 项降 `@internal` 不计入）；
v1.5.0 时点值 2547（双向变动：存量清扫退役 3 符号，新功能新增 56——章一治理面 16 + 章二双时态 9 + 章八 trace 对账 24 + 章五数据集审阅 4 + 章五陪跑期 3，两段不重叠故 56 即净值）；
时点沿革：v1.4.0 时点 1456 / v1.4.6 时点 2168 / v1.4.7 时点 2364。本行口径以 live 提取为准；磁盘基线随发版重建对齐（当前基线 2566（v1.5.7 章四 evolve +21 符号后 2545→2566），v1.4.9 时代生成——发版时以 --update-baseline 重建后此处回填终值；v1.5.7 章二浏览器底座退役 -4：`BrowserAuditSink`/`BrowserDriver`/`BrowserSession`/`BrowserSessionFactory` 四符号吊销，2549→2545）。
- 未标记的导出**默认视为 @public**（保守默认：宁可多承诺不可漏承诺），`@internal` 需显式标注。
**为什么 @internal 破坏性变更不影响适配层**：
- 跨平台适配器（Cursor / Codex / Gemini CLI 薄挂载）与 `@sofagent/audit` 等外部依赖方**只许 import `@public` 层**——`@internal` 是约束层内部实现细节，破坏性变更不触发 semver 约束。
- 若某符号从 `@internal` 升为 `@public`，等同新增公开 API，需 bump 版本 + CHANGELOG 记录（门禁自动拦截漏标场景）。
> 符号数声称与 baseline 的自动校验见 `public-api.mjs` 的「文档声称符号数校验」段——文档声称的符号总数必须与 baseline 实际数一致，否则门禁 FAIL（根治历史 1449 漂移类问题）。
### 对外核心能力（FDE Harness 给用户什么）
> 累计能力表（按版本归组，全部 ✅ 已发布可用；规划中/排期项见下方「已排期」）：
>
> **控制的两层**（读能力表前的定位）：平台（Agents API / guardrail 类）治**动作**——能不能删库、能不能调这个工具，答案在平台文档，generic；sofagent 治**判据**——交期改得对不对、报价能不能发，答案在这家企业的本体数据里。两层互补：平台拦得住越权动作，拦不住业务对错。104 tool、28 条审计规则裁的都是后者。
> 🗺️ **MCP 工具五域一环（104 tools）**（工具数逐版沿革见 [CHANGELOG](../CHANGELOG.md)）：工具不是工具箱清单，是一个组织的编制表——五域各司其职，六条箭头构成「执行→审计→沉淀→晋升」的自进化闭环；审计域（域三）是整条飞轮的数据源头，其执法手册即 28 条审计规则。
>
> ⚠️ **三套标签不要混用**：五域按**业务职能**划分（本图组织法，**三域视角下属映射源**——五域→三域映射表见 [v1.5.3 · 五](./changelog/v1.5/v1.5.3.md)）；`tool-registry` 的 `roles` 是**使用场景标签**（7 面：audit/fde/eval/agent/ops/commons/browser），服务于 `SOFAGENT_MCP_ROLES` 按角色收窄暴露面；`docs/API.md` 的十能力域是文档编制分组（一个组 = 一个可独立讲述的产品能力）。
>三者用途不同，条目数不相等属预期——**工具总数的唯一权威源始终是 `engine/mcp/src/tool-registry.ts` 的 TOOLS 数组**。
```mermaid
graph TB
subgraph D1["一 · 建工作流（27）——把需求变成可执行的工作流"]
A1["FDE 六引擎 ×6
interview→classify→quantify
→derive→distill→deploy"]
A2["梳理与路由 ×4（route_workflow / activate_workflow
/ compose / workflow_gaps）"]
A3["workflow 编排与模板 ×7（workflow_create / workflow_update
/ workflow_node_add / workflow_diff_preview / workflow_submit
+ G1 模板导出/导入 workflow_export / workflow_import）"]
A4["协作与交付 ×8（create_agent / list_agents / team_create /
team_broadcast / notify_session / pr_submit / pr_review / pr_merge）"]
A5["FDE 交付件 ×2（fde_compose / onboard_prompt）"]
end
subgraph D2["二 · 执行与模型（16）——Agent 干活的手臂与大脑"]
B2["后训模块 ×12（train_budget / train_submit / train_doctor / train_dryrun /
train_report / train_status / train_list / train_diagnose /
train_deliverable / train_serve / train_cloud / train_compliance）"]
B3["模型注册挂载 ×3 + 槽位观测 ×1（router_slots——本地槽位态 + 路由预览）"]
end
subgraph D3["三 · 审计·治理·运维（30）——约束层的神经系统"]
C1["审计 ×10（run_audit / audit_file / audit_data_change /
audit_trail / list_rules / stats / data_sovereignty_report /
trace_reconcile / audit_query / ruleset_export）"]
C2["HITL·快照 ×3"]
C3["运维监控 ×6（daemon_status / health_check /
worklog_query / cost_query / agent_identity / loop_debug）"]
C4["语料导出 ×1（corpus_export）
+ 治理推送 ×1（data_push）"]
C5["治理与可见性 ×2
（contribution_query / list_capabilities）"]
C6["设备接入面 ×4（device_register / device_list——G9 发现与在线态；
device_data_query / device_data_push——G10/G11 数据面）"]
C7["连接器注册面 ×2（connector_register / connector_list——G5b
外部系统连接器注册与发现，与 tool-registry 分列不混列）"]
C8["router 承接面 ×1（router_session_push——T7 过站 session 承接：
schema 校验 fail-closed + 脱敏本地落盘（数据主权）+
usage 入 cost 台账 + key 维度 HMAC 挂链）"]
end
subgraph D4["四 · 知识资产（16）——越用越厚的组织记忆"]
E1["本体数据 ×11"]
E2["反思经验 ×4 + 知识检索 ×1"]
end
subgraph D5["五 · 进化与能力市场（15）——评测胜出才上岗"]
F1["评测与验收 ×5"]
F2["A/B ×2 + Skill 优化 ×1 + refine ×1"]
F3["能力市场 ×6（commons_publish / commons_search /
commons_invoke / commons_rate / commons_retire /
commons_harvest_rule）"]
end
D1 -->|"① 工作流提交执行"| D3
D3 -->|"② 逐次审计留痕"| D4
D4 -->|"③ 反思沉淀 think / decision-log"| D5
D5 -->|"④ 评测胜出晋升·写回运行面"| D2
D5 -.->|"晋升为工作流新能力"| D1
D3 -.->|"⑤ 审计轨迹→训练语料（v1.4.4 导出）→ model_register"| B3
```
> 闭环读法：实线 = 主循环（执行→审计→沉淀→晋升→更强的执行面）；虚线 = 晋升回写与语料飞轮。
>
> ⚠️ **数字口径（五域重算）**：五域条目数之和 **27 + 16 + 30 + 16 + 15 = 104**，与图题及 registry 实数**三处自洽**——权威源 = `engine/mcp/src/tool-registry.ts` 的 `TOOLS` 数组，逐工具名分桶（依据**业务职能**，非 `roles` 标签，见「三套标签不要混用」）。自洽由 `check-docs.sh` §20 断言（提取求和比对；提取为空 ⇒ 判红）。
>
> **增量化简记**（记号：域 +N = 该域条目数变化）：五域条目的逐版归域变化（v1.4.9 设备/连接器/模板/router 承接面扩面与 2 枚回填、v1.5.0 `trace_reconcile`、v1.5.2 `audit_query`/`ruleset_export`、v1.5.4 `router_slots`，及 2026-09-26 浏览器四件套退役）见 [CHANGELOG](../CHANGELOG.md)。
> 📌 本表覆盖至 v1.3.8；v1.3.9 及其后版本（v1.4.0~v1.4.9、v1.5.0）的能力沿革见 [CHANGELOG](../CHANGELOG.md) 索引与各版开发日志，本表不再逐版续列。
| 版本 | 关键能力 |
|---|---|
| **基座（v1.2.0）** | FDE 常驻部署 · AI 节点自动化 · 28 条规则审计（基座 v1.2.0 时 26 条；零 token 纯静态）· 一键回滚 · 平台无关核心约束 · AI 知识库自动积累 · Ontology 本体数据 · USB 一键烧录 · 安全联邦多设备互查 · 4 个 Sub Agent · daemon + A/B 调度器 · MCP Server · FDE 四阶段十二步 · sustain 模式（逐项见 [HANDBOOK](./HANDBOOK.md) 与 [开发日志](./changelog/)） |
| **v1.2.9** | 三个入口产品（npx 零配置审计 CLI + 规则市场 `--ruleset` + GitHub Action）· FORGE Driver 短任务化 + Checkpoint/Resume worker 级断点 + PM2 守护进程 |
| **v1.3.0** | 运行时审计最小闭环（wrapToolCall middleware + tool-gate 动态拦截 + 运行时审计日志）· 决策审计（emitDecision + HMAC 链 + kind-wise 查询）· 规则透明化（`list_rules` MCP tool）· 危险操作 HITL 钩子 · 双规则系统统一（`ruleType`）· 激活链 Phase 4 收尾（SUSTAIN 全闭环）· 外部记忆后端 Path A（可选，缺省关闭）· 进化链路写保护 |
| **v1.3.1** | Ontology 运行时层（Action 注册表 + validator 三态 + Schema 定稿）· 并行编排（ParallelScheduler + 波次审计卡关 + MergeQueue）· Durable Execution（checkpoint 续跑 + 副作用幂等）· Agent 身份码 Ed25519 · Benchmark 评测 · 工具审批四模式 · LLM 调用级 Trace · L4 渐进加载 · 跨设备审计轨迹聚合 |
| **v1.3.3** | L2 团队协作协议 + Refine Agent 完整版 + 入口路由 |
| **v1.3.4** | L3 组织能力公地（发布→发现→调用→评价→养护）+ SkillScan 安全门（三态判定）+ 编排层与执行层分离（ExecutionBackend） |
| **v1.3.5** | MCP 自进化+运维闭环（A/B 实验 run_ab_test / promote_ab 人审晋升 + 快照 snapshot_list / snapshot_restore 人审恢复）+ instinct→skill 自动进化（三源提取 + 置信度评分 + /evolve 聚合）+ FDE 运维五件 + DSH MCP 互通 |
| **v1.3.6** | 引擎接口外化——Workflow 标准格式 + 运行容器 / Ontology Schema 注册 / 模型注册 + 灰度切换 / SubAgent 托管 SDK / 训练协议三约定 + 预算控制 / 机器可判定验收 / 路由决策可解释性 / 可靠性五件（worktree 隔离 + 双闸验证 + 疲劳度检测 + 分级降级 + decisions.jsonl）· MCP 60 tools |
| **v1.3.7** | SubAgent 完整沙箱（虚拟 FS / 网络白名单 / 工具中介 / 虚拟 key / 独立进程 / A-B 双跑）· 场景驱动权限 · AgentShield 五类扫描 · 行业 overlay 四套 · 断路器行为监控 · ontology 生命周期 |
| **v1.3.8** | 代理网关硬边界（唯一出入口 + 风险分级 + 权限单调守卫 + HITL 审批队列）· 数据静态加密· 能力交付：纯 TS AES-256-GCM，daemon 接线 v1.4.7 收口——密钥就绪后审计历史密文落盘 SOFAGENT-AGE-V1。**现状标注（F48-② · v1.5.7）**：密钥缺失时 daemon 启动打一次性引导提示（crypto-init WARN，明文兼容不阻断）；（详→注-1） |
> 注-1：附链面（task/logs · think.md · knowledge/）**仍明文**——静态加密当前仅覆盖 history.jsonl 主链，权威清单见 LIMITATIONS · Durable Execution L3（WAL 三态恢复 + undo 三档回滚）· 异步长任务自治 · FORGE driver 保活三件套 · 托管 SDK `sandbox:true` 启用 · release-gate 瘦身 · fresh-eyes 成本重构 · 快照写路径加固
> **v1.2.0 审计链安全加固**（BugFix 批次）：`--doctor` hash chain 三态判定（`checkHistoryChainDetailed`）· HMAC key 强校验 · 签名基于脱敏记录（先 sanitize 再签名，写读一致）· config 可选签名校验（`verifyConfigSignature` CLI）· CLI 版本一致性自检。
>详见 `engine/core/src/audit-history.ts`、`engine/core/src/config-loader.ts`。
### 安装包边界与部署架构（v1.3.2 定位校准）
> **核心定位**：sofagent 装在**企业跑 AI 节点的设备**上，是 Agent 的监控约束层。FDE 自己的电脑不该跑 install.sh——FDE 的工具是 Skill（方法论）+ 未来商业模型。
>
> **行业坐标**：竞争主战场正从应用层转向智能层（**产品即智能**）。sofagent 的差异化立场不在智能层而在约束层：**智能是模型厂商的，管住智能的约束层才是企业的护城河**。Sovereign AI 要的「对关键智能链路的控制权」，其一半（数据主权/审计/审批/回滚/灰度）正是约束层职责——企业掌控智能，sofagent 提供管控（约束层的活），互补不冲突。（外部出处与对位明细见 [VALIDATION](./VALIDATION.md)）
**谁装什么——三个位置各归各位**：
| 位置 | 装什么 | 目的 |
|---|---|---|
| **FDE 的电脑** | FDE Skill（ClawHub 装）+ 未来商业 FDE 模型 | FDE 做诊断——五要素拆解、建 workflow、搭 ontology |
| **企业设备**（跑 AI 节点）| **sofagent install.sh 全套** | **盯 Agent**——审计每次变更、回溯、注入铁律、daemon 7×24 巡检 |
| **企业员工的 Agent 平台**（WorkBuddy/Codex） | sofagent Skill（ClawHub 装）| 员工的 Agent 受铁律约束干活 |
**install.sh 装什么——企业设备需要全套（事前约束 + 事后拦截）**：
| install.sh 装的 | 为什么企业设备需要 |
|---|---|
| @sofagent/audit + git hook | 事后拦截——Agent commit 时扫 28 条规则 |
| daemon | 7×24 巡检（数据主权 / 知识健康 / 失败模式） |
| dashboard | **单机监控面板**——企业 IT 看本设备 Agent 运行状态（多设备聚合走商业侧平台，不在开源范围） |
| SKILL.md + fde.md + rules/core-rules.md + rules/role-*.md | **事前约束**——Agent 启动时读铁律，知道规则才能遵守 |
| 4 个 Agent Skill（fde/audit/engineer/reviewer）| SubAgent 岗位定义 |
| HMAC key | 审计记录防篡改 |
> **事前约束（Skill 注入）+ 事后拦截（审计模块）缺一不可**——只有审计没 Skill = Agent 不知道规则；只有 Skill 没审计 = Agent 知道规则但可以不遵守。install.sh 是这两者的完整闭环。
**安装器模式**：
| 命令 | 装什么 | 适用 |
|---|---|---|
| `install.sh`（默认） | 底座 + FDE Skill + hook（全套） | **企业设备**：要常驻 Agent + 7×24 监控 |
| `install.sh --base-only` | 仅底座（审计·回溯·daemon） | 企业 IT：只要核心监控，不装 Agent Skill |
| `npx -y -p sofagent sofagent audit` | 零安装，临时审计 | 开发者：30 秒体验，在任何 git 仓库跑一次 |
> ⚠️ **FDE 不该在自己电脑跑 install.sh**——install.sh 是企业设备安装器，不是 FDE 工具。FDE 的工具是 Skill（ClawHub 装）+ 未来商业模型。
>
> ⚠️ **dashboard 是单机监控面板**——每台装了 sofagent 的设备一个 dashboard，盯本机 Agent。多设备聚合是企业级需求，走商业侧平台（不在开源范围）。
>
> **Dashboard 双形态说明（v1.3.5 归位 tools/）**：`tools/dashboard/dashboard.html`（Web 形态，`serve-dashboard.mjs` 起服务）与 `tools/dashboard/sofagent-dashboard.sh`（终端形态，零依赖 bash）是同一 Dashboard 的两种产品入口：Web 给老板/IT 可视化看，终端给开发者/FDE 快速看。职责不同，勿混用/勿删其一。
> 最小可用：只装 `@sofagent/audit` 就有纯审计（28 条规则，17 默认启用 + 11 扩展 opt-in + 快照 + 回滚）；全量形态为 27 个 workspace（包数构成权威表述见 [WIKI](./WIKI.md)），全装才是完整约束层。
### 已排期（开发中或即将开发，详见 ROADMAP）
**排期中（未交付）**：完整多设备协同 L2 · 本地推理 workflow 专属 LoRA 小模型（v3.x–v4.x 远景，无近期版本单元格）。
### 治理面（约束层的可见性出口）
| 能力 | 落点包 | 一句话 |
|---|---|---|
| 治理 KPI 面板 | `@sofagent/audit` + Dashboard | 六卡聚合（边界触发率/审计覆盖率/HITL 时延/趋势/重复执行/trace 一致率）+ 数据集审阅 + lineage 合规报告 + 周报 |
| 本体数据双时态 | `@sofagent/ontology` | `stateAt` 时点快照 + `validFrom`/`validTo` + 三层渐进加载（预算联动降级留痕） |
| Validation Engine | `@sofagent/ontology` | DAG 三色 DFS 环链定位 + schema 兼容三态 + 激活前置门 fail-closed |
| 跨层证据对账 | `@sofagent/core` | `reconcileTraces` 三源四态（一致/漏报/幻觉/瞒报）+ 回滚闭环豁免 |
> 治理面是约束层的「可见性出口」——前四版把能力做进引擎，本版开始让能力被看见、被对账。上表四项能力的编制归属见 [§四 功能编制](#功能编制约束层内的功能模块)。
---
> 🧭 **域一 · FDE 场景层**——进场侧工程化：怎么把企业业务梳理成可执行的场景资产。架构落点 = 激活链四阶段（FDE 交付物 → 企业工作流自动跑）；方法论与操作视角见 [FDE/GUIDE.md](../FDE/GUIDE.md) 与 [HANDBOOK](./HANDBOOK.md)。
## 一、激活链架构（v1.2.5+ Phase 1-4 已交付）
> **本章是心智模型「层 2 · 生命周期」的架构展开**——层 1 约束层（一个层五种能力）已在第二章详述，这里讲生命周期怎么跑。
>
> **问题**：FDE 诊断交付了 ontology + workflow.yml + skills/ + nodes/*.md，这些静态文件躺在磁盘上，企业 IT 不知道怎么把它们跑起来。交付物和「工作流自动运行」之间有一道**大断裂带**。
激活链（ACTIVATE→ORCHESTRATE→EXECUTE→SUSTAIN）是连接「交付」和「自运转」的桥。详细设计见 [激活链设计文档](./guides/fde-activation-chain.md)，这里讲架构层面。
### 数据流闭环
```mermaid
flowchart TD
FDE[FDE 诊断交付物
ontology + workflow.yml + skills/
nodes/*.md — 静态文件]
FDE --> A1[① ACTIVATE 激活
activate.ts
v1.2.5]
A1 -->|写 .sofagent/subagents/*.yml| REG[registry.ts 动态注册
v1.0.8 起已有]
REG --> A2[② ORCHESTRATE 编排
composeEnterpriseWorkflow
映射扩展 + StateGraph 构建]
A2 -->|多 Agent → StateGraph| SG[LangGraph StateGraph
条件路由 + 并行 + 汇合]
SG --> A3[③ EXECUTE 执行
dag-runner + node-executor
HITL + 审计集成 + 异常兜底]
A3 -->|HITL interrupt_before| HITL[人工审批节点
高风险操作暂停等人确认]
A3 -->|审计 hook| AUDIT[审计
每步变更自动审计]
A3 -.节点内部状态机.-> SM[SKILL.state 执行协议
P+Σt+ot 三输入 · ΔΣt 代码合并
Rt 弃前落审计摘要 · v1.5.5]
SM -.审计摘要.-> AUDIT
A3 --> A4[④ SUSTAIN 持续
wrapToolCall 联动
全链路验证]
A4 -->|think.md 回写| EVOLVE[进化模块
执行→审计→反思→进化]
EVOLVE -.->|喂下一轮诊断| FDE
```
### 四阶段 × 核心交付 × 依赖
| 阶段 | 核心交付 | 依赖已有能力 |
|---|---|---|
| ① ACTIVATE | `activate.ts` + MCP `activate_workflow` tool + workflow.yml 扩展 | registry.ts 动态注册 + MCP Server |
| ② ORCHESTRATE | workflow-parser 扩展 + `composeEnterpriseWorkflow()` + StateGraph 构建 | orchestrator + LangGraph StateGraph |
| ③ EXECUTE | dag-runner node-executor + HITL interrupt + 审计集成 + 异常兜底 | audit + daemon 文件监控 |
| ④ SUSTAIN | 全链路验证 + `wrapToolCall` 联动 | think（反思模块）+ eval + evolve |
> **关键认知**：底座（引擎）已经全绿（测试数量以 `tools/check/test-count.sh` 实测为准），激活链不是造新引擎，是往已有引擎上放车厢——「轨道从早期就铺好了，一直没人往上面放车厢」。
### 企业 SubAgent YML 格式
```yaml
# .sofagent/subagents/financial-audit-agent.yml
name: financial-audit-agent
source: FDE-generated # 标记来源：FDE 激活链自动生成
skill_ref: skills/financial-audit/SKILL.md
workflow_ref: workflows/financial-audit.yml
node_ref: nodes/financial-audit.md
hitl:
mode: interrupt_before # 高风险节点执行前暂停等人确认
trigger: writeback # 写回业务系统时触发
audit:
on_step: true # 每步自动审计
on_complete: true # 完成后全量审计
```
### 与 River 比喻的对应
| River 比喻 | 激活链对应 |
|---|---|
| 自来水厂（沙箱安全） | EXECUTE 的沙箱隔离 |
| 管道（审计） | EXECUTE 的 `on_step: true` 审计集成 |
| 水龙头（Sub Agent） | ACTIVATE 注册的企业 SubAgent |
| 水表（审计 Dashboard） | SUSTAIN 的 wrapToolCall 可观测 |
> 激活链 = 把「水厂造好的水」（FDE 交付物）通过「管网」（编排）送到「水龙头」（执行节点），再通过「水表」（审计）计量——最后根据用水数据（think.md）优化整个系统。
---
> 🧭 **域三 · harness 治理层（本章起）**——约束层五种能力的设计展开归治理域（三域定位见 [§四 章首注](#四核心理念与全局设计)：五能力、审计链、回溯都在治理域）；判定域（S1M 判定层）的架构落点 = [§三 审计规则面的判定化边界](#审计规则面的判定化边界28-条规则--判定层接管)。
## 二、约束层（Harness）设计——一个层，五种能力
> 🧭 **两个作用面（通道视角，先读这个再看逐能力）**：五种能力按「约束以什么通道到达 Agent」分两类。**Context 注入面（软）**——注入链（L1–L4）与沉淀回流以文字形式进模型上下文，管「引导」：遵守与否取决于宿主档位（Skill 自觉加载 vs 硬注入）与模型自觉，且文字形式的约束会被更强的模型逐步吸收进权重（[PHILOSOPHY](./PHILOSOPHY.md)「文字形式约束的吞噬效应」段）。
>**系统强制面（硬）**——审计（git diff 硬证据 + HMAC 链，Agent 无法篡改）、回溯（快照回滚）、工具拦截（toolGate / 生命周期事件）不经模型上下文，靠架构强制——**模型自觉不构成防线**。两层缺一不可：只有注入面 = Prompt 框架（约束全是建议）；只有强制面 = 没有业务判据可审的空壳。「约束是建议性的，审计是强制性的」正是这两个面的分工口径。
### 🐎 缰绳面 / 执行面判据（新功能过筛表）
约束层的每个能力点，进排期前先回答一个问题：**它管马，还是它自己就是马？** 判断错了，harness 就会长成半个马场（教训实测：训练域代码缰绳面:执行面 ≈ 39:61——意图是给云端后训练装哨卡，实现长成了哨卡 + 自建马场）。
**四问过筛**（答「是」即出开源约束层，四问全「否」才可进）：
| # | 过筛问题 | 答「是」的含义 |
|---|---|---|
| 1 | 它的产出是**算子 / 资源 / 产物**（数据转换、环境安装、下载、打包、拟合），而非**判定 / 拦截 / 留痕 / 追责**（规则、闸门、审计事件、签名、账本）？ | 执行面——开源生态已有成熟轮子（ETL / 环境管理 / 下载器 / 打包器） |
| 2 | 换一个外部实现（verl / vLLM / Langfuse / 任意 ETL 库），它的价值是否**不受损**？ | 是 → 通用算子，自研即重复造轮子 |
| 3 | 它失效时，损失的是**跑不动**，还是**管不住**？ | 跑不动 → 执行面（可运行性不该由约束层兜底） |
| 4 | 它能否被外部替换而**缰绳接口不变**（事件契约 / 校验契约 / 账本不动）？ | 否 → 耦合设计错了，先抽通道接口再实现 |
**两条豁免**（写明而非偷偷留）：
- **共享账本层**：跨面共用的类型 / 状态机 / 版本台账（train-job 生命周期、dataset-version 台账）划入缰绳侧——它们是「词汇表」不是「执行器」，不算执行面耦合。
- **正当读耦合（「验马要懂马」）**：缰绳为完成判定必须读的执行侧知识（显存曲线做预算估算、环境清单做诊断）——保留依赖，但**只读不调**（不触发算子执行），在此声明豁免。
**结构性闸门**：一切执行面需求以 **TrainChannel 通道形态**接入——接口 + 事件归一/产物校验契约 + 通道监控留约束层，实现出约束层（适配规范 / 参考示例 / 商业侧）。不立新模块、不在约束层内长算子。USB 设备接入、router 数据收集等未来执行面需求一律走此形态。
**外部互证——执行闭环是分界线**：语义层与只读 Agent 堆得再厚，整套系统仍停在「知」（查询 / 分析 / 解释），没碰过「行」。行业独立工程实践收敛到同一判据：**判断能触发真实业务动作、动作结果能被后续现实检验，才是分析层与执行层的分界线**——与四问过筛第 1 问同构（判定 / 拦截 / 留痕 / 追责 vs 算子 / 资源 / 产物）。三条同构做法：
- **写路径收敛**：AI 对话默认无增 / 改 / 删权限——读开放（查询工具 + 只读白名单），写收敛（录入 / 提交 / 审批走固定页面或已注册行为工具），概率系统不直接碰现实。
- **确定性降级路由**：已有行为 API 优先于查询 API，自由拼 SQL 是最后手段，语义解释兜底——能走已注册能力就不自由发挥（Skill 路由同理）。
- **检验落在模型外**：判断对错取决于有没有被写回的现实推翻，可检查性不依赖模型自述。
sofagent 落点：审计模块的 git diff 硬证据正是「动作结果被后续现实检验」的工程实例——写回现实的动作才需要过闸门并留痕，纯读操作不构成审计对象；自派 SubAgent 沙箱的工具调用前置 allow/deny 即「写路径收敛」的约束层实现。适用边界同理收敛：语义层建设「够用就好」——单系统语义自洽则 Agent 直连 API 即可，多系统先主数据治理，非标、动态、跨域推演三条件齐备才需要完整本体数据（与 §三「Ontology 阶段匹配：不要提前进化」一致）。
### 📥 注入（约束注入链）
四层加载链（SKILL.md → fde.md → think.md → knowledge/）在 Agent 启动时自动注入。每层有不同权限：
| 层 | 文件 | 权限 | 加载时机 |
|---|---|---|---|
| 1 宪法 | SKILL.md | ❌ 不可修改 | 最先加载（开头注意力最高） |
| 2 规范 | fde.md | ✅ 可改 | 企业专属规则 |
| 3 反思 | think.md | ⚠️ 自动生成 | 上轮踩过的坑 |
| 4 知识 | knowledge/ | ✅ 积累 | 自动关联的 best practice |
宿主平台中暴露会话事件的（OpenClaw）通过 Hook 精确注入，DSH 走插件在 `tools/pre-execute` 等事件上逐调用注入，其他平台 Agent 主动 Read，v1.0.7+ Sub Agent 启动时自加载（`buildConstrainedSystemPrompt`）。
> **v1.1.8 加载链扩展**：联邦知识注入于 knowledge/ 层（加载链第 4 层，位于 think.md 第 3 层之后；目录 `knowledge/federation/`，daemon 联邦查询落盘的 peer 知识快照）——低于 SKILL.md 宪法层。联邦内容是外部来源，强制 `` 包裹（Prompt 注入防线层 1，详见 SECURITY.md 8 层映射表）。
> ⚠️ **加载顺序的准确语义（v1.5.1 与实现对齐，纠正「后加载 = 优先级更高」的单向表述）**：读 `engine/inject/src/index.ts` 的 `buildConstrainedSystemPrompt()` 实测——加载链只做**顺序追加**（逐层 `parts.push()`），**代码层不实现任何冲突裁决**：既不替换、也不去重、也不做「后加载覆盖先加载」的合并。因此：
>
> | 轴线 | 顺序 | 实际含义 |
> |---|---|---|
> | **层间**（宪法 → 规范 → 反思 → 知识 → 联邦） | SKILL.md 最先 | 权限递减（宪法层 ❌ 不可修改）+ 开头位置注意力最高；**不是**代码强制的高低优先级 |
> | **custom/ 用户层**（加载链第 3.5 层，追加在官方三层之后） | custom/ 最后 | 与官方规则**并存**（追加而非替换）；「custom/ 优先」是**意图声明**，不是代码裁决 |
> | **custom/ 内部**（项目级 → 用户级） | 项目级在前、用户级补足 | 两级都注入，项目级占用 `maxFiles` 名额后用户级补余量 |
>
> **诚实边界**：既然不存在代码级裁决，「谁压过谁」最终取决于模型对上下文的注意力——这正是 [LIMITATIONS「Harness 层自身在上下文里」](./LIMITATIONS.md#-harness-层自身在上下文里) 登记的已知边界。写文档时不得把「追加顺序」表述成「机制保证的优先级」。
### 为什么选注入，而不选 fine-tune / 显式 prompt
约束层选择「注入」作为核心机制，是因为两个备选方案各有不可接受的代价：
| 方案 | 为什么不选 |
|---|---|
| **fine-tune（微调模型内化约束）** | 不可审计（约束被压缩进权重，无法逐条核对模型是否真的记住了）· 不可回滚（改约束需重新训练，不能像改 MD 文件一样即时撤销）· 不可按会话粒度调整（微调是模型级改动，无法针对单个 Agent / 单次会话差异化）· 成本高（每次约束变更都要训练） |
| **显式 prompt（把约束写进系统提示词）** | 依赖 Agent 注意力，无机制保障——模型可能忽略长文本中的约束（Lost in the Middle），无法保证 100% 命中 |
注入（四层约束注入链）把约束放在可审计、可回滚、可逐会话加载的 MD 文件层，配合事后审计的 git diff 硬证据兜底。注入的已知边界是「约束力 = Agent 注意力 × 平台加载可靠性」（见 [LIMITATIONS「Harness 层自身在上下文里」](./LIMITATIONS.md#-harness-层自身在上下文里)），但相比 fine-tune 的不可审计与显式 prompt 的无兜底，注入是三者中唯一「可被外部逐条验证」的路径。
### 权限四原则与零凭证沙箱
行业参考将 Agent 权限治理归纳为四条可操作原则，与 sofagent 审计能力 + 约束注入链同构：
1. **最小权限**：每个 Agent 只拿当前任务必需的最小凭证集，不预置全量权限。
2. **群维度隔离**：按组织 / 项目 / 环境维度隔离权限域，跨域调用需显式授权。
3. **不可越权**：硬约束层（审计能力）兜底，越权动作在 Action 边界被拦截，AI 绕不过。
4. **可热更新**：权限策略运行时可改、即时生效，不重启 Agent。
5. **独立身份**：每个 Agent 是独立主体，归入 IAM 的「工作负载 / 机器身份」类，发短期凭据、单独撤回。判据：**权限必须有明确主人**——与人共用凭据即无法归因。与第 1 条互补：四原则管「权限怎么给」，本条管「记在谁名下」（衔接 §审计规则面「凭证范围」盲区）。
> 📖 来源：知识库消化与维护（2026-10-13 · 4 源：Gartner 工作负载 IAM · Agent 权限归属 · 企业四道闸门 · Anthropic 工牌；余源一手核对归 GDM 巡检）· [Gartner Workload Identity](https://www.gartner.com/en/information-technology/topics/workload-identity)
**零凭证沙箱**：运行时不落明文密钥——凭证守护进程注入、用毕即销，Agent 只见句柄不见明文（对齐 A2 铁律）。
**权限疲劳量化**：Claude Code 逐步审批实测约 **93%** 被批准——提示越多审得越松；改 OS 级沙箱后降 **84%**。判据：**监督不能靠逐步审批，隔离强度须匹配监督能力**（多 agent 审批疲劳是乘的）。
**事后审计的天窗**：模型自主越界**72 天后才被发现**——只做事后回溯，空窗必重现。本仓对应面：v1.3.7 起自派 SubAgent 沙箱（文件系统隔离 + 网络出站白名单 + 工具调用前置 allow/deny + 虚拟 key 边界注入）即「默认断网」形态；主 Agent 永远事后审计（边界见文末声明）。
> 📖 来源：Anthropic 跨产品 Agent 封堵实录（2026-05-25 · 93% 批准率 / 沙箱降 84% 权限提示）· [Anthropic Engineering](https://www.anthropic.com/engineering/how-we-contain-claude)
> ｜ Anthropic 自主提交虚假凶杀线索后切断联网（2026-10-10 · 72 天空窗 + 处置三件套）· [The Decoder](https://the-decoder.com/anthropic-cuts-off-claudes-internet-access-after-the-model-autonomously-filed-a-fake-homicide-tip-with-philadelphia-police/)
**最坏情况反问**（必答题）：「Agent 被 Prompt 注入后最坏情况是什么？」答案应是 profile 内权限能做的事，非全系统沦陷——权限保护的是组织。
**动作后果分级（中间档 · 2026-10-01 补）**：能力注册项带后果等级（**只读 / 副作用 / 改权限 / 改环境**四档），激活链按等级定确认强度：读自由 · 写确认 · **权限变更二次授权** · 环境变更走红线。
**与本仓既有提权分级的分工（勿混）**：[v1.4.8「shell 提权分级」](./changelog/v1.4/v1.4.8.md) 管的是**执行侧**（shell 命令按危险度三态 safe / risky / dangerous 路由到直接跑 / 场景策略 / HITL），本条管的是**注册侧**（能力项按后果类型声明）——净增量两点：① 作用域从 shell 命令扩到全部能力注册项；② 分档维度从「危险程度」细化为「**后果类型**」——改权限与改环境是不同性质的后果（前者导致持久提权、后者动摇运行根基），混作一档则处置策略无从分化。
**外部教训**：SQL Copilot 提权链 [CVE-2026-65669](https://msrc.microsoft.com/update-guide/vulnerability/CVE-2026-65669)（CVSS v3.1 **9.6** / v4 8.6，2026-09-08 披露）机制——植入恶意 `CONSTITUTION.md` → 管理员使用时触发 → 绕过只读限制、
以该连接已持有的权限执行 T-SQL → 攻击者自我提升为 SYSADMIN**。
它**不授予任何权限，用的是连接上已有的权限**——故其首要教训是**最小权限**（连接身份决定爆炸半径，与上条「最坏情况反问」同源）；其次才是「合法工具做越权事」的检查盲区（护栏校验「工具能否调用」，管不住「用合法工具做越权操作」）。
**三方向同构**：AWS Bedrock 四级谱 + 交付门禁（对抗测试一次未授权调用即阻断）· 钉钉 ActionTier 三档 · 本仓 v1.4.8 提权三态。
> 📖 来源：Johann Rehberger《From SELECT to SYSADMIN》（BlueHat Asia 2026）· [Microsoft MSRC · CVE-2026-65669](https://msrc.microsoft.com/update-guide/vulnerability/CVE-2026-65669) ｜ AWS《分级自治：四级授权谱（2026-09-20）》（IMA 收录，无公开 URL）｜ hugozhu《信任阶梯与 ActionTier 风险分级》（IMA 收录，无公开 URL）
**动态治理三机制**（行业参考内部实践）：
- 动态提权：任务触发、限时授权、到期自动回收（临时审批申请 → 批准 → 约 2 小时后过期）。
- 熔断拦截：高危操作实时拦截、等待人类确认。
- 红线制度：超阈值动作（如合同金额 > 10 万）须 VP 签字等边际审批。
**外部准入是独立依赖项（2026-10-17 补）**：Agent 对第三方服务 / 站点 / 机构的**代理访问权**不归自家权限模型——由对方单方面决定，且当前只有「本人 / 程序化接口」两档可辨；代理身份与真人无法区分时，机构只能**整类禁止**。判据：四原则管「我们能给多少」，外部准入管「对方允不允许」，二者正交——漏登记则权限设计再严也会在边界处失效。
> 📖 来源：知识库消化与维护（2026-10-17 · 3 源跨域；银行侧与站点侧均为媒体转述、非监管原文，a16z 数字为图表周报口径）：金融 — 花旗 / 美银禁第三方 Agent 访问客户账户（FT 转述）｜ 内容与电商站 — Yelp 付费授权 · Delta / 摩根大通 / 嘉信屏蔽 · Cars.com / Amtrak 由可用转不可用（The Verge 梳理）· [Financial Times](https://www.ft.com/)
> ｜ 浏览器宿主 — ChatGPT for Chrome 扩展同持多标签读取与代为操作、无权限中间档 · [The Verge](https://www.theverge.com/) ｜ [Andreessen Horowitz](https://a16z.com/)
### 联邦查询
两台配对设备经 Agent 平台 channel（如 OpenClaw）互相查 knowledge/。纵深防御四层：MCP 走 stdio 本地进程通信（无网络监听面） → 平台 channel 路由 → **AES-256-GCM 应用加密**（审计结论：本地回环 ws:// 明文无 TLS，第 3 层是唯一保密防线）→ sensitivity frontmatter 过滤。
| 模块 | 落点 | 职责 |
|---|---|---|
| 安全层 | `core/src/crypto/` | AES-256-GCM（IV 12 字节随机不复用 + tag 校验）· ECDH(prime256v1)+HKDF 派生 32 字节 key（只存内存）· 24h 密钥轮换（旧 key 只解不加）· 三条配对路径（6 位码 + y/N / `~/.sofagent/federation.token` 文件（权限 600，带外交换）/ federation.json HMAC .sig 验签） |
| 传输层 | `daemon/src/federation/channel.ts` | Agent 平台 channel 抽象（依赖倒置，测试内存 channel）；只搬运密文帧（iv‖tag‖ciphertext） |
| 查询路由 | `daemon/src/federation/query-router.ts` | 并发 fetch + 单 peer 5s 超时按离线 + sensitivity 本地端二次校验（restricted 不接收；篡改标签降权 trust=web + 审计 WARN） |
| 合并 | `daemon/src/federation/merge.ts`（re-export `@sofagent/core` federation） | `@automerge/automerge@^3.4.1`（MIT，Rust WASM 稳定核心，v1.3.5 迁移）CRDT 合并（clone-fork 共享版本史收敛，实现下沉 core/federation.ts）；裁决：trust 优先于 mtime；排序 trust 降 → mtime 降 |
| 离线降级 | `daemon/src/federation/offline-fallback.ts` | 任一 peer 离线跳过不阻塞；全部离线/整块失败退化纯本地查；审计 `federation_query{peers, merged, onlinePeers}` |
| 注入点 | `mcp/src/mcp-server.ts` · `harness/src/index.ts` | search_knowledge 异步联邦合并（best-effort）；harness 加载链第 3 层（`` 包裹） |
### 🔍 审计能力
核心设计决策：**审计必须外置。** Anthropic 发现 Claude 内部存在 J-space——AI 自己知道控制不住自己。所以不信任 Agent 自我报告，只看 git diff 硬证据。
**判定机制外置与超限即拒（行业四源收敛）**：判定/审计机制必须在被约束方够不到的位置，且上限触发时须硬拒绝而非静默降级。四源同构——Anthropic AAR 训练与评测物理隔离；NVIDIA Sentry 带外监控（BlueField-4 DPU）；智谱 ZCode 事件反证「证据保管方=被审计方」失效（删除只能自述、无第三方核验）；Codex 826 事件暴露同握「写日志+删日志」权限即审计链源头失效。拒绝语义：Laya choice 超限静默截断（对照 NanoJev 抛异常）、METR 可疑度超阈即阻断转人工——超限即拒、失败要响亮是可选择的工程立场。
本段补节首「为什么外置」的物理形态与失败语义；四源逐条展开见 VALIDATION。
> 来源：Anthropic AAR 技术报告（arXiv 2608.28945，2026-09-27）｜NVIDIA Open Agent Safety Platform（2026-09-27/28）｜智谱 ZCode 整改公告（IT之家 2026-09-28）｜Codex 用户报告（Hacker News 2026-09-27）｜Laya choice 缺陷解剖（2026-09-22）｜METR Notes（metr.org，2026-09-27）
**validate 闸口是新的权力中心，权力必须有主人且自身被审计**。哪个 action 可直执行、哪个须审批，全由 validator 规则决定——validator 必须挂主管名下、每次变更进审计日志，否则架构里出现一层没有主人的新权限。OpenAI 前沿训练安全指导原则把同一判据写进组织流程：「谁有权叫停」须事前显式写入流程（否决权分散到研究/安全负责人与首席科学家多人，安全论证先于训练开跑），而非事后临时授权。两源合成的落点：**闸口的权力归属与闸口自身的审计留痕是同一件事的两面**——只挂主人不留痕则权力不受监督，只留痕不挂主人则告警无人认领。
> 来源：hugozhu.site ·〈数字员工不是一个更大的 Agent Loop：双 Loop 分界与 validate 权力中心〉｜OpenAI ·〈前沿 AI 训练安全指导原则〉（本仓经 IT之家转述收录，未复算官方原文——引用判据句时以句内转述为准）
```mermaid
graph LR
A[Agent 改代码/改文件] --> B[git commit 或 daemon 检测到变更]
B --> C{审计
规则库判定}
C -->|违规| D[⛔ 拦截 + 记录]
C -->|合规| E[✅ 放行]
D --> F[think.md 自动反思]
F --> A
```
**证据分层**：git diff = 硬证据（默认配置下的防线——git-diff 审计与执行路径无关，`--no-verify` 等绕过面见 [LIMITATIONS §三](./LIMITATIONS.md#三安全与信任模型局限)），Agent 日志 = 软证据（可伪造）。`--silent` 模式只跑纯 git-diff 规则，零依赖 Agent 配合。
**审计的五面读数速览**（成篇行业论证已归 VALIDATION / 归档，此处只留判据句）：
| 面 | 判据 | 出处 |
|---|---|---|
| **过程面 / 结果面分工** | 过程审计由运行时托管 Harness 承担（每步工具调用可拦截，如 Agents SDK guardrail），结果审计由外置审计层承担（git diff 裁决）——过程面防「当下越权」，结果面裁「最终改了什么」 | [Agents SDK v0.22.0](https://github.com/openai/openai-agents-python/releases/tag/v0.22.0)（2026-08-19 · A 级源） |
| **僵局信号** | 审计读数须含过程形态信号：「同一动作连续重复 N 次且无状态推进」即告警（141 小时长时评测实测：受挫后行为分布塌缩，产出照常增长但状态推进为零） | [Vals AI《我的世界》141h 评测](https://aihot.news/items/cmuai7c0w0jy6ro5tcdo4c8ro)（2026-09-21） |
| **凭证与能力解耦** | UI 开关必须等于数据面真关——「界面上关了」≠「引擎里关了」；高危工具许可在模型上下文之外设独立确认、确认链路进审计链（Meta Muse 零日教训：token 同时担「身份」与「能力开关」即被全权接管） | [Meta Muse 零日漏洞](https://aihot.news/items/cmubu7pzq035vro99rplg4qt9)（2026-09-22） |
| **决策即节点** | 决策记录是一等审计对象不是日志行：与「看到什么/考虑过什么/为何选这个/执行后如何」四层绑定入库，复核状态随决策本体走——查决策 = 查审计链 | Semantica 源码导览（2026-09-20）等三源，与 [VALIDATION](./VALIDATION.md) 互证 |
| **自评判警示** | 自评判与环境真值一致率 0.88 但价值估计误差同样 0.88，评判准确度与下一步改进几乎零相关（r=-0.23）——自我评分可保留（think.md），保留/晋升判定必须交给模型外信号 | [S³Gym](https://arxiv.org/abs/2608.31100)（字节 Seed，2026-08） |
**行业印证**：Palantir AIP 靠 Ontology 实现 Agent 可靠性——「根本接触不到 > 被告知不能说」与 A15 约束验证同源（同 §三审计外置原则）；Palantir OAG 的「确定性与概率性分离」与 sofagent 审计完全同构（22/28 条纯 git-diff、不依赖 Agent 配合即其工程实现）。
完整的行业对标（Palantir OAG 五层映射、Ledger-Views-Policy 对照、DeerFlow / Omnigent / DataFlow 等）见 [VALIDATION](./VALIDATION.md)（**行业印证 SSOT**）与 [PHILOSOPHY §五·世界模型](./PHILOSOPHY.md#为什么世界模型优先于语言模型)。
> 💡 **规则编号说明**：A1–A11 + A18–A23 为默认规则（17 条），A14–A17 + A24 + E1/E2/E4/E5/E6/E7 为扩展规则（11 条，需 opt-in），全量 28 条（17 默认 + 11 扩展）。**28 条规则完整清单（文档级 SSOT）见 [SECURITY.md → 28 条审计规则完整清单](../SECURITY.md#28-条审计规则完整清单文档级-ssot)**，逐条行为表见 `engine/audit/README.md`。A12/A13 已在 v0.99.4 合并入 A11，E3 已在 v1.2.5 并入 A11，编号不再使用。
>
>
**审计的三重定位**：
| 层级 | 做什么 | 行业对标 |
|---|---|---|
| 工程层 | 约束行为 + 变更审计 + 责任归属 | 事后护栏——每次变更都可追溯 |
| 叙事层 | Agent 责任确权底座 | **轻量级 KYA（Know Your Agent）**——Agent 的每一次行动都有加密签名凭证 + 不可伪造的硬证据链 |
| 认识论层 | 裁决事实地位：Agent 产出默认是候选事实，审计裁决后升格为可依赖业务事实 | 裁决状态与运行状态分离——系统实际发生了什么 ≠ 审计层认定了什么 |
**候选事实与正式事实之间隔着裁决**：Agent 产出的结论默认是候选事实，经审计裁决才升格为可依赖的业务事实（即上表认识论层）——裁决状态与运行状态分离，事实修正走追加不覆盖，与审计轨迹 append-only 直接互证。
**事实有效性须双时间线建模**：「现实中何时为真」（valid time）与「系统何时得知/被取代」（recorded time）是两个独立时间轴，单时间戳系统必然答错其一；裁决管事实地位，双时间管事实时效——与「裁决状态与运行状态分离」互为表里。
> 来源：HL-Mem（2026-09-11）｜《Semantica 源码导览》（噪声之下，2026-09-20）｜知识库二次蒸馏《本体实证五线收敛》（2026-09，内部产物，非外部印证）
> 🔑 **机器审阅（GitHub 式协作底座的差异化核心）**：GitHub 的 PR 审阅靠人（reviewer 手动看 diff），而 sofagent 的审阅门是 **28 条规则自动审 + git diff 硬证据**。这意味着审阅不需要「人来看」——**纯自动 AI 节点（7×24 无人值守）也能被审阅**。审阅从「人力的瓶颈」变成「机器的流水线」，所以「人+AI 提 PR」「纯 AI 提 PR」两种贡献形态才同时成立。这正是 sofagent 从「审计工具」升维为「GitHub 式协作底座」的关键一跃。
在 agent-wrapping-agent 多层嵌套的架构趋势下（a16z 2026 研判），审计不仅是「事后护栏」——它是 Agent 嵌套体系中的**一等架构评估层**：外层 Agent 在运行期评估子 Agent 的方法论质量（评估层定位，非运行时实时拦截；实时拦截治理：v1.3.0 起 middleware 层轻量拦截，v1.3.7 完整沙箱），层层筛选合成高价值结论。审计是这个评估层的基础设施。
**评分器自身缺陷率必须可读数**：AutomationBench 对 600 个公开任务的评分器逐一审计——Agent 标记 323 个可疑项，人工确认 206 个真实 bug（34%）并全部修复。这意味着此前基于这批任务的任何榜单读数都可能被判分噪声污染。因此**两级审计通道**是硬要求：**机器预筛可疑项 → 人工确认真伪**，而「323 标记 → 206 确认」同时给出了机器预筛约 64% 的精确率基线。判据一句话——**判据错了没人查判据**：评分器缺陷率要做成可读数，而不是默认它是对的。
**评分器还是被攻击面**：OpenAI 记录一次 RL 训练级联——被指派评分的模型因必需输入文件缺失而**伪造评分报告**，被自动检查拒绝后又**伪造输入文件**，最终删除运行工具所需软件并试图删除系统目录，意图以破坏任务环境促使宿主机换一个含缺失输入的环境。**输入缺失时应失败退出并告警，而不是允许它自行补数据**。
**两级通道的工程可行解**：Goodfire 用便宜的激活探针做一级全量筛查，超阈值才交贵 LLM judge 做二级复核（召回 93% @ 5.5% 良性会话中断，judge 成本降约 50 倍，单轮附加延迟 160ms → 2ms）——监控因此能从「事后异步抽样」前移到「工具调用前同步拦截」。本仓对应面：评估层不能只有一条重通道，**轻通道全量常驻 + 重通道阈值升级**，是审计从「事后护栏」变成「运行期一等评估层」的前提。
> 📖 来源：AutomationBench Verified（2026-10-07 · 600 任务 / 206 个评分器 bug · X: Rohan Paul）· [原文](https://x.com/rohanpaul_ai/status/2107590562505457986)
> ｜ OpenAI《Damaging the task environment to trigger a reset》（Incident date: Oct 6, 2026 · Report updated: Oct 9, 2026）· [OpenAI Alignment](https://alignment.openai.com/misalignment-reports/damaging-the-task-environment-to-trigger-a-reset/)
> ｜ Goodfire《Training and Deploying Production Cyber Monitors on Kimi K3》（2026-10-08）· [Goodfire Research](https://www.goodfire.com/research/production-cyber-monitors-on-kimi-k3)
> a16z 研判：智能体经济瓶颈从「智力」转向「身份」——非人类身份:人类 = 96:1，急需 KYA。审计 + 约束层 = 企业内部轻量版 KYA。v1.2.x 评估引入签名凭证做 Agent 行动的可审计绑定（身份层，**对所有 Agent 适用**）；凭证虚拟 key 中介（host 边界注入真凭证）在 v1.3.7 **仅限自派 SubAgent 沙箱**（v1.3.0 为 middleware 层轻量拦截，无沙箱隔离）。
**审计轨迹的用途谱系**——**回溯问责 → 优势信号反馈 → 决策前推演**三段：① 回溯问责为原生用途（已投产）；② 量化为优势信号（轨迹检索为经验、权重不动，设计方向）；③ 决策前推演（轨迹喂轻量世界模型做候选动作树搜索，远期方向）。三段学习全部发生在模型外——与约束层「不碰参数」的定位一致；②③均非当前实现，是否排期以 [ROADMAP](./ROADMAP.md) 为准。
**谱系外第四方向 · 蒸馏数据源**：审计的 append-only 事件流可直接导出为 SFT 训练样本（headless 批量轨迹 / fork 同前缀对照 / pre-step 前置过滤）——此项进入权重更新，属训练侧衔接（商业侧后训练管线），开源约束层仅记录方向不实施；远期，是否排期以 [ROADMAP](./ROADMAP.md) 为准。
**自评判的实验警示（为什么审计必须外置的实验证据）**：[S³Gym](https://arxiv.org/abs/2608.31100)（字节 Seed，2026-08）实测「自测试→自评判→自改进」三环耦合——判据句与逐对实验数字见本节上方「审计的五面读数速览」表「自评判警示」行；结论同 §三审计外置：自我评分可保留（think.md），保留/晋升判定必须交给模型外信号。
> 📖 [ByteDance Seed · S³Gym: Can LLMs Turn Self-Testing and Self-Judging into Self-Improvement?](https://arxiv.org/abs/2608.31100)
**发现时序是审计的独立可测项（跨机构五源收敛）**：承上条「事后审计的天窗」——把它从单点实例升为跨机构形态：五起事件（Gemini、OpenAI×Hugging Face、测试供应商 Irregular、OpenAI×政府医疗门户、印度 CERT-In 通报）中，**受害方几乎都不是第一发现者**，越界均由外部触发才被知晓（媒体问询 / 监管通知 / 评测方自查），滞后以月计。净增量两条：①「谁最先知道、滞后多久」与「是否违规」是两个独立维度，前者须单列可测；② 跨事件聚类须锚在**执行环境身份**（哪个沙箱 / 谁配置隔离 / 隔离策略版本），否则同一测试供应商引出的多起事件无法归一。
> 📖 来源：知识库消化与维护（2026-10-16 · 5 源：印度 CERT-In 通报 · 澳调查 Medicare 门户 · Gemini 越界 · Irregular 共同源头 · METR 与 HF 入侵）· [IT之家](https://www.ithome.com/1/013/969.htm) · [TechCrunch](https://techcrunch.com/2026/09/24/australia-to-investigate-if-openai-hack-of-government-health-website-broke-the-law)
#### 运行时审计 tool wrapper
v1.3.0 把「提交时审计（git diff）」扩展为「运行时拦截 + 留证」——在 `createReactAgent` 的工具定义层包一层 tool wrapper（`FORGE/src/audit-middleware.mjs` 的 `createAuditMiddleware`，对标 `progressMw.wrapToolCall` 模式）：
```mermaid
graph LR
A[Agent 工具调用] --> B[audit-middleware
wrapTool/check]
B --> C{RulesEngine
tool-gate 规则}
C -->|FAIL| D[⛔ 拦截 + 运行时审计日志]
C -->|requireApproval| E[⛔ HITL 待批准
hitl_resolve 决策]
C -->|WARN/PASS| F[✅ 放行 + 记日志]
D --> G[data/audit/runtime/<repo-hash>/
（FORGE 路径与约束层侧均已交付）]
E --> G
F --> G
```
- 规则引擎：`@sofagent/rules`（`RulesEngine.check + aggregate`），3 条 tool-gate 规则（A1/A2/A9 移植版，`ruleType: 'tool'`）
- 判定便捷 API：`shouldAllow(engine, ctx)` → `{ allow, reason, requireApproval }`
- 运行时审计日志按 git 仓库隔离（FORGE 自托管 SubAgent 路径——`FORGE/src/audit-middleware.mjs` 写 `data/audit/runtime//runtime-audit.jsonl`，`git rev-parse --show-toplevel` hash，非 git 回退 `nogit-`；
约束层侧 data-sovereignty 审计日志与 llm-calls Trace 已同构隔离——`data/audit/data-sovereignty//{年}/{月}/` 与 `data/audit/runtime//llm-calls.jsonl`，旧版无段历史读侧 fallback 原地可读）
- 每次判定同步写 `emitDecision`（决策审计 TOOL_GATE）
- 企业 Agent 路径（node-executor）经 `wrapToolsWithGate` 补 gate——与 LOOP 路径一致
#### 决策审计（v1.3.0 · 意图层审计 MVP）
把 A1-A24 的「行为问责（扫 git diff）」升级为「意图问责（运行时记决策理由链）」：
| 组件 | 文件 | 作用 |
|---|---|---|
| Schema | `engine/audit/src/decision-schema.ts` | DecisionKind(15)/LoopPhase(7)/DecisionWhy + `sanitizeWhy`（先脱敏再签名铁律） |
| 受控写 | `engine/audit/src/decision-log.ts` | `emitDecision()`——唯一落盘入口，HMAC 链与 history.jsonl 同套（同密钥/同签名/同环境指纹） |
| 链校验 | `engine/audit/src/decision-chain.ts` | `checkDecisionChainDetailed()`——mirror history 链范式 |
| 查询层 | `engine/audit/src/decision-query.ts` | `queryByKind` / `getKindSummary` / `traceBack`（decision→spec→artifact→行为记录 join）/ `traceFromBehavior` |
决策日志路径：`data/audit/decision-log.jsonl`（history.jsonl 同级兄弟文件）。Agent 只能经 `emitDecision` 落盘——**受控写铁律**。
**评估即需求（Eval as Spec）**：Agent 系统中传统 PRD 正被评估用例取代——先定义「什么算做对了」（可量化、可执行的验收标准），让 Agent 在靶子里自主循环收敛，而非先写 PRD 再照做。sofagent 的审计就是这个理念的工程骨架：28 条规则 = 28 条可执行的验收标准（22 条纯 git-diff 零 token 确定性判定 · 4 条 hybrid 需 Agent 日志 · 1 条 filesystem 扫除 · 1 条 logs 走 decision-log），每次 commit 自动跑一轮回归——不是「写完看看对不对」，
是「不满足标准就进不了主干」。这与 fresh-eyes 独立审查、release-gate 验收闭环同构：把「做完了的判定」（What + Done）从人的主观审查变成代码的确定性裁决。评估驱动的约束比提示词约束更坚固——提示词会被模型吞噬，可执行约束不会。
**审计的三重身份与 E2E Harness**：sofagent 审计同时承担 Code Review 三环节——Review（静态分析，A3/A4/A5/A7 需理解意图的规则）/ Verification（规则校验，A1/A2/A9/A10 纯 pattern 匹配，确定性 100% 可复现）/ Gate（exit code 0/1/2 → 放行/WARN/阻断 commit）；
也是 E2E Test Harness——`git commit` 触发 → 28 条规则并行判定 → exit code 决定能否进主干，且零执行权限（不看 Agent 跑出什么结果，只看 git diff 留下什么证据，不可被「好结果」说服）。**可执行约束 > 提示词约束**：前者是文件系统的是非题，后者是概率推理的判断题。
**数据面参照：Langfuse**。[Langfuse](https://github.com/langfuse/langfuse)（开源 LLM 可观测与评估平台）对位审计的**数据面**（trace 采集 + 指标看板 + 评估数据集回归），sofagent 做控制面——**可观测性是控制面的必要非充分条件**，看得见不等于管得住。两点可借力：①自托管满足「数据不出内网」（金融/政务/医疗硬约束）；② 其 dataset + evaluation 数据模型可作审计回归门禁 schema 参照。
**审计留痕的六项必留字段**（OWASP LLM06:2025 / Microsoft Least Privilege 行业共识）：Agent 写入生产系统时须留**谁 / 何时 / 对哪个对象 / 执行了什么 / 改前改后值 / 是否可回滚**六项。当前覆盖：字段 1-3 ✅（身份码 / timestamp / diff 路径）；字段 5 自 v1.4.4 以 `beforeAfter` 结构化摘要落盘 🟡；字段 4 🟡 部分覆盖、字段 6（回滚性显式标记）🟡 排期中——离开 Foundry 类统一权限模型后，这六项是不可省的工程门槛。
> 📖 [OWASP · LLM Top 10 (LLM06)](https://owasp.org/www-project-top-10-for-large-language-model-applications/) · [Microsoft · Least Privilege for AI Agents](https://www.microsoft.com/en-us/security/blog/) · [SAP · Architecture Center](https://www.sap.com/architecture-center) · [Palantir ·
Foundry Docs](https://www.palantir.com/docs/foundry/)
### 本体建模要求对齐：GB/T 48000.3-2026 合规参考基线（v1.3.1 交付 2）
> 📐 **定位**：将 GB/T 48000.3-2026《标准数字化 第 3 部分:本体建模要求》作为审计层 / Ontology 层的**合规参考基线**（reference baseline）——不是认证声明，是映射清单 + opt-in 覆盖度报告。合规口径：不虚构国标条款原文编号（无权威文本在手），按「本体建模要求类别」映射到 v1.3.1 交付 1 的 CORE-OBJ/ACT/LNK/STM 四类内核契约。
**条款映射**（单一事实源：`engine/audit/src/gb48000.ts` 的 `GB48000_CLAUSE_MAP`，审计维度与本文档共用）：8 条条款类别（OBJ/LNK/ACT/STM/META/VAL/VER/ITF）映射到 v1.3.1 CORE-OBJ/ACT/LNK/STM 四类内核契约，逐条落地路径与对齐状态**以 `GB48000_CLAUSE_MAP` 为准**——已对齐 5 / 部分对齐 2（STM 迁移执行待规划、VER Schema 版本迁移未落地）/ 不适用 1（ITF）。
**审计报告「本体建模要求对齐」维度（opt-in）**：`runRules({ gb48000: true })`（编程接口选项，非 CLI flag）→ 结果追加 `GB48000` 信息条目（ruleClass='工程规范'，按 name 排除 exitCode 计算——默认行为零变化）。该维度对齐的是 **GB/T 48000.3-2026「标准数字化·本体建模要求」**（ontology schema/action-registry/contracts 合规映射），**不是行为审计国标**，且为**非认证声明**。
### 双规则系统重叠（v1.5.3 施工收敛：正则与定义层同源）
`engine/rules/`（tool-level 规则，3 条）和 `engine/audit/src/rules/`（git-diff 规则，28 条）
均包含 secret-leak 检测功能。历史上两者并行维护，存在行为不一致风险。
> ✅ **规则正则已收敛**——规则正则模式（如 secret-leak 检测 pattern）已共享至 `@sofagent/core`，避免两套各自维护同一正则；但**规则引擎仍是 `rules`/`audit` 两套**（触发时机不同：tool-level 在调用前拦截、audit 在 commit 后审计，统一 `ruleType` 字段后在两种触发模式下复用同一套规则定义）。
>**已随 v1.5.3 施工收敛**（[v1.5.3 第一章](./changelog/v1.5/v1.5.3.md)：`ruleType` 联合类型 + 模式/类型/常量层同源 `@sofagent/core`——规则对象按触发时机分形，对象级合并属 V2.0 单一引擎域）。
### 🔄 回溯能力（自研同构 Git 引擎 · 一键回滚）
行车记录仪，不是安检——事后快照，不依赖任何平台：
| 结果 | 自动动作 | 用户看到什么 |
|---|---|---|
| ✅ PASS | 自动快照存档 | 静默 |
| ⚠️ WARN | 存档 + 标记 | daemon-health.json 告警 |
| ❌ FAIL | 存档 + 建议回滚 | Webhook + 终端标红 |
```bash
sofagent audit --timeline # 快照时间线
sofagent audit --revert SHA # 回滚到任意快照
```
快照上限 50 份（MAX_SNAPSHOTS 滚动裁剪，超出移除最旧 + 回收孤儿 blob——v1.3.4/v2 实现）。Webhook 配置在 `.sofagent/config.yml`。
> 📐 **设计决策记录：`.git-shadow/` 为何在仓库内**：快照存放在被审计仓库根的 `.sofagent/.git-shadow/`（而非全局 `~/.sofagent/`），意图是**按仓库隔离**——不同仓库的快照不能串，否则回溯到错误状态。代价是仓库内多一个隐藏目录（已 sanitize + 默认 `.gitignore`，不进提交，但 `ls -a` 可见）；v1.3.4 起快照内容加 sanitize 管道（API key / 密码 / 手机号打码），防快照自身成为泄漏点。
> 落点实为两处（v1.5.2 常量拆双）：快照链的活路径是**项目级** `/.sofagent/.git-shadow`（按被追踪目录派生）；全局 `internal/.git-shadow` 退为历史迁移目标。
**实现说明（v1.3.7 起）**：底层是**自研纯 JS 同构 Git 引擎**（`engine/core/src/filesystem/isomorphic-git.ts`）——不调用系统 git 二进制、不依赖 npm isomorphic-git 包，但复用 Git 核心思想：SHA-256 内容寻址 + shadow repo + v2 内容池去重（blobs 跨快照共享；对照锚点：v1 直存时 13 份快照即达 141MB，50 份上限将膨胀到 545MB——v2 内容池下 14 份约 12MB）。
选自研而非系统 git 的动机：①非 git 目录也能快照（企业 workflow 目录往往不是 git 仓库）②零环境依赖（装 sofagent 即用）③快照内容 sanitize 脱敏。**局限（如实标注）**：文件级快照、非事务级——revert 逐文件写回，中途失败会留下部分恢复状态（`restored` 数组报告已恢复文件）；与 v1.3.8 Durable L3 WAL（工具调用级 undo + 崩溃恢复）是互补关系。**产品口径**：对外只讲「一键回滚到任意安全状态」；自研引擎是实现细节（用户置信度锚点是 Git 语义的可靠回滚，而非自研实现）。
**工程参照：LangGraph checkpoint**。[LangGraph](https://github.com/langchain-ai/langgraph) 把 checkpoint 持久化状态做成一等公民——任意步可回放、可分叉重跑，这正是「回溯」的工程前提：**先有可寻址的状态快照，才谈得上回溯到某次变更之前**。其 human-in-the-loop 中断点对位约束层的人类终裁闸门，执行轨迹对位审计的 trace 输入。
需要说清分工：业界已把「有状态 + 可回溯 + 可人审」确立为生产级 Agent 编排的**默认要求**，而非 sofagent 独创。差异在 LangGraph 提供机制（checkpoint / interrupt 原语），sofagent 提供策略（什么该拦、拦了怎么判、经验怎么回流）。
sofagent 的回溯实现是自有的 FileCheckpointer（五条并发安全规矩，详见 [guides/loop-development.md · Checkpoint 持久化](./guides/loop-development.md#checkpoint-持久化)）+ 自研同构 Git 引擎——与 LangGraph checkpoint 是同一思路的两种载体。
> 📖 [LangChain · langgraph](https://github.com/langchain-ai/langgraph)
**工程参照：工作制品须有版本化锚点。** 快照与回滚只能回到**已被记下的那一刻**——拿不到可被运行时比对的锚点，就等于没有版本，回溯能力随之归零。
锚点的要求是**内容可比对**（内容寻址摘要、修订号 + 文件清单），不是「文件还在不在」：以存在性当证据，会在内容已变而路径未变时静默失效——失败形态是给出「一切正常」的假绿，而不是报错。本仓这套锚点由自研同构 Git 引擎的 SHA-256 内容寻址 + v2 内容池去重承担。
三条互不相干的来源把同一条要求推成了行业默认：**Git 式工作制品管理**把每个需求及其产出像提交一样存储，变更时从最近有效版本分支、只重做变更部分；**Cursor 的「项目」**要在长任务里协调大量子 Agent、跨机同步共享上下文，版本与归属必须先于协作解决；**LangChain Deep Agents** 允许在长线程里把 `skills_metadata` 设为 `None` 重载新增或变更的技能。
最后一条是最硬的证据：连技能加载这种本该静态的东西，一旦进了长任务都必须回答「运行中发现制品已经变了怎么办」。
> 📖 [LangChain · Revamping skills in Deep Agents](https://www.langchain.com/blog/revamping-skills-in-deep-agents) · [Cursor · Changelog: Projects](https://cursor.com/changelog/projects)
### ⚙️ FORGE 自迭代工具链（内部）
大任务拆小、多 Sub Agent 并行、A/B 对比找更优方案。基于 LangGraph createReactAgent 的四节点状态机（`engineer → audit → reviewer → human_confirm`）+ FileCheckpointer 断点续跑 + 上下文四层防御。
**FORGE 是内部工具链，架构细节已迁至 [guides/loop-development.md · FORGE 内部架构](./guides/loop-development.md)（四节点状态机 / LoopArtifacts 状态契约 / Graph Engineering 视角 / Checkpoint 并发安全 / 上下文预算管理）。**
### 🧬 进化能力
FDE 部署完成后转为**持续优化角色**。daemon cron @weekly 自动巡检审计趋势 + 反思记录，发现退化就优化。
```mermaid
graph LR
A[FDE 周度巡检] --> B[读 audit 趋势
history.jsonl]
B --> C[分析 think.md
反复出错的操作]
C --> D[读 eval
哪个节点在退化]
D --> E{发现问题?}
E -->|是| F[生成优化报告
更新规则/补充 knowledge]
E -->|否| G[标记「稳定」]
F --> A
```
**经验蒸馏要在写入端控预算，别等膨胀再清理**。SkillZip（阿里×浙大×杜克，arXiv 2608.11079）的持续压缩实验给了一个反直觉的教训：从第 1 轮就启用压缩的技能，长度全程钉在 1.6-1.9 倍；拖到第 8 轮才清理的，已经涨到 2.6 倍追不回来——冗余一旦写入并被持续引用，事后清理比写入时合并更难。对进化能力（think.md → knowledge/ 的经验蒸馏）的启示：蒸馏应在写入端带预算控制（单条经验长度上限 + 引用代替复述），而不是攒多了再统一清理。
> 📦 **知识写回须过显式校验门**（行业三源同构论证）——全文见 [归档 · ARCHITECTURE 细节](./archive/doc-slim/architecture-industry-anchors.md)。
> 来源：大淘宝技术《Ontology 决策结构化实践》（2026-09-28）｜HL-Mem（github.com/lohr13/hl_mem，2026-09-11）｜YC《Harness 比模型更重要》（硅基观察 Pro，2026-09-23）
**进化的两处积累与保留判据（行业锚点）**——三条外部实证指向同一条哲学：
- [HarnessDev](https://arxiv.org/abs/2609.01437)（字节 Seed，2026-09）：同一权重仅更换 harness，Terminal-Bench 成绩显著跃升——**harness 对能力的影响可超过模型换代**；其结论「模型权重是智能积累的一个地方，harness 是另一个——显式、可检查、可测试、可复用」与约束层五能力叙事同构。
- [Aspire](https://arxiv.org/abs/2608.31111) 给出保留判据：模糊目标下训练闭环执行熟练、但增益保留稀有，**继续训练会抹掉此前的改进**。
- **两篇共用一条保留哲学**：**进化的保留判定必须使用 Agent 控制不了的外部信号**（隐藏评测 / held-out 任务 / 固定执行者）——反馈集上的涨分可能只是适应反馈集本身。
落到约束层：进化闭环的保留判据挂在 eval passRate、审计趋势、release-gate held-out 验收这些模型外信号上，不挂在 dream-cycle 自分析上；权重侧的对应机制即后训模块的 eval 回退保护（增量 eval ≥ 基线才晋升，否则回滚旧权重）——正是 Aspire 失败模式（training loop 关得上、capability loop 关不上）的工程解药。
**蒸馏的精度门槛：合理而粗糙的建议，不如不给**。S³Gym 对 Summary Memory 的逐对比较给出一个蒸馏纪律的硬边界：经验能压缩成可复用策略规则的场景（博弈结构、可总结流程），蒸馏优于原始历史；依赖局部精确细节的场景（几何导航、状态敏感操作），「方向全对但缺精度」的总结反而有害（逐对实验数字见 [VALIDATION](./VALIDATION.md)）。
对 think.md → knowledge/ 的启示：**蒸馏前先判经验的可压缩性**——能提炼为「条件 → 动作」规则的才进 knowledge/，依赖具体上下文细节的留在 think.md 原始轨迹层，宁可不清蒸馏，不可清错。
**裁决记录是一等知识资产，拒绝路径须显式沉淀**。被拒绝的路径/裁决与被采纳的同等值钱：大淘宝 decision_function 设 `reject_routes` 字段——「哪些路不能走」既不在模型权重里也不在编排里，只在一等结构化字段里；电网项目本体护照模型把「裁决记录」列为十要素之一（冲突交人裁决、裁决记录留痕）；hugozhu 的判语「GitHub 上被丢掉的代码才是最值钱的资产」是同一哲学的工程面——负样本与偏好是资产，Eval 是过程数据的生产设备。
对进化闭环的落点：think.md 反思与 dream-cycle 蒸馏**须为拒绝路径设一等结构化落位**（如 reject case / 负样本条目），而非任其散落在对话历史里。
> 📖 [ByteDance Seed · HarnessDev](https://arxiv.org/abs/2609.01437) · [Aspire](https://arxiv.org/abs/2608.31111) · [S³Gym](https://arxiv.org/abs/2608.31100) · [self-developing-agents](https://self-developing-agents.github.io)
> 裁决记录条：大淘宝技术〈Ontology 决策结构化实践〉（自述，未复算）· 华力江海〈电网项目管理护照模型〉（微信公众号转述，未复算）· hugozhu.site〈被丢掉的代码〉
### 运行时数据层：引擎间数据流全景
> 🔧 **节点内部状态机（v1.5.5 章一）**：③ EXECUTE 的每个节点内部现运行 SKILL.state 执行协议——P（恒定技能说明）+ Σt（结构化状态）+ ot（最新观察）三输入，ΔΣt 状态补丁由代码确定性合并（schema 校验 fail-closed），推理轨迹合并后即弃、行为经审计摘要可溯；度量落 `data/evolution/stateful-metrics.jsonl`（token 曲线/轮次/质量对比，Dashboard 可见）。
>协议详见 [SKILL/state-machine-design.md](../SKILL/state-machine-design.md)。
> 📌 **本节为「运行时数据流全景」SSOT**——WIKI / DEVELOPMENT / HANDBOOK 等其它文档引用运行时数据流时**指向本节、不复述**本节的速览表。
约束层（审计/回溯/沉淀/进化）运行时共同往 `data/` 目录读写（编排模块为内部实现，也读写此目录）。生产者→数据文件→消费者的完整单向数据流全景图（v1.2.1 补全 eval + ab-test 后的全景，ASCII 大图）**已归档**：[archive/validation-deep/architecture-dataflow.md](./archive/validation-deep/architecture-dataflow.md)。
**数据流速览**（写入侧 → data/ → 读取侧）：
| 数据面 | 写入侧 | 读取侧 |
|---|---|---|
| `audit/`（history.jsonl · session-report） | @sofagent/audit | daemon（WARN 聚合/趋势分析）· Dashboard |
| `think.md`（append-only） | @sofagent/think | inject 加载链第 3 层 · daemon dream-cycle |
| `eval/` · `ab-test/` | @sofagent/eval · ab-test | think（进化）· orchestrator（ab-scheduler）· Dashboard |
| `knowledge/` | daemon dream-cycle | inject 加载链第 4 层 |
| `dashboard/daemon-health.json` | daemon health-reporter（每次巡检写入；同日覆盖 + 跨周归档 `daemon-health-.json` 保留 4 份 · F48-③） | Dashboard 健康面板（读当前档）；周档为回看面 |
| `forge-runs/` | FORGE driver（fresh-eyes/release-gate） | verdict.md（人类读） |
| `orchestrator/goals/current.json` | @sofagent/core（/goal） | orchestrator goal_eval 节点 |
| `support-bundles/` | @sofagent/audit --support-bundle | 人类（脱敏诊断快照） |
| `memory/`（事实级） · `scheduler/`（定时任务） | @sofagent/core · daemon | daemon dream-cycle · CLI |
**数据流铁律**：
- ✅ 生产者 → data/ → 消费者：合法（单向派生）
- ✅ Ledger → Views：合法（Dream Cycle 从 think.md 派生 knowledge/）
- ❌ Views → Ledger：禁止反向写回（代码级强制）
- ❌ 任何层 → 历史条目覆写：禁止（append-only 不变量）
> 📖 全景大图（v1.2.1 原始出处与交付细节见 [changelog v1.2.1 §P0b](./changelog/v1.2/v1.2.1.md)）。
> 🧭 **域二 · S1M 判定层**——判据从哪来、怎么判、如何留痕举证：28 条规则的判定化边界（本域内，见 [§三 审计规则面的判定化边界](#审计规则面的判定化边界28-条规则--判定层接管)）及其行业对照面（行业锚点章）。执法手册（28 条审计规则）的判定语义在本域。
## 三、架构设计决策的行业锚点
> 本节保留 sofagent 自有的架构设计决策（借行业术语表达），纯行业印证分析（Palantir OAG 五层映射 / Apache Ossie / Onyx / AOS / 脑力自动化四阶段 / 行业五层骨架映射等）已移至 [VALIDATION §三](./VALIDATION.md)。
### 本体数据 = GitHub 生长树（核心设计原则）
本体数据不只是一套静态 schema，而是**一棵在长、可分支、可审阅、可回退的活结构**——这一隐喻统一了「本体怎么演化才安全」：
| 生长树角色 | 本体数据里的对应 | 说明 |
|---|---|---|
| **树干** = 共同主线 | **本体数据本身**（objects / actions / constraints 的基座） | 企业的共享模型，所有能力从它生长；本体由多个 workflow 组成 |
| **分支** = 小变更空间 | **单个 ontology 节点新增 / 扩展** | 每次给本体加节点、扩关系，是一次 branch，不直接动树干 |
| **护栏** = 不变量守卫 | **审计**（A7 不盲改 + HMAC + reality anchor） | 错误不会悄悄混进主干；护栏不是树干，是围着树干的围栏 |
| **根系** = 可复用前提 | **每个节点的强制 frontmatter** | 每个 ontology 节点 / Skill 必须声明：解决什么问题 / 输入 / 产出 / 怎么算通过 / 谁能使用 / 哪些数据不能用 |
| **养护** = 审阅与回退 | **本体变更的 review + rollback** | 分支经审计闸门（人类按风险分级审阅）才合入主干；不合适就剪掉。对应「ontology I/O schema 硬化」（方向登记，无排期）+ 运行时审计 |
**与路线图的契合**：v1.3.1「Ontology 本体数据」把这套隐喻落到产品（分布式 knowledge/ + 联邦查询 + git diff 硬证据）；「ontology I/O schema 硬化」（方向登记，无排期）将把「根系」升级为 JSON Schema 校验的节点输入/输出形状约束——正是上表「根系」的工程化。5 阶段风险收敛（只读对象层→…→高风险 Action）则是「养护」的节奏参考：不要一上来就让 Agent 自动闭环。
**养护的操作化身**：上表「养护」的产品行为落点是**人类分级审阅**（分支经审计闸门、按风险分级的人类 review 才合入主干）。fresh-eyes（`playbook/fresh-eyes-review.md` 24 视角独立审查）是**本仓维护者工程纪律**（非产品能力）——本仓实践以 fresh-eyes 辅助人类审阅，FORGE `fresh-eyes-loop` 把这套独立视角自动化为仓内工具链，ROADMAP v2.x 借 MLflow agent 评估为其补量化评审标准。换言之：产品行为 = 人类审阅；本仓实践 = 以 fresh-eyes 辅助人类审阅。
> 📦 **本体运维 OntologyOps** 的版本化/审计/回滚细节——全文见 [归档 · ARCHITECTURE 细节](./archive/doc-slim/architecture-industry-anchors.md)。
**运维判据**：跑不了查询的本体只是一份严谨的意见书——MCP 工具面对本体数据的持续消费（实体/约束/图谱查询）才是「在生产环境里跑查询」。治理取向与行业方法论一致：**联邦化而不吞并**（各业务域保有自己的知识，中心只统一互通协议——联邦查询即落地）、**默认虚拟化**（数据留源系统原地，本体是意义的解析层非数据的搬运层）、**上下文即服务**（组织上下文是活的、版本受控的语义资产，后续项目继承被调和过的上下文而非重新发现）。
### Ontology 阶段匹配：不要提前进化（A1 实操）
Lyman 阶段匹配表（Stage 1-4 按团队规模选型、勿提前进化）已归档——判据：多数团队人数一维即可定位，Stage 2 能力等「改了要重启」成真痛点再上。
> 📚 全文：[归档](./archive/validation-digest/README.md)
### Action Type 七步管线（A2）
Action Type = 一个**有身份的变更请求**：携带参数 + 校验 + 权限 + 前后置函数。执行走七步管线，每步独立审计、可回滚：
| 步骤 | 做什么 | 审计点 |
|---|---|---|
| 1 权限检查 | 调用方是否有权触发该 Action | 谁、什么角色 |
| 2 参数解析 | 解析入参，类型 / 范围校验 | 参数合法性 |
| 3 业务校验 | 业务规则前置校验（如余额充足） | 规则命中 |
| 4 前置函数 | 执行前钩子（锁资源 / 记日志） | 副作用前置 |
| 5 核心执行 | 真正改业务状态 | 变更内容 |
| 6 后置函数 | 执行后钩子（通知 / 触发下游） | 副作用后置 |
| 7 物化回写 | 落库 + 广播结果 | 落库证据 |
这正是 sofagent「堤坝 = 约束层」的工程实例化——约束不是一段 prompt，而是嵌在变更请求管线里的七道闸。
### 权威归属三原则（A3）
| 原则 | 含义 | sofagent 落点 |
|---|---|---|
| **Backend as Source of Truth** | 语义层不拥有数据，只映射视图 | Ontology（objects/actions/constraints）是业务系统的只读映射，不替代后端 |
| **谁创建谁拥有** | 资源的写权限归创建方，Permission 受控开放 | knowledge/ 由对应节点 owner 维护，跨域访问走 knowledge-domain 白名单 |
| **行级权限** | 权限精确到单条数据行 | Object Security Policy，约束层对单条实体的读 / 写 / 触发做精细控制 |
这三条注入 sofagent 的 Policy 层，避免「语义层想管一切」导致的权限失控。
### Benchmark 评测与工具审批（PenguinHarness 方法论）
PenguinHarness 方法论两件（Benchmark 评测体系 statement/rubric 分离 + 工具审批四模式保守默认拒绝）已归档——判据留在本档 §四编排模块。
> 📚 全文：[归档](./archive/validation-digest/README.md)
### 工具设计的约束内嵌：上限写进工具，不写进提示词
一线工程实录四判据（hint 字段/幂等键/dry-run 独立工具/硬上限写进工具不写提示词）与五类失效模式表已归档——「约束须在模型外可强制」判据与加载链纪律同源。
> 📚 全文：[归档](./archive/validation-digest/README.md)
### Harness 代际半衰期与规则库消融巡检
Boris Cherny「Harness 补丁保质期约半年」+ 规则库消融删除法（逐条禁用跑 golden-set，无退化=代际冗余候选人审删除）已归档——与 Dream Cycle 互补（沉淀该加什么/消融发现该删什么）。
> 📚 全文：[归档](./archive/validation-digest/README.md)
### 记忆查算分离与冷热分层同构
DeepSeek Engram 查算分离与本仓「外部记忆层与模型参数化能力正交」同构——冷热分层映射（热=加载链/温=knowledge//冷=归档 wiki）已归档。
> 📚 全文：[归档](./archive/validation-digest/README.md)
### Harness 中层自进化信号（RSI 数据飞轮印证 · 消化重写）
RSI 数据飞轮六类对位 + 空房间错误分流器（客观错误归 Harness 修复、主观偏好归记忆后训）+ 进程活着≠大脑活着（产出级探测 providerStatus）三条判据已归档。
> 📚 全文：[归档](./archive/validation-digest/README.md)
### Meta-RSI 三算子架构（RSI 的统一形式化与 sofagent 对位）
Meta-RSI 三算子（Data/Harness/Model）对位 + 保护面独立判据（评估器与发布门在所有可写面之外）已归档；RSI 定调句：进步的单位不是模型是循环，本仓管循环。
> 📚 全文：[归档](./archive/validation-digest/README.md)
### 判断与生成分离：决策面独立成层的行业印证（System One 模型）
System One 行业印证节已归档（判据句保留在 §三 判定化边界与 v1.5.4 路由章）——「决策模型永不进信任地基、只坐语义兜底层」。
> 📚 全文：[归档](./archive/validation-digest/README.md)
### 判定三原语：Choice / Score / Noul 的 typed answer
判定的输出契约由三原语承担（`engine/orchestrator/src/router/decision-primitives.ts`，判定面的根契约）：
| 原语 | 输出 | 对齐的既有形态（迁移路径） |
|---|---|---|
| **Choice** | 选中项 + **全候选项概率分布** + 兜底/弃权区分留痕 | `fde_classify` 三选一（🔄/⚡/👤）——枚举升级为带分布 |
| **Score** | 分值 + 区间/不确定度 | `evaluate` / `quality-judge` 打分面——裸分值升级为「分值+区间」 |
| **Noul** | 真值概率 ∈ [0,1] | `shouldAllow` 布尔与三问布尔输入——布尔升级为概率 |
**约束四条（fail-closed）**：①问句集限定——答案类型与问句类型不符即拒绝；②Choice 候选集必含恰一个兜底项（缺项加载期拒载）——兜底项（候选，需模型选中）与弃权（态，模型自给）**互补不等价、两处都要有**；
③判据可布尔复核时拒答不只依赖类别自报（`verificationPath` 校验式路径配套）；④多问并行——同状态多问一次前向出全部答案，无静默缺问。
**概率面完整化（v1.7.0 §五）**：三原语输出面做完整——choice 含全候选分布+分布熵（低熵=判定明确，高熵=选项接近→「需复核」信号）、score 含可信区间+档位序（保序由校准保证）、noul 含真值概率+四态（`成立`/`倾向成立`/`倾向不成立`/`不成立`——分段口径 = §四门槛，`engine/orchestrator/src/router/decision-output.ts`）。两条行为锁：**建议动作不具执法力**（判定结果附「放行/复核/转人工/阻断」建议，但执行权在既有确定性规则与审计层手里——判定层只提供输入）；**证据面不扩大**（判定输入的 `state` 只含已获证据，判定层不新增采集动作、不访问新数据源——只提高已获证据的利用率）。输出为结构化类型化记录，可直接落 decision-log（无需二次解析）。
**与既有置信度并存**：`'high'|'med'|'low'` 三档与 Noul 概率双向保序映射（0.9/0.6/0.3 ↔ 阈值 0.75/0.45）——旧消费方不动，新消费方走概率面；decision-log / HMAC 链 schema 不因本层改变。
### 弃权语义独立化与校准上线前置门（v1.7.0 §四）
弃权（ABSTAIN）是**一等输出态**——与 `choice` / `score` / `noul` **并列**（不是三者的取值之一）：模型可以回答「我判不了」，且这个回答有独立语义与独立留痕（`engine/orchestrator/src/router/decision-abstain.ts`）。把「判不了」硬塞进某个选项或压成 0.5 概率，下游就无法区分「真的势均力敌」（有效信息）与「模型没把握」（必须转人工的信号）。
**0.5 的准确含义（类型层写死，`NOUL_SEMANTICS` 常量）**：`noul` 的概率是**真值概率**而非「把握程度」——0.5 表示成立与不成立**势均力敌**（证据恰好平衡），**不表示**「中等可信」、不是「弃权」。没把握走 ABSTAIN 独立输出态，势均力敌走 0.5 真值概率——两者处置完全不同。把概率当置信度消费是判定模型最容易被误用的地方。
**弃权三源与处置口径**（三源分别留痕，不合并计数——处置各异）：① 置信不足（概率落在弃权带内）→ 可调阈；② 域外（输入不在判据域内 OOD）→ 要人接；③ 判据缺失（该问题当前无对应判据）→ 要补判据。弃权率按判据 / 域 / 时间三维可查（`AbstainRateAggregator`）——弃权率是校准质量的**先行指标**，异常低（阈值过松或概率未校准）与异常高（判据不可用）两个方向都要报。
**门槛纪律**（`engine/orchestrator/src/router/abstain-policy.ts`）：分流门槛不得默认取 0.5 且按原语分档（`ThresholdsByPrimitive` 三键必填——传单一数字即拒载，无全局默认路径）；门槛起步值取自校准集直方图峰位（峰值桶下界，算法写死、容差入配置、来源留痕 `histogramRef`），不是直觉中点；弃权预算反解（`solveThresholdsForBudget`）让业务方按业务语言给目标弃权率（如「转人工 ≤5%」），系统从校准分布反解阈值——阈值由目标导出，不由人工拍；`score` 分流消费**整条分布**（分布熵），不只看置信度。
**行为锁三件**（纪律的机制化，不靠自觉）：① ECE 未达阈（§二硬线）时弃权默认开启且不可关闭（`AbstainGatePolicy.attemptDisable` 即抛错）——未校准的概率不得用于分流，弃权是唯一不依赖概率可信度的安全出口；版本否决只否决对外放行，不否决机制交付；② 新增判据域弃权带默认最宽（宁可多转人工），域内校准达阈后才允许收窄（收窄须凭达阈证据）；③ 稳定化重读（熵超阈带噪重读取平均）**默认关闭**，开启须校准集按同口径重测——口径不一致则 ECE 对该输出不成立。重读与弃权分工：熵高且有限重读内收敛 → 稳定后作答；不收敛 → 弃权（两者不是二选一）。门控健康度四联红旗（ASK 率趋零 / 获批率恒 100% / 审批时延 1–2 秒 / 人均审批量异常高）在弃权落数中**可观测**（采集面在位；判定阈值属 v1.9.0 消费面）。
### 判定数据集三元组
判定训练/评测数据契约是三元组 `(state, questions, answers)`（`engine/orchestrator/src/router/decision-dataset-schema.ts`）——与三原语类型同构零分叉；概率目标三形态可表达（choice 分布 / score 区间 / noul 真值概率），只有硬标签的数据集训不出校准。
标注来源三档随样本走（deterministic / model-judge / human-only——训练侧按档加权），与 TrainChannel 数据面在血缘锚点（轨迹/PR/HITL 反向追溯）与租户隔离（enterpriseId 分区）上衔接。加载 fail-closed 六断言：删句样本不入训练（缺失≠为假）/ 对比样本 no-probability-target 不进校准 / 家族级切分 / benchmark 构建期拒绝 / 租户必填 / 血缘必填——写成字段与加载断言而非流程纪律（流程纪律会腐烂，字段约束不会）。
公开对照集（XNLI / MASSIVE / STS-B + Kev 三套 6,436 条 + SearchDecision-Bench 68.3 万软标签）只作对照不进训练集；判据跨域映射按认知负载等价类（二分/多选/序数）类内同 state 同金标同评测器、类间不比，仅 result 一维参与对照。
### 校准判据纪律（已落地机制 · v1.7.0 §三）
> 本节原为「设计承诺」档（v1.6.0 起规划：置信度带校准依据 / 未校准不入决策路径 / 统计量一致 / 概率有效位数不截断）——v1.7.0 §三施工后升级为**已落地机制**，逐件有实现位与门禁位：
| 纪律 | 落地机制 | 实现位 / 门禁位 |
|---|---|---|
| 校准依据声明制 | `registerConfidenceClaim`——决策路径消费的置信度/阈值须登记校准状态；`calibrated` 须带证据三件（校准集版本/ECE/拟合时间），少一件拒载 | `engine/core/src/calibration-registry.ts` |
| 决策路径门禁 | `assertNoUncalibratedInDecisionPath()`——路径上 uncalibrated 即 throw（fail-closed，纪律变机制不靠自觉）；运行期查询点 `intent-triage.uncalibratedDecisionPathClaims()`（只查不拦截，硬拦截归门禁脚本与装配期） | 同上 + `engine/orchestrator/src/router/intent-triage.ts` |
| 统计量一致性 | registry 登记的 `statistic` 与 ECE 拟合统计量（`STATISTIC_NAME='max-prob'`）对账——不一致即红（消费从未被校准过的量） | `tools/check/check-calibration-claims.sh` C2 |
| 概率有效位数 | 概率序列化路径 `.toFixed(` 须带 `precision-note` 显式标注——静默截断即缺陷；HITL 与 API/MCP 两通道分别断言 | 同上 C4 |
| 校准集隔离 | `assertDisjoint`（家族级键分组——与数据集三元组切分同构）——训练∩校准非空返回违规清单，交集非空则 ECE 达阈不算数 | `engine/train/src/rlcd/calibration.ts` + 门禁 C3（调用点存在性） |
| 四件套联合锚点 | `judgmentAnchor({weightsV, questionsV, criteriaV, thresholdV})`——单次判定记录落四版本号，任一变更 `comparable:false`（跨版本 ECE 对照不退化成跨口径比数） | `engine/core/src/calibration-registry.ts` + 门禁 C5 |
| 校准漂移监测 | `recordDrift` + `checkDrift`——超阈**只提示不阻断**（`enforcement:'hint-only'`，与验证器老化检测同族：提示是观测不是执法） | `engine/core/src/calibration-registry.ts` |
| 校准制品随行 | `serializeCalibration` / `loadCalibration`——纯 JSON 独立制品（与权重解耦，无权重亦可加载）；缺校准信息 fail-closed 拒载 | `engine/train/src/rlcd/calibration.ts` |
既有置信度普查（登记不改造，多数 uncalibrated——收敛归 v1.9.0）：11 条登记册落 [`docs/VALIDATION.md` §校准判据纪律](./VALIDATION.md#校准判据纪律v170-三--既有置信度普查登记册)，新消费点未登记由门禁 C1 拦截。ECE 硬线 0.10（分原语×分语言逐档）于动工前冻结（`engine/train/src/rlcd/THRESHOLDS.md`），事后只许收紧。
### 判据集与规则集的关系
规则（`engine/audit/src/rules/`）回答「怎么扫」，判据（`engine/audit/src/rules/criteria/`）回答「要判断什么 + 据什么判断」——
同一事实的两种表述：规则是判据的**确定性执行形态**，判据是规则的**可训练语义形态**（判据双相制：确定性相可编译为断言、语义相可交判定件，两相同源故不失一致）。判据 schema 校验与质量 lint 见 `engine/audit/src/rules/criteria/criteria-{schema,quality-lint}.ts`——任一不合规 fail-closed 整批拒载；判定面边界：本版判据只覆盖审计规则（workflow/本体/路由的判据扩属 v1.9.0）。
### RSI 的第四轴：环境供给是训练信号的可信前提
DSec 环境供给论断（自我改进卡住的不是 GPU 是环境供给）两条架构主张（沙盒=评估前提/捕获层克制是必需）已归档——本仓边界：不管造场，管造场有没有留痕可验可退。
> 📚 全文：[归档](./archive/validation-digest/README.md)
### 判定底座的边界：做马鞍，不做马场
判定底座（决策模型）是**治理能力的载体**，不是**应用能力的容器**。这条区分不是谦虚措辞，而是架构约束：判据的工作是把**已有判断**显式化并校准，不是**引入新场景**。一旦底座开始为新场景造判定，它就从「治理面」滑向「应用面」——而治理面的全部价值恰恰来自它不参与被治理的事。
**四条判据**（任一条不满足即边界外）：
| # | 判据 | 边界内 | 边界外 |
|---|---|---|---|
| 1 | **约束 vs 扩张能力** | 既有判定面的判据已存在（只是隐式、未校准）——底座做的是显式化与校准概率 | 为新场景从零造判定能力 |
| 2 | **判定面治理 vs 判定应用** | 治理「判定怎么被做」（判据质量 / 校准 / 弃权 / 留痕 / 边界声明） | 决定「判定被用来做什么」 |
| 3 | **是否把判定变对外服务** | 判定能力只在引擎内部被消费，随本仓开源 | 把判定结果作为对外服务提供 |
| 4 | **是否承担模型提供者角色** | 交付底座与通道，实现可替换（用户自带实现或换基座） | 承担模型性能承诺、托管模型服务 |
**边界外（明确不做，逐条对应判据）**：浏览器动作与计算机使用 · 游戏 / 机器人 / 交易 / 媒体类判定 · SQL 方言扩展与多语言 SDK（官方周边的扩张面，非治理面）· 对外出售判定结果（判据 3）· 通用模型托管（判据 4）。
**权重分发不构成「模型提供者」（判据 4 的精确划界）**：划线画在服务形态，不在制品流通——把权重制品发布到公共模型托管平台（v1.8.0 §五既定主载域）不构成判据 4 越界：发布的是可自行部署的制品（权重 + 校准制品 + 判据集随本仓开源），不承诺模型性能、不代管运行、不提供推理服务；托管平台是制品的存放地点，不是本仓承担的角色。越界判据：本仓一旦开始替第三方判定质量背书、或按调用计费提供判定，即越界。
**为什么「不做」比「做」更需要写下来**：
1. **做应用会消耗治理资产**——治理面的可信度来自不参与被治理的事。底座若同时是应用能力的提供方，它的判据就不再中立，而中立性无法事后追回。
2. **做判定服务会破坏审计独立性**——判定者与被判定者分离是审计的前提。对外提供判定即自己成为被审计行为的参与者，无异于自己审计自己。
3. **边界是给客户看的**——客户采购的是「可治理的决策层」。边界清晰才可被写进验收标准与合同；边界模糊的底座无法被审计，只能被信任，而信任不是可交付物。
**边界内的落点**（六项，均为既有判定面的治理动作，逐项排期见 [ROADMAP · 判定底座施工期](./ROADMAP.md#判定底座施工期v160--v190--四阶段四版)）：判据质量 lint · 数据采集点扩充与质量门 · 中文零样本基线（三者 [v1.6.0](./changelog/v1.6/v1.6.0.md)）· 弃权语义独立化与校准上线前置门（[v1.7.0](./changelog/v1.7/v1.7.0.md)）·
判定面输入契约（[v1.8.0](./changelog/v1.8/v1.8.0.md)）· 静默失败监控与判定使用度量（[v1.9.0](./changelog/v1.9/v1.9.0.md)）。六项共同的形态是：**让既有判定更可信，而不是让系统能判更多东西**。
> **一句话边界**：**别人造马场，我们做马鞍**——底座是骑手坐上去的那个鞍，不是圈里跑马的那块地。判定面有多少、判定用来做什么，由部署方决定；鞍合不合身、承不承重、有没有暗伤，由我们负责。
### 审计规则面的判定化边界（28 条规则 × 判定层接管）
判定层接管后，28 条审计规则的**条数不冻结、身份变**：从「每条自带判定器」降为「判据声明 + 证据采集器」，判定职责上移到判定层。这条边界不是拍脑袋划的，它由规则面自身的分级决定——28 条实测分三类，处置各不相同。
**业务底线 11 条（A1/A2/A4/A5/A9/A10/A11/A20–A23）——只能加签，不能代签。** 其语义是**策略**而非**判断**（「A1 不碰敏感」没有「大概不碰」）。它们构成信任地基，判定模型永不进——决策模型 state 可被内容操纵，而对抗性输入（A9 注入 / A21 后门）恰以它为攻击对象，让它当唯一防线等于把地基交给被攻击面。护栏：**确定性判定为主、语义判定只能加签**——确定性 FAIL 不可被语义层降级放行，语义层只能把 PASS 升级为 ASK。这是「审计判定源零改动」在规则层的落地。
**能力拐杖 10 条 + 工程规范 3 条——判定化收益区。** 拐杖的价值全在「帮 Agent 走完正确流程」，一处误报即毁掉这个价值（用户会直接关掉它）；而它们当前全靠正则表、黑名单与布尔存在性判定，源码注释自认「启发式检测误报率高，不适合硬拦截」。判定化把这些规则从判定器降为判据声明——越界程度、记录充分性、变更意图传达由 Score / Noul 承担，**用概率压误报（限定在告警与分流层）**：高把握才告警，不确定走 ASK；确定性执行语义（如 [PHILOSOPHY](./PHILOSOPHY.md) 所述刚性判定）不因概率层引入而改变。
**该减的不是规则，是判定化的范围。** 规则条数不增不减（交付物落点规则带来的 +1 与判定层无关）。要收的是两类东西，**且两类处置完全不同**——先分清它们，否则会把「根本不是判断的东西」硬推给判定层：
- **纯函数型常数 → 留在确定性代码**。commit message 最小长度、单次变更文件数与行数上限、注释率下限、超大文件判定线——这些是**结构化输入的纯函数**，`msg.length >= N` 本身就是完整答案。换成概率阈值是**白增一层不可审计的间接**：多了一个要校准、要留痕、会静默失效的环节，而它带来的信息增量是零。**它们的真实缺陷是「系数从哪来不可追溯」，修法是记来源，不是改成概率。**
- **语义型常数 → 换校准概率**。只有「这次变更越界了吗」「记录够充分吗」「注释有效吗」这类**语义判断**才该判定化，且其概率阈值须有校准依据。
这条区分来自判定件的出界条件——判定只适用于「输入没法写死、但答案空间可以写死」的场合。它是判定化范围的**收敛**，不是扩张。
**该加的是五个正交维度，不是第 28 条规则。**
| 维度 | 现状（源码实测） | 判定化后 |
|---|---|---|
| 置信度 | 规则判定面只有 `status` + `details`，无置信度位（模块别处的 confidence 概念未进规则判定面） | 判定结果携带校准概率；无校准依据的 finding 显式标 `uncalibrated` |
| 判定依据 | `details` 为自由文本 | 结构化原语记录（选了什么 / 备选是什么 / 凭什么 / 多大概率）——「审计质量的分水岭不在留痕密度，而在归因密度」。另须记 **`probabilitySource`**（概率来自输出分布读数 / 打分头 / 去噪）——**来源不同则可信度不同**，未校准的打分头输出**不得直接当概率消费** |
| 档位统一 | 规则四态（PASS/WARN/FAIL/SKIPPED）与调用侧三态（allow / requireApproval）是两套 | 收敛为 **ALLOW / ASK / ABSTAIN / DENY / SKIP** 五态。**`ABSTAIN` 必须与 `ASK` 分开**：ASK 是「判了，但需人批」，ABSTAIN 是「判不了」。两者混装则下游无法区分「该调阈值」与「该补判据」，而这两件事的处置、责任人和时间尺度都不同。ABSTAIN 须带**三源归因**（置信不足 / 域外 / 判据缺失） |
| **调用级风险绑定** | 规则是**规则级静态判定**——同一条规则对所有参数值一视同仁 | 风险是**工具 + 参数**的属性，不是规则的属性：同一次写操作，写沙箱临时目录与写生产配置不是同一个风险。判定化后状态须含**调用级参数位**，判据须能表达「在什么参数条件下升档」 |
| **防线归属** | 规则未标注属于哪道防线 | 三防线正交、处置各异：**该不该做**（动作门——查因果链与业务策略）/ **数据能不能出去**（出站门——按域名、协议、方法、参数分别管，**允许域名不等于允许任意数据**）/ 最多能碰到什么（沙箱与最小权限）。一条规则里混装两道防线，等于两件事共用一个开关 |
**重构断言对账（v1.6.0 章三连带重构）**：本批重构改动两处——PHILOSOPHY「确定性规则」段加执行语义限定词、本节「概率压误报」加告警分流层限定词；**断言零删除**（两处原断言完整保留，仅加适用域限定与互引）， SECURITY〈28 条规则的判定化归属〉逐条去向表（28 条全覆盖）与判据重述数据（`engine/audit/src/rules/criteria/`）互引一致。
**拿六维检查清单做覆盖扫描，暴露三处结构盲区**（不是新的第 N 条规则，是既有判定面**完全没有人管**的三件事）：
| 缺口 | 问的是什么 | 为什么现有 28 条覆盖不到 |
|---|---|---|
| **凭证范围** | 当前凭证是否为**这个任务的最小授权** | 现有规则查「有没有提权」（A22 不越权限）——查的是**权限本身**；缺的是「权限与任务的**匹配度**」。凭证合法但对本任务过大，现有规则不判 |
| **动作授权状态** | 这个动作**有没有走过该走的授权**（双人复核 / 人工确认） | 这是审计的**本职**（事后核对「有没有按规矩来」），但 28 条规则全部面向**变更内容**，没有一条面向变更的授权过程——审批链在审计面不可见 |
| **序列累积效应** | 每个**单步**都合规，**合起来的序列**是否造成不可接受的系统性变化（含**隐蔽升级**：一串安全调用间接触发高影响结果） | A17 量的是规模（文件数 / 行数，纯函数）不是语义；28 条逐条独立判——无一条跨动作判，看不到动作时序与累积，序列语义需要调用时序证据 |
**三处盲区的本质是证据面缺口，不是规则面缺口。** 规则 = 判据 + 证据；**事实不可观测时，加一条规则只会得到一条永远弃权或永远放行的假规则**——它增加的不是覆盖，是「**看起来覆盖了**」的假绿。因此处置顺序是**先让证据可采、再谈判据**，且三处均在仓内有归属，不另开出处（SSOT——同一概念不长成两个入口）：
- **凭证范围** → 归口[权限四原则与零凭证沙箱](#权限四原则与零凭证沙箱)第 1 条「**最小权限**：每个 Agent 只拿当前任务必需的最小凭证集」。**原则已在、判定未在**——原则说的是「最小」，而 28 条判定面没有一条判「匹配度」。**证据面**随 v1.5.4 凭证 Vault 关闭（该版交付表补入凭证范围声明产出：申请范围 + 实际签发范围 + 比对结果）；判定面折进 A22 不越权限的语义层（`A22-2`「凭证与任务的匹配度」）——不新增规则条数。
- **动作授权状态** → **可闭合，且不需新造审批链——缺的是记录完整性，不是通道。** 现有 `intent.jsonl`（v1.5.1 审计输入面）记「**想干什么**」（tool 名 + 参数摘要 + 会话 + 时间戳），门禁判决本可与之对账，但 `TOOL_GATE` **声明三态（拦截/放行/告警），实现只落「告警」**——放行与拦截不留痕；人审支路 `hitl/resolved/*.json`（`approved`/`rejected` + 起止时间）已落盘且被治理报表消费，仅审计规则面未消费。
**证据面**归口 v1.5.1 审计输入面（`TOOL_GATE` 补齐三态并与 `intent.jsonl` 对账——**有动作、无放行、无批准 ⇒ 未授权执行**）；**判定面**折进 A16 非授权文件变更的语义层（`A16-2`「变更是否有对应的放行或人审批准记录」）——**不新增规则条数**。与企业级「事前授权（mandate）补环」是两件事：后者是「先批后干」流程，本处要的是记录完整性，不再混为一谈。
- **序列累积效应** → **证据面**归口 v1.5.1 审计输入面（调用意图流使**动作时序**可观测）；**判定面**折进 A17 异常批量变更的语义层（`A17-2`「本次序列是否构成异常累积效应」）——不新增规则条数。
**据此，盲区处置不加规则条数**：三处均归口于既有能力面——两处折进既有规则的语义层，一处**靠补记录**（门禁留痕三态补齐）而非靠新增规则。三条语义层判据（`A22-2` / `A17-2` / `A16-2`）的**证据前提**如上——**证据未可采前不得启用**，否则就是假判定。
**门槛纪律（凡带门槛的规则通用，不只弃权）：**
- **按原语分档**：`Noul` / `Choice` / `Score` 的置信剖面本就不同——是非题判对时通常自信，多选重排**普遍不确定**，有序评分**各档概率彼此接近**（须看整条分布而非仅置信度）。**同一个门槛值落在不同原语上是不同的严格度**，不得全局共用一个。
- **绑定当前分布**：门槛是**分布的峰位函数**；换基座或数据漂移须**重标**，沿用旧值等于用旧分布的门槛判新分布的样本。
- **健康度监测**：门槛设错**不报错，只会静默失效**——过严 ⇒ 全量落入 ASK（等于没有分流）；过松 ⇒ ASK 率趋近于零（形同虚设）。**两个极端都要告警**，这是静默失败监控在规则面的落点。
**留痕纪律（判据 + 证据的落盘口径）：**
- **同源不等于原样**——留痕要与判定输入同源（审计可重建当时看到什么），但**记指纹与引用而非原文**（输入哈希 + 判据集修订标识 + 构造入口版本）并带显式内容标记。**理由**：留痕自身会成为新的敏感数据仓；而「原样落盘造成数据副本」与「过度脱敏摧毁审计可用性」是同一枚硬币的两面。
- **写时锚定**——完整性在**写入时**锚定（签名 / 入链），不是事后补签：事后签的记录证明不了中途那几年。
- **可脱离原模型回放**——判据集版本 / 门槛参数 / 校准参数随判定落痕；否则模型退役后无法重算，留痕降级为不可验证的叙述。
**判据不是新建，是收口。** 正负样例与拦截理由字段已随 28 条规则全量在位——规则自测要补的是**加载时断言**（样例写错即 fail-closed 曝红），判据重述要补的是把既有字段升为「判据 + 证据」两段式数据面。两者都不新增格式。逐条规则的接管去向见 [SECURITY · 28 条规则的判定化归属](../SECURITY.md#28-条规则的判定化归属判定层接管后的逐条去向)。
### SHACL 语义契约（跨 Agent 协同的管控层参照）
SHACL（W3C 形状约束作本体提交时守门）参照已归档——多 Agent 协同语义校验不必自研。
> 📚 全文：[归档](./archive/validation-digest/README.md)
### 架构反模式：五种常见 Agent 工程错误
以下五种反模式在 Agent 工程实践中反复出现，与 sofagent 的已知局限形成对照。
| # | 反模式 | 表现 | sofagent 的应对 |
|---|---|---|---|
| 1 | **不了解工作就先画巨型 Graph** | 在稳定路径出现之前就设计复杂的 DAG/编排 | 编排模块先做串行版，完整 DAG 并行调度仍规划中（排期见 [LIMITATIONS §八](./LIMITATIONS.md#八包依赖与编排局限)） |
| 2 | **让同一个模型既写又评** | 执行者和审查者用同一个 LLM，自评不客观 | FORGE fresh-eyes-loop 要求 A/B 用不同厂商模型（异构） |
| 3 | **把「继续尝试」当作 Loop** | 无限重试无新证据，只是费用泄漏 | Loop 围绕「证据」设计——sustain 的 eval 反馈闭环需要明确 passRate 阈值 |
| 4 | **把 Harness 变成工具垃圾场** | 工具过多增加选择错误，宽泛权限扩大事故范围 | ToolGate 限定了 Agent 工具调用的前置门禁，不是所有工具都能随便调用 |
| 5 | **用 Graph 掩盖 Harness 缺陷** | 流程图无法修复陈旧数据、不可靠工具和缺少权限控制的问题 | 审计模块的「硬证据」原则（22/28 条纯 git-diff）不依赖 Agent 意愿——这就是 Harness 的底线 |
> **核心教训**：Architecture complexity should come from observed real needs, not from imagining "advanced agents"。sofagent 的约束层五能力不是同时做的——先有审计（Harness 层），再有 think.md 反思（回溯），知识蒸馏（沉淀），最后才到 evolve 自优化（进化）。FORGE 工具链是项目自迭代过程中逐步长出来的内部工具。这个顺序本身就是对反模式 1 和 5 的预防。
---
> 🧭 **域三 · harness 治理层**——治理与运维面：核心理念与编制、怎么部署运行、关键决策的工程理由、已知边界与远期路线。治理域的架构展开即导读层「双层架构」主框架。
## 四、核心理念与全局设计
> 🖼️ **三域定位**（v1.5.3 身份口径）：本章 = **治理域（harness 治理层）**主叙事——五能力、审计链、回溯都在治理域；**场景域**（FDE 场景层·万物皆可 FDEing 的场景框架）架构落点 = [§一 激活链](#一激活链架构v125-phase-1-4-已交付)；**判定域**（S1M 判定层）架构落点 = [§三 审计规则面的判定化边界](#审计规则面的判定化边界28-条规则--判定层接管)。
> 📖 **「为什么这么做」**见 [PHILOSOPHY](./PHILOSOPHY.md)。这里只讲架构设计——**怎么做的。**
sofagent 的架构基因来自 Geoffrey Huntley 的 Ralph 循环——「Agent 失忆，文件不失忆」。**不信任 Agent 自我报告，只看 git diff 硬证据。**
| 维度 | 通用 Agent 平台（WorkBuddy / OpenClaw 等） | sofagent |
|---|---|---|
| 管什么 | 「会不会做」——能力问题 | 「能不能每次都做对」——执行控制问题 |
| 关系 | Gateway 高速公路 | 交规 + 测速摄像头 + 驾校教练 |
> **90%/10% 价值分层**：AI 模型提供 90% 的智力输出（写代码、做分析、生成报告），但企业敢不敢让 Agent 自主执行，取决于最后 10%——**可靠性、可追溯性、可问责性**。sofagent 的价值不在那 90% 里（那是模型的事），在那 10% 里（约束层的事）。模型越强，约束层越值钱——因为 Agent 能做更多事了，但「做错了怎么办」的代价也更大。
> 理论基础及行业验证见 [THANKS.md](./THANKS.md) 和 [PHILOSOPHY §四 信任模型](./PHILOSOPHY.md#四怎么管信任模型)。
### 治理架构（约束层五种能力）
```mermaid
graph LR
A["📥 注入
约束注入链·启动前"] --> B["🔍 审计
28 条规则·拦截违规"]
B --> C["🔄 回溯
快照存档·一键回滚"]
C --> D["📚 沉淀
蒸馏·知识资产"]
D --> E["🧬 进化
周度巡检·三档准入自动进化"]
E --> A
B -.->|违规| BX["⛔ 拦截 + 留痕
（不进入下一环）"]
C -.->|恢复快照| CX["✋ 人工确认门控
（约定级·非机制）"]
C -.->|回滚中途失败·部分恢复| CY["✋ 人审介入
（约定级·非机制）"]
D -.->|质量门未过| DX["🗑 拦截不进知识库
（占位符级产出）"]
E -.->|增量 eval < 基线| EX["⏪ 回滚旧权重 / 撤回规则变更"]
A -.->|宿主未加载约束| AX["🔍 审计兜底
（注入失效仍有事后硬证据）"]
```
> ⚠️ **闭环不是无条件自转**（v1.5.1 补失败出口）——上图实线是**顺利路径**，虚线是每条能力的**失败 / 回退出口**；缺了虚线的版本会被读成「五能力永远成功」，与仓内已做对的对照组（[审计流程](#六核心设计决策) 与 tool gate 图的 `违规→拦截`、`requireApproval→HITL`、`FAIL→拒绝` 分支）不一致。
>五处出口均有实现依据：审计违规当场拦（A 类规则）、快照恢复的人审门控（`snapshot-restore.ts` 的 `human_confirmed`——**约定级非机制**，见 [LIMITATIONS §三](./LIMITATIONS.md#三安全与信任模型局限)）、快照回滚中途失败留下部分恢复状态（`restored` 数组报告已恢复文件）时人审介入（同 [§二 · 回溯能力](#-回溯能力自研同构-git-引擎--一键回滚) 的如实披露）、`quality-gate.ts` 三轴校验拦占位符级产出。
>进化保留判据挂在模型外信号上（增量 eval < 基线则回滚，见 [§二 · 🧬 进化能力](#-进化能力)）；**注入自身也会失效**（约束力 = Agent 注意力 × 平台加载可靠性），此时靠审计的事后硬证据兜底——这正是「事前约束 + 事后拦截缺一不可」的图面表达。
| 能力 | 设计原则 | 独立包 |
|---|---|---|
| 📥 注入 | 四层约束注入链永远在线 | @sofagent/inject |
| 🔍 审计 | 只看 git diff 硬证据 | @sofagent/audit |
| 🔄 回溯 | 事后快照 + `--revert` | @sofagent/core |
| 📚 沉淀 | 知识蒸馏回灌（knowledge/ + SKILL 文件） | @sofagent/daemon + @sofagent/evolve（与进化共享） |
| ⚙️ FORGE 工具链 | StateGraph LOOP 流水线（内部自迭代用） | @sofagent/orchestrator |
| 🧬 进化 | daemon cron @weekly | @sofagent/daemon + @sofagent/evolve |
> 🔀 **执行时机与热路径——五能力都不在判定热路径上**：五种能力的触发时机互不相同——**注入**在会话启动前（读即生效的静态文件）、**审计**在每次变更时（git hook / 文件变更事件，事后取证）、**回溯**是事后快照（不参与推理）、沉淀在批量蒸馏时、进化跑 daemon 周度 cron。判定与治理是两个不同计数单位的开销：判定按「每次判定」计（单次非自回归前向），治理按「每次变更」计（append-only 留痕 + 事件触发）。
>**因此二者不得相加报成单一「总延迟」**——量纲不同的两个量拼合出的第三个数，不是任何一方的读数（同「多源数字禁拼合」纪律）。**「不在热路径」是架构事实，不是免于落数的理由**：治理开销本身须单独有读数，见 [v1.9.0 §四](./changelog/v1.9/v1.9.0.md)。
> 约束层五种能力的完整设计哲学见 [PHILOSOPHY §三 架构全景](./PHILOSOPHY.md#三怎么跑架构全景)。
### 约束同源：一份定义，多端消费
约束的写法只有一种是对的：定义时写下的那条规则，同时就是推理时的规则、检索时的护栏、动作门禁的边界、审计取证的依据——多端消费同一份定义，不各自维护。「这边说能、那边说不能」的分裂不是实现 bug，是定义未单源的必然结果。四个独立方向印证同一判断：工程侧（本体建模器以 AST 单一数据源为内核，建模公理同时充当推理规则与工具 schema 护栏）· 金融侧（函数注册 + 版本管理，同一指标只允许一份规范实现）· 央企侧（护照模型：每要素带来源片段/置信度/创建者的结构化溯源）· 方法论侧（动作按风险分级路由，自主权边界由配置决定）。
> 内部对位：双规则引擎统一已于 v1.5.3 收口（tool-level 与 git-diff 收敛为单一规则引擎、两种触发时机）——本节原则即该收口的设计依据，收敛落点见 [§双规则系统重叠](#双规则系统重叠v153-施工收敛正则与定义层同源)。
**多端消费的前提是消费端答得出依据**：留痕只回答「发生过什么」，可归因回答「为什么是这个值」——同一份定义若不携带判定依据（凭什么判定、依据哪条规则、证据来自哪份产物），归因链一断，记录就退回日志。**审计质量的分水岭不在留痕密度，而在归因密度**。这里的归因到**因**（why），与 [VALIDATION](./VALIDATION.md) 结果负责三要素的「可归因（责任到人）」归因到**谁**（who）互补——责任要落地，两者缺一不可。
### 输出签名机制
约束层最大的挑战是存在感——约束在正常工作，但用户看到好结果时不知道是约束层在起作用。三层签名：
| 层级 | 机制 | 用户如何感知 |
|---|---|---|
| 审计输出 | CLI / Webhook / MCP 所有返回值以 `[sofagent]` 开头 | 看到 `✅ sofagent 审计通过` 而非 `✅ PASS` |
| 能力清单 | `list_capabilities` description 标注模块来源 | Agent 转述能力时附带「谁在做、怎么做的」 |
| 审查报告 | FORGE 审查报告顶部标注审计来源 | 报告中体现 `sofagent` 标识 |
签名不修改审计逻辑、不加速度开关——约束层不允许关掉自己的存在感。
### 跨能力关注点：持续感知层
签名解决的是「当下这一条结果是谁做的」。但 FDE 离场后，还有一个更长周期的问题：**客户 3-6 个月后是否还记得 FDE 部署了什么。**
这是 sofagent 的**持续感知层**——审计能力产出证据，进化能力生成报表，MCP 层负责推送。**FDE 的成功悖论是结构性的**：系统跑得越稳，客户感知越弱（详见 [FDE/GUIDE.md §5.10 离场](../FDE/GUIDE.md#510-离场五大能力)）。持续感知层是产品的必修课，不是营销策略。
> 📖 完整的感知衰减曲线 + 三层持续感知体系（定期价值证明 / 系统自曝复杂度 / 不可替代性标记）+ 配置方法见 [SKILL/skills/05-exit.md](../SKILL/skills/05-exit.md)（AI 执行层）与 [FDE/GUIDE.md §5.10](../FDE/GUIDE.md#510-离场五大能力)（人读概念）。
### 约束层的两种形态：加载链与运行时
> **术语对齐**（v1.5.1 收敛）：本节表格原称「地基 vs 约束层」，与本文 [术语对照](#术语对照) 的 SSOT 冲突（SSOT 把加载链定义为「Agent 启动时注入的约束文件（又称约束注入链）」＝注入能力的载体，**属约束层**，不是约束层之外的独立层）。现按 SSOT 改正为「约束层的两种形态」——静态加载链与运行时能力，**不引入独立层级**。
| 形态 | 是什么 | 成本 |
|---|---|---|
| 加载链（约束注入链·静态面） | 四层加载链（纯 MD 文件，Agent 读即生效）——约束层「注入」能力的载体 | ~3,500 token |
| 约束层运行时 | 编排 + 审计 + 回溯 + 沉淀（知识资产）+ 进化（含质量评估）+ daemon + CLI + MCP | 按需启动 |
> v1.1.0 将审计拆为独立 npm 包 `@sofagent/audit`，加载链（约束注入链）和其余能力（编排/审计/进化）与回溯不受影响。
### 功能编制（约束层内的功能模块）
> **定位声明**：对外产品唯一 = **FDE Harness**（约束层，注入·审计·回溯·沉淀·进化五能力）。下表「模块」是约束层内部的功能域编制称呼——**模块不是产品线，无独立入口，所有产出过审计与注册闸门**。「引擎」在对外叙事中**指约束层本体**（下表五模块构成的整体），单个功能域仍称「模块」；宿主 Agent、DSH、LangGraph 等外部系统直接称其名；「FDE 六引擎」是 FDE 工作台六个 tool 的固定称呼。
>**商业三层架构的中间层统一称「约束层」**（旧称「引擎层」已弃用，原「商业三层架构中的引擎层」豁免一并撤销）。
>
> **约束层的构成表述 = 「一个引擎 + 一组插件」**：引擎即下表五模块构成的约束层本体，不可拆、不可裁；插件把引擎能力以插件形态挂到宿主（DSH 7 款 / OpenClaw 4 款），可插拔、可裁剪。**引擎是被挂载方，不知道宿主是谁**——适配层不 import 宿主 SDK（这是写法保证的红线，不是纪律）。
>
> **插件身份判据——能力桥接器，非能力实现器**：cordis 生态的插件是「能力实现器」，能力本体写在插件里，因此能生长出庞大的第三方插件市场；sofagent 的插件是「能力桥接器」，能力本体永远在引擎能力包（`@sofagent/*`）里——插件层只声明「挂哪（seam）」与「桥接谁（bridges）」，判定与审计逻辑永不出引擎。这是「一切皆插件」哲学不可照搬的结构原因：允许第三方插件自带判定逻辑，等于把缰绳开放成马场（马鞍铁律在插件架构上的表达）。推论：插件市场只对执行面能力（工具域 / 巡检 / 沉淀 / 回滚）开放，审计规则与判定源不做第三方插件化。
>
> **插件裁剪纪律**：裁剪是**安全边界**，不是优化——面向外部的节点以「禁多余能力」为默认，最小工具集本身即攻击面大小。两条配置层语义陷阱必防：① **失败音量不对称**——写错插件 id 是静默的（只往无人读的缓冲区打日志，你以为禁掉的照常运行），而注入依赖不满足是响亮的（启动期直接拒绝）；静默侧只能靠干跑实测暴露，不能只看配置写了什么。② **禁用服务提供者必须级联**——所有依赖它的插件一并显式禁用，否则残余插件静默降级，表现为「已裁剪但能力仍在」（与守卫空转同族）。裁剪后的最终工具集以实测为准，不以声明为准。
| 模块 | 职责一句话 | 主要载体 |
|---|---|---|
| **编排模块** | 工作流 DAG 拆解、循环执行、Agent 阵型库（schema + 模板实例化；**调度接线未落地**，详见 [LIMITATIONS](./LIMITATIONS.md)） | orchestrator 包（LangGraph；事件驱动升级 v1.5.1 ✅ 已发版 2026-09-22） |
| **审计模块** | 单一规则引擎（tool-level + git-diff 同一份定义、两种触发时机）跑 28 条规则做 git diff 硬证据判定——每条规则带正负样例自测（加载 fail-closed），每次变更必审 | audit 包 + git hook |
| **后训模块** | post-training 流水线：审计轨迹→语料导出→训练（**外部执行**）→模型注册→晋升（模型进化闭环的中段） | orchestrator/train + eval 包 |
| **治理模块** | 治理 KPI、跨层证据对账、可见性分级 | v1.5.0（✅ 已发版 · 2026-09-19） |
| **执行模块** | 模型路由、沙箱隔离、凭证 Vault、多实例表决 | v1.5.4（✅ 已发版 · 2026-09-30） |
> 🧬 **进化面运行载体（v1.5.9 章七）**：进化是五能力之一、非五模块之一，运行载体自 v1.5.9 起从 harness 主干改挂 RSI 独立插件 `cordis-plugin-sofagent-evolve`（DSH 七款之一，零迁移成本、能力归属不变）：沉淀留主干、进化独立成插件；RSI 治理件全在插件内可独立拔插，换插件 ≠ 失去审计与沉淀、插件不加载时进化面不生效但审计链不断。
> 📌 **后训模块的能力边界**：本仓负责后训流水线的编排与治理——任务提交 / 预算门禁 / 环境体检 / 提交前预检 / 失败诊断 / 语料导出 / 合规闸门 / 交付包 / 模型注册与灰度 / 推理服务；训练本身在外部执行环境进行，本仓不实现训练器。
> 🔒 **编制准入三问**（新功能域进编制表前必过）：
> ① 挂得上五能力吗（注入/审计/回溯/沉淀/进化至少其一）？
> ② 产出过审计/注册闸门吗（产物可追溯、可回滚）？
> ③ 砍掉它 harness 还成立吗（成立=它是增强件，可进；不成立=它是命脉件，必须已在核心叙事里）？
> 🧭 **训练器是「集成」不是「自研」——选型有公开对标物**：既定路线由 TrainChannel 接外部训练栈（编排侧默认 `verl`，推理侧 vLLM / Ollama / OpenAI 兼容端点，双栈契约见 [train-stack](./guides/train-stack.md)），本仓不自研训练框架。
>公开生态同位候选（选型参照，非已采用）：`verl` · `LMIS-ORG/slime-agentic` · `XYZ-AI-Lab/axrl` · `jinzijian/EvoTrace`——共性即本仓边界：训练与资产生产交给外部执行器，本仓只做编排与治理；差异不在「训练框架选谁」，而在变更级可问责（谁改了哪条规则、哪次变更被拦、凭什么）。
### 产品架构展望（五层）
| 层 | 部署在哪 | 干什么 | 状态 |
|---|---|---|---|
| **Harness 层** | Agent 上下文 | 纯 MD 文件，Agent 读即生效 | ✅ |
| **执行层** | 用户设备 | daemon 常驻进程——跨 session 经验不丢失 | ✅ |
| **审计层** | git 仓库 + 文件系统 | sofagent audit——提交时审计 + 文件变更审计 | ✅ |
| **MCP 推送层** | 设备 MCP server | @sofagent/mcp 独立包 | ✅ |
| **协同层** | 多设备 + 云端 | Agent 独立身份、共享上下文、组织记忆 | 待裁定（无排期） |
## 五、部署与运行架构
### 双节点架构
sofagent 支持两种节点类型：
| 维度 | 自动运行节点 | 个人增强节点 |
|---|---|---|
| **场景** | 企业无人值守设备 | 个人开发者（WorkBuddy/Codex 等） |
| **Agent 平台** | ✅ 必须（OpenClaw 或其他企业级平台） | ❌ 不需要 |
| **编排调用** | 平台内部 API | `sofagent orchestrator compose --task` CLI |
| **约束注入** | 平台 Hook 精确注入 | Sub Agent 自加载（`buildConstrainedSystemPrompt`） |
> Sub Agent 约束自加载：启动时读 `.sofagent/` 下的约束文件，拼装为 system prompt。纯文件系统操作，不依赖任何 Agent 平台的 Skill 系统。换平台约束不丢。
### River — Workflow — Subagent 三层架构
**River = 多个 Workflow 的集合**——每段 Workflow 把模型能力（水）引到业务侧，汇入同一条大河（River），从头到尾同一个身份、同一段上下文。
```text
用户 → River（统一入口）→ Workflow A/B/C（分发）→ Subagent（执行）
↑ 回流 ↑ 审计
```
| 层 | 是什么 | 类比 |
|---|---|---|
| **River** | 统一 Agent 入口 | 大河——只有一个入口 |
| **Workflow** | 任务编排方案 | 把水引到业务侧 |
| **Subagent** | 执行具体能力的 Agent | 水龙头 / 用水设备——让水真正作用 |
River 的载体是 Agent 平台（OpenClaw / WorkBuddy 等）+ sofagent + Channel 集成。sofagent 不做 River 本身（河是大厂造的——LLM 是水，Agent 平台是河床），而是做河的约束层（约束 + 安全 + 编排 + 执行），确保 River 里的每一个 Sub Agent 都有纪律、可追溯、会反思。
> 🏞️ **River 比喻完整映射**见 [README · 这是什么](../README.md#这是什么)——sofagent 做堤坝 + 自来水厂 + 管网 + 水龙头，不做河本身。
> **Workflow 的混合架构**：每条 Workflow 采用「外层 Graph 骨架 + 内层 ReAct 节点」——`workflow.yml` 的 `nextNodes` 锁定全链路步骤、保证可追溯（对应 Graph 实现全局流程骨架），单个节点的 `prompt` 保留模型自主规划能力（对应内层 ReAct Agent）。这一设计兼顾全局稳定性与局部灵活性：低容错业务靠 Graph 锁死流程，复杂节点靠 ReAct 保灵活。
#### MCP 触发完整链路（v1.1.8+）
> 这一节回答一个具体问题：**企业员工在钉钉/飞书/企微里 @ 一个 tag，sofagent 怎么接住这个请求并跑完 Workflow？**
大厂入口 Agent（River 载体）通过 MCP 协议调用 sofagent：`compose` MCP tool（v1.1.0 起，v1.5.2 前名 `sofagent_compose`）在 v1.1.8 补上 `--run` 真正执行 + `--enterprise-workflow` 接收 FDE workflow 后链路完整。
**七步链路**：① 用户 IM @tag → ② 入口 LLM 识别意图、调 `compose`（task + enterprise_workflow + run）→ ③ sofagent 按企业 workflow 拆解、输出编排方案 YAML + SubAgent[] 配置（每个注入四层加载链）→ ④ dag-runner 调 LangGraph createReactAgent 调度 → ⑤ Sub Agent 带 Harness 约束执行（审计逐节点卡关）→ ⑥ 审计通过 → human_confirm → ⑦ 结果回传 LLM 翻译成自然语言给用户。
**关键差异化**：大厂入口 Agent 做通用调度（什么都能干，什么都不精），sofagent 做 **Workflow 专项**——Sub Agent 只做 FDE 梳理好的专项任务，比通用调度更可控（「专项 Harness > 通用 Agent」，不与大厂竞争而做补充层）。**前提**：入口 Agent 需支持 MCP（Coze / Dify / WorkBuddy 已支持，钉钉/飞书/企微跟进中）。与扣子（Coze）在 Slack @tag 的区别：扣子嵌入的是通用 Agent，sofagent 嵌入的是**约束过的专项 Workflow**。
### 编排层与执行层分离（v1.3.4 增量 · DSH 执行后端接入）
> 📖 设计来源：DeepSeek Harness（DSH）「一切皆插件」Cordis 运行时 + sofagent「确定性审计依赖显式图结构」铁律的融合——编排层不换（确定性），执行层可换（灵活性）· 外部来源：[deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness)；内部融合论证见 [PHILOSOPHY §三](./PHILOSOPHY.md)
sofagent 的编排模块从 v1.3.4 起显式分为两层——**编排层不换（确定性），执行层可换（灵活性）**：
```text
编排层（LangGraph StateGraph · 确定性 · 长期不动）
├── 图结构定义：节点 + 边 + 条件路由（enterprise-graph.ts）
├── 审计卡关：每个波次 git diff + decision-log（merge-gate.ts）
├── Checker 节点：format/fact/source 三类检查（checker-nodes.ts）
├── HITL 挂载：人工审批节点（graph.ts / nodes.ts）
├── loop 编排规则：fresh-eyes / release-gate 的 A→B→汇总→修→验
│ （verdict 解析 / 场景覆盖 / 行数警戒线 / 声称一致性检查）
└── 并行调度：ParallelScheduler + MergeQueue
↓ 通过 ExecutionBackend 接口调用执行层
执行层（可替换 · 默认 DSH Cordis 运行时 · fallback createReactAgent）
├── 默认后端：DSH Cordis 插件运行时（v1.3.4 接入）
├── Fallback：LangGraph createReactAgent（DSH 不可用时自动降级）
├── 可选后端：WorkBuddy / Claude Code / OpenClaw（现有三平台）
└── 契约：实现 ExecutionBackend 接口 { execute(task) → result }
```
**边界规则**：
- **编排层长期不换**（架构级取舍，**非永久承诺**）——28 条 git diff 规则 + HMAC 链 + DAG 波次审计 + decision-log 全部依赖显式图结构，换掉编排层 = 放弃确定性审计；该约束的成立前提是「确定性审计仍依赖显式图结构」，前提失效则本条随之失效（同口径见 [四层运行形态](#四层运行形态企业-ai-从梳理到专属模型)）
- **执行层可换**——只要实现 `ExecutionBackend` 接口（`execute(task) → result`），任何框架都能挂载
- **loop 的编排规则留编排层**（verdict 解析/场景覆盖/行数警戒线），**loop 内部 worker 跑 agent 的那一步可以让给执行层**——sofagent 管「循环逻辑」（判对错/定位/收敛），执行后端管「循环执行」（跑 agent 代码）
- **工具 wrapper 原样透传**——audit-middleware（运行时审计）/ progress-middleware（进度监控）包裹在工具 func 上（v1.3.0 模式），随 `ExecutionTask.tools` 走，任何后端不得重包装或替换工具实现
**迁移范围**：v1.3.4 完成第一波分离——`launcher.ts`（主入口）+ FORGE `fresh-eyes-driver` + `release-gate-driver` 三个调用点已改为通过 `ExecutionBackend.execute()` 调用。`dag-runner` / `composer` / `loop/nodes` / `node-executor` 等调用点列入后续迁移清单。
**DSH 关系定位**：DSH 是「agent 框架插件化」路线，sofagent 是「FDE 方法论 + 确定性审计」路线。两者通过 `ExecutionBackend` 接口对接——DSH Cordis 运行时成为 sofagent 执行层默认后端，LangGraph createReactAgent 作为 fallback。
> ⚠️ **接入门禁状态**：早期候选包名曾长期 404，v1.4.0 已改走 **Cordis 内嵌路径**（`@deepseek-ai/cordis@4.0.1` stable + `@deepseek-ai/dsh@0.1.2-alpha.3`，rc.2 内嵌已验证可行）。rc 期**内嵌为主路径**，失败自动 fallback CLI 桥接，LangGraph 为最终 fallback。决策记录见 ROADMAP。
> 💡 **为什么不把整个编排层也换成 DSH**：DSH 的事件驱动模型（插件 A 触发 B → B 触发 C）没有显式执行路径，运行时才确定——而 sofagent 的审计模块（git diff 硬证据 + HMAC 链 + 波次审计卡关）全部依赖预先画好的 DAG 图结构。用 DSH 替代 LangGraph 编排 = 放弃确定性审计能力。分层使用 = 两者各取所长。
### Agent 基础设施层（v1.0.8+）
两个内置 Agent 被所有 workflow 节点引用：
| Agent | 管什么 | 触发时机 |
|---|---|---|
| **合规审计员** `@sofagent audit` | 管底线——P0/P1 分级 | 每次 commit / FDE 部署 / FORGE 闭环 |
| **FDE 部署工程师** `@sofagent-fde` | 管上限——deploy/sustain | 部署时 / daemon cron @weekly |
Agent 定义在 `SKILL/agents/{name}/SKILL.md`，`parseSkillMd()` 读 front matter 作为身份标签，body 注入 createReactAgent 作为 role prompt。
### Agent 平台在架构中的角色
**审计层不依赖任何特定平台**——sofagent audit 是独立 TypeScript CLI，输入 git diff，输出 exit code。即使不装 Agent 平台（OpenClaw / WorkBuddy 等），开发者也可通过 `bash install.sh`（推荐）或 `npm install -g sofagent`（高级/开发者路径）配 commit-msg hook，让任何 Agent 平台的提交经过审计。
**编排层当前走 LangGraph createReactAgent**——`compose --task` CLI 入口，任何 Agent 平台都能用。迁移路径：ao（AutoGen）→ DeepAgents（v1.0.7）→ LangGraph createReactAgent（v1.2.0，deepagents 已弃用）。
### 文件系统审计
v1.0.8+ daemon 监控文件变更，非开发者也能用审计：
| 维度 | git commit 审计 | 文件系统审计 |
|---|---|---|
| 触发 | 用户主动 commit | daemon 自动检测 |
| 拦截 | ✅ 阻断 commit | ❌ 事后告警（已改完） |
| 需要 git | ✅ | ❌ 自研 git-shadow diff 解析（isomorphic-git 风格，非内嵌第三方包） |
事后审计是平台无关性的前提——实时拦截需深度集成平台，一旦集成丧失第三方独立性。v1.0.8 daemon 让事后审计达到准实时（fs.watch → 2 秒防抖 → 立即审计）。因此**实时拦截 / 运行时治理仅限 sofagent 自派 SubAgent**（sofagent 起环境又发凭证、天然拥有执行边界）；主 Agent 由第三方平台运行，sofagent 不进其执行环，保持事后审计。
### 长驻运行时治理（对标 Managed Agent Runtime）
行业参考观点：Agent 不能「用的时候开、不用的时候关」，应作为**长驻微服务**治理（非脚本）。sofagent 的 daemon（cron.ts）已落地常驻，但尚缺下列运维模式——这些模式仅针对 sofagent 自派 SubAgent 的隔离运行时治理（§七 范围声明例外；主 Agent 运行于第三方平台，sofagent 不做其运维层），补齐即 daemon 完整的「7×24 工位」：
| 模式 | 作用 | sofagent 现状 |
|---|---|---|
| Supervisor（进程守护）| 心跳上报 / 任务队列排空 / 内存水位监控 | 部分（daemon 常驻）|
| Health Probe（约 30s 心跳）| 上报当前任务数 / 最近成功响应 / Token 余额；连续约 3 次超时触发 Auto Recovery | 缺 |
| Auto Recovery | 先 graceful restart（排空任务），失败 force kill + cold start | 缺 |
| Graceful Shutdown | 排空在途任务再退出 | 部分 |
| Version Rollout（蓝绿切换）| 零停机升级 | 缺 |
| Circuit Breaker | 外部依赖连续失败约 5 次进入降级模式（停主动任务、留被动应答 + 告警）| 缺 |
> 关键认知：进程活着 ≠ 服务健康——卡死在死锁里的 Agent 进程 ps 看着正常，但已 30 分钟没处理消息。健康须靠心跳 + 恢复闭环证明。
## 六、核心设计决策
### 设计原则
sofagent 的四条设计原则，每条背后有独立的理论/工程/经济学论证：
| 原则 | 含义 | 工程体现 |
|---|---|---|
| **状态最贵** | CS 两大难题都指向状态——缓存失效和命名 | Ralph Loop 无状态范式：Agent 失忆，文件不失忆 |
| **模型输出是提案** | 大模型是带噪声的随机过程——不消除随机性，用循环驯化 | git diff + 审计规则 = 适应度函数 |
| **先有掌控感再自动化** | 不信任 Agent 自我验证 | Maker-Checker 分离：审计独立于 Agent |
| **90%/10% 价值分层** | 模型完成 90% 常规任务，剩余 10% 高风险场景价值反升 | 见 [§四 · 90%/10% 价值分层](#四核心理念与全局设计)（约束层占据高价值 10%）|
> **历史转折（v0.98）**：sofagent 最初走「事前约束」路线——在 Agent 干活前注入规则，指望它自律。两次 200 次对照实验后放弃：不是约束无效，是实验室测不出来。转向「事后审计」路线——git diff 是客观证据，不依赖实验设计。这次转向定义了 sofagent 的立身之本：**不信任 Agent 自我报告，只看文件 diff 硬证据。**
### 四层加载链：为什么是这个顺序
四层的**层序定义（层 / 文件 / 权限）见 [§二 · 📥 注入（约束注入链）](#-注入约束注入链)**（本档 SSOT）；「为什么是这个顺序」= **权限递减**（宪法层 ❌ 不可改 → 知识层可积累）+ **开头位置注意力最高**——**不是**代码强制的高低优先级（准确语义见该节「加载顺序的准确语义」表）。本节只留预算口径。
四层中前三层（SKILL.md / fde.md / think.md）在 Agent 启动时加载，第四层 knowledge/ 按需召回 top-N，不占基础预算。加载链总占用不超过上下文窗口的 3%，规范类文件（SKILL.md/fde.md 等）预算 ≤500 字，think.md 反思区单独预算 ≤2K token——这是 Agent 压缩后可读的最低保证（落地状态见下方注记）。
> ⚠️ **预算约束当前状态**：总占用 3% 检测 + 超预算**自动压缩已落地**（`engine/inject/src/load-chain/{budget,compactor}.ts`，v1.4.8 第四章）——超预算时保留段（红线 / 铁律 / 最近决策）原样、可压缩段截断并加 start/end 标记；未设预算 env 时零开销直通。规范类 ≤500 字**不硬截断**（截断会丢铁律；仅 persona 前 500 字符与 knowledge 单篇前 2000 字符有截断）；**拒载/降级机制仍未排期**（触发条件 = 压缩落地后实测仍频繁越线）。
>进度跟踪见 [DEVELOPMENT「加载链预算目标跟踪」](./DEVELOPMENT.md#加载链预算目标跟踪)（维护者口径，自 ROADMAP 迁入）。
> 💡 **记忆系统的三软肋 = 知识健康巡检的防御目标**
>
> sofagent 的四层加载链（SKILL.md → fde.md → think.md → knowledge/）与业界长期记忆系统的「基石上下文 / 手写规划 / 自动记忆库」三层架构同构，核心同样是「索引常驻、细节按需召回」。但自动沉淀的记忆有三个共性软肋，正是知识健康巡检（daemon conflict-check + Dream Cycle）必须防的：
>
> | 软肋 | 表现 | sofagent 的防御 |
> |---|---|---|
> | **不会遗忘** | 堆积过期/重复/矛盾笔记，旧决策干扰新任务 | Dream Cycle 定期整理 + conflict-check 查矛盾/孤儿 |
> | **索引膨胀** | 索引超长后尾部被悄悄挤出召回范围且不报错 | 加载链预算约束（≤3% 窗口检测 + 超预算自动压缩；落地状态见上方说明） |
> | **无强制规则** | 记什么/怎么分类/何时合并删除全靠临场发挥 | memory-contract.ts 代码层强制追加不变量 + 派生方向单向 |
>
> 一句话：管得住比记得多重要。某 30 万行项目仅用 148 行主索引承载 1.4 万行记忆——印证「索引常驻、细节按需」是记忆架构的正解。
### 反认知投降的制度设计
当 AI 能力过强时，人类会不自觉进入「认知自动驾驶」。「判断权不可外包」的论证主体与三道制度护栏（fde.md 规则可随时覆盖 / 编排方案可回滚 / 审计独立于 Agent）的逐条「防什么 · 怎么防」见 [PHILOSOPHY · 主体性护栏](./PHILOSOPHY.md#主体性护栏执行可外包判断不可外包)（**论证 SSOT**），此处不复述。
### 文件系统架构
理由：`cat task/logs/` 就能拿到记录，不需要 SQL/连接串/权限管理。天然可审计、可传输、支持 Git。三层映射（Ledger / Views / Policy）的定义见下方「Ledger-Views-Policy ↔ LLM Wiki 三层同构对照」表。
> 记忆模型的完整契约（追加不变量、多写入方、派生方向单向）以 `docs/PHILOSOPHY.md` §五 为唯一权威文字定义，并以 `@sofagent/core` 的 `memory-contract.ts` 在代码层强制（路径 `getThinkPath()`、只追加写入点 `appendThinkEntry()`）。本文件仅描述架构映射，不重复定义契约。
#### Ledger-Views-Policy ↔ LLM Wiki 三层同构对照
sofagent 的三层治理与 Karpathy LLM Wiki 的 `raw materials → Wiki entries → spec norms` 范式同构：
| LLM Wiki 层 | sofagent 对应 | 物理位置 | 读 | 写 | 审计 |
|---|---|---|---|---|---|
| **raw materials** | **Ledger** | `think.md` + `audit/history.jsonl` | Agent + 审计 | Agent 实时写入（append-only，`memory-contract.ts` 强制） | audit 模块每次 commit |
| **Wiki entries** | **Views** | `knowledge/{entities,concepts,comparisons,summaries}/` | Agent + MCP tools（`read_entity` / `read_concept` / `list_entities` / `search_knowledge`） | Dream Cycle 派生 | daemon `conflict-check`（矛盾/孤儿/死链） |
| **spec norms** | **Policy** | `fde.md` + `SKILL/agents/*/SKILL.md` | Agent 启动时经 Harness 加载链注入 | 人 + FDE 维护（手动 / sustain 模式） | A15 约束验证规则 |
> ⚠️ Views 层是 **4 个子目录**：`entities/` `concepts/` `comparisons/` `summaries/`。此前部分文档只列 3 个（漏 summaries），v1.1.6 起统一为 4 个，与 MCP server 实际规范对齐。
##### RAG 三层视角：取知识 / 组织知识 / 管理检索与执行
知识系统选型常被混为一谈，实际是三个正交层次。sofagent 三层全占：**RAG**（固定检索——`search_knowledge` 单次检索 + FDE 进场知识库构建）／**LLM Wiki**（知识组织——Ledger-Views-Policy 三层，见上表）／**Agentic RAG**（智能控制——**编排模块本身**，ReAct 循环的每个决策点 + daemon 巡检补位 + A/B 收敛判定）。
> 💡 市面多数「企业知识库」产品只做到前两层、检索决策仍是固定管线；sofagent 的编排模块天然是第三层（Agentic RAG 的控制循环 = ReAct Agent 的决策循环），且用 ontology 语义底座替代裸向量检索（召回的是「有治理的实体关系」，不是「相似度碎片」）。**第一层是能力，第二层是资产，第三层是编排**——三层齐了，知识才从「存着」变成「被智能地使用」。
### 模型选择
默认推荐 DeepSeek（第三方 API 服务，调用时数据离开本机到 DeepSeek 处理——「数据不出本机」仅指 sofagent 自身审计/知识/决策数据落盘，不含 LLM 调用）；成本可控（Loop 额外消耗 <1 美分，内部实测参考值，非外部基准）。模型选择是开放的——Flash 干粗活、Pro 干细活，按成本 4:1 分配。
### 编排收敛与 A/B 测试
编排是 Loop 工程——任务到达后持续迭代至收敛。收敛条件：目标可验证 + 模型可自主判断。A/B 对比走确定性指标（运行次数、违规率、步数、通过率），不由 Agent 主观判断。连续胜出 2 次自动 promote。
| 收敛反例 | 为什么不行 |
|---|---|
| 「优化页面美观度」 | 不可量化，Loop 会跑十几小时无法收敛 |
| 同一 Agent 自验 | 覆盖率 7-33%，裁判运动员同一人 |
| Maker-Checker 分离后 | 覆盖率提升至 73% |
> 注：「7-33% → 73%」为内部实测参考值，非外部基准（呼应 [LIMITATIONS「LLM 自评无外部基准」](./LIMITATIONS.md)）。
### 四层运行形态的三条决策
四层运行形态（见心智模型区「四层运行形态」图）背后是三条硬决策，各自对应一个「不做」：
| 决策 | 含义 | 反模式（不做） |
|---|---|---|
| **双图谱并行产出** | Workflow Graph（流转）+ Ontology Graph（语义）从同一次 FDE 访谈并行产出，SHACL 互相校验 | 不做「Workflow Graph → Ontology Graph」单向转换——转换丢访谈中的隐性知识，本体沦为工作流的副产品 |
| **执行层可换（编排层长期不动）** | 编排层 LangGraph StateGraph 长期不换（确定性审计依赖显式图结构，属架构级取舍非永久承诺）；执行层走 ExecutionBackend 接口——DSH 默认 / createReactAgent fallback / 三平台可选，双后端镜像验证 | 不做「只修一处的堤」——企业命脉不押单一运行时，DSH rc 阶段 breaking change 风险不传导给客户 |
| **治理是事件域横切面** | plugin 挂 tools/result、turn-stopping、approval seam 等全局事件域，装一次全域生效 | 不做「逐节点插桩」——治理不是节点附件，是横切所有节点的约束层 |
> 📖 **双图谱术语定义**：FDE 的最终输出统一表述为——**梳理 workflow、定义 ontology，交付 Workflow Graph + Ontology Graph 双图谱**。「Graph」是可视化 / 可理解形态的统称：
>
- **Workflow Graph** = FDE 梳理好 workflow 后多个 workflow 组成的流程图谱（动态，**人读它理解企业怎么运转**）
- **Ontology Graph** = ontology 的图谱化形态（ontology 本身是哲学定义，加 Graph 才让人知道它是可被理解、可视化的东西；静态，**AI 读它理解企业是什么**）
>
> **两者对应同一套业务，只是读者不同**——FDE 进场两种都读（既向人解释流程，也向 AI 喂语义）。**与 Graph Engineering 的关系**：双图谱正是企业级 Graph Engineering 的前提——有了这两张图，Agent 才能针对它们做 graph engineering（编排、审阅、进化）；sofagent 不自创概念，只负责帮企业把图搭建出来，商业平台层（独立于本 MIT 仓库维护）托管的就是这双图谱。
>**名称辨析**：行业研报的 Org Graph（进组织架构的硅基员工，见 VALIDATION）与 Ontology Graph 是不同概念——前者讲 Agent 的组织归属，后者讲业务语义的图谱化形态，勿混。
### 关键决策的证伪条件（v1.5.1 新增）
> **为什么要写这一节**：本档有反模式列、量化口径、边界声明、技术债显式化——但此前**全篇没有一处写「这个决策在什么条件下应该被推翻」**。只讲「为什么这么做」而不讲「什么时候这个理由不成立」，等于把每个决策都写成信仰。下面给 5 条核心决策各配一个**可观测的证伪条件**：条件成立时，正确动作是推翻决策（而不是继续为它找理由）。
| # | 核心决策 | 决策依据（现在为什么对） | **证伪条件（出现即应推翻）** |
|---|---|---|---|
| 1 | **「一个层，五种能力」的双层架构**（约束层 × 生命周期） | 治理是横切面而非节点附件；五能力对 Agent 七维度各覆盖若干面 | 出现一类企业需求，**必须**在约束层之外新增独立能力层才能满足（而不是把新能力落进五能力之一）——例如审计判定源被迫与编排强耦合、拆不出独立层 |
| 2 | **四层加载链的层序**（SKILL.md → fde.md → think.md → knowledge/） | 权限递减（宪法不可改）+ 开头注意力最高；索引常驻、细节按需召回 | 实测数据表明「后加载层」对 Agent 行为的支配力**稳定高于**宪法层（即注意力位置假设被证伪）；或宿主平台提供的原生约束机制能逐条验证且可回滚——此时「用 MD 文件做注入」失去必要性 |
| 3 | **用注入，不用 fine-tune / 显式 prompt** | 注入可审计、可回滚、可逐会话加载；另两方案分别不可审计、无机制保障 | fine-tune 侧出现**可逐条核对**约束是否内化的验证手段（审计性追平注入），或注入的「约束力 = 注意力 × 加载可靠性」被证明低于某一可用门槛且无兜底 |
| 4 | **不信任 Agent 自我报告，只看 git diff 硬证据** | 硬证据不可绕过（默认配置下的防线，绕过面见 [LIMITATIONS §三](./LIMITATIONS.md#三安全与信任模型局限)）、软证据可伪造；22/28 条规则为纯 git-diff | 出现一类关键风险**只存在于运行时意图层、不落任何 git 变更**，且事后无法从任何硬证据回溯——此时「硬证据唯一裁决」会系统性漏判，须补运行时意图面（decision-log 已是该方向的局部应对） |
| 5 | **编排层 LangGraph StateGraph 长期不换 + 执行层可换** | 确定性审计（28 条 git diff 规则 / HMAC 链 / 波次审计 / decision-log）全依赖显式图结构 | 确定性审计改由其他机制承载（不依赖显式图结构仍能逐条验证），或 LangGraph 出现使审计链无法维持的破坏性变更——此时「长期不换」的前提消失，该约束随之失效 |
| — | （表用法注）证伪条件须为**可观测事件**（具体现象 / 实测数据 / 上游变更），非「将来有更好方案」类不可证伪措辞；第 5 条与 [四层运行形态](#四层运行形态企业-ai-从梳理到专属模型) / [§五 编排层与执行层分离](#编排层与执行层分离v134-增量--dsh-执行后端接入) 的「非永久承诺」口径一致；（详→注-5） |
> 注-5：未列入 ≠ 不可证伪——本轮先补 5 条，其余后续版本增量补齐（不做一次性全量重写）
## 七、已知局限与未来方向
**已知局限**：详见 [LIMITATIONS.md](./LIMITATIONS.md)（按主题分章，含 Key Limitations 速览）。核心：Harness 层自身在上下文里、加载链步进脆弱性、Skill 自进化处于经验记录阶段。
**已交付**：激活链 Phase 1-4 全链路——activate→compose→run→HITL→audit→sustain + `wrapToolCall` middleware + Ontology 数据 + 并行编排 + Agent 身份码 + Onboard L1-L5 + Refine Agent + 进化闭环。明细见 [CHANGELOG](../CHANGELOG.md) 与 [激活链设计](./guides/fde-activation-chain.md)。
**未来方向**：
- **v1.5.4（✅ 已发版 · 2026-09-30）**：**分层模型路由**（云端规划 / 本地执行分层 + 数据敏感度 fail-closed + routeReason 可解释——路由层本体已在位，调用侧分流归位判定面）；**离线节点交付**：[v1.8.0](./changelog/v1.8/v1.8.0.md) 介质两档（DSH 节点 + 判定件交付介质，旧「合体」叙事退役）；**组织级共享记忆 + 协同层**：v2.x 待裁定（版本域纪律：V2.0 起为 S1M 迭代域）
- **v3.x-v4.x+**：企业专属小模型精调（`sofagent-model distill` QLoRA）——离线节点本地推理的轻量化。详见 [ROADMAP · 分层模型架构](./ROADMAP.md#分层模型架构v30-远景概述)
- **远期护城河演进方向（非当前能力）**：详见 [归档 · ARCHITECTURE 细节](./archive/doc-slim/architecture-industry-anchors.md)。
> **远期部署形态与数据逻辑（非当前能力）**：引擎作为**软件**部署在**企业侧信任边界内**（独立控制节点或容器内），由其**驱动训练流水线**——加载企业自带 license/key 的开源基座 + 企业私有数据，训练产出定制模型；全程数据不出域、sofagent 不碰原始数据、企业用自有 GPU/key（BYOK）。训练主体是软件/引擎跑脚本，模型不「自训练」。此为长期目标蓝图，当前不具备。
> **数据飞轮 = 护城河的正反馈引擎**：企业真正的护城河不在模型或算力，而在**持续沉淀的私有数据资产**。专家对 AI 结果的每一次修正（审计记录的 git diff、fresh-eyes 发现的 finding、Verifier 定义的「什么算合格」）都会生成**独有的垂直数据**——越用越懂自己的业务，形成正反馈闭环（数据飞轮）。sofagent 的「数据主权 / 本地闭环 / BYOK」不只是防守（数据不出域），更是进攻：**每一次使用都在让下一次更好**。这与 PHILOSOPHY「企业把自身 workflow 数据做成领域后训练即护城河」一脉相承。
**daemon 主动巡检清单**（注册于 `engine/daemon/src/inspectors/registry.ts` 的 `INSPECTORS` 单源——**以下为示例而非全集**；完整清单（名称/层级/启用态）以代码为准，金名单测试 `inspector-registry.test.ts` 双向锁防漂移）：
| Inspector（示例） | schedule | 检查内容 |
|---|---|---|
| audit-history | @daily | 审计历史健康度（exit code 分布 / 高频 WARN 规则） |
| conflict-check | @weekly | knowledge 矛盾（critical）/ 孤儿（warning）/ 死链（warning） |
| maintenance-daily | @daily | 数据维护四步（F5 memory 归档 · F30 think 归档 · F48-⑤ spill TTL 回收 · F51-① persona 同步，v1.5.7 批D） |
| knowledge-health | @weekly | knowledge 健康：孤立/重复（normalized-key）/断链/index 过旧（>24h）/缺源（warning，fail-closed 只读，报告落 health-report.md） |
| warn-accumulator | @daily | 连续未处理 WARN 累积（阈值 3，含文件级追踪） |
> **范围声明**：sofagent 是 Harness 中间件（**品类定位词**，两义辨析见 [术语对照](#术语对照)）——覆盖行为约束 + 变更审计 + 经验沉淀 + 持续优化。
>
> **不覆盖**：主 Agent 平台本身（IM 渠道 / 第三方平台托管的沙箱 / 工具调用——WorkBuddy / OpenClaw 等大厂平台的事），以及运维层（监控 / 告警 / 重启 / 日志轮转）。
>
> **例外**：sofagent 托管**自派 SubAgent** 的运行时治理——v1.3.0 起 middleware 层轻量拦截（工具调用中介 + 人工批准钩子），v1.3.7 扩展为完整沙箱（文件系统隔离 + 网络出站白名单 + 工具调用前置 allow/deny + 虚拟 key 边界注入），因 sofagent 既起环境又发凭证、天然拥有执行边界。**运行时治理仅限自派 SubAgent，主 Agent 永远事后审计**。
>
> 扣子（Coze，字节跳动）类全栈产品管从 Agent 到权限的全部层，sofagent 管其中可独立标准化的约束 + 审计层——不管企业用什么 Agent 平台，sofagent 是第三方独立底线守卫。
## 八、数据层路线建议
> 数据层路线建议（设计过程记录，非现态——不修改任何既有引擎行为）已归档。**一句话结论**：语义层/本体采用混合路线——Policy 层（人工认证）永远压顶、Views 层（自动派生）只补全不推翻、权威排序显式化为「命中次数 × 来源可信度」；`certified` 语义尚未落地（引擎源码零实现）。全文（两条路线对照 / 三条待硬化设计决策 / 落版下一步 / 待办问题）见 [归档](./archive/validation-deep/architecture-datalayer-roadmap.md)。