# scenario-script compose 内部工序，不作为 catalog 入口。 ## 目的 基于 inspect 结果编写场景剧本制品的 frontmatter 和正文。 ## 步骤 ### 1. 确定制品 ID - 从项目 `idPatterns` 中场景类型对应的 pattern 派生合法 ID - 检查与已有制品 ID 不冲突 - ID 应简短且具有业务语义 ### 2. 编写 frontmatter 从 inspect 输出的项目模板、配置和同类制品派生 frontmatter。不得自行增加项目未采用的字段或状态。 ### 3. 编写正文结构 项目有模板时服从项目模板；项目无模板时使用 `references/default-template.md` 的默认骨架。 默认骨架的要点： - 场景节点标题：主场景 `## S-NN：<名>`（H2），变体 `### S-NNa：<名>`（H3，字母后缀）。 编号匹配 `^S-\d+[a-z]?$`，允许前导零；冒号半/全角由项目模板统一。标题层级、编号 形式、冒号形式以项目配置与既有制品为准——节点标题是制品图的解析锚点（CLI 按 `^#{2,3}\s+(S-\d+[a-z]?)\s*[:：]` 识别），不得随意变更形式。一个文件可含多个节点。 - 字段块：节点标题下逐行写加粗字段——`**场景代码**: <稳定 slug>`（推荐）、 `**关联决策**: `、`**关联功能**: `。`关联决策`/`关联功能` 是机器 锚点、必需：CLI 从含"关联功能/关联决策"字样的行内提取 ID 成边，只引用制品图中 已存在的 ID。字段集允许项目模板扩展（如 `**入口编号**`），技能族只强制上述三项。 标签后只写制品 ID，标签名以项目 `relationFields` 配置为准。 - 场景先于功能制品时（发现级场景）：`**关联功能**` 行按项目模板约定处理——省略该行， 或按项目模板标注"尚无功能制品"；如实写明现状，不编造功能 ID 顶替。此时 CLI 报的 `ORPHAN_SCENARIO` warning（不阻断、exit 0）属预期，不强制消灭。功能制品后续建立后， 再补挂接并在功能制品 frontmatter `scenarios` 中回列本场景。 - `### Given`：前置条件，可构造的具体状态（文件存在与否、数据记录、环境条件）， 逐条列出；不写泛泛背景。 - `### When`：用户或外部动作，编号步骤；每步一个具体动作。 - `### Then`：可观察、可验证的结果：输出文本、退出码、状态、记录。逐条列出， 每条都能被检查真伪；不写口号、不写"用户体验良好"之类不可验证表述。 - 小节标题形式（Given/When/Then 的具体写法）从项目模板派生。 - 变体场景：分支、边界、异常写成紧随主场景的变体 `### S-NNa：<名>`，复用主场景 语境，只写与主场景不同的 Given/When/Then。每个变体同样声明字段块。 ### 4. 语言风格（结构化验收场景语体） 场景剧本的语体是结构化验收场景：写可构造的状态、具体的动作、可观察的事实。 不写宣传，不写设计理由，不写口号。 去 AI 味行文规则（空洞词、排队连接词、排比堆砌等）统一维护在 `references/writing-style.md`，编写与审阅都以该文件为准。场景层面的约束： - Given 写可构造的状态：路径、记录、配置，不写"系统运行正常"这类空话。 - When 写具体动作：命令、点击、输入，步骤编号。 - Then 写可观察事实：输出、退出码、状态、记录；数字只在真实时写。 - 不写设计理由、不写宣传、不写观点。 - 写作惯性约束（视角锁定、语体一致、一句一事、Then 写正向状态等八条）统一维护在 `references/writing-style.md` 的"写作惯性约束"节，与去 AI 味行文规则同级执行。 - 禁本机绝对路径：正文中的路径一律用项目相对路径（如 `artifacts/scenarios/...`）或 占位符（如 ``），不得出现机器私有路径。 **交付前快速检查**： - 有没有空洞词、排队连接词或排比堆砌？删（清单见 `references/writing-style.md`）。 - 词汇可懂性：正文能否通过"外行三问"、内部动词有无裸用、术语首现有无解释、slug 是否 只在字段块（检查法见 `references/writing-style.md` 的"词汇可懂性纪律"节）？ - Then 里有没有不可验证的表述？换成可观察事实。 - 正文有没有本机绝对路径？换成项目相对路径或占位符。 - `关联功能`/`关联决策` 是否只引用图中已存在的 ID？有没有编造关联？ - 关联功能存在时，功能制品 frontmatter 的 `scenarios` 是否回列了本场景（双向一致）？ 尚未挂接功能时，`关联功能` 行是否按项目模板约定省略或标注，且如实报告？ - 每个节点的字段块是否齐全（场景代码/关联决策/关联功能；发现级场景下关联功能行可 按约定省略）？ ### 5. 文件放置 - 文件名按项目制品命名模式（从已有制品扫描结果派生） - 路径按项目中场景剧本注册类型的 paths 配置 - 文件名与 ID 保持可追溯对应 ## 输出 compose 输出供 validate 和 review 消费： - 完整的制品文件内容 - 制品 ID 和路径