用户手册
在 User-Manual/ 目录下维护一份基于证据的 Markdown 源。发布三个版本：最终用户、管理员/操作员和技术参考。Markdown 是产品；渲染是一个独立的、可替换的步骤。
选择最小化的工作流程
- 新建手册：与用户访谈，检查仓库，提出模块映射方案，获得批准，然后使用批准的 JSON 模块文件运行
scripts/init_manual.py。 - 已有手册：阅读
User-Manual/manual.yml，检查请求的范围和相关 Git diff，然后仅更新受影响的页面和资源。 - 覆盖审计：运行
scripts/audit_manual.py，解释每个错误和警告。 - 构建：仅在审计通过后运行
scripts/build_manual.py。它会组装每个版本，然后使用manual.yml中的renderer.kind进行渲染：markdown（默认）、command或mkdocs。 - 新鲜度检查：在更新后运行
scripts/manual_state.py record --feature <dir>；如果在记录之后输入或手册输出发生变化，status会以退出码 1 退出。
init_manual.py 将构建、审计和状态脚本（以及内置样式表，位于 tools/theme/）复制到 User-Manual/tools/ 以供 CI 使用。升级此技能后，从其 scripts/ 目录刷新这些副本。当 CI 从其他位置运行脚本时，--no-tools 会跳过复制。CI 工作流程遵循 --ci-policy <file> 中的 ci: 映射，如果存在，则遵循 .specify/workflow.yml。
此技能不需要 .specify/、功能规约或任何 Spec Kit 命令。根据用户的请求、仓库证据和版本控制变更来界定工作范围。
仅路由所需内容
| 任务 | 阅读 |
|---|---|
| 发现与访谈 | discovery.md |
| 页面结构与 Markdown 语法 | content-model.md |
| 受众与语言 | audience-language.md |
| 增量更改 | incremental-update.md |
| 实体、列、枚举、ER 图 | data-reference.md |
| 渲染器、模板、品牌、HTML、PDF、RTL | publishing.md |
| API 文档 | api-docs.md |
| 发布说明与迁移指南 | release-docs.md |
| UI 截图 | ui-screenshots.md |
| 预览与发布 | preview-publishing.md |
不可协商的规则
- 要求使用英文。阿拉伯语为可选项，但页面、渲染器、图表和 PDF 必须从初始化时就支持 RTL。
- 使用通俗、自然的英文或阿拉伯文。为声明的受众编写；切勿将技术说明原封不动地用于最终用户。
- 将主张基于实现、合约、测试、观察到的行为、架构或已批准的基础设施来源。标注未知信息，切勿编造行为。
- 绝不包含机密、凭据、令牌、私钥、连接字符串、生产记录或未经编辑的个人数据。使用确定性的合成示例。
- 将已批准的、可扩展的模块映射存储在
User-Manual/manual.yml中。在批准之前，将后续发现添加为proposed。 - 保持 Markdown 规范，编写 GitHub 自身语法，使每个页面在 GitHub 上正确显示；构建过程会将其转换为其他渲染器。仅通过构建过程生成其他格式。
- 仅生成有用的图表，并在安装了
illustrate技能时使用它。保持系统概览与可读的模块级细节分开：一个系统 ER 概览加较小的模块 ER 图。记录每个有证据的实体、列、数据类型、关系、约束和枚举。 - 保留拥有标记之外的手写内容，并使重新运行收敛。
- 仅链接到其受众会接收的页面。构建过程会拒绝跨受众的页面链接和缺失的资源，并且只会暂存一个版本页面所引用的资源，因此一个受众绝不会发布另一个受众的截图或样本。
实际示例
对于“为我们的预订平台创建手册”，从路由、导航、API、测试和架构文件中识别预订、客户、支付和运营模块。请用户批准该模块映射。然后，在 User-Manual/ 下创建面向受众的教程、安全的截图、API 和数据参考、英文内容以及可选阿拉伯文内容，并以项目选择的方式渲染它：GitHub 上的 Markdown、通过 Pandoc 生成的团队 Word 模板，或包含 PDF 的 MkDocs 站点。