@ai-zen/代理人-sdk

AI-Zen SDK——共享商业逻辑层,为CLI和桌面提供统一的Agent运行时间. 工作在框外,有预配置的供应商设置,默认代理,以及默认的子代理.

真相来源

docs/sdk-design-v1.md 是这个软件包设计的唯一的真理来源。 所有执行都必须符合该文件。 (前置设计保留在 docs/sdk-design-v0.md. ) (中文(简体) )

建筑

CLI ──┐
      ├── @ai-zen/agents-sdk ──┐
Desktop ──┘                    │
                          LLM API

模块层

types         ← pure types, zero business dependencies (incl. ToolEnv)
config        ← ConfigManager + constants: config.json read/write + directory setup + factory defaults
crud          ← capability-entity CRUD (Agent definitions; conversations/drafts are persisted by each consumer)
runtime       ← model factory + Agent assembly + task handoff/migration (cancellable via `AbortSignal`; createModel / createAgent / SdkAgent / HandoffService / HandoffGuardPlugin)
scope         ← Scope orchestration container + ScopePlugin contract + PermissionEvaluator / disclosure + plugins/ (5 self-contained capability sources: discovery + tools + plugin)
agent-plugins ← Agent plugins (autoMigrate, autoRefreshTools, contextGuard, unknownToolHint)
shared        ← content blocks (file → content block transport), entity repository, logging, errors

依赖方向 : agent-plugins → runtime → scope· ; runtime → scope / crud / shared / types, (中文(简体) ), scope → types / shared。上层依赖于下层.

核心概念

权限模式

这四个维度是独立的;允许/拒绝是相互排斥的,没有匹配手段否认,允许是披露(被否定的项目是LLM完全看不见的).

Agent.permissions
  ├── tools:      { allow: string[] } | { deny: string[] }
  ├── skills:     { allow: string[] } | { deny: string[] }
  ├── mcps:       { allow: string[] } | { deny: string[] }
  └── subagents:  { allow: string[] } | { deny: string[] }

消费

const scope = new Scope({
  config,
  cwd: "/path/to/workspace", // one working directory per Scope; parallel sessions don't interfere
  agentsDir,
}).use(
  ...allInOne({ skillsPaths, toolsPaths, subAgentsPaths, mcpPaths }),
);
await scope.init();

const agent = await createAgent(scope, "my-agent");
const handoffService = new HandoffService({ handoffDir: "/work/.ai-zen/handoffs", skillDirs });
agent.use(new ContextGuardPlugin({ guardTokens, isSuspended: () => handoffService.busy }));
agent.use(new AutoMigratePlugin({ service: handoffService, handoffTokens }));
agent.use(new AutoRefreshToolsPlugin());
agent.use(new UnknownToolHintPlugin({ scope }));
await agent.init();
await agent.send("Hello");

await scope.dispose(); // disconnect MCP, release plugin resources

发展状况

内建工具

所有内置工具都是类( 计划) SdkCallbackTool),由内置工具插件(BuiltinToolsScopePlugin带有 ToolEnv ——每条范围一组实例 cwd 注射和相对路径 Scope.cwd从不依赖于全球 process.cwd()。 。 。 .

基于活性模型/配置的有条件注入:

工具输出保护 : AppConfig.maxToolOutput (以字符表示,默认为32768)是工具输出的统一上限. 每一个工具都自相残杀—— exec 垃圾场 stdout.log 编号 : stderr.log 单独(每流返回头/尾预览), find_text 编号 : glob 编号 : ls 倾出 result.json (返回头部预览),和 read 只有警告和建议分批读取 range垃圾倒进 <tmpdir>/ai-zen/tool-output/<tool>-<timestamp>-<random>/,每个呼叫一个目录,没有自我清理。 见 docs/sdk-design-v1.md 第12节。 。 。 .

中断策略存在于配置中 : AppConfig.abortedMessageStrategy (单位:千美元)keep 编号 : drop工厂 keep ——模型在中断后可以继续半句判决)并 AppConfig.abortedToolRoundStrategy (单位:千美元)fill 编号 : drop工厂 fill 整个回合进出,因为 tool_calls (b) 与结果挂钩. createAgent() 读取他们从 scope.config 当没有通过明确的选择时,应当保持一个单一的真理来源.

内置插件

语言

这个SDK是 仅英文:每个模型造型和用户造型的字符串——工具计划描述,工厂提示,运行时注入的指针,工具结果,出错信息,工厂目录数据——是一个固定的英文文字. 没有本地化字段, 没有消息目录, 没有运行时语言切换 。 UI语言完全属于每个消费者(CLI) i18n/,桌面语言设置).

这是一个性能界限,而不是一个方便的选择—— SDK 行为和性能不得因用户语言而异数字 :

• 门槛是绝对的. Model.tokenThresholds.handoff 编号 : guard 财务报告和审定财务报表 AppConfig.maxToolOutput 是绝对符号 / 字符数。 一个本地化的工具计划是一个不同的符号计数,所以交接和上下文护卫会绊倒 不同数量的实际内容 相同项目 config.json ——每个语言都具有相同的配置,不同的行为.
• 斯克马的费用每轮都要付. 描述文本在每次请求时都会重新得到同意,因此一个符号三角洲是请求大小,上下文使用和花费的常态成本,而不是一次性成本.
• 缓存前缀不再具有可比性 . 前缀上的快速缓存匹配;让语言进入 SDK 将一个代码路径的前缀形状相乘并去除基准所依赖的单个变量.
• 诊断需要一种形状. 性能数据,bug复制和工具调用成功率必须在用户之间进行比较;一旦行为与地语相去甚远,每个结论都需要"先使用什么语言"的修饰语.

按照用户的语言,由工厂系统的一个语言中性指示处理,即时—— Always reply in the same language the user writes in. 适应每名 消息 而不是每个安装, 不需要本地管道 在SDK。 充分理由: docs/sdk-design-v1.md 第1节。 。 。 .

设计原则

见项目总库 PRINCIPLES.md数字 :

1. 逻辑一致性
2. 首先设计文件作为真相的来源
3. 对称性和统一性
4. 没有过度工程
5. 奥卡姆的剃刀
6. 继续重排; 保持清洁层
7. 测试是基础