AI 辅助接入

这套文档现在不只服务“人读完再自己写代码”，也服务“人把上下文整理好后，直接交给 AI 编程工具产出接入代码”。

如果你正在使用 Claude、Codex、Cursor、ChatGPT 或类似工具，推荐阅读方式改成下面这个工作流。

你应该给 AI 什么

推荐一次性提供 5 类信息：

你的项目类型：Node.js、TypeScript、Dart、Flutter
当前状态：新项目、已有 OpenAI 接入、已有自定义 agent、已有知识库
目标能力：LLM、TTS、ASR、Embeddings、Agent、RAG
输出要求：完整代码、增量改造、最小 diff、排障清单
AgentOS 事实约束：baseURL、apiKey、model 分别从哪里来

通用提示词模板

把下面模板里的占位符替换掉，再发给 AI 编程工具：

text

你现在是我的结对工程师，请直接在项目里完成 AgentOS 接入，不要只给思路。

项目情况：
- 项目类型：[Node.js / TypeScript / Dart / Flutter]
- 当前状态：[新项目 / 已有 OpenAI 接入 / 已有自定义 agent / 已有知识库]
- 我想接入的能力：[modelkit / agentkit / ragkit / tts / asr / embeddings]
- 我希望你输出：[完整可运行代码 / 基于现有代码改造 / 最小 diff / 排障修复]

必须遵守的 AgentOS 事实：
- 如果直接使用 OpenAI SDK，chat 的 baseURL 是 `${AgentOS 根接口返回的 baseUrl}/modelkit/chat/v1`
- apiKey 来自 registerBundle 或 POST /appkit/register 返回的 Bearer token
- model 来自 `sdk.modelkit.listModelsByTask(ModelTask.chat)`，或 `GET /modelkit/models` 中 `task=chat` 的 `model.id`
- 不要臆造不存在的 AgentOS 接口、字段名或初始化流程
- 如果文档给了最小示例，请优先贴近示例结构实现

请按下面顺序工作：
1. 先判断我的场景更适合 modelkit、agentkit 还是 ragkit，并说明理由
2. 基于这个判断直接修改代码
3. 输出我需要配置的环境变量、依赖和运行命令
4. 给出一份人工验收清单，告诉我如何确认接入成功
5. 如果发现上下文不足，请只询问真正阻塞实现的最少信息

AgentOS 最小事实清单

这是最值得和提示词一起交给 AI 的事实源：

事实	正确来源
网关地址	你部署的 AgentOS 地址，例如 `http://127.0.0.1:8888`
OpenAI SDK `baseURL`	chat 使用 `${AgentOS 根接口返回的 baseUrl}/modelkit/chat/v1`
OpenAI SDK `apiKey`	`registerBundle` 或 `POST /appkit/register` 返回的 Bearer token
OpenAI SDK `model`	ModelKit 中对应任务的 `model.id`
如果 App 已有复杂 agent	通常优先 `modelkit`，不必先接 `agentkit`
如果你有 tool 但不想自己编排 agent	通常优先 `agentkit`
如果你需要现成知识库查询和文档管理	通常优先 `ragkit`

人工验收清单

AI 生成完代码后，至少人工检查这几项：

是否真的调用了 registerBundle 或明确使用了已有 Bearer token
是否把 baseURL 写成了 AgentOS 的 baseUrl，而不是默认 OpenAI 地址
是否从 listModels() 或已知可用模型中选择模型，而不是随意写死一个未知 id
是否区分了“自己有 agent 只接模型”与“把 tool 和 agent 编排交给 AgentKit”这两类场景
是否把示例代码当成参考结构，而不是臆造新的 SDK 初始化方式

从哪里继续

不确定该选什么：看技术选型
要直接接 TypeScript：看 TypeScript 快速开始
要给 AI 一个最小参考实现：看 TypeScript 最小示例

AI 辅助接入 ​

推荐工作流 ​

你应该给 AI 什么 ​

通用提示词模板 ​

AgentOS 最小事实清单 ​

人工验收清单 ​