DeepSeek-Reasonix ACP 接入实战基于 Agent Client Protocol v1 的编辑器集成指南【免费下载链接】DeepSeek-ReasonixDeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.项目地址: https://gitcode.com/GitHub_Trending/de/DeepSeek-ReasonixReasonix 以 NDJSON JSON-RPC 2.0 agent 形态实现了 Agent Client ProtocolACPv1通过标准输入输出与编辑器等 ACP host 对话让 IDE 可以直接驱动 Reasonix 完成会话创建、流式消息、工具审批、计划展示与配置更新。本文以 docs/ACP.zh-CN.md 为骨架结合仓库源码internal/acp/protocol.go、internal/cli/acp.go逐层拆解 ACP 协议接入的完整链路读完你既能按检查清单把编辑器接入 Reasonix也能理解会话生命周期、厂商扩展与缓存兼容背后的实现原理。一、概述ACP v1 agent 与三大设计要点Reasonix 的 ACP 实现遵循三个核心设计纯 stdio 传输标准输出专用于 ACP 消息NDJSON JSON-RPC 2.0诊断日志写入标准错误因此 host绝不能合并两个流。从源码看internal/cli/acp.go 中的acpCommand明确以all diagnostics go to stderr为约束启动服务。会话隔离每个 ACP 会话拥有独立的 Controller、工作区根目录、模型、协作模式、审批模式、MCP 集合与持久化 transcript会话之间不泄漏状态。执行模式已移除普通请求一律进入 executor不存在自动任务模式唯一的会话角色是质量底线standard/delivery验证义务由宿主根据真实工具动作建立。internal/acp/quality_floor.go 中只暴露quality_floor配置项且仅有standard与delivery两个取值印证了这一简化。此外会话状态 usage 可携带结构化costQuote原币、originalTotals、identity/官方区域价表估值、costComplete、displayComplete、displayStatus、billingMode同时保留镜像所选展示估值的旧字段estimatedCost/currency。这一双重结构在 internal/acp/status_usage.go 的 wire 类型中均有体现详见计费文档。二、启动 agentreasonix acpACP host 应启动以下命令之一reasonix acp reasonix acp --model deepseek-pro--model仅在客户端未覆盖模型时用于选择启动模型会话建立后客户端可通过session/set_config_option或session/set_model切换。尚未配置 provider 时先运行reasonix setupinitialize响应也会声明一个启动reasonix setup的 terminal authentication methodAuthMethod结构见 internal/acp/protocol.go。从实现看acpCommand通过acpFactory为每个会话复用boot.Build逻辑将会话cwd作为WorkspaceRoot确保 ACP 会话与 CLI 聊天会话共享同一套运行时装配provider、以会话目录为根的工具、每会话 MCP见 internal/cli/acp.go。三、初始化与能力协商initialize客户端应在打开会话前调用initializeReasonix 会声明以下能力结构省略无关字段{ protocolVersion: 1, agentCapabilities: { loadSession: true, sessionCapabilities: { list: {}, resume: {}, close: {}, delete: {} }, promptCapabilities: { image: false, audio: false, embeddedContext: true }, mcpCapabilities: { http: true, sse: false }, _meta: { reasonix.io: { sessionSteer: { method: _reasonix.io/session/steer } } } } }上述字段与 internal/acp/protocol.go 中的InitializeResult、AgentCapabilities、SessionCapabilities、PromptCapabilities、MCPCapabilities一一对应。解读loadSession: true表示支持持久化会话加载sessionCapabilities声明了list/resume/close/delete四个可选生命周期方法。promptCapabilities只接受文本 block 与内嵌文本 resourceembeddedContext: true不声明图片与音频能力wire 上即使收到 image/audio block 也会被忽略见 internal/acp/protocol.go 的ContentBlock注释。mcpCapabilitiessession/new支持 stdio 与 Streamable HTTP MCP serverlegacy SSE 仅保持兼容解析sse: false。_meta[reasonix.io]是厂商扩展命名空间sessionSteer声明了回合中引导方法的真实名称详见下文扩展章节。客户端能力与编辑器 buffer 路由客户端声明fs.readTextFile、fs.writeTextFile或terminal后Reasonix 会让适用的文件操作经过编辑器的未保存 buffer并让适用的前台命令在客户端持有的 terminal 中运行读取、编辑、写入等全部文件工具都参与其中一次编辑作用于编辑器当前显示的内容而非磁盘上最后保存的副本非 UTF-8 文件不适用ACP 的文件方法只处理文本这类文件会留在本地的编码保持路径上原有字符集不变客户端未声明这些能力时常规工作区工具在 Reasonix 进程内本地运行。对应实现ClientCapabilities中的FSreadTextFile/writeTextFile与Terminal字段internal/acp/protocol.go以及 agent→client 的fs/read_text_file、fs/write_text_file、terminal/create、terminal/output、terminal/wait等请求类型internal/acp/protocol.go。_meta中未知或畸形的厂商能力条目会被宽容解析——对应厂商功能保持关闭不会导致握手失败。四、会话生命周期8 个核心方法方法行为session/new为绝对路径cwd打开会话并返回配置状态。session/load打开持久化 ACP 会话并通过session/update通知回放 transcript。session/resume打开持久化会话但不回放 transcript。session/prompt执行一轮任务流式发送更新最后返回停止原因。session/cancel取消活动回合它是一条 notification。session/list列出活动和持久化 ACP 会话可按绝对路径cwd过滤。session/close停止活动会话并释放资源但不删除历史。session/delete停止会话并删除其持久化 ACP 历史。实现要点session/load的 transcript 回放以一批session/updatenotification 的形式在请求返回前送达见 internal/acp/protocol.go 的SessionLoadParams/SessionLoadResult注释客户端应能接收批量更新突发。session/list目前返回单页结果NextCursor省略进程内列表不分页见SessionListResult注释。session/new、session/load、session/resume可携带mcpServers。Reasonix 支持 stdio、Streamable HTTP 和 legacy SSE serverstdioenv与 HTTPheaders支持 ACP 官方[{name:...,value:...}]结构同时继续接受旧版 object-map 结构。这一双格式解析在 internal/acp/protocol.go 的unmarshalNameValueMap中实现优先尝试官方数组形态失败后回退到旧 map 形态。五、会话控制独立控制轴与session/set_config_optionReasonix 把互不相关的选择拆成独立控制轴而不是混在一个 mode selector 中控制项可选值协议入口协作模式normal、plan、goalmodes和session/set_mode模型已配置的provider/modelid 为model的configOptions推理强度provider 支持的等级或autoid 为effort的configOptions工具审批ask、auto、yoloid 为tool_approval的configOptions模型、推理强度和工具审批统一使用session/set_config_option。参数是sessionId、configId和value其中configId取configOptions中该选项的id{ jsonrpc: 2.0, id: 3, method: session/set_config_option, params: { sessionId: session-id, configId: tool_approval, value: yolo } }注意字段名是configId不是optionId。返回值是刷新后的完整configOptions数组id 未知时返回-32602 InvalidParams。SetSessionConfigOptionResult还携带可选的deprecatedNotice字段internal/acp/protocol.go。切换模型或推理强度时会重建会话 Controller同时保留历史和其他控制轴工具审批只更新 gate不重建 Controller。acpFactory.RebuildSessioninternal/cli/acp.go正是这一重建语义的实现入口。兼容性说明执行模式已移除。兼容期内仍发送configId为agent_preset或work_mode含旧别名profile、runtime_profile、token_mode的session/set_config_option请求会得到成功的空操作不切换、不重建返回值中的deprecatedNotice会说明自适应标准执行。旧客户端仍可使用session/set_modellegacy model selector部分 host 仍会探测availableModels。session/set_mode继续接受 legacy 值default和auto分别表示常规 询问和常规 Yolo新客户端应使用上面的独立 selector。六、Prompt、更新与审批session/prompt支持文本 block 和内嵌文本 resource。执行回合期间Reasonix 可能发送agent 消息和思考内容 chunkagent_message_chunk/agent_thought_chunkpending 和 completed 工具调用更新tool_call/tool_call_update含可选的locations让编辑器定位到具体文件行从todo_write生成的完整计划更新plan每次携带完整计划并整体替换旧计划见 internal/acp/protocol.go可用的斜杠命令available_commands_update客户端可直接把/command文本回传给session/prompt当前 mode 和配置项更新current_mode_update/config_option_update针对受权限控制工具及用户问题的session/request_permission请求。Host 应让session/prompt请求保持打开直到 Reasonix 返回停止原因期间仍需同时处理双向 request 和 notification。停止原因与厂商状态Reasonix只会返回 ACP v1 规定的停止原因场景行为工作已完成但仍需 final-readiness 检查发送带[warning]的消息 chunk返回end_turn厂商状态保持readiness_paused便于 host 提供恢复入口显式模型轮数上限max_steps发送[warning]返回max_turn_requests记录 paused 厂商状态host 的任务时间/token/成本预算发送[warning]并记录 paused 状态但因 ACP v1 没有任务预算专用停止原因而返回end_turn模型正常结束且无工具调用返回end_turn响应含工具调用继续进入 Agent 循环真正的空响应在 frozen request 边界重试客户端取消始终返回cancelled即使被中断的 runner 没有返回 error其他 provider/工具/运行时失败返回 JSON-RPC-32603 InternalError消息携带长度受限且已脱敏的原因关键原则不会再用协议外的stopReason构造成功结果。SessionPromptResult的StopReason类型注释也写明failed turns are returned as JSON-RPC errors insteadinternal/acp/protocol.go。完成校验器已移除旧的completion_validation、completion_evaluator_model和REASONIX_COMPLETION_VALIDATION_MODE设置仍可读取但会被忽略且不再由配置渲染器生成。主机侧的就绪检查、预算、工具安全边界和恢复边界仍然有效。final-readiness 恢复状态 phase 为readiness_paused时可发送新的session/prompt并把可选action设为final_readiness_recovery以继续这一次检查。只发送/continue-checks文本 block 是兼容写法。两种方式都会消费一次持久化的 host checkpoint普通 prompt 不会继承该证据出现更新的用户消息后再提交旧 action 会以 JSON-RPC-32600 InvalidRequest被拒绝且不会发布或持久化虚假的状态回合。SessionPromptParams.Action字段的源码注释internal/acp/protocol.go明确空值保持 ACP 标准行为final_readiness_recovery显式恢复最新 paused 的 host 检查而不把普通散文当作授权。七、回合中引导扩展_reasonix.io/session/steerReasonix 通过 ACP v1 厂商扩展提供回合中引导mid-turn steering。它不是 ACP 核心方法也不是仍未发布的 ACP v2session/inject提案。发现能力从以下位置读取方法名agentCapabilities._meta[reasonix.io].sessionSteer.method不要假设该扩展一定存在也不要调用无命名空间的session/steer。ACP 为核心协议保留所有不以下划线开头的方法名客户端调用session/steer会得到-32601 MethodNotFound。实现中方法常量定义为sessionSteerMethod _reasonix.io/session/steerinternal/acp/protocol.go。发送引导在session/prompt仍处于活动状态时调用声明的方法{ jsonrpc: 2.0, id: 2, method: _reasonix.io/session/steer, params: { sessionId: session-id, prompt: [ {type: text, text: 把用户名改成邮箱} ] } }持久化会话会返回 item id 和 disposition{itemId:inbox-item-id,disposition:steer_accepted}Reasonix先完成持久化再返回。steer_accepted表示活动回合已接受queued_followup表示 admission 竞争失败或当前没有活动回合同一条持久化消息会保留为后续回合。无路径兼容会话可能不返回itemId但仍返回steer_accepted。已应用的消息会进入正常历史回放 transcript 时显示用户原文不显示内部 steer marker。完整的结果矩阵条件JSON-RPC 结果活动 prompt 接受持久化引导{itemId:...,disposition:steer_accepted}引导已持久化但活动 admission 被拒绝{itemId:...,disposition:queued_followup}session 不存在或 prompt 为空-32602 InvalidParams无路径兼容 session 没有活动 prompt-32600 InvalidRequest客户端调用session/steer-32601 MethodNotFound收到InvalidRequest时兼容会话没有把引导入队。八、持久化 Session Inbox 扩展从agentCapabilities._meta[reasonix.io].sessionInbox发现带版本的队列。Schema v1 在methodsmap 中声明方法名客户端应使用这里声明的名字不要自行拼接 vendor method。实现中的方法常量见 internal/acp/protocol.go_reasonix.io/session/inbox/enqueue、list、get、update、delete、move、setPaused、retry、refreshSessionInboxCapability的SchemaVersionMethods结构见同文件 internal/acp/protocol.go。Key用途主要参数enqueue持久化 follow-up 或 steersessionId、text可选intent、idempotencyKeylist读取元数据、容量、暂停和恢复状态sessionIdget按需读取一条完整 envelopesessionId、itemIdupdate/delete编辑或删除待处理项sessionId、itemIdmove调整待处理项顺序sessionId、itemId、从 0 开始的toIndexsetPaused暂停或恢复派发sessionId、pausedretry/refresh重试不确定项或重新冻结引用sessionId、itemIdenqueue返回itemId、disposition、position、paused和idempotent。List 只返回预览和字节数不返回正文。恢复出的 Inbox 默认暂停客户端应先让用户检查再用setPaused: false恢复派发。Inbox 数据模型位于 internal/sessioninbox/types.go持久化采用带版本的 sidecartranscript schema 保持不变。九、运行时重载与扩展表面Reasonix 还在agentCapabilities._meta[reasonix.io]中通告两个扩展点sessionReloadExtensions——vendor method_reasonix.io/session/reloadExtensions。调用后按与 CLI/reload相同的失败原子语义重载该会话的 agent 运行时扩展、工具、skills、commands、hooks、providers回合或重建进行中只排队一次{queued: true}空闲后执行否则原子重建并交换重建失败时保留旧运行时。重载成功后 Reasonix 会推送新的available_commands_update。返回结构SessionReloadExtensionsResult用Queued字段区分立即执行与排队等待见 internal/acp/protocol.go。extensionSurface——结构化扩展 UI 能力。在 initialize_meta中同样声明了reasonix.io.extensionSurface的客户端会收到结构化的扩展表面载荷vendorsession/update变体_reasonix.io/extension_surfaceschema v1未声明的客户端收到等价文本 fallbackcard/status 退化为agent_message_chunk扩展表单退化为权限请求因此客户端不做任何处理也能保持兼容。源码注释明确指出该 vendor 变体总会配对一份扁平化文本 fallbacka client that ignores the vendor variant still shows the contentinternal/acp/protocol.go。已安装插件声明的扩展 action 以/plugin:action出现在available_commands_update中可像普通斜杠命令一样调用。十、可选的 MCP 用户交互扩展支持 MCP elicitation 的宿主在initialize.clientCapabilities中显式声明{_meta:{reasonix.io:{mcpInteraction:{supported:true,schemaVersion:1}}}}Reasonix 在agentCapabilities._meta.reasonix.io.mcpInteraction返回对应能力含方法_reasonix.io/mcp/request_interaction。协商成功的会话使用 interactive MCP host profile未声明或版本不匹配的客户端继续使用 core profile不接收新增反向请求。新建、加载与重建会话均遵循这一协商结果。能力结构定义见 internal/acp/extension_capabilities.go协商逻辑在 internal/acp/service.go 附近的会话装配处生效。反向请求包含sessionId、promptId、turnId、server、mode、message表单模式还包含requestedSchemaURL 模式包含url和elicitationId。响应为{action:accept,content:{}}{action:decline}{action:cancel}宿主应按 schema 校验表单URL 流程交给用户操作不得把登录凭据作为表单内容返回。不支持的交互应取消。实现语义每次回答绑定原 controller 和 turn取消、无效回答及被拒绝的 URL 均取消交互只有accept才使用 contentcontroller 先持久化决定再释放 MCP 等待者。这一扩展不替代session/request_permission也不改变工具权限策略。协商出的 host profile 会影响 MCP capability/cache identitytranscript schema 不变。十一、兼容性与缓存行为表面旧版或非 Reasonix 客户端的行为结论现有 ACP v1 方法方法名和响应结构不变。兼容Capability_meta可以忽略未知 metadata。兼容持久化 transcripttranscript schema 不变Inbox 使用带版本的 sidecar。兼容CLI、Desktop、Bot steer被拒绝的 steer 会保留为持久化 follow-up。兼容前缀缓存稳定性是 Reasonix 的核心设计目标。Steer 只会把用户请求的消息追加到正常会话历史不改变 system prompt、工具 schema、工具顺序或其他稳定的 provider prefix 字节。下一次 provider 请求必然包含这条新消息和任何普通新用户消息一样会改变新增后缀但此前的稳定前缀仍可复用——这保证了长会话中 provider 侧的 prefix-cache 命中率不会因引导操作而受损。十二、客户端接入检查清单按以下顺序接入即可完成最小可用实现启动reasonix acp分离 stdin、stdout 和 stderrstdout 只承载 ACP 消息。调用initialize同时遵守标准 capability 和_metacapability包括宽容解析未知_meta条目。使用绝对工作区路径打开会话session/new的cwd必须是绝对路径否则SessionConfigState会返回 session cwd must be an absolute path 错误并隔离保存各 session id。Prompt 运行期间继续处理 agent 发往客户端的文件fs/*、terminalterminal/*和权限session/request_permission请求。只有在 Reasonix 声明 capability 且 prompt 活动时才显示 steer UI。按 steerdisposition分支两种结果都已持久化但只有steer_accepted能影响活动回合。用session/close释放资源只有用户明确要删除持久化历史时才调用session/delete。总结Reasonix 的 ACP 实现是一套标准协议 厂商扩展 严格缓存纪律的组合8 个标准会话方法覆盖完整生命周期session/set_config_option以独立控制轴替代了单一 mode selector_meta[reasonix.io]命名空间下的 steer、Inbox、运行时重载、extensionSurface 与 MCP 交互扩展全部遵循先发现、后调用、可回退的原则且任何引导或重载操作都不会破坏稳定的 provider prefix。编辑器接入方只需遵守清单中的七步即可获得与 CLI、Desktop、Bot 一致的会话体验与持久化保证。进一步可研读 internal/acp/server.go、internal/acp/dispatch.go事件流到session/update的映射与 internal/acp/inbox.goInbox 排空的完整实现。【免费下载链接】DeepSeek-ReasonixDeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.项目地址: https://gitcode.com/GitHub_Trending/de/DeepSeek-Reasonix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考