@zaimokuza/dsh-acp-adapter 0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zaimokuza
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# @zaimokuza/dsh-acp-adapter
+
+将外部 [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) Agent 接入
+[DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) 的插件。DSH
+继续负责会话、工作区、审批和宿主审计；ACP Agent 负责自己的推理、工具和运行时状态。
+
+当前包为发布候选版本，已针对 DSH `0.1.1-rc.2` 在 macOS 上验证。Windows、远程 ACP
+transport、同一会话跨 backend 迁移和 DSH tools/skills/MCP 注入不在已验证范围内。
+
+## 安装
+
+先安装并启动 DSH `0.1.1-rc.2`，然后在目标 profile 中安装插件：
+
+```bash
+dsh plugin --profile web add @zaimokuza/dsh-acp-adapter
+dsh web
+```
+
+本地 tarball 验证时，从本仓库执行 `pnpm pack`，再把生成的 `.tgz` 的绝对路径传给
+`dsh plugin --profile web add`。发布前请用干净 profile 验证安装和卸载；不要把本机
+认证文件复制到插件目录或日志中。
+
+最低宿主版本是 `0.1.1-rc.2`。peer 依赖接受该版本及更高版本，但结构兼容门和本项目
+实际验收仍以 rc.2 为准；不支持 rc.8。Node.js 支持范围与 DSH `0.1.1-rc.2` 一致：
+`^22.19.0 || >=24.0.0`；本仓库门禁使用 Node 24.19.0 与 pnpm 11.7.0。
+
+## 第一步
+
+1. 按 [入门指南](docs/getting-started.md) 检查 DSH 与插件状态。
+2. 先在 Agent 自己的 CLI 中完成登录和健康检查，再在 DSH ACP 设置中选择内置模板。
+3. 创建一个 ACP 会话，确认 health 状态为 `ready` 后再发送 prompt。
+4. 在 [Agent 指南索引](docs/agents/README.md) 中查阅命令、模型/mode 和数据目录说明。
+
+登录始终由 Agent 自己管理。插件只使用命令、环境变量名和 opaque 路径引用，不读取、
+复制或记录 token、cookie、配置中的 secret value。
+
+## 能力与安全边界
+
+- DSH 会话的 execution backend 在创建后不变；跨 native/ACP 必须新建会话。
+- ACP 模型、mode 和思考强度只在 Agent 真实暴露相应 config option 时显示。
+- `allowed-once` 审批保持一次性语义，绝不会映射为 `allow_always`。
+- 会话恢复先做 staging reconciliation；无法证明连续性就 fail closed，不静默新建
+  ACP 会话接续旧 DSH 历史。
+- sidecar 保存 ACP binding、恢复和审批审计；DSH session log 仍是用户可见历史真源。
+- 外部 Agent 的 tools、skills、MCP、system prompt、原生 token 统计和重试策略不会
+  自动变成 DSH 原生能力。
+
+详细边界见 [架构说明](docs/architecture.md)、[兼容性](docs/compatibility.md) 和
+[安全说明](SECURITY.md)。
+
+## 文档
+
+- [入门与安装](docs/getting-started.md)
+- [Agent 指南索引](docs/agents/README.md)：[Devin](docs/agents/devin.md) · [Codex](docs/agents/codex.md) · [Kimi](docs/agents/kimi.md) · [Claude](docs/agents/claude.md)
+- [操作与验收](docs/operations.md)
+- [架构与生命周期](docs/architecture.md)
+- [兼容性与已知限制](docs/compatibility.md)
+- [故障排查](docs/troubleshooting.md)
+- [安全策略](SECURITY.md)
+
+## 本地开发
+
+合同测试需要 DSH `0.1.1-rc.2` 的只读源码基线；该目录已被 Git 忽略：
+
+```bash
+git clone --depth 1 --branch dsh-v0.1.1-rc.2 \
+  https://github.com/deepseek-ai/deepseek-harness.git reference/deepseek-harness
+export DSH_UPSTREAM_CHECKOUT="$PWD/reference/deepseek-harness"
+```
+
+然后串行运行：
+
+```bash
+pnpm install --frozen-lockfile
+pnpm typecheck
+pnpm test
+pnpm build
+pnpm pack --dry-run
+```
+
+测试和构建必须串行执行，因为它们共享 `lib/` 与 `.typert/`。发布前还应运行
+`pnpm check:stale-build`、`pnpm check:picker-diff` 和不带真实凭证的 install gate。
+
+## 许可证
+
+MIT，见 [LICENSE](LICENSE)。

package/SECURITY.md

@@ -0,0 +1,12 @@
+# 安全策略
+
+本插件采用 external-login-only：认证由 Devin、Codex、Kimi 或 Claude 自己的 CLI 管理。
+插件不会读取、复制、解析或回传 token、cookie、私钥、credential 文件内容；日志和
+sidecar 只保存 opaque 路径引用、键名、哈希或脱敏摘要。
+
+请不要在 issue、日志或测试夹具中提交凭证、完整环境变量、私有工作区内容或未脱敏的
+ACP payload。若发现疑似泄漏，请不要公开创建 issue，发送最小化复现、受影响版本和
+文件路径到仓库维护者，并在可能时先撤销/轮换凭证。报告中只保留类别和脱敏片段。
+
+安全边界包括 host structure gate、进程终止梯子、审批语义保持、staging reconciliation
+和模型切换 CAS；外部 Agent 自身的工具策略不等于 DSH sandbox 保证。

package/cordis.patch.yml

@@ -0,0 +1,38 @@
+# @zaimokuza/dsh-acp-adapter bundle patch layer for the DSH rc.2 host.
+# The rows below replace the stock agent loop and model-selection contributions.
+#
+# This file becomes one patch layer when the package is listed in a profile's
+# dsh.profile.bundles (`dsh plugin --profile <name> add <path>` reconciles it
+# there). The Loader composes every bundle layer over the empty profile root in
+# ONE applyEntryPatches call (vendor/include/src/index.ts:58), so the rows
+# below address the stock rows inserted by @deepseek-ai/dsh-base and
+# @deepseek-ai/dsh-web-app.
+#
+# Legacy replacement form: the
+# vendored applyEntryPatches refuses id-targeted `name` swaps ("name mismatch
+# ... skipping" — name is the match guard), so replacement = disable the
+# original row + insert the subclass under a fresh id, restating the row's
+# whole owned `config` (a patch replaces the targeted row's entire config
+# rather than merging into it).
+
+# Row ①: replace the agent-loop row with this package's AcpAgentLoop.
+# The stock row (dsh-base cordis.patch.yml:436-439) carries
+# `config: {agents: []}`; its maxParallelToolCalls is the schema default 10
+# (core/agent-loop/src/constants.ts:6, resolveMaxParallelToolCalls at
+# core/agent-loop/src/index.ts:133-134). The insert restates both keys with
+# those exact values, so non-ACP sessions behave identically to stock.
+- id: agent-loop
+  disabled: true
+
+- insert:
+    - id: agent-loop-acp
+      name: '@zaimokuza/dsh-acp-adapter'
+      config:
+        maxParallelToolCalls: 10
+        agents: []
+
+# Row ②: the enhanced ACP model picker replaces the built-in
+# model-selection UI row (dsh-web-app cordis.patch.yml:249-251, no config of
+# its own, so a plain id-targeted disable suffices).
+- id: ui-model-selection
+  disabled: true

package/docs/agents/README.md

@@ -0,0 +1,9 @@
+# Agent 指南
+
+这些指南只说明外部 Agent 的 CLI 登录、健康检查和 DSH 模板选择。认证由 Agent
+自己管理；不要把 credential、token、cookie 或环境变量值复制到 DSH、日志或 issue。
+
+- [Devin](devin.md)
+- [Codex](codex.md)
+- [Kimi](kimi.md)
+- [Claude](claude.md)

package/docs/agents/claude.md

@@ -0,0 +1,20 @@
+# Claude
+
+## CLI 检查
+
+插件使用 `claude-agent-acp`。请先按 Claude CLI 的官方流程完成登录，并在不暴露账户
+详情的前提下确认可执行：
+
+```bash
+claude-agent-acp --version
+claude-agent-acp --help
+```
+
+Claude 的认证由下游 CLI 管理；插件不读取认证目录，也不替用户 login/logout。若使用
+自定义可执行文件，可在 DSH profile 中指定 `CLAUDE_CODE_EXECUTABLE`。
+
+## 模型与配置
+
+Claude session 返回的 model/config options 才是可选目录。切换通过 DSH 的模型事务和
+Agent 的 config option 写入口完成；CAS 冲突不会覆盖并发用户选择。重启恢复时，插件
+先恢复 binding 和已提交选择，再允许 prompt。

package/docs/agents/codex.md

@@ -0,0 +1,20 @@
+# Codex
+
+## CLI 检查
+
+插件使用 `codex-acp`：
+
+```bash
+codex-acp --version
+codex login
+```
+
+登录和认证状态由 Codex 自己管理。插件只使用 `CODEX_HOME` 的 opaque 路径引用，绝不
+读取或输出 auth 文件内容。若本机 CLI 不接受上述命令，请以当前 `codex-acp --help`
+为准，并在 DSH 配置中填写实际可执行文件。
+
+## 审批与子任务
+
+Codex 可能通过 ACP 请求一次性权限；在 DSH 中选择 `allowed-once` 时，回传 option
+必须仍是 `allow_once`。Codex collaboration/subagent 事件只作有界的工具过程和终态
+摘要展示，不等价于 DSH 原生 child session。

package/docs/agents/devin.md

@@ -0,0 +1,25 @@
+# Devin
+
+## CLI 检查
+
+插件使用 `devin acp`。先在 Devin 自己的终端完成登录，再检查 CLI：
+
+```bash
+devin --version
+devin auth login
+devin auth status
+devin acp --help
+```
+
+`devin auth status` 的账户详情不要复制到日志或 issue。插件只保留认证路径的 opaque
+引用，不打开 credentials 文件。
+
+## DSH 配置
+
+选择 Devin 内置模板，确认 workspace 权限与 Agent mode。Devin 的 ACP 会话状态可能
+需要宿主临时目录；workspace-write 会话会经过状态目录和恢复对账门。审批被拒后，
+恢复无法证明连续性时会进入 `reconciliation-required`，请回滚或新建会话，不要强行
+继续旧历史。
+
+Devin 不保证每个 `request_permission` 都带工具名称；审批面板会显示脱敏的 fallback
+和有界目标信息，不会伪造工具名。

package/docs/agents/kimi.md

@@ -0,0 +1,22 @@
+# Kimi
+
+## CLI 检查
+
+本机验证过 Kimi CLI 提供以下入口：
+
+```bash
+kimi --version
+kimi login
+kimi doctor
+kimi acp --help
+```
+
+请在 Kimi 自己的 CLI/浏览器流程中登录和修复健康问题。插件只引用 Kimi data home
+中的 opaque 配置、credentials 和 oauth 路径，不读取、复制或记录其中的值。
+
+## DSH 配置
+
+选择 Kimi 模板后先等待 health 为 `ready`，再创建 ACP 会话。模型和思考选项以本次
+Agent session 实际返回的 config options 为准；没有实时 option 时，界面不会猜测或
+伪造模型身份。无需、也不要把 credential 或环境变量值填入 DSH；只在 ACP 面板选择
+Kimi 模板并执行重新检查。Kimi 的文本、工具和上下文占用展示遵守统一 ACP 边界。

package/docs/architecture.md

@@ -0,0 +1,26 @@
+# 架构说明
+
+```text
+DSH host / Cordis
+      │ typed Remote + host structure gate
+      ├── host/             组合、profile、进程生命周期
+      ├── protocol/v1/      ACP RPC 门卫、事件翻译、展示信封
+      ├── domain/session/   binding、resume、reconciliation、options
+      ├── domain/policy/    sandbox、审批、脱敏与能力矩阵
+      ├── persistence/      sidecar SQLite 审计与恢复辅助状态
+      └── client/data + ui  picker、模型事务、面板与工具卡
+```
+
+依赖方向从 host/protocol 经过 domain/persistence 到 typed remote/client glue；上游
+`ModelPicker` 复制壳仅存在于 `client/host-compat/model-picker/`，不承载 ACP 业务逻辑。
+兼容岛结构漂移时 fail closed，保护 DSH native 路由。
+
+## 生命周期
+
+创建时先启动和初始化 Agent，再持久化 binding，最后才允许首个 prompt。恢复时先在
+staging 中 `session/load`，逐项核对 DSH 历史与 ACP 终态；无法证明同一会话就阻止续问。
+模型切换使用 begin → Agent apply → DSH select → commit 的事务边界，CAS 冲突只回报
+并发状态，不覆盖后来选择。
+
+DSH session log 是用户可见历史真源。DSH rc.2 没有可忽略自定义事件写入口，因此 ACP
+审批、binding、对账和降级审计写入 sidecar；sidecar 不是第二份对话历史。

package/docs/compatibility.md

@@ -0,0 +1,18 @@
+# 兼容性
+
+| 项目 | 接受范围 | 已验证 |
+| --- | --- | --- |
+| DSH | `>=0.1.1-rc.2` | `0.1.1-rc.2` |
+| Node.js | `^22.19.0 || >=24.0.0` | 24.19.0 |
+| 平台 | 以宿主和 Agent CLI 为准 | macOS |
+| Agent | Devin / Codex / Kimi / Claude ACP | 各自的当前 descriptor 版本 |
+
+“接受范围”是 package metadata 的版本约束，不等于每个版本或平台都经过真实 E2E。
+Windows 尚未验收，不属于当前已验证平台；rc.8 不在兼容范围。远程 ACP transport、
+跨 backend history handoff、通用 credential broker 和 DSH tools/skills/MCP 注入也不在
+当前产品范围。
+
+已知限制：被拒工具缺失导致的 Devin replay divergence 会被恢复对账拦截（fail closed）；
+DSH 会话删除没有 sidecar 删除钩子，插件 retention/compact 只能按自身生命周期清理；
+完整 controller 故障注入需要宿主公开 seam，自动化矩阵覆盖了该补偿逻辑，但不冒充真机
+DSH rejection 证据。

package/docs/getting-started.md

@@ -0,0 +1,44 @@
+# 入门
+
+## 环境
+
+- DSH `0.1.1-rc.2` 或更高版本（本项目已验证 rc.2；不支持 rc.8）。
+- Node.js `^22.19.0 || >=24.0.0`，门禁版本 Node 24.19.0。
+- 一个已安装、可独立运行的 ACP Agent CLI。
+
+## 安装插件
+
+公开包安装：
+
+```bash
+dsh plugin --profile web add @zaimokuza/dsh-acp-adapter
+dsh web
+```
+
+本地开发或发布前验证：
+
+```bash
+pnpm pack
+dsh plugin --profile web add /absolute/path/to/zaimokuza-dsh-acp-adapter-*.tgz
+dsh web
+```
+
+卸载使用 `dsh plugin --profile web remove @zaimokuza/dsh-acp-adapter`。安装、卸载和
+验证应在测试 profile 中完成；不要把生产 profile 的状态目录用于试验。
+
+## 创建第一个 ACP 会话
+
+1. 按 [Agent 指南索引](agents/README.md) 完成 CLI 自己的登录与健康检查。
+2. 打开 DSH ACP 设置，选择 Devin、Codex、Kimi 或 Claude 模板。
+3. 确认命令可执行、协议初始化通过、health 为 `ready`。
+4. 选择 Agent 暴露的 model/mode/config option 后创建会话。
+5. 首次 prompt 前确认设置面板已经显示 workspace 权限和 Agent mode 两条独立信息。
+
+ACP 会话创建后 backend 不可变。需要从 native 切到 ACP，或从一个 ACP runtime 切到
+另一个 runtime 时，请新建会话；插件不会把历史隐式迁移到新 Agent。
+
+## 不要做的事
+
+不要在插件配置、shell 日志、测试夹具或 issue 中粘贴认证文件、token、cookie、环境
+变量值或完整 command line。问题报告请只保留 Agent 名称、版本、health 状态和脱敏的
+错误类别。

package/docs/operations.md

@@ -0,0 +1,42 @@
+# 操作与发布检查
+
+## 日常诊断
+
+先记录 profile、Agent 命令、版本、health 状态和错误类别，不记录环境变量值或认证文件。
+按顺序检查 DSH、Agent CLI、ACP initialize、临时 session 和目标 workspace 权限。health
+不是 ready 时不要创建会话；已有会话按 UI 提供的回滚或新建出口处理。
+
+## 本地门禁
+
+```bash
+pnpm install --frozen-lockfile
+pnpm typecheck
+pnpm test
+pnpm build
+pnpm pack --dry-run
+pnpm check:stale-build
+pnpm check:picker-diff
+git diff --check
+```
+
+这些命令串行执行。install gate 必须使用隔离 profile 和 tarball；不带凭证运行时只验
+证凭证缺失的降级路径，不为了门禁读取或打印已有 key，也不发送真实模型 prompt。
+
+## 发布前
+
+从最终工作树重新 `pnpm pack`，检查 tarball 只包含 lib、patch、许可证、README 和 docs
+用户文档；在干净 DSH rc.2 profile 完成 install/boot/uninstall 后，再由发布负责人执行
+npm/GitHub Actions。未实际执行的 CI、npm publish、Windows 或 Agent E2E 不得写成 PASS。
+
+## npm 发布
+
+首次发布需要维护者用 npm 账户完成一次 bootstrap。确认 `npm whoami` 返回包 scope 的
+所有者，创建并推送与 `package.json` 完全一致的 tag（例如 `v0.1.0-rc.1`），然后执行
+`pnpm verify:release` 和 `npm publish --access public --tag next`。前一个命令会验证当前
+HEAD 正好位于版本 tag；预发布版本禁止占用 `latest`。
+
+首次发布后，在 npm 包设置中把 GitHub Actions Trusted Publisher 绑定到
+`zaimokuza-yoshiteru/dsh-acp-adapter`、工作流 `publish.yml` 和 environment
+`npm-publish`，允许 `npm publish`。后续版本只需更新版本号、通过 CI、创建对应 tag，
+再从该 tag 手动运行 `publish npm` 工作流。工作流使用 OIDC，不读取长期 npm token；
+预发布版本自动进入 `next`，稳定版本自动进入 `latest`。

package/docs/troubleshooting.md

@@ -0,0 +1,22 @@
+# 故障排查
+
+## health 不是 ready
+
+确认 CLI 可执行、外部登录已完成、workspace 权限允许 Agent data home，并重新运行 Agent
+自己的 doctor/help。插件不读取凭证；若认证失效，回到 Agent CLI 修复后重新检查。
+
+## 审批没有通过
+
+检查请求的 tool name/reason 是否为有界脱敏文本，并确认 UI 选择的是 `allowed-once`。
+仅提供 `allow_always` 的 Agent 选项会被拒绝，插件不会把它降级成一次性允许。
+
+## 会话变成 reconciliation-required
+
+这是 fail-closed 保护：DSH 历史和 Agent 回放无法证明一致。不要删除或手改 sidecar。
+按 UI 选择回滚、rebind blank 或新建 ACP 会话；需要报告时只提供 session id、状态和脱敏
+错误类别。
+
+## 模型切换失败
+
+并发写入会显示 conflict，插件不会覆盖后来选择。补偿失败会同时说明新会话是否创建、
+默认模型是否恢复；按提示人工检查 DSH 设置，再重试单次切换。