@huicai/cli 2026.714.0 → 2026.804.0

package/skills/dev-rust/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: dev-rust
+description: Rust 技术开发链（所有权心智与借用斗争止损→错误处理 thiserror/anyhow 分工→枚举建模"非法状态不可表示"→trait 对象 vs 泛型判据→tokio 异步(spawn_blocking/持锁 await/取消安全)→unsafe 最小化纪律→cargo workspace 与 feature 门→clippy 门禁→LTO 发布优化与编译时间治理→FFI 边界）。Rust 服务/CLI/性能组件开发、借用检查斗争、异步疑难时载入。
+version: 1.0.0
+---
+
+# Rust 技术开发链
+
+eng-develop 的 Rust 孙链。通则承 eng-develop,此处只写 Rust 特有判据。
+
+## 所有权心智与止损策略
+
+移动语义默认;借用二选一:多个共享借用 xor 一个可变借用;生命周期先让编译器推,报错再显式标注;
+**与借用检查器斗争超过 10 分钟=设计问题信号**,止损三招按序试:
+① 先 `clone()` 跑通再优化(正确性优先,画像后再抠热点);② 拆结构体(自引用/整体借用冲突→字段分组或方法只取所需字段);③ 集合内互引改索引(id 代替引用);
+共享所有权判据:单线程 `Rc<RefCell>`,跨线程 `Arc<Mutex/RwLock>`——用到就问一句"能不能重新设计所有权",大量出现=在用 Rust 写 Java。
+
+## 错误处理分工
+
+**库用 thiserror**(结构化枚举,调用方可 match);**应用用 anyhow**(`.context("read config")` 链路上下文);
+`?` 传播为主;`unwrap` 库代码禁,应用代码只许在"逻辑上不可能失败"处且**用 `expect("为什么不可能失败")` 写明理由**;
+`Option`/`Result` 组合子(map/and_then/ok_or)优先 if-let 嵌套;
+main 返回 `anyhow::Result<()>`,错误链完整打印。
+
+## 类型建模
+
+**非法状态不可表示**:枚举替布尔组合(`enum State { Connecting, Connected(Conn), Closed }` 而非三个 bool);
+newtype 封装约束(`UserId(u64)` 防参数窜位);
+derive 默认全家桶:`Debug, Clone`,公共类型加 `PartialEq`,配置类加 `serde`;
+trait 对象 vs 泛型判据:异构集合/插件式用 `dyn`(运行时开销小于编译膨胀),热路径/内联需求用泛型;公共 API 少暴露复杂泛型签名。
+
+## 异步（tokio）
+
+async 传染性认知:一处 async,调用链全 async(边界处 block_on 只许在最外层);
+**两大红线**:async 里做重 CPU(独占 worker→`spawn_blocking`)/持 `std::sync::Mutex` 跨 `.await`(死锁与全 runtime 卡)——临界区缩到 await 之前,或换 `tokio::sync::Mutex`(慢,先考虑缩临界区);
+取消安全:`select!` 分支被取消时未完成的 future 被丢弃——有副作用的操作(已发半个请求)要考虑取消后果;
+结构化并发 `JoinSet`(统一收割,散养 spawn 的 panic 无人知);
+每个外部 IO 带 timeout(`tokio::time::timeout`);运行时单例(嵌套 block_on=panic)。
+
+## unsafe 纪律
+
+能不用则不用(先找 safe 轮子);必用则:**最小化块范围**+`// SAFETY:` 注释写清依赖的不变量+封进 safe API(调用者无需 unsafe);
+`unsafe` 块 PR **双人评审**(eng-develop 评审加严);miri 跑测试(UB 检测);
+FFI 与性能是仅有的两个正当理由,"绕过借用检查器"不是理由。
+
+## cargo 工程
+
+workspace 统一依赖版本(`[workspace.dependencies]`)与 lint 配置;
+feature 门:默认精简(`default` 最小集),可选功能显式开;**feature 组合爆炸**要 CI 抽查关键组合(`--no-default-features` 至少常跑);
+依赖审计:`cargo audit`(漏洞,eng-security)+`cargo deny`(许可证/重复版本/来源白名单);
+`cargo tree -d` 查重复版本(编译时间与体积双害)。
+
+## clippy / fmt
+
+`cargo clippy -- -D warnings` 入 CI 红灯不合入;pedantic 组选择性开(全开=噪音);
+`#[allow]` 必须带理由注释(裸 allow 评审拦);rustfmt 默认配置少动(dev-toolchain 格式化零争论)。
+
+## 测试
+
+单测同文件 `#[cfg(test)] mod tests`(可测私有项);集成测试 `tests/`(只走公共 API);
+**文档测试**:示例即测试(```rust 块会被跑,文档永不腐烂——库必写);
+proptest/quickcheck 判据:解析器/编解码/不变量验证(roundtrip:encode(decode(x))==x);
+异步测试 `#[tokio::test]`;时间用 `tokio::time::pause` 虚拟推进(不真睡)。
+
+## 性能与编译
+
+**性能结论只看 release**(debug 慢 10–100 倍,拿 debug 数据谈优化=闹笑话);
+发布档:`lto = "thin"`(或 fat)+`codegen-units = 1`+`strip = true`;panic=abort 判据(体积敏感且无捕获需求);
+画像:criterion 基准+flamegraph;分配热点:clone 滥用/`String` 拼接(`&str`/`Cow` 化)/collect 中间集合(迭代器链到底);
+编译时间治理:增量开发档/mold-lld 链接器/大 crate 拆分/泛型改 dyn 减单态化膨胀——**编译慢也是债**(dev-toolchain 构建预算同拍)。
+
+## FFI 边界
+
+方向判据:导出给 C 用 cbindgen,绑定 C 库用 bindgen;
+边界三原则:C ABI(`extern "C"` + `#[repr(C)]`)/所有权明确(谁分配谁释放,跨界指针写清约定)/**panic 不许穿越 FFI**(边界处 `catch_unwind` 转错误码);
+字符串成本:CString/CStr 转换与生命周期(悬垂第一高发区)。
+
+**作业包**:`references/cargo-ci-snippets.md`(发布档 profile/workspace 统一/CI 门禁序(clippy -D/audit/deny/特性组合抽查)复制即用)。
+
+## 使用纪律
+
+clippy 红灯不合入;unsafe 双人评审+SAFETY 注释;
+性能数据必附 release+基准条件(eng-performance 基准纪律);
+每次与借用检查器的"高价值斗争"回写止损案例(本链心智库)。

package/skills/dev-rust/references/cargo-ci-snippets.md

@@ -0,0 +1,50 @@
+# Rust 工程配置片段（dev-rust 落笔件:复制即用）
+
+## 1. 发布档 profile(Cargo.toml)
+
+```toml
+[profile.release]
+lto = "thin"          # 或 "fat":更慢更小更快,基准后定
+codegen-units = 1
+strip = true
+# panic = "abort"     # 体积敏感且无捕获需求才开
+
+[profile.dev]
+# 开发档默认即可;编译慢先治依赖与拆 crate,别牺牲 debug 体验
+```
+
+## 2. workspace 统一(根 Cargo.toml)
+
+```toml
+[workspace]
+members = ["crates/*"]
+resolver = "2"
+
+[workspace.dependencies]   # 版本统一声明,成员用 dep.workspace = true
+serde = { version = "1", features = ["derive"] }
+
+[workspace.lints.clippy]
+unwrap_used = "warn"       # 库代码禁 unwrap 的执行面
+```
+
+## 3. CI 门禁序(cicd-pipeline 快慢分离)
+
+```sh
+cargo fmt --check                      # 秒级
+cargo clippy --all-targets -- -D warnings   # 红灯不合入
+cargo test --workspace
+cargo doc --no-deps                    # 文档测试跟 test 跑;doc 链接坏也拦
+cargo audit                            # 漏洞(eng-security SCA)
+cargo deny check licenses bans         # 许可证与重复版本
+# 抽查特性组合(组合爆炸,至少常跑):
+cargo check --no-default-features
+cargo check --all-features
+```
+
+## 4. 评审速扫
+
+- [ ] 库 thiserror/应用 anyhow;expect 带"为什么不可能失败"
+- [ ] async 里无重 CPU(spawn_blocking)与持 std Mutex 跨 .await
+- [ ] unsafe 块最小化+SAFETY 注释+双人评审;miri 跑过
+- [ ] 枚举建模状态(非法状态不可表示);pub 面上无复杂泛型泄漏
+- [ ] 热路径 clone/String 拼接审过(&str/Cow);性能结论只看 release

package/skills/dev-toolchain/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: dev-toolchain
+description: 通用开发工具链（Git 进阶工作流与提交粒度→通用调试方法论(二分/最小复现)→构建可重现与缓存治理→包管理私服与国内镜像→Lint/Format 统一→pre-commit 秒级门禁→效率工具箱→AI 结对纪律）。开发子链的语言无关工具底座:配新环境、治理仓库工程化、构建慢、工具链混乱时载入。
+version: 1.0.0
+---
+
+# 通用开发工具链
+
+eng-develop 的工具底座孙链,语言无关;语言专属工具(mvn/uv/cargo…)见各语言链。
+工程化及格线:**新人半天能跑通构建与测试**——超过半天,治理这条链。
+
+## Git 进阶
+
+- 提交粒度:一提交一意图,可独立构建、可独立回滚;禁"攒一周一把梭"与"WIP 直接进主干";
+- 提交前整理:交互式 rebase 把过程碎提交压成"评审者视角的故事线"(**push 前整理,push 后禁改共享分支历史**;force push 只许在自己的分支且用 --force-with-lease);
+- 定位回归:`git bisect` 二分嫌疑提交(配一个可脚本化的复现命令,几十个提交 7 步定位);
+- 并行任务:`git worktree` 同仓多目录(改 A 分支时来了紧急 fix,不必 stash 大挪移);
+- 后悔药:`git reflog` 找回"消失"的提交(reset --hard 后先别慌);
+- .gitignore 分层:全局(IDE/系统文件)+项目(构建产物);**误提交的密钥按已泄露处置**(eng-security),不是删文件了事;
+- 大文件:二进制资产走 LFS 或制品库,仓库里出现 >10MB 文件要拦(pre-commit)。
+
+## 分支与保护
+
+命名 `feature|fix|hotfix|chore/工单号-简述`;主干保护:必过 CI+至少一人评审+禁直推;
+分支寿命目标 <3 天(长寿分支=合并地狱,eng-release 策略judgment)。
+
+## 通用调试方法论（语言细则见各链画像节）
+
+1. **最小复现优先**:能稳定复现的 bug 已解决一半;复现不了先加观测(eng-observability)别盲改;
+2. **二分法三用**:版本二分(bisect)/代码二分(注释掉一半)/数据二分(半量输入)——嫌疑空间每次砍半;
+3. 断点进阶:条件断点(循环第 1000 次才停)/日志断点(不停不重启打变量)——比改代码加 print 再重启快十倍;
+4. 橡皮鸭法:向人(或 AI)完整复述问题,三成在复述中自愈;
+5. **改一处验一处**:同时改三处修好了=什么都没学到,下次还犯;
+6. 根因流程走 debug-root-cause(假设-验证法,变更嫌疑第一问)。
+
+## 构建可重现与缓存
+
+- 可重现三锁:锁依赖(lockfile 必提交)/锁工具链版本(Node/JDK/Python 版本声明进仓库:.nvmrc、.tool-versions 等)/锁构建环境(容器化构建)——"我机器上是好的"病根就是三锁缺一;
+- 缓存分层:本地增量+CI 远端缓存(依赖缓存按 lockfile 哈希为键);
+- **构建时间预算 10 分钟**:超了治理(并行化/模块拆分/缓存命中率先查),构建慢=所有人排队交税;
+- 构建脚本入库(Makefile/justfile/npm scripts 统一入口:`make build test lint` 三件套人人一致)。
+
+## 包管理与私服
+
+- 统一私服代理(npm/PyPI/Maven/Go proxy 一站式):加速、审计、防投毒白名单(eng-security 供应链)、断网可用;
+- 国内镜像要点:公司私服优先;个人环境配主流镜像源并**留意镜像同步延迟**(刚发布的包镜像可能还没有,报 404 先想到这一层);
+- 版本策略:应用锁死(lockfile 精确)、库宽松(range 声明);升级集中走 dependency-upgrade 不零敲碎打。
+
+## Lint / Format 统一
+
+- 格式化交给工具零人工(prettier/gofmt/rustfmt/spotless…):**评审里争论空格=集体时薪浪费**,.editorconfig 全仓统一;
+- lint 渐进纪律:新增代码严格(增量门禁)、存量分批清(一次性全量修=巨型 PR 灾难);
+- 规则改动走评审与公示,不是个人偏好战场;禁用规则要写理由注释(裸 disable 门禁拦)。
+
+## pre-commit 秒级门禁
+
+本地钩子只放**秒级**检查:格式化、lint 增量、密钥扫描、大文件拦截、裸 TODO 拦截(要挂工单号);
+**作业包**:`scripts/secret-scan.sh`(零依赖密钥扫描:私钥头/云 AK/JWT/连接串带密码/webhook 七类规则,默认扫 git 暂存区,`--install-hook` 一键装钩子;误报走 secretscan:allow 注释或 .secretscan-ignore);
+分钟级(全量测试/构建)放 CI——**门禁快才有人遵守,慢门禁必被 --no-verify**;
+钩子配置入库(团队一键安装),新人 clone 完即生效。
+
+## 效率工具箱（按需配备）
+
+终端复用(tmux)/模糊查找(fzf)/更快的搜索(ripgrep)/JSON 处理(jq)/HTTP 调试(curl/httpie+可入库的 .http 文件);
+**三次法则**:同一手工操作干到第三遍就脚本化,脚本入库共享;周期性的进一步例程化(office-automation);
+个人 dotfiles 与项目模板仓库化——环境是资产不是缘分。
+
+## AI 结对纪律（与 eng-develop 总则同拍,此处为工具视角）
+
+上下文喂足(相关文件/惯例/约束)再要产出;产出逐行读懂才提交;
+测试先行让 AI 补实现;边界条件(空/极值/并发/权限)亲自过;
+密钥与内部数据不出内网;**AI 是加速器不是责任主体——署你名的代码你负责**。
+
+## 使用纪律
+
+工具链配置一切入库(钩子/编辑器配置/脚本/模板),口头约定=没有约定;
+每次"环境问题"浪费半天以上→回写:补进模板或文档,让下一个人 5 分钟绕过;
+季度巡检:构建时长/缓存命中率/新人上手时长三个数,恶化即治理。

package/skills/dev-toolchain/scripts/secret-scan.sh

@@ -0,0 +1,83 @@
+#!/bin/sh
+# 敏感信息扫描（dev-toolchain pre-commit 秒级门禁件;eng-security"密钥不入库"的本地防线）。
+# 零依赖(POSIX grep -E);离线可用。规则求准不求全——低误报才有人真用(门禁快才有人遵守)。
+# 用法:
+#   sh secret-scan.sh                 # 扫 git 暂存区(pre-commit 姿势);非 git 目录则扫当前目录
+#   sh secret-scan.sh <路径...>       # 扫指定文件/目录
+#   sh secret-scan.sh --install-hook  # 安装为本仓库 pre-commit 钩子
+# 豁免: 项目根放 .secretscan-ignore,每行一个 grep -E 正则(匹配"文件路径"即跳过);误报也可行内加注释 secretscan:allow
+# 退出码: 0=干净 1=发现嫌疑(pre-commit 即阻断) 。发现真密钥的处置=已泄露流程(吊销重发),不是删了重提交!
+
+PATTERNS='
+私钥文件头:-----BEGIN (RSA |EC |OPENSSH |DSA )?PRIVATE KEY-----
+云AK_阿里系:LTAI[A-Za-z0-9]{12,24}
+云AK_AWS系:AKIA[0-9A-Z]{16}
+云AK_腾讯系:AKID[A-Za-z0-9]{13,20}
+JWT令牌:eyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}
+连接串带密码:(mysql|postgres(ql)?|redis|mongodb(\+srv)?|amqp)://[^/@ "'"'"']+:[^/@ "'"'"']{4,}@
+通用赋值:(password|passwd|secret|api_?key|access_?key|private_?key|token)["'"'"']?[[:space:]]*[:=][[:space:]]*["'"'"'][A-Za-z0-9_/+.-]{12,}["'"'"']
+钉钉企微webhook:(oapi\.dingtalk\.com/robot/send\?access_token=|qyapi\.weixin\.qq\.com/cgi-bin/webhook/send\?key=)[a-z0-9-]{20,}
+'
+EXCLUDE_PATH='(^|/)(node_modules|dist|build|target|vendor|\.git|__pycache__)(/|$)|\.(lock|min\.js|map|png|jpg|jpeg|gif|ico|pdf|zip|gz|jar|woff2?)$|package-lock\.json|pnpm-lock\.yaml'
+
+if [ "$1" = "--install-hook" ]; then
+  [ -d .git ] || { echo "不在 git 仓库根目录"; exit 2; }
+  SELF=$(cd "$(dirname "$0")" && pwd)/$(basename "$0")
+  mkdir -p .git/hooks
+  printf '#!/bin/sh\nexec sh "%s"\n' "$SELF" > .git/hooks/pre-commit
+  chmod +x .git/hooks/pre-commit
+  echo "已安装 pre-commit 钩子 → .git/hooks/pre-commit(团队共享请入库钩子配置,dev-toolchain)"
+  exit 0
+fi
+
+# 组装待扫文件清单
+LIST="/tmp/.sscan_$$"
+if [ $# -gt 0 ]; then
+  for p in "$@"; do
+    if [ -d "$p" ]; then find "$p" -type f 2>/dev/null; else echo "$p"; fi
+  done > "$LIST"
+elif command -v git >/dev/null 2>&1 && git rev-parse --git-dir >/dev/null 2>&1; then
+  git diff --cached --name-only --diff-filter=ACM 2>/dev/null > "$LIST"
+  [ -s "$LIST" ] || { echo "(暂存区为空,无可扫内容;扫全目录用: sh secret-scan.sh .)"; rm -f "$LIST"; exit 0; }
+else
+  find . -type f 2>/dev/null > "$LIST"
+fi
+
+IGN=".secretscan-ignore"
+HITS=0
+TMP_HIT="/tmp/.sscan_hit_$$"
+: > "$TMP_HIT"
+
+while IFS= read -r f; do
+  [ -f "$f" ] || continue
+  echo "$f" | grep -qE "$EXCLUDE_PATH" && continue
+  [ -f "$IGN" ] && grep -qE -f "$IGN" 2>/dev/null <<EOF && continue
+$f
+EOF
+  # 跳过二进制(grep -I);逐规则扫;行级豁免:显式 allow 注释 + 明显占位值(xxx/changeme/<host> 等,
+  # 实战回写 2026-07:文档示例密钥误报——占位值不报,但"真实格式的假密钥"仍会报,示例请用明显假值)
+  echo "$PATTERNS" | while IFS=: read -r name re; do
+    [ -z "$name" ] && continue
+    grep -nIE "$re" "$f" 2>/dev/null | grep -v 'secretscan:allow' \
+      | grep -viE 'xxx|changeme|placeholder|your[-_](key|secret|token)|<[^>]{1,30}>|示例|占位|\bexample\b' \
+      | head -3 | while IFS= read -r line; do
+      echo "[$name] $f:$(echo "$line" | cut -c1-160)" >> "$TMP_HIT"
+    done
+  done
+done < "$LIST"
+
+if [ -s "$TMP_HIT" ]; then
+  HITS=$(wc -l < "$TMP_HIT" | tr -d ' ')
+  echo "==== 发现 $HITS 处敏感信息嫌疑 ===="
+  cat "$TMP_HIT"
+  echo ""
+  echo "处置三选一:"
+  echo "  1) 真密钥 → 按已泄露处理:吊销重发+挪密钥服务(eng-security'入过历史=已泄露',删提交救不了);"
+  echo "  2) 误报   → 行尾加注释 secretscan:allow,或路径正则进 .secretscan-ignore(要评审);"
+  echo "  3) 示例值 → 改成明显假值(xxx/changeme),别用真实格式的假密钥(下次还报)。"
+  rm -f "$LIST" "$TMP_HIT"
+  exit 1
+fi
+rm -f "$LIST" "$TMP_HIT"
+echo "扫描通过(规则求准不求全——全史扫描与 SCA 由 CI 层承接,cicd-pipeline/eng-security)"
+exit 0

package/skills/doc-chain/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: doc-chain
+description: Word 文档技能链总控（文体路由→模板→分章生产→合成→评审比对→定稿归档全链、长报告/多人协作/文档生命周期三条端到端工作流）。当用户要写"正式文档"而文体未定，或诉求跨环节（"30 页报告从调研到定稿"）时先载入。
+version: 1.0.0
+---
+
+# Word 文档技能链总控
+
+## 文体路由表（先定体裁再动笔）
+
+| 文体 | 典型产出 | 技能 |
+|---|---|---|
+| 党政/企业公文 | 请示/报告/通知/函/纪要 | **gov-document** |
+| 商务报告 | 分析报告/可研/白皮书 | docx-author + 领域技能供内容 |
+| 会议文书 | 纪要/行动项跟踪 | meeting-minutes |
+| 合同法律文书 | 合同/审查意见/诉讼文书 | legal-contract / litigation-support |
+| 学术文书 | 论文/开题/rebuttal | academic-writing |
+| 制度与 SOP | 管理制度/操作规程 | knowledge-sop / risk-compliance |
+| 翻译件 | 双语对照/净版 | translation-pro |
+| 邮件函件 | 商务往来/催办/声明 | email-writing / pr-comms |
+| 申报材料 | 申报书/标书 | project-proposal / tender-bidding |
+
+## 通用生产线（六步，30 页以上必须走全）
+
+1. **大纲评审**：章节树+每章一句话要点+预估篇幅,**确认后再写**（返工最贵的是结构性返工）;
+2. **素材归集**：调研输入（长文档 long-doc-analysis 笔记法,带出处）、数据（data-chain 口径,
+   图表 data-analysis 规范）、引用清单（来源可核,academic 纪律通用）;
+3. **分章生产（防截断的关键）**：每章独立 `章节-NN.md`（write_file append 分段）——
+   Markdown 中转是本平台长文档的标准姿势;交叉引用先用占位符（[见第X章]）;
+4. **合成**：md 合并 → docx-author 的 md_to_docx（封面/目录域/页码/中文字体一次到位）;
+   合成后**交叉引用与编号核对**（占位符清零、图表编号连续、目录刷新提示）;
+5. **评审回合**：初稿 → 批注意见归一（冲突意见找定稿人裁决,brand-design 评审纪律同源）→
+   修订 → **doc-compare 出变更清单**给评审人复核（改了什么一目了然,别让人重读全文）;
+6. **定稿与归档**：版本命名规范（`文档名-vN.N-YYYYMMDD`,草稿/送审/定稿态标注）;
+   定稿 PDF 化防误改;归档进知识库（knowledge-sop 元数据:负责人/评审日期）。
+
+## 端到端工作流
+
+### ① 长报告生产链（30–100 页级）
+选题与大纲（领域技能供框架:可研=project-proposal 十章/研报=securities-research）→
+调研（long-doc-analysis 多文档对照矩阵）→ 分章写作（todo_write 跟踪,每章过领域验收清单）→
+数据与图表批量生成 → 合成与一致性核对（**全书数字一致性**:同一指标各处相同,
+项目申报的数字核对纪律通用）→ 评审两轮 → 定稿三件套（docx+PDF+摘要版）。
+
+### ② 多人协作文档链
+模板与分工表（章节×负责人×截止,project-management 跟踪）→ 风格对齐页
+（术语表+语调+格式约定,先发后写）→ 各自产出 md → 合稿（顺序合并+风格统一改写）→
+**术语一致性扫描**（translation-pro 的扫描法内用）→ 评审定稿。
+
+### ③ 文档生命周期链（制度/范本类）
+起草（knowledge-sop 可执行标准）→ 会签（意见归一台账）→ 发布（版本 v1.0+生效日期）→
+执行反馈收集 → 年度评审（过期文档巡检）→ 修订（**doc-compare 新旧对照表随修订稿发布**——
+让执行者 30 秒看懂改了什么）→ 废止归档（保留历史版本可追溯）。
+
+## 使用纪律
+
+先大纲后正文;长文一律 md 中转分章;修订必附变更清单;数字与引用可溯源;
+敏感文档外发前过脱敏确认（data-governance 清单）。

package/skills/doc-compare/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: doc-compare
+description: 文档比对与红线（合同版本比对、范本偏离检查、多方案差异表）。当用户说"比对两份文档/看改了哪里/和范本差在哪/红线版"时使用。
+version: 1.0.0
+---
+
+# 文档比对与红线（经 run_python，python-docx + difflib）
+
+## 场景分派
+
+| 场景 | 做法 |
+|---|---|
+| 两版 docx/文本改了哪 | `scripts/compare.py` 段落级 diff → 变更清单（新增/删除/修改 + 上下文） |
+| 合同 vs 范本偏离 | 先比对出变更清单，再逐条按 legal-contract 的条款清单定性（有利/不利/中性） |
+| 红线版交付 | 生成「变更清单.docx」（修改前/后对照表）——如实告知：这是**对照表式红线**，非 Word 修订模式 |
+| 多方案对比（>2 份） | 不做全文 diff；按维度建对照矩阵（long-doc-analysis 的矩阵法） |
+
+## 流程
+
+1. **统一底稿**：docx 直接读段落；pdf 先 read_document 全文转存 txt（告知：pdf 排版差异可能造成伪 diff）。
+2. **跑比对**：`read_skill_file` 读 `scripts/compare.py`，`compare_docx(a, b)` / `compare_text(a, b)` →
+   变更块列表（类型/位置/原文/新文），并 print 统计（N 处新增/M 处删除/K 处修改）。
+3. **降噪**：空白/标点全半角差异默认忽略（`normalize=True`）；页眉页脚编号类变更单独归组。
+4. **定性**（合同/制度类必做）：逐条标注影响——金额/期限/责任/权利义务变化优先级最高；
+   纯措辞变化归"编辑性修改"。
+5. **交付**：`变更清单.xlsx`（序号/位置/变更类型/原文/新文/影响定性/风险级）+ 摘要段
+   （一句话说清这版改动的实质）。
+
+## 边界与诚实
+
+- 段落级 diff 对**表格内容**变化不敏感：合同价格表类变更需单独读表核对并注明方法；
+- 扫描件 pdf 的 OCR 误差会制造伪差异——置信度低的差异标「待人工核对」;
+- 无法生成 Word 原生「修订模式」文件（需 Word 本体），提供对照表并说明。
+
+## 验收自查
+
+- [ ] 变更统计数与清单条数一致，无遗漏块（compare.py 的守恒断言通过）
+- [ ] 金额/日期/期限类变更全部人工复核过原文
+- [ ] 每条重要变更有影响定性，不止"改了"
+- [ ] 已说明比对方法与局限（尤其 pdf/表格）
+
+## 附件
+
+- `scripts/compare.py` — compare_docx / compare_text（归一化降噪、变更块合并、守恒断言）+ 清单落盘 to_xlsx；可直接执行自测

package/skills/doc-compare/scripts/compare.py

@@ -0,0 +1,93 @@
+# 文档比对（经 run_python 执行）：docx/纯文本 段落级 diff → 变更块清单（新增/删除/修改）。
+# 归一化降噪（空白/全半角标点）；守恒断言（原文段数 = 保留+删除+修改）。
+# 直接执行本文件 = 自测：现场造两版 docx 比对并断言。
+import difflib
+import re
+
+
+_PUNCT = str.maketrans({'，': ',', '。': '.', '；': ';', '：': ':', '！': '!', '？': '?',
+                        '（': '(', '）': ')', '“': '"', '”': '"', '‘': "'", '’': "'"})
+
+
+def _norm(s, normalize=True):
+    if not normalize:
+        return s
+    return re.sub(r'\s+', '', str(s)).translate(_PUNCT)
+
+
+def _paras_docx(path):
+    from docx import Document
+    doc = Document(path)
+    out = [p.text for p in doc.paragraphs if p.text.strip()]
+    for tb in doc.tables:  # 表格降级为行文本参与比对（并在报告注明方法局限）
+        for row in tb.rows:
+            t = ' | '.join(c.text.strip() for c in row.cells)
+            if t.strip(' |'):
+                out.append('[表] ' + t)
+    return out
+
+
+def compare_text(a_lines, b_lines, normalize=True):
+    """段落列表比对 → 变更块 [{type:'add'|'del'|'mod', pos, old, new}]。"""
+    na = [_norm(x, normalize) for x in a_lines]
+    nb = [_norm(x, normalize) for x in b_lines]
+    sm = difflib.SequenceMatcher(a=na, b=nb, autojunk=False)
+    changes = []
+    kept = 0
+    for tag, i1, i2, j1, j2 in sm.get_opcodes():
+        if tag == 'equal':
+            kept += i2 - i1
+        elif tag == 'delete':
+            for k in range(i1, i2):
+                changes.append({'type': 'del', 'pos': k + 1, 'old': a_lines[k], 'new': ''})
+        elif tag == 'insert':
+            for k in range(j1, j2):
+                changes.append({'type': 'add', 'pos': i1 + 1, 'old': '', 'new': b_lines[k]})
+        else:  # replace：按行配对，多余部分归增/删
+            n = max(i2 - i1, j2 - j1)
+            for k in range(n):
+                o = a_lines[i1 + k] if i1 + k < i2 else ''
+                w = b_lines[j1 + k] if j1 + k < j2 else ''
+                changes.append({'type': 'mod' if o and w else ('del' if o else 'add'),
+                                'pos': min(i1 + k, i2 - 1) + 1, 'old': o, 'new': w})
+    # 守恒断言：原文每段要么保留要么进了变更清单
+    covered = kept + sum(1 for c in changes if c['type'] in ('del', 'mod'))
+    assert covered == len(a_lines), f'守恒断言失败：{covered} != {len(a_lines)}'
+    stat = {t: sum(1 for c in changes if c['type'] == t) for t in ('add', 'del', 'mod')}
+    print(f"[compare] 原文 {len(a_lines)} 段 | 新增 {stat['add']} · 删除 {stat['del']} · 修改 {stat['mod']}")
+    return changes
+
+
+def compare_docx(a_path, b_path, normalize=True):
+    return compare_text(_paras_docx(a_path), _paras_docx(b_path), normalize)
+
+
+def to_xlsx(changes, out_path):
+    """变更清单落盘（配合 xlsx-analysis 的 write_styled 更佳；此处独立可用）。"""
+    import pandas as pd
+    label = {'add': '新增', 'del': '删除', 'mod': '修改'}
+    df = pd.DataFrame([{'序号': i + 1, '原文位置(段)': c['pos'], '类型': label[c['type']],
+                        '原文': c['old'], '新文': c['new'], '影响定性': ''} for i, c in enumerate(changes)])
+    df.to_excel(out_path, index=False)
+    print(f'[compare] 清单已落盘 {out_path}（{len(df)} 条，「影响定性」列待逐条填写）')
+    return out_path
+
+
+if __name__ == '__main__':
+    from docx import Document
+
+    def mk(path, paras):
+        d = Document()
+        for p in paras:
+            d.add_paragraph(p)
+        d.save(path)
+
+    mk('cmp_a.docx', ['第一条 合同总价为人民币 100 万元。', '第二条 交付期为 30 日。', '第三条 保密期五年。'])
+    mk('cmp_b.docx', ['第一条 合同总价为人民币 120 万元。', '第二条 交付期为 30 日。',
+                      '第三条 保密期五年。', '第四条 违约金按日千分之一。'])
+    ch = compare_docx('cmp_a.docx', 'cmp_b.docx')
+    kinds = sorted(c['type'] for c in ch)
+    assert kinds == ['add', 'mod'], kinds  # 100→120 为修改；第四条为新增
+    assert '120' in [c for c in ch if c['type'] == 'mod'][0]['new']
+    to_xlsx(ch, 'cmp_变更清单.xlsx')
+    print('OK compare.py')

package/skills/docx-author/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: docx-author
+description: 编写/生成 Word 文档（报告、周报、方案、纪要、总结）。当用户说"写个文档/Word/docx/报告/方案/会议纪要"且期望文件产物时使用。
+version: 1.0.0
+---
+
+# Word 文档生成（经 run_python 执行，python-docx 已随托管运行时就绪）
+
+## 流程
+
+1. **大纲先行**：先在回复里给出章节大纲（标题层级 + 每节要点），重要文档让用户确认再落盘。
+2. **内容走 Markdown 中转（防截断的关键）**：
+   - 用 write_file（长文加 `append=true` 分段）把全文写成 `草稿.md`——结构约定：`#`/`##`/`###` 标题、`-` 列表、`1.` 有序列表、`|` 表格、`**粗体**`、普通行=正文段落；
+   - `read_skill_file` 读本技能 `scripts/docx_doc.py`，执行 `md_to_docx('草稿.md', '产物.docx', title=..., author=...)` 一次转出成品——封面、目录域、页眉页脚页码、中文字体、标题样式全自动。
+   - 内容不长（<200 行）可跳过中转，直接在代码里用 helper 逐节构建。
+3. **验收（必做）**：`verify('产物.docx')` 重开打印标题树/段落数/表格数，并对照大纲检查无缺节。
+
+## 样式约定（docx_doc.py 已内置，别再手搓）
+
+- 中文字体：正文宋体、标题黑体（west=Calibri），经 `w:eastAsia` 正确设置——只设 `font.name` 中文不生效是最常见的坑。
+- 目录：插入的是 TOC **域**，首次打开 Word 会提示按 F9 更新——在文末提示用户这一点，不要伪造静态目录。
+- 页码：页脚"第 X 页 共 Y 页"域。
+- 表格：默认 `Table Grid` 网格样式 + 表头加粗。
+
+## 分析/总结既有文档
+
+- 读别人给的 docx/pdf：优先 `read_document`（平台解析，支持超长分段通读）；要精确到表格结构时再用 python-docx 遍历 `doc.tables`。
+- "总结成周报/纪要"类任务：先通读原文并列要点（在回复中），确认口径后再生成 docx。
+
+## 验收自查
+
+- [ ] 大纲与成品章节一一对应（verify 输出的标题树 print 过）
+- [ ] 目录域/页码已插入，且已提醒用户 Word 内按 F9 刷新目录
+- [ ] 中文在 Word 中字体正确（用了 helper 而非裸 add_paragraph）
+- [ ] 长文档没有因为单次工具参数过长被截断（走了 md 中转）
+
+## 附件
+
+- `scripts/docx_doc.py` — `md_to_docx()` Markdown→Word 转换（含封面/目录域/页脚页码/中文字体/表格）、`verify()` 重读校验；可直接执行自测