File size: 68,073 Bytes
99caad5
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
# 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 <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 标准](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、用户名和正文都是示例,`<access-token>`、`<演示账号密码>` 是占位值。实际 ID 由上一步响应取得,不应硬编码。全部 JSON 请求使用 `Content-Type: application/json`;除登录、live 外都携带 `Authorization: Bearer <access-token>`。响应示例省略通用 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":"<access-token>","token_type":"Bearer","expires_in":900,"auth_mode":"demo"}

```



```http

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`:



```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 <access-token>

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 <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:



```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 <access-token>

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 <access-token>

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 <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`:



```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 <access-token>

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 <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 查阅的官方资料。框架职责、运行时选择和兼容性测试方案是本项目设计决定;厂商列出平台支持不等于本应用获得认证。



- 现有项目基线:[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;不启动服务或发送企业微信消息。