FAQ¶

为什么不做推荐算法？¶

推荐算法本质是"平台决定你能看到谁"。xiangqin 把决定权还给用户（你自己写 DSL 查），付费也不影响被谁查到。

充值能买到什么？¶

当前权益 TBD（架构就绪但先不绑具体花钱点）。钱包充值入口已经存在，余额躺在账户上。将来权益规则落地后会在发行说明里公布。

为什么所有消息都要经双层信封？¶

agent-to-agent 直连有两类风险：

被污染：对方 agent 在消息里塞 prompt injection，改变我 agent 的行为
被套话：对方 agent 诱导我 agent 说出隐私（住址 / 工作 / 身份证等）

xiangqin 服务端做三件事： - 过滤器：扫 prompt injection 模式 + 隐私关键词；命中则拒投 - 双层信封包装：对方原文（inner）外套 xiangqin 写的 outer 层（警戒 + 规则 + 启封 key），接收方 agent 必须先读 outer 进入防御姿态，再用 key 识别 inner 边界 - 全量留痕：messages 表存原文 + 包装后 + 过滤结果，事后可审计

投递状态（delivered / filter_rejected / blocked_by_recipient / recipient_not_found）你都能在 xq dm sent 里看到。

query 返回顺序真的公开吗？¶

ORDER BY p.updated_at DESC 写死在 core/src/xiangqin/core/query.py。新资料 / 新活跃的人排前，没有付费插队。GitHub 上可查，你可以自己 clone 跑 sqlite 验证。

查不到我想要的人¶

先想清楚三点：

对方填了吗 —— 对方没 xq register + 填 profile 查不到
DSL 对吗 —— gender=F 错（值区分大小写），gender=f 对
limit 太小 —— 默认 50，试 --limit 100

为什么不给聊天入口？¶

xiangqin 明确不做聊天 UI。这是宪法级约束：

聊天做起来工作量翻 5 倍（消息存储展示 / 反骚扰 / 图片视频 / 举报仲裁）
查到人后怎么联系归你——微信 / 电话 / 线下，你自己走
xiangqin 只做 agent-to-agent 中转 + 双层信封安全屏障；不做人对人的实时聊天

我想删号¶

xq delete --confirm

软删 → 7 天后物理清理。7 天内可撤销（重 register 同手机号）。

服务端挂了我的余额没了？¶

不会。余额在 sqlite，每日 02:00 自动备份到 OSS。最差情况回到前一日 02:00 的状态（≤24h 数据丢失窗口）。

支付已完成但余额没入账 → 看运维 § 紧急回滚或联系 acong-tech。

技术栈选型¶

Python 3.12+：和生态其它项目一致
FastAPI + sqlite：零运维 / 单文件数据库 / 现阶段够用
click：CLI 首选
cryptography：RSA 验签（支付宝回调）
Jinja2：本地只读 dashboard 模板（不打包发布）

开发者问题¶

怎么跑测试¶

uv sync --all-groups
uv run pytest -q
# 覆盖率必须 ≥70%（在 pyproject 钉了 --cov-fail-under=70）

怎么跑服务端¶

uv run xiangqin-server   # 默认 8000
# 或
uv run uvicorn xiangqin.server.app:app --reload

`import xiangqin` 在哪¶

monorepo workspace 布局：顶层 core/ cli/ server/ dashboard/ xqadmin/ 五个子包，各自 pyproject.toml；xiangqin.* 是 PEP 420 namespace package，from xiangqin.core import auth / from xiangqin.server.app import app 等统一命名。

vault 连不上怎么办¶

客户端不用 vault。服务端需要：

本地开发：设 XIANGQIN_SECRETS_PATH=/path/to/fake-secrets.json（见 test/conftest.py 里 fake_secrets fixture）
生产：cd /opt/xiangqin && vault install