@huicai/cli 2026.714.0 → 2026.721.0

package/skills/web-scraping/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: web-scraping
+description: 网络数据抓取与结构化提取（网页抓取解析、数据字段提取、多级深度爬取、翻页与增量采集、JS 渲染页、API 接入、清洗入库）。当用户说"抓取网页/爬数据/采集/提取网页字段/深度爬取/从网站拿数据/接口对接/外部数据"时使用。爬虫链之采集环。
+version: 1.2.0
+---
+
+# 网络数据抓取与结构化提取（爬虫链 · 采集环；检索选题见 web-search，签名接口见 api-integration，全链见 crawl-chain）
+
+## 合规红线（第一位，不可跳过）
+
+- **遵守 robots.txt 与网站服务条款**;不抓取需登录/付费墙后的受保护内容;
+- 频率克制（加延时,别把人家站点打挂——高频=攻击）;标明 User-Agent;
+- **不抓个人隐私数据**（手机号/身份证/住址等,《个人信息保护法》红线,转 risk-compliance）;
+  不绕过验证码/反爬做对抗（技术对抗≈越界,如实劝阻）;
+- 数据用途合规（商用授权/版权）;拿不准的**先咨询法务**（legal-chain）。
+本技能仅辅助**合法公开数据**的采集与整理。
+
+## 工具路径（按规模递进，复用既有能力）
+
+- **单页/接口**：`fetch_url` 直接抓——已按页面字符集解码（GBK 中文站不乱码）、附标题;
+  **顺链翻页**：`fetch_url(url, links=true)` 返回「锚文本 → 绝对URL」清单,挑下一页/详情页继续;
+- **系统级工具**：`run_bash` 里用 **curl / wget**——需要自定义 header（Cookie/Referer/UA）、
+  调 REST 接口、下载文件、看响应头/状态码时比 fetch_url 更灵活:
+  - `curl -sSL -A "..." -H "Referer: ..." URL`（-s 静默 -S 报错 -L 跟跳转）;
+  - `curl -sD - -o body.html URL` 分离响应头与正文;`curl -w "%{http_code} %{time_total}\n"` 看指标;
+  - `curl --compressed`（gzip 省流）、`--retry 3 --retry-delay 2`（内建重试）、`--limit-rate 500k`（限速礼貌）;
+  - 签名认证接口 → 载入 **api-integration**（签名算法/时间戳/鉴权头）;
+- **解析与批量**：`run_python` + 按需装（`packages=['requests','beautifulsoup4','lxml']`）:
+  - requests（headers/timeout/重试/延时封装成函数,session 复用连接与 Cookie）;
+  - BeautifulSoup/lxml（CSS 选择器/XPath;**选择器写注释**,结构变更好修）;
+  - pandas `read_html` 一行抓网页表格（**规整表格首选,别手写解析**）;
+- **JS 渲染页判定与路由**：fetch_url 抓回正文近空/只有骨架 → 靠 JS 渲染:
+  ①优先找背后数据接口（浏览器 Network 里常有现成 JSON,直连最稳,配合 api-integration 处理签名）;
+  ②桌面端内置浏览器 browser_* 截图辅助定位;③仍不行才 playwright 渲染（重型,页面少不值得）。
+
+## 结构化数据提取（从"抓回一坨文本"到"干净的字段表"）
+
+1. **先定 schema**：要哪些字段、类型、必填性——照着 schema 提取,而非有啥抓啥;
+2. **定位锚点**：优先稳定锚（id/语义化 class/`data-*`/JSON-LD `<script type=application/ld+json>`
+   常含现成结构化数据,**先找它**）;避免依赖易变的层级下标与展示型 class;
+3. **正则只切碎片、结构靠解析器**：别用正则解析整页 HTML（脆且易错）;正则用于从已定位文本里
+   抠日期/金额/编号等 pattern;
+4. **规范化即时做**：日期统一 ISO、金额去千分位转数值并记币种、空值标 NA、去首尾空白与全半角;
+5. **一致性校验**：字段级（类型/枚举/范围）+ 记录级（该有的字段齐不齐）+ 批次级
+   （本批 vs 上批数量突变即预警）;连续大面积 NA → 选择器可能失效,停并报告,别闷头写下去。
+
+## 多级深度爬取（列表 → 详情 → 下一层，广度优先 + 去重 + 限深）
+
+- **模型**：种子 URL → 抽链接（fetch_url links=true 或解析器）→ 入队 → 逐个抓 → 再抽链接…
+  用 **BFS 队列**（先进先出,层层推进）而非无脑递归;
+- **三个必备闸门**（缺一即失控）：
+  - **去重集**：已访问 URL 归一化（去 fragment、排序 query、统一大小写）后入 set,命中即跳;
+  - **限深/限量**：max_depth（如详情页 2 层就够）+ max_pages（总量上限）,到顶即停;
+  - **同域约束**：默认只跟同域链接,跨域要显式放行（防爬遍半个互联网）;
+- **礼貌**：同域串行 + 延时 ≥1s;尊重 robots 的 Crawl-delay;并发只在多域间且带全局限速;
+- **断点续爬**：队列状态 + 已访问集落盘,中断可从断点续（大爬必备,别从头再来）;
+- **产出可回放**：每页原始响应存 `raw/<url哈希>.html`,解析与抓取解耦——解析逻辑改了不必重抓。
+
+## 抓取流程（工程化，不是一次性脚本）
+
+1. **踩点**：数据在页面还是接口?静态还是 JS 渲染?robots/ToS 确认?预估量级（<50 页脚本直跑,更大上断点续爬）;
+2. **单条验证**：先抓一条解析对（字段齐、编码正、类型对）,再批量;
+3. **批量/深爬**：BFS + 去重 + 限深 + 延时 + 重试(≤3 退避) + 逐条日志;
+4. **增量更新**：二次只抓新增/变更（URL 集合差 / 发布时间水位线）,全量重抓是浪费;
+5. **解析入库**：raw 留档 → schema 提取 → data-wrangling 清洗 → 落 xlsx/csv
+   （**每条带来源 URL 与采集时间戳,可溯源**）;
+6. **反爬礼貌应对**：403/429 降频而非对抗;结构变更解析容错(缺失标 NA 不崩)。
+
+## 典型场景
+
+竞品价格监控（定时抓取,office-automation 例程,pivot-crosstab 出趋势）/ 公开数据聚合
+（统计局/公告/榜单,web-search 先定位信源）/ 舆情信源采集（转 pr-comms 舆情分析）/
+目录站深度归集（列表→详情两级爬,tech-research 佐证,注明抓取日期）。
+
+## 验收自查
+
+- [ ] robots/ToS 已确认;无隐私/受保护数据
+- [ ] 先定 schema 再提取;锚点稳（优先 JSON-LD/语义化）;规范化与校验到位
+- [ ] 深爬有去重集+限深限量+同域约束+断点续;原始响应留档
+- [ ] 频率克制有延时;单条先验证再批量;JS 渲染页走接口/渲染路由
+- [ ] 数据带来源 URL 与采集时间戳;遇反爬降频不对抗

package/skills/web-search/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: web-search
+description: 网页搜索与信息检索（查询构造、多源交叉验证、结果甄别去重、网页内容分析与提炼、引用规范、搜索→抓取→分析闭环）。当用户说"搜一下/查资料/联网查/最新消息/找信源/调研某主题/分析这个网页/总结这篇文章"时使用。爬虫链之检索环。
+version: 1.1.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）。
+
+## 查询构造（一次搜不准是常态，会迭代才是能力）
+
+- 关键词化而非整句：提取实体+限定词（"华为 2025 年报 营收" 优于整句）;
+- 善用操作符：`site:gov.cn`（限站）、`filetype:pdf`（找报告原文）、`"精确短语"`、`-排除词`、时间限定;
+- 中英双语各搜一遍（技术/学术主题英文信源常更全）;
+- 递进式：宽泛首搜认识领域词汇 → 用学到的准确术语二搜 → 直捣权威信源站内三搜。
+
+## 网页内容分析（抓回来之后，从"文本"到"回答"）
+
+抓到正文（fetch_url / curl）后不是原样丢给用户,而是**按意图加工**：
+
+- **定位与降噪**：网页正文常裹在导航/广告/推荐里。找主体区域（`<article>`/`<main>`/正文密度最高块）,
+  剥离页眉页脚侧栏——喂给下一步的应是干净正文,不是整页噪声;
+- **抽取式提炼**：先抽关键句/关键数据（原文片段,可回指）,再做归纳——**先事实后观点**,别一上来就概括;
+- **结构化产出按意图**：
+  - 「总结这篇」→ 分层摘要（一句话结论 + 3-5 要点 + 关键数据表）;
+  - 「对比几个来源」→ 证据矩阵（行=来源,列=对比维度,每格带出处,见 tech-research）;
+  - 「提取字段」→ 结构化表（转 web-scraping 的 schema 提取）;
+  - 「找答案」→ 直接回答 + 支撑原文引用 + 未覆盖部分如实说;
+- **长文分块**：超长网页/文档分块处理再合并,别截断丢尾（长文走 long-doc-analysis）;
+- **多页聚合**：同主题多来源 → 去重（近义信息合并）→ 冲突并列 → 时间线/对比表收敛。
+
+## 结果甄别与交叉验证
+
+- **信源分级**：官方一手（官网/公告/统计局/论文）> 权威媒体/行业报告 > 社区/自媒体（只作线索）;
+- **关键事实至少两个独立信源相互印证**;数字类核对口径（统计范围/币种/时点）;
+- 时效检查：注明发布日期,旧文当新闻是硬伤;SEO 农场/内容拼凑站直接丢弃;
+- 搜索结果只是入口：**结论必须来自点进去的原文**（fetch_url 抓全文核实,别拿摘要下结论）。
+
+## 搜索 → 抓取 → 分析闭环
+
+1. 明确要回答的问题（拆成 2-5 个可检索的子问题）;
+2. 逐子问题检索,收集候选信源（URL + 标题 + 日期）;
+3. fetch_url/curl 抓正文,按上节「内容分析」降噪+提炼（web-scraping 处理批量/深爬）;
+4. 汇总输出：**每个关键结论标注来源（URL + 访问日期）**,冲突信息并列呈现并说明取舍;
+5. 信息不足时如实说"没查到/存疑"，绝不编造——宁缺毋滥。
+
+## 典型场景
+
+行业/竞品调研（转 tech-research 深度分析）/ 政策法规检索（官方原文为准,转 legal-chain 解读）/
+数据找源（统计局/年报/榜单 → web-scraping 采集）/ 技术选型查证（官方文档+GitHub issue 双核）/
+单篇深读（长文摘要/观点提炼,转 long-doc-analysis）/ 时事背景补全（写作/汇报前事实核查）。
+
+## 验收自查
+
+- [ ] 关键结论均有来源标注（URL + 访问日期）,且来自原文非摘要
+- [ ] 关键事实 ≥2 独立信源印证;冲突已并列说明
+- [ ] 内容分析先降噪再提炼、先事实后观点;长文分块不丢尾
+- [ ] 信源分级意识：结论不建立在社区/自媒体单源上
+- [ ] 搜索页兜底通道频率克制;没查到的如实说明

package/skills/xlsx-analysis/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: xlsx-analysis
+description: 复杂 Excel 表格分析、透视、对账与格式化回写。当用户说"Excel/表格/xlsx/透视/汇总/对账/核对/多 Sheet"或给出 .xlsx/.xls 文件时使用。
+version: 1.1.0
+---
+
+# Excel 分析与回写（经 run_python 执行，pandas/openpyxl/xlrd 已随托管运行时就绪）
+
+要点：**用 run_python 直接开原始表格文件**做精确分析——附件的纯文本摘要只够"大概看看"（公式/多 Sheet/合并单元格全丢），
+**绝不据摘要作答对账/透视类问题**。附件原件已落盘会话工作区 `attachments/`（提问上下文里会指明路径），直接读它。
+`.xls` 旧格式已随核心装了 xlrd，和 `.xlsx` 一样开箱即读，无需再补装。
+
+## 首选：先载工具箱（治真实办公表的脏——表头不在首行/文本金额/杂乱日期/合计行混入）
+
+真实表格 90% 的坑（表头在第 2~5 行、合并单元格留 NaN、金额是带千分位的文本、日期五花八门、夹着「合计」行）
+本技能的 `scripts/xlsx_toolkit.py` 已封装。**除非表格极简单，一律先用它**：
+
+```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, ...}
+```
+
+工具箱清单（函数名即用途，全部可直接调）：
+- `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)` — **按期对账**，逐期算差额并判「✅对平/❌差异」，打印对账表 + 结论。
+
+### 对账任务范式（多 Shet 勾稽，用户最常问的一类）
+> 「把 A 明细、B 明细按月汇总贷方金额，分别和汇总表里某组织的两列按月核对」——标准三步：
+```python
+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, '预收明细', '汇总预收-贷方')
+```
+
+## 底层手法（工具箱不够用、或需自定义时）
+
+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, ...)` 表头样式/冻结/列宽/数字格式/斑马纹；可直接执行自测
+
+> 本技能属 **Excel 与数据分析链**——19 项数据能力路由与端到端工作流见 `excel-analysis-chain`。

package/skills/xlsx-analysis/scripts/xlsx_style.py

@@ -0,0 +1,71 @@
+# xlsx 格式化回写助手（经 run_python 执行）。核心入口 write_styled()：
+#   表头加粗白字深蓝底、冻结首行、按内容自动列宽（中文按 2 宽）、数字/金额/日期格式、斑马纹。
+# 直接执行本文件 = 自测：产出 xlsx_style_check.xlsx 并重读校验。
+import pandas as pd
+from openpyxl.styles import Alignment, Border, Font, PatternFill, Side
+from openpyxl.utils import get_column_letter
+
+HEADER_FILL = PatternFill('solid', fgColor='1F4E79')   # 深蓝
+STRIPE_FILL = PatternFill('solid', fgColor='F2F6FA')   # 斑马浅蓝
+THIN = Side(style='thin', color='D9D9D9')
+BORDER = Border(left=THIN, right=THIN, top=THIN, bottom=THIN)
+
+
+def _width(v):
+    """按显示宽度估列宽：CJK 记 2，其他记 1。"""
+    s = '' if v is None else str(v)
+    return sum(2 if ord(ch) > 0x2E7F else 1 for ch in s)
+
+
+def write_styled(sheets, path, number_formats=None, stripe=True, max_width=60):
+    """把 {sheet名: DataFrame} 写成带格式的 xlsx。
+    number_formats: {列名: 格式}，如 {'销售额': '#,##0.00', '占比': '0.0%', '日期': 'yyyy-mm-dd'}。
+    """
+    if isinstance(sheets, pd.DataFrame):
+        sheets = {'Sheet1': sheets}
+    number_formats = number_formats or {}
+    with pd.ExcelWriter(path, engine='openpyxl') as xw:
+        for name, df in sheets.items():
+            df.to_excel(xw, sheet_name=name[:31], index=False)
+            ws = xw.sheets[name[:31]]
+            ws.freeze_panes = 'A2'
+            for j, col in enumerate(df.columns, start=1):
+                letter = get_column_letter(j)
+                head = ws.cell(row=1, column=j)
+                head.font = Font(bold=True, color='FFFFFF')
+                head.fill = HEADER_FILL
+                head.alignment = Alignment(horizontal='center', vertical='center')
+                fmt = number_formats.get(str(col))
+                w = _width(col) + 2
+                for i in range(2, len(df) + 2):
+                    cell = ws.cell(row=i, column=j)
+                    cell.border = BORDER
+                    if fmt:
+                        cell.number_format = fmt
+                    if stripe and i % 2 == 0:
+                        cell.fill = STRIPE_FILL
+                    w = max(w, _width(cell.value) + 2)
+                ws.column_dimensions[letter].width = min(w, max_width)
+    return path
+
+
+def verify(path):
+    """重读校验并打印（验收步骤用）：每个 sheet 的形状与首末行。"""
+    chk = pd.read_excel(path, sheet_name=None)
+    for s, d in chk.items():
+        head = d.iloc[0].tolist() if len(d) else '空'
+        tail = d.iloc[-1].tolist() if len(d) else '空'
+        print(f'[verify] {s} shape={d.shape} 首行={head} 末行={tail}')
+    return chk
+
+
+if __name__ == '__main__':
+    df = pd.DataFrame({
+        '地区': ['华东', '华南', '华北', '西南'],
+        '销售额': [1200.5, 950.25, 870.0, 640.75],
+        '占比': [0.328, 0.26, 0.238, 0.175],
+    })
+    p = write_styled({'销售汇总': df}, 'xlsx_style_check.xlsx',
+                     number_formats={'销售额': '#,##0.00', '占比': '0.0%'})
+    verify(p)
+    print('OK', p)