Skill organisation-documents

会计领域的入口引擎。接收 → 客户识别 → 归档 → 索引 → 生成报告。 实际工作由 scripts/main.py 完成（该脚本调用 scripts/extract.py）。本 skill 的作用仅限于：何时启动该脚本，以及如何与会计师对话。

⚠️ 绝对规则 — 脚本执行（不可协商）

每次调用时，唯一正确的归档操作是执行以下命令：

python3 scripts/main.py  

然后读取 /_report.json 并将内容转达给会计师。

❌ 禁止行为

• 逐个手动阅读 PDF 并人工归档。 模型通过肉眼提取字段时极不稳定（已观察到的真实案例：invoice_id 提取为 "N"、"des"、"um-rix"，而非正确值 F1-2026-0001；total_ttc 提取为 0.00，而非真实金额）。此类错误将直接导致后续 rapprochement-bancaire 对账失败。
• 在单元格或内联子进程中临时编写 Python 代码重复实现脚本逻辑。 脚本即权威逻辑，具备确定性且已充分测试。每次调用都重新实现，必然导致逻辑偏差。
• 手动创建或移动文件至 / 目录下（move / copy / write）。该操作应完全由脚本完成。
• 当 PDF 中无可读的 invoice_id 时自行编造。 若 extract.py 未能提取，则脚本会写入 SANS-NUM；请勿尝试根据发票开具方名称或描述等信息“优化”生成编号。

✅ 必须执行的操作

1. 执行上述 shell 命令（且仅此操作用于归档环节）。
2. 读取生成的 _report.json 文件。
3. 向会计师转达简明摘要，并在 questions 字段非空时一并提出开户引导问题。

若脚本执行失败

向会计师准确报告错误详情（stderr）。切勿 手动补救归档——这正是导致文件名损坏的根源。若缺失 pdftotext 二进制（poppler-utils 未安装），请明确告知并中止流程。

为何该规则如此严格？我们已多次遇到模型擅自归档并生成虚假 invoice_id（如 N、des、um-rix）的情况。每次都会触发 rapprochement-bancaire 报告误判的 facture_manquante（缺失发票），迫使会计师耗费时间排查。而脚本绝不会出现此类错误。

何时使用该 skill

面对所有新进文档时的默认响应流程：

1. 带附件的邮件 → 立即处理。
2. 手动存入 inbox 目录 → 同样立即处理。
3. 批量导入（ZIP 或文件夹）→ 同样立即处理。
4. 会计师对客户识别问题的答复 → 启动重处理（即开户引导第二步）。
5. 重新归档 / 修正 → 重新运行脚本。

不适用于：FEC（→ fec-parser）、催款函（→ relances）、银行对账（→ rapprochement-bancaire）。

执行方式

python3 scripts/main.py  []
# racine_clients 默认路径：~/.openclaw/workspace/clients

脚本执行以下步骤：

1. 基于 SHA-256 去重（通过 _index.json 忽略已归档文件）。
2. 使用 scripts/extract.py 提取每个 PDF（调用 pdftotext -layout + 确定性规则）。所有金额、编号、名称均严格来自原文，绝不臆造。
3. 第一阶段 — 优先处理银行对账单：对账单页眉显示的账户持有人即为事务所客户（身份确凿）→ 创建或完善 clients.json 条目（statut: auto-from-bank-statement），并将对账单归入 ///bank-statements/。
4. 第二阶段 — 处理发票：对每张发票，将其开具方与收件方分别与 clients.json 进行比对（先精确匹配，再模糊匹配 ≥ 0.82）：
   • 仅一方匹配 → 该方即为客户；开具方 ≈ 客户 → 归入 invoices/out/；收件方 ≈ 客户 → 归入 invoices/in/。
   • 双方均不匹配 → 归入 _a-identifier/，并在报告中添加一条识别问题（参见下方开户引导说明）。
   • 双方均匹配 → 归入 _a-identifier/ 并添加问题（罕见情况）。
   • 提取不完整（无法定位日期或含税总额）→ 归入 _incomplet/，并在报告中标记。
5. 第三阶段 — 其他文档：既非发票亦非对账单 → 归入 _non-attribue/。
6. 生成 clients/clients.json、clients/_index.json、clients/_report.json，并打印摘要。

执行完毕后，请读取 clients/_report.json 并执行以下操作：

• 向会计师转达简明摘要（已归档发票数量、对账单数量、新增客户数）；
• 若 _report.json → questions 非空 → 将其中问题提交会计师（参见格式规范）；
• 若 _report.json → incomplete 非空 → 向会计师指出这些文档；
• 对每张已成功归档（非 _a-identifier/_incomplet）的发票或对账单，可认为后续 rapprochement-bancaire 处理已被触发（批次任务本身也会自动覆盖全部客户）。

客户识别 — 绝对规则

三个可信信号，按优先级排序（均由脚本处理）：

1. 银行对账单：账户持有人 → 确凿无疑。
2. 已确认映射：发件人邮箱 ∈ contacts[].email，或域名 ∈ domains，或文档中的 SIREN ∈ 某客户的 siren 列表。
3. 公司名称模糊匹配 ≥ 0.82（对比 clients.json）→ 仅当开具方与收件方中仅有一方匹配时启用。

若无任何可信信号 → 绝不猜测。文档进入 _a-identifier/，由会计师一次性裁定。

模糊发件人的开户引导（以「Corse Plomberie」为例）

一张发票始终包含两家企业（开具方、收件方）。当两者均未知，且无对账单覆盖其中任一方时，脚本不会自行选择，而是将文档放入 _a-identifier/ 并添加一条识别问题。

第一步（自动） — 问题出现在 _report.json → questions 中：

「文档：发票 TUYO-2024-087（含税金额 348.50 €）。开具方「TUYO SARL」，收件方「Corse Plomberie」。哪一方是您的客户？」

模型需将该问题转达会计师。此时不得修改 clients.json。

第二步（会计师回复后） — 当会计师确认「是 X」时：

1. 在 clients.json 中新增或补充 X 的条目：

   { "slug": "", "raisonSociale": "X", "statut": "confirmed",
     "confiance": 1.0, "aValider": false,
     "siren": [""], "contacts": [{"email": ""}],
     "domains": [""], "sources": ["accountant-confirmation"] }
   

2. 重新运行 python3 scripts/main.py clients/_a-identifier ：由于 X 已存在于 clients.json，关联文档将被正确归档（in/out 方向明确），并移出 _a-identifier/ 目录。
3. 将结果转达会计师。

此后，来自同一发件人（相同邮箱）的所有新文档将自动归属该客户。

若会计师答复「两者均非客户」

将该文档从 _a-identifier/ 移至 _non-attribue/。无需进一步会计处理。

clients.json — 结构说明

[
  {
    "slug": "corse-plomberie",
    "raisonSociale": "Corse Plomberie",
    "statut": "auto-from-bank-statement | confirmed",
    "confiance": 0.9,
    "aValider": false,
    "siren": ["812345678"],
    "contacts": [{ "email": "jeanmichel@gmail.com" }],
    "domains": ["corseplomberie.fr"],
    "sources": ["bank-statement"]
  }
]

该文件仅由本 skill 构建与维护（通过 scripts/main.py 及开户引导期间的手动补充）。其他任何 skill 均不得写入此文件。会计师不得手动编辑：其职责仅为回答识别问题。

目标目录结构

clients/
├── clients.json                  ← 客户列表（源自对账单推导 + 人工确认）
├── _index.json                   ← sha256 → 已归档路径（去重依据）
├── _report.json                  ← 最近一次执行的报告
├── _a-identifier/                ← 客户尚未确认的发票（正在开户引导中）
├── _incomplet/                   ← 提取失败的文档（缺少日期 / 含税金额）
├── _non-attribue/                ← 无法识别为发票或对账单的文档
├── _cabinet/                     ← 事务所内部文档
└── /
    └── //
        ├── bank-statements/
        │   └── _.pdf
        └── invoices/
            ├── in/
            │   └── ___.pdf
            └── out/
                └── ___.pdf

文件命名规范（由脚本自动生成，严禁手动构造）：

• N°Facture：PDF 中提取的真实编号（如 F1-2026-0003），仅含字母、数字及短横线；缺失时为 SANS-NUM。
• Contrepartie：另一方名称中前 14 个有效字符（去除重音符号与空格）。
• MontantTTC：小数点分隔，无千位分隔符，无货币符号（如 3336.78）。
• AAAA-MM-JJ：文档签发日期。

发票 vs 对账单检测（回顾 — 实现于 extract.py）

• 判定为银行对账单 当满足以下任一条件：RELEVÉ DE COMPTE/EXTRAIT DE COMPTE/ACCOUNT STATEMENT，或银行名称 + RELEVÉ，或含 Solde d'ouverture/Solde de clôture。 例外：若文档同时含 FACTURE/INVOICE 且含 SIRET/TVA → 视为发票。
• 判定为发票 当至少满足以下两个信号：FACTURE/INVOICE/BON DE FACTURATION · 含 SIRET/TVA/SIREN 的区块 · 收件方区块（FACTURÉ À/DESTINATAIRE/BILL TO）· TOTAL HT/TOTAL TTC/NET À PAYER。
• 否则 → 归入 _non-attribue/。

与会计师的沟通规范

• 默认静默：仅开头一行、结尾一行文字。禁止分步叙述过程。
• 开户引导问题：统一汇总于消息末尾，每个模糊发件人单独一行，格式为「文档 … — 开具方「…」，收件方「…」 — 哪一方是您的客户？」
• 禁用术语：pdftotext、regex、SHA-256、pipeline、extract.py、系统绝对路径。
• 专业术语：发票、单据、客户档案、当月、归档、重复、法定必备要素、交易对手方。

安全防护机制

• 所有数据均不离开 LXD 容器。
• 数据保存期不少于 10 年。永不删除 — _a-identifier/、_incomplet/、_non-attribue/ 均保留原始单据。
• 外部数据源仅允许只读访问。
• 系统绝不猜测任何金额、编号或客户身份：仅凭可信信号判断，否则必提问题。宁入 _incomplet/，不填臆造值。

后续处理

对于每张/每份已归档至真实客户目录（非 _a-identifier/ 或 _incomplet/）的发票或对账单，rapprochement-bancaire 状态引擎将自动接管。请发出如下指令：

{ "trigger": "rapprochement-bancaire", "client": "" }

（批次任务本身会扫描全部客户；此触发仅用于加速处理。）

关于催款函：切勿直接调用。最多输出：

{ "trigger_suggestion": "relances", "reason": "invoice status may require update" }

设计哲学

organisation-documents = 入口引擎 — 归档单据、识别客户（通过对账单或提问）、维护 clients.json
rapprochement-bancaire           = 状态引擎 — 执行对账、重建会计状态
relances               = 延迟决策引擎

机械性工作交由脚本完成。本 skill 的核心职责是决定何时启动脚本，以及如何向会计师清晰传达结果。