starmen1265
cee3598d37
- 新增 stats.py 模块：record_event, get_stats, format_stats_report - dev_workflow.py 添加 stats 和 record-event 命令 - 支持事件记录、统计报告、数据清理 - 安全特性：敏感数据过滤、文件锁、权限控制 - Cross-Debate 和 Cross-Review 记录文件
156 lines
3.1 KiB
Markdown
156 lines
3.1 KiB
Markdown
# 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 共识） |
|