sa-doc

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

sa-doc — SA&D document generator

sa-doc — SA&D 文档生成器

One validated model, one consistent document. Every section of the output is derived from

sa-model.yaml

; a Python validator blocks generation until the model is referentially consistent. This exists because hand-written SA documents rot by copy-paste: the reviewed specimen carried 30+ cross-artifact contradictions (see ADR 0025 at the marketplace root:

docs/adr/0025-sa-doc-generates-from-central-model.md

一个经过验证的模型，一份前后一致的文档。输出内容的每个部分均源自

sa-model.yaml

；Python验证器会在模型达到引用一致性之前阻止文档生成。本工具的诞生源于手写SA文档存在复制粘贴导致的内容失效问题：经审查的样本存在30多处跨工件矛盾（详见市场根目录下的ADR 0025：

docs/adr/0025-sa-doc-generates-from-central-model.md

）。

The one rule: Source-or-TBD

唯一规则：来源明确或标记为TBD

Every value in the model and every fact in the document must trace to the user's input. If the input does not state it, the value is

TBD

— never a plausible-looking default, estimate, or example. The job is a faithful SA document, not a convincing one. This covers every kind of fact: actors, entities, fields, numbers, prices, dates, NFR metrics, field sizes and samples, cardinalities, states and triggers, security controls, architecture style/components/deployment/environments, budget amounts, citations, stakeholder interests, frequencies.

The validator cannot enforce this — it checks the model's internal consistency, and never receives the source input, so it can't tell an invented value from a real one. Faithfulness therefore rests on this rule, not on the gate. A

TBD

is a correct, tracked answer; an invented-but-reasonable value is a defect. When you are unsure whether the input stated something, it did not — write
TBD
and ask. Guessing is a defect, not a shortcut; obeying the letter here is obeying the spirit.

模型中的每个值和文档中的每个事实都必须可追溯到用户输入。如果输入未提及该内容，则对应值为

TBD

——绝不能使用看似合理的默认值、估算值或示例。本工具的目标是生成忠实于输入的SA文档，而非看似可信的文档。这适用于所有类型的事实：参与者、实体、字段、数字、价格、日期、非功能需求（NFR）指标、字段大小与示例、基数、状态与触发器、安全控制、架构风格/组件/部署/环境、预算金额、引用、利益相关者诉求、频率等。

验证器无法强制执行此规则——它仅检查模型的内部一致性，且从未接收原始输入，因此无法区分虚构值与真实值。因此，忠实性依赖于这条规则，而非验证器的检查。

TBD

是正确的、可追踪的答案；虚构但看似合理的值属于缺陷。当你不确定输入是否提及某内容时，默认视为未提及——标记为
TBD
并询问用户。猜测是缺陷，而非捷径；严格遵守这条规则才符合工具的设计初衷。

When NOT to use

禁止使用场景

One diagram or one section on demand — just draw it, no model needed.
Explaining a problem interactively →
```
problem-description
```
.
Reviewing/critiquing an existing SA document →
```
scrutinize
```
.

按需生成单个图表或单个章节——直接绘制即可，无需使用模型。
交互式问题说明 → 使用
```
problem-description
```
工具。
审查/评判现有SA文档 → 使用
```
scrutinize
```
工具。

Flow

流程

1. Intake

1. 输入收集

Gather the input (file paths, pasted text, or the conversation so far). Detect the input language → document language (an explicit language request wins). Ask the user, in one round:

Profile —
```
academic
```
(course report: adds literature, Gantt plan, budget, bibliography) or
```
professional
```
(work SDD: adds security design, deployment, test-case seed).
Output —
```
md
```
,
```
pdf
```
, or
```
both
```
.
Project name — suggest one from the input.

Working directory:

./SA-<project>/

under the current directory unless the user names another. Persist the raw input (pasted text, the relevant file excerpts, or the conversation brief) to

SA-<project>/.source/input.txt

— it is the audit trail for what the document is allowed to say, and the faithfulness check in Step 4.5 reads it.

收集输入内容（文件路径、粘贴文本或当前对话记录）。检测输入语言并以此确定文档语言（用户明确指定的语言优先级更高）。通过一轮询问向用户确认以下信息：

文档类型 —
```
academic
```
（课程报告：添加文献综述、甘特图、预算、参考文献）或
```
professional
```
（工作用SDD：添加安全设计、部署方案、测试用例种子）。
输出格式 —
```
md
```
、
```
pdf
```
或
```
both
```
。
项目名称 — 根据输入内容给出建议名称。

./SA-<project>/

，除非用户指定其他目录。将原始输入（粘贴文本、相关文件摘录或对话概要）保存至

SA-<project>/.source/input.txt

——这是文档内容范围的审计追踪依据，也是步骤4.5中忠实性检查的读取源。

2. Build the model

2. 构建模型

Write

SA-<project>/sa-model.yaml

following

references/model-contract.md

(the schema lives only there). Fill everything the input answers; for required slots the input does not answer, ask — grouped, fewest possible questions. Apply the Source-or-TBD rule (top of this file): anything the input is silent on is

TBD

(tracked), never a plausible value — this holds even where a validator warning nags you to fill a field (W6/W8/W9) or a profile requires a section (E8): satisfy the gate with a

TBD

-valued record, never manufactured content. The bundled example

${CLAUDE_PLUGIN_ROOT}/scripts/fixtures/sa-model-bookstore.yaml

shows a complete, clean model.

遵循

references/model-contract.md

（仅在此文件中定义 schema）编写

SA-<project>/sa-model.yaml

。填充输入中已明确的所有内容；对于输入未覆盖的必填项，分组询问用户，尽量减少提问次数。严格遵循来源明确或标记为TBD规则（本文档顶部）：输入未提及的任何内容均标记为

TBD

（可追踪），绝不能使用看似合理的值——即使验证器警告你需要填充字段（W6/W8/W9）或文档类型要求某章节（E8），也应使用

TBD

值来满足验证要求，绝不能生成虚构内容。附带的示例

${CLAUDE_PLUGIN_ROOT}/scripts/fixtures/sa-model-bookstore.yaml

展示了一个完整、规范的模型。

3. Validate — the gate

3. 验证——准入门槛

python ${CLAUDE_PLUGIN_ROOT}/scripts/validate_model.py SA-<project>/sa-model.yaml

Errors block generation. Fix the model; ask the user when the fix is a domain decision. Re-run until exit 0.
Warnings are shown to the user and either fixed or explicitly accepted — never silently ignored.
The TBD inventory is carried into the final summary.

Never write the document while the validator reports errors.

python ${CLAUDE_PLUGIN_ROOT}/scripts/validate_model.py SA-<project>/sa-model.yaml

错误会阻止文档生成。修复模型；若修复涉及领域决策，则询问用户。重新运行验证直到返回退出码0。
警告信息会展示给用户，要么修复要么明确接受——绝不能忽略。
TBD清单会被带入最终总结。

验证器报告错误时，绝不能生成文档。

4. Generate the document

4. 生成文档

Write

SA-<project>/SA-<project>.md

from the model using

references/template-core.md

plus the profile file (

references/template-academic.md

references/template-professional.md

). Rules:

Facts come from the model only; prose connects, never introduces.
Provenance self-check before writing: for every filled model leaf, name the input span it came from; any leaf you cannot trace, flip to
```
TBD
```
. STOP words that usually mark a guess — "probably / typically / usually / standard / e.g. / assume / should be", plus round-number metrics, sample data, prices, dates, environments, or security mechanisms with no input source. (Class-vs- instance: a concrete sourced value that merely contains such a word is fine — the target is invented content, not a literal word ban.)
Diagrams follow
```
${CLAUDE_PLUGIN_ROOT}/references/diagram-convention.md
```
— one Mermaid overview at the top, type-matched section diagrams (
```
sequenceDiagram
```
,
```
classDiagram
```
,
```
erDiagram
```
,
```
flowchart TD
```
,
```
stateDiagram-v2
```
). The data model carries both a
```
classDiagram
```
(OO/domain view) and an
```
erDiagram
```
(database view).
Emit the document-furniture markers the core template specifies (
```

```
,
```

```
) so the render step can build the contents page and page breaks.
The 13-field use case semantics in the core template are non-negotiable (postcondition = guaranteed state; extensions anchored to steps; no boilerplate).

使用

references/template-core.md

加上对应类型的模板文件（

references/template-academic.md

references/template-professional.md

），从模型生成

SA-<project>/SA-<project>.md

。规则如下：

所有事实仅来自模型；文字仅用于衔接，绝不引入新内容。
写入前的来源自查：对于模型中每个已填充的叶子节点，标注其对应的输入片段；任何无法追溯的叶子节点，均改为
```
TBD
```
。注意通常表示猜测的词汇——"probably / typically / usually / standard / e.g. / assume / should be"，以及无输入来源的整数指标、样本数据、价格、日期、环境或安全机制。（类与实例的区别：若具体来源值中包含此类词汇则没问题——目标是禁止虚构内容，而非字面禁止这些词汇。）
图表遵循
```
${CLAUDE_PLUGIN_ROOT}/references/diagram-convention.md
```
——顶部有一个Mermaid概览图，各章节使用匹配类型的图表（
```
sequenceDiagram
```
、
```
classDiagram
```
、
```
erDiagram
```
、
```
flowchart TD
```
、
```
stateDiagram-v2
```
）。数据模型同时包含
```
classDiagram
```
（面向对象/领域视图）和
```
erDiagram
```
（数据库视图）。
输出核心模板指定的文档结构标记（
```

```
、
```

```
），以便渲染步骤生成目录和分页符。
核心模板中定义的13字段用例语义不可更改（后置条件=保证状态；扩展锚定到步骤；无模板化内容）。

4.5 Faithfulness check — the anti-fabrication gate

4.5 忠实性检查——防虚构门槛

python ${CLAUDE_PLUGIN_ROOT}/scripts/check_doc_provenance.py SA-<project>/SA-<project>.md SA-<project>/sa-model.yaml

Traces every hard fact in the generated document (numbers, money, percentages, dates) back to a model value — enforcing "prose connects, never introduces" mechanically, because the validator cannot (it never sees the source). Pass

--source SA-<project>/.source/input.txt

to also accept a token that is in the input but not yet in the model. Structural numbers (section/figure/table/FR/TC ids, list markers) are exempt. Each flagged token is either a fabrication to remove, or a real value missing from the model — add it to

sa-model.yaml

and regenerate. This is a report, resolved or justified like a validator warning, not a hard block.

python ${CLAUDE_PLUGIN_ROOT}/scripts/check_doc_provenance.py SA-<project>/SA-<project>.md SA-<project>/sa-model.yaml

将生成文档中的每个硬事实（数字、金额、百分比、日期）追溯到模型中的对应值——机械地强制执行“文字仅用于衔接，绝不引入新内容”的规则，因为验证器无法做到这一点（它从未见过原始输入）。传入

--source SA-<project>/.source/input.txt

参数，可同时接受存在于输入但尚未加入模型的内容。结构性编号（章节/图表/表格/功能需求/测试用例ID、列表标记）除外。每个被标记的内容要么是需要删除的虚构内容，要么是尚未加入模型的真实值——将其添加到

sa-model.yaml

并重新生成文档。这是一份报告，需像处理验证器警告一样解决或说明理由，而非硬性阻止。

5. Render (pdf/both only)

5. 渲染（仅当输出格式为pdf或both时执行）

python ${CLAUDE_PLUGIN_ROOT}/scripts/render_doc.py SA-<project>/SA-<project>.md --pdf

Produces a self-contained HTML and prints it to PDF with headless Edge/Chrome. The renderer builds the table of contents from the

<!-- sa-doc:toc -->

marker, honours

<!-- sa-doc:pagebreak -->

, and auto-numbers figures/tables in the document language (auto-detected; override with

--lang th|en

). Add

--page-numbers

for an academic report that needs a page footer (it keeps Chrome's footer at the cost of also showing the date/URL). No browser found → the script says so and the HTML plus print instructions is the deliverable; do not treat that as a failure. Offline machines: pass

--marked-js

--mermaid-js

with local copies.

python ${CLAUDE_PLUGIN_ROOT}/scripts/render_doc.py SA-<project>/SA-<project>.md --pdf

生成独立的HTML文件，并通过无头Edge/Chrome打印为PDF。渲染器会根据

<!-- sa-doc:toc -->

标记生成目录，遵循

<!-- sa-doc:pagebreak -->

标记，并根据文档语言自动为图表/表格编号（自动检测；可通过

--lang th|en

参数覆盖）。若为学术报告需要页脚页码，添加

--page-numbers

参数（此参数会保留Chrome的页脚，但同时会显示日期/URL）。若未找到浏览器，脚本会提示说明，此时HTML文件加打印说明即为交付物；请勿将此视为失败。离线机器：传入

--marked-js

--mermaid-js

参数并指定本地文件路径。

Wrap-up

收尾

Summarize: file paths, warnings the user accepted, the TBD inventory (what is still unknown), and offer next steps —

generating-test-cases

for a test suite from the use cases, or the backlog pipeline to file open TBDs as work items. To change the document later, edit

sa-model.yaml

, re-validate, regenerate — never patch the generated file by hand.

总结内容包括：文件路径、用户已接受的警告信息、TBD清单（仍未明确的内容），并提供后续步骤选项——从用例生成测试套件的

generating-test-cases

，或将未解决的TBD项作为工作项纳入待办事项流程。若后续需要修改文档，请编辑

sa-model.yaml

，重新验证并生成——绝不能手动修改已生成的文档。

Rules

规则

Never generate while the validator reports errors.
Source-or-TBD (top of this file): never invent a domain fact of any kind — when the input is silent, record
```
TBD
```
and ask; never fill a plausible value.
Never patch the generated document directly — the model is the source of truth.
The schema is defined only in
```
references/model-contract.md
```
; do not restate it elsewhere.

验证器报告错误时，绝不能生成文档。
严格遵循“来源明确或标记为TBD”规则（本文档顶部）：绝不能虚构任何领域事实——输入未提及的内容，记录为
```
TBD
```
并询问用户；绝不能填充看似合理的值。
绝不能直接修改已生成的文档——模型是唯一的事实来源。
Schema仅在
```
references/model-contract.md
```
中定义；请勿在其他地方重述。