每次完成任务后,在提交前逐项自检。每一项 PASS 才能说"完成了"。 发现 FAIL → 自己修 → 重检 → 直到全部 PASS。
- 所有新增/修改的输出字段在 state.py 有对应的 Pydantic Model
- Model 的 Optional 字段有默认值,不会因缺少数据而崩溃
- 嵌套 Model(如 ProbeOutput 包含 BrandProfile)的解析链完整
- 每个 LLM 调用/API 调用都有 try-except
- 失败时返回带 status="error" + error 消息的结构化输出(不是裸异常)
- Probe 各模块独立容错:一个模块失败不阻塞其他模块
- 有 fallback 逻辑的模块(如 brand_profiler → intro_composer),fallback 路径已验证
- 外部 API 调用有 timeout(不能无限等待)
- Token 预算检查存在且生效(当前硬限 150K)
- 批量调用有并发控制(Semaphore,当前 BATCH_SIZE=3)
- asyncio 代码中没有混用同步阻塞调用
- 共享状态(如 CircuitBreaker)在并发环境下安全
- create_task 的结果都被 await(没有泄漏的 task)
- System Prompt 要求输出 JSON 且指定了 response_format={"type": "json_object"}
- Prompt 中有"只返回JSON,不要其他文字"的约束
- Few-Shot 示例的输出格式和实际要求的格式一致
- Prompt 长度合理(没有把整个 ProbeOutput 原文塞进去)
- LLM 返回的 JSON 用 json.loads 解析(不是 eval)
- 解析后的 dict 用 Pydantic Model 验证(不是直接取字段)
- 验证失败时有明确的错误信息(包含原始返回内容的前200字符)
- 关键节点有 NodeLogger 输出(开始/结束/错误)
- 日志包含可定位的信息(模块名、token数、耗时、关键指标值)
- 没有把敏感信息(API Key)打到日志里
- 模块可以独立调用(不依赖全局状态或上一个节点的副作用)
- 有对应的 test_*.py 文件或调用示例
- test 文件可以独立运行(python test_xxx.py)
- 三条流(品牌/搜索/竞品)确实并行执行(不是串行等待)
- Level 依赖关系正确:L2 等 L1 完成,L3 等 L2 完成
- 竞品流缺失 competitors 时优雅跳过(不报错)
- ProbeOutput 的 14 个字段都有值(或明确标记为 None)
- citation_metrics.details 的条数和 query_terms 的条数一致
- source_authority.top_sources 的数据和 citation_analyzer 的输出能对上
- query_expander 输出正好 30 个查询词(或指定数量)
- fc_search 对每个查询词都返回了结果(成功/跳过/失败三种状态)
- ChatGPT 调用带了 web_search 工具(中转站模式)
- build_context 的输出和 SYSTEM_PROMPT 中的字段名完全对应
- _build_user_message 的输出格式和 Few-Shot 示例的输入格式一致
- 数据表格的列名和 SYSTEM_PROMPT 中"数据扫描"步骤对应
- 输出的 actions 数量在 2-5 条之间
- 每个 action 有完整的 8 个字段(priority/action/rationale/expected_impact/target_metric/current_value/expected_value/action_steps)
- action_steps 至少 3 步,精确到平台名称
- rationale 是洞察(解释为什么),不是数据复述
- severity 判定符合规则 7 的条件(critical/warning/healthy)
- 新增节点在 dag.py 中正确注册(add_node + add_edge)
- 条件路由逻辑正确(当前:coordinator pass→END, retry→Commander, 最多2次)
- State TypedDict 包含了所有节点需要读写的字段
- config.py 中的 API 端点和模型名正确
- 环境变量(OPENAI_API_KEY / DEEPSEEK_API_KEY)在调用前检查
- 中转站兼容性确认:tools 参数类型(function/custom,不是 web_search)
- 本次任务是否新增/删除/重命名了 .py 文件?如果是,已更新 CODEBASE.md
- 本次任务是否改变了数据流(如新增工具、修改调用链)?如果是,已更新 CODEBASE.md 的数据流图
- 本次任务是否新增/修改了 Pydantic Model?如果是,已更新 CODEBASE.md 的数据模型表
- 本次任务是否改变了模块状态(如从mock变为真实实现)?如果是,已更新 CODEBASE.md 的状态速查
验证方法:对比 git diff --name-only 和 CODEBASE.md,确认新增/删除的文件都已反映。
CHECKLIST 完成后,在回复中附带:
自检结果: X/8 代码质量 + X/6 Probe + X/5 Analyst + X/3 DAG + X/3 API + X/4 代码库 = XX/29
失败项: (无 / 列出)
修复记录: (如有修复,简述)
每次修改 page.tsx 或任何 scan-*.tsx 组件后,必须逐项验证:
- Light 扫描报告(scan-result.tsx)显示的是 Light 数据,不是 Probe 数据
- 测试:先跑 Light 扫描 → 看报告 → 再跑 Probe → 回到 Light 报告页 → 数据仍是 Light 的
- 所有 6 种 step(input/probe/analyst/doctor/dashboard/error)都能正常进入和退出
- sidebar 按钮在每种 step 下行为正确(locked/available/completed 三态)
- tier 检查没有被绕过(free 用户不能进 Analyst/Doctor)
- 页面刷新后数据不丢失
- 不同 scanMode(light/full)的数据存在不同 key 下
- 旧 key 迁移逻辑还在(不能删)
- beforeunload 保护还在(不能删)
- 新组件不与现有组件功能重复
- 改组件前确认:是"修改现有"还是"新建"
- 新建组件命名遵循
scan-[name].tsx格式
- inline style(不是 Tailwind class)
- 暗色主题色值正确:#0A0A0F / #131318 / 边框 rgba(255,255,255,0.04)
- Framer Motion 动画,不是 CSS animation/transition
- console 无红色报错
- 所有按钮可点击且有响应
- 锁定模块显示 mock 数据或升级提示(不是空白 div)
以下情况直接判定为 交付不合格,无需继续审查:
- 跳过 CHECKLIST 直接说"做好了"
- LLM 调用没有 try-except(裸异常会崩整个管道)
- 输出没有 Pydantic Model 验证(脏数据会污染下游)
- Probe 某模块失败导致整个管道崩溃(应该部分成功+标记)
- 修改了文件结构但没更新 CODEBASE.md