docs(i18n): restore prompt-v4 as the pipeline baseline

按 jingtingxiang 拍板将 prompt 回到 v4 基线：模板正文恢复内嵌的格式/语气/句式/词汇/标点全量约束与 11 组正误例（量词规则按术语表现行裁定 package→包写作「由三个包构成的 seam」），不再注入 translation-rules.md——该文件约束人和 agent，不进模板；占位符收敛为 source_lang/target_lang/terminology 三个，切换行由模型按文档自身拼写。渲染器、解析器、conformance 门禁与单测同步回 v4 契约：三段裸 XML（translation/review/final 顺序唯一），容忍整体 ```xml 围栏回显；saxes 依赖随 CDATA 协议一并移除。
2026-07-16 00:19:25 -07:00
parent 4139e093dd
commit 60fcb494a7
6 changed files with 213 additions and 237 deletions
--- a/scripts/translation-prompt.spec.ts
+++ b/scripts/translation-prompt.spec.ts
@@ -1,5 +1,7 @@
-/** Regression tests for the executable translation prompt contract. */
+/** Unit tests for the prompt-v4 renderer and three-section response parser. */

+import { readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
 import { describe, expect, it } from 'vitest'
 import {
  parseTranslationResponse,
@@ -7,70 +9,43 @@ import {
  renderTranslationResponse,
 } from './translation-prompt.ts'

-const document = `# Wrapper
-
-## 模板正文
-
-\`\`\`\`text
-{{source_lang}} to {{target_lang}}
-{{translation_rules}}
-{{terminology}}
-[English]({{source_filename}}) | [中文]({{source_filename_zh}})
-\`\`\`\`
-`
+const root = resolve(import.meta.dirname, '..')
+const document = readFileSync(join(root, 'docs/i18n/translation-prompt.md'), 'utf8')
+const terminology = '| English | 中文 |\n|---|---|\n| agent | agent |'

 describe('translation prompt rendering', () => {
-  it('renders every supported placeholder without recursively rewriting injected rules', () => {
-    const rendered = renderTranslationPrompt(document, {
-      sourceLanguage: 'English',
-      sourceFilename: 'guide.md',
-      translationRules: 'A literal {{source_lang}} in injected rules.',
-      terminology: '| English | 中文 |',
-    })
-    expect(rendered).toContain('English to Chinese')
-    expect(rendered).toContain('A literal {{source_lang}} in injected rules.')
-    expect(rendered).toContain('[English](guide.md) | [中文](guide.zh.md)')
+  it('renders both directions with every placeholder resolved', () => {
+    const en = renderTranslationPrompt(document, { sourceLanguage: 'English', terminology })
+    expect(en).toContain('from English to Chinese')
+    expect(en).toContain(terminology)
+    expect(en).not.toContain('{{')
+    const zh = renderTranslationPrompt(document, { sourceLanguage: 'Chinese', terminology })
+    expect(zh).toContain('from Chinese to English')
  })

-  it('rejects a filename whose suffix contradicts the source language', () => {
-    expect(() => renderTranslationPrompt(document, {
-      sourceLanguage: 'Chinese',
-      sourceFilename: 'guide.md',
-      translationRules: 'rules',
-      terminology: 'terms',
-    })).toThrow('does not match source language Chinese')
-  })
-
-  it('rejects malformed template placeholders before injecting rule contents', () => {
-    expect(() => renderTranslationPrompt(document.replace('{{source_lang}}', '{{source-lang}}'), {
-      sourceLanguage: 'English',
-      sourceFilename: 'guide.md',
-      translationRules: 'A literal {{source_lang}} in injected rules.',
-      terminology: '| English | 中文 |',
-    })).toThrow('template contains malformed placeholder syntax')
+  it('rejects a template with unknown or missing placeholders', () => {
+    const alien = document.replaceAll('{{terminology}}', '{{terms_prompt}}')
+    expect(() => renderTranslationPrompt(alien, { sourceLanguage: 'English', terminology })).toThrow(/unsupported placeholder/)
+    const missing = document.replaceAll('{{terminology}}', '')
+    expect(() => renderTranslationPrompt(missing, { sourceLanguage: 'English', terminology })).toThrow(/required placeholder/)
  })
 })

-describe('translation response XML', () => {
-  it('round-trips Markdown and the CDATA terminator', () => {
-    const response = {
-      translation: '# Draft\n\nA ]]> marker.',
-      review: '- [Tone] Fixed.',
-      final: '# Final\n\nA ]]> marker.',
-    }
+describe('translation response sections', () => {
+  it('round-trips Markdown bodies', () => {
+    const response = { translation: '# 标题\n\n正文 **加粗**。', review: '- [Tone] 修正一处。\n- 无修正', final: '# 标题\n\n定稿。' }
    expect(parseTranslationResponse(renderTranslationResponse(response))).toEqual(response)
  })

-  it('rejects missing, reordered, nested, attributed, or non-CDATA children', () => {
-    expect(() => parseTranslationResponse('<dsh-translation-response version="1"/>')).toThrow('translation, review, and final')
-    expect(() => parseTranslationResponse('<dsh-translation-response version="1"><review><![CDATA[x]]></review></dsh-translation-response>'))
-      .toThrow('expected translation, got review')
-    expect(() => parseTranslationResponse(renderTranslationResponse({ translation: 'x', review: 'y', final: 'z' })
-      .replace('<translation><![CDATA[x]]></translation>', '<translation><b><![CDATA[x]]></b></translation>')))
-      .toThrow('nested element b is not allowed')
-    expect(() => parseTranslationResponse(renderTranslationResponse({ translation: 'x', review: 'y', final: 'z' }).replace('<review>', '<review lang="en">')))
-      .toThrow('review must not have attributes')
-    expect(() => parseTranslationResponse(renderTranslationResponse({ translation: 'x', review: 'y', final: 'z' }).replace('<![CDATA[x]]>', 'x')))
-      .toThrow('all response field content must be inside CDATA')
+  it('tolerates a fenced xml wrapper around the whole response', () => {
+    const fenced = '```xml\n<translation>\nA\n</translation>\n\n<review>\n- 无修正\n</review>\n\n<final>\nA\n</final>\n```'
+    expect(parseTranslationResponse(fenced).final).toBe('A')
+  })
+
+  it('rejects missing, unterminated, or duplicated sections', () => {
+    expect(() => parseTranslationResponse('<translation>\nA\n</translation>')).toThrow(/missing <review>/)
+    expect(() => parseTranslationResponse('<translation>\nA')).toThrow(/unterminated <translation>/)
+    const dup = '<translation>\nA\n</translation>\n<review>\nR\n</review>\n<final>\nF\n</final>\n<final>\nG\n</final>'
+    expect(() => parseTranslationResponse(dup)).toThrow(/duplicate <final>/)
  })
 })
--- a/scripts/translation-prompt.ts
+++ b/scripts/translation-prompt.ts
@@ -1,20 +1,16 @@
 /**
- * Executable renderer and strict response parser for the committed
- * documentation-translation prompt contract.
+ * Executable renderer and response parser for the committed
+ * documentation-translation prompt contract (prompt-v4).
+ *
+ * The v4 contract: three placeholders (`source_lang`, `target_lang`,
+ * `terminology`), whole-document translation, and a three-section response
+ * (`<translation>`, `<review>`, `<final>` in order, bare XML tags with raw
+ * Markdown bodies). The switcher filename is spelled out by the model from
+ * the document itself; the pipeline injects no other repository file.
 */

-import { basename } from 'node:path'
-import { SaxesParser } from 'saxes'
-
 /** Placeholder names supported by the committed translation prompt. */
-export const TRANSLATION_PROMPT_PLACEHOLDERS = [
-  'source_lang',
-  'target_lang',
-  'translation_rules',
-  'terminology',
-  'source_filename',
-  'source_filename_zh',
-] as const
+export const TRANSLATION_PROMPT_PLACEHOLDERS = ['source_lang', 'target_lang', 'terminology'] as const

 type TranslationPromptPlaceholder = (typeof TRANSLATION_PROMPT_PLACEHOLDERS)[number]

@@ -24,15 +20,11 @@ type TranslationLanguage = 'English' | 'Chinese'
 /** Inputs that vary for one rendered translation request. */
 export interface TranslationPromptInput {
  sourceLanguage: TranslationLanguage
-  /** Source basename, including `.md` or `.zh.md`. */
-  sourceFilename: string
-  /** Complete current `translation-rules.md` contents. */
-  translationRules: string
  /** Complete current `terminology.md` contents. */
  terminology: string
 }

-/** Parsed contents of the three-element XML response. */
+/** Parsed contents of the three-section response. */
 export interface TranslationResponse {
  translation: string
  review: string
@@ -42,7 +34,7 @@ export interface TranslationResponse {
 const PLACEHOLDER = /{{([a-z_]+)}}/g
 const TEMPLATE_OPEN = '## 模板正文\n\n````text\n'
 const TEMPLATE_CLOSE = '\n````'
-const RESPONSE_CHILDREN = ['translation', 'review', 'final'] as const
+const RESPONSE_SECTIONS = ['translation', 'review', 'final'] as const

 /** Extract the machine-consumed text fence from `translation-prompt.md`. */
 function extractTranslationPrompt(document: string): string {
@@ -61,31 +53,15 @@ export function documentedTranslationPromptPlaceholders(document: string): strin
  return [...document.slice(0, preambleEnd).matchAll(/^\| `{{([a-z_]+)}}` \|/gm)].map(match => match[1] ?? '')
 }

-/** Render one system prompt from the checked-in template and canonical rules. */
+/** Render one system prompt from the checked-in template. */
 export function renderTranslationPrompt(document: string, input: TranslationPromptInput): string {
-  if (basename(input.sourceFilename) !== input.sourceFilename) {
-    throw new Error(`translation prompt: sourceFilename must be a basename; got ${JSON.stringify(input.sourceFilename)}`)
-  }
-  const sourceIsChinese = input.sourceFilename.endsWith('.zh.md')
-  if (input.sourceLanguage === 'Chinese' ? !sourceIsChinese : sourceIsChinese || !input.sourceFilename.endsWith('.md')) {
-    throw new Error(`translation prompt: ${input.sourceFilename} does not match source language ${input.sourceLanguage}`)
-  }
-
  const targetLanguage: TranslationLanguage = input.sourceLanguage === 'English' ? 'Chinese' : 'English'
-  const sourceFilenameZh = sourceIsChinese ? input.sourceFilename : input.sourceFilename.replace(/\.md$/, '.zh.md')
  const values: Record<TranslationPromptPlaceholder, string> = {
    source_lang: input.sourceLanguage,
    target_lang: targetLanguage,
-    translation_rules: input.translationRules,
    terminology: input.terminology,
-    source_filename: input.sourceFilename,
-    source_filename_zh: sourceFilenameZh,
  }
  const template = extractTranslationPrompt(document)
-  const placeholderFreeTemplate = template.replace(PLACEHOLDER, '')
-  if (placeholderFreeTemplate.includes('{{') || placeholderFreeTemplate.includes('}}')) {
-    throw new Error('translation prompt: template contains malformed placeholder syntax')
-  }
  const names = [...template.matchAll(PLACEHOLDER)].map(match => match[1] ?? '')
  const unknown = names.filter(name => !TRANSLATION_PROMPT_PLACEHOLDERS.includes(name as TranslationPromptPlaceholder))
  if (unknown.length > 0) throw new Error(`translation prompt: unsupported placeholder(s): ${[...new Set(unknown)].join(', ')}`)
@@ -95,77 +71,37 @@ export function renderTranslationPrompt(document: string, input: TranslationProm
  return template.replace(PLACEHOLDER, (_token, name: string) => values[name as TranslationPromptPlaceholder])
 }

-/** Escape one value so it remains byte-identical inside an XML CDATA field. */
-function escapeTranslationCdata(value: string): string {
-  return value.replaceAll(']]>', ']]]]><![CDATA[>')
-}
-
-/** Serialize a response using the exact XML wire contract in the prompt. */
+/** Serialize a response in the exact three-section shape the prompt requests. */
 export function renderTranslationResponse(response: TranslationResponse): string {
-  return [
-    '<dsh-translation-response version="1">',
-    `<translation><![CDATA[${escapeTranslationCdata(response.translation)}]]></translation>`,
-    `<review><![CDATA[${escapeTranslationCdata(response.review)}]]></review>`,
-    `<final><![CDATA[${escapeTranslationCdata(response.final)}]]></final>`,
-    '</dsh-translation-response>',
-  ].join('\n')
+  return RESPONSE_SECTIONS.map(section => `<${section}>\n${response[section]}\n</${section}>`).join('\n\n')
 }

-/** Parse and validate the exact XML response shape emitted by the model. */
-export function parseTranslationResponse(xml: string): TranslationResponse {
-  const values: TranslationResponse = { translation: '', review: '', final: '' }
-  const stack: string[] = []
-  const cdataFields = new Set<string>()
-  let rootSeen = false
-  let childIndex = 0
-  const fail = (message: string): never => {
-    throw new Error(`translation response: ${message}`)
-  }
-  const parser = new SaxesParser({ xmlns: false })
+/**
+ * Parse the three-section response. Sections must each appear exactly once
+ * and in order; bodies are raw Markdown taken verbatim between the tags.
+ * A fenced ```xml wrapper around the whole response is tolerated, matching
+ * the shape some models echo back from the prompt's own example.
+ */
+export function parseTranslationResponse(text: string): TranslationResponse {
+  let body = text.trim()
+  const fenced = /^```(?:xml)?\n([\s\S]*?)\n```$/.exec(body)
+  if (fenced?.[1] !== undefined) body = fenced[1].trim()

-  parser.on('opentag', (tag) => {
-    if (stack.length === 0) {
-      if (rootSeen) fail('contains more than one root element')
-      if (tag.name !== 'dsh-translation-response') fail(`expected dsh-translation-response root, got ${tag.name}`)
-      const attributes = Object.keys(tag.attributes)
-      if (attributes.length !== 1 || tag.attributes.version !== '1') fail('root must have only version="1"')
-      rootSeen = true
-    } else if (stack.length === 1) {
-      const expected = RESPONSE_CHILDREN[childIndex]
-      if (tag.name !== expected) fail(`expected ${expected ?? 'no more children'}, got ${tag.name}`)
-      if (Object.keys(tag.attributes).length !== 0) fail(`${tag.name} must not have attributes`)
-      childIndex++
-    } else {
-      fail(`nested element ${tag.name} is not allowed`)
-    }
-    stack.push(tag.name)
-  })
-  parser.on('text', (value) => {
-    if (stack.length <= 1 && value.trim() === '') return
-    fail('all response field content must be inside CDATA')
-  })
-  parser.on('cdata', (value) => {
-    const field = stack.at(-1)
-    if (field === undefined || !RESPONSE_CHILDREN.includes(field as (typeof RESPONSE_CHILDREN)[number])) {
-      fail('CDATA is allowed only inside translation, review, or final')
-    }
-    const key = field as (typeof RESPONSE_CHILDREN)[number]
-    values[key] += value
-    cdataFields.add(key)
-  })
-  parser.on('closetag', (tag) => {
-    const expected = stack.pop()
-    if (expected !== tag.name) fail(`closing ${tag.name} does not match ${expected ?? 'nothing'}`)
-  })
-  parser.on('comment', () => fail('comments are not allowed'))
-  parser.on('doctype', () => fail('doctypes are not allowed'))
-  parser.on('processinginstruction', () => fail('processing instructions are not allowed'))
-  parser.on('error', error => fail(`invalid XML: ${error.message}`))
-  parser.write(xml).close()
-
-  if (childIndex !== RESPONSE_CHILDREN.length) fail('translation, review, and final must each appear exactly once and in order')
-  for (const field of RESPONSE_CHILDREN) {
-    if (!cdataFields.has(field)) fail(`${field} must contain a CDATA section`)
+  const values: Partial<Record<(typeof RESPONSE_SECTIONS)[number], string>> = {}
+  let cursor = 0
+  for (const section of RESPONSE_SECTIONS) {
+    const open = `<${section}>`
+    const close = `</${section}>`
+    const start = body.indexOf(open, cursor)
+    if (start === -1) throw new Error(`translation response: missing <${section}> section`)
+    const end = body.indexOf(close, start + open.length)
+    if (end === -1) throw new Error(`translation response: unterminated <${section}> section`)
+    values[section] = body.slice(start + open.length, end).replace(/^\n/, '').replace(/\n$/, '')
+    cursor = end + close.length
  }
-  return values
+  for (const section of RESPONSE_SECTIONS) {
+    const again = body.indexOf(`<${section}>`, cursor)
+    if (again !== -1) throw new Error(`translation response: duplicate <${section}> section`)
+  }
+  return values as TranslationResponse
 }
--- a/scripts/verify-translation-prompt.ts
+++ b/scripts/verify-translation-prompt.ts
@@ -18,37 +18,27 @@ function read(path: string): string {

 try {
  const document = read('docs/i18n/translation-prompt.md')
-  const translationRules = read('docs/i18n/translation-rules.md')
  const terminology = read('docs/i18n/terminology.md')
  const documented = documentedTranslationPromptPlaceholders(document)
  if (documented.join('\n') !== TRANSLATION_PROMPT_PLACEHOLDERS.join('\n')) {
    throw new Error(`placeholder table must list exactly: ${TRANSLATION_PROMPT_PLACEHOLDERS.join(', ')}`)
  }

-  const englishSource = renderTranslationPrompt(document, {
-    sourceLanguage: 'English',
-    sourceFilename: 'example.md',
-    translationRules,
-    terminology,
-  })
-  const chineseSource = renderTranslationPrompt(document, {
-    sourceLanguage: 'Chinese',
-    sourceFilename: 'example.zh.md',
-    translationRules,
-    terminology,
-  })
-  if (!englishSource.includes('[English](example.md) | 中文')) throw new Error('English-source render does not carry the Chinese switcher instruction')
-  if (!chineseSource.includes('English | [中文](example.zh.md)')) throw new Error('Chinese-source render does not carry the English switcher instruction')
+  const englishSource = renderTranslationPrompt(document, { sourceLanguage: 'English', terminology })
+  const chineseSource = renderTranslationPrompt(document, { sourceLanguage: 'Chinese', terminology })
+  if (englishSource.includes('{{') || chineseSource.includes('{{')) throw new Error('rendered prompt contains an unresolved placeholder')
+  if (!englishSource.includes('from English to Chinese')) throw new Error('English-source render does not translate into Chinese')
+  if (!chineseSource.includes('from Chinese to English')) throw new Error('Chinese-source render does not translate into English')

  const example = /```xml\n([\s\S]*?)\n```/.exec(englishSource)?.[1]
-  if (example === undefined) throw new Error('rendered prompt has no XML response example')
+  if (example === undefined) throw new Error('rendered prompt has no three-section response example')
  parseTranslationResponse(example)

-  const roundTrip = { translation: 'first ]]> pass', review: '- [None] No corrections.', final: 'final ]]> text' }
+  const roundTrip = { translation: 'first pass\n\nwith **markdown**', review: '- 无修正', final: 'final text' }
  const parsed = parseTranslationResponse(renderTranslationResponse(roundTrip))
-  if (JSON.stringify(parsed) !== JSON.stringify(roundTrip)) throw new Error('CDATA split rule does not round-trip response content')
+  if (JSON.stringify(parsed) !== JSON.stringify(roundTrip)) throw new Error('three-section response does not round-trip')

-  console.log('verify-translation-prompt: both directions render and the XML response contract parses.')
+  console.log('verify-translation-prompt: both directions render and the three-section response contract parses.')
 } catch (error) {
  const message = error instanceof Error ? error.message : String(error)
  console.error(`verify-translation-prompt: ${message}`)