# Optima Agent

基于 [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) 的电商运营 AI 助手。

[![npm version](https://badge.fury.io/js/@optima-chat%2Foptima-agent.svg)](https://www.npmjs.com/package/@optima-chat/optima-agent)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 快速开始

### 安装

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

### 认证

```bash
export ANTHROPIC_API_KEY=your-api-key
```

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

### 使用

```bash
# 交互模式（终端对话）
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 集成** - 店铺连接、商品/订单/库存同步
- **交互式问答** - 执行任务时向用户提问（架构选择、方案确认等）

### 执行模式

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

## 可用 Skills

| Skill | 用途 |
|-------|------|
| merchant | 店铺信息管理 |
| product | 商品管理 |
| order | 订单处理与发货 |
| inventory | 库存管理与监控 |
| shipping | 运费配置与管理 |
| logistics | 物流运单与追踪 |
| i18n | 国际化翻译 |
| collection | 商品集合管理 |
| homepage | 店铺首页配置 |
| product-page | 商品详情页配置 |
| review | 评价管理与 AI 生成 |
| comfy | 图像/视频/语音生成（TTS/ASR） |
| ffmpeg | 音视频处理（合成、压缩、裁切） |
| browser | 浏览器自动化与 Workflow 录制回放 |
| ads | Google Ads 广告投放 |
| scout | Amazon 选品与 1688 供应商sourcing |
| shein | Shein 产品搜索与快时尚调研 |
| tiktok | TikTok 网红营销与 Shop 产品研究 |
| instagram | Instagram 达人发现与内容分析 |
| shopify | Shopify 店铺集成与同步 |
| bi | 销售数据与趋势分析 |
| sentinel | 自动化监控规则与巡检 |
| markdown-pdf | Markdown 导出 PDF |

## 交互式问答 (AskUserQuestion)

Claude 可以在执行任务时向用户提问，用于：
- **架构选择** - 选择技术栈、库、框架等
- **方案确认** - 多个实现方案，让用户决策
- **需求澄清** - 遇到模糊需求时请求明确

### 各模式支持情况

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

### 示例：终端交互

```bash
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 事件** (后端 → 前端):
```json
{
  "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 消息** (前端 → 后端):
```json
{
  "type": "answer_question",
  "request_id": "ask_question_xxx",
  "answers": {
    "0": "OAuth 2.0"
  }
}
```

详细文档：[docs/ask-user-question-implementation.md](docs/ask-user-question-implementation.md)

## 配置

项目根目录可选配置：

**OPTIMA.json** - 配置选项
```json
{
  "model": "claude-sonnet-4-5-20250929",
  "maxTurns": 50
}
```

**OPTIMA.md** - 自定义 System Prompt
```markdown
# 项目规则

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

## API 使用

```typescript
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 工具

## 开发

```bash
# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build

# 类型检查
npm run typecheck
```

## License

MIT