Homecare Router (家庭照护多 Agent 路由协同系统)

面向慢性病长辈居家照护的跨端分布式多智能体路由与协同系统。系统基于华为云 AgentArts 平台与 LangGraph 编排引擎构建，核心主张在既定照护计划下实现最小披露多人协同、断网离线确定性执行与零自动医疗推断，彻底解决多子女照护沟通摩擦、长辈隐私过度泄露与网络抖动导致照护失效的工程痛点。

---

1. 项目背景与痛点

在多子女共同照料居家慢病长辈（如高血压、糖尿病、骨质疏松等）的典型家庭场景中，现有照护手段往往存在四大结构性矛盾：

1. 信息过载与沟通摩擦： 同城/本地常在子女（主要行动者）与异地子女（信息关注者）诉求不同。若对长辈用药与体征无差别群发，既打扰长辈与异地子女，又容易在关键突发事件（如连续漏服、跌倒、体征异常）时造成责任推诿或协同不及时。
2. 中心化隐私过度泄露： 传统云端健康助理要求将长辈的全部敏感健康隐私（具体药名、剂量、按键反应时、绝对体征值）以明文形式上传并存储至云端。一旦泄露，极易导致定向医药推销、电信诈骗甚至歧视风险。
3. 网络脆弱性导致失联失效： 长辈居家环境常面临 WiFi 断开、老人外出离线或路由器偶发断电。若提醒逻辑与响应仲裁强依赖公网大模型，断网即意味着整个照护系统停摆。
4. 大模型医疗幻觉与安全合规边界： 大语言模型具备创造性但缺乏确定性，直接让 LLM 推断用药方案或调整剂量存在不可估量的医疗事故隐患。

系统的核心解决思路

• 分级最小披露（Need-to-Know）：云端仅掌握脱敏的技术调度事实；长辈端到端加密数据仅向被明确授权的子女开放；同城子女与异地子女按权限查看不同粒度的回执卡片。
• 离线优先契约执行（Offline-First Contract）：经人确认的照护计划提前编译为带有时效与防伪签名的契约，下发并固化在家庭边缘网关（HomeEdge）；断网期间由边缘状态机自主倒计时与打卡，恢复后双向回执对账。
• 零自动医疗推断：大模型仅负责多意图解析、多约束冲突协调（如就诊时间窗口与子女日程对齐）与自然语言人机交互，所有医疗类动作严格依赖医生与监护人签署的既定计划。

---

2. 核心架构设计

系统采用四层分布式拓扑：云端中枢（AgentArts）、公网零知识中转（Relay）、家庭边缘网关（HomeEdge Hub）与跨端轻量人机界面（PWA）。

flowchart TB
    subgraph Cloud["云端中枢 (Huawei Cloud AgentArts & LangGraph Runtime)"]
        A[外部自然语言意图 / 问询] --> B[Intent Classifier & Extractor]
        B --> C{Guardian 安全护栏}
        C -- 违规出域/越权 --- D[Fallback / 安全拦截]
        C -- 校验通过 --- E[Placement Solver 确定性放置求解器]
        E --> F[LangGraph 13 节点协同编排图]
        F --> G[Two-tier Approval 两层审批流]
        F --> H[Ledger 对账与审计账本]
    end

    subgraph RelayLayer["公网安全中转 (Relay Service - Envelope Only)"]
        R1[租约信箱 Lease Queue]
        R2[ED25519 签名与时间戳防重放校验]
        R3[联合租约分发: Household / Event / Recipient]
    end

    subgraph Edge["家庭边缘网关 (HomeEdge Hub - Local Daemon)"]
        H1[Local SQLite Store]
        H2[Contract Verifier 契约验签器]
        H3[Deterministic Scheduler 本地契约调度器]
        H4[Response FSM 响应状态机]
        H5[Egress Guard 七类禁出域硬闸门]
        H6[E2E Crypto X25519/ChaCha20 密文封包]
    end

    subgraph Terminals["跨端交互界面 (Multi-Device Frontends)"]
        T1["长辈触控大屏 / 平板 (大字 3-Button 极简打卡)"]
        T2["同城本地子女端 (行动指引 / 异常近端介入)"]
        T3["异地子女端 (趋势摘要 / 脱敏状态卡)"]
    end

    Cloud <-->|契约同步 / 离线对账回执| RelayLayer
    RelayLayer <-->|E2E 加密封包 / 联合拉取| Edge
    Edge <-->|局域网极简信令| T1
    RelayLayer <-->|端到端加密直达| T2
    RelayLayer <-->|端到端加密直达| T3

四层职责划分

1. 云端运行时 (runtime/)：
   • 托管于华为云 AgentArts 平台（ARM64 容器）。
   • 运行 13 节点的 LangGraph 状态图与确定性约束求解器，负责跨主体意图理解、时隙协调与双层人工确认门禁。
2. 安全中转信箱 (relay/)：
   • 采用零知识设计，仅处理带时间戳的加密信封（Envelope-Only），校验 ED25519 设备签名，防止重放攻击。
   • 维护 (household_id, event_id, recipient_id) 联合出队租约，确保离线期间消息不丢失、不乱序。
3. 边缘网关 (edge/homeedge/)：
   • 部署在家庭微型主机或常开软路由上，维护嵌入式 SQLite。
   • 本地调度器（APScheduler + 状态机）独立执行提醒，严格阻断任何敏感字段向外传输。
4. 多端触控前端 (web/ & pwa/)：
   • 长辈端提供 3-Button 极简响应交互（已服 / 稍后 / 身体不适）；
   • 子女端以 PWA 呈现，基于 ECDH 协商密钥在本地解密并渲染状态。

---

3. DEC-3 最小披露与七类禁出域硬红线

为了彻底保障家庭隐私，系统在架构上确立了 DEC-3 硬红线，由 edge/homeedge/egress_guard/ 模块在数据离开局域网前进行全量结构体反射与白名单字节级拦截。

七类严禁出域数据

字段类型	字段标识	禁出域原因与威胁模型
药品名称	med_name	泄露特定重大疾病或隐私病史，引发定向推销或歧视
用药剂量	dose	涉及病情严重程度分级，属于高价值医疗隐私
响应耗时	response_time	按键反应毫秒差可被推算长辈认知退化或运动失能程度
具体按键	button_choice	原始按键细节属于微观行为特征，易被建模反推作息
绝对测量值	measurement	原始血压（mmHg）、血糖（mmol/L）严禁在公网中转明文流转
私密备注	notes	包含长辈主观生活记录或私密就医记录
日历明文	calendar_text	包含家庭起居规律与真实地址轨迹

出域传输规范

• 端到端加密传输（E2E Encrypted）：上述数据在边缘网关完成采集后，必须通过 X25519 密钥交换及 ChaCha20-Poly1305 算法加密后打包，仅有持有授权私钥的指定子女端可解密。
• 云端可见数据（Cloud Metadata）：公网中转与云端 AgentArts 仅允许处理脱敏的事实控制元数据（如 contract_id、event_time、state: taken、action_type: medication_reminder）。

---

4. 端云协同与断网离线执行契约

家庭照护的可用性红线是即使光纤被拔掉或公网瘫痪，老人用药提醒绝不能漏。系统设计了离线优先的双向契约状态机：

sequenceDiagram
    autonumber
    participant Cloud as AgentArts 云端中枢
    participant Relay as 公网 Relay 队列
    participant Hub as 家庭 HomeEdge Hub
    participant Elder as 长辈平板/硬件
    participant Child as 子女手机 PWA

    Note over Cloud,Hub: 阶段一：计划发布与离线契约固化
    Cloud->>Cloud: 医生/监护人确认照护计划
    Cloud->>Relay: 签署 PlanContract (含有效窗与版本哈希)
    Relay->>Hub: 下发并持久化至本地 SQLite
    Hub->>Hub: 安装本地定时调度器任务

    Note over Hub,Elder: 阶段二：断网离线自主执行
    rect rgb(240, 240, 240)
        Note over Cloud,Hub: [公网断开 / 路由器离线]
        Hub->>Elder: 本地定时触发用药提醒
        Elder->>Hub: 点击 "已服药"
        Hub->>Hub: 响应状态机置位: taken<br/>写入本地 Outbox (pending_send)
    end

    Note over Cloud,Child: 阶段三：网络恢复与双向回执对账
    rect rgb(245, 250, 255)
        Note over Cloud,Hub: [公网恢复连接]
        Hub->>Relay: 批量推送执行回执 (Receipt Chain)
        Relay->>Cloud: 投递脱敏回执至 Ledger 账本节点
        Relay->>Child: 投递 E2E 密文通知至子女端
        Child->>Child: 本地私钥解密并更新照护日报
        Cloud->>Hub: 回执对账确认，标记 Outbox 为 confirmed
    end

契约模型关键字段

• contract_id 与 contract_version：单调递增版本号，防止旧计划覆盖新计划。
• valid_from 与 valid_until：严格有效期区间，过期自动降级并提醒人工续期。
• revoked_at：撤销戳标记，支持近端物理一键撤回。
• idempotency_key：幂等键，防止网络抖动导致的重复弹窗。

---

5. 项目目录结构

homecare-router/
├── runtime/                   # 云端核心大脑 (AgentArts / LangGraph Runtime)
│   ├── app.py                 # FastAPI 入口与 AgentArts 高代码适配器
│   ├── core/                  # 确定性放置求解器、状态定义与策略过滤规则
│   ├── graph/                 # LangGraph 13 节点主编排图与上下文流转
│   ├── guardian/              # Guardian 出入域安全防护门禁与白名单校验
│   ├── approval/              # Human-in-the-Loop 两层审批流管理
│   └── ledger/                # 状态审计账本与回执确认节点
├── edge/                      # 家庭边缘计算节点 (HomeEdge Hub)
│   └── homeedge/
│       ├── scheduler/         # 本地确定性定时调度器 (APScheduler 隔离)
│       ├── response_fsm/      # 3-State 本地响应状态机
│       ├── local_store/       # SQLite 离线存储与 Outbox 队列
│       ├── e2e_crypto/        # X25519 ECDH / ED25519 签名与配对协议
│       ├── egress_guard/      # DEC-3 七类禁出域硬红线物理闸门
│       └── relay_client/      # 安全出站代理与离线断网自愈逻辑
├── relay/                     # 公网零知识中转信箱服务 (Relay)
│   ├── app.py                 # 中转服务 API 入口
│   ├── auth.py                # 设备签名校验与时间窗防重放中间件
│   ├── queue.py               # 多主体联合出队租约队列
│   └── ledger.py              # 信封投递审计记录
├── platform/                  # 华为云平台集成与联调工具
│   ├── Dockerfile.agentarts   # ARM64 标准容器构建描述
│   ├── controller_config.yaml # AgentArts 纳管配置
│   ├── probe_maas.py          # 华为云 MaaS 大模型服务实机探针
│   └── push_arm64_image_to_swr.py # SWR 镜像构建推送脚本
├── mcp_servers/               # MCP 协议标准工具服务
│   └── cloud_slots_mcp/       # 门诊排班与号源插槽查询工具
├── pwa/                       # 子女端渐进式 Web 应用后端服务
├── web/                       # 可视化交互控制台与全景模拟服务
│   ├── app.py                 # 多端演示服务器入口
│   ├── index.html             # 7-View 桌面全景控制台
│   └── mobile.html            # 移动端三合一触控模拟界面
├── tests/                     # 自动化测试与 Oracle 断言测试套件
│   ├── test_oracle_core.py    # Core 路由与求解器不变性测试 (142 项)
│   ├── test_oracle_hub.py     # Hub 边缘契约与调度不变性测试 (206 项)
│   ├── test_oracle_relay.py   # Relay 加密与防重放不变性测试 (95 项)
│   ├── test_graph_*.py        # LangGraph 节点与仲裁测试 (70 项)
│   └── test_p5_platform_local.py # 平台接口与离线联调测试 (6 项)
├── scripts/                   # 工程构建与开发运维脚本
│   ├── dev.sh                 # 一键环境同步、单测、代码检查驱动
│   └── verify_env.sh          # 本地运行环境基线校验
├── pyproject.toml             # Python 项目声明与依赖管理 (PEP 621)
├── LICENSE                    # Apache 2.0 开源许可证
└── .agentarts_config.yaml     # 华为云 AgentArts 高代码平台规范描述

---

6. 本地快速启动与三机联调指南

系统推荐在 WSL2（Ubuntu 24.04 LTS）或 Linux 环境下运行。

6.1 依赖环境要求

• Python 3.12+
• 包管理工具：uv (推荐) 或 pip
• 系统工具：curl, git

6.2 一键同步依赖与环境初始化

# 复制环境变量模板
cp .env.example .env

# 同步安装运行依赖与测试依赖
bash scripts/dev.sh sync

6.3 运行全量回归测试

# 执行全库测试（验证 520 项核心契约与 Oracle 测试）
bash scripts/dev.sh test

# 执行代码静态风格检查
bash scripts/dev.sh lint

6.4 启动全景交互控制台与三端联调模拟

# 启动本地可视化服务（默认监听 0.0.0.0:8088）
bash scripts/dev.sh demo

服务启动后，可在浏览器中打开以下入口进行三机协同交互验证：

视图/终端	访问 URL	场景定位与功能说明
桌面全景控制台	http://localhost:8088/	7-View 全景大屏：涵盖长辈当前状态、同城/异地双子女视图、Guardian 实时仲裁拦截流、审批流及断网模拟卡。
长辈触控终端	http://localhost:8088/mobile?role=elder	Phone 1 (长辈)：高对比度、超大字体，呈现定时声光打卡交互（已服 / 稍后 / 不适）。
同城本地子女端	http://localhost:8088/mobile?role=child_a	Phone 2 (同城 A)：聚焦“就近行动”派工，显示异常提醒与近端协助指引。
异地常态子女端	http://localhost:8088/mobile?role=child_b	Phone 3 (异地 B)：聚焦“健康关怀与趋势”，展示最小披露后的脱敏用药对账流水。

---

7. 华为云 AgentArts 部署与远程探针指南

系统支持无缝部署至华为云 AgentArts 平台，以高代码智能体（High-Code Agent）模式托管运行。

7.1 配置华为云凭据

在 .env 中填入华为云真实鉴权凭据：

HUAWEICLOUD_SDK_AK=your-access-key-id
HUAWEICLOUD_SDK_SK=your-secret-access-key
HUAWEICLOUD_REGION=cn-north-4
MAAS_BASE_URL=https://infer-modelarts-cn-north-4.myhuaweicloud.com/v1/infers/xxxx
MAAS_API_KEY=your-maas-token
MAAS_MODEL_ID=DeepSeek-V4-Flash-0731-W8A8

7.2 运行环境与模型探针

在部署前，运行内置探针校验与华为云 MaaS 服务的连通性：

python platform/probe_maas.py

7.3 构建并推送 ARM64 容器镜像至 SWR

华为云 AgentArts 运行时基于 linux/arm64 架构：

# 自动通过 buildx 交叉编译并在 SWR 镜像仓库完成推送
python platform/push_arm64_image_to_swr.py

7.4 AgentArts 平台配置发布

平台配置通过 .agentarts_config.yaml 自动纳管，包含入口 runtime.app:app、公开调用协议（HTTP/8080）与 Session 存储路径配置：

python platform/publish_agentarts.py

---

8. 测试覆盖说明

本项目全面采用面向不变性（Invariant）的 Oracle 测试体系，所有核心状态机、边界求解器与加密逻辑均具备确定性单测覆盖。

当前全库测试结果：519 passed, 1 skipped (总计 520 项用例)：

tests/test_oracle_core.py        142 passed  [确定性放置求解器、状态与策略过滤]
tests/test_oracle_hub.py         206 passed  [边缘调度、契约验证、本地响应 FSM、回执]
tests/test_oracle_relay.py        95 passed  [中转信箱、E2E 加密、出域闸门、重放防护]
tests/test_graph_*.py             70 passed  [LangGraph 13 节点流转、Guardian 仲裁、审批]
tests/test_p5_platform_local.py    6 passed  [AgentArts 平台协议接入与本地契约]
============================= 519 passed, 1 skipped =============================

核心测试集覆盖重点

1. Core Oracle (test_oracle_core.py)：
   • 验证确定性放置求解器在各类资源冲突下的淘汰分支输出；
   • 保证多主体身份快照（Consent Snapshot）防篡改。
2. Hub Oracle (test_oracle_hub.py)：
   • 验证弱网与断网环境下，本地调度器的离线执行保全能力；
   • 验证契约版本冲突（Stale Version）时的回滚与降级机制。
3. Relay Oracle (test_oracle_relay.py)：
   • 验证 DEC-3 七类禁止字段在任何公网报文中的绝对零存在；
   • 验证 ED25519 签名验证先于 Nonce 查库的严格防护顺序；
   • 验证联合主键租约锁防多端竞争。
4. Graph & Guardian (test_graph_*.py)：
   • 验证 LangGraph 13 节点主状态图的确定性跳转；
   • 验证两层审批流（Human-in-the-Loop）在紧急超时与人工干预下的安全兜底。

---

9. 开源许可证

本项目遵循 Apache License 2.0 协议开源。