1. 系统概述

LawSight 是一个外观设计专利侵权/非侵权比对分析的多智能体（Agentic Workflow）系统，面向律师与企业管理"产品是否落入他人外观专利保护范围"（路径 A：侵权比对）与"如何改设计规避"（路径 B：规避设计 / FTO）两类需求。

仓库结构（docgen/ 为设计文档 Word 的生成器、1.pdf/2.pdf/外观专利侵权非侵权对比分析.md 为参考资料，非运行时组件）：

lawsight-design-patent/
├── lawsight/
│   ├── backend/app/
│   │   ├── main.py            # FastAPI 入口 + SPA 托管
│   │   ├── config.py          # .env 注入（密钥/开关/Redis）
│   │   ├── schemas.py         # CaseState 等 Pydantic 模型
│   │   ├── store.py           # SQLite 9 表 + 规范化落库
│   │   ├── report.py          # 法域×语言四套报告模板 + 证据链
│   │   ├── chat.py            # 对话引擎（12 类动作）
│   │   ├── api/routes.py      # REST 全部路由
│   │   ├── orchestrator/engine.py  # 工作流引擎（图/检查点/HITL/停止）
│   │   ├── agents/{base, path_a, path_b}.py  # 15 个智能体
│   │   └── tools/{zhihuiya, glm, vision, image_search,
│   │             patent_doc, law_kb, token_bus, mock_data}.py
│   ├── frontend/src/          # Vue3：App/ChatPanel/Workbench/
│   │                          # Overview·CaseDetail·ImageSearch·Health
│   ├── deploy/docker-compose.yml
│   └── backend/{smoke_test, benchmark, test_patent_upload, check_apis}.py
└── docgen/                    # 设计文档 .docx 生成器（Node docx）

2. 总体架构

2.1 架构图（分层视图）

graph TB
    subgraph Client["浏览器 · Vue 3 SPA（同源托管 dist/）"]
        Chat["左侧 ChatPanel 对话智能体<br/>多会话 · 动作芯片 · 快捷指令"]
        Work["右侧 Workbench 工作台<br/>Overview 建案/列表 · ImageSearch 以图搜图<br/>Health 状态 · CaseDetail 案件详情(总览/分析过程)"]
    end

    subgraph Server["FastAPI 单服务（uvicorn, /api/* + 静态回退）"]
        direction TB
        API["api/routes.py<br/>案件 CRUD/run/stop/review/workflow<br/>chat · image-search · loc-predict · files"]
        ChatE["chat.py ChatEngine<br/>意图解析 → 12 类动作执行"]
        IMG["tools/image_search.py<br/>双入口检索比对引擎"]
        ENG["orchestrator/engine.py<br/>Workflow 状态图 · 检查点 · HITL · 断点续跑"]
        AG["agents/ 15 智能体节点<br/>路径A 9 + 路径B 6（5 专属+复用评分）"]
        VIS["tools/vision.py 视觉引擎<br/>ORB+RANSAC · Hu矩+剪影IoU · Laws纹理<br/>HSV色彩 · CLIP/轻量嵌入 · 缩略图测试"]
        PDOC["tools/patent_doc.py<br/>PyMuPDF 著录正则 + 连通域分图"]
        RPT["report.py 四套报告模板<br/>law_kb 引用校验 · 证据链"]
        KB["tools/law_kb.py 法条判例知识库<br/>CN/US 双集合 RAG"]
        ST["store.py SQLite(WAL) 9 表<br/>案件JSON快照 + 规范化行 + 审计"]
        BUS["tools/token_bus.py<br/>contextvars → Redis Stream"]
    end

    subgraph Ext["外部服务（密钥经 .env 注入）"]
        ZHY["智慧芽开放平台<br/>D005 检索 · P011 著录 · P026 法律<br/>P021/P042 附图 · AI LOC 预测<br/>（令牌桶3QPS·退避·熔断·幂等缓存）"]
        GLM["智谱 GLM-5.3-FlashX<br/>chat / vision · JSON 模式<br/>（空回复/失败 → 规则降级）"]
        RDS[("Redis Stream<br/>wf:llm_tokens 只写")]
    end

    Chat -->|"POST /api/chat"| API
    Work -->|"REST + 2s 轮询"| API
    API --> ChatE
    API --> IMG
    API --> ENG
    ChatE -->|"create_case/run/review..."| ENG
    ChatE --> KB
    IMG -->|"rank_visual 复用"| VIS
    ENG --> AG
    AG --> VIS
    AG --> RPT
    AG --> ST
    AG -->|"zhy 客户端单例"| ZHY
    AG -->|"glm 单例"| GLM
    ChatE --> GLM
    IMG --> ZHY
    IMG --> GLM
    API --> PDOC
    RPT --> KB
    GLM --> BUS
    ST --> BUS

要点：

• 单进程单体：API、编排、Agent、视觉引擎同进程；流水线在 daemon 线程执行，靠 SQLite WAL 支持跨线程/多实例读写；生产路径预留 K8s + PostgreSQL/Milvus/MinIO（见 §8）。
• 两个"单例客户端"（agents/base.py 的 glm / zhy）贯穿全系统：对话、以图搜图、Agent 群共享同一套限流/熔断/缓存与 Token 计量。
• 以图搜图与工作流复用同一视觉实现 rank_visual：检索阶段即完成"产品图 × 候选视图"的视觉重排，下游 StatusVerify/RiskRanking 直接消费视觉相似度。

2.2 模块职责图（后端代码组织）

graph LR
    subgraph 入口层
        M["main.py<br/>init_db + CORS + SPA回退"]
        RT["api/routes.py"]
    end
    subgraph 交互层
        CH["chat.py<br/>意图→动作"]
        IS["image_search.py"]
    end
    subgraph 编排层
        EN["engine.py<br/>build_graph / execute_case"]
        PA["agents/path_a.py<br/>9 Agent"]
        PB["agents/path_b.py<br/>5 Agent"]
        BA["agents/base.py<br/>RunContext/BaseAgent"]
    end
    subgraph 工具层
        ZH["zhihuiya.py"]
        GL["glm.py"]
        VI["vision.py"]
        PD["patent_doc.py"]
        LK["law_kb.py"]
        TB["token_bus.py"]
        MD["mock_data.py"]
    end
    subgraph 数据层
        SP["store.py"]
        RP["report.py"]
        SC["schemas.py"]
        CF["config.py"]
    end
    M --> RT --> CH & IS
    RT --> EN
    CH --> EN
    EN --> PA & PB
    PA & PB --> BA
    BA --> ZH & GL
    PA & PB & IS --> VI
    RT --> PD
    CH & RP --> LK
    GL --> TB
    PA & PB & IS --> MD
    RT & CH & EN --> SP
    PA & PB --> RP
    RT & CH --> SC
    ZH & GL & SP -.-> CF

3. 核心设计

3.1 双路径工作流（编排引擎）

orchestrator/engine.py 用约 200 行实现 LangGraph 同构的状态图：add_node / add_edge / add_conditional_edges，节点函数签名 (RunContext) -> str，可平替为 langgraph.StateGraph。

flowchart TD
    S(("start")) --> P["parse_patent 专利解析<br/>著录+法律事件→PatentCard<br/>（上传文件模式走 patent_doc 解析）"]
    P --> I["ingest_asset 产品素材规整<br/>视图方向分类/质量打分/缺失注入演示图"]
    I --> SE["search 多源检索<br/>LOC + 关键词同义词 + 申请人定向<br/>著录补全 DESIGN 过滤 + 附图抓取<br/>+ rank_visual 视觉重排"]
    SE --> SV["status_verify 法律状态核验 ★人审<br/>事件码/文本规则→有效/终止/待核<br/>有效且视觉相似≥80% 写高危理由"]
    SV --> VA["view_align 视图配准<br/>同方向配对 + ORB+RANSAC 叠加图<br/>顺带计算维度相似度(视角加权)"]
    VA --> FD["feature_diff 特征差异矩阵 ★人审<br/>GLM 多模态并行扇出(3线程/逐专利)<br/>失败→视觉引擎确定性矩阵"]
    FD --> PR["prior_art 现有设计参照系<br/>参照集两两嵌入→拥挤度→设计空间<br/>主专利vs参照集→创新点占比"]
    PR --> VS["visual_score 双指标评分 ★人审<br/>S_overall=形状.40+创新.30+纹理.20+色彩.10<br/>S_novelty=嵌入.6+整体.4±关键特征修正<br/>→ 四档风险 high/mid_high/mid/low"]
    VS -->|mode == A| RP["report 侵权比对意见书 ★"]
    VS -->|mode ∈ B, B_then_A| RR["risk_ranking 高危排序<br/>视觉相似度优先"]
    RR --> DF["distinct_feature 必避特征提炼<br/>key 且非功能性特征→权重"]
    DF --> DA["design_around 规避方案生成 ★人审<br/>GLM JSON → 删/替/重组 3-5 方案<br/>失败→模板方案；版本落档案"]
    DA --> RG["regression 回归测试<br/>mock: 按策略重绘产品图真实复测<br/>递归复用路径A评分管线"]
    RG --> FR["fto_report FTO 报告 ★"]
    RP --> H(("hitl 挂起<br/>awaiting_review"))
    FR --> H
    H -->|approve + 五类上市决策| C(("completed"))
    H -->|reject 打回| R2["created 可重跑"]

★ = 强制人工复核节点（status_verify / feature_diff / visual_score / report|fto_report / design_around，演示环境自动通过但留痕）。

引擎关键机制（对应代码）：

• 检查点与断点续跑（engine.run）：每节点开始/结束都 store.save_case(state)；resume=True 跳过 status=="done" 的节点，从 state["checkpoint"] 或失败节点续跑；stopped/failed 状态的 run 请求自动按 resume 处理（routes.run_case）。
• 停止语义：POST /stop 翻转执行线程内存中的活状态（_live_states 注册表 + stop_requested 标志），在当前节点完成后的边界停止——避免"只写数据库副本会被线程逐节点落库覆盖"的经典并发问题；DB 副本标志作为跨进程兜底被 execute_case 吸收。
• 中间产物（Artifact）：RunContext.artifact() 登记 {title, kv, table, images, note}，随步骤落库；未登记的节点由 _default_artifact() 生成兜底摘要，保证 15 个节点每步都可在前端"分析过程"页签可视化。
• 容错边界：BaseAgent.__call__ 记审计（含 PROMPT_VERSION=v1.1）后重抛；单节点失败→案件 failed 而非整案崩溃；单路检索失败降级保留其他路。

3.2 案件状态机

stateDiagram-v2
    [*] --> created: POST /api/cases（或对话 create_case / 以图搜图 to-case）
    created --> running: run（后台线程 execute_case）
    running --> running: 逐节点执行+落检查点
    running --> stopped: stop（节点边界，checkpoint=待执行节点）
    stopped --> running: run（自动 resume 续跑）
    running --> failed: 节点异常（error 记录）
    failed --> running: run（自动 resume，跳过已完成节点）
    running --> awaiting_review: 到达 hitl 终端挂起
    awaiting_review --> completed: approve（+五类上市决策并行记录）
    awaiting_review --> created: reject（打回可重跑）
    completed --> [*]

3.3 视觉比对引擎（tools/vision.py，纯 OpenCV，无 GPU 依赖）

3.4 外部服务韧性设计（tools/zhihuiya.py / glm.py）

智慧芽客户端——四层防护：

1. 令牌桶限流：QPS 3.0（可配），令牌不足自旋等待；
2. 指数退避：平台级错误（67200001–67200007）重试 3 次，1s/2s/4s；
3. 熔断：连续 3 次平台级失败 → 熔断 30s 快速失败（CircuitOpenError），上层降级、案件不失败；业务级错误（683xxxxx，如检索式语法）不重试不计熔断，检索语法错误自动降级最简式重试；
4. 幂等缓存：sha256(路径+参数) 请求指纹 → 进程内缓存（生产换 Redis），同一请求不重复计费；LAWISIGHT_RAW_ARCHIVE=1 可将原始响应落盘归档。

GLM 客户端：chat / vision / chat_json（JSON 模式 + 容错解析：剥代码围栏、正则截取首个 JSON）；推理预算耗尽的空回复视为异常抛出，由上层走确定性降级链（FeatureDiff→视觉矩阵模板、DesignAround→3 套模板方案、LOC 预测→GLM 纯文本重试→规则、相似原因→规则模板）；每次调用经 UsageMeter 计数并 emit_usage 写 Redis Stream。

Token 指标总线（token_bus.py）：contextvars 携带 user_id / matter_id / stage（引擎每节点刷新 stage，线程入口设置 user/matter），GLM 每次调用 XADD wf:llm_tokens（9 字段：ts/user_id/matter_id/stage/name/model/tokens_in/tokens_out/total，MAXLEN≈100k）；只写不读，Redis 不可用静默跳过，指标永不阻断业务。

3.5 对话智能体（chat.py）——自然语言驱动全流程

sequenceDiagram
    autonumber
    participant U as 用户
    participant F as ChatPanel(前端)
    participant A as POST /api/chat
    participant C as ChatEngine
    participant K as law_kb(RAG)
    participant G as GLM-5.3-FlashX
    participant X as 动作执行层
    participant W as 编排引擎(后台线程)

    U->>F: "创建路径A案件，专利号 CN306123456S"
    F->>A: {session_id, message, user_id}
    A->>C: handle()（set_usage_ctx: user+stage=chat）
    C->>K: 法条/判例检索 top_k=2+1(另一法域)
    C->>G: system(能力目录+案件摘要+RAG片段) + 近6轮 + user
    Note over C,G: GLM 失败/离线 → 降级为关键词规则解析
    G-->>C: {"reply", "action":{name:create_case, params}}
    C->>X: _execute(create_case)
    X->>W: threading.Thread(execute_case)
    Note over W: 逐节点执行+落检查点<br/>每节点刷新 stage→token流
    W-->>F: 前端 2s 轮询案件状态，工作台联动
    X-->>C: {ok, case_id, summary}
    C-->>A: reply = 意图说明 + 动作真实结果
    A-->>F: {reply, action, case_id(聚焦), messages}
    F-->>U: 回复 + 右侧自动切换到新案件

12 类动作：create_case / run_case / view_case / review_case / rerun_variant（换法域·语言·路径·专利派生重跑，复制产品视图文件）/ loc_predict / explain_case / image_search（专利号入口对话直达）/ case_progress / list_cases / explain_artifact（解读中间产物）/ answer（RAG 支撑的法律问答）。会话聚焦案件 = 最后一条带 case_id 的 assistant 消息（t_chat 表实现，system 空消息作指针）。

3.6 以图搜图子系统（tools/image_search.py）——双入口检索比对

flowchart TD
    subgraph 双入口
        E1["📷 图片入口<br/>上传文件 / 公网URL(≤4M)"]
        E2["📄 专利号入口<br/>resolve_patent_query:<br/>著录+附图视图=查询图"]
    end
    E1 --> Q["查询图落盘 uploads/IMG-xxx/query.png"]
    E2 --> Q
    Q --> L{"LOC 确定（来源标注）"}
    L -->|"专利号入口"| L1["patent_loc 直达"]
    L -->|"有公网URL"| L2["智慧芽 AI loc_predict"]
    L -->|"失败/无URL"| L3["GLM 依描述推断<br/>(再失败→关键词)"]
    L1 & L2 & L3 --> SR["多路检索（智慧芽 D005）<br/>LOC × LOC×关键词 × 关键词 × 地域<br/>关键词净化防语法错误·错误降级最简式"]
    SR --> BF["著录补全 LOC + patent_type=DESIGN 过滤<br/>合并去重取最高分 ≤12 件"]
    BF -->|"专利号入口排除自身"| VF
    VF["附图抓取 P021优先/P042<br/>小缩略图×2放大 · 连通域分图"]
    VF --> LG["法律状态批量核验<br/>事件码/文本→终止判定+到期推算"]
    LG --> RV["rank_visual 逐候选视觉比对<br/>sim=形状.40+嵌入.25+纹理.20+缩略图.15<br/>取多视图最优并重排"]
    RV --> T{"四档分档"}
    T -->|"≥0.80"| H["high 高风险"]
    T -->|"0.60–0.80"| W2["watch 需留意"]
    T -->|"<0.60"| LO["low 较低"]
    T -->|"法律状态终止"| EX["expired 已过期(不计风险)"]
    H & W2 & LO & EX --> GR["GLM 视觉相似原因(仅Top3)<br/>其余规则模板；摘要统计+AI免责"]
    GR --> OUT["落库 t_image_search →<br/>双图对比卡/叠图+热力图弹窗<br/>逐件标记 todo/dismiss/confirm"]
    OUT --> TC["一键创建路径A案件并自动执行<br/>查询图=被诉侧 命中专利=涉案侧"]

3.7 专利文件上传解析（tools/patent_doc.py）

PDF（PyMuPDF）：文本层正则提取著录（专利号/LOC dd-dd/日期/名称/设计要点/色彩保护声明/权利人）→ 优先提取嵌入图像（跳过著录首页、xref 去重、面积≥20000 阈值）→ 无嵌入图则 150dpi 渲染整页并用连通域分析把一页多视图分割为单视图 → 标准视图标签（主视图/后视图/…）按顺序映射方向。解析结果作为涉案专利直接进入整条流水线（patent_source=upload，法律状态尽力富化否则标注"以上传文件为准"）。

3.8 报告生成与可信机制（report.py）

• 四套模板：kind（infringement/fto）× lang（zh/en）；铁则"法条引用以法域原文为准，locale 只决定解释文字语言"。
• 引用校验防幻觉：法条来自 law_kb 检索（CN 7 条/US 7 条：专利法 64 条 2 款、法释〔2009〕21 号、高仪诉健龙、35 U.S.C. §171/173/289、Gorham、Egyptian Goddess、Samsung v. Apple 等），逐条 validate_citation 校验后才进报告。
• 证据链（Evidence Chain）：对象键计数（产品/专利/叠加图）+ 审计事件数 + 状态指纹（全部步骤 node:status:detail 的 SHA256 前 16 位，保证结论可复现）。
• 免责声明随附：仅为初步风险判断，不构成法律意见。

4. 数据设计

4.1 存储层设计

t_case.state 保存全量 CaseState JSON 快照（引擎每节点覆写，WAL 支持跨线程并发读），同时 _normalize_rows 把可查询字段规范化同步到 4 张关系表（每次保存先删后插），兼顾"图引擎要灵活 dict"与"外部系统要结构化查询"。

erDiagram
    t_case ||--o{ t_audit : "case_id 审计事件(只增)"
    t_case ||--o{ t_patent : "case_id 涉案专利"
    t_case ||--o{ t_feature_matrix : "case_id 特征矩阵行"
    t_case ||--o{ t_score : "case_id 双指标评分"
    t_case ||--o{ t_avoid_scheme : "case_id 规避方案"
    t_case ||--o{ t_design_version : "case_id 设计版本档案"
    t_case {
        text case_id PK "LS-8位HEX"
        text mode "A|B|B_then_A"
        text status "created/running/awaiting_review/completed/failed/stopped"
        text current_node "当前/挂起节点"
        text state "CaseState 全量JSON(含checkpoint·steps·artifact)"
    }
    t_audit {
        real ts "Unix时间戳"
        text agent "节点/引擎动作"
        text action "done/failed/visual_rank..."
        text detail "含 prompt:v1.1"
        int ms "耗时"
    }
    t_patent {
        text pn "公开号"
        text loc "洛迦诺"
        text legal_status "法律状态结论"
        int view_count "视图数"
    }
    t_feature_matrix {
        text feature_id "F1.."
        text commonality "相同/近似/不同"
        text distinctiveness "key/conventional/functional"
        real observability_weight "要部权重0-2"
        int functional_constraint "功能性特征"
    }
    t_score {
        real s_overall "整体相似度"
        real s_novelty "创新点相似度"
        text risk_grade "四档"
        real view_coverage "视图覆盖度"
    }
    t_avoid_scheme {
        text scheme_id "S1.."
        text strategy "delete/replace/recombine"
        real est_risk_drop "预估降幅"
        real regression_before "回归前S"
        real regression_after "回归后S"
    }
    t_design_version {
        text version "V1-方案S1/selected-S1"
        text owner "系统(DesignAroundGen)/user"
        text approved_by "审批"
    }
    t_chat {
        text session_id "多会话隔离"
        text role "user/assistant/system(聚焦指针)"
        text action "动作名"
        text case_id "聚焦案件"
    }
    t_image_search {
        text query_id PK "IMG-8位HEX"
        text record "全量检测结果JSON"
        text query_path "查询图路径"
    }

（t_chat、t_image_search 为独立聚合根，不挂接 t_case。）文件侧：data/uploads/{case_id|query_id}/ 存产品图、专利视图、叠加图、回归重绘图；GET /api/files/* 做路径穿越防护。

4.2 CaseState 关键字段（schemas.py）

case_id / user_id / mode / locale / jurisdiction / markets → 输入侧 product.views[] / patent(PatentCard) / patent_pn / patent_source → 过程侧 candidates[]（含 visual.similarity）/ alignment{pn→pairs} / vision_dims / feature_matrix(es) / prior_art_ctx / degraded_pairs → 结果侧 scores(双指标+不确定性) / score_map / risk / avoid_schemes / report / reviews[] → 执行侧 steps[](含 artifact) / status / current_node / checkpoint / error。

5. 前端设计

• 布局：App.vue = 顶栏（品牌/聚焦案件/中英切换）+ 左 ChatPanel + 右 Workbench；聚焦案件变化时工作台自动切换 CaseDetail。
• ChatPanel：多会话（localStorage 持久化、首条消息自动命名、🗑 两步确认删除）、动作芯片（⚙ action）、快捷指令 chips；busy 状态防重入。
• Workbench：无聚焦时三页签 Overview（建案表单：路径/法域/语言/上传整个专利文件/演示载入 + 案件列表）、ImageSearch（双入口、四档 Tab、文本/LOC 过滤、对比弹窗=并排/ORB 叠图/热力图+五维得分、逐件标记、一键建案、最近检测）、Health。
• CaseDetail：流水线进度条（含停止/断点续跑按钮）+ 两页签——"结果总览"（候选表含视觉相似度列、涉案专利视图、特征矩阵、双指标评分、叠加图、规避方案+回归梯度、报告 Markdown 渲染、HITL 复核含五类上市决策、审计链）与"分析过程"（每步 artifact 卡片：kv 指标/中间表格/过程图像/报告前段，可折叠）。
• 国际化：i18n 字典内嵌 main.js（zh-CN/en-US 全量键值），用户标识 ls_user 本地生成随全 API 携带。

6. 可信、治理与可观测

7. 部署架构

graph TB
    subgraph Host["docker-compose 单机演示/开发（deploy/docker-compose.yml）"]
        GW["gateway 容器<br/>uvicorn app.main:app<br/>--workers 2 :8000"]
        VOL[("volume lawsight-data:/data<br/>SQLite + uploads + raw")]
        GW --- VOL
    end
    subgraph Prod["生产演进（注释预留，见 README）"]
        K8s["K8s 多副本 gateway"]
        PG[("PostgreSQL<br/>替 SQLite")]
        MV[("Milvus IVF_SQ8<br/>千万级外观专利向量库")]
        MIO[("MinIO<br/>视图/素材对象存储")]
        GPU["GPU 推理池<br/>CLIP/DINOv2 私有化 Triton/vLLM"]
        K8s --- PG & MV & MIO & GPU
    end
    User["浏览器 / 局域网客户端"] -->|"http://ip:8000 或 8123"| GW
    GW -->|"https"| ZY["智慧芽 connect.zhihuiya.com"]
    GW -->|"https"| GL["智谱 open.bigmodel.cn"]
    GW -->|"6379（可选）"| RD[("Redis Stream")]

当前演示部署双端口：8123 真实智慧芽模式（页面 🌱 徽标）/ 8000 离线演示库（LAWISIGHT_MOCK=1，🧪 徽标）；前端 dev 模式 5173 代理至 8000。密钥仅经 .env 环境注入，不出现在 API 层。