# goagent-kernel

> 多智能体编排的通用内核（Go library）。**编排是代码，LLM 只做单环节**——
> 只提供确定性编排的机制面（报告协议 / 工具判定环 / 续跑契约 / 上下文预算 / 执行沙箱），
> 不认识任何领域概念：专家包、诊断链、词表、拓扑、文案全部属于宿主。
> 文档站: https://yi-nology.github.io/goagent-kernel  |  GitHub: https://github.com/yi-nology/goagent-kernel

> 本文件由 `site/gen.mjs` 生成，数字取自 README / go.mod / architecture-policy.yaml / Makefile，随构建刷新。

## 判定口诀
「这个包需要知道自己在给谁干活吗？」需要 → 属于宿主，不属于内核。换个宿主要改的代码不该在内核。

## 三个必须先知道的约束
1. **内核只判定，不处置**：内核回报「该阻断/该重试/不可归类」，动作由宿主执行。
2. **门面的门朝外**：dispatch / policy / reminder 只做调用面转发，核心在上游 oagentkit。
3. **单向依赖**：本仓不 import 宿主，宿主 import 本仓（门禁强制）。

## AI 直读入口（同族）
- oekit（基础库矩阵）: https://oekit.github.io/llms.txt
- oagentkit（Agent/LLM 编排工具链矩阵）: https://oagentkit.github.io/llms.txt

## 文档（人读）
- 介绍（是什么/边界/依赖链）: https://yi-nology.github.io/goagent-kernel/guide/introduction.html
- 设计初衷（为什么长这样）: https://yi-nology.github.io/goagent-kernel/guide/philosophy.html
- 怎么用（安装/三约束/接入路线图）: https://yi-nology.github.io/goagent-kernel/guide/getting-started.html
- 能力详解（九组图解）: https://yi-nology.github.io/goagent-kernel/guide/capabilities.html
- 坑速查（症状→真因）: https://yi-nology.github.io/goagent-kernel/reference/pitfalls.html
- 包清单与机器事实: https://yi-nology.github.io/goagent-kernel/reference/packages.html
- 门禁体系: https://yi-nology.github.io/goagent-kernel/reference/gates.html
- 决策记录（ADR，设计推导与取舍）: https://yi-nology.github.io/goagent-kernel/reference/adr.html
- 完整接入指南（逐包：职责→片段→符号→坑）: https://github.com/yi-nology/goagent-kernel/blob/main/docs/USAGE.md
- README（边界纪律/下游升级须知）: https://github.com/yi-nology/goagent-kernel#readme

## 事实快照
- 模块: `github.com/yi-nology/goagent-kernel` · Go · MIT · 零 replace（go.mod 含 replace 即门禁红）
- 能力包 41 个；生产代码 28,332 行 / 154 文件；测试 192 个文件
- 覆盖率门槛: 全局 60% + 逐包下限 70%
- 门禁规则 8 条 + go/ast 结构判定；依赖方向登记于 `architecture-policy.yaml`
- 平台: linux/amd64 · linux/arm64 · darwin/arm64 · windows/amd64（进程树语义降级）

## 包一览（41）
- `protocol` — Report 契约 + 五级容错解析 + 白名单校验 + Markdown 渲染
- `dispatch` — allow 矩阵物化 + 深度上限 + 自派发拒绝 + 环检测（拓扑经 `EdgeSource` 由宿主提供）
- `eventbus` — 进程内有损广播（缓冲 chan）
- `policy` — 操作审计门：阈值只降不升、解析失败即拒
- `spill` — 输出预算溢出：提示契约 / 取回 / 按龄清理
- `pii` — 个人信息价值面脱敏（手机号 / 身份证四重校验）
- `netguard` — 出站 URL 守卫（SSRF）：名字层（解析前按名拒）+ 解析后逐 IP 过 egress + 重定向逐跳重验
- `statemachine` — 环节状态机：条件迁移的纯函数件
- `contract` — 编排运行契约：编排引擎 ↔ 宿主状态的**唯一边界**（纯接口面，零实现）
- `checkpoint` — 编排续跑契约：进度快照存取边界 + **「续跑而非重放」**的恢复判定（空洞不采信 / 终态不自动重开 / 序号单调闸）…
- `commitgate` — 环节终态独占提交闸：同一 (run, 环节) 的终态只允许被提交一次（`statemachine` 是纯谓词，`SeqG…
- `budget` — 上下文预算：分段计量 + 窗口钳位 + 压实计划骨架（三重空转守卫
- `offload` — 内联大对象外置：sha 去重 + **两阶段**（首次标记、后续轮才替换占位）+ fail-soft（与 `spill`…
- `tooldisclose` — 渐进式工具披露（确定性打分检索换完整 schema）+ 执行门禁（**未加载可重试 / 不在目录禁止绕过** 两类严格二…
- `toolfail` — 工具失败的错误分类契约（**门面**，核心在 `oagentkit/guardx/toolfail`）：类别 → 可重试…
- `toolname` — 工具名 → 程序内可用的 JS 标识符：**一条单一真相**
- `sideeffect` — 副作用「至多一次」的跨进程契约：**幂等键**（同一逻辑动作重试不重复施加）+ **租约**（同一资源独占，带 TTL）…
- `sidetest` — sideeffect.Store 的**共享契约测试套件**：宿主写完存储实现后跑一遍，违反哪条契约就红在哪一条——免得…
- `cmdpolicy` — 命令级判据：把判定面从「工具调用」**向下延伸到工具内部实际执行的那条命令**
- `egress` — 出口策略：**三档**（`ModeUnrestricted` < `ModeProxy` < `ModeDenied`，…
- `gatecheck` — 审批层与沙箱层的**联合判据**：Codex 的两层安全模型是「沙箱强制 + 审批策略，**两层都同意才放行**」
- `preset` — 命名权限预设：把「隔离档位 × 审批模式 × 出口策略」三件散参数收成一份**具名、只读、加载期自检**的组合（`Pre…
- `retryplan` — 重试处置决策：把「该不该重试」（`toolfail` 判）与「重试会不会重复施加」（`sideeffect` 判）合成*…
- `delta` — 增量节流：分片合并 + 权威整段优先 + 确定性收口扫序
- `pending` — 多轮挂起态载体：单一编码入口 + 宽容解码（非法值降级为无挂起）
- `reminder` — 系统注入提示的防伪包裹（门面）：核心已下沉 `guardx/injectband`，本包只保调用路径稳定，宿主调用点一行…
- `sessionref` — 跨会话引用快照：把**另一个会话的结论**以有界、带来源、带失效点的片段注入当前上下文
- `drain` — 优雅排水：轮 ctx 取消脱钩 + 等在途收敛 + 预算耗尽强制收刀（经 `Turns` 接口）
- `ptc` — 程序化工具编排：模型写程序 → 沙箱 VM 执行 → 经 `bindings` 调宿主工具
- `sandbox` — 执行沙箱的**档位语义**与**后端协议**（**门面**，核心在 `oagentkit/guardx/sandbox`…
- `watchdog` — 被动配对不变量监视：环节收口仍有未执行声明 / 结果无对应声明
- `guardset` — 守卫装配契约：一组**相互独立**的判定一并求值，多条拒绝合成一条（按 Rank 定序、**不可重试优先**的保守裁决、…
- `archcheck` — 架构门禁执行体：`architecture-policy.yaml` 的**可执行面**（规则判定 / 门包判定 / 依…
- `trajectory` — 轨迹投影器：**事件流 → 一轮 turn 的步骤序列**（增量投影：喂新事件继续更新既有行）
- `taskboard` — 多 agent 协调面的**存储中立契约 + 一致性判据**：`dispatch` 只回答「能不能派」，派出去之后「谁负…
- `skilldisclose` — 技能披露：**确定性**挑出该给模型看的那几个技能
- `hookengine` — Hooks 的**判定面**（不是传输面）：Codex 是「外部进程协议 + 规则文件」，DSH 是「动态插件包」，形态…
- `memorypipe` — 记忆注入的三段：**注入 / 引用 / 打标**（读写时机与摘要生成归宿主，与 `budget` 留 `Summariz…
- `delegate` — 异构委托的**契约面**：ACP 一类东西同时是协议 + 传输，线格式归上游
- `worktree` — 工作区隔离的**声明面与冲突判据**（**不碰真实文件系统**——建目录/挂载/chroot 是宿主与执行后端的活）
- `ticket` — 一次性短时授权票据的机制面：签发 / **单次消费**（用过即焚）/ TTL / **用途绑定**（载荷原样携带，语义归…