feat(dev-workflow): 添加 Cross 模式统计报告功能

- 新增 stats.py 模块:record_event, get_stats, format_stats_report
- dev_workflow.py 添加 stats 和 record-event 命令
- 支持事件记录、统计报告、数据清理
- 安全特性:敏感数据过滤、文件锁、权限控制
- Cross-Debate 和 Cross-Review 记录文件
This commit is contained in:
2026-03-09 15:26:53 +08:00
parent 630dc09062
commit cee3598d37
5 changed files with 609 additions and 0 deletions
+155
View File
@@ -0,0 +1,155 @@
# Spec: Cross 模式统计报告
**创建时间:** 2026-03-09 14:38
**状态:** approved
**分支:** feature/cross-stats
**来源:** Cross-Debate
---
## 概述
给 dev-workflow 添加统计报告功能,显示 Cross 模式(Cross-Debate + Cross-Review)的使用情况。
---
## 背景
Cross 模式是 dev-workflow 的核心功能,需要了解其使用情况:
- 调用频率
- 成功率
- 常见场景
- 问题分布
---
## Cross-Debate 统一方案
### 共识
三个 Agent(保守派、全面派、快速派)经过交叉审查后达成共识:
> **"快速不等于简陋,结构化 + 缓存 + 权限是底线"**
### 渐进式架构
#### 短期(MVP)
```
日志埋点 → 结构化 JSON 存储 → Redis 缓存(TTL 5分钟)
```
#### 中期(加固)
```
Grafana 可视化 + 权限隔离(API 层最小校验)
```
#### 长期(完善)
```
数据脱敏 + 告警通知 + 定期归档
```
---
## 需求
### 功能需求
- [ ] **REQ-01**: 记录 Cross-Debate 调用事件(时间、场景、Agent 参与情况)
- [ ] **REQ-02**: 记录 Cross-Review 调用事件(时间、轮次、问题数量)
- [ ] **REQ-03**: 统计报告命令:`python3 dev_workflow.py stats`
- [ ] **REQ-04**: 输出格式:JSON + Markdown
- [ ] **REQ-05**: 统计维度:日/周/月、按场景、按成功率
### 非功能需求
- 性能:查询响应 < 100ms(通过 Redis 缓存)
- 安全:API 层最小权限校验
- 兼容:不破坏现有 dev_workflow.py 接口
---
## 技术设计
### 数据结构
```json
{
"cross_events": [
{
"timestamp": "2026-03-09T14:38:00Z",
"type": "debate" | "review",
"scenario": "功能设计" | "Bug修复" | "重构",
"agents": ["claude-code", "codex", "gemini"],
"duration_ms": 45000,
"status": "success" | "failed",
"issues_found": 3,
"rounds": 2
}
]
}
```
### 文件结构
```
dev-workflow/
├── dev_workflow.py # 添加 stats 命令
├── stats.py # 新增:统计逻辑
└── .data/
└── cross_events.json # 事件存储
```
### 实现步骤
1. 添加 `record_event()` 函数记录事件
2. 在 Cross-Debate 和 Cross-Review 流程中埋点
3. 实现 `stats` 命令输出报告
4. 添加 Redis 缓存(可选)
### 依赖
- 无新增外部依赖
- 可选:Redis(用于缓存)
---
## 测试计划
### 单元测试
- [ ] `record_event()` 正常记录
- [ ] `record_event()` 异常处理
- [ ] `get_stats()` 空数据返回
- [ ] `get_stats()` 正常统计
### 集成测试
- [ ] 完整 Cross-Debate 流程后查看统计
- [ ] 完整 Cross-Review 流程后查看统计
---
## 验收标准
1. 执行 `python3 dev_workflow.py stats` 输出统计报告
2. 报告包含:总调用次数、成功率、Top 5 场景
3. 数据持久化到 JSON 文件
4. 不影响现有功能
---
## 风险与缓解
| 风险 | 缓解措施 |
|------|----------|
| 并发写入冲突 | 使用文件锁或队列 |
| 存储增长 | 定期归档旧数据 |
| 敏感信息泄露 | 不记录用户输入内容 |
---
## 变更日志
| 日期 | 变更 |
|------|------|
| 2026-03-09 14:38 | 初始创建(来自 Cross-Debate 共识) |