Workflow-skill-router

# 工作流技能路由 V2 [繁體中文](README.zh-TW.md) · [文档](https://huangchiyu.com/Workflow-skill-router/) · [路由飞行记录器](https://huangchiyu.com/Workflow-skill-router/#routing-flight-recorder) 工作流技能路由是一个为 Codex 预先执行、运行时感知的技能选择层。它使代理专注于最小的可验证执行路径，保留用户权限，并暴露运行时可以实际执行的操作。它不是权限、审批策略、沙盒或生产编排的替代品。 > 当前发布的 V2 版本：`2.0.2`。不可变的 V1.3.1 恢复路径在迁移期间仍然可用。 每个 V2 版本都是源代码绑定的。候选版本首先作为 `prepared-local-candidate`；只有经过审查的元数据更新绑定了 `release_source_revision`、记录了维护者的证明，并将 `release_lifecycle` 设置为 `reviewed-attested-publishable`，才能解锁 `CREATE_V2_RELEASE`。然后，受信任的默认分支工作流会构建、标记、证明并发布冻结的源代码。 ## 60 秒结果 给路由一个请求。它会返回一个执行信封、一个能力计划、同意边界以及继续安全执行所需的证据。公共飞行记录器显示确切的净化 MCP 请求和响应，而不是在浏览器中重新创建决策。 ```text 请求 -> 分类工作形状 -> 发现可用的运行时能力 -> 锁定明确的用户选择 -> 计划最小的路由 -> 执行、验证并披露实际的技能使用 ``` ## 插件 + MCP 与仅技能 | 能力 | 插件 + MCP | 仅技能 | | --- | --- | --- | | 路由指令 | 已包含 | 已包含 | | 个人路由配置文件 | 确定性加载、验证、优先级和预览 | 咨询解释相同的固定 JSON 合同 | | 本地持久 R0 规划和范围同意 | `plan_work`、`propose_support_consent`、`transition_support_consent`、`get_router_status` | 无法观察 | | 验证主机调度和路由验证 | 主机集成后可用 | 不可用 | | 跨进程状态和比较交换 | 取决于主机/运行时 | 不可用 | | 密封模型评估 | 需要配置适配器 | 仅手动工作流 | | 诚实运行时标签 | `bundled-local-r0` 或验证配置文件 | `skill-only-fallback` | 选择插件时，Codex 支持插件/MCP 加载。选择独立技能时，您需要指令路由或必须在不支持插件的主机上运行。`hybrid-full` 一致性标签对独立软件包不可用。 ## 五分钟插件 + MCP 快速入门 对于正常安装，固定不可变的 `v2.0.2` 市场快照： ```powershell codex plugin marketplace add eric861129/Workflow-skill-router --ref v2.0.2 codex plugin add workflow-skill-router@workflow-skill-router codex plugin list ``` 打开一个新的 Codex 任务，并要求它显示工作流技能路由器的状态。已发布的 V2 接口公开了十二种 MCP 工具：**4 种始终就绪本地**，**5 种需要验证主机**，和 3 种需要配置适配器的工具。运行时准备情况仍然是每个操作的权威。 对于正在更改或测试路由器的贡献者： ```powershell git clone https://github.com/eric861129/Workflow-skill-router.git Set-Location Workflow-skill-router codex plugin marketplace add . codex plugin add workflow-skill-router@workflow-skill-router codex plugin list python plugins/workflow-skill-router/runtime/workflow_skill_router.pyz doctor ``` 检出是当前 V2 版本的源代码。贡献者必须保持候选版本和已发布元数据的区别：后一个元数据更新绑定了 `release_source_revision` 到确切的已审查源代码 SHA，然后才能调度 `Release V2`。 `v2.0.2` 是一个不可变的 GA 标签，由受信任的发布工作流创建和验证；正常安装应固定该标签，而不是可变分支。 已发布的插件已经包含 MCP 包和 Python 运行时。需要 Node.js 24+ 和 Python 3.11+；仅在从源代码重建时需要 npm。请参阅 [插件安装](site/src/content/docs/guides/install-plugin.md)。 ## 五分钟仅技能快速入门 对于正常安装，下载 [`workflow-skill-router-skill-v2.0.2.zip`](https://github.com/eric861129/Workflow-skill-router/releases/download/v2.0.2/workflow-skill-router-skill-v2.0.2.zip) 并提取其内部的 `workflow-skill-router/` 文件夹到 Codex 技能目录中。 对于在 Windows 上从检出进行贡献的贡献者： ```powershell $Target = Join-Path $env:USERPROFILE ".codex\skills\workflow-skill-router" Copy-Item -Recurse -Force "starter\v2\workflow-skill-router" $Target Get-Content -Encoding UTF8 (Join-Path $Target "SKILL.md") | Select-Object -First 8 ``` 此软件包保留路由指令和显式选择策略，但无法证明持久恢复、完整漂移检测或密封激活。请参阅 [仅技能安装](site/src/content/docs/guides/install-skill.md)。 ## 架构：运行时能力发现优先 运行时能力发现将代理经常崩溃的五个事实分开：已安装的元数据、主机暴露、身份验证、策略资格和新鲜度。只有当风险特定要求通过时，能力才可路由。 ```mermaid flowchart LR U["用户请求"] --> R["路由器核心"] H["Codex 主机观察"] --> D["运行时能力发现"] P["插件握手"] --> D S["技能元数据"] --> D D --> R R --> E["单个 / 分阶段 / 管理目标"] E --> L["本地 R0 控制平面"] E --> V["验证主机适配器"] E --> M["配置评估适配器"] V --> A["状态、证据和审计存储"] ``` 维护者可以从 [V2 架构概述](docs/architecture/v2-overview.md) 开始。 ## 单个、分阶段和管理目标 - **单个** 处理具有一个最小主要能力的限定意图。 - **分阶段** 保留不同的阶段，并从当前证据重新路由每个阶段。 - **管理目标** 维护可恢复的工作图，尊重依赖关系，并将 Codex 目标视为主机拥有状态。 路由器不会强制每个任务进入目标编排。工作形状来自请求、依赖关系、风险和当前目标关系。 `plan_work` 将 **确定性自动分类** 与工作信封结合使用，并使用 **可选确定性配置文件** 进行用户拥有的技能树。分类器是一个有界的结构和词汇规则集，而不是语义模型；其源、置信度、修订版和原因代码与配置文件匹配源分开返回。计划的技能仍然只是意图，实际激活保持 `unverified`。显式技能锁定和同意边界仍然适用。本地路由器不会激活技能、改变原生 Codex 目标或授予部署/生产权限。 ## 显式技能锁定 当用户命名一个技能时，该选择成为权威的。路由器可以建议支持，但必须在激活前解释目的、范围、拒绝后果和上下文成本。被拒绝的支持不会进入主动选择。 在插件模式下，提案在显示问题之前会持续。后续模型转换仅分类为 `approved`、`rejected` 或 `unclear`；确定性 MCP 转换保留绑定路由，如果阶段、范围、修订版或材料上下文发生变化，则关闭失败。仅技能模式保持与咨询指令相同的交互策略，但无法声称持久强制。 当用户没有命名技能时，路由器会选择最小的足够路由，而不会反复请求对其建议的同意。在执行之前，它会声明计划的技能使用情况；在执行之后，它会报告实际使用情况和任何更改。 ## 个人路由配置文件 V2 保留了 V1 中最有价值的部分：您可以拥有技能树。个人路由配置文件将目标关键词、域、标签和工作模式映射到具有一个主要、最多三个当前阶段支持技能和每个阶段出口门的分阶段路由。 > 个人路由配置文件包含在 `v2.0.0-beta.2` 中。36 次尝试的 beta.1 模型评估是历史运行时证据，不涵盖此配置文件功能。 优先级是确定的：主机硬约束、当前请求的显式技能、工作区配置文件、个人配置文件，然后是内置路由。工作区配置文件位于 `.codex/workflow-skill-router.json`；个人配置文件位于外部路由器数据目录下。MCP 工作区读取仅在客户端广告根或 `WORKFLOW_SKILL_ROUTER_WORKSPACE_ROOTS` 下接受；模型提供的任意路径失败关闭。匹配的工作树替换个人树为一个完整的路由 - 没有隐含的深度合并。 ```powershell Copy-Item starter/v2/workflow-skill-router/assets/personal-routing-profile.example.json ./my-profile.json python plugins/workflow-skill-router/runtime/workflow_skill_router.pyz profile validate .\my-profile.json python plugins/workflow-skill-router/runtime/workflow_skill_router.pyz profile install .\my-profile.json python plugins/workflow-skill-router/runtime/workflow_skill_router.pyz profile list python plugins/workflow-skill-router/runtime/workflow_skill_router.pyz profile preview --objective "Deliver the API" --work-mode phased --domain api python plugins/workflow-skill-router/runtime/workflow_skill_router.pyz profile preview --objective "Deliver the API" --work-mode phased --domain api --explain python plugins/workflow-skill-router/runtime/workflow_skill_router.pyz profile lint .\my-profile.json ``` 生成的插件运行时支持 `profile preview --explain` 和 `profile lint`；两者都是确定性诊断，不暴露任何技能指令正文或权限。插件 + MCP 模式加载并确定性验证配置文件。仅技能读取与 `skill-only-fallback` 相同的合同，只有当主机授予对固定配置文件位置的文件系统访问权限时；否则，用户必须在对话中提供配置文件内容。它无法声称持久加载或强制执行。在两种模式下，配置文件结果为 `intended-unverified`：运行时能力发现仍然决定每个技能是否安装、暴露、兼容、授权和合格。配置文件永远不会安装技能或授予权限。请参阅 [个人路由配置文件](site/src/content/docs/concepts/personal-routing-profiles.md)。 ## MCP 工具表面 插件公开了十二种类型工具： ```text sync_runtime_context plan_work propose_support_consent transition_support_consent get_next_work validate_route record_work_event evaluate_gate get_router_status run_model_evaluation compare_evaluations export_router_artifact ``` 工具模式、风险、所需能力和备用操作由服务器使用的相同合同生成。请参阅 [生成的 MCP 参考](site/src/content/docs/reference/mcp-tools.mdx)。 ## 运行时就绪矩阵 ### 已发布 beta.3 (`published-beta.3`) | 可用性 | 工具 | 含义 | | --- | --- | --- | | `local-ready` | `plan_work`、`propose_support_consent`、`transition_support_consent`、`get_router_status` | 四个捆绑的路由器本地操作 | | `verified-host-required` | `sync_runtime_context`、`get_next_work`、`validate_route`、`record_work_event`、`evaluate_gate` | 五个操作需要验证主机权限 | | `configured-adapter-required` | `run_model_evaluation`、`compare_evaluations`、`export_router_artifact` | 三个操作需要授权评估适配器 | ### 准备好的 GA 候选版本 (`prepared-ga-candidate`) 此准备好的候选矩阵 **不包含在已发布的 beta.3** 中，并且不是已发布的 GA 版本。它仍然被检查的 `prepared-local-candidate` 生命周期阻塞，直到确切的候选 SHA 具有新鲜的最终模型证据、维护者证明、审查和受信任的元数据绑定源。 | 捆绑本地 R0 可用性 | 工具 | 含义 | | --- | --- | --- | | `local-ready` | `plan_work`、`propose_support_consent`、`transition_support_consent`、`get_router_status` | 持久本地 R0 规划、范围同意和状态 | | `conditional-local` | `get_next_work`、`record_work_event`、`evaluate_gate` | 路由器拥有图调度、报告本地进度和咨询本地门评估，仅 | | `verified-host-required` | `sync_runtime_context`、`validate_route` | 需要验证主机权限和存储 | | `configured-adapter-required` | `run_model_evaluation`、`compare_evaluations`、`export_router_artifact` | 需要授权评估适配器和证据 | 准备好的 GA 候选声明故意 **4 always local-ready + 3 路由器拥有条件本地**，而非 `7/12 local-ready`。条件本地调用仅在验证的路由器拥有工作图且无本地目标权限时成功。`get_next_work` 返回 `authority_mode=router-local` 和 `host_goal_mutated=false`；进度和本地门结果使用 `evidence_class=user-or-agent-reported-local` 和 `host_transition_authorized=false`。本地门通过是咨询性的：它不是技能激活、本地目标完成、部署批准或生产许可。显式技能锁定和同意行为不受影响。 | 运行时条件 | `get_next_work` | `record_work_event` | `evaluate_gate` | | --- | --- | --- | --- | | 有效路由器拥有图 | 路由器本地结果 | 路由器本地报告进度 | 路由器本地咨询门 | | 本地目标 | `verified-host-scheduler` | `verified-event-store` + `activation-receipt-verifier` | `verified-evidence-store` + `gate-authority` | | 缺失路由器拥有图 | `router-owned-work-graph`; 创建或重放本地 | `router-owned-work-graph`; 创建或重放本地 | `router-owned-work-graph`; 创建或重放本地 | | 损坏路由器拥有图 | 净化 `internal-error` | 净化 `internal-error` | 净化 `internal-error` | 缺少的图是本地图初始化条件，而不是发明主机回落的原因。损坏的图跨越完整性边界，仅通过 `internal-error` 返回公共安全关联；内部腐败细节保留在诊断中。本地目标工作使用上述工具特定的验证主机能力。所有不可用或不安全的分支必须 **关闭失败**。 不可用的调用返回类型为 `capability-unavailable` 的响应，并包含所需能力和备用操作。路由器永远不会伪造成功的调度器或评估结果。`latest` 兼容性通道在 V2 GA 门户通过之前保持在 V1.3.1 上。 ## 真实模型评估 **Tier 0 合同** 固定证明确定性兼容性；它们不是模型行为。行为证据需要新鲜的隔离尝试、密封的案例包、配对的基准/候选人清单、边界输出、零硬违规和受信任的审查后发布。基准臂明确为 `model-only`；候选人为 `hybrid-router`。对于同意后续，新的模型分类意图和持久的 MCP 状态机实现最终路由。 评估合同 `2.3.0` 保留当前阶段的预言机和有状态阶段转换评分，然后将每个行为运行绑定到干净的完整源修订版和验证的适配器入口点标识。运行程序在适配器调用之前和之后重新验证源和适配器，因此更改的源或复制、重命名或替换的适配器无法继续现有的运行。其六案例测试配置文件仍然为 36 次尝试和 42 个模型转换；十三案例完整门户为 78 次尝试和 96 个模型转换，每个臂重复三次。历史 `2.2.0` 报告保留其原始案例和指令摘要，不会根据新合同重新评分。在新鲜授权的 `2.3.0` 运行之前，公共证据仍然为 `manual-required`；执行后，它在受信任的证明之前保持 `review-required`。 ## 安全边界和本地状态 插件安装、技能同意、运行时权限和生产授权是独立的决策。模型不能提供可执行路径用于评估、铸造主机权限、将固定装置升级为运行时证据或改变原生 Codex 目标。 插件将状态存储在其缓存之外： | 平台 | 默认路径 | | --- | --- | | Windows | `%LOCALAPPDATA%\Codex\workflow-skill-router` | | macOS | `~/Library/Application Support/Codex/workflow-skill-router` | | Linux | `${XDG_STATE_HOME:-~/.local/state}/codex/workflow-skill-router` | 设置 `WORKFLOW_SKILL_ROUTER_DATA_DIR` 以选择另一个外部目录。默认情况下不启用 telemetry。请在集成主机侧 R2/R3 操作前阅读 [安全边界](site/src/content/docs/reference/security-boundaries.md)。 ## 贡献 首先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，然后运行您更改的表面聚焦检查。发布工件来自允许列表和确定性构建器；生成的输出永远不会手动编辑。 ```powershell $env:PYTHONPATH = (Resolve-Path "packages/router-core/src").Path python -m unittest discover -s packages/router-core/tests -v python -m unittest discover -s tests -v python scripts/build-v2-demo-data.py --check $Version = (Get-Content -Raw -Encoding UTF8 release/version.json | ConvertFrom-Json).v2_version $Output = Join-Path "dist" "release-$Version" python -I -S -B scripts/build-release-artifacts.py --output-dir $Output --provenance-mode test --check-determinism ``` 发布构建器仅允许重复覆盖当前清单。它如果输出目录包含过时、意外、符号链接或非清单路径，则关闭失败；请使用版本特定的目录而不是混合发布世代。 ## 版本通道 | 通道 | 当前角色 | 推广规则 | | --- | --- | --- | | `latest` | V1.3.1 兼容性直到 V2 GA | 仅在 GA 发布门户通过后移动 | | `latest-v1` | 不变的 V1 恢复 | 保持固定到 V1.3.1 | | `latest-v2` | 历史 V2 预发布通道 | 保留审查的预发布历史直到合格的 GA 推广 | 存储库是 V2-first，即使兼容性通道保持固定。版本元数据位于 [`release/version.json`](release/version.json)。 ## V1 迁移 使用 [V1 到 V2 迁移指南](site/src/content/docs/guides/migrate-v1-to-v2.md) 从基于模板的路由迁移到运行时感知的插件或独立技能。V1 源代码和软件包仍然可以从不可变的 [`v1.3.1` 标签](https://github.com/eric861129/Workflow-skill-router/tree/v1.3.1) 和 GitHub 发布中恢复；它们不是主要的 V2 导航。 MIT 许可。