llm-intelligence/OPENCLAW_EXECUTION.md

# 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 等外部文档源的稳定性；当前 Cloudflare 已补上“代理传输失败 → 直连 fallback”兜底，但仍需区分瞬时网络抖动与真实结构漂移
3. 维持正式日报、历史重建与手工真实复跑三条运行语义边界，防止后续优化重新串线

### Phase 6+ 范围定义

Phase 6 的结束点是：`verify_phase6.sh`、`verify_pre_phase6.sh`、正式日报主链路与 API 健康门禁已经恢复绿色，主发布闭环可以诚实复用。

Phase 6+ 指的是 **治理阶段**，不属于新的发布门禁，也不等于新的业务功能 phase。它覆盖的范围是：
- review / cron / verifier / backlog / memory 的长期治理
- release 语义、风险老化、状态一致性、噪声收敛
- 外部 provider 漂移后的解释层、回退层与 guard 持续补强
- 正式日报 / 历史重建 / 手工真实复跑三条运行语义的边界维护

Phase 6+ 的目标不是再声明“可发布”，而是防止已经恢复绿色的主链路因为治理退化再次失真。
### 当前运行真相

当前可直接引用的事实是：

- `bash scripts/verify_phase3.sh` 已通过，正式调度链、正式日报主产物、归档副本、report_runs / daily_report 写入链均为绿色
- `bash scripts/verify_phase5.sh` 已通过，仓库已补齐 `.github/workflows/ci.yml`，验收链对关键构建检查已有统一 coverage gate
- `bash scripts/verify_pre_phase6.sh` 已通过，说明 Phase 1~5 门禁当前仍闭环
- `bash scripts/run_real_pipeline.sh` 已于 `2026-05-30 15:18` 真实复跑成功，当前本机 `.env.local` / `.env` 优先级缺陷已修复后，官方 importer、多源同步、日报生成与运行记录链都能在本机真实跑通
- `bash scripts/verify_phase6.sh` 已于 `2026-05-30 15:33` 通过：`SUMMARY pass=18 fail=0 warn=0`
- 最近 7 次采集窗口当前输出为 `success_rate=100.00%`，且已支持把历史前置条件样本老化为 `aged_precondition_missing`，不会继续污染当前 release success-rate
- `verify_phase6.sh` 当前已输出结构化：
  - `ROOT_CAUSE class=... source=... summary=...`
  - `RELEASE_SEMANTICS class=... gate=... policy=...`
  - `BLOCKER_SWITCH class=... old=... new=...`
  - `stability_label=...`
- `bash scripts/verify_importer_smoke.sh`、`bash scripts/importer_smoke_gate_test.sh`、`bash scripts/pipeline_runtime_alignment_test.sh` 已通过；当前 CoresHub / 华为 MaaS / 百川 / 01.AI / SenseNova / 讯飞 / 火山方舟等官方 importer 已接入 runtime + smoke + docs 闭环
- 正式日报、历史重建和手工真实复跑已分流到不同运行语义；非正式运行产物会进入 `reports/ad_hoc/...`，不会覆盖正式日报主路径
- `fetchLatestReport` 默认只展示正式日报，不会把历史重建或手工真实复跑当成最新正式产出
- 本机 cron 继续指向 `bash scripts/run_daily.sh`，且在当前用户 / 当前仓库 / 当前 `.env.local` 条件下已手工验证可以成功落盘，具备每天真实运行作为回归验证的条件

---

## 四、验证规则

### 项目内验证（优先）

宰相执行本项目任务时，**默认读取本项目 `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 不碰多租户、用户系统、邮件/飞书推送

---

*本文档由宰相维护，每次项目状态重大变更后更新。*