dsh-local-telemetry 0.1.0

package/docs/schema.md

@@ -0,0 +1,165 @@
+# dsh-telemetry 事件契约（schema version 1.0）
+
+本文档定义 dsh-telemetry 事件的 JSON 结构、字段含义与使用约束。所有事件必须通过 `validateEvent` 校验，未知指标为 `null` 而非 0。
+
+## 事件列表（计划 §2）
+
+| 事件名 | 含义 |
+| --- | --- |
+| `request.started` | 用户请求开始（根 span） |
+| `request.context` | 请求上下文（可选 metadata，仅 capture_metadata="safe" 时脱敏附加） |
+| `model.requested` | 模型请求开始（attempt span） |
+| `model.first_token` | 模型首 Token 到达 |
+| `model.completed` | 模型请求成功完成 |
+| `model.failed` | 模型请求失败 |
+| `tool.started` | 工具调用开始 |
+| `tool.completed` | 工具调用完成 |
+| `plugin.started` | 插件 hook 开始 |
+| `plugin.completed` | 插件 hook 完成 |
+| `request.completed` | 用户请求成功完成 |
+| `request.cancelled` | 用户请求被取消 |
+
+**重要**：失败/超时/取消通过 `completed` 事件的 `result.status` 表达，无独立的 `tool.failed` 事件名。
+
+## 最小事件结构
+
+```json
+{
+  "schema_version": "1.0",
+  "event": "model.completed",
+  "event_id": "evt-001",
+  "trace_id": "trace-001",
+  "span_id": "span-003",
+  "parent_id": "span-001",
+  "timestamp": "2026-08-23T12:00:00.000Z",
+  "duration_ms": 8420,
+  "session": { "profile": "web", "environment": "local" },
+  "model": {
+    "provider": "deepseek",
+    "name": "deepseek-chat",
+    "request_type": "chat"
+  },
+  "usage": {
+    "input_tokens": 4200,
+    "output_tokens": 860,
+    "cached_input_tokens": 0,
+    "reasoning_tokens": null
+  },
+  "result": {
+    "status": "success",
+    "finish_reason": "stop"
+  },
+  "privacy": {
+    "content_captured": false,
+    "redactions": 0
+  }
+}
+```
+
+## 字段说明
+
+### 顶层字段
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `schema_version` | string | 是 | 当前为 "1.0" |
+| `event` | string | 是 | 事件名（必须为 12 种之一） |
+| `event_id` | string | 是 | 事件唯一 ID（推荐 `evt-` + 12 hex） |
+| `trace_id` | string | 是 | 请求追踪 ID（推荐 `trace-` + 12 hex） |
+| `span_id` | string | 是 | 跨时间线的操作 ID（用于配对 started/completed） |
+| `parent_id` | string | 否 | 父 span ID（构建树） |
+| `request_id` | string | 否 | 用户请求 ID（可选，request 事件常用） |
+| `timestamp` | string | 是 | ISO 8601 UTC（如 `2026-08-23T12:00:00.000Z`） |
+| `duration_ms` | number | 否 | 毫秒整数（非负整数，未知则 null） |
+| `session` | object | 否 | 请求会话信息 |
+| `model` | object | 否 | 模型信息（model 事件） |
+| `tool` | object | 否 | 工具信息（tool 事件） |
+| `plugin` | object | 否 | 插件信息（plugin 事件） |
+| `usage` | object | 否 | Token 使用量（model.completed 事件） |
+| `result` | object | 否 | 结果状态（终止型事件） |
+| `error` | object | 否 | 错误信息（失败/超时事件） |
+| `sampling` | object | 否 | 采样元数据（写入事件，用于解释聚合结果） |
+| `privacy` | object | 否 | 隐私元数据（content_captured/redactions/rules） |
+| `metadata` | object | 否 | 可选脱敏后的安全元数据（仅 safe 模式） |
+
+### session
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `profile` | string | Harness profile 名称（可配置哈希） |
+| `environment` | string | 环境（如 local / prod） |
+
+### model
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `provider` | string | 提供商（如 deepseek / openai） |
+| `name` | string | 模型名（如 deepseek-chat） |
+| `request_type` | string | 请求类型（如 chat / completion） |
+
+### tool
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `name` | string | 工具名 |
+
+### plugin
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `name` | string | 插件名 |
+| `hook` | string | Hook 名称（如 onRequest / onResponse） |
+
+### usage
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `input_tokens` | number | 输入 Token 数（整数，无则为 null） |
+| `output_tokens` | number | 输出 Token 数（整数，无则为 null） |
+| `cached_input_tokens` | number | 缓存命中输入 Token 数（整数，无则为 null） |
+| `reasoning_tokens` | number | 推理 Token 数（整数，无则为 null） |
+
+### result
+
+| 字段 | 类型 | 允许值 | 说明 |
+| --- | --- | --- | --- |
+| `status` | string | success / failed / timeout / cancelled | 操作结果 |
+| `finish_reason` | string | - | 完成原因（仅 model.completed） |
+
+### error
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `kind` | string | 错误分类（如 rate_limit / auth / network / server / invalid_request / timeout / unknown） |
+
+### sampling
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `rate` | number | 采样率（0..1） |
+| `strategy` | string | 策略标识（per-trace-hash-v1） |
+| `errors_always_sample` | boolean | 是否强制保留错误/取消 |
+
+### privacy
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `content_captured` | boolean | 是否采集了内容字段（默认 false） |
+| `redactions` | number | 脱敏命中次数 |
+| `rules` | string[] | 命中的脱敏规则名列表 |
+
+### metadata
+
+- 仅当 `capture_metadata="safe"` 时附加。
+- 脱敏后仅保留安全原语（数字/布尔/null/字符串）。
+- 敏感键（Authorization/Cookie/token/password/secret/api_key 等）整键丢弃。
+- 字符串值经过内置 + 自定义规则脱敏（URL 凭据、绝对路径、正则匹配）。
+
+## 约束
+
+- 时间戳必须为 ISO 8601 UTC（`YYYY-MM-DDThh:mm:ss.sssZ`）。
+- `duration_ms` 为非负整数；未知时为 null（不补 0）。
+- Token 字段为整数或 null；不可用 0 替代未知。
+- 成本计算仅在 模型名 + usage + 价格目录 三者齐备时进行，否则 `cost: null` 并记录缺失原因。
+- 采样按 trace 整体决策：同一 trace_id 的所有事件同决策，避免 trace 断裂。
+- 默认不采集内容字段（prompt/response/文件正文/命令参数/环境变量/密钥）。

package/examples/prices.json

@@ -0,0 +1,16 @@
+{
+  "currency": "USD",
+  "effective_at": "2026-08-23T00:00:00Z",
+  "models": {
+    "deepseek-chat": {
+      "input_per_million": 0.27,
+      "cached_input_per_million": 0.07,
+      "output_per_million": 1.1
+    },
+    "deepseek-reasoner": {
+      "input_per_million": 0.55,
+      "cached_input_per_million": 0.14,
+      "output_per_million": 2.19
+    }
+  }
+}

package/examples/telemetry.json

@@ -0,0 +1,17 @@
+{
+  "enabled": true,
+  "store": "jsonl",
+  "path": "~/.dsh/telemetry",
+  "sample_rate": 1,
+  "errors_always_sample": true,
+  "slow_request_ms": 10000,
+  "capture_metadata": "none",
+  "hash_names": false,
+  "retention_days": 7,
+  "max_file_mb": 100,
+  "flush_interval_ms": 1000,
+  "batch_size": 100,
+  "max_queue_events": 1000,
+  "price_catalog": null,
+  "redact_rules": []
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "dsh-local-telemetry",
+  "version": "0.1.0",
+  "description": "本地优先的 Harness 运行遥测插件：记录请求、模型、工具与插件生命周期指标（延迟、Token、成本、错误、缓存），默认不采集内容。Local-first Harness telemetry plugin for DeepSeek Harness. npm 包 dsh-local-telemetry（dsh-telemetry 名已被第三方占用）。",
+  "type": "module",
+  "main": "./plugin/index.js",
+  "exports": {
+    ".": "./plugin/index.js",
+    "./telemetry": "./src/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "telemetry": "./bin/telemetry.mjs",
+    "dsh-local-telemetry": "./bin/telemetry.mjs"
+  },
+  "files": [
+    "plugin/index.js",
+    "cordis.patch.yml",
+    "skills/",
+    "src",
+    "bin",
+    "web",
+    "docs",
+    "examples",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "PUBLISHING.md",
+    "DSH-TELEMETRY-开发计划.md"
+  ],
+  "scripts": {
+    "test": "node --test test/schema.test.mjs test/config.test.mjs test/privacy.test.mjs test/cost.test.mjs test/sink.test.mjs test/recorder.test.mjs test/store.test.mjs test/aggregate.test.mjs test/cli.test.mjs test/server.test.mjs test/manifest.test.mjs",
+    "prepublishOnly": "npm test",
+    "check": "node --check bin/telemetry.mjs && node --check src/index.mjs && node --check src/schema.mjs && node --check src/config.mjs && node --check src/privacy.mjs && node --check src/sampling.mjs && node --check src/cost.mjs && node --check src/sink-jsonl.mjs && node --check src/sink-sqlite.mjs && node --check src/adapter.mjs && node --check src/recorder.mjs && node --check src/store.mjs && node --check src/aggregate.mjs && node --check src/report.mjs && node --check src/server.mjs && node --check plugin/index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-skill-filesystem": "*"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-skill-filesystem": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "telemetry",
+    "observability",
+    "local-first",
+    "privacy"
+  ],
+  "license": "MIT"
+}

package/plugin/index.js

@@ -0,0 +1,82 @@
+/**
+ * dsh-local-telemetry — DSH (DeepSeek Harness) 插件入口（GitHub 仓库 dsh-telemetry；npm 名 dsh-telemetry 已被第三方占用）。
+ *
+ * 职责（计划 §10）：读取配置、注册技能根、惰性创建 sink/记录器、
+ * 注册关闭时 flush 的资源清理逻辑、暴露查询 CLI 与本地服务。
+ *
+ * 遥测是旁路能力（fail-open）：
+ * - 初始化失败不阻止 Harness 启动（只留一次性 stderr 提示）；
+ * - 不注册任何改变请求语义的人设、工具或参数；
+ * - 宿主生命周期 Hook 尚未确认（计划 §2），事件经显式适配器接入：
+ *   宿主集成代码 `import { createRecorder } from "dsh-local-telemetry/telemetry"`。
+ */
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { createRequire } from "node:module";
+import { createRecorder } from "../src/recorder.mjs";
+
+export const name = "dsh-local-telemetry";
+
+const rootDir = join(dirname(fileURLToPath(import.meta.url)), "..");
+const skillsDir = join(rootDir, "skills");
+const requireOptional = createRequire(import.meta.url);
+
+let sharedRecorder = null;
+
+/** 供宿主集成代码获取共享记录器（惰性创建；配置 enabled=false 时仍可创建，由 record() 自行短路）。 */
+export function getTelemetry(config) {
+  if (!sharedRecorder) {
+    sharedRecorder = createRecorder(config ?? {});
+  }
+  return sharedRecorder;
+}
+
+export function apply(ctx, config = {}) {
+  let provider;
+  let skillsRegistered = false;
+
+  // 技能注册：复用官方 FileSystemSkillProvider；不可用时静默降级（遥测核心不依赖技能）
+  try {
+    const { FileSystemSkillProvider } = requireOptional("@deepseek-ai/dsh-skill-filesystem");
+    ctx.skills.registerProvider((control) => {
+      provider = new FileSystemSkillProvider(ctx, control, {
+        providerName: "dsh-local-telemetry",
+        includeDefaultRoots: false,
+        customSkillDirs: [skillsDir],
+      });
+      skillsRegistered = true;
+      return provider;
+    });
+  } catch {
+    console.warn?.("[dsh-local-telemetry] skill provider unavailable; CLI and library interfaces remain usable");
+  }
+
+  // 记录器预热（惰性 sink：首个事件落盘前不创建文件）
+  let recorder = null;
+  try {
+    recorder = getTelemetry(config?.telemetry);
+    void recorder.start?.();
+  } catch {
+    recorder = null; // fail-open：遥测初始化失败不影响 Harness
+  }
+
+  ctx.effect(
+    function* () {
+      yield async () => {
+        try {
+          if (provider && typeof provider.dispose === "function") await provider.dispose();
+        } catch {
+          /* ignore */
+        }
+        try {
+          if (recorder && typeof recorder.close === "function") await recorder.close();
+        } catch {
+          /* 关闭 flush 失败不阻塞退出（§6.3） */
+        }
+      };
+    },
+    "dsh-local-telemetry skill provider + telemetry flush"
+  );
+
+  return { name, skillsRegistered };
+}

package/skills/telemetry-runbook/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: telemetry-runbook
+description: 本地遥测查询与诊断：查询 Harness 请求、模型、工具、插件生命周期指标（延迟分位数、Token、估算成本、错误分类、重试与回退），查看 trace/span 树，导出 Markdown 报告，清理保留期数据，或启动本地只读 Web UI。需要分析请求耗时、Token 成本、工具失败或验证遥测采集状态时加载本技能。
+---
+
+# telemetry-runbook
+
+dsh-local-telemetry runbook（GitHub 仓库 dsh-telemetry；npm 名 dsh-telemetry 已被第三方占用）。遥测是旁路能力：查询只读本地存储，不联网；默认不采集 prompt / response / 文件内容 / 密钥。CLI 路径以仓库根为基准（插件安装后为 `<bundle-dir>/bin/telemetry.mjs`）。
+
+## 调用方式
+
+```bash
+# 采集状态与累计计数（written / dropped / sampled_out）
+node bin/telemetry.mjs --status
+node bin/telemetry.mjs --status --json
+
+# 摘要（默认窗口全量；百分比与分位数为 nearest-rank，可由原始事件重算）
+node bin/telemetry.mjs --summary --since 1h
+node bin/telemetry.mjs --summary --since 24h --group-by model       # model|plugin|tool|profile|day
+node bin/telemetry.mjs --summary --errors-only --slow-over-ms 10000
+
+# trace/span 树
+node bin/telemetry.mjs --trace <trace_id>
+
+# 导出（json 或 markdown；markdown 生成 TELEMETRY-REPORT.md 结构）
+node bin/telemetry.mjs --export summary.json --since 7d
+node bin/telemetry.mjs --export TELEMETRY-REPORT.md --since 7d --format markdown
+
+# 保留期清理（删除 30 天前的日期文件/行）
+node bin/telemetry.mjs --purge --before 30d
+
+# 本地只读 Web UI（仅绑定 127.0.0.1，禁止暴露局域网）
+node bin/telemetry.mjs --ui --port 47610
+
+# 配置文件
+node bin/telemetry.mjs --config telemetry.json --summary --since 24h
+```
+
+## 常用参数
+
+- `--store jsonl|sqlite`：存储后端；sqlite 需要 Node ≥ 22.5（内置 node:sqlite），低版本会明确报错并建议回退 jsonl。
+- `--path <dir>`：数据目录（默认 `~/.dsh/telemetry`；JSONL 按日期命名 `<YYYY-MM-DD>.jsonl`，超过 100MB 轮转 `.part-NNN`）。
+- `--since / --until`：`500ms|10s|30m|1h|7d|30d` 或 ISO 时间戳。
+- `--profile / --model / --plugin / --event <name|prefix.*>`：维度过滤。
+- `--format text|json|markdown`；`--json` 等价 `--format json`。
+
+## 库接口（宿主集成 / 上层插件）
+
+宿主生命周期 Hook 尚未确认，事件经显式适配器接入：
+
+```js
+import { createRecorder, createEventBusAdapter } from 'dsh-local-telemetry/telemetry';
+
+const recorder = createRecorder({ config: { path: '~/.dsh/telemetry', capture_metadata: 'safe' } });
+await recorder.start();
+recorder.record({
+  event: 'model.completed',
+  trace_id: 'trace-001', span_id: 'span-003', parent_id: 'span-001',
+  timestamp: '2026-08-23T12:00:00.000Z',
+  model: { provider: 'deepseek', name: 'deepseek-chat', request_type: 'chat' },
+  usage: { input_tokens: 4200, output_tokens: 860, cached_input_tokens: 0, reasoning_tokens: null },
+  result: { status: 'success', finish_reason: 'stop' },
+});
+await recorder.close(); // 退出前 flush；失败不阻塞
+```
+
+聚合读取（供 dsh-test-insight 等按 §15 边界通过公开聚合接口使用）：
+
+```js
+import { openStore, aggregateEvents, buildTraceView } from 'dsh-local-telemetry/telemetry';
+const store = await openStore({ store: 'jsonl', path: '~/.dsh/telemetry' });
+const { events } = await store.readEvents({ fromMs: Date.now() - 3600e3 });
+const summary = aggregateEvents(events, { catalog: null });
+```
+
+## 事件契约要点
+
+- 12 种生命周期事件（schema_version 1.0）；失败/超时用 completed 事件的 `result.status` 表达，无独立 `tool.failed` 事件名。
+- 时长不在事件里臆造：聚合器按 `span_id` 配对 started/completed 推导；两端缺失则为 null。
+- 未知指标为 null，不补 0；Token 只记录宿主/模型返回的真实 usage。
+- 采样按 trace 整体决策（salted hash），错误/取消/慢请求默认绕过；`sampling` 块写入事件元数据。
+- 成本仅在模型、usage、价格目录齐备时计算，否则 `cost: null` 并给出缺失原因。
+
+## 解读提示
+
+- 摘要样本数 n 与分位数方法随输出标注；窗口不同结果不可直接比较。
+- `dropped` 计数为存储级累计值（write/queue/oversize/invalid/sampled），与时间窗口无关。
+- 估算成本 ≠ 实际账单；价格目录版本与生效时间在摘要与 Markdown 报告附录中标注。

package/src/adapter.mjs

@@ -0,0 +1,79 @@
+/**
+ * dsh-local-telemetry — 宿主适配器（计划 §2）。
+ *
+ * DSH Harness 的生命周期 Hook（request.started / model.completed / …）目前
+ * 无法确认其真实暴露面。按计划 §2 的降级路径：
+ *   1. 只实现独立事件记录器与显式适配器接口；
+ *   2. 只接入已确认存在的生命周期事件（当前：无，全部经显式 emit 接入）；
+ *   3. 缺失指标返回 null / unavailable，不从时间戳臆造；
+ *   4. 用适配器隔离具体 DSH 版本，宿主私有 API 不散落到各模块。
+ *
+ * 因此 getCapabilities() 如实声明：lifecycle_hooks: "unconfirmed"。
+ * 宿主未来确认 Hook 后，仅需提供一个新的 adapter 实现，其余模块零改动。
+ */
+
+import { SCHEMA_VERSION } from "./schema.mjs";
+
+/** 能力声明：未确认的能力一律 "unconfirmed"，不得伪造成可用。 */
+export function createCapabilities(overrides = {}) {
+  return Object.freeze({
+    schema_version: SCHEMA_VERSION,
+    lifecycle_hooks: "unconfirmed", // "full" | "partial" | "none" | "unconfirmed"
+    events: [], // 宿主确认可提供的事件名；显式接入模式下由 emit 方声明
+    usage_tokens: "unconfirmed",
+    cache_tokens: "unconfirmed",
+    cost_model: "catalog", // 成本来自版本化价格目录，非宿主
+    ...overrides,
+  });
+}
+
+/**
+ * 显式事件总线适配器 — 当前唯一受支持的接入方式。
+ * 嵌入方（宿主集成代码、其他插件、测试）通过 emit() 送入事件，
+ * 录制器经 on() 消费。on() 返回解绑函数。
+ */
+export function createEventBusAdapter({ capabilities } = {}) {
+  const handlers = new Map(); // eventName | "*" -> Set<handler>
+  const caps = createCapabilities({
+    lifecycle_hooks: "none",
+    ...capabilities,
+  });
+
+  function on(eventName, handler) {
+    if (typeof handler !== "function") return () => {};
+    if (!handlers.has(eventName)) handlers.set(eventName, new Set());
+    handlers.get(eventName).add(handler);
+    return () => handlers.get(eventName)?.delete(handler);
+  }
+
+  function emit(event) {
+    let delivered = 0;
+    const sets = [handlers.get("*"), handlers.get(event?.event)].filter(Boolean);
+    for (const set of sets) {
+      for (const handler of set) {
+        try {
+          handler(event);
+          delivered += 1;
+        } catch {
+          /* 单个 handler 异常不阻断其余订阅者（fail-open） */
+        }
+      }
+    }
+    return delivered;
+  }
+
+  function getCapabilities() {
+    return caps;
+  }
+
+  return { on, emit, getCapabilities };
+}
+
+/**
+ * 能力探测：以最保守结果响应。绝不因为探测代码「没有抛错」就声明宿主
+ * 具备 Hook（缺失宿主能力不会被伪造成可用指标 —— Phase 0 验收）。
+ */
+export function detectCapabilities(host) {
+  if (!host || typeof host !== "object") return createCapabilities();
+  return createCapabilities();
+}