{
  "openapi": "3.1.0",
  "info": {
    "title": "member-marketing Agent API",
    "version": "0.6.0",
    "description": "商品中心、增长/转化/用户运营 Skills、统一记忆协议、阶段固定工作流、Agent 工具网关、企微审批待办、交付物与 Sandbox Agent。"
  },
  "servers": [{ "url": "https://ops.chengyuan.team/member-marketing" }],
  "components": {
    "securitySchemes": {
      "basicAuth": { "type": "http", "scheme": "basic" },
      "internalApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" },
      "agentToken": { "type": "apiKey", "in": "header", "name": "X-Agent-Token" }
    },
    "schemas": {
      "GatewayCall": {
        "type": "object",
        "required": ["tool"],
        "properties": {
          "tool": { "type": "string" },
          "params": { "type": "object" },
          "dry_run": { "type": "boolean", "default": false }
        }
      },
      "ArtifactUpload": {
        "type": "object",
        "required": ["task_id", "file_name"],
        "properties": {
          "task_id": { "type": "string" },
          "run_id": { "type": "string" },
          "file_name": { "type": "string" },
          "mime_type": { "type": "string" },
          "artifact_type": { "type": "string" },
          "content_text": { "type": "string" },
          "content_base64": { "type": "string" },
          "metadata": { "type": "object" }
        }
      },
      "SandboxStart": {
        "type": "object",
        "required": ["task_id", "agent_id"],
        "properties": {
          "task_id": { "type": "string" },
          "agent_id": { "type": "string" },
          "backend": { "type": "string", "enum": ["filesystem", "docker", "sandbox_agent", "openai_sandbox"] },
          "input": { "type": "object" }
        }
      },
      "MemoryCandidate": {
        "type": "object",
        "required": ["agent_id", "memory_type", "claim", "evidence_refs", "source_version"],
        "properties": {
          "agent_id": { "type": "string" },
          "memory_type": { "type": "string", "enum": ["business_rule", "metric_definition", "system_fact", "field_mapping", "playbook", "risk_rule", "experiment_learning"] },
          "scope": { "type": "string", "default": "agent" },
          "claim": { "type": "string" },
          "evidence_refs": { "type": "array", "minItems": 1, "items": { "type": "string" } },
          "sample_size": { "type": "integer", "minimum": 0 },
          "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
          "metric_definition": { "type": "object" },
          "applicable_conditions": { "type": "array" },
          "invalid_conditions": { "type": "array" },
          "tags": { "type": "array", "items": { "type": "string" } },
          "source_task_id": { "type": "string" },
          "source_run_id": { "type": "string" },
          "source_version": { "type": "string" },
          "expires_at": { "type": "string", "format": "date-time" },
          "supersedes_id": { "type": "string" }
        }
      },
      "MemoryReview": {
        "type": "object",
        "required": ["memory_id", "decision"],
        "properties": {
          "memory_id": { "type": "string" },
          "decision": { "type": "string", "enum": ["verify", "reject", "revoke"] },
          "note": { "type": "string" }
        }
      },
      "SandboxSession": {
        "type": "object",
        "required": ["task_id", "project_id"],
        "properties": {
          "task_id": { "type": "string" },
          "project_id": { "type": "string" },
          "mode": { "type": "string", "enum": ["read", "write"], "default": "read" },
          "approval_id": { "type": "string" }
        }
      },
      "SandboxAction": {
        "type": "object",
        "required": ["session_id", "action"],
        "properties": {
          "session_id": { "type": "string" },
          "action": { "type": "string", "enum": ["tree", "read_file", "search", "git_status", "git_diff", "run_test", "write_file"] },
          "path": { "type": "string" },
          "query": { "type": "string" },
          "command_id": { "type": "string" },
          "content": { "type": "string" },
          "expected_sha256": { "type": "string" },
          "approval_id": { "type": "string" }
        }
      },
      "ArticleStatsIngest": {
        "type": "object",
        "required": ["account", "articles"],
        "properties": {
          "account": { "type": "string" },
          "collected_date": { "type": "string", "format": "date" },
          "source": { "type": "string" },
          "articles": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["msg_id", "item_idx"],
              "properties": {
                "product_id": { "type": "string" },
                "article_id": { "type": "string" },
                "msg_id": { "type": "string" },
                "item_idx": { "type": "integer" },
                "corresponding_article_key": { "type": "string" },
                "title": { "type": "string" },
                "read_uv": { "type": ["integer", "null"] },
                "avg_read_time_minutes": { "type": ["number", "null"] },
                "new_follow_uv": { "type": ["integer", "null"] },
                "share_uv": { "type": ["integer", "null"] },
                "paid_users": { "type": ["integer", "null"] },
                "actual_revenue": { "type": ["number", "null"] }
              },
              "additionalProperties": true
            }
          }
        }
      }
    }
  },
  "security": [{ "basicAuth": [] }],
  "paths": {
    "/api/tasks/tool-gateway/manifest": {
      "get": { "summary": "按 X-Agent-ID 查询工具白名单", "parameters": [{ "in": "header", "name": "X-Agent-ID", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "工具清单" } } }
    },
    "/api/tasks/tool-gateway/status": {
      "get": { "summary": "工具网关健康状态", "responses": { "200": { "description": "检查结果" } } }
    },
    "/api/tasks/tool-gateway/call": {
      "post": { "summary": "调用 Agent 白名单工具", "parameters": [{ "in": "header", "name": "X-Agent-ID", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "X-Task-ID", "schema": { "type": "string" } }, { "in": "header", "name": "X-Run-ID", "schema": { "type": "string" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GatewayCall" } } } }, "responses": { "200": { "description": "工具调用结果" }, "403": { "description": "Agent 无该工具权限" } } }
    },
    "/api/tasks/execution-result": {
      "post": { "summary": "回写带证据的真实任务结果并执行完成门禁", "security": [{ "internalApiKey": [] }], "responses": { "200": { "description": "结果与完成门禁均通过，任务置为 done" }, "422": { "description": "业务结果或完成证据不完整" } } }
    },
    "/api/tasks/completion-gate/status": {
      "post": { "summary": "查询任务工作流、工具、交付物和接收验收证据", "security": [{ "internalApiKey": [], "agentToken": [] }], "responses": { "200": { "description": "完成门禁状态" } } }
    },
    "/api/crm5173/daily-articles/topics": {
      "get": { "summary": "查询日运选题元数据与来源证明（无客户 PII）", "parameters": [{ "in": "query", "name": "date", "schema": { "type": "string", "format": "date" } }, { "in": "query", "name": "stem", "schema": { "type": "string" } }], "responses": { "200": { "description": "日运主题列表" } } }
    },
    "/api/tasks/wecom-moments/cancel": {
      "post": { "summary": "撤销原申请人尚未审批的朋友圈请求", "security": [{ "internalApiKey": [] }], "responses": { "200": { "description": "已撤销" }, "403": { "description": "非原申请人/编排器/QA" }, "409": { "description": "请求已批准或已执行" } } }
    },
    "/api/products": {
      "get": { "summary": "商品中心列表", "responses": { "200": { "description": "Notion 商品与公众号付费映射" } } }
    },
    "/api/products/summary": {
      "get": { "summary": "商品中心汇总", "responses": { "200": { "description": "商品和付费汇总" } } }
    },
    "/api/products/writeback-status": {
      "get": { "summary": "付费数据回写 Notion 的定时配置与最近记录", "parameters": [{ "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 30, "default": 8 } }], "responses": { "200": { "description": "enabled、scheduler_running、interval_minutes、daily_time、next_daily_run_at、in_flight、latest_run、runs" } } }
    },
    "/api/products/writeback-trigger": {
      "post": { "summary": "立即回写付费人数与统计日期到 Notion 付费文章库（来源 manual_ui）", "responses": { "200": { "description": "回写完成，data.run 含 id、status、updated_count、failed_count" }, "207": { "description": "部分失败" }, "500": { "description": "回写失败或超时" } } }
    },
    "/api/products/writeback": {
      "post": { "summary": "服务调用回写；dry_run 默认 true，仅预览候选", "security": [{ "internalApiKey": [] }], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "dry_run": { "type": "boolean", "default": true }, "trigger_source": { "type": "string" } } } } } }, "responses": { "200": { "description": "回写结果" }, "207": { "description": "部分失败" }, "401": { "description": "服务密钥无效" } } }
    },
    "/api/products/writeback-runs": {
      "get": { "summary": "回写审计记录（含逐商品明细与下游同步结果）", "security": [{ "internalApiKey": [] }], "parameters": [{ "in": "query", "name": "limit", "schema": { "type": "integer", "maximum": 200, "default": 50 } }], "responses": { "200": { "description": "记录列表；状态 running/success/noop/partial/failed/interrupted/dry_run" }, "401": { "description": "服务密钥无效" } } }
    },
    "/api/tasks/wechat-article-collection/start": {
      "post": { "summary": "在 59 启动公众号 appmsganalysis 单篇深度采集", "security": [{ "internalApiKey": [] }], "responses": { "202": { "description": "采集任务已接受" } } }
    },
    "/api/tasks/wechat-article-collection/status": {
      "get": { "summary": "查询 59 采集状态、统一账号注册表和回流快照", "security": [{ "internalApiKey": [] }], "responses": { "200": { "description": "采集状态" } } }
    },
    "/api/tasks/wechat-article-collection/stop": {
      "post": { "summary": "停止 59 公众号深度采集", "security": [{ "internalApiKey": [] }], "responses": { "200": { "description": "停止请求已接受" } } }
    },
    "/api/tasks/article-stats-ingest": {
      "post": { "summary": "写入单篇公众号传播指标", "security": [{ "internalApiKey": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArticleStatsIngest" } } } }, "responses": { "200": { "description": "写入结果" } } }
    },
    "/api/tasks/article-stats": {
      "get": { "summary": "查询单篇公众号传播指标", "security": [{ "internalApiKey": [] }], "responses": { "200": { "description": "最新或历史快照" } } }
    },
    "/api/artifacts": {
      "post": { "summary": "上传 Agent 交付物", "security": [{ "internalApiKey": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactUpload" } } } }, "responses": { "201": { "description": "交付物记录与 SHA-256" } } },
      "get": { "summary": "查询 Agent 交付物", "security": [{ "internalApiKey": [] }], "responses": { "200": { "description": "交付物列表" } } }
    },
    "/api/artifacts/{artifactId}/download": {
      "get": { "summary": "下载交付物", "parameters": [{ "in": "path", "name": "artifactId", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "文件内容" }, "404": { "description": "不存在" } } }
    },
    "/api/sandbox/runs": {
      "post": { "summary": "登记 sandbox 运行", "security": [{ "internalApiKey": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxStart" } } } }, "responses": { "201": { "description": "运行记录" } } },
      "get": { "summary": "查询 sandbox 运行", "security": [{ "internalApiKey": [] }], "responses": { "200": { "description": "运行列表" } } }
    },
    "/api/sandbox/runs/complete": {
      "post": { "summary": "完成运行并绑定 artifact_ids", "security": [{ "internalApiKey": [] }], "responses": { "200": { "description": "完成记录与证据" } } }
    },
    "/api/agent-memory/protocol": {
      "get": { "summary": "读取统一记忆协议", "security": [{ "internalApiKey": [] }], "responses": { "200": { "description": "协议、类型、状态机和升格门槛" } } }
    },
    "/api/agent-memory": {
      "get": { "summary": "查询 Agent 长期记忆", "security": [{ "internalApiKey": [] }], "responses": { "200": { "description": "默认返回未过期 verified 记忆" } } }
    },
    "/api/agent-memory/candidates": {
      "post": { "summary": "创建长期记忆候选", "security": [{ "internalApiKey": [], "agentToken": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryCandidate" } } } }, "responses": { "201": { "description": "候选记忆" }, "422": { "description": "证据不足或包含敏感信息" } } }
    },
    "/api/agent-memory/review": {
      "post": { "summary": "验收、驳回或撤销长期记忆", "security": [{ "internalApiKey": [], "agentToken": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryReview" } } } }, "responses": { "200": { "description": "更新后的记忆" }, "403": { "description": "非 QA/调度审核角色" }, "409": { "description": "未满足升格门槛" } } }
    },
    "/api/agent-memory/usage": {
      "post": { "summary": "记录 verified 记忆使用结果", "security": [{ "internalApiKey": [] }], "responses": { "200": { "description": "记忆使用回执" } } }
    },
    "/api/sandbox/agent/health": {
      "get": { "summary": "Sandbox Agent 健康和配置状态", "security": [{ "internalApiKey": [] }], "responses": { "200": { "description": "远程或内置快照模式、健康状态和项目白名单" } } }
    },
    "/api/sandbox/agent/projects": {
      "get": { "summary": "列出允许的 Sandbox 项目", "security": [{ "internalApiKey": [] }], "responses": { "200": { "description": "脱敏项目列表" } } }
    },
    "/api/sandbox/agent/sessions": {
      "post": { "summary": "创建隔离开发会话", "security": [{ "internalApiKey": [], "agentToken": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxSession" } } } }, "responses": { "201": { "description": "会话" }, "403": { "description": "项目或写权限不允许" } } },
      "get": { "summary": "查询隔离开发会话", "security": [{ "internalApiKey": [] }], "responses": { "200": { "description": "会话状态和审计摘要" } } }
    },
    "/api/sandbox/agent/actions": {
      "post": { "summary": "执行 Sandbox 白名单动作", "security": [{ "internalApiKey": [], "agentToken": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxAction" } } } }, "responses": { "200": { "description": "动作结果" }, "403": { "description": "动作或审批不允许" }, "409": { "description": "SHA-256 乐观锁失败" } } }
    },
    "/api/projects/actions/project-create": {
      "post": { "summary": "创建通用业务项目、阶段、分工与依赖", "security": [{ "internalApiKey": [], "agentToken": [] }], "responses": { "200": { "description": "项目详情" }, "409": { "description": "重复阶段或冲突" } } }
    },
    "/api/projects/actions/campaign-create": {
      "post": { "summary": "在项目下创建 Campaign 并生成阶段任务", "security": [{ "internalApiKey": [], "agentToken": [] }], "responses": { "200": { "description": "Campaign、项目和任务列表" } } }
    },
    "/api/h5-activation/delivery-attempts/reconcile": {
      "post": { "summary": "从企微官方接口核验已提交的私域触达", "security": [{ "internalApiKey": [] }], "responses": { "200": { "description": "真实发送、待成员确认、失败及错误数量" }, "403": { "description": "调用角色无权核验" } } }
    },
    "/api/h5-activation/campaigns/repair-execution-state": {
      "post": { "summary": "修复 H5 战役错误完成态并重建阶段门禁", "security": [{ "internalApiKey": [] }], "responses": { "200": { "description": "apply=false 返回修复预览；apply=true 返回修复后的任务与批次状态" }, "409": { "description": "活动批次不存在或无法安全冻结" } } }
    },
    "/api/wecom-approval-todos/status": {
      "get": { "summary": "读取企微审批待办配置、权限与同步状态", "responses": { "200": { "description": "模板、审批人、活动待办数及按状态统计" } } }
    },
    "/api/wecom-approval-todos": {
      "get": {
        "summary": "查询 Agent 人工闸门与企微审批单映射",
        "parameters": [
          { "in": "query", "name": "status", "schema": { "type": "string" } },
          { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }
        ],
        "responses": { "200": { "description": "企微审批待办列表" } }
      }
    },
    "/api/wecom-approval-todos/sync": {
      "post": { "summary": "扫描待审批来源、幂等创建企微审批并回收审批结果", "responses": { "200": { "description": "同步、提交、解析与执行数量" } } }
    },
    "/api/wecom-approval-todos/{todoId}/retry": {
      "post": {
        "summary": "重试企微审批同步、轮询或批准后的执行动作",
        "parameters": [{ "in": "path", "name": "todoId", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "重试结果" }, "404": { "description": "待办不存在" }, "409": { "description": "当前状态不可重试" } }
      }
    }
  }
}