@huicai/cli 2026.714.0 → 2026.721.0

package/README.md

@@ -112,7 +112,8 @@ huicai -c -p "继续修" --yolo   # 非交互续接（CI）
 |---|---|---|
 | `read_file` / `list_files` / `glob` / `grep` | 读(带行号)/列/查找/搜索（grep 支持 ignore_case/files_only） | 自动放行（只读） |
 | `write_file` / `edit_file` | 写文件 / 精确替换（仅项目目录内） | 需授权 |
-| `run_bash` | 执行 shell 命令（超时整进程组击杀；Windows 走 cmd） | 需授权 |
+| `run_bash` | 执行 shell 命令（超时整进程组击杀；Windows 走 cmd；托管 Python 就绪后注入 `HUICAI_PYTHON`） | 需授权 |
+| `run_python` | 在**托管 Python** 中执行代码/脚本（办公能力层，docs/21）：首次调用自动装 uv+CPython 3.12+基础包（pandas/openpyxl/python-docx/python-pptx/pypdf/matplotlib/tabulate）到 `~/.huicai/python`，用户无需预装 Python。慢网治理：**整包直下**（`HUICAI_PYRT_BUNDLE` 指向 `huicai python pack` 产物的静态目录，断点续传+sha256，失败回退组装）＋**分级安装**（表格核心三件套先行、扩展容错续装）；组装镜像三键 `HUICAI_UV_MIRROR / HUICAI_PYTHON_MIRROR / HUICAI_PYPI_MIRROR`；`packages` 按需补包；`HUICAI_PYTHON_DISABLED=1` 禁用；`huicai python [status/setup/pack/reset]` 管理 | 需授权（沙箱模式禁用） |
 | `fetch_url` | 抓取网页/接口（HTML 自动转纯文本），查在线文档 | 需授权 |
 | `todo_write` | 维护任务清单（TUI 实时渲染进度） | 自动放行 |
 | `dispatch_agent` | 委派子任务给隔离上下文的只读子智能体 | 自动放行（只读） |

package/bin/huicai.js

@@ -135,6 +135,7 @@ ${c.bold('huicai')} — 终端智能体，以 HuiCai_AI 平台为模型后端，
   huicai kb-sync <id> [ref]  配合 git diff 增量同步知识库，保鲜 RAG（--dry 试运行）
   huicai skills pull [name]  平台技能 → 本地（默认 ~/.huicai/skills；--project 放入项目）
   huicai skills push <name>  本地技能 → 平台（默认同名跳过；--overwrite 覆盖）
+  huicai python [setup]      托管 Python 运行时：状态/预装/整包打包(pack)/重置（数据分析与办公文档的地基）
   huicai uninstall [--yes]   清理本机所有 CLI 数据（~/.huicai：配置/令牌/会话/记忆/技能…）
   huicai help                显示本帮助
 
@@ -293,6 +294,83 @@ async function cmdUsage(config) {
   }
 }
 
+/**
+ * python 子命令：托管 Python 运行时（办公能力层地基，docs/21）。
+ *   huicai python [status]        各组件状态与镜像（默认）
+ *   huicai python setup           立即安装/补齐（私有化母盘、CI 预热用；平时首次 run_python 自动装）
+ *   huicai python pack [--out d]  构建运行时整包（tar.gz + manifest），托管到静态目录即成整包源
+ *   huicai python reset --yes     整体清空（重装前置）
+ */
+async function cmdPython(config, rest) {
+  const py = await import('../src/pyruntime.js');
+  const action = rest.find((x) => !x.startsWith('-')) || 'status';
+
+  if (action === 'status') {
+    const s = py.runtimeStatus(config);
+    const mark = (ok) => (ok ? c.green('✓') : c.yellow('•'));
+    process.stdout.write(c.bold('托管 Python 运行时') + c.gray('（' + s.dir + '）') + '\n');
+    process.stdout.write(`  ${mark(s.uv)} uv ${s.uv ? '已就绪' + (s.uvVersion ? '（' + s.uvVersion + '）' : '') : '未安装'}\n`);
+    process.stdout.write(`  ${mark(s.python)} CPython ${s.python ? s.pythonVersion + ' 已就绪' : '未安装'}\n`);
+    process.stdout.write(`  ${mark(s.venv)} 虚拟环境 ${s.venv ? s.venvPython : '未创建'}\n`);
+    process.stdout.write(`  ${mark(s.coreMissing.length === 0)} 核心包（表格） ${s.coreMissing.length === 0
+      ? '已就绪' : '缺 ' + s.coreMissing.join(' ')}\n`);
+    process.stdout.write(`  ${mark(s.extrasMissing.length === 0)} 扩展包（图表/文档） ${s.extrasMissing.length === 0
+      ? '已就绪' : '缺 ' + s.extrasMissing.join(' ')}\n`);
+    const mir = [s.mirrors.bundle && '整包=' + s.mirrors.bundle, s.mirrors.uv && 'uv=' + s.mirrors.uv,
+      s.mirrors.python && 'python=' + s.mirrors.python, s.mirrors.pypi && 'PyPI=' + s.mirrors.pypi].filter(Boolean);
+    if (mir.length) process.stdout.write(c.gray('  镜像：' + mir.join('  ')) + '\n');
+    if (!s.ready) process.stdout.write(c.gray('  （huicai python setup 立即安装；或首次数据分析任务时自动安装）') + '\n');
+    return;
+  }
+
+  if (action === 'setup') {
+    try {
+      const r = await py.ensureRuntime({
+        config, retryExtrasNow: true,
+        log: (line) => process.stdout.write(c.gray('  ' + line) + '\n'),
+      });
+      if (r.extrasMissing.length) {
+        process.stdout.write(c.yellow(`⚠ 核心已就绪，扩展包未装齐（${r.extrasMissing.join(' ')}）；重跑本命令补装。`) + '\n');
+        process.exit(1);
+      }
+      process.stdout.write(c.green(r.firstInstall ? '✅ 运行时安装完成：' : '✅ 运行时已就绪：') + r.python + '\n');
+    } catch (e) {
+      process.stderr.write(c.red('安装失败：' + e.message) + '\n');
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (action === 'pack') {
+    // 构建运行时整包（CI/运维）：产物（tar.gz + manifest）丢任意静态目录即成整包源（HUICAI_PYRT_BUNDLE）
+    const outIdx = rest.indexOf('--out');
+    const outDir = outIdx >= 0 && rest[outIdx + 1] ? rest[outIdx + 1] : '.';
+    try {
+      const r = await py.packRuntime({ outDir, config, log: (line) => process.stdout.write(c.gray('  ' + line) + '\n') });
+      process.stdout.write(c.green('✅ 整包完成：') + r.file + c.gray(`（${Math.round(r.size / 1024 / 1024)}MB）`) + '\n');
+      process.stdout.write(c.gray('  清单已更新：' + r.manifest) + '\n');
+      process.stdout.write(c.gray('  托管到静态目录后配置 HUICAI_PYRT_BUNDLE=<基址> 即启用整包直下') + '\n');
+    } catch (e) {
+      process.stderr.write(c.red('打包失败：' + e.message) + '\n');
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (action === 'reset') {
+    if (!rest.includes('--yes') && !rest.includes('-y')) {
+      process.stderr.write(c.red('将删除整个 ' + py.runtimeDir() + '（uv/CPython/虚拟环境/已装包）；确认请加 --yes') + '\n');
+      process.exit(1);
+    }
+    py.resetRuntime();
+    process.stdout.write(c.green('✅ 已清空托管 Python 运行时（下次使用时自动重装）') + '\n');
+    return;
+  }
+
+  process.stderr.write(c.red(`未知子命令：python ${action}（可用：status / setup / pack [--out 目录] / reset --yes）`) + '\n');
+  process.exit(1);
+}
+
 /**
  * skills 子命令：本地技能与平台云端技能库的查看/同步。
  *   huicai skills                    列出本地 + 平台技能
@@ -505,6 +583,11 @@ async function main() {
     return;
   }
 
+  if (sub === 'python') {
+    await cmdPython(config, positional.slice(1));
+    return;
+  }
+
   if (sub === 'daemon') {
     // 内置调度守护：按 cron 真正运行 /schedule 登记的任务（Ctrl-C 退出）
     const { runDaemon } = await import('../src/daemon.js');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@huicai/cli",
-  "version": "2026.714.0",
-  "versionDisplay": "2026.07.14",
+  "version": "2026.721.0",
+  "versionDisplay": "2026.07.21",
   "description": "在终端运行的智能体 CLI：以 HuiCai_AI 平台的 OpenAI 兼容 /v1 为模型后端，在用户本机执行文件/命令工具。",
   "type": "module",
   "bin": {

package/skills/ab-testing/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: ab-testing
+description: AB 实验设计与分析（假设与指标设计、样本量计算、SRM 校验、显著性检验、实验结论规范）。当用户说"做个 AB 实验/这个实验显著吗/要跑多少样本/实验结果怎么解读"时使用。数据技能链之实验环。
+version: 1.0.0
+---
+
+# AB 实验（数据技能链 · 实验环；全景见 data-chain）
+
+实验是**因果**的金标准——前提是设计对、跑够长、不作弊。三者缺一,结论比拍脑袋更危险
+（因为它披着科学外衣）。
+
+## 实验设计七步（开跑前全部落纸）
+
+1. **假设**：可证伪句式——"把按钮从 A 改为 B,将使支付转化率相对提升 ≥3%"（改什么/影响什么/幅度）;
+2. **指标**：主指标一个（与假设直接对应）+ 护栏指标（退货率/加载时长/投诉——**赢了主指标
+   输了护栏=输**,metrics-system 口径）;
+3. **实验单位与分流**：用户级 vs 会话级（跨设备/登录态污染评估）;分流互斥域（同时跑的实验
+   会不会打架）;
+4. **样本量**（`read_skill_file` 读 `scripts/ab_test.py`）：`sample_size()` 由基线率/最小可检测
+   效应 MDE/显著性水平/功效算出**每组**所需样本——样本不够就开跑=大概率白跑;
+5. **时长**：max(样本量所需天数, **≥1 个完整周期**（含周末,周期效应）),避开大促等异常期;
+6. **预检**：AA 实验或 SRM 预演,埋点核对（曝光与转化事件成对,product-design 埋点规范）;
+7. 登记：实验台账（假设/指标/流量/起止/负责人）——不登记的实验=部落知识。
+
+## 分析纪律（结果出来后）
+
+- **先 SRM 后结论**：`srm_check()` 卡方检验分流比例——SRM 不过（p<0.001）说明分流有 bug,
+  **结果直接作废**,别解读;
+- 显著性：`ztest_2prop()` 双比例 z 检验——报告**效应量+置信区间**,不只 p 值
+  （"提升 2.1%,95%CI [0.4%, 3.8%],p=0.014"）;
+- **不许偷看提前停**：到样本量/时长才读数（偷看使假阳性率飙升;要提前停就预先声明序贯方法）;
+- 多重比较：同时看 N 个指标/分组,显著阈值要校正（Bonferroni 除 N 起步）或明示"探索性发现,
+  需复跑验证";
+- 分层解读：总体不显著但某分层显著 → **只能作为下一个实验的假设**,不能直接下结论（辛普森陷阱）;
+- 业务显著 ≠ 统计显著：显著但提升 0.1% 不值得工程成本的,如实说"统计显著、业务不显著"。
+
+## 常见坑清单（复盘对照）
+
+新奇效应（上线初期虚高,看分周趋势）/ 学习效应（老用户适应期）/ 溢出污染
+（实验组行为影响对照组:社交/供需场景）/ 幸存者偏差（只统计完成流程的用户）/
+指标口径漂移（实验期间口径变更=作废重跑）。
+
+## 结论报告模板
+
+背景与假设 → 设计参数（样本量/时长/分流）→ SRM 与数据质量 → 主指标结果
+（效应+CI+p）→ 护栏检查 → 分层观察（标注探索性）→ 决策建议
+（全量/回滚/加大样本复跑）→ 台账归档。
+
+## 验收自查
+
+- [ ] 开跑前七步齐,样本量有计算过程
+- [ ] SRM 先于结论;无偷看提前停
+- [ ] 报告效应量+CI;多指标做了校正或标注
+- [ ] 护栏指标过检;分层结论未越界
+
+## 附件
+
+- `scripts/ab_test.py` — sample_size（双比例）/ ztest_2prop（效应+CI+p）/ srm_check（卡方）;可直接执行自测

package/skills/ab-testing/scripts/ab_test.py

@@ -0,0 +1,71 @@
+# AB 实验计算件（经 run_python 执行）：双比例样本量 / 双比例 z 检验（效应+95%CI+p）/ SRM 卡方校验。
+# 仅用 math（正态近似），不依赖 scipy。直接执行本文件 = 自测。
+import math
+
+Z_ALPHA2 = {0.10: 1.6449, 0.05: 1.9600, 0.01: 2.5758}          # 双侧显著性 α → z_{1-α/2}
+ZP = {0.80: 0.8416, 0.85: 1.0364, 0.90: 1.2816, 0.95: 1.6449}  # 功效 → z_{power}
+
+
+def _phi(x):
+    """标准正态 CDF（误差函数式）。"""
+    return 0.5 * (1 + math.erf(x / math.sqrt(2)))
+
+
+def sample_size(baseline, mde_rel, alpha=0.05, power=0.80):
+    """双比例每组样本量（正态近似）：baseline=基线转化率，mde_rel=相对最小可检测效应（如 0.03=+3%）。"""
+    p1 = baseline
+    p2 = baseline * (1 + mde_rel)
+    za = Z_ALPHA2[alpha]
+    zb = ZP[power]
+    pbar = (p1 + p2) / 2
+    n = ((za * math.sqrt(2 * pbar * (1 - pbar)) + zb * math.sqrt(p1 * (1 - p1) + p2 * (1 - p2))) ** 2
+         / (p2 - p1) ** 2)
+    n = math.ceil(n)
+    print(f'[样本量] 基线 {p1:.2%} → 目标 {p2:.2%}（相对 +{mde_rel:.1%}），α={alpha} 功效={power:.0%} '
+          f'→ 每组 {n:,} 个（两组共 {2 * n:,}）')
+    return n
+
+
+def ztest_2prop(x1, n1, x2, n2, alpha=0.05):
+    """双比例 z 检验：返回 绝对效应/相对效应/95%CI/p 值（双侧）。组1=对照，组2=实验。"""
+    p1, p2 = x1 / n1, x2 / n2
+    diff = p2 - p1
+    pp = (x1 + x2) / (n1 + n2)
+    se_pooled = math.sqrt(pp * (1 - pp) * (1 / n1 + 1 / n2))
+    z = diff / se_pooled if se_pooled else 0.0
+    p_val = 2 * (1 - _phi(abs(z)))
+    se_ci = math.sqrt(p1 * (1 - p1) / n1 + p2 * (1 - p2) / n2)
+    zc = Z_ALPHA2[alpha]
+    ci = (diff - zc * se_ci, diff + zc * se_ci)
+    sig = p_val < alpha
+    print(f'[z检验] 对照 {p1:.3%}（{x1}/{n1}） vs 实验 {p2:.3%}（{x2}/{n2}）')
+    print(f'  绝对效应 {diff:+.3%}，相对 {diff / p1:+.2%}，95%CI [{ci[0]:+.3%}, {ci[1]:+.3%}]，'
+          f'p={p_val:.4f} → {"统计显著" if sig else "不显著"}（α={alpha}）')
+    return {'diff': diff, 'rel': diff / p1 if p1 else float("nan"), 'ci': ci, 'p': p_val, 'significant': sig}
+
+
+def srm_check(n1, n2, expected_ratio=0.5, threshold=0.001):
+    """SRM 样本比例失配：卡方拟合检验（df=1）。p < threshold → 分流有 bug，结果作废。"""
+    total = n1 + n2
+    e1, e2 = total * expected_ratio, total * (1 - expected_ratio)
+    chi2 = (n1 - e1) ** 2 / e1 + (n2 - e2) ** 2 / e2
+    # df=1 的卡方 p 值 = 2*(1-Φ(sqrt(chi2)))
+    p = 2 * (1 - _phi(math.sqrt(chi2)))
+    ok = p >= threshold
+    print(f'[SRM] {n1:,} vs {n2:,}（期望 {expected_ratio:.0%}），χ²={chi2:.2f}，p={p:.5f} → '
+          + ('通过 ✓' if ok else '❌ 失配：分流异常，本次实验结果作废，先排查分流/埋点'))
+    return ok, p
+
+
+if __name__ == '__main__':
+    n = sample_size(baseline=0.05, mde_rel=0.10, alpha=0.05, power=0.80)
+    assert 28000 < n < 34000, n  # 5% 基线检 +10% 相对提升的量级
+    r = ztest_2prop(x1=500, n1=10000, x2=565, n2=10000)
+    assert r['significant'] and r['ci'][0] > 0
+    r2 = ztest_2prop(x1=500, n1=10000, x2=505, n2=10000)
+    assert not r2['significant'] and r2['ci'][0] < 0 < r2['ci'][1]
+    ok, _ = srm_check(50000, 50100)
+    assert ok
+    ok2, _ = srm_check(50000, 52000)
+    assert not ok2  # 4% 失配应判失败
+    print('OK ab_test.py')

package/skills/academic-writing/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: academic-writing
+description: 学术写作与投稿（论文结构、摘要引言打磨、图表规范、投稿信 cover letter、审稿意见回复 rebuttal、学位论文）。当用户说"写论文/改摘要/投稿/回复审稿人/开题/学位论文"时使用。
+version: 1.0.0
+---
+
+# 学术写作（结构规范 + 论证闭环 + 投稿攻防）
+
+## 学术诚信红线（先行）
+
+**不代写造假**：辅助结构/语言/逻辑,数据与实验结论必须来自用户;引用只列用户提供或明确存在的文献,
+**绝不编造文献与 DOI**——拿不准的标「请核实」;涉及 AI 辅助声明按目标期刊政策提示用户。
+
+## 论文结构（IMRaD 及各节写法）
+
+- **Abstract**（最后写）：背景一句 → 空白/问题一句 → 方法一句 → 关键结果（带数字）1–2 句 →
+  意义一句;150–250 词;无引用无缩写首现;
+- **Introduction 漏斗式**：领域重要性 → 已有工作与局限（综述走 tech-research 矩阵法,
+  对相关工作**归类评述**而非罗列）→ 本文问题与贡献（编号列出,与实验一一对应）;
+- **Method**：可复现标准——别人按此节能重做（参数/数据/环境）;选择性描述要给依据;
+- **Results**：图表先行,文字讲"图说明了什么"而非复读数据;统计显著性规范（检验方法/p 值/效应量/
+  置信区间,多重比较校正注明）;
+- **Discussion**：结果解释 → 与前人对照（一致/矛盾及可能原因）→ 局限（真实的,审稿人反正会发现）→
+  展望;**结论不越界**：样本/场景边界内说话;
+- **图表规范**：自明性（脱离正文可读:完整题注/轴与单位/图例）;矢量或 ≥300dpi;
+  数据图走 data-analysis 规范。
+
+## 语言打磨（学术英语）
+
+主张动词分级（demonstrate>show>suggest>may indicate——证据强度匹配）;
+每段首句=主题句;剪 hedging 堆叠（"may possibly suggest"）与冗词（"in order to"→to）;
+时态惯例：方法结果过去时,普适结论现在时。
+
+## 投稿与攻防
+
+- **选刊**：范围匹配>影响因子;查 Aims&Scope 与近两年相似主题文章;给 2–3 备选梯队;
+- **Cover letter**：一页——研究问题与新贡献（对刊物读者的价值）+ 合规声明（原创/无一稿多投/
+  利益冲突）+ 建议/回避审稿人（如政策允许）;
+- **Rebuttal（回复审稿人）**：逐条编号引用原意见 → 感谢+回应（同意→改了什么在第几页;
+  部分同意→做了什么+保留什么及理由;不同意→**证据说话,语气恭敬立场坚定**）→ 修改对照表;
+  所有承诺的修改必须真实落在修订稿——回复与稿子不一致是大忌;
+- 拒稿再投：先按意见实改再投别家,同批审稿人撞上没改的稿子=声誉损失。
+
+## 学位论文
+
+章节骨架按培养单位模板;各章衔接段（承上启下明示逻辑链）;开题报告=tech-research 综述 +
+project-proposal 的进度与可行性范式;盲审自查：创新点表述/工作量证据/格式规范三查。
+
+## 验收自查
+
+- [ ] 贡献-实验-结论三者一一对应
+- [ ] 文献真实可核;统计报告规范
+- [ ] 结论未越界;局限真实
+- [ ] rebuttal 逐条闭环且与修订稿一致

package/skills/accounting-ops/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: accounting-ops
+description: 日常核算与账务处理（收入收款、采购付款、资产管理、薪酬往来、期末结账与三大报表）。当用户说"账龄/催款/对流水/发票校验/排款/折旧/计提/工资核算/月结/结账/试算平衡"时使用。财务技能链之核算环。
+version: 1.0.0
+---
+
+# 日常核算与账务处理（财务技能链 · 核算环；全景见 finance-chain）
+
+会计处理以企业会计准则与现行法规为准;重大判断（收入确认时点/减值/资本化）标注"建议与审计师沟通"。
+
+## 1. 收入与收款
+
+- **收入确认（准则五步法过一遍再入账）**：识别合同 → 履约义务 → 交易价格（可变对价约束）→
+  分摊 → **控制权转移时点确认**（时点 vs 时段;总额 vs 净额=主要责任人判定）——
+  开票≠收入、收款≠收入,口径表先行;
+- 开票管理：合同-发票-收入三方一致（品名/金额/税率）,红字发票场景与流程;
+- **应收账龄**（`read_skill_file` 读 `scripts/acct_tools.py`）：`aging()` 分桶（30/60/90/180+）
+  +客户维度排序+**催款优先级**（金额×账龄权重）;催款函走 email-writing 三级阶梯,
+  90+ 天客户给"停止赊销评估"提示;坏账计提政策（账龄组合计提比例表,参数化）;
+- 银行流水核对：流水 vs 应收核销（data-report-pro 的 recon_diff 三清单法）,
+  未达账项编制银行存款余额调节表（四类:银收企未收/银付企未付/企收银未收/企付银未付）。
+
+## 2. 采购与付款
+
+- **三单匹配**：订单-入库-发票（数量/单价/税率逐项,容差写死）,不匹配挂异常清单不入账;
+- 发票校验清单：抬头税号/品目与业务一致/税率正确/连号大额警觉/查验真伪提示;
+- **排款计划**：按到期日+账期+供应商等级排周付款计划（联动 treasury-mgmt 资金头寸——
+  排款超头寸自动触发缺口预警）;付款审批链与权限矩阵（内控:申请/审批/复核/支付分离）;
+- 预付款台账：预付-核销-余额滚动,长龄预付（>90 天未核销）= 红旗清单;
+- 报销审核清单：预算内?标准内（差旅/招待标准表）?凭证合规（发票抬头/连号/时间逻辑）?
+  审批链完整?——逐项打勾,拒付给依据。
+
+## 3. 资产管理
+
+- 固定资产：折旧政策表（类别×年限×残值率×方法）+ `depreciation()` 批量折旧表
+  （直线法,月折旧/累计/净值,**购置当月不提次月起提**口径可调）;在建工程转固时点
+  （达到预定可使用状态,长期挂账=红旗）;处置损益计算;
+- 无形资产摊销同口径;使用寿命不确定的不摊销做减值测试（提示判断）;
+- 存货：盘点程序（audit-assist 监盘口径）、盘盈盘亏处理路径、**跌价准备**
+  （可变现净值=售价−至完工成本−销售费用,库龄长+售价跌=计提信号,联动 supply 库龄表）。
+
+## 4. 薪酬往来
+
+工资核算流程：考勤/绩效输入 → 应发（基本+绩效+加班+补贴）→ 代扣
+（社保公积金个人部分+**个税**:tax-compliance 的 iit_salary 累计预扣提示）→ 实发;
+计提与发放分录逻辑（当月计提次月发放的期间归属）;年终奖计税两案对比（iit_bonus）;
+薪酬数据保密纪律（最小可见,输出前确认脱敏）。
+
+## 5. 期末结账（月/季/年）
+
+- **结账清单**（顺序执行,漏一项报表就是错的）：收入截止核对 → 成本结转 → 计提
+  （工资/折旧摊销/利息/税金）→ 暂估入库 → 往来核对（内往抵消）→ 汇兑损益 → 结转损益;
+- `trial_balance()` **科目余额表试算平衡**（借贷合计校验,不平给差额与排查方向:
+  差额÷2 查借贷反向/差额÷9 查移位错）;
+- 三大报表出具顺序：利润表 → 资产负债表 → 现金流量表（间接法从净利调起）,
+  出完立即跑 finance-analysis 勾稽校验（不过=回去查账,不许带病出表）;
+- 结账日历：D-3 提醒各单据截止、D+5 出表（office-automation 例程配方见 finance-chain）。
+
+## 验收自查
+
+- [ ] 收入确认过五步法,开票/收款/收入三口径分清
+- [ ] 账龄与排款联动资金;三单不匹配未入账
+- [ ] 折旧摊销政策表化,长龄预付/在建有红旗清单
+- [ ] 试算平衡通过;报表勾稽（finance-analysis）通过后才出具
+
+## 附件
+
+- `scripts/acct_tools.py` — aging 账龄与催款优先级 / depreciation 批量折旧表 / trial_balance 试算平衡与差错方向;可直接执行自测

package/skills/accounting-ops/scripts/acct_tools.py

@@ -0,0 +1,89 @@
+# 核算三件套（经 run_python 执行）：应收账龄与催款优先级 / 固定资产批量折旧表 / 试算平衡。
+# 直接执行本文件 = 自测。
+import numpy as np
+import pandas as pd
+
+AGING_BUCKETS = [(30, '0-30天'), (60, '31-60天'), (90, '61-90天'), (180, '91-180天'), (10 ** 9, '180天以上')]
+AGING_WEIGHT = {'0-30天': 0.2, '31-60天': 0.5, '61-90天': 1.0, '91-180天': 2.0, '180天以上': 4.0}
+
+
+def aging(df, cust_col='客户', amt_col='金额', date_col='应收日期', asof=None):
+    """应收账龄：分桶 + 客户汇总 + 催款优先级（金额×账龄权重）。返回 (明细, 客户汇总, 分桶汇总)。"""
+    d = df.copy()
+    d[date_col] = pd.to_datetime(d[date_col])
+    asof = pd.to_datetime(asof) if asof else pd.Timestamp.today().normalize()
+    d['账龄天数'] = (asof - d[date_col]).dt.days.clip(lower=0)
+    d['账龄段'] = d['账龄天数'].map(lambda x: next(lbl for cap, lbl in AGING_BUCKETS if x <= cap))
+    d['催款权重分'] = d[amt_col] * d['账龄段'].map(AGING_WEIGHT)
+    by_bucket = d.groupby('账龄段', observed=True)[amt_col].agg(['sum', 'count'])
+    by_bucket['占比%'] = (by_bucket['sum'] / d[amt_col].sum() * 100).round(1)
+    order = [lbl for _, lbl in AGING_BUCKETS]
+    by_bucket = by_bucket.reindex([x for x in order if x in by_bucket.index])
+    by_cust = d.groupby(cust_col, observed=True).agg(
+        应收合计=(amt_col, 'sum'), 最长账龄=('账龄天数', 'max'),
+        催款优先分=('催款权重分', 'sum')).sort_values('催款优先分', ascending=False)
+    over90 = d[d['账龄天数'] > 90][amt_col].sum()
+    print(f'[账龄] 截至 {asof.date()} · 应收合计 {d[amt_col].sum():,.0f} · 90+ 天 {over90:,.0f}'
+          f'（{over90 / d[amt_col].sum():.1%}）' + ('  ⚠ 90+ 占比高：启动停止赊销评估' if over90 / d[amt_col].sum() > 0.2 else ''))
+    print(by_bucket.to_markdown())
+    print('[催款优先] TOP：\n' + by_cust.head(10).to_markdown())
+    return d, by_cust, by_bucket
+
+
+def depreciation(assets, asof_month, cur_month_no_dep=True):
+    """批量直线法折旧：assets 列[资产, 原值, 残值率, 年限年, 启用日期]。
+    口径：购置当月不提、次月起提（cur_month_no_dep 可关）。返回含 本月折旧/累计折旧/净值。"""
+    d = assets.copy()
+    asof = pd.Period(asof_month, freq='M')
+    start = pd.to_datetime(d['启用日期']).dt.to_period('M')
+    used = (asof - start).map(lambda x: x.n) + (0 if cur_month_no_dep else 1)
+    total_m = d['年限年'] * 12
+    d['月折旧'] = ((d['原值'] * (1 - d['残值率'])) / total_m).round(2)
+    d['已提月数'] = np.minimum(np.maximum(used, 0), total_m)
+    d['本月折旧'] = np.where((used >= 1) & (used <= total_m), d['月折旧'], 0.0)
+    d['累计折旧'] = (d['月折旧'] * d['已提月数']).round(2)
+    d['净值'] = (d['原值'] - d['累计折旧']).round(2)
+    print(f"[折旧] {asof} · 本月折旧合计 {d['本月折旧'].sum():,.2f} · 净值合计 {d['净值'].sum():,.2f}")
+    print(d[['资产', '原值', '月折旧', '已提月数', '本月折旧', '累计折旧', '净值']].to_markdown(index=False))
+    return d
+
+
+def trial_balance(entries, acct_col='科目', dr_col='借方', cr_col='贷方', tol=0.005):
+    """科目余额表试算平衡：借贷合计校验；不平给差额与经典排查方向（÷2 反向 / ÷9 移位）。"""
+    g = entries.groupby(acct_col, observed=True)[[dr_col, cr_col]].sum()
+    g['余额(借正)'] = (g[dr_col] - g[cr_col]).round(2)
+    td, tc = float(g[dr_col].sum()), float(g[cr_col].sum())
+    diff = round(td - tc, 2)
+    balanced = abs(diff) <= tol
+    print(f'[试算] 借方合计 {td:,.2f} vs 贷方合计 {tc:,.2f} → ' + ('平衡 ✓' if balanced else f'不平，差额 {diff:+,.2f}'))
+    if not balanced:
+        hints = []
+        if abs(diff) % 2 < tol or abs(round(diff / 2, 2)) in set(entries[dr_col].abs().round(2)) | set(entries[cr_col].abs().round(2)):
+            hints.append(f'差额÷2={abs(diff) / 2:,.2f}：查是否有金额记反借贷方向')
+        if abs(diff) % 9 < tol:
+            hints.append('差额可被 9 整除：查数字移位/颠倒（如 540 记成 450）')
+        hints.append('按科目二分核对：先对差额最大的科目组')
+        print('  排查方向：' + '；'.join(hints))
+    print(g.to_markdown())
+    return g, balanced, diff
+
+
+if __name__ == '__main__':
+    ar = pd.DataFrame({'客户': ['甲', '甲', '乙', '丙'], '金额': [100000, 50000, 80000, 30000],
+                       '应收日期': ['2026-06-20', '2026-03-01', '2026-05-10', '2025-11-30']})
+    detail, by_cust, bucket = aging(ar, asof='2026-07-15')
+    assert detail.loc[3, '账龄段'] == '180天以上'
+    assert by_cust.index[0] in ('甲', '丙')  # 高权重靠前
+    assets = pd.DataFrame({'资产': ['服务器', '产线'], '原值': [120000, 600000],
+                           '残值率': [0.05, 0.05], '年限年': [5, 10], '启用日期': ['2026-05-15', '2020-01-10']})
+    dep = depreciation(assets, '2026-07')
+    assert abs(dep.loc[0, '月折旧'] - 120000 * 0.95 / 60) < 0.01 and dep.loc[0, '已提月数'] == 2
+    assert dep.loc[1, '本月折旧'] > 0
+    ok_entries = pd.DataFrame({'科目': ['银行存款', '应收账款', '主营业务收入'],
+                               '借方': [500, 500, 0], '贷方': [0, 0, 1000]})
+    _, balanced, _ = trial_balance(ok_entries)
+    assert balanced
+    # 经典移位错：540 记成 450，差额 90 可被 9 整除 → 应给出移位排查提示
+    _, balanced2, diff2 = trial_balance(pd.DataFrame({'科目': ['A', 'B'], '借方': [540, 0], '贷方': [0, 450]}))
+    assert not balanced2 and abs(diff2 - 90) < 0.01
+    print('OK acct_tools.py')

package/skills/ai-agent/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: ai-agent
+description: Agent 工程链（工作流 vs Agent 判据→工具设计即 API 设计(描述/粒度/可行动错误)→循环护栏(步数/预算/重复检测)→上下文与记忆管理→工具权限四级沙箱→审计留痕→多 Agent 拆分判据与编排模式→轨迹回放评测→人机协作打断判据）。eng-ai 的智能体孙链:做自动执行任务的 AI、Agent 跑飞/死循环/越权风险治理、多 Agent 架构评审时载入。
+version: 1.0.0
+---
+
+# Agent 工程链
+
+eng-ai 的智能体孙链。Agent=LLM 在循环里自主决定下一步并调用工具。
+第一判据永远是:**这活需要自主性吗?**——自主性是用确定性、成本、可测性换的,不是免费的酷。
+
+## 工作流 vs Agent 判据
+
+| 特征 | 用工作流(固定编排) | 用 Agent(动态规划) |
+|---|---|---|
+| 步骤 | 可预先写清(抽取→校验→入库) | 依中间结果而变(排查问题/多轮找资料) |
+| 确定性要求 | 高(审批/对账) | 容忍探索 |
+| 成本与延迟 | 可控优先 | 接受多轮调用 |
+| 测试 | 每步可单测 | 只能端到端+轨迹评估 |
+
+**能用工作流别上 Agent**;混合形态是常态:外层工作流锁流程,不确定的环节内嵌小 Agent。
+LLM 只做一次判断(分类/生成)的不叫 Agent,别把简单问题 Agent 化。
+
+## 工具设计（Agent 质量的第一决定因素）
+
+- **工具即 API 设计**(api-design 思维):名称动宾结构、描述说清"何时用我/何时别用我"、参数带格式与示例、能枚举不自由;
+- 粒度判据:面向任务的高层工具(query_orders(条件))优于原子工具堆(connect_db/execute_sql)——步数少一半,错处少一半;但过度封装丧失灵活,按任务画像折中;
+- **错误信息可行动**:"日期需 YYYY-MM-DD,收到'昨天'"——Agent 靠错误自愈,"操作失败"=逼它瞎猜;错误里给建议("未找到,试试模糊搜索 search_fuzzy");
+- 返回瘦身:工具返回给模型的内容裁剪到任务所需(整表 JSON 灌回去=烧上下文+淹没重点);超长结果分页+摘要;
+- 工具数量:单场景挂载 ≤15 个为宜,多了按场景分组动态挂载(ai-llm-app 工具节)。
+
+## 循环护栏（没有护栏的 Agent=不定时账单炸弹）
+
+**四闸必配**:最大步数(按任务画像定,超限优雅收尾"已达步数上限,当前进展…")/token 预算(单任务费用上限)/
+超时(墙钟时间)/**重复检测**(连续同工具同参数 N 次=死循环,熔断);
+中间自检判据:长任务每 N 步让模型对照原始目标复述进展(防跑题漂移);
+失败处置:工具连续失败→换路径提示;彻底卡死→带上下文转人工(半成品也有价值,别静默丢弃)。
+
+## 上下文与记忆
+
+短期=对话上下文:步数多了滚动压缩(早期步骤摘要化,保留目标与关键结论,ai-llm-app 预算纪律);
+长期=外置存储:跨会话要记的(用户偏好/任务档案)显式写入检索式记忆(本质是私有 RAG,ai-rag 纪律适用);
+**状态持久化**:长任务的步骤状态落盘,断点可恢复(进程重启不从头烧钱重跑);
+工作产物走文件/存储传递,不在上下文里搬运大 payload。
+
+## 安全沙箱（工具权限四级,eng-security 落点）
+
+| 级 | 工具类型 | 授权 |
+|---|---|---|
+| 只读 | 查询/搜索/读文件 | 自动执行 |
+| 低危写 | 写草稿/建任务/发内部通知 | 自动执行+留痕 |
+| 高危写 | 改数据/对外发送/花钱 | **人确认后执行**(确认页带影响说明) |
+| 禁区 | 删库/权限变更/资金操作 | 不做成工具,流程走人(eng-ops) |
+
+环境隔离:代码执行类工具进沙箱(容器/受限运行时,文件与网络白名单);
+凭证纪律:Agent 用**降权专用凭证**(不是借用户全权;它被注入时爆炸半径=凭证权限,ai-llm-app 注入防护);
+**审计全留痕**:每步 思考摘要/工具/参数/结果 落审计日志(出事可还原,合规可查,eng-observability)。
+
+## 多 Agent 判据（默认单体,拆分要理由）
+
+拆的正当理由:上下文装不下(各管一摊资料)/角色目标冲突(起草者 vs 审查者要独立立场)/权限隔离(高危工具只给审批 Agent);
+**不拆的理由更常见**:多 Agent=多倍成本+通信损耗+调试地狱——单 Agent+好工具能解决的别拆;
+编排模式判据:主从(总控派活,默认)/流水线(阶段清晰)/辩论(质量关键且值得双倍成本,如审查场景);
+Agent 间通信结构化(任务书:目标/输入/期望产出/预算),别自由聊天。
+
+## 评测（ai-eval 承接方法论,Agent 特有部分）
+
+端到端:任务成功率(硬标准:任务真完成没)+成本分布(P50/P99 步数与 token)+人工干预率;
+**过程评测靠轨迹回放**:失败案例逐步看哪步走偏(工具选错/参数错/理解错/该停不停)——失败模式分类统计决定优化点(工具描述?护栏?提示?);
+回归:改工具/提示/模型后任务集重跑(录制的确定性工具响应做回放,ai-llm-app 录制回放);
+上线后:干预率与成功率进监控(ai-mlops),劣化即回查。
+
+## 人机协作
+
+打断问人判据(写进系统提示):关键决策不可逆时/信息缺失且猜错代价高时/权限不足时——**宁可多问一次,不可自作聪明一次**(高危场景);
+进度可见:长任务实时播报当前步骤(用户敢交托的前提是看得见);
+产物交付带过程摘要(做了什么/依据什么/哪些没做到),不是只甩结果。
+
+**作业包**:`references/tool-design-checklist.md`(工具设计评审表/权限四级登记/护栏四闸配置/轨迹评测项——上线准入)。
+
+## 使用纪律
+
+上 Agent 前先答"为什么工作流不行";四闸护栏与权限分级是上线准入(eng-ai 红线);
+每次跑飞/死循环/越权事故回写:护栏参数或工具设计;
+**Agent 的复利在工具质量与失败模式库,模型升级只是放大器**。

package/skills/ai-agent/references/tool-design-checklist.md

@@ -0,0 +1,51 @@
+# Agent 工具设计与护栏配置单（ai-agent 落笔件）
+
+## 0. 立项判据(先答"为什么工作流不行")
+
+步骤可预先写清? □是→工作流,别上 Agent  □否(依中间结果而变)→继续
+混合形态优先:外层工作流锁流程,不确定环节内嵌小 Agent。
+
+## 1. 工具设计评审(每个工具一行)
+
+| 工具名(动宾) | 描述含"何时用/何时别用"? | 参数枚举化? | 错误信息可行动? | 返回瘦身(分页/摘要)? | 权限级 |
+|---|---|---|---|---|---|
+
+- [ ] 单场景挂载 ≤15 个(多了分组动态挂载)
+- [ ] 粒度检查:面向任务的高层工具优先(query_orders 优于 connect_db+execute_sql 堆)
+- [ ] 错误样例过一遍:"操作失败"=逼模型瞎猜;"date 需 YYYY-MM-DD,收到'昨天'"=可自愈
+
+## 2. 权限四级登记(eng-security 落点)
+
+| 级 | 本 Agent 的工具 | 授权 |
+|---|---|---|
+| 只读 | __ | 自动执行 |
+| 低危写 | __ | 自动+留痕 |
+| 高危写 | __ | **人确认后执行**(确认页带影响说明) |
+| 禁区 | __(删库/权限/资金) | 不做成工具 |
+
+- [ ] 凭证降权:专用受限凭证(非用户全权;被注入时爆炸半径=凭证权限)
+- [ ] 代码执行类工具进沙箱(文件与网络白名单):__
+
+## 3. 循环护栏四闸(缺一不上线)
+
+| 闸 | 值 | 触发动作 |
+|---|---|---|
+| 最大步数 | __ | 优雅收尾"已达上限,当前进展__" |
+| token/费用预算 | __ | 同上+告警 |
+| 墙钟超时 | __ | |
+| 重复检测 | 同工具同参数 __ 次 | 熔断+换路径提示 |
+
+- [ ] 中间自检:每 __ 步对照原始目标复述进展(防跑题)
+- [ ] 彻底卡死→带上下文转人工(半成品不静默丢)
+
+## 4. 记忆与留痕
+
+- [ ] 长任务状态落盘可断点恢复(重启不重烧);产物走文件不灌上下文
+- [ ] 审计日志全留痕:每步 思考摘要/工具/参数/结果(出事可还原)
+
+## 5. 评测与上线(ai-eval)
+
+- [ ] 任务集端到端成功率 __%;成本分布 P50/P99 步数 __/__
+- [ ] 失败轨迹回放分类:工具选错/参数错/理解错/该停不停 → 优化点 __
+- [ ] 打断问人判据写进系统提示(不可逆/信息缺/权限不足——宁多问一次)
+- [ ] 进度对用户可见;产物附过程摘要(做了什么/依据/没做到什么)