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

docs: gate concise model experience summaries

Browse Source
This commit is contained in:
Tianyi Cui
2026-07-13 15:47:46 +08:00
parent 08b5c4d1c8
commit 7195d9eda2
20 changed files with 105 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
packages/bash/bash/README.md
View File

@@ -38,9 +38,7 @@ The seam also owns the per-session mode override vocabulary (the sandbox RFC §
## Model Experience
| Context surface | What the model sees | Token effect |
|---|---|---|
| None directly | This interface registers no prompt, tool schema, or message. `dsh-tool-bash` turns an implementation's stdout, stderr, task state, and sandbox facts into model-visible tool results and guidance. | Zero direct tokens. Result size and sandbox state affect input tokens only when a consumer renders them. |
Indirectly, through `dsh-tool-bash`, which turns executor output and sandbox facts into guidance and retained tool-result tokens.
## Known Limitations and Deferred Work

4
packages/code-runtime/code-runtime/README.md
View File

@@ -20,9 +20,7 @@ Semantics every implementation must honor (contract details in the class JSDoc):
## Model Experience
| Context surface | What the model sees | Token effect |
|---|---|---|
| None directly | The seam receives a program and host bindings but registers no prompt, schema, or message. Code Mode in `dsh-tools` exposes the SDK and `run_code`, then converts `CodeRunResult` into the outer tool result. | Zero direct tokens. Program logs, values, and failures affect the conversation only through the Code Mode consumer. |
Indirectly, through Code Mode in `dsh-tools`, which exposes `run_code` and returns program logs, values, or failures as retained tool-result tokens.
## Known Limitations and Deferred Work

4
packages/fs/fs/README.md
View File

@@ -45,9 +45,7 @@ This package declares three events (see the generated [events catalog](../../../
## Model Experience
| Context surface | What the model sees | Token effect |
|---|---|---|
| None directly | The provider seam registers no prompt or tool. `dsh-tool-fs` converts provider text and structured `FsError` values into model-visible read, write, and edit results; policy listeners can change which outcome it receives. | Zero direct tokens. File content and errors enter context only through a consumer, whose window and byte caps determine result size. |
Indirectly, through `dsh-tool-fs`, which renders provider text and errors as bounded, retained filesystem tool results.
## Known Limitations and Deferred Work

4
packages/hooks/hook-protocol/README.md
View File

@@ -31,9 +31,7 @@ Like every event they must sit inside an open turn. The mid-turn points (`PreToo
## Model Experience
| Context surface | What the model sees | Token effect |
|---|---|---|
| None directly | This library registers nothing. Its `hook/invoked` and `hook/result` events are log-only and do not enter derived messages; bridge packages decide whether parsed `additionalContext`, blocks, or continuation feedback reach the model. | Zero direct tokens. Persisted hook audit records add no context tokens. |
Indirectly, through `dsh-hooks-claude` and `dsh-hooks-codex`, which can turn parsed hook output into prompt context, blocked outcomes, or continuation feedback.
## Known Limitations and Deferred Work

4
packages/sandbox/sandbox/README.md
View File

@@ -12,9 +12,7 @@ Implementations: [`@deepseek-ai/dsh-sandbox-local`](../sandbox-local/) (Linux: `
## Model Experience
| Context surface | What the model sees | Token effect |
|---|---|---|
| None directly | This seam registers no prompt, schema, or message. A consumer may expose configured mode, enforcement, denial, or `SANDBOX_UNAVAILABLE` facts in its own guidance or result. | Zero direct tokens. Confinement changes model-visible text only through the consuming capability. |
Indirectly, through consumers such as `dsh-bash-sandbox`, which may expose enforcement, denial, or sandbox-unavailable facts in schemas or results.
## Known Limitations and Deferred Work

4
packages/skill/skill/README.md
View File

@@ -37,9 +37,7 @@ The registry does not render model guidance or register model-facing tools. [`@d
## Model Experience
| Context surface | What the model sees | Token effect |
|---|---|---|
| None directly | The registry renders nothing and registers no tool. `dsh-tool-skill` turns `list()` summaries into a session prefix and a selected `get()` body into a tool result; provider failures can remove entries from that request's catalog. | Zero direct tokens. Catalog size, descriptions, and loaded body length affect context only through the consumer. |
Indirectly, through `dsh-tool-skill`, which renders provider summaries into the session prefix and loaded instructions into retained tool results.
## Known Limitations and Deferred Work

4
packages/subagent/subagent-subprocess/README.md
View File

@@ -41,9 +41,7 @@ A per-run isolated config directory for an external CLI child (the target of `CL
## Model Experience
| Context surface | What the model sees | Token effect |
|---|---|---|
| None directly | This process utility registers no provider, prompt, tool, or message. A consuming backend's child application decides the child's model context; environment scrubbing and isolated config directories prevent ambient credentials and user state from silently changing that composition. | Zero direct tokens. It can indirectly stabilize child context, but it adds no text to parent or child requests. |
Indirectly, through process-based subagent backends, whose child composition is constrained by credential scrubbing and isolated config directories.
## Known Limitations and Deferred Work

4
packages/subagent/subagent/README.md
View File

@@ -62,9 +62,7 @@ The current model-facing tool collects synchronously: it awaits the child result
## Model Experience
| Context surface | What the model sees | Token effect |
|---|---|---|
| None directly | The provider registry registers no prompt or tool. Provider lifecycle makes a bound `dsh-tool-subagent` schema appear or disappear, and `inheritsParentContext` selects truthful fresh-versus-fork wording. Run events are observe-only. | Zero direct tokens. Child prompts and final results enter model contexts only through a provider and consumer. |
Indirectly, through `dsh-tool-subagent` and registered providers, which expose delegation schemas, child contexts, and retained parent results.
## Known Limitations and Deferred Work

4
packages/support/acp-snapshot/README.md
View File

@@ -43,9 +43,7 @@ Constraints: `suite.ts` imports vitest, so the package is importable only inside
## Model Experience
| Context surface | What the model sees | Token effect |
|---|---|---|
| None in production | The test harness records, normalizes, scrubs, and compares request headers and ACP transcripts but does not alter the agent's assembled context. Replay scenarios obtain assistant chunks from `dsh-llm-replay`; record mode uses the real composition. | Zero production tokens. Replay spends no provider tokens, while record mode pays the composition's ordinary model cost; golden scrubbing changes files only, never the live request. |
None, as this test-only harness records, normalizes, and compares ACP transcripts without changing the agent's assembled model request.
## Known Limitations and Deferred Work

4
packages/support/invariants/README.md
View File

@@ -53,9 +53,7 @@ A seeded or forked session arrives with events already in its log because constr
## Model Experience
| Context surface | What the model sees | Token effect |
|---|---|---|
| None | The plugin observes and validates session events, agent states, and frozen model requests; it does not rewrite a prompt, schema, message, or stream. An invariant failure aborts the faulty turn instead of adding guidance. | Zero model tokens when checks pass; a failure prevents or ends a request rather than contributing context. |
None, as this observer only validates events and frozen requests and never rewrites prompts, schemas, messages, or streams.
## Known Limitations and Deferred Work

4
packages/ui/app-boot/README.md
View File

@@ -16,9 +16,7 @@ Bare plugin specifiers in a config (`@deepseek-ai/dsh-*`) resolve through the co
## Model Experience
| Context surface | What the model sees | Token effect |
|---|---|---|
| None directly | Boot and environment helpers load the configured plugin tree but register no prompt, schema, or message of their own. `.env`, loader diagnostics, and config-path selection are process concerns, not model context. | Zero direct tokens. The selected configuration indirectly determines which other packages contribute context. |
Indirectly, through the plugin tree it loads, which determines the prompts, schemas, messages, and model adapter in the resulting application.
## Known Limitations and Deferred Work

4
packages/ui/user-interaction/README.md
View File

@@ -25,9 +25,7 @@ This is the interface package. Model-facing consumers such as `@deepseek-ai/dsh-
## Model Experience
| Context surface | What the model sees | Token effect |
|---|---|---|
| None directly | This UI-neutral seam registers no prompt or tool. A consumer such as `dsh-tool-ask-user` turns a model call into an `ask()` request and converts the provider's human answer into a model-visible tool result. | Zero direct tokens. Question and answer size affect context only through the consumer. |
Indirectly, through consumers such as `dsh-tool-ask-user`, which return human answers as retained tool-result tokens.
## Known Limitations and Deferred Work

4
packages/util/brand/README.md
View File

@@ -27,6 +27,4 @@ This package owns ONLY the primitive — no concrete id, no runtime code beyond
## Model Experience
| Context surface | What the model sees | Token effect |
|---|---|---|
| None | `Branded<B>` is erased at compile time and registers no runtime plugin, prompt, schema, event, or message. Branded ids serialize exactly as their underlying strings when another package logs or renders them. | Zero direct or indirect token overhead beyond the string another package already chose to expose. |
None, as `Branded<B>` is erased at compile time and registers no runtime behavior.

4
packages/util/timeout/README.md
View File

@@ -43,9 +43,7 @@ Local file `read`/`write`/`edit` take no `timeoutMs`: a syscall is best-effort-a
## Model Experience
| Context surface | What the model sees | Token effect |
|---|---|---|
| None directly | This library only creates and classifies abort signals. It registers no prompt, schema, or message; consumers decide whether a timeout becomes a marker, a structured error, or no model-visible change. | Zero direct tokens. It can indirectly cap or replace a consumer's result when that consumer renders a timeout. |
Indirectly, through consumers such as `dsh-timeout-policy`, which may replace a provider result with a retained timeout error or suppress a late result.
## Known Limitations and Deferred Work

4
packages/web/web/README.md
View File

@@ -45,9 +45,7 @@ The failure branches throw `WebError`, whose structured code (plus message detai
## Model Experience
| Context surface | What the model sees | Token effect |
|---|---|---|
| None directly | The seam registers providers, not tools or prompt text. `dsh-tool-web` renders normalized search answers, sources, fetched bodies, and structured `WebError` values. Provider selection details stay internal except for an execution error. | Zero direct tokens. The seam indirectly bounds search result tokens by truncating sources to `maxResults`; all rendered size comes through a consumer. |
Indirectly, through `dsh-tool-web`, which renders normalized search or fetch data and errors as bounded, retained tool results.
## Known Limitations and Deferred Work

4
packages/workflow/workflow/README.md
View File

@@ -40,9 +40,7 @@ A child that resolves normally with a non-completed stop reason is not an infras
## Model Experience
| Context surface | What the model sees | Token effect |
|---|---|---|
| None directly | The service seam and `workflow/*` observer events register no prompt, schema, or message. `dsh-tool-workflow` renders the parent-facing contract and final value; an engine decides which child prompts run. | Zero direct tokens. Parent result and child contexts affect tokens only through the consumer and implementation. |
Indirectly, through `dsh-tool-workflow` and a workflow engine, which create child-agent requests and return a retained parent tool result.
## Known Limitations and Deferred Work