dsh-ark

Readme

[English](README.en.md) | [简体中文](README.md)

# dsh-ark

DeepSeek Harness 的 Ark 模式：三个冻结的 minimal wire 预设
（`bash` + `str_replace_editor`），所有扩展能力都通过 `dsh-ark` CLI 侧信道交付。

| 预设 | 对应模式 | CLI 目录 |
|---|---|---|
| `ark` | standard | standard |
| `ark-code` | code (PTC) | code |
| `ark-cordis` | cordis | cordis |

## 项目目的

本项目是针对 `deepseek-v4-pro-0813` 对 deepseek-harness `minimal` 预设的
系统提示词与 tool schema 存在过拟合问题而设计的 workaround。

具体来说，`deepseek-v4-pro-0813` 在 `minimal` 预设的固定提示词和极简工具面上
表现最为稳定；一旦切换到 standard / code / cordis 等模式的原生 persona 与更大、
更复杂的 tool schema，模型行为容易变得不稳定或不符合预期。dsh-ark 因此将 Ark
系列预设统一冻结在 minimal 的 wire 表面（`bash` + `str_replace_editor`），不让
standard / code / cordis 的扩展工具直接进入模型请求，而是通过 `dsh-ark` CLI
侧信道按需代理执行，从而同时获得：

- minimal 预设的稳定性；
- standard / code / cordis 的完整能力目录。

## 原理

核心思路是“冻结模型可见面，扩展能力走 CLI 侧信道”：

1. 模型请求中只保留 minimal 风格的系统提示词，以及 `bash`、
   `str_replace_editor` 两个工具，避免大而杂的 tool schema 干扰模型。
2. 其它模式的能力（指令、技能、工具、MCP、宿主桥等）由 `dsh-ark` CLI 封装，
   通过 bash 侧信道按需调用。
3. CLI 根据当前会话的 `DSH_ARK_MODE`（`standard` / `code` / `cordis`）加载
   对应目录，把原本需要以 tool schema 注入模型的能力，改为模型用一条 bash
   命令触发、CLI 代理执行的模式。

## 使用方法

1. 安装插件：

   ```sh
   dsh plugin --profile web add dsh-ark
   dsh web
   ```

2. 在客户端中选择 Ark-* 预设：

   - `Ark`：standard 目录
   - `Ark-Code`：code 目录
   - `Ark-Cordis`：cordis 目录

3. 会话启动后，按需在 bash 中运行 `dsh-ark <domain> <action>` 即可使用对应
   模式的扩展能力，例如：

   ```sh
   dsh-ark tools list
   dsh-ark mcp list
   dsh-ark bridge status
   ```

## 安装

```sh
dsh plugin --profile web add dsh-ark
dsh web
```

安装后，`dsh --profile web --dump-config` 必须输出
`agent-presets.default: ark`，且预设名册中必须包含 `ark`、`ark-code` 与
`ark-cordis`。宿主插件会在启动时为每个预设写一个模式专属的
`$DSH_HOME/.agent-presets/<mode>/shellrc.sh` —— 即官方 harness-home 用户预设根目录 ——
持久 bash 通过 `--rcfile` 加载该文件，因此无需配置 PATH 即可访问
`dsh-ark guide` 及其它侧信道命令。会话开始时，ark 宿主插件会在第一个请求中注入
一个合成的 "`dsh-ark guide` 已运行并返回了该输出" turn；当 dsh compaction 把可见的
guide 结果遮蔽之后，它会再次注入同一对（见 `docs/dsh-ark-design.md` 4.6）。
只有当注入的输出不再可见时，模型才需要自己运行 `dsh-ark guide`。
shellrc 会导出 `DSH_ARK_MODE`（用于选择 CLI 目录）和 `DSH_ARK_WORKSPACE`
（把每条 dsh-ark 命令固定到 shell 启动时捕获的会话工作区根目录，而不是持久 shell
可变的 `pwd`）。

## 本地测试发布

要在本地 dsh 的 `web` 与 `dsh-tui` profile 上就地验证全新构建的检出，而不经过真正的
发布流程，运行：

```sh
pnpm run test:publish
```

它会执行 `pnpm pack`（触发 `prepack` 并重建 `lib/`），把结果复制到
`dist/dsh-ark-current.tgz`（已被 gitignore），重写
`$DSH_HOME/profiles/{web,dsh-tui}/package.json` 中 `dependencies.dsh-ark` 的条目，
使其指向该绝对 `file:` 路径，然后调用 `dsh plugin add`，让 pnpm 把新 tarball 重新
解压进每个 profile 的 `node_modules/dsh-ark/`。传 `pnpm run test:publish:dry` 可以
只打包而不改动 profile 清单。要回滚到 registry 已发布的版本，运行
`dsh plugin --profile web remove dsh-ark && dsh plugin --profile dsh-tui remove dsh-ark`。

## CLI

```text
dsh-ark [--json] [--no-color] <domain> <action> [options]

guide          打印当前模式与会话工作区对应的 Ark 会话指引（会话开始时运行一次）
instructions   展示/列出 AGENTS.md + CLAUDE.md 指令链
skills         从项目/用户根目录列出/展示技能
tools          列出/查看可用性/调用工具，外加每个工具的 --help 结构
mcp            配置合并 + stdio/streamable-http MCP 客户端
run-code       仅 v1 协议；执行返回 UNAVAILABLE_IN_V1
bridge         经过认证的宿主桥：status/list/schema/call
version        包版本
```

示例：

```sh
dsh-ark --help
dsh-ark guide                 # 报告固定的会话工作区与当前 ark 模式
dsh-ark instructions show
dsh-ark skills list           # ark-cordis 会话会附带打包的 cordis 技能
dsh-ark tools list            # 依据已安装的预设列出 standard/code/cordis 目录
dsh-ark tools call read '{"file_path":"/tmp/x"}'
dsh-ark tools grep --help
dsh-ark mcp list
dsh-ark mcp call memory search '{"query":"TODO"}'
dsh-ark bridge status
dsh-ark bridge call job_list '{}'
dsh-ark bridge call subagent '{"prompt":"..."}' --wait
```

没有 `--preset` 选项。目录由已安装的 ark 预设选择，并通过生成的 shellrc 导出为
`DSH_ARK_MODE`。

## 运行时模型

- 运行时从不导入固定的 `@deepseek-ai/dsh-*` registry 版本。CLI 从
  `DSH_ARK_DSH_PACKAGES_DIR` 或 `$DSH_HOME/profiles/node_modules` 解析用户安装的
  dsh 包依赖图，并在使用前探测结构化的能力契约。
- 活动目录由生成的 shellrc 中的 `DSH_ARK_MODE`（`standard`、`code` 或 `cordis`）
  选择；直接调用 CLI 时默认 `standard`。没有状态文件、不改变环境、无持久化。
- 宿主插件在最终提示组装边界强制冻结的 wire 表面：对 ark 会话，宿主/全局工具
  schema（例如 dsh-tui 的 `ask_user_question`）会从请求中移除并被记录日志。
- Phase 2 在 `$DSH_HOME/ark/{bridge.sock,bridge.token}`（均为 0600）下增加了一个
  经过认证的 Unix-socket 宿主桥。`dsh-ark bridge` 通过活跃会话 agent 与宿主审批/
  沙箱栈发现并执行完整的模式目录。其它宿主插件注入的工具保持在冻结的模型 wire 之外，
  再以 `source: proxy` 条目动态出现在 `dsh-ark bridge list` / `dsh-ark tools list`
  中；它们与内置工具一样通过同一 `ark.executeTool` 宿主管线执行。长时委派返回宿主
  拥有的 `bridgeJobId` 以便轮询，且 CLI 从不 daemon 化。
- 桥状态限定在 `$DSH_HOME` 内：每个 dsh 实例拥有自己的 socket/token/jobs，每个请求
  都绑定到生成 shell 所继承的 `DSH_SESSION_ID` 与 `DSH_ARK_MODE` 对应的活跃会话。
  完整机制及其信任边界见 `docs/phase2/session-binding.md`。
- MCP 配置：全局 `$DSH_HOME/ark/mcp.yml`、项目
  `<projectRoot>/.dsh/ark-mcp.yml`、显式的 `DSH_ARK_MCP_CONFIG` 覆盖。
- 退出码：`0` 成功，`2` 用法错误，`3` 未找到，`4` 不可用，`5`
  上游/IO/执行失败，`124` 超时。

## 可追溯性

实现由 OpenSpec 跟踪：
- 活动 spec：`openspec/specs/dsh-ark/spec.md`
- 活动 change：`openspec/changes/release-prep-preset-layout`
- 已归档 v1 change：`openspec/changes/archive/2026-08-16-implement-dsh-ark-v1`
- 已归档 wire-guard change：`openspec/changes/archive/2026-08-16-implement-ark-wire-guard`
- 已归档 phase 2 change：`openspec/changes/archive/2026-08-24-implement-dsh-ark-phase2`
- 已归档 upstream-compat change：`openspec/changes/archive/2026-08-24-harden-dsh-ark-upstream-compat`
- 已归档 dynamic-tool-proxy change：`openspec/changes/archive/2026-08-24-implement-dynamic-tool-proxy`

运行 `openspec validate --all --strict` 校验记录。

## 开发

```sh
pnpm install
pnpm run sync-upstream
pnpm run check:upstream-contracts
pnpm run build
pnpm test
pnpm test:bwrap          # 未带 bwrap userns 的本地 runner 默认跳过
pnpm pack --dry-run
```

兼容性矩阵：`docs/compatibility.md`。
维护指南：`docs/dsh-ark-maintenance.md`。
发布清单：`docs/release-checklist.md`。
桥实例/会话绑定报告：`docs/phase2/session-binding.md`。

不变量与完整实现计划见 `docs/dsh-ark-design.md`。

## 致谢

感谢 [xiaobright/dsh-anchored-standard](https://github.com/xiaobright/dsh-anchored-standard)
等相关研究，为本项目的思路提供了重要参考。