li-sky/dsh-aiservice-deeplink

dsh-aiservice-deeplink

用于 DSH 模型配置的 AI Service Deeplink（aiservice://）导入与导出。针对组合的 llm-pi-ai 提供方路由，实现了
协议草案 v1
的传输层和配置层。

单个 aiservice://model、aiservice://provider 或 aiservice://bundle
链接携带端点、线路协议、凭据、模型能力，以及推理和传输策略。本包将此类链接转换为 DSH
提供方路由，并将已配置的路由转换回链接。

界面

| 界面 | 功能 |
| --- | --- |
| 设置 → 模型面板 | 粘贴链接，预览它将配置的内容，导入它，或从当前路由构建分享链接 |
| aiservice_deeplink 工具 | 供智能体使用的相同三种操作（preview、import、export） |
| POST /aiservice/preview | 传输 + 模式验证和目标摘要，无副作用 |
| POST /aiservice/import | 验证、发现模型，然后写入路由和凭据 |
| POST /aiservice/export | 从任何已配置的路由构建链接，包括内置的 DeepSeek 路由 |
| GET /aiservice/routes | 来自两个命名空间的每个可分享路由 |
| GET /aiservice/status | 命名空间是否存在以及是否可写 |

布局

| 文件 | 角色 |
| --- | --- |
| lib/protocol.js | 传输层（§2）、完整性（§9）和模式验证（§3–§6、§8）；严格 JSON 读取器、Base64URL 编解码器、合并优先级 |
| lib/mapping.js | llm.model / llm.provider / llm.bundle ⇄ llm-pi-ai 配置文件和原生 llm-deepseek 路由 |
| lib/index.js | 宿主插件：工具、HTTP 路由、设置和凭据写入 |
| lib/client.js | 浏览器插件：设置 → 模型面板（__ModuleLoader__ 包，手写，无构建步骤） |
| test/ | 78 个 node --test 用例，包括协议仓库自身发布的示例 |

挂载位置

~/.dsh/profiles/web/cordis.patch.yml 插入一行，通过绝对路径指向
lib/index.js。该包刻意不依赖任何东西：该行不属于配置文件的 pnpm 项目，因此
它无法导入 @deepseek-ai/，并且每个宿主服务都通过声明的 inject 列表或
在请求时通过 ctx.get 访问。

映射

两个适配器在此组合中拥有路由，导入和导出对它们的处理方式不同。

| Deeplink | DSH llm-pi-ai |
| --- | --- |
| endpoint.base_url | providers..baseURL |
| endpoint.api_format | providers..api（openai_chat_completions → openai-completions，…） |
| endpoint.provider / provider.id | 路由键（slug 化，针对无关路由去重） |
| endpoint.credential.api_key | 名为 _API_KEY 的凭据记录；配置文件保留 apiKeyEnv |
| transport.mode / timeout_seconds / cache_retention / retry | transport / timeoutMs / cacheRetention / retryPolicy |
| transport.extra_headers | headers（凭据同时提供的名称会报错，依据 §3.2） |
| capabilities. | models[].contextWindow / maxTokens / input |
| capabilities.api_features + compatibility | compat，其中公共字段优先于兼容性覆盖（§5） |
| inference.reasoning | models[].reasoningEfforts（mode: disabled 时为 false），外加仅当每个模型都能接受时才设置的路由级 reasoning |
| autodiscover | 在验证之后、持久化之前调用一次 llm.discoverModels（§4.2.1） |
| required_features | 支持 provider.autodiscover、transport.websocket、transport.websocket-cached；其他任何内容都会被拒绝 |

导出会读取两个命名空间，因此内置的 DeepSeek 路由像其他路由一样共享。llm-pi-ai 是一个以路由为键的注册表；llm-deepseek 恰好拥有一个固定路由（deepseek-official），带有一个扁平化区段，并被投影到相同的形态上——端点、凭据引用、思考策略，以及解析后的目录，后者由适配器作为模式默认值提供。导出的 endpoint.provider 是 deepseek，一个接收方可以从中推断默认值的目录标识符，而不是 harness 自身的路由名称。

有两个限制值得了解：

- 当未配置 baseURL 时，适配器会回退到来自受信任启动环境的 DEEPSEEK_BASE_URL，而该值无法从插件读取。显式配置的端点会被传递；否则，链接会携带 DeepSeek 的公共端点。
- 适配器自身的 reasoningEffort 默认值按请求应用，且从不出现在解析后的设置中，因此未配置的 effort 会被省略，而不是被猜测。显式配置的 effort 会被传递。

推理是唯一可能破坏整条路由的字段

providers..reasoning 是应用于该路由上每个模型的硬性默认值，而请求中指定了模型不支持的级别时，会以 UNSUPPORTED_REASONING_EFFORT 被拒绝。手工声明的模型完全不声明推理，因此它只支持 off。因此，将某个模型的 effort 提升到路由上会使其他所有模型不可用——这正是从 inference.reasoning.effort 进行无条件映射所导致的结果。

因此，effort 是按模型处理的：

- mode: disabled → reasoningEfforts: false，这是 harness 自身声明非推理模型的方式。
- 显式 effort，且载荷也为线上传输配备了该 effort（它指定了 compatibility.thinking_format 或 supports_reasoning_effort）→ 在该模型上设置 reasoningEfforts: { off: null, :  }，这样该级别就存在，会话选择器也会提供它。
- 显式 effort，但没有任何内容说明该级别如何到达线上传输 → 该模型保持不变，并报告该损失。无论如何都声明该级别会宣传一个不发送任何内容的控件，这与捏造无异
- 就像发明一种连线拼写一样。
- 只有当路由上的每一个模型都能接受同一级别时，才会设置路由范围的 reasoning 默认值。请注意，这关乎每个模型支持什么，而不是模型之间是否一致：提供方默认值会让每个模型都解析到相同的 effort，而这恰恰是那种否则会强制使用某个没有任何模型有能力发送的级别的情况。

Import 始终写入 llm-pi-ai。原生 DeepSeek 路由是单供应商适配器，不是用来指向任意端点的地方，而且路由名称在整个 llm 注册表中是唯一的——因此导入的链接永远不会占用另一个适配器拥有的名称，即使其端点匹配也是如此。

映射无法承载的所有内容（transport.user_agent、inference.temperature、inference.reasoning.history 和 budget_tokens、retry.max_retry_after_seconds、Anthropic 路由上的仅 completions 开关）都会在预览的备注中报告，而不是被静默丢弃。在导出时，对于高于协议所命名的所有级别的 thinking 级别也是如此：harness 的 max 会作为 xhigh 共享，并且该替换会在链接旁报告。

保证

- 解析永远没有副作用。 没有网络，没有写入；发现和凭据存储只发生在 import 内部。
- 失败是原子的。 整个更改通过一次 settings.update('llm-pi-ai', …) 调用完成，该调用会在持久化之前进行验证，因此被拒绝的导入会让先前的配置保持不变（§7）。
- 发现失败不会抹除配置。 声明了模型的提供方在其端点不可达时会保留这些模型（§4.2.1）。
- 凭据不会出现在日志和错误中。 响应和诊断携带错误代码和路径，绝不携带 URI 或机密（§6、§7）。
- 共享默认包含凭据，并且面板提供无凭据模式，该模式改为写入 credential.type = "prompt"（§6.1）。
- 导入永远不会替换已经存在的凭据。 预览会报告该引用是新的、已存储的，还是由启动环境提供的，而替换已存储的值需要显式的 overwriteCredentials。
- 导入只写入它命名的路由。 不会重述任何其他内容，因此用户并发编辑的路由，以及所有其他条目的存储格式，都会保留下来。

凭据

harness 拥有两个不相交的键空间，而导入的 API 密钥属于第一个：

| 空间 | 地址 | 存储为 | 使用者 |
| --- | --- | --- | --- |
| reference | _API_KEY，一个 POSIX shell 标识符 | .credentials.yaml refs: | 路由的 apiKeyEnv，每个请求解析一次 |
| record | /，小写连字符分隔 | .credentials.yaml records: | 插件自己的登录流程（例如 llm-pi-ai/） |

pi-ai 路由命名的是一个引用，所以这就是该插件写入的内容：与 Models 页面使用的相同的 _API_KEY 推导方式，通过
同样的 credentials.set。引用是相对于环境分层的，而继承的进程环境优先于托管文件——因此，启动 shell 会遮蔽的写入会被提供方拒绝，而这个插件会先检查 credentials.describe 并报告它，而不是在导入中途失败。

因为引用是一个共享名称，而不是某个链接的私有槽位，所以派生名称永远不会覆盖已经存在的值。否则，一个命名为 anthropic 的链接会替换用户为该提供方存储的任何密钥。

测试

node --test 'test/.test.mjs'

test/protocol.test.mjs 逐字节复现协议仓库发布的 model.uri、provider.uri 和 bundle.uri，并检查规范要求的拒绝情况。将 AISERVICE_EXAMPLES 指向该仓库的另一个检出，即可针对不同修订版本运行。

修改它

配置文件通过绝对路径挂载宿主部分，而 Node 按 URL 缓存 ES 模块：对 lib/.js 的编辑只有在 dsh web 重启后才会到达正在运行的进程。客户端 bundle 还需要刷新页面。