dsh-siyuan-bridge 0.6.2 → 0.6.6

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.
Files changed (35) hide show
  1. package/README.md +228 -197
  2. package/lib/index.js +1 -1
  3. package/package.json +6 -16
  4. package/plugin.json +118 -133
  5. package/service/debug/test_autostage.mjs +109 -95
  6. package/service/debug/test_code_block_edit.mjs +202 -0
  7. package/service/debug/test_import_fidelity.mjs +278 -0
  8. package/service/debug/test_version_ui.mjs +127 -0
  9. package/service/package.json +1 -1
  10. package/service/public/app.js +222 -3
  11. package/service/public/index.html +3 -0
  12. package/service/public/style.css +46 -0
  13. package/service/rollback.cjs +204 -0
  14. package/service/save-doc.mjs +279 -260
  15. package/service/server.mjs +217 -11
  16. package/smoke.mjs +302 -290
  17. package//346/223/215/344/275/234/344/275/277/347/224/250/346/211/213/345/206/214.html +82 -83
  18. package/docs/2026-11-06-/346/200/235/346/272/220/346/241/245/346/217/222/344/273/266/344/270/216/345/206/205/346/240/270/346/250/241/345/274/217/351/227/256/351/242/230/346/225/264/347/220/206.md +0 -53
  19. package/docs/2026-11-10-/345/276/205/345/205/245/345/272/223/344/270/216/345/267/262/344/270/242/345/274/203/344/270/244/346/240/217.md +0 -75
  20. package/docs/AUTOMATION.md +0 -71
  21. package/docs/CHANGELOG.md +0 -347
  22. package/docs/DATA-PLAN.md +0 -188
  23. package/docs/INSTALL.md +0 -208
  24. package/docs/LEGACY-README-0.4.5.md +0 -272
  25. package/docs/PANEL.md +0 -122
  26. package/docs/SYNC.md +0 -71
  27. package/docs/open-in-siYuan.md +0 -57
  28. package/docs/screens/stage-tabs-light.png +0 -0
  29. package/docs/screens/stage-tabs.png +0 -0
  30. package/docs/staging-queue.md +0 -72
  31. package/install.mjs +0 -754
  32. package/install.sh +0 -30
  33. package//344/270/200/351/224/256/345/256/211/350/243/205.cmd +0 -46
  34. package//344/270/200/351/224/256/345/256/211/350/243/205.command +0 -30
  35. package//344/270/200/351/224/256/345/256/211/350/243/205.vbs +0 -93
package/README.md CHANGED
@@ -1,197 +1,228 @@
1
- # 思源桥 · SiYuan Bridge(完整插件包 v0.6.2)
2
-
3
- > **装上即用**:整个目录拷到任何一台机器,双击一下就装好,不需要命令行、不需要联网、不需要 npm / git、不需要重启 DSH。
4
- > 面板包 **0.6.2** · 桥接服务 **0.24.6** · 零第三方依赖 · 零预置凭据 · 笔记数据不随包分发。
5
-
6
- ---
7
-
8
- ## 一句话说明
9
-
10
- 思源桥把 SiYuan 的**搜索 / 阅读 / 编辑 / 导出**界面嵌进 DeepSeek Harness 的主面板,并能在思源里开原生页签。
11
- 一切读写都走**正在运行的思源内核 HTTP API**,服务代为注入内核 token,所以索引、反链、关系图与桌面端窗口始终一致。
12
-
13
- ```
14
- 思源页签(思源插件 iframe) ┐
15
- ├─► 桥接服务 127.0.0.1:5599 ──► 思源内核 6806 / 6814 ──► 工作空间 data/
16
- DSH 面板(DSH 插件 iframe) ┤ token 只在服务端
17
- 浏览器(可选) ┘
18
- ```
19
-
20
- ## 和旧版的区别
21
-
22
- | | 旧版(GitHub 源码包 0.4.5) | 本版(完整插件包 0.6.2) |
23
- | --- | --- | --- |
24
- | 安装 | `github:` 依赖 + 手工改 `cordis.patch.yml` | **双击一键安装**,bundle / 配置 / 服务全自动 |
25
- | 装完 | 还要跑一次 `node setup.mjs` 写 `service/config.json` | 安装器自动探测并写配置,**无需任何手工步骤** |
26
- | 服务 | 手工双击 `start.cmd` | 安装器拉起;Host 半身每 60s 探活自举 |
27
- | 分发 | 只存在于 `node_modules`,重装即被替换 | **独立目录整包**,约 1.2 MB,离线拷贝即用 |
28
- | 换机 | clone 仓库 / pnpm / 可能超时 | 拷目录 → 双击 → 完成 |
29
- | 校验 | 无 | `--verify` / `--dry-run` / `smoke.mjs` |
30
- | 回滚 | 手工清理 | `--uninstall` 完整还原,使用者数据保留 |
31
- | 凭据 | 本机配置文件 | 包内零凭据,token 由服务端从工作空间 `conf/conf.json` 注入 |
32
-
33
- 旧版 README 归档在 `docs/LEGACY-README-0.4.5.md`,其它技术文档全部保留在 `docs/`。
34
-
35
- ---
36
-
37
- ## 快速开始(3 步)
38
-
39
- 1. **拷贝整个目录**到目标机器任意位置(路径可以带空格和中文)。
40
- 2. **双击**:
41
- - Windows:`一键安装.vbs`(若被安全策略拦截,改双击 `一键安装.cmd`)
42
- - macOS:`一键安装.command`
43
- - Linux:`bash install.sh`
44
- 3. 浏览器自动打开 `http://127.0.0.1:5599/`;DSH 左侧边栏「思源桥」也可直接用,**不用重启 DSH**。
45
-
46
- 成功时不弹窗、不提问、不要求输入任何命令。首次打开若还没选笔记数据来源,面板顶部会出现「首次使用」横幅。
47
-
48
- ### 安装器具体做了什么
49
-
50
- | # | 动作 | 说明 |
51
- | --- | --- | --- |
52
- | 1 | 找 Node | DSH 自带 → WorkBuddy → 系统 → PATH,找不到才提示 |
53
- | 2 | 注册 bundle | `profile/node_modules/dsh-siyuan-bridge` 建目录联接指向本包,原目录整体挪去备份 |
54
- | 3 | 写 profile 清单 | `package.json` 的 `dependencies` + `dsh.profile.bundles`,写前备份 |
55
- | 4 | 写 `cordis.patch.yml` | 已有 `siyuan-bridge` insert 就**保留原样**,否则插入带标记的块 |
56
- | 5 | 探测环境 | **优先沿用运行中服务在用的工作空间与内核模式**;否则按命令行参数 → 环境变量 → 常见位置探测,不做全盘扫描 |
57
- | 6 | 写运行时配置 | 稳定数据目录 + 包内 `service/config.json` 两处,**与已有配置合并、写前备份**,零凭据 |
58
- | 7 | 装思源侧插件 | 复制 `service/plugin/` 到工作空间并启用集市状态 |
59
- | 8 | 拉起服务 | 服务已在线就**复用不重启**;不在线才启动并等待就绪 |
60
- | 9 | 打开面板 | 默认浏览器;失败也不影响安装结果 |
61
-
62
- > **为什么不需要重启 DSH**:Host 半身按自身相对路径找 `../service/server.mjs`。目录联接一换,已加载的旧 Host 也自动指向新包;浏览器半身由 `package.json` 的 `dsh.client` 声明。
63
-
64
- ### 前置条件
65
-
66
- - Node.js **>= 18**(DeepSeek Harness 自带,安装器会自动找)
67
- - DSH 的 profile 目录可写
68
- - **不需要**联网、npm、git、pnpm
69
- - 思源桌面端与工作空间**可选**:没有也能装好,面板会引导选择数据来源
70
-
71
- ---
72
-
73
- ## 首次使用:选笔记数据来源
74
-
75
- **完整包里只有代码(约 1.2 MB),不含任何笔记数据**。这是刻意的:数据仓约 268 MB 且含个人笔记,不随代码分发。
76
-
77
- 装完第一次打开面板,若没探测到工作空间,顶部横幅给四条路:
78
-
79
- | 方式 | 做什么 | 适合谁 |
80
- | --- | --- | --- |
81
- | **自动检测并应用** | 在常见位置找思源与工作空间,找到立刻生效 | 本机已有思源/数据仓 |
82
- | **指定已有工作空间** | 填一个含 `data/` 与 `conf/` 的绝对路径 | 思源装在别处 |
83
- | **从数据仓克隆** | 面板直接 `git clone` + `git lfs pull`,再指向它的 `workspace/` | 换机、新同事 |
84
- | **新建空白工作空间** | 建空工作空间,只要功能不要历史笔记 | 新起点 |
85
-
86
- 选完立刻生效,配置同时写入稳定数据目录,**重装插件也不丢**。
87
-
88
- ### 数据与隐私
89
-
90
- - 包内**零凭据**:内核 token 只存在于思源工作空间的 `conf/conf.json`,由服务端注入请求,浏览器和包都拿不到;
91
- - 服务只监听 `127.0.0.1`,写操作校验同源,**任意公网页面不能改你的笔记**;
92
- - 待入库队列、丢弃归档、备份默认放稳定数据目录(`~/.dsh/siyuan-bridge/`),在 `node_modules` 之外,重装不丢;
93
- - 笔记本体始终在思源工作空间里,与桌面端共享。
94
-
95
- ---
96
-
97
- ## 校验、回滚、升级
98
-
99
- ```bash
100
- node install.mjs --dry-run # 预览会改什么,零写入
101
- node install.mjs --verify # 校验安装状态(未安装时只做包自检)
102
- node smoke.mjs # 完整自检:隔离端口 + 临时目录 + 假内核
103
- node install.mjs --uninstall # 回滚,使用者数据完整保留
104
- npm run check # 全部脚本语法检查
105
- ```
106
-
107
- `smoke.mjs` 全程隔离:不碰真实工作空间、不启动真实内核、不改 profile、不重启现网服务。
108
-
109
- **升级**:把新版本整个目录覆盖到原位置,再双击一次安装器即可(幂等,重复运行不会破坏配置)。
110
- **回滚**:`--uninstall` 会恢复原插件目录、profile 依赖与 bundles、移除自动插入的 patch 块;稳定数据目录与笔记数据保留。运行中的桥接服务默认不强制停止,避免打断正在写的笔记。
111
-
112
- ### 命令速查
113
-
114
- | 想做什么 | 命令 |
115
- | --- | --- |
116
- | 双击安装 | `一键安装.vbs` / `.cmd` / `.command` / `install.sh` |
117
- | 命令行安装 | `node install.mjs` |
118
- | 装完打开面板 | `node install.mjs --open` |
119
- | 指定工作空间 | `node install.mjs --workspace=/path/to/workspace` |
120
- | 指定思源程序 | `node install.mjs --siyuan=/path/to/SiYuan.exe` |
121
- | 指定 profile | `node install.mjs --profile=web` |
122
- | 强制重启服务 | `node install.mjs --restart` |
123
- | 只起服务 | `npm run serve` |
124
- | 开机自启(可选) | `node setup.mjs --autostart` |
125
- | 全库体检(渲染是否失真) | `npm run audit` |
126
- | 单篇诊断 | `npm run audit:doc 文档标题` |
127
- | 裸 SQL 整理成代码块 | `npm run fix:sql`(默认预览,`--apply` 才写) |
128
-
129
- ---
130
-
131
- ## 目录
132
-
133
- | 路径 | 内容 |
134
- | --- | --- |
135
- | `install.mjs` | **一键安装 / 校验 / 回滚**(核心) |
136
- | `一键安装.vbs` / `.cmd` / `.command` / `install.sh` | 四平台双击安装器 |
137
- | `smoke.mjs` | 隔离冒烟自检 |
138
- | `plugin.json` | 机器可读清单(入口、自动化、安全、分发约定) |
139
- | `package.json` / `lib/` / `cordis.patch.yml` | DSH 面板插件(Host 半身 + 浏览器半身) |
140
- | `service/server.mjs` | 桥接服务:内核代理、块级 diff 保存、导出、待入库 |
141
- | `service/public/` | 面板网页(原生 JS,无构建) |
142
- | `service/plugin/` | 思源侧插件(在思源里开原生页签) |
143
- | `service/watchdog.vbs` / `start-hidden.vbs` | 静默启动 + 探活自愈(可选) |
144
- | `setup.mjs` / `start.cmd` / `start.sh` | 传统命令行安装 / 启服务(保留兼容) |
145
- | `docs/` | 功能、自动化、同步、变更记录等完整技术文档 |
146
- | `操作使用手册.html` | 自包含单页手册(离线可读) |
147
- | `.gitignore` | 排除安装后生成的本机产物 |
148
-
149
- 安装后会在包内生成 `service/config.json`(Host 自举时没有环境变量,读这一份);运行日志写在稳定数据目录的 `bridge.log`(`SIYUAN_BRIDGE_DATA`,默认 `%LOCALAPPDATA%\siyuan-bridge\data`)。**两者都是本机运行时产物,不属于分发包**(已由 `.gitignore` 排除)。
150
-
151
- ---
152
-
153
- ## 常见问题
154
-
155
- **Q:双击没反应 / 提示找不到 Node?**
156
- 安装器按 DSH 自带 → WorkBuddy → 系统 → PATH 顺序找。可设置环境变量 `SIYUAN_BRIDGE_NODE` 指向 `node.exe`,或直接用 `node install.mjs`。
157
-
158
- **Q:装完 DSH 侧边栏没出现「思源桥」?**
159
- 先跑 `node install.mjs --verify` 看是哪一项没过。多数情况是 profile 目录不对(用 `--profile=web` 指定)或 `cordis.patch.yml` 被其它配置覆盖。完全退出并重新打开 DSH 可强制重新加载 bundle。
160
-
161
- **Q:服务没起 / 面板显示「桥接服务没有响应」?**
162
- `node install.mjs` 会再拉起一次;日志在稳定数据目录的 `bridge.log`(`SIYUAN_BRIDGE_DATA` 指向哪里就在哪里,默认 `%LOCALAPPDATA%\siyuan-bridge\data`)。Host 半身每 60 秒探活一次,服务挂了会自愈。
163
-
164
- **Q:会不会覆盖我现有的笔记?**
165
- 不会。服务不直接改 `.sy` 文件,一切写入都经思源内核 HTTP API;「待入库」队列里的文档要你确认后才会写进思源。
166
-
167
- **Q:旧机器上的数据怎么迁过来?**
168
- 用面板「从数据仓克隆」,或把思源工作空间整个拷过来后在「指定已有工作空间」里填路径。代码包与数据包分开维护。
169
-
170
- **Q:关掉面板 / 禁用插件之后,服务还在跑吗?**
171
- - **关掉面板**:服务继续跑。面板只是个 iframe,而服务托管着思源内核(6814)、每 15 秒做「待入库」收件——藏起界面不该打断这些。面板左下角会明说:`宿主已连接` / `宿主已关闭 · 服务仍在后台`。
172
- - **禁用或卸载插件**:服务**跟着停**。宿主半身在 dispose 时停掉服务并写暂停标记,看门狗与宿主自愈都不会再拉起——你用界面表达了"不要它",后台就不该还活着。
173
- - **重新启用插件**:服务**自动恢复**(标记里记了来源,见下)。
174
-
175
- 要手动停:点面板左下角 **停止服务**(写暂停标记,思源内核与笔记不受影响)。恢复:双击 `一键安装.vbs`、运行 `start.cmd`、或 `node install.mjs`——都会清标记并重新武装自愈。
176
-
177
- 暂停标记里记了「谁停的」,两种来源语义不同:`panel` = 你按了停止按钮,只能由你明确恢复,重新启用插件也不会自己爬起来;`plugin-disabled` = 随插件一起停的,插件再次加载就自动恢复。命令行等价物:`curl -X POST http://127.0.0.1:5599/api/shutdown -H "Content-Type: application/json" -d '{"by":"panel"}'`。
178
-
179
- **Q:不装思源能用吗?**
180
- 不能。这不是独立笔记应用,而是**思源数据的访问层**:笔记库是思源的(`.sy` + SQLite 索引),解析、块 ID、全文搜索、资源文件全由思源内核提供。没有内核时服务仍能启动、面板能打开、待入库队列能排队,但笔记本、目录树、正文、搜索、导出、保存全部报 `fetch failed`。
181
- 两种模式都依赖内核,区别只是谁来启动它:**托管模式**由桥接服务拉起 `SiYuan-Kernel.exe`(不用装桌面端),**桌面端模式**连接你已经打开的思源(默认 6806)。
182
- 换句话说:不想要思源、只想要个 Markdown 笔记库,那是另一个产品。
183
-
184
- **Q:卸载会不会删数据?**
185
- 不会。`--uninstall` 只还原 DSH 侧的注册,稳定数据目录与思源工作空间完整保留。它会顺手停掉后台服务(与「禁用即停」一致),想保留就加 `--keep-service`。
186
-
187
- ---
188
-
189
- ## 更多文档
190
-
191
- - `操作使用手册.html` — 安装、验证、换机、回滚、排障(离线单页)
192
- - `docs/PANEL.md` — 面板与桥接服务完整功能
193
- - `docs/INSTALL.md` — 旧版从零安装指南(保留作参考)
194
- - `docs/AUTOMATION.md` — 开机自启与探活自愈
195
- - `docs/SYNC.md` — 双终端同步与冲突处理
196
- - `docs/CHANGELOG.md` — 版本变更
197
- - `docs/LEGACY-README-0.4.5.md` — 旧版 README 归档
1
+ # 思源桥 · SiYuan Bridge(完整插件包 v0.6.6)
2
+
3
+ > **即装即用**:纯 npm 包形态,通过 DSH 插件页或 `pnpm add dsh-siyuan-bridge` 安装,bundle 由 `cordis.patch.yml` 自动挂载,无需双击安装器、无需手工配置。
4
+ > 面板包 **v0.6.6** · 桥接服务 **0.24.9** · 零第三方依赖 · 零预置凭据 · 笔记数据不随包分发。
5
+
6
+ ### v0.6.6 改了什么 · 版本标识与一键回退(2026-11-20)
7
+
8
+ 参考周报插件,面板上加了两样东西:**版本标识**与**版本回退**。
9
+
10
+ | 位置 | 作用 |
11
+ | --- | --- |
12
+ | 侧栏底部徽标 | 一眼看到「现在跑的是哪个版本」(面板包版本 + 桥接服务版本),点开就是「版本与回退」面板 |
13
+ | 「版本与回退」面板 | 列出 npm 上已发布的版本,选一个点「回退到该版本」,面板会短暂断开,完成后重启一次 DSH |
14
+
15
+ 实现要点:
16
+
17
+ - 新增 `GET /api/version`(不联网,秒回)、`GET /api/versions`(查 npm registry)、
18
+ `GET /api/rollback-log`、`POST /api/rollback`;`/api/status` 也带上了版本号;
19
+ - 新增 `service/rollback.cjs`:回退由**独立工人脚本**执行 —— 占位应答器接管 5599 端口 →
20
+ 结束旧服务(目录解锁)→ `pnpm add dsh-siyuan-bridge@<版本>`(并登记供应链冷却期豁免)→
21
+ 校验 → 撤占位器 → 宿主心跳自动拉起新版本。工人会先复制到稳定数据目录,回退时插件目录被换掉也跑得掉;
22
+ - 源码运行(不在 profile 里)时回退不可用,面板会直说原因。
23
+
24
+ 版本:面板包 0.6.5 → **0.6.6**;桥接服务 0.24.8 → **0.24.9**。
25
+
26
+ ### v0.6.5 改了什么 · 代码块编辑手感(2026-11-20)
27
+
28
+ 用户反馈两点:**往代码块里粘贴的命令被压成一行**、**Ctrl+A 总是全选整篇**。
29
+
30
+ | 之前 | 现在 |
31
+ | --- | --- |
32
+ | 代码块里粘贴走 `execCommand('insertText')` —— Chrome 会把换行吃掉,多条命令全挤成一行 | 改成手工插**带真实换行的文本节点**;缩进与空行原样保留(代码块里不再做「公共缩进」规整),并手动补上脏标记(手工插节点不触发 input 事件) |
33
+ | Ctrl+A 一律全选整篇 | 光标在**代码块**里时,Ctrl+A 只选这个代码块(`<pre><code>` 的内容,不含顶部那条 .code-bar);源码/分栏模式下则只选光标所在的 ``` 围栏内容;正文里 Ctrl+A 仍是全选 |
34
+
35
+ 测试:新增 `debug/test_code_block_edit.mjs`(**18/18**,无头 Chrome 真实页面:粘贴多行命令、缩进保留、
36
+ Ctrl+A 只选代码块、正文 Ctrl+A 仍全选、保存后 Markdown 仍是多行代码块、源码模式围栏选择);
37
+ 回归 `test_editor_ux` 36/36、`test_layout` 37/37、`test_paste_top` 10/10。
38
+
39
+ ### v0.6.4 改了什么 · 导入保真度(2026-11-19)
40
+
41
+ 用户反馈「在通用会话里导入的一份文档,格式错误」。根因在写库前的统一规整链
42
+ `normaliseMarkdown = cleanMarkdownArtifacts → fenceShellBlocks → fixMarkdownFences`:
43
+
44
+ | 问题 | 现在 |
45
+ | --- | --- |
46
+ | `fenceShellBlocks` 对**整篇**按空行切块 → 代码块里的空行被当分隔符吃掉、首行缩进被 `trim()` 剥掉、还凭空补 ```bash | 先按围栏切成「围栏区 / 正文区」,**围栏里的内容一个字符都不动**;正文区仍跑原来的 shell 分组 |
47
+ | `cleanMarkdownArtifacts` 收尾的 `\n{3,}\n\n\n` → `\n\n\n` 是**全文**替换 → 代码块内部的连续空行被并掉 | 空行收敛**只在围栏之外**做 |
48
+ | 标题取自 `/^#\s+(.+)$/m` 一把抓 → 代码块里的 `# ====…` 曾被当成标题(60 个等号) | 改为**围栏之外**取 ATX 标题 + 拒绝分隔线 |
49
+ | 标题里 `一网通办 / IM` 的 `/` 换成空格后留下一串三连空格 | 清洗后**连片空格收敛成一个** |
50
+
51
+ 三条取标题的路径(自动接入、`--stage-dir`、`--stdin`)统一走同一口径。
52
+ 新增 `debug/test_import_fidelity.mjs`(**19/19**:真实文档围栏逐行比对、标题回归、
53
+ 裸 shell 分组不回退、未闭合围栏补闭合);`test_autostage` 改用服务真实监听的目录(**11/11**)。
54
+
55
+ ---
56
+
57
+ ## 一句话说明
58
+
59
+ 思源桥把 SiYuan 的**搜索 / 阅读 / 编辑 / 导出**界面嵌进 DeepSeek Harness 的主面板,并能在思源里开原生页签。
60
+ 一切读写都走**正在运行的思源内核 HTTP API**,服务代为注入内核 token,所以索引、反链、关系图与桌面端窗口始终一致。
61
+
62
+ ```
63
+ 思源页签(思源插件 iframe) ┐
64
+ ├─► 桥接服务 127.0.0.1:5599 ──► 思源内核 6806 / 6814 ──► 工作空间 data/
65
+ DSH 面板(DSH 插件 iframe) ┤ token 只在服务端
66
+ 浏览器(可选) ┘
67
+ ```
68
+
69
+ ## 和旧版的区别
70
+
71
+ | | 旧版(GitHub 源码包 0.4.5) | 本版(完整插件包 0.6.3) |
72
+ | --- | --- | --- |
73
+ | 安装 | `github:` 依赖 + 手工改 `cordis.patch.yml` | **DSH 插件页 / `pnpm add`**,bundle / 配置 / 服务全自动 |
74
+ | 装完 | 还要跑一次 `node setup.mjs` 写 `service/config.json` | 首次运行自动探测并写配置,**无需任何手工步骤** |
75
+ | 服务 | 手工双击 `start.cmd` | Host 半身拉起;每 60s 探活自举 |
76
+ | 分发 | 只存在于 `node_modules`,重装即被替换 | **npm 包**,随 DSH 插件页 / pnpm 安装即用 |
77
+ | 换机 | clone 仓库 / pnpm / 可能超时 | DSH 插件页重装 / `pnpm add`,重装不丢稳定数据 |
78
+ | 校验 | 无 | `smoke.mjs` / `verify:lifecycle` |
79
+ | 回滚 | 手工清理 | 插件页卸载 / `pnpm remove`,使用者数据保留 |
80
+ | 凭据 | 本机配置文件 | 包内零凭据,token 由服务端从工作空间 `conf/conf.json` 注入 |
81
+
82
+ ---
83
+
84
+ ## 安装(标准流程,无需双击安装器)
85
+
86
+ 本插件是纯 npm 包形态:bundle 由 `cordis.patch.yml` 自动挂载,首次运行由 `setup.mjs` 写 `service/config.json` 并装好思源侧插件,服务随 DSH 自动拉起。两种安装方式:
87
+
88
+ - **方式 A(推荐)**:在 DSH 插件页粘贴仓库地址 `https://github.com/Lau-Jin/dsh-siyuan-bridge` 安装。
89
+ - **方式 B**:在 DSH 的 profile 下执行 `pnpm add dsh-siyuan-bridge`,重启 DSH,bundle 自动挂载、服务自动起。
90
+
91
+ 安装后 DSH 左侧边栏「思源桥」即可直接使用;浏览器也可访问 `http://127.0.0.1:5599/`。首次打开若还没选笔记数据来源,面板顶部会出现「首次使用」横幅。
92
+
93
+ **卸载**:`pnpm remove dsh-siyuan-bridge`,或在 DSH 插件页卸载;稳定数据目录与思源工作空间完整保留。
94
+
95
+ ### 安装后自动完成什么
96
+
97
+ | # | 动作 | 说明 |
98
+ | --- | --- | --- |
99
+ | 1 | 注册 bundle | `pnpm add` 把包装进 profile 的 `node_modules`,`cordis.patch.yml` 由 DSH 自动插入并挂载 |
100
+ | 2 | 探测环境 | **优先沿用运行中服务在用的工作空间与内核模式**;否则按环境变量 → 常见位置探测,不做全盘扫描 |
101
+ | 3 | 写运行时配置 | 首次运行 `setup.mjs` 写稳定数据目录 + 包内 `service/config.json`,**与已有配置合并、写前备份**,零凭据 |
102
+ | 4 | 装思源侧插件 | 复制 `service/plugin/` 到工作空间并启用集市状态 |
103
+ | 5 | 拉起服务 | Host 半身探测 5599 端口,未在线就拉起 `service/server.mjs` 并等待就绪 |
104
+ | 6 | 打开面板 | DSH 侧边栏内嵌面板;默认浏览器访问也可 |
105
+
106
+ > **为什么不需要手工配置**:bundle 挂载与挂载点都由 `cordis.patch.yml` 声明,Host 半身(`lib/index.js`)按自身相对路径找 `../service/server.mjs`,浏览器半身由 `package.json` 的 `dsh.client` 声明。装完即可见面板。
107
+
108
+ ### 前置条件
109
+
110
+ - Node.js **>= 18**(DeepSeek Harness 自带)
111
+ - DSH 的 profile 目录可写(安装即写 `node_modules` 与 `cordis.patch.yml`)
112
+ - 安装需要 **pnpm**(方式 B)或 DSH 插件页(方式 A);装好后日常使用无需联网、git
113
+ - 思源桌面端与工作空间**可选**:没有也能装好,面板会引导选择数据来源
114
+
115
+ ---
116
+
117
+ ## 首次使用:选笔记数据来源
118
+
119
+ **完整包里只有代码(约 1.2 MB),不含任何笔记数据**。这是刻意的:数据仓约 268 MB 且含个人笔记,不随代码分发。
120
+
121
+ 装完第一次打开面板,若没探测到工作空间,顶部横幅给四条路:
122
+
123
+ | 方式 | 做什么 | 适合谁 |
124
+ | --- | --- | --- |
125
+ | **自动检测并应用** | 在常见位置找思源与工作空间,找到立刻生效 | 本机已有思源/数据仓 |
126
+ | **指定已有工作空间** | 填一个含 `data/` 与 `conf/` 的绝对路径 | 思源装在别处 |
127
+ | **从数据仓克隆** | 面板直接 `git clone` + `git lfs pull`,再指向它的 `workspace/` | 换机、新同事 |
128
+ | **新建空白工作空间** | 建空工作空间,只要功能不要历史笔记 | 新起点 |
129
+
130
+ 选完立刻生效,配置同时写入稳定数据目录,**重装插件也不丢**。
131
+
132
+ ### 数据与隐私
133
+
134
+ - 包内**零凭据**:内核 token 只存在于思源工作空间的 `conf/conf.json`,由服务端注入请求,浏览器和包都拿不到;
135
+ - 服务只监听 `127.0.0.1`,写操作校验同源,**任意公网页面不能改你的笔记**;
136
+ - 待入库队列、丢弃归档、备份默认放稳定数据目录(`~/.dsh/siyuan-bridge/`),在 `node_modules` 之外,重装不丢;
137
+ - 笔记本体始终在思源工作空间里,与桌面端共享。
138
+
139
+ ---
140
+
141
+ ## 校验、卸载、升级
142
+
143
+ ```bash
144
+ node smoke.mjs # 完整自检:隔离端口 + 临时目录 + 假内核
145
+ node tools/verify-lifecycle.mjs # 生命周期自检:禁用即停 → 重启用自动恢复
146
+ npm run check # 全部脚本语法检查
147
+ npm run serve # 手动只起桥接服务
148
+ ```
149
+
150
+ `smoke.mjs` 全程隔离:不碰真实工作空间、不启动真实内核、不改 profile、不重启现网服务。
151
+
152
+ **升级**:`pnpm add dsh-siyuan-bridge@latest`(或 DSH 插件页更新),bundle 与配置自动更新,重复安装不会破坏你后来改过的设置。
153
+ **卸载**:`pnpm remove dsh-siyuan-bridge` 或 DSH 插件页卸载;稳定数据目录与笔记数据保留。运行中的桥接服务默认随插件停用而停止,避免打断正在写的笔记。
154
+
155
+ ### 命令速查
156
+
157
+ | 想做什么 | 命令 |
158
+ | --- | --- |
159
+ | 安装 | `pnpm add dsh-siyuan-bridge`(或 DSH 插件页) |
160
+ | 卸载 | `pnpm remove dsh-siyuan-bridge`(或 DSH 插件页) |
161
+ | 自检 | `node smoke.mjs` |
162
+ | 生命周期自检 | `node tools/verify-lifecycle.mjs` |
163
+ | 只起服务 | `npm run serve` |
164
+ | 开机自启(可选) | `node setup.mjs --autostart` |
165
+ | 全库体检(渲染是否失真) | `npm run audit` |
166
+ | 单篇诊断 | `npm run audit:doc 文档标题` |
167
+ | 裸 SQL 整理成代码块 | `npm run fix:sql`(默认预览,`--apply` 才写) |
168
+
169
+ ---
170
+
171
+ ## 目录
172
+
173
+ | 路径 | 内容 |
174
+ | --- | --- |
175
+ | `smoke.mjs` | 隔离冒烟自检 |
176
+ | `setup.mjs` | 首次运行写 `service/config.json` + 装思源侧插件(保留) |
177
+ | `plugin.json` | 机器可读清单(入口、自动化、安全、分发约定) |
178
+ | `package.json` / `lib/` / `cordis.patch.yml` | DSH 面板插件(Host 半身 + 浏览器半身) |
179
+ | `service/server.mjs` | 桥接服务:内核代理、块级 diff 保存、导出、待入库 |
180
+ | `service/public/` | 面板网页(原生 JS,无构建) |
181
+ | `service/plugin/` | 思源侧插件(在思源里开原生页签) |
182
+ | `service/watchdog.vbs` / `start-hidden.vbs` | 静默启动 + 探活自愈(可选) |
183
+ | `start.cmd` / `start.sh` | 手动启服务的辅助脚本(保留兼容) |
184
+ | `tools/` | 体检、诊断、SQL 整理等维护脚本 |
185
+ | `操作使用手册.html` | 自包含单页手册(离线可读) |
186
+ | `.gitignore` | 排除安装后生成的本机产物 |
187
+
188
+ 安装后会在包内生成 `service/config.json`(Host 自举时没有环境变量,读这一份);运行日志写在稳定数据目录的 `bridge.log`(`SIYUAN_BRIDGE_DATA`,默认 `%LOCALAPPDATA%\siyuan-bridge\data`)。**两者都是本机运行时产物,不属于分发包**(已由 `.gitignore` 排除)。
189
+
190
+ ---
191
+
192
+ ## 常见问题
193
+
194
+ **Q:装完 DSH 侧边栏没出现「思源桥」?**
195
+ 先跑 `node smoke.mjs` 看是否通过。多数情况是 profile 目录不对或 `cordis.patch.yml` 被其它配置覆盖。完全退出并重新打开 DSH 可强制重新加载 bundle;用 DSH 插件页安装时确认仓库地址 `https://github.com/Lau-Jin/dsh-siyuan-bridge` 正确。
196
+
197
+ **Q:服务没起 / 面板显示「桥接服务没有响应」?**
198
+ 手动 `npm run serve` 拉起一次看控制台;日志在稳定数据目录的 `bridge.log`(`SIYUAN_BRIDGE_DATA` 指向哪里就在哪里,默认 `%LOCALAPPDATA%\siyuan-bridge\data`)。Host 半身每 60 秒探活一次,服务挂了会自愈。
199
+
200
+ **Q:会不会覆盖我现有的笔记?**
201
+ 不会。服务不直接改 `.sy` 文件,一切写入都经思源内核 HTTP API;「待入库」队列里的文档要你确认后才会写进思源。
202
+
203
+ **Q:旧机器上的数据怎么迁过来?**
204
+ 用面板「从数据仓克隆」,或把思源工作空间整个拷过来后在「指定已有工作空间」里填路径。代码包与数据包分开维护。
205
+
206
+ **Q:关掉面板 / 禁用插件之后,服务还在跑吗?**
207
+ - **关掉面板**:服务继续跑。面板只是个 iframe,而服务托管着思源内核(6814)、每 15 秒做「待入库」收件——藏起界面不该打断这些。面板左下角会明说:`宿主已连接` / `宿主已关闭 · 服务仍在后台`。
208
+ - **禁用或卸载插件**:服务**跟着停**。宿主半身在 dispose 时停掉服务并写暂停标记,看门狗与宿主自愈都不会再拉起——你用界面表达了"不要它",后台就不该还活着。
209
+ - **重新启用插件**:服务**自动恢复**(标记里记了来源,见下)。
210
+
211
+ 要手动停:点面板左下角 **停止服务**(写暂停标记,思源内核与笔记不受影响)。恢复:运行 `start.cmd` / `start.sh` 或 `npm run serve`——都会清标记并重新武装自愈。
212
+
213
+ 暂停标记里记了「谁停的」,两种来源语义不同:`panel` = 你按了停止按钮,只能由你明确恢复,重新启用插件也不会自己爬起来;`plugin-disabled` = 随插件一起停的,插件再次加载就自动恢复。命令行等价物:`curl -X POST http://127.0.0.1:5599/api/shutdown -H "Content-Type: application/json" -d '{"by":"panel"}'`。
214
+
215
+ **Q:不装思源能用吗?**
216
+ 不能。这不是独立笔记应用,而是**思源数据的访问层**:笔记库是思源的(`.sy` + SQLite 索引),解析、块 ID、全文搜索、资源文件全由思源内核提供。没有内核时服务仍能启动、面板能打开、待入库队列能排队,但笔记本、目录树、正文、搜索、导出、保存全部报 `fetch failed`。
217
+ 两种模式都依赖内核,区别只是谁来启动它:**托管模式**由桥接服务拉起 `SiYuan-Kernel.exe`(不用装桌面端),**桌面端模式**连接你已经打开的思源(默认 6806)。
218
+ 换句话说:不想要思源、只想要个 Markdown 笔记库,那是另一个产品。
219
+
220
+ **Q:卸载会不会删数据?**
221
+ 不会。`pnpm remove dsh-siyuan-bridge` 或插件页卸载只移除 DSH 侧的注册,稳定数据目录与思源工作空间完整保留。它会顺手停掉后台服务(与「禁用即停」一致)。
222
+
223
+ ---
224
+
225
+ ## 更多文档
226
+
227
+ - `操作使用手册.html` — 安装、验证、换机、卸载、排障(离线单页)
228
+ - 版本变更、面板功能、自动化、同步等技术说明随仓库 README 与发行说明维护。
package/lib/index.js CHANGED
@@ -15,7 +15,7 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSy
15
15
  import path from 'node:path'
16
16
  import { fileURLToPath } from 'node:url'
17
17
 
18
- const VERSION = '0.6.1'
18
+ const VERSION = '0.6.6'
19
19
  // 与服务端同一个端口来源,便于自检/多实例把宿主半身指向隔离端口。
20
20
  const PORT = process.env.SIYUAN_BRIDGE_PORT || '5599'
21
21
  const SERVICE = 'http://127.0.0.1:' + PORT
package/package.json CHANGED
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "name": "dsh-siyuan-bridge",
3
- "version": "0.6.2",
3
+ "version": "0.6.6",
4
4
  "type": "module",
5
- "description": "思源桥 · 装上即用的完整插件:双击即装、自动注册 DSH bundle、自动探测思源与工作空间、自动起服务与面板。零第三方依赖、零预置凭据、笔记数据不随包分发。",
5
+ "description": "思源桥 · 即装即用的完整插件:自动注册 DSH bundle、自动探测思源与工作空间、自动起服务与面板。零第三方依赖、零预置凭据、笔记数据不随包分发。",
6
6
  "repository": {
7
7
  "type": "git",
8
- "url": "https://github.com/Lau-Jin/dsh-siyuan-bridge.git"
8
+ "url": "git+ssh://git@github.com:Lau-Jin/dsh-siyuan-bridge.git"
9
9
  },
10
10
  "homepage": "https://github.com/Lau-Jin/dsh-siyuan-bridge",
11
11
  "bugs": {
@@ -24,24 +24,18 @@
24
24
  "locale/*.json",
25
25
  "icon.svg",
26
26
  "service",
27
+ "!service/config.json",
27
28
  "service/debug",
28
29
  "tools",
29
- "docs",
30
30
  "cordis.patch.yml",
31
31
  "plugin.json",
32
- "install.mjs",
33
32
  "smoke.mjs",
34
33
  "setup.mjs",
35
34
  "start.cmd",
36
35
  "start.sh",
37
- "install.sh",
38
- "一键安装.vbs",
39
- "一键安装.cmd",
40
- "一键安装.command",
41
36
  "操作使用手册.html",
42
37
  "README.md",
43
- ".gitignore",
44
- "!service/config.json"
38
+ ".gitignore"
45
39
  ],
46
40
  "comment:distribution": "完整包零第三方依赖,整个目录拷贝即可分发;运行时产物 service/config.json 与稳定数据目录下的 bridge.log、data/ 由 .gitignore 排除,不属于分发包。",
47
41
  "dsh": {
@@ -58,14 +52,10 @@
58
52
  "@deepseek-ai/cordis": "~4.0.5"
59
53
  },
60
54
  "scripts": {
61
- "setup": "node install.mjs",
62
- "verify": "node install.mjs --verify",
63
- "uninstall": "node install.mjs --uninstall",
64
- "dry-run": "node install.mjs --dry-run",
65
55
  "smoke": "node smoke.mjs",
66
56
  "verify:lifecycle": "node tools/verify-lifecycle.mjs",
67
57
  "serve": "node service/server.mjs",
68
- "check": "node --check install.mjs && node --check smoke.mjs && node --check setup.mjs && node --check lib/index.js && node --check lib/client.js && node --check service/server.mjs && node --check service/bridge-cli.mjs && node --check service/save-doc.mjs && node --check service/plugin/index.js && node --check service/public/app.js && node --check tools/verify-lifecycle.mjs && node --check tools/audit-render.mjs && node --check tools/inspect-doc.mjs && node --check tools/fix-sql-blocks.mjs && node --check service/html-repair.mjs",
58
+ "check": "node --check smoke.mjs && node --check setup.mjs && node --check lib/index.js && node --check lib/client.js && node --check service/server.mjs && node --check service/bridge-cli.mjs && node --check service/save-doc.mjs && node --check service/plugin/index.js && node --check service/public/app.js && node --check tools/verify-lifecycle.mjs && node --check tools/audit-render.mjs && node --check tools/inspect-doc.mjs && node --check tools/fix-sql-blocks.mjs && node --check service/html-repair.mjs",
69
59
  "audit": "node tools/audit-render.mjs",
70
60
  "audit:doc": "node tools/inspect-doc.mjs",
71
61
  "fix:sql": "node tools/fix-sql-blocks.mjs"