文档控制信息

PRD｜产品需求说明

1. 背景与问题

• 用户想要的是可直接使用的成果（报告/PPT/海报/网站/脚本），而不是一段聊天记录。
• 单一对话式 AI 体验难以处理：长任务、并行任务、跨工具执行、审核/合规、多人协作。
• 竞品分化明显：Genspark 偏“页面化研究+工作台”、Lovart 偏“画布化创作”、Manus 偏“执行型虚拟同事”。

2. 产品愿景与目标

3. 非目标（明确不做）

• 不做“通用模型训练/自研基础大模型”（使用 Claude 等外部模型 + 可选企业自带模型路由）。
• 不在 v1 做“完全开放的用户自定义代码插件市场”（先做受控的 Skills + MCP 连接器）。
• 不在 v1 做“完全实时协同编辑（像 Figma 那样）”，先做“基于版本/评论的协作”。

4. 目标用户与角色

5. 关键产品原则

• Artifact-first：成果是第一公民（Page/Canvas/Run 的产物可发布、可版本化、可审计）。
• Human-in-the-loop：高风险动作必须审批（发送邮件、外部写入、支付、删除）。
• Deterministic where it matters：关键步骤结构化输出（JSON Schema），可校验可重试。
• Secure by default：默认最小权限；工具访问需显式授权；沙箱隔离。
• Transparent cost：执行前给出 credits 预估；执行中给出成本分解。
• Workflow as product：每个成功流程可一键固化为模板，成为可复用资产。

6. 核心体验：四工作区（Workspaces）

7. 功能需求（FRD）分解

以下按模块列出 v1 需要交付的“工程可验收”功能点（每点可拆成 tickets）：

7.1 账号与组织（Auth/Org）

• 邮箱/第三方登录；可选 MFA（TOTP）。
• 组织：Org、Team、Project 多级归属；成员邀请、角色管理。
• 企业：SSO（OIDC/SAML）、域名验证、SCIM（后续）。

7.2 项目与产物（Project/Artifact）

• Project：包含多个 Artifacts、Runs、Workflows、Skills 安装记录。
• Artifact：Page/Canvas/Run-output/File 等类型；支持版本、标签、分享链接（权限）。
• 导出：PDF/MD/Docx/PNG/SVG/MP4/ZIP（按类型）。

7.3 Workflow Builder（可视化/DSL）

• 节点：Agent Step / Tool Step / Skill Step / Subagent Step / Human Step / Artifact Step。
• 触发：手动、定时（cron）、Webhook（外部系统触发）。
• 版本：每次发布生成 workflow_version，可回滚。
• 运行：workflow_run 可回放；节点支持重试、跳过、回滚策略。

7.4 Skills 市场（公共 + 组织私有）

• Skill 包：描述、版本、所需工具权限、依赖、示例。
• 安装：组织/项目级安装；启用范围（所有项目/指定项目）。
• 审核：静态扫描 + 动态沙箱测试（见 Tech Spec）。

7.5 Tool/MCP 连接器

• 连接器授权：OAuth 授权、token vault、安全域隔离。
• MCP Server：注册/启用/禁用/白名单；工具调用配额。
• 审批：对写入类工具默认需要审批（可由管理员策略调整）。

7.6 计费与用量（Billing/Metering）

• 套餐：Free / Pro / Team / Enterprise（可配置）。
• Credits：统一点数（内部拆分 token/tool/compute/storage/concurrency）。
• 预估：Run/Workflow 启动前给出 cost estimate（范围 + 置信度）。
• 账单：用量明细、发票、团队分摊、预算报警。

7.7 可观测与合规（Obs/Audit）

• Run trace：每一步的输入/输出摘要、工具参数、耗时、消耗。
• 审计：谁在何时授权了什么 connector、做了什么外部写入。
• 数据保留：按组织策略设置（7/30/180 天或自定义）。

8. 权限矩阵（简版）

9. 成功指标（KPI）

• Activation：D1 激活率（完成第一个可导出的交付物）、TTV（首次价值时间）。
• Reliability：Run 完成率、平均重试次数、失败可定位率。
• Efficiency：平均成本/任务、平均耗时、cache 命中率。
• Growth：分享率、模板复用率、组织新增率。
• Revenue：付费转化率、ARPA、credits 续费率。

10. 发布计划（建议节奏）

1. A：Run 执行层 + Tool trace + 审批 + Artifact store（先让“能干活”）
2. B：Page Workspace + 引用 + 发布/导出（研究交付闭环）
3. C：Canvas Workspace + 批注/Inspector/导出（创意交付闭环）
4. D：Workflow Builder + Skills Registry + Team 治理（平台化增长）

Tech Spec｜技术规格说明

1. 系统总体架构（Control/Data Plane）

复制
                ┌───────────────────────────┐
                │          Web / App         │
                │ Chat · Page · Canvas · Run │
                └─────────────┬─────────────┘
                              │ SSE/WS + REST
                       ┌──────▼──────┐
                       │ API Gateway  │  (AuthN, Rate limit, Idempotency)
                       └───┬─────┬───┘
                           │     │
              ┌────────────▼─┐ ┌─▼─────────────┐
              │ Identity/Org  │ │ Billing/Meter │
              │ RBAC/SSO      │ │ Credits/Ledger│
              └──────┬────────┘ └──────┬────────┘
                     │                 │
          ┌──────────▼──────────┐  ┌──▼────────────────┐
          │ Project/Artifact Svc │  │ Skill/Workflow Reg │
          │ DB + Object Storage  │  │ Version + Policy   │
          └──────────┬──────────┘  └──┬────────────────┘
                     │                │
                     │ enqueue steps  │
               ┌─────▼───────────────▼─────┐
               │        Workflow Engine     │
               │ DAG · retries · approvals  │
               └─────┬───────────────────┬─┘
                     │                   │
         ┌───────────▼──────────┐  ┌────▼───────────────────┐
         │ Workflow Workers      │  │ Agent Runtime Pool      │
         │ (K8s Jobs)            │  │ (Claude Agent SDK)      │
         └───────────┬──────────┘  └────┬───────────────────┘
                     │                  │
                 ┌───▼───┐          ┌───▼──────────┐
                 │ Tool  │  MCP     │ Sandbox/VM     │
                 │ Hub   ├──────────► Browser/Code    │
                 └───┬───┘          └───┬──────────┘
                     │                  │
               ┌─────▼──────────────┐   │
               │ Observability/Audit │◄──┘
               │ OTEL + Logs + Events│
               └─────────────────────┘
          

2. 服务拆分（建议微服务边界）

3. 数据存储与多租户

• 元数据：PostgreSQL（强一致，适合 RBAC、账本、状态机）。
• 缓存：Redis（session cache、rate limit、idempotency）。
• 产物：对象存储（S3/GCS/OSS），支持版本化。
• 向量：可选 Vector DB（pgvector/Milvus）用于企业知识库检索。
• 日志：OpenTelemetry → ClickHouse/Elastic（按规模选）。

4. 核心数据模型（关键表）

5. Run/Workflow 状态机（建议）

复制
RUN_STATUS:
  QUEUED -> RUNNING -> (SUCCEEDED | FAILED | CANCELED)

Step:
  PENDING -> RUNNING -> (SUCCEEDED | FAILED | SKIPPED)
  FAILED -> RETRYING -> RUNNING ...

Approval:
  REQUESTED -> (APPROVED | DENIED | EXPIRED)
            

复制
Client -> POST /v1/runs  (idempotency key)
  API Gateway -> Billing: preflight quota check
  Run Service -> create run + enqueue first step
Client -> GET /v1/runs/{run_id}/events (SSE)
Worker -> execute step (Agent SDK)
  -> tool calls via Tool Hub (may require approvals)
  -> write artifacts to Object Storage
  -> emit events (step_started/step_completed/artifact_created)
SSE -> client updates UI in real-time
On completion -> Billing: finalize metering + ledger entries
            

6. Workflow Engine 设计要点

• DAG JSON：节点/边/输入输出 schema；节点声明重试策略与幂等键。
• 幂等：每个外部写入 Tool Step 必须带 idempotency_key；重复执行不产生重复副作用。
• 缓存：对确定性 Tool Step（例如抓取静态资料、标准化处理）可缓存，提升成本与速度。
• Map‑Reduce：支持批处理子 agent 并行，Reduce 节点做汇总与校验。
• Human Step：审批/补充输入；超时策略与 fallback。

7. Agent Runtime（Claude Agent SDK）平台化要点

• 运行隔离：K8s Job/Pod（资源限制、网络 egress 白名单、只读文件系统可选）。
• Skills 装配：启动前把选中技能版本下载到 .claude/skills/ 并挂载。
• Session/Resume：将 session_id 与 run_id 映射；支持暂停/继续；idle reclaim。
• Compaction：长任务对话定期压缩（摘要写入 run_steps.meta_json）。
• Checkpoint：关键文件/产物版本化；支持回滚与 diff（Run Workspace）。

8. Tool Hub（MCP 网关）与连接器治理

• 统一鉴权：Tool Hub 负责从 token vault 取凭证并注入调用。
• 最小权限：连接器 scopes 精确到资源/动作；默认只读。
• 审批策略：组织管理员可配置：哪些工具/动作必须审批；哪些免审批。
• 审计：每次 tool call 写入 tool_calls 与 audit_logs（必要时脱敏）。

9. 成本估算与计费扣减

10. 安全、合规与风险控制

• 沙箱：执行面容器隔离；网络出站白名单；禁止访问内网地址（SSRF 防护）。
• 数据安全：token vault 加密；敏感字段加密；对象存储按 org 分桶或前缀隔离。
• 审批：对外部写入/发送/删除/支付动作必须审批（可配置）。
• 内容安全：输出前进行敏感检测（企业可自定义策略）。
• 审计：所有 connector 授权、审批、外部写入必须落审计日志。

11. 可观测与运维

• Tracing：每个 run 作为 trace root，step/tool call 作为 span（OpenTelemetry）。
• Metrics：完成率、耗时分布、失败原因 Top、缓存命中率、成本/任务。
• Alert：失败率激增、超时、账本写入失败、队列积压、token vault 异常。

12. 测试与评测（建议必做）

• 单元测试：Workflow 节点解析、RBAC、账本、幂等。
• 集成测试：工具调用 mock、OAuth 流程、SSE 事件流。
• 回归评测：建立 Golden Tasks（研究/写作/设计/自动化），每次发布跑评测。
• 红队：工具滥用、越权、提示注入（Prompt Injection）、数据外泄测试。

API Spec｜接口规格说明（REST + SSE + Webhook）

1. 约定

• Base URL：https://api.yourdomain.com
• 版本：/v1（重大变更使用 /v2）
• 认证：Bearer Token（JWT）或 API Key（服务端集成）
• 组织上下文：优先从 token 解析；可显式传 X-Org-Id
• 幂等：对创建/触发类接口支持 X-Idempotency-Key
• 分页：limit + cursor（返回 next_cursor）

2. 通用错误码

3. 认证与 API Keys

复制
POST /v1/api-keys
Authorization: Bearer <user_jwt>

Response 201
{"id":"key_01H..","prefix":"sk_live_****","created_at":"..."}

Use:
Authorization: Bearer sk_live_xxx
            

4. Projects

复制
POST /v1/projects
Headers:
  Authorization: Bearer ...
  X-Org-Id: org_...
  X-Idempotency-Key: ...

Body:
{"name":"竞品调研-Q1","description":"Genspark/Lovart/Manus","locale":"zh-CN"}

Response 201:
{"id":"proj_...","org_id":"org_...","name":"...","created_at":"..."}
          

5. Artifacts（产物/Drive）

复制
POST /v1/projects/{project_id}/artifacts
Body:
{
  "type":"page",
  "title":"市场调研：Agent 平台",
  "content": {
    "schema":"page.v1",
    "blocks":[
      {"type":"heading","text":"摘要"},
      {"type":"paragraph","text":"..."}
    ]
  }
}

Response:
{"id":"art_...","type":"page","latest_version_id":"ver_..."}
            

复制
POST /v1/projects/{project_id}/artifacts
Content-Type: multipart/form-data
Fields:
  type=file
  file=@/path/data.csv
  title="sales.csv"

Response:
{"id":"art_...","type":"file","download_url":"..."}
            

6. Runs（执行/对话/流式事件）

复制
POST /v1/runs
Headers:
  Authorization: Bearer ...
  X-Org-Id: org_...
  X-Idempotency-Key: ...

Body:
{
  "project_id":"proj_...",
  "workspace":"run",
  "mode":"workflow",              // "agent" | "workflow"
  "workflow_version_id":"wfver_...", // optional
  "input": {
    "prompt":"抓取这份 CSV 并生成图表与总结报告",
    "artifacts":[{"id":"art_file_..."}]
  },
  "options": {
    "language":"zh-CN",
    "model":"claude-sonnet",     // router key or explicit
    "thinking":"auto",           // "fast" | "auto" | "deep"
    "max_cost_credits": 300
  }
}

Response 201:
{
  "id":"run_...",
  "status":"QUEUED",
  "cost_estimate": {"credits_low":80,"credits_high":180,"confidence":0.62},
  "events_url":"/v1/runs/run_.../events"
}
            

复制
GET /v1/runs/{run_id}/events
Accept: text/event-stream

event: run.started
data: {"run_id":"run_...","ts":"..."}

event: step.started
data: {"step_id":"step_01","type":"agent_step","name":"Plan","ts":"..."}

event: tool.called
data: {"tool":"mcp.web.fetch","input":{"url":"..."},"ts":"..."}

event: approval.requested
data: {"approval_id":"appr_...","scope":"email.send","reason":"将向外部地址发送邮件"}

event: artifact.created
data: {"artifact_id":"art_...","type":"report","title":"分析报告.pdf"}

event: run.completed
data: {"status":"SUCCEEDED","cost":{"credits":143}}
            

复制
POST /v1/runs/{run_id}/approvals/{approval_id}/approve
Body:
{"comment":"同意发送"}

POST /v1/runs/{run_id}/approvals/{approval_id}/deny
Body:
{"comment":"不允许外发"}
            

7. Workflows（模板/版本/触发）

复制
POST /v1/workflows
Body:
{
  "name":"Wide Research - 竞品表格",
  "visibility":"org",
  "description":"对一组 URL 并行抓取并输出对比表"
}

Response:
{"id":"wf_...","latest_version":null}
            

复制
POST /v1/workflows/{workflow_id}/versions
Body:
{
  "version":"1.0.0",
  "dag": {
    "schema":"workflow.v1",
    "nodes":[
      {"id":"n1","type":"subagent_map","input_schema":"items.v1","config":{"model":"haiku","concurrency":50}},
      {"id":"n2","type":"agent_reduce","depends_on":["n1"],"config":{"model":"sonnet"}},
      {"id":"n3","type":"artifact_export","depends_on":["n2"],"config":{"format":"xlsx"}}
    ],
    "edges":[
      {"from":"n1","to":"n2"},
      {"from":"n2","to":"n3"}
    ]
  }
}
            

复制
POST /v1/workflows/{workflow_id}/runs
Body:
{
  "project_id":"proj_...",
  "version":"1.0.0",
  "input": {
    "items":[
      {"url":"https://.../a"},
      {"url":"https://.../b"}
    ]
  }
}

Response:
{"workflow_run_id":"wfrun_...","status":"QUEUED","events_url":"/v1/runs/run_.../events"}
            

8. Skills（市场/安装）

复制
GET /v1/skills?visibility=public&limit=20

Response:
{
  "data":[
    {"id":"skill_...","name":"Brand Guard","latest_version":"1.2.0","summary":"品牌规范校验与修复"}
  ],
  "next_cursor": null
}
            

复制
POST /v1/orgs/{org_id}/skills/{skill_id}/install
Body:
{"version":"1.2.0","enable_projects":["proj_..."]}

Response:
{"install_id":"skinst_...","status":"ENABLED"}
            

9. Connectors / MCP Servers

复制
POST /v1/orgs/{org_id}/connectors/{provider}/connect
Body:
{"scopes":["drive.read","drive.write"],"redirect_uri":"https://app.yourdomain.com/oauth/callback"}

Response:
{"auth_url":"https://accounts.google.com/o/oauth2/v2/auth?..."}
            

复制
POST /v1/orgs/{org_id}/mcp/servers
Body:
{
  "name":"internal-crm",
  "url":"https://mcp.company.com",
  "auth":"bearer",
  "allowed_tools":["crm.search","crm.update"],
  "egress_policy":"deny_all_except_list",
  "notes":"只允许在审批后写入"
}
            

10. Billing / Credits

复制
GET /v1/billing/credits
Response:
{"org_id":"org_...","balance":12500,"resets_at":"2026-01-01T00:00:00Z"}

GET /v1/billing/ledger?limit=50
Response:
{"data":[{"delta":-143,"reason":"run.completed","ref_id":"run_..."}]}
            

11. Webhooks（结果回调）

复制
POST /v1/webhooks
Body:
{
  "url":"https://yourapp.com/webhooks/agent",
  "events":["run.completed","artifact.created","approval.requested"],
  "secret":"whsec_..."
}

Response:
{"id":"wh_...","status":"ENABLED"}
            

复制
POST https://yourapp.com/webhooks/agent
Headers:
  X-Signature: t=...,v1=...

Body:
{
  "event":"run.completed",
  "ts":"2025-12-28T12:00:00Z",
  "data": {
    "run_id":"run_...",
    "status":"SUCCEEDED",
    "project_id":"proj_...",
    "artifacts":[{"id":"art_...","type":"report","download_url":"..."}],
    "cost": {"credits":143}
  }
}
            

附录｜可直接落地的模板与 DSL

A. Workflow DAG JSON（最小模板）

复制
{
  "schema":"workflow.v1",
  "nodes":[
    {
      "id":"plan",
      "type":"agent_step",
      "name":"Plan",
      "config": {"role":"planner","model":"sonnet","output_schema":"plan.v1"}
    },
    {
      "id":"execute",
      "type":"agent_step",
      "name":"Execute",
      "depends_on":["plan"],
      "config": {"role":"executor","model":"sonnet","tools_policy":"restricted"}
    },
    {
      "id":"verify",
      "type":"agent_step",
      "name":"Verify",
      "depends_on":["execute"],
      "config": {"role":"verifier","model":"opus","output_schema":"verify.v1"}
    },
    {
      "id":"export",
      "type":"artifact_export",
      "depends_on":["verify"],
      "config": {"format":"pdf","artifact_type":"report"}
    }
  ]
}
          

B. Skill 包 Manifest（建议字段）

复制
{
  "schema":"skill.manifest.v1",
  "name":"brand-guard",
  "version":"1.2.0",
  "summary":"品牌规范校验与修复",
  "entry":".claude/skills/brand-guard/SKILL.md",
  "required_tools":[
    "mcp.storage.read",
    "mcp.image.inspect",
    "mcp.page.edit"
  ],
  "risk_level":"medium",
  "policy": {
    "requires_approval_for":["mcp.storage.write","mcp.email.send"]
  },
  "tests":[
    {"name":"logo_clearspace","input":"...","expect":"pass"},
    {"name":"palette_check","input":"...","expect":"pass"}
  ]
}
          

C. Page DSL（示例）

复制
{
  "schema":"page.v1",
  "title":"竞品调研：Agent 平台",
  "blocks":[
    {"type":"heading","level":1,"text":"摘要"},
    {"type":"paragraph","text":"..."},
    {"type":"table","columns":["平台","定位","优势"],"rows":[["Genspark","页面化研究","..."]]},
    {"type":"citation","items":[{"title":"官方文档","url":"...","note":"..."}]}
  ]
}
          

D. Canvas Node Tree（示例）

复制
{
  "schema":"canvas.v1",
  "viewport": {"x":0,"y":0,"zoom":1},
  "nodes":[
    {"id":"frame1","type":"frame","x":0,"y":0,"w":1200,"h":800,"name":"Cover"},
    {"id":"img1","type":"image","parent":"frame1","x":80,"y":120,"w":520,"h":520,"asset_ref":"art_..."},
    {"id":"txt1","type":"text","parent":"frame1","x":640,"y":160,"w":480,"h":200,
      "style": {"font":"Inter","size":64,"weight":800,"color":"#111"},
      "text":"PIXEL VOGUE"}
  ],
  "comments":[
    {"id":"c1","node_id":"img1","text":"把主视觉调成更冷的蓝绿色","status":"queued"}
  ]
}