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

4
docs/rfc/implemented/process/2026-07-12-package-model-experience-contract.md
View File

@@ -8,11 +8,11 @@ A package README can explain APIs and runtime mechanics without answering the qu
## Decision
Every workspace package README ends with the canonical [Model Experience section](../../../cookbook/adding-a-package.md#4-write-the-package-readme), immediately before `## Known Limitations and Deferred Work`; a package on the no-limitations allowlist ends with Model Experience itself. Packages with direct, multi-surface, conditional, capped, or lifetime effects use the three-column table. Each row identifies a concrete request surface, says what the relevant model literally receives and when, and classifies the token effect. Stable source literals are quoted verbatim, with named placeholders only for interpolated values; summaries are reserved for data-dependent payloads, provider-owned text, or schemas too large to reproduce. The default subject is the conversation model; a package that invokes an auxiliary model, such as a summarizer or search provider, names that request separately. Agent-scoped visibility is stated where it changes which agent receives a contribution. Prompt text and tool schemas are described separately whenever configuration or scoping can hide one without the other.
Every workspace package README ends with the canonical [Model Experience section](../../../cookbook/adding-a-package.md#4-write-the-package-readme), immediately before `## Known Limitations and Deferred Work`; a package on the no-limitations allowlist ends with Model Experience itself. Packages with direct, multi-surface, conditional, capped, or lifetime effects use the three-column table. Each row identifies a concrete request surface, says what the relevant model literally receives and when, and classifies the token effect. Short stable source literals are quoted verbatim in the table, with named placeholders only for interpolated values. Long stable prompts or schema descriptions live in a `### Verbatim model-visible text` appendix immediately after the table, one titled `text` fence per literal, and the table links to them; long prompts do not become table-cell prose. Summaries are reserved for data-dependent payloads, provider-owned text, or schemas too large to reproduce. The default subject is the conversation model; a package that invokes an auxiliary model, such as a summarizer or search provider, names that request separately. Agent-scoped visibility is stated where it changes which agent receives a contribution. Prompt text and tool schemas are described separately whenever configuration or scoping can hide one without the other.
Every package participates. A package with no model-context effect, or one simple effect rendered entirely by another package, can join the verifier's audited sentence allowlist. It then uses exactly one sentence beginning `None, as ` or `Indirectly, through ` instead of stretching a negative fact across a three-column table. Implementations that shape results, caps, history, lifetimes, or more than one request surface keep the table even when they add zero direct prompt tokens.
`verify-package-readme-model-experience` discovers packages from `packages/*/*/package.json`, requires one sibling README and the canonical final-section order, and validates one of two package-classified bodies outside fenced code. An allowlisted package must carry exactly one sentence with its assigned prefix; every other package must carry only the exact three-column header and at least one complete row. It runs in `doc-sync` and the parallel gate runner. The check owns package classification, structural presence, shape, and order; implementation review owns coverage and the truth of the prose.
`verify-package-readme-model-experience` discovers packages from `packages/*/*/package.json`, requires one sibling README and the canonical final-section order, and validates one of two package-classified bodies. An allowlisted package must carry exactly one sentence with its assigned prefix; every other package must start with the exact three-column header and at least one complete row. Optional long literals must follow that table under the exact appendix heading, with each H4 title paired to one non-empty `text` fence. It runs in `doc-sync` and the parallel gate runner. The check owns package classification, structural presence, table and appendix shape, and order; implementation review owns coverage and the truth of the prose.
## Alternatives considered