在 IDE 中使用（ACP）

ThinCoder 支持 Agent Client Protocol（ACP v1）：thincoder acp 由 IDE 作为子进程拉起， 通过 stdin/stdout 以 JSON-RPC（NDJSON）通信。

流式回复与思考、工具审批对话框、编辑器内 diff、持久化会话——一并在场。

上手三步：① 在终端跑通一次 thincoder（完成凭据设置）； ② 按下面任一宿主的配置把 thincoder acp 接上； ③ 在宿主的 Agent 面板开新对话开始用。

本页内容更新于 2026-10-04。

前置条件

• Node.js ≥ 24，且 thincoder 在 PATH 上； 或直接使用绝对路径（IDE 的 GUI 进程常常不继承终端的 PATH——Windows 用 where thincoder、POSIX 用 which thincoder 查）。
• 凭据就位即可开始：~/.thincoder/config.json 里已有可用的提供商 API Key（providers[].apiKey）， 或在终端跑过一次 thincoder 完成设置。
• ACP 以凭据为准即时判断——凭据已在，会话直接可用； authenticate 只是可选的确认动作（客户端支持终端登录引导时会用到，见「登录与凭据」）。
• 两句自检：node -v 应 ≥ 24；thincoder -v 应打印版本——两者都有输出，接入的先决条件就齐了。 （Node 版本过低是「拉起即退出」最常见的原因——先自检。）

能力一览

当前为 M1 能力面——按「你会看到什么」列出：

以上能力随宿主客户端的不同自动适配——宿主能力位不满足时，按「降级并让它可见」的原则处理（见各节说明）。

快速接入 · Zed

在 ~/.config/zed/settings.json 中加入：

{ "agent_servers": { "ThinCoder": { "type": "custom", "command": "thincoder", "args": ["acp"], "env": {} } }
}

若 thincoder 不在 GUI 的 PATH 上，command 用绝对路径 （Windows 用 where thincoder、POSIX 用 which thincoder 查）。

生效点：在 Zed 的 Agent 面板里新开一次对话——它会按上面的配置拉起 ThinCoder 的 ACP 子进程。

同一份配置对同一台机器上的所有 Zed 窗口生效；接入后先问一句「你好」即可验证链路。

Zed 里同时配置了多个 agent 时，会话面板会分别列出——选 ThinCoder 的那个。

快速接入 · JetBrains

JetBrains（IntelliJ IDEA / PyCharm / WebStorm …）通过 AI Chat 插件支持 ACP。

没有 JetBrains AI 订阅时：在 Registry（连按两次 Shift → "Registry"）里开启 llm.enable.mock.response， 即可在纯 ACP 场景下使用 AI Chat 面板。

在 AI Chat 面板菜单里选 Configure ACP agents，加入：

{ "agent_servers": { "ThinCoder": { "command": "C:\\path\\to\\thincoder.exe", "args": ["acp"], "env": {} } }
}

JetBrains 要求 command 用绝对路径。

保存后 ThinCoder 会出现在 AI Chat 的 agent 选择器里—— 在 AI Chat 里把 agent 选为 ThinCoder 再发问即可。

该配置按 IDE 生效；装有多个 JetBrains IDE 时，在每个 IDE 里各配一次。

快速接入 · Paseo

在 ~/.paseo/config.json 里把 ThinCoder 选为自定义 ACP provider：

{ "agents": { "providers": { "thincoder": { "extends": "acp", "label": "ThinCoder", "command": ["thincoder", "acp"] } } }
}

Paseo 的通用 ACP 适配器不驱动登录流程——先在终端完成设置（见「前置条件」），再回到 Paseo 使用。

配置生效后，Paseo 下的新会话会通过 thincoder acp 运行；provider 列表里显示为「ThinCoder」。

若 Paseo 跑在另一台机器上，那台机器也需要完成一次设置（凭据与 thincoder 都在本地）。

登录与凭据

• 凭据存放在 ~/.thincoder/config.json（提供商 API Key）。 已配置时，IDE 里的会话直接使用现成凭据，无需额外登录动作。
• 需要新登录或更换凭据时，可在终端运行 thincoder acp --login 走登录流程 （客户端支持终端登录引导时会代为引导）；也可以直接编辑配置文件。
• --login 之后凭据落入 config.json——后续所有面（IDE、VS Code、桌面、终端）共用同一份凭据。
• 非交互环境（CI、脚本）没有终端可引导：预置 config.json 即可； 没有可用凭据时会快速失败并给出提示，不会挂住。
• 安全提示：凭据只保存在本机 ~/.thincoder/config.json；不要把它提交进任何仓库或分享给他人。
• 换机器时：把 config.json 里的凭据重新配置一遍——没有云端同步。

会话管理

会话按项目目录存档——与终端里的会话同一族（同一个项目目录、同一个槽位体系）。

ThinCoder 启动在哪个目录，会话就归属哪个项目；在 IDE 里换一个项目目录，看不到另一个项目的历史，这是预期行为。

IDE 里对会话的四类操作（协议名 session/list / load / resume / delete）：

• 列出：会话列表给出该项目目录下的历史会话，按最近更新排序—— 打开 IDE 的会话面板即可看到，无需先「导入」什么。
• 加载：打开一个历史会话会重放此前的对话过程（历史事件逐条再现）—— 适合先看看上次聊到哪，再决定继续。
• 恢复：接续此前的上下文继续聊，但不重放显示—— 适合你已清楚上下文、只想把活接着干。
• 删除：删除选中会话及其存档——删除后列表不再出现。
• 占用处理：若该会话正被终端占用，ThinCoder 会另开一个槽位—— 两边各自有存档，不会双写同一份。

列表里每条会话都带最近更新时间——排序与显示以它为准。

与终端的关系：两边共用同一套会话存档——在终端开的会话，IDE 里也能看到并接续（同一项目目录即可）。

例：你在 ~/proj 用终端聊过三轮，打开 Zed（同一目录）—— 会话面板里能看到这三轮，点开重放、或直接恢复继续。

两个不同项目想共用同一个会话：不支持——会话以项目目录为锚，这是设计上的取向。

配置选项

会话内可调整三类选项（客户端以选项控件呈现，切换当场生效）：

• 模型——在当前提供商下切换模型。不同模型能力与成本不同，按任务轻重现场选。
• 思考——开启 / 关闭扩展思考（视模型能力而定）。难题开、快改关，是常见的用法。
• 模式——plan ⇄ normal：计划模式先给出方案（不动手），普通模式直接执行。

这些选项只对本会话生效，不会写回 config.json—— 所以换一个会话，看到的又是配置文件里的默认值。

三项之外，提供商 / Key 的更换在配置文件层完成，不在会话内提供。

如果你希望某个选择成为长期默认：改配置文件里的对应项，

这样所有面（终端、IDE、桌面）的新会话都会用新默认；各项默认值怎么配见 配置页。

@文件引用

在支持该能力的宿主里（如 Zed），输入 @ 选择文件—— 被引用文件的内容（或选区）随对话一并发给 ThinCoder，无需手动贴代码。

• 怎么用：在对话输入框敲 @，从补全里挑文件； 选中了代码就用选区引用——只把选中的部分带进对话。
• 进入上下文：被引用的内容作为该条消息的一部分进入对话——参与后续上下文，占用与普通对话相同。
• 范围：引用补全的范围随 IDE 的工作区——工作区里没有的文件，见「故障排查」一条。
• 上限：单个引用至多 10MB、2000 行、100k 字符。
• 降级可见：超出上限或读取失败时不会静默——对话里会出现降级标记 （形如 [File reference: … — <原因>]），说明这次引用以什么形式生效 （例如截断，或只给了路径而没有内容）。
• 建议：大文件优先用选区引用；看到降级标记时，按标记里的原因缩小引用面再试。

子代理活动

ThinCoder 工作时可能派出子代理（查资料、跑专项任务），与主线并行。

支持该扩展的客户端会收到子代理的结构化更新——事件里带角色、状态与进度 （协议名 session_info_update，细节在 _meta 的 thincoder.dev/subagent 键下）—— 你可以像看主线一样看到它们在忙什么；子代理结束后，状态会更新为完成。

这些事件不影响主线对话的节奏——你随时可以继续在主线里发消息。

不支持该扩展的客户端忽略这些更新即可——不影响任何功能，主线的回复与结果照常。

故障排查

• 会话断开 / "agent exited"
  原因：command 路径不对，或未完成设置。
  修法：在终端直接跑 thincoder acp——健康时它会阻塞等待 stdin；若立刻报错，错误信息就是线索（通常是 "authenticate → authRequired"）。
• "auth required"
  原因：~/.thincoder/config.json 里没有可解析的提供商 Key。
  修法：运行 thincoder acp --login，或在终端跑一次 thincoder 完成设置，然后重启 IDE。
• 编辑器缓冲陈旧
  原因：edit 在应用前会先读回 IDE 缓冲（未保存的改动会被尊重）； 若文件在磁盘上已被改而编辑器未重载，可能出现陈旧缓冲不匹配。
  修法：先重载文件再让 Agent 操作。
• 没有权限弹窗
  原因：ACP 会话默认不开 AUTO 模式；session/request_permission 失败（传输错误）时一律拒绝工具调用（安全优先）。
  修法：属预期行为；需要更少打断时在会话内切换模式，而不要期待外来放行。
• 编辑没有走 IDE diff
  原因：该客户端未宣告文件系统能力，ThinCoder 回落到本地写盘（预期行为，改动照常落盘）。
  修法：无需处理；需要 diff 体验时换用宣告了文件系统能力的客户端。
• 会话列表看不到历史
  原因：会话按项目目录存档。
  修法：确认 IDE 打开的项目目录与当初使用的目录一致（同一目录才在同一族槽位里）。
• @引用没有进上下文 / 看到 [File reference: …] 标记
  原因：超出引用上限（10MB / 2000 行 / 100k 字符）或读取失败——按设计以降级形式生效、不静默。
  修法：改用选区引用，或先精简文件。
• @ 补全里找不到目标文件
  原因：引用补全的范围随 IDE 的工作区。
  修法：把文件放进工作区，或直接告诉 Agent 文件路径让它自行读取。
• 创建会话即失败（无终端可引导）
  原因：非交互环境没有 TTY，登录引导无法进行。
  修法：预置 config.json（含可用 Key）后重试——有凭据就不会走到引导。
• 换了 Key 之后仍旧报错
  原因：旧进程仍在跑（拿的是旧凭据）。
  修法：更新 config.json 或跑 thincoder acp --login 后，重启 IDE 让宿主重新拉起。
• 对话停住不再更新
  原因：正在等待审批弹窗，或网络中断后连接已断。
  修法：检查宿主的审批提示；确认无待批后取消本回合重发。
• 终端里正常、IDE 里报「authenticate 失败」
  原因：IDE 的子进程环境与终端不同（如 PATH，或读不到 ~/.thincoder/config.json）。
  修法：command 用绝对路径，并确认 IDE 进程的用户环境能访问到那份配置文件。
• 会话内切的模型/模式，新会话又变回去了
  原因：会话内配置不写回配置文件（预期行为）。
  修法：想要长期默认就改 config.json 里的对应项，新会话会以它为准。

限制与路线图

• 终端命令类工具（reverse-RPC）暂不由 IDE 承接——shell 在本地执行； 需要交互式终端操作时，请用终端里的 ThinCoder。
• MCP 转发在 M2 规划中——需要 MCP 工具时，先用终端或 VS Code / 桌面版。
• 澄清提问目前不弹独立对话框——追问会出现在对话正文里，注意别漏读。
• 工具输出不支持流式增量——工具卡在结束时呈现最终结果；长任务请以完成后的卡片为准。
• unstable 协议扩展不在支持面——依赖它们的客户端能力不承诺。
• 路线图随版本推进——以本页与 更新日志 为准。

日志

stdout 上只走协议 JSON；所有诊断信息都在 stderr。

用 thincoder acp 2> acp.log 捕获它们；反馈问题时附上这段日志与你的客户端名称，定位会快很多。

更多细节见 文档页 与 ACP 协议官网。