356 lines
14 KiB
Markdown
356 lines
14 KiB
Markdown
# OpenClaw 执行手册 — LLM Intelligence Hub
|
||
|
||
> 本文档说明宰相（AI Agent）如何在本项目内执行、验证与回收任务。
|
||
> 版本：v1.0
|
||
> 日期：2026-05-14
|
||
> 状态：与当前代码状态对齐
|
||
|
||
---
|
||
|
||
## 一、项目现状
|
||
|
||
**不再是"仅有规划文档"**。
|
||
|
||
当前已落地：
|
||
|
||
| 组件 | 状态 | 路径 |
|
||
|------|------|------|
|
||
| 规划文档 | ✅ | PRD.md / FEATURE_LIST.md / TECHNICAL_DESIGN.md / BUSINESS_MODEL.md |
|
||
| OpenRouter 采集器 | ✅ | `scripts/fetch_openrouter.go` — Go 实现，直写 PostgreSQL |
|
||
| 数据库迁移 | ✅ | `db/migrations/001_phase1_core_tables.sql` |
|
||
| 日报生成器 | ✅ | `scripts/generate_daily_report.go` |
|
||
| 日报产出 | ✅ | `reports/daily/` 已有 7 份 Markdown 日报 + HTML 产物 |
|
||
| 前端脚手架 | ✅ | `frontend/src/pages/Explorer.tsx` + 数据文件 |
|
||
| 项目内任务管理 | ✅ | `GOALS.md` / `TASKS.md` / `AGENTS.md` |
|
||
| 项目内记忆入口 | ✅ | `SESSION-STATE.md` / `MEMORY.md` / `memory/README.md` |
|
||
| 验证器 | ✅ | `scripts/verification_executor.go` + 6 个 verify 脚本 |
|
||
| CI 工作流 | ✅ | `.github/workflows/ci.yml` |
|
||
| OpenClaw Review | ✅ | `reports/openclaw/` 已有 review + backlog |
|
||
|
||
**技术栈确认**：Go 1.22.2 + PostgreSQL + Vanilla JS/React（前端）
|
||
|
||
---
|
||
|
||
## 二、角色定义
|
||
|
||
四个固定责任面，任务并行推进：
|
||
|
||
### 产品架构师
|
||
- **负责**：PRD 维护、Phase 范围冻结、文档一致性审查
|
||
- **当前任务**：主线已完成，当前关注 Phase 2 范围定义与文档真实性维护
|
||
- **判定标准**：PRD / FEATURE / TECH 三份文档无冲突描述
|
||
|
||
### 数据后端
|
||
- **负责**：采集器、数据库 schema、日报生成、数据质量
|
||
- **当前任务**：主线已完成，当前关注数据质量、Phase 2 多数据源扩展、真实运行验证
|
||
- **判定标准**：`fetch_openrouter` 可运行并写入 DB；`generate_daily_report` 产出 Markdown
|
||
|
||
### 前端实现
|
||
- **负责**：Explorer 页面、Dashboard 组件、数据可视化
|
||
- **当前任务**：Explorer / Dashboard 最小可用已完成，腾讯云套餐订阅价已接入 Dashboard，当前关注展示质量与后续增强
|
||
- **判定标准**：前端页面可展示模型表格 + 免费标记 + 筛选排序；Dashboard 可独立展示腾讯云套餐订阅价
|
||
|
||
### 集成验收
|
||
- **负责**：验证脚本、任务回收、日报推送、cron 集成
|
||
- **当前任务**：主线已完成，当前关注验证真实性、回写边界、review/cron/verifier 降噪
|
||
- **判定标准**：`verification_executor --dry-run` 能读取本项目 TASKS.md；cron 每日触发采集+日报
|
||
|
||
---
|
||
|
||
## 三、执行顺序（已更新）
|
||
|
||
```
|
||
执行基线（2026-05-11）：
|
||
|
||
[✅] 1. Phase 1 范围冻结与文档冲突清理
|
||
[✅] 2. OpenRouter 采集器、数据库迁移、日报生成器落地
|
||
[✅] 3. Explorer / Dashboard 最小可用前端落地
|
||
[✅] 4. 项目内 TASKS / GOALS / verification / execution 闭环落地
|
||
[✅] 5. 自动采集 + 日报调度闭环落地
|
||
[✅] 6. Phase 5 CI 工作流与 Phase 3/Phase 5 验收门禁补齐
|
||
[🟡] 7. OpenClaw review / cron / verifier 质量治理持续优化
|
||
[✅] 8. Phase 6 稳定性门禁已恢复通过，当前转入后续治理项跟踪
|
||
```
|
||
|
||
**下一步优先**：
|
||
1. 继续收口 review / cron / verifier 的真实性与降噪质量，避免历史 blocker 已消失但 board 仍滞后
|
||
2. 观察 Cloudflare / Perplexity / Vertex 等外部文档源的稳定性，把瞬时网络抖动与真实结构漂移区分开
|
||
3. 维持正式日报、历史重建与手工真实复跑三条运行语义边界，防止后续优化重新串线
|
||
|
||
### 当前运行真相
|
||
|
||
当前可直接引用的事实是：
|
||
|
||
- `bash scripts/verify_phase3.sh` 已通过，`run_daily.sh` 的正式调度链已收紧真实采集判定并写入来源级运行审计
|
||
- `bash scripts/verify_phase5.sh` 已通过，仓库已补齐 `.github/workflows/ci.yml`
|
||
- `bash scripts/verify_pre_phase6.sh` 已通过，说明 Phase 1~5 门禁当前仍闭环
|
||
- `bash scripts/run_real_pipeline.sh` 已于 `2026-05-24 18:15` 真实复跑成功，Cloudflare / Perplexity / Vertex 等外部官方价格链路本轮均通过
|
||
- `bash scripts/verify_phase6.sh` 已于 `2026-05-24 18:17` 通过：`SUMMARY pass=17 fail=0 warn=0`
|
||
- 最近 7 次采集窗口已恢复到 `success_rate=100.00%`，`precondition_missing=0`
|
||
- `bash scripts/verify_importer_smoke.sh`、`bash scripts/importer_smoke_gate_test.sh`、`bash scripts/pipeline_runtime_alignment_test.sh` 已通过；Baichuan / 01.AI / SenseNova / 讯飞 4 个官方 importer 已接入 runtime + smoke + docs 闭环并完成三远端推送
|
||
- 正式日报、历史重建和手工真实复跑已分流到不同运行语义
|
||
- `fetchLatestReport` 默认只展示正式日报，不会把历史重建当成最新正式产出
|
||
|
||
---
|
||
|
||
## 四、验证规则
|
||
|
||
### 项目内验证（优先）
|
||
|
||
宰相执行本项目任务时，**默认读取本项目 `TASKS.md`**，不是全局 `~/.openclaw/workspace/TASKS.md`。
|
||
|
||
```bash
|
||
# 项目内验证（默认行为）
|
||
cd /home/long/project/llm-intelligence && go run scripts/verification_executor.go --dry-run
|
||
|
||
# 指定任务验证
|
||
cd /home/long/project/llm-intelligence && go run scripts/verification_executor.go --task T-2.1
|
||
|
||
# 只验证已完成任务（推荐用于日常健康检查）
|
||
cd /home/long/project/llm-intelligence && go run scripts/verification_executor.go --completed-only
|
||
|
||
# 按状态过滤
|
||
cd /home/long/project/llm-intelligence && go run scripts/verification_executor.go --status planned
|
||
```
|
||
|
||
### 验证 schema
|
||
|
||
每个 Task 必须包含：
|
||
|
||
```yaml
|
||
verification:
|
||
mode: artifact_present | test_pass | semantic
|
||
command: "精确命令"
|
||
expected_evidence: "预期输出"
|
||
evidence_grade: runtime-verified | artifact-present | doc-claimed
|
||
task_type: code | automation | documentation | configuration | data | analysis
|
||
timeout_seconds: 30
|
||
```
|
||
|
||
### 验证真实性协议
|
||
|
||
- 任何结论都要区分三种证据等级：
|
||
- `doc-claimed`：只有文档、任务表、说明文字这样写
|
||
- `artifact-present`：文件、脚本、模板、配置确实存在
|
||
- `runtime-verified`：构建、测试、接口、数据库、真实命令输出验证通过
|
||
- 对代码、脚本、自动化、调度、数据链路任务，默认**不能**只用 `doc-claimed` 或纯 `semantic` 判定完成。
|
||
- `artifact_present` 只适用于：
|
||
- 静态文档存在性
|
||
- 模板文件存在性
|
||
- 非执行型配置存在性
|
||
- 只要任务声称“可运行”“已打通”“已自动化”“已上线前可交付”，就必须至少补一条 `runtime-verified` 证据。
|
||
- review 报告里必须明确区分：
|
||
- 文档宣称完成
|
||
- 仓库产物存在
|
||
- 真实运行验证通过
|
||
- 未区分这三层时，不能把任务写成“完成”。
|
||
|
||
### 复杂任务执行协议
|
||
|
||
- 多文件、跨模块、跨角色或高风险任务，必须先拆成 checkpoints，再执行。
|
||
- 每个 checkpoint 至少包含：
|
||
- 目标输出
|
||
- 预期证据
|
||
- 对应验证命令
|
||
- checkpoint 完成后：
|
||
1. 先更新 `SESSION-STATE.md`
|
||
2. 再做局部验证
|
||
3. 最后才考虑改 `TASKS.md`
|
||
- 在整个复杂任务链路中，只允许一个写者做最终任务状态回收，避免多个 agent 并发改状态。
|
||
- 如果某个 checkpoint 只完成文档或模板，而主链路运行证据尚未出现，任务状态最多更新到 `🟡`，不能直接标 `✅`。
|
||
|
||
### 状态回收流程
|
||
|
||
1. 任务完成后 → 更新 `TASKS.md` 状态（🔴 → 🟡 → ✅）
|
||
2. 运行 `verification_executor` 确认通过
|
||
3. 按项目 daily memory 协议记录到 `memory/YYYY-MM-DD.md`
|
||
4. 每周复盘时 → 更新 `GOALS.md` 里程碑
|
||
|
||
### Project Daily Memory 回写协议
|
||
|
||
项目内的 `cron` / `review` / `verifier` / `main` / `worker` 在结束一个执行块后，如果需要留下可恢复归档，必须遵守以下规则：
|
||
|
||
#### 1. 写入目标
|
||
|
||
- 高频工作态只写 `SESSION-STATE.md`
|
||
- 单日归档只写 `memory/YYYY-MM-DD.md`
|
||
- 长期稳定知识只写 `MEMORY.md`
|
||
- 任务状态真相只写 `TASKS.md`
|
||
- 目标里程碑真相只写 `GOALS.md`
|
||
|
||
#### 2. 初始化规则
|
||
|
||
- 如果 `memory/YYYY-MM-DD.md` 不存在，必须先创建标准骨架：
|
||
|
||
```md
|
||
# llm-intelligence Daily Memory - YYYY-MM-DD
|
||
|
||
> 项目单日归档文件。
|
||
> 记录高价值摘要、证据、结论，不记录每条实时对话。
|
||
> 高频工作状态优先写 `SESSION-STATE.md`。
|
||
|
||
## Entries
|
||
```
|
||
|
||
- 不允许第一次写入就直接从裸 `## HH:MM ...` 开始。
|
||
- 项目内 daily memory 细则以 `memory/README.md` 为准。
|
||
|
||
#### 3. 追加格式
|
||
|
||
- 新条目只能追加在 `## Entries` 后面
|
||
- 标题格式固定为：
|
||
|
||
```md
|
||
## HH:MM - <actor> - <topic>
|
||
```
|
||
|
||
- `<actor>` 只允许：
|
||
- `main`
|
||
- `cron`
|
||
- `review`
|
||
- `verifier`
|
||
- `worker`
|
||
|
||
- 每个条目正文只允许使用四个小节：
|
||
|
||
```md
|
||
### Context
|
||
- ...
|
||
|
||
### Evidence
|
||
- ...
|
||
|
||
### Outcome
|
||
- ...
|
||
|
||
### Next
|
||
- ...
|
||
```
|
||
|
||
#### 4. 角色写法约束
|
||
|
||
- `cron`：只写调度结果、失败原因、是否需要人工介入
|
||
- `review`：只写关键发现、风险判断、建议动作
|
||
- `verifier`：只写验证命令、证据、PASS/FAIL
|
||
- `main`：只写用户决策、任务切换、阶段结论
|
||
- `worker`：只写局部实现进展、阻塞、交接点
|
||
|
||
#### 5. 工具使用约束
|
||
|
||
- `memory/YYYY-MM-DD.md` 是日志型文件，默认不要优先使用脆弱的 `edit`
|
||
- 推荐流程固定为：
|
||
1. `read` 当前文件
|
||
2. 保留旧内容
|
||
3. 在末尾追加一个新时间块
|
||
4. 用 `write` 做整文件重写
|
||
- 只有在锚点极小、唯一、且刚刚读取过的情况下，才允许对 daily memory 使用 `edit`
|
||
- 不允许把大段原始日志、整篇 review、整段命令输出直接粘进 daily memory；只保留高价值摘要和可追溯证据路径
|
||
|
||
#### 6. 完成前核验
|
||
|
||
- 写完 `memory/YYYY-MM-DD.md` 后，必须立即重新读取并确认：
|
||
- 标题还在
|
||
- `## Entries` 还在
|
||
- 新条目已经落在末尾
|
||
- `<actor>` 与 section 标题格式正确
|
||
- 没有通过这一步，不能声称“已归档”
|
||
|
||
### Review 产物字段协议
|
||
|
||
- `reports/openclaw/YYYY-MM-DD-HHMM-review.md` 必须与项目 daily memory 保持同一组字段命名。
|
||
- 允许保留标题和 metadata block，但除这两部分外，顶层 section 只允许：
|
||
- `## Context`
|
||
- `## Evidence`
|
||
- `## Outcome`
|
||
- `## Next`
|
||
- 字段映射固定为：
|
||
- `Context`：review 背景、阶段判断、时间窗口
|
||
- `Evidence`：验证命令与结果、完成项、未完成项、不一致项、gap 证据
|
||
- `Outcome`：执行摘要、风险判断、阶段结论
|
||
- `Next`：下一轮动作、owner、复核点
|
||
- review 模板以 `reports/openclaw/REVIEW_TEMPLATE.md` 为准；新报告默认基于该模板生成。
|
||
- 历史 review 报告允许保留旧格式，不要求批量回写；从本规则生效后生成的新报告必须遵守四段式字段协议。
|
||
- `Evidence` 段必须优先展示 `runtime-verified` 证据，其次才是 `artifact-present` 与 `doc-claimed`。
|
||
|
||
### 任务写回边界
|
||
|
||
- `llm-intelligence` 的 review、cron、实施、验收任务，**只允许写本项目**：
|
||
- `/home/long/project/llm-intelligence/TASKS.md`
|
||
- `/home/long/project/llm-intelligence/GOALS.md`
|
||
- 明确禁止写：
|
||
- `~/.openclaw/workspace/TASKS.md`
|
||
- `~/.openclaw/workspace/GOALS.md`
|
||
- 如果只是 review，不要顺手改任务状态；只有当本轮真的完成了某项任务并拿到了验证证据，才允许改本项目 `TASKS.md`。
|
||
- 任何任务文件写回前，必须先跑预检守卫：
|
||
|
||
```bash
|
||
cd /home/long/project/llm-intelligence
|
||
bash scripts/review/preflight_task_write_guard.sh llm-intelligence-review /home/long/project/llm-intelligence/TASKS.md
|
||
bash scripts/review/preflight_task_write_guard.sh llm-intelligence-review /home/long/project/llm-intelligence/GOALS.md
|
||
```
|
||
|
||
- 如果是 cron 场景，writer role 改成 `llm-intelligence-cron`；只要守卫返回非 0，就必须立即停止，不得继续写回。
|
||
|
||
---
|
||
|
||
## 五、文档改写规则
|
||
|
||
这条规则专门用于避免大 Markdown 文档在 Feishu 会话里出现“回复看起来完成、工具层实际失败”的假完成。
|
||
|
||
### 先读后改
|
||
|
||
- 修改 `TECHNICAL_DESIGN.md`、`IMPLEMENTATION_PLAN.md`、`TASKS.md` 这类大文件前，必须先重新读取目标文件的最新内容。
|
||
- 只有在**刚读取过且能精确定位** `oldText` 的情况下，才允许使用 `edit`。
|
||
- 对共享或高频变动文件（如 `TASKS.md`、`OPENCLAW_CAPABILITY_BACKLOG.md`），默认假设存在并发写入风险。
|
||
|
||
### 大文件优先锚点，锚点不稳就整段重写
|
||
|
||
- 当单文件大于 50KB、变更跨越多个分散段落，或旧文本包含表格/代码块/全角字符时，默认不要连续重试 `edit`。
|
||
- `edit` 一旦出现 `Could not find the exact text`，必须停止复用旧的 `oldText`，改为：
|
||
- 重新读取更小范围的精确锚点后再改
|
||
- 或基于最新全文直接 `write` 重写目标文件
|
||
- **禁止**连续两次拿同一份 `oldText` 重试。
|
||
- 如果文件是共享面板或任务总表，第二次失败后直接放弃 `edit`，改为整段 `write`。
|
||
|
||
### 单写者约束
|
||
|
||
- `~/.openclaw/workspace/TASKS.md` 和 `~/.openclaw/workspace/GOALS.md` 由 `main session` 独占写入。
|
||
- `llm-intelligence` agent 与它的 cron review 对全局任务面板一律只读。
|
||
- 本项目自己的 `TASKS.md` 允许本项目 agent 写入，但同一轮执行里只允许一个写者负责回收，避免多个 subagent 同时改任务表。
|
||
|
||
### 回写后必须二次核验
|
||
|
||
- 每次 `write` 或 `edit` 成功后，必须立刻重新读取目标文件。
|
||
- 至少核验三类内容：
|
||
- 目标标题是否更新
|
||
- 关键关键词是否已落盘
|
||
- 旧的冲突描述是否已消失
|
||
|
||
### 响应前提
|
||
|
||
- 没有通过“回写后二次核验”，不能在 Feishu 中声称“已完成”。
|
||
- 如果工具层失败，应明确报告“失败于 edit/write，未落盘”，不能用文字总结代替文件变更。
|
||
|
||
---
|
||
|
||
## 六、与立交桥其他项目的关系
|
||
|
||
| 项目 | 关系 | 注意 |
|
||
|------|------|------|
|
||
| `ai-customer-service` | 独立 | 技术栈相同（Go+PostgreSQL），但数据/目标完全独立 |
|
||
| `supply-intelligence` | 独立 | 小龙团队推进，宰相不直接参与 |
|
||
| `~/.openclaw/workspace/` | 全局配置 | 仅保留 GOALS/TASKS 双层管理框架，不塞本项目任务 |
|
||
|
||
---
|
||
|
||
## 七、不做清单
|
||
|
||
- ❌ 不再往全局 `~/.openclaw/workspace/TASKS.md` 塞本项目任务
|
||
- ❌ 不新增大而全的设计文档（PRD/TECH 已冻结，进入执行期）
|
||
- ❌ 不引入 Python/Flask 技术栈（已统一为 Go）
|
||
- ❌ Phase 1 不碰多租户、用户系统、邮件/飞书推送
|
||
|
||
---
|
||
|
||
*本文档由宰相维护，每次项目状态重大变更后更新。*
|