DotCraft ACP 模式指南

Agent Client Protocol（ACP） 是一个开放协议，专门用于标准化编码代理与编辑器/IDE 之间的通信方式——与 LSP（Language Server Protocol）解决编辑器与语言服务器耦合问题的思路如出一辙，但作用对象是 AI 代理。任何实现了 ACP 的编辑器都可以接入任意 ACP 兼容代理。DotCraft 原生支持 ACP，这意味着它可以作为编辑器内的一等公民编码助手运行，无需云订阅、无需专有插件、无需任何厂商特定的配置。

从编辑器角度来看，通信方式仍基于 stdio（标准输入/输出）与 JSON-RPC 2.0：编辑器将 DotCraft 作为子进程启动，通过标准流双向交换消息。在内部，DotCraft ACP 进程充当协议桥接层，将编辑器（ACP 协议）与 AppServer 实例（Wire Protocol）连接起来。所有会话状态、Agent 执行和工具调用均由 AppServer 处理，并与 TUI、Desktop、外部渠道等客户端共用同一套后端。桥接层会自动启动本地 AppServer 子进程，也可连接到你指定的远程 AppServer。

支持的编辑器

ACP 是开放标准，生态持续扩展。DotCraft 可运行于以下环境：

编辑器	插件 / 集成方式
JetBrains Rider（及其他 JetBrains IDE）	AI Assistant 内置 Agent 支持
Obsidian	obsidian-agent-client

任何其他支持 ACP 的编辑器或工具，均可使用相同的配置模式接入 DotCraft。

快速开始

1. 初始化 DotCraft 工作区

在接入编辑器之前，先在终端中进入项目目录并完成一次非交互式初始化。这一步会创建 .craft/ 文件夹，并生成默认配置文件和内置命令：

cd <你的项目目录>
dotcraft setup --language Chinese --model <model> --endpoint <endpoint> --api-key <key> --profile developer

DotCraft 初始化完成后，工作区即可供 ACP、TUI、Desktop 或自动化入口使用。模型配置等详细设置请参考配置指南。

2. 在编辑器中配置 ACP

在编辑器的 Agent 配置中，将命令设置为 dotcraft，并在参数中填入 -acp。DotCraft 以 -acp 标志启动时会自动激活 ACP 模式，无需修改任何配置文件。

工作目录应设置为第 1 步中完成初始化的项目根目录。

远程工作区（可选）

如果你已有正在运行的 DotCraft AppServer（例如通过 dotcraft app-server 或桌面应用启动），可以让 ACP 桥接层连接到该实例，而不是重新启动子进程：

dotcraft -acp --remote ws://<host>:<port>/ws

如果 AppServer 需要认证，可附加 --token <token>。连接远程 AppServer 后，通过编辑器创建的会话对所有已连接的客户端实时可见。

---

JetBrains Rider（及 JetBrains IDE）

安装了 AI Assistant 插件的 JetBrains IDE 可以直接添加 ACP 代理。打开 AIChat - Add Custom Agents，创建一条代理配置：

{
    "agent_servers": {
        "DotCraft": {
            "command": "dotcraft",
            "args": ["-acp"]
        }
    }
}

保存后，在 AI 聊天面板的代理选择器中选中 DotCraft 即可。IDE 负责进程的生命周期管理——打开会话时 DotCraft 自动启动，关闭时自动退出。

---

Obsidian

安装 obsidian-agent-client 插件（通过 BRAT 或手动安装），然后在插件设置中添加Custom agents：

字段	值
AgentID	DotCraft
Display name	DotCraft
Path	dotcraft.exe
Arguments	-acp

配置完成后，DotCraft 会显示在插件的聊天界面中。它既能回答问题，也能直接读写笔记——同一个代理，既是编码助手，也是知识库助理。

---

工作原理

编辑器以 ACP 模式启动 DotCraft 后，交互流程如下：

1. 初始化 — 编辑器与 ACP 桥接层交换协议版本和能力声明（initialize）；桥接层随后连接 AppServer（若未指定 --remote 则自动启动本地子进程），并将握手信息通过 Wire Protocol 转发给 AppServer。
2. 创建会话 — 编辑器发送创建会话请求（session/new）；桥接层将请求转发给 AppServer，由 AppServer 创建会话，再将响应（可用斜杠命令、配置选项等）中继回编辑器 UI。
3. 提示交互 — 编辑器发送用户消息（session/prompt）；AppServer 运行 Agent 并流式返回回复、工具调用状态和执行结果，桥接层将这些内容作为 session/update 通知转发给编辑器。
4. 权限请求 — 执行文件写入或 Shell 命令前，AppServer 通过 Wire Protocol 下发审批请求；桥接层将其转换为 requestPermission ACP 消息，由编辑器向用户展示审批/拒绝提示。
5. 文件与终端访问 — 当 AppServer 需要编辑器原生的文件或终端访问能力时，请求通过桥接层转发回编辑器（fs/readTextFile、fs/writeTextFile、terminal/*），所有操作均通过编辑器自身的 API 路由。

这意味着 DotCraft 能够读取编辑器缓冲区中尚未保存的内容、在应用变更前展示内联 diff、并在编辑器管理的终端中执行命令——这些能力超出了普通 CLI 代理所能提供的范畴。与此同时，所有 Agent 状态均由 AppServer 统一管理，会话持久存储并可在其他客户端中访问，即使编辑器关闭后依然保留。

支持的协议功能

功能	说明
initialize	协议版本协商和能力交换
session/new	创建新会话
session/load	加载已有会话并回放历史
session/list	列出所有 ACP 会话
session/prompt	发送提示并流式接收回复
session/update	DotCraft 向编辑器推送消息块和工具调用状态
session/cancel	取消正在进行的操作
requestPermission	DotCraft 就敏感操作向编辑器请求执行权限
fs/readTextFile	通过编辑器读取文件（含未保存内容）
fs/writeTextFile	通过编辑器写入文件（可预览 diff）
terminal/*	通过编辑器创建和管理终端
Slash Commands	.craft/commands/ 中的自定义命令自动广播到编辑器命令选择器
Config Options	将可选配置（模式、模型等）暴露到编辑器 UI

会话与工作区行为

ACP 作为完整的 AppServer 客户端工作。通过编辑器创建的会话会写入同一套会话存储：

• 会话 ID 格式：acp_{sessionId}（会话 ID 由编辑器分配后转发给 AppServer）
• 会话存储：存储于 <workspace>/.craft/sessions/，与 TUI、Desktop、Bot 等渠道的会话并列存放
• 共享记忆：memory/MEMORY.md 和 memory/HISTORY.md 在同一工作区的所有 Channel 之间共享——在 ACP 会话中获取的知识，在 TUI、Desktop 或 QQ 机器人会话中同样可以访问，反之亦然
• 多客户端并发：使用 --remote 时，多个客户端可同时连接同一个 AppServer。在 Obsidian 中开启的 ACP 会话，可以在桌面应用中实时查看或继续

使用示例

场景	推荐方式
本地 IDE 直接使用	配置编辑器启动 dotcraft acp
远程工作区	先启动 AppServer WebSocket，再在 ACP 参数中使用 --remote
与 Desktop 共享会话	连接同一个 workspace / AppServer
让编辑器负责文件和终端能力	使用支持 fs/* 和 terminal/* 的 ACP 客户端

故障排查

编辑器里没有出现 DotCraft

确认命令路径指向 dotcraft，参数为 ACP 模式，并且编辑器插件支持 Agent Client Protocol。

无法读取未保存文件

只有通过编辑器 ACP 客户端路由的文件访问才能看到未保存缓冲区。其他入口通常读取磁盘文件。

远程模式连接失败

确认 AppServer 使用 WebSocket 启动，URL 包含 /ws，并且 token 与服务端一致。