Skip to content

feat: /acp-cache command for all clients with a command seam (#1146) - #1156

Merged
ranxianglei merged 1 commit into
masterfrom
2026-09-22_acp-cache-all-clients
Sep 23, 2026
Merged

ranxianglei merged 1 commit into
masterfrom
2026-09-22_acp-cache-all-clients

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Registers the human /acp-cache entry point (prompt-cache reconciliation report — identical output to the acp_cache tool, added in #800) on every client that has a user-typable command surface, in both native mode and bili launcher mode.

Per-client coverage

Client Before After
pi / omp /acp-cache [full] (shared factory, both modes) unchanged
opencode V1 (launcher + native) no such command /acp-cache [full] via createAcpCommandHooks; report rendered as an ignored message wrapped in [acp-cache]/[/acp-cache], which the proxy strips from model context by content signature before it reaches the wire
opencode V2 (launcher + native) no such command /acp-cache [full] via ctx.command.transform; synthetic message — inert model-facing body, report in the visible description (8 KB cap)
dsh (launcher-injected + native profile) no such command session-bound acp_cache forward (initiator session id, latest-conversation fallback); default detail only
legacy opencode-acp sessions (#920) raw 404-style failure explicit "unavailable for legacy DCP session" notice
Claude Code no seam bili plugin install claude now also writes <configdir>/commands/acp-cache.md — a model-mediated markdown command whose prompt drives the acp_cache MCP tool and pastes the report back verbatim
codex / kimi / hermes no seam none exists (verified: no custom slash-command mechanism in these hosts) — documented; acp_cache remains reachable model-side through the bili MCP server

Behavior changes (old → new)

  • New registrations: opencode V1/V2 and both dsh lanes gain /acp-cache. No existing command's behavior changed anywhere.
  • opencode V1: the report message is wrapped in [acp-cache]…[/acp-cache] markers. This reuses the 给出缓存精确对账,增加新的命令/acp-开头 #800 strip contract — the proxy removes whole messages matching that signature from model context, so the model never sees the report (same as pi's bili-acp-cache sendMessage). Error texts are deliberately not wrapped (they stay visible to the model like /acp errors do).
  • opencode V2: cache-report visible cap is 8192 chars vs the 1024-char panel cap (V2_SYNTHETIC_VISIBLE_MAX). Deliberate deviation: the report's tail (per-line deltas) is the payload, unlike the status panel where the head matters.
  • dsh: no full flag — the dsh command API passes no arguments to handlers, so only the default summary ledger is available (documented in CONFIGURATION.md/zh-CN and the command description).
  • Legacy opencode sessions (opencode v1: keep opencode-acp legacy sessions working after switching to bili #920): /acp-cache used to fall through to the raw forward and surface a confusing unknown-conversation error; now an explicit notice explains why (traffic bypasses this proxy's compression state) and suggests a new session.
  • bili plugin install claude: new side effect — writes <configdir>/commands/acp-cache.md (CLAUDE_CONFIG_DIR-aware). Install never clobbers a foreign file (content-ownership check, same precedent as the codex config block); removal deletes only an exact-template match. Uninstall notes when a foreign file was left untouched.
  • dsh error paths (new code only): the version probe in the new cacheOutcome handlers catches network throws and renders the friendly "proxy not reachable" message instead of rejecting with TypeError: fetch failed. Pre-existing /acp paths are untouched.

Out of scope / documented instead

codex, kimi, and hermes expose no user-typable custom-command mechanism (checked their extension surfaces: hooks/MCP/tools only). Forcing a seam there would mean product changes in those hosts — out of scope. Their users can ask the model to call the acp_cache tool directly (already exposed via the bili MCP server). Documented in README + CONFIGURATION.md (+ zh-CN).

Pre-flight (on rebased head, base e28fdfa)

  • npm run typecheck — pass
  • npm test — 2271 tests, 2269 pass, 0 fail, 2 skipped (default-gated E2E)
  • npm run build (tsup) — success

New regression coverage: tests/opencode-acp-command.test.ts (V1 unit suite, 7 cases incl. full-flag matrix and strip-wrapping assertion), opencode-v2 (registration/render/truncation/disabled/no-proxy), dsh-acp (5 cache cases), dsh-native (session-bound forward, latest fallback, unreachable), opencode-native-v1 (legacy notice, no acp fall-through), claude-native (installer ownership round-trip ×3).

Fixes #1146

@github-actions

github-actions Bot commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-09-22_acp-cache-all-clients (def6d9e)

Option A — Install from npm PR tag (recommended)

npm install -g billion-context@pr-1156

Each push to this PR publishes a new version under the pr-1156 npm tag.

Option B — Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr1156.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 收到。这是已完成的工作分支(2026-09-22_acp-cache-all-clients @ dbbe51d,base e28fdfa),我不重做——正在做合并前核验:拉取分支、核对 diff、跑 typecheck/test/build、查 CI 状态。结论稍后贴在本线程。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Review 完成 —— 结论:验证通过,无回归,可合并(按规则我不执行合并,请你合并)。

一句话摘要:给 opencode V1/V2、dsh 双 lane、claude(模型中介 markdown 命令)补上 /acp-cache 人类入口,纯复用既有 #800 strip 契约与 forwardTool 机制,零服务端代码改动;diff 干净、CI 8/8 绿,未发现回归。

查重

分支与 CI

  • head dbbe51d,base e28fdfa = 当前 master tip(0 behind,无需 rebase),mergeable_state=clean,单一线性 commit。
  • CI 在该 SHA 上 8/8 success:全测试矩阵 ubuntu/windows × node 22/24(2271 tests)、zero-token codex e2e(真实 codex vs deterministic fake upstream)、build-artifact、version-guard、codex CODEX_HOME overlay job。
  • diff 未触碰请求管线热点(src/server.ts / src/loop/ / adapters / preflight),故无需额外跑 ACP_TEST_E2E 全相位。

回归审查(diff 触碰路径的既有行为 → 逐项结论)

触碰路径 既有行为 结论
src/agent/opencode-acp-command.ts(V1+V2 共享 hooks) /acp 注册/渲染/status 拉取/no-proxy 消息 保持 —— /acp 分支逻辑逐字节不变;仅新增第二个命令入口,acp 的 no-proxy 文案原样保留
src/agent/opencode-native.ts V1 dispatch legacy 会话(/acp,/dcp)路由到 opencode-acp 保持 —— legacy early-return 只匹配 acp/dcp;新分支仅拦截 acp-cache && isLegacy,位于其后,顺序正确
src/agent/dsh-acp.ts / dsh-native.ts 两 lane 的 /acp statusOutcome 保持 —— 纯新增(cacheOutcome + 第二个 commands.register),既有 handler 零改动;新 handler 复用 maybeRetry/sessionIdOf/fetchStatusLatest,与相邻 statusOutcome 同模式(已在 PR head 逐行核对)
src/agent/opencode-v2.ts /acp editor.add、工具注册、1024 panel cap 保持 —— 新 editor.add("acp-cache") 在同一守卫块内;model-facing body 维持 inert V2_SYNTHETIC_TEXT(无需 proxy 侧 strip);报告走 description、8192 cap
src/plugin-install.ts claude lane managed settings block + MCP 注册/移除 保持 —— 命令文件步骤为纯增量;remove best-effort 永不 throw;install 对非 bili 内容文件绝不覆盖(codex block 同款所有权先例)
Wire 层 消息形状/注入协议 无变更 —— 服务端零改动;V1 报告用 wrapCacheReport 包裹,依赖的 #800 契约我已在 master 代码核实:isCacheReport(首尾签名匹配)+ stripAcpPanelMessages/stripAcpPanelResponsesInput 每请求应用于 src/server.ts:2247/2414/2814 及 fork-adoption.ts:80

行为变化(old→new,均已在 PR body 披露,本次逐项复核属实)

  1. 新增 /acp-cache 注册:opencode V1/V2 × launcher/native、dsh × launcher/profile、claude install 副作用。所有既有命令行为零变化。
  2. opencode V1:报告消息带 [acp-cache]…[/acp-cache] 包裹,由 proxy 在上线前按内容签名剥离(model 不可见);错误文案故意不包裹(model 可见,与 /acp 错误一致)。已知边界:用户消息若恰好以 [acp-cache] 开头且以 [/acp-cache] 结尾会被同样剥离——这是 给出缓存精确对账,增加新的命令/acp-开头 #800 既有契约的固有属性,非本 PR 引入。
  3. opencode V2:可见上限 8192(panel 仍 1024)——有意偏离,PR body 已说明理由(报告 payload 在尾部 LINE ITEMS)。
  4. dsh:无 full 参数(host command API 不传参)——CONFIGURATION.md 中英均已注明。
  5. legacy DCP 会话(opencode v1: keep opencode-acp legacy sessions working after switching to bili #920):/acp-cache 从 fall-through 原始报错 → 明确「unavailable for this legacy DCP session」提示——有意改进,已披露。
  6. bili plugin install claude:新增写 <configdir>/commands/acp-cache.md。新失败模式:若 commands 目录不可写,install 会在 settings+MCP 写入后 throw(报错信息指引修权限后重跑,幂等安全)——可接受,在此记录。

测试覆盖

6 个测试文件新增 +672 行:opencode-acp-command(V1 单测含 full-flag 矩阵与 strip-wrap 断言)、opencode-v2(注册/渲染/truncation/disabled/no-proxy)、dsh-acp(5 例)、dsh-native(session-bound forward/latest fallback/unreachable)、opencode-native-v1(legacy notice + no /acp fall-through)、claude-native(installer ownership round-trip ×3)。

判定

diff 干净(15 文件全部与本目标相关,无空白 churn、无 lockfile/version 漂移),单 commit,门禁在当前 master 上全绿,未审出无意回归。按 §7.4 属 feat 且触及 wire-adjacent 消息形态与 installer 副作用,必须人工合并。

PR: #1156 —— 等你合并。

Register the human entry point to the acp_cache prompt-cache reconciliation report on every client that has a user-typable command surface, in both native mode and bili launcher mode:

- pi/omp: already covered via the shared factory (/acp-cache [full])
- opencode V1 (launcher + native): /acp-cache [full] in createAcpCommandHooks; report rendered as an ignored message wrapped in [acp-cache] markers, which the proxy strips from model context by content signature before it reaches the wire
- opencode V2: /acp-cache [full] via ctx.command.transform; rendered as a synthetic message (inert body, report in the visible description, 8 KB cap vs the 1 KB panel cap because the report tail is payload)
- dsh (launcher-injected + native profile): session-bound acp_cache forward (initiator session id, latest-conversation fallback); default detail only - the dsh command API passes no arguments
- legacy opencode-acp sessions (#920): explicit unavailable notice instead of a raw 404 (their traffic bypasses this proxy's compression state)
- Claude Code: no in-process command API; bili plugin install claude now also writes <configdir>/commands/acp-cache.md (model-mediated markdown command driving the acp_cache MCP tool), content-owned install/remove never clobbers foreign files
- codex/kimi/hermes: no user-typable command seam exists - documented, acp_cache remains reachable model-side via the bili MCP server
@ranxianglei
ranxianglei force-pushed the 2026-09-22_acp-cache-all-clients branch from dbbe51d to def6d9e Compare September 23, 2026 11:29
@ranxianglei
ranxianglei merged commit 8f12986 into master Sep 23, 2026
16 checks passed
@ranxianglei
ranxianglei deleted the 2026-09-22_acp-cache-all-clients branch October 15, 2026 05:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

所有的客户端支持acp-cache命令,在native模式和bili启动器模式下

1 participant