能力详解：九组能力

🤖 本页要点已收录进 llms.txt——AI 代理可直接读取。

本章按「解决什么问题」分组，先看图、再看字。逐包的集成片段与坑在仓内 docs/USAGE.md，包级事实（行数、依赖）在包清单与机器事实。

能力全景：模型与工具的每一次交互都被中间三层机制管住，落点是宿主自己的设施。

1 · 报告与协议：`protocol`

解决：模型输出的 JSON 不可信——字段漂移、置信虚高、越权字段。形态：五级容错解析 → 白名单校验 → 注入式渲染。

解析分信任级：ParseLLMReport（剥引擎侧字段，解析 LLM 产出用这个）与 ParseReport（落库往返入口）；
校验分两级：warn 留痕不拦截，critical 才 ErrViolation 整份拦；
渲染三档，标题与文案走 RenderOptions 注入；
证据面：AssignEvidenceIDs / CheckEvidenceRefs（编号唯一、引用完整）。

什么时候用：凡是「LLM 产出 → 结构化下游消费」的出口。

2 · 工具判定环：`tooldisclose` + `guardset` + `toolfail` + `policy` + `dispatch`

解决：工具调用的「披露、守卫、失败、审批、拓扑」五件事若各走各的路，必有绕过点。

任何一次工具调用（包括模型写的程序里的调用）都走同一条判定环——少接一段，那里就是唯一绕过所有门禁的路径。

tooldisclose 渐进式披露：工具面按需展开，「拒绝即激活」是正常行为；
guardset 多守卫合成：相互独立的判定一并求值，多条拒绝合成一条，可重试取「全部可重试才算」的保守侧——不要用逐个过、第一个拒绝就收口的链；
toolfail 失败是数据表：类别 → 可重试性 / 退避 / 需人工 / 重发安全 / 模型指引；只看 Retryable 不看 SafeToResubmit，重试会把一次副作用变成两次；
policy.Stage 把审批门接进判定环：工具调用、程序内调用、子进程侧调用走同一条 invoke 链，审批规则只装配一次。

什么时候用：只要你放一个工具给模型。全部接进同一条 invoke.Stage 链。

3 · 编排契约与续跑：`contract` + `statemachine` + `checkpoint` + `commitgate`

解决：状态存哪、怎么流转、崩了怎么接着跑、终态怎么独占。

左：恢复判定是纯函数，不是宿主的临场决定；右：终态独占权凭令牌，不靠内容比对认人。

contract：RunContext / StepSink / ToolBinder / Clock—— 编排引擎与宿主状态的唯一边界（纯接口面，零实现）；
statemachine：环节状态机纯谓词（含 interrupted 终态：中止 ≠ 失败）；
checkpoint：StoreCAS 跨进程 CAS 存取、并行 fan-out 按各自前驱采信；
commitgate：Acquire / ReleaseLease 凭令牌放闸。

什么时候用：编排超过一个环节、或「崩了不能全量重跑」的时候。

4 · 上下文三件套：`budget` + `spill` + `offload`

解决：上下文窗口是有限预算，不是无限历史。

三件套各管一段：进来的计量与压实、出去的溢出与取回、躺在线里的大对象。

budget：区分「工具面膨胀」与「历史膨胀」；要减账用 NetRemovedTokens（净）；
spill：截断 + 分页取回，提示契约定死；
offload：首次只标记不替换——直接替换会让模型引用一个自己没看过的东西。

什么时候用：工具面大、历史长、或产出含大对象（图片、日志、报告全文）。

5 · 程序化编排：`ptc` + `sandbox` + `cmdpolicy` + `egress` + `preset`

解决：N 轮 ReAct 往返的上下文成本与原始数据过模型面的问题。

同一个任务：上面每一轮的原始数据都要挤进上下文；下面只有一次往返，原始数据留在沙箱里。

ptc：绑定可带 Signature（净化名，撞名装配期拒）；
sandbox：档位声明与兑现（sandbox.Capable）——子进程后端用 cgroup v2 memory.max 兑现 MaxMemory，建不出即拒绝执行；
cmdpolicy：命令级判据（前缀 token 规则 + 三态裁决，规则自带样例、加载期自检）；
preset：把「档位 × 审批 × 出口」收成一份具名组合。

什么时候用：一次任务要聚合多次工具调用（多表查询、批量巡检、逐机采样）。

6 · 实时事件与流式：`eventbus` + `watchdog` + `delta` + `drain` + `pending`

eventbus：进程内有损广播——先落库再广播，SSE 断了靠 DB 回放游标补达；
watchdog：工具调用配对监视（收口/幽灵调用的判据）；
delta：增量节流（Pacer 每环节新建，长生命周期会内存涨、收口卡住）；
drain：优雅排水（用 DrainSession 而非全局 Drain）；
pending：多轮挂起态载体（落列必须走 pending.ColumnValue）。

7 · 安全面：`netguard` + `pii`

netguard：出站 SSRF 守卫——名字层 + 逐 IP 过 egress + 重定向逐跳重验 + DialFunc 建连后核对真实 RemoteAddr（闭合 rebinding 窗口）；
pii：个人信息脱敏（手机号/身份证四重校验），内核只回报信号，阻断由宿主执行。

什么时候用：模型/工具能碰外网，或报告/上下文里可能进个人信息。

8 · 副作用只做一次：`retryplan` + `sideeffect` + `sidetest`

接线范式：retryplan 判策（Retryable × SafeToResubmit 两个正交维度）→ sideeffect 执行（幂等键 + 租约 + 栅栏）。sidetest 给你的存储实现一份验收标准。

taskboard（多 agent 认领与依赖）· skilldisclose（技能渐进披露）· hookengine（钩子装配）· memorypipe（记忆管道）· ticket / trajectory（工单与轨迹）· toolname（工具名净化）· gatecheck（审批 × 档位联合判据）· sessionref / worktree / delegate（会话引用 / 工作树 / 委派）；门面三件 dispatch / policy / reminder 调用面稳定、核心归上游。

怎么选：三个判断

这判定换个宿主要不要改？ 要 → 写在宿主适配层；不要 → 可以内核机制化。
这语义跨宿主必须一致吗？（失败分类/隔离档位/终态独占）→ 用内核的机制包，别自研。
这条路径绕过判定环了吗？ 任何工具到达模型的执行面都要过同一条 invoke.Stage 链；发现第二条路 = 缺陷。