智能体（插件）开发规范

小雅开放平台支持两类外部应用：标准 MCP 智能体，以及通过 OAuth 接入的网页型智能体。两者都由开发者自己的服务承载；官网文档只在构建时生成静态页面，不会新增需要部署或启动的文档服务。

选择接入方式

场景	推荐方式	必须实现
希望小雅中的 AI 直接发现并调用工具	MCP 智能体	Manifest、initialize、tools/list、tools/call
需要独立页面、表单、订单或长期业务状态	网页型智能体	OAuth 回调、服务端 Session、开放 API 调用
两类能力都需要	混合接入	分别遵守两套边界，同一业务动作不得重复计费

Manifest

在开放平台登记的 Manifest 至少应描述稳定的应用标识、版本、展示信息、生产入口与 MCP URL。生产 URL 必须使用公网 HTTPS；回调地址必须精确匹配登记值，禁止通配符和开放重定向。

版本升级时保持工具名称稳定。删除工具、改变输入含义、扩大权限、提高价格或把同步改为异步都属于需要重新审核的契约变化。

MCP 连接顺序

小雅使用 JSON-RPC 2.0，依次执行 initialize、notifications/initialized、tools/list 和 tools/call。通知没有 id，服务端不得返回响应。

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": { "name": "xiaoya-open-platform", "version": "1.0.0" }
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

Streamable HTTP 端点应接受 application/json 与 text/event-stream，正确维护 Mcp-Session-Id，限制请求体、响应体、并发数和执行时间，并拒绝非预期重定向。

工具定义

每个工具都必须提供 inputSchema、outputSchema、标准 annotations 和完整 xiaoya/* 元数据：

{
  "name": "generate_product_brief",
  "title": "生成商品推广简报",
  "description": "根据商品资料生成结构化推广简报",
  "inputSchema": {
    "type": "object",
    "required": ["productName"],
    "properties": {
      "productName": { "type": "string", "minLength": 1, "maxLength": 120 }
    },
    "additionalProperties": false
  },
  "outputSchema": {
    "type": "object",
    "required": ["status", "summary", "data", "artifacts"],
    "properties": {
      "status": { "type": "string", "enum": ["accepted", "completed", "failed", "cancelled"] },
      "summary": { "type": "string" },
      "data": { "type": "object" },
      "artifacts": { "type": "array", "items": { "type": "object" } }
    },
    "additionalProperties": false
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": true
  },
  "_meta": {
    "xiaoya/version": "1.0.0",
    "xiaoya/pricePoints": 20,
    "xiaoya/requiredScopes": [],
    "xiaoya/executionMode": "async",
    "xiaoya/artifactTypes": ["markdown"],
    "xiaoya/timeoutSeconds": 600
  }
}

• inputSchema 必须限制 required、长度、范围、数组 items，并使用 additionalProperties: false；身份、Token、调用编号、回调地址、Team 和计费参数不得成为 AI 可填写的业务参数。
• 免费工具也要显式声明 xiaoya/pricePoints: 0；xiaoya/executionMode 只能是 sync 或 async；超时必须为 1–3600 秒。
• Artifact 类型使用 text、markdown、html、image、audio、video、file、json、table 或 link。

调用与结果

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "generate_product_brief",
    "arguments": { "productName": "小雅 Claw" }
  }
}

同步成功、异步受理和业务失败都返回标准业务 envelope：

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{ "type": "text", "text": "推广简报已生成" }],
    "structuredContent": {
      "status": "completed",
      "summary": "推广简报已生成",
      "data": { "briefId": "brief_01" },
      "artifacts": [
        {
          "type": "markdown",
          "title": "推广简报",
          "url": "https://agent.example.com/artifacts/immutable-id",
          "mimeType": "text/markdown",
          "size": 1024,
          "sha256": "<hex-digest>"
        }
      ]
    }
  }
}

Artifact URL 必须短期有效、不可猜测、只读且只授权单个产物。不要返回本地路径、内部地址或把大文件直接塞入 JSON。

调用上下文与异步回调

平台通过受保护 Header 传递调用上下文。服务端必须验证签名、时效、目标智能体和 invocation，并可调用 POST /api/v1/open-agent-tools/call-context/introspect 进行在线校验。禁止把这些 Header 转发给模型、浏览器或日志，也禁止使用共享平台 JWT Secret。

异步工具应立即返回 status: "accepted" 和稳定任务 ID。完成后使用平台签发的回调凭据调用 POST /api/v1/open-agent-tools/callbacks/{invocation_id} 提交同一 invocation 的最终 envelope；网络重试必须保持相同 invocation 和幂等身份，不得让 AI 重新发起任务。

计费规则

一个业务动作只能选择一种计费路径：

1. MCP 工具在已审核元数据中声明 xiaoya/pricePoints，由平台确认、扣费和失败退款；开发者不得再调用 /charge。
2. 网页型智能体中没有被工具价格覆盖的独立消费，由开发者后端在用户本次确认后调用 /api/v1/open/charge，失败时引用原扣费键调用 /refund。

价格、订单和幂等键必须由可信服务端产生。/balance 只用于展示，不能替代 /charge 的原子结果。

错误、安全与发布

• JSON 解析、非法请求、未知 method/tool、非法参数分别使用 -32700、-32600、-32601、-32602；业务失败使用 status: "failed" 和稳定的 data.errorCode。
• 所有外部 HTTP 请求设置明确超时；只重试幂等操作，不在外部请求期间持有数据库事务。
• invocation、订单和 callback 使用数据库唯一约束与事务保证幂等；单进程内存或 JSON 文件只能用于本地开发。
• 不记录 Authorization、OAuth Code、调用安全 Header、原始 PII、完整 Prompt 或供应商凭据。
• 发布前校验 Manifest、工具 Schema、价格、Scope、同步/异步模式和 Artifact；刷新工具快照并审核差异后再启用。工具合同变化必须重新审核。

所有开放接口的鉴权、参数、请求体和响应 Schema 请查看完整 API 参考。可直接下载的模板、校验器和离线接口说明位于小雅开放平台开发 Skill。