整体架构

Hoshimi 的代码分四层，依赖只朝一个方向：api 和 cli 依赖 core，core 不依赖它们，也不导入任何框架。两个入口——服务器和命令行——都通过 build_services() 得到同一个 Services，再各自把它包装成 HTTP 路由或命令。本页先讲分层规则，再讲 Services、应用工厂和错误，最后跟随一个请求走完全程。

分层规则复制锚点链接

两条规则由测试保证：

• tests/core/test_architecture.py 解析 hoshimi/core 下每个文件的导入，发现上表禁止的框架就失败；它还检查这些文件里不出现 hoshimi.api 或 hoshimi.cli。httpx 是允许的，因为渠道适配器本身就是上游站点的 HTTP 客户端。
• tests/test_package_api.py 在一个新进程里 import hoshimi，要求 fastapi 和 httpx 都没有被加载，并且惰性导出的 Services、build_services、create_app 就是实现模块里的那些对象。

这样做的好处是：领域逻辑可以脱离服务器单独测试和复用；领域异常（hoshimi/core/errors.py）由 API 映射为 HTTP 响应、由命令行映射为退出码，core 自己不关心。

core 的模块复制锚点链接

Services复制锚点链接

hoshimi/core/context.py 的 Services 是一个命令或一个请求处理函数需要的全部：

build_services(settings=None) 在没有传入设置时读取数据目录里的 config.json，然后：从配置收集每个渠道的账号和选项（pool_inputs），用它们构建 Registry；在数据目录打开 hoshimi.db，各个存储共用这个连接；最后创建续期、签到、登录和更新检查的服务。登录管理器在一次浏览器登录写入新账号后，立即用新配置重建渠道池。

直接构造的 Services（测试、嵌入）只需要 settings 和 registry，其余存储默认把数据放在内存里，定时器类服务为 None。

运行中更新配置复制锚点链接

在 Web UI 保存设置会调用 Services.apply_settings(new)，不需要重启：

• 只有构建渠道池的输入（每个渠道的账号、选项和禁用状态）变化时才重建池；只改端口之类的设置不会重建。重建时，配置没有变化的渠道原样保留，所以它们在内存里的状态（哪个账号的刷新令牌被拒绝、哪个账号正在冷却）不会丢；只有网络选项变化的渠道也保留，只更新路由。
• 持有设置对象的每个服务（续期、签到、登录、更新检查、网络客户端）都改为指向新设置，免得某个服务稍后把旧配置写回文件。
• server.check_updates 的开关立即启停更新检查的定时器。

Services.close() 依次停止各个定时器、关闭 Playground 的后台命令和渠道的 HTTP 客户端，写入最后一批用量记录，然后关闭数据库。重复调用是安全的。

应用工厂复制锚点链接

hoshimi/api/app.py 的 create_app(services, ...) 构建 FastAPI 应用：

它做的事：

1. 校验安全设置，有问题时抛出 ValidationError，服务器不启动。
2. 生命周期：启动时按 server.auto_refresh、server.auto_checkin、server.check_updates 启动对应的定时器，并清理上次进程留下的临时对话；关闭时调用 services.close()。
3. 路由：/health；管理路由加上 /api 前缀（它们自己带 /v1，所以是 /api/v1/...）；模型路由在 /v1（Chat Completions、Responses、模型列表、TypeSafe 分类、Anthropic Messages）。交互式文档在 /docs，OpenAPI 文档在 /openapi.json，ReDoc 关闭。
4. 中间件：配置了 security.allow_origins 时加 CORS；4096 字节以上的响应 gzip 压缩；SecurityMiddleware 检查 Host 头、浏览器请求的来源、客户端地址是否在允许的 CIDR 内，以及访问密钥（管理 API 与文档）和模型 API 密钥（/v1/）。规则见安全。
5. 最后挂载 Web UI（SPAStaticFiles）：只接收其他路由都不匹配的路径；assets/ 下带哈希的文件缓存一年，index.html 不缓存；接受 HTML 的未知路径回落到 index.html，其他未知路径仍是 404。没有构建产物时记录警告，只提供 API。

把 Hoshimi 嵌入另一个 ASGI 应用：

from hoshimi import build_services, create_app

app = create_app(build_services(), api_prefix="/gateway")

Web UI 从自身脚本的 URL 推导部署根路径，所以挂在前缀下无需改动。

错误复制锚点链接

hoshimi/core/errors.py 定义领域异常，每个带一个代码、一个 HTTP 状态和一个命令行退出码：

渠道的 ProviderError（见渠道适配器）是 UpstreamError 的子类，带上游的状态码：上游返回 4xx 或 5xx 时，这个状态码原样传给客户端。

hoshimi/api/errors.py 按路径选择错误的形状：

• /v1/messages 与 /v1/messages/count_tokens：Anthropic 的 {"type": "error", "error": {"type", "message"}}；原生透传的上游错误原样返回上游的响应体和头。
• 其他 /v1/ 路径：OpenAI 的 {"error": {"message", "type", "code"}}。
• 管理 API：{"code", "message", "detail"}。

命令行的 main() 捕获 HoshimiError，记录它的消息并以它的退出码退出；Ctrl+C 退出码为 130，其他意外异常打印回溯后以 1 退出。

一个请求的路径复制锚点链接

以 POST /v1/chat/completions 为例：

flowchart TD
A["客户端 POST /v1/chat/completions"] --> B["SecurityMiddleware"]
B --> C["routers/chat.py"]
C --> D["prepare_request"]
D --> E["tracked_chunks: stats.turn"]
E --> F["Registry.stream"]
F --> G["Provider.stream_using: 账号轮换"]
G --> H["stream_raw: 上游协议"]
H --> I["归一化分片"]
I --> J["emit_chat_chunks"]
J --> K["SSE 帧与 [DONE]"]

其他协议共用这条路径，只有两端不同：

Messages 的流式响应在上游思考期间每 15 秒发送一次 event: ping，客户端断开时关闭上游连接（hoshimi/api/heartbeat.py）。Playground 的对话走的也是同一条路由和计量路径，只是用量记录的来源不同。

命令行复制锚点链接

hoshimi/cli/app.py 的 get_app() 是注册命令的唯一位置；每个命令的实现在 hoshimi/cli/commands/。Typer 的私有导入（typer._click）只出现在 hoshimi/cli/factory.py，Typer 的版本变化先在这里、在命令行测试里暴露。所有命令都有 --debug 选项，打开调试日志。python -m hoshimi 与 hoshimi 命令等价。