dsh-acp-agentmode

给 dsh --profile acp（Agent Client Protocol 自动化模式）增加一个参数：启动时直接选定 agent preset。

dsh --profile acp --agentmode cordis     # 本次进程的每个新会话都用 cordis preset
dsh --profile acp                        # 用 profile 配置的默认 preset（本包默认 standard）
dsh --profile acp --list-agentmodes      # 列出本 profile 声明的 preset

默认不持久化：不带参数时复用当前 profile 里用户已设定的 preset（并在日志里标明来源）；--agentmode 只覆盖本次启动；只有显式 --remember 才会把选择写进当前 profile。

⚠️ 设定按 profile 隔离（harness 设计，不是本插件的取舍）：Web 界面里的"默认 preset"由 settings 服务写入当前 profile 的 cordis.patch.yml。桌面端 Web 界面 = desktop profile，所以在那里设的值不会自动带到 dsh --profile acp；acp 会退回本 bundle 声明的部署默认 standard。要让 ACP 跟随某个默认，用 --remember 写入 acp profile（推荐），或把值放进共享 home patch $DSH_HOME/cordis.patch.yml（它会压住 Web 表单对该字段的写入）。

工具链：Vite+ 1.3（vp check / vp test / vp pack）+ pnpm + TypeScript 7，零运行时依赖。

安装、构建与卸载

pnpm install        # 只装工具链（vite-plus / typescript / vitest / @types/node）
pnpm build          # vp pack → dist/index.mjs + dist/index.d.mts + sourcemap
git clone https://github.com/MangMax/dsh-acp-agentmode.git
dsh plugin --profile acp add ./dsh-acp-agentmode

• 也可以直接从 GitHub Releases 下载 tarball：dsh plugin --profile acp add ./dsh-acp-agentmode-0.3.0.tgz（未发布到 npm，刻意为之：这个包只在 acp profile 里有意义）。
• 该 bundle 只属于 acp profile。界面里的 plugin_manager 只作用于当前 profile（本机是 desktop），必须用 dsh plugin --profile acp …。
• 安装会写 profile 的 dependencies 并把 dsh-acp-agentmode 追加到 dsh.profile.bundles 末尾；patch 层按顺序应用，只有排在 @deepseek-ai/dsh-acp-app 之后的层才能覆盖它的行。
• profile 以 symlink 方式引用本目录，因此改完代码必须 pnpm build（harness 通过 package exports 加载 dist/index.mjs）。
• 卸载：dsh plugin --profile acp remove dsh-acp-agentmode，profile 回到“零参数 ACP”。

命令

命令	作用
pnpm check / pnpm check:fix	vp check：格式化 + oxlint（含类型感知与 tsc 类型检查）
pnpm test	vp test：69 个单元测试（纯逻辑 + 假端口，无真实 harness）
pnpm build	vp pack：ESM 库构建（含 .d.mts 与 sourcemap）
pnpm smoke -- --agentmode minimal	真实端到端冒烟：拉起 dsh --profile acp，走 initialize → session/new，再从会话日志断言 preset 真的挂上了
pnpm smoke	同上，但走"无参数"路径，验证 profile 设定的复用
pnpm sync-presets	从已安装的 @deepseek-ai/dsh-web-app 重新快照四个官方 preset 声明
pnpm verify	check && test && build，即 prepack 的完整门禁

目录与模块

src/constants.ts   限制、退出码、计时预算、preset id 语法（安全策略集中处）
src/ports.ts       四个协作方的最小结构接口（无 @deepseek-ai/cordis 版本绑定）
src/args.ts        严格参数解析（纯函数）
src/sanitize.ts    诊断文本净化（ANSI/控制字符/换行/路径）
src/errors.ts      错误码 + 退出码映射的唯一位置
src/log.ts         唯一写 stderr 的出口
src/selection.ts   roster 等待与 resolve（带回退重试与截止时间）
src/compose.ts     会话与 preset 的绑定策略（select / mount / 降级）
src/plugin.ts      Cordis 适配层：守卫、发布就绪、事件、清理
src/index.ts       包入口（导出 name/inject/apply 及公开错误类型）
tests/unit/*.test.ts  纯逻辑单测；tests/helpers/fakes.ts  手写假端口
scripts/sync-presets.ts / scripts/smoke-acp.ts
cordis.patch.yml + presets/*.patch.yml   组合层（见下）

设计要点：ports.ts 让插件不依赖具体 harness 版本的类型，也让人工假端口可以完整单测；plugin.ts 是唯一接触真实 Cordis 上下文的地方。

复用你的设定：读取 / 覆盖 / 持久化

registry 解析"新会话用哪个 preset"的公式是 selectedDefault ?? default：

• default 是本 bundle 的补丁声明的部署默认（standard），只是兜底；
• selectedDefault 是 volatile 用户字段——Web 设置界面里"默认 preset"写的就是它，由 settings 服务持久化到当前 profile 的 Cordis 补丁层。

所以插件本来就是"读用户设定"的，--agentmode 只是本次覆盖。三种用法与来源标注：

用法	行为	启动日志
dsh --profile acp	读 selectedDefault ?? default	agent preset: ptc (user setting) / (home/command-line override) / (deployment default)
dsh --profile acp --agentmode cordis	仅本次覆盖	agent preset: cordis (from --agentmode)
dsh --profile acp --agentmode ptc --remember	通过官方 settings.update('agent-preset-registry', { selectedDefault }) 写入当前 profile 补丁，之后无参数即复用	remembered agent preset: ptc

--list-agentmodes 也会标出 (default, user setting) / (default, override)。

为什么 desktop/web 里的选择不会自动带到 ACP：settings 是按 profile 持久化的（写入 profileContext.patchPath），而 dsh --profile acp 是另一个 profile，有独立的补丁层与存储。想跨 profile 共用一份，两条路：① 在 acp profile 里 --remember 一次；② 写共享的 home patch $DSH_HOME/cordis.patch.yml（优先级高于 profile 补丁；注意此时 settings 表单写入会被拒绝，见上游 dsh-settings README）。插件不会去读别的 profile 的文件——那会破坏 profile 隔离。

它在 profile 里改了什么

cordis.patch.yml 四段，全部是普通 Loader patch：

1. 接管命令行：disable 官方 acp-app-startup 行（零参数 commander program，任何额外参数都会 error: unknown option），插入本包的 acp-agentmode 行，由它提供官方 acp 行 inject 的 acpAppStartup 服务。
2. agent 平面搬进 preset：禁用 base 里 23 条“每 agent 各自贡献”的行（tool-bash / tool-fs / tool-skill / tool-todo / tool-web / tool-subagent* / compaction-basic / agent-instructions / skill-filesystem …），与 @deepseek-ai/dsh-web-app/cordis.patch.yml 对 Web 面的拆分同构——ACP 一个进程服务多个会话，而这些 base 行是为“单会话、进程级组合”的表面保留的。
3. 插入 preset 选择注册表：agent-preset-registry，default: standard（仅在没有 --agentmode 时兜底）。
4. 插入 host 支撑行：subagent-model-selection-settings、plugin-inventory —— preset 子行要消费、base 不提供的 Host 服务。

工作原理

命令行：inject: ['cmdlineArgs'] → 严格解析 → assertAcpProfile() 守卫 → 同步发布 acpAppStartup → 后台解析 preset → 成功后才 arm stdin EOF。

就绪必须同步发布：App 层启动审计会独立结算 Loader 树，若让 readiness 等 registry I/O，慢一点就会被判成“启动失败”。解析失败则打印分类错误并以对应退出码退出。

会话绑定：dsh-acp 建 agent 时只传 meta: { cwd }，从不挂 preset（Web 的 session controller 是在自己的 setup 里 agentPresets.mount）。所以从外部接上：监听 serial 事件 agent/created（agent loop 在释放排队输入之前 await 它），对空白会话调 agentPresets.select(agent, id) —— 这正是 Web UI 给“活着的空白会话”换 preset 用的公开 API，且 select 只在 recompose/mount 成功后写入 agent-preset/selected。session/resume 的会话已过首轮（select 会以 agent-preset/locked 拒绝），因此沿用日志记录的 preset 并用 agentPresets.mount() 组合。

两个启动期竞态：① 声明是异步注册的 —— 按 Loader 中声明行数等待 roster 到齐（有截止时间）；② profile 的启动 patch 重载会重建 registry 行 —— 只对 agent-preset/not-found 做抖动退避重试，INACTIVE_EFFECT（实例被替换）交给替换实例。另有一个 watchdog：registry 始终不激活时报 E_ENVIRONMENT 并退出，而不是让客户端在“永远不会被组合”的会话上打转。

安全加固

面	措施
参数面	只接受 --agentmode / --agentmode= / --list-agentmodes / -h；重复参数直接报错（不做 last-wins）；-- 之后不允许位置参数；未知选项不静默忽略
输入校验	preset id 在进入 registry 之前按 ^[A-Za-z0-9][A-Za-z0-9._-]*$、长度 ≤ 64 校验：不允许空白、控制字符、前导分隔符（防止被下游当成 flag）
组合守卫	启动时检查组合里确实有 @deepseek-ai/dsh-acp 行、且官方零参数启动行已被禁用；否则以 E_ENVIRONMENT 退出——误装到别的 profile 会响亮地失败而不是劫持它的 stdin/退出语义
服务发布	只发布一次；若别的 row 已发布 acpAppStartup，记警告并让位，不抛错、不崩溃
诊断卫生	所有 stderr 输出经 oneLine + redactPaths：剥离 ANSI/OSC 与控制字符（防终端劫持）、压成单行（防日志伪造）、长度截断、把 $HOME/$DSH_HOME/绝对路径替换为 ~ / <path>
代码面	无 eval/Function/动态 import；不读 stdin（只挂 end 监听并在卸载时移除）；不调用 process.exit（走 launcher 的 appExit）；零运行时依赖
生命周期	每个实例一个 AbortController，卸载即中止所有等待并清理全部定时器，不留悬挂句柄
stdout 纯净	stdout 只允许 --help 与 --list-agentmodes 两个出口；ACP 协议帧独占 stdout，冒烟脚本会断言 stdout 不含诊断文本

性能

• 启动零阻塞：readiness 同步发布；preset 解析在后台，首个 session/new 会 await 同一个 promise（只解析一次）。
• 不做忙等：等待策略是“先让 Loader 静止（有界 race）→ 再按声明行数等 roster”；退避 20ms 起、160ms 封顶，全部有截止时间；不存在固定轮询热路径。
• 零热路径开销：已绑定 preset 的 agent 只做一次 composedPreset() 判断即返回；subagent 子代理在自身 setup 里继承父级，直接跳过。
• 构建产物：单文件 ESM 31.6 kB（gzip 10.5 kB），无运行时依赖、无 top-level 副作用。
• 清理：定时器统一由实例时钟登记，卸载即 clearTimeout。

错误模型

错误码	含义	退出码
E_USAGE	调用本身不对（未知选项、缺值、非法 id、重复参数）	2
E_PRESET_UNKNOWN	id 不在 roster（消息附可用列表）	3
E_PRESET_UNUSABLE	声明存在但无法激活（消息附 registry 给出的原因，如缺 cordisInspect）	3
E_REGISTRY	registry 未在预算内响应	3
E_ENVIRONMENT	组合不对（不是 ACP app、官方启动行仍激活、注入缺失、registry 从未激活）	4
E_BIND	单个会话绑定失败——只 warning，降级为“无 preset 组合”，绝不让 session/new 失败	—

DSH_ACP_AGENTMODE_DEBUG=1 会额外输出 cause 链与（净化后的）栈，默认只输出一行分类错误。

已验证

单测：vp test — 7 个文件 / 85 个用例全绿（参数语法、诊断净化、roster 等待、resolve 分类与重试、空白会话判定、绑定降级、设定来源判定与 --remember 写入、apply() 的 help/守卫/发布/列表/重复发布等）。

静态门禁：vp check — 格式化 + oxlint（类型感知）+ tsc 类型检查，0 error / 0 warning。

真实端到端（本机 0.2.1-rc.2，最小 ACP 客户端，不触发模型调用）：

用例	结果
--agentmode standard/minimal/ptc/cordis	会话创建成功；会话日志分别写入 agent-preset/selected: standard/minimal/ptc/cordis
不带参数	默认 standard
--agentmode nope	exit 3，E_PRESET_UNKNOWN: unknown agent preset "nope"; available: standard, ptc, minimal, cordis
--bogus	exit 2，E_USAGE: unknown option "--bogus"
--list-agentmodes / --help	exit 0，输出正确
session/resume（空白会话）	成功，组合沿用日志记录的 preset
pnpm smoke -- --agentmode minimal	通过（脚本自行读会话日志断言）
stdout 纯净	客户端只收到 JSON-RPC 帧

未实测：session/resume 的非空白会话（mount 分支）需要先产生一轮真实模型对话。

权限（沙箱 / 审批）

ACP profile 里权限由 permission 行（@deepseek-ai/dsh-permission-presets）决定，它把 sandbox 与 approval 绑成一个预设。acp profile 默认没有 defaultPreset，所以默认值是推断出来的：

项	默认值
permission/preset	workspace-write
sandbox/mode	workspace-write
approval/policy	ask

要改成完全访问，在 ~/.dsh/profiles/acp/cordis.patch.yml 里补 defaultPreset（config 是整体替换，整张 presets 表必须重述）：

- id: permission
  name: '@deepseek-ai/dsh-permission-presets'
  config:
    presets:
      read-only:
        sandbox: read-only
        approval: ask
      workspace-write:
        sandbox: workspace-write
        approval: ask
      danger-full-access:
        sandbox: danger-full-access
        approval: never
    defaultPreset: danger-full-access

只想本次生效就不改 profile，把它存成文件后用 launcher flag 叠加（--patch 必须在 app 参数之前）：

dsh --profile acp --patch ~/.dsh/full-access.yml

验证方式是读会话日志的前三个事件：

permission/preset : danger-full-access
sandbox/mode      : danger-full-access
approval/policy   : never

三个要注意的点：ACP 客户端的 session/new 只暴露 model 与 reasoning_effort，没有权限选择面（/permission 这类命令 ACP 也不支持），所以权限只能在 profile 默认或 --patch 上设；danger-full-access 自带 approval: never，因此不再产生审批请求；一个 ACP 进程服务多个会话，该默认对全部会话生效。

已知能力边界

• 设定按 profile 隔离：selectedDefault 只存在于写入它的那个 profile；跨 profile 没有共享存储（同机 desktop/web/acp 各自独立）。要跨 profile 统一，用共享 home patch，代价是 Web 表单此后改不动该字段。
• 粒度是进程级：一次 dsh --profile acp 一个 preset。要让 ACP 客户端按会话指定，必须改 harness 的 dsh-acp（session/new 的 _meta 被 SDK 保留但 bridge 完全忽略），纯插件做不到。
• preset 不含模型：preset 组合工具/提示词段/skills/压缩/委派；模型仍由 acp 行与 agent-default-model 决定，客户端还能用 session/set_config_option 改 model/reasoning_effort。
• 两个子行在该表面不可用，已在快照中 disabled: true 并保留上游原文：tool-schedule（需要 Web 专属 sessionController 支撑的 schedule）、tool-cordis（需要 Web 专属 inspector 的 cordisInspect）。因此 cordis preset 在 ACP 面上可用但缺少 cordis 运行时查询工具。
• 禁用清单镜像 Web 面的 23 行：上游改名只会产生 “warn + skip”（不致命）；上游新增 agent 平面行会留在 host 平面并被 preset 同名行就近遮蔽，但可能带来额外 token 开销——升级后建议对照一次。
• 桌面界面的 plugin_manager 看不到它（不同 profile）；locale/、icon.svg 只为清单完整性准备，渲染效果无法在桌面 UI 验证。

升级维护

pnpm sync-presets                       # 从当前安装的 harness 重新快照 presets/
pnpm sync-presets /path/to/dsh-web-app  # 或显式指定包目录

脚本会按当前 harness 版本重新生成四个 preset 声明，并自动给“本表面不可用”的子行加 disabled: true（清单与原因写在脚本里）。升级 harness 后建议再跑一次 pnpm verify && pnpm smoke。

依赖的公开 API

ctx.cmdlineArgs / ctx.appExit / ctx.appReady（启动器值），ctx.agentPresets.{list,resolve,select,mount,composedPreset,defaultId}，ctx.sessionProjections.stateOf(session, 'agentPreset' | 'turnBoundary')，serial 事件 agent/created，Loader 的 entries() / await()。全部为公开契约，未触碰内部实现。

贡献与安全

• 参与开发：见 CONTRIBUTING.md（本地门禁是 pnpm verify；dist/ 不入库，Release 构建产出）。
• 报告漏洞：请走 SECURITY.md 的私密渠道，不要开公开 issue。
• 行为准则：CODE_OF_CONDUCT.md。

main 受保护：所有改动经 PR + CI 全绿 + 维护者审核后合并。

MIT License.