[Feature]: Add doctor or instructions on how to check complete and correct operation #319

Activity

1. HaleTom

   added

   enhancementNew feature or requestNew feature or request

   on Aug 17, 2026
2. ranxianglei commented on Aug 17, 2026

   

   ranxianglei

   on Aug 17, 2026

   Owner

   More actions

   感谢建议。

   TL;DR: On the roadmap — designing a cross-project `doctor` self-check; not being worked on yet (parked as design tracking).

   这个功能会统筹整个 ACP 项目群设计，不单作为 opencode-acp 的一个 feature：

   涉及项目

   • `opencode-acp`（本仓库，opencode host）
   • `billion-context-pi`（pi host）
   • `billion-context`（opencode proxy/launcher host）
   • `acp-kernel`（共享内核）——通用检查项应下沉到内核实现，各 host 只负责自己的"入口表面"（opencode 的 /acp doctor、pi 侧对应命令等），避免三套漂移

   要覆盖的故障模式（按诊断顺序）

   1. 插件未被 host 加载 → 命令完全无响应（最大死角：doctor 自己也不响应时，文档必须写明"无响应=第 1 类故障，查 X"）
   2. ACP server 进程未启动 / 崩溃
   3. 插件 ↔ server 版本不匹配
   4. 配置非法 / 未知键静默回退默认值
   5. 子命令被权限门静默吞掉（本仓库 release: v1.14.21 — /acp command fixes and completion (permission gate, export, help) #317 已修 compress 权限门吞命令的实例，doctor 需专门探测此类"静默失败"）
   6. "以为在工作其实没压缩"——上下文悄悄涨到上限（需暴露：block 数、最近一次成功压缩时间、modelContextLimit 是否解析成功）

   候选方案

   • A. In-band `/acp doctor` 子命令（推荐主入口：版本对齐 / 配置合法性 / server 存活+ping / 日志可写+最近 ERROR / session 压缩状态，输出 ✓/✗ 清单+修复建议）
   • B. Out-of-band CLI（覆盖"插件没加载所以 doctor 跑不了"的死角；第二个维护入口，暂缓）
   • C. README"手动验证三步"章节（零代码，作为 A 的死角兜底，必做）
   • 推荐组合：A + C，B 视后续用户反馈

   状态：暂不处理。本 issue 作为设计跟踪入口；动手前需先在 acp-kernel 侧确定哪些检查逻辑可下沉复用（另开内核 issue 跟进）。