# oagentkit

> Open Agent Kit — Agent / LLM 编排工具链模块矩阵。13 个独立发版的 Go 模块：模型客户端、MCP 工具池、技能库、知识检索、Agent 编排、运行时基础设施。

oagentkit 是一套按**框架耦合分层**组织的 Go 模块矩阵。依赖严格自底向上，每仓独立 SemVer + 独立 CI。**每个仓库根目录都有 AGENTS.md**（面向 AI Agent 的规范与硬规则）。

## 与 oekit 的关系

oagentkit 是一套**独立矩阵**，与 [oekit](https://oekit.github.io/llms.txt)（Open Easy Kit，Go 微服务工具链）是姊妹项目。oagentkit **依赖** oekit 的：

- `github.com/oekit/pkg` — 微工具集（errors/stringx/encoding/mathx）
- `github.com/oekit/concurrency` — goroutine 池/单飞/重试/令牌桶/滑动窗口/时间轮
- `github.com/oekit/logx` — 日志门面

两者只共享 `o`/`kit` 元素，**不是子品牌关系**。

## 版本矩阵（机器可读）

- https://oagentkit.github.io/versions.json（由 matrix-tools `scripts/gen_versions.py` 生成）
- 矩阵数据源：[matrix-tools/modules.json](https://github.com/oagentkit/matrix-tools)（13 模块 / 52 包）

## 破坏性变更

登记在册的破坏性变更共 16 条（由各仓 CHANGELOG 自动抽取，机器可读同源见 versions.json 的 `breakingIndex` 字段）：

- **textx v0.6.1** — 修复(agents)：审计日志归属改为 obs/audit（guardx/audit 已迁出）
  包在模块之间搬家：audit → guardx/obs
- **runtime v0.5.0** — 重构：移除本仓的 breaker 实现，迁到 oekit/concurrency/breaker
  github.com/oagentkit/runtime/breaker 不再存在。迁移方 import github.com/oagentkit/runtime/breaker -> github.com/oekit/concurrency/breaker 注意语义差异：上游三态由「窗口丢弃概率>0 或连续失败达阈值」触发， 而本仓原实现是纯计数型；且 Breakers 多实例注册表改为按 name 取 NewBreaker/GetBreaker。 已知上游缺口：计数型触发只切状态、切不了放行决策 （https://github.com/oekit/concurrency/issues/25），由 llm 仓的准入适配层兜底。 门禁：go build / go vet / go test -race 5 包全绿，gofmt 干净。
- **guardx v0.7.0** — 重构：audit / bashguard 迁出本仓，回到单 module 零依赖
  github.com/oagentkit/guardx/audit 与 github.com/oagentkit/guardx/bashguard 不再属于本仓模块。 迁往：
- **guardx v0.6.0** — 新增(logredact)!：规则表可组合 + 保定位线索掩码档；audit/bashguard 拆嵌套模块
- **obs v0.9.0** — 重构：obsx 迁出本仓 —— eino 耦合的观测适配层该待在重仓
  github.com/oagentkit/obs/obsx → github.com/oagentkit/llm/obsx obsx 是 eino callbacks 适配层（intrinsically 绑 eino 框架）。它在本仓时， **langfuse 与 audit 这两个轻包被白拖 27 个第三方模块**（eino + sonic 全家）—— Go 的依赖面按 module 结算。 迁到 llm（本仓早已 import obsx 做成本记账与阶段打标，同一关注点）后：
- **obs v0.8.0** — 新增(audit)：接收 guardx/audit —— 审计留痕落到本来就带 logx 的仓
  包在模块之间搬家：audit → guardx/obs
- **rag v0.6.0** — 重构(rag)!：包上移至 module 根，import 路径不再重复末段
  import 路径 github.com/oagentkit/rag/rag → github.com/oagentkit/rag。 包名 rag 恰好等于仓名 rag，留在 rag/ 子目录会产出 stutter 的公开路径 （Go 惯例：包名不重复 import 路径末段）。 矩阵 import 规则随之收敛：matrix_paths.new_import_path 在「包名末段 == 仓名」时 收口到 module 根，不再拼末段。这是该规则的**唯一例外**，写在唯一构造点里， gen_versions / gen_llms_txt / rewrite_imports / test_matrix_paths 全部随之生效。 与 oagentkit/llm 同批：全矩阵 47 个包中只有这两处仓名=包名。
- **llm v0.12.0** — 新增(obsx)：接收 obs/obsx —— LLM 调用观测与模型客户端住在一起
  包在模块之间搬家：obsx → llm/obs
- **llm v0.9.0** — 重构(llm)!：包上移至 module 根，import 路径不再重复末段
  import 路径 github.com/oagentkit/llm/llm → github.com/oagentkit/llm。 包名 llm 恰好等于仓名 llm，留在 llm/ 子目录会产出 stutter 的公开路径 （Go 惯例：包名不重复 import 路径末段）。 矩阵 import 规则随之收敛：matrix_paths.new_import_path 在「包名末段 == 仓名」时 收口到 module 根，不再拼末段。这是该规则的**唯一例外**，写在唯一构造点里， gen_versions / gen_llms_txt / rewrite_imports / test_matrix_paths 全部随之生效。 llmtest 与 wrap 的末段 ≠ 仓名，路径不变（oagentkit/llm/llmtest、oagentkit/llm/wrap）。
- **toolgate v0.12.0** — 重构：invoke 迁出本仓 —— 框架无关的原语不该被 eino 重仓的地板拖住
  github.com/oagentkit/toolgate/invoke → github.com/oagentkit/guardx/invoke invoke 的包文档自证「刻意不携带任何框架类型：本包与 policy/toolegate 无耦合」—— 它是框架无关的原语，自身 import 面只有 oekit/pkg/errors，却在带 eino 家族的重仓里 让消费方白吃 34 个第三方模块。 policy 改为依赖 guardx/invoke（tier2 → tier0，方向合法，无环）。 关联 oagentkit/guardx#3
- **tools v0.10.0** — 新增(bashguard)：接收 guardx/bashguard —— Shell 静态裁决落到重仓
  包在模块之间搬家：bashguard → guardx/tools
- **agent v0.8.0** — 重构(agent)!：import 跟随 llm 包上移，依赖地板升到 v0.9.0
  依赖 github.com/oagentkit/llm v0.9.0（该版起 import 路径为 github.com/oagentkit/llm，原 oagentkit/llm/llm 已移除）。
- **agentkit v1.8.9** — 重构：obsx 的转发改指 llm（obsx 已迁仓）
  github.com/oagentkit/obs/obsx → github.com/oagentkit/llm/obsx 门面的公共路径不变。地板跟到 obs v0.9.0 / llm v0.12.0。
- **agentkit v1.8.8** — 重构：invoke 的转发改指 guardx
  github.com/oagentkit/toolgate/invoke → github.com/oagentkit/guardx/invoke invoke 是框架无关的原语（自身只 import oekit/pkg/errors），迁到零依赖底座后， 消费它不会再被拖进 eino 家族的 34 个第三方模块。 门面的公共路径（github.com/oagentkit/agentkit/invoke）不变。 依赖地板跟到 guardx v0.8.0 / toolgate v0.12.0。
- **agentkit v1.8.7** — 重构：audit / bashguard 的转发改指 obs / tools
  门面上游的两个包已迁仓（guardx v0.7.0 起）： github.com/oagentkit/guardx/audit → github.com/oagentkit/obs/audit github.com/oagentkit/guardx/bashguard → github.com/oagentkit/tools/bashguard 门面的**公共路径不变**（github.com/oagentkit/agentkit/audit 等照旧可用）， 只有内部转发指向改了。go.mod 跟新地板：guardx v0.7.0 / obs v0.8.0 / tools v0.10.0， 并去掉两条嵌套 module 的 require（guardx/audit、guardx/bashguard）。 关联 oagentkit/guardx#3
- **agentkit v1.8.0** — 重构(agentkit)!：门面地板跟到 llm v0.9.0 / rag v0.6.0 / agent v0.8.0
  上游三个仓本轮为破坏性发布（包上移至 module 根），门面的 re-export 必须指向新版本，否则消费方从门面仓装走的是旧实现。

## 依赖地板

**Go 的依赖面按 module 结算**：import 某仓的**任意一个包**，该仓的整条 `require` 就进你的模块图。所以「这个仓的地板」= 「用它的包要吃的依赖」。

**tier0/tier1 共 4 个仓，地板为空** —— 只用这些仓的包，你的模块图里不会出现重量级第三方 SDK（门禁：`matrix-tools/scripts/verify_dep_floor.py`）：

- `guardx`（tier0）
- `runtime`（tier0）
- `textx`（tier0）
- `promptx`（tier1）

带地板的集成层（tier2+）——用它们的包要接受这些依赖：

- `llm`（tier2）：`github.com/cloudwego/eino`、`github.com/cloudwego/eino-ext/components/model/openai`、`github.com/meguminnnnnnnnn/go-openai`、`github.com/oekit/logx`、`golang.org/x/time`
- `mcpkit`（tier2）：`github.com/cloudwego/eino`、`github.com/eino-contrib/jsonschema`、`github.com/mark3labs/mcp-go`
- `obs`（tier2）：`github.com/oekit/logx`
- `queue`（tier2）：`github.com/lib/pq`、`github.com/oekit/logx`
- `rag`（tier2）：`github.com/cloudwego/eino`、`github.com/milvus-io/milvus-sdk-go/v2`、`github.com/oekit/logx`
- `skillkit`（tier2）：`github.com/Masterminds/semver/v3`、`github.com/cloudwego/eino`、`gopkg.in/yaml.v3`
- `toolgate`（tier2）：`github.com/cloudwego/eino`、`gopkg.in/yaml.v3`
- `tools`（tier2）：`github.com/cloudwego/eino`、`github.com/oekit/logx`、`mvdan.cc/sh/v3`
- `agent`（tier3）：`github.com/cloudwego/eino`、`github.com/cloudwego/eino-ext/components/model/openai`、`gopkg.in/yaml.v3`

## 模块

依赖严格自底向上，四个能力层：

### 基础层 · 零重量级第三方地板（纯 stdlib / 第一方基座）

- [guardx](https://github.com/oagentkit/guardx): 安全围栏——凭据脱敏/URL 出口 SSRF 防护/工具许可判定链/提示注入卫生（tier0 零外部依赖底座）
  - 包：`fence`、`logredact`、`egress`、`permgate`、`injectband`、`invoke`、`toolfail`、`sandbox`、`wire`
  - 安装：`go get github.com/oagentkit/guardx@latest`
- [runtime](https://github.com/oagentkit/runtime): Agent 进程运行时——LLM token 流式节控/泛型事件总线/子进程最小环境/运行时热插拔/生命周期钩子
  - 包：`pacer`、`progress`、`procx`、`hotplug`、`hookx`
  - 安装：`go get github.com/oagentkit/runtime@latest`
- [textx](https://github.com/oagentkit/textx): 文本与差异处理——增量切片/unified diff 解析/代码符号索引/会话滚动窗口与压缩/评审报告指纹
  - 包：`textutil`、`diffx`、`codeintel`、`compact`、`conversation`、`reportutil`
  - 安装：`go get github.com/oagentkit/textx@latest`

### 能力层 · 依赖 tier0，仍不引重量级第三方 SDK

- [promptx](https://github.com/oagentkit/promptx): 提示词上下文——system prompt 分段组装/运行中转向队列/文件读后写一致性状态
  - 包：`sysprompt`、`steering`、`filestate`
  - 依赖：[runtime](https://github.com/oagentkit/runtime)、[textx](https://github.com/oagentkit/textx)
  - 安装：`go get github.com/oagentkit/promptx@latest`

### 集成层 · 依赖 tier0/tier1 + 重第三方地板

- [llm](https://github.com/oagentkit/llm): 模型客户端——多模型降级链/任务级预算/成本记账/分阶段路由/LLM 调用观测
  - 包：`llm`、`port`、`wrap`、`llmtest`、`obsx`、`decision`
  - 依赖：[textx](https://github.com/oagentkit/textx)
  - 安装：`go get github.com/oagentkit/llm@latest`
- [mcpkit](https://github.com/oagentkit/mcpkit): MCP 工具池——客户端封装/工具目录/建连单飞/自愈与租约管理
  - 包：`mcp`
  - 依赖：[runtime](https://github.com/oagentkit/runtime)
  - 安装：`go get github.com/oagentkit/mcpkit@latest`
- [obs](https://github.com/oagentkit/obs): 观测与审计——Langfuse 追踪客户端/敏感操作结构化审计（不引 eino 框架）
  - 包：`langfuse`、`audit`
  - 依赖：[guardx](https://github.com/oagentkit/guardx)
  - 安装：`go get github.com/oagentkit/obs@latest`
- [queue](https://github.com/oagentkit/queue): DB 即队列 + Postgres Lease 选主——任务表驱动的工作池与主备单活回调
  - 包：`worker`、`pglease`
  - 安装：`go get github.com/oagentkit/queue@latest`
- [rag](https://github.com/oagentkit/rag): 知识检索——向量化/混合召回/重排，向量后端可插拔
  - 包：`rag`
  - 依赖：[textx](https://github.com/oagentkit/textx)
  - 安装：`go get github.com/oagentkit/rag@latest`
- [skillkit](https://github.com/oagentkit/skillkit): 技能与资产契约——SKILL.md 渐进披露/领域包布局契约/装配血缘图
  - 包：`skill`、`pack`、`lineage`
  - 依赖：[guardx](https://github.com/oagentkit/guardx)、[textx](https://github.com/oagentkit/textx)
  - 安装：`go get github.com/oagentkit/skillkit@latest`
- [toolgate](https://github.com/oagentkit/toolgate): 工具治理——优先级三层约束/注解驱动并发调度/操作审计门/构造期不可绕过的工具调用链
  - 包：`toolprior`、`toolsched`、`policy`
  - 依赖：[guardx](https://github.com/oagentkit/guardx)、[mcpkit](https://github.com/oagentkit/mcpkit)
  - 安装：`go get github.com/oagentkit/toolgate@latest`
- [tools](https://github.com/oagentkit/tools): 外部工具接入——CLI 编码 agent 统一调用/公开资料检索/git 工作副本沙箱/确定性 SAST 扫描/Shell 命令静态裁决
  - 包：`acpx`、`websearch`、`workcopy`、`sast`、`bashguard`
  - 依赖：[guardx](https://github.com/oagentkit/guardx)、[runtime](https://github.com/oagentkit/runtime)、[textx](https://github.com/oagentkit/textx)
  - 安装：`go get github.com/oagentkit/tools@latest`

### 编排层 · 依赖 llm 等 tier2 门面

- [agent](https://github.com/oagentkit/agent): Agent 编排——ReAct 运行样板/计划先行/反思循环/意图路由/多专家黑板/派发守卫
  - 包：`agentrun`、`reflection`、`router`、`blackboard`、`dispatch`、`clarify`
  - 依赖：[llm](https://github.com/oagentkit/llm)、[textx](https://github.com/oagentkit/textx)
  - 安装：`go get github.com/oagentkit/agent@latest`

## 门面仓（迁移过渡 · 已废弃）

- [agentkit](https://github.com/oagentkit/agentkit): 原单仓 `git.enjoye.top/enjoydream/agentkit` 的兼容门面，52 包 re-export。**已废弃**：v1.x 退役条件已满足，只保留兼容转发、不接受新功能，**新代码不要引它**。归档待旧单仓 `git.enjoye.top/enjoydream/agentkit` 下线后执行；在此之前本仓继续可用，已有 tag 的 `go get` 照常解析。
- 完整旧→新包路径映射见该仓 [MIGRATION.md](https://github.com/oagentkit/agentkit/blob/main/MIGRATION.md)。
- 门面**包集合已冻结**：矩阵新增的包不再要求门面跟上（见 `scripts/facade_package_baseline.json` 与 `scripts/verify_facade_frozen.py`）。

## 基建

- [oagentkit/.github](https://github.com/oagentkit/.github) — org profile + **全 org 共享的 CI 门禁**（reusable workflow）
- [oagentkit/matrix-tools](https://github.com/oagentkit/matrix-tools) — 版本矩阵生成 / 审计 / import 改写 / 建仓 / 发布流水线

## AI Agent 要点

- **每仓根目录的 `AGENTS.md` 是该仓的权威规范**：分层不变量、错误处理、日志、并发安全、API 命名，以及该仓特有的工程红线。
- 安装一律 `go get github.com/oagentkit/<mod>@latest`；不要引门面仓 `agentkit`。
- **import 路径 = `github.com/oagentkit/{仓名}/{包名末段}`**；**末段与仓名相同**时收口成 `github.com/oagentkit/{仓名}`（不重复末段）。旧单仓 `git.enjoye.top/enjoydream/agentkit/<包>` 的**中间层目录会被丢掉**，因为新矩阵里那层组织职责由**仓**承担。例如：
    - `agentkit/worker/pglease` → `github.com/oagentkit/queue/pglease`
    - `agentkit/knowledge/rag` → `github.com/oagentkit/rag`
    - `agentkit/llm` → `github.com/oagentkit/llm`
    - `agentkit/llm/port` → `github.com/oagentkit/llm/port`
    - `agentkit/llm/wrap` → `github.com/oagentkit/llm/wrap`
    - `agentkit/llm/llmtest` → `github.com/oagentkit/llm/llmtest`
    - `agentkit/llm/decision` → `github.com/oagentkit/llm/decision`
  其中 `agentkit/knowledge/rag` → `github.com/oagentkit/rag` 尤其坑：包名末段与仓名相同时**收口到 module 根**（不重复末段），直觉会以为要写成 `llm/llm`。完整 7 条易踩对照、及全部 52 条映射见 [matrix-tools/scripts/rewrite_imports.py --print-rules](https://github.com/oagentkit/matrix-tools)，机器可读映射见 [versions.json](https://oagentkit.github.io/versions.json) 的 `fromLegacy` 字段。
- 完整包路径映射见 [matrix-tools/modules.json](https://github.com/oagentkit/matrix-tools)。
- 改 CI 规则只去 [{org}/.github](https://github.com/{org}/.github) 仓（`go-ci.yml@main`）；各仓 `ci.yml` 只是薄调用层，不要在各仓复制规则。
- 不确定 API 时以源码为准：各仓均带测试，`go doc github.com/oagentkit/<mod>[/<pkg>]` 可查。

## 易踩的坑

- **import 路径不是纯前缀映射**：旧单仓 `agentkit/<包>` 迁到新矩阵时，中间层目录会被丢掉 —— `agentkit/worker/pglease` → `github.com/oagentkit/queue/pglease`。按「仓库名 + 完整旧路径」拼会直接构建断裂。
- **`guardx/audit` 与 `guardx/bashguard` 已迁出**（guardx v0.7.0）：`github.com/oagentkit/obs/audit`（依赖 oekit/logx）、`github.com/oagentkit/tools/bashguard`（依赖 mvdan.cc/sh/v3）。guardx 回到**一个 module、一条版本线、零外部依赖**的 tier0 底座 —— Go 的依赖面按 module 结算：只 import `guardx/logredact` 的下游，模块图里不该多出任何第三方依赖。旧路径的嵌套 module tag 仍在但**已冻结**。
- **`progress` 撞名但语义相反**：`oekit/concurrency/progress` 是长任务**阶段进度追踪器**，而 `oagentkit/runtime/progress` 是泛型**事件总线**。按包名对齐会做错。
- **`pacer` ≠ `ratelimit`**：前者是聚合缓冲（攒够窗口再发），后者是准入控制。
- **`runtime/breaker` 已退役**：`llm` v0.4.0 起熔断全量使用 `oekit/concurrency/breaker`（三态状态机 + 代绑定 + 冷却期/探测时限独立配置 + 计数型触发）。上游 [#17](https://github.com/oekit/concurrency/issues/17)→[#25](https://github.com/oekit/concurrency/issues/25) 已全部落地。
- **`oekit/concurrency/breaker` 的 `0` 语义是陷阱**：`WithConsecutiveFailures(0)` 表示**关闭计数型触发**、`WithCooldown(0)` 表示**沿用 probeTimeout**；而旧 `agentkit/breaker` 的 `New(0, …)` 里 0 是「用缺省」。照抄会让熔断静默失效。
- **`GetBreaker` 是进程级单例且 opts 只认首次创建**：同名不同参会静默沿用首次配置。需要多套配置时把参数并进 breaker 名字做命名空间隔离。
- **上游未导出 breaker 缺省值**：需要 trip/cooldown 缺省请在调用方显式固化常量，别依赖「传 0 走默认」——上游没有这个约定。