Skill: synththoughts/okx-strategy-factory (version 2.0.1)

--- name: okx-strategy-factory description: "Agent Team 工厂：协调 5 个 AI Agent（Strategy/Backtest/Infra/Publish/Iteration）完成 OKX OnchainOS 链上交易策略的全生命周期——开发、回测、部署、发布、迭代。支持多策略并行，每个策略独立状态管理。触发词：策略开发、agent team、回测、迭代策略、发布 skill、部署策略。" license: Apache-2.0 metadata: author: SynthThoughts version: "2.0.0" pattern: "pipeline" steps: "5" --- # OKX Strategy Factory — Agent Team 协调 5 个专家 Agent 完成交易策略全生命周期。Lead 只协调不写代码。 ``` Strategy → Backtest → Infra(deploy) → LIVE ↑ ↑ (parallel) │ Publish → GitHub Release │ Iteration ← (定时/手动复盘) ``` **这是文件夹 Skill**。按需读取 `roles/`、`references/`、`assets/`，不要一次性加载全部。 ## Strategy Selection Lead 启动 Pipeline 时**必须**指定策略名称 `{strategy}`，所有路径和状态按策略隔离。 - **已有策略**: `grid-trading`、`cl-lp-rebalancer` - **新策略**: 指定新名称即可，自动创建 `Strategy/{strategy}/` 工作空间 - 每个策略拥有独立的 `Strategy/{strategy}/state.json`，互不干扰 - 同一时间可有多个策略处于不同阶段（如 grid-trading 在 LIVE，cl-lp-rebalancer 在 BACKTEST） ## When to Use - 开发新交易策略 → Lead 指定 `{strategy}` 名称，读 `roles/lead.md`，spawn strategy + backtest - 回测 → spawn backtest，读 `roles/backtest.md`，指定 `{strategy}` - 部署到 VPS → spawn infra，读 `roles/infra.md`，指定 `{strategy}` - 发布为独立 Skill → spawn publish，读 `roles/publish.md`，指定 `{strategy}` - 迭代/复盘 → spawn iteration，读 `roles/iteration.md`，指定 `{strategy}` - 全流程 → spawn 全部 teammate，Lead 指定 `{strategy}` 后协调 **示例**: ``` "启动 grid-trading 策略的回测" "为 cl-lp-rebalancer 执行全流程 Pipeline" "新建策略 momentum-breakout，从 Step 1 开始" ``` ## Pipeline: Execution Steps **CRITICAL RULE**: Steps MUST execute in order. Do NOT skip steps or proceed past a gate. ### Step 1: Strategy Development **Load**: `roles/lead.md`（第一跳流程）+ `roles/strategy.md` + `references/api-interfaces.md` + `references/strategy-lessons.md` **Actions**: 1. Lead 从主窗口讨论中提炼需求，填写 `templates/requirements.md` 模板，写入 `Strategy/{strategy}/requirements.md` 2. Lead 展示需求给用户确认（用户可修正） 3. 确认后 spawn strategy teammate，prompt 指向需求文件 4. Strategy agent 输出到 `Strategy/{strategy}/Script/v{version}/` 5. Lead 验证产出完整性 **Gate** (ALL must pass): - [ ] `strategy.js` 或 `.ts` 存在，无硬编码参数 - [ ] `config.json` 存在，所有可调参数已外置 - [ ] `risk-profile.json` 存在且字段完整（校验 `references/risk-schema.json`） - [ ] `README.md` 存在，含收益预期和适用市场条件 ### Step 2: Backtest Validation **Load**: `roles/backtest.md` **Input**: Step 1 输出的 `Strategy/{strategy}/Script/v{version}/` **Actions**: 1. Spawn backtest teammate 2. 拉取历史行情数据 3. 运行回测，输出到 `Strategy/{strategy}/Backtest/v{version}/` 4. 执行 Compliance Check：实际指标 vs `risk-profile.json` 声明值 **Gate**: - [ ] Compliance 全部 PASS + Sharpe > 1.0 + Win Rate > 40% → **PASS** - [ ] 任一 Compliance FAIL → **FAIL**，退回 Step 1 附失败详情 - [ ] Compliance PASS 但指标 borderline → **CONDITIONAL**，请用户决定 ### Step 3: Local Validate + Deploy to VPS **Load**: `roles/infra.md` **Input**: 通过回测的策略版本 **Actions**: 1. Spawn infra teammate 2. **本地验证**: `./deploy.sh {strategy} validate` — 3 tick dry-run，验证启动 + RPC + 钱包 3. 本地验证通过后，`./deploy.sh {strategy} production` — 部署到 VPS 4. 健康检查通过后更新 `VERSION` **Gate (Local)**: - [ ] 本地 3 tick dry-run 全部成功 - [ ] onchainos 连接 + 价格/余额查询正常 - [ ] 失败 → 退回 Step 1 修复 **Gate (Production)**: - [ ] 进程存活（pm2 status → "online"） - [ ] 启动 10s 内无错误日志 - [ ] 失败 → 自动回滚到上一版本 ### Step 4: Publish as Skill **Load**: `roles/publish.md` + `assets/product-skill-template/` **Input**: 通过回测的策略 + deploy 成功确认 **Actions**: 1. Spawn publish teammate（可在 Step 3 并行开始抽象） 2. 从 `assets/product-skill-template/` 读取产品 Skill 模板 3. 生成独立 Skill 包到 `{strategy}/`（仓库根目录下，与策略同名） 4. GitHub release 等待 Step 3 成功后执行 **Gate**: - [ ] `manifest.json` 存在（Single Source of Truth） - [ ] 三平台 adapter 均已生成（SKILL.md / agents.md / openclaw.yaml） - [ ] `install.sh` 存在且可执行 - [ ] GitHub tag + release 创建成功 ### Step 5: Iteration (Post-LIVE) **Load**: `roles/iteration.md` **Input**: 链上交易记录 + 行情数据 **Actions**: 1. Spawn iteration teammate（定时或手动触发） 2. 分析表现、提取因果关系、输出优化方案 3. 输出到 `Strategy/{strategy}/Iteration/v{version}-review-{date}.md` 4. **用户确认后** → 回到 Step 1 生成新版本 → 必须重走 Step 2 **Gate**: - [ ] 优化方案已输出 - [ ] 用户在聊天中确认 — **绝不自动执行** - [ ] 新版本回到 Step 1，必须走完整 Pipeline ## State Machine 每个策略独立维护状态，互不影响。 ``` DRAFT → BACKTEST → PASSED → LOCAL_VALIDATING → LOCAL_VALIDATED → DEPLOYING → LIVE → ITERATION_REVIEW → FAILED → DRAFT (revision) → CONDITIONAL → (user decides) LOCAL_VALIDATING → LOCAL_FAILED → DRAFT (fix issues) DEPLOYING → DEPLOY_FAILED → rollback + DRAFT or retry ITERATION_REVIEW → APPROVED → DRAFT (new version, must re-backtest) → REJECTED → LIVE (keep current) ``` Track in `Strategy/{strategy}/state.json`。Log every transition: `[STATE] {strategy} v{ver}: {OLD} → {NEW} | {reason}` ## Failure & Rollback ``` IF Step N fails for strategy {strategy}: 1. Log failure reason to Strategy/{strategy}/state.json 2. Step 2 fail → 退回 Step 1（Strategy 修订），附失败详情 3. Step 3 fail → Infra 自动回滚到上一版本 4. Step 4 fail → 不影响线上运行，可重试 Publish 5. Step 5 fail → 保持当前版本，通知用户 6. DO NOT proceed to next step ``` ## Anti-Patterns | Pattern | Problem | |---|---| | Lead 自己写代码 | Lead 只协调，代码由 Strategy agent 写 | | 跳过 Backtest 直接部署 | 包括 Iteration 新版本也必须回测 | | 自动执行 Iteration 优化 | 必须用户确认 | | risk-profile.json 缺失 | 直接 reject，不要"帮忙补全" | | 同时部署两个版本 | 同一策略同一时间只有一个 DEPLOYING | | 修改已发布版本目录 | 版本不可变，只能创建新版本 | | 2 次迭代未改善仍继续 | 应建议暂停策略或重新设计 | | 启动 Pipeline 未指定策略名 | Lead 必须先明确 `{strategy}`，否则拒绝执行 |

path: INTRODUCTION.md
content: # Strategy Factory：AI Agent 团队协作开发链上交易策略

## 它是什么

5 个 AI Agent 各司其职，把一句话需求变成实盘运行的链上交易策略。

```
"做一个 ETH 网格交易策略"
              │
     ┌────────▼────────┐
     │   Lead Agent    │ 协调全局，不写代码
     └────────┬────────┘
              │
  ┌───────────┼───────────┬────────────┐
  ▼           ▼           ▼            ▼
Strategy → Backtest → Infra      Iteration
写代码      回测验证    部署VPS     实盘复盘
                         │
                      Publish
                    打包为Skill
```

每步之间有质量门禁——回测不达标退回重写，部署失败自动回滚，迭代优化必须用户确认。

## 为什么不用单个 Agent

### 单 Agent vs Agent Team

一个 AI Agent 一趟水跑完策略开发、回测、部署、迭代——能不能做？能做。但问题是：

```
┌─ 单 Agent 一趟跑完 ───────────────────────────────────────┐
│                                                            │
│  同一个 context window 塞进所有东西：                        │
│                                                            │
│  量化逻辑 + onchainos接口 + 回测数据 + 部署运维               │
│                                                            │
│  问题 1: context 爆炸                                       │
│    讨论需求 → 写代码 → 跑回测 → 看结果 → 部署                │
│    到部署时，前面讨论的细节已经被压缩或丢失                    │
│                                                            │
│  问题 2: 没有质量关卡                                       │
│    Agent 自己写完自己判断"行了"，直接往下走                   │
│    回测没达标也可能被忽略，没有独立的第二双眼睛                 │
│                                                            │
│  问题 3: 角色混乱                                           │
│    同一个 Agent 既是开发者又是测试者又是运维                   │
│    它不会真正挑战自己写的代码                                  │
│                                                            │
│  问题 4: 经验无法沉淀                                       │
│    所有知识留在对话里，下次开新会话从零开始                     │
│                                                            │
└────────────────────────────────────────────────────────────┘

┌─ Agent Team (专家分工 + 流水线) ──────────────────────────┐
│                                                            │
│  每个 Agent 用独立 context 专注一件事：                      │
│                                                            │
│  Strategy Agent → 只管写策略（读需求文件 + 经验库）          │
│  Backtest Agent → 独立验证（不知道代码怎么写的，只看结果）    │
│  Infra Agent    → 只管部署（拿到回测通过的版本就行）          │
│  Iteration Agent → 只看实盘数据（不受开发时的偏见影响）       │
│                                                            │
│  关键差异：                                                  │
│  · 每步之间有 Gate — 回测不过就退回，不是自己放自己过          │
│  · 经验沉淀在文件里（strategy-lessons.md）— 跨会话复用       │
│  · context 隔离 — 每个 Agent 的工作台是干净的                │
│  · 可独立重跑 — 回测失败只需重跑 Strategy，不用从头来          │
│                                                            │
└────────────────────────────────────────────────────────────┘
```

### 策略开发的真正门槛

onchainos 的文档能教你怎么调用命令。但从"我有一个交易想法"到"它在链上自动运行并且赚钱"，要跨四个完全不同的领域：

```
┌─ 量化设计 ─────────────────────────────────────────────────┐
│                                                            │
│  信号怎么设计？EMA 交叉、布林带突破、还是链上数据驱动？       │
│  风控分几层？止损、熔断、仓位限制怎么配合？                   │
│  参数怎么定？网格步距 2% 还是 3%？波动率高的时候怎么调？      │
│                                                            │
│  这是量化交易的领域，跟 OnchainOS 没关系                     │
└────────────────────────────────────────────────────────────┘
        ×
┌─ 链上执行 ─────────────────────────────────────────────────┐
│                                                            │
│  怎么把交易逻辑变成 onchainos 调用链？                       │
│  quote → approve → swap → simulate → contract-call         │
│  不同链的差异怎么处理？单位、Gas、签名方式都不一样            │
│                                                            │
│  这是 OnchainOS + Web3 的领域                               │
└────────────────────────────────────────────────────────────┘
        ×
┌─ 生产工程 ─────────────────────────────────────────────────┐
│                                                            │
│  策略跑着跑着进程挂了，状态怎么恢复？                        │
│  API 连续超时 5 次，是暂停还是继续？                         │
│  状态文件写到一半断电了，怎么防损坏？                         │
│  怎么监控、怎么报警、怎么远程部署？                          │
│                                                            │
│  这是后端运维的领域                                         │
└────────────────────────────────────────────────────────────┘
        ×
┌─ 迭代分析 ─────────────────────────────────────────────────┐
│                                                            │
│  跑了 229 笔交易，HODL Alpha 为负——为什么？                 │
│  是信号不准、slippage 太高、还是市场条件不适合？              │
│  改哪个参数？改了会不会引入新问题？                          │
│                                                            │
│  这是数据分析的领域，而且反馈循环慢——犯错要等实盘亏钱才知道   │
└────────────────────────────────────────────────────────────┘

门槛 = 四个领域的乘积，不是加法
```

Strategy Factory 的做法是让每个 Agent 专注一个领域，同时把已有策略的实战经验沉淀下来：

```
量化设计  → Strategy Agent + strategy-lessons.md（9层风控、MTF趋势、非对称设计）
链上执行  → onchainos Skill 文件 + 标准 wrapper + api-interfaces.md
生产工程  → Infra Agent + deploy.sh + 实盘验证的状态管理模式
迭代分析  → Iteration Agent + 结构化复盘模板

你只需要描述交易想法，剩下的每个领域有对应的 Agent + 已有经验兜底
```

### 经验库：策略越多，后续越强

```
Grid Trading 实盘 229笔 ──┐
                           ├──▶ strategy-lessons.md（经验库）
CL LP Rebalancer 回测 ────┘          │
                                     │ 新策略开发时必读
                                     ▼
┌─ 已沉淀的经验 ──────────────────────────────────┐
│                                                  │
│  · 9层风控模式（Stop→熔断→止损→仓位→Gas检查…）    │
│  · MTF趋势分析标准实现（可直接复用）               │
│  · 波动率4档自适应（Low/Med/High/Extreme）         │
│  · slippage 6.24%的实盘教训                       │
│  · onchainos 各接口的避坑指南                      │
│                                                  │
│  只记录实盘验证过的经验，不记录猜测                  │
└──────────────────────────────────────────────────┘

Iteration Agent 每次复盘 ──▶ 新经验回写 ──▶ 下一个策略自动受益
```

### AI 闭环迭代：实际案例

```
ETH网格 v3 上线
    │ 运行10天，229笔交易
    ▼
Iteration Agent 分析
    │ 发现：
    │  · HODL Alpha 为负（跑输单纯持有）
    │  · 根因：震荡和趋势用同一套参数
    │  · 卖出成功率84.3%，低于买入100%
    ▼
优化方案（用户确认后执行）
    │  + MTF多时间框架趋势分析
    │  + 非对称网格（看涨时快买慢卖）
    │  + 追踪止盈（趋势中延迟卖出）
    ▼
v4 重走完整流水线
    │ Strategy → Backtest → Deploy
    ▼
实盘运行，等待下一轮复盘
```

## 一个策略的完整产出

```
Strategy/grid-trading/
│
├── Script/v4.0.0/
│   ├── strategy.py        ← 交易逻辑（调onchainos抽象接口）
│   ├── config.json        ← 参数外置（网格数、步距、交易对…）
│   ├── risk-profile.json  ← 风控硬约束（止损15%、回撤20%、Gas预算$50）
│   └── README.md          ← 收益预期 + 适用市场条件
│
├── Backtest/v4.0.0/
│   ├── backtest-report.json  ← Sharpe、胜率、最大回撤
│   └── equity-curve.csv      ← 资金曲线
│
└── Iteration/
    └── v3.0.0-review-2026-03-10.md  ← v3→v4的分析报告
```

上线后：Cron 每 5 分钟 tick → onchainos 报价+K线+交易 → Discord 通知 → Dashboard 可视化。


path: README.md
content: # OKX Strategy Factory

[中文](./README_CN.md)

A meta-skill that coordinates 5 specialized AI agents to handle the full lifecycle of on-chain trading strategies on OKX OnchainOS: development, backtesting, deployment, publishing, and iteration.

## What is this?

Strategy Factory is an **Agent Team pipeline** — instead of a single AI agent doing everything, a Lead coordinator spawns purpose-built expert agents for each phase. Each agent has strict input/output contracts and quality gates that must pass before the pipeline advances.

Built for developers who want AI agents to develop, validate, deploy, and continuously improve on-chain trading strategies via OKX DEX API.

## Architecture

```
User Request
     │
     ▼
┌─────────┐     ┌───────────┐     ┌─────────┐     ┌──────────┐     ┌───────────┐
│ Strategy │────▶│ Backtest  │────▶│  Infra   │────▶│ Publish  │     │ Iteration │
│  Agent   │     │  Agent    │     │  Agent   │     │  Agent   │     │   Agent   │
│          │     │           │     │          │     │(parallel)│     │(post-LIVE)│
│ Develop  │     │ Validate  │     │ Deploy   │     │ Package  │     │  Review   │
│ strategy │     │ backtest  │     │ to VPS   │     │ as Skill │     │ & propose │
└─────────┘     └───────────┘     └─────────┘     └──────────┘     └───────────┘
     ▲               │ FAIL            │                                  │
     └───────────────┘                 │ FAIL → auto-rollback             │
     ▲                                                                    │
     └────────────────────── user approves optimization ──────────────────┘

                    Lead Agent (coordinator, never writes code)
```

## Platform Compatibility

> **Recommended**: Claude Code, Cursor, Gemini CLI — AI coding IDEs with subagent/teammate spawning.
>
> **Not recommended**: OpenClaw — OpenClaw is a runtime for executing strategies, not for multi-agent development pipelines. Use the individual strategy skills (e.g. `grid-trading`) on OpenClaw instead.

## Installation

**Claude Code** (recommended):
```bash
npx clawhub install okx-strategy-factory
# Or manual:
cp -r okx-strategy-factory ~/.claude/skills/
```

**Cursor**:
```bash
cp -r okx-strategy-factory /path/to/project/.cursor/skills/
```

**Gemini CLI**:
```bash
cp -r okx-strategy-factory /path/to/project/.gemini/skills/
```

## Quick Start

After installation, ask your AI agent:

```
Use the okx-strategy-factory skill to develop a grid trading strategy for ETH/USDC on Base.
```

Or trigger a specific phase:

```
Use okx-strategy-factory to backtest the grid-trading strategy in Strategy/grid-trading/Script/v1.0.0/.
```

```
Use okx-strategy-factory to iterate on the live ETH grid strategy — review the last 7 days.
```

The Lead agent will coordinate the appropriate expert agents automatically.

## Directory Structure

```
okx-strategy-factory/
├── SKILL.md              # Main document: pipeline definition + state machine
├── roles/                # Agent role definitions
│   ├── lead.md           #   Coordinator — spawns agents, enforces gates
│   ├── strategy.md       #   Writes strategy code + config + risk profile
│   ├── backtest.md       #   Validates strategy against historical data
│   ├── infra.md          #   Deploys to VPS via SSH
│   ├── publish.md        #   Packages strategy as cross-platform Skill
│   └── iteration.md      #   Post-LIVE review and optimization proposals
├── templates/            # Structured templates
│   └── requirements.md   #   Strategy requirements template (Lead fills before spawning Strategy agent)
├── references/           # Shared technical references
│   ├── api-interfaces.md #   Adapter interface spec (wallet, dex, position)
│   ├── risk-schema.json  #   JSON Schema for risk-profile.json validation
│   └── strategy-lessons.md # Strategy lessons learned (risk, MTF, cost, pitfalls)
├── assets/               # Templates and tools
│   ├── product-skill-template/  # Strategy-specific packaging templates (.tmpl)
│   ├── skill-templates/         # Skill design pattern templates (pipeline, tool-wrapper, etc.)
│   └── publish.sh               # Skill validation and publishing script
└── hooks/                # Pipeline automation
    ├── task-completed-gate.sh   # Quality gate checks between steps
    └── teammate-idle-reassign.sh # Reassign idle agents
```

## Agent Roles

| Role | Responsibility | Input | Output |
|------|---------------|-------|--------|
| **Lead** | Coordinate pipeline, enforce quality gates, manage state | User request | Spawn prompts, state.json updates |
| **Strategy** | Write strategy logic + config + risk profile | `Strategy/{strategy}/requirements.md` (structured requirements distilled by Lead) | `Strategy/{strategy}/Script/v{ver}/` (strategy.js, config.json, risk-profile.json, README.md) |
| **Backtest** | Validate strategy against historical data | Strategy script directory | `Strategy/{strategy}/Backtest/v{ver}/` (backtest-report.json, equity-curve.csv) |
| **Infra** | Deploy to VPS (SSH, pm2, health check, rollback) | Backtest-passed strategy version | Running process on VPS, VERSION file |
| **Publish** | Package strategy as cross-platform Skill + GitHub release | Backtest-passed strategy + deploy confirmation | `{strategy}/` (manifest.json, install.sh, SKILL.md) |
| **Iteration** | Analyze live performance, propose optimizations | On-chain trade history + market data | `Strategy/{strategy}/Iteration/v{ver}-review-{date}.md` |

## Pipeline

```
Step 1: Strategy Development
  Lead distills discussion into Strategy/{strategy}/requirements.md → user confirms → spawn Strategy agent
  Gate: strategy.js + config.json + risk-profile.json + README.md all present
    │
    ▼
Step 2: Backtest Validation
  Gate: Compliance PASS + Sharpe > 1.0 + Win Rate > 40%
  FAIL → back to Step 1 with failure details
    │
    ▼
Step 3: Deploy to VPS ──────────────────── Step 4: Publish as Skill (parallel start)
  Gate: pm2 online + no errors in 30s       Gate: manifest.json + install.sh + adapters
  FAIL → auto-rollback to previous version   GitHub release waits for Step 3 success
    │
    ▼
Step 5: Iteration (post-LIVE, on-demand)
  Gate: user confirms optimization proposal
  Approved → new version starts at Step 1 (must re-backtest)
```

Steps execute strictly in order. No skipping. Iteration always triggers a full re-run from Step 1.

## Prerequisites

- **onchainos CLI** — `npx skills add okx/onchainos-skills`
- **OKX API Key** — with DEX trading permissions
- **OnchainOS Agentic Wallet** — with TEE signing enabled
- **Python 3.10+** — for backtest engine and trading scripts
- **VPS** (optional) — for live deployment
- **1Password CLI** (optional) — for secure credential management (`op`)

## License

Apache-2.0


path: README_CN.md
content: # OKX 策略工厂

[English](./README.md)

一个元技能，协调 5 个专业 AI 智能体，完成 OKX OnchainOS 链上交易策略的完整生命周期：开发、回测、部署、发布和迭代。

## 这是什么？

策略工厂是一个 **Agent Team 流水线** —— 不是一个 AI 智能体包揽一切，而是由 Lead 协调者为每个阶段生成专用的专家智能体。每个智能体有严格的输入/输出契约和质量门禁，必须通过才能进入下一阶段。

适合希望用 AI 智能体通过 OKX DEX API 开发、验证、部署并持续优化链上交易策略的开发者。

## 架构

```
用户请求
   │
   ▼
┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│ Strategy │────▶│ Backtest │────▶│  Infra   │────▶│ Publish  │     │ Iteration│
│  Agent   │     │  Agent   │     │  Agent   │     │  Agent   │     │  Agent   │
│          │     │          │     │          │     │ (并行启动)│     │(上线后)  │
│ 开发策略  │     │ 回测验证  │     │ 部署到VPS │     │ 打包为技能│     │ 复盘优化 │
└──────────┘     └──────────┘     └──────────┘     └──────────┘     └──────────┘
     ▲               │ 失败            │                                  │
     └───────────────┘                 │ 失败 → 自动回滚                   │
     ▲                                                                    │
     └──────────────────── 用户批准优化方案 ──────────────────────────────┘

                    Lead Agent（协调者，不写代码）
```

## 平台兼容性

> **推荐**: Claude Code、Cursor、Gemini CLI —— 支持子智能体/队友生成的 AI 编程 IDE。
>
> **不推荐**: OpenClaw —— OpenClaw 是策略执行运行时，不适合多智能体开发流水线。请在 OpenClaw 上使用独立策略技能（如 `grid-trading`）。

## 安装

**Claude Code**（推荐）:
```bash
npx clawhub install okx-strategy-factory
# 或手动安装:
cp -r okx-strategy-factory ~/.claude/skills/
```

**Cursor**:
```bash
cp -r okx-strategy-factory /path/to/project/.cursor/skills/
```

**Gemini CLI**:
```bash
cp -r okx-strategy-factory /path/to/project/.gemini/skills/
```

## 快速开始

安装后，对你的 AI 智能体说：

```
使用 okx-strategy-factory 技能，为 Base 链上的 ETH/USDC 开发一个网格交易策略。
```

或触发特定阶段：

```
使用 okx-strategy-factory 回测 Strategy/grid-trading/Script/v1.0.0/ 中的网格策略。
```

```
使用 okx-strategy-factory 对正在运行的 ETH 网格策略做迭代复盘 —— 回顾最近 7 天。
```

Lead 智能体会自动协调对应的专家智能体。

## 目录结构

```
okx-strategy-factory/
├── SKILL.md              # 主文档：流水线定义 + 状态机
├── roles/                # 智能体角色定义
│   ├── lead.md           #   协调者 —— 生成智能体、执行门禁
│   ├── strategy.md       #   编写策略代码 + 配置 + 风控档案
│   ├── backtest.md       #   基于历史数据验证策略
│   ├── infra.md          #   通过 SSH 部署到 VPS
│   ├── publish.md        #   将策略打包为跨平台技能
│   └── iteration.md      #   上线后复盘与优化建议
├── templates/            # 结构化模板
│   └── requirements.md   #   策略需求模板（Lead 在 spawn Strategy agent 前填写）
├── references/           # 共享技术参考
│   ├── api-interfaces.md #   适配器接口规范（钱包、DEX、持仓）
│   ├── risk-schema.json  #   risk-profile.json 的 JSON Schema
│   └── strategy-lessons.md # 策略经验库（风控、MTF、成本、陷阱）
├── assets/               # 模板和工具
│   ├── product-skill-template/  # 策略专用打包模板（.tmpl）
│   ├── skill-templates/         # Skill 设计模式模板（pipeline、tool-wrapper 等）
│   └── publish.sh               # Skill 验证与发布脚本
└── hooks/                # 流水线自动化
    ├── task-completed-gate.sh   # 步骤间质量门禁检查
    └── teammate-idle-reassign.sh # 空闲智能体重新分配
```

## 智能体角色

| 角色 | 职责 | 输入 | 输出 |
|------|------|------|------|
| **Lead** | 协调流水线、执行质量门禁、管理状态 | 用户请求 | 生成提示词、更新 state.json |
| **Strategy** | 编写策略逻辑 + 配置 + 风控档案 | `Strategy/{strategy}/requirements.md`（Lead 提炼的结构化需求） | `Strategy/{strategy}/Script/v{ver}/`（strategy.js, config.json, risk-profile.json, README.md） |
| **Backtest** | 基于历史数据验证策略 | 策略脚本目录 | `Strategy/{strategy}/Backtest/v{ver}/`（backtest-report.json, equity-curve.csv） |
| **Infra** | 部署到 VPS（SSH、pm2、健康检查、回滚） | 回测通过的策略版本 | VPS 上运行的进程、VERSION 文件 |
| **Publish** | 将策略打包为跨平台技能 + GitHub 发布 | 回测通过的策略 + 部署确认 | `{strategy}/`（manifest.json, install.sh, SKILL.md） |
| **Iteration** | 分析实盘表现、提出优化建议 | 链上交易记录 + 市场数据 | `Strategy/{strategy}/Iteration/v{ver}-review-{date}.md` |

## 流水线

```
步骤 1: 策略开发
  Lead 从讨论中提炼需求 → 写入 Strategy/{strategy}/requirements.md → 用户确认 → spawn Strategy agent
  门禁: strategy.js + config.json + risk-profile.json + README.md 全部就位
    │
    ▼
步骤 2: 回测验证
  门禁: 合规 PASS + Sharpe > 1.0 + 胜率 > 40%
  失败 → 携带失败详情返回步骤 1
    │
    ▼
步骤 3: 部署到 VPS ────────────────── 步骤 4: 发布为技能（并行启动）
  门禁: pm2 在线 + 30s 内无报错       门禁: manifest.json + install.sh + 适配器
  失败 → 自动回滚到上一版本            GitHub release 等待步骤 3 成功
    │
    ▼
步骤 5: 迭代（上线后，按需触发）
  门禁: 用户确认优化方案
  批准 → 新版本从步骤 1 重新开始（必须重新回测）
```

严格顺序执行，不可跳步。迭代始终触发从步骤 1 的完整重跑。

## 前置条件

- **onchainos CLI** — `npx skills add okx/onchainos-skills`
- **OKX API Key** — 需有 DEX 交易权限
- **OnchainOS Agentic Wallet** — 需启用 TEE 签名
- **Python 3.10+** — 用于回测引擎和交易脚本
- **VPS**（可选） — 用于实盘部署
- **1Password CLI**（可选） — 安全凭证管理（`op`）

## 许可证

Apache-2.0


path: assets/publish.sh
content: #!/usr/bin/env bash
#
# publish.sh - 验证并发布一个新的 Skill 到 Skills 仓库
#
# 用法:
#   ./publish.sh <skill-name>                    # 验证 + git commit
#   ./publish.sh <skill-name> --push             # 验证 + git commit + push
#   ./publish.sh <skill-name> --dry-run          # 仅验证，不提交
#   ./publish.sh <skill-name> --copy-script <path>  # 复制策略脚本到 Skill 目录后发布
#
# 示例:
#   ./publish.sh grid-trading
#   ./publish.sh momentum-breakout --copy-script ~/scripts/momentum.py --push
#   ./publish.sh new-strategy --dry-run

set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"

# --- 颜色 ---
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m'

# --- 参数解析 ---
SKILL_NAME=""
PUSH=false
DRY_RUN=false
COPY_SCRIPT=""

while [[ $# -gt 0 ]]; do
    case $1 in
        --push)       PUSH=true; shift ;;
        --dry-run)    DRY_RUN=true; shift ;;
        --copy-script) COPY_SCRIPT="$2"; shift 2 ;;
        -h|--help)
            echo "用法: $0 <skill-name> [--push] [--dry-run] [--copy-script <path>]"
            echo ""
            echo "选项:"
            echo "  --push              验证 + commit 后自动 push"
            echo "  --dry-run           仅验证格式，不执行 git 操作"
            echo "  --copy-script PATH  复制策略脚本到 Skill 目录"
            echo ""
            echo "示例:"
            echo "  $0 grid-trading"
            echo "  $0 momentum --copy-script ~/scripts/momentum.py --push"
            exit 0
            ;;
        *)
            if [[ -z "$SKILL_NAME" ]]; then
                SKILL_NAME="$1"
            else
                echo -e "${RED}错误: 未知参数 '$1'${NC}" >&2
                exit 1
            fi
            shift
            ;;
    esac
done

if [[ -z "$SKILL_NAME" ]]; then
    echo -e "${RED}错误: 请指定 skill 名称${NC}" >&2
    echo "用法: $0 <skill-name> [--push] [--dry-run] [--copy-script <path>]"
    exit 1
fi

SKILL_DIR="$REPO_ROOT/$SKILL_NAME"
SKILL_FILE="$SKILL_DIR/SKILL.md"

# --- 辅助函数 ---
pass() { echo -e "  ${GREEN}✓${NC} $1"; }
fail() { echo -e "  ${RED}✗${NC} $1"; ERRORS=$((ERRORS + 1)); }
warn() { echo -e "  ${YELLOW}!${NC} $1"; WARNINGS=$((WARNINGS + 1)); }
info() { echo -e "  ${BLUE}→${NC} $1"; }

ERRORS=0
WARNINGS=0

# --- Step 0: 复制脚本（如果指定） ---
if [[ -n "$COPY_SCRIPT" ]]; then
    echo -e "\n${BLUE}[0/4] 复制策略脚本${NC}"
    if [[ ! -f "$COPY_SCRIPT" ]]; then
        fail "脚本不存在: $COPY_SCRIPT"
        exit 1
    fi
    mkdir -p "$SKILL_DIR"
    cp "$COPY_SCRIPT" "$SKILL_DIR/"
    pass "已复制 $(basename "$COPY_SCRIPT") -> $SKILL_DIR/"
fi

# --- Step 1: 检查文件存在 ---
echo -e "\n${BLUE}[1/4] 检查文件结构${NC}"

if [[ ! -d "$SKILL_DIR" ]]; then
    fail "Skill 目录不存在: $SKILL_DIR"
    echo -e "\n${RED}发布失败: 请先创建 Skill 目录和 SKILL.md${NC}"
    exit 1
fi

if [[ ! -f "$SKILL_FILE" ]]; then
    fail "SKILL.md 不存在: $SKILL_FILE"
    echo -e "\n${RED}发布失败: 请先创建 SKILL.md${NC}"
    exit 1
fi

pass "SKILL.md 存在"

# 检查是否有额外的策略文件
EXTRA_FILES=$(find "$SKILL_DIR" -type f ! -name "SKILL.md" ! -name ".*" 2>/dev/null | head -5)
if [[ -n "$EXTRA_FILES" ]]; then
    info "包含额外文件:"
    echo "$EXTRA_FILES" | while read -r f; do
        info "  $(basename "$f")"
    done
fi

# --- Step 2: 验证 YAML frontmatter ---
echo -e "\n${BLUE}[2/4] 验证 YAML frontmatter${NC}"

# 检查是否以 --- 开头
if ! head -1 "$SKILL_FILE" | grep -q '^---$'; then
    fail "SKILL.md 必须以 '---' 开头（YAML frontmatter）"
else
    pass "YAML frontmatter 起始标记"
fi

# 提取 frontmatter（第一个 --- 到第二个 --- 之间）
FRONTMATTER=$(awk 'BEGIN{n=0} /^---$/{n++; if(n==2) exit; next} n==1{print}' "$SKILL_FILE")

# 检查必需字段
check_field() {
    local field="$1"
    local label="$2"
    if echo "$FRONTMATTER" | grep -q "^${field}:"; then
        local value
        value=$(echo "$FRONTMATTER" | grep "^${field}:" | head -1 | sed "s/^${field}:[[:space:]]*//")
        if [[ -z "$value" || "$value" == '""' || "$value" == "''" ]]; then
            fail "$label 为空"
        else
            pass "$label: $value"
        fi
    else
        fail "缺少必需字段: $field"
    fi
}

check_field "name" "名称"
check_field "description" "描述"
check_field "license" "许可证"

# 检查 metadata 子字段
if echo "$FRONTMATTER" | grep -q "^metadata:"; then
    pass "metadata 章节存在"
    if echo "$FRONTMATTER" | grep -q "author:"; then
        pass "metadata.author 存在"
    else
        fail "缺少 metadata.author"
    fi
    if echo "$FRONTMATTER" | grep -q "version:"; then
        VERSION=$(echo "$FRONTMATTER" | grep "version:" | sed 's/.*version:[[:space:]]*//' | tr -d '"' | tr -d "'" | xargs)
        if echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+'; then
            pass "version 格式正确: $VERSION"
        else
            warn "version 建议使用 semver 格式 (x.y.z)，当前: $VERSION"
        fi
    else
        fail "缺少 metadata.version"
    fi
else
    fail "缺少 metadata 章节"
fi

# 检查 description 长度（至少 50 字符，用于 AI agent 路由）
DESC_LEN=$(echo "$FRONTMATTER" | grep "^description:" | wc -c | tr -d ' ')
if [[ "$DESC_LEN" -lt 60 ]]; then
    warn "description 偏短（<60 字符），建议写详细以改善 AI agent 路由匹配"
fi

# 检查 pattern 字段
VALID_PATTERNS="tool-wrapper generator reviewer inversion pipeline"
PATTERN_VALUE=$(echo "$FRONTMATTER" | grep "pattern:" | sed 's/.*pattern:[[:space:]]*//' | tr -d '"' | tr -d "'" | xargs || true)
if [[ -n "$PATTERN_VALUE" ]]; then
    # 支持复合模式（逗号分隔）
    ALL_VALID=true
    IFS=',' read -ra PATTERNS <<< "$PATTERN_VALUE"
    for p in "${PATTERNS[@]}"; do
        p=$(echo "$p" | xargs)  # trim whitespace
        if echo "$VALID_PATTERNS" | grep -qw "$p"; then
            :
        else
            fail "无效的 pattern: '$p' (允许: $VALID_PATTERNS)"
            ALL_VALID=false
        fi
    done
    if [[ "$ALL_VALID" == true ]]; then
        pass "pattern: $PATTERN_VALUE"
        # 检查 pattern 特有的 metadata 字段
        for p in "${PATTERNS[@]}"; do
            p=$(echo "$p" | xargs)
            case "$p" in
                generator)
                    if ! echo "$FRONTMATTER" | grep -q "output-format:"; then
                        warn "generator 模式建议添加 metadata.output-format 字段"
                    fi
                    ;;
                reviewer)
                    if ! echo "$FRONTMATTER" | grep -q "severity-levels:"; then
                        warn "reviewer 模式建议添加 metadata.severity-levels 字段"
                    fi
                    ;;
                inversion)
                    if ! echo "$FRONTMATTER" | grep -q "interaction:"; then
                        warn "inversion 模式建议添加 metadata.interaction 字段"
                    fi
                    ;;
                pipeline)
                    if ! echo "$FRONTMATTER" | grep -q "steps:"; then
                        warn "pipeline 模式建议添加 metadata.steps 字段"
                    fi
                    ;;
            esac
        done
    fi
else
    warn "未指定 pattern 字段，建议使用: $VALID_PATTERNS"
fi

# --- Step 3: 验证内容结构 ---
echo -e "\n${BLUE}[3/4] 验证内容结构${NC}"

CONTENT=$(cat "$SKILL_FILE")

# 必需章节
check_section() {
    local heading="$1"
    local label="$2"
    local required="${3:-true}"
    if echo "$CONTENT" | grep -qiE "^##+ .*($heading)" 2>/dev/null; then
        pass "章节: $label"
    elif [[ "$required" == "true" ]]; then
        fail "缺少必需章节: $label (需要包含 '$heading' 的标题)"
    else
        warn "建议添加章节: $label"
    fi
}

# 通用必需章节
check_section "Architecture|架构" "Architecture（架构）"
check_section "Instruction|Algorithm|算法|Core|指令" "Instructions / Core Algorithm（指令/核心算法）"

# 按 pattern 检查特有章节
if [[ -n "$PATTERN_VALUE" ]]; then
    for p in "${PATTERNS[@]}"; do
        p=$(echo "$p" | xargs)
        case "$p" in
            tool-wrapper)
                check_section "Trigger|触发|Keyword" "Trigger Keywords（触发关键词）" "false"
                check_section "Context.Load|上下文加载" "Context Loading Rules（上下文加载规则）" "false"
                ;;
            generator)
                check_section "Template|模板|Variable" "Template / Variables（模板/变量）" "false"
                check_section "Style|风格|Output" "Style / Output Format（风格/输出格式）" "false"
                ;;
            reviewer)
                check_section "Checklist|清单|Severity" "Review Checklist / Severity（检查清单/严重程度）" "false"
                ;;
            inversion)
                check_section "Phase|阶段" "Phases（采访阶段）" "false"
                check_section "Synthesis|综合|Gate|门控" "Synthesis / Gates（综合/门控）" "false"
                ;;
            pipeline)
                check_section "Step|步骤" "Pipeline Steps（管道步骤）" "false"
                check_section "Gate|门控|Checkpoint" "Gates / Checkpoints（门控/检查点）" "false"
                check_section "Fail|Rollback|失败|回滚" "Failure Handling（失败处理）" "false"
                ;;
        esac
    done
fi

# 通用推荐章节
check_section "Parameter|参数|Tunable" "Parameters（参数）" "false"
check_section "Risk|风险|风控" "Risk Controls（风险控制）" "false"
check_section "Anti.Pattern|反模式" "Anti-Patterns（反模式）" "false"
check_section "State|状态" "State Schema（状态模式）" "false"
check_section "Execut|执行|Pipeline" "Execution Pipeline（执行流程）" "false"
check_section "Extend|扩展|Adapt" "Extension Points（扩展点）" "false"
check_section "PnL|收益" "PnL Tracking（收益追踪）" "false"

# 检查 pattern 对应的目录结构
if [[ -n "$PATTERN_VALUE" ]]; then
    for p in "${PATTERNS[@]}"; do
        p=$(echo "$p" | xargs)
        case "$p" in
            tool-wrapper)
                if [[ -d "$SKILL_DIR/references" ]] && [[ -n "$(ls -A "$SKILL_DIR/references/" 2>/dev/null)" ]]; then
                    pass "references/ 目录存在且非空（tool-wrapper 必需）"
                else
                    warn "tool-wrapper 模式建议创建 references/ 目录存放 API 规范"
                fi
                ;;
            generator)
                if [[ -d "$SKILL_DIR/assets" ]] && [[ -n "$(ls -A "$SKILL_DIR/assets/" 2>/dev/null)" ]]; then
                    pass "assets/ 目录存在且非空（generator 必需）"
                else
                    warn "generator 模式建议创建 assets/ 目录存放输出模板"
                fi
                ;;
            reviewer)
                if [[ -f "$SKILL_DIR/references/review-checklist.md" ]]; then
                    pass "references/review-checklist.md 存在（reviewer 必需）"
                else
                    warn "reviewer 模式建议创建 references/review-checklist.md"
                fi
                ;;
        esac
    done
fi

# 检查是否有参数表格
if echo "$CONTENT" | grep -q '|.*Parameter\|参数.*|.*Default\|默认.*|'; then
    pass "包含参数表格"
elif echo "$CONTENT" | grep -q '|.*|.*|.*|'; then
    pass "包含表格（请确保参数有 Default 列）"
else
    warn "未发现参数表格，建议使用 | Parameter | Default | Description | 格式"
fi

# 检查是否有代码块
CODE_BLOCKS=$(echo "$CONTENT" | grep -c '```' || true)
if [[ "$CODE_BLOCKS" -ge 4 ]]; then
    pass "包含 $((CODE_BLOCKS / 2)) 个代码块"
elif [[ "$CODE_BLOCKS" -ge 2 ]]; then
    warn "仅有 $((CODE_BLOCKS / 2)) 个代码块，策略类 Skill 建议包含更多代码示例"
else
    warn "几乎没有代码块，策略类 Skill 应包含算法实现和命令示例"
fi

# 文件大小检查
FILE_SIZE=$(wc -c < "$SKILL_FILE" | tr -d ' ')
if [[ "$FILE_SIZE" -lt 500 ]]; then
    warn "SKILL.md 过短（${FILE_SIZE} 字节），可能缺少关键内容"
elif [[ "$FILE_SIZE" -gt 100000 ]]; then
    warn "SKILL.md 过长（${FILE_SIZE} 字节），考虑拆分为主文件 + references/"
else
    pass "文件大小合理: ${FILE_SIZE} 字节"
fi

# --- 验证结果 ---
echo -e "\n${BLUE}━━━ 验证结果 ━━━${NC}"
echo -e "  错误: ${RED}${ERRORS}${NC}  警告: ${YELLOW}${WARNINGS}${NC}"

if [[ $ERRORS -gt 0 ]]; then
    echo -e "\n${RED}验证失败: 请修复以上 ${ERRORS} 个错误后重试${NC}"
    exit 1
fi

if [[ "$DRY_RUN" == true ]]; then
    echo -e "\n${GREEN}验证通过 (dry-run 模式，未执行 git 操作)${NC}"
    exit 0
fi

# --- Step 4: Git commit ---
echo -e "\n${BLUE}[4/4] Git 提交${NC}"

cd "$REPO_ROOT"

# 获取 skill name 和 version 用于 commit message
SKILL_NAME_FM=$(echo "$FRONTMATTER" | grep "^name:" | sed 's/^name:[[:space:]]*//')
SKILL_VERSION=$(echo "$FRONTMATTER" | grep "version:" | sed 's/.*version:[[:space:]]*"\?\([^"]*\)"\?/\1/' | tr -d '"')

# 检查是否有变更
if git diff --quiet "$SKILL_NAME/" 2>/dev/null && \
   git diff --cached --quiet "$SKILL_NAME/" 2>/dev/null && \
   [[ -z "$(git ls-files --others --exclude-standard "$SKILL_NAME/")" ]]; then
    echo -e "${YELLOW}没有检测到变更，跳过提交${NC}"
    exit 0
fi

# Stage skill 目录
git add "$SKILL_NAME/"
pass "已暂存 $SKILL_NAME/"

# 判断是新增还是更新
if git log --oneline -- "$SKILL_NAME/SKILL.md" 2>/dev/null | head -1 | grep -q .; then
    COMMIT_MSG="Update ${SKILL_NAME_FM} skill v${SKILL_VERSION}"
else
    COMMIT_MSG="Add ${SKILL_NAME_FM} skill v${SKILL_VERSION}"
fi

git commit -m "$(cat <<EOF
${COMMIT_MSG}
EOF
)"
pass "已提交: $COMMIT_MSG"

if [[ "$PUSH" == true ]]; then
    BRANCH=$(git branch --show-current)
    git push origin "$BRANCH"
    pass "已推送到 origin/$BRANCH"
fi

echo -e "\n${GREEN}发布完成: $SKILL_NAME/${NC}"


path: assets/skill-templates/SKILL_TEMPLATE.md
content: ---
name: <skill-name>
description: "<一句话描述 Skill 的核心能力、适用场景和触发关键词。用于 AI agent 路由匹配，写得越精确越好。>"
license: Apache-2.0
metadata:
  author: <作者>
  version: "<major.minor.patch>"
  pattern: "<tool-wrapper | generator | reviewer | inversion | pipeline>"
  # 复合模式用逗号分隔: "pipeline, tool-wrapper"
  # 可选字段（按 pattern 需要添加）:
  # output-format: "markdown"          # generator 用
  # severity-levels: "error,warning,info"  # reviewer 用
  # interaction: "multi-turn"          # inversion 用
  # steps: "N"                         # pipeline 用
---

# <Skill 名称>

一句话概述：Skill 做什么、怎么触发、输出到哪里。

<!--
选择你的设计模式，从 Skills/templates/ 目录获取对应模板：

| Pattern        | 适用场景                           | 模板文件                  |
|----------------|-----------------------------------|--------------------------|
| tool-wrapper   | 按需加载 API/库的上下文             | templates/tool-wrapper.md |
| generator      | 强制一致的输出结构                  | templates/generator.md    |
| reviewer       | 分离"检查什么"和"如何检查"          | templates/reviewer.md     |
| inversion      | Agent 先采访用户再行动              | templates/inversion.md    |
| pipeline       | 严格顺序多步工作流+硬检查点          | templates/pipeline.md     |

模式可以组合：
- Pipeline + Tool Wrapper: 多步工作流，每步加载不同 API 文档
- Generator + Inversion: 先收集变量，再填充模板
- Pipeline + Reviewer: 工作流中包含审查步骤

组合模式时，在 metadata.pattern 用逗号分隔，然后从各模板中挑选需要的章节合并。
-->

## Architecture

```
<系统架构图 - 用 ASCII art 展示数据流>
```

**依赖的外部服务/Skill**:
- <服务1>: `<调用方式>` -> `<具体命令>`

## Instructions

<!--
这是 Skill 的核心指令区。根据 pattern 不同，结构差异很大。
请参考对应的 templates/*.md 获取该 pattern 的标准指令结构。
-->

## Directory Structure

```
<skill-name>/
├── SKILL.md              # 主文件（必需）
├── references/           # API 规范、风格指南、检查清单等（按需）
│   └── <context-file>.md
└── assets/               # 输出模板、脚手架等（按需）
    └── <template-file>.md
```

## Anti-Patterns

| Pattern | Problem |
|---|---|
| <反模式1> | <为什么有问题> |


path: assets/skill-templates/generator.md
content: ---
name: <skill-name>
description: "<描述：生成一致结构的输出，如报告、配置、文档等。包含触发关键词。>"
license: Apache-2.0
metadata:
  author: <作者>
  version: "<major.minor.patch>"
  pattern: "generator"
  output-format: "markdown"
  # output-format: "json" | "yaml" | "code" | "markdown"
---

# <Skill 名称> (Generator)

<!--
Generator 模式：强制一致的输出结构。
用 assets/ 存输出模板，references/ 存风格指南。
指令协调检索并逐步填充。

核心思路：
- assets/ 目录存放输出模板（骨架）
- references/ 存放风格指南和约束规则
- 指令定义：加载模板 → 加载风格 → 询问缺失信息 → 填充 → 输出
-->

一句话概述：根据输入数据生成结构一致的 <输出类型>。

## Architecture

```
Input Data / User Request
    ↓
Load Template (assets/<template>.md)
    ↓
Load Style Guide (references/<style>.md)
    ↓
Check for Missing Variables → Ask User (if needed)
    ↓
Fill Template → Validate → Output
```

## Instructions

### Step 1: Load Template

```
LOAD assets/<output-template>.md
This defines the output skeleton — every section is REQUIRED unless marked [optional].
```

### Step 2: Load Style Guide

```
LOAD references/<style-guide>.md
Apply these rules to ALL generated content:
- Tone, voice, formatting constraints
- Domain-specific terminology
- Naming conventions
```

### Step 3: Collect Variables

<!-- 列出模板需要的所有变量 -->

| Variable | Source | Required | Default |
|---|---|---|---|
| `<var-1>` | User input | Yes | — |
| `<var-2>` | Auto-detect | No | `<default>` |
| `<var-3>` | User input | Yes | — |

**If any required variable is missing**: Ask the user before proceeding. Do NOT guess.

### Step 4: Fill Template

```
For each section in the template:
1. Substitute variables
2. Apply style guide rules
3. Validate against constraints (length limits, format rules, etc.)
```

### Step 5: Output

```
Output the filled template in <output-format> format.
If validation fails, report which sections need fixes.
```

## Template Variables Reference

<!-- 详细描述每个变量的格式要求 -->

### `<var-1>`
- Type: string
- Format: <格式描述>
- Constraints: <约束>
- Example: `<示例值>`

### `<var-2>`
- Type: string
- Format: <格式描述>
- Constraints: <约束>
- Example: `<示例值>`

## Directory Structure

```
<skill-name>/
├── SKILL.md                    # 主文件：生成流程指令
├── assets/                     # 输出模板（骨架）
│   ├── <output-template>.md    # 主输出模板
│   └── <variant-template>.md   # 变体模板（如不同格式）
└── references/                 # 风格指南和约束
    ├── <style-guide>.md        # 语气、格式、术语
    └── <constraints>.md        # 字数限制、必填字段等
```

## Anti-Patterns

| Pattern | Problem |
|---|---|
| 不加载模板直接生成 | 输出结构不一致 |
| 猜测缺失变量 | 输出内容不准确，应该问用户 |
| 模板里写死内容 | 模板应该是骨架+占位符，不是完整文档 |
| 风格指南太模糊 | "写得好一点" 没有用，要具体到格式规则 |
| 跳过验证步骤 | 输出可能不符合约束 |


path: assets/skill-templates/inversion.md
content: ---
name: <skill-name>
description: "<描述：通过多轮对话收集需求后再行动。包含触发关键词。>"
license: Apache-2.0
metadata:
  author: <作者>
  version: "<major.minor.patch>"
  pattern: "inversion"
  interaction: "multi-turn"
---

# <Skill 名称> (Inversion)

<!--
Inversion 模式：Agent 先采访用户再行动。
分阶段提问，显式门控（"DO NOT start building until all phases are complete"）。

核心思路：
- 分 Phase 提问，收集完整需求
- 每个 Phase 有明确的完成条件
- 所有 Phase 完成后才进入 Synthesis（生成）阶段
- 防止 agent 在信息不足时就开始行动
-->

一句话概述：通过结构化采访收集完整需求，然后生成 <输出类型>。

## Architecture

```
User Request
    ↓
Phase 1: <领域1> 提问 → 收集答案
    ↓ (gate: all required answers collected)
Phase 2: <领域2> 提问 → 收集答案
    ↓ (gate: all required answers collected)
Phase N: <领域N> 提问 → 收集答案
    ↓ (gate: ALL phases complete)
Synthesis: 生成输出
```

## Instructions

**CRITICAL RULE**: DO NOT start building/generating until ALL phases are complete.
If the user tries to skip ahead, remind them which phase is pending.

### Phase 1: <领域名称>

**Goal**: Understand <what this phase collects>

Ask the following questions (adapt wording to context):

1. <问题1>
2. <问题2>
3. <问题3>

**Completion gate**:
- [ ] <条件1 已满足>
- [ ] <条件2 已满足>

**If user is unsure**: Offer these defaults: <defaults>

### Phase 2: <领域名称>

**Goal**: Understand <what this phase collects>

Ask the following questions:

1. <问题1>
2. <问题2>
3. <问题3>

**Completion gate**:
- [ ] <条件1 已满足>
- [ ] <条件2 已满足>

<!-- 按需添加更多 Phase -->

### Phase N: Confirmation

**Goal**: Confirm all collected information before proceeding

```
Present a summary of all collected answers:

Phase 1 (<领域1>):
  - <var>: <collected value>

Phase 2 (<领域2>):
  - <var>: <collected value>

Ask: "Is this correct? Should I proceed with generation?"
```

**Completion gate**:
- [ ] User explicitly confirms

### Synthesis

**Precondition**: ALL phases above are complete and confirmed.

```
1. Compile all collected variables
2. [If combined with Generator] Load template from assets/
3. Generate output using collected context
4. Present output for review
```

## Phase Design Guidelines

<!-- 给 Skill 作者的指导 -->

- 每个 Phase 聚焦一个领域，不要混杂
- 问题按依赖关系排序（前面的答案可能影响后面的问题）
- 必须提供 "unsure" 的默认值选项
- Phase 数量建议 2-4 个，太多会让用户疲劳
- 最后一个 Phase 总是 Confirmation

## Directory Structure

```
<skill-name>/
├── SKILL.md                    # 主文件：Phase 定义 + 门控规则
├── references/                 # 领域知识（辅助提问）
│   └── <domain-context>.md     # 帮助 agent 提出更好问题的背景知识
└── assets/                     # 输出模板（如果结合 Generator）
    └── <output-template>.md
```

## Anti-Patterns

| Pattern | Problem |
|---|---|
| 信息不全就开始行动 | 输出质量差，需要反复修改 |
| 一次问太多问题（>5个） | 用户认知过载 |
| 没有完成门控 | Agent 可能跳过关键问题 |
| 不提供默认值 | 用户不确定时被卡住 |
| Phase 之间有循环依赖 | 无法线性推进 |
| 不做最终确认 | 误解需求后浪费大量工作 |


path: assets/skill-templates/pipeline.md
content: ---
name: <skill-name>
description: "<描述：严格顺序的多步工作流，每步有门控条件。包含触发关键词。>"
license: Apache-2.0
metadata:
  author: <作者>
  version: "<major.minor.patch>"
  pattern: "pipeline"
  steps: "<N>"
---

# <Skill 名称> (Pipeline)

<!--
Pipeline 模式：严格顺序多步工作流 + 硬检查点。
显式菱形门控条件，需要满足条件才能进入下一步。

核心思路：
- 每步加载不同的 reference 文件
- 步骤间有门控条件（不能跳过）
- 门控可以是自动检查或用户确认
- 适合部署、交易执行、数据处理等多步流程

与 Inversion 的区别：
- Inversion 是"收集信息后一次性生成"
- Pipeline 是"每步都执行操作，步步推进"
-->

一句话概述：按严格顺序执行 N 步工作流，每步有门控检查。

## Architecture

```
Step 1: <步骤名>
    ↓ [Gate: <条件>]
Step 2: <步骤名>
    ↓ [Gate: <条件>]
Step N: <步骤名>
    ↓
Output / Completion
```

## Instructions

**CRITICAL RULE**: Steps MUST execute in order. Do NOT skip steps or proceed past a gate
that has not been satisfied. If a gate fails, STOP and report.

### Step 1: <步骤名称>

**Load**: `references/<step1-context>.md`

**Actions**:
1. <操作1>
2. <操作2>
3. <操作3>

**Output**: <本步骤的输出>

**Gate** (ALL must pass):
- [ ] <条件1> — 自动检查: `<检查命令或逻辑>`
- [ ] <条件2> — 用户确认: "Proceed to Step 2?"

### Step 2: <步骤名称>

**Load**: `references/<step2-context>.md`

**Input**: Step 1 output

**Actions**:
1. <操作1>
2. <操作2>

**Output**: <本步骤的输出>

**Gate**:
- [ ] <条件> — 自动检查: `<检查命令或逻辑>`

<!-- 按需添加更多步骤 -->

### Step N: <最终步骤>

**Load**: `references/<stepN-context>.md` (if needed)

**Input**: Step N-1 output

**Actions**:
1. <操作1>
2. <操作2>

**Output**: <最终输出>

**Completion criteria**:
- [ ] <最终验证条件>

## Gate Types

<!-- 门控类型参考 -->

| Type | Description | Example |
|---|---|---|
| `auto-check` | 自动验证，无需用户介入 | 文件存在、API 返回 200、测试通过 |
| `user-confirm` | 需要用户确认才能继续 | "Review the output. Proceed?" |
| `threshold` | 数值满足条件 | `success_rate > 95%` |
| `composite` | 多个条件 AND/OR 组合 | `auto-check AND user-confirm` |

## Failure & Rollback

<!-- 定义步骤失败时的处理策略 -->

```
IF Step N fails:
  1. Log failure reason
  2. [If rollback defined] Execute rollback for Step N
  3. Report to user: which step failed, why, how to fix
  4. DO NOT proceed to Step N+1

Rollback actions (optional, per step):
  Step 1 rollback: <撤销操作>
  Step 2 rollback: <撤销操作>
```

## State Tracking

<!-- Pipeline 可以用状态追踪执行进度 -->

```json
{
  "pipeline": "<skill-name>",
  "current_step": 2,
  "steps": {
    "1": {"status": "completed", "output": "...", "completed_at": "ISO"},
    "2": {"status": "in_progress"},
    "3": {"status": "pending"}
  }
}
```

## Directory Structure

```
<skill-name>/
├── SKILL.md                        # 主文件：步骤定义 + 门控规则
└── references/                     # 每步的上下文文档
    ├── step1-<context>.md          # Step 1 需要的参考资料
    ├── step2-<context>.md          # Step 2 需要的参考资料
    └── step3-<context>.md          # Step 3 需要的参考资料
```

## Combining with Other Patterns

<!-- Pipeline 经常与其他模式组合 -->

### Pipeline + Tool Wrapper
每步加载不同的 API reference，适合跨多个 API 的工作流：
```
Step 1: LOAD references/api-market-data.md → 获取价格
Step 2: LOAD references/api-swap.md → 执行交易
Step 3: LOAD references/api-portfolio.md → 验证结果
```

### Pipeline + Reviewer
某个步骤是审查步骤，加载 review-checklist：
```
Step 1: 生成代码
Step 2: LOAD references/review-checklist.md → 审查代码 [Gate: 0 errors]
Step 3: 部署
```

### Pipeline + Inversion
第一步是采访阶段，收集参数后执行后续步骤：
```
Step 1: Inversion phases → 收集需求 [Gate: user confirms]
Step 2: 生成 → 执行
Step 3: 验证
```

## Anti-Patterns

| Pattern | Problem |
|---|---|
| 跳过门控条件 | 后续步骤基于错误的前提执行 |
| 步骤间隐式依赖 | 应该显式声明每步的输入/输出 |
| 所有步骤加载相同 reference | 没必要用 Pipeline，用 Tool Wrapper 即可 |
| 无失败处理 | 步骤失败后状态不一致 |
| 步骤太多（>7） | 考虑合并相关步骤或拆分为子 Pipeline |
| 门控全是 user-confirm | 考虑哪些可以自动化 |


path: assets/skill-templates/reviewer.md
content: ---
name: <skill-name>
description: "<描述：审查/评审特定领域的内容，按检查清单输出分级结果。包含触发关键词。>"
license: Apache-2.0
metadata:
  author: <作者>
  version: "<major.minor.patch>"
  pattern: "reviewer"
  severity-levels: "error,warning,info"
---

# <Skill 名称> (Reviewer)

<!--
Reviewer 模式：分离"检查什么"和"如何检查"。
references/review-checklist.md 存放模块化评分标准。
指令定义检查流程和输出格式。

核心思路：
- "检查什么" 定义在 references/review-checklist.md（可独立维护）
- "如何检查" 定义在 SKILL.md 的 Instructions 中
- 输出按严重程度分组：error → warning → info
-->

一句话概述：审查 <目标类型>，按检查清单输出分级发现。

## Architecture

```
Input (code / doc / strategy / config)
    ↓
Load Checklist (references/review-checklist.md)
    ↓
For each checklist item:
    Check → Classify severity → Record finding
    ↓
Group by severity → Format output
    ↓
Summary + Recommendations
```

## Instructions

### Step 1: Load Review Checklist

```
LOAD references/review-checklist.md
Each checklist item has:
- ID: unique identifier (e.g., SEC-001)
- Category: grouping (e.g., Security, Performance)
- Check: what to verify
- Severity: default level if failed (error | warning | info)
- Fix: recommended remediation
```

### Step 2: Execute Review

```
For each item in checklist:
1. Apply the check to the input
2. Record result: PASS | FAIL
3. If FAIL: use the item's severity level
4. Collect evidence (line numbers, quotes, metrics)
```

### Step 3: Classify Findings

| Severity | Meaning | Action Required |
|---|---|---|
| `error` | 必须修复，阻塞发布/部署 | 立即处理 |
| `warning` | 应该修复，但不阻塞 | 计划处理 |
| `info` | 建议改进，可选 | 酌情处理 |

### Step 4: Output Report

```markdown
## Review Summary

- Errors: N
- Warnings: N
- Info: N
- Pass rate: X%

## Errors (must fix)

### [SEC-001] <检查标题>
- **Finding**: <具体发现>
- **Evidence**: <证据（行号、引用）>
- **Fix**: <修复建议>

## Warnings (should fix)

### [PERF-003] <检查标题>
...

## Info (nice to have)

### [STYLE-002] <检查标题>
...
```

### Severity Override Rules

<!-- 定义何时升级/降级严重程度 -->

```
- If <condition>: upgrade <ID> from warning → error
- If <condition>: downgrade <ID> from error → warning
- Context: <context that affects severity>
```

## Review Checklist Format

<!-- 这是 references/review-checklist.md 的格式规范 -->

```markdown
## <Category>

### <ID>: <Check Title>
- **Check**: <检查内容的具体描述>
- **Severity**: error | warning | info
- **Pass criteria**: <通过条件>
- **Fix**: <修复建议>
```

## Directory Structure

```
<skill-name>/
├── SKILL.md                        # 主文件：检查流程 + 输出格式
└── references/
    ├── review-checklist.md          # 检查清单（模块化，可独立维护）
    ├── <domain-standards>.md        # 领域标准（如安全规范）
    └── <scoring-rubric>.md          # 评分标准（如果需要打分）
```

## Anti-Patterns

| Pattern | Problem |
|---|---|
| 检查逻辑和检查清单混在一起 | 无法独立维护清单 |
| 不分级，所有发现同等对待 | 用户无法区分优先级 |
| 只列问题不给修复建议 | 审查没有可操作性 |
| 缺少证据/行号 | 用户找不到问题位置 |
| 检查清单太大不分类 | 难以导航和维护 |


path: assets/skill-templates/tool-wrapper.md
content: ---
name: <skill-name>
description: "<描述：按需加载特定 API/库的上下文，作为绝对真理指导 agent 操作。包含触发关键词。>"
license: Apache-2.0
metadata:
  author: <作者>
  version: "<major.minor.patch>"
  pattern: "tool-wrapper"
---

# <Skill 名称> (Tool Wrapper)

<!--
Tool Wrapper 模式：按需加载特定库/API 的上下文。
SKILL.md 监听关键词，从 references/ 目录动态加载文档，作为绝对真理应用。

核心思路：
- references/ 目录存放 API 规范、SDK 文档、类型定义
- 指令告诉 agent 何时加载哪个 reference
- 加载后的内容覆盖 agent 的先验知识
-->

一句话概述：封装 <API/库> 的操作接口，提供精确的上下文加载。

## Architecture

```
User Request
    ↓
Keyword Match → 加载 references/<relevant>.md
    ↓
Agent + Loaded Context → 执行操作
    ↓
Structured Output
```

**依赖的外部服务/Skill**:
- <API/库名>: `<调用方式>` -> `<具体命令>`

## Trigger Keywords

<!-- 列出触发此 Skill 的关键词，用于 agent 路由 -->

| Keyword / Pattern | Load Reference | Description |
|---|---|---|
| `<keyword-1>` | `references/<file1>.md` | <何时加载> |
| `<keyword-2>` | `references/<file2>.md` | <何时加载> |
| `<keyword-3>` | `references/<file1>.md, references/<file2>.md` | <组合加载> |

## Instructions

When the user mentions any trigger keyword:

1. **Load Context**: Read the corresponding reference file(s) from `references/` directory
2. **Apply as Ground Truth**: Treat loaded content as the authoritative specification — override any prior knowledge that conflicts
3. **Execute**: Follow the API/library conventions exactly as documented
4. **Validate**: Check output against the reference specification before returning

<!--
关键原则：
- Reference 文件是绝对真理，覆盖 agent 的训练知识
- 只加载需要的 reference，不要一次全加载（节省 context window）
- 如果用户请求与 reference 矛盾，以 reference 为准并告知用户
-->

### Context Loading Rules

```
IF user mentions <keyword-1>:
    LOAD references/<file1>.md
    APPLY as ground truth for <specific domain>

IF user mentions <keyword-2>:
    LOAD references/<file2>.md
    APPLY as ground truth for <specific domain>

IF task requires both:
    LOAD both, <file1>.md takes precedence on conflicts
```

### Core Operations

<!-- 列出此 Skill 封装的核心操作 -->

| Operation | Command / API | Input | Output |
|---|---|---|---|
| `<op-1>` | `<command>` | <输入参数> | <返回格式> |
| `<op-2>` | `<command>` | <输入参数> | <返回格式> |

### Error Handling

```python
# 统一错误格式
failure_info = {
    "reason": str,      # 机器可读
    "detail": str,      # 人类可读上下文
    "retriable": bool,  # 是否可自动重试
    "hint": str         # 提示
}
```

## Directory Structure

```
<skill-name>/
├── SKILL.md                    # 主文件：触发规则 + 指令
└── references/                 # API 规范和文档（绝对真理）
    ├── <api-spec>.md           # API 端点、参数、返回值
    ├── <type-definitions>.md   # 类型定义、枚举值
    └── <error-codes>.md        # 错误码和处理方式
```

## Anti-Patterns

| Pattern | Problem |
|---|---|
| 一次加载所有 references | 浪费 context window，降低精度 |
| 忽略 reference 与先验知识的冲突 | Reference 是真理，必须覆盖 |
| Reference 文件太大（>2000行） | 拆分为更细粒度的文件 |
| 把执行逻辑写在 reference 里 | Reference 只存事实，指令写在 SKILL.md |


path: hooks/task-completed-gate.sh
content: #!/usr/bin/env bash
# TaskCompleted hook — 质量门禁 (multi-strategy)
# Exit 0: 允许完成 | Exit 2: 拒绝，附反馈

set -euo pipefail

TEAMMATE="${CLAUDE_TEAMMATE_NAME:-}"
STRATEGY="${CLAUDE_STRATEGY_NAME:-}"

# 如果未指定策略，尝试从最近修改的 Strategy/*/ 推断
if [[ -z "$STRATEGY" ]]; then
    STRATEGY=$(ls -dt Strategy/*/ 2>/dev/null | head -1 | xargs basename 2>/dev/null || true)
fi

# 仍然为空则放行
if [[ -z "$STRATEGY" ]]; then
    exit 0
fi

if [[ "$TEAMMATE" == "strategy" ]]; then
    V=$(ls -d "Strategy/$STRATEGY/Script/v"*/ 2>/dev/null | sort -V | tail -1)
    [ -z "$V" ] && { echo "FEEDBACK: Strategy/$STRATEGY/Script/ 下无版本目录"; exit 2; }
    for f in config.json risk-profile.json README.md; do
        [ ! -f "$V/$f" ] && { echo "FEEDBACK: 缺少 $V/$f"; exit 2; }
    done
    ls "$V"/strategy.{js,ts,py} &>/dev/null 2>&1 || { echo "FEEDBACK: 缺少策略主文件"; exit 2; }
    for field in max_position_size_pct stop_loss_pct max_drawdown_pct gas_budget_usd slippage_tolerance_pct; do
        grep -q "\"$field\"" "$V/risk-profile.json" || { echo "FEEDBACK: risk-profile.json 缺少字段: $field"; exit 2; }
    done
fi

if [[ "$TEAMMATE" == "backtest" ]]; then
    V=$(ls -d "Strategy/$STRATEGY/Backtest/v"*/ 2>/dev/null | sort -V | tail -1)
    [ -z "$V" ] && { echo "FEEDBACK: Strategy/$STRATEGY/Backtest/ 下无回测输出目录"; exit 2; }
    # 至少有报告文件
    ls "$V"/*.{json,md} &>/dev/null 2>&1 || { echo "FEEDBACK: 回测目录缺少报告文件"; exit 2; }
fi

if [[ "$TEAMMATE" == "publish" ]]; then
    # 检查策略根目录下的 manifest.json
    [ ! -f "$STRATEGY/manifest.json" ] && { echo "FEEDBACK: $STRATEGY/ 缺少 manifest.json"; exit 2; }
fi

exit 0


path: hooks/teammate-idle-reassign.sh
content: #!/usr/bin/env bash
# TeammateIdle hook — 空闲时检查待办 (multi-strategy)
# Exit 0: 允许空闲 | Exit 2: 分配工作

set -euo pipefail

TEAMMATE="${CLAUDE_TEAMMATE_NAME:-}"

case "$TEAMMATE" in
    backtest)
        # 遍历所有策略，检查未回测的版本
        for strat_dir in Strategy/*/; do
            [ ! -d "$strat_dir" ] && continue
            strat=$(basename "$strat_dir")
            for v in "Strategy/$strat/Script/v"*/; do
                [ ! -d "$v" ] && continue
                ver=$(basename "$v")
                [ ! -d "Strategy/$strat/Backtest/$ver" ] && [ -f "$v/risk-profile.json" ] && {
                    echo "FEEDBACK: $strat/$ver 未回测。请验证 $v"; exit 2; }
            done
        done ;;
esac

exit 0


path: references/api-interfaces.md
content: # onchainos CLI 接口参考

策略代码通过 `subprocess` 调用 `onchainos` CLI 与链上交互。**这是唯一的执行方式**，不存在 SDK 或 Python 包。

## 运行时

| 环境 | 路径 | 架构 |
|------|------|------|
| 本地 Mac | `Agentic Wallet/onchainos` | arm64 |
| VPS | `/usr/local/bin/onchainos` | amd64 |

认证通过环境变量：`OKX_API_KEY` / `OKX_SECRET_KEY` / `OKX_PASSPHRASE`（从 1Password 获取）。

## 标准 Wrapper

所有策略必须使用统一的 CLI wrapper 模式（参考 `grid-trading/references/eth_grid_v1.py`）：

```python
import subprocess, json, os

def onchainos_cmd(args: list[str], timeout: int = 30) -> dict | None:
    """Run onchainos CLI command, return parsed JSON."""
    env = os.environ.copy()
    env.setdefault("OKX_API_KEY", os.environ.get("OKX_API_KEY", ""))
    env.setdefault("OKX_SECRET_KEY", os.environ.get("OKX_SECRET_KEY", ""))
    env.setdefault("OKX_PASSPHRASE", os.environ.get("OKX_PASSPHRASE", ""))
    try:
        result = subprocess.run(
            ["onchainos"] + args,
            capture_output=True, text=True, timeout=timeout, env=env,
        )
        output = result.stdout.strip() if result.stdout else ""
        if output:
            try:
                data = json.loads(output)
                if isinstance(data, dict) and "ok" in data:
                    return data
                return {"ok": True, "data": data if isinstance(data, list) else [data]}
            except json.JSONDecodeError:
                pass
        if result.returncode != 0:
            stderr = result.stderr.strip() if result.stderr else ""
            log(f"onchainos rc={result.returncode}: {' '.join(args[:3])} "
                f"{'stderr=' + stderr[:150] if stderr else 'no output'}")
    except subprocess.TimeoutExpired:
        log(f"onchainos timeout: {' '.join(args[:3])}")
    except Exception as e:
        log(f"onchainos error: {e}")
    return None
```

## 命令速查

### Wallet（钱包操作）

```bash
# 登录 & 状态
onchainos wallet login <email> --locale zh-CN
onchainos wallet verify <otp>
onchainos wallet status
onchainos wallet addresses                       # 所有地址，按链分组
onchainos wallet addresses --chain <chainId>     # 指定链

# 余额（⚠️ 返回 UI 单位）
onchainos wallet balance                         # 所有链概览
onchainos wallet balance --chain <chainId>       # 指定链
onchainos wallet balance --chain <chainId> --token-address <addr>  # 指定 token

# 转账（⚠️ amount 用 UI 单位："0.1" = 0.1 ETH）
onchainos wallet send --amount <amt> --receipt <addr> --chain <chainId>
onchainos wallet send --amount <amt> --receipt <addr> --chain <chainId> --contract-token <tokenAddr>  # ERC-20

# 合约调用（TEE 签名）
onchainos wallet contract-call --to <addr> --chain <chainId> --input-data <hex>
onchainos wallet contract-call --to <addr> --chain <chainId> --input-data <hex> --value <amount>  # payable
onchainos wallet contract-call --to <addr> --chain <chainId> --input-data <hex> --mev-protection  # 防 MEV

# 交易历史
onchainos wallet history
onchainos wallet history --tx-hash <hash> --chain <chainId> --address <addr>
```

### Swap（DEX 聚合交易）

```bash
# 询价（⚠️ amount 用最小单位 wei/lamports）
onchainos swap quote --from <tokenAddr> --to <tokenAddr> --amount <minimalUnits> --chain <chainId>

# 授权（EVM 需要，Solana 不需要）
onchainos swap approve --token <tokenAddr> --amount <minimalUnits> --chain <chainId>

# 执行 swap（返回 tx calldata，需要通过 wallet contract-call 签名广播）
onchainos swap swap --from <tokenAddr> --to <tokenAddr> --amount <minimalUnits> --chain <chainId> --wallet <walletAddr>

# 支持的链 & 流动性源
onchainos swap chains
onchainos swap liquidity --chain <chainId>
```

**原生代币地址**:
- EVM: `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee`
- Solana: `11111111111111111111111111111111`

### Market（行情数据）

```bash
# 价格
onchainos market price --address <tokenAddr> --chain <chainId>
onchainos market prices --tokens "<chainId>:<addr>,<chainId>:<addr>"  # 批量

# K线（⚠️ Solana 用 wSOL SPL 地址）
onchainos market kline --address <tokenAddr> --chain <chainId> --bar <1m|5m|15m|1H|4H|1D> --limit <count>

# 指数价格（聚合多源）
onchainos market index --address <tokenAddr> --chain <chainId>
```

### Gateway（交易基础设施）

```bash
# Gas
onchainos gateway gas --chain <chainId>                                    # 当前 gas price
onchainos gateway gas-limit --from <addr> --to <addr> --chain <chainId>    # 估算 gas limit
onchainos gateway gas-limit --from <addr> --to <addr> --data <calldata> --chain <chainId>

# 模拟（不上链，验证交易可行性）
onchainos gateway simulate --from <addr> --to <contract> --data <calldata> --chain <chainId>

# 广播（需要已签名的 tx）
onchainos gateway broadcast --signed-tx <hex> --address <addr> --chain <chainId>

# 订单追踪
onchainos gateway orders --address <addr> --chain <chainId>
onchainos gateway orders --address <addr> --chain <chainId> --order-id <id>
```

### Security（安全扫描）

```bash
# Token 风险检测（蜜罐、rug pull）
onchainos security token-scan --tokens "<chainId>:<addr>,<chainId>:<addr>"

# DApp/URL 钓鱼检测
onchainos security dapp-scan --domain <domain>

# 交易预执行安全检查
onchainos security tx-scan --chain <chainId> --from <addr> --to <contract> --data <calldata>

# 授权查询
onchainos security approvals --address <addr> --chain <chainId>
```

### Token（代币数据）

```bash
# 搜索 & 信息
onchainos token search --query <term> --chains "<chainId1>,<chainId2>"
onchainos token info --address <addr> --chain <chainId>
onchainos token price-info --address <addr> --chain <chainId>      # 价格 + 市值 + 流动性

# 持有者分析
onchainos token holders --address <addr> --chain <chainId>
onchainos token holders --address <addr> --chain <chainId> --tag-filter <whale|kol|smart_money|sniper>

# 流动性池
onchainos token liquidity --address <addr> --chain <chainId>

# 高级风险信息（创建者、持仓集中度）
onchainos token advanced-info --address <addr> --chain <chainId>
```

### Portfolio（公开地址查询）

```bash
onchainos portfolio total-value --address <addr> --chains "<chainId1>,<chainId2>"
onchainos portfolio all-balances --address <addr> --chains "<chainIds>"
onchainos portfolio token-balances --address <addr> --tokens "<chainId>:<addr>,<chainId>:<addr>"  # 最多 20 个
```

## ⚠️ 关键陷阱

| 陷阱 | 说明 | 正确做法 |
|------|------|----------|
| **单位混用** | `wallet send` 用 UI 单位，`swap` 用最小单位 (wei) | 每个命令查本表确认单位 |
| **EVM approve** | EVM swap 前必须 approve，Solana 不需要 | 根据链判断是否 approve |
| **合约地址大小写** | onchainos 要求小写 | `.lower()` 处理 |
| **K线 Solana** | `market kline` 用 wSOL SPL 地址，不是原生地址 | 区分原生 vs SPL 地址 |
| **Gas 估算不可靠** | DEX API 返回的 gas 值不准 | 让 onchainos 内部估算，不要手动传 gas |
| **签名方式** | 用 `wallet contract-call` 签名，不是 gateway broadcast | 策略代码不直接签名 |

## 策略代码的标准执行流程

以 swap 为例（参考 grid-trading 实盘代码）：

```
1. onchainos swap quote      → 获取报价 + priceImpact
2. 检查 priceImpact < tolerance  → 超出则放弃
3. onchainos swap approve    → EVM 授权（Solana 跳过）
4. onchainos swap swap       → 获取 tx calldata
5. onchainos gateway simulate → 预检交易（大额操作建议做）
6. onchainos wallet contract-call → TEE 签名 + 广播
7. 验证返回 txHash           → 记录到 state.json
```

**完整示例见 `grid-trading/references/eth_grid_v1.py`** — 这是经过实盘验证的代码，新策略应复用其 wrapper 和执行模式。


path: references/risk-schema.json
content: {
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Risk Profile",
  "description": "策略风控硬约束。所有字段必填。Backtest Agent 逐项校验。",
  "type": "object",
  "required": [
    "max_position_size_pct", "stop_loss_pct", "take_profit_pct",
    "max_drawdown_pct", "max_daily_loss_pct", "gas_budget_usd",
    "slippage_tolerance_pct", "max_concurrent_positions", "market_conditions"
  ],
  "properties": {
    "max_position_size_pct": { "type": "number", "description": "单笔最大仓位占比 %", "minimum": 0.1, "maximum": 100 },
    "stop_loss_pct": { "type": "number", "description": "止损触发 %", "minimum": 0.1 },
    "take_profit_pct": { "type": "number", "description": "止盈触发 %", "minimum": 0.1 },
    "max_drawdown_pct": { "type": "number", "description": "最大回撤 %", "minimum": 1 },
    "max_daily_loss_pct": { "type": "number", "description": "单日最大亏损 %", "minimum": 0.5 },
    "gas_budget_usd": { "type": "number", "description": "每日 Gas 预算 USD", "minimum": 1 },
    "slippage_tolerance_pct": { "type": "number", "description": "滑点容忍度 %", "minimum": 0.01 },
    "max_concurrent_positions": { "type": "integer", "description": "最大同时持仓数", "minimum": 1 },
    "market_conditions": {
      "type": "object",
      "required": ["applicable", "not_applicable"],
      "properties": {
        "applicable": { "type": "array", "items": { "type": "string" } },
        "not_applicable": { "type": "array", "items": { "type": "string" } }
      }
    }
  }
}


path: references/strategy-lessons.md
content: # 策略经验库

从已有策略的开发、回测、实盘中提炼的可复用经验。新策略开发时 **必须** 先读本文件。

---

## 一、通用风控模式

所有策略已验证有效的风控层级（按优先级从高到低）：

| 层级 | 机制 | 推荐值 | 来源 |
|------|------|--------|------|
| 1 | 全局 Stop 开关 | — | grid-trading, cl-lp |
| 2 | 熔断器（连续错误→冷却） | 5 错误 → 1h 冷却 | grid-trading, cl-lp |
| 3 | 数据验证（价格/余额/API 返回） | 每次操作前 | 通用 |
| 4 | 止损 / 追踪止损 | 15% / 10% | grid-trading, cl-lp |
| 5 | 仓位限制 | 按策略类型定义上限 | grid-trading |
| 6 | 最小操作间隔 | 30min (交易) / 2h (调仓) | grid-trading, cl-lp |
| 7 | 重复操作保护 | 同向最多 3 次后暂停 | grid-trading |
| 8 | Gas 成本检查 | Gas < 预期收益的 50% | cl-lp |
| 9 | 最小变化阈值 | > 3% (网格) / > 5% (范围) | grid-trading, cl-lp |

**原则**: 新策略不必照搬全部层级，但至少包含 1-4 层（Stop、熔断、数据验证、止损）。5-9 层根据策略类型选取。

---

## 二、多时间框架趋势分析 (MTF)

Grid Trading 首创，CL LP Rebalancer 已成功复用。**推荐所有需要趋势判断的策略复用此模块。**

```
短期 EMA: 5 bars (25min @ 5min K线)  → 快速信号
中期 EMA: 12 bars (1h)               → 方向确认
长期 EMA: 48 bars (4h)               → 趋势过滤
8h 结构检测: 上升/下降/震荡           → 宏观背景
```

**输出**:
- `trend_direction`: bullish / bearish / neutral
- `trend_strength`: 0-1（> 0.3 时激活非对称逻辑）

**复用方式**: 独立函数，输入 K 线数组，输出趋势方向 + 强度。不依赖具体策略逻辑。

---

## 三、波动率自适应

两个策略都使用 K线 ATR + 价格标准差融合的波动率估计，效果优于单一指标。

**ATR 计算**: 24 根 1H K 线 → 24h 波动率窗口

**波动率分级**（CL LP 已验证）:

| 级别 | ATR 范围 | 策略行为 |
|------|----------|----------|
| Low | < 1.5% | 收紧参数，追求资本效率 |
| Medium | 1.5-3% | 平衡配置 |
| High | 3-5% | 放宽参数，减少操作频率 |
| Extreme | > 5% | 防御模式，安全优先 |

**教训**: Grid Trading 的波动率乘数 (VOLATILITY_MULTIPLIER) 在不同趋势下需要差异化——看涨时放宽 (3.0x)，看跌时收紧 (1.0x)。

---

## 四、非对称设计

两个策略都证明了**趋势方向应驱动买卖不对称**：

- **Grid Trading**: 看涨时买网格密、卖网格疏（快买慢卖）；看跌反之
- **CL LP**: 看涨时上方范围宽、下方窄；看跌反之

**激活条件**: `trend_strength > 0.3` 时启用，否则保持对称。

**非对称系数**: Grid 用 0.4，CL LP 用 0.3。新策略建议从 0.3 起步，根据回测调整。

---

## 五、成本管理经验

### Slippage（最大痛点）

Grid Trading 回测暴露了 **6.24% 的 slippage**，直接抵消了交易利润。

**教训**:
- 单笔交易金额越大，slippage 越高 → 控制单笔大小
- DEX swap 天然存在 slippage，无法消除只能管理
- `slippage_tolerance_pct` 设为 1-1.5%，超出时放弃交易

### Gas

CL LP 在 Base 链上 Gas 极低（$0.048/天），但其他链差异巨大。

**教训**:
- 始终检查 `gas_cost < expected_profit * gas_to_fee_ratio`
- Base/Arbitrum/Polygon 的 Gas 成本可忽略，Ethereum L1 需要特别注意
- 调仓/交易前先估算 Gas，不满足则跳过

---

## 六、状态管理模式

两个策略都使用 JSON 文件管理状态，已验证可靠：

```python
state = {
    "positions": [],           # 当前持仓
    "price_history": [],       # 288 根 5min K线 = 24h
    "error_count": 0,          # 熔断计数
    "last_action_time": "",    # 操作间隔控制
    "equity_curve": [],        # 资金曲线
    "trade_log": []            # 交易记录（配对分析用）
}
```

**教训**:
- 状态文件必须原子写入（先写 tmp 再 rename），防止中断导致损坏
- 价格历史保留 24h 足够（288 根 5min），更长周期用 API 按需拉取
- 交易记录要保留完整的 round trip（买卖配对），便于 Iteration Agent 分析

---

## 七、回测指标基线

| 指标 | Grid Trading v4 | CL LP v1 | 建议门槛 |
|------|-----------------|----------|----------|
| Sharpe Ratio | — | 29.67 | > 1.0 |
| Max Drawdown | — | 2.72% | < 声明值 |
| Win Rate | — | 85.7% | > 40% |
| Profit Factor | — | 7.5 | > 1.5 |
| Gas/Revenue | 高 | 0.22% | < 50% |
| Slippage 实际 | 6.24% | 0.35% | < 声明值 |
| 在范围时间 (LP) | N/A | 99.3% | > 90% |

**注意**: CL LP 的指标异常优秀，部分因为回测期间市场条件理想（中等波动 + 温和趋势）。新策略不应以此为基准，而应以 Gate 最低要求（Sharpe>1.0, WR>40%）为目标。

---

## 八、适用市场条件

两个策略的共同发现：

| 市场状态 | 表现 | 应对 |
|----------|------|------|
| 震荡 / 低波动 | ✅ 最佳 | 正常运行 |
| 中等波动 + 温和趋势 | ✅ 良好 | 非对称模式激活 |
| 高波动 | ⚠️ 可接受 | 放宽参数，降低频率 |
| 极端波动 / 闪崩 | ❌ 风险高 | 建议暂停或进入防御模式 |
| 持续单边行情 | ❌ 不适合 | 网格策略天然逆势，LP 面临 IL |

**建议**: 新策略的 `risk-profile.json` 中 `market_conditions.not_applicable` 必须明确列出不适用场景。

---

## 九、执行架构模式

### onchainos CLI — 运行时依赖

所有策略的链上操作通过 `onchainos` 二进制执行。本地 `Agentic Wallet/onchainos` (arm64)，VPS `/usr/local/bin/onchainos` (amd64)。onchainos 更新频繁，独立测试。

onchainos 的能力已作为 Claude Code Skill 安装（`okx-dex-swap`、`okx-agentic-wallet` 等），策略开发时按 skill 名称调用，接口细节以 skill 文档为准。

**与 onchainos 协作的经验教训**:
- `wallet send` 用 UI 单位（"0.1" ETH），`swap` 系列用最小单位（wei）—— 混用必出错
- EVM swap 需要先 `approve` 再 `swap`，Solana 不需要
- `gateway simulate` 可在不上链的情况下预检交易，建议大额操作前必做
- `security token-scan` 可检测蜜罐，新策略接入未知 Token 前应先扫描
- onchainos 更新后，策略的 CLI 调用方式可能变化，部署前需验证兼容性

### 通用执行架构

```
Cron (5min) → Python 脚本 → onchainos CLI → OKX Web3 API → Chain
                  ↓                              ↓
            state.json (本地)              Wallet (TEE signing)
                  ↓
          Discord 通知 (via OpenClaw)
```

**标准 CLI 入口**（所有策略应统一）：

```bash
python3 {strategy}.py tick      # 主循环（cron 调度）
python3 {strategy}.py status    # 当前状态
python3 {strategy}.py report    # 日报
python3 {strategy}.py close     # 完全退出（仅部分策略需要）
```

---

## 十、常见陷阱

| 陷阱 | 策略 | 后果 | 预防 |
|------|------|------|------|
| 硬编码 Token 地址 | 通用 | 换链时全部失效 | config.json 外置 |
| 不校验 API 返回 | 通用 | 空数据导致异常交易 | 数据验证层 |
| 止损和追踪止损冲突 | Grid | 两者同时触发导致重复平仓 | 互斥检查 |
| 调仓过于频繁 | CL LP | Gas + slippage 吃掉收益 | anti-churn 保护 |
| 价格历史不足就计算 ATR | 通用 | 波动率估计偏差大 | 最少 24 根 K 线才启用 |
| 忽略 decimal 差异 | 通用 | ETH(18) vs USDC(6) 计算错误 | 统一转换层 |
| 混用 UI 和最小单位 | 通用 | onchainos 不同命令单位不同，混用导致金额错误 | 查阅 cli-reference 确认每个命令的单位 |
| 回测用理想 slippage | Grid | 实盘 slippage 远高于预期 | 回测加入随机 slippage 模型 |
| onchainos 版本不兼容 | 通用 | 更新后 CLI 参数变化导致策略报错 | 部署前验证 onchainos 版本兼容性 |

---

## 更新记录

- 2026-03-20: 初始版本，从 grid-trading v4 和 cl-lp-rebalancer v1 提取


path: roles/backtest.md
content: # Backtest Agent

验证策略版本。不写策略。

## 参数

从 Lead 接收 `{strategy}` — 策略名称，决定所有输入/输出路径。

## 输入

`Strategy/{strategy}/Script/v{version}/` 下的完整策略文件

## 产出

写入 `Strategy/{strategy}/Backtest/v{version}/`（可复用已有的回测框架 `Strategy/{strategy}/Backtest/backtest_engine.py`）：

1. **backtest-report.json**:
```json
{
  "version": "", "strategy_name": "{strategy}",
  "test_period": { "start": "", "end": "" },
  "metrics": {
    "sharpe_ratio": 0, "max_drawdown_pct": 0, "win_rate_pct": 0,
    "profit_factor": 0, "total_return_pct": 0, "total_trades": 0,
    "max_consecutive_losses": 0, "gas_cost_total_usd": 0, "slippage_impact_pct": 0
  },
  "compliance": {
    "max_drawdown": { "declared": 0, "actual": 0, "pass": true },
    "stop_loss": { "triggered_correctly": true, "pass": true },
    "gas_budget": { "declared_daily": 0, "actual_daily_avg": 0, "pass": true },
    "slippage": { "declared": 0, "actual_avg": 0, "pass": true },
    "position_size": { "declared_max_pct": 0, "actual_max_pct": 0, "pass": true }
  },
  "verdict": "PASS | FAIL | CONDITIONAL",
  "failures": []
}
```

2. **backtest-summary.md** — 人类可读报告
3. **equity-curve.csv** — `timestamp,equity,drawdown_pct,position_count`

## Verdict 规则

- Compliance 全 PASS + Sharpe > 1.0 + Win Rate > 40% → **PASS**
- 任一 Compliance FAIL → **FAIL**（列出每项失败的 declared vs actual）
- Compliance PASS 但指标 borderline → **CONDITIONAL**（说明哪项差多少）

向 Lead 报告 verdict + 完整 metrics。


path: roles/infra.md
content: # Infra Agent — 本地验证 + 生产部署

部署通过回测的策略。流程: **本地验证 → 生产部署**。不写策略、不做回测。

这是**开发者自用的部署流程**。消费者部署（OpenClaw/Docker）在产品 Skill 里定义。

## 参数

从 Lead 接收 `{strategy}` — 策略名称，决定所有源路径和 VPS 目标路径。

## 环境配置

策略脚本通过 `env_config.py` 加载环境配置，由 `ENV` 环境变量切换:

| 环境 | 配置文件 | onchainos | dry_run | 凭证 |
|------|---------|-----------|---------|------|
| `local` | `env.local.json` | `./Agentic Wallet/onchainos` (arm64) | `true` | 1Password |
| `production` | `env.production.json` | `/usr/local/bin/onchainos` (amd64) | `false` | 环境变量 |

## 部署脚本

所有操作通过 `deploy.sh` 统一执行:

```bash
./deploy.sh {strategy} validate     # Step 1: 本地验证（3 tick dry-run）
./deploy.sh {strategy} local        # 本地运行（持续 dry-run）
./deploy.sh {strategy} production   # Step 2: 部署到 VPS
./deploy.sh {strategy} status       # 查看 VPS 状态
./deploy.sh {strategy} stop         # 停止 VPS 进程
```

## 流程

### Step 1: 本地验证（Gate）

**必须在部署 VPS 前通过。**

```bash
./deploy.sh {strategy} validate
```

验证内容:
- 策略脚本在本地 onchainos（arm64）环境下启动无报错
- RPC 连接正常，能获取价格和余额
- 钱包适配器响应正常
- 连续 3 个 tick dry-run 无异常

**Gate**: 3 tick 全部成功 → PASS，任一失败 → FAIL，退回 Strategy 修复。

### Step 2: 生产部署

```bash
./deploy.sh {strategy} production
```

自动完成:

1. **凭证获取** — 通过 1Password 获取 SSH 密钥（临时文件，用完删除）
2. **Pre-deploy Check** — SSH 连通、磁盘 > 1GB、onchainos 可用、备份当前版本
3. **上传 + 切换** — scp 上传 staging → pm2 stop → mv current → pm2 start
4. **健康检查（10s）** — pm2 status online + 无错误日志
5. **回滚** — 健康检查失败自动回滚到上一版本

### Step 3: 收尾

- 清理旧备份（保留最近 3 个）
- 向 Lead 报告结果 + 更新 state.json

## 回滚

部署脚本自动处理回滚。手动回滚:

```bash
./deploy.sh {strategy} stop
# SSH 到 VPS 手动恢复 backup
```

报告失败给 Lead。**不自动重试**。

## 部署窗口

优先 UTC 0:00–4:00。紧急修复需用户确认。

## 安全

- SSH 密钥: 1Password 临时取出 → mktemp → trap 清理。不存入环境变量/文件/日志
- OKX 凭证: 本地通过 `op` 获取，VPS 通过环境变量（pm2 ecosystem 管理）


path: roles/iteration.md
content: # Iteration Agent

复盘线上策略表现，提取因果关系，输出优化方案。不直接改代码。

## 参数

从 Lead 接收 `{strategy}` — 策略名称，决定所有输入/输出路径。

## 产出

写入 `Strategy/{strategy}/Iteration/v{ver}-review-{YYYY-MM-DD}.md`

## 分析框架（全部必填）

### 1. Performance Summary
期间收益 vs 预期区间。实际风控指标 vs 声明阈值。

### 2. Correct Decisions
盈利交易 + 市场背景。成功共性模式。可复用信号特征。

### 3. Wrong Decisions
亏损交易 + 市场背景。分类：信号误判 / 参数不当 / 市场突变 / 执行问题。标注可避免 vs 系统性风险。

### 4. Causal Extraction
```
[HIGH] IF {条件} THEN {结果} (N/M 次观察)
[LOW]  IF {条件} THEN {结果} (数据不足)
```
强因果：5+ 次观察。弱因果：< 5 次。

### 5. Optimization Proposal
具体的 config.json 修改（字段、当前值 → 建议值、理由）。风控阈值调整。逻辑变更及预期效果。

### 6. Risk Flag
- 风控阈值触发 > 3 次 → **优先迭代项**
- 市场偏离适用条件 → **建议暂停**
- 连续亏损 > 回测最大值 → **升级给用户**

## 经验回写

每次复盘完成后，检查是否有**跨策略可复用**的新发现（风控模式、成本教训、市场条件洞察、新陷阱）。如有，追加到 `references/strategy-lessons.md` 对应章节，并更新底部的更新记录。

**回写标准**: 仅记录经过实盘验证的经验，不记录假设或未验证的推测。

## 规则

1. 产出是**提案** — 绝不自动执行
2. 新版本必须重新回测
3. 所有迭代记录永久保留
4. 连续 2 次未改善 → 建议暂停或重新设计

## 数据来源

参考 `grid-trading/SKILL.md` 的 AI Review & Optimization 部分：
- 从 `Strategy/{strategy}/state.json` 读取交易记录
- 配对 round trips（BUY-SELL 匹配）
- 分析 win rate、avg spread、loss/micro/good 分类
- 检查 MTF 数据在亏损时的趋势对齐


path: roles/lead.md
content: # Lead — 协调者

你是 Agent Team 的 Lead。**你绝不写代码**。你只做：协调、分发、质量门禁、状态管理。

## 参数

启动时接收 `{strategy}` 参数，标识当前操作的策略名称。所有 teammate spawn 时必须传递此参数。

## 第一跳：需求提炼（Lead → Strategy）

Spawn Strategy Agent **之前**，Lead 必须完成以下流程：

1. **提炼** — 从主窗口讨论中提取最终决策，丢弃犹豫、被否决方案、闲聊
2. **填模板** — 读取 `templates/requirements.md`，填写所有字段，写入 `Strategy/{strategy}/requirements.md`
3. **确认** — 将填好的需求展示给用户，等待确认。用户可修正后再继续
4. **Spawn** — 确认后 spawn Strategy Agent，prompt 中指向需求文件而非内联上下文

**原则**: 需求文件只记录"做什么"，不记录"讨论过什么"。字段留空比填垃圾信息好。

## Spawn Teammates

| Teammate | 时机 | Spawn Prompt |
|----------|------|-------------|
| strategy | 新建/修订策略 | `Read roles/strategy.md and references/strategy-lessons.md. Strategy: {strategy}. Requirements: Strategy/{strategy}/requirements.md` |
| backtest | Strategy 产出完整 | `Read roles/backtest.md. Strategy: {strategy}. Validate Strategy/{strategy}/Script/v{ver}/` |
| infra | Backtest PASS | `Read roles/infra.md. Strategy: {strategy}. Deploy v{ver}.` |
| publish | Backtest PASS（可并行） | `Read roles/publish.md. Strategy: {strategy}. Package v{ver} as Skill.` |
| iteration | LIVE + 复盘请求 | `Read roles/iteration.md. Strategy: {strategy}. Review v{ver} for {period}.` |

## 质量门禁

**Strategy → Backtest 前**，验证 `Strategy/{strategy}/Script/v{version}/` 包含：
- `strategy.js` 或 `.ts`（无硬编码参数）
- `config.json`（参数外置）
- `risk-profile.json`（字段完整，校验 `references/risk-schema.json`）
- `README.md`（含收益预期 + 适用市场条件）

**缺任何文件 = reject**，附具体缺失项退回 strategy teammate。

**Backtest → Deploy 前**：
- Compliance 全 PASS + Sharpe > 1.0 + Win Rate > 40% → 自动通过
- Compliance PASS 但指标 borderline → CONDITIONAL，问用户
- 任一 Compliance FAIL → reject 附失败详情

## 版本管理

SemVer: `MAJOR.MINOR.PATCH`。每版本独立目录。已发布版本不可修改。

## 状态追踪

文件 `Strategy/{strategy}/state.json`：
```json
{ "strategy_name": "{strategy}", "state": "DRAFT", "version": "1.0.0", "live_version": "", "log": [] }
```

每次转换记录：`[STATE] {strategy} v{ver}: {OLD} → {NEW} | {reason}`

## 规则

1. 同时只有一个版本处于 DEPLOYING
2. Publish 在 Backtest 通过后开始抽象，GitHub release 等 Deploy 成功
3. **Iteration 新版本必须重新回测 — 无例外**
4. 任何 Agent 报错 → 暂停流水线 + 通知用户
5. 连续 2 次迭代未改善 → 建议暂停策略或重新设计


path: roles/publish.md
content: # Publish Agent

把策略抽象为独立的、跨平台可复用的产品 Skill。不写策略。

## 参数

从 Lead 接收 `{strategy}` — 策略名称，决定所有输入/输出路径。

## 职责

从 `Strategy/{strategy}/Script/v{version}/` 读取策略，用 `assets/product-skill-template/` 模板生成独立 Skill 包，输出到 `{strategy}/`。

## Skill 设计模式选择

生成 SKILL.md 前，先根据策略特征选择合适的设计模式。模式模板在 `assets/skill-templates/` 下：

| 模式 | 模板文件 | 适用场景 |
|------|----------|----------|
| pipeline | `pipeline.md` | 严格顺序多步工作流（如网格交易：取价→分析→决策→执行→通知） |
| tool-wrapper | `tool-wrapper.md` | 按需加载 API/CLI 上下文（如封装 onchainos CLI 操作） |
| generator | `generator.md` | 生成一致结构的输出（如报告、配置文件） |
| reviewer | `reviewer.md` | 审查/评估（如策略回测结果审查） |
| inversion | `inversion.md` | 先采访用户收集需求再行动 |

**选择流程**：

1. 读取策略代码，理解其执行模式
2. 从 `assets/skill-templates/` 加载匹配的模式模板
3. 用 `assets/skill-templates/SKILL_TEMPLATE.md` 作为 SKILL.md 的基础骨架
4. 按所选模式的结构组织 SKILL.md 的 Instructions 章节
5. 复合模式用逗号分隔写入 `metadata.pattern`（如 `"pipeline, tool-wrapper"`）

大多数交易策略是 **pipeline + tool-wrapper** 的组合：流水线定义执行步骤，tool-wrapper 加载每步需要的 API 参考文档。

## 发布验证

生成完成后，用 `assets/publish.sh` 验证 Skill 格式：

```bash
bash okx-strategy-factory/assets/publish.sh {strategy} --dry-run
```

验证通过后再执行 git commit。`publish.sh` 检查 YAML frontmatter、必需章节、模式特有字段等。

## 产出结构

```
{strategy}/
├── SKILL.md              ← 主文件（从 product-skill-template/SKILL.md.tmpl 生成）
├── references/
│   └── api-interfaces.md ← 从工厂 references/ 复制
├── deploy/
│   ├── openclaw.md       ← 消费者: Discord/Telegram 命令部署
│   └── docker.md         ← 消费者: Docker Compose 部署
├── manifest.json         ← SSOT（从 product-skill-template/manifest.json.tmpl 生成）
├── install.sh            ← 一键安装（从 product-skill-template/install.sh.tmpl 生成）
└── README.md
```

注意：策略代码本身（strategy.js, config.json, risk-profile.json）已在 `Strategy/{strategy}/Script/v{version}/`，产品 Skill 的 SKILL.md 引用它们而非复制。发布到 GitHub 时打包在一起。

## manifest.json（SSOT）

所有 adapter/install 文件从 manifest 派生。**不允许独立修改适配文件。**

```json
{
  "name": "{strategy}", "version": "", "description": "",
  "platforms": ["claude-code", "codex", "openclaw"],
  "dependencies": { "npm": [], "pip": [] },
  "entry_point": "strategy.js",
  "tags": ["defi", "dex", "onchain", "okx"]
}
```

## install.sh

- 幂等：重复执行不破坏已有配置
- 自动检测平台（Claude Code / Codex / OpenClaw）
- 安装 manifest.json 中声明的依赖
- 打印验证信息

## 两阶段发布

1. **Skill 抽象**（Backtest PASS 后开始，可与 Infra 并行）
2. **GitHub Release**（等 Infra Deploy 成功后执行）：
```bash
git tag -a "v{ver}" -m "{strategy} v{ver}"
git push origin main --tags
gh release create "v{ver}" --title "{strategy} v{ver}" --notes-file CHANGELOG_ENTRY.md
```

## 迭代更新

新版本时：更新 manifest.json 版本 → 重新生成所有适配文件 → 新 GitHub release。


path: roles/strategy.md
content: # Strategy Agent

编写基于 **onchainos CLI** 的 OKX OnchainOS 链上交易策略。只写策略逻辑，不做回测/部署/发布。

## 核心约束

所有链上操作（查价、swap、转账、签名）**必须通过 `onchainos` CLI 执行**。不存在 Python SDK，不直接调用 OKX API。策略代码本质是：Python 逻辑 + `subprocess.run(["onchainos", ...])` 调用。

## 启动前必读

1. **`references/api-interfaces.md`**（onchainos CLI 命令速查 + 标准 wrapper + 关键陷阱）— 这是你写代码的接口参考
2. **`references/strategy-lessons.md`**（策略经验库）— 风控模式、MTF、波动率、成本管理、常见陷阱
3. **`grid-trading/references/eth_grid_v1.py`**（实盘参考）— 经过验证的 onchainos 调用模式，复用其 wrapper

## 输入

从 Lead 接收 `{strategy}` — 策略名称，决定所有输出路径。

**启动后第一步**: 读取 `Strategy/{strategy}/requirements.md`（Lead 提炼的结构化需求）。这是你的唯一需求来源，不要猜测或补充需求文件中未提及的业务逻辑。字段标注"待回测确认"的参数，填合理默认值并在 config.json 中注释。

## 产出

写入 `Strategy/{strategy}/Script/v{version}/`，**全部必需**：

1. **strategy.js / .ts** — 核心逻辑，只调用 adapter 接口（见 `references/api-interfaces.md`），不硬编码参数
2. **config.json** — 所有可调参数外置
3. **risk-profile.json** — 风控硬约束（schema 见 `references/risk-schema.json`）：
```json
{
  "max_position_size_pct": 10, "stop_loss_pct": 5, "take_profit_pct": 15,
  "max_drawdown_pct": 20, "max_daily_loss_pct": 8, "gas_budget_usd": 50,
  "slippage_tolerance_pct": 1.5, "max_concurrent_positions": 3,
  "market_conditions": { "applicable": [], "not_applicable": [] }
}
```
4. **README.md** — 逻辑概述、信号描述、收益预期（乐观/中性/悲观）、适用市场条件、参数说明

## onchainos CLI 调用

策略代码通过 `subprocess` 调用 onchainos CLI。完整命令表见 `references/api-interfaces.md`，核心操作：

```bash
onchainos wallet balance --chain <chainId>                    # 查余额（UI 单位）
onchainos swap quote --from <addr> --to <addr> --amount <wei> # 询价（最小单位!）
onchainos swap approve --token <addr> --amount <wei> --chain <chainId>  # EVM 授权
onchainos swap swap --from <addr> --to <addr> --amount <wei> --chain <chainId> --wallet <addr>
onchainos wallet contract-call --to <addr> --chain <chainId> --input-data <hex>  # TEE 签名+广播
onchainos market kline --address <addr> --chain <chainId> --bar <1H> --limit 24  # K线
onchainos gateway simulate --from <addr> --to <addr> --data <hex> --chain <chainId>  # 预检
```

**必须复用** `grid-trading/references/eth_grid_v1.py` 中的 `onchainos_cmd()` wrapper，不要重新发明。

**⚠️ 单位陷阱**: `wallet send/balance` 用 UI 单位（"0.1" ETH），`swap` 系列用最小单位（wei）。混用必出错。

## 修订请求

Lead 退回时：只修改指出的问题，不重写无关逻辑。更新 CHANGELOG.md。


path: templates/requirements.md
content: # {strategy} — 策略需求

> Lead 填写，用户确认后交给 Strategy Agent。只保留最终决策，不要讨论过程。

## 核心定义

- **策略类型**: (网格 / 动量 / 均值回归 / LP / 套利 / 其他)
- **交易对**: (例: ETH/USDC)
- **链**: (例: Base)
- **方向**: (多 / 空 / 双向)

## 信号逻辑

- **入场信号**: (具体指标 + 参数，例: EMA(12) 上穿 EMA(26))
- **出场信号**: (止盈条件 / 信号反转 / 时间退出)
- **过滤条件**: (趋势过滤 / 波动率过滤 / 时间窗口，没有写"无")

## 参数 (将进入 config.json)

| 参数 | 值 | 说明 |
|------|-----|------|
| | | |

> 不确定的参数写合理默认值 + "待回测确认"

## 风控 (将进入 risk-profile.json)

- **单笔仓位上限**: (占本金 %)
- **止损**: (%)
- **止盈**: (%)
- **最大回撤**: (%)
- **日亏损熔断**: (%)
- **最大并发仓位**: (个)
- **Gas 预算**: (USD/天)
- **Slippage 容忍**: (%)

> 未指定的项由 Strategy Agent 按 strategy-lessons.md 经验填写合理默认值

## 市场假设

- **适用场景**: (例: 震荡市、中等波动)
- **不适用场景**: (例: 持续单边、极端波动)
- **收益预期**: 乐观 __ / 中性 __ / 悲观 __ (月化 %)

## 特殊要求

(复用 MTF 模块？非对称设计？特定时间框架？其他约束？没有写"无")


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)