平台愿景与“极致简化”原则

目标：打造一个任意素材上传后，平台能够自动理解素材类型与意图线索，并以最少的问题引导用户得到结果产物（会议纪要 / PPT / 图文报告 / 表格分析 / 视频摘要等）。

你提到“可学习 Manus 但要更进一步”。更进一步的关键不是 UI 细节，而是“素材 → 意图 → 规划 → 执行 → 验证 → 交付”的闭环稳定性与可扩展性。

核心概念：Asset / IR / Skill / Spec / Agent

总体架构：一处上传，多智能体协作

推荐采用“上传即触发”的闭环：上传 → 解析 → 推荐 → 追问 → 运行 → 交付。

[Web / App]
  └─ Upload Component
       ├─ 预览/限制/进度
       └─ 调用 API: /assets/upload

[API Gateway]
  ├─ Auth / Quota / Audit
  ├─ Asset Service (对象存储 + 元数据 DB)
  ├─ Analyzer Service (确定性解析：时长/尺寸/文本/行列/字幕)
  └─ Orchestrator Service (Claude Agent SDK runtime)
        ├─ Action Recommender (候选动作 + 排序)
        ├─ Slot Filler (最少追问)
        ├─ Planner (选 Skill/Spec/模型)
        ├─ Runner (调用 Worker Agents / MCP tools)
        └─ Verifier (验收/回滚/重试)

[Worker Agents]
  ├─ ppt-agent
  ├─ video-agent
  ├─ image-agent
  ├─ spreadsheet-agent
  └─ doc-agent
      

为什么需要“素材分析器”作为统一入口？

• 用户不需要知道平台有哪些智能体：只要上传素材就行。
• 平台可以根据素材自动路由到最合适的智能体/模型组合。
• 多个素材可组合：例如“录音 + PPT + Excel”生成“复盘报告 + 行动项 + 新 PPT”。

素材接入：支持格式与提取能力

支持的文件格式（10 大类）

上传组件特性（前端）

• 拖拽上传 + 点击上传
• 自动文件类型检测
• 内容自动提取（文本 / 字幕 / 数据）
• 元数据提取（尺寸 / 时长 / 行列数）
• 帧角色选择器（首帧 / 尾帧，用于视频生成）
• 可配置（最大文件数、大小限制、允许类型等）
• 紧凑模式支持

后端解析建议：确定性优先

解析层建议尽量确定性（ffprobe/exif/pdf解析/表格读取），只在需要理解时才调用 LLM。 这样更快、更便宜、更可测试。

智能“素材分析器”设计：推荐动作 + 智能追问

目标

• 输入：一个或多个 Asset（及其 IR）
• 输出：Top-N 可执行动作（Action Candidates），并能对每个动作继续追问补齐参数
• 原则：少问、先给选项、默认可直接开跑

Action Candidate（候选动作）结构

{
  "id": "audio.meeting_minutes",
  "title": "生成会议纪要",
  "why": "检测到多人对话音频，包含时间戳与议题切换",
  "needed_slots": [
    { "key": "language", "type": "enum", "options": ["中文","英文"], "default": "中文" },
    { "key": "style", "type": "enum", "options": ["正式","精简","可执行"], "default": "可执行" }
  ],
  "outputs": ["markdown", "docx", "tasks.json"],
  "confidence": 0.83
}
    

推荐算法：规则 + LLM 排序（两段式）

1. 规则召回：根据文件类型、MIME、时长/页数/行列数、字幕存在等，快速召回可能动作（ActionSpec 触发器）。
2. LLM 重排：将少量候选 + IR 摘要输入给模型做排序与理由生成（可要求结构化输出）。

智能追问（Slot Filling）策略

• 优先做选择题：用按钮/单选代替输入框。
• 一问一要点：每次只问一个 slot，减少认知负担。
• 可推断不问：比如素材语言可用语言检测；输出格式默认 markdown + 可导出。
• 可撤销：用户随时切换动作或修改参数，平台保留运行草稿。

多素材协同：组合意图（Composite Intent）

当用户上传多文件时，分析器要识别“互补关系”：

• 视频 + 字幕 → 更快生成摘要/章节
• 音频 + PPT → 生成“讲解版 PPT + 讲稿 + QA”
• Excel + PDF → 生成“对账报告/差异说明”
• 图片 + 文本 → 生成“图文海报/小红书笔记/产品页”

Claude Agent SDK 作为执行底座：工具、权限、MCP、结构化输出

平台的 Orchestrator 推荐基于 Claude Agent SDK 执行：它提供“带工具的 agent loop”，可读写文件、执行命令、连接 MCP 工具，并支持长任务的上下文管理与部署建议。

关键能力一览（你会在平台用到的）

• 工具与 Agent Loop：流式消息 + 工具调用 + 观察结果 + 决策下一步。
• 权限：通过 allowed_tools / permission_mode 控制能做什么、是否需要人工批准。
• MCP：连接外部工具与服务（stdio / HTTP / SSE / in-process）。
• Skills：从 .claude/skills/ 自动发现并在需要时调用（“Skill” 工具）。
• 结构化输出：用 JSON Schema 强制返回格式，减少解析与重试。
• 文件 checkpointing：跟踪 Write/Edit 修改，支持回滚。

# 伪代码：展示结构（不是完整可运行工程）
from claude_agent_sdk import query, ClaudeAgentOptions

async def run_orchestrator(user_prompt: str):
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Write", "Edit", "Glob", "Grep", "Bash", "Skill"],
        permission_mode="acceptEdits",
        setting_sources=["user", "project"]  # 让 .claude/skills 可用
    )

    async for msg in query(prompt=user_prompt, options=options):
        # 1) 记录 stream（用于前端实时展示）
        # 2) 解析 tool call / tool result
        # 3) result 收敛到 artifact 输出
        yield msg
      

MCP：把“平台能力”工具化

让 Orchestrator 通过 MCP 调用平台内部服务（分析、检索、调度 Worker、写入产物），比“让模型自己写代码去调 HTTP API”更可靠。

// 关键点：在 Agent SDK 里用 createSdkMcpServer + tool 定义工具
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const platformServer = createSdkMcpServer({
  name: "platform",
  version: "1.0.0",
  tools: [
    tool(
      "asset_analyze",
      "Analyze uploaded assets and return structured IR",
      { asset_id: z.string() },
      async ({ asset_id }) => {
        // TODO: call your internal analyzer service
        return { content: [{ type: "text", text: JSON.stringify({ asset_id, ok: true }) }] };
      }
    )
  ]
});

// 使用 MCP 工具：注意 MCP 需要 streaming input（prompt 不能是纯字符串）
async function* promptStream() {
  yield { type: "user", message: { role: "user", content: "Analyze asset 123 and recommend actions" } };
}

for await (const msg of query({
  prompt: promptStream(),
  options: {
    mcpServers: { "platform": platformServer },
    allowedTools: ["mcp__platform__asset_analyze", "Skill", "Read"]
  }
})) {
  console.log(msg);
}
      

结构化输出：让“推荐动作/计划”可机器执行

强烈建议：分析器的关键产出（Action Candidates、Plan、Artifact Manifest）都通过结构化输出返回。 这样前端与下游 Worker 不需要猜测模型输出。

{
  "type": "object",
  "properties": {
    "candidates": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "why": { "type": "string" },
          "confidence": { "type": "number" }
        },
        "required": ["id","title","confidence"],
        "additionalProperties": false
      }
    }
  },
  "required": ["candidates"],
  "additionalProperties": false
}
      

Checkpointing：产物写入可回滚

生成 PPT/文档/代码这类“写文件”的任务，务必开启 checkpointing：一旦模型写坏，可回滚到安全状态再重试。

Skill 体系：Agent Skills 标准、组织方式与最佳实践

推荐采用 Agent Skills（开放标准）作为技能包格式

每个 Skill 是一个目录，至少包含 SKILL.md（YAML frontmatter + Markdown body），可选带 scripts/、references/、assets/。

---
name: meeting-minutes
description: Turn an audio transcript into structured meeting minutes with decisions, action items, owners, and deadlines. Use when the user uploads audio/video of a meeting or asks for minutes, summary, or action items.
license: Proprietary
metadata:
  owner: "platform-team"
  version: "1.0"
compatibility: Requires transcript text in IR. Optional access to calendar attendees.
---

## Goal
Produce a clear meeting minutes document:
- Agenda
- Key discussion points
- Decisions
- Action items (owner, due date)
- Open questions

## Input
- transcript (plain text with timestamps if possible)
- optional: speaker map, meeting title, date

## Output
- minutes.md
- tasks.json (structured)

## Instructions
1) Read transcript, identify topic shifts.
2) Extract decisions and action items; do not invent owners or dates.
3) If missing critical info, ask user one question at a time.
      

在 Agent SDK 中启用 Skills

• 把 Skills 放在项目目录的 .claude/skills/（团队共享）或 ~/.claude/skills/（个人）。
• 在 SDK options 里开启 setting_sources / settingSources 并把 "Skill" 加入 allowed tools。
• 注意：allowed-tools frontmatter 字段在 Claude Code CLI 中支持，但在 SDK 使用时以 allowedTools 为准。

Skill 编写最佳实践（为“极致简化”服务）

• description 写清触发关键词：让模型更容易自动调用。
• 把长资料放到 references/：减少上下文占用，按需加载。
• 给出“最小追问策略”：明确什么情况下才需要问用户。
• 输出标准化：明确产物结构、文件名、字段格式，便于 Spec 组合。

Spec 体系：Action Spec / Workflow Spec（声明式任务说明书）

Skill 解决“怎么做”，Spec 解决“做什么、何时做、需要什么参数、交付什么产物、如何验收”。建议把 Spec 当成产品与工程的“契约”。

Action Spec（推荐动作的声明）

面向用户：上传后能看到的动作按钮，就是 Action Spec 的实例化。

id: audio.meeting_minutes
title: 生成会议纪要
description: 将会议音频/视频转写并生成结构化会议纪要与行动项
triggers:
  any_of:
    - category: audio
    - category: video
slots:
  - key: language
    type: enum
    options: [中文, English]
    default: 中文
    ask: 输出语言？
  - key: detail_level
    type: enum
    options: [精简, 标准, 很详细]
    default: 标准
    ask: 纪要详细程度？
outputs:
  - type: artifact
    format: markdown
    name: minutes.md
  - type: artifact
    format: json
    name: tasks.json
pipeline:
  - step: transcribe
    uses: skill/media-transcribe
    model: gateway.asr.default
  - step: minutes
    uses: skill/meeting-minutes
    model: gateway.text.reasoning
verification:
  - check: schema
    target: tasks.json
    schema_ref: schemas/tasks.schema.json
      

Workflow Spec（跨智能体编排的 DAG）

面向系统：一个复杂任务往往需要多个 Worker 与多种模型协同。

id: video.summary_to_ppt
title: 视频摘要并生成 PPT
triggers:
  any_of:
    - category: video
inputs:
  assets: required
slots:
  - key: tone
    type: enum
    options: [商务, 科普, 轻松]
    default: 商务
    ask: 演示风格？
dag:
  nodes:
    - id: extract_frames
      agent: video-agent
      tool: mcp__video__extract_keyframes
    - id: transcribe
      agent: media-agent
      tool: mcp__media__asr
    - id: outline
      agent: orchestrator
      skill: skill/ppt-outline
      model: gateway.text.reasoning
    - id: build_ppt
      agent: ppt-agent
      tool: mcp__ppt__generate_pptx
  edges:
    - from: extract_frames
      to: outline
    - from: transcribe
      to: outline
    - from: outline
      to: build_ppt
outputs:
  - artifact: slides.pptx
verification:
  - check: pptx_renderable
    target: slides.pptx
      

多模型网关：统一能力、路由与成本/质量治理

平台需要“各大模型 API”，但不应让业务直接依赖具体厂商 API。建立 Model Gateway 做三件事： 统一接口、能力路由、成本与可观测。

统一接口（建议）

interface ModelGateway {
  chat(request): Stream|Response
  embeddings(request): Response
  image(request): Response
  speech_to_text(request): Response
  text_to_speech(request): Response
  usage(reporting): Response
}
    

能力路由（示例策略）

• Orchestrator / 规划：优先高可靠推理模型（支持工具/结构化输出）。
• 产物生成：按类型选择：PPT 用擅长结构化与长文本的模型；图片用图像生成模型；ASR 用语音模型。
• 成本控制：默认用性价比模型，置信度不足或验收失败才升级。
• 回退：同一能力至少 2 家供应商可替换，避免单点风险。

网关必须提供的治理能力

• 限流/配额、熔断、重试与幂等
• 请求与响应的结构化日志（脱敏）
• Token/时长/费用统计（按用户/团队/Spec/Skill 维度）
• 缓存策略（提示词缓存、embedding 缓存、产物缓存）
• 评估与 A/B（同一 Spec 不同模型的质量对比）

多智能体协作：专业智能体、MCP 工具化、编排策略

推荐的智能体分工

统一通信：把每个 Worker 暴露为 MCP Server 或“工具 API”

这样 Orchestrator 在 Claude Agent SDK 中可以像调用工具一样调用 Worker。

server: ppt
tools:
  - generate_pptx(outline_json, theme_id) -> slides.pptx
  - render_preview(pptx) -> preview.png[]
  - apply_brand(theme_id, brand_rules) -> theme.json
      

编排策略：把复杂任务拆成“可验收的小步”

• 先结构化，再生成：先让模型输出大纲/表格/JSON，再交给 Worker 生成最终文件。
• 先快后准：先用便宜模型给初稿；验收不通过再升级模型/增加上下文。
• 并行化：转写、抽帧、OCR 等可并行；Orchestrator 聚合结果再生成大纲。
• 失败可恢复：节点级重试；写文件有 checkpoint 回滚；必要时追问用户。

平台 API 与事件流：上传、分析、运行、产物

建议的核心 API（REST + SSE）

POST   /v1/assets/upload              # 上传文件（多文件）
GET    /v1/assets/{id}                # 查询素材元数据与 IR 状态
POST   /v1/assets/{id}/analyze        # 触发/重试解析（可异步）
GET    /v1/actions/recommend?asset=.. # 返回候选动作（Action Candidates）

POST   /v1/runs                        # 创建一次运行（选择 action/spec）
GET    /v1/runs/{id}                   # 运行状态
GET    /v1/runs/{id}/events            # SSE：流式输出（agent messages + progress）
POST   /v1/runs/{id}/input             # 用户回答追问（slot）
POST   /v1/runs/{id}/cancel            # 取消

GET    /v1/artifacts/{id}              # 下载产物
GET    /v1/artifacts/{id}/preview      # 在线预览（图片/文本/页渲染）
    

Run 状态机（示例）

created -> analyzing_assets -> recommending -> waiting_user_choice
-> planning -> running -> verifying -> (waiting_user_input)? -> completed | failed | canceled
    

SSE 建议输出统一事件结构（type + payload），前端可以用一个渲染器同时展示“模型输出/工具调用/进度/产物链接”。

安全与合规：沙箱、权限、审计、数据隔离

安全底线

• 文件上传：病毒扫描 + 类型嗅探 + 大小/数量/后缀白名单
• 存储：按租户隔离（bucket/prefix）+ 加密（KMS）+ 访问审计
• 执行：Agent SDK 必须跑在容器沙箱（资源/网络/文件系统隔离）
• 工具权限：默认最小权限（allowed_tools），危险操作需要二次确认
• 日志：记录“谁让 agent 做了什么”（工具调用与产物变更）

权限分级（建议）

测试与评估：可回归的“端到端真实任务”

为什么测试很难？

• LLM 输出非确定；
• 素材多样；
• 多智能体协同，故障点多。

推荐测试体系

1. 确定性层单测：解析器（IR）、MCP 工具、产物渲染。
2. Spec 验收测试：固定输入素材（golden set）+ 预期产物检查（schema/页数/关键字段）。
3. 回归与对比：同一 Spec 不同模型/不同 prompt 的质量对比，记录指标。

验收检查（示例）

• 会议纪要：必须包含“议题/决策/行动项”；行动项字段齐全（owner 可为空但必须标注未知）。
• PPT：可打开；页数在范围内；每页标题非空；图片引用存在。
• 表格分析：输出结论必须能追溯到具体行/列或聚合结果（可引用行号/字段名）。

部署与扩展：容器化、队列化、弹性伸缩

运行形态

• 前端：Web / Desktop / Mobile
• 控制面：API Gateway + Auth + Billing
• 数据面：Asset Store + Analyzer + Artifacts
• 执行面：Orchestrator Worker Pool（每个 run 一个容器或会话）

推荐两种部署模式

队列化与幂等

• 所有 run 以 job 形式入队（可重试、可取消）。
• 关键节点输出落盘（Artifact/IR），做到断点续跑。
• 同一输入（hash）+ 同一 Spec + 同一版本可命中缓存。

附录：示例 Spec、示例 Skill、数据结构

AssetProfile（IR）建议字段

{
  "asset_id": "ast_123",
  "filename": "meeting.mp3",
  "mime": "audio/mpeg",
  "category": "audio",
  "bytes": 10485760,
  "hash": "sha256:...",
  "metadata": { "duration_sec": 3600 },
  "extractions": {
    "transcript": { "text": "...", "segments": [{"t0":0,"t1":3.2,"speaker":"S1","text":"..."}] },
    "language": "zh"
  },
  "indexes": {
    "search": { "chunks": 240, "vector_index": "optional" }
  }
}
    

ArtifactManifest（产物清单）

{
  "run_id": "run_456",
  "artifacts": [
    { "name": "minutes.md", "type": "text/markdown", "url": "..." },
    { "name": "tasks.json", "type": "application/json", "url": "..." },
    { "name": "slides.pptx", "type": "application/vnd.openxmlformats-officedocument.presentationml.presentation", "url": "..." }
  ]
}