dev-change-report 0.0.0-stage → 1.1.0

package/README.md

@@ -1,3 +1,162 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# dev-change-report
+
+把一次代码改动整理成**可直接粘贴的富文本 HTML**，用于 OA / CKEditor / 飞书 / Word 的开发说明文档。
+
+- 片段里只写语义标签，样式由命令统一注入，改观感只改一处
+- 代码块自动从**真实文件按行截取**，不用手抄、不用转义
+- 输出单个 `report.html`，编辑器源码模式粘贴即成型，无需上传截图
+- 零第三方依赖，Node 18+，Windows / macOS / Linux 通用
+
+## 安装
+
+**一句话：装个依赖就行，skill 会自动注册。**
+
+```bash
+npm i -D dev-change-report
+```
+
+`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 时才需要）
+
+`npm run exe` 会生成 `dist/dcr.exe`（83 MB），打包后约 33 MB。
+体积来自内嵌的 Node 运行时，SEA 不支持裁剪，无法再小。
+
+对方解压 `dcr-win-x64.zip` 后双击 `install.cmd` 即可（自动复制到
+`%LOCALAPPDATA%\Programs\dcr`、加 PATH、注册 skill）。首次运行可能有
+SmartScreen 提示，点「更多信息」→「仍要运行」。
+
+> 83 MB 换来的只是「不用装 Node」。如果对方有 Node，用 npm 包，体积差约 3000 倍。
+
+
+## 使用
+
+### 1. 收集改动
+
+```bash
+npx dcr changes --repo . --base origin/release
+```
+
+输出分支、HEAD、文件清单与增删行数，并列出工作区未提交改动。
+加 `--json changes.json` 可导出结构化清单。
+
+### 2. 写片段
+
+新建 `report.fragment.html`，只写标签，不写样式：
+
+```html
+<h2>一、选择柜组件优化</h2>
+
+<h3>1.1 默认搜索条件与 PC 对齐</h3>
+<p>原问题：默认按实际柜号搜索且发货日期写死当天，柜的发货时间普遍早于当天，必然空结果。</p>
+<pre data-code-file="src/views/qbcrm/blRelease/Form.vue" data-code-range="56-79"></pre>
+<p tip="info">改后效果：打开即有数据，输入提示随字段联动。</p>
+```
+
+| 写法 | 用途 |
+|---|---|
+| `<h2>` / `<h3>` | 一级章节 / 二级标题 |
+| `<p>` | 正文 |
+| `<p tip="info\|warn\|danger">` | 提示块（绿 / 黄 / 红） |
+| `<table><tr><th>…<td>…` | 表格，不要写 border 或 style |
+| `<ul><li>` | 列表 |
+| `<code>` | 行内代码 |
+| `<pre data-code-file="…" data-code-range="…">` | 从文件按行截取（推荐） |
+| `<pre data-code-lang="text">…</pre>` | 内嵌代码，需转义 `<` `>` `&` |
+
+`data-code-range` 是 1-based 闭区间（如 `56-79`），省略则取全文。
+
+### 3. 生成
+
+```bash
+npx dcr build --input report.fragment.html --repo-root .
+```
+
+产物 `change-report/report.html`。
+
+### 4. 粘贴
+
+打开 `report.html`，全选复制 → 编辑器切到「源码」模式 → 粘贴 → 切回可视化。
+
+## 调整样式
+
+打开 `lib/build.js`，顶部的 `STYLE` 与 `TIP` 两个字典控制全部观感：
+
+```js
+const STYLE = {
+  h2: 'font-size:19px;font-weight:600;margin:26px 0 12px;...',
+  pre: 'background:#f6f8fa;border:1px solid #e5e8eb;...',
+  // ...
+};
+const TIP = { info: ['#f2f7f4', '#0a7a50'], warn: [...], danger: [...] };
+```
+
+## 命令总览
+
+```
+dcr install [--project] [--force]     安装 skill 到 .agents/skills/
+dcr build --input <fragment.html>     生成 report.html
+      [--outdir ./change-report]
+      [--repo-root .]
+dcr changes --repo <路径> [--repo …]  收集 git 改动清单
+      [--base origin/release]
+      [--json changes.json]
+dcr --version                         查看版本
+dcr help                              查看帮助
+```
+
+## 自行构建 exe
+
+只在确实需要「无 Node 环境」分发时才构建。需要 Node 20+（含 SEA 支持），
+`tools/` 下的脚本零第三方依赖，只有注入环节需要 `postject`。
+
+```bash
+npm i -D postject
+npm run bundle      # lib/ + bin/ 合并成 dist/dcr-bundle.js（21 KB）
+npm run sea:blob    # 生成 dist/sea-prep.blob
+node tools/make-exe.js --node "C:\Program Files\nodejs\node.exe"
+```
+
+`--node` 必须指向**真实的 node.exe**（80 MB 左右）。用 Volta / nvm 时 `Get-Command node`
+拿到的是几 MB 的 shim，注入会失败，用 `node -e "console.log(process.execPath)"` 找真实路径。
+
+SKILL.md 会被内嵌进 exe，所以对方运行 `dcr.exe install` 时不需要任何外部文件。
+
+exe 产物已在 `.gitignore` 中排除，不会进版本库。
+
+## 常见问题
+**代码块显示成一行？**
+`<pre>` 依赖 `white-space:pre-wrap`，若编辑器剥离了内联样式，把生成的 `<pre>` 标签内容重新粘贴一次，或换用支持内联样式的编辑器（飞书文档、新版 CKEditor 均可）。
+
+**`data-code-file` 报文件不存在？**
+检查 `--repo-root` 是否指向代码仓库根目录。引用其他仓库的文件用相对路径，如 `../another-repo/src/a.ts`。
+
+**表格没有边框？**
+片段里不要给 `<table>` 写 `border` 属性，交给脚本注入 `border-collapse` 与单元格边框。
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: dev-change-report
+description: 把一次代码改动整理成可直接粘贴到 CKEditor / OA / 飞书 / Word 的开发说明文档。代码块以浅灰底等宽字体呈现，全部内联样式，源码模式粘贴即成型。Use when the user asks to 整理改动内容、输出开发描述、写改动说明、总结本次改动、生成需求交付文档、生成代码说明文档、粘贴到富文本编辑器。
+---
+
+# 开发改动说明文档
+
+把代码改动整理成一份**可直接粘贴的富文本 HTML**。
+
+命令由 npm 包 `dev-change-report` 提供（`npx dcr`）。如果项目里还没有：
+`npm i -D dev-change-report`，装完 skill 会自动注册。
+
+核心约定：**片段只写语义标签，不写任何 style**，样式由 `dcr build` 统一注入。
+
+## 工作流
+
+1. **收集改动**
+   ```bash
+   npx dcr changes --repo . --repo ../another-repo --base origin/release
+   ```
+   省略 `--base` 会自动探测（`origin/release` → `master` → `main` → `develop` → `HEAD~10`），
+   同时列出工作区未提交改动。
+
+2. **读关键 diff**，每个要点写清三件事：**原问题 → 怎么改的 → 改后效果**。
+   需要精确行号时用 `git -C <repo> diff --unified=0 <base>...HEAD -- <file>`，
+   拿到的 `@@ -a,b +c,d @@` 可直接换算成 `data-code-range`。
+
+3. **写片段** `report.fragment.html`（只写标签，不写样式）。
+
+4. **生成**
+   ```bash
+   npx dcr build --input report.fragment.html --outdir ./change-report --repo-root .
+   ```
+   产物只有 `report.html` 一个文件。
+
+5. **交付**：给出 `report.html` 全文，提示「粘到编辑器源码模式 → 切回可视化」。
+
+## 片段写法
+
+```html
+<h2>一、模块名</h2>
+
+<h3>1.1 要点</h3>
+<p>原问题：……</p>
+<pre data-code-file="src/a.ts" data-code-range="40-60"></pre>
+<p tip="info">改后效果：……</p>
+```
+
+| 写法 | 用途 |
+|---|---|
+| `<h2>` / `<h3>` | 一级章节 / 二级标题 |
+| `<p>` | 正文 |
+| `<p tip="info">` / `warn` / `danger` | 提示块（绿 / 黄 / 红） |
+| `<table><tr><th>…<td>…` | 表格，**不要**写 border 或 style |
+| `<ul><li>` | 列表 |
+| `<code>` | 行内代码，如 `<code>Form.vue</code>` |
+| `<pre data-code-file="…" data-code-range="…">` | 代码块，从文件按行截取（推荐） |
+| `<pre data-code-lang="text">…</pre>` | 代码块，内嵌（需转义 `<` `>` `&`） |
+
+`data-code-file` 相对 `--repo-root`；`data-code-range` 是 1-based 闭区间，省略取全文。
+**优先引用真实文件**，避免手抄出错。只截 8~25 行能说明问题的片段，不要贴整文件。
+
+## 报告结构
+
+```
+<h2>标题</h2>
+<table> 元信息：需求 / 分支 / 提交 / 影响范围
+<h2>一、<板块 1></h2>   要点 + 代码块
+<h2>二、<板块 2></h2>
+<h2>三、涉及文件清单</h2>  表格，相对路径 + <code>
+<h2>四、验证记录</h2>
+<h2>五、上线说明</h2>  发布顺序、环境变量（用 tip="danger" 提示风险）
+```
+
+写作要点：
+- 代码块前用一句话说明**为什么**需要这段代码，块后不重复解释代码本身
+- 「两个字段名字一样但含义不同」这类根因，比贴代码更有价值
+- 文件清单写**相对路径**，不写绝对路径
+- 先写正文章节，最后统一补标题编号，避免反复改
+
+## 富文本兼容
+
+脚本已处理：`<pre>` 等宽与换行、表格边框、行内代码底色、提示块配色、各级标签默认字号间距。
+片段里仍需避免：
+
+| 禁止 | 原因 |
+|---|---|
+| `<style>` 块 | 编辑器会剥离 |
+| `<p>` 嵌套 `<p>` | 编辑器会拆结构 |
+| Markdown 语法（`**`、`` ` ``） | 源码模式不转换 |
+| `<pre>` 里手写代码 | 用 `data-code-*` 占位，交给脚本转义 |
+
+## 命令参数
+
+| 命令 | 参数 | 说明 |
+|---|---|---|
+| `dcr build` | `--input` | 必填，片段 HTML 路径 |
+| | `--outdir` | 默认 `./change-report` |
+| | `--repo-root` | 默认当前目录，`data-code-file` 的解析根 |
+| `dcr changes` | `--repo` | 可多次传入 |
+| | `--base` | 对比基线，省略自动探测 |
+| | `--json` | 导出结构化清单 |
+| `dcr install` | `--project` | 装到当前项目而非用户目录 |
+| | `--force` | 覆盖已有版本 |
+
+## 环境
+
+`npx dcr --version` 能输出版本号即可用。包内零第三方依赖，Node 18+，Windows / macOS / Linux 通用。
+
+`change-report/` 属于临时产物，交付后清理，或在 `.gitignore` 中排除。

package/bin/dcr.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * dcr —— dev-change-report 命令行入口
+ *
+ *   dcr install [--project] [--force]     把 skill 装到 .agents/skills/
+ *   dcr build   --input <fragment.html>   生成 report.html
+ *   dcr changes --repo <path> [--repo …]  收集 git 改动清单
+ */
+const { run } = require('../lib/cli');
+
+process.exitCode = run(process.argv.slice(2));

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/build.js

@@ -0,0 +1,106 @@
+/**
+ * 报告生成核心：把带 <pre data-code-*> 占位的 HTML 片段转成富文本 HTML。
+ * 片段里不写任何 style，样式由 STYLE / TIP 两个字典统一注入。
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+
+// ---- 样式字典：只改这里，全文观感随之变化 ----
+const BASE = 'font-size:14px;line-height:1.75;color:#2f363d;';
+const STYLE = {
+  h2: 'font-size:19px;font-weight:600;margin:26px 0 12px;padding-bottom:6px;border-bottom:1px solid #e5e8eb;color:#1f2328;',
+  h3: 'font-size:15px;font-weight:600;margin:18px 0 8px;color:#1f2328;',
+  p: `${BASE}margin:10px 0;`,
+  ul: `${BASE}margin:10px 0 10px 22px;padding:0;`,
+  li: 'margin:4px 0;',
+  table: 'border-collapse:collapse;width:100%;font-size:13px;margin:12px 0;',
+  th: 'padding:7px 10px;text-align:left;border:1px solid #dfe3e6;background:#f6f8fa;font-weight:600;',
+  td: 'padding:7px 10px;border:1px solid #dfe3e6;vertical-align:top;',
+  code: 'background:#f2f4f6;padding:1px 5px;border-radius:3px;font-family:Consolas,Monaco,monospace;font-size:13px;color:#b3320f;',
+  pre: 'background:#f6f8fa;border:1px solid #e5e8eb;border-radius:3px;padding:10px 12px;margin:10px 0;'
+    + 'font-family:Consolas,Monaco,"Courier New",monospace;font-size:13px;line-height:1.55;'
+    + 'white-space:pre-wrap;word-break:break-word;color:#24292f;'
+};
+const TIP = {
+  info: ['#f2f7f4', '#0a7a50'],
+  warn: ['#fdf8e9', '#c99515'],
+  danger: ['#fcf0ef', '#c0392b']
+};
+
+const escapeHtml = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+const decodeEntities = (s) => String(s)
+  .replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"')
+  .replace(/&#39;/g, "'").replace(/&nbsp;/g, ' ').replace(/&amp;/g, '&');
+const attr = (tag, name) => (tag.match(new RegExp(`${name}\\s*=\\s*"([^"]*)"`)) || [])[1] || '';
+
+/** 从文件按 1-based 闭区间截取；range 形如 "40-60"，省略则取全文。 */
+function readCode(repoRoot, file, range) {
+  const full = path.isAbsolute(file) ? file : path.join(repoRoot, file);
+  if (!fs.existsSync(full)) throw new Error(`data-code-file 指向的文件不存在: ${full}`);
+  const lines = fs.readFileSync(full, 'utf8').replace(/\r\n?/g, '\n').split('\n');
+  if (!range) return lines.join('\n');
+  const [a, b] = String(range).split('-');
+  const from = Math.max(1, parseInt(a, 10) || 1);
+  const to = b ? Math.min(lines.length, parseInt(b, 10) || lines.length) : lines.length;
+  return lines.slice(from - 1, to).join('\n');
+}
+
+/** 占位 -> 浅灰底 <pre>。必须在注入样式之前执行，避免代码里的 <h2> 被误处理。 */
+function renderCodeBlocks(html, repoRoot, log) {
+  let seq = 0;
+  return html.replace(/<pre\b([^>]*)>([\s\S]*?)<\/pre>/gi, (whole, attrs, inner) => {
+    if (!/data-code-(file|lang)/i.test(attrs)) return whole;
+    seq += 1;
+    const file = attr(attrs, 'data-code-file');
+    const range = attr(attrs, 'data-code-range');
+    const raw = file ? readCode(repoRoot, file, range) : decodeEntities(inner);
+    const code = raw.replace(/^\n+/, '').replace(/\s+$/, '');
+    if (!code) { log(`  ! #${seq} 空代码块，已跳过`); return ''; }
+    const src = file ? `${file}:${range || 'all'}` : 'inline';
+    log(`  #${String(seq).padStart(2, '0')} ${src} (${code.split('\n').length} 行)`);
+    return `<pre style="${STYLE.pre}">${escapeHtml(code)}</pre>`;
+  });
+}
+
+/** 给没有 style 的标签补默认样式。 */
+const styleTag = (html, tag, style) =>
+  html.replace(new RegExp(`<${tag}(\\s[^>]*)?>`, 'gi'), (m, attrs = '') =>
+    /\bstyle\s*=/i.test(attrs) ? m : `<${tag}${attrs} style="${style}">`);
+
+const applyTips = (html) =>
+  html.replace(/<p\s+tip="(\w+)"[^>]*>([\s\S]*?)<\/p>/gi, (m, kind, inner) => {
+    const [bg, border] = TIP[kind] || TIP.info;
+    return `<p style="${BASE}margin:10px 0;padding:8px 12px;background:${bg};border-left:3px solid ${border};">${inner}</p>`;
+  });
+
+const TAGS = ['h2', 'h3', 'p', 'ul', 'li', 'table', 'th', 'td', 'code'];
+
+/**
+ * @param {object} options
+ * @param {string} options.input   片段 HTML 路径
+ * @param {string} [options.outdir] 输出目录，默认 ./change-report
+ * @param {string} [options.repoRoot] data-code-file 的解析根目录
+ * @param {(s:string)=>void} [options.log]
+ * @returns {{outFile:string, bytes:number}}
+ */
+function buildReport(options) {
+  if (!options.input) throw new Error('缺少 input');
+  const input = path.resolve(options.input);
+  if (!fs.existsSync(input)) throw new Error(`输入文件不存在: ${input}`);
+  const outdir = path.resolve(options.outdir || './change-report');
+  const repoRoot = path.resolve(options.repoRoot || process.cwd());
+  const log = options.log || (() => {});
+
+  let html = fs.readFileSync(input, 'utf8');
+  html = renderCodeBlocks(html, repoRoot, log);
+  html = applyTips(html);
+  for (const tag of TAGS) html = styleTag(html, tag, STYLE[tag]);
+
+  fs.mkdirSync(outdir, { recursive: true });
+  const outFile = path.join(outdir, 'report.html');
+  const out = html.trim() + '\n';
+  fs.writeFileSync(outFile, out, 'utf8');
+  return { outFile, bytes: Buffer.byteLength(out) };
+}
+
+module.exports = { buildReport, STYLE, TIP };

package/lib/changes.js

@@ -0,0 +1,100 @@
+/**
+ * 收集 git 改动清单，供撰写「改动说明」时对照。
+ * 不指定 base 时自动探测：origin/release → origin/master → origin/main → origin/develop → HEAD~10。
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const git = (repo, args) => {
+  try {
+    return execFileSync('git', ['-C', repo, ...args], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore']
+    }).trim();
+  } catch {
+    return '';
+  }
+};
+
+const detectBase = (repo) => {
+  for (const candidate of ['origin/release', 'origin/master', 'origin/main', 'origin/develop']) {
+    if (git(repo, ['rev-parse', '--verify', '--quiet', candidate])) return candidate;
+  }
+  return 'HEAD~10';
+};
+
+const parseNumstat = (text) => text.split('\n')
+  .filter((line) => line.trim())
+  .map((line) => {
+    const [added, deleted, file] = line.split('\t');
+    if (!file) return null;
+    return {
+      path: file,
+      added: added === '-' ? null : Number(added),
+      deleted: deleted === '-' ? null : Number(deleted)
+    };
+  })
+  .filter(Boolean);
+
+const parseStatus = (text) => text.split('\n')
+  .filter((line) => line.trim())
+  .map((line) => ({ code: line.slice(0, 2).trim(), path: line.slice(3).trim() }));
+
+/**
+ * @param {object} options
+ * @param {string[]} options.repos 仓库路径
+ * @param {string} [options.base]  对比基线，省略则自动探测
+ * @param {string} [options.json]  导出 JSON 的路径
+ * @param {(s:string)=>void} [options.log]
+ */
+function collectChanges(options) {
+  const repos = (options.repos || []).filter(Boolean);
+  if (!repos.length) throw new Error('至少需要一个仓库路径');
+  const log = options.log || (() => {});
+  const report = { generatedAt: new Date().toISOString(), repos: [] };
+
+  for (const repoArg of repos) {
+    const repo = path.resolve(repoArg);
+    if (!fs.existsSync(repo)) {
+      log(`跳过不存在的路径: ${repo}`);
+      continue;
+    }
+    const name = path.basename(repo);
+    const branch = git(repo, ['rev-parse', '--abbrev-ref', 'HEAD']) || '(unknown)';
+    const head = git(repo, ['log', '-1', '--format=%h %s']) || '';
+    const base = options.base || detectBase(repo);
+    const files = parseNumstat(git(repo, ['diff', '--numstat', `${base}...HEAD`]));
+    const uncommitted = parseStatus(git(repo, ['status', '--porcelain', '--untracked-files=all']));
+
+    report.repos.push({ name, path: repo, branch, head, base, files, uncommitted });
+
+    log(`\n=== ${name} (${branch}) ===`);
+    log(`HEAD: ${head}`);
+    log(`BASE: ${base}`);
+    if (!files.length) {
+      log('  分支内暂无已提交改动');
+    } else {
+      const added = files.reduce((sum, f) => sum + (f.added || 0), 0);
+      const deleted = files.reduce((sum, f) => sum + (f.deleted || 0), 0);
+      log(`  已提交改动 ${files.length} 个文件，+${added} / -${deleted}`);
+      for (const file of files) {
+        const stat = file.added === null ? 'binary' : `+${file.added}/-${file.deleted}`;
+        log(`    ${stat.padEnd(12)} ${file.path}`);
+      }
+    }
+    if (uncommitted.length) {
+      log(`  工作区未提交 ${uncommitted.length} 项`);
+      for (const item of uncommitted) log(`    [${item.code}] ${item.path}`);
+    }
+  }
+
+  if (options.json) {
+    const out = path.resolve(options.json);
+    fs.writeFileSync(out, JSON.stringify(report, null, 2), 'utf8');
+    log(`\nJSON 已写入: ${out}`);
+  }
+  return report;
+}
+
+module.exports = { collectChanges, detectBase };

package/lib/cli.js

@@ -0,0 +1,107 @@
+/**
+ * CLI 主逻辑（不依赖进程启动方式），供 bin/dcr.js 与 SEA 单文件入口共用。
+ */
+const { buildReport } = require('./build');
+const { collectChanges } = require('./changes');
+const { installSkill } = require('./install');
+
+const HELP = `dcr —— 代码改动说明文档生成器
+
+安装后无需任何配置：npm i 时已自动把 skill 注册到 ~/.agents/skills/。
+
+用法:
+  dcr install [--project] [--force]        手动注册 skill（一般不需要）
+         --project   装到当前项目而非用户目录
+         --force     覆盖已存在的版本
+
+  dcr build --input <fragment.html>        生成富文本报告
+         [--outdir ./change-report]        输出目录
+         [--repo-root .]                   data-code-file 的解析根目录
+
+  dcr changes --repo <路径> [--repo …]     收集 git 改动清单
+         [--base origin/release]          对比基线（省略自动探测）
+         [--json changes.json]            导出 JSON
+
+示例:
+  dcr changes --repo . --base origin/release
+  dcr build --input report.fragment.html --repo-root .`;
+
+function parseArgs(argv) {
+  const args = { repos: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith('--')) continue;
+    const key = token.replace(/^--/, '').replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    const value = argv[i + 1];
+    if (key === 'repo') {
+      if (value && !value.startsWith('--')) { args.repos.push(value); i += 1; }
+    } else if (value === undefined || value.startsWith('--')) {
+      args[key] = true;
+    } else {
+      args[key] = value;
+      i += 1;
+    }
+  }
+  return args;
+}
+
+const version = () => global.__DCR_VERSION__ || require('../package.json').version;
+
+/**
+ * @param {string[]} argv 不含 node 与脚本路径的参数
+ * @param {{print?:(s?:string)=>void}} [io]
+ * @returns {number} 退出码
+ */
+function run(argv, io = {}) {
+  const print = io.print || ((line = '') => process.stdout.write(`${line}\n`));
+  const [command, ...rest] = argv;
+  const args = parseArgs(rest);
+
+  if (command === '--version' || command === '-v' || command === 'version') {
+    print(version());
+    return 0;
+  }
+
+  if (!command || command === 'help' || command === '--help' || args.help) {
+    print(HELP);
+    return 0;
+  }
+
+  try {
+    if (command === 'install') {
+      installSkill({ project: args.project === true, force: args.force === true, log: print });
+      return 0;
+    }
+
+    if (command === 'build') {
+      if (!args.input) {
+        print('缺少 --input <fragment.html>，用 dcr help 查看用法');
+        return 1;
+      }
+      print('处理代码块：');
+      const { outFile, bytes } = buildReport({
+        input: args.input,
+        outdir: args.outdir,
+        repoRoot: args.repoRoot,
+        log: print
+      });
+      print(`\n完成 -> ${outFile} (${Math.round(bytes / 1024)} KB)`);
+      print('粘贴方式：编辑器切到「源码」模式，粘入 report.html 全文，再切回可视化。');
+      return 0;
+    }
+
+    if (command === 'changes') {
+      collectChanges({ repos: args.repos, base: args.base, json: args.json, log: print });
+      return 0;
+    }
+
+    print(`未知命令: ${command}\n`);
+    print(HELP);
+    return 1;
+  } catch (error) {
+    print(`\n出错: ${error.message}`);
+    return 1;
+  }
+}
+
+module.exports = { run, version, HELP };

package/lib/install.js

@@ -0,0 +1,84 @@
+/**
+ * 把 SKILL.md 安装到 agent 能识别的 skills 目录。
+ *
+ * 个人级（默认）: <home>/.agents/skills/dev-change-report/SKILL.md   —— 所有项目可用
+ * 项目级（--project）: <cwd>/.agents/skills/dev-change-report/SKILL.md —— 跟着仓库走
+ *
+ * SKILL.md 的来源优先级：
+ *   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');
+const path = require('node:path');
+
+const SKILL_NAME = 'dev-change-report';
+const PACKAGE_ROOT = path.join(__dirname, '..');
+
+/**
+ * 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;
+  if (typeof global.__DCR_SKILL_MD__ === 'string') return global.__DCR_SKILL_MD__;
+  const source = path.join(PACKAGE_ROOT, 'SKILL.md');
+  if (fs.existsSync(source)) return fs.readFileSync(source, 'utf8');
+  throw new Error('找不到 SKILL.md，请确认安装完整');
+}
+
+/**
+ * @param {object} options
+ * @param {boolean} [options.project] true 装到当前项目，false 装到用户目录
+ * @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 || (() => {});
+  const content = readSkillMarkdown(options.content);
+  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 (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, skipped: false };
+  }
+
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(target, content, 'utf8');
+  log(`${existed ? '已更新' : '已安装'}: ${target}`);
+  if (!options.quiet) {
+    log('');
+    log('下一步：重启编辑器，然后对它说「整理一下这次改动」即可触发。');
+  }
+  return { dir, written: true, existed, skipped: false };
+}
+
+module.exports = { installSkill, SKILL_NAME };

package/lib/sea-entry.js

@@ -0,0 +1,7 @@
+/**
+ * SEA 入口：node 单文件可执行程序从这里启动。
+ * 该文件会被 tools/bundle.js 内联，不要 require 任何相对路径以外的资源。
+ */
+const { run } = require('./cli');
+
+process.exitCode = run(process.argv.slice(2));

package/package.json

@@ -1,6 +1,42 @@
-{
-  "name": "dev-change-report",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "dev-change-report",
+  "version": "1.1.0",
+  "description": "把一次代码改动整理成可直接粘贴到 CKEditor / OA / 飞书 / Word 的富文本开发说明文档",
+  "keywords": [
+    "copilot",
+    "skill",
+    "changelog",
+    "report",
+    "ckeditor",
+    "rich-text",
+    "code-review",
+    "documentation"
+  ],
+  "bin": {
+    "dcr": "bin/dcr.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "SKILL.md",
+    "README.md"
+  ],
+  "engines": {
+    "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",
+    "pack:win": "npm run exe && node tools/pack-win.js"
+  },
+  "devDependencies": {
+    "postject": "^1.0.0-alpha.6"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT"
+}