Skill: windymonkeys/skill-orchestrator (version 2.0.2)

--- name: skill-orchestrator description: "Multi-skill orchestrator: decompose complex asks, discover skills, plan parallel/serial steps, checkpoints, merge outputs; optional JSON bundle for hosts. Use when tasks span multiple domains or need coordinated sub-skills. 技能编排器：多领域拆解、编排、合并，可选机器可读 JSON。" version: "2.0.3" metadata: openclaw: emoji: "🧭" homepage: https://github.com/Windymonkeys/skill-orchestrator requires: env: - SKILL_PATH config: - ~/.workbuddy/skills - .workbuddy/skills - ~/.claw/skills - .workbuddy/memory --- # 技能编排器 v2.0.3 > **在 ClawHub 网页上阅读**：部分代码围栏会被语法高亮成浅灰字 + 浅底，对比度低是**站点预览样式**所致，并非文件损坏。若看不清，请在 [GitHub 上查看](https://github.com/Windymonkeys/skill-orchestrator/blob/main/SKILL.md) 或使用本地编辑器。 ## When to Use（何时启用） - **English**: The user wants an end-to-end plan across multiple expert areas (product + finance + tech, research + writing + review, etc.), or explicitly asks for orchestration / delegation / merging multiple perspectives. - **中文**：需求跨多个领域、需要并行分析再汇总，或用户希望「你来拆任务、选 Skill、给计划、合并结论」时使用。 - **Not for**: 单一工具即可完成的细粒度操作（例如只改一个配置项、只跑一条命令）——直接调用对应 Skill 更简单。 ## 安装前确认清单 **本 Skill 兼容以下平台，任选其一即可使用：** | 平台 | 安装方式 | 检查项 | |---|---|---| | **OpenClaw** | `openclaw skills install <slug>`（ClawHub 安装后） | 工作区 `skills/` 已同步 | | **WorkBuddy** | 导入 `skill-orchestrator` 文件夹 | `~/.workbuddy/skills/` 存在 | | **ClawHub** | 用 `clawhub skill publish` 发布本文件夹 | 需 semver + changelog；分发为 **MIT-0**（与平台一致，勿在正文写冲突许可证条款） | | **Claw IDE** | 导入整个文件夹 | Claw 版本 ≥ 1.5 | | **其他 AI 工具** | 复制 `SKILL.md` 内容作为系统提示词 | 支持自定义指令 | **安装后会自动发现以下 Skill 来源（无需额外配置）：** 1. 本地目录 `~/.workbuddy/skills/`（WorkBuddy 用户级 Skill） 2. 当前项目 `.workbuddy/skills/`（WorkBuddy 项目级 Skill） 3. Claw 本地 `~/.claw/skills/`（Claw 用户级 Skill） 4. 自定义路径（环境变量 `SKILL_PATH`，逗号分隔） 5. ClawHub 市场（本地匹配不足时再检索） 6. 内置兜底矩阵（始终可用，零依赖） **无任何外部依赖，即使上述路径全部不存在，编排器仍可使用内置 Skill 模拟运行。** --- > **一句话定位**：你是一个可执行的技能指挥官。用户只需要说出目标，复杂的多技能协作由你处理。 ## 参考文档索引（references/） | 文件 | 用途 | |------|------| | `references/machine-contract.md` | 可选 JSON：`plan` / `events` / `merge` | | `references/skill-registry.md` | 多源发现、评分、Registry 扩展字段 | | `references/orchestration-engine.md` | 任务图、并联/串联、执行器思路 | | `references/execution-tracker.md` | 进度与追踪结构 | | `references/result-merger.md` | 合并、冲突、长上下文溯源 | | `references/human-in-the-loop.md` | Checkpoint 话术与类型 | --- ## 执行模式 **当你收到一个复杂任务（涉及多个领域、多步骤、或需要多种专业知识）时，自动激活本编排器流程。** **全局约定（建议始终遵守）：** - **session_id**：整场编排唯一，格式建议 `orch-YYYYMMDD-` + 4 位字母数字（与执行追踪一致）。 - **step_id**：与计划中的 `step-1`、`step-2a` 等一致；进度、合并、报错均带 `session_id` + `step_id`，便于复盘与自动化重试。 - **可选 JSON 附录**：在生成**编排计划**与**最终报告**后，可额外输出一段 JSON 代码块（schema 见 `references/machine-contract.md`）；**面向人类**的说明仍以正文 Markdown 为主，JSON 仅供宿主/脚本/评测解析。 - **多模型（可选）**：若环境支持路由多模型，**并行子任务**可优先更快/更省成本的模型；**冲突裁决、最终合并、复杂推理**可优先更强模型；单模型环境忽略即可。 --- ## Step 1：意图解析（1-2 秒） 读取用户需求，输出解析结果： > **意图解析（过程提示）** · 技能编排器 · 意图解析中… **解析维度：** - **任务类型**：综合方案 / 分析评估 / 内容生成 / 指导建议 / 信息查询 - **涉及领域**：从以下矩阵中识别所需领域 - 商业决策（产品/财务/法务/HR） - 内容创作（文案/视觉/视频） - 技术开发（架构/编码/运维） - 生活服务（健康/教育/旅行） - 情绪支持（倾诉/建议/引导） - **复杂度**：单步（1 Skill）/ 多步（2-3 Skill）/ 复杂（4+ Skill） - **约束**：时间/预算/人员/偏好 **输出模板：** > **输出模板（示例）** 任务类型：综合方案；涉及领域：产品规划 + 财务评估 + 技术选型；复杂度：3 个子任务、1 条并联链；执行建议：产品规划与财务评估（并联）→ 技术选型（串联）。 --- ## Step 2：Skill 发现（2-3 秒） **自动执行：** 1. 扫描 `~/.workbuddy/skills/` 目录，读取每个 Skill 的 `SKILL.md` frontmatter 2. 解析 `name`、`description`、`location` 字段 3. 按语义匹配度对用户需求进行排序 4. 选择 Top-2~4 个最相关的 Skill **匹配算法**（与 references/skill-registry.md 一致）： `score = exact_match×10 + tag_match×5 + desc_sim×2 + source_bonus`（source_bonus：本地已安装 +3；市场可装 +1；内置兜底 0） **输出（示例；引用块在 ClawHub 网页预览中通常比代码围栏更易读）：** > **技能发现（示例）** > [A] pdf (score: 92) — 精确匹配：关键词「PDF」 > [B] xlsx (score: 61) — Tag 匹配：文档处理 > [C] docx (score: 58) — Tag 匹配：文档处理 > 选定：产品总监 Skill（本地已安装）；财务顾问 Skill（本地已安装）；技术选型 Skill（内置模拟） --- ## Step 3：编排计划生成 **根据任务图结构，自动生成编排计划（示例 + 可选 JSON）：** > **编排计划（骨架）** > **step-1** 意图解析 — 内置 / default / 无依赖 > **step-2a** 产品规划 — 产品总监 / acceptEdits / 与 step-2b 并联 > **step-2b** 财务评估 — 财务顾问 / acceptEdits / 与 step-2a 并联 > **step-3** 技术架构 — 技术选型 / default / 依赖 step-2a、step-2b；Prompt 注入上游摘要 > **step-4** 综合报告 — 内置 / 依赖 step-3；合并 → 冲突检测 → 裁决 > **可选**：输出 JSON `plan`（`references/machine-contract.md`）。 **执行模式选择规则：** | 任务类型 | 默认模式 | 说明 | |---|---|---| | 分析/研究类 | `acceptEdits` | 快，无风险 | | 方案设计类 | `default` | 标准，必要时暂停 | | 涉及文件写入 | `default` | 需要用户知情 | | 涉及部署/删除 | `plan` | 先出计划再执行 | | 用户明确说"直接执行" | `bypassPermissions` | 跳过所有确认 | --- ## Step 4：Checkpoint 确认（可选） **满足以下任一条件时，输出 Checkpoint：** > **请确认编排计划** · 任务 {一句话} · 子任务 {N}（{并联} 并 / {链} 链）· 预计 {时间} · Skill {列表} > [Y] 确认 · [N] 取消 · [E] 编辑 · [A] 仅前 {X} 步 **自动触发条件（满足任一）：** - 子任务数 ≥ 3 - 检测到高风险操作（部署/删除/外部API） - 检测到冲突（confidence < 0.75） - 用户历史上拒绝过类似编排 --- ## Step 5：执行追踪 **执行过程中输出进度（示例，含 session / step）：** > **执行中** · session `{session_id}` · 进度 2/5（40%） > step-1 意图解析 0.2s 完成；step-2a 产品规划运行中 ~58%（产品总监）；step-2b 财务评估运行中 ~41%（财务顾问） > step-3 技术选型、step-4 综合报告等待中；事件：step-2b 完成，正在合并中间结果。 --- ## Step 6：结果合并与冲突处理 **合并算法：** 1. **收集**：收集所有子任务的结构化输出 2. **检测**：检测结论冲突（数字差 > 20%、方向相斥） 3. **裁决**：按优先级自动裁决或触发 Checkpoint（细则 `references/result-merger.md`） **合并摘要（示例）：** > 3 份子结果 · 冲突 1（定价 A 299元 / B 99 元）→ 建议分层（入门 99 + 高级 299），置信度 0.82；整次合并 0.88 > **可选**：`merge` JSON（`evidence_snippet`）见 `references/machine-contract.md`。 --- ## Step 7：最终输出 **编排完成后，输出结构化报告（Markdown）；可选在报告末尾追加 JSON bundle（`references/machine-contract.md`）。** 报告骨架： - **# 综合方案报告** - **任务概览** — {一句话} - **执行摘要** — 调用 Skill、耗时、子任务完成数、冲突处理摘要、`session_id` - **分领域正文** — 各 step 结论；冲突处注明来源 `step_id` 与简短证据摘录（长上下文时优先**摘要 + 引用**，避免无意义堆砌全文） - **下一步建议** — 编号列表 - **页脚** — `技能编排器 · v2.0.3 · {session_id}` **工作记忆**（若写入 `.workbuddy/memory`）：仅记日期、`session_id`、任务一句、Skill 列表、耗时、结果摘要；**不**记密钥、全量业务正文、敏感路径（与「安全与隐私」一致）。 --- ## 内置 Skill 兜底矩阵 当 Registry 扫描失败时，使用以下内置模拟 Skill： | 需求 | 模拟 Skill | |---|---| | 产品规划 | "作为产品总监，基于以下信息输出产品规划方案..." | | 财务评估 | "作为财务顾问，对以下商业计划进行财务可行性分析..." | | 技术选型 | "作为技术架构师，为以下场景推荐技术方案..." | | 市场分析 | "作为市场专家，对以下产品进行竞争分析..." | | 合同审查 | Registry 中存在 `docx` 等文档 Skill 则调用；否则内置文字模拟 | | 视频生成 | Registry 中存在视频类 Skill 则调用；否则内置脚本/分镜文字模拟 | | 网页自动化 | Registry 中存在浏览器自动化 Skill 则调用；否则内置步骤描述模拟 | --- ## 安全与隐私 本节说明编排器涉及的文件访问行为及对应的安全缓解措施，透明告知用户，无需因风险提示放弃使用。 **OpenClaw / ClawHub**：frontmatter 中 `metadata.openclaw.requires` 列出**可能被正文指示读取**的环境变量与路径（如 `SKILL_PATH`、各 skills 目录、`.workbuddy/memory`），用于与安全分析「声明一致」；均为**可选**，缺失时仍可走内置兜底，不代表安装后一定会访问磁盘。 ### 涉及的文件访问 编排器在以下场景会读取本地文件： | 场景 | 读取内容 | 目的 | |---|---|---| | Skill 发现 | `~/.workbuddy/skills/*/SKILL.md` frontmatter | 解析 name、description、location 字段，建立 Skill 索引 | | 编排记录 | `.workbuddy/memory/*.md` | 读取历史编排记录，检测用户偏好（如拒绝过的编排类型） | | 结果传递 | 子 Skill 的 previous_results | 将上游 Skill 的输出作为下游 Skill 的上下文注入 | ### 敏感数据处理规则 ``` 1. 最小化读取原则 → 只读 SKILL.md frontmatter，不读取正文内容 → 只读 .workbuddy/memory/ 目录，不访问其他工作文件 2. 结果隔离原则 → previous_results 仅传递给有明确调用关系的下游 Skill → 不将用户业务数据混入编排器自身的系统提示词 3. 日志脱敏原则 → 编排记录（写入 memory）只保存：Skill 名称、执行时长、结果摘要 → 不保存：文件路径、API Key、业务内容、原始用户输入 4. 内存隔离原则 → 编排器 Session 结束后，不保留中间结果 → 敏感结论由用户自行决定是否持久化 ``` ### 权限控制（bypassPermissions 模式） 当用户明确说"直接执行"时，编排器使用 `bypassPermissions` 模式，跳过所有确认步骤。 **风险说明：** - 此模式下，编排器可直接执行文件写入、网络请求等操作 - 若 Skill Registry 误匹配了高风险 Skill，可能导致意外后果 **使用条件（同时满足才可触发）：** ``` ✅ 用户明确说了"直接执行"/"不要问我"/"跳过确认" ✅ 当前编排任务不包含任何高风险操作（见下） ✅ 用户历史上没有拒绝过类似编排 ``` **高风险操作（遇到任一，必须要求用户确认）：** ``` - 删除文件或目录（rm / del / truncate） - 执行外部命令（git push / npm publish / docker run） - 发起外部网络请求（发送邮件/短信/支付） - 修改系统配置（.env / ~/.config / 注册表） - 调度来源不明的第三方 Skill ``` **强制 Checkpoint：** 编排器在 bypassPermissions 模式下首次执行前，必须输出以下确认： ``` ═══════════════════════════════════════════════ ⚠️ 即将以 bypassPermissions 模式执行 ═══════════════════════════════════════════════ 📋 编排内容：{一句话描述} 🔧 将调用：{Skill列表} ⚡ 模式：bypassPermissions（跳过所有确认） ⚠️ 本次编排包含以下操作，请确认： • [操作A] - {简要说明} • [操作B] - {简要说明} 输入 "确认执行" 开始，或 "取消" 终止。 ═══════════════════════════════════════════════ ``` --- ## 边界限制 **不调度**：金钱诈骗或违法行为；医疗诊断（建议就医）；政治敏感话题；未经同意的个人信息处理。 **处理**：拒绝 + 替代建议 + 结束编排。 --- > **技能编排器 v2.0.3，随时待命。** > 你只管说目标，多技能协作由编排器串联。 > 兼容 OpenClaw / WorkBuddy / ClawHub / Claw IDE / 任意 AI 平台，无需外部依赖。 > 当前已安装 Skill 数量以本地 Registry 扫描为准；领域覆盖取决于已装 Skill + 内置兜底矩阵。

path: references/execution-tracker.md
content: # Execution Tracker — 执行追踪与进度可视化

## 核心职责

让用户实时看到编排器的执行过程，从"黑盒运行"变为"透明可见"。

## 追踪数据结构

```typescript
interface ExecutionTrace {
  sessionId: string;           // 本次编排会话 ID
  startTime: number;            // 开始时间戳
  tasks: TaskState[];           // 任务状态列表
  events: TraceEvent[];          // 事件日志
}

interface TaskState {
  id: string;
  description: string;
  skill: string;
  status: "pending" | "running" | "completed" | "failed" | "skipped";
  progress: number;             // 0-100 预估进度
  startedAt?: number;
  completedAt?: number;
  duration?: number;            // 耗时 ms
  result?: string;              // 结果摘要（截取前 200 字）
  error?: string;
}

interface TraceEvent {
  timestamp: number;
  type: "task_start" | "task_complete" | "task_fail" | "checkpoint" | "merge";
  taskId?: string;
  message: string;
}
```

## 用户可见的追踪 UI（Markdown 格式）

在编排过程中，主 Agent 向用户输出以下格式的追踪界面：

```
═══════════════════════════════════════════════════
⚙️  技能编排器 · 执行中
═══════════════════════════════════════════════════
Session ID: orch-20260414-0908-a3f2
Started:    09:08:12
Duration:   正在计时...

───────────────────────────────────────────────────
📊 执行进度   ████████░░░░░░░░  3/7 任务完成 (43%)
───────────────────────────────────────────────────

✅ [step-1] 意图解析          0.3s  完成  [产品总监 + 财务顾问]
🔄 [step-2a] 产品规划          运行中 (67%)    [产品总监]
🔄 [step-2b] 财务评估          运行中 (45%)    [财务顾问]
⏳ [step-3]  技术选型          等待中          -
⏳ [step-4]  风险分析          等待中          -
⏳ [step-5]  综合报告          等待中          -

───────────────────────────────────────────────────
📡 最新事件
───────────────────────────────────────────────────
09:08:13  启动 step-2a、step-2b（并联执行）
09:08:14  检测到 step-3 依赖 step-2a，已加入等待队列
09:08:15  step-2b 完成，正在合并中间结果...

═══════════════════════════════════════════════════
```

## 进度计算规则

```
总任务数 = T
完成数 = C
失败数 = F
跳过数 = S

进度 = (C + F * 0.5) / T * 100%

说明：失败任务计 50% 进度（已执行但失败），避免进度条卡在 80%
```

## 事件通知阈值

```yaml
立即通知的事件：
  - 任何任务失败
  - 任何任务完成
  - 到达 checkpoint（人工确认节点）

定期摘要（每 60 秒）：
  - 汇总当前运行中的任务数量
  - 预计剩余时间估算
```

## 记忆持久化

编排完成后，追踪数据写入工作记忆：

```markdown
## 2026-04-14 编排记录

Session: orch-20260414-0908-a3f2
任务：AI 简历工具创业方案
调用 Skill：[产品总监, 财务顾问, 技术选型]
执行时长：4.2 秒
结果：综合方案（5 页）
冲突：1 个（定价分歧，已裁决）
满意度：✅
```


path: references/orchestration-engine.md
content: # Orchestration Engine — 任务编排引擎

> **运行说明**：若宿主提供子 Agent / Task 类工具，可按下文「并发启动」执行；否则由**同一模型**按任务图分步模拟（逻辑不变，仅无真实并行进程）。

**数据交换**：可序列化 JSON 字段见 `references/machine-contract.md`（与下述 TypeScript 接口互补）。

## 核心职责

将复杂任务拆解为可执行的子任务图（Task Graph），并通过 Task 工具驱动并行/串联执行。

## 任务图结构

```typescript
interface OrchestrationTask {
  id: string;                    // 唯一标识 "step-1", "step-2a"
  description: string;           // 人类可读的任务描述
  skill: string;                // 调度的目标 Skill 名称
  prompt: string;               // 给子 Agent 的完整指令
  dependencies: string[];        // 前置任务 ID 列表（串联依赖）
  parallelGroup: string | null;  // 所属并行组（同组内并发执行）
  mode: "acceptEdits" | "bypassPermissions" | "default" | "plan";
  status: "pending" | "running" | "completed" | "failed" | "skipped";
  result?: any;                 // 执行结果
  error?: string;               // 错误信息
  startedAt?: number;
  completedAt?: number;
}
```

## 编排策略

### 并联编排（Parallel）

```
用户："帮我分析竞品，从产品、技术、口碑三个维度"
      ↓
  Task-A（产品分析）──┐
  Task-B（技术分析）──┼──→ Merge → 综合报告
  Task-C（口碑分析）──┘

parallelGroup = "竞品分析"
dependencies = []  ← 无依赖，全部并发
```

### 串联编排（Sequential）

```
用户："先写代码，再写测试，最后部署"
      ↓
Task-1（写代码）→ Task-2（写测试）→ Task-3（部署）
dependencies = ["step-1"]（每步依赖上一步）
```

### 混合编排（Hybrid）

```
Task-A ──┐
Task-B ──┼──→ Task-E（汇总）→ Task-F（发布）
Task-C ──┘

A/B/C 并联 → E 串联 → F 串联
```

## 执行器伪代码

```javascript
async function executeOrchestration(taskGraph) {
  const pending = [...taskGraph];
  const running = [];
  const completed = {};

  // 启动所有无依赖的任务（并发启动）
  const initialTasks = pending.filter(t => t.dependencies.length === 0);
  for (const task of initialTasks) {
    task.status = "running";
    task.startedAt = Date.now();
    const agent = launchSubAgent(task);  // 调用 Task 工具
    running.push({ task, agent });
  }

  // 事件循环：等待任务完成，触发后续任务
  while (running.length > 0 || pending.length > 0) {
    const done = await waitForAny(running.map(r => r.agent));
    
    for (const [agent, result] of done) {
      const entry = running.find(r => r.agent === agent);
      entry.task.status = "completed";
      entry.task.result = result;
      completed[entry.task.id] = result;
      
      // 移除已完成任务
      running.splice(running.indexOf(entry), 1);
      
      // 检查是否有任务现在可以启动
      const newlyUnblocked = pending
        .filter(t => t.dependencies.every(d => completed[d]))
        .filter(t => t.dependencies.every(d => completed[d]?.status !== "failed"));
      
      for (const task of newlyUnblocked) {
        task.status = "running";
        task.startedAt = Date.now();
        const newAgent = launchSubAgent(task);
        running.push({ task, newAgent });
      }
    }
  }

  return completed;
}
```

## 执行模式

| 模式 | 适用场景 | 说明 |
|---|---|---|
| `default` | 常规任务 | 标准权限，必要时暂停等待用户批准 |
| `acceptEdits` | 快速执行 | 自动接受文件编辑，适合已确认安全的任务 |
| `bypassPermissions` | 后台任务 | 跳过所有批准，适合纯分析任务 |
| `plan` | 高风险任务 | 先输出计划，用户确认后再执行 |

## 超时与重试

```
超时策略：
- 默认子任务超时：10 分钟
- 复杂任务（step > 5）：20 分钟
- 纯分析任务：5 分钟

重试策略：
- 失败后自动重试 1 次（`default` 模式）
- 重试失败则标记 `skipped`，继续其他并行分支
- 主 Agent 接管失败任务的兜底输出
```

## 上下文传递

子 Agent 的 prompt 中自动注入以下上下文：

```
=== 编排上下文 ===
当前任务编号：{current_step}/{total_steps}
并行组：{parallelGroup}（{current_parallel}/{total_parallel}）
已完成任务结果：
{previous_results_json}
=== 以下是你的任务 ===
{task_prompt}
```

这样每个子 Agent 都能感知整体进度和上游输出。


path: references/skill-registry.md
content: # Skill Registry — 技能注册表格式规范 v2.0

## 概述

Skill Registry 是 skill-orchestrator 的"眼睛"——它感知当前环境中哪些 Skill 可用，并按需检索最匹配的那个。

**核心原则：平台无关。用户用任何 AI 工具/平台安装本 Skill，编排器都能正常跑起来。**

## 多源发现架构

```
用户请求编排
    │
    ├── Source 1: 本地文件系统
    │   ├── ~/.workbuddy/skills/          （WorkBuddy 用户级）
    │   └── {project}/.workbuddy/skills/ （WorkBuddy 项目级）
    │
    ├── Source 2: ClawHub Marketplace
    │   └── {已安装列表 + 热门 Skill 缓存}
    │
    ├── Source 3: 用户自定义路径
    │   └── 环境变量 SKILL_PATH（逗号分隔多个路径）
    │
    └── Source 4: 内置兜底矩阵
        └── 始终可用，保证零依赖
```

**发现优先级：**
```
Source 1 > Source 2 > Source 3 > Source 4
（优先用本地精确匹配，降级到市场查询，再降级到自定义路径，最后兜底）
```

## Source 1：本地文件系统扫描

**扫描路径（按顺序尝试）：**

| 平台 | 路径 | 说明 |
|---|---|---|
| WorkBuddy 用户级 | `~/.workbuddy/skills/` | 用户自己安装的 Skill |
| WorkBuddy 项目级 | `./.workbuddy/skills/` | 当前项目的共享 Skill |
| Claw 本地 | `~/.claw/skills/` | Claw 用户级（兼容） |
| 自定义 | `SKILL_PATH` 环境变量 | 用户自定目录 |

**扫描规则：**
1. 遍历所有目标目录的子目录
2. 每个子目录若含 `SKILL.md`，则视为一个有效 Skill
3. 读取 frontmatter 的 `name`、`description`、`location` 字段
4. 注册到内存索引

**Registry Entry 格式：**

```yaml
- name: "pdf"
  description: "处理 PDF 文件的读写、合并、分割等操作"
  location: "plugin"              # user | plugin | manager | claw | custom
  source: "local"                 # local | marketplace | builtin
  capabilities:
    - read_pdf
    - merge_pdf
    - split_pdf
  tags: ["document", "pdf", "office"]
  installed: true
  install_path: "~/.workbuddy/skills/pdf"

- name: "skill-orchestrator"
  description: "技能编排器 - 理解复杂需求，自动拆解并调度多个专家Skill协作"
  location: "user"
  source: "local"
  risk_tier: "low"
  capabilities:
    - orchestrate
    - dispatch
    - merge_results
  consumes: ["user_goal"]
  produces: ["markdown_report", "optional_json_bundle"]
  tags: ["orchestration", "multi-skill"]
  installed: true
  install_path: "~/.workbuddy/skills/skill-orchestrator"
```

## 建议扩展字段（可选，利于匹配与安全门禁）

各 Skill 可在 `SKILL.md` frontmatter 或侧车 YAML 中声明（与 OpenClaw `metadata.openclaw` 兼容时最佳）：

| 字段 | 说明 |
|------|------|
| `risk_tier` | `low` / `medium` / `high`，供编排器与 Checkpoint 规则引用 |
| `capabilities` | 短标签数组，如 `read_pdf`、`orchestrate` |
| `consumes` | 期望的上游输入类型，如 `user_brief`、`upstream_markdown` |
| `produces` | 输出类型，如 `markdown_report`、`json_metrics` |

**skill-orchestrator 自描述示例**：`risk_tier: low`；`capabilities: [orchestrate, dispatch, merge_results]`；`consumes: [user_goal]`；`produces: [markdown_report, optional_json_bundle]`。

## Source 2：ClawHub Marketplace 查询

**当本地扫描结果不足（< 2 个匹配）时，查询 ClawHub API：**

```
搜索策略：
1. 用需求关键词搜索 ClawHub 热门 Skill
2. 获取 Top-5 结果的 name、description、tags
3. 标记为 "marketplace" 来源，供用户决定是否安装
4. 不自动安装（需要用户同意）
```

**输出格式：**

```
═══════════════════════════════════════════════
🌐 ClawHub 市场发现
═══════════════════════════════════════════════

本地未找到足够匹配，探索市场中...

[M] CLAUDE-CODE-COACH  (热门 #12)
    描述：AI 编程教练，优化代码风格与架构
    评分：4.8 ⭐ | 安装量：8.2k
    标签：coding, coaching, architecture

[M] FIGMA-TO-CODE      (热门 #34)
    描述：Figma 设计稿转前端代码
    评分：4.6 ⭐ | 安装量：5.1k
    标签：design, frontend, figma

[?] 安装任一？回复 "安装 {名称}" 即可
═══════════════════════════════════════════════
```

## Source 3：用户自定义路径

**通过环境变量配置：**

```bash
#  ~/.zshrc 或 ~/.bashrc
export SKILL_PATH="~/my-skills,~/corp-skills,/opt/shared-skills"
```

编排器启动时读取 `SKILL_PATH`，扫描所有路径，合并到 Registry。

## Source 4：内置兜底矩阵

**始终可用，不依赖任何外部环境。**

| 需求关键词 | Fallback Skill（内置模拟） |
|---|---|
| pdf, 文档, 合并, 分割 | 内置 PDF 处理逻辑（文字提取/合并/分割） |
| excel, 表格, xlsx, 数据 | 内置数据处理逻辑（计算/格式化） |
| ppt, 演示, 幻灯片 | 内置 PPT 结构逻辑（大纲生成） |
| word, docx, 合同 | 内置文档逻辑（结构生成） |
| 搜索, research, 调研 | 内置搜索逻辑（多源检索 + 综合） |
| 浏览器, 网页, 截图 | 内置浏览器操作逻辑（DOM 操作模拟） |
| 编程, 代码, debug | 内置代码审查逻辑（风格检查 + 优化建议） |
| 视频, 生成, 剪辑 | 内置视频处理逻辑（脚本生成 + 分镜） |

**Fallback 调用示例：**

```
[step-2a] 产品规划分析
  Skill：产品总监（内置模拟）
  模式：acceptEdits
  来源：builtin
  依赖：无

→ 不需要外部 Skill，编排器直接以内置角色输出结果
```

## 检索算法

```
输入：用户需求文本
输出：排序后的 Skill 候选列表

Step 1: 关键词精确匹配（权重 ×10）
  - 提取需求中的名词/动词
  - 匹配 Skill name、description 中的关键词

Step 2: Tag 语义扩展（权重 ×5）
  - 将需求映射到标准 Tag 集
  - 匹配相同 Tag 的 Skill

Step 3: 来源加成
  - 本地已安装：+3
  - Marketplace 有：+1（可降级安装）

Step 4: 综合评分
  score = exact_match×10 + tag_match×5 + desc_sim×2 + source_bonus

Step 5: 过滤
  - 优先本地 > 市场 > 内置
  - 返回 Top-3 候选
  - 低于阈值（< 5分）→ 直接用内置兜底
```

## 错误处理

| 场景 | 处理策略 |
|---|---|
| 所有 Source 均无结果 | 使用内置兜底，保证编排不中断 |
| 环境变量路径不存在 | 跳过该路径，不报错 |
| SKILL.md 解析失败 | 跳过该 Skill，继续扫描其他 |
| ClawHub API 不可用 | 降级到本地 + 内置，不阻塞编排 |
| 磁盘 I/O 超时（> 2s） | 跳过该目录，用其他 Source |

## 调用接口

```javascript
// 编排器内部调用流程
async function discoverSkills(query) {
  const results = [];

  // Source 1: 本地扫描
  const local = await scanLocalPaths(LOCAL_PATHS);
  results.push(...local.map(s => ({ ...s, source: 'local' })));

  // Source 2: ClawHub（仅当本地不足时）
  if (results.length < 2) {
    const marketplace = await queryClawHub(query);
    results.push(...marketplace.map(s => ({ ...s, source: 'marketplace' })));
  }

  // Source 3: 自定义路径
  const customPaths = (process.env.SKILL_PATH || '').split(',').filter(Boolean);
  if (customPaths.length) {
    const custom = await scanLocalPaths(customPaths);
    results.push(...custom.map(s => ({ ...s, source: 'custom' })));
  }

  // Source 4: 内置兜底（始终可用）
  const builtin = getBuiltinFallback(query);
  results.push(...builtin.map(s => ({ ...s, source: 'builtin' })));

  // 评分排序
  const scored = results.map(s => ({
    skill: s,
    score: calculateScore(query, s)
  }));

  return scored.sort((a, b) => b.score - a.score);
}
```


path: references/human-in-the-loop.md
content: # Human-in-the-Loop — 人工确认节点

## 核心职责

在关键决策点暂停编排，等待用户明确确认后再继续执行。避免"启动后撒手不管"的风险。

## 确认节点类型

### Checkpoint A：编排计划确认（执行前）

```
═══════════════════════════════════════════════════
🛑 编排计划已生成，请确认后继续
═══════════════════════════════════════════════════

📋 任务概览：AI 简历工具创业方案
⏱️  预计执行：5 个子任务，并联 2 条，串联 3 步
🔧  将调用以下 Skill：
    1. 产品总监（产品规划）
    2. 财务顾问（财务评估）
    3. 技术选型（技术架构）
    4. 法律顾问（合规审查）

⏳  预计耗时：约 10-15 秒

───────────────────────────────────────────────────
请选择：
  [Y] 确认，开始执行
  [N] 取消，不执行
  [E] 编辑计划（修改子任务或 Skill）
  [A] 仅执行前 2 个任务

═══════════════════════════════════════════════════
```

### Checkpoint B：冲突裁决确认

```
═══════════════════════════════════════════════════
⚠️  检测到结论冲突，请确认处理方式
═══════════════════════════════════════════════════

📌 冲突点：定价策略

  方案 A（产品总监 Skill）：
    "高端路线，单价 ¥299，突出品牌溢价"

  方案 B（市场专家 Skill）：
    "性价比路线，单价 ¥99，主攻下沉市场"

───────────────────────────────────────────────────
主 Agent 建议：分层定价策略
  - 基础版 ¥99（获客引流）
  - 高级版 ¥299（深度服务）

请选择：
  [A] 采用方案 A
  [B] 采用方案 B
  [S] 采用主 Agent 建议（分层定价）
  [K] 保留双方结论，不裁决
═══════════════════════════════════════════════════
```

### Checkpoint C：高风险操作确认

```
═══════════════════════════════════════════════════
⚠️  高风险操作，需您明确授权
═══════════════════════════════════════════════════

📌 任务：部署 Web 应用至生产环境

⚠️  以下操作将被执行：
  - npm run build（构建项目）
  - git push origin main（推送代码）
  - 执行部署脚本（影响正式服务器）

💰 风险评估：此操作不可逆，请确保代码已就绪

请选择：
  [Y] 确认部署
  [P] 改为部署到预发布环境（staging）
  [C] 取消
═══════════════════════════════════════════════════
```

## 触发规则

```yaml
自动触发 Checkpoint 的条件：

Checkpoint-A（计划确认）：
  - 任务拆解后、子任务数 >= 3
  - 或用户历史上拒绝过类似编排

Checkpoint-B（冲突裁决）：
  - 检测到"数字结论冲突"或"方向结论冲突"
  - confidence < 0.75

Checkpoint-C（高风险操作）：
  - 任务涉及文件删除（delete_file）
  - 任务涉及 git push / 部署操作
  - 任务涉及外部 API 调用
  - 任务涉及个人信息处理

静默放行（无需确认）：
  - 子任务数 < 3 的简单编排
  - 纯分析/研究类任务
  - 用户明确说"直接执行"
```

## 响应处理

```typescript
switch (userResponse) {
  case "Y": continue(); break;
  case "N": abort(); return "已取消";
  case "E": enterEditMode(); break;      // 进入编辑模式
  case "A": runSubset(selectedTasks); break;  // 仅执行部分
  case "S": applySuggestion(); break;    // 采用建议
  case "K": keepBoth(); break;           // 保留分歧
  case "P": redirectToStaging(); break;   // 降级到预发布
}
```

## 上下文恢复

用户确认后，编排器恢复执行时输出：

```
═══════════════════════════════════════════════════
✅ 已确认，继续执行
═══════════════════════════════════════════════════
上次暂停点：Checkpoint-A（计划确认）
用户选择：确认，开始执行
⏯️  恢复编排，已跳过计划确认步骤

📡 启动第一个任务：产品规划...
═══════════════════════════════════════════════════
```


path: references/result-merger.md
content: # Result Merger — 结果合并与冲突裁决

## 核心职责

将多个子 Agent 的输出合并为统一的综合方案，处理内容重复、结论冲突、格式不一致等问题。

## 合并场景

### 场景 1：独立维度分析（无冲突）

```
Task-A 输出：产品定位报告（Markdown）
Task-B 输出：财务评估报告（Markdown）
Task-C 输出：技术选型报告（Markdown）
      ↓
合并策略：直接拼接 + 添加分隔标题
```

**合并格式：**

```markdown
# 综合方案报告

## 📦 一、产品规划
[Task-A 内容]

## 💰 二、财务评估
[Task-B 内容]

## ⚙️ 三、技术选型
[Task-C 内容]

## 🎯 四、整合建议
[主 Agent 交叉分析]
```

### 场景 2：同一问题给出不同结论（冲突）

```
Task-A："定价策略建议走高端路线，单价 ¥299"
Task-B："建议走性价比路线，单价 ¥99"
      ↓
裁决规则：
1. 若两结论差距 < 10%，取均值或合并
2. 若两结论差距 > 50%，标注"存在分歧"并列呈现
3. 主 Agent 给出裁决理由
```

**输出格式：**

```markdown
## ⚠️ 定价策略（存在分歧）

| 方案 | 建议方 | 理由 |
|---|---|---|
| 高端路线 ¥299 | 产品总监 | 品牌溢价、毛利空间 |
| 性价比路线 ¥99 | 市场专家 | 快速获客、市场渗透 |

**主 Agent 裁决**：综合考虑冷启动阶段的不确定性，建议采用
分层定价策略——基础版 ¥99（获客），高级版 ¥299（转化）。
```

### 场景 3：格式不一致

```
Task-A 输出：JSON
Task-B 输出：纯文本
Task-C 输出：Markdown 表格
      ↓
统一转换为结构化 Markdown
```

## 合并算法

```typescript
interface MergeResult {
  merged: string;           // 合并后的综合内容
  conflicts: Conflict[];    // 检测到的冲突列表
  summary: string;           // 一句话总结
  nextSteps: string[];      // 建议的后续行动
  confidence: number;      // 合并置信度 0-1
}

function mergeResults(taskResults: TaskResult[]): MergeResult {
  const conflicts = detectConflicts(taskResults);
  const merged = conflicts.length > 0
    ? mergeWithConflictNote(taskResults, conflicts)
    : simpleConcat(taskResults);

  return {
    merged,
    conflicts,
    summary: generateSummary(taskResults),
    nextSteps: generateNextSteps(taskResults),
    confidence: conflicts.length === 0 ? 0.95 : 0.7
  };
}
```

## 冲突检测规则

```yaml
冲突类型:
  - 名称: "数字结论冲突"
    检测: "两输出包含同一个数字指标但值不同"
    例: "Task-A 说成本 5 万，Task-B 说成本 15 万"
    
  - 名称: "方向结论冲突"
    检测: "两输出包含相斥的 action verb"
    例: "Task-A 建议扩张，Task-B 建议收缩"
    
  - 名称: "前提假设冲突"
    检测: "两输出的 base assumption 互相矛盾"
    例: "Task-A 以'目标用户是 Z 世代'为前提，Task-B 以'目标用户是职场人群'为前提"

裁决优先级:
  1. 有数据支撑 > 无数据支撑
  2. 最近数据 > 历史数据
  3. 更专业的 Skill > 更通用的 Skill
  4. 无法裁决 → 呈现双方 + 主 Agent 判断
```

## 长上下文与溯源

窗口变长后，仍优先向下游传递 **结构化摘要 + `step_id` +短证据摘录**（≤200 字/条），而非无脑拼接全文；冲突条目在 `machine-contract.md` 的 `evidence_snippet` 中落地，便于审计与人工复核。

## 输出格式规范

最终合并输出必须包含：

```yaml
final_output:
  task_overview: "一句话描述任务"
  skill_invocations: ["skill-A", "skill-B"]
  sub_task_results: [...]
  merged_content: "## 合并后内容..."
  conflicts_handled: [...]
  next_steps: ["建议1", "建议2"]
  confidence: 0.85
```


path: references/machine-contract.md
content: # Machine Contract — 机器可读附录

可选 JSON 供宿主、脚本或评测解析；**人类仍以 Markdown 为主**。在 Step 3（计划）、Step 6/7（合并与终稿）后可选用下列结构，放在 Markdown 代码围栏内并标注语言为 `json`。

## 会话与计划

```json
{
  "schema": "skill-orchestrator.bundle@v1",
  "session_id": "orch-20260414-a3f2",
  "user_goal_one_liner": "一句话用户目标",
  "intent": {
    "task_type": "综合方案 | 分析评估 | 内容生成 | 指导建议 | 信息查询",
    "domains": ["产品", "财务"],
    "complexity": "single | multi | complex",
    "constraints": ["时间紧", "无预算"]
  },
  "plan": {
    "steps": [
      {
        "id": "step-1",
        "skill": "builtin|skill-name",
        "mode": "default|acceptEdits|plan|bypassPermissions",
        "depends_on": [],
        "parallel_group": null,
        "risk_tier": "low|medium|high"
      },
      {
        "id": "step-2a",
        "skill": "产品总监",
        "mode": "acceptEdits",
        "depends_on": [],
        "parallel_group": "phase-2",
        "risk_tier": "low"
      }
    ]
  }
}
```

## 执行轨迹（可增量追加）

```json
{
  "session_id": "orch-20260414-a3f2",
  "events": [
    {
      "ts": "ISO8601",
      "step_id": "step-2a",
      "type": "task_start|task_complete|task_fail|checkpoint|merge",
      "message": "人类可读一句",
      "error_class": "timeout|refusal|tool_error|null"
    }
  ]
}
```

## 合并结果

```json
{
  "session_id": "orch-20260414-a3f2",
  "merge": {
    "summary": "一句话结论",
    "confidence": 0.88,
    "conflicts": [
      {
        "topic": "定价策略",
        "positions": [
          { "from_step": "step-2a", "claim": "¥299 高端", "evidence_snippet": "≤200 字摘录" },
          { "from_step": "step-2b", "claim": "¥99 性价比", "evidence_snippet": "≤200 字摘录" }
        ],
        "resolution": "分层定价 | 保留分歧 | 待用户裁决",
        "resolution_confidence": 0.82
      }
    ],
    "next_steps": ["建议 1", "建议 2"]
  }
}
```

## 使用约定

- 字段名可扩展，**勿删** `schema` / `session_id`（若输出 JSON）。
- `risk_tier`与 Registry 中 Skill 声明对齐时，利于自动 Checkpoint。
- 与 `orchestration-engine.md` 中 TypeScript 接口互补：接口偏实现，本文件偏**可交换数据**。


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)