星辰智能

• 1: VLAgent 智能文档识别平台架构解读
• 2: 结算类凭证要素核验需求规格说明书
• 3: 智能文档识别平台规划方案
• 4: 智能文档识别平台建设实施计划与详细方案
• 5: StarWork 桌面端技术架构
• 6: StarWork 云控服务端技术架构

1 - VLAgent 智能文档识别平台架构解读

依据 vlagent 前后端仓库（vlagent-backend / vlagent-frontend）与工程内文档编制，用于项目组内部分享。文中五张图表均为交互式：支持缩放、语义视图、关系追踪与 PNG/SVG 导出。

一、项目概览

VLAgent 是部署在银行内网 K8s 上的智能文档识别平台：以 Qwen-VL 多模态大模型为主、PaddleOCR 为辅，对银行流水、结算凭证、询证函、发票、类凭证等影像做结构化抽取与规则核验，替代柜面与审计场景中的人工初核。系统以 iframe 嵌入**星辰智能助手（IOA）**对外提供服务，前端工作台与 FastAPI 后端共享同一 Ingress 域名（生产为 aisit.qdccb.cn / vlagent 路径）。

两个工程均为"垂直切片"式组织：后端 src/ 下每个业务模块自带 router + service + models + prompts；前端除平铺的 views/ 外，settlement/、credit_comparison/ 两个新模块采用自带 views/components/api 的 feature 目录，代表较新的组织方式。

二、业务架构

平台服务两类用户：柜面柜员（凭证影像上传、核验结果确认）与审计/运营人员（流水核对、报表核对）。接入侧通过 iframe 嵌入星辰智能助手（IOA），JWT 多通道取 token，用户无需二次登录；首页模块卡片由后端 modules + permissions/me 接口动态驱动，按权限渲染、前端零改动即可上下架模块。

业务能力划分为三个域 + 平台服务域，共九个业务模块：

全屏打开 ↗

三、技术架构

3.1 前端

• 无第三方组件库、无 Pinia：全部手写 Vue 组件 + Tailwind 工具类；状态用 composables 的模块级 ref 单例（useUser）与函数式状态机（useAuth、useSettlementRecords）共享。
• API 层单文件收敛：src/api/index.ts 约 400 行封装全部后端接口，统一注入 Bearer token、401 全局登出、blob 预览与下载。
• 重前端计算：credit_comparison 在前端完成 Word 段落锚点匹配、高亮分词、Excel 行列识别（约 1000 行纯前端数据变换）；PDF 渲染用 pdfjs-dist（含中文 cmaps），Word 用 docx-preview。
• 通信模式为纯 HTTP + 轮询（典型 3 秒，完成后自动停止），全库无 SSE/WebSocket。

3.2 后端

• 入口链路：main.py 组装 app（启动时自动 alembic upgrade head、按需起 JVM 与上游同步、APScheduler）→ api.py 统一挂载 13 组子路由，全部默认要求 JWT（HS256，支持 ?token= URL 参数以适配 iframe）。
• 无消息队列：异步识别全部走 FastAPI 后台任务 + asyncio.to_thread，全局 asyncio.Semaphore(2) 限流——2 副本 × 4 workers × 2 = 16 并发，压在 AI 网关 20 并发上限之内。
• 银行流水策略模式：抽象基类 BankHandler + @register_bank 注册表，11 家银行各一个 handler 与独立表结构，config/bank_schemas/ 外置 schema。
• 文档处理链：pdf2image/poppler 拆页压缩、pdfplumber/pymupdf 结构化提取、容器内 LibreOffice 做 DOCX→PDF、diff-match-patch 做比对。

3.3 AI 混合管线

核心设计是抽取与核验分离：Qwen-VL 只做忠实抽取（含裁片精读），PaddleOCR 只做定位（印章 bbox、版面），合规判定完全在确定性规则层。所有模型不确定性被限制在第一阶段，判定层可单测、可审计。

全屏打开 ↗

四、数据架构

双库架构：业务主库 vlagent（PostgreSQL，asyncpg 异步驱动）+ 上游星辰智能助手（IOA）只读库。APScheduler 定时单向同步模块与权限，用 PG Advisory Lock 保证多副本多 worker 只有一个实例执行。

建表策略：表结构真相在 SQLModel 模型，由 init_db() 的 create_all 创建；alembic 仅做增量列变更（基线迁移为空操作，后续迁移逐条 ADD COLUMN IF NOT EXISTS 保证幂等）。

表清单概览（约 38 张）：

全屏打开 ↗

五、核心流程：凭证核验主链路

以结算凭证核验为代表的通用异步契约：

1. 接入：柜员上传 PDF（魔数校验、防路径穿越）→ 建 pending 记录 → 接口立即返回任务 ID，前端开始 3 秒轮询。
2. AI 抽取：按票种分发 Handler（prompt + Pydantic schema）→ Qwen-VL 整图多面抽取 → PaddleOCR 印章定位 + VLM 裁片精读覆盖 stamps。
3. 自修复：盲区二次提取、金额复核读（裁左右半分读大小写）、付款人账号跨单复核，矛盾消解后才覆盖。
4. 规则核验：极简规则引擎（Rule.check() → Engine → Report）对要素总集逐条判定，输出五态结论（通过/不通过/警告/不适用/待人工复核），总体取最严重态。
5. 交付：记录 + 逐条明细落库，前端轮询到完成态后渲染报告，支持证据定位与导出。

全屏打开 ↗

六、CI/CD 发布流水线

三环境分级流转，生产网与研发网物理隔离：

双工程构建策略差异是理解流水线的关键：

• 前端在容器内多阶段构建（node:lts-bullseye 内 npm install + vite build → 拷入 OpenResty），.dockerignore 排除 lock 文件以适配内网 npm 源；
• 后端采用 Agent 预构建 + 纯打包（Jenkins Agent 上 uv sync 生成 .venv，镜像只 COPY venv + 源码），基础镜像 vlagent-backend-runtime:1.1 预装 poppler、中文字体、LibreOffice 与 tini。

配置注入走 Helm：非敏感项进 ConfigMap、密钥进 Secret，Pod 以 config-hash/secret-hash 注解实现配置变更自动重启；上传产物落 nfs-client PVC。

全屏打开 ↗

七、工程质量与演进方向

• 测试重心：44 个测试文件、361 个用例，其中 settlement_check 占 33 个文件约 300 例（规则逐条一测、印章管线 40 例、可注入假 extractor 不依赖网络/DB），TDD 痕迹明显；HTTP 层与早期模块（banks/files）基本无单测。
• 已知文档滞后：前端 README 提及的 Tiptap、api 分文件与后端的 native_statement 模块均与当前代码不符，以代码为准。
• 值得关注的取舍：无消息队列（进程内后台任务 + 信号量）在当前并发规模下最简可靠，但识别吞吐受副本数硬约束；轮询而非 SSE 也是同源 iframe 场景下的务实选择。
• 演进方向：结算凭证特种票种扩展、HTTP 层集成测试补齐、识别结果缓存与幂等重试。

2 - 结算类凭证要素核验需求规格说明书

依据《AI 审核规则》及 vlagent 项目已实现的核验能力编制。本说明书覆盖结算业务申请书（单张/批量）与**「转账支票+进账单」联合核验**两个场景，规则与需求文档逐条对应（申请书 1.1–1.8、支票 2.1–2.12），并纳入实现过程中经业务确认的判定口径。

一、引言

1.1 目的与范围

为银行柜面结算凭证的人工审核提供 AI 辅助要素核验：识别凭证影像上的要素，按规则逐条给出结论与证据，供柜员快速定位问题。本说明书界定两个核验场景的功能与非功能需求；特种转账借方传票等票种为规划范围（规则文档 §3 占位），不在本期。

1.2 术语

1.3 参考文档

《AI 审核规则》（结算业务申请书 §1、转账支票+进账单 §2）；项目 CONTEXT.md 词汇表与 ADR-0001～0004。

二、总体描述

2.1 系统定位与流程

系统采用抽取-校验分离的两阶段架构：第一阶段完成要素收集与自修复（VLM 整图抽取 → PaddleOCR 印章增强 → 金额/账号复核 → 文本兜底），产出一册完整的要素总集；第二阶段由规则引擎对同一册证据逐条判定，输出五态结论。所有模型不确定性被限制在第一阶段，判定层完全确定、可单测、可审计。

全屏打开 ↗

2.2 系统架构

前端为核验工作台（上传、轮询、报告呈现）；FastAPI 后端编排两阶段管线；AI 服务包括 Qwen-VL 多模态（整图抽取与裁片精读）与内网 PaddleOCR（版面解析与印章定位）；证据（裁片文件、PaddleOCR 输出、校验明细）随记录落库可追溯。

全屏打开 ↗

2.3 结论体系（五态）

总体结论取全部规则的最严重态。

2.4 凭证上传要求

• 结算业务申请书：单面凭证，支持单张与批量上传（一次最多 5 张，逐张独立识别）；批量时逐张展示状态与结论，支持汇总（N 通过 / M 不通过 / K 待复核）与单张钻取。
• 转账支票+进账单：三件配套必传——支票正面、支票背面、进账单，缺一拒绝受理（无背面则背书核对无从做起，无进账单则跨单比对无从做起）；可选输入交易码（票号位数模式用）。

三、功能需求——结算业务申请书

规则与需求文档 §1.1–§1.8 一一对应；申请日期与进账单日期共用公共日期口径。

印章分类按证据判定：类型词/形状会被识别错（如方形名章被读作「圆形+测试专用章」），分类依「章文结构 + person_name/unit_name 互斥字段 + 形状」综合反推；票面有单位章时按单位口径（户名启发式可被章型证据纠正）。

四、功能需求——转账支票+进账单

三件联合核验，规则与 §2.1–§2.12 一一对应。支票正面/背面字段平铺合并，进账单整体挂 slip 命名空间。

说明文案要求（业务确认）：无论结论如何，说明中固定罗列检核用到的各要素（票面收款人、每手背书人（标注形式）与被背书人（含委托收款标记）、进账单收款人全称），未识别项标注「未识别」。

五、印章识别混合方案

整图 VLM 识别印章不可靠（计数幻觉、锚点挪用、示例污染），采用 PaddleOCR 定位裁片 + VLM 裁片精读：

• PaddleOCR 只负责检测印章位置并输出裁片；章文内容由 VLM 按统一印章解剖学口径精读单枚特写；其余字段维持整图抽取。
• 归属用表格结构与 bbox 几何（背面 x 向三区：附加信息 / 第 1 手 / 第 2 手），VLM 不参与。
• 三重透印过滤（两面通用）：低饱和淡红（颜色）、裁片框红墨覆盖率过低（稀疏透痕）、镜像反字（方向）任一命中即剔除。
• 章证优先：检出单位章即以其单位名称重推锚点并覆盖手写标志；手写保护——该手未检出裁片时整图结果原样保留（手写第一行锚点不清空）。
• PaddleOCR 失败优雅降级退回整图值；被剔除裁片仍落盘留证。

全屏打开 ↗

六、抽取自修复链（第一阶段）

所有修复仅发生在证据层，「发现缺口/矛盾 → 定向重读 → 能消解才采纳」：

七、接口需求

八、非功能需求

• 确定性：同一输入必出同一结论；规则层不调用任何模型。
• 可追溯：每条结论附说明与证据；印章证据附裁片文件地址；PaddleOCR 输出目录随记录落库。
• 降级：任一外部服务（VLM/PaddleOCR）失败不影响主流程出报告（退回可用证据，标注待复核）。
• 性能：性能测试本期不涉及；单张凭证端到端（含两次 VLM 抽取 + 印章增强）按 ≤60s 设计、批量 5 张并行，仅作设计参考值，不作为测试验收口径。
• 安全：全接口 JWT 鉴权；影像与输出文件按用户目录隔离。

九、附录

9.1 规划范围

• 结算业务申请书批量上传（≤5 张）前端交互与汇总展示（增量需求）。
• 特种转账借方传票（规则文档 §3 占位）、电汇凭证等新票种。
• PaddleOCR 能力服务化（ADR-0004：独立 OCR 标准化服务，方案已定案）。

9.2 版式先验

背面背书栏位三区/手间分界等几何先验按样本标定，换版式样本须复标；进账单金额位值表格解析依赖表格结构识别质量。

3 - 智能文档识别平台规划方案

面向企业影像与文档智能场景的识别能力平台规划方案。平台以 OCR 与 VLM 双引擎为底座，通过 REST API、MCP 与可嵌入识别工作台（AG-UI）三种形态对外输出识别能力。本方案为从目标出发的全新设计，不绑定任何现有系统的实现；现有业务系统在方案中仅以"首个消费方"身份出现。文中七张图表均为交互式：支持缩放、语义视图、关系追踪与 PNG/SVG 导出。

一、背景与目标

1.1 建设动因

识别类能力目前散落在各业务系统中自建自用，存在三方面问题：

• 识别与业务规则耦合：抽取管线与校验规则交织在同一套代码里，换模型、调参数会波及业务逻辑，测试边界模糊；
• 能力无法复用：每个系统重复解决版面解析、手写识别、印章提取、裁片精读等同类问题，质量参差；
• 质量无闭环：识别错误依赖各系统自行发现，没有统一的 badcase 归集、评测与模型迭代机制。

1.2 平台目标

一句话定位：给一份文档，还你结构化与语义化的识别结果——OCR 负责结构与位置，VLM 负责语义与理解，双引擎一个平台，REST、MCP 与工作台三出口。

三条核心目标：

1. 识别与判断解耦：平台输出"事实"（字段、位置、置信度、证据），业务判断（合规校验、规则比对）完全留在消费方。判断类输出（一致/不一致、合规/违规）永远不出现在平台侧。
2. 识别能力服务化：企业内任何系统、任何智能体都可以通过标准契约消费识别能力，新场景上线是"新增一条类型配置"，不是"新写一套识别服务"。
3. 引擎可插拔可演进：OCR、CV、VLM 引擎都是可替换资源；接入第 N+1 个引擎只新增一个适配器，核心层零改动；模型可通过微调闭环持续变准。

1.3 设计原则

1.4 成功度量

二、业务架构

2.1 消费方

平台服务四类消费方，对应三种接入形态：

• 业务系统（REST API）：消费识别字段做业务处理。典型如结算凭证核验系统——平台读出大小写金额与印章位置，系统侧做一致性校验；
• 智能体（MCP）：对话式消费识别能力。柜员或审计在智能助手里"把这张凭证的金额读出来"，助手调 MCP 工具完成识别并组织回答；
• 终端操作者（可嵌入识别工作台 · AG-UI）：业务系统把平台提供的识别工作台嵌入自身页面，操作人员以对话方式完成上传、识别与人工复核——界面交互走 AG-UI 协议（第三出口），权威数据仍凭 log_id 走 REST/MCP 获取；
• 平台运营方：管理文档类型、评测集、引擎版本与调用配额。

2.2 能力分层

划分标准：“怎么读准"进平台文档类型，“读出来的对不对"留在消费方。版式先验（如票据金额栏位置）属于"怎么读准”，沉淀为平台文档类型，全行复用；合规规则属于业务立场，不得进入平台。

2.3 质量闭环

业务架构的灵魂是 badcase 闭环：消费方复核标记 → 平台归集台账 → 人工标注修正 → 沉淀 golden 评测集 → 驱动文档类型调优与引擎微调 → 评测通过后灰度上线 → 通知消费方。闭环转起来，平台从成本中心变成越用越准的资产。

全屏打开 ↗

三、应用架构

3.1 应用组件

3.2 统一结果模型（契约核心）

所有引擎输出归一到同一对象模型，这是 API 与 MCP 共享的地基：

{
  "document_id": "doc_8f3a",
  "pages": [
    {"page_no": 1, "blocks": [
      {"bbox": [0.12, 0.31, 0.68, 0.36], "type": "handwriting",
       "text": "青岛市北区……", "confidence": 0.71, "source_engine": "paddleocr-vl"}
    ]}
  ],
  "fields": [
    {"name": "merchant_name", "value": "……", "confidence": 0.64,
     "needs_review": true, "evidence_block_ids": ["blk_12"]}
  ],
  "meta": {"log_id": "…", "doc_type": "voucher-v1", "engines_used": […],
           "artifacts_uri": "minio://…", "latency_ms": 4200}
}

三个关键字段：confidence（字段级置信度）、needs_review（投票不一致即标记，宁缺勿错）、evidence_block_ids（每个字段可回溯到原图证据块，审计场景刚需）。

3.3 MCP 设计要点

• 工具粗粒度：upload_document（拿 doc_id）、recognize_document、extract_fields、compare_documents、query_result；文件走引用不传裸 base64；
• 结果作为 MCP resources 暴露，智能体可按 URI 二次取用；
• tool description 即给大模型的说明书，明确"何时该用、何时不该用”；
• 每次工具调用记调用方身份并进审计日志。

全屏打开 ↗

3.4 AG-UI 识别工作台：可嵌入的对话式识别界面

第三出口面向终端操作者：不是所有人都在智能助手里对话，更多时候是在业务系统页面里直接办事。AG-UI（Agent-User Interaction Protocol）是"智能体后端 ↔ 前端界面"的标准协议——平台实现该协议的会话端点，并交付一个可被任意业务系统嵌入的识别工作台前端，操作人员上传文档、看到流式识别过程、在界面上完成人工复核。

设计要点：

• 端点即协议：POST /agent/run 接收 RunAgentInput（会话 ID、消息历史、共享状态），以 SSE 事件流返回（RUN_* 生命周期、TEXT_MESSAGE_* 流式文本、TOOL_CALL_* 工具过程、STATE_SNAPSHOT 状态快照）——标准 AG-UI，前端实现可整体替换；
• 三出口单一实现：会话内的工具（列类型、抽取字段、查历史）直接调用与 REST/MCP 相同的业务层，工作台只是协议之上的第三个壳；
• 客户端权威状态：共享状态（doc_id、字段、复核标记）由前端持有、每轮全量上送，服务端无会话粘性——平台不成为有状态单体；
• 人在回路：needs_review 字段驱动复核表单，复核意见作为新消息进入下一轮会话，形成"识别 → 复核 → 确认"闭环；
• 嵌入契约：业务系统以 iframe 嵌入，URL 注入访问凭证；界面只管操作，权威结果凭 log_id 走 REST/MCP 获取（界面与数据解耦）；调用方/用户/机构级权限随调用方管理演进（凭证携带身份声明）。

全屏打开 ↗

3.5 MCP 与企业服务总线（ESB）的协同

企业已有传统 ESB，系统间接口调用统一经其转发。MCP 引入后的关系定位：两者不是替代关系，而是架构中两段不同的接线——ESB 管"系统之间怎么互相调用"（服务治理层），MCP 管"智能体怎么调用能力"（AI 接入层）。MCP Server 站在前面作为智能体接入层，它发起的跨系统服务调用仍然走 ESB，就像当年移动端渠道出现时，移动网关背后照样调 ESB 服务——智能体只是又一种前端。

MCP Server 的归属：跟着能力走，属于能力提供方系统。本平台的 MCP Server 是平台应用的组件之一，部署在平台命名空间、与 REST API 共享同一套编排实现；智能体平台只做消费方，不替提供方建工具适配，避免长出绕开治理的影子集成网。分工与 ESB 治理经验同构：工具语义（描述、参数 Schema、错误码）由能力提供方定义，鉴权/审计/限流等治理能力可集中——中期由 ESB/APIGW 原生托管 MCP 协议绑定时，这一分工不变。

调用边界：MCP Server 调用本平台内部能力（MCP → 编排层）属系统内调用，不经 ESB；跨系统调用（如经 ESB 到影像平台调阅影像、回写核心系统）一律走 ESB，纳入既有治理。两层审计各司其职：MCP 层记录"哪个智能体、代表哪个用户、调了什么工具"，ESB 层照旧记录服务调用，日志 ID 串联。

全屏打开 ↗

3.6 文档类型化接入：按类型识别输出

识别接口按**文档类型（文档类型）**输出对应字段集——发票返回发票字段、询证函返回询证函字段，文档类型与输出字段在平台管理端可配置。这是编排层类型化的直接应用：输出字段 = 文档类型中声明式定义的字段 Schema。

API 形态：按能力大类分端点，大类内按文档类型参数化。 大类与文档类型是两个正交维度——大类区分任务形态（识别、比对、批量），文档类型区分票种（发票、询证函、凭证）：

POST /v1/documents          // 文档接入：上传拿 doc_id、查询、状态（REST 资源型）
POST /v1/recognize          // 识别抽取大类：单文档进、字段集出
  { "file": "…", "doc_type": "invoice" }        // → 发票字段
  { "file": "…", "doc_type": "confirmation" }   // → 询证函字段
POST /v1/compare            // 比对大类：双文档进、差异结论出（doc_type 同样参数化）
POST /v1/batches            // 批量异步大类：文档集进、任务句柄出（引用文档类型）
GET  /v1/doc-types/{id}/schema  // 文档类型契约下发

划分判据：请求/响应骨架是否同构。 同构（单文档进、字段出）归入识别大类，用类型参数区分文档种类——发票、询证函、凭证互不开端点；不同构（双文档进差异出、批量任务句柄、文档资源管理）才开新大类。由此保留两个收益：新文档类型上线 = 管理端加类型，不发版；新任务形态出现才动 API 面。MCP 工具按大类映射（upload_document / extract_fields / compare_documents），保持粗粒度。印章提取等"输出为位置与图像证据"的能力首选纳入类型化配置（印章作为特殊字段类型，值 = 位置 + 裁片引用），仅当输出形态无法归入统一结果模型时才开专项端点，避免大类膨胀。

动态字段的契约机制（此设计成败的关键）：每个类型携带正式的字段 Schema 作为一等契约下发——GET /v1/doc-types/{id}/schema 随时可取，SDK 按文档类型生成强类型客户端；字段变更守纪律（加字段 = 文档类型小版本兼容升级；改字段语义/删字段 = 新大版本，消费方显式迁移）；管理端保存文档类型时即做 Schema 校验（命名规范、类型合法、必填约束自洽），脏配置进不了生产。文档类型配置模型示例：

{
  "id": "invoice", "version": "3.2",
  "fields": [
    {"name": "invoice_number", "type": "string", "required": true,
     "extraction": {"mode": "ocr_direct"},
     "post_rules": [{"type": "regex_validate", "pattern": "^[0-9]{8,20}$"}]},
    {"name": "amount", "type": "decimal", "required": true,
     "extraction": {"mode": "cross_engine_vote"}}
  ],
  "layout_priors": {"amount_region": "…"},
  "routing": {"preference": ["ocr", "vlm"], "fallback": true}
}

配置化的深度与边界：配置表达"结构与参数"，代码表达"算法与流程"——把逻辑塞进配置端会演化出没人敢改的"配置编程语言"，把结构参数写死代码又会让新场景接入周期失控。

两条配套约束：① 类型变更与代码变更同级对待——管理端配置同样走"草稿 → golden 集评测通过 → 发布"，不允许直接改生产文档类型；② 配置出来的字段同样携带 confidence / needs_review / evidence_block_ids，配置化不绕过质量纪律。自然扩展（按需）：doc_type: "auto"——混合批次先经 CV 引擎文档分类再路由到对应文档类型，文档类型机制天然支持。

3.7 提示词管理：渲染产物与护栏

VLM 识别的提示词不是独立维护的字符串，而是文档类型的渲染产物：字段定义是数据，提示词模板是模板，最终发给 VLM 的提示词 = 渲染器（模板 + 字段定义 + Schema 约束）生成——与文档类型同版本、同生命周期。

关键机制是渲染时注入：模板引用受控变量插槽（{{fields_schema}} 等）而非硬编码字段清单——文档类型加字段，下次渲染自动带上，不存在"字段加了、提示词忘了同步"的不一致。由此买到三样东西：一致性（字段与提示词同源）、可审计（结果 ↔ 类型版本 ↔ 渲染后提示词绑定，历史可重放）、缓存友好（同版本渲染结果可缓存）。

五条护栏（缺一条，动态提示词就是事故源）：

1. 模板与数据分离：字段清单永远经渲染注入，不写死在模板里；
2. 受控变量插槽：模板只支持平台预定义变量（fields、schema、language、context），不允许任意表达式——配置端不能演化成编程语言；
3. 系统级指令不可配：输出必须 JSON、不得编造等平台级纪律由代码持有，管理端模板覆盖不到；
4. 评测门禁覆盖提示词变更：提示词有牵一发动全身的隐性风险（改一个字段描述可能让整页其他字段退化），正确工作流是草稿 → golden 集回归 → 新旧 A/B 对比 → 发布，不允许直接改生产；
5. 提示词版本 = 类型版本：不存在独立的提示词版本，回滚文档类型即回滚提示词。

由此，提示词调优进入与模型迭代同一条质量闭环：badcase 台账发现字段系统性读错 → 定位字段描述歧义或模板问题 → 管理端改草稿 → golden 集验证提升且无回归 → 发布新类型版本。提示词从代码里的字符串变成可运营、可度量、可回滚的资产——这是文档类型化架构对 VLM 侧最大的红利。

四、技术架构

4.1 分层结构

自上而下四层 + 一条旁路 + 一个横切面：

• 接入层：REST 网关与 MCP Server，只做协议、鉴权与流控；
• 编排层：类型引擎（场景 = 配置而非代码）、引擎路由（按精度/成本/健康度选引擎）、投票融合与降级决策；
• 能力与适配层：对上暴露稳定的能力契约，对下吸收引擎差异——坐标归一（统一像素系）、置信度标定（引擎分数可比化）、块类型映射（统一版面词表）；
• 引擎层：可插拔资源，多版本灰度共存；
• 训练流水线（旁路）：标注集管理 → 微调训练 → golden 集评测 → 版本注册，产出新引擎版本进入引擎层；
• 横切治理：鉴权、审计、配额、监控在接入层统一实施。

4.2 双引擎协作模式

编排层固化的三种文档类型模式：

1. OCR 直出：印刷体、清晰扫描，一步到位——多数页面走这条，成本最低；
2. OCR 定位 + VLM 精读：OCR 出版面与 bbox，定位目标区域裁片增强后交 VLM 读字段——手写、印章、模糊区域走这条；
3. VLM 全读：无版式规律的语义理解与文档比对，整图交 VLM。

4.3 路由、投票与降级

• 成本路由：OCR 能解决的字段不过 VLM；冲突或低置信才升级，控制推理成本；
• 跨引擎投票：不同架构的模型错误模式不相关，关键字段（金额、户名）双引擎互验远比同模型多读可靠；
• 降级链：引擎超时/异常 → 重试 → 备用引擎 → 整图直读兜底；仍失败返回明确错误码；投票不一致字段标 needs_review 走人工。

全屏打开 ↗

五、技术栈选型

选型独立于任何现有系统评估，按扩展性、成熟度、开发效率、性能、运维成本、信创合规六个维度论证。

5.1 选型决策表

5.2 Python 与 Go：主体与边缘的分工

决策：平台主体语言为 Python；Go 不作为平台语言，仅作为特定边缘组件的按需选项——按瓶颈引入，不按偏好引入。

先看负载画像：处理一份文档的时间分布为——引擎推理（GPU，秒级）> VLM 调用（秒级）> 预处理（百毫秒级）> 编排逻辑（毫秒级）。延迟大头在引擎、吞吐瓶颈在算力，编排层是 IO 密集的轻计算层，FastAPI 的 asyncio 在凭证级调用量下余量充足；Go 的并发优势在高 RPS 网关场景才兑现，此处用不上。更关键的是语言分裂的代价：训练、微调、评测、预处理全在 Python 生态，编排层若用 Go，模型迭代链路被切成两半，每次调整都要跨语言维护两份实现——平台的核心竞争力（文档类型快速迭代 + 模型持续变准）都长在 Python 生态里。

公允对照 Go 的真实优势与平台需求：

分层语言分工：

组件改写为 Go 的三条触发判据（不满足任何一条则不引入，第二语言的维护成本是持续的）：

1. 实测瓶颈：压测显示 Python 组件在目标 SLA 下 p99 不可接受，且进程池、缓存等优化已到头；
2. 部署形态：组件需以单二进制下沉到无 Python 运行时的环境；
3. 纯网络转发：组件为无状态转发/聚合、无业务语义，用 Go 实现反而更简单。

补充选项：若企业平台工程规范倾向 Go 网关，可接受"Go 接入壳 + Python 编排核"的混合架构——Go 只做协议接入与流控，全部业务语义在 Python；前提是契约（OpenAPI）稳定且团队双语言人力齐备。

5.3 多智能体：不引入的架构决策

决策：识别平台不引入自主智能体编排（含多智能体）；平台是工具/能力提供方——被智能体调用的那一端——自身不成为智能体。跨工具的动态编排属于消费方智能体平台的职责。

期望"智能体"带来的能力，平台已用确定性等价物覆盖：多读投票（应对幻觉）、needs_review 复核标记（自我校验）、降级链（自主恢复）、文档类型路由（自适应选择）——效果可度量、路径可复现。

边界条件：若未来出现开放式任务（如"审计整卷信贷档案"需运行时分解、交叉比对、汇总结论），正确做法是在消费方/业务方案层增设智能体编排——由它规划步骤并循环调用平台的 MCP 工具，识别平台继续作为被调用的工具集，分层不变。

5.4 维度小结

• 扩展性：引擎适配层 + 注册表保证水平扩展（多引擎）与垂直扩展（多副本 HPA）两条路径都开放；
• 成熟度：全部选型均为生产级验证过的主流组件，无实验性依赖；
• 开发效率：单一语言（Python）覆盖业务编排到模型迭代，文档类型化让新场景以天级接入；
• 性能：计算密度在引擎层（GPU），编排层 IO 密集（异步足够），分层各自优化互不拖累；
• 运维成本：一期落地组件仅 3 个（平台服务、MinIO、PG；引擎复用已有部署），Redis 二期引入；
• 信创：框架（PaddlePaddle）与芯片适配（昇腾/昆仑）均国产化可选。

六、数据架构

6.1 存储分工

6.2 核心数据模型（表清单）

6.3 证据链与数据反哺

• 每个字段的 evidence_block_ids 指向块级记录，块级记录指向对象存储中的裁片与引擎原始输出——任何结论可重放验证；
• 低置信字段与复核标记自动进入 badcase 台账，人工标注后沉淀 golden 集；golden 集同时服务引擎评测、类型回归与微调训练三类消费；
• 数据生命周期：原始文档与证据按监管留存期归档；引擎原始输出可按期降冷，统一结果永久在线。

全屏打开 ↗

七、部署架构

7.1 K8s 拓扑

• 平台命名空间：统一接入（Ingress/TLS）+ 平台服务（API/MCP/编排，无状态多副本 + HPA）+ 存储组件（MinIO/PG/Redis，或接共享实例）；
• GPU 节点池：PaddleOCR-VL 等重推理产线，按负载独立扩缩容，容器独占卡（PaddleOCR-VL 已有部署，直接接入复用）；
• CPU 节点池：CV 任务与轻量 OCR；
• VLM：走大模型平台统一算力，平台不重复建设推理资源。

7.2 版本化与发布

• 模型版本 = 不可变镜像 tag：训练流水线产出带版本号的 serving 镜像，Harbor 承载，回滚即镜像回滚；
• 发布门禁：新引擎版本必须先在评测环境跑 golden 集回归，字段准确率不退化方可灰度；灰度通过端点 model_version 参数路由，默认 stable；
• 流水线：Jenkins 构建镜像 → Harbor → ArgoCD 声明式同步，发布与回滚均为 Git 变更，全程可审计。

7.3 环境规划

SIT（联调，黄金集回归常驻）/ UAT（业务验收 + 灰度验证）/ 生产（灰度发布 + 双版本并行）。生产网与研发网物理隔离，制品经镜像仓库摆渡。

全屏打开 ↗

八、演进路径

九、风险与对策

4 - 智能文档识别平台建设实施计划与详细方案

本文是《智能文档识别平台规划方案》的落地实施文档：规划方案回答"建什么、为什么这样建"，本文回答怎么建、什么节奏、做到什么程度算完成。所有架构决策以规划方案为准，本文不重复论证，只做实施展开。

一、建设原则

• 契约先行：统一结果模型与评测口径最先定版（M1），其后所有工作以此为验收基准；
• 演进式交付：一期到三期每期独立可交付，任何一期结束后暂停都不产生半成品负债；
• 评测门禁从第一天生效：一期上线即带 golden 集回归，“无评测集的场景不上线"从一期就是纪律而非愿景；
• 消费方牵引：每期以真实消费方场景验收，不以技术组件完成为验收标准。

二、总体建设路线

全屏打开 ↗

三、一期详细方案

3.1 范围界定

做：统一结果模型定版；编排引擎与双引擎适配（PaddleOCR-VL + VLM，VLM 经大模型平台 OpenAI 兼容协议接入）；提示词渲染器（类型模板 + 字段描述渲染，规划方案 3.7 的护栏一期即生效）；首个场景类型（结算凭证类，含手写字段的 OCR 定位 + VLM 精读）；REST API 与能力网关；管理端最小集（类型 CRUD + 发布门禁）；golden 评测集与 CI 门禁；SIT/UAT 环境部署。

做（追加）：MCP Server（原计划二期，应要求提前——Streamable HTTP 四工具：upload_document / recognize_document / extract_fields / query_result，与 REST 共用 services 业务层，双出口单一实现）；AG-UI 识别工作台（原计划二期，应要求提前——POST /agent/run 会话端点 + 规划器 + 三工具 + 可嵌入 React 工作台前端，三出口成型，见 3.7）。

不做（但接口预留）：跨引擎投票与复杂路由（二期）、智能体试点接入与 OAuth 对接（二期）、批量异步（二期）、训练流水线（三期）、消息队列（按需）、Redis（二期引入——一期限流用 PG 计数、引擎并发用 asyncio 进程内信号量）。一期与二期的切分是**“多引擎接入 → 多引擎协同决策”**：一期双引擎各自可用、类型声明三种基础模式（OCR 直出 / VLM 全读 / OCR 定位+VLM 精读），二期才有跨引擎投票这类组合决策。预留方式：编排引擎的引擎调用走适配器接口而非直连；融合器接口预留投票扩展点；结果模型字段（engines_used、needs_review）一期即落库。

3.2 工程结构

后端单仓（Python 3.12+，uv 管理）+ 两个独立前端工程：

idrp-backend/
├── server/            # FastAPI 应用：网关、管理 API、编排入口
│   ├── services.py    # 公共业务层：REST / MCP / AG-UI 三出口单一实现
│   ├── mcp_server.py  # MCP Server 独立进程（:8001/mcp，Streamable HTTP）
│   ├── api/           # REST 路由（/v1、/admin/v1）与 AG-UI 端点
│   └── agent/         # AG-UI 运行时：events / tools / runtime / api
├── core/              # 领域层：结果模型、类型引擎、编排状态机、融合器
├── adapters/          # 引擎适配器（paddleocr_vl + vlm）+ 注册表
├── preproc/           # 预处理：栅格化
├── eval/              # golden 集管理、准确率计算、门禁脚本
└── tests/             # 契约与流程测试（离线假引擎）

idrp-frontend/         # 管理台前端（Vue 3 + Vite：类型编辑/评测/发布门禁）
idrp-workbench/        # 识别工作台前端（React 18 + TS + AntD 5，可嵌入，见 3.7）

3.3 数据库详细设计（核心表）

延续规划方案 6.2 的域划分，一期落 7 张核心表（PostgreSQL，均带 created_at/updated_at）：

-- 文档域
documents(id, doc_id UNIQUE, source_caller, original_uri,   -- MinIO 对象
          mime_type, page_count, checksum, status)           -- uploaded/parsed/failed

-- 识别域
recognition_requests(id, log_id UNIQUE, doc_id FK, doc_type,
          doc_type_version, status,                       -- 见 3.9 状态机
          engines_used JSONB, latency_ms, error_code)
recognition_results(id, request_id FK, unified JSONB,        -- 统一结果模型全文
          field_count, review_count)

-- 证据域
result_blocks(id, request_id FK, page_no, block_type,
          bbox_norm JSONB,                                   -- 归一化坐标 [0..1]
          text, confidence, source_engine, artifact_uri)

-- 配置域
doc_types(id, doc_type, version, status,                      -- draft/released/deprecated
          definition JSONB,                                  -- 字段/提示词/版式先验/路由
          released_at)
engine_registry(id, engine_id, version, capabilities JSONB,
          endpoint, cost_profile, health, enabled)
golden_sets(id, set_id, doc_type, doc_uri, expected JSONB)
eval_runs(id, doc_type, doc_type_version, accuracy JSONB,
          passed, ran_at, trigger)                           -- ci/release/manual

3.4 统一结果模型定版（一期冻结内容）

以规划方案 3.2 的 JSON 为基线，一期补充冻结四点：坐标一律归一化到 [0,1]（相对页宽高，保留 4 位小数）；confidence 取值 [0,1]，未标定引擎给保守默认 0.5 并在 meta 标注 calibrated: false；block_type 词表一期含 text / handwriting / table / seal / figure / signature；fields[].value 统一字符串承载，数值与日期格式由类型 Schema 校验。定版后任何变更走大版本。

3.5 REST API 契约（一期）

错误码体系：4xx 消费方错误（INVALID_FILE、RECIPE_NOT_FOUND、QUOTA_EXCEEDED），5xx 平台错误（ENGINE_TIMEOUT、ENGINE_UNAVAILABLE、INTERNAL）；所有响应带 log_id；限流按调用方配额（一期以 PG 计数实现，二期 Redis 全局化）。

3.6 MCP Server（提前实现）

独立进程 server/mcp_server.py（uv run python -m server.mcp_server，默认 :8001，端点 /mcp），官方 MCP Python SDK（2.x MCPServer）+ Streamable HTTP 传输：

• 四个粗粒度工具：upload_document（base64 内容 → doc_id）、recognize_document（统一结果全文）、extract_fields（字段轻量视图）、query_result（历史查询）；
• 与 REST 共用 server/services.py 业务层——双出口单一实现，工具层只做协议适配不写业务；
• 工具 docstring 即 LLM 说明书（何时该用、参数含义、needs_review 提示），参数 schema 由类型注解自动生成；
• 错误契约与 REST 同构（error_code/error_msg 结构化返回，不抛协议错误）；
• 调用方鉴权与网关接入（OAuth 2.1 资源服务器语义）随二期智能体试点完善。

3.7 AG-UI 识别工作台（提前实现）

第三出口：面向终端操作者的对话式识别界面（规划方案 3.4）。后端 server/agent/ 四模块 + 独立前端工程 idrp-workbench。

后端（AG-UI 运行时）：

• 事件层 events.py：AG-UI 协议事件构造——RUN_STARTED/FINISHED/ERROR（生命周期）、TEXT_MESSAGE_START/CONTENT/END（流式文本，按块拆分）、TOOL_CALL_START/END（工具过程）、STATE_SNAPSHOT（状态快照），SSE data: 帧下发；
• 端点 /agent/run（agent/api.py）：接收 RunAgentInput（threadId、runId、messages、state），流式返回事件；X-Agent-Token 头做嵌入鉴权（骨架期全局 token，随调用方管理演进为按调用方签发的 JWT，携带用户/机构声明）；
• 规划器 runtime.py：默认规则规划器（离线可测：上传 → 选类型 → 识别 → 复核的会话状态机，类型词优先、上传通知重置残留状态、单轮动作数上限防失控），IDRP_AGENT_PLANNER=qwen 可切 LLM 函数调用规划（复用 VLM 通道）；
• 工具层 tools.py：list_doc_types / extract_fields / query_result 三工具——与 REST、MCP 调同一 services 业务层（三出口单一实现）；工具错误以结构化契约返回并转成可见文本事件；
• 交互细节：长耗时识别先发"正在识别"文本事件再执行工具（多页文档 1–2 分钟期间界面不失联）；每次识别的 fields/log_id 经 STATE_SNAPSHOT 下发驱动界面。

前端（idrp-workbench）：

• React 18 + TypeScript + Vite + Ant Design 5；自研 ~150 行 AG-UI 事件客户端（协议本身轻量，规避组件库 API 快速演进风险；后端是标准 AG-UI，可随时换 CopilotKit 等框架接入）；
• 会话界面：上传区（REST 拿 doc_id 进共享状态）→ 对话气泡（流式）→ 工具执行卡（进行中/耗时）→ 字段表（needs_review 高亮）→ 人工复核表单（复核意见作为新消息回传）→ 会话内识别记录（点击回看）；
• 嵌入契约：/workbench?token=… 注入凭证（localStorage + X-Agent-Token 头）；生产与平台服务同域部署，SSE 经代理需关闭缓冲（nginx proxy_buffering off）。

全屏打开 ↗

分期演进：二期补 postMessage 结果回传、按调用方/用户/机构的权限过滤（list_doc_types 只返回授权类型）、嵌入方自助接入；比对能力（compare_documents）落地后增设比对视图（同工程分流，见规划方案 3.4 视图拆分原则）。

3.8 管理端详细设计（一期最小集）

管理端服务平台运营方与接入人员，是文档类型化架构（规划方案 3.6）的运营界面。一期定位"最小但完整”：类型发布门禁的完整流程必须有界面，其余能力 API 优先、界面跟进。

功能模块（按优先级）：

管理 API（/admin/v1/*，与能力 API 隔离部署路径，独立管理鉴权）：

/admin/v1/doc-types          GET/POST/PATCH   类型草稿 CRUD
/admin/v1/doc-types/{id}/release   POST       发布（内部先触发评测门禁，未通过则 409）
/admin/v1/doc-types/{id}/rollback  POST       回滚至历史版本
/admin/v1/golden-sets      GET/POST         样本与期望标注管理
/admin/v1/eval-runs        GET/POST         评测触发与记录查询
/admin/v1/engines          GET/PATCH        注册表查看与启停
/admin/v1/callers          GET/POST/PATCH   凭证与配额
/admin/v1/requests         GET              审计检索（log_id / 调用方 / 类型 / 时间）

权限与留痕：角色三级——平台管理员（全部）/ 运营（类型 + 评测 + 审计）/ 只读；所有管理操作进审计日志（操作者、对象、前后版本）。发布即版本：每次发布生成不可变类型版本（含渲染后提示词快照），回滚 = 指向历史版本。

分期演进：二期增批量任务监控、MCP 调用审计、消费方自助接入流程（申请→审批→联调状态）；三期增 badcase 工作台（triage/分配/解决/验证）、训练流水线触发与灰度规则配置。

3.9 编排引擎运行时

请求状态机：pending → preprocessing → engine_calling → fusing → completed；异常路径 engine_calling --超时/重试耗尽--> degraded（降级为整图直读，结果标注 degraded: true）或 failed。异步执行用 FastAPI 后台任务 + PG 状态表（量级见规划方案 5.1，不引入分布式编排器），引擎并发用 asyncio 进程内信号量限流（多副本下为近似总量，一期规模可接受；二期引入 Redis 后全局精确）。needs_review 是字段级状态（投票不一致/低置信），不是请求级。

3.10 引擎适配器（PaddleOCR-VL 与 VLM）

PaddleOCR-VL 适配器三件事：能力声明（注册表登记 layout/text/handwriting 能力与成本画像）；协议适配（/layout-parsing 契约、参数透传——低阈值与关闭版面检测的手写召回参数封装为预处理策略）；结果归一（服务栅格坐标 → 归一化坐标；版面块标签 → 统一词表；无置信度时的保守默认与标注）。

VLM 适配器：OpenAI 兼容协议接入大模型平台；提示词由类型渲染器生成（模板与字段描述同版本，系统级指令由代码持有）；返回 JSON 修复与类型 Schema 校验；VLM 无原生置信度，融合器按"多次读取一致性"策略赋值（一期可先保守默认并标注 calibrated: false）。

两个适配器都必须通过 conformance test（标准样张进 → 统一结果模型 schema 校验 + 坐标/字段抽检）方可注册。

3.11 评测体系

• golden 集格式：每样本 = 文档对象 + 期望字段 JSON + 关键区块标注；一期每类型 ≥ 50 样本，覆盖典型/边界/低质量三类；
• 准确率口径：字段级完全匹配率为主指标，关键字段（金额、户名）辅以字符级差异率；needs_review 率单列；
• CI 门禁：类型发布与引擎版本变更必须触发 eval_runs，主指标不退化且无字段下降超阈值方可通过；门禁脚本进 CI 流水线。

3.12 一期部署清单

3.13 一期验收标准

① 首个消费方生产调用稳定运行 4 周（可用性 ≥ 99.5%，p95 ≤ 8s/单文档）；② golden 基线建立，准确率与复核率按周出数；③ 评测门禁在 CI 生效并拦截过至少一次违规发布（或演练验证）；④ 全部结果可经 log_id 回溯到证据裁片。

四、二期详细方案

• 智能体试点：MCP Server 已于一期实现（见 3.6），二期工作为试点接入星辰助手一个对话场景（凭证要素查询）、鉴权完善（OAuth 2.1 资源服务器语义）、网关/ESB 路由接入，以及 compare_documents 工具随比对大类补齐；
• 批量异步：/v1/batches（文档集 + 类型）→ 任务句柄 + 进度查询；PG 状态表 + 后台 worker，逐文档复用同步链路；
• 跨引擎投票：类型声明投票字段与引擎组合（如 PaddleOCR-VL + VLM）；投票算法首版先用字符级对齐取多数，不一致即 needs_review——宁可标记不裁断；触发条件由路由策略控制（关键字段或低置信字段）；
• 第二消费方接入：走标准 onboarding（申请凭证 → 选类型 → OpenAPI 联调 → 灰度 → 生产），沉淀接入手册。

五、三期详细方案

• 训练流水线：K8s Job 化——标注导出（badcase 台账 → 训练集）→ PaddleOCR 微调训练 → golden 全量评测 → 镜像构建（带版本 tag）→ 注册表更新；全程 Jenkins/ArgoCD 承载；
• badcase 运营：状态机 reported → triaged(定位: 数据/提示词/模型) → assigned → resolved(类型修复 | 微调排期) → verified；看板指标：闭环周期、badcase 存量、按类型分布；
• 灰度与回滚：新引擎版本按 model_version 参数灰度（5% → 50% → 100%），评测指标异常自动冻结灰度；回滚 = 注册表切回旧版本（镜像不可变）。

六、项目计划

6.1 里程碑时间线（相对周）

6.2 人力配置

6.3 外部依赖与协调

七、实施风险与应对

八、度量与验收汇总

5 - StarWork 桌面端技术架构

依据 star-work 仓库源码与 README.md 编制，与云控服务端架构互为表里：本文讲桌面端（终端），彼文讲服务端（治理）。文中四张图表均为交互式：支持缩放、语义视图、关系追踪与 PNG/SVG 导出。

一、项目概览

StarWork 是 AI 原生的企业级 Office 套件：一个桌面应用里装下文档、表格、演示、PDF、Markdown 五个编辑器，AI 与人工操作共用同一套文档模型——AI 能直接读写文档结构（改段落、改单元格、生成整套演示），而不是只在对话框里隔空聊天。打开和保存都是标准 Office 格式，不引入私有格式；本地功能不联网；AI 改动受代码级门禁约束。

二、总体技术架构

三层拼装：通用的 Agent 引擎负责「想」，成熟的编辑器负责「编辑」，自研的是把两者接起来并管得住的那一层。

全屏打开 ↗

• 统一外壳（自研 src/）：一个窗口 + 顶部标签页；首页工作台（会话、项目管理、记忆、设置）；Agent↔编辑器桥与工作区围栏；云控客户端；国际化与主题。
• Agent 层：第三方 pi-coding-agent SDK 承担推理与调度；自研的 workspace-jail 给全部会话套上文件/命令围栏，editor-bridge 为每个编辑器标签页注册领域工具。
• 编辑器层（自研应用层 + 文档引擎）：五个编辑器应用 + 14 个共享能力包；模型请求经模型网关（one-api 类）以 OpenAI 兼容协议转发，云控下发的网关根地址在客户端做 /v1 版本段幂等补全（model-url.ts），根治多实例网关偶发 404。

三、进程与运行时模型

全屏打开 ↗

• 一个主进程承载全部业务逻辑：五个编辑器的主模块都打包进同一个进程，窗口只有一个，靠标签页切换（tab-manager.ts）；
• 每个打开的文件新增一个界面视图（WebContentsView），首页不占独立视图——界面层进程数 = 1 + 打开的文件数，与应用个数无关；
• 真正的操作系统子进程只有一个：表格的 Rust 原生引擎 xlsx-sidecar，第一个表格打开时启动一次（带预热），之后所有表格共用，靠会话标识区分文件；
• 界面层拿不到文件系统与系统命令，所有文件读写与外部调用都经主进程受控执行，前后端走本机 IPC，不经网络。

四、编辑器与能力包

14 个共享能力包（packages/）按职责分四类：

五、AI 改文档的三条硬约束

这些约束不是提示词，是代码里的门禁。

5.1 演示：逐页生成与导出门禁

全屏打开 ↗

一句话任务进入后：附件与联网检索结果分配 [S#] 来源编号 → 大纲按页面角色逐页规划 → 模型流式生成语义 SVG（deck-stream）→ 每页过质量门禁（svg2pptx/quality.ts，与导出器共用同一渲染前端——凡是门禁放过的，导出器必然能渲染）→ 全套就绪后导出原生可编辑 PPTX，引用编号写入演讲者备注。

• 阻断项：页面角色缺失、元素越界、引用编号悬空 → 阻断导出；附件未读完 → 拒绝生成整套演示；
• 告警项：精确数字无来源 → 告警不阻断；
• 回归保障：127 份真实模板（decks/layouts/charts/tables）在 templates.test.ts 中持续验证产物一致性，改动导出器必跑。

5.2 表格：提议 → 预览 → 事务提交

AI 产出不直接改文件：先过 schema 校验 → 修订冲突检测 → 生成预览 → 使用者确认后才作为事务提交（apps/sheets/src/renderer/ai/ 的 response-verify / retry-prune / 编辑队列）。公式引用链可追踪审计（formula-audit）。大工作簿的内存占用与整表规模解耦、只与视口相关（架构如此，暂无实测基准）。

5.3 文档：按段落打补丁

docx-engine 以带 docxIndex 锚点的 Block 树解析 docx，保存时只重写 AI 实际动过的段落——样式、批注、页码等其余内容原样保留。

六、安全模型

• 工作区围栏（src/main/pi/workspace-jail.ts，1629 行）：全部 pi 会话共用；read/ls/grep/find/write/edit 路径越出工作区直接抛错，read 按扩展名分流——二进制文档经 file-parse 提取文本，图片保持裸字节交给多模态模型；
• 命令沙箱：macOS 用 sandbox-exec 硬沙箱（读写只放行工作区/临时目录/工具链缓存，$HOME 凭证目录不可读写）；Windows 无等价沙箱，用 spawnHook 命令级拦截（拦得住字面量，拦不住变量拼接）——如实说：强度低于 macOS；
• 网络：sandbox-net 沙箱代理受控放行；云控通道 TLS + 设备令牌；
• 委派（pi/delegate.ts）：把一整件事交给某个编辑器标签页的 agent 去办——模型只决定「目标应用 + 任务内容 + 源文件」，账号/会话/标签页寻址由主进程处理，领域工具与围栏在目标标签页那边。

七、云控通道

企业侧由云控承担：模型、配置、技能、版本、日志由服务端统一下发与回收，终端使用者不需要配置任何密钥。

全屏打开 ↗

客户端连接策略三阶段（src/main/cloud/client.ts）：启动期按内置清单轮询生产→准生产→测试入口（地址清单编译进 App，云控删不掉）→ 连上后按本地策略重连（间隔封顶 10s + 随机抖动）→ 连续失败够多次自动轮换候选入口。掉线判定由 socket error/close 驱动，睡眠唤醒后心跳失败主动 revalidate() 兜底 TCP 僵死的「假连接」。服务端侧协议与部署详见云控服务端技术架构。

八、工程与质量

• monorepo：根（外壳）+ apps/（5 编辑器，每个 = 主模块 + 界面层 + preload + shared）+ packages/（14 能力包），pnpm workspace；
• 开发形态：pnpm dev 并行起五个编辑器渲染服务（5173–5177，HMR）+ 外壳（首页 5199）；云控固定连本机 ws://127.0.0.1:8090；改主进程代码需重启 dev；
• 质量门禁：pnpm typecheck（主进程 + 首页 + 五编辑器）、ESLint + Prettier、vitest 单测分布在 apps/*/tests 与 packages/*/tests（实测合计 672 个 *.test.ts）；表格端另有 gate 全量门禁（typecheck + 夹具 + cargo test + 兼容性校验）；
• 运行期数据（开发形态）：~/Library/Application Support/StarWork Dev/（Windows %APPDATA%/StarWork Dev/）——home/projects.json（工作区）、app-settings.json、cloud-config.json、pi-sdk/models.json（云控下发的模型目录）、pi-sdk/sessions/ 与 home/pi-sessions/（完整对话与工具调用流水，排查问题先看这里）。

九、已知限制

6 - StarWork 云控服务端技术架构

依据 star-work-cloud 仓库源码与工程内文档（README.md / PROTOCOL.md）编制。文中四张图表均为交互式：支持缩放、语义视图、关系追踪与 PNG/SVG 导出。

一、项目概览

star-work-cloud 是桌面端（StarWork / Milo 客户端）的云控服务端：单个 Go 进程同时对外提供两条服务，共用一份 PostgreSQL 与同一套业务层。

代码采用经典分层：handler（解析请求/统一响应）→ service（业务逻辑）→ repository（数据访问）→ model（GORM 模型）；云控长连接独立成 internal/cloud（信封、会话表、topic 注册表、分片下发），TLS 治理在 internal/tls，后台巡检在 internal/worker + internal/leader（PG advisory lock 选主）。

二、总体架构

单进程内三个协作者：TLS 长连接服务（握手 / AUTH / 信封协议 / 会话表）、HTTP API（JWT + casbin 鉴权的 10 组管理接口）、后台巡检 Worker（心跳、补推、归档、选主）。入口分两条：设备走 L4 直达（NodePort / LB 的 TCP 8443，HTTP Ingress 无法转发 4 层 TLS），管理端走 Ingress 的 /starwork/api 前缀；前端 SPA 与后端同源部署，刻意不配置 CORS。

全屏打开 ↗

三、统一信封协议（Protocol v1）

一套信封覆盖上报 / 下发 / 配置同步 / 心跳，传输与业务分离：信封（怎么传）一次写死，业务能力以 topic 扩展——新增功能 = 注册表加一行 + 两端各一个处理函数，协议本身不动。

可靠性三件套：幂等（客户端记录已处理 id，重复消息直接 ack）、应答超时重试（按 meta.timeout/retry 重发，只补发未确认分片）、大 payload 分片（meta.seq/total 重组，可选 gzip 压缩）。

四、配置同步与定向下发

配置是云控的自举基座——客户端连接地址本身就在配置里，因此「地址可远程更新」是第一需求。服务端维护全局配置表（configs：每份配置独立 configId 与单调递增版本号，不按用户区分），客户端本地原子持久化（cloud-config.json），启动 / 重连必执行 config.sync 对账。

全屏打开 ↗

三个核心设计：

1. 双通道兜底：config.push（服务端定向推送，在线即时生效）+ config.sync（客户端拉取，离线攒下的新配置上线即补）。配置类消息靠 sync 全量对账兜底，离线队列只保留给一次性指令（重启、升级等）。
2. 全量下发 + 按字段合并：服务端始终下发完整配置对象，客户端按顶层字段合并（收到覆盖、未收到保留）。自带自愈——任何丢失或本地文件损坏，下次连接全量对账即恢复；配合原子写（临时文件 + rename）与版本守卫（旧版本拒绝覆盖新版本）。
3. 定向匹配：to 描述支持 platforms / deviceIds / minVersion 的 AND 组合——同一账号的 mac 更新只命中 mac 设备。每次下发落 config_deliveries + 逐设备明细（msg_id 关联 ack，状态 pending / delivering / done / failed），删除下发记录即撤销。

五、技能包与版本包分发

技能（zip，内含 SKILL.md）与版本安装包共用同一套 TLS 分片分发套路：base64 分片（128KB 原始字节/片）、共用命令 id 幂等、收齐重组后与元信息 sha256 强比对。设备端不暴露公网下载地址，HTTP 下载接口仅限管理端（JWT）。

全屏打开 ↗

关键防线与落地策略：

• 版本更新走配置携带：release 表（version / platform / arch / sha256）绑定到配置，随 config.push / config.sync 全量下发；客户端做平台/架构匹配（不符不弹窗）、版本比较（不高于当前忽略）、单会话去重后才弹确认窗。
• 技能按 category 六类落盘：global（全部编辑器）/ docs / sheets / slides / pdf / markdown 各自目录，非白名单取值兜底为 global；同目录原子替换 + .cloud-skill.json 登记，装完即用无需重启；后台改分类后，已装设备「更新」时自动迁移目录并清旧副本。
• 解压安全：防 zip-slip 路径穿越、校验 SKILL.md 必须存在，非法即回滚。

六、设备连接生命周期

连接治理三参数：握手读超时（10s）、空闲读超时（600s）、并发连接上限（默认 10000）；可选 DEVICE_AUTH_SECRET 二次鉴权。心跳按连接时长四阶段退避（15s → 30s → 60s → 5min），在线判定随策略动态计算：now - lastSeen < onlineTimeoutFactor × 当前阶段期望间隔（默认 2 倍系数）——Dashboard 不写死超时窗口，直接消费服务端状态字段。

全屏打开 ↗

七、数据模型

16 张业务表 + casbin 策略表，全部 GORM AutoMigrate 自动建表，无外键约束（运维规范），关联仅应用层维护：

八、安全设计

启动强校验（不满足直接退出）：JWT_SECRET ≥ 32 字符且非默认值；DATA_ENC_KEY 必须为 base64 的 32 字节。登录密码经 RSA 公钥加密传输（/auth/public-key 分发公钥，私钥服务端持有，生产务必挂载固定私钥文件）。设备侧可选 AUTH 二次鉴权；上传体积（UPLOAD_MAX_MB）与连接治理参数防滥用。刻意不配置 CORS：前后端同源部署于同一 Ingress host（/starwork 前端 SPA、/starwork/api 后端），浏览器只见一个 origin。

九、部署架构

• 镜像：CGO_ENABLED=0 静态二进制（amd64 / arm64 交叉编译），builder golang:1.26.3 + runtime alpine:3.12；vendor/ 入库离线构建（-mod=vendor），构建机无外网可编译。alpine 无 tzdata，二进制内嵌 time/tzdata 支撑 DB_TIMEZONE=Asia/Shanghai。
• K8s（Helm）：两端口同 Service（tls 8443 / http 8090，ClusterIP）；/app/data（上传包、归档、RSA 私钥）挂 PVC（nfs-client 动态供给，20Gi RWO）；8443 证书由 chart 建 Secret、流水线 --set-file 注入；JWT_SECRET / DATA_ENC_KEY 必须环境变量注入。
• Ingress 三前缀（最长前缀优先）：/starwork/api → 后端 8090；/starwork → 前端 SPA；/admin/static → 前端旧入口（301 到 /starwork/）。
• CI/CD：Jenkins 三环境流水线（sit / uat / prd：拉码 → make release-image.amd64 构图推 Harbor → Helm 部署）；敏感参数 sit 明文 / uat·prd 打码。

多副本就绪

设备长连接只在持有它的副本内存里，方案是不让副本共享会话（那要 Redis），每个副本自扫 + DB 兜底：

十、已知约束与演进

1. scripts/docker-deploy.sh 依赖的 docker-compose.yml 尚未入库。
2. builder 镜像 golang:1.26.3 tag 需 DevOps 在 Harbor 确认或新建。
3. vendor/ 约 270 MB（含已不被引用的 sqlite 依赖），清理需外网重跑 go mod vendor，或改私有 proxy。
4. 8443 需运维单独放通（NodePort / LoadBalancer / TCP 转发其一），HTTP Ingress 转发不了 4 层 TLS。
5. Ingress 的 serviceName 与前端仓库耦合（/admin/static 指向 star-work-cloud-front），改 release 名需两边同步。
6. 路由前缀 /staroffice → /starwork 的旧库迁移已自动化：种子菜单就地更新、casbin 旧前缀策略清理、接口条目按新路由重建，旧库重启即自动跟上。