• 人工智能
• AI 应用
• AI 评测
• RAG
• 微调
• 提示工程
• 开发工具
• 桌面应用

导读

specs/monorepo.md 是 Kiln 仓库的架构总纲：它定义了「一个仓库包含多个项目」的 Monorepo 布局，明确了libs/core、libs/server、app/web_ui、app/desktop四个子项目的职责边界，并规定了跨子项目规格文档的统一存放位置。读完本文，你将理解 Kiln 各子项目之间的依赖关系与构建方式、每个目录内部的技术栈组织，以及如何在仓库中为新特性编写规格文档并决定其存放位置。

一、Monorepo 总体布局：一个仓库、多个项目

Kiln 仓库采用经典的 Monorepo（单仓库多项目）组织方式，根目录下包含四个独立的子项目，各自拥有独立的技术栈、构建配置与版本发布节奏：

这一描述与根目录 pyproject.toml 中的 uv workspace 声明完全对应：

[tool.uv.workspace] members = ["libs/core", "libs/server", "app/desktop"]

注意app/web_ui不在 uv workspace 成员之列——它是独立的 npm/Node 项目（见 app/web_ui/package.json），由 SvelteKit 构建，其依赖锁定在独立的package-lock.json中。因此 Kiln 的依赖管理是「Python 侧统一由 uv workspace 协调、前端侧走 npm」的双轨模式。

二、libs/core：Kiln 的核心 Python 库

2.1 项目定位与包信息

libs/core是四个子项目中最底层的基石，对应 PyPI 上的kiln-ai包。从 libs/core/pyproject.toml 可以看到其关键约束：

• 包名kiln-ai，版本 1.2.0，要求 Python >= 3.10；
• 采用 MIT 许可证（见 libs/core/LICENSE.txt）；
• 提供命令行入口kiln_ai（指向kiln_ai.cli:app）以及 pytest 插件入口点；
• 核心依赖覆盖了完整的能力矩阵：litellm（多模型路由）、openai、vertexai、together、lancedb+llama-index（向量存储与 RAG）、jsonschema/pydantic（数据校验）、jinja2（提示词模板）、pypdf/pypdfium2/pillow（多模态文档解析）。

2.2 内部模块划分：Monorepo 文档中能力清单的落点

Monorepo 文档将libs/core描述为承载「evals、synthetic data gen、fine tuning、RAG 等」核心功能，这些能力在 libs/core/kiln_ai 目录下有明确的模块化落点：

• adapters/：模型与执行适配层，内部再细分为chat/、eval/、fine_tune/、data_gen/、rag/、vector_store/、embedding/、model_adapters/等子模块，以及模型清单ml_model_list.py、提供商工具provider_tools.py；
• datamodel/：数据模型层（Project、Task、TaskRun、Prompt、Eval、Finetune、RagConfig等），是.kilnJSON 文件格式的类型化映射；
• tools/与tool_testing/：Agent 工具及测试插件；
• synthetic_user/：多轮合成用户对话数据生成；
• cli/：命令行入口（如kiln_ai package_project用于导出最小化任务包）；
• utils/：配置管理（~/.kiln_ai/settings.yaml）、工具函数等。

这种「核心能力全部沉淀在 libs 层」的设计，正是 Monorepo 文档强调的复用前提：桌面应用内嵌的服务器、独立部署的 REST 服务器以及kiln-ai库本身，运行的是同一套引擎与同一份项目文件格式。

三、libs/server：封装核心库的 FastAPI REST 服务器

3.1 包与命令行

libs/server对应 PyPI 上的kiln-server包，在其 libs/server/pyproject.toml 中，依赖kiln-ai是其唯一的核心业务依赖（"kiln-ai>=1.2.0"，通过tool.uv.sources声明workspace = true指向本仓库的libs/core），并定义了uvicorn、fastapi、python-multipart等 HTTP 基础设施依赖。

该包提供两个命令行入口：

• kiln_server：启动 REST 服务器，指向kiln_server.server:main；
• kiln_mcp：启动 MCP 服务器，指向kiln_server.mcp.mcp:main。

3.2 服务器组装模式：connect_*_api

libs/server/kiln_server/server.py 展示了 Kiln 服务器可组合的组装方式：make_app()创建 FastAPI 应用后，通过一系列connect_*_api(app)调用挂载各业务模块，包括project_api、task_api、prompt_api、spec_api、run_api、feedback_api、document_api、statistics_api、custom_errors等。这种「每个领域一个 connect 函数」的设计让libs/server可以独立运行，也可以作为中间件宿主任意扩展——这也解释了 Monorepo 文档中「wrapping the core library」的定位：它只是一层薄的 HTTP 适配，业务逻辑全部在libs/core。

从 libs/server/kiln_server/server.py 的tags_metadata可以看到服务器暴露的完整能力面：Projects、Tasks、Prompts、Specs、Runs、Feedback、Run Configs、Documents、Evals、Eval Inputs、Statistics、Synthetic Data、Multiturn SDG、Eval Builder、Fine-tuning、Prompt Optimization、Skills、Copilot、Code Tools、Tools & MCP、Providers & Models、Git Sync、Agent、Settings & Utilities、Jobs，共 25 个 API 分组，与libs/core的能力矩阵一一对应。

启动参数（来自 libs/server/README.md 与 server.py）：

usage: kiln_server [-h] [--host HOST] [--port PORT] [--log-level LOG_LEVEL] [--auto-reload AUTO_RELOAD] --host HOST 网络监听主机 --port PORT 网络监听端口 --log-level LOG_LEVEL 日志级别 --auto-reload （store_true）启用热重载

其中--host/--port会写入环境变量KILN_LOCAL_API_HOST/KILN_LOCAL_API_PORT，再由Config读取，以保证 uvicorn 重载后的 worker 进程仍能拿到正确配置。此外该包还附带 MCP 服务器：通过kiln_mcp --transport streamable-http <project.kiln路径>即可把 Kiln 的搜索等工具暴露给任意 MCP 客户端（详见 libs/server/kiln_server/mcp/README.md）。

四、app/web_ui：Svelte Web 前端

4.1 技术栈与构建

app/web_ui是 Kiln 的浏览器端界面，对应 Monorepo 文档中的「Svelte web app frontend」。从 app/web_ui/package.json 与 app/web_ui/svelte.config.js 可以确认：

• 框架：SvelteKit（Svelte 4）+ TypeScript，配@sveltejs/adapter-static静态适配器，fallback: "404.html"、prerender.default: true，即产物是可直接静态托管的预渲染站点；
• 样式：Tailwind CSS + DaisyUI 组件库；
• 测试与质量：Vitest 单元测试、Playwright 端到端测试（见 app/web_ui/tests/e2e）、ESLint + Prettier +svelte-check；
• 关键依赖：openapi-fetch消费后端生成的 OpenAPI 客户端，echarts渲染评估图表，marked/highlight.js渲染文档，@sentry/sveltekit与posthog-js负责遥测。

4.2 与后端的分工

前端不包含任何业务逻辑：所有后端调用都指向 FastAPI 服务器。前端通过 app/web_ui/src/lib/api_client.ts 与自动生成的类型定义api_schema.d.ts通信，而类型定义由generate_schema.sh从运行中服务器的 OpenAPI 规范生成（见 app/web_ui/src/lib/generate_schema.sh）。这种「后端产出 OpenAPI、前端生成类型化客户端」的模式，是 Kiln 前后端契约保持一致的关键机制。

五、app/desktop：PyInstaller 桌面应用

5.1 三合一架构

Monorepo 文档对app/desktop的定位可以拆成三个要点：

1. 运行 FastAPI 服务器——app/desktop/pyproject.toml 中，kiln-studio-desktop包将kiln-server声明为 workspace 依赖，并额外引入pystray（系统托盘）、pygit2（Git 同步）、pyinstaller==6.22.3（打包）、sentry-sdk（遥测）等桌面专属依赖；
2. 托管预编译的 Web 前端——app/desktop/studio_server/webhost.py 中的connect_webhost(app)通过app.mount("/", HTMLStaticFiles(...))把app/web_ui的构建产物挂载为站点根路径；
3. 启动浏览器展示 UI——app/desktop/desktop.py 使用tkinter初始化隐藏 Tk 窗口（用于接收 macOS dock 事件）、webbrowser打开浏览器、并管理系统托盘图标与退出流程。

5.2 studio_server：桌面专属的服务器扩展

app/desktop目录下还有一个关键的studio_server/子目录（app/desktop/studio_server），它扩展了libs/server，为 Web 应用补充了大量 API：agent_api.py、copilot_api.py、eval_api.py、eval_builder_api.py、finetune_api.py、import_api.py、skill_api.py、tool_api.py、provider_api.py、prompt_optimization_job_api.py、jobs/等，并内置了自动生成的 API 客户端（app/desktop/studio_server/api_client/kiln_ai_server_client）。可见「桌面应用 = 核心库 + REST 服务器 + 额外扩展 API + 静态前端 + Tk/托盘外壳」的分层关系，每一层都从更底层的子项目复用能力。

5.3 本地开发与构建

app/desktop/README.md 与根目录 Makefile 给出了完整的开发/构建工作流：

• make dev：仅运行 API 服务器（端口 8757，对应环境变量KILN_LOCAL_API_PORT），不含 Tk 托盘与原生对话框；
• make dev_desktop：运行完整桌面应用，要求先执行cd app/web_ui && nvm use && npm run build生成app/web_ui/build，否则会报错提示；
• make ui：启动 Vite 开发服务器（默认 http://localhost:5173），与 8757 端口的 API 配合实现前端热重载；
• cd app/desktop && uv run ./build_desktop_app.sh：调用 app/desktop/build_desktop_app.sh 执行 PyInstaller 打包，通常用于 CI/CD 管道。

六、规格文档（Specs）的组织约定

Monorepo 文档的最后一段定义了仓库内规格文档（项目提案/设计文档）的存放规则，这是仓库治理层面的核心约定：

跨多个子项目的规格应放在仓库根目录的/specs/projects/下；仅涉及单个子项目的规格应放在该子项目自己的/specs/projects/下。

在仓库中的实际落地情况是：

• 根目录 specs/projects 目前承载了大量规格，例如evals_v2（评估系统 V2）、git_auto_sync（Git 自动同步）、code_tools（代码工具）、cloudflare_workers_ai_provider（云厂商模型提供商）、timezone_aware_datetimes、mcp_sessions等 40+ 个项目；
• 这些目录遵循统一的规格文件骨架，以 specs/projects/evals_v2 为例，包含project_overview.md（项目概览）、functional_spec.md（功能规格）、architecture.md（架构设计）、implementation_plan.md（实施计划）、phase_plans/（分阶段计划）以及可选的components/、research/、reference/等补充材料；
• 子项目自身的规格目录 app/web_ui/specs/projects 与 app/desktop/specs/projects 目前均为空目录，说明仓库内现有的全部规格都集中在根目录。

之所以把大量规格放在根目录，从这些项目的内容可以推断：Kiln 的绝大多数特性天然跨越多个子项目。例如evals_v2涉及核心库的评估引擎、REST API 的评估端点与前端评估 UI；git_auto_sync同时改动桌面端服务（后台同步进程）与前端配置界面。只有纯前端或纯后端的改动才适合下沉到对应子项目的specs/projects/中。这个约定让规格文档的可见性与归属清晰：跨层特性在根目录统一可见，单层改动就近管理，避免了「一个特性拆到多个文档位置」的割裂。

七、子项目依赖关系与整体工作流

综合以上分析，Kiln 的四个子项目构成一条清晰的分层依赖链：

libs/core（kiln-ai 核心库） └──> libs/server（kiln-server REST + MCP 服务器） └──> app/desktop（kiln-studio-desktop：内嵌服务器 + studio_server 扩展 + 静态前端 + Tk 外壳） app/web_ui（SvelteKit 静态站点，独立 npm 项目） └──> 通过 OpenAPI/HTTP 消费 libs/server 与 app/desktop 的 API

配套的治理机制包括：

• 版本对齐：三个 Python 子项目当前均处于 1.2.0 版本，由 uv workspace 统一管理；
• 代码质量门禁：AGENTS.md 与根目录 checks.sh 定义了全仓检查套件——Python 侧使用 ruff（lint/format）+ ty（类型检查）+ pytest，前端侧使用npm run lint/npm run format_check/npm run check/npm run test_run/npm run build，并有脚本校验 OpenAPI 生成的客户端是否过期；
• 测试分层：核心库与服务器各自带完整测试（如 libs/core 与 libs/server/kiln_server 下的test_*.py），桌面端在 app/desktop/git_sync/integration_tests 有专门的 Git 同步集成测试套件，前端另有 Playwright 端到端测试；
• 许可证差异：根据根目录 README.md 的说明，libs/core与libs/server为 MIT 许可证，桌面应用本体采用 source-available / fair-code 模式，这是 Monorepo 中各子项目拥有独立许可证文件（如 libs/core/LICENSE.txt、libs/server/LICENSE.txt）的原因。

结语

specs/monorepo.md以寥寥数行定义了一套清晰的分层架构：核心能力下沉到libs/core，HTTP 与工具协议封装在libs/server，交互界面由app/web_ui提供，而app/desktop则把前三者组装成开箱即用的桌面产品；同时用「跨子项目规格放根目录」的约定保证跨层设计文档的可见性。理解这张布局图，是阅读 Kiln 源码、定位功能实现、以及为仓库贡献新特性的第一把钥匙。

• 人工智能
• AI 应用
• AI 评测
• RAG
• 微调
• 提示工程
• 开发工具
• 桌面应用