Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add filesystem capability seam and tools

Browse Source
This commit is contained in:
Dudu-0223
2026-06-22 10:48:41 +08:00
parent 6b4dc48fbd
commit 5e01564afb
36 changed files with 3515 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

113
docs/rfc/implemented/feature/2026-06-17-filesystem-tool-schemas.md Normal file
View File

@@ -0,0 +1,113 @@
# RFC: Filesystem tool schemas — model-facing read/write/edit shapes
Status: implemented
## Problem
[The filesystem capability-seam RFC](../architecture/2026-06-17-filesystem-capability-seam.md) defines the filesystem capability seam (`ctx.fs`), the three-package split (`dsh-fs`, `dsh-fs-local`, `dsh-tool-fs`), and the observed-file/stale-version policy for read-before-write/edit checks. The remaining decision for the first filesystem tool delivery is the model-facing schema surface: what arguments the model sees for `read`, `write`, and `edit`.
The schema should be small enough to implement in the first `dsh-tool-fs` pass, but stable enough that future local/remote/sandboxed filesystem backends do not require model-facing churn. It should also avoid importing every option from reference systems. Claude Code and OpenCode expose similar core file tools but differ in naming style and extra flags; this RFC chooses the minimal shared surface for the prototype.
## Proposal
`@deepseek-ai/dsh-tool-fs` exposes these three model-facing tools in the first filesystem suite:
| Tool | Our schema | Claude Code | OpenCode | Notes | Part of prototype |
|---|---|---|---|---|---|
| `read` | `read(file_path, offset?, limit?)` | `Read(file_path, offset?, limit?, pages?)` | `read(filePath, offset?, limit?)` | Files only; 1-indexed `offset`; no image/PDF/multimodal support in the first pass. | YES |
| `write` | `write(file_path, content)` | `Write(file_path, content)` | `write(content, filePath)` | Creates or overwrites UTF-8 text. Updates to existing files require prior observation through `ctx.fs`; new-file creates do not. | YES |
| `edit` | `edit(file_path, old_string, new_string, replace_all?)` | `Edit(file_path, old_string, new_string, replace_all?)` | `edit(filePath, oldString, newString, replaceAll?)` | Literal string replacement; unique match required by default; requires prior full observation through `ctx.fs`. | YES |
The schema uses snake_case field names (`file_path`, `old_string`, `new_string`, `replace_all`) to align with Claude Code and with existing DeepSeek Harness tool-schema examples. The consumer package translates these model-facing names into internal `ctx.fs` requests.
## Tool schemas
### `read`
`read` inspects a UTF-8 text file and returns line-numbered content.
Arguments:
- `file_path: string` — required. Path to read, resolved by `ctx.fs`.
- `offset?: number` — optional. 1-based first line to return. Defaults to the first line.
- `limit?: number` — optional. Maximum number of lines to return. Defaults and caps are implementation details of `dsh-tool-fs` / `ctx.fs`.
Non-goals for the first pass:
- No PDF `pages` argument.
- No image or multimodal file reads.
- No directory listing through `read`; if needed, listing becomes a separate future tool.
### `write`
`write` creates or fully replaces a UTF-8 text file.
Arguments:
- `file_path: string` — required. Path to write, resolved by `ctx.fs`.
- `content: string` — required. Full UTF-8 text content to write.
For existing files, `write` requires prior full file state derived from a previous read in the same execution context. `ctx.fs` derives the file-state owner and uses the recorded version as the stale guard. Creating a new file does not require prior state or an owner.
The schema does not expose `expected_hash`, `expected_version`, or `create_only` as model-facing parameters. Stale-version checks are driven by `ctx.fs` file state and backend-produced versions, not by asking the model to copy version tokens through the schema.
### `edit`
`edit` updates an existing UTF-8 text file by replacing literal text.
Arguments:
- `file_path: string` — required. Path to edit, resolved by `ctx.fs`.
- `old_string: string` — required. Literal text to replace. Empty strings are invalid in the first pass.
- `new_string: string` — required. Literal replacement text; an empty string deletes the match.
- `replace_all?: boolean` — optional. Defaults to false. When false, `old_string` must identify exactly one match.
`edit` requires prior full file state derived from a previous read in the same execution context. `ctx.fs` derives the file-state owner and uses the recorded version as the stale guard.
The first pass rejects Codex-style patch grammars and multi-mode edit APIs. It uses one strict literal replacement mode so the model-facing contract stays simple and the backend can own exact-match, duplicate-match, line-ending, and stale-version semantics.
## Result shape
The first implementation returns `ContentBlock[]` through the existing `ToolDefinition.execute()` contract. `ctx.fs` returns structured filesystem results and owns file-state recording/refreshing; `tool-fs` formats those results into the model projection.
Default native projections:
| Tool | Structured `ctx.fs` outcome consumed by `tool-fs` | Default model projection |
|---|---|---|
| `read` | returned lines, returned line count, total line count, target display path, file version, partial-view flag | line-numbered text plus pagination footer |
| `write` | create/update operation, target display path, new file version | concise create/update success text |
| `edit` | replacement count, replace-all flag, target display path, new file version | concise edit success text |
The structured outcome should not restate model arguments such as `file_path`, `old_string`, or `content` unless the backend has resolved them into new information such as `displayPath`, `targetKey`, or a new version. Token-conscious truncation is part of the model projection, not the backend's canonical result.
## Deferred
The following are deliberately out of scope for the first filesystem schema pass:
- Model-facing `expected_hash`, `expected_version`, or `create_only` parameters.
- Directory listing, glob, grep, and search tools.
- Binary-safe read/write operations.
- PDF/image/multimodal `read`.
- Code Mode projection values for filesystem tools.
- A canonical edit diff format.
## Tests
`dsh-tool-fs` schema tests should assert:
- `read` requires `file_path` and accepts optional positive integer `offset` / `limit`.
- `write` requires `file_path` and `content`.
- `edit` requires `file_path`, `old_string`, and `new_string`, accepts optional boolean `replace_all`, rejects empty `old_string`, and defaults `replace_all` to false.
- The registered JSON schemas use the snake_case field names in this RFC.
- The tool descriptions accurately describe that existing-file `write` and `edit` require a prior full read in the same execution context, while new-file `write` does not.
- The root plugin and subpath plugins register the same schemas.
Integration tests should execute `read`, `write`, and `edit` through `ctx.tools.execute()` with a fake or local `ctx.fs` provider and verify that model arguments are translated into the expected `ctx.fs` calls.
## Risks
**The first schema is intentionally smaller than Claude Code's.** Dropping PDF pages, multimodal read, rich grep/list flags, and expected hash fields keeps the first implementation focused, but users may ask for those quickly. They should be added as separate RFCs or focused follow-ups rather than overloaded into the initial schema.
**No explicit model-facing stale guard in v1.** The schema does not ask the model to provide an expected hash/version. That is intentional: stale checks come from backend-produced versions and `ctx.fs` observed-file state, not from fragile model-copied tokens. Filesystem safety failures surface through structured `FsError` codes owned by `dsh-fs`, not through model-supplied version fields.
**Naming becomes public surface.** Once shipped, changing `file_path` to `filePath` or `old_string` to `oldString` would churn prompts, examples, and downstream clients. This RFC chooses snake_case up front and treats it as the stable model-facing contract.