Cordis 配置

嵌入式 Cordis/DSH 引擎由两个文档和一组环境变量配置。默认情况下，两个文档位于后端旁；可通过 LIBRE_CORDIS_CONFIG 和 LIBRE_CORDIS_SETTINGS 更改位置。

文档	归属	形式	用途
`cordis.patch.yml`	Cordis Loader	顶层 YAML 数组	挂载引擎的插件行
`cordis.config.yml`	Libre WebUI 宿主	YAML 映射	提供商、凭据来源及功能开关

之所以使用两个文档，是因为 Cordis 的 Include 树载体会直接读取组合，并拒绝顶层不是数组的文件。因此宿主设置不能放入同一文件。

启用方式

设置中的 Cordis 引擎开关，位于智能体开关旁。

管理员在设置 → 用户管理 → 访问与策略 → Cordis 引擎中启用。变更立即生效：启用后在下次请求时启动引擎，禁用则释放引擎，无需重启。

以下两种部署级设置可固定状态，并将界面开关置灰，不会被静默覆盖：

来源	效果
环境变量 `LIBRE_CORDIS_ENABLED`	`true`/`false` 固定此部署的功能状态
`cordis.config.yml` 中的 `features.enabled`	显式值会固定状态；省略该键则由管理员决定

引擎还需要组合文档。请从随附示例开始：

cd backend
cp cordis.patch.example.yml cordis.patch.yml
cp cordis.config.example.yml cordis.config.yml

宿主读取 cordis.patch.yml，将自身默认值合并到桥接行，并把结果写入 <DATA_DIR>/cordis-runtime/cordis.composed.yml。生成文件可以丢弃，不能手动编辑；运维人员维护的 cordis.patch.yml 才是权威来源。

`cordis.config.yml`

trace: false

model:
  provider: libre-webui
  # Empty selects the authenticated caller's configured default/fallback route.
  model: ''

features:
  # Omit enabled to let the administrator use the Settings toggle.
  streaming: true
  tools: true
  persistence: true

# Optional absolute paths; defaults live under Libre WebUI's data directory.
# workspacePath: /absolute/path/to/workspace
# sessionStorePath: /absolute/path/to/sessions

顶层键

键	类型	默认值	含义
`trace`	布尔值	`false`	记录每次 Cordis 激活状态转换
`model`	映射	–	选择模型适配器，见下文
`features`	映射	–	能力开关，见下文

`features`

键	类型	默认值	含义
`enabled`	布尔值	`false`	挂载引擎。为 false 时，所有路由返回 `503`。
`streaming`	布尔值	`true`	接受流式输出模型响应的轮次
`tools`	布尔值	`true`	允许引擎工具并公开工具注册表
`persistence`	布尔值	`true`	启用 JSONL 持久化并要求相应服务，使会话在重启后保留

打开桥接只需设置 features.enabled 这一开关。顶层的 enabled 键不会被读取；所有能力开关集中在 features 中，便于统一查看已启用的功能。

`model`

键	类型	默认值	含义
`provider`	字符串	`libre-webui`	`libre-webui`、`deepseek`、`pi-ai` 或 `none`
`apiKeyEnv`	字符串	`OPENAI_API_KEY`	保存密钥的环境变量名称
`route`	字符串	`libre-webui`	引擎在请求中使用的提供商路由
`model`	字符串	`''`	引擎请求的模型 ID。手动声明的路由必须设置
`baseUrl`	字符串	`''`	端点覆盖值；空值使用适配器自身的默认值
`providers`	映射	`{}`	按路由名索引的手动提供商路由

引擎模型的来源

引擎没有独立的提供商配置，而是通过组合中 libre-webui-llm-adapter 行注册的 libre-webui 路由，调用 Libre WebUI 已有的提供商。界面中可聊天的模型就是引擎可使用的模型：在界面拉取模型后，引擎就能看到它，并复用已配置的凭据与端点。

设置 model.provider: libre-webui 即可使用此模式。这也是默认模式；凭据和提供商端点继续保留在 Libre WebUI 现有设置中。

model 指定引擎请求的模型。空值表示使用应用默认模型；部署没有默认模型时，引擎选择提供商层返回的首个聊天模型，并优先选用可用的本地模型。嵌入模型不在选择范围内。内部选定的路由同时保留提供商和模型：lwui:ollama:<encoded-model> 或 lwui:plugin:<encoded-provider>:<encoded-model>。这样，名称冲突或 Ollama 中断都不会把本地请求转到远程提供商。显式选择的提供商不可用时请求失败，绝不会静默回退到其他提供商。

只有 libre-webui 路由可以安全地使用空 model。提供商软件包支持的路由必须显式指定模型：dsh-llm-pi-ai 会解析目录以回答目录查询，但不会默认选用路由首项。因此，手动声明却没有 model 的路由无法处理任何轮次，并报出：

provider "<route>" resolves no models; the installed catalog does not describe
this route, so its models must be listed in configuration

将 model 设置为该路由 models 列表中的 ID。随附示例将 route: ollama 与 model: llama3.2 配对，对应声明的 llama3.2 项。

provider 决定挂载哪个适配器软件包：

libre-webui 通过本部署自己的提供商层服务引擎。这是受支持的默认模式。
none 启动没有模型访问能力的引擎。工具可以列出，会话可以使用，但无法回答轮次，适合验证组合。
deepseek 和 pi-ai 直接挂载提供商软件包。这些软件包不是后端依赖：携带所有提供商 SDK 会引入 59 个传递依赖，其中包括引擎根本不会使用的能力所需的已弃用软件包。请安装所需软件包并在组合中挂载对应行；若软件包不存在，宿主会指出其名称。

提供商路由包含以下字段：

字段	含义
`displayName`	面向用户的名称
`api`	线上协议，例如 `openai-completions`
`baseURL`	端点基础地址
`apiKeyEnv`	保存密钥的环境变量
`models`	模型列表；每项包含 `id`、`name`、`contextWindow`、`maxTokens`

凭据绝不会写入这两个文档。 apiKeyEnv 指定环境变量名，适配器在每次请求时解析，因此轮换密钥不需要重启。

`cordis.patch.yml`

文档为 Cordis Loader 条目的顶层数组。随附示例挂载九行，是推荐的起点。

- id: llm
  name: '@deepseek-ai/dsh-llm'

- id: session
  name: '@deepseek-ai/dsh-session'

- id: session-projection
  name: '@deepseek-ai/dsh-session-projection'

- id: session-persistence
  name: '@deepseek-ai/dsh-session-persistence-jsonl'
  config:
    # The host supplies the resolved sessionStorePath.

- id: system-prompt
  name: '@deepseek-ai/dsh-system-prompt'
  config:
    personaPrefix: ''

- id: tools
  name: '@deepseek-ai/dsh-tools'

- id: agent
  name: '@deepseek-ai/dsh-agent'

- id: agent-loop
  name: '@deepseek-ai/dsh-agent-loop'
  config:
    agents: []

- id: libre-webui-bridge
  name: './dist/cordis/dsh/engine-plugin.js'

条目字段

字段	必填	含义
`id`	否	用于定位行的稳定 ID；省略时从 `name` 派生
`name`	是	Loader 导入的模块标识，必须是字符串字面量
`config`	否	插件配置；允许 `!!js` 表达式
`disabled`	否	保留行但跳过它；允许 `!!js`
`inject`	否	该行额外需要的服务或拦截配置

Loader 直接导入 name，不会对它求值，因此不能使用 !!js 表达式。config 值可以使用 !!js；表达式稍后在所属行的纤程内求值，并能访问 Loader 上下文。可以使用 process.env 和 ctx.get(...)，不能使用 import.meta。

相对模块标识以组合文件自身所在目录为基准。裸模块标识通过后端软件包解析，因此 @deepseek-ai/dsh-tools 会找到 backend/node_modules 中的副本。

行顺序不决定加载顺序。Cordis 会在声明的服务可用后激活对应行，上述分组只是为了方便阅读。

必需的行

能够回答聊天的引擎需要以下全部条目：

行	提供的服务	使用方
`dsh-llm`	`llm`	智能体循环
`dsh-session`	`sessions`	智能体循环、桥接层
`dsh-session-projection`	`sessionProjections`	智能体循环
`dsh-system-prompt`	`systemPrompt`	工具、智能体循环
`dsh-tools`	`tools`	智能体循环、桥接层
`dsh-agent`	`agents`	桥接层
`dsh-agent-loop`	智能体驱动	回答轮次
桥接行	`libreDshEngine`	所有路由

还需要挂载工具插件行，例如 @deepseek-ai/dsh-fs-sandbox 和 @deepseek-ai/dsh-tool-fs，GET /api/cordis/tools 才会返回内容。没有工具插件的注册表为空是正常的。

环境变量

每个设置值都有对应的环境变量覆盖项。优先级依次为环境变量、文档、内置默认值。

变量	覆盖项	默认值
`LIBRE_CORDIS_ENABLED`	`features.enabled`	`false`
`LIBRE_CORDIS_STREAMING`	`features.streaming`	`true`
`LIBRE_CORDIS_TOOLS`	`features.tools`	`true`
`LIBRE_CORDIS_PERSISTENCE`	`features.persistence`	`true`
`LIBRE_CORDIS_TRACE`	`trace`	`false`
`LIBRE_CORDIS_MODEL_PROVIDER`	`model.provider`	`libre-webui`
`LIBRE_CORDIS_MODEL_ROUTE`	`model.route`	`libre-webui`
`LIBRE_CORDIS_MODEL`	`model.model`	`''`
`LIBRE_CORDIS_API_KEY_ENV`	`model.apiKeyEnv`	`OPENAI_API_KEY`
`LIBRE_CORDIS_BASE_URL`	`model.baseUrl`	`''`
`LIBRE_CORDIS_CONFIG`	组合文档路径	`<cwd>/cordis.patch.yml`
`LIBRE_CORDIS_SETTINGS`	设置文档路径	位于组合文档旁
`LIBRE_CORDIS_WORKSPACE`	引擎默认工作区	`<DATA_DIR>/cordis-workspace`
`LIBRE_CORDIS_SESSION_STORE`	持久化会话目录	`<DATA_DIR>/cordis-sessions`

布尔环境变量接受 1/true/yes/on 和 0/false/no/off。无法识别的值会回退到文档设置，不会进行猜测。

随附组合的 !!js 表达式也会读取 LIBRE_CORDIS_SESSION_STORE 和 LIBRE_CORDIS_WORKSPACE，因此宿主会在挂载插件树之前导出它们。

配置示例

完全离线的本地 Ollama

features:
  enabled: true
model:
  provider: pi-ai
  route: ollama
  model: llama3.2
  apiKeyEnv: OLLAMA_API_KEY
  providers:
    ollama:
      api: openai-completions
      baseURL: http://127.0.0.1:11434/v1
      apiKeyEnv: OLLAMA_API_KEY
      models:
        - id: llama3.2
          contextWindow: 131072
          maxTokens: 4096

Ollama 会忽略密钥，但 OpenAI 客户端要求设置密钥。导出 OLLAMA_API_KEY=ollama 即可满足要求，无需编造秘密信息。没有内容离开本机。

OpenAI 兼容网关

features:
  enabled: true
model:
  provider: pi-ai
  route: gateway
  model: acme-large
  apiKeyEnv: ACME_GATEWAY_API_KEY
  providers:
    gateway:
      displayName: Acme Gateway
      api: openai-completions
      baseURL: https://gateway.acme.example/v1
      apiKeyEnv: ACME_GATEWAY_API_KEY
      models:
        - id: acme-large
          contextWindow: 65536
          maxTokens: 4096

DeepSeek 官方服务

features:
  enabled: true
model:
  provider: deepseek
  route: deepseek
  apiKeyEnv: DEEPSEEK_API_KEY

在后端环境中设置 DEEPSEEK_API_KEY。

无提供商，仅使用工具

features:
  enabled: true
model:
  provider: none

引擎启动后可以创建会话，GET /api/cordis/tools 会列出配置的工具插件。由于没有适配器可以处理请求，发送消息会失败。

迁移说明

Cordis 桥接是增量功能。关闭时不会改变现有行为，且默认处于关闭状态。

升级现有部署。 无需任何操作。两个示例文档以 cordis.patch.example.yml 和 cordis.config.example.yml 提供，只有复制它们并启用功能后才会被读取。不会运行迁移、创建表或修改现有数据目录。

首次启用。 复制两个示例文档，设置 features.enabled: true，无需另装软件包：引擎软件包已经是后端依赖。首次请求时会创建 <DATA_DIR>/cordis-workspace、<DATA_DIR>/cordis-sessions 和 <DATA_DIR>/cordis-runtime。三者都是现有数据目录下的新目录，因此覆盖该目录的备份和恢复也会覆盖它们。

升级引擎。 解析后的引擎版本记录在 package-lock.json 中。backend/package.json 声明兼容 alpha 版本的范围。请有计划地升级，并在运行 npm install 后验证提供商及会话接口约定。DSH 软件包新增对等依赖时，npm 会在安装阶段报告，而不是等到挂载阶段。模型和会话格式由 DSH 负责；格式变更属于 DSH 发行说明，而不是 Libre WebUI 数据迁移。

回滚。 设置 features.enabled: false 并重启，或从 cordis.patch.yml 移除桥接行。libreDshEngine 服务会被撤销，监听器会释放，创建的智能体会被销毁。会话文件仍作为数据保留在磁盘上；删除 sessionStorePath 目录可回收空间。是否卸载软件包可自行决定，不会影响 Libre WebUI 的其他功能。

现有 Chat 和 Work 部署。 Chat 增加仅限管理员的 DeepSeek Harness 选项，使用临时引擎会话和现有 Chat 记录。Work 增加独立的 DeepSeek Harness 引擎选择，由隔离的 DSH 驱动及现有 Work 沙箱和审批流程支持。已有模型选择保持原有行为。

使用标准 libre-webui 适配器时，Chat 的智能体选择器同时提供基础配置档和显式 DSH 提供商模型。显式选择会保留限定的提供商标识，基础配置档使用运行中组合的默认模型。标题和思考摘要直接调用这些 DSH 模型的底层提供商，不使用智能体工具。自定义模型适配器路由只保留基础 Chat 项，并需要另行设置 Ollama 或插件任务模型来生成标题与思考摘要。

DSH 遵循管理员的 Ollama 开关。Ollama 被禁用时，其模型既不会列出，也不会被探测；显式 Ollama 选择会失败，不会切换提供商。运维人员固定的非限定模型名也需要 Ollama 目录才能安全解析；仅用插件的部署应选择限定的 lwui:plugin:<plugin>:<model>。

运行边界

宿主引擎和 Chat 仅限管理员及 solo 模式。 引擎页面是使用本地 JSONL 存储的共享管理员控制台，无法在 team 模式中挂载。沙箱 Work 使用既有 SQL 仓库。
模型调用使用经过身份验证的调用者。 交互式宿主轮次使用该管理员的提供商凭据和默认模型偏好。可信的非交互式组合可将 LIBRE_CORDIS_USER 显式设为活跃管理员 ID；不会隐式回退到最早的管理员。
宿主文件工具受工作区限制。 读写检查规范化目标；会话不能选择配置根目录之外的工作目录。原生 DSH 修改限制仍然有效，运维人员安装的额外插件属于可信服务器代码。
宿主工具遵循 DSH 策略。 引擎页面提供每会话只读/工作区写入控件及原生单次审批卡片。这些控件不会绕过工作区边界。无界面的 Chat 轮次拒绝无法展示的审批请求；Work 的 DSH 驱动则使用 Work 审批和容器隔离，不带宿主文件工具。
流包含实时文本及公开推理。 持久化消息保留完整记录，客户端不会再次收到实时文本的副本。
重启和删除使用已存储会话。 空会话和已完成的引擎会话在重启后保留。删除桥接创建的 JSONL 会话会停止写入方并移除文件。其他持久化实现必须提供合适的删除适配器。
旧版格式错误日志需要显式修复。 较早桥接版本写入的用户消息缺少必需 ID。严格读取器会拒绝这些日志，不会丢弃它们。恢复流程见故障排除。
标题在本地派生。 会话摘要使用第一条用户消息作为短标题；空会话没有派生标题。

连接运行中的 DSH 实例所配置的模型

可选的 dsh-native-provider 插件暴露另一个 DSH 实例中已配置的模型与提供商连接，例如端口 3080 上的本地 Web 应用。将它安装到该实例现有配置档中。插件只调用 ctx.llm：提供商密钥留在 DSH 中，连接不能创建会话、运行智能体、读取原生附件文件或执行原生工具。

两个进程必须位于同一 Unix 主机并使用同一 OS 账户。传输使用显式配置的 Unix 套接字；其物理目录必须归该账户所有，权限为 0700，套接字权限为 0600。不会新增 TCP 监听器，也不会复用或削弱 DSH 的浏览器身份验证。此本地连接不支持 Windows 或远程 DSH 主机。

OS 账户就是本地访问边界：使用同一账户运行的其他进程也能使用套接字。此连接不为共享账户的应用提供独立原生提供商凭据，也不提供应用间隔离。

安装独立插件

在 DSH → Plugins → Add plugin 中，将以下公开仓库 URL 粘贴到 Package name or address，再点击 Install：

https://github.com/libre-webui/dsh-native-provider

DSH 询问时启用组件。公开软件包版本为 0.1.1，使用 Apache-2.0 许可，包含预构建运行时及组合补丁，无需本地构建、安装脚本或 npm 运行时依赖。裸包名 @libre-webui/dsh-native-provider 尚未发布到 npm；请在对话框中使用 GitHub URL。

组合包选择 <DSH home>/lwui-provider/llm.sock，通常是 $HOME/.dsh/lwui-provider/llm.sock；若配置了 DSH_HOME，则优先使用它。私有套接字目录不存在时会自动创建。每个 DSH 主目录只运行一个活跃桥接；额外配置档应通过其用户级 cordis.patch.yml 覆盖套接字路径。完整路径不得超过 100 个 UTF-8 字节，且不能包含符号链接组成部分。覆盖方法见独立插件的配置指南。

可选的等效 CLI 命令为：

dsh plugin --profile web add https://github.com/libre-webui/dsh-native-provider

如果实际运行的配置档不是 web，请改用它的名称。CLI 安装后应重启配置档；通过运行中的界面安装时可立即启用插件。若 DSH 显示重启通知，请按提示操作。无需修改原生 DSH 源码或复制提供商密钥。

从 Libre WebUI 准备组合包

Libre WebUI 也随附准备脚本。在源码检出目录中构建后端，并准备一个新的输出目录：

npm run build:backend
node scripts/prepare-dsh-provider.mjs /absolute/dsh-provider-bundle /absolute/private-directory/provider.sock
dsh plugin --profile web add /absolute/dsh-provider-bundle

通过 npm 安装的发行版已包含编译后端和准备脚本；从安装目录执行最后两条命令即可，无需构建。随后重启选定的 DSH 配置档。两种准备方式都拒绝覆盖已有输出目录，并附带软件包元数据、许可证和安装说明。

连接 Libre WebUI

将 Libre WebUI 的 cordis.config.yml 指向相同的绝对套接字路径。使用公开组合包默认路径时，请将 /absolute/home 替换为实际主目录：

nativeProvider:
  socketPath: /absolute/home/.dsh/lwui-provider/llm.sock

也可以把 LIBRE_DSH_PROVIDER_SOCKET 设置为该绝对路径。环境变量为空时，即使文件声明了路径，也会禁用连接。在 LWUI 中启用 Cordis 引擎后，活跃管理员可在 Work 的 DeepSeek Harness 引擎、引擎页面和 Chat 的智能体组中选择原生模型；Chat 还需启用 CLI代理模型。Work 用 providerType: dsh 保存原始原生模型和提供商 ID；现有 LWUI 提供商支持的 DSH 任务保留原有提供商标识和引擎标记。

原生模型列表实时读取。提供商或凭据配置变更会使连接代次失效并取消正在进行的原生调用。套接字、模型或原生提供商不可用时请求停止；LWUI 不会回退到 Ollama 或其他提供商。标题和思考摘要直接调用选定的原生 LLM，不使用工具。此初版连接接受文本、推理和工具消息，拒绝原生图像或文件引用。

原生凭据属于 DSH 运维人员，因此即使普通 Work 开放给更多用户，该连接仍仅供管理员使用。模型请求可能根据 DSH 的提供商配置离开主机，Work 会显示远程提供商提示。在 team 部署中，处理这些任务的每个工作进程都必须能访问配置的本地连接；连接缺失时拒绝执行。禁用 Cordis 或移除套接字设置会撤销原生访问，但保留已保存任务。若 DSH 崩溃并留下套接字，请先停止所属实例，再仅删除该陈旧套接字后重启；插件拒绝替换任何已有文件系统条目。

升级或移除插件

修改插件前，请等待活跃原生请求完成或将其取消。若要在 DSH 界面中替换旧的本地 0.0.0/0.1.0 组合包，请使用 Uninstall，返回 Add plugin，再安装上述公开 GitHub URL。通过受支持的用户配置档覆盖项保留自定义套接字路径。原生会话和凭据保持不变。

已通过 GitHub 安装的插件可使用 CLI 更新：

dsh plugin --profile web update @libre-webui/dsh-native-provider

CLI 更新后重启并确认版本。原先禁用的插件仍保持禁用，测试连接前请检查启用状态。若要固定或回退版本，可使用 github:libre-webui/dsh-native-provider#<commit> 作为来源。对于自行准备的本地组合包，应构建新的输出目录并重新添加该目录；更新本地依赖不会拉取 GitHub。

移除连接前，先删除 LWUI 的 nativeProvider.socketPath 设置，或将 LIBRE_DSH_PROVIDER_SOCKET 置为空，然后执行：

dsh plugin --profile web remove @libre-webui/dsh-native-provider

移除后重启 DSH 配置档。已保存的 LWUI 任务仍会保留，但在同一显式连接恢复之前，其原生模型请求会失败。移除此插件不会删除 DSH 中已配置的提供商或凭据。只有确认旧组合包已不再安装时，才删除其生成目录。

原生提供商使用情况

原生请求显示在提供商使用情况的 DeepSeek Harness · 提供商下，使用所选原始模型名。每个实际模型请求只记录一次，包括工具轮次、标题和思考摘要。仪表板显示成功、失败和取消的调用、延迟及 DSH 报告的令牌数。缓存输入仅计入输入总数一次；缺少用量时保持未计量，不进行估算。提供商 ID 使用 dsh-native:<percent-encoded-native-provider-id>，适用于现有费率和成本报告规则；未知费率保持未定价。

通过 LWUI 已配置提供商发出的 DSH 请求继续使用该提供商现有的用量记录。目录读取，以及在到达原生推理前已被拒绝的请求，不会额外记录模型调用。计量从安装此版本连接后开始，不会编造历史用量。保存的用量仅包含标识、状态、时间和计数，不包含提示词、响应、凭据、端点或提供商错误文本。

验证配置

curl -s http://127.0.0.1:3001/api/cordis/health | jq

{
  "success": true,
  "enabled": true,
  "ready": true,
  "services": [
    { "name": "llm", "state": "ready" },
    { "name": "systemPrompt", "state": "ready" },
    { "name": "sessions", "state": "ready" },
    { "name": "tools", "state": "ready" },
    { "name": "agents", "state": "ready" }
  ]
}

收到 503 且 code: CORDIS_UNAVAILABLE 表示组合未成功挂载。error 字段包含原因，LIBRE_CORDIS_TRACE=true 可增加 Cordis 激活日志。常见原因见故障排除。

启用方式​

cordis.config.yml​

顶层键​

features​

model​

引擎模型的来源​

cordis.patch.yml​

条目字段​

必需的行​

环境变量​

配置示例​

完全离线的本地 Ollama​

OpenAI 兼容网关​

DeepSeek 官方服务​

无提供商，仅使用工具​

迁移说明​

运行边界​

连接运行中的 DSH 实例所配置的模型​

安装独立插件​

从 Libre WebUI 准备组合包​

连接 Libre WebUI​

升级或移除插件​

原生提供商使用情况​

验证配置​