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

MiniDSH

npm
check
license: MIT
node ≥ 24

MiniDSH：一个架构优先、本地优先的智能体运行框架

极简表面。完整架构。

MiniDSH 是一个小巧、本地优先的编码智能体运行框架：它是模型周围的运行时，为模型提供工具、会话和权限。安装它，将其指向一个代码仓库，然后从终端、浏览器或脚本中使用它。它同时也是一份小到可以坐下来一口气读完的参考架构，以及一次以架构优先而非逐功能演进的方式来构建 AI 辅助系统的实验。

它以 DeepSeek Harness（DSH）——DeepSeek 开源的、由插件组合而成且文档异常完善的编码智能体——为教科书，追问一个系统在保持相同架构特性的前提下能有多小。这是一个独立的教育与工程项目：不是分支，不是产品，也与 DeepSeek 无关联，亦未获其背书。

目录： 它是什么 · 快速开始 · 你能得到什么 · 状态与局限 · 它所探究的问题 · 架构 · 它从 DeepSeek Harness 学到了什么 · 架构优先实验 · 验证 · 文档与帮助 · 许可证

MiniDSH 是什么

三件事：

1. 有用的软件。 一个编码智能体，在你设定的权限下编辑文件并运行命令——哪些文件可以写入，哪些操作需要你的批准——并且事后可以审计；它能在进程被杀后存活，并可从日志中恢复或分叉；它管理自己的上下文；它可以将一个有界的任务交给子智能体，或者在插入视觉插件后，将视觉检查交给一个能看见的模型。内置两个提供方（DeepSeek 和 Anthropic），一个会话可以在对话中途切换模型。
2. 一份参考架构。 单个包中约两万行 TypeScript，只有一个运行时依赖：四层结构，其依赖规则由 pnpm check 中的脚本强制执行；核心层有十七个服务契约，应用层另有一个，每个都有明确的归属；二十七种持久化事件类型；以及一份文档——ARCHITECTURE.md——它规定了每一个新东西应该放在哪里。
3. 一项系统工程实验。 一个几乎完全由编码智能体会话构建的项目，能否在数月内保持全局架构完好，方法是让架构显式、可检查并持续被证伪，而不是让各个会话逐渐自行发明它。

其论点是更少的概念和更强的不变量，而不是更少的代码行或更多的功能。

快速开始

要求：

- Node 24 或更新版本。
- Windows： PowerShell 7（pwsh）。shell 工具只运行 pwsh，当它缺失时会大声拒绝并指出补救方法；它绝不会回退到 PowerShell 5.1。Windows 没有 shell 隔离后端，因此那里的每条 shell 命令都需要一次批准（见下文）。
- Linux： 如果你希望 shell 命令由操作系统隔离，而不是逐条批准，则需要 bubblewrap（apt install bubblewrap）。macOS 不需要额外安装任何东西。
- 一个提供商密钥： 默认提供商使用 DEEPSEEK_API_KEY，Anthropic 使用 ANTHROPIC_API_KEY——放在环境变量中，或放在 ~/.minidsh/credentials.json 中，格式为 {"DEEPSEEK_API_KEY": "…"}。日志中只会记录密钥的名称；没有密钥的运行会停止，并指出它期望的密钥。

npm install -g minidsh            # 或者不安装直接运行：npx minidsh …

minidsh chat --cwd path/to/repo   # 交互式终端（--cwd 默认为当前目录）
minidsh web  --cwd path/to/repo   # 在浏览器中运行同一个运行时；打开它打印出的那个 URL
minidsh run "fix the failing test in src/slug.test.mjs" --approve
--approve 对所有批准请求都回答 yes；没有它时，无头运行
会拒绝任何需要批准的操作——在 Windows 上，那就是每条 shell 命令
minidsh run "review this module for unchecked inputs" --provider anthropic --model claude-sonnet-5
minidsh run "summarize this repository" --json     # 在 stdout 上为每个会话事件输出一行 JSON

minidsh sessions list                     # 已存储的内容，按名称列出
minidsh sessions show  --audit        # 此会话被允许做什么，以及何时允许
minidsh resume  "continue"            # 恢复一个已存储的会话；fork  --at  会在某个事件编号处分叉它
minidsh config                            # 生效的插件组合，以及每个条目由哪个文件设置
minidsh --help

在终端中：y/N 回答批准请求；/sandbox 、/ask  和 /preset  切换权限；/model [/] [effort] 切换模型；/compact 压缩上下文；/history 向后翻页；/sessions 列出最近的会话（minidsh sessions list 有全部会话）；/cancel 停止正在运行的回合；/exit 退出。在回合运行期间输入可以引导它。
MiniDSH 保存的所有内容都位于 ~/.minidsh 下（可通过 MINIDSH_HOME 覆盖）：sessions/（每个会话一个 JSONL 日志）、spill/（过大的工具输出，30 天后清理）、attachments/（图片，永不清理）、composition.json、settings.json（运行时也会写入的唯一文件，通过线上的 settings 方法）、credentials.json，以及一个可选的 AGENTS.md，每个会话都会读取它。会话在记录其第一条提示词的那一刻就被存储；harness 中没有任何东西会删除日志。

从代码检出开始：pnpm install，然后 pnpm minidsh …（TypeScript 在 Node 24 上原生运行，因此运行它无需构建步骤；pnpm build 只生成 tarball 所包含的 dist/），以及用于整个验证套件的 pnpm check。参见 CONTRIBUTING.md，并在依赖它之前阅读状态与限制。

你能得到什么

由你设定的权限，以及一份你可以读回的记录。 一次运行默认采用 workspace-write，审批为 ask：文件写入被限制在工作目录内，读取不受限制，shell 命令在操作系统能够限制的地方受到限制（Linux 上使用 bubblewrap，macOS 上使用 Seatbelt；harness 会在声称后端可用之前先探测它确实可用）。在受限主机上，普通任务无需任何人做出决定。模式有 read-only、workspace-write 和 danger-full-access，后者会为整个会话解除限制；第一个审批提示会说明这一点。审批可以在终端中、在浏览器中，或通过无头运行时的 --approve 来回答。每个会话都会记录它启动时所依据的权限，以及之后的每一次切换、请求和决定；sessions show --audit 会将该历史打印回来。限制未覆盖的内容见状态与限制。

能在其进程结束后存活的会话。 模型被展示和执行的一切都是一个仅追加的 JSONL 日志。在回合中途终止进程，下一次 resume 会修复尾部，并在日志所记录的权限下继续；fork  --at  可在任意事件处分支一个会话。第二个进程无法恢复另一个进程持有的会话：租约会在追加任何字节之前拒绝它。由于模型的历史记录派生自日志，存储的日志可以在没有 API 密钥的情况下重放，作为对写入它的会话的一种测试。

自我管理的上下文。 日志上方的计量器会跟踪压力（终端显示 [ctx 34% · 12.4k/32k]）。接近模型的窗口时，或当提供方以请求过大为由拒绝时，最旧的历史记录会被摘要替换（压缩）；被摘要的事件仍留在日志中，模型可以在 token 预算内通过 history_read 将它们读回。过大的工具输出会连同摘录和路径一起溢出到磁盘。工作区中的 AGENTS.md（或 CLAUDE.md）会作为对模型的指令进入，而绝不是 harness 的权限。
在对话中途切换模型。 路由——提供商、模型、推理强度——是会话可在任意时刻更改的持久事实（--provider/--model、/model anthropic/claude-sonnet-5，或通过协议使用 session/model），日志会记录它。composition.json 中的 model-roles 条目将一个用途——压缩摘要、被委派的子级——映射到不同的路由。DeepSeek 适配器提供 deepseek-v4-flash（默认）、deepseek-v4-pro 和一个视觉模型；Anthropic 适配器提供 Claude 5 和 4 系列，并带有针对实时 API 测量的各模型事实。提供商无法满足的选项会被拒绝，绝不会被静默丢弃。

带上限的委派。 模型可以将一个有界任务交给 subagent：一个拥有自己的会话和日志的子级，其权限固定为其父级的权限或更窄，且无法从内部扩大；审批处于关闭状态，因此需要审批的操作会被拒绝。一个能看见的验证器是第二个 subagent 条目，指向一个视觉模型，使用 view_image 工具——一个默认关闭、从 composition.json 启用的内置插件。

从磁盘组合。 默认组合是三十五个插件条目（行）的列表；~/.minidsh/composition.json 和 --patch 文件会覆盖它，每一行都记得是哪个文件更改了它。一行可以被禁用、重新配置或按模块说明符替换；每个会话都会记录它运行时所依据的组合；minidsh config 显示结果，并标记出任何被文件更改的权限敏感行。

一个运行时，三种入口。 无头 CLI、终端和浏览器是同一个运行时的客户端，使用同一种换行分隔的 JSON-RPC 协议（minidsh serve 在 stdio 上为你自己的客户端暴露它）。它们一次一页地显示会话日志，自身不保留任何状态；多个客户端可以观看同一个会话，浏览器标签页关闭不会结束任何东西。

状态与限制

版本 1.0.0 是开发者可以安装、指向一个仓库并每天使用而无需阅读架构的最小发布版。这是一个只有一位维护者的小项目。完整的限制登记见 ARCHITECTURE §13；最可能首先重要的几条：

- Windows 没有 shell 隔离后端，也不会获得一个。那里的每条 shell 命令都需要审批，而没有 --approve 的无头运行根本无法运行 shell。
- 隔离仅约束文件影响。被隔离的命令可以访问网络并读取 harness 的环境，包括提供商密钥。
- 文件系统围栏会解析符号链接，但无法检测硬链接：工作区内指向外部文件的硬链接会被写入。在受隔离的主机上，shell 不受影响，因为操作系统约束了整个进程。
- 工具执行是顺序的，被委派的子级是前台运行；没有后台作业。
- 无会话删除、搜索或重命名；无 OpenAI 适配器；组合变更需要重启。从已安装的 minidsh 加载插件尚未得到验证：它无法导入 MiniDSH 自身的模块，必须自带 package.json 和依赖（BLUEPRINT §3）。

接下来的内容由 BLUEPRINT §3 中的开放问题决定，而非由功能列表决定。

它研究的问题

用 AI 编码代理构建软件的一种常见方式是：发明一系列功能，并把一组功能交给每个会话。每个会话交付通过其测试的东西；数月累积下来的是架构堆积：功能获得了局部的归属而非有原则的归属，所有权变得模糊，之后每个会话都必须重新发现系统为何是现在这个样子。PROJECT.md 描述了这种失败模式。

DSH 对这种压力的回应是明确的：一个基于 Cordis 构建的一切皆插件的框架，其论文指出了使动态组合成立的两个属性——时间可组合性（组件的效果在移除时可被完全还原）和空间可组合性（依赖被声明并对其作出反应）。MiniDSH 向这本教科书提出的问题是：

仍然保留长期组合、可观测性、验证、多界面演进和可维护性所需的架构属性的最小现代代理框架是什么？

“最小”以概念而非行数来衡量。工作规则是一切可演进之物皆有接缝——一个组合边界——但并非一切皆可演进：一项能力只有在现实中可能需要被替换、限定作用域、禁用或由不同生命周期拥有时，才配拥有一个接缝；纯辅助函数或类型则不需要。动态组合应当停止于何处是核心研究问题，而答案是具体的：一个包含五种机制、十八个接缝（服务契约，在代码中称为 Definitions）的内核，其余皆为普通代码。

架构

这是一份阅读指南；ARCHITECTURE.md 是契约，代码注释引用其章节编号。阅读时需记住一个词：fold 是对会话日志的纯推导（模型的历史、当前权限和上下文压力都是 fold）。

分层与依赖规则

src/app/            应用装配与用户界面：组合、磁盘配置、CLI、终端、浏览器、stdio 宿主
src/capabilities/   基于核心接缝的提供者与消费者——绝不互相导入，绝不导入 app
src/core/           主干：服务契约（Service Definitions）及其作为插件的默认驱动
src/kernel/         组合基底：Context、插件生命周期、服务、效果、事件
src/test-support/   脚本化适配器、从日志重放的适配器、组合测试框架

| 从 | 可导入 |
|---|---|
| kernel | 内部无任何依赖 |
| core/ | kernel、其他 core 契约——但 core/loop 除外，它仅由 app 导入 |
| capabilities/ | 仅 kernel、core 的 Definition；提供者绝不导入另一个提供者或消费者 |
| app | 任意 |

pnpm check 中的一个脚本强制执行该表，确保事件负载通过 matches(event, KIND) 读取而绝不进行类型转换，并确保 core 在文件级别无环。这四个层就是全部拓扑；一个 capability 是一个目录，而不是一个包。

子系统及其各自拥有的内容

内核（src/kernel，约九百行）是支撑两个 Cordis 属性的最小机制集合：一个上下文树，其中注册上下文 = 可见性 = 生命周期；类型化服务令牌；具有声明式依赖生命周期的插件；按逆序运行的清理器；以及类型化事件，其上有一个 observe 钩子用于检查运行时不变式。没有加载器、热重载、隔离、代理或混入。

核心（src/core）是十七个服务契约（键），每个都是一个 Definition，拥有一个提供者——一个核心默认驱动或一个 capability——以及其上的消费者；第十八个，即组合句柄，属于应用程序。

| 关注点 | 键 | 拥有 |
|---|---|---|
| 事实 | sessions、persistence | 仅追加的会话日志及其派生的一切；存储日志的读取契约 |
| 认知 | llm、prompt、agents（+ loop 驱动，一个插件） | 提供者中立的模型流和适配器；稳定的提示段；代理注册表；回合/步骤驱动 |
| 效果 | tools、fs、shell | 受保护的工具管道；文件系统契约，写围栏位于其提供者内部；策略绑定的 shell |
| 权威 | sandbox、approval、presets、credentials | 当前策略记录及其变更方式；审批及其审计；两者的命名捆绑；仅按名称的凭据 |
| 上下文 | compaction、spill、attachments（+ 计量，一个无键的纯折叠） | 总结旧历史；超大输出；图像；唯一的上下文压力数值 |
| 组装 | settings、invariants | 客户端可更改的用户默认值；在进入日志之前对每个事件的验证 |

ARCHITECTURE §3 还说明了每个键不得拥有的内容——sandbox 从不拥有执行后端或任何告知模型的内容，tools 从不拥有策略——而这些否定条款正是大部分设计所在之处。
能力（src/capabilities，二十五个目录）是这些接缝之上的提供者和消费者：两个模型适配器、JSONL 持久化、带其围栏的文件系统、带其隔离后端的 shell、面向模型的工具（bash/pwsh、str_replace_editor、subagent、history_read、view_image）、压缩、溢出以及客户端协议。应用（src/app）是装配和用户界面：作为三十五条类型化行的默认组合、磁盘层、CLI、终端客户端和浏览器宿主。用户界面从事件流渲染，不持有任何权威状态。

成立的不变量

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

新事物该放在哪里

ARCHITECTURE §11 是一张从新事物到归属的表：模型提供者是 capabilities/llm- 下的适配器，面向模型的能力是 capabilities/tool- 下的工具，权威旋钮是带折叠的仅日志事件，无需代码编辑的能力是 composition.json 中的一行。表中没有对应行的变更，是一个需要先解决的架构问题，然后才是实现任务。

MiniDSH 从 DeepSeek Harness 学到了什么
MiniDSH 复现的是 DSH 的原则，而非其实现。DeepSeek Harness 是一个庞大且快速演进的系统——按其自身的模块图所述，截至 2026-09-09 共有 50 个组、267 个包——其书面架构异常出色：一份架构文档、每个子系统一页、一份包层级，以及记录每个边界存在原因的带日期笔记。凡有契约、配置档或措辞被改编之处，相邻注释都会说明（NOTICE）。以下链接均于 2026-09-09 核验。

采纳的理念

- 能力具有生命周期与依赖语义。 DSH 的规则是插件依赖 Service Definitions，而绝不依赖具体 provider（packages/README.md），这演变为三角色接缝：core 中的 Definition，capabilities 中的 Provider 与 Consumer。
- 每个 agent 拥有自己的注册作用域，在 agent 结束时被销毁（2026-07-08 笔记）。
- 面向模型的工具面极小即可。 DSH 的 minimal 预设（agent.cordis.yml）挂载一个 persona 和一个持久 shell；MiniDSH 的默认是三个工具（bash/pwsh、str_replace_editor、subagent），其中 history_read 仅在压缩后出现，而 view_image 是你自行插入的一行。
- 会话日志是记录，模型可见的历史由它派生（session 子系统、compaction 子系统）。
- 字节存于日志旁，引用存于日志中（attachment 接缝）；MiniDSH 为纯文本模型增加了一份存储的文本描述。
- 隔离是 shell provider 内部的 spawn 包装器，在声明之前先探测（sandbox 子系统、sandbox-local）；bubblewrap 配置档逐标志采纳。
- 传输层采用换行分隔的 JSON-RPC，浏览器是客户端，而不是第二个智能体（SDK，Web 客户端说明）。
- 把原因写下来。 DSH 的 .agents/notes 是 BLUEPRINT.md §4 背后的实践。

有意简化

这些都是实验，每一项都在 ARCHITECTURE §12 中陈述，并附有至今仍影响决策的理由。

- 自研内核而非 Cordis —— 用五个机制、约九百行代码实现那两个属性（见架构）。
- 一个带依赖门禁的包，而非数百个包。
- 顺序执行、前台运行、一次一个子进程： 没有后台任务、并行工具调用、可继续的子进程或智能体团队（DSH 自带的 minimal 预设也都不包含这些）。
- 一个协议覆盖三种传输方式（stdio、进程内、WebSocket；十六个 JSON-RPC 方法），而 DSH 提供多种协议配置。
- 两个隔离后端，而非四个： 没有 Landlock（一个原生插件），也没有 Windows 后端（DSH 自带的 Windows 后端只能报告部分强制执行）。
- 附带一个终端客户端（DSH 在 2026-08-04 的一份笔记中移除了其 TUI）：这是证明传输层承载用户界面所需一切的最廉价方式。
- 历史回溯仅在需要时出现： history_read 只覆盖本次会话的压缩所摘要掉的内容，并且在首次压缩之前处于隐藏状态，而 DSH 的 session-query 会向每个请求添加五个工具 schema。

分歧之处

ARCHITECTURE §12 载有原因。

- 工作区根目录就是整个可写上限，而 DSH 的 workspace-write 还会授予一个临时的 /tmp（sandbox-local）。
- 宿主机是否真的能够隔离，会在智能体创建时被探测并记录，而“无后端”是一种受支持、且被如实报告的状态。
- 被委派的子进程的起始权限是一道强制上限，而不仅仅是复制过来的审批策略；默认模型路由与当前模型路由分别记录；每个会话都记录其运行所依据的组成；一个没有任何已连接客户端能够应答的审批会被拒绝，而不是永远挂起。
- 被隔离的子进程在两个后端上都会获得自己的 POSIX 会话，从而在 macOS 和 Linux 上都堵住了控制终端的逃逸路径。

未构建

PTC（DSH 的程序化工具调用）；由模型编写的动态包；MCP 客户端；Windows 隔离后端和 Landlock；长期有效的审批授权；会话删除；会话搜索索引；按用户身份区分；桌面外壳。每一项都在 BLUEPRINT §2 中附有原因。

架构优先的实验
几乎所有代码都是由编码代理的开发会话在简短章程（CLAUDE.md）下编写的，该章程的第一条规则是架构定义会话；会话不定义架构。

先设计空间，再填充它。 第一个会话确立了分层、依赖方向、会话日志模型和权限边界，然后才构建使架构可执行的骨架。

每项能力在拥有代码之前先有归属。 会话在实现一项能力之前，先声明其所属层、接缝、拥有的状态和生命周期。当操作系统隔离在第十一个会话到来时，答案是“无需新增位置”：shell 契约从第三个会话起就已规定了它。

证伪架构，并修复它。 每隔一个功能会话之后都会有一个加固检查点，用于找出文档中记录但在代码中不成立的不变量。它们发现了若干问题——已声明但未实现的不变量、一条以提供方 API 拒绝的形式恢复对话的崩溃修复路径、一个可能向正在运行的委派子进程注入提示的网络客户端——BLUEPRINT.md §4 记录了每一项及其测量结果。

它教给我们的：文档漂移是一种缺陷，因此文档带有由门禁强制执行的大小预算；未被门禁约束的约定不会成立，因此依赖规则是脚本；验证意味着世界本身，而不是代理对世界的描述。经过十六个会话和一次发布之后，新贡献者仍然可以从一份文档中回答一项能力属于哪里、每一层拥有什么以及真相存储在哪里。

验证

pnpm check 包括类型检查、lint、依赖门禁、文档门禁和 676 个测试，在每次拉取请求以及每次推送到 main 或发布分支时，在 Ubuntu、macOS 和 Windows 上运行，随后各自对打包的 tarball 进行安装冒烟测试。测试挂载真实组合；只有模型是脚本化的或从录制的日志回放。

八个实时端到端测试——arcs——在发布前针对真实提供方运行，通过 Linux 和 macOS 上手动触发的工作流，以及在两个开发主机 Windows 和 Linux 上手动运行。每个测试断言的是世界本身，而不是代理的报告：一个在回合中途被终止的任务由第二个进程修复，其日志无需密钥即可回放；工作区之外的编辑被拒绝，并检查该文件确实不存在；上下文预算越界会触发压缩和溢出；一个会话在对话中途切换提供方；一个委派子进程在所有审批都被拒绝的情况下工作；浏览器在两个客户端之间共享一个会话，并通过网络接受一次同意。macOS 这一支在 Seatbelt 下运行，是该平台对这个项目而言唯一的证据。

文档和帮助

| | |
|---|---|
| ARCHITECTURE.md | 契约：分层、所有权、日志、权限、用户界面、新事物应放在哪里、限制 |
| PROJECT.md | 论文、定位与研究背景 |
| BLUEPRINT.md | 接下来要做的事、待解决的问题，以及按会话记录的开发日志 |
| CLAUDE.md | 构建会话所遵循的工作章程 |
| CONTRIBUTING.md · SECURITY.md · CHANGELOG.md | 如何贡献、安全边界在哪里、有哪些变更 |

获取帮助。 缺陷：使用缺陷报告 issue 模板。设计问题，或某项能力在 ARCHITECTURE §11 表格中没有对应条目：使用架构问题模板。漏洞：私下报告，具体方式见 SECURITY.md。

许可与署名

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