mingdao-harness 0.4.4 → 0.4.6

package/docs/STRATEGY-0.5.md

@@ -0,0 +1,262 @@
+# MingDao Harness 战略与路线（v0.5 起）：从「省钱 Coding Agent」到「可私有化的垂域智能体内核」
+
+> 成文：2026-09-11（v0.4.6 已发布，迁移至 macOS 后首次战略复盘）
+> **决策状态：✅ 已确认（2026-09-11）**——见 §十。
+> 性质：战略规划文件，**经确认后**才逐步落地。落地计划另见 `PLAN-v0.5.0.md`。
+> 前序：`STRATEGY-0.3.md`（产品定位）→ `STRATEGY-NEXT.md`（垂直产品 × 开放内核）→ **本文（垂域内核 + 确定性三保证）**。
+> 事实基础：本仓库 224 commit / 74 版本历史 + 全量源码通读 + 六路并行审计 + `Deyi-TCM-Harness` 下游实测。
+
+---
+
+## 一、复盘：我们现在真正拥有什么
+
+### 1.1 已被验证的资产
+
+| 资产 | 可验证事实 | 性质 |
+| --- | --- | --- |
+| 零依赖内核 | `src/` 74 文件 ~17K 行纯 Node 内置 API，运行时 0 依赖；`npm i -g` 秒装 | 分发/审计成本极低 |
+| DeepSeek 省钱纵深 | 官方词表 BPE（762KB 词表，127,741 merges）· 缓存 1/30 计价 · 峰谷双窗口 · Batch 半价 · 滞回压缩；bench 实测综合省 51%（v0.4.6 口径修正：改用精确计数 + 修正过期的只读档副本） | 对计费细节的闭环掌握 |
+| 本地模型自适应 | 窗口感知预算（75% 舒适区）· 分层超时 · 边缘强制压缩 · 工具输出按窗口截断 | 头部云产品结构性不做的空档 |
+| 工程可信度 | strict 棘轮 0/0 · 覆盖率门禁 60% · 208 bench 断言 · 三平台 CI 矩阵（Ubuntu 18/20/22 + Windows + macOS）· 6 套测试全绿 | 组织习惯，非功能 |
+| 中国分发链路 | 官网直连 + Gitee/GitCode/GitHub 三镜像 + 论坛 + 桌面自动更新 | 大厂不覆盖的细节 |
+| 双界面 + IDE | TUI / WebUI（HTTP+SSE，PWA）/ Electron 桌面 / VS Code / JetBrains | 使用面完整 |
+
+### 1.2 本次新增的关键事实：下游垂域已经真实存在
+
+`Deyi-TCM-Harness`（中医垂域层）不是玩具——它有患者主键模型（病历号）、同名不静默合并、四态对比、回访追踪、诊断字段强制保留等**真实行业约束**。它证明了一件事：
+
+> **MingDao 的内核可以被一个受监管的垂域团队复用，做出该行业的智能体。**
+
+这是 DSH / WorkBuddy / Claude Code 都没有的东西：它们提供的是**通用能力**，而垂域需要的是**领域约束 + 私有化 + 合规**。
+
+### 1.3 但同时，下游暴露了上游最致命的缺口（已实测确认）
+
+通读 `Deyi-TCM-Harness/layer/providers/dify.mjs`（286 行）后确认：**整个中医域逻辑被塞在一个 Provider 的 `chat()` 里**。原因是上游没有「垂域包」这个一等扩展点。代价是具体的：
+
+| 损失的能力 | 证据 |
+| --- | --- |
+| 权限引擎 / 沙箱 | 域内 3 个「工具」是 `chat()` 里的字符串正则（`/^(回访\|随访)\s*(.*)$/`），绕过 `permissions.js` |
+| 审计追溯 | 不写 `audit.jsonl`，无法回答「谁在什么时候读了哪位患者的病历」 |
+| 费用与护栏 | 域内每次 DeepSeek 调用硬编码 `usage: { prompt_tokens: 0, completion_tokens: 0 }` —— **完全不计费、不触发日费用护栏** |
+| UI 工具卡片 / 流式 | 只能手工 `opts.onDelta`，无工具卡片、无思考实况 |
+| 独立版本与契约 | 只能整文件覆盖，无 `apiVersion`、无兼容性保证、无法 CI 验证 |
+| 记忆/技能/预设复用 | 全部用不上 |
+
+**结论：上游下一阶段最高价值的投入，不是再加一个省钱特性，而是把「垂域 Pack」变成有契约的一等公民。** 这既是产品差异化，也是上下游协同的技术前提。
+
+---
+
+## 二、格局：2026-09 的生态位与避战原则
+
+外部事实沿用 `STRATEGY-NEXT.md` 的实查结论（DSH 官方框架 / WorkBuddy 通用平台 / Claude 企业级 / 浪潮元脑本地一体机）。在此基础上补一条本次复盘得到的新判断：
+
+| 生态位 | 谁占了 | 他们为什么不会来抢我们的位置 |
+| --- | --- | --- |
+| 通用框架/插件生态 | **DSH**（官方 + Cordis + MIT） | 拼框架完备度是正面撞车，且我们零依赖的设计恰恰不能要重插件内核 |
+| 通用 Agent 云平台 | **WorkBuddy**（腾讯级资源战） | 需要硬件/行业伙伴/平台治理，不可复制，也不该丢下已有垂直深度 |
+| 通用 Coding Agent | Claude Code / Cursor / OpenHands | 榜单与订阅模式不是我们的战场 |
+| **受监管垂域的私有化智能体内核** | **空档** | 单垂域市场天花板低、需要领域伙伴、必须私有化交付、无法标准化成云 SKU——巨头做了不划算 |
+
+**四条避战原则（在旧三条上补第四条）：**
+
+1. **不拼框架拼契约**——DSH 的框架深度拼不过，但「分钟级上手 + 不改内核就能定制」是 Cordis 给不了的。
+2. **不拼平台拼私有**——WorkBuddy 拼云上生态，我们拼「你的模型、你的机器、你的数据不出门」。
+3. **不拼通用拼垂直**——通用办公让 WorkBuddy/讯飞去卷；我们把省钱与本地模型做到他们不划算做的深度。
+4. **不拼能力拼确定性**（新增，本阶段核心）——巨头都在堆「能力上限」（更强的模型、更多的工具、更大的生态）；**我们补的是「能力之外的三件确定性」**：约束必被强制、成本可预测可归因、行为可审计可回放。能力可以追平，确定性是架构选择——云平台的多租户托管模型天然给不了。
+
+---
+
+## 三、定位升级：一句话与新内核
+
+> **旧定位（STRATEGY-NEXT）**：模型中立、零依赖、会省钱、私有化第一公民的 Agent 内核与终端。
+>
+> **新定位（本文）**：**可私有化的垂域智能体内核**——
+> 「**低依赖、可审计、约束优先、成本可归因**」，给垂域团队一个**不 fork 内核**就能做出合规智能体的基座。
+
+**三层产品结构（不是二选一，是同心圆）：**
+
+```
+        ┌─────────────────────────────────────────────┐
+   第三层 │  垂域 Pack（中医/法律/教育/制造/政务…）        │  ← 行业伙伴 / 下游仓库
+        │  领域工具 · 领域红线 · 领域提示词 · 领域记忆     │
+        ├─────────────────────────────────────────────┤
+   第二层 │  Pack 契约 + 约束引擎 + 归因账本（v0.5 新增）  │  ← 本仓库（护城河）
+        ├─────────────────────────────────────────────┤
+   第一层 │  通用内核：agent 循环 / 工具 / 权限 / 上下文    │  ← 本仓库（已建成）
+        │  Provider / 会话 / 省钱 / 本地模型自适应        │
+        └─────────────────────────────────────────────┘
+```
+
+- **第一层**是已有的通用能力（继续维护，不再无限加特性）；
+- **第二层是本阶段的主攻**，也是「有自己特色的智能体框架」的落点；
+- **第三层**由垂域伙伴/下游仓库提供，上游只提供契约与参考实现。
+
+**产品线（Coding + DeepSeek 省钱）不变**——它是第二层的活广告与真实用户来源。比例维持 `STRATEGY-NEXT` 的「产品线 : 内核线 = 2 : 1」，但本阶段内核线的一次性投入会偏高（因为要一次性把契约做对）。
+
+---
+
+## 四、特色：三个「确定性」——我们和所有头部框架的分野
+
+头部框架在比「能力」：模型更强、工具更多、生态更大。MingDao 不比能力上限，比**确定性下界**——这对私有化/受监管场景是采购硬指标，对通用框架是架构上给不了的东西。
+
+### 确定性 ①：约束确定性（Constraint Certainty）——红线不靠模型自觉
+
+**问题**：垂域的红线（「缺项绝不编造」「不输出诊疗结论」「不得跨患者串病历」）今天只能写在提示词里。提示词是建议，不是强制；模型一次越界就是医疗/法律事故。
+
+**做法**：把领域红线做成**内核级声明式约束**，由 harness 强制执行、阻断并留痕：
+
+```jsonc
+// pack.json 片段
+"constraints": [
+  { "id": "no-diagnosis-conclusion", "kind": "output-forbid",
+    "pattern": "有效|好转|治愈|确诊为", "action": "block-and-rewrite" },
+  { "id": "ten-questions-complete", "kind": "completeness",
+    "fields": ["zhushu","zhenduan","hanre","han","toushen","erbian","yinshi","xiongfu","kouke","jiubing"],
+    "onMissing": "require-tool", "tool": "intake_collect" },
+  { "id": "no-cross-patient", "kind": "tool-arg-require",
+    "tool": "intake_read", "requireArg": "patientId", "action": "block" }
+]
+```
+
+内核在三个时机强制：**PreToolUse（工具与参数）→ PostToolUse（结果）→ 输出前（正文）**，每次触发都写审计。这是提示词工程做不到的，也是通用框架不会做的（它们没有「垂域红线」这个抽象）。
+
+### 确定性 ②：成本确定性（Cost Certainty）——预算可预测、可归因、可阻断
+
+**问题**：私有化采购最怕「账单不可控」。今天的省钱纵深很强，但**归因粒度不够**：域内模型调用可以完全不计费（Deyi 实测 `usage: 0`），子代理消耗曾经漏计（本次审计已修）。
+
+**做法**：
+1. **统一 LLM 出口**：Pack 内所有模型调用必须走 `ctx.llm()`，自动并入 usage / 缓存命中 / 峰谷 / 护栏——域内调用再也无法「隐身」。
+2. **四维归因账本**：`(pack, tool, model, session)` 四级分账，`mingdao cost report --by pack` 可导出。
+3. **预算即资源**：日/周/单任务预算在 Pack 级可设，触顶按 `warn/block/downgrade` 处理（复用已有护栏）。
+4. 诚实原则：无价模型必须显式告警「无法估算」，绝不显示 `¥0.0000` 冒充免费（v0.4.5 已做，继续守住）。
+
+### 确定性 ③：行为确定性（Behavior Certainty）——每步可审计、可回放、可追责
+
+**问题**：受监管场景要回答「这个结论是怎么来的」。今天的 `audit.jsonl` 是追加日志，能追溯但不可回放。
+
+**做法**：
+1. **执行账本**：工具调用 + 模型轮次 + 约束触发 + 权限决策 + 费用，统一为可导出的事件流（脱敏）。
+2. **可回放**：给定账本 + 同一模型，可在离线环境重放一次执行路径（用于事故复盘与验收测试）。
+3. **合规导出**：`mingdao audit export --since --until --format pdf/json`，一键出脱敏审计报告。
+4. **离线证明**：出网白名单 + 出网事件入账，用于「数据不出门」的自证。
+
+---
+
+## 五、护城河重估（诚实版）
+
+| # | 护城河 | 为什么难抄 | 现状 |
+| --- | --- | --- | --- |
+| 1 | **DeepSeek 省钱纵深链** | 官方词表黄金值 + 峰谷双窗口 + 缓存 1/30 + Batch 半价 + bench 棘轮 208 断言的组合 | 已建成，持续加深 |
+| 2 | **零依赖可审计内核** | 主流框架全是依赖树；「一条命令装完 + 逐行可审计」是**等保/信创测评的硬门槛**，推倒重来才能做到 | 已建成（第二层要把它变成卖点） |
+| 3 | **本地模型自适应** | 大厂绑定自家云端；「单机/内网跑长任务不中断」是空档 | 已建成，是垂域私有化的前提 |
+| 4 | **垂域 Pack 契约 + 约束引擎** | 需要把「领域红线」抽象成内核原语；通用框架抽象层次不同，改不动 | **本阶段新建**（新护城河） |
+| 5 | **工程可信度** | strict 0/0 + 覆盖率 + bench + 三平台 CI + 每次发布自检的纪律 | 已建成，需随版本升级配额 |
+
+**伪护城河（警惕）**：功能/技能数量、省钱百分比数字、「先发」本身。都不构成壁垒。
+
+**正确的用法**：靠 **#1+#2+#3+#4+#5 的组合**，而不是单点。单点都可被追平，组合 + 垂域纵深 + 节奏难被复制。
+
+---
+
+## 六、明确不做（防止战略漂移）
+
+- ❌ 不自研模型、不做云端 Agent 平台、不做账号/订阅/抽成体系
+- ❌ 不引入 Cordis / 任何重依赖插件内核（零依赖是根基，也是等保卖点）
+- ❌ 不做插件商店规模竞赛（DSH / WorkBuddy 的地盘）
+- ❌ 不在通用 Coding 榜单上正面竞争
+- ❌ 不做硬件、不做行业应用商店抽成
+- ❌ **不把任何单一垂域的业务逻辑写进内核**（内核只提供抽象；中医在 Pack 里）
+
+---
+
+## 七、路线图（每期可独立发布、全绿门禁）
+
+### 阶段 A：v0.5.0「垂域 Pack 契约」（主攻，建议 2–3 周）
+
+| # | 交付 | 验收 |
+| --- | --- | --- |
+| A1 | **Pack 格式 v1**：`pack.json`(manifest) + `pack.mjs`(contributions)。manifest 含 `apiVersion` / `name` / `version` / `engines.mingdao`；contributions 含 tools / provider / presets / promptSections / permissionPolicy / memorySchema / uiPanels / skills / commands | 一个 Pack 能同时挂上工具、提示词段、权限策略且互不冲突 |
+| A2 | **Pack 加载器**：`config.packs: ["./packs/x", "npm:...", "https://.../pack.tgz"]` + `<home>/packs/<name>/`；缺 depend / 版本不匹配 / 加载失败均不崩启动，显式告警 | 坏 Pack 不阻塞启动（回归断言） |
+| A3 | **约束引擎 v1**：`kind ∈ {tool-deny, tool-arg-require, arg-forbid, output-forbid, completeness, confirm}`，三时机强制 + 审计事件 | 每条 kind 一条回归断言 + 一条真实阻断断言 |
+| A4 | **统一 LLM 出口 `ctx.llm()`**：Pack 内模型调用自动并入 usage / 缓存拆分 / 峰谷 / 护栏 / 四维归因 | Deyi 域内调用不再 `usage:0`（端到端断言） |
+| A5 | **四维归因账本**：`recordUsage` 增 `pack` 维度 + `mingdao cost report --by pack` | 分账可导出且与护栏同源 |
+| A6 | **上下游契约**：`docs/PACK-API.md`（含 apiVersion 语义 + 兼容策略）+ `mingdao pack new/verify/pack` 脚手架与 CI 校验命令 | 下游可 `mingdao pack verify` 做 CI 门禁 |
+| A7 | **偿还本次审计的 P0/P1**（见 `AUDIT-v0.4.6.md`） | 全绿 + 新增回归断言 |
+
+### 阶段 B：v0.5.x「参考实现回迁」（dogfooding，1–2 周）
+1. 把 Deyi 的 3 个域工具**从 Provider 里搬出来**，做成第一个真实 Pack（`pack-tcm` 样例，不含患者数据）；
+2. 用 A3 的约束引擎把中医三条红线从提示词升级为内核强制；
+3. 用 A4 让域内 DeepSeek 调用进入费用账本与护栏；
+4. 反向修正 Pack API：**下游用起来别扭的地方就是上游设计错的地方**。
+- 验收：下游 Pack 通过 `pack verify`，红线有真实阻断测试，域内费用可见。
+
+### 阶段 C：v0.6.0「合规与确定性」（2–3 周）
+1. 执行账本导出（脱敏、可签名）+ 可回放（离线重放执行路径）；
+2. 离线/内网安装包（air-gap，零外网依赖）+ 信创/国产推理栈适配预设；
+3. 出网白名单 + 出网事件入账（「数据不出门」自证）；
+4. 预算即资源：Pack 级预算与配额。
+
+### 阶段 D：v0.7.0「垂域复制」（按需）
+1. 第二个垂域参考实现（建议：法律文书 / 企业知识库 / 制造业 SOP 三选一）；
+2. Pack 注册表（复用技能的 sha256 防篡改基建）+ 企业内网私有 registry；
+3. 若被验证：把「垂域 Pack 交付」做成可复制的交付方法论（脚手架 + 验收清单 + 合规模板）。
+
+---
+
+## 八、上下游协同机制（MingDao ↔ Deyi）
+
+这是本次迁移后**新增的工程约束**：上游在 macOS 本机（DSH 开发），下游在 Linux 原机继续，两条线并行。
+
+### 8.1 边界（不变，写进契约）
+- 下游**只通过扩展点接入**，绝不修改上游源码（`Deyi` README 已明确）；
+- 内核 bug 在**上游修**，下游不重复造；
+- 上游不把任何中医逻辑写进内核。
+
+### 8.2 接口契约（本阶段建立）
+| 项 | 上游承诺 | 下游义务 |
+| --- | --- | --- |
+| `apiVersion` | 同一 major 内 Pack API 向后兼容（minor 只增不改） | 在 `pack.json` 声明 `apiVersion` |
+| 版本窗口 | 支持最近 2 个 minor（如 0.5/0.6） | `engines.mingdao: ">=0.5 <0.7"` |
+| 兼容验证 | 提供 `mingdao pack verify` + 兼容性矩阵文档 | 把 `pack verify` 放进自己的 CI |
+| 破坏性变更 | 走 major 升级 + 提供迁移指南与 codemod（如可行） | 跟版后回归 |
+| 上游发布节奏 | minor 可独立发布 | 每个上游 minor 跑一次兼容 matrix |
+
+### 8.3 协同节奏
+```
+上游 minor 发布 ──▶ 下游拉新内核 ──▶ mingdao pack verify ──▶ 绿：跟版
+                                              └──▶ 红：上游补兼容层 or 下游适配（记入矩阵）
+```
+
+### 8.4 近期具体动作
+1. 上游：v0.5.0 出 Pack API v1 + `pack verify`（**下游在等这个才能把工具从 Provider 里搬出来**）；
+2. 上游：把本次审计发现的漏计费/缓存失效修掉并在 v0.4.6 发布（下游的费用账本依赖它）；
+3. 下游：把 `layer/providers/dify.mjs` 按 Pack 拆分（等 A1–A4 就绪后）；
+4. 双方：确定第一个兼容性矩阵版本窗口（建议 0.5.x ↔ deyi 0.2.x）。
+
+---
+
+## 九、节奏与纪律（防漂移）
+
+1. **每期对照本文**：迭代前先回答「这一期强化的是哪个确定性？有没有撞进『不做』清单？」
+2. **产品线 : 内核线 = 2 : 1**（v0.5.0 例外，一次性投入偏高）。
+3. **发布纪律不变**：全绿门禁 + strict 0/0 + 发布前自检 + 用户验收后再发布。
+4. **每 10 个版本重读一次本文**，用事实（下载/issue/下游反馈）校准。
+5. **新增纪律（垂域线）**：任何 Pack API 变更必须同步更新 `PACK-API.md` 与兼容性矩阵，否则不予合并。
+
+---
+
+## 十、关键决策（✅ 已确认 2026-09-11）
+
+> 四项决策全部确认，本文即生效版本；落地计划见 `PLAN-v0.5.0.md`。
+
+1. **定位确认**：✅ 认同从「省钱 Coding Agent + 开放内核」升级为「**可私有化的垂域智能体内核**」，并把「垂域 Pack 契约 + 约束引擎」作为 v0.5 的**唯一主攻**。
+2. **主攻优先级**：✅ v0.5 做 **确定性①（约束确定性）+ ②（成本确定性）**；**确定性③（行为确定性：执行账本 / 可回放 / 合规导出）放 v0.6.0**。
+3. **下游回迁时机**：✅ **v0.5.0 发布即迁**——Deyi 的 3 个域工具从 Provider 搬进 Pack，用 dogfooding 最快暴露契约缺陷。
+4. **第二个垂域**：⏸ 暂不预设，等第一个垂域（中医）跑通后再定（v0.7.0 议题）。
+5. **费用归因粒度**：以 **Pack + 工具两级**起步（粒度越细埋点越重），后续按需加深。
+
+### 后续待定（v0.5.x 期间再议）
+
+- Pack 是否允许声明式覆盖内置同名 Provider？（起草倾向：不允许覆盖内置，只允许新增）
+- 约束 `block-and-rewrite` 的修正请求计费归属（Pack 还是内核）？
+- Pack 内 `fetch` 是彻底禁止，还是允许但需在 `permissions.net` 白名单内并强制入账？

package/docs/STRATEGY-NEXT.md

@@ -16,7 +16,7 @@
 | 资产 | 事实 | 性质 |
 | --- | --- | --- |
 | 零依赖内核 | `src/` 73 文件 ~15K 行纯 Node 内置 API，无运行时 npm 依赖；`npm i -g` 秒装 | 分发/审计成本极低，同赛道稀缺 |
-| DeepSeek 省钱纵深 | 官方词表 BPE tokenizer（黄金值精确命中）· 前缀缓存两态冻结 · 峰谷双窗口计价 · Batch 半价 · 滞回压缩 · bench-savings 省 63% 基线 | 对 DeepSeek 计费细节的闭环掌握，通用框架不会做 |
+| DeepSeek 省钱纵深 | 官方词表 BPE tokenizer（黄金值精确命中）· 前缀缓存两态冻结 · 峰谷双窗口计价 · Batch 半价 · 滞回压缩 · bench-savings 省 51% 基线（v0.4.6 修正口径：此前 63% 含启发式计数与过期只读档副本） | 对 DeepSeek 计费细节的闭环掌握，通用框架不会做 |
 | 长程任务能力 | 任务续跑 + 检查点（v0.3.0）· 自动续跑（v0.3.1）· 项目级记忆 · 子代理 | 从「24 步必断」到「长任务连续执行」 |
 | 本地模型自适应 | 上下文窗口感知预算 + 分层超时 + 边缘强制压缩 + 工具输出自适应截断（v0.3.2） | 大厂押注云端模型，这是空档 |
 | 工程可信度 | strict 棘轮 0/0 · 覆盖率 60% · bench 208 断言 · 三平台 CI · 每次发布自检 | 信任是独立开发者最稀缺的护城河 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mingdao-harness",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "MingDao Harness —— 开源智能体框架（Agent Harness）。零依赖、开箱即用，针对 DeepSeek-V4 系列优化，开放主流模型接入。",
   "type": "module",
   "bin": {
@@ -14,6 +14,7 @@
   "files": [
     "src/",
     "skills/",
+    "skills-lib/",
     "presets/",
     "assets/",
     "docs/",

package/skills-lib/bash/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: bash
+description: Bash/Shell 脚本编写（健壮性与可移植性）
+---
+
+# Bash 脚本编写
+
+写 shell 脚本或复杂的单行命令时使用。
+
+## 规则
+
+1. 开头固定：`#!/usr/bin/env bash` 与 `set -euo pipefail`（有意容忍错误处显式 `|| true`）。
+2. 变量引用加双引号 `"$var"`，避免分词与通配展开；路径含空格要安全处理。
+3. 用 `[[ ]]` 测试、`$(...)` 命令替换；不用已废弃的反引号。
+4. 循环处理文件名优先 `find -print0 | while read -r -d ''`，避免空格文件名问题。
+5. 长脚本拆函数；用户输入先校验（非空、格式、范围）。
+
+## 检查点
+
+- 不把 `rm -rf "$dir"` 的危险变量未校验就执行；
+- 给出可移植性说明（bash 4+ / GNU coreutils 差异处注明）；
+- 改动后附运行方式与预期输出。
+
+## 输出
+
+脚本 + 每段作用注释 + 风险点说明。

package/skills-lib/changelog/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: changelog
+description: 变更日志与发布说明写作
+---
+
+# 变更日志与发布说明
+
+整理版本变更、写 CHANGELOG 或发布公告时使用。
+
+## 规则
+
+1. 格式用 Keep a Changelog（[SemVer](https://semver.org)）：按版本分组，类别固定为 新增/修复/变更/移除/弃用。
+2. 条目面向用户价值：「修复了 X 导致的 Y」而非「改了第 42 行」；每条一行，可附 PR 号。
+3. 版本号遵循语义化版本；破坏性变更放最前并加粗标出。
+4. 发布说明（给用户看的）：新功能一句话价值 + 迁移提示 + 已知问题。
+
+## 检查点
+
+- 从提交记录反推时按用户视角重写，不复制 commit message；
+- 未发布的条目放 [Unreleased] 区，发布日期与实际发布一致。
+
+## 输出
+
+「CHANGELOG 条目 + 一段式发布说明」。

package/skills-lib/ci-cd/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: ci-cd
+description: CI/CD 流水线设计与故障排查（GitHub Actions/GitLab CI/自建）
+---
+
+# CI/CD 流水线
+
+设计或排查持续集成/部署流水线时使用。
+
+## 步骤
+
+1. 确认平台（GitHub Actions / GitLab CI / Jenkins 等）与触发时机。
+2. 设计流水线：构建 → 测试 → 静态检查 → 打包 → 部署，每阶段独立、可重入。
+3. 环境：锁定依赖版本、缓存构建产物、密钥走平台 Secret 不写进配置。
+4. 排查失败：读完整日志定位首个错误，先本地复现再改流水线，避免反复提交试错。
+
+## 检查点
+
+- 配置里不出现明文密钥；产物不含 .env / credentials；
+- 部署步骤默认「先备份/可回滚」；生产部署加人工确认或灰度；
+- 流水线尽量快：并行化、按变更路径跳过无关任务。
+
+## 输出
+
+「流水线配置文件 + 每阶段说明 + 本地验证方式」。

package/skills-lib/data-analysis/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: data-analysis
+description: 数据分析（CSV/统计汇总/图表建议）
+---
+
+# 数据分析
+
+对 CSV / Excel / 日志等数据做统计、聚合、洞察或可视化建议时使用。
+
+## 步骤
+
+1. 先探数据：文件格式、行数、字段与类型、缺失值比例（head + 统计摘要）。
+2. 明确分析目标（趋势/对比/分布/异常），再选方法，避免无目的统计。
+3. 计算：先聚合（分组求和/均值/分位数），再交叉对比；注意脏数据（空值、单位不一致）。
+4. 图表建议：趋势→折线、占比→饼/堆叠条、分布→直方图、相关→散点。
+5. 结论：每条数字结论注明口径（样本量、时间范围）。
+
+## 检查点
+
+- 不编造数据；算不了就说缺什么；
+- 大文件流式处理，避免一次性载入内存（可用 awk/sort 预聚合）。
+
+## 输出
+
+「数据概览 → 关键发现（数字+口径）→ 图表建议 → 结论与行动建议」。

package/skills-lib/database-design/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: database-design
+description: 数据库表结构设计（建模/范式/索引）
+---
+
+# 数据库表结构设计
+
+设计新表、评估现有表结构时使用。
+
+## 步骤
+
+1. 先梳理实体与关系：一张图（ER）胜过一段文字，明确 1:1 / 1:N / N:N。
+2. 建模：主键自增或业务键（注明取舍）；外键显式声明；枚举/状态用可读字符串或注释完整。
+3. 范式：满足第三范式（消除冗余），除非查询性能要求明确的冗余（注明理由）。
+4. 索引：主键外所有查询条件列建索引；复合索引按「等值在前、范围在后」排序。
+5. 演进：字段加注释、预留软删除字段（deleted_at）与时间戳（created_at/updated_at），迁移可回滚。
+
+## 检查点
+
+- 数据类型选最小够用（INT vs BIGINT、VARCHAR 长度）；
+- 给出建表 DDL 与回滚 DDL 成对输出。
+
+## 输出
+
+「ER 描述 → DDL（含注释）→ 索引与理由 → 迁移方案」。

package/skills-lib/docs/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: docs
+description: 技术文档写作（结构/语气/受众）
+---
+
+# 技术文档写作
+
+写架构说明、使用手册、API 文档、设计文档时使用。
+
+## 规则
+
+1. 先定受众与场景：新手教程/参考手册/设计决策，语气与深度不同，开篇一句话点明本文解决什么问题。
+2. 结构：概述 → 快速开始（最短可运行示例）→ 详细说明 → 常见问题；长文档有目录。
+3. 术语统一：同一概念全文同一名称；首次出现的缩写给出全称。
+4. 示例优先：每个概念配可运行的代码示例；命令给出输入与预期输出。
+5. 中文排版：中英文之间加空格、代码用反引号、标题层级不跳级。
+
+## 检查点
+
+- 不写「显然/大家知道」跳过关键步骤；写完自检：读者照做能成功吗？
+- 过时内容立即更新或标注废弃。
+
+## 输出
+
+结构化 Markdown 文档。

package/skills-lib/email/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: email
+description: 邮件写作（主题/结构/语气，中英文）
+---
+
+# 邮件写作
+
+起草工作邮件、回复或审阅邮件草稿时使用。
+
+## 规则
+
+1. 主题先行：一句话概括目的+事项（如「【请确认】周会上线方案（周五前）」），忌空泛主题。
+2. 结构：称呼 → 一句话来意 → 背景（对方需要的上下文）→ 具体事项（分点）→ 明确行动与时限 → 落款。
+3. 语气：对上级简洁有结论（结论先行）；对外部正式；对同事直接；敏感话题（拒绝/催办）委婉但明确。
+4. 长度：正文 ≤ 10 句；附件与长文用链接代替。
+5. 英文邮件：商务常用开头结尾，避免直译，不用情绪化措辞。
+
+## 检查点
+
+- 收件人、抄送、附件与文中所述一致；日期/时间/金额/链接核对无误；
+- 提供「正式版 + 简短版」两个版本供选择。
+
+## 输出
+
+主题 + 正文（注明语气与可替换的占位符）。

package/skills-lib/file-organize/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: file-organize
+description: 文件整理与归档（分类/重命名/去重/目录规范）
+---
+
+# 文件整理与归档
+
+整理杂乱目录、批量重命名、去重或设计目录结构时使用（办公/个人资料通用）。
+
+## 步骤
+
+1. 先盘点不动手：按类型/大小/修改时间统计，列出文件清单与占用。
+2. 设计目标结构：按「类型/日期/项目/用途」选主维度，层级 ≤ 3 层，命名统一（如 `2026-08-21_报告_v2.pdf`）。
+3. 执行前给出方案让用户确认，然后：
+   - 批量重命名：规则先行（去空格、补日期前缀、统一大小写），用脚本执行并保留原文件名映射表；
+   - 去重：按内容哈希（md5/sha256）识别重复文件，只列清单不自动删除；
+   - 归档：旧文件移入 `archive/2026/` 之类，压缩大目录。
+4. 收尾：更新映射表（原名 → 新名），关键目录放一个 `说明.txt` 记录规则。
+
+## 检查点
+
+- 任何删除/覆盖动作先给清单并等确认，默认只「移动」不「删除」；
+- 不整理系统目录/程序目录，只处理用户指定的范围。
+
+## 输出
+
+「盘点结果 → 目录方案 → 执行脚本 → 变更映射表」。

package/skills-lib/git-workflow/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: git-workflow
+description: Git 团队协作工作流（分支/PR/合并/冲突解决/回滚）
+---
+
+# Git 团队协作工作流
+
+任务涉及分支管理、Pull Request、合并、冲突或回滚时使用。
+
+## 步骤
+
+1. 先 `git status` / `git log --oneline -10` 了解现状，不猜测。
+2. 功能开发：新分支命名 `feat/<描述>`，修复 `fix/<描述>`（kebab-case）。
+3. 提交粒度：一次提交只做一件事；提交信息用约定式提交（参考 git-commit 技能）。
+4. 合并前先 `git fetch` 再对比 `origin/main`，有分歧先 rebase/merge 解决。
+5. 冲突解决：逐文件查看 `<<<<<<<` 标记，保留双方意图，解决后 `git add` 再完成合并。
+
+## 检查点
+
+- 不直接向 main/master 提交（除非用户明确要求）；
+- 不执行 `git push --force` 到共享分支；
+- 危险操作（reset --hard、删除远程分支）先说明后果并等确认。
+
+## 输出
+
+给出「现状 → 建议步骤 → 已执行命令与结果」，每步命令附一句说明。

package/skills-lib/i18n/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: i18n
+description: 国际化与本地化改造（多语言文案/格式/提取流程）
+---
+
+# 国际化与本地化
+
+给项目加多语言支持或整理翻译文案时使用。
+
+## 步骤
+
+1. 盘点：找出硬编码文案（UI 字符串、错误消息、提示），确认框架的 i18n 方案。
+2. 提取：文案进资源文件（key 用语义命名如 `login.failed`，不用 UI 原文做 key）；带变量的用占位符 `{count}`。
+3. 格式本地化：日期/数字/货币/复数规则用库处理（如 Intl），不手写拼接。
+4. 翻译：先翻英文再翻其他语言；术语表统一（同一概念全项目同一译法）；翻译后逐屏走查截断问题。
+
+## 检查点
+
+- 新增文案必须同步更新全部语言文件，缺失项标出；
+- 占位符与转义在各语言文件保持一致，给出校验方式。
+
+## 输出
+
+「改造方案 → 资源文件内容 → 术语表 → 验证清单」。

package/skills-lib/markdown/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: markdown
+description: Markdown 排版规范（标题/列表/表格/代码块/中英文间距）
+---
+
+# Markdown 排版规范
+
+编写或规范 Markdown 文档时使用。
+
+## 规则
+
+1. 标题层级不跳级（# → ## → ###），同级标题风格一致；文档只有一个一级标题。
+2. 列表：同类用同一种符号；有序列表序号正确；列表项之间空行按渲染器习惯处理。
+3. 代码：行内代码用反引号，代码块注明语言（` ```js `）；命令附输入输出。
+4. 表格：列对齐、表头简洁，长表格优先用列表替代。
+5. 中文排版：中英文之间加空格、中文用全角标点、链接文字有意义（不用「点击这里」）。
+6. 图片有替代文字；链接目标可访问；emoji 适度不喧宾夺主。
+
+## 检查点
+
+- 全文 lint：标题层级、闭合的代码块、表格列数、死链；
+- 渲染目标（GitHub/本地编辑器）差异处注明。
+
+## 输出
+
+规范后的 Markdown 全文 + 修改点列表。

package/skills-lib/meeting-notes/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: meeting-notes
+description: 会议纪要整理（结构化/决议/待办）
+---
+
+# 会议纪要
+
+根据会议记录/逐字稿整理纪要时使用。
+
+## 结构
+
+1. 基本信息：会议主题、时间、参会人、主持人。
+2. 核心结论：3–5 条，按重要性排序，写「决定了什么」而非过程复述。
+3. 讨论要点：按议题分组，保留关键分歧与依据，每条 1–2 行。
+4. 待办事项：任务/负责人/截止时间 三列齐全；不明确的标「待定」并注明跟进人。
+5. 遗留问题：未决事项单独列出，注明下次讨论时间。
+
+## 检查点
+
+- 区分「事实」与「观点」，发言人模糊的信息标注为待确认；
+- 用词客观中立，不加入会议外的主观评价。
+
+## 输出
+
+结构化 Markdown 纪要 + 一份「一句话摘要」。

package/skills-lib/nodejs/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: nodejs
+description: Node.js/JavaScript 编码规范与最佳实践
+---
+
+# Node.js 编码规范
+
+写/改/审查 Node.js 或前端 JavaScript 代码时使用。
+
+## 规则
+
+1. 现代语法：`const`/`let`（不用 `var`）、箭头函数、async/await 代替回调嵌套、模板字符串。
+2. ESM 优先（`import`/`export`）；项目已有模块体系时保持一致。
+3. 错误处理：异步调用用 try/catch，Promise 链有 catch；回调风格只在与旧库交互时用。
+4. 安全：不 `eval` 用户输入、路径用 `path.join` 防穿越、`child_process` 用数组参数避免 shell 注入。
+5. 结构：纯函数优先、单文件职责单一、配置外置（环境变量）。
+6. 依赖克制：能用标准库就不用第三方包；锁定版本（lockfile）。
+
+## 检查点
+
+- 改动后给出运行/测试命令；
+- 不依赖全局变量与隐式魔法，函数输入输出可预测。
+
+## 输出
+
+代码 + 关键设计说明。