Kiln 系统概览与架构

一、定位与产品形态

Kiln 是一个面向"完整 AI 开发闭环"的本地化工作台,覆盖评估、提示工程优化、RAG、微调、合成数据生成、Agent 与工具调用等全部环节。仓库根目录的 README.md 将其明确定义为"a workbench for the full AI development loop",强调"同一份任务与数据集贯穿所有技术栈,各阶段结果可累积叠加"。产品形态分为三层:

桌面应用负责让无代码背景的团队成员参与数据标注与评分 (README.md),MIT 许可的核心库则将同一套任务定义直接带到生产环境,实现"在 UI 中构建、在 Python 中部署"。

二、核心数据模型

Kiln 的数据集设计选择了"一组以 .kiln 为后缀的 JSON 文件"的扁平结构,而不是数据库 (libs/core/README.md)。这一选择带来三个直接收益:Git 友好、文件名带唯一 ID 避免冲突、便于使用 pandas/polars 等标准工具直接处理。核心层级关系如下:

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)。
• 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)。系统将远端仓库克隆到项目目录下的隐藏文件夹 .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 与 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),主题、输入、输出三段独立配置,便于客户端 SDK 自动编译。

See Also

• Kiln Data Model 与 Python 库
• Git 自动同步设计
• Kiln MCP Server (Beta)
• REST API OpenAPI 文档
• 用户文档站 (docs.kiln.tech)

评估、提示优化、合成数据与微调

概述与生态定位

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。

flowchart LR
  A[当前 Spec] --> B[生成 QuestionSet<br/>Question/AnswerOption]
  B --> C[用户回答<br/>SubmitAnswersRequest]
  C --> D[ClarifySpecOutput<br/>ExamplesForFeedbackItem + SDG 配置]
  D --> E[RefineSpecInput<br/>带反馈示例]
  E --> F[RefineSpecApiOutput<br/>新 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
• libs/core/README.md
• app/desktop/git_sync/README.md
• Kiln 官方文档：https://docs.kiln.tech

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::<server_id>::<tool_name>,并可附带输入/输出 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。

graph TB
    Task[Kiln Task] --> TRC[Task Run Config]
    TRC --> TC[ToolsRunConfig]
    TC --> MCP[MCP Tool<br/>mcp::local|remote::...]
    TC --> SUB[Subtask<br/>其他 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 标准,采用渐进式披露:仅在需要时把 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 官方文档
• Git 同步设计
• Python 库快速上手

概述与目标

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 导出，覆盖 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。

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

工作流关键特性：

资料来源：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
• Spec Copilot & Eval Builder
• Python Library Quickstart
• Git Auto Sync 内部规范

Pitfall Log / 踩坑日志

项目：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