niuniu/llm-intelligence
1
0
Fork 1
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
256975e10c770a6ed7057a13fb54a08842a729ea
llm-intelligence/OPENCLAW_EXECUTION.md

13 KiB
Raw Blame History

OpenClaw 执行手册 — LLM Intelligence Hub

本文档说明宰相（AI Agent）如何在本项目内执行、验证与回收任务。 版本：v1.0 日期：2026-05-11 状态：与当前代码状态对齐

一、项目现状

不再是"仅有规划文档"。

当前已落地：

组件 状态 路径
规划文档 ✅ 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 + 4 个 verify 脚本
OpenClaw Review ✅ reports/openclaw/ 已有 13 份 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 6 综合验收通过（`verify_phase6.sh` PASS）
[🟡] 7. OpenClaw review / cron / verifier 质量治理持续优化
[🟡] 8. Phase 2 多数据源扩展待规划

下一步优先：

  1. 提高 review / cron / verifier 的真实性与降噪质量
  2. 推进 Phase 2 数据源扩展与真实验证入口
  3. 收口工程纪律：提交、CI、回写边界、报告一致性

四、验证规则

项目内验证（优先）

宰相执行本项目任务时，默认读取本项目 TASKS.md，不是全局 ~/.openclaw/workspace/TASKS.md。

# 项目内验证（默认行为）
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 必须包含：

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 不存在，必须先创建标准骨架：
# llm-intelligence Daily Memory - YYYY-MM-DD

> 项目单日归档文件。
> 记录高价值摘要、证据、结论，不记录每条实时对话。
> 高频工作状态优先写 `SESSION-STATE.md`。

## Entries
  • 不允许第一次写入就直接从裸 ## HH:MM ... 开始。
  • 项目内 daily memory 细则以 memory/README.md 为准。

3. 追加格式

  • 新条目只能追加在 ## Entries 后面
  • 标题格式固定为：
## HH:MM - <actor> - <topic>

  • <actor> 只允许：

    • main
    • cron
    • review
    • verifier
    • worker

  • 每个条目正文只允许使用四个小节：

### 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。
  • 任何任务文件写回前，必须先跑预检守卫：
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 不碰多租户、用户系统、邮件/飞书推送

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

Reference in New Issue View Git Blame Copy Permalink