LamplitIsles/dsh-companion

dsh-companion

@lamplitisles/dsh-companion 是 DeepSeek Harness（DSH）的一个小型、一对一的 Svelte 界面。它保留了 DSH 持久的 Workspace/Session 契约，并在 /companion/ 处添加了一个平静的聊天呈现。

该包从 LamplitIsles/dsh-companion 仓库发布为
公共 npm 包。其可选的语音集成由单独
安装的 Kepos Speech 插件提供。

安装与构建

本仓库使用 Bun：

bun install
bun run typecheck
bun run test
bun run build

可发布的包包含 Host 包、浏览器包、Cordis 补丁、声明文件以及本 README。要将本地构建安装到一次性或真实的 DSH 配置文件中，请将其打包并使用 DSH 的插件管理器：

bun run build
npm pack --pack-destination .
dsh plugin --profile web add ./lamplitisles-dsh-companion-0.1.0.tgz

该包固定到已发布的 DSH 0.1.2-rc.1 契约系列（Cordis 4.0.2）。它有意不作为其他 DSH 版本的兼容层。源自 Session 的行为读取 rc.1 快照 API；不支持更早的急切事件数组契约。

两个界面

- / 保持原版 DSH Web UI，包括高级导航、普通 Tool 视图、Kepos ImageGen 的 React 视图以及插件设置。
- /companion/ 选择优先级较低的 Companion 根。它显示一个已配置的 Workspace 和一个已记住/最近的 Session、人类与助手聊天、允许列表中的 ImageGen 图像，以及已定稿的 Kepos Speech 语音消息。一个小型 高级 DSH 链接通过整页导航返回 /，这样两种组合不会相互泄漏。

将 /compact 作为完整的 Companion 输入键入会调用 DSH 的 Session 命令通道，并保持连续性检查点不可见；其他以斜杠为前缀的文本仍为普通消息。

在回复期间发送的消息使用 DSH 持久的 FIFO 队列，并保持为独立的轮次。当草稿为空时，撰写器操作会停止当前回复而不清除已排队的消息；在取消完成后，DSH 会按顺序恢复这些消息。

普通发送的乐观回显、请求/RPC 身份模型、Session 到 Chat 的交接、失败恢复、图像所有权以及回归策略记录在 乐观消息发送与视觉连续性 中。

DSH 继续在内部流式传输并持久化模型输出，而 Companion 仅在其消息定稿后显示助手文本。输入气泡在等待 12 秒后会获得一条缓慢旋转、不重复的 companion 提示；停止或完成回复会清除该临时计时器状态。

当 ImageGen 运行时，其图像骨架和“正在画一张图…”状态会替换通用输入气泡。如果智能体在图像稳定后恢复文本生成，输入指示器会带着新的长等待计时器返回。
Companion 有意不包含 Workspace 选择器、会话列表/新聊天流程、模型或预设控件、权限/审批、推理、Trajectory、通用 Tool 卡片、提示注入检查、通用文件上传、通知或多联系人 UI。它通过 DSH 的 Session 附件契约支持图片消息，并在编辑器中提供一个简短的语音输入控件。

配置与恢复

在 / 上打开原生 DSH 插件设置页面并进行配置：

- 一个稳定的 Workspace id；
- Companion 和用户的显示名称；
- 每个身份可选的有界本地头像（PNG/JPEG/WebP/GIF，至多 5 MB，解码后尺寸至多 4096 px）；
- 用户偏好的称呼方式；以及
- 新关系或显式重置关系的默认好感度（整数 0–100）。

配置的 Workspace 通过 id 和实时 Session cwd 解析。缺失的 id、过期的 Session、打开失败、发送被拒或连接丢失都会显示为恢复状态；Companion 绝不会静默选择另一个 Workspace。设置卡片在写入被拒/冲突后保留暂存的编辑，并提供原生 Discard/Save 操作。编辑默认好感度不会重写已建立的关系。

心情、好感度和签名是 Host 拥有的状态，以仅追加记录的形式存储在配置的 Workspace 下 .dsh/dsh-companion/state.jsonl。每次成功变更都会添加一条带时间戳的完整状态；最新记录驱动 UI 和 Agent 上下文，而更早的备注和逐字段原因仍可作为关系历史使用。Session 日志不是运行时状态的权威来源。测试仅使用测试拥有的状态，绝不修改实时 Workspace。Host 会验证并限制每次加载和变更。Companion 仅向浏览器暴露一个只读的关系 RPC；agent 的 companion_update_relationship Tool 会原子性地更改心情、好感度或两者，而 companion_set_signature 独立更改其持久签名。companion_read_history 有意验证完整的有界 JSONL，并按最新优先返回 1–20 条近期记录，且不做变更；历史绝不会自动注入每一轮。所有三个 Tool 都保持隐藏在聊天时间线之外。跨字段和数值边界由 Host TypeScript 强制执行，而非面向 provider 的高级 JSON Schema。好感度变动在每个被接受的轮次中被限制为净 ±10，动态提示上下文是有界的描述性元数据——不是指令、权限或要最大化的分数。

仅对于该配置 Workspace 中的 Session，该包会将 DSH 基础压缩的最终指令替换为其固定的 companion 连续性检查点。其他 Session 和 LLM 调用保持不变。一个在其他方面符合条件但不再具有 DSH 基础压缩所期望最终消息的请求会显式失败，而不是将 companion 提示应用于未知后端；运行时指令是其措辞的唯一事实来源。
执行姿态固定为 workspace-write，且升级已禁用。需要更广泛权限的操作会失败；不会呈现任何审批或权限选择器。

媒体依赖

图像使用选定的 DSH Session 附件契约。仅投影助手结构化图像块以及成功/运行中/失败的 kepos_image_generate 结果；不相关的 Tool 输出会被隐藏。对象 URL 由页面持有，并在被替换或卸载时撤销。原装的 / ImageGen 渲染器保持不变。

语音行仅识别一个最终确定的 [[tts:text]]...[[/tts:text]] 段落（围栏代码以及格式错误/多个段落会被忽略；规范化文本限制为 240 个 Unicode 码点）。合成会使用实时 Session id，在 /kepos-speech 上调用已安装的 Kepos Speech synthesize RPC。返回的音频 URL 必须保持在同源的 /kepos-speech/audio/ 路由上。页面本地缓存按 Session 和规范化文本共享准备工作，播放需要用户激活，并且始终保留转录回退。当需要语音输出或输入时，请将 Kepos Speech 与 Companion 一起安装。

编辑器麦克风位于上下文容量圆圈的紧左侧。点击 开始录音 以请求麦克风访问权限，点击 结束录音 以停止；浏览器会在五分钟时自动停止，或在提供方的完整 data:;base64,... 载荷达到其 10 MiB 上限之前停止。确切的原始字节上限取决于规范化后发出的媒体类型（其前缀是该上限的一部分）。语音输入需要安全浏览器上下文、MediaRecorder、已安装的 Kepos Speech 插件的可选 keposSpeech.transcribe Host 能力，以及其共享的 DashScope 凭据（KEPOS_SPEECH_DASHSCOPE_API_KEY）。录音仅保留到足以通过 Companion 的已认证 Host RPC 发送其 Base64 字节，完成转录后即被丢弃：Companion 不写入任何 localStorage 条目、工作区文件、音频缓存、播放器、附件或提供方凭据。成功的转录会作为一次普通 Session 文本轮次提交，并带有前缀 🎙️ ；当 Kepos Speech 提供可识别的表情标签时，仅追加其原始方括号形式（例如 [sad]）。缺失或未知标签会被省略。该标记和方括号标签是模型可读的语音元数据，不是转录内容，也不是对说话者内心状态的断言。在显示 正在转写语音… 时，键入发送仍然可用，并且失败或空的尝试不会创建轮次。

主题与设备目标

DSH 的有效外观是唯一的主题权威：浅色映射到创作的 Sticker Messenger 调色板，深色映射到 Night Voyage。根节点在 theme/change 时就地更新；它不会写入第二个偏好设置，也不会重新挂载时间线。Tailwind Preflight 被省略，实用工具/组件带有前缀，并且 Companion 选择器以 #dsh-companion 为根，使 / 保持不变。
已提交的 fixture 和 Playwright 项目覆盖桌面以及 Pixel 7a 尺寸的 Chromium 几何参数（412×915 CSS px，DPR 2.625，移动端 UA/触摸），包括降低高度的 composer 行为、IME/换行处理、滚动锚定、覆盖层/返回、媒体状态、两种主题以及减少动态效果。这是一个 Pixel 7a 尺寸的 Chromium 行为声明，并非穷尽性的物理设备认证。

验证

本地验收命令如下：

bun run typecheck
bun run test
bunx playwright test --config=playwright.config.ts --workers=1
bun run pack:check
DSH_CLI=/absolute/path/to/dsh bun run test:dsh-link

pack:check 会构建并检查可发布的 tarball。test:dsh-link 使用显式提供的 rc.1 CLI，在测试专用的 DSH_HOME 中通过 file: 添加此源码树，然后验证组合后的 bundle 和客户端注册。它不会启动 DSH Web、浏览器，也不会触碰实时 profile。使用 just deploy-local 更新宿主机本地的已链接 web profile；打包或 Kosmos 部署以及生产切换仍不在本地验收范围内。

发布版本

发布由 .github/workflows/release.yml 通过 tag 门控。该工作流仅在
v tag 上运行，并在创建可发布 tarball 之前检查该 tag 是否与包
版本完全匹配。稳定 tag（如 v0.1.0）使用 npm 的 latest 通道；预发布
版本（如 v0.1.0-beta.1）使用 beta。

Tag 使用严格的 SemVer 预发布标识符：每个纯数字段要么是 0，要么没有
前导零（v1.2.3-0 有效，而 v1.2.3-01 和 v1.2.3-alpha.01 无效）。
包含字母的混合标识符（如 v1.2.3-alpha01）仍然有效，构建元数据（如
v1.2.3+build.1）也是如此。

首次引导与 Trusted Publishing

使用一个从未发布过的预发布版本引导该包。对于首次发布，将
package.json 设置为 0.1.0-beta.0，运行本地检查，然后使用维护者本地
npm 认证发布该确切的预发布版本一次：

bun install --frozen-lockfile
bun run typecheck
bun run test
bun run build
bun run pack:check
GITHUB_REF_NAME=v0.1.0-beta.0 bun run release:check
npm publish --access public --tag beta

此引导预发布版本有意区别于首个稳定版 0.1.0；切勿手动发布或将
0.1.0 复用于引导。每个 npm 版本在发布前都必须是新的且未发布过。

引导成功后，在 npm 中为确切的 @lamplitisles/dsh-companion 包配置
Trusted Publishing：添加 LamplitIsles GitHub 所有者、仓库
dsh-companion、工作流 .github/workflows/release.yml 以及环境 npm
作为受信任发布者。创建一个名为 npm 的受保护 GitHub 环境，并配置发布
审批所需的维护者或部署规则。

首次稳定版 OIDC 发布

推送预期的发布提交。支持的 tag 命令是
og tag [ | --bump ]（参见 og tag --help）；它
创建并推送标签。CI 在检查和发布之前，从该标签同步其一次性发布清单。使用以下命令创建第一个稳定标签：

og tag v0.1.0

验证作业必须先完成，受保护的发布作业才能发布。对于后续的每个版本，选择一个未发布的标签版本，推送预期的更改，并使用相同的受支持操作创建其标签（例如，og tag v0.2.0-beta.1）。稳定标签使用 npm 的 latest 通道；包含预发布标识符的标签使用 beta。

可信发布是唯一的自动化发布身份验证路径。不要将 NPM_TOKEN、NODE_AUTH_TOKEN 或提供商凭据添加到工作流中；受保护的发布作业会接收 OIDC 身份，并为经过验证的 tarball 记录 npm 来源。一次性引导发布仅使用维护者本地的 npm 身份验证。