浅念
1.7 KiB
1.7 KiB
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（尚未存在）