ACP 协议
ACP（Agent Communication Protocol）Runtime 是 Mogick 的嵌入式运行模式。它通过标准输入/输出（stdio）建立 JSON-RPC 2.0 双向通信通道，让 IDE、桌面应用等宿主程序能够将 Mogick 作为 AI 引擎直接嵌入，无需启动终端全屏界面。这种方式使集成方可以完全掌控用户交互层，同时复用 Mogick 的全部 AI 能力。
启动 ACP Runtime：
| 启动方式 | 说明 |
|---|---|
mogick acp | 直接启动 ACP 模式，Mogick 接管当前进程的标准输入/输出，通过 stdio 建立 JSON-RPC 2.0 双向通信 |
mogick acp 是面向集成开发者的接口——IDE 插件或桌面应用通过 spawn 子进程的方式调用，双方通过 stdio 管道收发 JSON-RPC 2.0 消息。终端用户通常不会直接执行此命令。
与 TUI 模式的区别
TUI（终端全屏界面）与 ACP Runtime 服务于不同的使用场景。TUI 模式面向终端直接使用者，提供完整的交互式聊天体验；ACP Runtime 则面向集成开发者，将控制权完全交给宿主程序。理解两者的差异有助于选择合适的集成路径：
| 维度 | TUI | ACP Runtime |
|---|---|---|
| 界面 | 终端全屏 UI，Mogick 自主渲染 | 由宿主程序提供，Mogick 不负责呈现 |
| 通信 | 键盘输入 + 终端输出渲染 | stdio 上的 JSON-RPC 2.0 双向消息 |
| 会话管理 | 用户手动创建、切换、删除 | 宿主通过协议方法程序化控制 |
| 典型场景 | 终端中直接与 AI 对话 | IDE 插件、桌面应用集成、自动化流水线 |
简而言之：TUI 是给人用的完整终端应用，ACP 是给程序用的通信协议。
协议方法
ACP 协议的方法分为标准方法和扩展方法两类。标准方法遵循通用 Agent 协议规范，跨实现兼容；扩展方法使用 _mogick/ 前缀，提供 Mogick 特有的功能。标准客户端会自动忽略无法识别的扩展方法，无需额外适配。
标准方法
| 方法 | 说明 |
|---|---|
initialize | 协商协议版本与双方支持的能力集 |
session/new | 创建一个新的对话会话 |
session/load | 加载已有会话，恢复历史上下文 |
session/list | 列出当前持久化的会话摘要 |
session/prompt | 向模型发送用户提示并获取响应 |
session/cancel | 取消当前正在运行的生成任务 |
session/delete | 关闭会话并回收运行时资源；持久化历史保留 |
session/set_config_option | 在运行时动态更新会话级配置项 |
session/set_mode | 切换会话执行模式（Agent / Plan） |
session/set_model | 切换会话使用的模型 |
session/commands/refresh | 刷新宿主可用的命令列表 |
authenticate | 宿主向 Mogick 注入认证凭据（API Key 等） |
扩展方法
扩展方法覆盖 Mogick 特有的检查点管理、会话生命周期和多 Provider 配置等高级能力。此外，CRP（Copilot Runtime Protocol）是 Mogick 内部运行时协议。26.9.11 的 sessions export 不提供 CRP trace 导出参数；不要将会话历史导出当作协议追踪。
| 前缀 | 涵盖功能 |
|---|---|
_mogick/session_checkpoint_* | 检查点的创建、列表、恢复与删除 |
_mogick/session_{close,reopen,archive,unarchive,delete,fork} | 会话生命周期；其中 session_delete 是物理删除 |
_mogick/model_provider/* | 多 Provider 模型配置与切换 |
_mogick/session_{attach,detach,lock_info,request_write,force_write,release_write} | 多客户端附加与单写者锁 |
_mogick/session_mcp_update | 会话内 MCP 配置热更新 |
_mogick/workspace_update、_mogick/session_system_event、_mogick/session_plan_action | 宿主工作区与会话状态同步 |
_mogick/skills_state_update | Skills 状态同步 |
_mogick/session/updateMetadata | 会话元数据更新 |
_mogick/changeset_traces、_mogick/changeset_patchsets、_mogick/execution_summary | Changeset 与执行证据查询 |
宿主能力注入
ACP 协议允许宿主声明自己在某些能力上替代 Mogick 内置实现，从而提供更深度集成的体验。宿主在 initialize 阶段声明能力后，Mogick 会将相关请求回传给宿主处理：
| 能力 | 行为 |
|---|---|
| FS | 文件系统操作（读、写、列表、删除）全部走宿主实现，而非 Mogick 自身的文件工具 |
| Terminal | Shell 命令优先提交给宿主终端执行；若宿主不支持，则回退到 Mogick 本地 Shell |
| exitPlanApproval | 当 Plan 模式中的 plan.write 完成并结束当前轮次时，宿主展示计划审批卡片，而非依赖模型调用退出工具 |
能力注入的核心价值在于：IDE 可以在自身沙箱内执行文件操作，桌面应用可以统一管理终端权限，避免了 Mogick 绕过宿主直接访问系统资源的安全隐患。
多客户端附加
同一个 Mogick ACP 进程内支持多个客户端附加同一会话，写槽由单写者锁保护。该进程内能力通过 initialize 返回的 agentCapabilities._meta.mogick.multiAttach 探测，不需要环境变量。
多客户端环境的设计要点：
| 特性 | 说明 |
|---|---|
| 单写者锁 | 同一时间仅允许一个客户端发送 session/prompt，防止并发写入导致状态错乱 |
| 锁自动释放 | 当持有写锁的客户端意外断线时，经过 30 秒宽限期后自动释放锁，允许其他客户端接管 |
| 状态同步 | 所有客户端通过单调递增的事件修订号跟踪会话状态变更，确保视图一致 |
| 权限弹窗 | 后台会话的权限请求自动挂起；当用户将对应客户端切回前台时重新投递审批 |
如果客户端先调用标准 session/load，再调用 _mogick/session_attach 认领写槽，应把 load 响应的 _meta.mogick.historyReplayCursor 原样传入 attach 的 replayAfterEntryId。这样只回放该 entry 之后的内容，避免同一段助手回复被重复水合。
ACP 宿主注入的 Mogick 控制面元数据不会传给真实工具执行器；集成方不应依赖真实工具接收这些内部字段。