# 装机上手

## 装

```bash
# 方式 1：pip
pip install acong-tech-xiangqin

# 方式 2：uv tool（推荐，隔离环境）
uv tool install acong-tech-xiangqin

# 方式 3：skill（Claude Code 场景）
skills install acong-tech/xiangqin
```

装完验证：

```bash
xq --version
xq health           # 打生产 epsilon，期望 {"status":"ok","version":"..."}
```

## 第一次跑通

### 1. 注册

```bash
xq register 13800001111
# → 验证码已发 138****1111，60s 内有效
#   request_id: 01JF...
```

mock 期验证码固定 `123456`，生产期从阿里云短信服务收真码。

### 2. 验证 → 拿 session

```bash
xq verify 123456 --request-id 01JF...
# → 登录成功（新用户），user_id=01JG...
#   session 已写 ~/.xiangqin/session.json
```

### 3. 填资料

```bash
xq profile set gender m
xq profile set age 28
xq profile set city hangzhou
xq profile set tags '程序,登山,做饭'
xq profile set bio '想找能一起爬山的人'
xq profile show
```

可选字段：`gender / age / city` 必填，`tags / bio` 可空（`xq profile clear tags` 清）。

### 4. 查匹配

```bash
xq query 'gender=f AND city=hangzhou AND age>=25 AND age<=30'
# → 8 条命中
#   01JG...  f  27  hangzhou
#      tags: 瑜伽, 咖啡
#      bio:  想找稳定关系
```

### 5. 给心仪的人发私信

```bash
# 消耗 1 封信封；每天免费 3 封（0 点 UTC 重置）
xq dm send 01JG... "你好，我也在杭州..."

# 查我发出去的信 + 状态
xq dm sent
xq dm show <message_id>

# 买额外信封（超出免费 3/天后）
xq envelope state               # 查余额
xq envelope buy --count 10 --mock   # ¥10 买 10 封
```

### 6. 收信

```bash
xq inbox list                   # 按时间倒序
xq inbox show <message_id>      # 看详情 + 自动标已读
xq inbox reply <message_id> "..."   # 回信（消耗信封）
xq inbox report <message_id>    # 举报
xq block <sender_user_id>       # 拉黑
```

### 7. 登出

```bash
xq logout
```

## 常见错误

| 退出码 | 错误 | 解决 |
|---|---|---|
| 1 `未登录` | 过了 session 有效期 | `xq register <手机> && xq verify ...` |
| 1 `register failed: 429` | 1 分钟内重复发码 | 等 60s 或用上次返回的 request_id |
| 1 `verify failed: 400` | 验证码错 / 过期 | 重新 `xq register` |
| 1 `query failed: 400` | WHERE 语法不合规 | 看 [设计](../design.md) |
| 1 `insufficient_envelopes` | 今日免费用完且付费余额 0 | `xq envelope buy --count N --mock` |
| 1 `blocked_by_recipient` | 对方拉黑了你 | 信封退回；换人发 |

## 下一步

- [接入 vault](vault-integration.md) —— 把凭证从本地 `.env` 迁到 vault 声明式管理
- [私信 cookbook](cookbook.md) —— 发信 / 买信封 / 处理骚扰的常见玩法
