File size: 28,903 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
# Work OS MVP · Workspace Service 系统架构与功能设计 v1.0

> 状态:设计基线,已有首版 PC 持久化实现;与全部需求清单的完成状态请看 [实现说明](../../WorkspaceService/README.md)。日期:2026-10-10。目标:2026-10-18 前完成 PC 演示,随后腾讯云验收,再验证银河麒麟/海光。配套资料:[总体设计](../06_系统设计文档.md)、[API Gateway 设计及 OpenAPI](../10_API_Gateway/README.md)、[细化任务表](../03_细化任务与依赖表.md)。原 Gateway 演示桩已替换为 [Workspace 首版代码](../../WorkspaceService/README.md);目前 SQLite 模式已实测,PostgreSQL 与目标国产平台仍待实测,以下需求清单不可自动视为全部完成。

## 1. 模块定位与范围

Workspace 是**用户个人工作台和每件公文事项的事实账本**:保存事项归属、会话、附件引用、技能选择、草稿和不可变版本。所有数据以服务端核验的 `tenant_id + owner_user_id + workspace_id` 隔离。PC 可将 `tenant_id` 固定为 `demo`,字段、索引和校验仍须存在。

| 负责 | 不负责 |
|---|---|
| 个人空间唯一性;事项创建、列表、重命名、状态投影 | 登录与令牌校验(Identity/Gateway) |
| 事项消息;附件元数据、文件引用、授权下载 | 文件解析、知识索引/检索(Knowledge) |
| 事项 Skill ID/版本绑定;草稿正文、引用、版本及哈希 | Skill 定义、数字员工编排、模型调用(Agent Runtime) |
| 授权的内部读写 Port;可靠领域事件 | DOCX 生成与本机执行(Tool);通知投递(Notification) |

P0 指 10 月 18 日前的 PC 真服务;P1 指随后腾讯云单机;P2 指麒麟海光及企业级扩展。管理端、跨用户共享、正式 OA 发文不在 P0。

## 2. 系统架构、技术栈与小模块

```mermaid

flowchart TB

  Portal[Portal Web / 后续 Admin] --> G[API Gateway /api/v1]

  Identity[Identity Principal] --> G

  G --> W[Workspace Application Service]

  W --> A[WS01 个人/事项]

  W --> B[WS02 事项消息]

  W --> C[WS03 附件]

  W --> D[WS04 草稿版本]

  A & B & C & D --> R[Repository Ports]

  R --> PG[(PostgreSQL)]

  C --> S[StoragePort: 本机文件/S3兼容]

  W --> O[(Workspace outbox)]

  O -.变更事件.-> Context[Context]

  O -.解析请求.-> K[Knowledge]

  Runtime[Agent Runtime] <--> W

  Tool[Tool Gateway] --> W

```

PC 采用**模块化单体中的真实 Workspace 模块**:Gateway 路由调用进程内 `WorkspacePort`;设计目标是真连 PostgreSQL、真写受限文件目录。当前首版在无 PostgreSQL 服务的 PC 上以 SQLite 验证同一领域模型和文件落盘;切换 PostgreSQL 仍须现场验证。云阶段可继续同进程,或以内部 HTTPS 适配器承载同一 Port/DTO。业务服务不通过 HTTP 回调自身,也不直接调用其他模块的数据库表。

| 层 | 推荐技术/框架 | 设计依据与替换点 |
|---|---|---|
| HTTP/DTO | 复用 Gateway 的 FastAPI、Pydantic 2、OpenAPI 3.1 | 复用已冻结外部 URL;DTO 映射与领域服务分离 |
| 领域/装配 | Python 3.11+、`Protocol`、依赖注入/app factory | WS01–04 可独立编码;新实现只换 provider |
| 持久化 | SQLAlchemy 2、Alembic、psycopg 3、PostgreSQL | 事务、唯一约束、版本并发和 outbox;版本锁进依赖文件 |
| 附件 | `StoragePort`;PC 文件系统、云 S3 兼容适配器 | DB 只存随机逻辑键,不存 Windows 盘符/公网直链 |
| 事件 | 同库 outbox;PC 表轮询、云可换 RabbitMQ/Kafka | 业务写入和事件同事务;消费者按 event_id 幂等 |

| 运维 | JSON 日志、trace_id、指标、manifest 备份 | 日志仅记 ID/状态/哈希,不记正文或令牌 |

| 小模块 | 聚合/服务 | 主要方法 | P0 最小交付 |
|---|---|---|---|
| WS01 个人/事项 | `WorkspaceService`、`Matter` | `get_or_create_home`、`list/create/get/rename_matter`、`assert_access`、`bind_skills` | A/B 各有唯一 home;事项真实落库,所有子资源先查归属 |
| WS02 消息 | `MessageService`、`Message` | `append_user_message`、`append_assistant_message`、`list_messages` | 当前事项独立、稳定分页、重试不重复 |
| WS03 附件 | `AttachmentService`、`Attachment` | `upload`、`list`、`open_authorized`、`apply_ingest_result` | 真落盘、hash、受控下载、解析状态 |
| WS04 草稿版本 | `ArtifactService`、`ArtifactVersion` | `create_draft`、`edit_draft`、`get_version`、`resolve_approved_version` | 不可变版本、409 并发冲突、确认绑定版本/hash |

事项 Skill 绑定归 WS01,只存 `skill_id,skill_version,position`;Skill 内容、可用性及注入策略由 Agent/Skill Catalog 决定。客户端不能通过更改 Skill 名称注入执行指令。

## 3. 上层接口、下层对接和灵活扩展

浏览器流量只经 Gateway;Identity 验证后由 Gateway 构造不可由请求体覆盖的 `Principal(tenant_id,user_id,roles,trace_id)`。Workspace **再次用数据库 owner 校验**。内部工作者须有服务认证和最终用户/任务委托上下文;不能用系统身份绕过归属。管理员代读另行设计。

| 对接 | 方式与内容 | 模块更换时改动 |
|---|---|---|
| Portal → Gateway → Workspace | 外部 HTTPS/REST;PC 进程内 Port;13 个既有 `/api/v1` 操作 | 新业务加 DTO/Port/路由装配/合同测试,旧 URL 语义不变 |
| Identity → Workspace | Gateway 注入 Principal;Workspace 校验 owner | SSO/LDAP 变化只换 Identity adapter |
| Agent Runtime ↔ Workspace | `WorkspacePort` 或内网 mTLS HTTPS;起跑校验事项、读取 Skill 快照;写助手消息/草稿必须带 run_id 与幂等键 | 新数字员工流程复用 Port,不能直写 WS 表 |

| Context → Workspace | 只读 `ContextReadPort`;带 owner 的当前事项消息/附件/版本引用 | 换 Context 实现只改 adapter |

| Workspace → Knowledge | `document.ingest.requested` 事件;结果回执更新附件状态投影 | 换解析/索引引擎不改公共附件 API |

| Tool Gateway → Workspace | `ApprovedArtifactReadPort`;执行后绑定导出文件/回执 | 新工具复用精确版本/hash 约束 |

| Workspace → Context/Notification | outbox 变更事件,payload 只含必要 ID/版本/状态 | 新消费者订阅版本化事件,不改写路径 |



扩展的最低前提是 DTO 合同兼容、授权语义不弱化、事件版本受控、数据迁移通过。配置新 URL 并不能自动证明 owner 过滤或事务正确,替换实现必须跑双用户和幂等测试。



### 3.1 对外接口列表



以 [Gateway OpenAPI](../10_API_Gateway/openapi.json) 为字段、header、状态码和错误体的权威来源。以下 13 项为 Workspace 所有;所有路径前缀 `/api/v1`。越权资源与不存在统一 404;POST 创建/消息/上传要求 `Idempotency-Key`。



| API | 方法及路径 | 子模块 | 核心输入/结果 |

|---|---|---|---|

| 05 | `GET /workspaces` | WS01 | 本人事项稳定分页;200 |

| 06 | `POST /workspaces` | WS01 | title、幂等键;201 同键重试同 ID |

| 07 | `GET /workspaces/{workspace_id}` | WS01 | 本人事项;200/404 |
| 08 | `PATCH /workspaces/{workspace_id}` | WS01 | title、expected_version;成功版本+1,旧版 409 |

| 09 | `GET /workspaces/{workspace_id}/messages` | WS02 | 游标/limit;事项消息分页 |
| 10 | `POST /workspaces/{workspace_id}/messages` | WS02 | content、幂等键;201 |
| 11 | `GET /workspaces/{workspace_id}/attachments` | WS03 | 只返回元数据/解析状态 |
| 12 | `POST /workspaces/{workspace_id}/attachments` | WS03 | 单件 multipart、幂等键;201/413/422 |
| 13 | `GET /attachments/{attachment_id}/content` | WS03 | 授权流式下载;200/404 |
| 22 | `PUT /workspaces/{workspace_id}/skills` | WS01 | skill_ids、expected_version;200/409/422 |
| 28 | `GET /artifacts/{artifact_id}` | WS04 | 当前草稿正文、版本、hash、引用 |
| 29 | `PATCH /artifacts/{artifact_id}` | WS04 | content、expected_version;新版本或 409 |

| 30 | `GET /artifacts/{artifact_id}/versions/{version}/content` | WS04 | 该版本生成文件;200/404 |

API-23 任务启动和 API-27 人工确认归 Agent Runtime;API-14 上下文归 Context。Workspace 供其授权数据,不接管 run 状态机与 SSE。

Workspace 响应新增可选 `latest_artifact_id`(无草稿时为 null):客户端重启后可用既有 API-28 重新读取最新草稿,不新增路由。该指针仅在已授权事项响应中返回;[Gateway OpenAPI](../10_API_Gateway/openapi.json)同步定义。

### 3.2 内部 Port 代码骨架

```python

@dataclass(frozen=True)

class Principal:

    tenant_id: str

    user_id: str

    roles: frozenset[str]

    trace_id: str



class WorkspacePort(Protocol):

    def assert_access(self, principal: Principal, workspace_id: str) -> MatterRef: ...

    def append_assistant_message(self, principal: Principal, workspace_id: str,

                                 run_id: str, step_id: str, content: str,

                                 idempotency_key: str) -> MessageRef: ...

    def create_draft(self, principal: Principal, workspace_id: str,

                     run_id: str, content: str, citation_ids: list[str],

                     idempotency_key: str) -> ArtifactRef: ...

    def resolve_approved_version(self, principal: Principal, artifact_id: str,

                                 version: int, expected_hash: str) -> ArtifactVersionRef: ...

```

建议文件布局:`workspace/contracts/v1.py`、`ports.py`、`domain/`、`application/`、`adapters/postgres.py`、`adapters/storage_fs.py`、`tests/contract/`、`alembic/versions/`。分进程时由服务认证封装委托主体;不允许前端直接提交内部 Principal JSON。

## 4. 数据模型和关键不变量

```mermaid

erDiagram

  PERSONAL_WORKSPACE ||--o{ MATTER_WORKSPACE : contains

  MATTER_WORKSPACE ||--o{ MESSAGE : contains

  MATTER_WORKSPACE ||--o{ ATTACHMENT : contains

  MATTER_WORKSPACE ||--o{ WORKSPACE_SKILL_BINDING : selects

  MATTER_WORKSPACE ||--o{ ARTIFACT : owns

  ARTIFACT ||--o{ ARTIFACT_VERSION : has

  MATTER_WORKSPACE ||--o{ WORKSPACE_OUTBOX : emits

```

| 表/主键 | 必需字段(不含时间戳) | 唯一/索引与写入规则 |
|---|---|---|
| `personal_workspace(home_id)` | tenant_id,owner_user_id | `UNIQUE(tenant_id,owner_user_id)`;并发登录 `INSERT ... ON CONFLICT ... RETURNING` |
| `matter_workspace(workspace_id)` | home_id,tenant_id,owner_user_id,title,status,version | FK home;断言 home 同 tenant/owner;`INDEX(tenant_id,owner_user_id,updated_at,workspace_id)` |
| `workspace_message(message_id)` | workspace_id,tenant_id,owner_user_id,seq,role,content,run_id?,step_id? | `UNIQUE(workspace_id,seq)`;带幂等键时按主体+事项+操作唯一;只追加 |
| `attachment(attachment_id)` | workspace_id,filename,mime,byte_size,sha256,storage_key,parse_status,knowledge_document_id? | 随机 storage_key;`INDEX(workspace_id,created_at,id)`;解析状态由回执投影 |

| `workspace_skill_binding` | workspace_id,skill_id,skill_version,position,binding_version | `UNIQUE(workspace_id,skill_id)`;整体 CAS;目录不可用则拒绝 |

| `artifact(artifact_id)` | workspace_id,kind,current_version,approval_version? | 查找前校验事项归属;一个事项可有多个产物 |

| `artifact_version` | artifact_id,version,content,content_hash,citation_ids,source_run_id,export_storage_key? | `PRIMARY KEY(artifact_id,version)`;正文写后不可变 |

| `workspace_outbox(event_id)` | aggregate_id,aggregate_version,event_type,payload,trace_id,published_at? | 事务内写;`UNIQUE(aggregate_id,aggregate_version,event_type)` |
| `workspace_idempotency` | tenant_id,owner_user_id,workspace_id?,operation,key,request_hash,response_ref | 相同键+hash 复用结果,异 hash 409 |

每个子资源同时保留 tenant/owner/workspace;高风险查询须 JOIN `matter_workspace` 并过滤 tenant+owner,**不可只比较附件/草稿 ID**。数据库 FK/唯一约束为最终防线。SQLAlchemy 用 `with session.begin()`;版本冲突用 `UPDATE ... WHERE version=:expected RETURNING` 或行锁后校验,零行返回 409。PostgreSQL 的[官方行锁文档](https://www.postgresql.org/docs/current/explicit-locking.html)支撑同一聚合的串行化。分库后不承诺跨库本地事务,改用 outbox+幂等消费+对账。

### 4.1 附件状态和物理文件

PC 限单件 **10 MiB**、单事项 **5 件**;支持 DOCX/PDF/TXT/MD 文本;扫描 PDF/OCR 不在 P0。上传流先写受限 staging 目录,计数/校验 MIME、扩展名、SHA-256,再移动到随机逻辑键目录,随后提交元数据及 `document.ingest.requested` outbox;DB 提交失败则清理新文件,清理失败由 reconcile 找回孤儿。客户端不能指定 storage_key、物理路径或对象存储 URL。解析失败只更新 `parse_status=failed` 与安全错误码,原文件仍可授权下载。

文件系统与 DB 非一个事务:采用 `staging → verified → committed`,提供 manifest(attachment_id、storage_key、sha256、bytes)与重扫作业。云可换 S3 兼容 StoragePort;[MinIO S3 文档](https://min.io/docs/minio/linux/index.html)是适配依据,具体产品部署时再选并实测。Knowledge 拥有解析结果和索引,Workspace 只保存回执/状态投影;重复或乱序回执按 ingest_job_id+event_version 幂等处理。



### 4.2 草稿与人工确认



每次编辑在一个事务中检查 expected_version、插入 `artifact_version(current+1)`、更新 current_version、写 outbox;历史正文不可覆盖。`content_hash=SHA-256(UTF-8 NFC 正文)`,相同正文再次编辑仍产生新版本以保留审计。引用保存 citation ID 和生成时所用知识文档版本,显示时由 Knowledge 再做授权与有效性检查。

Runtime 的批准请求带 `artifact_id,version,content_hash`。Workspace 在事务内验证请求版本等于当前版本、hash 一致,并把确认绑定到这个不可变版本。之后编辑产生未确认新版本;旧确认只允许用于旧版受控导出,不能授权新版。Tool 仅按精确三元组读取,执行回执和导出文件引用再绑定到该版本。跨进程失败用幂等键重试并对账;不能靠 `approved=true` 布尔值授权任意正文。

### 4.3 状态与事件

事项 status 是列表投影:`new/running/awaiting_confirmation/completed/failed`;run 真状态/进度归 Runtime。Workspace 消费 Runtime 事件只接受同一 run 的更高 run_sequence;旧事件不得倒退事项状态。客户端 PATCH 不得修改 status。



Workspace 自有领域事件**不冒充**[RunEventEnvelope](../09_架构契约/event-envelope.schema.json):后者强制 run_id/sequence,而 workspace.created 尚无 run。Workspace outbox v1 字段为 `event_id,event_type,event_version,tenant_id,owner_user_id,workspace_id,aggregate_version,trace_id,occurred_at,payload`,run_id 可选;若 Runtime 需 SSE,须转成真正带 run_id/run sequence 的 RunEventEnvelope。事件包括 workspace.created/updated、message.appended、attachment.uploaded、document.ingest.requested、attachment.ingest_succeeded/failed、artifact.version_created/confirmed、artifact.export_attached。payload 只放 ID/版本/状态/摘要,不广播正文;消费者按 event_id 去重。


## 5. 安全、性能、部署与国产化迁移

**权限与隐私**:Identity 验证后 Gateway 注入 Principal,Workspace 每次读写重验 owner。用户 A 的事项 ID 用在消息、附件下载、草稿、Skill 绑定和内部 Context/Tool 读取均返回 404。内部 worker 带真实委托主体 + run_id;日志不记令牌、全文或物理路径。P0 不开放共享事项、管理员代读或正式发文。



**输入、并发和错误**:标题、消息、草稿设最大长度;SQL 参数绑定;文件名只用于安全显示,下载使用安全编码的 Content-Disposition;阻断路径穿越、符号链接逃逸和双扩展名伪装。上传流限额,不能整文件读爆内存。幂等作用域含租户/用户/事项/操作;稳定游标分页。单事项最多一个活跃 run 由 Runtime 限制。



**观测与恢复**:跟踪 HTTP 延迟、5xx/409、outbox 积压、解析等待、孤儿文件数;审计记录谁何时创建、修改、确认及 trace,不记全文。PC 的 DB 与文件目录成套备份,恢复时对账 manifest/hash,重跑 A/B 隔离用例。P1 腾讯云沿用[两阶段部署方案](../07_两阶段部署与成本.md)的 4 vCPU/8 GiB 单机、PostgreSQL 与受限数据盘或 S3 兼容存储;Qwen 继续走公网 API,Workspace 不另购 GPU。实际费用按部署方案及购买时价格复核。



**国产化**:银河麒麟 V10 SP3 官方资料列出[海光平台支持](https://www.kylinos.cn/productPc/server/serverMain/additional),但不表示 Python native wheel 已在目标环境验证。迁移时记录具体 OS/CPU 版本,实测 Python、psycopg、pydantic-core、cryptography、libpq/TLS、PostgreSQL、文件权限、systemd;运行相同 Alembic 迁移、接口合同、双用户越权、附件 hash、并发版本与备份恢复。容器镜像也须在目标机实测架构及运行时。PostgreSQL 方言封装于 Repository;不假设国产数据库零代码替换。国密/等保要求待客户定级和产品选型,不宣称 P0 已达标。



## 6. 办文工作流示例:Workspace 如何运行



```mermaid

sequenceDiagram

  participant U as 用户/Portal

  participant G as API Gateway

  participant W as Workspace

  participant K as Knowledge

  participant C as Context

  participant A as Agent Runtime

  participant T as Tool Gateway

  U->>G: 创建“年度培训通知”事项

  G->>W: create_matter(Principal,title,key)
  W-->>G: workspace_id/version=1

  U->>G: 上传制度PDF,发送写作要求

  G->>W: upload / append_user_message

  W-->>K: outbox: document.ingest.requested

  K-->>W: ingest_succeeded(document_id)

  U->>G: 调用公文写作数字员工

  G->>A: start(run,workspace_id,skills)
  A->>W: assert_access / read_message / read_attachment_refs
  A->>C: 构建当前事项上下文和引用
  A->>W: create_draft(content,citation_ids,run_id)

  W-->>U: 草稿 v1,待人工核对

  U->>G: PATCH 草稿 expected_version=1
  G->>W: edit_draft -> v2/hash2

  U->>G: 确认 v2/hash2

  G->>A: approval(run_id,v2,hash2)
  A->>W: resolve_approved_version(v2,hash2)
  A->>T: 导出 v2/hash2 DOCX
  T-->>W: 绑定导出文件及回执
```



A 创建事项 ws-a-01,B 即使拿到 ID,也不能读取该事项、消息或附件。A 把 v1 改为 v2 后再提交 v1/hash1 确认,Workspace 返回 409 artifact_version_conflict。Knowledge 故障时附件保持 parsing/failed 且本人可下载;Agent 对需要检索的步骤显示 dependency_not_ready,不假装检索成功。消息和进度流由 Runtime 组织,Workspace 留存消息及产物事实。



## 7. 接口示例与错误规范



以下是**设计示例,不是运行实测**;完整字段以[Gateway OpenAPI](../10_API_Gateway/openapi.json)为准。



```http

POST /api/v1/workspaces HTTP/1.1

Authorization: Bearer <token-for-user-a>

Idempotency-Key: create-matter-20261010-a

Content-Type: application/json



{"title":"2026年度培训通知"}

```

```json

{"workspace_id":"ws-a-01","parent_id":"home-a","title":"2026年度培训通知","version":1,"status":"new"}

```

```http

PATCH /api/v1/artifacts/art-a-01 HTTP/1.1

Authorization: Bearer <token-for-user-a>

Content-Type: application/json



{"content":"关于开展年度培训的通知……","expected_version":1}

```

```json

{"artifact_id":"art-a-01","workspace_id":"ws-a-01","version":2,"content":"关于开展年度培训的通知……","content_hash":"<sha256-hex>","approval_status":"unconfirmed","citation_ids":["cite-001"]}

```

错误沿用 Gateway 的 code/message/trace_id/details:401 会话无效;404 不存在或无权访问;409 版本、幂等键、附件额度冲突;413 文件超限;422 DTO、文件类型、Skill 不合法;503 必需存储依赖不可用。错误体不含他人 ID、正文、路径或内网地址。



```json

{"code":"artifact_version_conflict","message":"草稿已更新,请刷新后重试","trace_id":"tr-001","details":{"current_version":2}}

```



## 8. 开发顺序与验证方式



沿用[任务表 W01–W08](../03_细化任务与依赖表.md)的依赖链:Identity/Gateway/DB 基础 → WS01 个人与事项 → owner 校验 → WS02 消息与 WS03 附件 → WS04 版本。DTO/合同可先并行准备,但 Gateway fixture 不能代替 Workspace 验收。配置集中管理 DATABASE_URL、WORKSPACE_FILE_ROOT、MAX_UPLOAD_BYTES、OUTBOX_MODE;演示用户与 Windows 路径不写死在领域代码。



完成性证据必须是**真实进程 + 真 PostgreSQL + 文件目录**:A/B 各建两件事项、写消息、传文件;重启后数据仍在;B 访问 A 全部资源为 404;相同幂等键不重复;并发编辑同版仅一个成功;上传/下载 hash 相同;Knowledge 中断时解析状态显式失败或待重试。云和麒麟阶段重复同一套脚本,保留运行日志与环境版本。现有 Gateway 桩通过只证明 HTTP 演示链路。



设计依据:[Gateway OpenAPI](../10_API_Gateway/openapi.json)、[总体架构与 Run 事件契约](../09_架构契约/README.md)、[PostgreSQL 官方行锁文档](https://www.postgresql.org/docs/current/explicit-locking.html)、[麒麟 V10 SP3 平台信息](https://www.kylinos.cn/productPc/server/serverMain/additional)、[MinIO S3 接口文档](https://min.io/docs/minio/linux/index.html)。



## 9. 需求清单与可执行验收(客户重点)



**读法**:P0 是 10 月 18 日前 PC 必过;P1 是随后腾讯云;P2 是麒麟海光/后续能力。WS01–04 表示小模块从属。每一条都有可执行动作和可观察结果;未通过不得标完成。依赖列说明其他模块的前置条件,不能把其桩响应算作 Workspace 自身实现。



### 9.1 WS01:个人空间、事项和 Skill 绑定



| ID | 阶段 | 需求/行为 | 依赖 | 完成性检验 |

|---|---|---|---|---|

| WS01-01 | P0 | 首次登录为每位用户创建唯一个人空间;重复登录复用 | Identity Principal、PostgreSQL | A 连续登录 3 次仅 1 个 home;B 是另一个;DB 有唯一约束 |

| WS01-02 | P0 | 个人空间下创建、列出、进入事项;有标题、归属、状态、版本 | WS01-01、Gateway API-05–07 | A/B 各建 2 件,各列表只见自己的 2 件;重启后仍存在 |

| WS01-03 | P0 | 事项重命名按 expected_version 比对 | WS01-02、API-08 | 旧版 PATCH 409;成功后版本+1,标题不丢 |
| WS01-04 | P0 | 所有子资源统一租户+用户+事项授权 | Identity、WS01-02 | B 对 A 的事项、消息、附件、草稿、Skill URL 读写均 404;拒绝有审计 |
| WS01-05 | P0 | 事项列表稳定分页,切换事项不串消息或附件 | WS01-02 | 20+ 事项翻页不漏/不重;A1 切 A2 内容独立 |
| WS01-06 | P0 | 事项 Skill 选择保留 ID、版本、顺序,更新按绑定版本 CAS | Agent Skill Catalog、API-22 | 重开事项仍保留;不可用 Skill 422;并发旧版 409;运行读同一快照 |
| WS01-07 | P0 | 创建事项按幂等键和请求哈希去重 | WS01-02 | 同键同体返回同一事项;同键异体 409,无第 2 件 |
| WS01-08 | P0 | 事项状态投影消费 Runtime 事件并对账 | Runtime run 事件 | 乱序/重复不倒退状态;完成后列表与 run 一致 |
| WS01-09 | P2 | 共享事项和管理员授权另立角色模型 | 客户角色矩阵 | 未审批前接口不开放;审批后另立验收 |

### 9.2 WS02:事项消息和对话输入

| ID | 阶段 | 需求/行为 | 依赖 | 完成性检验 |
|---|---|---|---|---|
| WS02-01 | P0 | 用户消息写入当前事项,带主体、顺序、时间和内容 | WS01-04、API-10 | A1 写 3 条,刷新/重启仍为 3 条;A2/B 看不到 |
| WS02-02 | P0 | Agent 助手消息仅在授权事项及真实 run 上追加 | Runtime、WS01-04 | 错事项/run 委托写入拒绝;合法结果只在该事项可见 |
| WS02-03 | P0 | 消息按服务端序号稳定分页 | WS02-01、API-09 | 100 条分页读完 ID 与 DB 一致,无重复/遗漏 |
| WS02-04 | P0 | 消息写入幂等;键同而正文变化 409 | WS02-01 | 重试不多一条;异文重用键 409 |
| WS02-05 | P1 | 审计、内容长度和保留策略可配置 | 客户留存要求 | 超限 422,审计无正文,客户确认策略后迁移验证 |

### 9.3 WS03:附件与资料证据链

| ID | 阶段 | 需求/行为 | 依赖 | 完成性检验 |
|---|---|---|---|---|
| WS03-01 | P0 | 上传 DOCX/PDF/TXT/MD,单件≤10 MiB、事项最多 5 件 | WS01-04、StoragePort、API-12 | 四类样本可传;第 6 件/超限/非法文件给 409/413/422,不落半文件 |
| WS03-02 | P0 | 持久化原件及元数据:随机逻辑键、大小、MIME、SHA-256 | WS03-01、PostgreSQL | 重启后列表仍在;实际 hash 与记录一致;DB 无 Windows 绝对路径 |
| WS03-03 | P0 | 下载时重验 owner,阻断路径穿越/软链接逃逸 | WS01-04、API-13 | B 下载 A 的文件 404;伪造键/../ 无法越根;本人下载 hash 不变 |
| WS03-04 | P0 | 上传后发解析请求,展示 uploaded/parsing/ready/failed | Knowledge 回执、outbox | 成功为 ready、失败为 failed+安全错误码;重复回执无重复效果 |
| WS03-05 | P0 | DB/文件部分失败可清理或 reconcile | WS03-01/02 | 注入 DB 提交失败后无可见附件;扫描能报告并清理孤儿 |
| WS03-06 | P1 | 云对象存储 adapter 和 manifest 迁移 | 腾讯云存储/权限 | 导入后逐件 hash 相同,授权下载一致 |
| WS03-07 | P2 | OCR、病毒扫描、敏感信息策略另行选型 | 安全/OCR 产品 | 新用例另立;PC 文本资料不依赖 |

### 9.4 WS04:草稿、版本和人工确认

| ID | 阶段 | 需求/行为 | 依赖 | 完成性检验 |
|---|---|---|---|---|
| WS04-01 | P0 | Agent 在当前事项创建带引用的草稿 v1 | WS01-04、Runtime、Knowledge 引用 | 生成后正文、版本、hash、引用可查;重启仍可取 |
| WS04-02 | P0 | 每次编辑新增不可变版本,保留历史正文/hash | WS04-01、API-29 | 连改两次得 v1/v2/v3,v1 正文和 hash 不变 |
| WS04-03 | P0 | expected_version 乐观锁防覆盖 | WS04-02 | 两客户端同时以 v1 保存,仅一成功,另一 409;无丢失 |

| WS04-04 | P0 | 人工确认绑定 artifact_id+version+content_hash | Runtime API-27、WS04-02 | v1 确认后编辑 v2,旧确认不能导出 v2;错 hash/owner 拒绝 |

| WS04-05 | P0 | Tool 只读已确认精确版本;回执与版本关联 | Tool Gateway、WS04-04 | v2/hash2 返回 v2;v1/hash2 拒绝;下载对应版本 |

| WS04-06 | P0 | 草稿及版本文件下载始终校验 owner | WS01-04、API-28/30 | B 对 A 草稿和各版本内容均 404 |

| WS04-07 | P1 | 历史比较与恢复产生新版本 | WS04-02、Portal | 恢复 v1 时创建 vN+1,旧版本仍可审计 |

| WS04-08 | P2 | 正式 OA 发文回写、电子签章另用 Adapter | OA 系统/客户授权 | 未联通前 capability=false;另立端到端验收 |



### 9.5 跨模块非功能与交付要求



| ID | 阶段 | 需求/行为 | 依赖 | 完成性检验 |

|---|---|---|---|---|

| WS-X01 | P0 | Repository 真连 PostgreSQL,迁移脚本可重复部署 | DB、Alembic | 空库迁移→接口写入→重启→数据仍在;fixture 不计通过 |

| WS-X02 | P0 | 事务内写 outbox、可重试和去重发布 | WS-X01、消费者 | 注入发布失败再恢复,事件最终有一次业务效果,无已提交事项缺事件 |

| WS-X03 | P0 | Gateway/Workspace 错误和 trace 可追踪 | Gateway、日志 | 一次失败按 trace 找到调用;日志无 token、正文、物理路径 |

| WS-X04 | P0 | 完整双用户 E2E、并发与故障回归 | WS01–04 | 自动化脚本/日志留存;PC 从空状态走完办文,不借 WS 桩 |

| WS-X05 | P1 | 腾讯云单机迁移、备份恢复、manifest 对账 | 云主机/存储 | 恢复后 A/B 事项、附件、版本和 hash 与迁移前一致 |

| WS-X06 | P2 | 麒麟 V10 SP3 + 海光目标机实测 | 目标硬件/OS/依赖包 | 同一合同及隔离脚本通过,记录 CPU/OS/包版本及失败项 |



**P0 出门条件**:WS01-01~08、WS02-01~04、WS03-01~05、WS04-01~06、WS-X01~04 全通过。其他模块仍为桩时,报告逐项标注;Workspace 自身不得替换为桩。P1/P2 不阻挡 10 月 18 日前 PC 演示,但不得标为已完成。