# @cutie-crypto/connector

Bridge between your local OpenClaw / Hermes agent and the Cutie platform.

[Cutie 平台](https://cutie.tokenbeep.com) 是 KOL AI 分身的通道层。本 Connector
解决"KOL 的 AI 不能暴露公网 API，但 Cutie 平台需要调用它"的问题：connector 在
KOL 本机常驻，主动出站连接 Cutie Server，下发任务后转给本地 AI gateway 处理。

## Install

```bash
npm install -g @cutie-crypto/connector
```

connector-core 是依赖项，npm 会自动拉取，无需手动安装。

## Quick start

```bash
# 1. 在 Cutie App 拿到 pair_token
# 2. 一键 setup（自动检测 OpenClaw / Hermes）
cutie-connector setup --pair-token ptk_xxx

# 3. 启动
cutie-connector start
```

## Supported platforms

| 平台 | 配置文件 | gateway 默认端口 | 默认模型 | gateway secret 来源 |
|------|---------|----------------|---------|---------------------|
| **OpenClaw** | `~/.openclaw/openclaw.json` | 18789 | `openclaw:cutie` | `gateway.auth.token` |
| **Hermes** (Nous Research) | `~/.hermes/config.yaml` + `~/.hermes/.env` | 8642 | `hermes-agent` | `~/.hermes/.env` `API_SERVER_KEY` |

OpenClaw 的 `agent_model` 决定路由到哪个 agent（`openclaw:cutie` / `openclaw:main`）。
Hermes 没有"多 agent 路由"概念——profile 自身就是 agent，model 字段填 profile 名。

## Commands

| Command | Description |
|---------|-------------|
| `setup --pair-token ptk_xxx` | 一键配置（注册 + 写 workspace + 启 gateway + 装 service） |
| `setup --pair-token ptk_xxx --platform hermes\|openclaw` | 显式指定平台 |
| `start` | 启动连接器（首次需要 `--pair-token`） |
| `start --platform hermes` | 显式指定平台（默认自动检测） |
| `status` | 显示当前连接器状态（platform / gateway / agent_model） |
| `backtest-provider --kind none\|smoke\|external_http` | 配置是否声明回测执行能力 |
| `sync` | 手动触发人格同步（OpenClaw 主 agent → cutie agent workspace） |
| `reset` | 删除配置，重新配对 |

环境变量替代 `--platform`：`CUTIE_AGENT_PLATFORM=hermes cutie-connector start`

## Configuration

- 配置文件：`~/.cutie-connector/config.json`（mode 0600，自动迁移旧字段
  `openclaw_url` / `openclaw_secret` 到 `gateway_url` / `gateway_secret`）
- 日志：stdout / stderr 由 supervisor（systemd / launchd）收集

### Backtest provider

Connector 默认不声明 `backtest_run` 能力，也不会替用户生成回测结果。只有
`~/.cutie-connector/config.json` 里配置了 `backtest_provider` 且当前版本有对应
runner 时，心跳才会上报回测能力。

Pre / CI smoke 可用：

```bash
cutie-connector backtest-provider --kind smoke \
  --provider-name connector_smoke \
  --engine-name connector-smoke-backtest \
  --engine-version 0.2.0 \
  --data-source smoke
```

这只会生成零收益的 smoke 结果，`data_source=smoke`，用于链路验证。真实的 A/B
回测供应商走 `external_http` provider：

```bash
cutie-connector backtest-provider --kind external_http \
  --endpoint https://provider.example.com/cutie/backtest \
  --api-key prv_xxx \
  --provider-name "Provider A" \
  --engine-name "Provider A Backtest" \
  --engine-version "2026-05" \
  --data-source "provider_a" \
  --timeout-ms 30000
```

Connector 会把 Cutie 下发的回测 envelope POST 到 provider endpoint：

```json
{
  "schema": "cutie.external_backtest.request.v1",
  "backtest": { "...": "server envelope" },
  "provider": {
    "provider_name": "Provider A",
    "engine_name": "Provider A Backtest",
    "engine_version": "2026-05",
    "data_source": "provider_a"
  }
}
```

请求头使用 `Authorization: Bearer <api-key>`。provider 响应必须至少包含
`metrics`、`equity_curve`、`trades`，可选覆盖 `provider_name`、`engine_name`、
`engine_version`、`data_source`、`provider_run_id`、`result_hash`、`report_url`、
`assumptions`、`limitations`、`raw_report`。Connector 会把结果归一化后提交到
Cutie `/external-result`，但 Cutie 只标记为 `external_unverified`。

provider 已正常执行但业务失败时，返回 2xx + failed payload：

```json
{
  "result_status": "failed",
  "provider_run_id": "bt_123",
  "error_type": "no_trades",
  "error_message": "No entries matched the strategy conditions",
  "assumptions": { "fee_bps": 10 },
  "limitations": { "reason": "empty_signal_set" },
  "raw_report": { "provider_summary": "no trades" }
}
```

Connector 会提交 `result_status=failed` 到 Cutie，形成可调参重测的 failed run。
HTTP 401/5xx、timeout、网络错误、malformed response 属于 runner failure，不提交
callback，避免把临时基础设施故障写成终态回测失败。

## Auto-upgrade

connector 收到 server 下发的 `upgrade_required=true` 时自动跑
`npm install -g @cutie-crypto/connector@<target>`，systemd `Restart=always`
接管重启。无 root 时回退到本地自安装路径 `~/.cutie-connector/pkg/`。发布包把
自身版本作为自动升级的最低可信版本；相同版、旧版和低于显式 floor 的目标即使
带 `upgrade_required=true` 也会在执行 npm 前拒绝。显式 maintenance rollback
仍只接受服务端登记的稳定版本，和自动升级防降级是两条不同的受控路径。

## Architecture

connector 是 [`@cutie-crypto/connector-core`](../connector-core/README.md) 的
adapter 实现。core 不假设平台命名 / 进程管理 / 网络协议，本包提供：

- `OpenClawPlatform` / `HermesPlatform` — `PlatformAdapter` 实现
- `callAgentGateway` — 本地 AI gateway HTTP 调用（OpenAI Responses API 兼容）
- CLI 入口（`cutie-connector` bin）

## License

MIT