读懂 Codex（7.24）：Skill 根目录、层级优先级与有界发现算法

Skill Loader 从项目、用户、系统、管理员、插件和额外根目录收集候选，以根顺序表达优先级；扫描并发执行但合并时恢复确定顺序，并用深度/目录/条目上限约束不可信目录树。

本节只研究“Skill 元数据发现，不加载正文”。输入是 ConfigLayerStack、cwd/project root、plugin roots、extra roots，状态由 core-skills Loader、Discovery 与 RootLoader 持有，成功输出为去重排序的 SkillMetadata、错误与不完整扫描警告。相邻章节中看起来相似的对象如果由不同组件拥有，就不能用一个布尔状态替代。

先确定边界和状态所有者

问题	本节答案
谁发起	ConfigLayerStack、cwd/project root、plugin roots、extra roots
谁拥有可变状态	core-skills Loader、Discovery 与 RootLoader
成功产物	去重排序的 SkillMetadata、错误与不完整扫描警告
不在本节内	Skill 元数据发现，不加载正文之外的上游产品策略和下游业务实现

这张表的用途不是复述名词，而是约束实现顺序：校验必须发生在副作用之前；已经提交的状态只能由原所有者撤销；只读投影不能反过来成为控制权威。

端到端调用链

按配置层收集 roots
规范化/去重 root
并发有界扫描 SKILL.md
恢复 root 优先顺序
按 canonical path 去重并分类

Skill 根目录、层级优先级与有界发现算法的端到端机制流程，展示按配置层收集 roots、规范化/去重 root、并发有界扫描 SKILL.md、恢复 root 优先顺序、按 canonical path 去重并分类 — 图 7.24-1：按配置层收集 roots → 规范化/去重 root → 并发有界扫描 SKILL.md → 恢复 root 优先顺序 → 按 canonical path 去重并分类。图中每条箭头都表示下一层只接收上一层已经确认的状态。

这条链里至少有三种时间尺度：配置或身份在 Thread 创建时冻结，Turn 内状态由 Session 串行协调，Step 级目录与能力在每次模型采样前重新捕获。若把后一个时点的新状态拿去解释前一个时点已经发出的调用，就会产生跨代错误。

源码机制拆解

根目录来源是分层的

Loader 纳入项目/配置层 skills、旧 $CODEX_HOME/skills、$HOME/.agents/skills、系统缓存 .system、管理员 /etc/codex/skills、插件和 extra roots；还从 project root 到 cwd 逐级寻找 .agents/skills。

这项约束直接决定了边界两侧的数据形状。实现时应先证明前置状态，再写入由 core-skills Loader、Discovery 与 RootLoader 持有的对象；不能用日志、UI 状态或模型描述代替真实状态更新。

扫描有硬上限

默认最大扫描深度 6、目录 2000、条目 20000；同时限制并发 root 扫描和 skill 加载。达到上限会形成 incomplete inventory 警告，不能把“没发现”解释成目录一定不存在。

并发不改变优先级

多个 root 可以并发读取以降低延迟，但 RootLoader 在 merge 前恢复原 root index；相同 canonical SKILL.md 只保留高优先级首次出现项。

发现阶段只探测入口和元数据

扫描定位 SKILL.md，可探测 agents/openai.yaml 接口元数据；正文的完整内容留给明确触发后的注入阶段。

Python 风格伪代码

下面的伪代码提炼状态机与错误顺序，不逐行翻译 Rust，也不假装 Python 对象具有 Rust 的所有权保证：

async def discover_skills(config, cwd):
    roots = dedupe_roots(collect_roots_by_precedence(config, cwd))
    scans = await bounded_gather(
        [scan_root(r, max_depth=6, max_dirs=2000, max_entries=20000)
         for r in roots], limit=8)
    scans.sort(key=lambda scan: scan.root_index)

    seen = set(); skills = []; warnings = []
    for scan in scans:
        warnings.extend(scan.warnings)
        for skill in scan.skills:
            key = canonical(skill.skill_md)
            if key not in seen:
                seen.add(key); skills.append(skill)
    return SkillLoadOutcome(skills, warnings, incomplete=any(s.truncated for s in scans))

阅读这段伪代码时要检查三件事：第一，输入是否在副作用前完成规范化；第二，异步等待是否仍携带原 Thread/Turn/Step 身份；第三，失败后究竟释放了什么、又保留了什么。只写快乐路径会把本节最重要的一致性条件删掉。

失败、取消与恢复

Skill 根目录、层级优先级与有界发现算法的三类失败分支、可观察结果和恢复责任 — 图 7.24-2：失败不会抹掉已经提交的状态；每条分支都由拥有该状态的组件执行恢复或补偿。

故障点	已发生的状态	可观察结果	恢复责任
目录树超过上限	已发现前缀仍保留	返回技能+不完整警告	缩小 root/清理目录
符号链接/隐藏项不符合策略	不会跟随或纳入	候选缺失	按 discovery policy 调整结构
两个 root 指向同一 Skill	canonical path 相同	高优先级一项胜出	不重复注入

取消不自动等于回滚，列表不自动等于权威存储，模型看见的描述也不自动等于已经获准执行。对于已经建立的 Thread、写入的 Edge、入队的 Mailbox、安装的插件或外部工具副作用，必须由相应所有者执行显式关闭、补偿或保留。

并发与一致性不变量

同一身份不能在并发路径中被重复预留或重复注册；若允许幂等重试，幂等键必须是稳定路径、ThreadId、request id 或 catalog revision，而不是展示名称。
一次模型采样看见的 Prompt、工具目录和执行入口必须来自同一个 Step 快照；刷新只影响后续 Step。
Watch/Activity/事件是通知机制，不是状态本身。被唤醒后必须重新读取 Registry、Session、Mailbox、Store 或 Binding 的权威值。
失败路径不得“为了干净”删除仍可恢复的历史；同样也不得把只剩历史的对象伪报成当前仍驻留运行。

设计思路与代价

本节设计保护的核心不变量是：Skill Loader 从项目、用户、系统、管理员、插件和额外根目录收集候选，以根顺序表达优先级；扫描并发执行但合并时恢复确定顺序，并用深度/目录/条目上限约束不可信目录树。代价是同一个功能会跨越地址、配置、Session、队列、存储或扩展适配层，测试也必须覆盖正常、并发和中途失败。更短的单体实现虽然容易演示，却无法区分“存在、已加载、正在运行、可恢复、已关闭、模型可见”这些彼此独立的事实。

设计动机部分是根据生产类型、调用顺序和测试行为归纳；源码可直接证明的是字段、分支、状态所有者和失败结果。文章不会把推断写成服务端或产品层的未公开事实。

源码与测试证据

位置	能证明什么
`codex-rs/core-skills/src/loader.rs`	根目录来源、并发和扫描上限
`codex-rs/core-skills/src/loader/discovery.rs`	SKILL.md 遍历与隐藏/符号链接策略
`codex-rs/core-skills/src/root_loader.rs`	并发后恢复顺序与 canonical 去重
`codex-rs/core-skills/src/model.rs`	SkillLoadOutcome

测试/可执行检查	覆盖重点	预期
`codex-rs/core-skills/src/loader_tests.rs`	正常、边界与状态转换	应与本节不变量一致
`codex-rs/core-skills/src/service_tests.rs`	失败、并发或兼容行为	应与本节不变量一致

当前环境没有 Cargo，本轮不伪报 Rust 测试执行；验证由锁定提交下的源码—测试静态对读、源文件存在性检查、Mermaid 渲染、Astro 生产构建和公开页面检查组成。

Mini Codex 复刻建议

Mini Codex 应先复刻本节的协议不变量：明确状态所有者、稳定身份、可回滚预留、同 Step 快照、超时/取消和单一终态。平台沙箱、远程 Executor、OAuth、Backend App Route 或第三方 MCP Server 的安全性质不能由一个本地 Python mock 证明，适配器只能验证调用顺序和故障处理。

本节结论

Skill Loader 从项目、用户、系统、管理员、插件和额外根目录收集候选，以根顺序表达优先级；扫描并发执行但合并时恢复确定顺序，并用深度/目录/条目上限约束不可信目录树。掌握这一点后，再看相邻模块时就能判断它是在改变身份、运行状态、模型可见上下文、外部能力，还是仅提供观察快照。

阅读导航

上一节：V1 与 V2 协作协议的工具、地址、等待和恢复差异 · 下一节：Skill 元数据怎样进入 Prompt，全文怎样按需注入

源码依据

本文基于锁定提交 fe01054a28fa4bd04716d9ceadb410f2443a50ce 的生产代码和相邻测试静态核对。关键入口如下：

codex-rs/core-skills/src/loader.rs：根目录来源、并发和扫描上限
codex-rs/core-skills/src/loader/discovery.rs：SKILL.md 遍历与隐藏/符号链接策略
codex-rs/core-skills/src/root_loader.rs：并发后恢复顺序与 canonical 去重
codex-rs/core-skills/src/model.rs：SkillLoadOutcome