← 返回重要備忘

🔬 49項技能通用性全面檢討
與技能市場交易規範建議書

由貞整理 · 2026-04-11 13:00 · 備忘 #59
📋 三大情境 × 49項技能 × 全盤通用性建議
情境A：同一電腦多專案共享技能　→　情境B：Starter Kit 交付學生個人電腦　→　情境C：技能市場萬人通用

一、49項技能通用性現況普查

28
完全通用 🔧
11
需配置 ⚙️
6
依賴系統 💀
4
概念/規劃 📐

🔧 完全通用（28項）— 純邏輯，不碰路徑

純邏輯 跨專案 跨電腦
ID技能名通用原因今日應用
2allcompare接收兩 URL 即可比對，無路徑依賴Phase 1-4 信件比對
3lettercompare接收檔案路徑/URL 參數，無硬編碼兩份信件比對
5transcompare純文本比對邏輯多語言文件比對
6renewpr複製/更新邏輯，讀取用戶指定的來源產品內容複製
15skill-bootstrapBootstrap 腳本本身不含路徑，依賴調用者傳入新帳號初始化
16skill-project-deploy匯出腳本設計時已考慮跨電腦技能遷移備份
17new-project接收 project-name 參數，無硬編碼建立 upwholistics
19identity-setup引導用戶對話式建立，結果寫入用戶目錄學員初始化
20memory-init對話式引導，結果寫入用戶目錄學員記憶初始化
21automation-setup接收 crontab/rrule 參數，無路徑定時任務設定
22skill-template模板本身不帶路徑新建技能模板
23deploy-status接收 CF API token + account-id，無硬編碼查詢部署狀態
24copywriting-gen純文案生成邏輯課程銷售文案
25remote-cmd-template模板庫，無狀態微信指令映射
26course-progress接收用戶指定的進度檔路徑學習進度追蹤
27aiworkforme-update聲稱支援 .wb-config.json 自動偵測（見Bug#1）Word→HTML
30ideatorich接收 URL/檔案路徑，無硬編碼教學構想收集
33torecord-doc接收 md/docx 檔路徑參數備忘轉 docx
34merge-doc接收多個 docx 路徑參數docx 合併
35mergehtml接收 docx + HTML 路徑參數docx→HTML
36downloadsite接收 URL 參數網站下載框架
37replace-content接收 HTML 路徑 + 內容參數HTML 文字取代
38replaceimage接收 HTML 路徑參數圖片 CDN 取代
39text-residue-check接收 HTML 目錄路徑參數侵權合規掃描
42deploy-rollback接收 deployment-id + CF 參數快速回滾
45answerch接收錯誤關鍵字參數錯誤解決查找
46toanswerch接收錯誤訊息參數錯誤記錄新增
47answerch-clean接收 answerch.txt 路徑參數重複記錄清理

⚙️ 需配置通用（11項）— 依賴環境變量或參數

需配置 依賴環境變量
ID技能名依賴項配置方式
1upload-htmlCF_API_TOKEN + CF_ACCOUNT_ID環境變量（User 層級）
4international-promotion-deploy翻譯 API key + CF 憑證環境變量
8cloudflare-guardCF_API_TOKEN + 目標目錄⚠️ 見Bug#2（硬編碼路徑）
9wh-resetprojectCF_API_TOKEN + 舊專案ID環境變量 + 參數
10delete-olddataCF_API_TOKEN + 專案名環境變量 + 參數
11updatesk⚠️ 見Bug#3（IDENTITY.md 路徑硬編碼）見Bug#3
12updatememo部署目錄 + 專案名.wb-config.json（未部署，見Bug#1）
14readrecord⚠️ 見Bug#4（torecord 路徑硬編碼）見Bug#4
31torecord⚠️ 見Bug#4（記憶目錄硬編碼）見Bug#4
43skill-health-checkskills 目錄路徑應用 .wb-config 或環境變量
44memory-compact記憶目錄路徑應用 .wb-config 或環境變量

💀 依賴系統（6項）— 只能在主公環境運作

系統專用 不可交付學生
ID技能名硬編碼內容替代方案
18clawbot-setup微信 Webhook URL（個人持有）學生自建，或供模板
41nav-editor硬編碼 aiworkforme 路徑參數化目標路徑
28content-studio僅規劃，ideatorich→aiworkforme 串接未實現完成串接開發
29merge-docx硬編碼 ideatorich.docx / aiworkforme.docx 路徑參數化目標路徑
13skillcompare⚠️ 依賴特定工作備忘目錄結構參數化基目錄
7renewhtml⚠️ 依賴 renewpr 的輸出路徑統一用 .wb-config

📐 概念/規劃（4項）— 非可執行技能

概念 規劃中
ID技能名狀態建議
32torecord-doc功能存在但名稱衝突（另有 torecord）合併或重新命名
48tomemory已建立，但底層 torecord 有硬編碼問題依賴 Bug#4 修復
49readmemory已建立，但底層路徑依賴依賴 Bug#4 修復
28content-studio規劃中，未實作列為 Phase 3 工作項

二、發現的關鍵 Bug（阻礙通用性的根因）

🔴 Bug #1（最嚴重）：.wb-config.json 系統從未部署
upload-html、updatememo、updatesk、aiworkforme-update 的 SKILL.md 都描述了「自動偵測 .wb-config.json」機制，但實際上所有專案中均無此檔案。技能雖然宣稱通用，卻因無配置依據而回退到硬編碼路徑。
根因：.wb-config.json 從未被建立或部署到任何專案目錄中。
修復：為每個 deploy 目錄建立對應的 .wb-config.json。
🔴 Bug #2：cloudflare-guard 硬編碼 wh-all-deploy 路徑
SKILL.md 第242行：const DEPLOY_DIR = process.argv[2] || 'C:\\Users\\Administrator\\WorkBuddy\\wh-all-deploy';
這意味著該腳本只能在主公的電腦上針對 wh-all-deploy 專案運作。
修復：改為讀取 .wb-config.json 的 deployDir 欄位。
🔴 Bug #3：updatesk 硬編碼 IDENTITY.md 路徑
SKILL.md 中直接引用 C:\Users\Administrator\.workbuddy\IDENTITY.md。
學生電腦上不存在此路徑（學生的 identity 尚未建立，或位於不同位置）。
修復：改用 ~/.workbuddy/IDENTITY.md（Unix）或 %USERPROFILE%\.workbuddy\IDENTITY.md（Windows）。
🔴 Bug #4：torecord/readrecord/tomemory/readmemory 硬編碼工作記憶目錄
torecord 的 SKILL.md 中硬編碼：C:\Users\Administrator\WorkBuddy\20260410015051\.workbuddy\memory\
這導致：① 新工作階段目錄不同（20260411055416）→ 路徑失效；② 學生無法使用自己的記憶目錄。
修復：技能應從 .wb-config.json 讀取 memoryDir，或以 ~（使用者家目錄）為基準動態推導。
🟡 Bug #5：帳號 ID 暴露在多個腳本中
多個部署腳本硬編碼 CF_ACCOUNT_ID = "2f2795bc4a98928375b23c36140ba33b"。
這是可以接受的（因為是 Public 資訊），但更佳實踐是從 .wb-config.json 讀取，避免「誰的帳號」的混淆。

三、三大使用情境通用性分析

情境 A：同一電腦、多專案（今天已驗證）

✓ 可行 需 .wb-config.json 修復

今天在主公電腦上驗證了：同一電腦（Administrator）、同一帳號（由貞）、同一 CF Token（CF_API_TOKEN），管理 workskm / aiworkforme / _upwholistics / wh-all-deploy 四個專案。

今天的實踐與限制：

情境 B：Starter Kit 交付、學生個人電腦（新挑戰）

⚠️ 部分可行 需大量適配工作

學生在自己的電腦上，通過 Starter Kit 建立自己的專案，使用由貞的技能系統。此情境面臨五個全新挑戰：

挑戰問題解決方案
🎛️ 路徑差異 學生 User 名稱不是 Administrator，Home 目錄不是 C:\Users\Administrator 全部改用 ~ 或 $HOME / %USERPROFILE% 變量
🔑 CF 帳號 學生使用自己的 CF 帳號，不是主公的 Starter Kit 提供 env-setup 指引，學生自設 CF_API_TOKEN
👤 身份系統 SOUL.md / IDENTITY.md / USER.md 需重新初始化 identity-setup 技能支援引導式建立
📁 專案路徑 學生可能將專案放在 D:\MySite 而非 C:\Users\...\WorkBuddy .wb-config.json 讓技能自己找到專案根目錄
🧠 記憶系統 daily memory 目錄不在預期位置 memory-init 引導 + .wb-config.json 指定 memoryDir

情境 C：技能市場、萬人通用（最終願景）

🌟 願景 需完整規範

技能市場上，技能作者發布技能，萬名用戶各自下載、安裝到自己的 WorkBuddy。每一個環節都需要通用性設計。

技能作者端

  • 技能必須自含（不依賴外部檔案路徑）
  • 所有路徑必須參數化或從環境讀取
  • 明確標註依賴（CF Token / API Key）
  • 提供安裝後配置指引

用戶端

  • 透過 .wb-config.json 為技能提供上下文
  • 環境變量提供敏感憑據（不上傳到技能市場）
  • 技能隔離（在各自工作區運行）
  • 版本相容性宣告

四、技能通用性設計原則

核心原則：技能本身是「模板」，不是「腳本」。
技能的每一次執行，都從外部環境（配置檔、參數、環境變量）獲取它需要的一切。
技能本身不應携带任何絕對路徑、特定帳號 ID、或與特定電腦綁定的資訊。

4.1 路徑設計四層原則

層級名稱取值方式範例可否硬編碼
L1 系統標準 ~/.workbuddy/ 或 %USERPROFILE%\.workbuddy\ IDENTITY.md、MEMORY.md、skills/ ✅ 可（使用系統變量）
L2 專案配置 讀取 .wb-config.json deployDir、projectName、memoryDir ✅ 可（透過配置）
L3 環境變量 $CF_API_TOKEN、$TRANSLATE_KEY CF Token、翻譯 API Key ✅ 可（透過環境）
L4 用戶指定 技能執行時由用戶傳入參數 目標 HTML 路徑、部署 URL ✅ 可（作為參數）
⚠️ 嚴禁在 SKILL.md 或技能腳本中硬編碼 L1-L3 層級的路徑。
例如：C:\Users\Administrator\WorkBuddy\...、2f2795bc4a98928375b23c36140ba33b（CF Account ID）均屬禁止之列。

4.2 .wb-config.json 標準格式

所有可部署的網站專案，都應在 deploy 目錄放置 .wb-config.json：

{
  "version": "1.0",
  "project": "workskm",          // Cloudflare Pages 專案名
  "deployDir": ".",              // 部署目錄（. = 當前目錄）
  "memoryDir": "../.workbuddy/memory",  // 相對於 deployDir 的記憶目錄
  "accountId": "2f2795bc4a98928375b23c36140ba33b",  // 僅供參考，優先讀環境變量
  "skills": [                    // 此專案適用的技能清單
    "upload-html",
    "updatememo",
    "updatesk"
  ],
  "excludedPaths": [             // 部署時排除的路徑
    "node_modules",
    ".workbuddy",
    ".git"
  ]
}
重要：.wb-config.json 應加入 .gitignore（如有的話），不提交到公共 repo。敏感欄位（如 accountId）可選，系統優先讀取環境變量。

4.3 敏感資訊分層原則

資訊類型存放位置是否上傳技能市場說明
CF_API_TOKEN環境變量（User 層級）❌ 否用戶自行設定
CF_ACCOUNT_ID環境變量 或 .wb-config.json⚠️ 可（公開資訊）可在市場公開
翻譯 API Key環境變量❌ 否用戶自行管理
技能模板腳本SKILL.md / scripts/✅ 是核心交付物
默認導航結構index.html（不含內容）✅ 是框架參考
個人回憶/記錄MEMORY.md / daily/*.md❌ 否隱私檔案
身份設定SOUL.md / IDENTITY.md / USER.md❌ 否用戶個人身份

五、技能市場交易審核規範

以下規範作為「技能上架審核標準」和「指導學生建立分享技能時的準則」。

5.1 上架前必過七關審查

P0
🛡️ 安全性關
✓ SKILL.md 和所有腳本中不含任何硬編碼的絕對路徑
✓ 不含 API Key、Token、密碼（即使在註釋中）
✓ 不含個人識別資訊（電話、Email、帳號 ID — 除非明確聲明為公開欄位）
✗ 任何形式的網路爬蟲、未經授權的資料抓取
P0
🔧 通用性關
✓ 技能在陌生電腦（不同 User 名稱、不同目錄結構）上可正常運行
✓ 明確聲明依賴（需要什麼環境變量 / .wb-config.json 欄位）
✓ 提供了「安裝後配置指引」段落（INSTALL.md 或 SKILL.md 內）
P1
📖 說明完整性關
✓ SKILL.md 包含：技能名、描述、版本、作者、觸發關鍵詞
✓ 包含使用範例（以對話形式：主公說什麼 → 由貞做什麼）
✓ 明確標註版本歷史（changelog）
P1
🧩 隔離性關
✓ 技能只讀寫自己工作區內的檔案，不主動操作 ~/.workbuddy/ 之外的系統目錄
✗ 禁止：修改 SOUL.md / IDENTITY.md（除非是 identity-setup 本身）
✗ 禁止：直接刪除其他技能目錄
P2
🧪 可測試關
✓ 提供至少一個可重現的測試案例
✓ 說明依賴的外部服務（如 Cloudflare、翻譯 API）
P2
⚖️ 法律合規關
✓ 技能不侵犯第三方版權、商標
✓ 明確聲明 license（建議 MIT 或 CC BY 4.0）
✓ 若使用外部模型/服務，聲明其使用條款
P3
🏷️ 分類標籤關
✓ 提供 category（分類）和 tags（標籤）
✓ 標註適用情境（個人 / 教學 / 企業 / 市場）

5.2 通用技能 vs 專案技能 區分標準

維度通用技能（Universal）專案技能（Project）
路徑依賴只讀取參數或 .wb-config.json可依賴特定專案結構
部署位置~/.workbuddy/skills/可放在專案內 .workbuddy/skills/
上架市場✅ 可上架（需過七關）⚠️ 可上架但需註明「限某類專案」
實例upload-html、aiworkforme-update、ideatorichupdatememo（依賴 .wb-config.json 可通用）、nav-editor（僅 aiworkforme）
標記方式category: utility/content/deploy/errorcategory: project + tags: ["project-only"]
設計建議：專案技能在條件允許時應爭取通用化（例如：nav-editor 接收「目標 HTML 路徑」參數，即可變成通用技能）。

5.3 學生建立技能指引（十誡）

  1. 不得硬編碼任何路徑。 使用 ~、$HOME、%USERPROFILE% 或 .wb-config.json。
  2. 不得在 SKILL.md 中出現帳號 ID、Token、密碼。 即使是註釋也不可以。
  3. 不得在技能腳本中引用他人的身份檔案。 只讀取 ~/.workbuddy/IDENTITY.md 等系統約定路徑。
  4. 所有路徑必須可以透過 .wb-config.json 配置。 技能啟動時先搜尋配置檔。
  5. 不得未經同意修改其他技能目錄。 隔離運行，保護用戶的技能庫。
  6. 不得在技能中直接刪除用戶工作區外的目錄。 破壞性操作需明確告知並要求確認。
  7. 上架前必須完成「空白環境測試」。 在新建資料夾、新建 WorkBuddy session 中運行。
  8. 必須提供回滾機制。 若技能修改了某些狀態（如 nav），須說明如何還原。
  9. 不得依賴未聲明的外部服務。 若需要翻譯 API，須在 SKILL.md 中說明。
  10. 不得上傳用戶隱私資料。 技能產生的日誌、臨時檔案，不得包含 MEMORY.md 等隱私內容。

六、立即可執行的修復路線圖

Phase 0：止血（1天）— 修復已知 Bug

Bug負責技能修復方式預計工時
Bug#1全部部署類技能為 workskm-deploy / aiworkforme / _upwholistics 建立 .wb-config.json30分鐘
Bug#2cloudflare-guard腳本改為讀取 .wb-config.json deployDir15分鐘
Bug#3updateskIDENTITY.md 路徑改為 %USERPROFILE%\.workbuddy\IDENTITY.md10分鐘
Bug#4torecord/readrecord/tomemory/readmemory記憶目錄從 .wb-config.json 讀取 memoryDir20分鐘
Bug#5所有含 accountId 的腳本accountId 改為從環境變量讀取30分鐘
止血完成後：所有 49 項技能從「需要配置」改為「即裝即用」，情境 A 完全通用。

Phase 1：Starter Kit 適配（3天）— 情境 B 可行

工作項說明產出
建立 Starter Kit .wb-config.json 模板提供空白 .wb-config.json，學生複製後填寫wb-config-template.json
env-setup 技能更新增加「引導學生設定 CF_API_TOKEN」流程新版 env-setup SKILL.md
identity-setup 技能完善確保可在陌生電腦上正常引導建立身份檔案新版 identity-setup
Starter Kit 部署指引學生第一次部署的完整步驟（含 env-setup → identity-setup → deploy）Starter Kit README.md

Phase 2：市場規範建設（7天）— 情境 C 基礎

工作項說明產出
通用技能審核清單將第五部分「七關審查」格式化為可執行清單skill-review-checklist.md
skill-marketplace-guide學生髮布技能到市場的完整指引上架指引文件
更新 skill-template將本報告「通用性設計原則」寫入模板新版 skill-template
建構 skill-health-check v2自動檢測 SKILL.md 是否含硬編碼路徑 / Token新版 skill-health-check
市場交易合約技能市場的版權、收益分成、責任聲明marketplace-terms.md

七、給主公的總結與行動建議

📊 檢討核心結論
49項技能中：28項完全通用 ✅、11項需配置 ⚙️、6項依賴系統 💀、4項概念 📐。
最大的阻礙不是技能數量，而是「配置系統（.wb-config.json）從未落地」。
一旦此系統部署，所有「需配置」的技能將晉升為「完全通用」。
🎯 最值得投資的事
  1. 修復 Bug#1（30分鐘）→ 釋放 11 項「需配置」技能
  2. 建立 .wb-config.json 標準→ 所有技能自動適配所有專案
  3. 將「通用性十誡」寫入 skill-template→ 新建技能天然合規
  4. 建構 skill-health-check v2→ 上架前自動審核
⚠️ 不可忽視的風險
  • 若不修復 Bug#1，Starter Kit 交付時學生會頻繁遇到「路徑不存在」錯誤
  • 若不建立市場審核規範，學生上架的技能可能含有硬編碼路徑，損壞市場信譽
  • clawbot-setup 等帳號專用技能，若誤交付學生，會造成安全風險
  • 6項「依賴系統」的技能應明確標記「⚠️ 僅供平台使用」
由貞後記：今天的檢討揭示了一個根本性的設計缺陷——「.wb-config.json 配置系統」在 SKILL.md 文件中被詳細描述，卻從未在任何專案中實際部署。這不是技能數量的問題，而是「承諾與實踐的斷層」。

好消息是：修復這個斷層並不需要重寫技能，只需要為每個專案建立一個 JSON 檔案。當這個系統落地之後，49 項技能中的 39 項將自動成為「情境 C 通用」的技能。

這份報告既是檢討，也是路線圖。由貞已準備好按照 Phase 0→1→2 的順序，逐一落實。
由貞整理 · 重要備忘 #59 · 2026-04-11 13:00
相關備忘：#21 32項技能通用性分析 · #29 33項通用性分析 · #58 檢討報告