# AIConHIS-python

**Repository Path**: dongfq/aicon-his-python

## Basic Information

- **Project Name**: AIConHIS-python
- **Description**: aicon-his-python 实验环境
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-24
- **Last Updated**: 2026-05-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HIS Config Agent

> 通过自然语言 + AI 自动完成 HIS（医院信息系统）后台配置的智能 Agent 工具。
>
> Python 原型工程，dongfuqiang@imedway.com。
>
> **Phase 5 已完成 + V4 核心改进** · Ref + Fingerprint 引用系统 · DOM Snapshot 引擎 · 网络层验证 · [MIT License](LICENSE)

## 2026-05-31 本项目封存，转至 auto-con-his project 继续优化开发

## 核心功能

1. **自然语言理解** — 输入"增加骨科 005 王医生门诊出诊及处方权限"，系统自动解析意图
2. **知识库检索** — 支持腾讯 IMA、iMedway RAG、本地知识库三种知识库来源
3. **配置项生成** — 支持 LLM 优先 / 模板优先 / 仅 LLM / 仅模板四种生成策略
4. **配置模板管理** — 模板 CRUD，用户维护的模板可被配置生成器直接使用
5. **操作录制 V4** — Playwright 页面事件监听自动录制（click / fill / select / keypress / iframe），**自动生成 Ref + Fingerprint 引用标识**
6. **录制模板引擎 V4** — 录制操作保存为可执行模板，支持 **Ref + Fingerprint 三级匹配**（exact → stable → reidentified）+ 传统 5 种选择器策略 fallback
7. **OpenClaw Skill 集成** — 支持 A/B/C/D 四方案执行：录制模板回放 / 知识库指导 / 已连接浏览器 JS 执行 / Skill 执行 + AI 视觉 Fallback
8. **执行方案推荐** — 执行前智能推荐多种方案，前端弹窗展示供用户选择
9. **AI 视觉 Fallback** — 定位器失败时自动截图，通过多模态 LLM 分析并执行
10. **人工确认** — Web 界面展示清单，支持逐项确认 / 修改 / 跳过，显示生成来源（AI 模型 / 模板）
11. **自动执行** — Playwright WebBridge 浏览器自动化逐条完成 HIS 配置，含重试机制和并发控制
12. **审计追溯** — 完整操作日志、前后截图、人工回滚指引
13. **执行报告** — 统计摘要 + HTML 报告（含截图、参数、回滚步骤）

## 技术架构

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Web UI    │────>│  FastAPI    │────>│  Playwright │──> HIS 系统
│  (React)    │<────│  (Python)   │<────│  (WebBridge)│
└─────────────┘     └─────────────┘     └─────────────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
        ┌─────────┐  ┌─────────┐  ┌─────────┐
        │ 腾讯 IMA │  │iMedway  │  │ 本地 KB │
        │ 知识库   │  │RAG 问答 │  │ 向量库  │
        └─────────┘  └─────────┘  └─────────┘
                           │
                           │
                    ┌─────────────┐     ┌──────────────┐
                    │   LLM       │────>│ OpenClaw     │
                    │DeepSeek/etc │     │ Skill        │
                    └─────────────┘     └──────────────┘
```

## 快速开始

### 环境要求

- Python 3.11+
- Node.js 18+（前端）
- Playwright Chromium 浏览器

### 后端启动

```bash
# 1. 安装依赖
pip install -r requirements.txt
playwright install chromium

# 2. 配置环境变量
cp .env.example .env
# 编辑 .env，填写 LLM API Key 及 HIS 系统地址

# 3. 启动服务（开发调试）
.venv\Scripts\Activate.ps1
cd backend
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000
```

> Windows 上请勿使用 `--reload`，会导致 Playwright subprocess 崩溃。

### 前端启动

```bash
cd web
npm install
npm run dev
```

### Docker 启动

```bash
docker-compose up -d
```

## API 文档

启动后端后访问：[http://localhost:8000/docs](http://localhost:8000/docs)

## 项目结构

```
├── backend/                         # Python FastAPI 后端
│   ├── app/
│   │   ├── main.py                  # 服务入口
│   │   ├── api/routes/              # 8 组 REST API 路由
│   │   ├── api/schemas/             # Pydantic 数据模型
│   │   ├── core/                    # 工作流引擎、任务管理、事件总线
│   │   ├── modules/                 # 10 个功能模块
│   │   │   ├── nl_parser/           # 自然语言解析 (LLM+规则)
│   │   │   ├── kb_retriever/        # 知识库检索 (IMA/iMedway/本地)
│   │   │   ├── config_generator/    # 配置项生成 (LLM+模板, 4 策略)
│   │   │   ├── template_manager/    # 配置模板 CRUD
│   │   │   ├── execution/           # 执行引擎 (编排+策略+适配器)
│   │   │   ├── webbridge/           # 浏览器自动化 (9 文件)
│   │   │   │   ├── recorder.py          # 操作录制器 V4（Ref + Fingerprint）
│   │   │   │   ├── template_executor.py # 录制模板执行器 V4（三级匹配）
│   │   │   │   ├── dom_snapshot.py      # DOM Snapshot 引擎（V4 新增）
│   │   │   │   ├── verifier.py          # 操作结果验证器 V4（网络层验证）
│   │   │   │   ├── locator.py           # 元素定位库
│   │   │   │   ├── browser.py           # Playwright 浏览器管理
│   │   │   │   ├── cdp_bridge.py        # CDP 桥接（网络抓包）
│   │   │   │   ├── network_capture.py   # 网络抓包录制
│   │   │   │   └── connected_browser.py # 已连接浏览器管理
│   │   │   ├── skills/              # OpenClaw Skill 集成
│   │   │   └── audit/               # 审计与回滚
│   │   ├── models/                  # LLM 调用封装 (DeepSeek/Kimi/OpenAI/Claude)
│   │   ├── config/settings.py       # 全局配置 (Pydantic Settings)
│   │   ├── prompts/                 # 提示词模板
│   │   └── utils/                   # 工具函数 (加密/重试/校验)
│   ├── data/                        # 运行时数据
│   │   ├── locators/                # 元素定位器 YAML
│   │   ├── templates/               # 配置模板 JSON
│   │   ├── recorded_templates/      # 录制模板 JSON
│   │   ├── logs/                    # 审计日志 + 报告
│   │   ├── screenshots/             # 操作截图
│   │   └── cache/                   # 知识库缓存
│   └── tests/                       # 单元测试 + 集成测试
├── web/                             # React + TypeScript 前端
│   └── src/pages/
│       ├── TaskCreatePage.tsx       # 新建配置 (含方案选择弹窗)
│       ├── TaskListPage.tsx         # 任务历史
│       ├── TemplatesPage.tsx        # 模板管理 (配置+录制统一)
│       ├── SkillsPage.tsx           # OpenClaw Skill 管理
│       └── SettingsPage.tsx         # 系统设置
├── docs/                            # 项目文档
│   ├── product-intro.md             # 产品白皮书与阶段总结
│   ├── verify-report.md             # 验证报告 (MD 格式)
│   ├── his-api-design.md            # HIS API 对接设计方案
│   ├── HIS配置自动化验证报告_v2.docx # 验证报告 (DOCX 格式)
│   ├── system-overview.md           # 系统全貌
│   ├── WEBBRIDGE_FEASIBILITY.md     # WebBridge 可行性分析
│   └── ops.md                       # 运维手册
├── DESIGN.md                        # 系统架构设计文档
├── AGENTS.md                        # Agent 开发指南
└── docker-compose.yml               # Docker 编排
```

## 配置说明

编辑 `.env` 文件配置以下参数：

### LLM 配置

| 参数                | 说明           | 示例                                                 |
| ------------------- | -------------- | ---------------------------------------------------- |
| `LLM_PROVIDER`    | 大模型提供商   | `deepseek` / `openai` / `kimi` / `anthropic` |
| `LLM_API_KEY`     | 大模型 API Key | `sk-xxx`                                           |
| `LLM_MODEL`       | 模型名称       | `deepseek-chat`                                    |
| `LLM_BASE_URL`    | API 地址       | `https://api.deepseek.com`                         |
| `LLM_TEMPERATURE` | 生成温度 (0-2) | `0.1`                                              |
| `LLM_MAX_TOKENS`  | 最大输出 Token | `4096`                                             |

### 视觉 LLM 配置（AI 视觉 Fallback 使用）

| 参数                    | 说明             | 示例                              |
| ----------------------- | ---------------- | --------------------------------- |
| `VISION_LLM_PROVIDER` | 视觉模型提供商   | `kimi` / `openai`             |
| `VISION_LLM_API_KEY`  | 视觉模型 API Key | `sk-xxx`                        |
| `VISION_LLM_MODEL`    | 视觉模型名称     | `moonshot-v1-8k-vision-preview` |

### 知识库配置

| 参数                           | 说明               | 示例                                                                  |
| ------------------------------ | ------------------ | --------------------------------------------------------------------- |
| `KB_PROVIDER`                | 知识库来源         | `ima` / `imedway` / `local`                                     |
| `CONFIG_GENERATION_STRATEGY` | 配置项生成策略     | `llm_first` / `template_first` / `llm_only` / `template_only` |
| `IMA_OPENAPI_CLIENTID`       | 腾讯 IMA Client ID | `ima-xxx`                                                           |
| `IMEDWAY_API_KEY`            | iMedway API Key    | `imedway-xxx`                                                       |
| `LOCAL_KB_PATH`              | 本地知识库路径     | `D:\资料\标准实施文档`                                              |

### HIS 系统配置

| 参数             | 说明         | 示例                                      |
| ---------------- | ------------ | ----------------------------------------- |
| `HIS_BASE_URL` | HIS 系统地址 | https://192.168.100.105:1443/imedical/web |
| `HIS_USERNAME` | HIS 登录账号 | demo                                      |
| `HIS_PASSWORD` | HIS 登录密码 |                                           |

### 执行策略配置

| 参数                     | 说明             | 示例                                                       |
| ------------------------ | ---------------- | ---------------------------------------------------------- |
| `EXECUTION_STRATEGY`   | 执行策略         | `auto` / `webbridge` / `sandbox` / `api` / `mcp` |
| `CONTINUE_ON_ERROR`    | 出错是否继续     | `true` / `false`                                       |
| `LOCATOR_VERSION`      | 元素定位库版本   | `default` / `v1.0` / `v2.0`                          |
| `PLAYWRIGHT_HEADLESS`  | 无头模式         | `true` / `false`                                       |
| `PLAYWRIGHT_TIMEOUT`   | 操作超时 (ms)    | `30000`                                                  |
| `PLAYWRIGHT_POOL_SIZE` | 浏览器连接池大小 | `3`                                                      |

### HIS API 配置（预留，待对接后启用）

| 参数                 | 说明                | 示例                            |
| -------------------- | ------------------- | ------------------------------- |
| `HIS_API_ENABLED`  | 启用 HIS API 适配器 | `true` / `false`            |
| `HIS_API_BASE_URL` | HIS API Base URL    | `https://api.his.example.com` |
| `HIS_API_KEY`      | API Key (自动加密)  | `sk-xxx`                      |
| `HIS_API_VERSION`  | API 版本号          | `v1`                          |

以上所有配置也可以在 Web UI 的「系统设置」页面进行可视化配置。

## 实现状态与实测评估

| 模块                       | 完成状态 | 实测效果 | 说明                                                   |
| -------------------------- | -------- | -------- | ------------------------------------------------------ |
| 项目骨架 (FastAPI + React) | 已完成   | 良好     | 前后端可运行，Docker 编排就绪                          |
| 工作流引擎 (状态机)        | 已完成   | 良好     | 10 状态完整流转，事件总线                              |
| 任务管理                   | 已完成   | 良好     | 任务 CRUD、配置项确认、WebSocket 推送                  |
| 知识库检索 (KB Retriever)  | 已完成   | 可用     | 三种来源切换正常                                       |
| 审计与回滚                 | 已完成   | 良好     | JSONL 日志、HTML 报告、回滚指引                        |
| 安全性                     | 已完成   | 良好     | Fernet 加密、强制人工确认                              |
| NL Parser                  | 已完成   | 待优化   | 建议规则为主，LLM 兜底                                 |
| Config Generator           | 已完成   | 待优化   | 建议默认 template_only                                 |
| WebBridge 执行 (V4)        | 已完成   | 改进中   | Ref+Fingerprint 三级匹配，iframe 场景稳定性提升        |
| AI 视觉 Fallback           | 已完成   | 不达标   | 成功率 60-70%，V4 新增 DOM Snapshot 结构化输入降低成本 |
| DOM Snapshot 引擎          | V4 新增  | —       | 为 LLM 提供结构化页面文本替代纯截图                    |
| 网络层验证                 | V4 新增  | —       | 验证器集成 Ajax 拦截器响应检查                         |
| HIS API Adapter            | 预留接口 | —       | 框架就绪，待 HIS 厂商对接                              |

> 详细实测数据与根因分析见 [`docs/verify-report.md`](docs/verify-report.md)。

## 文档导航

| 文档                                                   | 说明                            |
| ------------------------------------------------------ | ------------------------------- |
| [product-intro.md](docs/product-intro.md)                 | 产品白皮书与阶段总结            |
| [verify-report.md](docs/verify-report.md)                 | 验证报告 MD 版                  |
| [his-api-design.md](docs/his-api-design.md)               | HIS API 对接集成设计方案        |
| [system-overview.md](docs/system-overview.md)             | 系统全貌 (16 章)                |
| [WEBBRIDGE_FEASIBILITY.md](docs/WEBBRIDGE_FEASIBILITY.md) | WebBridge 可行性分析 + 实测评估 |
| [DESIGN.md](DESIGN.md)                                    | 系统架构设计文档 (V4 已更新)    |
| [AGENTS.md](AGENTS.md)                                    | Agent 开发指南                  |
| [ops.md](docs/ops.md)                                     | 运维手册 (含 V4 新特性运维指南) |

## 安全与合规

- **强制人工确认**：任何自动化流程必须经过人工确认环节，不可绕过
- **无自动回滚**：MVP 阶段不自动回滚，生成人工回滚指引由管理员执行
- **完整审计**：每步操作前后截图、参数、结果全部记录，保留 180 天
- **渐进式执行**：新模块首次使用建议开启"观察模式"验证后再执行
- **密码加密**：敏感配置（密码、API Key）自动加密存储，密钥独立管理
- **并发控制**：BrowserContext 受 Semaphore 限制，避免资源耗尽

## License

[MIT](LICENSE)