niuniu/llm-intelligence

Fork 1

Files

phamnazage-jpg 62556e787f

CI / go-test (push) Has been cancelled

Details

CI / scripts-regression (push) Has been cancelled

Details

CI / frontend-build (push) Has been cancelled

Details

CI / docker-build (push) Has been cancelled

Details

docs: refresh openclaw execution runtime truth

2026-05-30 17:03:46 +08:00

16 KiB

Raw Blame History

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 稳定性门禁已恢复通过，当前转入后续治理项跟踪

下一步优先：

继续收口 review / cron / verifier 的真实性与降噪质量，避免历史 blocker 已消失但 board 仍滞后
继续观察 Cloudflare / Perplexity / Vertex 等外部文档源的稳定性；当前 Cloudflare 已补上“代理传输失败 → 直连 fallback”兜底，但仍需区分瞬时网络抖动与真实结构漂移
维持正式日报、历史重建与手工真实复跑三条运行语义边界，防止后续优化重新串线

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。

# 项目内验证（默认行为）
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 只完成文档或模板，而主链路运行证据尚未出现，任务状态最多更新到 🟡，不能直接标 ✅。

状态回收流程

任务完成后 → 更新 TASKS.md 状态（🔴 → 🟡 → ✅）
运行 verification_executor 确认通过
按项目 daily memory 协议记录到 memory/YYYY-MM-DD.md
每周复盘时 → 更新 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 不碰多租户、用户系统、邮件/飞书推送

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

16 KiB Raw Blame History Unescape Escape

OpenClaw 执行手册 — LLM Intelligence Hub

一、项目现状

二、角色定义

产品架构师

数据后端

前端实现

集成验收

三、执行顺序（已更新）

Phase 6+ 范围定义

当前运行真相

四、验证规则

项目内验证（优先）

验证 schema

验证真实性协议

复杂任务执行协议

状态回收流程

Project Daily Memory 回写协议

1. 写入目标

2. 初始化规则

3. 追加格式

4. 角色写法约束

5. 工具使用约束

6. 完成前核验

Review 产物字段协议

任务写回边界

五、文档改写规则

先读后改

大文件优先锚点，锚点不稳就整段重写

单写者约束

回写后必须二次核验

响应前提

六、与立交桥其他项目的关系

七、不做清单

16 KiB

Raw Blame History