finance-copilot-skills（财务助手 Skill 工具集）

简体中文 | English

finance-copilot-skills 是一套装进你已经在用的 AI 编程代理（Claude Code / Codex / WorkBuddy）的财务工作流 Skill，简体中文优先——程序管算（金额、匹配、勾稽由本地确定性代码完成），AI 管引导与解释（问清字段、说明结果、提醒风险），人管业务判断（哪笔算对上、哪笔要追、要不要放行）。面向财务、审计人员与中小企业管理者：不用会 Python、不用敲命令，账也不上传到任何地方。它不是 ERP、财务系统或记账软件，而是在你现有的 Excel / CSV / 本地文件工作流之上，补一组"小而专"的独立 Skill——装一个不必装一整套。当前 v0.3.0：1 个已发布 Skill fcs-reconcile（对账，发布状态 Preview），另有 8 个候选方向待真实需求验证。每个 Skill 的准确状态、平台支持与测试情况以各自的 SKILL_META.yaml 为准。

设计理念

确定性的事交给程序，模糊的事交给人，AI 只在两者之间做翻译。

财务工作里最耗时的那部分（多文件提取、格式清洗、流水与台账核对、勾稽检查）规则相对稳定、却极易因复制粘贴和公式出错；最不该自动化的那部分（这笔差额算不算手续费、这笔在途要不要追、能不能放行）依赖业务判断与责任承担。通用 AI 的问题恰恰是把两者搞反了：用不确定的推理去代替确定性计算，同一份数据两次跑出不同结果，还不告诉你文件有没有被上传、保存、用于训练。

本工具集把这条线划死：金额计算、匹配、勾稽、格式转换、规则校验一律由可重复执行的本地程序完成；AI 负责理解你的意图、引导字段确认、解释结果、提醒风险；AI 不猜金额、不在多个候选里任选一个、不编造差异原因、不在规则不明确时自动确认、不替财务人员做最终业务判断。

不可退让的底线：任何不确定的匹配一律不自动放行；每个结果都说清用了什么输入、什么规则、依据是什么、哪些仍需人工确认；原始明细默认不进入模型上下文。

冲突仲裁：严谨性一票否决。 不得为了"发布更快、流程更轻、少一次人工确认"而放松确定性校验、跳过测试或模糊化数据流披露。看似两难时，通常意味着流程本身该重新设计——"人工确认拖慢流程"要优化确认环节，而不是放宽自动确认条件（PRD §1.2）。

免费不以数据为代价：核心能力免费，且不通过收集、出售、训练或分析你的财务数据获得收益。不设隐藏付费墙、不强制注册、不默认上传使用记录、不在你不知情时启用遥测。

✅ 会做的 / ⛔ 不做的

"不自动放行"不是能力缺口，是责任边界。 对账里"看起来能配上"的那一笔，恰恰是最需要人看的那一笔。所以容差在这里只做差异分级，不放宽自动确认：金额差 8 元可能是手续费，也可能是少收了钱，程序不替你定性，只把它排到「待处理事项」的显眼位置，附上左右金额、差异、来源行与建议动作。

每条边界的出处见 PRD §2.5 非目标 与 §四 设计原则；对账的自动确认铁律见 matching-rules.md。

财务工作流 × 工具集能力

候选不等于路线图上的承诺。 每个新 Skill 都要过独立需求验证（有真实用户、有重复出现的任务、可验证输入输出、确定性部分可程序化、安全边界明确、至少一组脱敏测试数据与黄金答案），不因"工具集想做大"就自动立项（PRD §8.2）。涉及 PDF、OCR、税务、凭证或生产系统连接的 Skill，还要单独过安全评审。

快速开始

现在能用的是对账：把你导出的银行流水和收付款台账两份文件交给它，本地跑出 7 张中文工作表的结果工作簿。仓库里备了演示数据，装完 3 分钟就能看到完整产物。

安装

复制下面对应你的代理的那段话，粘贴给它就行——它会自己装完，你不用敲任何命令，也不用改里面的任何一个字。三段话只有目标目录不同，各自都是完整的。

装到 Claude Code 👇

帮我安装 finance-copilot-skills 财务助手 Skill 工具集：

1. 把 https://github.com/cxtx/finance-copilot-skills 克隆到一个临时目录
2. 确保 ~/.claude/skills/ 存在（没有就创建），把仓库 skills/ 下的**全部子目录**
   复制进去，一个都不能少（当前 1 个：fcs-reconcile）
   - 复制的是子目录本身，别把整个 skills/ 目录整体套进去——多套一层，技能名会
     变成 skills:fcs-reconcile
   - 每个 skill 目录要整体复制：SKILL.md、SKILL_META.yaml、requirements.txt、LICENSE
     与 scripts/ references/ examples/ 都得在，缺 scripts/ 就只能被发现、跑不了对账
   - 同名目录直接覆盖，这就是更新
   - 该目录下其他来源的 skill 一个都别动，千万不要清空目录
3. 装运行时依赖（**只有这一步需要网络**）：
   python -m pip install -r ~/.claude/skills/fcs-reconcile/requirements.txt
   - 用哪个 python 装，后面就得用哪个 python 跑对账脚本，必须是同一个解释器
   - 装完把 pandas / openpyxl / pyyaml 的实际版本告诉我
   - 装不上就把报错原样给我，别跳过这步当作装好了——缺依赖时对账脚本会直接失败
4. 删掉临时目录
5. 告诉我装到了哪里、装了哪些 skill、依赖装在哪个解释器下

装到 Codex 👇

帮我安装 finance-copilot-skills 财务助手 Skill 工具集：

1. 把 https://github.com/cxtx/finance-copilot-skills 克隆到一个临时目录
2. 确保 ~/.codex/skills/ 存在（没有就创建），把仓库 skills/ 下的**全部子目录**
   复制进去，一个都不能少（当前 1 个：fcs-reconcile）
   - 复制的是子目录本身，别把整个 skills/ 目录整体套进去——多套一层，技能名会
     变成 skills:fcs-reconcile
   - 每个 skill 目录要整体复制：SKILL.md、SKILL_META.yaml、requirements.txt、LICENSE
     与 scripts/ references/ examples/ 都得在，缺 scripts/ 就只能被发现、跑不了对账
   - 同名目录直接覆盖，这就是更新
   - 该目录下其他来源的 skill 一个都别动，千万不要清空目录
3. 装运行时依赖（**只有这一步需要网络**）：
   python -m pip install -r ~/.codex/skills/fcs-reconcile/requirements.txt
   - 用哪个 python 装，后面就得用哪个 python 跑对账脚本，必须是同一个解释器
   - 装完把 pandas / openpyxl / pyyaml 的实际版本告诉我
   - 装不上就把报错原样给我，别跳过这步当作装好了——缺依赖时对账脚本会直接失败
4. 删掉临时目录
5. 告诉我装到了哪里、装了哪些 skill、依赖装在哪个解释器下

装到 WorkBuddy 👇

帮我安装 finance-copilot-skills 财务助手 Skill 工具集：

1. 把 https://github.com/cxtx/finance-copilot-skills 克隆到一个临时目录
2. 确保 ~/.workbuddy/skills/ 存在（没有就创建），把仓库 skills/ 下的**全部子目录**
   复制进去，一个都不能少（当前 1 个：fcs-reconcile）
   - 复制的是子目录本身，别把整个 skills/ 目录整体套进去——多套一层，技能名会
     变成 skills:fcs-reconcile
   - 每个 skill 目录要整体复制：SKILL.md、SKILL_META.yaml、requirements.txt、LICENSE
     与 scripts/ references/ examples/ 都得在，缺 scripts/ 就只能被发现、跑不了对账
   - 同名目录直接覆盖，这就是更新
   - 该目录下其他来源的 skill 一个都别动，千万不要清空目录
3. 装运行时依赖（**只有这一步需要网络**）：
   python -m pip install -r ~/.workbuddy/skills/fcs-reconcile/requirements.txt
   - 用哪个 python 装，后面就得用哪个 python 跑对账脚本，必须是同一个解释器
   - 装完把 pandas / openpyxl / pyyaml 的实际版本告诉我
   - 装不上就把报错原样给我，别跳过这步当作装好了——缺依赖时对账脚本会直接失败
4. 删掉临时目录
5. 告诉我装到了哪里、装了哪些 skill、依赖装在哪个解释器下

装完新开一个会话才会加载——已开的会话看不到新技能。WorkBuddy 还可以在「技能」面板里核对是否装齐。

只想在单个项目里用？ 把提示词里的用户级路径换成该项目根目录下的项目级目录： Claude Code 用 .claude/skills/，Codex 用 .codex/skills/，WorkBuddy 用 .codebuddy/skills/——注意不是 .workbuddy/，它的用户级目录叫 ~/.workbuddy/， 项目级目录却沿用底层 CodeBuddy 内核的名字，写错了技能一个都不出现。

用的是别的宿主？ 同一段提示词，把目标路径换成该宿主的 skills 目录即可。Skill 遵循 Agent Skills 通用格式（SKILL.md + scripts/ + references/），不绑定单一宿主。 装错位置的表现是技能一个都不出现、且没有任何报错——几家宿主的目录互不读取，都用就各装一份。

安装期联网、运行期禁网：第 3 步装依赖需要网络；装完之后每次对账都在本地跑， scripts/reconcile.py 一进来就阻断网络，不再装任何东西、不联任何网。

⚠ 三家宿主的支持级别不同，装之前请看清你用的是哪一档：

宿主	级别	含义
Claude Code、Codex	使用验证	开发者在多个真实项目中反复安装并跑通。PRD FT-11 的 9 项验证项中，6 项由实际使用覆盖；权限确认、运行期网络拦截、错误处理这 3 项未在宿主内确认——它们只在异常分支出现，日常对账走不到。逐项状态见 验证记录
WorkBuddy	格式兼容	目录结构符合 Agent Skills 通用格式、路径取自该宿主公开约定，但本仓库从未在它上面实际跑过

「使用验证」不等于 PRD FT-11 定义的「逐项走查」。完整路径表、9 项验证项清单与排查步骤见 多代理安装矩阵。

3 分钟试一下

仓库 skills/fcs-reconcile/examples/ 备了一份演示数据（12 行台账 vs 13 行银行流水，埋了 7 类典型差异），把它拿出来对你的代理说：

用 fcs-reconcile 帮我核对这两份数据：对账演示数据.xlsx 里的台账和银行流水

它会先展示数据处理声明等你确认：

运行模式：本地隔离
将读取：N 个本地文件 ｜ 将写入：M 个结果文件
原始数据进入模型：否
网络访问：已禁用
源文件修改：否
终端输出交易明细：否
输入完整性：读取前后 SHA-256 校验

你确认后才本地跑对账，产出结果工作簿与运行清单。示例产物见同目录的 对账演示数据_对账结果.xlsx，可以直接打开对照着看该期待什么。

演示数据故意覆盖了对账里最常见的 7 种情形，其中第 ④ 类刻意保留为"未自动匹配"，用来演示主键匹配的边界在哪：

怎么开口问：对账场景的提问示例

不用背 Skill 名。 用你自己的话说出你卡在哪，代理会匹配到对应的 Skill；你也可以直接点名 fcs-reconcile，两种方式等价。

提问只是开场，不是一问一答。 它会先问清左右表是哪两份、哪些列是编号 / 金额 / 日期 / 方向、容差定多少、结果写到哪，在数据处理声明处停下等你拍板，确认前零落盘。

这些问法会被拦下来——但每条都有替代出口

串起来看：一次对账从头到尾

 1. 从网银导出流水、从系统导出台账（两份 xlsx/csv）   ← 你自己做，不联网
 2. "帮我核对这两份"                                  → 代理匹配到 fcs-reconcile
 3. 确认左右表、字段映射、容差、借贷方向、输出位置       ← 你拍板
 4. 看数据处理声明（读写几个文件 / 是否进模型 / 网络）   ← 你确认，确认前零落盘
 5. 本地跑对账：读取 → 标准化 → 分阶段匹配 → 分类       ← 程序做，禁网
 6. 勾稽校验（数量勾稽 + 金额勾稽，Decimal）            ← 结论写进总览与运行清单，不静默吞掉
 7. 写 7 张表的结果工作簿 + manifest.json 运行清单       ← 落盘到你指定位置
 8. AI 只拿到汇总：匹配率、各状态计数、勾稽结论           ← 明细留在本地
 9. 你在 Excel 里复核「待处理事项」，填复核状态/复核人/意见 ← 判断归你
10. 结果 + 运行清单一起交审计                            ← 版本、哈希、配置都在里面

你会拿到什么：结果工作簿的 7 张表

全中文，无英文状态码，打开就能用 Excel 继续筛选、批注、流转（输出契约 v1.0）：

8 种结果状态（全中文）：已自动匹配 · 疑似匹配 · 金额差异 · 左侧单边 · 右侧单边 · 重复编号 · 多候选冲突 · 数据质量问题。含义与中文财务术语对照见 field-glossary.md。

为什么可信

不是承诺，是可以逐条检查的工程设计：

• 自动确认铁律：进入「已自动匹配」当且仅当 ① 候选唯一（左右各恰一条、无竞争候选）且 ② 规则完全满足（金额差严格 = 0，或复合键逐字段全等）。任一不满足就转对应待处理 / 冲突状态。容差只做差异分级，永不放宽自动确认——容差内的差异属"不确定"，交人判断（matching-rules.md）。
• 金额不碰浮点：一律 Decimal 定点计算，千分位 / 货币符号 / 全角字符先清洗；量化小数位可配，四舍五入 HALF_UP。
• 勾稽显式呈现，不静默吞掉：左表行数 = Σ各状态左侧计数、右表行数 = Σ各状态右侧计数、左金额合计 − 右金额合计 = Σ金额差异（Decimal）。结论以「通过 / 不通过」写在「对账总览」首屏，同时计入运行清单的 errors 计数——勾稽不过意味着"这次对账本身有问题"，你一眼就能看到，而不是拿到一份"看起来对"的结果。它保证的是每一行都有明确去向。
• 运行期禁网：scripts/reconcile.py 第一步执行 guard.block_network()，任何出站 socket.connect 直接抛 NetworkDisabledError。只有安装依赖那一步需要网络。
• 源文件只读且可证：读取前后各算一次 SHA-256 并比对；输出路径等于任一输入路径时直接拒绝执行。
• 明细不越界：上交给 AI 的只有 summary（匹配率、各状态计数、勾稽结论）；原始明细、DataFrame、标准行不出数据平面，终端也不打印交易明细，日志只记状态计数与错误码。
• 可重复：相同输入 + 相同配置 + 相同规则版本必须产生相同结果（NFR-05）。rule_version 与 contract_version 一经发布只增不改——已落盘的运行清单引用的是旧版本号，改写它等于篡改审计证据。
• 版本不漂移：pyproject.toml、SKILL_META.yaml、scripts/version.py、SKILL.md 与两份 CHANGELOG 的版本号由 tests/supply_chain/test_version_consistency.py 机器断言一致；README 的安装路径由 tests/cross_platform/test_install_paths.py 对着安装矩阵守卫。这两类漂移在使用侧几乎不可发现，所以必须机器化。
• 测试现状：单元 / 属性 / 黄金答案（逐单元格快照）/ 安全测试通过（网络隔离、日志脱敏、源文件完整性、输出不覆盖输入），工具集级安全基线 6 项在 CI 中真跑；独立前向测试为 self-tested——开发者自测过，但"测试者不预知答案"的那一轮还没跑，而开发者越熟悉这个 Skill 就越不能代表陌生用户，所以这里不写 passing。

⚠ 不要把"本地运行"读成"数据绝不离开本机"。 本地脚本确实禁网，原始明细默认不进模型；但你与代理的对话本身要经过宿主平台（Claude Code / Codex / WorkBuddy 各有自己的数据政策）。所以：文件路径、字段名、汇总数会进对话，交易明细不会。高敏数据请配合完全离线环境使用（PRD §7.2 宿主平台披露）。

⚠ 当前发布状态是 Preview：不承诺接口稳定。仍未落地的有——FT-11 的 9 项逐项走查（当前是「使用验证」，3 项未在宿主内确认）、PRD §10.1 的独立前向测试（当前是开发者自测）、发布包签名与 SBOM。用于生产账务前请自行按你的内控要求评估，并保留人工复核环节。已知限制逐条列在 CHANGELOG 的「已知限制」里。

仓库结构

单个 Skill 内部（以 fcs-reconcile 为例）：SKILL.md（AI 入口）· SKILL_META.yaml（目录元数据）· scripts/（确定性执行，数据平面）· references/（AI 运行时参考，控制平面）· agents/（各代理专属配置）· examples/（演示数据与示例结果）· tests/（单元 / 属性 / 边界 / 黄金 / 安全）。

确定性代码归 scripts/，AI 可见内容归 SKILL.md / references/，两者不得混淆——这是控制平面与数据平面分离的落地方式。项目结构的完整设计与决策依据见 docs/specs/2026-07-23-project-structure-design.md。

开发

需要 Python ≥ 3.11 与 uv。

# 依赖管理与统一工具（uv workspace）；uv.lock 是依赖锁定的唯一真源
uv sync

# 全量测试（工具集级 + 各 Skill 内部）
uv run pytest

# 只跑某个 Skill 的测试
uv run pytest skills/fcs-reconcile/tests

# Lint / 类型检查（mypy strict）
uv run ruff check .
uv run mypy .

# 重新生成演示数据与示例结果
python3 skills/fcs-reconcile/examples/gen_reconcile_demo.py
python3 skills/fcs-reconcile/examples/gen_reconcile_result.py

直接跑对账引擎（配置字段见输入契约）：

python skills/fcs-reconcile/scripts/reconcile.py --config <config.yaml>

路线图

路线图是计划，CHANGELOG 是事实。 两者不一致时以 CHANGELOG 为准（versioning.md §6）。

贡献

想参与开发或二次定制，先读 CONTRIBUTING.md（新增 Skill 的 FT-12 提交清单、三审维度、立项条件）与 docs/governance/versioning.md（四层版本的事实源与 bump 时机）。三条最容易踩的：

1. 不放松确定性校验、安全隔离或可核验性——严谨性一票否决，这条压过一切便利。
2. rule_version / contract_version 一经发布只增不改；运行期版本号只从 scripts/version.py 取，不在业务代码里散写字面量。
3. 新增 Skill 要回改 README 三段安装提示词（点名新 Skill、更新"当前 N 个"），否则 CI 的安装路径守卫会挡下。

⚠ 是否接受社区贡献 Skill、由谁做财务 / 安全 / 代码审核，尚待确定（PRD §10.4 待办 ⑨⑩）。

安全

漏洞请不要通过公开 issue 报告，也请勿在报告中附带真实财务数据；仅提供脱敏样本。私密报告渠道待定，详见 SECURITY.md。

许可

MIT License —— 可自由使用、修改、分发、商用与再授权，只需保留版权与许可声明。全文见 LICENSE。

许可证之外还有一条不写进许可证、但同样不退让的承诺：本工具集不收集、不出售、不用于训练你的财务数据（PRD §1.3）。MIT 约束的是代码的使用方式，管不了数据；这条承诺由工程设计兜底——运行期禁网、原始明细不进模型、日志不含交易明细，都是可以逐条检查的（见为什么可信）。

软件按"原样"提供，不含任何担保。对账结果始终需要你的人工复核——这既是许可证的免责条款，也是本工具集的设计前提。