登录
OverDustD7

逸乎物外，尘心自闲。

Projects · 项目返回项目 ↗

DSH 主目录同步插件

2026-09-26 · GitHub

English ｜ DeepSeek Harness 插件（profile bundle）

npm version GitHub

DSH 配置与 Mnemon 记忆插件数据的 Git 同步工具，支持自动双向同步、跨设备迁移、初始化备份、冲突检测和 Web 可视化管理。0.2.1 补齐维护建议，并修复复审发现的历史检查、初始化和状态显示遗漏。

需要 Node.js 20 或更新版本、Git，以及提供 webServer、timer、connection.requestRejection 的 DSH 宿主。本机兼容性验证使用 DSH 0.1.2-rc.1、Node 24.20.0、Git 2.55.0.windows.4。

安装与生效

从 npm 安装（推荐）

powershell
dsh plugin --profile web add dsh-home-sync

装完重启 DSH web，刷新浏览器加载界面。已发布包无需构建或第三方依赖。

从 GitHub 安装

powershell
dsh plugin --profile web add github:OverDustD7/dsh-home-sync

本地开发（从源码）

powershell
dsh plugin --profile web add link:D:/Project/DSH/dsh-home-sync

link: 安装直接读取该源码目录：后端改动后重启 DSH web，界面改动刷新浏览器即可。

离线/隔离网络设备

先本地生成安装包再拷到目标机：

powershell
npm pack --pack-destination dist

目标机在压缩包所在目录执行：

powershell
dsh plugin --profile web add ./dsh-home-sync-0.2.3.tgz

若目标机器的包管理器无法使用本地 tarball，可把包解压到任意持久目录，再将该目录中的 package 子目录以 link: 安装；避免把临时解压目录作为长期链接目标。

同步行为

  • “拉取”检查远端并尝试快进，遇到分叉或可能覆盖本地修改时失败，不会创建本地提交。显式禁用 merge.autoStash，避免自动恢复暂存时发生冲突却误报成功；合并结束还会检查未解决的索引冲突。
  • “同步到远端”先 fetch 并检查文件范围，再提交允许同步的修改、整合远端，最后推送。工作区干净时仍会重试尚未上传的提交。
  • 自动同步按间隔执行完整同步，本地没有变化时也会检查远端。保存开关和间隔后立即重建任务；操作正在执行时，设置保存和其他写请求返回忙碌，请待其结束后重试。
  • 当前分支必须与设置中的分支一致。分支分叉可以尝试普通 Git 合并；同一内容冲突时停止推送、撤销此次未完成合并并保留本地提交。需手动解决 Git 冲突后重试，不会自动 force push。
  • 状态区每 15 秒刷新，区分待提交、待推送、待拉取和读取失败，新增目录按实际文件计数。领先/落后数量以最近成功 fetch 的远端快照为准。
  • 操作反馈使用 toast；面板底部“操作记录”默认折叠，按需展开查看、选择并复制备份路径和恢复指引。最近 100 条后台/手动操作记录保存在主目录旁的 <DSH_HOME>.home-sync-history.json，重启后仍可查询，不参与 Git 同步。记录包含操作结果、时间和备份路径，不记录文件正文。记录文件损坏时保留原文件并报告错误；记录写入失败不会撤销已经成功的同步。
  • 打开的面板与浮动按钮随宿主和系统主题变化重新配色，保留当前输入及展开状态。

所有 HTTP 数据接口都使用宿主的身份和 Host/Origin 校验；缺少此服务时插件不启用。POST 只接受 JSON。界面脚本本身不含用户数据。

允许同步的文件

  • .gitignore、settings.yaml、根目录 cordis.patch.yml。
  • profiles/web/ 下的 package.json、pnpm-lock.yaml、pnpm-workspace.yaml、cordis.yml、cordis.patch.yml、.dsh-market/state.json。
  • mnemon/ 下非隐藏文件，但排除名称为 data、state、credential(s)、secret(s) 的路径段，以及 .log、.wal、.shm 文件。

凭据、会话、附件、node_modules 等不加入提交。已暂存或已跟踪的禁止文件会阻止同步；推送前检查 HEAD 的完整可达历史（最多 1000 个提交），不以拉取仓库已有历史作为免检范围，因此拉取/推送地址不同或多个推送地址同样受保护。历史中曾出现禁止文件时停止发布，即使该文件已被删除；超过检查上限需先人工整理为干净同步历史。推送只更新所选分支，不自动跟随标签或镜像其他引用。多个目标的网络推送不具备跨仓库事务性，部分失败时需重试。允许文件内部的文本不做字段级脱敏，因此不要在允许同步的配置或记忆里保存不希望上传的内容。

只接受普通文件。符号链接、硬链接、子模块、越界路径、Windows 保留名称和大小写冲突会被拒绝。Git hooks 和提交签名仍遵循用户自己的 Git 配置；Git 子进程设置了超时及非交互凭据模式。

设备初始化与恢复

两种初始化模式都会备份。merge 表示备份后需要手动合并，并不表示自动把两份记忆合并。

  1. 从远端抓取到独立临时仓库，检查所有目标路径和文件类型。
  2. 检查本机碰撞，备份所有可能覆盖/删除的文件、原 Git 元数据和插件配置。
  3. 验证备份期间本地文件没有变化，再应用允许的文件并设置目标分支、origin、upstream。
  4. 成功后暂停自动同步与启动拉取，等待用户核对、手动合并及重新开启。

支持全新目录、已执行 git init 但尚未首次提交的独立仓库，以及再次初始化到历史不相关的远端。成功响应返回实际配置，界面立即刷新自动开关；初始化视为显式重置设置，当前表单以服务端配置为准。

备份位于 DSH_HOME 旁边的 <DSH_HOME>.home-sync-backups/init-*，不在被同步的工作区内。默认主目录时类似 ~/.dsh.home-sync-backups/init-*。

  • files/：原文件。
  • repository/：原 .git，包含本地历史、索引和远端配置。
  • config.json：原插件配置（原先存在时）。
  • manifest.json：目标、阶段、原文件存在状态和校验值。
  • MERGE.md：恢复说明。

可捕获的执行错误会尝试自动恢复。断电或强制结束进程不能保证自动恢复：先停止 DSH，依据 manifest 恢复 files，将 repository 恢复为 .git，恢复原配置，并移除清单中原先不存在的新文件。不要在 DSH 正写入记忆时执行恢复。Git worktree 或链接 .git 的初始化目前会明确拒绝。

初始化期间仍需避免其他程序写入同步文件；插件锁只协调本插件实例，不能暂停其他插件或人工 Git 操作。

配置与运行锁

配置位于 <DSH_HOME>/dsh-home-sync.json，支持：branch、autoPullOnStartup、autoSync、syncIntervalSeconds（15–86400）、commitMessage（1–1000 字符）、sshBatch。旧 autoSyncOnStartup 会迁移为 autoSync；同时存在时以 autoSync 为准。

损坏配置不会退回并开启默认自动任务。需修复或恢复此 JSON 后重启 DSH。写入通过临时文件同步落盘后替换，初始化另外保留配置备份。

跨进程锁目录为 <DSH_HOME>.home-sync-lock，其中的 owner.json 记录持锁进程与起始时间，其修改时间兼作心跳。进程被强杀或系统异常关机留下的锁会被自动接管：持有人信息缺失或损坏、持锁进程已不存在、或心跳超过 15 分钟未更新时，旧锁会被改名为 <DSH_HOME>.home-sync-lock.stale-<时间戳> 并继续本次操作（接管情况会写进操作消息）。仍由存活进程持有的新鲜锁依然返回 busy。未完成的初始化应先按备份恢复。

验证

powershell
npm run check
npm test

文档统一保存为 UTF-8。使用脚本修改时，读取和写入都应显式指定 UTF-8，不能依赖系统默认代码页。npm run check:docs 检查 README 正文和语言链接，并已接入 npm run check 与正常 npm 打包流程；打包时不要使用 --ignore-scripts，否则会跳过该检查。

测试使用系统临时目录、虚构文件与本地 Git 远端，不访问真实 DSH 主目录或真实账号。测试仓库保留在系统临时目录便于诊断。

浏览器测试使用独立临时 Chrome/Edge 配置；没有浏览器时跳过，可通过 CHROME_PATH 指定。受限环境可能需要在正常用户权限下运行浏览器测试。宿主兼容性测试可用 DSH_HOST_MODULES 指向已安装 DSH 的 node_modules/@deepseek-ai，未找到时跳过；此测试复用真实宿主路由与来源校验方法，身份 Cookie 验证使用虚构实现。

开发与审计文档（检查/修复/复核报告及 audit/ 证据）为本地内部资料，不随本仓库分发；test/ 与 npm test 是公开可复现的验证入口。

历史复核记录（2026-09-07，已被后续复审补充）

以下是 0.2.0 的历史记录，其"未发现新的高风险缺陷"结论已被后续复审推翻。 开发与审计文档（含 0.2.1 二次审查报告）为本地内部资料，未随本仓库分发，本段仅作历史追溯；默认隐藏即时日志的交互保持，新增独立折叠操作记录入口。

在修复完成报告之后，对 0.2.0 源码进行了独立的只读复核与测试复跑：

  • 复核范围：lib/index.js、lib/sync.js、lib/ui.js、package.json、cordis.patch.yml，与两份报告逐条对照。
  • 结果：原审计 17 项（F01–F17）修复均已落实到当前源码，抽查关键实现与本页“同步行为/允许同步的文件/设备初始化/验证”描述一致；报告所述 35 项测试在本机（Node 24.20.0 + Git 2.55.0.windows.4，真实 Git 临时仓库与虚构远端）复跑35/35 通过，0 失败。
  • 复核中修正的一处界面回归：界面操作反馈改为底部 toast 浮窗（不再显示卡片内日志框）；#log 保留但改为视觉隐藏，仅作 aria-live 供屏幕阅读器使用，避免再次出现用户已否决的“保存后在下方显示提示”。
  • 复核结论：npm run check 与 npm test 全绿；未发现新的高风险缺陷。
  • 已知边界（与报告一致，非缺陷）：两种初始化模式底层行为相同（备份 → 重置 → 暂停自动任务），mode 仅影响提示文案；“已用机器合并”需要按备份与 MERGE.md 手动挑拣；HTTP 接口仅接受已登录的可信会话（未登录直连返回 401 属预期）；后端（index/sync）改动需重启 DSH web 后生效，界面（ui.js）改动 Ctrl+F5 即生效。