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

docs: apply verbatim model experience guidance repo-wide

Browse Source
This commit is contained in:
Tianyi Cui
2026-07-13 21:33:23 +08:00
parent 3fc2a4ca82
commit 646f3d2d0c
43 changed files with 405 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
packages/bash/bash-local/README.md
View File

@@ -29,7 +29,7 @@ Design surveyed against the bash tools of Claude Code, OpenCode, Codex, and pi;
| Context surface | What the model sees | Token effect |
|---|---|---|
| Bash tool results, indirectly | Through `dsh-tool-bash`, the conversation model sees the retained stdout and stderr tail, exit and timeout markers, background-task state, and a spill-file path when full output is available. This backend adds no prompt or schema itself. | Zero tokens until a bash tool runs. Foreground output is bounded per stream by `maxOutputBytes`; background reads return only new output, so polling does not repeat already-delivered text. Results remain in history until compaction. |
| Bash tool results, indirectly | Through `dsh-tool-bash`, the conversation model sees the data-dependent stdout and stderr tail inside that consumer's exact result wrappers, exit and timeout markers, background-task state, and a spill-file path when full output is available. This backend adds no prompt or schema itself. An unknown task becomes exactly `Error: unknown bash task "<taskId>"`; a pre-spawn cancellation becomes `Error: aborted before spawn: <reason>`. | Zero tokens until a bash tool runs. Foreground output is bounded per stream by `maxOutputBytes`; background reads return only new output, so polling does not repeat already-delivered text. Results remain in history until compaction. |
## Known Limitations and Deferred Work

8
packages/bash/tool-bash/README.md
View File

@@ -62,9 +62,11 @@ Under a sandboxing executor this plugin makes the session's standing mode overri
| Context surface | What the model sees | Token effect |
|---|---|---|
| System prompt | Every request in this plugin's registration scope carries the short `tool:bash` exit-code instruction. A sandboxing executor adds no mode statement or switch notice. Scoped tool restrictions can hide the schemas without removing this independently registered section. | Small fixed input cost per request while the plugin is active, unchanged by sandbox mode or mode switches. |
| Tool schemas | The model sees `bash`, `bash_output`, and `bash_kill`. `sandbox_permissions` and `justification` appear on `bash` only when the mounted executor advertises sandboxing. Agent-scoped tool restrictions can remove the definitions for that agent. | Fixed schema cost on every request where the tools are visible; sandbox support adds the escalation fields. |
| Tool-call history and results | Calls retain their arguments. Results contain bounded stdout and stderr, status markers, task ids, incremental background output, kill outcomes, and sandbox denial or failure markers. | Data-dependent tokens are added after each call and resent on later steps until compaction. Executor output caps and incremental reads bound each result; spill paths let the model fetch omitted output deliberately. |
| System prompt | Every request in this plugin's registration scope contains exactly `Check the [exit code: N] marker on every bash result; investigate failures before moving on.` A sandboxing executor adds no mode statement or switch notice. Scoped tool restrictions can hide the schemas without removing this independently registered section. | Small fixed input cost per request while the plugin is active, unchanged by sandbox mode or mode switches. |
| Tool schemas | The model sees `bash`, `bash_output`, and `bash_kill`; their full descriptions and JSON schemas are the exact output of the definitions in `src/index.ts`. `sandbox_permissions` and `justification` appear on `bash` only when the mounted executor advertises sandboxing. Agent-scoped tool restrictions can remove the definitions for that agent. | Fixed schema cost on every request where the tools are visible; sandbox support adds the escalation fields and its conditional description paragraph. |
| Foreground result | The renderer emits the data-dependent stdout tail, then optional `[stderr]` and the stderr tail. With no output it emits exactly `(no output)`. Conditional lines are exactly `[output truncated; full output: <path-or-(unavailable)>]`, `[sandbox: file access denied under <mode> mode]`, `[timed out after <timeoutMs>ms]`, `[killed by signal: <signal>]`, and `[exit code: <exitCode>]`; the sandbox escalation and runner-failure lines are quoted in [`dsh-bash-sandbox`](../bash-sandbox/README.md). | Zero result tokens before a call. Output is bounded per stream, while each emitted line remains in history until compaction. |
| Background task context and results | Start returns exactly `started background task <taskId>`. Completion injects exactly `background bash task <taskId> finished <status>. Read its output with bash_output.` Reads return only the data-dependent delta or `(no new output)`, optionally `[some output was dropped from memory; full output: <paths-or-(unavailable)>]`, then exactly one of `[status: running]`, `[status: killed]`, `[status: killed by <signal>]`, or `[status: completed, exit code: <exitCode>]`. Kill returns `killed background task <taskId>` or `task <taskId> had already finished`. | Start and status text is small; deltas are data-dependent. The completion notice and every tool result are retained until compaction, but polling does not repeat already-delivered output. |
| Tool errors | Validation and policy failures are normalized as `Error: <message>`. This package's stable messages are `invalid command: expected a non-empty string`, `invalid description: expected a non-empty string`, `invalid timeoutMs: expected a positive number, got <value>`, `invalid escalation: sandbox_permissions requires a justification`, `invalid escalation: justification is only valid together with sandbox_permissions`, `invalid justification: expected a non-empty sentence`, `invalid task_id: expected a string, got <value>`, `task <taskId> belongs to another session`, `sandbox_permissions is not available in this composition (no sandboxing executor to escalate)`, `sandbox escalation to "<mode>" is not strictly wider than this call's current "<mode>" mode`, the approval-availability/rejection/cancellation variants, and `command aborted`. | Only the failing call adds these retained tokens; a rejected escalation does not add command output because the command does not run. |
## Known Limitations and Deferred Work