技术架构 — QiLin 麒麟引擎

01Profile 与组合包

运行中的引擎由启动时按序叠加的各层组合而成——组合即产品，配置即代码。

Profile 是存放在 Harness home 中的具名组装。它列出自己叠放的组合包，存放自己安装的树外插件，并保存用户自己的 cordis.patch.yml。web、headless、sdk、sdk-minimal 和 acp 作为模板随发行版交付。

组合包（bundle）是 Kylin 配置项及其挂载代码的分发格式，因此它插入的内容始终可被其上各层 patch。各层按此顺序应用在空条目列表之上：

组合包（按 profile 列出的顺序）
  → profile 的 cordis.patch.yml
    → home 级的 cordis.patch.yml
      → 任意 --patch overlay

一条 patch 按 id 定位某个条目并替换其整个 config，或插入新条目。qilin-base 是 web、headless、sdk 与 acp profile 的共享第一层：模型适配器、工具、持久化、沙箱与审批策略、设置、凭据、遥测。qilin-web-app 增加浏览器应用，qilin-headless 增加不带服务器的一次性运行器，qilin-sdk-app 增加 SDK JSON-RPC 服务器，qilin-acp-app 增加仅用于自动化的 ACP 服务器。

要查看一台机器启动的配置树：

qilin --profile web --dump-config

它打印出的任何条目，都可以由你自己的 patch 替换。

02核心包

以下包向 Kylin 插件树贡献内容，每个服务占据一个稳定的上下文键。

包	职责	上下文键
`core/session`	仅追加的 `SessionEvent` 日志和内存存储	`ctx.sessions`
`core/system-prompt`	提示词片段与工具 schema 的组装	`ctx.systemPrompt`
`core/tools`	作用域化的工具注册表和带把关的执行流水线	`ctx.tools`
`core/agent`	`Agent` 接口、活跃 agent 注册表和 `agent/*` 事件	`ctx.agents`
`core/agent-loop`	实现该接口的默认驱动器	`ctx.agentLoop`
`core/scope`	按 agent 划分作用域的注册原语	库，无 ctx 键
`llm/llm`	消息与流式词汇表，以及适配器 seam	`ctx.llm`
`webhook/webhook`	已认证 delivery 的分派和会话创建	`ctx.webhookRuntime`

03事件域

事件就是扩展点，而选对事件域是大多数改动的第一个决定。

会话事件是追加到日志并通过 session/event 广播的持久事实。当某个事实必须在重新加载后仍然存在时，使用它。
Agent 事件（agent/*）携带活跃 agent：inbox、步骤、状态、请求、验证、续跑。要观察或拦截进行中的工作时，使用它。
能力事件无需导入循环即可向某个 seam（fs/*、tools/*、telemetry/*）附加策略和适配器。

其中 agent/pre-step、agent/request、llm/stream 和三个 tools/* 事件是 waterfall（瀑布式）事件，其监听器必须调用 next() 才能委托下去；策略监听器在拥有决策权时可以短路，仅做观察的监听器必须委托。

04轮次流程

一个步骤是一次模型请求加上它调用的工具；一个轮次包含零个或多个步骤：它在领取首条输入之前打开，并在不再欠下任何工作时关闭。

turn/start
  claim next-step input plus one queued message
  assemble prompt sections + tool schemas; project runtime context
  -> agent/pre-step                reject | enter(messages)
     step/start
     agent/request -> prepareCall
     reconcile system/message using the prepared call capability
     derive and freeze model history from the log
     stream the bound prepared call -> llm/stream -> agent/assistant-stream
       assistant/message | assistant/attempt
     tool/call* -> tools/pre-execute -> tools/execute -> tools/post-execute -> tool/result*
     step/end
     tools owe another request, or next-step input arrived -> claim -> next step
  -> agent/turn-stopping
turn/end

turn/*、step/*、system/message、user/message、assistant/message、assistant/attempt 和 tool/* 是持久会话事件；其余是分属三个事件域的实时扩展点。循环发送不可变请求，同时保留实时取消能力；每次尝试同步协调同一份已渲染组装结果、仅在首次尝试追加用户消息、按需记录 header/context、派生并冻结请求，再通过绑定调用发起流式请求。

05两种部署形态

同一套基座以两种形态交付，差异是有意为之。

WEB · 多租户

qilin web

为多个账户服务同一个入口。supervisor 维护账户名册，并按需为每个账户启动一个隔离的运行时；会话、工作区、用量账本、插件与模型设置都归属各自的租户。浏览器经部署自己的门认证，路由 cookie 转发到所属账户的运行时；TLS 可由 hub 终结，也可为每个账户分配独立 origin。

DESKTOP · 单用户

桌面壳

把一个本地引擎包进一个窗口，服务于一个人：没有名册、没有账户门、没有租户路由——整套基座在本地对着一个数据目录运行，插件树、会话与工具与 Web 形态完全一致。

更深入的子系统文档、配置目录与扩展指南，随源码仓库的 docs/ 目录与GitHub 仓库发布。