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 生成产品图片和视频
• 广告投放 - Google Ads 管理
• 选品调研 - Amazon 产品分析
• 数据分析 - 销售数据和趋势
• 评价管理 - 审核、回复、精选评价
• 交互式问答 - 执行任务时向用户提问（架构选择、方案确认等）

执行模式

| 模式 | 用途 | 特性 | |------|------|------| | Stream | 本地终端交互 | Context 可视化、命令菜单、实时统计 | | Headless | 容器内运行 | stdin/stdout JSON、多对话管理、会话恢复 | | Server | 多客户端服务 | WebSocket、完整统计、Abort 支持 | | 单次查询 | 命令行执行 | 快速查询、支持 JSON 输出 |

可用 Skills

| Skill | 用途 | |-------|------| | merchant | 店铺信息管理 | | product | 商品管理 | | order | 订单处理 | | inventory | 库存管理 | | i18n | 国际化翻译 | | collection | 商品集合管理 | | homepage | 店铺首页配置 | | product-page | 商品详情页配置 | | comfy | 图像/视频生成 | | ads | Google Ads 广告 | | scout | Amazon 选品调研 | | bi | 数据分析 | | review | 评价管理 |

交互式问答 (AskUserQuestion)

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

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

各模式支持情况

| 模式 | 支持 | 交互方式 | |------|------|----------| | Stream (CLI) | ✅ | 终端菜单（箭头键/Space/Enter） | | Headless | ✅ | JSON 消息协议（ask_question/answer_question） | | Server | ✅ | WebSocket 消息协议 | | 单次查询 | ❌ | 自动拒绝（提示使用交互模式） |

示例：终端交互

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    │
│ (10个)      (引导逻辑)           (Bash/Read..)    (Memory)      │
└──────────────────────┬──────────────────────────────────────────┘
                       │
        ┌──────────────┼──────────────┐
        ▼              ▼               ▼
┌─────────────┐  ┌──────────┐  ┌──────────────┐
│ commerce    │  │  comfy   │  │ google-ads   │
│   -cli      │  │   -cli   │  │    -cli      │  ...
│             │  │          │  │              │
│ 商品·订单   │  │ 图像·视频 │  │   广告投放    │
└─────────────┘  └──────────┘  └──────────────┘

技术栈

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

开发

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build

# 类型检查
npm run typecheck

License

MIT