ACP 扩展命名空间参考

公共

公共可选扩展。标准 ACP 面（cbc --acp）可见或可选携带；缺失不影响协议可用；第三方客户端可以安全地读取、按需忽略。

私有

多租户私有通道，仅 session-payload 组合根（WorkBuddy daemon ↔ CLI、multi-owner-headless）生产与消费。第三方 ACP 客户端不得生产这些键；标准面永远不会要求它们。

A

142

真正的 _meta 扩展键

§3（全部列出）

B

44

JSON-RPC 扩展方法/通知名（_codebuddy.ai/*），被 grep 切掉了下划线

§4（全部列出）

C

3

命名空间前缀 / 通配写法，不是独立键

§5.1

D

6

产品站 URL 路径伪命中（https://www.codebuddy.ai/...）

§5.2

runtimeAdmission

A→C

公共

CLI，runtime-admission-acp-adapter.ts:10-11,30-39（initialize 响应）

session-payload 侧的 daemon（据此构造 envelope）；标准面客户端可忽略

进程准入握手：schemaVersion / runtimeProfile / runtimeConfigSha256 / processInstanceId / handshakeNonce。两条组合根都发，零 meta e2e 用它锚定 runtimeProfile === 'cbc-headless'

sessionAdmissionV2

C→A

私有

multi-owner issuer（进程外签发）；WorkBuddy 家族现仅剩 host control sidecar（workbuddy-host-control-authority.ts）

runtime-admission-acp-adapter.ts:47-53、multi-owner-acp-admission-service.ts:164

session/new / session/load 的准入 envelope。缺失即 ACP Session request is missing sessionAdmissionV2 metadata。process-login 与 C3 后的 workbuddy-single / completion-warm 均由 CLI 自产覆盖，客户端无需也不应携带

sessionGrantV1

C→A

私有

daemon，workbuddy-runtime-admission.tsbuildSessionGrantMetadata（C3 新增）

workbuddy-single-admission-authority.tsreadWorkbuddySessionGrant（仅 workbuddy-single 装配）

身份撤出 _meta 后仍需过 wire 的非身份业务授权：canonicalSessionId（daemon 的会话主键，captureRuntimeBinding 断言回报相等）/ environment.values（prewarm 命中路径下 session 增量 env 的唯一送达通道）/ workspace{root,cwd,allowedRoots}。不参与身份决策；标准 ACP 面不读该键

completionDispatchGrantV1

C→A

私有

daemon，workbuddy-runtime-admission.tsbuildCompletionDispatchGrantMetadata（C3 新增）

workbuddy-single-admission-authority.tsreadWorkbuddyCompletionDispatchGrant（仅 completion-warm 装配）

completion warm 的 per-dispatch 执行授权：executionSubPolicyId + 其 digest / dispatchId / executionDigest / workspace。身份来自进程级注入，执行天花板仍逐 dispatch 由 daemon 下达；缺该键即 fail-closed

authSession

C→A

私有

daemon（session-payload 身份种子）

acp-agent.ts:2141-2143 → per-session auth holder

{ auth: { accessToken, tokenType?, domain?, refreshToken? }, account?: { uid? } }。account 字段一律由 JWT 派生，绝不采信客户端自报

productConfig

C→A

私有

daemon（workbuddy-server/src/agent/cli-product-env.ts:170）

acp-agent.ts:2144-2146

per-session 产品配置注入：endpoint / networkEnvironment

runtimeTransportCredential

双向

私有

准入核心（multi-owner-acp-admission-service.ts:38-39、host-teammate-admission-security.ts:41）

同上

绑定 transport 的一次性凭据，用于 admit 时证明连接身份

runtimeSessionBindingV2

A→C

私有

multi-owner-acp-admission-service.ts:40-41、workbuddy-session-admission-authority.ts:18

daemon

准入成功后回带的 exact binding 投影：ownerId / ownerGeneration / canonicalSessionId / sessionGeneration / resourceId

runtimeBindingToken

C→A

私有

daemon

agent-client-protocol/src/common/runtime-wire-authority.ts:1、acp-agent.ts:2147-2155

wire 请求的 binding token；非空字符串否则 RUNTIME_BINDING_TOKEN_INVALID

runtimeAuthority

双向

私有

daemon / CLI

runtime-wire-authority.ts:2

wire fencing 权威快照（processIncarnation / connectionEpoch / owner / session / run 各代际），失配抛 RUNTIME_*_STALE

teamNamespaceActivation

C→A

公共

leader 启动 teammate 时注入（host-teammate-launch.ts:138、workbuddy-teammate-launch.ts:124）

teammate 子进程

team 命名空间激活声明。两条组合根共用，不是 session-payload 独有；第三方客户端不会遇到。限定：唯一消费通道是 teammate bootstrap 启动链（teammate-runner.ts:272 从 receiveWorkbuddyTeammateBootstrap 返回的 bootstrap metadata 上读取），不是 ACP wire 上的客户端 _meta；第三方客户端在标准 ACP 面生产该键不会被任何路径消费

userinfo

A→C

公共

acp-agent.ts:1963-1974（authenticate 响应）

客户端 UI

登录用户信息：userId / userName / userNickname / enterpriseId / enterpriseName / authType

accessToken

-

私有

无生产者（协议上不存在）

-

仅出现在日志脱敏覆盖用例（workbuddy-core/.../conversation-file-logger.spec.ts:44）：验证“带命名空间前缀的 token 键同样被 [redacted]”。列在此处防止今后误当作可用键

homeDir

-

公共

已退役

-

已退役死字段，生产与消费两侧代码均已物理删除（D6-7）：全仓唯一命中是反向门禁用例 settings-persession-invariants.spec.ts:10，断言 acp-agent.ts 里不再出现该键——连存量兼容读侧都没有，客户端携带不会被任何路径读取。homeDir 恒由 JWT 派生（resolveControlledHomeDir）。仅为“不要重新启用该键名”而留档

requestId

双向

acp-agent.ts:2925,3412

一次模型请求的全链路关联 ID（命中数最高的键）

messageId

双向

acp-agent.ts:2937,3349

消息级 ID

messageRequestId

双向

acp-agent.ts:2932,3423

消息 ↔ 请求的关联 ID

userMessageId

双向

acp-agent.ts:2931

用户消息 ID（session/prompt 响应也回带）

promptRequestId

双向

acp-agent.ts:3415-3416

Renderer 每次 send/resend 生成的业务关联 ID，供 Desktop 埋点 + Galileo 串联

clientRequestId

C→A

客户端

工具调用上的客户端自定义关联 ID（workbuddy-server/src/session/handlers.ts:1634）

modelRequestId

A→C

acp-view.ts:694

模型侧请求 ID

traceId

A→C

acp-agent.ts:3075

CLI 侧 trace ID

traceparent

A→C

acp-agent.ts:2866,3429

W3C traceparent 回传，使 renderer 的 stream_render span 能挂到 prompt.send 下

runId

A→C

acp-agent.ts:263

SessionRunStateMachine 的 run ID

runStateRevision

A→C

acp-agent.ts:262

run 状态快照 revision

agentPhase

A→C

acp-agent.ts:261

Agent 执行阶段（AgentPhaseInfo）

timestamp

A→C

acp-timestamp-meta.ts:124-128

时间戳（归一化时会删除该扁平键，统一走规范位置）

sendTime

C→A

Renderer

用户点击发送的时间戳，供 message 维度用户视角 TTFT 计算（galileo-timing-hook.ts:110）

lfConvId

A→C

上游

LF 会话 ID（扁平透传，agent-ui/src/adapters/acp-message-accumulator.spec.ts:1132）

lfConvReqId

A→C

上游

LF 会话请求 ID（同上）

mode

双向

公共

acp-agent.ts:2984,3072

场景模式（scene mode）

userId

C→A

公共

Renderer → session.meta（acp-agent.ts:2888）

埋点 / trace attribute 用的用户 ID（不参与身份决策，身份只认 JWT）

conversationId

双向

公共

acp-agent.ts:2889 / workbuddy-app/.../stream-span-manager.ts:144

上游会话 ID

locale

C→A

公共

acp-agent.ts:2890（兼容 language）

语言 / 区域

expertId

双向

公共

acp-agent.ts:2891,2987

专家（expert）ID

expertSelection

A→C

公共

workbuddy-server/.../expert-selection-reminder.ts:7

专家选择提醒块标记

parentSessionId

A→C

公共

acp-protocol.ts:319,342

子代理会话的父 session ID

isSubAgent

A→C

公共

acp-protocol.ts:319,342

是否子代理会话（注意与下面 isSubagent 大小写不同，属历史遗留双写）

isSubagent

A→C

公共

api-schema.ts:1803、use-acp.ts:284

工具调用维度“是否子代理调用”

subagentType

A→C

公共

api-schema.ts:1804

子代理类型（默认 general-purpose）

isBackground

A→C

公共

api-schema.ts:1805

是否后台执行

isPlayground

A→C

公共

stream-span-manager.ts:148

是否 playground 场景

continue

C→A

公共

acp-agent.ts:2560

session/new 上声明“继续上次对话”

sessionControl

双向

公共

workbuddy-core/.../conversation-prompt-operations.ts:12

会话控制指令载荷

errorMessage

A→C

公共

acp-agent.ts:414,3066

与 stopReason: 'refusal' 并列的可读错误文案

finishReason

A→C

公共

acp-view.ts:703

模型 finish reason

outcome

A→C

公共

acp-agent.ts:3087-3088

prompt 结果判定（SUCCESS 等）

businessFailed

A→C

公共

acp-utils.ts:1004

业务失败标记，供 UI renderer 与传输失败区分

cancelReason

A→C

公共

acp-protocol.ts:973

取消原因

cancelCause

A→C

公共

automation-prompt-builder.ts:285

prompt result 上的取消成因（automation 优先读它）

terminationReason

A→C

公共

acp-broadcast-service.ts:435

终止原因（如 prompt_timeout）

promptFailurePhase

A→C

公共

workbuddy-server/src/backend/prompt-replay-safety.ts:2

prompt 失败发生的阶段

promptFailureReason

A→C

公共

同上 :3

prompt 失败原因

promptReplaySafe

A→C

公共

同上 :1

该次失败是否可安全重放

transportLost

A→C

公共

workbuddy-agent-adapter-next.ts:10689

传输连接丢失标记

transportError

A→C

公共

同上 :10690

传输错误码（如 ws_rpc_connection_lost）

toolName

acp-agent.ts:4093,4168

工具名

toolCallId

acp-broadcast-service.ts:287

关联的工具调用 ID

parentToolCallId

acp-agent.ts:3949,4004

父工具调用 ID（子代理嵌套）

toolCancelReason

acp-agent.ts:578

工具取消原因（permission_denied 用于与普通取消区分）

toolFailReason

acp-agent.ts:650

工具失败原因分类

toolResultTitle

persisted-transcript-projector.ts:72

工具结果标题（转写投影用）

description

acp-agent.ts:5047,6344

工具调用描述

operation

acp-agent.ts:5046,6343

操作类型（如 mcp-ui reverse tools/call）

target

acp-agent.ts:5045,6342

操作目标（如 MCP server 名）

filename

acp-utils.ts:654

关联文件名

images

acp-broadcast-service.ts:684

图片载荷

rawResponse

acp-utils.ts:997

工具原始结构化结果，透传给 UI renderer（如 web-search）

bulkDeleteInfo

acp-agent.ts:5059-5060

批量删除信息

bypassHint

acp-agent.ts:5056-5057

旁路提示

interceptType

acp-agent.ts:5044,6758

拦截类型

sandboxIntercept

acp-agent.ts:5013,5043

沙箱拦截标记

sandboxApprovalMode

acp-agent.ts:5053-5054

沙箱审批模式

mcpUiIntercept

acp-agent.ts:4853,6341

MCP-UI 反向调用拦截标记

hook

acp-utils.ts:770、session-manager.ts:766

Hook 结构化阻断信息

details

acp-agent.ts:6800

事件补充明细

decision

acp-broadcast-service.ts:289

权限决策结果

permissionResolved

acp-broadcast-service.ts:286

权限已解决通知

planContent

api-schema.ts:1808

ExitPlanMode 的计划正文

goalProgress

use-acp.ts:491-492

目标进度

goalRecap

acp-broadcast-service.ts:487

目标回顾

goalStatus

use-acp.ts:522-523

目标状态

interruptionRequest

acp-broadcast-service.ts:221、session-replay.ts:692

中断（HITL）请求载荷

promptSuggestion

prompt-suggestion-service.ts:502

Prompt 建议

historyReplay

A→C

公共

session-replay.ts:392

历史回放边界标记（start / 结束）

historyReplayTotalItems

A→C

公共

session-replay.ts:393

回放总条目数（仅 start 时）

rendererHistoryReplay

A→C

公共

conversation-frame-classifier.ts:83、replay-event-classifier.ts:82

渲染层回放标记

ownerSnapshotHistoryReplay

A→C

私有

replay-event-classifier.ts:87、conversation-frame-classifier.ts:84

owner 快照回放标记——owner 概念只在 session-payload 多租户下成立

isSessionSeparator

A→C

公共

conversation-frame-classifier.ts:91

会话分隔帧标记

separatorExtra

A→C

公共

同上 :94

分隔帧附加信息

createTime

A→C

公共

同上 :93

帧创建时间

offset

A→C

公共

workbuddy-agent-adapter-next.ts:6458

转写源 offset（旧键）

sourceOffset

A→C

公共

agent-member-utils.ts:242、team-runtime.ts:461

转写源 offset（新键，优先于 offset）

originalBytes

A→C

公共

persisted-transcript-projector.ts:71

转写截断前的原始字节数

compactType

context-protocol.ts:231

压缩类型，desktop adapter 据此决定呈现

compactStatus

conversation-frame-classifier.ts:231

压缩状态

compact-cancelled

context-protocol.ts:287

{ cancelled: true } —— 压缩被取消

compact-limit-reached

context-protocol.ts:295

{ limitReached: true } —— 触达压缩上限

compactTruncated

persisted-transcript-projector.ts:70

该帧在压缩中被截断

isCompactInternal

acp-agent.ts:3200,3396

该 prompt 是 compact 内部触发（不计入用户可见轮次）

teamUpdate

A→C

公共

acp-team-bridge.ts:745,779

Team 状态事件（成员状态变更等）

memberEvent

A→C

公共

acp-team-bridge.ts:602

成员流式消息的归属标签（成员名）

memberName

A→C

公共

acp-agent.ts:5037

工具调用所属成员名

isTeamMember

A→C

公共

acp-agent.ts:5036

该工具调用来自 team 成员

agentColor

A→C

公共

acp-agent.ts:5039

成员展示色

syntheticTeammateMessage

A→C

公共

team-runtime-loader.ts:691、workbuddy-agent-adapter-next.ts:4945

合成的 teammate 消息（非模型直出）

teammateSummary

A→C

公共

同上 :693 / :4946

teammate 摘要文本

workflowEventKind

:151

事件类型

workflowRunId

:156,168

运行 ID

workflowName

:157

工作流名

workflowStatus

:158

运行状态

workflowAgentCount

:159

agent 总数

workflowCachedCount

:160

命中缓存的 agent 数

workflowPhaseCount

:161

阶段总数

workflowError

:163

运行级错误

workflowPhase

:169

当前阶段

workflowAgentKey

:175

agent key

workflowAgentLabel

:177

agent 展示名

workflowAgentPhase

:180

agent 阶段

workflowAgentError

:183

agent 级错误

workflowAgentTokens

:186

agent token 消耗

channelSource

渠道来源标识

channelSender

发送者 ID

channelSenderName

发送者展示名

channelChatId

会话 ID

channelChatType

会话类型（single / group）

commandKind

命令种类（slash）

sendMessageMode

C→A

公共

MCP-UI widget（mcp-app-handlers.ts:79,112）

widget 回写消息的行为路由：send / fill

message_queue_update

A→C

公共

acp-broadcast-service.ts:462

消息队列增量更新

newSessionId

A→C

公共

acp-command-attachment-router.ts:73

命令触发新建会话后的新 sessionId

sessionReset

A→C

公共

acp-command-attachment-router.ts:72

会话被重置（如 /clear）

usageByCategory

A→C

公共

acp-protocol.ts:64,1331

usage_update 的分类用量；不变式：sum(usageByCategory) === update.used

contentFilterNotice

A→C

公共

context-protocol.ts:258

内容过滤提示（true 时该 text 块是过滤告知）

hiddenPromptContext

C→A

公共

colleague-mention-context.ts:15

该 prompt 块是隐藏上下文，不在 UI 呈现

progress

A→C

公共

acp-agent.ts:3820、stream-json-protocol.ts:554

session_info_update 上的进度载荷

sourceEvent

A→C

公共

acp-utils.ts:146

该 update 的来源事件客观描述（facets），供 adapter 分流

requestModelId

请求所用模型 ID

requestModelName

请求所用模型名

responseModelId

实际响应模型 ID

responseModelName

实际响应模型名（conversation-event-machine.ts:334）

status

A→C

公共

acp-session-info-router.ts:136-137、conversation-event-machine.ts:763

session_info_update 的状态字段

model

A→C

公共

stream-span-manager.ts:145

扁平模型名（span 归因用）

_codebuddy.ai/question

A→C（request）

公共

HITL 提问，等待客户端应答（acp-protocol.ts:900）

_codebuddy.ai/resolveInterruption

C→A（request）

公共

客户端回答中断请求（acp-agent.ts:5565-5570）

_codebuddy.ai/artifact

A→C（notify）

公共

产物推送（session-replay.ts:523）

_codebuddy.ai/command

A→C（notify）

公共

命令事件（types.ts:25）

_codebuddy.ai/checkpoint

A→C（notify）

公共

checkpoint 事件（session-replay.ts:601）

_codebuddy.ai/session/rollback

C→A（request）

公共

会话回滚（acp-agent.ts:5812）

_codebuddy.ai/session/rollbackFiles

C→A（request）

公共

文件级回滚

_codebuddy.ai/session/previewFileRollback

C→A（request）

公共

回滚预览

_codebuddy.ai/file_history_snapshot

A→C（notify）

公共

文件历史快照（types.ts:29）

_codebuddy.ai/fileTreeChanged

A→C（notify）

公共

文件树变更（须带 filePath）

_codebuddy.ai/authUrl

A→C（notify）

公共

登录跳转 URL（types.ts:27）

_codebuddy.ai/getUserInfo

C→A（request）

公共

拉取用户信息（acp-agent.ts:5578）

_codebuddy.ai/uiControl

A→C（request）

公共

UI 控制指令（types.ts:35）

_codebuddy.ai/system_init

A→C（notify）

公共

系统初始化通知

_codebuddy.ai/tool_input

A→C（request）

公共

工具输入征询（agent-provider/examples/question-example.ts:16）

_codebuddy.ai/delegateTool

A→C（request）

公共

工具代理执行（delegate-tool-manager.ts:299）

_codebuddy.ai/delegateToolsChanged

C→A（notify）

公共

客户端可代理工具集变更（acp-agent.ts:5580）

_codebuddy.ai/refreshPlugins

C→A（request）

公共

请求刷新插件（acp-agent.ts:5584）

_codebuddy.ai/plugins_changed

A→C（notify）

公共

插件集变更

_codebuddy.ai/mcp_servers_changed

A→C（notify）

公共

MCP server 集变更

_codebuddy.ai/models_changed

A→C（notify）

公共

模型列表变更

_codebuddy.ai/product_config_changed

A→C（notify）

公共

产品配置变更

_codebuddy.ai/identity_changed

A→C（notify）

公共

身份变更广播（主进程写入后广播到所有 live session）

_codebuddy.ai/queue_state_changed

A→C（notify）

公共

队列状态变更

_codebuddy.ai/message_queue_snapshot_changed

A→C（notify）

公共

消息队列快照变更

_codebuddy.ai/automation_snapshot

A→C（notify）

公共

automation 快照

_codebuddy.ai/interaction_timeout

A→C（notify）

公共

交互超时（cloud-agent-event-bridge.ts:10）

_codebuddy.ai/teams

A→C（notify）

公共

Team SSE 事件（use-collab-queue.ts:5）

_codebuddy.ai/conversation

A→C（notify）

公共

会话事件（use-conversation-events.ts:50）

_codebuddy.ai/mcpUiCallTool

C→A（request）

公共

MCP-UI 反向 tools/call

_codebuddy.ai/mcpUiReadResource

C→A（request）

公共

MCP-UI 读资源

_codebuddy.ai/mcpUiUpdateModelContext

C→A（request）

公共

MCP-UI 更新模型上下文

_codebuddy.ai/mcpUiRequestDisplayMode

C→A（request）

公共

MCP-UI 请求显示模式

_codebuddy.ai/mcpUiResourceTeardown

C→A（request）

公共

MCP-UI 资源释放

_codebuddy.ai/respondToSandboxIntercept

C→A（request）

公共

应答沙箱拦截（codebuddy-code-backend.ts:1909）

_codebuddy.ai/admitControl

C→A（request）

私有

control Session 准入。process-login 组合根直接 throw（process-login-acp-admission-service.ts:87-90），仅 workbuddy-host-sidecar 用

_codebuddy.ai/runtimeCredentialUpdate

C→A（request）

私有

per-session exact 凭据更新（acp-agent.ts:5595）

_codebuddy.ai/runtimeControlCredentialUpdate

C→A（request）

私有

control binding 凭据更新（acp-agent.ts:5597）

_codebuddy.ai/runtimeOwnerCredentialUpdate

C→A（request）

私有

owner 级批量凭据更新（acp-agent.ts:5599），对应 bulkApplyExactCredentialUpdates

_codebuddy.ai/activateWorkbuddyOwnerRuntime

C→A（request）

私有

C3 新增：向 workbuddy-single 进程注入一次 owner 授权（authSession + product 材料 + 凭据句柄），此后 session/new 零身份 meta。载荷 = {proof, processInstanceId, handshakeNonce, runtimeConfigSha256, ownerGeneration}，验证点 workbuddy-admission-security.tsactivateOwnerRuntime

_codebuddy.ai/activateCompletionRuntime

C→A（request）

私有

激活 completion warm 运行时；**C3 起 claims 追加 credentialMaterial**，同时承担 warm 侧的进程级 owner 注入，且凭据刷新后会以同 ownerGeneration、新 proof 重复调用（整体替换语义）

_codebuddy.ai/completionDispatch

C→A（request）

私有

分发一次 completion（acp-agent.ts:5738）

_codebuddy.ai/completionRuntimeDiagnostics

C→A（request）

私有

completion 运行时诊断（acp-agent.ts:5708）

_codebuddy.ai/disposeEphemeralSession

C→A（request）

私有

销毁 ephemeral session（acp-agent.ts:5676）

_codebuddy.ai/disposePersistentSession

C→A（request）

私有

销毁 persistent session（acp-agent.ts:5705）

_codebuddy.ai/example

——

——

测试用占位方法名，仅出现在 workbuddy-server/src/server-owned-handlers.spec.ts:2113，无生产实现

codebuddy.ai/

startsWith('codebuddy.ai/') / startsWith('_codebuddy.ai/')

命名空间前缀本身。守卫点：workflow-acp-bridge.spec.ts:82、sandbox-proxy/src/handler/artifacts-proxy.ts:70、sandbox-proxy/src/replay/replay.ts:1047

codebuddy.ai/workflow

注释里的 codebuddy.ai/workflow*

键空间通配写法（workflow-acp-bridge.ts:146），不是独立键

codebuddy.ai/mcpUi

注释里的 _codebuddy.ai/mcpUi*

5 个 MCP-UI 扩展方法的通配写法（mcp-apps-extmethod.spec.ts:4）

codebuddy.ai/docs

keybinding-template.ts:18,52、mcp-approval-box.tsx:16

codebuddy.ai/schemas

keybinding-template.ts:17,51

codebuddy.ai/login

chat-ui/src/browser/login/login.tsx:149

codebuddy.ai/agents

agent-ui/src/utils/workbuddy-share-origin.spec.ts:312

codebuddy.ai/profile

use-error-banner.tsx:186（.../profile/plan）

codebuddy.ai/v2

model-provider.spec.ts:454,520（API baseURL）