极简编码智能体框架 earthwalker17/MiniDSH

MiniDSH

MiniDSH: an architecture-first, local-first agent harness

Minimal surface. Complete architecture.

MiniDSH 是一个小巧的本地优先编码智能体 harness：它是模型外围的运行时，为模型提供工具、会话和权限。安装之后，把它指向一个仓库，你就能在终端、浏览器或脚本里使用它。它同时也是一份参考架构，篇幅小到坐下来一口气就能读完；还是一场实验，探索如何以架构优先的方式培育 AI 辅助系统，而不是一个功能一个功能地堆。

它把 DeepSeek Harness（DSH）当作教科书来研究——那是 DeepSeek 开源的编码智能体，由插件组合而成，文档写得格外详尽——并追问：一个系统要小到什么程度，还能保住同样的架构特性？它是独立项目：不是 fork，不是产品，也与 DeepSeek 没有隶属关系。

MiniDSH 是什么

三件事：

1. 好用的软件。 一个编码智能体，在你设定的权限下编辑文件、运行命令——哪些文件可以写、哪些操作需要你批准——事后还能审计；进程被杀掉也能活下来，可以从日志恢复或分叉；它管理自己的上下文；能把一个有边界的任务交给子代理，或把视觉检查交给能看图的模型。内置三个服务商（DeepSeek、Anthropic 和 OpenAI），会话可以在对话中途切换模型。
2. 一份参考架构。 一个包，约三万三千行 TypeScript，只有一个运行时依赖：四层结构，依赖规则由 pnpm check 里的脚本强制执行；core 里有十八个服务契约，application 里再加一个；三十四种持久化事件类型；还有一份文档——ARCHITECTURE.md——规定每样新东西该放在哪里。
3. 一场系统工程实验。 一个几乎完全由编码智能体会话构建的项目，能不能在几个月里保住全局架构不散架？办法是让架构显式、可检查、持续被证伪，而不是任由会话慢慢把它发明出来。

核心主张是更少的概念、更强的不变量，而不是更少的代码行或更多的功能。

快速开始

要求：

- Node 24 或更新版本。
- Windows： 用 PowerShell 7（pwsh），绝不用 5.1；找不到 pwsh 会直接点名拒绝。Windows 没有 shell 隔离，所以那里的 shell 命令会被拒绝，直到会话接受这一点（--accept none）——见状态与限制。
- Linux： 想让操作系统限制 shell 命令、而不是逐条审批，就装 bubblewrap（apt install bubblewrap）。macOS 不需要额外装东西。
- 服务商密钥： 默认服务商用 DEEPSEEK_API_KEY，Anthropic 用 ANTHROPIC_API_KEY，OpenAI 用 OPENAI_API_KEY（可选开启的网页搜索用 TAVILY_API_KEY）——放在环境变量里，或写进 ~/.minidsh/credentials.json，格式为 {"DEEPSEEK_API_KEY": "…"}。缺密钥时运行会停下，并告诉你它期望的是哪个密钥。

npm install -g minidsh # or run it without installing: npx minidsh …

minidsh chat --cwd path/to/repo # interactive terminal (--cwd defaults to the current directory)
minidsh web --cwd path/to/repo # the same runtime in a browser; open the one URL it prints
minidsh run "fix the failing test in src/slug.test.mjs" --approve
--approve answers every approval yes (chat, serve and web then never ask);
without it a headless run refuses anything that needs one (on Windows: add
--accept none, which runs shell commands unconfined but keeps file edits fenced)
minidsh run "review this module for unchecked inputs" --provider anthropic --model claude-sonnet-5
minidsh run "summarize this repository" --json # one JSON line per session event on stdout

minidsh sessions list # what is stored, by name
minidsh sessions show <id> --audit # what this session was allowed to do, and what each call did
minidsh sessions verify <id> # can this log be resumed? (exit 0 for ok, interrupted and torn; 1 for
damaged, invalid or a newer format; reads it without resuming it)
minidsh sessions inspect <id> # its lifecycles, authority, and what a resume would append
minidsh resume <id> "continue" # pick a stored session up; fork <id> --at <seq> branches it at a turn boundary
(fork <id> --salvage branches a damaged log from what is still readable)
minidsh config # the effective plugin composition, and which file set each entry
minidsh skills # the skills a session here is offered, and why the others are not
minidsh --help

在终端里：y/N 用来回答审批请求；a（出现时才可用）表示本次会话运行期间，这一类调用都放行（恢复或分叉会话时会重新询问；/grants 列出你已放行的项，/revoke <id> 撤销其中一项）；/sandbox <read-only|workspace-write|danger-full-access>、/ask <ask|never>、/accept <full|none> 和 /preset <name> 用来切换权限；/model [<provider>/]<model> [effort] 切换模型；/compact 压缩上下文；/history 往回翻页；/sessions 列出最近的会话；/cancel 停止正在运行的回合；/exit 退出。回合运行期间输入文字会引导它。
MiniDSH 保存的所有内容都在 ~/.minidsh 下（可用 MINIDSH_HOME 覆盖）：sessions/（每个会话一份 JSONL 日志）、spill/（超大的工具输出，30 天后清理）、attachments/（图片，永不清理）、composition.json、settings.json、credentials.json、skills/（你自己的技能），以及可选的 AGENTS.md，每个会话都会读取它。harness 里没有任何东西会删除日志。

从代码检出开始：先 pnpm install，再 pnpm minidsh …（TypeScript 在 Node 24 上原生运行，所以跑起来不需要构建步骤；pnpm build 只产出 tarball 随附的 dist/），pnpm check 跑完整验证套件。参见 CONTRIBUTING.md，依赖它之前先读 Status and limitations。

你能得到什么

权限由你设定，记录可随时回读。 一次运行默认 workspace-write，审批为 ask：文件写入限制在工作目录内，读取不受限，shell 命令在操作系统能限制的地方加以限制（Linux 上用 bubblewrap，macOS 上用 Seatbelt）。审批界面会显示运行时所说的这次调用将做什么——命令本身，以及它将在何种权限下运行——模型给出的理由放在旁边，而不是取代它。每个会话都会记录启动时的权限，以及之后的每次切换、请求和决定；sessions show --audit 会把这段历史打印出来。

会话能挺过进程终止。 模型看到和做过的一切，都是一份只追加的 JSONL 日志。在一轮对话中途杀掉进程，下一次 resume 会修复日志尾部，并按日志记录的权限继续。一个会话被某个进程占用时，另一个进程无法恢复它。

上下文自己管理自己。 接近模型窗口上限，或服务商以请求过大为由拒绝时，最旧的历史会被替换成摘要（compaction）；被摘要的事件仍留在日志里，模型可以用 history_read 读回来。工作区里的 AGENTS.md（或 CLAUDE.md）作为给模型的指令进入，绝不是给 harness 的权限。

对话中途切换模型。 路由——服务商、模型、推理强度——是会话随时可以更改的持久事实。composition.json 里的 model-roles 条目把某个用途——压缩摘要、委派的子代理——映射到不同的路由。服务商无法满足的选项会被拒绝，绝不会悄悄丢弃。DeepSeek 适配器提供 deepseek-flash（默认，能读图片；已退役的 deepseek-v4-flash 名称按它处理）和纯文本的 deepseek-v4-pro；Anthropic 适配器提供 Claude 5.5、5 和 4 系列；OpenAI 适配器在 Responses API 上提供 GPT-6 和 GPT-5 系列。
有上限的委派，并行执行。 模型可以把一项有边界的任务交给 subagent：子代理有自己的会话和日志，权限在创建时固定为父级或更窄，无法从内部扩大；审批关闭，需要审批的操作一律拒绝。同一条消息里的多个 subagent 调用会同时运行（最多四个，maxParallelToolCalls），全部返回后父级继续。能看见的校验器是第二个 subagent 条目，指向视觉模型，使用 view_image 工具——内置行，默认关闭。

会回报的后台任务。 模型可以用 job_start 启动长命令——开发服务器、慢速测试——继续干活，用 job_output 读输出，用 job_cancel 停止。任务自行结束时，通知会进入会话并唤醒空闲智能体，次数有上限。任务在会话自身的权限下运行，随会话结束而结束。

用真实浏览器检查前端。 装了 Chrome、Edge 或 Chromium 时，模型可以打开页面（它作为任务启动的开发服务器，或工作区文件），按无障碍树读取，点击、输入、截图、运行 JavaScript；每个结果都会说明页面记录了什么或哪里失败。它只能访问 localhost 和工作区自己的文件，限制在浏览器内部强制执行。

挂载后才有的网页搜索。 composition.json 里加一行就启用 web_search（Tavily）。每次查询先询问，列出将离开本机的确切文本、去向和所用凭据；结果是标题、URL 和摘要，外面套一条固定的不可信内容提示。委派出的子代理不提供这项能力。

技能：以数据形式存在的知识。 技能是一个文件夹，内含 SKILL.md（开放的 agentskills.io 格式），放在 ~/.minidsh/skills/、仓库的 .agents/skills/ 或 .claude/skills/ 下。会话会看到一份简短列表，任务合适时模型用普通文件工具读取其中一个：只是建议，从不是权限。自带两个，都只依赖 Node：office（创建、读取、编辑 .docx、.xlsx、.pptx）和 pdf。仓库的技能永远不会替换你自己的。

从磁盘组合。 默认组合是四十一个插件条目（行）的列表；~/.minidsh/composition.json 和 --patch 文件会覆盖它。一行可以禁用、重新配置，或按模块说明符替换；minidsh config 会标出任何被文件改动的权限敏感行。

一个运行时，三种入口。 无头命令行、终端和 Web UI 都是同一个运行时的客户端，说同一种换行分隔的 JSON-RPC 协议（minidsh serve 在 stdio 上暴露它，供你自己的客户端使用）。多个客户端可以观察同一个会话，浏览器标签页关闭不会结束任何东西，只会让仅该标签页能回答的审批被拒绝，并记录在案。

状态与限制

Version 1.2.0 是开发者能安装的最小版本：指向一个仓库，就能每天使用，不必先读架构文档。1.1 加入了持久执行，带冷启动的 sessions verify 和 inspect；每次审批都绑定可信的同意主体；会话能接受宿主交付的强制执行。1.2 加入后台任务、把 OpenAI 作为第三个服务商、可选开启的网页搜索、技能（仅靠 Node 就能处理 Office 和 PDF 文档），以及一个带围栏的浏览器，用来检查前端。这些都在发布前一起评审过。项目很小，只有一位维护者。完整的限制清单见 ARCHITECTURE §13；最可能先碰到的几条如下：

- Windows 没有 shell 限制后端，也不打算加。默认情况下，在那里执行 shell 命令要经过一次审批，并在全新的 shell 里运行（cd 和环境变量改动不会保留）；--accept none 表示会话接受不受限制的 shell，正常执行，文件编辑仍然有围栏，而不是用 danger-full-access——那会连围栏一起撤掉。
- 围栏只管文件影响。受限制的命令照样能访问网络。它的环境会清掉本次部署声明的服务商密钥和 MINIDSH_，别的都不清：你自己设的、长得像凭据的变量归你，会传进 shell。这层清理是纵深防御，不是边界：读取没有围栏，所以凭据文件对愿意去找的命令仍然可读。
- 文件系统围栏会解析符号链接，但检测不到硬链接：工作区里指向外部文件的硬链接会被写穿。受限制的 shell 也会写穿这种链接，因为操作系统限制的是路径；两个后端都不允许它跨工作区边界创建硬链接（在 bubblewrap 和 Seatbelt 下实测过）。
- 只有委派任务并行执行；其他工具调用一律单独、按顺序执行。并行的子任务共享工作区：给它们分不同的文件。子任务是前台执行：发给父任务的消息要等最慢的子任务结束，停掉父任务的回合会停掉所有子任务。后台任务的进程可能比被杀的 MiniDSH 进程活得更久（Windows、macOS，以及 Linux 上不受限制时）：恢复时会报告它已丢失，但不会停掉它。在 Windows 上，任务只能在接受不受限制 shell 的会话里运行（--accept none），而且任务自己的命令结束后仍留在运行的程序，不会随任务一起停掉。
- 网络没有任何限制：网页搜索按每次查询征得同意，也没有 web_fetch。浏览器与互联网隔开，但与 localhost 不隔：它能访问每个本地服务，任何沙箱模式、被委派的子任务都一样。没有会话删除、搜索或重命名；组合变更需要重启。从已安装的 minidsh 加载插件尚未验证（BLUEPRINT §3）。

接下来要做：可继续而不丢失收窄范围的被委派子任务，以及 Windows 上的任务隔离（BLUEPRINT §2）。

它研究的问题

它要解决的失败模式是架构堆积：每个编码智能体会话都交付一簇功能，这些功能能通过测试，功能各自找到局部归宿，而非有原则的归宿，归属变得模糊，之后每个会话都必须重新发现系统为何长成现在这样（PROJECT.md）。

DSH 对这种压力的回应很明确：一个一切皆插件的 harness，构建在 Cordis 之上，其论文点出了让动态组合站得住的两个性质——时间可组合性（组件的效果在移除时可完全回退）和空间可组合性（依赖被声明并对之作出反应）。MiniDSH 向这本教科书提出的问题是：

能保留长期组合、可观测性、验证、多界面演进和可维护性所需架构性质的最小现代智能体 harness 是什么？

「最小」以概念衡量，不以行数衡量。工作规则是一切可演进之物都有接缝——一条组合边界——而并非一切都可演进：一项能力在现实中可能需要被替换、限定作用域、禁用或归属到不同生命周期时，才赢得一条接缝；纯辅助函数或类型则不然。答案是具体的：一个内核，含五种机制、十九条接缝，其余都是普通代码。

架构

这是一份阅读指南；ARCHITECTURE.md 才是契约。阅读时请记住一个词：折叠（fold）是对会话日志的纯推导（模型的历史、当前权限和上下文压力都是折叠）。

分层与依赖规则

src/app/ application assembly and user interfaces: composition, disk config, CLI, terminal, web UI, stdio host
src/capabilities/ providers and consumers over core seams — never import each other, never app src/core/ the spine: the service contracts (Service Definitions) and their default drivers as plugins src/kernel/ composition substrate: Context, plugin lifecycle, services, effects, events src/test-support/ scripted adapter, replay-from-log adapter, composition harness

pnpm check 中的脚本强制依赖方向（ARCHITECTURE §1），并确保 core 在文件层面无环。这四层就是全部拓扑。

子系统及各自职责

内核（src/kernel）用最少的机制实现 Cordis 的两个性质：一棵上下文树，其中注册上下文 = 可见性 = 生命周期；带类型的服务 token；带声明式依赖生命周期的插件；按逆序运行的清理器；以及带 observe 钩子的带类型事件。

Core（src/core）是十八个服务契约（键），每个都是一个 Definition，配一个提供者——core 默认驱动或某项能力——以及其上的消费者。

| 关注点 | 键 | 职责 |
| Facts | sessions、persistence | 只追加的会话日志，以及由它派生的一切；存储日志的读取契约 |
| Cognition | llm、prompt、agents（外加 loop 驱动器，一个插件） | 与服务商无关的模型流和适配器；稳定的提示词分段；智能体注册表；轮次/步骤驱动器 |
| Effects | tools、fs、shell、jobs | 带防护的工具流水线；文件系统契约，写入围栏放在它的服务商内部；受策略约束的 shell；按所有者划分的后台任务 |
| Authority | sandbox、approval、authority-presets、credentials | 当前策略记录及其变更方式；审批及其审计；两者的命名捆绑；仅按名称引用的凭据 |
| Context | compaction、spill、attachments（外加 metering，一个无键的纯折叠） | 摘要旧历史；超大输出；图像；唯一的上下文压力数值 |
| Assembly | settings、invariants | 客户端可以修改的用户默认值；每个事件进入日志前的校验 |

ARCHITECTURE §3 还说明了每个键必须不拥有什么——sandbox 从不拥有执行后端，也不拥有告诉模型的任何一个字；tools 从不拥有策略——这些否定条款正是大部分设计的所在。

能力（src/capabilities）是这些接缝上的服务商与消费者：三个模型适配器、JSONL 持久化、带围栏的文件系统、带隔离后端的 shell、面向模型的工具、压缩、溢出，以及客户端协议。

成立的不变量

- 日志是唯一的真相。 模型的历史是对三种模型可见事件类型的折叠；其余一切只是日志事实或追踪。新的持久状态以新的仅日志事件类型加入，绝不作为用户界面持有的字段。
- 模型可见 ⟺ 已记录。 每次模型请求都恰好是日志派生出的内容——消息历史加上请求设置——运行时检查会在每次调用前验证这一点。
- 每个动作之前先持久化。 每次付费模型调用和每次工具效果之前，都先同步到磁盘。
- 模型提议，策略决定，效果边界执行，日志记录。 执行发生在效果处，绝不在工具闸门处。
- 委派的子代理在无法拓宽的上限下开启；路由是事实；用户界面按页渲染日志，只持有实时的、非持久的状态，例如当前输入和连接。
- 仓库可以说它喜欢自己的代码怎么写，但不能说 harness 被允许做什么。 这里刻意没有按工作区的配置层；组合与设置只存在于 ~/.minidsh 下。

新东西该放哪里

ARCHITECTURE §11 是一张从新东西到归属的表：模型服务商是 capabilities/llm- 下的适配器，面向模型的能力是 capabilities/tool-<x> 下的工具，权限旋钮是带折叠的仅日志事件，无需改代码的能力是 composition.json 中的一行。

MiniDSH 从 DeepSeek Harness 学到了什么

DSH 是个体量大、迭代快的系统（按 2026-10-23 的模块图，共 363 个包）；references/ 是本项目对它的固定快照，ARCHITECTURE §12 记录了下面每处差异的来由。

采纳的思路

- 能力有生命周期和依赖语义。 插件依赖 Service Definitions，绝不依赖具体服务商（packages/README.md）。
- 每个智能体有自己的注册作用域，智能体结束时销毁（2026-07-08 笔记）。
- 面向模型的工具面够小就行。 DSH 的 minimal 预设（minimal.patch.yml）是一个 persona 加一个常驻 shell（2026-10-12 起加上图片读取和压缩）；MiniDSH 默认给 bash/pwsh、str_replace_editor 和 subagent，再加三个 job 工具，装了浏览器的地方再加五个浏览器工具。
- 会话日志是记录本身；模型可见的历史由它派生（session、compaction）。
- 字节放日志旁边，引用放日志里（attachment seam）。
- 隔离是 shell 服务商内部的 spawn 包装器（sandbox、sandbox-local），它的 bubblewrap 配置档逐 flag 照搬。
- 传输用换行分隔的 JSON-RPC，浏览器是客户端，不是第二个智能体（SDK、web client 笔记）。

刻意简化

- 自研内核，不用 Cordis：五个机制、约九百行代码，实现那两条性质。
- 一个包加依赖门禁，不用几百个包。
- 只在需要汇合的地方并行： 一步里的委派同时跑，但父级会等它们结束，没有后台、可续的子代理或智能体团队（DSH：每个子级都是异步激活）；后台 job 属于它的会话，进程死掉就以 lost 关闭，唤醒会话的次数有上限（DSH：丢失的 job 保持打开，唤醒次数无上限）。
- 一套协议，三种传输方式（stdio、进程内、WebSocket），而不是几套组合配置档。
- 两个隔离后端，不是四个： 没有 Landlock（原生启动器），也没有 Windows 后端（DSH 的报告只做到部分强制执行）。
- 自带终端客户端（DSH 在 2026-08-04 的说明里移除了 TUI）。
- 历史召回只在需要时出现： 首次压缩之前 history_read 一直隐藏；DSH 的 session-query 工具会往每个请求里塞 schema，所以改成了按需开启。

差异之处

- 工作区根目录就是可写范围的全部上限，而 DSH 的 workspace-write 还会额外放行临时目录和运维人员指定的其他根目录。
- 宿主能否隔离，在创建智能体时就探测并记录，哪怕只有一个后端也照做；「没有后端」是一种如实上报的状态，会话可以带着这条记录继续跑。
- 委派出去的子代理，起始权限就是硬上限；同意针对的是运行时对这次调用的记录，而 DSH 展示的是模型自己写的文字；模型角色可以把某一类调用从会话记录的路径上引开；已连客户端都答不了的审批直接拒绝，不会一直挂着。

未实现

PTC（DSH 的编程式工具调用）、模型编写的动态包、MCP 客户端、会话删除和按用户区分身份：BLUEPRINT §2 列出了这些，并把桌面启动器排进了路线。

架构先行的实验

几乎所有代码都由编码智能体的开发会话写成，遵循一份简短的章程（CLAUDE.md），第一条规则是：架构定义会话；会话不定义架构。

每项能力先有归属，再有代码。 会话在实现一项能力之前，先说明它属于哪一层、接缝在哪、拥有什么状态、生命周期如何。第十一次会话引入操作系统隔离时，答案是「不需要新地方」：shell 契约从第三次会话起就已经写明了。

证伪架构，然后修好它。 每完成一组架构改动就做一次加固检查，找出文档里写了、代码里却不成立的不变量。确实找出了几处：写了却没实现的不变量；一条崩溃修复路径恢复出来的对话，形状会被各服务商的 API 拒绝；一个网络客户端能把提示词注入正在运行的委派子代理；一条写进文档的安全声明被实验推翻。这些连同实测结果都记在 BLUEPRINT.md §4。

它教会我们：文档漂移就是缺陷，所以文档有体积预算，由门禁强制执行；没有门禁的约定守不住，所以依赖规则写成了脚本；验证要看世界本身，而不是智能体对世界的说法。十七次会话、两个版本之后，新贡献者仍然能只靠一份文档回答：一项能力该归到哪里、每一层拥有什么、真相存在哪里。

验证

pnpm check 包含类型检查、lint、依赖门禁、文档门禁和约 1,400 个测试，在 CI 上跑 Ubuntu、macOS 和 Windows 三条腿，每条腿跑完还要对打包出的 tarball 做一次安装冒烟。测试挂载真实组合，模型要么按脚本走，要么从录制的日志回放；每次运行都会修复并回放两份真实日志，其中一份来自 minidsh@1.0.0。

十三个实时端到端测试——arcs*——在发版前对着真实服务商跑，跑在一个工作流里：发版流程会等它（Linux、macOS），也可以手动跑（Windows、Linux）。每个测试都断言一个真实存在的世界：一次在工具调用中途被杀掉的任务，由第二个进程修复，它的日志无需密钥即可回放；一次工作区之外的编辑被拒绝，文件不存在；一次上下文预算越界触发压缩和溢出；一个会话在对话中途切换服务商；一个被委派的子代理的升级请求被它的 pin 拒绝；一条消息里委派的三个子代理同时运行；Web 客户端在两个客户端之间共享一个会话，并通过网络接受一次同意；一个任务的结束唤醒空闲的智能体；一个技能把 PDF 和 CSV 变成 Word 报告；浏览器在修复它的编辑之前就看到一个运行时 bug。macOS 那条腿跑在 Seatbelt 下，是这个项目对该平台唯一的证据。

文档与帮助

| ARCHITECTURE.md | 契约：分层、归属、日志、权限、用户界面、新东西放哪、限制 |
| PROJECT.md | 论点、定位与研究背景 |
| BLUEPRINT.md | 接下来做什么、开放问题，以及按会话的开发记录 |
| CLAUDE.md | 构建会话运行时遵守的工作章程 |
| CONTRIBUTING.md · SECURITY.md · CHANGELOG.md | 如何贡献、安全边界在哪、改了什么 |

获取帮助。 Bug：用 bug 报告 issue 模板。设计问题，或者某项能力在 ARCHITECTURE §11 表里没有对应行：用架构问题模板。漏洞：私下报告，方式见 SECURITY.md。

许可与署名

MIT——见 LICENSE。MiniDSH 是一个独立的教育与工程项目，灵感来自 DeepSeek Harness（MIT，© DeepSeek）。它不是 DeepSeek 官方项目，与 DeepSeek 无隶属关系，也未获其背书。代码独立实现；凡改编了契约、配置档或措辞之处，均在相邻注释中注明来源，并在 NOTICE 中汇总。