x/ai Primer
x/ai Primer
Section titled “x/ai Primer”实验性 — API 兼容性未冻结。采用前请先评估。查看发布策略了解当前成熟度。
范围说明：
x/ai用于构建调用 AI provider（OpenAI、Anthropic 等）的服务。关于 AI 编码助手（Copilot、Claude、Cursor）如何在本仓库的机器可读控制面中工作，请参阅 Agent-first 工作流。
当你已经通过 x/* 家族 确认问题明显属于 AI gateway 能力边界时，就打开这一页：连接 provider、管理对话 session、流式传输 completion，或 wiring tool。
x/ai 是 Plumego 的 AI gateway 扩展。它拥有 provider 适配器、session 与上下文管理、streaming 助手、tool 调用基础元语，以及面向 AI 的弹性和缓存助手。它绝不能要求 core 或稳定根了解 AI provider 内部细节。
什么时候从这里开始
Section titled “什么时候从这里开始”- 你正在添加或修改 provider 适配器（
provider/）— OpenAI、Anthropic 或自定义后端 - 你正在管理对话 session 或上下文窗口（
session/） - 你正在实现或消费流式 completion 响应（
streaming/、sse/） - 你正在注册、调用或管控 tool call（
tool/） - 你正在用弹性基础元语封装 AI 调用，如重试或断路器（
resilience/） - 你正在探索基于 embedding 的查询语义缓存（
semanticcache/）
什么时候不该从这里开始
Section titled “什么时候不该从这里开始”- 改动关于 core app bootstrap 或稳定入口点
- 工作是业务专属的 prompt 流程或领域逻辑 — 保留在应用代码中
- 改动需要不含 AI session 语义的通用持久化 — 从
store开始 - 工作涉及 tenant 专属的 AI 策略或每租户速率限制 — 与
x/tenant协调
当前仓库里先读哪些文件
Section titled “当前仓库里先读哪些文件”x/ai/module.yamlx/ai/provider/x/ai/session/x/ai/streaming/x/ai/tool/
x/ai 使用显式稳定性分级。在依赖某个子包之前，请检查 module.yaml：
| 子包 | 分级 | 含义 |
|---|---|---|
provider、session、streaming、tool | stable | 受语义版本控制覆盖 |
tokenizer、llmcache | experimental | 基础层 — 被其他 x/ai 子包依赖 |
resilience、semanticcache、instrumentation | experimental | 组合层 — 构建在基础层或 x/resilience 之上 |
orchestration、marketplace、distributed、sse、filter、metrics、multimodal、prompt | experimental | 功能层 — 可能在没有弃用期的情况下发生变化 |
生产服务中，experimental 的 x/ai 子包应通过应用本地 adapter 隔离；在假设超出声明分级的兼容性之前，请先查看发布策略。
深入更窄的 helper 前，先从这些具体 API 表面开始：
provider.NewOpenAIProvider、provider.NewClaudeProvider与provider.Provider：provider 驱动的补全provider.NewTextMessage：构造简单文本请求，避免手写 content blocksession.NewManager搭配session.NewMemoryStorage：管理对话状态streaming.NewStreamManager与streaming.NewHandler：处理流式补全路径tool.NewRegistry、tool.NewFuncTool与tool.NewAllowListPolicy：工具调用
更具体的归属例子
Section titled “更具体的归属例子”这些工作适合留在 x/ai | 一旦变成这些问题就应移出 |
|---|---|
provider：CompletionRequest / CompletionResponse、streaming 类型、provider 选择 | 要求 core 了解 provider 内部细节或使用隐式 provider 全局变量 |
session：Manager、Session、Storage 接口，用于对话上下文 | x/tenant/session 中的通用 auth session 或 tenant session lifecycle |
streaming：StreamManager、StreamingEngine、SSE 助手 | AI 上下文之外的 websocket 帧或 HTTP 传输关注点 |
tool：Tool 接口、Registry、FuncTool、调用 Policy | 带有领域验证的业务专属 tool 实现 |
resilience：AI provider 调用专属的断路器、重试封装 | x/resilience 中跨非 AI 工作负载共享的通用弹性基础元语 |
为什么单独写这一页
Section titled “为什么单独写这一页”AI 能力是组合式的：一个请求可能要解析 provider、管理 session、流式传输响应并调用 tool — 全部在一个 handler 中完成。x/ai 定义了每个关注点的归属，使组合保持显式、子包边界保持可审计。稳定性分级表的存在是因为实验性子包正在积极演进；在稳定服务路径中 wiring 它们会产生升级阻力。