dsh-plugin-daily-report 1.0.0 → 1.0.1

package/README.md

@@ -1,97 +1,97 @@
-# dsh-plugin-daily-report
-
-按天汇总多个 Git 仓库/分支与本地文档，导出 XLSX 日报。
-
-## 功能
-
-- **Git 数据源**：支持多个远程仓库地址（https / ssh / git / file）或本地仓库路径，每个源可指定分支；远程仓库使用裸仓库缓存，首次拉取后再次生成会复用缓存。
-- **本地文档**：支持单个文件或目录；目录递归扫描 `.md`、`.markdown`、`.mdx`、`.txt`、`.text`、`.log`、`.docx`、`.html`、`.htm`。自动跳过 `.git`、`node_modules`、`dist`、`build` 等目录。
-- **按天归集**：Git 按提交作者时间归入日期；文档优先取文件名中的日期，其次取文档内 `date:` / `日期:` 字段，最后使用文件修改时间。
-- **时间范围**：默认当月月初到月底，可在页面中改为任意范围（最长 366 天）。
-- **仅统计我的提交（默认开启）**：按每个仓库的 `git config user.email` / `user.name` 过滤，个人日报不会混入同事提交；可随时关闭。
-- **AI 分析（默认启用）**：使用当前默认模型，结合提交说明、代码 diff 片段和文档摘要，按天生成简要总结；结果写入「日报汇总」的 AI 分析列和独立的「AI分析」工作表。可按天编辑、重新分析单日，也可关闭。
-- **AI 增量缓存**：按“模型 + 日期 + 提交/diff/文档内容”缓存每日分析结果，只重新分析新增或变化的日期；缓存命中会在进度和结果中显示。缓存文件为 `$DSH_HOME/daily-report/ai-cache.json`。
-- **生成结果预览**：生成后先进入预览页，可编辑总体总结、每日 AI 摘要，添加手动工作项，确认后再导出 XLSX；支持对单日重新调用模型分析。每日条目默认折叠，可单日展开或使用「全部展开/全部收起」。
-- **手动补充工作项**：会议、沟通、线上支持等非代码工作可按天补充，导出时进入「手动补充」列。
-- **从目录批量添加仓库**：在 Git 仓库卡片点击「扫描目录」，选择或输入目录后自动识别最多 6 层内的 Git 仓库，读取当前分支并批量加入；已存在的仓库会自动跳过。
-- **设置持久化**：Git 仓库、文档和 AI 分析开关都会保存到 `settings.json`，下次打开页面保持一致；修改后会自动保存，也可以点击右上角「保存设置」立即保存。
-- **生成进度**：生成任务异步执行，页面实时显示当前阶段、百分比和 AI 已接收字数；AI 分析阶段使用不确定进度条，避免长时间无反馈。
-- **XLSX 输出**：工作簿包含【日报汇总】【AI分析】（启用时）【Git明细】【文档明细】【数据源】【说明】工作表，带表头样式、冻结窗格、筛选和列宽。日报汇总冻结日期/星期/日类型三列，Git 明细冻结日期/仓库/分支，左右滚动时保持可见。
-- **独立页面**：左侧全局菜单新增「日报汇总」入口，点击后在中栏打开独立页面，不依附于任何会话。
-- **两种入口**：左侧「日报汇总」页面；同时注册 `daily_report` Agent 工具，便于在对话中直接生成。
-
-## 安装
-
-在 DSH 的「设置 → 插件」中安装 npm 包：
-
-```text
-dsh-plugin-daily-report
-```
-
-或通过插件管理器安装：
-
-```text
-plugin_manager
-  action: install_bundle
-  target: dsh-plugin-daily-report
-```
-
-安装后刷新 DSH 页面，左侧会出现「日报汇总」入口。不要把本包只 `npm install -g` 到 Node 全局目录；DSH 需要把它作为当前 profile 的 bundle 安装。
-
-## 首次配置
-
-首次安装没有预置仓库，页面打开后可以：
-
-- 点击「扫描目录」，选择 `E:\sunline\SBG` 这类目录，批量识别其中的 Git 仓库和当前分支；
-- 或者手动添加仓库地址/本地路径和分支；
-- 添加本地文档或目录；
-- 选择日期范围后生成日报。
-
-页面中可随时增删、修改仓库或分支；修改后会保存到 `settings.json`。
-
-## 使用
-
-1. 点击左侧菜单底部的「日报汇总」图标，在中栏打开独立页面。
-2. 添加 Git 仓库：填写远程地址或本地路径，分支留空时使用默认分支；也可以点击「扫描目录」，指定一个包含多个仓库的目录，批量识别其中的仓库和当前分支。
-3. 添加本地文档：填写文件或目录路径；相对路径以页面顶部的「工作目录」为基准，可点击「使用当前目录」直接加入该目录。
-4. 选择日期范围（默认当月），按需勾选「启用 AI 分析」（默认已勾选），点击页面右上角的「生成 XLSX 日报」。
-5. 生成完成后先在预览区检查：编辑总体/每日 AI 摘要、对某天重新分析、补充手动工作项，确认后点击「导出 XLSX」下载。
-
-Git 仓库、文档和 AI 分析开关会自动保存在 `$DSH_HOME/daily-report/settings.json`，跨会话与重启有效；日期范围不持久化，每次打开默认回到当月。
-
-## Agent 工具
-
-工具名：`daily_report`。参数：
-
-| 参数 | 说明 |
-|---|---|
-| `start` / `end` | 可选，`YYYY-MM-DD`；省略时使用当月 |
-| `git` | 可选，`[{ location, branch, label }]`；省略时使用已保存配置 |
-| `docs` | 可选，字符串数组；省略时使用已保存配置 |
-| `outputPath` | 可选，输出路径；省略时写入当前会话工作目录 |
-| `ai` | 可选，布尔值；`true` 时调用当前默认模型分析提交 diff 与文档摘要 |
-| `locale` | `zh` / `en` |
-
-## 结构
-
-| 文件 | 作用 |
-|---|---|
-| `index.js` | Host 半侧：本地 HTTP 接口、设置持久化、`daily_report` 工具 |
-| `client.js` | Web 半侧：左侧全局入口、中栏独立日报页面、预览编辑与导出 |
-| `lib/collect.js` | Git 日志、作者过滤、文档扫描、按天归集、仓库目录扫描 |
-| `lib/ai.js` | AI 提示词、按天分析、增量缓存、单日重新分析 |
-| `lib/report.js` | XLSX 工作表内容与样式 |
-| `lib/xlsx.js` | 无第三方依赖的 XLSX（ZIP + SpreadsheetML）写入器 |
-| `cordis.patch.yml` | 插入 `daily-report` 插件行 |
-| `locale/*.json` | 插件管理器展示文案 |
-| `icon.svg` | 插件图标 |
-
-## 说明与边界
-
-- Git 读取使用系统 `git`，沿用本机已有的 HTTPS credential helper / SSH agent；HTTP 克隆设置 `GIT_TERMINAL_PROMPT=0`，不会在后台弹出密码提示。
-- 单次最多读取 5000 条提交、3000 个文档；单个文档最大 2 MB；Git 明细中每个提交最多列出 50 个变更文件。
-- 不解析 PDF、Excel、图片或加密文档；这些文件不会进入日报。
-- 「仅统计我的提交」使用每个仓库的 `git config user.email` / `user.name`；远程裸仓库缓存没有仓库级用户配置时会回退到全局配置，若匹配不到可在页面关闭该过滤。
-- AI 分析会读取每个仓库前 60 条提交的代码 diff 片段（每条最多约 1200 字符），并使用当前默认模型；会产生额外的生成时间和 token 消耗。模型调用失败时仍会生成普通日报，并在提示中说明失败原因。
-- AI 缓存只复用未变化的日期；提交、diff、文档摘要或模型变化后会重新分析对应日期。
-- 所有处理在本机完成，不上传仓库或文档内容；启用 AI 分析时，会把上述有界摘要发送给当前配置的模型服务。
+# dsh-plugin-daily-report
+
+按天汇总多个 Git 仓库/分支与本地文档，导出 XLSX 日报。
+
+## 功能
+
+- **Git 数据源**：支持多个远程仓库地址（https / ssh / git / file）或本地仓库路径，每个源可指定分支；远程仓库使用裸仓库缓存，首次拉取后再次生成会复用缓存。
+- **本地文档**：支持单个文件或目录；目录递归扫描 `.md`、`.markdown`、`.mdx`、`.txt`、`.text`、`.log`、`.docx`、`.html`、`.htm`。自动跳过 `.git`、`node_modules`、`dist`、`build` 等目录。
+- **按天归集**：Git 按提交作者时间归入日期；文档优先取文件名中的日期，其次取文档内 `date:` / `日期:` 字段，最后使用文件修改时间。
+- **时间范围**：默认当月月初到月底，可在页面中改为任意范围（最长 366 天）。
+- **仅统计我的提交（默认开启）**：按每个仓库的 `git config user.email` / `user.name` 过滤，个人日报不会混入同事提交；可随时关闭。
+- **AI 分析（默认启用）**：使用当前默认模型，结合提交说明、代码 diff 片段和文档摘要，按天生成简要总结；结果写入「日报汇总」的 AI 分析列和独立的「AI分析」工作表。可按天编辑、重新分析单日，也可关闭。
+- **AI 增量缓存**：按“模型 + 日期 + 提交/diff/文档内容”缓存每日分析结果，只重新分析新增或变化的日期；缓存命中会在进度和结果中显示。缓存文件为 `$DSH_HOME/daily-report/ai-cache.json`。
+- **生成结果预览**：生成后先进入预览页，可编辑总体总结、每日 AI 摘要，添加手动工作项，确认后再导出 XLSX；支持对单日重新调用模型分析。每日条目默认折叠，可单日展开或使用「全部展开/全部收起」。
+- **手动补充工作项**：会议、沟通、线上支持等非代码工作可按天补充，导出时进入「手动补充」列。
+- **从目录批量添加仓库**：在 Git 仓库卡片点击「扫描目录」，选择或输入目录后自动识别最多 6 层内的 Git 仓库，读取当前分支并批量加入；已存在的仓库会自动跳过。
+- **设置持久化**：Git 仓库、文档、AI 分析、仅统计我的提交和日期范围都会保存到 `settings.json`，下次打开页面保持一致；修改后会自动保存，也可以点击右上角「保存设置」立即保存。
+- **生成进度**：生成任务异步执行，页面实时显示当前阶段、百分比和 AI 已接收字数；AI 分析阶段使用不确定进度条，避免长时间无反馈。
+- **XLSX 输出**：工作簿包含【日报汇总】【AI分析】（启用时）【Git明细】【文档明细】【数据源】【说明】工作表，带表头样式、冻结窗格、筛选和列宽。日报汇总冻结日期/星期/日类型三列，Git 明细冻结日期/仓库/分支，左右滚动时保持可见。
+- **独立页面**：左侧全局菜单新增「日报汇总」入口，点击后在中栏打开独立页面，不依附于任何会话。
+- **两种入口**：左侧「日报汇总」页面；同时注册 `daily_report` Agent 工具，便于在对话中直接生成。
+
+## 安装
+
+在 DSH 的「设置 → 插件」中安装 npm 包：
+
+```text
+dsh-plugin-daily-report
+```
+
+或通过插件管理器安装：
+
+```text
+plugin_manager
+  action: install_bundle
+  target: dsh-plugin-daily-report
+```
+
+安装后刷新 DSH 页面，左侧会出现「日报汇总」入口。不要把本包只 `npm install -g` 到 Node 全局目录；DSH 需要把它作为当前 profile 的 bundle 安装。
+
+## 首次配置
+
+首次安装没有预置仓库，页面打开后可以：
+
+- 点击「扫描目录」，选择 `E:\sunline\SBG` 这类目录，批量识别其中的 Git 仓库和当前分支；
+- 或者手动添加仓库地址/本地路径和分支；
+- 添加本地文档或目录；
+- 选择日期范围后生成日报。
+
+页面中可随时增删、修改仓库或分支；修改后会保存到 `settings.json`。
+
+## 使用
+
+1. 点击左侧菜单底部的「日报汇总」图标，在中栏打开独立页面。
+2. 添加 Git 仓库：填写远程地址或本地路径，分支留空时使用默认分支；也可以点击「扫描目录」，指定一个包含多个仓库的目录，批量识别其中的仓库和当前分支。
+3. 添加本地文档：填写文件或目录的绝对路径。
+4. 选择日期范围（默认当月），按需勾选「启用 AI 分析」（默认已勾选），点击页面右上角的「生成 XLSX 日报」。
+5. 生成完成后先在预览区检查：编辑总体/每日 AI 摘要、对某天重新分析、补充手动工作项，确认后点击「导出 XLSX」下载。
+
+Git 仓库、文档、AI 分析开关、作者过滤和日期范围会自动保存在 `$DSH_HOME/daily-report/settings.json`，跨会话与重启有效。
+
+## Agent 工具
+
+工具名：`daily_report`。参数：
+
+| 参数 | 说明 |
+|---|---|
+| `start` / `end` | 可选，`YYYY-MM-DD`；省略时使用当月 |
+| `git` | 可选，`[{ location, branch, label }]`；省略时使用已保存配置 |
+| `docs` | 可选，字符串数组；省略时使用已保存配置 |
+| `outputPath` | 可选，输出路径；省略时写入当前会话工作目录 |
+| `ai` | 可选，布尔值；`true` 时调用当前默认模型分析提交 diff 与文档摘要 |
+| `locale` | `zh` / `en` |
+
+## 结构
+
+| 文件 | 作用 |
+|---|---|
+| `index.js` | Host 半侧：本地 HTTP 接口、设置持久化、`daily_report` 工具 |
+| `client.js` | Web 半侧：左侧全局入口、中栏独立日报页面、预览编辑与导出 |
+| `lib/collect.js` | Git 日志、作者过滤、文档扫描、按天归集、仓库目录扫描 |
+| `lib/ai.js` | AI 提示词、按天分析、增量缓存、单日重新分析 |
+| `lib/report.js` | XLSX 工作表内容与样式 |
+| `lib/xlsx.js` | 无第三方依赖的 XLSX（ZIP + SpreadsheetML）写入器 |
+| `cordis.patch.yml` | 插入 `daily-report` 插件行 |
+| `locale/*.json` | 插件管理器展示文案 |
+| `icon.svg` | 插件图标 |
+
+## 说明与边界
+
+- Git 读取使用系统 `git`，沿用本机已有的 HTTPS credential helper / SSH agent；HTTP 克隆设置 `GIT_TERMINAL_PROMPT=0`，不会在后台弹出密码提示。
+- 单次最多读取 5000 条提交、3000 个文档；单个文档最大 2 MB；Git 明细中每个提交最多列出 50 个变更文件。
+- 不解析 PDF、Excel、图片或加密文档；这些文件不会进入日报。
+- 「仅统计我的提交」使用每个仓库的 `git config user.email` / `user.name`；远程裸仓库缓存没有仓库级用户配置时会回退到全局配置，若匹配不到可在页面关闭该过滤。
+- AI 分析会读取每个仓库前 60 条提交的代码 diff 片段（每条最多约 1200 字符），并使用当前默认模型；会产生额外的生成时间和 token 消耗。模型调用失败时仍会生成普通日报，并在提示中说明失败原因。
+- AI 缓存只复用未变化的日期；提交、diff、文档摘要或模型变化后会重新分析对应日期。
+- 所有处理在本机完成，不上传仓库或文档内容；启用 AI 分析时，会把上述有界摘要发送给当前配置的模型服务。