left-skills 0.1.9 → 0.3.0

package/README.md

@@ -2,89 +2,100 @@
 
 # left-skills
 
-**shift-left for skills** — 在 skill 投入使用前就度量它用没用,而不是等用户撞 bug。
+**shift-left for skills** — measure how your AI skills are used before users hit bugs.
 
 [![npm version](https://img.shields.io/npm/v/left-skills)](https://www.npmjs.com/package/left-skills)
 [![license](https://img.shields.io/npm/l/left-skills)](./LICENSE)
 [![stars](https://img.shields.io/github/stars/cuikexi/left-skills)](https://github.com/cuikexi/left-skills)
 
+[中文](./README.zh.md)
+
 </div>
 
-## 命名由来
+## Why "left-skills"?
 
-`left-skills` = **shift-left for skills**。把质量/度量左移到"投入使用前"——你写完 skill,先看它用没用、写得好不好,而不是等用户撞 bug 才发现。
+`left-skills` = **shift-left for skills**. Move quality/measurement "left" — to *before* a skill is put into use — instead of waiting for users to hit bugs. Know which skills never get called, fix them early.
 
 ## How It Works
 
 ```
-打 /skill 或 AI 调 skill
-    │ Claude Code hook 触发
+type /skill or AI invokes a skill
+    │ Claude Code hook fires
     ▼
-left-skills hook(三数据源)
-  - UserPromptExpansion.command_name   (手动 /slash)
-  - PreToolUse.tool_input.skill        (AI 调 Skill 工具)
-  - UserPromptSubmit.prompt            (自然语言提及)
-    │ 解析 payload,取 skill 名
+left-skills hook (3 sources)
+  - UserPromptExpansion.command_name   (manual /slash)
+  - PreToolUse.tool_input.skill        (AI invokes Skill tool)
+  - UserPromptSubmit.prompt            (natural-language mention)
+    │ parse payload, extract skill name
     ▼
-~/.left-skills/usage.json (append 记录)
+~/.left-skills/usage.json (append records)
     │
     ▼
-left-skills usage 报告(手动/AI/提及 分开 + 从未调用 ⚠)
+left-skills usage report (manual / AI / mention split + never-called ⚠)
 ```
 
 ## Installation
 
 ```bash
 npm i -g left-skills
-left-skills install   # 输出 hook 片段,复制进 ~/.claude/settings.json 的 hooks 字段
+left-skills install --write   # auto-config hooks into ~/.claude/settings.json (merge + backup .bak)
 ```
 
-详见 [docs/install.md](docs/install.md)。
+> Don't want auto-write? `left-skills install` prints a snippet to add manually. See [docs/install.md](docs/install.md).
+
+## Uninstall
+
+```bash
+left-skills uninstall           # remove hooks (backup .bak)
+npm uninstall -g left-skills    # remove binary
+```
 
 ## Quick Start
 
 ```bash
-left-skills usage            # 人看报告
-left-skills usage --json     # AI 用(JSON)
-left-skills usage --since 7  # 近 7 天
+left-skills usage            # human-readable report
+left-skills usage --json     # for AI (JSON)
+left-skills usage --since 7  # last 7 days
+left-skills doctor           # diagnose install (✓/✗ + fix)
+left-skills report --markdown > report.md  # export report
 ```
 
-报告示例:
+Example:
 
 ```
-skill 调用报告(14 个 skill)
+skill usage report (14 skills)
 ────────────────────────────────────
-  3  grill-me            (手动1 + AI1 + 提及1,最近 今天)
-  0  gitlab-ci-generate  ⚠ 从未调用
+  3  grill-me            (manual1 + AI1 + mention1, last today)
+  0  gitlab-ci-generate  ⚠ never called
 ```
 
 ## Highlights
 
-- **三数据源 hook 埋点**:手动 /slash、AI 调 Skill、自然语言提及,分开记
-- **诚实报告**:手动/AI/提及 分开标(不混"调用次数"),从未调用 ⚠
-- **给 AI 用**:`--json` 输出,AI 能解析决策(改/删 skill)
-- **单文件 bundle**:TS 打包单 `.js`,随 skill 生态分发
+- **3-source hook tracking**: manual `/slash`, AI Skill-tool invoke, natural-language mention — tracked separately
+- **Honest reporting**: manual/AI/mention split (no fake "call count"), never-called ⚠
+- **For AI use**: `--json` output, AI can parse to decide (improve/delete skill)
+- **Single-file bundle**: TS bundled to one `.js`, ships via skill ecosystem
 
 ## Limitations
 
-- 只 **Claude Code**(Cursor / Codex 后扩)
-- **AI 纯 progressive disclosure 自主激活**(不走 Skill 工具)抓不到——只手动 /slash + AI 调 Skill 工具 + 自然语言提及
-- 需装 hook 配置(用户加 settings.json)
-- MVP 期(早期,API 可能变)
+- **Claude Code only** (Cursor / Codex later)
+- **AI pure progressive-disclosure auto-activation** (not via Skill tool) can't be tracked — only manual `/slash` + AI Skill-tool + natural-language mention
+- Requires hook config (user adds to settings.json)
+- MVP stage (early, API may change)
 
 ## Contributing
 
-PR 欢迎。开发:
+PRs welcome. Dev setup:
 
 ```bash
 git clone https://github.com/cuikexi/left-skills
 cd left-skills
 npm install
 npm run build
-npm link   # 本地 left-skills 进 PATH
+npm link   # local left-skills into PATH
 ```
 
-提 PR 前 `npm run build` 确保 dist 最新。理念 / roadmap 见 [docs/roadmap.md](docs/roadmap.md)。
+Run `npm run build` before PR to ensure dist is fresh. Philosophy / roadmap see [docs/roadmap.md](docs/roadmap.md).
 
 ## Star History
 

package/README.zh.md

@@ -0,0 +1,106 @@
+<div align="center">
+
+# left-skills
+
+**shift-left for skills** — 在 skill 投入使用前就度量它用没用,而不是等用户撞 bug。
+
+[![npm version](https://img.shields.io/npm/v/left-skills)](https://www.npmjs.com/package/left-skills)
+[![license](https://img.shields.io/npm/l/left-skills)](./LICENSE)
+[![stars](https://img.shields.io/github/stars/cuikexi/left-skills)](https://github.com/cuikexi/left-skills)
+
+[English](./README.md)
+
+</div>
+
+## 命名由来
+
+`left-skills` = **shift-left for skills**。把质量/度量左移到"投入使用前"——你写完 skill,先看它用没用、写得好不好,而不是等用户撞 bug 才发现。
+
+## How It Works
+
+```
+打 /skill 或 AI 调 skill
+    │ Claude Code hook 触发
+    ▼
+left-skills hook(三数据源)
+  - UserPromptExpansion.command_name   (手动 /slash)
+  - PreToolUse.tool_input.skill        (AI 调 Skill 工具)
+  - UserPromptSubmit.prompt            (自然语言提及)
+    │ 解析 payload,取 skill 名
+    ▼
+~/.left-skills/usage.json (append 记录)
+    │
+    ▼
+left-skills usage 报告(手动/AI/提及 分开 + 从未调用 ⚠)
+```
+
+## Installation
+
+```bash
+npm i -g left-skills
+left-skills install --write   # 自动配 hook 到 ~/.claude/settings.json(合并去重 + 备份 .bak)
+```
+
+> 不想自动写?`left-skills install` 输出片段手动加。详见 [docs/install.md](docs/install.md)。
+
+## 卸载
+
+```bash
+left-skills uninstall           # 删 hook(备份 .bak)
+npm uninstall -g left-skills    # 卸 binary
+```
+
+## Quick Start
+
+```bash
+left-skills usage            # 人看报告
+left-skills usage --json     # AI 用(JSON)
+left-skills usage --since 7  # 近 7 天
+left-skills doctor           # 诊断安装(✓/✗ + 建议)
+left-skills report --markdown > report.md  # 导出报告
+```
+
+报告示例:
+
+```
+skill 调用报告(14 个 skill)
+────────────────────────────────────
+  3  grill-me            (手动1 + AI1 + 提及1,最近 今天)
+  0  gitlab-ci-generate  ⚠ 从未调用
+```
+
+## Highlights
+
+- **三数据源 hook 埋点**:手动 `/slash`、AI 调 Skill、自然语言提及,分开记
+- **诚实报告**:手动/AI/提及 分开标(不混"调用次数"),从未调用 ⚠
+- **给 AI 用**:`--json` 输出,AI 能解析决策(改/删 skill)
+- **单文件 bundle**:TS 打包单 `.js`,随 skill 生态分发
+
+## Limitations
+
+- 只 **Claude Code**(Cursor / Codex 后扩)
+- **AI 纯 progressive disclosure 自主激活**(不走 Skill 工具)抓不到——只手动 `/slash` + AI 调 Skill 工具 + 自然语言提及
+- 需装 hook 配置(用户加 settings.json)
+- MVP 期(早期,API 可能变)
+
+## Contributing
+
+PR 欢迎。开发:
+
+```bash
+git clone https://github.com/cuikexi/left-skills
+cd left-skills
+npm install
+npm run build
+npm link   # 本地 left-skills 进 PATH
+```
+
+提 PR 前 `npm run build` 确保 dist 最新。理念 / roadmap 见 [docs/roadmap.md](docs/roadmap.md)。
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=cuikexi/left-skills&type=Date)](https://star-history.com/#cuikexi/left-skills&date)
+
+## License
+
+[MIT](./LICENSE)

package/dist/cli.js

@@ -3201,6 +3201,22 @@ function relativeTime(iso) {
   if (days === 1) return "1 \u5929\u524D";
   return `${days} \u5929\u524D`;
 }
+function formatMarkdown(report) {
+  const lines = [];
+  lines.push(`# left-skills usage report`);
+  lines.push("");
+  lines.push(`Generated: ${report.generated_at}  |  Skills: ${report.skills.length}`);
+  lines.push("");
+  lines.push("| skill | manual | AI | mention | total | last |");
+  lines.push("|---|---|---|---|---|---|");
+  for (const s of report.skills) {
+    const total = s.manual + s.ai + s.mention;
+    const last = s.last_used ? relativeTime(s.last_used) : "-";
+    const mark = total === 0 ? " \u26A0" : "";
+    lines.push(`| ${s.name}${mark} | ${s.manual} | ${s.ai} | ${s.mention} | ${total} | ${last} |`);
+  }
+  return lines.join("\n");
+}
 
 // src/install.ts
 var import_node_fs3 = require("fs");
@@ -3248,14 +3264,88 @@ function writeHooksToSettings(settingsPath) {
   }
   (0, import_node_fs3.writeFileSync)(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
 }
+function removeHooksFromSettings(settingsPath) {
+  if (!(0, import_node_fs3.existsSync)(settingsPath)) return;
+  (0, import_node_fs3.copyFileSync)(settingsPath, settingsPath + ".bak");
+  let settings = {};
+  try {
+    settings = JSON.parse((0, import_node_fs3.readFileSync)(settingsPath, "utf-8"));
+  } catch {
+    return;
+  }
+  if (!settings.hooks) return;
+  for (const event of Object.keys(settings.hooks)) {
+    settings.hooks[event] = settings.hooks[event].filter((entry) => {
+      entry.hooks = (entry.hooks || []).filter((h) => !(h.command && h.command.includes("left-skills")));
+      return entry.hooks.length > 0;
+    });
+    if (settings.hooks[event].length === 0) delete settings.hooks[event];
+  }
+  if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+  (0, import_node_fs3.writeFileSync)(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+}
 function globalSettingsPath() {
   return (0, import_node_path3.join)((0, import_node_os3.homedir)(), ".claude", "settings.json");
 }
 
+// src/doctor.ts
+var import_node_fs4 = require("fs");
+var import_node_os4 = require("os");
+var import_node_path4 = require("path");
+var import_node_child_process = require("child_process");
+function checkBinary() {
+  try {
+    const path = (0, import_node_child_process.execSync)("which left-skills", { encoding: "utf-8" }).trim();
+    return { name: "binary in PATH", ok: true, detail: path };
+  } catch {
+    return { name: "binary in PATH", ok: false, detail: "left-skills \u547D\u4EE4\u627E\u4E0D\u5230", fix: "npm i -g left-skills" };
+  }
+}
+function checkHook() {
+  const settingsPath = (0, import_node_path4.join)((0, import_node_os4.homedir)(), ".claude", "settings.json");
+  if (!(0, import_node_fs4.existsSync)(settingsPath)) {
+    return { name: "hook in settings", ok: false, detail: "~/.claude/settings.json \u4E0D\u5B58\u5728", fix: "left-skills install --write" };
+  }
+  try {
+    const settings = JSON.parse((0, import_node_fs4.readFileSync)(settingsPath, "utf-8"));
+    const hooks = settings.hooks || {};
+    const hasLeft = Object.values(hooks).some(
+      (entries) => entries.some((e) => (e.hooks || []).some((h) => h.command && h.command.includes("left-skills")))
+    );
+    return hasLeft ? { name: "hook in settings", ok: true, detail: "~/.claude/settings.json \u6709 left-skills hook" } : { name: "hook in settings", ok: false, detail: "settings.json \u65E0 left-skills hook", fix: "left-skills install --write" };
+  } catch {
+    return { name: "hook in settings", ok: false, detail: "settings.json \u89E3\u6790\u5931\u8D25", fix: "\u68C0\u67E5 ~/.claude/settings.json JSON" };
+  }
+}
+function checkUsageFile() {
+  const usagePath = (0, import_node_path4.join)((0, import_node_os4.homedir)(), ".left-skills", "usage.json");
+  return (0, import_node_fs4.existsSync)(usagePath) ? { name: "usage.json", ok: true, detail: "~/.left-skills/usage.json \u5B58\u5728" } : { name: "usage.json", ok: false, detail: "~/.left-skills/usage.json \u4E0D\u5B58\u5728(\u9996\u6B21\u7528\u540E\u521B\u5EFA)", fix: "\u6253 /skill \u6216 AI \u8C03 skill \u89E6\u53D1 hook \u8BB0\u5F55" };
+}
+function checkHookCanRun() {
+  try {
+    (0, import_node_child_process.execSync)('echo "{}" | left-skills hook UserPromptExpansion', { encoding: "utf-8", stdio: "pipe" });
+    return { name: "hook command runs", ok: true, detail: "left-skills hook \u80FD\u6267\u884C" };
+  } catch {
+    return { name: "hook command runs", ok: false, detail: "left-skills hook \u547D\u4EE4\u6267\u884C\u5931\u8D25", fix: "\u68C0\u67E5 left-skills binary / node" };
+  }
+}
+function checkNodeVersion() {
+  try {
+    const ver = (0, import_node_child_process.execSync)("node --version", { encoding: "utf-8" }).trim();
+    const major = parseInt(ver.slice(1).split(".")[0], 10);
+    return major >= 18 ? { name: "node version", ok: true, detail: `${ver} (\u226518)` } : { name: "node version", ok: false, detail: `${ver} (<18)`, fix: "\u5347\u7EA7 node \u5230 18+" };
+  } catch {
+    return { name: "node version", ok: false, detail: "node \u547D\u4EE4\u627E\u4E0D\u5230", fix: "\u88C5 node 18+" };
+  }
+}
+function runDoctor() {
+  return [checkBinary(), checkHook(), checkUsageFile(), checkHookCanRun(), checkNodeVersion()];
+}
+
 // package.json
 var package_default = {
   name: "left-skills",
-  version: "0.1.9",
+  version: "0.3.0",
   description: "\u7ED9 AI \u7528\u7684 skill \u751F\u547D\u5468\u671F\u7BA1\u7406\u5DE5\u5177 \u2014 MVP: skill \u8C03\u7528\u4F7F\u7528\u7EDF\u8BA1",
   bin: {
     "left-skills": "./dist/cli.js"
@@ -3309,6 +3399,19 @@ program2.command("usage").description("skill \u8C03\u7528\u4F7F\u7528\u62A5\u544
     console.log(formatHuman(report));
   }
 });
+program2.command("report").description("\u5BFC\u51FA usage \u62A5\u544A markdown(\u53EF > report.md \u5206\u4EAB)").option("--markdown", "\u8F93\u51FA markdown(\u9ED8\u8BA4\u5373 markdown)").option("--since <days>", "\u65F6\u95F4\u7A97\u53E3(\u5929,\u9ED8\u8BA4 30)", "30").action((opts) => {
+  const since = parseInt(opts.since, 10) || 30;
+  const report = buildReport(since);
+  console.log(formatMarkdown(report));
+});
+program2.command("doctor").description("\u8BCA\u65AD left-skills \u5B89\u88C5/hook \u914D\u7F6E(\u2713/\u2717 + \u4FEE\u590D\u5EFA\u8BAE)").action(() => {
+  const results = runDoctor();
+  for (const r of results) {
+    const mark = r.ok ? "\u2713" : "\u2717";
+    console.log(`${mark} ${r.name}: ${r.detail}`);
+    if (r.fix) console.log(`    \u2192 \u4FEE\u590D: ${r.fix}`);
+  }
+});
 program2.command("install").description("\u8F93\u51FA hook \u914D\u7F6E\u7247\u6BB5(\u9ED8\u8BA4)\u6216 --write \u81EA\u52A8\u5199\u8FDB ~/.claude/settings.json(\u5408\u5E76+\u5907\u4EFD .bak)").option("--write", "\u81EA\u52A8\u5199 hook \u5230 settings.json(\u5408\u5E76\u53BB\u91CD + \u5907\u4EFD .bak)", false).action((opts) => {
   if (opts.write) {
     const path = globalSettingsPath();
@@ -3320,6 +3423,12 @@ program2.command("install").description("\u8F93\u51FA hook \u914D\u7F6E\u7247\u6
     console.log("\n# \u628A\u4E0A\u9762\u7247\u6BB5\u52A0\u8FDB ~/.claude/settings.json \u7684 hooks \u5B57\u6BB5,\u6216\u8DD1 left-skills install --write \u81EA\u52A8\u5199");
   }
 });
+program2.command("uninstall").description("\u5220 ~/.claude/settings.json \u7684 left-skills hook(\u5E72\u51C0\u5378\u8F7D,\u5907\u4EFD .bak)").action(() => {
+  const path = globalSettingsPath();
+  removeHooksFromSettings(path);
+  console.log(`\u2713 left-skills hook \u5DF2\u4ECE ${path} \u5220\u9664(\u5DF2\u5907\u4EFD .bak)`);
+  console.log("  \u518D\u8DD1 npm uninstall -g left-skills \u5378\u8F7D binary");
+});
 program2.command("hook <event>").description("hook \u5165\u53E3(\u8BFB stdin payload)").action(async (event) => {
   const payload = await readStdinPayload();
   if (!payload) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "left-skills",
-  "version": "0.1.9",
+  "version": "0.3.0",
   "description": "给 AI 用的 skill 生命周期管理工具 — MVP: skill 调用使用统计",
   "bin": {
     "left-skills": "./dist/cli.js"