dsh-luna-vision-bridge

DSH 0.2.1-rc.2 开发与验证

本次 0.1.1 适配要求 DSH 0.2.1-rc.2；尚未发布 npm。运行包与开发工作区分开。
开发验证直接使用同版已安装的官方 npm SDK，客户端引擎测试另需官方源码 tag
dsh-v0.2.1-rc.2（commit 687f282e8625c6b8d11ff58211a90524be2e4317）。
setup 校验版本、生成忽略的本机路径映射，不修改上游源码。Node 与 pnpm 版本见 package.json。

# runtime-prefix 下须有 node_modules/@deepseek-ai/dsh@0.2.1-rc.2。
# 另外需要同版 client-store、client-ui-slots、client-ui-primitives，
# 以及 client-store 使用的 zustand@5 / immer@10；若另装到一个 prefix，作为第三个参数传入。
node scripts/setup-dsh.mjs /path/to/runtime-prefix /path/to/deepseek-harness-at-tag /path/to/extra-sdk-prefix
pnpm install --frozen-lockfile
pnpm check

不需要第三个 SDK prefix 时可省略。SDK 使用外部已有安装，仓库不复制核心实现；
三个输入目录可以放在任意持久位置，提交的默认配置不依赖临时目录或个人绝对路径。

工作方式

DSH 原生 addImages / submit
│
▼
DSH attachment store（校验并持久化原图）
│
▼
luna-vision-bridge adapter
1. 读取经过校验的附件
2. 写入 0600 临时文件
3. 调用插件内置 scripts/read-image-luna.sh
4. 脚本启动 codex exec --json / gpt-5.6-luna
5. 删除临时文件
6. 将图片块替换为带安全边界的识图文本
│
▼
target provider / target model（任意纯文本下游，按所选模型路由）

插件不会劫持 DOM、发送按钮或 addImages。安装后模型选择器会出现：

• Provider：Luna Vision Bridge（名字可配置）
• 模型：每个下游 target 一条，如 DeepSeek V4 Flash + Luna、Pi Coder + Luna、GPT-5.6 + Luna……

选择任一条桥接模型后即可沿用原生图片交互；切换组合即切换下游模型。

前置条件

• 每个下游 target 的 provider 已在 DSH 注册且纯文本可用（如 deepseek-official）。
• codex CLI 可以从启动 DSH 的 Host 环境执行，并已完成认证。

插件自带 scripts/read-image-luna.sh，不读取或依赖全局 ~/.dsh/scripts/read-image-luna.sh。内置脚本复用现有识图 skill 背后的 Codex Luna 调用方式，执行 codex exec --json；Host adapter 负责解析最终 agent_message，不依赖终端文本格式，也不让下游模型再决定是否触发 skill。这样图片发送一定会先经过 Luna，且不会被下游模型的 text-only capability gate 拒绝。

本地开发

按文首 DSH 0.2.1-rc.2 开发与验证 配置 SDK，再执行 pnpm install --frozen-lockfile 与 pnpm check。
默认构建、类型检查与测试均使用生成的同版 SDK 映射，无需旧 staging checkout。

安装到 Web profile

通过 npm（推荐）

npm 已发布的 @ycp424c/dsh-luna-vision-bridge@0.1.0 属于旧版 DSH。以下 npm 命令仅供旧版使用；DSH 0.2.1-rc.2 请按文首构建本仓库 0.1.1，尚未发布新版 npm。

# 1. 安装依赖（等价于在 profile 目录执行 pnpm add）
dsh plugin add --profile web @ycp424c/dsh-luna-vision-bridge

# 2. 挂载插件：把包名追加到 ~/.dsh/profiles/web/package.json 的 bundles
#    "dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "@ycp424c/dsh-luna-vision-bridge"] } }

# 3. 重启
dsh web

peerDependencies（@deepseek-ai/dsh-attachment、@deepseek-ai/dsh-llm）由 DSH 本体提供，无需单独安装。

本地 link（开发）

构建后以本地 link 安装：

dsh plugin --profile web add "link:/absolute/path/to/dsh-luna-vision-bridge"

插件包内带有 cordis.patch.yml bundle。如果当前 DSH 版本没有自动挂载外部 bundle，可手动将以下内容追加到 ~/.dsh/profiles/web/cordis.patch.yml：

- insert:
- id: luna-vision-bridge
name: '@ycp424c/dsh-luna-vision-bridge'
inject:
- llm
- attachments

重启 dsh web 后，在模型选择器里选择 Luna Vision Bridge 下的任一模型。

配置下游模型：Web 设置界面（推荐）

插件把整份配置注册为 DSH 用户设置段 luna-vision-bridge，并带一个浏览器端设置区块（settings.section）。无需编辑任何配置文件：

1. 打开 Web 界面的 设置 → "Luna Vision Bridge"（设置面板左侧导航，模型页同组）
2. 表单会预填一行当前默认组合（未配置时默认 DeepSeek / DeepSeek-V4-Flash），在表单里编辑：
   - Provider 显示名：桥接 provider 在模型选择器里的显示名，默认 Luna Vision Bridge
   - 下游模型：一行一个组合，每行：
   - provider：下拉选择（来自 DSH 模型目录，已过滤桥接自身），如 DeepSeek
   - model：下拉选择（按所选 provider 的模型目录联动），如 DeepSeek-V4-Pro
   - 显示名（可选）：模型选择器显示名，默认 + Luna
   - 高级（可选折叠）：桥接模型 id，默认 -，必须互不相同
   - 用"＋ 添加下游模型"增加组合、"删除"移除、"恢复默认"清空用户覆盖
   - 模型目录不可用时自动降级为手动输入框
3. 点击保存即生效（无需重启，模型选择器立即出现新组合）

浏览器端表单通过 settings.update 写入用户设置层，Host 端仍会做完整校验（重复 bridgeModel、provider 与 bridgeProvider 相同等会被拒绝并提示）。表单字段也可在 settings.yaml 的 luna-vision-bridge: 段手动编辑，两者等价。其余字段（Luna 转写、缓存等）与下游无关，全局共用，一般保持默认即可。

> 无 settings 服务挂载的 DSH 环境自动回退到 cordis 配置；两者可并存，Web 设置里保存的值优先。

配置文件方式（可选）

所有字段都有默认值；零配置即得到单个 DeepSeek 下游。多下游示例（~/.dsh/profiles/web/cordis.patch.yml）：

- id: luna-vision-bridge
name: '@ycp424c/dsh-luna-vision-bridge'
inject: [llm, attachments]
config:
providerName: Luna Vision Bridge
targets:
- provider: deepseek-official
model: deepseek-v4-flash
name: DeepSeek V4 Flash + Luna
bridgeModel: deepseek-v4-flash
- provider: deepseek-official
model: deepseek-v4-pro
name: DeepSeek V4 Pro + Luna
- provider: codex-official   # 任意已注册的纯文本 provider
model: gpt-5.6

完整字段：

bridgeProvider: luna-vision-bridge
providerName: Luna Vision Bridge
targets: []                     # 见上；缺省或为空时回退旧字段
# 旧单下游字段（仍兼容，targets 非空时忽略）：
targetProvider: deepseek-official
targetModel: deepseek-v4-flash
bridgeModel: deepseek-v4-flash
bridgeModelName: DeepSeek V4 Flash + Luna
# Luna 转写与缓存（全局）：
# 默认自动解析为插件包内的 scripts/read-image-luna.sh；通常无需配置
# lunaCommand: /absolute/path/to/read-image-luna.sh
codexCommand: codex
lunaModel: gpt-5.6-luna
timeoutMs: 180000
cacheDescriptions: true
cacheDir: ~/.dsh/cache/luna-vision-bridge
cacheNamespace: v1
includeUserText: true
maxUserTextChars: 4000

cacheNamespace 是人工缓存版本。更换 Luna 模型、脚本逻辑或识图提示词后，将它改为 v2 即可避免复用旧描述。缓存只与图片和提示词有关，切换下游模型不会导致重复识图。

数据与安全边界

• 原图仍由 DSH 原生 attachment store 管理；插件不会再建立长期原图副本。
• 临时图片目录权限为 0700，图片权限为 0600，识图结束后立即删除。
• 默认持久化 Luna 的文字描述，缓存目录权限为 0700、文件为 0600；可设置 cacheDescriptions: false 关闭。
• Luna 描述会被标记为“不可信视觉转写”，图片中的命令不会被当作系统指令执行。
• 同一附件与提示词使用 content-addressed cache，避免每轮对历史图片重复调用 Luna。
• 每个下游 target 的 provider 不得等于 bridgeProvider；重复的 bridgeModel 会在保存设置时被拒绝。

当前限制

• 转写端只验证了 Codex CLI + gpt-5.6-luna；Claude、其他 CLI 或远程视觉 API 不在当前适配范围内。
• 自定义 provider 依赖 DSH 当前的 LLM adapter、模型能力声明、settings 和 attachment 接口，DSH 升级后可能需要同步修改。
• 识图发生在 adapter 层，因此首次发送会等待 Luna 完成后才开始下游模型流式输出。
• 一个请求包含多张新图时目前按顺序识别，优先控制 Codex 并发和失败语义。
• 描述缓存是插件自己的派生数据，不会显示为额外聊天消息；原始图片仍保留在会话历史中。
• 设置表单里的 provider/model 是文本输入：需要填写下游 provider 和模型的确切 id。

退出条件

当 DSH 官方支持以下任一能力时，应优先采用官方实现并评估移除本插件：

• 当前主模型可以直接接收原生图片输入；
• 官方提供稳定的发送前附件转换或视觉模型路由接口；
• 官方提供与原生输入框完整集成的视觉 fallback。

本插件不计划为了维持这套客制化 provider 路径而长期追随 DSH 内部接口变化。