@archships/dim-acp-server

DimCode 扩展协议 (ext) 实现状态

本目录包含 DimCode 扩展协议（dimcode.*）的接口文档。以下是各接口和事件的实现状态汇总。

主要实现入口：packages/acp-server/src/agent.ts（extensionHandlers / notificationHandlers）

给接入 ACP client 的同事：凡是涉及 tool approval / ask-user 交互，请优先参照 native ACP 文档，而不是继续按 ext 事件接入。当前口径是：

• 权限交互：session/request_permission
• AskUserQuestion：session/elicitation（当前仅 form 模式）
• 参考文档：../native/README.md、../native/initialize.in.md、../native/session.elicitation.in.md、../native/session.elicitation.out.md

工作区路由约定

• dimcode.config.*、dimcode.providers.*、dimcode.mcp.*、dimcode.tools.*、dimcode.ui.* 这类 workspace-sensitive 扩展方法，当前都支持通过 cwd、sessionId，或两者同时来定位目标工作区。
• 若传入 sessionId，server 会优先解析该 session 已绑定的 cwd。
• 若同时传了 sessionId 和 cwd，且两者指向的工作区不一致，返回 invalidParams。
• provider/model/auth 等 env 解析按目标工作区现算，不会把某个 workspace 的解析结果写回成运行中的全局 serverEnv。
• 这些扩展方法只负责“按目标工作区解析/修改配置”，不会借机迁移一个已存在 session 的 workdir。

一、扩展方法（extMethod / extNotification）

所有 RPC 方法均已注册在 agent.ts 的 extensionHandlers 中，实现完整且均已编写文档。

config

方法	状态	实现位置
dimcode.config.get	✅ 已实现	extensions/config.ts
dimcode.config.update	✅ 已实现	extensions/config.ts
dimcode.config.reset	✅ 已实现	extensions/config.ts

events

方法	状态	实现位置	备注
dimcode.events.subscribe	✅ 已实现	agent.ts	同时支持 extMethod 和 extNotification 双路径
dimcode.events.unsubscribe	✅ 已实现	agent.ts	同上
dimcode.events.notification	✅ 已实现	agent.ts、stream/event-dispatcher.ts	仅 Server→Client 方向；不作为 extMethod 注册

mcp

方法	状态	实现位置
dimcode.mcp.list	✅ 已实现	extensions/mcp.ts
dimcode.mcp.get	✅ 已实现	extensions/mcp.ts
dimcode.mcp.create	✅ 已实现	extensions/mcp.ts
dimcode.mcp.update	✅ 已实现	extensions/mcp.ts
dimcode.mcp.delete	✅ 已实现	extensions/mcp.ts
dimcode.mcp.test	✅ 已实现	extensions/mcp.ts
dimcode.mcp.toggle	✅ 已实现	extensions/mcp.ts

providers

方法	状态	实现位置	备注
dimcode.providers.list	✅ 已实现	extensions/providers.ts
dimcode.providers.get	✅ 已实现	extensions/providers.ts
dimcode.providers.create	✅ 已实现	extensions/providers.ts
dimcode.providers.upsert	✅ 已实现	extensions/providers.ts	合并语义：存在则更新，不存在则创建
dimcode.providers.delete	✅ 已实现	extensions/providers.ts
dimcode.providers.switch	✅ 已实现	extensions/providers.ts
dimcode.providers.test	✅ 已实现	extensions/providers.ts
dimcode.providers.models	✅ 已实现	extensions/providers.ts	Legacy 兼容别名 (fetchProviderModelsLegacy)
dimcode.providers.models.list	✅ 已实现	extensions/providers.ts
dimcode.providers.models.get	✅ 已实现	extensions/providers.ts
dimcode.providers.updateModels	✅ 已实现	extensions/providers.ts
dimcode.providers.fetchModels	✅ 已实现	extensions/providers.ts

sessions

方法	状态	实现位置
dimcode.sessions.list	✅ 已实现	extensions/sessions.ts
dimcode.sessions.delete	✅ 已实现	extensions/sessions.ts
dimcode.sessions.rename	✅ 已实现	extensions/sessions.ts
dimcode.sessions.updateMetadata	✅ 已实现	extensions/sessions.ts
dimcode.sessions.export	✅ 已实现	extensions/sessions.ts
dimcode.sessions.getCanonicalSnapshot	✅ 已实现	agent.ts
dimcode.sessions.normalizeHistory	✅ 已实现	extensions/sessions.ts

skills

方法	状态	实现位置
dimcode.skills.list	✅ 已实现	extensions/skills.ts
dimcode.skills.get	✅ 已实现	extensions/skills.ts
dimcode.skills.create	✅ 已实现	extensions/skills.ts
dimcode.skills.update	✅ 已实现	extensions/skills.ts
dimcode.skills.delete	✅ 已实现	extensions/skills.ts
dimcode.skills.activate	✅ 已实现	extensions/skills.ts
dimcode.skills.deactivate	✅ 已实现	extensions/skills.ts
dimcode.skills.getActive	✅ 已实现	extensions/skills.ts

status

方法	状态	实现位置
dimcode.status.get	✅ 已实现	agent.ts (extGetStatus)
dimcode.status.health	✅ 已实现	agent.ts (extGetHealth)

subagent

方法	状态	实现位置
dimcode.subagent.explore	✅ 已实现	extensions/subagent.ts
dimcode.subagent.task	✅ 已实现	extensions/subagent.ts
dimcode.subagent.cancel	✅ 已实现	extensions/subagent.ts

tools

方法	状态	实现位置
dimcode.tools.getSettings	✅ 已实现	extensions/settings.ts
dimcode.tools.updateSettings	✅ 已实现	extensions/settings.ts

ui

方法	状态	实现位置
dimcode.ui.getSettings	✅ 已实现	extensions/settings.ts
dimcode.ui.updateSettings	✅ 已实现	extensions/settings.ts

二、通知事件（dimcode.events.notification 内的 event 类型）

通过 dimcode.events.subscribe 订阅后，服务端会以 dimcode.events.notification 推送以下事件。

关键说明：acp-server 有两条事件产生路径：

• Live turn — handleDimPromptEvent 处理 dim runtime 的实时事件流
• History replay — session/load 回放历史时通过 mapAcpMessageToServerEvents 映射

部分事件仅在历史回放时产生，live turn 中走的是 native ACP 原生协议而非 ext notification。

session 生命周期

事件	状态	Live turn	History replay	发射位置
session.created	✅ 已实现	✅	✅	agent.ts、stream/events.ts
session.updated	✅ 已实现	✅	—	agent.ts、extensions/sessions.ts
session.deleted	✅ 已实现	✅	—	extensions/sessions.ts

message 流

事件	状态	Live turn	History replay	发射位置
message.start	✅ 已实现	✅	✅	agent.ts、stream/events.ts
message.delta	✅ 已实现	✅	✅	agent.ts、stream/events.ts
message.end	✅ 已实现	✅	✅	agent.ts、stream/events.ts

thinking 流

事件	状态	Live turn	History replay	发射位置
thinking_start	✅ 已实现	✅	✅	agent.ts、stream/events.ts
thinking_delta	✅ 已实现	✅	✅	agent.ts、stream/events.ts
thinking_end	✅ 已实现	✅	✅	agent.ts、stream/events.ts

tool 流

事件	状态	Live turn	History replay	发射位置
tool.call	✅ 已实现	✅	✅	agent.ts、stream/events.ts
tool.output	✅ 已实现	✅	✅	agent.ts、stream/events.ts
tool.result	✅ 已实现	✅	✅	agent.ts、stream/events.ts

run 状态

事件	状态	Live turn	History replay	发射位置	备注
run.status	✅ 已实现	✅	✅	agent.ts、stream/events.ts
context.compression	✅ 已实现	✅	✅	runtime onCompressionEvent 回调、stream/events.ts	live turn 通过 AgentRuntime 的 onCompressionEvent 回调发出

插件

事件	状态	Live turn	History replay	发射位置
plugin.event	✅ 已实现	✅	—	agent.ts

配置变更

事件	状态	发射位置
config.changed	✅ 已实现	extensions/config.ts

provider 变更

事件	状态	发射位置
provider.created	✅ 已实现	extensions/providers.ts
provider.deleted	✅ 已实现	extensions/providers.ts
provider.models_updated	✅ 已实现	extensions/providers.ts
provider.switched	✅ 已实现	extensions/providers.ts

skill 变更

事件	状态	发射位置
skill.created	✅ 已实现	extensions/skills.ts
skill.updated	✅ 已实现	extensions/skills.ts
skill.deleted	✅ 已实现	extensions/skills.ts
skill.activated	✅ 已实现	extensions/skills.ts
skill.deactivated	✅ 已实现	extensions/skills.ts

MCP 变更

事件	状态	发射位置
mcp.created	✅ 已实现	extensions/mcp.ts
mcp.updated	✅ 已实现	extensions/mcp.ts
mcp.deleted	✅ 已实现	extensions/mcp.ts
mcp.toggled	✅ 已实现	extensions/mcp.ts

settings 变更

事件	状态	发射位置
tools.settings_updated	✅ 已实现	extensions/settings.ts
ui.settings_updated	✅ 已实现	extensions/settings.ts

subagent 生命周期

事件	状态	发射位置	备注
subagent.started	✅ 已实现	extensions/subagent.ts、ACP adapter
subagent.output	✅ 已实现	extensions/subagent.ts、ACP adapter
subagent.done	✅ 已实现	extensions/subagent.ts	host-driven 路径使用
subagent.cancelled	✅ 已实现	extensions/subagent.ts	host-driven 路径使用
subagent.error	✅ 已实现	extensions/subagent.ts	host-driven 路径使用
subagent.finished	✅ 已实现	ACP adapter	runtime delegation 路径使用，与 subagent.done 互补

三、设计说明

requires_action（已移除）

旧 requires_action 不再承载权限交互，也不再承载 ask-user 交互；这些能力都应按 native ACP 接入：

• tool approval：统一走 session/request_permission
• AskUserQuestion：统一走 session/elicitation（当前仅 form 模式）
• client 需要在 initialize 中声明 clientCapabilities.elicitation.form（兼容旧 harness 简写 elicitation=true）
• 若 client 未声明 elicitation 能力，server 当前会直接返回 unsupported error，不再回退旧 ext ask-user 桥接

因此，接 ACP client 的同事应直接参照 native 文档中的 elicitation 章节，而不是继续寻找 requires_action 的 ext 定义。

run.usage（已移除）

用量信息统一走 native session/update 的 usage_update 类型（标准 ACP 协议），不再作为 ext notification 发出。

四、统计

类别	已实现	合计
扩展方法	49	49
通知事件	37	37

• 所有 49 个扩展方法均已完整实现并编写文档。
• 37 个通知事件在 live turn 和 history replay 均正常发射（含 context.compression，通过 AgentRuntime 的 onCompressionEvent 回调实现）。
• requires_action 已移除；权限交互统一走 native session/request_permission，ask-user 统一走 native session/elicitation。
• run.usage 已移除，用量信息统一走 native session/update usage_update（标准协议）。