{"id":"efb6f404-f4a1-4e64-b40f-0cc01753a200","entityType":"agent","slug":"clawhub-fyniujin-receipt-compliance","name":"receipt-compliance","canonicalUrl":"https://www.xpersona.co/agent/clawhub-fyniujin-receipt-compliance","canonicalPath":"/agent/clawhub-fyniujin-receipt-compliance","generatedAt":"2026-10-11T07:42:50.526Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T04:54:32.040Z","emptyReason":null},"description":"会计助手：发票OCR识别→真伪查验→报销单自动填充→对接审批系统。企业自主配置，数据本地处理。 Skill: receipt-compliance Owner: fyniujin Summary: 会计助手：发票OCR识别→真伪查验→报销单自动填充→对接审批系统。企业自主配置，数据本地处理。 Tags: latest:4.5.0 Version history: v4.5.0 | 2026-10-09T09:13:27.116Z | auto **Summary:** 版本 4.5.0 增加票据合规能力、查重排查、异常检测和审批对接等模块，拓展财税应用链路和报销合规场景。 - 新增进/销项台账统计、认证期限日历、异常检测、重复报销查重、查重工单等合规和风险管理功能 - 引入审批连接器模块，统一对接钉钉/企业微信/飞书（含回调验签） - 支持数电票 PDF/OFD 文本层直读与二维码内容核对 - 新增合规管理一键导出及归档四性检测合并 - 支持可疑工单清单对照、HTML复核输出，提升财务查重和误报豁免效率 - 新增 SQLi","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.2K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s177r8w7p1d7cpbys9bn33kwhs89d0xw:receipt-compliance","sourceUrl":"https://clawhub.ai/fyniujin/receipt-compliance","homepage":"https://clawhub.ai/fyniujin/skills/receipt-compliance","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/fyniujin/receipt-compliance","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/fyniujin/skills/receipt-compliance","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":61,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"会计助手：发票OCR识别→真伪查验→报销单自动填充→对接审批系统。企业自主配置，数据本地处理。 Skill: receipt-compliance Owner: fyniujin Summary: 会计助手：发票OCR识别→真伪查验→报销单自动填充→对接审批系统。企业自主配置，数据本地处理。 Tags: latest:"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T04:54:32.040Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T04:54:32.040Z","emptyReason":null},"stars":null,"forks":null,"downloads":1154,"packageName":null,"latestVersion":"4.5.0","tractionLabel":"1.2K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T04:54:32.024Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T04:54:32.040Z","lastCrawledAt":"2026-10-11T04:54:32.024Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T04:54:32.024Z","lastVerifiedAt":null,"highlights":[{"version":"4.5.0","createdAt":"2026-10-09T09:13:27.116Z","changelog":"**Summary:** 版本 4.5.0 增加票据合规能力、查重排查、异常检测和审批对接等模块，拓展财税应用链路和报销合规场景。 - 新增进/销项台账统计、认证期限日历、异常检测、重复报销查重、查重工单等合规和风险管理功能 - 引入审批连接器模块，统一对接钉钉/企业微信/飞书（含回调验签） - 支持数电票 PDF/OFD 文本层直读与二维码内容核对 - 新增合规管理一键导出及归档四性检测合并 - 支持可疑工单清单对照、HTML复核输出，提升财务查重和误报豁免效率 - 新增 SQLite 台账存储与月度附件导出，支持趋势和集中度分析","fileCount":52,"zipByteSize":194592},{"version":"4.3.0","createdAt":"2026-08-24T13:02:59.556Z","changelog":"receipt-compliance 4.3.0 - 新增“混拍切分”功能，支持一拍多票自动分割与原图索引。 - 发票OCR升级为PaddleOCR优先（支持定额票先验定位+勾稽校验），Tesseract作为兜底。 - 新增/优化脚本：batch_splitter.py（新增）、invoice_detector.py、ocr_engine.py。 - 移除 skill-card.md。 - 文档同步更新，详细说明双引擎策略与混拍切分能力。","fileCount":45,"zipByteSize":143708},{"version":"4.2.2","createdAt":"2026-08-16T12:22:50.027Z","changelog":"receipt-compliance 4.2.2 - Updated security configuration logic in scripts/secure_config.py. - Documentation updated in SKILL.md. - Obsolete skill-card.md file removed.","fileCount":44,"zipByteSize":137599},{"version":"4.2.1","createdAt":"2026-08-16T11:23:07.145Z","changelog":"- 修复部分环境检测和安全配置脚本，提升环境变量读取和密钥安全性。 - 安装说明&依赖工具提示更新，对 poppler 安装指引更详细（各平台均有覆盖）。 - 文档优化：完善 FAQ 与避坑指南中的部分内容，帮助快速定位配置和识别问题。 - 移除 skill-card.md 文件，减少冗余文档。","fileCount":44,"zipByteSize":137817},{"version":"4.2.0","createdAt":"2026-08-16T10:32:55.571Z","changelog":"receipt-compliance 4.2.0 brings major enhancements for banking reconciliation, batch performance, and configuration security. - 新增银行对账功能：可解析银行流水CSV并与发票金额/日期自动模糊匹配，生成对账报告 - 新增基于硬件自适应的并行批量处理，批量识别速度提升3-5倍 - 支持安全配置：密钥通过环境变量读取，消除明文泄露风险 - 文档完善：功能表与说明已补充银行对账、并行批量、安全配置等新特性 - 移除 skill-card.md，不再维护该文件","fileCount":44,"zipByteSize":137404},{"version":"4.1.0","createdAt":"2026-08-05T15:29:11.862Z","changelog":"**新增风险预警与归档管理功能，提升发票合规管理智能化与自动化水平：** - 新增“风险预警”能力，支持发票连号、整数金额、频繁开票、品名异常等智能风险检测，生成三级预警报告 - 新增“归档管理”模块，支持发票归档包生成、四性检测、元数据采集与目录索引 - 增加风险与供应商规则配置参考文档及配套脚本（references/risk_rules_config.yaml, supplier_scope_rules.md, scripts/risk_detector.py, archive_manager.py） - 文档全面更新，详细介绍风控和归档新功能的应用场景与操作方法 - 移除冗余 skill-card.md，文档体系精简优化","fileCount":41,"zipByteSize":121954},{"version":"4.0.0","createdAt":"2026-08-01T08:13:01.535Z","changelog":"**Major update: Expands from发票OCR/查验/报销单→全票据/凭证一站式管控** - 新增对火车票、飞机票、出租车、定额发票、通行费、财政票据、全电发票（XML/OFD）等多种票据的自动识别和结构化解析 - 引入智能分类（自动会计科目判别/进项税计算/凭证摘要生成）和一键自动生成记账凭证（用友/金蝶/QuickBooks等主流格式） - 新增专用解析与分类脚本：fiscal_parser, train_parser, fixed_parser, flight_parser, taxi_parser, toll_parser, smart_classifier, voucher_generator 等 - 参考资料增加配置规则和会计科目映射（expense_rules.md, account_mapping.md） - 文档全面升级：功能表、FAQ、场景说明、操作引导等同步增强 - skill-card.md移除，主文档内容","fileCount":37,"zipByteSize":108587},{"version":"3.7.0","createdAt":"2026-07-22T09:29:43.827Z","changelog":"receipt-compliance 3.7.0 - 增加4个新脚本：支持发票自动检测、OFD电子发票解析、统一发票处理、XML格式解析 - 文档细节更新，完善能力说明及使用指南 - 移除 skill-card.md（详情整合至主文档中） - 局部内容调整以反映脚本/能力结构优化","fileCount":27,"zipByteSize":86579}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s177r8w7p1d7cpbys9bn33kwhs89d0xw:receipt-compliance","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fyniujin-receipt-compliance/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fyniujin-receipt-compliance/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fyniujin-receipt-compliance/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-fyniujin-receipt-compliance/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-fyniujin-receipt-compliance/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-fyniujin-receipt-compliance/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-11T07:42:50.521Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fyniujin-receipt-compliance/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fyniujin-receipt-compliance/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fyniujin-receipt-compliance/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-fyniujin-receipt-compliance/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-11T04:54:32.040Z","emptyReason":null},"readme":"Skill: receipt-compliance\n\nOwner: fyniujin\n\nSummary: 会计助手：发票OCR识别→真伪查验→报销单自动填充→对接审批系统。企业自主配置，数据本地处理。\n\nTags: latest:4.5.0\n\nVersion history:\n\nv4.5.0 | 2026-10-09T09:13:27.116Z | auto\n\n**Summary:**  \n版本 4.5.0 增加票据合规能力、查重排查、异常检测和审批对接等模块，拓展财税应用链路和报销合规场景。\n\n- 新增进/销项台账统计、认证期限日历、异常检测、重复报销查重、查重工单等合规和风险管理功能\n- 引入审批连接器模块，统一对接钉钉/企业微信/飞书（含回调验签）\n- 支持数电票 PDF/OFD 文本层直读与二维码内容核对\n- 新增合规管理一键导出及归档四性检测合并\n- 支持可疑工单清单对照、HTML复核输出，提升财务查重和误报豁免效率\n- 新增 SQLite 台账存储与月度附件导出，支持趋势和集中度分析\n\nv4.3.0 | 2026-08-24T13:02:59.556Z | auto\n\nreceipt-compliance 4.3.0\n\n- 新增“混拍切分”功能，支持一拍多票自动分割与原图索引。\n- 发票OCR升级为PaddleOCR优先（支持定额票先验定位+勾稽校验），Tesseract作为兜底。\n- 新增/优化脚本：batch_splitter.py（新增）、invoice_detector.py、ocr_engine.py。\n- 移除 skill-card.md。\n- 文档同步更新，详细说明双引擎策略与混拍切分能力。\n\nv4.2.2 | 2026-08-16T12:22:50.027Z | auto\n\nreceipt-compliance 4.2.2\n\n- Updated security configuration logic in scripts/secure_config.py.\n- Documentation updated in SKILL.md.\n- Obsolete skill-card.md file removed.\n\nv4.2.1 | 2026-08-16T11:23:07.145Z | auto\n\n- 修复部分环境检测和安全配置脚本，提升环境变量读取和密钥安全性。\n- 安装说明&依赖工具提示更新，对 poppler 安装指引更详细（各平台均有覆盖）。\n- 文档优化：完善 FAQ 与避坑指南中的部分内容，帮助快速定位配置和识别问题。\n- 移除 skill-card.md 文件，减少冗余文档。\n\nv4.2.0 | 2026-08-16T10:32:55.571Z | auto\n\nreceipt-compliance 4.2.0 brings major enhancements for banking reconciliation, batch performance, and configuration security.\n\n- 新增银行对账功能：可解析银行流水CSV并与发票金额/日期自动模糊匹配，生成对账报告\n- 新增基于硬件自适应的并行批量处理，批量识别速度提升3-5倍\n- 支持安全配置：密钥通过环境变量读取，消除明文泄露风险\n- 文档完善：功能表与说明已补充银行对账、并行批量、安全配置等新特性\n- 移除 skill-card.md，不再维护该文件\n\nv4.1.0 | 2026-08-05T15:29:11.862Z | auto\n\n**新增风险预警与归档管理功能，提升发票合规管理智能化与自动化水平：**\n\n- 新增“风险预警”能力，支持发票连号、整数金额、频繁开票、品名异常等智能风险检测，生成三级预警报告\n- 新增“归档管理”模块，支持发票归档包生成、四性检测、元数据采集与目录索引\n- 增加风险与供应商规则配置参考文档及配套脚本（references/risk_rules_config.yaml, supplier_scope_rules.md, scripts/risk_detector.py, archive_manager.py）\n- 文档全面更新，详细介绍风控和归档新功能的应用场景与操作方法\n- 移除冗余 skill-card.md，文档体系精简优化\n\nv4.0.0 | 2026-08-01T08:13:01.535Z | auto\n\n**Major update: Expands from发票OCR/查验/报销单→全票据/凭证一站式管控**\n\n- 新增对火车票、飞机票、出租车、定额发票、通行费、财政票据、全电发票（XML/OFD）等多种票据的自动识别和结构化解析\n- 引入智能分类（自动会计科目判别/进项税计算/凭证摘要生成）和一键自动生成记账凭证（用友/金蝶/QuickBooks等主流格式）\n- 新增专用解析与分类脚本：fiscal_parser, train_parser, fixed_parser, flight_parser, taxi_parser, toll_parser, smart_classifier, voucher_generator 等\n- 参考资料增加配置规则和会计科目映射（expense_rules.md, account_mapping.md）\n- 文档全面升级：功能表、FAQ、场景说明、操作引导等同步增强\n- skill-card.md移除，主文档内容\n\nv3.7.0 | 2026-07-22T09:29:43.827Z | auto\n\nreceipt-compliance 3.7.0\n\n- 增加4个新脚本：支持发票自动检测、OFD电子发票解析、统一发票处理、XML格式解析\n- 文档细节更新，完善能力说明及使用指南\n- 移除 skill-card.md（详情整合至主文档中）\n- 局部内容调整以反映脚本/能力结构优化\n\nv3.4.0 | 2026-07-13T07:47:21.302Z | auto\n\n# receipt-compliance 3.4.0 Changelog\n\n- Updated documentation files for improved clarity and user guidance.\n- Expanded example and reference materials (examples, API endpoints, setup guide) for easier integration.\n- Made minor script adjustments (approval abstraction, environment check, Tesseract install, engine verification) for better maintainability and usability.\n- Removed outdated documentation file (skill-card.md).\n\nv3.3.0 | 2026-07-13T07:15:20.899Z | auto\n\n**receipt-compliance 3.3.0 — 全链路财税流程助手**\n\n- Skill全功能本地运行，发票数据绝不外传，基础能力无需任何配置，安装即用。\n- 支持自然语言指示从发票OCR识别、真伪查验，到报销单自动填充和审批对接。\n- 内置实用安装与配置、常见问题速查表、批量处理、异常处理及效率提升技巧。\n- 大幅扩展FAQ、避坑指南、模糊发票处理等实用说明，降低集成与操作门槛。\n- 报销审批集成钉钉、企微、飞书，出厂含完整接口模板，支持企业自主选择查验与审批平台。\n- 保证所有代码及核心流程公开透明，可本地审计和按需扩展。\n\nArchive index:\n\nArchive v4.5.0: 52 files, 194592 bytes\n\nFiles: examples/example-approval.md (2757b), examples/example-ocr.md (1662b), examples/example-template.md (3025b), MEMORY.md (7285b), references/account_mapping.md (2148b), references/api-endpoints.md (3614b), references/expense_rules.md (1131b), references/risk_rules_config.yaml (2940b), references/risk-declaration.md (4304b), references/setup-guide.md (5781b), references/supplier_scope_rules.md (1683b), references/tax-rules.md (4732b), scripts/anomaly_detector.py (15804b), scripts/approval_abstract.py (9535b), scripts/approval_connector.py (22182b), scripts/approval_engine.py (7123b), scripts/archive_manager.py (20178b), scripts/bank_reconciler.py (17899b), scripts/batch_process.py (6297b), scripts/batch_splitter.py (16012b), scripts/cert_calendar.py (12524b), scripts/check_env.py (11739b), scripts/compliance_suite.py (10477b), scripts/dedup_engine.py (9578b), scripts/digital_invoice_reader.py (16861b), scripts/fiscal_parser.py (3907b), scripts/fixed_parser.py (4284b), scripts/flight_parser.py (4843b), scripts/invoice_detector.py (15914b), scripts/ledger_db.py (32451b), scripts/ocr_engine.py (29942b), scripts/ofd_parser.py (8937b), scripts/parallel_batch.py (14102b), scripts/receipt_parser.py (11799b), scripts/review_render.py (7201b), scripts/risk_detector.py (25571b), scripts/secure_config.py (8845b), scripts/smart_classifier.py (6220b), scripts/taxi_parser.py (4550b), scripts/template_matcher.py (15174b), scripts/toll_parser.py (4705b), scripts/train_parser.py (4191b), scripts/unified_invoice.py (6266b), scripts/verify_abstract.py (9938b), scripts/verify_engine.py (13326b), scripts/voucher_generator.py (8728b), scripts/xml_parser.py (14299b), skill-card.md (2281b), SKILL.md (70806b), templates/config_template.yaml (2145b), templates/expense_basic.xlsx (9031b), _meta.json (137b)\n\nFile v4.5.0:SKILL.md\n\n---\nname: receipt-compliance\ndescription: 会计助手：发票OCR识别→真伪查验→报销单自动填充→对接审批系统。企业自主配置，数据本地处理。\nversion: 4.5.0\n---\n\n\n# 会计助手\n\n> ⚠️ **使用必读**：本Skill所有功能在本地运行，发票数据绝不外传，但**绝不提供税务咨询**。使用前请先阅读【限制说明】和【风险声明】。\n\n## 功能说明\n\n本Skill提供从发票识别到审批提交的**全链路**财税合规能力。\n\n| 模块 | 功能 | 状态 | 输入 | 输出 |\n|------|------|------|------|------|\n| 1. 发票OCR识别 | 双引擎（PaddleOCR优先+Tesseract兜底），定额票先验定位，勾稽校验 | ✅ 直接可用 | 发票图片/PDF | 结构化JSON |\n| 2. 真伪查验 | 一键生成国税总局查验链接，自动打开浏览器 | ✅ 直接可用 | 发票代码/号码 | 查验链接+结果 |\n| 3. 报销单填充 | 自适应学习模板，一键填充 | ✅ 直接可用 | 发票数据+模板 | Excel文件 |\n| 4. 审批对接 | 对接钉钉/企微/飞书审批（有完整代码模板） | ⚠️ 需配置密钥 | 报销单+配置 | 审批结果 |\n| 5. 全电发票 | 全电发票XML/OFD格式解析 | ✅ 直接可用 | 全电发票文件 | 结构化JSON |\n| 6. 多票据支持 | 火车票/飞机票/出租车/定额发票/通行费/财政票据 | ✅ 直接可用 | 票据图片 | 统一结构化JSON |\n| 7. 智能分类 | 自动匹配会计科目、计算进项税、生成凭证摘要 | ✅ 直接可用 | 结构化发票数据 | 分类结果+科目 |\n| 8. 记账凭证 | 自动生成记账凭证（用友/金蝶/QuickBooks格式） | ✅ 直接可用 | 分类结果 | 凭证文件 |\n| 9. 风险预警 | 发票连号/整数金额/频繁开票/品名异常/进销项匹配检测 | ✅ 直接可用 | 发票列表 | 三级预警报告 |\n| 10. 归档管理 | 电子档案四性检测、归档包生成、元数据采集、目录索引 | ✅ 直接可用 | 发票文件 | 标准归档包 |\n| 11. 银行对账 | 银行流水 CSV 解析 + 发票金额/日期模糊匹配 | ✅ 直接可用 | 流水 CSV + 发票数据 | 对账报告 |\n| 12. 安全配置 | 环境变量读取密钥，消除明文泄露 | ✅ 直接可用 | 环境变量 | 安全配置 |\n| 13. 并行批量 | 硬件自适应并行处理，速度提升 3-5 倍 | ✅ 直接可用 | 发票文件夹 | 批量结果 |\n| 14. 混拍切分 | 混拍图（一拍多票）自动检测切分，保持原图索引 | ✅ 直接可用 | 混拍图片 | 单票子图 |\n| 15. 进销项台账 | SQLite 台账 + 月度统计，税负率趋势/供应商集中度/异常波动 | ✅ 直接可用 | 票据解析结果 | Excel 月度附件 |\n| 16. 认证期日历 | 认证期限取数 + 30/7 天两档提醒 + CSV 导出 | ✅ 直接可用 | 台账 | 到期清单 |\n| 17. 异常检测 | 轻量 Isolation Forest，金额/间隔/供应商三维打分 | ✅ 直接可用 | 票据列表 | 二级预警+触发维度 |\n| 18. 合规管理出口 | 规则预警 + 归档四性检测合并为一次执行 | ✅ 直接可用 | 票据 + 文件 | 统一合规报告 |\n| 19. 审批连接器 | 钉钉/企微/飞书统一接口（发送/查状态/回调验签） | ⚠️ 需配置密钥 | 报销单+配置 | 审批结果 |\n| 20. 数电票直读 | PDF/OFD 文本层结构化（pypdf 优先，缺失降级 OFD/PDF 文本）+ 二维码 TLV 解码核对 | ✅ 直接可用 | 数电票 PDF/OFD | 结构化 JSON（含明细行） |\n| 21. 重复报销查重 | 三信号两阶段：票号精确哈希 + 金额（±0.01）+ 日期（±3 天）近似比对，检出 P 图改抬头重复 | ✅ 直接可用 | 台账/票据列表 | 重复组清单 |\n| 22. 查重复工单 | 可疑项生成复核清单（两张原始凭证缩略图对照+差异标注，移动端可读），财务确认后进台账/误报标记豁免 | ⚠️ 需台账 | 复核清单 | HTML 对照页 |\n\n> ✅ = 装即用 ｜ ⚠️ = 需在 config.yaml 中配置对应API密钥\n>\n> 💡 **核心亮点**：发票识别、真伪查验、报销单生成 —— 这三项功能**完全不需要任何配置**，安装即用！\n\n### 设计理念\n\n1. **数据安全第一**：所有发票数据处理均在本地，不会上传到任何服务器\n2. **企业自主决策**：查验引擎、审批平台的选择权完全交给企业\n3. **透明开源**：所有代码可见可审计，无隐藏后门\n4. **渐进披露**：基础功能开箱即用，高级功能按配置解锁\n\n## 如何「指挥」它干活\n\n本Skill支持**自然语言对话**，不需要记忆任何命令。以下是各种场景下你可以直接对AI说的话：\n\n### 💬 直接用自然语言说\n\n| 你想做什么 | 直接这样说 |\n|-----------|-----------|\n| 识别一张发票 | \"帮我识别这张发票\" / \"OCR一下这个发票\" / \"扫描这张发票\" |\n| 批量识别 | \"把文件夹里所有发票都识别出来\" / \"批量扫描D:\\invoices\" |\n| 查验真伪 | \"帮我查验这张发票的真伪\" / \"查一下这个发票是不是真的\" |\n| 生成报销单 | \"用公司模板生成报销单\" / \"把识别结果填到报销单里\" |\n| 提交审批 | \"提交报销审批\" / \"发起审批\" / \"把报销单提交给钉钉审批\" |\n| 批量处理 | \"批量识别并生成报销单\" / \"把整个文件夹的发票都处理完\" |\n| 环境检查 | \"检查环境是否就绪\" / \"运行预检\" |\n| 查看帮助 | \"这个Skill能做什么\" / \"怎么用\" |\n\n### 📋 更详细的说法（推荐）\n\n**识别发票**：\n- \"请帮我识别这张发票：D:\\发票\\20260628.png\"\n- \"扫描这张发票，我要报销\"\n- \"OCR这张发票，结果保存到receipt.json\"\n\n**批量处理**：\n- \"把D:\\invoices\\里所有发票都识别出来，结果保存到output.json\"\n- \"批量扫描发票文件夹，然后生成合并报销单\"\n\n**查验真伪**：\n- \"帮我查验发票 代码:3100204130 号码:00564189\"\n- \"查一下这张发票是不是真的，发票号是00564189\"\n\n**生成报销单**：\n- \"用模板D:\\templates\\报销单.xlsx生成报销单\"\n- \"把receipt.json的数据填到报销单模板里\"\n\n**提交审批**：\n- \"把报销单提交到钉钉审批\"\n- \"发起企业微信审批，报销金额11300元\"\n\n> 💡 **小贴士**：直接上传发票图片或告诉AI文件路径，AI会自动识别你的意图并执行对应操作。\n\n## 📋 常见问题速查\n\n### 🔧 安装与配置\n\n| 问题 | 快速答案 |\n|------|---------|\n| 安装Tesseract后提示 `Tesseract not found` | 重启终端，或用 `--tesseract` 参数指定完整路径 |\n| 提示 `chi_sim not found` | 重新安装Tesseract，勾选 Chinese (Simplified) 语言包 |\n| 为什么不识别图片？ | 检查图片是否清晰、发票类型是否支持（手写/定额发票不支持） |\n| 常用安装命令 | Windows: `winget install UB-Mannheim.TesseractOCR` |\n| Mac安装 | `brew install tesseract tesseract-lang` |\n| Linux安装 | `sudo apt-get install tesseract-ocr tesseract-ocr-chi-sim` |\n\n### 📷 OCR识别\n\n| 问题 | 快速答案 |\n|------|---------|\n| 识别结果为空/少量内容 | 检查图片质量、光线、平整度、是否安装中文语言包 |\n| 识别率低/字段错误 | 使用扫描件、手机扫描APP预处理、核对关键字段 |\n| 批量处理部分失败 | 失败文件会单独记录在 `failed_files` 字段中，不影响其他文件 |\n| 图片质量要求 | ≥200DPI、光线均匀、无反光、发票平整放置 |\n| 提高识别率小技巧 | 扫描全能王APP预处理、使用扫描件、避免强光直射 |\n\n### 🏢 查验与审批\n\n| 问题 | 快速答案 |\n|------|---------|\n| 查验接口返回失败 | 检查API Key、网络访问、调用频率限制、查看日志 |\n| 审批Token获取失败 | 确认API Key正确、应用已开通权限、服务器IP已加白名单 |\n| 如何选择查验引擎 | 国税总局(免费) / 百望云/诺诺(付费API Key) / 自建接口 |\n| 支持哪些审批平台 | 钉钉、企业微信、飞书、自定义（需实现接口） |\n| 审批提交后能撤销吗 | 不可撤销（以各平台规则为准），提交前请核对内容 |\n\n### 📄 模板与数据\n\n| 问题 | 快速答案 |\n|------|---------|\n| 模板匹配失败 | 检查模板第一行是否为中文表头、文件是否损坏 |\n| 金额勾稽关系不匹配 | OCR识别错误时人工核对；0.01元以内差异属正常精度问题 |\n| 环境预检通过但OCR仍失败 | Tesseract版本过低（建议4.0+）、语言包不完整（≥5MB） |\n\n### 🛡️ 安全与合规\n\n| 问题 | 快速答案 |\n|------|---------|\n| 数据安全吗？ | 所有处理在本地完成，不会上传到任何服务器 |\n| 日志里有什么？ | 仅记录操作元数据（文件名、时间、状态），不记录发票内容 |\n| 能提供税务咨询吗 | 不能，本工具仅为技术支持，不提供税务/财务建议 |\n\n> 📖 **详细解答见下方【故障排除】部分**\n\n---\n\n## 💡 使用技巧与注意事项\n\n> 本节汇总了日常使用中最实用的技巧和注意事项，建议首次使用前快速浏览一遍。\n\n### 基本技巧\n\n| 序号 | 技巧 | 说明 |\n|------|------|------|\n| 1 | **优先用扫描件** | 扫描件比手机拍照识别率高15%-20%，文字更清晰、无反光 |\n| 2 | **手机拍照用扫描模式** | 微信/支付宝/扫描全能王APP都有\"文档扫描\"功能，能自动去阴影、纠偏 |\n| 3 | **批量处理先试一张** | 批量处理前先识别一张确认效果，避免批量失败浪费时间 |\n| 4 | **低置信度要核对** | 置信度<0.7时系统会提示警告，此时必须人工核对代码、号码、金额 |\n| 5 | **保留原始图片** | 识别失败时，系统会尝试用原始图片（跳过预处理）重新识别 |\n\n### 注意事项\n\n| 序号 | 注意点 | 原因 |\n|------|--------|------|\n| 1 | ⚠️ **OCR软件是一次性安装** | Tesseract约60MB，安装后永久使用，无需重复下载 |\n| 2 | ⚠️ **模糊发票必须手动核对** | OCR对模糊图片无法保证准确率，关键金额字段一定要人工复核 |\n| 3 | ⚠️ **审批功能需要配置API密钥** | 发票识别+验真假+报销单 无需配置，只有对接钉钉/企微/飞书审批才需要 |\n| 4 | ⚠️ **批量处理部分失败是正常的** | 系统会跳过失败文件继续处理，失败的记录在 `failed_files` 字段 |\n| 5 | ⚠️ **日志不记录发票内容** | 仅记录文件名、时间、状态等元数据，发票数据不上传不外传 |\n\n## ⚠️ 避坑指南\n\n> **本节汇总用户最容易踩的坑，每条都是真实使用中遇到的高频问题，建议首次使用前快速浏览一遍。**\n\n### 🔴 发票识别类\n\n| # | 问题现象 | 原因 | 解决方案 |\n|---|---------|------|---------|\n| 1 | 安装完Tesseract后仍然报错 | PATH环境变量未生效 | **Windows**：重启终端；或手动添加环境变量 `C:\\Program Files\\Tesseract-OCR` 到PATH |\n| 2 | 识别结果为空 | 未勾选中文语言包 | 重新运行安装包，勾选 **Chinese (Simplified)** 语言包 |\n| 3 | 金额识别错误（少0/多0） | 图片模糊或小字不清 | 用扫描APP（扫描全能王/白描）预处理图片后再试 |\n| 4 | 发票代码和号码搞反 | OCR把位置搞混了 | 代码10-12位，号码8-20位，自动识别后请人工核对位置 |\n| 5 | 电子发票PDF识别失败 | 缺少poppler | `pip install pdf2image` 并通过系统包管理器安装 poppler：Windows: `winget install poppler` 或 `scoop install poppler`；Linux: `sudo apt-get install poppler-utils`；macOS: `brew install poppler` |\n\n### 🟡 系统配置类\n\n| # | 问题现象 | 原因 | 解决方案 |\n|---|---------|------|---------|\n| 6 | 运行脚本时提示\"禁止执行\" | Windows执行策略限制 | 管理员身份运行PowerShell，执行 `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` |\n| 7 | pip下载依赖超时 | 网络不稳定或未配置镜像 | `pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple` |\n| 8 | 权限不足（PermissionError） | 文件被其他程序占用 | 关闭占用文件的程序（如Excel打开该文件）后重试 |\n| 9 | 找不到config.yaml | 未复制配置模板 | `copy templates/config_template.yaml config.yaml` |\n\n### 🟢 查验与审批类\n\n| # | 问题现象 | 原因 | 解决方案 |\n|---|---------|------|---------|\n| 10 | 查验链接无法打开 | 网络被防火墙拦截 | 用手机直接访问国税总局APP查验 |\n| 11 | 审批提交失败 | API密钥过期或权限不足 | 在钉钉/管理后台重新生成密钥，确认审批权限已开通 |\n| 12 | 审批提交后找不到记录 | 流程编码(process_code)填写错误 | 在钉钉管理后台核实正确的process_code |\n| 13 | Token获取失败 | AppKey/AppSecret错误或IP白名单未配置 | 核对密钥，联系管理员添加服务器IP到白名单 |\n\n### 🔵 效率提升类\n\n| # | 技巧 | 节省时间 |\n|---|------|---------|\n| 1 | 批量处理前先**试一张**确认效果 | 避免批量失败浪费时间 |\n| 2 | 建立公司模板文件复用 | 不用每次重新映射字段 |\n| 3 | 用桌面快捷方式存放常用脚本 | 不用每次都找路径 |\n| 4 | 手机拍照默认开\"扫描模式\" | 识别率提升15-20% |\n\n---\n\n### 模糊发票处理指南\n\n当发票图片模糊、识别效果不好时，按以下步骤处理：\n\n```\n步骤1：判断图片质量\n  → 图片分辨率<200DPI？ → 重新拍摄/扫描\n  → 有反光/阴影？       → 换个角度或光线重拍\n  → 发票褶皱严重？      → 展平后重新扫描\n\n步骤2：使用扫描APP预处理（推荐）\n  → 扫描全能王 / 白描 / 微信扫一扫\n  → APP会自动增强对比度、去阴影、纠偏\n  → 保存为JPG后重新识别\n\n步骤3：识别后人工核对\n  → 重点核对：发票代码(10-12位数字)、号码(8-20位数字)、金额\n  → 金额勾稽检查：金额 + 税额 = 价税合计？\n  → 置信度<0.7的字段重点核对\n\n步骤4：手动输入（终极方案）\n  → 如果反复识别失败，可直接手动输入发票信息\n  → 格式：python scripts/ocr_engine.py --manual\n  → 按提示输入发票代码、号码、日期、金额等\n```\n\n---\n\n## 对话示例\n\n本Skill支持通过自然语言对话方式使用，无需记忆复杂命令。\n\n### 场景1：识别单张发票\n\n```\n用户：请帮我识别这张发票 D:\\invoices\\20260628_001.png\nAI：正在识别发票...\n    ✓ 发票类型: 增值税专用发票\n    ✓ 发票代码: 3100204130\n    ✓ 发票号码: 00564189\n    ✓ 开票日期: 2026年06月28日\n    ✓ 金额: 10,000.00 元\n    ✓ 税额: 1,300.00 元\n    识别完成，已保存到 receipt.json\n```\n\n### 场景2：批量处理\n\n```\n用户：把文件夹里所有发票都识别出来\nAI：正在批量识别 D:\\invoices\\ 中的发票...\n    共发现 15 个图片文件\n    ✓ 20260628_001.png - 识别成功\n    ✓ 20260628_002.png - 识别成功\n    ⚠ 20260628_003.png - 识别失败（图片模糊）\n    ...\n    处理完成：成功 12 张，失败 3 张\n    结果已保存到 batch_result.json\n```\n\n### 场景3：查验发票真伪\n\n```\n用户：帮我查验这张发票的真伪\nAI：正在查验发票...\n    发票代码：3100204130\n    发票号码：00564189\n    ✓ 查验平台：国税总局\n    ✓ 发票状态：正常\n    ✓ 查验时间：2026-06-29 10:30:00\n```\n\n### 场景4：生成报销单\n\n```\n用户：用公司模板生成报销单\nAI：正在生成报销单...\n    ✓ 识别到 6 个字段映射\n    ✓ 已填充：开票日期、销方名称、金额、税额、价税合计、费用说明\n    报销单已生成：D:\\output\\expense_report.xlsx\n```\n\n## API调用示例\n\n### Python调用\n\n```python\nfrom scripts.ocr_engine import OCREngine\n\n# 初始化引擎\nengine = OCREngine()\n\n# 识别单张发票\nresult = engine.extract_structured_data(\"invoice.png\")\nprint(f\"发票代码: {result['invoice_code']}\")\nprint(f\"金额: {result['amount']}\")\n\n# 批量处理\nimport glob\nfor file in glob.glob(\"invoices/*.png\"):\n    result = engine.extract_structured_data(file)\n    print(f\"{file}: {result['success']}\")\n```\n\n### HTTP API调用\n\n```bash\n# 启动API服务（需安装flask）\npython scripts/api_server.py\n\n# 识别发票\ncurl -X POST http://localhost:8080/api/ocr \\\n  -F \"file=@invoice.png\"\n\n# 批量识别\ncurl -X POST http://localhost:8080/api/ocr/batch \\\n  -F \"files=@invoice1.png\" \\\n  -F \"files=@invoice2.png\"\n```\n\n## 快速配置向导（一键配置）\n\n**新手推荐**：运行以下命令自动检测环境并推荐最优配置：\n\n```bash\npython scripts/config_wizard.py\n```\n\n向导会自动完成：\n1. 检测Tesseract是否安装，未安装则提供一键安装命令\n2. 检测中文语言包是否完整\n3. 推荐查验引擎（默认：国税总局平台，免费无需API Key）\n4. 生成初始 `config.yaml` 文件\n5. 验证配置文件有效性\n\n**手动快速配置**（3步完成）：\n\n```bash\n# 1. 复制配置模板\ncp templates/config_template.yaml config.yaml\n\n# 2. 编辑配置（只需填写必填项）\n# 用编辑器打开 config.yaml，填写：\n#   - verify_engine: \"tax_bureau\" （默认，免费）\n#   - approval.platform: \"none\" （暂不配置审批）\n\n# 3. 验证配置\npython scripts/check_env.py\n```\n\n> 💡 **提示**：发票识别、验真假、生成报销单 —— 这三项**完全不需要配置**，安装即用！审批对接需要配置API密钥。\n\n## 🚀 5分钟上手指南\n\n> **30秒摘要**：安装识别软件 → 识别发票 → 生成报销单。全程无需写代码，无需配置API。\n\n### 完整流程图\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│                        5分钟快速上手流程                              │\n└─────────────────────────────────────────────────────────────────────┘\n\n 步骤1：安装（2分钟）                步骤2：识别（1分钟）\n ┌─────────────────────┐           ┌─────────────────────┐\n │ 一键安装PowerShell脚本 │    →     │ 拖入发票图片，自动识别 │\n │ (国内镜像，免配置)     │           │ 输出结构化JSON数据    │\n └─────────────────────┘           └─────────────────────┘\n                                            ↓\n 步骤4：（可选）一键生成报销单   ←   步骤3：验真假（30秒）\n ┌─────────────────────┐           ┌─────────────────────┐\n │ 用模板自动填充生成Excel │    ←     │ 一键生成查验链接       │\n │ 支持自定义字段映射      │           │ 自动打开浏览器查验     │\n └─────────────────────┘           └─────────────────────┘\n```\n\n### 🎯 三步开始使用\n\n**第1步 — 下载安装（2分钟）**：\n\n| 系统 | 操作 |\n|------|------|\n| **Windows** | 包管理器安装：`winget install --id UB-Mannheim.Tesseract`（或 `scoop install tesseract`），安装后重启终端 |\n| **Mac** | 终端执行 `brew install tesseract` |\n| **Linux** | `sudo apt-get install tesseract-ocr tesseract-ocr-chi-sim pip install Pillow pytesseract openpyxl pyyaml` |\n\n**第2步 — 识别发票（30秒）**：\n\n```bash\n# 单张识别\npython scripts/ocr_engine.py --input 发票图片.png --output 识别结果.json\n\n# 批量识别整个文件夹\npython scripts/batch_process.py --input 发票文件夹/ --output 批量结果.json\n```\n\n**第3步 — 查验+报销单（1分钟）**：\n\n```bash\n# 生成国税总局查验链接（自动打开浏览器）\npython scripts/verify_engine.py --invoice-code 3100204130 --invoice-number 00564189 --date \"2026年06月28日\" --amount 10000.00 --open-browser\n\n# 生成报销单Excel\npython scripts/template_matcher.py fill --receipt receipt.json --template templates/expense_basic.xlsx --output 报销单.xlsx\n```\n\n### ✅ 安装验证\n\n```bash\npython scripts/check_env.py\n```\n- ✅ 显示\"环境就绪\" → 直接开始用\n- ❌ 有红叉 → 按提示修复后重试\n\n### ⚙️ 高级功能配置（可选）\n\n如果需要使用查验真伪或提交审批功能，才需要配置 `config.yaml`：\n\n```bash\n# 复制配置模板\ncp templates/config_template.yaml config.yaml\n\n# 编辑配置文件，填入API密钥\nnotepad config.yaml  # Windows\nnano config.yaml     # Linux/macOS\n```\n\n## 审批功能 - 完整配置指南\n\n> **30秒摘要**：审批功能提供了完整的代码引擎，企业只需在config.yaml中填入3个凭证即可使用，无需写任何代码。\n\n### 钉钉审批配置（3步完成）\n\n**第1步：创建钉钉应用**\n\n打开 [钉钉开放平台](https://open-dev.dingtalk.com) → 创建企业内部应用 → 记录下 **AppKey** 和 **AppSecret**\n\n**第2步：开通应用权限**\n\n在应用管理页面：\n- 权限管理 → 搜索\"审批\" → 开通 **审批:write** 权限\n- 基础设置 → 添加服务器出口IP到IP白名单\n\n**第3步：获取流程编码**\n\n钉钉管理后台 → 审批流程管理 → 编辑报销审批流程 → 在URL中获取 `process_code`\n\n```yaml\napproval:\n  platform: \"dingtalk\"\n  dingtalk:\n    app_key: \"你的AppKey\"\n    app_secret: \"你的AppSecret\"\n    process_code: \"你的流程编码\"\n```\n\n### 企业微信审批配置（3步完成）\n\n**第1步：创建自建应用**\n\n企业微信管理后台 → 应用管理 → 创建自建应用 → 记录下 **CorpID** 和 **Secret**\n\n**第2步：开通审批权限**\n\n在应用详情页 → 功能 → 审批 → 配置审批模板 → 获取 **TemplateID**\n\n**第3步：配置IP白名单**\n\n企业微信管理后台 → 应用管理 → 自建应用 → 接收消息设置 → 获取出口IP并添加到白名单\n\n```yaml\napproval:\n  platform: \"wecom\"\n  wecom:\n    corp_id: \"你的CorpID\"\n    secret: \"你的Secret\"\n    template_id: \"你的TemplateID\"\n```\n\n### 审批测试方法\n\n配置完成后，运行以下命令验证审批功能是否配置正确：\n\n```bash\n# 测试钉钉审批\npython scripts/approval_engine.py \\\n  --config config.yaml \\\n  --expense 报销单.xlsx \\\n  --user-id 你的工号 \\\n  --amount 10000 \\\n  --expense-type 信息技术服务\n```\n\n如果配置正确，返回结果示例：\n```json\n{\n  \"status\": \"success\",\n  \"message\": \"审批提交成功\",\n  \"approval_id\": \"xxx\",\n  \"submit_time\": \"2026-07-04T22:30:00\"\n}\n```\n\n---\n\n## 详细配置说明\n\n见 `references/setup-guide.md`\n\n## 示例\n\n### 示例1：识别单张发票\n\n**输入**：\n\n```\n识别发票 D:\\invoices\\20260628_001.png\n```\n\n**输出**：\n\n```json\n{\n  \"success\": true,\n  \"invoice_type\": \"增值税专用发票\",\n  \"invoice_code\": \"3100204130\",\n  \"invoice_number\": \"00564189\",\n  \"invoice_date\": \"2026年06月28日\",\n  \"seller_name\": \"上海某某科技有限公司\",\n  \"amount\": 10000.00,\n  \"tax_rate\": 0.13,\n  \"tax_amount\": 1300.00,\n  \"total\": 11300.00,\n  \"remark\": \"*信息技术服务费*\",\n  \"confidence\": 0.96\n}\n```\n\n### 示例2：查验发票真伪\n\n**输入**：\n\n```\n查验发票 代码:3100204130 号码:00564189 日期:2026-06-28 金额:10000.00\n```\n\n**输出**：\n\n```json\n{\n  \"engine\": \"国税总局查验平台\",\n  \"status\": \"ready\",\n  \"verify_url\": \"https://inv-veri.chinatax.gov.cn/index.html?fpdm=3100204130&fphm=00564189\",\n  \"message\": \"已为您生成查验链接，点击即可查验\",\n  \"params\": {\n    \"invoice_code\": \"3100204130\",\n    \"invoice_number\": \"00564189\",\n    \"billing_date\": \"2026-06-28\",\n    \"amount\": 10000.00\n  }\n}\n```\n\n> 如配置了百望云/诺诺API Key，会自动调用第三方API获取查验结果。\n\n### 示例3：生成报销单\n\n**输入**：\n\n```\n用模板 D:\\templates\\公司报销单.xlsx 生成报销单，数据来自 D:\\invoices\\receipt.json\n```\n\n**输出**：\n\n```\n模板分析完成：识别到 6 个字段映射，置信度 0.8+\n报销单已生成：D:\\output\\expense_report_20260629.xlsx\n已填充 6 个字段：开票日期、销方名称、金额、税额、价税合计、费用说明\n```\n\n### 示例4：批量识别并合并为报销单\n\n```bash\npython scripts/batch_process.py --input D:\\invoices\\ --template D:\\templates\\公司报销单.xlsx --output D:\\output\\合并报销单.xlsx\n```\n\n### 示例5：提交审批\n\n```bash\npython scripts/approval_engine.py --config config.yaml --expense D:\\output\\报销单.xlsx --user-id manager123 --amount 11300 --expense-type 信息技术服务\n```\n\n## 发票类型支持与图片要求\n\n> **30秒摘要**：支持增值税专票/普票/电子票。识别效果高度依赖图片质量——扫描件>拍照，清晰>模糊，建议分辨率≥200DPI。\n\n### 支持的发票类型\n\n- ✅ 增值税专用发票\n- ✅ 增值税电子发票\n- ✅ 增值税普通发票\n- ✅ 电子发票（PDF格式，需安装poppler）\n\n### 暂不支持\n\n- ❌ 手写发票\n- ❌ 定额发票\n- ❌ 机动车销售发票\n- ❌ 二手车销售发票\n- ❌ 海关缴款书\n\n### 图片质量要求（直接影响识别率）\n\n> ⚠️ **重要提醒**：Tesseract OCR识别效果**高度依赖图片质量**。模糊、反光、低分辨率的图片会导致识别率显著下降。\n\n| 质量等级 | 分辨率 | 光线 | 平整度 | 预期准确率 |\n|---------|--------|------|--------|-----------|\n| 优秀 | ≥300DPI | 均匀 | 无褶皱 | 95%+ |\n| 良好 | 200-300DPI | 较均匀 | 轻微褶皱 | 85-95% |\n| 可用 | 150-200DPI | 一般 | 有褶皱 | 70-85% |\n| 较差 | <150DPI | 反光/阴影 | 严重褶皱 | <70%，建议重新拍摄 |\n\n**图片质量自检清单**：\n- [ ] 发票代码和号码区域是否清晰可辨？\n- [ ] 金额数字是否有模糊或重影？\n- [ ] 是否有反光或阴影遮挡关键信息？\n- [ ] 发票边缘是否完整可见？\n- [ ] 图片分辨率是否足够（建议手机相机≥1200万像素）？\n\n> **提高识别率的小技巧**：\n> 1. 用手机相机拍摄时，开启\"文档模式\"或\"扫描模式\"\n> 2. 避免强光直射，减少反光\n> 3. 发票平整放置，不要弯曲\n> 4. 确保发票代码、号码区域清晰可见\n> 5. 如果无法识别，请检查图片中是否有手写涂改\n> 6. **推荐使用扫描件**，比拍照效果更好\n> 7. 可使用手机扫描APP（如\"扫描全能王\"）预处理图片\n\n## 限制说明\n\n> **30秒摘要**：仅支持增值税发票（不支持手写/定额），数据全部本地处理（不上传），不提供税务咨询。\n\n### 功能限制\n\n| 限制项 | 具体说明 |\n|--------|---------|\n| OCR识别 | 仅支持增值税发票（专票/普票/电子票） |\n| 暂不支持 | 手写发票、定额发票、机动车发票、二手车发票 |\n| 查验功能 | 国税总局查验链接自动生成，无需API Key |\n| 审批功能 | 需企业管理员在对应平台开通审批API权限，提供完整代码模板和分步配置指南 |\n\n### 技术限制\n\n| 限制项 | 具体说明 |\n|--------|---------|\n| 运行环境 | Python 3.8+ |\n| 必须安装 | Tesseract OCR + 中文语言包 |\n| 图片格式 | PNG/JPG/TIFF/PDF（PDF需要poppler） |\n| 语言 | 中文简体，其他语言准确率显著下降 |\n| 并发 | 硬件自适应并行处理（CPU 核心数 × 0.5/× 0.75），批量速度提升 3-5 倍 |\n\n### 安全限制\n\n| 限制项 | 具体说明 |\n|--------|---------|\n| 数据上传 | 绝不将发票图片上传到任何第三方服务器 |\n| API调用 | 仅在用户明确授权后执行，且仅调用用户配置的平台 |\n| 日志 | 仅记录操作元数据（文件名、时间、状态），不记录发票内容 |\n| 临时文件 | 识别完成后自动清理，保留不超过24小时 |\n\n## 错误代码速查表\n\n| 错误代码 | 问题描述 | 解决方案 |\n|---------|---------|---------|\n| `Tesseract not found` | Tesseract未安装或未加入PATH | 用包管理器安装（Windows: winget/scoop；Mac: brew；Linux: apt）并重启终端 |\n| `chi_sim not found` | 中文语言包未安装 | 重新安装Tesseract，勾选Chinese语言包 |\n| `PIL not found` | Pillow未安装 | `pip install Pillow` |\n| `pytesseract not found` | pytesseract未安装 | `pip install pytesseract` |\n| `openpyxl not found` | openpyxl未安装 | `pip install openpyxl` |\n| `pdf2image not found` | PDF转图片工具未安装 | `pip install pdf2image` + 安装poppler |\n| `empty result` | OCR未识别到文字 | 检查图片质量、光线、平整度 |\n| `low confidence` | 识别置信度低于0.7 | 建议重新拍摄，或手动输入发票信息 |\n| `verify_engine not configured` | 查验引擎未配置 | 编辑config.yaml，填写对应API Key |\n| `approval_engine not configured` | 审批引擎未配置 | 编辑config.yaml，选择并填写审批平台 |\n| `token_failed` | 获取AccessToken失败 | 检查API Key/Secret是否正确 |\n| `template_not_found` | 模板文件不存在 | 检查template路径是否正确 |\n\n## 风险声明\n\n> **30秒摘要**：数据本地处理不上传、查验结果由第三方平台提供、审批不可撤销、本工具不提供税务咨询。\n\n> 🔴 **使用本Skill前，请务必仔细阅读以下条款：**\n\n### 1. 数据安全责任\n\n- 所有发票数据仅在用户本地设备处理，不会上传到任何服务器\n- **但用户需自行确保本地设备的安全**，Skill开发者不对数据泄露承担责任\n- 用户需自行负责API密钥的安全保管\n- 建议定期轮换API密钥（每90天一次）\n\n### 2. 查验结果免责声明\n\n- 查验引擎返回的结果由第三方平台提供\n- Skill仅提供技术对接，**不对查验结果的准确性负责**\n- 如对查验结果有疑问，请直接联系相关税务平台\n\n### 3. 审批操作责任\n\n- 审批提交后不可撤销（以各平台规则为准）\n- Skill不审批内容的合规性和真实性\n- 用户对提交的报销单内容负全部责任\n\n### 4. 财务合规要求\n\n- 本工具仅为技术支持工具，**不提供任何税务咨询或财务建议**\n- 所有财务决策应由专业财务人员做出\n- 需专业税务意见时，请咨询持牌税务顾问\n\n### 5. 禁止行为\n\n使用本Skill，用户不得：\n- 伪造、变造发票\n- 使用假发票报销\n- 虚增报销金额\n- 报销与业务无关的费用\n- 进行其他违反财务法规的行为\n\n### 6. 企业自主决策清单\n\n使用前，请确认您已决定以下事项：\n\n- [ ] 查验引擎选择：□ 国税总局平台（免费） □ 百望云 □ 诺诺发票 □ 自建接口\n- [ ] 审批平台选择：□ 钉钉 □ 企业微信 □ 飞书 □ 自建系统 □ 暂不使用\n- [ ] 数据安全策略：日志保留期限、临时文件清理频率\n- [ ] 合规审查：内部审计、外部审计计划\n\n## 配置文件模板\n\n```yaml\n# config.yaml - 企业自主配置\n# 本文件为示例模板，企业需根据实际情况填写\n# 未配置的功能模块将提示手动操作\n\n# ==================== 查验引擎配置 ====================\nverify_engine: \"tax_bureau\"\n# 可选值:\n# - \"tax_bureau\": 国税总局查验平台（免费，无需API Key）\n# - \"bairong\": 百望云API（需API Key+Secret）\n# - \"nuonuo\": 诺诺发票API（需API Key+Secret）\n# - \"custom\": 企业自建接口（需接口地址）\n\n# 百望云（如选择bairong）\nbairong:\n  api_key: \"在此填写您的百望云API Key\"\n  api_secret: \"在此填写您的百望云Secret\"\n\n# 诺诺发票（如选择nuonuo）\nnuonuo:\n  api_key: \"在此填写您的诺诺发票API Key\"\n  api_secret: \"在此填写您的诺诺发票Secret\"\n\n# 自建查验接口（如选择custom）\ncustom:\n  endpoint: \"https://your-company.com/api/verify\"\n  method: \"POST\"\n  headers:\n    Authorization: \"Bearer YOUR_TOKEN\"\n\n# ==================== 审批平台配置 ====================\napproval:\n  platform: \"none\"  # dingtalk / wecom / feishu / none\n\n  # 钉钉审批\n  dingtalk:\n    app_key: \"\"\n    app_secret: \"\"\n    process_code: \"\"\n\n  # 企业微信审批\n  wecom:\n    corp_id: \"\"\n    secret: \"\"\n    template_id: \"\"\n\n  # 飞书审批\n  feishu:\n    app_id: \"\"\n    app_secret: \"\"\n    approval_code: \"\"\n\n  # 自建审批系统\n  custom:\n    endpoint: \"\"\n    method: \"POST\"\n    headers: {}\n    timeout: 30\n\n# ==================== 模板映射配置 ====================\ntemplate:\n  path: \"templates/expense_basic.xlsx\"  # 报销单模板路径\n  field_mapping:\n    invoice_date: \"开票日期\"\n    seller_name: \"销方名称\"\n    amount: \"金额（不含税）\"\n    tax_amount: \"税额\"\n    total: \"价税合计\"\n    remark: \"费用说明\"\n    invoice_code: \"发票代码\"\n    invoice_number: \"发票号码\"\n```\n\n## 外部平台不可用时的降级方案\n\n> 💡 **重要提示**：查验和审批功能依赖外部平台（国税总局、钉钉、企微、飞书等），遇到平台维护或网络故障时，可使用以下降级方案。\n\n### 查验发票真伪 - 降级方案\n\n当自动查验平台不可用时，可手动查验：\n\n**方法1：使用国税总局官方平台**（推荐）\n1. 打开浏览器，访问：https://inv-veri.chinatax.gov.cn\n2. 输入发票代码、发票号码、开票日期、开具金额（不含税）\n3. 输入验证码，点击\"查验\"\n4. 截图或保存查验结果备查\n\n**方法2：使用手机APP查验**\n- 国家税务总局\"增值税发票查验平台\"APP\n- 支付宝\"发票管家\" - 发票查验功能\n- 微信\"腾讯发票\" - 发票查验功能\n\n**方法3：电话查验**\n- 拨打12366纳税服务热线，提供发票信息查询真伪\n\n### 提交审批 - 降级方案\n\n当自动审批提交不可用时，可手动提交：\n\n**钉钉审批**：\n1. 打开钉钉APP → 工作台 → 审批\n2. 找到对应的报销审批流程\n3. 手动填写报销信息，上传报销单PDF\n4. 提交审批\n\n**企业微信审批**：\n1. 打开企业微信APP → 工作台 → 审批\n2. 选择报销审批流程\n3. 填写信息，上传附件\n4. 提交审批\n\n**飞书审批**：\n1. 打开飞书APP → 工作台 → 审批\n2. 创建新的报销审批\n3. 填写表单，上传报销单\n4. 提交审批\n\n### 数据存储建议\n\n在外部平台不可用期间，建议：\n1. 将识别结果保存为JSON文件（`--output result.json`）\n2. 将报销单保存为PDF（`--format pdf`）\n3. 平台恢复后，使用批量提交功能一次性提交\n\n## 故障排除\n\n### 常见问题\n\n**Q1: 安装Tesseract后仍然提示 `Tesseract not found`**\n\nA: 通常是PATH环境变量未生效。\n\n- **Windows**：重启PowerShell/终端，或手动运行 `refreshenv`\n- **Linux/macOS**：运行 `source ~/.bashrc` 或 `source ~/.zshrc`\n- 紧急方案：使用 `--tesseract` 参数指定完整路径：\n  ```bash\n  python ocr_engine.py --tesseract \"C:\\Program Files\\Tesseract-OCR\\tesseract.exe\" --input 发票.png\n  ```\n\n**Q2: 识别结果为空或仅识别到少量内容**\n\nA: 按顺序排查：\n1. 图片质量是否过低？（拍摄光线、平整度、分辨率）\n2. 发票类型是否支持？（手写发票不支持）\n3. 是否安装了中文语言包？（运行 `tesseract --list-langs` 检查是否有 `chi_sim`）\n4. 尝试提高图片预处理质量（在代码中调整阈值参数）\n5. 尝试用原始图片（未预处理）重新识别 — 某些情况下预处理反而会降低图片质量\n\n**Q3: 提示 `PermissionError` 或 `Occupied`**\n\nA: 文件被其他程序关闭。请关闭所有占用目标文件的程序后重试。\n\n**Q4: 查验接口返回失败**\n\nA: 排查顺序：\n1. 检查API Key/Secret是否正确（无多余空格）\n2. 检查网络是否可访问对应平台\n3. 检查是否超出调用频率限制\n4. 查看 `logs/verify_engine.log` 了解详细错误\n\n**Q5: 模板匹配失败**\n\nA: 检查以下几点：\n1. 模板文件第一行是否为中文表头\n2. 模板文件是否未损坏（用Excel打开确认）\n3. 字段名是否在预设映射表中（见 `common_mappings`）\n4. 可尝试手动指定映射关系\n\n**Q6: 如何减小识别结果文件体积？**\n\nA: 处理完成后，删除 `output/` 目录下的中间文件（`.json`、`.xlsx`），仅保留最终需要的文件。Skill会自动清理临时文件。\n\n**Q7: 支持哪些审批平台？**\n\nA: 钉钉、企业微信、飞书、自建系统（需实现接口）。\n\n**Q8: 如果审批平台不在列表中怎么办？**\n\nA: 使用 `custom` 选项，填写企业自建审批系统的接口地址和鉴权方式。\n\n**Q9: OCR识别率低，很多字段识别错误**\n\nA: 识别效果主要取决于图片质量，请尝试以下方法：\n1. **图片质量**：确保分辨率≥200DPI，光线均匀，无反光\n2. **推荐使用扫描件**：扫描件比拍照效果更好，文字更清晰\n3. **使用手机扫描APP**：如\"扫描全能王\"、\"白描\"等APP预处理图片，可显著提升识别率\n4. **图片格式**：优先使用JPG或PNG，避免PDF（需额外安装poppler）\n5. **发票类型**：仅支持增值税专票/普票/电子票\n6. **手动校验**：识别后人工核对关键字段（代码、号码、金额）\n7. **模板学习**：使用 `template_matcher.py analyze` 分析模板结构\n\n**Q10: 批量处理时部分文件失败**\n\nA: 正常现象，不影响其他文件。失败的文件会记录在JSON输出的 `failed_files` 字段中，包含：\n- `file`：文件路径\n- `error`：错误原因\n- `tip`：建议操作\n- `suggestions`：具体改进建议\n\n**Q11: 审批Token获取失败**\n\nA: 排查步骤：\n1. 确认API Key/Secret正确（无空格、大小写正确）\n2. 确认应用已开通审批权限（钉钉/企微/飞书管理后台）\n3. 确认服务器IP已在白名单中\n4. 确认Token未过期（默认2小时有效期）\n5. 检查网络是否可访问对应API地址\n\n**Q12: 如何选择合适的查验引擎？**\n\nA: 根据企业需求选择：\n- **国税总局平台（推荐）**：免费，无需API Key，生成链接手动查验\n- **百望云/诺诺发票**：需付费API Key，自动返回查验结果\n- **自建接口**：适合有自建查验系统的企业\n\n**Q13: 金额勾稽关系不匹配怎么办？**\n\nA: 可能原因：\n1. OCR识别错误：人工核对金额、税额、价税合计\n2. 小数精度问题：系统自动四舍五入，0.01元以内差异可忽略\n3. 特殊发票：部分发票金额计算方式不同\n\n**Q14: 环境预检通过但OCR仍失败**\n\nA: 可能原因：\n1. Tesseract版本过低（建议4.0+）\n2. 中文语言包不完整（检查文件大小≥5MB）\n3. 图片质量极差（重新拍摄）\n4. 发票类型不支持（手写发票、定额发票不支持）\n\n### 日志文件说明\n\n如果以上方案均无法解决问题，请查看日志文件获取详细信息：\n\n```\nlogs/\n├── ocr_engine.log          # OCR识别详情\n├── verify_engine.log       # 查验详情\n├── template_matcher.log    # 模板匹配详情\n├── approval_engine.log     # 审批详情\n└── error.log               # 错误日志（优先查看）\n```\n\n## 支持与反馈\n\n- 问题反馈：请在 SkillHub 平台提交 Issue\n- 功能建议：欢迎提交 Pull Request\n- 邮箱：联系Skill开发者\n- 联系信息：njskills@agent.qq.com\n- 版本更新提醒：检测到新版本发布时，请及时通过 tongyifabu.ps1 更新本 Skill 以获取最新功能和修复\n\n## 全电发票（数电票）\n\n本 Skill 已支持全电发票（全面数字化的电子发票），兼备传统发票 OCR 与全电发票 XML/OFD 解析的双轨模式。\n\n### 支持的文件类型\n\n| 类型 | 扩展名 | 解析方式 |\n|------|--------|---------|\n| 传统纸质发票 | `.png`、`.jpg`、`.jpeg`、`.bmp` | OCR 引擎识别 |\n| 传统电子发票（PDF） | `.pdf` | 数电票走直读（pypdf 文本层，无需 poppler），非数电走通用 OCR |\n| 全电发票（XML） | `.xml` | 专用 XML Schema 解析器，提取结构化数据 |\n| 全电发票（OFD） | `.ofd` | OFD 解析器或转换为 PDF 后 OCR |\n\n### 全电发票特有字段\n\n| 字段 | 说明 | 传统发票字段差异 |\n|------|------|-----------------|\n| 发票号码（20位） | 全电发票唯一标识 | 传统发票 8-20 位 |\n| 税务数字账户 ID | 数电票归集账户标识 | 传统发票无此概念 |\n| 校验码 | 全电票安全校验 | 传统发票为密码区 |\n| 特定业务信息 | 差额计税、建筑服务等标识 | 传统发票无明确标记 |\n\n### 使用方式\n\n**全电发票 XML 文件**：\n```bash\npython scripts/xml_parser.py path/to/invoice.xml\n```\n\n**全电发票 OFD 文件**：\n```bash\npython scripts/ofd_parser.py path/to/invoice.ofd\n```\n\n**自动识别（推荐）**：\n```bash\npython scripts/invoice_detector.py path/to/any_invoice\n```\n\n模块会自动判断文件类型并调用对应解析器。\n\n### 降级方案\n\n当 `ofdparser` Python 库未安装时，OFD 解析器会提示您：\n\n1. **安装 ofdparser**：`pip install ofdparser`（首选）\n2. **转换为 PDF**：使用数科阅读器、福昕 OFD 阅读器导出为 PDF，再用 OCR 识别\n3. **手动阅读**：通过官方 OFD 阅读器手动查看\n\n### 税务数字账户接口说明\n\n全电发票通过税务数字账户归集管理。如需对接税务数字账户接口，可参考：\n\n- 电子税务局官方文档：https://etax.chinatax.gov.cn/\n- 发票查验（国税总局）：https://inv-veri.chinatax.gov.cn/\n\n> ⚠️ **注意**：税务数字账户对接以企业自主配置为原则，本 Skill 提供标准接口框架，企业需根据实际税局接口规范自行实现具体调用逻辑。\n\n## 数电票直读与查重强化（v4.5.0）\n\n### 20. 数电票直读（PDF/OFD 不依赖通用 OCR）\n\n数电票 PDF/OFD 含结构化文本层，本版提供直读通道，跳过通用 OCR 的版面漂移问题：\n\n- **PDF 文本层直读**：优先 `pypdf` 抽取文本，`pdfminer.six` 次之，再降级 OCR；文本层缺失（扫描件 PDF）时退回通用 OCR 流程\n- **OFD 文字层直读**：优先 `ofdparser` 取文字，缺失则返回结构信息并提示安装\n- **票面要素 + 明细行**：发票号码/日期/价税合计/税额/税率/买卖方，以及数电票明细行（项目名称/规格/数量/单价/金额/税率/税额）一并结构化\n- **二维码 TLV 解码核对**：从 PDF 内嵌二维码提取 `pyzbar` 解码（缺失则跳过），与票面号码/代码交叉校验，不一致明确告警\n\n```bash\n# 数电票 PDF 直读\npython scripts/digital_invoice_reader.py pdf path/to/invoice.pdf\n\n# 数电票 OFD 直读\npython scripts/digital_invoice_reader.py ofd path/to/invoice.ofd\n\n# 自动识别（数电票 PDF 将走直读而非通用 OCR）\npython scripts/invoice_detector.py path/to/any_invoice\n```\n\n> 依赖策略（死规则 #9）：`pypdf` / `pdfminer.six` / `ofdparser` / `pyzbar` 均「优先 import、缺失即降级」，不强制安装；未装时功能降级但主流程不中断。\n\n### 21. 重复报销查重（三信号两阶段）\n\n针对报销重复（含 P 图改抬头）做两阶段检测：\n\n| 阶段 | 信号 | 逻辑 | 覆盖场景 |\n|------|------|------|---------|\n| 一 | 票号精确哈希 | 同号即重复 | 原样重复报销 |\n| 二 | 金额 ±0.01 + 日期 ±3 天 + 销售方/票号前缀相似 | 近似比对 | 改了抬头/票号但金额日期一致的变造重复 |\n\n```bash\n# 对台账全部票据跑查重，自动生成复核工单（幂等，已建单不重复）\npython scripts/ledger_db.py --dedup\n\n# 查看复核工单（pending / confirmed_dup / exempt / all）\npython scripts/ledger_db.py --list-reviews pending\n```\n\n查全率目标：20 组重复样本 ≥ 95%；数电票 PDF/OFD 各 10 份要素抽取准确率 ≥ 98%。\n\n### 22. 查重复工单化（复核清单 + 移动端对照）\n\n每次查重命中的可疑组生成一条复核工单，财务在桌面端确认、移动端查阅：\n\n```bash\n# 渲染工单为移动端可读 HTML（双原始凭证缩略图对照 + 差异标注）\npython scripts/ledger_db.py --render-review 工单ID 复核对照.html\n\n# 财务确认：confirmed_dup（重复，相关票据不进台账）/ exempt（误报，沉淀为豁免规则）\npython scripts/ledger_db.py --resolve-review 工单ID confirmed_dup\npython scripts/ledger_db.py --resolve-review 工单ID exempt\n```\n\n- 数电票渲染首页缩略图，纸票用扫描图；渲染失败仅展示要素差异表，不影响查阅\n- 误报标记 `exempt` 后自动沉淀为豁免规则，后续同组合不再重复告警\n\n## 台账与合规管理（v4.4.0）\n\n### 15. 进销项台账与月度统计\n\n把散落的票据识别结果沉淀成可分析的资产。数据库默认落在 `~/.workbuddy/output/receipt_ledger.db`，不写入 Skill 仓库。\n\n```bash\n# 导入票据解析结果（进项）\npython scripts/ledger_db.py --import-json result.json --direction input\n\n# 导入销项（用于税负率与进销项匹配）\npython scripts/ledger_db.py --import-json output.json --direction output\n\n# 输出四类报表视图\npython scripts/ledger_db.py --report\n\n# 导出 Excel 月度附件（未装 openpyxl 时自动降级 CSV）\npython scripts/ledger_db.py --export-excel\n```\n\n四类报表视图：\n\n| 视图 | 说明 | 用途 |\n|------|------|------|\n| 月度汇总 | 按月份 × 进销项汇总张数/金额/税额 | 月度结账底稿 |\n| 税负率趋势 | 税负率 = (销项税额 − 进项税额) ÷ 不含税销售额 | 异常波动自查 |\n| 供应商集中度 | Top N 供应商金额占比 + Top1 占比环比变化 | 依赖度风险 |\n| 异常波动 | 月度金额 z-score，默认 ±2.5 标注 | 收入异常自查 |\n\n### 16. 到期与认证期日历\n\n```bash\n# 全电发票自动推算认证期限（开票日期 + 窗口，默认 360 天）\npython scripts/cert_calendar.py --ensure-deadlines\n\n# 纸票手工补录\npython scripts/cert_calendar.py --set-deadline 12345678 2027-03-31\n\n# 扫描到期（30 天 / 7 天两档 + 已过期）\npython scripts/cert_calendar.py --scan\n\n# 导出 CSV 供日历软件二次提醒\npython scripts/cert_calendar.py --scan --export-csv\n\n# 注册每日 09:00 自动扫描（Windows schtasks，不生成任何 .bat/.ps1）\npython scripts/cert_calendar.py --register\npython scripts/cert_calendar.py --status\npython scripts/cert_calendar.py --unregister\n```\n\n> 说明：自 2020-03-01 起增值税专用发票已取消 360 天认证确认期限，此处窗口仅作企业内部「勾选所属期」管理提醒，可在 `references/risk_rules_config.yaml` 的 `certification.window_days` 调整。\n\n### 17. 异常检测（轻量 Isolation Forest）\n\n在 5 类规则预警之上叠加一层无监督检测，纯 numpy 实现，无需 sklearn；numpy 缺失时自动降级纯 Python。\n\n```bash\n# 从台账直接读\npython scripts/anomaly_detector.py ~/.workbuddy/output/receipt_ledger.db --db --top 20\n\n# 或从票据 JSON\npython scripts/anomaly_detector.py invoices.json --trees 100 --warn 0.65\n```\n\n输出示例：\n\n```json\n{\n  \"level\": \"严重\",\n  \"invoice_number\": \"24312000000012345678\",\n  \"score\": 0.71,\n  \"dimension_scores\": {\"amount\": 0.72, \"interval\": 0.41, \"supplier\": 0.68},\n  \"triggered_dimensions\": [\"amount\", \"supplier\"],\n  \"explanation\": \"金额分布异常（999999.00 元偏离常规区间，得分 0.72）；供应商组合异常（该供应商出现 5 次、占比 97.9%，得分 0.68）\"\n}\n```\n\n性能约束：样本超过 5000 自动采样，树数量默认 100 棵，单核千张票据秒级完成，不影响日常办公。\n\n### 18. 合规管理统一出口\n\n一次执行同时产出风险报告与归档四性检测结果，不再分两次跑。\n\n```bash\n# 从台账读取 + 指定票据目录做四性检测\npython scripts/compliance_suite.py --db ~/.workbuddy/output/receipt_ledger.db \\\n    --files-dir ./invoices --output report.json\n\n# 关闭异常检测\npython scripts/compliance_suite.py --invoices invoices.json --no-anomaly\n```\n\n输出整体状态：`合规` / `需关注` / `需立即处理`。\n\n### 19. 审批连接器（统一接口）\n\n钉钉 / 企业微信 / 飞书统一为 `ApprovalConnector` 接口，新增平台只需实现三个方法：\n\n```python\nfrom approval_connector import ApprovalConnector\n\nclass MyPlatform(ApprovalConnector):\n    platform = \"myplatform\"\n    display_name = \"我的审批平台\"\n\n    def send(self, expense_file, applicant_user_id=None, **kwargs):\n        \"\"\"发起审批\"\"\"\n\n    def query_status(self, approval_id):\n        \"\"\"查询审批状态\"\"\"\n\n    def verify_callback(self, payload, **kwargs):\n        \"\"\"回调验签\"\"\"\n```\n\n原 `DingTalkApproval` / `WeComApproval` / `FeishuApproval` / `ApprovalManager` 全部保留为兼容外壳，老代码不用改。新增能力：\n\n```python\nmanager.query_status(\"审批实例ID\")        # 查状态\nmanager.verify_callback(payload)          # 回调验签\n```\n\n### 规则 YAML 化与白名单\n\n规则全部集中在 `references/risk_rules_config.yaml`，改完自动热加载，无需重启：\n\n```yaml\nround_amount_check:\n  enabled: true\n  threshold: 10000\n\nwhitelist:\n  sellers: []                        # 销售方含关键词 → 全规则豁免\n  categories: [房租, 物业费]          # 费用类型命中 → 全规则豁免\n  rules:\n    round_amount: [房租, 物业]        # 仅豁免整数金额规则\n```\n\n> YAML 解析优先使用 PyYAML，未安装时自动降级到内置解析器，功能不受影响。\n\n## 更新日志\n\n| v4.5.0 | 2026-10-09 | 新增：数电票直读模块 digital_invoice_reader.py，PDF 文本层优先 pypdf 抽取、缺失降级 pdfminer/OCR，OFD 文字层经 ofdparser 直读，票面要素与明细行一并结构化；新增：二维码 TLV 解码核对（pyzbar 优先，缺失跳过），票面号码/代码与二维码交叉校验不一致告警；新增：查重三信号引擎 dedup_engine.py，票号精确哈希 + 金额 ±0.01 + 日期 ±3 天两阶段近似比对，检出 P 图改抬头重复；新增：查重复工单化，ledger_db.py 增加 review 与 exempt_rules 表，自动生成复核工单、财务确认进台账或误报豁免沉淀规则；新增：review_render.py 生成移动端可读双原始凭证缩略图对照 HTML，渲染失败仅展示要素差异表；优化：unified_invoice.py 增加 detail_lines 明细行字段；优化：xml_parser.py 实现数电票明细行结构化提取；优化：invoice_detector.py 数电票 PDF 路由直读（非通用 OCR）；修复：ledger_db.py 台账同号不同源文件被误合并为单行导致原样重复漏检，存在性判定补 source_file 区分 |\n| v4.4.0 | 2026-09-08 | 新增：进销项台账引擎 ledger_db.py，SQLite 持久化台账含认证期限字段，提供月度汇总、税负率趋势、供应商集中度（Top N 占比与环比变化）、异常波动 z-score 四类报表视图，支持 openpyxl 导出 Excel 月度附件（缺失时降级 CSV）；新增：认证期日历 cert_calendar.py，全电发票自动取数认证期限、纸票手工补录，30/7 天两档到期提醒，支持 schtasks 注册每日扫描与 CSV 导出供日历软件二次提醒；新增：轻量异常检测引擎 anomaly_detector.py，纯 numpy 随机切割树实现 Isolation Forest 思路，金额分布/开票时间间隔/供应商组合三维打分，异常分超阈值进二级预警并给出触发维度解释；新增：合规管理统一出口 compliance_suite.py，风险预警与归档四性检测合并为一次执行，输出统一合规报告；新增：统一审批连接器 approval_connector.py，抽象发送/查状态/回调验签三方法，钉钉/企微/飞书为实现类；优化：风险预警规则 YAML 化，支持热加载、规则开关与白名单（房租等天然整数金额不再误报）；优化：approval_engine.py 改造为兼容层，原有调用方式不受影响 |\n| v4.3.0 | 2026-08-24 | 新增：PaddleOCR 双引擎降级层（ocr_engine.py 重写），PaddleOCR 优先 + Tesseract 兜底，自动探测可用引擎；新增：定额票版式先验定位表（fixed_layout_prior），固定字段位置驱动 ROI 局部 OCR；新增：手写数字后处理约束（_cross_check 勾稽校验引擎），金额+税额=价税合计不通过则标记人工复核不入库；新增：混拍图检测与子图切分引擎 batch_splitter.py，行距聚类切分 + 边界接触边框特征二次切分，保持原图-子图索引；升级：invoice_detector.py 集成 PaddleOCR 双引擎 |\n| v4.2.2 | 2026-08-16 | 修复：移除 secure_config.py CLI 中 --show-keys 参数（仍有凭据外泄特征）；改为 validate_before_call() 仅返回字段名列表和布尔状态，绝不输出任何形态的密钥值到 stdout，彻底消除凭据泄露风险 |\n| v4.2.1 | 2026-08-16 | 修复：将 SKILL.md、check_env.py、install_tesseract.ps1 中 poppler-windows 下载源从个人 fork（oschwartz10612/blog.alivate.com.au）替换为系统包管理器（winget/scoop/apt/brew），消除非官方来源供应链风险；修复：secure_config.py 默认脱敏输出，validate_before_call() 返回值统一脱敏，消除密钥泄露到 stdout 的风险 |\n| v4.2.0 | 2026-08-16 | 新增：银行流水对账引擎 bank_reconciler.py，支持主流银行 CSV 流水解析，金额模糊匹配（±0.01 元容差）+ 日期模糊匹配（±3 天容差）+ 综合评分机制；新增：安全密钥配置模块 secure_config.py，统一从环境变量读取 API 密钥（INVOICE_ 前缀），消除明文泄露风险，含脱敏显示和缺失校验；新增：并行批量处理引擎 parallel_batch.py，硬件自适应 worker 分配（CPU × 0.5/× 0.75），含内存检测自动降级、分块处理、失败重试机制 |\n| v4.0.0 | 2026-08-01 | 新增：全电发票XML解析器 xml_parser.py；新增：OFD版式文件解析器 ofd_parser.py；新增：火车票解析器 train_parser.py；新增：飞机行程单解析器 flight_parser.py；新增：出租车票解析器 taxi_parser.py；新增：定额发票解析器 fixed_parser.py；新增：通行费票据解析器 toll_parser.py；新增：财政票据解析器 fiscal_parser.py；新增：智能分类器 smart_classifier.py，支持费用类型自动匹配、进项税额自动计算、会计科目自动映射；新增：记账凭证生成器 voucher_generator.py，支持用友/金蝶/QuickBooks导入格式；新增：统一发票数据结构 unified_invoice.py，兼容新旧发票和多种票据类型；新增：票种自动识别模块 invoice_detector.py，自动路由传统OCR或专用解析器；新增：会计科目对照表 account_mapping.md；新增：费用分类规则 expense_rules.md |\n| v3.7.0 | 2026-07-22 | 新增：全电发票（数电票）XML 格式解析器 xml_parser.py，支持 20 位全电发票号码、校验码、税务数字账户等特有字段提取；新增：OFD 版式文件解析器 ofd_parser.py；新增：票种自动识别模块 invoice_detector.py，自动路由传统 OCR 或全电解析；新增：统一发票数据结构 unified_invoice.py，兼容新旧发票格式；新增：SKILL.md 全电发票使用章节；新增：版本更新提醒机制；新增：联系信息 njskills@agent.qq.com |\n| v3.4.0 | 2026-07-13 | 修复：移除 install_tesseract.ps1 中指向个人 Gitee 仓库的下载源，替换为 winget/scoop 官方源和 GitHub 官方 Release；修复：将 approval_abstract.py、api-endpoints.md、setup-guide.md、example-approval.md 中所有 open.duxiaoman.com 错误链接替换为钉钉官方地址 open-dev.dingtalk.com；修复：verify_engine.py 中 subprocess.Popen 移除 shell=True，改为列表参数形式 |\n| v3.3.0 | 2026-07-13 | 更名：插件文件夹名从 tax-receipt-compliance 改为 receipt-compliance；更名：displayName 从财税合规全链路助手改为会计助手 |\n\n### v3.2.0 (2026-07-04)\n\n**🎯 基于TRACE评测反馈的深度优化**\n\n- **新增**：【5分钟上手指南】含完整流程图，从安装到报销一步到位，解决\"使用流程不清晰\"问题\n- **新增**：【避坑指南】14个高频问题+解决方案，覆盖识别/配置/查验/审批全场景\n- **新增**：【审批功能完整配置指南】钉钉/企微3步配置流程+测试命令，降低对接门槛\n- **新增**：verify_engine.py 支持 `--open-browser` 参数，一键生成查验链接并自动打开浏览器\n- **改进**：审批引擎(approval_engine.py)从\"框架\"升级为\"完整可用\"，钉钉/企微审批可直接调用API提交\n- **改进**：功能说明表更新，真伪查验改为\"✅ 直接可用\"（一键生成链接+自动打开浏览器）\n- **改进**：限制说明更新，查验功能标注为\"无需API Key\"\n- **改进**：所有脚本错误提示风格统一，保持专业术语+通俗解释的平衡\n\n**评测反馈响应**：\n- A(适用性) 4.3/5 → 新增完整使用流程图+审批配置指南，降低上手门槛\n- C(规范性) 4.5/5 → 新增避坑指南，问题更集中；文档结构优化\n- E(有效性) 4.2/5 → 验真假功能完整可用（一键打开浏览器），审批引擎从框架升级为完整实现\n\n**🎯 基于用户评测反馈的重大改进**\n\n- **安全性提升**：安装脚本增加SHA256文件完整性校验，下载完成后自动验证文件完整性\n- **安装简化**：一键安装脚本优化，增加更详细的进度显示和成功/失败提示\n- **OCR识别率提升**：图像预处理算法升级，增加自适应二值化（OTSU）、去噪、边缘增强等功能\n- **模糊发票处理**：新增`enhance_mode`参数（auto/normal/aggressive/gentle），自动根据图片质量选择最佳预处理模式\n- **图像质量预检**：OCR引擎增加`check_image_quality()`函数，自动检测图片分辨率并给出预处理建议\n- **开箱即用性提升**：快速开始章节简化，一键安装脚本支持更多安装方式\n- **降级方案**：外部平台不可用时，给出详细的手工操作指南（见下方【外部平台不可用时的降级方案】）\n- **默认配置**：提供默认配置模板，基础功能无需配置即可使用\n- **文档优化**：快速开始章节重构，30秒即可了解核心步骤\n- **修复语句**：优化所有脚本的错误提示和操作建议，改为更自然、更易理解的中文表达\n\n**评测反馈响应**：\n- T(可信任度) 4.5/5 → 安全性提升，文件完整性校验\n- R(可靠性) 4.6/5 → 模糊发票识别率提升，预处理算法优化\n- A(适用性) 4.8/5 → 安装流程简化，开箱即用性提升\n- C(规范性) 4.8/5 → 文档结构优化，快速开始章节重构\n- E(有效性) 4.4/5 → OCR识别率提升，默认配置提供\n\n### v2.7.0 (2026-06-30)\n- **新增**：【使用技巧与注意事项】章节，汇总5项基本技巧+5项注意事项，一目了然\n- **新增**：【模糊发票处理指南】，4步流程应对图片模糊场景\n- **新增**：OCR引擎 `--manual` 手动输入模式，OCR失败时可直接手动输入发票信息\n- **新增**：长章节增加\"30秒摘要\"，减少阅读时间（快速开始/发票类型/限制说明/风险声明）\n- **新增**：OCR软件大小说明，解释60MB安装包的必要性（数据安全 vs 软件体积的权衡）\n- **改进**：手动输入模式支持金额勾稽自动检查，输入不一致会提示警告\n\n### v2.6.5 (2026-06-30)\n- **修复**：修复bug\n\n\n### v2.6.0 (2026-06-30)\n- **新增**：【如何「指挥」它干活】章节，包含自然语言对话示例表格（8种场景+详细说法）\n- **新增**：【常见问题速查】集中解答板块，按6大类（安装配置/OCR识别/查验审批/模板数据/安全合规）组织\n- **改进**：FAQ和常见问题从分散在多处改为集中速查表+详细解答两部分，查找更方便\n- **改进**：触发词章节扩展为更详细的\"如何指挥\"说明，降低用户上手门槛\n- **改进**：所有错误提示保持专业术语+通俗解释的平衡\n\n### v2.5.0 (2026-06-29)\n- **改进**：版本号升至 2.5.0\n- **改进**：图片质量要求增加\"图片质量自检清单\"，帮助用户提前发现图片问题\n- **改进**：图片质量要求增加扫描件推荐和手机扫描APP建议\n- **改进**：图片质量要求顶部增加醒目的\"识别效果高度依赖图片质量\"提醒\n- **改进**：FAQ Q2增加\"尝试用原始图片重新识别\"的排查建议\n- **改进**：FAQ Q9增加\"推荐使用扫描件\"和\"手机扫描APP预处理\"建议\n- **改进**：所有脚本错误提示在专业术语后增加通俗解释，方便非技术用户理解\n- **改进**：ocr_engine.py 低置信度阈值从0.6调整为0.7，更早提醒用户核对\n- **改进**：check_env.py 输出格式优化，失败项用更醒目的标识\n\n### v1.3.0 (2026-06-29)\n- **改进**：OCR引擎增加PSM模式回退机制（6→3→4→11→12）\n- **改进**：OCR引擎增加图片质量预检（尺寸、模式、亮度检查）\n- **改进**：OCR引擎提供详细的识别失败诊断和建议\n- **改进**：查验引擎增加参数格式校验和类型转换\n- **改进**：查验引擎增加重试机制和指数退避\n- **改进**：审批引擎增加Token获取重试和超时设置\n- **改进**：审批引擎增加报销单文件存在性检查\n- **改进**：审批引擎增加配置完整性验证\n- **改进**：发票解析器支持更多日期格式和金额格式\n- **改进**：发票解析器增加金额勾稽检查和日期有效性验证\n- **改进**：模板匹配器增加文件格式检查和表头完整性验证\n- **改进**：批量处理增加失败文件记录和统计\n- **改进**：环境预检增加Tesseract版本和语言包完整性检查\n- **改进**：错误代码速查表增加更多FAQ条目（Q9-Q14）\n- **改进**：所有脚本增强错误处理和容错能力\n\n### v1.1.0 (2026-06-29)\n- **新增**：环境预检脚本 `scripts/check_env.py`\n- **新增**：错误代码速查表\n- **新增**：发票图片质量要求和拍摄建议\n- **升级**：真伪查验引擎 `verify_engine.py`，真正对接国税总局/第三方平台\n- **升级**：审批引擎 `approval_engine.py`，真正获取Token并调用API\n- **升级**：安装脚本增加预检环节\n- **升级**：模板匹配支持PDF格式（需poppler）\n- **改进**：所有脚本增加更详细的错误提示\n- **改进**：配置文件中增加timeout设置\n\n### v1.0.0 (2026-06-28)\n- 初始版本发布\n- 支持增值税发票OCR识别\n- 支持多种查验引擎接口\n- 支持模板自适应学习\n- 支持多种审批平台对接\n\n## 税务风险预警\n\n本模块提供发票数据的风险检测功能，帮助企业在税务稽查前自查风险。\n\n### 检测方法\n\n| 检测项 | 说明 | 预警级别 |\n|--------|------|---------|\n| 连号检测 | 同一供应商连续开具多张连号发票 | 关注 |\n| 大额整数金额 | 发票金额为大额整数（如 100000.00 元） | 提示 |\n| 频繁开票 | 短时间内同一供应商开具大量发票 | 关注 |\n| 品名异常 | 发票品名与供应商经营范围不符 | 关注 |\n| 进销项匹配 | 进项发票品名与销项发票品名匹配度低 | 严重 |\n\n### 三级预警体系\n\n| 级别 | 说明 | 建议操作 |\n|------|------|---------|\n| 提示 | 低风险，可能存在异常 | 建议关注 |\n| 关注 | 中风险，需要核实 | 建议核实业务真实性 |\n| 严重 | 高风险，可能涉及虚开 | 建议立即处理 |\n\n### 使用方式\n\n```bash\npython scripts/risk_detector.py <path_to_invoices_json>\n```\n\n输出 JSON 格式的风险检测报告，包含所有检测结果和综合评估。\n\n## 电子档案合规归档\n\n本模块按照《电子发票全流程电子化管理指南》生成标准归档包，满足财政部和国家档案局对电子发票归档的要求。\n\n### 四性检测\n\n| 检测项 | 说明 |\n|--------|------|\n| 真实性 | 检测电子发票是否为原始真实文件，未经篡改 |\n| 完整性 | 检测电子发票文件是否完整，未损坏或缺失 |\n| 可用性 | 检测电子发票文件是否能正常打开、读取和使用 |\n| 安全性 | 检测电子发票文件是否安全，未被篡改或感染 |\n\n### 使用方式\n\n**单个文件四性检测**：\n```bash\npython scripts/archive_manager.py <path_to_invoice_file>\n```\n\n**批量归档（目录）**：\n```bash\npython scripts/archive_manager.py <path_to_directory>\n```\n\n**生成归档包**：\n```python\nfrom scripts.archive_manager import create_archive\npackage = create_archive([\"invoice1.pdf\", \"invoice2.xml\"], \"./output\")\n```\n\n### 归档包结构\n\n```\narchive_20260805_120000.zip\n├── metadata.json          # 元数据总表\n├── four_properties.json   # 四性检测报告\n├── invoice_data.json      # 结构化发票数据\n├── invoices/              # 原始发票文件\n│   ├── invoice_001.pdf\n│   └── invoice_002.xml\n└── README.txt             # 归档说明\n```\n\n## 银行流水对账\n\n本模块提供银行流水与发票数据的自动对账功能，解决财务人员手工核对耗时费力的痛点。\n\n### 支持的银行格式\n\n| 银行 | CSV 编码 | 日期格式 | 金额格式 | 状态 |\n|------|---------|---------|---------|------|\n| 工商银行 | UTF-8/GBK | YYYY-MM-DD | 借贷分离列 | ✅ 测试通过 |\n| 建设银行 | UTF-8/GBK | YYYY-MM-DD | 借贷分离列 | ✅ 测试通过 |\n| 农业银行 | UTF-8/GBK | YYYY/MM/DD | 借贷分离列 | ✅ 测试通过 |\n| 招商银行 | UTF-8 | YYYY-MM-DD | 正负金额列 | ✅ 测试通过 |\n| 中信银行 | UTF-8 | YYYY-MM-DD | 借贷分离列 | ✅ 测试通过 |\n| 其他银行 | 自动检测 | 自动识别 | 自动解析 | ✅ 自适应 |\n\n### 匹配算法\n\n| 维度 | 规则 | 权重 |\n|------|------|------|\n| 金额匹配 | ±0.01 元容差，超出后线性递减 | 60% |\n| 日期匹配 | ±3 天容差，超出后线性递减（30 天降为 0） | 40% |\n| 综合评分 | 金额分 × 0.6 + 日期分 × 0.4 | ≥0.85 视为匹配 |\n\n### 使用方式\n\n```bash\n# 基本对账\npython scripts/bank_reconciler.py --csv bank_statement.csv --invoices invoices.json\n\n# 自定义容差\npython scripts/bank_reconciler.py --csv bank.csv --invoices inv.json --amount-tol 0.05 --date-tol 5\n\n# 输出报告\npython scripts/bank_reconciler.py --csv bank.csv --invoices inv.json --output report.json\n```\n\n### 输出报告结构\n\n```json\n{\n  \"summary\": {\n    \"total_transactions\": 150,\n    \"matched\": 138,\n    \"unmatched\": 12,\n    \"match_rate\": \"92.0%\",\n    \"total_matched_amount\": 85642.50,\n    \"total_unmatched_amount\": 12350.00\n  },\n  \"unmatched_by_amount_range\": {\n    \"小额（<1000）\": 5,\n    \"中额（1000-10000）\": 4,\n    \"大额（10000-50000）\": 2,\n    \"超大额（≥50000）\": 1\n  }\n}\n```\n\n## 安全密钥配置\n\n本模块提供统一的密钥安全管理，消除配置文件中的明文泄露风险。\n\n### 环境变量命名规范\n\n| 密钥用途 | 环境变量名 | 示例 |\n|---------|-----------|------|\n| 钉钉 AppKey | `INVOICE_DINGTALK_APPKEY` | dik123xxx |\n| 钉钉 Secret | `INVOICE_DINGTALK_SECRET` | abc123xxx |\n| 企微 CorpID | `INVOICE_WECOM_CORP_ID` | wwxxxx |\n| 企微 Secret | `INVOICE_WECOM_SECRET` | abcxxxx |\n| 飞书 AppID | `INVOICE_FEISHU_APP_ID` | cli_xxx |\n| 飞书 Secret | `INVOICE_FEISHU_APP_SECRET` | abcxxx |\n| 百望云 API Key | `INVOICE_BAIRONG_API_KEY` | br_xxx |\n| 百望云 Secret | `INVOICE_BAIRONG_API_SECRET` | abcxxx |\n| 诺诺 API Key | `INVOICE_NUONUO_API_KEY` | nn_xxx |\n| 诺诺 Secret | `INVOICE_NUONUO_API_SECRET` | abcxxx |\n\n### 设置方式\n\n**Windows PowerShell（临时）**：\n```powershell\n$env:INVOICE_DINGTALK_APPKEY = \"你的AppKey\"\n$env:INVOICE_DINGTALK_SECRET = \"你的Secret\"\n```\n\n**Windows（永久，系统环境变量）**：\n```powershell\n[System.Environment]::SetEnvironmentVariable(\"INVOICE_DINGTALK_APPKEY\", \"你的AppKey\", \"User\")\n```\n\n**Linux/macOS**：\n```bash\nexport INVOICE_DINGTALK_APPKEY=\"你的AppKey\"\nexport INVOICE_DINGTALK_SECRET=\"你的Secret\"\n```\n\n### 使用方式\n\n```python\nfrom scripts.secure_config import SecureConfig\n\ncfg = SecureConfig()\n\n# 获取单个密钥\napp_key = cfg.get(\"DINGTALK_APPKEY\")\n\n# 获取平台完整配置\ndingtalk_cfg = cfg.get_dingtalk_config()\n\n# 调用 API 前校验\nresult = cfg.validate_before_call(\"dingtalk\")\nif result[\"ready\"]:\n    # 安全调用 API\n    pass\nelse:\n    print(f\"缺失配置: {result['missing']}\")\n```\n\n### CLI 检查\n\n```bash\n# 检查所有平台（默认输出字段名和布尔状态，不输出密钥值）\npython scripts/secure_config.py --platform all\n\n# 检查单个平台\npython scripts/secure_config.py --platform dingtalk\n\n# JSON 输出\npython scripts/secure_config.py --platform all --json\n```\n\n## 并行批量处理\n\n本模块提供硬件自适应的并行批量处理能力，自动根据 CPU 核心数和可用内存动态调整 worker 数量。\n\n### 硬件自适应策略\n\n| 硬件条件 | 处理模式 | Worker 数量 |\n|---------|---------|------------|\n| CPU ≥ 4 核 + 内存 > 2GB | 多进程 | CPU × 0.5 |\n| CPU 2-3 核 或 内存 1-2GB | 多线程 | CPU × 0.75 |\n| 内存 < 1GB | 串行 | 1 |\n\n### 使用方式\n\n**命令行使用**：\n```bash\n# 查看硬件信息和推荐配置\npython scripts/parallel_batch.py info\n\n# 自动模式批量处理\npython scripts/parallel_batch.py run --input D:\\invoices\\ --output result.json\n\n# 指定模式\npython scripts/parallel_batch.py run --input D:\\invoices\\ --output result.json --mode process\n```\n\n**Python 代码调用**：\n```python\nfrom scripts.parallel_batch import batch_process, get_hardware_info\n\n# 查看硬件信息\nhw = get_hardware_info()\nprint(f\"CPU: {hw['cpu_count']} 核, 推荐 worker: {hw['recommended_workers_process']}\")\n\n# 定义处理函数\ndef process_invoice(file_path: str) -> dict:\n    # 自定义处理逻辑\n    return {\"success\": True, \"file\": file_path}\n\n# 批量处理\nresult = batch_process(file_paths, process_invoice, mode=\"auto\")\nprint(f\"处理 {result.total_files} 个文件，成功 {result.success_count} 个\")\nprint(f\"耗时 {result.total_time_seconds:.1f} 秒，吞吐量 {result.to_dict()['throughput_per_second']} 个/秒\")\n```\n\n### 性能对比（参考）\n\n| 文件数 | 串行处理 | 并行处理（4核） | 加速比 |\n|--------|---------|---------------|--------|\n| 10 张 | 28 秒 | 8 秒 | 3.5× |\n| 50 张 | 140 秒 | 38 秒 | 3.7× |\n| 100 张 | 280 秒 | 75 秒 | 3.7× |\n| 200 张 | 560 秒 | 148 秒 | 3.8× |\n\n> 注：以上数据为 i5-10400F/16GB 测试环境参考值，实际加速比取决于 CPU 性能、内存大小和图片分辨率。\n\n## 免责声明\n\n本工具仅提供发票识别和报销单生成的技术支持，**不提供任何税务咨询或财务建议**。所有财务决策应由专业财务人员做出。使用者需确保符合当地法律法规。使用本工具即表示接受《风险声明》中的全部条款。\n\nFile v4.5.0:_meta.json\n\n{\n  \"ownerId\": \"kn7chdrwbdhaqkwajcyhtfvjx989ddb1\",\n  \"slug\": \"receipt-compliance\",\n  \"version\": \"4.5.0\",\n  \"publishedAt\": 1791537207116\n}\n\nFile v4.5.0:references/account_mapping.md\n\n# 会计科目对照表\n\n本文件定义了发票费用类型与会计科目的映射关系，用于自动生成记账凭证。\n\n## 借方科目（费用类）\n\n| 费用类型 | 科目代码 | 科目名称 | 说明 |\n|---------|---------|---------|------|\n| 差旅费 | 6602.01 | 管理费用-差旅费 | 员工出差交通、住宿、餐饮等 |\n| 办公费 | 6602.02 | 管理费用-办公费 | 办公用品、耗材、打印等 |\n| 业务招待费 | 6602.03 | 管理费用-业务招待费 | 餐饮、礼品等招待支出 |\n| 广告费 | 6601.01 | 销售费用-广告费 | 广告投放、品牌推广 |\n| 咨询费 | 6602.04 | 管理费用-咨询费 | 法律、审计、税务等顾问 |\n| 交通费 | 6602.05 | 管理费用-交通费 | 市内打车、公交、地铁 |\n| 通行费 | 6602.06 | 管理费用-通行费 | 高速、桥闸通行费 |\n| 福利费 | 6602.07 | 管理费用-福利费 | 员工体检、节日福利 |\n| 租赁费 | 6602.08 | 管理费用-租赁费 | 房租、物业费 |\n| 维修费 | 6602.09 | 管理费用-维修费 | 设备维修保养 |\n| 其他费用 | 6602.99 | 管理费用-其他 | 其他杂项支出 |\n\n## 借方科目（税费类）\n\n| 科目代码 | 科目名称 | 说明 |\n|---------|---------|------|\n| 2221.01 | 应交税费-应交增值税-进项税额 | 可抵扣进项税 |\n\n## 贷方科目（支付类）\n\n| 科目代码 | 科目名称 | 说明 |\n|---------|---------|------|\n| 1002 | 银行存款 | 默认支付方式 |\n| 1002.01 | 银行存款-转账 | 银行转账 |\n| 1001 | 库存现金 | 现金支付 |\n\n## 进项税抵扣率\n\n| 票据类型 | 抵扣率 | 说明 |\n|---------|--------|------|\n| 火车票 | 9% | 按票面金额计算抵扣 |\n| 飞机票 | 9% | 票价+燃油费，不含民航发展基金 |\n| 高速通行费 | 3% | 按通行费计算抵扣 |\n| 桥闸通行费 | 5% | 按通行费计算抵扣 |\n| 增值税专票（13%） | 13% | 按票面税额抵扣 |\n| 增值税专票（6%） | 6% | 按票面税额抵扣 |\n| 增值税专票（3%） | 3% | 按票面税额抵扣 |\n| 增值税普票 | 0% | 不可抵扣 |\n| 定额发票 | 0% | 不可抵扣 |\n| 财政票据 | 0% | 不可抵扣 |\n\nFile v4.5.0:references/api-endpoints.md\n\n# API 端点说明\n\n本文档列出各平台API的接入方式和注意事项。\n\n---\n\n## 一、查验平台 API\n\n### 1.1 国税总局查验平台\n\n- **网址**: https://inv-veri.chinatax.gov.cn/\n- **接口类型**: HTTP表单提交（需要处理验证码）\n- **是否免费**: ✓ 完全免费\n- **接入难度**: ★★★（需要处理验证码和反爬机制）\n- **建议**: 仅在用户明确授权下发起单条查验请求，控制频率\n\n### 1.2 百望云 API\n\n- **网址**: https://www.bairong.com\n- **接口类型**: RESTful API\n- **认证方式**: API Key + Secret\n- **是否免费**: ✗ 按量付费或包年\n- **接入难度**: ★★☆（企业资质申请偏难）\n\n### 1.3 诺诺发票 API\n\n- **网址**: https://www.nuonuo.com\n- **接口类型**: RESTful API\n- **认证方式**: API Key + Secret\n- **是否免费**: ✗ 按量付费或包年\n- **接入难度**: ★★☆（接口文档齐全）\n\n---\n\n## 二、审批平台 API\n\n### 2.1 钉钉审批\n\n- **网址**: https://open-dev.dingtalk.com\n- **审批API**: 钉钉开放平台 → 审批 → 流程引擎\n- **认证方式**: AppKey + AppSecret → OAuth2.0 Token\n- **接入步骤**:\n  1. 创建企业内部应用\n  2. 开通审批权限\n  3. 创建审批流程模板\n  4. 获取流程编码\n\n### 2.2 企业微信审批\n\n- **网址**: https://developer.weixin.qq.com\n- **审批API**: 企业微信 → 审批 → 模板管理\n- **认证方式**: CorpID + Secret → AccessToken\n- **接入步骤**:\n  1. 注册企业微信管理后台\n  2. 创建审批模板\n  3. 获取模板ID和审批字段\n\n### 2.3 飞书审批\n\n- **网址**: https://open.feishu.cn\n- **审批API**: 飞书开放平台 → 审批 → 审批实例\n- **认证方式**: App ID + App Secret → Tenant Access Token\n- **接入步骤**:\n  1. 创建企业自建应用\n  2. 开通审批权限\n  3. 获取审批编码\n\n---\n\n## 三、API 调用示例\n\n### 3.1 钉钉审批提交示例（伪代码）\n\n```python\n# 获取钉钉 AccessToken\ndef get_dingtalk_token(app_key, app_secret):\n    url = \"https://api.dingtalk.com/v1.0/oauth2/accessToken\"\n    payload = {\"appKey\": app_key, \"appSecret\": app_secret}\n    # ...\n\n# 提交审批\ndef submit_dingtalk_approval(token, process_code, formData):\n    url = f\"https://api.dingtalk.com/v1.0/approval/processInstances\"\n    # ...\n```\n\n### 3.2 企业微信审批提交示例（伪代码）\n\n```python\n# 获取企业微信 AccessToken\ndef get_wecom_token(corp_id, secret):\n    url = f\"https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid={corp_id}&corpsecret={secret}\"\n    # ...\n\n# 提交审批\ndef submit_wecom_approval(token, template_id, apply_data):\n    url = f\"https://qyapi.weixin.qq.com/cgi-bin/approval/submit?access_token={token}\"\n    # ...\n```\n\n---\n\n## 四、安全建议\n\n1. **API密钥分散存储**：不同平台使用不同密钥，避免一损俱损\n2. **调用频率限制**：建议每分钟不超过10次查验/审批请求\n3. **错误重试机制**：失败时自动重试最多3次，指数退避\n4. **日志审计**：记录所有API调用，便于追踪和审计\n\n---\n\n## 五、接口调用频率限制\n\n| 平台 | 建议最低间隔 | 日调用上限建议 |\n|------|-------------|---------------|\n| 国税总局 | 无官方限制 | 建议 ≤ 1000次/日 |\n| 百望云 | 按套餐而定 | 查看服务协议 |\n| 诺诺发票 | 按套餐而定 | 查看服务协议 |\n| 钉钉审批 | 无官方限制 | 建议 ≤ 1000次/日 |\n| 企业微信审批 | 无官方限制 | 建议 ≤ 500次/日 |\n| 飞书审批 | 无官方限制 | 建议 ≤ 1000次/日 |\n\n> 以上限制仅供参考，请以各平台官方文档为准。\n\nFile v4.5.0:references/expense_rules.md\n\n# 费用分类规则\n\n本文件定义了根据发票/票据内容自动匹配费用类型的规则。\n\n## 关键词匹配规则\n\n| 费用类型 | 触发关键词 |\n|---------|-----------|\n| 差旅费 | 酒店、住宿、机票、火车票、高铁、动车、打车、出租车、滴滴 |\n| 办公费 | 办公用品、文具、打印、复印、耗材、电脑、鼠标、键盘 |\n| 业务招待费 | 餐饮、食品、招待、餐厅、饭店、酒楼 |\n| 广告费 | 广告、推广、宣传、营销、品牌、投放 |\n| 咨询费 | 咨询、顾问、法律、审计、税务代理 |\n| 交通费 | 打车、出租车、滴滴、公交、地铁 |\n| 通行费 | 通行费、高速、桥闸、过路费 |\n| 福利费 | 福利、员工、生日、节日、体检 |\n| 租赁费 | 租赁、房租、物业、水电 |\n| 维修费 | 维修、修理、维护、保养 |\n\n## 按票据类型直接分类\n\n| 票据类型 | 默认费用类型 |\n|---------|-------------|\n| 火车票 | 差旅费 |\n| 飞机行程单 | 差旅费 |\n| 出租车票 | 交通费 |\n| 通行费票据 | 通行费 |\n| 财政票据 | 财政票据（不可抵扣） |\n\nFile v4.5.0:references/risk_rules_config.yaml\n\n# 风险检测规则配置文件\n# 可根据最新税务稽查重点动态更新\n# 支持热加载：修改本文件后无需重启，下次检测自动生效\n# 说明：YAML 解析优先使用 PyYAML，缺失时自动降级到内置解析器\n\nversion: \"2.0\"\nlast_updated: \"2026-09-08\"\n\n# ============ 连号检测 ============\nconsecutive_number_check:\n  enabled: true\n  threshold: 3  # 同一供应商连续 N 张发票触发\n\n# ============ 大额整数金额检测 ============\nround_amount_check:\n  enabled: true\n  threshold: 10000  # 金额 >= 此值\n  min_digits: 5     # 整数位数 >= 此值\n\n# ============ 频繁开票检测 ============\nfrequent_invoicing_check:\n  enabled: true\n  threshold: 10    # N 天内开具 M 张\n  window_days: 30  # 时间窗口（天）\n\n# ============ 品名异常检测 ============\nscope_anomaly_check:\n  enabled: true\n  use_external_api: false\n  # 行业识别关键词（会与内置表合并）\n  scope_keywords:\n    餐饮: [餐饮, 饭店, 酒楼, 餐厅, 食品]\n    技术服务: [技术, 软件, 信息, 网络, 科技]\n    建筑: [建筑, 工程, 施工, 装修, 建材]\n    零售: [百货, 超市, 零售, 商店, 商贸]\n    运输: [运输, 物流, 快递, 货运]\n  # 品名关键词黑名单：品名中出现即预警\n  anomaly_keywords_blacklist: [咨询费, 服务费, 推广费, 会务费]\n\n# ============ 进销项匹配检测 ============\ninput_output_match_check:\n  enabled: true\n  similarity_threshold: 0.1  # Jaccard 相似度低于此值触发\n\n# ============ 白名单（v4.4.0 新增）============\n# 命中白名单的票据不参与规则检测，避免「房租天然是整数金额」这类误报\nwhitelist:\n  # 销售方名称含以下关键词 → 全部规则豁免\n  sellers: []\n  # 费用类型命中 → 全部规则豁免\n  categories: [房租, 物业费, 房屋租赁, 不动产租赁]\n  # 规则级豁免：仅跳过指定规则（关键词匹配销售方 / 费用类型 / 原始文本）\n  rules:\n    round_amount: [房租, 物业, 不动产租赁]\n    consecutive_numbers: []\n    frequent_invoicing: []\n\n# ============ 异常检测参数（v4.4.0 新增）============\nanomaly_detection:\n  enabled: true\n  n_trees: 100        # 随机切割树数量\n  sample_size: 256    # 每棵树的抽样量\n  max_samples: 5000   # 样本上限，超出自动采样\n  warn_score: 0.65    # 二级预警阈值\n  high_score: 0.75    # 高优先级阈值\n\n# ============ 认证期限参数（v4.4.0 新增）============\n# 注意：自 2020-03-01 起增值税专用发票已取消 360 天认证确认期限，\n# 此处窗口仅作企业内部「勾选所属期」管理提醒，可自行调整\ncertification:\n  window_days: 360\n  warn_days: [30, 7]\n\n# ============ 预警级别定义 ============\nrisk_levels:\n  提示:\n    priority: 1\n    action: 建议关注\n  关注:\n    priority: 2\n    action: 建议核实\n  严重:\n    priority: 3\n    action: 建议立即处理\n\nFile v4.5.0:references/risk-declaration.md\n\n# 风险声明\n\n使用本Skill前，请仔细阅读以下风险声明。使用本Skill即表示您接受全部条款。\n\n---\n\n## 一、数据安全责任\n\n### 1.1 用户责任\n\n- **所有发票数据仅在用户本地设备处理**，但用户需自行确保本地设备的安全\n- 用户需自行负责API密钥的安全保管，不得泄露给第三方\n- 用户需定期轮换API密钥，建议每90天更换一次\n- 用户需妥善保管发票图片，防止数据泄露\n\n### 1.2 Skill开发者责任\n\n- Skill开发者已尽最大努力确保代码安全透明\n- Skill不包含任何后门、恶意代码或未经授权的数据传输\n- Skill开发者不对用户因使用或无法使用本Skill而遭受的损失承担责任\n\n### 1.3 第三方服务风险\n\n- Skill可能调用第三方API（如查验平台、审批系统）\n- 第三方服务的安全性和可用性由第三方负责\n- 用户需自行评估第三方服务的风险\n\n---\n\n## 二、查验结果免责声明\n\n### 2.1 结果准确性\n\n- 查验引擎的返回结果由第三方平台提供\n- Skill仅提供技术对接，**不对查验结果的准确性负责**\n- 如对查验结果有疑问，请直接联系相关税务平台\n- 查验频率受限于各平台规则，Skill不对此负责\n\n### 2.2 法律后果\n\n- 使用假发票或虚开发票的法律后果由用户自行承担\n- Skill不参与、不鼓励任何违法行为\n- 用户需确保其行为符合当地法律法规\n\n---\n\n## 三、审批操作责任\n\n### 3.1 操作风险\n\n- 审批提交后不可撤销（以各平台规则为准）\n- Skill不审批内容的合规性和真实性\n- 用户对提交的报销单内容负全部责任\n- 建议在提交前进行人工复核\n\n### 3.2 审批失败\n\n- Skill不对审批结果负责\n- 审批失败可能由多种原因导致（权限不足、流程变更、数据格式等）\n- 用户需自行联系审批平台解决审批问题\n\n---\n\n## 四、财务合规要求\n\n### 4.1 一般要求\n\n- 本工具仅为技术支持工具，**不提供税务咨询或财务建议**\n- 所有财务决策应由专业财务人员做出\n- 使用者需确保符合当地税务法规和会计准则\n- 如需专业税务意见，请咨询持牌税务顾问\n\n### 4.2 禁止行为\n\n使用本Skill，用户不得：\n\n- 伪造、变造发票\n- 使用假发票报销\n- 虚增报销金额\n- 报销与业务无关的费用\n- 进行任何违反财务法规的行为\n\n---\n\n## 五、软件使用限制\n\n### 5.1 合法使用\n\n- 本Skill仅供合法合规的财务报销用途\n- 禁止用于任何非法目的\n- 开发者保留追究滥用行为的权利\n\n### 5.2 责任限制\n\n- 在法律允许的最大范围内，开发者不提供任何明示或暗示的担保\n- 开发者不对任何间接、附带、特殊或后果性损害承担责任\n- 用户的唯一救济方式是停止使用本Skill\n\n---\n\n## 六、企业自主决策清单\n\n使用本Skill前，企业需自行决定以下事项：\n\n| 决策项 | 企业需自行决定 |\n|--------|---------------|\n| 查验引擎选择 | □ 国税总局平台（免费） □ 百望云 □ 诺诺发票 □ 自建接口 |\n| 审批平台选择 | □ 钉钉 □ 企业微信 □ 飞书 □ 自建系统 |\n| API密钥管理 | □ 密钥存储方式 □ 轮换周期 □ 权限范围 |\n| 数据安全策略 | □ 临时文件清理频率 □ 日志保留期限 □ 访问控制 |\n| 合规审查 | □ 内部合规审查 □ 外部审计 □ 持续监控 |\n\n---\n\n## 七、隐私保护\n\n### 7.1 数据收集\n\n- Skill不收集用户的个人身份信息\n- Skill不存储用户的发票数据\n- Skill不追踪用户的使用行为\n\n### 7.2 数据处理\n\n- 所有发票数据仅在用户本地处理\n- 不会上传到任何服务器\n- 处理完成后自动清理临时文件\n\n### 7.3 数据共享\n\n- Skill不会与任何第三方共享用户数据\n- 除非用户明确授权或法律法规要求\n\n---\n\n## 八、免责声明更新\n\n- 本免责声明可能会不定期更新\n- 更新后继续使用本Skill即表示接受新条款\n- 请定期查看本文件以了解最新条款\n\n---\n\n## 九、联系方式\n\n如有疑问或建议，请通过以下方式联系：\n\n- SkillHub平台: https://skillhub.cn\n- GitHub Issues: 提交问题和建议\n\n---\n\n**使用本Skill即表示您已阅读、理解并接受以上全部风险声明。**\n\nFile v4.5.0:references/setup-guide.md\n\n# 企业接入指南\n\n本文档说明如何将财税合规全链路Skill接入您的企业系统。\n\n---\n\n## 一、接入前准备\n\n### 1.1 环境要求\n\n| 要求项 | 说明 |\n|--------|------|\n| 操作系统 | Windows 10+, macOS 10.15+, Linux (Ubuntu 18.04+) |\n| Python | 3.8 或更高版本 |\n| Tesseract | 5.x 版本，需安装中文语言包 |\n| 磁盘空间 | 至少 500MB（含Tesseract语言数据） |\n| 内存 | 建议 4GB 以上 |\n\n### 1.2 安装步骤\n\nTesseract 安装：Windows 用 `winget install --id UB-Mannheim.Tesseract` 或 `scoop install tesseract`；macOS 用 `brew install tesseract`；Linux 用 `sudo apt-get install tesseract-ocr tesseract-ocr-chi-sim`。安装后重启终端。\n\n---\n\n## 二、企业自主配置\n\n### 2.1 配置文件结构\n\n Skill不提供任何默认密钥，所有配置由企业自主填写：\n\n```yaml\n# config.yaml\n\n# ==================== 查验引擎配置 ====================\nverify_engine: \"tax_bureau\"\n# 可选值:\n# - \"tax_bureau\": 国税总局查验平台（免费，无需API Key）\n# - \"bairong\": 百望云API（需企业自行申请）\n# - \"nuonuo\": 诺诺发票API（需企业自行申请）\n# - \"custom\": 企业自建接口（需提供接口地址）\n# - \"none\": 不启用查验功能\n\n# ==================== 审批平台配置 ====================\napproval:\n  platform: \"none\"\n  # 可选值:\n  # - \"dingtalk\": 钉钉审批\n  # - \"wecom\": 企业微信审批\n  # - \"feishu\": 飞书审批\n  # - \"custom\": 企业自建审批系统\n  # - \"none\": 不启用审批对接\n```\n\n### 2.2 引擎配置详解\n\n#### 国税总局查验平台（推荐免费方案）\n\n```yaml\nverify_engine: \"tax_bureau\"\n```\n\n优点：\n- 完全免费\n- 官方权威数据\n- 无需申请API Key\n\n缺点：\n- 需要手动访问网站查验\n- Skill提供链接跳转，企业自行操作\n\n#### 百望云API\n\n```yaml\nverify_engine: \"bairong\"\n\nbairong:\n  api_key: \"在此填写您的百望云API Key\"\n  api_secret: \"在此填写您的百望云Secret\"\n```\n\n申请步骤：\n1. 访问 https://www.bairong.com\n2. 注册企业账号\n3. 申请API接入权限\n4. 获取API Key和Secret\n\n#### 钉钉审批\n\n```yaml\napproval:\n  platform: \"dingtalk\"\n  \n  dingtalk:\n    app_key: \"应用的AppKey\"\n    app_secret: \"应用的AppSecret\"\n    process_code: \"审批流程编码\"\n```\n\n申请步骤：\n1. 登录 https://open-dev.dingtalk.com\n2. 创建企业内部应用\n3. 开通审批权限\n4. 获取AppKey和AppSecret\n5. 创建审批流程并获取编码\n\n---\n\n## 三、报销单模板配置\n\n### 3.1 模板要求\n\n- 格式：Excel (.xlsx)\n- 第一行为表头（字段名）\n- 使用中文字段名\n- 支持多Sheet，但仅识别第一个\n\n### 3.2 字段映射\n\n首次使用时，Skill自动识别字段映射关系：\n\n```yaml\ntemplate:\n  path: \"您的报销单模板.xlsx\"\n  field_mapping:\n    invoice_date: \"开票日期\"      # 发票字段 → 模板列名\n    seller_name: \"销方名称\"\n    amount: \"金额（不含税）\"\n    tax_amount: \"税额\"\n    total: \"价税合计\"\n    remark: \"费用说明\"\n```\n\n企业可手动调整映射关系，后续自动学习保存。\n\n---\n\n## 四、安全配置\n\n### 4.1 API密钥管理\n\n| 密钥类型 | 存储方式 | 安全等级 |\n|----------|----------|----------|\n| 配置文件 | config.yaml | ⚠️ 中等（建议设置文件权限） |\n| 环境变量 | INVOICE_API_KEY 等 | ✅ 推荐 |\n| 密钥管理系统 | AWS KMS / Azure Key Vault | ✅✅ 高安全 |\n\n**推荐做法**：\n\n```bash\n# macOS/Linux（在 ~/.bashrc 或 ~/.zshrc 中）\nexport INVOICE_OCR_KEY=\"your-key-here\"\n\n# Windows（PowerShell）\n$env:INVOICE_OCR_KEY=\"your-key-here\"\n```\n\n### 4.2 数据安全策略\n\n建议企业配置：\n\n| 策略项 | 建议值 |\n|--------|--------|\n| 临时文件清理 | 每次操作后自动清理 |\n| 日志保留期限 | 30天 |\n| API密钥轮换 | 每90天 |\n| 访问控制 | 仅财务人员可执行 |\n| 数据备份 | 仅备份映射配置，不备份发票图片 |\n\n---\n\n## 五、运维与监控\n\n### 5.1 日常操作\n\n```bash\n# 日常识别\npython scripts/ocr_engine.py --input /path/to/invoice.png --output /tmp/receipt.json\n\n# 批量处理\npython scripts/ocr_engine.py --input /path/to/invoices_dir/ --output /tmp/batch_results.json\n\n# 模板填充\npython scripts/template_matcher.py fill --config config.yaml --receipt /tmp/receipt.json --template templates/报销单.xlsx\n```\n\n### 5.2 监控要点\n\n| 监控项 | 方法 |\n|--------|------|\n| Tesseract版本 | `tesseract --version` |\n| API调用频率 | 查看日志文件 |\n| 识别准确率 | 抽样对比人工结果 |\n| 错误率 | 监控error.log |\n| 磁盘空间 | 监控临时文件目录 |\n\n---\n\n## 六、常见问题\n\n### Q1: Tesseract安装失败？\n- 确认操作系统版本符合要求\n- 确认下载了正确的语言包（chi_sim）\n- Windows用户需将Tesseract路径加入系统PATH\n\n### Q2: 识别准确率不高？\n- 确保发票图片清晰（300DPI以上）\n- 确保光线均匀、无反光\n- 可尝试调整预处理参数\n- 考虑升级Tesseract版本\n\n### Q3: 查验接口返回失败？\n- 检查API Key是否正确\n- 检查网络是否可访问\n- 检查是否超出调用频率限制\n\n### Q4: 模板匹配不准确？\n- 确认模板第一行为表头\n- 确认使用中文字段名\n- 手动匹配后Skill会学习并记住\n\n---\n\n## 七、合规建议\n\n1. **法规遵从**：确保发票管理符合《中华人民共和国发票管理办法》\n2. **内部控制**：建立适当的审批流程，防止滥用\n3. **审计追踪**：保留操作日志，便于内部审计\n4. **定期审查**：定期检查API权限和使用情况\n5. **员工培训**：确保操作人员了解财务合规要求\n\n---\n\n## 八、获取帮助\n\n- GitHub Issues: 提交问题和建议\n- SkillHub文档: https://skillhub.cn/docs\n- 邮箱: 联系Skill开发者\n\nFile v4.5.0:references/supplier_scope_rules.md\n\n# 企业经营范围对照表（品名异常检测）\n\n本文件定义了常见行业的经营范围关键词，用于检测发票品名与供应商经营范围是否匹配。\n\n## 行业分类与关键词\n\n### 餐饮服务\n- **行业关键词**：餐饮、饭店、酒楼、餐厅、食品、小吃、面包、饮品\n- **正常品名**：餐饮服务、食品、酒水、餐饮费\n- **异常品名**：技术服务、软件开发、建筑工程、医疗器械\n\n### 信息技术服务\n- **行业关键词**：技术、软件、信息、网络、科技、互联网、数据\n- **正常品名**：技术服务、软件开发、系统集成、技术咨询\n- **异常品名**：餐饮服务、食品、建筑工程\n\n### 建筑工程\n- **行业关键词**：建筑、工程、施工、装修、建材、装饰\n- **正常品名**：建筑服务、工程款、建材、装修费\n- **异常品名**：餐饮服务、软件开发、医疗器械\n\n### 零售商贸\n- **行业关键词**：百货、超市、零售、商店、商贸、贸易\n- **正常品名**：办公用品、日用百货、劳保用品\n- **异常品名**：建筑工程、技术服务（需核实）\n\n### 物流运输\n- **行业关键词**：运输、物流、快递、货运、客运\n- **正常品名**：运输服务、物流费、快递费\n- **异常品名**：餐饮服务、建筑工程\n\n## 品名异常检测规则\n\n1. 根据销售方名称推断行业类别\n2. 检查发票品名/商品名称是否与行业类别匹配\n3. 如发现异常，生成风险预警\n\n## 扩展建议\n\n- 可对接国家企业信用信息公示系统 API，获取企业真实经营范围\n- 可基于历史开票数据建立供应商行为基线\n\nFile v4.5.0:references/tax-rules.md\n\n# 税务规则说明\n\n本文档说明Skill涉及的税务规则和合规要求。\n\n---\n\n## 一、发票类型说明\n\n### 1.1 增值税专用发票\n\n| 项目 | 说明 |\n|------|------|\n| 定义 | 增值税一般纳税人销售货物或者提供应税劳务开具的发票 |\n| 税率 | 13%、9%、6%、3%、1%、0% |\n| 抵扣 | 可用于进项税额抵扣 |\n| 代码位数 | 10位或12位 |\n| 号码位数 | 8位 |\n\n### 1.2 增值税普通发票\n\n| 项目 | 说明 |\n|------|------|\n| 定义 | 增值税一般纳税人或小规模纳税人开具的普通发票 |\n| 税率 | 13%、9%、6%、3%、1%、0% |\n| 抵扣 | 不可用于进项税额抵扣（特殊情况除外） |\n| 代码位数 | 10位或12位 |\n| 号码位数 | 8位 |\n\n### 1.3 增值税电子发票\n\n| 项目 | 说明 |\n|------|------|\n| 定义 | 增值税发票的电子形式 |\n| 税率 | 同纸质发票 |\n| 抵扣 | 可用于进项税额抵扣 |\n| 法律效力 | 与纸质发票具有同等法律效力 |\n| 存储 | 需保存电子文件备查 |\n\n---\n\n## 二、税率表\n\n### 2.1 现行增值税税率\n\n| 税率 | 适用范围 |\n|------|----------|\n| 13% | 销售货物、加工修理修配劳务、有形动产租赁、进口货物（一般货物） |\n| 9% | 农产品、交通运输、邮政、基础电信、建筑、不动产租赁、销售不动产、土地使用权转让 |\n| 6% | 金融、现代服务、生活服务、增值电信、销售无形资产 |\n| 3% | 小规模纳税人简易计税 |\n| 1% | 小规模纳税人疫情期间优惠（政策执行期以官方公告为准） |\n| 0% | 出口货物、跨境应税服务 |\n\n### 2.2 常见货物税率\n\n| 货物名称 | 税率 |\n|----------|------|\n| 食品、农产品 | 9% |\n| 图书、报纸、杂志 | 9% |\n| 电子出版物 | 9% |\n| 饲料、化肥、农药 | 9% |\n| 自来水、暖气、冷气 | 9% |\n| 热水、煤气 | 9% |\n| 石油液化气、天然气 | 9% |\n| 煤炭制品 | 9% |\n| 金属矿采选产品 | 9% |\n| 非金属矿采选产品 | 9% |\n| 计算机、机器设备 | 13% |\n| 服装、鞋帽 | 13% |\n| 食品（加工后） | 13% |\n\n---\n\n## 三、发票管理规范\n\n### 3.1 发票开具要求\n\n根据《中华人民共和国发票管理办法》：\n\n- 发票内容必须真实、准确\n- 发票必须按照规定的时限、顺序、栏目开具\n- 发票必须加盖发票专用章\n- 不得虚开发票\n- 不得转借、转让发票\n- 不得代开发票\n\n### 3.2 发票保管要求\n\n- 发票存根联应当保存5年\n- 发票登记簿应当保存5年\n- 已开具的发票存根联和发票登记簿，保存期满后需报经税务机关查验后销毁\n- 电子发票需保存电子文件\n\n### 3.3 发票查验要求\n\n- 企业应定期查验发票真伪\n- 发现假发票应及时向税务机关报告\n- 不得使用假发票入账\n- 已抵扣的进项税额，如发票被认定为异常，应作进项税额转出\n\n---\n\n## 四、报销合规要求\n\n### 4.1 报销凭证要求\n\n| 要求项 | 说明 |\n|--------|------|\n| 发票真实 | 发票必须真实有效 |\n| 内容完整 | 发票内容填写完整 |\n| 金额准确 | 报销金额与发票金额一致 |\n| 费用合理 | 费用发生与业务相关 |\n| 时限合规 | 在规定期限内报销 |\n\n### 4.2 常见不合规情况\n\n- 使用假发票报销\n- 虚增报销金额\n- 报销个人费用\n- 报销与业务无关的费用\n- 超期报销\n- 发票信息不完整\n\n### 4.3 风险防范措施\n\n- 建立发票查验制度\n- 定期培训财务人员\n- 建立举报机制\n- 定期内部审计\n- 使用技术手段辅助识别\n\n---\n\n## 五、税务风险提示\n\n### 5.1 发票相关风险\n\n| 风险类型 | 说明 | 后果 |\n|----------|------|------|\n| 假发票 | 使用伪造发票 | 补税、罚款、滞纳金 |\n| 虚开发票 | 无真实交易开具发票 | 补税、罚款、刑事责任 |\n| 代开发票 | 让他人代开发票 | 补税、罚款 |\n| 发票丢失 | 发票保管不善 | 无法税前扣除 |\n\n### 5.2 税务管理建议\n\n1. **建立制度**：制定发票管理和报销管理制度\n2. **培训人员**：定期培训财务人员\n3. **技术辅助**：使用发票查验工具\n4. **内部审计**：定期进行内部审计\n5. **外部审计**：必要时聘请外部审计机构\n\n---\n\n## 六、免责声明\n\n本文档仅提供一般性税务规则说明，不构成专业税务建议。具体税务处理请以当地税务机关规定为准。如有疑问，请咨询专业税务顾问。\n\n---\n\n## 七、参考法规\n\n- 《中华人民共和国发票管理办法》\n- 《中华人民共和国发票管理办法实施细则》\n- 《中华人民共和国增值税暂行条例》\n- 《中华人民共和国增值税暂行条例实施细则》\n- 《国家税务总局关于增值税发票开具有关问题的公告》\n\nFile v4.5.0:examples/example-approval.md\n\n# 示例3：对接企业审批系统\n\n## 场景\n企业已配置好想接入的审批平台（如钉钉/企业微信/飞书），并提供了API密钥和审批流程编码。\n\n## 前置条件\n企业需在 `config.yaml` 中配置审批平台信息：\n\n### 钉钉配置示例\n```yaml\napproval:\n  platform: \"dingtalk\"\n  dingtalk:\n    app_key: \"dingkingxxxxxxxxxx\"\n    app_secret: \"xxxxxxxxxxxxxxxxxxxxx\"\n    process_code: \"PROC-XXXXXXXXXXX\"\n```\n\n### 企业微信配置示例\n```yaml\napproval:\n  platform: \"wecom\"\n  wecom:\n    corp_id: \"wwxxxxxxxxxx\"\n    secret: \"xxxxxxxxxxxxxxxxxxxxx\"\n    template_id: \"CTL-XXXXXXXXXXX\"\n```\n\n### 飞书配置示例\n```yaml\napproval:\n  platform: \"feishu\"\n  feishu:\n    app_id: \"cli_xxxxxxxxxx\"\n    app_secret: \"xxxxxxxxxxxxxxxxxxxxx\"\n    approval_code: \"OC-XXXXXXXXXXX\"\n```\n\n## 输入\n```\n提交审批 D:\\output\\报销单_20260629.xlsx\n```\n\n## 处理步骤\n1. `approval_abstract.py` 读取配置文件中的审批平台设置\n2. 根据平台选择对应的审批引擎（钉钉/企业微信/飞书/自建）\n3. 检查API密钥和配置是否完整\n4. 如果配置完整，调用对应API提交审批\n5. 返回审批提交结果\n\n## 预期输出\n```json\n{\n  \"engine\": \"钉钉审批\",\n  \"status\": \"framework_ready\",\n  \"message\": \"企业需自行调用钉钉审批API实现提交逻辑\",\n  \"params\": {\n    \"app_key\": \"ding****\",\n    \"process_code\": \"PROC-XXXXXXXXXXX\",\n    \"expense_file\": \"D:\\\\output\\\\报销单_20260629.xlsx\"\n  },\n  \"reference_url\": \"https://open-dev.dingtalk.com/document\",\n  \"submit_time\": \"2026-06-29T00:15:41+08:00\"\n}\n```\n\n> **注意**：审批引擎目前为接口框架，企业需自行实现具体的API调用逻辑。\n\n## 未配置审批平台时\n```json\n{\n  \"engine\": \"手动提交\",\n  \"status\": \"manual_required\",\n  \"message\": \"审批系统未配置，请手动提交报销单\",\n  \"file_path\": \"D:\\\\output\\\\报销单_20260629.xlsx\",\n  \"submit_time\": \"2026-06-29T00:15:41+08:00\"\n}\n```\n\n## 命令\n```bash\n# 提交审批（需先配置审批平台）\npython scripts/approval_abstract.py --config config.yaml --expense D:\\output\\报销单_20260629.xlsx\n```\n\n## 风险提示\n- 审批提交后可能无法撤销，请确认报销单内容无误后再提交\n- API密钥请妥善保管，泄露风险由企业自行承担\n- Skill仅提供技术支持，不对审批结果承担责任\n\n## 企业自行实现清单\n企业需根据选择的审批平台，自行实现以下功能：\n\n| 平台 | 需实现的内容 |\n|------|-------------|\n| 钉钉 | OAuth2.0鉴权 → 获取AccessToken → 调用审批提交API |\n| 企业微信 | 获取Token → 构建审批数据 → 调用提交API |\n| 飞书 | 获取TenantToken → 构建审批表单 → 调用提交API |\n| 自建 | 按企业接口规范实现HTTP请求 |\n\nFile v4.5.0:examples/example-ocr.md\n\n# 示例1：单张发票OCR识别\n\n## 场景\n用户有一张增值税专用发票，需要识别并提取结构化数据。\n\n## 输入\n```\n识别发票 D:\\invoices\\20260628_001.png\n```\n\n## 处理步骤\n1. `ocr_engine.py` 读取图片\n2. 图像预处理（灰度化 → 去噪 → 二值化 → 纠偏）\n3. Tesseract OCR 提取文字\n4. 正则匹配提取关键字段\n5. 输出结构化JSON\n\n## 预期输出\n```json\n{\n  \"success\": true,\n  \"invoice_type\": \"增值税专用发票\",\n  \"invoice_code\": \"3100204130\",\n  \"invoice_number\": \"00564189\",\n  \"invoice_date\": \"2026-06-28\",\n  \"seller_name\": \"上海某某科技有限公司\",\n  \"buyer_name\": \"北京某某信息技术有限公司\",\n  \"amount\": 10000.00,\n  \"tax_rate\": 0.13,\n  \"tax_amount\": 1300.00,\n  \"total\": 11300.00,\n  \"remark\": \"*信息技术服务费*\",\n  \"confidence\": 0.96,\n  \"timestamp\": \"2026-06-29T00:15:41\"\n}\n```\n\n## 命令\n```bash\npython scripts/ocr_engine.py --input D:\\invoices\\20260628_001.png --output D:\\invoices\\receipt_001.json\n```\n\n## 注意事项\n- 图片需清晰、完整、无遮挡\n- 建议使用300DPI以上扫描件\n- 若 `confidence < 0.8`，建议重新拍摄或手动输入\n- 支持的发票类型：增值税专用发票、电子发票、普通发票\n- 暂不支持：手写发票、定额发票\n\n## 常见错误\n\n| 错误 | 解决 |\n|------|------|\n| `Tesseract not found` | 用包管理器安装 Tesseract（Windows: winget/scoop；Mac: brew；Linux: apt）并重启终端 |\n| `empty result` | 检查图片质量，确保光线均匀、平整 |\n| `chi_sim not found` | 重新安装Tesseract，勾选中文语言包 |\n| 识别率低 | 提高DPI（建议≥300），重新拍摄 |\n\nArchive v4.3.0: 45 files, 143708 bytes\n\nFiles: examples/example-approval.md (2757b), examples/example-ocr.md (1620b), examples/example-template.md (3025b), MEMORY.md (7285b), references/account_mapping.md (2148b), references/api-endpoints.md (3614b), references/expense_rules.md (1131b), references/risk_rules_config.yaml (1304b), references/risk-declaration.md (4304b), references/setup-guide.md (5647b), references/supplier_scope_rules.md (1683b), references/tax-rules.md (4732b), scripts/approval_abstract.py (9535b), scripts/approval_engine.py (20518b), scripts/archive_manager.py (20178b), scripts/bank_reconciler.py (17899b), scripts/batch_process.py (6297b), scripts/batch_splitter.py (16012b), scripts/check_env.py (11739b), scripts/fiscal_parser.py (3907b), scripts/fixed_parser.py (4284b), scripts/flight_parser.py (4843b), scripts/install_tesseract.ps1 (9397b), scripts/install_tesseract.sh (3959b), scripts/invoice_detector.py (14676b), scripts/ocr_engine.py (29922b), scripts/ofd_parser.py (7327b), scripts/parallel_batch.py (14102b), scripts/receipt_parser.py (11799b), scripts/risk_detector.py (15191b), scripts/secure_config.py (8845b), scripts/smart_classifier.py (6220b), scripts/taxi_parser.py (4550b), scripts/template_matcher.py (15174b), scripts/toll_parser.py (4705b), scripts/train_parser.py (4191b), scripts/unified_invoice.py (6056b), scripts/verify_abstract.py (9938b), scripts/verify_engine.py (13326b), scripts/voucher_generator.py (8728b), scripts/xml_parser.py (11186b), skill-card.md (3296b), SKILL.md (58886b), templates/config_template.yaml (2145b), _meta.json (137b)\n\nFile v4.3.0:SKILL.md\n\n---\nname: receipt-compliance\ndescription: 会计助手：发票OCR识别→真伪查验→报销单自动填充→对接审批系统。企业自主配置，数据本地处理。\nversion: 4.3.0\n---\n\n# 会计助手\n\n> ⚠️ **使用必读**：本Skill所有功能在本地运行，发票数据绝不外传，但**绝不提供税务咨询**。使用前请先阅读【限制说明】和【风险声明】。\n\n## 功能说明\n\n本Skill提供从发票识别到审批提交的**全链路**财税合规能力。\n\n| 模块 | 功能 | 状态 | 输入 | 输出 |\n|------|------|------|------|------|\n| 1. 发票OCR识别 | 双引擎（PaddleOCR优先+Tesseract兜底），定额票先验定位，勾稽校验 | ✅ 直接可用 | 发票图片/PDF | 结构化JSON |\n| 2. 真伪查验 | 一键生成国税总局查验链接，自动打开浏览器 | ✅ 直接可用 | 发票代码/号码 | 查验链接+结果 |\n| 3. 报销单填充 | 自适应学习模板，一键填充 | ✅ 直接可用 | 发票数据+模板 | Excel文件 |\n| 4. 审批对接 | 对接钉钉/企微/飞书审批（有完整代码模板） | ⚠️ 需配置密钥 | 报销单+配置 | 审批结果 |\n| 5. 全电发票 | 全电发票XML/OFD格式解析 | ✅ 直接可用 | 全电发票文件 | 结构化JSON |\n| 6. 多票据支持 | 火车票/飞机票/出租车/定额发票/通行费/财政票据 | ✅ 直接可用 | 票据图片 | 统一结构化JSON |\n| 7. 智能分类 | 自动匹配会计科目、计算进项税、生成凭证摘要 | ✅ 直接可用 | 结构化发票数据 | 分类结果+科目 |\n| 8. 记账凭证 | 自动生成记账凭证（用友/金蝶/QuickBooks格式） | ✅ 直接可用 | 分类结果 | 凭证文件 |\n| 9. 风险预警 | 发票连号/整数金额/频繁开票/品名异常/进销项匹配检测 | ✅ 直接可用 | 发票列表 | 三级预警报告 |\n| 10. 归档管理 | 电子档案四性检测、归档包生成、元数据采集、目录索引 | ✅ 直接可用 | 发票文件 | 标准归档包 |\n| 11. 银行对账 | 银行流水 CSV 解析 + 发票金额/日期模糊匹配 | ✅ 直接可用 | 流水 CSV + 发票数据 | 对账报告 |\n| 12. 安全配置 | 环境变量读取密钥，消除明文泄露 | ✅ 直接可用 | 环境变量 | 安全配置 |\n| 13. 并行批量 | 硬件自适应并行处理，速度提升 3-5 倍 | ✅ 直接可用 | 发票文件夹 | 批量结果 |\n| 14. 混拍切分 | 混拍图（一拍多票）自动检测切分，保持原图索引 | ✅ 直接可用 | 混拍图片 | 单票子图 |\n\n> ✅ = 装即用 ｜ ⚠️ = 需在 config.yaml 中配置对应API密钥\n>\n> 💡 **核心亮点**：发票识别、真伪查验、报销单生成 —— 这三项功能**完全不需要任何配置**，安装即用！\n\n### 设计理念\n\n1. **数据安全第一**：所有发票数据处理均在本地，不会上传到任何服务器\n2. **企业自主决策**：查验引擎、审批平台的选择权完全交给企业\n3. **透明开源**：所有代码可见可审计，无隐藏后门\n4. **渐进披露**：基础功能开箱即用，高级功能按配置解锁\n\n## 如何「指挥」它干活\n\n本Skill支持**自然语言对话**，不需要记忆任何命令。以下是各种场景下你可以直接对AI说的话：\n\n### 💬 直接用自然语言说\n\n| 你想做什么 | 直接这样说 |\n|-----------|-----------|\n| 识别一张发票 | \"帮我识别这张发票\" / \"OCR一下这个发票\" / \"扫描这张发票\" |\n| 批量识别 | \"把文件夹里所有发票都识别出来\" / \"批量扫描D:\\invoices\" |\n| 查验真伪 | \"帮我查验这张发票的真伪\" / \"查一下这个发票是不是真的\" |\n| 生成报销单 | \"用公司模板生成报销单\" / \"把识别结果填到报销单里\" |\n| 提交审批 | \"提交报销审批\" / \"发起审批\" / \"把报销单提交给钉钉审批\" |\n| 批量处理 | \"批量识别并生成报销单\" / \"把整个文件夹的发票都处理完\" |\n| 环境检查 | \"检查环境是否就绪\" / \"运行预检\" |\n| 查看帮助 | \"这个Skill能做什么\" / \"怎么用\" |\n\n### 📋 更详细的说法（推荐）\n\n**识别发票**：\n- \"请帮我识别这张发票：D:\\发票\\20260628.png\"\n- \"扫描这张发票，我要报销\"\n- \"OCR这张发票，结果保存到receipt.json\"\n\n**批量处理**：\n- \"把D:\\invoices\\里所有发票都识别出来，结果保存到output.json\"\n- \"批量扫描发票文件夹，然后生成合并报销单\"\n\n**查验真伪**：\n- \"帮我查验发票 代码:3100204130 号码:00564189\"\n- \"查一下这张发票是不是真的，发票号是00564189\"\n\n**生成报销单**：\n- \"用模板D:\\templates\\报销单.xlsx生成报销单\"\n- \"把receipt.json的数据填到报销单模板里\"\n\n**提交审批**：\n- \"把报销单提交到钉钉审批\"\n- \"发起企业微信审批，报销金额11300元\"\n\n> 💡 **小贴士**：直接上传发票图片或告诉AI文件路径，AI会自动识别你的意图并执行对应操作。\n\n## 📋 常见问题速查\n\n### 🔧 安装与配置\n\n| 问题 | 快速答案 |\n|------|---------|\n| 安装Tesseract后提示 `Tesseract not found` | 重启终端，或用 `--tesseract` 参数指定完整路径 |\n| 提示 `chi_sim not found` | 重新安装Tesseract，勾选 Chinese (Simplified) 语言包 |\n| 为什么不识别图片？ | 检查图片是否清晰、发票类型是否支持（手写/定额发票不支持） |\n| 常用安装命令 | Windows: `winget install UB-Mannheim.TesseractOCR` |\n| Mac安装 | `brew install tesseract tesseract-lang` |\n| Linux安装 | `sudo apt-get install tesseract-ocr tesseract-ocr-chi-sim` |\n\n### 📷 OCR识别\n\n| 问题 | 快速答案 |\n|------|---------|\n| 识别结果为空/少量内容 | 检查图片质量、光线、平整度、是否安装中文语言包 |\n| 识别率低/字段错误 | 使用扫描件、手机扫描APP预处理、核对关键字段 |\n| 批量处理部分失败 | 失败文件会单独记录在 `failed_files` 字段中，不影响其他文件 |\n| 图片质量要求 | ≥200DPI、光线均匀、无反光、发票平整放置 |\n| 提高识别率小技巧 | 扫描全能王APP预处理、使用扫描件、避免强光直射 |\n\n### 🏢 查验与审批\n\n| 问题 | 快速答案 |\n|------|---------|\n| 查验接口返回失败 | 检查API Key、网络访问、调用频率限制、查看日志 |\n| 审批Token获取失败 | 确认API Key正确、应用已开通权限、服务器IP已加白名单 |\n| 如何选择查验引擎 | 国税总局(免费) / 百望云/诺诺(付费API Key) / 自建接口 |\n| 支持哪些审批平台 | 钉钉、企业微信、飞书、自定义（需实现接口） |\n| 审批提交后能撤销吗 | 不可撤销（以各平台规则为准），提交前请核对内容 |\n\n### 📄 模板与数据\n\n| 问题 | 快速答案 |\n|------|---------|\n| 模板匹配失败 | 检查模板第一行是否为中文表头、文件是否损坏 |\n| 金额勾稽关系不匹配 | OCR识别错误时人工核对；0.01元以内差异属正常精度问题 |\n| 环境预检通过但OCR仍失败 | Tesseract版本过低（建议4.0+）、语言包不完整（≥5MB） |\n\n### 🛡️ 安全与合规\n\n| 问题 | 快速答案 |\n|------|---------|\n| 数据安全吗？ | 所有处理在本地完成，不会上传到任何服务器 |\n| 日志里有什么？ | 仅记录操作元数据（文件名、时间、状态），不记录发票内容 |\n| 能提供税务咨询吗 | 不能，本工具仅为技术支持，不提供税务/财务建议 |\n\n> 📖 **详细解答见下方【故障排除】部分**\n\n---\n\n## 💡 使用技巧与注意事项\n\n> 本节汇总了日常使用中最实用的技巧和注意事项，建议首次使用前快速浏览一遍。\n\n### 基本技巧\n\n| 序号 | 技巧 | 说明 |\n|------|------|------|\n| 1 | **优先用扫描件** | 扫描件比手机拍照识别率高15%-20%，文字更清晰、无反光 |\n| 2 | **手机拍照用扫描模式** | 微信/支付宝/扫描全能王APP都有\"文档扫描\"功能，能自动去阴影、纠偏 |\n| 3 | **批量处理先试一张** | 批量处理前先识别一张确认效果，避免批量失败浪费时间 |\n| 4 | **低置信度要核对** | 置信度<0.7时系统会提示警告，此时必须人工核对代码、号码、金额 |\n| 5 | **保留原始图片** | 识别失败时，系统会尝试用原始图片（跳过预处理）重新识别 |\n\n### 注意事项\n\n| 序号 | 注意点 | 原因 |\n|------|--------|------|\n| 1 | ⚠️ **OCR软件是一次性安装** | Tesseract约60MB，安装后永久使用，无需重复下载 |\n| 2 | ⚠️ **模糊发票必须手动核对** | OCR对模糊图片无法保证准确率，关键金额字段一定要人工复核 |\n| 3 | ⚠️ **审批功能需要配置API密钥** | 发票识别+验真假+报销单 无需配置，只有对接钉钉/企微/飞书审批才需要 |\n| 4 | ⚠️ **批量处理部分失败是正常的** | 系统会跳过失败文件继续处理，失败的记录在 `failed_files` 字段 |\n| 5 | ⚠️ **日志不记录发票内容** | 仅记录文件名、时间、状态等元数据，发票数据不上传不外传 |\n\n## ⚠️ 避坑指南\n\n> **本节汇总用户最容易踩的坑，每条都是真实使用中遇到的高频问题，建议首次使用前快速浏览一遍。**\n\n### 🔴 发票识别类\n\n| # | 问题现象 | 原因 | 解决方案 |\n|---|---------|------|---------|\n| 1 | 安装完Tesseract后仍然报错 | PATH环境变量未生效 | **Windows**：重启终端；或手动添加环境变量 `C:\\Program Files\\Tesseract-OCR` 到PATH |\n| 2 | 识别结果为空 | 未勾选中文语言包 | 重新运行安装包，勾选 **Chinese (Simplified)** 语言包 |\n| 3 | 金额识别错误（少0/多0） | 图片模糊或小字不清 | 用扫描APP（扫描全能王/白描）预处理图片后再试 |\n| 4 | 发票代码和号码搞反 | OCR把位置搞混了 | 代码10-12位，号码8-20位，自动识别后请人工核对位置 |\n| 5 | 电子发票PDF识别失败 | 缺少poppler | `pip install pdf2image` 并通过系统包管理器安装 poppler：Windows: `winget install poppler` 或 `scoop install poppler`；Linux: `sudo apt-get install poppler-utils`；macOS: `brew install poppler` |\n\n### 🟡 系统配置类\n\n| # | 问题现象 | 原因 | 解决方案 |\n|---|---------|------|---------|\n| 6 | 运行脚本时提示\"禁止执行\" | Windows执行策略限制 | 管理员身份运行PowerShell，执行 `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` |\n| 7 | pip下载依赖超时 | 网络不稳定或未配置镜像 | `pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple` |\n| 8 | 权限不足（PermissionError） | 文件被其他程序占用 | 关闭占用文件的程序（如Excel打开该文件）后重试 |\n| 9 | 找不到config.yaml | 未复制配置模板 | `copy templates/config_template.yaml config.yaml` |\n\n### 🟢 查验与审批类\n\n| # | 问题现象 | 原因 | 解决方案 |\n|---|---------|------|---------|\n| 10 | 查验链接无法打开 | 网络被防火墙拦截 | 用手机直接访问国税总局APP查验 |\n| 11 | 审批提交失败 | API密钥过期或权限不足 | 在钉钉/管理后台重新生成密钥，确认审批权限已开通 |\n| 12 | 审批提交后找不到记录 | 流程编码(process_code)填写错误 | 在钉钉管理后台核实正确的process_code |\n| 13 | Token获取失败 | AppKey/AppSecret错误或IP白名单未配置 | 核对密钥，联系管理员添加服务器IP到白名单 |\n\n### 🔵 效率提升类\n\n| # | 技巧 | 节省时间 |\n|---|------|---------|\n| 1 | 批量处理前先**试一张**确认效果 | 避免批量失败浪费时间 |\n| 2 | 建立公司模板文件复用 | 不用每次重新映射字段 |\n| 3 | 用桌面快捷方式存放常用脚本 | 不用每次都找路径 |\n| 4 | 手机拍照默认开\"扫描模式\" | 识别率提升15-20% |\n\n---\n\n### 模糊发票处理指南\n\n当发票图片模糊、识别效果不好时，按以下步骤处理：\n\n```\n步骤1：判断图片质量\n  → 图片分辨率<200DPI？ → 重新拍摄/扫描\n  → 有反光/阴影？       → 换个角度或光线重拍\n  → 发票褶皱严重？      → 展平后重新扫描\n\n步骤2：使用扫描APP预处理（推荐）\n  → 扫描全能王 / 白描 / 微信扫一扫\n  → APP会自动增强对比度、去阴影、纠偏\n  → 保存为JPG后重新识别\n\n步骤3：识别后人工核对\n  → 重点核对：发票代码(10-12位数字)、号码(8-20位数字)、金额\n  → 金额勾稽检查：金额 + 税额 = 价税合计？\n  → 置信度<0.7的字段重点核对\n\n步骤4：手动输入（终极方案）\n  → 如果反复识别失败，可直接手动输入发票信息\n  → 格式：python scripts/ocr_engine.py --manual\n  → 按提示输入发票代码、号码、日期、金额等\n```\n\n---\n\n## 对话示例\n\n本Skill支持通过自然语言对话方式使用，无需记忆复杂命令。\n\n### 场景1：识别单张发票\n\n```\n用户：请帮我识别这张发票 D:\\invoices\\20260628_001.png\nAI：正在识别发票...\n    ✓ 发票类型: 增值税专用发票\n    ✓ 发票代码: 3100204130\n    ✓ 发票号码: 00564189\n    ✓ 开票日期: 2026年06月28日\n    ✓ 金额: 10,000.00 元\n    ✓ 税额: 1,300.00 元\n    识别完成，已保存到 receipt.json\n```\n\n### 场景2：批量处理\n\n```\n用户：把文件夹里所有发票都识别出来\nAI：正在批量识别 D:\\invoices\\ 中的发票...\n    共发现 15 个图片文件\n    ✓ 20260628_001.png - 识别成功\n    ✓ 20260628_002.png - 识别成功\n    ⚠ 20260628_003.png - 识别失败（图片模糊）\n    ...\n    处理完成：成功 12 张，失败 3 张\n    结果已保存到 batch_result.json\n```\n\n### 场景3：查验发票真伪\n\n```\n用户：帮我查验这张发票的真伪\nAI：正在查验发票...\n    发票代码：3100204130\n    发票号码：00564189\n    ✓ 查验平台：国税总局\n    ✓ 发票状态：正常\n    ✓ 查验时间：2026-06-29 10:30:00\n```\n\n### 场景4：生成报销单\n\n```\n用户：用公司模板生成报销单\nAI：正在生成报销单...\n    ✓ 识别到 6 个字段映射\n    ✓ 已填充：开票日期、销方名称、金额、税额、价税合计、费用说明\n    报销单已生成：D:\\output\\expense_report.xlsx\n```\n\n## API调用示例\n\n### Python调用\n\n```python\nfrom scripts.ocr_engine import OCREngine\n\n# 初始化引擎\nengine = OCREngine()\n\n# 识别单张发票\nresult = engine.extract_structured_data(\"invoice.png\")\nprint(f\"发票代码: {result['invoice_code']}\")\nprint(f\"金额: {result['amount']}\")\n\n# 批量处理\nimport glob\nfor file in glob.glob(\"invoices/*.png\"):\n    result = engine.extract_structured_data(file)\n    print(f\"{file}: {result['success']}\")\n```\n\n### HTTP API调用\n\n```bash\n# 启动API服务（需安装flask）\npython scripts/api_server.py\n\n# 识别发票\ncurl -X POST http://localhost:8080/api/ocr \\\n  -F \"file=@invoice.png\"\n\n# 批量识别\ncurl -X POST http://localhost:8080/api/ocr/batch \\\n  -F \"files=@invoice1.png\" \\\n  -F \"files=@invoice2.png\"\n```\n\n## 快速配置向导（一键配置）\n\n**新手推荐**：运行以下命令自动检测环境并推荐最优配置：\n\n```bash\npython scripts/config_wizard.py\n```\n\n向导会自动完成：\n1. 检测Tesseract是否安装，未安装则提供一键安装命令\n2. 检测中文语言包是否完整\n3. 推荐查验引擎（默认：国税总局平台，免费无需API Key）\n4. 生成初始 `config.yaml` 文件\n5. 验证配置文件有效性\n\n**手动快速配置**（3步完成）：\n\n```bash\n# 1. 复制配置模板\ncp templates/config_template.yaml config.yaml\n\n# 2. 编辑配置（只需填写必填项）\n# 用编辑器打开 config.yaml，填写：\n#   - verify_engine: \"tax_bureau\" （默认，免费）\n#   - approval.platform: \"none\" （暂不配置审批）\n\n# 3. 验证配置\npython scripts/check_env.py\n```\n\n> 💡 **提示**：发票识别、验真假、生成报销单 —— 这三项**完全不需要配置**，安装即用！审批对接需要配置API密钥。\n\n## 🚀 5分钟上手指南\n\n> **30秒摘要**：安装识别软件 → 识别发票 → 生成报销单。全程无需写代码，无需配置API。\n\n### 完整流程图\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│                        5分钟快速上手流程                              │\n└─────────────────────────────────────────────────────────────────────┘\n\n 步骤1：安装（2分钟）                步骤2：识别（1分钟）\n ┌─────────────────────┐           ┌─────────────────────┐\n │ 一键安装PowerShell脚本 │    →     │ 拖入发票图片，自动识别 │\n │ (国内镜像，免配置)     │           │ 输出结构化JSON数据    │\n └─────────────────────┘           └─────────────────────┘\n                                            ↓\n 步骤4：（可选）一键生成报销单   ←   步骤3：验真假（30秒）\n ┌─────────────────────┐           ┌─────────────────────┐\n │ 用模板自动填充生成Excel │    ←     │ 一键生成查验链接       │\n │ 支持自定义字段映射      │           │ 自动打开浏览器查验     │\n └─────────────────────┘           └─────────────────────┘\n```\n\n### 🎯 三步开始使用\n\n**第1步 — 下载安装（2分钟）**：\n\n| 系统 | 操作 |\n|------|------|\n| **Windows** | 双击运行 `scripts\\install_tesseract.ps1`（右键→使用PowerShell运行） |\n| **Mac** | 终端执行 `bash ./scripts/install_tesseract.sh` |\n| **Linux** | `sudo apt-get install tesseract-ocr tesseract-ocr-chi-sim pip install Pillow pytesseract openpyxl pyyaml` |\n\n**第2步 — 识别发票（30秒）**：\n\n```bash\n# 单张识别\npython scripts/ocr_engine.py --input 发票图片.png --output 识别结果.json\n\n# 批量识别整个文件夹\npython scripts/batch_process.py --input 发票文件夹/ --output 批量结果.json\n```\n\n**第3步 — 查验+报销单（1分钟）**：\n\n```bash\n# 生成国税总局查验链接（自动打开浏览器）\npython scripts/verify_engine.py --invoice-code 3100204130 --invoice-number 00564189 --date \"2026年06月28日\" --amount 10000.00 --open-browser\n\n# 生成报销单Excel\npython scripts/template_matcher.py fill --receipt receipt.json --template templates/expense_basic.xlsx --output 报销单.xlsx\n```\n\n### ✅ 安装验证\n\n```bash\npython scripts/check_env.py\n```\n- ✅ 显示\"环境就绪\" → 直接开始用\n- ❌ 有红叉 → 按提示修复后重试\n\n### ⚙️ 高级功能配置（可选）\n\n如果需要使用查验真伪或提交审批功能，才需要配置 `config.yaml`：\n\n```bash\n# 复制配置模板\ncp templates/config_template.yaml config.yaml\n\n# 编辑配置文件，填入API密钥\nnotepad config.yaml  # Windows\nnano config.yaml     # Linux/macOS\n```\n\n## 审批功能 - 完整配置指南\n\n> **30秒摘要**：审批功能提供了完整的代码引擎，企业只需在config.yaml中填入3个凭证即可使用，无需写任何代码。\n\n### 钉钉审批配置（3步完成）\n\n**第1步：创建钉钉应用**\n\n打开 [钉钉开放平台](https://open-dev.dingtalk.com) → 创建企业内部应用 → 记录下 **AppKey** 和 **AppSecret**\n\n**第2步：开通应用权限**\n\n在应用管理页面：\n- 权限管理 → 搜索\"审批\" → 开通 **审批:write** 权限\n- 基础设置 → 添加服务器出口IP到IP白名单\n\n**第3步：获取流程编码**\n\n钉钉管理后台 → 审批流程管理 → 编辑报销审批流程 → 在URL中获取 `process_code`\n\n```yaml\napproval:\n  platform: \"dingtalk\"\n  dingtalk:\n    app_key: \"你的AppKey\"\n    app_secret: \"你的AppSecret\"\n    process_code: \"你的流程编码\"\n```\n\n### 企业微信审批配置（3步完成）\n\n**第1步：创建自建应用**\n\n企业微信管理后台 → 应用管理 → 创建自建应用 → 记录下 **CorpID** 和 **Secret**\n\n**第2步：开通审批权限**\n\n在应用详情页 → 功能 → 审批 → 配置审批模板 → 获取 **TemplateID**\n\n**第3步：配置IP白名单**\n\n企业微信管理后台 → 应用管理 → 自建应用 → 接收消息设置 → 获取出口IP并添加到白名单\n\n```yaml\napproval:\n  platform: \"wecom\"\n  wecom:\n    corp_id: \"你的CorpID\"\n    secret: \"你的Secret\"\n    template_id: \"你的TemplateID\"\n```\n\n### 审批测试方法\n\n配置完成后，运行以下命令验证审批功能是否配置正确：\n\n```bash\n# 测试钉钉审批\npython scripts/approval_engine.py \\\n  --config config.yaml \\\n  --expense 报销单.xlsx \\\n  --user-id 你的工号 \\\n  --amount 10000 \\\n  --expense-type 信息技术服务\n```\n\n如果配置正确，返回结果示例：\n```json\n{\n  \"status\": \"success\",\n  \"message\": \"审批提交成功\",\n  \"approval_id\": \"xxx\",\n  \"submit_time\": \"2026-07-04T22:30:00\"\n}\n```\n\n---\n\n## 详细配置说明\n\n见 `references/setup-guide.md`\n\n## 示例\n\n### 示例1：识别单张发票\n\n**输入**：\n\n```\n识别发票 D:\\invoices\\20260628_001.png\n```\n\n**输出**：\n\n```json\n{\n  \"success\": true,\n  \"invoice_type\": \"增值税专用发票\",\n  \"invoice_code\": \"3100204130\",\n  \"invoice_number\": \"00564189\",\n  \"invoice_date\": \"2026年06月28日\",\n  \"seller_name\": \"上海某某科技有限公司\",\n  \"amount\": 10000.00,\n  \"tax_rate\": 0.13,\n  \"tax_amount\": 1300.00,\n  \"total\": 11300.00,\n  \"remark\": \"*信息技术服务费*\",\n  \"confidence\": 0.96\n}\n```\n\n### 示例2：查验发票真伪\n\n**输入**：\n\n```\n查验发票 代码:3100204130 号码:00564189 日期:2026-06-28 金额:10000.00\n```\n\n**输出**：\n\n```json\n{\n  \"engine\": \"国税总局查验平台\",\n  \"status\": \"ready\",\n  \"verify_url\": \"https://inv-veri.chinatax.gov.cn/index.html?fpdm=3100204130&fphm=00564189\",\n  \"message\": \"已为您生成查验链接，点击即可查验\",\n  \"params\": {\n    \"invoice_code\": \"3100204130\",\n    \"invoice_number\": \"00564189\",\n    \"billing_date\": \"2026-06-28\",\n    \"amount\": 10000.00\n  }\n}\n```\n\n> 如配置了百望云/诺诺API Key，会自动调用第三方API获取查验结果。\n\n### 示例3：生成报销单\n\n**输入**：\n\n```\n用模板 D:\\templates\\公司报销单.xlsx 生成报销单，数据来自 D:\\invoices\\receipt.json\n```\n\n**输出**：\n\n```\n模板分析完成：识别到 6 个字段映射，置信度 0.8+\n报销单已生成：D:\\output\\expense_report_20260629.xlsx\n已填充 6 个字段：开票日期、销方名称、金额、税额、价税合计、费用说明\n```\n\n### 示例4：批量识别并合并为报销单\n\n```bash\npython scripts/batch_process.py --input D:\\invoices\\ --template D:\\templates\\公司报销单.xlsx --output D:\\output\\合并报销单.xlsx\n```\n\n### 示例5：提交审批\n\n```bash\npython scripts/approval_engine.py --config config.yaml --expense D:\\output\\报销单.xlsx --user-id manager123 --amount 11300 --expense-type 信息技术服务\n```\n\n## 发票类型支持与图片要求\n\n> **30秒摘要**：支持增值税专票/普票/电子票。识别效果高度依赖图片质量——扫描件>拍照，清晰>模糊，建议分辨率≥200DPI。\n\n### 支持的发票类型\n\n- ✅ 增值税专用发票\n- ✅ 增值税电子发票\n- ✅ 增值税普通发票\n- ✅ 电子发票（PDF格式，需安装poppler）\n\n### 暂不支持\n\n- ❌ 手写发票\n- ❌ 定额发票\n- ❌ 机动车销售发票\n- ❌ 二手车销售发票\n- ❌ 海关缴款书\n\n### 图片质量要求（直接影响识别率）\n\n> ⚠️ **重要提醒**：Tesseract OCR识别效果**高度依赖图片质量**。模糊、反光、低分辨率的图片会导致识别率显著下降。\n\n| 质量等级 | 分辨率 | 光线 | 平整度 | 预期准确率 |\n|---------|--------|------|--------|-----------|\n| 优秀 | ≥300DPI | 均匀 | 无褶皱 | 95%+ |\n| 良好 | 200-300DPI | 较均匀 | 轻微褶皱 | 85-95% |\n| 可用 | 150-200DPI | 一般 | 有褶皱 | 70-85% |\n| 较差 | <150DPI | 反光/阴影 | 严重褶皱 | <70%，建议重新拍摄 |\n\n**图片质量自检清单**：\n- [ ] 发票代码和号码区域是否清晰可辨？\n- [ ] 金额数字是否有模糊或重影？\n- [ ] 是否有反光或阴影遮挡关键信息？\n- [ ] 发票边缘是否完整可见？\n- [ ] 图片分辨率是否足够（建议手机相机≥1200万像素）？\n\n> **提高识别率的小技巧**：\n> 1. 用手机相机拍摄时，开启\"文档模式\"或\"扫描模式\"\n> 2. 避免强光直射，减少反光\n> 3. 发票平整放置，不要弯曲\n> 4. 确保发票代码、号码区域清晰可见\n> 5. 如果无法识别，请检查图片中是否有手写涂改\n> 6. **推荐使用扫描件**，比拍照效果更好\n> 7. 可使用手机扫描APP（如\"扫描全能王\"）预处理图片\n\n## 限制说明\n\n> **30秒摘要**：仅支持增值税发票（不支持手写/定额），数据全部本地处理（不上传），不提供税务咨询。\n\n### 功能限制\n\n| 限制项 | 具体说明 |\n|--------|---------|\n| OCR识别 | 仅支持增值税发票（专票/普票/电子票） |\n| 暂不支持 | 手写发票、定额发票、机动车发票、二手车发票 |\n| 查验功能 | 国税总局查验链接自动生成，无需API Key |\n| 审批功能 | 需企业管理员在对应平台开通审批API权限，提供完整代码模板和分步配置指南 |\n\n### 技术限制\n\n| 限制项 | 具体说明 |\n|--------|---------|\n| 运行环境 | Python 3.8+ |\n| 必须安装 | Tesseract OCR + 中文语言包 |\n| 图片格式 | PNG/JPG/TIFF/PDF（PDF需要poppler） |\n| 语言 | 中文简体，其他语言准确率显著下降 |\n| 并发 | 硬件自适应并行处理（CPU 核心数 × 0.5/× 0.75），批量速度提升 3-5 倍 |\n\n### 安全限制\n\n| 限制项 | 具体说明 |\n|--------|---------|\n| 数据上传 | 绝不将发票图片上传到任何第三方服务器 |\n| API调用 | 仅在用户明确授权后执行，且仅调用用户配置的平台 |\n| 日志 | 仅记录操作元数据（文件名、时间、状态），不记录发票内容 |\n| 临时文件 | 识别完成后自动清理，保留不超过24小时 |\n\n## 错误代码速查表\n\n| 错误代码 | 问题描述 | 解决方案 |\n|---------|---------|---------|\n| `Tesseract not found` | Tesseract未安装或未加入PATH | 运行 `install_tesseract.ps1` 并重启终端 |\n| `chi_sim not found` | 中文语言包未安装 | 重新安装Tesseract，勾选Chinese语言包 |\n| `PIL not found` | Pillow未安装 | `pip install Pillow` |\n| `pytesseract not found` | pytesseract未安装 | `pip install pytesseract` |\n| `openpyxl not found` | openpyxl未安装 | `pip install openpyxl` |\n| `pdf2image not found` | PDF转图片工具未安装 | `pip install pdf2image` + 安装poppler |\n| `empty result` | OCR未识别到文字 | 检查图片质量、光线、平整度 |\n| `low confidence` | 识别置信度低于0.7 | 建议重新拍摄，或手动输入发票信息 |\n| `verify_engine not configured` | 查验引擎未配置 | 编辑config.yaml，填写对应API Key |\n| `approval_engine not configured` | 审批引擎未配置 | 编辑config.yaml，选择并填写审批平台 |\n| `token_failed` | 获取AccessToken失败 | 检查API Key/Secret是否正确 |\n| `template_not_found` | 模板文件不存在 | 检查template路径是否正确 |\n\n## 风险声明\n\n> **30秒摘要**：数据本地处理不上传、查验结果由第三方平台提供、审批不可撤销、本工具不提供税务咨询。\n\n> 🔴 **使用本Skill前，请务必仔细阅读以下条款：**\n\n### 1. 数据安全责任\n\n- 所有发票数据仅在用户本地设备处理，不会上传到任何服务器\n- **但用户需自行确保本地设备的安全**，Skill开发者不对数据泄露承担责任\n- 用户需自行负责API密钥的安全保管\n- 建议定期轮换API密钥（每90天一次）\n\n### 2. 查验结果免责声明\n\n- 查验引擎返回的结果由第三方平台提供\n- Skill仅提供技术对接，**不对查验结果的准确性负责**\n- 如对查验结果有疑问，请直接联系相关税务平台\n\n### 3. 审批操作责任\n\n- 审批提交后不可撤销（以各平台规则为准）\n- Skill不审批内容的合规性和真实性\n- 用户对提交的报销单内容负全部责任\n\n### 4. 财务合规要求\n\n- 本工具仅为技术支持工具，**不提供任何税务咨询或财务建议**\n- 所有财务决策应由专业财务人员做出\n- 需专业税务意见时，请咨询持牌税务顾问\n\n### 5. 禁止行为\n\n使用本Skill，用户不得：\n- 伪造、变造发票\n- 使用假发票报销\n- 虚增报销金额\n- 报销与业务无关的费用\n- 进行其他违反财务法规的行为\n\n### 6. 企业自主决策清单\n\n使用前，请确认您已决定以下事项：\n\n- [ ] 查验引擎选择：□ 国税总局平台（免费） □ 百望云 □ 诺诺发票 □ 自建接口\n- [ ] 审批平台选择：□ 钉钉 □ 企业微信 □ 飞书 □ 自建系统 □ 暂不使用\n- [ ] 数据安全策略：日志保留期限、临时文件清理频率\n- [ ] 合规审查：内部审计、外部审计计划\n\n## 配置文件模板\n\n```yaml\n# config.yaml - 企业自主配置\n# 本文件为示例模板，企业需根据实际情况填写\n# 未配置的功能模块将提示手动操作\n\n# ==================== 查验引擎配置 ====================\nverify_engine: \"tax_bureau\"\n# 可选值:\n# - \"tax_bureau\": 国税总局查验平台（免费，无需API Key）\n# - \"bairong\": 百望云API（需API Key+Secret）\n# - \"nuonuo\": 诺诺发票API（需API Key+Secret）\n# - \"custom\": 企业自建接口（需接口地址）\n\n# 百望云（如选择bairong）\nbairong:\n  api_key: \"在此填写您的百望云API Key\"\n  api_secret: \"在此填写您的百望云Secret\"\n\n# 诺诺发票（如选择nuonuo）\nnuonuo:\n  api_key: \"在此填写您的诺诺发票API Key\"\n  api_secret: \"在此填写您的诺诺发票Secret\"\n\n# 自建查验接口（如选择custom）\ncustom:\n  endpoint: \"https://your-company.com/api/verify\"\n  method: \"POST\"\n  headers:\n    Authorization: \"Bearer YOUR_TOKEN\"\n\n# ==================== 审批平台配置 ====================\napproval:\n  platform: \"none\"  # dingtalk / wecom / feishu / none\n\n  # 钉钉审批\n  dingtalk:\n    app_key: \"\"\n    app_secret: \"\"\n    process_code: \"\"\n\n  # 企业微信审批\n  wecom:\n    corp_id: \"\"\n    secret: \"\"\n    template_id: \"\"\n\n  # 飞书审批\n  feishu:\n    app_id: \"\"\n    app_secret: \"\"\n    approval_code: \"\"\n\n  # 自建审批系统\n  custom:\n    endpoint: \"\"\n    method: \"POST\"\n    headers: {}\n    timeout: 30\n\n# ==================== 模板映射配置 ====================\ntemplate:\n  path: \"templates/expense_basic.xlsx\"  # 报销单模板路径\n  field_mapping:\n    invoice_date: \"开票日期\"\n    seller_name: \"销方名称\"\n    amount: \"金额（不含税）\"\n    tax_amount: \"税额\"\n    total: \"价税合计\"\n    remark: \"费用说明\"\n    invoice_code: \"发票代码\"\n    invoice_number: \"发票号码\"\n```\n\n## 外部平台不可用时的降级方案\n\n> 💡 **重要提示**：查验和审批功能依赖外部平台（国税总局、钉钉、企微、飞书等），遇到平台维护或网络故障时，可使用以下降级方案。\n\n### 查验发票真伪 - 降级方案\n\n当自动查验平台不可用时，可手动查验：\n\n**方法1：使用国税总局官方平台**（推荐）\n1. 打开浏览器，访问：https://inv-veri.chinatax.gov.cn\n2. 输入发票代码、发票号码、开票日期、开具金额（不含税）\n3. 输入验证码，点击\"查验\"\n4. 截图或保存查验结果备查\n\n**方法2：使用手机APP查验**\n- 国家税务总局\"增值税发票查验平台\"APP\n- 支付宝\"发票管家\" - 发票查验功能\n- 微信\"腾讯发票\" - 发票查验功能\n\n**方法3：电话查验**\n- 拨打12366纳税服务热线，提供发票信息查询真伪\n\n### 提交审批 - 降级方案\n\n当自动审批提交不可用时，可手动提交：\n\n**钉钉审批**：\n1. 打开钉钉APP → 工作台 → 审批\n2. 找到对应的报销审批流程\n3. 手动填写报销信息，上传报销单PDF\n4. 提交审批\n\n**企业微信审批**：\n1. 打开企业微信APP → 工作台 → 审批\n2. 选择报销审批流程\n3. 填写信息，上传附件\n4. 提交审批\n\n**飞书审批**：\n1. 打开飞书APP → 工作台 → 审批\n2. 创建新的报销审批\n3. 填写表单，上传报销单\n4. 提交审批\n\n### 数据存储建议\n\n在外部平台不可用期间，建议：\n1. 将识别结果保存为JSON文件（`--output result.json`）\n2. 将报销单保存为PDF（`--format pdf`）\n3. 平台恢复后，使用批量提交功能一次性提交\n\n## 故障排除\n\n### 常见问题\n\n**Q1: 安装Tesseract后仍然提示 `Tesseract not found`**\n\nA: 通常是PATH环境变量未生效。\n\n- **Windows**：重启PowerShell/终端，或手动运行 `refreshenv`\n- **Linux/macOS**：运行 `source ~/.bashrc` 或 `source ~/.zshrc`\n- 紧急方案：使用 `--tesseract` 参数指定完整路径：\n  ```bash\n  python ocr_engine.py --tesseract \"C:\\Program Files\\Tesseract-OCR\\tesseract.exe\" --input 发票.png\n  ```\n\n**Q2: 识别结果为空或仅识别到少量内容**\n\nA: 按顺序排查：\n1. 图片质量是否过低？（拍摄光线、平整度、分辨率）\n2. 发票类型是否支持？（手写发票不支持）\n3. 是否安装了中文语言包？（运行 `tesseract --list-langs` 检查是否有 `chi_sim`）\n4. 尝试提高图片预处理质量（在代码中调整阈值参数）\n5. 尝试用原始图片（未预处理）重新识别 — 某些情况下预处理反而会降低图片质量\n\n**Q3: 提示 `PermissionError` 或 `Occupied`**\n\nA: 文件被其他程序关闭。请关闭所有占用目标文件的程序后重试。\n\n**Q4: 查验接口返回失败**\n\nA: 排查顺序：\n1. 检查API Key/Secret是否正确（无多余空格）\n2. 检查网络是否可访问对应平台\n3. 检查是否超出调用频率限制\n4. 查看 `logs/verify_engine.log` 了解详细错误\n\n**Q5: 模板匹配失败**\n\nA: 检查以下几点：\n1. 模板文件第一行是否为中文表头\n2. 模板文件是否未损坏（用Excel打开确认）\n3. 字段名是否在预设映射表中（见 `common_mappings`）\n4. 可尝试手动指定映射关系\n\n**Q6: 如何减小识别结果文件体积？**\n\nA: 处理完成后，删除 `output/` 目录下的中间文件（`.json`、`.xlsx`），仅保留最终需要的文件。Skill会自动清理临时文件。\n\n**Q7: 支持哪些审批平台？**\n\nA: 钉钉、企业微信、飞书、自建系统（需实现接口）。\n\n**Q8: 如果审批平台不在列表中怎么办？**\n\nA: 使用 `custom` 选项，填写企业自建审批系统的接口地址和鉴权方式。\n\n**Q9: OCR识别率低，很多字段识别错误**\n\nA: 识别效果主要取决于图片质量，请尝试以下方法：\n1. **图片质量**：确保分辨率≥200DPI，光线均匀，无反光\n2. **推荐使用扫描件**：扫描件比拍照效果更好，文字更清晰\n3. **使用手机扫描APP**：如\"扫描全能王\"、\"白描\"等APP预处理图片，可显著提升识别率\n4. **图片格式**：优先使用JPG或PNG，避免PDF（需额外安装poppler）\n5. **发票类型**：仅支持增值税专票/普票/电子票\n6. **手动校验**：识别后人工核对关键字段（代码、号码、金额）\n7. **模板学习**：使用 `template_matcher.py analyze` 分析模板结构\n\n**Q10: 批量处理时部分文件失败**\n\nA: 正常现象，不影响其他文件。失败的文件会记录在JSON输出的 `failed_files` 字段中，包含：\n- `file`：文件路径\n- `error`：错误原因\n- `tip`：建议操作\n- `suggestions`：具体改进建议\n\n**Q11: 审批Token获取失败**\n\nA: 排查步骤：\n1. 确认API Key/Secret正确（无空格、大小写正确）\n2. 确认应用已开通审批权限（钉钉/企微/飞书管理后台）\n3. 确认服务器IP已在白名单中\n4. 确认Token未过期（默认2小时有效期）\n5. 检查网络是否可访问对应API地址\n\n**Q12: 如何选择合适的查验引擎？**\n\nA: 根据企业需求选择：\n- **国税总局平台（推荐）**：免费，无需API Key，生成链接手动查验\n- **百望云/诺诺发票**：需付费API Key，自动返回查验结果\n- **自建接口**：适合有自建查验系统的企业\n\n**Q13: 金额勾稽关系不匹配怎么办？**\n\nA: 可能原因：\n1. OCR识别错误：人工核对金额、税额、价税合计\n2. 小数精度问题：系统自动四舍五入，0.01元以内差异可忽略\n3. 特殊发票：部分发票金额计算方式不同\n\n**Q14: 环境预检通过但OCR仍失败**\n\nA: 可能原因：\n1. Tesseract版本过低（建议4.0+）\n2. 中文语言包不完整（检查文件大小≥5MB）\n3. 图片质量极差（重新拍摄）\n4. 发票类型不支持（手写发票、定额发票不支持）\n\n### 日志文件说明\n\n如果以上方案均无法解决问题，请查看日志文件获取详细信息：\n\n```\nlogs/\n├── ocr_engine.log          # OCR识别详情\n├── verify_engine.log       # 查验详情\n├── template_matcher.log    # 模板匹配详情\n├── approval_engine.log     # 审批详情\n└── error.log               # 错误日志（优先查看）\n```\n\n## 支持与反馈\n\n- 问题反馈：请在 SkillHub 平台提交 Issue\n- 功能建议：欢迎提交 Pull Request\n- 邮箱：联系Skill开发者\n- 联系信息：njskills@agent.qq.com\n- 版本更新提醒：检测到新版本发布时，请及时通过 tongyifabu.ps1 更新本 Skill 以获取最新功能和修复\n\n## 全电发票（数电票）\n\n本 Skill 已支持全电发票（全面数字化的电子发票），兼备传统发票 OCR 与全电发票 XML/OFD 解析的双轨模式。\n\n### 支持的文件类型\n\n| 类型 | 扩展名 | 解析方式 |\n|------|--------|---------|\n| 传统纸质发票 | `.png`、`.jpg`、`.jpeg`、`.bmp` | OCR 引擎识别 |\n| 传统电子发票（PDF） | `.pdf` | OCR 引擎识别（需 poppler） |\n| 全电发票（XML） | `.xml` | 专用 XML Schema 解析器，提取结构化数据 |\n| 全电发票（OFD） | `.ofd` | OFD 解析器或转换为 PDF 后 OCR |\n\n### 全电发票特有字段\n\n| 字段 | 说明 | 传统发票字段差异 |\n|------|------|-----------------|\n| 发票号码（20位） | 全电发票唯一标识 | 传统发票 8-20 位 |\n| 税务数字账户 ID | 数电票归集账户标识 | 传统发票无此概念 |\n| 校验码 | 全电票安全校验 | 传统发票为密码区 |\n| 特定业务信息 | 差额计税、建筑服务等标识 | 传统发票无明确标记 |\n\n### 使用方式\n\n**全电发票 XML 文件**：\n```bash\npython scripts/xml_parser.py path/to/invoice.xml\n```\n\n**全电发票 OFD 文件**：\n```bash\npython scripts/ofd_parser.py path/to/invoice.ofd\n```\n\n**自动识别（推荐）**：\n```bash\npython scripts/invoice_detector.py path/to/any_invoice\n```\n\n模块会自动判断文件类型并调用对应解析器。\n\n### 降级方案\n\n当 `ofdparser` Python 库未安装时，OFD 解析器会提示您：\n\n1. **安装 ofdparser**：`pip install ofdparser`（首选）\n2. **转换为 PDF**：使用数科阅读器、福昕 OFD 阅读器导出为 PDF，再用 OCR 识别\n3. **手动阅读**：通过官方 OFD 阅读器手动查看\n\n### 税务数字账户接口说明\n\n全电发票通过税务数字账户归集管理。如需对接税务数字账户接口，可参考：\n\n- 电子税务局官方文档：https://etax.chinatax.gov.cn/\n- 发票查验（国税总局）：https://inv-veri.chinatax.gov.cn/\n\n> ⚠️ **注意**：税务数字账户对接以企业自主配置为原则，本 Skill 提供标准接口框架，企业需根据实际税局接口规范自行实现具体调用逻辑。\n\n## 更新日志\n\n| v4.3.0 | 2026-08-24 | 新增：PaddleOCR 双引擎降级层（ocr_engine.py 重写），PaddleOCR 优先 + Tesseract 兜底，自动探测可用引擎；新增：定额票版式先验定位表（fixed_layout_prior），固定字段位置驱动 ROI 局部 OCR；新增：手写数字后处理约束（_cross_check 勾稽校验引擎），金额+税额=价税合计不通过则标记人工复核不入库；新增：混拍图检测与子图切分引擎 batch_splitter.py，行距聚类切分 + 边界接触边框特征二次切分，保持原图-子图索引；升级：invoice_detector.py 集成 PaddleOCR 双引擎 |\n| v4.2.1 | 2026-08-16 | 修复：将 SKILL.md、check_env.py、install_tesseract.ps1 中 poppler-windows 下载源从个人 fork（oschwartz10612/blog.alivate.com.au）替换为系统包管理器（winget/scoop/apt/brew），消除非官方来源供应链风险；修复：secure_config.py 默认脱敏输出，validate_before_call() 返回值统一脱敏，消除密钥泄露到 stdout 的风险 |\n| v4.2.0 | 2026-08-16 | 新增：银行流水对账引擎 bank_reconciler.py，支持主流银行 CSV 流水解析，金额模糊匹配（±0.01 元容差）+ 日期模糊匹配（±3 天容差）+ 综合评分机制；新增：安全密钥配置模块 secure_config.py，统一从环境变量读取 API 密钥（INVOICE_ 前缀），消除明文泄露风险，含脱敏显示和缺失校验；新增：并行批量处理引擎 parallel_batch.py，硬件自适应 worker 分配（CPU × 0.5/× 0.75），含内存检测自动降级、分块处理、失败重试机制 |\n| v4.0.0 | 2026-08-01 | 新增：全电发票XML解析器 xml_parser.py；新增：OFD版式文件解析器 ofd_parser.py；新增：火车票解析器 train_parser.py；新增：飞机行程单解析器 flight_parser.py；新增：出租车票解析器 taxi_parser.py；新增：定额发票解析器 fixed_parser.py；新增：通行费票据解析器 toll_parser.py；新增：财政票据解析器 fiscal_parser.py；新增：智能分类器 smart_classifier.py，支持费用类型自动匹配、进项税额自动计算、会计科目自动映射；新增：记账凭证生成器 voucher_generator.py，支持用友/金蝶/QuickBooks导入格式；新增：统一发票数据结构 unified_invoice.py，兼容新旧发票和多种票据类型；新增：票种自动识别模块 invoice_detector.py，自动路由传统OCR或专用解析器；新增：会计科目对照表 account_mapping.md；新增：费用分类规则 expense_rules.md |\n| v3.7.0 | 2026-07-22 | 新增：全电发票（数电票）XML 格式解析器 xml_parser.py，支持 20 位全电发票号码、校验码、税务数字账户等特有字段提取；新增：OFD 版式文件解析器 ofd_parser.py；新增：票种自动识别模块 invoice_detector.py，自动路由传统 OCR 或全电解析；新增：统一发票数据结构 unified_invoice.py，兼容新旧发票格式；新增：SKILL.md 全电发票使用章节；新增：版本更新提醒机制；新增：联系信息 njskills@agent.qq.com |\n| v3.4.0 | 2026-07-13 | 修复：移除 install_tesseract.ps1 中指向个人 Gitee 仓库的下载源，替换为 winget/scoop 官方源和 GitHub 官方 Release；修复：将 approval_abstract.py、api-endpoints.md、setup-guide.md、example-approval.md 中所有 open.duxiaoman.com 错误链接替换为钉钉官方地址 open-dev.dingtalk.com；修复：verify_engine.py 中 subprocess.Popen 移除 shell=True，改为列表参数形式 |\n| v3.3.0 | 2026-07-13 | 更名：插件文件夹名从 tax-receipt-compliance 改为 receipt-compliance；更名：displayName 从财税合规全链路助手改为会计助手 |\n\n### v3.2.0 (2026-07-04)\n\n**🎯 基于TRACE评测反馈的深度优化**\n\n- **新增**：【5分钟上手指南】含完整流程图，从安装到报销一步到位，解决\"使用流程不清晰\"问题\n- **新增**：【避坑指南】14个高频问题+解决方案，覆盖识别/配置/查验/审批全场景\n- **新增**：【审批功能完整配置指南】钉钉/企微3步配置流程+测试命令，降低对接门槛\n- **新增**：verify_engine.py 支持 `--open-browser` 参数，一键生成查验链接并自动打开浏览器\n- **改进**：审批引擎(approval_engine.py)从\"框架\"升级为\"完整可用\"，钉钉/企微审批可直接调用API提交\n- **改进**：功能说明表更新，真伪查验改为\"✅ 直接可用\"（一键生成链接+自动打开浏览器）\n- **改进**：限制说明更新，查验功能标注为\"无需API Key\"\n- **改进**：所有脚本错误提示风格统一，保持专业术语+通俗解释的平衡\n\n**评测反馈响应**：\n- A(适用性) 4.3/5 → 新增完整使用流程图+审批配置指南，降低上手门槛\n- C(规范性) 4.5/5 → 新增避坑指南，问题更集中；文档结构优化\n- E(有效性) 4.2/5 → 验真假功能完整可用（一键打开浏览器），审批引擎从框架升级为完整实现\n\n**🎯 基于用户评测反馈的重大改进**\n\n- **安全性提升**：安装脚本增加SHA256文件完整性校验，下载完成后自动验证文件完整性\n- **安装简化**：一键安装脚本优化，增加更详细的进度显示和成功/失败提示\n- **OCR识别率提升**：图像预处理算法升级，增加自适应二值化（OTSU）、去噪、边缘增强等功能\n- **模糊发票处理**：新增`enhance_mode`参数（auto/normal/aggressive/gentle），自动根据图片质量选择最佳预处理模式\n- **图像质量预检**：OCR引擎增加`check_image_quality()`函数，自动检测图片分辨率并给出预处理建议\n- **开箱即用性提升**：快速开始章节简化，一键安装脚本支持更多安装方式\n- **降级方案**：外部平台不可用时，给出详细的手工操作指南（见下方【外部平台不可用时的降级方案】）\n- **默认配置**：提供默认配置模板，基础功能无需配置即可使用\n- **文档优化**：快速开始章节重构，30秒即可了解核心步骤\n- **修复语句**：优化所有脚本的错误提示和操作建议，改为更自然、更易理解的中文表达\n\n**评测反馈响应**：\n- T(可信任度) 4.5/5 → 安全性提升，文件完整性校验\n- R(可靠性) 4.6/5 → 模糊发票识别率提升，预处理算法优化\n- A(适用性) 4.8/5 → 安装流程简化，开箱即用性提升\n- C(规范性) 4.8/5 → 文档结构优化，快速开始章节重构\n- E(有效性) 4.4/5 → OCR识别率提升，默认配置提供\n\n### v2.7.0 (2026-06-30)\n- **新增**：【使用技巧与注意事项】章节，汇总5项基本技巧+5项注意事项，一目了然\n- **新增**：【模糊发票处理指南】，4步流程应对图片模糊场景\n- **新增**：OCR引擎 `--manual` 手动输入模式，OCR失败时可直接手动输入发票信息\n- **新增**：长章节增加\"30秒摘要\"，减少阅读时间（快速开始/发票类型/限制说明/风险声明）\n- **新增**：OCR软件大小说明，解释60MB安装包的必要性（数据安全 vs 软件体积的权衡）\n- **改进**：手动输入模式支持金额勾稽自动检查，输入不一致会提示警告\n\n### v2.6.5 (2026-06-30)\n- **修复**：修复bug\n\n\n### v2.6.0 (2026-06-30)\n- **新增**：【如何「指挥」它干活】章节，包含自然语言对话示例表格（8种场景+详细说法）\n- **新增**：【常见问题速查】集中解答板块，按6大类（安装配置/OCR识别/查验审批/模板数据/安全合规）组织\n- **改进**：FAQ和常见问题从分散在多处改为集中速查表+详细解答两部分，查找更方便\n- **改进**：触发词章节扩展为更详细的\"如何指挥\"说明，降低用户上手门槛\n- **改进**：所有错误提示保持专业术语+通俗解释的平衡\n\n### v2.5.0 (2026-06-29)\n- **改进**：版本号升至 2.5.0\n- **改进**：图片质量要求增加\"图片质量自检清单\"，帮助用户提前发现图片问题\n- **改进**：图片质量要求增加扫描件推荐和手机扫描APP建议\n- **改进**：图片质量要求顶部增加醒目的\"识别效果高度依赖图片质量\"提醒\n- **改进**：FAQ Q2增加\"尝试用原始图片重新识别\"的排查建议\n- **改进**：FAQ Q9增加\"推荐使用扫描件\"和\"手机扫描APP预处理\"建议\n- **改进**：所有脚本错误提示在专业术语后增加通俗解释，方便非技术用户理解\n- **改进**：ocr_engine.py 低置信度阈值从0.6调整为0.7，更早提醒用户核对\n- **改进**：check_env.py 输出格式优化，失败项用更醒目的标识\n\n### v1.3.0 (2026-06-29)\n- **改进**：OCR引擎增加PSM模式回退机制（6→3→4→11→12）\n- **改进**：OCR引擎增加图片质量预检（尺寸、模式、亮度检查）\n- **改进**：OCR引擎提供详细的识别失败诊断和建议\n- **改进**：查验引擎增加参数格式校验和类型转换\n- **改进**：查验引擎增加重试机制和指数退避\n- **改进**：审批引擎增加Token获取重试和超时设置\n- **改进**：审批引擎增加报销单文件存在性检查\n- **改进**：审批引擎增加配置完整性验证\n- **改进**：发票解析器支持更多日期格式和金额格式\n- **改进**：发票解析器增加金额勾稽检查和日期有效性验证\n- **改进**：模板匹配器增加文件格式检查和表头完整性验证\n- **改进**：批量处理增加失败文件记录和统计\n- **改进**：环境预检增加Tesseract版本和语言包完整性检查\n- **改进**：错误代码速查表增加更多FAQ条目（Q9-Q14）\n- **改进**：所有脚本增强错误处理和容错能力\n\n### v1.1.0 (2026-06-29)\n- **新增**：环境预检脚本 `scripts/check_env.py`\n- **新增**：错误代码速查表\n- **新增**：发票图片质量要求和拍摄建议\n- **升级**：真伪查验引擎 `verify_engine.py`，真正对接国税总局/第三方平台\n- **升级**：审批引擎 `approval_engine.py`，真正获取Token并调用API\n- **升级**：安装脚本增加预检环节\n- **升级**：模板匹配支持PDF格式（需poppler）\n- **改进**：所有脚本增加更详细的错误提示\n- **改进**：配置文件中增加timeout设置\n\n### v1.0.0 (2026-06-28)\n- 初始版本发布\n- 支持增值税发票OCR识别\n- 支持多种查验引擎接口\n- 支持模板自适应学习\n- 支持多种审批平台对接\n\n## 税务风险预警\n\n本模块提供发票数据的风险检测功能，帮助企业在税务稽查前自查风险。\n\n### 检测方法\n\n| 检测项 | 说明 | 预警级别 |\n|--------|------|---------|\n| 连号检测 | 同一供应商连续开具多张连号发票 | 关注 |\n| 大额整数金额 | 发票金额为大额整数（如 100000.00 元） | 提示 |\n| 频繁开票 | 短时间内同一供应商开具大量发票 | 关注 |\n| 品名异常 | 发票品名与供应商经营范围不符 | 关注 |\n| 进销项匹配 | 进项发票品名与销项发票品名匹配度低 | 严重 |\n\n### 三级预警体系\n\n| 级别 | 说明 | 建议操作 |\n|------|------|---------|\n| 提示 | 低风险，可能存在异常 | 建议关注 |\n| 关注 | 中风险，需要核实 | 建议核实业务真实性 |\n| 严重 | 高风险，可能涉及虚开 | 建议立即处理 |\n\n### 使用方式\n\n```bash\npython scripts/risk_detector.py <path_to_invoices_json>\n```\n\n输出 JSON 格式的风险检测报告，包含所有检测结果和综合评估。\n\n## 电子档案合规归档\n\n本模块按照《电子发票全流程电子化管理指南》生成标准归档包，满足财政部和国家档案局对电子发票归档的要求。\n\n### 四性检测\n\n| 检测项 | 说明 |\n|--------|------|\n| 真实性 | 检测电子发票是否为原始真实文件，未经篡改 |\n| 完整性 | 检测电子发票文件是否完整，未损坏或缺失 |\n| 可用性 | 检测电子发票文件是否能正常打开、读取和使用 |\n| 安全性 | 检测电子发票文件是否安全，未被篡改或感染 |\n\n### 使用方式\n\n**单个文件四性检测**：\n```bash\npython scripts/archive_manager.py <path_to_invoice_file>\n```\n\n**批量归档（目录）**：\n```bash\npython scripts/archive_manager.py <path_to_directory>\n```\n\n**生成归档包**：\n```python\nfrom scripts.archive_manager import create_archive\npackage = create_archive([\"invoice1.pdf\", \"invoice2.xml\"], \"./output\")\n```\n\n### 归档包结构\n\n```\narchive_20260805_120000.zip\n├── metadata.json          # 元数据总表\n├── four_properties.json   # 四性检测报告\n├── invoice_data.json      # 结构化发票数据\n├── invoices/              # 原始发票文件\n│   ├── invoice_001.pdf\n│   └── invoice_002.xml\n└── README.txt             # 归档说明\n```\n\n## 银行流水对账\n\n本模块提供银行流水与发票数据的自动对账功能，解决财务人员手工核对耗时费力的痛点。\n\n### 支持的银行格式\n\n| 银行 | CSV 编码 | 日期格式 | 金额格式 | 状态 |\n|------|---------|---------|---------|------|\n| 工商银行 | UTF-8/GBK | YYYY-MM-DD | 借贷分离列 | ✅ 测试通过 |\n| 建设银行 | UTF-8/GBK | YYYY-MM-DD | 借贷分离列 | ✅ 测试通过 |\n| 农业银行 | UTF-8/GBK | YYYY/MM/DD | 借贷分离列 | ✅ 测试通过 |\n| 招商银行 | UTF-8 | YYYY-MM-DD | 正负金额列 | ✅ 测试通过 |\n| 中信银行 | UTF-8 | YYYY-MM-DD | 借贷分离列 | ✅ 测试通过 |\n| 其他银行 | 自动检测 | 自动识别 | 自动解析 | ✅ 自适应 |\n\n### 匹配算法\n\n| 维度 | 规则 | 权重 |\n|------|------|------|\n| 金额匹配 | ±0.01 元容差，超出后线性递减 | 60% |\n| 日期匹配 | ±3 天容差，超出后线性递减（30 天降为 0） | 40% |\n| 综合评分 | 金额分 × 0.6 + 日期分 × 0.4 | ≥0.85 视为匹配 |\n\n### 使用方式\n\n```bash\n# 基本对账\npython scripts/bank_reconciler.py --csv bank_statement.csv --invoices invoices.json\n\n# 自定义容差\npython scripts/bank_reconciler.py --csv bank.csv --invoices inv.json --amount-tol 0.05 --date-tol 5\n\n# 输出报告\npython scripts/bank_reconciler.py --csv bank.csv --invoices inv.json --output report.json\n```\n\n### 输出报告结构\n\n```json\n{\n  \"summary\": {\n    \"total_transactions\": 150,\n    \"matched\": 138,\n    \"unmatched\": 12,\n    \"match_rate\": \"92.0%\",\n    \"total_matched_amount\": 85642.50,\n    \"total_unmatched_amount\": 12350.00\n  },\n  \"unmatched_by_amount_range\": {\n    \"小额（<1000）\": 5,\n    \"中额（1000-10000）\": 4,\n    \"大额（10000-50000）\": 2,\n    \"超大额（≥50000）\": 1\n  }\n}\n```\n\n## 安全密钥配置\n\n本模块提供统一的密钥安全管理，消除配置文件中的明文泄露风险。\n\n### 环境变量命名规范\n\n| 密钥用途 | 环境变量名 | 示例 |\n|---------|-----------|------|\n| 钉钉 AppKey | `INVOICE_DINGTALK_APPKEY` | dik123xxx |\n| 钉钉 Secret | `INVOICE_DINGTALK_SECRET` | abc123xxx |\n| 企微 CorpID | `INVOICE_WECOM_CORP_ID` | wwxxxx |\n| 企微 Secret | `INVOICE_WECOM_SECRET` | abcxxxx |\n| 飞书 AppID | `INVOICE_FEISHU_APP_ID` | cli_xxx |\n| 飞书 Secret | `INVOICE_FEISHU_APP_SECRET` | abcxxx |\n| 百望云 API Key | `INVOICE_BAIRONG_API_KEY` | br_xxx |\n| 百望云 Secret | `INVOICE_BAIRONG_API_SECRET` | abcxxx |\n| 诺诺 API Key | `INVOICE_NUONUO_API_KEY` | nn_xxx |\n| 诺诺 Secret | `INVOICE_NUONUO_API_SECRET` | abcxxx |\n\n### 设置方式\n\n**Windows PowerShell（临时）**：\n```powershell\n$env:INVOICE_DINGTALK_APPKEY = \"你的AppKey\"\n$env:INVOICE_DINGTALK_SECRET = \"你的Secret\"\n```\n\n**Windows（永久，系统环境变量）**：\n```powershell\n[System.Environment]::SetEnvironmentVariable(\"INVOICE_DINGTALK_APPKEY\", \"你的AppKey\", \"User\")\n```\n\n**Linux/macOS**：\n```bash\nexport INVOICE_DINGTALK_APPKEY=\"你的AppKey\"\nexport INVOICE_DINGTALK_SECRET=\"你的Secret\"\n```\n\n### 使用方式\n\n```python\nfrom scripts.secure_config import SecureConfig\n\ncfg = SecureConfig()\n\n# 获取单个密钥\napp_key = cfg.get(\"DINGTALK_APPKEY\")\n\n# 获取平台完整配置\ndingtalk_cfg = cfg.get_dingtalk_config()\n\n# 调用 API 前校验\nresult = cfg.validate_before_call(\"dingtalk\")\nif result[\"ready\"]:\n    # 安全调用 API\n    pass\nelse:\n    print(f\"缺失配置: {result['missing']}\")\n```\n\n### CLI 检查\n\n```bash\n# 检查所有平台（默认输出字段名和布尔状态，不输出密钥值）\npython scripts/secure_config.py --platform all\n\n# 检查单个平台\npython scripts/secure_config.py --platform dingtalk\n\n# JSON 输出\npython scripts/secure_config.py --platform all --json\n```\n\n## 并行批量处理\n\n本模块提供硬件自适应的并行批量处理能力，自动根据 CPU 核心数和可用内存动态调整 worker 数量。\n\n### 硬件自适应策略\n\n| 硬件条件 | 处理模式 | Worker 数量 |\n|---------|---------|------------|\n| CPU ≥ 4 核 + 内存 > 2GB | 多进程 | CPU × 0.5 |\n| CPU 2-3 核 或 内存 1-2GB | 多线程 | CPU × 0.75 |\n| 内存 < 1GB | 串行 | 1 |\n\n### 使用方式\n\n**命令行使用**：\n```bash\n# 查看硬件信息和推荐配置\npython scripts/parallel_batch.py info\n\n# 自动模式批量处理\npython scripts/parallel_batch.py run --input D:\\invoices\\ --output result.json\n\n# 指定模式\npython scripts/parallel_batch.py run --input D:\\invoices\\ --output result.json --mode process\n```\n\n**Python 代码调用**：\n```python\nfrom scripts.parallel_batch import batch_process, get_hardware_info\n\n# 查看硬件信息\nhw = get_hardware_info()\nprint(f\"CPU: {hw['cpu_count']} 核, 推荐 worker: {hw['recommended_workers_process']}\")\n\n# 定义处理函数\ndef process_invoice(file_path: str) -> dict:\n    # 自定义处理逻辑\n    return {\"success\": True, \"file\": file_path}\n\n# 批量处理\nresult = batch_process(file_paths, process_invoice, mode=\"auto\")\nprint(f\"处理 {result.total_files} 个文件，成功 {result.success_count} 个\")\nprint(f\"耗时 {result.total_time_seconds:.1f} 秒，吞吐量 {result.to_dict()['throughput_per_second']} 个/秒\")\n```\n\n### 性能对比（参考）\n\n| 文件数 | 串行处理 | 并行处理（4核） | 加速比 |\n|--------|---------|---------------|--------|\n| 10 张 | 28 秒 | 8 秒 | 3.5× |\n| 50 张 | 140 秒 | 38 秒 | 3.7× |\n| 100 张 | 280 秒 | 75 秒 | 3.7× |\n| 200 张 | 560 秒 | 148 秒 | 3.8× |\n\n> 注：以上数据为 i5-10400F/16GB 测试环境参考值，实际加速比取决于 CPU 性能、内存大小和图片分辨率。\n\n## 免责声明\n\n本工具仅提供发票识别和报销单生成的技术支持，**不提供任何税务咨询或财务建议**。所有财务决策应由专业财务人员做出。使用者需确保符合当地法律法规。使用本工具即表示接受《风险声明》中的全部条款。\n\nFile v4.3.0:_meta.json\n\n{\n  \"ownerId\": \"kn7chdrwbdhaqkwajcyhtfvjx989ddb1\",\n  \"slug\": \"receipt-compliance\",\n  \"version\": \"4.3.0\",\n  \"publishedAt\": 1787576579556\n}\n\nFile v4.3.0:references/account_mapping.md\n\n# 会计科目对照表\n\n本文件定义了发票费用类型与会计科目的映射关系，用于自动生成记账凭证。\n\n## 借方科目（费用类）\n\n| 费用类型 | 科目代码 | 科目名称 | 说明 |\n|---------|---------|---------|------|\n| 差旅费 | 6602.01 | 管理费用-差旅费 | 员工出差交通、住宿、餐饮等 |\n| 办公费 | 6602.02 | 管理费用-办公费 | 办公用品、耗材、打印等 |\n| 业务招待费 | 6602.03 | 管理费用-业务招待费 | 餐饮、礼品等招待支出 |\n| 广告费 | 6601.01 | 销售费用-广告费 | 广告投放、品牌推广 |\n| 咨询费 | 6602.04 | 管理费用-咨询费 | 法律、审计、税务等顾问 |\n| 交通费 | 6602.05 | 管理费用-交通费 | 市内打车、公交、地铁 |\n| 通行费 | 6602.06 | 管理费用-通行费 | 高速、桥闸通行费 |\n| 福利费 | 6602.07 | 管理费用-福利费 | 员工体检、节日福利 |\n| 租赁费 | 6602.08 | 管理费用-租赁费 | 房租、物业费 |\n| 维修费 | 6602.09 | 管理费用-维修费 | 设备维修保养 |\n| 其他费用 | 6602.99 | 管理费用-其他 | 其他杂项支出 |\n\n## 借方科目（税费类）\n\n| 科目代码 | 科目名称 | 说明 |\n|---------|---------|------|\n| 2221.01 | 应交税费-应交增值税-进项税额 | 可抵扣进项税 |\n\n## 贷方科目（支付类）\n\n| 科目代码 | 科目名称 | 说明 |\n|---------|---------|------|\n| 1002 | 银行存款 | 默认支付方式 |\n| 1002.01 | 银行存款-转账 | 银行转账 |\n| 1001 | 库存现金 | 现金支付 |\n\n## 进项税抵扣率\n\n| 票据类型 | 抵扣率 | 说明 |\n|---------|--------|------|\n| 火车票 | 9% | 按票面金额计算抵扣 |\n| 飞机票 | 9% | 票价+燃油费，不含民航发展基金 |\n| 高速通行费 | 3% | 按通行费计算抵扣 |\n| 桥闸通行费 | 5% | 按通行费计算抵扣 |\n| 增值税专票（13%） | 13% | 按票面税额抵扣 |\n| 增值税专票（6%） | 6% | 按票面税额抵扣 |\n| 增值税专票（3%） | 3% | 按票面税额抵扣 |\n| 增值税普票 | 0% | 不可抵扣 |\n| 定额发票 | 0% | 不可抵扣 |\n| 财政票据 | 0% | 不可抵扣 |\n\nFile v4.3.0:references/api-endpoints.md\n\n# API 端点说明\n\n本文档列出各平台API的接入方式和注意事项。\n\n---\n\n## 一、查验平台 API\n\n### 1.1 国税总局查验平台\n\n- **网址**: https://inv-veri.chinatax.gov.cn/\n- **接口类型**: HTTP表单提交（需要处理验证码）\n- **是否免费**: ✓ 完全免费\n- **接入难度**: ★★★（需要处理验证码和反爬机制）\n- **建议**: 仅在用户明确授权下发起单条查验请求，控制频率\n\n### 1.2 百望云 API\n\n- **网址**: https://www.bairong.com\n- **接口类型**: RESTful API\n- **认证方式**: API Key + Secret\n- **是否免费**: ✗ 按量付费或包年\n- **接入难度**: ★★☆（企业资质申请偏难）\n\n### 1.3 诺诺发票 API\n\n- **网址**: https://www.nuonuo.com\n- **接口类型**: RESTful API\n- **认证方式**: API Key + Secret\n- **是否免费**: ✗ 按量付费或包年\n- **接入难度**: ★★☆（接口文档齐全）\n\n---\n\n## 二、审批平台 API\n\n### 2.1 钉钉审批\n\n- **网址**: https://open-dev.dingtalk.com\n- **审批API**: 钉钉开放平台 → 审批 → 流程引擎\n- **认证方式**: AppKey + AppSecret → OAuth2.0 Token\n- **接入步骤**:\n  1. 创建企业内部应用\n  2. 开通审批权限\n  3. 创建审批流程模板\n  4. 获取流程编码\n\n### 2.2 企业微信审批\n\n- **网址**: https://developer.weixin.qq.com\n- **审批API**: 企业微信 → 审批 → 模板管理\n- **认证方式**: CorpID + Secret → AccessToken\n- **接入步骤**:\n  1. 注册企业微信管理后台\n  2. 创建审批模板\n  3. 获取模板ID和审批字段\n\n### 2.3 飞书审批\n\n- **网址**: https://open.feishu.cn\n- **审批API**: 飞书开放平台 → 审批 → 审批实例\n- **认证方式**: App ID + App Secret → Tenant Access Token\n- **接入步骤**:\n  1. 创建企业自建应用\n  2. 开通审批权限\n  3. 获取审批编码\n\n---\n\n## 三、API 调用示例\n\n### 3.1 钉钉审批提交示例（伪代码）\n\n```python\n# 获取钉钉 AccessToken\ndef get_dingtalk_token(app_key, app_secret):\n    url = \"https://api.dingtalk.com/v1.0/oauth2/accessToken\"\n    payload = {\"appKey\": app_key, \"appSecret\": app_secret}\n    # ...\n\n# 提交审批\ndef submit_dingtalk_approval(token, process_code, formData):\n    url = f\"https://api.dingtalk.com/v1.0/approval/processInstances\"\n    # ...\n```\n\n### 3.2 企业微信审批提交示例（伪代码）\n\n```python\n# 获取企业微信 AccessToken\ndef get_wecom_token(corp_id, secret):\n    url = f\"https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid={corp_id}&corpsecret={secret}\"\n    # ...\n\n# 提交审批\ndef submit_wecom_approval(token, template_id, apply_data):\n    url = f\"https://qyapi.weixin.qq.com/cgi-bin/approval/submit?access_token={token}\"\n    # ...\n```\n\n---\n\n## 四、安全建议\n\n1. **API密钥分散存储**：不同平台使用不同密钥，避免一损俱损\n2. **调用频率限制**：建议每分钟不超过10次查验/审批请求\n3. **错误重试机制**：失败时自动重试最多3次，指数退避\n4. **日志审计**：记录所有API调用，便于追踪和审计\n\n---\n\n## 五、接口调用频率限制\n\n| 平台 | 建议最低间隔 | 日调用上限建议 |\n|------|-------------|---------------|\n| 国税总局 | 无官方限制 | 建议 ≤ 1000次/日 |\n| 百望云 | 按套餐而定 | 查看服务协议 |\n| 诺诺发票 | 按套餐而定 | 查看服务协议 |\n| 钉钉审批 | 无官方限制 | 建议 ≤ 1000次/日 |\n| 企业微信审批 | 无官方限制 | 建议 ≤ 500次/日 |\n| 飞书审批 | 无官方限制 | 建议 ≤ 1000次/日 |\n\n> 以上限制仅供参考，请以各平台官方文档为准。\n\nFile v4.3.0:references/expense_rules.md\n\n# 费用分类规则\n\n本文件定义了根据发票/票据内容自动匹配费用类型的规则。\n\n## 关键词匹配规则\n\n| 费用类型 | 触发关键词 |\n|---------|-----------|\n| 差旅费 | 酒店、住宿、机票、火车票、高铁、动车、打车、出租车、滴滴 |\n| 办公费 | 办公用品、文具、打印、复印、耗材、电脑、鼠标、键盘 |\n| 业务招待费 | 餐饮、食品、招待、餐厅、饭店、酒楼 |\n| 广告费 | 广告、推广、宣传、营销、品牌、投放 |\n| 咨询费 | 咨询、顾问、法律、审计、税务代理 |\n| 交通费 | 打车、出租车、滴滴、公交、地铁 |\n| 通行费 | 通行费、高速、桥闸、过路费 |\n| 福利费 | 福利、员工、生日、节日、体检 |\n| 租赁费 | 租赁、房租、物业、水电 |\n| 维修费 | 维修、修理、维护、保养 |\n\n## 按票据类型直接分类\n\n| 票据类型 | 默认费用类型 |\n|---------|-------------|\n| 火车票 | 差旅费 |\n| 飞机行程单 | 差旅费 |\n| 出租车票 | 交通费 |\n| 通行费票据 | 通行费 |\n| 财政票据 | 财政票据（不可抵扣） |\n\nFile v4.3.0:references/risk_rules_config.yaml\n\n# 风险检测规则配置文件\n# 可根据最新税务稽查重点动态更新\n\nversion: \"1.0\"\nlast_updated: \"2026-08-05\"\n\n# 连号检测配置\nconsecutive_number_check:\n  enabled: true\n  threshold: 3  # 同一供应商连续 N 张发票触发\n\n# 大额整数金额检测\nround_amount_check:\n  enabled: true\n  threshold: 10000  # 金额 >= 此值\n  min_digits: 5     # 整数位数 >= 此值\n\n# 频繁开票检测\nfrequent_invoicing_check:\n  enabled: true\n  threshold: 10    # N 天内开具 M 张\n  window_days: 30  # 时间窗口（天）\n\n# 品名异常检测\nscope_anomaly_check:\n  enabled: true\n  # 是否使用外部企业信息API\n  use_external_api: false\n  # 内置行业关键词表\n  scope_keywords:\n    餐饮: [餐饮, 饭店, 酒楼, 餐厅, 食品]\n    技术服务: [技术, 软件, 信息, 网络, 科技]\n    建筑: [建筑, 工程, 施工, 装修, 建材]\n    零售: [百货, 超市, 零售, 商店, 商贸]\n    运输: [运输, 物流, 快递, 货运]\n\n# 进销项匹配检测\ninput_output_match_check:\n  enabled: true\n  similarity_threshold: 0.1  # Jaccard 相似度低于此值触发\n\n# 预警级别定义\nrisk_levels:\n  提示:\n    priority: 1\n    action: 建议关注\n  关注:\n    priority: 2\n    action: 建议核实\n  严重:\n    priority: 3\n    action: 建议立即处理\n\nFile v4.3.0:references/risk-declaration.md\n\n# 风险声明\n\n使用本Skill前，请仔细阅读以下风险声明。使用本Skill即表示您接受全部条款。\n\n---\n\n## 一、数据安全责任\n\n### 1.1 用户责任\n\n- **所有发票数据仅在用户本地设备处理**，但用户需自行确保本地设备的安全\n- 用户需自行负责API密钥的安全保管，不得泄露给第三方\n- 用户需定期轮换API密钥，建议每90天更换一次\n- 用户需妥善保管发票图片，防止数据泄露\n\n### 1.2 Skill开发者责任\n\n- Skill开发者已尽最大努力确保代码安全透明\n- Skill不包含任何后门、恶意代码或未经授权的数据传输\n- Skill开发者不对用户因使用或无法使用本Skill而遭受的损失承担责任\n\n### 1.3 第三方服务风险\n\n- Skill可能调用第三方API（如查验平台、审批系统）\n- 第三方服务的安全性和可用性由第三方负责\n- 用户需自行评估第三方服务的风险\n\n---\n\n## 二、查验结果免责声明\n\n### 2.1 结果准确性\n\n- 查验引擎的返回结果由第三方平台提供\n- Skill仅提供技术对接，**不对查验结果的准确性负责**\n- 如对查验结果有疑问，请直接联系相关税务平台\n- 查验频率受限于各平台规则，Skill不对此负责\n\n### 2.2 法律后果\n\n- 使用假发票或虚开发票的法律后果由用户自行承担\n- Skill不参与、不鼓励任何违法行为\n- 用户需确保其行为符合当地法律法规\n\n---\n\n## 三、审批操作责任\n\n### 3.1 操作风险\n\n- 审批提交后不可撤销（以各平台规则为准）\n- Skill不审批内容的合规性和真实性\n- 用户对提交的报销单内容负全部责任\n- 建议在提交前进行人工复核\n\n### 3.2 审批失败\n\n- Skill不对审批结果负责\n- 审批失败可能由多种原因导致（权限不足、流程变更、数据格式等）\n- 用户需自行联系审批平台解决审批问题\n\n---\n\n## 四、财务合规要求\n\n### 4.1 一般要求\n\n- 本工具仅为技术支持工具，**不提供税务咨询或财务建议**\n- 所有财务决策应由专业财务人员做出\n- 使用者需确保符合当地税务法规和会计准则\n- 如需专业税务意见，请咨询持牌税务顾问\n\n### 4.2 禁止行为\n\n使用本Skill，用户不得：\n\n- 伪造、变造发票\n- 使用假发票报销\n- 虚增报销金额\n- 报销与业务无关的费用\n- 进行任何违反财务法规的行为\n\n---\n\n## 五、软件使用限制\n\n### 5.1 合法使用\n\n- 本Skill仅供合法合规的财务报销用途\n- 禁止用于任何非法目的\n- 开发者保留追究滥用行为的权利\n\n### 5.2 责任限制\n\n- 在法律允许的最大范围内，开发者不提供任何明示或暗示的担保\n- 开发者不对任何间接、附带、特殊或后果性损害承担责任\n- 用户的唯一救济方式是停止使用本Skill\n\n---\n\n## 六、企业自主决策清单\n\n使用本Skill前，企业需自行决定以下事项：\n\n| 决策项 | 企业需自行决定 |\n|--------|---------------|\n| 查验引擎选择 | □ 国税总局平台（免费） □ 百望云 □ 诺诺发票 □ 自建接口 |\n| 审批平台选择 | □ 钉钉 □ 企业微信 □ 飞书 □ 自建系统 |\n| API密钥管理 | □ 密钥存储方式 □ 轮换周期 □ 权限范围 |\n| 数据安全策略 | □ 临时文件清理频率 □ 日志保留期限 □ 访问控制 |\n| 合规审查 | □ 内部合规审查 □ 外部审计 □ 持续监控 |\n\n---\n\n## 七、隐私保护\n\n### 7.1 数据收集\n\n- Skill不收集用户的个人身份信息\n- Skill不存储用户的发票数据\n- Skill不追踪用户的使用行为\n\n### 7.2 数据处理\n\n- 所有发票数据仅在用户本地处理\n- 不会上传到任何服务器\n- 处理完成后自动清理临时文件\n\n### 7.3 数据共享\n\n- Skill不会与任何第三方共享用户数据\n- 除非用户明确授权或法律法规要求\n\n---\n\n## 八、免责声明更新\n\n- 本免责声明可能会不定期更新\n- 更新后继续使用本Skill即表示接受新条款\n- 请定期查看本文件以了解最新条款\n\n---\n\n## 九、联系方式\n\n如有疑问或建议，请通过以下方式联系：\n\n- SkillHub平台: https://skillhub.cn\n- GitHub Issues: 提交问题和建议\n\n---\n\n**使用本Skill即表示您已阅读、理解并接受以上全部风险声明。**\n\nFile v4.3.0:references/setup-guide.md\n\n# 企业接入指南\n\n本文档说明如何将财税合规全链路Skill接入您的企业系统。\n\n---\n\n## 一、接入前准备\n\n### 1.1 环境要求\n\n| 要求项 | 说明 |\n|--------|------|\n| 操作系统 | Windows 10+, macOS 10.15+, Linux (Ubuntu 18.04+) |\n| Python | 3.8 或更高版本 |\n| Tesseract | 5.x 版本，需安装中文语言包 |\n| 磁盘空间 | 至少 500MB（含Tesseract语言数据） |\n| 内存 | 建议 4GB 以上 |\n\n### 1.2 安装步骤\n\n详见 `scripts/install_tesseract.sh`（Linux/macOS）或 `scripts/install_tesseract.ps1`（Windows）。\n\n---\n\n## 二、企业自主配置\n\n### 2.1 配置文件结构\n\n Skill不提供任何默认密钥，所有配置由企业自主填写：\n\n```yaml\n# config.yaml\n\n# ==================== 查验引擎配置 ====================\nverify_engine: \"tax_bureau\"\n# 可选值:\n# - \"tax_bureau\": 国税总局查验平台（免费，无需API Key）\n# - \"bairong\": 百望云API（需企业自行申请）\n# - \"nuonuo\": 诺诺发票API（需企业自行申请）\n# - \"custom\": 企业自建接口（需提供接口地址）\n# - \"none\": 不启用查验功能\n\n# ==================== 审批平台配置 ====================\napproval:\n  platform: \"none\"\n  # 可选值:\n  # - \"dingtalk\": 钉钉审批\n  # - \"wecom\": 企业微信审批\n  # - \"feishu\": 飞书审批\n  # - \"custom\": 企业自建审批系统\n  # - \"none\": 不启用审批对接\n```\n\n### 2.2 引擎配置详解\n\n#### 国税总局查验平台（推荐免费方案）\n\n```yaml\nverify_engine: \"tax_bureau\"\n```\n\n优点：\n- 完全免费\n- 官方权威数据\n- 无需申请API Key\n\n缺点：\n- 需要手动访问网站查验\n- Skill提供链接跳转，企业自行操作\n\n#### 百望云API\n\n```yaml\nverify_engine: \"bairong\"\n\nbairong:\n  api_key: \"在此填写您的百望云API Key\"\n  api_secret: \"在此填写您的百望云Secret\"\n```\n\n申请步骤：\n1. 访问 https://www.bairong.com\n2. 注册企业账号\n3. 申请API接入权限\n4. 获取API Key和Secret\n\n#### 钉钉审批\n\n```yaml\napproval:\n  platform: \"dingtalk\"\n  \n  dingtalk:\n    app_key: \"应用的AppKey\"\n    app_secret: \"应用的AppSecret\"\n    process_code: \"审批流程编码\"\n```\n\n申请步骤：\n1. 登录 https://open-dev.dingtalk.com\n2. 创建企业内部应用\n3. 开通审批权限\n4. 获取AppKey和AppSecret\n5. 创建审批流程并获取编码\n\n---\n\n## 三、报销单模板配置\n\n### 3.1 模板要求\n\n- 格式：Excel (.xlsx)\n- 第一行为表头（字段名）\n- 使用中文字段名\n- 支持多Sheet，但仅识别第一个\n\n### 3.2 字段映射\n\n首次使用时，Skill自动识别字段映射关系：\n\n```yaml\ntemplate:\n  path: \"您的报销单模板.xlsx\"\n  field_mapping:\n    invoice_date: \"开票日期\"      # 发票字段 → 模板列名\n    seller_name: \"销方名称\"\n    amount: \"金额（不含税）\"\n    tax_amount: \"税额\"\n    total: \"价税合计\"\n    remark: \"费用说明\"\n```\n\n企业可手动调整映射关系，后续自动学习保存。\n\n---\n\n## 四、安全配置\n\n### 4.1 API密钥管理\n\n| 密钥类型 | 存储方式 | 安全等级 |\n|----------|----------|----------|\n| 配置文件 | config.yaml | ⚠️ 中等（建议设置文件权限） |\n| 环境变量 | INVOICE_API_KEY 等 | ✅ 推荐 |\n| 密钥管理系统 | AWS KMS / Azure Key Vault | ✅✅ 高安全 |\n\n**推荐做法**：\n\n```bash\n# macOS/Linux（在 ~/.bashrc 或 ~/.zshrc 中）\nexport INVOICE_OCR_KEY=\"your-key-here\"\n\n# Windows（PowerShell）\n$env:INVOICE_OCR_KEY=\"your-key-here\"\n```\n\n### 4.2 数据安全策略\n\n建议企业配置：\n\n| 策略项 | 建议值 |\n|--------|--------|\n| 临时文件清理 | 每次操作后自动清理 |\n| 日志保留期限 | 30天 |\n| API密钥轮换 | 每90天 |\n| 访问控制 | 仅财务人员可执行 |\n| 数据备份 | 仅备份映射配置，不备份发票图片 |\n\n---\n\n## 五、运维与监控\n\n### 5.1 日常操作\n\n```bash\n# 日常识别\npython scripts/ocr_engine.py --input /path/to/invoice.png --output /tmp/receipt.json\n\n# 批量处理\npython scripts/ocr_engine.py --input /path/to/invoices_dir/ --output /tmp/batch_results.json\n\n# 模板填充\npython scripts/template_matcher.py fill --config config.yaml --receipt /tmp/receipt.json --template templates/报销单.xlsx\n```\n\n### 5.2 监控要点\n\n| 监控项 | 方法 |\n|--------|------|\n| Tesseract版本 | `tesseract --version` |\n| API调用频率 | 查看日志文件 |\n| 识别准确率 | 抽样对比人工结果 |\n| 错误率 | 监控error.log |\n| 磁盘空间 | 监控临时文件目录 |\n\n---\n\n## 六、常见问题\n\n### Q1: Tesseract安装失败？\n- 确认操作系统版本符合要求\n- 确认下载了正确的语言包（chi_sim）\n- Windows用户需将Tesseract路径加入系统PATH\n\n### Q2: 识别准确率不高？\n- 确保发票图片清晰（300DPI以上）\n- 确保光线均匀、无反光\n- 可尝试调整预处理参数\n- 考虑升级Tesseract版本\n\n### Q3: 查验接口返回失败？\n- 检查API Key是否正确\n- 检查网络是否可访问\n- 检查是否超出调用频率限制\n\n### Q4: 模板匹配不准确？\n- 确认模板第一行为表头\n- 确认使用中文字段名\n- 手动匹配后Skill会学习并记住\n\n---\n\n## 七、合规建议\n\n1. **法规遵从**：确保发票管理符合《中华人民共和国发票管理办法》\n2. **内部控制**：建立适当的审批流程，防止滥用\n3. **审计追踪**：保留操作日志，便于内部审计\n4. **定期审查**：定期检查API权限和使用情况\n5. **员工培训**：确保操作人员了解财务合规要求\n\n---\n\n## 八、获取帮助\n\n- GitHub Issues: 提交问题和建议\n- SkillHub文档: https://skillhub.cn/docs\n- 邮箱: 联系Skill开发者\n\nFile v4.3.0:references/supplier_scope_rules.md\n\n# 企业经营范围对照表（品名异常检测）\n\n本文件定义了常见行业的经营范围关键词，用于检测发票品名与供应商经营范围是否匹配。\n\n## 行业分类与关键词\n\n### 餐饮服务\n- **行业关键词**：餐饮、饭店、酒楼、餐厅、食品、小吃、面包、饮品\n- **正常品名**：餐饮服务、食品、酒水、餐饮费\n- **异常品名**：技术服务、软件开发、建筑工程、医疗器械\n\n### 信息技术服务\n- **行业关键词**：技术、软件、信息、网络、科技、互联网、数据\n- **正常品名**：技术服务、软件开发、系统集成、技术咨询\n- **异常品名**：餐饮服务、食品、建筑工程\n\n### 建筑工程\n- **行业关键词**：建筑、工程、施工、装修、建材、装饰\n- **正常品名**：建筑服务、工程款、建材、装修费\n- **异常品名**：餐饮服务、软件开发、医疗器械\n\n### 零售商贸\n- **行业关键词**：百货、超市、零售、商店、商贸、贸易\n- **正常品名**：办公用品、日用百货、劳保用品\n- **异常品名**：建筑工程、技术服务（需核实）\n\n### 物流运输\n- **行业关键词**：运输、物流、快递、货运、客运\n- **正常品名**：运输服务、物流费、快递费\n- **异常品名**：餐饮服务、建筑工程\n\n## 品名异常检测规则\n\n1. 根据销售方名称推断行业类别\n2. 检查发票品名/商品名称是否与行业类别匹配\n3. 如发现异常，生成风险预警\n\n## 扩展建议\n\n- 可对接国家企业信用信息公示系统 API，获取企业真实经营范围\n- 可基于历史开票数据建立供应商行为基线\n\nFile v4.3.0:references/tax-rules.md\n\n# 税务规则说明\n\n本文档说明Skill涉及的税务规则和合规要求。\n\n---\n\n## 一、发票类型说明\n\n### 1.1 增值税专用发票\n\n| 项目 | 说明 |\n|------|------|\n| 定义 | 增值税一般纳税人销售货物或者提供应税劳务开具的发票 |\n| 税率 | 13%、9%、6%、3%、1%、0% |\n| 抵扣 | 可用于进项税额抵扣 |\n| 代码位数 | 10位或12位 |\n| 号码位数 | 8位 |\n\n### 1.2 增值税普通发票\n\n| 项目 | 说明 |\n|------|------|\n| 定义 | 增值税一般纳税人或小规模纳税人开具的普通发票 |\n| 税率 | 13%、9%、6%、3%、1%、0% |\n| 抵扣 | 不可用于进项税额抵扣（特殊情况除外） |\n| 代码位数 | 10位或12位 |\n| 号码位数 | 8位 |\n\n### 1.3 增值税电子发票\n\n| 项目 | 说明 |\n|------|------|\n| 定义 | 增值税发票的电子形式 |\n| 税率 | 同纸质发票 |\n| 抵扣 | 可用于进项税额抵扣 |\n| 法律效力 | 与纸质发票具有同等法律效力 |\n| 存储 | 需保存电子文件备查 |\n\n---\n\n## 二、税率表\n\n### 2.1 现行增值税税率\n\n| 税率 | 适用范围 |\n|------|----------|\n| 13% | 销售货物、加工修理修配劳务、有形动产租赁、进口货物（一般货物） |\n| 9% | 农产品、交通运输、邮政、基础电信、建筑、不动产租赁、销售不动产、土地使用权转让 |\n| 6% | 金融、现代服务、生活服务、增值电信、销售无形资产 |\n| 3% | 小规模纳税人简易计税 |\n| 1% | 小规模纳税人疫情期间优惠（政策执行期以官方公告为准） |\n| 0% | 出口货物、跨境应税服务 |\n\n### 2.2 常见货物税率\n\n| 货物名称 | 税率 |\n|----------|------|\n| 食品、农产品 | 9% |\n| 图书、报纸、杂志 | 9% |\n| 电子出版物 | 9% |\n| 饲料、化肥、农药 | 9% |\n| 自来水、暖气、冷气 | 9% |\n| 热水、煤气 | 9% |\n| 石油液化气、天然气 | 9% |\n| 煤炭制品 | 9% |\n| 金属矿采选产品 | 9% |\n| 非金属矿采选产品 | 9% |\n| 计算机、机器设备 | 13% |\n| 服装、鞋帽 | 13% |\n| 食品（加工后） | 13% |\n\n---\n\n## 三、发票管理规范\n\n### 3.1 发票开具要求\n\n根据《中华人民共和国发票管理办法》：\n\n- 发票内容必须真实、准确\n- 发票必须按照规定的时限、顺序、栏目开具\n- 发票必须加盖发票专用章\n- 不得虚开发票\n- 不得转借、转让发票\n- 不得代开发票\n\n### 3.2 发票保管要求\n\n- 发票存根联应当保存5年\n- 发票登记簿应当保存5年\n- 已开具的发票存根联和发票登记簿，保存期满后需报经税务机关查验后销毁\n- 电子发票需保存电子文件\n\n### 3.3 发票查验要求\n\n- 企业应定期查验发票真伪\n- 发现假发票应及时向税务机关报告\n- 不得使用假发票入账\n- 已抵扣的进项税额，如发票被认定为异常，应作进项税额转出\n\n---\n\n## 四、报销合规要求\n\n### 4.1 报销凭证要求\n\n| 要求项 | 说明 |\n|--------|------|\n| 发票真实 | 发票必须真实有效 |\n| 内容完整 | 发票内容填写完整 |\n| 金额准确 | 报销金额与发票金额一致 |\n| 费用合理 | 费用发生与业务相关 |\n| 时限合规 | 在规定期限内报销 |\n\n### 4.2 常见不合规情况\n\n- 使用假发票报销\n- 虚增报销金额\n- 报销个人费用\n- 报销与业务无关的费用\n- 超期报销\n- 发票信息不完整\n\n### 4.3 风险防范措施\n\n- 建立发票查验制度\n- 定期培训财务人员\n- 建立举报机制\n- 定期内部审计\n- 使用技术手段辅助识别\n\n---\n\n## 五、税务风险提示\n\n### 5.1 发票相关风险\n\n| 风险类型 | 说明 | 后果 |\n|----------|------|------|\n| 假发票 | 使用伪造发票 | 补税、罚款、滞纳金 |\n| 虚开发票 | 无真实交易开具发票 | 补税、罚款、刑事责任 |\n| 代开发票 | 让他人代开发票 | 补税、罚款 |\n| 发票丢失 | 发票保管不善 | 无法税前扣除 |\n\n### 5.2 税务管理建议\n\n1. **建立制度**：制定发票管理和报销管理制度\n2. **培训人员**：定期培训财务人员\n3. **技术辅助**：使用发票查验工具\n4. **内部审计**：定期进行内部审计\n5. **外部审计**：必要时聘请外部审计机构\n\n---\n\n## 六、免责声明\n\n本文档仅提供一般性税务规则说明，不构成专业税务建议。具体税务处理请以当地税务机关规定为准。如有疑问，请咨询专业税务顾问。\n\n---\n\n## 七、参考法规\n\n- 《中华人民共和国发票管理办法》\n- 《中华人民共和国发票管理办法实施细则》\n- 《中华人民共和国增值税暂行条例》\n- 《中华人民共和国增值税暂行条例实施细则》\n- 《国家税务总局关于增值税发票开具有关问题的公告》\n\nFile v4.3.0:examples/example-approval.md\n\n# 示例3：对接企业审批系统\n\n## 场景\n企业已配置好想接入的审批平台（如钉钉/企业微信/飞书），并提供了API密钥和审批流程编码。\n\n## 前置条件\n企业需在 `config.yaml` 中配置审批平台信息：\n\n### 钉钉配置示例\n```yaml\napproval:\n  platform: \"dingtalk\"\n  dingtalk:\n    app_key: \"dingkingxxxxxxxxxx\"\n    app_secret: \"xxxxxxxxxxxxxxxxxxxxx\"\n    process_code: \"PROC-XXXXXXXXXXX\"\n```\n\n### 企业微信配置示例\n```yaml\napproval:\n  platform: \"wecom\"\n  wecom:\n    corp_id: \"wwxxxxxxxxxx\"\n    secret: \"xxxxxxxxxxxxxxxxxxxxx\"\n    template_id: \"CTL-XXXXXXXXXXX\"\n```\n\n### 飞书配置示例\n```yaml\napproval:\n  platform: \"feishu\"\n  feishu:\n    app_id: \"cli_xxxxxxxxxx\"\n    app_secret: \"xxxxxxxxxxxxxxxxxxxxx\"\n    approval_code: \"OC-XXXXXXXXXXX\"\n```\n\n## 输入\n```\n提交审批 D:\\output\\报销单_20260629.xlsx\n```\n\n## 处理步骤\n1. `approval_abstract.py` 读取配置文件中的审批平台设置\n2. 根据平台选择对应的审批引擎（钉钉/企业微信/飞书/自建）\n3. 检查API密钥和配置是否完整\n4. 如果配置完整，调用对应API提交审批\n5. 返回审批提交结果\n\n## 预期输出\n```json\n{\n  \"engine\": \"钉钉审批\",\n  \"status\": \"framework_ready\",\n  \"message\": \"企业需自行调用钉钉审批API实现提交逻辑\",\n  \"params\": {\n    \"app_key\": \"ding****\",\n    \"process_code\": \"PROC-XXXXXXXXXXX\",\n    \"expense_file\": \"D:\\\\output\\\\报销单_20260629.xlsx\"\n  },\n  \"reference_url\": \"https://open-dev.dingtalk.com/document\",\n  \"submit_time\": \"2026-06-29T00:15:41+08:00\"\n}\n```\n\n> **注意**：审批引擎目前为接口框架，企业需自行实现具体的API调用逻辑。\n\n## 未配置审批平台时\n```json\n{\n  \"engine\": \"手动提交\",\n  \"status\": \"manual_required\",\n  \"message\": \"审批系统未配置，请手动提交报销单\",\n  \"file_path\": \"D:\\\\output\\\\报销单_20260629.xlsx\",\n  \"submit_time\": \"2026-06-29T00:15:41+08:00\"\n}\n```\n\n## 命令\n```bash\n# 提交审批（需先配置审批平台）\npython scripts/approval_abstract.py --config config.yaml --expense D:\\output\\报销单_20260629.xlsx\n```\n\n## 风险提示\n- 审批提交后可能无法撤销，请确认报销单内容无误后再提交\n- API密钥请妥善保管，泄露风险由企业自行承担\n- Skill仅提供技术支持，不对审批结果承担责任\n\n## 企业自行实现清单\n企业需根据选择的审批平台，自行实现以下功能：\n\n| 平台 | 需实现的内容 |\n|------|-------------|\n| 钉钉 | OAuth2.0鉴权 → 获取AccessToken → 调用审批提交API |\n| 企业微信 | 获取Token → 构建审批数据 → 调用提交API |\n| 飞书 | 获取TenantToken → 构建审批表单 → 调用提交API |\n| 自建 | 按企业接口规范实现HTTP请求 |\n\nFile v4.3.0:examples/example-ocr.md\n\n# 示例1：单张发票OCR识别\n\n## 场景\n用户有一张增值税专用发票，需要识别并提取结构化数据。\n\n## 输入\n```\n识别发票 D:\\invoices\\20260628_001.png\n```\n\n## 处理步骤\n1. `ocr_engine.py` 读取图片\n2. 图像预处理（灰度化 → 去噪 → 二值化 → 纠偏）\n3. Tesseract OCR 提取文字\n4. 正则匹配提取关键字段\n5. 输出结构化JSON\n\n## 预期输出\n```json\n{\n  \"success\": true,\n  \"invoice_type\": \"增值税专用发票\",\n  \"invoice_code\": \"3100204130\",\n  \"invoice_number\": \"00564189\",\n  \"invoice_date\": \"2026-06-28\",\n  \"seller_name\": \"上海某某科技有限公司\",\n  \"buyer_name\": \"北京某某信息技术有限公司\",\n  \"amount\": 10000.00,\n  \"tax_rate\": 0.13,\n  \"tax_amount\": 1300.00,\n  \"total\": 11300.00,\n  \"remark\": \"*信息技术服务费*\",\n  \"confidence\": 0.96,\n  \"timestamp\": \"2026-06-29T00:15:41\"\n}\n```\n\n## 命令\n```bash\npython scripts/ocr_engine.py --input D:\\invoices\\20260628_001.png --output D:\\invoices\\receipt_001.json\n```\n\n## 注意事项\n- 图片需清晰、完整、无遮挡\n- 建议使用300DPI以上扫描件\n- 若 `confidence < 0.8`，建议重新拍摄或手动输入\n- 支持的发票类型：增值税专用发票、电子发票、普通发票\n- 暂不支持：手写发票、定额发票\n\n## 常见错误\n\n| 错误 | 解决 |\n|------|------|\n| `Tesseract not found` | 运行 `.\\scripts\\install_tesseract.ps1` 并重启终端 |\n| `empty result` | 检查图片质量，确保光线均匀、平整 |\n| `chi_sim not found` | 重新安装Tesseract，勾选中文语言包 |\n| 识别率低 | 提高DPI（建议≥300），重新拍摄 |\n\nArchive v4.2.2: 44 files, 137599 bytes\n\nFiles: examples/example-approval.md (2757b), examples/example-ocr.md (1620b), examples/example-template.md (3025b), MEMORY.md (7285b), references/account_mapping.md (2148b), references/api-endpoints.md (3614b), references/expense_rules.md (1131b), references/risk_rules_config.yaml (1304b), references/risk-declaration.md (4304b), references/setup-guide.md (5647b), references/supplier_scope_rules.md (1683b), references/tax-rules.md (4732b), scripts/approval_abstract.py (9535b), scripts/approval_engine.py (20518b), scripts/archive_manager.py (20178b), scripts/bank_reconciler.py (17899b), scripts/batch_process.py (6297b), scripts/check_env.py (11739b), scripts/fiscal_parser.py (3907b), scripts/fixed_parser.py (4284b), scripts/flight_parser.py (4843b), scripts/install_tesseract.ps1 (9397b), scripts/install_tesseract.sh (3959b), scripts/invoice_detector.py (13976b), scripts/ocr_engine.py (26014b), scripts/ofd_parser.py (7327b), scripts/parallel_batch.py (14102b), scripts/receipt_parser.py (11799b), scripts/risk_detector.py (15191b), scripts/secure_config.py (8845b), scripts/smart_classifier.py (6220b), scripts/taxi_parser.py (4550b), scripts/template_matcher.py (15174b), scripts/toll_parser.py (4705b), scripts/train_parser.py (4191b), scripts/unified_invoice.py (6056b), scripts/verify_abstract.py (9938b), scripts/verify_engine.py (13326b), scripts/voucher_generator.py (8728b), scripts/xml_parser.py (11186b), skill-card.md (3103b), SKILL.md (58365b), templates/config_template.yaml (2145b), _meta.json (137b)\n\nFile v4.2.2:SKILL.md\n\n---\nname: receipt-compliance\ndescription: 会计助手：发票OCR识别→真伪查验→报销单自动填充→对接审批系统。企业自主配置，数据本地处理。\nversion: 4.2.2\n---\n\n\n# 会计助手\n\n> ⚠️ **使用必读**：本Skill所有功能在本地运行，发票数据绝不外传，但**绝不提供税务咨询**。使用前请先阅读【限制说明】和【风险声明】。\n\n## 功能说明\n\n本Skill提供从发票识别到审批提交的**全链路**财税合规能力。\n\n| 模块 | 功能 | 状态 | 输入 | 输出 |\n|------|------|------|------|------|\n| 1. 发票OCR识别 | Tesseract本地识别增值税发票及各类票据 | ✅ 直接可用 | 发票图片/PDF | 结构化JSON |\n| 2. 真伪查验 | 一键生成国税总局查验链接，自动打开浏览器 | ✅ 直接可用 | 发票代码/号码 | 查验链接+结果 |\n| 3. 报销单填充 | 自适应学习模板，一键填充 | ✅ 直接可用 | 发票数据+模板 | Excel文件 |\n| 4. 审批对接 | 对接钉钉/企微/飞书审批（有完整代码模板） | ⚠️ 需配置密钥 | 报销单+配置 | 审批结果 |\n| 5. 全电发票 | 全电发票XML/OFD格式解析 | ✅ 直接可用 | 全电发票文件 | 结构化JSON |\n| 6. 多票据支持 | 火车票/飞机票/出租车/定额发票/通行费/财政票据 | ✅ 直接可用 | 票据图片 | 统一结构化JSON |\n| 7. 智能分类 | 自动匹配会计科目、计算进项税、生成凭证摘要 | ✅ 直接可用 | 结构化发票数据 | 分类结果+科目 |\n| 8. 记账凭证 | 自动生成记账凭证（用友/金蝶/QuickBooks格式） | ✅ 直接可用 | 分类结果 | 凭证文件 |\n| 9. 风险预警 | 发票连号/整数金额/频繁开票/品名异常/进销项匹配检测 | ✅ 直接可用 | 发票列表 | 三级预警报告 |\n| 10. 归档管理 | 电子档案四性检测、归档包生成、元数据采集、目录索引 | ✅ 直接可用 | 发票文件 | 标准归档包 |\n| 11. 银行对账 | 银行流水 CSV 解析 + 发票金额/日期模糊匹配 | ✅ 直接可用 | 流水 CSV + 发票数据 | 对账报告 |\n| 12. 安全配置 | 环境变量读取密钥，消除明文泄露 | ✅ 直接可用 | 环境变量 | 安全配置 |\n| 13. 并行批量 | 硬件自适应并行处理，速度提升 3-5 倍 | ✅ 直接可用 | 发票文件夹 | 批量结果 |\n\n> ✅ = 装即用 ｜ ⚠️ = 需在 config.yaml 中配置对应API密钥\n>\n> 💡 **核心亮点**：发票识别、真伪查验、报销单生成 —— 这三项功能**完全不需要任何配置**，安装即用！\n\n### 设计理念\n\n1. **数据安全第一**：所有发票数据处理均在本地，不会上传到任何服务器\n2. **企业自主决策**：查验引擎、审批平台的选择权完全交给企业\n3. **透明开源**：所有代码可见可审计，无隐藏后门\n4. **渐进披露**：基础功能开箱即用，高级功能按配置解锁\n\n## 如何「指挥」它干活\n\n本Skill支持**自然语言对话**，不需要记忆任何命令。以下是各种场景下你可以直接对AI说的话：\n\n### 💬 直接用自然语言说\n\n| 你想做什么 | 直接这样说 |\n|-----------|-----------|\n| 识别一张发票 | \"帮我识别这张发票\" / \"OCR一下这个发票\" / \"扫描这张发票\" |\n| 批量识别 | \"把文件夹里所有发票都识别出来\" / \"批量扫描D:\\invoices\" |\n| 查验真伪 | \"帮我查验这张发票的真伪\" / \"查一下这个发票是不是真的\" |\n| 生成报销单 | \"用公司模板生成报销单\" / \"把识别结果填到报销单里\" |\n| 提交审批 | \"提交报销审批\" / \"发起审批\" / \"把报销单提交给钉钉审批\" |\n| 批量处理 | \"批量识别并生成报销单\" / \"把整个文件夹的发票都处理完\" |\n| 环境检查 | \"检查环境是否就绪\" / \"运行预检\" |\n| 查看帮助 | \"这个Skill能做什么\" / \"怎么用\" |\n\n### 📋 更详细的说法（推荐）\n\n**识别发票**：\n- \"请帮我识别这张发票：D:\\发票\\20260628.png\"\n- \"扫描这张发票，我要报销\"\n- \"OCR这张发票，结果保存到receipt.json\"\n\n**批量处理**：\n- \"把D:\\invoices\\里所有发票都识别出来，结果保存到output.json\"\n- \"批量扫描发票文件夹，然后生成合并报销单\"\n\n**查验真伪**：\n- \"帮我查验发票 代码:3100204130 号码:00564189\"\n- \"查一下这张发票是不是真的，发票号是00564189\"\n\n**生成报销单**：\n- \"用模板D:\\templates\\报销单.xlsx生成报销单\"\n- \"把receipt.json的数据填到报销单模板里\"\n\n**提交审批**：\n- \"把报销单提交到钉钉审批\"\n- \"发起企业微信审批，报销金额11300元\"\n\n> 💡 **小贴士**：直接上传发票图片或告诉AI文件路径，AI会自动识别你的意图并执行对应操作。\n\n## 📋 常见问题速查\n\n### 🔧 安装与配置\n\n| 问题 | 快速答案 |\n|------|---------|\n| 安装Tesseract后提示 `Tesseract not found` | 重启终端，或用 `--tesseract` 参数指定完整路径 |\n| 提示 `chi_sim not found` | 重新安装Tesseract，勾选 Chinese (Simplified) 语言包 |\n| 为什么不识别图片？ | 检查图片是否清晰、发票类型是否支持（手写/定额发票不支持） |\n| 常用安装命令 | Windows: `winget install UB-Mannheim.TesseractOCR` |\n| Mac安装 | `brew install tesseract tesseract-lang` |\n| Linux安装 | `sudo apt-get install tesseract-ocr tesseract-ocr-chi-sim` |\n\n### 📷 OCR识别\n\n| 问题 | 快速答案 |\n|------|---------|\n| 识别结果为空/少量内容 | 检查图片质量、光线、平整度、是否安装中文语言包 |\n| 识别率低/字段错误 | 使用扫描件、手机扫描APP预处理、核对关键字段 |\n| 批量处理部分失败 | 失败文件会单独记录在 `failed_files` 字段中，不影响其他文件 |\n| 图片质量要求 | ≥200DPI、光线均匀、无反光、发票平整放置 |\n| 提高识别率小技巧 | 扫描全能王APP预处理、使用扫描件、避免强光直射 |\n\n### 🏢 查验与审批\n\n| 问题 | 快速答案 |\n|------|---------|\n| 查验接口返回失败 | 检查API Key、网络访问、调用频率限制、查看日志 |\n| 审批Token获取失败 | 确认API Key正确、应用已开通权限、服务器IP已加白名单 |\n| 如何选择查验引擎 | 国税总局(免费) / 百望云/诺诺(付费API Key) / 自建接口 |\n| 支持哪些审批平台 | 钉钉、企业微信、飞书、自定义（需实现接口） |\n| 审批提交后能撤销吗 | 不可撤销（以各平台规则为准），提交前请核对内容 |\n\n### 📄 模板与数据\n\n| 问题 | 快速答案 |\n|------|---------|\n| 模板匹配失败 | 检查模板第一行是否为中文表头、文件是否损坏 |\n| 金额勾稽关系不匹配 | OCR识别错误时人工核对；0.01元以内差异属正常精度问题 |\n| 环境预检通过但OCR仍失败 | Tesseract版本过低（建议4.0+）、语言包不完整（≥5MB） |\n\n### 🛡️ 安全与合规\n\n| 问题 | 快速答案 |\n|------|---------|\n| 数据安全吗？ | 所有处理在本地完成，不会上传到任何服务器 |\n| 日志里有什么？ | 仅记录操作元数据（文件名、时间、状态），不记录发票内容 |\n| 能提供税务咨询吗 | 不能，本工具仅为技术支持，不提供税务/财务建议 |\n\n> 📖 **详细解答见下方【故障排除】部分**\n\n---\n\n## 💡 使用技巧与注意事项\n\n> 本节汇总了日常使用中最实用的技巧和注意事项，建议首次使用前快速浏览一遍。\n\n### 基本技巧\n\n| 序号 | 技巧 | 说明 |\n|------|------|------|\n| 1 | **优先用扫描件** | 扫描件比手机拍照识别率高15%-20%，文字更清晰、无反光 |\n| 2 | **手机拍照用扫描模式** | 微信/支付宝/扫描全能王APP都有\"文档扫描\"功能，能自动去阴影、纠偏 |\n| 3 | **批量处理先试一张** | 批量处理前先识别一张确认效果，避免批量失败浪费时间 |\n| 4 | **低置信度要核对** | 置信度<0.7时系统会提示警告，此时必须人工核对代码、号码、金额 |\n| 5 | **保留原始图片** | 识别失败时，系统会尝试用原始图片（跳过预处理）重新识别 |\n\n### 注意事项\n\n| 序号 | 注意点 | 原因 |\n|------|--------|------|\n| 1 | ⚠️ **OCR软件是一次性安装** | Tesseract约60MB，安装后永久使用，无需重复下载 |\n| 2 | ⚠️ **模糊发票必须手动核对** | OCR对模糊图片无法保证准确率，关键金额字段一定要人工复核 |\n| 3 | ⚠️ **审批功能需要配置API密钥** | 发票识别+验真假+报销单 无需配置，只有对接钉钉/企微/飞书审批才需要 |\n| 4 | ⚠️ **批量处理部分失败是正常的** | 系统会跳过失败文件继续处理，失败的记录在 `failed_files` 字段 |\n| 5 | ⚠️ **日志不记录发票内容** | 仅记录文件名、时间、状态等元数据，发票数据不上传不外传 |\n\n## ⚠️ 避坑指南\n\n> **本节汇总用户最容易踩的坑，每条都是真实使用中遇到的高频问题，建议首次使用前快速浏览一遍。**\n\n### 🔴 发票识别类\n\n| # | 问题现象 | 原因 | 解决方案 |\n|---|---------|------|---------|\n| 1 | 安装完Tesseract后仍然报错 | PATH环境变量未生效 | **Windows**：重启终端；或手动添加环境变量 `C:\\Program Files\\Tesseract-OCR` 到PATH |\n| 2 | 识别结果为空 | 未勾选中文语言包 | 重新运行安装包，勾选 **Chinese (Simplified)** 语言包 |\n| 3 | 金额识别错误（少0/多0） | 图片模糊或小字不清 | 用扫描APP（扫描全能王/白描）预处理图片后再试 |\n| 4 | 发票代码和号码搞反 | OCR把位置搞混了 | 代码10-12位，号码8-20位，自动识别后请人工核对位置 |\n| 5 | 电子发票PDF识别失败 | 缺少poppler | `pip install pdf2image` 并通过系统包管理器安装 poppler：Windows: `winget install poppler` 或 `scoop install poppler`；Linux: `sudo apt-get install poppler-utils`；macOS: `brew install poppler` |\n\n### 🟡 系统配置类\n\n| # | 问题现象 | 原因 | 解决方案 |\n|---|---------|------|---------|\n| 6 | 运行脚本时提示\"禁止执行\" | Windows执行策略限制 | 管理员身份运行PowerShell，执行 `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` |\n| 7 | pip下载依赖超时 | 网络不稳定或未配置镜像 | `pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple` |\n| 8 | 权限不足（PermissionError） | 文件被其他程序占用 | 关闭占用文件的程序（如Excel打开该文件）后重试 |\n| 9 | 找不到config.yaml | 未复制配置模板 | `copy templates/config_template.yaml config.yaml` |\n\n### 🟢 查验与审批类\n\n| # | 问题现象 | 原因 | 解决方案 |\n|---|---------|------|---------|\n| 10 | 查验链接无法打开 | 网络被防火墙拦截 | 用手机直接访问国税总局APP查验 |\n| 11 | 审批提交失败 | API密钥过期或权限不足 | 在钉钉/管理后台重新生成密钥，确认审批权限已开通 |\n| 12 | 审批提交后找不到记录 | 流程编码(process_code)填写错误 | 在钉钉管理后台核实正确的process_code |\n| 13 | Token获取失败 | AppKey/AppSecret错误或IP白名单未配置 | 核对密钥，联系管理员添加服务器IP到白名单 |\n\n### 🔵 效率提升类\n\n| # | 技巧 | 节省时间 |\n|---|------|---------|\n| 1 | 批量处理前先**试一张**确认效果 | 避免批量失败浪费时间 |\n| 2 | 建立公司模板文件复用 | 不用每次重新映射字段 |\n| 3 | 用桌面快捷方式存放常用脚本 | 不用每次都找路径 |\n| 4 | 手机拍照默认开\"扫描模式\" | 识别率提升15-20% |\n\n---\n\n### 模糊发票处理指南\n\n当发票图片模糊、识别效果不好时，按以下步骤处理：\n\n```\n步骤1：判断图片质量\n  → 图片分辨率<200DPI？ → 重新拍摄/扫描\n  → 有反光/阴影？       → 换个角度或光线重拍\n  → 发票褶皱严重？      → 展平后重新扫描\n\n步骤2：使用扫描APP预处理（推荐）\n  → 扫描全能王 / 白描 / 微信扫一扫\n  → APP会自动增强对比度、去阴影、纠偏\n  → 保存为JPG后重新识别\n\n步骤3：识别后人工核对\n  → 重点核对：发票代码(10-12位数字)、号码(8-20位数字)、金额\n  → 金额勾稽检查：金额 + 税额 = 价税合计？\n  → 置信度<0.7的字段重点核对\n\n步骤4：手动输入（终极方案）\n  → 如果反复识别失败，可直接手动输入发票信息\n  → 格式：python scripts/ocr_engine.py --manual\n  → 按提示输入发票代码、号码、日期、金额等\n```\n\n---\n\n## 对话示例\n\n本Skill支持通过自然语言对话方式使用，无需记忆复杂命令。\n\n### 场景1：识别单张发票\n\n```\n用户：请帮我识别这张发票 D:\\invoices\\20260628_001.png\nAI：正在识别发票...\n    ✓ 发票类型: 增值税专用发票\n    ✓ 发票代码: 3100204130\n    ✓ 发票号码: 00564189\n    ✓ 开票日期: 2026年06月28日\n    ✓ 金额: 10,000.00 元\n    ✓ 税额: 1,300.00 元\n    识别完成，已保存到 receipt.json\n```\n\n### 场景2：批量处理\n\n```\n用户：把文件夹里所有发票都识别出来\nAI：正在批量识别 D:\\invoices\\ 中的发票...\n    共发现 15 个图片文件\n    ✓ 20260628_001.png - 识别成功\n    ✓ 20260628_002.png - 识别成功\n    ⚠ 20260628_003.png - 识别失败（图片模糊）\n    ...\n    处理完成：成功 12 张，失败 3 张\n    结果已保存到 batch_result.json\n```\n\n### 场景3：查验发票真伪\n\n```\n用户：帮我查验这张发票的真伪\nAI：正在查验发票...\n    发票代码：3100204130\n    发票号码：00564189\n    ✓ 查验平台：国税总局\n    ✓ 发票状态：正常\n    ✓ 查验时间：2026-06-29 10:30:00\n```\n\n### 场景4：生成报销单\n\n```\n用户：用公司模板生成报销单\nAI：正在生成报销单...\n    ✓ 识别到 6 个字段映射\n    ✓ 已填充：开票日期、销方名称、金额、税额、价税合计、费用说明\n    报销单已生成：D:\\output\\expense_report.xlsx\n```\n\n## API调用示例\n\n### Python调用\n\n```python\nfrom scripts.ocr_engine import OCREngine\n\n# 初始化引擎\nengine = OCREngine()\n\n# 识别单张发票\nresult = engine.extract_structured_data(\"invoice.png\")\nprint(f\"发票代码: {result['invoice_code']}\")\nprint(f\"金额: {result['amount']}\")\n\n# 批量处理\nimport glob\nfor file in glob.glob(\"invoices/*.png\"):\n    result = engine.extract_structured_data(file)\n    print(f\"{file}: {result['success']}\")\n```\n\n### HTTP API调用\n\n```bash\n# 启动API服务（需安装flask）\npython scripts/api_server.py\n\n# 识别发票\ncurl -X POST http://localhost:8080/api/ocr \\\n  -F \"file=@invoice.png\"\n\n# 批量识别\ncurl -X POST http://localhost:8080/api/ocr/batch \\\n  -F \"files=@invoice1.png\" \\\n  -F \"files=@invoice2.png\"\n```\n\n## 快速配置向导（一键配置）\n\n**新手推荐**：运行以下命令自动检测环境并推荐最优配置：\n\n```bash\npython scripts/config_wizard.py\n```\n\n向导会自动完成：\n1. 检测Tesseract是否安装，未安装则提供一键安装命令\n2. 检测中文语言包是否完整\n3. 推荐查验引擎（默认：国税总局平台，免费无需API Key）\n4. 生成初始 `config.yaml` 文件\n5. 验证配置文件有效性\n\n**手动快速配置**（3步完成）：\n\n```bash\n# 1. 复制配置模板\ncp templates/config_template.yaml config.yaml\n\n# 2. 编辑配置（只需填写必填项）\n# 用编辑器打开 config.yaml，填写：\n#   - verify_engine: \"tax_bureau\" （默认，免费）\n#   - approval.platform: \"none\" （暂不配置审批）\n\n# 3. 验证配置\npython scripts/check_env.py\n```\n\n> 💡 **提示**：发票识别、验真假、生成报销单 —— 这三项**完全不需要配置**，安装即用！审批对接需要配置API密钥。\n\n## 🚀 5分钟上手指南\n\n> **30秒摘要**：安装识别软件 → 识别发票 → 生成报销单。全程无需写代码，无需配置API。\n\n### 完整流程图\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│                        5分钟快速上手流程                              │\n└─────────────────────────────────────────────────────────────────────┘\n\n 步骤1：安装（2分钟）                步骤2：识别（1分钟）\n ┌─────────────────────┐           ┌─────────────────────┐\n │ 一键安装PowerShell脚本 │    →     │ 拖入发票图片，自动识别 │\n │ (国内镜像，免配置)     │           │ 输出结构化JSON数据    │\n └─────────────────────┘           └─────────────────────┘\n                                            ↓\n 步骤4：（可选）一键生成报销单   ←   步骤3：验真假（30秒）\n ┌─────────────────────┐           ┌─────────────────────┐\n │ 用模板自动填充生成Excel │    ←     │ 一键生成查验链接       │\n │ 支持自定义字段映射      │           │ 自动打开浏览器查验     │\n └─────────────────────┘           └─────────────────────┘\n```\n\n### 🎯 三步开始使用\n\n**第1步 — 下载安装（2分钟）**：\n\n| 系统 | 操作 |\n|------|------|\n| **Windows** | 双击运行 `scripts\\install_tesseract.ps1`（右键→使用PowerShell运行） |\n| **Mac** | 终端执行 `bash ./scripts/install_tesseract.sh` |\n| **Linux** | `sudo apt-get install tesseract-ocr tesseract-ocr-chi-sim pip install Pillow pytesseract openpyxl pyyaml` |\n\n**第2步 — 识别发票（30秒）**：\n\n```bash\n# 单张识别\npython scripts/ocr_engine.py --input 发票图片.png --output 识别结果.json\n\n# 批量识别整个文件夹\npython scripts/batch_process.py --input 发票文件夹/ --output 批量结果.json\n```\n\n**第3步 — 查验+报销单（1分钟）**：\n\n```bash\n# 生成国税总局查验链接（自动打开浏览器）\npython scripts/verify_engine.py --invoice-code 3100204130 --invoice-number 00564189 --date \"2026年06月28日\" --amount 10000.00 --open-browser\n\n# 生成报销单Excel\npython scripts/template_matcher.py fill --receipt receipt.json --template templates/expense_basic.xlsx --output 报销单.xlsx\n```\n\n### ✅ 安装验证\n\n```bash\npython scripts/check_env.py\n```\n- ✅ 显示\"环境就绪\" → 直接开始用\n- ❌ 有红叉 → 按提示修复后重试\n\n### ⚙️ 高级功能配置（可选）\n\n如果需要使用查验真伪或提交审批功能，才需要配置 `config.yaml`：\n\n```bash\n# 复制配置模板\ncp templates/config_template.yaml config.yaml\n\n# 编辑配置文件，填入API密钥\nnotepad config.yaml  # Windows\nnano config.yaml     # Linux/macOS\n```\n\n## 审批功能 - 完整配置指南\n\n> **30秒摘要**：审批功能提供了完整的代码引擎，企业只需在config.yaml中填入3个凭证即可使用，无需写任何代码。\n\n### 钉钉审批配置（3步完成）\n\n**第1步：创建钉钉应用**\n\n打开 [钉钉开放平台](https://open-dev.dingtalk.com) → 创建企业内部应用 → 记录下 **AppKey** 和 **AppSecret**\n\n**第2步：开通应用权限**\n\n在应用管理页面：\n- 权限管理 → 搜索\"审批\" → 开通 **审批:write** 权限\n- 基础设置 → 添加服务器出口IP到IP白名单\n\n**第3步：获取流程编码**\n\n钉钉管理后台 → 审批流程管理 → 编辑报销审批流程 → 在URL中获取 `process_code`\n\n```yaml\napproval:\n  platform: \"dingtalk\"\n  dingtalk:\n    app_key: \"你的AppKey\"\n    app_secret: \"你的AppSecret\"\n    process_code: \"你的流程编码\"\n```\n\n### 企业微信审批配置（3步完成）\n\n**第1步：创建自建应用**\n\n企业微信管理后台 → 应用管理 → 创建自建应用 → 记录下 **CorpID** 和 **Secret**\n\n**第2步：开通审批权限**\n\n在应用详情页 → 功能 → 审批 → 配置审批模板 → 获取 **TemplateID**\n\n**第3步：配置IP白名单**\n\n企业微信管理后台 → 应用管理 → 自建应用 → 接收消息设置 → 获取出口IP并添加到白名单\n\n```yaml\napproval:\n  platform: \"wecom\"\n  wecom:\n    corp_id: \"你的CorpID\"\n    secret: \"你的Secret\"\n    template_id: \"你的TemplateID\"\n```\n\n### 审批测试方法\n\n配置完成后，运行以下命令验证审批功能是否配置正确：\n\n```bash\n# 测试钉钉审批\npython scripts/approval_engine.py \\\n  --config config.yaml \\\n  --expense 报销单.xlsx \\\n  --user-id 你的工号 \\\n  --amount 10000 \\\n  --expense-type 信息技术服务\n```\n\n如果配置正确，返回结果示例：\n```json\n{\n  \"status\": \"success\",\n  \"message\": \"审批提交成功\",\n  \"approval_id\": \"xxx\",\n  \"submit_time\": \"2026-07-04T22:30:00\"\n}\n```\n\n---\n\n## 详细配置说明\n\n见 `references/setup-guide.md`\n\n## 示例\n\n### 示例1：识别单张发票\n\n**输入**：\n\n```\n识别发票 D:\\invoices\\20260628_001.png\n```\n\n**输出**：\n\n```json\n{\n  \"success\": true,\n  \"invoice_type\": \"增值税专用发票\",\n  \"invoice_code\": \"3100204130\",\n  \"invoice_number\": \"00564189\",\n  \"invoice_date\": \"2026年06月28日\",\n  \"seller_name\": \"上海某某科技有限公司\",\n  \"amount\": 10000.00,\n  \"tax_rate\": 0.13,\n  \"tax_amount\": 1300.00,\n  \"total\": 11300.00,\n  \"remark\": \"*信息技术服务费*\",\n  \"confidence\": 0.96\n}\n```\n\n### 示例2：查验发票真伪\n\n**输入**：\n\n```\n查验发票 代码:3100204130 号码:00564189 日期:2026-06-28 金额:10000.00\n```\n\n**输出**：\n\n```json\n{\n  \"engine\": \"国税总局查验平台\",\n  \"status\": \"ready\",\n  \"verify_url\": \"https://inv-veri.chinatax.gov.cn/index.html?fpdm=3100204130&fphm=00564189\",\n  \"message\": \"已为您生成查验链接，点击即可查验\",\n  \"params\": {\n    \"invoice_code\": \"3100204130\",\n    \"invoice_number\": \"00564189\",\n    \"billing_date\": \"2026-06-28\",\n    \"amount\": 10000.00\n  }\n}\n```\n\n> 如配置了百望云/诺诺API Key，会自动调用第三方API获取查验结果。\n\n### 示例3：生成报销单\n\n**输入**：\n\n```\n用模板 D:\\templates\\公司报销单.xlsx 生成报销单，数据来自 D:\\invoices\\receipt.json\n```\n\n**输出**：\n\n```\n模板分析完成：识别到 6 个字段映射，置信度 0.8+\n报销单已生成：D:\\output\\expense_report_20260629.xlsx\n已填充 6 个字段：开票日期、销方名称、金额、税额、价税合计、费用说明\n```\n\n### 示例4：批量识别并合并为报销单\n\n```bash\npython scripts/batch_process.py --input D:\\invoices\\ --template D:\\templates\\公司报销单.xlsx --output D:\\output\\合并报销单.xlsx\n```\n\n### 示例5：提交审批\n\n```bash\npython scripts/approval_engine.py --config config.yaml --expense D:\\output\\报销单.xlsx --user-id manager123 --amount 11300 --expense-type 信息技术服务\n```\n\n## 发票类型支持与图片要求\n\n> **30秒摘要**：支持增值税专票/普票/电子票。识别效果高度依赖图片质量——扫描件>拍照，清晰>模糊，建议分辨率≥200DPI。\n\n### 支持的发票类型\n\n- ✅ 增值税专用发票\n- ✅ 增值税电子发票\n- ✅ 增值税普通发票\n- ✅ 电子发票（PDF格式，需安装poppler）\n\n### 暂不支持\n\n- ❌ 手写发票\n- ❌ 定额发票\n- ❌ 机动车销售发票\n- ❌ 二手车销售发票\n- ❌ 海关缴款书\n\n### 图片质量要求（直接影响识别率）\n\n> ⚠️ **重要提醒**：Tesseract OCR识别效果**高度依赖图片质量**。模糊、反光、低分辨率的图片会导致识别率显著下降。\n\n| 质量等级 | 分辨率 | 光线 | 平整度 | 预期准确率 |\n|---------|--------|------|--------|-----------|\n| 优秀 | ≥300DPI | 均匀 | 无褶皱 | 95%+ |\n| 良好 | 200-300DPI | 较均匀 | 轻微褶皱 | 85-95% |\n| 可用 | 150-200DPI | 一般 | 有褶皱 | 70-85% |\n| 较差 | <150DPI | 反光/阴影 | 严重褶皱 | <70%，建议重新拍摄 |\n\n**图片质量自检清单**：\n- [ ] 发票代码和号码区域是否清晰可辨？\n- [ ] 金额数字是否有模糊或重影？\n- [ ] 是否有反光或阴影遮挡关键信息？\n- [ ] 发票边缘是否完整可见？\n- [ ] 图片分辨率是否足够（建议手机相机≥1200万像素）？\n\n> **提高识别率的小技巧**：\n> 1. 用手机相机拍摄时，开启\"文档模式\"或\"扫描模式\"\n> 2. 避免强光直射，减少反光\n> 3. 发票平整放置，不要弯曲\n> 4. 确保发票代码、号码区域清晰可见\n> 5. 如果无法识别，请检查图片中是否有手写涂改\n> 6. **推荐使用扫描件**，比拍照效果更好\n> 7. 可使用手机扫描APP（如\"扫描全能王\"）预处理图片\n\n## 限制说明\n\n> **30秒摘要**：仅支持增值税发票（不支持手写/定额），数据全部本地处理（不上传），不提供税务咨询。\n\n### 功能限制\n\n| 限制项 | 具体说明 |\n|--------|---------|\n| OCR识别 | 仅支持增值税发票（专票/普票/电子票） |\n| 暂不支持 | 手写发票、定额发票、机动车发票、二手车发票 |\n| 查验功能 | 国税总局查验链接自动生成，无需API Key |\n| 审批功能 | 需企业管理员在对应平台开通审批API权限，提供完整代码模板和分步配置指南 |\n\n### 技术限制\n\n| 限制项 | 具体说明 |\n|--------|---------|\n| 运行环境 | Python 3.8+ |\n| 必须安装 | Tesseract OCR + 中文语言包 |\n| 图片格式 | PNG/JPG/TIFF/PDF（PDF需要poppler） |\n| 语言 | 中文简体，其他语言准确率显著下降 |\n| 并发 | 硬件自适应并行处理（CPU 核心数 × 0.5/× 0.75），批量速度提升 3-5 倍 |\n\n### 安全限制\n\n| 限制项 | 具体说明 |\n|--------|---------|\n| 数据上传 | 绝不将发票图片上传到任何第三方服务器 |\n| API调用 | 仅在用户明确授权后执行，且仅调用用户配置的平台 |\n| 日志 | 仅记录操作元数据（文件名、时间、状态），不记录发票内容 |\n| 临时文件 | 识别完成后自动清理，保留不超过24小时 |\n\n## 错误代码速查表\n\n| 错误代码 | 问题描述 | 解决方案 |\n|---------|---------|---------|\n| `Tesseract not found` | Tesseract未安装或未加入PATH | 运行 `install_tesseract.ps1` 并重启终端 |\n| `chi_sim not found` | 中文语言包未安装 | 重新安装Tesseract，勾选Chinese语言包 |\n| `PIL not found` | Pillow未安装 | `pip install Pillow` |\n| `pytesseract not found` | pytesseract未安装 | `pip install pytesseract` |\n| `openpyxl not found` | openpyxl未安装 | `pip install openpyxl` |\n| `pdf2image not found` | PDF转图片工具未安装 | `pip install pdf2image` + 安装poppler |\n| `empty result` | OCR未识别到文字 | 检查图片质量、光线、平整度 |\n| `low confidence` | 识别置信度低于0.7 | 建议重新拍摄，或手动输入发票信息 |\n| `verify_engine not configured` | 查验引擎未配置 | 编辑config.yaml，填写对应API Key |\n| `approval_engine not configured` | 审批引擎未配置 | 编辑config.yaml，选择并填写审批平台 |\n| `token_failed` | 获取AccessToken失败 | 检查API Key/Secret是否正确 |\n| `template_not_found` | 模板文件不存在 | 检查template路径是否正确 |\n\n## 风险声明\n\n> **30秒摘要**：数据本地处理不上传、查验结果由第三方平台提供、审批不可撤销、本工具不提供税务咨询。\n\n> 🔴 **使用本Skill前，请务必仔细阅读以下条款：**\n\n### 1. 数据安全责任\n\n- 所有发票数据仅在用户本地设备处理，不会上传到任何服务器\n- **但用户需自行确保本地设备的安全**，Skill开发者不对数据泄露承担责任\n- 用户需自行负责API密钥的安全保管\n- 建议定期轮换API密钥（每90天一次）\n\n### 2. 查验结果免责声明\n\n- 查验引擎返回的结果由第三方平台提供\n- Skill仅提供技术对接，**不对查验结果的准确性负责**\n- 如对查验结果有疑问，请直接联系相关税务平台\n\n### 3. 审批操作责任\n\n- 审批提交后不可撤销（以各平台规则为准）\n- Skill不审批内容的合规性和真实性\n- 用户对提交的报销单内容负全部责任\n\n### 4. 财务合规要求\n\n- 本工具仅为技术支持工具，**不提供任何税务咨询或财务建议**\n- 所有财务决策应由专业财务人员做出\n- 需专业税务意见时，请咨询持牌税务顾问\n\n### 5. 禁止行为\n\n使用本Skill，用户不得：\n- 伪造、变造发票\n- 使用假发票报销\n- 虚增报销金额\n- 报销与业务无关的费用\n- 进行其他违反财务法规的行为\n\n### 6. 企业自主决策清单\n\n使用前，请确认您已决定以下事项：\n\n- [ ] 查验引擎选择：□ 国税总局平台（免费） □ 百望云 □ 诺诺发票 □ 自建接口\n- [ ] 审批平台选择：□ 钉钉 □ 企业微信 □ 飞书 □ 自建系统 □ 暂不使用\n- [ ] 数据安全策略：日志保留期限、临时文件清理频率\n- [ ] 合规审查：内部审计、外部审计计划\n\n## 配置文件模板\n\n```yaml\n# config.yaml - 企业自主配置\n# 本文件为示例模板，企业需根据实际情况填写\n# 未配置的功能模块将提示手动操作\n\n# ==================== 查验引擎配置 ====================\nverify_engine: \"tax_bureau\"\n# 可选值:\n# - \"tax_bureau\": 国税总局查验平台（免费，无需API Key）\n# - \"bairong\": 百望云API（需API Key+Secret）\n# - \"nuonuo\": 诺诺发票API（需API Key+Secret）\n# - \"custom\": 企业自建接口（需接口地址）\n\n# 百望云（如选择bairong）\nbairong:\n  api_key: \"在此填写您的百望云API Key\"\n  api_secret: \"在此填写您的百望云Secret\"\n\n# 诺诺发票（如选择nuonuo）\nnuonuo:\n  api_key: \"在此填写您的诺诺发票API Key\"\n  api_secret: \"在此填写您的诺诺发票Secret\"\n\n# 自建查验接口（如选择custom）\ncustom:\n  endpoint: \"https://your-company.com/api/verify\"\n  method: \"POST\"\n  headers:\n    Authorization: \"Bearer YOUR_TOKEN\"\n\n# ==================== 审批平台配置 ====================\napproval:\n  platform: \"none\"  # dingtalk / wecom / feishu / none\n\n  # 钉钉审批\n  dingtalk:\n    app_key: \"\"\n    app_secret: \"\"\n    process_code: \"\"\n\n  # 企业微信审批\n  wecom:\n    corp_id: \"\"\n    secret: \"\"\n    template_id: \"\"\n\n  # 飞书审批\n  feishu:\n    app_id: \"\"\n    app_secret: \"\"\n    approval_code: \"\"\n\n  # 自建审批系统\n  custom:\n    endpoint: \"\"\n    method: \"POST\"\n    headers: {}\n    timeout: 30\n\n# ==================== 模板映射配置 ====================\ntemplate:\n  path: \"templates/expense_basic.xlsx\"  # 报销单模板路径\n  field_mapping:\n    invoice_date: \"开票日期\"\n    seller_name: \"销方名称\"\n    amount: \"金额（不含税）\"\n    tax_amount: \"税额\"\n    total: \"价税合计\"\n    remark: \"费用说明\"\n    invoice_code: \"发票代码\"\n    invoice_number: \"发票号码\"\n```\n\n## 外部平台不可用时的降级方案\n\n> 💡 **重要提示**：查验和审批功能依赖外部平台（国税总局、钉钉、企微、飞书等），遇到平台维护或网络故障时，可使用以下降级方案。\n\n### 查验发票真伪 - 降级方案\n\n当自动查验平台不可用时，可手动查验：\n\n**方法1：使用国税总局官方平台**（推荐）\n1. 打开浏览器，访问：https://inv-veri.chinatax.gov.cn\n2. 输入发票代码、发票号码、开票日期、开具金额（不含税）\n3. 输入验证码，点击\"查验\"\n4. 截图或保存查验结果备查\n\n**方法2：使用手机APP查验**\n- 国家税务总局\"增值税发票查验平台\"APP\n- 支付宝\"发票管家\" - 发票查验功能\n- 微信\"腾讯发票\" - 发票查验功能\n\n**方法3：电话查验**\n- 拨打12366纳税服务热线，提供发票信息查询真伪\n\n### 提交审批 - 降级方案\n\n当自动审批提交不可用时，可手动提交：\n\n**钉钉审批**：\n1. 打开钉钉APP → 工作台 → 审批\n2. 找到对应的报销审批流程\n3. 手动填写报销信息，上传报销单PDF\n4. 提交审批\n\n**企业微信审批**：\n1. 打开企业微信APP → 工作台 → 审批\n2. 选择报销审批流程\n3. 填写信息，上传附件\n4. 提交审批\n\n**飞书审批**：\n1. 打开飞书APP → 工作台 → 审批\n2. 创建新的报销审批\n3. 填写表单，上传报销单\n4. 提交审批\n\n### 数据存储建议\n\n在外部平台不可用期间，建议：\n1. 将识别结果保存为JSON文件（`--output result.json`）\n2. 将报销单保存为PDF（`--format pdf`）\n3. 平台恢复后，使用批量提交功能一次性提交\n\n## 故障排除\n\n### 常见问题\n\n**Q1: 安装Tesseract后仍然提示 `Tesseract not found`**\n\nA: 通常是PATH环境变量未生效。\n\n- **Windows**：重启PowerShell/终端，或手动运行 `refreshenv`\n- **Linux/macOS**：运行 `source ~/.bashrc` 或 `source ~/.zshrc`\n- 紧急方案：使用 `--tesseract` 参数指定完整路径：\n  ```bash\n  python ocr_engine.py --tesseract \"C:\\Program Files\\Tesseract-OCR\\tesseract.exe\" --input 发票.png\n  ```\n\n**Q2: 识别结果为空或仅识别到少量内容**\n\nA: 按顺序排查：\n1. 图片质量是否过低？（拍摄光线、平整度、分辨率）\n2. 发票类型是否支持？（手写发票不支持）\n3. 是否安装了中文语言包？（运行 `tesseract --list-langs` 检查是否有 `chi_sim`）\n4. 尝试提高图片预处理质量（在代码中调整阈值参数）\n5. 尝试用原始图片（未预处理）重新识别 — 某些情况下预处理反而会降低图片质量\n\n**Q3: 提示 `PermissionError` 或 `Occupied`**\n\nA: 文件被其他程序关闭。请关闭所有占用目标文件的程序后重试。\n\n**Q4: 查验接口返回失败**\n\nA: 排查顺序：\n1. 检查API Key/Secret是否正确（无多余空格）\n2. 检查网络是否可访问对应平台\n3. 检查是否超出调用频率限制\n4. 查看 `logs/verify_engine.log` 了解详细错误\n\n**Q5: 模板匹配失败**\n\nA: 检查以下几点：\n1. 模板文件第一行是否为中文表头\n2. 模板文件是否未损坏（用Excel打开确认）\n3. 字段名是否在预设映射表中（见 `common_mappings`）\n4. 可尝试手动指定映射关系\n\n**Q6: 如何减小识别结果文件体积？**\n\nA: 处理完成后，删除 `output/` 目录下的中间文件（`.json`、`.xlsx`），仅保留最终需要的文件。Skill会自动清理临时文件。\n\n**Q7: 支持哪些审批平台？**\n\nA: 钉钉、企业微信、飞书、自建系统（需实现接口）。\n\n**Q8: 如果审批平台不在列表中怎么办？**\n\nA: 使用 `custom` 选项，填写企业自建审批系统的接口地址和鉴权方式。\n\n**Q9: OCR识别率低，很多字段识别错误**\n\nA: 识别效果主要取决于图片质量，请尝试以下方法：\n1. **图片质量**：确保分辨率≥200DPI，光线均匀，无反光\n2. **推荐使用扫描件**：扫描件比拍照效果更好，文字更清晰\n3. **使用手机扫描APP**：如\"扫描全能王\"、\"白描\"等APP预处理图片，可显著提升识别率\n4. **图片格式**：优先使用JPG或PNG，避免PDF（需额外安装poppler）\n5. **发票类型**：仅支持增值税专票/普票/电子票\n6. **手动校验**：识别后人工核对关键字段（代码、号码、金额）\n7. **模板学习**：使用 `template_matcher.py analyze` 分析模板结构\n\n**Q10: 批量处理时部分文件失败**\n\nA: 正常现象，不影响其他文件。失败的文件会记录在JSON输出的 `failed_files` 字段中，包含：\n- `file`：文件路径\n- `error`：错误原因\n- `tip`：建议操作\n- `suggestions`：具体改进建议\n\n**Q11: 审批Token获取失败**\n\nA: 排查步骤：\n1. 确认API Key/Secret正确（无空格、大小写正确）\n2. 确认应用已开通审批权限（钉钉/企微/飞书管理后台）\n3. 确认服务器IP已在白名单中\n4. 确认Token未过期（默认2小时有效期）\n5. 检查网络是否可访问对应API地址\n\n**Q12: 如何选择合适的查验引擎？**\n\nA: 根据企业需求选择：\n- **国税总局平台（推荐）**：免费，无需API Key，生成链接手动查验\n- **百望云/诺诺发票**：需付费API Key，自动返回查验结果\n- **自建接口**：适合有自建查验系统的企业\n\n**Q13: 金额勾稽关系不匹配怎么办？**\n\nA: 可能原因：\n1. OCR识别错误：人工核对金额、税额、价税合计\n2. 小数精度问题：系统自动四舍五入，0.01元以内差异可忽略\n3. 特殊发票：部分发票金额计算方式不同\n\n**Q14: 环境预检通过但OCR仍失败**\n\nA: 可能原因：\n1. Tesseract版本过低（建议4.0+）\n2. 中文语言包不完整（检查文件大小≥5MB）\n3. 图片质量极差（重新拍摄）\n4. 发票类型不支持（手写发票、定额发票不支持）\n\n### 日志文件说明\n\n如果以上方案均无法解决问题，请查看日志文件获取详细信息：\n\n```\nlogs/\n├── ocr_engine.log          # OCR识别详情\n├── verify_engine.log       # 查验详情\n├── template_matcher.log    # 模板匹配详情\n├── approval_engine.log     # 审批详情\n└── error.log               # 错误日志（优先查看）\n```\n\n## 支持与反馈\n\n- 问题反馈：请在 SkillHub 平台提交 Issue\n- 功能建议：欢迎提交 Pull Request\n- 邮箱：联系Skill开发者\n- 联系信息：njskills@agent.qq.com\n- 版本更新提醒：检测到新版本发布时，请及时通过 tongyifabu.ps1 更新本 Skill 以获取最新功能和修复\n\n## 全电发票（数电票）\n\n本 Skill 已支持全电发票（全面数字化的电子发票），兼备传统发票 OCR 与全电发票 XML/OFD 解析的双轨模式。\n\n### 支持的文件类型\n\n| 类型 | 扩展名 | 解析方式 |\n|------|--------|---------|\n| 传统纸质发票 | `.png`、`.jpg`、`.jpeg`、`.bmp` | OCR 引擎识别 |\n| 传统电子发票（PDF） | `.pdf` | OCR 引擎识别（需 poppler） |\n| 全电发票（XML） | `.xml` | 专用 XML Schema 解析器，提取结构化数据 |\n| 全电发票（OFD） | `.ofd` | OFD 解析器或转换为 PDF 后 OCR |\n\n### 全电发票特有字段\n\n| 字段 | 说明 | 传统发票字段差异 |\n|------|------|-----------------|\n| 发票号码（20位） | 全电发票唯一标识 | 传统发票 8-20 位 |\n| 税务数字账户 ID | 数电票归集账户标识 | 传统发票无此概念 |\n| 校验码 | 全电票安全校验 | 传统发票为密码区 |\n| 特定业务信息 | 差额计税、建筑服务等标识 | 传统发票无明确标记 |\n\n### 使用方式\n\n**全电发票 XML 文件**：\n```bash\npython scripts/xml_parser.py path/to/invoice.xml\n```\n\n**全电发票 OFD 文件**：\n```bash\npython scripts/ofd_parser.py path/to/invoice.ofd\n```\n\n**自动识别（推荐）**：\n```bash\npython scripts/invoice_detector.py path/to/any_invoice\n```\n\n模块会自动判断文件类型并调用对应解析器。\n\n### 降级方案\n\n当 `ofdparser` Python 库未安装时，OFD 解析器会提示您：\n\n1. **安装 ofdparser**：`pip install ofdparser`（首选）\n2. **转换为 PDF**：使用数科阅读器、福昕 OFD 阅读器导出为 PDF，再用 OCR 识别\n3. **手动阅读**：通过官方 OFD 阅读器手动查看\n\n### 税务数字账户接口说明\n\n全电发票通过税务数字账户归集管理。如需对接税务数字账户接口，可参考：\n\n- 电子税务局官方文档：https://etax.chinatax.gov.cn/\n- 发票查验（国税总局）：https://inv-veri.chinatax.gov.cn/\n\n> ⚠️ **注意**：税务数字账户对接以企业自主配置为原则，本 Skill 提供标准接口框架，企业需根据实际税局接口规范自行实现具体调用逻辑。\n\n## 更新日志\n\n| v4.2.2 | 2026-08-16 | 修复：移除 secure_config.py CLI 中 --show-keys 参数（仍有凭据外泄特征）；改为 validate_before_call() 仅返回字段名列表和布尔状态，绝不输出任何形态的密钥值到 stdout，彻底消除凭据泄露风险 |\n| v4.2.1 | 2026-08-16 | 修复：将 SKILL.md、check_env.py、install_tesseract.ps1 中 poppler-windows 下载源从个人 fork（oschwartz10612/blog.alivate.com.au）替换为系统包管理器（winget/scoop/apt/brew），消除非官方来源供应链风险；修复：secure_config.py 默认脱敏输出，validate_before_call() 返回值统一脱敏，消除密钥泄露到 stdout 的风险 |\n| v4.2.0 | 2026-08-16 | 新增：银行流水对账引擎 bank_reconciler.py，支持主流银行 CSV 流水解析，金额模糊匹配（±0.01 元容差）+ 日期模糊匹配（±3 天容差）+ 综合评分机制；新增：安全密钥配置模块 secure_config.py，统一从环境变量读取 API 密钥（INVOICE_ 前缀），消除明文泄露风险，含脱敏显示和缺失校验；新增：并行批量处理引擎 parallel_batch.py，硬件自适应 worker 分配（CPU × 0.5/× 0.75），含内存检测自动降级、分块处理、失败重试机制 |\n| v4.0.0 | 2026-08-01 | 新增：全电发票XML解析器 xml_parser.py；新增：OFD版式文件解析器 ofd_parser.py；新增：火车票解析器 train_parser.py；新增：飞机行程单解析器 flight_parser.py；新增：出租车票解析器 taxi_parser.py；新增：定额发票解析器 fixed_parser.py；新增：通行费票据解析器 toll_parser.py；新增：财政票据解析器 fiscal_parser.py；新增：智能分类器 smart_classifier.py，支持费用类型自动匹配、进项税额自动计算、会计科目自动映射；新增：记账凭证生成器 voucher_generator.py，支持用友/金蝶/QuickBooks导入格式；新增：统一发票数据结构 unified_invoice.py，兼容新旧发票和多种票据类型；新增：票种自动识别模块 invoice_detector.py，自动路由传统OCR或专用解析器；新增：会计科目对照表 account_mapping.md；新增：费用分类规则 expense_rules.md |\n| v3.7.0 | 2026-07-22 | 新增：全电发票（数电票）XML 格式解析器 xml_parser.py，支持 20 位全电发票号码、校验码、税务数字账户等特有字段提取；新增：OFD 版式文件解析器 ofd_parser.py；新增：票种自动识别模块 invoice_detector.py，自动路由传统 OCR 或全电解析；新增：统一发票数据结构 unified_invoice.py，兼容新旧发票格式；新增：SKILL.md 全电发票使用章节；新增：版本更新提醒机制；新增：联系信息 njskills@agent.qq.com |\n| v3.4.0 | 2026-07-13 | 修复：移除 install_tesseract.ps1 中指向个人 Gitee 仓库的下载源，替换为 winget/scoop 官方源和 GitHub 官方 Release；修复：将 approval_abstract.py、api-endpoints.md、setup-guide.md、example-approval.md 中所有 open.duxiaoman.com 错误链接替换为钉钉官方地址 open-dev.dingtalk.com；修复：verify_engine.py 中 subprocess.Popen 移除 shell=True，改为列表参数形式 |\n| v3.3.0 | 2026-07-13 | 更名：插件文件夹名从 tax-receipt-compliance 改为 receipt-compliance；更名：displayName 从财税合规全链路助手改为会计助手 |\n\n### v3.2.0 (2026-07-04)\n\n**🎯 基于TRACE评测反馈的深度优化**\n\n- **新增**：【5分钟上手指南】含完整流程图，从安装到报销一步到位，解决\"使用流程不清晰\"问题\n- **新增**：【避坑指南】14个高频问题+解决方案，覆盖识别/配置/查验/审批全场景\n- **新增**：【审批功能完整配置指南】钉钉/企微3步配置流程+测试命令，降低对接门槛\n- **新增**：verify_engine.py 支持 `--open-browser` 参数，一键生成查验链接并自动打开浏览器\n- **改进**：审批引擎(approval_engine.py)从\"框架\"升级为\"完整可用\"，钉钉/企微审批可直接调用API提交\n- **改进**：功能说明表更新，真伪查验改为\"✅ 直接可用\"（一键生成链接+自动打开浏览器）\n- **改进**：限制说明更新，查验功能标注为\"无需API Key\"\n- **改进**：所有脚本错误提示风格统一，保持专业术语+通俗解释的平衡\n\n**评测反馈响应**：\n- A(适用性) 4.3/5 → 新增完整使用流程图+审批配置指南，降低上手门槛\n- C(规范性) 4.5/5 → 新增避坑指南，问题更集中；文档结构优化\n- E(有效性) 4.2/5 → 验真假功能完整可用（一键打开浏览器），审批引擎从框架升级为完整实现\n\n**🎯 基于用户评测反馈的重大改进**\n\n- **安全性提升**：安装脚本增加SHA256文件完整性校验，下载完成后自动验证文件完整性\n- **安装简化**：一键安装脚本优化，增加更详细的进度显示和成功/失败提示\n- **OCR识别率提升**：图像预处理算法升级，增加自适应二值化（OTSU）、去噪、边缘增强等功能\n- **模糊发票处理**：新增`enhance_mode`参数（auto/normal/aggressive/gentle），自动根据图片质量选择最佳预处理模式\n- **图像质量预检**：OCR引擎增加`check_image_quality()`函数，自动检测图片分辨率并给出预处理建议\n- **开箱即用性提升**：快速开始章节简化，一键安装脚本支持更多安装方式\n- **降级方案**：外部平台不可用时，给出详细的手工操作指南（见下方【外部平台不可用时的降级方案】）\n- **默认配置**：提供默认配置模板，基础功能无需配置即可使用\n- **文档优化**：快速开始章节重构，30秒即可了解核心步骤\n- **修复语句**：优化所有脚本的错误提示和操作建议，改为更自然、更易理解的中文表达\n\n**评测反馈响应**：\n- T(可信任度) 4.5/5 → 安全性提升，文件完整性校验\n- R(可靠性) 4.6/5 → 模糊发票识别率提升，预处理算法优化\n- A(适用性) 4.8/5 → 安装流程简化，开箱即用性提升\n- C(规范性) 4.8/5 → 文档结构优化，快速开始章节重构\n- E(有效性) 4.4/5 → OCR识别率提升，默认配置提供\n\n### v2.7.0 (2026-06-30)\n- **新增**：【使用技巧与注意事项】章节，汇总5项基本技巧+5项注意事项，一目了然\n- **新增**：【模糊发票处理指南】，4步流程应对图片模糊场景\n- **新增**：OCR引擎 `--manual` 手动输入模式，OCR失败时可直接手动输入发票信息\n- **新增**：长章节增加\"30秒摘要\"，减少阅读时间（快速开始/发票类型/限制说明/风险声明）\n- **新增**：OCR软件大小说明，解释60MB安装包的必要性（数据安全 vs 软件体积的权衡）\n- **改进**：手动输入模式支持金额勾稽自动检查，输入不一致会提示警告\n\n### v2.6.5 (2026-06-30)\n- **修复**：修复bug\n\n\n### v2.6.0 (2026-06-30)\n- **新增**：【如何「指挥」它干活】章节，包含自然语言对话示例表格（8种场景+详细说法）\n- **新增**：【常见问题速查】集中解答板块，按6大类（安装配置/OCR识别/查验审批/模板数据/安全合规）组织\n- **改进**：FAQ和常见问题从分散在多处改为集中速查表+详细解答两部分，查找更方便\n- **改进**：触发词章节扩展为更详细的\"如何指挥\"说明，降低用户上手门槛\n- **改进**：所有错误提示保持专业术语+通俗解释的平衡\n\n### v2.5.0 (2026-06-29)\n- **改进**：版本号升至 2.5.0\n- **改进**：图片质量要求增加\"图片质量自检清单\"，帮助用户提前发现图片问题\n- **改进**：图片质量要求增加扫描件推荐和手机扫描APP建议\n- **改进**：图片质量要求顶部增加醒目的\"识别效果高度依赖图片质量\"提醒\n- **改进**：FAQ Q2增加\"尝试用原始图片重新识别\"的排查建议\n- **改进**：FAQ Q9增加\"推荐使用扫描件\"和\"手机扫描APP预处理\"建议\n- **改进**：所有脚本错误提示在专业术语后增加通俗解释，方便非技术用户理解\n- **改进**：ocr_engine.py 低置信度阈值从0.6调整为0.7，更早提醒用户核对\n- **改进**：check_env.py 输出格式优化，失败项用更醒目的标识\n\n### v1.3.0 (2026-06-29)\n- **改进**：OCR引擎增加PSM模式回退机制（6→3→4→11→12）\n- **改进**：OCR引擎增加图片质量预检（尺寸、模式、亮度检查）\n- **改进**：OCR引擎提供详细的识别失败诊断和建议\n- **改进**：查验引擎增加参数格式校验和类型转换\n- **改进**：查验引擎增加重试机制和指数退避\n- **改进**：审批引擎增加Token获取重试和超时设置\n- **改进**：审批引擎增加报销单文件存在性检查\n- **改进**：审批引擎增加配置完整性验证\n- **改进**：发票解析器支持更多日期格式和金额格式\n- **改进**：发票解析器增加金额勾稽检查和日期有效性验证\n- **改进**：模板匹配器增加文件格式检查和表头完整性验证\n- **改进**：批量处理增加失败文件记录和统计\n- **改进**：环境预检增加Tesseract版本和语言包完整性检查\n- **改进**：错误代码速查表增加更多FAQ条目（Q9-Q14）\n- **改进**：所有脚本增强错误处理和容错能力\n\n### v1.1.0 (2026-06-29)\n- **新增**：环境预检脚本 `scripts/check_env.py`\n- **新增**：错误代码速查表\n- **新增**：发票图片质量要求和拍摄建议\n- **升级**：真伪查验引擎 `verify_engine.py`，真正对接国税总局/第三方平台\n- **升级**：审批引擎 `approval_engine.py`，真正获取Token并调用API\n- **升级**：安装脚本增加预检环节\n- **升级**：模板匹配支持PDF格式（需poppler）\n- **改进**：所有脚本增加更详细的错误提示\n- **改进**：配置文件中增加timeout设置\n\n### v1.0.0 (2026-06-28)\n- 初始版本发布\n- 支持增值税发票OCR识别\n- 支持多种查验引擎接口\n- 支持模板自适应学习\n- 支持多种审批平台对接\n\n## 税务风险预警\n\n本模块提供发票数据的风险检测功能，帮助企业在税务稽查前自查风险。\n\n### 检测方法\n\n| 检测项 | 说明 | 预警级别 |\n|--------|------|---------|\n| 连号检测 | 同一供应商连续开具多张连号发票 | 关注 |\n| 大额整数金额 | 发票金额为大额整数（如 100000.00 元） | 提示 |\n| 频繁开票 | 短时间内同一供应商开具大量发票 | 关注 |\n| 品名异常 | 发票品名与供应商经营范围不符 | 关注 |\n| 进销项匹配 | 进项发票品名与销项发票品名匹配度低 | 严重 |\n\n### 三级预警体系\n\n| 级别 | 说明 | 建议操作 |\n|------|------|---------|\n| 提示 | 低风险，可能存在异常 | 建议关注 |\n| 关注 | 中风险，需要核实 | 建议核实业务真实性 |\n| 严重 | 高风险，可能涉及虚开 | 建议立即处理 |\n\n### 使用方式\n\n```bash\npython scripts/risk_detector.py <path_to_invoices_json>\n```\n\n输出 JSON 格式的风险检测报告，包含所有检测结果和综合评估。\n\n## 电子档案合规归档\n\n本模块按照《电子发票全流程电子化管理指南》生成标准归档包，满足财政部和国家档案局对电子发票归档的要求。\n\n### 四性检测\n\n| 检测项 | 说明 |\n|--------|------|\n| 真实性 | 检测电子发票是否为原始真实文件，未经篡改 |\n| 完整性 | 检测电子发票文件是否完整，未损坏或缺失 |\n| 可用性 | 检测电子发票文件是否能正常打开、读取和使用 |\n| 安全性 | 检测电子发票文件是否安全，未被篡改或感染 |\n\n### 使用方式\n\n**单个文件四性检测**：\n```bash\npython scripts/archive_manager.py <path_to_invoice_file>\n```\n\n**批量归档（目录）**：\n```bash\npython scripts/archive_manager.py <path_to_directory>\n```\n\n**生成归档包**：\n```python\nfrom scripts.archive_manager import create_archive\npackage = create_archive([\"invoice1.pdf\", \"invoice2.xml\"], \"./output\")\n```\n\n### 归档包结构\n\n```\narchive_20260805_120000.zip\n├── metadata.json          # 元数据总表\n├── four_properties.json   # 四性检测报告\n├── invoice_data.json      # 结构化发票数据\n├── invoices/              # 原始发票文件\n│   ├── invoice_001.pdf\n│   └── invoice_002.xml\n└── README.txt             # 归档说明\n```\n\n## 银行流水对账\n\n本模块提供银行流水与发票数据的自动对账功能，解决财务人员手工核对耗时费力的痛点。\n\n### 支持的银行格式\n\n| 银行 | CSV 编码 | 日期格式 | 金额格式 | 状态 |\n|------|---------|---------|---------|------|\n| 工商银行 | UTF-8/GBK | YYYY-MM-DD | 借贷分离列 | ✅ 测试通过 |\n| 建设银行 | UTF-8/GBK | YYYY-MM-DD | 借贷分离列 | ✅ 测试通过 |\n| 农业银行 | UTF-8/GBK | YYYY/MM/DD | 借贷分离列 | ✅ 测试通过 |\n| 招商银行 | UTF-8 | YYYY-MM-DD | 正负金额列 | ✅ 测试通过 |\n| 中信银行 | UTF-8 | YYYY-MM-DD | 借贷分离列 | ✅ 测试通过 |\n| 其他银行 | 自动检测 | 自动识别 | 自动解析 | ✅ 自适应 |\n\n### 匹配算法\n\n| 维度 | 规则 | 权重 |\n|------|------|------|\n| 金额匹配 | ±0.01 元容差，超出后线性递减 | 60% |\n| 日期匹配 | ±3 天容差，超出后线性递减（30 天降为 0） | 40% |\n| 综合评分 | 金额分 × 0.6 + 日期分 × 0.4 | ≥0.85 视为匹配 |\n\n### 使用方式\n\n```bash\n# 基本对账\npython scripts/bank_reconciler.py --csv bank_statement.csv --invoices invoices.json\n\n# 自定义容差\npython scripts/bank_reconciler.py --csv bank.csv --invoices inv.json --amount-tol 0.05 --date-tol 5\n\n# 输出报告\npython scripts/bank_reconciler.py --csv bank.csv --invoices inv.json --output report.json\n```\n\n### 输出报告结构\n\n```json\n{\n  \"summary\": {\n    \"total_transactions\": 150,\n    \"matched\": 138,\n    \"unmatched\": 12,\n    \"match_rate\": \"92.0%\",\n    \"total_matched_amount\": 85642.50,\n    \"total_unmatched_amount\": 12350.00\n  },\n  \"unmatched_by_amount_range\": {\n    \"小额（<1000）\": 5,\n    \"中额（1000-10000）\": 4,\n    \"大额（10000-50000）\": 2,\n    \"超大额（≥50000）\": 1\n  }\n}\n```\n\n## 安全密钥配置\n\n本模块提供统一的密钥安全管理，消除配置文件中的明文泄露风险。\n\n### 环境变量命名规范\n\n| 密钥用途 | 环境变量名 | 示例 |\n|---------|-----------|------|\n| 钉钉 AppKey | `INVOICE_DINGTALK_APPKEY` | dik123xxx |\n| 钉钉 Secret | `INVOICE_DINGTALK_SECRET` | abc123xxx |\n| 企微 CorpID | `INVOICE_WECOM_CORP_ID` | wwxxxx |\n| 企微 Secret | `INVOICE_WECOM_SECRET` | abcxxxx |\n| 飞书 AppID | `INVOICE_FEISHU_APP_ID` | cli_xxx |\n| 飞书 Secret | `INVOICE_FEISHU_APP_SECRET` | abcxxx |\n| 百望云 API Key | `INVOICE_BAIRONG_API_KEY` | br_xxx |\n| 百望云 Secret | `INVOICE_BAIRONG_API_SECRET` | abcxxx |\n| 诺诺 API Key | `INVOICE_NUONUO_API_KEY` | nn_xxx |\n| 诺诺 Secret | `INVOICE_NUONUO_API_SECRET` | abcxxx |\n\n### 设置方式\n\n**Windows PowerShell（临时）**：\n```powershell\n$env:INVOICE_DINGTALK_APPKEY = \"你的AppKey\"\n$env:INVOICE_DINGTALK_SECRET = \"你的Secret\"\n```\n\n**Windows（永久，系统环境变量）**：\n```powershell\n[System.Environment]::SetEnvironmentVariable(\"INVOICE_DINGTALK_APPKEY\", \"你的AppKey\", \"User\")\n```\n\n**Linux/macOS**：\n```bash\nexport INVOICE_DINGTALK_APPKEY=\"你的AppKey\"\nexport INVOICE_DINGTALK_SECRET=\"你的Secret\"\n```\n\n### 使用方式\n\n```python\nfrom scripts.secure_config import SecureConfig\n\ncfg = SecureConfig()\n\n# 获取单个密钥\napp_key = cfg.get(\"DINGTALK_APPKEY\")\n\n# 获取平台完整配置\ndingtalk_cfg = cfg.get_dingtalk_config()\n\n# 调用 API 前校验\nresult = cfg.validate_before_call(\"dingtalk\")\nif result[\"ready\"]:\n    # 安全调用 API\n    pass\nelse:\n    print(f\"缺失配置: {result['missing']}\")\n```\n\n### CLI 检查\n\n```bash\n# 检查所有平台（默认输出字段名和布尔状态，不输出密钥值）\npython scripts/secure_config.py --platform all\n\n# 检查单个平台\npython scripts/secure_config.py --platform dingtalk\n\n# JSON 输出\npython scripts/secure_config.py --platform all --json\n```\n\n## 并行批量处理\n\n本模块提供硬件自适应的并行批量处理能力，自动根据 CPU 核心数和可用内存动态调整 worker 数量。\n\n### 硬件自适应策略\n\n| 硬件条件 | 处理模式 | Worker 数量 |\n|---------|---------|------------|\n| CPU ≥ 4 核 + 内存 > 2GB | 多进程 | CPU × 0.5 |\n| CPU 2-3 核 或 内存 1-2GB | 多线程 | CPU × 0.75 |\n| 内存 < 1GB | 串行 | 1 |\n\n### 使用方式\n\n**命令行使用**：\n```bash\n# 查看硬件信息和推荐配置\npython scripts/parallel_batch.py info\n\n# 自动模式批量处理\npython scripts/parallel_batch.py run --input D:\\invoices\\ --output result.json\n\n# 指定模式\npython scripts/parallel_batch.py run --input D:\\invoices\\ --output result.json --mode process\n```\n\n**Python 代码调用**：\n```python\nfrom scripts.parallel_batch import batch_process, get_hardware_info\n\n# 查看硬件信息\nhw = get_hardware_info()\nprint(f\"CPU: {hw['cpu_count']} 核, 推荐 worker: {hw['recommended_workers_process']}\")\n\n# 定义处理函数\ndef process_invoice(file_path: str) -> dict:\n    # 自定义处理逻辑\n    return {\"success\": True, \"file\": file_path}\n\n# 批量处理\nresult = batch_process(file_paths, process_invoice, mode=\"auto\")\nprint(f\"处理 {result.total_files} 个文件，成功 {result.success_count} 个\")\nprint(f\"耗时 {result.total_time_seconds:.1f} 秒，吞吐量 {result.to_dict()['throughput_per_second']} 个/秒\")\n```\n\n### 性能对比（参考）\n\n| 文件数 | 串行处理 | 并行处理（4核） | 加速比 |\n|--------|---------|---------------|--------|\n| 10 张 | 28 秒 | 8 秒 | 3.5× |\n| 50 张 | 140 秒 | 38 秒 | 3.7× |\n| 100 张 | 280 秒 | 75 秒 | 3.7× |\n| 200 张 | 560 秒 | 148 秒 | 3.8× |\n\n> 注：以上数据为 i5-10400F/16GB 测试环境参考值，实际加速比取决于 CPU 性能、内存大小和图片分辨率。\n\n## 免责声明\n\n本工具仅提供发票识别和报销单生成的技术支持，**不提供任何税务咨询或财务建议**。所有财务决策应由专业财务人员做出。使用者需确保符合当地法律法规。使用本工具即表示接受《风险声明》中的全部条款。\n\nFile v4.2.2:_meta.json\n\n{\n  \"ownerId\": \"kn7chdrwbdhaqkwajcyhtfvjx989ddb1\",\n  \"sl\n\nArchive v4.2.1: 44 files, 137817 bytes\n\nFiles: examples/example-approval.md (2757b), examples/example-ocr.md (1620b), examples/example-template.md (3025b), MEMORY.md (7285b), references/account_mapping.md (2148b), references/api-endpoints.md (3614b), references/expense_rules.md (1131b), references/risk_rules_config.yaml (1304b), references/risk-declaration.md (4304b), references/setup-guide.md (5647b), references/supplier_scope_rules.md (1683b), references/tax-rules.md (4732b), scripts/approval_abstract.py (9535b), scripts/approval_engine.py (20518b), scripts/archive_manager.py (20178b), scripts/bank_reconciler.py (17899b), scripts/batch_process.py (6297b), scripts/check_env.py (11739b), scripts/fiscal_parser.py (3907b), scripts/fixed_parser.py (4284b), scripts/flight_parser.py (4843b), scripts/install_tesseract.ps1 (9397b), scripts/install_tesseract.sh (3959b), scripts/invoice_detector.py (13976b), scripts/ocr_engine.py (26014b), scripts/ofd_parser.py (7327b), scripts/parallel_batch.py (14102b), scripts/receipt_parser.py (11799b), scripts/risk_detector.py (15191b), scripts/secure_config.py (9299b), scripts/smart_classifier.py (6220b), scripts/taxi_parser.py (4550b), scripts/template_matcher.py (15174b), scripts/toll_parser.py (4705b), scripts/train_parser.py (4191b), scripts/unified_invoice.py (6056b), scripts/verify_abstract.py (9938b), scripts/verify_engine.py (13326b), scripts/voucher_generator.py (8728b), scripts/xml_parser.py (11186b), skill-card.md (3109b), SKILL.md (58224b), templates/config_template.yaml (2145b), _meta.json (137b)\n\nArchive v4.2.0: 44 files, 137404 bytes\n\nFiles: examples/example-approval.md (2757b), examples/example-ocr.md (1620b), examples/example-template.md (3025b), MEMORY.md (7285b), references/account_mapping.md (2148b), references/api-endpoints.md (3614b), references/expense_rules.md (1131b), references/risk_rules_config.yaml (1304b), references/risk-declaration.md (4304b), references/setup-guide.md (5647b), references/supplier_scope_rules.md (1683b), references/tax-rules.md (4732b), scripts/approval_abstract.py (9535b), scripts/approval_engine.py (20518b), scripts/archive_manager.py (20178b), scripts/bank_reconciler.py (17899b), scripts/batch_process.py (6297b), scripts/check_env.py (11658b), scripts/fiscal_parser.py (3907b), scripts/fixed_parser.py (4284b), scripts/flight_parser.py (4843b), scripts/install_tesseract.ps1 (9291b), scripts/install_tesseract.sh (3959b), scripts/invoice_detector.py (13976b), scripts/ocr_engine.py (26014b), scripts/ofd_parser.py (7327b), scripts/parallel_batch.py (14102b), scripts/receipt_parser.py (11799b), scripts/risk_detector.py (15191b), scripts/secure_config.py (8693b), scripts/smart_classifier.py (6220b), scripts/taxi_parser.py (4550b), scripts/template_matcher.py (15174b), scripts/toll_parser.py (4705b), scripts/train_parser.py (4191b), scripts/unified_invoice.py (6056b), scripts/verify_abstract.py (9938b), scripts/verify_engine.py (13326b), scripts/voucher_generator.py (8728b), scripts/xml_parser.py (11186b), skill-card.md (3591b), SKILL.md (57529b), templates/config_template.yaml (2145b), _meta.json (137b)\n\nArchive v4.1.0: 41 files, 121954 bytes\n\nFiles: examples/example-approval.md (2757b), examples/example-ocr.md (1620b), examples/example-template.md (3025b), MEMORY.md (7285b), references/account_mapping.md (2148b), references/api-endpoints.md (3614b), references/expense_rules.md (1131b), references/risk_rules_config.yaml (1304b), references/risk-declaration.md (4304b), references/setup-guide.md (5647b), references/supplier_scope_rules.md (1683b), references/tax-rules.md (4732b), scripts/approval_abstract.py (9535b), scripts/approval_engine.py (20518b), scripts/archive_manager.py (20178b), scripts/batch_process.py (6297b), scripts/check_env.py (11658b), scripts/fiscal_parser.py (3907b), scripts/fixed_parser.py (4284b), scripts/flight_parser.py (4843b), scripts/install_tesseract.ps1 (9291b), scripts/install_tesseract.sh (3959b), scripts/invoice_detector.py (13976b), scripts/ocr_engine.py (26014b), scripts/ofd_parser.py (7327b), scripts/receipt_parser.py (11799b), scripts/risk_detector.py (15191b), scripts/smart_classifier.py (6220b), scripts/taxi_parser.py (4550b), scripts/template_matcher.py (15174b), scripts/toll_parser.py (4705b), scripts/train_parser.py (4191b), scripts/unified_invoice.py (6056b), scripts/verify_abstract.py (9938b), scripts/verify_engine.py (13326b), scripts/voucher_generator.py (8728b), scripts/xml_parser.py (11186b), skill-card.md (3245b), SKILL.md (51604b), templates/config_template.yaml (2145b), _meta.json (137b)\n\nArchive v4.0.0: 37 files, 108587 bytes\n\nFiles: examples/example-approval.md (2757b), examples/example-ocr.md (1620b), examples/example-template.md (3025b), MEMORY.md (6021b), references/account_mapping.md (2148b), references/api-endpoints.md (3614b), references/expense_rules.md (1131b), references/risk-declaration.md (4304b), references/setup-guide.md (5647b), references/tax-rules.md (4732b), scripts/approval_abstract.py (9535b), scripts/approval_engine.py (20518b), scripts/batch_process.py (6297b), scripts/check_env.py (11658b), scripts/fiscal_parser.py (3907b), scripts/fixed_parser.py (4284b), scripts/flight_parser.py (4843b), scripts/install_tesseract.ps1 (9291b), scripts/install_tesseract.sh (3959b), scripts/invoice_detector.py (13976b), scripts/ocr_engine.py (26014b), scripts/ofd_parser.py (7327b), scripts/receipt_parser.py (11799b), scripts/smart_classifier.py (6220b), scripts/taxi_parser.py (4550b), scripts/template_matcher.py (15174b), scripts/toll_parser.py (4705b), scripts/train_parser.py (4191b), scripts/unified_invoice.py (6056b), scripts/verify_abstract.py (9938b), scripts/verify_engine.py (13326b), scripts/voucher_generator.py (8728b), scripts/xml_parser.py (11186b), skill-card.md (2746b), SKILL.md (48294b), templates/config_template.yaml (2145b), _meta.json (137b)\n\nArchive v3.7.0: 27 files, 86579 bytes\n\nFiles: examples/example-approval.md (2757b), examples/example-ocr.md (1620b), examples/example-template.md (3025b), MEMORY.md (4220b), references/api-endpoints.md (3614b), references/risk-declaration.md (4304b), references/setup-guide.md (5647b), references/tax-rules.md (4732b), scripts/approval_abstract.py (9535b), scripts/approval_engine.py (20518b), scripts/batch_process.py (6297b), scripts/check_env.py (11658b), scripts/install_tesseract.ps1 (9291b), scripts/install_tesseract.sh (3959b), scripts/invoice_detector.py (7800b), scripts/ocr_engine.py (26014b), scripts/ofd_parser.py (7327b), scripts/receipt_parser.py (11799b), scripts/template_matcher.py (15174b), scripts/unified_invoice.py (3037b), scripts/verify_abstract.py (9938b), scripts/verify_engine.py (13326b), scripts/xml_parser.py (11186b), skill-card.md (3212b), SKILL.md (46787b), templates/config_template.yaml (2145b), _meta.json (137b)\n\nArchive v3.4.0: 23 files, 74087 bytes\n\nFiles: examples/example-approval.md (2757b), examples/example-ocr.md (1620b), examples/example-template.md (3025b), MEMORY.md (1820b), references/api-endpoints.md (3614b), references/risk-declaration.md (4304b), references/setup-guide.md (5647b), references/tax-rules.md (4732b), scripts/approval_abstract.py (9535b), scripts/approval_engine.py (20518b), scripts/batch_process.py (6297b), scripts/check_env.py (11658b), scripts/install_tesseract.ps1 (9291b), scripts/install_tesseract.sh (3959b), scripts/ocr_engine.py (26014b), scripts/receipt_parser.py (11799b), scripts/template_matcher.py (15174b), scripts/verify_abstract.py (9938b), scripts/verify_engine.py (13326b), skill-card.md (3112b), SKILL.md (44141b), templates/config_template.yaml (2145b), _meta.json (137b)\n\nArchive v3.3.0: 23 files, 74433 bytes\n\nFiles: examples/example-approval.md (2754b), examples/example-ocr.md (1620b), examples/example-template.md (3025b), MEMORY.md (2237b), references/api-endpoints.md (3611b), references/risk-declaration.md (4304b), references/setup-guide.md (5644b), references/tax-rules.md (4732b), scripts/approval_abstract.py (9529b), scripts/approval_engine.py (20518b), scripts/batch_process.py (6297b), scripts/check_env.py (11666b), scripts/install_tesseract.ps1 (9756b), scripts/install_tesseract.sh (3959b), scripts/ocr_engine.py (26014b), scripts/receipt_parser.py (11799b), scripts/template_matcher.py (15174b), scripts/verify_abstract.py (9938b), scripts/verify_engine.py (13325b), skill-card.md (3152b), SKILL.md (43552b), templates/config_template.yaml (2145b), _meta.json (137b)","readmeExcerpt":"Skill: receipt-compliance Owner: fyniujin Summary: 会计助手：发票OCR识别→真伪查验→报销单自动填充→对接审批系统。企业自主配置，数据本地处理。 Tags: latest:4.5.0 Version history: v4.5.0 | 2026-10-09T09:13:27.116Z | auto **Summary:** 版本 4.5.0 增加票据合规能力、查重排查、异常检测和审批对接等模块，拓展财税应用链路和报销合规场景。 - 新增进/销项台账统计、认证期限日历、异常检测、重复报销查重、查重工单等合规和风险管理功能 - 引入审批连接器模块，统一对接钉钉/企业微信/飞书（含回调验签） - 支持数电票 PDF/OFD 文本层直读与二维码内容核对 - 新增合规管理一键导出及归档四性检测合并 - 支持可疑工单清单对照、HTML复核输出，提升财务查重和误报豁免效率 - 新增 SQLi","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"步骤1：判断图片质量\n  → 图片分辨率<200DPI？ → 重新拍摄/扫描\n  → 有反光/阴影？       → 换个角度或光线重拍\n  → 发票褶皱严重？      → 展平后重新扫描\n\n步骤2：使用扫描APP预处理（推荐）\n  → 扫描全能王 / 白描 / 微信扫一扫\n  → APP会自动增强对比度、去阴影、纠偏\n  → 保存为JPG后重新识别\n\n步骤3：识别后人工核对\n  → 重点核对：发票代码(10-12位数字)、号码(8-20位数字)、金额\n  → 金额勾稽检查：金额 + 税额 = 价税合计？\n  → 置信度<0.7的字段重点核对\n\n步骤4：手动输入（终极方案）\n  → 如果反复识别失败，可直接手动输入发票信息\n  → 格式：python scripts/ocr_engine.py --manual\n  → 按提示输入发票代码、号码、日期、金额等"},{"language":"text","snippet":"用户：请帮我识别这张发票 D:\\invoices\\20260628_001.png\nAI：正在识别发票...\n    ✓ 发票类型: 增值税专用发票\n    ✓ 发票代码: 3100204130\n    ✓ 发票号码: 00564189\n    ✓ 开票日期: 2026年06月28日\n    ✓ 金额: 10,000.00 元\n    ✓ 税额: 1,300.00 元\n    识别完成，已保存到 receipt.json"},{"language":"text","snippet":"用户：把文件夹里所有发票都识别出来\nAI：正在批量识别 D:\\invoices\\ 中的发票...\n    共发现 15 个图片文件\n    ✓ 20260628_001.png - 识别成功\n    ✓ 20260628_002.png - 识别成功\n    ⚠ 20260628_003.png - 识别失败（图片模糊）\n    ...\n    处理完成：成功 12 张，失败 3 张\n    结果已保存到 batch_result.json"},{"language":"text","snippet":"用户：帮我查验这张发票的真伪\nAI：正在查验发票...\n    发票代码：3100204130\n    发票号码：00564189\n    ✓ 查验平台：国税总局\n    ✓ 发票状态：正常\n    ✓ 查验时间：2026-06-29 10:30:00"},{"language":"text","snippet":"用户：用公司模板生成报销单\nAI：正在生成报销单...\n    ✓ 识别到 6 个字段映射\n    ✓ 已填充：开票日期、销方名称、金额、税额、价税合计、费用说明\n    报销单已生成：D:\\output\\expense_report.xlsx"},{"language":"python","snippet":"from scripts.ocr_engine import OCREngine\n\n# 初始化引擎\nengine = OCREngine()\n\n# 识别单张发票\nresult = engine.extract_structured_data(\"invoice.png\")\nprint(f\"发票代码: {result['invoice_code']}\")\nprint(f\"金额: {result['amount']}\")\n\n# 批量处理\nimport glob\nfor file in glob.glob(\"invoices/*.png\"):\n    result = engine.extract_structured_data(file)\n    print(f\"{file}: {result['success']}\")"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: receipt-compliance\ndescription: 会计助手：发票OCR识别→真伪查验→报销单自动填充→对接审批系统。企业自主配置，数据本地处理。\nversion: 4.5.0\n---\n\n\n# 会计助手\n\n> ⚠️ **使用必读**：本Skill所有功能在本地运行，发票数据绝不外传，但**绝不提供税务咨询**。使用前请先阅读【限制说明】和【风险声明】。\n\n## 功能说明\n\n本Skill提供从发票识别到审批提交的**全链路**财税合规能力。\n\n| 模块 | 功能 | 状态 | 输入 | 输出 |\n|------|------|------|------|------|\n| 1. 发票OCR识别 | 双引擎（PaddleOCR优先+Tesseract兜底），定额票先验定位，勾稽校验 | ✅ 直接可用 | 发票图片/PDF | 结构化JSON |\n| 2. 真伪查验 | 一键生成国税总局查验链接，自动打开浏览器 | ✅ 直接可用 | 发票代码/号码 | 查验链接+结果 |\n| 3. 报销单填充 | 自适应学习模板，一键填充 | ✅ 直接可用 | 发票数据+模板 | Excel文件 |\n| 4. 审批对接 | 对接钉钉/企微/飞书审批（有完整代码模板） | ⚠️ 需配置密钥 | 报销单+配置 | 审批结果 |\n| 5. 全电发票 | 全电发票XML/OFD格式解析 | ✅ 直接可用 | 全电发票文件 | 结构化JSON |\n| 6. 多票据支持 | 火车票/飞机票/出租车/定额发票/通行费/财政票据 | ✅ 直接可用 | 票据图片 | 统一结构化JSON |\n| 7. 智能分类 | 自动匹配会计科目、计算进项税、生成凭证摘要 | ✅ 直接可用 | 结构化发票数据 | 分类结果+科目 |\n| 8. 记账凭证 | 自动生成记账凭证（用友/金蝶/QuickBooks格式） | ✅ 直接可用 | 分类结果 | 凭证文件 |\n| 9. 风险预警 | 发票连号/整数金额/频繁开票/品名异常/进销项匹配检测 | ✅ 直接可用 | 发票列表 | 三级预警报告 |\n| 10. 归档管理 | 电子档案四性检测、归档包生成、元数据采集、目录索引 | ✅ 直接可用 | 发票文件 | 标准归档包 |\n| 11. 银行对账 | 银行流水 CSV 解析 + 发票金额/日期模糊匹配 | ✅ 直接可用 | 流水 CSV + 发票数据 | 对账报告 |\n| 12. 安全配置 | 环境变量读取密钥，消除明文泄露 | ✅ 直接可用 | 环境变量 | 安全配置 |\n| 13. 并行批量 | 硬件自适应并行处理，速度提升 3-5 倍 | ✅ 直接可用 | 发票文件夹 | 批量结果 |\n| 14. 混拍切分 | 混拍图（一拍多票）自动检测切分，保持原图索引 | ✅ 直接可用 | 混拍图片 | 单票子图 |\n| 15. 进销项台账 | SQLite 台账 + 月度统计，税负率趋势/供应商集中度/异常波动 | ✅ 直接可用 | 票据解析结果 | Excel 月度附件 |\n| 16. 认证期日历 | 认证期限取数 + 30/7 天两档提醒 + CSV 导出 | ✅ 直接可用 | 台账 | 到期清单 |\n| 17. 异常检测 | 轻量 Isolation Forest，金额/间隔/供应商三维打分 | ✅ 直接可用 | 票据列表 | 二级预警+触发维度 |\n| 18. 合规管理出口 | 规则预警 + 归档四性检测合并为一次执行 | ✅ 直接可用 | 票据 + 文件 | 统一合规报告 |\n| 19. 审批连接器 | 钉钉/企微/飞书统一接口（发送/查状态/回调验签） | ⚠️ 需配置密钥 | 报销单+配置 | 审批结果 |\n| 20. 数电票直读 | PDF/OFD 文本层结构化（pypdf 优先，缺失降级 OFD/PDF 文本）+ 二维码 TLV 解码核对 | ✅ 直接可用 | 数电票 PDF/OFD | 结构化 JSON（含明细行） |\n| 21. 重复报销查重 | 三信号两阶段：票号精确哈希 + 金额（±0.01）+ 日期（±3 天）近似比对，检出 P 图改抬头重复 | ✅ 直接可用 | 台账/票据列表 | 重复组清单 |\n| 22. 查重复工单 | 可疑项生成复核清单（两张原始凭证缩略图对照+差异标注，移动端可读），财务确认后进台账/误报标记豁免 | ⚠️ 需台账 | 复核清单 | HTML 对照页 |\n\n> ✅ = 装即用 ｜ ⚠️ = 需在 config.yaml 中配置对应API密钥\n>\n> 💡 **核心亮点**：发票识别、真伪查验、报销单生成 —— 这三项功能**完全不需要任何配置**，安装即用！\n\n### 设计理念\n\n1. **数据安全第一**：所有发票数据处理均在本地，不会上传到任何服务器\n2. **企业自主决策**：查验引擎、审批平台的选择权完全交给企业\n3. **透明开源**：所有代码可见可审计，无隐藏后门\n4. **渐进披露**：基础功能开箱即用，高级功能按配置解锁\n\n## 如何「指挥」它干活\n\n本Skill支持**自然语言对话**，不需要记忆任何命令。以下是各种场景下你可以直接对AI说的话：\n\n### 💬 直接用自然语言说\n\n| 你想做什么 | 直接这样说 |\n|-----------|-----------|\n| 识别一张发票 | \"帮我识别这张发票\" / \"OCR一下这个发票\" / \"扫描这张发票\" |\n| 批量识别 | \"把文件夹里所有发票都识别出来\" / \"批量扫描D:\\invoices\" |\n| 查验真伪 | \"帮我查验这张发票的真伪\" / \"查一下这个发票是不是真的\" |\n| 生成报销单 | \"用公司模板生成报销单\" / \"把识别结果填到报销单里\" |\n| 提交审批 | \"提交报销审批\" / \"发起审批\" / \"把报销单提交给钉钉审批\" |\n| 批量处理 | \"批量识别并生成报销单\" / \"把整个文件夹的发票都处理完\" |\n| 环境检查 | \"检查环境是否就绪\" / \"运行预检\" |\n| 查看帮助 | \"这个Skill能做什么\" / \"怎么用\" |\n\n### 📋 更详细的说法（推荐）\n\n**识别发票**：\n- \"请帮我识别这张发票：D:\\发票\\20260628.png\"\n- \"扫描这张发票，我要报销\"\n- \"OCR这张发票，结果保存到receipt.json\"\n\n**批量处理**：\n- \"把D:\\invoices\\里所有发票都识别出来，结果保存到output.json\"\n- \"批量扫描发票文件夹，然后生成合并报销单\"\n\n**查验真伪**：\n- \"帮我查验发票 代码:3100204130 号码:00564189\"\n- \"查一下这张发票是不是真的，发票号是00564189\"\n\n**生成报销单**：\n- \"用模板D:\\templates\\报销单.xlsx生成报销单\"\n- \"把receipt.json的数据填到报销单模板里\"\n\n**提交审批**：\n- \"把报销单提交到钉钉审批\"\n- \"发起企业微信审批，报销金额11300元\"\n\n> 💡 **小贴士**：直接上传发票图片或告诉AI文件"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7chdrwbdhaqkwajcyhtfvjx989ddb1\",\n  \"slug\": \"receipt-compliance\",\n  \"version\": \"4.5.0\",\n  \"publishedAt\": 1791537207116\n}"},{"path":"references/account_mapping.md","content":"# 会计科目对照表\n\n本文件定义了发票费用类型与会计科目的映射关系，用于自动生成记账凭证。\n\n## 借方科目（费用类）\n\n| 费用类型 | 科目代码 | 科目名称 | 说明 |\n|---------|---------|---------|------|\n| 差旅费 | 6602.01 | 管理费用-差旅费 | 员工出差交通、住宿、餐饮等 |\n| 办公费 | 6602.02 | 管理费用-办公费 | 办公用品、耗材、打印等 |\n| 业务招待费 | 6602.03 | 管理费用-业务招待费 | 餐饮、礼品等招待支出 |\n| 广告费 | 6601.01 | 销售费用-广告费 | 广告投放、品牌推广 |\n| 咨询费 | 6602.04 | 管理费用-咨询费 | 法律、审计、税务等顾问 |\n| 交通费 | 6602.05 | 管理费用-交通费 | 市内打车、公交、地铁 |\n| 通行费 | 6602.06 | 管理费用-通行费 | 高速、桥闸通行费 |\n| 福利费 | 6602.07 | 管理费用-福利费 | 员工体检、节日福利 |\n| 租赁费 | 6602.08 | 管理费用-租赁费 | 房租、物业费 |\n| 维修费 | 6602.09 | 管理费用-维修费 | 设备维修保养 |\n| 其他费用 | 6602.99 | 管理费用-其他 | 其他杂项支出 |\n\n## 借方科目（税费类）\n\n| 科目代码 | 科目名称 | 说明 |\n|---------|---------|------|\n| 2221.01 | 应交税费-应交增值税-进项税额 | 可抵扣进项税 |\n\n## 贷方科目（支付类）\n\n| 科目代码 | 科目名称 | 说明 |\n|---------|---------|------|\n| 1002 | 银行存款 | 默认支付方式 |\n| 1002.01 | 银行存款-转账 | 银行转账 |\n| 1001 | 库存现金 | 现金支付 |\n\n## 进项税抵扣率\n\n| 票据类型 | 抵扣率 | 说明 |\n|---------|--------|------|\n| 火车票 | 9% | 按票面金额计算抵扣 |\n| 飞机票 | 9% | 票价+燃油费，不含民航发展基金 |\n| 高速通行费 | 3% | 按通行费计算抵扣 |\n| 桥闸通行费 | 5% | 按通行费计算抵扣 |\n| 增值税专票（13%） | 13% | 按票面税额抵扣 |\n| 增值税专票（6%） | 6% | 按票面税额抵扣 |\n| 增值税专票（3%） | 3% | 按票面税额抵扣 |\n| 增值税普票 | 0% | 不可抵扣 |\n| 定额发票 | 0% | 不可抵扣 |\n| 财政票据 | 0% | 不可抵扣 |"},{"path":"references/api-endpoints.md","content":"# API 端点说明\n\n本文档列出各平台API的接入方式和注意事项。\n\n---\n\n## 一、查验平台 API\n\n### 1.1 国税总局查验平台\n\n- **网址**: https://inv-veri.chinatax.gov.cn/\n- **接口类型**: HTTP表单提交（需要处理验证码）\n- **是否免费**: ✓ 完全免费\n- **接入难度**: ★★★（需要处理验证码和反爬机制）\n- **建议**: 仅在用户明确授权下发起单条查验请求，控制频率\n\n### 1.2 百望云 API\n\n- **网址**: https://www.bairong.com\n- **接口类型**: RESTful API\n- **认证方式**: API Key + Secret\n- **是否免费**: ✗ 按量付费或包年\n- **接入难度**: ★★☆（企业资质申请偏难）\n\n### 1.3 诺诺发票 API\n\n- **网址**: https://www.nuonuo.com\n- **接口类型**: RESTful API\n- **认证方式**: API Key + Secret\n- **是否免费**: ✗ 按量付费或包年\n- **接入难度**: ★★☆（接口文档齐全）\n\n---\n\n## 二、审批平台 API\n\n### 2.1 钉钉审批\n\n- **网址**: https://open-dev.dingtalk.com\n- **审批API**: 钉钉开放平台 → 审批 → 流程引擎\n- **认证方式**: AppKey + AppSecret → OAuth2.0 Token\n- **接入步骤**:\n  1. 创建企业内部应用\n  2. 开通审批权限\n  3. 创建审批流程模板\n  4. 获取流程编码\n\n### 2.2 企业微信审批\n\n- **网址**: https://developer.weixin.qq.com\n- **审批API**: 企业微信 → 审批 → 模板管理\n- **认证方式**: CorpID + Secret → AccessToken\n- **接入步骤**:\n  1. 注册企业微信管理后台\n  2. 创建审批模板\n  3. 获取模板ID和审批字段\n\n### 2.3 飞书审批\n\n- **网址**: https://open.feishu.cn\n- **审批API**: 飞书开放平台 → 审批 → 审批实例\n- **认证方式**: App ID + App Secret → Tenant Access Token\n- **接入步骤**:\n  1. 创建企业自建应用\n  2. 开通审批权限\n  3. 获取审批编码\n\n---\n\n## 三、API 调用示例\n\n### 3.1 钉钉审批提交示例（伪代码）\n\n```python\n# 获取钉钉 AccessToken\ndef get_dingtalk_token(app_key, app_secret):\n    url = \"https://api.dingtalk.com/v1.0/oauth2/accessToken\"\n    payload = {\"appKey\": app_key, \"appSecret\": app_secret}\n    # ...\n\n# 提交审批\ndef submit_dingtalk_approval(token, process_code, formData):\n    url = f\"https://api.dingtalk.com/v1.0/approval/processInstances\"\n    # ...\n```\n\n### 3.2 企业微信审批提交示例（伪代码）\n\n```python\n# 获取企业微信 AccessToken\ndef get_wecom_token(corp_id, secret):\n    url = f\"https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid={corp_id}&corpsecret={secret}\"\n    # ...\n\n# 提交审批\ndef submit_wecom_approval(token, template_id, apply_data):\n    url = f\"https://qyapi.weixin.qq.com/cgi-bin/approval/submit?access_token={token}\"\n    # ...\n```\n\n---\n\n## 四、安全建议\n\n1. **API密钥分散存储**：不同平台使用不同密钥，避免一损俱损\n2. **调用频率限制**：建议每分钟不超过10次查验/审批请求\n3. **错误重试机制**：失败时自动重试最多3次，指数退避\n4. **日志审计**：记录所有API调用，便于追踪和审计\n\n---\n\n## 五、接口调用频率限制\n\n| 平台 | 建议最低间隔 | 日调用上限建议 |\n|------|-------------|---------------|\n| 国税总局 | 无官方限制 | 建议 ≤ 1000次/日 |\n| 百望云 | 按套餐而定 | 查看服务协议 |\n| 诺诺发票 | 按套餐而定 | 查看服务协议 |\n| 钉钉审批 | 无官方限制 | 建议 ≤ 1000次/日 |\n| 企业微信审批 | 无官方限制 | 建议 ≤ 500次/日 |\n| 飞书审批 | 无官方限制 | 建议 ≤ 1000次/日 |\n\n> 以上限制仅供参考，请以各平台官方文档为准。"},{"path":"references/expense_rules.md","content":"# 费用分类规则\n\n本文件定义了根据发票/票据内容自动匹配费用类型的规则。\n\n## 关键词匹配规则\n\n| 费用类型 | 触发关键词 |\n|---------|-----------|\n| 差旅费 | 酒店、住宿、机票、火车票、高铁、动车、打车、出租车、滴滴 |\n| 办公费 | 办公用品、文具、打印、复印、耗材、电脑、鼠标、键盘 |\n| 业务招待费 | 餐饮、食品、招待、餐厅、饭店、酒楼 |\n| 广告费 | 广告、推广、宣传、营销、品牌、投放 |\n| 咨询费 | 咨询、顾问、法律、审计、税务代理 |\n| 交通费 | 打车、出租车、滴滴、公交、地铁 |\n| 通行费 | 通行费、高速、桥闸、过路费 |\n| 福利费 | 福利、员工、生日、节日、体检 |\n| 租赁费 | 租赁、房租、物业、水电 |\n| 维修费 | 维修、修理、维护、保养 |\n\n## 按票据类型直接分类\n\n| 票据类型 | 默认费用类型 |\n|---------|-------------|\n| 火车票 | 差旅费 |\n| 飞机行程单 | 差旅费 |\n| 出租车票 | 交通费 |\n| 通行费票据 | 通行费 |\n| 财政票据 | 财政票据（不可抵扣） |"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"会计助手：发票OCR识别→真伪查验→报销单自动填充→对接审批系统。企业自主配置，数据本地处理。 Skill: receipt-compliance Owner: fyniujin Summary: 会计助手：发票OCR识别→真伪查验→报销单自动填充→对接审批系统。企业自主配置，数据本地处理。 Tags: latest:4.5.0 Version history: v4.5.0 | 2026-10-09T09:13:27.116Z | auto **Summary:** 版本 4.5.0 增加票据合规能力、查重排查、异常检测和审批对接等模块，拓展财税应用链路和报销合规场景。 - 新增进/销项台账统计、认证期限日历、异常检测、重复报销查重、查重工单等合规和风险管理功能 - 引入审批连接器模块，统一对接钉钉/企业微信/飞书（含回调验签） - 支持数电票 PDF/OFD 文本层直读与二维码内容核对 - 新增合规管理一键导出及归档四性检测合并 - 支持可疑工单清单对照、HTML复核输出，提升财务查重和误报豁免效率 - 新增 SQLi","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":648,"uniquenessScore":62,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T04:54:32.040Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T04:54:32.040Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-11T07:42:50.526Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}