报表自动化填报技能（report-auto-fill）
技能概述
本技能通过「报签 + 规则库」体系，实现各类报表的自动化填写：
1. 识别报表类型，建立唯一报签
2. 建立/调用填写规则（AI推断 + 用户提供 + 用户修正）
3. 持久化存储规则，同类报表直接复用
4. 自动提取数据，输出填好的报表文件
所有规则存储在 ~/.workbuddy/report_rules/rules_db.json，跨会话持久保留。
⚠️ 核心原则（必须严格遵守）
> 规则先行、数据后置 — 严禁在无规则或规则未确定、未固化的情况下开展任何数据填报工作。
- 每条规则必须落库：所有填写规则在确认后，必须立即调用
rule_store.py存入规则库，不可仅存在于对话上下文中。 - 规则覆盖率校验：填报前必须校验「规则库中的规则是否覆盖模板中所有需填字段」，未覆盖的字段须补齐规则后再执行。
- 先改规则、再重填：发现数据错误时，必须先更新规则库中的对应规则，再基于新规则重新填报，禁止直接修改输出文件中的数值。
- 填报依赖规则库：
fill_report.py执行填报时会强制校验规则库状态，无有效规则或规则不完整将拒绝执行。
执行流程
阶段零：读取参考文档（必须）
在开始每次任务前，先读取以下参考文档：
- references/workflow.md：完整工作流程与脚本用法
- references/rule_schema.md：规则库数据结构和字段说明
- references/report_knowledge.md：常见报表知识和科目代码（用于AI自动推断规则）
阶段一：接收用户文件
用户需提供：
1. 原始数据文件：Excel科目余额表、业务数据表、CSV、PDF等
2. 报表模板文件：需要填写的目标报表（Excel格式最佳）
接收文件后，立即运行字段提取脚本：
python scripts/report_identify.py extract-fields <原始数据文件路径>
python scripts/report_identify.py extract-fields <报表模板文件路径>
向用户简要展示提取到的字段列表，确认数据可识别。
特殊处理：
- PDF扫描件/图片：直接调用AI视觉能力识别表格内容，手动整理字段列表
- 多Sheet Excel：分别列出各Sheet字段，询问用户使用哪个Sheet
阶段二：报表识别与报签管理
步骤1：尝试匹配已有报签
python scripts/report_identify.py match-sig <报表模板文件路径>
- 匹配度 ≥ 70%：向用户确认「是否使用已有报签《XXX》及其现有规则？」
- 若用户确认：直接进入阶段三（跳过规则重建）
- 若用户否认：新建报签
- 无匹配或匹配度 < 70%：新建报签
步骤2：建立报签（若需要）
根据报表模板的字段特征，参考 references/report_knowledge.md，判断报表类型，向用户确认后创建：
python scripts/rule_store.py add-sig "<报表名称>" "<类型代码>" "<描述>"
记录返回的 sig_id，在整个任务中持续使用。
向用户告知：「已为《XXX》建立报签，ID：xxxxxxxx，后续同类报表将自动复用此规则。」
阶段三：规则建立（规则先行阶段）
> ⛔ 铁律：此阶段必须全部完成后，才能进入阶段五执行填报。跳过此阶段直接填报属于严重违规。
重要原则：无论规则来源如何，所有规则一旦确认，必须立即调用 rule_store.py add-rule 或 import-rules 存入规则库。
3A：AI自动推断规则
根据：
- 原始数据字段列表
- 输出报表字段列表
- references/report_knowledge.md 中的会计知识
生成初步规则映射表，格式如下（Markdown表格展示给用户）：
| 输出字段 | 来源字段/表达式 | 取数逻辑 | 公式 | 置信度 |
|---|---|---|---|---|
| 货币资金 | 1001,1002 | 库存现金+银行存款期末余额 | — | 高 |
| 应收账款 | 1122 | 应收账款期末借方余额 | — | 高 |
| 流动资产合计 | — | 各流动资产项目之和 | 货币资金+应收账款+... | 中 |
向用户说明：「以上为AI推断的初步规则，请检查确认，如有问题请告知修改。」
等待用户确认或修改后，立即批量存入规则库：
python scripts/rule_store.py import-rules <sig_id> <rules_json_file>
存库后向用户确认：「✅ 已将 N 条规则存入规则库，报签ID：<sig_id>」
3B：用户主动告知规则
当用户说明特定字段的取数规则时，立即转化为规则条目并存入库：
echo '{"output_field":"XXX","source_field":"YYY","logic":"ZZZ","source":"user_provided"}' | python scripts/rule_store.py add-rule <sig_id>
向用户确认：「✅ 已将规则「XXX → YYY」存入规则库。」
3C：用户修正规则
当用户说「XX字段不对」或「应该用XXX而不是YYY」时：
1. 先查询当前规则：python scripts/rule_store.py list-rules <sig_id>
2. 找到对应 rule_id
3. 先更新规则库（来源自动标记为 user_corrected）：
echo '{"source_field":"新字段","logic":"新逻辑"}' | python scripts/rule_store.py update-rule <rule_id>
- 向用户确认：「✅ 规则已更新并固化到规则库。」
- 再执行阶段五基于新规则重新填报
3D：规则覆盖率校验（新增，必须执行）
在进入阶段五之前，必须执行规则覆盖率校验：
python scripts/rule_store.py list-rules <sig_id>
对比规则库中的 output_field 列表与模板中所有需填字段，生成覆盖率报告：
📊 规则覆盖率校验：
- 模板需填字段：42 个
- 已有规则覆盖：38 个
- ⚠️ 未覆盖字段（4 个）：
1. 收到的税费返还 — 缺少取数规则
2. 汇率变动影响 — 需确认是否应填写
3. ...
- 覆盖率达 100%：可以进入阶段五执行填报
- 覆盖率不足：必须为未覆盖字段补充规则后再填报，或由用户明确确认哪些字段可以留空
> ⛔ 禁止在未完成规则覆盖率校验的情况下执行填报。
阶段四：规则检查与修正
触发词：「查看规则」、「检查规则」、「规则对不对」、「当前有哪些规则」等
执行：
python scripts/rule_store.py list-rules <sig_id>
以 Markdown 表格形式向用户展示所有规则，包含：规则来源、字段对应、取数逻辑、计算公式、备注。
同时输出规则覆盖率报告（同阶段三D），让用户一目了然哪些字段有规则、哪些没有。
规则修正流程（当用户发现问题）：
1. 更新规则库：python scripts/rule_store.py update-rule <rule_id>
2. 确认规则已固化：「✅ 规则已更新到规则库。」
3. 询问用户是否需要重新填报（触发阶段五）
阶段五：报表填写与输出
> ⛔ 前置条件检查（脚本内置，不可绕过）：
> - 规则库中必须存在该报签的有效规则
> - 规则数量必须 ≥ 模板需填字段的 50%（可由用户确认放宽）
> - 不满足条件时，脚本将报错并拒绝执行填报
步骤1：预览确认（必须执行）
在正式填报前，必须先运行预览，让用户核对取值：
python scripts/fill_report.py preview <sig_id> <原始数据文件>
将预览结果以表格形式展示给用户（字段名 + 取到的值 + 取值方式），确认数据无误。
步骤2：生成填报文件
用户确认预览结果后，执行正式填报：
python scripts/fill_report.py fill <sig_id> <原始数据文件> <报表模板文件> [输出文件路径]
执行完成后：
- 展示填报摘要（成功填写N个字段，未找到M个字段）
- 对于未能填写的字段，列出原因，并询问用户是否需要补充规则后重填
- 输出完成的报表文件，提示用户下载
⚠️ 严禁以下行为：
- 跳过预览直接填报
- 不通过规则库，直接用 Python 脚本写数值到 Excel（所有数据必须来自规则驱动）
- 在用户修正规则后，不重填而直接手动修改输出文件
用户交互要点
关键确认节点
| 节点 | 需向用户确认的内容 | 必须完成 |
|---|---|---|
| 报签匹配 | 是否使用已有报签和规则 | ✅ |
| 新建报签 | 报表名称和类型是否正确 | ✅ |
| AI推断规则 | 规则表格是否合理，有无错误 | ✅ |
| 规则存库确认 | 「N条规则已存入规则库」 | ✅ 强制 |
| 规则覆盖率校验 | 是否覆盖全部需填字段 | ✅ 强制 |
| 预览结果 | 取到的数值是否符合预期 | ✅ 强制 |
| 填报完成 | 是否需补充规则并重填 | — 可选 |
常见用户指令识别
| 用户说 | AI应执行的操作 |
|---|---|
| "帮我填这张报表" | 启动完整流程（阶段一到阶段五），必须先完成阶段三规则落库 |
| "上次那张报表的规则还有吗" | 列出所有报签，按名称匹配 |
| "查看当前规则" | 触发阶段四，输出规则表格 + 覆盖率报告 |
| "第X行不对，应该是XXX" | 先更新规则库（阶段三C），再重新填报（阶段五） |
| "这个字段取YYY科目" | 触发阶段三B，添加用户提供规则 → 立即存库 |
| "重新生成一下" | 触发阶段五预览 → 填报（基于规则库中的最新规则） |
| "直接帮我填上去" | ⚠️ 如规则未建/未存库，必须拒绝并先引导完成阶段三 |
脚本依赖安装
首次运行前需安装以下 Python 包：
pip install pandas openpyxl pdfminer.six
如运行报错缺少依赖，脚本会自动提示安装命令。
规则库位置说明
- 规则持久化文件：
~/.workbuddy/report_rules/rules_db.json - 所有会话共享同一规则库，报签和规则跨项目复用
- 如需备份规则库，直接复制该 JSON 文件即可
⚠️ 禁止事项（红线）
以下行为在本技能执行过程中严格禁止，违反将导致数据质量不可控：
| # | 禁止行为 | 原因 | 正确做法 |
|---|---|---|---|
| 1 | 无规则直接填报 | 数据来源无法追溯 | 先完成阶段三，规则存库后再填报 |
| 2 | 跳过规则覆盖率校验 | 可能遗漏关键字段 | 必须执行3D校验，覆盖率达100%（或用户确认） |
| 3 | 跳过预览直接填报 | 填报错误无法及时拦截 | 必须先preview，用户确认后再fill |
| 4 | 直接写Excel数值绕过规则库 | 规则库与实际数据不一致 | 所有数值必须通过规则驱动写入 |
| 5 | 修正规则后不重填 | 规则更新未生效到输出 | 规则更新后必须重新执行阶段五 |
| 6 | 规则仅存在于对话上下文 | 跨会话丢失，无法复用 | 规则必须存入规则库（调用rule_store.py） |
常见填报问题处理
Q1：借贷方向判断错误
现象：资产类科目取到负值，或权益类科目取值方向相反
原因：未正确判断余额所在列（借方 vs 贷方）
处理步骤：
1. 检查 references/report_knowledge.md 第5.1-5.3节确认借贷方向含义
2. 根据科目类型判断正常余额方向
3. 查看原始数据中余额在借方还是贷方列
4. 修正规则中的取数逻辑
Q2：本年利润与未分配利润计算错误
现象：所有者权益不平衡，差异较大
原因：未正确理解4103本年利润与4104利润分配的关系
处理步骤：
1. 参见 references/report_knowledge.md 第6节
2. 亏损时：未分配利润 = 利润分配贷方 - 本年利润借方
3. 盈利时：未分配利润 = 利润分配贷方 + 本年利润贷方
4. 更新规则后重新计算
Q3：科目余额表列结构不匹配
现象：取到的数值全部为0或明显错误
原因：科目余额表有合并表头或多行标题
处理步骤：
1. 使用 header=None 参数读取原始数据
2. 手动跳过前几行（通常2-4行）
3. 确认列结构：期初借/贷、本期借/贷、期末借/贷
4. 参见 references/report_knowledge.md 第7节
Q4：利润表数据不平衡
现象：营业利润计算结果与净利润不一致
原因：缺少收入数据，或计算公式错误
处理步骤：
1. 参见 references/report_knowledge.md 第8节利润表公式
2. 只有费用数据时：营业利润 = -(管理费用 + 财务费用)
3. 净利润 = 利润总额 = 营业利润（无营业外收支时）
Q5：资产负债表不平衡
现象：资产合计 ≠ 负债+所有者权益合计
允许误差：±0.10元（计算舍入误差）
处理步骤：
1. 检查所有资产科目是否正确取值
2. 检查借贷方向是否正确
3. 检查本年利润结转计算
4. 确认未分配利润公式（参见第6节）
5. 修正规则后重新填报
