开发说明书是一套可执行契约，不是发布后不再维护的宣传材料。更新代码时要同步回答：开发者怎样使用、失败时怎样排查、运维怎样验证、交付方凭什么承诺。

事实来源优先级

当前分支可编译源码和生成输出；
自动化测试、CI workflow 与发布脚本；
CONTEXT.md、适用的 .ai/constraints、架构文档与 ADR；
配置样例和运行环境；
路线图与历史文档。

低优先级资料与源码冲突时，应更新资料或明确标记历史背景，不能用旧规划覆盖当前事实。

一次文档变更的完成标准

中英文同路径页面同时更新，标题与主要语义对应；
命令、路径、类型名、配置键和链接可由当前仓库验证；
已交付、可扩展、设计中和待交付使用明确措辞；
示例覆盖成功、拒绝、重试、租户隔离或恢复等关键失败面；
不把 at-least-once 写成 exactly-once，不把 best-effort 写成原子事务；
新增页面进入索引或被相关页面链接；
同步改 frontmatter lastUpdated，让最近更新能列到该页；
能力级变化另写更新日志，不要手写第二份页面流水账；
npm run build、内部链接、语言对齐和 git diff --check 通过。

写作要求

先交代读者要解决的问题，再解释原理和步骤。少用口号与堆叠形容词；表格只用于比较，列表只用于真正并列的信息。代码片段应短到能看出决策，并明确哪些名字来自真实源码、哪些是应用示例。

页面事实卡

动笔前记录目标读者、任务、源码 owner、声明位置、宿主装配点、配置节、成功结果、失败结果、降级行为、测试证据和未实现缺口。接口只能证明扩展点存在；实现、装配和测试同时成立，才能写成可用能力。

主题: Files 完成上传
声明: IFileStore / FinalizeUploadCommand
装配: PersistenceRegistration 中的具体 File Store
成功: 对象存在、哈希校验通过、文件记录完成
失败: 会话不存在 / 哈希冲突 / Store 不可用
缺口: 恶意内容扫描、会话过期、重复 finalize 幂等
证据: handler tests + provider parity + consumer test

事实卡不是正文模板。它防止作者只看到理想接口就写出实现更强的教程，也让审查者快速定位每项主张的依据。

示例代码标准

示例必须属于本页业务场景，不能在多个模块复制同一骨架后只换类型名。它至少要解释前置条件、稳定标识来源、失败分支、事务或幂等边界，以及返回后的业务含义。

长代码块至少有两处解释性注释，但数量不是目标。好注释回答“为什么必须这样做”，不逐字翻译语句。不能直接编译的片段在邻近正文标为“示例伪代码”“配置片段”或“响应示例”，不要把免责声明写成标题。

// 复用原业务事实的稳定标识；重试时不能重新生成随机键。
var command = new FinalizeUploadCommand(sessionId, expectedSha256);
var result = await mediator.Send(command, cancellationToken);

if (result.IsFailure)
{
    // 保留稳定 Error.Code，调用方不解析本地化错误消息。
    return result.Error.ToProblem(httpContext);
}

// 成功只代表当前实现边界，不外推尚未接入的恶意内容扫描。
return Results.Ok(result.GetValueOrThrow());

图例与可访问性

图应解释多个组件的关系、顺序、状态或所有权。Mermaid 适合流程、状态机和小型关系图；复杂架构图使用统一 SVG/HTML 生成器。两者都要能缩放、有文本替代和正文解释，关键规则不能只存在图片中。

类型名、箭头方向和部署边界必须对照源码。架构调整后执行图形源验证，并抽查中英文视觉结果；SVG XML 合法不等于内容正确。

双语同步不是机械翻译

中英文应拥有相同的信息架构、事实、示例步骤、图和链接目标，同时使用自然语言表达。不要逐字翻译术语，也不能在某一语言遗漏风险边界。

新增路径先保证相对路径成对；重命名还要同步侧边栏、交叉链接、源码事实清单、搜索关键词和重定向。

修改工作流

读取仓库规则和直接相关的架构约束；
搜索目标页、对应语言页、源码声明、装配与测试；
写事实卡，区分现状、设计和待办；
同步修改双语正文、图、源码定位和链接；
运行内容、源码、严格深度、模块和图形门禁；
静态构建并抽查桌面与移动页面；
在 PR 记录命令输出、未覆盖风险和回滚方式。

完整门禁

# 内容、双语、源码、模块和图形一致性。
npm run verify:docs
npm run verify:docs-source
npm run verify:docs-depth
npm run verify:modules
npm run verify:module-source
npm run verify:diagrams

# 类型检查、静态站点、搜索索引和补丁格式。
npm run check
npm run build
git diff --check

严格深度门禁必须归零 baseline 页面，不能靠自动填充通用段落通过。构建后检查警告、索引页数和关键交互；修改 Mermaid、代码高亮、Callout、表格或自定义组件时，至少视觉抽查一个受影响页面。

审查问题

读者能否完成真实任务并诊断主要失败？
每项“支持”“自动”“幂等”“事务内”和“生产可用”是否有实现与测试证据？
示例是否属于本模块，注释是否解释业务边界？
图是否符合当前物理架构并可放大阅读？
是否区分当前能力、扩展点、规划和部署方责任？
双语事实是否一致，链接和源码路径是否可解析？

发现实现缺口时先收缩说明书，再把功能补全项写入知识库相应架构主题。说明书诚实描述当前边界，知识库承接未来落地计划。

文档维护与事实校准