dsh-session-sync 0.2.32 → 0.3.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.es.md ADDED
@@ -0,0 +1,455 @@
1
+ <div align="center">
2
+
3
+ <picture>
4
+ <source media="(prefers-color-scheme: dark)" srcset="docs/assets/dsh-session-sync-hero-en-dark.webp">
5
+ <img src="docs/assets/dsh-session-sync-hero-en-light.webp" width="100%" alt="dsh-session-sync: dos dispositivos copian $DSH_HOME/sessions como bytes opacos a un worktree git y lo sincronizan con un remoto propio; el pull hace un merge de tres vías por archivo que conserva ambos lados (la versión remota como archivo fork) y nunca hace force-push.">
6
+ </picture>
7
+
8
+ # dsh-session-sync
9
+
10
+ **Convierte tu almacén de sesiones en un repositorio git que tú controlas: sincroniza entre dispositivos, conserva ambos lados ante cualquier conflicto y no pierdas nunca un turno.**
11
+
12
+ Un plugin de sincronización puramente host-side para DeepSeek Harness: los archivos de sesión se copian como bytes opacos, la divergencia se resuelve con un merge de tres vías append-only y el remoto es tuyo (git en texto plano por defecto, cifrado age opcional) — sin servicio en la nube, sin almacenamiento de terceros.
13
+
14
+ [Instalar](#instalación-en-tres-pasos) · [Configuración](#configuración) · [FAQ](#faq) · [简体中文](README.md) · [English](README.en.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
15
+
16
+ [![License](https://img.shields.io/badge/license-Apache--2.0-3366CC?style=flat-square&labelColor=2B3245)](LICENSE)
17
+ [![DSH](https://img.shields.io/badge/DSH-%E2%89%A50.1.2%20%3C0.3.0-4B67B4?style=flat-square&labelColor=2B3245)](#compatibilidad)
18
+ [![npm](https://img.shields.io/npm/v/dsh-session-sync?style=flat-square&labelColor=2B3245&color=CB3837)](https://www.npmjs.com/package/dsh-session-sync)
19
+ [![CI](https://img.shields.io/github/actions/workflow/status/PerryLink/dsh-session-sync/ci.yml?branch=main&label=CI&style=flat-square&labelColor=2B3245)](https://github.com/PerryLink/dsh-session-sync/actions/workflows/ci.yml)
20
+ [![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24.9-339933?style=flat-square&labelColor=2B3245)](#compatibilidad)
21
+
22
+ [![Stars](https://img.shields.io/github/stars/PerryLink/dsh-session-sync?style=flat-square&labelColor=2B3245)](https://github.com/PerryLink/dsh-session-sync/stargazers)
23
+ [![npm downloads](https://img.shields.io/npm/dm/dsh-session-sync?style=flat-square&labelColor=2B3245&color=CB3837)](https://www.npmjs.com/package/dsh-session-sync)
24
+ [![dshfind](https://dshfind.com/api/badge/PerryLink/dsh-session-sync?metric=downloads)](https://dshfind.com/plugins/PerryLink/dsh-session-sync?ref=badge)
25
+ [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/PerryLink/dsh-session-sync/badge)](https://securityscorecards.dev/viewer/?uri=github.com/PerryLink/dsh-session-sync)
26
+ [![DSH Market](https://img.shields.io/badge/DSH_Market-listed-4B67B4?style=flat-square&labelColor=2B3245)](https://dsh.market/)
27
+ [![Gitee](https://img.shields.io/badge/Gitee-mirror-C71D23?style=flat-square&labelColor=2B3245&logo=gitee)](https://gitee.com/perrylink/dsh-session-sync)
28
+
29
+ ```sh
30
+ dsh plugin --profile <name> add dsh-session-sync
31
+ ```
32
+
33
+ </div>
34
+
35
+ <sub>Plugin de la comunidad, no afiliado a DeepSeek. Este es el único repositorio oficial, mantenido por PerryLink; los repositorios con el mismo nombre en otras cuentas no están afiliados. Gitee es un espejo.</sub>
36
+
37
+ ## Qué es
38
+
39
+ `dsh-session-sync` refleja el almacén de sesiones de DSH (`$DSH_HOME/sessions`) en un worktree git dedicado y lo sincroniza con un remoto que **tú** controlas: sin servicio en la nube, sin almacenamiento de terceros. Los archivos de sesión se copian como bytes opacos — el plugin nunca analiza JSONL/zstd, porque la codificación física pertenece al harness; su trabajo es mover esos bytes, fusionar historiales append-only y reportar el estado. Ante cualquier divergencia ejecuta un merge de tres vías append-only: **se conservan ambos lados**, la versión remota se preserva como archivos fork y nada se sobrescribe en silencio. `backend: git` (el valor por defecto) es un espejo en texto plano; `backend: encrypted` añade una capa age por encima; todos los modos automáticos son configurables y reversibles.
40
+
41
+ <p align="center">
42
+ <picture>
43
+ <source media="(prefers-color-scheme: dark)" srcset="docs/assets/dsh-session-sync-flow-v5-dark.svg">
44
+ <img src="docs/assets/dsh-session-sync-flow-v5-light.svg" width="100%" alt="Estructura de dsh-session-sync: el dispositivo A copia por bytes y confirma $DSH_HOME/sessions, y el push cruza la puerta de confirmación hacia tu remoto git; el dispositivo B hace fetch, ejecuta un merge de tres vías por archivo (base/ours/theirs) y restaura las sesiones localmente, conservando los bytes remotos divergentes como archivos fork en la ruta original; los archivos fork nunca se borran ni se sobrescriben.">
45
+ </picture>
46
+ </p>
47
+
48
+ ## Instalación en tres pasos
49
+
50
+ 1. **Instala** (elige un canal):
51
+
52
+ ```sh
53
+ # canal git (último main; equivalente a git+https://github.com/PerryLink/dsh-session-sync.git)
54
+ dsh plugin --profile web add github:PerryLink/dsh-session-sync
55
+ # canal npm (versiones publicadas)
56
+ dsh plugin --profile web add dsh-session-sync
57
+ # canal tarball: pnpm pack en este repo y luego
58
+ dsh plugin --profile web add ./dsh-session-sync-<version>.tgz
59
+ ```
60
+
61
+ Sin paso de build: `index.mjs` y `lib/` son los artefactos enviados.
62
+
63
+ 2. **Configuración mínima** (apunta a un remoto git **privado** en tu profile patch):
64
+
65
+ ```yaml
66
+ - insert:
67
+ - id: session-sync
68
+ name: dsh-session-sync
69
+ config:
70
+ remote: git@github.com:you/your-dsh-sessions.git
71
+ ```
72
+
73
+ 3. **Verifica que se monta**:
74
+
75
+ ```sh
76
+ dsh --profile web --dump-config | grep -A2 'id: session-sync'
77
+ ```
78
+
79
+ ```
80
+ > /sync status
81
+ > /sync pull
82
+ > /sync push
83
+ ```
84
+
85
+ **Desinstalar**: `dsh plugin --profile web remove dsh-session-sync` (o elimina la fila del profile patch).
86
+
87
+ ## Capacidades principales
88
+
89
+ `dsh-session-sync` convierte el almacén de sesiones en un espejo git versionado en el host y delega la acción de sincronización en tu remoto:
90
+
91
+ - **Comando `/sync`** — `status` (rama, remoto saneado, delante/detrás, archivos sucios, archivos fork), `diff`, `log`, `pull`, `push`, `help`.
92
+ - **Herramientas `sync_status` / `sync_pull` / `sync_push`** — la misma superficie para el modelo, dentro de un turno.
93
+ - **Resolución de conflictos append-only** — los registros de sesión son append-only; ante cualquier divergencia el plugin conserva **ambos** lados (la versión local se mantiene, la remota se preserva como archivos fork) y nunca sobrescribe en silencio. Las sesiones divergentes también pueden bifurcarse a nivel de sesión.
94
+ - **Modos automáticos** — pull al arrancar, push tras cada turno cerrado y pull periódico, todo configurable y reversible.
95
+ - **Escrituras con puerta de confirmación** — `pull`/`push` preguntan primero (mediante `userQuestions` o `approval`); las superficies de solo lectura nunca preguntan; sin respondedor la operación falla en cerrado.
96
+
97
+ ```text
98
+ dispositivo A remoto (tu repositorio git) dispositivo B
99
+ $DSH_HOME/sessions ──espejo──▶ commit ──push──▶ [sessions] ──pull──▶ merge (conservar ambos + fork)
100
+ ```
101
+
102
+ ### Comandos y herramientas
103
+
104
+ | Superficie | Solo lectura | Requiere confirmación | Notas |
105
+ |---|---|---|---|
106
+ | `/sync status` | ✅ | — | Rama, remoto saneado, delante/detrás, archivos sucios, archivos fork, último pull/push |
107
+ | `/sync diff` | ✅ | — | Cambios sin commit + estadística `HEAD..remote` (solo lectura) |
108
+ | `/sync log` | ✅ | — | Últimos commits del repositorio de sincronización |
109
+ | `/sync pull` | | ✅ | Fetch + merge con semántica de conservar ambos; lo local se conserva, lo remoto se preserva como forks |
110
+ | `/sync push` | | ✅ | Espejo + commit + push; nunca fuerza push, reconcilia y reintenta una vez ante rechazo |
111
+ | `sync_status` | ✅ | — | Los mismos datos que `/sync status` para el modelo |
112
+ | `sync_pull` | | ✅ | Pull invocable por el modelo |
113
+ | `sync_push` | | ✅ | Push invocable por el modelo |
114
+
115
+ ### Ejemplos
116
+
117
+ Estos son los puntos de entrada reales del plugin; instala una vez y llama a uno.
118
+
119
+ **Ejemplo detallado** — comando `/sync help`:
120
+
121
+ ```text
122
+ sync: usage — /sync [status | pull | push | diff | log | help]
123
+ status show mirror state (default): branch, remote, ahead/behind, dirty, forks
124
+ pull fetch + merge remote changes (keep-both; confirms first)
125
+ push mirror + commit + push local changes (confirms first)
126
+ diff uncommitted changes + HEAD..remote stat (read-only)
127
+ log last commits in the sync repository
128
+ ```
129
+
130
+ *Observed from `index.mjs:754-765 (registered /sync handler)`*
131
+
132
+ **Rama de fallo** — entrada `/sync push`:
133
+
134
+ ```text
135
+ sync: cancelled: approval requires an open turn; /sync commands run between turns — mount userQuestions or set confirmVia: userQuestions
136
+ ```
137
+
138
+ *Observed from `plugins/dsh-session-sync/lib/gate.mjs:134-137; plugins/dsh-session-sync/index.mjs:792-794; plugins/dsh-session-sync/test/gate.test.mjs:80-88; plugins/dsh-session-sync/README.md:246`*
139
+
140
+ **Ejemplos breves**: `/sync diff` · `/sync pull`
141
+
142
+ ## Configuración
143
+
144
+ Todos los ajustes son campos `Config` de Schemastery (modificables desde cordis.yml). Una sobreescritura dirigida por id reemplaza la fila entera — repite todas las claves que necesites. `cordis.patch.yml` documenta cada clave en línea.
145
+
146
+ Claves más usadas:
147
+
148
+ | Clave | Valor por defecto | Significado |
149
+ |---|---|---|
150
+ | `remote` | `''` | Dirección del remoto (obligatoria antes de pull/push; status/diff funcionan sin ella) |
151
+ | `backend` | `git` | Backend de sincronización: `git` (espejo en texto plano) o `encrypted` (contenido del espejo cifrado con age) |
152
+ | `sessionRoot` | `''` | Raíz del almacén de sesiones; vacío = `$DSH_HOME/sessions` (si faltan ambas, falla la carga) |
153
+ | `repoDir` | `''` | Raíz del worktree de sincronización; vacío = `$DSH_HOME/dsh-session-sync/repo` |
154
+ | `branch` | `main` | Nombre de la rama remota |
155
+ | `autoPushOnTurnEnd` | `false` | Push tras cada turno cerrado |
156
+ | `pullIntervalMinutes` | `0` | Pull periódico cada N minutos (`0` = apagado, máximo `10080`) |
157
+ | `cwdMap` | `[]` | Proyección de cwd en la restauración `[{from, to}]` (gana el prefijo más largo; los cwd multiplataforma sin coincidencia quedan en solo lectura bajo `<sessionRoot>/--unmapped--`) |
158
+ | `followSessionSymlinks` | `false` | Sigue enlaces simbólicos cuyo realpath permanece dentro de `sessionRoot` (diagnóstico para Android/proot) |
159
+ | `confirmVia` | `auto` | Canal de confirmación: `auto` (primero userQuestions, luego approval), `userQuestions`, `approval` |
160
+
161
+ <details>
162
+ <summary>Tabla de configuración completa (23 claves)</summary>
163
+
164
+ | Clave | Valor por defecto | Significado |
165
+ |---|---|---|
166
+ | `enabled` | `true` | Interruptor maestro; `false` desregistra el comando, las herramientas, los listeners y los modos automáticos |
167
+ | `backend` | `git` | Backend de sincronización: `git` (espejo en texto plano) o `encrypted` (contenido del espejo cifrado con age) |
168
+ | `sessionRoot` | `''` | Raíz del almacén de sesiones; vacío = `$DSH_HOME/sessions` (si faltan ambas, falla la carga) |
169
+ | `repoDir` | `''` | Raíz del worktree de sincronización; vacío = `$DSH_HOME/dsh-session-sync/repo` |
170
+ | `remote` | `''` | Dirección del remoto (obligatoria antes de pull/push; status/diff funcionan sin ella) |
171
+ | `branch` | `main` | Nombre de la rama remota |
172
+ | `gitBin` | `git` | Ruta del ejecutable git |
173
+ | `ageBin` | `age` | Ruta del ejecutable age (se sondea con `backend: encrypted`; si falta, degrada a texto plano) |
174
+ | `ageRecipient` | `''` | Destinatario age (clave pública o cadena de identidad); vacío = no puede cifrar, degrada a texto plano |
175
+ | `ageIdentity` | `''` | Ruta a una clave secreta age sin frase de contraseña para descifrar; vacío = no puede descifrar, degrada a texto plano |
176
+ | `autoPullOnStart` | `false` | Pull una vez al montar el plugin (la configuración es la autorización; no reconfirma) |
177
+ | `autoPushOnTurnEnd` | `false` | Push tras cada turno cerrado |
178
+ | `pullIntervalMinutes` | `0` | Pull periódico cada N minutos (`0` = apagado, máximo `10080`) |
179
+ | `cwdMap` | `[]` | Proyección de cwd en la restauración `[{from, to}]` (gana el prefijo más largo; los cwd multiplataforma sin coincidencia quedan en solo lectura bajo `<sessionRoot>/--unmapped--`) |
180
+ | `followSessionSymlinks` | `false` | Sigue enlaces simbólicos cuyo realpath permanece dentro de `sessionRoot` (diagnóstico para Android/proot) |
181
+ | `confirmVia` | `auto` | Canal de confirmación: `auto` (primero userQuestions, luego approval), `userQuestions`, `approval` |
182
+ | `graceMs` | `10000` | Margen de gracia para matar git (ms) |
183
+ | `commandTimeoutMs` | `120000` | Timeout por comando (ms) |
184
+ | `maxOutputBytes` | `262144` | Tope de salida recolectada por flujo (bytes) |
185
+ | `commitName` | `dsh-session-sync` | Nombre del autor del commit |
186
+ | `commitEmail` | `dsh-session-sync@localhost` | Correo del autor del commit |
187
+ | `registerCommand` | `true` | Registra el comando `/sync` |
188
+ | `registerTools` | `true` | Registra las herramientas `sync_*` cuando el servicio tools está presente |
189
+
190
+ </details>
191
+
192
+ Ejemplo de sobreescritura en tu profile patch:
193
+
194
+ ```yaml
195
+ - insert:
196
+ - id: session-sync
197
+ name: dsh-session-sync
198
+ config:
199
+ remote: git@github.com:you/your-dsh-sessions.git
200
+ branch: main
201
+ autoPushOnTurnEnd: true
202
+ pullIntervalMinutes: 30
203
+ confirmVia: userQuestions
204
+ ```
205
+
206
+ ## FAQ
207
+
208
+ <details>
209
+ <summary>¿Dónde viven realmente los datos? ¿Se sube algo a la nube?</summary>
210
+
211
+ No hay servicio en la nube ni almacenamiento de terceros. En tu máquina quedan dos copias: `$DSH_HOME/sessions` (el almacén de sesiones del harness) y el worktree `repoDir` que configures (por defecto `$DSH_HOME/dsh-session-sync/repo`); el remoto es **tu propio** repositorio git. `backend: encrypted` solo convierte la copia enviada/remota en texto cifrado age — el espejo local sigue en texto plano.
212
+
213
+ </details>
214
+
215
+ <details>
216
+ <summary>¿Un conflicto puede sobrescribir o perder una sesión?</summary>
217
+
218
+ Nada se sobrescribe en silencio. Los registros de sesión son append-only y el merge de tres vías conserva ambos lados ante cualquier divergencia: la versión local se mantiene y la remota se preserva como archivo fork llamado `<basename>.remote-fork-<marca UTC de 14 dígitos>-<device8>`; los archivos fork nunca se eliminan ni se sobrescriben, y git nunca fuerza push, resetea, rebase ni cambia de rama. Una sesión divergente también se bifurca a nivel de sesión, con un aviso persistente inyectado en la hija.
219
+
220
+ </details>
221
+
222
+ <details>
223
+ <summary>¿El cifrado está activado por defecto? ¿Qué pasa si falta age?</summary>
224
+
225
+ No: el valor por defecto es `backend: git`, así que los bytes de sesión quedan sin cifrar en tu remoto — usa un repositorio privado. `backend: encrypted` necesita `age` y `ageRecipient`/`ageIdentity` no vacíos; si falta algo, el plugin avisa explícitamente y cae a git en texto plano — nunca finge cifrar. Revisa el aviso en `/sync status` antes de confiar en el remoto como cifrado.
226
+
227
+ </details>
228
+
229
+ <details>
230
+ <summary>¿Qué pasa sin git o sin respondedor de confirmación?</summary>
231
+
232
+ Sin el ejecutable `git` o el servicio `subprocess`, las operaciones de sincronización fallan con un motivo claro (los perfiles siguen arrancando). `/sync` se ejecuta entre turnos, donde el canal `approval` no tiene un turno abierto al que adjuntarse: usa `confirmVia: userQuestions`, o impulsa la sincronización mediante las herramientas `sync_*` dentro de un turno; sin ningún respondedor la operación falla en cerrado.
233
+
234
+ </details>
235
+
236
+ <details>
237
+ <summary>¿Cuánta sobrecarga hay? ¿Los modos automáticos se ejecutan siempre?</summary>
238
+
239
+ Los archivos de sesión se copian como bytes opacos y nunca se analizan; cada comando git tiene timeout, margen de terminación y tope de salida por flujo. El push automático está apagado por defecto, el pull periódico está apagado por defecto (`pullIntervalMinutes: 0`) y el pull al arrancar está apagado por defecto — una vez activados quedan cubiertos por la autorización de configuración y no reconfirman. El coste depende del tamaño del almacén de sesiones y de la latencia del remoto; este repositorio no tiene datos de benchmark, así que no damos cifras inventadas.
240
+
241
+ </details>
242
+
243
+ ## Límites de seguridad
244
+
245
+ - **Nunca sobrescribe en silencio.** El merge de tres vías append-only conserva ambos lados ante cualquier divergencia, incluido delete/modify (los bytes modificados se conservan, la intención de borrado se respeta); los archivos fork nunca se eliminan y git nunca fuerza push, resetea, rebase ni cambia de rama.
246
+ - **Contención de rutas.** Los archivos se reflejan como bytes opacos con enlaces simbólicos rechazados y cada ruta unida se comprueba por contención (`PATH_UNSAFE` falla alto).
247
+ - **Salida saneada.** Las credenciales de URL remota, los tokens y los secretos `key=value` se redactan antes de llegar al modelo o al registro; la visualización de rutas rechaza todo lo que esté fuera de su raíz.
248
+ - **Sin almacenamiento de credenciales.** El plugin no almacena credenciales; las credenciales de git viven en tu helper de credenciales normal. Las identidades/destinatarios age los gestionas tú, y las claves nunca entran en el repositorio de sincronización.
249
+ - **Endurecimiento de git.** git se ejecuta con `GIT_TERMINAL_PROMPT=0` y `GIT_OPTIONAL_LOCKS=0`, acotado por plazo y señal, con un límite de salida por flujo.
250
+ - **Falla cerrada.** La falta de respondedor de confirmación, de remoto o una ruta insegura rechaza la operación alto.
251
+
252
+ ## Permisos y datos
253
+
254
+ - **Permisos**: las operaciones mutadoras cruzan la puerta de confirmación (`confirmVia`); el plugin nunca reimplementa ni elude los servicios `userQuestions`/`approval` del harness. Los modos automáticos están cubiertos por la autorización de configuración y nunca reconfirman.
255
+ - **Datos**: los metadatos de sincronización (id de dispositivo, último pull/push, última cabecera de push, último error) viven en el dominio de almacenamiento `session-sync`. Los archivos de sesión se copian como bytes opacos — el plugin nunca los analiza. El id de dispositivo también se escribe en `device.txt` en el repositorio de sincronización para la atribución de forks entre dispositivos.
256
+ - **Registro de sesión**: `sync/push`, `sync/pull` y `sync/conflict` están declarados en `types.d.ts`; se anexan solo cuando el host registra los tipos (ver Limitaciones conocidas). Todo lo escrito o mostrado se sanea. El único mensaje duradero que el plugin escribe —el aviso de fork por conflicto— lleva el source kind propio del plugin (producer-owned, `dsh-session-sync`); el harness retiró el kind compartido `plugin` y lo rechaza al releer una sesión.
257
+
258
+ ## Cifrado y modelo de amenazas
259
+
260
+ `backend: encrypted` añade una capa **age** opcional sobre el espejo: los bytes de sesión se cifran en archivos `encrypted/**/*.age` antes de commitear y subir, y se descifran de vuelta al espejo local en texto plano antes de fusionar. El merge a tres bandas siempre se ejecuta en texto plano localmente, por lo que la semántica append-only de conservar ambos lados no cambia.
261
+
262
+ Qué **protege** el cifrado:
263
+
264
+ - **El contenido del espejo en reposo en el remoto.** Los archivos de sesión que subes son texto cifrado age; el host remoto, sus operadores y cualquiera que clone el repositorio no ven los bytes de sesión en claro sin la clave privada.
265
+
266
+ Qué **no** protege (la frontera):
267
+
268
+ - **Las claves e identidades age son tuyas.** Los archivos de destinatario/identidad nunca son distribuidos, almacenados ni rotados por el plugin. Si una clave se filtra, el contenido del espejo que protege queda expuesto. Usa una identidad sin frase de contraseña y mantenla fuera del repositorio.
269
+ - **El remoto sigue siendo en la práctica un repositorio privado.** Los metadatos de git — mensajes de commit, el `.gitignore`, la estructura de rutas `encrypted/`, los nombres de rama y la actividad de push/fetch — siguen siendo visibles para el host remoto. El cifrado oculta el *contenido*, no el hecho de que sincronizas, ni la forma de tu árbol de sesiones.
270
+ - **El texto plano sigue existiendo localmente.** El espejo en `<repoDir>/sessions/` es texto plano en disco; el cifrado protege la copia transmitida/remota, no el cifrado del disco local ni el almacén de sesiones en vivo.
271
+ - **La degradación elegante significa texto plano.** Con `backend: encrypted`, si falta `age`, o `ageRecipient`/`ageIdentity` están vacíos, el plugin cae al camino git en texto plano **y avisa explícitamente** en el estado/registro — nunca finge cifrar. Revisa la advertencia en `/sync status` antes de confiar en el remoto como cifrado.
272
+
273
+ Línea base: con `backend: git` (el predeterminado), los bytes de sesión se almacenan sin cifrar en **tu** remoto git — usa un repositorio privado.
274
+
275
+ ### Sesiones multiplataforma y proyección de cwd
276
+
277
+ Una sesión de Windows sincronizada en Linux (o al revés) lleva un `header.cwd` que no es una ruta absoluta nativa en el host receptor: `dsh-workspace` indexa las sesiones con `realpath(header.cwd)`, y `session-persistence-jsonl` ni siquiera puede analizar un header cuyo cwd no sea absoluto nativo. Asigna el prefijo de origen a una ruta local:
278
+
279
+ ```yaml
280
+ cwdMap:
281
+ - from: 'C:\Users\me'
282
+ to: /home/me/win
283
+ ```
284
+
285
+ - Gana el prefijo más largo y los prefijos deben terminar en un límite de segmento (`C:\Users\me2` no coincide con `C:\Users\me`).
286
+ - La restauración solo proyecta la **copia local**: su primer frame lleva el cwd local y aterriza en el directorio de proyecto del host, así la sesión aparece en la lista de workspaces. El espejo conserva los bytes del dispositivo de origen; un push vuelve a enganchar el frame de cabecera original, de modo que el otro dispositivo sigue viendo appends idénticos byte a byte y nunca recibe conflictos sin sentido.
287
+ - Un cwd multiplataforma sin entrada cae en `<sessionRoot>/--unmapped--`: **visible pero de solo lectura** (`sync_status` lo informa como `cwdUnmapped` y las ediciones locales nunca se suben). Añade una entrada `cwdMap` y vuelve a hacer pull para convertirlo en una sesión local continuable.
288
+
289
+ ### Enlaces simbólicos (Android/proot)
290
+
291
+ El espejo **nunca sigue enlaces simbólicos** por defecto (límite de seguridad). El `link2symlink` de Android/proot informa los archivos de sesión escritos por el host como enlaces simbólicos (`readdir` dice enlace, `readlink` está vacío, los bytes son legibles), así que las sesiones propias del teléfono nunca llegan al espejo. Diagnóstico y seguimiento opcional:
292
+
293
+ - `sync_status` informa `skippedSymlinks` / `skippedSymlinkPaths` (recuento y muestras de rutas) y `followedSymlinks`; el resultado de push lleva el mismo aviso.
294
+ - `followSessionSymlinks: true` (por defecto `false`) sigue solo los enlaces cuyo `realpath` permanece dentro de `sessionRoot`; los enlaces que escapan siempre se omiten y se cuentan.
295
+
296
+ ## Limitaciones conocidas
297
+
298
+ - **El cifrado es opcional y age es una dependencia externa.** `backend: encrypted` añade una capa age (ver «Cifrado y modelo de amenazas» arriba); si falta `age` o `ageRecipient`/`ageIdentity` están vacíos, avisa explícitamente y cae a texto plano, y una identidad protegida con frase de contraseña no se puede usar (el descifrado bloquearía en un prompt TTY, así que falla en cerrado). Con `backend: git` (el predeterminado), los bytes de sesión se almacenan sin cifrar en **tu** remoto git — usa un repositorio privado.
299
+ - **`object-storage` es una interfaz reservada.** Es un marcador de posición de interfaz y falla alto al cargar; solo `git` y `encrypted` están implementados.
300
+ - **Se requiere git.** El plugin necesita el ejecutable `git` y el servicio `subprocess`; sin ellos, las operaciones de sincronización fallan con un motivo claro (los perfiles siguen arrancando).
301
+ - **Un `repoDir` por backend.** Cambiar entre `git` y `encrypted` sobre el mismo `repoDir` no está soportado; usa un worktree nuevo por backend.
302
+ - **Eventos de sesión en `0.1.0-rc.6`/`0.1.0-rc.8`/`0.1.1-rc.2`/`0.1.2-alpha.2`/`0.1.2-alpha.3`/`0.1.2-rc.1`/`0.1.7-alpha.2`.** El harness no registra los tipos `sync/*`, por lo que los anexos al registro de sesión se omiten (las sesiones siguen cargando); el plugin los habilita automáticamente una vez que un host registra los tipos o expone el envoltorio `ignorable` en `Session.append`.
303
+ - **`approval` entre turnos.** `/sync` se ejecuta entre turnos, donde el canal `approval` no tiene un turno abierto al que adjuntarse; usa `confirmVia: userQuestions` para la sincronización por comando, o impulsa la sincronización mediante las herramientas dentro de un turno. La comprobación de turno abierto lee la proyección de sesión `turnBoundary` del host: una composición sin `@deepseek-ai/dsh-session-projection` no puede verificar el estado del turno y falla en cerrado con ese motivo.
304
+ - **Los artefactos privados del host no se sincronizan.** `session.lock` (el arriendo de sesión del harness) y los archivos de staging `session.migration.*.tmp` nunca se reflejan ni se eliminan: son estado de ejecución, no contenido sincronizable. Los registros de sesión (`session.jsonl`, `session.v[1-9]*.jsonl[.zstd]`) siguen siendo la carga útil reflejada.
305
+
306
+ ## Compatibilidad
307
+
308
+ | Superficie | Estado |
309
+ |---|---|
310
+ | Harness | DeepSeek Harness `dsh-v0.2.1-alpha.1` (tag de GitHub, verificado el 2026-09-25: cadena completa de puertas contra los peers fijados `0.1.7-rc.2`). Línea de dependencia npm `0.1.7-rc.2`, peers `>=0.1.2-rc.1 <0.2.0 \|\| >=0.1.5-alpha.1 <0.2.0 \|\| >=0.1.6-0 <0.2.0 \|\| >=0.1.7-0 <0.2.0`. (adaptado el 2026-10-04): el aviso de fork por conflicto lleva el source kind propio del plugin (producer-owned) — el harness retiró el kind compartido `plugin` y lo rechaza al releer. |
311
+ | Node | `^22.19.0 \|\| >=24.9.0` |
312
+ | Plataformas | Dondequiera que corran `git` y DSH (espejo basado en git; sin código específico de plataforma) |
313
+ | Modelo | Modelos solo de texto totalmente soportados; no se requiere visión ni capacidad extra de modelo |
314
+
315
+ ## Ecosistema y calidad
316
+
317
+ - [Espejo en Gitee](https://gitee.com/perrylink/dsh-session-sync) (espejo sincronizado; GitHub es canónico)
318
+ - [Página de dshfind](https://dshfind.com/plugins/PerryLink/dsh-session-sync) (instalaciones y ranking)
319
+ - [Informe OpenSSF Scorecard](https://securityscorecards.dev/viewer/?uri=github.com/PerryLink/dsh-session-sync) (impulsado por [.github/workflows/scorecard.yml](.github/workflows/scorecard.yml))
320
+ - [Informe de verificación de dsh-plugin-doctor](https://github.com/PerryLink/dsh-plugin-doctor#verified-徽章) (insignia histórica de verificación K10–K13)
321
+ - [DSH Market](https://dsh.market/) (listado)
322
+ - **Canal de la tienda 1024**: ejecuta `npm i -g dsh1024` una vez y luego `dsh1024 plugin --profile web add dsh-session-sync` (cuenta para el ranking de instalaciones de [deepseek1024.com](https://deepseek1024.com))
323
+ - [Base de conocimiento del ecosistema](https://perrylink.github.io/dsh-plugin-guide/): guía de desarrollo de plugins · datos medidos de selección · criterios de mantenimiento
324
+
325
+ ## Desarrollo
326
+
327
+ ```sh
328
+ pnpm install # node ^22.19 || >=24.9
329
+ pnpm run typecheck && pnpm run typecheck:ci # tsc --checkJs: cara del checkout + cara de la línea publicada
330
+ pnpm test # node --test (14 archivos de test; la suite git del motor se omite sin git)
331
+ pnpm run verify:self-contained # las specs de dependencias resuelven desde el registry
332
+ pnpm run verify:artifacts # archivos enviados presentes + index.mjs importable
333
+ pnpm run check:readmes # consistencia de los README en cinco idiomas
334
+ pnpm pack # el tarball publicado
335
+ ```
336
+
337
+ Sin paso de build: ESM puro, `index.mjs` y `lib/` son los artefactos enviados. Las imágenes del README se generan programáticamente con [`scripts/gen-readme-assets.py`](scripts/gen-readme-assets.py) (Python + Pillow) y se pueden reejecutar sin riesgo.
338
+
339
+ Topics: `dsh`, `dsh-plugin`, `deepseek-harness`, `deepseek`, `cordis`, `session-sync`, `session`, `git`, `sync`, `cross-device`
340
+
341
+ ## Familia y agradecimientos
342
+
343
+ Este proyecto forma parte de la familia de plugins de DeepSeek Harness de [PerryLink](https://github.com/PerryLink) (todos Apache-2.0). Si te resulta útil, **una estrella ayuda a que la siguiente persona lo encuentre** — no hay nada bloqueado tras ella.
344
+
345
+ - [@BlakrPander](https://github.com/BlakrPander) — redacción de PAT-como-usuario y el análisis delete/modify de conservar ambos (#14); ambas partes se publicaron en 0.2.27/0.2.28.
346
+ - [@PerryLink](https://github.com/PerryLink) — creador y mantenedor: motor de espejo git, merge append-only de conservar ambos, comando `/sync` y herramientas `sync_*`, modos automáticos, saneadores y la documentación en cinco idiomas.
347
+
348
+ <details>
349
+ <summary>Expandir todos los plugins</summary>
350
+
351
+ | Plugin | Estado |
352
+ |---|---|
353
+ | **[dsh-aqua-input-check](https://github.com/PerryLink/dsh-aqua-input-check)** | |
354
+ | **[dsh-archive-check](https://github.com/PerryLink/dsh-archive-check)** | |
355
+ | **[dsh-auto-review](https://github.com/PerryLink/dsh-auto-review)** | |
356
+ | **[dsh-autotier](https://github.com/PerryLink/dsh-autotier)** | 🧊 CONGELADO — ver el README del repo |
357
+ | **[dsh-bid-ca-precheck](https://github.com/PerryLink/dsh-bid-ca-precheck)** | |
358
+ | **[dsh-bid-qual-check](https://github.com/PerryLink/dsh-bid-qual-check)** | |
359
+ | **[dsh-cert-mcp](https://github.com/PerryLink/dsh-cert-mcp)** | 🧊 CONGELADO — ver el README del repo |
360
+ | **[dsh-checkpoint-rewind](https://github.com/PerryLink/dsh-checkpoint-rewind)** | |
361
+ | **[dsh-click](https://github.com/PerryLink/dsh-click)** | |
362
+ | **[dsh-composer-history](https://github.com/PerryLink/dsh-composer-history)** | |
363
+ | **[dsh-contract-stance](https://github.com/PerryLink/dsh-contract-stance)** | |
364
+ | **[dsh-customs-doc-check](https://github.com/PerryLink/dsh-customs-doc-check)** | |
365
+ | **[dsh-data-quality](https://github.com/PerryLink/dsh-data-quality)** | 🧊 CONGELADO — ver el README del repo |
366
+ | **[dsh-demurrage-ledger](https://github.com/PerryLink/dsh-demurrage-ledger)** | |
367
+ | **[dsh-doublecheck](https://github.com/PerryLink/dsh-doublecheck)** | |
368
+ | **[dsh-drill-script-check](https://github.com/PerryLink/dsh-drill-script-check)** | |
369
+ | **[dsh-eia-guide-check](https://github.com/PerryLink/dsh-eia-guide-check)** | |
370
+ | **[dsh-emergency-plan](https://github.com/PerryLink/dsh-emergency-plan)** | |
371
+ | **[dsh-essay-rubric-check](https://github.com/PerryLink/dsh-essay-rubric-check)** | |
372
+ | **[dsh-evidence-check](https://github.com/PerryLink/dsh-evidence-check)** | |
373
+ | **[dsh-export-ctl-check](https://github.com/PerryLink/dsh-export-ctl-check)** | |
374
+ | **[dsh-fast](https://github.com/PerryLink/dsh-fast)** | |
375
+ | **[dsh-fmea-table-check](https://github.com/PerryLink/dsh-fmea-table-check)** | |
376
+ | **[dsh-forecast-penalty](https://github.com/PerryLink/dsh-forecast-penalty)** | |
377
+ | **[dsh-fund-research](https://github.com/PerryLink/dsh-fund-research)** | |
378
+ | **[dsh-github](https://github.com/PerryLink/dsh-github)** | |
379
+ | **[dsh-gongwen-flow-check](https://github.com/PerryLink/dsh-gongwen-flow-check)** | |
380
+ | **[dsh-gongwen-word-check](https://github.com/PerryLink/dsh-gongwen-word-check)** | |
381
+ | **[dsh-guard-plan-qc](https://github.com/PerryLink/dsh-guard-plan-qc)** | |
382
+ | **[dsh-hazchem-check](https://github.com/PerryLink/dsh-hazchem-check)** | |
383
+ | **[dsh-hazplan-check](https://github.com/PerryLink/dsh-hazplan-check)** | |
384
+ | **[dsh-hidden-risk-map](https://github.com/PerryLink/dsh-hidden-risk-map)** | |
385
+ | **[dsh-hs-classify](https://github.com/PerryLink/dsh-hs-classify)** | |
386
+ | **[dsh-icd-rule-check](https://github.com/PerryLink/dsh-icd-rule-check)** | |
387
+ | **[dsh-industry-research](https://github.com/PerryLink/dsh-industry-research)** | |
388
+ | **[dsh-lawcite-adapter](https://github.com/PerryLink/dsh-lawcite-adapter)** | |
389
+ | **[dsh-laya](https://github.com/PerryLink/dsh-laya)** | |
390
+ | **[dsh-lc-doc-check](https://github.com/PerryLink/dsh-lc-doc-check)** | |
391
+ | **[dsh-learning-gap-check](https://github.com/PerryLink/dsh-learning-gap-check)** | |
392
+ | **[dsh-library](https://github.com/PerryLink/dsh-library)** | |
393
+ | **[dsh-local-ai](https://github.com/PerryLink/dsh-local-ai)** | |
394
+ | **[dsh-lsp-actions](https://github.com/PerryLink/dsh-lsp-actions)** | |
395
+ | **[dsh-mask](https://github.com/PerryLink/dsh-mask)** | |
396
+ | **[dsh-mcp-panel](https://github.com/PerryLink/dsh-mcp-panel)** | |
397
+ | **[dsh-medrec-qc](https://github.com/PerryLink/dsh-medrec-qc)** | |
398
+ | **[dsh-memento](https://github.com/PerryLink/dsh-memento)** | 🧊 CONGELADO — ver el README del repo |
399
+ | **[dsh-nsfc-form-check](https://github.com/PerryLink/dsh-nsfc-form-check)** | |
400
+ | **[dsh-nurse-record-check](https://github.com/PerryLink/dsh-nurse-record-check)** | |
401
+ | **[dsh-observe](https://github.com/PerryLink/dsh-observe)** | |
402
+ | **[dsh-origin-rvc-check](https://github.com/PerryLink/dsh-origin-rvc-check)** | |
403
+ | **[dsh-ota-review-check](https://github.com/PerryLink/dsh-ota-review-check)** | |
404
+ | **[dsh-output-styles](https://github.com/PerryLink/dsh-output-styles)** | |
405
+ | **[dsh-paper-doc-adapter](https://github.com/PerryLink/dsh-paper-doc-adapter)** | |
406
+ | **[dsh-permission-rules](https://github.com/PerryLink/dsh-permission-rules)** | |
407
+ | **[dsh-permit-report-check](https://github.com/PerryLink/dsh-permit-report-check)** | |
408
+ | **[dsh-pipeline-check](https://github.com/PerryLink/dsh-pipeline-check)** | |
409
+ | **[dsh-pleading-draft](https://github.com/PerryLink/dsh-pleading-draft)** | |
410
+ | **[dsh-plugin-doctor](https://github.com/PerryLink/dsh-plugin-doctor)** | 🚫 RETIRADO (repo archivado) |
411
+ | **[dsh-plugin-guide](https://github.com/PerryLink/dsh-plugin-guide)** | |
412
+ | **[dsh-plugin-kit](https://github.com/PerryLink/dsh-plugin-kit)** | 🚫 RETIRADO (repo archivado) |
413
+ | **[dsh-plugin-upgrade](https://github.com/PerryLink/dsh-plugin-upgrade)** | 🚫 RETIRADO (repo archivado) |
414
+ | **[dsh-policy-brief-draft](https://github.com/PerryLink/dsh-policy-brief-draft)** | |
415
+ | **[dsh-power-loss-split](https://github.com/PerryLink/dsh-power-loss-split)** | |
416
+ | **[dsh-power-ticket-check](https://github.com/PerryLink/dsh-power-ticket-check)** | |
417
+ | **[dsh-ppap-check](https://github.com/PerryLink/dsh-ppap-check)** | |
418
+ | **[dsh-protest-deadline](https://github.com/PerryLink/dsh-protest-deadline)** | |
419
+ | **[dsh-railway-window](https://github.com/PerryLink/dsh-railway-window)** | |
420
+ | **[dsh-repair-order-qc](https://github.com/PerryLink/dsh-repair-order-qc)** | |
421
+ | **[dsh-research-report](https://github.com/PerryLink/dsh-research-report)** | |
422
+ | **[dsh-review-reply-check](https://github.com/PerryLink/dsh-review-reply-check)** | |
423
+ | **[dsh-rulefile-check](https://github.com/PerryLink/dsh-rulefile-check)** | |
424
+ | **[dsh-safety-brief-check](https://github.com/PerryLink/dsh-safety-brief-check)** | |
425
+ | **[dsh-score](https://github.com/PerryLink/dsh-score)** | 🧊 CONGELADO — ver el README del repo |
426
+ | **[dsh-session-sync](https://github.com/PerryLink/dsh-session-sync)** | |
427
+ | **[dsh-site-log-check](https://github.com/PerryLink/dsh-site-log-check)** | |
428
+ | **[dsh-skill-pack-security](https://github.com/PerryLink/dsh-skill-pack-security)** | |
429
+ | **[dsh-soe-decision-check](https://github.com/PerryLink/dsh-soe-decision-check)** | |
430
+ | **[dsh-soilwater-check](https://github.com/PerryLink/dsh-soilwater-check)** | |
431
+ | **[dsh-sop-sync-check](https://github.com/PerryLink/dsh-sop-sync-check)** | |
432
+ | **[dsh-spc-gbt-adapter](https://github.com/PerryLink/dsh-spc-gbt-adapter)** | |
433
+ | **[dsh-talk](https://github.com/PerryLink/dsh-talk)** | |
434
+ | **[dsh-tender-extract](https://github.com/PerryLink/dsh-tender-extract)** | |
435
+ | **[dsh-tender-matrix](https://github.com/PerryLink/dsh-tender-matrix)** | |
436
+ | **[dsh-test-drive](https://github.com/PerryLink/dsh-test-drive)** | |
437
+ | **[dsh-ticktick](https://github.com/PerryLink/dsh-ticktick)** | 🚫 RETIRADO (repo archivado) |
438
+ | **[dsh-translate](https://github.com/PerryLink/dsh-translate)** | |
439
+ | **[dsh-warranty-calc](https://github.com/PerryLink/dsh-warranty-calc)** | |
440
+ | **[dsh-budget](https://github.com/PerryLink/dsh-budget)** | 🧊 CONGELADO — ver el README del repo |
441
+ | **[dsh-claude-move](https://github.com/PerryLink/dsh-claude-move)** | 🧊 CONGELADO — ver el README del repo |
442
+ | **[dsh-defend](https://github.com/PerryLink/dsh-defend)** | 🧊 CONGELADO — ver el README del repo |
443
+ | **[dsh-draw](https://github.com/PerryLink/dsh-draw)** | 🧊 CONGELADO — ver el README del repo |
444
+ | **[dsh-reach](https://github.com/PerryLink/dsh-reach)** | 🧊 CONGELADO — ver el README del repo |
445
+ | **[dsh-background-agents](https://github.com/PerryLink/dsh-background-agents)** | 🚫 RETIRADO (repo archivado) |
446
+ | **[dsh-session-pin](https://github.com/PerryLink/dsh-session-pin)** | 🚫 RETIRADO (repo archivado) |
447
+ | **[dsh-team-rooms](https://github.com/PerryLink/dsh-team-rooms)** | 🚫 RETIRADO (repo archivado) |
448
+
449
+ </details>
450
+
451
+ ## Licencia
452
+
453
+ [LICENSE](LICENSE) (Apache License 2.0) © 2026 dsh-session-sync contributors
454
+
455
+ <p align="center"><sub>Apache-2.0 · Plugin de la comunidad, no afiliado a DeepSeek.</sub></p>