Servicialo — Open Protocol for AI-Coordinated Services

---

协议规范

有关架构、消息流和数据模型的正式说明：

• 白皮书 v0.9 — 正式协议规范
• 协议仓库 — 架构、RFC 和参考资料
• PROTOCOL.md — 本仓库中的完整规范

---

协议单元

该协议区分事件原语（SC、CAC）和计费模型（SC、CAC、RAC）。请参阅 GLOSSARY.md 了解完整定义。

---

从哪里开始？

我有一家服务企业，希望 AI Agent 能发现并预约我的服务 → 你需要的是一个兼容该协议的平台，而不是这个仓库。Coordinalo 是参考实现。随着协议日趋成熟，我们期待涌现出更多兼容平台。

我是开发者，想要构建一个兼容该协议的平台 → 请继续阅读。从 IMPLEMENTING.md 开始。

---

问题

没有标准协议，每个平台的服务都各自使用一套语言。想要预约医疗服务、验证上门维修，或支付法律咨询费用的 AI Agent，都需要针对每个平台进行单独集成。数据被孤立在各自系统中，互操作性需要定制集成，而关于服务交付的集体智能始终无法形成。

Servicialo 是通用协议。 它定义了最小可行架构，使任何 AI Agent 都能在任何兼容平台上协调任何专业服务，无需额外集成。

---

协议原语

Servicialo 定义了四种协调原语。它们共同覆盖专业服务交付的完整价值链：

原语	解决的问题	协议覆盖范围
日程协调	多方（服务提供者、客户、资源）可用时间的交集及例外处理	6+3 生命周期、6 种例外流程、3 变量调度器
身份验证	服务提供者凭证、信任评分、客户与付款方分离	服务提供者凭证、trust_score、payer_id 分离
财务结算	开票、收款、结算和收入分成，并解决争议	收费维度、服务订单账本、payment_schedule
需求信号	网络节点间匿名且聚合的运营遥测数据	遥测扩展（贡献以获得访问权限模型）

每种原语均可独立规范。实现方可按需采用。

---

什么是服务

服务是在特定时间和地点交付的一种转变承诺。

与产品不同，服务无法储存、转售或退货。它在交付时即被消费。这使其本质上截然不同——因此它需要自己的协议。

服务源自三个方面：

来源	关键问题	示例
来自资产	你有什么是他人需要的？	空置公寓 → 临时住宿
来自优势	你有什么本领是他人不具备的？	运动机能学认证 → 运动康复
来自你的时间	你能做什么，是他人不愿或无法做的？	可支配时间 → 专业清洁

---

8 个维度

所有专业服务——从运动机能学诊疗到税务审计——都可以用相同的 8 个维度建模：

	维度	捕捉的信息	示例
1	内容	交付的活动或结果	运动机能学诊疗、电气维修
2	交付方	服务提供者及其资质	持证运动机能学师、SEC 电工
3	接收方	客户——并明确区分付款方	患者（由 FONASA 付款）、员工（由公司付款）
4	时间	约定的时间段	2026-02-10 10:00 至 10:45
5	地点	实体或虚拟地点，可选用 resource_id 引用实体资源（3.5b：诊室、检查室、椅子、设备）	诊所 3 号诊室、客户住所、视频通话
6	周期	当前在各状态维度（交付、证据、接受、结算）中的位置	已完成 · 已记录证据 · 待收款
7	证据	如何佐证服务已发生	GPS + 时长 + 客户签名
8	收费	独立于周期的财务结算	$35.000 CLP · 已收款 · 预付套餐

付款方不总是客户。 医疗服务由保险公司付款。企业服务由公司付款。教育服务由监护人付款。协议明确区分客户与付款方——因为现实生活中，他们几乎从来都不是同一个人。

---

生命周期：6 个核心状态 + 3 个可选财务状态

协议定义了相互独立的状态，用于观察协调工作的完整周期。以下 9 个里程碑构成顺利流程——这是最常见的运营路径，并非唯一的强制顺序。前 6 个为必需状态；3 个财务状态为可选扩展。交付、证据、接受和结算会独立演进（PROTOCOL.md §6.0）：

Solicitado → Agendado → Confirmado → En Curso → Completado → Documentado → (opcional) Facturado → Cobrado → Verificado

#	状态	发生的情况
1	已请求	客户或其 Agent 定义所需服务、时间和地点
2	已安排	分配时间、服务提供者和地点。时段被预留
3	已确认	双方确认该约定
4	进行中	检测到签到。服务正在交付
5	已完成	服务提供者将交付标记为完成
6	已记录	已生成正式记录：临床档案、报告、会议纪要
7	已开票	已开具税务凭证
8	已收款	已收到并确认付款
9	已核验	客户确认——周期结束

已核验代表周期结束。 客户必须掌握完整信息后才能核验：证据已记录、发票已开具、款项已到账。过早核验会迫使客户确认尚无正式记录的事项。

---

异常才是常态

异常并非个例，而是发生在 15–30% 的预约中。设计良好的服务会明确规定计划未能如期进行时的处理方式：

异常	转换	处理方式
客户未到场	已确认 → 已取消	收取违约金，并释放服务提供方的时间
服务提供方未到场	已确认 → 正在重新分配 → 已安排	自动寻找替代人选
取消	任何交付前状态 → 已取消	按约定的取消政策处理
质量争议	已完成 → 有争议	冻结收款，并要求提供证据
改期	已安排/已确认 → 正在改期 → 已安排	尽可能保留原服务提供方。包括资源冲突（重复预订、资源不可用）
部分交付	进行中 → 部分完成	记录已交付的内容，并调整发票

---

服务与服务订单

该协议建立在两个对象及其关系之上：

Organización
└── Orden de Servicio            ← acuerdo comercial (opcional)
    ├── alcance                   qué servicios, cuántos, de qué tipo
    ├── precio                    cómo se calcula el valor
    ├── esquema de pagos          cuándo se mueve el dinero
    └── Servicios                 ← unidades atómicas de entrega
        └── 8 dimensiones cada uno

**Service Delivery（服务交付）**是实际执行的原子实例——也就是真正发生的事情。在当前的 wire format 中，它由 Service 对象表示（为保持兼容而保留此名称）。服务订单是将多次交付归入同一范围、价格和付款方案的商业协议。单独使用“服务”一词时，指的是领域中的一般概念，而不是第四个对象。

当某项服务属于某个服务订单时，其收费维度仅供参考——记录经济价值，但不生成发票。开票完全由服务订单负责。

同一结构适用于任何垂直领域：

垂直领域	示例	范围	付款
医疗健康	运动治疗计划	12 次疗程	按次付款
咨询	按小时计费的合同	40 小时法律咨询	按月根据实际用量付款
项目	分 3 个阶段进行的前期审计	明确的里程碑	每个里程碑获批后付款

---

按垂直行业划分的证据

每个垂直行业都会通过政策定义哪些证据可以证明交付已完成。以下配置文件仅为可配置示例，并非协议的普遍要求：每份协议都可以要求不同的证据，隐私、比例原则和监管要求也会限制应收集的内容。最终的证明仅在所应用的政策及其确定性级别范围内有效；它本身不能决定服务质量，也不能绝对证明每项陈述属实。明确无歧义——事先约定的明确要求，用于生成可验证的服务证明：

医疗健康 — 4 种证据类型

证据	描述	采集方式
到达记录	到达时的时间戳，以及适用情况下的位置信息	自动
离开记录	离开时的时间戳，以及适用情况下的位置信息	自动
已签署的临床记录	与交付相关的文档或证明，适用政策要求时提供	手动
计划依从性	已执行治疗计划的核对清单	手动

示例性证明规则： 如果本政策要求的证据——到达／离开记录和已签署的记录——均已提供且有效 → 则根据本政策及其确定性级别证明交付已完成。如果缺少记录或签名 → 升级处理。

居家服务 — 4 种证据类型

证据	描述	采集方式
前期照片	附带时间戳和 GPS 的初始状态照片	手动
后期照片	附带时间戳和 GPS 的最终结果照片	手动
核对清单	标记为已完成的约定任务	手动
客户签名	确认已接收服务的客户数字签名	手动

示例性证明规则： 如果前期／后期照片均已提供且元数据有效，且核对清单已完整填写 → 则根据本政策及其确定性级别证明交付已完成。如果缺少客户签名 → 升级处理。

法律服务 — 3 种证据类型

证据	描述	采集方式
会议纪要	讨论内容和达成共识的记录	手动
文件交付	确认已交付生成的文件	手动
工时记录	可计费工时及活动说明	手动

示例性证明规则： 如果会议纪要已提供，且记录的工时处于约定范围内 → 则根据本政策及其确定性级别证明交付已完成。如果工时超出约定范围且无正当理由 → 升级处理。

教育 — 3 种证据类型

证据	描述	采集方式
出勤记录	确认学生和教师出席	自动
材料交付	已交付给学生的材料或作业	手动
评估	对课程的评估或反馈	手动

示例性证明规则： 如果已记录出勤且已交付材料 → 则根据本政策及其确定性级别证明交付已完成。如果缺少评估且合同要求提供 → 升级处理。

---

争议解决 — 设计中的扩展

争议模块（Servicialo/Disputas）仍在设计中——以下流程描述的是目标设计，并非当前已上线的功能：

1. 发起争议 — 任一方可在规定期限内发起争议。款项会自动冻结。

2. 审核证据 — 向双方索取补充证据。系统会将已记录的证据与合同进行比对。

3. 解决争议 — 如果服务提供方胜诉：已收款 → 已验证。如果客户胜诉：已取消，并恢复余额。

设计目标： 自动解决证据符合合同中预先约定规则的案件。证据无法解决的案件将升级为人工审核；同一垂直领域内的同行仲裁仍是研究方向，并非已部署的机制。

---

MCP 服务

Servicialo 将其工具作为 MCP 服务提供，让 AI Agent 能够原生发现并协调专业服务。

快速开始

@servicialo/mcp-server 包是一个轻量客户端，可连接到 Servicialo 兼容平台的 HTTP API。默认指向 Coordinalo（servicialo.com）。如果你正在构建自己的后端，请通过 SERVICIALO_BASE_URL 指向你的后端。如果你是用户组织（诊所、咨询公司等），请从所用平台获取凭据——无需直接安装此包。

npx -y @servicialo/mcp-server

完成后，你的 Agent 就可以搜索组织、查询可用时间并列出服务——无需凭据。

已验证模式

如需完成整个流程——预约、验证交付、收款：

{
  "mcpServers": {
    "servicialo": {
      "command": "npx",
      "args": ["-y", "@servicialo/mcp-server"],
      "env": {
        "SERVICIALO_API_KEY": "tu_api_key",
        "SERVICIALO_ORG_ID": "tu_org_id"
      }
    }
  }
}

各组织可从所使用的 Servicialo 兼容平台获取凭据。

Agent 的阶段 — 40 个工具

设计良好的 Agent 遵循以下顺序：

#	阶段	解决的问题	工具
0	解析	endpoint 在哪里	resolve.lookup · resolve.search · trust.get_score
1	发现	有哪些可用内容	registry.search · registry.get_organization · registry.manifest · scheduling.check_availability · services.list · a2a.get_agent_card
2	理解	服务的维度和规则	service.get · contract.get
3	承诺	客户端身份和预订	clients.get_or_create · scheduling.book · scheduling.confirm
4	管理	状态和转换	lifecycle.get_state · lifecycle.transition · scheduling.reschedule · scheduling.cancel
5	验证	已完成服务的证明	delivery.checkin · delivery.checkout · delivery.record_evidence
6	结算	文档和收款	documentation.create · payments.create_sale · payments.record_payment · payments.get_status
—	资源	实体空间和设备	resource.list · resource.get · resource.create · resource.update · resource.delete · resource.get_availability
—	解析管理	可移植性和遥测	resolve.register · resolve.update_endpoint · telemetry.heartbeat
—	网络智能	匿名市场基准数据	market.list_segments · market.get_benchmark
—	发现（冷启动）	无需先验知识即可获取分类信息——有哪些垂直领域、地区和事件	registry.list_verticals · registry.list_regions · registry.list_event_types

服务器启动时会发送匿名遥测数据，用于协议统计。可通过 SERVICIALO_TELEMETRY=false 禁用。此外，经过身份验证的服务器还会发送分桶的运行遥测数据，用于生成网络基准数据——可通过 SERVICIALO_OPERATIONAL_TELEMETRY=false 选择退出。请参阅 docs/telemetry-operational.md。

该协议确保任何 Agent 都能通过任何兼容实现完成整个周期。

完整示例

运动机能治疗 — 健康领域。GPS 签到、已签名的临床档案、银行转账付款。

电气维修 — 家庭服务领域。上门服务、维修前后照片、检查清单、客户签名、现金付款。

A2A 就绪

Servicialo 支持 A2A（Agent-to-Agent） 作为可选扩展，允许外部 Agent（Salesforce Agentforce、Google ADK 等）发现和预订服务，而无需通过 MCP。

完整指南：docs/a2a-interoperability.md

网络智能 — 市场基准

每个运行经过身份验证的 MCP 服务的节点都会发出匿名化运营事件（booking_created、service_completed、dispute_opened、payment_settled），并使用分桶值（价格按区间划分、时长按范围划分、地区精确到国家、使用 fingerprint 而非 slug）。注册中心汇总这些事件，并根据两项严格规则，按（垂直领域 × 地区 × 事件）发布分布数据：

• k-匿名性 ≥ 5 — 只有在有 ≥ 5 个不同组织贡献数据时，才会发布相应细分数据。
• 贡献后访问 — 不贡献遥测数据的节点会延迟 90 天查看数据；活跃贡献节点可实时查看。无付费层级。

两种使用方式：

• 拉取 — GET /api/benchmarks 和 GET /api/benchmarks/segments，或使用 MCP 工具 market.get_benchmark / market.list_segments。
• 推送 — 通过 Webhooks API 订阅 benchmark.weekly_snapshot 事件。注册中心每周一 00:00 UTC 触发一次快照，并附带 HMAC 签名载荷。

详情：docs/benchmarks.md · docs/telemetry-operational.md · GOVERNANCE.md · WEBHOOKS.md

---

7 项原则

#	原则
1	每项服务都有一个周期	无论是按摩还是审计都一样。协议定义了彼此独立的状态，用于观察完整周期：交付、证据、验收和结算。
2	交付必须可验证	没有足够的证据，交付就无法达到所需的确定性标准。协议定义了有效证据的构成，使人类和 AI Agent 都能信任它。
3	付款方不一定是客户	医疗服务由保险公司付款。企业服务由公司付款。教育服务由监护人付款。协议明确区分客户和付款方。
4	例外才是常态	未出席、取消、改期、争议。设计完善的服务会定义当事情未按计划进行时该如何处理。
5	服务是机器可读的产品	它有名称、价格、时长、要求和预期结果。如此定义后，任何 AI Agent 都能以与人类同等的信心发现、协调并完成服务。
6	协议与交付相互独立	服务订单定义了双方的约定。原子服务定义了实际交付的内容。这是两个不同的对象，具有不同的生命周期。
7	集体智能是协议的共同资产	每个实现该协议的节点都会贡献运营数据。汇总后的智能会让所有节点受益——就像 Waze，每位驾驶者都做出贡献，所有人的导航都会更好。没有任何一种实现拥有网络数据。

---

分层架构

只采用你需要的部分。Core 覆盖完整的交付周期。扩展为专业运营添加能力。

Servicialo Core — estable

建模专业服务端到端流程所需的一切。

适用于任何由双方达成交付承诺、并需要对实际发生的情况进行可验证核算的平台——从心理学家协会到拥有多个账户、团队和员工的清洁公司皆可。

包括：8 个维度 · 6+3 生命周期（6 个核心状态 + 3 个可选财务状态）· 6 个例外流程 · 7 项基本原则 · 资源管理 · 服务订单 · 交付证明 · MCP 协议（40 个工具）· 发现解析器（类似 DNS，基于 HTTP）· A2A 互操作性 · 网络智能（采用分桶基准数据，k-匿名性 ≥5 且贡献后访问）· 用于推送分发的 Webhooks · 无需预先了解即可发现分类体系（冷启动）

Servicialo/Finanzas — en diseño

在专业人士、组织与基础设施之间分配付款，并制定明确的结算规则。

适用于在客户与专业人士之间撮合支付，或收取佣金的平台。

Servicialo/Disputas — en diseño

正式解决争议。设计目标：自动处理证据符合预先约定规则的案件；同一垂直领域内的同行仲裁是一项研究方向。

适用于业务量足够大，或单笔服务金额使争议具有经济影响的平台。

---

Schema

用于自动验证的 JSON Schemas：schema/service.schema.json 和 schema/service-order.schema.json

# ─────────────────────────────────────────────
# SERVICIALO v0.9
# Dos entidades: Orden + Servicios atómicos
# ─────────────────────────────────────────────

orden_de_servicio:
  id: texto                      # Identificador único
  alcance: texto                 # Qué se acuerda entregar
  precio: número                 # Precio total acordado
  esquema_pagos: texto           # prepago | por_sesión | mensual
  currency: texto                # ISO 4217

  servicios[]:                   # Cada servicio atómico — 8 dimensiones

    servicio:
      id: texto
      orden_de_servicio_id: texto  # Referencia a la Orden padre
      tipo: texto                # Categoría del servicio
      vertical: texto            # salud | legal | hogar | educación | ...
      nombre: texto              # Nombre legible
      duración_minutos: entero
      visibilidad: texto         # public | unlisted | private

      proveedor:
        id: texto
        credenciales: texto[]    # Certificaciones requeridas
        puntaje_confianza: número  # 0-100 calculado por historial
        organización_id: texto

      cliente:
        id: texto
        pagador_id: texto        # Puede diferir del cliente

      agenda:
        solicitado_en: fecha_hora
        agendado_para: fecha_hora
        duración_esperada: minutos

      ubicación:
        tipo: presencial | virtual | domicilio
        dirección: texto
        recurso_id: texto        # Opcional — referencia a recurso físico

      ciclo_de_vida:
        estado_actual: enum      # 6 core + 3 financieros opcionales + excepciones
        transiciones: transición[]
        excepciones: excepción[]

      prueba_de_entrega:
        entrada: fecha_hora
        salida: fecha_hora
        duración_real: minutos
        evidencia: evidencia[]   # GPS, firma, fotos, documentos

      cobro:
        orden_de_servicio_id: texto  # Referencia a la Orden padre
        monto:
          valor: número
          moneda: texto          # ISO 4217
        pagador: referencia
        estado: pendiente | cobrado | facturado | pagado | disputado
        cobrado_en: fecha_hora
        documento_tributario: referencia  # Boleta/factura si se emitió

      mandato:                   # Delegación explícita a agente IA
        mandato_id: texto        # UUID único
        principal_id: texto      # Humano u organización
        agente_id: texto         # Agente que recibe la delegación
        alcances: texto[]        # resource:action (e.g. schedule:write)
        estado: activo | expirado | revocado | suspendido

# Ledger: proyección calculada desde entregas + términos comerciales +
# eventos de liquidación — nunca un saldo editable a mano

---

实现

任何平台都可以实现 Servicialo。要列入名录，平台必须对 8 个维度建模，实现 6 个核心状态（3 个财务状态为可选），处理 6 种异常流程中的至少 3 种，遵循 7 项基本原则，并提供至少一种实现核心配置文件的机器对机器绑定（HTTP、MCP、A2A 或其他等效方式——纯 HTTP 实现符合要求，无需 MCP；MCP 是推荐的 Agent 接入方式）。目前采用人工验证（PR + 团队审核）；自动化认证套件已列入路线图。

平台	垂直领域	覆盖范围	状态
Coordinalo	Healthcare	8/8 个维度 · 6+3 完整周期 · 6/6 种异常情况 · 7/7 项原则	已上线

Coordinalo 是参考实现，而非协议。第二个节点的机会仍然开放——请参阅 IMPLEMENTORS.md。

面向实现者

从零开始构建兼容平台的分步指南——共 8 步，第一步耗时 20 分钟。 从此处开始：IMPLEMENTING.md (English)

其他参考资料：

• schema/evidence/ — 各垂直领域的证据 Schemas（医疗、家居、法律、教育、咨询）
• ERRORS.md — 协议错误代码
• WEBHOOKS.md — 状态变更的异步通知（v0.2 — registry 事件已稳定）

---

此仓库包含的内容

servicialo/
├── app/                  # servicialo.com — sitio del protocolo (Next.js)
├── components/           # Componentes del sitio
├── examples/             # Conversaciones agente-servidor
├── lib/                  # Datos del protocolo
├── packages/
│   └── mcp-server/       # @servicialo/mcp-server — servidor MCP (npm)
├── schema/               # JSON Schemas para validación
│   ├── evidence/         # Schemas de evidencia por vertical
│   │   ├── base.schema.json       # Envelope compartido
│   │   ├── health.schema.json     # Salud
│   │   ├── home.schema.json       # Hogar
│   │   ├── legal.schema.json      # Legal
│   │   ├── education.schema.json  # Educación
│   │   └── consulting.schema.json # Consultoría
│   ├── service.schema.json
│   ├── service-order.schema.json
│   └── ...
├── protocol/
│   └── manifest.yaml     # Fuente única de verdad: versión, tools, estados, extensiones
├── SPEC.md               # Quick spec — referencia autocontenida para evaluadores
├── PROTOCOL.md           # Especificación completa
├── ERRORS.md             # Códigos de error del protocolo
├── WEBHOOKS.md           # Especificación de webhooks (v0.2)
├── IMPLEMENTORS.md       # Guía para construir una implementación
├── GOVERNANCE.md         # Gobernanza de red y política de datos
└── README.md

	版本	状态
Protocol	0.10	Draft
@servicialo/mcp-server	0.9.13	npm

---

生态系统

• 网络遥测 — 遥测报告的 MCP server 安装量（不等同于已采用该协议的实现）
• 实现者 — 经验证的协议实现
• 正在使用 Servicialo？创建 issue 以列入名录

---

许可证

Apache-2.0 — Servicialo 是一项开放协议。任何人都可以实现。