Kun 的 ACP 运行时与模型网关协议桥:统一接入外部 Agent、打通 Kun 工具与用量归属

原创2026-10-10 23:55:071,719 阅读
文章标签:AI 应用人工智能AI Agent代码智能体交互助手桌面应用多智能体Agent 编排Agent 工作流工具调用Agent 记忆本地部署LLM 网关MCP Clients前端CLI

Kun 的 ACP 运行时与模型网关协议桥:统一接入外部 Agent、打通 Kun 工具与用量归属

Kun 是一个 local-first 的 AI agent 工作台,其 ADE(Agent-Driven Engineering)模式允许"总管"线程把任务派发给不同的 agent harness 执行。本文依据仓库内 ADE 实施拆解文档 p1-acp-mcp-gateway.md(以及它的上层设计 03-acp-runtime.md、04-model-gateway-bridge.md、05-worker-callbacks.md)展开,聚焦 P1-01 ~ P1-09 九项实施单元:ACP(Agent Client Protocol)接入运行时、共享工具桥宿主、Kun Tools MCP server,以及 harness × 模型网关协议桥。读完本文,你将掌握:ACP 进程与 JSON-RPC 传输层的落地细节、会话管理与事件映射规则、客户端方法(fs/终端/权限)的实现约束,以及"Claude Code 外壳 + DeepSeek 模型"这类混合形态如何通过 kun-gateway 凭据模式实现模型寻址、令牌范围与用量归属。


1. 背景与目标:一套运行时接入所有 ACP agent

Kun 现有的三个深度适配器(Claude SDK、Cursor SDK、Antigravity CLI)各自实现了几千行专用逻辑。ACP 接入的目标是:用一个通用运行时接入所有支持 ACP(Agent Client Protocol)的 agent——Gemini CLI(原生支持)、Codex(经 adapter)、OpenCode 等。新 agent 只需在 harness 目录里加一条配置,而不再为每个 agent 编写专属适配器;三个深度适配器保持不变。

实现层面,这条链路分为三条并行的能力线(见 总索引 的关键路径):

  • ACP 运行时(P1-01 ~ P1-05):进程、JSON-RPC 传输、会话管理、事件/工具映射、客户端方法、运行时装配。
  • 工具桥与 MCP(P1-06、P1-07):把 Kun 的独有工具(记忆、画布、网页、技能、MCP 门面等)通过共享宿主 + MCP server 暴露给外部 agent。
  • 网关协议桥(P1-08、P1-09):让外部 harness 使用 Kun 配置的任意 provider/model,凭据始终留在 Kun 里,harness 进程只拿到短期、限定范围的令牌。

2. P1-01:ACP 的 JSON-RPC 传输、受管进程与假 agent 夹具

2.1 模块划分与依赖

文件 内容
kun/src/runtime/acp/acp-schema.ts 协议类型。先确认官方 TypeScript 类型包的包名与版本并 pin(写入 kun/package.json);若只引类型,用 import type 保证运行时零依赖。zod 解析器只覆盖 Kun 读取的字段,未知字段 passthrough
kun/src/runtime/acp/acp-jsonrpc.ts AcpJsonRpc:逐行 JSON 帧;request(method, params, { timeoutMs, signal });notify();onRequest(method, handler)(agent → 客户端);onNotification(method, handler);close()
kun/src/runtime/acp/acp-process.ts startAcpProcess():spawnOwnedProcess(command, args, { env, stdio: ['pipe','pipe','pipe'], windowsHide: true });stderr 环形缓冲 64 KiB;exit promise;stop(graceMs) 调 stopOwnedProcess
kun/src/harness/harness-env.ts HARNESS_CREDENTIAL_ENV_DENYLIST、buildHarnessEnv({ base, strip, add });Claude SDK 的 buildScopedEnv 改为调用它(行为不变的测试守护)
kun/src/runtime/acp/__fixtures__/fake-acp-agent.mjs 读 stdin 行,按 FAKE_ACP_SCENARIO 环境变量指向的 JSON 场景回应:握手、会话、按脚本发 update、发客户端请求并等待回复
kun/src/runtime/acp/__fixtures__/scenarios/*.json 基础对话、工具调用 + diff、权限请求、取消、崩溃、加载会话回放、畸形输出

依赖:P1-01 依赖 P0-04(线程/turn 字段与 HarnessRouter 接入),分支 codex/ade-acp-transport,提交 feat(acp): json-rpc transport and owned agent process。

2.2 进程启动与环境隔离

startAcpProcess 使用 Kun 通用受管进程启动器 spawnOwnedProcess / stopOwnedProcess(位于 owned-process.ts),而不是 SDK 专用的 spawnOwnedSdkProcess。从源码看,spawnOwnedProcess 在 POSIX 下通过一个 guard 进程登记进程组(guard.request({ type: 'register', pid, ... })),只有登记成功后才会向子进程发送启动闸门 start,从而保证"用户代码运行前进程已被登记、退出时整棵树被回收";Windows 下则使用 Job Object(spawnWindowsOwnedProcess)。stopOwnedProcess 带 graceMs(默认 1000)与 timeoutMs(默认 5000)两级终止语义。

环境构建的关键约束:

const env = buildHarnessEnv({
  base: process.env,
  strip: HARNESS_CREDENTIAL_ENV_DENYLIST,  // 剥掉会抢优先级的 *_API_KEY、代理令牌等
  add: { ...input.def.launch!.env, ...credentialEnv(input.credential) }
})
  • HARNESS_CREDENTIAL_ENV_DENYLIST 放在 kun/src/harness/harness-env.ts,Claude SDK 现有 buildScopedEnv 改为调用它,保证所有 harness 口径一致。
  • 同一 (harnessId, credentialIdentity) 的 spawn env 必须逐字节稳定:不要往 env 里放随机值或时间戳,否则连接池判断"配置变了"会反复重启进程;需要的随机令牌走 MCP URL 或文件。
  • stderr 只保留尾部 64 KiB,用于报错与脱敏。

2.3 JSON-RPC 帧细节

  • 帧:每行一个 JSON 对象,\n 分隔;读取端用增量缓冲,单行上限 8 MiB,超过则关闭连接并报 harness_protocol_error。
  • id:客户端请求用自增整数;收到 agent 发来的请求时按其 id 回复。
  • 超时:每个请求独立计时;超时后从 pending 表删除并拒绝 promise,迟到的响应丢弃并记 debug。
  • 背压:写入用 stdin.write 的返回值与 drain 事件排队,避免大 prompt 丢数据。
  • 关闭:进程退出时拒绝所有 pending 请求,错误里附 stderr 尾部(脱敏:去掉形如令牌、Bearer、sk- 前缀的片段)。

2.4 测试

用例 期望
并发 10 个请求 各自拿到正确响应
agent 主动请求 注册的 handler 被调用,回复带相同 id
半行 / 粘包 正确分帧
超长行 连接关闭,错误码正确
进程退出 pending 全部拒绝,附脱敏 stderr
env denylist 中的变量不出现在子进程环境;Claude SDK 现有 env 测试通过

3. P1-02:会话管理、config options 与能力推导

3.1 连接池与会话绑定

文件 内容
kun/src/runtime/acp/acp-connection-pool.ts key = ${harnessId}:${credentialIdentity};acquire / release / markUnhealthy / onExit;空闲释放定时器
kun/src/runtime/acp/acp-connection.ts 包装一个进程 + JSON-RPC + initResult;initialize();sessionUpdates 分发器(按 sessionId 路由到订阅者)
kun/src/runtime/acp/acp-session-manager.ts ensureSession(ctx, conn)、applyConfigOptions()、commit(session, ctx)
kun/src/runtime/acp/acp-capabilities.ts capabilitiesFromAcp(initResult, sessionFacts)

依赖:P1-02 依赖 P1-01,分支 codex/ade-acp-session。

连接池的复用规则(03 §4.3):引用计数归零且空闲超过 idleReleaseMs(默认 10 分钟)后关闭进程,会话按 ActivityStore 规则进入 dormant;进程意外退出时该连接上所有会话标记 native_state_unavailable,下一轮走 portable 重建。

线程 ↔ 会话绑定复用 DelegatedSessionCoordinator(delegated-session-binding.ts)。当前源码中 DelegatedProviderKind 为 'agent-sdk' | 'cursor-sdk' | 'antigravity-cli',实施项要求新增 'acp' 值;providerStateDir('acp', …) 目前不需要存东西,但保持接口一致。DelegatedSessionRoute.providerId 对 ACP 填 harnessId(ACP 没有 provider 概念时),continuationMode 按 loadSession 能力取 native 或 portable。

ensureSession 的核心分支:session/load 成功则复用原生会话;失败则 coordinator.rejectResume(preparation) 后 session/new 新建会话,此时本轮 prompt 需要携带交接简报(handoff brief)。

3.2 加载阶段过滤与 config options

  • 加载阶段过滤:AcpSessionHandle.phase 在 session/load 请求返回之前为 loading,此期间收到的 user_message_chunk / agent_message_chunk / agent_thought_chunk / tool_call* 全部丢弃,只处理 available_commands_update、current_mode_update、config_option_update——因为 session/load 会让 agent 回放历史,而 Kun 时间线已经有这段历史。
  • cwd 与 mcpServers:cwd 永远是任务工作区路径;mcpServers 注入 Kun Tools MCP server:agent 声明 mcpCapabilities.http 时用 HTTP 形式,否则用 stdio 桥形式(kun mcp-bridge --session <id>)。用户在 Kun 里配置的其它 MCP server 默认不透传给外部 agent,避免与它们自己的 MCP 配置冲突。
  • 效果推导:effort 可设置 ⇔ 存在 category: 'thought_level' 的选项;modes ⇔ 存在 category: 'mode' 的选项或旧的 modes 列表。

applyConfigOptions 的取值策略:找不到精确模型 id 时不猜(保持 agent 默认并记日志);thought_level 由 mapEffort(ctx.reasoningEffort) 把 off/low/medium/high/max 映射到 agent 选项;mode 按权限档位映射;只有 opt.options 里包含该 value 才发起 session/set_config_option。

3.3 测试

用例 期望
loadSession 能力为 true 且绑定有 nativeSessionId 调用 session/load,回放不产生 Kun item
load 失败 rejectResume → session/new
config options 中无精确模型 不调用 set,记 debug
同 key 两次 acquire 复用同一进程
进程退出 该连接上的会话绑定被标为 native_state_unavailable

4. P1-03:事件映射与工具调用映射

4.1 Mapper 输出形态

文件 内容
kun/src/runtime/acp/acp-event-mapper.ts AcpEventMapper:apply(update)、flush();持有本轮文本 / 推理累积、工具调用状态机
kun/src/runtime/acp/acp-tool-call-mapper.ts toolItemKind(kind)、toKunToolCallItem(update)、toKunToolResult(update)、diff 内容的结构化
kun/src/contracts/events.ts 新事件 harness_session_state

外部运行时写事件的方式沿用现有 SDK 映射器(agent-sdk/sdk-event-mapper.ts):通过 TurnService.applyItem / updateItem 写 item,通过 RuntimeEventRecorder.record 写流式事件。映射器只产出"草稿",由 acp-runtime.ts 统一写入,便于测试:

type MapperOutput =
  | { kind: 'text_delta'; text: string }                                     // → assistant_text_delta(增量)
  | { kind: 'reasoning_delta'; text: string }
  | { kind: 'tool_call_ready'; item: ToolCallTurnItemDraft }
  | { kind: 'tool_call_started'; callId: string }
  | { kind: 'tool_call_finished'; callId: string; result: ToolResultDraft }
  | { kind: 'todos'; todos: TodoDraft[] }
  | { kind: 'usage'; usage: UsageSnapshot }
  | { kind: 'context'; snapshot: ContextSnapshotDraft }
  | { kind: 'session_state'; state: HarnessSessionStateDraft }

4.2 关键映射规则

  • 文本增量:只发本次 chunk,不发累计全文(Claude SDK 接入时的教训:GUI 对 assistant_text_delta 是追加)。flush() 时写完整 assistant_text item(替换语义)。
  • 工具调用状态机:Map<toolCallId, { phase: 'pending' | 'running' | 'done', item }>;先到的 tool_call_update 建占位;重复终态忽略;turn 结束时仍未终态的调用标为 interrupted。
  • toolName:acp:${kind}(例如 acp:edit),标题用 title;arguments 放 { title, kind, locations, rawInput? }(rawInput 超过 16 KiB 截断)。
  • toolItemKind:edit/delete/move → file_change、execute → command_execution、其余(read/search/fetch/think/switch_mode/other)→ tool_call。
  • diff:tool_result 的结构化输出 { diffs: Array<{ path, oldText: string | null, newText }> },渲染层按现有 file_change 工具的展示方式显示;oldText: null 表示新文件;这些 diff 同时供 AI 行归属账本(P2-06)使用。
  • 其它 update:plan → todos_updated(内容、状态、优先级);usage_update → usage 事件(有 token 数时)+ context_snapshot(有窗口占用时),usageReporting 事实置为 exact;session_info_update 忽略标题(Kun 自己生成标题)。

harness_session_state 新事件(写入 kun/src/contracts/events.ts)承载 commands(≤200 条)与 configOptions(≤32 条),composer 斜杠菜单与模式/模型/推理强度控件据此刷新。

4.3 测试

用 P1-01 的场景夹具驱动映射器(不启进程),逐条断言输出:

场景 期望
基础对话 若干 text_delta,flush 后一条完整 assistant_text
思考 + 回答 reasoning 与 text 分开
工具调用正常顺序 ready → started → finished
update 先于 tool_call 占位后补全,不重复
重复终态 只 finished 一次
diff 结构化结果正确,oldText: null 表示新文件
plan todos 映射(状态、优先级)
usage usage + context 输出
未知 sessionUpdate 忽略并记 debug

5. P1-04:客户端方法(fs、终端、权限、取消)

文件 内容
kun/src/runtime/acp/acp-client-host.ts 注册 agent → 客户端的方法;contextFor(sessionId) 找到线程 / turn / 工作区 / 审批
kun/src/runtime/acp/acp-fs.ts readTextFile、writeTextFile
kun/src/runtime/acp/acp-terminal-registry.ts create / output / waitForExit / kill / release;句柄 Map<terminalId, { child, buffer, turnId }>;turn 结束时 stopOwnedProcess 全部
kun/src/runtime/acp/acp-permission.ts requestPermission;PendingPermissions:按 sessionId 跟踪,cancelAll(sessionId)

依赖:P1-02、P0-10(任务工作区),分支 codex/ade-acp-client-host。

5.1 路径边界

resolveInside(roots, path):path.resolve 后 realpath(不存在的写入目标取父目录的 realpath 再拼文件名),必须以某个根 + 分隔符开头;Windows 下大小写不敏感比较。读根 = 工作区 + additionalWorkspaces + 已挂载只读根;写根只允许任务工作区。越界即拒绝(JSON-RPC 错误),符号链接逃逸同样被 realpath 挡住。

5.2 写入审批、检查点与记录

  • 写入审批去重:ApprovalMemo:Map<turnId, Set<string>>,记录本轮已允许的 (kind, target);request_permission 允许后把 toolCall.locations[].path 加进去;writeTextFile 命中则不再询问。
  • 检查点:写入前调用 turn 生命周期里已有的 awaitWorkspaceCheckpoint(agent-loop-turn-lifecycle.ts 委派路径就是这么做的),保证变更前有快照。
  • 写入记录:写完产出一条 file_change 类的 tool 结果(toolName: 'acp:fs.write'),这样 Changes 面板与工作现场都能看到。
  • 终端:terminal/create 用 spawnOwnedProcess 启动(BackgroundShellRuntime 只是 bash 后台会话的登记表,不提供启动能力),句柄登记在 AcpTerminalRegistry(按 sessionId + turnId),turn 结束或取消时回收整棵进程树;输出环形缓冲,按 outputByteLimit 截断,output 返回 { output, truncated, exitStatus? }。
  • 取消:session/cancel 前先 cancelAll(sessionId),让挂起的权限请求都回复 { outcome: 'cancelled' }。

权限选择语义:Kun 的审批只有"这一次"的语义,永远不选 allow_always,除非选项里只有它;决策为 allow 时优先 allow_once,deny 时优先 reject_once。审批者为 agent(approve-for-me)时走现有 approvalReview 服务,和原生 loop 一致。

5.3 测试

用例 期望
读工作区外文件(含符号链接逃逸) JSON-RPC 错误
写入:未审批 触发审批;deny 时返回错误且文件未改
写入:同一工具调用已允许 不二次审批
写入前检查点 被调用
权限:永不选 allow_always(有 allow_once 时) 断言
终端:输出超限 truncated: true
终端:turn 取消 进程被回收(真实进程测试,POSIX 与 Windows CI 各一)
取消时挂起的权限 回复 cancelled

6. P1-05:运行时装配、内置定义与冒烟

文件 改什么
kun/src/runtime/acp/acp-runtime.ts(新) AcpRuntime implements DelegatedTurnRuntime:handlesRoute(route) = route.transport === 'acp';capabilitiesV2(route);runTurn()
kun/src/harness/build-harness-runtimes.ts 注册 acp
kun/src/harness/builtin-harnesses.ts 加 gemini-cli、codex、opencode 三个定义
kun/src/server/routes/harnesses.ts GET /v1/harnesses/:id/models 对 ACP harness 用"探测会话"取模型(开一个 session/new、读 config options、立即丢弃;结果缓存 10 分钟)

依赖:P1-03、P1-04、P1-07。

6.1 一轮(runTurn)的主干

async runTurn(threadId, turnId, signal): Promise<TurnRunOutcome> {
  const ctx = await this.loadTurnContext(threadId, turnId)
  const lease = await this.pool.acquire(ctx.connectionKey, () => this.connect(ctx))
  try {
    const session = await this.sessions.ensure(ctx, lease.connection)
    const prompt = buildPromptBlocks(ctx, session, lease.connection.initResult.agentCapabilities.promptCapabilities)
    const mapper = new AcpEventMapper(ctx, this.deps.recorder)
    const unsubscribe = lease.connection.onSessionUpdate(session.sessionId, (u) => mapper.apply(u))
    const onAbort = () => this.cancel(lease.connection, session.sessionId)
    signal.addEventListener('abort', onAbort, { once: true })
    try {
      const res = await lease.connection.rpc.request('session/prompt',
        { sessionId: session.sessionId, prompt }, { timeoutMs: ctx.limits.turnWallMs })
      await mapper.flush()
      await this.sessions.commit(session, ctx)
      return outcomeFromStopReason(res.stopReason, signal)
    } finally {
      signal.removeEventListener('abort', onAbort)
      unsubscribe()
    }
  } catch (error) {
    return this.failTurn(ctx, error)
  } finally {
    this.pool.release(lease)
  }
}

buildPromptBlocks 的块顺序:新建会话且有更早历史 → 交接简报文本块(第一块);用户消息正文 + composer contexts;图片附件(promptCapabilities.image 为真时转 image 块,否则转文件路径文本并在 UI 提示);文件引用转 resource_link 块(路径必须在工作区内);客户端表面说明追加在末尾,不进 harness 的 system prompt。

outcomeFromStopReason:end_turn → completed;max_tokens / max_turn_requests → completed(并追加系统提示说明因上限停止);refusal → failed(错误码 harness_refusal);cancelled → aborted。

取消流程:cancelPendingPermissions(sessionId) 先回复所有挂起权限为 cancelled,再 notify('session/cancel');给 agent 10 秒回复 cancelled,超时则标记连接不健康,下一次 acquire 重建进程。

6.2 内置定义的落地流程

在写定义之前,用真实二进制跑一遍并录制:

  1. 在开发机安装三个 CLI 的当前版本,记录版本号。
  2. 用一个最小脚本(kun/scripts/record-acp-session.mjs,不进发布包)以正确参数启动每个 agent,完成:initialize、session/new、一次提问、一次工具调用、一次取消。
  3. 保存 JSON-RPC 往返记录,脱敏后放进 kun/src/runtime/acp/__fixtures__/recorded/<harness>-<version>.jsonl。
  4. 定义里的 launch.args、detect.minVersion 以录制时确认可用的为准。
  5. 映射器测试增加"录制回放"用例:把录制的 agent 输出喂给映射器,断言产出的 Kun 事件序列(快照)。

冒烟清单(手动或夜间):对每个 ACP harness,一对一会话里完成一轮对话、一次需要审批的写文件、一次终端命令、一次中断、关闭应用再打开后继续对话(native 或 portable)。

7. P1-06:抽取 KunToolBridgeHost 共享执行宿主

分支 codex/ade-tool-bridge-host,提交 refactor(runtime): share kun tool execution across delegated runtimes,纯重构,行为不变。

步骤:

  1. 新建 kun/src/harness/kun-tool-bridge-host.ts,定义共享接口:listTools(threadId, turnId, { overlap })(已按 turn 的能力快照、计划上下文、surface 过滤,并去掉与 harness 内置重叠的工具)与 execute(threadId, turnId, call)(与 SDK 路径完全相同的执行语义:审批、沙箱、技能、计划写盘路径、画布回执)。
  2. 把 agent-sdk-runtime-factory-tools.ts 起 createAgentSdkToolRuntimeDeps().executeKunTool 的函数体整体移入 createKunToolBridgeHost(deps, context).execute;listTools 从 agent-sdk-runtime-factory-turn.ts 附近"取可桥接工具 + selectBridgeableTools"的代码抽出。
  3. Claude SDK 工厂改为调用宿主;Cursor 工具桥(cursor-sdk-tool-bridge.ts)的执行回调也改为调用宿主。
  4. SDK 特有的部分留在原处:mapKunResultToSdkContent、jsonSchemaToZodShape、toSdkMcpServer、Cursor 的 SDKCustomTool 适配。

listTools 复用 selectBridgeableTools 和 DEFAULT_OVERLAP_TOOL_NAMES(sdk-tool-bridge.ts)。ACP agent 的内置工具集合各不相同,overlap 集合放在 harness 定义里(HarnessDefinition.overlapTools,缺省用默认集合)。

测试:kun/src/runtime/agent-sdk、kun/src/runtime/cursor 现有测试全部通过;新增宿主的单测(计划上下文、审批、画布回执三条路径各一)。

8. P1-07:HarnessTokenService、Kun Tools MCP server 与 stdio 桥

文件 内容
kun/src/harness/harness-token-service.ts 04 §4 的令牌服务,grant 带 scopes: Array<'gateway' | 'kun-tools' | 'worker-callback' | 'hook-ingest'>;issue / verifyScope / revokeThread
kun/src/server/routes/kun-tools-mcp.ts handleKunToolsMcp:POST /mcp/kun(不放在 /v1/ 下,避免与运行时令牌鉴权混在一起);GET /mcp/kun 返回 405(不提供服务端推送流)
kun/src/server/kgw-token-guard.ts 在路由分发前检查:请求带 kgw_ 令牌时,只允许其 scope 对应的路径前缀,其余一律 401(放在现有运行时令牌鉴权之前)
kun/src/cli/mcp-bridge-cli.ts kun mcp-bridge --token-env <VAR>:stdio ↔ POST /mcp/kun 转发,逐条请求,不支持批量

依赖:P1-06,分支 codex/ade-kun-tools-mcp。

8.1 为什么需要 MCP server

ACP agent 只能通过 session/new 的 mcpServers 拿到额外工具;Kun 目前只有 MCP 客户端依赖(@modelcontextprotocol/client),没有服务端,因此本实施项手写最小服务端。

8.2 最小子集实现(不引入新依赖)

JSON-RPC 方法 处理
initialize 协商协议版本(取客户端请求版本与本端支持列表的交集中最新的),capabilities: { tools: { listChanged: false } },serverInfo: { name: 'kun' }
notifications/initialized 记录会话已初始化,返回 202
ping 空结果
tools/list host.listTools() → { name, description, inputSchema };分页可选
tools/call host.execute() → { content: [...], isError }
其它 JSON-RPC -32601

关键约束:

  • 身份:每个 harness 会话一个 kun-tools 范围令牌,绑定 threadId。工具调用落在该线程当前运行中的 turn;没有运行中的 turn 时拒绝(返回工具错误),保证"工具只在一轮对话里执行"。
  • 审批:走 host.execute 内部的 ApprovalGate,和 SDK 路径一致;MCP 协议层不做任何放行。
  • 批量请求不支持(返回 400),避免身份混淆;请求体上限 1 MiB。
  • stdio 形态:kun mcp-bridge --token-env KUN_TOOLS_TOKEN,令牌通过环境变量传,不进 argv(argv 在进程列表里可见)。

MCP 协议版本:initialize 协商时维护 SUPPORTED_MCP_PROTOCOL_VERSIONS(实现时以 MCP 官方规范列出的 streamable HTTP 版本为准,选 2–3 个);客户端请求的版本在列表中则回同一版本,否则回列表中最新的版本;客户端不接受时由它断开。

8.3 测试

用例 期望
无令牌 / 错误签名 / 错误 scope 401
kgw_ 令牌访问 /v1/threads 401(guard 拦截)
tools/list 与 SDK 路径同一 turn 的可桥接工具集合一致
tools/call 无运行中 turn 返回工具错误
tools/call 需要审批的工具 走 ApprovalGate
stdio 桥 两个请求往返正确;令牌不出现在 argv

9. P1-08:网关公共部分抽取 + Anthropic messages 入口

分支:先 codex/ade-gateway-core(重构),再 codex/ade-gateway-messages(新入口);两个 PR。

9.1 PR A:抽取(行为不变)

kun/src/server/routes/openai-model-gateway.ts 拆为:

  • model-gateway-core.ts:guardFor、authorizePublicGateway、readJsonBody 包装、gatewayMessagesToTurnItems(从 makeModelRequest 里"消息 → TurnItem"的部分抽出,定义中间形态 GatewayMessage)、parseTools、错误辅助。
  • openai-model-gateway.ts:chat / responses 的入站解析与出站 SSE / JSON。

测试:openai-model-gateway.test.ts 不改并通过。

9.2 PR B:messages 入口

文件 内容
kun/src/server/routes/anthropic-messages-gateway.ts gatewayMessages(runtime, request)、gatewayCountTokens(runtime, request);入站映射 Anthropic → ModelRequest,出站映射 Kun 流 → Anthropic SSE
kun/src/server/routes/register-core-routes.ts 加 POST /v1/messages、POST /v1/messages/count_tokens

从当前源码看,仓库已实际注册了 POST /v1/messages(register-core-routes.ts),入口 gatewayMessages 位于 openai-model-gateway-anthropic.ts;鉴权复用 GatewayRequestGuard,同时接受 Authorization: Bearer 与 x-api-key(Anthropic 风格客户端只带后者,见 gateway-request-guard.ts),并带 token bucket 限流(默认容量 20、每秒补充 1)与并发租约(默认并发 2、超时 120 秒)。当前实现经由 resolveGatewayModel 从路由池解析模型;P1-09 将在此之上增加 kun/<providerId>/<model> 直接寻址。

  • 本 PR 只支持路由池模型(与现有公共网关一致);直接寻址与 harness 令牌在 P1-09。
  • count_tokens:用 kun 现有的请求 token 估算函数(上下文容量计算用的那个),响应加头 x-kun-estimate: true。

9.3 入站映射:Anthropic → ModelRequest

ModelRequest(kun/src/ports/model-client.ts)的对话历史是 prefix / history: TurnItem[],不是聊天消息数组。现有网关的 makeModelRequest(openai-model-gateway.ts)已实现"聊天消息 → TurnItem",抽到 model-gateway-core.ts 作为 gatewayMessagesToTurnItems(messages: GatewayMessage[]),Anthropic 入口先转成同一个中间形态 GatewayMessage 再复用它:

Anthropic 内容块 Kun 消息
user text user 文本
user image(base64 / url) 图片部分(目标模型不支持视觉时返回 400 并说明,不静默丢图)
user tool_result tool 结果消息,按 tool_use_id 关联
assistant text assistant 文本
assistant thinking / redacted_thinking 丢弃(不回传给非 Anthropic 模型)
assistant tool_use assistant tool call
document、服务端工具(web_search 等) 400 unsupported_content,并在能力里标注
  • thinking 块回传时在入站被丢弃,不会造成签名校验错误。
  • tool_choice: { type: 'any' } 与 'none':ModelRequest 没有对应字段;none 通过传空 tools 实现,any 退化为 auto 并记 debug。
  • 历史修复:入站历史必须经过 Kun 现有的 model-history repair(孤儿 tool_result、缺结果的 tool_call),和原生 loop 同一条规则。

9.4 出站映射:Kun 流 → Anthropic SSE

核心事件序列(测试基准):

message_start → content_block_start(text) → content_block_delta(text_delta)… → content_block_stop
→ … → message_delta(stop_reason) → message_stop
  • assistant_text_delta → text_delta;assistant_reasoning_delta → thinking_delta(非 Anthropic 模型给出的推理只作为 thinking 展示,不带签名)。
  • tool_call_delta(有参数增量的 provider)→ input_json_delta 逐段;tool_call_complete(只有 complete 的 provider)→ 一次性 input_json_delta。两种都是合法的 SSE 序列。
  • stop_reason 映射:tool_calls → tool_use;length → max_tokens;其余 → end_turn。
  • 用量字段:input_tokens = 未命中缓存的输入;cache_read_input_tokens = provider 原生命中数;output_tokens = 输出(沿用 Kun 缓存统计口径,优先 provider 原生字段)。
  • 非流式请求:累积后一次性返回 message JSON,与流式累积结果一致。
  • image_generation_complete(Codex 类生图)在 messages 入口不支持,映射为文本提示并在能力里标注。

9.5 测试

用例 期望
文本流式 事件序列:message_start → content_block_start(text) → delta… → stop → message_delta → message_stop
工具调用(有 tool_call_delta 的 provider) input_json_delta 逐段
工具调用(只有 complete) 一次性 input_json_delta
多轮 tool_use / tool_result 往返 历史转成 TurnItem 正确,孤儿 tool_result 被修复逻辑丢弃
thinking 块回传 入站丢弃,不报签名错误
非流式 与流式累积结果一致
图片 + 非视觉模型 400 并说明

10. P1-09:网关直接寻址、用量归属、Claude SDK 网关模式

文件 改什么
kun/src/harness/gateway-model-id.ts(新) parseGatewayModelId / formatGatewayModelId
model-gateway-core.ts 鉴权顺序:先 harnessTokens.verifyScope(token, 'gateway'),失败再试公共凭据;harness grant 允许 kun/<provider>/<model> 寻址且必须在 grant 的 routes 里;grant 的请求体上限 32 MiB、并发 4
用量 网关完成后按 04 §6 记账:usage 事件加 source: 'harness-gateway'、harnessId;ModelRequest.threadId 用 grant 的线程,turnId 用 ActivityStore 里该线程当前运行的 turn
kun/src/contracts/harness.ts HarnessDefinition.gateway(04 §8)
kun/src/runtime/agent-sdk/sdk-options-builder.ts credentialMode === 'kun-gateway' 时:buildHarnessEnv 注入 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL、ANTHROPIC_SMALL_FAST_MODEL,剥离 CLAUDE_CODE_OAUTH_TOKEN 等;resolveSdkModel 对 kun/ 前缀不做回退
kun/src/runtime/agent-sdk/agent-sdk-runtime-core.ts handlesRoute(route):route.harnessId === 'claude-code' && (route.credentialMode === 'native-login' || route.credentialMode === 'kun-gateway')
用量去重 网关模式下,SDK 自己报告的 usage 事件只写 context_snapshot,不写 usage(避免同一次调用计两遍)
src/renderer 用量面板 source 为 harness-gateway 的行显示"经 Kun 网关"

依赖:P1-08、P1-07、P0-04,分支 codex/ade-gateway-harness。

10.1 模型寻址

harness 会话里使用的模型 id 统一为 kun/<providerId>/<model>,例如 kun/deepseek/deepseek-v4-pro。解析正则:/^kun\/([^/]{1,128})\/(.{1,512})$/。这种直接寻址只对 harness 范围令牌开放;公共网关凭据仍只能用路由池 id,行为不变。除主模型外,允许一个"小模型"路由(Claude Code 会用小模型做后台任务),默认取 roles.smallModel,没配则用主模型。

10.2 harness 范围令牌

export type HarnessGatewayGrant = {
  grantId: string
  threadId: string
  harnessId: HarnessId
  routes: Array<{ providerId: string; model: string; role: 'main' | 'small' }>
  maxConcurrent: number          // 默认 4
  maxBodyBytes: number           // 默认 32 MiB(长上下文请求远大于公共网关的 2 MiB)
  expiresAt: number              // 进程级有效;Kun 重启即全部失效
}
  • 令牌形如 kgw_<grantId>.<sig>,secret 为进程内 randomBytes(32),不落盘;同一 (harnessId, credentialIdentity, threadId) 在本进程内得到同一个令牌,保证 spawn env 逐字节稳定。
  • verify 用 timingSafeEqualHex 做常量时间比较,防时序侧信道。
  • 令牌只在内存里,Kun 重启后全部失效;harness 进程是 Kun 的受管子进程,也会随之重建。令牌不写日志;debug 记录里只写 grantId 前 8 位。
  • 线程删除、worker 释放、harness 被禁用时 revokeThread,已发出的令牌立即失效。

10.3 注入到 harness 的 gateway 定义

HarnessDefinition 增加可选字段:

gateway: z.object({
  protocol: z.enum(['anthropic-messages', 'openai-responses', 'openai-chat']),
  env: z.object({
    baseUrl: z.string().regex(/^[A-Z][A-Z0-9_]*$/),     // 例如 ANTHROPIC_BASE_URL
    token: z.string().regex(/^[A-Z][A-Z0-9_]*$/),       // 例如 ANTHROPIC_AUTH_TOKEN
    model: z.string().regex(/^[A-Z][A-Z0-9_]*$/).optional(),
    smallModel: z.string().regex(/^[A-Z][A-Z0-9_]*$/).optional()
  }).strict(),
  /** 必须从 env 里删掉的变量:否则 harness 会优先用它们,悄悄绕过网关 */
  stripEnv: z.array(z.string()).max(32)
}).strict().optional()

Claude Code(agent-sdk transport)的示例定义:

{
  protocol: 'anthropic-messages',
  env: { baseUrl: 'ANTHROPIC_BASE_URL', token: 'ANTHROPIC_AUTH_TOKEN',
         model: 'ANTHROPIC_MODEL', smallModel: 'ANTHROPIC_SMALL_FAST_MODEL' },
  stripEnv: ['ANTHROPIC_API_KEY', 'CLAUDE_CODE_OAUTH_TOKEN', 'CLAUDE_CODE_USE_BEDROCK', 'CLAUDE_CODE_USE_VERTEX']
}
  • baseUrl 是 kun serve 的 loopback 地址(http://127.0.0.1:<port>),SDK 自己拼 /v1/messages;网关只监听 loopback(沿用 kun serve 现有绑定)。
  • Claude SDK 适配器的"网关模式":sdk-options-builder.ts 的 buildScopedEnv 在 credentialMode === 'kun-gateway' 时注入以上变量,并跳过写 CLAUDE_CODE_OAUTH_TOKEN;resolveSdkModel 对 kun/ 前缀的模型不做 isAnthropicModel 回退。
  • 其他 harness 的变量名在接入时按其官方文档填写并测试,不预先写死。

两条原则:

  1. 永远经网关,即使 harness 自己能直连某个兼容 provider。直连意味着把 provider 密钥放进 harness 进程环境,而 harness 能跑任意命令(能读到自己的环境变量)。
  2. 多一跳翻译的代价是 Kun ModelRequest 表达不了的上游特性会丢失,这些特性在能力收窄表中显式标为不支持,而不是静默失效。

10.4 能力收窄与用量归属

credentialMode: 'kun-gateway' 时按 routeConstraints 层收窄能力:imageInput 取目标模型 profile 的 inputModalities;reasoningStream 取模型 profile 的 reasoning 声明;服务端工具(网页搜索等)不支持;usageReporting 为 exact(Kun 自己记账);提示缓存透传 provider 原生缓存(DeepSeek 自动前缀缓存可用),Anthropic cache_control 标记被丢弃,命中率以 provider 实际为准。

用量归属:attributeUsage 把经网关的请求记入发起它的线程——turnId = runtime.activity.currentTurnFor(grant.threadId),没有运行中的 turn(后台请求)时记在线程级。usage 事件新增可选字段 source: 'native' | 'harness-gateway' | 'harness-reported',用量面板据此区分"Kun 自己算的"与"harness 报告的";走网关的 harness 会话,harness 自己报告的 usage 只用于上下文显示,不入账,避免同一次调用计两遍。这让"Claude Code + DeepSeek"的费用出现在 Kun 用量里,和原生 loop 一样可按线程、按天、按模型查看。

10.5 测试

用例 期望
harness grant 请求 grant 外的模型 404
公共凭据请求 kun/... 404
用量归属 记在 grant 的线程与当前 turn;没有运行中 turn 时记线程级
去重 同一轮只有网关一条 usage
Claude SDK 网关模式环境 子进程环境有 BASE_URL / AUTH_TOKEN,没有 OAUTH_TOKEN 与 provider 密钥
端到端(夜间) 真实 Claude Code + 网关 + DeepSeek 完成"读文件 → 修改 → 回答"

11. 安全要点与实现约定

  • 四种 scope 的令牌互不通用:gateway(/v1/messages*、/v1/chat/completions、/v1/responses、/v1/models)、kun-tools(/mcp/kun)、worker-callback(/v1/worker-callbacks/*)、hook-ingest(/v1/activity/hooks)。终端 agent 拿到的令牌不能调用模型网关或 Kun 工具。
  • harness 令牌只能访问网关相关路径,访问任何其它 /v1/* 路由返回 401(在路由分发前按令牌前缀 kgw_ 拦截,见 kgw-token-guard.ts)。
  • 每个 grant 有并发上限和请求体上限,超出返回 429 / 413。
  • 所有回调路由都有请求体上限和速率限制。
  • 每个实现文件控制在 700 行以内;acp-event-mapper.ts 预计最大,工具调用映射单独拆 acp-tool-call-mapper.ts。
  • 错误处理口径(03 §9):命令不存在/启动失败、initialize 超时(20s)、需要认证 → harness_not_ready 并指向设置页;进程在一轮中退出 → harness_crashed;JSON 解析失败/未知必需字段 → harness_protocol_error;agent 调用未声明的客户端方法 → JSON-RPC method not found。所有错误文案不包含凭据、完整环境变量或未脱敏路径。
  • 观测:复用 ModelRequestTraceDelegated,每轮记录 harnessId、协议版本、sessionId(哈希)、stopReason、耗时、工具调用数;LLM debug 打开时 JSON-RPC 帧先脱敏(去掉 headers、env、文件全文,只保留长度和哈希)再写入 debug sink。

12. 相关文件索引

登录后查看全文
Kun