dsh-local-telemetry 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 duyanta123
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PUBLISHING.md

@@ -0,0 +1,42 @@
+# Publishing
+
+## 命名说明（重要）
+
+- npm 包名：`dsh-local-telemetry`。`dsh-telemetry` 在 npm 上已被第三方（tudamu，2026-08-20 发布 0.0.1，同为 DeepSeek Harness 遥测方向）占用，故改名；已验证 `dsh-local-telemetry` 未注册。
+- GitHub 仓库名保持 `dsh-telemetry`（小写，与 dsh-repo-scanner 惯例一致）。
+- bin 命令：`telemetry` 与 `dsh-local-telemetry`；exports 子路径 `dsh-local-telemetry/telemetry`；cordis.patch.yml 插件行 id/name 均为 `dsh-local-telemetry`（manifest 契约测试强制与 package.json name 一致）。
+
+## 发布前检查清单
+
+1. 运行 `npm test`（127/127 全绿）与 `npm run check`（全模块语法检查），确保全部通过。
+2. 运行 `npm pack --dry-run`，确认包含 `plugin/index.js`、`cordis.patch.yml`、`skills/`、`src/`、`bin/`、`web/`、`docs/`、`examples/`、`README.md`、`CHANGELOG.md`、`LICENSE`、`PUBLISHING.md`、`DSH-TELEMETRY-开发计划.md`。
+3. 版本一致性：`package.json` version、`bin/telemetry.mjs` USAGE 版本号、`src/aggregate.mjs` `tool.version`、`CHANGELOG.md` 发布段、git tag 五处保持一致（manifest 契约测试覆盖前三处）。
+
+## DSH bundle 契约（对齐 2026-09 现行契约）
+
+- `package.json` 声明 `dsh.bundle.patch: ./cordis.patch.yml`——harness 只激活声明该字段的包。
+- `cordis.patch.yml` 为 config-tree `- insert:` 补丁格式；harness 加载 `main`（`plugin/index.js`）。
+- `plugin/index.js` 经官方 `@deepseek-ai/dsh-skill-filesystem` 的 `FileSystemSkillProvider` 注册 `skills/` 为技能根（includeDefaultRoots: false）。
+- `skills/telemetry-runbook/SKILL.md` frontmatter 必填 `name`（kebab-case）+ `description`。
+- 扫描内核经 exports 子路径 `dsh-local-telemetry/telemetry` 暴露；CLI bin 为 `telemetry` / `dsh-local-telemetry`。
+
+## 发布渠道
+
+### GitHub
+
+1. push `main`，确认 GitHub Actions CI 全绿（Node 18/20/22 × Windows/Ubuntu）。
+2. 打 tag `v0.1.0` 并推送。
+3. 给仓库添加 GitHub topic `dsh-plugin`（awesome 收录门槛之一）。
+
+### npm
+
+1. `npm login`（bugcome 账号）。
+2. `npm publish`（首次发布非 scope 公有包无需 `--access public`；`prepublishOnly` 会先跑 `npm test`）。
+3. 发布后核对 `npm view dsh-local-telemetry version` 与 dist-tags。
+
+### awesome-dsh-plugin 收录（可选，参照 dsh-repo-scanner 经验）
+
+- 仓库需创建满 1 天且 ≥10 个提交（自动检查，过滤一次性投稿仓；本仓历史提交偏少，可先补收尾提交再投）。
+- 仓库 `package.json` 必须声明 `dsh.bundle`（根包或 packages/ 子包）。
+- 需给仓库加 GitHub topic `dsh-plugin`。
+- 检查失败后向同一分支推送修复即可，无需重开 PR。

package/README.md

@@ -0,0 +1,156 @@
+# dsh-telemetry
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![DeepSeek Harness](https://img.shields.io/badge/DeepSeek%20Harness-plugin-4c1d95)](https://github.com/topics/dsh-plugin)
+[![CI](https://github.com/duyanta123/dsh-telemetry/actions/workflows/ci.yml/badge.svg)](https://github.com/duyanta123/dsh-telemetry/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/badge/npm-dsh--local--telemetry-blue)](https://www.npmjs.com/package/dsh-local-telemetry)
+[![version](https://img.shields.io/badge/version-0.1.0-green)](CHANGELOG.md)
+
+本地优先的 Harness 运行遥测插件：记录请求、模型、工具与插件生命周期指标（延迟、Token、成本、错误、缓存），默认不采集内容。
+
+> npm 包名为 `dsh-local-telemetry`（`dsh-telemetry` 在 npm 上已被第三方占用）；GitHub 仓库名保持 `dsh-telemetry`，两者指向同一项目。
+
+## 定位
+
+dsh-telemetry 是 Harness 运行可观测性插件，不负责业务分析，不负责修改请求内容，也不负责把用户对话上传到第三方平台。
+
+它回答：
+- 一次请求花了多少时间？
+- 时间消耗在模型、工具、插件还是排队？
+- 输入/输出 Token 和重试成本是多少？
+- 哪些工具调用最慢、最容易失败？
+- 哪些插件发生异常或阻塞？
+- 缓存是否命中，模型路由是否节省了成本？
+- 是否存在上下文过大、循环工具调用和异常重试？
+
+一句话定位：
+
+> Make Harness behavior measurable without collecting sensitive conversation content by default.
+
+## 安装
+
+作为 DSH 插件（推荐）：
+
+```bash
+dsh plugin --profile web add "github:duyanta123/dsh-telemetry#main"
+```
+
+或从 npm 安装（作为库或独立 CLI 使用）：
+
+```bash
+npm install dsh-local-telemetry
+```
+
+安装后重启 `dsh --profile web`，即可通过 `telemetry-runbook` 技能使用查询 CLI：
+
+```bash
+node bin/telemetry.mjs --status
+node bin/telemetry.mjs --summary --since 24h
+node bin/telemetry.mjs --trace <trace_id>
+node bin/telemetry.mjs --ui --port 47610
+```
+
+## 快速开始
+
+### 1. 作为宿主集成代码使用
+
+事件经显式适配器接入（当前推荐的唯一方式）：
+
+```js
+import { createRecorder } from 'dsh-local-telemetry/telemetry';
+
+const recorder = createRecorder({
+  config: {
+    path: '~/.dsh/telemetry',
+    capture_metadata: 'safe', // 默认 none，不采集内容
+    hash_names: false,
+    sample_rate: 1,
+    errors_always_sample: true,
+    slow_request_ms: 10000,
+    retention_days: 7,
+  },
+});
+await recorder.start();
+
+// 记录一条事件（缺失的 id 和 timestamp 会自动补全）
+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' },
+});
+
+// 退出前 flush；失败不阻塞退出
+await recorder.close();
+```
+
+### 2. 聚合读取（上层插件可引用）
+
+```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 });
+
+console.log(`P95 latency: ${summary.requests.latency.p95}ms, Input tokens: ${summary.tokens.input}`);
+```
+
+### 3. 作为 DSH 技能调用（CLI 由技能指引）
+
+```bash
+node bin/telemetry.mjs --summary --since 1h --group-by model
+node bin/telemetry.mjs --export TELEMETRY-REPORT.md --since 7d --format markdown
+node bin/telemetry.mjs --purge --before 30d
+node bin/telemetry.mjs --ui --port 47610
+```
+
+## CLI 参数
+
+| 参数 | 默认 | 说明 |
+| --- | --- | --- |
+| `--store jsonl\|sqlite` | jsonl | 存储后端（sqlite 需 Node ≥22.5） |
+| `--path <dir>` | ~/.dsh/telemetry | 数据目录 |
+| `--config <file>` | - | 配置文件 |
+| `--since <duration\|ts>` | - | 时间窗起点（如 1h / 7d / ISO 时间戳） |
+| `--until <duration\|ts>` | - | 时间窗终点 |
+| `--profile <name>` | - | 按 profile 过滤 |
+| `--model <name>` | - | 按模型过滤 |
+| `--plugin <name>` | - | 按插件过滤 |
+| `--event <name\|prefix.*>` | - | 按事件过滤（如 model.*） |
+| `--group-by <key>` | - | 分组：model\|plugin\|tool\|profile\|day |
+| `--format text\|json\|markdown` | text | 输出格式（`--export` 未指定时按扩展名 `.json`/`.md` 推断） |
+| `--errors-only` | - | 只看错误与取消 |
+| `--slow-over-ms <N>` | - | 只看耗时 ≥ N 的请求 |
+| `--sample-rate <0..1>` | - | 采样率（录制侧配置） |
+| `--capture-metadata none\|safe` | - | metadata 采集（录制侧配置） |
+| `--purge --before <d>` | - | 保留期清理 |
+
+## 隐私与安全
+
+- **默认不采集内容**：prompt、response、文件内容、命令参数、环境变量和密钥。
+- **脱敏策略**：敏感字段（Authorization、Cookie、token、password、api_key 等）整键丢弃；URL 凭据与 query token 脱敏；绝对路径可配置为 basename 或哈希。
+- **名称哈希**：工具、插件、模型名与 profile 可配置哈希化，稳定但不可直接还原。
+- **本地存储**：默认 `~/.dsh/telemetry`（JSONL 按日期分文件，SQLite 可选），不联网。
+- **只读 UI**：`--ui` 只绑定 127.0.0.1，禁止默认暴露到局域网。
+
+## 版本规划
+
+### v0.1.0
+
+- 本地 JSONL + 可选 SQLite（Node ≥22.5 内置 `node:sqlite`）
+- request/model/tool/plugin 基础事件
+- 启停配置、fail-open、`--status`、`--summary`、`--trace`、`--export`、`--purge`、`--ui`
+- 默认不采集内容
+- 采样、慢请求、错误保留策略
+- 成本目录、脱敏、隐私块、保留期清理
+- Markdown 报告
+- Trace/span 树与时间线视图
+
+## 许可证
+
+MIT

package/bin/telemetry.mjs

@@ -0,0 +1,295 @@
+#!/usr/bin/env node
+/**
+ * dsh-local-telemetry — 查询 CLI（计划 §10）。
+ *
+ *   node bin/telemetry.mjs --status
+ *   node bin/telemetry.mjs --summary --since 24h --group-by model
+ *   node bin/telemetry.mjs --trace <trace_id>
+ *   node bin/telemetry.mjs --export report.json --since 7d
+ *   node bin/telemetry.mjs --export TELEMETRY-REPORT.md --since 7d --format markdown
+ *   node bin/telemetry.mjs --config telemetry.json --summary
+ *   node bin/telemetry.mjs --purge --before 30d
+ *   node bin/telemetry.mjs --ui --port 47610
+ *
+ * 全部命令只读本地存储（--purge 除外）；遥测查询不联网。
+ */
+
+import { writeFile } from "node:fs/promises";
+import { resolveDataPath, sinceUntilRange, parseDurationOrTimestamp, loadConfigFile, resolveConfig } from "../src/config.mjs";
+import { openStore } from "../src/store.mjs";
+import { aggregateEvents, aggregateGrouped, slowTraceIds, buildTraceView } from "../src/aggregate.mjs";
+import { loadPriceCatalog } from "../src/cost.mjs";
+import { renderTextSummary, renderMarkdownReport, renderTraceText, renderGroupedText } from "../src/report.mjs";
+import { createTelemetryServer } from "../src/server.mjs";
+
+const USAGE = `dsh-local-telemetry — 本地 Harness 遥测查询 CLI（v0.1.0）
+
+用法：
+  node bin/telemetry.mjs --status
+  node bin/telemetry.mjs --summary [--since 1h] [--until <t>] [--group-by model|plugin|tool|profile|day]
+  node bin/telemetry.mjs --trace <trace_id>
+  node bin/telemetry.mjs --export <file> [--since 7d] [--format text|json|markdown]
+  node bin/telemetry.mjs --purge --before 30d
+  node bin/telemetry.mjs --ui [--port 47610]
+
+参数：
+  --store jsonl|sqlite      存储后端（默认 jsonl；sqlite 需 Node ≥22.5）
+  --path <dir>              数据目录（默认 ~/.dsh/telemetry）
+  --config <file>           配置文件（解析失败时按「关闭」安全默认）
+  --since <duration|ts>     时间窗起点（如 1h / 7d / ISO 时间戳）
+  --until <duration|ts>     时间窗终点
+  --profile <name>          按 profile 过滤
+  --model <name>            按模型过滤
+  --plugin <name>           按插件过滤
+  --event <name|prefix.*>   按事件过滤（如 model.*）
+  --group-by <key>          分组：model | plugin | tool | profile | day
+  --format text|json|markdown  输出格式（默认 text；--export 未指定时按扩展名 .json/.md 推断）
+  --errors-only             只看错误与取消
+  --slow-over-ms <N>        只看耗时 ≥ N 的请求
+  --sample-rate <0..1>      采样率（录制侧配置，查询命令接受但仅用于配置覆盖）
+  --capture-metadata none|safe  metadata 采集（录制侧配置，同上）
+  --json                    等价于 --format json
+  --help                    本帮助
+
+说明：所有摘要标注时间范围、样本数与分位数方法（nearest-rank）；成本为估算值。
+`;
+
+function parseArgs(argv) {
+  const flags = new Map();
+  const positional = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      const next = argv[i + 1];
+      const takesValue = !["status", "summary", "purge", "ui", "errors-only", "json", "help"].includes(key);
+      if (takesValue && next !== undefined && !next.startsWith("--")) {
+        flags.set(key, next);
+        i += 1;
+      } else {
+        flags.set(key, true);
+      }
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { flags, positional };
+}
+
+function fail(message, code = 2) {
+  console.error(`dsh-local-telemetry: ${message}`);
+  process.exit(code);
+}
+
+/** --json 显式优先；其次 --format；--export 时按目标扩展名推断（.json→json，.md→markdown）；默认 text。 */
+function resolveFormat(flags) {
+  if (flags.get("json")) return "json";
+  const explicit = flags.get("format");
+  if (explicit) return String(explicit);
+  const exportTarget = flags.get("export");
+  if (typeof exportTarget === "string") {
+    if (exportTarget.endsWith(".json")) return "json";
+    if (exportTarget.endsWith(".md")) return "markdown";
+  }
+  return "text";
+}
+
+async function main() {
+  const { flags, positional } = parseArgs(process.argv.slice(2));
+  if (flags.get("help") || (flags.size === 0 && positional.length === 0)) {
+    process.stdout.write(USAGE);
+    process.exit(flags.get("help") ? 0 : 2);
+  }
+
+  // ---- 配置：文件 + CLI 覆盖 ----
+  let fileConfig = undefined;
+  if (flags.get("config")) {
+    const loaded = loadConfigFile(String(flags.get("config")));
+    fileConfig = loaded.config;
+    if (!loaded.ok) {
+      for (const error of loaded.errors) console.error(`[config] ${error}`);
+    }
+  }
+  const overrides = {};
+  if (flags.get("store")) overrides.store = String(flags.get("store"));
+  if (flags.get("path")) overrides.path = String(flags.get("path"));
+  if (flags.get("sample-rate")) overrides.sample_rate = Number(flags.get("sample-rate"));
+  if (flags.get("capture-metadata")) overrides.capture_metadata = String(flags.get("capture-metadata"));
+  const resolution = resolveConfig({ file: fileConfig, overrides });
+  if (!resolution.ok) {
+    for (const error of resolution.errors) console.error(`[config] ${error}`);
+  }
+  const config = resolution.config;
+  const format = resolveFormat(flags);
+  const dataPath = flags.get("path") ? resolveDataPath(String(flags.get("path"))) : resolveDataPath(config.path);
+
+  if (flags.get("store") === "sqlite" && config.store === "sqlite") {
+    const { isSqliteSupported } = await import("../src/sink-sqlite.mjs");
+    if (!(await isSqliteSupported())) {
+      fail("sqlite backend requires Node >= 22.5 (node:sqlite); use --store jsonl on this runtime", 1);
+    }
+  }
+
+  const store = await openStore({ store: config.store, path: dataPath });
+
+  // ---- --status ----
+  if (flags.get("status")) {
+    const status = await store.status();
+    if (typeof store.close === "function") store.close();
+    if (format === "json") {
+      process.stdout.write(`${JSON.stringify(status, null, 2)}\n`);
+    } else {
+      const lines = [
+        `Store: ${status.store}`,
+        `Path:  ${status.path}`,
+        status.unavailable ? `Note:  ${status.unavailable}` : null,
+        `Files: ${status.files.length} (${status.total_bytes} bytes)${status.rows !== undefined ? `, rows: ${status.rows}` : ""}`,
+        `Counters: written=${status.counters.written} dropped(write=${status.counters.dropped_write} queue=${status.counters.dropped_queue} oversize=${status.counters.dropped_oversize} invalid=${status.counters.dropped_invalid}) sampled_out=${status.counters.sampled_out}`,
+      ].filter(Boolean);
+      process.stdout.write(`${lines.join("\n")}\n`);
+    }
+    return;
+  }
+
+  // ---- --purge --before <duration> ----
+  if (flags.get("purge")) {
+    const before = flags.get("before");
+    if (!before || before === true) fail("--purge requires --before <duration> (e.g. 30d)");
+    const parsed = parseDurationOrTimestamp(String(before));
+    if (!parsed) fail(`invalid --before value: ${before}`);
+    const cutoffMs = parsed.relative ? Date.now() - parsed.absolute : parsed.absolute;
+    const result = await store.purge({ beforeMs: cutoffMs });
+    if (typeof store.close === "function") store.close();
+    if (format === "json") {
+      process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    } else {
+      process.stdout.write(
+        `Purged before ${new Date(cutoffMs).toISOString()}: removed_files=${result.removed_files} removed_bytes=${result.removed_bytes}${result.removed_rows !== undefined ? ` removed_rows=${result.removed_rows}` : ""}\n`
+      );
+    }
+    return;
+  }
+
+  // ---- --ui ----
+  if (flags.get("ui")) {
+    const port = Number(flags.get("port") ?? 47610);
+    let catalog = null;
+    if (config.price_catalog) {
+      const loaded = loadPriceCatalog(resolveDataPath(config.price_catalog));
+      catalog = loaded.catalog;
+    }
+    const server = await createTelemetryServer({ store, catalog, catalogPath: config.price_catalog });
+    await new Promise((resolveListen, rejectListen) => {
+      server.listen(port, "127.0.0.1", resolveListen);
+      server.on("error", rejectListen);
+    });
+    console.log(`dsh-local-telemetry UI: http://127.0.0.1:${port}/ (localhost only; Ctrl+C to stop)`);
+    const shutdown = () => {
+      server.close();
+      if (typeof store.close === "function") store.close();
+      process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    return;
+  }
+
+  // ---- --summary ----
+  if (flags.get("summary") || flags.get("export")) {
+    const range = sinceUntilRange(flags.get("since") ?? null, flags.get("until") ?? null);
+    const filters = {
+      fromMs: range.from,
+      toMs: range.to,
+      profile: flags.get("profile") ? String(flags.get("profile")) : null,
+      model: flags.get("model") ? String(flags.get("model")) : null,
+      plugin: flags.get("plugin") ? String(flags.get("plugin")) : null,
+      event: flags.get("event") ? String(flags.get("event")) : null,
+      errorsOnly: Boolean(flags.get("errors-only")),
+    };
+    const { events, skipped } = await store.readEvents(filters);
+    let effective = events;
+    if (flags.get("slow-over-ms")) {
+      const threshold = Number(flags.get("slow-over-ms"));
+      if (!Number.isFinite(threshold) || threshold < 0) fail("invalid --slow-over-ms value");
+      const ids = slowTraceIds(events, threshold);
+      effective = events.filter((event) => ids.has(event.trace_id ?? event.span_id));
+    }
+
+    let catalog = null;
+    let catalogPath = null;
+    if (config.price_catalog) {
+      catalogPath = resolveDataPath(config.price_catalog);
+      const loaded = loadPriceCatalog(catalogPath);
+      if (!loaded.ok && loaded.errors.length > 0) {
+        for (const error of loaded.errors) console.error(`[price_catalog] ${error}`);
+      }
+      catalog = loaded.catalog;
+    }
+
+    const groupBy = flags.get("group-by") ? String(flags.get("group-by")) : null;
+    const storeStatus = await store.status();
+    const meta = {
+      store: storeStatus.store,
+      path: storeStatus.path,
+      dropped: storeStatus.counters,
+      priceCatalogPath: catalogPath,
+      command: `node bin/telemetry.mjs ${process.argv.slice(2).join(" ")}`,
+    };
+
+    if (groupBy) {
+      const rows = aggregateGrouped(effective, { groupBy, catalog, catalogPath });
+      if (!rows) fail(`invalid --group-by value: ${groupBy} (expected model|plugin|tool|profile|day)`);
+      const payload = { generated_at: new Date().toISOString(), group_by: groupBy, window: { since: flags.get("since") ?? null, until: flags.get("until") ?? null }, rows };
+      await outputResult(payload, format, flags, () => renderGroupedText(rows, groupBy), meta, "summary");
+      if (typeof store.close === "function") store.close();
+      return;
+    }
+
+    const summary = aggregateEvents(effective, { catalog, catalogPath });
+    summary.skipped = skipped;
+    await outputResult(summary, format, flags, () => renderTextSummary(summary, { dropped: meta.dropped, store: meta.store }), meta, "summary");
+    if (typeof store.close === "function") store.close();
+    return;
+  }
+
+  // ---- --trace <id> ----
+  if (flags.get("trace")) {
+    const traceId = String(flags.get("trace"));
+    const { events, skipped } = await store.readEvents({ traceId });
+    if (events.length === 0) {
+      console.error(`dsh-local-telemetry: no events found for trace ${traceId} (skipped: invalid=${skipped.invalid} schema=${skipped.schema_incompatible})`);
+      process.exit(1);
+    }
+    const view = buildTraceView(events);
+    if (format === "json") {
+      process.stdout.write(`${JSON.stringify(view, null, 2)}\n`);
+    } else {
+      process.stdout.write(`${renderTraceText(view)}\n`);
+    }
+    if (typeof store.close === "function") store.close();
+    return;
+  }
+
+  fail("no command given (use --status | --summary | --trace <id> | --export <file> | --purge --before <d> | --ui)");
+}
+
+async function outputResult(payload, format, flags, renderText, meta, kind) {
+  const exportTarget = flags.get("export");
+  let body;
+  if (format === "json") body = `${JSON.stringify(payload, null, 2)}\n`;
+  else if (format === "markdown") body = `${renderMarkdownReport(payload, meta)}\n`;
+  else body = `${renderText()}\n`;
+
+  if (exportTarget && typeof exportTarget === "string") {
+    const target = resolveDataPath(exportTarget);
+    await writeFile(target, body, "utf8");
+    console.error(`exported ${kind} to ${target} (format: ${format})`);
+  } else {
+    process.stdout.write(body);
+  }
+}
+
+main().catch((error) => {
+  console.error(`dsh-local-telemetry: ${error?.stack ?? error}`);
+  process.exit(1);
+});

package/cordis.patch.yml

@@ -0,0 +1,11 @@
+# dsh-local-telemetry — DSH bundle patch。
+#
+# 当某个 profile 在 dsh.profile.bundles 中列出本包时（dsh plugin add 即完成
+# 此事），dsh 启动时把本补丁打入配置树：插入本包插件行，加载 package.json
+# 的 main（plugin/index.js），将自带 skills/ 注册为技能根。
+#
+# 遥测是旁路能力：插件入口只注册技能根、按配置惰性创建 sink，并在关闭时
+# flush；不注册任何会改变请求语义的人设或工具。
+- insert:
+    - id: dsh-local-telemetry
+      name: dsh-local-telemetry

package/docs/configuration.md

@@ -0,0 +1,148 @@
+# dsh-telemetry 配置文档
+
+dsh-telemetry 支持通过配置文件、CLI 参数和环境变量覆盖配置。本文档描述所有可配置项、默认值和语义。
+
+## 配置文件
+
+配置文件为 JSON 格式，通过 `--config <file>` 指定：
+
+```bash
+node bin/telemetry.mjs --config telemetry.json --summary
+```
+
+## 完整配置项
+
+```json
+{
+  "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": []
+}
+```
+
+### 配置项说明
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `enabled` | boolean | true | 是否启用遥测（关闭后不记录事件，不创建日志文件） |
+| `store` | string | jsonl | 存储后端：`jsonl` 或 `sqlite`（sqlite 需要 Node ≥22.5） |
+| `path` | string | ~/.dsh/telemetry | 数据目录路径（支持 `~` 展开家目录） |
+| `sample_rate` | number | 1 | 采样率（0..1），按 trace 整体决策 |
+| `errors_always_sample` | boolean | true | 错误/取消事件是否绕过采样 |
+| `slow_request_ms` | number | 10000 | 慢请求阈值（超过则保留） |
+| `capture_metadata` | string | none | metadata 采集模式：`none`（不采集）或 `safe`（脱敏后采集） |
+| `hash_names` | boolean | false | 是否哈希化工具/插件/模型名/profile |
+| `retention_days` | number | 7 | 保留期（天数），超过此期限的数据会被清理 |
+| `max_file_mb` | number | 100 | 单文件上限（MB），超过时轮转（JSONL）或清理最旧日期（SQLite） |
+| `flush_interval_ms` | number | 1000 | 定时 flush 间隔（毫秒） |
+| `batch_size` | number | 100 | 批量写入大小（事件数） |
+| `max_queue_events` | number | 1000 | 队列上限（事件数），超过时丢弃新到事件 |
+| `price_catalog` | string | null | 版本化价格目录 JSON 文件路径（用于成本计算） |
+| `redact_rules` | array | [] | 自定义脱敏规则列表（见下方） |
+
+## 自定义脱敏规则
+
+每个规则对象包含 `name` 和 `pattern`（正则字符串）：
+
+```json
+{
+  "redact_rules": [
+    { "name": "employee_id", "pattern": "EMP-\\d+" },
+    { "name": "internal_token", "pattern": "ITK_[A-Z0-9]{32}" }
+  ]
+}
+```
+
+规则在 metadata 字符串值上按序匹配，命中后替换为 `[redacted:<name>]`。
+
+## 资源预算（计划 §7.2）
+
+以下硬预算在代码中强制执行，配置值超出时会被钳制：
+
+| 预算项 | 默认上限 | 说明 |
+| --- | --- | --- |
+| 单事件最大字节 | 64 KB | 超过的事件被丢弃并计数 |
+| 队列最大事件数 | 1000 | 超过的新事件被丢弃并计数 |
+| 最大批量大小 | 1000 | 超过时钳制到 1000 |
+| 最小 flush 间隔 | 50 ms | 超过时钳制到 50 ms |
+
+## 采样策略
+
+- 决策粒度：按 `trace_id` 整体决策（同一 trace 的所有事件同命运）。
+- 决策方法：`SHA256(salt + trace_id)` 取 hash，与 `sample_rate` 比较。
+- 保留例外：`errors_always_sample=true` 时，失败/取消事件强制保留；慢请求强制保留。
+- 元数据写入：保留的事件会写入 `sampling` 块（rate/strategy/errors_always_sample），便于解释聚合结果。
+
+## 价格目录格式
+
+用于成本计算，必须包含 `currency`、`effective_at` 和 `models` 映射：
+
+```json
+{
+  "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
+    }
+  }
+}
+```
+
+成本计算公式：
+
+```
+cost = (input_tokens / 1_000_000) * input_per_million
+     + (cached_input_tokens / 1_000_000) * cached_input_per_million
+     + (output_tokens / 1_000_000) * output_per_million
+```
+
+若模型名、usage 或价格缺失，`cost` 为 `null` 并在摘要中标记缺失原因。
+
+## 环境变量
+
+不通过环境变量配置敏感信息（密钥不属于遥测配置）。
+
+## 配置解析失败行为
+
+- 文件不存在/损坏 → 配置降级为 `{ enabled: false }`，并在 stderr 打印一次性警告。
+- 字段类型错误 → 采用安全默认值（如 `sample_rate` 回退到 1），不猜测用户意图。
+- 非法值（如 `store: "mongodb"`）→ 回退到 `jsonl`。
+
+## 例子
+
+### 仅保留错误和慢请求
+
+```json
+{
+  "enabled": true,
+  "sample_rate": 0.1,
+  "errors_always_sample": true,
+  "slow_request_ms": 5000,
+  "capture_metadata": "safe"
+}
+```
+
+### SQLite 后端 + 成本计算
+
+```json
+{
+  "store": "sqlite",
+  "path": "~/.dsh/telemetry/sqlite",
+  "price_catalog": "~/.dsh/telemetry/prices.json"
+}
+```