@devflow-tools/telemetry 0.17.5 → 0.17.6

package/README.md

@@ -1,62 +1,43 @@
 # @devflow-tools/telemetry
 
-DevFlow 遥测引擎 — 记录和分析 AI Agent 执行轨迹，提供 MCP 合规率统计、ROI 汇总和失败分类。
+> 记录 Agent、tool、LLM 和语义控制事件，并生成健康度、失败分类和 ROI 汇总。（v0.17.6）
 
-## Installation
+[![npm version](https://img.shields.io/npm/v/%40devflow-tools%2Ftelemetry.svg)](https://www.npmjs.com/package/@devflow-tools/telemetry)
+
+## 安装
 
 ```bash
 npm install @devflow-tools/telemetry
 ```
 
-## Usage
+## 快速开始
 
 ```typescript
 import { TelemetryEngine } from '@devflow-tools/telemetry';
 
-const engine = new TelemetryEngine({ projectRoot: '/path/to/project' });
+const telemetry = new TelemetryEngine(process.cwd());
+await telemetry.recordToolCall({ eventId: 'evt-1', executionId: 'run-1', timestamp: Date.now(), toolName: 'bash', toolType: 'shell', isMcpTool: false, mcpEnforced: false, mcpFallback: false, input: { command: 'npm test' }, tokensUsed: 0, duration: 1200, blocked: false });
+```
+
+## 公共 API / 命令
 
-// 记录 tool call 事件
-await engine.recordToolCall({
-  eventId: 'evt:123',
-  executionId: 'exec:456',
-  toolName: 'bash',
-  command: 'npm run build',
-  isMcpTool: false,
-  durationMs: 3200,
-});
+`TelemetryEngine`、`LogWriter`、`getLogWriter`、`emitSemanticControlLog`、`aggregateHealthStatus` 和 `createHealthSnapshot`。
 
-// 获取执行历史
-const runs = await engine.listRuns({ limit: 10 });
 
-// 获取 MCP 合规率
-const compliance = await engine.getMCPCompliance();
-```
+## 配置与运行时
+
+事件默认写入 DevFlow 本地数据库/日志目录；使用 `createLogger` 或 `LogWriter` 保持结构化字段，避免直接写 stdout。
+
+## 版本与兼容性
+
+- 当前包版本：`0.17.6`
+- Node.js：未在 package manifest 声明更高版本时，使用 Node.js 18+；原生 SQLite/Playwright 能力请按对应依赖安装
+- workspace 内部包应使用同一 DevFlow minor/patch 版本，避免类型和数据库 schema 不一致
+
+## 相关链接
 
-## Features
-
-- **Skill 执行追踪** — 完整生命周期记录（start → running → completed/failed）
-- **Tool Call 事件流** — 每次 tool 调用的详细记录（exitCode、stderr、output、durationMs）
-- **MCP 合规率** — 统计 MCP tool vs 直接 tool 调用比例
-- **失败分类** — 自动识别失败根因（上下文不足、知识缺失、工作流设计、工具错误等）
-- **ROI 汇总** — 效率指标、失败分布、工作流/插件健康度、每日趋势
-- **实验性 ROI** — baseline vs devflow 对比分析（时间节省率、Token 减少率）
-
-## API
-
-- `new TelemetryEngine({ projectRoot })` — 构造函数
-- `.recordToolCall(event)` — 记录单次 tool 调用事件
-- `.getToolCallEvents(executionId)` — 获取某次执行的所有事件
-- `.updateToolCallOutput(eventId, output)` — 回填 tool 调用结果
-- `.recordExecutionStart/Complete(params)` — skill 执行生命周期管理
-- `.getExecutions(filter?)` — 查询 skill 执行历史
-- `.getExecutionEvents(executionId)` — 获取执行事件流
-- `.getMCPCompliance()` — MCP 合规率统计
-- `.getPluginEffectiveness(name)` — 插件有效性分析
-- `.getPluginUsageStats()` — 插件使用统计
-- `.getExperimentalRoiSummary()` — 实验性 ROI 汇总
-- `.classifyFailure(runId)` — 失败分类
-- `.getRunStats(runId)` — 运行统计
-- `.cleanup(maxAge)` — 清理过期数据
+- [DevFlow 仓库](https://github.com/shilongfeicool/dev-flow)
+- [问题反馈](https://github.com/shilongfeicool/dev-flow/issues)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devflow-tools/telemetry",
-  "version": "0.17.5",
+  "version": "0.17.6",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -17,8 +17,8 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@devflow-tools/database": "0.17.4",
-    "@devflow-tools/sdk": "0.17.5"
+    "@devflow-tools/database": "0.17.6",
+    "@devflow-tools/sdk": "0.17.6"
   },
   "devDependencies": {
     "typescript": "^5.5.0",
@@ -27,5 +27,5 @@
   "files": [
     "dist"
   ],
-  "gitHead": "817b0286c249eed9c2bd27d3974ee3b3d6ded4bb"
+  "gitHead": "669fea3aa72aa3fde14ed50d24c1fec4dfac088f"
 }