# CLAUDE.md — all-kefu 工作约定

## 项目定位

本项目 all-kefu 是**统一多租户 AI 客服平台**：一套引擎 + 租户配置包，消除"每客户复制一套代码"的旧模式。项目由 ai-kefu / ai-kefu-jc 两个复制分叉项目合并而来，**jc 为主线**（代码以 ai-kefu-jc 为基础迁移，再做租户化改造）。

## 硬约束

- **uvicorn 必须以 `--workers 1` 运行**。内存中的 token 缓存、限流状态、配置缓存、每租户 engine 缓存均假设单进程，多 worker 会导致状态割裂。任何启动脚本/部署配置不得改动此项。
- **Windows 环境**：跑 python / pytest 前设置 `PYTHONUTF8=1`（GBK 控制台遇 emoji / 中文 payload 会直接崩，血泪教训）。

## 本地开发访问方式

- 路由按 Host 解析租户：`/` 与 `/static` 也需要已知租户域名（未知 Host 一律 404，唯一豁免 `/health`，供部署健康检查 curl 用）。
- 本地访问二选一：改 hosts 把 `chat.agent.hnxinyouhe.com` / `chat2.agent.hnxinyouhe.com` 指到 `127.0.0.1`；或 curl 显式带 `-H "Host: chat2.agent.hnxinyouhe.com"`。
- uvicorn 起在 8018：`PYTHONUTF8=1 .venv/Scripts/python -m uvicorn app.main:app --port 8018 --workers 1`。

## 开发流程

- 改动 `seed_profiles` 后必须跑全量 pytest（出厂配置影响面大）。
- 目前尚无 tests/ 目录时的 pytest 报错属预期，后续任务会补齐。

## 文档索引

- 设计文档（spec）：`docs/superpowers/specs/2026-10-12-unified-kefu-platform-design.md`
- Phase 1 实施计划：`docs/superpowers/plans/2026-10-12-phase1-engine-merge-tenantization.md`
- 部署坑手册：Phase 4 补 `docs/deploy-production.md`（尚未存在）