dev-change-report 1.0.0 → 1.1.0

package/README.md

@@ -9,16 +9,36 @@
 
 ## 安装
 
-**首选 npm 包**（10 KB）。前端同事基本都有 Node，这是最省事的方式。
+**一句话：装个依赖就行，skill 会自动注册。**
 
 ```bash
-npm i -D dev-change-report               # 私有 registry
-npm i -D ./dev-change-report-1.0.0.tgz   # 本地 tarball
-npx dcr install                          # 装到 ~/.agents/skills/，所有项目可用
-npx dcr install --project                # 装到 ./.agents/skills/，跟着仓库走
+npm i -D dev-change-report
 ```
 
-装完**重启编辑器**，对 AI 说「整理一下这次改动」即可触发。
+`postinstall` 会自动把 `SKILL.md` 写到 `~/.agents/skills/dev-change-report/`，
+**重启编辑器**后对 AI 说「整理一下这次改动」即可触发。不需要额外命令。
+
+升级同理，改一下版本号即可，skill 会跟着更新：
+
+```bash
+npm i -D dev-change-report@latest
+```
+
+### 需要时可手动控制
+
+```bash
+npx dcr install             # 重新注册（幂等，内容相同则不写盘）
+npx dcr install --project   # 装到 ./.agents/skills/，跟着仓库走
+npx dcr install --force     # 强制覆盖
+```
+
+| 环境变量 | 作用 |
+|---|---|
+| `DCR_SKIP_INSTALL=1` | 跳过 postinstall 自动注册（CI 里常用） |
+| `DCR_SKILLS_DIR=<路径>` | 自定义 skills 根目录，沙箱/测试用 |
+
+> 如果公司 npm 配置了 `--ignore-scripts`，postinstall 不会执行，
+> 装完手动跑一次 `npx dcr install` 即可。
 
 ### 备选：单文件 exe（对方机器没装 Node 时才需要）
 
@@ -29,7 +49,7 @@ npx dcr install --project                # 装到 ./.agents/skills/，跟着仓
 `%LOCALAPPDATA%\Programs\dcr`、加 PATH、注册 skill）。首次运行可能有
 SmartScreen 提示，点「更多信息」→「仍要运行」。
 
-> 83 MB 换来的只是「不用装 Node」。如果对方有 Node，用 npm 包，体积差约 9000 倍。
+> 83 MB 换来的只是「不用装 Node」。如果对方有 Node，用 npm 包，体积差约 3000 倍。
 
 
 ## 使用

package/SKILL.md

@@ -7,7 +7,9 @@ description: 把一次代码改动整理成可直接粘贴到 CKEditor / OA /
 
 把代码改动整理成一份**可直接粘贴的富文本 HTML**。
 
-需要的命令由 npm 包 `dev-change-report` 提供（`npx dcr`），前置条件：项目已安装该包。
+命令由 npm 包 `dev-change-report` 提供（`npx dcr`）。如果项目里还没有：
+`npm i -D dev-change-report`，装完 skill 会自动注册。
+
 核心约定：**片段只写语义标签，不写任何 style**，样式由 `dcr build` 统一注入。
 
 ## 工作流

package/bin/postinstall.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * postinstall 钩子：npm i 时自动把 skill 注册到 ~/.agents/skills/。
+ *
+ * 设计约束：
+ *   - 永不失败。任何异常都吞掉并退出码 0，不能因为装 skill 失败而破坏 npm i。
+ *   - 内容一致时完全静默，不给每次 npm i 都刷屏。
+ *   - 用 DCR_SKIP_INSTALL=1 可跳过（CI、或不想污染用户目录时）。
+ *   - 只装用户级（~/.agents/skills）。项目级请手动 dcr install --project。
+ */
+let installSkill;
+
+try {
+  ({ installSkill } = require('../lib/install'));
+} catch (error) {
+  // lib 缺失说明包损坏，交给 npm 的完整性校验处理，这里不发声。
+  process.exit(0);
+}
+
+const skip = String(process.env.DCR_SKIP_INSTALL || '') === '1';
+if (skip) process.exit(0);
+
+// npm run 时会带上大量 npm_config_*，取 loglevel 判断是否静默
+const silent = /silent|error/.test(String(process.env.npm_config_loglevel || ''));
+
+try {
+  const result = installSkill({
+    quiet: true,
+    force: true,
+    log: silent ? () => {} : (line) => process.stdout.write(`[dev-change-report] ${line}\n`)
+  });
+
+  if (result.written && !silent) {
+    process.stdout.write(
+      '[dev-change-report] skill 已就绪，重启编辑器后对 AI 说「整理一下这次改动」即可触发。\n'
+    );
+  }
+} catch (error) {
+  // 无写权限（如只读 HOME、受限沙箱）时静默降级，提示手动安装。
+  if (!silent) {
+    process.stdout.write(
+      '[dev-change-report] 自动注册 skill 失败，请稍后手动执行: npx dcr install\n'
+    );
+  }
+}
+
+process.exit(0);

package/lib/cli.js

@@ -7,8 +7,10 @@ const { installSkill } = require('./install');
 
 const HELP = `dcr —— 代码改动说明文档生成器
 
+安装后无需任何配置：npm i 时已自动把 skill 注册到 ~/.agents/skills/。
+
 用法:
-  dcr install [--project] [--force]        安装 skill 到 .agents/skills/
+  dcr install [--project] [--force]        手动注册 skill（一般不需要）
          --project   装到当前项目而非用户目录
          --force     覆盖已存在的版本
 
@@ -21,7 +23,6 @@ const HELP = `dcr —— 代码改动说明文档生成器
          [--json changes.json]            导出 JSON
 
 示例:
-  dcr install
   dcr changes --repo . --base origin/release
   dcr build --input report.fragment.html --repo-root .`;
 

package/lib/install.js

@@ -8,6 +8,11 @@
  *   1. options.content         调用方直接给内容
  *   2. global.__DCR_SKILL_MD__ 打包进 exe 的内嵌副本
  *   3. 包内 SKILL.md             npm 安装场景
+ *
+ * 三种调用场景：
+ *   - postinstall 自动安装：内容相同则完全静默，不同则覆盖（升级路径）
+ *   - dcr install：显式执行，输出完整提示
+ *   - dcr install --force：强制重写
  */
 const fs = require('node:fs');
 const os = require('node:os');
@@ -16,8 +21,15 @@ const path = require('node:path');
 const SKILL_NAME = 'dev-change-report';
 const PACKAGE_ROOT = path.join(__dirname, '..');
 
-const targetDir = (useProject) =>
-  path.join(useProject ? process.cwd() : os.homedir(), '.agents', 'skills', SKILL_NAME);
+/**
+ * skills 根目录。
+ * DCR_SKILLS_DIR 可整体覆盖，便于在沙箱/CI 里验证而不污染真实用户目录。
+ */
+const targetDir = (useProject) => {
+  const override = String(process.env.DCR_SKILLS_DIR || '').trim();
+  if (override) return path.join(override, SKILL_NAME);
+  return path.join(useProject ? process.cwd() : os.homedir(), '.agents', 'skills', SKILL_NAME);
+};
 
 function readSkillMarkdown(explicit) {
   if (explicit) return explicit;
@@ -30,9 +42,11 @@ function readSkillMarkdown(explicit) {
 /**
  * @param {object} options
  * @param {boolean} [options.project] true 装到当前项目，false 装到用户目录
- * @param {boolean} [options.force]   已存在时覆盖
+ * @param {boolean} [options.force]   已存在且内容不同时也覆盖；内容相同永远跳过写入
  * @param {string}  [options.content] 直接指定 SKILL.md 内容
+ * @param {boolean} [options.quiet]   内容无变化时不输出（postinstall 用）
  * @param {(s:string)=>void} [options.log]
+ * @returns {{dir:string, written:boolean, existed:boolean, skipped:boolean}}
  */
 function installSkill(options = {}) {
   const log = options.log || (() => {});
@@ -40,19 +54,31 @@ function installSkill(options = {}) {
   const dir = targetDir(options.project);
   const target = path.join(dir, 'SKILL.md');
   const existed = fs.existsSync(target);
+  const unchanged = existed && fs.readFileSync(target, 'utf8') === content;
 
-  if (existed && !options.force) {
+  // 内容一致就没必要写盘，也不打扰用户。
+  if (unchanged) {
+    if (!options.quiet) {
+      log(`已是最新: ${target}`);
+    }
+    return { dir, written: false, existed: true, skipped: true };
+  }
+
+  // 已存在且内容不同：force 或 quiet（postinstall 升级场景）时覆盖
+  if (existed && !options.force && !options.quiet) {
     log(`已存在，未覆盖: ${target}`);
     log('如需更新，加 --force');
-    return { dir, written: false, existed: true };
+    return { dir, written: false, existed: true, skipped: false };
   }
 
   fs.mkdirSync(dir, { recursive: true });
   fs.writeFileSync(target, content, 'utf8');
   log(`${existed ? '已更新' : '已安装'}: ${target}`);
-  log('');
-  log('下一步：重启编辑器，然后对它说「整理一下这次改动」即可触发。');
-  return { dir, written: true, existed };
+  if (!options.quiet) {
+    log('');
+    log('下一步：重启编辑器，然后对它说「整理一下这次改动」即可触发。');
+  }
+  return { dir, written: true, existed, skipped: false };
 }
 
 module.exports = { installSkill, SKILL_NAME };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dev-change-report",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "把一次代码改动整理成可直接粘贴到 CKEditor / OA / 飞书 / Word 的富文本开发说明文档",
   "keywords": [
     "copilot",
@@ -25,6 +25,7 @@
     "node": ">=18"
   },
   "scripts": {
+    "postinstall": "node bin/postinstall.js",
     "bundle": "node tools/bundle.js",
     "sea:blob": "node --experimental-sea-config packaging/sea-config.json",
     "exe": "npm run bundle && npm run sea:blob && node tools/make-exe.js",