0. 范围与原则

平台目标：将用户上传的素材与自然语言需求统一送入云端沙箱环境执行，由 Claude Agentic SDK 的 Agent（结合 Spec 与多个 Skill）自动完成任务， 并将任务拆解、Skill 调用链、执行状态与结果全流程可视化呈现给用户。

1. 系统整体架构设计（模块划分与组件职责）

建议采用“前端极简 + 后端编排中枢 + 沙箱执行集群 + Skill 仓库 + 事件总线 + 观测/治理”的分层架构。 其核心是：用户只表达需求，系统把需求转为可执行工作流，并把执行过程透明化。

1.1 核心模块

1.1 端到端执行流水线（建议实现为事件驱动）

以下流程用于“用户上传素材 + 自然语言需求 → 沙箱执行 → 输出 + 全流程可视化”。

1. 上传素材：前端上传到对象存储/文件服务；获得 asset_id 与访问控制信息。
2. 创建会话/任务：前端发起 POST /sessions 或 POST /tasks，携带用户输入与 asset_id 列表。
3. 编排与入队：后端生成 task_id，写入数据库；推送“task.created”事件；将任务投递到队列。
4. 分配沙箱：Worker 从队列取任务，选择/创建沙箱（容器/微VM），挂载所需卷（素材、技能、输出目录）。
5. 启动 Agent：注入 Spec（系统规范/约束）+ 可用 Skill 列表（按权限过滤）。
6. 计划生成：Agent 生成执行计划（Plan），发布“plan.generated”。
7. Skill 调用与工具执行：Agent 按计划调用 Skill/工具；每一步发布事件（skill.invoked / tool.started / tool.finished）。
8. 产物与汇总：写入输出目录并登记产物（report/file/preview）；发布“artifact.created”。
9. 完成/失败：发布“task.completed”或“task.failed”；前端呈现结果与可视化链路；可下载产物。
10. 回收：会话活跃则保留沙箱；否则按TTL销毁并归档日志/trace。

2. 云端沙箱设计（安全性、资源隔离、可扩展性）

沙箱是平台安全与可控执行的根基：Agent 必须拥有足够能力处理任务（读写文件、运行代码、执行命令），但所有副作用必须被隔离、限额、可审计。

2.1 隔离模型与资源配额

• 隔离边界：每个任务/会话独立容器或微VM（推荐 Kubernetes Pod 或 microVM）。
• 文件系统：输出目录独立；素材只读挂载（可选）；Skill 目录只读；临时目录可写。
• 网络策略：默认禁止出网；如需访问第三方API，用代理 + 域名白名单 + 速率限制。
• 资源配额：CPU、内存、磁盘、进程数、执行时长、并发工具调用上限。
• 系统调用与权限：最小权限运行（非root）；可用 seccomp/AppArmor 限制高危系统调用。

2.2 沙箱生命周期策略

2.3 依赖与镜像管理

• 维护基础镜像（含 SDK 与常用工具）；按任务类型提供不同模板镜像（数据分析/网页自动化/文档处理等）。
• 允许运行时安装依赖，但应结合缓存与白名单源；对企业环境优先采用预装镜像以可控可审计。
• 禁止在沙箱内持久化敏感凭据；API Key 用短期凭据注入（环境变量/临时文件），任务结束即失效。

3. Skill 管理与适配机制（注册、依赖、动态加载）

Skill 是平台可扩展能力的主要载体。平台应适配 Anthropic 的 Skill 概念：用 SKILL.md 描述技能元数据与用法，资源文件（代码/模板）同目录存放。 Agent 启动时仅加载元数据；当模型判断某技能相关时，再按需读取技能完整内容（渐进披露），避免上下文爆炸。

3.1 Skill 生命周期

1. 开发：编写 Skill 包（SKILL.md + 资源文件 + 可选测试用例）。
2. 注册：上传到 Skill 仓库，进行结构校验与安全扫描，生成版本号。
3. 发布：选择发布范围（个人/组织/全局）；配置权限与可用性。
4. 加载：执行时按用户权限将 Skill 目录挂载到沙箱；SDK 扫描发现。
5. 审计与回滚：记录技能调用；出现问题按版本快速回滚。

3.2 Skill 组织结构建议

.claude/
  skills/
    pdf_extractor/
      SKILL.md
      extractor.py
      requirements.txt
      examples/
    data_cleaner/
      SKILL.md
      clean.py
      requirements.txt
  specs/
    default_spec.md
    enterprise_spec.md

3.3 依赖声明与冲突处理

• 依赖声明：在技能包内用 requirements.txt / package.json 声明依赖；在 SKILL.md 中说明运行前置条件。
• 冲突策略：优先通过“任务选择镜像模板”解决（不同技能组合使用不同镜像）；必要时为技能提供独立虚拟环境或隔离运行方式。
• 企业治理：企业技能需审批发布，限制高风险依赖源与外部网络访问。

4. 全流程可视化设计（开发者与非技术用户）

可视化应覆盖：任务拆解（Plan）、Skill 调用链、工具执行状态、产物生成、错误与重试、最终输出。推荐事件驱动 + 实时推送（WebSocket/SSE）。

4.1 展示分层（两种视图）

4.2 建议 UI 结构

• 左侧：对话窗口（用户输入、Agent 输出、关键步骤摘要）。
• 右侧：执行面板（Plan、Skill 列表、实时事件流、产物列表、错误与重试）。
• 顶部：任务状态（运行中/完成/失败）、耗时、token/成本估算、资源使用。
• 底部：产物下载与预览（文件、报告、表格、图片等）。

4.3 可视化数据来源

核心是统一事件协议（见附录A）。Agent/沙箱执行过程中产生事件 → 事件总线 → 前端订阅渲染。 同时把事件写入持久化存储，支持“回放与审计”。

5. 技术选型建议（语言框架、队列、数据库、事件总线）

5.1 推荐技术栈（可按团队习惯调整）

5.2 工程实践建议

• 上传：前端直传对象存储（签名URL），后端只处理元数据与授权。
• 幂等：任务创建与事件发布要幂等（防止重复消费/重试导致重复执行）。
• 成本控制：记录每次模型调用的token、耗时、重试次数；在可视化中展示。
• 回放：事件持久化 + 产物快照 → 可重现/可审计（对企业尤重要）。

6. 多用户与权限管理（RBAC、多租户、审计、配额）

平台覆盖开发者、企业与消费者，必须把权限与治理做到系统级：用户/组织隔离、技能权限、数据访问权限、配额、审计日志、风控。

6.1 角色与能力边界（示例）

6.2 多租户隔离

• 数据隔离：所有数据库查询带 tenant_id/org_id；对象存储按租户前缀分目录。
• 技能隔离：组织技能与个人技能分开；沙箱仅挂载被授权的技能目录。
• 运行隔离：沙箱实例标签化（tenant_id/session_id），便于清理与审计。

6.3 审计、风控与配额

• 审计记录：登录、上传、技能发布/回滚、外部调用、执行命令等关键动作。
• 风控策略：异常频率/耗时/失败重试；敏感内容与越权尝试的拦截与告警。
• 配额：token、并发任务数、沙箱时长、CPU/内存限制；超限提示与降级策略。

7. 平台可持续演进建议（路线图与治理）

7.1 迭代优先级（推荐顺序）

1. 事件协议 + 可视化 MVP：先把“过程可见”打通，否则后续难调试。
2. 沙箱隔离 + 配额：把风险关进笼子里，再开放更强技能。
3. Skill 仓库 + 版本/权限：支持企业与开发者共建生态。
4. 回放与审计：企业级必备；也是平台质量提升利器。
5. 性能与成本：引入沙箱池、缓存、重试策略与并发控制。

7.2 生态与标准

• 跟进 Anthropic Skill 标准演进，保持兼容，降低技能迁移成本。
• 规划“技能市场/分享机制”，但安全审核必须同步上线（评分与签名验证更佳）。

7.3 多模态与多模型扩展（可选）

• 把 Agent 适配层抽象为接口，未来可并行支持其它模型或特定任务引擎。
• 以 Skill 的方式接入语音、视觉、检索、企业系统集成（CRM/ERP/工单）。

附录：实施模板与示例

{
  "event_type": "skill.invoked",
  "timestamp": "2026-01-01T12:34:56.789Z",
  "tenant_id": "org_123",
  "session_id": "sess_abc",
  "task_id": "task_xyz",
  "severity": "info",
  "payload": {
    "skill_name": "pdf_extractor",
    "reason": "用户上传了PDF并请求提取字段",
    "inputs": {
      "asset_id": "asset_001",
      "options": { "mode": "form_fields" }
    }
  }
}

{
  "event_type": "tool.finished",
  "timestamp": "2026-01-01T12:35:10.120Z",
  "tenant_id": "org_123",
  "session_id": "sess_abc",
  "task_id": "task_xyz",
  "severity": "info",
  "payload": {
    "tool": "python",
    "duration_ms": 8320,
    "stdout_preview": "extracted 10 fields ...",
    "stderr_preview": "",
    "artifacts": [
      { "artifact_id": "art_1001", "type": "json", "path": "outputs/fields.json" }
    ]
  }
}

# 会话
POST   /sessions
GET    /sessions/{session_id}
POST   /sessions/{session_id}/messages
GET    /sessions/{session_id}/events   # SSE/WebSocket 订阅的逻辑入口（也可走WS网关）

# 任务（可选：把会话与任务分离，支持一对多）
POST   /tasks
GET    /tasks/{task_id}
POST   /tasks/{task_id}/cancel
GET    /tasks/{task_id}/artifacts

# 上传（可选：签名URL）
POST   /assets/sign
POST   /assets/complete

# Skills 管理（管理员/开发者）
POST   /skills
GET    /skills
GET    /skills/{skill_id}
POST   /skills/{skill_id}/versions
POST   /skills/{skill_id}/publish
POST   /skills/{skill_id}/disable
POST   /skills/{skill_id}/rollback

# pdf_extractor

## 描述
从用户上传的 PDF 中提取结构化信息（表单字段/表格/关键段落），输出 JSON 或 CSV。

## 何时使用
- 用户上传 PDF 并要求提取字段、表格、或生成结构化摘要。
- 需要将 PDF 内容转为可被下游技能/脚本处理的数据格式。

## 输入
- asset_id: PDF 文件标识
- mode: form_fields | tables | paragraphs
- output_format: json | csv

## 输出
- outputs/fields.json 或 outputs/tables.csv
- 可选：preview.md 用于前端预览

## 执行步骤（建议）
1. 验证文件类型与大小（策略/配额）
2. 解析 PDF（优先本地库；必要时OCR，但要限额）
3. 结构化整理
4. 写入输出目录并生成 artifact 事件

## 依赖
- python: pypdf, pandas（如需要表格）
- 可选：tesseract（如启用OCR）

## 安全与限制
- 默认禁止外部网络
- 只读访问 uploads/ 目录
- 输出仅允许写入 outputs/

参考信息（可用于检索原始材料）

以下为本指南所依据的公开主题关键词（建议按标题检索）：

• Anthropic Engineering：Building agents with the Claude Agent SDK
• Anthropic：Equipping agents for the real world with Agent Skills（Agent Skills / SKILL.md / 渐进披露）
• Anthropic Docs：Agent Skills in the SDK（setting_sources / allowed_tools 等配置）
• 沙箱执行实践：在云沙箱中运行 agent / code（容器/隔离/可审计）
• 可观测性实践：Trace/Span、事件流、回放与审计