Agent-System/docs/user-manual/manual.md

水木东方 · 医疗器械 AI 协同工作台 — 系统使用说明书

项目	说明
文档版本	v1.0
编写日期	2026-09-18
适用环境	dev / test / main 三环境通用（截图取自 dev 环境）
适用读者	系统管理员、研发总监、技术主管、方案工程师、外部审计/访客
配套格式	Markdown（本文）/ HTML / PDF / Word

---

目录

1. 系统简介
2. 快速开始：从 0 进入系统
3. 界面导览：三栏工作台
4. 管理员指南：用户、角色与权限
5. 项目使用：立项与成员配置
6. 对话与 AI 项目助手
7. 文档工作台
8. 审批全流程
9. 角色权限速查与典型动线
10. 常见问题 FAQ

---

1. 系统简介

1.1 系统定位

水木东方 · 医疗器械 AI 协同工作台 是一个面向企业与团队的多用户工作流与对话智能体平台，定位于医疗器械受控研发场景（NMPA / ISO 13485 语境）。它将「AI 对话助手」与「受控文档治理」结合：项目成员通过对话推进项目，AI 助手协助沉淀研发文档，文档经过编制 → 审核 → 批准三责分离的审批链后归档生效，阶段全部必需文档批准后项目方可推进到下一阶段。

1.2 三大核心能力

1. 受控 RBAC 权限体系：系统级角色权限（RBAC）+ 文档级职责角色（编制/审核/批准）+ 项目级成员职责，三层隔离。
2. 项目助手（AI Agent）：每个项目会话配备项目助手，支持 SSE 流式对话、意图识别、计划确认卡片、知识库检索推荐。
3. 三层文档隔离：交付物分为「工作流受控」「项目共享」「个人私密」三类，受控文档全生命周期留痕，支持版本历史、修订、导出 DOCX/XLSX。

1.3 主要功能一览

模块	功能
登录与准入	账号密码登录、用户自主注册、注册审批、首次登录强制改密
工作台	三栏布局：项目会话列表 / 对话区 / 交付物文档区
项目管理	立项会话、成员与职责分配、工作流切换、阶段门禁推进
对话	流式对话、附件上传（每轮最多 5 个）、意图计划卡片、历史搜索与导出
文档	块编辑、编辑租约锁、版本历史与对比、评论、可见性覆盖、导出
审批	文档三责审批（编制/审核/批准）、阶段门禁、注册审批、修改建议审批
系统管理台	运行总览、知识库连接、特性开关、设置白名单、工作流定义、RBAC 角色权限、用户与准入治理、文档模板库
知识库	跨环境共享的向量知识库（RAG），检索结果在对话中以推荐卡片呈现

1.4 术语表

术语	含义
项目实例（ProjectInstance）	一个业务项目激活工作流后生成的运行实例，包含阶段序列与当前活动阶段
工作流（Workflow）	预定义的「阶段 → 任务 → 产出文档」模板。系统内置三套正式工作流：main（V0.1 需求摸底 → V0.5 方案与可行性 → V1.0 商务报价）、product_manager（系统需求基线）、test_manager（系统验证策划）
阶段门禁（Stage Gate）	进入下一阶段前，本阶段所有「必需且受审批管理」的文档必须到达「已批准」终态，由项目创建人显式推进
文档审批（docgov）	受控文档 编制中 → 审核中 → 批准中 → 已批准 的生命周期，三责分离，含编辑租约锁
职责三角色	编制人（author，唯一可改正文）、审核人（reviewer）、批准人（approver）
RAG 知识库	跨环境共享的向量检索库，为对话提供引用与案例推荐
SSE 流式对话	服务端推送（Server-Sent Events）实时输出 AI 回复，逐字呈现
任务持久化	AI 任务运行落库，支持断点恢复、取消与事件回放
PI Agent Runner	产品容器内的真实 AI 执行器，驱动项目助手对话与文档生成

---

2. 快速开始：从 0 进入系统

2.1 访问地址与浏览器要求

环境	访问地址	用途
开发 dev	http://127.0.0.1:8080	日常开发验证
测试 test	http://127.0.0.1:8081	发布前验收
生产 main	http://127.0.0.1:8000	正式使用

推荐使用 Chrome / Edge 最新版本，窗口宽度建议 1440px 以上（三栏布局）。

2.2 账号从哪里来

系统不提供匿名访问，账号有三条来源：

1. 管理员直接开通（最常见）：管理员在管理台「用户与准入治理」中创建受控员工账号，初始密码默认为 InitPass123，首次登录强制改密（见 2.5）。
2. 用户自主注册：在登录页「用户自主注册」Tab 自行注册。注册后职位为「访客/待指派」，必须经管理员在注册审批中心核准后才能登录。是否开放注册、注册是否需要审核，由管理员在「准入策略」中控制。
3. 环境引导管理员：系统首次部署时自动创建管理员账号（用户名密码由部署配置决定）。

2.3 登录

打开访问地址，进入登录页。左侧为品牌与能力介绍，右侧为登录表单；左上角胶囊显示当前环境（DEV/MAIN）。

操作步骤：

1. 在「账号密码登录」Tab 输入用户名与密码；
2. 点击登录；
3. 登录成功后进入三栏工作台。

注意：连续登录失败请确认账号状态。新注册未审核的账号登录会提示「账号正在等待管理员审核中」；被停用的账号无法登录，需联系管理员。

2.4 自主注册

1. 切换到「用户自主注册」Tab；
2. 填写必填项：用户名、真实姓名、密码（两次输入一致）；选填：部门、工号；
3. 提交后等待管理员审核；审核通过后使用注册的用户名密码登录；
4. 审核通过后，管理员还会为你指派职位与角色（见第 4 章）。

2.5 首次登录强制改密

管理员开通的账号使用初始密码首次登录时，系统强制要求修改密码：

1. 输入新密码并确认；
2. 点击「重置并加密」；
3. 确认后自动进入系统，之后使用新密码登录。

---

3. 界面导览：三栏工作台

登录成功后进入工作台。工作台为三栏布局：

区域	内容
左栏	项目会话列表（一项目一会话）、「+ 新建立项会话」按钮、项目成员入口
中栏	对话区：消息流、阶段事件条、分类 Dock、输入区（附件/引用/发送）
右栏	交付物文档区：分类 Tab（受控/共享/私密）、文档渲染与块编辑、治理操作条

3.1 顶栏

顶栏显示：当前项目名与当前阶段、工作流名称与运行状态、项目助手在线状态（绿点）、系统设置与个人信息入口。

3.2 左栏：项目会话列表

• 每个项目对应一个会话卡片，显示项目名、当前阶段徽标、消息数；
• 点击卡片切换当前项目；
• 「+ 新建立项会话」发起立项（见 5.1）；
• 「项目成员」打开成员与职责弹窗（见 5.2）。

3.3 个人设置

点击左下角个人区域打开个人设置弹窗，可修改个人资料（姓名、部门、工号等）：

3.4 我的项目权限

「我的项目权限」弹窗展示当前账号在各项目中的职责：待我编制 / 待我审核 / 待我批准的文档清单，以及法定职责说明：

---

4. 管理员指南：用户、角色与权限

本章仅适用于**系统管理员（ADMIN）**角色。管理员登录后，可通过顶栏入口切换到「系统管理台」全屏视图；非管理员访问会被二次鉴权拦截（403 退回工作台）。

系统管理台左侧为 8 个分组导航：

分组	用途
系统运行总览	服务健康、版本、数据库与知识库就绪状态
知识库连接	知识库在线状态、服务地址、数据库、连接账号
特性功能开关	环境变量级 / 数据库级 feature flag 管理
系统设置白名单	允许前端读取的系统设置项
工作流定义	内置工作流定义列表（阶段/任务/产出文档结构）
RBAC 角色权限	角色-权限矩阵，支持自定义角色
用户与准入治理	账号开通、注册审批、准入策略
文档与模板库	文档模板名称、版本、资产标识

4.1 开通受控员工账号

在「用户与准入治理 → 账号列表」中：

1. 点击「开通受控员工账号」；
2. 填写用户名、姓名、角色、部门等信息；
3. 系统生成初始密码（默认 InitPass123），将其线下告知员工；
4. 员工首次登录会被强制改密（见 2.5）。

账号列表还支持：变更职位与角色、启用/停用账号、重置初始密码（重置后该账号下次登录再次强制改密）。

4.2 注册审批中心

当准入策略开启「自主注册」且「注册需审核」时，新注册用户进入待审核队列：

• 通过并指派：先在下拉框选择授予的业务职位（如「方案工程师」），再点击通过；账号激活，用户可登录并立即拥有该职位对应角色权限；
• 驳回：注册被拒绝，账号不可用。

4.3 准入策略

两个开关：

开关	说明
开放自主注册	关闭后登录页不再显示「用户自主注册」Tab
注册需要审核	开启后新注册账号处于待审核状态，须管理员核准

4.4 RBAC 角色权限矩阵

「RBAC 角色权限」分组展示角色 × 权限点矩阵：

系统内置 5 个角色（ADMIN 为系统角色，不可删除/改名）：

角色	Code	定位
系统管理员	ADMIN	全量权限，含系统管理台
研发总监	DIRECTOR	立项、指派负责人、可见性配置与覆盖、导出、查看全部工作流
研发技术主管	TECH_LEAD	立项、指派负责人、导出、查看全部工作流
方案工程师	ENGINEER	导出、查看全部工作流
外部审计/访客	GUEST	仅导出（只读审计场景）

权限点目录：project:create（立项）、project:assign_lead（变更责任人）、system:manage（系统管理）、workflow:config_visibility（可见性配置）、doc:override_visibility（可见性覆盖）、doc:export（导出）、workflow:view_all（查阅全部）、workflow_defs.publish（发布工作流定义）、templates.publish（发布模板）。

管理员还可新建自定义角色并勾选权限点组合，或修改/删除非系统角色。

4.5 其余管理分组

截图	说明
	特性功能开关：控制实验性能力的启用/关闭（数据库级开关即时生效；环境变量级需重启服务）。注意：未理解的开关不要随意改动，部分开关影响数据处理链路
	知识库连接：查看共享知识库（RAG）在线状态、服务地址、数据库与连接账号；离线时对话中的案例推荐不可用
	工作流定义：查看内置工作流的阶段、任务与产出文档模板结构
	文档与模板库：模板名称、版本列表与资产标识（asset_key），受控文档基于模板生成

---

5. 项目使用：立项与成员配置

5.1 新建立项会话

拥有 project:create 权限的角色（研发总监、技术主管）可立项。点击左栏「+ 新建立项会话」：

1. 填写项目名称、项目类型、背景说明等；
2. 选择工作流（见 5.3）；
3. 确认后系统创建项目实例，自动进入第一阶段（如 main 工作流的「V0.1 需求摸底」），并生成本阶段要求的受控文档骨架。

5.2 项目成员与职责分配

立项后，打开「项目成员」弹窗，把成员加入项目并分配职责：

职责与文档审批链直接挂钩（见第 8 章）：

• 编制人：可编辑受控文档正文、提交送审；
• 审核人：对送审文档做审核决议（通过/驳回）；
• 批准人：终审批准，批准后文档归档生效。

职责模式：项目工作流计划可配置 full（编制/审核/批准三人齐备）、partial（部分职责）、none（免审批链）以及试点环境的「编制人兼任」（同人三签）模式。

5.3 工作流切换

一个项目可挂接多套工作流（如同时推进商务线 main 与产品线 product_manager）。工作流在项目设置的「选择工作流」步骤中选择（列出全部已发布工作流，单选）：

工作流	阶段序列
main	V0.1 需求摸底 → V0.5 方案与可行性 → V1.0 商务报价
product_manager	系统需求基线
test_manager	系统验证策划

5.4 项目设置与职责配置

项目设置的「配置职责」步骤中，可将阶段产出文档（如 intake 用户初始需求收集表）纳入人工审批，并通过下拉框指派编制/审核/批准三权责任人：

---

6. 对话与 AI 项目助手

6.1 发起对话

中栏底部为输入区：输入消息，Enter 发送，Shift+Enter 换行。项目助手以 SSE 流式逐字输出回复。

下图为与项目助手的真实对话（dev 环境真实 PI Agent 执行）：

项目助手可以帮你：查询项目进展与风险、沉淀客户需求与技术指标、起草沟通话术与方案要点、推进方案论证与报价核算、编制或修订交付物文档。

6.2 附件上传

每轮对话最多可上传 5 个附件（图片、文档等），点击输入区附件图标选择文件：

6.3 意图计划确认卡片

当助手识别到需要多步骤执行的任务时，会在对话中给出执行计划（步骤清单与选项），你可以直接回复确认（如"好"或"1"）让助手按计划执行，或补充说明调整方向。多意图计划的确认/驳回卡片由特性开关控制（当前 dev 环境默认关闭，计划以消息内选项形式呈现，见 6.1 的真实对话截图）。

6.4 历史记录

对话支持历史搜索、日历定位、导出与 Digest 时间线回顾：

---

7. 文档工作台

右栏为交付物文档区，顶部分类 Tab 将文档分为三层：

分类	说明
工作流受控	工作流要求的正式交付物，走三责审批链，全生命周期留痕
项目共享	项目成员共享的非受控资料
个人私密	仅自己可见的草稿与笔记

7.1 块编辑

受控文档由「块」组成。双击任意段落进入就地编辑；鼠标右键可唤出快捷菜单（编辑、批注、复制、插块）：

编辑租约锁：同一文档同一时间仅一人持有编辑租约，避免冲突；他人打开时显示锁定状态。审核中/批准中的文档正文锁定，不可编辑。

7.2 版本历史与对比

文档工具栏可打开版本历史抽屉，查看每次修订版本，支持两版本对比（人工修改以琥珀底+下划线标出，相对最新基线）：

7.3 导出

交付物支持导出 DOCX / XLSX / Markdown（需要 doc:export 权限）：

7.4 文档可见性

默认可见性由工作流配置；有 doc:override_visibility 权限的角色（如研发总监）可对单个文档做可见性覆盖：

---

8. 审批全流程

系统中有四套审批机制，本章逐一说明。

8.1 文档三责审批（核心）

受控文档生命周期：

编制中(drafting) → 审核中(reviewing) → 批准中(approving) → 已批准(approved)
        ↑                ↓ 驳回
        └──── 退回编制 ────┘

第 1 步：编制人认领文档。 编制人打开受控文档并首次保存正文后，系统自动完成认领（治理操作条显示「编制中 · 已被编制人认领」），获得该文档的编制权：

第 2 步：编制并提交送审。 编制完成后点击「提交送审（流转至审核人）」，文档进入「审核中」，正文锁定：

第 3 步：审核人审核。 审核人在自己的队列中看到待审核文档，可「审核通过（送呈批准人）」或「驳回退回编制」（驳回需说明理由）：

第 4 步：批准人终审。 批准人执行「终审批准生效」；批准后文档到达 approved 终态并自动入标杆库。批准人驳回时必须填写理由，可指定回退到编制或审核环节：

三责分离守卫：只有编制人可改正文；审核人/批准人不可编辑；送审只能由编制人发起。试点环境支持「编制人兼任」同人三签模式（同一人员依次完成三签）。

8.2 阶段门禁推进

当前阶段所有「必需且受审批管理」的文档到达已批准后，阶段门禁就绪，顶部出现推进 Banner：

只有项目创建人可以点击「确认推进」进入下一阶段；门禁未就绪时按钮不可用并列出阻塞项（哪些必需文档未批准）：

8.3 修改建议审批

非编制人员对受控文档可发起「修改建议」（propose），由责任人确认（decide）后合入，全程留痕，不破坏三责分离。

8.4 注册审批

面向管理员，见 4.2。普通用户视角：注册后等待审核，审核通过前登录会收到「等待管理员审核」提示。

---

9. 角色权限速查与典型动线

9.1 权限速查表

权限点	ADMIN	DIRECTOR	TECH_LEAD	ENGINEER	GUEST
立项 project:create	✓	✓	✓	—	—
变更责任人 project:assign_lead	✓	✓	✓	—	—
系统管理 system:manage	✓	—	—	—	—
可见性配置 workflow:config_visibility	✓	✓	—	—	—
可见性覆盖 doc:override_visibility	✓	✓	✓	—	—
导出 doc:export	✓	✓	✓	✓	✓
查阅全部 workflow:view_all	✓	✓	✓	✓	—

以管理台「RBAC 角色权限」矩阵实时数据为准；自定义角色权限由管理员配置。

9.2 典型角色的一天

系统管理员：登录 → 管理台总览看运行状态 → 注册审批中心处理新注册 → 为新员工开通账号并指派角色 → 按需调整特性开关。

研发总监 / 技术主管（项目创建人）：立项 → 配置成员职责 → 与项目助手对话推进需求 → 关注待批准队列 → 终审批准文档 → 阶段门禁就绪后确认推进。

编制人：在「我的项目权限」看待我编制清单 → 认领文档 → 块编辑编制内容 → 提交送审 → 如被驳回按意见修改再送审。

审核人：看待我审核队列 → 审阅送审文档（可批注/提修改建议）→ 通过送呈批准人，或驳回退回编制。

外部审计/访客：只读查阅被授权的交付物 → 导出留存。

---

10. 常见问题 FAQ

Q1：登录提示「账号正在等待管理员审核中」？ 自主注册的账号需要管理员在「注册审批中心」核准。请联系系统管理员。

Q2：忘记密码怎么办？ 联系管理员在「账号列表」中「重置初始密码」，之后用初始密码登录并按提示强制改密。

Q3：登录后看不到管理台入口？ 管理台仅系统管理员可见。其他角色访问会被拦截并退回工作台。

Q4：为什么不能编辑某份受控文档？ 可能原因：你不是该文档编制人；文档处于审核中/批准中（正文锁定）；他人持有编辑租约；文档已批准归档（终态只读）。

Q5：「确认推进」按钮不可用？ 阶段门禁未就绪：本阶段还有必需文档未批准。Banner 上会列出阻塞文档清单，先完成其审批链。另外只有项目创建人能推进阶段。

Q6：对话中助手没有推荐案例？ 知识库可能离线。请管理员到「知识库连接」分组检查共享知识库状态。

Q7：附件传不上去？ 每轮对话最多 5 个附件，超出需分轮发送；另请确认文件类型受支持。

Q8：注册 Tab 不见了？ 管理员在「准入策略」中关闭了自主注册。请联系管理员直接开通账号。

---

本说明书基于 dev 环境（schema v52）真实操作截图编写。界面与流程以实际环境为准。