Hongming Wang 24fec62d7f initial commit — Molecule AI platform

Forked clean from public hackathon repo (Starfire-AgentTeam, BSL 1.1)
with full rebrand to Molecule AI under github.com/Molecule-AI/molecule-monorepo.

Brand: Starfire → Molecule AI.
Slug: starfire / agent-molecule → molecule.
Env vars: STARFIRE_* → MOLECULE_*.
Go module: github.com/agent-molecule/platform → github.com/Molecule-AI/molecule-monorepo/platform.
Python packages: starfire_plugin → molecule_plugin, starfire_agent → molecule_agent.
DB: agentmolecule → molecule.

History truncated; see public repo for prior commits and contributor
attribution. Verified green: go test -race ./... (platform), pytest
(workspace-template 1129 + sdk 132), vitest (canvas 352), build (mcp).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-04-13 11:55:37 -07:00

36 KiB

Raw Blame History

Molecule AI — 产品需求文档 (PRD)

Product Name: Molecule AI
Tagline: "构建你的 AI 组织 — 让每一个智能体成为团队，让每一个团队成为公司"
Version: 1.0
Date: 2026-04-01
Author: Molecule AI Product Team
Status: Draft — Pending Review

1. 产品愿景

1.1 一句话定义

Molecule AI 是一个可视化 AI Agent Team 编排平台。用户在画布上构建 AI 组织架构图 —— 拖拽角色、嵌套团队、配置技能 —— 每个节点背后运行一个真实的 AI 智能体。平台自动处理部署、发现、通信和可观测性。

1.2 核心信念

信念	解释
角色 > 任务	竞品节点代表"任务"或"工具"。Molecule AI 的节点代表"角色"（Role），即组织中的一个岗位。内部的 AI 模型可以随时替换，但角色位置、层级关系、技能配置不变。
组织架构即访问控制	无需手动连线。通信拓扑从 parent/child 层级结构自动派生。组织结构图就是安全策略。
分形递归	任何一个智能体节点都可以"展开"为一整个团队。从外部看，它仍然是同一个 A2A 端点。内部结构对外完全不透明 —— 与真实企业组织的分工逻辑一致。
标准协议	基于 Google/Linux Foundation 的 A2A 协议（Agent-to-Agent），任何符合 A2A 标准的智能体都可以直接接入，零供应商锁定。

1.3 产品不是什么

❌ Molecule AI 不是	说明
工作流自动化工具（如 n8n）	节点是角色，不是任务步骤
聊天界面	智能体间通过 A2A 协议程序化通信
模型供应商	用户自带 API Key (BYOK)
LangGraph 的替代品	LangGraph 是每个 Workspace 内部的运行引擎
托管服务（MVP 阶段）	自托管、开源优先

2. 市场分析与竞争格局

2.1 行业趋势 (2026)

从单智能体到多智能体系统（Multi-Agent Systems, MAS） —— 企业已不再满足单个 chatbot，需要多个专业化智能体协同完成复杂任务。
"持久执行"成为金标准 —— 复杂、长周期的智能体流程需要状态持久化、人工审批门控和跨重启恢复。
Human-on-the-Loop > Full Autonomy —— 最成功的企业采用人类监督模式，而非完全自主。
互操作性需求爆发 —— A2A 等开放协议的出现开始打破供应商锁定。
运维成熟度分水岭 —— 成本监控、审计日志和失败熔断成为生产准入门槛。

2.2 竞品对比矩阵

维度	Molecule AI	CrewAI	AutoGen	LangGraph	n8n / Flowise	Sim.ai
核心抽象	角色 (Role)	角色 (Role)	对话 (Chat)	状态图 (Graph)	任务 (Task)	任务 (Task)
递归团队	✅ 无限嵌套	❌ 扁平	❌ 扁平	❌ 手动编排	❌ 无	❌ 无
可视化画布	✅ 核心产品力	❌ 纯代码	❌ 纯代码	❌ 纯代码	✅ 画布	✅ 画布
通信协议	A2A (标准)	内部 API	内部 API	内部 API	HTTP Webhook	内部 API
分布式部署	✅ 多机	❌ 单进程	❌ 单进程	❌ 单进程	❌ 单机	❌ 单机
模型无关	✅ BYOK	✅	✅	✅	部分	部分
安全隔离	4 级 Tier	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无
可观测性	Langfuse 全链追踪	基础	基础	LangSmith (SaaS)	基础	基础
Bundle 市场	✅ (规划中)	❌	❌	Hub (社区)	模板	❌
开源	✅ MIT	✅	✅	✅	✅ Community	❌

2.3 竞争核心结论

Important

Molecule AI 的本质差异不在于"又一个多智能体框架"，而在于它是唯一一个将"组织架构"作为第一公民抽象的可视化平台。 它不竞争 LangGraph 的底层引擎能力，而是将 LangGraph 包装在一个可视化、可嵌套、可分发的组织层中。

3. 核心差异化优势

3.1 差异化金字塔

                    ┌───────────────────────┐
                    │   Bundle Marketplace   │  ← 商业壁垒
                    │  (角色的 App Store)     │
                    ├───────────────────────┤
                    │   递归分形团队展开      │  ← 产品体验壁垒
                    │   (节点展开为子团队)    │
                    ├───────────────────────┤
                    │   组织即拓扑            │  ← 架构壁垒
                    │   (层级 = 访问控制)     │
                    ├───────────────────────┤
                    │   A2A 标准协议          │  ← 生态壁垒
                    │   (零锁定，可互操作)    │
                    └───────────────────────┘

3.2 九大差异化要点

#	差异化	竞品现状	Molecule AI 方案
D1	角色抽象 vs 任务抽象	节点 = 一个 API 调用或工具	节点 = 一个组织岗位，内部 AI 可随时热替换
D2	递归团队展开	扁平节点列表，无嵌套	任何节点可展开为子团队，子团队可再展开，无限递归
D3	组织即拓扑	手动连线 / 白名单	拖入嵌套自动建立通信关系，zero wiring
D4	分布式 A2A 通信	单进程内部调用	节点可分布在不同机器，通过 A2A JSON-RPC 2.0 直连
D5	4 级安全隔离	所有节点共享同一运行时	Tier 1-3 容器隔离，Tier 4 提供完整宿主机访问能力
D6	层级审批链	扁平人工介入	智能体沿组织层级逐级上报，直到根节点暴露给人类
D7	跨 Workspace 全链可观测	单节点 tracing	统一 Langfuse 实例，跨所有 Workspace 的 LLM 调用链
D8	Bundle 可分发/可交易	无便携格式	`.bundle.json` 标准格式，未来支持市场化售卖
D9	层次化记忆架构 (HMA)	全局共享向量库（越权、噪音大）	按汇报线隔离的 Local/Team/Global 三级记忆存储

4. 目标用户画像

4.1 Persona 1 — 技术架构师 (Technical Architect)

属性	描述
背景	10+ 年后端经验，熟悉分布式系统和 DevOps
痛点	需要编排多个 AI 智能体协作，但现有框架要么太底层（LangGraph），要么不支持分布式（CrewAI）
需求	可视化编排 + 代码级控制、生产级部署、安全隔离
价值主张	"在画布上拖拽即可构建企业级多智能体系统，不牺牲任何工程控制力"

4.2 Persona 2 — 业务运营者 (Business Operator)

属性	描述
背景	业务管理者，非技术背景，但理解团队组织管理
痛点	想自动化复杂的多步骤业务流程（如 SEO + 内容 + 投放），但没有编程能力
需求	像搭建组织架构一样部署 AI 团队，无需写代码
价值主张	"像管理人类团队一样管理 AI 团队 — 定义角色、分配技能、设置汇报线"

4.3 Persona 3 — Workspace 作者 (Workspace Author / Skill Developer)

属性	描述
背景	AI/LLM 应用开发者，熟悉 Prompt Engineering 和工具开发
痛点	开发的智能体/技能缺乏可复用的分发渠道
需求	将自己的专业知识打包为可复用、可交易的 Workspace Bundle
价值主张	"把你的 AI 专业能力打包成产品，一键分发或在市场上售卖"

4.4 Persona 4 — 企业管理员 (Enterprise Admin)

属性	描述
背景	IT 部门负责人，关注安全合规、成本管控
痛点	AI 智能体运行不透明、无审计轨迹、成本不可控
需求	全链可观测、层级审批机制、秘钥加密管理、多租户隔离
价值主张	"每一次 LLM 调用都有迹可循，每一次危险操作都需层级审批"

5. 核心功能需求

F1 — 可视化 Org Canvas (Visual Org Canvas)

目标： 提供类 Figma 的画布体验，以组织架构图的形式创建和管理 AI 智能体。

ID	功能点	优先级	描述
F1.1	画布渲染	P0	基于 React Flow 的无限画布，支持缩放、平移、小地图
F1.2	WorkspaceNode 组件	P0	每个节点展示：名称、状态指示灯（green/gray/yellow/red）、Tier 徽章、技能列表、活跃任务计数器
F1.3	层级边自动渲染	P0	parent/child 关系自动生成连线，无需手动连接
F1.4	拖拽嵌套	P0	将节点拖入另一个节点即建立 parent/child 关系。拖出到画布取消嵌套
F1.5	模板面板 (Template Palette)	P0	侧边栏展示可用 Workspace 模板，点击即可配置并部署
F1.6	快速配置弹窗	P0	选择模板后弹出：名称、模型选择、父节点选择，预填默认值
F1.7	节点位置持久化	P0	拖拽停止后 PATCH 到后端 Postgres，跨浏览器一致
F1.8	视口记忆	P1	保存画布缩放/平移状态，再次打开恢复上次视角
F1.9	实时状态同步	P0	WebSocket 推送所有状态变更，节点颜色/徽章实时更新
F1.10	节点右键菜单	P0	导出 Bundle、复制节点、展开为团队、删除
F1.11	团队缩放视图	P1	展开的节点支持"Zoom-in"查看子 Workspace 内部结构
F1.12	Bundle 拖放导入	P1	拖拽 `.bundle.json` 文件到画布即可导入并部署
F1.13	连接断裂可视化	P2	委派失败时，两节点之间的边显示警告指示

F2 — 递归团队展开 (Recursive Team Expansion)

目标： 任何 Workspace 节点可展开为一个子团队，递归无限深度。

ID	功能点	优先级	描述
F2.1	展开操作	P0	右键 → "展开为团队" 或 API `POST /workspaces/:id/expand`
F2.2	子节点自动部署	P0	读取 config.yaml 的 `sub_workspaces` 字段，自动 provision 子容器
F2.3	团队领导保留	P0	展开后，原节点的 Agent 保留为协调员（Team Lead），接收上游消息并分发
F2.4	作用域隔离	P0	子节点只能与同级 sibling 和 Team Lead 通信，不能直接联系外部
F2.5	折叠操作	P1	`POST /workspaces/:id/collapse` 停止子节点，Team Lead 恢复为独立执行
F2.6	删除前拖出	P1	删除团队时可先将子节点拖出保留，再级联删除剩余
F2.7	事件广播	P0	`WORKSPACE_EXPANDED` / `WORKSPACE_COLLAPSED` 事件触发画布更新

F3 — A2A 标准通信 (Agent-to-Agent Protocol)

目标： 所有 Workspace 间通过开放标准 A2A 协议直接通信，Platform 只做服务发现。

ID	功能点	优先级	描述
F3.1	Agent Card 发布	P0	每个 Workspace 在 `/.well-known/agent-card.json` 发布身份文档
F3.2	按需发现	P0	委派时才查询 Platform 解析目标 URL，不预推送拓扑
F3.3	层级访问检查	P0	`CanCommunicate()` 基于 parent_id 层级强制执行 403 Forbidden
F3.4	Peer 发现 API	P0	`GET /registry/:id/peers` 返回当前节点可达的所有 Workspace
F3.5	同步/流式调用	P0	`message/send` (同步短任务) 和 `message/sendSubscribe` (SSE 流式长任务)
F3.6	任务生命周期	P0	submitted → working → completed/failed/canceled，含 `input-required` 中间态
F3.7	委派失败处理	P0	3 次重试 + 指数退避 + 可选 fallback workspace + LLM 自主决策
F3.8	签名令牌 (Post-MVP)	P2	Platform 颁发短生命周期签名令牌，目标 Workspace 验证每次 A2A 请求

F4 — Skills 生态系统 (Skills Ecosystem)

目标： 模块化的技能包系统，支持热加载、ClawHub 生态兼容、MCP 工具集成。

ID	功能点	优先级	描述
F4.1	Skill 包格式	P0	`SKILL.md` (YAML frontmatter + Markdown 指令) + `tools/` (LangChain @tool)
F4.2	运行时热加载	P0	文件监控 → 2s 去抖 → 重新扫描 skills → 重建 Agent Card → 广播 AGENT_CARD_UPDATED
F4.3	画布拖放技能	P1	从技能面板拖拽技能到节点，自动复制文件到容器 volume
F4.4	ClawHub 兼容	P1	`npx clawhub@latest install <skill-name>` 安装社区技能
F4.5	三种技能类型	P0	纯上下文（仅 SKILL.md）/ 混合（SKILL.md + tools）/ 纯工具（仅 tools）
F4.6	环境依赖声明	P1	frontmatter 中声明 `requires.env` / `requires.bins`，启动时校验

F5 — Bundle 便携系统 (Bundle System)

目标： Workspace 的完整可移植格式，支持导出/导入/复制/未来市场交易。

ID	功能点	优先级	描述
F5.1	导出	P0	右键 → 导出为 `.bundle.json`，内含 system prompt、所有 skill 文件、工具配置、递归子 Workspace
F5.2	导入	P0	拖放到画布 → `POST /bundles/import` → 递归部署
F5.3	复制	P1	导出 + 全新 ID 重新导入，两个实例完全独立
F5.4	秘钥隔离	P0	Bundle 绝不包含 API Key 或密码。导入方自带凭据
F5.5	部分失败处理	P1	子节点部署失败不阻塞父节点，失败节点标红提供重试按钮
F5.6	来源追溯	P1	`source_bundle_id` 字段记录实例来源模板
F5.7	市场流通 (Future)	P3	卖家上架 Bundle + 定价 → 买家购买 → 平台在买方环境部署

F6 — 层级审批链 (Hierarchical Human-in-the-Loop)

目标： 智能体遇到需要审批的操作时，沿组织层级逐级上报，Root 节点暴露给人类。

ID	功能点	优先级	描述
F6.1	LangGraph 暂停集成	P0	利用 LangGraph 原生 interrupt 机制暂停执行
F6.2	层级上报	P0	子节点 → 父节点，父节点可 approve / deny / 继续上报
F6.3	Root 节点人工界面	P0	根节点收到审批请求时，在画布 UI 上弹出审批卡片
F6.4	审批结果回传	P0	审批结果沿层级向下传递，触发子节点恢复/中止
F6.5	可配置审批规则	P1	在 system prompt 中定义哪些操作需要审批（破坏性操作、高成本操作等）

F7 — 跨 Workspace 可观测性 (Cross-Workspace Observability)

目标： 统一 Langfuse 追踪平台，跨所有 Workspace 查看完整 LLM 调用链。

ID	功能点	优先级	描述
F7.1	自动 LLM Tracing	P0	LangGraph 检测 Langfuse 环境变量自动注入追踪，零配置
F7.2	追踪内容	P0	LLM 调用 (prompt/output/tokens/cost)、工具调用、规划步骤、错误堆栈
F7.3	A2A 委派跨度	P1	手动 span 链接：`parent_task_id` 将子 Workspace trace 关联到父链路
F7.4	统一视图	P0	所有 Workspace 报告到同一 Langfuse 实例，提供全局调用树
F7.5	画布内联追踪 (Future)	P3	点击节点直接查看最近 LLM 调用摘要，无需切换到 Langfuse

F8 — 分级安全隔离 (Tiered Security Isolation)

目标： 4 级安全分级，不同角色获得不同的系统权限和隔离程度。

ID	功能点	优先级	描述
F8.1	Tier 1 — 无特权容器	P0	只读文件系统，纯文本/数据处理
F8.2	Tier 2 — 标准容器	P0	资源受限 Docker + `/workspace` 挂载，适合大多数开发/协调型智能体
F8.3	Tier 3 — 特权容器	P1	`--privileged` + host PID，保留 Docker 网络，适合高权限开发操作
F8.4	Tier 4 — 完整宿主机访问	P2	privileged + host PID + host network + Docker socket，适合 DevOps / orchestrator 类工作区
F8.5	秘钥加密存储	P0	AES-256 应用层加密，`SECRETS_ENCRYPTION_KEY` 环境变量管理密钥
F8.6	代码沙箱	P2	Tier 3+ 的代码执行在一次性容器中运行（网络禁用、内存限制、执行后销毁）

6. 用户旅程 (User Journeys)

Journey 1 — 首次上手：部署一个 SEO Agent 团队

用户打开 Molecule AI Canvas (localhost:3000)
      │
      ▼
空白画布 — 左侧 Template Palette 展示可用模板
      │
      ▼
用户点击 "SEO Agent" 模板
      │
      ▼
弹出快速配置：
  • 名称: "Reno Stars SEO Agent"
  • 模型: Claude Sonnet (下拉选择)
  • 父节点: 无 (根级别)
      │
      ▼
用户确认 → POST /workspaces
      │
      ▼
画布出现新节点 🔄 (provisioning)
      │
      ▼
~30 秒后节点变绿 🟢 (online)
技能徽章: [Generate SEO Page] [Audit SEO Page]
      │
      ▼
用户右键节点 → "展开为团队"
      │
      ▼
节点展开：SEO Lead + Keyword Agent + Writer Agent + QA Agent
子节点依次上线，边自动渲染
      │
      ▼
用户在 Langfuse 中看到完整的跨 Agent 调用链 ✅

验收标准 (Acceptance Criteria):

从选择模板到节点上线 < 60 秒
节点状态从 provisioning 到 online 实时更新，无刷新
团队展开后子节点自动部署并建立正确的层级关系
子节点间只能与 sibling 和 Team Lead 通信，直接联系外部返回 403
Langfuse 中可看到从 SEO Lead 到各子 Agent 的完整调用树

Journey 2 — 构建多层组织：AI 软件开发公司

用户已有一个顶层 "Business Core" 节点
      │
      ▼
从模板添加: Marketing Agent, Developer PM, Operations Agent
拖入 Business Core 建立 parent/child 关系
      │
      ▼
画布自动渲染 Business Core → 三个子节点的组织架构
      │
      ▼
用户展开 Developer PM 为团队:
  Developer PM (协调员)
    ├── Frontend Agent
    ├── Backend Agent
    └── QA PM
      │
      ▼
进一步展开 QA PM 为团队:
  QA PM (协调员)
    ├── Auto Test Agent
    └── Manual Review Agent
      │
      ▼
三层组织架构完成 ✅
通信规则自动生效:
  • Frontend ↔ Backend ↔ QA PM (siblings) ✅
  • Frontend → Developer PM (up to parent) ✅
  • Frontend → Business Core (skip level) ❌ 403
  • Frontend → Marketing (cross-team) ❌ 403

验收标准:

三层嵌套结构正确建立，画布正确渲染所有层级
通信访问控制严格按照层级规则执行
拖出子节点到画布根级别后，该节点失去原 parent/child 关系
删除 QA PM 时，弹出警告列出所有将被级联删除的子节点

Journey 3 — Bundle 分发：导出并在另一环境复现

用户右键 Developer PM 节点 → "导出为 Bundle"
      │
      ▼
下载 developer-pm.bundle.json
内含: system prompt + 3 个子 Workspace 的完整定义（递归）
不含: API keys
      │
      ▼
用户将文件分享给同事
      │
      ▼
同事打开自己的 Molecule AI，拖拽 .bundle.json 到画布
      │
      ▼
POST /bundles/import → 递归创建 4 个 Workspace
全新 ID，保留 source_bundle_id 追溯
      │
      ▼
同事配置自己的 API Key
      │
      ▼
完整的 Developer PM 团队在同事环境中上线 ✅

Journey 4 — 层级审批：危险操作上报人类

Frontend Agent 决定需要删除生产数据库的旧表
      │
      ▼
Frontend Agent 暂停 (LangGraph interrupt)
发送审批请求 → Developer PM (parent)
      │
      ▼
Developer PM 的 LLM 评估：
"这是破坏性操作，超出我的权限"
      │
      ▼
Developer PM 继续上报 → Business Core (its parent)
      │
      ▼
Business Core 是根节点 →
审批请求通过画布 UI 暴露给人类用户
      │
      ▼
人类在画布上看到审批卡片：
"Frontend Agent 请求删除 production.legacy_table"
[批准] [拒绝]
      │
      ▼
人类点击 [拒绝]
      │
      ▼
拒绝信号沿链路回传：
Business Core → Developer PM → Frontend Agent
      │
      ▼
Frontend Agent 收到拒绝，采取替代方案 ✅

7. 技术架构概要

7.1 系统全景图

┌─────────────────────────────────────────────────────────────┐
│                    Molecule AI Canvas                           │
│           Next.js 15 · React Flow · Zustand · TailwindCSS   │
│    ┌──────────┐  ┌──────────┐  ┌──────────┐                │
│    │WorkspaceNode│ │TemplatePanel│ │ApprovalCard│ ...         │
│    └────┬─────┘  └────┬─────┘  └─────┬────┘                │
│         │ HTTP REST    │              │ WebSocket             │
└─────────┼──────────────┼──────────────┼─────────────────────┘
          │              │              │
┌─────────▼──────────────▼──────────────▼─────────────────────┐
│                   Molecule AI Platform                          │
│              Go (Gin) · REST API · WebSocket Hub             │
│                                                             │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │ Registry │ │Provisioner│ │ Bundler  │ │ Broadcaster│      │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘       │
│       │             │            │             │              │
│  ┌────▼─────┐  ┌────▼────┐                                  │
│  │ Postgres │  │  Redis  │     Events Flow:                  │
│  │  (SoT)   │  │ (Cache) │     Action → DB Insert → Redis   │
│  └──────────┘  └─────────┘     Pub/Sub → WebSocket Hub →    │
│                                 Canvas + Workspace Clients   │
└─────────────────────────────────────────────────────────────┘
          ↕ A2A JSON-RPC 2.0 (Direct, P2P)
┌─────────────────────────────────────────────────────────────┐
│              Workspace Runtime (per instance)                │
│         Python · Deep Agents · LangGraph · a2a-sdk        │
│                                                             │
│  ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐        │
│  │ Agent   │ │  Skills  │ │ Heartbeat│ │  Memory  │         │
│  │(LangGraph)││(SKILL.md)│ │(30s loop)│ │(fs/pg/s3)│        │
│  └────┬────┘ └─────┬────┘ └────┬─────┘ └──────────┘        │
│       │ Traces      │           │                            │
│  ┌────▼─────────────▼───────────▼──────────────────┐        │
│  │              Langfuse (Observability)            │        │
│  │          Unified cross-workspace tracing         │        │
│  └─────────────────────────────────────────────────┘        │
└─────────────────────────────────────────────────────────────┘

7.2 技术栈确认

层级	技术	版本	选型理由
Canvas	Next.js	15	App Router + React Server Components + 易于代理后端
Canvas	React Flow (@xyflow/react)	v12	业界标准可视化画布库
Canvas	Zustand	latest	轻量状态管理，契合 React Flow 受控模式
Canvas	TailwindCSS	v4	快速 UI 开发，暗色主题支持
Platform	Go + Gin	Go 1.22+	高并发心跳/WebSocket，goroutine 模型
Platform	PostgreSQL	16	事实源，append-only 事件日志，JSONB Agent Card
Platform	Redis	7	TTL 活跃检测 + Pub/Sub 事件广播 + URL 缓存
Runtime	Python	3.11+	Deep Agents / LangGraph 的原生语言
Runtime	Deep Agents	0.4+	Agent 封装（TODO 规划、子 Agent、文件系统记忆）
Runtime	LangGraph	latest	Agent 循环、状态持久化、流式处理、Human-in-the-Loop
Runtime	a2a-sdk	latest	A2A 服务端包装（JSON-RPC 路由 + Agent Card 自动发布）
Observability	Langfuse	3.x (self-hosted)	开源可自托管，LangGraph 原生集成
Infra	Docker Compose	2.x	本地开发全栈启动

7.3 数据库核心模型

表	用途	关键字段
`workspaces`	Workspace 注册表（当前态）	`id`, `name`, `status`, `parent_id`, `agent_card` (JSONB), `tier`, `url`
`agents`	Agent 分配历史	`workspace_id`, `model`, `status`
`structure_events`	不可变事件日志 (APPEND-ONLY)	`event_type`, `workspace_id`, `payload` (JSONB)
`workspace_secrets`	加密凭据	`workspace_id`, `key`, `encrypted_value` (AES-256)
`canvas_layouts`	节点画布位置	`workspace_id`, `x`, `y`, `collapsed`

7.4 实时数据流

1. 操作发生 (register / heartbeat / expand / ...)
      │
      ▼
2. broadcaster.RecordAndBroadcast()
   → INSERT INTO structure_events (append-only)
   → PUBLISH to Redis pub/sub channel
      │
      ▼
3. Redis subscriber relay → WebSocket Hub
      │
      ▼
4. Hub broadcasts:
   → Canvas clients: 所有事件 (更新全局视图)
   → Workspace clients: 过滤后事件 (仅 CanCommunicate 可达节点)
      │
      ▼
5. Canvas: Zustand applyEvent() → React Flow re-render
   Workspace: 重建 system prompt (如需)

8. 非功能性需求

8.1 性能

指标	目标
Workspace 上线时间 (Provisioning → Online)	< 60s (Tier 1-3), < 180s (Tier 4)
心跳间隔	30s
心跳处理吞吐	> 1000 次/秒 (Platform)
WebSocket 事件延迟	< 200ms (操作到画布更新)
画布渲染节点数	> 100 节点流畅
A2A 发现延迟	< 50ms (Redis 命中)

8.2 可靠性

指标	目标
Redis 丢失恢复	下次心跳自动重建状态
WebSocket 断连恢复	指数退避重连 + 全量 re-hydrate
Bundle 导入部分失败	成功节点保持运行，失败节点提供重试
委派失败	3 次重试 + 退避 + fallback + LLM 决策

8.3 安全

要求	实现
Workspace 间认证 (MVP)	发现时验证 `CanCommunicate()`，直连无认证
Workspace 间认证 (Post-MVP)	Platform 签发短效签名令牌
秘钥存储	Postgres + AES-256 应用层加密
Bundle 安全	不序列化任何凭据
Tier 4 隔离	完整宿主机访问级别的 Docker 配置
Docker 网络	所有容器在 `molecule-monorepo-net` 私有网络内

8.4 可扩展性

方向	设计支持
多机部署	A2A 协议天然跨机器，节点可在任何主机运行
多租户 (Future)	Schema 预留 `org_id` 扩展位
Marketplace (Future)	Bundle 格式已标准化，可直接挂载商业层
自定义 Provider	LangChain 兼容字符串格式，支持 Anthropic/OpenAI/Ollama/本地模型

9. 分阶段交付计划

Phase 1 — Foundation (基石期) · 8 周

目标： 证明核心循环 —— Workspace 注册 → 画布显示 → 心跳保活 → 离线检测 → 画布变灰。

周次	里程碑	交付物
W1-2	基础设施 + 数据库	Docker Compose (Postgres/Redis/Langfuse) + 5 个 Migration 文件
W2-3	Platform API 骨架	Go/Gin 服务启动，CORS，连接 PG/Redis
W3-4	Registry 端点	register / heartbeat / update-card + Redis TTL 活跃检测
W4-5	Workspace Runtime	Python 模板 + 最小 Echo Agent + A2A 包装 + 心跳
W5-6	Canvas 骨架	Next.js + React Flow + Zustand + WorkspaceNode + 初始加载
W6-7	WebSocket 实时更新	事件广播 + 画布实时节点状态更新
W7-8	第一个真实 Workspace	SEO Agent 配置完成，端到端从启动到画布可见

Phase 1 完成标准： 一个 SEO Agent Workspace 从容器启动到画布显示为绿色节点，心跳停止后变为灰色，全流程端到端通过。

Phase 2 — Growth (增长期) · 6 周

目标： 组织架构能力 + 通信 + Bundle 系统，用户可以构建多层 AI 组织。

周次	里程碑	交付物
W9-10	层级 & 通信	`CanCommunicate()` + Peer 发现 + 画布拖拽嵌套
W10-11	团队展开/折叠	expand/collapse API + 递归子 Workspace 部署
W11-12	Bundle 导入/导出	exporter + importer + 画布拖放
W12-13	模板面板	侧边栏模板列表 + 快速配置弹窗
W13-14	层级审批	Human-in-the-loop 层级上报 + 画布审批卡片

Phase 2 完成标准： 用户能构建 3 层组织架构，通信规则正确执行，Bundle 可导出/导入，审批链从叶节点上报到人类。

Phase 3 — Enterprise (企业期) · 6 周

目标： 安全隔离、分级部署、高级可观测性、SaaS 扩展准备。

周次	里程碑	交付物
W15-16	Tier 2-3 部署	Playwright / Xvfb 容器配置
W17-18	Tier 4 Full-Host 部署	Host network / Docker socket / 特权运行时策略
W18-19	代码沙箱	Tier 3+ Docker-in-Docker 沙箱
W19-20	SaaS 准备	Auth 抽象层 + org_id 扩展 + Stripe 集成点

10. 成功指标 (KPIs)

10.1 产品指标

指标	Phase 1 目标	Phase 2 目标	Phase 3 目标
从模板到节点上线时间	< 120s	< 60s	< 30s
画布流畅节点数量	20+	50+	100+
Bundle 导入成功率	—	> 95%	> 99%
委派成功率 (首次)	—	> 90%	> 95%
WebSocket 重连恢复时间	< 10s	< 5s	< 3s

10.2 社区指标 (开源)

指标	6 个月	12 个月
GitHub Stars	1,000	5,000
社区 Workspace Bundle 数量	10	50
月活跃 Self-Hosted 部署	50	500
ClawHub 上架 Skills 数量	20	100

11. 风险分析与缓解

#	风险	影响	概率	缓解策略
R1	A2A 协议尚未广泛采用	生态兼容性受限	中	Molecule AI 本身推动 A2A 落地，提供参考实现；保留 HTTP fallback
R2	LangGraph/Deep Agents 版本迭代	Runtime 适配成本	高	抽象 Agent 接口层，隔离底层框架变更
R3	画布性能瓶颈 (100+ 节点)	复杂组织架构下 UX 降级	中	虚拟化渲染 + 团队折叠；外层只看单个团队节点
R4	MVP 无认证的安全隐患	如果用户暴露到公网	低	文档明确标注 "仅限可信网络"；Post-MVP 优先加签名令牌
R5	多 AI Provider 成本不可控	用户不知道花了多少钱	中	Langfuse 自带 Token/Cost 追踪；画布节点展示累计 cost
R6	递归团队深度过大	延迟爆炸 + 调试困难	低	默认建议 ≤ 4 层深度，超出时 UI 警告

12. 附录

12.1 术语表

术语	定义
Workspace	Molecule AI 的基本单元。一个组织角色，内含一个 AI Agent，对外提供 A2A 端点
Agent	Workspace 内部的 AI 模型实例，可热替换
Agent Card	发布在 `/.well-known/agent-card.json` 的身份文档，描述能力和技能
Bundle	`.bundle.json` 可移植文件，包含 Workspace 完整配置（递归含子 Workspace）
Skill	可加载的技能包 (SKILL.md + tools/)，赋予 Agent 特定能力
Tier	安全等级 (1-4)，决定 Workspace 的隔离程度和部署方式
A2A	Agent-to-Agent 协议，JSON-RPC 2.0 over HTTP，Workspace 间直连通信
Team Expansion	将单个 Workspace 展开为包含子 Workspace 的团队
Platform	Go 后端控制平面，负责注册、发现、事件广播、部署
Canvas	Next.js 前端可视化画布，用户在此构建和管理 AI 组织

12.2 关键设计约束

Caution

以下约束在任何情况下不得违反：

Platform 永远不路由 Agent 消息 — A2A 消息是点对点 (P2P) 的
Postgres 是事实源，Redis 是临时缓存 — Redis 丢失可自动恢复
structure_events 表永远只 INSERT — 不 UPDATE，不 DELETE
workspace-template 不含业务逻辑 — 所有业务在 workspace-configs-templates/
Bundle 绝不包含秘钥 — API Key / 密码禁止序列化
层级即拓扑 — 无手动连线，通信关系从 parent_id 派生

12.3 相关文档索引

文档	路径
系统架构	[architecture.md](file:///Users/cuizhanlin/Desktop/Molecule AI-Agent-Team/docs/architecture.md)
核心概念	[core-concepts.md](file:///Users/cuizhanlin/Desktop/Molecule AI-Agent-Team/docs/core-concepts.md)
通信规则	[communication-rules.md](file:///Users/cuizhanlin/Desktop/Molecule AI-Agent-Team/docs/communication-rules.md)
平台 API	[platform-api.md](file:///Users/cuizhanlin/Desktop/Molecule AI-Agent-Team/docs/platform-api.md)
Workspace 运行时	[workspace-runtime.md](file:///Users/cuizhanlin/Desktop/Molecule AI-Agent-Team/docs/workspace-runtime.md)
Canvas UI	[canvas.md](file:///Users/cuizhanlin/Desktop/Molecule AI-Agent-Team/docs/canvas.md)
Skills 系统	[skills.md](file:///Users/cuizhanlin/Desktop/Molecule AI-Agent-Team/docs/skills.md)
Bundle 系统	[bundle-system.md](file:///Users/cuizhanlin/Desktop/Molecule AI-Agent-Team/docs/bundle-system.md)
数据库 Schema	[database-schema.md](file:///Users/cuizhanlin/Desktop/Molecule AI-Agent-Team/docs/database-schema.md)
部署器	[provisioner.md](file:///Users/cuizhanlin/Desktop/Molecule AI-Agent-Team/docs/provisioner.md)
安全等级	[workspace-tiers.md](file:///Users/cuizhanlin/Desktop/Molecule AI-Agent-Team/docs/workspace-tiers.md)
WebSocket 事件	[websocket-events.md](file:///Users/cuizhanlin/Desktop/Molecule AI-Agent-Team/docs/websocket-events.md)
可观测性	[observability.md](file:///Users/cuizhanlin/Desktop/Molecule AI-Agent-Team/docs/observability.md)
构建顺序	[build-order.md](file:///Users/cuizhanlin/Desktop/Molecule AI-Agent-Team/docs/build-order.md)

Note

本 PRD 基于现有 Molecule AI 架构文档编写，覆盖了从技术架构到产品体验的完整产品定义。所有功能需求均与现有代码库中的设计文档对齐，并在此基础上增加了用户旅程、验收标准和商业化路径。

Molecule AI — 点燃你的 AI 组织

36 KiB Raw Blame History Unescape Escape