@dshx/dshx

Readme

# dshX

<p align="center">
  <a href="https://www.npmjs.com/package/@dshx/dshx"><img alt="npm" src="https://img.shields.io/npm/v/@dshx/dshx?style=flat-square&color=4b6fff"></a>
  <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-blue?style=flat-square"></a>
  <img alt="dsh-plugin" src="https://img.shields.io/badge/DeepSeek%20Harness%20plugin-%E2%9C%93-brightgreen?style=flat-square">
</p>

> ⚠️ 社区项目，与 DeepSeek 官方无关联、未获背书。基于 deepseek-harness（MIT），
> 遵循官方插件生态指南（本仓库带 `dsh-plugin` topic）。

> 基于 **deepseek-harness** + **@dshx/tui**（dsh-TUI 的分叉）、内置 **prefab-anchored-standard** 的
> Claude Code / opencode 风格终端编程应用。

`dshx` 一条命令启动：deepseek-harness 提供模型适配与工具执行，@dshx/tui（dsh-TUI 的
分叉，词标 `dshx` + 简洁启动页）提供 Claude Code 风格终端交互，prefab-anchored-standard
用一个已验证的 anchored 轨迹**预填充每个新会话**，并在首请求上暴露 Minimal 工具对，
把 DeepSeek V4 Pro 的训练对齐轨迹锚定住，再逐步恢复按需工具。

## 是什么

dshX 不是 fork，而是一个「profile bundle + launcher + 内置 preset」分发层：

```
dshx (命令) ──> dsh --profile dshx
                 ├─ dsh-base        （deepseek-harness 核心：LLM 路由、沙箱、会话、工具）
                 ├─ @dshx/tui      （终端前端 + 状态行 + /preset + /resume …）
                 └─ dshx patch      （默认 preset=prefab-anchored-standard + 产品姿态）
```

模型调用、工具执行、会话/持久化、沙箱/审批全部由 DSH 服务拥有；dshX 只做组合，
**零 deepseek-harness 核心改动**。

## 为什么内置 prefab-anchored-standard

DeepSeek V4 Pro 强依赖首个 API 请求可见的工具目录。官方 `minimal` preset 发送
「精确的 RL prompt 与 schema」（官方快照测试原话 `exact RL prompt and schemas`），
在 Project2 评测得到 99/96；而 `standard`（约 25 个工具）只有 91，`PTC` 只有 92。

prefab-anchored-standard（dsh-anchored-standard 的 prefab 模式）把「首次轨迹选择」
和「后续完整工具能力」拆开，并且比基础 anchored-standard 更进一步——**先给会话一段
已经跑通的 anchored 轨迹，再让模型继续**：

1. **会话预填充**：选中预设即用内置的 compact prefab 模板把空白会话回放成一段
   已验证的 anchored 轨迹（`prefab-session-seed`），用户的第一个真实任务在预填回合之后
   继续，首请求不再从零开始；
2. **首请求只暴露官方 Minimal preset 的 REAL 工具对**（持久 `bash` + `str_replace_editor`），
   输出预算为 adapter 默认（无 1024 cap）——该 schema 在默认 maxTokens 下锚定
   5/5，而每个 standard-family schema 都是 11/11 掉回 standard-like 行为；
3. **首请求剥离自动注入**：技能目录、AGENTS.md、时间/tmux、hooks 等一律不注入
   （`context-gate`），只放行用户主动的 `/技能` 手势；
4. **晋升后也不倒完整目录**：首个持久工具调用**或**首个助手回复（`promoteOn: either`）后，
   目录收窄为「Minimal 对 + 三个发现工具（`dev_tool_search` / `skill_search` / `skill_load`）+
   模型通过 `dev_tool_search` 显式解锁的工具」——重工具永远一次 `dev_tool_search` 之遥，
   不再被 25 工具 dump 拉回 standard-like；
5. **prefab 会话不广播 host skill catalog**（`skill-catalog-gate`）：dsh-base 在 host 层
   挂的 `dsh-tool-skill` 会把完整 `<available_skills>` 注入每个会话——包括 dshx 内置同步的
   j-space skill。该行在 prefab 作用域 `deny` 掉 `skill` 工具，广播整体消失，j-space 只通过
   按需的 `skill_search` 可达。

实测（Project2 V4.1b、`reasoningEffort=max`）连续两跑 **98/99**。
详见 [`xiaobright/modeltest`](https://github.com/xiaobright/modeltest) 的方法学与证据。

## 内置 skill：j-space

dshx 随包内置 **J-Space Cognition Suite V3.6**（`skills/j-space/`，推理时认知控制套件），
launcher 以 marker+checksum 幂等同步到 `$DSH_HOME/skills/j-space`——与 preset 同步同一套
「绝不覆盖用户数据」契约：用户手工装过的目录（无 dshX marker）原样保留。

- 在 **prefab** 会话里，j-space 不出现在自动 host catalog 中；模型或用户通过
  `skill_search "j-space"` + `skill_load`（或直接 `/j-space` 手势）按需加载。
- 在 **standard/code/cordis** 会话里，j-space 出现在 `<available_skills>` 中，可用 `skill` 工具加载。
- J-Space 自身目录、安装方式与行为**未做任何改动**；用户按原 README 手工安装 J-Space，
  再执行 dshX 时是 0 作用、无冲突、无报错。

## 快速开始

前置条件：Node `^22.19 || >=24`、`pnpm` 10+（首次初始化 profile 需要）、`DEEPSEEK_API_KEY`。
**dsh CLI 已随包内置**——无需单独安装 `@deepseek-ai/dsh`。

```sh
# 1. 全局安装 dshx（自动带上内置 dsh + TUI + preset + j-space skill）
npm install -g @dshx/dshx

# 2. 启动（首次运行自动初始化 dshx profile + 内置 preset）
dshx
```

`dshx` 提供 `dsh` 命令（透传内置 CLI）：`dsh plugin --profile X add <pkg>`、
`dsh --version` 等均可直接使用。装 dshx 后**不要再单独装官方 dsh**（会冲突）。

```sh
# 环境自检
dshx doctor

# 恢复上次会话
dshx --resume
```

首次运行会自动：
1. `dsh plugin --profile dshx add @dshx/tui@<v> @dshx/dshx@<v>`
   （两个包都必须是 profile 直接依赖，才能各自作为 bundle 层）；
2. 幂等同步内置 preset 到 `$DSH_HOME/.agent-presets/prefab-anchored-standard`；
3. 幂等同步内置 j-space skill 到 `$DSH_HOME/skills/j-space`。

## 首次请求行为

| 请求 | 工具目录 | 输出预算 | 注入上下文 |
|---|---|---|---|
| 会话创建 | 被内置 anchored 模板预填充（回放已跑通的轨迹） | — | — |
| 请求 #1 | Minimal 对（`bash` + `str_replace_editor`） | adapter 默认（无 cap） | 无（剥离技能目录 / AGENTS.md 等） |
| 请求 #2 起 | Minimal 对 + 发现工具 + 已解锁工具 | 恢复原值 | 恢复 |

- **纯文字首答不会困死**：`promoteOn: either` 下首个 `assistant/message` 即晋升。
- **晋升后目录仍是小的**：完整 25 工具要 `dev_tool_search` 按需解锁，防止被 dump 拉回
  standard-like。
- **子代理同策略**（`includeSubagents: true`）：子代理首请求也是 Minimal 对，自己的首个
  回复/工具调用再晋升。
- **compaction 后回到受控相位**：`compaction/end` 把会话视为「第二次首请求」，回到
  Minimal 对 + 核心工作集，直到边界之后出现新的晋升信号。
- **resume/reload 保持相位**：晋升由持久 session 事件推导。
- 用户主动的 `/` 技能手势不受剥离影响。

## 信任与安全边界

- 默认 **`workspace-write` + `ask`**（全平台）：写入操作会弹审批。
- **`workspace-write` 只限制写入，不限制读取/网络/进程可见性**（Linux 与 Windows 皆然）：
  bwrap/landlock 只把根只读 bind + 工作区可写，不 unshare 网络/进程命名空间。因此会话能读
  任何用户可读的文件、能对外联网——这是双平台的写-only 模型，不是 Windows 特有。
- **Windows 的写边界更弱**（`windows-acl` 部分约束）：
  - workspace 外所有 Everyone 可写对象仍可写（restricting list 必须保留 Everyone）；
  - NTFS 硬链接可把 workspace 内被授权的文件 alias 到外部路径；
  - 可写目录须 caller-owned（WRITE_DAC）——在管理员拥有的 workspace 或网络共享上，
    workspace-write 的每个 shell 写入都可能失败关闭。
- 可信环境可用 `DSHX_SANDBOX_MODE=danger-full-access` 进入完整访问（无审批），
  但**默认永远是 workspace-write + ask**。
- 遥测默认关闭（`session-telemetry-otel` 行禁用，无端点）。
- preset 安装在用户根 `$DSH_HOME/.agent-presets`（trust: user），与 shell 访问同信任级，
  安装前可自行审阅 `preset/` 下的文件。

## preset 与切换

默认 preset = **Prefab Anchored Standard**（id `prefab-anchored-standard`）。`/preset` 仍可切到
官方 standard/code/minimal/cordis。
**`minimal` 仅 Linux 可用**：它的 persistent-bash（PTY bash）在 Windows 上无法创建
（`createProcessInspector` 在 win32 直接 throw，`terminal-bash` 默认 `/bin/bash`），
Windows 上 minimal = 死 shell + `str_replace_editor`。dshX 默认的 prefab-anchored-standard 在
Windows 用 `custom-bash`（Git Bash 路径）+ `str_replace_editor`，无此问题。
优先级：`CC_TUI_PRESET` env > 持久化选择 > roster default。已产生对话的会话不可切换，
空白会话立即生效。

> 从 dshX ≤ 0.2.1 升级：旧的 `$DSH_HOME/.agent-presets/anchored-standard`（旧默认 preset）
> **不会被删除**（dshx 绝不覆盖非目标目录），会作为普通可用 preset 留在 `/preset` 列表里。
> 若之前手工 `/preset` 切到过它，持久化选择会覆盖新默认——想用新的默认请先 `/preset` 切回。

## 从 dsh-TUI 迁移

dshX 的终端前端 `@dshx/tui` 是 dsh-TUI 的分叉，共享 `$DSH_HOME/sessions` 会话库与
`~/.dsh-cc` 偏好目录——从 dsh-TUI 迁移无需搬数据，已有会话和偏好直接可见。
唯一区别是启动页品牌（词标 `dshx`，无 `DEEPSEEK`/`HARNESS` 大字）。
已有 `agent-preset.json`（若切过其它 preset）会覆盖 roster default——想用 prefab-anchored-standard
请先 `/preset` 切回或删除该文件。

## 已知问题

见 [`KNOWN_BUGS.md`](KNOWN_BUGS.md)。

## License

[MIT](LICENSE)。`preset/` 派生自 dsh-anchored-standard 的 prefab 模式
（含 DeepSeek Harness Standard preset 改编），原始版权与 MIT 声明保留在 [`NOTICE`](NOTICE)。