docs: 输出语言功能文档收尾(README/design.md/计划/opencode忽略)

- README 新增 --output-language 参数表、中文模板用法、auto 推导规则与中文场景注意
- design.md §6.2.1 新增输出语言控制设计(贯通链路/auto推导/生成期强制/标签本地化);
  §7.2 十项校验清单 → 11 项(新增语言一致性维度)
- 计划文档验收复选框勾选
- .gitignore 加入 .opencode/(AI 工具本地配置不入库)
This commit is contained in:
lhl
2026-08-26 00:45:09 +08:00
parent 3f4d17cf69
commit 84d3b87da3
4 changed files with 53 additions and 3 deletions
+3 -1
View File
@@ -29,4 +29,6 @@ conversations/
# ---- IDE / 编辑器 ----
.vscode/
.idea/
.idea/
# ---- AI 工具本地配置(不入库)----
.opencode/
+27
View File
@@ -53,6 +53,33 @@ python scripts/run_trial.py `
--output output\output.docx
```
### 输出语言(--output-language
生成概要设计书正文的自然语言由 `--output-language` 控制,取值:
| 取值 | 行为 |
|---|---|
| `auto`(默认) | 跟随章节标题:标题含日文假名 → 日文;否则看规则文档主导脚本(作成说明书/记入规则为日文 → 日文) |
| `zh` | 强制简体中文(正文程序化校验:混入日文假名会被重试/硬失败) |
| `ja` | 强制日文(正文程序化校验:纯汉字段落疑似中文会被重试/硬失败) |
表格数据始终照抄源 Excel 原文(不翻译),见 design.md §7.2。
**生成中文概要设计书**需配合中文模板:
```powershell
python scripts/run_trial.py `
--template samples\概要设计书模板_中文.docx `
--output-language zh `
--output output\output.docx
```
`samples\概要设计书模板_中文.docx` 为日文模板的完整镜像(7 章锚点 `section:*` 原样保留),由
`scripts/make_zh_template.py` 生成,可随时用该脚本重新生成。
**中文场景注意**:若规则文档(作成说明书/记入规则)仍为日文,`auto` 推导会倾向日文——请显式
`--output-language zh`,不要依赖 auto。
## 测试
```powershell
+22 -1
View File
@@ -740,6 +740,22 @@ Writer Agent(每章循环)
└── LLM 生成内容 → 注入模板对应位置
```
### 6.2.1 输出语言控制(output_language2026-08 新增)
- 参数:`--output-language {auto,zh,ja}`config `WriterConfig.output_language`,默认 `auto`
- 贯通链路:`run_trial → orchestrator.generate → build_contexts → GenerationContext.output_language
→ to_vars()["language_instruction"]`(prompt 的【语言约束】段引用该变量)
- **auto 推导规则**`src/genesis/writer/language.py::resolve_expected_language`,单一事实来源):
1. 显式 zh/ja → 直接采用
2. 标题含日文假名 → ja(纯汉字标题不可靠,跳过)
3. 规则文档(write_rules/design_rulesRAG 自作成说明书/记入规则)主导脚本
4. 均无法推导 → ""unverifiable,不强制)
- **生成期强制**`WriterAgent.generate_chapter` 用 `find_language_violations` 校验正文块
paragraph/note/listheading/table 不检——标题跟随模板、表格照抄源),违规按生成失败重试
max_retries 默认 2),耗尽抛 `WriterGenerationError` 硬失败
- 影响调查标签按 output_language 本地化(`_format_impact`):zh=新建/变更/删除/警告,ja=新規/変更/削除/警告
- 中文输出需配合中文模板 `samples/概要设计书模板_中文.docx`(日文模板镜像,锚点 id 原样保留)
### 6.3 模板注入策略
- 章位置识别:模板中的 Heading 层级 / 书签 / 占位符
@@ -972,7 +988,7 @@ WriterState(会话级,跨章节共享):
生成后的全量校验,覆盖格式、内容、规则遵守、可追溯性四个维度。校验在**全章生成完成后**执行,发现问题时反馈给 Writer Agent 修正该章节,形成「QA 校验 → Writer 修正 → 重新校验」循环。
### 7.2 十项校验清单
### 7.2 校验清单11 项)
| # | 校验项 | 维度 | 方法 | 判定标准 |
|---|--------|------|------|---------|
@@ -986,6 +1002,11 @@ WriterState(会话级,跨章节共享):
| 8 | 可追溯性 | 可追溯 | 每段内容检查 source_uri 标注 | 每个断言有来源 |
| 9 | 术语一致性 | 规则 | 与统一术语表对比 | 无术语混用 |
| 10 | 章节完整性 | 内容 | 与模板章结构对比 | 所有章节已生成且无缺章 |
| 11 | 语言一致性 | 语言 | 脚本检测正文与期望语言是否一致(`language_consistency`,确定性) | 期望语言可推导时正文不混入他语言;不可推导记满分(unverifiable |
> 第 11 项为 2026-08 新增(输出语言一致性保障)。期望语言由显式 `--output-language zh/ja` 或 auto 推导
> (标题假名 → 规则文档主导脚本)得到,单一事实来源为 `src/genesis/writer/language.py`
> 表格/标题不检(表格照抄源、标题跟随模板);Writer 生成阶段同源强制(违规重试、耗尽硬失败)。
### 7.3 校验方法
@@ -98,7 +98,7 @@ python scripts/run_trial.py
- [x] 计划已获用户批准(等待二次确认开工)
- [x] 计划评审(2026-08-24,对照真实代码逐条核验,见下节)
- [x] 步骤 0-3 实施
- [ ] 验收
- [x] 验收
## 验收记录(2026-08-25,含真实 LLM 双跑)