goagent-kernel

goagent-kernel · 多智能体编排通用内核

一句话：编排是代码，LLM 只做单环节——本仓只提供确定性编排的机制面， 不认识任何领域概念。

从上游私有宿主仓（代号见内部文档）拆出的内核层，宿主业务不公开。定位对标同族的 oagentkit（Agent/LLM 编排工具链矩阵）与 oekit（基础库）：独立发版、版本化引入、 零 replace（go.mod 含 replace 即门禁红；本地并行开发走 make devlink 的 workspace，见下）。

本文档导航

• README（本文）= 是什么、为什么这么设计、边界纪律
• docs/USAGE.md = 怎么接、接错了会怎样 ← 宿主开发者从这儿开始
• docs/AI-GUIDE.md = 怎么改、会被哪条门禁拦 ← 要动这个仓的 AI 代理从这儿开始
• AGENTS.md = 在本仓干活的工作纪律
• 文档站 = 介绍 / 设计初衷 / 怎么用 / 能力 / 参考（VuePress，源码在 site/）

全部文档一览（docs/ 下标着历史快照的那些记录当时的判断与踩坑， 不是当前事实；当前事实一律以本文 + 门禁 + 源码为准）：

文档	回答什么	性质
README	是什么、为什么这么设计、边界纪律、下游升级须知	活文档
docs/USAGE.md	宿主开发者：怎么把 harness 接进自己产品	活文档
docs/AI-GUIDE.md	改本仓的 AI 代理：任务 → 改哪些文件 → 哪条门禁拦 → 怎么验收	活文档
AGENTS.md	在本仓干活的工作纪律（每条纪律的事故来源）	活文档
architecture-policy.yaml	门禁声明面：模块拓扑 / 规则 / 阈值 / 例外	活文档（机器判定）
CHANGELOG.md	版本历史与破坏性变更	活文档（按 tag 切段生成）
docs/adr/README.md	决策记录（ADR）索引：每条设计取舍的编号 / 一句话结论 / 状态	决策记录（ADR）｜设计推导与取舍的真相源
docs/OAGENTKIT-OVERLAP.md	本仓与上游 oagentkit 的能力边界：哪些该做、哪些上游已有	活文档
docs/SANDBOX-DESIGN-20261021.md	执行沙箱的下一层：跨域执行与资源兜底（发现「内存无兜底」真缺陷 + 与上游 guardx 的分工）	活文档
docs/HARNESS-BENCHMARK-20261021.md	对标 Codex / DSH / Octop / Coze 五家：借鉴了什么、什么归宿主、什么本轮没做	活文档
docs/GAP-ANALYSIS-20261021.md	与 Codex / DSH / Octop / Coze 的逐项实测对齐：差距在哪个维度、哪些该补、哪些不该补	活文档
docs/GAP-ANALYSIS-20261106.md	同一对标的刷新（2026-11-06 重拉五家）：Coze 已停更、DSH 219→400 叶子包、缺口从「可撤销性」移到「判定面的宽度」	活文档
docs/GAP-ANALYSIS-20261107.md	第三次刷新（2026-11-07 重拉五家）：参照系这轮没长出新机制面；唯一开着的 P0 是出口强制件的两端都空（无代理 + 无 Enforcer 实现）	活文档
docs/CROSS-ENV-VERIFY-20261021.md	跨环境验证：平台相关的机制怎么在「CI 绿但其实跳过」的情况下真验（实测环境矩阵 + 交叉编译流程）	活文档
docs/CHECKPOINT.md	续跑契约的设计推导、三条不变量与跨进程闸	活文档
docs/ENGINEERING-HISTORY.md	「工程底座」表九轮校准的过程与账：为什么它漂过、后来怎么接进门禁	历史快照（从 README 下沉，2026-11-11）
docs/SPLIT_PLAN.md	从宿主仓拆分的分层依据（L1/L2/L3）	历史快照（2026-10-17 写于 10 个包时）
docs/MIGRATION_OAGENTKIT_20261018.md	门面迁移与 errors 链路改写的执行记录	历史快照（已于 2026-10-18 执行完毕）
docs/SELF-AUDIT-20261018.md	独立复核发现并修复的缺陷	历史快照（2026-10-18 收尾）

边界：本仓有什么、没有什么

✓ 有（机制，与领域无关）        ✗ 没有（资产，属于宿主/领域包）
─────────────────────────      ──────────────────────────────
protocol   统一报告协议          专家包 / 专家清单 / 技能
           宽容解析 + 结构化校验  诊断链 / 编排图（faultChain 等）
           白名单校验            运维词表（巡检域、K8s 词面…）
           Markdown 渲染         目标类型（主机 / 集群 / Pod）
contract   编排运行契约（唯一边界） 宿主状态的落库方式与并发约束
statemachine 环节状态机          审批风险分级（restart/delete 四档）
eventbus   进程内有损广播        拓扑内容（谁允许派发谁）
policy     操作审计门            品牌文案（报告标题、引导 agent 名）
spill      输出预算溢出          事件持久化与表结构
budget     输入侧上下文预算      摘要生成的具体实现（走 Summarizer 接口）
offload    内联大对象外置        IM 通道 / 通知模板
toolfail   工具失败分类契约      HTTP 路由 / 鉴权
tooldisclose 渐进式工具披露 + 调用门禁    工具实现（MCP server）
guardset   守卫装配与拒绝合成      具体守卫实现（披露门/出站门/审计门）
pii        个人信息脱敏          工具目录内容（本包只管披露与门禁）
netguard   出站 SSRF 守卫        诊断链/巡检图（编排图属宿主）
dispatch   派发守卫（权限即拓扑） 摘要策略（何时压实属宿主）
ptc        程序化工具编排沙箱    环节语义（收口/幽灵结果的具体判据属宿主）
watchdog   工具调用配对监视      工具描述文案
checkpoint 编排续跑契约          快照的存储介质（SQLite / PG / 文件）
commitgate 环节终态独占提交闸    并行分支的冲突裁决（该归宿主还是机制）
delta      增量节流 + 标签分流   模型供应商路由
sideeffect 副作用至多一次契约   幂等键的存储实现（Redis / PG / etcd）
sidetest  副作用闸契约测试套件   存储实现的并发正确性（原子性 / 跨进程）
retryplan 重试处置决策          幂等键的具体存储（内核只给路径，不给实现）

判定口诀：「这个包需要知道自己在给谁干活吗？」需要 → 属于宿主。

包清单

「生产行数」口径：wc -l 统计 *.go 且不含 _test.go——包体量看的是要交付的实现， 不是它的测试。依赖列只列仓外 import；「无」表示该包生产代码只用 stdlib。

本表由 make check 末步的 docsync 机器校验（cmd/docsync），判定分两类： 依赖列逐项相等——加依赖是显式动作，必须同步；行数按 25% 相对容差判定 ——容差内的逐行涨落不拦，改一行代码不必顺手改文档，而跨量级的误述 （某包声称 ~86 行、实际 412 行那种）仍然拦下。行数取较大者为分母， 「少写」与「夸大」同等对待。职责列与依赖列非空也在判定内。

internal/ 下的包刻意不在本表：它们是内部件，不是对外承诺（docsync 的 反向收录判定只看一级目录，故 internal/subhub 不会要求一行）。但它们不受 「未登记包」豁免——architecture-policy.yaml 的 modules 段照样要给 {id, roots, requires, owner}，否则依赖方向门禁判它「对本门禁隐形」。

特性

边界不是文档，是门禁

「内核不许长出领域知识」这句话写在散文里就会烂掉——本仓把它做成了 8 条正则规则 + 6 条 go/ast 结构性规则（门包不变 / 依赖方向 / 沙箱档位登记 / 执行路径 / 子进程出口 / 未受管逃逸），全部挂在 make check 上，CI 只执行这一条。 分界线很清楚：散文不是门禁——真有人往门面包里塞一份实现，规则不响，结果是与上游并存的第二份实现。

设计推导见 ADR-0001

工具调用只有一条路

渐进披露、披露门、多守卫合成、失败分类、程序内调用——全部接成同一条判定环，包括 ptc 里模型自己写的 host.<tool>()。 少接一段，那个位置就成了整条链上唯一绕过所有门禁的路径。

普通工具调用 ─┐
             ├─→ invoke.Stage 链 ─→ guardset(并求值·合成拒绝) ─→ tooldisclose(披露门)
ptc 程序内   ─┘                            └─→ policy(审计门) ─→ dispatch(派发拓扑)

guardset 补的是「链在第一个拒绝处就收口、模型一次只听得到一个理由」那一面：多条拒绝合成一条，取「全部可重试才算可重试」的保守侧，并点出该先处理哪一条。

崩了能接着跑，而且不会「两条分支都赢了」

checkpoint 把恢复判定做成纯函数：可信边界按依赖判定、终态不自动重开、序号单调闸。 commitgate 用独占提交闸保证终态只被提交一次（statemachine 是纯谓词、SeqGate 只排快照序号，都排不出「两条并发分支都以为自己赢了」）。 为什么：临场决定必然选最坏的那个（要么盲目全量重跑、要么盲目跳过）；终态独占权必须单独一道闸，且 Commit / Release 成对。

上下文是有限预算，不是无限历史

三件套分工泾渭分明：budget 管输入侧分段计量与压实、offload 管二进制本体躺在消息里（两阶段：首次只标记不替换，否则模型会引用一个自己从没看过的东西）、spill 管输出侧截断与分页取回。 为什么：只给总数无法区分「工具面膨胀」与「历史膨胀」，而两者处置完全不同。

失败是数据表，不是散落的 if

toolfail 把「类别 → 可重试性 / 退避 / 需人工 / 重发安全 / 模型指引」做成数据表，不可归类一律不可重试（fail-closed）。 为什么：重发安全与重试价值是两个正交维度——超时值得重试，但服务端可能已执行，原样重发就是重复施加副作用。

N 轮 ReAct 往返塌缩成 1 轮

ptc 让模型写程序、进程内 goja VM 执行、程序内经 bindings 调宿主工具，只把归并后的小结果带回上下文：原始数据不过模型面。 为什么：三重预算（墙钟 / 调用数 / 字节数）替代 OS 沙盘，纯 Go 零 CGO，无 Node 分发面。

工程底座

上表分两类：前两行有机器判定，其余仍是散文（issue #31）。

✅ 已判：生产代码行数 / 文件数 / 测试文件数——三项由 docsync 判相等，不留容差。 包表那 25% 容差是给「逐行涨落」留的噪声滤波，而这张表的历史漂移量恰好落在容差里 （895 / 578 / 573 行相对 1.9 万行都在 3% 上下），给它容差等于让静默过期继续成立。 口径就是本段末尾那三条命令，门禁报错时也会原样给出来。

⚠️ 未判：覆盖率与其余四行。

• 覆盖率不判是刻意的：它随「跑的是哪个用例集合」变——2026-11-06 同一批用例、 生产代码一行未改，量出 85.5 / 85.0 / 87.0 三个值。让散文去复述一个由门禁实时 给出的数字，只会制造两处不一致；故这一格只写门槛（门槛由 Makefile 判，不会漂）， 实测值看 make cover-gate 的输出。
• 结构阈值 / 门禁条数 / 例外登记数是描述，各自有执行体（policy + 各条门禁）， 写错不会让门禁失效、只是描述不准——判定成本高于收益，故不判。

于是「改这张表」的规矩变成两半：前两行照门禁的报错改（它会告诉你实测值）， 其余行改前请手算，别信上一版。 v0.6.4 那次修「工程底座」三处漂移（生产代码 11,491 行/66 文件 → 13,336 行/77 文件、 测试 84 → 99 个文件、覆盖率 80.4% → 86.6%）时，这三处已经过期了三个月—— 它们是 archcheck 从 cmd/ 下沉成独立包（2026-10-19）之前的旧值，此后没人更新。 这正是本仓「散文不是门禁」那条纪律的反面案例：机器只管得着被写成规则的那部分。 改这张表时请手动重算，别信上一版。

重算口径（照抄这三条，别手算）——「生产代码」= 全仓非 _test.go 的 .go， 排除隐藏目录与 vendor：

find . -name '*.go' -not -name '*_test.go' -not -path './.*' -not -path './vendor/*' | wc -l
find . -name '*.go' -not -name '*_test.go' -not -path './.*' -not -path './vendor/*' -print0 | xargs -0 cat | wc -l
find . -name '*_test.go' -not -path './.*' -not -path './vendor/*' | wc -l

覆盖率取 make cover 的最后一行（go tool cover -func=coverage.out | tail -1）。

2026-11-06 第八轮校准（生产代码一行没动）：19,624 行 / 113 文件未变，测试文件 139 → 141（sandbox/forwarders_test.go、cmd/docsync/run_test.go），覆盖率 85.5% → 87.0%。这 +1.5pp 全部来自补测，不是新写的生产代码：sandbox 60.0% → 100%、cmd/docsync 23.6% → 88.8%（run() 端到端，用 t.Chdir 造夹具）。

中间有一次「只补了 sandbox」的测量是 85.0%——比上一版低 0.5pp，而生产代码 没变、只多了一个测试文件。这件事本身值得记下来：这张表的数字会随测量口径与批次 漂（同一批用例在不同轮次里给出 85.5 / 85.0 / 87.0 三个值）。

2026-11-06 第九轮（这一轮把表接进了门禁，issue #31）：19,624 → 20,397 行 / 113 → 118 文件 / 141 → 146 个测试文件（+773 行）。前两行从此由 docsync 判相等，报错时会把实测值与三条重算命令一并给出，不需要再靠「记得回来手算」； 覆盖率那一格删掉了手抄的百分数，只留门槛（门槛由 Makefile 判）。 这一轮记下的教训是：「会漂的数」与「不会漂的数」要分开对待——覆盖率属于前者， 让它出现在散文里，就等于承认「这里迟早会说谎」；行数/文件数属于后者，那就判相等， 连容差都不该给。

同日补的第四条门禁口径：cover-gate 从「只判全局」变成「全局 + 逐包下限 70%」。 起因是全局 85.5% 同时掩盖着 cmd/docsync 23.6% 与 sandbox 60.0%——单个包的 塌方在大盘里完全看不见。sandbox 的 60% 已补到 100%（门面包的每条语句就是 一句转发，转发目标或参数顺序写错编译得过、语义却错，故对门面包而言语句覆盖率 恰好是恰当的度量）；cmd/docsync 当时先登记豁免（判定逻辑仍在 package main、 没有可注入的接缝），同日即拆除——改用 t.Chdir 造夹具后 run() 端到端可测， 23.6% → 88.8%，PKG_COV_EXEMPT 现已为空。

2026-11-06 第九轮校准（差距台账落地轮）：上一版记的 19,624 行/113 文件、141 个测试 文件、87.0%，这一轮按 docs/GAP-ANALYSIS-20261106.md 落了 P0-1/P0-2、P1-1..P1-5 与 五项 P2（cmdpolicy / egress / preset / sessionref / taskboard / skilldisclose / hookengine / memorypipe / delegate / worktree，外加 archcheck 的样例自检与子进程出口判据），实测 23,281 行 / 130 文件、156 个测试 文件、87.6%；门禁表里「依赖方向」那一格也从 34 包改为 42 包（archcheck 实测）。 这一轮值得记一笔的不是行数涨了 3,657——而是十条门禁里有两条是这一轮才有的 判定面（规则样例自检、子进程出口），它们此前都是「有声明、没人判」。

平台支持矩阵（2026-11-06 补齐）

此前本仓从未声明支持哪些平台，也没有任何东西验过——本机 darwin 全绿，而本仓是 「被宿主编进二进制」的库，真正的交付面是 linux。2026-11-06 实测才发现 Windows 根本编不过，而这个事实在仓里一个字都没有。

处置方式：显式声明不支持，而不是留着「看起来支持、其实编不过」。make crossbuild 只判 CROSS_TARGETS 里列出的平台——为一条永远编不过的目标留门禁不是严谨，是把红线 泡软：它会常年红，然后被人忽略，连带把别的红一起忽略掉。

要在 Windows 上使用，前提是上游 procx 先给出可移植的进程组实现；在那之前本仓 ptc 的子进程后端不适用于 Windows。这条限制不在本仓能力范围内，故不做兼容层。

三条「目标存在但没人跑」的门禁（2026-11-06 补齐）

2026-11-06 的仓库审计里有三条门禁的共同形态：目标/文档里有，但没有任何东西执行它——这和 lint 当年一模一样（见 Makefile 的 lint 注释）。 处置方式也一样：接进 make check，不挂到 ci.yml 上变回「推送后门禁」。逐条实测漏项如下。

顺带补上的第四条：覆盖率此前只判全局。全局 85.5% 同时掩盖着 cmd/docsync 23.6% 与 sandbox 60.0%——大盘涨 1% 就能抵消一个包从 70 掉到 20 的塌方，而报告里只有一行「85.5%，绿」。 故 cover-gate 现在跑两条判据（逐包判据的执行体是 cmd/pkgcov——原先是 scripts/pkgcov.awk，issue #36 收编为 Go 并带上自己的用例），且逐包下限的豁免失效即红（豁免包一旦自己达标，门禁会要求当天删掉那条豁免——本轮就是这样把它拆掉的：cmd/docsync 补测到 88.8% 后第一次跑门禁，报的正是「豁免失效，请从 PKG_COV_EXEMPT 移除」，而不是默默放行）。

头号红线：不得长出领域知识

拆分做完后最现实的风险不是拆不动，而是业务代码一年年渗回内核，等发现时内核已经退化成「换了个名字的 monolith」。 这条红线的规则清单、推导与事故来源已下沉成 ADR 集——README 只留结论，入口是 ADR 索引：

通用化判据

内核每加一个能力，先过这一问：换个宿主，这段代码要不要改？ 要 → 属于宿主，不该在内核。 落到三条可执行约定：判定语义归内核、判定依据归宿主；展示文案归宿主；测试夹具用合成数据。

设计推导见 ADR-0006

文档站（GitHub Pages · VuePress）

yi-nology.github.io/goagent-kernel

VuePress 文档站：介绍、设计初衷、怎么用（接入路线图 + 最小示例）、能力详解（九组）、 门禁体系、坑速查、包清单与机器事实。

站点源码在本仓 site/（docs/ 内容 + gen.mjs + .vuepress/config.js）， 发布走 .github/workflows/pages.yml（build_type: workflow）： push 到 main 且站点内容或其事实输入（README.md / go.mod / Makefile / architecture-policy.yaml / docs/USAGE.md）有变更时，CI 自动构建并部署。

本地构建：

make site     # = cd site && npm ci && npm run docs:build（开发预览：npm run docs:dev）

站点上的每个数字都不手抄。 生成器 site/gen.mjs 在每次构建前把 README（包表 / 工程底座）、go.mod（依赖版本）、architecture-policy.yaml（规则清单）、Makefile （覆盖率门槛）、docs/USAGE.md（坑速查表）抽成站点页——解析不到即构建失败， 不静默填默认值。生成页不入库（入库就会没人重新生成，等于把「自动」改回「手抄」）。 理由与本仓其它纪律同源：手抄一遍就等于多一份会静默失真的真相。

迁移记录（2026-11-11）：站点原先住在 gh-pages 独立分支（build_type: legacy）， 生成器与源码不在 main 里——恰好违反本仓「单一真相」的纪律。当日迁回 site/ 并升级为 VuePress 文档站；gh-pages 分支冻结为历史归档（迁走前的最后一版， 只作对照，不再接收产物）。

快速开始

要接入本仓：直接看 docs/USAGE.md，那是按「宿主接入顺序」 组织的完整指南——九组能力逐个讲清「职责 → 最小集成片段 → 关键符号 → 坑」， 末尾有一张按症状索引的坑速查表。

要改本仓：

make build          # 编译 archcheck
make test           # 全量单测
make check          # fmt + vet + lint + test + cover-gate + vuln + race + crossbuild + architecture-check + docsync + 仓库卫生
make architecture-check --report   # 看全量违规清单（默认前 10 条）

macOS：本机 go build/test 一律带 CGO_ENABLED=0（新 SDK 27.0 与 CLT linker 不兼容 + 许可未接受），Makefile 已内置。

make check 需要 golangci-lint（CI 钉 v2.14.0）；未安装时该目标明确报错退出， 不静默跳过——没人跑的门禁等于没有门禁。

提交与合并

main 有分支保护：必须走 PR，且必须通过两条检查——

• fmt + vet + lint + test + cover-gate(全局+逐包) + vuln + race + crossbuild + archcheck + repo 卫生（Linux 综合门禁）
• windows (真跑测试)（Windows 上真执行，不是只编译）

两条都是 strict（需与 main 同步）。管理员保留 bypass 通道（应急直推）， 但门禁本体全在 make check 里——本地能过，CI 就该过；CI 红了先看日志分清 「真违规」与「基建抖动」，不要绕过。

这条保护是 2026-11-11 开的（issue #77）。此前 main 完全无保护，直推即合， CI 通过与否与能不能合无关——于是「CI 是绿的」不再等于「能合」， 门禁的失败形态又变回了「变绿」。

本地多仓并行开发

本仓处在 oagentkit / oekit 矩阵里，改本仓时经常要同时改上游仓（如 guardx）。 这里有个必须知道的陷阱：

Go 的 replace 只在主模块生效，依赖模块的 replace 不级联。

在本仓 go.mod 里写 replace github.com/oagentkit/guardx => ./.guardx-work/guardx， 本仓构建全绿（自己就是主模块）；但下游宿主把本仓当依赖时，这条 replace 被静默忽略， guardx 按 MVS 回落到已发布的旧版本，于是报 no required module provides package github.com/oagentkit/guardx/injectband—— 错指 guardx，真正原因（本仓依赖了未发布的新包）不出现，一行本地验证代码断掉所有下游。

正确姿势是 workspace（use 跨仓生效，且不碰任何 go.mod）：

git clone https://github.com/oagentkit/guardx.git .guardx-work/guardx   # 未跟踪
make devlink     # 生成本地 go.work，把 guardx 工作副本接入
# ...改 guardx，本仓构建即时生效...
make devunlink   # 断开，构建回到 go.mod 声明的已发布版本

配套纪律：

1. go.mod 零 replace。 go.mod 不得含 replace / go.work 不得入库 两条门禁在 make check 里（本地与 CI 同一条路径），本地 go.work 由 .gitignore 兜底。
2. go.mod 里 require 的版本必须是已发布的 tag。 若确需依赖未发布的新包， 用 make devlink，不要动 go.mod。CI 在干净环境构建，未发布版本解析不到直接红—— 这是发版顺序纪律的第二道防线。
3. workspace 期间别跑 go work sync。 它按 workspace 的构建列表回写各模块的 go.mod / go.sum：仓不全时用不到的依赖会被直接删掉（实测把 oagentkit 的四个依赖 整片剥掉）。要整合同步，先 make devunlink，再在单模块下 go mod tidy。
4. make devlink 可重复执行。 已有 go.work 时走 go work use -add 追加而不是 重建，所以往 workspace 里加第二个仓不会抹掉别人已加的条目。
5. 验下游而不是只验本仓。 本仓作为主模块绿，不代表作为依赖也绿（replace 的失效就发生在这个差别里）。

下游升级须知（破坏性变更）

本仓的公开 API 里有一部分类型来自上游矩阵（invoke 判定环原语）。上游把它换了包， 本仓跟随，下游的 import 路径就要跟着换——这类变更记在这里，不记在 tag 注解里 （tag 注解会沉到 git 历史里，README 不会）。

受影响的本仓 API（签名里带 invoke 类型）：

guardset.Guard          // Check func(ctx, c invoke.Call) invoke.Verdict
guardset.Set.Evaluate   // (ctx, c invoke.Call) Outcome
guardset.Stage          // invoke.Stage
tooldisclose.Stage      // invoke.Stage
ptc.Options.Stages      // []invoke.Stage

依赖面变轻了：判定环从 eino 重仓挪到了零依赖底座。下游若自己 import 过 toolgate/invoke，那条依赖曾把 eino 拖进下游的模块图，现在没有了。

宿主接入

go get github.com/yi-nology/goagent-kernel@latest

require github.com/yi-nology/goagent-kernel v0.29.0   // 零 replace，直接版本化引入

升级前用 git ls-remote --tags origin 核候选版本真的存在—— go list -m -versions 报的是 proxy 的缓存目录，不是远端现实。 当前已发布 tag 以远端为准（写稿时为 v0.29.0）。

⚠️ require 里写的是「最低版本」，不是「锁定版本」：下游 go mod tidy 只保证不低于这个版本，不会自动升到最新版。要用新版本必须显式 go get ...@<新版本>——这也是为什么这里写当前版本号而不是 v0.0.0。

import "github.com/yi-nology/goagent-kernel/dispatch"

// 派发守卫：宿主提供拓扑，harness 提供机制
type myEdgeSource struct{ reg *myRegistry }

func (s myEdgeSource) Slugs() []string                   { return s.reg.Slugs() }
func (s myEdgeSource) DispatchAllow(slug string) []string { return s.reg.Allow(slug) }

g := dispatch.NewGuard(myEdgeSource{reg: reg}, maxDepth) // 矩阵含环会在构造期 panic
if err := g.Assert(caller, callee, depth); err != nil { /* 结构化 *dispatch.DenyError */ }

⚠️ 上面只是九组能力之一的片段。完整接入路线图见 docs/USAGE.md： 契约面（contract + statemachine）、工具判定环（tooldisclose + guardset + toolfail）、报告协议（protocol）、续跑契约（checkpoint + commitgate）、 上下文三件套（budget + spill + offload）、实时事件、流式与退出、 安全面（netguard + pii）、程序化编排（ptc）、门面三件。

宿主侧的安全不变量（如「全拓扑只有一条边能到达执行器」）的断言测试应留在宿主仓—— 那是产品级承诺，不是内核机制属性。dispatch/guard_test.go 用合成拓扑测机制， 可复用于任何宿主。

演进纪律

• 新增能力前先问：这是机制还是资产？ 资产进宿主/领域包，机制才进本仓。
• 新依赖方向先改 policy 再写代码；例外带注释写明拆除条件。
• 改了包或门禁，同步本 README 的包表：新增/删除包、改外部依赖、改生产行数跨过 25% 容差——三者任一发生就要改表，make docsync 会拦。
• 内核包规模远小于宿主，max_file_lines: 400 直接阻断（宿主仓是报告口径）。 2026-10-18 起 thresholds.enforce 由 false 切 true：此前 3 处超长文件 （protocol/report_types.go 660、protocol/report_test.go 782、 cmd/archcheck/main.go 490）已拆分归零，2026-10-19 起执行体整体下沉为 archcheck 包，切换条件才成立。拆分只为满足 机械阈值，单文件读不动时该模块应重新分组，而不是继续往上加。
• 拆自宿主仓的代码历史见 docs/SPLIT_PLAN.md——那是 2026-10-17 写于 10 个包时的分层依据快照，其中「L2/L3 待拆」一节描述的是当时的待办， 不是当前包清单（当前清单见本文「包清单」表）。