# xiangqin

**相亲平台** —— 虚拟信封私信商业模式。

[![CI](https://agentaily-xiangqin.pages.dev/assets/badges/ci.svg)](https://github.com/yarnovo/xiangqin/actions)
[![docs](https://agentaily-xiangqin.pages.dev/assets/badges/docs.svg)](https://agentaily-xiangqin.pages.dev/)
![tests](https://agentaily-xiangqin.pages.dev/assets/badges/tests.svg)
![coverage](https://agentaily-xiangqin.pages.dev/assets/badges/coverage.svg)
[![backup-fresh](https://github.com/yarnovo/xiangqin/actions/workflows/chaos-backup-freshness.yml/badge.svg)](https://github.com/yarnovo/xiangqin/actions/workflows/chaos-backup-freshness.yml)
[![backup-integrity](https://github.com/yarnovo/xiangqin/actions/workflows/chaos-backup-integrity.yml/badge.svg)](https://github.com/yarnovo/xiangqin/actions/workflows/chaos-backup-integrity.yml)
[![restore-drill](https://github.com/yarnovo/xiangqin/actions/workflows/chaos-restore-drill.yml/badge.svg)](https://github.com/yarnovo/xiangqin/actions/workflows/chaos-restore-drill.yml)
[![migration-drill](https://github.com/yarnovo/xiangqin/actions/workflows/chaos-migration-drill.yml/badge.svg)](https://github.com/yarnovo/xiangqin/actions/workflows/chaos-migration-drill.yml)
[![api-p95](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fyarnovo%2Fxiangqin%2Fmetrics-data%2Fapi-p95.json)](https://github.com/yarnovo/xiangqin/actions/workflows/chaos-metrics-daily.yml)
[![error-rate](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fyarnovo%2Fxiangqin%2Fmetrics-data%2Ferror-rate.json)](https://github.com/yarnovo/xiangqin/actions/workflows/chaos-metrics-daily.yml)

给 Claude Code 用户的相亲工具。不做推荐、不做聊天、不做匹配评分 —— 只做两件事：

1. 你用受限 WHERE DSL 自己查匹配（查询权在用户 agent）
2. 想跟谁说话就给谁写信（虚拟信封，每天免费 3 封，超额 ¥1/封）

## 装

**简中用户首选（ClawHub）**：

```bash
clawhub install acong-tech-xiangqin      # Claude / OpenClaw / 多 agent runtime
pip install acong-tech-xiangqin          # 配套 xq CLI
```

**英文 / 国际（skills.sh）**：

```bash
npx skills add acong-tech-skills/xiangqin       # 默认拿 main HEAD
npx skills add acong-tech-skills/xiangqin#v0.6.5 # 锁定版本
pip install acong-tech-xiangqin                  # 配套 xq CLI
```

**只要 CLI（不装 skill）**：

```bash
pip install acong-tech-xiangqin
# 或
uv tool install acong-tech-xiangqin
```

分发策略 / 渠道对比见 [brain/prd/PRD-002](brain/prd/PRD-002-distribution-strategy.md)。

## 快速上手

```bash
# 1. 注册
xq register 13800001111
xq verify 123456 --request-id <上条返回的 ULID>

# 2. 填资料
xq profile set gender m
xq profile set age 28
xq profile set city hangzhou
xq profile set height 178
xq profile set education master
xq profile set tags '程序,登山,做饭'
xq profile set bio '想找能一起爬山的人'

# 3. 查匹配
xq query 'gender=f AND city=hangzhou AND age>=25 AND age<=30'

# 4. 给心仪的人发私信
xq dm send <user_id> "你好，我是..."

# 5. 收件 + 回信
xq inbox list
xq inbox reply <message_id> "..."
```

## 心智模型

- **数据层**：sqlite @ epsilon
- **排序规则公开**：`ORDER BY p.updated_at DESC`（新资料 / 新活跃的人排前）
- **付费点**：主动发私信。每天免费 3 封信封，超额 ¥1/封
- **触达**：信进对方邮箱；若对方配了 agent gateway 还会收到推送（12h 去重）
- **隐私红线**：手机号 HMAC-SHA256，永不明文；双方 agent_gateway_url 互不透露

## 设计原则

- 查询权在用户（不做推荐算法）
- 排序规则固定公开（不做暗箱权重）
- 付费 = 主动接触权（不影响被查）
- 匿名代理（不透露对方 URL/token）
- 不做聊天（只存单次信件，30 天 TTL）
- 凭证走 [vault](https://agentaily-vault.pages.dev/) 声明式（无 SDK）
- 除 vault 外不依赖其它生态 CLI（自治单体实验）

## 为什么做

传统交友 app 推荐算法变相骗钱；xiangqin 把游戏规则摊在桌面上——谁能查、谁能联系、怎么联系都是公开规则。

## 项目结构

见 [`CLAUDE.md`](./CLAUDE.md) —— 对外 `docs/` vs 对内 `brain/` 的分层 + 代码目录。

## 开发

```bash
uv sync --all-groups                      # 装全部 dep
uv run pytest -q                          # 跑测试（--cov-fail-under=70）
uv run ruff check src test scripts        # lint
uv run ruff format src test scripts       # format
uv run --group docs mkdocs serve          # 本地文档站 http://127.0.0.1:8000/
pre-commit install                        # 启用 pre-commit
```

## 完整文档

- [文档站](https://agentaily-xiangqin.pages.dev/)
- [设计](docs/design.md)
- [装机上手](docs/usage/getting-started.md)
- [接入 vault](docs/usage/vault-integration.md)
- [私信 cookbook](docs/usage/cookbook.md)
- [CLI 参考](docs/cli-reference.md)
- [运维](docs/ops.md)
- [安全](docs/security.md)
- [FAQ](docs/faq.md)

## 反馈

- GitHub Issues：https://github.com/yarnovo/xiangqin/issues

## License

MIT
