CommitStrip/dsh-integrity-plugins

English · 简体中文 · Security · Upstream DSH

CI
License: MIT
DSH
Tests

Make agent side effects explicit, durable, and reviewable · 让 Agent 的副作用显式、持久、可审查

DSH Integrity Plugins 是专为
DeepSeek Harness 打造的一个专注的、树外安全层。它保持
上游 agent 循环不变，并在官方 DSH
插件接缝处添加三项能力：崩溃安全的副作用账本、持久化的工作区变更包装，
以及带有显式父级验收的隔离子 agent 工作区。

本仓库刻意不重建 DSH 的文件系统、沙箱、
审批流程、会话运行时或子 agent 生命周期。它与它们组合协作。

✨ 三个插件

| 插件 | 它添加的内容 | 仍由上游拥有的内容 |
|---|---|---|
| dsh-integrity-effect-ledger | 派发前记录日志、幂等键拒绝、不完整结果检查、仅摘要载荷存储 | 工具注册表和 tools/execute 流水线 |
| dsh-integrity-workspace-mutation | 通过持久化账本路由 write 和 edit | 原子写入、观察守卫、过期版本检查、沙箱化 |
| dsh-integrity-subagent-workspace | 私有子工作区、固定子策略、保留变更、仅父级显式验收 | Agent 创建、提示词、模型、取消、结果收集 |

三者都使用相同的终态模型：

PREPARED → AUTHORIZED → APPLYING → APPLIED | FAILED | UNKNOWN

没有终态记录的 APPLYING 永远不会被自动重放。

📦 安装

要求：

- Linux x64
- Node.js 24
- DeepSeek Harness 0.1.5-rc.1
- 一个 DSH Web 配置文件或其他基于 base 的配置文件

从检出目录直接安装，按依赖顺序：

git clone https://github.com/CommitStrip/dsh-integrity-plugins.git
cd dsh-integrity-plugins

dsh plugin --profile web add \
./packages/effect-ledger \
./packages/workspace-mutation \
./packages/subagent-workspace

dsh --profile web --dump-config
dsh --profile web

对于不可变的部署产物，请先打包每个插件：

npm pack --workspace packages/effect-ledger
npm pack --workspace packages/workspace-mutation
npm pack --workspace packages/subagent-workspace

然后使用 dsh plugin --profile ... add 安装生成的三个 .tgz 文件。
无需安装时构建脚本。

🚀 快速开始

安装这三个 bundle 后，普通的 DSH write 和 edit 调用会自动通过持久化变更边界。

subagent bundle 新增了两个面向父级的工具：

- subagent_isolated — 在父级持久化工作区的私有副本中启动子级。子级无法调用验收工具。
- accept_subagent_workspace — 检查所有权、路径安全性和父级漂移，然后显式合并保留的子级变更。

典型的 agent 流程如下：

1. 父级调用 subagent_isolated。
2. 子级在 workspace-write + approvalPolicy: never 下工作。
3. 子级退出；父级工作区仍然未改变。
4. 父级审查结果并调用 accept_subagent_workspace。
5. 插件在父级漂移时拒绝，或应用保留的文件增量。

🏗️ 工作原理

flowchart LR
MODEL["Agent / model"] --> TOOLS["DSH tools/execute"]
TOOLS --> LEDGER["Effect ledgerfsynced JSONL"]
LEDGER -->|authorized| FS["Upstream DSH FSguards + atomic write"]
LEDGER -->|authorized| CHILD["Isolated child workspace"]
CHILD --> RETAIN["Retained delta"]
RETAIN -->|explicit parent accept| FS
LEDGER -->|crash window| UNKNOWN["Manual recovery required"]

持久化边界存储请求、结果、幂等键和错误消息的 SHA-256 摘要。原始工具内容和原始异常文本不会写入日志。

🔒 安全属性

- 当通过 effect ledger 分类时，外部/不透明效果默认被拒绝。
- 重复或中断的幂等键会失败关闭。
- 日志文件和控制记录使用私有权限，并在分发前执行 fsync。
- 子级工作区拒绝符号链接、套接字、设备、NUL 路径、绝对清单路径和 .. 逃逸。
- 验收绑定到持久化的父级 agent id。
- 每个受影响的父级文件必须仍然与子级工作区的基线匹配。
- 子级 agent 被固定为 workspace-write；审批被固定为 never。
- 默认情况下，.git 和 .dsh-integrity 从子级副本中排除。

在将任何 DSH 部署暴露到网络之前，请阅读 SECURITY.md。
这些插件不会将上游 DSH Developer Preview 转变为强化的公共多租户服务。

✅ 验证

当前测试套件包含 11 个聚焦测试：

| 领域 | 用例数 |
|---|---:|
| Effect ledger | 5 |
| 工作区变更集成 | 3 |
| 隔离工作区 / 验收 | 3 |

npm install
npm test

服务器验收运行还会验证预构建 tarball 校验和、针对官方 Web profile 的干净安装/卸载、peer 解析，以及经过身份验证的 loopback Web 响应。

📁 仓库结构

packages/
effect-ledger/          durable effect Service + tools/execute consumer
workspace-mutation/     write/edit adapter over the ledger
subagent-workspace/     isolated provider + explicit acceptance tool
docs/
logo.svg
.github/workflows/
ci.yml

每个包都是一个独立的 DSH 捆绑包，拥有自己的 package.json、
cordis.patch.yml、运行时入口点和测试。

⚠️ 兼容性与诚实的局限

| DSH 版本 | 状态 |
|---|---|
| 0.1.5-rc.1 | 已固定并测试 |
| 更新的预发布版本 | 在重新验证之前不受支持 |
| 0.1.1-rc.2 及更早版本 | 使用归档的旧版实现，而非这些捆绑包 |

在做出广泛的生产环境声明之前，仍然需要完成：每个状态的终止故障
注入、对抗性多进程压力测试、真实模型子代理的端到端
运行、大树性能特征描述，以及面向用户的完整性
检查面板。

🙏 上游与许可

本项目是
deepseek-ai/deepseek-harness 的扩展，
针对当前发布线固定到标签 dsh-v0.1.5-rc.1。
它依赖于 DSH 的 Cordis 插件模型以及公共服务/事件接缝。参见 THIRD_PARTY_NOTICES.md。

许可证

MIT © 2026 CommitStrip