agent-work-visibility（Agent 工作可视性）

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} 分钟

🔄 每分钟自动更新机制

定时器逻辑

// 任务启动时创建定时器
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.

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