DotCraft

简体中文

English

简体中文

English

外观

IDE / 编辑器（ACP） ​

Agent Client Protocol（ACP） 是一个开放协议，专门用于标准化编码代理与编辑器/IDE 之间的通信方式——与 LSP 解决编辑器与语言服务器耦合问题的思路如出一辙，但作用对象是 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 支持
Obsidianobsidian-agent-client
Unity Editordotcraft-unity

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

快速开始 ​

1. 初始化 DotCraft 工作区 ​

在接入编辑器之前，先在终端进入项目目录完成一次非交互式初始化：

bash
cd <你的项目目录>
dotcraft setup

按提示填写 language / provider / model / api-key 即可。完整字段可见 配置完整参考；其余支持的 setup 参数可通过 dotcraft setup --help 查看。

DotCraft 初始化完成后，工作区即可供 ACP、TUI、Desktop 或自动化入口使用。

2. 在编辑器中配置 ACP ​

在编辑器的 Agent 配置中：

  • 命令：dotcraft
  • 参数：-acp
  • 工作目录：第 1 步中完成初始化的项目根目录

DotCraft 以 -acp 标志启动时会自动激活 ACP 模式，无需修改任何配置文件。

3. 远程工作区（可选） ​

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

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

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

JetBrains Rider（及其他 JetBrains IDE） ​

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

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

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

Obsidian ​

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

字段值
AgentIDDotCraft
Display nameDotCraft
Pathdotcraft.exe
Arguments-acp

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

Unity 编辑器 ​

Unity 编辑器客户端独立维护在另一个仓库：DotHarness/dotcraft-unity。

DotCraft 本体仍然是 Unity 客户端通过 ACP 启动的 agent harness。请先从本仓库安装并配置 DotCraft，然后在 Unity 项目中添加 dotcraft-unity：

text
https://github.com/DotHarness/dotcraft-unity.git

Unity 场景、选中对象、控制台和项目信息工具由 dotcraft-unity 在 ACP 初始化时声明为运行时 dynamic tools。_unity/* 是 Unity 客户端内部的 ACP 扩展方法，由客户端插件负责实现和维护。

工作原理 ​

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

  1. 初始化 — 编辑器与 ACP 桥接层交换协议版本和能力声明（initialize）；桥接层随后连接 AppServer（若未指定 --remote 则自动启动本地子进程），并将握手信息通过 Wire Protocol 转发给 AppServer。支持 DotCraft 扩展的客户端还可以在 _meta.dotcraft.runtimeTools 中声明由客户端实现的运行时工具。
  2. 创建会话 — 编辑器发送创建会话请求（session/new）；桥接层将请求转发给 AppServer，由 AppServer 创建会话，再将响应（可用斜杠命令、配置选项等）中继回编辑器 UI。客户端声明的运行时工具会作为 AppServer dynamicTools 绑定到当前会话连接。
  3. 提示交互 — 编辑器发送用户消息（session/prompt）；AppServer 运行 Agent 并流式返回可见回复、思考内容、工具调用状态和执行结果，桥接层将可见回复作为 agent_message_chunk、思考内容作为 agent_thought_chunk，并通过 session/update 通知转发给编辑器。
  4. 配置切换 — DotCraft 通过 ACP configOptions 暴露模式和模型选择器。支持该能力的客户端调用 session/set_config_option 切换模型，桥接层会同步更新当前线程和工作区默认模型。
  5. 权限请求 — 执行文件写入或 Shell 命令前，AppServer 通过 Wire Protocol 下发审批请求；桥接层将其转换为 requestPermission ACP 消息，由编辑器向用户展示审批/拒绝提示。
  6. 文件与终端访问 — 当 AppServer 需要编辑器原生的文件或终端访问能力时，请求通过桥接层转发回编辑器（fs/readTextFile、fs/writeTextFile、terminal/*），所有操作均通过编辑器自身的 API 路由。
  7. 客户端运行时工具 — Unity 等客户端可以声明场景查询、选中对象读取、控制台日志读取等客户端拥有的工具。DotCraft 只负责校验和桥接工具描述符，具体实现仍留在客户端插件内。

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

支持的协议功能 ​

功能说明
initialize协议版本协商和能力交换
session/new创建新会话
session/load加载已有会话并回放历史
session/list列出所有 ACP 会话
session/prompt发送提示并流式接收回复
session/updateDotCraft 向编辑器推送可见消息块、思考消息块和工具调用状态
session/set_config_option切换会话配置选项，例如模式和模型
session/cancel取消正在进行的操作
requestPermissionDotCraft 就敏感操作向编辑器请求执行权限
fs/readTextFile通过编辑器读取文件（含未保存内容）
fs/writeTextFile通过编辑器写入文件（可预览 diff）
terminal/*通过编辑器创建和管理终端
Runtime Dynamic Tools客户端通过 _meta.dotcraft.runtimeTools 声明线程级工具，桥接层通过 AppServer item/tool/call 调回客户端
Slash Commands.craft/commands/ 中的自定义命令自动广播到编辑器命令选择器
Config Options将可选配置（模式、模型等）暴露到编辑器 UI，模型选择器使用 ACP category: "model"

会话与工作区行为 ​

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 与服务端一致。

相关入口 ​

Apache License 2.0

Copyright © DotHarness