跨境卖家出海前要回答的第一个问题永远是"这个市场对我这类产品有什么强制性要求"——但答案分散在十几个国家的官方网站、标准目录、认证机构公告里，语言不通、时效不明、真假难辨。RegPilot 是一个基于 LangGraph 的合规情报系统：给定「目标市场（可一个或多个）+ 产品类别 + 可选产品参数/销售上下文」，自动完成澄清追问、规划检索策略、多轨检索法规原文、判定每条结果的身份与可信度、对存疑条目二次核实与深挖，若涉及多市场则并行调度并输出结构化的跨市场对比与优先级排序，最终产出带明确风险标注的合规情报报告。
初版聚焦便携式充电宝品类，覆盖 EU / US / UK / JP / KR / AU / SA·UAE / IN / TH / BR 共10个市场；产品属性驱动的过滤机制已为多品类扩展预留（详见下方"当前局限"）。
English summary: RegPilot is a LangGraph-based regulatory intelligence system for cross-border sellers. Given one or more target markets and a product category (optionally with product attributes and sales context), it clarifies ambiguous input through structured multi-round dialogue, plans a retrieval strategy from a YAML-first configuration, searches for applicable regulations across official and standards-body sources, identifies which specific regulation each result corresponds to, scores source credibility and relevance, re-verifies stale or disputed entries, deep-dives into confirmed regulations for concrete test items / certification process / timeline / cost estimates, and — when multiple markets are involved — orchestrates parallel per-market pipelines and produces a cross-market comparison with structural conflict detection and priority ranking. Every report is explicit about what it doesn't know: forced-retain placeholders, identity-protected low-relevance items, and disputed-threshold clarifications are all surfaced, not silently dropped. Initial scope: portable power banks across 10 markets. Built with Python + LangGraph + Tavily search + DeepSeek. Full architecture map and 8 in-depth technical documents (in Chinese) are linked below.
关于定位的诚实说明：本系统当前是一个结合了若干"有界自主"决策点的工作流系统，不是完全自主决策的通用 Agent——大部分执行路径（法规清单加载、身份判定、状态判定）仍是确定性规则，真正体现"运行时依赖上下文做判断"的自主性点集中在三处：多市场并行调度与结构性冲突处理、node_reflect 的 gap-driven 二次搜索重试、node_deep_dive 的信息充分性判断循环。这条边界判断的完整论证见 docs/Overview.md 第五节"核心设计原则"与第七节"架构演进：从固定规则到有界自主"，本 README 不重新定义这个判断标准，只引用其结论。
系统由三个独立编译的 LangGraph 组成，自底向上分别解决三个不同层面的问题：
flowchart TD
subgraph parse_graph["parse_graph（输入解析与澄清）"]
PI[parse_input<br/>统一解析：市场列表/品类/产品属性/<br/>销售上下文/未映射内容，含幻觉防护]
CMC[clarify_market_category<br/>市场或品类未识别时的追问中断]
AG[attribute_gateway<br/>disputed_threshold法规的<br/>数值阈值结构化澄清]
PI -->|未识别且未超限| CMC
PI -->|解析成功| AG
CMC -->|resume后回到| PI
AG -->|仍有待澄清属性，resume后回到| PI
end
subgraph orchestrator["orchestrator_graph（多市场编排）"]
FANOUT[fan_out<br/>为每个目标市场生成Send任务]
RM[run_market<br/>子进程内完整跑一次main_graph]
JOIN[join_markets] --> COMPARE[compare<br/>统计对比+优先级排序+冲突探测]
COMPARE --> FINALIZE[finalize<br/>渲染最终对比报告]
FANOUT -.Send.-> RM --> JOIN
end
subgraph main_graph["main_graph（单市场主流程，独立进程内运行）"]
A[input] --> B[plan] --> C[retrieve] --> D[identify] --> E[validate] --> F[reflect] --> G[deep_dive] --> H[report]
end
parse_graph -->|main.py构建run_id后调用| orchestrator
RM -.进程内完整调用.-> main_graph
节点间仅通过各自的 State（RegPilotState/OrchestratorState）传递数据，禁止直接调用；identify 判定的 regulation_id 与 attribute_gateway 产出的 disputed_threshold_judgments 一经写入，下游节点全程只读。三层图为什么不能合并、orchestrator_graph 为什么用进程级隔离而非线程/协程、State 如何跨三层流转，完整说明见 docs/Overview.md 第二、三节。
- YAML-first 配置驱动：新增市场或法规只改
markets.yaml，无需碰代码；LLM 全程不参与法规清单的生成或增删，只在确定清单之上做打分/文案组织 - 统一输入解析与两类结构化追问：单次自由文本一次性抽取市场（支持多个）、品类、产品属性、销售上下文，未识别时自动追问；对适用性依赖连续数值变量的存疑法规（如电压阈值），在生成检索计划前就用
interrupt()/Command(resume=...)结构化多轮确认，而非等报告生成后才靠一段短摘要语义猜测 - 产品属性驱动的适用性过滤：
applies_when二元闸门（如"是否含无线充电"）+disputed_threshold三态判断（确定适用/确定不适用/未确认）双机制，法规清单在检索之前就按产品真实形态收窄 - 多轨检索 + 身份归属：结合人工核实锚点、官方目录页窄查询、关键词检索，独立环节判定每条结果对应哪条具体法规，避免因标题格式差异误判丢弃核心法规
- 五层过滤与可信度评分：来源权威性、时效性、语义相关性多维度加权评分，fast/full 双档 LLM 路由控制成本，
determine_status()是全流程唯一硬否决点 - gap-driven 二次补全：核心法规检索结果不理想时，LLM 先诊断"具体缺什么类型的信息"（官方确认/适用范围/时效性三选一），再针对性拼接检索词重试，而非盲目重复同一查询
- Deep Dive 决策支持：对已确认适用的法规，进一步检索并产出具体测试项、认证流程、责任主体、预估周期与费用区间——从"有哪些法规"跃迁到"具体怎么做、大概多久多少钱"，抽不到具体数字时诚实占位，不编造
- 多市场并行编排：单次输入可覆盖多个市场，
Sendfan-out + 进程级隔离并行执行，自动产出跨市场统计对比、确定性优先级排序（不经 LLM）、结构性冲突探测（同一底层标准跨市场状态不一致时提示），某市场失败不影响其余市场正常展示 - 兜底透明化：核心法规找不到可信来源时不会静默丢弃，而是标记"强制保留"并在报告中明确提示不可直接采信；属性排除、disputed_threshold 排除/确认、用户提及但未参与判断的内容均在报告中独立展示行呈现
- LLM决策审计（轨道C）：四条独立记录线（相关性判分、gap诊断、deep_dive充分性判断、输入解析抽取）覆盖全部"LLM在有限空间内做判断"的现场，支持人工标注与准确率回归验证
以下局限是刻意的架构取舍，完整论证见 docs/Overview.md 第六节：
- 法规检索关键词生成本身仍是确定性的：
markets.yaml权威给定法规清单，LLM 不参与清单生成或增删，只做已确定清单之上的确定性优先级打分——这是防幻觉的核心机制，不是待办 - 核心过滤逻辑（身份归属、状态判定）仍是规则引擎：已验证过决策空间过窄，不适合 LLM 化
- 产品属性目前只有充电宝一个品类接入真实法规数据：耳机/门锁/手表/路由器已在
CATEGORY_DEFAULT_ATTRIBUTES预留但注释掉，扩展只需补齐markets.yaml配置，不需要改动任何节点代码 - 认证服务/费用参考数据尚无独立护栏层：Deep Dive 目前直接从检索内容抽取周期/费用信息，抽不到就诚实占位，尚未接入独立维护的认证机构名录/费用区间参考表
已经不再成立的局限（早期版本曾列出，现已被本轮重构解决）：无法处理多市场对比与优先级排序——orchestrator_graph + node_compare 已完整实现；无法感知产品参数——product_attributes + applies_when + disputed_threshold 三件套已支持属性驱动过滤与数值阈值多轮追问；停留在信息汇总、未触达决策——node_deep_dive 已产出具体测试项/流程/费用区间。
以下节选取自 2026-08-11 一次真实的欧盟+美国双市场运行（multi_portable_power_bank_20260811_130918），选取原则是覆盖当前系统全部核心透明化机制，而非只展示"好看"的部分：
| 项目 | 内容 |
|---|---|
| 目标市场 | 欧盟 |
| 正文法规条目数 | 26 条 |
| 数据质量 | ✅ 正常 17 条 / |
| 核心法规强制保留（来源可信度低） | 是，共 1 条，见 🔴 标记，请勿直接采信 |
| 人工核实锚点确认（非实时检索） | 是，共 3 条，见 📌 标记 |
| 身份保护降级（核心法规relevance误判，已封顶） | 是，共 1 条，见 🛡️ 标记 |
| 已完成深挖（测试项/流程/费用预估） | 1 条 |
单市场报告每条法规都会标注发布机构、可信度分数、原文链接，并在存在语言壁垒、来源降级、身份保护降级、争议阈值确认等情况时给出对应提示，完整节选见 examples/report_sample.md；多市场场景下会额外产出跨市场统计对比与优先级排序，示例见 examples/multi_market_comparison_sample.md。
要求 Python ≥ 3.10。
pip install -e .在 .env 中配置：
DEEPSEEK_API_KEY=...
DEEPSEEK_BASE_URL=https://api.deepseek.com # 可选，默认即此值
TAVILY_API_KEY=...
运行前请注意：
main.py::resolve_user_input()中驱动parse_graph多轮追问循环的用户输入函数（_get_next_user_turn()/_get_simulated_attribute_answer()）目前用固定文本模拟多轮对话，用于开发期验证追问循环逻辑本身，尚未接入真实交互层（CLIinput()或前端请求）。真实接入时只需替换这两个函数的实现，resolve_user_input()的循环控制逻辑无需改动。
系统提供两个入口，均先完整驱动 parse_graph 完成澄清，再进入对应主流程：
python main.py # main.py 底部默认调用 main_orchestrator()（多市场编排，单市场输入亦可，
# Send fan-out 长度为1的特例）；如需单市场直连调试，切换为调用 main()main()：单市场直连入口，产出runs/<run_id>/（report.md/run.log/state_snapshot.json/metrics.json）main_orchestrator()：多市场编排入口，产出runs/<orchestrator_run_id>/，含各市场独立子目录与顶层comparison_report.md/comparison_summary.json
runs/ 为运行时产出目录，不纳入版本库（见 .gitignore）。
系统由三层独立编译的 LangGraph 组成：parse_graph（输入解析与澄清）→ main_graph（input→plan→retrieve→identify→validate→reflect→deep_dive→report 七节点单市场主流程）→ orchestrator_graph（多市场编排）。完整架构地图、State 生命周期、技术文档导航、演进路线，见 docs/Overview.md。
按关注点划分的 8 份深度技术文档：
| 文档 | 回答的问题 |
|---|---|
| 输入解析与澄清架构 | 用户自由文本如何变成标准化输入；两类多轮追问循环如何统一驱动；幻觉防护如何实现 |
| 检索与规划架构 | 系统如何决定搜什么、从哪搜；产品属性如何过滤法规清单；确定性优先级打分如何计算 |
| 过滤架构 | 一条法规如何被判定去留、评分、去重，五层过滤模型的完整判定逻辑 |
| DeepDive与决策支持架构 | 系统如何判断值不值得深挖、信息够不够、如何产出测试项/流程/费用估算 |
| 编排层架构 | 单/多市场如何统一调度；为什么用进程级隔离；跨市场对比/排序/冲突探测的确定性边界 |
| LLM决策审计 | 四条LLM决策记录线如何采样、记录、人工标注、回归验证准确率 |
| 测试与指标体系 | 如何验证系统正确性；如何度量真实运行表现；哪些能力原则上不纳入自动化回归 |
| Reporting统计体系 | 处理结果如何被计数、分类、汇总进单市场/多市场报告展示层 |
配置字段/数据结构速查见 docs/SCHEMA_REFERENCE.md。
scripts/ 下有一套配套的开发/评测工具，非运行时依赖，独立于主流程：
| 脚本 | 用途 |
|---|---|
validate_config.py |
markets.yaml 配置完整性校验（含 disputed_threshold 属性注册/类型/分段一致性校验），可接入 CI |
record_fixture.py / test_regression.py |
回归测试基准录制与运行（轨道A） |
aggregate_metrics.py |
真实运行指标定期汇总（轨道B，含 parse 阶段成功率统计） |
label_audit.py / eval_llm_judgment.py |
LLM 决策审计人工标注与四条线准确率回归验证（轨道C） |
具体用法与命令速查见 测试与指标体系 与 LLM决策审计 两份文档。
Python · LangGraph（含 interrupt()/Command(resume=...) 中断驱动 + ProcessPoolExecutor 进程级并行）· Tavily（检索）· DeepSeek（LLM，fast/full 双档路由）· PyYAML
当前架构的仍然成立的局限（见上方"当前局限"一节）与完整演进路线，详见 docs/Overview.md 第六、七节。用户反馈闭环、批量查询、团队协作、一键导出等产品化功能有意暂不实现，原因同样在该文档说明。