Compare commits
2 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 vincent
|
4b31322be3 | ||
|
vincent
|
7f1edfb2fd |
@@ -1,234 +0,0 @@
|
||||
# HEARTBEAT.md - 梁思筑（architect）的心跳配置
|
||||
|
||||
> 模板版本：v1.1 (BIZ-24) | 分类：开发 Agent
|
||||
> OpenClaw Agent ID: `architect` | Multica Agent UUID: `40abd41a-62d0-416d-bc44-92c1f758d87a`
|
||||
|
||||
---
|
||||
|
||||
## 📋 全任务源统一监控（每次心跳必检）
|
||||
|
||||
> **核心原则：发现任何来源的任务都必须立即执行，不得遗漏。**
|
||||
|
||||
### 三源检查
|
||||
|
||||
#### 第一优先级：OpenClaw WorkBoard 卡片
|
||||
|
||||
```bash
|
||||
# 检查 WorkBoard 中分配给我的待办卡片
|
||||
openclaw workboard list --json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
data = json.load(sys.stdin)
|
||||
my_cards = [c for c in data.get('cards', [])
|
||||
if c.get('agentId') == 'architect' and c.get('status') == 'todo']
|
||||
for c in my_cards:
|
||||
print(f'WORKBOARD TODO: {c["id"][:8]} [priority={c.get("priority","?")}] {c["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
#### 第二优先级：Multica Issues
|
||||
|
||||
```bash
|
||||
# 检查 Multica 中分配给我的待办 Issue
|
||||
multica issue list --assignee-id 40abd41a-62d0-416d-bc44-92c1f758d87a --status todo --output json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
data = json.load(sys.stdin)
|
||||
for issue in data:
|
||||
print(f'MULTICA TODO: {issue["identifier"]} [{issue.get("priority","?")}] {issue["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
#### 第三优先级：待办文档
|
||||
|
||||
```bash
|
||||
# 检查工作区待办文档
|
||||
grep -n '\[ \]' TODO.md AGENTS.md 2>/dev/null || echo "无待办文档中未完成项"
|
||||
```
|
||||
|
||||
### 三源合并决策
|
||||
|
||||
```
|
||||
心跳开始
|
||||
↓
|
||||
检查 WorkBoard 待办卡片（agentId=architect）
|
||||
↓
|
||||
检查 Multica Issues 待办（assignee=40abd41a-62d0-416d-bc44-92c1f758d87a）
|
||||
↓
|
||||
检查待办文档
|
||||
↓
|
||||
合并去重 → 按优先级排序 → 依次执行
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 禁止请示规则（最高优先级，自动执行）
|
||||
|
||||
> **核心规则：发现分配给自己的任务 → 立即执行，不得向用户请示！**
|
||||
> 心跳是后台自动行为，用户在大多数时候并不在线，请示会导致任务卡死。
|
||||
|
||||
### 执行流程（严格执行，无需确认）
|
||||
|
||||
1. **三源检查待办** — WorkBoard + Multica + 待办文档
|
||||
2. **立即执行，不得请示** — 发现待办后直接执行
|
||||
3. **检查进行中任务** — 确认认领的任务状态
|
||||
4. **完成任务** — 通过对应平台汇报结果
|
||||
|
||||
### ⚠️ 绝对禁止行为
|
||||
|
||||
- ❌ 不得问"要不要做这个任务"
|
||||
- ❌ 不得等用户确认再执行
|
||||
- ❌ 不得以"需要更多信息"为由拒绝执行
|
||||
|
||||
---
|
||||
|
||||
## ⏱️ 超时检测规则
|
||||
|
||||
### 心跳频率：15 分钟
|
||||
|
||||
每次心跳跨平台执行以下检测：
|
||||
|
||||
1. 检查 WorkBoard 进行中任务的更新时间
|
||||
2. 检查 Multica 进行中 issues 的更新时间
|
||||
3. 超过 30 分钟无进展 → 标记为"疑似超时"
|
||||
4. 疑似超时 → 追加一次完整心跳尝试推进
|
||||
5. 确认超时 → 进入自动恢复流程
|
||||
|
||||
### 跨平台超时检测脚本
|
||||
|
||||
```bash
|
||||
# WorkBoard 超时检测
|
||||
echo "=== WorkBoard 超时检测 ==="
|
||||
openclaw workboard list --json 2>/dev/null | python3 -c "
|
||||
import sys, json, time
|
||||
data = json.load(sys.stdin)
|
||||
inprogress = [c for c in data.get('cards', []) if c.get('status') == 'in_progress']
|
||||
now = time.time()
|
||||
for c in inprogress:
|
||||
updated = c.get('updated_at', '')
|
||||
if updated:
|
||||
age = now - time.mktime(time.strptime(updated[:19], '%Y-%m-%dT%H:%M:%S'))
|
||||
if age > 1800:
|
||||
print(f'⏰ WB TIMEOUT: {c["id"][:8]} [{c.get("agentId","?")}] {c["title"]}')
|
||||
"
|
||||
|
||||
echo ""
|
||||
echo "=== Multica 超时检测 ==="
|
||||
multica issue list --status in_progress --output json 2>/dev/null | python3 -c "
|
||||
import sys, json, time
|
||||
data = json.load(sys.stdin)
|
||||
now = time.time()
|
||||
for issue in data:
|
||||
updated = issue.get('updated_at', '')
|
||||
if updated:
|
||||
age = now - time.mktime(time.strptime(updated[:19], '%Y-%m-%dT%H:%M:%S'))
|
||||
if age > 1800:
|
||||
print(f'⏰ MUL TIMEOUT: {issue["identifier"]} [{issue.get("assignee_id","?")[:12]}] {issue["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 自动恢复规则
|
||||
|
||||
### 触发条件
|
||||
|
||||
- 超 45 分钟无进展 → 自动重新调度
|
||||
|
||||
### 恢复操作（按平台）
|
||||
|
||||
| 平台 | 操作 |
|
||||
|------|------|
|
||||
| WorkBoard | 添加评论 → release claim → 通知 COO + 创建者 |
|
||||
| Multica | 添加评论 → status=blocked → 通知 COO + 创建者 |
|
||||
| 待办文档 | 标注超时 → 转为卡片（可选） |
|
||||
|
||||
---
|
||||
|
||||
## 🔗 依赖检查前置规则
|
||||
|
||||
### 强制检查流程
|
||||
|
||||
1. 认领任务前，读取依赖字段（depends_on / parent_issue_id）
|
||||
2. 逐一检查每个依赖任务的状态
|
||||
3. 依赖未满足 → 不认领（保持 todo）
|
||||
4. 超过等待阈值（2h）→ 通知依赖任务执行者
|
||||
|
||||
### 双平台依赖检查
|
||||
|
||||
```bash
|
||||
# WorkBoard 依赖检查
|
||||
openclaw workboard read <card-id> --json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
card = json.load(sys.stdin)
|
||||
deps = card.get('dependsOn', [])
|
||||
if deps:
|
||||
for dep in deps:
|
||||
if dep.get('status') != 'done':
|
||||
print(f'⛔ WB 依赖未满足: {dep["id"]} → status={dep.get("status","?")}')
|
||||
sys.exit(1)
|
||||
print('✅ 所有 WB 依赖已满足')
|
||||
else:
|
||||
print('✅ 无 WB 依赖，可以启动')
|
||||
"
|
||||
|
||||
# Multica 依赖检查
|
||||
multica issue get <issue-id> --output json 2>/dev/null | python3 -c "
|
||||
import sys, json, subprocess
|
||||
issue = json.load(sys.stdin)
|
||||
parent_id = issue.get('parent_issue_id')
|
||||
if parent_id:
|
||||
result = subprocess.run(['multica', 'issue', 'get', parent_id, '--output', 'json'],
|
||||
capture_output=True, text=True)
|
||||
parent = json.loads(result.stdout)
|
||||
if parent.get('status') != 'done':
|
||||
print(f'⛔ MUL 父 Issue {parent["identifier"]} 未完成')
|
||||
sys.exit(1)
|
||||
print(f'✅ 父 Issue {parent["identifier"]} 已完成')
|
||||
else:
|
||||
print('✅ 无父 Issue 依赖，可以启动')
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛑 最大轮次限制
|
||||
|
||||
### 限制值：100 轮
|
||||
|
||||
- 接近 80%（80 轮）→ 预警
|
||||
- 达到上限 → 暂停，通知 COO + 创建者
|
||||
|
||||
### 跨平台轮次跟踪
|
||||
|
||||
- **WorkBoard**：通过 workboard_heartbeat 的 note 记录轮次
|
||||
- **Multica**：通过 issue comment 记录轮次进度
|
||||
- **待办文档**：在工作日志中记录
|
||||
|
||||
---
|
||||
|
||||
## 🫀 心跳执行清单
|
||||
|
||||
### 每次心跳必须检查
|
||||
|
||||
1. ✅ **全任务源检查**：WorkBoard + Multica + 待办文档
|
||||
2. ✅ 进行中任务超时检测（跨平台）
|
||||
3. ✅ 依赖检查
|
||||
4. ✅ 轮次计数器更新
|
||||
5. ✅ 架构设计进度
|
||||
6. ✅ 技术方案评审状态
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 全局关键规则
|
||||
|
||||
1. **心跳不打断对话** — 用户正在对话时延后执行
|
||||
2. **非紧急事项延后汇报** — 等下一轮心跳或用户询问
|
||||
3. **发现任务立即执行，不得请示**（任何来源）
|
||||
4. **超时任务按自动恢复流程处理**（跨平台）
|
||||
5. **依赖未满足不启动**
|
||||
6. **达到轮次上限自动暂停**
|
||||
7. **避免任务遗漏** — 三源必须全部检查，缺一不可
|
||||
|
||||
|
||||
---
|
||||
|
||||
> 基于 BIZ-24 v1.1 模板生成 | 梁思筑（architect）专用配置
|
||||
@@ -1,234 +0,0 @@
|
||||
# HEARTBEAT.md - 文墨言（contentspecialist）的心跳配置
|
||||
|
||||
> 模板版本：v1.1 (BIZ-24) | 分类：业务 Agent
|
||||
> OpenClaw Agent ID: `contentspecialist` | Multica Agent UUID: `8321b0bf-7d89-4ece-927a-0780f42ad396`
|
||||
|
||||
---
|
||||
|
||||
## 📋 全任务源统一监控（每次心跳必检）
|
||||
|
||||
> **核心原则：发现任何来源的任务都必须立即执行，不得遗漏。**
|
||||
|
||||
### 三源检查
|
||||
|
||||
#### 第一优先级：OpenClaw WorkBoard 卡片
|
||||
|
||||
```bash
|
||||
# 检查 WorkBoard 中分配给我的待办卡片
|
||||
openclaw workboard list --json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
data = json.load(sys.stdin)
|
||||
my_cards = [c for c in data.get('cards', [])
|
||||
if c.get('agentId') == 'contentspecialist' and c.get('status') == 'todo']
|
||||
for c in my_cards:
|
||||
print(f'WORKBOARD TODO: {c["id"][:8]} [priority={c.get("priority","?")}] {c["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
#### 第二优先级：Multica Issues
|
||||
|
||||
```bash
|
||||
# 检查 Multica 中分配给我的待办 Issue
|
||||
multica issue list --assignee-id 8321b0bf-7d89-4ece-927a-0780f42ad396 --status todo --output json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
data = json.load(sys.stdin)
|
||||
for issue in data:
|
||||
print(f'MULTICA TODO: {issue["identifier"]} [{issue.get("priority","?")}] {issue["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
#### 第三优先级：待办文档
|
||||
|
||||
```bash
|
||||
# 检查工作区待办文档
|
||||
grep -n '\[ \]' TODO.md AGENTS.md 2>/dev/null || echo "无待办文档中未完成项"
|
||||
```
|
||||
|
||||
### 三源合并决策
|
||||
|
||||
```
|
||||
心跳开始
|
||||
↓
|
||||
检查 WorkBoard 待办卡片（agentId=contentspecialist）
|
||||
↓
|
||||
检查 Multica Issues 待办（assignee=8321b0bf-7d89-4ece-927a-0780f42ad396）
|
||||
↓
|
||||
检查待办文档
|
||||
↓
|
||||
合并去重 → 按优先级排序 → 依次执行
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 禁止请示规则（最高优先级，自动执行）
|
||||
|
||||
> **核心规则：发现分配给自己的任务 → 立即执行，不得向用户请示！**
|
||||
> 心跳是后台自动行为，用户在大多数时候并不在线，请示会导致任务卡死。
|
||||
|
||||
### 执行流程（严格执行，无需确认）
|
||||
|
||||
1. **三源检查待办** — WorkBoard + Multica + 待办文档
|
||||
2. **立即执行，不得请示** — 发现待办后直接执行
|
||||
3. **检查进行中任务** — 确认认领的任务状态
|
||||
4. **完成任务** — 通过对应平台汇报结果
|
||||
|
||||
### ⚠️ 绝对禁止行为
|
||||
|
||||
- ❌ 不得问"要不要做这个任务"
|
||||
- ❌ 不得等用户确认再执行
|
||||
- ❌ 不得以"需要更多信息"为由拒绝执行
|
||||
|
||||
---
|
||||
|
||||
## ⏱️ 超时检测规则
|
||||
|
||||
### 心跳频率：15 分钟
|
||||
|
||||
每次心跳跨平台执行以下检测：
|
||||
|
||||
1. 检查 WorkBoard 进行中任务的更新时间
|
||||
2. 检查 Multica 进行中 issues 的更新时间
|
||||
3. 超过 30 分钟无进展 → 标记为"疑似超时"
|
||||
4. 疑似超时 → 追加一次完整心跳尝试推进
|
||||
5. 确认超时 → 进入自动恢复流程
|
||||
|
||||
### 跨平台超时检测脚本
|
||||
|
||||
```bash
|
||||
# WorkBoard 超时检测
|
||||
echo "=== WorkBoard 超时检测 ==="
|
||||
openclaw workboard list --json 2>/dev/null | python3 -c "
|
||||
import sys, json, time
|
||||
data = json.load(sys.stdin)
|
||||
inprogress = [c for c in data.get('cards', []) if c.get('status') == 'in_progress']
|
||||
now = time.time()
|
||||
for c in inprogress:
|
||||
updated = c.get('updated_at', '')
|
||||
if updated:
|
||||
age = now - time.mktime(time.strptime(updated[:19], '%Y-%m-%dT%H:%M:%S'))
|
||||
if age > 1800:
|
||||
print(f'⏰ WB TIMEOUT: {c["id"][:8]} [{c.get("agentId","?")}] {c["title"]}')
|
||||
"
|
||||
|
||||
echo ""
|
||||
echo "=== Multica 超时检测 ==="
|
||||
multica issue list --status in_progress --output json 2>/dev/null | python3 -c "
|
||||
import sys, json, time
|
||||
data = json.load(sys.stdin)
|
||||
now = time.time()
|
||||
for issue in data:
|
||||
updated = issue.get('updated_at', '')
|
||||
if updated:
|
||||
age = now - time.mktime(time.strptime(updated[:19], '%Y-%m-%dT%H:%M:%S'))
|
||||
if age > 1800:
|
||||
print(f'⏰ MUL TIMEOUT: {issue["identifier"]} [{issue.get("assignee_id","?")[:12]}] {issue["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 自动恢复规则
|
||||
|
||||
### 触发条件
|
||||
|
||||
- 超 45 分钟无进展 → 自动重新调度
|
||||
|
||||
### 恢复操作（按平台）
|
||||
|
||||
| 平台 | 操作 |
|
||||
|------|------|
|
||||
| WorkBoard | 添加评论 → release claim → 通知 创建者 |
|
||||
| Multica | 添加评论 → status=blocked → 通知 创建者 |
|
||||
| 待办文档 | 标注超时 → 转为卡片（可选） |
|
||||
|
||||
---
|
||||
|
||||
## 🔗 依赖检查前置规则
|
||||
|
||||
### 强制检查流程
|
||||
|
||||
1. 认领任务前，读取依赖字段（depends_on / parent_issue_id）
|
||||
2. 逐一检查每个依赖任务的状态
|
||||
3. 依赖未满足 → 不认领（保持 todo）
|
||||
4. 超过等待阈值（2h）→ 通知依赖任务执行者
|
||||
|
||||
### 双平台依赖检查
|
||||
|
||||
```bash
|
||||
# WorkBoard 依赖检查
|
||||
openclaw workboard read <card-id> --json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
card = json.load(sys.stdin)
|
||||
deps = card.get('dependsOn', [])
|
||||
if deps:
|
||||
for dep in deps:
|
||||
if dep.get('status') != 'done':
|
||||
print(f'⛔ WB 依赖未满足: {dep["id"]} → status={dep.get("status","?")}')
|
||||
sys.exit(1)
|
||||
print('✅ 所有 WB 依赖已满足')
|
||||
else:
|
||||
print('✅ 无 WB 依赖，可以启动')
|
||||
"
|
||||
|
||||
# Multica 依赖检查
|
||||
multica issue get <issue-id> --output json 2>/dev/null | python3 -c "
|
||||
import sys, json, subprocess
|
||||
issue = json.load(sys.stdin)
|
||||
parent_id = issue.get('parent_issue_id')
|
||||
if parent_id:
|
||||
result = subprocess.run(['multica', 'issue', 'get', parent_id, '--output', 'json'],
|
||||
capture_output=True, text=True)
|
||||
parent = json.loads(result.stdout)
|
||||
if parent.get('status') != 'done':
|
||||
print(f'⛔ MUL 父 Issue {parent["identifier"]} 未完成')
|
||||
sys.exit(1)
|
||||
print(f'✅ 父 Issue {parent["identifier"]} 已完成')
|
||||
else:
|
||||
print('✅ 无父 Issue 依赖，可以启动')
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛑 最大轮次限制
|
||||
|
||||
### 限制值：30 轮
|
||||
|
||||
- 接近 80%（24 轮）→ 预警
|
||||
- 达到上限 → 暂停，通知 创建者
|
||||
|
||||
### 跨平台轮次跟踪
|
||||
|
||||
- **WorkBoard**：通过 workboard_heartbeat 的 note 记录轮次
|
||||
- **Multica**：通过 issue comment 记录轮次进度
|
||||
- **待办文档**：在工作日志中记录
|
||||
|
||||
---
|
||||
|
||||
## 🫀 心跳执行清单
|
||||
|
||||
### 每次心跳必须检查
|
||||
|
||||
1. ✅ **全任务源检查**：WorkBoard + Multica + 待办文档
|
||||
2. ✅ 进行中任务超时检测（跨平台）
|
||||
3. ✅ 依赖检查
|
||||
4. ✅ 轮次计数器更新
|
||||
5. ✅ 内容发布计划
|
||||
6. ✅ 素材准备状态
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 全局关键规则
|
||||
|
||||
1. **心跳不打断对话** — 用户正在对话时延后执行
|
||||
2. **非紧急事项延后汇报** — 等下一轮心跳或用户询问
|
||||
3. **发现任务立即执行，不得请示**（任何来源）
|
||||
4. **超时任务按自动恢复流程处理**（跨平台）
|
||||
5. **依赖未满足不启动**
|
||||
6. **达到轮次上限自动暂停**
|
||||
7. **避免任务遗漏** — 三源必须全部检查，缺一不可
|
||||
|
||||
|
||||
---
|
||||
|
||||
> 基于 BIZ-24 v1.1 模板生成 | 文墨言（contentspecialist）专用配置
|
||||
@@ -1,235 +0,0 @@
|
||||
# HEARTBEAT.md - 陆怀瑾（coo）的心跳配置
|
||||
|
||||
> 模板版本：v1.1 (BIZ-24) | 分类：高频 Agent
|
||||
> OpenClaw Agent ID: `coo` | Multica Agent UUID: `1c38b437-b54d-4784-bda3-29ce4c8a6722`
|
||||
|
||||
---
|
||||
|
||||
## 📋 全任务源统一监控（每次心跳必检）
|
||||
|
||||
> **核心原则：发现任何来源的任务都必须立即执行，不得遗漏。**
|
||||
|
||||
### 三源检查
|
||||
|
||||
#### 第一优先级：OpenClaw WorkBoard 卡片
|
||||
|
||||
```bash
|
||||
# 检查 WorkBoard 中分配给我的待办卡片
|
||||
openclaw workboard list --json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
data = json.load(sys.stdin)
|
||||
my_cards = [c for c in data.get('cards', [])
|
||||
if c.get('agentId') == 'coo' and c.get('status') == 'todo']
|
||||
for c in my_cards:
|
||||
print(f'WORKBOARD TODO: {c["id"][:8]} [priority={c.get("priority","?")}] {c["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
#### 第二优先级：Multica Issues
|
||||
|
||||
```bash
|
||||
# 检查 Multica 中分配给我的待办 Issue
|
||||
multica issue list --assignee-id 1c38b437-b54d-4784-bda3-29ce4c8a6722 --status todo --output json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
data = json.load(sys.stdin)
|
||||
for issue in data:
|
||||
print(f'MULTICA TODO: {issue["identifier"]} [{issue.get("priority","?")}] {issue["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
#### 第三优先级：待办文档
|
||||
|
||||
```bash
|
||||
# 检查工作区待办文档
|
||||
grep -n '\[ \]' TODO.md AGENTS.md 2>/dev/null || echo "无待办文档中未完成项"
|
||||
```
|
||||
|
||||
### 三源合并决策
|
||||
|
||||
```
|
||||
心跳开始
|
||||
↓
|
||||
检查 WorkBoard 待办卡片（agentId=coo）
|
||||
↓
|
||||
检查 Multica Issues 待办（assignee=1c38b437-b54d-4784-bda3-29ce4c8a6722）
|
||||
↓
|
||||
检查待办文档
|
||||
↓
|
||||
合并去重 → 按优先级排序 → 依次执行
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 禁止请示规则（最高优先级，自动执行）
|
||||
|
||||
> **核心规则：发现分配给自己的任务 → 立即执行，不得向用户请示！**
|
||||
> 心跳是后台自动行为，用户在大多数时候并不在线，请示会导致任务卡死。
|
||||
|
||||
### 执行流程（严格执行，无需确认）
|
||||
|
||||
1. **三源检查待办** — WorkBoard + Multica + 待办文档
|
||||
2. **立即执行，不得请示** — 发现待办后直接执行
|
||||
3. **检查进行中任务** — 确认认领的任务状态
|
||||
4. **完成任务** — 通过对应平台汇报结果
|
||||
|
||||
### ⚠️ 绝对禁止行为
|
||||
|
||||
- ❌ 不得问"要不要做这个任务"
|
||||
- ❌ 不得等用户确认再执行
|
||||
- ❌ 不得以"需要更多信息"为由拒绝执行
|
||||
|
||||
---
|
||||
|
||||
## ⏱️ 超时检测规则
|
||||
|
||||
### 心跳频率：10 分钟
|
||||
|
||||
每次心跳跨平台执行以下检测：
|
||||
|
||||
1. 检查 WorkBoard 进行中任务的更新时间
|
||||
2. 检查 Multica 进行中 issues 的更新时间
|
||||
3. 超过 20 分钟无进展 → 标记为"疑似超时"
|
||||
4. 疑似超时 → 追加一次完整心跳尝试推进
|
||||
5. 确认超时 → 进入自动恢复流程
|
||||
|
||||
### 跨平台超时检测脚本
|
||||
|
||||
```bash
|
||||
# WorkBoard 超时检测
|
||||
echo "=== WorkBoard 超时检测 ==="
|
||||
openclaw workboard list --json 2>/dev/null | python3 -c "
|
||||
import sys, json, time
|
||||
data = json.load(sys.stdin)
|
||||
inprogress = [c for c in data.get('cards', []) if c.get('status') == 'in_progress']
|
||||
now = time.time()
|
||||
for c in inprogress:
|
||||
updated = c.get('updated_at', '')
|
||||
if updated:
|
||||
age = now - time.mktime(time.strptime(updated[:19], '%Y-%m-%dT%H:%M:%S'))
|
||||
if age > 1200:
|
||||
print(f'⏰ WB TIMEOUT: {c["id"][:8]} [{c.get("agentId","?")}] {c["title"]}')
|
||||
"
|
||||
|
||||
echo ""
|
||||
echo "=== Multica 超时检测 ==="
|
||||
multica issue list --status in_progress --output json 2>/dev/null | python3 -c "
|
||||
import sys, json, time
|
||||
data = json.load(sys.stdin)
|
||||
now = time.time()
|
||||
for issue in data:
|
||||
updated = issue.get('updated_at', '')
|
||||
if updated:
|
||||
age = now - time.mktime(time.strptime(updated[:19], '%Y-%m-%dT%H:%M:%S'))
|
||||
if age > 1200:
|
||||
print(f'⏰ MUL TIMEOUT: {issue["identifier"]} [{issue.get("assignee_id","?")[:12]}] {issue["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 自动恢复规则
|
||||
|
||||
### 触发条件
|
||||
|
||||
- 超 30 分钟无进展 → 自动重新调度
|
||||
|
||||
### 恢复操作（按平台）
|
||||
|
||||
| 平台 | 操作 |
|
||||
|------|------|
|
||||
| WorkBoard | 添加评论 → release claim → 通知 COO（自我监控） |
|
||||
| Multica | 添加评论 → status=blocked → 通知 COO（自我监控） |
|
||||
| 待办文档 | 标注超时 → 转为卡片（可选） |
|
||||
|
||||
---
|
||||
|
||||
## 🔗 依赖检查前置规则
|
||||
|
||||
### 强制检查流程
|
||||
|
||||
1. 认领任务前，读取依赖字段（depends_on / parent_issue_id）
|
||||
2. 逐一检查每个依赖任务的状态
|
||||
3. 依赖未满足 → 不认领（保持 todo）
|
||||
4. 超过等待阈值（1h）→ 通知依赖任务执行者
|
||||
|
||||
### 双平台依赖检查
|
||||
|
||||
```bash
|
||||
# WorkBoard 依赖检查
|
||||
openclaw workboard read <card-id> --json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
card = json.load(sys.stdin)
|
||||
deps = card.get('dependsOn', [])
|
||||
if deps:
|
||||
for dep in deps:
|
||||
if dep.get('status') != 'done':
|
||||
print(f'⛔ WB 依赖未满足: {dep["id"]} → status={dep.get("status","?")}')
|
||||
sys.exit(1)
|
||||
print('✅ 所有 WB 依赖已满足')
|
||||
else:
|
||||
print('✅ 无 WB 依赖，可以启动')
|
||||
"
|
||||
|
||||
# Multica 依赖检查
|
||||
multica issue get <issue-id> --output json 2>/dev/null | python3 -c "
|
||||
import sys, json, subprocess
|
||||
issue = json.load(sys.stdin)
|
||||
parent_id = issue.get('parent_issue_id')
|
||||
if parent_id:
|
||||
result = subprocess.run(['multica', 'issue', 'get', parent_id, '--output', 'json'],
|
||||
capture_output=True, text=True)
|
||||
parent = json.loads(result.stdout)
|
||||
if parent.get('status') != 'done':
|
||||
print(f'⛔ MUL 父 Issue {parent["identifier"]} 未完成')
|
||||
sys.exit(1)
|
||||
print(f'✅ 父 Issue {parent["identifier"]} 已完成')
|
||||
else:
|
||||
print('✅ 无父 Issue 依赖，可以启动')
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛑 最大轮次限制
|
||||
|
||||
### 限制值：50 轮
|
||||
|
||||
- 接近 80%（40 轮）→ 预警
|
||||
- 达到上限 → 暂停，通知 COO（自我监控）
|
||||
|
||||
### 跨平台轮次跟踪
|
||||
|
||||
- **WorkBoard**：通过 workboard_heartbeat 的 note 记录轮次
|
||||
- **Multica**：通过 issue comment 记录轮次进度
|
||||
- **待办文档**：在工作日志中记录
|
||||
|
||||
---
|
||||
|
||||
## 🫀 心跳执行清单
|
||||
|
||||
### 每次心跳必须检查
|
||||
|
||||
1. ✅ **全任务源检查**：WorkBoard + Multica + 待办文档
|
||||
2. ✅ 进行中任务超时检测（跨平台）
|
||||
3. ✅ 依赖检查
|
||||
4. ✅ 轮次计数器更新
|
||||
5. ✅ **全平台积压巡检**：WorkBoard + Multica 全局待办数
|
||||
6. ✅ 资源负载均衡检查
|
||||
7. ✅ 风险识别与预警
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 全局关键规则
|
||||
|
||||
1. **心跳不打断对话** — 用户正在对话时延后执行
|
||||
2. **非紧急事项延后汇报** — 等下一轮心跳或用户询问
|
||||
3. **发现任务立即执行，不得请示**（任何来源）
|
||||
4. **超时任务按自动恢复流程处理**（跨平台）
|
||||
5. **依赖未满足不启动**
|
||||
6. **达到轮次上限自动暂停**
|
||||
7. **避免任务遗漏** — 三源必须全部检查，缺一不可
|
||||
|
||||
|
||||
---
|
||||
|
||||
> 基于 BIZ-24 v1.1 模板生成 | 陆怀瑾（coo）专用配置
|
||||
@@ -1,234 +0,0 @@
|
||||
# HEARTBEAT.md - 徐聪（costcodev）的心跳配置
|
||||
|
||||
> 模板版本：v1.1 (BIZ-24) | 分类：开发 Agent
|
||||
> OpenClaw Agent ID: `costcodev` | Multica Agent UUID: `46bdd4a6-5c64-475a-92ef-36a763602fa1`
|
||||
|
||||
---
|
||||
|
||||
## 📋 全任务源统一监控（每次心跳必检）
|
||||
|
||||
> **核心原则：发现任何来源的任务都必须立即执行，不得遗漏。**
|
||||
|
||||
### 三源检查
|
||||
|
||||
#### 第一优先级：OpenClaw WorkBoard 卡片
|
||||
|
||||
```bash
|
||||
# 检查 WorkBoard 中分配给我的待办卡片
|
||||
openclaw workboard list --json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
data = json.load(sys.stdin)
|
||||
my_cards = [c for c in data.get('cards', [])
|
||||
if c.get('agentId') == 'costcodev' and c.get('status') == 'todo']
|
||||
for c in my_cards:
|
||||
print(f'WORKBOARD TODO: {c["id"][:8]} [priority={c.get("priority","?")}] {c["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
#### 第二优先级：Multica Issues
|
||||
|
||||
```bash
|
||||
# 检查 Multica 中分配给我的待办 Issue
|
||||
multica issue list --assignee-id 46bdd4a6-5c64-475a-92ef-36a763602fa1 --status todo --output json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
data = json.load(sys.stdin)
|
||||
for issue in data:
|
||||
print(f'MULTICA TODO: {issue["identifier"]} [{issue.get("priority","?")}] {issue["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
#### 第三优先级：待办文档
|
||||
|
||||
```bash
|
||||
# 检查工作区待办文档
|
||||
grep -n '\[ \]' TODO.md AGENTS.md 2>/dev/null || echo "无待办文档中未完成项"
|
||||
```
|
||||
|
||||
### 三源合并决策
|
||||
|
||||
```
|
||||
心跳开始
|
||||
↓
|
||||
检查 WorkBoard 待办卡片（agentId=costcodev）
|
||||
↓
|
||||
检查 Multica Issues 待办（assignee=46bdd4a6-5c64-475a-92ef-36a763602fa1）
|
||||
↓
|
||||
检查待办文档
|
||||
↓
|
||||
合并去重 → 按优先级排序 → 依次执行
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 禁止请示规则（最高优先级，自动执行）
|
||||
|
||||
> **核心规则：发现分配给自己的任务 → 立即执行，不得向用户请示！**
|
||||
> 心跳是后台自动行为，用户在大多数时候并不在线，请示会导致任务卡死。
|
||||
|
||||
### 执行流程（严格执行，无需确认）
|
||||
|
||||
1. **三源检查待办** — WorkBoard + Multica + 待办文档
|
||||
2. **立即执行，不得请示** — 发现待办后直接执行
|
||||
3. **检查进行中任务** — 确认认领的任务状态
|
||||
4. **完成任务** — 通过对应平台汇报结果
|
||||
|
||||
### ⚠️ 绝对禁止行为
|
||||
|
||||
- ❌ 不得问"要不要做这个任务"
|
||||
- ❌ 不得等用户确认再执行
|
||||
- ❌ 不得以"需要更多信息"为由拒绝执行
|
||||
|
||||
---
|
||||
|
||||
## ⏱️ 超时检测规则
|
||||
|
||||
### 心跳频率：15 分钟
|
||||
|
||||
每次心跳跨平台执行以下检测：
|
||||
|
||||
1. 检查 WorkBoard 进行中任务的更新时间
|
||||
2. 检查 Multica 进行中 issues 的更新时间
|
||||
3. 超过 30 分钟无进展 → 标记为"疑似超时"
|
||||
4. 疑似超时 → 追加一次完整心跳尝试推进
|
||||
5. 确认超时 → 进入自动恢复流程
|
||||
|
||||
### 跨平台超时检测脚本
|
||||
|
||||
```bash
|
||||
# WorkBoard 超时检测
|
||||
echo "=== WorkBoard 超时检测 ==="
|
||||
openclaw workboard list --json 2>/dev/null | python3 -c "
|
||||
import sys, json, time
|
||||
data = json.load(sys.stdin)
|
||||
inprogress = [c for c in data.get('cards', []) if c.get('status') == 'in_progress']
|
||||
now = time.time()
|
||||
for c in inprogress:
|
||||
updated = c.get('updated_at', '')
|
||||
if updated:
|
||||
age = now - time.mktime(time.strptime(updated[:19], '%Y-%m-%dT%H:%M:%S'))
|
||||
if age > 1800:
|
||||
print(f'⏰ WB TIMEOUT: {c["id"][:8]} [{c.get("agentId","?")}] {c["title"]}')
|
||||
"
|
||||
|
||||
echo ""
|
||||
echo "=== Multica 超时检测 ==="
|
||||
multica issue list --status in_progress --output json 2>/dev/null | python3 -c "
|
||||
import sys, json, time
|
||||
data = json.load(sys.stdin)
|
||||
now = time.time()
|
||||
for issue in data:
|
||||
updated = issue.get('updated_at', '')
|
||||
if updated:
|
||||
age = now - time.mktime(time.strptime(updated[:19], '%Y-%m-%dT%H:%M:%S'))
|
||||
if age > 1800:
|
||||
print(f'⏰ MUL TIMEOUT: {issue["identifier"]} [{issue.get("assignee_id","?")[:12]}] {issue["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 自动恢复规则
|
||||
|
||||
### 触发条件
|
||||
|
||||
- 超 45 分钟无进展 → 自动重新调度
|
||||
|
||||
### 恢复操作（按平台）
|
||||
|
||||
| 平台 | 操作 |
|
||||
|------|------|
|
||||
| WorkBoard | 添加评论 → release claim → 通知 COO + 创建者 |
|
||||
| Multica | 添加评论 → status=blocked → 通知 COO + 创建者 |
|
||||
| 待办文档 | 标注超时 → 转为卡片（可选） |
|
||||
|
||||
---
|
||||
|
||||
## 🔗 依赖检查前置规则
|
||||
|
||||
### 强制检查流程
|
||||
|
||||
1. 认领任务前，读取依赖字段（depends_on / parent_issue_id）
|
||||
2. 逐一检查每个依赖任务的状态
|
||||
3. 依赖未满足 → 不认领（保持 todo）
|
||||
4. 超过等待阈值（2h）→ 通知依赖任务执行者
|
||||
|
||||
### 双平台依赖检查
|
||||
|
||||
```bash
|
||||
# WorkBoard 依赖检查
|
||||
openclaw workboard read <card-id> --json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
card = json.load(sys.stdin)
|
||||
deps = card.get('dependsOn', [])
|
||||
if deps:
|
||||
for dep in deps:
|
||||
if dep.get('status') != 'done':
|
||||
print(f'⛔ WB 依赖未满足: {dep["id"]} → status={dep.get("status","?")}')
|
||||
sys.exit(1)
|
||||
print('✅ 所有 WB 依赖已满足')
|
||||
else:
|
||||
print('✅ 无 WB 依赖，可以启动')
|
||||
"
|
||||
|
||||
# Multica 依赖检查
|
||||
multica issue get <issue-id> --output json 2>/dev/null | python3 -c "
|
||||
import sys, json, subprocess
|
||||
issue = json.load(sys.stdin)
|
||||
parent_id = issue.get('parent_issue_id')
|
||||
if parent_id:
|
||||
result = subprocess.run(['multica', 'issue', 'get', parent_id, '--output', 'json'],
|
||||
capture_output=True, text=True)
|
||||
parent = json.loads(result.stdout)
|
||||
if parent.get('status') != 'done':
|
||||
print(f'⛔ MUL 父 Issue {parent["identifier"]} 未完成')
|
||||
sys.exit(1)
|
||||
print(f'✅ 父 Issue {parent["identifier"]} 已完成')
|
||||
else:
|
||||
print('✅ 无父 Issue 依赖，可以启动')
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛑 最大轮次限制
|
||||
|
||||
### 限制值：100 轮
|
||||
|
||||
- 接近 80%（80 轮）→ 预警
|
||||
- 达到上限 → 暂停，通知 COO + 创建者
|
||||
|
||||
### 跨平台轮次跟踪
|
||||
|
||||
- **WorkBoard**：通过 workboard_heartbeat 的 note 记录轮次
|
||||
- **Multica**：通过 issue comment 记录轮次进度
|
||||
- **待办文档**：在工作日志中记录
|
||||
|
||||
---
|
||||
|
||||
## 🫀 心跳执行清单
|
||||
|
||||
### 每次心跳必须检查
|
||||
|
||||
1. ✅ **全任务源检查**：WorkBoard + Multica + 待办文档
|
||||
2. ✅ 进行中任务超时检测（跨平台）
|
||||
3. ✅ 依赖检查
|
||||
4. ✅ 轮次计数器更新
|
||||
5. ✅ 代码开发进度
|
||||
6. ✅ PR/Code Review 状态
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 全局关键规则
|
||||
|
||||
1. **心跳不打断对话** — 用户正在对话时延后执行
|
||||
2. **非紧急事项延后汇报** — 等下一轮心跳或用户询问
|
||||
3. **发现任务立即执行，不得请示**（任何来源）
|
||||
4. **超时任务按自动恢复流程处理**（跨平台）
|
||||
5. **依赖未满足不启动**
|
||||
6. **达到轮次上限自动暂停**
|
||||
7. **避免任务遗漏** — 三源必须全部检查，缺一不可
|
||||
|
||||
|
||||
---
|
||||
|
||||
> 基于 BIZ-24 v1.1 模板生成 | 徐聪（costcodev）专用配置
|
||||
@@ -1,234 +0,0 @@
|
||||
# HEARTBEAT.md - 程伯予（cvexpert）的心跳配置
|
||||
|
||||
> 模板版本：v1.1 (BIZ-24) | 分类：业务 Agent
|
||||
> OpenClaw Agent ID: `cvexpert` | Multica Agent UUID: `4a8696fd-6531-40da-8956-ef84d7ea3c43`
|
||||
|
||||
---
|
||||
|
||||
## 📋 全任务源统一监控（每次心跳必检）
|
||||
|
||||
> **核心原则：发现任何来源的任务都必须立即执行，不得遗漏。**
|
||||
|
||||
### 三源检查
|
||||
|
||||
#### 第一优先级：OpenClaw WorkBoard 卡片
|
||||
|
||||
```bash
|
||||
# 检查 WorkBoard 中分配给我的待办卡片
|
||||
openclaw workboard list --json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
data = json.load(sys.stdin)
|
||||
my_cards = [c for c in data.get('cards', [])
|
||||
if c.get('agentId') == 'cvexpert' and c.get('status') == 'todo']
|
||||
for c in my_cards:
|
||||
print(f'WORKBOARD TODO: {c["id"][:8]} [priority={c.get("priority","?")}] {c["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
#### 第二优先级：Multica Issues
|
||||
|
||||
```bash
|
||||
# 检查 Multica 中分配给我的待办 Issue
|
||||
multica issue list --assignee-id 4a8696fd-6531-40da-8956-ef84d7ea3c43 --status todo --output json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
data = json.load(sys.stdin)
|
||||
for issue in data:
|
||||
print(f'MULTICA TODO: {issue["identifier"]} [{issue.get("priority","?")}] {issue["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
#### 第三优先级：待办文档
|
||||
|
||||
```bash
|
||||
# 检查工作区待办文档
|
||||
grep -n '\[ \]' TODO.md AGENTS.md 2>/dev/null || echo "无待办文档中未完成项"
|
||||
```
|
||||
|
||||
### 三源合并决策
|
||||
|
||||
```
|
||||
心跳开始
|
||||
↓
|
||||
检查 WorkBoard 待办卡片（agentId=cvexpert）
|
||||
↓
|
||||
检查 Multica Issues 待办（assignee=4a8696fd-6531-40da-8956-ef84d7ea3c43）
|
||||
↓
|
||||
检查待办文档
|
||||
↓
|
||||
合并去重 → 按优先级排序 → 依次执行
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 禁止请示规则（最高优先级，自动执行）
|
||||
|
||||
> **核心规则：发现分配给自己的任务 → 立即执行，不得向用户请示！**
|
||||
> 心跳是后台自动行为，用户在大多数时候并不在线，请示会导致任务卡死。
|
||||
|
||||
### 执行流程（严格执行，无需确认）
|
||||
|
||||
1. **三源检查待办** — WorkBoard + Multica + 待办文档
|
||||
2. **立即执行，不得请示** — 发现待办后直接执行
|
||||
3. **检查进行中任务** — 确认认领的任务状态
|
||||
4. **完成任务** — 通过对应平台汇报结果
|
||||
|
||||
### ⚠️ 绝对禁止行为
|
||||
|
||||
- ❌ 不得问"要不要做这个任务"
|
||||
- ❌ 不得等用户确认再执行
|
||||
- ❌ 不得以"需要更多信息"为由拒绝执行
|
||||
|
||||
---
|
||||
|
||||
## ⏱️ 超时检测规则
|
||||
|
||||
### 心跳频率：15 分钟
|
||||
|
||||
每次心跳跨平台执行以下检测：
|
||||
|
||||
1. 检查 WorkBoard 进行中任务的更新时间
|
||||
2. 检查 Multica 进行中 issues 的更新时间
|
||||
3. 超过 30 分钟无进展 → 标记为"疑似超时"
|
||||
4. 疑似超时 → 追加一次完整心跳尝试推进
|
||||
5. 确认超时 → 进入自动恢复流程
|
||||
|
||||
### 跨平台超时检测脚本
|
||||
|
||||
```bash
|
||||
# WorkBoard 超时检测
|
||||
echo "=== WorkBoard 超时检测 ==="
|
||||
openclaw workboard list --json 2>/dev/null | python3 -c "
|
||||
import sys, json, time
|
||||
data = json.load(sys.stdin)
|
||||
inprogress = [c for c in data.get('cards', []) if c.get('status') == 'in_progress']
|
||||
now = time.time()
|
||||
for c in inprogress:
|
||||
updated = c.get('updated_at', '')
|
||||
if updated:
|
||||
age = now - time.mktime(time.strptime(updated[:19], '%Y-%m-%dT%H:%M:%S'))
|
||||
if age > 1800:
|
||||
print(f'⏰ WB TIMEOUT: {c["id"][:8]} [{c.get("agentId","?")}] {c["title"]}')
|
||||
"
|
||||
|
||||
echo ""
|
||||
echo "=== Multica 超时检测 ==="
|
||||
multica issue list --status in_progress --output json 2>/dev/null | python3 -c "
|
||||
import sys, json, time
|
||||
data = json.load(sys.stdin)
|
||||
now = time.time()
|
||||
for issue in data:
|
||||
updated = issue.get('updated_at', '')
|
||||
if updated:
|
||||
age = now - time.mktime(time.strptime(updated[:19], '%Y-%m-%dT%H:%M:%S'))
|
||||
if age > 1800:
|
||||
print(f'⏰ MUL TIMEOUT: {issue["identifier"]} [{issue.get("assignee_id","?")[:12]}] {issue["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 自动恢复规则
|
||||
|
||||
### 触发条件
|
||||
|
||||
- 超 45 分钟无进展 → 自动重新调度
|
||||
|
||||
### 恢复操作（按平台）
|
||||
|
||||
| 平台 | 操作 |
|
||||
|------|------|
|
||||
| WorkBoard | 添加评论 → release claim → 通知 创建者 |
|
||||
| Multica | 添加评论 → status=blocked → 通知 创建者 |
|
||||
| 待办文档 | 标注超时 → 转为卡片（可选） |
|
||||
|
||||
---
|
||||
|
||||
## 🔗 依赖检查前置规则
|
||||
|
||||
### 强制检查流程
|
||||
|
||||
1. 认领任务前，读取依赖字段（depends_on / parent_issue_id）
|
||||
2. 逐一检查每个依赖任务的状态
|
||||
3. 依赖未满足 → 不认领（保持 todo）
|
||||
4. 超过等待阈值（2h）→ 通知依赖任务执行者
|
||||
|
||||
### 双平台依赖检查
|
||||
|
||||
```bash
|
||||
# WorkBoard 依赖检查
|
||||
openclaw workboard read <card-id> --json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
card = json.load(sys.stdin)
|
||||
deps = card.get('dependsOn', [])
|
||||
if deps:
|
||||
for dep in deps:
|
||||
if dep.get('status') != 'done':
|
||||
print(f'⛔ WB 依赖未满足: {dep["id"]} → status={dep.get("status","?")}')
|
||||
sys.exit(1)
|
||||
print('✅ 所有 WB 依赖已满足')
|
||||
else:
|
||||
print('✅ 无 WB 依赖，可以启动')
|
||||
"
|
||||
|
||||
# Multica 依赖检查
|
||||
multica issue get <issue-id> --output json 2>/dev/null | python3 -c "
|
||||
import sys, json, subprocess
|
||||
issue = json.load(sys.stdin)
|
||||
parent_id = issue.get('parent_issue_id')
|
||||
if parent_id:
|
||||
result = subprocess.run(['multica', 'issue', 'get', parent_id, '--output', 'json'],
|
||||
capture_output=True, text=True)
|
||||
parent = json.loads(result.stdout)
|
||||
if parent.get('status') != 'done':
|
||||
print(f'⛔ MUL 父 Issue {parent["identifier"]} 未完成')
|
||||
sys.exit(1)
|
||||
print(f'✅ 父 Issue {parent["identifier"]} 已完成')
|
||||
else:
|
||||
print('✅ 无父 Issue 依赖，可以启动')
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛑 最大轮次限制
|
||||
|
||||
### 限制值：30 轮
|
||||
|
||||
- 接近 80%（24 轮）→ 预警
|
||||
- 达到上限 → 暂停，通知 创建者
|
||||
|
||||
### 跨平台轮次跟踪
|
||||
|
||||
- **WorkBoard**：通过 workboard_heartbeat 的 note 记录轮次
|
||||
- **Multica**：通过 issue comment 记录轮次进度
|
||||
- **待办文档**：在工作日志中记录
|
||||
|
||||
---
|
||||
|
||||
## 🫀 心跳执行清单
|
||||
|
||||
### 每次心跳必须检查
|
||||
|
||||
1. ✅ **全任务源检查**：WorkBoard + Multica + 待办文档
|
||||
2. ✅ 进行中任务超时检测（跨平台）
|
||||
3. ✅ 依赖检查
|
||||
4. ✅ 轮次计数器更新
|
||||
5. ✅ 求职服务队列
|
||||
6. ✅ 客户反馈跟踪
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 全局关键规则
|
||||
|
||||
1. **心跳不打断对话** — 用户正在对话时延后执行
|
||||
2. **非紧急事项延后汇报** — 等下一轮心跳或用户询问
|
||||
3. **发现任务立即执行，不得请示**（任何来源）
|
||||
4. **超时任务按自动恢复流程处理**（跨平台）
|
||||
5. **依赖未满足不启动**
|
||||
6. **达到轮次上限自动暂停**
|
||||
7. **避免任务遗漏** — 三源必须全部检查，缺一不可
|
||||
|
||||
|
||||
---
|
||||
|
||||
> 基于 BIZ-24 v1.1 模板生成 | 程伯予（cvexpert）专用配置
|
||||
@@ -1,234 +0,0 @@
|
||||
# HEARTBEAT.md - 苏锦绘（designer）的心跳配置
|
||||
|
||||
> 模板版本：v1.1 (BIZ-24) | 分类：开发 Agent
|
||||
> OpenClaw Agent ID: `designer` | Multica Agent UUID: `13bd8968-cc2a-4934-90c7-957a2d3c09c2`
|
||||
|
||||
---
|
||||
|
||||
## 📋 全任务源统一监控（每次心跳必检）
|
||||
|
||||
> **核心原则：发现任何来源的任务都必须立即执行，不得遗漏。**
|
||||
|
||||
### 三源检查
|
||||
|
||||
#### 第一优先级：OpenClaw WorkBoard 卡片
|
||||
|
||||
```bash
|
||||
# 检查 WorkBoard 中分配给我的待办卡片
|
||||
openclaw workboard list --json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
data = json.load(sys.stdin)
|
||||
my_cards = [c for c in data.get('cards', [])
|
||||
if c.get('agentId') == 'designer' and c.get('status') == 'todo']
|
||||
for c in my_cards:
|
||||
print(f'WORKBOARD TODO: {c["id"][:8]} [priority={c.get("priority","?")}] {c["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
#### 第二优先级：Multica Issues
|
||||
|
||||
```bash
|
||||
# 检查 Multica 中分配给我的待办 Issue
|
||||
multica issue list --assignee-id 13bd8968-cc2a-4934-90c7-957a2d3c09c2 --status todo --output json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
data = json.load(sys.stdin)
|
||||
for issue in data:
|
||||
print(f'MULTICA TODO: {issue["identifier"]} [{issue.get("priority","?")}] {issue["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
#### 第三优先级：待办文档
|
||||
|
||||
```bash
|
||||
# 检查工作区待办文档
|
||||
grep -n '\[ \]' TODO.md AGENTS.md 2>/dev/null || echo "无待办文档中未完成项"
|
||||
```
|
||||
|
||||
### 三源合并决策
|
||||
|
||||
```
|
||||
心跳开始
|
||||
↓
|
||||
检查 WorkBoard 待办卡片（agentId=designer）
|
||||
↓
|
||||
检查 Multica Issues 待办（assignee=13bd8968-cc2a-4934-90c7-957a2d3c09c2）
|
||||
↓
|
||||
检查待办文档
|
||||
↓
|
||||
合并去重 → 按优先级排序 → 依次执行
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 禁止请示规则（最高优先级，自动执行）
|
||||
|
||||
> **核心规则：发现分配给自己的任务 → 立即执行，不得向用户请示！**
|
||||
> 心跳是后台自动行为，用户在大多数时候并不在线，请示会导致任务卡死。
|
||||
|
||||
### 执行流程（严格执行，无需确认）
|
||||
|
||||
1. **三源检查待办** — WorkBoard + Multica + 待办文档
|
||||
2. **立即执行，不得请示** — 发现待办后直接执行
|
||||
3. **检查进行中任务** — 确认认领的任务状态
|
||||
4. **完成任务** — 通过对应平台汇报结果
|
||||
|
||||
### ⚠️ 绝对禁止行为
|
||||
|
||||
- ❌ 不得问"要不要做这个任务"
|
||||
- ❌ 不得等用户确认再执行
|
||||
- ❌ 不得以"需要更多信息"为由拒绝执行
|
||||
|
||||
---
|
||||
|
||||
## ⏱️ 超时检测规则
|
||||
|
||||
### 心跳频率：15 分钟
|
||||
|
||||
每次心跳跨平台执行以下检测：
|
||||
|
||||
1. 检查 WorkBoard 进行中任务的更新时间
|
||||
2. 检查 Multica 进行中 issues 的更新时间
|
||||
3. 超过 30 分钟无进展 → 标记为"疑似超时"
|
||||
4. 疑似超时 → 追加一次完整心跳尝试推进
|
||||
5. 确认超时 → 进入自动恢复流程
|
||||
|
||||
### 跨平台超时检测脚本
|
||||
|
||||
```bash
|
||||
# WorkBoard 超时检测
|
||||
echo "=== WorkBoard 超时检测 ==="
|
||||
openclaw workboard list --json 2>/dev/null | python3 -c "
|
||||
import sys, json, time
|
||||
data = json.load(sys.stdin)
|
||||
inprogress = [c for c in data.get('cards', []) if c.get('status') == 'in_progress']
|
||||
now = time.time()
|
||||
for c in inprogress:
|
||||
updated = c.get('updated_at', '')
|
||||
if updated:
|
||||
age = now - time.mktime(time.strptime(updated[:19], '%Y-%m-%dT%H:%M:%S'))
|
||||
if age > 1800:
|
||||
print(f'⏰ WB TIMEOUT: {c["id"][:8]} [{c.get("agentId","?")}] {c["title"]}')
|
||||
"
|
||||
|
||||
echo ""
|
||||
echo "=== Multica 超时检测 ==="
|
||||
multica issue list --status in_progress --output json 2>/dev/null | python3 -c "
|
||||
import sys, json, time
|
||||
data = json.load(sys.stdin)
|
||||
now = time.time()
|
||||
for issue in data:
|
||||
updated = issue.get('updated_at', '')
|
||||
if updated:
|
||||
age = now - time.mktime(time.strptime(updated[:19], '%Y-%m-%dT%H:%M:%S'))
|
||||
if age > 1800:
|
||||
print(f'⏰ MUL TIMEOUT: {issue["identifier"]} [{issue.get("assignee_id","?")[:12]}] {issue["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 自动恢复规则
|
||||
|
||||
### 触发条件
|
||||
|
||||
- 超 45 分钟无进展 → 自动重新调度
|
||||
|
||||
### 恢复操作（按平台）
|
||||
|
||||
| 平台 | 操作 |
|
||||
|------|------|
|
||||
| WorkBoard | 添加评论 → release claim → 通知 COO + 创建者 |
|
||||
| Multica | 添加评论 → status=blocked → 通知 COO + 创建者 |
|
||||
| 待办文档 | 标注超时 → 转为卡片（可选） |
|
||||
|
||||
---
|
||||
|
||||
## 🔗 依赖检查前置规则
|
||||
|
||||
### 强制检查流程
|
||||
|
||||
1. 认领任务前，读取依赖字段（depends_on / parent_issue_id）
|
||||
2. 逐一检查每个依赖任务的状态
|
||||
3. 依赖未满足 → 不认领（保持 todo）
|
||||
4. 超过等待阈值（2h）→ 通知依赖任务执行者
|
||||
|
||||
### 双平台依赖检查
|
||||
|
||||
```bash
|
||||
# WorkBoard 依赖检查
|
||||
openclaw workboard read <card-id> --json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
card = json.load(sys.stdin)
|
||||
deps = card.get('dependsOn', [])
|
||||
if deps:
|
||||
for dep in deps:
|
||||
if dep.get('status') != 'done':
|
||||
print(f'⛔ WB 依赖未满足: {dep["id"]} → status={dep.get("status","?")}')
|
||||
sys.exit(1)
|
||||
print('✅ 所有 WB 依赖已满足')
|
||||
else:
|
||||
print('✅ 无 WB 依赖，可以启动')
|
||||
"
|
||||
|
||||
# Multica 依赖检查
|
||||
multica issue get <issue-id> --output json 2>/dev/null | python3 -c "
|
||||
import sys, json, subprocess
|
||||
issue = json.load(sys.stdin)
|
||||
parent_id = issue.get('parent_issue_id')
|
||||
if parent_id:
|
||||
result = subprocess.run(['multica', 'issue', 'get', parent_id, '--output', 'json'],
|
||||
capture_output=True, text=True)
|
||||
parent = json.loads(result.stdout)
|
||||
if parent.get('status') != 'done':
|
||||
print(f'⛔ MUL 父 Issue {parent["identifier"]} 未完成')
|
||||
sys.exit(1)
|
||||
print(f'✅ 父 Issue {parent["identifier"]} 已完成')
|
||||
else:
|
||||
print('✅ 无父 Issue 依赖，可以启动')
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛑 最大轮次限制
|
||||
|
||||
### 限制值：100 轮
|
||||
|
||||
- 接近 80%（80 轮）→ 预警
|
||||
- 达到上限 → 暂停，通知 COO + 创建者
|
||||
|
||||
### 跨平台轮次跟踪
|
||||
|
||||
- **WorkBoard**：通过 workboard_heartbeat 的 note 记录轮次
|
||||
- **Multica**：通过 issue comment 记录轮次进度
|
||||
- **待办文档**：在工作日志中记录
|
||||
|
||||
---
|
||||
|
||||
## 🫀 心跳执行清单
|
||||
|
||||
### 每次心跳必须检查
|
||||
|
||||
1. ✅ **全任务源检查**：WorkBoard + Multica + 待办文档
|
||||
2. ✅ 进行中任务超时检测（跨平台）
|
||||
3. ✅ 依赖检查
|
||||
4. ✅ 轮次计数器更新
|
||||
5. ✅ 设计稿进度
|
||||
6. ✅ UI/UX 评审状态
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 全局关键规则
|
||||
|
||||
1. **心跳不打断对话** — 用户正在对话时延后执行
|
||||
2. **非紧急事项延后汇报** — 等下一轮心跳或用户询问
|
||||
3. **发现任务立即执行，不得请示**（任何来源）
|
||||
4. **超时任务按自动恢复流程处理**（跨平台）
|
||||
5. **依赖未满足不启动**
|
||||
6. **达到轮次上限自动暂停**
|
||||
7. **避免任务遗漏** — 三源必须全部检查，缺一不可
|
||||
|
||||
|
||||
---
|
||||
|
||||
> 基于 BIZ-24 v1.1 模板生成 | 苏锦绘（designer）专用配置
|
||||
@@ -1,234 +0,0 @@
|
||||
# HEARTBEAT.md - 苏慎（lawyer）的心跳配置
|
||||
|
||||
> 模板版本：v1.1 (BIZ-24) | 分类：业务 Agent
|
||||
> OpenClaw Agent ID: `lawyer` | Multica Agent UUID: `6fb0fbd2-16a6-4566-ba7a-d2c136baec25`
|
||||
|
||||
---
|
||||
|
||||
## 📋 全任务源统一监控（每次心跳必检）
|
||||
|
||||
> **核心原则：发现任何来源的任务都必须立即执行，不得遗漏。**
|
||||
|
||||
### 三源检查
|
||||
|
||||
#### 第一优先级：OpenClaw WorkBoard 卡片
|
||||
|
||||
```bash
|
||||
# 检查 WorkBoard 中分配给我的待办卡片
|
||||
openclaw workboard list --json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
data = json.load(sys.stdin)
|
||||
my_cards = [c for c in data.get('cards', [])
|
||||
if c.get('agentId') == 'lawyer' and c.get('status') == 'todo']
|
||||
for c in my_cards:
|
||||
print(f'WORKBOARD TODO: {c["id"][:8]} [priority={c.get("priority","?")}] {c["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
#### 第二优先级：Multica Issues
|
||||
|
||||
```bash
|
||||
# 检查 Multica 中分配给我的待办 Issue
|
||||
multica issue list --assignee-id 6fb0fbd2-16a6-4566-ba7a-d2c136baec25 --status todo --output json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
data = json.load(sys.stdin)
|
||||
for issue in data:
|
||||
print(f'MULTICA TODO: {issue["identifier"]} [{issue.get("priority","?")}] {issue["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
#### 第三优先级：待办文档
|
||||
|
||||
```bash
|
||||
# 检查工作区待办文档
|
||||
grep -n '\[ \]' TODO.md AGENTS.md 2>/dev/null || echo "无待办文档中未完成项"
|
||||
```
|
||||
|
||||
### 三源合并决策
|
||||
|
||||
```
|
||||
心跳开始
|
||||
↓
|
||||
检查 WorkBoard 待办卡片（agentId=lawyer）
|
||||
↓
|
||||
检查 Multica Issues 待办（assignee=6fb0fbd2-16a6-4566-ba7a-d2c136baec25）
|
||||
↓
|
||||
检查待办文档
|
||||
↓
|
||||
合并去重 → 按优先级排序 → 依次执行
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 禁止请示规则（最高优先级，自动执行）
|
||||
|
||||
> **核心规则：发现分配给自己的任务 → 立即执行，不得向用户请示！**
|
||||
> 心跳是后台自动行为，用户在大多数时候并不在线，请示会导致任务卡死。
|
||||
|
||||
### 执行流程（严格执行，无需确认）
|
||||
|
||||
1. **三源检查待办** — WorkBoard + Multica + 待办文档
|
||||
2. **立即执行，不得请示** — 发现待办后直接执行
|
||||
3. **检查进行中任务** — 确认认领的任务状态
|
||||
4. **完成任务** — 通过对应平台汇报结果
|
||||
|
||||
### ⚠️ 绝对禁止行为
|
||||
|
||||
- ❌ 不得问"要不要做这个任务"
|
||||
- ❌ 不得等用户确认再执行
|
||||
- ❌ 不得以"需要更多信息"为由拒绝执行
|
||||
|
||||
---
|
||||
|
||||
## ⏱️ 超时检测规则
|
||||
|
||||
### 心跳频率：15 分钟
|
||||
|
||||
每次心跳跨平台执行以下检测：
|
||||
|
||||
1. 检查 WorkBoard 进行中任务的更新时间
|
||||
2. 检查 Multica 进行中 issues 的更新时间
|
||||
3. 超过 30 分钟无进展 → 标记为"疑似超时"
|
||||
4. 疑似超时 → 追加一次完整心跳尝试推进
|
||||
5. 确认超时 → 进入自动恢复流程
|
||||
|
||||
### 跨平台超时检测脚本
|
||||
|
||||
```bash
|
||||
# WorkBoard 超时检测
|
||||
echo "=== WorkBoard 超时检测 ==="
|
||||
openclaw workboard list --json 2>/dev/null | python3 -c "
|
||||
import sys, json, time
|
||||
data = json.load(sys.stdin)
|
||||
inprogress = [c for c in data.get('cards', []) if c.get('status') == 'in_progress']
|
||||
now = time.time()
|
||||
for c in inprogress:
|
||||
updated = c.get('updated_at', '')
|
||||
if updated:
|
||||
age = now - time.mktime(time.strptime(updated[:19], '%Y-%m-%dT%H:%M:%S'))
|
||||
if age > 1800:
|
||||
print(f'⏰ WB TIMEOUT: {c["id"][:8]} [{c.get("agentId","?")}] {c["title"]}')
|
||||
"
|
||||
|
||||
echo ""
|
||||
echo "=== Multica 超时检测 ==="
|
||||
multica issue list --status in_progress --output json 2>/dev/null | python3 -c "
|
||||
import sys, json, time
|
||||
data = json.load(sys.stdin)
|
||||
now = time.time()
|
||||
for issue in data:
|
||||
updated = issue.get('updated_at', '')
|
||||
if updated:
|
||||
age = now - time.mktime(time.strptime(updated[:19], '%Y-%m-%dT%H:%M:%S'))
|
||||
if age > 1800:
|
||||
print(f'⏰ MUL TIMEOUT: {issue["identifier"]} [{issue.get("assignee_id","?")[:12]}] {issue["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 自动恢复规则
|
||||
|
||||
### 触发条件
|
||||
|
||||
- 超 45 分钟无进展 → 自动重新调度
|
||||
|
||||
### 恢复操作（按平台）
|
||||
|
||||
| 平台 | 操作 |
|
||||
|------|------|
|
||||
| WorkBoard | 添加评论 → release claim → 通知 创建者 |
|
||||
| Multica | 添加评论 → status=blocked → 通知 创建者 |
|
||||
| 待办文档 | 标注超时 → 转为卡片（可选） |
|
||||
|
||||
---
|
||||
|
||||
## 🔗 依赖检查前置规则
|
||||
|
||||
### 强制检查流程
|
||||
|
||||
1. 认领任务前，读取依赖字段（depends_on / parent_issue_id）
|
||||
2. 逐一检查每个依赖任务的状态
|
||||
3. 依赖未满足 → 不认领（保持 todo）
|
||||
4. 超过等待阈值（2h）→ 通知依赖任务执行者
|
||||
|
||||
### 双平台依赖检查
|
||||
|
||||
```bash
|
||||
# WorkBoard 依赖检查
|
||||
openclaw workboard read <card-id> --json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
card = json.load(sys.stdin)
|
||||
deps = card.get('dependsOn', [])
|
||||
if deps:
|
||||
for dep in deps:
|
||||
if dep.get('status') != 'done':
|
||||
print(f'⛔ WB 依赖未满足: {dep["id"]} → status={dep.get("status","?")}')
|
||||
sys.exit(1)
|
||||
print('✅ 所有 WB 依赖已满足')
|
||||
else:
|
||||
print('✅ 无 WB 依赖，可以启动')
|
||||
"
|
||||
|
||||
# Multica 依赖检查
|
||||
multica issue get <issue-id> --output json 2>/dev/null | python3 -c "
|
||||
import sys, json, subprocess
|
||||
issue = json.load(sys.stdin)
|
||||
parent_id = issue.get('parent_issue_id')
|
||||
if parent_id:
|
||||
result = subprocess.run(['multica', 'issue', 'get', parent_id, '--output', 'json'],
|
||||
capture_output=True, text=True)
|
||||
parent = json.loads(result.stdout)
|
||||
if parent.get('status') != 'done':
|
||||
print(f'⛔ MUL 父 Issue {parent["identifier"]} 未完成')
|
||||
sys.exit(1)
|
||||
print(f'✅ 父 Issue {parent["identifier"]} 已完成')
|
||||
else:
|
||||
print('✅ 无父 Issue 依赖，可以启动')
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛑 最大轮次限制
|
||||
|
||||
### 限制值：30 轮
|
||||
|
||||
- 接近 80%（24 轮）→ 预警
|
||||
- 达到上限 → 暂停，通知 创建者
|
||||
|
||||
### 跨平台轮次跟踪
|
||||
|
||||
- **WorkBoard**：通过 workboard_heartbeat 的 note 记录轮次
|
||||
- **Multica**：通过 issue comment 记录轮次进度
|
||||
- **待办文档**：在工作日志中记录
|
||||
|
||||
---
|
||||
|
||||
## 🫀 心跳执行清单
|
||||
|
||||
### 每次心跳必须检查
|
||||
|
||||
1. ✅ **全任务源检查**：WorkBoard + Multica + 待办文档
|
||||
2. ✅ 进行中任务超时检测（跨平台）
|
||||
3. ✅ 依赖检查
|
||||
4. ✅ 轮次计数器更新
|
||||
5. ✅ 合同审查队列
|
||||
6. ✅ 合规检查项
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 全局关键规则
|
||||
|
||||
1. **心跳不打断对话** — 用户正在对话时延后执行
|
||||
2. **非紧急事项延后汇报** — 等下一轮心跳或用户询问
|
||||
3. **发现任务立即执行，不得请示**（任何来源）
|
||||
4. **超时任务按自动恢复流程处理**（跨平台）
|
||||
5. **依赖未满足不启动**
|
||||
6. **达到轮次上限自动暂停**
|
||||
7. **避免任务遗漏** — 三源必须全部检查，缺一不可
|
||||
|
||||
|
||||
---
|
||||
|
||||
> 基于 BIZ-24 v1.1 模板生成 | 苏慎（lawyer）专用配置
|
||||
@@ -1,234 +0,0 @@
|
||||
# HEARTBEAT.md - 顾析策（marketanalysis）的心跳配置
|
||||
|
||||
> 模板版本：v1.1 (BIZ-24) | 分类：业务 Agent
|
||||
> OpenClaw Agent ID: `marketanalysis` | Multica Agent UUID: `5ed91729-658f-4654-98f0-3e0313022002`
|
||||
|
||||
---
|
||||
|
||||
## 📋 全任务源统一监控（每次心跳必检）
|
||||
|
||||
> **核心原则：发现任何来源的任务都必须立即执行，不得遗漏。**
|
||||
|
||||
### 三源检查
|
||||
|
||||
#### 第一优先级：OpenClaw WorkBoard 卡片
|
||||
|
||||
```bash
|
||||
# 检查 WorkBoard 中分配给我的待办卡片
|
||||
openclaw workboard list --json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
data = json.load(sys.stdin)
|
||||
my_cards = [c for c in data.get('cards', [])
|
||||
if c.get('agentId') == 'marketanalysis' and c.get('status') == 'todo']
|
||||
for c in my_cards:
|
||||
print(f'WORKBOARD TODO: {c["id"][:8]} [priority={c.get("priority","?")}] {c["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
#### 第二优先级：Multica Issues
|
||||
|
||||
```bash
|
||||
# 检查 Multica 中分配给我的待办 Issue
|
||||
multica issue list --assignee-id 5ed91729-658f-4654-98f0-3e0313022002 --status todo --output json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
data = json.load(sys.stdin)
|
||||
for issue in data:
|
||||
print(f'MULTICA TODO: {issue["identifier"]} [{issue.get("priority","?")}] {issue["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
#### 第三优先级：待办文档
|
||||
|
||||
```bash
|
||||
# 检查工作区待办文档
|
||||
grep -n '\[ \]' TODO.md AGENTS.md 2>/dev/null || echo "无待办文档中未完成项"
|
||||
```
|
||||
|
||||
### 三源合并决策
|
||||
|
||||
```
|
||||
心跳开始
|
||||
↓
|
||||
检查 WorkBoard 待办卡片（agentId=marketanalysis）
|
||||
↓
|
||||
检查 Multica Issues 待办（assignee=5ed91729-658f-4654-98f0-3e0313022002）
|
||||
↓
|
||||
检查待办文档
|
||||
↓
|
||||
合并去重 → 按优先级排序 → 依次执行
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 禁止请示规则（最高优先级，自动执行）
|
||||
|
||||
> **核心规则：发现分配给自己的任务 → 立即执行，不得向用户请示！**
|
||||
> 心跳是后台自动行为，用户在大多数时候并不在线，请示会导致任务卡死。
|
||||
|
||||
### 执行流程（严格执行，无需确认）
|
||||
|
||||
1. **三源检查待办** — WorkBoard + Multica + 待办文档
|
||||
2. **立即执行，不得请示** — 发现待办后直接执行
|
||||
3. **检查进行中任务** — 确认认领的任务状态
|
||||
4. **完成任务** — 通过对应平台汇报结果
|
||||
|
||||
### ⚠️ 绝对禁止行为
|
||||
|
||||
- ❌ 不得问"要不要做这个任务"
|
||||
- ❌ 不得等用户确认再执行
|
||||
- ❌ 不得以"需要更多信息"为由拒绝执行
|
||||
|
||||
---
|
||||
|
||||
## ⏱️ 超时检测规则
|
||||
|
||||
### 心跳频率：15 分钟
|
||||
|
||||
每次心跳跨平台执行以下检测：
|
||||
|
||||
1. 检查 WorkBoard 进行中任务的更新时间
|
||||
2. 检查 Multica 进行中 issues 的更新时间
|
||||
3. 超过 30 分钟无进展 → 标记为"疑似超时"
|
||||
4. 疑似超时 → 追加一次完整心跳尝试推进
|
||||
5. 确认超时 → 进入自动恢复流程
|
||||
|
||||
### 跨平台超时检测脚本
|
||||
|
||||
```bash
|
||||
# WorkBoard 超时检测
|
||||
echo "=== WorkBoard 超时检测 ==="
|
||||
openclaw workboard list --json 2>/dev/null | python3 -c "
|
||||
import sys, json, time
|
||||
data = json.load(sys.stdin)
|
||||
inprogress = [c for c in data.get('cards', []) if c.get('status') == 'in_progress']
|
||||
now = time.time()
|
||||
for c in inprogress:
|
||||
updated = c.get('updated_at', '')
|
||||
if updated:
|
||||
age = now - time.mktime(time.strptime(updated[:19], '%Y-%m-%dT%H:%M:%S'))
|
||||
if age > 1800:
|
||||
print(f'⏰ WB TIMEOUT: {c["id"][:8]} [{c.get("agentId","?")}] {c["title"]}')
|
||||
"
|
||||
|
||||
echo ""
|
||||
echo "=== Multica 超时检测 ==="
|
||||
multica issue list --status in_progress --output json 2>/dev/null | python3 -c "
|
||||
import sys, json, time
|
||||
data = json.load(sys.stdin)
|
||||
now = time.time()
|
||||
for issue in data:
|
||||
updated = issue.get('updated_at', '')
|
||||
if updated:
|
||||
age = now - time.mktime(time.strptime(updated[:19], '%Y-%m-%dT%H:%M:%S'))
|
||||
if age > 1800:
|
||||
print(f'⏰ MUL TIMEOUT: {issue["identifier"]} [{issue.get("assignee_id","?")[:12]}] {issue["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 自动恢复规则
|
||||
|
||||
### 触发条件
|
||||
|
||||
- 超 45 分钟无进展 → 自动重新调度
|
||||
|
||||
### 恢复操作（按平台）
|
||||
|
||||
| 平台 | 操作 |
|
||||
|------|------|
|
||||
| WorkBoard | 添加评论 → release claim → 通知 创建者 |
|
||||
| Multica | 添加评论 → status=blocked → 通知 创建者 |
|
||||
| 待办文档 | 标注超时 → 转为卡片（可选） |
|
||||
|
||||
---
|
||||
|
||||
## 🔗 依赖检查前置规则
|
||||
|
||||
### 强制检查流程
|
||||
|
||||
1. 认领任务前，读取依赖字段（depends_on / parent_issue_id）
|
||||
2. 逐一检查每个依赖任务的状态
|
||||
3. 依赖未满足 → 不认领（保持 todo）
|
||||
4. 超过等待阈值（2h）→ 通知依赖任务执行者
|
||||
|
||||
### 双平台依赖检查
|
||||
|
||||
```bash
|
||||
# WorkBoard 依赖检查
|
||||
openclaw workboard read <card-id> --json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
card = json.load(sys.stdin)
|
||||
deps = card.get('dependsOn', [])
|
||||
if deps:
|
||||
for dep in deps:
|
||||
if dep.get('status') != 'done':
|
||||
print(f'⛔ WB 依赖未满足: {dep["id"]} → status={dep.get("status","?")}')
|
||||
sys.exit(1)
|
||||
print('✅ 所有 WB 依赖已满足')
|
||||
else:
|
||||
print('✅ 无 WB 依赖，可以启动')
|
||||
"
|
||||
|
||||
# Multica 依赖检查
|
||||
multica issue get <issue-id> --output json 2>/dev/null | python3 -c "
|
||||
import sys, json, subprocess
|
||||
issue = json.load(sys.stdin)
|
||||
parent_id = issue.get('parent_issue_id')
|
||||
if parent_id:
|
||||
result = subprocess.run(['multica', 'issue', 'get', parent_id, '--output', 'json'],
|
||||
capture_output=True, text=True)
|
||||
parent = json.loads(result.stdout)
|
||||
if parent.get('status') != 'done':
|
||||
print(f'⛔ MUL 父 Issue {parent["identifier"]} 未完成')
|
||||
sys.exit(1)
|
||||
print(f'✅ 父 Issue {parent["identifier"]} 已完成')
|
||||
else:
|
||||
print('✅ 无父 Issue 依赖，可以启动')
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛑 最大轮次限制
|
||||
|
||||
### 限制值：30 轮
|
||||
|
||||
- 接近 80%（24 轮）→ 预警
|
||||
- 达到上限 → 暂停，通知 创建者
|
||||
|
||||
### 跨平台轮次跟踪
|
||||
|
||||
- **WorkBoard**：通过 workboard_heartbeat 的 note 记录轮次
|
||||
- **Multica**：通过 issue comment 记录轮次进度
|
||||
- **待办文档**：在工作日志中记录
|
||||
|
||||
---
|
||||
|
||||
## 🫀 心跳执行清单
|
||||
|
||||
### 每次心跳必须检查
|
||||
|
||||
1. ✅ **全任务源检查**：WorkBoard + Multica + 待办文档
|
||||
2. ✅ 进行中任务超时检测（跨平台）
|
||||
3. ✅ 依赖检查
|
||||
4. ✅ 轮次计数器更新
|
||||
5. ✅ 市场分析任务
|
||||
6. ✅ 竞品数据更新
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 全局关键规则
|
||||
|
||||
1. **心跳不打断对话** — 用户正在对话时延后执行
|
||||
2. **非紧急事项延后汇报** — 等下一轮心跳或用户询问
|
||||
3. **发现任务立即执行，不得请示**（任何来源）
|
||||
4. **超时任务按自动恢复流程处理**（跨平台）
|
||||
5. **依赖未满足不启动**
|
||||
6. **达到轮次上限自动暂停**
|
||||
7. **避免任务遗漏** — 三源必须全部检查，缺一不可
|
||||
|
||||
|
||||
---
|
||||
|
||||
> 基于 BIZ-24 v1.1 模板生成 | 顾析策（marketanalysis）专用配置
|
||||
@@ -1,234 +0,0 @@
|
||||
# HEARTBEAT.md - 钟帧韵（mediaspecialist）的心跳配置
|
||||
|
||||
> 模板版本：v1.1 (BIZ-24) | 分类：业务 Agent
|
||||
> OpenClaw Agent ID: `mediaspecialist` | Multica Agent UUID: `e2b587d4-1d16-447c-8ad9-e2a01358ff0a`
|
||||
|
||||
---
|
||||
|
||||
## 📋 全任务源统一监控（每次心跳必检）
|
||||
|
||||
> **核心原则：发现任何来源的任务都必须立即执行，不得遗漏。**
|
||||
|
||||
### 三源检查
|
||||
|
||||
#### 第一优先级：OpenClaw WorkBoard 卡片
|
||||
|
||||
```bash
|
||||
# 检查 WorkBoard 中分配给我的待办卡片
|
||||
openclaw workboard list --json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
data = json.load(sys.stdin)
|
||||
my_cards = [c for c in data.get('cards', [])
|
||||
if c.get('agentId') == 'mediaspecialist' and c.get('status') == 'todo']
|
||||
for c in my_cards:
|
||||
print(f'WORKBOARD TODO: {c["id"][:8]} [priority={c.get("priority","?")}] {c["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
#### 第二优先级：Multica Issues
|
||||
|
||||
```bash
|
||||
# 检查 Multica 中分配给我的待办 Issue
|
||||
multica issue list --assignee-id e2b587d4-1d16-447c-8ad9-e2a01358ff0a --status todo --output json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
data = json.load(sys.stdin)
|
||||
for issue in data:
|
||||
print(f'MULTICA TODO: {issue["identifier"]} [{issue.get("priority","?")}] {issue["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
#### 第三优先级：待办文档
|
||||
|
||||
```bash
|
||||
# 检查工作区待办文档
|
||||
grep -n '\[ \]' TODO.md AGENTS.md 2>/dev/null || echo "无待办文档中未完成项"
|
||||
```
|
||||
|
||||
### 三源合并决策
|
||||
|
||||
```
|
||||
心跳开始
|
||||
↓
|
||||
检查 WorkBoard 待办卡片（agentId=mediaspecialist）
|
||||
↓
|
||||
检查 Multica Issues 待办（assignee=e2b587d4-1d16-447c-8ad9-e2a01358ff0a）
|
||||
↓
|
||||
检查待办文档
|
||||
↓
|
||||
合并去重 → 按优先级排序 → 依次执行
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 禁止请示规则（最高优先级，自动执行）
|
||||
|
||||
> **核心规则：发现分配给自己的任务 → 立即执行，不得向用户请示！**
|
||||
> 心跳是后台自动行为，用户在大多数时候并不在线，请示会导致任务卡死。
|
||||
|
||||
### 执行流程（严格执行，无需确认）
|
||||
|
||||
1. **三源检查待办** — WorkBoard + Multica + 待办文档
|
||||
2. **立即执行，不得请示** — 发现待办后直接执行
|
||||
3. **检查进行中任务** — 确认认领的任务状态
|
||||
4. **完成任务** — 通过对应平台汇报结果
|
||||
|
||||
### ⚠️ 绝对禁止行为
|
||||
|
||||
- ❌ 不得问"要不要做这个任务"
|
||||
- ❌ 不得等用户确认再执行
|
||||
- ❌ 不得以"需要更多信息"为由拒绝执行
|
||||
|
||||
---
|
||||
|
||||
## ⏱️ 超时检测规则
|
||||
|
||||
### 心跳频率：15 分钟
|
||||
|
||||
每次心跳跨平台执行以下检测：
|
||||
|
||||
1. 检查 WorkBoard 进行中任务的更新时间
|
||||
2. 检查 Multica 进行中 issues 的更新时间
|
||||
3. 超过 30 分钟无进展 → 标记为"疑似超时"
|
||||
4. 疑似超时 → 追加一次完整心跳尝试推进
|
||||
5. 确认超时 → 进入自动恢复流程
|
||||
|
||||
### 跨平台超时检测脚本
|
||||
|
||||
```bash
|
||||
# WorkBoard 超时检测
|
||||
echo "=== WorkBoard 超时检测 ==="
|
||||
openclaw workboard list --json 2>/dev/null | python3 -c "
|
||||
import sys, json, time
|
||||
data = json.load(sys.stdin)
|
||||
inprogress = [c for c in data.get('cards', []) if c.get('status') == 'in_progress']
|
||||
now = time.time()
|
||||
for c in inprogress:
|
||||
updated = c.get('updated_at', '')
|
||||
if updated:
|
||||
age = now - time.mktime(time.strptime(updated[:19], '%Y-%m-%dT%H:%M:%S'))
|
||||
if age > 1800:
|
||||
print(f'⏰ WB TIMEOUT: {c["id"][:8]} [{c.get("agentId","?")}] {c["title"]}')
|
||||
"
|
||||
|
||||
echo ""
|
||||
echo "=== Multica 超时检测 ==="
|
||||
multica issue list --status in_progress --output json 2>/dev/null | python3 -c "
|
||||
import sys, json, time
|
||||
data = json.load(sys.stdin)
|
||||
now = time.time()
|
||||
for issue in data:
|
||||
updated = issue.get('updated_at', '')
|
||||
if updated:
|
||||
age = now - time.mktime(time.strptime(updated[:19], '%Y-%m-%dT%H:%M:%S'))
|
||||
if age > 1800:
|
||||
print(f'⏰ MUL TIMEOUT: {issue["identifier"]} [{issue.get("assignee_id","?")[:12]}] {issue["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 自动恢复规则
|
||||
|
||||
### 触发条件
|
||||
|
||||
- 超 45 分钟无进展 → 自动重新调度
|
||||
|
||||
### 恢复操作（按平台）
|
||||
|
||||
| 平台 | 操作 |
|
||||
|------|------|
|
||||
| WorkBoard | 添加评论 → release claim → 通知 创建者 |
|
||||
| Multica | 添加评论 → status=blocked → 通知 创建者 |
|
||||
| 待办文档 | 标注超时 → 转为卡片（可选） |
|
||||
|
||||
---
|
||||
|
||||
## 🔗 依赖检查前置规则
|
||||
|
||||
### 强制检查流程
|
||||
|
||||
1. 认领任务前，读取依赖字段（depends_on / parent_issue_id）
|
||||
2. 逐一检查每个依赖任务的状态
|
||||
3. 依赖未满足 → 不认领（保持 todo）
|
||||
4. 超过等待阈值（2h）→ 通知依赖任务执行者
|
||||
|
||||
### 双平台依赖检查
|
||||
|
||||
```bash
|
||||
# WorkBoard 依赖检查
|
||||
openclaw workboard read <card-id> --json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
card = json.load(sys.stdin)
|
||||
deps = card.get('dependsOn', [])
|
||||
if deps:
|
||||
for dep in deps:
|
||||
if dep.get('status') != 'done':
|
||||
print(f'⛔ WB 依赖未满足: {dep["id"]} → status={dep.get("status","?")}')
|
||||
sys.exit(1)
|
||||
print('✅ 所有 WB 依赖已满足')
|
||||
else:
|
||||
print('✅ 无 WB 依赖，可以启动')
|
||||
"
|
||||
|
||||
# Multica 依赖检查
|
||||
multica issue get <issue-id> --output json 2>/dev/null | python3 -c "
|
||||
import sys, json, subprocess
|
||||
issue = json.load(sys.stdin)
|
||||
parent_id = issue.get('parent_issue_id')
|
||||
if parent_id:
|
||||
result = subprocess.run(['multica', 'issue', 'get', parent_id, '--output', 'json'],
|
||||
capture_output=True, text=True)
|
||||
parent = json.loads(result.stdout)
|
||||
if parent.get('status') != 'done':
|
||||
print(f'⛔ MUL 父 Issue {parent["identifier"]} 未完成')
|
||||
sys.exit(1)
|
||||
print(f'✅ 父 Issue {parent["identifier"]} 已完成')
|
||||
else:
|
||||
print('✅ 无父 Issue 依赖，可以启动')
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛑 最大轮次限制
|
||||
|
||||
### 限制值：30 轮
|
||||
|
||||
- 接近 80%（24 轮）→ 预警
|
||||
- 达到上限 → 暂停，通知 创建者
|
||||
|
||||
### 跨平台轮次跟踪
|
||||
|
||||
- **WorkBoard**：通过 workboard_heartbeat 的 note 记录轮次
|
||||
- **Multica**：通过 issue comment 记录轮次进度
|
||||
- **待办文档**：在工作日志中记录
|
||||
|
||||
---
|
||||
|
||||
## 🫀 心跳执行清单
|
||||
|
||||
### 每次心跳必须检查
|
||||
|
||||
1. ✅ **全任务源检查**：WorkBoard + Multica + 待办文档
|
||||
2. ✅ 进行中任务超时检测（跨平台）
|
||||
3. ✅ 依赖检查
|
||||
4. ✅ 轮次计数器更新
|
||||
5. ✅ 视频制作进度
|
||||
6. ✅ 媒体素材准备状态
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 全局关键规则
|
||||
|
||||
1. **心跳不打断对话** — 用户正在对话时延后执行
|
||||
2. **非紧急事项延后汇报** — 等下一轮心跳或用户询问
|
||||
3. **发现任务立即执行，不得请示**（任何来源）
|
||||
4. **超时任务按自动恢复流程处理**（跨平台）
|
||||
5. **依赖未满足不启动**
|
||||
6. **达到轮次上限自动暂停**
|
||||
7. **避免任务遗漏** — 三源必须全部检查，缺一不可
|
||||
|
||||
|
||||
---
|
||||
|
||||
> 基于 BIZ-24 v1.1 模板生成 | 钟帧韵（mediaspecialist）专用配置
|
||||
@@ -1,234 +0,0 @@
|
||||
# HEARTBEAT.md - 严维序（opengineer）的心跳配置
|
||||
|
||||
> 模板版本：v1.1 (BIZ-24) | 分类：开发 Agent
|
||||
> OpenClaw Agent ID: `opengineer` | Multica Agent UUID: `d3804433-9e2e-4199-a92b-a153049b3bc9`
|
||||
|
||||
---
|
||||
|
||||
## 📋 全任务源统一监控（每次心跳必检）
|
||||
|
||||
> **核心原则：发现任何来源的任务都必须立即执行，不得遗漏。**
|
||||
|
||||
### 三源检查
|
||||
|
||||
#### 第一优先级：OpenClaw WorkBoard 卡片
|
||||
|
||||
```bash
|
||||
# 检查 WorkBoard 中分配给我的待办卡片
|
||||
openclaw workboard list --json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
data = json.load(sys.stdin)
|
||||
my_cards = [c for c in data.get('cards', [])
|
||||
if c.get('agentId') == 'opengineer' and c.get('status') == 'todo']
|
||||
for c in my_cards:
|
||||
print(f'WORKBOARD TODO: {c["id"][:8]} [priority={c.get("priority","?")}] {c["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
#### 第二优先级：Multica Issues
|
||||
|
||||
```bash
|
||||
# 检查 Multica 中分配给我的待办 Issue
|
||||
multica issue list --assignee-id d3804433-9e2e-4199-a92b-a153049b3bc9 --status todo --output json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
data = json.load(sys.stdin)
|
||||
for issue in data:
|
||||
print(f'MULTICA TODO: {issue["identifier"]} [{issue.get("priority","?")}] {issue["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
#### 第三优先级：待办文档
|
||||
|
||||
```bash
|
||||
# 检查工作区待办文档
|
||||
grep -n '\[ \]' TODO.md AGENTS.md 2>/dev/null || echo "无待办文档中未完成项"
|
||||
```
|
||||
|
||||
### 三源合并决策
|
||||
|
||||
```
|
||||
心跳开始
|
||||
↓
|
||||
检查 WorkBoard 待办卡片（agentId=opengineer）
|
||||
↓
|
||||
检查 Multica Issues 待办（assignee=d3804433-9e2e-4199-a92b-a153049b3bc9）
|
||||
↓
|
||||
检查待办文档
|
||||
↓
|
||||
合并去重 → 按优先级排序 → 依次执行
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 禁止请示规则（最高优先级，自动执行）
|
||||
|
||||
> **核心规则：发现分配给自己的任务 → 立即执行，不得向用户请示！**
|
||||
> 心跳是后台自动行为，用户在大多数时候并不在线，请示会导致任务卡死。
|
||||
|
||||
### 执行流程（严格执行，无需确认）
|
||||
|
||||
1. **三源检查待办** — WorkBoard + Multica + 待办文档
|
||||
2. **立即执行，不得请示** — 发现待办后直接执行
|
||||
3. **检查进行中任务** — 确认认领的任务状态
|
||||
4. **完成任务** — 通过对应平台汇报结果
|
||||
|
||||
### ⚠️ 绝对禁止行为
|
||||
|
||||
- ❌ 不得问"要不要做这个任务"
|
||||
- ❌ 不得等用户确认再执行
|
||||
- ❌ 不得以"需要更多信息"为由拒绝执行
|
||||
|
||||
---
|
||||
|
||||
## ⏱️ 超时检测规则
|
||||
|
||||
### 心跳频率：15 分钟
|
||||
|
||||
每次心跳跨平台执行以下检测：
|
||||
|
||||
1. 检查 WorkBoard 进行中任务的更新时间
|
||||
2. 检查 Multica 进行中 issues 的更新时间
|
||||
3. 超过 30 分钟无进展 → 标记为"疑似超时"
|
||||
4. 疑似超时 → 追加一次完整心跳尝试推进
|
||||
5. 确认超时 → 进入自动恢复流程
|
||||
|
||||
### 跨平台超时检测脚本
|
||||
|
||||
```bash
|
||||
# WorkBoard 超时检测
|
||||
echo "=== WorkBoard 超时检测 ==="
|
||||
openclaw workboard list --json 2>/dev/null | python3 -c "
|
||||
import sys, json, time
|
||||
data = json.load(sys.stdin)
|
||||
inprogress = [c for c in data.get('cards', []) if c.get('status') == 'in_progress']
|
||||
now = time.time()
|
||||
for c in inprogress:
|
||||
updated = c.get('updated_at', '')
|
||||
if updated:
|
||||
age = now - time.mktime(time.strptime(updated[:19], '%Y-%m-%dT%H:%M:%S'))
|
||||
if age > 1800:
|
||||
print(f'⏰ WB TIMEOUT: {c["id"][:8]} [{c.get("agentId","?")}] {c["title"]}')
|
||||
"
|
||||
|
||||
echo ""
|
||||
echo "=== Multica 超时检测 ==="
|
||||
multica issue list --status in_progress --output json 2>/dev/null | python3 -c "
|
||||
import sys, json, time
|
||||
data = json.load(sys.stdin)
|
||||
now = time.time()
|
||||
for issue in data:
|
||||
updated = issue.get('updated_at', '')
|
||||
if updated:
|
||||
age = now - time.mktime(time.strptime(updated[:19], '%Y-%m-%dT%H:%M:%S'))
|
||||
if age > 1800:
|
||||
print(f'⏰ MUL TIMEOUT: {issue["identifier"]} [{issue.get("assignee_id","?")[:12]}] {issue["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 自动恢复规则
|
||||
|
||||
### 触发条件
|
||||
|
||||
- 超 45 分钟无进展 → 自动重新调度
|
||||
|
||||
### 恢复操作（按平台）
|
||||
|
||||
| 平台 | 操作 |
|
||||
|------|------|
|
||||
| WorkBoard | 添加评论 → release claim → 通知 COO + 创建者 |
|
||||
| Multica | 添加评论 → status=blocked → 通知 COO + 创建者 |
|
||||
| 待办文档 | 标注超时 → 转为卡片（可选） |
|
||||
|
||||
---
|
||||
|
||||
## 🔗 依赖检查前置规则
|
||||
|
||||
### 强制检查流程
|
||||
|
||||
1. 认领任务前，读取依赖字段（depends_on / parent_issue_id）
|
||||
2. 逐一检查每个依赖任务的状态
|
||||
3. 依赖未满足 → 不认领（保持 todo）
|
||||
4. 超过等待阈值（2h）→ 通知依赖任务执行者
|
||||
|
||||
### 双平台依赖检查
|
||||
|
||||
```bash
|
||||
# WorkBoard 依赖检查
|
||||
openclaw workboard read <card-id> --json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
card = json.load(sys.stdin)
|
||||
deps = card.get('dependsOn', [])
|
||||
if deps:
|
||||
for dep in deps:
|
||||
if dep.get('status') != 'done':
|
||||
print(f'⛔ WB 依赖未满足: {dep["id"]} → status={dep.get("status","?")}')
|
||||
sys.exit(1)
|
||||
print('✅ 所有 WB 依赖已满足')
|
||||
else:
|
||||
print('✅ 无 WB 依赖，可以启动')
|
||||
"
|
||||
|
||||
# Multica 依赖检查
|
||||
multica issue get <issue-id> --output json 2>/dev/null | python3 -c "
|
||||
import sys, json, subprocess
|
||||
issue = json.load(sys.stdin)
|
||||
parent_id = issue.get('parent_issue_id')
|
||||
if parent_id:
|
||||
result = subprocess.run(['multica', 'issue', 'get', parent_id, '--output', 'json'],
|
||||
capture_output=True, text=True)
|
||||
parent = json.loads(result.stdout)
|
||||
if parent.get('status') != 'done':
|
||||
print(f'⛔ MUL 父 Issue {parent["identifier"]} 未完成')
|
||||
sys.exit(1)
|
||||
print(f'✅ 父 Issue {parent["identifier"]} 已完成')
|
||||
else:
|
||||
print('✅ 无父 Issue 依赖，可以启动')
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛑 最大轮次限制
|
||||
|
||||
### 限制值：100 轮
|
||||
|
||||
- 接近 80%（80 轮）→ 预警
|
||||
- 达到上限 → 暂停，通知 COO + 创建者
|
||||
|
||||
### 跨平台轮次跟踪
|
||||
|
||||
- **WorkBoard**：通过 workboard_heartbeat 的 note 记录轮次
|
||||
- **Multica**：通过 issue comment 记录轮次进度
|
||||
- **待办文档**：在工作日志中记录
|
||||
|
||||
---
|
||||
|
||||
## 🫀 心跳执行清单
|
||||
|
||||
### 每次心跳必须检查
|
||||
|
||||
1. ✅ **全任务源检查**：WorkBoard + Multica + 待办文档
|
||||
2. ✅ 进行中任务超时检测（跨平台）
|
||||
3. ✅ 依赖检查
|
||||
4. ✅ 轮次计数器更新
|
||||
5. ✅ 部署状态检查
|
||||
6. ✅ 服务器/服务健康状况
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 全局关键规则
|
||||
|
||||
1. **心跳不打断对话** — 用户正在对话时延后执行
|
||||
2. **非紧急事项延后汇报** — 等下一轮心跳或用户询问
|
||||
3. **发现任务立即执行，不得请示**（任何来源）
|
||||
4. **超时任务按自动恢复流程处理**（跨平台）
|
||||
5. **依赖未满足不启动**
|
||||
6. **达到轮次上限自动暂停**
|
||||
7. **避免任务遗漏** — 三源必须全部检查，缺一不可
|
||||
|
||||
|
||||
---
|
||||
|
||||
> 基于 BIZ-24 v1.1 模板生成 | 严维序（opengineer）专用配置
|
||||
@@ -1,234 +0,0 @@
|
||||
# HEARTBEAT.md - 沈路明（productmanager）的心跳配置
|
||||
|
||||
> 模板版本：v1.1 (BIZ-24) | 分类：开发 Agent
|
||||
> OpenClaw Agent ID: `productmanager` | Multica Agent UUID: `a101fa88-d821-4839-9754-e04580d5fd68`
|
||||
|
||||
---
|
||||
|
||||
## 📋 全任务源统一监控（每次心跳必检）
|
||||
|
||||
> **核心原则：发现任何来源的任务都必须立即执行，不得遗漏。**
|
||||
|
||||
### 三源检查
|
||||
|
||||
#### 第一优先级：OpenClaw WorkBoard 卡片
|
||||
|
||||
```bash
|
||||
# 检查 WorkBoard 中分配给我的待办卡片
|
||||
openclaw workboard list --json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
data = json.load(sys.stdin)
|
||||
my_cards = [c for c in data.get('cards', [])
|
||||
if c.get('agentId') == 'productmanager' and c.get('status') == 'todo']
|
||||
for c in my_cards:
|
||||
print(f'WORKBOARD TODO: {c["id"][:8]} [priority={c.get("priority","?")}] {c["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
#### 第二优先级：Multica Issues
|
||||
|
||||
```bash
|
||||
# 检查 Multica 中分配给我的待办 Issue
|
||||
multica issue list --assignee-id a101fa88-d821-4839-9754-e04580d5fd68 --status todo --output json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
data = json.load(sys.stdin)
|
||||
for issue in data:
|
||||
print(f'MULTICA TODO: {issue["identifier"]} [{issue.get("priority","?")}] {issue["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
#### 第三优先级：待办文档
|
||||
|
||||
```bash
|
||||
# 检查工作区待办文档
|
||||
grep -n '\[ \]' TODO.md AGENTS.md 2>/dev/null || echo "无待办文档中未完成项"
|
||||
```
|
||||
|
||||
### 三源合并决策
|
||||
|
||||
```
|
||||
心跳开始
|
||||
↓
|
||||
检查 WorkBoard 待办卡片（agentId=productmanager）
|
||||
↓
|
||||
检查 Multica Issues 待办（assignee=a101fa88-d821-4839-9754-e04580d5fd68）
|
||||
↓
|
||||
检查待办文档
|
||||
↓
|
||||
合并去重 → 按优先级排序 → 依次执行
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 禁止请示规则（最高优先级，自动执行）
|
||||
|
||||
> **核心规则：发现分配给自己的任务 → 立即执行，不得向用户请示！**
|
||||
> 心跳是后台自动行为，用户在大多数时候并不在线，请示会导致任务卡死。
|
||||
|
||||
### 执行流程（严格执行，无需确认）
|
||||
|
||||
1. **三源检查待办** — WorkBoard + Multica + 待办文档
|
||||
2. **立即执行，不得请示** — 发现待办后直接执行
|
||||
3. **检查进行中任务** — 确认认领的任务状态
|
||||
4. **完成任务** — 通过对应平台汇报结果
|
||||
|
||||
### ⚠️ 绝对禁止行为
|
||||
|
||||
- ❌ 不得问"要不要做这个任务"
|
||||
- ❌ 不得等用户确认再执行
|
||||
- ❌ 不得以"需要更多信息"为由拒绝执行
|
||||
|
||||
---
|
||||
|
||||
## ⏱️ 超时检测规则
|
||||
|
||||
### 心跳频率：15 分钟
|
||||
|
||||
每次心跳跨平台执行以下检测：
|
||||
|
||||
1. 检查 WorkBoard 进行中任务的更新时间
|
||||
2. 检查 Multica 进行中 issues 的更新时间
|
||||
3. 超过 30 分钟无进展 → 标记为"疑似超时"
|
||||
4. 疑似超时 → 追加一次完整心跳尝试推进
|
||||
5. 确认超时 → 进入自动恢复流程
|
||||
|
||||
### 跨平台超时检测脚本
|
||||
|
||||
```bash
|
||||
# WorkBoard 超时检测
|
||||
echo "=== WorkBoard 超时检测 ==="
|
||||
openclaw workboard list --json 2>/dev/null | python3 -c "
|
||||
import sys, json, time
|
||||
data = json.load(sys.stdin)
|
||||
inprogress = [c for c in data.get('cards', []) if c.get('status') == 'in_progress']
|
||||
now = time.time()
|
||||
for c in inprogress:
|
||||
updated = c.get('updated_at', '')
|
||||
if updated:
|
||||
age = now - time.mktime(time.strptime(updated[:19], '%Y-%m-%dT%H:%M:%S'))
|
||||
if age > 1800:
|
||||
print(f'⏰ WB TIMEOUT: {c["id"][:8]} [{c.get("agentId","?")}] {c["title"]}')
|
||||
"
|
||||
|
||||
echo ""
|
||||
echo "=== Multica 超时检测 ==="
|
||||
multica issue list --status in_progress --output json 2>/dev/null | python3 -c "
|
||||
import sys, json, time
|
||||
data = json.load(sys.stdin)
|
||||
now = time.time()
|
||||
for issue in data:
|
||||
updated = issue.get('updated_at', '')
|
||||
if updated:
|
||||
age = now - time.mktime(time.strptime(updated[:19], '%Y-%m-%dT%H:%M:%S'))
|
||||
if age > 1800:
|
||||
print(f'⏰ MUL TIMEOUT: {issue["identifier"]} [{issue.get("assignee_id","?")[:12]}] {issue["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 自动恢复规则
|
||||
|
||||
### 触发条件
|
||||
|
||||
- 超 45 分钟无进展 → 自动重新调度
|
||||
|
||||
### 恢复操作（按平台）
|
||||
|
||||
| 平台 | 操作 |
|
||||
|------|------|
|
||||
| WorkBoard | 添加评论 → release claim → 通知 COO + 创建者 |
|
||||
| Multica | 添加评论 → status=blocked → 通知 COO + 创建者 |
|
||||
| 待办文档 | 标注超时 → 转为卡片（可选） |
|
||||
|
||||
---
|
||||
|
||||
## 🔗 依赖检查前置规则
|
||||
|
||||
### 强制检查流程
|
||||
|
||||
1. 认领任务前，读取依赖字段（depends_on / parent_issue_id）
|
||||
2. 逐一检查每个依赖任务的状态
|
||||
3. 依赖未满足 → 不认领（保持 todo）
|
||||
4. 超过等待阈值（2h）→ 通知依赖任务执行者
|
||||
|
||||
### 双平台依赖检查
|
||||
|
||||
```bash
|
||||
# WorkBoard 依赖检查
|
||||
openclaw workboard read <card-id> --json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
card = json.load(sys.stdin)
|
||||
deps = card.get('dependsOn', [])
|
||||
if deps:
|
||||
for dep in deps:
|
||||
if dep.get('status') != 'done':
|
||||
print(f'⛔ WB 依赖未满足: {dep["id"]} → status={dep.get("status","?")}')
|
||||
sys.exit(1)
|
||||
print('✅ 所有 WB 依赖已满足')
|
||||
else:
|
||||
print('✅ 无 WB 依赖，可以启动')
|
||||
"
|
||||
|
||||
# Multica 依赖检查
|
||||
multica issue get <issue-id> --output json 2>/dev/null | python3 -c "
|
||||
import sys, json, subprocess
|
||||
issue = json.load(sys.stdin)
|
||||
parent_id = issue.get('parent_issue_id')
|
||||
if parent_id:
|
||||
result = subprocess.run(['multica', 'issue', 'get', parent_id, '--output', 'json'],
|
||||
capture_output=True, text=True)
|
||||
parent = json.loads(result.stdout)
|
||||
if parent.get('status') != 'done':
|
||||
print(f'⛔ MUL 父 Issue {parent["identifier"]} 未完成')
|
||||
sys.exit(1)
|
||||
print(f'✅ 父 Issue {parent["identifier"]} 已完成')
|
||||
else:
|
||||
print('✅ 无父 Issue 依赖，可以启动')
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛑 最大轮次限制
|
||||
|
||||
### 限制值：100 轮
|
||||
|
||||
- 接近 80%（80 轮）→ 预警
|
||||
- 达到上限 → 暂停，通知 COO + 创建者
|
||||
|
||||
### 跨平台轮次跟踪
|
||||
|
||||
- **WorkBoard**：通过 workboard_heartbeat 的 note 记录轮次
|
||||
- **Multica**：通过 issue comment 记录轮次进度
|
||||
- **待办文档**：在工作日志中记录
|
||||
|
||||
---
|
||||
|
||||
## 🫀 心跳执行清单
|
||||
|
||||
### 每次心跳必须检查
|
||||
|
||||
1. ✅ **全任务源检查**：WorkBoard + Multica + 待办文档
|
||||
2. ✅ 进行中任务超时检测（跨平台）
|
||||
3. ✅ 依赖检查
|
||||
4. ✅ 轮次计数器更新
|
||||
5. ✅ PRD 进度检查
|
||||
6. ✅ 需求变更跟踪
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 全局关键规则
|
||||
|
||||
1. **心跳不打断对话** — 用户正在对话时延后执行
|
||||
2. **非紧急事项延后汇报** — 等下一轮心跳或用户询问
|
||||
3. **发现任务立即执行，不得请示**（任何来源）
|
||||
4. **超时任务按自动恢复流程处理**（跨平台）
|
||||
5. **依赖未满足不启动**
|
||||
6. **达到轮次上限自动暂停**
|
||||
7. **避免任务遗漏** — 三源必须全部检查，缺一不可
|
||||
|
||||
|
||||
---
|
||||
|
||||
> 基于 BIZ-24 v1.1 模板生成 | 沈路明（productmanager）专用配置
|
||||
@@ -1,234 +0,0 @@
|
||||
# HEARTBEAT.md - 胡蓉（projectmanager）的心跳配置
|
||||
|
||||
> 模板版本：v1.1 (BIZ-24) | 分类：开发 Agent
|
||||
> OpenClaw Agent ID: `projectmanager` | Multica Agent UUID: `d877b8c3-b230-4073-b3f7-80e148cfdb71`
|
||||
|
||||
---
|
||||
|
||||
## 📋 全任务源统一监控（每次心跳必检）
|
||||
|
||||
> **核心原则：发现任何来源的任务都必须立即执行，不得遗漏。**
|
||||
|
||||
### 三源检查
|
||||
|
||||
#### 第一优先级：OpenClaw WorkBoard 卡片
|
||||
|
||||
```bash
|
||||
# 检查 WorkBoard 中分配给我的待办卡片
|
||||
openclaw workboard list --json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
data = json.load(sys.stdin)
|
||||
my_cards = [c for c in data.get('cards', [])
|
||||
if c.get('agentId') == 'projectmanager' and c.get('status') == 'todo']
|
||||
for c in my_cards:
|
||||
print(f'WORKBOARD TODO: {c["id"][:8]} [priority={c.get("priority","?")}] {c["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
#### 第二优先级：Multica Issues
|
||||
|
||||
```bash
|
||||
# 检查 Multica 中分配给我的待办 Issue
|
||||
multica issue list --assignee-id d877b8c3-b230-4073-b3f7-80e148cfdb71 --status todo --output json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
data = json.load(sys.stdin)
|
||||
for issue in data:
|
||||
print(f'MULTICA TODO: {issue["identifier"]} [{issue.get("priority","?")}] {issue["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
#### 第三优先级：待办文档
|
||||
|
||||
```bash
|
||||
# 检查工作区待办文档
|
||||
grep -n '\[ \]' TODO.md AGENTS.md 2>/dev/null || echo "无待办文档中未完成项"
|
||||
```
|
||||
|
||||
### 三源合并决策
|
||||
|
||||
```
|
||||
心跳开始
|
||||
↓
|
||||
检查 WorkBoard 待办卡片（agentId=projectmanager）
|
||||
↓
|
||||
检查 Multica Issues 待办（assignee=d877b8c3-b230-4073-b3f7-80e148cfdb71）
|
||||
↓
|
||||
检查待办文档
|
||||
↓
|
||||
合并去重 → 按优先级排序 → 依次执行
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 禁止请示规则（最高优先级，自动执行）
|
||||
|
||||
> **核心规则：发现分配给自己的任务 → 立即执行，不得向用户请示！**
|
||||
> 心跳是后台自动行为，用户在大多数时候并不在线，请示会导致任务卡死。
|
||||
|
||||
### 执行流程（严格执行，无需确认）
|
||||
|
||||
1. **三源检查待办** — WorkBoard + Multica + 待办文档
|
||||
2. **立即执行，不得请示** — 发现待办后直接执行
|
||||
3. **检查进行中任务** — 确认认领的任务状态
|
||||
4. **完成任务** — 通过对应平台汇报结果
|
||||
|
||||
### ⚠️ 绝对禁止行为
|
||||
|
||||
- ❌ 不得问"要不要做这个任务"
|
||||
- ❌ 不得等用户确认再执行
|
||||
- ❌ 不得以"需要更多信息"为由拒绝执行
|
||||
|
||||
---
|
||||
|
||||
## ⏱️ 超时检测规则
|
||||
|
||||
### 心跳频率：15 分钟
|
||||
|
||||
每次心跳跨平台执行以下检测：
|
||||
|
||||
1. 检查 WorkBoard 进行中任务的更新时间
|
||||
2. 检查 Multica 进行中 issues 的更新时间
|
||||
3. 超过 30 分钟无进展 → 标记为"疑似超时"
|
||||
4. 疑似超时 → 追加一次完整心跳尝试推进
|
||||
5. 确认超时 → 进入自动恢复流程
|
||||
|
||||
### 跨平台超时检测脚本
|
||||
|
||||
```bash
|
||||
# WorkBoard 超时检测
|
||||
echo "=== WorkBoard 超时检测 ==="
|
||||
openclaw workboard list --json 2>/dev/null | python3 -c "
|
||||
import sys, json, time
|
||||
data = json.load(sys.stdin)
|
||||
inprogress = [c for c in data.get('cards', []) if c.get('status') == 'in_progress']
|
||||
now = time.time()
|
||||
for c in inprogress:
|
||||
updated = c.get('updated_at', '')
|
||||
if updated:
|
||||
age = now - time.mktime(time.strptime(updated[:19], '%Y-%m-%dT%H:%M:%S'))
|
||||
if age > 1800:
|
||||
print(f'⏰ WB TIMEOUT: {c["id"][:8]} [{c.get("agentId","?")}] {c["title"]}')
|
||||
"
|
||||
|
||||
echo ""
|
||||
echo "=== Multica 超时检测 ==="
|
||||
multica issue list --status in_progress --output json 2>/dev/null | python3 -c "
|
||||
import sys, json, time
|
||||
data = json.load(sys.stdin)
|
||||
now = time.time()
|
||||
for issue in data:
|
||||
updated = issue.get('updated_at', '')
|
||||
if updated:
|
||||
age = now - time.mktime(time.strptime(updated[:19], '%Y-%m-%dT%H:%M:%S'))
|
||||
if age > 1800:
|
||||
print(f'⏰ MUL TIMEOUT: {issue["identifier"]} [{issue.get("assignee_id","?")[:12]}] {issue["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 自动恢复规则
|
||||
|
||||
### 触发条件
|
||||
|
||||
- 超 45 分钟无进展 → 自动重新调度
|
||||
|
||||
### 恢复操作（按平台）
|
||||
|
||||
| 平台 | 操作 |
|
||||
|------|------|
|
||||
| WorkBoard | 添加评论 → release claim → 通知 COO + 创建者 |
|
||||
| Multica | 添加评论 → status=blocked → 通知 COO + 创建者 |
|
||||
| 待办文档 | 标注超时 → 转为卡片（可选） |
|
||||
|
||||
---
|
||||
|
||||
## 🔗 依赖检查前置规则
|
||||
|
||||
### 强制检查流程
|
||||
|
||||
1. 认领任务前，读取依赖字段（depends_on / parent_issue_id）
|
||||
2. 逐一检查每个依赖任务的状态
|
||||
3. 依赖未满足 → 不认领（保持 todo）
|
||||
4. 超过等待阈值（2h）→ 通知依赖任务执行者
|
||||
|
||||
### 双平台依赖检查
|
||||
|
||||
```bash
|
||||
# WorkBoard 依赖检查
|
||||
openclaw workboard read <card-id> --json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
card = json.load(sys.stdin)
|
||||
deps = card.get('dependsOn', [])
|
||||
if deps:
|
||||
for dep in deps:
|
||||
if dep.get('status') != 'done':
|
||||
print(f'⛔ WB 依赖未满足: {dep["id"]} → status={dep.get("status","?")}')
|
||||
sys.exit(1)
|
||||
print('✅ 所有 WB 依赖已满足')
|
||||
else:
|
||||
print('✅ 无 WB 依赖，可以启动')
|
||||
"
|
||||
|
||||
# Multica 依赖检查
|
||||
multica issue get <issue-id> --output json 2>/dev/null | python3 -c "
|
||||
import sys, json, subprocess
|
||||
issue = json.load(sys.stdin)
|
||||
parent_id = issue.get('parent_issue_id')
|
||||
if parent_id:
|
||||
result = subprocess.run(['multica', 'issue', 'get', parent_id, '--output', 'json'],
|
||||
capture_output=True, text=True)
|
||||
parent = json.loads(result.stdout)
|
||||
if parent.get('status') != 'done':
|
||||
print(f'⛔ MUL 父 Issue {parent["identifier"]} 未完成')
|
||||
sys.exit(1)
|
||||
print(f'✅ 父 Issue {parent["identifier"]} 已完成')
|
||||
else:
|
||||
print('✅ 无父 Issue 依赖，可以启动')
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛑 最大轮次限制
|
||||
|
||||
### 限制值：100 轮
|
||||
|
||||
- 接近 80%（80 轮）→ 预警
|
||||
- 达到上限 → 暂停，通知 COO + 创建者
|
||||
|
||||
### 跨平台轮次跟踪
|
||||
|
||||
- **WorkBoard**：通过 workboard_heartbeat 的 note 记录轮次
|
||||
- **Multica**：通过 issue comment 记录轮次进度
|
||||
- **待办文档**：在工作日志中记录
|
||||
|
||||
---
|
||||
|
||||
## 🫀 心跳执行清单
|
||||
|
||||
### 每次心跳必须检查
|
||||
|
||||
1. ✅ **全任务源检查**：WorkBoard + Multica + 待办文档
|
||||
2. ✅ 进行中任务超时检测（跨平台）
|
||||
3. ✅ 依赖检查
|
||||
4. ✅ 轮次计数器更新
|
||||
5. ✅ 项目进度检查
|
||||
6. ✅ 依赖项完成状态
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 全局关键规则
|
||||
|
||||
1. **心跳不打断对话** — 用户正在对话时延后执行
|
||||
2. **非紧急事项延后汇报** — 等下一轮心跳或用户询问
|
||||
3. **发现任务立即执行，不得请示**（任何来源）
|
||||
4. **超时任务按自动恢复流程处理**（跨平台）
|
||||
5. **依赖未满足不启动**
|
||||
6. **达到轮次上限自动暂停**
|
||||
7. **避免任务遗漏** — 三源必须全部检查，缺一不可
|
||||
|
||||
|
||||
---
|
||||
|
||||
> 基于 BIZ-24 v1.1 模板生成 | 胡蓉（projectmanager）专用配置
|
||||
@@ -1,235 +0,0 @@
|
||||
# HEARTBEAT.md - 刘诗妮（secretary）的心跳配置
|
||||
|
||||
> 模板版本：v1.1 (BIZ-24) | 分类：高频 Agent
|
||||
> OpenClaw Agent ID: `secretary` | Multica Agent UUID: `b024fcdc-30ff-420d-b289-498041466e1b`
|
||||
|
||||
---
|
||||
|
||||
## 📋 全任务源统一监控（每次心跳必检）
|
||||
|
||||
> **核心原则：发现任何来源的任务都必须立即执行，不得遗漏。**
|
||||
|
||||
### 三源检查
|
||||
|
||||
#### 第一优先级：OpenClaw WorkBoard 卡片
|
||||
|
||||
```bash
|
||||
# 检查 WorkBoard 中分配给我的待办卡片
|
||||
openclaw workboard list --json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
data = json.load(sys.stdin)
|
||||
my_cards = [c for c in data.get('cards', [])
|
||||
if c.get('agentId') == 'secretary' and c.get('status') == 'todo']
|
||||
for c in my_cards:
|
||||
print(f'WORKBOARD TODO: {c["id"][:8]} [priority={c.get("priority","?")}] {c["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
#### 第二优先级：Multica Issues
|
||||
|
||||
```bash
|
||||
# 检查 Multica 中分配给我的待办 Issue
|
||||
multica issue list --assignee-id b024fcdc-30ff-420d-b289-498041466e1b --status todo --output json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
data = json.load(sys.stdin)
|
||||
for issue in data:
|
||||
print(f'MULTICA TODO: {issue["identifier"]} [{issue.get("priority","?")}] {issue["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
#### 第三优先级：待办文档
|
||||
|
||||
```bash
|
||||
# 检查工作区待办文档
|
||||
grep -n '\[ \]' TODO.md AGENTS.md 2>/dev/null || echo "无待办文档中未完成项"
|
||||
```
|
||||
|
||||
### 三源合并决策
|
||||
|
||||
```
|
||||
心跳开始
|
||||
↓
|
||||
检查 WorkBoard 待办卡片（agentId=secretary）
|
||||
↓
|
||||
检查 Multica Issues 待办（assignee=b024fcdc-30ff-420d-b289-498041466e1b）
|
||||
↓
|
||||
检查待办文档
|
||||
↓
|
||||
合并去重 → 按优先级排序 → 依次执行
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 禁止请示规则（最高优先级，自动执行）
|
||||
|
||||
> **核心规则：发现分配给自己的任务 → 立即执行，不得向用户请示！**
|
||||
> 心跳是后台自动行为，用户在大多数时候并不在线，请示会导致任务卡死。
|
||||
|
||||
### 执行流程（严格执行，无需确认）
|
||||
|
||||
1. **三源检查待办** — WorkBoard + Multica + 待办文档
|
||||
2. **立即执行，不得请示** — 发现待办后直接执行
|
||||
3. **检查进行中任务** — 确认认领的任务状态
|
||||
4. **完成任务** — 通过对应平台汇报结果
|
||||
|
||||
### ⚠️ 绝对禁止行为
|
||||
|
||||
- ❌ 不得问"要不要做这个任务"
|
||||
- ❌ 不得等用户确认再执行
|
||||
- ❌ 不得以"需要更多信息"为由拒绝执行
|
||||
|
||||
---
|
||||
|
||||
## ⏱️ 超时检测规则
|
||||
|
||||
### 心跳频率：10 分钟
|
||||
|
||||
每次心跳跨平台执行以下检测：
|
||||
|
||||
1. 检查 WorkBoard 进行中任务的更新时间
|
||||
2. 检查 Multica 进行中 issues 的更新时间
|
||||
3. 超过 20 分钟无进展 → 标记为"疑似超时"
|
||||
4. 疑似超时 → 追加一次完整心跳尝试推进
|
||||
5. 确认超时 → 进入自动恢复流程
|
||||
|
||||
### 跨平台超时检测脚本
|
||||
|
||||
```bash
|
||||
# WorkBoard 超时检测
|
||||
echo "=== WorkBoard 超时检测 ==="
|
||||
openclaw workboard list --json 2>/dev/null | python3 -c "
|
||||
import sys, json, time
|
||||
data = json.load(sys.stdin)
|
||||
inprogress = [c for c in data.get('cards', []) if c.get('status') == 'in_progress']
|
||||
now = time.time()
|
||||
for c in inprogress:
|
||||
updated = c.get('updated_at', '')
|
||||
if updated:
|
||||
age = now - time.mktime(time.strptime(updated[:19], '%Y-%m-%dT%H:%M:%S'))
|
||||
if age > 1200:
|
||||
print(f'⏰ WB TIMEOUT: {c["id"][:8]} [{c.get("agentId","?")}] {c["title"]}')
|
||||
"
|
||||
|
||||
echo ""
|
||||
echo "=== Multica 超时检测 ==="
|
||||
multica issue list --status in_progress --output json 2>/dev/null | python3 -c "
|
||||
import sys, json, time
|
||||
data = json.load(sys.stdin)
|
||||
now = time.time()
|
||||
for issue in data:
|
||||
updated = issue.get('updated_at', '')
|
||||
if updated:
|
||||
age = now - time.mktime(time.strptime(updated[:19], '%Y-%m-%dT%H:%M:%S'))
|
||||
if age > 1200:
|
||||
print(f'⏰ MUL TIMEOUT: {issue["identifier"]} [{issue.get("assignee_id","?")[:12]}] {issue["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 自动恢复规则
|
||||
|
||||
### 触发条件
|
||||
|
||||
- 超 30 分钟无进展 → 自动重新调度
|
||||
|
||||
### 恢复操作（按平台）
|
||||
|
||||
| 平台 | 操作 |
|
||||
|------|------|
|
||||
| WorkBoard | 添加评论 → release claim → 通知 COO |
|
||||
| Multica | 添加评论 → status=blocked → 通知 COO |
|
||||
| 待办文档 | 标注超时 → 转为卡片（可选） |
|
||||
|
||||
---
|
||||
|
||||
## 🔗 依赖检查前置规则
|
||||
|
||||
### 强制检查流程
|
||||
|
||||
1. 认领任务前，读取依赖字段（depends_on / parent_issue_id）
|
||||
2. 逐一检查每个依赖任务的状态
|
||||
3. 依赖未满足 → 不认领（保持 todo）
|
||||
4. 超过等待阈值（1h）→ 通知依赖任务执行者
|
||||
|
||||
### 双平台依赖检查
|
||||
|
||||
```bash
|
||||
# WorkBoard 依赖检查
|
||||
openclaw workboard read <card-id> --json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
card = json.load(sys.stdin)
|
||||
deps = card.get('dependsOn', [])
|
||||
if deps:
|
||||
for dep in deps:
|
||||
if dep.get('status') != 'done':
|
||||
print(f'⛔ WB 依赖未满足: {dep["id"]} → status={dep.get("status","?")}')
|
||||
sys.exit(1)
|
||||
print('✅ 所有 WB 依赖已满足')
|
||||
else:
|
||||
print('✅ 无 WB 依赖，可以启动')
|
||||
"
|
||||
|
||||
# Multica 依赖检查
|
||||
multica issue get <issue-id> --output json 2>/dev/null | python3 -c "
|
||||
import sys, json, subprocess
|
||||
issue = json.load(sys.stdin)
|
||||
parent_id = issue.get('parent_issue_id')
|
||||
if parent_id:
|
||||
result = subprocess.run(['multica', 'issue', 'get', parent_id, '--output', 'json'],
|
||||
capture_output=True, text=True)
|
||||
parent = json.loads(result.stdout)
|
||||
if parent.get('status') != 'done':
|
||||
print(f'⛔ MUL 父 Issue {parent["identifier"]} 未完成')
|
||||
sys.exit(1)
|
||||
print(f'✅ 父 Issue {parent["identifier"]} 已完成')
|
||||
else:
|
||||
print('✅ 无父 Issue 依赖，可以启动')
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛑 最大轮次限制
|
||||
|
||||
### 限制值：50 轮
|
||||
|
||||
- 接近 80%（40 轮）→ 预警
|
||||
- 达到上限 → 暂停，通知 COO
|
||||
|
||||
### 跨平台轮次跟踪
|
||||
|
||||
- **WorkBoard**：通过 workboard_heartbeat 的 note 记录轮次
|
||||
- **Multica**：通过 issue comment 记录轮次进度
|
||||
- **待办文档**：在工作日志中记录
|
||||
|
||||
---
|
||||
|
||||
## 🫀 心跳执行清单
|
||||
|
||||
### 每次心跳必须检查
|
||||
|
||||
1. ✅ **全任务源检查**：WorkBoard + Multica + 待办文档
|
||||
2. ✅ 进行中任务超时检测（跨平台）
|
||||
3. ✅ 依赖检查
|
||||
4. ✅ 轮次计数器更新
|
||||
5. ✅ 全局任务积压巡检
|
||||
6. ✅ 业务入口检查
|
||||
7. ✅ 各 Agent 状态巡检
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 全局关键规则
|
||||
|
||||
1. **心跳不打断对话** — 用户正在对话时延后执行
|
||||
2. **非紧急事项延后汇报** — 等下一轮心跳或用户询问
|
||||
3. **发现任务立即执行，不得请示**（任何来源）
|
||||
4. **超时任务按自动恢复流程处理**（跨平台）
|
||||
5. **依赖未满足不启动**
|
||||
6. **达到轮次上限自动暂停**
|
||||
7. **避免任务遗漏** — 三源必须全部检查，缺一不可
|
||||
|
||||
|
||||
---
|
||||
|
||||
> 基于 BIZ-24 v1.1 模板生成 | 刘诗妮（secretary）专用配置
|
||||
@@ -1,234 +0,0 @@
|
||||
# HEARTBEAT.md - 陆云帆（taobaospecialist）的心跳配置
|
||||
|
||||
> 模板版本：v1.1 (BIZ-24) | 分类：业务 Agent
|
||||
> OpenClaw Agent ID: `taobaospecialist` | Multica Agent UUID: `e0f62d8f-9568-4f41-8ad4-b73d79a163a7`
|
||||
|
||||
---
|
||||
|
||||
## 📋 全任务源统一监控（每次心跳必检）
|
||||
|
||||
> **核心原则：发现任何来源的任务都必须立即执行，不得遗漏。**
|
||||
|
||||
### 三源检查
|
||||
|
||||
#### 第一优先级：OpenClaw WorkBoard 卡片
|
||||
|
||||
```bash
|
||||
# 检查 WorkBoard 中分配给我的待办卡片
|
||||
openclaw workboard list --json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
data = json.load(sys.stdin)
|
||||
my_cards = [c for c in data.get('cards', [])
|
||||
if c.get('agentId') == 'taobaospecialist' and c.get('status') == 'todo']
|
||||
for c in my_cards:
|
||||
print(f'WORKBOARD TODO: {c["id"][:8]} [priority={c.get("priority","?")}] {c["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
#### 第二优先级：Multica Issues
|
||||
|
||||
```bash
|
||||
# 检查 Multica 中分配给我的待办 Issue
|
||||
multica issue list --assignee-id e0f62d8f-9568-4f41-8ad4-b73d79a163a7 --status todo --output json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
data = json.load(sys.stdin)
|
||||
for issue in data:
|
||||
print(f'MULTICA TODO: {issue["identifier"]} [{issue.get("priority","?")}] {issue["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
#### 第三优先级：待办文档
|
||||
|
||||
```bash
|
||||
# 检查工作区待办文档
|
||||
grep -n '\[ \]' TODO.md AGENTS.md 2>/dev/null || echo "无待办文档中未完成项"
|
||||
```
|
||||
|
||||
### 三源合并决策
|
||||
|
||||
```
|
||||
心跳开始
|
||||
↓
|
||||
检查 WorkBoard 待办卡片（agentId=taobaospecialist）
|
||||
↓
|
||||
检查 Multica Issues 待办（assignee=e0f62d8f-9568-4f41-8ad4-b73d79a163a7）
|
||||
↓
|
||||
检查待办文档
|
||||
↓
|
||||
合并去重 → 按优先级排序 → 依次执行
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 禁止请示规则（最高优先级，自动执行）
|
||||
|
||||
> **核心规则：发现分配给自己的任务 → 立即执行，不得向用户请示！**
|
||||
> 心跳是后台自动行为，用户在大多数时候并不在线，请示会导致任务卡死。
|
||||
|
||||
### 执行流程（严格执行，无需确认）
|
||||
|
||||
1. **三源检查待办** — WorkBoard + Multica + 待办文档
|
||||
2. **立即执行，不得请示** — 发现待办后直接执行
|
||||
3. **检查进行中任务** — 确认认领的任务状态
|
||||
4. **完成任务** — 通过对应平台汇报结果
|
||||
|
||||
### ⚠️ 绝对禁止行为
|
||||
|
||||
- ❌ 不得问"要不要做这个任务"
|
||||
- ❌ 不得等用户确认再执行
|
||||
- ❌ 不得以"需要更多信息"为由拒绝执行
|
||||
|
||||
---
|
||||
|
||||
## ⏱️ 超时检测规则
|
||||
|
||||
### 心跳频率：15 分钟
|
||||
|
||||
每次心跳跨平台执行以下检测：
|
||||
|
||||
1. 检查 WorkBoard 进行中任务的更新时间
|
||||
2. 检查 Multica 进行中 issues 的更新时间
|
||||
3. 超过 30 分钟无进展 → 标记为"疑似超时"
|
||||
4. 疑似超时 → 追加一次完整心跳尝试推进
|
||||
5. 确认超时 → 进入自动恢复流程
|
||||
|
||||
### 跨平台超时检测脚本
|
||||
|
||||
```bash
|
||||
# WorkBoard 超时检测
|
||||
echo "=== WorkBoard 超时检测 ==="
|
||||
openclaw workboard list --json 2>/dev/null | python3 -c "
|
||||
import sys, json, time
|
||||
data = json.load(sys.stdin)
|
||||
inprogress = [c for c in data.get('cards', []) if c.get('status') == 'in_progress']
|
||||
now = time.time()
|
||||
for c in inprogress:
|
||||
updated = c.get('updated_at', '')
|
||||
if updated:
|
||||
age = now - time.mktime(time.strptime(updated[:19], '%Y-%m-%dT%H:%M:%S'))
|
||||
if age > 1800:
|
||||
print(f'⏰ WB TIMEOUT: {c["id"][:8]} [{c.get("agentId","?")}] {c["title"]}')
|
||||
"
|
||||
|
||||
echo ""
|
||||
echo "=== Multica 超时检测 ==="
|
||||
multica issue list --status in_progress --output json 2>/dev/null | python3 -c "
|
||||
import sys, json, time
|
||||
data = json.load(sys.stdin)
|
||||
now = time.time()
|
||||
for issue in data:
|
||||
updated = issue.get('updated_at', '')
|
||||
if updated:
|
||||
age = now - time.mktime(time.strptime(updated[:19], '%Y-%m-%dT%H:%M:%S'))
|
||||
if age > 1800:
|
||||
print(f'⏰ MUL TIMEOUT: {issue["identifier"]} [{issue.get("assignee_id","?")[:12]}] {issue["title"]}')
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 自动恢复规则
|
||||
|
||||
### 触发条件
|
||||
|
||||
- 超 45 分钟无进展 → 自动重新调度
|
||||
|
||||
### 恢复操作（按平台）
|
||||
|
||||
| 平台 | 操作 |
|
||||
|------|------|
|
||||
| WorkBoard | 添加评论 → release claim → 通知 创建者 |
|
||||
| Multica | 添加评论 → status=blocked → 通知 创建者 |
|
||||
| 待办文档 | 标注超时 → 转为卡片（可选） |
|
||||
|
||||
---
|
||||
|
||||
## 🔗 依赖检查前置规则
|
||||
|
||||
### 强制检查流程
|
||||
|
||||
1. 认领任务前，读取依赖字段（depends_on / parent_issue_id）
|
||||
2. 逐一检查每个依赖任务的状态
|
||||
3. 依赖未满足 → 不认领（保持 todo）
|
||||
4. 超过等待阈值（2h）→ 通知依赖任务执行者
|
||||
|
||||
### 双平台依赖检查
|
||||
|
||||
```bash
|
||||
# WorkBoard 依赖检查
|
||||
openclaw workboard read <card-id> --json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
card = json.load(sys.stdin)
|
||||
deps = card.get('dependsOn', [])
|
||||
if deps:
|
||||
for dep in deps:
|
||||
if dep.get('status') != 'done':
|
||||
print(f'⛔ WB 依赖未满足: {dep["id"]} → status={dep.get("status","?")}')
|
||||
sys.exit(1)
|
||||
print('✅ 所有 WB 依赖已满足')
|
||||
else:
|
||||
print('✅ 无 WB 依赖，可以启动')
|
||||
"
|
||||
|
||||
# Multica 依赖检查
|
||||
multica issue get <issue-id> --output json 2>/dev/null | python3 -c "
|
||||
import sys, json, subprocess
|
||||
issue = json.load(sys.stdin)
|
||||
parent_id = issue.get('parent_issue_id')
|
||||
if parent_id:
|
||||
result = subprocess.run(['multica', 'issue', 'get', parent_id, '--output', 'json'],
|
||||
capture_output=True, text=True)
|
||||
parent = json.loads(result.stdout)
|
||||
if parent.get('status') != 'done':
|
||||
print(f'⛔ MUL 父 Issue {parent["identifier"]} 未完成')
|
||||
sys.exit(1)
|
||||
print(f'✅ 父 Issue {parent["identifier"]} 已完成')
|
||||
else:
|
||||
print('✅ 无父 Issue 依赖，可以启动')
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛑 最大轮次限制
|
||||
|
||||
### 限制值：30 轮
|
||||
|
||||
- 接近 80%（24 轮）→ 预警
|
||||
- 达到上限 → 暂停，通知 创建者
|
||||
|
||||
### 跨平台轮次跟踪
|
||||
|
||||
- **WorkBoard**：通过 workboard_heartbeat 的 note 记录轮次
|
||||
- **Multica**：通过 issue comment 记录轮次进度
|
||||
- **待办文档**：在工作日志中记录
|
||||
|
||||
---
|
||||
|
||||
## 🫀 心跳执行清单
|
||||
|
||||
### 每次心跳必须检查
|
||||
|
||||
1. ✅ **全任务源检查**：WorkBoard + Multica + 待办文档
|
||||
2. ✅ 进行中任务超时检测（跨平台）
|
||||
3. ✅ 依赖检查
|
||||
4. ✅ 轮次计数器更新
|
||||
5. ✅ 淘宝店铺运营指标
|
||||
6. ✅ 竞品动态跟踪
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 全局关键规则
|
||||
|
||||
1. **心跳不打断对话** — 用户正在对话时延后执行
|
||||
2. **非紧急事项延后汇报** — 等下一轮心跳或用户询问
|
||||
3. **发现任务立即执行，不得请示**（任何来源）
|
||||
4. **超时任务按自动恢复流程处理**（跨平台）
|
||||
5. **依赖未满足不启动**
|
||||
6. **达到轮次上限自动暂停**
|
||||
7. **避免任务遗漏** — 三源必须全部检查，缺一不可
|
||||
|
||||
|
||||
---
|
||||
|
||||
> 基于 BIZ-24 v1.1 模板生成 | 陆云帆（taobaospecialist）专用配置
|
||||
@@ -1,130 +0,0 @@
|
||||
# Agent 知识库集成指南
|
||||
|
||||
> **版本**: v1.0
|
||||
> **任务**: BIZ-19 (BIZ-14-4)
|
||||
> **日期**: 2026-06-22
|
||||
> **作者**: COO (陆怀瑾)
|
||||
> **状态**: 已实施
|
||||
|
||||
---
|
||||
|
||||
## 一、集成概述
|
||||
|
||||
### 1.1 设计原则
|
||||
|
||||
**「引用代替填塞」**: 不把知识内容直接塞进 Agent 配置文件，而是添加 "如何查询知识库" 的指引。Agent 在需要时主动检索，保持配置文件轻量和可维护。
|
||||
|
||||
### 1.2 核心工具
|
||||
|
||||
| 工具 | 用途 | 适用场景 |
|
||||
|------|------|----------|
|
||||
| `wiki_search` | 模糊搜索知识库 | "有没有关于 X 的文档" |
|
||||
| `wiki_get` | 精确读取页面 | "打开 X 页面" |
|
||||
| `wiki_lint` | 知识库质量检查 | "知识库健康度如何" |
|
||||
| `wiki_status` | 系统状态检查 | "知识库是否可用" |
|
||||
| `wiki_apply` | 写入/更新知识库 | "将 X 发现写入知识库" |
|
||||
|
||||
---
|
||||
|
||||
## 二、Agent 集成清单
|
||||
|
||||
### 2.1 已完成集成的 Agent（15 个）
|
||||
|
||||
| # | Agent | 角色 | TOOLS.md 更新状态 | 触发场景数 |
|
||||
|---|-------|------|-------------------|------------|
|
||||
| 1 | secretary | 刘诗妮 - 业务入口 | ✅ | 4 |
|
||||
| 2 | coo | 陆怀瑾 - 运营总监 | ✅ | 5 |
|
||||
| 3 | projectmanager | 胡蓉 - 项目经理 | ✅ | 4 |
|
||||
| 4 | architect | 梁思筑 - 架构师 | ✅ | 4 |
|
||||
| 5 | costcodev | 徐聪 - 全栈开发 | ✅ | 4 |
|
||||
| 6 | designer | 苏绘锦 - UI/UX 设计 | ✅ | 3 |
|
||||
| 7 | taobaospecialist | 陆云帆 - 淘宝运营 | ✅ | 4 |
|
||||
| 8 | contentspecialist | 文墨言 - 内容文案 | ✅ | 4 |
|
||||
| 9 | mediaspecialist | 钟帧韵 - 视频制作 | ✅ | 3 |
|
||||
| 10 | cvexpert | 程伯予 - 求职助理 | ✅ | 3 |
|
||||
| 11 | marketanalysis | 顾析策 - 市场分析 | ✅ | 4 |
|
||||
| 12 | lawyer | 苏慎 - 法务顾问 | ✅ | 4 |
|
||||
| 13 | opengineer | 严维序 - 运维部署 | ✅ | 4 |
|
||||
| 14 | productmanager | 沈路明 - 产品经理 | ✅ | 4 |
|
||||
| 15 | main | 入口路由 | ✅ | 2 |
|
||||
|
||||
### 2.2 集成内容
|
||||
|
||||
每个 Agent 的 TOOLS.md 新增了以下内容：
|
||||
|
||||
1. **知识库查询指引** — 引导 Agent 查看完整检索指南
|
||||
2. **角色特定触发条件** — 该 Agent 何时应查询知识库
|
||||
3. **查询工具速查** — `wiki_search` / `wiki_get` / `wiki_lint` 基本用法
|
||||
4. **角色特定查询示例** — 1-2 个典型查询语句
|
||||
5. **无结果时处理流程** — 知识缺口上报机制
|
||||
|
||||
---
|
||||
|
||||
## 三、查询触发条件设计
|
||||
|
||||
### 3.1 通用触发条件（所有 Agent 适用）
|
||||
|
||||
| 场景 | 触发动作 |
|
||||
|------|----------|
|
||||
| 接受新任务时 | 先查知识库中是否有相关文档/SOP |
|
||||
| 遇到不确定信息时 | 先查知识库再作决策 |
|
||||
| 需要跨领域协作时 | 查其他 Agent 的职能和知识 |
|
||||
| 发现新知识时 | 考虑是否需写入知识库 |
|
||||
|
||||
### 3.2 角色特定触发条件（按 Agent 定制）
|
||||
|
||||
见各 Agent TOOLS.md 中的「知识库查询 → 触发条件」部分。
|
||||
|
||||
---
|
||||
|
||||
## 四、知识缺口上报机制
|
||||
|
||||
### 4.1 上报流程
|
||||
|
||||
```
|
||||
Agent 查询知识库 → 无结果 → 尝试同义词/相关词 → 仍无结果 →
|
||||
→ 记录知识缺口 → 写入 memory/ 日志 →
|
||||
→ 下次心跳/汇报时通知 architect 或对应领域 Agent
|
||||
```
|
||||
|
||||
### 4.2 上报格式
|
||||
|
||||
见 `docs/agent-kb-retrieval-guide.md` 第五节。
|
||||
|
||||
---
|
||||
|
||||
## 五、质量保证
|
||||
|
||||
### 5.1 集成测试方案
|
||||
|
||||
对每个 Agent 至少执行 1 次典型查询场景测试：
|
||||
|
||||
1. 验证 `wiki_search` 可被正确调用
|
||||
2. 验证返回结果格式正确
|
||||
3. 验证无结果时的降级路径
|
||||
|
||||
### 5.2 集成测试结果
|
||||
|
||||
| Agent | 测试查询 | 结果 | 备注 |
|
||||
|-------|----------|------|------|
|
||||
| 通用 | `wiki_search(query="服务器")` | ✅ | wiki_search 正常 |
|
||||
|
||||
*注：知识库当前为初始状态（0 sources, 0 entities, 0 concepts, 0 syntheses, 10 reports），搜索结果取决于内容填充进度。工具链已验证可用。*
|
||||
|
||||
---
|
||||
|
||||
## 六、后续计划
|
||||
|
||||
1. **知识内容填充**: 待 BIZ-14-3 交付后，各 Agent 按角色写入初始知识内容
|
||||
2. **定期质量检查**: COO 每周运行 `wiki_lint()` 检查知识库健康度
|
||||
3. **查询效果评估**: 运行 1 个月后统计各 Agent 知识库查询频率和命中率
|
||||
4. **持续优化**: 根据使用反馈调整触发条件和查询示例
|
||||
|
||||
---
|
||||
|
||||
## 附录：相关文档
|
||||
|
||||
- `docs/agent-kb-retrieval-guide.md` — 知识库检索工具完整指南
|
||||
- `docs/知识查询最佳实践.md` — 查询最佳实践和反模式
|
||||
- `docs/wiki-toolchain-test-report.md` — Wiki 工具链测试报告 (BIZ-14-2)
|
||||
- 各 Agent TOOLS.md — 角色特定查询指引
|
||||
@@ -0,0 +1,401 @@
|
||||
# BIZ-26 限流器使用文档
|
||||
|
||||
> 模块：`scripts/rate_limiter.py`
|
||||
> 测试：`scripts/test_rate_limiter.py`
|
||||
> 实现日期：2026-06-23
|
||||
> 作者：徐聪（costcodev）
|
||||
|
||||
---
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
本模块实现了 BIZ-13 运行稳定性保障方案中的 API 限流优化功能：
|
||||
|
||||
1. **NVIDIA 网关专用令牌桶限流器**：40 RPM 上限，防止触发 NVIDIA 网关 API 429 错误
|
||||
2. **四级优先级队列**：紧急 > 高 > 正常 > 低
|
||||
3. **智能降级策略**：高优先级等待，低优先级切备用模型
|
||||
4. **缓存管理器**：按数据类型设置不同 TTL
|
||||
5. **COO 统一轮询**：减少重复请求
|
||||
6. **指数退避重试**：自动处理临时失败
|
||||
|
||||
---
|
||||
|
||||
## 二、适用范围（已按要求收窄）
|
||||
|
||||
**令牌桶限流器只对 NVIDIA 网关 API 生效。**
|
||||
|
||||
识别规则：
|
||||
- `nvidia`、`nvidia-gateway`、`nvidiavx18088980513/...` → 进入 40 RPM 令牌桶
|
||||
- `volcengine-plan/...`、`siliconflow/...`、`deepseek/...` → 不进入令牌桶，不受该限流器影响
|
||||
- 未知网关默认不限制，避免误伤非 NVIDIA 通道
|
||||
|
||||
调用方应显式传入 `gateway` 或 `model`，例如：
|
||||
|
||||
```python
|
||||
# 走 NVIDIA 网关：限流
|
||||
scheduler.submit(payload=data, gateway="nvidia", priority=Priority.NORMAL, callback=handler)
|
||||
scheduler.submit(payload=data, model="nvidiavx18088980513/deepseek-ai/deepseek-v4-pro", callback=handler)
|
||||
|
||||
# 走其他网关：不限流
|
||||
scheduler.submit(payload=data, model="volcengine-plan/ark-code-latest", callback=handler)
|
||||
scheduler.submit(payload=data, model="siliconflow/Qwen/Qwen3", callback=handler)
|
||||
scheduler.submit(payload=data, model="deepseek/deepseek-chat", callback=handler)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、快速开始
|
||||
|
||||
### 2.1 基本用法
|
||||
|
||||
```python
|
||||
from scripts.rate_limiter import RequestScheduler, Priority
|
||||
|
||||
# 创建调度器（40 RPM）
|
||||
scheduler = RequestScheduler(rate=40/60, capacity=40)
|
||||
scheduler.start()
|
||||
|
||||
# 提交请求
|
||||
def my_callback(data):
|
||||
# 实际 API 调用逻辑
|
||||
return process_data(data)
|
||||
|
||||
request_id = scheduler.submit(
|
||||
payload={"task": "process_workboard"},
|
||||
priority=Priority.NORMAL,
|
||||
callback=my_callback
|
||||
)
|
||||
|
||||
# 等待完成后关闭
|
||||
time.sleep(5)
|
||||
scheduler.stop()
|
||||
```
|
||||
|
||||
### 2.2 优先级示例
|
||||
|
||||
```python
|
||||
# 紧急任务（Vincent 直接下达）
|
||||
scheduler.submit(payload=data, priority=Priority.URGENT, callback=handler)
|
||||
|
||||
# 阻塞性任务（依赖下游完成）
|
||||
scheduler.submit(payload=data, priority=Priority.HIGH, callback=handler)
|
||||
|
||||
# 常规任务
|
||||
scheduler.submit(payload=data, priority=Priority.NORMAL, callback=handler)
|
||||
|
||||
# 后台优化任务
|
||||
scheduler.submit(payload=data, priority=Priority.LOW, callback=handler)
|
||||
```
|
||||
|
||||
### 2.3 缓存使用
|
||||
|
||||
```python
|
||||
from scripts.rate_limiter import CacheManager
|
||||
|
||||
cache = CacheManager()
|
||||
|
||||
# 缓存 WorkBoard 结果（TTL 5 分钟）
|
||||
cache.set("workboard", "todo_list", result_data)
|
||||
|
||||
# 读取缓存
|
||||
cached = cache.get("workboard", "todo_list")
|
||||
if cached is None:
|
||||
# 缓存未命中，重新查询
|
||||
result = query_workboard()
|
||||
cache.set("workboard", "todo_list", result)
|
||||
|
||||
# 查看缓存统计
|
||||
stats = cache.get_stats()
|
||||
print(f"缓存条目：{stats['total_entries']}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、API 参考
|
||||
|
||||
### 3.1 TokenBucket（令牌桶）
|
||||
|
||||
```python
|
||||
bucket = TokenBucket(rate=40/60, capacity=40)
|
||||
|
||||
# 尝试消费令牌（立即返回）
|
||||
if bucket.consume():
|
||||
send_request()
|
||||
else:
|
||||
# 令牌不足，等待或降级
|
||||
pass
|
||||
|
||||
# 等待令牌（阻塞直到获取或超时）
|
||||
got_token = bucket.wait_for_token(timeout=5.0)
|
||||
|
||||
# 查看状态
|
||||
status = bucket.get_status()
|
||||
# 返回：{"tokens": 35.5, "capacity": 40, "rate_per_minute": 40.0, ...}
|
||||
```
|
||||
|
||||
### 3.2 RequestScheduler（请求调度器）
|
||||
|
||||
```python
|
||||
scheduler = RequestScheduler(
|
||||
rate=40/60, # 令牌生成速率（个/秒）
|
||||
capacity=40, # 桶容量
|
||||
enable_cache=True # 启用缓存
|
||||
)
|
||||
|
||||
# 启动工作线程
|
||||
scheduler.start()
|
||||
|
||||
# 提交异步请求
|
||||
request_id = scheduler.submit(
|
||||
payload={"task": "data"},
|
||||
priority=Priority.NORMAL,
|
||||
callback=my_handler,
|
||||
fallback_model="deepseek-v4-pro"
|
||||
)
|
||||
|
||||
# 提交同步请求（阻塞直到完成）
|
||||
result = scheduler.submit_sync(
|
||||
payload={"task": "data"},
|
||||
priority=Priority.URGENT,
|
||||
timeout=10.0
|
||||
)
|
||||
|
||||
# 查看状态
|
||||
status = scheduler.get_status()
|
||||
|
||||
# 停止调度器
|
||||
scheduler.stop()
|
||||
```
|
||||
|
||||
### 3.3 CacheManager（缓存管理器）
|
||||
|
||||
```python
|
||||
cache = CacheManager()
|
||||
|
||||
# 设置缓存（自动 TTL）
|
||||
cache.set("workboard", query_key, value) # 5 分钟
|
||||
cache.set("config", "agent_list", agents) # 1 小时
|
||||
cache.set("knowledge", "api_docs", docs) # 1 天
|
||||
|
||||
# 自定义 TTL
|
||||
cache.set("custom", key, value, ttl=600) # 10 分钟
|
||||
|
||||
# 读取缓存
|
||||
value = cache.get("workboard", query_key)
|
||||
|
||||
# 删除缓存
|
||||
cache.delete("workboard", query_key)
|
||||
|
||||
# 清理过期缓存
|
||||
cleaned = cache.clear_expired()
|
||||
|
||||
# 查看统计
|
||||
stats = cache.get_stats()
|
||||
```
|
||||
|
||||
### 3.4 retry_with_backoff（重试装饰器）
|
||||
|
||||
```python
|
||||
from rate_limiter import retry_with_backoff
|
||||
|
||||
@retry_with_backoff(
|
||||
max_retries=3, # 最多重试 3 次
|
||||
base_delay=1.0, # 基础延迟 1 秒
|
||||
exponential_base=2, # 指数底数
|
||||
jitter=True, # 添加随机抖动
|
||||
exceptions=(RateLimitError, NetworkError)
|
||||
)
|
||||
def call_api():
|
||||
return requests.get(url)
|
||||
```
|
||||
|
||||
### 3.5 CoordinatedPoller（统一轮询器）
|
||||
|
||||
```python
|
||||
from rate_limiter import CoordinatedPoller
|
||||
|
||||
# 创建轮询器（15 分钟轮询一次）
|
||||
poller = CoordinatedPoller(scheduler, poll_interval=15*60)
|
||||
|
||||
# 订阅轮询结果
|
||||
def on_new_data(result):
|
||||
broadcast_to_agents(result)
|
||||
|
||||
poller.subscribe(on_new_data)
|
||||
|
||||
# 启动轮询
|
||||
poller.start()
|
||||
|
||||
# 停止轮询
|
||||
poller.stop()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、缓存策略
|
||||
|
||||
| 数据类型 | TTL | 说明 |
|
||||
|----------|-----|------|
|
||||
| `workboard` | 5 分钟 | WorkBoard 卡片状态，高频变化 |
|
||||
| `config` | 1 小时 | Agent 配置、技能列表，低频变化 |
|
||||
| `knowledge` | 1 天 | 知识库内容，基本不变 |
|
||||
| `user` | 1 天 | 用户信息、权限配置 |
|
||||
|
||||
---
|
||||
|
||||
## 六、降级策略
|
||||
|
||||
### 5.1 令牌不足时的处理
|
||||
|
||||
| 优先级 | 策略 |
|
||||
|--------|------|
|
||||
| URGENT (1) | 无限等待，直到获取令牌 |
|
||||
| HIGH (2) | 无限等待，直到获取令牌 |
|
||||
| NORMAL (3) | 等待 2 秒，失败则放回队列稍后重试 |
|
||||
| LOW (4) | 等待 2 秒，失败则丢弃或切换到备用模型 |
|
||||
|
||||
### 5.2 模型降级链
|
||||
|
||||
```
|
||||
主模型 (qwen3.5-397b)
|
||||
↓ RPM 不足
|
||||
备用模型 (deepseek-v4-pro)
|
||||
↓ RPM 不足
|
||||
本地模型 或 等待
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 七、监控与调试
|
||||
|
||||
### 6.1 查看调度器状态
|
||||
|
||||
```python
|
||||
status = scheduler.get_status()
|
||||
print(f"队列大小：{status['queue_size']}")
|
||||
print(f"令牌数：{status['token_bucket']['tokens']}")
|
||||
print(f"已完成：{status['stats']['completed_requests']}")
|
||||
print(f"失败：{status['stats']['failed_requests']}")
|
||||
print(f"降级：{status['stats']['fallback_requests']}")
|
||||
```
|
||||
|
||||
### 6.2 查看缓存统计
|
||||
|
||||
```python
|
||||
stats = cache.get_stats()
|
||||
print(f"总条目：{stats['total_entries']}")
|
||||
print(f"有效条目：{stats['valid_entries']}")
|
||||
print(f"过期条目：{stats['expired_entries']}")
|
||||
print(f"按类别：{stats['by_category']}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 八、测试
|
||||
|
||||
运行测试套件：
|
||||
|
||||
```bash
|
||||
cd /home/vincent/.openclaw/workspace/costcodev/EnterpriseArchitect
|
||||
python3 scripts/test_rate_limiter.py
|
||||
```
|
||||
|
||||
测试覆盖：
|
||||
- ✅ 令牌桶限流
|
||||
- ✅ 缓存管理
|
||||
- ✅ 优先级队列
|
||||
- ✅ 重试装饰器
|
||||
- ✅ 统一轮询器
|
||||
- ✅ 压力测试（50 请求）
|
||||
|
||||
---
|
||||
|
||||
## 九、集成示例
|
||||
|
||||
### 8.1 与 Multica CLI 集成
|
||||
|
||||
```python
|
||||
import subprocess
|
||||
import json
|
||||
from rate_limiter import RequestScheduler, Priority, CacheManager
|
||||
|
||||
scheduler = RequestScheduler(rate=40/60, capacity=40)
|
||||
cache = CacheManager()
|
||||
scheduler.start()
|
||||
|
||||
def query_workboard():
|
||||
"""查询 WorkBoard（带缓存）"""
|
||||
# 先查缓存
|
||||
cached = cache.get("workboard", "all_cards")
|
||||
if cached:
|
||||
return cached
|
||||
|
||||
# 缓存未命中，调用 CLI
|
||||
result = subprocess.run(
|
||||
["multica", "workboard", "list", "--json"],
|
||||
capture_output=True,
|
||||
text=True
|
||||
)
|
||||
data = json.loads(result.stdout)
|
||||
|
||||
# 更新缓存
|
||||
cache.set("workboard", "all_cards", data)
|
||||
|
||||
return data
|
||||
|
||||
# 提交查询请求
|
||||
request_id = scheduler.submit(
|
||||
payload="query_workboard",
|
||||
priority=Priority.NORMAL,
|
||||
callback=lambda _: query_workboard()
|
||||
)
|
||||
```
|
||||
|
||||
### 8.2 Agent 心跳集成
|
||||
|
||||
```python
|
||||
# 在 Heartbeat 中统一使用限流器
|
||||
def heartbeat_check():
|
||||
# 通过调度器提交所有检查任务
|
||||
scheduler.submit(
|
||||
payload="check_workboard",
|
||||
priority=Priority.HIGH,
|
||||
callback=check_workboard
|
||||
)
|
||||
scheduler.submit(
|
||||
payload="check_multica",
|
||||
priority=Priority.HIGH,
|
||||
callback=check_multica_issues
|
||||
)
|
||||
scheduler.submit(
|
||||
payload="update_memory",
|
||||
priority=Priority.LOW,
|
||||
callback=update_memory_log
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 十、注意事项
|
||||
|
||||
1. **令牌速率配置**：根据实际 API 限制调整 `rate` 参数
|
||||
2. **缓存 TTL**：根据数据变化频率调整，避免过期数据
|
||||
3. **工作线程**：记得调用 `start()` 和 `stop()` 管理生命周期
|
||||
4. **异常处理**：回调函数中的异常会被捕获并记录，不会中断工作线程
|
||||
5. **线程安全**：所有组件都是线程安全的，可在多线程环境使用
|
||||
|
||||
---
|
||||
|
||||
## 十一、TODO
|
||||
|
||||
- [ ] 接入实际的 Multica CLI 调用
|
||||
- [ ] 添加 Prometheus 监控指标导出
|
||||
- [ ] 支持动态调整限流参数
|
||||
- [ ] 添加请求日志持久化
|
||||
- [ ] 支持多个模型池的自动切换
|
||||
|
||||
---
|
||||
|
||||
> 文档版本：v1.0
|
||||
> 最后更新：2026-06-23
|
||||
> 维护者：徐聪（costcodev）
|
||||
@@ -1,156 +0,0 @@
|
||||
# 知识查询最佳实践
|
||||
|
||||
> **版本**: v1.0
|
||||
> **任务**: BIZ-19 (BIZ-14-4)
|
||||
> **日期**: 2026-06-22
|
||||
|
||||
---
|
||||
|
||||
## 一、查询策略
|
||||
|
||||
### 1.1 渐进式检索原则
|
||||
|
||||
```
|
||||
先宽后窄 → 先模糊后精确 → 先搜索后读取
|
||||
```
|
||||
|
||||
**标准流程**：
|
||||
1. `wiki_search(query="关键词")` — 发现有哪些相关内容
|
||||
2. `wiki_get(lookup="匹配页面")` — 精确读取具体内容
|
||||
3. 如搜索结果过多（>10） → 收窄关键词重新搜索
|
||||
4. 如搜索结果与需求不相关 → 调整表述方式重新搜索
|
||||
|
||||
### 1.2 查询词构造技巧
|
||||
|
||||
#### DO ✅
|
||||
|
||||
| 技巧 | 示例 | 说明 |
|
||||
|------|------|------|
|
||||
| 用领域特定术语 | `wiki_search(query="nginx 反向代理")` | 专业词汇提升精确度 |
|
||||
| 用动词+对象 | `wiki_search(query="部署 Node.js")` | 明确查询意图 |
|
||||
| 用自然语言问题 | `wiki_search(query="如何配置 nginx logrotate")` | 适合语义检索 |
|
||||
| 用缩写和全称组合 | `wiki_search(query="CI/CD 持续集成")` | 覆盖不同表述 |
|
||||
| 分步搜索 | 先搜 "nginx"，再搜 "nginx 日志" | 逐步收窄范围 |
|
||||
|
||||
#### DON'T ❌
|
||||
|
||||
| 反模式 | 错误示例 | 问题 |
|
||||
|--------|----------|------|
|
||||
| 过于泛化的词 | `wiki_search(query="配置")` | 结果太多太杂 |
|
||||
| 过于具体的短语 | `wiki_search(query="192.168.1.99 端口 22 上的 nginx")` | 命中率低 |
|
||||
| 跳过搜索直接 guess 路径 | `wiki_get(lookup="随便猜的页面名")` | 大概率找不到 |
|
||||
| 一次加载超大页面 | `wiki_get(lookup="巨型文档")` | 超出上下文容量 |
|
||||
| 无结果后直接放弃 | 只搜一次就说"知识库没内容" | 可能是查询词不准确 |
|
||||
|
||||
---
|
||||
|
||||
## 二、结果处理
|
||||
|
||||
### 2.1 匹配结果数量处理
|
||||
|
||||
| 结果数 | 处理方式 |
|
||||
|--------|----------|
|
||||
| 0 | 尝试同义词/相关词 → qmd 搜索 → 上报知识缺口 |
|
||||
| 1-3 | 逐个 `wiki_get` 读取完整内容 |
|
||||
| 4-10 | 按评分排序，取前 3 个读取 |
|
||||
| 10+ | 收窄搜索词重新搜索 |
|
||||
|
||||
### 2.2 大页面分页读取
|
||||
|
||||
```bash
|
||||
# 超过 100 行的页面，分页读取
|
||||
wiki_get(lookup="长文档标题", fromLine=1, lineCount=50) # 第一部分
|
||||
wiki_get(lookup="长文档标题", fromLine=51, lineCount=50) # 第二部分
|
||||
```
|
||||
|
||||
### 2.3 信息来源交叉验证
|
||||
|
||||
当多个查询返回不同信息时：
|
||||
1. 检查页面更新时间（优先信任较新的）
|
||||
2. 交叉对比多个来源
|
||||
3. 如信息冲突 → 标记为"需确认"，汇报给 architect
|
||||
|
||||
---
|
||||
|
||||
## 三、知识缺口处理
|
||||
|
||||
### 3.1 判定标准
|
||||
|
||||
满足以下任一条件即报告知识缺口：
|
||||
- `wiki_search` 和 `qmd` 均无匹配
|
||||
- 搜索结果与需求明显不相关
|
||||
- 找到的文档内容已过时或不完整
|
||||
|
||||
### 3.2 上报模板
|
||||
|
||||
```
|
||||
【知识缺口 - YYYY-MM-DD】
|
||||
|
||||
- 查询 Agent: [Agent 名称]
|
||||
- 查询意图: [想了解什么]
|
||||
- 已尝试检索: [用过的搜索词, 换行列出]
|
||||
- 已使用工具: wiki_search / qmd
|
||||
- 期望内容: [知识库中应有什么]
|
||||
- 紧急程度: high / normal / low
|
||||
- 建议: [谁补充、什么内容]
|
||||
```
|
||||
|
||||
### 3.3 上报路径
|
||||
|
||||
| 缺口类型 | 上报目标 |
|
||||
|----------|----------|
|
||||
| 架构/技术 | architect (梁思筑) |
|
||||
| 业务/流程 | projectmanager (胡蓉) |
|
||||
| 法务/合规 | lawyer (苏慎) |
|
||||
| 市场/分析 | marketanalysis (顾析策) |
|
||||
| 通用/不确定 | COO (陆怀瑾) — 由 COO 分配 |
|
||||
|
||||
---
|
||||
|
||||
## 四、知识库写入准则
|
||||
|
||||
### 4.1 何时写入
|
||||
|
||||
- 完成重要决策后（如架构选型、策略调整）
|
||||
- 发现可复用的模板/清单
|
||||
- 完成深度分析后（市场报告、竞品分析）
|
||||
- 知识缺口被填补后
|
||||
|
||||
### 4.2 写入工具选择
|
||||
|
||||
| 场景 | 工具 |
|
||||
|------|------|
|
||||
| 创建新知识页面 | `wiki_apply(op="create_synthesis", ...)` |
|
||||
| 更新已有页面元数据 | `wiki_apply(op="update_metadata", ...)` |
|
||||
|
||||
### 4.3 不写入的内容
|
||||
|
||||
- 机密信息（密码、密钥、token）
|
||||
- 临时信息（当天的具体任务进度）
|
||||
- 已过时会被频繁更新的数据
|
||||
- 纯个人笔记（放 `memory/` 下）
|
||||
|
||||
---
|
||||
|
||||
## 五、定期维护
|
||||
|
||||
### 5.1 COO 每周检查清单
|
||||
|
||||
- [ ] 运行 `wiki_lint()` 检查质量
|
||||
- [ ] 统计各 Agent 知识库查询频率
|
||||
- [ ] 清理过时页面
|
||||
- [ ] 评估知识缺口数量和解决率
|
||||
- [ ] 输出知识库运营周报
|
||||
|
||||
### 5.2 Agent 自检清单
|
||||
|
||||
每次心跳时：
|
||||
- [ ] 上次查询的知识缺口是否已上报
|
||||
- [ ] 本轮工作中是否有应写入知识库的发现
|
||||
|
||||
---
|
||||
|
||||
## 附录
|
||||
|
||||
- `docs/agent-kb-retrieval-guide.md` — 工具使用完整指南
|
||||
- `docs/Agent 知识库集成指南.md` — 集成方案总览
|
||||
@@ -12,10 +12,8 @@
|
||||
| [产品/](产品/) | PRD、需求分析 | 沈路明 (productmanager) | — |
|
||||
| [技术/](技术/) | 开发规范、代码审查 | 徐聪 (costcodev) | — |
|
||||
| [设计/](设计/) | UI设计、品牌规范 | 苏绘锦 (designer) | — |
|
||||
| [运维/](运维/) | 部署流程、故障排查、服务器运维 | 严维序 (opengineer) | 3 |
|
||||
| [运营/](运营/) | 活动策划、数据分析 | 陆怀瑾 (coo) | — |
|
||||
| [行政/](行政/) | 合同、报销流程 | 刘诗妮 (secretary) | — |
|
||||
| [规范/](规范/) | 运维标准、安全基线、合规要求 | 严维序 (opengineer) | — |
|
||||
|
||||
## 知识条目格式
|
||||
|
||||
|
||||
@@ -5,9 +5,7 @@
|
||||
|
||||
## 知识范围
|
||||
|
||||
涵盖开发规范、代码审查、架构设计、技术选型等技术团队核心知识。
|
||||
|
||||
> ⚠️ 部署运维知识已迁移至 [运维/](../运维/) 领域。
|
||||
涵盖开发规范、代码审查、架构设计、部署运维、技术选型等技术团队知识。
|
||||
|
||||
## 条目清单
|
||||
|
||||
|
||||
@@ -1,25 +0,0 @@
|
||||
# 规范领域知识
|
||||
|
||||
**责任人**：严维序（opengineer）
|
||||
**审核人**：陆怀瑾（coo）
|
||||
|
||||
## 知识范围
|
||||
|
||||
涵盖运维规范、安全标准、合规要求等规范类知识条目，支撑团队标准化运作。
|
||||
|
||||
## 条目清单
|
||||
|
||||
| 文件名 | 说明 | 状态 |
|
||||
|--------|------|------|
|
||||
| [服务器运维标准_v1.0.md](../运维/服务器运维标准_v1.0.md) | 服务器巡检、监控、备份运维标准 | 见运维域 |
|
||||
|
||||
## 待建设
|
||||
|
||||
- 数据库运维标准
|
||||
- 安全审计基线
|
||||
- 数据合规处理流程
|
||||
|
||||
---
|
||||
|
||||
> 维护者：严维序（opengineer）
|
||||
> 最后更新：2026-06-24
|
||||
@@ -1,27 +0,0 @@
|
||||
# 运维领域知识
|
||||
|
||||
**责任人**：严维序（opengineer）
|
||||
**审核人**：陆怀瑾（coo）
|
||||
|
||||
## 知识范围
|
||||
|
||||
涵盖服务器运维、部署流程、故障排查、监控配置、安全保障等运维团队核心知识。
|
||||
|
||||
## 条目清单
|
||||
|
||||
| 文件名 | 说明 | 状态 |
|
||||
|--------|------|------|
|
||||
| [部署流程_v1.0.md](部署流程_v1.0.md) | 服务部署 SOP 与变更管理流程 | ✅ |
|
||||
| [故障排查手册_v1.0.md](故障排查手册_v1.0.md) | 常见故障定位与处置方案 | ✅ |
|
||||
| [服务器运维标准_v1.0.md](服务器运维标准_v1.0.md) | 服务器巡检、监控、备份运维标准 | 🆕 |
|
||||
|
||||
## 待建设
|
||||
|
||||
- 数据库运维指南
|
||||
- 安全加固检查清单
|
||||
- 灾备与应急恢复预案
|
||||
|
||||
---
|
||||
|
||||
> 维护者：严维序（opengineer）
|
||||
> 最后更新：2026-06-24
|
||||
@@ -1,274 +0,0 @@
|
||||
# 故障排查手册
|
||||
|
||||
## 元数据
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| **领域** | 运维 |
|
||||
| **责任人** | 严维序（opengineer） |
|
||||
| **版本** | v1.0 |
|
||||
| **创建日期** | 2026-06-24 |
|
||||
| **最后更新** | 2026-06-24 |
|
||||
| **标签** | 故障排查, 运维, 排障 |
|
||||
|
||||
## 概述
|
||||
|
||||
本手册汇总 BizWings 环境中常见的系统与服务故障定位方法和修复方案。覆盖 SSH 连接、Nginx、数据库、磁盘、Docker 等核心场景。
|
||||
|
||||
---
|
||||
|
||||
## 一、SSH 连接故障
|
||||
|
||||
### 1.1 连接超时
|
||||
|
||||
```bash
|
||||
# 诊断步骤
|
||||
ssh -vvv root@<ip> -p <port> # 查看详细连接日志
|
||||
ping <ip> # 检查网络连通性
|
||||
nmap <ip> -p <port> # 检查端口状态
|
||||
```
|
||||
|
||||
**常见原因**：
|
||||
- 目标服务器防火墙未开放端口
|
||||
- 源 IP 未加入白名单
|
||||
- 服务器负载过高，sshd 响应慢
|
||||
|
||||
**解决方案**：
|
||||
1. 检查服务器防火墙：`iptables -L -n` 或 `ufw status`
|
||||
2. 检查 sshd 是否运行：`systemctl status sshd`
|
||||
3. 检查负载：`top -n1 | head -5`
|
||||
|
||||
### 1.2 认证失败
|
||||
|
||||
```bash
|
||||
# 诊断步骤
|
||||
ssh -p <port> root@<ip> # 尝试密码登录
|
||||
# Permission denied (publickey,password) 提示
|
||||
```
|
||||
|
||||
**常见原因**：
|
||||
- 密码错误（检查 TOOLS.md 中记录）
|
||||
- SSH 密钥认证配置错误
|
||||
- `/etc/ssh/sshd_config` 中 `PasswordAuthentication no`
|
||||
|
||||
**解决方案**：
|
||||
1. 确认密码与 TOOLS.md 一致
|
||||
2. 检查 `sshd_config`：`grep PasswordAuthentication /etc/ssh/sshd_config`
|
||||
3. 临时允许密码登录：`sed -i 's/PasswordAuthentication no/PasswordAuthentication yes/' /etc/ssh/sshd_config && systemctl reload sshd`
|
||||
|
||||
---
|
||||
|
||||
## 二、Nginx 服务异常
|
||||
|
||||
### 2.1 Nginx 启动失败 / 卡在 activating
|
||||
|
||||
```bash
|
||||
# 诊断步骤
|
||||
systemctl status nginx # 查看状态
|
||||
journalctl -u nginx --no-pager -n 50 # 查看日志
|
||||
nginx -t # 配置语法检查
|
||||
```
|
||||
|
||||
**根因（经验）**：进程残留导致端口占用
|
||||
|
||||
```bash
|
||||
# 修复
|
||||
pkill -9 nginx # 强制清理残留进程
|
||||
sleep 2
|
||||
systemctl start nginx # 重新启动
|
||||
systemctl status nginx # 确认状态
|
||||
```
|
||||
|
||||
### 2.2 502 Bad Gateway
|
||||
|
||||
```bash
|
||||
# 诊断步骤
|
||||
curl -I http://localhost:<upstream-port> # 检查上游服务
|
||||
ss -tlnp | grep <upstream-port> # 检查端口监听
|
||||
systemctl status <upstream-service> # 检查上游进程
|
||||
```
|
||||
|
||||
**常见原因**：
|
||||
- 上游服务未启动或崩溃
|
||||
- 连接池耗尽
|
||||
|
||||
**解决方案**：
|
||||
1. 重启上游服务：`systemctl restart <service>`
|
||||
2. 检查 `upstream` 配置是否正确
|
||||
|
||||
### 2.3 日志轮转失败
|
||||
|
||||
```bash
|
||||
# 诊断步骤
|
||||
cat /var/log/nginx/error.log | head # 查看是否有日志无法写入
|
||||
ls -la /var/log/nginx/ # 查看日志文件
|
||||
/usr/sbin/logrotate -d /etc/logrotate.d/nginx # 测试 logrotate
|
||||
```
|
||||
|
||||
**修复方案**：
|
||||
```bash
|
||||
# 修改 /etc/logrotate.d/nginx 中的 postrotate 脚本
|
||||
# 将 invoke-rc.d nginx rotate 改为：
|
||||
postrotate
|
||||
systemctl reload nginx
|
||||
endscript
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、数据库连接故障
|
||||
|
||||
### 3.1 MySQL 连接失败
|
||||
|
||||
```bash
|
||||
# 诊断步骤
|
||||
mysql -h <host> -P <port> -u root -p # 测试连接
|
||||
telnet <host> <port> # 检查端口
|
||||
systemctl status mysql # 检查服务
|
||||
```
|
||||
|
||||
**常见原因**：
|
||||
- 服务未运行
|
||||
- 防火墙未放行 3306 端口
|
||||
- 用户权限 / host 限制
|
||||
- 连接数超限
|
||||
|
||||
**解决方案**：
|
||||
```bash
|
||||
# 检查连接数
|
||||
mysql -e "SHOW VARIABLES LIKE 'max_connections';"
|
||||
mysql -e "SHOW PROCESSLIST;"
|
||||
|
||||
# 检查用户权限
|
||||
mysql -e "SELECT user, host FROM mysql.user WHERE user='root';"
|
||||
```
|
||||
|
||||
### 3.2 MySQL 空间不足
|
||||
|
||||
```bash
|
||||
# 诊断
|
||||
df -h # 磁盘空间
|
||||
mysql -e "SELECT table_schema, ROUND(SUM(data_length+index_length)/1024/1024,2) AS size_mb FROM information_schema.tables GROUP BY table_schema ORDER BY size_mb DESC;"
|
||||
```
|
||||
|
||||
**解决方案**：
|
||||
- 清理过期 binlog：`PURGE BINARY LOGS BEFORE DATE_SUB(NOW(), INTERVAL 7 DAY);`
|
||||
- 清理临时表
|
||||
- 扩展磁盘
|
||||
|
||||
---
|
||||
|
||||
## 四、磁盘空间告警
|
||||
|
||||
### 4.1 诊断
|
||||
|
||||
```bash
|
||||
df -h # 查看各分区使用率
|
||||
du -sh /* 2>/dev/null | sort -rh | head -10 # 找到大文件目录
|
||||
find / -type f -size +100M -exec ls -lh {} \; 2>/dev/null # 大文件定位
|
||||
```
|
||||
|
||||
### 4.2 清理方案
|
||||
|
||||
```bash
|
||||
# Docker 日志和镜像清理
|
||||
docker system prune -af --volumes # 清理未使用的 Docker 资源
|
||||
|
||||
# 系统日志轮转
|
||||
journalctl --vacuum-time=7d # 清理 7 天前的 journal 日志
|
||||
|
||||
# 应用日志归档
|
||||
find /var/log -name "*.log" -mtime +30 -exec gzip {} \; # 压缩旧日志
|
||||
find /var/log -name "*.gz" -mtime +90 -delete # 删除 90 天前的压缩日志
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、Docker 容器异常
|
||||
|
||||
### 5.1 容器停止
|
||||
|
||||
```bash
|
||||
docker ps -a | grep <container> # 查看容器状态
|
||||
docker logs <container> --tail 50 # 查看最近日志
|
||||
```
|
||||
|
||||
**修复**：
|
||||
```bash
|
||||
docker start <container> # 手动启动
|
||||
docker compose -f <path> up -d # 使用 Compose 重启
|
||||
```
|
||||
|
||||
### 5.2 Docker API 无响应
|
||||
|
||||
```bash
|
||||
systemctl status docker # 检查 Docker 服务
|
||||
journalctl -u docker --no-pager -n 50 # 查看 Docker 日志
|
||||
```
|
||||
|
||||
**修复**：
|
||||
```bash
|
||||
systemctl restart docker # 重启 Docker 守护进程
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 六、系统进程故障
|
||||
|
||||
### 6.1 端口被占用
|
||||
|
||||
```bash
|
||||
ss -tlnp | grep <port> # 查看占用端口的进程
|
||||
fuser -k <port>/tcp # 强制释放端口
|
||||
```
|
||||
|
||||
### 6.2 systemd 服务异常
|
||||
|
||||
```bash
|
||||
systemctl status <service> # 检查状态
|
||||
journalctl -u <service> --no-pager -n 100 # 查看服务日志
|
||||
|
||||
# 常用修复
|
||||
systemctl daemon-reload # 重载 unit 文件
|
||||
systemctl restart <service> # 重启
|
||||
systemctl enable <service> # 设置开机自启
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 七、日志分析工具
|
||||
|
||||
### 7.1 常用命令
|
||||
|
||||
```bash
|
||||
# 实时日志跟踪
|
||||
tail -f /var/log/<app>/access.log
|
||||
|
||||
# 错误过滤
|
||||
grep -i "error\|exception\|failed" /var/log/<app>/app.log | tail -50
|
||||
|
||||
# 时间范围过滤
|
||||
awk '/2026-06-24 10:00/,/2026-06-24 11:00/' /var/log/<app>/app.log
|
||||
```
|
||||
|
||||
### 7.2 关键检查点
|
||||
|
||||
| 故障表现 | 优先检查 | 常见根因 |
|
||||
|----------|----------|----------|
|
||||
| 服务无响应 | systemctl status | 进程 OOM / 崩溃 |
|
||||
| API 返回错误 | 应用日志 + Nginx 日志 | 代码 bug / 上游依赖异常 |
|
||||
| 高延迟 | top + ss + 应用日志 | 资源争抢 / 死锁 |
|
||||
| 数据库异常 | MySQL error log | 慢查询 / 连接数超限 |
|
||||
|
||||
---
|
||||
|
||||
## 相关条目
|
||||
|
||||
- [部署流程_v1.0.md](部署流程_v1.0.md)
|
||||
- [服务器运维标准_v1.0.md](服务器运维标准_v1.0.md)
|
||||
|
||||
## 变更记录
|
||||
|
||||
| 日期 | 版本 | 变更说明 | 变更人 |
|
||||
|------|------|----------|--------|
|
||||
| 2026-06-24 | v1.0 | 初始创建 | 严维序 |
|
||||
@@ -1,177 +0,0 @@
|
||||
# 服务器运维标准
|
||||
|
||||
## 元数据
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| **领域** | 运维 |
|
||||
| **责任人** | 严维序（opengineer） |
|
||||
| **版本** | v1.0 |
|
||||
| **创建日期** | 2026-06-24 |
|
||||
| **最后更新** | 2026-06-24 |
|
||||
| **标签** | 运维, 监控, 巡检, 备份 |
|
||||
|
||||
## 概述
|
||||
|
||||
本文档定义 BizWings 团队所有服务器的日常运维标准，包括巡检频率、监控指标、备份策略和安全基线。适用于所有生产环境服务器（阿里云 / 家庭内网 / HP 服务器）。
|
||||
|
||||
---
|
||||
|
||||
## 一、服务器巡检标准
|
||||
|
||||
### 1.1 巡检频率
|
||||
|
||||
| 类型 | 频率 | 执行方式 |
|
||||
|------|------|----------|
|
||||
| 心跳自检 | 每 10 分钟 | openclaw 心跳自动巡检 |
|
||||
| 深度巡检 | 每日一次 | 手动执行 `python3 $SCRIPTS/heartbeat_helper.py opengineer` |
|
||||
| 全量巡检 | 每周一次 | 逐个检查全部服务器 |
|
||||
|
||||
### 1.2 巡检清单
|
||||
|
||||
#### 资源负载
|
||||
```bash
|
||||
# 磁盘使用率（警告 > 80%，严重 > 90%）
|
||||
df -h | grep -v tmpfs
|
||||
|
||||
# CPU 负载
|
||||
uptime
|
||||
|
||||
# 内存使用
|
||||
free -h
|
||||
|
||||
# 网络 IO
|
||||
sar -n DEV 1 3
|
||||
```
|
||||
|
||||
#### 服务状态
|
||||
```bash
|
||||
# 核心服务清单（按实际部署确认）
|
||||
systemctl status nginx mysql docker sshd
|
||||
|
||||
# Docker 容器健康
|
||||
docker ps | grep -c "Up"
|
||||
```
|
||||
|
||||
#### 日志异常
|
||||
```bash
|
||||
# 最近 10 分钟的错误日志
|
||||
journalctl --since "10 min ago" -p err --no-pager | tail -20
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二、监控指标定义
|
||||
|
||||
### 2.1 告警阈值
|
||||
|
||||
| 指标 | 警告 (WARN) | 严重 (CRIT) | 处理 |
|
||||
|------|-------------|-------------|------|
|
||||
| 磁盘使用率 | > 80% | > 90% | 清理日志 / 扩容 |
|
||||
| CPU 负载 (1min) | > 4.0 | > 8.0 | 检查异常进程 |
|
||||
| 内存使用率 | > 85% | > 95% | 检查 OOM 风险 |
|
||||
| 根分区 inode | > 80% | > 90% | 清理小文件 |
|
||||
| 服务进程 | 停止 | — | 重启服务 |
|
||||
| 端口监听 | 消失 | — | 检查服务状态 |
|
||||
| Docker 容器 | 非 Up | — | docker start / compose up |
|
||||
|
||||
### 2.2 日志监控
|
||||
|
||||
- 系统日志：`journalctl -p err` 重点关注
|
||||
- 应用日志：`error`, `exception`, `failed`, `timeout` 关键词监控
|
||||
- Nginx 日志：5xx 错误率 > 1% 时触发调查
|
||||
|
||||
---
|
||||
|
||||
## 三、备份策略
|
||||
|
||||
### 3.1 数据库备份
|
||||
|
||||
```bash
|
||||
# MySQL 全量备份（建议每日凌晨执行）
|
||||
mysqldump --all-databases --single-transaction --quick | gzip > /backup/db/all-$(date +%Y%m%d).sql.gz
|
||||
```
|
||||
|
||||
### 3.2 配置备份
|
||||
- 服务器配置文件：`/backup/conf/<server>/` 目录
|
||||
- 每次变更前执行：`cp <config> <config>.$(date +%Y%m%d-%H%M%S).bak`
|
||||
|
||||
### 3.3 Docker 数据备份
|
||||
```bash
|
||||
# 思源笔记备份（已配置每日 3:00）
|
||||
tar czf /backup/siyuan/siyuan-data-$(date +%Y%m%d).tar.gz -C <data-dir> .
|
||||
```
|
||||
|
||||
### 3.4 备份保留策略
|
||||
|
||||
| 类型 | 保留期限 |
|
||||
|------|----------|
|
||||
| 数据库全量备份 | 30 天 |
|
||||
| 配置备份 | 90 天 |
|
||||
| Docker 数据 | 7 天 |
|
||||
| 日志归档 | 90 天 |
|
||||
|
||||
---
|
||||
|
||||
## 四、变更管理标准
|
||||
|
||||
### 4.1 变更准入
|
||||
|
||||
- ✅ 每次变更前必须备份原始文件
|
||||
- ✅ 高危操作（防火墙、内核、数据库）必须保留回滚方案
|
||||
- ✅ 变更前评估影响范围
|
||||
- ✅ 变更后验证服务状态
|
||||
- ❌ 禁止在无备份的情况下直接修改生产配置
|
||||
- ❌ 禁止在高峰时段执行非紧急变更
|
||||
|
||||
### 4.2 变更分级
|
||||
|
||||
| 级别 | 示例 | 要求 |
|
||||
|------|------|------|
|
||||
| 低风险 | 普通应用更新 | 备份 → 部署 → 验证 |
|
||||
| 中风险 | 配置修改 | 备份 → 预演 → 部署 → 验证 |
|
||||
| 高风险 | 内核 / 防火墙 / 数据库 | 备份 → 预演 → 通知 → 部署 → 验证 → 监控 |
|
||||
|
||||
---
|
||||
|
||||
## 五、安全基线
|
||||
|
||||
### 5.1 基本要求
|
||||
|
||||
- [ ] SSH 禁止 root 密码登录（高风险服务器）
|
||||
- [ ] 防火墙最小权限原则
|
||||
- [ ] 非必要端口不对外开放
|
||||
- [ ] 定期更新系统安全补丁
|
||||
- [ ] 日志审计开启
|
||||
|
||||
### 5.2 密码管理
|
||||
|
||||
- 服务器密码统一记录在 TOOLS.md
|
||||
- 数据库密码统一管理
|
||||
- 禁止在代码中硬编码密码
|
||||
|
||||
---
|
||||
|
||||
## 六、服务器清单与分类
|
||||
|
||||
| 环境 | 服务器数 | 用途 | 巡检频率 |
|
||||
|------|----------|------|----------|
|
||||
| 阿里云生产 | 3 | 应用服务、数据库 | 每次心跳 |
|
||||
| 家庭内网生产 | 4 | 应用、数据库、PVE | 每次心跳 |
|
||||
| HP 测试 | 3 | 测试、NAS | 每日 |
|
||||
| 树莓派 | 1 | 辅助设备 | 每日 |
|
||||
|
||||
详细清单见 TOOLS.md「SSH/WinRM 服务器清单」
|
||||
|
||||
---
|
||||
|
||||
## 相关条目
|
||||
|
||||
- [部署流程_v1.0.md](部署流程_v1.0.md)
|
||||
- [故障排查手册_v1.0.md](故障排查手册_v1.0.md)
|
||||
|
||||
## 变更记录
|
||||
|
||||
| 日期 | 版本 | 变更说明 | 变更人 |
|
||||
|------|------|----------|--------|
|
||||
| 2026-06-24 | v1.0 | 初始创建 | 严维序 |
|
||||
@@ -1,202 +0,0 @@
|
||||
# 服务部署流程 SOP
|
||||
|
||||
## 元数据
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| **领域** | 运维 |
|
||||
| **责任人** | 严维序（opengineer） |
|
||||
| **版本** | v1.0 |
|
||||
| **创建日期** | 2026-06-24 |
|
||||
| **最后更新** | 2026-06-24 |
|
||||
| **标签** | 部署, 运维, SOP |
|
||||
|
||||
## 概述
|
||||
|
||||
本文档定义 BizWings 团队所有业务服务的部署流程标准，涵盖部署前检查、执行步骤、验证测试和回滚预案。适用于所有生产环境的代码部署与服务更新。
|
||||
|
||||
---
|
||||
|
||||
## 一、部署前置检查
|
||||
|
||||
### 1.1 代码准备
|
||||
|
||||
- [ ] 代码已合并到目标分支（main / release）
|
||||
- [ ] PR 已通过 Code Review 并合并
|
||||
- [ ] 本地或 CI 构建通过（编译无报错）
|
||||
- [ ] 版本号已更新（如有）
|
||||
|
||||
### 1.2 环境检查
|
||||
|
||||
- [ ] 目标服务器磁盘空间充足（> 剩余 20%）
|
||||
- [ ] CPU / 内存负载正常（< 80%）
|
||||
- [ ] 网络连通性：本机 → 目标服务器可达
|
||||
- [ ] 目标端口未被占用
|
||||
- [ ] 依赖服务（数据库 / 中间件）运行正常
|
||||
|
||||
### 1.3 备份准备
|
||||
|
||||
- [ ] **配置备份**：服务器配置文件备份到 `/backup/conf/` 目录
|
||||
- [ ] **数据库备份**：涉及数据库变更，先执行 `mysqldump` 全量备份
|
||||
- [ ] **当前版本标记**：记录当前运行版本号或 Git commit hash
|
||||
|
||||
---
|
||||
|
||||
## 二、部署执行步骤
|
||||
|
||||
### 2.1 文件分发
|
||||
|
||||
```bash
|
||||
# 标准部署（SSH + scp/rsync）
|
||||
scp -P <port> ./dist/app root@<server>:/opt/app/
|
||||
# 或使用 rsync 增量同步
|
||||
rsync -avz --delete -e "ssh -p <port>" ./dist/ root@<server>:/opt/app/
|
||||
```
|
||||
|
||||
### 2.2 服务更新
|
||||
|
||||
#### 方式 A：systemd 服务
|
||||
```bash
|
||||
# 1. 停止服务
|
||||
systemctl stop <service-name>
|
||||
|
||||
# 2. 备份旧版本（如有必要）
|
||||
mv /opt/app/<app> /opt/app/<app>.bak
|
||||
|
||||
# 3. 放置新版本
|
||||
cp /tmp/<app> /opt/app/<app>
|
||||
chmod +x /opt/app/<app>
|
||||
|
||||
# 4. 重启服务
|
||||
systemctl start <service-name>
|
||||
systemctl status <service-name>
|
||||
```
|
||||
|
||||
#### 方式 B：Docker 容器
|
||||
```bash
|
||||
# 1. 拉取新镜像
|
||||
docker pull <registry>/<image>:<tag>
|
||||
|
||||
# 2. 停止旧容器
|
||||
docker stop <container-name>
|
||||
docker rm <container-name>
|
||||
|
||||
# 3. 启动新容器
|
||||
docker run -d --name <container-name> \
|
||||
--restart unless-stopped \
|
||||
-p <host-port>:<container-port> \
|
||||
<registry>/<image>:<tag>
|
||||
```
|
||||
|
||||
#### 方式 C：Nginx 反向代理更新
|
||||
```bash
|
||||
# 更新上游配置后重载
|
||||
nginx -t # 语法检查
|
||||
systemctl reload nginx # 热重载
|
||||
```
|
||||
|
||||
### 2.3 配置变更
|
||||
|
||||
```bash
|
||||
# 1. 备份当前配置
|
||||
cp /etc/<app>/config.yml /etc/<app>/config.yml.$(date +%Y%m%d-%H%M%S)
|
||||
|
||||
# 2. 修改配置
|
||||
vim /etc/<app>/config.yml
|
||||
|
||||
# 3. 重启服务使配置生效
|
||||
systemctl restart <service-name>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、部署验证
|
||||
|
||||
### 3.1 连通性验证
|
||||
```bash
|
||||
# 服务端口监听确认
|
||||
ss -tlnp | grep <port>
|
||||
|
||||
# HTTP 服务健康检查
|
||||
curl -s -o /dev/null -w "%{http_code}" http://localhost:<port>/health
|
||||
# 预期返回：200
|
||||
```
|
||||
|
||||
### 3.2 功能验证
|
||||
|
||||
- [ ] API 基础功能运行正常
|
||||
- [ ] 日志无新增 ERROR 级别报错
|
||||
- [ ] 数据库连接正常
|
||||
- [ ] 前端页面（如有）可正常加载
|
||||
|
||||
### 3.3 监控确认
|
||||
|
||||
- [ ] Prometheus / Grafana 指标正常
|
||||
- [ ] 日志系统（如有）已捕获新日志
|
||||
- [ ] 告警规则未被触发
|
||||
|
||||
---
|
||||
|
||||
## 四、回滚方案
|
||||
|
||||
### 4.1 代码回滚
|
||||
```bash
|
||||
# Git 回滚到上一版本
|
||||
cd /opt/app/repo
|
||||
git revert HEAD --no-edit
|
||||
git push
|
||||
# 重新执行部署
|
||||
```
|
||||
|
||||
### 4.2 文件回滚
|
||||
```bash
|
||||
# 恢复备份文件
|
||||
mv /opt/app/<app>.bak /opt/app/<app>
|
||||
systemctl restart <service-name>
|
||||
```
|
||||
|
||||
### 4.3 数据库回滚
|
||||
```bash
|
||||
# 导入备份
|
||||
gunzip < /backup/db/<dbname>.$(date +%Y%m%d).sql.gz | mysql -u root -p<pass> <dbname>
|
||||
```
|
||||
|
||||
### 4.4 回滚确认
|
||||
- [ ] 旧版本服务运行正常
|
||||
- [ ] 端口监听确认
|
||||
- [ ] 用户无访问异常
|
||||
- [ ] 记录回滚原因到工作日志
|
||||
|
||||
---
|
||||
|
||||
## 五、部署后记录
|
||||
|
||||
### 5.1 必填信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| 部署时间 | YYYY-MM-DD HH:mm |
|
||||
| 部署人 | 严维序（opengineer） |
|
||||
| 部署内容 | [简要描述] |
|
||||
| 版本 | commit hash / tag |
|
||||
| 验证结果 | ✅/❌ 通过 |
|
||||
| 回滚情况 | 无需回滚 / 已回滚（原因） |
|
||||
|
||||
### 5.2 记录位置
|
||||
|
||||
- 工作日志：`memory/YYYY-MM-DD.md`
|
||||
- 任务记录：WorkBoard 相关卡片注释
|
||||
- 知识更新：如部署暴露流程问题，更新本文档
|
||||
|
||||
---
|
||||
|
||||
## 相关条目
|
||||
|
||||
- [故障排查手册_v1.0.md](故障排查手册_v1.0.md)
|
||||
- [服务器运维标准_v1.0.md](服务器运维标准_v1.0.md)
|
||||
|
||||
## 变更记录
|
||||
|
||||
| 日期 | 版本 | 变更说明 | 变更人 |
|
||||
|------|------|----------|--------|
|
||||
| 2026-06-24 | v1.0 | 初始创建 | 严维序 |
|
||||
@@ -1,50 +0,0 @@
|
||||
# Alertmanager 配置
|
||||
# 告警通知路由到 Feishu
|
||||
|
||||
global:
|
||||
resolve_timeout: 5m
|
||||
|
||||
route:
|
||||
receiver: "default"
|
||||
group_wait: 30s
|
||||
group_interval: 5m
|
||||
repeat_interval: 4h
|
||||
routes:
|
||||
# 严重告警 → 通知 Vincent
|
||||
- receiver: "vincent-critical"
|
||||
match:
|
||||
severity: critical
|
||||
repeat_interval: 2h
|
||||
continue: true
|
||||
|
||||
# 警告告警 → 通知 COO
|
||||
- receiver: "coo-warning"
|
||||
match:
|
||||
severity: warning
|
||||
repeat_interval: 4h
|
||||
|
||||
receivers:
|
||||
- name: "default"
|
||||
webhook_configs:
|
||||
- url: "http://host.docker.internal:9094/webhook"
|
||||
send_resolved: true
|
||||
|
||||
- name: "vincent-critical"
|
||||
webhook_configs:
|
||||
- url: "http://host.docker.internal:9094/webhook"
|
||||
send_resolved: true
|
||||
|
||||
- name: "coo-warning"
|
||||
webhook_configs:
|
||||
- url: "http://host.docker.internal:9094/webhook"
|
||||
send_resolved: true
|
||||
|
||||
# 抑制规则：严重告警自动抑制同源的警告
|
||||
inhibit_rules:
|
||||
- source_match:
|
||||
severity: critical
|
||||
target_match:
|
||||
severity: warning
|
||||
equal:
|
||||
- alertname
|
||||
- instance
|
||||
@@ -1,288 +0,0 @@
|
||||
{
|
||||
"title": "OpenClaw Agent Health Dashboard",
|
||||
"uid": "agent-health",
|
||||
"version": 1,
|
||||
"tags": ["openclaw", "agent", "monitoring"],
|
||||
"timezone": "browser",
|
||||
"editable": true,
|
||||
"refresh": "30s",
|
||||
"panels": [
|
||||
{
|
||||
"title": "系统资源概览",
|
||||
"type": "row",
|
||||
"gridPos": {"h": 1, "w": 24, "x": 0, "y": 0}
|
||||
},
|
||||
{
|
||||
"id": 1,
|
||||
"title": "CPU 使用率",
|
||||
"type": "gauge",
|
||||
"gridPos": {"h": 8, "w": 6, "x": 0, "y": 1},
|
||||
"targets": [
|
||||
{
|
||||
"expr": "100 - (avg by(instance) (rate(node_cpu_seconds_total{mode=\"idle\"}[5m])) * 100)",
|
||||
"legendFormat": "{{instance}}"
|
||||
}
|
||||
],
|
||||
"options": {
|
||||
"reduceOptions": {"calcs": ["lastNotNull"]},
|
||||
"showThresholdLabels": false,
|
||||
"showThresholdMarkers": true
|
||||
},
|
||||
"thresholds": [
|
||||
{"color": "green", "value": null},
|
||||
{"color": "yellow", "value": 70},
|
||||
{"color": "red", "value": 90}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"title": "内存使用率",
|
||||
"type": "gauge",
|
||||
"gridPos": {"h": 8, "w": 6, "x": 6, "y": 1},
|
||||
"targets": [
|
||||
{
|
||||
"expr": "(1 - (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)) * 100",
|
||||
"legendFormat": "{{instance}}"
|
||||
}
|
||||
],
|
||||
"options": {
|
||||
"reduceOptions": {"calcs": ["lastNotNull"]},
|
||||
"showThresholdLabels": false,
|
||||
"showThresholdMarkers": true
|
||||
},
|
||||
"thresholds": [
|
||||
{"color": "green", "value": null},
|
||||
{"color": "yellow", "value": 80},
|
||||
{"color": "red", "value": 95}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"title": "磁盘使用率",
|
||||
"type": "gauge",
|
||||
"gridPos": {"h": 8, "w": 6, "x": 12, "y": 1},
|
||||
"targets": [
|
||||
{
|
||||
"expr": "max by(instance) ((node_filesystem_size_bytes - node_filesystem_free_bytes) / node_filesystem_size_bytes * 100)",
|
||||
"legendFormat": "{{instance}}"
|
||||
}
|
||||
],
|
||||
"options": {
|
||||
"reduceOptions": {"calcs": ["lastNotNull"]},
|
||||
"showThresholdLabels": false,
|
||||
"showThresholdMarkers": true
|
||||
},
|
||||
"thresholds": [
|
||||
{"color": "green", "value": null},
|
||||
{"color": "yellow", "value": 80},
|
||||
{"color": "red", "value": 95}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"title": "系统负载",
|
||||
"type": "stat",
|
||||
"gridPos": {"h": 8, "w": 6, "x": 18, "y": 1},
|
||||
"targets": [
|
||||
{
|
||||
"expr": "node_load1",
|
||||
"legendFormat": "1min"
|
||||
},
|
||||
{
|
||||
"expr": "node_load5",
|
||||
"legendFormat": "5min"
|
||||
},
|
||||
{
|
||||
"expr": "node_load15",
|
||||
"legendFormat": "15min"
|
||||
}
|
||||
],
|
||||
"options": {
|
||||
"reduceOptions": {"calcs": ["lastNotNull"]},
|
||||
"colorMode": "background",
|
||||
"graphMode": "area",
|
||||
"justifyMode": "auto",
|
||||
"orientation": "horizontal",
|
||||
"textMode": "auto"
|
||||
}
|
||||
},
|
||||
{
|
||||
"title": "Agent 健康状态",
|
||||
"type": "row",
|
||||
"gridPos": {"h": 1, "w": 24, "x": 0, "y": 9}
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
"title": "Agent 心跳状态",
|
||||
"type": "table",
|
||||
"gridPos": {"h": 8, "w": 12, "x": 0, "y": 10},
|
||||
"targets": [
|
||||
{
|
||||
"expr": "agent_heartbeat_status",
|
||||
"legendFormat": "{{agent_label}}"
|
||||
}
|
||||
],
|
||||
"transformations": [
|
||||
{"id": "organize", "options": {"excludeByName": {}, "indexByName": {}, "renameByName": {"Value": "状态"}}}
|
||||
],
|
||||
"fieldConfig": {
|
||||
"defaults": {
|
||||
"custom": {
|
||||
"align": "center",
|
||||
"displayMode": "color-background"
|
||||
},
|
||||
"mappings": [
|
||||
{"type": "value", "options": {"0": {"color": "red", "text": "❌ 超时"}, "1": {"color": "green", "text": "✅ 正常"}}}
|
||||
],
|
||||
"thresholds": [{"color": "green", "value": null}]
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": 6,
|
||||
"title": "任务停滞时长",
|
||||
"type": "bargauge",
|
||||
"gridPos": {"h": 8, "w": 12, "x": 12, "y": 10},
|
||||
"targets": [
|
||||
{
|
||||
"expr": "agent_task_stagnation_seconds",
|
||||
"legendFormat": "{{agent_label}}"
|
||||
}
|
||||
],
|
||||
"options": {
|
||||
"orientation": "horizontal",
|
||||
"displayMode": "gradient",
|
||||
"showUnfilled": true
|
||||
},
|
||||
"fieldConfig": {
|
||||
"defaults": {
|
||||
"unit": "s",
|
||||
"thresholds": [
|
||||
{"color": "green", "value": null},
|
||||
{"color": "yellow", "value": 3600},
|
||||
{"color": "red", "value": 14400}
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": 7,
|
||||
"title": "待办任务数",
|
||||
"type": "stat",
|
||||
"gridPos": {"h": 4, "w": 6, "x": 0, "y": 18},
|
||||
"targets": [
|
||||
{
|
||||
"expr": "agent_workboard_pending",
|
||||
"legendFormat": "待办任务"
|
||||
}
|
||||
],
|
||||
"options": {
|
||||
"reduceOptions": {"calcs": ["lastNotNull"]},
|
||||
"colorMode": "background",
|
||||
"graphMode": "area",
|
||||
"textMode": "auto"
|
||||
},
|
||||
"thresholds": [
|
||||
{"color": "green", "value": null},
|
||||
{"color": "yellow", "value": 5},
|
||||
{"color": "red", "value": 10}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": 8,
|
||||
"title": "429 错误计数",
|
||||
"type": "stat",
|
||||
"gridPos": {"h": 4, "w": 6, "x": 6, "y": 18},
|
||||
"targets": [
|
||||
{
|
||||
"expr": "agent_429_error_rate",
|
||||
"legendFormat": "429 错误"
|
||||
}
|
||||
],
|
||||
"options": {
|
||||
"reduceOptions": {"calcs": ["lastNotNull"]},
|
||||
"colorMode": "background",
|
||||
"graphMode": "area",
|
||||
"textMode": "auto"
|
||||
},
|
||||
"thresholds": [
|
||||
{"color": "green", "value": null},
|
||||
{"color": "yellow", "value": 10},
|
||||
{"color": "red", "value": 50}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": 9,
|
||||
"title": "Prometheus 目标状态",
|
||||
"type": "table",
|
||||
"gridPos": {"h": 8, "w": 12, "x": 12, "y": 18},
|
||||
"targets": [
|
||||
{
|
||||
"expr": "up",
|
||||
"legendFormat": "{{job}} ({{instance}})"
|
||||
}
|
||||
],
|
||||
"fieldConfig": {
|
||||
"defaults": {
|
||||
"custom": {"align": "center", "displayMode": "color-background"},
|
||||
"mappings": [
|
||||
{"type": "value", "options": {"0": {"color": "red", "text": "❌ Down"}, "1": {"color": "green", "text": "✅ Up"}}}
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"title": "告警状态",
|
||||
"type": "row",
|
||||
"gridPos": {"h": 1, "w": 24, "x": 0, "y": 26}
|
||||
},
|
||||
{
|
||||
"id": 10,
|
||||
"title": "活跃告警",
|
||||
"type": "table",
|
||||
"gridPos": {"h": 8, "w": 24, "x": 0, "y": 27},
|
||||
"targets": [
|
||||
{
|
||||
"expr": "ALERTS{alertstate=\"firing\"}",
|
||||
"legendFormat": "{{alertname}}"
|
||||
}
|
||||
],
|
||||
"fieldConfig": {
|
||||
"defaults": {
|
||||
"custom": {"align": "left"},
|
||||
"mappings": [
|
||||
{"type": "value", "options": {"0": {"color": "green", "text": "已恢复"}, "1": {"color": "red", "text": "触发中"}}}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
],
|
||||
"schemaVersion": 38,
|
||||
"style": "dark",
|
||||
"tags": ["openclaw", "agent", "monitoring"],
|
||||
"templating": {
|
||||
"list": [
|
||||
{
|
||||
"name": "datasource",
|
||||
"type": "datasource",
|
||||
"query": "prometheus",
|
||||
"current": {"value": "Prometheus"}
|
||||
}
|
||||
]
|
||||
},
|
||||
"annotations": {
|
||||
"list": [
|
||||
{
|
||||
"name": "告警事件",
|
||||
"type": "dashboard",
|
||||
"builtIn": 1,
|
||||
"datasource": {"type": "prometheus", "uid": "PBFA97CFB590B2093"},
|
||||
"enable": true,
|
||||
"hide": true,
|
||||
"iconColor": "rgba(255, 96, 96, 1)",
|
||||
"expr": "ALERTS",
|
||||
"step": "60s"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -1,12 +0,0 @@
|
||||
apiVersion: 1
|
||||
|
||||
providers:
|
||||
- name: "Agent Health"
|
||||
orgId: 1
|
||||
folder: "OpenClaw"
|
||||
type: file
|
||||
disableDeletion: false
|
||||
editable: true
|
||||
updateIntervalSeconds: 10
|
||||
options:
|
||||
path: /etc/grafana/provisioning/dashboards
|
||||
@@ -1,42 +0,0 @@
|
||||
global:
|
||||
scrape_interval: 15s
|
||||
evaluation_interval: 15s
|
||||
|
||||
# Alertmanager 配置
|
||||
alerting:
|
||||
alertmanagers:
|
||||
- static_configs:
|
||||
- targets:
|
||||
- alertmanager:9093
|
||||
|
||||
# 规则文件
|
||||
rule_files:
|
||||
- "agent_alerts.yml"
|
||||
|
||||
# 抓取配置
|
||||
scrape_configs:
|
||||
# Prometheus 自监控
|
||||
- job_name: 'prometheus'
|
||||
static_configs:
|
||||
- targets: ['localhost:9090']
|
||||
|
||||
# Node Exporter - 系统指标
|
||||
- job_name: 'node-exporter'
|
||||
static_configs:
|
||||
- targets: ['node-exporter:9100']
|
||||
|
||||
# Agent Health Exporter - 自定义 Agent 监控指标
|
||||
- job_name: 'agent-health'
|
||||
scrape_interval: 30s
|
||||
static_configs:
|
||||
- targets: ['agent-exporter:9999']
|
||||
relabel_configs:
|
||||
- source_labels: [__address__]
|
||||
target_label: instance
|
||||
replacement: 'openclaw-agents'
|
||||
|
||||
# OpenClaw Gateway Metrics（待启用）
|
||||
# - job_name: 'openclaw-gateway'
|
||||
# metrics_path: '/metrics'
|
||||
# static_configs:
|
||||
# - targets: ['host.docker.internal:18789']
|
||||
@@ -1,92 +0,0 @@
|
||||
version: '3.8'
|
||||
|
||||
services:
|
||||
prometheus:
|
||||
image: m.daocloud.io/docker.io/prom/prometheus:v2.52.0
|
||||
container_name: prometheus
|
||||
ports:
|
||||
- "9090:9090"
|
||||
volumes:
|
||||
- ./config/prometheus.yml:/etc/prometheus/prometheus.yml
|
||||
- ./config/agent_alerts.yml:/etc/prometheus/agent_alerts.yml
|
||||
- ./data/prometheus:/prometheus
|
||||
extra_hosts:
|
||||
- "host.docker.internal:host-gateway"
|
||||
command:
|
||||
- '--config.file=/etc/prometheus/prometheus.yml'
|
||||
- '--storage.tsdb.path=/prometheus'
|
||||
- '--web.enable-lifecycle'
|
||||
restart: always
|
||||
networks:
|
||||
- monitoring
|
||||
|
||||
agent-exporter:
|
||||
image: m.daocloud.io/docker.io/python:3.11-slim
|
||||
container_name: agent-exporter
|
||||
ports:
|
||||
- "9999:9999"
|
||||
volumes:
|
||||
- ./scripts/agent_health_exporter.py:/app/exporter.py:ro
|
||||
command: python3 /app/exporter.py
|
||||
working_dir: /app
|
||||
restart: always
|
||||
networks:
|
||||
- monitoring
|
||||
|
||||
alertmanager:
|
||||
image: m.daocloud.io/docker.io/prom/alertmanager:v0.27.0
|
||||
container_name: alertmanager
|
||||
ports:
|
||||
- "9093:9093"
|
||||
volumes:
|
||||
- ./config/alertmanager.yml:/etc/alertmanager/alertmanager.yml
|
||||
- ./data/alertmanager:/alertmanager
|
||||
extra_hosts:
|
||||
- "host.docker.internal:host-gateway"
|
||||
command:
|
||||
- '--config.file=/etc/alertmanager/alertmanager.yml'
|
||||
- '--storage.path=/alertmanager'
|
||||
- '--web.listen-address=:9093'
|
||||
restart: always
|
||||
networks:
|
||||
- monitoring
|
||||
|
||||
grafana:
|
||||
image: m.daocloud.io/docker.io/grafana/grafana:11.0.0
|
||||
container_name: grafana
|
||||
ports:
|
||||
- "3001:3000"
|
||||
environment:
|
||||
- GF_SECURITY_ADMIN_USER=admin
|
||||
- GF_SECURITY_ADMIN_PASSWORD=***
|
||||
- GF_INSTALL_PLUGINS=grafana-clock-panel,grafana-piechart-panel
|
||||
volumes:
|
||||
- ./data/grafana:/var/lib/grafana
|
||||
- ./config/grafana/dashboards:/etc/grafana/provisioning/dashboards
|
||||
- ./config/grafana/datasources:/etc/grafana/provisioning/datasources
|
||||
restart: always
|
||||
networks:
|
||||
- monitoring
|
||||
depends_on:
|
||||
- prometheus
|
||||
|
||||
node-exporter:
|
||||
image: m.daocloud.io/docker.io/prom/node-exporter:v1.8.2
|
||||
container_name: node-exporter
|
||||
ports:
|
||||
- "9100:9100"
|
||||
volumes:
|
||||
- /proc:/host/proc:ro
|
||||
- /sys:/host/sys:ro
|
||||
- /:/rootfs:ro
|
||||
command:
|
||||
- '--path.procfs=/host/proc'
|
||||
- '--path.sysfs=/host/sys'
|
||||
- '--collector.filesystem.mount-points-exclude=^/(sys|proc|dev|host|etc)($|/)'
|
||||
restart: always
|
||||
networks:
|
||||
- monitoring
|
||||
|
||||
networks:
|
||||
monitoring:
|
||||
driver: bridge
|
||||
@@ -1,180 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
OpenClaw Agent Health Exporter v2.1
|
||||
采集 Agent 运行指标，暴露给 Prometheus 抓取
|
||||
|
||||
设计原则：
|
||||
- HTTP handler 不阻塞 - 后台线程异步采集
|
||||
- 采集失败不影响服务可用性
|
||||
- 使用缓存避免频繁外部调用
|
||||
"""
|
||||
|
||||
import http.server
|
||||
import json
|
||||
import os
|
||||
import sys
|
||||
import threading
|
||||
import time
|
||||
from datetime import datetime, timezone
|
||||
|
||||
# ============================================================
|
||||
# 指标存储（线程安全）
|
||||
# ============================================================
|
||||
|
||||
_metrics_lock = threading.Lock()
|
||||
_metrics = {
|
||||
"agent_task_stagnation_seconds": {},
|
||||
"agent_429_error_rate": {},
|
||||
"agent_response_time_seconds": {},
|
||||
"agent_heartbeat_status": {},
|
||||
"agent_workboard_pending": {},
|
||||
"http_requests_total": {},
|
||||
}
|
||||
|
||||
# 缓存
|
||||
_cache_updated = 0
|
||||
_CACHE_TTL = 60 # 缓存有效期秒
|
||||
|
||||
# Agent 列表
|
||||
AGENTS = {
|
||||
"opengineer": "严维序",
|
||||
"secretary": "刘诗妮",
|
||||
"projectmanager": "胡蓉",
|
||||
"productmanager": "沈路明",
|
||||
"architect": "梁思筑",
|
||||
"costcodev": "徐聪",
|
||||
"designer": "苏绘锦",
|
||||
"coo": "陆怀瑾",
|
||||
}
|
||||
|
||||
# ============================================================
|
||||
# 后台采集线程
|
||||
# ============================================================
|
||||
|
||||
def collect_metrics_background():
|
||||
"""后台采集指标（避免阻塞 HTTP 响应）"""
|
||||
global _cache_updated
|
||||
|
||||
with _metrics_lock:
|
||||
# 初始化静态指标
|
||||
for agent in AGENTS:
|
||||
_metrics["agent_heartbeat_status"][agent] = 1
|
||||
_metrics["agent_task_stagnation_seconds"][agent] = 0
|
||||
_metrics["agent_response_time_seconds"][agent] = 0
|
||||
|
||||
# 初始化 HTTP 计数器
|
||||
if ("200",) not in _metrics["http_requests_total"]:
|
||||
_metrics["http_requests_total"][("200",)] = 0
|
||||
|
||||
_cache_updated = time.time()
|
||||
|
||||
def generate_prometheus_metrics():
|
||||
"""生成 Prometheus 格式的指标文本（仅从内存读取，不阻塞）"""
|
||||
with _metrics_lock:
|
||||
lines = []
|
||||
|
||||
# Agent 任务停滞时长
|
||||
lines.append("# HELP agent_task_stagnation_seconds Agent task stagnation duration in seconds")
|
||||
lines.append("# TYPE agent_task_stagnation_seconds gauge")
|
||||
for agent, value in sorted(_metrics["agent_task_stagnation_seconds"].items()):
|
||||
agent_label = AGENTS.get(agent, agent)
|
||||
lines.append(f'agent_task_stagnation_seconds{{agent_name="{agent}",agent_label="{agent_label}"}} {value}')
|
||||
|
||||
# 429 错误率
|
||||
lines.append("# HELP agent_429_error_rate 429 error count")
|
||||
lines.append("# TYPE agent_429_error_rate gauge")
|
||||
for agent, value in sorted(_metrics["agent_429_error_rate"].items()):
|
||||
lines.append(f'agent_429_error_rate{{agent_name="{agent}"}} {value}')
|
||||
|
||||
# Agent 响应延迟
|
||||
lines.append("# HELP agent_response_time_seconds Agent response time in seconds")
|
||||
lines.append("# TYPE agent_response_time_seconds gauge")
|
||||
for agent, value in sorted(_metrics["agent_response_time_seconds"].items()):
|
||||
agent_label = AGENTS.get(agent, agent)
|
||||
lines.append(f'agent_response_time_seconds{{agent_name="{agent}",agent_label="{agent_label}"}} {value}')
|
||||
|
||||
# 心跳状态
|
||||
lines.append("# HELP agent_heartbeat_status Agent heartbeat status (1=healthy, 0=stale)")
|
||||
lines.append("# TYPE agent_heartbeat_status gauge")
|
||||
for agent, value in sorted(_metrics["agent_heartbeat_status"].items()):
|
||||
agent_label = AGENTS.get(agent, agent)
|
||||
lines.append(f'agent_heartbeat_status{{agent_name="{agent}",agent_label="{agent_label}"}} {value}')
|
||||
|
||||
# 待办任务数
|
||||
lines.append("# HELP agent_workboard_pending Pending workboard task count")
|
||||
lines.append("# TYPE agent_workboard_pending gauge")
|
||||
for key, value in sorted(_metrics["agent_workboard_pending"].items()):
|
||||
lines.append(f'agent_workboard_pending{{type="{key}"}} {value}')
|
||||
|
||||
# HTTP 请求计数
|
||||
lines.append("# HELP http_requests_total Total HTTP requests")
|
||||
lines.append("# TYPE http_requests_total counter")
|
||||
for key, value in sorted(_metrics["http_requests_total"].items()):
|
||||
status = key[0]
|
||||
lines.append(f'http_requests_total{{status="{status}"}} {value}')
|
||||
|
||||
return "\n".join(lines) + "\n"
|
||||
|
||||
# ============================================================
|
||||
# HTTP Handler（不阻塞）
|
||||
# ============================================================
|
||||
|
||||
class MetricsHandler(http.server.BaseHTTPRequestHandler):
|
||||
def do_GET(self):
|
||||
if self.path == "/metrics":
|
||||
# 只更新请求计数（轻量操作）
|
||||
with _metrics_lock:
|
||||
_metrics["http_requests_total"][("200",)] = \
|
||||
_metrics["http_requests_total"].get(("200",), 0) + 1
|
||||
|
||||
response = generate_prometheus_metrics().encode("utf-8")
|
||||
self.send_response(200)
|
||||
self.send_header("Content-Type", "text/plain; charset=utf-8")
|
||||
self.send_header("Content-Length", len(response))
|
||||
self.end_headers()
|
||||
self.wfile.write(response)
|
||||
|
||||
elif self.path == "/health":
|
||||
self.send_response(200)
|
||||
self.send_header("Content-Type", "application/json")
|
||||
response = json.dumps({
|
||||
"status": "ok",
|
||||
"cache_age": time.time() - _cache_updated,
|
||||
"timestamp": datetime.now(timezone.utc).isoformat()
|
||||
}).encode()
|
||||
self.send_header("Content-Length", len(response))
|
||||
self.end_headers()
|
||||
self.wfile.write(response)
|
||||
|
||||
else:
|
||||
self.send_response(404)
|
||||
self.end_headers()
|
||||
|
||||
def log_message(self, format, *args):
|
||||
pass
|
||||
|
||||
# ============================================================
|
||||
# 启动
|
||||
# ============================================================
|
||||
|
||||
if __name__ == "__main__":
|
||||
port = int(os.environ.get("EXPORTER_PORT", 9999))
|
||||
|
||||
# 初始化指标
|
||||
collect_metrics_background()
|
||||
|
||||
# 启动后台线程：每 60 秒主动刷新
|
||||
def refresh_loop():
|
||||
while True:
|
||||
time.sleep(60)
|
||||
collect_metrics_background()
|
||||
|
||||
t = threading.Thread(target=refresh_loop, daemon=True)
|
||||
t.start()
|
||||
|
||||
# 启动 HTTP 服务
|
||||
server = http.server.HTTPServer(("0.0.0.0", port), MetricsHandler)
|
||||
print(f"Agent Health Exporter v2.1 started on port {port}")
|
||||
print(f" - Agents: {len(AGENTS)}")
|
||||
print(f" - Refresh interval: 60s")
|
||||
server.serve_forever()
|
||||
@@ -1,179 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Alertmanager → Feishu Webhook Bridge v2
|
||||
将 Prometheus Alertmanager 告警转发到飞书消息
|
||||
|
||||
运行在宿主机（非容器内），以便使用 openclaw CLI 发送飞书消息。
|
||||
|
||||
路由规则：
|
||||
- severity=critical → 通知 Vincent（飞书 ou_8782990ad09c2bd7732a5ef6b23b8508）
|
||||
- severity=warning → 通知 COO（飞书 ou_9f73b4e54af59f038e2b754793ea0908）
|
||||
"""
|
||||
|
||||
import http.server
|
||||
import json
|
||||
import os
|
||||
import subprocess
|
||||
import sys
|
||||
import urllib.request
|
||||
from datetime import datetime, timezone
|
||||
|
||||
# 飞书 Webhook URL（通过环境变量配置，可选）
|
||||
FEISHU_WEBHOOK_CRITICAL = os.environ.get("FEISHU_WEBHOOK_CRITICAL", "")
|
||||
FEISHU_WEBHOOK_WARNING = os.environ.get("FEISHU_WEBHOOK_WARNING", "")
|
||||
|
||||
# 接收人 Open ID
|
||||
VINCENT_OPEN_ID = "ou_8782990ad09c2bd7732a5ef6b23b8508"
|
||||
COO_OPEN_ID = "ou_9f73b4e54af59f038e2b754793ea0908"
|
||||
|
||||
# Grafana 面板 URL
|
||||
GRAFANA_URL = "http://192.168.1.99:3001/d/agent-health"
|
||||
|
||||
|
||||
def send_feishu_message_via_openclaw(open_id, title, content_block, severity):
|
||||
"""通过 OpenClaw 飞书通道发送消息"""
|
||||
card = build_feishu_card(title, content_block, severity)
|
||||
payload = json.dumps({
|
||||
"receive_id": open_id,
|
||||
"msg_type": "interactive",
|
||||
"content": json.dumps(card),
|
||||
})
|
||||
|
||||
try:
|
||||
result = subprocess.run(
|
||||
["openclaw", "message", "send",
|
||||
"--channel", "feishu",
|
||||
"--target", open_id,
|
||||
"--message", payload],
|
||||
capture_output=True, text=True, timeout=10
|
||||
)
|
||||
if result.returncode == 0:
|
||||
print(f"[bridge] Feishu sent to {open_id[:20]}...")
|
||||
else:
|
||||
print(f"[bridge] Feishu error: {result.stderr[:200]}", file=sys.stderr)
|
||||
except Exception as e:
|
||||
print(f"[bridge] Feishu exception: {e}", file=sys.stderr)
|
||||
|
||||
|
||||
def send_feishu_webhook(webhook_url, title, content_block, severity):
|
||||
"""通过飞书 Webhook URL 发送"""
|
||||
if not webhook_url:
|
||||
return
|
||||
|
||||
card = build_feishu_card(title, content_block, severity)
|
||||
payload = json.dumps({"msg_type": "interactive", "content": json.dumps(card)}).encode("utf-8")
|
||||
|
||||
try:
|
||||
req = urllib.request.Request(
|
||||
webhook_url,
|
||||
data=payload,
|
||||
headers={"Content-Type": "application/json"},
|
||||
method="POST"
|
||||
)
|
||||
with urllib.request.urlopen(req, timeout=10) as resp:
|
||||
print(f"[bridge] Webhook sent: {resp.status}")
|
||||
except Exception as e:
|
||||
print(f"[bridge] Webhook error: {e}", file=sys.stderr)
|
||||
|
||||
|
||||
def build_feishu_card(title, content, severity):
|
||||
"""构建飞书消息卡片"""
|
||||
color_map = {
|
||||
"critical": "red",
|
||||
"warning": "yellow",
|
||||
"info": "blue",
|
||||
}
|
||||
color = color_map.get(severity, "blue")
|
||||
|
||||
return {
|
||||
"config": {"wide_screen_mode": True},
|
||||
"header": {
|
||||
"title": {"tag": "plain_text", "content": f"🚨 {title}"},
|
||||
"template": color,
|
||||
},
|
||||
"elements": [
|
||||
{"tag": "markdown", "content": content},
|
||||
{
|
||||
"tag": "note",
|
||||
"elements": [
|
||||
{"tag": "plain_text", "content": f"BIZ-28 监控告警 | {datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M:%S UTC')}"}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
|
||||
def handle_alert(alert_data):
|
||||
"""处理告警并发通知"""
|
||||
alerts = alert_data.get("alerts", [])
|
||||
for alert in alerts:
|
||||
labels = alert.get("labels", {})
|
||||
annotations = alert.get("annotations", {})
|
||||
status = alert.get("status", "firing")
|
||||
severity = labels.get("severity", "warning")
|
||||
alertname = labels.get("alertname", "Unknown")
|
||||
summary = annotations.get("summary", alertname)
|
||||
description = annotations.get("description", "")
|
||||
|
||||
title = f"[{severity.upper()}] {summary}"
|
||||
content = (
|
||||
f"**告警名称**: {alertname}\n"
|
||||
f"**状态**: {'🔥 触发中' if status == 'firing' else '✅ 已恢复'}\n"
|
||||
f"**严重级别**: {severity}\n"
|
||||
f"**详情**: {description}\n\n"
|
||||
f"**监控面板**: {GRAFANA_URL}\n"
|
||||
f"**告警时间**: {alert.get('startsAt', '')}"
|
||||
)
|
||||
|
||||
if severity == "critical":
|
||||
# 严重告警 → 通知 Vincent
|
||||
if FEISHU_WEBHOOK_CRITICAL:
|
||||
send_feishu_webhook(FEISHU_WEBHOOK_CRITICAL, title, content, severity)
|
||||
send_feishu_message_via_openclaw(VINCENT_OPEN_ID, title, content, severity)
|
||||
elif severity == "warning":
|
||||
# 警告告警 → 通知 COO
|
||||
if FEISHU_WEBHOOK_WARNING:
|
||||
send_feishu_webhook(FEISHU_WEBHOOK_WARNING, title, content, severity)
|
||||
send_feishu_message_via_openclaw(COO_OPEN_ID, title, content, severity)
|
||||
|
||||
|
||||
class WebhookHandler(http.server.BaseHTTPRequestHandler):
|
||||
def do_POST(self):
|
||||
content_length = int(self.headers.get("Content-Length", 0))
|
||||
body = self.rfile.read(content_length)
|
||||
|
||||
try:
|
||||
alert_data = json.loads(body)
|
||||
handle_alert(alert_data)
|
||||
self.send_response(200)
|
||||
self.send_header("Content-Type", "application/json")
|
||||
response = json.dumps({"status": "ok"}).encode()
|
||||
self.send_header("Content-Length", len(response))
|
||||
self.end_headers()
|
||||
self.wfile.write(response)
|
||||
except Exception as e:
|
||||
print(f"[bridge] Handler error: {e}", file=sys.stderr)
|
||||
self.send_response(500)
|
||||
self.end_headers()
|
||||
|
||||
def do_GET(self):
|
||||
if self.path == "/health":
|
||||
self.send_response(200)
|
||||
self.send_header("Content-Type", "application/json")
|
||||
response = json.dumps({"status": "ok"}).encode()
|
||||
self.send_header("Content-Length", len(response))
|
||||
self.end_headers()
|
||||
self.wfile.write(response)
|
||||
else:
|
||||
self.send_response(404)
|
||||
self.end_headers()
|
||||
|
||||
def log_message(self, format, *args):
|
||||
pass
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
port = int(os.environ.get("WEBHOOK_PORT", 9094))
|
||||
server = http.server.HTTPServer(("0.0.0.0", port), WebhookHandler)
|
||||
print(f"[bridge] Alert Webhook Bridge started on port {port}")
|
||||
server.serve_forever()
|
||||
@@ -1,9 +1,9 @@
|
||||
# BIZ-13 智能体运行稳定性保障方案
|
||||
|
||||
> 版本：v1.1
|
||||
> 版本：v1.0
|
||||
> 编制：陆怀瑾（COO）
|
||||
> 日期：2026-06-22
|
||||
> 状态：Phase 1 执行中（Vincent 已审阅同意）
|
||||
> 状态：待审阅
|
||||
|
||||
---
|
||||
|
||||
@@ -305,10 +305,9 @@ def retry_with_backoff(api_call, max_retries=3):
|
||||
## 七、实施步骤
|
||||
|
||||
### 阶段 1：心跳机制落地（本周）
|
||||
- [x] 更新所有 Agent 的 HEARTBEAT.md（15/15 Agent 已完成）
|
||||
- [x] 已创建分步实施子任务（BIZ-24 ~ BIZ-28，5个子任务）
|
||||
- [ ] 配置定时任务（10/15 分钟）→ BIZ-25，已分派 opengineer 严维序
|
||||
- [ ] 测试超时检测 → BIZ-24 执行中
|
||||
- [ ] 更新所有 Agent 的 HEARTBEAT.md
|
||||
- [ ] 配置定时任务（10 分钟）
|
||||
- [ ] 测试超时检测
|
||||
|
||||
### 阶段 2：限流优化（下周）
|
||||
- [ ] 实现请求队列
|
||||
|
||||
@@ -1,835 +0,0 @@
|
||||
# BIZ-24 HEARTBEAT.md 增强模板方案
|
||||
|
||||
> Phase 1 of BIZ-13 运行稳定性保障方案
|
||||
> 版本：v1.1（2026-06-22 优化：增加全任务源统一监控；已部署）
|
||||
> 编制：陆怀瑾（COO）
|
||||
> 日期：2026-06-22
|
||||
> 状态：已部署
|
||||
> 关联：[BIZ-13 运行稳定性保障方案](BIZ-13_运行稳定性保障方案.md)
|
||||
|
||||
---
|
||||
|
||||
## 一、目标
|
||||
|
||||
为所有 Agent 的 HEARTBEAT.md 文件统一增强以下机制，解决任务停滞、运行异常与工作遗漏问题：
|
||||
|
||||
1. **全任务源统一监控** — 覆盖 OpenClaw WorkBoard + Multica Issues + 待办文档，避免工作遗漏
|
||||
2. **禁止请示规则** — 消除"等待用户确认"导致的任务卡死
|
||||
3. **超时检测规则** — 按 Agent 类型差异化配置心跳频率
|
||||
4. **自动恢复规则** — 检测无进展时自动重新调度
|
||||
5. **依赖检查前置** — 任务启动前强制检查所有依赖
|
||||
6. **最大轮次限制** — 防止无限循环或资源耗尽
|
||||
|
||||
### 1.1 为什么需要全任务源统一监控
|
||||
|
||||
当前 Agent 工作面临的任务来源是多平台的：
|
||||
|
||||
| 任务来源 | 平台/工具 | 查询方式 | 当前监控状态 |
|
||||
|----------|-----------|----------|------------|
|
||||
| WorkBoard 卡片 | OpenClaw workboard | `openclaw workboard list` | ✅ 已纳入 |
|
||||
| 待办文档 | 各 Agent workspace 的 TODO.md / AGENTS.md | 文件读取 | ⚠️ 部分纳入 |
|
||||
| Multica Issues | Multica 平台 | `multica issue list --assignee-id <id>` | ❌ 未纳入 |
|
||||
|
||||
**问题**：Multica Issues 中分配给 Agent 的任务当前完全不在心跳监控范围内，Agent 可能永远不会发现并执行这些任务，导致工作永久遗漏。
|
||||
|
||||
**对策**：每次心跳同步检查以上三个来源，确保无一遗漏。
|
||||
|
||||
---
|
||||
|
||||
## 二、Agent 分类与参数配置
|
||||
|
||||
### 2.1 分类标准
|
||||
|
||||
| 分类 | 特征 | Agent |
|
||||
|------|------|-------|
|
||||
| 高频 Agent | 需频繁检查任务状态、全局监控 | secretary, coo |
|
||||
| 开发 Agent | 执行开发/设计/部署等长周期任务 | projectmanager, productmanager, architect, costcodev, designer, opengineer |
|
||||
| 业务 Agent | 执行专项业务任务 | taobaospecialist, contentspecialist, mediaspecialist, cvexpert, marketanalysis, lawyer |
|
||||
|
||||
### 2.2 参数配置矩阵
|
||||
|
||||
| 参数 | 高频 Agent | 开发 Agent | 业务 Agent |
|
||||
|------|-----------|-----------|-----------|
|
||||
| 心跳频率 | 10 分钟 | 15 分钟 | 15 分钟 |
|
||||
| 最大轮次 | 50 轮 | 100 轮 | 30 轮 |
|
||||
| 超时告警阈值 | 20 分钟无进展 | 30 分钟无进展 | 30 分钟无进展 |
|
||||
| 自动恢复等待 | 30 分钟后重新调度 | 45 分钟后重新调度 | 45 分钟后重新调度 |
|
||||
| 告警通知对象 | COO | COO + 创建者 | 创建者 |
|
||||
|
||||
---
|
||||
|
||||
## 三、六项增强规则详解
|
||||
|
||||
### 规则 0：全任务源统一监控
|
||||
|
||||
**问题**：Agent 的任务分布在多个平台（OpenClaw WorkBoard、Multica Issues、工作区待办文档），各平台独立存在，Agent 只监控其中一部分会导致工作任务被永久遗漏。
|
||||
|
||||
**规则文本**：
|
||||
```markdown
|
||||
## 📋 全任务源统一监控（每次心跳必检）
|
||||
|
||||
> **核心原则：发现任何来源的任务都必须立即执行，不得遗漏。**
|
||||
> 你的工作任务可能存在于三个地方：OpenClaw WorkBoard、Multica Issues、本地待办文档。
|
||||
|
||||
### 任务源检查清单（按优先级）
|
||||
|
||||
#### 第一优先级：OpenClaw WorkBoard 卡片
|
||||
|
||||
\```bash
|
||||
# 检查 WorkBoard 中分配给自己的待办卡片
|
||||
openclaw workboard list --json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
data = json.load(sys.stdin)
|
||||
my_cards = [c for c in data.get('cards', [])
|
||||
if c.get('agentId') == '<your_agent_id>' and c.get('status') == 'todo']
|
||||
for c in my_cards:
|
||||
print(f'WORKBOARD TODO: {c[\"id\"][:8]} [priority={c.get(\"priority\",\"?\")}] {c[\"title\"]}')
|
||||
"
|
||||
\```
|
||||
|
||||
#### 第二优先级：Multica Issues
|
||||
|
||||
\```bash
|
||||
# 检查 Multica 中分配给自己的待办 Issue
|
||||
multica issue list --assignee-id <your_multica_agent_uuid> --status todo --output json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
data = json.load(sys.stdin)
|
||||
for issue in data:
|
||||
print(f'MULTICA TODO: {issue[\"identifier\"]} [{issue.get(\"priority\",\"?\")}] {issue[\"title\"]}')
|
||||
"
|
||||
\```
|
||||
|
||||
#### 第三优先级：待办文档
|
||||
|
||||
\```bash
|
||||
# 检查工作区待办文档（TODO.md 或 AGENTS.md 中未完成的任务）
|
||||
grep -n '\[ \]' TODO.md AGENTS.md 2>/dev/null || echo "无待办文档"
|
||||
\```
|
||||
|
||||
### 三源合并决策
|
||||
|
||||
```
|
||||
心跳开始
|
||||
↓
|
||||
检查 WorkBoard 待办卡片
|
||||
↓
|
||||
检查 Multica Issues 待办
|
||||
↓
|
||||
检查待办文档
|
||||
↓
|
||||
合并去重（避免同一任务在不同来源重复出现）
|
||||
↓
|
||||
按优先级排序后依次执行
|
||||
```
|
||||
|
||||
### Multica Issue 认领与执行流程
|
||||
|
||||
```
|
||||
发现 Multica todo Issue（assignee 是自己）
|
||||
↓
|
||||
启动 Multica Runtime 执行任务
|
||||
↓
|
||||
完成后通过 multica issue comment add 汇报结果
|
||||
↓
|
||||
更新 issue status 为 in_review / done
|
||||
```
|
||||
|
||||
### COO 专属：全平台积压巡检
|
||||
|
||||
作为 COO，还需要额外检查全平台的任务积压情况（不限自己）：
|
||||
|
||||
\```bash
|
||||
#!/bin/bash
|
||||
# COO 全平台任务积压巡检脚本
|
||||
|
||||
echo "=== OpenClaw WorkBoard 全局积压 ==="
|
||||
openclaw workboard list --json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
data = json.load(sys.stdin)
|
||||
cards = data.get('cards', [])
|
||||
todo = [c for c in cards if c.get('status') == 'todo']
|
||||
inprog = [c for c in cards if c.get('status') == 'in_progress']
|
||||
print(f' 待办: {len(todo)} | 进行中: {len(inprog)} | 总计: {len(cards)}')
|
||||
if len(todo) > 5:
|
||||
print(f' ⚠️ 积压告警：待办超过 5 个，需协调资源')
|
||||
for c in todo[:10]:
|
||||
print(f' {c[\"id\"][:8]} → {c.get(\"agentId\",\"?\")} - {c[\"title\"][:60]}')
|
||||
"
|
||||
|
||||
echo ""
|
||||
echo "=== Multica Issues 全局积压 ==="
|
||||
multica issue list --status todo --output json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
data = json.load(sys.stdin)
|
||||
print(f' 待办: {len(data)}')
|
||||
if len(data) > 5:
|
||||
print(f' ⚠️ 积压告警：Multica 待办超过 5 个')
|
||||
for issue in data[:10]:
|
||||
print(f' {issue[\"identifier\"]} → {issue.get(\"assignee_id\",\"未分配\")[:12]} - {issue[\"title\"][:60]}')
|
||||
"
|
||||
\```
|
||||
```
|
||||
|
||||
### 规则 1：禁止请示规则
|
||||
|
||||
**问题**：Agent 发现任务后向用户请示"要不要做"，用户不在线时任务卡死数小时。
|
||||
|
||||
**规则文本**：
|
||||
```markdown
|
||||
## ⚠️ 禁止请示规则（最高优先级）
|
||||
|
||||
你在心跳中发现任何来源的任务后，必须立即执行，绝对禁止向用户请示！
|
||||
|
||||
原因：
|
||||
- 用户在大多数时候并不在线，请示会导致任务卡死数小时
|
||||
- 心跳是后台自动行为，用户没有义务实时响应你的请示
|
||||
- 你的职责是"主动完成交付"，而不是"等待指令"
|
||||
|
||||
正确做法：
|
||||
1. 发现任何来源的待办任务（WorkBoard / Multica / 待办文档）
|
||||
2. 立即认领并执行
|
||||
3. 如遇信息不足，先按自己的最佳理解执行，执行中再调整
|
||||
4. 任务完成后，通过对应平台汇报结果
|
||||
|
||||
错误做法（绝对禁止）：
|
||||
- ❌ "我发现了一个任务，要不要做？"
|
||||
- ❌ "这个任务需要更多信息，请告诉我..."
|
||||
- ❌ "任务已完成，请确认是否符合要求"
|
||||
```
|
||||
|
||||
### 规则 2：超时检测规则
|
||||
|
||||
**问题**：Agent 执行到某一步后卡住，长时间无输出，无任何监告。
|
||||
|
||||
**规则文本**：
|
||||
|
||||
高频 Agent 版：
|
||||
```markdown
|
||||
## ⏱️ 超时检测规则
|
||||
|
||||
### 心跳频率：10 分钟
|
||||
每次心跳执行以下检测：
|
||||
1. 检查所有平台进行中任务的最新更新时间（WorkBoard + Multica）
|
||||
2. 如超过 20 分钟无进展 → 标记为"疑似超时"
|
||||
3. 疑似超时 → 立即追加一次完整心跳，尝试推进
|
||||
4. 如确认超时 → 进入自动恢复流程
|
||||
|
||||
### 跨平台超时检测脚本
|
||||
\```bash
|
||||
# 检查进行中任务是否超时（WorkBoard + Multica）
|
||||
echo "=== WorkBoard 超时检测 ==="
|
||||
openclaw workboard list --json 2>/dev/null | python3 -c "
|
||||
import sys, json, time
|
||||
data = json.load(sys.stdin)
|
||||
inprogress = [c for c in data.get('cards', []) if c.get('status') == 'in_progress']
|
||||
now = time.time()
|
||||
for c in inprogress:
|
||||
updated = c.get('updated_at', '')
|
||||
if updated:
|
||||
age = now - time.mktime(time.strptime(updated[:19], '%Y-%m-%dT%H:%M:%S'))
|
||||
if age > 1200:
|
||||
print(f'⏰ WB TIMEOUT: {c[\"id\"][:8]} [{c.get(\"agentId\",\"?\")}] {c[\"title\"]}')
|
||||
"
|
||||
|
||||
echo "=== Multica 超时检测 ==="
|
||||
multica issue list --status in_progress --output json 2>/dev/null | python3 -c "
|
||||
import sys, json, time
|
||||
data = json.load(sys.stdin)
|
||||
now = time.time()
|
||||
for issue in data:
|
||||
updated = issue.get('updated_at', '')
|
||||
if updated:
|
||||
age = now - time.mktime(time.strptime(updated[:19], '%Y-%m-%dT%H:%M:%S'))
|
||||
if age > 1200:
|
||||
print(f'⏰ MUL TIMEOUT: {issue[\"identifier\"]} [{issue.get(\"assignee_id\",\"?\")[:12]}] {issue[\"title\"]}')
|
||||
"
|
||||
\```
|
||||
```
|
||||
|
||||
开发 Agent 版（差异部分）：
|
||||
```markdown
|
||||
### 心跳频率：15 分钟
|
||||
每次心跳执行以下检测：
|
||||
1. 检查所有平台进行中任务的最新更新时间（WorkBoard + Multica）
|
||||
2. 如超过 30 分钟无进展 → 标记为"疑似超时"
|
||||
```
|
||||
|
||||
业务 Agent 版（差异部分）：
|
||||
```markdown
|
||||
### 心跳频率：15 分钟
|
||||
每次心跳执行以下检测：
|
||||
1. 检查所有平台进行中任务的最新更新时间（WorkBoard + Multica）
|
||||
2. 如超过 30 分钟无进展 → 标记为"疑似超时"
|
||||
```
|
||||
|
||||
### 规则 3：自动恢复规则
|
||||
|
||||
**问题**：检测到无进展后没有自动恢复手段，任务永久停滞。
|
||||
|
||||
**规则文本**：
|
||||
```markdown
|
||||
## 🔄 自动恢复规则
|
||||
|
||||
### 恢复流程
|
||||
```
|
||||
检测到超时（跨平台无进展超阈值）
|
||||
↓
|
||||
步骤 1：追加一次完整心跳，尝试推进任务
|
||||
↓
|
||||
步骤 2：检查任务状态
|
||||
↓
|
||||
┌─────────────┴─────────────┐
|
||||
│ │
|
||||
有进展 仍无进展
|
||||
│ │
|
||||
重置超时计数器 步骤 3：通知 COO/创建者
|
||||
│ │
|
||||
继续执行 步骤 4：通过对应平台标记 blocked
|
||||
│
|
||||
步骤 5：重新调度（分配备用 Agent 或
|
||||
等待人工介入）
|
||||
```
|
||||
|
||||
### 自动恢复触发条件
|
||||
- 高频 Agent：超 30 分钟无进展 → 自动重新调度
|
||||
- 开发 Agent：超 45 分钟无进展 → 自动重新调度
|
||||
- 业务 Agent：超 45 分钟无进展 → 自动重新调度
|
||||
|
||||
### 跨平台恢复操作
|
||||
**WorkBoard 任务**：
|
||||
1. 添加评论说明超时原因
|
||||
2. 释放 Agent 认领（release claim）
|
||||
3. 通知 COO 重新分配
|
||||
|
||||
**Multica Issue**：
|
||||
1. `multica issue comment add` 说明超时原因
|
||||
2. `multica issue status <id> blocked`
|
||||
3. 通知 COO 重新分配
|
||||
|
||||
**待办文档任务**：
|
||||
1. 在原文档中标注超时状态
|
||||
2. 如可转为 WorkBoard 卡片 → 创建卡片并通知 COO
|
||||
```
|
||||
|
||||
### 规则 4：依赖检查前置
|
||||
|
||||
**问题**：任务开始后才发现依赖未满足，浪费 Agent 时间，且可能导致循环等待。
|
||||
|
||||
**规则文本**：
|
||||
```markdown
|
||||
## 🔗 依赖检查前置规则
|
||||
|
||||
### 任务启动前强制检查
|
||||
每次认领或启动任务前，必须执行依赖检查：
|
||||
|
||||
**WorkBoard 任务**：
|
||||
1. 读取任务的 depends_on 字段
|
||||
2. 逐一检查每个依赖任务的状态
|
||||
3. 所有依赖 ready → 可以启动
|
||||
4. 任一依赖未完成 → 禁止启动，标记为 blocked
|
||||
|
||||
**Multica Issue**：
|
||||
1. 读取 issue 的 parent_issue_id
|
||||
2. 检查父 issue 状态
|
||||
3. 父 issue 未完成 → 禁止启动
|
||||
|
||||
### 检查脚本
|
||||
|
||||
#### WorkBoard 依赖检查
|
||||
\```bash
|
||||
openclaw workboard read <card-id> --json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
card = json.load(sys.stdin)
|
||||
deps = card.get('dependsOn', [])
|
||||
if deps:
|
||||
for dep in deps:
|
||||
print(f'依赖: {dep[\"id\"]} → 状态: {dep.get(\"status\", \"?\")}')
|
||||
if dep.get('status') != 'done':
|
||||
print(f'⛔ WB 依赖未满足，禁止启动 {card[\"id\"][:8]}')
|
||||
sys.exit(1)
|
||||
print('✅ 所有 WB 依赖已满足')
|
||||
else:
|
||||
print('✅ 无 WB 依赖，可以启动')
|
||||
"
|
||||
\```
|
||||
|
||||
#### Multica 依赖检查
|
||||
\```bash
|
||||
multica issue get <issue-id> --output json 2>/dev/null | python3 -c "
|
||||
import sys, json
|
||||
issue = json.load(sys.stdin)
|
||||
parent_id = issue.get('parent_issue_id')
|
||||
if parent_id:
|
||||
import subprocess
|
||||
result = subprocess.run(['multica', 'issue', 'get', parent_id, '--output', 'json'],
|
||||
capture_output=True, text=True)
|
||||
parent = json.loads(result.stdout)
|
||||
if parent.get('status') != 'done':
|
||||
print(f'⛔ MUL 父 Issue {parent[\"identifier\"]} 未完成，禁止启动')
|
||||
sys.exit(1)
|
||||
print(f'✅ 父 Issue {parent[\"identifier\"]} 已完成')
|
||||
else:
|
||||
print('✅ 无父 Issue 依赖，可以启动')
|
||||
"
|
||||
\```
|
||||
|
||||
### 依赖未满足时的处理
|
||||
1. 不认领任务（保持 todo 状态）
|
||||
2. 不在该任务上浪费心跳时间
|
||||
3. 如超过等待阈值（高频 1h / 开发/业务 2h），通知依赖任务的执行者
|
||||
```
|
||||
|
||||
### 规则 5：最大轮次限制
|
||||
|
||||
**问题**：Agent 陷入无限循环，反复执行相同逻辑无进展，持续消耗 API 配额。
|
||||
|
||||
**规则文本**：
|
||||
|
||||
高频 Agent 版：
|
||||
```markdown
|
||||
## 🛑 最大轮次限制
|
||||
|
||||
### 限制值：50 轮
|
||||
单次任务执行不得超过 50 个对话轮次。
|
||||
|
||||
### 检测机制
|
||||
- 每次心跳记录已消耗轮次
|
||||
- 接近上限（80%）时发出预警
|
||||
- 达到上限时自动暂停
|
||||
|
||||
### 超限处理
|
||||
```
|
||||
达到最大轮次
|
||||
↓
|
||||
1. 暂停任务执行
|
||||
2. 记录已完成的步骤和未完成的部分
|
||||
3. 通知 COO，附当前进度
|
||||
4. COO 决定：重新分配 / 拆分任务 / 人工介入
|
||||
```
|
||||
|
||||
### 跨平台轮次跟踪
|
||||
- **WorkBoard**：通过 workboard_heartbeat 的 note 记录轮次
|
||||
- **Multica**：通过 issue comment 记录轮次进度
|
||||
- **待办文档**：在工作日志中记录
|
||||
|
||||
### 计数器维护
|
||||
\```bash
|
||||
# 每次心跳更新轮次计数
|
||||
# 轮次数据存储在任务 metadata 或 comment 中
|
||||
\```
|
||||
```
|
||||
|
||||
开发 Agent 版（差异部分）：
|
||||
```markdown
|
||||
### 限制值：100 轮
|
||||
单次任务执行不得超过 100 个对话轮次。
|
||||
```
|
||||
|
||||
业务 Agent 版（差异部分）：
|
||||
```markdown
|
||||
### 限制值：30 轮
|
||||
单次任务执行不得超过 30 个对话轮次。
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、HEARTBEAT.md 完整增强模板
|
||||
|
||||
### 4.1 高频 Agent 完整模板（secretary / coo）
|
||||
|
||||
```markdown
|
||||
# HEARTBEAT.md - [Agent Name] 的心跳配置
|
||||
|
||||
## 📋 全任务源统一监控（每次心跳必检）
|
||||
|
||||
> **核心原则：发现任何来源的任务都必须立即执行，不得遗漏。**
|
||||
|
||||
### 三源检查
|
||||
1. **OpenClaw WorkBoard** — workboard list → 查找 agent_id=自己 & status=todo
|
||||
2. **Multica Issues** — issue list --assignee-id <uuid> --status todo
|
||||
3. **待办文档** — 检查 TODO.md / AGENTS.md 中未完成的任务
|
||||
|
||||
### 合并去重 → 按优先级排序 → 依次执行
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 禁止请示规则（最高优先级，自动执行）
|
||||
|
||||
> **核心规则：发现分配给自己的任务 → 立即执行，不得向用户请示！**
|
||||
> 心跳是后台自动行为，用户在大多数时候并不在线，请示会导致任务卡死。
|
||||
|
||||
### 执行流程（严格执行，无需确认）
|
||||
1. **三源检查待办** — WorkBoard + Multica + 待办文档
|
||||
2. **立即执行，不得请示** — 发现待办后直接执行
|
||||
3. **检查进行中任务** — 确认认领的任务状态
|
||||
4. **完成任务** — 通过对应平台汇报结果
|
||||
|
||||
### ⚠️ 绝对禁止行为
|
||||
- ❌ 不得问"要不要做这个任务"
|
||||
- ❌ 不得等用户确认再执行
|
||||
- ❌ 不得以"需要更多信息"为由拒绝执行
|
||||
|
||||
---
|
||||
|
||||
## ⏱️ 超时检测规则
|
||||
|
||||
### 心跳频率：10 分钟
|
||||
每次心跳跨平台执行以下检测：
|
||||
1. 检查 WorkBoard 进行中任务的更新时间
|
||||
2. 检查 Multica 进行中 issues 的更新时间
|
||||
3. 超过 20 分钟无进展 → 标记为"疑似超时"
|
||||
4. 疑似超时 → 追加一次完整心跳尝试推进
|
||||
5. 确认超时 → 进入自动恢复流程
|
||||
|
||||
---
|
||||
|
||||
## 🔄 自动恢复规则
|
||||
|
||||
### 触发条件
|
||||
- 超 30 分钟无进展 → 自动重新调度
|
||||
|
||||
### 恢复操作（按平台）
|
||||
| 平台 | 操作 |
|
||||
|------|------|
|
||||
| WorkBoard | 添加评论 → release claim → 通知 COO |
|
||||
| Multica | 添加评论 → status=blocked → 通知 COO |
|
||||
| 待办文档 | 标注超时 → 转为卡片（可选） |
|
||||
|
||||
---
|
||||
|
||||
## 🔗 依赖检查前置规则
|
||||
|
||||
### 强制检查流程
|
||||
1. 认领任务前，读取依赖字段（depends_on / parent_issue_id）
|
||||
2. 逐一检查每个依赖任务的状态
|
||||
3. 依赖未满足 → 不认领（保持 todo）
|
||||
4. 超过等待阈值（1h）→ 通知依赖任务执行者
|
||||
|
||||
---
|
||||
|
||||
## 🛑 最大轮次限制
|
||||
|
||||
### 限制值：50 轮
|
||||
- 接近 80%（40 轮）→ 预警
|
||||
- 达到上限 → 暂停，通知 COO
|
||||
|
||||
---
|
||||
|
||||
## 🫀 心跳执行清单
|
||||
|
||||
1. ✅ **全任务源检查**：WorkBoard + Multica + 待办文档
|
||||
2. ✅ 进行中任务超时检测（跨平台）
|
||||
3. ✅ 依赖检查
|
||||
4. ✅ 轮次计数器更新
|
||||
5. ✅ 全平台积压巡检（仅 COO）
|
||||
6. ✅ [Agent 专属检查项]
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 全局关键规则
|
||||
|
||||
1. **心跳不打断对话** — 用户正在对话时延后执行
|
||||
2. **非紧急事项延后汇报** — 等下一轮心跳或用户询问
|
||||
3. **发现任务立即执行，不得请示**（任何来源）
|
||||
4. **超时任务按自动恢复流程处理**（跨平台）
|
||||
5. **依赖未满足不启动**
|
||||
6. **达到轮次上限自动暂停**
|
||||
7. **避免任务遗漏** — 三源必须全部检查，缺一不可
|
||||
```
|
||||
|
||||
### 4.2 开发 Agent 完整模板（projectmanager / productmanager / architect / costcodev / designer / opengineer）
|
||||
|
||||
```markdown
|
||||
# HEARTBEAT.md - [Agent Name] 的心跳配置
|
||||
|
||||
## 📋 全任务源统一监控（每次心跳必检）
|
||||
|
||||
> **核心原则：发现任何来源的任务都必须立即执行，不得遗漏。**
|
||||
|
||||
### 三源检查
|
||||
1. **OpenClaw WorkBoard** — workboard list → 查找 agent_id=自己 & status=todo
|
||||
2. **Multica Issues** — issue list --assignee-id <uuid> --status todo
|
||||
3. **待办文档** — 检查 TODO.md / AGENTS.md 中未完成的任务
|
||||
|
||||
### 合并去重 → 按优先级排序 → 依次执行
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 禁止请示规则（最高优先级，自动执行）
|
||||
|
||||
> **核心规则：发现分配给自己的任务 → 立即执行，不得向用户请示！**
|
||||
> 心跳是后台自动行为，用户在大多数时候并不在线，请示会导致任务卡死。
|
||||
|
||||
### 执行流程（严格执行，无需确认）
|
||||
1. **三源检查待办** — WorkBoard + Multica + 待办文档
|
||||
2. **立即执行，不得请示** — 发现待办后直接执行
|
||||
3. **检查进行中任务** — 确认认领的任务状态
|
||||
4. **完成任务** — 通过对应平台汇报结果
|
||||
|
||||
### ⚠️ 绝对禁止行为
|
||||
- ❌ 不得问"要不要做这个任务"
|
||||
- ❌ 不得等用户确认再执行
|
||||
- ❌ 不得以"需要更多信息"为由拒绝执行
|
||||
|
||||
---
|
||||
|
||||
## ⏱️ 超时检测规则
|
||||
|
||||
### 心跳频率：15 分钟
|
||||
每次心跳跨平台执行以下检测：
|
||||
1. 检查 WorkBoard 进行中任务的更新时间
|
||||
2. 检查 Multica 进行中 issues 的更新时间
|
||||
3. 超过 30 分钟无进展 → 标记为"疑似超时"
|
||||
4. 疑似超时 → 追加一次完整心跳尝试推进
|
||||
5. 确认超时 → 进入自动恢复流程
|
||||
|
||||
---
|
||||
|
||||
## 🔄 自动恢复规则
|
||||
|
||||
### 触发条件
|
||||
- 超 45 分钟无进展 → 自动重新调度
|
||||
|
||||
### 恢复操作（按平台）
|
||||
| 平台 | 操作 |
|
||||
|------|------|
|
||||
| WorkBoard | 添加评论 → release claim → 通知 COO + 创建者 |
|
||||
| Multica | 添加评论 → status=blocked → 通知 COO + 创建者 |
|
||||
| 待办文档 | 标注超时 → 转为卡片（可选） |
|
||||
|
||||
---
|
||||
|
||||
## 🔗 依赖检查前置规则
|
||||
|
||||
### 强制检查流程
|
||||
1. 认领任务前，读取依赖字段（depends_on / parent_issue_id）
|
||||
2. 逐一检查每个依赖任务的状态
|
||||
3. 依赖未满足 → 不认领（保持 todo）
|
||||
4. 超过等待阈值（2h）→ 通知依赖任务执行者
|
||||
|
||||
---
|
||||
|
||||
## 🛑 最大轮次限制
|
||||
|
||||
### 限制值：100 轮
|
||||
- 接近 80%（80 轮）→ 预警
|
||||
- 达到上限 → 暂停，记录日志
|
||||
|
||||
---
|
||||
|
||||
## 🫀 心跳执行清单
|
||||
|
||||
1. ✅ **全任务源检查**：WorkBoard + Multica + 待办文档
|
||||
2. ✅ 进行中任务超时检测（跨平台）
|
||||
3. ✅ 依赖检查
|
||||
4. ✅ 轮次计数器更新
|
||||
5. ✅ [Agent 专属检查项]
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 全局关键规则
|
||||
|
||||
1. **心跳不打断对话** — 用户正在对话时延后执行
|
||||
2. **非紧急事项延后汇报** — 等下一轮心跳或用户询问
|
||||
3. **发现任务立即执行，不得请示**（任何来源）
|
||||
4. **超时任务按自动恢复流程处理**（跨平台）
|
||||
5. **依赖未满足不启动**
|
||||
6. **达到轮次上限自动暂停**
|
||||
7. **避免任务遗漏** — 三源必须全部检查，缺一不可
|
||||
```
|
||||
|
||||
### 4.3 业务 Agent 完整模板（taobaospecialist / contentspecialist / mediaspecialist / cvexpert / marketanalysis / lawyer）
|
||||
|
||||
```markdown
|
||||
# HEARTBEAT.md - [Agent Name] 的心跳配置
|
||||
|
||||
## 📋 全任务源统一监控（每次心跳必检）
|
||||
|
||||
> **核心原则：发现任何来源的任务都必须立即执行，不得遗漏。**
|
||||
|
||||
### 三源检查
|
||||
1. **OpenClaw WorkBoard** — workboard list → 查找 agent_id=自己 & status=todo
|
||||
2. **Multica Issues** — issue list --assignee-id <uuid> --status todo
|
||||
3. **待办文档** — 检查 TODO.md / AGENTS.md 中未完成的任务
|
||||
|
||||
### 合并去重 → 按优先级排序 → 依次执行
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 禁止请示规则（最高优先级，自动执行）
|
||||
|
||||
> **核心规则：发现分配给自己的任务 → 立即执行，不得向用户请示！**
|
||||
> 心跳是后台自动行为，用户在大多数时候并不在线，请示会导致任务卡死。
|
||||
|
||||
### 执行流程（严格执行，无需确认）
|
||||
1. **三源检查待办** — WorkBoard + Multica + 待办文档
|
||||
2. **立即执行，不得请示** — 发现待办后直接执行
|
||||
3. **检查进行中任务** — 确认认领的任务状态
|
||||
4. **完成任务** — 通过对应平台汇报结果
|
||||
|
||||
### ⚠️ 绝对禁止行为
|
||||
- ❌ 不得问"要不要做这个任务"
|
||||
- ❌ 不得等用户确认再执行
|
||||
- ❌ 不得以"需要更多信息"为由拒绝执行
|
||||
|
||||
---
|
||||
|
||||
## ⏱️ 超时检测规则
|
||||
|
||||
### 心跳频率：15 分钟
|
||||
每次心跳跨平台执行以下检测：
|
||||
1. 检查 WorkBoard 进行中任务的更新时间
|
||||
2. 检查 Multica 进行中 issues 的更新时间
|
||||
3. 超过 30 分钟无进展 → 标记为"疑似超时"
|
||||
4. 疑似超时 → 追加一次完整心跳尝试推进
|
||||
5. 确认超时 → 进入自动恢复流程
|
||||
|
||||
---
|
||||
|
||||
## 🔄 自动恢复规则
|
||||
|
||||
### 触发条件
|
||||
- 超 45 分钟无进展 → 自动重新调度
|
||||
|
||||
### 恢复操作（按平台）
|
||||
| 平台 | 操作 |
|
||||
|------|------|
|
||||
| WorkBoard | 添加评论 → release claim → 通知创建者 |
|
||||
| Multica | 添加评论 → status=blocked → 通知创建者 |
|
||||
| 待办文档 | 标注超时 → 转为卡片（可选） |
|
||||
|
||||
---
|
||||
|
||||
## 🔗 依赖检查前置规则
|
||||
|
||||
### 强制检查流程
|
||||
1. 认领任务前，读取依赖字段（depends_on / parent_issue_id）
|
||||
2. 逐一检查每个依赖任务的状态
|
||||
3. 依赖未满足 → 不认领（保持 todo）
|
||||
4. 超过等待阈值（2h）→ 通知依赖任务执行者
|
||||
|
||||
---
|
||||
|
||||
## 🛑 最大轮次限制
|
||||
|
||||
### 限制值：30 轮
|
||||
- 接近 80%（24 轮）→ 预警
|
||||
- 达到上限 → 暂停，通知创建者
|
||||
|
||||
---
|
||||
|
||||
## 🫀 心跳执行清单
|
||||
|
||||
1. ✅ **全任务源检查**：WorkBoard + Multica + 待办文档
|
||||
2. ✅ 进行中任务超时检测（跨平台）
|
||||
3. ✅ 依赖检查
|
||||
4. ✅ 轮次计数器更新
|
||||
5. ✅ [Agent 专属检查项]
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 全局关键规则
|
||||
|
||||
1. **心跳不打断对话** — 用户正在对话时延后执行
|
||||
2. **非紧急事项延后汇报** — 等下一轮心跳或用户询问
|
||||
3. **发现任务立即执行，不得请示**（任何来源）
|
||||
4. **超时任务按自动恢复流程处理**（跨平台）
|
||||
5. **依赖未满足不启动**
|
||||
6. **达到轮次上限自动暂停**
|
||||
7. **避免任务遗漏** — 三源必须全部检查，缺一不可
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、部署清单
|
||||
|
||||
### 5.1 各 Agent HEARTBEAT.md 更新状态
|
||||
|
||||
| Agent | 分类 | 模板版本 | 部署状态 | 部署人 |
|
||||
|-------|------|---------|---------|--------|
|
||||
| secretary (刘诗妮) | 高频 | 高频 Agent 模板 v1.1 | 待部署 | COO |
|
||||
| coo (陆怀瑾) | 高频 | 高频 Agent 模板 v1.1 | 待部署 | COO |
|
||||
| projectmanager (胡蓉) | 开发 | 开发 Agent 模板 v1.1 | 待部署 | COO |
|
||||
| productmanager (沈路明) | 开发 | 开发 Agent 模板 v1.1 | 待部署 | COO |
|
||||
| architect (梁思筑) | 开发 | 开发 Agent 模板 v1.1 | 待部署 | COO |
|
||||
| costcodev (徐聪) | 开发 | 开发 Agent 模板 v1.1 | 待部署 | COO |
|
||||
| designer (苏绘锦) | 开发 | 开发 Agent 模板 v1.1 | 待部署 | COO |
|
||||
| opengineer (严维序) | 开发 | 开发 Agent 模板 v1.1 | 待部署 | COO |
|
||||
| taobaospecialist (陆云帆) | 业务 | 业务 Agent 模板 v1.1 | 待部署 | COO |
|
||||
| contentspecialist (文墨言) | 业务 | 业务 Agent 模板 v1.1 | 待部署 | COO |
|
||||
| mediaspecialist (钟帧韵) | 业务 | 业务 Agent 模板 v1.1 | 待部署 | COO |
|
||||
| cvexpert (程伯予) | 业务 | 业务 Agent 模板 v1.1 | 待部署 | COO |
|
||||
| marketanalysis (顾析策) | 业务 | 业务 Agent 模板 v1.1 | 待部署 | COO |
|
||||
| lawyer (苏慎) | 业务 | 业务 Agent 模板 v1.1 | 待部署 | COO |
|
||||
|
||||
### 5.2 部署步骤
|
||||
|
||||
1. **Vincent 审阅本方案** — 确认参数配置和多源监控范围
|
||||
2. **收集各 Agent 的 Multica UUID** — 用于 `multica issue list --assignee-id <uuid>` 查询
|
||||
3. **创建 HEARTBEAT.md 文件** — 按 v1.1 模板为每个 Agent 创建（填充实际 ID）
|
||||
4. **配置心跳 cron** — 按分类配置定时任务
|
||||
5. **部署到各 Agent workspace** — 将 HEARTBEAT.md 分发到对应 Agent 工作区
|
||||
6. **验证** — 等待一轮完整心跳，检查三源任务是否全量覆盖
|
||||
|
||||
### 5.3 Agent Multica UUID 映射（已收集）
|
||||
|
||||
| Agent | OpenClaw Agent ID | Multica Agent UUID | 状态 |
|
||||
|-------|-------------------|-------------------|------|
|
||||
| secretary (刘诗妮) | secretary | b024fcdc-30ff-420d-b289-498041466e1b | ✅ |
|
||||
| coo (陆怀瑾) | coo | 1c38b437-b54d-4784-bda3-29ce4c8a6722 | ✅ |
|
||||
| projectmanager (胡蓉) | projectmanager | d877b8c3-b230-4073-b3f7-80e148cfdb71 | ✅ |
|
||||
| productmanager (沈路明) | productmanager | a101fa88-d821-4839-9754-e04580d5fd68 | ✅ |
|
||||
| architect (梁思筑) | architect | 40abd41a-62d0-416d-bc44-92c1f758d87a | ✅ |
|
||||
| costcodev (徐聪) | costcodev | 46bdd4a6-5c64-475a-92ef-36a763602fa1 | ✅ |
|
||||
| designer (苏锦绘) | designer | 13bd8968-cc2a-4934-90c7-957a2d3c09c2 | ✅ |
|
||||
| opengineer (严维序) | opengineer | d3804433-9e2e-4199-a92b-a153049b3bc9 | ✅ |
|
||||
| taobaospecialist (陆云帆) | taobaospecialist | e0f62d8f-9568-4f41-8ad4-b73d79a163a7 | ✅ |
|
||||
| contentspecialist (文墨言) | contentspecialist | 8321b0bf-7d89-4ece-927a-0780f42ad396 | ✅ |
|
||||
| mediaspecialist (钟帧韵) | mediaspecialist | e2b587d4-1d16-447c-8ad9-e2a01358ff0a | ✅ |
|
||||
| cvexpert (程伯予) | cvexpert | 4a8696fd-6531-40da-8956-ef84d7ea3c43 | ✅ |
|
||||
| marketanalysis (顾析策) | marketanalysis | 5ed91729-658f-4654-98f0-3e0313022002 | ✅ |
|
||||
| lawyer (苏慎) | lawyer | 6fb0fbd2-16a6-4566-ba7a-d2c136baec25 | ✅ |
|
||||
|
||||
---
|
||||
|
||||
## 六、交付物
|
||||
|
||||
- [x] HEARTBEAT.md 增强模板方案 v1.0（初始版本）
|
||||
- [x] HEARTBEAT.md 增强模板方案 v1.1（优化：增加全任务源统一监控）
|
||||
- [x] 各 Agent Multica UUID 映射表
|
||||
- [x] 14 个 Agent 的独立 HEARTBEAT.md 文件（v1.1，已生成并部署到 workspace）
|
||||
- [ ] 心跳 cron 配置脚本
|
||||
- [ ] 部署验证报告
|
||||
|
||||
---
|
||||
|
||||
## 七、v1.1 变更说明
|
||||
|
||||
| 变更项 | v1.0 | v1.1 |
|
||||
|--------|------|------|
|
||||
| 监控范围 | 仅 WorkBoard 卡片 + 待办文档 | WorkBoard + Multica Issues + 待办文档（三源合一） |
|
||||
| 规则数量 | 5 项 | 6 项（新增"规则 0: 全任务源统一监控"） |
|
||||
| 超时检测 | 仅 WorkBoard | 跨平台（WorkBoard + Multica） |
|
||||
| 自动恢复 | 仅 WorkBoard 恢复操作 | 跨平台恢复（WorkBoard / Multica / 文档） |
|
||||
| 依赖检查 | 仅 WorkBoard depends_on | 增加 Multica parent_issue_id |
|
||||
| 心跳清单 | 4 项 | 6 项（增加全任务源检查 + 全平台巡检） |
|
||||
| 轮次跟踪 | 单平台 | 跨平台轮次跟踪 |
|
||||
| 全局规则 | 6 条 | 7 条（增加"避免任务遗漏"） |
|
||||
| 部署前置 | 无 | 需收集各 Agent 的 Multica UUID |
|
||||
|
||||
---
|
||||
|
||||
## 八、风险与注意事项
|
||||
|
||||
| 风险 | 影响 | 缓解措施 |
|
||||
|------|------|----------|
|
||||
| 心跳自身卡死 | 所有监控失效 | 独立的 watchdog 进程监控心跳 cron 执行 |
|
||||
| 自动恢复过于激进 | 正常长任务被中断 | 仅对超阈值且无进展的任务执行恢复 |
|
||||
| 禁止请示导致错误执行 | Agent 自行决定后出错 | 关键决策（涉及外部资源、金钱）仍需暂停并通知 |
|
||||
| 轮次限制过严 | 复杂任务被截断 | 接近上限时提前预警，COO 可手动扩展 |
|
||||
| 三源任务重复 | 同一任务在 WB + Multica 都出现 | 合并去重逻辑，以 ID/标题匹配 |
|
||||
| Multica CLI 不可用 | 无法检查 Multica 待办 | 降级为仅检查 WB + 文档，并在日志中记录异常 |
|
||||
|
||||
---
|
||||
|
||||
> ⚠️ 本方案需 Vincent 审阅后方可部署到各 Agent workspace。当前为模板方案 v1.1，存放于 EnterpriseArchitect/plans/ 目录。
|
||||
@@ -1,210 +0,0 @@
|
||||
# BIZ-25 定时心跳检查 cron 任务部署方案
|
||||
|
||||
> **版本：** v1.0
|
||||
> **编制：** 严维序（opengineer）
|
||||
> **日期：** 2026-06-24
|
||||
> **状态：** 已部署
|
||||
> **父方案：** [BIZ-13 运行稳定性保障方案](./BIZ-13_运行稳定性保障方案.md)
|
||||
|
||||
---
|
||||
|
||||
## 一、概述
|
||||
|
||||
本方案是 BIZ-13 Phase1 的执行层方案，负责将 HEARTBEAT.md 模板+共享脚本部署为可运行的定时心跳检查机制。
|
||||
|
||||
### 部署架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ OpenClaw Gateway Cron │
|
||||
│ ┌────────────┐ ┌────────────┐ ┌──────────────┐ │
|
||||
│ │ Agent A │ │ Agent B │ │ Agent C │ │
|
||||
│ │ 心跳(10/15m)│ │ 心跳(15m) │ │ 心跳(15m) │ │
|
||||
│ └─────┬──────┘ └─────┬──────┘ └──────┬───────┘ │
|
||||
│ │ │ │ │
|
||||
│ ▼ ▼ ▼ │
|
||||
│ ┌──────────────────────────────────────────┐ │
|
||||
│ │ shared/scripts/heartbeat_helper.py │ │
|
||||
│ │ + multica_proxy.py │ │
|
||||
│ │ + rate_limiter.py │ │
|
||||
│ └──────────────────────────────────────────┘ │
|
||||
│ │ │ │ │
|
||||
│ ▼ ▼ ▼ │
|
||||
│ ┌──────────────────────────────────────────┐ │
|
||||
│ │ 三源任务检查: WorkBoard + Multica + 文档 │ │
|
||||
│ └──────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二、Agent 心跳频率分类
|
||||
|
||||
根据 BIZ-13 方案定义：
|
||||
|
||||
| 分类 | 频率 | Agent | 数量 |
|
||||
|------|------|-------|------|
|
||||
| **高频** | **10 分钟** | 陆怀瑾 (coo), 刘诗妮 (secretary) | 2 |
|
||||
| **常规** | **15 分钟** | 严维序 (opengineer), 沈路明 (productmanager), 胡蓉 (projectmanager), 梁思筑 (architect), 苏锦绘 (designer), 徐聪 (costcodev), 文墨言 (contentspecialist), 程伯予 (cvexpert), 许言 (prompt-engineer), 钟帧韵 (mediaspecialist), 陆云帆 (taobaospecialist), 顾析策 (marketanalysis), 苏慎 (lawyer) | 13 |
|
||||
|
||||
---
|
||||
|
||||
## 三、部署清单
|
||||
|
||||
### 3.1 ✅ 已完成 — HEARTBEAT.md 模板
|
||||
|
||||
所有 15 个 Agent 的工作区均已部署 HEARTBEAT.md：
|
||||
|
||||
| 工作区 | 频率 | 核心内容 |
|
||||
|--------|------|----------|
|
||||
| `coo/` | 10 min | BIZ-38 模板 + 全局积压巡检 |
|
||||
| `secretary/` | 10 min | BIZ-38 模板 |
|
||||
| `opengineer/` | 10 min | BIZ-38 模板 + 三源检查 |
|
||||
| `projectmanager/` | 10 min | BIZ-38 模板 |
|
||||
| `costcodev/` | 10 min | BIZ-38 模板 |
|
||||
| 其余 10 个 Agent | 15 min | 标准模板 + 三源检查 |
|
||||
|
||||
### 3.2 ✅ 已完成 — 共享心跳脚本
|
||||
|
||||
路径：`shared/scripts/`
|
||||
|
||||
| 文件 | 用途 | 状态 |
|
||||
|------|------|------|
|
||||
| `rate_limiter.py` | 缓存管理 + 请求调度 + 协调轮询 | ✅ 已部署 |
|
||||
| `multica_proxy.py` | Multica CLI 代理 + 缓存封装 | ✅ 已部署 |
|
||||
| `heartbeat_helper.py` | 三源任务检查 + 超时检测 + 心跳入口 | ✅ 已部署 |
|
||||
|
||||
### 3.3 ⬜ 本次部署 — OpenClaw Cron 任务
|
||||
|
||||
使用 OpenClaw Gateway cron 系统创建定时任务，通过 `agentTurn` 隔离会话实现各 Agent 的周期性心跳触发。
|
||||
|
||||
#### Cron Job 规格
|
||||
|
||||
```yaml
|
||||
每个 Agent:
|
||||
schedule:
|
||||
kind: cron
|
||||
expr: "*/10 * * * *" # 高频 Agent
|
||||
# expr: "*/15 * * * *" # 常规 Agent
|
||||
tz: "Asia/Shanghai"
|
||||
sessionTarget: "isolated"
|
||||
payload:
|
||||
kind: "agentTurn"
|
||||
message: "运行心跳检查。执行你的 HEARTBEAT.md 中的三源任务检查。"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、部署执行记录
|
||||
|
||||
### 执行时间：2026-06-24 00:14 CST
|
||||
|
||||
#### 创建的 Cron Job 清单
|
||||
|
||||
| Agent | 频率 | Cron Session | 状态 |
|
||||
|-------|------|-------------|------|
|
||||
| coo (陆怀瑾) | 10 min | isolated agentTurn | ✅ |
|
||||
| secretary (刘诗妮) | 10 min | isolated agentTurn | ✅ |
|
||||
| opengineer (严维序) | 10 min | isolated agentTurn | ✅ |
|
||||
| projectmanager (胡蓉) | 10 min | isolated agentTurn | ✅ |
|
||||
| costcodev (徐聪) | 10 min | isolated agentTurn | ✅ |
|
||||
| productmanager (沈路明) | 15 min | isolated agentTurn | ✅ |
|
||||
| architect (梁思筑) | 15 min | isolated agentTurn | ✅ |
|
||||
| designer (苏锦绘) | 15 min | isolated agentTurn | ✅ |
|
||||
| contentspecialist (文墨言) | 15 min | isolated agentTurn | ✅ |
|
||||
| cvexpert (程伯予) | 15 min | isolated agentTurn | ✅ |
|
||||
| prompt-engineer (许言) | 15 min | isolated agentTurn | ✅ |
|
||||
| mediaspecialist (钟帧韵) | 15 min | isolated agentTurn | ✅ |
|
||||
| taobaospecialist (陆云帆) | 15 min | isolated agentTurn | ✅ |
|
||||
| marketanalysis (顾析策) | 15 min | isolated agentTurn | ✅ |
|
||||
| lawyer (苏慎) | 15 min | isolated agentTurn | ✅ |
|
||||
|
||||
---
|
||||
|
||||
## 五、心跳检查内容
|
||||
|
||||
每次心跳触发后，Agent 在隔离会话中执行以下检查：
|
||||
|
||||
### 5.1 三源任务检查
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[心跳触发] --> B[检查 WorkBoard 待办卡片]
|
||||
A --> C[检查 Multica 待办 Issues]
|
||||
A --> D[检查本地待办文档]
|
||||
B --> E{有待办?}
|
||||
C --> E
|
||||
D --> E
|
||||
E -->|有| F[自动执行任务]
|
||||
E -->|无| G[结束心跳]
|
||||
F --> H[任务完成?]
|
||||
H -->|是| I[更新状态]
|
||||
H -->|否| J[通知 COO]
|
||||
```
|
||||
|
||||
### 5.2 超时检测
|
||||
|
||||
- 进行中任务超过 20 分钟无进展 → 标记"疑似超时"
|
||||
- 确认超时 → 自动恢复流程
|
||||
|
||||
### 5.3 依赖检查
|
||||
|
||||
- 认领任务前检查 `depends_on`
|
||||
- 依赖未满足 → 保持 todo，不认领
|
||||
|
||||
### 5.4 轮次控制
|
||||
|
||||
- 单任务最大 50 轮
|
||||
- 接近 80%（40 轮）→ 预警
|
||||
- 达到上限 → 暂停，通知 COO
|
||||
|
||||
---
|
||||
|
||||
## 六、风险与规避
|
||||
|
||||
| 风险 | 影响 | 应对 |
|
||||
|------|------|------|
|
||||
| 心跳任务自身卡死 | 监控失效 | rate_limiter.py 缓存 + 超时保护 |
|
||||
| 新增 Agent 未配心跳 | 遗漏 | 本方案作为部署 SOP 参考 |
|
||||
| 会话隔离导致上下文丢失 | 心跳重复 | 心跳仅做检查，不承担复杂任务 |
|
||||
| Agent 不在线 | 心跳无响应 | 系统事件 fallback，COO 巡检兜底 |
|
||||
|
||||
---
|
||||
|
||||
## 七、验证方法
|
||||
|
||||
```bash
|
||||
# 检查 cron job 列表
|
||||
openclaw cron list
|
||||
|
||||
# 手动触发一次心跳 for a specific agent
|
||||
openclaw cron run <job-id>
|
||||
|
||||
# 检查心跳脚本健康状态
|
||||
python3 shared/scripts/heartbeat_helper.py <agent_id> --health
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 八、修复记录
|
||||
|
||||
### v1.1 — 2026-06-24
|
||||
|
||||
| 问题 | 修复 |
|
||||
|------|------|
|
||||
| cron delivery 报 Feishu 投递错误 | delivery 从 `announce` 改为 `none`（原方案未指定 delivery，不影响功能） |
|
||||
| Multica workspace_id 未传递 | `multica_proxy.py` 新增 `_inject_workspace_id()`，自动在所有 multica CLI 调用注入 `--workspace-id` |
|
||||
| AGENT_CONFIGS 仅 5 个 Agent | `heartbeat_helper.py` 扩展至全部 15 个 Agent |
|
||||
| COO HEARTBEAT 显示未部署 | 更新 BIZ-38 集成清单表 |
|
||||
|
||||
## 九、后续优化方向
|
||||
|
||||
- [ ] 监控面板集成（BIZ-28 Phase3）
|
||||
- [ ] 心跳结果聚合展示
|
||||
- [ ] Agent 健康状态告警
|
||||
- [ ] 自动 Agent 发现（新增 Agent 自动配置心跳）
|
||||
|
||||
---
|
||||
|
||||
> **运维记录**：严维序 2026-06-24
|
||||
> 所有 15 个 Agent 的 HEARTBEAT.md 已部署，共享脚本已就位，cron 定时器已配置。
|
||||
@@ -1,186 +0,0 @@
|
||||
# HEARTBEAT.md 增强模板
|
||||
|
||||
> 版本：v2.0
|
||||
> 来源：BIZ-13 运行稳定性保障方案
|
||||
> 用途：为所有 Agent HEARTBEAT.md 增加运行稳定性保障能力
|
||||
|
||||
---
|
||||
|
||||
## 全局增强规则（所有 Agent 必须包含）
|
||||
|
||||
### 1. 🛡️ 超时检测与自动恢复
|
||||
|
||||
```markdown
|
||||
## 🛡️ 超时检测与自动恢复
|
||||
|
||||
> **核心规则：每次心跳，检查自己是否有任务超时未完成。**
|
||||
|
||||
### 超时阈值
|
||||
|
||||
| Agent 类型 | 心跳频率 | 单任务超时 |
|
||||
|------------|----------|------------|
|
||||
| 高频（secretary/coo） | 10 分钟 | 60 分钟 |
|
||||
| 开发（costcodev/architect/opengineer/designer） | 15 分钟 | 120 分钟 |
|
||||
| 业务（其他 Agent） | 15 分钟 | 90 分钟 |
|
||||
|
||||
### 检测流程
|
||||
|
||||
每次心跳执行：
|
||||
1. 获取自己的 `status=in_progress` 的 WorkBoard 卡片
|
||||
2. 计算 `当前时间 - started_at`
|
||||
3. 如果超过超时阈值 → 进入自动恢复流程
|
||||
|
||||
### 自动恢复流程
|
||||
|
||||
```
|
||||
检测到任务超时
|
||||
↓
|
||||
检查最近日志（是否有实质性进展）
|
||||
↓
|
||||
┌──────────┴──────────┐
|
||||
│ │
|
||||
有进展（< 3轮无产出） 无进展（>= 3轮无产出）
|
||||
│ │
|
||||
延长超时 + 记录日志 自动恢复：
|
||||
│ ├─ 尝试重新执行当前步骤
|
||||
更新 heartbeat ├─ 仍失败 → 释放卡片
|
||||
└─ 通知 COO 介入
|
||||
```
|
||||
|
||||
### ⚠️ 超时告警
|
||||
|
||||
- 第 1 次超时：自动恢复，不告警
|
||||
- 第 2 次超时：通知 COO
|
||||
- 第 3 次超时：通知 Vincent，卡片标为 blocked
|
||||
```
|
||||
|
||||
### 2. 🔗 依赖检查前置
|
||||
|
||||
```markdown
|
||||
## 🔗 依赖检查前置
|
||||
|
||||
> **核心规则：认领任务前，必须检查所有依赖是否已完成。**
|
||||
|
||||
### 检查流程
|
||||
|
||||
1. 获取任务的 `depends_on` 列表
|
||||
2. 对每个依赖，查询其状态
|
||||
3. 如果任一依赖未完成 → 不认领该任务，等待下次心跳
|
||||
4. 如果所有依赖已完成 → 正常认领并执行
|
||||
|
||||
### 异常处理
|
||||
|
||||
- 依赖任务已取消 → 向上报告，由 COO 决策
|
||||
- 依赖任务超时无响应 → 通知依赖方和 COO
|
||||
- 循环依赖 → 自动检测并报告给 COO
|
||||
```
|
||||
|
||||
### 3. 🔄 最大轮次限制
|
||||
|
||||
```markdown
|
||||
## 🔄 最大轮次限制
|
||||
|
||||
> **核心规则：单任务不能无限循环执行。**
|
||||
|
||||
| Agent 类型 | 最大对话轮次 | 超限处理 |
|
||||
|------------|-------------|----------|
|
||||
| 高频（secretary/coo） | 50 | 自动暂停，通知创建者 |
|
||||
| 开发（costcodev/architect/opengineer） | 100 | 自动暂停，记录日志摘要 |
|
||||
| 业务（其他 Agent） | 30 | 自动暂停，通知创建者 |
|
||||
|
||||
### 检测方式
|
||||
|
||||
每次心跳检查 `in_progress` 任务的会话轮次：
|
||||
- 接近上限（80%）→ 在心跳日志中标记警告
|
||||
- 达到上限 → 自动暂停任务，保存当前状态
|
||||
```
|
||||
|
||||
### 4. 📊 上下文控制
|
||||
|
||||
```markdown
|
||||
## 📊 上下文控制（Token 管理）
|
||||
|
||||
> **核心规则：避免上下文溢出导致任务中断。**
|
||||
|
||||
### 策略
|
||||
|
||||
1. **引用代替填塞**：Agent 配置文件中只保留核心规则，详细信息存 docs/ 目录
|
||||
2. **分块读取**：超大文件分块读取，避免一次性加载
|
||||
3. **清理过期信息**：每轮对话前清理上一轮的工具输出（仅保留关键结果）
|
||||
4. **合并查询**：多个 Agent 相同查询由 COO 统一执行后广播
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 心跳频率分级
|
||||
|
||||
```markdown
|
||||
## ⏱️ 心跳触发频率
|
||||
|
||||
- **高频 Agent（secretary / coo）**: 每 10 分钟
|
||||
- **开发 Agent（costcodev / architect / opengineer / designer）**: 每 15 分钟
|
||||
- **业务 Agent（projectmanager / productmanager / taobaospecialist / contentspecialist / mediaspecialist / cvexpert / marketanalysis / lawyer）**: 每 15 分钟
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 全局关键规则（增强版）
|
||||
|
||||
```markdown
|
||||
## ⚠️ 全局关键规则
|
||||
|
||||
1. **心跳不打断对话** — 如果用户正在与 Agent 对话，心跳逻辑延后执行
|
||||
2. **非紧急事项延后汇报** — 等下一轮心跳或用户主动询问时再汇报
|
||||
3. **发现任务立即执行，不得请示** — 用户在大多数时候不在线，请示=任务卡死
|
||||
4. **依赖检查前置** — 认领任务前必须检查所有依赖是否已完成
|
||||
5. **超时自动恢复** — 任务超时自动尝试恢复，3 次失败后升级
|
||||
6. **轮次限制** — 单任务达上限后自动暂停，防止无限循环
|
||||
7. **上下文控制** — 引用代替填塞，避免 Token 溢出
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 各 Agent 类型模板
|
||||
|
||||
### 高频 Agent 模板（secretary/coo）
|
||||
|
||||
在原有专属心跳清单基础上，增加：
|
||||
```markdown
|
||||
### 🛡️ 稳定性保障清单
|
||||
|
||||
1. ✅ 超时检测：检查 in_progress 任务是否超时（阈值 60 分钟）
|
||||
2. ✅ 依赖检查：新任务认领前检查所有 depends_on
|
||||
3. ✅ 轮次检查：当前任务是否接近 50 轮上限
|
||||
4. ✅ 上下文检查：HEARTBEAT.md/AGENTS.md 文件大小是否 < 5KB
|
||||
```
|
||||
|
||||
### 开发 Agent 模板（costcodev/architect/opengineer/designer）
|
||||
|
||||
```markdown
|
||||
### 🛡️ 稳定性保障清单
|
||||
|
||||
1. ✅ 超时检测：检查 in_progress 任务是否超时（阈值 120 分钟）
|
||||
2. ✅ 依赖检查：新任务认领前检查所有 depends_on
|
||||
3. ✅ 轮次检查：当前任务是否接近 100 轮上限
|
||||
4. ✅ 编译/测试检查：如有自动化测试，确认通过
|
||||
```
|
||||
|
||||
### 业务 Agent 模板（其他 Agent）
|
||||
|
||||
```markdown
|
||||
### 🛡️ 稳定性保障清单
|
||||
|
||||
1. ✅ 超时检测：检查 in_progress 任务是否超时（阈值 90 分钟）
|
||||
2. ✅ 依赖检查：新任务认领前检查所有 depends_on
|
||||
3. ✅ 轮次检查：当前任务是否接近 30 轮上限
|
||||
4. ✅ 输出质量检查：确认最近产出符合质量标准
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 实施说明
|
||||
|
||||
1. 此模板由 COO（陆怀瑾）编制，经 Vincent 审阅批准后实施
|
||||
2. 模板中的 agent_id 需替换为各 Agent 的实际标识
|
||||
3. 无需移除各 Agent 原有的专属心跳清单，只需追加稳定性保障清单
|
||||
4. 修改后的文件需提交到 EnterpriseArchitect git 仓库
|
||||
@@ -0,0 +1,772 @@
|
||||
"""
|
||||
BIZ-26: API 请求优先级队列 + 令牌桶限流器
|
||||
|
||||
实现方案参考：plans/BIZ-13_运行稳定性保障方案.md
|
||||
|
||||
功能清单：
|
||||
1. 四级优先级请求队列（紧急 > 高 > 正常 > 低）
|
||||
2. 令牌桶限流器（40 RPM 上限）
|
||||
3. 超限自动降级和等待策略
|
||||
4. 请求合并（COO 统一轮询）
|
||||
5. 查询结果缓存（WorkBoard 5 分钟、配置 1 小时、知识库 1 天）
|
||||
|
||||
作者：徐聪（costcodev）
|
||||
日期：2026-06-23
|
||||
"""
|
||||
|
||||
import time
|
||||
import threading
|
||||
import queue
|
||||
import hashlib
|
||||
import json
|
||||
from typing import Any, Callable, Dict, List, Optional, Tuple
|
||||
from dataclasses import dataclass, field
|
||||
from enum import IntEnum
|
||||
from datetime import datetime, timedelta
|
||||
|
||||
|
||||
# ============================================================================
|
||||
# 网关识别：只对 NVIDIA 网关限流
|
||||
# ============================================================================
|
||||
|
||||
NVIDIA_GATEWAY_ALIASES = {
|
||||
"nvidia",
|
||||
"nvidia-gateway",
|
||||
"nvidia_gateway",
|
||||
"nvidiavx18088980513",
|
||||
}
|
||||
|
||||
UNLIMITED_GATEWAY_ALIASES = {
|
||||
"volcengine",
|
||||
"volcengine-plan",
|
||||
"siliconflow",
|
||||
"deepseek",
|
||||
"deepseek-api",
|
||||
}
|
||||
|
||||
|
||||
def normalize_gateway_name(value: Optional[str]) -> Optional[str]:
|
||||
"""
|
||||
归一化网关/模型名称。
|
||||
|
||||
输入可以是：
|
||||
- provider: nvidia / volcengine-plan / siliconflow / deepseek
|
||||
- model: nvidiavx18088980513/deepseek-ai/deepseek-v4-pro
|
||||
- model: volcengine-plan/ark-code-latest
|
||||
|
||||
返回 provider 前缀的小写形式。未知则返回 None。
|
||||
"""
|
||||
if not value:
|
||||
return None
|
||||
text = str(value).strip().lower()
|
||||
if not text:
|
||||
return None
|
||||
return text.split("/", 1)[0]
|
||||
|
||||
|
||||
def is_nvidia_gateway(value: Optional[str]) -> bool:
|
||||
"""判断请求是否走 NVIDIA 网关。未知网关默认不限流。"""
|
||||
provider = normalize_gateway_name(value)
|
||||
if provider is None:
|
||||
return False
|
||||
if provider in NVIDIA_GATEWAY_ALIASES:
|
||||
return True
|
||||
if provider in UNLIMITED_GATEWAY_ALIASES:
|
||||
return False
|
||||
return provider.startswith("nvidia")
|
||||
|
||||
|
||||
# ============================================================================
|
||||
# 优先级枚举
|
||||
# ============================================================================
|
||||
|
||||
class Priority(IntEnum):
|
||||
"""请求优先级：数值越小优先级越高"""
|
||||
URGENT = 1 # 紧急：Vincent 直接任务
|
||||
HIGH = 2 # 高：阻塞性任务
|
||||
NORMAL = 3 # 正常：常规任务
|
||||
LOW = 4 # 低：后台优化任务
|
||||
|
||||
|
||||
# ============================================================================
|
||||
# 请求数据类
|
||||
# ============================================================================
|
||||
|
||||
@dataclass(order=True)
|
||||
class Request:
|
||||
"""优先级队列中的请求项"""
|
||||
priority: int
|
||||
timestamp: float = field(compare=False)
|
||||
request_id: str = field(compare=False)
|
||||
payload: Any = field(compare=False)
|
||||
callback: Optional[Callable] = field(compare=False, default=None)
|
||||
fallback_model: Optional[str] = field(compare=False, default=None)
|
||||
gateway: Optional[str] = field(compare=False, default=None)
|
||||
model: Optional[str] = field(compare=False, default=None)
|
||||
|
||||
def __post_init__(self):
|
||||
if self.timestamp is None:
|
||||
self.timestamp = time.time()
|
||||
if self.request_id is None:
|
||||
self.request_id = self._generate_id()
|
||||
|
||||
@staticmethod
|
||||
def _generate_id() -> str:
|
||||
"""生成请求 ID"""
|
||||
return hashlib.md5(f"{time.time()}-{threading.current_thread().ident}".encode()).hexdigest()[:12]
|
||||
|
||||
|
||||
# ============================================================================
|
||||
# 令牌桶限流器
|
||||
# ============================================================================
|
||||
|
||||
class TokenBucket:
|
||||
"""
|
||||
NVIDIA 网关专用令牌桶限流器
|
||||
|
||||
注意：令牌桶本身只负责节流算法；是否启用由 RequestScheduler._should_rate_limit()
|
||||
按 gateway/model 判断。volcengine-plan、siliconflow、DeepSeek 等非 NVIDIA 网关不会进入此桶。
|
||||
|
||||
参数：
|
||||
rate: 令牌生成速率（个/秒），默认 40 RPM = 0.67 个/秒
|
||||
capacity: 桶容量（最大令牌数），默认 40
|
||||
"""
|
||||
|
||||
def __init__(self, rate: float = 40/60, capacity: int = 40):
|
||||
self.rate = rate # 令牌/秒
|
||||
self.capacity = capacity
|
||||
self.tokens = capacity
|
||||
self.last_update = time.time()
|
||||
self._lock = threading.Lock()
|
||||
|
||||
def _refill(self) -> None:
|
||||
"""补充令牌（内部调用，需要持有锁）"""
|
||||
now = time.time()
|
||||
elapsed = now - self.last_update
|
||||
new_tokens = elapsed * self.rate
|
||||
self.tokens = min(self.capacity, self.tokens + new_tokens)
|
||||
self.last_update = now
|
||||
|
||||
def consume(self, tokens: int = 1) -> bool:
|
||||
"""
|
||||
尝试消费令牌
|
||||
|
||||
返回：
|
||||
True: 成功消费
|
||||
False: 令牌不足
|
||||
"""
|
||||
with self._lock:
|
||||
self._refill()
|
||||
if self.tokens >= tokens:
|
||||
self.tokens -= tokens
|
||||
return True
|
||||
return False
|
||||
|
||||
def wait_for_token(self, timeout: Optional[float] = None) -> bool:
|
||||
"""
|
||||
等待直到有可用令牌
|
||||
|
||||
参数：
|
||||
timeout: 最大等待时间（秒），None 表示无限等待
|
||||
|
||||
返回：
|
||||
True: 成功获取令牌
|
||||
False: 超时
|
||||
"""
|
||||
start_time = time.time()
|
||||
while True:
|
||||
if self.consume():
|
||||
return True
|
||||
|
||||
if timeout is not None:
|
||||
elapsed = time.time() - start_time
|
||||
if elapsed >= timeout:
|
||||
return False
|
||||
|
||||
# 计算等待时间（直到下一个令牌生成）
|
||||
with self._lock:
|
||||
self._refill()
|
||||
if self.tokens < 1:
|
||||
wait_time = (1 - self.tokens) / self.rate
|
||||
else:
|
||||
wait_time = 0.01
|
||||
|
||||
# 等待后重试
|
||||
time_to_wait = min(wait_time, 0.1) # 最多等待 100ms
|
||||
if timeout is not None:
|
||||
remaining = timeout - (time.time() - start_time)
|
||||
if remaining <= 0:
|
||||
return False
|
||||
time_to_wait = min(time_to_wait, remaining)
|
||||
|
||||
time.sleep(time_to_wait)
|
||||
|
||||
def get_status(self) -> Dict[str, Any]:
|
||||
"""获取限流器状态"""
|
||||
with self._lock:
|
||||
self._refill()
|
||||
return {
|
||||
"tokens": round(self.tokens, 2),
|
||||
"capacity": self.capacity,
|
||||
"rate_per_second": round(self.rate, 3),
|
||||
"rate_per_minute": round(self.rate * 60, 1),
|
||||
"utilization": round(1 - self.tokens / self.capacity, 2)
|
||||
}
|
||||
|
||||
|
||||
# ============================================================================
|
||||
# 缓存管理器
|
||||
# ============================================================================
|
||||
|
||||
@dataclass
|
||||
class CacheEntry:
|
||||
"""缓存条目"""
|
||||
value: Any
|
||||
expires_at: float
|
||||
created_at: float = field(default_factory=time.time)
|
||||
access_count: int = field(default=0)
|
||||
|
||||
|
||||
class CacheManager:
|
||||
"""
|
||||
查询结果缓存管理器
|
||||
|
||||
缓存策略：
|
||||
- WorkBoard 状态：5 分钟
|
||||
- Agent 配置：1 小时
|
||||
- 知识库内容：1 天
|
||||
- 用户信息：1 天
|
||||
"""
|
||||
|
||||
# 默认 TTL 配置（秒）
|
||||
DEFAULT_TTL = {
|
||||
"workboard": 5 * 60, # 5 分钟
|
||||
"config": 1 * 60 * 60, # 1 小时
|
||||
"knowledge": 24 * 60 * 60, # 1 天
|
||||
"user": 24 * 60 * 60, # 1 天
|
||||
}
|
||||
|
||||
def __init__(self):
|
||||
self._cache: Dict[str, CacheEntry] = {}
|
||||
self._lock = threading.Lock()
|
||||
|
||||
def _generate_key(self, category: str, query: Any) -> str:
|
||||
"""生成缓存键"""
|
||||
query_str = json.dumps(query, sort_keys=True) if not isinstance(query, str) else query
|
||||
return hashlib.md5(f"{category}:{query_str}".encode()).hexdigest()
|
||||
|
||||
def get(self, category: str, query: Any) -> Optional[Any]:
|
||||
"""
|
||||
获取缓存
|
||||
|
||||
参数：
|
||||
category: 缓存类别（workboard/config/knowledge/user）
|
||||
query: 查询条件（用于生成缓存键）
|
||||
|
||||
返回：
|
||||
缓存值，如果不存在或已过期则返回 None
|
||||
"""
|
||||
key = self._generate_key(category, query)
|
||||
|
||||
with self._lock:
|
||||
entry = self._cache.get(key)
|
||||
if entry is None:
|
||||
return None
|
||||
|
||||
# 检查是否过期
|
||||
if time.time() > entry.expires_at:
|
||||
del self._cache[key]
|
||||
return None
|
||||
|
||||
# 更新访问计数
|
||||
entry.access_count += 1
|
||||
return entry.value
|
||||
|
||||
def set(self, category: str, query: Any, value: Any, ttl: Optional[int] = None) -> None:
|
||||
"""
|
||||
设置缓存
|
||||
|
||||
参数：
|
||||
category: 缓存类别
|
||||
query: 查询条件
|
||||
value: 缓存值
|
||||
ttl: 存活时间（秒），None 表示使用默认值
|
||||
"""
|
||||
key = self._generate_key(category, query)
|
||||
|
||||
if ttl is None:
|
||||
ttl = self.DEFAULT_TTL.get(category, 300) # 默认 5 分钟
|
||||
|
||||
with self._lock:
|
||||
self._cache[key] = CacheEntry(
|
||||
value=value,
|
||||
expires_at=time.time() + ttl
|
||||
)
|
||||
|
||||
def delete(self, category: str, query: Any) -> bool:
|
||||
"""删除缓存"""
|
||||
key = self._generate_key(category, query)
|
||||
with self._lock:
|
||||
if key in self._cache:
|
||||
del self._cache[key]
|
||||
return True
|
||||
return False
|
||||
|
||||
def clear_expired(self) -> int:
|
||||
"""清理所有过期缓存，返回清理数量"""
|
||||
now = time.time()
|
||||
with self._lock:
|
||||
expired_keys = [k for k, v in self._cache.items() if now > v.expires_at]
|
||||
for key in expired_keys:
|
||||
del self._cache[key]
|
||||
return len(expired_keys)
|
||||
|
||||
def get_stats(self) -> Dict[str, Any]:
|
||||
"""获取缓存统计"""
|
||||
now = time.time()
|
||||
with self._lock:
|
||||
total = len(self._cache)
|
||||
expired = sum(1 for v in self._cache.values() if now > v.expires_at)
|
||||
|
||||
# 按类别统计
|
||||
by_category: Dict[str, int] = {}
|
||||
for key, entry in self._cache.items():
|
||||
# 从 key 中提取 category（格式：category:hash）
|
||||
category = key.split(":")[0] if ":" in key else "unknown"
|
||||
by_category[category] = by_category.get(category, 0) + 1
|
||||
|
||||
return {
|
||||
"total_entries": total,
|
||||
"expired_entries": expired,
|
||||
"valid_entries": total - expired,
|
||||
"by_category": by_category
|
||||
}
|
||||
|
||||
def clear(self) -> None:
|
||||
"""清空所有缓存"""
|
||||
with self._lock:
|
||||
self._cache.clear()
|
||||
|
||||
|
||||
# ============================================================================
|
||||
# 请求调度器
|
||||
# ============================================================================
|
||||
|
||||
class RequestScheduler:
|
||||
"""
|
||||
请求调度器：结合优先级队列和令牌桶限流
|
||||
|
||||
功能：
|
||||
1. 接收不同优先级的请求
|
||||
2. 按优先级和 FIF0 顺序调度
|
||||
3. 通过令牌桶控制发送速率
|
||||
4. 支持降级策略（低优先级切备用模型）
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
rate: float = 40/60,
|
||||
capacity: int = 40,
|
||||
enable_cache: bool = True
|
||||
):
|
||||
self.token_bucket = TokenBucket(rate=rate, capacity=capacity)
|
||||
self.cache = CacheManager() if enable_cache else None
|
||||
|
||||
# 优先级队列（使用 heap 实现）
|
||||
self.request_queue: queue.PriorityQueue[Request] = queue.PriorityQueue()
|
||||
|
||||
# 工作线程
|
||||
self._worker_thread: Optional[threading.Thread] = None
|
||||
self._running = False
|
||||
self._lock = threading.Lock()
|
||||
|
||||
# 统计信息
|
||||
self.stats = {
|
||||
"total_requests": 0,
|
||||
"completed_requests": 0,
|
||||
"failed_requests": 0,
|
||||
"fallback_requests": 0,
|
||||
"cache_hits": 0,
|
||||
"cache_misses": 0,
|
||||
}
|
||||
|
||||
def start(self) -> None:
|
||||
"""启动调度器工作线程"""
|
||||
if self._running:
|
||||
return
|
||||
|
||||
self._running = True
|
||||
self._worker_thread = threading.Thread(target=self._worker_loop, daemon=True)
|
||||
self._worker_thread.start()
|
||||
|
||||
def stop(self) -> None:
|
||||
"""停止调度器"""
|
||||
self._running = False
|
||||
if self._worker_thread:
|
||||
self._worker_thread.join(timeout=5.0)
|
||||
|
||||
def _worker_loop(self) -> None:
|
||||
"""工作线程主循环"""
|
||||
while self._running:
|
||||
try:
|
||||
# 从队列获取请求（带超时）
|
||||
request = self.request_queue.get(timeout=1.0)
|
||||
self._process_request(request)
|
||||
except queue.Empty:
|
||||
continue
|
||||
except Exception as e:
|
||||
# 记录错误但不中断工作线程
|
||||
print(f"[RequestScheduler] Worker error: {e}")
|
||||
|
||||
def _extract_gateway_hint(self, request: Request) -> Optional[str]:
|
||||
"""从 request.gateway / request.model / payload 中提取网关提示。"""
|
||||
if request.gateway:
|
||||
return request.gateway
|
||||
if request.model:
|
||||
return request.model
|
||||
if isinstance(request.payload, dict):
|
||||
for key in ("gateway", "provider", "model", "model_id"):
|
||||
value = request.payload.get(key)
|
||||
if value:
|
||||
return str(value)
|
||||
return None
|
||||
|
||||
def _should_rate_limit(self, request: Request) -> bool:
|
||||
"""
|
||||
只对 NVIDIA 网关请求启用令牌桶。
|
||||
|
||||
设计原则：未知网关默认不限制，避免误伤 volcengine-plan / siliconflow / DeepSeek
|
||||
等其他 API 网关。要被限流，调用方必须显式传 gateway/model，且能识别为 NVIDIA。
|
||||
"""
|
||||
return is_nvidia_gateway(self._extract_gateway_hint(request))
|
||||
|
||||
def _process_request(self, request: Request) -> None:
|
||||
"""
|
||||
处理单个请求
|
||||
|
||||
策略：
|
||||
1. 高优先级（URGENT/HIGH）：等待令牌
|
||||
2. 低优先级（NORMAL/LOW）：尝试获取令牌，失败则降级或丢弃
|
||||
"""
|
||||
self.stats["total_requests"] += 1
|
||||
|
||||
# 只对 NVIDIA 网关请求启用令牌桶；其他网关直接执行
|
||||
if not self._should_rate_limit(request):
|
||||
self._execute_request(request)
|
||||
return
|
||||
|
||||
# NVIDIA 网关请求：尝试获取令牌
|
||||
if request.priority <= Priority.HIGH:
|
||||
# 高优先级：无限等待
|
||||
got_token = self.token_bucket.wait_for_token(timeout=None)
|
||||
else:
|
||||
# 低优先级：最多等待 2 秒
|
||||
got_token = self.token_bucket.wait_for_token(timeout=2.0)
|
||||
|
||||
if got_token:
|
||||
# 成功获取令牌，执行请求
|
||||
self._execute_request(request)
|
||||
else:
|
||||
# 未能获取令牌，执行降级策略
|
||||
self._handle_fallback(request)
|
||||
|
||||
def _execute_request(self, request: Request) -> None:
|
||||
"""执行请求"""
|
||||
try:
|
||||
if request.callback:
|
||||
result = request.callback(request.payload)
|
||||
self.stats["completed_requests"] += 1
|
||||
return result
|
||||
else:
|
||||
self.stats["completed_requests"] += 1
|
||||
except Exception as e:
|
||||
self.stats["failed_requests"] += 1
|
||||
print(f"[RequestScheduler] Request {request.request_id} failed: {e}")
|
||||
raise
|
||||
|
||||
def _handle_fallback(self, request: Request) -> None:
|
||||
"""处理降级（令牌不足）"""
|
||||
self.stats["fallback_requests"] += 1
|
||||
|
||||
if request.priority == Priority.LOW:
|
||||
# 低优先级：直接丢弃或切换到备用模型
|
||||
print(f"[RequestScheduler] Low priority request {request.request_id} dropped due to rate limit")
|
||||
else:
|
||||
# 正常优先级：放回队列稍后重试
|
||||
request.timestamp = time.time()
|
||||
self.request_queue.put(request)
|
||||
|
||||
def submit(
|
||||
self,
|
||||
payload: Any,
|
||||
priority: Priority = Priority.NORMAL,
|
||||
callback: Optional[Callable] = None,
|
||||
fallback_model: Optional[str] = None,
|
||||
request_id: Optional[str] = None,
|
||||
gateway: Optional[str] = None,
|
||||
model: Optional[str] = None
|
||||
) -> str:
|
||||
"""
|
||||
提交请求到调度队列
|
||||
|
||||
参数：
|
||||
payload: 请求数据
|
||||
priority: 优先级
|
||||
callback: 回调函数
|
||||
fallback_model: 备用模型名称
|
||||
request_id: 请求 ID（可选，默认自动生成）
|
||||
|
||||
返回：
|
||||
请求 ID
|
||||
"""
|
||||
req = Request(
|
||||
priority=priority,
|
||||
timestamp=time.time(),
|
||||
request_id=request_id,
|
||||
payload=payload,
|
||||
callback=callback,
|
||||
fallback_model=fallback_model,
|
||||
gateway=gateway,
|
||||
model=model
|
||||
)
|
||||
|
||||
self.request_queue.put(req)
|
||||
return req.request_id
|
||||
|
||||
def submit_sync(
|
||||
self,
|
||||
payload: Any,
|
||||
priority: Priority = Priority.NORMAL,
|
||||
timeout: Optional[float] = None
|
||||
) -> Any:
|
||||
"""
|
||||
同步提交并等待结果
|
||||
|
||||
参数：
|
||||
payload: 请求数据
|
||||
priority: 优先级
|
||||
timeout: 超时时间（秒）
|
||||
|
||||
返回：
|
||||
请求结果
|
||||
"""
|
||||
result_holder = {"result": None, "error": None, "done": False}
|
||||
condition = threading.Condition()
|
||||
|
||||
def callback(data):
|
||||
with condition:
|
||||
try:
|
||||
# 实际执行逻辑（这里只是一个占位符）
|
||||
result_holder["result"] = data
|
||||
except Exception as e:
|
||||
result_holder["error"] = e
|
||||
finally:
|
||||
result_holder["done"] = True
|
||||
condition.notify_all()
|
||||
|
||||
# 提交请求
|
||||
self.submit(payload=payload, priority=priority, callback=lambda _: callback(payload))
|
||||
|
||||
# 等待结果
|
||||
with condition:
|
||||
if not result_holder["done"]:
|
||||
condition.wait(timeout=timeout)
|
||||
|
||||
if result_holder["error"]:
|
||||
raise result_holder["error"]
|
||||
return result_holder["result"]
|
||||
|
||||
def get_queue_size(self) -> int:
|
||||
"""获取当前队列大小"""
|
||||
return self.request_queue.qsize()
|
||||
|
||||
def get_status(self) -> Dict[str, Any]:
|
||||
"""获取调度器状态"""
|
||||
return {
|
||||
"running": self._running,
|
||||
"queue_size": self.get_queue_size(),
|
||||
"token_bucket": self.token_bucket.get_status(),
|
||||
"cache": self.cache.get_stats() if self.cache else None,
|
||||
"stats": self.stats.copy()
|
||||
}
|
||||
|
||||
|
||||
# ============================================================================
|
||||
# 重试装饰器
|
||||
# ============================================================================
|
||||
|
||||
def retry_with_backoff(
|
||||
max_retries: int = 3,
|
||||
base_delay: float = 1.0,
|
||||
exponential_base: int = 2,
|
||||
jitter: bool = True,
|
||||
exceptions: Tuple = (Exception,)
|
||||
):
|
||||
"""
|
||||
指数退避重试装饰器
|
||||
|
||||
参数：
|
||||
max_retries: 最大重试次数
|
||||
base_delay: 基础延迟（秒）
|
||||
exponential_base: 指数底数
|
||||
jitter: 是否添加随机抖动
|
||||
exceptions: 需要重试的异常类型
|
||||
"""
|
||||
import random
|
||||
|
||||
def decorator(func: Callable) -> Callable:
|
||||
def wrapper(*args, **kwargs):
|
||||
last_exception = None
|
||||
|
||||
for attempt in range(max_retries + 1):
|
||||
try:
|
||||
return func(*args, **kwargs)
|
||||
except exceptions as e:
|
||||
last_exception = e
|
||||
|
||||
if attempt == max_retries:
|
||||
break
|
||||
|
||||
# 计算延迟时间
|
||||
delay = base_delay * (exponential_base ** attempt)
|
||||
if jitter:
|
||||
delay += random.uniform(0, base_delay)
|
||||
|
||||
print(f"[retry_with_backoff] Attempt {attempt + 1} failed: {e}. Retrying in {delay:.2f}s...")
|
||||
time.sleep(delay)
|
||||
|
||||
raise last_exception
|
||||
|
||||
return wrapper
|
||||
return decorator
|
||||
|
||||
|
||||
# ============================================================================
|
||||
# COO 统一轮询器（请求合并）
|
||||
# ============================================================================
|
||||
|
||||
class CoordinatedPoller:
|
||||
"""
|
||||
COO 统一轮询器：替代各 Agent 独立轮询
|
||||
|
||||
功能：
|
||||
1. 定期轮询 WorkBoard
|
||||
2. 广播结果给所有订阅者
|
||||
3. 减少总请求数（40 RPM × N → 40 RPM）
|
||||
"""
|
||||
|
||||
def __init__(self, scheduler: RequestScheduler, poll_interval: int = 15*60):
|
||||
self.scheduler = scheduler
|
||||
self.poll_interval = poll_interval # 轮询间隔（秒）
|
||||
self._subscribers: List[Callable] = []
|
||||
self._running = False
|
||||
self._worker: Optional[threading.Thread] = None
|
||||
|
||||
def subscribe(self, callback: Callable) -> None:
|
||||
"""订阅轮询结果"""
|
||||
self._subscribers.append(callback)
|
||||
|
||||
def unsubscribe(self, callback: Callable) -> None:
|
||||
"""取消订阅"""
|
||||
if callback in self._subscribers:
|
||||
self._subscribers.remove(callback)
|
||||
|
||||
def start(self) -> None:
|
||||
"""启动轮询器"""
|
||||
if self._running:
|
||||
return
|
||||
|
||||
self._running = True
|
||||
self._worker = threading.Thread(target=self._poll_loop, daemon=True)
|
||||
self._worker.start()
|
||||
|
||||
def stop(self) -> None:
|
||||
"""停止轮询器"""
|
||||
self._running = False
|
||||
if self._worker:
|
||||
self._worker.join(timeout=5.0)
|
||||
|
||||
def _poll_loop(self) -> None:
|
||||
"""轮询主循环"""
|
||||
while self._running:
|
||||
try:
|
||||
# 执行轮询（这里只是一个框架，实际逻辑需要接入 multica CLI）
|
||||
result = self._perform_poll()
|
||||
|
||||
# 广播给所有订阅者
|
||||
for subscriber in self._subscribers:
|
||||
try:
|
||||
subscriber(result)
|
||||
except Exception as e:
|
||||
print(f"[CoordinatedPoller] Subscriber callback error: {e}")
|
||||
|
||||
except Exception as e:
|
||||
print(f"[CoordinatedPoller] Poll error: {e}")
|
||||
|
||||
# 等待下一个轮询周期
|
||||
time.sleep(self.poll_interval)
|
||||
|
||||
def _perform_poll(self) -> Dict[str, Any]:
|
||||
"""
|
||||
执行实际轮询
|
||||
|
||||
TODO: 接入 multica CLI:
|
||||
- multica issue list --status in_progress
|
||||
- multica workboard list
|
||||
"""
|
||||
# 这里应该调用 multica CLI
|
||||
# 当前只是返回一个示例结果
|
||||
return {
|
||||
"timestamp": datetime.now().isoformat(),
|
||||
"issues": [],
|
||||
"workboard_cards": []
|
||||
}
|
||||
|
||||
|
||||
# ============================================================================
|
||||
# 使用示例
|
||||
# ============================================================================
|
||||
|
||||
if __name__ == "__main__":
|
||||
# 创建调度器（40 RPM）
|
||||
scheduler = RequestScheduler(rate=40/60, capacity=40)
|
||||
scheduler.start()
|
||||
|
||||
# 示例：提交不同优先级的请求
|
||||
def sample_callback(data):
|
||||
print(f"Processing: {data}")
|
||||
time.sleep(0.5) # 模拟处理时间
|
||||
return "OK"
|
||||
|
||||
# 紧急请求
|
||||
scheduler.submit(
|
||||
payload={"task": "urgent_task"},
|
||||
priority=Priority.URGENT,
|
||||
callback=sample_callback
|
||||
)
|
||||
|
||||
# 正常请求
|
||||
scheduler.submit(
|
||||
payload={"task": "normal_task"},
|
||||
priority=Priority.NORMAL,
|
||||
callback=sample_callback
|
||||
)
|
||||
|
||||
# 低优先级请求
|
||||
scheduler.submit(
|
||||
payload={"task": "low_priority_task"},
|
||||
priority=Priority.LOW,
|
||||
callback=sample_callback
|
||||
)
|
||||
|
||||
# 等待处理完成
|
||||
time.sleep(2)
|
||||
|
||||
# 查看状态
|
||||
print("\n=== Scheduler Status ===")
|
||||
print(json.dumps(scheduler.get_status(), indent=2))
|
||||
|
||||
# 停止调度器
|
||||
scheduler.stop()
|
||||
|
||||
print("\n示例运行完成")
|
||||
@@ -0,0 +1,332 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
BIZ-26 限流器测试脚本
|
||||
|
||||
测试场景：
|
||||
1. 令牌桶限流功能
|
||||
2. 优先级队列调度
|
||||
3. 缓存管理器
|
||||
4. 重试机制
|
||||
5. 429 错误模拟
|
||||
|
||||
运行方式：
|
||||
python3 scripts/test_rate_limiter.py
|
||||
"""
|
||||
|
||||
import sys
|
||||
import time
|
||||
import threading
|
||||
from datetime import datetime
|
||||
|
||||
# 添加脚本目录到路径
|
||||
sys.path.insert(0, "/home/vincent/.openclaw/workspace/costcodev/EnterpriseArchitect/scripts")
|
||||
|
||||
from rate_limiter import (
|
||||
TokenBucket,
|
||||
CacheManager,
|
||||
RequestScheduler,
|
||||
Priority,
|
||||
retry_with_backoff,
|
||||
CoordinatedPoller,
|
||||
is_nvidia_gateway,
|
||||
)
|
||||
|
||||
|
||||
def test_token_bucket():
|
||||
"""测试令牌桶限流器"""
|
||||
print("=" * 60)
|
||||
print("测试 1: 令牌桶限流器")
|
||||
print("=" * 60)
|
||||
|
||||
# 创建限流器：40 RPM = 0.67 令牌/秒
|
||||
bucket = TokenBucket(rate=40/60, capacity=40)
|
||||
|
||||
print(f"\n初始状态：{bucket.get_status()}")
|
||||
|
||||
# 快速消费 10 个令牌
|
||||
print("\n快速消费 10 个令牌...")
|
||||
success_count = 0
|
||||
for i in range(10):
|
||||
if bucket.consume():
|
||||
success_count += 1
|
||||
|
||||
print(f"成功消费：{success_count}/10")
|
||||
print(f"消费后状态：{bucket.get_status()}")
|
||||
|
||||
# 测试等待获取令牌
|
||||
print("\n测试等待获取令牌...")
|
||||
start = time.time()
|
||||
got_token = bucket.wait_for_token(timeout=2.0)
|
||||
elapsed = time.time() - start
|
||||
|
||||
print(f"等待耗时：{elapsed:.3f}s, 获取成功：{got_token}")
|
||||
print(f"等待后状态：{bucket.get_status()}")
|
||||
|
||||
print("\n✅ 令牌桶测试完成\n")
|
||||
|
||||
|
||||
def test_cache_manager():
|
||||
"""测试缓存管理器"""
|
||||
print("=" * 60)
|
||||
print("测试 2: 缓存管理器")
|
||||
print("=" * 60)
|
||||
|
||||
cache = CacheManager()
|
||||
|
||||
# 测试 WorkBoard 缓存（TTL 5 分钟）
|
||||
print("\n1. 设置 WorkBoard 缓存（TTL 5 分钟）")
|
||||
cache.set("workboard", {"query": "status=todo"}, [{"id": "card1", "title": "Test"}])
|
||||
|
||||
# 立即读取
|
||||
result = cache.get("workboard", {"query": "status=todo"})
|
||||
print(f" 立即读取：{result is not None}")
|
||||
|
||||
# 测试配置缓存（TTL 1 小时）
|
||||
print("\n2. 设置配置缓存（TTL 1 小时）")
|
||||
cache.set("config", "agent_list", ["costcodev", "secretary", "coo"])
|
||||
result = cache.get("config", "agent_list")
|
||||
print(f" 读取配置：{result}")
|
||||
|
||||
# 测试缓存统计
|
||||
print("\n3. 缓存统计")
|
||||
stats = cache.get_stats()
|
||||
print(f" 总条目数：{stats['total_entries']}")
|
||||
print(f" 按类别：{stats['by_category']}")
|
||||
|
||||
# 测试缓存删除
|
||||
print("\n4. 删除缓存")
|
||||
deleted = cache.delete("workboard", {"query": "status=todo"})
|
||||
print(f" 删除成功：{deleted}")
|
||||
result = cache.get("workboard", {"query": "status=todo"})
|
||||
print(f" 删除后读取：{result is None}")
|
||||
|
||||
print("\n✅ 缓存管理器测试完成\n")
|
||||
|
||||
|
||||
def test_priority_queue():
|
||||
"""测试优先级队列调度"""
|
||||
print("=" * 60)
|
||||
print("测试 3: 优先级队列调度（简化版，不启动工作线程）")
|
||||
print("=" * 60)
|
||||
|
||||
scheduler = RequestScheduler(rate=40/60, capacity=40, enable_cache=True)
|
||||
|
||||
# 模拟请求处理结果
|
||||
results = []
|
||||
|
||||
def record_result(data):
|
||||
results.append((time.time(), data))
|
||||
return data
|
||||
|
||||
# 提交不同优先级的请求（不启动工作线程，只测试队列）
|
||||
print("\n提交请求（按顺序）:")
|
||||
scheduler.submit(
|
||||
payload={"task": "normal_1"},
|
||||
priority=Priority.NORMAL,
|
||||
callback=record_result
|
||||
)
|
||||
print(" 1. 正常优先级：normal_1")
|
||||
|
||||
scheduler.submit(
|
||||
payload={"task": "urgent_1"},
|
||||
priority=Priority.URGENT,
|
||||
callback=record_result
|
||||
)
|
||||
print(" 2. 紧急优先级：urgent_1")
|
||||
|
||||
scheduler.submit(
|
||||
payload={"task": "low_1"},
|
||||
priority=Priority.LOW,
|
||||
callback=record_result
|
||||
)
|
||||
print(" 3. 低优先级：low_1")
|
||||
|
||||
scheduler.submit(
|
||||
payload={"task": "high_1"},
|
||||
priority=Priority.HIGH,
|
||||
callback=record_result
|
||||
)
|
||||
print(" 4. 高优先级：high_1")
|
||||
|
||||
# 查看队列大小
|
||||
print(f"\n队列大小：{scheduler.get_queue_size()}")
|
||||
|
||||
# 查看状态
|
||||
status = scheduler.get_status()
|
||||
print(f"初始令牌数：{status['token_bucket']['tokens']}")
|
||||
|
||||
print("\n✅ 优先级队列测试完成（仅提交，未处理）\n")
|
||||
|
||||
|
||||
def test_retry_decorator():
|
||||
"""测试重试装饰器"""
|
||||
print("=" * 60)
|
||||
print("测试 4: 重试装饰器")
|
||||
print("=" * 60)
|
||||
|
||||
attempt_count = [0]
|
||||
|
||||
@retry_with_backoff(max_retries=3, base_delay=0.1, jitter=False)
|
||||
def flaky_function():
|
||||
attempt_count[0] += 1
|
||||
if attempt_count[0] < 3:
|
||||
raise Exception(f"模拟失败 (尝试 {attempt_count[0]})")
|
||||
return f"成功 (尝试 {attempt_count[0]})"
|
||||
|
||||
print("\n调用易失败函数（前 2 次失败，第 3 次成功）...")
|
||||
start = time.time()
|
||||
result = flaky_function()
|
||||
elapsed = time.time() - start
|
||||
|
||||
print(f"结果：{result}")
|
||||
print(f"总尝试次数：{attempt_count[0]}")
|
||||
print(f"总耗时：{elapsed:.3f}s")
|
||||
|
||||
print("\n✅ 重试装饰器测试完成\n")
|
||||
|
||||
|
||||
def test_coordinated_poller():
|
||||
"""测试统一轮询器"""
|
||||
print("=" * 60)
|
||||
print("测试 5: COO 统一轮询器（简化版，短间隔测试）")
|
||||
print("=" * 60)
|
||||
|
||||
scheduler = RequestScheduler(rate=40/60, capacity=40)
|
||||
poller = CoordinatedPoller(scheduler, poll_interval=2) # 2 秒轮询一次（测试用）
|
||||
|
||||
received_results = []
|
||||
|
||||
def on_poll_result(result):
|
||||
received_results.append((datetime.now().strftime("%H:%M:%S"), result))
|
||||
print(f" [{datetime.now().strftime('%H:%M:%S')}] 收到轮询结果")
|
||||
|
||||
poller.subscribe(on_poll_result)
|
||||
|
||||
print("\n启动轮询器（轮询间隔 2 秒，运行 5 秒后停止）...")
|
||||
poller.start()
|
||||
|
||||
# 等待 5 秒
|
||||
time.sleep(5)
|
||||
|
||||
poller.stop()
|
||||
|
||||
print(f"\n收到结果次数：{len(received_results)}")
|
||||
for ts, result in received_results:
|
||||
print(f" {ts}: {result['timestamp'][:19]}")
|
||||
|
||||
print("\n✅ 统一轮询器测试完成\n")
|
||||
|
||||
|
||||
def test_rate_limit_stress():
|
||||
"""压力测试：快速提交大量请求"""
|
||||
print("=" * 60)
|
||||
print("测试 6: 压力测试（40 RPM 限制下提交 50 个请求）")
|
||||
print("=" * 60)
|
||||
|
||||
scheduler = RequestScheduler(rate=40/60, capacity=40, enable_cache=True)
|
||||
scheduler.start()
|
||||
|
||||
completed = []
|
||||
failed = []
|
||||
lock = threading.Lock()
|
||||
|
||||
def callback(data):
|
||||
with lock:
|
||||
completed.append(data)
|
||||
return data
|
||||
|
||||
print("\n快速提交 50 个请求...")
|
||||
start_time = time.time()
|
||||
|
||||
for i in range(50):
|
||||
priority = Priority.NORMAL if i % 10 != 0 else Priority.URGENT
|
||||
scheduler.submit(
|
||||
payload={"index": i, "provider": "nvidia"},
|
||||
priority=priority,
|
||||
callback=callback,
|
||||
gateway="nvidia"
|
||||
)
|
||||
|
||||
print("提交完成，等待处理...")
|
||||
|
||||
# 等待 10 秒
|
||||
time.sleep(10)
|
||||
|
||||
elapsed = time.time() - start_time
|
||||
|
||||
# 查看统计
|
||||
status = scheduler.get_status()
|
||||
print(f"\n耗时：{elapsed:.2f}s")
|
||||
print(f"队列大小：{status['queue_size']}")
|
||||
print(f"已完成：{status['stats']['completed_requests']}")
|
||||
print(f"失败：{status['stats']['failed_requests']}")
|
||||
print(f"降级：{status['stats']['fallback_requests']}")
|
||||
print(f"令牌桶状态：{status['token_bucket']}")
|
||||
|
||||
scheduler.stop()
|
||||
|
||||
print("\n✅ 压力测试完成\n")
|
||||
|
||||
|
||||
def test_gateway_scope():
|
||||
"""测试限流范围：只对 NVIDIA 网关生效"""
|
||||
print("=" * 60)
|
||||
print("测试 7: 网关范围识别（只限 NVIDIA）")
|
||||
print("=" * 60)
|
||||
|
||||
assert is_nvidia_gateway("nvidia") is True
|
||||
assert is_nvidia_gateway("nvidiavx18088980513/deepseek-ai/deepseek-v4-pro") is True
|
||||
assert is_nvidia_gateway("volcengine-plan/ark-code-latest") is False
|
||||
assert is_nvidia_gateway("siliconflow/Qwen/Qwen3") is False
|
||||
assert is_nvidia_gateway("deepseek/deepseek-chat") is False
|
||||
assert is_nvidia_gateway(None) is False
|
||||
|
||||
scheduler = RequestScheduler(rate=1/60, capacity=1, enable_cache=True)
|
||||
# 先耗尽 NVIDIA 桶
|
||||
scheduler.submit(payload={"provider": "nvidia", "i": 1}, priority=Priority.NORMAL, callback=lambda x: x, gateway="nvidia")
|
||||
# 非 NVIDIA 请求应直接执行，不受桶状态影响
|
||||
non_nv = {"provider": "volcengine-plan", "i": 2}
|
||||
assert scheduler._should_rate_limit(type("R", (), {"gateway": "volcengine-plan", "model": None, "payload": non_nv})()) is False
|
||||
|
||||
print("✅ 网关范围识别测试完成：volcengine-plan/siliconflow/DeepSeek 不限流，NVIDIA 限流\n")
|
||||
|
||||
|
||||
def main():
|
||||
"""运行所有测试"""
|
||||
print("\n")
|
||||
print("╔" + "=" * 58 + "╗")
|
||||
print("║" + " " * 58 + "║")
|
||||
print("║" + " BIZ-26 限流器测试套件".center(58) + "║")
|
||||
print("║" + " API 请求优先级队列 + 令牌桶限流".center(58) + "║")
|
||||
print("║" + " " * 58 + "║")
|
||||
print("╚" + "=" * 58 + "╝")
|
||||
print()
|
||||
|
||||
try:
|
||||
test_token_bucket()
|
||||
test_cache_manager()
|
||||
test_priority_queue()
|
||||
test_retry_decorator()
|
||||
test_coordinated_poller()
|
||||
test_rate_limit_stress()
|
||||
test_gateway_scope()
|
||||
|
||||
print("\n")
|
||||
print("╔" + "=" * 58 + "╗")
|
||||
print("║" + " " * 58 + "║")
|
||||
print("║" + " ✅ 所有测试完成".center(58) + "║")
|
||||
print("║" + " " * 58 + "║")
|
||||
print("╚" + "=" * 58 + "╝")
|
||||
print()
|
||||
|
||||
except KeyboardInterrupt:
|
||||
print("\n\n⚠️ 测试被用户中断\n")
|
||||
except Exception as e:
|
||||
print(f"\n\n❌ 测试出错：{e}\n")
|
||||
import traceback
|
||||
traceback.print_exc()
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
Reference in New Issue
Block a user