# 主体核验项目公开文档

发布快照：2026-10-23。文档公开不表示生产查询API已开放。

# 把名称线索，变成有依据的主体记录。

面向中国大陆医药经营与临床供药主体，组合工商登记、医疗机构登记和互联网资料，返回候选、身份信息、缺失与证据。调用方决定是否查询、采用结果以及如何回写。

> 状态快照 · 2026-10-23：本机异步查询原型、CleverSee共享搜索及宿主机开发／Git桥接已实现；生产API、鉴权和对外部署尚未完成。本网站用于阅读文档，不提供在线查询服务。

## 从你的任务开始

- [我是调用方：评估与接入](getting-started.html)：了解输入、异步流程、渠道选择和结果采用条件。
- [我是开发者：理解系统](architecture.html)：查看模块关系、关键决策、已实现范围及下一步。
- [我要查字段与状态](data-contract.html)：快速找到主详细结构、字段语义与缺失状态。

## 当前可以做什么

| 能力 | 当前状态 | 使用边界 |
| --- | --- | --- |
| 信用代码精确核验 | 已实现 | 仅做精确匹配；格式异常、未命中和来源失败分别处理 |
| 名称精确及多候选 | 已实现 | 当前候选来自工商关键词与字符排序，不是语义概率 |
| 医疗机构登记查询 | 已实测 | 需独立定位及省份上下文；通用定位仍有缺口 |
| 登记官方网页／PDF补充 | 已实测 | 现有覆盖有限，不代表任意机构都可获得统计 |
| CleverSee 主检索 | 已交付 | 共享 CLI 与 Hermes 原生搜索可用，业务语义流程尚未接入 |
| weight／return_mode | 待实现 | 设计方向已记录；当前请求提交这些字段会被拒绝 |
| 外部生产 API | 未部署 | 正式契约、鉴权、服务等级及调用方联调尚待完成 |

## 三个阅读原则

1. **记录存在，不等于身份确认。** 同名、旧名、院区和法律主体需要分别核对。
2. **有值，不等于完整成功。** 读取 status、query_status、sources 和 issues 后再采用字段。
3. **有链接，不等于原文已核验。** 搜索索引、网页原文、官方登记和推断是不同证据层级。

## 项目边界

服务只查询并反馈，不读取源系统的启用开关、不自动决定回写，不修改生产业务数据。医疗机构登记号与统一社会信用代码不能互换；统计资料不能代替身份标识。

[查看接口参考 →](api.html) · [查看已实现与待办 →](roadmap.html)


---

# 调用方接入指南

先确认你需要识别的主体，以及接受什么证据等级，再选择渠道和采用规则。

## 适用范围

目标为中国大陆依法设立，具备与业务相适应资质，并以药品流通或临床诊疗为主要业务，实际开展药品采购、销售或调剂供药活动的主体。仅从事科研、试验或教学且不开展相应经营／临床供药活动的机构，不纳入目标业务范围。

这是业务筛选方向；当前分类路由不等于完整药品资质核验。名称中含“研究型”不能单独作为排除依据，未查到资质也不等于无资质。

## 一次查询的最小输入

```json
{
  "rid": "caller-record-001",
  "name": "上海交通大学医学院附属瑞金医院",
  "social_credit_code": null,
  "query_mask": 7
}
```

rid 是调用方关联标识，原样返回，不参与检索，也不是任务幂等键。name 和 social_credit_code 至少有一项。省份、地址、账户状态、short_name 不是当前外部输入。

## 请求到采用的步骤

1. 部署方提供受控的查询服务地址。当前没有已发布的公共 API 地址。
2. POST /verifications 提交，保存返回的 job_id 与 status_url。
3. GET /verifications/{job_id} 轮询任务。不要因等待而反复 POST 同一请求。
4. 任务完成后，先读 result.status，再逐条检查 details 及组级 query_status。
5. 依据 sources、field_evidence、issues 和候选覆盖程度决定是否采用。回写由调用方完成。

## query_mask 选择的是渠道

| 位值 | 查询渠道 | 常见内容 |
| --- | --- | --- |
| 1 | 天眼查 | 工商登记、当前名称、信用代码、曾用名 |
| 2 | 卫健委 | 医疗登记号、类别、执业地址和级别依据 |
| 4 | 互联网补充 | 登记来源中的床位、医院等次等公开资料 |

相加组合，默认 7。例如 6=2+4，请求医疗登记和互联网，不能暗中补查工商。

当前 mask=4／6 只有已登记规范名称及成功读取可信网页后才可独立建立上下文；mask=2 的通用独立定位仍不足。已有工商信息不会仅凭 rid 自动从调用方历史记录中取回。

## 两条轴：渠道与属性

query_mask 控制从哪里查；identity／business／medical／custom 表示查到的值是什么。床位与诊疗量始终属于 medical，虽然通过互联网获取；custom 目前保存渠道类型，可由任意所选渠道的明确依据派生。

T21（药店）、T31（第三终端）、C（商业）不查询医疗专属属性。分类未知或冲突时先待复核，不能只看名称里是否有“医院”。

## 正式采用前还需要什么

目前适合受控原型验证与样本评测。正式接入前仍需部署鉴权、冻结结果契约、验证目标机构覆盖、明确预算与整体截止时间，并约定失败、歧义和字段缺失的采用规则。当前没有服务等级或字段全覆盖承诺。


---

# HTTP 接口参考

本文描述当前 v0.4 开发原型。文档公开不表示查询服务已对外开放。示例地址为占位符，部署方需另行提供实际地址及接入方式。

## 提交查询

```http
POST /verifications
Content-Type: application/json
```

```bash
curl -X POST 'https://your-api.example/verifications' \
  -H 'Content-Type: application/json' \
  -d '{"rid":"example-001","name":"瑞金医院","query_mask":7}'
```

| 字段 | 类型 | 规则 |
| --- | --- | --- |
| rid | string 或 integer | 必填；非空，字符串表示最多200字符；不接受布尔值 |
| name | string 或 null | 最多200字符；与信用代码至少一项非空 |
| social_credit_code | string 或 null | 最多200字符；格式问题在业务结果中反馈 |
| query_mask | integer | 1–7，默认7；不接受布尔值 |

不接收额外字段。name／social_credit_code 纯空白视为无值。JSON 不允许重复字段或非标准常量，请求体为1–8192字节，暂不支持 Transfer-Encoding。

信用代码当前仅检查18位大写字母／数字形式，尚未实施校验位算法。格式不符但仍有名称时可继续名称路径；不要把格式检查当成有效性确认。

## 提交响应与任务状态

成功提交返回 HTTP 202。下面为合成的结构示例：

```json
{
  "job_id": "00000000000000000000000000000001",
  "state": "QUEUED",
  "request": {
    "rid": "example-001",
    "name": "瑞金医院",
    "social_credit_code": null,
    "query_mask": 7
  },
  "created_at": "2026-10-22T00:00:00+00:00",
  "updated_at": "2026-10-22T00:00:00+00:00",
  "result": null,
  "status_url": "/verifications/00000000000000000000000000000001"
}
```

每次 POST 都创建新任务。rid 仅关联，不提供幂等保障。

## 查询任务

```http
GET /verifications/{job_id}
```

返回任务封装；job_id 为32位小写十六进制字符串。

| state | 含义 |
| --- | --- |
| QUEUED | 已接受，等待来源执行 |
| RUNNING | 当前正在执行 |
| COMPLETED | 执行结束；不保证唯一匹配或所有字段齐全 |
| FAILED | 任务级执行失败或中断恢复标记，检查错误 |

业务结论在 result.status，字段完整性在 details 各组 query_status。HTTP 200 和 COMPLETED 都不能替代这些判断。

## 健康检查

```http
GET /health
```

当前返回 status=ok 与 schema_version=0.4，仅表示进程能响应，不承诺来源授权、额度或实时可用性。

## HTTP 错误

| HTTP | 含义 |
| --- | --- |
| 400 | JSON或字段校验失败 |
| 404 | 路径或任务不存在 |
| 413 | 请求体为空或超过8192字节 |
| 415 | 非 application/json |
| 429 | 队列已满，最多20个未完成任务 |

来源超时、无权限、日额度不足等通常体现在任务结果的 sources／issues。不要把来源失败解释为未找到主体。

## 当前执行限制

当前不支持批量、取消、人工恢复或任务级自动重试。来源按预算串行执行，医疗渠道有至少65秒提交间隔、验证码最多3次及单次预算；任务整体尚无统一截止时间，极端串行耗时可能较长。重启后中断的 RUNNING 任务标记失败，不自动重复扣费重跑。

[下载 OpenAPI 原型参考](openapi.json)（描述当前接口，非生产契约承诺）


---

# 字段、状态与主详细结构

当前结果 schema_version=0.4。头部代表一次输入，details 代表零个、一个或多个查得主体。

## 头部与明细

头部保留 rid、原始 name 和 social_credit_code；查询得到的当前名称／代码在 details[i].identity。输入代码未命中时，不把它复制到候选主体代码字段。

头部 issues 解释输入和整体流程，明细 issues 解释该主体；同一问题不在两处重复。所有明细共享头部输入名，不设置 aliases 或 original_name。former_names 只保存来源取得的曾用名，规范化去重并排除当前名，不自动加入输入简称或错误名。

以下仅为结构示意，省略部分运行字段，不是真实查询记录：

```json
{
  "schema_version": "0.4",
  "rid": "example-001",
  "name": "输入名称",
  "social_credit_code": null,
  "query_mask": 7,
  "queried_at": "2026-10-22T00:00:00+00:00",
  "status": "CANDIDATES",
  "details": [{
    "identity": {"name":"候选当前名称","social_credit_code":null},
    "business": {"query_status":"PARTIAL","former_names":[]},
    "medical": {"query_status":"WAITING_REVIEW","bed_count":null,"annual_outpatient_visits":null},
    "custom": {"query_status":"WAITING_REVIEW","channel_type_code":null},
    "sources": {},
    "field_evidence": {},
    "issues": []
  }],
  "candidates": [],
  "issues": []
}
```

## 四个属性分组

| 分组 | 字段与含义 |
| --- | --- |
| identity | name、social_credit_code、company_id、address、division_code |
| business | former_names、reg_status、reg_capital、legal_person_name、estiblish_time、from_time、to_time、approved_time、company_org_type、business_scope、staff_num_range、social_staff_num |
| medical | medical_registration_number、medical_institution_category_code、practice_addresses、bed_count、annual_outpatient_visits |
| custom | channel_type_code：由选定来源中的明确依据派生 |

estiblish_time 沿用既有字段拼写。reg_capital 当前对象保留 raw，金额／单位／币种等规范化尚不完整；事业单位开办资金不能直接当企业注册资本。主地址和县级区划的通用适配仍未完成，无法确认时为null。

标识一律用字符串；医疗登记号不是信用代码。类别代码（如A100）不等于医院等级或渠道类型。practice_addresses 是同一医疗登记记录的已确认执业地址，不混入另一独立分院。

## 业务结论 result.status

| 状态 | 含义 |
| --- | --- |
| MATCHED_BUSINESS_RECORD | 按输入代码／当前名称取得精确工商记录，不自动证明医疗法律主体映射 |
| MATCHED_MEDICAL_RECORD（预留语义） | 精确医疗记录语义；当前独立医疗定位尚未完整实现 |
| MATCHED_WEB_PROFILE | 本次读取已登记主体的可信网页，不等于工商核验 |
| CANDIDATES | 一条查实候选，尚需判断是否为输入所指对象 |
| AMBIGUOUS | 多条查实候选，分别返回，不强选 |
| NOT_FOUND | 本次已执行范围内没有可返回主体，不代表机构不存在 |
| WAITING_REVIEW | 独立定位或分类依据不足 |
| INVALID_INPUT | 只有不合法代码且无可继续的名称 |
| ERROR | 定位或执行失败，不能解释成查无结果 |

## 字段完整性 query_status

| 状态 | 含义 |
| --- | --- |
| OK | 本次请求且适用的字段已满足当前规则 |
| PARTIAL | 本次请求且适用的字段有结果，也有缺失或来源限制 |
| NOT_REQUESTED | 本次没有选择需要的渠道 |
| NOT_APPLICABLE | 主体不适用该属性，如药店的医疗专属属性 |
| WAITING_REVIEW | 定位、分类或关联依据不足 |
| ERROR | 本次适用查询执行失败 |
| CONFLICT | 来源间存在未解决冲突，未强选 |

例如mask=3没有请求互联网统计，不应仅因床位为null判PARTIAL；mask=6取得登记和床位但缺所请求年量，可以是PARTIAL。former_names=[]需结合来源状态读取，不能认定客观上从未更名。

## 渠道分类

| 编码 | 含义 |
| --- | --- |
| T11 | 基层医院 |
| T12 / T12A / T12B / T12C / T12Z | 二级／二甲／二乙／二丙／明确未定等 |
| T13 / T13A / T13B / T13C / T13Z | 三级／三甲／三乙／三丙／明确未定等 |
| T21 | 药店 |
| T31 | 第三终端 |
| C | 商业 |

只知道三级，用T13；只有来源明确未定等才用T13Z。缺等级不能推为基层。部分分类细则及完整类别表的标准版本仍待验证。

## 查询时间与缺失值

头部queried_at是本次统一业务查询时间，分组不重复设置日期。finished_at表示执行结束；来源采集时间、网页发布时间、报告年度和统计年度分别保留。无法取得的标量用null，数组用[]，不以0或空字符串代替未知。


---

# 证据与统计口径

主体识别和数据采用要能追溯。字段非空或搜索排名靠前，都不能代替证据判断。

## 证据层次

| 层次 | 能说明什么 | 不能直接说明什么 |
| --- | --- | --- |
| 来源登记记录 | 来源当前返回的登记主体、标识与字段 | 跨登记体系的法律身份必然相同 |
| 直接读取网页／PDF | 本次取得的原文内容、URL、采集时间与哈希 | 网页内容必然代表查询当日实时状况 |
| 搜索服务索引正文 | 发现名称关系、候选来源和统计线索 | 本轮已独立打开原站、已经核实事实 |
| 多源关联和派生 | 依据、方法、冲突和推断结果 | 来源直接返回该派生字段 |

来源保存在sources，字段级依据在field_evidence；记录原文、URL、采集时间、口径及哈希等。公开文档站不提供内部证据文件位置或完整执行日志。

## 不混淆的五种时间

- queried_at：这次查询的业务时间。
- 来源采集时间：某次实际访问发生的时间。
- published_at：页面发表时间，不是数据统计年。
- document_year：报告标称年度。
- year：字段数据明确所属的统计年度，无法确认时null。

## 床位和诊疗量

床位需区分核定、登记、开放、编制外、规划及在建；不能因为后一个页面发表更晚，就直接认定它的床位统计更新。

诊疗量需区分门诊与门急诊、全院与院区／科室、年度与日均，保留约数、区间及年份未知说明。不按日量自行推算年量，不把科室数当全院数，不将不同口径上下限拼成区间。

已确认的产品方向允许带来源链接的约数和媒体区间；当前医院API仍有较严格的精确整数解析，尚待业务接入放宽。共享搜索工具能返回相关资料，不表示统计字段已自动按新规则填充。

## 一个可复核的历史样本

瑞金医院的2024年度决算公开材料中出现核定床位2942张及三级甲等描述。本项目曾真实读取并保存原文件，报告年度为2024，床位精确统计年度未独立确认；不能标成2026实时床位。

[查看上海市政府公开报告](https://www.shanghai.gov.cn/cmsres/ed/eddfbdcc0938466b95ae10afc7eefa3d/a0821fb2fe6658c40c10d1f430bd9942.pdf)

共享搜索又检出一篇2025年医院介绍中的年门诊450万线索，但统计年未注明，且原文未独立读通。另一媒体门急诊500万与450万门诊口径不同，不能直接合并或仅据数值判冲突。用户指定的450万—480万文章尚未核实。

## 去重、失败和权限

同一文章的转载不算多份独立事实证据。更名、资源整合、整建制合并可能发生在不同年份，不能用转载数量投票抹平差异。

来源未命中、权限不足、日额度耗尽、超时、预算未覆盖及未执行分别列示。只查询第一页或核验部分候选时，必须说明不完整；单个候选也不自动具有100%把握。


---

# 开发者指南：结构与边界

以当前实现和最新决策为准。历史测试记录是证据，不意味着全部业务流程已经产品化。

## GitHub项目与开发入口

- [主体核验项目实体仓库](https://github.com/chenponsh/entity_identity_agent)：业务代码、来源适配、搜索工具、宿主机开发桥接、测试和开发说明。
- [项目开发接续指南](https://github.com/chenponsh/entity_identity_agent/blob/master/docs/DEVELOPMENT.md)：获取源码、配置环境和运行离线验证。
- [本指南源码仓库](https://github.com/chenponsh/entity_identity_docs)：公开文稿、生成器和静态资源。

以上源码仓库均为私有，需要项目所有者授予GitHub访问权限。指南网页公开不代表业务代码开源，也不代表查询API已对外部署。

```bash
git clone --recurse-submodules https://github.com/chenponsh/entity_identity_agent.git
```

## 模块关系

```text
调用方
  └─ entity_api：HTTP异步接口、SQLite队列、输入校验
       └─ service：定位、多候选、渠道预算、结果封装
            ├─ 工商CLI适配
            ├─ nhc_query：医疗登记浏览器适配
            └─ internet：已登记官方网页／PDF读取

entity_search：CleverSee标准库客户端、CLI、共享缓存
  ├─ 独立工具调用
  └─ Hermes插件 → 原生web_search

下一阶段：把共享搜索与语义判断接入业务定位／统计流程
```

## 已运行的业务路径

有信用代码时精确查并核对返回代码；正常未命中或格式异常且有名称时回退名称。来源失败与未命中分开，不对代码模糊搜索。

当前名称路径仍先做工商名称精确查询，未命中后用工商关键词搜索候选，再按稳定标识逐一核验。当前分数是名称包含关系／字符相似度，不是互联网语义概率。

没有选择工商时不隐式补查。已登记规范全称可通过本次可信网页建立上下文；未登记名称及单医疗渠道的通用独立定位仍有缺口。

## 已确认但尚待接入的路径

名称查询优先互联网发现现实称谓、旧名、合并与院区关系，再形成候选并精确核验。CleverSee主检索提供方已经确定并交付；仍需把检索结果转为可审计的候选判断、业务范围、weight与统计事实。

实现时保留原有信用代码精确优先分支，不能让语义模型修改代码或把院区名称凭空变成独立法律主体。

## 执行约束

来源串行、有单次预算与医疗提交间隔。工商某维度无权限后停止重复查询该维度；额度或授权失败停止后续工商调用。预算未覆盖的候选仍需保留说明。

业务任务保存每次来源调用的独立证据目录，避免多候选覆盖。队列重启不会自动重跑中断任务。检索工具有一小时成功缓存与按查询锁；生产级整体截止时间、跨服务预算和外部鉴权仍待完善。

## 开发者首先检查什么

1. API输入和当前schema_version，而非旧版本字段草案。
2. 每次来源响应的真实形状、状态和权限，而非传统接口的假定契约。
3. 候选去重依据是否为信用代码／稳定ID，同名不同标识能否独立返回。
4. mask是否控制渠道，输出是否按属性归组。
5. 新值是否保留口径、统计年、来源与推断关系。
6. 测试是否区分合成页面、模拟适配器和真实来源调用。

## 源码导航

| 相对路径 | 责任 |
| --- | --- |
| entity_api/ | API、持久队列、匹配、结果和登记网页适配 |
| nhc_query/ | 浏览器、限速、验证码协作、医疗字段读取 |
| entity_search/ | CleverSee共享客户端与缓存 |
| entity_host_bridge/ | 运行主机后台开发任务、状态、取消及受限Git备份入口 |
| integrations/hermes/ | 原生工具插件和共享技能 |
| tests/ | 离线、HTTP、浏览器合成场景及工具测试 |
| docs/ | 内部详细接口与设计文档 |

此公开站是经过整理的发布快照；内部文档中的部署信息和证据文件不随站点公开。更新站点时需对照代码及状态记录，不自动把全部内部Markdown发布出去。

Telegram／Hermes到宿主机的开发与Git入口现已实现，手机Git状态收发、真实Codex任务和私有GitHub推送均已验证。它服务开发协作，不是对外业务查询API；使用方式见[宿主机开发说明](https://github.com/chenponsh/entity_identity_agent/blob/master/docs/HOST_DEVELOPMENT.md)。


---

# 关键决策与易错问题

把已经决定的业务语义与尚未落地的实现分开，便于后续开发延续。

## 01 · 查询服务不接管源系统

**已确认并遵循。** 只查询和反馈。调用方决定是否查询、采用和回写；不新增账户启用字段、更新时间触发或自动回写流程。rid只关联输入，不读取调用方历史数据。

## 02 · 信用代码只做精确查询

**已实现。** 命中后以返回登记名为准；输入名不同不妨碍返回，但需解释。代码无结果不是已证实代码错误；来源失败也不能当无结果。输入代码保留在头部，明细只填查得代码。

## 03 · 主详细关系保留歧义

**已实现。** 一次输入可对应0／1／多条明细。每条主体独立来源、问题和跨源关联判断；不按搜索顺序强选。输入名共享，不重复original_name；former_names仅来自登记来源。

## 04 · 渠道与属性分开

**v0.4已实现。** bit4表示互联网，而不是custom字段。medical中的床位可来自互联网，custom分类也可来自工商或医疗证据。T21／T31／C不查医疗属性，未知分类先待复核。

## 05 · 统一业务查询时间

**已实现。** 头部queried_at统一表示本次查询，不重复组级日期；实际采集、来源发表、报告及统计年份继续保留。缓存不伪造本次重新采集时间。

## 06 · score 与 weight 分离

**score已实现，weight待实现。** score独立评价字面关系，每条0–1且无总和约束；weight按互联网含义估计通常指代，每条0–1、总和不超过1，未评估为null，剩余质量留给未知。

不能用搜索条数、当前排序或转载频率直接当weight。若weight总和不超过1，第一名≥0.6时自然领先第二名至少0.2；这一性质不适用于独立score。

## 07 · 返回模式是执行选项

**设计已记录，当前请求不接受。** return_mode方向为字符串"1"（最高weight）、s100／s090等（score阈值）、w090等（weight阈值）。并列、未知weight、范围未知和检索截断仍需反馈，不能静默强选或归一化剩余候选。

## 08 · 先发现真实称谓，再核验主体

**方向已确认，业务运行时尚待替换。** 宝钢医院与九院北部院区的现实关系说明字符研究不足；资源整合与整建制合并需分别保留事件及日期。称谓对应不等于法律主体及标识已核实。

## 09 · 接受约数，保留真实口径

**产品方向已确认，业务解析仍待放宽。** 可采用有来源的近似量或区间，但不能接受错主体、错科室或错年份。发布年不填成统计年，门诊与门急诊不混用。

## 10 · 主检索选择CleverSee

**用户已确定并交付。** CleverSee共享工具和Hermes原生搜索可用。Serper不作为业务依赖；当前VM的Bing浏览器同题检索相关性不足并遇真人验证，不作默认自动备用。检索工具可用不代表医院业务语义流程已完成。


---

# CleverSee 共享搜索工具

CleverSee CNAuto是已确定的主检索提供方。独立CLI与Hermes原生web_search共用同一客户端，适合为名称发现及公开资料核对提供来源。

## 在项目中调用

```bash
python3 -m entity_search '瑞金医院 年门诊量' --limit 6
```

Hermes可直接调用原生web_search(query, limit)。凭据由部署者在私有配置或进程环境中提供，本公开站不收集或展示Key，也不代访问真实搜索接口。

## 参数

| 参数 | 语义 |
| --- | --- |
| query | 1–500字符，建议简明且尽量30字符以内，不静默截断 |
| --limit | 1–10，默认6 |
| --time-range | NoLimit、OneDay、OneWeek、OneMonth、OneYear；约束页面时间 |
| --raw | 加入脱敏上游原响应 |
| --refresh | 跳过一小时缓存，可能重新产生用量 |
| --health | 无网络检查本地配置，不证明账户或额度可用 |

请求开启索引正文与相关度，关闭增强摘要；单次25秒超时、响应上限8MB，不自动重试或跨提供方回退。空结果仍是一次成功执行的检索。

## 返回值

顶层包含success、status、provider、engine、results、usage、cached、queried_at。每条结果含title、url、snippet、main_text、published_at、relevance和evidence_kind=search_index。

失败状态包含INVALID_INPUT、CONFIG_ERROR、AUTH_ERROR、QUOTA_EXCEEDED、FORBIDDEN、RATE_LIMITED、HTTP_ERROR、REQUEST_ERROR、INVALID_RESPONSE、RESPONSE_TOO_LARGE、CACHE_ERROR、BUSY及上游错误。不要将失败当无结果，或循环重试导致重复费用。

## 缓存与成本

相同query／条数／时间范围的成功结果缓存1小时，同查询锁避免并发重复请求。命中缓存时保留原queried_at并增加served_at；usage表示原响应计量，不等于缓存命中也再次扣费。

Hermes还有自己的进程内缓存和条数分桶，当前6条请求可能向插件传10条，再裁成6条。跨CLI与原生工具比较缓存时需核对条数。Hermes既有救援策略可能影响失败后的实际后端，应保留backend_error及来源，不将救援结果标成CleverSee。

## 已验证与尚未验证

已完成Hermes原生首次、重复请求、新进程和跨用户共享缓存验证；共享技能可发现。尚未把它接入医院API的通用名称推理／近似统计字段填充，也未执行完整Hermes模型问答验收。原文提取仍是独立步骤。

[阿里云官方统一搜索接口参考](https://help.aliyun.com/zh/document_detail/3062218.html)


---

# 实现状态与后续工作

本页记录2026-10-23的发布快照。已确认方向不等于已实现，单个成功样本也不等于MVP评测通过。

## 已实现／已验证

| 范围 | 状态与证据边界 |
| --- | --- |
| 单机构医疗登记原型 | 已真实查询成功，合成浏览器测试另行验证；通用定位仍有限 |
| 天眼查接入与多候选 | 已真实调用，候选分数未校准；部分曾用名权益不足 |
| 本机异步API／SQLite | 当前v0.4主详细结构、任务状态和渠道掩码已实现；未对外部署 |
| 官方网页／PDF读取 | 瑞金公开决算2942核定床位／三甲已实测；不是广泛机构覆盖 |
| CleverSee共享检索 | 独立工具、Hermes插件／技能和缓存实测通过；尚未驱动业务语义层 |
| 宿主机开发与Git | 后台任务和Hermes命令已交付；真实Codex开发、私有GitHub推送及手机Git状态收发已验证 |
| 测试 | 最近全量离线回归108项：102通过、6项浏览器测试默认跳过；不表示生产稳定性验收完成 |

## 优先推进

1. 将CleverSee与可审计语义判断接入业务名称发现，保留代码精确优先及预算控制。
2. 实现weight／return_mode、范围判断、未发现质量与歧义处理，并用标注样本校准。
3. 支持带来源、统计口径、约数／区间及年份未知的诊疗量，替换当前过严的整数准入。
4. 扩展独立省份定位、主地址／县级区划适配，以及更多医院、药店和商业主体样本。
5. 完成10–20条可复核样本、稳定性、调用预算、日吞吐及验收阈值评估。
6. 冻结正式契约、错误和证据结构，再完成外部鉴权、部署与调用方联调。

## 接入前仍待冻结

- 正式生产API与JSON Schema、资金／长期有效的规范表达。
- 来源权益、费用、全局截止时间与并发策略。
- 完整类别表、渠道分类细则、地址和跨源法律主体关联规则。
- 服务等级、监控与生产运行责任。
- 最终业务模型和SDK。主检索提供方已经确定，不与模型选择混为一谈。

## 文档维护规则

代码与当前状态记录是接续依据，旧草案仅保留历史。公开站点为整理后的版本快照，内容更新需重新核对实现、已验证事实和待办；不会自动同步内部文档或聊天。

[下载公开文档合辑](handbook.md) · [下载OpenAPI原型参考](openapi.json)