fable-artifact

Fable Artifact

将需求和证据转化为独立成篇的文档，确保其内容、结构、图表、链接和渲染结果都能单独检查。

使命

文档不能仅凭 Markdown 能解析或图表看起来精致就算成功。它必须向正确的受众传达正确的主张，忠实保留来源事实，明确呈现假设，并能在用户实际使用的媒介中正确呈现。

适用场景

• 编写 RFC、架构提案、技术报告、运行手册、决策记录、图表或丰富的独立文档；
• 将分析结果整理成持久文档；
• 根据已确定的需求或证据创建图表或交互式说明文档。

不适用场景

• 一段话即可充分回答；
• 需要修改应用逻辑本身（fable-execute）；
• 主要工作是选择数值图表类型（fable-dataviz）；
• 文档所需的事实尚未经过研究或发现。

文档分类

文档	主要约定
RFC/提案	决策、备选方案、权衡、验收/推出
架构文档	边界、数据/控制流、不变量、部署
运行手册	触发条件、前置条件、可执行步骤、回滚/升级
事件/报告	时间线/证据/影响，不得捏造因果关系
决策记录	背景、决策、备选方案、后果
图表	语义拓扑/序列/状态，而非装饰性方框
交互式说明文档	易访问的交互 + 确定的内容/来源

流程

阶段 1 — 明确受众和任务

说明谁会使用这份文档，以及它需要支持什么决策或行动。一份文档可以包含多个章节，但应有一个主要沟通目标。

阶段 2 — 建立主张/来源映射

在撰写润色后的正文之前，先识别：

• 有测量结果或来源支持的事实；
• 设计决策；
• 假设/推断；
• 未解决事项；
• 数据/可视化来源；
• 需要引用/链接的主张。

不要为了让文档显得完整而捏造示例、指标、架构组件、测试结果或引用。

阶段 3 — 根据文档类型选择结构

示例：

• RFC：背景 → 目标/非目标 → 证据 → 选项 → 决策 → 设计 → 风险 → 推出/回滚 → 验收；
• 运行手册：症状/触发条件 → 安全前置条件 → 诊断 → 操作 → 验证 → 回滚/升级；
• 架构：范围 → 上下文 → 组件/边界 → 流程 → 数据/状态 → 故障/安全 → 部署/运维 → 决策。

避免加入与文档目标无关的通用模板章节。

阶段 4 — 按语义设计图表

每个节点/边都应代表真实的组件、状态、依赖、事件或数据/控制流。存在歧义时，应标明方向/含义。

对于 Mermaid 或其他文本图表：

• 验证语法；
• 安全地为标签添加引号/转义；
• 避免绘制庞大难读的图表；
• 一个图表承载过多信息时，按问题拆分视图（上下文、容器、序列、状态）。

阶段 5 — 方便浏览并提升决策质量

使用清晰的层级和简短的章节；仅在有助于比较时使用表格；少用提示框；并酌情明确使用 Decision、Risk、Unknown、Evidence 等表述。

不要把每句话都改写成项目符号，也不要将主要决策埋在背景细节之后。

阶段 6 — 验证内部一致性

交叉检查：

• 术语/名称/版本在全文中保持一致；
• 图表与正文一致；
• 示例符合实际 API/架构；
• 链接/锚点有效；
• 建议有引用证据支持；
• 各章节均不与已采纳的设计相矛盾。

阶段 7 — 在目标媒介中渲染

如果渲染结果会影响使用体验，源文件就不是最终文档。应根据需要预览/渲染 Markdown/Mermaid/HTML/PDF/其他目标格式，并检查裁切、图表损坏、溢出、素材缺失、排版难读或交互不可访问等问题。

阶段 8 — 检查内容真实性与可用性

询问：

• 目标受众能否快速找到主要决策／行动？
• 哪些陈述是事实、提案或推断？
• 是否存在缺乏依据的主张？
• 图表是否会暗示不存在的关系？
• 未来的读者能否在没有聊天上下文的情况下执行／维护该产物？

决策规则

• 相比用看似合理的内容填补空白，优先明确标注 unknown/not checked。
• 图表应当回答一个问题；如果一个视图混合了拓扑、顺序、部署和所有权，导致难以阅读，就应拆分。
• 对于需要追溯的外部／时效性主张，应使用链接／引用；不要伪造来源。
• 生成的图表／表格应沿用 DataViz／研究资料包的数据来源信息。
• 如果产物会随设计变化而改变，完成前应协调更新每个图表／示例／决策引用。
• 交互式产物需要具备适合其用途的键盘操作／无障碍／备用方案；视觉上的新颖性不能替代有效沟通。
• 除非会实质影响决策，否则不要在面向高管／决策的产物中加入实现细节。
• 使用仓库／指定的产物存放位置；不要把文件散落在根目录／临时路径中。

不变要求

• 每项事实性主张都有来源支持，或明确标注为推断／提案。
• 不得伪造数据、引用、测试结果、架构组件或案例研究。
• 图表／正文／示例描述的是同一套设计。
• 如果交付内容包含渲染，则应检查目标渲染效果。
• 产物应能独立使用，无需依赖隐藏的对话上下文。
• 受众能够识别主要决策／行动。

失败类型

内容幻觉

用看似合理的细节填补缺失事实。应删除、研究或标记为未知。

图表语义偏移

图表不再符合当前设计，或暗示了错误流程。应重新生成／协调更新。

模板臃肿

通用章节掩盖了文档的用途。删除没有决策价值的章节。

源文件／渲染不匹配

Markdown／HTML 代码看起来有效，但目标渲染器会裁切或破坏资源／图表。应验证渲染后的输出。

内部矛盾

不同章节中的版本／名称／决策不一致。应确定唯一的规范声明映射，并协调更新。

受众不匹配

文档在技术上很完整，但对目标读者而言层次过低／过高。应围绕他们的决策／行动重新组织。

链接／来源失效

关键证据指向无效／缺失路径。应修复，或在适当情况下将相关内容保存在本地。

反模式

• 为了让提案更有说服力而伪造指标；
• 使用没有清晰连线语义、充斥装饰性方框的 Mermaid 图表；
• 不论文档用途如何，都套用通用的“概览／架构／结论”模板；
• 未经综合整理就直接复制原始研究笔记；
• 到处使用提示块；
• 未预览目标媒介，就声称内容已渲染／无障碍；
• 更新了架构正文，却让图表保持过时；
• 引用内容无法支持对应的句子；
• 在主要决策之前堆砌大量实现细节。

产物资料包

Audience / job:
Artifact type + destination:
Claim/source map:
Decisions vs assumptions vs unknowns:
Structure rationale:
Diagram(s) + question answered:
Data/source provenance:
Internal consistency checks:
Rendered validation:
Accessibility/usability check:
Known limitations:

完成标准

满足以下条件时，产物即告完成：

• 内容以证据为依据，并符合受众与用途；
• 结构有助于实现预期决策／行动；
• 图表／示例／数据在语义上保持一致；
• 明确说明未知项，而非凭空编造；
• 已验证目标渲染效果／链接／资源；
• 没有上下文的新读者也能理解并使用该产物。

渐进式资源

• 深度指南：references/source-grounded-artifact-design.md
• 现有指南：references/artifact-composition-guide.md
• 示例：examples/system-architecture-diagram.md