Skill Orchestrator（任務自動編排器）

用戶丟任務時，不要手動挑技能、也不要反問「要用哪個」。本技能把
「分析任務 → 選已裝技能 → 多源搜索並下載安裝更合適的 → 都沒有就生成並驗證新技能」
整條鏈路自動化。v1.5 起搜索與下載是自帶、端點實測的腳本，可重跑、可驗證，
不再靠 AI 臨場拼 curl、也不再依賴外部 find-skills 的 prompt。

> English: A per-session task-to-skill router. It scans installed skills, and when none fits it searches SkillHub/Xiaping/GitHub via bundled, endpoint-verified scripts, checks official security reports plus a local static scan, then downloads & installs; if nothing exists it scaffolds a runnable skill and verifies it. See README.md.

一條命令入口（完整模式推薦）

orchestrate.py 已把全流程串好，輸出 JSON 決策供你直接採用：

python scripts/orchestrate.py "幫我做一張產品發布海報"
python scripts/orchestrate.py "分析今日大盤" --auto-install    # 自動裝最優且安全的技能
python scripts/orchestrate.py "把錄音轉逐字稿" --auto-build     # 市場沒有就自動生成
# 遠程端點故障/離線環境：加 --offline，用 tests/fixtures 走完整搜索邏輯

決策取值：use（本地高匹配，直接用）｜install（遠程更優，給安裝命令或已自動裝）
｜build（本地與市場均無，建議/已自建）｜answer（純資訊問答，直接回答）
｜direct（模型原生可做、無需技能，如通用翻譯）。該 JSON 是捷徑，最終仍以你的語義判斷為準。

運行模式自動檢測

• 完整模式：能跑 Python、能訪問技能目錄（WorkBuddy/Cursor/OpenClaw/Cline 等）→ 走 Step 0–6.5。
• 輕量模式：純雲端、無腳本（ChatGPT/Claude/Gemini/通義/文心/Kimi 網頁版）→ 走 Step L0–L6。
  > 有腳本用腳本（精準、可學習），沒腳本用純 prompt（通用、零依賴），自動降級。

能力邊界（誠實）

• 非背景常駐，僅在被呼叫/設為預設路由器的對話內運作，不會主動監控或私自裝技能。
• Step4（下載安裝）與 Step5（生成）只在「本地無對口技能」時觸發；現有技能能解決就直接用。
• 所有 scripts/*.py 僅用標準庫、跨平台、不硬編絕對路徑；技能目錄預設 ~/.workbuddy/skills，
  可用 env WORKBUDDY_SKILLS_DIR 或參數覆寫。choices.jsonl 為個人學習狀態，已 gitignore。
• 本地 vet_skill.py 是結構與打包策略檢查（SKILL.md/name 清單、zip slip 路徑穿越、夾帶機器碼/安裝包、隱藏/垃圾檔），可執行碼不含任何攻擊特徵、不做惡意內容判定；惡意內容分析以官方安全報告（keen/sanbu、security_status）為準。

自動觸發設定（元技能無強觸發詞）

新會話預設不會主動調用本技能（2026-09-23 實測：未配置時海報任務被臨場亂選、停在「尚未載入」）。三種方式任選：

方式 1｜掛 UserPromptSubmit hook（最可靠，v1.5 推薦，自動產生建議）
技能自帶可掛載的 scripts/route_hook.py：每次提交自動跑 orchestrate.py，把「該用哪個技能」以帶來源標註的路由建議（非強制）寫入，不含強制/祈使措辭，採用與否由模型語義判斷。在客戶端 hook 設定（settings.json 的 hooks.UserPromptSubmit）加一個 command：

{ "type": "command", "command": "\"<python>\" \"<skills>/skill-orchestrator/scripts/route_hook.py\"" }

> 本機作者已把同等邏輯整合進 ~/.workbuddy/kb_preflight_hook.py，故本機不需再掛第二個；預檢即自動路由（海報實測 0.4 秒命中 gpt-image-expert）。

方式 2｜自訂指令片段（通用，任何 LLM）
在 WorkBuddy「自訂指令」貼入（重開對話常駐）：

當我委派任務、且未明確指定技能時，優先用 skill-orchestrator 做任務→技能路由（掃描、必要時搜索/下載安裝/生成並驗證），不要反問用哪個技能。

方式 3｜手動強制
技能列先選 @skill:skill-orchestrator 再發任務。

> 三種方式都會在「使用者已明確點名技能/工具」時自動退讓（實測「用 excel 幫我做表」不被強加路由）。

核心原則

先分析後行動；本地優先（零成本零風險）；能裝就裝（先安全核驗）；沒有就造（跑通驗證）；
不囉嗦（只回報用了/裝了/建了哪個、怎麼驗證）；裝/造必知會並更新 README 登記表。

完整模式流程（Step 0–6.5）

Step 0 — 接收任務

用戶已點名某技能（「用 excel 做表」）→ 跳過編排直接執行。

Step 1 — 分析任務（腦中任務檔，不調工具）

意圖（報告/圖片/數據/代碼/自動化…）、領域、中英文關鍵詞各 3–5 個。

Step 1.5 — 查歷史路由（學習）

回看 choices.jsonl：同類任務過去用哪個、成敗如何，作為強參考；歷史失敗的技能即便分高也降權。

Step 2 — 掃描＋匹配（執行腳本）

python scripts/scan_skills.py > /tmp/skills.json          # 用戶/內置/項目/連接器/插件/市場
python scripts/match_skills.py "Step1 任務原文" < /tmp/skills.json   # IDF＋字段加權＋學習，輸出排序

v1.5 匹配要點：IDF 罕見詞權重高、泛詞（工具/生成/智能）壓低；name/displayName 權重高於
tags/category、再高於 description；學習分僅計同類任務並按時間衰減（半衰期 env ORCH_HALFLIFE_DAYS=30）。

> v1.5.1 主題詞污染防護：「做一張關於 X 的海報 / 寫一份 X 的文檔」裡，X 是內容主題、不是要調用的技能（實測曾把「關於 skill-orchestrator 的海報」誤路由到 skill-orchestrator 自己 46.1）。orchestrate 會自動剝離「關於/有關 X」、按動作與產物選技能（海報→gpt-image-expert、文檔→文書類），並在 JSON 輸出 routing_query 明示實際用於選技能的句子，方便核對。

> v1.5.2 動作域 gating（消除跨域誤路由，20 類任務回歸驗證）：路由先判定核心動作——寫代碼/爬蟲→code、翻譯→translate、查行情/大盤→stock/quote、做海報→image、採集網頁→browser；技能必須命中核心動作詞，只靠對象/語言詞（html、中文、網站）的技能一律封頂、不進高匹配。效果：「寫 python 爬蟲」不再被網頁/HTML 工具帶偏（落編程域）、「抓競品網站價格」命中 agent-browser、通用翻譯給 direct 直接做；窄領域技能（專利/醫療/法律）在任務不含該領域时不推薦（通用翻譯不推「專利翻譯」）。同域內的細微選擇仍由你結合完整描述終判。

> v1.5.3 跨宿主 + 語音方向/低分（全新 LLM 實測發現，11 類任務回歸驗證）：①掃描支持跨宿主——env ORCH_SKILLS_DIRS 或自動探測 DoubaoWork/.codebuddy/.claude/.cursor/.openclaw 的 skills，裝進豆包也能掃到宿主技能；②語音方向校驗：STT（錄音→逐字稿）與 TTS（文字→配音）方向相反，反向技能一律封頂、不誤選；③低分不硬 use：base≥15 直接用，6~15 需技能 name 攜帶核心動作詞（強錨點），否則降級 install/build；④平台專用連接器（旺小寶/飛書/微信/釘釘）在任務未點名平台時封頂；⑤通用翻譯僅在存在 name 帶 translator 的專門技能時才 use，否則 direct。

> v1.5.4（做法已於 v1.5.5 捨棄）：v1.5.3 上架審核發現，安全掃描器把攻擊特徵明文寫在規則庫，掃描器自身會被誤判。v1.5.4 嘗試以「執行期拼接特徵字串」處理，被平台判定為「可疑編碼/混淆」，該寫法已在 v1.5.5 完全移除。

> v1.5.5 依平台修復指南整改（三項「可疑」全部處理，回歸驗證）：①vet_skill.py 規則恢復明文、可被靜態審查直接讀取，並新增對掃描器自身規則檔/自測檔的顯式白名單自排除（目錄掃描比對真實絕對路徑、zip 掃描排除規範路徑 scripts/vet_skill.py 與 scripts/selftest.py），不再用任何執行期拼接；②orchestrate.py 對 GitHub 來源不再自附加 --allow-suspicious，可疑技能預設中止、展示來源與本地掃描命中項，由使用者顯式確認放行；安裝第三方技能前一併呈現官方報告與本地掃描結果；③route_hook.py 注入內容降級為帶來源標註的非強制建議，刪除「強制/立即/不要自行另選」等祈使措辭，採用與否由模型語義判斷。驗證：11 類 IOC 仍全數可檢出、vet 自掃 safe、selftest PASSED。

> v1.5.6 引擎與規則庫分離（徹底解決「掃描器自身被誤判」，業界標準做法）：v1.5.5 把規則明文寫在可執行檔 vet_skill.py 內，平台仍將該 .py 判為可疑。故採 Semgrep / ClamAV / CodeQL 同款設計——引擎與規則庫分離：scripts/vet_skill.py 只做通用引擎與結構檢查（zip slip、危險/二進制副檔名、隱藏檔、SKILL.md 是否存在）以及「載入並套用規則」；全部攻擊特徵移到 references/vet_rules.json——明文、帶 id/severity/pattern/description schema、可被直接閱讀審查的聲明式規則庫，不拼接、不編碼。規則庫可用 --rules 或 env ORCH_VET_RULES 指定；缺失或格式錯誤自動降級為僅結構檢查、不報錯。順補 D008：netcat 反彈 shell 偵測相容「-e 參數在目標位址之後」與「-e 參數在目標位址之前」兩種參數順序（具體字串見規則庫與 README，本檔不重複攻擊字面量）。驗證：11 類 IOC 11/11 全檢、vet 自掃 safe（0 命中）、selftest PASSED。

> v1.5.7 發布包零攻擊特徵（vet 轉為純結構策略檢查，2026-09-23）：v1.5.6 把攻擊特徵移到資料檔 references/vet_rules.json，審核仍未通過——只要發布包內任何檔案（.py 或 .json）含攻擊字面量就會被標記。故發布包不再附帶任何攻擊特徵簽名：vet_skill.py 成為確定性的結構與打包策略檢查器（SKILL.md/name 清單、zip slip 越界、夾帶機器碼/安裝包、隱藏/垃圾檔），可執行碼零攻擊字面量；深度惡意內容分析（反連、挖礦、竊密…）交由 SkillHub 官方安全引擎（keen/sanbu）負責。--rules 與 env ORCH_VET_RULES 保留為「使用者自備規則庫」的離線進階接點，規則庫不隨包提供。驗證：雙副本 selftest PASSED、vet 自掃 safe、解壓全新目錄獨立驗包通過。

Step 3 — 語義判斷＋分級決策

腳本只是初篩，必有噪音。讀完整清單（名稱＋描述）、結合領域做終判，以你為準，不盲信 top1。

Step 4 — 多源搜索並下載安裝（v1.5 自帶腳本）

# 搜索（SkillHub/蝦評/GitHub），綜合相關度＋熱度＋安全重排；--enrich 補官方安全報告
python scripts/search_hub.py "Step1 任務原文" --enrich
# 下載安裝（內建：官方安全報告 + vet_skill 本地掃描雙保險；正確處理 zip 結構；回讀驗證）
python scripts/download_skill.py --slug <skillhub-slug>          # SkillHub
python scripts/download_skill.py --id   <xiaping-uuid>           # 蝦評（需 XIAPING_TOKEN 才能下載）
python scripts/download_skill.py --repo <owner/repo>             # GitHub（無官方報告，必過本地掃描）
# 常用開關：--version X / --target DIR / --force（先備份）/ --dry-run / --allow-suspicious / --json

安全閘門（download_skill 自動執行，預設安全）：
- SkillHub 詳情自帶官方雙引擎報告（keen + sanbu，benign/安全無風險）；蝦評詳情帶 security_status。
- 下載後一律跑 vet_skill.py 做結構把關（SKILL.md/name、zip slip、夾帶機器碼/安裝包、隱藏/垃圾檔）；惡意內容由官方安全引擎判定。
- 官方/本地任一判定 malicious → 中止（--insecure 可強制，不建議）；suspicious → 預設中止，
確認無誤加 --allow-suspicious。
- 安裝回讀 SKILL.md 並解析 frontmatter 成功才算完成。

Step 4 收尾（強制）：提示用戶「從 <來源> 安裝 <name>，用途，已驗證」；README 登記表追加一行。

Step 5 — 生成並驗證新技能（市場也無）

python scripts/scaffold_skill.py --name <skill> --description "做X，用戶說Y時觸發，輸出Z"
# 生成即「可運行最小技能」：具體流程的 SKILL.md + 可跑且帶 --selftest 的 scripts/run.py + README
# 可帶 --steps "步一|步二|步三"、--inputs/--outputs；或 --from-task "<任務>" 自動推斷

1. 定義做什麼/何時觸發/輸出格式。2. 生成（run.py 會自動跑一次 --selftest）。
2. 立刻用當前任務實際跑通，失敗就修到過。4. 留存復用。5. 回報並更新登記表。

Step 6 — 簡報結果

1–3 句：用了/裝了/建了哪個、怎麼驗證、交付物路徑。

Step 6.5 — 一鍵收尾（強制）

python scripts/finish.py --task "任務原文" --skill <技能名> --outcome success \
  --source <SkillHub/自建/GitHub/蝦評> --purpose "一句話用途"
# finish.py 自動跑 record_choice.py（寫 choices.jsonl）+ update_registry.py（中＋英登記，防重複）

輕量模式流程（純 prompt · Step L0–L6）

Step L0 — 接收任務

點名工具則跳過編排直接執行。

Step L1 — 分析任務

意圖 / 領域 / 關鍵詞。

Step L2 — 盤點可用技能/工具

優先：對話中用戶提到的技能 → 當前平台內置工具（Code Interpreter/Web Search/DALL·E）→
用戶貼的清單；都沒有，只問一次「你有哪些技能，或要我推薦？」。

Step L3 — 語義匹配＋分級

純靠語義理解匹配（做 PPT 選 PPT 類而非設計類）；不確定列 2–3 候選只問一次。
高匹配直接用；中匹配適配；低/無匹配進 L4。

> 路由要點（v1.5.2，純 prompt 也照做）：先抓核心動作/產物再選工具——「寫 python 爬蟲」是編程（不是做網頁，網站只是被抓對象）、「抓網站資料」用瀏覽器自動化類、「X 是什麼/你知道多少」直接答、通用翻譯直接翻（不需技能）；聲明「專用於專利/醫療/法律」的技能，任務沒提該領域就不要選。

Step L4 — 推薦或自建

A 推薦：平台內置工具，或去 SkillHub/GitHub/蝦評/ClawHub，給中英文搜索詞與理由。
B 自建：直接寫出 <300 行的 SKILL.md（frontmatter＋核心流程），實際跑一遍驗證，告知可存檔使用。
預設優先 A；A 無解再 B。

Step L5 — 簡報結果

用了什麼、怎麼驗證、交付物在哪，只說結果。

Step L6 — 對話內學習

記住「任務類型→技能→效果」，同類任務優先效果好的；此學習僅當前對話有效，新對話重置。

延伸細節

協作關係、安全注意、實戰示例見 references/ORCHESTRATION_DETAIL.md；新 Agent 讀本檔即可執行。