门诊 HIS 智能助手 CaiZongyuan/DSH-AGUI-demo

安康 HIS + DSH Agent 示例项目

这是一个可直接运行的门诊 HIS 与 Agent 集成教程。项目同时展示完整的医生工作流，以及如何通过 CopilotKit、AG-UI 和 dsh-ag-ui 将 DeepSeek Harness Agent 安全地嵌入 React 应用。

本项目仅用于开发演示和技术验证。所有患者、病历、诊断、检查和处方数据均为虚构内容，不可直接用于真实医疗业务、诊疗决策或生产医疗设备。

产品预览

9 秒流程视频

观看 9 秒智能助手演示

点击海报打开 WebM 视频。视频为 4 倍速，中文字幕依次说明进入当前接诊、加载页面上下文、调用结构化页面工具，以及将结果写入未保存病历草稿的过程。

今日总览

今日总览、当前接诊和候诊队列

桌面与移动助手

桌面端：助手调用受约束工具填写现病史和体格检查移动端：单列对话与完整工具结果

你可以在这个示例中看到什么

HIS 业务

- 今日总览、患者队列、搜索和状态筛选。
- 患者纵向病历、生命体征、诊疗时间线、检验结果和用药记录。
- Encounter 驱动的问诊工作台：病历、诊断、检查申请、报告、处方和复诊嘱托。
- 病历草稿保存、检查开具、报告回传、处方开具、文书签署和结束接诊的独立生命周期。
- 服务端校验正式临床动作，保存草稿不会自动签署，也不会自动完成 Encounter。
- 8 位确定性虚构种子患者，其中多位候诊患者可以开始新的问诊流程。

Agent 能力

- 在总览、患者详情和问诊工作台中打开同一个 HIS 助手入口。
- 获取当前页面完整的结构化业务快照，包括尚未保存的病历草稿。
- 流式显示 DSH 回复，保留按业务对象隔离的 thread history。
- 跳转页面、筛选患者、切换页签、填写病历、编辑结构化诊断和保存草稿。
- 发起检查、处方、签署和完诊流程，但正式动作必须由用户在对话框中确认。
- 浏览器从不接触 Gateway bearer secret，也不能自行声明可信 tenant/user identity。

整体架构

这个项目不使用 Vercel AI SDK。CopilotKit 负责 React 聊天界面、Agent discovery、消息状态、流式渲染和前端 Tool 调用；AG-UI 是 CopilotKit Runtime 与 DSH Gateway 之间的协议。

React 19 + CopilotChat (:5173)
-> /api/copilotkit
-> Vite dev proxy

Hono + CopilotRuntime v2 (:8900)
-> server-side HttpAgent
-> 注入 Gateway bearer、tenantId 和 userId

private dsh-ag-ui Gateway (:3080/ag-ui)
-> AG-UI request / thread / Tool validation
-> DSH Agent 与 Session binding -> AG-UI SSE events

DeepSeek Harness
-> 已配置的 provider / model -> openai / gpt-5.6-luna（本项目验证配置）

浏览器只请求同源的 /api/copilotkit/。真正的 Gateway 地址、Bearer Token 和可信身份头只存在于 Hono 服务端。

DSH React Surface

仓库包含 @ankang/dsh-his Adapter，可将完整 HIS 作为 dsh-react-surface 应用运行在 DSH Web 内。总览、患者详情、问诊工作台、Dialog、Select、Memory Router 和 Query Client 都与独立 Vite 应用共享；Adapter 使用独立的 /his-api Host 代理和 ShadowRoot 样式作用域，但不会把 CopilotKit bundle 带进 DSH Client。

桌面端 workspace 布局保留 DSH 左侧栏，把 HIS 放在中央，并保留右侧原生 DSH 会话。Surface 打开后，当前原生 DSH Session 才会获得 HIS 的上下文读取、导航、队列筛选、问诊页签、草稿编辑、草稿保存和正式动作准备 Tools；关闭 Surface、切换 Session 或切换业务 scope 会撤销旧租约。正式临床动作仍然只打开人工确认流程，Hono 会在确认后重新校验数据库状态。独立 Vite 模式继续使用 CopilotKit + AG-UI Adapter。

先在相邻的 dsh-react-surface 仓库构建并安装通用 runtime，再从本仓库构建 Adapter：

D:\Projects\Frontend\dsh-react-surface
bun run build
dsh.cmd plugin --profile web add ./packages/runtime

D:\Projects\Frontend\dsh-ag-ui
pnpm build
dsh.cmd plugin --profile web add .

D:\Projects\Frontend\his-agent-ui
bun run --cwd packages/dsh-his build
dsh.cmd plugin --profile web add ./packages/dsh-his
bun run dev:server

另一个终端 dsh.cmd web 打开 http://127.0.0.1:3080，从 DSH 侧栏选择「安康 HIS」。浏览器通过 DSH 的 /his-api/ 发起请求，落到固定的 loopback Hono upstream；这个代理会限制请求体大小，并保留 HIS 的 { data } / { error } envelope，不会记录完整患者 payload。

已验证版本

以下组合于 2026-08-24 验证通过：

| 组件 | 版本 |
| Bun | 1.4.0 |
| Node.js | 24.x |
| DeepSeek Harness | 0.1.1-rc.2 |
| dsh-ag-ui | 0.1.0，源码 commit 0247853 |
| CopilotKit | 1.69.0 |
| CopilotKit 使用的 AG-UI | 0.0.57 |
| dsh-ag-ui 使用的 AG-UI | 0.0.58 |
| React / Vite | React 19 / Vite 8 |

0.0.57 与 0.0.58 位于 HTTP 协议两端，并不共享运行时类型。本项目通过文本流、状态快照、Tool events、Tool continuation 和取消请求测试确认其 wire compatibility，因此没有使用依赖 override 强行统一版本。

从零运行项目

运行时需要两个长期保持的终端：

1. 终端 A：DSH Web 与 dsh-ag-ui Gateway，端口 3080。
2. 终端 B：Hono 与 Vite，端口 8900 和 5173。

1. 准备基础环境

需要安装：

- Node.js ^22.19.0 或 >=24.0.0。
- Bun 1.4.0 或更高版本。
- Git。
- 一个可以在 DSH 中使用的模型 provider 和 API key。

检查环境：

node --version
npm --version
bun --version
git --version

2. 全局安装 DSH

推荐固定与本项目验证一致的版本：

npm install --global @deepseek-ai/dsh@0.1.1-rc.2
dsh --version

预期版本：

0.1.1-rc.2

不想全局安装时也可以一次性运行：

npx @deepseek-ai/dsh@0.1.1-rc.2 web

不要使用 npx -g @deepseek-ai/dsh web。-g 属于 npm 全局安装语义，不是这里需要的 npx 调用方式。

3. 第一次启动 DSH 并配置模型

dsh web

打开 http://127.0.0.1:3080，在 DSH 设置中添加 provider、API key 和模型。先在 DSH 自带页面完成一次普通聊天，确认模型本身可用。

本项目验证时使用：

provider: openai
model: gpt-5.6-luna

这里必须填写 DSH 实际注册的 provider/model ID，而不是展示名称。你也可以换成自己的模型，只需在后续环境变量中保持一致。

普通聊天成功后，回到终端按 Ctrl+C，准备安装插件。

4. 安装 dsh-ag-ui 插件

从 npm 安装：

dsh plugin --profile web add dsh-ag-ui

从 GitHub 安装当前源码：

dsh plugin --profile web add github:CaiZongyuan/dsh-ag-ui

如果希望精确复现本项目验证的 commit，可以先克隆并构建：

git clone https://github.com/CaiZongyuan/dsh-ag-ui.git
Set-Location dsh-ag-ui
git checkout 0247853c179c5e02f32fc0cb436d1980eef0867c
corepack enable
corepack pnpm install --frozen-lockfile
corepack pnpm build
dsh plugin --profile web add .

检查 Web Profile 中的插件：

dsh plugin --profile web list --depth 0

应当能看到 dsh-ag-ui。插件安装后不会立即监听 Gateway；缺少 provider、model 或 secret 时，bundle 会保持 dormant。

5. 生成 Gateway secret

在 PowerShell 中生成 32 字节随机 secret：

$GatewaySecret = node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))"
$GatewaySecret

不要把这个值提交到 Git。接下来 DSH 和 Hono 必须使用完全相同的值。

6. 启动 DSH Gateway

在终端 A 中设置当前进程环境变量并启动 DSH：

$env:DSH_AG_UI_PROVIDER = 'openai'
$env:DSH_AG_UI_MODEL = 'gpt-5.6-luna'
$env:DSH_AG_UI_SHARED_SECRET = $GatewaySecret
$env:DSH_AG_UI_PATH = '/ag-ui'

dsh web
保持终端 A 运行。DSH Web 与 private Gateway 现在共用 127.0.0.1:3080，Gateway 地址为：

http://127.0.0.1:3080/ag-ui

直接发送未认证请求应返回 401，这是正常的安全行为：

Invoke-WebRequest
-Method Post
-Uri 'http://127.0.0.1:3080/ag-ui'
-ContentType 'application/json'
-Body '{}'

7. 配置 HIS 服务端

回到本仓库，在终端 B 中安装依赖并创建本地环境文件：

bun install
Copy-Item server/.env.example server/.env
notepad server/.env

填写：

DSH_AG_UI_GATEWAY_URL=http://127.0.0.1:3080/ag-ui
DSH_AG_UI_SHARED_SECRET=<与终端 A 完全相同的 GatewaySecret>
COPILOTKIT_TELEMETRY_DISABLED=true

server/.env 已被 .gitignore 排除。仓库只提交不含 secret 的 server/.env.example。

8. 启动 HIS 前后端

在仓库根目录执行：

bun run dev

启动后访问：

| 服务 | 地址 |
| React / Vite | http://127.0.0.1:5173 |
| Hono health | http://127.0.0.1:8900/health |
| DSH Web | http://127.0.0.1:3080 |
| private Gateway | http://127.0.0.1:3080/ag-ui |

后端首次启动会执行 server/drizzle/ 中的迁移，并在 server/data/his.db 中写入幂等虚构种子数据。

Bash 等价配置

Linux、macOS 或 WSL 可以使用：

export DSH_AG_UI_PROVIDER='openai'
export DSH_AG_UI_MODEL='gpt-5.6-luna'
export DSH_AG_UI_SHARED_SECRET="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("hex"))')"
export DSH_AG_UI_PATH='/ag-ui'
dsh web

在另一个终端中，把相同 secret 写入 server/.env，然后运行 bun install && bun run dev。

如何体验 HIS 与 Agent

多患者工作流

1. 打开今日总览，队列表格会显示全部虚构患者。
2. 候诊中 患者显示“接诊”，可以进入工作台后点击“开始接诊”。
3. 系统同一时间只允许一个 in_consultation Encounter。开始下一位患者前，需要先完成当前 Encounter。
4. 已完诊患者只能查看病历，不会再显示为活动问诊。
5. 也可以使用右上角“新建患者”创建一条新的候诊记录。

打开助手

- 总览和患者详情页：使用顶部“助手”按钮。
- 问诊工作台：使用患者栏右侧“助手”按钮。
- 桌面端显示右侧面板，移动端切换为单列助手视图。

推荐测试提示词

先测试上下文读取：

请概括当前页面的患者、Encounter 状态、异常生命体征和下一步待办。

测试页面导航：

请打开当前患者的完整病历。

测试填写病历草稿：

请调用工具填写现病史和体格检查，但不要保存。
现病史：患者2天前出现咽痛，伴低热，无咳嗽及呼吸困难。
体格检查：咽部充血，双侧扁桃体I度肿大。

测试结构化诊断：

请把诊断草稿替换为急性咽炎，ICD 编码 J02.9，确诊，设为主诊断。不要签署。

测试草稿持久化：

请保存当前病历草稿。不要签署病历，也不要结束接诊。

测试人工确认：

请发起签署病历，但不要替我确认。

最后一个提示只会打开确认对话框。真正的签署仍需用户点击“确认签署”，随后服务端会重新校验全部前置条件。

Agent 如何获得页面信息

每个已加载路由通过 useRegisterAssistantPage() 注册一份可序列化快照：

| 页面 | 发送给 Agent 的内容 |
| 今日总览 | 搜索条件、统计指标、当前接诊、全部队列、排班、提醒和可用控制 |
| 患者详情 | 患者档案、活动 Encounter、生命体征、诊断、时间线、检验和用药 |
| 问诊工作台 | 完整 Workspace、患者、生命体征、病历、检查、报告、处方、安全检查、完诊条件和未保存草稿 |

关键代码：

- app/src/components/assistant-page-context.tsx：页面注册表与 Agent action contract。
- app/src/routes/index.tsx：总览上下文与队列筛选 action。
- app/src/routes/patients.$patientId.tsx：患者详情上下文。
- app/src/routes/consultations.$visitId.tsx：Encounter 上下文、表单 state、Mutation 和确认流程。
- app/src/components/assistant-runtime.tsx：CopilotKit Provider、Chat 和 frontend Tools。

当前数据均为虚构示例，因此教程发送完整页面快照。接入真实 HIS 时应根据最小必要原则删减身份信息，并在服务端做患者、租户和角色授权。

智能体如何操作页面

智能体不通过 CSS selector 模拟鼠标，也不会随意遍历 DOM。页面向它注册了 7 个结构化 frontend Tools：

| Tool | 能力 | 是否直接产生正式临床动作 |
| navigate_his | 跳转总览、患者详情或问诊工作台 | 否 |
| filter_patient_queue | 修改总览搜索词和状态筛选 | 否 |
| select_encounter_section | 切换病历、诊断、检查、报告、处方或嘱托页签 | 否 |
| update_clinical_document_draft | 填写病历文本字段 | 否，仅本地草稿 |
| replace_clinical_diagnoses | 替换结构化诊断草稿 | 否，仅本地草稿 |
| save_clinical_document_draft | 校验并持久化草稿版本 | 否，不签署、不完诊 |
| prepare_encounter_action | 发起接诊、检查、报告、处方、签署或完诊 | 否，只打开人工确认流程 |

Tool handler 复用与页面按钮相同的 React state、TanStack Mutation 和 API，不存在一套绕过业务规则的智能体专用写接口。

为什么正式动作必须确认

- 检查开具、处方开具、文书签署和完诊会改变独立业务资源的生命周期。
- 智能体只能请求动作，不能声明它已经获得医生授权。
- 对话框确认后仍调用原有 API。
- Hono 会再次读取数据库并验证当前 Encounter 状态及全部前置条件。

这使「模型建议」「编辑草稿」「正式临床动作」保持分离。

一次工具调用发生了什么

1. 模型在 DSH 中选择 frontend Tool
2. dsh-ag-ui 发出 TOOL_CALL_START / ARGS / END
3. CopilotKit 在浏览器执行已注册 handler
4. handler 更新页面或调用 HIS API
5. CopilotKit 追加 ToolMessage 并发起 continuation run
6. dsh-ag-ui resolve 原 DSH Tool Promise
7. 同一个 DSH turn 继续生成最终回复

当前 dsh-ag-ui V1 每个 DSH step 允许一个 frontend Tool call。复杂任务可能需要模型经过多个 step，或者拆成多条清晰提示词。

DSH Tool Schema 兼容注意事项

@deepseek-ai/dsh-tools@0.1.1-rc.2 只接受保守的 object-rooted JSON Schema 子集，主要包括：

type
properties
required
additionalProperties
items
enum
const
oneOf
description 等 annotation

CopilotKit 从 Zod 生成 frontend Tool schema 时，不要在发送给 DSH 的 schema 中使用当前版本不支持的关键词，例如：

minLength / maxLength
minItems / maxItems
default

业务长度和必填校验仍可在浏览器 handler 内使用完整 Zod schema，并由服务端 HTTP boundary 再校验一次。本项目的 Tool schema 与业务校验 schema 因此是两层：前者负责 DSH 协议兼容，后者负责业务正确性。

此外，本项目所有 DSH frontend Tools 都设置 followUp: true。dsh-ag-ui 会暂停 DSH Tool Promise 等待浏览器 ToolMessage；缺少 continuation 会让 thread 保持 parked。可预期的 handler 失败会被编码为普通 Tool result，避免 CopilotKit 1.69 的 tool_handler_failed 留下未释放 thread。

Hono 与安全边界

服务端创建 CopilotRuntime，并只在服务端实例化 HttpAgent：

/api/copilotkit/*
-> CopilotRuntime
-> HttpAgent(url = DSH_AG_UI_GATEWAY_URL)
-> Authorization: Bearer <server-only secret>
-> x-dsh-tenant-id: local-demo
-> x-dsh-user-id: clinician-demo

当前 tenant/user 是本地演示身份。生产化时必须替换为：

- 服务端登录 session。
- 租户成员关系和角色权限。
- 当前患者和 Encounter 的资源授权。
- CSRF、rate limit、审计与结构化脱敏日志。

浏览器提交的 context、Tool args、patientId、tenantId 或 userId 都不是授权证据。

项目还保留 /api/agent 低层 AG-UI BFF，用于兼容和独立协议测试；当前 CopilotChat 主链路使用 /api/copilotkit。

项目结构

.
├─ AGENTS.md
├─ app/ # React + Vite 前端 │ └─ src/ │ ├─ components/ │ │ ├─ assistant-page-context.tsx │ │ ├─ assistant-panel.tsx │ │ └─ assistant-runtime.tsx │ ├─ routes/ # TanStack Router 文件路由 │ ├─ lib/ # API client │ └─ store/ # Zustand 瞬时 UI state ├─ server/ # Hono API 与 CopilotRuntime │ ├─ drizzle/ # SQLite migrations │ └─ src/ │ ├─ agent/ │ │ ├─ copilot-runtime.ts │ │ └─ gateway.ts │ ├─ db/ # Schema、连接和确定性种子 │ └─ app.ts # HIS API 与工作流规则 ├─ packages/contracts/ # 前后端共享 Zod contracts ├─ patches/eventsource@3.0.7.patch # Bun/CopilotKit 模块加载兼容补丁 ├─ docs/ │ ├─ DSH-AG-UI-tutorial.md # 不依赖 CopilotKit 的底层 AG-UI 教程 │ ├─ research/ # 设计与技术调研 │ └─ ui/ # 原始视觉参考，不参与生产构建 └─ dogfood-output/ # 本地浏览器验收产物，Git 忽略

页面路由

| 路由 | 说明 |
| / | 今日总览和患者队列 |
| /patients/:patientId | 患者纵向病历 |
| /consultations/:visitId | Encounter 问诊工作台 |

URL 中保存搜索词、患者 ID 和 Encounter ID；主题、助手开关和弹窗等瞬时状态保存在 Zustand。

API

所有业务成功响应使用 { "data": ... }，失败响应使用 { "error": { "code", "message" } }。

| 方法 | 路径 | 说明 |
| GET | /health | 服务健康检查 |
| GET/POST | /api/copilotkit/* | CopilotKit Runtime discovery、run、connect 和 stop |
| POST | /api/agent | 低层 AG-UI BFF 兼容入口 |
| GET | /api/dashboard | 总览、队列查询和状态筛选 |
| POST | /api/patients | 新建患者与候诊记录 |
| GET | /api/patients/:id | 患者病历聚合数据 |
| GET | /api/visits/:id/workspace | 问诊 Workspace |
| POST | /api/visits/:id/start | 开始 Encounter |
| PATCH | /api/visits/:id/document | 按 expected version 保存草稿 |
| POST | /api/visits/:id/clinical-requests/issue | 开具检查 |
| POST | /api/visits/:id/clinical-requests/report | 演示环境同步报告 |
| POST | /api/visits/:id/prescriptions/issue | 开具处方 |
| POST | /api/visits/:id/document/sign | 签署病历 |
| POST | /api/visits/:id/complete | 完成并归档 Encounter |

常用命令

安装 monorepo 依赖并应用 Bun patch
bun install

同时启动 Hono 与 Vite
bun run dev

类型、ESLint 和 Prettier 检查
bun run check

Bun API 与 AG-UI compatibility tests
bun run test

前端生产构建
bun run build

Schema 修改后生成 Drizzle migration
bun run db:generate

手动执行 migration
bun run db:migrate

测试覆盖

当前自动化测试覆盖：

- 总览查询和队列筛选。
- 候诊患者拥有可编辑 Workspace，已完诊患者不会重新成为活动问诊。
- 无效 HTTP payload。
- 病历、检查、报告、处方、签署和完诊完整状态链。
- CopilotRuntime /info discovery。
- AG-UI 文本 SSE 与 STATE_SNAPSHOT。
- backend Tool events 与 frontend Tool continuation。
- 取消请求向 Gateway 传播。
- Gateway 边界校验与可信身份头注入。

真实浏览器验收还覆盖：

- DSH 实际流式聊天。
- Agent 填写病历、替换诊断、保存草稿。
- Agent 导航与队列筛选。
- Agent 发起签署但由用户取消，API 状态仍保持 draft。
- 1440x900 桌面与 390x844 移动布局。

常见问题

dsh 命令不存在

npm install --global @deepseek-ai/dsh@0.1.1-rc.2
npm config get prefix

确认 npm global bin 已进入 PATH，然后重新打开终端。

listen EACCES ... 127.0.0.1:3080

先检查端口占用和 Windows excluded port range：

Get-NetTCPConnection -LocalPort 3080 -ErrorAction SilentlyContinue
netsh interface ipv4 show excludedportrange protocol=tcp

停止占用进程，或者修改 DSH WebServer 端口，并同步修改 server/.env 中的 Gateway URL。不要同时运行两份监听同一端口的 DSH Web Profile。

DSH 可以打开，但 /ag-ui 返回 404

通常是插件处于 dormant：

- 检查 dsh plugin --profile web list --depth 0。
- 确认启动 DSH 的同一个终端存在 DSH_AG_UI_PROVIDER、DSH_AG_UI_MODEL 和 DSH_AG_UI_SHARED_SECRET。
- 确认 provider/model ID 与 DSH 设置页一致。
- 重新启动 dsh web。

Gateway 返回 401

未携带 Bearer Token 的直接请求返回 401 是预期行为。如果 Hono 转发也返回 401，说明终端 A 的 DSH_AG_UI_SHARED_SECRET 与 server/.env 不一致。

AGENT_EXECUTION_ERROR 在发送 Tools 后出现

检查 frontend Tool JSON Schema 是否超出 DSH Tools 当前支持子集。尤其不要把 Zod 的 minLength、maxLength、minItems、maxItems 或 default 发送到 Gateway。

AGENT_BUSY

这通常表示某个 frontend Tool 已由 DSH 调用，但浏览器没有续传 ToolMessage。确保 Tool 使用 followUp: true，并且 handler 将可预期错误返回为 Tool result，而不是让异常逃出 handler。开发过程中修改了不兼容 Tool 协议时，应升级 ASSISTANT_THREAD_NAMESPACE 或重启 DSH，避免重放旧失败 run。

Bun 启动 CopilotKit 时出现 EventSource 模块错误

根目录 package.json 已注册 patches/eventsource@3.0.7.patch。必须从根目录使用 bun install，不要只在 app/ 或 server/ 单独安装依赖。

DSH 回复仍像通用编码助手

检查用户 Web Profile 的 cordis.patch.yml 是否仍注入强制编码 workspace/persona。dsh-ag-ui 应使用面向当前应用上下文的 scoped conversational Agent。修改个人 Profile 前先备份，并避免把本机绝对路径或 secret 提交到本仓库。

当前限制

- DSH 与 dsh-ag-ui 仍处于 developer preview。
- Thread、run ledger、parked Tool 和 shared state 由 dsh-ag-ui 进程内保存，重启 Host 后不会完整恢复。
- 当前适配器尚未发送 reasoning events、STATE_DELTA、标准 AG-UI interrupts、multimodal 或 activity events。
- CopilotKit 完整聊天组件按需加载，但 lazy chunk 仍约为 1.7 MB。
- 当前演示身份是固定的 local-demo / clinician-demo，没有真实登录和租户授权。
- 当前应用只使用虚构患者数据。接入真实数据前必须完成隐私、审计、访问控制和临床安全评估。

延伸阅读

- docs/DSH-AG-UI-tutorial.md：从底层 HttpAgent 与 Hono BFF 理解 AG-UI，不依赖 CopilotKit UI。
- DeepSeek Harness
- dsh-ag-ui
- dsh-ag-ui 中文文档
- CopilotKit
- AG-UI
- Hono