@suagr_xl/dsh-safety
用于 DeepSeek Harness (DSH) 的安全防护插件：强制执行受保护路径规则，提供基于回收站且支持撤销的 safe_delete、最近已知良好组合快照、重启前组合检查以及审计日志。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add @suagr_xl/dsh-safety@0.2.1Safety 以 @suagr_xl/dsh-safety 发布，当前版本为 0.2.1。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
English | 中文
Filesystem safety harness for DeepSeek Harness
execution-time guard · user-gated approvals · trash-based deletes · composition snapshots · pre-restart checks · standalone CLI
What · Features · Approval workflow · Install · Quick start · CLI · Tools · Config · How it works · Structure · Testing · Troubleshooting · Security · Design · FAQ · Known limitations
A filesystem safety harness for DeepSeek Harness (DSH). It enforces a three-tier file policy at the tool-execution boundary and, crucially, makes the agent ask the human before it deletes or rewrites anything important:
The package has zero runtime dependencies. It installs as a standard DSH profile bundle and also ships a standalone CLI, so the recovery and approval layer remains usable even when DSH itself will not start.
Background — the guard rules are derived from a real production incident: a script silently resolved the wrong path (PowerShell's
$HOMEis read-only) andRemove-Item -Recurse -Forcedeleted an entire engine runtime root. The directory was recoverable only because it was generated content; hand-authored files would have been lost permanently. The plugin turns the lessons of that incident into enforced mechanisms rather than documentation.
ctx.tools.guard) — denies destructive tool calls
before they run.
rm -r/-rf, Remove-Item -Recurse,
rd /s, rmdir, shutil.rmtree, fs.rm recursive,
require('fs').rmSync…) are denied by default and routed to safe_delete
(trash, undoable). In cooperative mode a human-granted approval can
authorize a free-path recursive shell delete.write/edit/str_replace_editor on protected paths (profile
package.json, cordis.patch.yml, cordis.yml, lockfiles,
node_modules, the deployment install dir, home patch/settings) are
denied unless the user has granted an approval.run_code bodies are scanned too — arbitrary code execution cannot
hide an fs.rmSync/shutil.rmtree on a protected zone behind a tool
call boundary.Remove-Item "$env:USERPROFILE\.dsh\…" whose literal path only exists after expansion
is denied (the reference + tail fragment is matched against protected
markers).safety_ask creates a structured request
(what / why / consequence / alternative); the human approves via
dsh-safety allow <id> (or dsh-safety delete --force); the approval is
one-shot, time-limited, audited, and serialized across processes by an
atomic lock. The model can never grant itself one — a force:true flag
alone is not an approval. Every request also carries a system-computed
consequence (from the real path classification) shown separately from the
model's self-report, so the human approves on a system-backed verdict.The whole point of the approval system is that the model can never approve
its own destructive calls. A flag it can set (force:true) is not a
confirmation — only a human action (CLI) is.
agent calls delete/write on a confirm/protected zone
│
▼
guard BLOCKS it (educational message: what / why / consequence / sanctioned path)
│
▼
agent calls safety_ask { path, kind, what, why, consequence, alternative }
│ → creates a request (the SYSTEM also computes an authoritative
│ consequence from the real path classification), returns an id
▼
agent tells the user: "please approve: dsh-safety allow <id>"
│
▼
USER runs dsh-safety allow <id> (or: dsh-safety delete --force)
│ → grants a one-shot, time-limited approval (default 5 min)
▼
agent retries the original call → guard consumes the approval and LETS IT THROUGH
│ (the approval is now spent; a second call is blocked again)
▼
everything is audited: who requested, who approved, when, when it was consumed
Practical details:
safety_ask with the causality. The request carries
what/why/consequence/alternative and a system-computed
systemNote — dsh-safety approvals shows the [system] verdict and the
(model: …) self-report separately, so you approve on the system's
classification, not the model's unverifiable story.dsh-safety allow <id> approves an agent-created request.
dsh-safety allow --path <p> --kind delete|write [--recursive] creates and
approves one directly (you are the human). dsh-safety delete --force on a
confirm/protected path also grants the approval it needs and then moves the
item to trash.approvalTtlMs
(default 5 minutes) and must be re-granted.safe_delete is the trash channel: an
approved raw retry (e.g. a Remove-Item re-run) executes as-is; that is
exactly what the human authorized. If you want the operation recoverable,
have the agent use safe_delete (always trash, undoable) instead of raw
shell. Recursive raw deletes on protected/confirm paths are never
approvable via raw shell — they always go through safe_delete.mode: strict (default), raw recursive shell
deletes are never approvable — the only way to remove a directory tree is
safe_delete (trash, undoable). In mode: cooperative, the human can
authorize a free-path recursive shell delete with a generic recursive
approval (dsh-safety allow --path … --recursive).System requirements: a working DeepSeek Harness (dsh web boots). npm
install has no extra requirements; installing from the repository needs
Node.js >= 22 and pnpm.
dsh plugin --profile web add @suagr_xl/dsh-safety # install from the official npm registry / 从官方 npm registry 安装
dsh plugin runs pnpm and reconciles dsh.profile.bundles automatically
because this package declares dsh.bundle. Restart dsh web — the guard is
then active and the safety_* tools appear.
git clone https://github.com/sugarxl/dsh-safety.git # clone the repo / 克隆仓库
cd dsh-safety # enter the directory / 进入目录
dsh plugin --profile web add link:$(pwd) # symlink the repo into the profile / 把仓库软链进 profile
The link: protocol symlinks the repo (changes to lib/ apply after a
restart), unlike file: which copies a snapshot. dsh plugin reconciles the
bundle automatically. Note: the profile directory is not a pnpm workspace, so
any workspace:* deps would fall back to the npm registry — this plugin has
zero runtime dependencies at all (its imports are only Node builtins + its
own safety-core.mjs/state.mjs/audit.mjs), so a bare link: install works
with no node_modules of its own and no fallback is needed.
Both installs go through the official dsh plugin mechanism — nothing else to
configure:
$DSH_HOME/profiles/<name>/package.json # + dependency + dsh.profile.bundles / 新增依赖 + dsh.profile.bundles
$DSH_HOME/profiles/<name>/node_modules/@suagr_xl/dsh-safety/ # the installed package / 安装的包本体
The bundle layer is read at boot from the package's own cordis.patch.yml.
The dsh-safety row id appears in exactly one layer (that file); never add it
to the profile or home cordis.patch.yml.
dsh --profile web --dump-config | grep -i dsh-safety # row present / 确认行出现
dsh-safety check # pre-restart gate / 重启前体检
# restart dsh web / 重启 dsh web
# uninstall: / 卸载：
dsh plugin --profile web remove @suagr_xl/dsh-safety
# restart dsh web / 重启 dsh web
dsh web
process — a page refresh is not enough. Confirm the row is mounted with
dsh --profile web --dump-config.ERR_PNPM_IGNORED_BUILDS: pnpm blocks dependency build scripts; add
the listed packages to pnpm-workspace.yaml allowBuilds and re-run.minimumReleaseAge can silently pick an older publish within ~10 days; add
minimumReleaseAgeExclude: ['@suagr_xl/dsh-safety'] to the profile's
pnpm-workspace.yaml and run dsh plugin --profile web update @suagr_xl/dsh-safety.npm link # or: node bin/dsh-safety.mjs ...
dsh-safety status
The CLI reads the same $DSH_HOME/.dsh-safety state the plugin uses, so you
can approve/undo/restore from your terminal even if DSH is down.
# 1. Inspect the effective policy zones
dsh-safety policy
# 2. Snapshot before editing any composition file
dsh-safety snapshot before-edit
# 3. Delete through the safe channel (preview first, then execute)
dsh-safety delete path/to/file --preview # free path — just works
dsh-safety delete path/to/file # moves to trash (undoable)
dsh-safety delete path/to/important --force # confirm/protected zone:
# --force IS the human approval here
# 4. Recover a delete
dsh-safety trash
dsh-safety undo <trash-id>
# 5. Boot failure: validate, then roll back
dsh-safety check
dsh-safety status # list snapshots + pending approvals
dsh-safety restore <snapshot-id> --confirm
# 6. Approve a request the agent created (model asked via safety_ask)
dsh-safety approvals
dsh-safety allow <request-id>
dsh-safety status state: trash, snapshots, approvals, journal
dsh-safety delete <path> [--force] [--preview]
dsh-safety trash [--limit N]
dsh-safety undo <id>
dsh-safety snapshot [label] [--exclude a,b]
dsh-safety restore <id> --confirm
dsh-safety check exit 1 on failure (CI-friendly)
dsh-safety journal [n]
dsh-safety policy effective policy zones
dsh-safety approvals list pending/granted approval requests
dsh-safety allow <id> approve a request the agent created
dsh-safety allow --path <p> [--kind delete|write] [--recursive] approve a new one directly
dsh-safety revoke <id> revoke a request
dsh-safety help
--home <path> overrides the state root ($DSH_HOME or ~/.dsh by default).
The plugin's configured roots live in the cordis patch layers, which a
standalone CLI cannot read — so delete/policy accept the same overrides to
align with the running guard:
--write-root <path> add a protected (no write/edit/delete) root
--confirm-root <path> add a confirm-delete (trash-only) root
--no-home-confirm do NOT make the whole OS home a confirm zone
--keep-trash=N / --keep-snapshots=N retention caps after delete/snapshot
The CLI is the human side of the approval flow:
dsh-safety delete --forceanddsh-safety alloware REAL user authorizations (recorded in state); the model can never grant itself an approval.
| Tool | Purpose |
|---|---|
safe_delete | trash-based delete (preview / user approval / undoable). force:true is NOT a user approval — the deletion needs a granted approval first |
safety_ask | request the user's approval with the causality (what / why / consequence / alternative); the user approves via dsh-safety allow <id> |
safety_trash / safety_undo | list trash / restore an item |
safety_snapshot / safety_restore | snapshot composition / rollback (confirm:true) |
safety_check | pre-restart validation (UTF-8 / mojibake / JSON / duplicate ids) |
safety_journal / safety_status | audit log / state (incl. pending approvals) |
Configure via the bundle row in a patch layer (e.g. the profile's
cordis.patch.yml):
- id: dsh-safety
config:
blockWriteRoots: ["C:\\extra\\protected"]
confirmDeleteRoots: ["D:\\data"]
snapshotExclude: ["settings.yaml", ".credentials.yaml"]
blockWrites: true
blockShellDestructive: true
audit: true
keepTrash: 200
keepSnapshots: 10
mode: strict # strict | cooperative
approvalTtlMs: 300000 # approval validity window (5 min default)
| Field | Default | Meaning |
|---|---|---|
blockWriteRoots | profile manifests/patches/lockfiles/node_modules, install dir, home patch/settings | no write/edit/delete |
confirmDeleteRoots | $HOME, profiles/*, .agent-presets | no delete without a granted user approval (still trash-only) |
snapshotExclude | ["settings.yaml", ".credentials.yaml"] | files never copied into snapshots |
blockWrites | true | enable the write/edit guard |
blockShellDestructive | true | enable the shell-delete guard |
audit | true | journal destructive tool calls |
keepTrash / keepSnapshots | 200 / 10 | retention limits |
mode | strict | strict: recursive shell deletes are never approvable; cooperative: the human can authorize them via the approval flow |
approvalTtlMs | 300000 | how long a granted approval stays valid before it must be re-granted |
Three-tier policy:
| Tier | Allowed | Denied | Default coverage |
|---|---|---|---|
protected | read | write / edit / delete (unless a user approval is granted) | profile package.json/cordis.patch.yml/cordis.yml/lockfiles/node_modules, install dir, home patch & settings |
confirm | read, edit | delete (needs a granted user approval) | entire $HOME, plugin sources, agent presets |
free | read/write/delete | recursive delete (approvable in cooperative mode) | regular workspace files |
The guard decision chain, per tool call: destructive verb? → is it a
recursive delete? → does an explicit path hit a protected/confirm zone? → does
a variable-reference fragment ($env:X\…, %X%\…, ${X}/…) expand into a
protected zone? → does the command text hit a protected marker (~/relative
forms)? → run_code code bodies go through the same chain. A matching,
granted user approval lets the call through once; otherwise it is denied.
Denials are educational: they name the target, describe it, explain the
consequence (e.g. "rewriting this can make DSH fail to boot") and the
sanctioned path (safe_delete / safety_ask), and tell the agent not to try
workarounds. Repeated blocks for the same target escalate to an explicit STOP.
Denials are journaled and returned to the model as errors (never a crash).
A second layer hooks the fs/write-intent / fs/edit-intent waterfalls and
throws FS_DENIED on protected paths regardless of which tool writes.
buildPolicy lives in safety-core.mjs and is shared by the plugin guard and
the standalone CLI, so the two surfaces can never drift apart.
restoreSnapshot is transactional: it backs up live files first, then copies
snapshot files back, and rolls the whole thing back if either phase fails — a
failed rollback never leaves the composition half-restored. Approval state
lives in $DSH_HOME/.dsh-safety/state.json, shared by the guard, safe_delete
and the CLI.
dsh-safety/
├── bin/
│ └── dsh-safety.mjs # standalone CLI (zero deps)
├── lib/
│ ├── safety-core.mjs # pure logic: policy/guard/trash/snapshot/check
│ ├── index.js # host half: tools, guard, fs hooks
│ ├── state.mjs # persisted state (approvals, guard counters) — wired into index.js
│ ├── audit.mjs # JSONL audit log + threshold alerts — wired into index.js
│ ├── policy.mjs # policy refinement utilities (symlink/mount detection, exported)
│ └── snapshot-store.mjs # incremental snapshot utilities (baseline/delta, exported)
├── test/
│ ├── safety.test.mjs # unit tests: core guard/trash/snapshot/check
│ ├── state.test.mjs # state persistence + approval lifecycle
│ ├── audit.test.mjs # audit log + alerts
│ ├── policy.test.mjs # policy refinement
│ ├── snapshot-store.test.mjs # incremental snapshots
│ └── harness.mjs # integration checks (clean checkout, zero deps)
├── cordis.patch.yml # bundle patch (inserts the dsh-safety row)
├── package.json # dsh.bundle + bin
├── install.ps1 / recover.ps1 # local convenience scripts (snapshot→install→verify→rollback)
├── README.md / README.zh.md # docs (bilingual, officially paired)
└── LICENSE / NOTICE / SECURITY.md
npm test # all unit tests (core + state/audit/policy/snapshot-store)
node test/harness.mjs # integration checks, clean checkout (no @deepseek-ai needed)
npm run check # syntax checks on every lib/bin module
Current suite: 68 unit tests + the integration harness, green on Windows and Linux CI (Node 22 and 24).
dsh-safety check to find
mojibake / JSON / duplicate-id problems; dsh --profile web --dump-default-config to see the bundle layer without the user layer;
dsh-safety restore <id> --confirm to roll back a snapshot.$HOME/plugin/config zones
and asks the human for approval. Use safe_delete (undoable) instead of raw
rm; for a confirm/protected path, let the agent create a safety_ask
request and approve it with dsh-safety allow <id>.dsh-safety delete <path> --force — the CLI user is the human, so --force is a real approval
and the item still goes to trash, never permanent. From the model side, a
granted approval is required (force:true alone is not enough).safety_ask and wait for your
approval, or deny the request.See SECURITY.md for the full threat model. In short: the guard
intercepts model tool calls, not commands you run in your own terminal;
run_code scanning is text-based and can be outsmarted by dynamic/obfuscated
code; approval records in state.json can be tampered with by a
same-process plugin. It is a safety net, not a sandbox — configure DSH's own
sandbox/approval for real containment, and use this plugin for the recovery
and ask-the-human layer DSH lacks.
MIT. Integration patterns modeled after DeepSeek Harness (MIT); see NOTICE.
safe_deletesafety_undopreview:truesafety_snapshot saves the whole plugin
composition (per-profile manifests, patches, lockfiles, plugin
package.json + cordis.patch.yml, agent presets) with SHA-256 hashes;
safety_restore rolls back to a last-known-good state transactionally
(current files are backed up first; a failed rollback never leaves the
composition half-restored). Credential-bearing files are excluded by default.safety_check validates UTF-8, detects mojibake
(wrong-encoding round-trips, the classic "DSH won't open" cause), JSON
parse errors, and duplicate plugin row ids across patch layers (the
"one row, one layer" rule).safety_journal / safety_status.dsh-safety works without DSH: policy / delete /
undo / snapshot / restore / check / approve from your own terminal, even
when DSH won't boot.