Orca Agent Skill 提供者路径注册表V1 支持的 Provider、放置策略与注册表变更流程【免费下载链接】orcaOrca is the ADE for working with a fleet of parallel agents. Run any coding agent with your own subscription. Available on desktop, mobile and VPS.项目地址: https://gitcode.com/GitHub_Trending/orca48/orca本文基于 Orca 仓库的参考文档 Agent skill provider paths文档标注 Last verified: 2026-08-11系统讲解 Orca 在安装 Agent Skill 时如何决定“每个已检测到的 Agent 从哪里读取技能”以及注册表本身如何受控演进。读完本文你可以掌握V1 支持矩阵中 Codex 与 Claude Code 的全局/工作区技能路径差异、Orca 的三类放置拓扑规范副本、POSIX 目录符号链接、Windows 目录联接及其独立副本兜底、“绝不替换不属于自己的路径”这一所有权边界以及新增/修改 provider 时必须满足的六项证据要求。1. 为什么要有一份“刻意很小”的路径注册表Agent Skill 的可用性取决于每个 AgentCodex、Claude Code 等自己约定的技能发现根目录。不同 Agent 的根目录各不相同且官方文档对“符号链接是否有效、父目录向上遍历是否生效”等行为的说明也不一致。Orca 把这份映射收敛为一个注册表并在文档中明确了两条设计原则只有官方文档独立确立的 provider 路径才进入 V1 支持范围文档原文为 “V1 supports only providers whose paths are independently established by official documentation”即路径必须由 provider 官方文档背书而不是靠社区经验或上游路径表同步得来。注册表刻意保持很小且不与任何社区路径表做复制或同步原文为 “The registry is deliberately small; it is not copied or synchronized from a community path table”。这避免了第三方表格中未经验证的语义例如某 provider 是否支持符号链接、是否读取嵌套目录被无声地带入安装行为。文档还给出了两条官方出处按文档原文表述不在此展开外部链接Codex 的目录位置与符号链接行为以 OpenAI 官方文档 “Build skills”其中 “where codex loads local skills” 一节为准Claude Code 的目录位置、优先级、父目录向上遍历parent traversal、实时检测与符号链接行为以 Anthropic 官方文档 “Extend Claude with skills”其中 “where skills live” 一节为准。这两条出处直接决定了后文表格中两个 provider 的“放置”差异。2. V1 提供者路径注册表核心内容文档中的完整支持矩阵如下表格内容继承自原文档未做删减Provider检测方式全局规范路径支持工作区路径支持Orca 放置策略Codex通过 Orca 的 host-owned PATH 检测发现codexCLI直接读取$HOME/.agents/skills从当前目录一路向上直到仓库根目录读取.agents/skills仅规范副本Canonical copy onlyClaude Code通过 Orca 的 host-owned PATH 检测发现claudeCLI读取$HOME/.claude/skills从启动目录一路向上直到仓库根目录读取.claude/skills并在文件被访问时包含嵌套目录POSIX 上使用相对目录符号链接Windows 上使用目录联接junction或经验证的独立副本兜底三个关键概念解释host-owned PATH 检测Orca 不使用用户 shell 的环境而是用自己持有的 PATH 视图来探测codex/claude可执行文件是否存在。这与仓库中 TUI Agent 检测配置 的设计一致每个 Agent 声明detectCmdCodex 为codexClaude 为claude必要时还有detectCmdAliases、detectRequiredCommands与平台级不支持的运行环境detectUnsupportedRuntimes。安装目标注册表 的注释也写明安装目标 id 与tui-agent-config.ts中的检测 id 一一对应因此“检测到的 Agent”可以直接映射为“放置目的地”。规范副本canonical copyOrca 管理的技能统一存放在规范根作用域/.agents/skills/技能名全局作用域下为$HOME/.agents/skills工作区作用域下为目录/.agents/skills。Codex 在两个作用域都直接读取这个根目录因此不需要任何额外放置动作。放置placement对不直接读取.agents/skills的 provider如 Claude CodeOrca 需要把规范副本“投影”到该 provider 自己文档化的目录.claude/skills下。投影方式即上表最后一列所说的三种拓扑。一个容易忽略的推论文档原文Codex 因此不需要 provider 专属放置而 Claude Code 的官方文档并未把.agents/skills列为发现根所以 Orca 必须把它文档化的.claude/skills路径“调和reconcile”回规范副本——这就是“placement”机制存在的根本原因。3. 注册表在源码中的落点文档描述的是“行为契约”源码中对应三块实现3.1 目的地解析resolveSkillProviderDestinations目的地解析实现 接收scope: global | workspace、homeDirectory、workspaceDirectory与已检测到的 provider 列表为每个受支持的 provider 计算放置根路径const canonicalRoot join(scopeRoot, .agents, skills) // ... const segments input.scope global ? provider.globalSegments : provider.workspaceSegments const rootPath overriddenRoot ? overriddenRoot : segments ? join(scopeRoot, ...segments) : canonicalRoot const readsCanonicalRoot normalizedPath(rootPath) normalizedPath(canonicalRoot)要点每个 provider 定义globalSegments/workspaceSegmentsnull段表示该 Agent 在该作用域直接读取规范根.agents/skills因此自身无需放置注册表注释原话“it reads the canonical.agents/skillsroot at that scope, so it needs no placement of its own”。Codex 在两个作用域都是null与文档中 “Canonical copy only” 完全对应。两个 provider 的计算出的根若指向同一个非规范路径会抛出skill-install-provider-root-collision防止两个别名互相覆盖。providerRootOverrides仅对全局作用域生效允许对全局根做显式覆盖例如 SSH 主机上 home 目录不同的场景这是“local、paired-runtime 与 SSH 三类 host-owned 路径解析”在代码侧的挂载点。从源码结构看注册表常量 当前还列出了 Cursor、Gemini CLI、Droid、Continue、Trae、Grok、Augment 等 provider 的放置段例如 Cursor 为[.cursor, skills]全局、工作区nullGemini 为[.gemini, skills]全局。注意这里的边界参考文档定义的 V1 受控支持矩阵只收录 Codex 与 Claude Code 两个由官方文档独立背书的 provider源码注册表中的其他条目是放置能力扩展其各自语义如符号链接是否被该 Agent 跟随不等同于文档 V1 表中的证据等级。3.2 放置调和reconcileSkillProviderPlacement放置调和实现 是文档最后一句“Orca never replaces a path it does not own”的落地处。核心函数reconcileSkillProviderPlacement的行为若destination.readsCanonicalRoot为真即 Codex 这类情况直接返回null不做任何放置——这就是 “Codex therefore needs no provider-specific placement” 的代码形态。放置目标路径为join(destination.rootPath, skillName)。已存在目标时走reconcileExistingPlacement不存在时走createMissingPlacement。别名symlink/junction的创建策略createProviderAliasWindows 上使用symlink(..., junction)创建目录联接POSIX 上先对父目录与规范路径做realpath再用相对路径symlink(relative(realParent, realCanonical), destinationPath, dir)创建相对符号链接——与文档中 “Relative directory symlink on POSIX, directory junction on Windows” 一一对应。所有权保护已存在的符号链接若不是 Orca 自己创建的aliasTargets校验失败或realpath后不指向规范路径返回status: skipped并标记skill-placement-unowned-link已存在的普通目录若不是 Orca 拥有返回skill-placement-unowned并跳过只有“破损的自有别名”指向已失效目标的 Orca 自有符号链接才会被删除后重建。3.3 独立副本兜底与安装回执install receipt文档最后一句“If alias creation is unavailable, the verified copy fallback is tracked in the install receipt so update and removal can detect drift.” 对应的实现链条别名失败即回退副本创建缺失放置 中createProviderAlias抛错时observation.copyFallback置位随后以topology: independent-copy写入一个经验证的独立副本。“验证”指摘要比对副本创建实现 中的createVerifiedSkillPlacementCopy先把规范副本复制到临时目录再对源与副本各自执行observeSkill若observedDigest不一致则抛skill-placement-copy-digest-mismatch校验通过后才原子rename到目标位置。回执结构安装回执 V1 定义了SkillInstallReceiptV1其中placements: SkillPlacementResult[]逐条记录每个 provider 的path、topologyprovider-alias或independent-copy与statusinstalled/unchanged/skipped/failed以及packageDigest、scope、canonicalPath等字段回执文件以规范路径的 SHA-256 命名存放在状态目录的receipts/子目录中。漂移检测调和时若回执表明该目标是independent-copy会重新观察该副本的摘要——摘要与回执中的packageDigest不符说明副本已被外部修改skill-placement-modified-copy跳过并告警摘要与新包不一致则用replaceOwnedSkillPlacementCopy整体替换。这正是“update and removal can detect drift”的机制。4. 发现Discovery侧如何消费这套路径放置解决的是“写入”发现解决的是“扫描”。Orca 的技能发现把多个根目录统一建模后再扫描、去重发现实现 中的discoverSkills接收repos、homeDir、cwd与providerRootOverrides由 发现源构建逻辑 生成全局根如~/.claude/skills、~/.agents/skills、仓库根repo/.agents/skills、repo/.claude/skills等及嵌套目录源码注释明确解释了文档表中“从启动目录/当前目录一路向上”的语义来源~/.claude/skills这类路径可能同时是 home 根和仓库根当 home 目录本身就是工作区时二者扫描深度不同靠sourceKind区分同一技能文件经多条根路径可达时mergeScannedSkill以规范文件路径去重同时合并rootPaths与providers保证设置页的 provider 徽标/过滤器不漏报单根不可达时降级为unavailable并沿用“最后一次已知扫描结果”避免一个慢根拖垮整体发现scanRootShared中的注释详细说明了这一取舍。这些行为与文档注册表的“Workspace support”一列相互印证工作区支持不是简单的固定路径而是“当前目录/启动目录 → 仓库根”的向上遍历且 Claude Code 场景下嵌套目录会在文件被访问时纳入。5. 注册表变更流程Registry change process文档对“向注册表新增/修改 provider”设定了硬性流程每次注册表变更都必须走正常代码评审并且同时提供以下全部证据链接当前 provider 官方文档中关于全局路径与工作区路径的说明记录该 provider 是否直接读取.agents/skills以及其文档化的符号链接行为在 provider 支持的平台上实测验证 macOS、Linux、原生 Windows 与 WSL 上“全局 文件夹工作区”两类发现演练 local、paired-runtime 与 SSH 三种 host-owned 路径解析测试别名被拒绝alias denial、破损的自有别名、独立副本漂移、更新update、回滚rollback与移除removal若放置契约发生变化同步更新混合版本mixed-version能力证据。文档最后给出反向约束不要添加任何自动化的上游路径表同步“Do not add automated upstream path-table synchronization”任何改变发现语义的 provider 版本发布都必须通过上述评审流程进入。其动机在于路径发现语义读哪个根、是否跟随符号链接、是否向上遍历属于 provider 的未承诺行为自动同步会把未经本机验证的语义带入安装行为破坏“Orca 只对自己拥有的路径负责”的边界。6. 验证入口与相关文件索引若要在当前仓库中进一步核对本篇内容可按以下路径自查参考文档本体docs/reference/agent-skill-provider-paths.md同目录还有 Agent 技能共享威胁模型、上游边界 与 技能共享 等配套参考文档。安装目标注册表与 provider 过滤src/shared/skill-install-providers.ts配套测试 src/main/skills/skill-provider-destinations.test.ts。目的地解析规范根/冲突检测/全局覆盖src/main/skills/skill-provider-destinations.ts。放置调和别名、所有权、兜底副本src/main/skills/skill-placement-reconciliation.ts以及副本验证/替换 src/main/skills/skill-placement-copy.ts、回执与漂移 src/main/skills/skill-install-provenance.ts。Agent 检测codex/claude的 host-owned PATH 探测src/shared/tui-agent-config.ts。发现与去重src/main/skills/discovery.ts、src/main/skills/skill-discovery-sources.ts。行为测试src/main/skills/skill-placement-reconciliation.test.ts、src/main/skills/skill-placement-copy-drift.test.ts、src/main/skills/skill-placement-alias-repair.test.ts、src/main/skills/skill-provider-destinations.test.ts。7. 适用前提与限制本文所述路径矩阵以文档标注的验证日期2026-08-11与当前仓库代码为准provider 官方文档若更新了发现语义例如改变根目录、废弃符号链接支持必须按第 5 节流程重新走评审不能默认旧语义仍成立。V1 支持矩阵只覆盖 Codex 与 Claude Code 两个 provider源码注册表中的其余 provider 条目属于放置能力扩展其语义证据等级以各自评审记录为准。“Orca 从不替换不属于自己的路径”意味着如果.claude/skills/技能名位置已存在非 Orca 创建的文件或符号链接对应 provider 的放置结果会是skipped而非覆盖——在排查“某个 Agent 没看到更新后的技能”时应首先检查回执中该 provider 的status与topology。【免费下载链接】orcaOrca is the ADE for working with a fleet of parallel agents. Run any coding agent with your own subscription. Available on desktop, mobile and VPS.项目地址: https://gitcode.com/GitHub_Trending/orca48/orca创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考