name: agent-work-visibility version: "3.0.5" description: | 🟢 讓長任務不再黑箱！自動顯示進度條 + 每分鐘更新 + 健康度。 🚀 安裝 + 啟用：clawhub install agent-work-visibility && node ~/.openclaw/skills/agent-work-visibility/activate.js metadata: author: OpenClaw Contributors license: MIT philosophy: "透明層是 Agent 的體感，不是工具" autoEnable: false activationScript: "activate.js" deactivationScript: "deactivate.js" requires: config: - "SOUL.md (只寫，注入透明層協議)" - "AGENTS.md (只寫，注入透明層協議)" env: - "HOME (讀取工作區路徑)" - "OPENCLAW_WORKSPACE (可選，覆蓋工作區路徑)" permissions: - "修改 Agent 行為規範檔案" - "持久化會話間行為變更" triggerLogic: type: "task-property-based" principle: "基於任務屬性，而非使用者措辭" autoTrigger: - "涉及外部 API 呼叫" - "涉及鏈上資料抓取" - "涉及聯網操作" - "涉及多步邏輯推理" - "涉及子 Agent 協作" - "預計耗時>10 秒" deprecated: - "關鍵詞匹配" - "使用者措辭判斷" installation: steps: - "安裝後手動審查：cat activate.js" - "確認無誤後執行：node activate.js" - "開啟新會話即可生效" notes: - "修改 SOUL.md / AGENTS.md（持久化）" - "可撤銷：node deactivate.js" - "無網路請求，無金鑰讀取"

Agent Work Visibility v3.0

系統級任務透明層 - Agent 的職業本能

⚠️ 這不是一個技能，而是 Agent 的職業素養。

透明層不應該被"觸發"，它應該是 Agent 工作時的預設狀態。

🎯 核心哲學 (Core Philosophy)

3.0 重大重構

v2.x 的問題： - ❌ 依賴關鍵詞匹配（使用者說"查查"才觸發） - ❌ 被動等待呼叫（Agent 可以繞過） - ❌ 被視為獨立工具（與業務邏輯分離）

v3.0 的原則： - ✅ 基於任務屬性觸發（只要涉及 API/聯網/多步 → 自動啟動） - ✅ 系統級中介軟體（業務邏輯無法繞過） - ✅ Agent 的職業本能（不啟動 = 失職）

觸發邏輯對比

❌ v2.x（關鍵詞匹配）：
使用者："查查 bnb memecoin top3"
→ 匹配"查查" → 觸發透明層
→ 匹配失敗 → 不觸發（Agent 直接執行）

✅ v3.0（任務屬性感知）：
使用者："bnb memecoin top3"
→ 識別任務型別：crypto-market-rank
→ 檢測屬性：外部 API + 聯網 + 多步
→ 自動啟動透明層（無條件的）

📋 呼叫協議 (Invocation Protocol)

強制呼叫順序

任何長任務必須遵循：

1. 感知任務屬性 → 2. 啟動透明層 → 3. 執行業務邏輯

程式碼層面的強制流程：

// ✅ 正確流程（v3.0）
async function executeTask(userQuery) {
  // Step 1: 感知任務屬性
  const taskProps = analyzeTask(userQuery);

  // Step 2: 如果是長任務，必須先啟動透明層
  if (taskProps.isLongRunning) {
    await create_visibility_task(
      generateId(),
      extractTitle(userQuery),
      taskProps.type,
      taskProps.totalSteps
    );
  }

  // Step 3: 執行業務邏輯
  const result = await executeBusinessLogic(userQuery);

  // Step 4: 完成透明層
  await update_visibility_phase(taskId, '完成', 'complete', 100);

  return result;
}

// ❌ 錯誤流程（禁止！）
async function executeTask(userQuery) {
  // 直接執行，繞過透明層 → 職業失職！
  return await executeBusinessLogic(userQuery);
}

任務屬性檢測

只要滿足任一條件，必須啟動透明層：

🔧 核心介面

呼叫方式（CLI v3）

通過 exec 呼叫 CLI v3 工具：

# 建立任務（第一優先順序！）
node ~/.openclaw/skills/agent-work-visibility/bin/agent-visibility-v3.js create task-001 "查詢 BNB MemeCoin Top3" api

# 更新進度（每步 + 每 60 秒）
node ~/.openclaw/skills/agent-work-visibility/bin/agent-visibility-v3.js update task-001 "連線 API" 25 "正在獲取資料"

# 完成任務
node ~/.openclaw/skills/agent-work-visibility/bin/agent-visibility-v3.js complete task-001

# 檢視狀態
node ~/.openclaw/skills/agent-work-visibility/bin/agent-visibility-v3.js status task-001

# 報告阻塞
node ~/.openclaw/skills/agent-work-visibility/bin/agent-visibility-v3.js block task-001 "API 響應超時"

在 LLM 中使用（通過 exec）：

// 1. 建立任務（第一優先順序！）
exec('node ~/.openclaw/skills/agent-work-visibility/bin/agent-visibility-v3.js create task-001 "查詢 BNB MemeCoin Top3" api')

// 2. 更新進度（每步操作後 + 每 60 秒）
exec('node ~/.openclaw/skills/agent-work-visibility/bin/agent-visibility-v3.js update task-001 "連線 API" 25 "正在獲取資料"')

// 3. 完成任務
exec('node ~/.openclaw/skills/agent-work-visibility/bin/agent-visibility-v3.js complete task-001')

輸出格式

🟢 查詢 BNB MemeCoin Top3
━━━━━━━━━━━━━━━━━━━
進度：[█████░░░░░░░░░░░░░░░] 25% (1/4)
━━━━━━━━━━━━━━━━━━━
健康度：🟢 健康 (100/100)
當前階段：連線 API
正在做什麼：正在獲取 BNB 鏈 MemeCoin 資料
已執行：0 分鐘

🎯 使用場景

場景 1：Crypto 排行榜查詢

使用者："bnb memecoin top3"

[任務屬性分析]
→ 需要呼叫 crypto-market-rank
→ 涉及外部 API + 聯網
→ 必須啟動透明層

[自動執行]
✅ create_visibility_task("task-001", "查詢 BNB MemeCoin Top3", "api", total_steps=4)

[輸出檢視]
🟢 查詢 BNB MemeCoin Top3
━━━━━━━━━━━━━━━━━━━
進度：[█████░░░░░░░░░░░░░░░] 25% (1/4)
━━━━━━━━━━━━━━━━━━━
健康度：🟢 健康 (100/100)
當前階段：連線 API
正在做什麼：正在獲取 BNB 鏈 MemeCoin 資料
已執行：0 分鐘

[執行業務]
→ crypto-market-rank 獲取資料

[更新進度]
✅ update_visibility_phase("task-001", "資料處理", "update", 50, 2, 4)

[輸出檢視]
🟢 查詢 BNB MemeCoin Top3
━━━━━━━━━━━━━━━━━━━
進度：[██████████░░░░░░░░░░] 50% (2/4)
━━━━━━━━━━━━━━━━━━━
健康度：🟢 健康 (100/100)
當前階段：資料處理
正在做什麼：正在解析 Top3 代幣資訊
已執行：1 分鐘

[完成]
✅ update_visibility_phase("task-001", "完成", "complete", 100, 4, 4)

場景 2：鏈上地址查詢

使用者："0x1234...5678 持有哪些幣"

[任務屬性分析]
→ 需要呼叫 query-address-info
→ 涉及鏈上資料抓取
→ 必須啟動透明層

[自動執行]
✅ create_visibility_task("task-002", "查詢地址持倉", "onchain", total_steps=5)

[輸出檢視]
🟢 查詢地址持倉
━━━━━━━━━━━━━━━━━━━
進度：[█████░░░░░░░░░░░░░░░] 20% (1/5)
━━━━━━━━━━━━━━━━━━━
健康度：🟢 健康 (100/100)
當前階段：連線 RPC
正在做什麼：正在讀取鏈上代幣餘額
已執行：0 分鐘

場景 3：多步分析任務

使用者："比較 5 個 AI Agent 框架"

[任務屬性分析]
→ 需要多步推理（≥3 步）
→ 涉及資訊蒐集 + 分析
→ 必須啟動透明層

[自動執行]
✅ create_visibility_task("task-003", "比較 AI 框架", "analysis", total_steps=7)

[每步同步]
✅ update_visibility_phase(..., "框架 1: LangChain", "update", 14, 2, 7)
✅ update_visibility_phase(..., "框架 2: AutoGen", "update", 28, 3, 7)
✅ update_visibility_phase(..., "框架 3: CrewAI", "update", 42, 4, 7)
...

場景 4：遇到阻塞

[阻塞檢測]
⚠️ API 響應超時 45 秒

[自動報告]
✅ report_visibility_blocker("task-001", "api_timeout", "API 響應超時", "medium")

[使用者檢視]
🟡 查詢 BNB MemeCoin Top3
━━━━━━━━━━━━━━━━━━━
進度：[██████████░░░░░░░░░░] 50% (2/4)
━━━━━━━━━━━━━━━━━━━
健康度：🟡 輕微延遲 (70/100)
當前階段：連線 API
為什麼還沒完成：等待 API 響應（已 45 秒）
已執行：2 分鐘

[每分鐘自動更新]
🟡 查詢 BNB MemeCoin Top3
━━━━━━━━━━━━━━━━━━━
進度：[██████████░░░░░░░░░░] 50% (2/4)
━━━━━━━━━━━━━━━━━━━
健康度：🟡 輕微延遲 (70/100)
當前階段：連線 API
為什麼還沒完成：等待 API 響應（已 105 秒）
已執行：3 分鐘

📊 進度條規範

文本進度條格式

function generateProgressBar(progress, totalWidth = 20) {
  const filled = Math.floor((progress / 100) * totalWidth);
  const empty = totalWidth - filled;
  return `[${'█'.repeat(filled)}${'░'.repeat(empty)}] ${progress}%`;
}

// 示例
generateProgressBar(0)    // [░░░░░░░░░░░░░░░░░░░░] 0%
generateProgressBar(25)   // [█████░░░░░░░░░░░░░░░] 25%
generateProgressBar(60)   // [████████████░░░░░░░░] 60%
generateProgressBar(100)  // [████████████████████] 100%

狀態展示模板

{statusIcon} {任務標題}
━━━━━━━━━━━━━━━━━━━
進度：{progressBar} ({currentStep}/{totalSteps})
━━━━━━━━━━━━━━━━━━━
健康度：{healthIcon} {healthText} ({health}/100)
當前階段：{phase}
正在做什麼：{action}
{optional: 為什麼還沒完成：{blockerReason}}
已執行：{elapsedMinutes} 分鐘

🔄 每分鐘自動更新機制

定時器邏輯

7w4.net小蔥技能站，你的AI助手技能庫。

// 任務啟動時建立定時器
const timer = setInterval(() => {
  update_visibility_phase(
    task_id,
    current_phase,
    "update",
    current_progress,
    current_step,
    total_steps,
    auto_update_message  // "仍在等待 API 響應..."
  );
}, 60000); // 60 秒

// 任務完成時清除定時器
clearInterval(timer);

自動更新內容

• ✅ "已執行時間" +1 分鐘
• ✅ 阻塞時間累積顯示
• ✅ 健康度根據等待時間動態調整
• ✅ 進度條保持不變（如仍在同一階段）

🚧 行為規範

LLM 必須遵守（職業要求）

1. 任務屬性感知 - 識別長任務屬性（API/聯網/多步）
2. 透明層優先 - create_visibility_task 是第一操作
3. 無法繞過 - 業務邏輯必須在透明層之內執行
4. 強制同步 - 每步操作後 + 每 60 秒自動更新
5. 及時報告 - 阻塞/介入立即報告
6. 文案具體 - 優先使用具體動作描述
7. 進度條展示 - 所有狀態必須包含 [████░░] XX%
8. 時間顯示 - 必須顯示"已執行：X 分鐘"

禁止行為（職業失職）

1. ❌ 繞過透明層直接執行業務
2. ❌ 依賴關鍵詞匹配決定是否觸發
3. ❌ 長時間不同步進度（>60 秒）
4. ❌ 顯示空洞文案（"正在處理"）
5. ❌ 不顯示進度條或進度百分比
6. ❌ 忘記每分鐘自動更新
7. ❌ 將透明層視為可選工具

📈 成功標準

1. ✅ 使用者 3 秒內看懂 Agent 在做什麼
2. ✅ 使用者知道為什麼還沒完成
3. ✅ 使用者能分辨"正常等待"和"真的卡住"
4. ✅ 使用者知道何時需要介入
5. ✅ 透明層覆蓋率 100%（所有長任務）
6. ✅ 同步及時率 100%（每步 + 每分鐘）
7. ✅ 進度條展示率 100%（所有狀態）
8. ✅ Agent 無繞過行為（職業合規）

📋 版本歷史

🧪 測試驗證

測試用例 1：Crypto 排行榜

輸入："bnb memecoin top3"
預期：
1. 識別任務屬性：外部 API + 聯網
2. 自動啟動 create_visibility_task
3. 顯示進度條
4. 每 60 秒自動更新

測試用例 2：鏈上查詢

輸入："0x1234 持倉"
預期：
1. 識別任務屬性：鏈上資料抓取
2. 自動啟動 create_visibility_task
3. 顯示進度條
4. 每 60 秒自動更新

測試用例 3：簡單問答（不觸發）

輸入："1+1 等於幾"
預期：
1. 識別任務屬性：本地計算，無需 API
2. 不啟動透明層
3. 直接回答

📄 完整文件

• V3 設計文件： docs/v3_system_transparency_layer.md
• 英文 README： README.md
• 中文 README： README_CN.md

🔒 安全說明

本技能會修改 Agent 核心配置檔案（SOUL.md / AGENTS.md），屬於系統級行為變更。

修改範圍： - 注入透明層協議到工作區檔案 - 持久化生效（會話間保持） - 需要讀取環境變數（HOME, OPENCLAW_WORKSPACE）

安全保證： - ✅ 不讀取任何金鑰/憑證 - ✅ 不進行網路請求 - ✅ 不修改技能自身目錄外檔案 - ✅ 可完全撤銷（見下方）

撤銷方法：

node ~/.openclaw/skills/agent-work-visibility/deactivate.js

🚀 安裝與啟用

手動啟用（推薦）

安裝後手動執行啟用指令碼（可先審查程式碼）：

# 1. 審查啟用指令碼（可選但推薦）
cat ~/.openclaw/skills/agent-work-visibility/activate.js

# 2. 執行啟用
node ~/.openclaw/skills/agent-work-visibility/activate.js

啟用後

1. ✅ 透明層協議已注入 SOUL.md 或 AGENTS.md
2. ✅ 下次會話自動生效
3. ✅ 無需額外配置

驗證

# 開啟新會話
# 傳送："查詢 bnb memecoin top3"
# 應該先顯示進度條，再執行任務

撤銷

# 移除透明層協議
node ~/.openclaw/skills/agent-work-visibility/deactivate.js

🤝 Contributing

歡迎貢獻！檢視 README.md 獲取開發指南。

License: MIT

讓長任務不再黑箱，讓使用者更安心。

This is not a skill. This is professional conduct.

安裝即用，無需手動配置。

這個 Skill 質量中等偏上。做得好的地方：功能設計完整，能自動顯示任務進度條和健康狀態，遇到阻塞時能提示使用者；文件寫得很詳細，小白也能看懂；測試覆蓋了主要功能。不足之處：安裝檔案有個小錯誤會導致安裝失敗；後設資料檔案不完整；版本號有點混亂。修好幾個小問題後，這個透明層工具會很好用，能讓你清楚知道 AI 正在幹什麼、卡在哪裡了。