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

94
scripts/verify-package-readme-model-experience.ts
View File

@@ -1,8 +1,8 @@
/**
* Doc-sync gate: require every workspace package README to explain its exact
* model-visible context surface and token behavior. Most packages require the
* canonical table; an audited allowlist requires one concise zero-effect or
* indirect-only sentence instead.
* canonical table plus an optional linked long-literal appendix; an audited
* allowlist requires one concise zero-effect or indirect-only sentence instead.
*
* Run: `tsx scripts/verify-package-readme-model-experience.ts`.
*/
@@ -15,6 +15,7 @@ const HEADING = '## Model Experience'
const LIMITATIONS_HEADING = '## Known Limitations and Deferred Work'
const TABLE_HEADER = '| Context surface | What the model sees | Token effect |'
const TABLE_DIVIDER = '|---|---|---|'
const VERBATIM_HEADING = '### Verbatim model-visible text'
const H2_HEADING = /^## .+$/
type SentenceKind = 'none' | 'indirect'
@@ -34,17 +35,13 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
'packages/code-runtime/code-runtime': { kind: 'indirect', reason: 'The service interface delegates model rendering to Code Mode in dsh-tools.' },
'packages/fs/fs': { kind: 'indirect', reason: 'The service interface delegates model rendering to dsh-tool-fs.' },
'packages/hooks/hook-protocol': { kind: 'indirect', reason: 'Only the hook bridge plugins render decoded hook output to a model.' },
'packages/sandbox/sandbox': { kind: 'indirect', reason: 'Only sandbox-consuming capabilities render enforcement facts.' },
'packages/skill/skill': { kind: 'indirect', reason: 'The provider registry delegates model rendering to dsh-tool-skill.' },
'packages/subagent/subagent': { kind: 'indirect', reason: 'The provider registry delegates model rendering to dsh-tool-subagent.' },
'packages/subagent/subagent-subprocess': { kind: 'indirect', reason: 'Only process-based subagent backends compose a child model request.' },
'packages/support/acp-snapshot': { kind: 'none', reason: 'The test harness observes and normalizes transcripts without changing live requests.' },
'packages/support/invariants': { kind: 'none', reason: 'The observer validates requests but never rewrites their context.' },
'packages/ui/app-boot': { kind: 'indirect', reason: 'Only the loaded plugin tree contributes model context.' },
'packages/ui/user-interaction': { kind: 'indirect', reason: 'Only a model-facing consumer renders human answers.' },
'packages/util/brand': { kind: 'none', reason: 'The type-only primitive is erased at compile time.' },
'packages/util/timeout': { kind: 'indirect', reason: 'Only timeout consumers render timeout outcomes.' },
'packages/web/web': { kind: 'indirect', reason: 'The provider registry delegates model rendering to dsh-tool-web.' },
'packages/workflow/workflow': { kind: 'indirect', reason: 'The service delegates parent and child model rendering to its consumer and engine.' },
}
@@ -101,12 +98,59 @@ function isEscaped(text: string, index: number): boolean {
return backslashes % 2 === 1
}
/** Validate the optional long-form literal appendix after a Model Experience table. */
function validateVerbatimTail(raw: readonly string[]): { blocks: number; titles: string[]; error?: string } {
let cursor = 0
while (raw[cursor]?.trim().length === 0) cursor += 1
if (cursor === raw.length) return { blocks: 0, titles: [] }
if (raw[cursor] !== VERBATIM_HEADING) {
return { blocks: 0, titles: [], error: `non-table content must begin with ${VERBATIM_HEADING}` }
}
cursor += 1
let blocks = 0
const titles: string[] = []
while (true) {
while (raw[cursor]?.trim().length === 0) cursor += 1
if (cursor === raw.length) break
if (!/^#### \S/.test(raw[cursor] ?? '')) {
return { blocks, titles, error: `${VERBATIM_HEADING} entries require a non-empty H4 title` }
}
const title = (raw[cursor] as string).slice('#### '.length)
const fragment = headingFragment(title)
if (fragment.length === 0) return { blocks, titles, error: 'verbatim H4 title must produce a non-empty link fragment' }
if (titles.some(existing => headingFragment(existing) === fragment)) {
return { blocks, titles, error: `verbatim H4 link fragment ${JSON.stringify(fragment)} is duplicated` }
}
titles.push(title)
cursor += 1
while (raw[cursor]?.trim().length === 0) cursor += 1
if (raw[cursor] !== '```text') {
return { blocks, titles, error: 'each verbatim entry requires an exact ```text fence' }
}
cursor += 1
const contentStart = cursor
while (cursor < raw.length && raw[cursor] !== '```') cursor += 1
if (cursor === raw.length) return { blocks, titles, error: 'unterminated verbatim ```text fence' }
if (cursor === contentStart) return { blocks, titles, error: 'verbatim ```text fence must not be empty' }
cursor += 1
blocks += 1
}
return blocks > 0 ? { blocks, titles } : { blocks, titles, error: `${VERBATIM_HEADING} requires at least one entry` }
}
/** GitHub-style fragment for the simple ASCII H4 titles allowed by this contract. */
function headingFragment(title: string): string {
return title.toLowerCase().replaceAll('`', '').replaceAll(/[^a-z0-9 _-]/g, '').trim().replaceAll(/\s+/g, '-')
}
const failures: Failure[] = []
const packageJsons = globSync('packages/*/*/package.json', { cwd: root }).sort()
const scannedPackages = new Set(packageJsons.map(path => path.slice(0, -'/package.json'.length)))
let tableCount = 0
let noneCount = 0
let indirectCount = 0
let verbatimBlockCount = 0
for (const [pkg, contract] of Object.entries(SENTENCE_MODEL_EXPERIENCE)) {
if (!scannedPackages.has(pkg)) {
@@ -126,7 +170,9 @@ for (const packageJson of packageJsons) {
continue
}
const lines = proseLines(readFileSync(abs, 'utf8'))
const text = readFileSync(abs, 'utf8')
const rawLines = text.split('\n')
const lines = proseLines(text)
const h2Headings = lines.filter(line => H2_HEADING.test(line.raw))
const modelHeadings = h2Headings.filter(line => line.raw === HEADING)
if (modelHeadings.length !== 1) {
@@ -156,11 +202,14 @@ for (const packageJson of packageJsons) {
const body = lines.slice(lines.indexOf(modelHeading) + 1)
const nextH2 = body.findIndex(line => H2_HEADING.test(line.raw))
const section = nextH2 < 0 ? body : body.slice(0, nextH2)
const nextH2Line = nextH2 < 0 ? rawLines.length + 1 : (body[nextH2] as Line).index
const rawSection = rawLines.slice(modelHeading.index, nextH2Line - 1)
const content = section.filter(line => line.raw.trim().length > 0)
const sentenceContract = SENTENCE_MODEL_EXPERIENCE[pkg]
if (sentenceContract !== undefined) {
const pattern = sentenceContract.kind === 'none' ? /^None, as .+\.$/ : /^Indirectly, through .+\.$/
if (content.length !== 1 || !pattern.test(content[0]?.raw ?? '')) {
const rawContent = rawSection.filter(line => line.trim().length > 0)
if (content.length !== 1 || rawContent.length !== 1 || !pattern.test(content[0]?.raw ?? '')) {
const prefix = sentenceContract.kind === 'none' ? 'None, as ' : 'Indirectly, through '
failures.push({ path: readme, message: `must contain exactly one sentence beginning ${JSON.stringify(prefix)} and ending with a period` })
continue
@@ -199,17 +248,36 @@ for (const packageJson of packageJsons) {
failures.push({ path: readme, message: `line ${row.index}: invalid three-column Model Experience row: ${row.raw}` })
}
}
const tableLines = new Set([header, section[headerIndex + 1], ...rows])
const extra = content.find(line => !tableLines.has(line))
if (extra !== undefined) {
failures.push({ path: readme, message: `line ${extra.index}: Model Experience table section contains non-table content: ${extra.raw}` })
if (content[0] !== header) {
failures.push({ path: readme, message: 'Model Experience table must be the first nonblank content in the section' })
continue
}
const tableLines = new Set([header, section[headerIndex + 1], ...rows])
const extra = content.filter(line => !tableLines.has(line))
if (extra.length > 0 && (extra[0]?.raw !== VERBATIM_HEADING || extra.slice(1).some(line => !/^#### \S/.test(line.raw)))) {
const first = extra[0] as Line
failures.push({ path: readme, message: `line ${first.index}: invalid content after Model Experience table: ${first.raw}` })
continue
}
const lastRow = rows.at(-1) as Line
const rawTail = rawLines.slice(lastRow.index, nextH2Line - 1)
const verbatim = validateVerbatimTail(rawTail)
if (verbatim.error !== undefined) {
failures.push({ path: readme, message: verbatim.error })
continue
}
const tableText = rows.map(row => row.raw).join('\n')
const unlinked = verbatim.titles.find(title => !tableText.includes(`](#${headingFragment(title)})`))
if (unlinked !== undefined) {
failures.push({ path: readme, message: `verbatim entry ${JSON.stringify(unlinked)} must be linked from a Model Experience table row` })
continue
}
verbatimBlockCount += verbatim.blocks
tableCount += 1
}
if (failures.length === 0) {
console.log(`verify-package-readme-model-experience: ${packageJsons.length} README(s) checked (${tableCount} tables, ${noneCount} none, ${indirectCount} indirect), all conform.`)
console.log(`verify-package-readme-model-experience: ${packageJsons.length} README(s) checked (${tableCount} tables, ${noneCount} none, ${indirectCount} indirect, ${verbatimBlockCount} verbatim blocks), all conform.`)
process.exit(0)
}