@huicai/cli 2026.804.0 → 2026.1019.0

package/skills/web-craft/trigger-cases.json

@@ -0,0 +1,14 @@
+{
+  "skill": "web-craft",
+  "cases": [
+    { "id": "pos-wedding", "prompt": "帮我开发一个婚礼邀请函H5，要好看，能发到微信里", "shouldTrigger": true },
+    { "id": "pos-landing", "prompt": "做一个有设计感的产品落地页网页", "shouldTrigger": true },
+    { "id": "pos-signup", "prompt": "给公司年会做一个活动报名页面", "shouldTrigger": true },
+    { "id": "pos-portfolio", "prompt": "做一个个人作品集网站，要高级一点", "shouldTrigger": true },
+    { "id": "pos-birthday", "prompt": "写一个生日请柬网页，发给朋友用", "shouldTrigger": true },
+    { "id": "neg-cwv", "prompt": "前端首屏慢，Core Web Vitals 怎么优化", "shouldTrigger": false },
+    { "id": "neg-slides", "prompt": "做一份发布会用的炫酷PPT", "shouldTrigger": false },
+    { "id": "neg-prd", "prompt": "帮我写一份产品需求文档PRD", "shouldTrigger": false },
+    { "id": "neg-vi", "prompt": "给品牌起个名字，做一套VI规范", "shouldTrigger": false }
+  ]
+}

package/skills/web-scraping/trigger-cases.json

@@ -0,0 +1,34 @@
+{
+  "skill": "web-scraping",
+  "intentionalOverlap": [
+    "crawl-chain"
+  ],
+  "cases": [
+    {
+      "id": "pos-1",
+      "prompt": "从网站采集数据，翻页增量怎么做",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-2",
+      "prompt": "深度爬取和 JS 渲染页怎么抓",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-3",
+      "prompt": "提取网页字段后清洗入库",
+      "shouldTrigger": true
+    },
+    {
+      "id": "neg-1",
+      "prompt": "搜一下最新消息，找几个信源",
+      "shouldTrigger": false,
+      "lexical": false
+    },
+    {
+      "id": "neg-2",
+      "prompt": "对接一个需要签名的 API",
+      "shouldTrigger": false
+    }
+  ]
+}

package/skills/web-search/SKILL.md

@@ -1,19 +1,20 @@
 ---
 name: web-search
 description: 网页搜索与信息检索（查询构造、多源交叉验证、结果甄别去重、网页内容分析与提炼、引用规范、搜索→抓取→分析闭环）。当用户说"搜一下/查资料/联网查/最新消息/找信源/调研某主题/分析这个网页/总结这篇文章"时使用。爬虫链之检索环。
-version: 1.1.0
+version: 1.2.0
 ---
 
 # 网页搜索与内容分析（爬虫链 · 检索环；采集见 web-scraping，全链见 crawl-chain）
 
-## 检索通道（按可用性择优）
+## 检索通道（只有一个：平台统一联网搜索）
 
-- **平台联网搜索**：所用智能体/模型开了联网搜索时优先用（结果带引用,最省事）;
-- **企业/用户自备搜索 API**：有 Bing/Google/SerpAPI 等 key 时用 curl / fetch_url 直连其 REST 接口
-  （key 走环境变量,勿硬编码勿回显;需签名的载入 api-integration）;
-- **公开搜索页兜底**：fetch_url 抓轻量搜索页（如 `https://html.duckduckgo.com/html/?q=关键词`）,
-  再 `links=true` 取结果链接——**频率克制（次数少、间隔≥2s），尊重对方 ToS**;被限流即停;
-- 定向检索常比通用搜索准：已知权威站直接站内查（官网/文档站/统计局/交易所/GitHub）。
+- **`web_search` 工具**：联网检索的唯一入口。走平台统一联网搜索（提供商与密钥由管理员在管理后台统一配置）,
+  结果抬头会注明由哪个提供商返回——引用时如实带上;
+- **不可用就如实说**：工具不在工具表里、或返回「已关闭 / 不可用」,说明本端联网搜索开关已关或平台未启用——
+  直接告诉用户（可在设置里打开「联网搜索」,CLI 输入 `/websearch on`）。**禁止**用 curl / fetch_url 直连
+  Bing / Google / SerpAPI 等搜索接口,也**禁止**抓 DuckDuckGo / 百度等搜索结果页兜底——那是绕过开关,等同联网搜索;
+- **定向抓取仍可用**：已知权威站点的具体页面（官网/文档站/统计局/交易所/GitHub）直接 fetch_url 抓,
+  定向抓取常比通用搜索更准。
 
 ## 查询构造（一次搜不准是常态，会迭代才是能力）
 
@@ -47,7 +48,7 @@ version: 1.1.0
 ## 搜索 → 抓取 → 分析闭环
 
 1. 明确要回答的问题（拆成 2-5 个可检索的子问题）;
-2. 逐子问题检索,收集候选信源（URL + 标题 + 日期）;
+2. 逐子问题用 web_search 检索,收集候选信源（URL + 标题 + 日期 + 提供商）;
 3. fetch_url/curl 抓正文,按上节「内容分析」降噪+提炼（web-scraping 处理批量/深爬）;
 4. 汇总输出：**每个关键结论标注来源（URL + 访问日期）**,冲突信息并列呈现并说明取舍;
 5. 信息不足时如实说"没查到/存疑"，绝不编造——宁缺毋滥。
@@ -64,4 +65,4 @@ version: 1.1.0
 - [ ] 关键事实 ≥2 独立信源印证;冲突已并列说明
 - [ ] 内容分析先降噪再提炼、先事实后观点;长文分块不丢尾
 - [ ] 信源分级意识：结论不建立在社区/自媒体单源上
-- [ ] 搜索页兜底通道频率克制;没查到的如实说明
+- [ ] 检索只经 web_search（不可用时如实告知,未绕道直连搜索接口或抓搜索结果页）;没查到的如实说明

package/skills/web-search/trigger-cases.json

@@ -0,0 +1,31 @@
+{
+  "skill": "web-search",
+  "cases": [
+    {
+      "id": "pos-1",
+      "prompt": "搜一下，查点资料",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-2",
+      "prompt": "联网查最新消息，找可靠信源",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-3",
+      "prompt": "这个网页帮我总结一下，做多源交叉验证",
+      "shouldTrigger": true
+    },
+    {
+      "id": "neg-1",
+      "prompt": "抓取这个网站做深度爬取",
+      "shouldTrigger": false,
+      "lexical": false
+    },
+    {
+      "id": "neg-2",
+      "prompt": "做一次技术选型的调研综述",
+      "shouldTrigger": false
+    }
+  ]
+}

package/skills/weekly-report/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: weekly-report
+description: 周报自动取数与成稿——扫本机多仓库 Git 提交、拉 TAPD 需求/缺陷/迭代/发布计划、扫版本库外的文档痕迹，按公司模板出片并体检。当用户说"写本周周报/生成周报/我这周干了啥/汇总我的工作"时使用。
+version: 1.0.0
+---
+
+# 周报（先把事实摆齐，再谈怎么写）
+
+周报写不好，九成不是文笔问题，是**手上没有事实**：凭印象回忆一周做了什么，
+写出来的必然是"持续推进平台建设"这类没法被追问的句子。所以顺序永远是
+**取证 → 归并 → 出片体检**，不能跳。
+
+## 一、取证（一次取齐，三个来源共用同一个汇报周期）
+
+调 **`work_evidence`** 一次拿全，不要分开调三次——三次各带一份 since/until，
+少写一个参数或把 `days:7` 和 `week:"this"` 混着用，拼出来的周报就会「提交数来自这一周、
+需求数来自另一周」，而每一份材料自己都是对的，没人发现得了。合成一件之后周期算一次、传给所有来源。
+
+| 来源 | 取什么 | 证据强度 | 最常见的坑 |
+|---|---|---|---|
+| Git 提交 | 多仓库、多身份合并 | **强**（有作者/时间/行数） | 身份配漏→工作量凭空少一半，且无声无息 |
+| TAPD 工作项 | 需求/缺陷/发布计划 | **强**（有单号可核） | 「动过」≠「已交付」，写交付只引用「本周完成/解决」那部分 |
+| 版本库外文档 | Word/Excel/PPT/PDF | **弱**（只有 mtime） | 拷贝/解压/网盘同步都会刷新，必须逐条认领 |
+
+- **先问清楚汇报周期**：默认「最近 7 天含今天」（周报多半周四五写，按自然周算会把上周四五漏在
+  两份周报的缝里）；用户明确说自然周就传 `week:"this"`；
+- 未配 roots 时只扫当前工作目录——**这几乎一定是漏的**。第一次用就问清项目都放在哪，
+  然后建议写进 `.huicai/weekly.json`，别每次重问；
+- 结果里的「同期其它作者」是给用户看的：若有他自己的另一套 name/email，加进 `identities` 重跑；
+- 要别的 TAPD 口径（按 `created` 查新增、按状态过滤、指定空间）再用 `tapd_fetch` 单独查；
+- **团队层面的数据不按人筛**：`tapd_fetch` 不传 person 就是全空间口径，那才是"团队完成了多少"；
+- **状态用各空间自己的说法**：接口里是 `status_2` 这种自定义代号，工具已翻成中文
+  （"已实现，转测试""测试通过，待发布"）。
+
+> **别为取证单开一轮子智能体。** 工具输出自带可信度标注与缺口提示（弱证据声明、
+> 超大提交的「剔除后」第二个数字、同期其它作者提醒、TAPD 取空时的排查顺序）。
+> 派一个成员去"读一遍再整理成清单"，读的是你已经拿在手里的东西——那一轮白花。
+
+## 二、归并（把过程量变成成果）
+
+- **提交数和行数是过程量，不是成果**。"本周 23 次提交、+4120 行"没有任何汇报价值；
+  "把出片缺陷率从 17% 降到 2%"才有。行数只在一种情况下能写：它本身就是结论（如"清理了 8000 行死代码"）；
+- 工具会标出**超大提交**并给出"剔除后"的第二个数。两个数差得越远，越说明行数不代表手写工作量——
+  这种时候周报里干脆别写行数；
+- 把十几条 commit 按**项目/功能**归并成 **3~5 件事**，每件事一条。多于 6 条领导记不住，少于 3 条像没干活；
+- **个人层面 vs 团队层面要真的分开**：个人写"我决策了什么、我推动了什么"（第一人称的动作），
+  团队写"整体完成率、重点交付、人才与机制"（组织口径的结果）。
+  把团队成果搬到个人栏里，是述职最容易被当场问穿的地方；
+- 范本的四类个人进展可以直接当骨架：**核心事项推进 / 跨部门与外部协同 / 管理动作落地 / 行业认知沉淀**；
+  团队四类：**本周目标完成概览 / 重点项目交付 / 团队效能与人才进展 / 流程与机制优化**。
+
+> **别为取证单开一轮子智能体。** 三件工具的输出自带可信度标注与缺口提示
+> （弱证据声明、超大提交的「剔除后」第二个数字、同期其它作者提醒、TAPD 取空时的排查顺序）。
+> 派一个成员去"读一遍再整理成清单"，读的是你已经拿在手里的东西，产出的是同一批事实换个排版——
+> 那一轮的时间和 token 都白花。分诊自己做，判不了的直接问用户。
+
+## 三、出片（`weekly_report` 渲染，不要自己拼模板）
+
+- 骨架固定：汇报周期 / 汇报人 →【个人层面核心进展】【团队层面核心成果】【存在问题及分析】【下周工作计划】。
+  自己拼模板的结果是小节名、编号符号、周期写法每周变一点，读的人每次都要重新找落点；
+- **每次都把 `work_evidence` 的完整输出传进 `evidence`**。它会拿取证包末尾的【对账锚点】
+  回头核对正文里的原始计数——写「本周 23 次提交」而取证只有 12 次，当场判必修。
+  这是全流程唯一能机检数字真伪的地方，不传就等于没查；
+- **有上一期周报就传 `prev`**（路径或全文）。它会检查上周计划的事这周有没有交代——
+  上周承诺、这周只字不提，是周报最伤信用的写法，也最容易被漏掉；
+- 每条用 **加粗引导词 + 正文**：`{lead:"核心事项推进", text:"完成…"}`。引导词 4~6 字，
+  是这一条的**性质**不是标题，正文紧接其后不加标点；
+- 一条里用分号串 2~3 个子事项（范本就是这么写的），每个子事项自带数字；
+- **【存在问题及分析】必须有"具体问题"和"根因分析"两条**（模板硬要求），建议再加"影响预判"：
+  问题写现象与差距，根因写机制，影响写"若几号前不解决会怎样"。写"暂无问题"等于把问题推迟到月报爆炸；
+- **【下周工作计划】每条都要有日期与责任人**。没有时间点的计划下周无法复盘；
+- 需要向上要资源的放 `asks`（【需上级决策/支持事项】）：写清**要什么、多少、解决哪个已陈述的问题**。
+
+## 四、红线
+
+- **不编数字、不编单号**。取不到就说取不到——编出来的需求号同事一眼认得出，比少写一段严重得多；
+- `work_scan` 的结果是**弱证据**，转述时要说"这些文件本周有改动，请确认哪些是你的工作"，
+  不能直接写成"我完成了 X 文档"；
+- 每个数字都要能指回来源（哪个仓库的哪几次提交、哪个 TAPD 单号）。用户问"这个 92% 哪来的"要答得上。
+  **原始计数**（提交次数/需求条数/缺陷解决数/文档份数）由对账机检；
+  **推算值**（完成率、耗时、百分比）工具判不了，得你自己核算法——它也不假装能判；
+- **必修清零才算能发**。`weekly_report` 出片后自动体检，必修项没清就改了再渲染一遍；
+- 体检**不判断数字真假**——它只保证你写了可被追问的数字。对不对，仍要人核。
+
+## 五、配置（第一次用时帮用户配好，之后就不必问了）
+
+**TAPD 只需要一个个人访问令牌**（TAPD 里「个人设置 → 访问令牌」自助生成）：
+
+```bash
+export TAPD_ACCESS_TOKEN=<你的令牌>
+```
+
+令牌**自带身份**——工具由它问出你是谁（昵称）和你参与了哪些项目，
+所以 `workspace_id` 与 `nickname` 都不用配。第一次先跑 `tapd_fetch({kind:"projects"})`
+验证凭据并看清有哪些空间。也支持公司 API 账号（`TAPD_API_USER`/`TAPD_API_PASSWORD`，Basic），
+但那种问不出身份，**必须自己配 workspace_id**。私有部署设 `TAPD_BASE_URL`。
+
+Git 与文档扫描的设置放 `.huicai/weekly.json`——**项目级**（工作目录下，跟着项目走）
+覆盖**用户级**（`~/.huicai/weekly.json`）：
+
+```json
+{
+  "roots": ["~/Projects", "~/work"],
+  "identities": ["张三", "zhangsan@corp.com", "zhangsan@users.noreply.github.com"],
+  "reporter": "技术中心 张三",
+  "tapd": { "workspace_id": ["12345678"] }
+}
+```
+
+项目级那份在工作区内，可以直接帮用户写；用户级那份在主目录，**请把内容给用户让他自己存**。
+令牌也能写进 `tapd.access_token`，但落盘就有被备份/同步带走的风险，能用环境变量就别写进文件。
+
+> 周报这条链路**不读**平台配置与任何密钥文件——设置单独一个文件，与 API Key 井水不犯河水。
+
+## 六、要 Word 版
+
+先用 `weekly_report(format:"word")` 渲染，再把正文交给 `create_doc` 的 `spec.markdown`。
+
+**别拿默认的 md 版直接去出 Word**——实测那样生成的 docx **一个标题都没有**（28 段全是正文样式），
+目录域和导航窗格全是空的，docx 体检会当场报「全文没有使用标题样式」。
+`format:"word"` 把 `【小节名】` 转成 `## 小节名`，Word 里就是四个二级标题，目录立刻生成得出来。
+
+两点如实告知用户：加粗引导词**会**保留；但条目编号会被 Word 的有序列表样式渲染成 `1.`，
+而不是模板的 `1、`——那是 Word 惯例不是错误，只是发出去的 .md 与 Word 版在这里不一致。
+月报/季度述职/年终总结的**方法论**（OKR 对齐、STAR-I 叙事、晋升自证）走 `okr-review` 技能，
+本技能只管"把这一周的事实取回来并按模板落地"。
+
+## 验收自查
+
+- 三个来源用的是同一个汇报周期，且与正文抬头那行一致；
+- 个人栏每条都是"我"的动作，团队栏每条都是组织口径的结果，没有互串；
+- 每条都有至少一个数字；下周计划每条都有日期；
+- 【存在问题及分析】有具体问题 + 根因分析，不是"暂无"；
+- 体检必修 0 条；每个数字都能说出来源。

package/skills/weekly-report/trigger-cases.json

@@ -0,0 +1,11 @@
+{
+  "skill": "weekly-report",
+  "cases": [
+    { "id": "pos-1", "prompt": "帮我生成本周周报，扫一下我这几个项目的 git 提交", "shouldTrigger": true },
+    { "id": "pos-2", "prompt": "从 TAPD 拉一下我本周解决的缺陷和发布计划，汇总成周报", "shouldTrigger": true },
+    { "id": "pos-3", "prompt": "我这周到底干了啥，把工作情况汇总一下", "shouldTrigger": true },
+    { "id": "neg-1", "prompt": "帮我定下个季度的 OKR 并做对齐检查", "shouldTrigger": false },
+    { "id": "neg-2", "prompt": "把这个仓库的提交历史分析一下，看这段代码为什么存在", "shouldTrigger": false },
+    { "id": "neg-3", "prompt": "写一份晋升答辩材料，对照职级标准逐条自证", "shouldTrigger": false, "lexical": false }
+  ]
+}

package/skills/write-tests/trigger-cases.json

@@ -0,0 +1,31 @@
+{
+  "skill": "write-tests",
+  "cases": [
+    {
+      "id": "pos-1",
+      "prompt": "帮我给这段代码补测试",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-2",
+      "prompt": "提高一下覆盖率，写单元测试",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-3",
+      "prompt": "按 TDD 补集成测试",
+      "shouldTrigger": true
+    },
+    {
+      "id": "neg-1",
+      "prompt": "定一套测试策略和质量门禁",
+      "shouldTrigger": false,
+      "lexical": false
+    },
+    {
+      "id": "neg-2",
+      "prompt": "做一次接口自动化框架搭建",
+      "shouldTrigger": false
+    }
+  ]
+}

package/skills/xlsx-analysis/SKILL.md

@@ -1,96 +1,162 @@
 ---
 name: xlsx-analysis
-description: 复杂 Excel 表格分析、透视、对账与格式化回写。当用户说"Excel/表格/xlsx/透视/汇总/对账/核对/多 Sheet"或给出 .xlsx/.xls 文件时使用。
-version: 1.1.0
+description: Excel 表格分析、透视、对账与报表产出，并对工作簿做体检与校正（数值存成文本、合计写死不是公式、求和范围漏行、合并单元格、列宽显示井号）。当用户说"Excel/表格/xlsx/透视/汇总/对账/核对/多 Sheet/做报表"或给出 .xlsx/.xls 文件，或说"表格数字对不上/合计不对/检查这份表"时使用。
+version: 2.0.0
 ---
 
-# Excel 分析与回写（经 run_python 执行，pandas/openpyxl/xlrd 已随托管运行时就绪）
+# Excel 分析、报表产出与表格体检
 
-要点：**用 run_python 直接开原始表格文件**做精确分析——附件的纯文本摘要只够"大概看看"（公式/多 Sheet/合并单元格全丢），
-**绝不据摘要作答对账/透视类问题**。附件原件已落盘会话工作区 `attachments/`（提问上下文里会指明路径），直接读它。
-`.xls` 旧格式已随核心装了 xlrd，和 `.xlsx` 一样开箱即读，无需再补装。
+**Excel 的事故不改变外观，只改变数字。** PPT 出事一眼看得见，Word 出事翻页能发现，
+Excel 出事什么都看不出来——金额存成文本让 SUM 得 0；合计行是上周算好的常量，改了明细纹丝不动；
+`SUM(B2:B100)` 但数据长到了 B180，少算 80 行；明细里混着「合计」行，一汇总就翻倍。
+这些全都不报错、不变色，只是安静地给出一个错的数，**而错的数和对的数长得一模一样**。
 
-## 首选：先载工具箱（治真实办公表的脏——表头不在首行/文本金额/杂乱日期/合计行混入）
+所以三条纪律：**读之前先体检、算之后要勾稽、产出不由你摆格式。**
 
-真实表格 90% 的坑（表头在第 2~5 行、合并单元格留 NaN、金额是带千分位的文本、日期五花八门、夹着「合计」行）
-本技能的 `scripts/xlsx_toolkit.py` 已封装。**除非表格极简单，一律先用它**：
+## 一、拿到别人的表：先体检，再动手算
+
+```
+xlsx_inspect(path='attachments/收款单202602.xlsx', profile=true)
+```
+
+**这一步不能跳。** 它先告诉你「读进来的东西是不是你以为的东西」：哪列的数值其实是文本、
+哪列编号被读成了数字（前导零已经没了）、哪里有合并单元格会让排序错位、
+明细里混了几行「合计」、哪两个「北京」其实差一个空格。跳过它，后面所有数字都不可信。
+
+体检完再用工具箱稳读（真实办公表 90% 的坑它已经治了）：
 
 ```python
-# 1) read_skill_file(skill="xlsx-analysis", path="scripts/xlsx_toolkit.py") 取源码
-# 2) 连同下面的调用一起交给 run_python 执行（把源码内联在最前，或 exec 之）
-sheet_map('attachments/收款单202602.xlsx')                 # 摸清每个 Sheet：满形状/表头行/列清单/金额·日期列
-df  = smart_read('attachments/收款单202602.xlsx', '凌川峰应收账款')  # 稳读：自动表头+去spacer+剔合计+金额救成float
-ar  = sum_by_period(df, value_col='贷方金额', date_col='记账日期')   # 按月汇总贷方 → {'2026-01':30000, ...}
+# read_skill_file(skill="xlsx-analysis", path="scripts/xlsx_toolkit.py") 取源码，连同调用一起交给 run_python
+sheet_map('attachments/收款单202602.xlsx')                          # 摸清每个 Sheet：表头行/列清单/金额·日期列
+df = smart_read('attachments/收款单202602.xlsx', '凌川峰应收账款')     # 稳读：自动表头+去 spacer+剔合计+金额救成 float
+ar = sum_by_period(df, value_col='贷方金额', date_col='记账日期')      # 按月汇总 → {'2026-01': 30000, …}
 ```
 
-工具箱清单（函数名即用途，全部可直接调）：
-- `sheet_map(path)` — **分析第 0 步**，一次打印整本工作簿结构（表头行、列名、疑似金额/日期列）。
-- `smart_read(path, sheet, header=None, drop_subtotal=True)` — 稳读单个 Sheet，返回干净 DataFrame。表头识别不准时手动传 `header=N`。
-- `to_amount(series)` / `to_period(series, freq='M')` — 金额（清千分位/货币符/括号负数）、日期（含 `2026.3`/excel 序列号/`2026-02-03 0`）稳健转换。
-- `sum_by_period(df, value_col, date_col, freq='M')` — 明细按期汇总 → Series。
-- `reconcile(left, right, left_name, right_name, tol=0.01)` — **按期对账**，逐期算差额并判「✅对平/❌差异」，打印对账表 + 结论。
+`smart_read` 的表头定位对**标题横幅、「标签：值」标注行、整句话**都会避让——真实语料 95 张 sheet 里曾有 28 张把这三类当成了表头（如把「月份：XX年XX月」当列名，读出 `列2/列3/列4`）。同一工作簿里**填了数据的表和空模板必须判成同一表头行**：
+表格稀疏时天真的打分会让横幅反超真表头，而它不报错，下游分析全建在垃圾列名上。
+
+**绝不据附件的纯文本摘要作答对账/透视类问题**——摘要把公式、多 Sheet、合并单元格全丢了。
+原件已落盘会话工作区 `attachments/`，直接读它。`.xls` 随核心装了 xlrd，开箱即读。
+
+### 对账范式（多 Sheet 勾稽，用户最常问的一类）
 
-### 对账任务范式（多 Shet 勾稽，用户最常问的一类）
-> 「把 A 明细、B 明细按月汇总贷方金额，分别和汇总表里某组织的两列按月核对」——标准三步：
 ```python
-ar  = sum_by_period(smart_read(F, '凌川峰应收账款'), '贷方金额', '记账日期')
-adv = sum_by_period(smart_read(F, '凌川峰预收'),   '贷方金额', '记账日期')
+ar   = sum_by_period(smart_read(F, '凌川峰应收账款'), '贷方金额', '记账日期')
+adv  = sum_by_period(smart_read(F, '凌川峰预收'),     '贷方金额', '记账日期')
 summ = smart_read(F, '收款单汇总')
 mine = summ[summ['收款组织'].astype(str).str.contains('凌川峰')]        # 先按组织过滤
-sum_ar  = pd.Series(to_amount(mine['应收账款-贷方']).values, index=to_period(mine['月份']).values)
-sum_adv = pd.Series(to_amount(mine['预收账款-贷方']).values, index=to_period(mine['月份']).values)
-reconcile(ar,  sum_ar,  '应收明细', '汇总应收-贷方')                    # 逐月对平/差异一目了然
-reconcile(adv, sum_adv, '预收明细', '汇总预收-贷方')
+sum_ar = pd.Series(to_amount(mine['应收账款-贷方']).values, index=to_period(mine['月份']).values)
+reconcile(ar, sum_ar, '应收明细', '汇总应收-贷方')                      # 逐月对平/差异一目了然
+```
+
+对不平时**先查三件事再怀疑业务**：dtypes（金额是不是文本）、有没有把「合计」行也汇总进去、
+两边的期间口径是不是同一个（`to_period` 已统一，手写的容易不一致）。
+
+## 二、产出报表：用 `create_sheet`，不要自己写 openpyxl
+
+`create_sheet(path, spec)` 是首选路径。你只给「哪张表放什么」，格式由引擎算：
+
+```jsonc
+{ "profile": "report",
+  "cover": { "title": "2026 年 8 月经营报表",
+             "fields": [["编制单位","数据一部"], ["口径","含税，截至 2026-08-31"], ["来源","ERP 销售出库单"]] },
+  "sheets": [{
+    "name": "分区域明细", "title": "2026 年 8 月分区域销售明细", "note": "口径：含税，单位万元",
+    "columns": [{"key":"region","header":"大区"}, {"key":"prov","header":"省份"},
+                {"key":"amt","header":"销售额","format":"amount"},
+                {"key":"rate","header":"毛利率","format":"percent"}],
+    "rows": [["华东","上海",12000.0,0.224], ["华南","广东",15300.0,0.168]],
+    "group_by": "region", "total": {"label":"总计"},
+    "conditional": [{"col":"amt","type":"data_bar"}],
+    "chart": {"type":"bar","cat":"prov","values":["amt"],"title":"各省销售额"}
+  }]}
+```
+
+引擎替你做对这几件最容易翻车的事，**不要再手工做一遍**：
+
+- **合计一律写 `SUBTOTAL(9,…)` 公式，不是算好的常量**——常量合计在你改明细后不会更新，
+  而且不报错。这是 Excel 交付件最经典的事故，也是本引擎存在的首要理由；
+- 分组小计与总计都用 SUBTOTAL，**总计不会把小计再加一遍**（SUBTOTAL 会忽略嵌套的 SUBTOTAL，
+  这正是这个函数存在的意义，用 SUM 就会翻倍）；
+- 列宽按内容量（数字列不够宽会显示成 ####，打印出来一片井号）；
+- 编号/身份证/单号类列强制 `text` 格式，防前导零消失与科学计数法；
+- 冻结首行 + 自动筛选 + 打印缩放到一页宽 + 跨页重复标题行 + 页脚页码。
+
+**三档规范** `profile`：`report` 业务报表（默认）/ `plain` 素表（便于再加工）/
+`finance` 财务（会计格式、负数红括号）。**四套配色** `theme`：navy / green / mono / warm。
+
+已经有 DataFrame 时也可以走引擎（`xlsx_style.write_styled` 已改为它的薄封装）：
+
+```python
+import os, sys; sys.path.insert(0, os.path.join(os.environ['HUICAI_SKILLS_DIR'], 'xlsx-analysis', 'scripts'))
+from xlsx_build import from_frames
+from_frames({'明细': df, '汇总': pv}, '经营报表.xlsx', total=True, title='2026 年 8 月经营报表')
 ```
 
-## 底层手法（工具箱不够用、或需自定义时）
-
-1. **先摸结构再分析**（跳过这步 = 错误答案的头号来源）：`sheet_map(path)`；或手写
-   ```python
-   import pandas as pd
-   xf = pd.ExcelFile('文件.xlsx')
-   for s in xf.sheet_names:
-       print(s, xf.parse(s, header=None, nrows=8).to_markdown())  # header=None 看清表头到底在第几行
-   ```
-   看清：表头在第几行？有没有合并单元格产生的 NaN？哪些列是日期/金额？
-2. **正确读取**：表头不在首行用 `header=N` 或 `skiprows`；读全部 Sheet 用 `sheet_name=None`（返回 dict）；大表先 `usecols` 挑列。
-3. **清洗**：合并单元格读出的 NaN 用 `df[col] = df[col].ffill()`（仅对确认是合并单元格的列）；金额千分位/文本用 `to_amount()`；日期用 `to_period()` 或 `pd.to_datetime(df[col])`。
-4. **分析/透视**：
-   ```python
-   pv = df.pivot_table(index='地区', columns='季度', values='销售额', aggfunc='sum', margins=True, margins_name='合计')
-   ```
-   多层透视 index=['大区','省份']；同时多个聚合 aggfunc={'销售额':'sum','订单':'count'}。
-5. **格式化回写**：`read_skill_file` 读本技能 `scripts/xlsx_style.py`，把 `write_styled()` 连同代码一起执行——表头样式/冻结首行/自动列宽/数字格式/斑马纹一步到位。需要图表另出 png（画图先 load_skill('data-analysis') 用其字体脚本）。
-6. **验收（必做）**：回写后**重新打开**校验并 print：
-   ```python
-   chk = pd.read_excel('产物.xlsx', sheet_name=None)
-   for s, d in chk.items():
-       print(s, d.shape, '| 首行:', d.iloc[0].tolist() if len(d) else '空', '| 末行:', d.iloc[-1].tolist() if len(d) else '空')
-   ```
-
-## 公式与格式的边界
-
-- pandas 读到的是**值**；要读**公式本身**用 `openpyxl.load_workbook(f)`（不带 data_only），要读**公式算出的值**用 `data_only=True`（前提：文件被 Excel 保存过，否则缓存值为 None——此时用 pandas 自己算）。
-- 回写公式：openpyxl `ws['D2'] = '=SUM(B2:C2)'`；写完的公式值要等用户用 Excel 打开才计算，验收时校验公式字符串而非值。
-- `.xls` 老格式：xlrd 已随核心装好，`pd.read_excel('x.xls')` 直接可读（pandas 按扩展名自动选引擎），无需补装。
-
-## 常见坑
-
-- 「合计」行混在数据里：分析前剔除（`df[df['地区']!='合计']`），透视用 margins 自己生成。
-- 数字被读成文本（前导零/空格）：对账合不上先查 dtypes。
-- 单元格里的换行与不可见空格：`str.strip()`。
-- 超大表（几十万行）：pandas 正常处理；不要逐单元格 openpyxl 循环（慢百倍）。
-
-## 验收自查
-
-- [ ] 第一步结构探查的输出在结果里（Sheets/形状/表头）
-- [ ] 每个产物 xlsx 都重读校验过（形状+首末行已 print）
-- [ ] 金额/日期列类型正确（对账类任务 print 过 dtypes）
-- [ ] 用户口径的"合计"与你算的合计对得上（差异要指出原因）
-
-## 附件
-
-- `scripts/xlsx_toolkit.py` — **分析工具箱（首选先载）**：`sheet_map` 摸结构、`smart_read` 稳读脏表、`to_amount`/`to_period` 稳健转换、`sum_by_period` 按期汇总、`reconcile` 按期对账；`python xlsx_toolkit.py` 可直接跑自测
-- `scripts/xlsx_style.py` — 格式化回写助手：`write_styled(df_dict, path, ...)` 表头样式/冻结/列宽/数字格式/斑马纹；可直接执行自测
+## 三、验收：`xlsx_inspect` 必修项清零才算做完
+
+`create_sheet` 已自动体检；**自己写 openpyxl/pandas 导出的更要手动跑一遍**。六类问题分三档：
+
+| 必修（数字是错的） | 建议（能用，但不专业） | 提示 |
+|---|---|---|
+| 数值被存成文本（SUM 得 0） | 一列里数字与文本混杂 | 日期存成文本 |
+| 合计是写死的常量而不是公式 | 一列里公式与手打常量混杂 | 易失函数过多 |
+| 合计对不上明细之和 | 占比列合计不等于 100% | 断月 |
+| 求和范围没覆盖到数据末行 | 外部工作簿链接 | 默认表名 Sheet1 |
+| 错误值 #REF!/#DIV/0!/#N/A | 隐藏行列（会被 SUM 计入却看不见） | — |
+| 数据区内的合并单元格 | 「合计」行混在明细中 | 表头不在首行 |
+| 引用了不存在的工作表 | 完全重复行、首尾空白与不可见字符 | 极端值 |
+| 编号列超 15 位已丢精度 | 编号列被存成数字（前导零消失） | — |
+| 列宽不足会显示 #### | 同列数字格式不统一、金额缺千分位 | 缺筛选 |
+| 重名列 | 缺冻结窗格、打印横跨多页 | 缺重复标题行 |
+
+**旧版 `.xls`**（真实归档里常占一半：评审报告、预算表往往还是 .xls）：体检会自动降级——
+用 xlrd 把**值**读进来做数据层与勾稽层判断，并明说公式、列宽、合并、冻结、打印这几类
+**读不到、本次没查**（不是「没问题」）。`fix` 对 .xls 直接拒绝：读入时只剩值，
+另存会把原件的公式与格式一次性丢光，而输出文件看起来完全正常。先用 Excel 另存为 .xlsx 再修。
+
+`xlsx_inspect(path, fix=true)` 自动修可确定性修的那几类（文本转数字、编号列转文本、清空白、
+拆数据区合并并填充、**写死的合计改成 SUBTOTAL 公式**、补齐求和范围、列宽自适应、格式归一、
+补千分位、冻结与筛选、打印一页宽），**另存 `-已校正.xlsx` 不覆盖原件**。
+救不回来的会如实说——比如编号已超 15 位、精度在导出那一刻就丢了，**任何工具都救不回来，
+只能让对方按文本重新导出**。别假装修好了。
+
+## 四、公式与格式的边界
+
+- pandas 读到的是**值**；要读**公式本身**用 `openpyxl.load_workbook(f)`（不带 data_only），
+  要读**公式算出的值**用 `data_only=True`——前提是文件被 Excel 保存过，否则缓存值为 None，
+  此时用 pandas 自己算。
+- 回写公式：`ws['D2'] = '=SUM(B2:C2)'`；公式值要等用户用 Excel 打开才计算，
+  验收时校验公式字符串而非值（`xlsx_inspect` 就是这么查的）。
+- 超大表（几十万行）：pandas 正常处理；**不要逐单元格 openpyxl 循环**（慢百倍）。
+  多表关联 / 跨表勾稽 / 内存吃紧改走 `sql-analysis`（DuckDB 直接对文件跑 SQL，不落库）——
+  多步 merge→groupby→pivot→再 merge 是最容易写错也最难自查的一类代码，一句 SQL 说得清。
+
+## 五、交付自查
+
+- [ ] 动手算之前跑过 `xlsx_inspect(profile=true)`，读进来的类型确认无误
+- [ ] `xlsx_inspect` 必修 = 0（做不到就如实说明哪几项需要用户决定）
+- [ ] 合计是公式不是常量（改一行明细，合计会跟着变）
+- [ ] 用户口径的「合计」与你算的合计对得上，差异指出了原因
+- [ ] 每个产物 xlsx 都重读校验过（形状 + 首末行已 print）
+- [ ] 文件名是中文描述性名称，已 print 产物清单
+
+## 附件（日常用 `create_sheet` / `xlsx_inspect` 工具即可，不必读源码）
+
+- `scripts/xlsx_toolkit.py` — **读脏表工具箱（分析第一步）**：`sheet_map` 摸结构、
+  `smart_read` 稳读、`to_amount`/`to_period` 稳健转换、`sum_by_period` 按期汇总、
+  `reconcile` 按期对账；可直接执行自测。
+- `scripts/data_profile.py` — 数据体检：推断真实类型、找唯一标识列、重复行、同物异名、
+  缺失率、极端值、断月。`profile(df)` / `report_file(path)`；也是 `xlsx_inspect(profile=true)` 的那一层。
+- `scripts/xlsx_layout.py` — 呈现度量内核：列宽计算（中文按 2 宽）、数字格式档位、
+  主题配色、打印页宽估算。**建表与体检共用同一把尺**。
+- `scripts/xlsx_build.py` — 建表引擎：多表、标题、分组小计、合计公式、条件格式、
+  数据验证、图表、打印设置；`from_frames()` 直接吃 DataFrame；`--demo` 可自测。
+- `scripts/xlsx_check.py` — 体检与自动校正：`inspect()` / `report()` / `fix()`；
+  CLI `python xlsx_check.py 报表.xlsx --fix`。
+- `scripts/xlsx_style.py` — 老接口 `write_styled()` 的兼容垫片（已改走新引擎）。
+- `scripts/xlsx_battery.py` — 压力测试：随机内容 × 三档规范跑几百份断言零事故，
+  **反向造 29 类缺陷验证体检不是瞎子**，再跑 9 项反误报与校正闭环。
+  改了上面任何一个引擎文件，**必须重跑**：`python xlsx_battery.py 300`。
 
 > 本技能属 **Excel 与数据分析链**——19 项数据能力路由与端到端工作流见 `excel-analysis-chain`。