64 lines
3.3 KiB
Markdown
64 lines
3.3 KiB
Markdown
|
# 质量文档
|
||
|
|
|
||
|
|
> 给项目的每个产品领域和架构层打分，跟踪代码库随时间是变强还是变弱，回答"这个项目在变强还是变弱"。
|
||
|
|
> 它评的是**代码库本身的质量**；单次 agent 输出质量见 [`evaluator-rubric.md`](evaluator-rubric.md)。
|
||
|
|
|
||
|
|
## 使用时机
|
||
|
|
|
||
|
|
- **开始会话前**：读它，了解代码库当前哪里最弱，优先处理。
|
||
|
|
- **会话结束后**：更新评级。
|
||
|
|
- **长期**：对比不同时间点的快照，看哪些改动真正改善了代码库健康度。
|
||
|
|
- 做基准对比、清理简化、或换新 agent / 新模型时，也更新一次。
|
||
|
|
|
||
|
|
## 评级标准
|
||
|
|
|
||
|
|
- **A**：验证全部通过，结构干净，agent 能读懂，测试稳定。
|
||
|
|
- **B**：验证通过，基本干净，可读性或测试覆盖有少量缺口。
|
||
|
|
- **C**：部分可用，有已知缺口，部分代码 agent 不容易理解。
|
||
|
|
- **D**：不可用，或存在重大结构问题。
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 产品领域
|
||
|
|
|
||
|
|
| 领域 | 评级 | 验证状态 | Agent 可读性 | 测试稳定性 | 关键缺口 | 上次更新 |
|
||
|
|
|------|------|---------|-------------|-----------|---------|---------|
|
||
|
|
| web 建单与人工决策 | C | 仅文档 | 高 | 无代码 | 原型与生产实现均未开始 | 2026-08-03 |
|
||
|
|
| desk 真机试选与下单 | D | 未取证 | 高 | 无代码 | T-103 单价节点与页面判据未取证 | 2026-08-03 |
|
||
|
|
| 提交围栏与结果调和 | C | 协议已定义 | 高 | 无代码 | T-208 / T-401 未实现 | 2026-08-03 |
|
||
|
|
| 任务数据与持久化 | C | 模型已定义 | 高 | 无代码 | schema / migration / 状态测试未实现 | 2026-08-03 |
|
||
|
|
| 身份与鉴权 | C | 合约已定义 | 高 | 无代码 | 管理会话与设备凭据未实现 | 2026-08-03 |
|
||
|
|
|
||
|
|
## 架构层
|
||
|
|
|
||
|
|
| 层级 | 评级 | 边界执行 | Agent 可读性 | 关键缺口 | 上次更新 |
|
||
|
|
|------|------|---------|-------------|---------|---------|
|
||
|
|
| web SSR 页面 | C | 文档明确 | 高 | 原型与 Go 实现未开始 | 2026-08-03 |
|
||
|
|
| desk PySide6 / 执行器 | D | 红线明确 | 高 | 原型、骨架、真机取证未开始 | 2026-08-03 |
|
||
|
|
| web API / 状态机 | C | 围栏协议已补齐 | 高 | 未实现、未测试 | 2026-08-03 |
|
||
|
|
| SQLite 数据层 | C | 核心实体已定义 | 高 | 迁移、约束和并发测试未实现 | 2026-08-03 |
|
||
|
|
| 拼多多 / ADB 适配 | D | 必须先取证 | 高 | 无本项目真机事实 | 2026-08-03 |
|
||
|
|
|
||
|
|
## 变更历史
|
||
|
|
|
||
|
|
### 2026-08-03
|
||
|
|
|
||
|
|
- 变更内容：完成文档级全栈复核；补齐 dry-run、提交前服务端围栏、点击后调和与 App 版本
|
||
|
|
fail-closed；把网页端 / 桌面端原型前置为 T-005 / T-006。
|
||
|
|
- 提升：API 与资金安全状态机不再只依赖点击后的客户端回报；生产 UI 有人工确认门槛。
|
||
|
|
- 下降：无。
|
||
|
|
- 新发现的缺口：尚无生产代码和真机证据；网页与桌面原型待生成。
|
||
|
|
- 已关闭的缺口：移除不存在的治理脚本 / `progress.md` 引用，替换质量文档占位领域。
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 进阶：验证 harness 是否可以简化
|
||
|
|
|
||
|
|
Harness 里的每个组件（规则、脚本、检查清单）都编码了一个假设——"模型做不到这件事"。模型变强后，这些假设可能过时。用本文档检查某个组件是否还有必要：
|
||
|
|
|
||
|
|
1. 拍一份本文档快照。
|
||
|
|
2. 移除一个 harness 组件。
|
||
|
|
3. 跑一轮基准任务。
|
||
|
|
4. 再拍一份快照。
|
||
|
|
5. 对比——评级没降，说明那个组件多余，可以去掉；降了，就恢复。
|