dsh-syn-config 0.0.0-stage → 0.7.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dreamaniax
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,227 @@
-# Temporary Holding Version
+# dsh-syn-config
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+跨电脑同步 DSH 配置（技能 / profile 设置 / AGENTS.md）的 DeepSeek Harness 插件，**macOS 与 Windows 同一份代码**。
+
+> 状态：**P6（隐私加固）**。六个工具 + 一个斜杠命令 + 一个状态卡 + 随包技能：
+> - `dsh_sync_status`：仓库分支 / 上游 / 领先落后 / 脏文件数（默认不联网）。
+> - `dsh_sync_doctor`：`doctor.sh` 的 Node 移植，六节体检，退出码 0-2-1 与脚本一致。
+> - `dsh_sync_pull`：`git pull --ff-only` + 镜像 skills / agents-skills / weekly；**默认 dry-run**。
+> - `dsh_sync_secrets`：scan / redact / inject / refresh / fingerprint；**默认 dry-run**，注入后残留占位符直接失败且不写盘。
+>
+> - `dsh_sync_push`：快照 → lint 闸门 → 脱敏 → 明文扫描 → 提交 → 推送；**默认 dry-run**；分叉时停下，不 rebase、不 force；提交信息含 URL/凭据会被拒绝。
+> - `dsh_sync_diag`：报告本次激活真正注册了什么（服务是否可用、每一步的成败与错误原文）——命令或状态卡不见时先看它。
+>
+> 引导（新机第一条命令）仍由 `dsh-config/scripts/apply.sh` 负责——插件装不上时它不在。
+>
+> `/syn-dsh status|doctor|pull|push|secrets`：斜杠命令，宿主半执行、不进模型消息；`/syn-dsh push now` 才真推。
+> 输入框上方的状态圆点：绿=已同步、黄=有漂移（↑领先/↓落后/±脏）、红=不可用；点一下刷新。
+> `syn-dsh` 技能由插件自带（`assets/syn-dsh.md`，rank 600），不再放在配置仓库里。
+>
+> 设计理由与后续阶段见主仓库的调研文档：`../research/syn-dsh-plugin/PLAN.md`。
+
+## 为什么是插件，而不是又一层 shell
+
+| | 现状（`~/dsh-config/scripts/*.sh`） | 本插件 |
+|---|---|---|
+| Windows | 需要 Git Bash 兜底（12 个 `.cmd`） | 原生 Node，无 shell 依赖 |
+| 模型拿到的东西 | 中文日志文本，需要自己解析 | 结构化 JSON（分支/领先/落后/脏文件），工具 schema 强制校验 |
+| 跨平台差异 | rsync / sed / chmod / od 各自分支 | 一个 `execFile('git', argv)`，两边一致 |
+| 引导（新机第一条命令） | 脚本仍是唯一入口 | **仍由脚本负责**——插件装不上时它不存在 |
+
+分工：**插件当手**（日常读写本机与仓库）、**脚本当门**（引导、提交闸门、CI 回归）、**技能当脑**（`/syn-dsh` 决定先做什么）。
+
+## 安装
+
+### 开发 / 离线（link 安装，本仓库直接生效）
+
+```bash
+node scripts/install.mjs --dry-run    # 先看会改什么
+node scripts/install.mjs              # 写 profile manifest + 建 link
+node scripts/verify.mjs               # 校验 manifest / link / 模块 / 工具 / 仓库
+```
+
+它会：备份 `~/.dsh/profiles/desktop/package.json`（`.bak-dsh-syn-config`）→ 写 `link:` 依赖 → 把 `dsh-syn-config` 追加进 `dsh.profile.bundles` → 在 `profile/node_modules/` 建 **symlink（macOS）/ junction（Windows）** → 重新读盘逐项校验。
+
+安装后**完全退出并重开 DeepSeek Harness**（macOS `Cmd+Q` / Windows 托盘 → 退出），新会话里才会有 `dsh_sync_status`。
+
+### 生产（正式分发）
+
+```bash
+dsh plugin --profile desktop add github:Dreamaniax/dsh-syn-config
+```
+
+注意：`dsh plugin add` 只写 `dependencies` + lock，**不写** `dsh.profile.bundles`；只有 GUI 的「设置 → 插件」安装会写 bundles。所以走 CLI 时要么再手工补一行 bundles，要么用 GUI 安装。
+
+### 卸载
+
+```bash
+node scripts/uninstall.mjs --dry-run
+node scripts/uninstall.mjs
+```
+
+只删投影（link/junction，绝不穿过 link 删目标）与 manifest 里的两处条目，保留备份；仓库本身不受影响。
+
+## 工具
+
+### `dsh_sync_doctor`
+
+`dsh-config/scripts/doctor.sh` 的结构化版本：同样的六节、同样的判定、同样的退出码（0 干净 / 2 有警告 / 1 有阻塞），但返回的是 JSON 分节而不是中文日志。
+
+| 参数 | 类型 | 说明 |
+|---|---|---|
+| `repo` | string（可选） | 仓库路径，支持 `~`；默认取配置 |
+| `offline` | boolean（可选） | 跳过 `git fetch` 与远端比对 |
+| `profile` | string（可选） | 要体检的 profile，默认 `desktop` |
+
+每节返回 `{ id, title, status: ok|warn|error, items: [{ level, text }] }`。与脚本的对等性由 `node scripts/parity.mjs` 逐项比对（当前 13/13 一致）。
+
+### `dsh_sync_push`
+
+| 参数 | 类型 | 说明 |
+|---|---|---|
+| `repo` | string（可选） | 仓库路径，默认取配置 |
+| `dry_run` | boolean（可选，**默认 true**） | 只算：快照计划 + lint + 脱敏 + 扫描，全都不写 |
+| `message` | string（可选） | 提交信息，默认 `sync: <本地日期时间>` |
+| `include_profile` | boolean（可选，默认 true） | 是否带 profile 设置与插件清单（`--no-profile` 的等价物） |
+| `allow_delete` | boolean（可选，默认 false） | 才允许删除仓库里多出来的条目；默认只报告 |
+
+顺序是契约不是细节：**pack → lint → redact → scan → commit → push**。先脱敏再扫描，扫描不通过就不提交；分叉时保留本地提交并让人手工合，**永不 rebase、永不 force**。
+
+### `dsh_sync_pull`
+
+| 参数 | 类型 | 说明 |
+|---|---|---|
+| `repo` | string（可选） | 仓库路径，默认取配置 |
+| `dry_run` | boolean（可选，**默认 true**） | 只 fetch 并报告计划，不动 HEAD、不写本机 |
+| `delete_local` | boolean（可选，默认 false） | 同时删除仓库里已不存在的本机技能（危险，默认关） |
+
+`git pull --ff-only`；分叉时返回 `ok:false` 并保留本地提交，不做合并、更不 reset。镜像目标：`skills/`、`agents-skills/`、`weekly/`（weekly 的 `.sh` 自动 `chmod +x`）。
+
+### `dsh_sync_secrets`
+
+| `action` | 作用方向 | 说明 |
+|---|---|---|
+| `scan` | 仓库（只读） | 找明文密钥，命中即 `exitCode:1` |
+| `redact` | 仓库副本 | 真实值 → `__KEY__` |
+| `inject` | 已部署副本 | `__KEY__` → 真实值；**残留占位符则不写盘** |
+| `refresh` | 已部署副本 | 轮换后重写 `Authorization: "Bearer …"` |
+| `fingerprint` | 只读 | 只给 sha256 前 8 位与长度 |
+
+替换一律**字面量**（`sed` 元字符 bug 的修复点）；写前留 `<file>.bak-<ISO>` 备份；返回值、日志、渲染里都没有明文。
+
+### `dsh_sync_status`
+
+| 参数 | 类型 | 说明 |
+|---|---|---|
+| `repo` | string（可选） | 仓库路径，支持 `~/dsh-config`；默认取配置里的 `repoPath` |
+| `fetch` | boolean（可选） | 先 `git fetch --prune`，再算领先/落后；默认取配置（关） |
+
+返回（`output.schema` 强制）：
+
+```json
+{
+  "ok": true,
+  "repoPath": "/Users/you/dsh-config",
+  "repoPresent": true,
+  "branch": "main",
+  "upstream": "origin/main",
+  "ahead": 2,
+  "behind": 0,
+  "dirty": 1,
+  "dirtyFiles": [" M AGENTS.md"],
+  "notes": []
+}
+```
+
+边界情况全部**以数据返回、不抛异常**（抛异常会让宿主把工具调用判错）：仓库不存在 → `repoPresent:false`；不是 git 仓库 → `ok:false` + `notes`；没有上游 → `notes` 说明并停止计算领先/落后；git 缺失（含 Windows 的安装提示）→ `notes` 给出可操作建议。
+
+## 配置
+
+在 profile 的 `cordis.patch.yml` 里那行插件下加 `config`（注释示例见本仓库 `cordis.patch.yml`）：
+
+```yaml
+- insert:
+    - id: dsh-syn-config
+      name: 'dsh-syn-config'
+      config:
+        repoPath: '~/dsh-config'
+        gitTimeoutMs: 15000
+        fetchOnStatus: false
+```
+
+P0 没有导出 Config schema（避免依赖 schemastery，见下），所以 `config` 未做 schema 校验——`apply()` 里逐字段自检并回退默认值。
+
+## 为什么宿主半不 import 任何 `@deepseek-ai/*`
+
+`link:` 安装时插件真实文件在 checkout 里，Node 按真实路径解析裸导入；而 profile 的 `node_modules` 并不含 `@deepseek-ai/dsh-tools`（它们在应用打包内），于是 `import '@deepseek-ai/dsh-tools'` 会在 link 安装下解析失败。因此宿主半只用 `ctx` 注入的服务 + Node 内置模块：
+
+- 工具定义直接用**编译后的 JSON Schema**（`ctx.tools.register` 校验的就是这个形状：必须有 `output.render`，且属性不能写 `required: true` 那种 authoring 简写，要用 `required: [...]` 数组）。
+- 代价：失去 `defineTool` 的参数预校验 → 我们在 `execute()` 里自己收窄参数并把失败作为数据返回。
+
+这条也顺带让测试能在裸 Node 下跑，不需要任何安装步骤。
+
+## 隐私边界
+
+| 面 | 做法 |
+|---|---|
+| 上传范围 | `skills/`、`agents-skills/`、`AGENTS.md`、profile 五文件；`.dsh-market/` **默认不上传**（`include_market` 才带） |
+| 密钥 | 脱敏/注入都是字面量替换；仓库副本与 `AGENTS.md` 一起处理；注入后残留占位符 → 拒绝写盘 |
+| 扫描 | 工作树 + `deep:true` 时最近 200 次提交；规则覆盖 `as_sk_/ghp_/github_pat_/sk-/sk-proj-/AKIA/AIza/xox*/JWT/PEM/Bearer/通用 api_key 赋值` |
+| 历史命中 | 命中只给 commit + 掩码预览（`AKIAIO…MPLE`），不回传原值；提示先轮换再谈改写历史 |
+| 提交信息 | 含 URL 或凭据特征直接拒绝（进历史不可撤回） |
+| 本地 HTTP 路由 | 只返回分支/领先落后/脏计数，**不返回文件名**；`no-store` |
+| 输出路径 | notes/渲染里的绝对路径缩成 `~/…` |
+| 发布 | `node scripts/publish-check.mjs` 扫 tracked 文件里的账号名、私有仓库 URL、launchd 标签、家目录路径，非零退出可做发布闸门 |
+
+## 平台差异（已在代码里处理）
+
+| 关注点 | macOS | Windows |
+|---|---|---|
+| profile 投影 | symlink | **junction**（不需要管理员权限 / 开发者模式），失败再退 dir symlink |
+| manifest 原子写 | rename | 同名 rename；遇到杀软/索引器占用（`EACCES`/`EBUSY`/`EPERM`）退避重试 |
+| 路径 | `~/…`、`/` | `~\…` 同样支持；`isAbsolute`/`join` 处理盘符 |
+| git | Apple git | Git for Windows 的 `git.exe`（不在 PATH 时 `notes` 会给安装提示） |
+| 换行 | LF | `.gitattributes` 固定 `*.sh`/`*.js` LF、`*.cmd`/`*.ps1` CRLF |
+| 控制台 | 直接输出 | `execFile(..., { windowsHide: true })`，不弹黑框 |
+
+## 开发
+
+```bash
+node --test "test/*.test.mjs"     # 26 个用例：解析/脱敏/扫描/体检分节 + 真 git 仓库 + 插件契约
+node scripts/parity.mjs           # 与 scripts/doctor.sh 逐项比对（同状态、同退出码）
+node --test test/mirror.test.mjs  # 镜像与 rsync -a --delete 的树对比
+node scripts/install.mjs --dry-run
+node scripts/verify.mjs
+```
+
+`test/status.test.mjs` 在临时目录里 `git init` 真仓库来断言；`test/plugin.test.mjs` 用假 `ctx` 断言注册形态与 `execute` 返回值形状。
+
+## 验收清单
+
+| # | 验收项 | 命令 / 判据 |
+|---|---|---|
+| 1 | manifest 依赖 + bundles 条目 | `node scripts/verify.mjs` 前两项 `ok` |
+| 2 | 投影是 link 且指向本 checkout | `verify.mjs` 的 projection 两项 |
+| 3 | 模块可被宿主加载 | `verify.mjs` 的 load/export 四项 |
+| 4 | 只注册一个工具且 schema 合法 | `verify.mjs` 的 tool 三项 |
+| 5 | 能读真实仓库状态 | `verify.mjs` 打印 branch/upstream/ahead/behind/dirty |
+| 6 | 宿主启动时组合进该行 | `dsh --profile desktop --dump-config \| grep dsh-syn-config` |
+| 7 | 新会话工具可见 | 重启客户端后问答一次「dsh 配置同步了吗」 |
+| 8 | 三种仓库状态结果正确 | 干净 / 落后 / 脏（本地真仓库或临时仓库） |
+| 9 | 体检与脚本对等 | `node scripts/parity.mjs` → 13/13，退出码一致 |
+| 10 | 报告不含明文密钥 | `test/doctor.test.mjs` 的 redaction 用例 |
+| 11 | 镜像与 rsync 等价 | `test/mirror.test.mjs`（有 rsync 时真跑对照） |
+| 12 | reasoningEffort 4 条断言 | `test/patch.test.mjs`（移植自 `selftest.sh:26-69`） |
+| 13 | 元字符密钥往返 | `test/secrets.test.mjs` |
+| 14 | 残留占位符不写盘 | `test/p2.test.mjs` |
+| 15 | 快照不动 reasoningEffort | `test/pack.test.mjs` |
+| 16 | 默认不删仓库条目 | `test/pack.test.mjs`（`allowDelete` 才删） |
+| 17 | 分叉不 rebase、不丢提交 | `test/push.test.mjs` |
+| 18 | 明文密钥在提交前中止 | `test/push.test.mjs` |
+| 19 | 斜杠命令五个子命令 | `test/p4.test.mjs`（status/push dry-run/未知子命令） |
+| 20 | 状态路由 GET/405 | `test/p4.test.mjs`（含 `Cache-Control: no-store`） |
+| 21 | 技能随包携带 | `test/p4.test.mjs`（provider list/get，rank 600） |
+
+## 许可
+
+MIT。Windows 投影与原子写逻辑改编自同作者的 `dsh-model-effort-chips`（MIT）。

package/assets/syn-dsh.md

@@ -0,0 +1,223 @@
+---
+name: syn-dsh
+description: "跨电脑同步 DSH 配置（技能 / 插件 / profile 设置 / AGENTS.md）与私有仓库 ~/dsh-config：拉取、推送、新机全量恢复、体检与失败排查。当用户说「同步 dsh」「syn_dsh」「更新另一台机器的配置」「把配置推到仓库」「换电脑恢复配置」「为什么技能没同步」时使用。"
+---
+
+# Syn DSH（跨电脑同步 DSH 配置）
+
+把「本机 `~/.dsh`」和「私有配置仓库 `~/dsh-config`」双向对齐。所有命令都在仓库目录里跑。
+
+## 优先用插件（已装 `dsh-syn-config` 时）
+
+插件把日常动作做成了工具与命令，脚本退居「引导 + CI + 提交闸门」：
+
+| 想做的事 | 会话里 | 命令 | 对应脚本（兜底） |
+|---|---|---|---|
+| 看是否同步 | 问「dsh 同步了吗」/ 调 `dsh_sync_status` | `/syn-dsh status` | `doctor.sh`（只读版） |
+| 完整体检 | 调 `dsh_sync_doctor` | `/syn-dsh doctor` | `doctor.sh` |
+| 拉取 | 调 `dsh_sync_pull`（默认 dry-run） | `/syn-dsh pull now` | `update.sh` |
+| 推送 | 调 `dsh_sync_push`（默认 dry-run） | `/syn-dsh push now` | `pack.sh` + `sync.sh` |
+| 密钥 | 调 `dsh_sync_secrets` | `/syn-dsh secrets scan` | `secrets.sh` |
+| 新机引导 / CI | —— 插件管不到 | —— | `apply.sh` / `selftest.sh` |
+
+插件铁律：写操作默认 dry-run；推送分叉时**只停不 rebase**；`--delete` 默认降级为「报告 + 显式确认」；`reasoningEffort` 永不同步。
+
+仓库位置：`~/dsh-config`（本机惯例；插件默认也是这个路径，可在配置里改）
+远端：`https://github.com/<owner>/dsh-config`（私有）
+profile：`desktop`；技能目录：`~/.dsh/skills`；跨 agent 技能：`~/.agents/skills`
+
+## 平台（先判断，再决定用哪条命令）
+
+| 系统 | 日常命令 | 说明 |
+|---|---|---|
+| macOS / Linux | `./scripts/update.sh` | bash + rsync（有就用 rsync） |
+| Windows（推荐） | `scripts\win\update.cmd` | 自动定位 Git for Windows 的 bash；不需要 WSL |
+| Windows（Git Bash 里） | `./scripts/update.sh` | 与 macOS 完全一致 |
+
+Windows 首次：`git clone … %USERPROFILE%\dsh-config` → `scripts\win\apply.cmd --yes` → 用 PowerShell 写 `secrets.env` → **再跑一次** `apply --yes` 让密钥注入。
+
+## 何时用
+
+- 用户说「同步 dsh / syn_dsh / 把配置同步一下 / 拉最新配置」
+- 换电脑后第一次恢复配置
+- 刚改完技能或插件，要推给另一台
+- 同步出问题（冲突、推送失败、技能没生效）来排查
+
+## 一句铁律
+
+仓库是唯一真相源。本机 `~/.dsh` 与仓库之间只有两个方向：**拉**（update / apply）和**推**（sync）。
+不确定就先体检（只读），不要靠猜，也不要靠记忆里的参数。所有参数以脚本自带 `--help` 为准。
+
+**例外：`reasoningEffort` 永不同步。** 它是本机模型 / 思考强度 chip 的状态，不是跨机配置：
+`pack.sh` 保留仓库里的值（不把本机值推上去），`apply.sh` 保留本机值（不把仓库值盖下来），
+`doctor.sh` 比较时忽略这一行。手工提交、PR、周报也不要把它带进仓库。
+
+## 第一步永远是体检
+
+```bash
+cd ~/dsh-config && ./scripts/doctor.sh        # macOS/Linux
+cd %USERPROFILE%\dsh-config && scripts\win\doctor.cmd   # Windows
+```
+
+只读（仅 `git fetch`），报告：git/rsync 可用性、工作区是否脏、落后/领先几个提交、仓库与本机技能数及**差集**、缺 `SKILL.md` 的技能、`secrets.env` 权限与键名（不打印值）、仓库明文密钥扫描、**设置与插件清单是否和仓库一致**（把真实密钥换回占位符后比对，只报差异行数）。
+
+退出码：`0` 干净 · `2` 有警告可继续 · `1` 有阻塞（先修再同步）。
+`--offline` 不联网；`--quiet` 只打结论。
+
+## 决策表
+
+| 用户的意思 | 动作 | 命令 |
+|---|---|---|
+| 「同步一下」（默认） | 拉 + 体检 + 本机有漂移就推 | 见下方「默认流程」 |
+| 拉 / 更新 / 另一台改了 | 只拉技能（秒级） | `./scripts/update.sh` |
+| 连插件、设置、AGENTS.md 一起拉 | 拉 + 恢复 profile + 重装插件 | `./scripts/update.sh --all` |
+| 只看会变什么 | 不动文件 | `./scripts/update.sh --dry-run` |
+| 推 / 上传 / 这台改好了 | 快照 + 提交 + 推送 | `./scripts/sync.sh "说明"` |
+| 新电脑 / 第一次 | clone + 全量恢复 + 补密钥 | 见「新电脑第一次」 |
+| 只想看状态 / 排查 | 体检 | `./scripts/doctor.sh` |
+| 换了密钥 / 要轮换 | 记指纹 → 换 key → 再记指纹 → apply → verify | `./scripts/secrets.sh fingerprint`（只出 sha256 前缀，不出明文） |
+| 「到底能不能用 / 环境闭环了吗」 | 端到端验收（含真实 AnySearch 调用与重启检测） | `./scripts/verify.sh`（`--no-net` 跳过联网） |
+| 装/改周报定时任务 | 跨平台调度器 | `./scripts/schedule.sh`（mac launchd / win schtasks / Linux 给 cron 行） |
+
+## 默认流程（用户只说「同步一下」时照这个走）
+
+1. `./scripts/doctor.sh`
+   - 退出 `1`：先修阻塞项（没有 remote / 找不到 git / 仓库有明文密钥），**不要继续同步**。
+2. 拉：`./scripts/update.sh`
+   - 失败（网络/鉴权）：如实报告「拉取失败」+ 错误摘要并停止。**此时不要推**，否则可能覆盖另一台的提交。
+3. 判断本机是否有未推送改动 —— **以 `doctor.sh` 为准，不要只看 `git status`**：
+   ```bash
+   cd ~/dsh-config && ./scripts/doctor.sh --quiet     # 看「仅本机有（未入库）」+「工作区 N 处未提交改动」
+   ```
+   - 两边都空 → 已一致，跳到第 5 步。
+   - 有「仅本机有」→ 那是 `~/.dsh/skills` 里的新/改技能，`git status` 看不到（要先 `pack.sh` 才进仓库），必须走第 4 步推送。
+   - 有「cordis.patch.yml 与仓库差 N 行」→ 本机改了设置（模型/UI/MCP），也要推；反过来想在本机应用另一台的设置，用 `update.sh --all`。
+   - 有「package.json（插件清单）与仓库不同」→ 本机装了/卸载了插件，同上处理。
+   - 工作区脏 → 先看摘要：`git -C ~/dsh-config diff --stat | tail -20`。
+4. 推送 `./scripts/sync.sh "sync: <一句话说明>"`
+   - 只有 `skills/` `agents-skills/` 变动 → 可直接推。
+   - 动了 `profiles/`、`AGENTS.md`、插件清单 → **必须先给用户看 diff 摘要并确认**，这些会影响所有电脑的模型、插件和指令。
+   - 用户没说要推、且改动涉及配置/插件时，问一句再推。
+5. 验收（必须贴证据，不许说「应该没问题」）：
+   - `./scripts/doctor.sh --quiet` 没有 ❌ 和 ⚠️（技能数相等、设置与仓库一致）
+   - commit 短哈希 + 是否出现「✅ 已推送」
+   - 生效提示：技能要**新开会话**才加载；插件/设置改动要重启客户端
+
+## 新电脑第一次（`/syn-dsh` 还不存在时）
+
+技能本身来自仓库，所以新机上 `/syn-dsh` 还没有——第一次必须手工 bootstrap 一次，跑完技能才会出现：
+
+```bash
+# 0) 装同版本 DSH 桌面端，用同一账号登录一次（生成 ~/.dsh）
+# 1) 私有仓库先授权：gh auth login / PAT / SSH key（首次 clone 会弹凭据管理器）
+git clone https://github.com/<owner>/dsh-config ~/dsh-config
+cd ~/dsh-config
+./scripts/doctor.sh        # 可选：只读体检
+./scripts/apply.sh         # 先 dry-run 看差异
+# 2) 先写密钥再 apply --yes：缺 secrets.env 时 apply 检测到未注入占位符会回滚（退出码 1）
+printf 'ANYSEARCH_API_KEY=%s\n' '你的key' >> ~/.dsh/secrets.env && chmod 600 ~/.dsh/secrets.env
+./scripts/apply.sh --yes   # 全量：技能 + profile + AGENTS.md + 重装插件
+# 3) 新开会话 → /syn-dsh 与其余技能就位
+```
+
+Windows 用 `scripts\win\doctor.cmd` / `scripts\win\apply.cmd`（参数相同，自动找 Git Bash，不需要 WSL）：
+
+```bat
+git clone https://github.com/<owner>/dsh-config %USERPROFILE%\dsh-config
+cd %USERPROFILE%\dsh-config
+scripts\win\apply.cmd               :: dry-run
+echo ANYSEARCH_API_KEY=你的key> %USERPROFILE%\.dsh\secrets.env
+scripts\win\apply.cmd --yes
+```
+
+注意：
+
+- 仓库是私有的，没凭据第一步就 clone 不下来。
+- **顺序不能反**：`secrets.env` 必须在 `apply --yes` 之前存在；若先 apply 失败，补好密钥后重跑同一条 `apply --yes` 即可（它自己会 inject，不必单独跑 `secrets.sh inject`）。
+- `apply --yes` 第 5 步会重装插件；仓库里的插件版本与新客户端运行时不一致时这一步会报警，按提示对齐版本，别当成功。
+- 首次 clone 约 141 MB，慢是正常的；还没有 remote 时用 `./scripts/publish.sh`。
+
+## 日常拉取
+
+```bash
+cd ~/dsh-config && ./scripts/update.sh            # 只技能，秒级
+cd ~/dsh-config && ./scripts/update.sh --all      # 连 profile 配置 / AGENTS.md / 重装插件
+cd ~/dsh-config && ./scripts/update.sh --mirror   # 额外删除仓库里没有的技能（危险：先问用户 + 先 --dry-run）
+```
+
+`update.sh` 会 `git pull --ff-only` → 打印本次变动技能 → rsync 到 `~/.dsh/skills` 与 `~/.agents/skills` → 自检技能数。
+
+## 本机改动推回
+
+```bash
+cd ~/dsh-config && ./scripts/sync.sh "sync: 新增 X 技能"
+```
+
+等于 `pack.sh`（本机 → 仓库快照）→ `secrets.sh redact` + `scan`（发现明文直接中止，不提交）→ commit → push。
+没有变化时输出「没有变化，无需提交。」，不要当失败。
+
+## 密钥轮换
+
+```bash
+vim ~/.dsh/secrets.env                          # 改成新值
+cd ~/dsh-config && ./scripts/secrets.sh refresh # 本机配置里的旧值 → 新值
+# 重启 DSH 生效。key 不贴进对话、提交信息、周报、截图
+```
+
+## 失败处置
+
+| 现象 | 原因 | 处理 |
+|---|---|---|
+| `git pull --ff-only` 失败或冲突 | 两台都改了同一文件（常见 `cordis.patch.yml` / `package.json`） | 先保住本机改动：`git -C ~/dsh-config stash push -m wip` → `update.sh` → `stash pop` 手工合。**绝不** `git checkout -- .`、`git reset --hard`（会丢本机技能改动） |
+| 推送失败 | 断网 / 凭据过期 / 非快进 | 回「已落地但未同步」+ 错误摘要，下次会话先补推（`sync.sh` 幂等）。不得声称已同步 |
+| `pack.sh` 报「仍有明文密钥，已中止」 | 配置里写了真实 key | 值挪进 `~/.dsh/secrets.env`，配置改 `__KEY_NAME__`，再 `./scripts/secrets.sh redact` |
+| 另一台说没变化，但确实改了 | 那台没推成功 | 到那台跑 `doctor.sh` 看「领先 N 个提交」；补推成功后本机再 `update.sh` |
+| 技能数不相等 | `--mirror` 未跑 / 缺 `SKILL.md` / rsync 权限 | `doctor.sh` 看差集与「缺 SKILL.md」清单 |
+| 拉完新技能不出现 | 技能在**会话启动**时加载 | 新开一个会话；插件变更需重启客户端 |
+| `/usr/bin/git` 报 exit 69 | Xcode 许可 | 脚本已自动优先 Xcode 自带 git；或 `sudo xcodebuild -license accept` |
+| 脚本报 `xxx: unbound variable` | bash 3.2 把紧跟变量的全角字符吞进变量名 | 输出用 `${VAR}` 而不是 `$VAR`（写脚本时注意；全仓库已扫过一遍） |
+| `$'\r': command not found` | Windows 上 `.sh` 被 autocrlf 转成 CRLF | 仓库有 `.gitattributes` 兜底；若仍出现，`git config core.autocrlf false` 后重 clone |
+| Windows 报 `rsync: command not found` | 老版本脚本或自建 shim | 直接用 `scripts\win\*.cmd`；新版 `scripts/_lib.sh` 无 rsync 时自动用 cp/find |
+| `apply` 报「仍有未解析的密钥占位符」 | `secrets.env` 缺键或没建 | 补键后重跑 `apply --yes`；**已自动回滚**，不会把坏配置激活（DSH 继续用上一份可用配置） |
+| `apply` 报「secrets.env 里没有这些键名」但文件肉眼看正常 | 文件末尾缺换行，`read` 丢掉最后一行（Windows `Set-Content -NoNewline` / `echo\|set /p` 易踩） | 已修（`read ... \|\| [ -n "$k" ]`）；写入时用 `printf '...\n'` 或换行结尾 |
+| `verify` 报「配置比 DSH 进程新」但功能已经能用 | MCP 配置热加载；时间戳只说明配置新，不说明没生效 | 第 4 项通过时自动降级为提示；只有主题/模型/插件类改动建议重启 |
+
+## Windows 已知差异（脚本已处理，知道就行）
+
+- **没有 rsync**：`scripts/_lib.sh` 用 `cp/find` 实现同样语义（`--delete`/`--dry-run` 都支持），别再手搓 shim。
+- **没有 600 权限**：`secrets.env` 靠 NTFS ACL；doctor 在 Windows 上跳过 600 检查，只确认文件存在。
+- **换行符**：`.gitattributes` 强制 `*.sh`=LF、`*.cmd`=CRLF。
+- **周报流水线**（`~/.dsh/learning/` + launchd）只在 macOS 配置过；Windows 要另建目录 + 任务计划程序，不随仓库同步。
+- **`dsh` 命令可能不在 PATH**：`apply` 会提示，改用桌面端「设置 → 插件」按 `MANIFEST.md` 装。
+- **平台快照**：`MANIFEST.md` 只放跨机一致的内容；机器名/平台写在本地 `MANIFEST.local.md`（已 gitignore），避免来回 push 产生噪声 diff。
+
+## 一条验收原则（真机踩出来的）
+
+**强证据定结论，弱证据降提示。** 端到端调用（真实 `tools/call`）能证明"能用"时，进程启动时间、文件 mtime 这类弱证据只能作提示，不得推翻实测：
+- `verify` 第 4 项通过 → 第 5 项（配置是否比进程新）降为 ⚠️，不计缺口；只有端到端失败时它才升 ❌
+- 同一台机器上两个检查给出矛盾信号时，先问"哪个是实测、哪个是推断"，不要让用户自己裁决
+
+## 硬规则
+
+- **永不**把 `~/.dsh/secrets.env`、`.credentials.yaml`、`~/.dsh/sessions/` 提交进仓库；真实 key 只在 `secrets.env`（`chmod 600`）。
+- **永不** `git push --force`：会覆盖另一台的历史。冲突一律手工合并。
+- `--mirror` 会删本机技能：先问用户，先用 `--dry-run` 看会删什么。
+- `apply.sh --yes` 会覆盖本机 `~/.dsh` 配置（旧文件留 `.bak-<时间戳>`）：第一次必须让用户先看 dry-run 输出。
+- 推送前必须能说清「改了哪些技能 / 有没有动配置」；说不清就先 `git diff --stat`。
+- **reasoningEffort 永不同步**：模型/强度是本机状态。不要用 `sync.sh` 推送它，也不要用 `update.sh --all` 覆盖它；脚本已内置双向保留，别绕过脚本手工改仓库里的这一行。
+- 汇报必须带证据：技能数、commit 短哈希、是否已推送。没成功就写「未同步」+ 原因，不许用「应该没问题」代替验收。
+
+## 跨平台回归（改脚本后必跑）
+
+```bash
+cd ~/dsh-config && bash scripts/cross-platform-selftest.sh
+```
+
+它在临时目录里模拟「两台机器 + 一个本地裸远端」：A（macOS 风格）→ pack/sync → B（HOME 带空格、无 rsync）→ update/apply/doctor → B 反向 push → A 拉取。覆盖绝对 `link:` 归一化、密钥脱敏/注入、`reasoningEffort` 双向保留、CRLF、无 rsync 兜底。GitHub Actions 在 ubuntu / macOS / Windows 三个 runner 上跑同一份；Windows 还会冒烟 `scripts\win\pack.cmd`。
+
+## 汇报格式（中文，≤12 行）
+
+1. **结论**：已一致 / 拉取了 N 个技能 / 推送了 commit `abc1234` / 失败原因
+2. **变化**：改动的技能名（超过 10 个只列前 10 + 共几个）；是否动了配置/插件
+3. **生效**：新开会话（技能）/ 重启客户端（插件）
+4. **待办**：缺密钥、冲突未合、推送失败等

package/client/client.js

@@ -0,0 +1,115 @@
+/**
+ * Browser half: one compact chip in the composer dock.
+ *
+ * It reads the host route registered by `lib/core/http.js` — no websocket, no
+ * shared state, no second data channel to keep consistent. The chip is
+ * deliberately small: a dot whose colour encodes "clean / drift / error", the
+ * branch, and the ahead/behind counts. Clicking it re-fetches.
+ *
+ * Plain JavaScript, no build step: the module table supplies React.
+ */
+
+window.__ModuleLoader__.load({
+  id: 'dsh-syn-config',
+  factory(require) {
+    const React = require('react')
+    const h = React.createElement
+    const STATUS_URL = '/plugins/dsh-syn-config/status'
+
+    /** Fetch the host status once; abort on unmount. */
+    function useStatus() {
+      const [state, setState] = React.useState({ phase: 'loading' })
+      const [nonce, setNonce] = React.useState(0)
+      React.useEffect(() => {
+        const controller = new AbortController()
+        let alive = true
+        fetch(STATUS_URL, { signal: controller.signal, headers: { accept: 'application/json' } })
+          .then((response) => (response.ok ? response.json() : Promise.reject(new Error(`HTTP ${response.status}`))))
+          .then((body) => {
+            if (alive) setState({ phase: 'ready', body })
+          })
+          .catch((error) => {
+            if (alive && error?.name !== 'AbortError') setState({ phase: 'error', message: String(error?.message ?? error) })
+          })
+        return () => {
+          alive = false
+          controller.abort()
+        }
+      }, [nonce])
+      return [state, () => setNonce((value) => value + 1)]
+    }
+
+    /** Colour + label for the current state. */
+    function describe(state) {
+      if (state.phase === 'loading') return { color: '#8a8a8a', label: '检查中…' }
+      // The desktop build may serve the UI over IPC without exposing the route;
+      // that is not a plugin failure, so do not paint it red.
+      if (state.phase === 'error') return { color: '#8a8a8a', label: '同步就位' }
+      const body = state.body
+      if (body.repoPresent !== true) return { color: '#ef7272', label: '无仓库' }
+      if (body.ok !== true) return { color: '#ef7272', label: '读取失败' }
+      const drift = (body.ahead ?? 0) + (body.behind ?? 0) + (body.dirty ?? 0)
+      if (drift > 0) {
+        const parts = []
+        if (body.ahead > 0) parts.push(`↑${body.ahead}`)
+        if (body.behind > 0) parts.push(`↓${body.behind}`)
+        if (body.dirty > 0) parts.push(`±${body.dirty}`)
+        return { color: '#e0a33e', label: `${body.branch || 'HEAD'} ${parts.join(' ')}` }
+      }
+      return { color: '#51b976', label: `${body.branch || 'HEAD'} 已同步` }
+    }
+
+    function StatusChip() {
+      const [state, refresh] = useStatus()
+      const { color, label } = describe(state)
+      const title = state.phase === 'ready'
+        ? `${state.body.repoPath ?? ''}\n${label}\n点击刷新`
+        : state.phase === 'error'
+          ? '状态接口在本组合不可用；用 /syn-dsh status 查看'
+          : label
+      return h('button', {
+        type: 'button',
+        onClick: refresh,
+        title,
+        style: {
+          display: 'inline-flex',
+          alignItems: 'center',
+          gap: '6px',
+          padding: '3px 9px',
+          font: 'inherit',
+          fontSize: '12px',
+          lineHeight: '16px',
+          color: 'var(--dsw-alias-label-secondary, #b9b9b9)',
+          background: 'transparent',
+          border: '0.5px solid var(--dsw-alias-border-l2, #494949)',
+          borderRadius: '999px',
+          cursor: 'pointer',
+        },
+      },
+        h('span', {
+          'aria-hidden': true,
+          style: { width: '7px', height: '7px', borderRadius: '50%', background: color, display: 'inline-block' },
+        }),
+        h('span', null, label),
+      )
+    }
+
+    return {
+      inject: ['slots'],
+      apply(ctx) {
+        // A missing slot must cost the chip, not the whole client plugin: the
+        // host UI owns the slot table and may rename it between versions.
+        try {
+          ctx.slots.inject('conversation.composer.dock', () => ctx.slots.register({
+            name: 'conversation.composer.dock',
+            id: 'dsh-syn-config-status',
+            order: 40,
+          }, StatusChip))
+        } catch (error) {
+          // eslint-disable-next-line no-console -- there is no logger in the browser half
+          console.warn(`dsh-syn-config: status chip not mounted (${String(error?.message ?? error)})`)
+        }
+      },
+    }
+  },
+})

package/cordis.patch.yml

@@ -0,0 +1,17 @@
+# dsh-syn-config — bundle patch for DeepSeek Harness.
+#
+# Applied as a profile bundle layer (the `dsh.bundle.patch` manifest field).
+# The row resolves this package by name through the profile's node_modules;
+# everything the plugin does lives in the host half (lib/index.js).
+#
+# Optional per-profile settings — uncomment and edit to override the defaults
+# (default repo path is `~/dsh-config`, git timeout 15 s, no network on status):
+#
+#   config:
+#     repoPath: '~/dsh-config'
+#     profile: 'desktop'
+#     gitTimeoutMs: 15000
+#     fetchOnStatus: false
+- insert:
+    - id: dsh-syn-config
+      name: 'dsh-syn-config'