【安心陪诊 Agent】Node.js 20 + Node.js 内置 http 模块 实战：Web Demo 与规则 Agent 架构

在陪诊产品中，最容易被误解的需求是“做一个能聊天的 Agent”。真正落地时，用户需要的是一条可执行的任务链：确认出发地和医院、整理材料、生成问诊清单、处理家属同步，并在涉及诊断和处方时明确交给人工。本文用一个 Web Demo 说明 Page、Node.js API 和规则 Agent 如何协作。

一、本文解决什么问题

本文聚焦“自然语言输入如何变成稳定任务卡片”。示例环境为 Node.js 20 及以上、Node.js 内置 http 模块、现代 Chromium 浏览器；前端通过结构化 code 判断页面状态，后端不输出诊断结论。

二、目录和启动方式

src/
  server.js
  routes/plan.js
  services/plan-service.js
  rules/safety-rule.js
  public/index.html
node --version
npm list express
npm run dev

先固定 Node.js 和 Express 版本，再启动本地服务。这样读者遇到请求体解析或路由行为差异时，可以先排除运行时版本问题。

三、接口协议：先定义状态再写页面

import express from "express";
const app = express();
app.use(express.json());

app.post("/api/plan", (req, res) => {
  const { start, hospital, visitTime } = req.body || {};
  if (!start || !hospital) {
    return res.status(400).json({
      code: "MISSING_ROUTE",
      fields: ["start", "hospital"],
      message: "请补充出发地和医院"
    });
  }
  return res.json({
    code: "OK",
    route: { start, hospital, visitTime: visitTime || "待确认" },
    tasks: ["材料清单", "问诊问题", "家属同步"]
  });
});

返回值使用 code、route 和 tasks 三个稳定字段。前端不需要猜测自然语言，也能对正常、缺字段和安全拦截分别渲染。

四、规则 Agent 的安全边界

const blocked = ["诊断", "处方", "剂量", "停药"];
function guard(text) {
  const hit = blocked.find((word) => String(text || "").includes(word));
  return hit ? { code: "SAFE_GUARD", hit, next: "人工确认" } : { code: "OK" };
}

规则只负责发现风险并给出下一步，不输出病情判断。这个边界既能减少误导，也让测试用例有明确的预期。

五、前端如何消费返回值

async function submitPlan(form) {
  const response = await fetch("/api/plan", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(form)
  });
  const data = await response.json();
  if (data.code === "MISSING_ROUTE") return showFormError(data.message);
  if (data.code === "SAFE_GUARD") return showSafetyCard(data.next);
  return renderTaskCards(data.tasks);
}

页面只根据协议渲染状态：错误提示可修复，安全提示需要人工确认，成功状态展示任务卡片。网络失败时还要保留重试按钮和当前输入。

六、可复现请求和返回

curl -X POST http://localhost:5188/api/plan ^
  -H "Content-Type: application/json" ^
  -d "{"start":"杭州西湖文化广场","hospital":"浙江省人民医院","visitTime":"周三上午"}"

{ "code": "OK", "tasks": ["材料清单", "问诊问题", "家属同步"] }

七、验收清单

八、常见问题

九、总结

安心陪诊 Agent 的工程价值不在于“什么都能聊”，而在于把就医准备拆成可验证任务，并对医疗风险保持克制。固定版本、明确协议、保留异常路径和真实验收记录，才能让 Web Demo 具备迁移到 HarmonyOS ArkTS 的基础。

扩展验证：从 Web Demo 迁移到 HarmonyOS

Web Demo 的协议不应该和页面组件绑死。迁移到 HarmonyOS ArkTS 时，可以把 PlanResult、TaskItem 和 SafetyNotice 作为公共模型，页面只负责状态渲染，网络访问放在 Service，Preferences 只保存用户主动勾选的轻量设置。

interface TaskItem {
  title: string;
  detail: string;
  done: boolean;
}
interface PlanResult {
  code: "OK" | "MISSING_ROUTE" | "SAFE_GUARD";
  message?: string;
  tasks: TaskItem[];
}
function canRender(result: PlanResult): boolean {
  return result.code === "OK" && result.tasks.length > 0;
}

这样迁移时，Web 的返回值仍然可以驱动原生任务卡片；网络失败、空数据和安全拦截也能保持一致，不需要在每个页面重复判断字符串。

异常路径和重试策略

重试不能无限循环。前端最多自动重试一次，之后显示明确按钮；服务端记录请求耗时和错误码，但不记录不必要的病情细节和家属联系方式。

测试矩阵

const cases = [
  { name: "normal", body: { start: "杭州", hospital: "省人民医院" }, expect: "OK" },
  { name: "missing-hospital", body: { start: "杭州" }, expect: "MISSING_ROUTE" },
  { name: "medical-risk", body: { start: "杭州", hospital: "省人民医院", text: "如何调整剂量" }, expect: "SAFE_GUARD" }
];

测试名称直接对应接口返回码，验收人员可以先跑接口，再打开页面核对状态。这样问题能定位到协议、规则还是 UI，而不是只记录“按钮点过了”。

发布前复查

完整的陪诊 Agent 不是一个泛聊天框，而是一个可解释、可验证、可回退的任务系统。版本、协议、代码和测试记录彼此对应，文章才真正能帮助读者复现。

可运行接口：规则 Agent 如何接收、校验并返回任务

以下示例来自 Demo 的 Node.js 20 及以上 与 Node.js 内置 http 模块 服务层。它只把用户已经确认的陪诊事项整理为待办，不推断病情，也不生成诊疗建议。请求体在进入规则层前完成字段校验，便于本地复现。

import express from 'express';
const app = express();
app.use(express.json());

app.post('/api/escort-plan', (req, res) => {
  const { hospital, visitAt, need } = req.body ?? {};
  if (![hospital, visitAt, need].every((value) => typeof value === 'string' && value.trim())) {
    return res.status(400).json({ code: 'INVALID_ARGUMENT', message: 'hospital、visitAt、need 为必填文本' });
  }
  const tasks = [
    `提前确认 ${hospital} 的院区和到达时间`,
    `准备证件、既往检查资料和问题清单`,
    `在 ${visitAt} 前预留出行与签到时间`
  ];
  return res.json({ code: 'OK', version: 'demo-1.0.0', tasks, boundary: 'not-medical-diagnosis' });
});
app.listen(3000);

本地验证命令：node server.mjs 后执行 curl -X POST http://127.0.0.1:3000/api/escort-plan -H "Content-Type: application/json" -d "{\"hospital\":\"门诊楼\",\"visitAt\":\"09:00\",\"need\":\"协助取号\"}"。预期得到 200、三个待办和 not-medical-diagnosis 边界标记；缺失字段时返回 400。

完整接口契约：任务生成不是一句提示词

在 Demo 里，规则 Agent 的输出要先定义成稳定的数据协议，再交给页面渲染。否则同一个“帮我准备陪诊”的输入，今天可能返回字符串，明天变成数组，前端会不断增加临时判断。这里的协议只描述流程事项和展示状态，明确不携带病情判断、药品剂量或处方内容。

export type TaskStatus = 'todo' | 'done' | 'blocked';

export interface EscortTask {
  id: string;
  title: string;
  status: TaskStatus;
  source: 'rule';
}

export interface EscortPlanResponse {
  code: 'OK' | 'INVALID_ARGUMENT' | 'OUT_OF_SCOPE';
  message: string;
  tasks: EscortTask[];
  traceId: string;
}

export function toPlanResponse(input: { hospital: string; visitAt: string; need: string }): EscortPlanResponse {
  const traceId = crypto.randomUUID();
  if (![input.hospital, input.visitAt, input.need].every((value) => value.trim())) {
    return { code: 'INVALID_ARGUMENT', message: '请补全医院、时间和陪诊需求', tasks: [], traceId };
  }
  if (/处方|剂量|确诊|诊断/.test(input.need)) {
    return { code: 'OUT_OF_SCOPE', message: '该问题需要由医生或药师处理', tasks: [], traceId };
  }
  return {
    code: 'OK',
    message: '已生成就诊准备清单',
    traceId,
    tasks: [
      { id: 'arrival', title: `确认 ${input.hospital} 的院区与到达路线`, status: 'todo', source: 'rule' },
      { id: 'materials', title: '准备证件、病历和检查资料', status: 'todo', source: 'rule' },
      { id: 'time', title: `在 ${input.visitAt} 前预留签到时间`, status: 'todo', source: 'rule' }
    ]
  };
}

页面只根据 code 决定状态：OK 展示任务卡片，INVALID_ARGUMENT 高亮未完成字段，OUT_OF_SCOPE 显示医疗边界说明。这样 UI 不解析自然语言，也不会把错误信息伪装成成功结果。

HTTP 路由、超时与可观察性

服务端在 Node.js 20 及以上 和 Node.js 内置 http 模块 下运行。每次请求分配 traceId，日志只记录流程字段和结果码，不记录身份证号、病历图片或具体病情描述。前端超时后保留用户输入并允许再次提交。

app.post('/api/escort-plan', (req, res) => {
  const startedAt = Date.now();
  const result = toPlanResponse(req.body ?? {});
  console.info(JSON.stringify({
    event: 'escort_plan', traceId: result.traceId,
    code: result.code, durationMs: Date.now() - startedAt
  }));
  const status = result.code === 'OK' ? 200 : result.code === 'INVALID_ARGUMENT' ? 400 : 422;
  res.status(status).json(result);
});

app.use((error, _req, res, _next) => {
  console.error('unexpected_error', error?.message);
  res.status(500).json({ code: 'SERVER_ERROR', message: '服务暂不可用，请稍后重试', tasks: [] });
});

本地运行命令为 npm ci、npm run dev。使用 现代 Chromium 浏览器 打开页面后，在 Network 面板中可核对请求体、状态码和 traceId；调用失败时页面展示重试按钮而不是清空已填写的医院与时间。

从接口到页面的状态表

可复现的测试与验收记录

import assert from 'node:assert/strict';

const normal = toPlanResponse({ hospital: '门诊楼', visitAt: '09:00', need: '协助取号' });
assert.equal(normal.code, 'OK');
assert.equal(normal.tasks.length, 3);

const missing = toPlanResponse({ hospital: '', visitAt: '09:00', need: '协助取号' });
assert.equal(missing.code, 'INVALID_ARGUMENT');

const boundary = toPlanResponse({ hospital: '门诊楼', visitAt: '09:00', need: '这个药吃多少' });
assert.equal(boundary.code, 'OUT_OF_SCOPE');

执行 node --test test/escort-plan.test.js，三条断言应全部通过。最后再进行一轮人工验收：窄屏 360px、普通桌面 1280px、请求超时、重复点击提交、医疗边界输入。每一项都应有 loading、success、error 或 disabled 的可见状态。

前端状态机：防止重复提交与结果闪烁

Web Demo 的交互状态需要独立于接口返回管理。用户点击“生成陪诊清单”后，按钮先进入 loading；接口成功才进入 success；网络异常进入 error；在 loading 期间禁用再次点击。这样即使网络抖动，也不会出现两次请求覆盖同一组任务的情况。

const state = { phase: 'idle', error: '', plan: null };

function renderPlanState() {
  submitButton.disabled = state.phase === 'loading';
  submitButton.textContent = state.phase === 'loading' ? '正在生成...' : '生成陪诊清单';
  errorBox.hidden = state.phase !== 'error';
  errorBox.textContent = state.error;
  resultPanel.hidden = state.phase !== 'success';
}

async function submitPlan(payload) {
  if (state.phase === 'loading') return;
  state.phase = 'loading'; state.error = ''; renderPlanState();
  try {
    const response = await fetch('/api/escort-plan', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(payload) });
    const data = await response.json();
    if (!response.ok) throw new Error(data.message || '请求失败');
    state.plan = data; state.phase = 'success';
  } catch (error) {
    state.phase = 'error'; state.error = String(error.message || error);
  }
  renderPlanState();
}

可访问性也要在 Demo 中可见：错误区域使用 role="alert"，loading 状态使用 aria-busy="true"，任务勾选框必须有文字标签。键盘使用 Tab 可以依次到达医院、时间、需求、提交按钮和重试按钮，焦点不会落到被隐藏的结果面板上。

完成上述验证后，Demo 的价值不再只是“能跑起来”：它有明确输入、稳定接口、可见状态、异常兜底和可被他人复查的测试路径。这些内容也方便后续迁移到 HarmonyOS ArkUI 页面，由页面状态、服务层和本地记录共同承担任务闭环。

工程深度补充：从页面表现走到可复查实现

这一部分把 安心陪诊 Agent 的文章主题 【安心陪诊 Agent】Node.js 20 + Node.js 内置 http 模块 实战：Web Demo 与规则 Agent 架构 继续落到工程证据上。读者不只看到结论，还能看到输入、处理、输出、异常兜底和验收方式。

type AgentIntent = "plan" | "chat" | "summary";

interface AgentRequest {
  intent: AgentIntent;
  userText: string;
  safeMode: boolean;
}

function routeAgent(req: AgentRequest) {
  if (!req.userText.trim()) return { type: "empty", message: "请先补充就医需求" };
  if (req.safeMode && /诊断|剂量|处方/.test(req.userText)) {
    return { type: "guard", message: "仅提供就医准备建议，不替代医生判断" };
  }
  return { type: req.intent, message: "进入陪诊任务编排" };
}

这段代码的重点不是堆功能，而是把文章里的核心判断拆成稳定输入、明确输出和可解释的失败分支。读者复用时可以先保留接口形状，再替换成自己的业务字段。

实际提交前还需要做一次人工复查：标题是否和正文一致，封面是否能在列表页看清，代码是否和项目主题相关，图片是否能解释流程，结尾是否有可执行的验证清单。

源码复核与实测记录（2026-07-28）

复核范围：安心陪诊 Agent v1.0.0；运行要求来自 project/package.json 的 node >=20。服务端实际使用 Node.js 内置 node:http，不是 Express；前端使用原生 HTML、CSS 与 JavaScript ES Modules。本文不再使用源码无法证明的精确浏览器、TypeScript、Express 或 DevEco 版本。

主题对应证据：源码使用 Node.js 内置 http.createServer 提供静态资源、/api/context、/api/plan 与 /api/chat；package.json 没有 Express 依赖。

真实文件：project/server/index.js + project/tests/smoke-test.js

import http from "node:http";
import { buildCarePlan, buildChatReply } from "./agent.js";

export function createServer() {
  return http.createServer(async (req, res) => {
    const url = new URL(req.url || "/", "http://localhost");
    if (url.pathname === "/api/plan" && req.method === "POST") {
      sendJson(res, 200, buildCarePlan(await readBody(req)));
      return;
    }
    if (url.pathname === "/api/chat" && req.method === "POST") {
      sendJson(res, 200, buildChatReply(await readBody(req)));
      return;
    }
  });
}

复现步骤：进入 project 目录执行 npm test。测试会随机监听本机端口，依次请求三个接口，并断言心内科方向、慢病模式、华为手表提醒、家属摘要、安全提示和急症意图；全部断言通过后只输出 Smoke test passed.。这是一条已经执行的本地证据，不代表医院服务或医疗结果。

当前版本兼容性与主题验证（2026-07-28）

时效性基线：截至 2026 年 7 月 28 日，当前可运行交付物仍是安心陪诊 Agent v1.0.0 Web Demo，package.json 要求 Node.js >=20，服务端使用标准库 node:http，前端使用原生 HTML、CSS 与 JavaScript ES Modules。现代 Chromium 浏览器可用于本地复现，但仓库没有固定某一个浏览器小版本，所以本文不把单一 Chrome 版本写成兼容结论。

主题输入：GET /api/context、POST /api/plan、POST /api/chat 与错误方法。

可复查调用链：http.createServer -> URL 路由 -> readBody -> agent 纯函数 -> sendJson。

预期结果：三个接口返回结构化 JSON，静态首页可访问，Smoke test 全部断言通过。

失败与边界：未知接口返回 404，方法不匹配不进入业务分支，异常请求不伪造成功结果。

1. 本地复现顺序

复现时先进入 project 目录执行 npm test。脚本创建本机随机端口，依次请求上下文、计划与聊天接口，并检查科室方向、慢病模式、提醒、家属摘要、安全提示和急症意图。只有控制台输出 Smoke test passed. 才能记录为自动化回归通过；某个断言失败时，应保留首个失败项，不能只截取最后一行日志。

cd project
npm test
# 通过标准：Smoke test passed.

# 需要人工查看页面时再启动本地服务
npm start
# 浏览器打开终端输出的本机地址，不使用真实患者资料

页面验证使用演示资料，重点检查表单能否提交、计划是否渲染、对话能否返回、错误是否可读和手机宽度下是否仍可操作。当前测试不等于临床验证，也不证明真实医院流程、诊断准确率或商业需求已经成立。

2. 兼容性矩阵

3. 从 Web 数据契约迁移到 HarmonyOS 5.0+

迁移时先冻结 profile、department、timeline、questions、reminders 与 familyBrief 的字段，再定义严格 ArkTS 接口。页面只持有输入草稿、加载、错误和内容状态；规则判断放在 Service，Preferences 或 RDB 由 Repository 管理。这样能避免把 JavaScript 动态对象直接搬进 ArkUI 页面后产生大量可空字段和隐式类型错误。

interface CarePlan {
  profile: PatientProfile
  department: DepartmentSuggestion
  timeline: CareStep[]
  questions: DoctorQuestion[]
  reminders: CareReminder[]
  familyBrief: string
}

type PageState = 'loading' | 'empty' | 'error' | 'content'

轻量开关、引导状态和用户偏好可以评估 Preferences；结构化计划、查询、统计和需要迁移的历史记录更适合 RDB。医疗相关字段遵循最小化原则，默认本地处理；如果未来增加账号、云同步、语音、小艺或跨设备流转，必须重新设计授权、删除、隐私说明、服务端边界和审核材料，不能从当前 Web Demo 自动推导。

4. 主题专项检查表

性能记录至少观察接口响应时间、连续提交后的事件处理、长文本渲染和手机宽度布局。当前规则函数是本地同步计算，若以后接入模型或远端服务，还要增加超时、取消、重试、限流、离线提示与服务降级；这些都属于新增能力，不能在当前结论中提前写成完成。

5. 故障注入与证据回读

只验证成功输入无法证明流程稳定。第一组故障注入针对 HTTP 边界：向 /api/plan 发送空对象、缺少字段、额外字段和无效 JSON，向 /api/chat 发送空消息与超长消息，再访问未知路径。服务应返回可解释状态，不因一次请求导致进程退出；未知路径必须保持 404 语义，不能被静态首页兜底成看似成功的页面。

第二组故障注入针对规则边界：把普通慢病描述与“胸痛、呼吸困难、意识不清”等急症信号分别输入，确认急症判断先于普通科室建议。再使用相近但不属于急症的描述，观察是否出现过度匹配。测试记录要保留输入类别、命中的规则、响应中的 intent 或 urgency 和安全提示，不保存真实患者姓名、联系方式与病历。

第三组故障注入针对前端状态：在请求进行中重复点击、关闭本地服务后提交、返回非 JSON 响应、缩小到手机宽度、放大系统字体并刷新页面。通过标准是加载状态不会永久卡住，错误消息可见，旧结果不会冒充本次成功，按钮和输入仍可到达。若未来迁移 ArkUI，应显式维护 loading、empty、error 与 content，不要只用一个布尔值覆盖所有页面状态。

证据回读发生在修改之后。服务端文章重新读取 server/index.js 与 server/agent.js，确认方法名、接口路径和字段仍存在；前端文章重新读取 public/app.js 与 public/styles.css；测试文章重新执行 npm test。如果源码已经变化，文章应更新为新的快照，而不是为了保留旧结论去修改代码或虚构兼容层。

HarmonyOS 迁移阶段还要增加构建与设备证据：DevEco 工程的 build-profile.json5、module.json5、目标 SDK、设备类型和权限用途必须一致；执行仓库实际提供的 Hvigor 任务，记录第一条编译错误；有签名候选包后再做安装、启动、核心流程、返回和卸载。没有执行这些步骤时，只能写“设计方案”或“待验证”，不能写“已适配”或“已上架”。

对医疗陪诊主题而言，功能正确之外还有可逆性要求。用户应能修改或清除本地资料，提醒可以关闭，家属摘要应由用户主动生成或分享，急症提示必须引导线下求助。未来增加云端能力时，要补充传输、存储位置、删除、账号退出和隐私授权；当前本地 Demo 没有这些能力，所以文章不会提前承诺云同步、跨设备数据或医疗机构接入。

维护阶段建议为每个接口保存一份最小请求与响应样例，但样例只使用虚构人物和非敏感症状。字段新增时先更新纯函数、Smoke test 和前端渲染，再同步文章中的数据结构；字段删除时检查旧页面是否仍访问它。通过这种契约式回归，可以把“页面看起来没变”转换为可执行断言，也能在迁移 ArkTS 严格类型时尽早发现可空字段、枚举值和默认值不一致。

每次修改完成后还要重新从 CSDN 编辑端回读正文唯一标记、三张托管图片、摘要、标签和封面，避免接口保存成功但编辑器展示仍是旧版本。平台内容状态可能异步更新，因此修改记录与后台结果要分开保存：正文已升级只能写“已回读”，不能把尚未返回的结果写成已经达成。

发布前最后回读标题、摘要、五个相关标签、正文三张托管图片、AI 辅助声明和封面 URL。正文中的代码路径必须能在仓库定位，测试结果必须来自实际执行；未验证的设备、HarmonyOS 原生能力和临床效果统一写成待办或迁移边界。

AI 辅助声明：本文在人工复核真实源码、配置字段与验证记录的基础上，使用 AI 辅助整理结构和语言；功能边界、代码路径、版本信息与测试结论均以当前工程为准，未执行的真机、云测或平台操作不会写成已经通过。