# 开发指南 ## 环境与命令 - Node.js ≥ 22.19;主开发测试依赖锁定 DSH `0.2.2-rc.1`、Cordis `4.1.0`、Loader `1.1.0`,Schemastery 解析为 `3.19.0`。插件依赖 Schemastery `~3.18.5 || ~3.19.0`,与宿主共用一份。对外 peer 使用下述兼容范围。 - 使用 `package-lock.json` 安装依赖;锁文件下载地址使用 npm 官方 registry。 - 浏览器脚本当前使用本机 Microsoft Edge 的 headless 通道,需要已安装 Edge;`npm ci` 不会安装 Edge。 ```sh npm ci npm run verify npm run test:ui npm pack ``` | 命令 | 行为 | | --- | --- | | `npm run lint` | 检查源码 Promise 处理及 React Hook 规则 | | `npm run format:check` | 校验源码、脚本和测试的统一格式;format 命令可修正 | | `npm run typecheck` | 通过 tsconfig.test.json 检查源码与 TSX fixture,不输出文件 | | `npm run build` | tsc 生成 lib,esbuild 生成压缩的 DSH 客户端入口 | | `npm test` | 先构建,再测试 lib 中的实际产物 | | `npm run verify` | lint、格式、类型检查、构建测试、打包文件预检查;只构建一次 lib,pack 预检查跳过生命周期脚本 | | `npm run test:ui` | 六组浏览器脚本,包含批量核对,部分截图写入 work | | `npm run test:legacy -- --ui` | 在 work 下创建隔离副本,用已提交的旧宿主锁文件执行 npm ci、verify 和相同的六组 Edge 测试;不修改当前依赖或真实 profile | | `npm run test:legacy -- --update-lock` | 依赖调整后更新旧宿主锁文件;只更新锁,不代表测试通过,随后仍需执行回归 | | `npm pack` | prepack 先构建,仅生成本地 tgz,不等同于 `npm publish` | | `npm run release:notes -- --from <上次发布标签>` | 从双语变更条目生成 work/release/notes.md,仅本地预览,不发布 | 日常使用标准测试命令,不在修改源码后直接测试旧 `lib`。浏览器 fixture 测试不能替代真实 Desktop 验收。GitHub Actions 在 Windows runner 上使用 Node 22.19.0,分别验证主基线和旧宿主的完整检查与六组 Edge 浏览器测试;Ubuntu 验证主基线。真实 Desktop 验收由维护者在发布阶段另行安排,不作为本轮兼容升级或自动发布的阻断条件;结果仍须与自动化分开记录。 ## 宿主版本兼容策略 所有 DSH peer 与 `engines.dsh` 继续使用 `^0.2.0-rc.2 || ^0.2.1-alpha.1 || ^0.2.2-rc.1`,包含从 `0.2.0-rc.2` 到 `0.2.2-rc.1` 的版本;不接受 `0.3.0` 及其预发布。`0.2.0-rc.2` 宿主仅检查 DSH peers;`0.2.1-rc.5` 起的[兼容检查器](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.2.1-rc.5/packages/boot/app-boot/src/plugin-compatibility.ts)在插件自有 `engines.dsh` 存在时只按该字段决定,未声明时才回退 DSH peers;不兼容结果由 `peers` 改为 `requirements`。npm 安装仍独立检查 peer 依赖。两处声明应保持一致。Cordis peer 保留 `~4.0.4 || ~4.1.0`、Loader 保留 `~1.0.5 || ~1.1.0`,覆盖当前补丁版本;React 保持 `^18.3.1`。 两套宿主检查器都使用 `includePrerelease: true`,因此上述范围还允许后续 `0.2.x` 的预发布进入加载检查。npm 默认规则不同:每个新补丁版本的预发布需要显式加入范围;例如 `0.2.3-alpha.1` 会通过 DSH 检查,但不满足 npm 默认 peer 判断。后续支持此类版本时,应核对接口、补充范围并回归测试,不依赖用户强制安装或版本豁免。 主 `package-lock.json` 固定 `0.2.2-rc.1`、Cordis `4.1.0`、Loader `1.1.0`,Schemastery 解析为 `3.19.0`;`compat/legacy-package-lock.json` 固定 `0.2.0-rc.2`、Cordis `4.0.4`、Loader `1.0.5`,Schemastery 按同一范围解析为宿主的 `3.18.5`。`scripts/host-versions.mjs` 只转换开发依赖,旧宿主测试同一份源代码及实际发布的 dependencies/peerDependencies。运行器复制白名单项目文件,不复制 node_modules、用户配置或构建产物,npm ci 后重新构建;work 下保留隔离环境方便诊断。依赖变化时显式更新旧锁,普通测试发现旧锁过期即失败,不临时解析新版本掩盖差异。插件版本号变化只同步隔离副本的根包版本,不重新解析依赖。 `test/peer-compatibility.test.mjs` 分别调用当前安装宿主的真实检查器,覆盖 engines 优先级、未声明时的 peer 回退、版本边界以及实际安装版本与锁文件一致性。Settings 测试既保留有限字段 fixture,又补充真实 llm-pi-ai 完整 Config schema 的保存与重启检查;后者仍不代表运行了完整适配器服务、internal/config 钩子或真实模型请求。UI 测试使用 Edge 和模拟远程响应,没有覆盖真实 Gateway 的 owner/受限身份授权。当前操作管理 profile 全局配置,未声明 resources 不视为已知缺陷;如以后支持受限连接,需按实际身份和授权策略单独验证,不能把 Web profile 等同于非 owner。 允许加载不等于完成真实 Desktop 验收;兼容性结论以对应测试日志和维护者记录的实际范围为准。升级到 DSH 0.3 系列前需重新评估接口并更新范围。固定历史源码引用和费用接口研究保留其原版本,不将其中的 rc.2 机械替换为 rc.5。 ## 目录职责 | 路径 | 职责 | | --- | --- | | `src/core/` | 目录转换、候选匹配、字段差异与原币种价格校验 | | `src/index.ts` | Cordis 服务、按需网络请求、目录缓存与报价快照 | | `src/integration/` | Settings 写入、导入预览、内置覆盖及批量核对与保存 | | `src/wire.ts` / `src/controller.ts` | 前后端共享 schema 与受限远程操作 | | `src/client/` | 设置页、模型与价格草稿、列表及交互;model-draft 和 override-draft 提供草稿转换 | | `src/pricing-schema.ts` | Settings 价格持久化 schema | | `src/package-identity.ts` | 公共包标识;内部服务和配置 ID 保持兼容 | | `test/` / `scripts/` | 逻辑与宿主集成测试、浏览器 fixture、构建和验证脚本 | | `docs/` | 用户说明、开发契约与参考资料 | ## 宿主接入约定 - 模型和价格写入经过官方 Settings `mutate` 及 revision 检查;不直接重写用户配置文件。 - 内置继承目录按字段写入 `modelOverrides`,不替换完整目录;凭据不进入客户端响应。 - 客户端使用 `settings.section` 注册独立设置页,远程 namespace 在注入作用域内访问。 - Typert 描述使用当前版本的 `codec.create`。资源注册与事件监听必须随 Cordis 生命周期清理。 - React 和共享宿主服务使用 peer + dev dependencies;不要让插件引入另一份服务实例。 - 客户端产物注册 DSH 模块工厂;`./client` 使用宿主识别的 default 导出。Zod 在浏览器包内,尚未迁移 Zod Mini。 - 模型配置仍归适配器,价格存插件 `prices`;不向宿主模型注入未经支持的 cost 字段。 固定基线资料:[发布与加载](https://github.com/deepseek-ai/DeepSeek-Harness/blob/dsh-v0.2.0-rc.2/docs/user/develop/basic/publish.md)、[配置](https://github.com/deepseek-ai/DeepSeek-Harness/blob/dsh-v0.2.0-rc.2/docs/user/develop/basic/config.md)、[服务](https://github.com/deepseek-ai/DeepSeek-Harness/blob/dsh-v0.2.0-rc.2/docs/user/develop/framework/service.md)。 ## 文档维护 1. README 只保留用户需要的功能、安装、操作与限制,不堆放调试历史或发布待办。 2. 行为变化更新对应使用说明或 API 文档;自动化测试结果以实际 CI 运行记录为准。 3. 不把浏览器 fixture 或模拟测试写成真实 Desktop 验收。 4. 发布新版本前核对 README 命令、相对链接、源代码行为和许可。 5. **后续完成功能或修复时,一并在 `.changes/entries/` 添加简短的中英变更条目。** 同一功能的未发布条目可完善;已发布条目不修改、移动或删除,纠正内容另加文件。值得向用户说明的文档或发布流程变更也记录;格式见 [条目说明](../.changes/README.md)。 6. 更新日志与 Release 说明不附带由维护者另行执行真实桌面验收的固定声明(含同义中英文措辞)。测试范围与实际验证结果留在开发/验证文档,不作为日志附带字段;仍须如实区分自动化与真实宿主验证。 GitHub Release 通过手动触发的独立工作流构建、验证并按固定中英格式汇总条目,命令、试运行与失败处理见 [发布指南](releasing.md)。普通提交只运行 CI,版本由维护者指定,npm 仍手动发布;更改工作流不等于授权触发正式发布。 价格草稿的来源失效和数值显示规则集中在 src/client/price-draft.ts。开发依赖锁定 ESLint、typescript-eslint、React Hooks 规则和 Prettier;这些工具不随插件运行。CI 另在 Ubuntu 执行 verify,浏览器布局验收仍在 Windows Edge 上执行。 ## 后续版本待办 ### 第一组实施进度 0.1.5 已实现第一、二阶段:**批量核对、逐字段选择与确认保存**。支持选择最多 100 个显式模型、每批共享配置快照与最新目录、补全/更新两种模式、参数和直接单价逐字段选择,以及同来源整份倍率参考更新。宿主管理 15 分钟/20 份有界计划;写入前校验整批选择与两份 revision,分别报告参数和价格结果,部分失败时保留原选择和报价,仅在原版本仍可用时重试未完成部分。主要实现位于 `src/integration/review.ts`、`src/integration/batch.ts` 和 `src/client/BatchReviewPanel.tsx`;使用与限制见 [编辑面板](editor.md#批量核对与变化预览)。真实 Settings 临时 profile 覆盖写盘、重启、两命名空间各一次 mutation、部分失败及原币种倍率恢复;浏览器 fixture 覆盖勾选、确认与保存自身通知。真实 Desktop 验收仍待完成。 0.1.5 已实现第三阶段:**记住已确认的价格参考来源映射**。显式模型可按目标命名空间/供应商/模型、数据源和币种保存精确参考身份,支持指定别名、替换、清除、重启恢复及主动获取新报价。绑定目标的有效宿主报价才能确认映射;协议/API 地址或目录地址变化时失效,获取时保留精确条目、原币种和复杂计费检查。映射不会改动自动匹配、参数来源、批量来源或保存的倍率基价。主要实现位于 `src/integration/source-mappings.ts` 与 `src/client/SourceMappingEditor.tsx`;使用与协议见 [编辑面板](editor.md#记住参考来源与别名) 和 [Settings](settings.md#已确认的价格参考映射)。参数来源映射、跨目标集中管理及自动批量应用不在本阶段范围内。 下一项推进白名单配置导入导出,再处理费用试算。真实 Desktop/完整适配器验收、历史共识倍率参考的批量处理,以及更精细的选择保留与诊断仍单独跟进。倍率目前采用完整快照策略,目录缺少已保存项时拒绝批量替换,不混用不同获取时间的数据。 ### 剩余候选项目 以下是尚未实现的候选改进,不代表当前版本已支持,也不绑定具体版本或交付时间。实施时先明确行为与验收范围,再补对应测试。 以下顺序综合功能价值、实现成本及宿主接入风险;难度包含校验、冲突处理、回归测试和真实 Desktop 验收,不只是界面工作量。新功能继续遵循按需联网、先预览后写入、保留人工值及未知不等于零的约定。 ### 第一组:近期配置管理与试算 | 优先级 | 项目 | 难度 | 实施与验收要点 | | --- | --- | --- | --- | | 已实现,待真实宿主验收 | 批量核对、补全与价格变化预览 | 中高 | 已实现预览、字段选择、确认保存、有界宿主计划及部分失败重试;参数与价格各最多一次 mutation,不承诺跨命名空间事务。倍率按完整的同来源快照更新,历史共识参考与缺失已知价格项仍需单模型核对。继续验证真实 Desktop 与完整适配器;现有 fillPrices 的备用手动价语义保持。 | | 已实现价格参考入口,待真实宿主验收 | 记住已确认的来源映射 | 中 | 已支持精确价格参考的别名、确认、替换、清除、路由/目录变化失效及主动重新获取,独立保存于插件 sourceMappings。映射不证明中转站按参考价结算,不改变自动匹配及路由冲突保护;参数来源、集中管理和自动批量应用后续单独评估。 | | 高 | 模型与价格配置导入/导出 | 中 | 使用带格式版本的插件白名单 JSON,先支持 JSON 再评估其他格式;仅导出模型参数、价格及参考映射,不包含凭据或整个 profile。导入执行新写入限制、大小与数量限制、目标重新映射及冲突预览,不直接复用允许历史超限值的读取 schema。导入的来源信息标为未经重新验证,不冒充新获取的可信报价;覆盖未知值、零价、倍率快照及往返恢复。 | | 高 | 多模型对比与费用试算 | 中低 | 对比显示名、容量、模态、推理档与生效单价;用户输入假设用量,按四项单价试算并保留未知状态。币种分组,不默认换汇;仅在币种、计量单位和对应字段可比时展示配置价相对参考价的倍率,参考零价或缺失时不计算无意义比值,不将其称为多收费判断。 | | 中 | 参数/价格变化与陈旧度提示 | 中 | 手动检查保存值与最新来源差异,选择字段后更新;参数需补充来源及上次确认基准,价格区分来源时间与人工修改时间。陈旧只表示建议检查,不证明错误,也不自动覆盖手动价格或倍率基价。 | | 中 | 普通模型字段恢复默认 | 中 | 增加明确的“移除本地覆盖/恢复默认”操作,区分“留空保留原值”。先核对 Settings 对模型数组及继承值的语义,保留 revision、脱敏字段保护和 maxTokens 变化确认;删除显式模型字段与删除 modelOverrides 字段的回退来源不同。恢复后可能仍有宿主或上游输出上限,不能承诺无限输出。 | | 中 | 单项价格清除 | 中低到中 | 提供显式删除或恢复未知操作,保留“留空不修改”和明确零价的现有语义;区分直接单价与倍率参考,覆盖来源信息清理和重启恢复。 | | 中 | 外部配置变化提示 | 中 | 保留用户草稿的同时,提示当前模型或价格版本已经变化;区分无关配置与当前目标变化,继续拒绝过期写入,不自动覆盖或丢弃草稿。revision 冲突与来源陈旧度分别判断,不能互相替代。 | | 维护者手动验收 | 真实宿主验收 | 中 | 由维护者在发布阶段另行安排 DSH Desktop 与完整 llm-pi-ai 适配器的导入、覆盖、输出上限、保存及重连检查,记录具体宿主版本;不作为本轮兼容升级或自动发布的门禁。浏览器 fixture 和配置 schema 集成测试不能替代此验收。计量接入真实聊天前另验证流透传、取消、错误与插件卸载。 | ### 第二组:独立费用估算专项 独立费用估算具备候选宿主接口,先完成原型与真实 Desktop 验证,再决定发布范围;原生费用弹层接入单独评估。接口证据、计算口径及限制见 [费用接口核查与实施计划](cost-integration.md)。 | 阶段 | 范围 | 难度 | 必须满足的条件 | | --- | --- | --- | --- | | 原型 | 验证逐请求 usage 捕获、实际路由及会话归属 | 中高 | 验证 llm/stream 的监听范围、重试与辅助调用;sessionId 和进程内来源标记不能代替请求唯一标识。对计量错误隔离,真实流、原始异常、取消与关闭语义保持透传。 | | 首版 | 新请求、固定 token 单价、独立费用明细 | 高 | 从第一版起保存当次生效费率、币种、用量及完整性状态;缺失不当零,先逐请求计算再汇总,明确模型命名空间映射和统计覆盖范围。重试、失败与辅助调用逐次处理,不在模型流内等待记账 I/O。可先做实验性内存记录,但必须说明重启清空,不能称为持久历史账本。 | | 后续 | 持久记录、轮次/会话/日期统计与导出 | 高 | 使用独立运行数据存储,不逐请求重写 cordis.patch.yml;完成去重、恢复、保留策略及分支/子代理归属。旧日志缺少当时价格时,只能明确按指定价格回算;读取使用宿主支持的接口,避免启动时扫描全量日志。 | | 扩展 | 预算提醒、聊天内费用入口、复杂价格规则 | 高 | 基于稳定统计增加提醒;提醒不保证供应商侧绝不超支。优先验证独立聊天扩展入口,不直接替换原生 token 弹层。分时、长上下文阶梯、缓存写入档位及按次等收费另设计规则与迁移,不能压入四项固定单价。 | ### 第三组:数据源与诊断扩展 | 优先级 | 项目 | 难度 | 实施与验收要点 | | --- | --- | --- | --- | | 中 | OpenRouter 可选数据源 | 中 | 先面向实际 OpenRouter 路由,精确匹配 ID/变体并标注来源。核对 USD 每 token/每次等单位及条件价格;有额外收费或不支持规则时拒绝自动保存为固定价。上下文、输出上限与模态可作为建议,但支持 reasoning 参数不等于验证了具体档位;平台定价不能代表其他同名中转路由。[官方模型说明](https://openrouter.ai/docs/guides/overview/models)。 | | 中 | Ollama 本地模型信息读取 | 中;多后端高 | 先只读取用户指定的已配置服务与模型,核对模型能力、声明上下文及运行时设置差异,预览后写入。不开启局域网自动扫描,不把 stop 等当前白名单外字段直接写入;vLLM、LM Studio、LocalAI 等后端分别验证接口后再扩展。[Ollama 官方接口](https://github.com/ollama/ollama/blob/main/docs/api.md#show-model-information)。 | | 中 | 连接测试与专项能力检查 | 基础中;全面探测高 | 用户主动触发,说明测试可能计费;通过宿主服务使用已有凭据,不返回密钥。区分连接、首 token/总耗时及实际响应结果;小请求成功不能认证上下文、全部推理档、图片或工具能力,也不能把参数未报错视为已生效。按专项测试提供可取消、有限时及并发限制的结果。 | | 中 | 界面国际化 | 中 | 按宿主 locale 契约提取界面与服务错误文案,跟随宿主语言并提供缺失翻译回退;保留稳定错误码和来源数据。现有 locale 文件主要是插件元信息,不代表界面已经支持切换语言。可按英文用户需求提前。 | | 低/按需 | 官方模型家族扩展 | 中 | 核对目录真实 provider ID、精确模型候选和地域条目后,再扩展 moonshot、豆包、Llama、阶跃等家族;名称前缀不能单独证明官方来源。现有匹配已结合 API 主机名,新增规则继续覆盖官方权重、推理请求值来源和非官方同名候选,避免模糊匹配。 | | 暂缓 | 通用供应商预设 | 中高且需持续维护 | 先用用户保存的白名单配置方案解决迁移与复用;硬编码供应商端点、协议及模型组合易过期,也可能超出现有模型参数编辑范围。有明确需求后再设计预设版本、更新和保护规则,不自动写入凭据或覆盖原生供应商配置。 | ### 维护与暂缓项 | 优先级 | 项目 | 实施与验收要点 | | --- | --- | --- | | 低 | 缺协议地址的匹配兼容 | 先验证宿主是否接受无协议 baseURL、是否会自行规范化,再决定统一校验或仅对匹配提示作规范化。不得把无效路由误判为已验证可用,也不无条件补 HTTPS。 | | 低 | ETag/304 条件请求 | 先验证各目录端点及重定向后的响应头支持情况,再考虑 ETag/Last-Modified;覆盖首次下载、304 无缓存、内容变化、失败恢复和强制刷新语义,保留响应大小限制、并发复用和请求取消。 | | 低 | 客户端与发布包精简 | 评估 Zod Mini 或更细的导入方式,保持请求/响应校验、错误提示、类型与宿主模块工厂一致;分别测量压缩前后体积,不预设 100 KB 目标。评估移除包内非运行入口 JS 和 README 远程引用的截图,同时保留所需声明、宿主模块及第三方许可。 | | 低 | 编辑器状态与测试维护 | 按实际复杂度拆分价格草稿、保存请求和 Panel 状态逻辑,保留跨命名空间部分失败与并发保护;为关键规则增加独立测试,继续保留浏览器集成覆盖。 | | 低 | 文档与诊断一致性 | 补齐中英文 README 功能与致谢对应,发布前核对固定截图是否仍准确;细化供应商不存在/类型不支持的提示及中英文错误文案。用户界面保持简洁,完整校验诊断可另供排障使用。 | | 低/待验证 | 配置一致性与命名空间诊断 | 先核对适配器约定,再对 maxTokens 与 contextWindow 等组合提供有依据的提示,不把输出单价低于输入单价视为错误。模型命名空间误指插件自身可考虑提前给出诊断,但未证实为正常配置下的高优先级缺陷;保留现有读取与写入保护。 |