在医疗健康应用里介绍一个 Skill，如果只写“能总结、能检索、能生成报告”，开发团队很难判断它能否接入现有系统。更关键的问题是：它在哪个流程节点被调用、由谁触发、输入输出如何约束、失败后如何降级、日志如何留存。本文只讨论技术架构和工程流程示例，不提供诊断、治疗、分诊或用药建议；涉及规则均为示例，真实项目需由医疗专业人员和机构规范确认。

为什么功能清单会误导接入评估

医疗相关 Skill 往往不是一个孤立按钮，而是嵌入到业务流程中的一个可调用能力。例如“医学文献摘要 Skill”听起来只是文本生成，但工程接入时至少要回答这些问题：

• 输入来自用户粘贴、文档解析结果，还是内部知识库检索结果？
• 输出是直接展示给用户，还是进入人工复核队列？
• 是否允许携带敏感字段，字段脱敏在哪里完成？
• 调用失败后是重试、跳过，还是切换到人工处理？
• 调用记录是否能满足审计、追踪和问题复盘？

如果介绍页只列功能，会把“能力边界”隐藏掉。对技术负责人来说，更有价值的是一张接入图、一份接口契约、一组权限策略，以及 Skill 在工作流里的位置。

一个更适合医疗 Skill 的四层描述法

我通常把医疗 Skill 拆成四层来描述：入口层、编排层、能力层、治理层。

入口层负责把外部调用收敛到统一 API Gateway，处理认证、限流、请求大小限制和基础校验。医疗场景中不建议让前端直接调用 Skill Runtime，因为后续很难统一做权限、审计和降级。

编排层由 workflow engine 负责，决定 Skill 在流程中的位置。例如“文档上传后先解析，再脱敏，再调用摘要 Skill，最后进入人工复核”。这个层面描述清楚后，读者才能理解 Skill 是自动执行、半自动执行，还是人工触发。

能力层是 Skill 本身，包括输入 schema、输出 schema、超时设置、重试策略和错误码。这里不要只写自然语言能力，要写清楚接口契约。

治理层包括 RBAC、audit log、数据留存、调用追踪和配置管理。医疗健康项目通常要关注谁调用了什么、什么时候调用、输入输出摘要是什么、是否经过复核。

接口契约比功能描述更重要

一个可接入的 Skill 至少要提供稳定的 manifest。下面是一个简化示例，用来描述“文献摘要 Skill”的接入边界：

skill_id: literature_summary_v1
name: 文献摘要 Skill
input_schema:
  type: object
  required:
    - document_id
    - text_blocks
    - language
  properties:
    document_id:
      type: string
    text_blocks:
      type: array
      max_items: 50
      items:
        type: string
    language:
      type: string
      enum:
        - zh
        - en
output_schema:
  type: object
  required:
    - summary
    - citations
    - review_required
  properties:
    summary:
      type: string
    citations:
      type: array
      items:
        type: string
    review_required:
      type: boolean
runtime_policy:
  timeout_ms: 15000
  retry:
    max_attempts: 2
    backoff_ms: 800
governance:
  pii_allowed: false
  audit_level: full
  human_review: required

这份 manifest 不讨论医学结论，只约束工程接入方式。pii_allowed: false 表示调用前应完成脱敏；human_review: required 表示输出不能直接进入最终发布链路；timeout_ms 和 retry 帮助工作流引擎决定失败处理方式。

在 API Gateway 层收口调用边界

API Gateway 不只是转发请求。对于医疗相关 Skill，它应该承担统一鉴权、限流、字段过滤和审计埋点。下面的 Python 示例展示一个最小化的调用前校验逻辑，真实项目可放在网关插件、BFF 或内部服务中。

from dataclasses import dataclass
from typing import Dict, Any, List
import time
import uuid

@dataclass
class UserContext:
    user_id: str
    roles: List[str]
    department: str

SKILL_POLICY = {
    "literature_summary_v1": {
        "allowed_roles": {"researcher", "reviewer", "admin"},
        "pii_allowed": False,
        "max_text_blocks": 50
    }
}

def has_permission(user: UserContext, skill_id: str) -> bool:
    policy = SKILL_POLICY.get(skill_id)
    if not policy:
        return False
    return bool(set(user.roles) & policy["allowed_roles"])

def contains_sensitive_fields(payload: Dict[str, Any]) -> bool:
    # 示例规则：真实项目应接入机构确认的字段字典和脱敏策略
    sensitive_keys = {"patient_name", "phone", "id_number"}
    return any(key in payload for key in sensitive_keys)

def build_audit_event(user: UserContext, skill_id: str, status: str) -> Dict[str, Any]:
    return {
        "event_id": str(uuid.uuid4()),
        "timestamp": int(time.time()),
        "user_id": user.user_id,
        "department": user.department,
        "skill_id": skill_id,
        "status": status
    }

def validate_skill_call(user: UserContext, skill_id: str, payload: Dict[str, Any]) -> Dict[str, Any]:
    if not has_permission(user, skill_id):
        return build_audit_event(user, skill_id, "denied_by_rbac")

    policy = SKILL_POLICY[skill_id]
    if not policy["pii_allowed"] and contains_sensitive_fields(payload):
        return build_audit_event(user, skill_id, "denied_by_sensitive_field")

    text_blocks = payload.get("text_blocks", [])
    if len(text_blocks) > policy["max_text_blocks"]:
        return build_audit_event(user, skill_id, "denied_by_payload_limit")

    return build_audit_event(user, skill_id, "accepted")

if __name__ == "__main__":
    user = UserContext(
        user_id="u_1001",
        roles=["researcher"],
        department="medical_research"
    )
    payload = {
        "document_id": "doc_20260615_001",
        "text_blocks": ["abstract text", "method text"],
        "language": "en"
    }
    print(validate_skill_call(user, "literature_summary_v1", payload))

这段代码的重点不是实现完整网关，而是说明：Skill 介绍中应该把调用边界外显出来。RBAC、敏感字段策略、payload 限制、审计事件，都应成为接入文档的一部分。

工作流位置决定产品风险和工程复杂度

同一个 Skill，放在不同流程节点，风险和实现复杂度完全不同。

如果放在“用户主动点击后生成草稿”的位置，系统主要关注调用体验、失败提示和结果保存。如果放在“文档入库后自动处理”的位置，就需要任务队列、幂等键、批处理限流和异常重放。如果输出会进入对外展示页面，还需要人工复核节点和版本冻结机制。

一个更稳妥的医疗 Skill 工作流可以这样设计：

1. 用户上传或选择文档。
2. 文档解析服务提取文本块。
3. 脱敏服务按机构规则处理字段。
4. 工作流引擎调用摘要 Skill。
5. 输出进入人工复核节点。
6. 复核通过后写入业务系统。
7. 全链路写入 audit log。

这里的“人工复核”是工程流程节点，不代表任何医疗判断。真实项目中的复核职责、升级规则和留痕要求，应由机构制度和专业人员确认。

编排层需要关注的失败模式

医疗 Skill 接入文档还应写明失败处理，而不是只展示成功路径。常见失败模式包括：

• 上游文档解析失败，Skill 不应被调用。
• 输入文本超长，需要切块或拒绝。
• Skill 超时，工作流应进入可重试状态。
• 输出 schema 不合法，不能直接进入下一节点。
• 审计写入失败，业务是否阻断要提前定义。

建议在 workflow engine 中为每次调用生成 correlation_id，贯穿网关、编排、Skill Adapter 和审计日志。排查线上问题时，开发者能通过一个 ID 找到请求来源、参数摘要、执行节点、错误码和处理人。

医疗 Skill 介绍页应该包含什么

面向开发者的 Skill 介绍页，可以按以下结构组织：

• 适用流程：说明它适合放在上传后、检索后、复核前，还是归档前。
• 输入输出：提供 JSON Schema 或 OpenAPI 片段。
• 调用边界：说明是否允许敏感字段、最大文本长度、超时和并发限制。
• 权限模型：列出示例角色和允许动作。
• 审计字段：说明记录哪些事件，不记录哪些原文内容。
• 失败策略：列出重试、降级、人工处理和告警规则。
• 示例工作流：给出从触发到复核的完整链路。

这比“支持摘要、支持问答、支持翻译”更能帮助架构师评估接入成本，也能让开发者提前发现权限、日志和异常处理上的缺口。

总结

医疗相关 Skill 的技术介绍，不应停留在功能清单，而要回答“如何接入、在哪里调用、边界是什么、如何治理”。API Gateway 负责收口入口，workflow engine 负责放置流程位置，RBAC 控制谁能调用，audit log 支撑追踪和复盘。

如果你正在设计医疗健康应用中的 Skill 平台，建议先写 manifest、接口契约和工作流图，再写功能说明。功能决定它能做什么，接入方式和工作流位置决定它能否安全、稳定、可维护地进入真实系统。

本文文献检索、文献挖掘以及文献翻译采用的是【超能文献| AI文献检索|AI文档翻译】。