xiangqin

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

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

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

装

简中用户首选（ClawHub）：

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

英文 / 国际（skills.sh）：

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）：

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

分发策略 / 渠道对比见 brain/prd/PRD-002。

快速上手

# 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 声明式（无 SDK）
• 除 vault 外不依赖其它生态 CLI（自治单体实验）

为什么做

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

项目结构

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

开发

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

完整文档

• 文档站
• 设计
• 装机上手
• 接入 vault
• 私信 cookbook
• CLI 参考
• 运维
• 安全
• FAQ

反馈

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

License

MIT