按项目规则修改技术文档，不弄坏链接

## 修改前，分清可编辑的文件和自动生成的文件 - 确定人工编写的内容、可复用的包含片段、模板、结构化数据、静态资源和生成式参考文档分别位于何处。 - 将仓库的贡献指南、风格指南、组件参考和前置元数据规则视为权威依据。 - 在变更前区分可编辑源文件、随项目引入的第三方内容和生成内容。 - 不要直接编辑随项目引入的第三方文件或生成的参考页面。应追溯到其上游源文件并在那里修正。 - 如果本地验证失败源于受保护内容，应报告负责该内容的上游来源，而不是采用本地变通方案。 ## 链接使用真实的文件路径，并核对每个目标 - 确定发布系统是否会重写源路径、移除路径前缀或为其设置别名。 - 如果构建系统按照源文件树解析链接，内部引用应使用完整源路径，即使公开 URL 更短也不例外。 - 根据实际渲染器生成的标题标识符检查锚点，包括转为小写和 slug 化的规则。 - 应验证替换链接，不要猜测。如果无法确认目标地址，则应将变更视为受阻；但已确立的迁移允许使用更安全的不带锚点 URL 时除外。 - 更改缺失资源的引用前，除可见的源文件夹外，还应检查框架的虚拟文件系统和依赖项提供的资源。 ## 用项目认可的用词，写简短直接的句子 - 使用直接、简洁的主动表达。 - 去除模糊措辞、宣传性填充内容、元评论，以及把任务描述得毫不费力的说法。 - 优先使用以读者为中心的指示；必须明确归属时，应写出产品或系统的名称。 - 使用仓库批准的术语、大小写形式、UI 操作动词和强调规则。 - 当永久性的版本引入说明用于解释某项行为从何时开始时，应保留该说明；避免使用含义会随时间失效的相对时间词。 - 将确有必要的技术术语加入范围最窄的词汇允许列表。使用规范的大小写形式，并避免采用会屏蔽无关检查的宽泛模式。 ## 填好每页的标题和说明，正确书写组件 - 包含所有必填的元数据字段，例如页面标题、预览描述和搜索关键词。 - 导航标签不得超过文档规定的限制；只有章节需要时才使用排序字段。 - 编写框架短代码或嵌入式组件前，应查阅组件参考；无效语法可能在没有明显报错的情况下生成损坏的输出。 - 遵循文档规定的客户端 UI 指令行为。如果一种隐藏机制可能永久覆盖另一种，不要同时使用这两种机制；应采用框架的初始化前遮罩模式。 - 不要仅为绕过本地构建或工作树的限制而更改全局配置。 ## 先对改过的文件做格式化和检查，需要时再检查整个网站 - 编辑后，对已变更文件运行仓库提供的格式化工具。 - 在进行更广泛的验证前，运行同时检查标记和正文的文件级范围检查工具。 - 增量工作期间优先执行有针对性的检查，以免无关失败掩盖结果。 - 如果变更影响路由、共享组件、导航、生成式参考文档或其他跨页面行为，应执行完整站点构建和链接检查。 - 如果某个一体化验证目标与当前环境不兼容，应分别运行受支持的检查，并保持配置不变。 - 无需等待额外提醒即可完成适用的验证，并报告任何无法运行的检查。 ## 一个问题只做一处小改动，并回复每条审查意见 - 每个问题只建立一个聚焦的变更集。不要把相邻清理或无关重构混入文档修正。 - 显式暂存文件。绝不要使用可能一并纳入锁文件或生成变更的宽泛暂存命令。 - 提交前检查已暂存的文件列表，并移除预期文档范围之外的所有内容。 - 确认推送目标是贡献者的派生仓库或其他获批远程仓库，而不是受保护的上游仓库。 - 将问题报告和审查建议视为需要验证的主张。更改文档前，应确认实际观察到的行为。 - 处理审查意见后，应回复每个审查讨论串，包括可能需要单独调用审查 API 的行级评论。 - 如果便捷命令不可靠，应使用已经证明能够保留标签和元数据的服务端点。 ## 删除页面或新增版本时，不留下失效链接 - 删除页面前，在人工编写的内容和导航配置中搜索该页面的 slug、标题、别名和入站引用。 - 推进版本化参考文档时，应在同一次变更中更新中央版本设置、创建新版本页面，并把最新版别名从旧版本页面移到新页面。 - 绝不要让两个版本页面同时声明同一个最新版别名。 - 对于生成式参考文档，应更改上游规范或生成器并重新生成输出；不要手动编辑生成页面。 - 保持修正范围最小，验证实际故障，并在归属或外部证据尚未确定时保留清晰的升级处理路径。