# DSH 信标

[English](README.md) | 中文

DSH 信标是一个可安装的 DeepSeek Harness bundle，用于监督并行会话。它在一个 package 中提供确定性活动投影、注意力排序、有界生成摘要、`/brief` 命令、可拖动活动信标、全局工作台和单会话 Context 视图。

可安装 npm package 位于仓库根目录，并拥有完整功能闭包。唯一的 Cordis Loader 行把 activity、brief、LLM provider 和 command 插件作为子 fiber 挂载，同时 package 只暴露一个 Web Client 入口。该结构不依赖尚未发布的 `@deepseek-ai/dsh-session-*` 包，并符合 DSH Client loader 每个 package 只允许一个来源的规则。

## 兼容性

| 组件 | 支持版本 |
| --- | --- |
| DeepSeek Harness packages | `>=0.1.2-alpha.6 <0.1.3` 中首个包含 `SessionEventIntent` 和 `session-brief` LLM purpose 的版本 |
| Cordis | `4.0.2` |
| Node.js | `^22.19.0` 或 `>=24.0.0` |
| React | `^18.2.0` |
| Document Picture-in-Picture | 当前 Chromium 浏览器；可选 |

DSH 处于开发者预览阶段，不承诺 prerelease 之间的 API 兼容性。因此 Beacon 将所有 DSH peer 限定在同一 prerelease 版本线；升级 DSH 时应同时升级 Beacon。

已经发布的 DSH `0.1.2-alpha.5` package 与 Beacon 不兼容：其 Session reader 要求树外事件携带 `ignorable` envelope marker，但公开的 `Session.append()` 实现无法持久化该 marker，LLM purpose 联合也不包含 `session-brief`。若针对 alpha.5 发布 Beacon，卸载或重启后可能无法读取相关会话。在 DSH 发布这两个 API 之前，不应把本 package 发布到 npm；发布后应把临时最低版本替换为确切发行版本，并验证全新安装。

## 安装

兼容 DSH 版本与本 npm package 发布后，把 bundle 加入 Web profile：

```sh
dsh plugin --profile web add @jingzechen/dsh-beacon
dsh --profile web --dump-config
dsh --profile web
```

配置转储中会出现 `@jingzechen/dsh-beacon` layer 和一个 `dsh-beacon` Loader 行。该 package 是 bundle，不是 profile；`dsh plugin` 会把它的 patch 加入所选 profile。

升级或卸载：

```sh
dsh plugin --profile web update @jingzechen/dsh-beacon
dsh plugin --profile web remove @jingzechen/dsh-beacon
```

卸载 bundle 会移除 profile 依赖和配置层。保存在 `dsh.session-overview.view.v1` 下的浏览器本地审阅偏好会继续存在，直至清除该站点数据。

## 配置

发布的 [`cordis.patch.yml`](cordis.patch.yml) 提供以下保守默认值：

| 字段 | 默认值 | 含义 |
| --- | ---: | --- |
| `sessionActivity.maxOpenTools` | `3` | 投影到会话摘要中的未配对工具名称上限 |
| `sessionActivity.maxErrorBytes` | `64` | provider-neutral 错误代码保留的 UTF-8 字节上限 |
| `sessionBrief.automaticTriggers` | `turn-end`、`goal-blocked`、`turn-error` | 可以自动生成摘要的稳定检查点 |
| `sessionBrief.minMeaningfulEvents` | `2` | 相对上一份已接受摘要所需的活动推进量 |
| `sessionBrief.maxBriefBytes` | `4096` | 完整已接受摘要的大小上限 |
| `sessionBrief.maxItemsPerField` | `8` | 已完成项、阻塞项和引用项上限 |
| `sessionBriefLlm.maxInputBytes` | `32768` | 精确 JSON 框架模型输入的大小上限 |
| `sessionBriefLlm.maxOutputTokens` | `512` | 辅助输出 token 上限 |
| `sessionBriefLlm.timeoutMs` | `30000` | 辅助请求的端到端 deadline |

profile patch 可以替换完整的 `dsh-beacon` 行来调整这些值。DSH patch 会替换整个 `config`，不会深度合并，因此必须重新写出所有必填字段。

如需把生成摘要固定到专用路由，请在 `sessionBriefLlm` 下同时提供 `provider` 和 `model`。两者均省略时，Beacon 使用会话最近记录的合格路由。两种路由都不存在时，摘要生成不可用，但确定性活动和 context 仍正常工作。

## 产品行为

全局工作台列出未归档顶层会话，排除子会话和来源为 subagent 的会话。排序依次为待批准、问题和计划审核，随后是阻塞、失败、运行中、排队、显式 Goal 完成、有变化、Goal 暂停和空闲。

所选会话视图从有界 DSH 投影中推导任务、当前重点、已完成 Todo、下一步、用户待处理项、来源和新鲜度。生成文本独立展示，绝不控制注意力排序。Agent 空闲、轮次正常结束和 Todo 完成均不表示 Goal 已完成。

Web UI 通过现有 DSH API 和权限检查支持打开、取消、归档、steering、置顶、稍后提醒、标记已查看、回答待处理交互和显式刷新摘要。

## 网络、模型与成本

浏览器插件不会为会话数据建立独立网络连接，而是使用 `web` profile 已配置的 DSH Web Client transport 和 controller service。

可选 brief provider 会通过已配置的 DSH LLM provider 发起一个有界辅助请求。该请求会消耗 token，并可能产生 provider 费用。系统会把准确路由、源序列号、所选事件序列号、耗时、结果和 provider 报告的 token usage 记录为会话元数据。生成摘要不会进入主 Agent 历史，也不会使其 KV cache 失效。

摘要输入可能包含有界的可见 user/assistant 文本、会话标题和 header 事实、Goal 和 Todo 状态、最新轮次结果、活跃工具名称以及上一份已接受摘要。默认排除 reasoning content、凭据、任意文件内容、原始工具参数和原始工具结果。

## 文件与权限访问

Beacon 不会直接读取任意 workspace 文件，也不会增加文件系统工具。activity 和 brief service 只读取 Host 进程中的会话日志与现有投影。Agent 执行的所有文件或工具访问仍受已安装 DSH provider、sandbox 和 approval policy 控制。

批准、问题和计划审核响应复用当前 DSH interaction 对象。Beacon 不增加批量批准、自动回答或第二套授权通道。

## 浏览器行为

可拖动活动信标是全局入口。悬停或聚焦预览最多显示 3 个待处理和 3 个运行中会话标题；分离的 Picture-in-Picture 视图最多显示 3 个合并活动行。

Document Picture-in-Picture 必须由用户显式点击触发。不支持的浏览器会隐藏该操作。来源 DSH 标签页必须保持打开和连接；分离窗口只包含有界活动视图，不包含完整工作台。

置顶、稍后提醒、书签、筛选器、信标位置和最后查看值都只存储在浏览器中。它们不会改变会话日志，也不会在浏览器 profile 或设备间同步。

## 从 GitHub 安装

Git dependency 得到的是源码，不是 npm 预构建 package 产物。仓库包含自包含的 `prepare` 脚本，但 pnpm 10 及更高版本要求用户在 profile 的 `pnpm-workspace.yaml` 中授权该安装时构建：

```yaml
allowBuilds:
  '@jingzechen/dsh-beacon': true
```

随后安装固定 commit；如果 pnpm 先要求授权，则授权后重复 add 命令：

```sh
dsh plugin --profile web add github:JingzeChen/dsh-beacon#<commit-sha>
```

`allowBuilds` 表示允许 package 在安装期间执行代码，应只对可信源码启用。更推荐 npm 分发，因为 npm package 会直接携带预构建的 `lib/index.js`、`lib/client.js`、类型声明和 `cordis.patch.yml`，无需安装时构建。

## 开发

```sh
pnpm install
pnpm run build
pnpm pack
```

`pnpm run build` 会生成 Host 代码、带内联 CSS Modules 的 DSH `window.__ModuleLoader__` Client bundle，以及 `lib/` 下的类型声明。`pnpm pack` 只包含 `package.json` 列出的文件。

## 许可证

[MIT](LICENSE)