# @devflow-tools/telemetry

> 记录 Agent、tool、LLM 和语义控制事件，并生成健康度、失败分类和 ROI 汇总。（v0.17.8）

[![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
```

## 快速开始

```typescript
import { TelemetryEngine } from '@devflow-tools/telemetry';

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 / 命令

`TelemetryEngine`、`LogWriter`、`getLogWriter`、`emitSemanticControlLog`、`aggregateHealthStatus` 和 `createHealthSnapshot`。


## 配置与运行时

事件默认写入 DevFlow 本地数据库/日志目录；使用 `createLogger` 或 `LogWriter` 保持结构化字段，避免直接写 stdout。

## 版本与兼容性

- 当前包版本：`0.17.8`
- Node.js：未在 package manifest 声明更高版本时，使用 Node.js 18+；原生 SQLite/Playwright 能力请按对应依赖安装
- workspace 内部包应使用同一 DevFlow minor/patch 版本，避免类型和数据库 schema 不一致

## 相关链接

- [DevFlow 仓库](https://github.com/shilongfeicool/dev-flow)
- [问题反馈](https://github.com/shilongfeicool/dev-flow/issues)

## License

MIT