photon-hq/dsh-imessage

用于 DeepSeek Harness 的 Photon iMessage

dsh-imessage 为 DeepSeek Harness Web 配置文件添加了一个由 Photon 托管的 iMessage 传输通道，以及一个 设置 → iMessage 页面。用户通过设备登录授权 Photon，保存其将用于发送短信的手机号码，并收到一个用于发送短信的托管 iMessage 号码。来自该确切路由的消息会成为 DSH 提示词，最终的 DSH 回答会通过 iMessage 发回。

初始兼容性目标为：

- DeepSeek Harness 0.1.0-rc.6
- Spectrum 12.7.x（该包目前锁定为 12.7.0）
- Node.js 22.19+ 或 24+

安装

安装稳定的 npm 包，然后从其 iMessage 会话应使用的工作区启动 DSH：

dsh plugin --profile web add dsh-imessage
dsh web

DSH 会将 plugin ... add 转发给配置文件包管理器。未限定的包名遵循 npm 的稳定 latest 通道；仅在有意测试某个预发布版本时才使用显式的预发布标签。

如果 DSH 通过 npx 运行，且 pnpm 未全局安装，请为安装命令同时提供这两个工具，而不更改全局环境：

npx --yes --package=pnpm@10.33.0 --package=@deepseek-ai/dsh \
-c 'dsh plugin --profile web add dsh-imessage'
npx --yes @deepseek-ai/dsh web

对于本地检出或打包构建：

npm ci --legacy-peer-deps
npm run build
npm pack
dsh plugin --profile web add ./dsh-imessage-*.tgz

打开 设置 → iMessage 并完成三张卡片：

1. 选择 授权。浏览器会立即打开一个空白窗口，然后在 DSH 收到设备代码后将其导航到 Photon。如果弹窗被阻止，请使用显示的链接和可复制的代码。
2. 输入你将用于发送短信的 E.164 号码，例如 +14155552671，并保存。
3. 复制或发送最后一张卡片中显示的已分配托管 iMessage 号码。

该插件始终确保存在一个名称恰好为 dsh 的 Photon 项目。它首先复用已存储的可访问项目，否则复用唯一的大小写完全匹配项，并且仅当不存在时才创建一个美国/iMessage 项目。多个完全匹配的项目或用户会连同其公共 ID 一并报告以供手动解决；该插件绝不会任意选择。

命令

普通文本会作为 DSH 提示词排队。对于确实以 / 开头的提示词，请使用 // 作为前缀，例如 //review this route。

| 命令 | 行为 |
|---|---|
| /help | 显示命令帮助。 |
| /new | 创建并选择一个新根会话。 |
| /sessions [page] | 列出同一工作区的根会话，默认每页五个。 |
| /switch  | 按索引、精确 ID 或唯一 ID 前缀选择列出的会话。 |
| /status | 显示活动会话及其状态。 |
| /stop 或 /cancel | 取消正在运行的轮次，并使仍在 iMessage FIFO 中等待的提示词失效。 |
| /approve  | 允许一个与 iMessage 轮次相关联的审批请求。 |
| /deny  | 拒绝一个相关联的审批请求。 |
| /answer   | 回答一个关联问题。逗号可选择多个编号选项。 |

当 iMessage 提示已排队/正在运行或有待处理的人工交互时，/new 和 /switch 会失败。请先发送 /stop。

新会话使用 dsh web 进程的工作目录、配置的默认 Agent Preset 以及当前默认模型。会话列表仅包含 cwd 与该工作目录完全匹配的根会话。子代理被排除在外。浏览器创建的活跃 Agent 可以被接管，但插件绝不会释放被接管的 Agent；它只释放自己创建或恢复的句柄。

路由与隐私边界

监听器仅接受满足以下所有条件的入站文本消息：

- 平台为 iMessage；
- 方向为入站；
- 空间为直接消息；
- 发送者等于配置的 E.164 号码；
- 路由为分配的托管线路：专用连接会公开并验证确切的收件人号码；共享连接由 Photon 按项目限定范围，并携带 Spectrum 的 shared 收件人哨兵值，因为提供商不公开入站收件人字段；
- 当提供商包含服务元数据时，服务为 iMessage。

未授权的流量会被忽略且不予回复。插件不会记录消息内容、原始电话号码、设备代码、访问令牌或项目机密。它会存储：

- 非机密的电话/用户/线路配置，位于 DSH 设置命名空间 dsh-imessage 中；
- 一个原子性的不透明凭据，位于 DSH_IMESSAGE_PHOTON_CREDENTIALS，包含管理令牌、公开账户/项目标识符以及 Spectrum 项目机密；
- 所选会话 ID 以及 dsh_imessage 存储域中一个有界的持久入站提供商消息 ID 窗口（1,024 条）。

浏览器仅接收公开的账户/项目/线路元数据、授权 URL 和用户代码、修订版本、健康状态以及凭据可用性标志。设备代码和令牌保留在主机上。Photon HTTP 调用被固定到一个配置的来源，并拒绝重定向或跨来源响应。

每条 iMessage 提示都通过其确切的 DSH UserMessage.id 进行关联，并且只有在 DSH 将该消息认领用于某一轮次后才归其所有。助手输出、审批和问题仅针对该已认领的轮次进行转发。同一被接管会话中源自浏览器的轮次仍保留在浏览器中。审批投递失败、监听器不健康、取消或超时都会以失败关闭方式处理。

仅投递最终助手答案。中间推理、工具活动和部分输出保留在 DSH 中。答案在投递前会从 markdown 转换为纯文本，因此格式标记不会以原始形式通过 iMessage 到达；围栏代码块和行内代码保留其确切内容。长答案会在段落、行或单词边界附近拆分，且不会拆分 Unicode 字素簇。在 DSH 轮次运行期间，Spectrum 输入状态保持活跃。

Photon 授权与资源
该插件直接通过 HTTPS 实现 Photon CLI 当前的 RFC 8628 设备流程；它不会启动 CLI 或读取 CLI 凭据文件。它目前使用 CLI 兼容值 client_id=photon-cli、作用域 openid profile email 以及标准设备代码授权。挂起、slow_down、HTTP 429、拒绝、过期和取消均被显式处理。

这个共享客户端 ID 是有意为之的兼容性例外。契约测试夹具固定到 Photon CLI 提交 13fb65a3f33e801cb50f7e7a240a8eb6466c4152，包括 src/commands/login.ts。如果 Photon 为此插件签发专用客户端 ID，请在更改生产流程之前，一并迁移常量和契约测试夹具。

自动用户预配会创建一个共享 Spectrum 用户，并禁用邀请。如果已存在完全匹配的电话用户，无论其分配是共享还是专用，插件都会复用它。如果共享容量不可用，设置会以 shared-line-unavailable 停止；请先与 Photon 配置/解析专用线路，然后重试。

对于共享分配，Photon 会在投递项目作用域流之前执行托管线路路由。Spectrum 12.7 将该路由表示为 space.phone = "shared"；因此，插件会验证精确配置的发送者、私信形态和 iMessage 服务，同时依赖 Photon 的项目边界来验证接收者。专用分配则继续根据精确分配的托管号码进行检查。

电话更换是非破坏性的。新的 Photon 用户和 Spectrum 连接会在本地设置切换之前准备好，如果准备失败，旧的可用监听器会保持活动。旧的 Photon 用户会被有意保留。

当管理令牌过期时，存储的项目密钥可以继续路由消息。设置会显示需要重新授权，并且在用户再次授权之前，项目/用户更改保持禁用。

断开连接仅在本地生效。 它会停止路由，并清除本地凭据、设置、活动会话选择和去重状态。它绝不会删除 Photon 项目、用户或托管线路资源。

限制

- 每个插件实例一个 Photon 账户、一个发送电话号码和一个分配的托管线路。
- v1 中仅支持纯文本直接 iMessage 对话。
- 出站答案为纯文本：Markdown 格式会被剥离，而代码块会原样保留。
- 附件、回应、群聊、SMS 和 RCS 会被忽略。
- 项目名称固定为精确字符串 dsh。
- 所有同一工作区根 DSH 会话对 /sessions 和 /switch 可见。
- 不会自动清理 Photon 云资源。

主机配置

默认值仅限主机使用，不会在设置页面中公开：

| 选项 | 默认值 |
|---|---:|
| photonApiOrigin | https://app.photon.codes |
| interactionTimeoutMs | 600000（10 分钟） |
| maxOutboundChars | 3500 个字素 |
| sessionsPerPage | 5 |
| dedupeEntries | 1024 |
| reconnectMinMs | 1000 |
| reconnectMaxMs | 60000 |

在 Web 配置文件的 cordis.patch.yml 中覆盖该 bundle 行。DSH 补丁覆盖会替换整行，因此请同时保留 id 和 name：

- id: dsh-imessage
name: dsh-imessage
config:
interactionTimeoutMs: 900000
maxOutboundChars: 3000

非 HTTPS 的 API 源会被拒绝，测试所用的回环 HTTP 除外。

故障排查

| 错误 | 操作 |
|---|---|
| invalid-phone | 输入 +、一个非零的国家代码数字，且总位数不超过 15 位。不要包含空格或标点符号。 |
| auth-expired / auth-denied | 重新开始授权，并在显示的过期时间之前完成授权。 |
| authorization-required | 重新授权 Photon；如果项目密钥仍然有效，当前路由可以继续。 |
| project-ambiguous | 在 Photon 中将除一个之外的所有完全匹配的 dsh 项目重命名，然后重试。 |
| user-ambiguous / user-resolution-required | 在 Photon 中解决重复/账户级别的电话号码归属问题，然后再次保存。 |
| shared-line-unavailable | 向 Photon 申请共享容量，或配置专用分配。 |
| credential-readonly / settings-readonly | 移除优先级更高的只读 DSH 覆盖。 |
| settings-conflict | 另一个窗口更改了设置；请刷新并重试。 |
| runtime-failed | 使用 Retry listener；如果问题重复出现，请在 Photon 中确认项目的 iMessage 平台和托管线路。 |

开发与验证

npm ci --legacy-peer-deps
npm test
npm run build
npm pack --dry-run
With an rc.6 dsh binary available:
DSH_BIN=/path/to/dsh npm run test:profile

测试套件涵盖设备流程退避/取消、密钥脱敏、项目/用户幂等性与歧义、分阶段电话号码替换、入口过滤器、持久重放去重、重连、Unicode 分块、精确轮次归属、审批/问题失败关闭行为、会话默认值/过滤/句柄归属，以及交互式设置 UI。CI 在 Node 22 和 24 上运行该测试套件、打包产物检查，以及一次性的 DSH Web 配置文件安装。

发布

发布工作流 委托给 BuildSpace 的单包 TypeScript 流水线。要发布，请在将拉取请求合并到 main 之前为其添加 release 标签。随后 BuildSpace 会确定语义化版本、生成发布说明、提交版本号变更、创建 GitHub Release、运行完整的包检查，并发布到 npm 的稳定 latest 渠道，附带来源证明。
对于预发布版本，同时应用 release 和 prerelease；BuildSpace 会将该版本发布到其预发布通道。未标记的合并会运行常规 CI，但不会发布。手动触发可以强制发布以进行恢复。BuildSpace 的 dry-run 仅跳过 npm 发布；当与强制发布结合使用时，它仍会创建版本提交和 GitHub Release，因此拉取请求 CI 是安全的验证路径。

该工作流通过 GitHub OIDC 使用 npm Trusted Publishing。不要仅为发布而添加长期有效的 NPM_TOKEN。它有意调用 BuildSpace main，因为不可变的 v1 工作流早于 OIDC 支持；一旦下一个不可变的 BuildSpace 标签包含 use-oidc，就迁移到该标签。

dsh-imessage 曾在 0.1.0-alpha.1 时进行过一次引导，然后通过 npm CLI 使用以下确切的 Trusted Publisher 值进行配置：

| 字段 | 值 |
|---|---|
| Provider | GitHub Actions |
| Organization | photon-hq |
| Repository | dsh-imessage |
| Workflow filename | publish-npm.yml |
| Environment | 留空 |
| Allowed action | npm publish |

可以通过 npm CLI 检查该配置：

npx --yes npm@11.19.0 trust list dsh-imessage

OIDC 发布已通过 alpha 版本验证，包括 npm 的 SLSA 来源证明。该包的发布访问权限设置为 Require two-factor authentication and disallow tokens，并且临时引导 CLI 会话随后已注销。

在兼容性目标提升之前，使用真实托管线路运行 Photon 暂存冒烟测试：授权，创建/复用 dsh，配置/复用发送者，发送入站提示，回答审批和问题，演练 /new、/sessions、/switch，停止/重启 DSH，确认重放去重，在令牌过期后重新授权，并在验证 Photon 项目/用户仍然存在的同时断开连接。

参考

- DeepSeek Harness
- DSH API gateway and generated Typert RPC
- Photon CLI authentication
- Spectrum TypeScript getting started
- Spectrum iMessage routing