1．项目名称： DeiNai平台SKILL软件开发项目

2．交付物清单：

SKILL-01（高耦合版）：
    功能描述：与DeiNai平台深度耦合，需对接平台认证token体系、credits购买与消费接口。用户须先在 DeiNai 主平台（deinai.ai）注册/登录，复用平台团队订阅与积分（credits）体系；MCP 鉴权使用平台专用 MCP JWT，积分在平台订阅/加油包购买后由平台钱包扣减。与 SKILL-02 账号、积分不互通。

    【具体功能边界、输入输出参数】
    功能边界：
    - 支持：TikTok / Instagram / YouTube 红人 AI 搜索；MCP 工具 ping、get_location_ids、searchInfluencers；按实际返回红人条数 × search 单价扣 credits
    - 不支持：其他社交平台；站内建联/邮件/支付；独立 Skill 账号（sk_live_）

    MCP 工具入参/出参：
    - ping：入参无；出参 { status: "ok", service: "..." }
    - get_location_ids：必填 platform（tiktok|instagram|youtube）、location_text（string[]）；出参 { code: 0, data: { locationIds: [...] } }
    - searchInfluencers：必填 query、platform；可选 page、page_size(1-50)、followers_min/max、gender、language、has_email、locations[]、username、engagement_rate_min 等；成功 { code: 0, data: { influencers, total } }；积分不足 { code: 402, errorCode: CREDITS_INSUFFICIENT }

    工具契约参考：deinai_backend/output/clawhub/skills/creator-skill-v2/tool_specs.yaml
    运行时实现：deinai_backend/deinai_mcp/tools/*.py

    运行环境：
    - 生产服务：https://deinai.ai（FastAPI + FastMCP，/mcp 挂载于主后端）
    - 服务端 OS：Linux（Ubuntu 22.04+），Docker 部署
    - 依赖：PostgreSQL、Redis、Modash API（出站 HTTPS）
    - 反向代理：Nginx，/mcp 须 streamable-http、长超时（≥180s）、禁止 HTTPS→HTTP 302
    - 客户端桥接：Python ≥ 3.11；PyPI 包 deinai-mcp（stdio → 远程 MCP）
    - 客户端：Cursor、Claude Desktop、OpenClaw、Coze（MCP 或 Legacy REST）

    对接接口：
    - 用户登录：https://deinai.ai 门户，获取登录 JWT
    - MCP Token 创建：POST https://deinai.ai/api/v1/mcp/tokens（Bearer 登录 JWT），返回 data.jwt_token（仅展示一次）
    - MCP Token 管理：GET/PATCH /api/v1/mcp/tokens、/tokens/{id}/disable（Bearer 登录 JWT）
    - MCP 业务：streamable-http https://deinai.ai/mcp（Bearer MCP JWT），工具 ping / get_location_ids / searchInfluencers，资源 app://info
    - 积分/钱包：GET /api/v1/wallets/...（Bearer 登录 JWT），余额、流水
    - 充值/订阅：POST /api/v1/wallets/topup 及平台支付相关 API（Bearer 登录 JWT）
    - Legacy REST 搜索：POST /api/v1/discovery/smart-discovery-v2（Bearer 登录 JWT，Coze 旧路径，新接入不推荐）
    - Stdio 桥接：PyPI deinai-mcp-match，环境变量 DEINAI_MCP_TOKEN，可选 DEINAI_MCP_URL
  上架物料路径：E:\CodeProject\deinai_backend\output\（ClawHub、MCP Registry、Coze SOP，不含业务密钥）

SKILL-02（无耦合版）：
    功能描述：独立运行，从注册、订阅到使用均可由 Claw 自动完成，与 DeiNai 平台无耦合关系。拥有独立账号、Session/API Token、钱包、订阅与 Stripe 支付；注册→订阅→创建 Token→MCP 搜索可由 OpenClaw / Claw Agent 全自动完成。

    【具体功能边界、输入输出参数】
    功能边界：
    - 支持：独立邮箱注册/登录；Stripe 月付订阅（starter/pro/growth）；MCP 三工具 + REST 等价搜索；门户 /portal/（登录、订阅、Token 管理）；OpenClaw 测试环境自动化支付端点
    - 不支持：复用 deinai.ai 登录；与平台钱包/积分互通

    Token 体系：
    - Session（sk_sess_）：门户、创建 API Token、订阅 checkout
    - API Token（sk_live_）：MCP、REST 搜索、账户状态查询

    核心 REST API：
    - POST /api/v1/auth/register：入参 email、password、displayName?；出参 accountId、email
    - POST /api/v1/auth/login：入参 email、password；出参 sessionToken（sk_sess_）、expiresAt
    - GET  /api/v1/account/status：鉴权 sk_live_；出参 balance、canSearch、needsRecharge、needsRenewal 及引导 URL
    - GET  /api/v1/subscriptions/plans：出参 plans[]
    - POST /api/v1/subscriptions/checkout：鉴权 sk_sess_；入参 plan_code（starter|pro|growth）、channel=stripe；出参 checkoutUrl、orderNo
    - GET  /api/v1/subscriptions/orders/{order_no}：鉴权 sk_sess_；出参 paymentSucceeded、creditsGranted
    - POST /api/v1/tokens：鉴权 sk_sess_；入参 name、expires_in_days?；出参 token（sk_live_，仅一次）
    - POST /api/v1/search/influencers：鉴权 sk_live_；入参与 MCP searchInfluencers 对齐（支持 camelCase）
    - POST /api/v1/search/locations：鉴权 sk_live_；入参 platform、locationText[]
    - GET  /health：出参 { status: "ok" }

    MCP：https://skill.deinai.ai/mcp（streamable-http，Bearer sk_live_），工具入参/出参与 SKILL-01 契约一致。

    订阅套餐（生产参考）：
    - starter 基础版：月付 1200 积分，参考价 ¥49
    - pro     专业版：月付 6000 积分，参考价 ¥199
    - growth  增长版：月付 20000 积分，参考价 ¥499

    运行环境：
    - 生产域名：https://skill.deinai.ai
    - 代码路径：E:\CodeProject\apps\skill-service
    - 运行时：Python ≥ 3.11，FastAPI + Uvicorn + FastMCP
    - 容器：Docker Compose（服务端口 8080）
    - 数据库：独立 PostgreSQL 库 skills（与 deinai_prod 分离）
    - 缓存：Redis（可选）
    - 支付：Stripe Live；Webhook /api/v1/payments/stripe/notify
    - 外部依赖：Modash API（api.modash.io）
    - PyPI / Registry：包名 skill-service；Registry ai.deinai/creator-skill-v2；ClawHub creator-skill-v2
    - 测试环境：https://ai.hsiangyaya.top

    注册/订阅/使用流程：
    1. GET  /health
    2. POST /api/v1/auth/register（或 login）
    3. GET  /api/v1/subscriptions/plans
    4. POST /api/v1/subscriptions/checkout（plan_code=starter, channel=stripe）
    5. Stripe Checkout 支付（或测试环境 automation 端点模拟）
    6. GET  /api/v1/subscriptions/orders/{order_no} 轮询至 paymentSucceeded
    7. POST /api/v1/tokens → 获得 sk_live_
    8. openclaw mcp set creator-skill-v2（url + Bearer sk_live_）
    9. GET  /api/v1/account/status → canSearch=true
    10. MCP ping → get_location_ids → searchInfluencers

SKILL-01 与 SKILL-02 对照：
    - 服务基址：deinai.ai / skill.deinai.ai
    - 账号：DeiNai 平台用户/团队 / 独立 Skill 账号
    - MCP 鉴权：MCP JWT / sk_live_
    - 积分来源：平台订阅+加油包 / Stripe 订阅+充值
    - PyPI 桥接包：deinai-mcp / skill-service

3．软件支持的环境：
    - 服务端 OS：Linux Ubuntu 22.04+（推荐）；本地开发支持 Windows / macOS
    - 容器：Docker、Docker Compose
    - 反向代理：Nginx（TLS 终止、MCP 长连接代理）
    - Python：≥ 3.11（服务端与 stdio 桥接）
    - 数据库：PostgreSQL 14+（SKILL-02 独立库 skills；SKILL-01 使用平台库）
    - 缓存：Redis 6+（SKILL-01 必需；SKILL-02 可选）
    - AI 客户端：OpenClaw、Cursor、Claude Desktop（remote MCP 或 stdio 桥接）、Coze 扣子
    - 浏览器：Chrome / Edge / Safari / Firefox 最新两个大版本（门户登录、Stripe Checkout）
    - 网络：公网 HTTPS；出站访问 Modash API、Stripe API
    - 社交平台：搜索目标 TikTok、Instagram、YouTube

4．开发目标：软件整体功能符合甲方描述的要求，应达到正确性、效率、安全性、可靠性等技术指标。

    正确性：MCP 三工具契约与 tool_specs.yaml 一致；搜索按返回条数扣费；account/status 门控准确（canSearch）。验证：e2e_openclaw_flow.py、smoke_mcp.py、OpenClaw E2E。

    效率：MCP 搜索支持 180s 超时；异步 FastAPI；Nginx /mcp 关闭缓冲、长读超时 ≥300s。

    安全性：Bearer 鉴权；Session / API Token 职责分离；MCP 禁止 HTTPS→HTTP 重定向（防 Authorization 丢失）；密钥不入库；Stripe Webhook 签名校验。

    可靠性：GET /health 探活；Stripe Webhook 幂等入账；订阅续费/取消事件处理；订单状态可轮询。
