Optima Agent

基于 Claude Agent SDK 的电商运营 AI 助手。

快速开始

安装

npm install -g @optima-chat/optima-agent@latest

认证

export ANTHROPIC_API_KEY=your-api-key

或使用 Claude Code 的认证（~/.claude/）。

使用

# 交互模式（终端对话）
optima

# Headless 模式（容器内运行，stdin/stdout JSON）
optima headless

# 服务器模式（HTTP + WebSocket）
optima serve --port 3000

# 单次查询
optima -p "查看商品列表"

功能特性

核心能力

• 店铺管理 - 查看和更新店铺信息
• 商品管理 - 创建、编辑、查询商品
• 订单处理 - 发货、退款、订单查询
• 库存管理 - 监控库存、调整数量
• 运费与物流 - 运费配置、运单查询、物流追踪
• 国际化 - 多语言翻译管理
• 店铺配置 - 首页、集合、商品详情页
• 图像/视频/语音 - AI 生成产品图片、视频、TTS/ASR
• 音视频处理 - 视频合成、压缩、裁切、格式转换
• 浏览器自动化 - 网页操作、Workflow 录制与回放
• 广告投放 - Google Ads 管理
• 选品调研 - Amazon 产品分析、1688 供应商sourcing
• 竞品研究 - Shein、TikTok Shop 产品搜索
• 网红营销 - TikTok/Instagram 达人发现与分析
• 数据分析 - 销售数据和趋势
• 评价管理 - 审核、回复、AI 生成评价
• 自动化监控 - 定时规则、巡检、审批
• Shopify 集成 - 店铺连接、商品/订单/库存同步
• 交互式问答 - 执行任务时向用户提问（架构选择、方案确认等）

执行模式

可用 Skills

交互式问答 (AskUserQuestion)

Claude 可以在执行任务时向用户提问，用于：

• 架构选择 - 选择技术栈、库、框架等
• 方案确认 - 多个实现方案，让用户决策
• 需求澄清 - 遇到模糊需求时请求明确

各模式支持情况

示例：终端交互

optima

> 我需要实现用户认证，请帮我选择方案

🤔 Claude 需要你的输入

Auth method
Which authentication method should we use?

○ OAuth 2.0
  Industry standard, supports multiple providers

○ JWT
  Stateless, simple to implement

● Session
  Traditional approach, server-side state

            [取消]  [确认] ✓

Headless/Server 消息协议

ask_question 事件 (后端 → 前端):

{
  "type": "ask_question",
  "conversation_id": "conv_123",
  "request_id": "ask_question_xxx",
  "questions": [{
    "question": "Which method?",
    "header": "Auth",
    "options": [
      {"label": "OAuth 2.0", "description": "Industry standard"},
      {"label": "JWT", "description": "Stateless"}
    ],
    "multiSelect": false
  }]
}

answer_question 消息 (前端 → 后端):

{
  "type": "answer_question",
  "request_id": "ask_question_xxx",
  "answers": {
    "0": "OAuth 2.0"
  }
}

详细文档：docs/ask-user-question-implementation.md

配置

项目根目录可选配置：

OPTIMA.json - 配置选项

{
  "model": "claude-sonnet-4-5-20250929",
  "maxTurns": 50
}

OPTIMA.md - 自定义 System Prompt

# 项目规则

- 使用简体中文
- 优先使用现有库存

API 使用

import { OptimaAgent } from '@optima-chat/optima-agent';

const agent = new OptimaAgent({
  model: 'claude-sonnet-4-5-20250929',
  maxTurns: 50,
});

for await (const event of agent.chat('查看商品列表')) {
  if (event.type === 'assistant') {
    console.log(event.message);
  }
}

// 重置会话
agent.reset();

技术架构

┌─────────────────────────────────────────────────────────────────┐
│                        用户界面层                                │
│  ┌──────────────────┐              ┌──────────────────┐        │
│  │   终端 CLI       │              │   HTTP Server    │        │
│  │  (Stream Mode)   │              │   (WebSocket)    │        │
│  └────────┬─────────┘              └────────┬─────────┘        │
└───────────┼──────────────────────────────────┼──────────────────┘
            │                                  │
            └──────────────┬───────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Optima Agent 核心                           │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                  Claude Agent SDK                          │  │
│  │  • 流式输出  • 上下文管理  • Hooks  • 会话恢复             │  │
│  └───────────────────────────────────────────────────────────┘  │
│                             │                                    │
│  ┌──────────────┬──────────┴──────────┬──────────────┐         │
│  │              │                      │              │         │
│  ▼              ▼                      ▼              ▼         │
│ Skills      System Prompt          Tools         MCP Server    │
│ (23个)      (引导逻辑)           (Bash/Read..)    (Memory)      │
└──────────────────────┬──────────────────────────────────────────┘
                       │
        ┌──────────────┼──────────────┐
        ▼              ▼               ▼
┌─────────────┐  ┌──────────┐  ┌──────────────┐
│ commerce    │  │  comfy   │  │ google-ads   │
│   -cli      │  │   -cli   │  │    -cli      │  ...
│             │  │          │  │              │
│ 商品·订单   │  │ 图像·视频 │  │   广告投放    │
└─────────────┘  └──────────┘  └──────────────┘

技术栈

• 核心: Claude Agent SDK v0.1.55
• 语言: TypeScript
• UI: 自定义终端渲染
• 工具集成: 10+ 专业 CLI 工具

开发

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build

# 类型检查
npm run typecheck

License

MIT