# https://github.com/Kiln-AI/Kiln 项目说明书 生成时间：2026-06-26 21:09:24 UTC ## 目录 - [Kiln System Overview and Architecture](#page-1) - [Evals, Prompt Optimization, Synthetic Data and Fine-Tuning](#page-2) - [RAG, Agents, Tools, MCP and Skills](#page-3) - [Desktop App, REST Server, Git Sync and Operations](#page-4) ## Kiln System Overview and Architecture ### 相关页面 相关主题：[Evals, Prompt Optimization, Synthetic Data and Fine-Tuning](#page-2), [Desktop App, REST Server, Git Sync and Operations](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/Kiln-AI/Kiln/blob/main/README.md) - [libs/core/README.md](https://github.com/Kiln-AI/Kiln/blob/main/libs/core/README.md) - [libs/server/README.md](https://github.com/Kiln-AI/Kiln/blob/main/libs/server/README.md) - [libs/server/kiln_server/mcp/README.md](https://github.com/Kiln-AI/Kiln/blob/main/libs/server/kiln_server/mcp/README.md) - [app/desktop/git_sync/README.md](https://github.com/Kiln-AI/Kiln/blob/main/app/desktop/git_sync/README.md) - [libs/core/kiln_ai/cli/cli.py](https://github.com/Kiln-AI/Kiln/blob/main/libs/core/kiln_ai/cli/cli.py) - [libs/core/kiln_ai/cli/commands/test_package_project.py](https://github.com/Kiln-AI/Kiln/blob/main/libs/core/kiln_ai/cli/commands/test_package_project.py) - [app/desktop/studio_server/api_client/kiln_ai_server_client/models/synthetic_data_generation_session_config_input.py](https://github.com/Kiln-AI/Kiln/blob/main/app/desktop/studio_server/api_client/kiln_ai_server_client/models/synthetic_data_generation_session_config_input.py)
# Kiln 系统概览与架构 ## 一、定位与产品形态 Kiln 是一个面向"完整 AI 开发闭环"的本地化工作台,覆盖评估、提示工程优化、RAG、微调、合成数据生成、Agent 与工具调用等全部环节。仓库根目录的 [README.md](https://github.com/Kiln-AI/Kiln/blob/main/README.md) 将其明确定义为"a workbench for the full AI development loop",强调"同一份任务与数据集贯穿所有技术栈,各阶段结果可累积叠加"。产品形态分为三层: | 形态 | 路径 | 许可 | 主要受众 | |------|------|------|---------| | 桌面应用 | `app/` | Source-available (fair-code) | 产品经理、领域专家、QA 等非工程师 | | Python 核心库 | `libs/core/` (PyPI 包名 `kiln-ai`) | MIT | 开发者与生产环境 | | REST/MCP 服务 | `libs/server/` (PyPI 包名 `kiln-server`) | MIT | 远程调用、外部 MCP 客户端 | 桌面应用负责让无代码背景的团队成员参与数据标注与评分 ([README.md](https://github.com/Kiln-AI/Kiln/blob/main/README.md)),MIT 许可的核心库则将同一套任务定义直接带到生产环境,实现"在 UI 中构建、在 Python 中部署"。 ## 二、核心数据模型 Kiln 的数据集设计选择了"一组以 `.kiln` 为后缀的 JSON 文件"的扁平结构,而不是数据库 ([libs/core/README.md](https://github.com/Kiln-AI/Kiln/blob/main/libs/core/README.md))。这一选择带来三个直接收益:Git 友好、文件名带唯一 ID 避免冲突、便于使用 pandas/polars 等标准工具直接处理。核心层级关系如下: ```mermaid graph TD A[Project 项目] --> B[Task 任务] B --> C[TaskRun 单次样本] B --> D[Finetune 微调配置] B --> E[Prompt 提示词] B --> F[DatasetSplit 数据切分] B --> G[TaskRunConfig 运行配置] ``` - `Project` 是顶层容器,组织一组相关任务。 - `Task` 定义提示词指令、输入/输出 JSON Schema、需求规格。 - `TaskRun` 保存单次执行的输入、输出与人工评分 ([libs/core/README.md](https://github.com/Kiln-AI/Kiln/blob/main/libs/core/README.md))。 - `DatasetSplit` 用于冻结数据切分以保证评估的可复现性。 `libs/core/kiln_ai/cli/commands/test_package_project.py` 中的测试 fixture 演示了典型结构:先创建 `Project` 与 `Task`,再添加 `TaskRunConfig`(包含 `model_name`、`model_provider_name`、`prompt_id`、`structured_output_mode` 等属性),并通过 `task.default_run_config_id` 关联回任务,这一模式在 CLI 的 `package_project` 命令中被复用。 ## 三、关键子系统 ### 3.1 Git 自动同步 `app/desktop/git_sync/` 实现了"零 Git 知识门槛"的协作能力 ([app/desktop/git_sync/README.md](https://github.com/Kiln-AI/Kiln/blob/main/app/desktop/git_sync/README.md))。系统将远端仓库克隆到项目目录下的隐藏文件夹 `.git-projects/` 中,通过 HTTP 中间件层持续轮询(目标 15 秒内同步),并以 503 错误阻止离线编辑以避免分歧。冲突之所以罕见,是因为 Kiln 数据模型大量采用"小而频繁的提交 + 不可变/仅追加对象"。 ### 3.2 MCP 服务 `libs/server/kiln_server/mcp/README.md` 描述了一个 Beta 阶段的 MCP 服务器,允许任意 MCP 客户端(Cursor、VSCode 等)调用 Kiln 内置工具,例如 Search Tool。其运行依赖:必须在启动 MCP 之前,先在 Kiln 桌面应用中对同一项目执行过搜索索引,否则无法提供检索能力。 ### 3.3 CLI 与自动优化 `libs/core/kiln_ai/cli/cli.py` 基于 Typer 暴露了 `projects`、`tasks`、`package_project` 三个子命令。社区对 v0.25.0 起引入的"Automatic Prompt Optimizer"反响积极,该功能也是用户在社区中关注度较高的能力之一。 ## 四、与社区关注的关联 社区中积累了三类典型诉求: - **手动数据录入与修正** (#115):希望支持人工直接编辑 `TaskRun`,而非仅靠合成或模型生成。 - **Unsloth 集成** (#251):希望将 Unsloth 的微调流程与 Kiln 打通,降低"导出 JSONL → 改 Notebook → 回灌 Ollama"的链路摩擦。 - **模型参数面板** (#31):希望在 UI 中持久化 `temperature`、`max_tokens` 等参数,目前这些通常通过 `TaskRunConfig` 在代码层维护。 ## 五、运行模式与许可 按照 [README.md](https://github.com/Kiln-AI/Kiln/blob/main/README.md) 与 [libs/server/README.md](https://github.com/Kiln-AI/Kiln/blob/main/libs/server/README.md) 的说明,Kiln 既支持"自带 API Key + 云端模型",也支持"通过 Ollama 完全离线"运行。REST 服务可通过 `uv tool install kiln_server` 安装后以 `kiln_server --host --port --log-level --auto-reload` 启动。生成式 API(如 `synthetic_data_generation_session_config_input` 模型)采用 FastAPI 的输入输出分离模式 ([synthetic_data_generation_session_config_input.py](https://github.com/Kiln-AI/Kiln/blob/main/app/desktop/studio_server/api_client/kiln_ai_server_client/models/synthetic_data_generation_session_config_input.py)),主题、输入、输出三段独立配置,便于客户端 SDK 自动编译。 ## See Also - [Kiln Data Model 与 Python 库](https://github.com/Kiln-AI/Kiln/blob/main/libs/core/README.md) - [Git 自动同步设计](https://github.com/Kiln-AI/Kiln/blob/main/app/desktop/git_sync/README.md) - [Kiln MCP Server (Beta)](https://github.com/Kiln-AI/Kiln/blob/main/libs/server/kiln_server/mcp/README.md) - [REST API OpenAPI 文档](https://kiln-ai.github.io/Kiln/kiln_server_openapi_docs/index.html) - [用户文档站 (docs.kiln.tech)](https://docs.kiln.tech) --- ## Evals, Prompt Optimization, Synthetic Data and Fine-Tuning ### 相关页面 相关主题：[Kiln System Overview and Architecture](#page-1), [RAG, Agents, Tools, MCP and Skills](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/Kiln-AI/Kiln/blob/main/README.md) - [libs/core/README.md](https://github.com/Kiln-AI/Kiln/blob/main/libs/core/README.md) - [libs/core/kiln_ai/cli/commands/test_package_project.py](https://github.com/Kiln-AI/Kiln/blob/main/libs/core/kiln_ai/cli/commands/test_package_project.py) - [app/desktop/git_sync/README.md](https://github.com/Kiln-AI/Kiln/blob/main/app/desktop/git_sync/README.md) - [app/desktop/studio_server/api_client/kiln_ai_server_client/models/synthetic_data_generation_session_config_input.py](https://github.com/Kiln-AI/Kiln/blob/main/app/desktop/studio_server/api_client/kiln_ai_server_client/models/synthetic_data_generation_session_config_input.py) - [app/desktop/studio_server/api_client/kiln_ai_server_client/models/prompt_optimization_job_output.py](https://github.com/Kiln-AI/Kiln/blob/main/app/desktop/studio_server/api_client/kiln_ai_server_client/models/prompt_optimization_job_output.py) - [app/desktop/studio_server/api_client/kiln_ai_server_client/models/clarify_spec_output.py](https://github.com/Kiln-AI/Kiln/blob/main/app/desktop/studio_server/api_client/kiln_ai_server_client/models/clarify_spec_output.py) - [app/desktop/studio_server/api_client/kiln_ai_server_client/models/refine_spec_input.py](https://github.com/Kiln-AI/Kiln/blob/main/app/desktop/studio_server/api_client/kiln_ai_server_client/models/refine_spec_input.py) - [app/desktop/studio_server/api_client/kiln_ai_server_client/models/requirement_rating.py](https://github.com/Kiln-AI/Kiln/blob/main/app/desktop/studio_server/api_client/kiln_ai_server_client/models/requirement_rating.py) - [app/desktop/studio_server/api_client/kiln_ai_server_client/models/tools_run_config.py](https://github.com/Kiln-AI/Kiln/blob/main/app/desktop/studio_server/api_client/kiln_ai_server_client/models/tools_run_config.py) - [app/desktop/studio_server/api_client/kiln_ai_server_client/models/question_set.py](https://github.com/Kiln-AI/Kiln/blob/main/app/desktop/studio_server/api_client/kiln_ai_server_client/models/question_set.py) - [app/desktop/studio_server/api_client/kiln_ai_server_client/models/examples_for_feedback_item.py](https://github.com/Kiln-AI/Kiln/blob/main/app/desktop/studio_server/api_client/kiln_ai_server_client/models/examples_for_feedback_item.py) - [app/desktop/studio_server/api_client/kiln_ai_server_client/models/submit_answers_request.py](https://github.com/Kiln-AI/Kiln/blob/main/app/desktop/studio_server/api_client/kiln_ai_server_client/models/submit_answers_request.py) - [app/desktop/studio_server/api_client/kiln_ai_server_client/models/answer_option.py](https://github.com/Kiln-AI/Kiln/blob/main/app/desktop/studio_server/api_client/kiln_ai_server_client/models/answer_option.py) - [app/desktop/studio_server/api_client/kiln_ai_server_client/models/output_file_info.py](https://github.com/Kiln-AI/Kiln/blob/main/app/desktop/studio_server/api_client/kiln_ai_server_client/models/output_file_info.py)
# 评估、提示优化、合成数据与微调 ## 概述与生态定位 Kiln 是一个面向"完整 AI 开发闭环"的工作台，串联起评估、提示优化、合成数据、RAG、代理与微调等环节，核心理念是让产品经理、领域专家和 QA 都能在不写代码的前提下贡献样本与评分资料来源：[README.md:1-40]()。 整套系统建立在 `kiln-ai` 核心 Python 库之上，提供基于磁盘的 JSON 数据模型与可观测的 REST 服务。最基础的工作单元是 Task（任务），其下聚合了 Prompt（提示）、TaskRun（运行样本与人工评分）、Finetune（微调配置与状态）以及 DatasetSplit（训练/测试/验证切分）等子对象，正是这一分层让评估、合成数据与微调三类流程可以共享同一份真实样本资料来源：[libs/core/README.md:1-30]()。 ## 评估系统与规范提炼 ### 评估与评分模型 评估结果可按"需求维度"打分，每条评分由 `value` 与 `type_`（`TaskOutputRatingType`）共同组成，便于在同一任务内同时存在多种评分体系（如五分制与通过/不通过）资料来源：[requirement_rating.py:1-32]()。在工具调用场景下，运行配置通过 `ToolsRunConfig.tools` 显式声明可用的工具 ID 列表，让"工具使用评估"可被独立追踪资料来源：[tools_run_config.py:1-30]()。 ### 规范提炼（Spec Refinement）流程 自 v0.24 起，Kiln 引入了 Spec 与 Kiln Copilot：通过交互式问答协助用户编写可执行的"任务规范"。系统会基于当前规范与若干示例生成提问集，提问由 `Question`、`AnswerOption` 与 `QuestionSet` 三类模型共同描述资料来源：[answer_option.py:1-25]()资料来源：[question_set.py:1-33]()。 用户回答通过 `SubmitAnswersRequest` 提交，载荷中携带任务提示、当前规范与问答对，服务端据此产出新一轮规范与合成数据配置资料来源：[submit_answers_request.py:1-35]()。提炼接口 `RefineSpecInput` 接收目标 `TaskInfo`、目标 `Spec` 与若干"带反馈的示例"，返回 `RefineSpecApiOutput`，包含新一轮的规范编辑与未采纳的反馈说明资料来源：[refine_spec_input.py:1-44]()资料来源：[refine_spec_api_output.py:1-35]()。 在 `clarify_spec` 阶段，模型会同时返回"用于反馈的示例"和合成数据会话配置，示例结构由 `ExamplesForFeedbackItem` 定义，包含输入、输出与是否违背规范的布尔标记 `fails_specification`资料来源：[clarify_spec_output.py:1-37]()资料来源：[examples_for_feedback_item.py:1-30]()。 ```mermaid flowchart LR A[当前 Spec] --> B[生成 QuestionSet
Question/AnswerOption] B --> C[用户回答
SubmitAnswersRequest] C --> D[ClarifySpecOutput
ExamplesForFeedbackItem + SDG 配置] D --> E[RefineSpecInput
带反馈示例] E --> F[RefineSpecApiOutput
新 Spec 编辑] F --> A ``` 社区反馈（如 GitHub #31）也反映出对"在 UI 暴露 temperature、max_tokens 等参数并持久化"的需求——评估管线必须能在统一配置下复用这些运行时参数资料来源：[README.md:1-40]()。 ## 提示优化与合成数据生成 ### 提示优化 `PromptOptimizationJobOutput` 以"优化后的提示文本"作为唯一核心字段 `optimized_prompt`，封装了 v0.25 引入的自动提示优化器的运行结果，使迭代后的 Prompt 可立即被写回 Task，并直接进入评估管线资料来源：[prompt_optimization_job_output.py:1-32]()。 ### 合成数据 合成数据（Synthetic Data Generation，SDG）在 v0.21 重写为 V3 体系。一次完整的合成会话由三个阶段构成，分别对应 `topic_generation_config`、`input_generation_config` 和 `output_generation_config`，三者在 `SyntheticDataGenerationSessionConfigInput` 中并列定义，覆盖了"先发散主题、再生成输入、最后产出输出"的标准链路资料来源：[synthetic_data_generation_session_config_input.py:1-35]()。 该三段式结构同时为后续 RAG 问答合成与 Tool Use 评估合成提供了统一的配置入口。配合 `clarify_spec` 阶段返回的 SDG 会话配置，团队可以基于同一条规范持续生产训练数据，再反馈到评估闭环。 ## 微调与项目导出 微调以 `Finetune` 实体记录训练配置和状态，其数据来源是从 `TaskRun` 切分出的 `DatasetSplit`。`libs/core/kiln_ai/cli/commands/test_package_project.py` 中的 `package_project_for_training`、`export_task` 与 `create_zip` 等函数负责把项目目录精简为训练框架可消费的最小集合，社区中关于 Kiln-Unsloth 桥接（#251）的诉求正是建立在此导出能力之上资料来源：[test_package_project.py:1-44]()。 对于需要分发运行产物的场景，`OutputFileInfo` 提供带签名 URL 的下载入口，使微调产物或导出包可被外部流程安全拉取资料来源：[output_file_info.py:1-50]()。 在多用户协作方面，git 同步模块通过后台轮询保证本地仓库与远端在 15 秒内对齐；频繁且小颗粒的提交让评估样本、合成数据与微调记录天然具备版本历史，并大幅降低并发冲突概率资料来源：[git_sync/README.md:1-30]()。 ## See Also - [README.md](https://github.com/Kiln-AI/Kiln/blob/main/README.md) - [libs/core/README.md](https://github.com/Kiln-AI/Kiln/blob/main/libs/core/README.md) - [app/desktop/git_sync/README.md](https://github.com/Kiln-AI/Kiln/blob/main/app/desktop/git_sync/README.md) - Kiln 官方文档：https://docs.kiln.tech --- ## RAG, Agents, Tools, MCP and Skills ### 相关页面 相关主题：[Evals, Prompt Optimization, Synthetic Data and Fine-Tuning](#page-2), [Desktop App, REST Server, Git Sync and Operations](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/Kiln-AI/Kiln/blob/main/README.md) - [libs/core/README.md](https://github.com/Kiln-AI/Kiln/blob/main/libs/core/README.md) - [libs/core/kiln_ai/cli/commands/test_package_project.py](https://github.com/Kiln-AI/Kiln/blob/main/libs/core/kiln_ai/cli/commands/test_package_project.py) - [app/desktop/studio_server/api_client/kiln_ai_server_client/models/tools_run_config.py](https://github.com/Kiln-AI/Kiln/blob/main/app/desktop/studio_server/api_client/kiln_ai_server_client/models/tools_run_config.py) - [app/desktop/studio_server/api_client/kiln_ai_server_client/models/mcp_tool_reference.py](https://github.com/Kiln-AI/Kiln/blob/main/app/desktop/studio_server/api_client/kiln_ai_server_client/models/mcp_tool_reference.py) - [app/desktop/studio_server/api_client/kiln_ai_server_client/models/mcp_run_config_properties.py](https://github.com/Kiln-AI/Kiln/blob/main/app/desktop/studio_server/api_client/kiln_ai_server_client/models/mcp_run_config_properties.py) - [app/desktop/git_sync/README.md](https://github.com/Kiln-AI/Kiln/blob/main/app/desktop/git_sync/README.md)
# RAG、Agents、Tools、MCP 与 Skills ## 概述 Kiln 是一套覆盖 AI 开发全链路的工作台,核心库由 Python 实现,围绕 `Project` / `Task` / `TaskRun` / `Finetune` / `Prompt` / `DatasetSplit` 等数据模型组织数据,使评估、提示词优化、RAG、代理(Agents)、工具(Tools)、MCP 与 Skills 可以在同一项目内协同工作 资料来源：[README.md:1-15]() 资料来源：[libs/core/README.md:7-25]()。 任务级 RunConfig 将模型、提示词、结构化输出模式与可用工具绑定,任意 Kiln 任务都可以作为另一个任务的工具,从而把多步推理或外部能力组合成代理系统 资料来源：[libs/core/README.md:18-25]()。 社区方面,自 v0.21 起 RAG 与搜索工具、v0.22 起的 Agents/Subtasks、v0.25 起的 MCP 服务器运行 Evals、以及 v0.26 起的 Agent Skills 标准均已在桌面版中陆续落地。 ## 工具与 MCP 集成 工具由 `ToolsRunConfig` 描述,以工具 ID 列表形式声明任务可用的工具 资料来源：[app/desktop/studio_server/api_client/kiln_ai_server_client/models/tools_run_config.py:14-18]()。 MCP 工具通过 `MCPToolReference` 描述,ID 格式为 `mcp::local|remote::::`,并可附带输入/输出 Schema 快照以便在脱离 MCP 服务器时回放 资料来源：[app/desktop/studio_server/api_client/kiln_ai_server_client/models/mcp_tool_reference.py:24-35]()。 `McpRunConfigProperties` 持有 `tool_reference` 字段,并将 `type` 字段默认设为 `"mcp"` 资料来源：[app/desktop/studio_server/api_client/kiln_ai_server_client/models/mcp_run_config_properties.py:17-22]()。当导出包含本地 MCP 工具的项目时,CLI 会先弹出确认提示,确认后才继续执行 资料来源：[libs/core/kiln_ai/cli/commands/test_package_project.py:97-110]()。 ```mermaid graph TB Task[Kiln Task] --> TRC[Task Run Config] TRC --> TC[ToolsRunConfig] TC --> MCP[MCP Tool
mcp::local|remote::...] TC --> SUB[Subtask
其他 Kiln Task] TC --> SK[Skill] TC -. "导出时被拒绝" .-> RAG[RAG Tool] TRC --> PROMPT[Prompt + 结构化输出] ``` ## RAG、Subtasks 与 Skills RAG 在 Kiln 中以文档库与检索器为运行时后端。CLI 在打包项目时显式拒绝 RAG 工具,`package_project` 会以 `exit_code=1` 退出,原因是 RAG 强依赖本地索引,不适合作为静态产物分发 资料来源：[libs/core/kiln_ai/cli/commands/test_package_project.py:78-95]()。 Subtask 通过工具列表引用其他 Kiln 任务实现。打包流程中 `collect_subtask_ids_from_tools` 扫描 `ToolsRunConfig` 抽取被引用任务的 ID,确保它们随项目一起导出 资料来源：[libs/core/kiln_ai/cli/commands/test_package_project.py:1-15]()。 Skills 遵循开放 [Agent Skills](https://agentskills.io/home) 标准,采用渐进式披露:仅在需要时把 Skill 的额外上下文注入到提示中。导出阶段 `collect_required_skills` 收集项目实际引用的 Skill,`export_skills` 将其序列化进打包文件 资料来源：[libs/core/kiln_ai/cli/commands/test_package_project.py:1-15]()。 ## 导出流程与运行时同步 打包入口 `package_project` 依次调用 `validate_tasks`、`validate_and_build_prompts`、`validate_tools` 三个校验函数,再调用 `collect_required_tool_servers` / `collect_required_skills` / `collect_subtask_ids_from_tools` 收集依赖,确保所有外部引用都能在产物中解析 资料来源：[libs/core/kiln_ai/cli/commands/test_package_project.py:1-15]()。 多用户协作时,Kiln 提供基于 Git 的自动同步:本地仓库始终位于 `.git-projects/` 隐藏目录内,通过后台轮询与远端保持 15 秒以内的同步,离线时以 HTTP 503 错误阻断读写而非静默分叉 资料来源：[app/desktop/git_sync/README.md:1-15]()。 ## 常见失败模式 - 在 `package_project` 中包含 RAG 工具会直接失败,需在调用前剔除 RAG 工具 ID 资料来源：[libs/core/kiln_ai/cli/commands/test_package_project.py:78-95]()。 - 引用缺失的 Skill、Subtask 或 MCP Tool Server 会触发 `validate_tools` / `validate_skills` 抛错。 - MCP 本地工具在非交互环境下会卡在确认步骤,CI 场景需预先 mock `typer.confirm` 或提供 `--yes` 类开关 资料来源：[libs/core/kiln_ai/cli/commands/test_package_project.py:97-110]()。 ## See Also - [Kiln 官方文档](https://docs.kiln.tech) - [Git 同步设计](app/desktop/git_sync/README.md) - [Python 库快速上手](libs/core/README.md) --- ## Desktop App, REST Server, Git Sync and Operations ### 相关页面 相关主题：[Kiln System Overview and Architecture](#page-1), [RAG, Agents, Tools, MCP and Skills](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/Kiln-AI/Kiln/blob/main/README.md) - [app/desktop/git_sync/README.md](https://github.com/Kiln-AI/Kiln/blob/main/app/desktop/git_sync/README.md) - [libs/core/README.md](https://github.com/Kiln-AI/Kiln/blob/main/libs/core/README.md) - [libs/server/README.md](https://github.com/Kiln-AI/Kiln/blob/main/libs/server/README.md) - [app/desktop/studio_server/api_client/kiln_ai_server_client/models/__init__.py](https://github.com/Kiln-AI/Kiln/blob/main/app/desktop/studio_server/api_client/kiln_ai_server_client/models/__init__.py) - [app/desktop/studio_server/api_client/kiln_ai_server_client/models/output_file_info.py](https://github.com/Kiln-AI/Kiln/blob/main/app/desktop/studio_server/api_client/kiln_ai_server_client/models/output_file_info.py) - [libs/core/kiln_ai/cli/commands/test_package_project.py](https://github.com/Kiln-AI/Kiln/blob/main/libs/core/kiln_ai/cli/commands/test_package_project.py)
# Desktop App, REST Server, Git Sync and Operations ## 概述与目标 Kiln 提供完整的 AI 开发闭环工作台，覆盖评估（Eval）、提示词优化、合成数据生成、RAG、Agent、工具调用以及微调（Fine-tuning）。整套系统由三层构成：桌面应用（Desktop App / Studio Server）、MIT 许可的 Python 库与 REST 服务器，以及基于 Git 的自动同步层。社区近期关注的热点（Agent Skills、自动 Prompt Optimizer、Kiln Chat 助手、Specs Copilot、Input Transforms 等）均在桌面端、库端或服务器端体现，Git 同步则保证团队协作时数据不丢失、不分叉。资料来源：[README.md:14-25]()、[README.md:1-12]()。 ## 桌面应用与 Studio Server 桌面端通过 `app/desktop` 目录承载 Electron + 前端 UI，并由 Studio Server 提供 HTTP API。Studio Server 暴露了大量结构化模型以承载不同业务，例如： - `SyntheticDataGenerationSessionConfigInput` 描述主题/输入/输出三段式的合成数据生成配置； - `OutputFileInfo` 携带签名下载链接（`signed_url`、`mime_type`）用于将文件安全地返回给前端； - `ClarifySpecOutput` 与 `RefineSpecInput` 支撑 Spec Copilot 的迭代流程：先用澄清问题收集反馈，再用示例驱动规格（Spec）精炼； - `SubmitAnswersRequest` 接收用户对澄清问题的回答。 这些模型集中在 [`__init__.py`](https://github.com/Kiln-AI/Kiln/blob/main/app/desktop/studio_server/api_client/kiln_ai_server_client/models/__init__.py) 导出，覆盖 Chat、Eval、Fine-tune、Prompt Optimization、Spec、Job 等功能域。资料来源：[synthetic_data_generation_session_config_input.py:13-44]()、[output_file_info.py:11-20]()、[clarify_spec_output.py:13-19]()、[refine_spec_input.py:13-19]()。 ## REST Server 与 Python 库 `libs/server` 子包提供独立的 FastAPI 服务，可通过 `uv tool install kiln_server` 安装并以 `kiln_server` 启动，支持 `--host`、`--port`、`--log-level`、`--auto-reload` 等 CLI 选项；OpenAPI 文档由 GitHub Pages 托管。`libs/core` 则是核心数据模型与运行引擎，封装了 `Project` / `Task` / `TaskRun` / `Finetune` / `Prompt` / `DatasetSplit` 等对象。项目以 `.kiln` 扩展名的 JSON 文件存储，便于 Git 协作、pandas 加载和结构化校验。资料来源：[libs/server/README.md:5-37]()、[libs/core/README.md:24-50]()。 CLI 工具支持 `kiln package-project` 之类的命令，可在测试代码中观察到典型用法：通过 `TaskRunConfig`（含 `model_name`、`model_provider_name`、`prompt_id`、`structured_output_mode`）锁定任务运行配置，再由 `package_project_for_training` 等函数导出训练包。资料来源：[test_package_project.py:23-49]()。 ## Git 自动同步机制 Git 同步（`app/desktop/git_sync`）在 HTTP 中间件层工作：核心数据模型（`KilnBaseModel`、`libs/core`）保持原样，所有变更由 `git status` 事后观察并提交，从而避免侵入业务逻辑。设计目标包括：用户友好（仅需 PAT 即可完成克隆/提交/拉取）、多用户并行（数据模型以唯一 ID 文件命名，绝大部分对象为 append-only）以及在线优先（后台轮询保证本地仓库与远程差距不超过 15 秒）。资料来源：[app/desktop/git_sync/README.md:5-13]()。 ```mermaid flowchart LR UI[桌面应用 UI] -->|读写 .kiln 文件| FS[项目目录] FS -->|git status 观察变更| GSM[Git Sync Manager] GSM -->|小粒度 commit & push| Remote[(Git Remote)] Remote -->|后台轮询 <15s| BGS[Background Sync] BGS -->|检测冲突并回滚| GSM GSM -->|冲突时返回 503| UI ``` 工作流关键特性： | 特性 | 行为 | 失败模式 | | --- | --- | --- | | 高速小提交 | 每次写操作后立刻 commit+push | 网络失败时 stash 变更，不丢数据 | | 冲突解决 | API 调用触发回滚并同步远程 | 返回 503，客户端重试即可成功 | | 离线策略 | 必须在线；离线则阻塞读写 | 防止静默分叉 | | 仓库隔离 | 自动克隆到 `.git-projects/` 隐藏目录 | 不影响用户自己的 IDE/编辑器 | 资料来源：[app/desktop/git_sync/README.md:15-30]()。 ## 操作与协作工作流 典型用户旅程：团队成员通过 Kiln 桌面应用完成提示词设计、合成数据生成、Eval 标注与 Fine-tune 配置；每次保存都触发 Git 同步，5 分钟无活动后后台轮询自动暂停，下次 API 请求到来时立即恢复。Python 库与 REST Server 复用同一份 `.kiln` 数据，使评估过的任务可以直接导出（`export_task`、`export_evals`、`export_documents`、`export_skills`、`export_tool_servers`）并部署到生产环境。若需调整模型参数（如 temperature、max_tokens 等），目前需通过代码或后续 UI（社区 Issue #31 正在跟踪）暴露。资料来源：[test_package_project.py:1-22]()、[libs/core/README.md:52-78]()。 ## See Also - [Auto-Optimize & Prompt Optimization Jobs](auto-optimize.md) - [Spec Copilot & Eval Builder](spec-copilot.md) - [Python Library Quickstart](python-library-quickstart.md) - [Git Auto Sync 内部规范](../../../specs/projects/git_auto_sync/functional_spec.md) --- --- ## Doramagic 踩坑日志 项目：Kiln-AI/Kiln 摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。 ## 1. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/Kiln-AI/Kiln | README/documentation is current enough for a first validation pass. ## 2. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/Kiln-AI/Kiln | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/Kiln-AI/Kiln | no_demo; severity=medium ## 4. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/Kiln-AI/Kiln | no_demo; severity=medium ## 5. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/Kiln-AI/Kiln | issue_or_pr_quality=unknown ## 6. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/Kiln-AI/Kiln | release_recency=unknown