@lyra-ai/toolkit 0.0.1 → 0.1.0

package/QUICKSTART.md

@@ -0,0 +1,91 @@
+# @lyra-ai/toolkit Quickstart
+
+面向 AI agent 的零依赖禅道 CLI。
+
+## 安装
+
+```bash
+npm install -g @lyra-ai/toolkit
+```
+
+验证：
+
+```bash
+zentao --help
+```
+
+## 初始化
+
+```bash
+zentao init
+```
+
+按提示填入禅道地址、用户名、密码，末尾自动验证连通性。
+
+脚本 / CI 环境用非交互模式：
+
+```bash
+zentao init --url https://zentao.example.com --username myname --password mypass
+```
+
+## 开始使用
+
+```bash
+# 查看项目与产品
+zentao project list --pretty
+zentao product list --pretty
+
+# 同步产品 bug 到本地缓存（现有产品版本17.x API不支持直接筛选）
+zentao bug sync --product 财司核心7.0   # 支持名称前缀，也可用数字 ID
+
+# 查 bug（全走本地缓存，先 sync 后查）
+zentao bug list --mine --status active
+zentao bug list --title 124网银
+
+# 看详情
+zentao bug get 42 --pretty
+
+# 解决 / 指派
+zentao bug resolve 42 --resolution fixed --comment "已修复"
+zentao bug assign 42 --to zhangsan
+
+# 配置管理
+zentao config                      # 查看所有配置
+zentao config set ZENTAO_DEFAULT_PROJECT 1
+```
+
+## Bug 工作流
+
+```
+sync（拉取） → list/search（检索） → get（详情） → resolve/assign（操作）
+```
+
+- **`bug sync`** 拉产品 bug 到本地缓存（`~/.zentao-cli/cache/`）
+- **`bug list`** 本地检索，支持标题/状态/严重程度/指派/日期/排序等
+- **`bug search`** 与 `bug list` 等价（隐藏别名）
+- **`bug get`** 实时拉取单条最新详情
+
+## Agent 集成要点
+
+- 默认输出 **JSON → stdout**，错误 → stderr
+- 退出码：`0` 成功 / `2` 参数错误 / `3` 认证失败 / `4` 网络错误 / `5` API 错误
+- `--pretty` 输出 Markdown 表格（人类可读）
+- `--product` 支持 ID 或**产品名前缀**（如 `财司` → 匹配"财司存款"）
+
+```bash
+# Agent 典型用法
+zentao bug sync --product 财司
+zentao bug list --status active --mine --limit 10
+zentao bug get 42
+```
+
+## 配置参考
+
+| 变量 | 必填 | 说明 |
+|---|---|---|
+| `ZENTAO_URL` | ✅ | 禅道地址 |
+| `ZENTAO_USERNAME` | ✅ | 用户名 |
+| `ZENTAO_PASSWORD` | ✅ | 密码 |
+| `ZENTAO_DEFAULT_PROJECT` | | 默认产品/项目 ID |
+| `ZENTAO_TOKEN_TTL` | | Token 有效期（秒，默认 3600） |
+| `ZENTAO_CACHE_STALE_MS` | | 缓存过期阈值（ms，默认 3600000） |

package/README.md

@@ -1,57 +1,81 @@
 # @lyra-ai/toolkit
 
-面向 AI agent 的零依赖开发工具集。纯 JS（`.mjs`，Node 18+，无编译、无运行时依赖）。
-当前工具：**zentao**（禅道 REST v1）。预留 `log-query`、`skill-hub` 等扩展位。
+组织级研发工具集。面向研发团队的效能分析、评估与持续改进。
 
-## 工程骨架
+> **适用场景**：组织内部已部署配套的分析平台和技能中心。不适用于个人开发者独立使用。
+
+纯 JS（`.mjs`，Node 18+，无编译、无运行时依赖）。
+
+## 功能
+
+### 个人编码效能看板
+
+安装后，你的 AI 编码数据自动进入组织分析平台，生成专属的多维度效能看板。
+
+```bash
+toolkit install claudecode --registry http://your-platform:38000
 ```
-bin/zentao.mjs        # 命令入口（薄封装）→ src/zentao.mjs
-src/zentao.mjs        # zentao 工具逻辑
-src/shared/           # 预留：多工具共享底座（config/http/output/errors）
-test/*.test.mjs       # node:test，零测试依赖
-package.json          # bin 多命令声明
-.env.example          # 配置模板（占位符，无真实凭证）
+
+- 会话结束后自动同步，无需手动操作
+- 支持多项目，按项目自动分组
+- 只处理新会话，不重复
+
+### 管理命令
+
+```bash
+toolkit status                 # 安装状态 + 已同步/待同步会话数
+toolkit flush                  # 手动触发一次同步
+toolkit config                 # 查看全部配置
+toolkit config set registry <url>      # 修改平台地址
+toolkit config set project-filter <关键词>  # 按项目名关键词过滤(逗号分隔),留空=全部
+toolkit config unset project-filter         # 清除过滤,恢复全部
+toolkit uninstall              # 卸载
+toolkit uninstall --purge      # 卸载并清除本地数据
 ```
-新增工具：在 `bin/` 加入口、`src/` 加逻辑、`package.json` 的 `bin` 加一行。
+
+### --registry
+
+组织平台根地址，自动派生子系统路径：
+
+```
+http://your-host:38000
+  /ai-metrics    效能分析平台
+  /skillhub      技能中心（预留）
+```
+
+---
+
+### 禅道 CLI（zentao）
+
+禅道 REST v1 的命令行工具，支持 bug 查询/创建/解决、项目管理、配置管理。
+
+```bash
+zentao ping                              # 连通性测试
+zentao init                              # 交互式配置
+zentao project list                      # 项目列表
+zentao product list                      # 产品列表
+zentao bug list [过滤选项]                # bug 检索（本地缓存）
+zentao bug sync [--product ID] [--mine]  # 同步 bug 到本地
+zentao bug get <id>                      # bug 详情
+zentao bug create --title T              # 创建 bug
+zentao bug resolve <id> --resolution fixed  # 解决 bug
+zentao config set <key> <value>          # 配置管理
+```
+
+默认输出 JSON（stdout），错误走 stderr。退出码：0 成功 / 2 参数 / 3 认证 / 4 网络 / 5 API。
+
+---
 
 ## 安装
+
 ```bash
 npm install -g @lyra-ai/toolkit   # 发布后
 # 或本地开发：
-cd <本目录> && npm link            # 全局可用 zentao 命令
+cd <本目录> && npm link
 ```
-配置：复制 `.env.example` 为 `~/.zentao-cli/.env` 或 cwd `.env`，填 `ZENTAO_URL/USERNAME/PASSWORD`。
-或用 `zentao config set` 命令行管理配置，或 `zentao init` 向导式初始化。
-
-## 命令速查（agent 直接用）
-- `zentao ping` → `{"ok":true,"url":...}`
-- `zentao init` → 交互式向导（填 URL/用户/密码，末了验证连通性）
-- `zentao init --url <url> --username <u> --password <p> [--project <id>] [--ping]` → 非交互式（脚本/AI）
-- `zentao project list [--status active|closed|all] [--limit N] [--offset N]`
-- `zentao product list [--status active|closed|all] [--limit N] [--offset N]`
-- `zentao config` → 列出所有配置（密码脱敏为 `***`）
-- `zentao config get <key>` → 取单个值（密码需 `--raw` 才显原文）
-- `zentao config set <key> <value>` → 写入 `~/.zentao-cli/.env`
-- `zentao config unset <key>` → 删除配置项
-- `zentao config path` → 输出配置文件路径
-- `zentao bug list [--title <kw>] [--status S] [--severity 1-4] [--priority 1-4] [--assigned-to U] [--opened-by U] [--mine] [--product <ID|名称前缀>] [--project ID] [--start YYYY-MM-DD] [--end YYYY-MM-DD] [--order id_desc|...] [--limit N] [--offset N]` → 本地缓存检索（需先 sync）；`bug search` 等价别名
-- `zentao bug get <id>` → Bug 详情 JSON（live）
-- `zentao bug create --title T [--product ID --severity 1 --priority 2 --assigned-to U]`（`--project` 为兼容别名，作用域为产品）
-- `zentao bug resolve <id> --resolution fixed [--comment ...]`
-- `zentao bug assign <id> --to <user>`
-
-### 本地 bug 索引（先 sync 再 list/search，统一为缓存检索）
-- `zentao bug sync [--product ID] [--status <browseType>] [--mine]` → 一次性同步某产品 bug 到本地（默认 `unclosed`）；`--mine` 只缓存指派给我的
-- `zentao bug browse-types` → 列出 `sync --status` 的合法 browseType（`all`/`unclosed`/`assigntome`/...）
-
-> 缓存位于 `~/.zentao-cli/cache/bugs-<productId>.json`；关键判断仍走 `bug get`（live）。
-> `bug list` 的 `--product` 支持产品 ID 或**产品名前缀**（如 `--product 财司`，内部调用 products API 解析）。
-> `--mine` 一律本地按 `ZENTAO_USERNAME` 过滤，可与任意过滤叠加。
-> 缓存 >1h（`ZENTAO_CACHE_STALE_MS` 可配）时 search 会在 stderr 提示过期。
-
-默认输出 JSON（stdout），错误走 stderr。退出码：0 成功 / 2 参数配置 / 3 认证 / 4 网络 / 5 API。
 
 ## JSON 示例
+
 ```json
 {"total":1,"count":1,"bugs":[{"id":"9","title":"t","severity":"1","priority":"2","status":"active","assignedTo":"a"}]}
 ```

package/bin/toolkit.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+/**
+ * toolkit — 研发工具集 CLI 入口
+ *
+ * 用法:
+ *   toolkit install claudecode --registry <url>   安装插件
+ *   toolkit status                                 查看状态
+ *   toolkit flush                                  手动上传
+ *   toolkit uninstall [--purge]                    卸载
+ *   toolkit help                                   帮助
+ *
+ * 其他子命令(zentao 等)保留向后兼容。
+ */
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const srcDir = path.resolve(__dirname, '..', 'src');
+const args = process.argv.slice(2);
+const cmd = args[0];
+
+const HELP = `toolkit — 研发工具集
+
+命令:
+  install claudecode --registry <url>   安装 Claude Code 插件
+  status                                 查看安装状态 + 待同步会话
+  flush                                  手动触发一次同步
+  config                                 配置管理(registry / include)
+  uninstall [--purge]                    卸载插件(--purge 同时删数据)
+  help                                   显示此帮助
+
+其他:
+  zentao <subcommand>                    禅道 CLI(向后兼容)
+`;
+
+async function main() {
+  // 无参数 → help
+  if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+    console.log(HELP);
+    return;
+  }
+
+  // toolkit install claudecode --registry <url>
+  if (cmd === 'install') {
+    const target = args[1]; // claudecode
+    if (target !== 'claudecode') {
+      console.error('目前只支持: toolkit install claudecode');
+      console.error('  用法: toolkit install claudecode --registry <url>');
+      process.exit(2);
+    }
+    // 解析 --registry
+    const regIdx = args.indexOf('--registry');
+    let registry = regIdx >= 0 ? args[regIdx + 1] : null;
+    if (!registry) {
+      console.error('ERROR: 缺少 --registry <url>');
+      console.error('  用法: toolkit install claudecode --registry http://your-platform');
+      process.exit(2);
+    }
+    const { install } = await import(pathToFileURL(path.join(srcDir, 'install.mjs')).href);
+    install(registry);
+    return;
+  }
+
+  // toolkit status
+  if (cmd === 'status') {
+    const { status } = await import(pathToFileURL(path.join(srcDir, 'status.mjs')).href);
+    status();
+    return;
+  }
+
+  // toolkit flush
+  if (cmd === 'flush') {
+    const flushScript = path.join(srcDir, 'flush.mjs');
+    // 同步运行 flush(显示输出)
+    const child = spawn(process.execPath, [flushScript], {
+      stdio: 'inherit',
+      env: { ...process.env, TOOLKIT_VERBOSE: '1' },
+    });
+    child.on('exit', (code) => process.exit(code || 0));
+    return;
+  }
+
+  // toolkit uninstall [--purge]
+  if (cmd === 'uninstall') {
+    const purge = args.includes('--purge');
+    const { uninstall } = await import(pathToFileURL(path.join(srcDir, 'uninstall.mjs')).href);
+    uninstall({ purge });
+    return;
+  }
+
+  // toolkit config [get|set|unset|list]
+  if (cmd === 'config') {
+    const { configCmd } = await import(pathToFileURL(path.join(srcDir, 'config-cmd.mjs')).href);
+    configCmd(args.slice(1));
+    return;
+  }
+
+  // 未知命令 → 尝试 zentao 兼容
+  // 注意:'config' 已被 toolkit 自己处理,不在 zentao 转发列表中
+  const zentaoSubcmds = ['project', 'product', 'bug', 'ping', 'init'];
+  if (zentaoSubcmds.includes(cmd)) {
+    const mod = await import(pathToFileURL(path.join(srcDir, 'zentao.mjs')).href);
+    const zcode = mod.main();
+    if (zcode != null) process.exit(zcode);
+    return;
+  }
+
+  console.error(`未知命令: ${cmd}\n`);
+  console.log(HELP);
+  process.exit(2);
+}
+
+main();

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@lyra-ai/toolkit",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "面向 AI agent 的零依赖开发工具集",
   "type": "module",
   "bin": {
+    "toolkit": "./bin/toolkit.mjs",
     "zentao": "./bin/zentao.mjs"
   },
   "engines": { "node": ">=18" },
@@ -11,6 +12,7 @@
     "bin",
     "src",
     "README.md",
+    "QUICKSTART.md",
     "LICENSE",
     ".env.example"
   ],

package/src/config-cmd.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+/**
+ * config-cmd.mjs — `toolkit config [get|set|unset|list]`
+ * 管理 ~/.toolkit/config.json(registry / project-filter)。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const TOOLKIT_DIR = path.join(os.homedir(), '.toolkit');
+const CONFIG_PATH = path.join(TOOLKIT_DIR, 'config.json');
+
+const HELP = `toolkit config — 配置管理
+
+用法:
+  toolkit config                                  显示全部配置
+  toolkit config get <key>                        查看单个配置项
+  toolkit config set <key> <value>                设置配置项
+  toolkit config unset <key>                      删除配置项
+
+可用配置项:
+  registry        平台根地址(如 http://your-host:38000)
+  project-filter  项目过滤关键词,逗号分隔(如 my-project,backend);留空 = 全部上传
+`;
+
+function load() {
+  try { return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8')); }
+  catch { console.error('配置文件不存在。先运行: toolkit install claudecode --registry <url>'); process.exit(1); }
+}
+
+function save(config) {
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
+}
+
+export function configCmd(args) {
+  const sub = args[0];
+
+  if (!sub || sub === 'list' || sub === 'help' || sub === '--help') {
+    const config = load();
+    const pf = config['project-filter'];
+    console.log('Toolkit 配置 (' + CONFIG_PATH + ')');
+    console.log('════════════════════════════════════════');
+    console.log(`  registry:        ${config.registry || '(未设置)'}`);
+    console.log(`  project-filter:  ${pf && pf.length ? pf.join(', ') : '(空 = 全部上传)'}`);
+    console.log(`  uid:             ${config.uid?.slice(0, 12)}...`);
+    console.log('════════════════════════════════════════');
+    return;
+  }
+
+  if (sub === 'get') {
+    const key = args[1];
+    if (!key) { console.error('用法: toolkit config get <key>'); process.exit(2); }
+    const config = load();
+    if (key === 'project-filter') {
+      const pf = config['project-filter'];
+      console.log(pf && pf.length ? pf.join(', ') : '');
+    } else {
+      console.log(config[key] ?? '');
+    }
+    return;
+  }
+
+  if (sub === 'set') {
+    const key = args[1];
+    const value = args.slice(2).join(' ');
+    if (!key || !value) { console.error('用法: toolkit config set <key> <value>'); process.exit(2); }
+    const config = load();
+    if (key === 'project-filter') {
+      config['project-filter'] = value.split(',').map(s => s.trim()).filter(Boolean);
+    } else if (key === 'registry') {
+      config.registry = value.replace(/\/$/, '');
+    } else {
+      config[key] = value;
+    }
+    save(config);
+    const display = key === 'project-filter'
+      ? (config['project-filter'].join(', ') || '(空)')
+      : config[key];
+    console.log(`✅ ${key} = ${display}`);
+    return;
+  }
+
+  if (sub === 'unset') {
+    const key = args[1];
+    if (!key) { console.error('用法: toolkit config unset <key>'); process.exit(2); }
+    const config = load();
+    if (key === 'project-filter') {
+      config['project-filter'] = [];
+    } else {
+      delete config[key];
+    }
+    save(config);
+    console.log(`✅ ${key} 已清除`);
+    return;
+  }
+
+  console.error(`未知子命令: ${sub}\n`);
+  console.log(HELP);
+  process.exit(2);
+}

package/src/flush.mjs

@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+/**
+ * flush.mjs — 扫描 Claude Code 会话 JSONL → 零依赖 zip → POST 平台。
+ * 被 hook.mjs(SessionEnd)detached spawn 调用,或 `toolkit flush` 手动调用。
+ * 自包含:零依赖,只用 Node 内置模块。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { deflateRawSync } from 'node:zlib';
+import { randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const HOME = os.homedir();
+const TOOLKIT_DIR = path.join(HOME, '.toolkit');
+const CONFIG_PATH = path.join(TOOLKIT_DIR, 'config.json');
+const UPLOADED_PATH = path.join(TOOLKIT_DIR, 'uploaded.json');
+const LOG_DIR = path.join(TOOLKIT_DIR, 'logs');
+const CLAUDE_PROJECTS = path.join(HOME, '.claude', 'projects');
+
+// ── 日志 ──────────────────────────────────────────────
+function log(...args) {
+  const ts = new Date().toISOString();
+  const line = `[${ts}] ${args.join(' ')}\n`;
+  try {
+    fs.mkdirSync(LOG_DIR, { recursive: true });
+    fs.appendFileSync(path.join(LOG_DIR, `${ts.slice(0, 10)}.log`), line);
+  } catch {}
+  if (process.env.TOOLKIT_VERBOSE) process.stderr.write(line);
+}
+
+// ── 读配置 ────────────────────────────────────────────
+function loadConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
+  } catch {
+    log('ERROR: config.json not found. Run `toolkit install` first.');
+    process.exit(1);
+  }
+}
+
+function loadUploaded() {
+  try {
+    return JSON.parse(fs.readFileSync(UPLOADED_PATH, 'utf-8'));
+  } catch {
+    return { uploaded_sids: [], last_flush: null };
+  }
+}
+
+function saveUploaded(state) {
+  state.last_flush = new Date().toISOString();
+  // 只保留最近 500 个 sid(防膨胀)
+  if (state.uploaded_sids.length > 500) {
+    state.uploaded_sids = state.uploaded_sids.slice(-500);
+  }
+  try {
+    fs.writeFileSync(UPLOADED_PATH, JSON.stringify(state, null, 2));
+  } catch (e) {
+    log('WARN: cannot save uploaded.json:', e.message);
+  }
+}
+
+// ── 扫描新会话 ────────────────────────────────────────
+function scanNewSessions(uploadedSet, includeKeywords) {
+  const found = [];
+  if (!fs.existsSync(CLAUDE_PROJECTS)) return found;
+  for (const projDir of fs.readdirSync(CLAUDE_PROJECTS)) {
+    // project-filter:配了关键词时,项目目录名必须命中至少一个(子串,大小写不敏感)
+    if (includeKeywords && includeKeywords.length > 0) {
+      const lower = projDir.toLowerCase();
+      if (!includeKeywords.some(kw => lower.includes(kw.toLowerCase()))) continue;
+    }
+    const projPath = path.join(CLAUDE_PROJECTS, projDir);
+    let st;
+    try { st = fs.statSync(projPath); } catch { continue; }
+    if (!st.isDirectory()) continue;
+    for (const file of fs.readdirSync(projPath)) {
+      if (!file.endsWith('.jsonl')) continue;
+      const sid = file.slice(0, -6); // 去掉 .jsonl
+      if (uploadedSet.has(sid)) continue;
+      const fp = path.join(projPath, file);
+      // 跳过空文件(<100 字节,可能是刚创建的)
+      try { if (fs.statSync(fp).size < 100) continue; } catch { continue; }
+      found.push({ sid, path: fp, project: projDir, name: file });
+    }
+  }
+  return found;
+}
+
+// ── 零依赖 zip ────────────────────────────────────────
+// CRC32 查表法
+const CRC_TABLE = (() => {
+  const t = new Uint32Array(256);
+  for (let i = 0; i < 256; i++) {
+    let c = i;
+    for (let j = 0; j < 8; j++) c = (c & 1) ? (0xEDB88320 ^ (c >>> 1)) : (c >>> 1);
+    t[i] = c;
+  }
+  return t;
+})();
+
+function crc32(buf) {
+  let crc = 0xFFFFFFFF;
+  for (let i = 0; i < buf.length; i++) {
+    crc = CRC_TABLE[(crc ^ buf[i]) & 0xFF] ^ (crc >>> 8);
+  }
+  return (crc ^ 0xFFFFFFFF) >>> 0;
+}
+
+function createZip(files) {
+  // files: [{ name: string, data: Buffer }]
+  const localParts = [];
+  const centralParts = [];
+  let offset = 0;
+
+  for (const file of files) {
+    const data = Buffer.isBuffer(file.data) ? file.data : Buffer.from(file.data);
+    const compressed = deflateRawSync(data);
+    const crc = crc32(data);
+    const nameBuf = Buffer.from(file.name);
+
+    // Local file header (30 bytes)
+    const lh = Buffer.alloc(30);
+    lh.writeUInt32LE(0x04034b50, 0);
+    lh.writeUInt16LE(20, 4);           // version needed
+    lh.writeUInt16LE(0, 6);            // flags
+    lh.writeUInt16LE(8, 8);            // compression: deflate
+    lh.writeUInt16LE(0, 10);           // mod time
+    lh.writeUInt16LE(0x0021, 12);      // mod date (1980-01-01 safe)
+    lh.writeUInt32LE(crc, 14);
+    lh.writeUInt32LE(compressed.length, 18);
+    lh.writeUInt32LE(data.length, 22);
+    lh.writeUInt16LE(nameBuf.length, 26);
+    lh.writeUInt16LE(0, 28);           // extra length
+
+    const localPart = Buffer.concat([lh, nameBuf, compressed]);
+    localParts.push(localPart);
+
+    // Central directory header (46 bytes)
+    const ch = Buffer.alloc(46);
+    ch.writeUInt32LE(0x02014b50, 0);
+    ch.writeUInt16LE(20, 4);
+    ch.writeUInt16LE(20, 6);
+    ch.writeUInt16LE(0, 8);
+    ch.writeUInt16LE(8, 10);
+    ch.writeUInt16LE(0, 12);
+    ch.writeUInt16LE(0x0021, 14);
+    ch.writeUInt32LE(crc, 16);
+    ch.writeUInt32LE(compressed.length, 20);
+    ch.writeUInt32LE(data.length, 24);
+    ch.writeUInt16LE(nameBuf.length, 28);
+    ch.writeUInt16LE(0, 30);           // extra
+    ch.writeUInt16LE(0, 32);           // comment
+    ch.writeUInt16LE(0, 34);           // disk
+    ch.writeUInt16LE(0, 36);           // internal attrs
+    ch.writeUInt32LE(0, 38);           // external attrs
+    ch.writeUInt32LE(offset, 42);      // local header offset
+    centralParts.push(Buffer.concat([ch, nameBuf]));
+
+    offset += localPart.length;
+  }
+
+  // End of central directory (22 bytes)
+  const centralBuf = Buffer.concat(centralParts);
+  const eocd = Buffer.alloc(22);
+  eocd.writeUInt32LE(0x06054b50, 0);
+  eocd.writeUInt16LE(0, 4);
+  eocd.writeUInt16LE(0, 6);
+  eocd.writeUInt16LE(files.length, 8);
+  eocd.writeUInt16LE(files.length, 10);
+  eocd.writeUInt32LE(centralBuf.length, 12);
+  eocd.writeUInt32LE(offset, 16);       // central dir offset
+  eocd.writeUInt16LE(0, 20);
+
+  return Buffer.concat([...localParts, centralBuf, eocd]);
+}
+
+// ── HTTP POST(带重试)────────────────────────────────
+async function postZip(url, zipBuf, uid) {
+  const delays = [2000, 4000, 8000]; // 重试间隔
+  for (let attempt = 0; attempt <= delays.length; attempt++) {
+    try {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), 30000);
+      const res = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/zip', 'X-Uid': uid },
+        body: zipBuf,
+        signal: controller.signal,
+      });
+      clearTimeout(timeout);
+      if (res.ok) {
+        const j = await res.json().catch(() => ({}));
+        return j;
+      }
+      if (res.status >= 400 && res.status < 500 && res.status !== 429) {
+        throw new Error(`HTTP ${res.status}: ${await res.text().catch(() => '')}`);
+      }
+      throw new Error(`HTTP ${res.status}`);
+    } catch (e) {
+      if (attempt < delays.length) {
+        const jitter = (Math.random() - 0.5) * delays[attempt] * 0.5;
+        const wait = Math.max(1000, delays[attempt] + jitter);
+        log(`attempt ${attempt + 1} failed: ${e.message}, retry in ${Math.round(wait)}ms`);
+        await new Promise(r => setTimeout(r, wait));
+      } else {
+        throw e;
+      }
+    }
+  }
+}
+
+// ── 主流程 ────────────────────────────────────────────
+async function main() {
+  const config = loadConfig();
+  const { registry, uid } = config;
+  const metricsBase = `${registry.replace(/\/$/, '')}${config.contexts?.metrics || '/ai-metrics'}`;
+  const uploadUrl = `${metricsBase}/api/upload`;
+
+  log(`flush start: registry=${registry} uid=${uid.slice(0, 8)}...`);
+
+  const uploaded = loadUploaded();
+  const uploadedSet = new Set(uploaded.uploaded_sids);
+  const includeKeywords = config['project-filter'] || [];
+  const newSessions = scanNewSessions(uploadedSet, includeKeywords);
+
+  if (newSessions.length === 0) {
+    log('no new sessions to upload');
+    saveUploaded(uploaded);
+    return;
+  }
+
+  log(`found ${newSessions.length} new session(s)`);
+
+  // 按项目分组,每组一次上传(平台按项目分)
+  const byProject = new Map();
+  for (const s of newSessions) {
+    if (!byProject.has(s.project)) byProject.set(s.project, []);
+    byProject.get(s.project).push(s);
+  }
+
+  let totalUploaded = 0;
+  for (const [project, sessions] of byProject) {
+    log(`uploading project=${project}: ${sessions.length} session(s)`);
+
+    // 读文件 + 创建 zip
+    const zipFiles = [];
+    for (const s of sessions) {
+      try {
+        const data = fs.readFileSync(s.path);
+        zipFiles.push({ name: `${project}/${s.name}`, data });
+      } catch (e) {
+        log(`WARN: cannot read ${s.path}: ${e.message}`);
+      }
+    }
+    if (zipFiles.length === 0) continue;
+
+    const zipBuf = createZip(zipFiles);
+    log(`zip created: ${zipFiles.length} files, ${Math.round(zipBuf.length / 1024)}KB`);
+
+    // 上传
+    try {
+      const result = await postZip(uploadUrl, zipBuf, uid);
+      log(`upload OK: dataset=${result.dataset_id}, sessions=${result.files || '?'}`);
+      for (const s of sessions) {
+        uploadedSet.add(s.sid);
+        uploaded.uploaded_sids = [...uploadedSet];
+      }
+      totalUploaded += sessions.length;
+    } catch (e) {
+      log(`upload FAILED for ${project}: ${e.message}`);
+      // 不更新 uploaded — 下次重试
+    }
+  }
+
+  saveUploaded(uploaded);
+  log(`flush done: ${totalUploaded}/${newSessions.length} uploaded`);
+}
+
+main().catch(e => {
+  log(`FATAL: ${e.message}`);
+  process.exit(1);
+});

package/src/hook.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * hook.mjs — Claude Code SessionEnd hook 插件入口。
+ * 职责:detached spawn flush.mjs → exit(0)。
+ * 不读 stdin、不开网、不写文件。<10ms,远在 1.5s 超时内。
+ *
+ * Claude Code 通过 hooks.json (exec form) 调用:
+ *   command: "node"
+ *   args: ["${CLAUDE_PLUGIN_ROOT}/hook.mjs"]
+ *
+ * ${CLAUDE_PLUGIN_ROOT} 被 Claude Code 替换为插件目录路径,
+ * 同时 export 为环境变量 process.env.CLAUDE_PLUGIN_ROOT。
+ */
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const flushScript = path.join(__dirname, 'flush.mjs');
+
+try {
+  spawn(process.execPath, [flushScript], {
+    detached: true,
+    stdio: 'ignore',
+    env: { ...process.env, TOOLKIT_AUTO: '1' },
+  }).unref();
+} catch {
+  // 永不抛错:flusher 没起来,下次 SessionEnd 或手动 toolkit flush 补传
+}
+
+process.exit(0);

package/src/install.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * install.mjs — `toolkit install claudecode --registry <url>`
+ * 创建 Claude Code 插件(~/.claude/plugins/toolkit/)+ 配置(~/.toolkit/)+ 启用。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const HOME = os.homedir();
+const PLUGIN_DIR = path.join(HOME, '.claude', 'plugins', 'toolkit');
+const TOOLKIT_DIR = path.join(HOME, '.toolkit');
+const SETTINGS_PATH = path.join(HOME, '.claude', 'settings.json');
+const PLUGIN_KEY = 'toolkit@local';
+
+const PLUGIN_JSON = {
+  name: 'toolkit',
+  version: '0.1.0',
+  description: '研发工具集 — 会话度量、技能同步等',
+};
+
+const HOOKS_JSON = {
+  hooks: {
+    SessionEnd: [{
+      hooks: [{
+        type: 'command',
+        command: 'node',
+        args: ['${CLAUDE_PLUGIN_ROOT}/hook.mjs'],
+        async: false,
+      }],
+    }],
+  },
+};
+
+export function install(registry, opts = {}) {
+  // 1. 检测 Claude Code
+  const claudeDir = path.join(HOME, '.claude');
+  if (!fs.existsSync(claudeDir)) {
+    console.error('ERROR: ~/.claude not found. Is Claude Code installed?');
+    process.exit(1);
+  }
+
+  // 2. 创建插件目录
+  fs.mkdirSync(path.join(PLUGIN_DIR, '.claude-plugin'), { recursive: true });
+  fs.mkdirSync(path.join(PLUGIN_DIR, 'hooks'), { recursive: true });
+
+  // 3. 写插件文件
+  fs.writeFileSync(
+    path.join(PLUGIN_DIR, '.claude-plugin', 'plugin.json'),
+    JSON.stringify(PLUGIN_JSON, null, 2)
+  );
+  fs.writeFileSync(
+    path.join(PLUGIN_DIR, 'hooks', 'hooks.json'),
+    JSON.stringify(HOOKS_JSON, null, 2)
+  );
+
+  // 4. 复制 hook.mjs + flush.mjs 到插件目录(自包含)
+  const srcDir = __dirname;
+  fs.copyFileSync(path.join(srcDir, 'hook.mjs'), path.join(PLUGIN_DIR, 'hook.mjs'));
+  fs.copyFileSync(path.join(srcDir, 'flush.mjs'), path.join(PLUGIN_DIR, 'flush.mjs'));
+
+  // 5. 创建 ~/.toolkit/ 配置
+  fs.mkdirSync(TOOLKIT_DIR, { recursive: true });
+  fs.mkdirSync(path.join(TOOLKIT_DIR, 'logs'), { recursive: true });
+
+  // 读取已有 config(保留 uid)或新建
+  const configPath = path.join(TOOLKIT_DIR, 'config.json');
+  let config = {};
+  try { config = JSON.parse(fs.readFileSync(configPath, 'utf-8')); } catch {}
+  if (!config.uid) config.uid = randomUUID();
+  config.registry = registry.replace(/\/$/, '');
+  config.contexts = { metrics: '/ai-metrics', skills: '/skillhub' };
+  config.installed_at = new Date().toISOString();
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+
+  // 6. uploaded.json 初始化(如果不存在)
+  const uploadedPath = path.join(TOOLKIT_DIR, 'uploaded.json');
+  if (!fs.existsSync(uploadedPath)) {
+    fs.writeFileSync(uploadedPath, JSON.stringify({ uploaded_sids: [], last_flush: null }, null, 2));
+  }
+
+  // 7. 启用插件(settings.json)
+  let settings = {};
+  try { settings = JSON.parse(fs.readFileSync(SETTINGS_PATH, 'utf-8')); } catch {}
+  if (!settings.enabledPlugins) settings.enabledPlugins = {};
+  settings.enabledPlugins[PLUGIN_KEY] = true;
+  fs.writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2));
+
+  // 8. 输出
+  console.log('✅ 安装完成。\n');
+  console.log(`   插件目录:  ${PLUGIN_DIR}`);
+  console.log(`   配置文件:  ${configPath}`);
+  console.log(`   身份 UID:  ${config.uid.slice(0, 12)}...`);
+  console.log(`   平台地址:  ${config.registry}${config.contexts.metrics}/`);
+  console.log(`\n   Claude Code 会话结束后,数据自动上报到上述地址。`);
+  console.log(`   手动触发:  toolkit flush`);
+  console.log(`   查看状态:  toolkit status`);
+}

package/src/status.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * status.mjs — `toolkit status`
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const HOME = os.homedir();
+const PLUGIN_DIR = path.join(HOME, '.claude', 'plugins', 'toolkit');
+const TOOLKIT_DIR = path.join(HOME, '.toolkit');
+
+export function status() {
+  const pluginExists = fs.existsSync(path.join(PLUGIN_DIR, '.claude-plugin', 'plugin.json'));
+  const configExists = fs.existsSync(path.join(TOOLKIT_DIR, 'config.json'));
+
+  console.log('Toolkit Status');
+  console.log('════════════════════════════════════════');
+
+  if (!pluginExists && !configExists) {
+    console.log('  ❌ 未安装。运行: toolkit install claudecode --registry <url>');
+    return;
+  }
+
+  // 插件状态
+  console.log(`  插件:        ${pluginExists ? '✅ 已安装' : '❌ 缺失'}`);
+  if (pluginExists) {
+    const pj = JSON.parse(fs.readFileSync(path.join(PLUGIN_DIR, '.claude-plugin', 'plugin.json'), 'utf-8'));
+    console.log(`  版本:        ${pj.version}`);
+  }
+
+  // 配置
+  if (configExists) {
+    const config = JSON.parse(fs.readFileSync(path.join(TOOLKIT_DIR, 'config.json'), 'utf-8'));
+    console.log(`  平台地址:    ${config.registry}${config.contexts?.metrics || '/ai-metrics'}/`);
+    console.log(`  身份 UID:    ${config.uid?.slice(0, 12)}...`);
+  }
+
+  // 上传状态
+  const uploadedPath = path.join(TOOLKIT_DIR, 'uploaded.json');
+  try {
+    const up = JSON.parse(fs.readFileSync(uploadedPath, 'utf-8'));
+    console.log(`  已传会话:    ${up.uploaded_sids?.length || 0} 个`);
+    console.log(`  上次上传:    ${up.last_flush || '从未'}`);
+  } catch {
+    console.log('  上传状态:    未初始化');
+  }
+
+  // 待传会话计数
+  const projectsDir = path.join(HOME, '.claude', 'projects');
+  let pending = 0;
+  if (fs.existsSync(projectsDir) && configExists) {
+    const up = JSON.parse(fs.readFileSync(uploadedPath, 'utf-8'));
+    const uploadedSet = new Set(up.uploaded_sids || []);
+    for (const projDir of fs.readdirSync(projectsDir)) {
+      const pp = path.join(projectsDir, projDir);
+      try {
+        if (!fs.statSync(pp).isDirectory()) continue;
+        for (const f of fs.readdirSync(pp)) {
+          if (f.endsWith('.jsonl') && !uploadedSet.has(f.slice(0, -6))) pending++;
+        }
+      } catch {}
+    }
+  }
+  console.log(`  待传会话:    ${pending} 个`);
+  console.log('════════════════════════════════════════');
+}

package/src/uninstall.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+/**
+ * uninstall.mjs — `toolkit uninstall`
+ * 删插件目录 + 移除 settings.json enabledPlugins 条目 + 可选保留 ~/.toolkit/ 数据。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const HOME = os.homedir();
+const PLUGIN_DIR = path.join(HOME, '.claude', 'plugins', 'toolkit');
+const SETTINGS_PATH = path.join(HOME, '.claude', 'settings.json');
+const PLUGIN_KEY = 'toolkit@local';
+
+function rmrf(dir) {
+  if (!fs.existsSync(dir)) return;
+  for (const entry of fs.readdirSync(dir)) {
+    const p = path.join(dir, entry);
+    try {
+      if (fs.statSync(p).isDirectory()) rmrf(p);
+      else fs.unlinkSync(p);
+    } catch {}
+  }
+  try { fs.rmdirSync(dir); } catch {}
+}
+
+export function uninstall(opts = {}) {
+  // 1. 删插件目录
+  rmrf(PLUGIN_DIR);
+  console.log('✅ 插件目录已删除');
+
+  // 2. 移除 settings.json enabledPlugins
+  try {
+    const settings = JSON.parse(fs.readFileSync(SETTINGS_PATH, 'utf-8'));
+    if (settings.enabledPlugins?.[PLUGIN_KEY] !== undefined) {
+      delete settings.enabledPlugins[PLUGIN_KEY];
+      fs.writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2));
+      console.log('✅ settings.json enabledPlugins 已移除');
+    }
+  } catch {}
+
+  // 3. 数据(~/.toolkit/)
+  if (opts.purge) {
+    rmrf(path.join(HOME, '.toolkit'));
+    console.log('✅ ~/.toolkit/ 数据已清除');
+  } else {
+    console.log('ℹ️  ~/.toolkit/ 数据保留(含 UID + 上传记录)。');
+    console.log('   彻底清除: toolkit uninstall --purge');
+  }
+}