feat: 添加 Cross 模式统计报告功能

- 添加 stats.py 统计模块 - 添加 dev_workflow.py CLI 工具 - 实现 record_event() 记录事件 - 实现 get_stats() 生成报告 - 支持敏感数据自动过滤 - 使用原子写入保证数据安全 - 添加 README 文档
2026-03-09 14:44:04 +08:00
parent 512f7fdf41
commit 3efe98e17d
4 changed files with 562 additions and 0 deletions
@@ -0,0 +1,146 @@
+# Dev Workflow - 开发工作流工具
+
+Cross 模式统计报告功能
+
+## 功能特性
+
+- ✅ 事件记录和统计
+- ✅ 多模式支持（cross, normal 等）
+- ✅ 敏感数据自动过滤
+- ✅ 原子写入保证数据安全
+- ✅ 格式化报告输出
+
+## 使用方法
+
+### 查看统计报告
+
+```bash
+python3 dev-workflow/dev_workflow.py stats
+```
+
+### 筛选特定模式
+
+```bash
+python3 dev-workflow/dev_workflow.py stats --mode cross
+```
+
+### 记录事件（用于集成）
+
+```bash
+python3 dev-workflow/dev_workflow.py record "event_type" --mode cross --description "事件描述"
+```
+
+### 清空统计数据
+
+```bash
+python3 dev-workflow/dev_workflow.py clear --confirm
+```
+
+## API 使用
+
+### Python 代码中记录事件
+
+```python
+from stats import record_event, get_stats, format_stats_report
+
+# 记录事件
+record_event(
+    "task_completed",
+    mode="cross",
+    metadata={
+        "task_name": "开发功能",
+        "duration": 120
+    }
+)
+
+# 获取统计数据
+stats = get_stats(mode="cross")
+print(format_stats_report(stats))
+```
+
+## 安全特性
+
+### 敏感数据过滤
+
+以下字段会被自动过滤（替换为 `[REDACTED]`）：
+- password
+- token
+- secret
+- key
+- credential
+- auth
+
+示例：
+```python
+record_event("login", metadata={
+    "username": "user123",      # 正常记录
+    "password": "secret123"     # 记录为 [REDACTED]
+})
+```
+
+### 原子写入
+
+所有数据写入都使用原子操作（临时文件 + 重命名），确保：
+- 并发写入不会损坏数据
+- 系统崩溃不会丢失数据
+- 临时文件自动清理
+
+## 数据存储
+
+- 位置：`dev-workflow/data/stats_data.json`
+- 格式：JSON
+- 结构：
+  ```json
+  {
+    "events": [
+      {
+        "event_type": "string",
+        "mode": "string",
+        "timestamp": "ISO8601",
+        "metadata": {}
+      }
+    ],
+    "metadata": {
+      "created_at": "ISO8601",
+      "last_updated": "ISO8601"
+    }
+  }
+  ```
+
+## 统计报告内容
+
+报告包含以下信息：
+- 总事件数
+- 时间范围（首次和最后事件）
+- 按事件类型统计
+- 按模式统计
+- 按日期统计（最近7天）
+
+## 开发说明
+
+### 文件结构
+
+```
+dev-workflow/
+├── dev_workflow.py    # CLI 工具
+├── stats.py           # 统计模块
+├── README.md          # 本文档
+└── data/
+    └── stats_data.json  # 数据存储
+```
+
+### 扩展事件类型
+
+可以在代码中定义新的事件类型，例如：
+- `task_started` - 任务开始
+- `task_completed` - 任务完成
+- `code_committed` - 代码提交
+- `error_occurred` - 错误发生
+- `stats_viewed` - 查看统计
+
+## 测试
+
+运行测试：
+```bash
+python3 dev-workflow/stats.py
+```