deepseekplugins

DeepSeek Harness plugin

session-teleport

PostgreSQL-backed single-writer session handoff service for DeepSeek Harness

Memory
Jump to install

Source facts

Repository
omdsh-dev/session-teleport
Latest update
Aug 14, 2026
Category
Memory
GitHub stars
2
Format
plugin
Catalog evidence
Upstream dsh.bundle evidence
Evidence path
package.json#dsh.bundle
Checked against
0.1.0-rc.8
Upstream check date
2026-08-20

This evidence comes from the upstream catalog. This site has not installed, run, or security-reviewed the plugin.

Install

Start with a prompt that asks an agent to review the GitHub repository and source. Switch to the command if you want to install it yourself.

Copy this prompt into DSH, Codex, or another agent and ask it to review the GitHub repository and source first.

Do not install or run any commands yet. Read this plugin's GitHub repository, README, and relevant source code. Then answer the questions below clearly and directly so I can decide whether it fits my needs:

1. What is this plugin, and what problem does it solve?
2. Who is it for, and what are its typical use cases?
3. How is it used after installation? Include one minimal example.
4. What known limitations or privacy, security, compatibility, or maintenance risks does it have?
5. Give a clear recommendation: recommend, conditionally recommend, or do not recommend, with reasons.

Distinguish statements documented by the repository, inferences from source code, and unknowns. If evidence is insufficient, say so explicitly. Do not guess or simply repeat the README.

GitHub: https://github.com/omdsh-dev/session-teleport
Plugin: session-teleport
Author: omdsh-dev

Check the source files

Read the README and other files from this plugin directory before installing.

File explorer3 files
README.mdSource · read only

session-teleport

DeepSeek Harness 多设备 Session 接力插件。PostgreSQL 是唯一在线权威；同一时间只有一台设备持有写入凭据，移交后旧凭据立即被 writer_epoch 拒绝。

这是独立插件仓库，只分发 BSD-3-Clause 许可下的 Session Teleport 代码。 DSH peer packages 是外部依赖，保留各自许可，不在本仓库中复制、镜像或重新授权。 本包保留 private: true，避免本地发布演练误触 npm 发布；受支持的插件源是 https://github.com/omdsh-dev/session-teleport，安装时必须固定到完整 commit。

当前适配器使用 npm next 包做严格编译基线：@deepseek-ai/cordis@4.0.1-rc.4， 以及 @deepseek-ai/dsh-session、@deepseek-ai/dsh-session-persistence、 @deepseek-ai/dsh-session-persistence-jsonl 的 0.1.0-rc.6。这些精确版本只用于 开发和验证；安装时仍由目标 DSH 环境按 peerDependencies 提供兼容版本。

能做什么

  • 原样保存 JSON event envelope，包括扩展字段。
  • 在单个事务中校验 writer、revision、next seq 和连续事件序号。
  • 通过 idempotency key 与请求摘要安全重认“已提交但响应丢失”的重试。
  • 生成一次性、限时 handoff code；接管后旧 writer token 被 fencing。
  • 旧设备丢失时可由独立管理员凭据执行显式恢复接管，并审计每次 writer 变化。
  • 可对既有 Session 做无写入 dry-run、单事务导入和受约束的回滚切换。
  • 可从旧 DSH Profile 临时挂载只读 overlay，经 inspect() 抓取 Session，

不必手写 TypeScript，也不解析 JSONL/SQLite 物理文件。

  • 提供计划优先的 install / upgrade / uninstall / doctor 生命周期工具；

只接受完整 commit pin，结构校验失败会恢复旧依赖。

  • 提供一致快照、增量读取与 SSE 观察端点。
  • 提供 DSH PersistenceBackend adapter 和 profile bundle patch。
  • 将每个 Session 的 writer credential 保存为本机 0600 原子文件。
  • 在非 loopback 监听时强制配置服务 Bearer token。

架构

DSH device A ─┐
DSH device B ─┼─ HTTP/SSE Teleport service ─ PostgreSQL
observer     ─┘

客户端不直接连接 PostgreSQL。PostgreSQL 负责事务、行锁、CAS、writer fencing 和幂等记录；SSE 只是通知通道，客户端仍从权威表读取数据。

安装插件

首次安装从目标 commit 的本地 checkout 运行生命周期工具。默认只输出计划：

node dist/plugin-cli.js install --profile web --revision <full-commit-sha>
node dist/plugin-cli.js install --profile web --revision <full-commit-sha> \
  --apply --profile-stopped --cutover-safe

目标环境需要通过其正常、受支持的软件源解析匹配版本的 @deepseek-ai peer packages。本仓库不分发这些依赖，也不要求把软件源配置或访问凭据放入仓库。

为运行该 profile 的每台设备配置：

export DSH_TELEPORT_ENABLE=1
export DSH_TELEPORT_URL=https://teleport.example.com
export DSH_TELEPORT_API_TOKEN=a-long-random-service-token
export DSH_TELEPORT_DEVICE_ID=office-mac
# 可选：启动健康检查超时，默认 5000 毫秒
export DSH_TELEPORT_HEALTH_TIMEOUT_MS=5000

仅安装 bundle 不会切换 Session authority：默认仍使用 RC.6 自带 JSONL，Teleport adapter 保持禁用。先启动 Teleport 服务并验证 /health，再停止 profile、设置 DSH_TELEPORT_ENABLE=1 并重启，才会关闭 JSONL、启用 Teleport。显式启用后如果 服务不可达，profile 会拒绝启动，不会静默回退到另一份权威存储。

启用或停用会切换 Session authority，升级也会替换 profile 依赖。请先让正在写入的 turn 完成并停止对应 profile，再重启；不要把它当成对运行中 Session 无影响的热替换。 生命周期工具不会删除 PostgreSQL 数据或本机 writer 凭据。完整步骤见 [插件生命周期](docs/PLUGIN_LIFECYCLE.md) 和 [DSH 接入说明](docs/DSH_INTEGRATION.md)。

运行服务

需要 Node.js 22.19+ 和 PostgreSQL：

export NPM_TOKEN
pnpm install --frozen-lockfile --ignore-scripts
pnpm build

cp .env.example .env
set -a && source .env && set +a
pnpm start

服务默认监听 127.0.0.1:43127，启动时自动创建所需数据库表。从插件包安装后也可直接运行 dsh-teleport-server。

除 /health 外，请求需要：

Authorization: Bearer $TELEPORT_API_TOKEN

管理员恢复还需要与普通 API token 不同的 TELEPORT_ADMIN_TOKEN。

主要端点：

  • GET /v1/sessions
  • POST /v1/sessions
  • POST /v1/sessions/materialize
  • GET /v1/sessions/:id/head
  • GET /v1/sessions/:id?after=-1
  • GET /v1/sessions/:id/watch?after=-1
  • POST /v1/sessions/:id/append
  • POST /v1/sessions/:id/handoffs
  • POST /v1/handoffs/:code/accept
  • POST /v1/admin/sessions/:id/recover-writer
  • GET /v1/admin/sessions/:id/writer-audit
  • POST /v1/admin/sessions/:id/rollback-import

换机

先让旧设备上的当前 turn 完成，然后生成一次性码：

pnpm device create-handoff <session-id>

在新设备上设置不同的 DSH_TELEPORT_DEVICE_ID，再接受：

pnpm device accept-handoff <one-time-code>

旧设备丢失且无法生成移交码时，在目标设备上配置管理员凭据并执行显式恢复：

export DSH_TELEPORT_ADMIN_TOKEN=a-different-long-admin-token
export DSH_TELEPORT_ADMIN_ACTOR=operator-name
pnpm admin recover-writer <session-id> "lost device"
pnpm admin writer-audit <session-id>

恢复操作会原子增加 writer_epoch、保存新凭据并记录原因；它不是自动 lease，不会因短暂断网自行驱逐 writer。

导入既有 Session

先让旧 writer 完成当前 turn、flush 并停止对应 Profile。迁移工具会临时启动 这个 Profile，挂载一次性只读 overlay，并把一致 inspect() 结果写成 0600 bundle；它不修改旧 Profile 配置或旧存储，也不会覆盖已有输出文件：

dsh-teleport-import capture <source-profile> <session-id> <session.session-import.json>

然后依次运行：

dsh-teleport-import dry-run <session.session-import.json>
dsh-teleport-import apply <session.session-import.json>

导入不会修改旧存储。若切换后的只读 smoke check 失败，且 Teleport 尚未发生 新 append、handoff 或 recovery，可使用管理员令牌执行：

dsh-teleport-import rollback <session-id> "cutover smoke check failed"

一旦目标 head 或 writer epoch 前进，回滚会明确拒绝，避免切回旧前缀导致历史 丢失。完整边界见 [导入与可回滚切换](docs/IMPORT_AND_CUTOVER.md)。

开发与验证

export NPM_TOKEN
pnpm install --frozen-lockfile --ignore-scripts
pnpm check
pnpm audit --prod

只读 npm 令牌仅通过进程环境提供；仓库 .npmrc 只保存 ${NPM_TOKEN} 占位符， 发布包检查会拒绝把 .npmrc 打进产物。

仓库内的通用测试覆盖 authority 的 CAS/fencing/handoff/idempotency、HTTP API、schema 与 credential file。更多说明见 [测试边界](docs/TESTING.md)。

模拟测试不能替代物理双机、真实网络和 PostgreSQL 故障演练。候选版本应按 [真实设备验收](docs/REAL_DEVICE_ACCEPTANCE.md) 执行两机测试。

正确性边界

  • 当前版本是单写者接力与显式恢复，不是任意多写者自动合并。
  • 如果未来支持离线多写者，推荐把冲突保存为显式 branch，再 fast-forward 或人工

merge；不把两条对话和工具副作用自动穿插。设计边界见 [多写者分支策略](docs/MULTIWRITER.md)。

  • 并发 append 只有一个能推进 revision；其他请求明确冲突，不会静默拼接历史。
  • 本地 SQLite 可作为未来离线缓存；NAS/S3/MinIO 可作为未来快照或冷备，但不参与在线 head 竞争。
  • 多服务副本需要跨实例通知机制；通知只用于唤醒，不能代替 PostgreSQL 权威读取。
  • 尚未认证物理多主机网络、TLS/反向代理、PostgreSQL HA、长时间分区、PITR 恢复和持续负载。
  • 不直接解析或改写 JSONL/SQLite 物理文件；导入使用原后端读出的一致 portable snapshot。

事件列使用 PostgreSQL JSON 而不是 JSONB，以保留 event envelope 的序列化键顺序和无损往返。schema 会拒绝无法证明无损的旧格式迁移，避免静默改写历史。

License

BSD-3-Clause

Back to searchOpen GitHub repository

More related plugins

View category