Skip to content

Commit f11e1b8

Browse files
xiaojilele-glitchxiaojilele-glitch
committed
docs: add sprint roadmap and troubleshooting
1 parent f4a2b2d commit f11e1b8

4 files changed

Lines changed: 223 additions & 3 deletions

File tree

‎README.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -220,14 +220,16 @@ OpenClaw Feishu Progress 当前可以理解成 5 层：
220220

221221
## Roadmap
222222

223-
- 当前：OpenClaw 转发、飞书 ACK、阶段进度、analysis 完成态、本地 smoke 与 systemd 部署已可用
224-
- 下一步：补强飞书卡片交互、等待态决策流、任务摘要质量和服务监控
225-
- 后续：抽离更完整的任务执行器、更多消息渠道、更多可观测性能力
223+
- 当前：OpenClaw 转发、飞书 ACK、阶段进度、analysis 完成态、本地 smoke 与 Studio UI 已可用
224+
- 下一步：飞书卡片交互与等待态决策流、出站投递稳态、可观测性与生产化部署
225+
- 同期：OpenCroc 的 scan/graph + pipeline（生成/执行/自愈/报告）持续补强，确保任务“真的跑完并可交付”
226+
- 详细 Sprint 计划与 DoD：见 [docs/roadmap.md](docs/roadmap.md)
226227

227228
## 更多文档
228229

229230
- [架构说明](docs/architecture.md)
230231
- [配置参考](docs/configuration.md)
232+
- [Roadmap（Sprint 计划）](docs/roadmap.md)
231233
- [后端埋点指南](docs/backend-instrumentation.md)
232234
- [AI Provider 配置](docs/ai-providers.md)
233235
- [自愈机制说明](docs/self-healing.md)

‎docs/backend-instrumentation.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Backend Instrumentation (Guide)
2+
3+
本项目的执行与自愈能力依赖“后端可观测数据”来做判定与归因。你可以先把下面几类埋点补齐，再逐步增强。
4+
5+
## 最小可用（P0）
6+
7+
- Health endpoint：提供一个稳定的健康检查 URL（例如 `/health`），用于启动与就绪检测
8+
- Seed/Cleanup endpoint（可选但强烈建议）：用于 E2E 前置数据准备与清理
9+
- Log endpoint（可选）：用于拉取指定 `requestId` 或时间窗口内的日志片段（用于 log completion 检测与失败归因）
10+
11+
## 推荐日志字段（结构化日志）
12+
13+
- `requestId`：请求级唯一 ID（最好与链路透传一致）
14+
- `userId`/`tenantId`：多租户或用户隔离时用于归因
15+
- `method`/`path`/`status`：HTTP 维度的核心字段
16+
- `durationMs`：耗时统计，用于慢接口与 SLO
17+
- `eventStatus`：业务级完成态（避免“HTTP 200 但业务失败”）
18+
19+
## 与 OpenCroc/Studio 的对接点
20+
21+
- 运行时健康检查与等待：用于判定后端是否准备好
22+
- Log completion 检测：用于判定关键请求是否真正完成（而不是只看 HTTP 返回）
23+
- 自愈归因：失败时需要更完整的上下文（错误栈、关键日志、请求摘要）
24+
25+
## 常见坑
26+
27+
- 日志不带 `requestId` 导致难以匹配同一次 E2E 请求的后端事件
28+
- 只记录 HTTP 层状态导致“业务失败”无法识别
29+
- seed/cleanup 没有幂等导致并发执行时互相污染
30+
31+
下一步建议：当你有一条可稳定跑通的 E2E 流程后，再逐步把日志字段与 endpoint 做到更标准化。

‎docs/roadmap.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
# Roadmap (Sprint-Based) — OpenClaw Feishu Progress + OpenCroc
2+
3+
本 Roadmap 把两条主线视为同等优先级并同步推进：
4+
5+
- 主线 A（对话入口）：OpenClaw relay + 飞书 ACK/进度/卡片交互，把复杂请求稳定变成“可追踪任务”
6+
- 主线 B（任务内核）：OpenCroc scan/graph + pipeline（生成/执行/自愈/报告），把任务真正跑完并产出可交付物
7+
8+
> 节奏：每个 Sprint 2 周。日期以 2026-03-23 为 Sprint 1 起点，可按实际排期平移。
9+
10+
## 北极星指标
11+
12+
- 飞书侧体验：ACK p95 < 2s；进度投递成功率 > 99%；卡片更新乱序/重复 < 0.1%
13+
- 任务闭环：一次复杂请求能在 Studio 看到任务链路，并能稳定产出 report/文件/可复现日志
14+
- 工程质量：`npm test` 与 CI 绿；新增能力都有最小可回归用例与文档
15+
16+
## 全局 DoD（所有 Sprint 通用）
17+
18+
- 新增/变更的接口有明确的契约（请求字段、鉴权、幂等、错误码）
19+
- 单元测试覆盖关键分支（成功、失败、重试、鉴权失败、幂等重复）
20+
- 关键路径有结构化日志字段（至少包含 `taskId`，涉及飞书时包含 `chatId`/`messageId`）
21+
- 文档与示例可跑通（至少 1 条 smoke 流程）
22+
23+
## Sprint 1（2026-03-23 ~ 2026-04-05）：入口与投递“生产化底座”
24+
25+
目标：先把入口安全、投递稳态、幂等去重做扎实，再把 OpenCroc 的阶段进度与飞书展示对齐。
26+
27+
交付（主线 A：OpenClaw/飞书）
28+
29+
- `/api/feishu/webhook` 的安全校验与幂等去重“可持久”：重启进程后仍能在 TTL 内去重
30+
- `/api/feishu/relay` 与 `/api/feishu/relay/event` 增加最小鉴权（共享密钥/HMAC），并有回放保护（timestamp/nonce）
31+
- 出站投递稳态：对 429/5xx/网络抖动的重试退避策略明确，可配置，且不会造成无限重试与消息风暴
32+
33+
交付（主线 B：OpenCroc scan/pipeline）
34+
35+
- 任务阶段与飞书展示对齐：scan/pipeline/execute/report 的 stage 文案与百分比策略统一（减少“跳进度/卡住”）
36+
- `scan` 与 Studio UI 的数据落盘/缓存策略明确（至少保证重启后能恢复最近任务与图谱快照）
37+
38+
Sprint 1 DoD（验收）
39+
40+
- 针对 webhook/relay 鉴权与去重的单测覆盖完成，并在 CI 里跑
41+
- 本地 smoke：能在飞书看到 ACK -> 多次 progress -> done/failed（含 1 次重试场景）
42+
- 文档：新增/更新“鉴权配置与部署注意事项”小节（包含环境变量与回滚方式）
43+
44+
## Sprint 2（2026-04-06 ~ 2026-04-19）：等待态决策与卡片交互闭环
45+
46+
目标：让 `waiting` 不再只是“发一条文本提示”，而是可交互、可回填决策并驱动任务继续。
47+
48+
交付（主线 A：飞书卡片交互）
49+
50+
- `waiting` 状态生成带按钮的卡片（例如：继续执行/停止/只生成报告/仅 scan），并支持回调
51+
- 增加决策提交接口（例如：`POST /api/tasks/:id/decision`），支持 option id 与可选 free text
52+
- 卡片 `card-live` 原地更新：用户点选后，卡片显示“已选择 X”，并推进任务状态
53+
54+
交付（主线 B：任务编排）
55+
56+
- 为“有风险/有成本”的动作加决策点：例如 self-heal 的 source mutation 或 PR 生成前必须进入 `waiting` 等待确认
57+
- 让 chat 意图分类（pipeline/scan/report/analysis）与可交互按钮保持一致（避免 UI/后端分叉）
58+
59+
Sprint 2 DoD（验收）
60+
61+
- 一条完整流程：飞书触发 -> 进入 waiting -> 点按钮 -> 任务继续 -> 最终在飞书收到完成摘要 + 任务链接
62+
- 决策回调与任务状态变更有单测（含重复点击/重复回调幂等）
63+
64+
## Sprint 3（2026-04-20 ~ 2026-05-03）：可观测性与生产部署一键化
65+
66+
目标：把“能跑”提升到“可长期跑、可排障、可监控”。
67+
68+
交付（主线 A：服务化与排障）
69+
70+
- 增加 `/healthz`（以及必要的 `/readyz`）并明确判断标准（配置、存储、飞书凭据可用性）
71+
- systemd 或 Docker 交付物完善：环境变量清单、日志路径、升级步骤、回滚方式
72+
- 飞书相关关键错误可定位：token 获取失败、权限不足、429、卡片更新失败、消息线程参数不匹配
73+
74+
交付（主线 B：scan/graph 的可观测）
75+
76+
- scan 过程输出阶段日志与耗时统计（文件数、跳过数、deep scan 上限命中等）
77+
- 为超大仓库提供降级策略（maxDeepScan、忽略规则、超时中止），并能在报告里解释“扫描了什么/没扫描什么”
78+
79+
Sprint 3 DoD（验收）
80+
81+
- 以“重启/故障/权限不足/429”作为必测场景，能给出明确可执行的排障建议
82+
- 文档补齐：Troubleshooting + Deployment 两段可独立读懂并复现
83+
84+
## Sprint 4（2026-05-04 ~ 2026-05-17）：报告回传与执行质量门禁
85+
86+
目标：让飞书收到的不只是“完成了”，而是“可交付的结果”；让 pipeline/run 的质量结果可量化。
87+
88+
交付（主线 A：飞书回传内容升级）
89+
90+
- done/failed 的最终摘要模板化：结论、关键数据、产物链接（report/文件/仪表盘）
91+
- 将 checklist/workorder/token usage（如有）作为可选附件回传（文本或卡片分块）
92+
93+
交付（主线 B：执行与自愈质量）
94+
95+
- 执行质量门禁（quality gate）默认启用且可配置：例如后端不可用、auth 失败、失败率过高直接标红
96+
- 自愈策略分级：config-only 默认优先，source mutation 需进入 waiting 并二次确认
97+
98+
Sprint 4 DoD（验收）
99+
100+
- 在飞书里能看到“可落地的下一步”：失败原因分类、建议动作、指向 report 的链接
101+
- 至少 1 套端到端回归：pipeline -> execute -> (optional heal) -> report，数据在 Studio 可回看
102+
103+
## Sprint 5（2026-05-18 ~ 2026-05-31）：任务队列与并发治理（多 chat 生产形态）
104+
105+
目标：从“单任务互斥”走向“可控并发”，避免多 chat/多请求导致互相干扰。
106+
107+
交付（主线 A：多会话治理）
108+
109+
- 按 chatId/tenant 的并发与队列策略：默认串行，同 chat 不乱序；跨 chat 可并行但有全局上限
110+
- 任务取消/超时：能在飞书触发取消，并在 Studio 与飞书都可见（含幂等）
111+
112+
交付（主线 B：远程 scan 与任务化运行）
113+
114+
- 支持把 `opencroc scan <target>` 的能力任务化（本机路径或远端仓库），并把结果回传到飞书
115+
- 明确缓存策略：同一 target 的重复 scan 可以复用（可配置禁用）
116+
117+
Sprint 5 DoD（验收）
118+
119+
- 压测式验收：并发 5 个 chat 触发任务，队列/并发策略符合预期，且不会把进度串线
120+
- 取消/超时与恢复（重启后仍能看到任务最终态）有回归用例
121+
122+
## Sprint 6（2026-06-01 ~ 2026-06-14）：插件化与包边界收敛
123+
124+
目标：把“飞书桥接”和“OpenCroc 内核”边界明确，支持未来多渠道与多形态部署。
125+
126+
交付（主线 A：通知渠道插件）
127+
128+
- 抽象 `NotificationChannel`（send/update/ack/decision callback），飞书实现作为第一个插件
129+
- 预留第二渠道占位（例如 stdout/webhook/slack 任一），验证核心不被飞书绑死
130+
131+
交付（主线 B：内核拆分与兼容）
132+
133+
- 明确包与命名策略：`openclaw-feishu-progress` 与 `opencroc` 的 CLI/配置兼容路线图（不破坏现有用户）
134+
- 将 scanner/graph/insight/pipeline/execution 的依赖关系写成“架构契约”（谁能依赖谁）
135+
136+
Sprint 6 DoD（验收）
137+
138+
- 新增渠道不会影响飞书能力，且新增渠道有最小 smoke
139+
- README 与配置文档更新，包含迁移/兼容说明
140+
141+
## 依赖与外部约束（需在文档中持续强调）
142+
143+
- OpenClaw 的 `mode` 只支持 `daily|idle`，没有真正的 `never`。如需“等同只靠 `/new`、`/reset` 手动切会话”，用超大 `idleMinutes` 规避自动切会话。
144+
- OpenClaw 侧配置生效通常需要重启正在运行的 `openclaw/gateway` 进程或服务。
145+
146+
## 未来（超出本季度的候选方向）
147+
148+
- 多租户与权限（Studio 鉴权、审计日志）
149+
- 更强的 LLM 约束推理（链路规划/自愈策略更可控）
150+
- 执行平台化（worker 池、任务分片、artifact 存储与检索）

‎docs/troubleshooting.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Troubleshooting
2+
3+
## 配置改了但没生效
4+
5+
- 如果你改的是本项目（OpenClaw Feishu Progress / Studio）配置：需要重启正在运行的服务进程。
6+
- 如果你改的是 OpenClaw 侧（openclaw/gateway）配置：同样需要重启正在运行的 `openclaw/gateway` 进程或 systemd 服务后才会生效。
7+
8+
补充说明（OpenClaw 会话模式）
9+
10+
- OpenClaw 的 `mode` 只支持 `daily|idle`，没有真正的 `never`。
11+
- 如果你想实现“等同只靠 `/new`、`/reset` 手动切会话”，用超大 `idleMinutes` 来避免自动切会话。
12+
13+
## 飞书收不到 ACK/进度消息
14+
15+
- 检查 `.env` 或 config 里的 `FEISHU_APP_ID` / `FEISHU_APP_SECRET`（或 `FEISHU_TENANT_ACCESS_TOKEN`）是否正确。
16+
- 确认飞书应用权限与范围：机器人是否有发消息权限，是否能在目标群/私聊中发言。
17+
- 确认 `OPENCLAW_FEISHU_PROGRESS_BASE_TASK_URL` 可被飞书用户访问，否则卡片/文本里的“任务详情链接”会打不开。
18+
- 如果使用 `messageFormat: 'card-live'`：需要能成功拿到 `message_id` 并允许 PATCH 更新；否则会退化为多条消息。
19+
- 如果出现 429：属于飞书限流，需要降低更新频率或启用退避重试策略。
20+
21+
## Webhook 收不到或验签失败
22+
23+
- 确认飞书事件订阅 URL 指向 `/api/feishu/webhook`，并能通过公网访问。
24+
- 首次校验会发送 `url_verification`，服务需要正确回传 challenge。
25+
- 若启用了验签/加密：确保配置的 token/key 与飞书后台一致。
26+
27+
## relay 进度能进来但飞书不更新
28+
29+
- 检查 `/api/feishu/relay/event` 是否成功返回（是否被鉴权拦截、是否 4xx/5xx）。
30+
- 检查任务是否已 bind 到飞书（`chatId` 是否正确；是否记录了 `messageId` 用于 live update）。
31+
- 如果 OpenClaw 负责最终答案：确保 relay start 时设置 `finalAnswerSource=openclaw`，避免重复发送最终摘要。
32+
33+
## Studio 页面没数据
34+
35+
- 先触发一次 `scan` 或 `pipeline`，让图谱与任务产生数据。
36+
- 确认服务监听地址与端口正确（开发态默认 `:5173` 前端、`:8765` 后端）。
37+
- 如果你是生产构建：确认 `npm run build` 生成了 `src/web/dist`，否则会使用内嵌的简易页面。

0 commit comments

Comments
 (0)