dsh-fs-observation-bridge
将代码读取工具（MCP、CLI、保守的 Bash 和 PowerShell shell 读取、本机读取）接入 DSH 的 fs/observed 编辑前读取策略，并提供传输和来源注册表。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:iBobbyTS/dsh-fs-observation-bridge#8535e2be0099bd21dbd08416aaaa09967b8797feFs Observation Bridge 以 dsh-fs-observation-bridge 发布，当前版本为 0.3.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
English | 简体中文
Bridges external code-reading tools into DeepSeek Harness (DSH)'s native file observation system, allowing agents to edit files without redundant read calls after inspecting source code.
pwsh.Bridge code readers to DSH's native file observation system rather than replacing its editing mechanisms.
The plugin consists of three independent layers:
fs/observed.Each layer is independently extensible. New code-reading tools can be integrated without modifying the core, and unverifiable reads do not grant editing authorization.
Concurrent tool calls are observed in completion order. If an older observation for the same file arrives last, a later edit fails closed with FS_STALE_VERSION rather than editing unseen content.
fs/observed is a whole-file, versioned observation, exactly like DSH's native read offset/limit: a trusted partial view authorizes a later full-file edit while the version is unchanged. This bridge does not add a coverage policy; it only feeds the stock policy trusted observations.
The shell-read transport claims two small, deterministic grammars: Bash on POSIX hosts and PowerShell on Windows hosts (pwsh). It is mutually exclusive with the CodeGraph cli transport: a command is normalized by exactly one of them.
| Form | Example | Replay rule |
|---|---|---|
cat file / cat -- file | cat src/app.ts | Exact full-file comparison |
head file / head -n N file / head -N file | head -n 80 src/app.ts | First N lines (default 10) |
tail file / tail -n N file | tail -n 50 src/app.ts | Last N lines (default 10) |
tail -n +N file | tail -n +522 README.md | From line N to EOF |
sed -n 'Np' file | sed -n '42p' src/app.ts | One line |
sed -n 'N,Mp' file | sed -n '40,120p' src/app.ts | Inclusive range |
sed -n 'N,$p' file | sed -n '40,$p' src/app.ts | From line N to EOF |
A pipeline is one reader (cat without numbering, nl -ba, or sed) followed by up to two stages chosen from head, tail, sed, and nl. nl may appear at most once, and four or more stages are rejected.
| Form | Example |
|---|---|
cat -n file / cat -b file | Number all lines / non-blank lines |
nl -ba file | Number all lines |
cat file | head -n N | cat app.ts | head -n 80 |
cat file | tail -n N | cat app.ts | tail -n 80 |
cat file | sed -n 'N,Mp' | cat app.ts | sed -n '20,80p' |
cat file | nl -ba | Number the whole file |
cat file | head -n N | tail -n M | Select a window from a prefix |
cat file | sed -n 'N,Mp' | nl -ba | Select first, then number from 1 |
cat file | nl -ba | sed -n 'N,Mp' | Number first, then select |
nl -ba file | sed -n 'N,Mp' | Number first, then select |
sed -n 'N,Mp' file | nl -ba | Select first, then number from 1 |
Only a normal foreground pwsh call with a session owner is observed. Persistent PowerShell, background jobs, promoted/timeout calls, and PTC-nested calls are never observed.
| Form | Example | Replay rule |
|---|---|---|
Get-Content file, gc/cat/type alias | Get-Content .\src\app.ts | every line object, exactly |
Get-Content file -Raw | Get-Content .\app.ts -Raw | the whole file string plus the host's final newline |
Get-Content file -TotalCount N / -Head N | Get-Content .\app.ts -TotalCount 120 | first N line objects |
Get-Content file -Tail N | Get-Content .\app.ts -Tail 50 | last N line objects |
Get-Content file | Select-Object -First N | ... | Select-Object -First 100 | first N line objects |
Get-Content file | Select-Object -Last N | ... | Select-Object -Last 50 | last N line objects |
Get-Content file | Select-Object -Skip N -First M | ... | Select-Object -Skip 200 -First 100 | line objects N+1 through N+M |
Get-Content file | Select-Object -Index I | ... | Select-Object -Index 42 | one line object, 0-based |
PowerShell is not Bash and is parsed by its own strict grammar:
Get-Content (or its stock aliases gc, cat, type) with one literal file, plus at most one Select-Object stage, is accepted.-LiteralPath keeps [id] and similar characters literal. Positional binding and -Path keep PowerShell wildcard semantics, so *, ?, [, and ] are rejected there even when quoted.Env:, HKLM:), drive-relative paths (C:file), NTFS alternate data streams (file:stream), device namespaces (\\?\, \\.\), ~, variables and subexpressions, arrays and commas, splatting, script blocks, redirection, ;/&&, comments, backtick escapes, newlines, and parameter abbreviations.-Encoding, -Stream, -Wait, -AsByteStream, -Delimiter, -ReadCount, -Filter, -Include, -Exclude, -Force, and any unknown parameter. -Raw cannot be combined with -TotalCount/-Tail or a pipeline; Select-Object accepts only -First, -Last, -Skip (with -First), and -Index, and rejects -Property, -ExpandProperty, and -Unique.Get-Content emits one string object per line (terminators consumed) and the console host writes each formatted object followed by its own newline; -Raw emits one string and the host appends one more newline. The bridge therefore rebuilds the expected stdout from DSH's own ctx.fs.readText and compares it with the structured stdout.text, normalizing only CRLF/LF. Line bodies, blank lines, tabs, trailing spaces, and a missing final newline are compared exactly. A Windows PowerShell 5.1 read that decodes a UTF-8 file through the legacy ANSI code page produces different text and therefore fails closed; an empty file is observable only for a complete Get-Content/-Raw read.
A shell-read observation is emitted only when all of these hold:
bash or pwsh call with a session owner. Persistent-shell, background, promoted, job_output, and PTC-nested calls are not supported.exitCode === 0, no signal/timeout/abort/stop, no sandbox denial or runner failure, stderr is empty, and neither stdout nor stderr is truncated; a spill file is not accepted as model-visible content.|, no redirection, variable/command substitution, glob, brace expansion, or unquoted tilde. Quoted glob characters such as '[id]/+page.svelte' are literal filenames and are allowed for Bash; PowerShell follows the dialect rules above.workdir (or the session directory) and matches the Bash result's cwd. For PowerShell it is the result's own cwd, because that is the directory the process actually ran in. The path always resolves through ctx.fs.maxSourceBytes; before = stat, readText, after = stat must report the same opaque version.cat or complete Get-Content/-Raw read of an empty file.Rejected examples include cat f1 f2, cat -, cat -A, head -c, tail -f, complex or -i sed, npx cat, ssh host cat f, docker exec ... cat f, git show HEAD:f, rg --files, arbitrary Python/Node/awk scripts, redirections, command lists, and more than two pipeline selectors for Bash; and Get-Content -Wait, Get-Content -AsByteStream, Get-Content -Raw | Select-Object ..., Select-String, rg, cmd /c type, path arrays, provider paths, and dynamic paths for PowerShell. These are deliberately outside the low-complexity trusted whitelist.
Set fields under the plugin row's config in the profile patch:
- id: fs-observation-bridge
name: 'dsh-fs-observation-bridge'
config:
maxSourceBytes: 8388608
maxEvidenceFiles: 200
disabledSources: []
| Field | Default | Meaning |
|---|---|---|
maxSourceBytes | 8388608 (8 MiB) | Largest file read to verify evidence; larger files are skipped (no authorization). |
maxEvidenceFiles | 200 | Largest number of files validated from one tool result. |
disabledSources | [] | Built-in source ids to disable, for example [codegraph], [shell-read], or [powershell-read]. An unknown id fails activation. |
Install this package as a DSH bundle from the Plugin Manager (plugin_manager, action install_bundle, target: the absolute path of this package). The bundle declares dsh.bundle.patch, inserts one fs-observation-bridge row, and leaves the stock fs-observation-policy enabled.
Sources are built into the project rather than registered at runtime. Adding one is a focused contribution:
lib/sources/<tool>.js exporting { id, accepts, extract, resolveRoot? }.extract(invocation) returns an evidence array. Snippet-based items are { path, root?, snippets: [{ text, startLine?, endLine? }] }; exact-output items are { path, expectedStdout, verify(content), stable, permitEmpty }. verify must replay the source's visible output from current file content.createSourceRegistry([...]) in lib/index.js.A source that cannot provide verifiable output simply never authorizes an edit.
Issues and pull requests are welcome, especially contributions that add support for additional code-reading tools.
All contributions should preserve DSH's native file observation and editing safety semantics.
MIT.