# 机器索引与目录数据维护指南 本指南对应平铺的metadata文件；仅因同名冲突，指南与README分别命名为`metadata-AGENTS.md`和`metadata-README.md`。本组维护机器可读索引与限定子域数据协议，是README、docs和AI引用资产之间的结构桥。 ## 约束 - 新增、删除、移动或重命名 docs 入口时，必须同步`.github/taxonomy.yml`。 - 历史路径仍需被 AI 或外部说明理解时，维护`.github/redirects.yml`。 - 术语口径变化时，同步`.github/glossary.yml`。 - 不确定的映射不要猜；先查当前文件和锚点，再修改。 - `redirects.yml`只记录已经不存在的历史路径到当前入口的映射；禁止添加指向自身的自映射。 - `redirects.yml`的`from`必须唯一，且不能仍然存在于仓库中。 ## 功法子域 - `gongfa/registry.json`是功法品级与条目数据的唯一可编辑源，Schema和冻结来源同目录维护。 - 本体主文仍是类型与语义入口；JSON只引用已有主类并附人工判定理由，不复制主父树或推广为全仓IR。 - 修改来源、内容版本或规则时遵守`gongfa/AGENTS.md`；不凭原文宣传、篇幅或候选收录状态赋级。 - 人工初评批次保存于`grade_proposals`，不能冒称实测评级或放松草案`rated`检查；表格由JSON只读输出。 - README品级块由JSON生成，运行`make check-gongfa`和`make test-gongfa`，保留真实退出码及产物。 - 功法总表`gongfa/catalog.md`与`catalog.xlsx`由同一脚本生成，输入为当前登记和历史来源材料。 - `catalog-sources.json`只索引不可变来源快照的路径/SHA/范围，不持有活跃登记或新评级，不是第二可编辑登记。 - 来源快照保留其历史编者意见；当前登记状态以登记源为准，不同限定内容和同名条目不自动合并或继承品级。 - 更新后运行`make sync-gongfa-catalog`、`make check-gongfa-catalog`及`make test-gongfa-catalog`，不手改生成视图。 ## 法器总分类登记 - `faqi.json`是法器总分类登记的唯一可编辑源：包含固定来源实现初审、Vibe Coding依赖图具名对象/实例、用户确认纳入的依赖类别、暂定品级记录及外部资源逐ID分流；字段契约由`faqi.schema.json`约束。 - 类型只引用唯一本体；FaQi使用的原资源ID、名称、地址、状态、验证状态和风险按固定外部来源路径保存在`.github/context/faqi/data.json`的`documents`中，不另建资源登记或恢复外部资源集合。 - 程序内容、运行实例、模型、服务、硬件、信息内容、过程、地址及账号按真实所指分离；用户可确认依赖类别纳入范围，但该确认不自动补出具体产品身份、版本或任务效果等级。 - 来源用途是人工初审标注，Schema/后缀/SHA不能证明语义正确；`exclusion_evidence`不能作为纳入对象实现来源。每个空纳入入口至少有一条显式排除记录；同一入口可列多项排除对象，按入口路径与名称去重，排除来源分别唯一绑定，不能静默复入。 - `faqi-grade-vocabulary-v1`仍为draft且效能结果带阈值未校准；正式效能评级与当前`provisional_grade_assignments`的重要性分级是不同轴。用户要求暂按Vibe Coding核心模型/Agent、代码执行与变更基础、质量/上下文/产品交付增强、可替代专用支路分层；各阶初中高表示阶内重要性，不表示效果或实现质量。运行时对象正式`grade_id`仍为null，效能验证仍为false。 - 固定来源修订、原字节SHA与一基半开选区；新内容/版本重新核身份，不继承旧能力，不覆盖旧Git来源事实。当前法器登记以单一顶层`source_revision`绑定父仓库来源，校验器要求所有父仓库来源使用同一修订；重采样父仓库修订时须重新核对并绑定全部父仓库选区，不能只给单条来源改版本。旧登记状态由不可改写的Git历史保留。仓库目录迁移只更新当前定位路径，校验按固定修订回读原路径，并仅接受批准根路径前缀变化及 Codex 安装脚本及配套 README 中同仓 raw 地址的 `develop` → `main` 迁移；其他指令、来源域名/所有者、原 SHA 与选区继续严格核对；submodule URL与gitlink修订仍须一致。依赖图文本SHA与观测时间分别绑定，不冒称固定源码来源。父仓库实现/支持来源字节或选区变更时，仍须创建可追溯修订并重核、重绑全部父仓库来源；`test-faqi-catalog.py`要求`source_revision`在`origin/main`历史可达，Squash合并不会把PR分支源提交带入`main`，不可让登记自指最终合并提交。`references`则描述当前仓内软链接别名，不是来源选区：可在固定`source_revision`保留历史0字节占位状态的前提下，将当前状态更新为软链接；仅当当前相对目标精确匹配登记值、规范化后指向`.gitmodules`已登记submodule、关联对象的实现仓库匹配，且历史blob为相同链接目标或0字节时接受。此转换不改变其他父仓库源选择；未知历史状态、越界或未登记目标仍拒绝。 - `.github/context/faqi/README.md#法器总表`只读生成；运行`make sync-faqi-catalog`、`make check-faqi-catalog`、`make test-faqi-catalog`，保留真实工件。 ## 验证 ```bash make check-metadata make check-faqi-catalog make test-faqi-catalog make check-gongfa make test-gongfa make test ```