dellweb3's picture
Work OS validated demo local-v0.8
99caad5 verified
|
Raw History Blame Contribute Delete
68.1 kB

Work OS MVP:API Gateway 系统架构与功能设计

2026-10-10 实现更新:Agent Runtime 已替换为 PC 持久化模块,新增管理员编排接口。本文保留总体设计契约;当前运行契约见 AgentRuntime/openapi.json,管理 API 和实施边界见 实现说明。

版本:1.0(设计基线) 日期:2026-10-10 状态:待开发;不是运行实现或国产化认证报告。

关联仓库:delltom2000/workosMvp。设计输入为用户本次提供的《Work OS 1.0 系统架构图(模块、消息流与控制流)》及仓库提交 321dca9774d8f3a34cb599478f4b60e64b8c723f 下的 base1。已读取远端系统设计,和本地基线一致。

配套交付:接口目录、PC 核心 OpenAPI 3.1 契约、模块装配示例、配置 Schema、Nginx SSE 配置片段、可校验的接口示例。主文档给出完整设计边界;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. 逻辑架构与请求链

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 与依赖注入可复用路由和身份依赖:官方组织方式。

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 参数选择:官方设置。Pydantic 的验证核心采用原生实现:官方架构说明。HTTPX 的连接、读写和池等待超时应分开设定:官方超时说明。这些能力是框架事实;下面的阈值和流程是本项目设计决定。

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 编码形态

# 设计示意;省略具体领域类型的 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 中间件不需要跟着改:

{
  "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 <token> 仅放请求头;禁止 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 使用 <run_id>:<sequence>;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 标准

设计值: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 已适配。麒麟官方发布说明

交付前冻结:服务器型号、海光 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 不需要任何本地依赖”。官方安装说明

11.2 离线部署与运维

建议交付结构:app.whl / requirements.lock / wheelhouse / sbom / config / migrations / static / hashes / systemd。wheelhouse 按 Windows-amd64 与 Kylin-linux-x86_64 分别产出;不将 Windows venv 拷贝到麒麟。用内部镜像源或离线校验通过的包安装,包名、版本、hash 与构建环境一起记录。

示意命令(工程代码与精确锁生成后使用,当前仓库只有设计和前端原型):

/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 代理缓冲文档

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. 开发目录、任务拆分与合入条件

建议未来工程目录(当前交付的是设计文件,不创建空类冒充实例化):

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 调用时序

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、用户名和正文都是示例,<access-token>、<演示账号密码> 是占位值。实际 ID 由上一步响应取得,不应硬编码。全部 JSON 请求使用 Content-Type: application/json;除登录、live 外都携带 Authorization: Bearer <access-token>。响应示例省略通用 HTTP 头,仅列关键头。机器可验证的请求/响应样例见 examples.json。

16.1 登录与新建事项

POST /api/v1/auth/login HTTP/1.1
Content-Type: application/json

{"username":"demo-writer-a","password":"<演示账号密码>"}
{"access_token":"<access-token>","token_type":"Bearer","expires_in":900,"auth_mode":"demo"}
POST /api/v1/workspaces HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json
Idempotency-Key: ws-training-20261010-001

{"title":"培训通知起草"}

返回 201 Created,Location: /api/v1/workspaces/ws-001:

{"workspace_id":"ws-001","parent_id":"personal-u-001","title":"培训通知起草","version":1,"status":"active"}

parent_id 为服务端按 Principal 确定的个人工作空间,客户端不能指定别人的个人空间。首次登录的个人空间创建采用唯一约束保证只创建一次。

16.2 保存用户需求、调用数字员工并自动注入 Skill

POST /api/v1/workspaces/ws-001/messages HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json
Idempotency-Key: msg-training-20261010-001

{"content":"请根据来文和培训制度,起草培训通知,缺少日期时标记待确认。"}

获得 201 的 message_id 后启动任务。没有显式传入 Skill,员工默认 Skill 仍自动加载:

POST /api/v1/workspaces/ws-001/runs HTTP/1.1
Authorization: Bearer <access-token>
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:

{
  "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 授权进度流与断线续读

GET /api/v1/runs/run-001/events HTTP/1.1
Authorization: Bearer <access-token>
Accept: text/event-stream
Last-Event-ID: run-001:4
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 修改草稿和确认具体版本

PATCH /api/v1/artifacts/art-001 HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json

{"expected_version":1,"content":"关于开展办公技能培训的通知\n培训日期:待确认。"}

服务端返回 version: 2 与新 content_hash。批准时携带刚取得的 hash;以下 <响应中的64位hash> 为占位值,不是可直接通过校验的请求体:

POST /api/v1/runs/run-001/approval HTTP/1.1
Authorization: Bearer <access-token>
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:

{"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 保存和知识库检索

POST /api/v1/skills HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json
Idempotency-Key: skill-style-20261010-001

{"name":"公文日期核对","category":"document","content":"核对正文中的日期;缺少的信息标记待确认,不自行推测。"}
POST /api/v1/knowledge/search HTTP/1.1
Authorization: Bearer <access-token>
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 查阅的官方资料。框架职责、运行时选择和兼容性测试方案是本项目设计决定;厂商列出平台支持不等于本应用获得认证。

附件 validation-report.json 记录本次静态检查范围;不包含运行时、压力、企业微信投递或真实麒麟/海光测试结果。

附件验证方法

配套 validate_contract.py 和 requirements-design.txt 用于设计契约检查,与未来 Gateway 运行依赖分开。使用 Python 3.12 的隔离环境安装 requirements-design.txt 后,在本目录执行 python validate_contract.py。若依赖已安装在独立目录,可传 --dependency-dir <目录>。检查脚本验证 OpenAPI 3.1、示例 DTO、配置依赖图、幂等/鉴权声明和链接,并重新生成 validation-report.json;不启动服务或发送企业微信消息。