dsh-session-sync 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.zh.md ADDED
@@ -0,0 +1,181 @@
1
+ # dsh-session-sync
2
+
3
+ <div align="center">
4
+
5
+ **DeepSeek Harness 的跨设备会话同步 —— 为你的会话存储建立专用 git 镜像。**
6
+
7
+ *在设备间同步会话,冲突时两边都保留,绝不丢失任何一轮。*
8
+
9
+ [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
10
+ [![DSH plugin](https://img.shields.io/badge/dsh-plugin-✅-green)](https://github.com/topics/dsh-plugin)
11
+ [![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-brightgreen.svg)](#)
12
+ [![CI](https://img.shields.io/github/actions/workflow/status/PerryLink/dsh-session-sync/ci.yml?branch=main&label=CI)](https://github.com/PerryLink/dsh-session-sync/actions)
13
+ [![Version](https://img.shields.io/github/v/tag/PerryLink/dsh-session-sync?label=version)](https://github.com/PerryLink/dsh-session-sync/releases)
14
+ [![npm version](https://img.shields.io/npm/v/dsh-session-sync)](https://www.npmjs.com/package/dsh-session-sync)
15
+ [![npm downloads](https://img.shields.io/npm/dm/dsh-session-sync)](https://www.npmjs.com/package/dsh-session-sync)
16
+
17
+ [English](README.md) · [简体中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
18
+
19
+ </div>
20
+
21
+ ---
22
+
23
+ ## 兼容性
24
+
25
+ | 项目 | 状态 |
26
+ |---|---|
27
+ | Harness | DeepSeek Harness `0.1.0-rc.6` |
28
+ | Node | `^22.19.0 \|\| >=24.0.0` |
29
+ | 平台 | 任何能运行 `git` 和 DSH 的环境(基于 git 镜像;无平台特定代码) |
30
+ | 模型 | 纯文本模型即可完整支持;无需视觉或额外模型能力 |
31
+
32
+ ## 你能得到什么
33
+
34
+ `dsh-session-sync` 把你的 DSH 会话存储镜像到一个专用 git 工作树,并同步到**你自己**控制的远端 —— 无云服务、无第三方存储:
35
+
36
+ - **`/sync` 命令** —— `status`(分支、脱敏后的远端、领先/落后、未提交文件、fork 文件)、`diff`、`log`、`pull`、`push`、`help`。
37
+ - **`sync_status` / `sync_pull` / `sync_push` 工具** —— 在轮次内为模型提供同样的能力。
38
+ - **append-only 冲突裁决** —— 会话日志是 append-only;任何分歧都会**两边都保留**(本地版本保留、远端版本留存为 fork 文件),绝不静默覆盖。分歧的会话还可在会话层面 fork。
39
+ - **自动模式** —— 启动时拉取、每个关闭轮次后推送、周期拉取,全部可配置且可逆。
40
+ - **写操作走确认门** —— `pull`/`push` 会先询问(经 `userQuestions` 或 `approval`);只读界面从不询问;没有回答者时操作失败关闭。
41
+
42
+ ```text
43
+ 设备 A 远端(你的 git 仓库) 设备 B
44
+ $DSH_HOME/sessions ──镜像──▶ 提交 ──推送──▶ [sessions] ──拉取──▶ 合并(两边保留 + fork)
45
+ ```
46
+
47
+ ## 快速开始
48
+
49
+ ```sh
50
+ # 1. 把 bundle 安装进你的 profile
51
+ dsh plugin --profile web add "github:PerryLink/dsh-session-sync#main"
52
+
53
+ # 或从 npm(已发布版本)
54
+ dsh plugin --profile web add dsh-session-sync
55
+
56
+ # 2. 指向一个私有 git 远端并核对挂载行
57
+ dsh --profile web --dump-config | grep -A2 'id: session-sync'
58
+ ```
59
+
60
+ 然后在你的 profile patch 里设置远端(基线应是**私有**仓库)并同步:
61
+
62
+ ```yaml
63
+ - insert:
64
+ - id: session-sync
65
+ name: dsh-session-sync
66
+ config:
67
+ remote: git@github.com:you/your-dsh-sessions.git
68
+ ```
69
+
70
+ ```
71
+ > /sync status
72
+ > /sync pull
73
+ > /sync push
74
+ ```
75
+
76
+ ## 安装与卸载
77
+
78
+ - **git 通道**(最新 `main`):`dsh plugin --profile web add "github:PerryLink/dsh-session-sync#main"`(等价于从 `git+https://github.com/PerryLink/dsh-session-sync.git` 安装)。无构建步骤 —— `index.mjs` 与 `lib/` 即发布产物。
79
+ - **npm 通道**(已发布版本):`dsh plugin --profile web add dsh-session-sync`。
80
+ - **tarball 通道**:在本仓库执行 `pnpm pack`,然后 `dsh plugin --profile web add ./dsh-session-sync-<version>.tgz`。
81
+ - **卸载**:`dsh plugin --profile web remove dsh-session-sync`(或从 profile patch 删除该行)。
82
+
83
+ ## 配置
84
+
85
+ 所有可调项都是 Schemastery `Config` 字段(可从 cordis.yml 覆盖)。按 id 的覆盖会替换整行 —— 重述你需要的每个键。`cordis.patch.yml` 对每个键都有行内注释。
86
+
87
+ | 键 | 默认值 | 含义 |
88
+ |---|---|---|
89
+ | `enabled` | `true` | 总开关;`false` 卸载命令、工具、监听器与自动模式 |
90
+ | `backend` | `git` | 同步后端;仅 `git` 已实现(加密后端为预留、配置即响亮失败) |
91
+ | `sessionRoot` | `''` | 会话存储根;空 = `$DSH_HOME/sessions`(两者皆缺加载失败) |
92
+ | `repoDir` | `''` | 同步工作树根;空 = `$DSH_HOME/dsh-session-sync/repo` |
93
+ | `remote` | `''` | 远端地址(pull/push 前必须非空;status/diff 无需) |
94
+ | `branch` | `main` | 远端分支名 |
95
+ | `gitBin` | `git` | git 可执行路径 |
96
+ | `autoPullOnStart` | `false` | 插件挂载时拉取一次(配置即授权,不再确认) |
97
+ | `autoPushOnTurnEnd` | `false` | 每个关闭轮次后推送 |
98
+ | `pullIntervalMinutes` | `0` | 每 N 分钟周期拉取(`0` = 关闭,最大 `10080`) |
99
+ | `confirmVia` | `auto` | 确认通道:`auto`(优先 userQuestions,其次 approval)、`userQuestions`、`approval` |
100
+ | `graceMs` | `10000` | git 终止宽限(毫秒) |
101
+ | `commandTimeoutMs` | `120000` | 单条命令超时(毫秒) |
102
+ | `maxOutputBytes` | `262144` | 单流收集输出上限(字节) |
103
+ | `commitName` | `dsh-session-sync` | 提交者名 |
104
+ | `commitEmail` | `dsh-session-sync@localhost` | 提交者邮箱 |
105
+ | `registerCommand` | `true` | 注册 `/sync` 命令 |
106
+ | `registerTools` | `true` | tools 服务存在时注册 `sync_*` 工具 |
107
+
108
+ 在你的 profile patch 中的覆盖示例:
109
+
110
+ ```yaml
111
+ - insert:
112
+ - id: session-sync
113
+ name: dsh-session-sync
114
+ config:
115
+ remote: git@github.com:you/your-dsh-sessions.git
116
+ branch: main
117
+ autoPushOnTurnEnd: true
118
+ pullIntervalMinutes: 30
119
+ confirmVia: userQuestions
120
+ ```
121
+
122
+ ## 工具与界面
123
+
124
+ | 界面 | 只读 | 需要确认 | 说明 |
125
+ |---|---|---|---|
126
+ | `/sync status` | ✅ | — | 分支、脱敏远端、领先/落后、未提交文件、fork 文件、最近推/拉 |
127
+ | `/sync diff` | ✅ | — | 未提交变更 + `HEAD..remote` 统计(只读) |
128
+ | `/sync log` | ✅ | — | 同步仓库最近提交 |
129
+ | `/sync pull` | | ✅ | fetch + 合并(两边保留语义;本地保留、远端留存为 fork) |
130
+ | `/sync push` | | ✅ | 镜像 + 提交 + 推送;绝不强推,被拒时拉取调和后重试一次 |
131
+ | `sync_status` | ✅ | — | 为模型提供 `/sync status` 同样的信息 |
132
+ | `sync_pull` | | ✅ | 模型可调用的拉取 |
133
+ | `sync_push` | | ✅ | 模型可调用的推送 |
134
+
135
+ ## 权限与数据
136
+
137
+ - **权限**:写操作走确认门(`confirmVia`);插件从不重新实现或绕过 harness 的 `userQuestions`/`approval` 服务。自动模式由配置授权覆盖,不再确认。
138
+ - **数据**:同步元数据(设备 id、最近推/拉、最近推送头、最近错误)存于 `session-sync` 存储领域。会话文件按不透明字节复制 —— 插件从不解析它们。设备 id 也写入同步仓库的 `device.txt`,用于跨设备 fork 归属。
139
+ - **会话日志**:`sync/push`、`sync/pull`、`sync/conflict` 在 `types.d.ts` 中声明;仅当宿主收录这些类型时才追加(见已知限制)。所有写入与展示的内容都经过脱敏。
140
+
141
+ ## 安全边界
142
+
143
+ - **绝不静默覆盖。** append-only 三分支合并在任何分歧时都保留两边;fork 文件永不被删除,git 绝不强推、reset、rebase 或切换分支。
144
+ - **路径收容。** 文件按不透明字节镜像、拒绝符号链接,每次路径拼接都做收容校验(`PATH_UNSAFE` 响亮失败)。
145
+ - **脱敏输出。** 远端 URL 凭据、令牌与 `key=value` 密钥在进入模型或日志前被打码;路径展示拒绝根外路径。
146
+ - **不存凭据。** 插件自身不存凭据;git 凭据由你常规的 git credential helper 管理。预留的端到端加密后端尚未实现,密钥绝不进入同步仓库。
147
+ - **git 加固。** git 以 `GIT_TERMINAL_PROMPT=0`、`GIT_OPTIONAL_LOCKS=0` 运行,带截止时间与信号边界,输出按流封顶。
148
+ - **失败关闭。** 缺少确认回答者、缺少远端或不安全路径都会响亮拒绝操作。
149
+
150
+ ## 已知限制
151
+
152
+ - **仅 git 后端。** 端到端加密后端(age/GPG 风格)为预留、尚未实现;配置它会响亮失败。在此之前,会话字节以未加密形式存放在**你的** git 远端 —— 请使用私有仓库。
153
+ - **依赖 git。** 插件需要 `git` 可执行文件与 `subprocess` 服务;没有它们时同步操作会给出明确原因失败(profile 仍可启动)。
154
+ - **`0.1.0-rc.6` 上的会话事件。** harness 尚未收录 `sync/*` 事件类型,因此 rc.6 上会话日志追加被跳过(会话仍可加载);宿主收录类型或支持 `ignorable` 信封后插件会自动开启。
155
+ - **轮次间的 `approval`。** `/sync` 在轮次之间运行,`approval` 通道没有开放轮次可挂靠;请对命令式同步使用 `confirmVia: userQuestions`,或在轮次内经工具驱动同步。
156
+
157
+ ## 开发
158
+
159
+ ```sh
160
+ pnpm install # node ^22.19 || >=24
161
+ pnpm run typecheck && pnpm run typecheck:ci # tsc --checkJs,针对已发布的 rc.6 peers
162
+ pnpm test # node --test(6 个套件;git 套件在无 git 时跳过)
163
+ pnpm run verify:self-contained # 依赖 spec 可从 registry 解析
164
+ pnpm run verify:artifacts # 发布文件齐全 + index.mjs 可 import
165
+ pnpm run check:readmes # 五语 README 一致性
166
+ pnpm pack # 发布 tarball
167
+ ```
168
+
169
+ 无构建步骤:纯 ESM,`index.mjs` 与 `lib/` 即发布产物。
170
+
171
+ ## Topics
172
+
173
+ `dsh`, `dsh-plugin`, `deepseek-harness`, `deepseek`, `cordis`, `session-sync`, `session`, `git`, `sync`, `cross-device`
174
+
175
+ ## 贡献者
176
+
177
+ - [@PerryLink](https://github.com/PerryLink) —— 创建者与维护者:git 镜像引擎、append-only 两边保留合并、`/sync` 命令与 `sync_*` 工具、自动模式、脱敏器与五语文档。
178
+
179
+ ## 许可证
180
+
181
+ [LICENSE](LICENSE) (Apache License 2.0) © 2026 dsh-session-sync contributors
package/SECURITY.md ADDED
@@ -0,0 +1,39 @@
1
+ # Security policy
2
+
3
+ ## Reporting a vulnerability
4
+
5
+ Please **do not** open a public issue for security vulnerabilities.
6
+
7
+ Report privately through GitHub's private vulnerability reporting:
8
+
9
+ **https://github.com/PerryLink/dsh-session-sync/security/advisories/new**
10
+
11
+ That flow keeps the report confidential while we triage, and it is the channel we watch first.
12
+
13
+ ## Before you report
14
+
15
+ - **Redact sensitive data** from any logs or `/sync` output you attach: tokens, API keys, secrets, Authorization/request headers, personal paths, and account identifiers. The plugin already redacts remote-URL credentials in its own output; still, do not paste a raw remote URL that embeds a password or token.
16
+ - Include, when possible: the plugin version, the harness (`dsh`) version, Node and OS versions, the remote type (git over https/ssh), and the minimal steps to reproduce.
17
+
18
+ ## What to expect
19
+
20
+ - **Acknowledgment**: within 5 business days.
21
+ - **Triage**: within 10 business days we confirm the issue and assess severity, or ask for more details.
22
+ - **Fix**: security fixes are prepared in a private fork, released as a patch version, and announced in the release notes.
23
+
24
+ ## Disclosure and credit
25
+
26
+ - We follow coordinated disclosure: a public advisory (and CVE request where appropriate) is published once a fix ships.
27
+ - Reporters are credited in the advisory unless they ask to remain anonymous. There is no bug bounty program at this time.
28
+
29
+ ## Scope
30
+
31
+ This plugin mirrors the DSH session store into a local git worktree and syncs it to a user-provided remote. Its own guarantees are:
32
+
33
+ - **Never silently overwrite.** The append-only three-way merge keeps both sides on any divergence; fork files are never deleted, and git never force-pushes, resets, rebases, or switches branches.
34
+ - **Bounded, sanitized output.** Remote-URL credentials, tokens, and `key=value` secrets are redacted before reaching the model or the log; path display refuses anything outside its root.
35
+ - **Path containment.** Session files are copied as opaque bytes with symlinks refused and every joined path containment-checked (`PATH_UNSAFE` fails loud).
36
+ - **No credential storage.** The plugin stores no credentials itself; git credentials live in the user's normal git credential helper. The reserved end-to-end-encryption backend is unimplemented and keys never enter the sync repository.
37
+ - **Git hardening.** Git runs with `GIT_TERMINAL_PROMPT=0` and `GIT_OPTIONAL_LOCKS=0`, deadline- and signal-bounded, with a per-stream output cap.
38
+
39
+ The security of the synced session data depends on the remote you configure: a private repository is the baseline, and the future encrypted backend is the path to encrypting session bytes before they leave the device. Vulnerabilities in the harness itself should be reported to the official harness maintainers instead.
@@ -0,0 +1,25 @@
1
+ # Third-party notices
2
+
3
+ `dsh-session-sync` bundles no third-party source code. All JavaScript in this
4
+ repository (`index.mjs` and `lib/`) is original work by the dsh-session-sync
5
+ contributors, licensed under Apache-2.0 (see `LICENSE`).
6
+
7
+ The package depends on the following software. None of it is bundled into the
8
+ published tarball; these are install-time dependencies:
9
+
10
+ | Package | Version range | License | Purpose |
11
+ |---|---|---|---|
12
+ | [zod](https://github.com/colinhacks/zod) | `^4.4.3` | MIT | Runtime schema for the `session-sync` storage-domain record (persistence-boundary validator) |
13
+ | [typescript](https://github.com/microsoft/TypeScript) | `^5.9.0` | Apache-2.0 | `tsc --checkJs` typecheck gate (`tsconfig.check.json`) |
14
+ | [@deepseek-ai/cordis](https://www.npmjs.com/package/@deepseek-ai/cordis) | `^4.0.1` (peer) | See package | The plugin runtime |
15
+ | [@deepseek-ai/schemastery](https://www.npmjs.com/package/@deepseek-ai/schemastery) | `^3.18.0` (peer) | See package | Configuration schema |
16
+ | `@deepseek-ai/dsh-*` peers | `0.1.0-rc.6` (peer) | See packages | Official harness seams (`dsh-session`, `dsh-storage-domain`, `dsh-tools`) |
17
+
18
+ Development-only dependencies (not shipped, used by tests and the typecheck
19
+ gate) add `@deepseek-ai/dsh-commands`, `@deepseek-ai/dsh-llm`, `@deepseek-ai/dsh-storage`,
20
+ `@deepseek-ai/dsh-storage-json`, `@deepseek-ai/dsh-subprocess`, `@deepseek-ai/dsh-user-approval`,
21
+ `@deepseek-ai/dsh-user-questions` at `0.1.0-rc.6`, and `@types/node`.
22
+
23
+ At runtime the plugin only talks to the harness services listed as
24
+ peerDependencies; it performs no network requests of its own — all network
25
+ traffic is `git` to the remote the user configures.
@@ -0,0 +1,41 @@
1
+ # dsh-session-sync bundle patch: mount the session-sync plugin.
2
+ #
3
+ # Every key below is a Config field (Schemastery schema); invalid values fail
4
+ # the profile load loudly. See README.md "Configuration" for the full table.
5
+ - insert:
6
+ - id: session-sync
7
+ name: dsh-session-sync
8
+ config:
9
+ enabled: true
10
+ # backend: git is the only implemented backend; 'git-age' etc. are
11
+ # reserved for the future end-to-end-encryption seam (fail loud today).
12
+ backend: git
13
+ # Root of the DSH session store to mirror ('' = $DSH_HOME/sessions).
14
+ sessionRoot: ''
15
+ # Local git worktree that mirrors sessionRoot ('' = $DSH_HOME/dsh-session-sync/repo).
16
+ repoDir: ''
17
+ # Required before any pull/push (status works without one).
18
+ remote: ''
19
+ branch: main
20
+ gitBin: git
21
+ # Auto modes: pull once when the plugin mounts; push after every
22
+ # closed turn; periodic pull every N minutes (0 = off). Auto runs are
23
+ # covered by the config grant and never re-confirm.
24
+ autoPullOnStart: false
25
+ autoPushOnTurnEnd: false
26
+ pullIntervalMinutes: 0
27
+ # Confirmation channel for /sync pull|push and the sync_* tools:
28
+ # auto (userQuestions first, then approval) · userQuestions · approval.
29
+ # Read-only surfaces (status/diff/log) never ask.
30
+ confirmVia: auto
31
+ # Subprocess tuning: grace period for git kills, per-command timeout,
32
+ # and the per-stream collected-output cap.
33
+ graceMs: 10000
34
+ commandTimeoutMs: 120000
35
+ maxOutputBytes: 262144
36
+ # Identity for commits created by the plugin.
37
+ commitName: dsh-session-sync
38
+ commitEmail: dsh-session-sync@localhost
39
+ # Surface switches: register the /sync command and the sync_* tools.
40
+ registerCommand: true
41
+ registerTools: true