便携终端编程助手 LouisYang841/dsh-mini

dsh-mini

CI
version
stars
license
node
runtime deps
Termux

DeepSeek Harness 核心的便携引擎 + 一个能在手机上干活的终端编程 Agent CLI。 我们不是 fork：以 npm 消费者身份把 pi（壳）和 DSH（引擎）拼在一起，本仓库真正自研的是五条缝、兼容层和文档——拼装与解耦。

这是什么

- 引擎原样来自 DSH 官方包：事件溯源会话、turn/step 状态机、工具调度、压缩、skills——@deepseek-ai/dsh- 锁版直用，一行不改
- 壳来自 pi 生态：真 @earendil-works/pi-tui 框架 + 社区 @openguardrails/dsh-tui 全屏界面（默认）
- 我们能替换的只有缝：provider 换、文件系统换、持久化换、UI 换，引擎不动

依赖砍了多少

| | 官方 DSH | dsh-mini |
| 构建期直接依赖 | — | 39 个（npm 闭包 168 包/161MB，见 REFLECTION.md） |
| 默认 profile 插件 | ~90 个 | 31 个（全纯 JS，零原生模块） |
| 运行时 npm 依赖 | 全家桶 | 0 个（产物自包含） |
| 安装体积 | 359MB node_modules | 7.7MB 单文件（约 47 倍缩减） |
| 便携引擎 | — | 419KB，零 Node 内置依赖 |

数字来源：官方安装的 node_modules 实测 359MB；我们只保留直接 import 的 39 个构建期包（全部 devDependencies，npm install --omit=dev 装 0 个）；完整砍依赖账本见 REFLECTION.md。

为什么对 Termux 友好

- 推荐 Node ≥ 22.15——zstd 内置于 node:zlib，无原生模块、无编译；更旧 Node 可运行但 session 会退化为未压缩 JSONL
- 一条命令安装：curl | sh，下载单个 7.7MB 自包含文件 + 26 行 launcher，npm 都不需要
- bash 工具直接打手机真实文件系统（OnePlus 15 / Termux 实测：ls、建文件、跑脚本）
- 为 Android 修过的真坑（skill 里有记录）：SELinux 禁硬链接 → 持久化降级为 rename 原子发布；exit 与 200ms 写批的时序 → 退出前强制 flush
- 数据和密钥都在手机本地：会话 JSONL 在 ~/.dsh-mini/sessions；密钥只从环境变量读取（可选持久化到 0600 权限的 ~/.dsh-mini/env 或 ./.env），不出设备
- 三套界面按环境自适应：默认全屏 TUI / DSH_TUI=basic 简易壳 / DSH_PLAIN=1 纯文本（管道与脚本友好）

pi 和 DSH 是怎么低耦合焊在一起的

五条缝（完整契约见 ARCHITECTURE.md）：

1. LLM 适配器——DSH 官方 DeepSeek 直连 + 官方 pi-ai 多 provider（OpenAI/Anthropic/OpenRouter，环境变量存在即启用）+ 自写 Gemini 作为缝的参考实现
2. 文件系统服务——官方 dsh-fs-local（koffi 仅 Windows 惰性加载，Linux/Termux 等效纯包）；node-fs.js 是非 Node 宿主的契约参考
3. 持久化后端——官方 JSONL 后端 + 我们的 shims/fs-promises.js 兼容层（Android 专属修复）
4. Node API 面 shims——纯 JS 重实现 + "大声失败"桩：核心一旦越界立刻报错
5. 引擎面 polyfills——QuickJS/V8 等引擎差异归一化（同 bundle 在 Node 与 QuickJS 上产生字节级一致的事件序列）

这个 repo 如何支持再拼装与扩展

- ARCHITECTURE.md：五缝 + 六步改装配方——把引擎装进任何 harness/agent app
- DECISIONS.md：ADR-0001（为什么组装而不是 fork 官方）+ ADR-0002（砍大头留小头判据）
- skills/：近 50 条实踩坑（cordis 语义、引擎差异、Android、配额、发布），agent 可通过内置 skill 工具现场加载
- conformance 门：假 provider 回放 + 字节级基线（run.sh）——上游升版、引擎改动全有客观验收，且零 API 配额
- AGENTS.md：给任何 coding agent（包括 dsh-mini 自己）的工程规矩

快速开始

任意 Node ≥ 22.15 机器（Termux 先 pkg install nodejs）
curl -fsSL https://github.com/LouisYang841/dsh-mini/raw/main/scripts/install.sh | sh
dsh-mini

首次运行无密钥会交互询问 provider 并持久化（~/.dsh-mini/env）。DeepSeek 默认；/provider 切换，/model 换型号，--resume/--sessions 回访会话。

新会话默认 minimal 模式：system prompt 固定为官方 Minimal 的完整 persona，模型只看到 bash + str_replace_editor。用 --mode standard、DSH_MODE=standard 或会话内 /mode standard 切到完整工具目录；模式作为 durable session event 保存，resume 时自动恢复。/mode standard --global 会把新默认值写进 ~/.dsh-mini/settings.json，之后每次启动都生效。

持久化配置

两层 JSON 设置（仿 pi 的 settings 契约，去掉 watcher/lockfile 依赖）：

1. ~/.dsh-mini/settings.json — 用户默认值（首次 /mode --global 或 /config key value 时以 0600 创建）
2. /.dsh-mini/settings.json — 当前项目覆盖值

优先级：CLI flag > 环境变量 > 项目设置 > 用户设置 > 内置默认值。支持的字段：

| 字段 | 默认 | 说明 |
| defaultMode | minimal | 新会话模式（minimal / standard） |
| defaultProvider | 自动 | 启动默认 provider（如 deepseek-official、google、openai） |
| defaultModel | provider 默认 | 启动默认模型 |
| reasoningEffort | provider 默认 | 推理强度（以 /reasoning 列出当前模型支持的 id，如 off/high/max；env：DSH_REASONING_EFFORT） |
| sessionsDir | ~/.dsh-mini/sessions | 会话存储目录，支持 ~/... |
| compactionRatio | 0.8 | 自动压缩触发比例（>0 且 ≤1） |
| titles | false | 是否给会话生成标题（静默消耗一次 LLM 调用） |
| workspaceInstructions | true | 是否注入工作目录的 AGENTS.md |
| showBanner | true | 是否显示启动 banner |
| renderer | auto | auto（默认 cc-tui）/ cc / basic / plain |

会话内 /config 查看当前有效值及来源；/config 写入用户设置。会话内 /reasoning [id] 查看/切换推理强度，/reasoning --global 把新默认值写进用户设置（/reasoning default --global 清除并回到 provider 默认）。凭据不进 settings —— API key 只从环境变量或 ~/.dsh-mini/env 读取。

自定义工具（toolpackages）

Agent 或用户可以给 dsh-mini 写自己的工具。扫描目录是 /tools/ 和 ~/.dsh-mini/tools/：每个工具由 .tool.json manifest 加一个可执行文件组成。manifest 声明 name / description / parameters / output / command；执行时 dsh-mini spawn 该命令，JSON 参数走 stdin，结果从 stdout 读回 JSON。写完后 /tools reload 热加载，完整工具在 standard 模式可见。完整契约见 docs/toolpackages.md，agent 开发时可加载 skills/toolpkg-authoring/SKILL.md。

许可证

自身代码 MIT；全部拼装组件的归属声明见 THIRD_PARTY_LICENSES.md（随 release 分发）。

相关项目 / Related

- DeepSeek Harness — 本项目的引擎来源（官方 255 包全家桶 → 我们砍到 39 个构建期包、0 运行时依赖）
- pi — 壳与 provider 生态来源（pi-tui / pi-ai）
- @openguardrails/dsh-tui — 默认全屏 TUI（同为 pi-tui 系，MIT）
- dsh-cc-tui — 另一社区 TUI（BSD-3，仅作参考未打包）

以下为英文文档（架构细节、开发指南）。

This directory is the spike that answers one question: can the DeepSeek
Harness core be pulled from npm, run as a self-contained engine behind a
compatibility layer, and be embedded in other hosts?

Two deliverables:
1. 引擎探针（bundle.mjs、run.sh）

真正的 DSH 核心——cordis + AgentRegistry + SessionStore + SystemPrompt
+ ToolRuntime + AgentLoop（事件溯源的轮次/步骤状态机）——被打包成一个与引擎无关的单一文件（约 419 KB，零 Node 内置依赖），包含：

- shims/——用纯 JS 重新实现的 Node 内置接口表面（path、 util、crypto、async_hooks/AsyncLocalStorage 通过打补丁的 promise 链实现，……）。fs/sqlite/child_process 是显式失败的桩：如果核心一旦触碰它们，就会大声报错而不是行为异常。
- polyfills.js——引擎 polyfill（AbortController、structuredClone、 Promise.withResolvers、Symbol.dispose，……）外加一处引擎差异归一化：QuickJS 将原生函数的 Function.prototype.toString 渲染为多行，而 dsh-tools 会按 V8 的单行形式做字符串比较。

关键设计选择：esbuild --target=es2016 将 async/await 降级为生成器，使每个 promise 续体都经过 JS 可见的 Promise.prototype.then ——这是 AsyncLocalStorage 前奏在 QuickJS 上工作所必需的，因为 QuickJS 的 await 是 C 内部实现。

验证：5 个脚本化场景（纯文本 / 工具往返 / 并行+独占工具调度 / 最大 token 截断 / 轮次中途引导）通过一个假 provider 回放。Node 和 QuickJS 产生逐字节相同的事件轨迹（114 个事件），在 baseline.node.json + baseline.sha256 中做哈希锚定。未来每一次 @deepseek-ai/ 升级都必须通过 ./run.sh。

2. dsh-mini CLI（cli/）

同一个 DSH 核心，在 Node 上作为真正的交互式编码代理：

node cli/cli.mjs [model]

- Provider：通过 AI Studio SSE 端点接入 Google Gemini，实现为一个 dsh-llm 的 LlmAdapter（cli/gemini-adapter.js）——证明第三方 provider 可以通过适配器接缝接入核心。包含 Gemini-3 的 thoughtSignature 回显怪癖（签名在两个方向上都是 functionCall 的部件级同级项）。
- 工具：真正的 dsh-tool-fs 工具（read/write/edit/list）+ dsh-tool-todo，由官方 dsh-fs-local 服务支撑（cli/node-fs.js 仍是非 Node 的契约参考）。
- 持久化：真正的 DSH JSONL 后端（dsh-session-persistence-jsonl， zstd，按 cwd 布局）；会话在重启后存活，--resume 恢复， --sessions 列出。已验证跨进程记忆（密语测试）。
- 模式：minimal 是新会话的默认模式（精确的 Minimal 人格 + 仅 bash/str_replace_editor）；standard 保留完整的 dsh-mini 目录。通过 --mode 、DSH_MODE、/mode 或 defaultMode 设置选择；当前活动模式被记录为持久会话事件，并在恢复时还原。/mode --global 将新的默认值持久化到 ~/.dsh-mini/settings.json。
- 设置：~/.dsh-mini/settings.json（用户）合并到 ./.dsh-mini/settings.json（项目）之下，然后是环境变量，然后是 CLI 标志。
字段：defaultMode、defaultProvider、defaultModel， reasoningEffort、sessionsDir、compactionRatio、titles、 workspaceInstructions、showBanner、renderer。/config 显示有效值，/config 保存到用户文件。
推理强度按模型通过 /reasoning [id] 选择（/reasoning --global 持久化默认值）；CLI/环境变量默认值为 --reasoning-effort / DSH_REASONING_EFFORT。API 密钥不放在设置中——它们存在于环境变量或 ~/.dsh-mini/env 中。
- 工具包：扫描 /tools 和 ~/.dsh-mini/tools 中的 .tool.json 清单。每个工具以进程外方式运行，通过 stdin/stdout 传递 JSON； /tools reload 无需重启即可重新扫描。
- REPL：/clear、/model 、/mode [id [--global]]、/reasoning [id [--global]]、
/config [key [value]]、/sessions、/tools [reload]、/exit；来自
会话 firehose 的实时事件渲染；带实时 token 使用量的 ANSI 状态栏。

命令： cli/cli-build.sh # build cli/cli.mjs (Node profile) ./run.sh # engine conformance (Node + QuickJS, diff vs baseline) ./build.sh # portable engine bundle only
node cli/cli.mjs [model] [--mode ] [--reasoning-effort ] [--resume ] [--sessions] # settings files + env configure the rest

提供商。 DeepSeek 是默认项（通过 DSH 自有的 dsh-llm-deepseek 适配器走 deepseek-official 路由；DEEPSEEK_API_KEY），Google Gemini 通过 GEMINI_API_KEY。pi 提供商生态共用一个适配器（dsh-llm-pi-ai）：设置 OPENAI_API_KEY / ANTHROPIC_API_KEY / OPENROUTER_API_KEY，openai / anthropic / openrouter 路由会自动启用（外加 pi-ai 的 deepseek 路由）。使用 /provider 切换提供商，使用 /model 切换模型。
首次运行且任何地方都没有密钥时会启动交互式设置：选择一个提供商，粘贴密钥——它会被持久化到 ~/.dsh-mini/env（回退到 ./.env，两者都被 gitignore）并在下次启动时自动加载。
工作区指令：如果工作目录包含 AGENTS.md，它会被注入到系统提示中（DSH_NO_AGENTS=1 或 workspaceInstructions: false 可禁用）。

架构（引擎/宿主接缝、改造配方、升级策略）： ARCHITECTURE.md。陷阱与宿主集成清单： skills/dsh-core-embedding/SKILL.md。

安装（一行命令）

curl -fsSL https://github.com/LouisYang841/dsh-mini/raw/main/scripts/install.sh | sh

将 dsh-mini 安装为命令（包安装到 ~/.dsh-mini/，启动器放入 PATH）。zstd 会话需要 Node >= 22.15；较旧的 Node 可使用未压缩的 JSONL。在 Termux 上：先执行 pkg install nodejs。

Termux（Android）

发布产物完全自包含——无需 npm install（也已在 OnePlus 15 上实机验证：设置 → bash 工具驱动手机的真实文件系统 → 会话持久化，全部在设备上完成）：

渲染器模式：在真实终端上，全屏 pi-tui shell （@openguardrails/dsh-tui，Claude-Code 风格）是默认模式；
DSH_TUI=basic 获得最小化的聊天流式外壳，DSH_PLAIN=1（或管道）
获得用于脚本/CI 的纯行模式。

pkg install nodejs # Node >= 22.15 (zstd is bundled in node:zlib)
curl -LO https://github.com/LouisYang841/dsh-mini/releases/latest/download/dsh-mini.mjs
export GEMINI_API_KEY=""
node dsh-mini.mjs # pi-tui shell; the bash tool hits Termux's real bash

会话持久化在 ~/.dsh-mini/sessions 下（zstd JSONL；在 Node = 22.15 运行它。无需 npm install，无需 DSH 包树。
2. 仅引擎：将 dsh-engine.mjs + shims/ + polyfills.js（全部为普通文件）放入你自己的框架中；main.js 是启动参考， baseline.node.json 是一致性门禁。同样无需 npm install。
3. 源码构建：git clone + npm install（仅构建时 devDependencies）
+ bash cli/cli-build.sh。加上 --omit=dev 则完全不安装任何东西；在 Termux 上加上 --ignore-scripts。

CI

.github/workflows/conformance.yml 在每次推送时运行：npm install → 单元测试 → 可移植包构建 → 一致性门禁（与 baseline.node.json 逐字节一致） → CLI 构建。

路线图

带有来源决策（pi-native → DSH minimal → 自写胶水代码）的功能审计、优先级，以及一份有意跳过清单：ROADMAP.md。