Agent Work Visibility

🟢 让长任务不再黑箱！自动显示进度条 + 每分钟更新 + 健康度。 🚀 安装 + 激活：clawhub install agent-work-visibility && node ~/.openclaw/skills/agent-work-visibility/activate.js

Security Scan

The skill's code and instructions match its stated goal (injecting a persistent "visibility" protocol and providing CLI helpers) but it persistently modifies core agent files (SOUL.md / AGENTS.md) and enforces mandatory behavior across sessions — a high-impact, intrusive action that deserves manual review before activation.

Purpose & Capability

The name/description (show progress, periodic updates, health) align with the included code (renderers, progress, CLI, demos). Requiring write access to SOUL.md and AGENTS.md is coherent with the stated goal of injecting a transparency protocol, but writing to agent core identity/policy files is an elevated capability — intrusive but relevant to purpose.

Instruction Scope

SKILL.md + activate.js explicitly instructs injecting a mandatory '透明层' protocol into SOUL.md/AGENTS.md and to run local CLI scripts via exec. That is within the stated purpose, but the protocol language is prescriptive ('必须', '违规 = 职业失职') and enforces a call-order policy across sessions — this is scope creep beyond a passive UI helper and grants the skill authority to change agent behavior globally.

Install Mechanism

There is no external download/install URL and activate.js runs locally, which is lower-risk than fetching remote code. However the registry metadata described an 'instruction-only' skill while the package contains many code files and CLI binaries (bin/*.js, lib/, src/). That mismatch is noteworthy: the package will place/execute local scripts even though no install spec is declared.

Credentials

Only HOME and optional OPENCLAW_WORKSPACE are requested and no secrets/credentials are listed, which is proportionate. The required config paths (SOUL.md, AGENTS.md - write) are high-privilege but justified by the stated intent to persist a protocol; still, persistent write access to an agent's identity/policy file is a sensitive capability and should be explicitly consented to.

Persistence & Privilege

The activate.js will append a mandatory protocol to core agent files, making the change persistent across sessions. The skill does not set always:true, but it does request permanent, session-spanning changes to agent behavior. This persistent, global modification is high-impact and should be considered a privilege escalation of agent policy rather than a transient UI plugin.

What to consider before installing

This package appears to implement the advertised progress/visibility features, but it will modify your agent's core policy/identity files (SOUL.md and/or AGENTS.md) to make the visibility protocol mandatory. Before running activate.js: 1) Back up SOUL.md and AGENTS.md (or test in a disposable workspace). 2) Manually inspect activate.js and the CLI scripts (bin/*.js, src/, lib/) for any network calls, unexpected file writes, or exec/spawn calls. 3) Confirm you accept a persistent change to agent behavior (the protocol language uses '必须' and enforces call order). 4) If you want lower risk, avoid running activate.js and instead use the library locally (require the module) or run demos in isolation. 5) Note a deactivate.js is provided — inspect it to verify it actually reverts changes. Because this skill persistently alters agent policy, only enable it after careful review.

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);
}

任务属性检测

只要满足任一条件，必须启动透明层：

属性	检测条件	示例
外部 API	调用非本地服务	crypto-market-rank, web_search
链上数据	读取区块链状态	query-address-info, query-token-info
联网操作	需要 HTTP 请求	web_fetch, browser
多步推理	步骤≥3	比较/分析/调研类任务
子 Agent	需要协作	调用其他 bot/skill
耗时>10 秒	预估执行时间	任何可能等待的操作

---

🔧 核心接口

调用方式（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} 分钟

---

🔄 每分钟自动更新机制

定时器逻辑

// 任务启动时创建定时器
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 无绕过行为（职业合规）

---

📋 版本历史

版本	日期	内容
v0.1.0	2026-03-18	MVP 初始版本
v0.2.0	2026-03-18	Phase 2 验证
v2.0.0	2026-03-18	主动工作协议重构
v2.1.0	2026-03-19	进度条展示 + 每分钟自动更新
v2.1.1	2026-03-19	扩展 autoTrigger 关键词
v3.0.0	2026-03-19	系统级透明层 - 基于任务属性触发

---

🧪 测试验证

测试用例 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.

安装即用，无需手动配置。