# Work OS MVP:API Gateway 系统架构与功能设计 > 2026-10-10 实现更新:Agent Runtime 已替换为 PC 持久化模块,新增管理员编排接口。本文保留总体设计契约;当前运行契约见 [AgentRuntime/openapi.json](../../AgentRuntime/openapi.json),管理 API 和实施边界见 [实现说明](../../AgentRuntime/README.md)。 版本:1.0(设计基线) 日期:2026-10-10 状态:待开发;不是运行实现或国产化认证报告。 关联仓库:[delltom2000/workosMvp](https://github.com/delltom2000/workosMvp)。设计输入为用户本次提供的《Work OS 1.0 系统架构图(模块、消息流与控制流)》及仓库提交 `321dca9774d8f3a34cb599478f4b60e64b8c723f` 下的 `base1`。已读取远端系统设计,和本地基线一致。 配套交付:[接口目录](api-catalog.json)、[PC 核心 OpenAPI 3.1 契约](openapi.json)、[模块装配示例](modules.example.json)、[配置 Schema](modules.schema.json)、[Nginx SSE 配置片段](nginx.conf.example)、[可校验的接口示例](examples.json)。主文档给出完整设计边界;OpenAPI 覆盖接口目录中标记为 PC 的操作,后续阶段接口先列出目标,不伪装成可调用接口。 ## 1. 设计结论与已有方案的衔接 采用 **FastAPI 应用接入层 + 可替换的模块 Port/Adapter + 可选 Nginx 边缘代理**。PC 阶段 Gateway 与七个业务模块同进程装配,耗时流程在独立 worker 中执行。腾讯云或麒麟服务器阶段可以先保持相同结构,需要独立扩容时再将指定模块的 local adapter 换成 HTTP adapter。 Gateway 的职责是“把经过验证的请求交给正确模块,并向正确用户返回结果和进度”。它负责路由、身份、输入边界、统一错误、限流、跟踪、流式出口和协议版本;公文编排属于 Agent Runtime,知识检索属于 Knowledge,模型选择属于 LLM Gateway,本机工具授权与执行属于 Tool Gateway。 | 与原设计的关系 | 本文决定 | |---|---| | 七个核心服务 | 保持 Workspace、Context、Knowledge、LLM、Agent、Tool、Notification;API Gateway 与 Identity 仍为接入支撑 | | API01 / G01、G02 | 细化可信 Principal、统一路由、错误、日志和可替换装配 | | API02 / G03 | 保持单文件 10 MiB 上限,补充实际流量计数、格式识别与超时规则 | | API03 / G04 | 细化授权 SSE、持久游标、断线恢复、令牌过期和慢客户端 | | 公网 Identity 暂不对接 | PC 使用签名演示身份 Provider;服务端稳定映射用户,不接受前端自由指定身份 | | 图中的消息总线 | PC 以 PostgreSQL 事件、任务与 outbox 实现;RabbitMQ/Kafka 属扩展选择,不增加首周必需依赖 | | 网页原型 `/api/...` 接入建议 | 统一正式契约为 `/api/v1/...`;原型当前没有实际后端,不需要兼容不存在的接口 | | 图中的 WebSocket | PC 使用 HTTP 命令 + SSE 事件;双向设备连接等能力以后按需增加 | | 原图中直连箭头 | 所有 Portal/Admin 公网请求必须过 Gateway;后端模块间调用按 Ports 进行,不绕回公网入口 | 一人配合 AI 开发时,第一步不引入独立 APISIX/Kong 集群、服务注册中心和消息总线。未来需要独立边缘网关时,可在外部增加代理,保留本层业务身份与资源授权边界。新增模块并非“完全零代码”:已有契约换实现主要改配置,新增业务语义必须有新 DTO、handler 与验收用例。 ## 2. 目标、范围与成功标准 PC 必须实现:统一 `/api/v1`、双用户身份与资源隔离、受限上传、事项与公文任务入口、Skill/员工能力入口、人工确认、SSE 续读、统一错误和审计。允许真实模型或 fixture 模式,但必须返回真实模式标识,不能在失败时静默变成模板演示。 本模块不负责 PDF/OCR、提示词编排、知识切分、模型推理、DOCX 排版、企业微信 token 管理或正式 OA 审批。它提供这些能力的受控入口和结果查询。本文不把这些业务实现算入 Gateway 工时。 | 阶段 | 部署形态 | 入口与约束 | 验收边界 | |---|---|---|---| | P0:PC | 单个 Uvicorn API 进程 + worker + 原生 PostgreSQL + local runner | 默认 `127.0.0.1:8000`;Portal 同源;演示身份 | 10 月 18 日前完成 PC 演示;以既有 10 月 17 日验收安排为目标 | | P1:腾讯云 | HTTPS 边缘代理 + 应用容器/进程;初始仍单 API 进程 | HTTPS、受限账号、外网 Identity 或受控演示账号;PC 工具走主动出站连接器 | PC 验收之后,单独验收 | | P2:麒麟 + 海光 | 银河麒麟服务器版上的 systemd/受支持 OCI 运行时 | 内网 CA、离线包、平台兼容性记录;按客户需要接入国产中间件与密码设备 | 真实目标机适配验收;不自动纳入首周承诺 | ## 3. 逻辑架构与请求链 ```mermaid flowchart TB Portal[Portal Web:对话、事项、专家、技能] --> Edge[可选 Nginx:HTTPS 与连接边界] Admin[后续 Admin Web] --> Edge Edge --> Gate subgraph Gate[API Gateway / FastAPI] Guard[Host/CORS/请求大小/trace] --> Auth[IdentityProvider / Principal] Auth --> Policy[权限范围 / 限流 / 输入校验] Policy --> Router[版本化 APIRouter / Operation Registry] Router --> Ports[显式 Port 装配 / local 或 HTTP adapter] Stream[授权 SSE / 游标 / 心跳 / 背压] end Ports --> WS[Workspace Service] Ports --> KB[Knowledge Service] Ports --> AR[Agent Runtime] Ports --> NT[Notification Service] Ports --> TG[Tool Gateway:能力与回执查询] Ports --> CTX[Context:授权摘要查询] AR --> CTX CTX --> KB AR --> LLM[LLM Gateway] AR --> TG AR --> NT AR --> Events[持久 Run Event / EventReaderPort] Stream --> Events Router --> Stream Auth --> ID[演示身份 / OIDC Adapter] ``` 普通请求次序:生成服务器 trace → 限制 Host、方法、大小和来源 → 路由匹配 → 校验 Bearer token → 生成不可变 Principal → 读取能力开关和权限范围 → 校验 DTO → 调用领域服务 → 领域服务检查资源归属 → 领域事务提交 → 统一响应与审计。 SSE 在上述检查后进入独立的流处理路径,不套用普通请求的 10 秒总超时。上传在框架完整解析 multipart 之前通过 ASGI receive 包装器累计请求体字节数;不能仅依赖 Content-Length 或等待 `UploadFile` 已落临时文件后才检查。 应用工厂 `create_app(settings, providers)` 在 lifespan 中创建共享 HTTP client、连接池和模块 registry,退出时释放资源。中间件采用原生 ASGI 包装实现流量计数和流式审计,避免为日志读入整个响应正文。FastAPI 的 APIRouter 与依赖注入可复用路由和身份依赖:[官方组织方式](https://fastapi.tiangolo.com/tutorial/bigger-applications/)。 ## 4. 技术栈与版本策略 下表是选型系列,不是可直接安装的精确依赖锁。首次工程初始化需在 Windows 与目标 Linux 上解析同一套兼容依赖,提交精确补丁版本、传递依赖、hash、许可证清单及镜像 digest;禁止生产使用浮动 `latest`。本次不虚构一份未经安装验证的精确 lock。 | 部件 | 建议技术 | 本模块用途 | 替换边界与国产化影响 | |---|---|---|---| | 语言 | CPython 3.12 系列的受维护安全补丁版本 | 与已有 Python 后端保持一致 | 自带独立解释器,不覆盖麒麟系统 Python;选择客户允许的软件包来源 | | HTTP 框架 | FastAPI + 其依赖约束允许的 Starlette | Router、DI、DTO、OpenAPI、流式响应 | 不单独强升 Starlette 破坏依赖约束 | | DTO / 配置 | Pydantic 2、pydantic-settings 2 | 请求响应、配置校验,写入 DTO `extra='forbid'` | pydantic-core 含 Rust 原生扩展,必须核对 wheel/ABI,不能称为全纯 Python | | ASGI 服务 | Uvicorn;基线 `--loop asyncio --http h11` | PC/Linux HTTP 服务 | 不依赖 uvloop/httptools 的平台 wheel;后续性能优化单独验证 | | 模块远程调用 | HTTPX AsyncClient | HTTPS、连接池、明确超时、内部服务身份 | 本地模式不经过 HTTP;远程模式才启用连接池和断路保护 | | JSON/配置文件 | 标准 JSON + JSON Schema | 模块映射、策略参数、版本 | 首期不用可执行脚本作为配置,不接收用户 URL 作为 upstream | | 身份 | IdentityProvider;PC JWT 演示实现,正式 OIDC/JWKS adapter | 验签、issuer/audience/expiry、主体映射 | 固定算法允许表;正式签名库及加密依赖纳入 ABI 适配 | | 流式出口 | Starlette StreamingResponse + 明确 SSE 编码器 | 状态、步骤、受控增量内容 | 无需 WebSocket;事件持久化和回放由 Runtime 负责 | | 持久化 | 复用 PostgreSQL、SQLAlchemy 2、Alembic、psycopg 3 | 领域事件、幂等与身份会话记录的存储适配 | Gateway 不跨模块写业务表;国产数据库通过 RepositoryPort 单独适配 | | 边缘代理 | Nginx(服务器阶段) | TLS、SSE 禁缓冲、连接限额、静态资源 | 使用目标平台受支持包;有国密要求时接入经选定认证的密码边界 | | 可观测性 | JSON 日志;Prometheus client;OpenTelemetry 接口预留 | 延迟、错误、连接、trace | PC 可先本地日志与受限指标,服务器阶段接内网采集系统 | | 验证工具 | pytest + HTTPX/ASGI;Playwright;压测工具后选 | 契约、权限、SSE、浏览器流程 | 本文提供验收要求,不声称已执行网关运行测试 | Uvicorn 提供 asyncio/h11 参数选择:[官方设置](https://www.uvicorn.org/settings/)。Pydantic 的验证核心采用原生实现:[官方架构说明](https://pydantic.dev/docs/validation/latest/internals/architecture/)。HTTPX 的连接、读写和池等待超时应分开设定:[官方超时说明](https://www.python-httpx.org/advanced/timeouts/)。这些能力是框架事实;下面的阈值和流程是本项目设计决定。 ## 5. 上下层接口与模块责任 ### 5.1 上层消费者 | 上层 | 协议 | 使用的能力 | 约束 | |---|---|---|---| | Portal Web | HTTPS REST + fetch SSE | 登录、事项、消息、附件、员工、Skills、任务、草稿、通知 | 每个资源请求独立鉴权,切换账号清理缓存与订阅 | | 前端插件面板 | 复用 Portal SDK | 按 capability/operation_id 展示允许操作 | manifest 仅描述界面,不给任意路径、任意脚本或服务凭据 | | Admin Web(后续) | `/admin/v1` REST | 模块状态、策略和审计管理 | 独立管理员权限与网络访问策略;普通用户 token 不可调用 | | 授权 PC Connector(云阶段) | `/device/v1` HTTPS | 领取工具任务、回传 receipt | 使用设备身份,不复用用户 token;绑定用户、设备与允许工具 | | 运维系统 | 内网 HTTP/HTTPS | live、ready、metrics | 只读,诊断详情和指标不公开 | ### 5.2 下层对接 | 模块 | Gateway 可调用的 Port | PC | 拆分部署后 | 业务责任与公开边界 | |---|---|---|---|---| | Identity | verify / login / revoke | 演示签名 Provider | OIDC 标准流程、JWKS;可选受控 introspection | 生产身份不接受仅用户名登录;不直连 LDAP 数据库 | | Workspace | workspaces/messages/attachments/artifacts | 进程内 Protocol | 固定 HTTPS endpoint + DTO | 每次校验归属;草稿版本和附件路径由该模块控制 | | Context | read_authorized_summary | local adapter | 内部 HTTPS | 门户只看已授权来源摘要;完整模型上下文由 Runtime 内部调用构造 | | Knowledge | bases/search/citation/ingestion | local adapter | 内部 HTTPS | 检索前过滤授权,原文获取再鉴权;入库耗时任务异步化 | | Agent Runtime | start/read/events/cancel/approve/catalog | local adapter + 独立 worker | 命令 HTTP + 内部事件读取接口 | 负责工作流与员工/Skill registry;Gateway 不解释 Skill 为代码 | | LLM Gateway | 本次不直接公开推理 Port | Runtime 内部调用 | Runtime → LLM 内部 HTTPS | Gateway 只转发 Runtime 产出的事件;前端拿不到模型密钥 | | Tool Gateway | list_capabilities/read_receipt | local adapter | 内部 HTTPS;device 路由另设 | 公共入口没有通用 execute-shell/execute-tool;实际执行由已确认工作流触发 | | Notification | list/read_status/mark_read | local adapter | 内部 HTTPS | 企业微信发送、收件人映射和 outbox 在 Notification 内部 | 共享 Principal 类型:`tenant_id, user_id, scopes, auth_mode, session_id, expires_at`。Gateway 仅从已验证凭据生成它,拒绝请求体中的 owner/user/tenant 替代字段;用户上传材料也不能产生 Principal。资源不存在与非本人资源统一返回 404,避免枚举;已登录但缺少全局操作权限返回 403。 local adapter 传不可变 Principal 对象。远程 adapter 不直接信任裸 `X-User-Id`:使用服务身份(mTLS)和短期、目标 audience 绑定的内部委托令牌,绑定原始主体与允许 scope;下游仍检查资源归属。入口丢弃客户端伪造的内部身份头。禁止在没有网络隔离与认证时将内部服务接口开放到公网。 ## 6. 以最少改动扩展模块 ### 6.1 三层注册 1. **代码层**:受审查的 `ModuleProvider`、Port 与 Router,全部使用静态允许表。不得从上传的 Skill、任意目录或 JSON 字段动态 import 任意 Python 代码。 2. **配置层**:`modules.example.json` 指定 module_id、adapter_key、contract_version、enabled 和服务器侧 endpoint_ref。部署地址与密钥引用由环境配置解析,不允许客户端提交 upstream URL。 3. **能力层**:Runtime 提供员工、Skill 和插件能力目录,关联权限与 workflow_version。Portal 根据 `/capabilities` 更新按钮;服务端仍检查相同能力,不以按钮隐藏作为授权。 启动步骤:校验配置 Schema → 校验 adapter_key 在已编译允许表 → 校验重复 module/operation/path → 按依赖拓扑装配 → 绑定 Port → 注册 Router → 发布 OpenAPI 与 readiness。任何未知 adapter、冲突路由、缺少强依赖都必须使启动失败并给出明确错误。 | 变化 | 最小修改 | 是否重启/发布 | 验证 | |---|---|---|---| | 同契约模块更换地址 | endpoint_ref 指向的新环境值 | 滚动重启 Gateway | 证书、契约版本与健康检查 | | 关闭公文能力 | approved config 中 enabled=false | PC 重启生效;不设计首期远程配置写接口 | 新 run 返回 CAPABILITY_DISABLED;旧 run 可读、取消;既有执行按锁定快照继续,紧急停用另走取消 | | local Workspace 换 remote Workspace | adapter_key + endpoint_ref | 首次增加 HTTP adapter 需要发布;之后地址变更只改配置 | 相同 DTO/错误/归属结果;数据迁移另验收 | | 新增数字员工/Skill | 受控 registry 记录与版本 | 数据变更;新任务读取新版本 | 权限与允许工具不因 Skill 内容扩大;运行中快照不变 | | 新增同业务契约的下游实现 | 实现 Port,注册 provider | 一次代码发布 | 契约测试;Gateway 中间件不变 | | 新业务接口或新文种语义 | DTO、Router、权限、Port、OpenAPI 与测试 | 代码发布 | 不承诺仅 JSON 配置便能实现新业务 | | API 破坏性升级 | 并行 `/api/v2`、兼容窗口与前端 SDK 升级 | 分阶段发布 | v1 客户端继续可用,之后公告退役 | 首期不做运行中随意增删 APIRouter。配置按 `config_revision` 固定到进程生命周期;先校验新配置,再启新实例、切流、排空旧实例。PC 单进程重启会短暂断开 SSE,客户端按持久游标恢复,worker 中已持久任务继续。 ### 6.2 编码形态 ```python # 设计示意;省略具体领域类型的 import,不是可直接部署的实现。 class RuntimePort(Protocol): async def start(self, principal: Principal, workspace_id: str, command: StartRun, idempotency_key: str) -> RunView: ... async def read(self, principal: Principal, run_id: str) -> RunView: ... @router.post('/workspaces/{workspace_id}/runs', status_code=202) async def start_run(workspace_id: str, command: StartRun, principal=Depends(require_user), key=Header(alias='Idempotency-Key'), runtime=Depends(get_runtime_port)): # Scope/能力检查在公用依赖;归属、幂等与业务事务在 Runtime。 return await runtime.start(principal, workspace_id, command, key) ``` `get_runtime_port` 从应用级 providers 获取实例,不在每个请求里创建 HTTP client。Route 只处理协议,不生成公文、不写业务 SQL。每个服务拥有自己的 Repository 和事务;共享 PostgreSQL 是部署决定,不意味着共享写表权限。 ### 6.2 一次具体的模块替换 假设 Workspace 已实现同一版本的远程 adapter,发布版本中注册了 `workspace.http.v1`。将配置条目从 `workspace.local.v1` 改为下例,即可改变接入位置;Portal URL、DTO、Gateway 中间件不需要跟着改: ```json { "module_id": "workspace", "adapter_key": "workspace.http.v1", "contract_version": "1", "enabled": true, "depends_on": ["identity"], "endpoint_ref": "env:WORKOS_WORKSPACE_ENDPOINT" } ``` 这是假设 adapter 已完成的替换示例,不表示仓库已实现远程服务。运维设置 endpoint、CA、客户端证书和委托令牌签名材料;Registry 从静态允许表选择构造器。启动检查契约版本、网络 allowlist 和服务身份,通过后滚动重启。必须重新跑跨用户隔离、幂等与超时契约测试;如上游返回不兼容 DTO,应返回受控下游错误,不能静默丢字段。 配置附件包含 Identity 加七个业务模块。`depends_on` 指启动装配依赖,不代表请求时必须同步调用所有依赖。`secret_refs` 只存引用:`env:NAME` 读取指定环境变量,`file:NAME` 由部署配置将 NAME 解析为受限密钥文件路径;禁止把引用串当成秘密本身。数据库、Qwen、企业微信等配置由各自 provider 读取。Schema 只验证结构;adapter允许表、endpoint网络范围、依赖拓扑和秘密存在性必须由启动代码继续验证。 ## 7. 对外协议、安全与输入边界 ### 7.1 统一协议 - 所有业务接口前缀 `/api/v1`,JSON UTF-8;日期时间用带时区 RFC3339,数据库存 UTC,界面本地化。ID 是不透明字符串,客户端不拆解前缀推断权限。 - 成功返回明确 DTO;列表统一 `{items, next_cursor}`,`limit` 默认 20、最大 100,游标不接受 SQL/排序表达式。文件下载和 SSE 使用各自媒体类型,不强行包 JSON。 - 错误统一 `{code, message, trace_id, details}`,所有响应携带 `X-Trace-Id`;错误 details 只允许字段名、错误类型和安全的版本信息。 - `Authorization: Bearer ` 仅放请求头;禁止 URL token。浏览器 token 在内存保存,退出清空;PC 不设计长期刷新 token,过期重新登录。正式 SSO 另接 Authorization Code + PKCE,若改 HttpOnly cookie 必须同步补 CSRF 防护与 SameSite 策略。 - PC 演示登录只在 demo 模式、受控本机环境开放;账号密码由部署时注入的配置提供。服务端签发约 15 分钟 token,校验算法允许表、签名、iss、aud、exp、nbf 与稳定主体。logout 记录当前 session 撤销,SSE 最迟下个心跳关闭。 - OIDC 阶段未知 kid 或无有效验证材料时失败关闭;可用缓存只限已信任的签名材料及其明确有效窗口,不以网络失败跳过校验。组织用户目录故障不能转为匿名模式。 ### 7.2 请求边界 | 项目 | PC 默认设计值 | 行为与责任 | |---|---|---| | 普通 JSON body | 256 KiB | ASGI receive 累计;超限 413;正文不写日志 | | 单附件 | 10 MiB(10×1024×1024 bytes) | 一次一文件;multipart 总体另限 11 MiB,元字段限制 64 KiB;无 Content-Length 也累计 | | 允许附件 | pdf、docx、txt、md | Workspace 识别扩展名、MIME 和文件特征;不支持 415,不合法 422;解析异步 | | Skill 内容 | UTF-8 文本 ≤32 KiB | 仅保存方法文本,不能安装包或运行代码;权限与工具白名单独立 | | 上传文件名 | 显示用途,最大 255 字符 | 存储使用随机逻辑 key;路径与下载文件名由服务器净化 | | 文档解析 | Knowledge/受控解析 worker | ZIP/DOCX 解压限量、防路径穿越;扫描 PDF 标识需 OCR;不在 Gateway 请求线程解析 | | CORS/Host | Portal 精确 origin / Host 白名单 | 开发端口显式配置;不使用带凭据的通配源;只信任已配置反向代理地址 | | 普通用户速率 | 60 次/分钟、突发 20 | PC 单进程 token bucket;auth 之前按 IP 限制,之后按 tenant+user+route_class 限制 | | 登录与写作启动 | 登录 5 次/分钟/IP;启动 5 次/分钟/用户 | 429 + Retry-After;Runtime 另外限制单事项一个活跃 run、两个执行槽位 | | SSE | 每用户最多 3 条,进程最多 20 条 | 与请求速率分别计数;断线必须归还额度;PC 单进程限制不冒充集群全局限制 | 浏览器登出、切换用户时关闭旧流、清空私有缓存。Gateway 返回私有 JSON/SSE/下载结果时 `Cache-Control: no-store`,禁止共享代理缓存个人内容。诊断接口不返回密钥、完整 endpoint、连接字符串、模型提示词或私有正文。 ### 7.3 幂等、版本与确认 业务幂等由拥有事务的模块实现,Gateway 负责 header 规则与向下传递。强制幂等的创建/命令操作在接口目录标记,键为客户端随机值(8–128 字符),不是租户或用户凭据。 唯一作用域:`tenant + user + workspace(无事项时用personal)+ operation_id + key`。领域模块将标准化请求哈希、幂等记录、业务写入与首事件放在同一事务。相同键相同请求返回原资源和状态;相同键不同正文返回 409 IDEMPOTENCY_CONFLICT。并发同键由数据库唯一约束串行化;处理未完成时返回 409 OPERATION_IN_PROGRESS 与 Retry-After,不能重复启动。 建议幂等记录保留 24 小时,长任务未结束不清理。超过保留期旧键不能保证仍去重,客户端先按 run_id 查询。Gateway 不自动重发 POST/PATCH/上传/确认等有副作用请求,超时可能意味着领域事务已经提交,客户端使用相同幂等键查询/重试。 草稿 PATCH 必填 `expected_version`。Runtime approval 必填 `artifact_id + expected_version + content_hash`;获取 Workspace 的当前不可变版本并记录批准。local 模式可通过明确的应用服务事务协调实现检查与批准;remote 模式使用 Workspace 签发、绑定版本/hash/用户/事项的短期批准引用,再由 Runtime 消费。不得用“先 GET 版本,再无条件批准”的跨服务竞态替代原子版本检查。 Tool 执行读取被批准的不可变版本,校验批准引用、当前版本策略及工具幂等键;用户修改草稿后旧批准不能用于新版本。下载与人工确认是不同操作,下载不会隐式发文或产生企业微信通知。 ## 8. SSE、超时与故障语义 ### 8.1 事件流 `GET /api/v1/runs/{run_id}/events` 是当前 run 的持久事件出口,owner/tenant 与 Runtime 授权独立校验。沿用仓库 EventEnvelope:event_id、event_type、event_version、tenant_id、owner_user_id、workspace_id、run_id、step_id(可选)、sequence、trace_id、occurred_at、payload。 SSE 的 `id` 使用 `:`;`event` 使用 event_type;`data` 是一个完整 Envelope 的 JSON。sequence 在 Runtime 事务内按 run 分配。HTTP header `Last-Event-ID` 优先于 query `after_sequence`;run 不一致、负数或大于当前最新序号返回 400 INVALID_CURSOR。新连接无游标从保留的第一条开始;超过保留范围的游标返回 410 EVENTS_EXPIRED 与安全的 `snapshot_url`,前端先 GET run,再从 snapshot.last_sequence 继续。 前端使用带 Authorization header 的 fetch 流读取器,并手动实现 SSE 行、空行、UTF-8 分片和重连;浏览器原生 EventSource 构造器不提供通用自定义 Authorization header 参数。不能把 token 放 URL 来绕开限制。[SSE 标准](https://html.spec.whatwg.org/multipage/server-sent-events.html) 设计值:15 秒心跳注释 `: heartbeat`;每条连接最长 10 分钟且不得超出 token 剩余寿命;每次发送和每次心跳重新检查时间有效性,撤销和资源权限按不超过 15 秒的周期重查。断连后以 1/2/4/8/15 秒封顶并带抖动重连,前端按 run+sequence 去重。授权撤销或 token 到期后关闭连接,不发新的私有 payload。 每连接最多缓冲 128 条或 256 KiB。慢客户端超限关闭并记录原因,让其按游标恢复;不能丢事件后声称送达。数据库按 run 和 sequence 短查询、释放连接后等待,绝不让一个 SSE 占用一条长事务或独占连接。PC 每次最多读 100 条、无新事件时约 1 秒轮询;后续消息总线仅做唤醒,持久事件仍是回放依据。 持久步骤事件建议保留 7 天且所有未结束 run 事件不提前清除;模型逐 token 数据可合并为受控片段,密钥、系统提示词和无关用户上下文不进入事件。已经发出 200 后的异常只能发送允许的 error event 并关闭,不能再更改 HTTP 状态码。客户端断线不取消后端 run,取消必须走显式命令。 ### 8.2 时限和降级 | 路径 | 默认时限(设计值) | 失败策略 | |---|---|---| | local CRUD | 整体 10 秒;数据库事务目标 ≤3 秒 | 超时返回 504,不撤销已提交事务;按幂等或资源查询确认 | | remote adapter 普通请求 | connect 2 秒、pool 1 秒、write 5 秒、read 8 秒;整体不超过 10 秒 | HTTPX 的分项超时不能替代 overall deadline;取消后释放连接 | | 上传 | 整体 60 秒、连续无数据 15 秒 | 清理临时文件,领域操作可记录失败状态;不自动重传 | | 入库/起草/导出 | 202 接收,不等待任务结束 | 返回 resource ID + Location;状态与 SSE 查询 | | SSE | 心跳 15 秒;反代空闲读取超时 75 秒 | 流不使用普通请求 10 秒 deadline;重连可恢复 | | 下游只读 GET | 总预算内可重试最多 1 次,仅连接失败/明确可重试 502、503 | 不重试 401/403/404/429;不重试已开始的 SSE | | remote 断路器 | 连续 5 次可归因下游故障后打开 30 秒,再单探测半开 | 按模块隔离;4xx 不计入;业务 start 不排队在 Gateway 内存 | LLM 模型超时、重试及计费记录属于 LLM Gateway/Runtime。模型失败返回明确节点失败和 real/fixture 标志,Gateway 不生成“替代成功文稿”。通知失败不把已经保存的公文改为失败;状态分别显示。 ### 8.3 统一错误目录 | HTTP | code 例子 | 客户端动作 | |---|---|---| | 400 | INVALID_CURSOR / INVALID_REQUEST_HEADER | 修正输入;不盲重试 | | 401 | TOKEN_EXPIRED / TOKEN_INVALID | 清会话或重新登录;业务错误体不得含 token | | 403 | SCOPE_DENIED / CAPABILITY_DISABLED | 提示无权限或能力关闭 | | 404 | RESOURCE_NOT_FOUND | 资源不存在或无权访问,统一提示 | | 409 | VERSION_CONFLICT / ACTIVE_RUN_EXISTS / IDEMPOTENCY_CONFLICT | 重新读取状态,或使用原请求/不同键 | | 410 | EVENTS_EXPIRED | 获取状态快照后恢复订阅 | | 413 / 415 / 422 | PAYLOAD_TOO_LARGE / UNSUPPORTED_MEDIA_TYPE / VALIDATION_ERROR | 明确展示大小、格式或字段要求 | | 429 | RATE_LIMITED | 遵循 Retry-After | | 500 | INTERNAL_ERROR | 提供 trace_id,正文和秘密不出现在返回中 | | 502 / 503 / 504 | UPSTREAM_BAD_RESPONSE / DEPENDENCY_UNAVAILABLE / UPSTREAM_TIMEOUT | 读请求有限重试;写请求按幂等规则确认结果 | ## 9. 接口清单与暴露范围 以下状态码为成功状态。所有 PC 接口详见同目录 openapi.json,字段、鉴权、幂等 header 和错误响应可供 SDK/模拟服务生成。后续接口不在 PC OpenAPI 中注册;未完成时 capability=false,不以空壳 200 伪装就绪。 | 编号 | 方法与路径 | 功能 | 下层归属 | 阶段 | 幂等键 | |---|---|---|---|---|---| | API-01 | `POST /api/v1/auth/login` | 演示账号登录 | Identity | PC | — | | API-02 | `POST /api/v1/auth/logout` | 撤销当前会话 | Identity | PC | — | | API-03 | `GET /api/v1/me` | 读取本人身份与权限 | Identity | PC | — | | API-04 | `GET /api/v1/capabilities` | 获取当前用户可见能力 | Agent | PC | — | | API-05 | `GET /api/v1/workspaces` | 列出本人的事项 | Workspace | PC | — | | API-06 | `POST /api/v1/workspaces` | 建立个人事项 | Workspace | PC | 必需 | | API-07 | `GET /api/v1/workspaces/{workspace_id}` | 进入事项 | Workspace | PC | — | | API-08 | `PATCH /api/v1/workspaces/{workspace_id}` | 按版本重命名事项 | Workspace | PC | — | | API-09 | `GET /api/v1/workspaces/{workspace_id}/messages` | 读取对话历史 | Workspace | PC | — | | API-10 | `POST /api/v1/workspaces/{workspace_id}/messages` | 追加用户消息 | Workspace | PC | 必需 | | API-11 | `GET /api/v1/workspaces/{workspace_id}/attachments` | 列出事项附件 | Workspace | PC | — | | API-12 | `POST /api/v1/workspaces/{workspace_id}/attachments` | 上传一个附件并安排解析 | Workspace | PC | 必需 | | API-13 | `GET /api/v1/attachments/{attachment_id}/content` | 授权下载附件 | Workspace | PC | — | | API-14 | `GET /api/v1/workspaces/{workspace_id}/context` | 读取授权事实与来源摘要 | Context | PC | — | | API-15 | `GET /api/v1/knowledge-bases` | 列出授权知识库 | Knowledge | PC | — | | API-16 | `POST /api/v1/knowledge/search` | 授权范围内检索 | Knowledge | PC | — | | API-17 | `GET /api/v1/citations/{citation_id}` | 查看授权原文定位片段 | Knowledge | PC | — | | API-18 | `GET /api/v1/employees` | 数字员工目录 | Agent | PC | — | | API-19 | `GET /api/v1/skills` | 个人及共享技能目录 | Agent | PC | — | | API-20 | `POST /api/v1/skills` | 保存个人 Skill | Agent | PC | 必需 | | API-21 | `PUT /api/v1/skills/{skill_id}` | 按版本更新个人 Skill | Agent | PC | — | | API-22 | `PUT /api/v1/workspaces/{workspace_id}/skills` | 按版本更新事项技能选项 | Workspace | PC | — | | API-23 | `POST /api/v1/workspaces/{workspace_id}/runs` | 调用数字员工并注入技能 | Agent | PC | 必需 | | API-24 | `GET /api/v1/runs/{run_id}` | 任务快照与游标 | Agent | PC | — | | API-25 | `GET /api/v1/runs/{run_id}/events` | 授权进度流与续读 | Agent | PC | — | | API-26 | `POST /api/v1/runs/{run_id}/cancel` | 请求在安全边界取消 | Agent | PC | 必需 | | API-27 | `POST /api/v1/runs/{run_id}/approval` | 批准指定草稿版本并续跑 | Agent | PC | 必需 | | API-28 | `GET /api/v1/artifacts/{artifact_id}` | 读取本人草稿当前版本 | Workspace | PC | — | | API-29 | `PATCH /api/v1/artifacts/{artifact_id}` | 乐观锁修改草稿 | Workspace | PC | — | | API-30 | `GET /api/v1/artifacts/{artifact_id}/versions/{version}/content` | 下载已生成的版本文件 | Workspace | PC | — | | API-31 | `GET /api/v1/tools` | 查看允许的工具能力 | Tool | PC | — | | API-32 | `GET /api/v1/tool-receipts/{receipt_id}` | 读取本人工具回执 | Tool | PC | — | | API-33 | `GET /api/v1/notifications` | 本人通知与投递结果 | Notification | PC | — | | API-34 | `POST /api/v1/notifications/{notification_id}/read` | 标记本人通知已读 | Notification | PC | — | | API-35 | `GET /health/live` | 进程存活 | Gateway | PC | — | | API-36 | `GET /health/ready` | 诊断模块就绪与运行模式 | Gateway | PC | — | | API-37 | `POST /api/v1/runs/{run_id}/pause` | 请求暂停;需 Runtime 扩展 pausing/paused 状态 | Agent | P1/P2 | 必需 | | API-38 | `POST /api/v1/runs/{run_id}/resume` | 恢复已暂停任务 | Agent | P1/P2 | 必需 | | API-39 | `GET /admin/v1/modules` | 管理员模块状态 | Gateway | P1/P2 | — | | API-40 | `POST /admin/v1/knowledge-bases/{base_id}/ingestions` | 知识管理者发起材料入库 | Knowledge | P1/P2 | 必需 | | API-41 | `POST /device/v1/jobs/claim` | 设备身份领取本人设备任务 | Tool | P1/P2 | 必需 | | API-42 | `POST /device/v1/jobs/{job_id}/receipts` | 设备回传幂等执行回执 | Tool | P1/P2 | 必需 | | API-43 | `GET /metrics` | 受保护的内网指标 | Gateway | P1/P2 | — | | API-44 | POST /api/v1/workspaces/{workspace_id}/chat | 不选数字员工时直接模型对话,并将用户/助手消息保存到 Workspace;当前模型为演示桩 | LLM + Workspace | PC | Idempotency-Key | PC 的知识库样例可通过受控 seed/管理脚本入库;管理端入库 API 单列后续阶段,避免为展示五库提前建设整个管理台。原型中的通用暂停/继续按钮只有在 Runtime 实现相应状态后才启用;PC 基线的人工确认等待已经通过 awaiting_confirmation + approval 覆盖,不混用为任意中途暂停。 ## 10. 状态、日志、容量与运行管理 ### 10.1 数据所有权 Gateway 本身保持无业务状态:只保存本进程配置快照、短期公钥缓存、连接池、限流计数与 SSE 连接额度。用户/会话属于 Identity;事项、附件、草稿属于 Workspace;run、步骤、事件和 Skill 快照属于 Runtime;通知/outbox 属于 Notification。Gateway 不创建一份平行的 run 状态表,也不以内存 BackgroundTasks 替代持久 worker。 记录请求:trace_id、operation_id、身份作用域(适度脱敏)、resource_id、config_revision、status_code、duration、bytes、error_code。流式请求记录开始/结束时间、最后送出序号、断开原因。指标标签只用路由模板、模块和状态类,避免按 user_id/run_id 产生高基数指标。 审计由领域事务记录批准、取消、技能版本更新和工具请求等业务动作,Gateway 接入日志只证明“收到/返回请求”,不能代替“保存或发文已经成功”的审计证据。运行日志不记录 password、Authorization、模型密钥、完整请求体、文稿正文或文件内容。 ### 10.2 健康与容量 `/health/live` 只证明进程响应。受保护的 `/health/ready` 返回 module 状态和 real/fixture 模式:配置不合法、身份验证器或必需数据库不可用 → 503;知识/模型/企业微信等非所有路由都必需的依赖不可用 → 明确 degraded 并禁用依赖该模块的能力,基本事项 CRUD 可继续。不能因企业微信短暂失败让用户失去查看文稿的入口。 待验证的 PC 容量目标:单 API 进程、两位演示用户、20 条 SSE、两个 worker 执行槽位。以固定 4 核/8 GiB 测试环境为参考,使用受控空业务 adapter 测量 Gateway 额外延迟 P95≤50 ms;用真实数据库测 run 接收 P95≤500 ms;持久事件提交到本机浏览器可见 P95≤2 s。需记录样本量、请求组合、机器与依赖版本,这些数值是验收目标,不是已测性能或生产 SLA。 扩到多 API 进程前,必须把需要全局限制的计数移到共享 RateLimitPort(如客户允许的 Redis 适配器或边缘统一限流);重跑流控与隔离验证。SSE 不要求粘性会话,因为事件由 Runtime 持久化。部署停机排空 30 秒,之后关闭旧连接并让客户端续读,不杀掉另一个进程中的任务。 ## 11. 麒麟与海光迁移设计 ### 11.1 适配基线与证据 拟适配基线为 **银河麒麟高级服务器操作系统 V10 SP3 系列的 x86_64 版本 + 海光 CPU 服务器**。麒麟官方 SP3 2403 发布说明列出 x86_64 发行介质和多个海光处理器系列,说明这一组合有厂商产品支持依据;并不证明本项目所选 Python 包、容器运行时或所有海光 SKU 已适配。[麒麟官方发布说明](https://kylinos.cn/upload/product/20241209/797030052b05a1031992e849b5c08246.pdf) 交付前冻结:服务器型号、海光 CPU 型号/步进、BIOS、OS 完整版本与补丁、kernel、glibc、OpenSSL、Python 补丁号、OCI 运行时、依赖锁和镜像 digest。当前尚未获得客户目标机参数,因此兼容矩阵状态为“待目标机验证”。海光 CPU 与用于模型推理的加速卡是不同资源,本 Gateway 不需要 GPU/DCU。 | 层次 | 可迁移设计 | 必须验证的点 | 不通过时处理 | |---|---|---|---| | 指令集 | 海光 CPU 基线使用 linux/amd64、x86_64 构建物 | 目标 CPU 指令集与 wheel/编译器基线;无 illegal instruction | 在基准构建机重编译;禁用 `-march=native` 等宿主机专属优化 | | OS/ABI | Linux 服务进程,独立虚拟环境 | glibc/GLIBCXX/OpenSSL 版本与动态依赖 | 构建匹配 ABI 的 wheel;不修改系统库强行满足应用 | | Python | 独立安装于 `/opt/workos/runtime`,virtualenv | ssl、证书链、时区、线程和文件编码 | 用受维护发行包或在目标环境构建,不覆盖 `/usr/bin/python` | | 原生 Python 包 | 明确列出 pydantic-core、cryptography、数据库驱动及传递原生依赖 | wheel tag、so 动态链接、导入、签名验签、数据库连接 | 内网构建 wheelhouse;Rust/C 编译在构建区完成,运行机不临时联网编译 | | ASGI | asyncio+h11 | 并发、SSE、SIGTERM、文件描述符 | 调整 systemd 限额;高性能扩展作为后续单独选项 | | PostgreSQL | RepositoryPort、SQLAlchemy、受控迁移 | 锁、唯一约束、JSON、事务与 SKIP LOCKED 等实际使用语义 | 国产数据库逐项适配,不能只改连接字符串便宣布兼容 | | 部署 | systemd 优先保证可落地;OCI 为可选分发 | 客户发行版和运行时支持、cgroup、文件卷与网络策略 | 容器不满足时使用原生 virtualenv+systemd,同业务代码运行 | | 存储 | storage_key 与配置路径分离,pathlib | Linux 大小写、UTF-8 文件名、权限、磁盘配额 | 用 manifest/hash 迁移数据;不把 Windows 盘符写入数据库 | | 浏览器/密码 | Portal 静态资源与 OpenAPI UI 全部内网托管 | CA 信任链、HTTPS、企业浏览器 SSE、国密链路 | 适配客户密码设备与协议;应用层证书校验不可跳过 | Psycopg 的纯 Python 包仍需要系统 libpq;缺少可用二进制 wheel 时可以选择适配的本地构建或纯 Python 包加系统库,而不是声称“纯 Python 不需要任何本地依赖”。[官方安装说明](https://www.psycopg.org/psycopg3/docs/basic/install.html) ### 11.2 离线部署与运维 建议交付结构:`app.whl / requirements.lock / wheelhouse / sbom / config / migrations / static / hashes / systemd`。wheelhouse 按 Windows-amd64 与 Kylin-linux-x86_64 分别产出;不将 Windows venv 拷贝到麒麟。用内部镜像源或离线校验通过的包安装,包名、版本、hash 与构建环境一起记录。 示意命令(工程代码与精确锁生成后使用,当前仓库只有设计和前端原型): ```bash /opt/workos/runtime/bin/python -m venv /opt/workos/venv /opt/workos/venv/bin/python -m pip install --no-index \ --find-links=/opt/workos/release/wheelhouse --require-hashes \ -r /opt/workos/release/requirements.lock /opt/workos/venv/bin/python -m uvicorn app.main:create_app --factory \ --host 127.0.0.1 --port 8000 --workers 1 --loop asyncio --http h11 ``` systemd 使用专用无特权账号,代码目录只读,工作目录和日志目录显式授权,`Restart=on-failure`,`TimeoutStopSec=30`,LimitNOFILE 与连接规模对应。代理与 API 同机时监听回环;容器部署中 API 可监听容器内 `0.0.0.0`,但只在内部网络暴露,由边缘代理提供 HTTPS。数据库、runner、内部 Port API 不做公网端口映射。 Nginx 对 SSE 设置 `proxy_buffering off`、`proxy_cache off`、`gzip off`,上游 HTTP/1.1,read timeout 75 秒;应用发 `text/event-stream`、`Cache-Control: no-store`、`X-Accel-Buffering: no`。普通路由与 SSE 路由分别配置超时。仅对附件上传路径允许 multipart 上限;其他 JSON 请求仍由 ASGI 限制 256 KiB。示例片段见 nginx.conf.example,需要实际域名、证书和网络配置后才能上线。[Nginx 代理缓冲文档](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering) ### 11.3 国产化范围与国密边界 “可在麒麟和海光上部署”“使用国产数据库/中间件”“通过特定信创或商用密码测评”是三项不同交付。本文承诺设计可替换并给出验证路径,不宣称所有开源组件都是国产组件或已经获得认证。 如果客户要求 SM2/SM3/SM4、TLCP 或特定国密 TLS,采用客户认可且与浏览器及上游服务兼容的密码网关/加密设备进行边界适配,记录终止点、内部链路保护、密钥所有者和审计;Python 默认 ssl、普通 Nginx 和普通 JWT 库不自动提供这些合规能力。不能通过关闭验签或证书校验换取“能连通”。JWT 身份令牌方案与国密传输协议分别评估。 隔离内网迁移时,当前公网 Qwen 和公网 Identity 的出站依赖需要真实网络出口策略或替代内网实现;HTTP adapter 可替换不等于网络天然可达。目标环境完全无外网时,模型接口需换成客户允许的内网端点,Gateway 对 Portal 的契约保持不变。企业微信也要按实际网络条件验证,不能默认内网可达。 ## 12. 主要需求清单与验收判据 P0=PC 必需;P1=云端/扩展;P2=麒麟海光交付。归属仍落到 API01/API02/API03;身份和业务事务通过原 ID/WS/AR 任务协作,不新增第八个业务模块。 | 需求ID | 归属 | 需求 | 优先级 | 完成判据 | |---|---|---|---|---| | GW-01 | API01 | 统一版本路径与 Router | P0 | 37 项 PC 操作与 OpenAPI 路径/method/operationId 一致;不开放通用代理 | | GW-02 | API01 | 可信主体注入 | P0 | body/query/伪造头的 user_id/tenant_id 不改变主体 | | GW-03 | API01+ID | 令牌生命周期 | P0 | 过期、错误签名、错误 aud/iss 拒绝;登出撤销生效 | | GW-04 | API01+WS | 全资源归属隔离 | P0 | B 读写 A 的事项、附件、文稿、引用、回执、通知和 run 返回 404 | | GW-05 | API01 | 统一错误与 trace | P0 | 校验、未捕获异常和下游故障都符合错误模型且不泄密 | | GW-06 | API01 | 显式模块装配 | P0 | 缺依赖、重复 route、未知 provider 启动失败;local adapter 可替换 | | GW-07 | API01+AR | 员工、Skill 与能力目录 | P0 | 关闭能力后不能新启动;注入版本快照由 Runtime 返回 | | GW-08 | API01+AR | 幂等命令 | P0 | 并发同键同输入只建一个 run;同键不同输入 409 | | GW-09 | API01+WS/AR | 版本批准门 | P0 | 修改草稿后旧 hash/version 不能续跑工具保存 | | GW-10 | API02 | 请求体与文件限制 | P0 | 超 10 MiB、无 Content-Length 的超限流、非法 multipart 均被拦截 | | GW-11 | API02+WS | 下载边界 | P0 | 文件名与 key 无目录穿越,重复编码也不能越界 | | GW-12 | API02 | DTO 与媒体类型 | P0 | 禁止写入 DTO 多余身份字段;错误媒体类型得到明确状态 | | GW-13 | API01 | 单进程限流 | P0 | 超额 429 与 Retry-After;SSE 配额单独计数 | | GW-14 | API03 | 持久事件续读 | P0 | 从最后序号重连无缺失,重复由客户端去重,过期游标410 | | GW-15 | API03 | 流式持续鉴权 | P0 | B 订阅 A 失败;token 到期不再发数据;撤销≤15秒关流 | | GW-16 | API03 | 背压和资源释放 | P0 | 慢客户端限内存;断线连接计数/DB池恢复;不持有长事务 | | GW-17 | API03 | 任务与连接解耦 | P0 | 关闭浏览器后 worker 继续;取消需要命令,刷新只恢复订阅 | | GW-18 | API01 | 健康与运行模式 | P0 | live/ready 含义分离;fixture 显式;通知失败不阻断阅读草稿 | | GW-19 | API01 | 安全审计 | P0 | 日志无 token/密码/文稿正文;批准成功能追到领域事务记录 | | GW-20 | API01 | 远程 adapter | P1 | 更换 endpoint 不改 Portal;mTLS/委托令牌与资源校验通过 | | GW-21 | API01 | 配置发布与回滚 | P1 | 新配置校验失败不切流;运行任务与路由版本明确 | | GW-22 | API03 | HTTPS 反代流式行为 | P1 | 浏览器实时收到事件,代理无缓冲,断流可恢复 | | GW-23 | API01/02 | 管理与设备身份隔离 | P1 | 普通用户不能调用 admin/device,设备仅能领本机任务 | | GW-24 | API01 | 集群限流与就绪摘流 | P1 | 两实例总额限制符合配置;不是每实例重复放额 | | GW-25 | API01/02/03 | 麒麟海光运行 | P2 | 目标机离线安装、签名验签、DB事务、上传下载、SSE全链路通过 | | GW-26 | API01 | 国产数据库与密码边界 | P2/按需 | 选定产品、版本、适配证据与未覆盖项;不以配置替换冒充完成 | | GW-27 | API01 | 离线可复现交付 | P2 | 包、锁、hash、SBOM、镜像或systemd配置齐备;无运行期CDN | ## 13. 开发目录、任务拆分与合入条件 建议未来工程目录(当前交付的是设计文件,不创建空类冒充实例化): ```text backend/app/ main.py # create_app / lifespan / 依赖装配 gateway/ routers/ # auth/workspaces/runs/knowledge/catalog/artifacts/notifications middleware/ # trace、错误兜底、大小计数、审计 security/ # require_user / scopes / 可信代理 streaming/ # SSE编码、游标、连接额度、心跳、断连释放 registry.py # ModuleProvider 与静态允许表 settings.py # Pydantic配置与config_revision errors.py # 领域异常到HTTP错误映射 contracts/ # DTO、Principal、Ports;跨模块可共享 adapters/local/ # 进程内领域服务封装 adapters/http/ # 后续远程实现,固定服务身份及endpoint modules/ # 七业务模块,各自管理Repository与事务 identity/ # 演示 / OIDC Provider worker/ # 持久任务执行,不放在Gateway进程 ``` | 任务 | 主要交付 | 前置 | 关联旧任务 | 可独立验收的完成性 | |---|---|---|---|---| | GW-D01 | DTO、路径、错误与Principal冻结 | F03、本文评审 | G02 | OpenAPI可解析,DTO和示例一致 | | GW-D02 | create_app、Provider registry、配置验证 | GW-D01、F04 | G01/G02 | local providers可装配,缺依赖明确失败 | | GW-D03 | 演示身份、范围依赖与可信头处理 | GW-D02、I02/I03 | G01 | 伪造、过期、跨用户负向用例通过 | | GW-D04 | WS/目录/知识等 Router 与限流 | GW-D03、各业务Port可用 | G02、W03/P03 | 调领域服务且保持单一数据所有权 | | GW-D05 | 文件流量边界、上传下载 | GW-D04、W05/W06 | G03 | 10MiB、无长度流、非法路径、错误格式验证 | | GW-D06 | run/approval/cancel与幂等契约 | GW-D04、A02/A10 | G02、A01/AR04 | 同键只创建一次;过期批准被拒绝 | | GW-D07 | SSE、心跳、续读、背压与撤销 | GW-D06、F08持久事件 | G04 | 双用户隔离、重连、慢客户端、浏览器退出通过 | | GW-D08 | 健康、审计、PC薄链路 | GW-D05/GW-D07 | Q01/Q03 | 真实API→任务→事件→受控fixture工具回执,模式明确 | | GW-D09 | 服务器TLS、远程adapter、设备域 | PC验收、实际网络与证书 | D04/D07–D10 | 云端流式代理、设备身份和服务身份通过 | | GW-D10 | 国产平台离线交付与兼容验证 | 锁定目标OS/CPU/中间件 | 新增国产化工作包 | 兼容矩阵、构建记录、故障与回滚证据完整 | 原 G01–G04 的短工时是早期薄实现估算。本文件补充了持续鉴权、背压、远程身份和国产化工程,不能把新增范围自动塞入原 1.25 小时预算;排期时先按 P0 范围重新估算,P1/P2 单列。首两天优先 GW-D01/D02/D03 加最小 startRun/getRun/events 薄链路,之后补上传与版本确认,不先开发管理界面。 编码任务提示应包含:唯一主归属、输入 Port/DTO、允许修改的文件、不可绕过的权限/事务约束、成功与失败样例、验收证据。Vibe Coding 每次完成一个可检查任务;不一次让模型生成整套网关并跳过集成。 ## 14. 验证、迁移与发布清单 | 检验层 | 必做场景 | 证据 | |---|---|---| | 静态契约 | 全部PC操作唯一,路径参数齐备,schema引用可解析,示例符合字段 | 契约检查记录;本文附件已做静态一致性检查 | | 应用鉴权 | 双用户交叉访问、伪造租户头、过期及撤销令牌 | HTTP断言与脱敏trace;待开发后执行 | | 业务一致性 | 并发同键、同键不同输入、审批过程中改稿、工具超时查询receipt | 数据库事务记录和重复请求结果 | | 流式连接 | UTF-8分片、断网续读、游标过期、慢客户端、token过期、Nginx缓冲 | 事件序号、浏览器录屏、连接与内存指标 | | 依赖故障 | Identity/JWKS不可用、DB故障、模型超时、企业微信失败、PC离线 | 正确错误/降级,不能出现未执行却成功 | | 国产平台 | 离线安装、原生扩展导入、中文文件名、TLS、重启、备份恢复、负载 | 具体OS/CPU矩阵、包hash、实际结果与遗留问题 | 发布前核对 schema migration、应用 commit、OpenAPI版本、workflow版本、配置revision、依赖锁及证书引用。先备份数据库和文件manifest,灰度部署、ready验证、切流、排空旧连接。应用回滚使用前一版本包与配置;不可逆数据库迁移必须走专门恢复方案,不能只切镜像便宣布回滚成功。 ## 15. 办文工作流:从调用数字员工到确认归档 以“根据来文和制度库,起草一份培训通知”为例。所有示例材料均为合成演示材料;正式对外发文和 OA 审批不在此次 PC 自动执行范围内。 ### 15.1 用户看到的过程 用户进入个人 Workspace,创建“培训通知”事项,上传来文,在对话框下方点击“数字员工 → 公文写作”。界面显示已自动注入的 Skill、五步进度、引用依据和可编辑草稿。用户核对并确认具体版本后,系统生成 DOCX、保存到允许的目录,并通过企业微信应用消息提示完成。用户关闭页面再打开时可以从持久任务记录恢复进度。 建议公文员工的默认 Skill:`document-understand`(来文要素提取)、`knowledge-cite`(检索与引用)、`document-draft`(文种与结构)、`document-review`(事实/格式检查)。这些是应用内声明式 Skill 内容,不是允许网关执行任意 Python、Shell 或动态导入插件的入口。 ### 15.2 调用时序 ```mermaid sequenceDiagram actor U as 用户 / Portal participant G as API Gateway participant I as Identity Provider participant W as Workspace participant R as Agent Runtime / Worker participant C as Context participant K as Knowledge participant L as LLM Gateway participant T as Tool Gateway participant N as Notification U->>G: 登录,创建事项,保存消息/附件 G->>I: 验证身份并生成可信 Principal G->>W: 在用户资源域中创建并保存 W-->>U: 经 Gateway 返回资源 ID U->>G: POST /workspaces/{id}/runs + 幂等键 G->>R: startRun(principal, workspace, employee, input) R->>W: 校验事项、消息及附件访问权 R->>R: 固化员工 / workflow / Skill 版本,事务保存任务 R-->>G: queued + run_id + effective_skills G-->>U: 202 Accepted + Location U->>G: GET /runs/{id}/events (Bearer,游标) G->>R: 授权读取已提交的持久事件 R->>C: 获取事项事实与上下文快照 C->>K: 按用户与知识库权限检索 K-->>C: 来源版本、引用片段、定位信息 C-->>R: 受控上下文与引用 R->>L: 按冻结 Skill 和上下文起草 L-->>R: 文本 / 模型调用结果 R->>W: 保存未确认草稿与引用 R->>R: 提交 awaiting_confirmation 事件 G-->>U: SSE:步骤进度 / 草稿 ID / 等待人工确认 U->>G: GET 或 PATCH /artifacts/{id} G->>W: 乐观锁更新草稿,生成新版本与 hash U->>G: POST /runs/{id}/approval (版本 + hash) G->>R: 审核提交者身份、确认范围和幂等键 R->>W: 原子绑定当前草稿版本与确认记录 R-->>G: 接受确认并恢复持久任务 G-->>U: 202 Accepted R->>T: 受控生成 DOCX / 保存指定产物版本 T-->>R: 工具回执;失败或不确定须显式返回 R->>N: 通过事务 outbox 触发通知 N->>N: 企业微信应用消息 / 可追踪投递结果 G-->>U: SSE:任务结果与回执;通知投递状态另行查询 ``` 图中的返回箭头是逻辑返回;浏览器响应均通过 Gateway。Worker 持续提交事件,Gateway 从事件 Port 续读,图中未逐条画出。Gateway 本身不循环调用知识库、模型或工具来完成写作。 ### 15.3 每一步的职责及失败处理 | 阶段 | Gateway 做什么 | 业务模块做什么 | 检查点 / 失败表现 | |---|---|---|---| | 1. 建事项、上传、发消息 | 鉴权、大小与 DTO 校验、资源域传递 | Workspace 保存父子事项关系、附件与消息 | 其他用户的 workspace/message/attachment ID 统一按不可见资源处理;附件解析失败必须可见 | | 2. 选择数字员工 | 提供员工/Skill 目录;受控 startRun 入口 | Runtime 根据员工配置合并默认 Skill、事项已绑定 Skill、请求额外 Skill;按 ID 去重,校验可用性与权限,冻结版本 | 请求中未传 `skill_ids` 也会加载员工默认技能;数组不等于允许删除必需技能;未授权 Skill 拒绝,不能静默忽略 | | 3. 理解来文、检索依据 | 只处理进度查询和事件出口 | Runtime 编排 Context/Knowledge;检索限定租户、可见知识库及文档版本 | 无依据时提示缺失,不编造条文;检索或解析失败可明确阻断 | | 4. 起草与校核 | 输出持久步骤事件和产物查询地址 | Runtime 调 LLM Gateway;Workspace 存草稿和引用;进入 awaiting_confirmation | 模型故障返回真实任务失败或可恢复状态;fixture 必须在 run.mode 中标注 | | 5. 人工修改并确认 | 输入校验、身份范围、统一冲突错误 | Workspace 乐观锁更新;Runtime 与 Workspace 原子冻结确认的版本和 hash | 修改后的 v2 不接受对 v1 的批准;返回 409,用户必须看见新版本后重新确认 | | 6. 执行、归档、通知 | 查询回执、结果下载与通知状态 | Tool Gateway 只执行已确认的工具动作;Notification 独立管理企业微信投递 | 工具超时先查询 receipt,不能重复执行未知结果;微信失败不会把已保存公文说成保存失败 | Skill 的内容由服务端加载;浏览器不得在 startRun 中覆盖系统提示词、工具允许表、目标模型地址或用户身份。个人 Skill 更新产生新版本,不修改已开始任务的快照。默认技能增加/替换由员工配置和版本决定,下一次 run 才生效。Skill 内容即使包含“忽略权限”等指令,也没有修改后端授权策略的能力。 PC 的“人工确认”只授权**生成并保存当前公文版本**以及发送配置范围内的完成通知;不代表有权正式发文、签章或替他人审批。批准之后若继续编辑,必须生成新的未确认版本,旧任务仍只处理原确认版本。工具动作类型、目标目录、收件人范围由服务端工作流配置限制,客户端不可任意指定。 运行完成和通知成功是两个状态:公文已可靠保存即可使办文任务成功;Notification 记录 pending/sent/failed/unknown。企业微信拒绝或超时可独立重试/核对,不能在网络结果未知时声称已送达。PC runner 与 Gateway 同机;云端迁移后如仍需写用户 PC,则必须使用已绑定设备的出站连接器,云服务器路径不能冒充用户 PC 路径。 ## 16. 接口请求、响应和事件示例 以下 ID、用户名和正文都是示例,``、`<演示账号密码>` 是占位值。实际 ID 由上一步响应取得,不应硬编码。全部 JSON 请求使用 `Content-Type: application/json`;除登录、live 外都携带 `Authorization: Bearer `。响应示例省略通用 HTTP 头,仅列关键头。机器可验证的请求/响应样例见 [examples.json](examples.json)。 ### 16.1 登录与新建事项 ```http POST /api/v1/auth/login HTTP/1.1 Content-Type: application/json {"username":"demo-writer-a","password":"<演示账号密码>"} ``` ```json {"access_token":"","token_type":"Bearer","expires_in":900,"auth_mode":"demo"} ``` ```http POST /api/v1/workspaces HTTP/1.1 Authorization: Bearer Content-Type: application/json Idempotency-Key: ws-training-20261010-001 {"title":"培训通知起草"} ``` 返回 `201 Created`,`Location: /api/v1/workspaces/ws-001`: ```json {"workspace_id":"ws-001","parent_id":"personal-u-001","title":"培训通知起草","version":1,"status":"active"} ``` `parent_id` 为服务端按 Principal 确定的个人工作空间,客户端不能指定别人的个人空间。首次登录的个人空间创建采用唯一约束保证只创建一次。 ### 16.2 保存用户需求、调用数字员工并自动注入 Skill ```http POST /api/v1/workspaces/ws-001/messages HTTP/1.1 Authorization: Bearer Content-Type: application/json Idempotency-Key: msg-training-20261010-001 {"content":"请根据来文和培训制度,起草培训通知,缺少日期时标记待确认。"} ``` 获得 `201` 的 `message_id` 后启动任务。没有显式传入 Skill,员工默认 Skill 仍自动加载: ```http POST /api/v1/workspaces/ws-001/runs HTTP/1.1 Authorization: Bearer Content-Type: application/json Idempotency-Key: run-training-20261010-001 {"employee_id":"official-document-writer","input_message_id":"msg-001"} ``` 返回 `202 Accepted`,`Location: /api/v1/runs/run-001`。下方 hash 仅表示格式,运行时来自已存 Skill 的真实内容 hash;完整示例附件通过实际示例文本计算 hash: ```json { "run_id":"run-001","workspace_id":"ws-001","status":"queued", "last_sequence":0,"mode":"real","workflow_id":"official-document", "workflow_version":1, "effective_skills":[ {"skill_id":"document-understand","version":1,"content_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}, {"skill_id":"knowledge-cite","version":1,"content_hash":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"}, {"skill_id":"document-draft","version":1,"content_hash":"cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"}, {"skill_id":"document-review","version":1,"content_hash":"dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"} ],"artifact_id":null } ``` Runtime 需在一个接受事务里固化消息引用、附件快照、可见 Skill 版本、workflow 版本及幂等结果,然后才能返回 202。不得先返回“已排队”再依靠不可靠的内存队列接收任务。 ### 16.3 授权进度流与断线续读 ```http GET /api/v1/runs/run-001/events HTTP/1.1 Authorization: Bearer Accept: text/event-stream Last-Event-ID: run-001:4 ``` ```text HTTP/1.1 200 OK Content-Type: text/event-stream Cache-Control: no-store X-Accel-Buffering: no id: run-001:5 event: task.step.completed data: {"event_id":"evt-005","event_type":"task.step.completed","event_version":1,"tenant_id":"demo-tenant","owner_user_id":"u-001","workspace_id":"ws-001","run_id":"run-001","step_id":"retrieve","sequence":5,"trace_id":"trace-001","occurred_at":"2026-10-10T02:00:00Z","payload":{"step":"retrieve","progress":40,"citation_ids":["cite-001"]}} : heartbeat ``` 一帧以两个换行结束,`id` 对应数据中的 run_id/sequence。`task.step.completed` 是在通用 EventEnvelope 之上增加的事件类型,需在 Runtime 事件目录注册,不改变已有信封结构。浏览器用支持 Authorization 的 `fetch` 流式读取,正确处理 UTF-8 跨 chunk 解码与不完整帧;不要假设一个网络 chunk 就是一条事件。客户端按 `(run_id, sequence)` 去重,续读至少一次投递,不宣称网络端到端恰好一次。 ### 16.4 修改草稿和确认具体版本 ```http PATCH /api/v1/artifacts/art-001 HTTP/1.1 Authorization: Bearer Content-Type: application/json {"expected_version":1,"content":"关于开展办公技能培训的通知\n培训日期:待确认。"} ``` 服务端返回 `version: 2` 与新 `content_hash`。批准时携带**刚取得的** hash;以下 `<响应中的64位hash>` 为占位值,不是可直接通过校验的请求体: ```http POST /api/v1/runs/run-001/approval HTTP/1.1 Authorization: Bearer Content-Type: application/json Idempotency-Key: approve-training-v2-001 {"artifact_id":"art-001","expected_version":2,"content_hash":"<响应中的64位hash>"} ``` `202` 表示批准命令已可靠接受,工具执行结果随后由 SSE 和 receipt 提供。若草稿已改为 v3,返回 `409`: ```json {"code":"ARTIFACT_VERSION_CONFLICT","message":"草稿已更新,请查看最新版本后重新确认。","trace_id":"trace-002","details":{"expected_version":2,"current_version":3}} ``` 同一批准键重试返回原接受结果;以相同键提交不同版本/hash 返回 `IDEMPOTENCY_CONFLICT`。使用新的幂等键也不能绕过一次性批准状态和产物版本校验。取消入口同样返回 `202`,表示取消请求已持久保存;状态可能暂时仍为 running,直到 worker 在安全边界确认取消。 ### 16.5 Skill 保存和知识库检索 ```http POST /api/v1/skills HTTP/1.1 Authorization: Bearer Content-Type: application/json Idempotency-Key: skill-style-20261010-001 {"name":"公文日期核对","category":"document","content":"核对正文中的日期;缺少的信息标记待确认,不自行推测。"} ``` ```http POST /api/v1/knowledge/search HTTP/1.1 Authorization: Bearer Content-Type: application/json {"workspace_id":"ws-001","query":"培训通知的写作要求","base_ids":["kb-policy","kb-templates"],"top_k":5} ``` 知识结果返回 `citation_id/document_id/document_version/title/locator/snippet`。服务端再次检查指定知识库和命中文档权限,不能只验证 workspace 可见就返回全部知识库内容。个人 Skill 保存只是存储声明式指令;调用工具仍须通过 Tool Gateway 策略。 ## 17. 开发前需冻结的决定 | 决定 | 当前默认 | 冻结责任 / 时间 | 未确定时的影响 | |---|---|---|---| | Python及依赖精确版本 | Python 3.12 维护补丁线,框架按第4节 | GW-D02,生成锁文件并跑PC测试 | 本文不是可直接安装的版本锁;不能拿宽版本范围代替可重复交付 | | Qwen真实模型ID和地址 | 单一公网模型,ID待确认 | 原计划 L01,LLM模块接入前 | Gateway 可使用显式 fixture run 验证接口,但不能算真实模型链路验收 | | 目标身份系统 | PC 签名演示身份;后续 OIDC | Identity 负责人 / 服务器接入前 | OIDC issuer、audience、JWKS和退出策略均须实测 | | 公文确认动作 | 生成并保存当前版本,发完成通知 | Runtime / Tool设计时 | 正式发文、签章、OA回写需新增授权和审批契约 | | 麒麟与海光准确组合 | 银河麒麟服务器V10 SP3、x86_64为候选 | GW-D10 前与客户运维共同冻结 | 未在目标机通过前只能称兼容性设计,不能承诺完成适配或认证 | | 云端写PC文件 | 后续受控设备连接器 | 云阶段 GW-D09 | 未实现时仅下载产物,不将服务器路径伪装为PC保存成功 | 这一版交付的是架构设计、接口契约和配置示例。网页 Demo 的前端展示不等于这里描述的真实服务已完成;开发时以 GW-D01–D08 的证据逐项转为“已实现”。PC 范围优先完成公文闭环,云端、国产化平台、Admin 和通用工作流暂停/恢复分别验收。 ## 18. 设计依据与官方资料 以下为 2026-10-10 查阅的官方资料。框架职责、运行时选择和兼容性测试方案是本项目设计决定;厂商列出平台支持不等于本应用获得认证。 - 现有项目基线:[base1 系统设计](https://github.com/delltom2000/workosMvp/blob/321dca9774d8f3a34cb599478f4b60e64b8c723f/base1/docs/06_系统设计文档.md)、[架构契约](https://github.com/delltom2000/workosMvp/tree/321dca9774d8f3a34cb599478f4b60e64b8c723f/base1/docs/09_架构契约)。 - 路由组织与依赖:[FastAPI Larger Applications](https://fastapi.tiangolo.com/tutorial/bigger-applications/);本设计用 APIRouter 组织模块接口,业务替换通过应用自身的 Ports 和 adapters 实现。 - 事件循环和HTTP实现配置:[Uvicorn Settings](https://www.uvicorn.org/settings/);PC 优先明确配置 asyncio/h11,减少不必要的原生依赖,性能需实际验证。 - 原生扩展边界:[Pydantic Architecture](https://pydantic.dev/docs/validation/latest/internals/architecture/) 与 [Psycopg Installation](https://www.psycopg.org/psycopg3/docs/basic/install.html);分别涉及 Rust core 和 libpq/安装方式,不能因应用以 Python 编写就跳过 ABI 验证。 - 远程调用超时:[HTTPX Timeouts](https://www.python-httpx.org/advanced/timeouts/);总截止时间仍由应用额外控制,不能把单项 read timeout 当成端到端截止时间。 - 流式代理:[Nginx proxy_buffering](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering);事件格式与续读:[WHATWG Server-sent events](https://html.spec.whatwg.org/multipage/server-sent-events.html)。 - 国产OS平台依据:[银河麒麟高级服务器操作系统 V10 SP3 官方发布说明 PDF](https://kylinos.cn/upload/product/20241209/797030052b05a1031992e849b5c08246.pdf)。说明中列有海光相关平台;实际交付仍按第11节固定具体 CPU/OS/补丁/驱动并完成应用测试。 附件 [validation-report.json](validation-report.json) 记录本次静态检查范围;不包含运行时、压力、企业微信投递或真实麒麟/海光测试结果。 ### 附件验证方法 配套 [validate_contract.py](validate_contract.py) 和 [requirements-design.txt](requirements-design.txt) 用于设计契约检查,与未来 Gateway 运行依赖分开。使用 Python 3.12 的隔离环境安装 requirements-design.txt 后,在本目录执行 `python validate_contract.py`。若依赖已安装在独立目录,可传 `--dependency-dir <目录>`。检查脚本验证 OpenAPI 3.1、示例 DTO、配置依赖图、幂等/鉴权声明和链接,并重新生成 validation-report.json;不启动服务或发送企业微信消息。