skill-system-router

Skill System Router

已弃用的兼容接口。skill-system-cli 现在负责运行时路由模块，供 sk 使用；此技能仍然可用，以确保过渡期间现有的路由文档、策略引用和旧版入口不会失效。

你是 Router。此技能将教你如何编排其他技能。

Router 是一个内部编排层。面向用户的公开入口仍然是 skill-system-cli 中的 sk。

工作原理

User goal → Read skills-index.json → Match capabilities → Read skill manifest
→ (Complex goal: plan with workflow) → Check policy → Execute entrypoints → Parse JSON output → Decide next step → Log

步骤 0：安装程序引导检查（仅首次运行）

检查项目的 AGENTS.md 是否包含 ## Skill System。

• 如果找到：跳到步骤 1（已完成引导）。
• 如果未找到：使用 skill-system-installer 引导程序搭建框架，并将技能系统嵌入项目。

引导工作由 skill-system-installer 负责。完成引导后，后续每次会话都会读取 AGENTS.md，并自动了解技能系统。

步骤 1：发现技能

读取 skills-index.json（位于技能根目录中，与各技能文件夹同级）以查看可用能力。

索引将能力映射到技能，并列出每个技能的操作及其描述和输入参数。将用户的目标与相应能力匹配。如果没有匹配项，请检查能否将目标分解为子能力。

如果目标涉及多个步骤、含义不明确，或可能需要执行 3 项以上操作，请先通过 plan-with-workflow 进行工作流规划。

如果缺少 skills-index.json 或该文件已过期，请重新生成：

bash "<this-skill-dir>/scripts/build-index.sh"

powershell.exe -NoProfile -ExecutionPolicy Bypass -File "<this-skill-dir>\scripts\build-index.ps1"

会话防护

强制要求先启动 Router：会话开始时，必须先加载此技能，然后才能加载任何非 Router 技能。这是一项失败即关闭的防护措施：

1. 首先加载 skill-system-router。
2. 运行 guard-check 操作。
3. 如果 guard-check 尚未成功：阻止加载所有非 Router 技能，并显示失败消息：

   Router guard failed: load skill-system-router and complete router discovery before using non-router skills.

4. 只有在 guard-check 成功后，才能继续使用非 Router 技能。

此要求不可协商。如果用户直接请求非 Router 技能，必须先加载 Router 并完成防护检查，然后才能继续。

防护失败语义：

• 如果缺少 router_checked 标志：阻止加载非 Router 技能，显示消息，并运行发现流程。

• 如果缺少 skills-index.json 或该文件已过期：先重建，再将防护标记为已完成。

• 优先使用基于记忆的标志：router_checked=true，并附带 session_id。

• 流程：scripts/session-guard-check.md

步骤 2：读取技能清单

打开目标技能的 SKILL.md，找到 `skill-manifest` 围栏代码块。其中包含：

• operations：技能可执行的操作，以及输入／输出架构
• effects：副作用（用于策略检查）
• entrypoints：特定操作系统的运行命令

完整清单规范：references/manifest-spec.md

配置

运行时设置位于 config/router.yaml。配置是唯一可信来源。

参见：../../config/router.yaml

步骤 3：检查策略

执行前，根据当前生效的策略配置，验证技能声明的 effects：

SELECT allowed_effects FROM skill_system.policy_profiles WHERE name = 'dev';

• 所有 allowed_effects 中的效果 → 继续
• 存在任何不在 allowed_effects 中的效果 → 继续前询问用户
• 不存在策略配置 → 询问用户

report-improvement-issue 策略说明：

• 始终需要：proc.exec、net.fetch
• 如果省略 repo 并从 git remote 推断，则还需要：git.read

标准效果：db.read、db.write、proc.exec、fs.read、fs.write、net.fetch、git.read、git.write

内部策略辅助工具 scripts/router.py check-policy 会返回结构化的 policy_decisions 列表，供调用方展示具体的允许／拒绝理由。 如果 skill_system.policy_profiles 不可用，辅助工具会回退到 config/router.yaml 中的 policy.default_allowed_effects，并在输出中 明确说明这一回退情况。

第 4 步：执行

1. 确定操作系统：OS 环境变量为 Windows_NT → 使用 windows 入口点，否则使用 unix
2. 读取适用于当前操作系统的操作 entrypoints
3. 将 {param} 占位符替换为实际值
4. 将当前工作目录设为该技能的目录
5. 运行命令
6. 将标准输出的最后一行解析为 JSON — 这就是结果

退出代码 ≠ 0，或最后一行不是 JSON → 操作失败。

第 5 步：串联操作

当某个目标需要多个技能／操作时：

1. 执行第一个操作 → 解析 JSON 输出
2. 将输出值用作下一个操作的输入（映射方式由你决定）
3. 重复上述步骤，直到达成目标

你具备智能，应根据中间结果灵活调整。这比固定流水线更好，因为你可以处理错误、跳过不必要的步骤，并根据上下文做出决策。

第 5.5 步：编排调用链（Router → TKT → Workflow）

对于需要多 Agent 协作的复杂目标，router 会编排以下三层：

1. Router identifies TKT-worthy goal
2. TKT.create-bundle → decomposes into tickets (000 + workers + audit)
3. Workflow.plan → orders tickets into a DAG with dependency waves
4. Router dispatches each ticket's skill execution by wave order
5. TKT.update / TKT.close → tracks results and triggers review

决策矩阵：

目标类型	路由
单技能，简单	直接执行（第 4 步）
多步骤，单会话	Workflow.plan → 按波次执行
多 Agent，跨会话	TKT.create-bundle → Workflow.plan → 执行 → TKT.close

仅规划工作流（不使用 TKT）时，请使用 scripts/plan-with-workflow.md。 使用 TKT 集成规划时，请使用上述调用链。

第 6 步：记录（可观测性）

完成非简单工作流后，记录信息以便观测：

INSERT INTO skill_system.runs(task_spec_id, status, started_at, effective_policy)
VALUES (NULL, 'running', NOW(), '{}'::jsonb) RETURNING id;

INSERT INTO skill_system.run_events(run_id, level, event_type, payload)
VALUES (<run_id>, 'info', 'step_completed',
  jsonb_build_object('skill', '<id>', 'operation', '<op>', 'status', '<ok|error>', 'duration_ms', <ms>));

UPDATE skill_system.runs SET status='succeeded', ended_at=NOW(),
  metrics=jsonb_build_object('steps', <n>, 'duration_ms', <ms>) WHERE id=<run_id>;

简单的单操作调用无需记录。

第 7 步：报告改进问题

当 Agent 发现技能／系统流程中可复用的缺陷、摩擦点或不明确的行为时，请创建 GitHub issue，以便跟踪改进。

请使用 scripts/report-improvement-issue.md。

报告时机：

• 执行过程中发现缺少防护措施或策略检查
• 文档／入口点不清晰，反复给用户造成困扰
• 可靠性缺陷（容易发生偏差的步骤、薄弱的验证、可观测性不足）

创建新 issue 前，请检查未关闭的 issue 中是否有重复项。

如果已有类似 issue，请关联该 issue，而不是创建新 issue。

实验准入检查委派

对于实验验证和注册表安全操作，请委派给 skill-system-gate：

操作	委派给
根据准入规则验证实验代码／日志	skill-system-gate → validate-experiment
重置／重新运行前检查注册表状态安全性	skill-system-gate → verify-registry
显示实验队列状态和运行状况	skill-system-gate → status

GitHub 操作委派

对于改进问题报告以外的一般 GitHub 项目管理操作，请委派给 skill-system-github：

操作	委派给
（路由期间）报告改进问题	此技能 — report-improvement-issue
创建／列出／评论／关闭／重新打开 issue	skill-system-github → manage-issues
创建／更新／删除／应用标签	skill-system-github → manage-labels
初始化／更新 issue 模板	skill-system-github → manage-templates
列出／检查／创建／更新工作流	skill-system-github → manage-workflows
工作流写入前检查 PAT 权限范围	skill-system-github → safety-check

router 保留 report-improvement-issue，因为它会在技能路由期间内联触发。所有其他 GitHub 操作都通过专用技能进行路由。

洞察建议

完成一段非简单的会话后（多步骤工作、深入讨论或调试），可以考虑建议进行一次洞察分析：

“要我对这次会话进行一次洞察分析吗？这有助于我了解你的偏好，以便下次更好地协作。”

这是一个轻量、可选的提示。仅在以下情况下建议：

• 会话中有实质性的互动（而非单行修复）
• 用户最近尚未触发过洞察提取
• 会话中包含值得记录的信号（挫折感、满意度、风格偏好）

如果用户同意，请加载 skill-system-insight 并遵循 scripts/extract-facets.md。

注意：skill-system-insight 是统一的观察与演进引擎。它同时处理特征提取和配置文件／配方演进（此前分属洞察和演进技能）。

常见模式

单次操作： 目标 → 索引查找 → 执行一个入口点 → 返回结果

多步链： 目标 → op1.search → 解析结果 → op2.store（使用结果）→ 完成

跨技能链： 目标 → skill-A.op1 → 将输出用作上下文 → skill-B.op2 → 重建索引 → 完成

工作流辅助链： 目标 → router.plan-with-workflow → 执行第 1 波任务 → 执行依赖波次 → 记录结果

数据库

使用 skill-system-postgres 中的表：

• skill_system.policy_profiles — 效果允许列表
• skill_system.runs — 执行记录
• skill_system.run_events — 步骤级日志

{
  "schema_version": "2.0",
  "id": "skill-system-router",
  "version": "1.0.0",
  "capabilities": ["skill-discover", "skill-execute", "skill-chain", "index-rebuild", "skill-improvement-report", "workflow-route", "session-guard", "policy-check"],
  "effects": ["fs.read", "fs.write", "proc.exec", "db.read", "db.write", "net.fetch", "git.read"],
  "operations": {
    "rebuild-index": {
      "description": "Regenerate skills-index.json by scanning all skill manifests.",
      "input": {},
      "output": {
        "description": "Index file path and skill count",
        "fields": { "file": "string", "skill_count": "integer" }
      },
      "entrypoints": {
        "unix": ["bash", "scripts/build-index.sh"],
        "windows": ["powershell.exe", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "scripts\\build-index.ps1"]
      }
    },
    "report-improvement-issue": {
      "description": "Create or link a GitHub issue for skill/system improvements discovered during routing.",
      "input": {
        "title": {"type": "string", "required": true, "description": "Issue title"},
        "summary": {"type": "string", "required": true, "description": "Concise problem statement and why it matters"},
        "repo": {"type": "string", "required": false, "description": "owner/repo override; default inferred from git remote"},
        "impact": {"type": "string", "required": false, "description": "User or system impact"},
        "repro_steps": {"type": "string", "required": false, "description": "Steps to reproduce observed friction"},
        "suggested_fix": {"type": "string", "required": false, "description": "Candidate fix or direction"}
      },
      "output": {
        "description": "Created or matched issue information",
        "fields": {"status": "created | linked", "issue_url": "string", "issue_number": "integer"}
      },
      "entrypoints": {
        "agent": "Follow scripts/report-improvement-issue.md procedure"
      }
    },
    "plan-with-workflow": {
      "description": "Use skill-system-workflow to plan complex goals as DAG waves, then route execution by dependency order.",
      "input": {
        "goal": {"type": "string", "required": true, "description": "Complex user goal"},
        "context": {"type": "string", "required": false, "description": "Optional files/constraints context"}
      },
      "output": {
        "description": "Workflow plan prepared for router execution",
        "fields": {"dag": "YAML", "mermaid": "string", "wave_count": "integer", "execution_notes": "string"}
      },
      "entrypoints": {
        "agent": "Follow scripts/plan-with-workflow.md procedure"
      }
    },
    "guard-check": {
      "description": "Mandatory fail-closed session-start guard: load skill-system-router first, confirm router discovery, and block non-router skills until the guard succeeds.",
      "input": {},
      "output": {
        "description": "Guard result and failure guidance",
        "fields": {"router_checked": "boolean", "message": "string"}
      },
      "entrypoints": {
        "agent": "Follow scripts/session-guard-check.md procedure"
      }
    },
    "check-policy": {
      "description": "Evaluate requested skill effects against the active policy profile and return structured allow/deny decisions.",
      "input": {
        "skill_id": {"type": "string", "required": true, "description": "Skill identifier being evaluated"},
        "effects": {"type": "array", "required": true, "description": "Requested effects to evaluate"},
        "profile": {"type": "string", "required": false, "description": "Policy profile name; defaults to dev"}
      },
      "output": {
        "description": "Policy lookup source, allowlist, and per-effect decisions",
        "fields": {"policy_decisions": "array", "all_allowed": "boolean", "policy_source": "string"}
      },
      "entrypoints": {
        "agent": "Invoke scripts/router.py check-policy with --skill-id, repeated --effect flags, and optional --profile"
      }
    }
  },
  "stdout_contract": {
    "last_line_json": false,
    "note": "rebuild-index prints summary to stdout; report-improvement-issue/plan-with-workflow are agent-executed."
  }
}