快速开始

安装

按需装单个模块，不要整包引入。矩阵的价值就在只为你真正用的能力付依赖代价。

bash

go get github.com/oagentkit/llm@latest        # 模型客户端（tier 2）
go get github.com/oagentkit/agent@latest      # Agent 编排（tier 3）
go get github.com/oagentkit/mcpkit@latest    # MCP 工具池（tier 1）

装 agent（tier 3）会自动拉上 llm + textx，链路到此为止——不会把 eino 之外的无关地板带进来。tier 分层就是干这个的。

不要引门面仓

import "git.enjoye.top/enjoydream/agentkit/agentrun"  // ❌ 原单仓路径
import "github.com/oagentkit/agent/agentrun"          // ✅ 拆分后

门面仓 oagentkit/agentkit 只是 re-export 兼容层， 47 包零逻辑转发，按 README 写死的期限在 v1.x 后退役。新代码一律用上表的模块路径。

import 路径不是纯前缀映射

从旧单仓迁移时，中间层目录会被丢掉：

新路径 = github.com/oagentkit/{仓名}/{包名末段}
        末段与仓名相同 → 收口成 github.com/oagentkit/{仓名}

agentkit/knowledge/rag   →  oagentkit/rag           ❌ 不是 rag/knowledge/rag
agentkit/worker/pglease  →  oagentkit/queue/pglease  ❌ 不是 queue/worker/pglease
agentkit/llm             →  oagentkit/llm           ❌ 不能重复成 llm/llm

完整 47 条对照跑 rewrite_imports.py --print-rules，机器可读映射见 versions.json 的 fromLegacy 字段。

一键改写 import

三个文件放同一目录后即可运行（rewrite_imports.py 依赖同目录的 matrix_paths.py，矩阵定义用 --modules 显式指定）：

bash

curl -sSfL https://raw.githubusercontent.com/oagentkit/matrix-tools/main/scripts/rewrite_imports.py -o rewrite_imports.py
curl -sSfL https://raw.githubusercontent.com/oagentkit/matrix-tools/main/scripts/matrix_paths.py -o matrix_paths.py
curl -sSfL https://raw.githubusercontent.com/oagentkit/matrix-tools/main/modules.json -o modules.json

# 看映射表（不动文件）
python3 rewrite_imports.py --org oagentkit --modules ./modules.json --print-rules

# 真改写（--root 指向你的工程根；只改 import 块内的引号字符串，改完自动 gofmt）
python3 rewrite_imports.py --org oagentkit --modules ./modules.json --root . --apply

改写后收尾：go mod tidy && go build ./... && gofmt -l .。

不要用 python3 -c "exec(urlopen(...).read())" 的写法

那样执行时脚本里没有 __file__，定位同目录依赖与 spawn 子进程都会炸（NameError: name '__file__' is not defined）。脚本必须作为文件运行。

按需求选模块

你要做的事	装这个	层
调模型、降级、控预算、算成本	`llm`	tier 2
ReAct / 反思 / 路由 / 多专家协作	`agent`	tier 3
接 MCP server、拿工具目录	`mcpkit`	tier 1
治理工具优先级、并发调度、敏感操作审计	`toolgate`	tier 2
组装 system prompt、运行中转向	`promptx`	tier 1
token 用量、trace、分阶段打标	`obs`	tier 1
脱敏、SSRF 防护、Shell 沙箱解析	`guardx`	tier 0
会话压缩、diff 解析、代码符号索引	`textx`	tier 0
事件总线、流控、子进程、热插拔、钩子	`runtime`	tier 0
任务队列、主备选主	`queue`	tier 0

完整 13 个模块见模块总览。

矩阵通用规约

这几条在每个仓的 AGENTS.md 里都写着，先记住能少踩一半坑：

错误处理 —— 一律用 github.com/oekit/pkg/errors，业务错误用 BizError：

import "github.com/oekit/pkg/errors"

// 包装底层错误，附带结构化上下文
if err := doIt(); err != nil {
    return errors.Wrap(err, "解析用户输入失败", "uid", uid)
}

// 业务错误用 BizError：第一个参数是业务码（int），不是 err
if err := doIt(); err != nil {
    return errors.WrapBizError(40010, "解析用户输入失败", err)
}

没有 errors.WrapBiz

oekit/pkg/errors 里没有 WrapBiz。实际导出是 Wrap(err, msg, kv...)、 NewBizError(code, msg)、WrapBizError(code, msg, cause)、 WrapBizErrorWithStatus(bizCode, httpCode, msg, cause)。业务码是 int，别把 err 传到第一个参数位。

所有 error 禁止 _ 忽略。

并发 —— 禁止裸 go func，用 oekit/concurrency/async 的 GoSafe 系列（panic 会被 recover）：

import "github.com/oekit/concurrency/async"

async.GoSafe(func() { /* ... */ })   // ✅ panic 被兜住
// go func() { /* ... */ }()          // ❌ 一个 panic 带走整个进程

共享状态用 mutex / atomic 保护；包级全局可变状态用 atomic.Pointer[T]。

API 命名 —— 函数选项模式命名 XxxOption，禁止裸 Option（多包 co-import 会冲突）：

type ModelOption func(*modelConfig)   // ✅ 带仓/包前缀
// type Option func(*cfg)             // ❌ 冲突

导出符号 PascalCase + godoc 注释，包文档放 doc.go。

日志 —— 走 oekit/logx，组件 logger 用 logx.Delegating：

logger := logx.Delegating("oagentkit-agent")

面向用户的最终输出落日志前要过 guardx/fence 的不可信文本中和。

查 API

不确定就以源码为准。各仓都带测试，go doc 可查：

bash

go doc github.com/oagentkit/llm
go doc github.com/oagentkit/agent/dispatch

每个仓的 AGENTS.md 是该仓的权威规范——本站的模块页只是摘要，不替代它。

下一步

架构总览 —— 分层不变量、依赖方向、跨矩阵撞名
AI Agent 编排 —— 从零搭一个带守卫的 Agent

快速开始 ​

安装 ​

一键改写 import ​

按需求选模块 ​

矩阵通用规约 ​

查 API ​

下一步 ​

快速开始

安装

一键改写 import

按需求选模块

矩阵通用规约

查 API

下一步