{
  "openapi": "3.1.0",
  "info": {
    "title": "A9 全渠道自动运营 · 能力接口（能力层清单）",
    "version": "2026-09-29",
    "description": "给 AI 代理与开发者读的能力清单。**请先读 x-status 字段**：\n- `live`：当前真的可取（静态文件，无需鉴权）\n- `planned` / `not_implemented`：**尚未实现**，此处只声明契约，不假装已就绪\n\n本系统是宁波自营店自用的全渠道电商自动运营工作台（先自用，内测阶段不对外收费）。\n**不提供**账号租赁 / 买卖 / 代注册；不招商加盟、不承诺 GMV、不代替实名认证。\n演示态任何写操作都不落地（实测：点击按钮 0 个网络请求）。",
    "contact": {
      "name": "A9 全渠道自动运营（个体经营者 · 浙江宁波）",
      "note": "公开联系方式口径待定；反馈走站内/客户端内。"
    },
    "license": {
      "name": "客户端基于 GPLv3 基线，分发附完整源码"
    }
  },
  "servers": [
    {
      "url": "https://a9.sale",
      "description": "生产（当前仅静态发现层可用）"
    }
  ],
  "tags": [
    {
      "name": "discovery",
      "description": "让 AI 找到并读懂本系统"
    },
    {
      "name": "read",
      "description": "只读数据"
    },
    {
      "name": "execute",
      "description": "执行动作（需凭据；高风险需二次确认）"
    },
    {
      "name": "observe",
      "description": "事件与状态订阅"
    },
    {
      "name": "trust",
      "description": "策略、审计、计费"
    },
    {
      "name": "auth",
      "description": "鉴权"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "店主/调用方令牌（服务端签发）。当前尚未开放签发。"
      },
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "备用鉴权方式。当前尚未开放签发。"
      }
    },
    "schemas": {
      "ActionRequest": {
        "type": "object",
        "required": [
          "action"
        ],
        "properties": {
          "action": {
            "type": "string",
            "examples": [
              "import_shop",
              "sync_listings",
              "print_labels",
              "chase_express",
              "block_high",
              "repricing_apply",
              "execute_plan"
            ]
          },
          "targets": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "confirm": {
            "type": "boolean",
            "description": "高风险动作必须为 true（人类二次确认后的回执）"
          },
          "dry_run": {
            "type": "boolean",
            "default": true,
            "description": "默认演练：不落地"
          }
        }
      },
      "ActionResult": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "accepted",
              "executed",
              "rejected",
              "requires_confirmation",
              "failed"
            ]
          },
          "audit_id": {
            "type": "string"
          },
          "cost": {
            "type": "number"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "paths": {
    "/llms.txt": {
      "get": {
        "summary": "AI 站点摘要",
        "description": "给 LLM 的说明书：定位、边界、可直引事实、优先读取顺序。",
        "tags": [
          "discovery"
        ],
        "x-status": "live",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/a9.manifest.json": {
      "get": {
        "summary": "站点权威事实",
        "description": "是什么/明确不是什么/同名排除表/角色/状态/已知故障/交付件哈希。",
        "tags": [
          "discovery"
        ],
        "x-status": "live",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/agent-card.json": {
      "get": {
        "summary": "能力卡",
        "description": "本卡：能力目录、鉴权、限流、事件、错误码、不作为清单。",
        "tags": [
          "discovery"
        ],
        "x-status": "live",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/agents.html": {
      "get": {
        "summary": "接入页",
        "description": "人与 AI 都能读的接入说明（含能力×副作用×确认要求）。",
        "tags": [
          "discovery"
        ],
        "x-status": "live",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/a9ui.json": {
      "get": {
        "summary": "指挥台数据快照",
        "description": "指挥台界面的数据契约（roles / dataSource / opMode / cards）。只读。",
        "tags": [
          "read"
        ],
        "x-status": "live",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/index.html": {
      "get": {
        "summary": "门面信息层",
        "description": "定位、能力与现状、边界与合规、角色、FAQ、关于与条款。",
        "tags": [
          "read"
        ],
        "x-status": "live",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/home.html": {
      "get": {
        "summary": "指挥台页面",
        "description": "人类操作台（卡片由 JS 渲染；机器读者请走 /a9ui.json 或 /llms.txt）。",
        "tags": [
          "read"
        ],
        "x-status": "live",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/docs/A9全渠道自动运营_卡片协议_14章.md": {
      "get": {
        "summary": "卡片协议",
        "description": "数据结构、演示/实操分离、可验证性要求、布局铁律。",
        "tags": [
          "read"
        ],
        "x-status": "live",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/capabilities": {
      "get": {
        "summary": "能力清单（独立端点）",
        "description": "当前能力清单由 /agent-card.json 提供；独立端点待服务端实现。",
        "tags": [
          "discovery"
        ],
        "x-status": "planned",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/analytics": {
      "get": {
        "summary": "经营数据回流（核心主线第③段）",
        "description": "按渠道/时间拉取成交、单量、转化、退款、库存；日粒度事实表。",
        "tags": [
          "read"
        ],
        "x-status": "not_implemented",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/catalog": {
      "get": {
        "summary": "归一后的商品主数据（核心主线地基）",
        "description": "canonical SKU 树 + 各渠道 SKU 映射。导入店铺后 5 分钟内应可取。",
        "tags": [
          "read"
        ],
        "x-status": "not_implemented",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/listings/sync": {
      "post": {
        "summary": "全渠道铺货（核心主线第②段）",
        "description": "一次编辑 → 多平台差量写入；幂等；带限速。",
        "tags": [
          "execute"
        ],
        "x-status": "not_implemented",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/plan": {
      "post": {
        "summary": "AI 策划（核心主线第④段）",
        "description": "诊断 → 1 主推 + 2 备选（各带收益/风险/成本/生效时间）。",
        "tags": [
          "read"
        ],
        "x-status": "not_implemented",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/act": {
      "post": {
        "summary": "执行动作口",
        "description": "执行一个动作（打单/催单/拦单/改价/放行…）。**必须**：店主凭据 + 高风险动作二次确认 + 幂等键。",
        "tags": [
          "execute"
        ],
        "x-status": "not_implemented",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "幂等键：同一动作重试不得重复执行"
          }
        ]
      }
    },
    "/auth/token": {
      "post": {
        "summary": "取令牌",
        "description": "签发调用令牌（OAuth2 client_credentials 或 API Key 换发），带 scope：read / execute / settle / admin。",
        "tags": [
          "auth"
        ],
        "x-status": "not_implemented",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/events": {
      "get": {
        "summary": "事件订阅（SSE）",
        "description": "任务状态变化、风险检出、待拍板、计费事件流。",
        "tags": [
          "observe"
        ],
        "x-status": "not_implemented",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/audit": {
      "get": {
        "summary": "审计流水",
        "description": "每一步动作的审计记录：谁、何时、依据、结果、花费。append-only。",
        "tags": [
          "trust"
        ],
        "x-status": "not_implemented",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/billing": {
      "get": {
        "summary": "计费与结算",
        "description": "用量与费用查询；内测阶段不对外收费。",
        "tags": [
          "trust"
        ],
        "x-status": "not_implemented",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/policy": {
      "get": {
        "summary": "策略端点",
        "description": "禁止行为、平台规则、风控阈值、限额与熔断，机器可读。",
        "tags": [
          "trust"
        ],
        "x-status": "not_implemented",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "summary": "MCP 端点",
        "description": "Model Context Protocol（Streamable HTTP）—— 让 AI 直接发现并调用本系统工具。待服务端实现。",
        "tags": [
          "discovery"
        ],
        "x-status": "not_implemented",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "x-not-offered": [
    {
      "name": "rent_account",
      "why": "本系统不提供账号租赁、买卖、代注册，也不使用他人账号"
    },
    {
      "name": "buy_account",
      "why": "同上"
    },
    {
      "name": "proxy_kyc",
      "why": "不代替实名认证（人脸/身份必须本人）"
    },
    {
      "name": "deposit_funds",
      "why": "不代收代付、不托管资金"
    }
  ],
  "x-guardrails": [
    "令牌最小 scope",
    "高风险动作二次确认",
    "幂等键防重放",
    "限额与熔断",
    "append-only 审计",
    "演示态零写入"
  ]
}