维护由数据文件生成的多语言资源清单，不手动修改页面

## 了解清单页面是由数据文件生成的 你维护的是一个精选知识库，其面向用户的输出是**生成**出来的，而不是手工撰写的。在动手之前，先理解这个划分： - **事实来源**是一组结构化数据文件：一个分类/章节树（定义锚点和目录结构），以及每个章节对应的一个条目文件。 - **生成产物**——面向人类阅读的列表文档（每种支持的语言各一份）以及任何机器可读的索引——都是由生成器脚本根据这些数据产出的。它们是可丢弃的，可按需重新生成。 - 同一份底层数据也可能为自动化代理提供运行时查询接口，因此数据质量的影响面不止于渲染出的文档。 这里通常没有应用运行时、构建流程或测试套件。每一次改动只会属于三类之一：结构化数据、工具脚本，或文档。牢记这个心智模型——它能防止最常见也最具破坏性的错误：编辑一份会被覆盖的输出文件。 ## 不改页面，修改数据后重新生成 - **绝不直接编辑生成的输出文档。** 任何编辑都会在下一次重新生成时被清空。要改变读者看到的内容，请修改底层数据。 - 要新增或修改一个条目，编辑对应章节的条目文件。 - 要新增一个章节，先编辑分类/章节树文件，再创建对应的条目文件。之后运行锚点校验工具，确认没有丢失任何被外部引用的锚点。 - 每次数据变更之后，在提交前先在本地运行生成器，刷新所有生成文件。持续集成会拒绝一个与刚生成的输出不一致的工作树——所以要重新生成，而不是靠猜测。 - 不要手工编辑机器可读的索引；它完全由生成器重新生成。 ## 填好每个条目的字段，为读者写一句说明 每个条目都是一条结构化记录，包含必填字段（稳定唯一的 id、URL、标题、分类、类型、难度等级、语言集合、添加日期、状态）以及由自动化流程填充的可选字段（存档 URL、最后检查时间戳、内容指纹）。请遵守类型、难度、语言和状态的受控词汇表——不要自行发明取值。 将条目附带的自由文本描述视为**面向公众、可供第三方阅读的文案**： - **应包含**一句描述该资源内容的事实性语句，之后可以选择性地附上作者署名。 - **应排除**任何内部信息：对本项目的引用、议题或变更请求编号、"最初由某某提议"之类的措辞，或任何历史性的元数据。版本控制历史本身已经保留了署名；外部读者不应能从条目中推断出它与本仓库之间存在任何关联。 - 除非原文有误或已过时，否则不要改动由机器迁移过来的取值。 - 只有在原作者明确要求时（例如内容需付费访问、或提出下架请求），才将某个条目排除在外部存档之外。 ## 不改各部分的链接名，让外部链接不失效 外部网站和内部目录都会指向具名锚点。重命名或删除一个已有锚点会悄无声息地破坏所有指向它的入站链接。 - **绝不重命名或删除已有的锚点。** 新章节请添加新的锚点。 - 持续集成中有一道防护会将当前的锚点集合与基线进行比对，只要基线中的任何锚点缺失就会使构建失败。把这道防护当作硬性关卡,而不是建议。 - 由于生成器会按确定的顺序（先按添加日期,再按标题）对条目排序,所以绝不要手工批量重排条目。若要把某个条目提前,应修改它的添加日期字段,而不是直接调整记录顺序。 ## 代码和说明用一种主要语言写，并决定条目收录的语言版本 项目自身撰写的内容使用一种主要语言。只有在多语言性是该产物本身固有属性的场合才会出现多种语言:翻译后的输出文档、本地化的章节标题覆写、保留资源原始语言的各条目标题,以及用来在非主要语言提示词下触发的触发短语。除此之外的一切——代码、注释、字段名、模板、流水线输出、标签、提交信息——都保持使用主要语言。 单个条目可以出现在多个语言版本中,由其语言集合字段控制: - 没有语言提示的新条目 → 只在主要语言版本中列出,并询问贡献者是否也希望加入其他语言版本。 - 与特定地区相关的资源 → 只标注该地区的语言标签。 - 真正具有跨文化通用性的经典资源 → 标注上相关的多种语言,或谨慎地使用通配符。 - 绝不要为了让各语言版本的结构保持一致,而强行翻译或强行在各版本间镜像某个条目。每个语言版本都可以包含其他版本没有的条目。 ## 采纳投稿时保留投稿者的署名 外部提交的请求有两种形式,必须妥善转入,确保署名绝不丢失: - **结构化提案（无分支）：** 直接将条目移植进数据模型,重新生成,运行校验工具,并在提交时附上co-author标注为提交者署名——这条标注是他们唯一能获得的署名。 - **直接的变更请求（贡献者已在自己的分支上编辑了文件）：** 在*贡献者自己的分支上*移植这项工作,使其变更能够带着完整署名一并合并。绝不要把贡献者的直接变更转交给某个自动化助手,让它开出自己的竞争性请求并关闭贡献者原本的请求——那样会毁掉贡献者的合并署名。 - 自动化编码助手可以作为**仅限结构化提案的异步兜底方案**,在维护者不在场、且队列必须继续推进时使用。这不是默认路径;合并前仍需由人来审核结果。这个助手节省的是打字的功夫,而不是判断力。 ## 自动检查每次改动，审查机器人只给建议 对每一次涉及数据或生成器脚本的变更,流水线应当: 1. 运行模式校验和锚点校验。 2. 重新运行生成器,如果工作树与刚生成的输出不一致就发出警告（这说明贡献者忘记重新生成了）。 3. 调用一个自动化审查机器人,依据已发布的评分标准对每个新条目打分,发布一条结构化评论,并打上建议性标签。 审查机器人的设计应偏保守:以确定性方式（而非通过模型）检测贡献者使用的语言,并将其作为指令传入;当模型调用失败时,回退到确定性的可达性和格式检查,并打上一个独立的"审查失败"标签。**机器人绝不会自动合并,也绝不会自动拒绝**——它只提供建议,决定权在人。 ## 绝不手动修改页面，规则未涵盖的改动先停下询问 不要: - 手工编辑生成的输出文档或机器可读索引。 - 重命名或删除已有的锚点。 - 在模板中引入超出项目允许标签白名单之外的标记。 - 批量重排已有条目,而不是调整排序键。 - 在未获明确要求的情况下编辑贡献指南、行为准则或工作流程定义。 - 在未获明确要求的情况下创建提交或推送。 当某项变更超出了这些规则的覆盖范围——比如新增一种语言版本、新增一个模式字段、新增一套章节分类体系——应当停下来提问,而不是自行发挥。要契合贡献指南和评分标准的精神,如有疑问,先与人确认后再行动。