dsh-siyuan-bridge 0.6.3 → 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.
package/README.md CHANGED
@@ -1,179 +1,228 @@
1
- # 思源桥 · SiYuan Bridge(完整插件包 v0.6.3)
2
-
3
- > **即装即用**:纯 npm 包形态,通过 DSH 插件页或 `pnpm add dsh-siyuan-bridge` 安装,bundle 由 `cordis.patch.yml` 自动挂载,无需双击安装器、无需手工配置。
4
- > 面板包 **v0.6.3** · 桥接服务 **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.3) |
23
- | --- | --- | --- |
24
- | 安装 | `github:` 依赖 + 手工改 `cordis.patch.yml` | **DSH 插件页 / `pnpm add`**,bundle / 配置 / 服务全自动 |
25
- | 装完 | 还要跑一次 `node setup.mjs` 写 `service/config.json` | 首次运行自动探测并写配置,**无需任何手工步骤** |
26
- | 服务 | 手工双击 `start.cmd` | Host 半身拉起;每 60s 探活自举 |
27
- | 分发 | 只存在于 `node_modules`,重装即被替换 | **npm 包**,随 DSH 插件页 / pnpm 安装即用 |
28
- | 换机 | clone 仓库 / pnpm / 可能超时 | DSH 插件页重装 / `pnpm add`,重装不丢稳定数据 |
29
- | 校验 | 无 | `smoke.mjs` / `verify:lifecycle` |
30
- | 回滚 | 手工清理 | 插件页卸载 / `pnpm remove`,使用者数据保留 |
31
- | 凭据 | 本机配置文件 | 包内零凭据,token 由服务端从工作空间 `conf/conf.json` 注入 |
32
-
33
- ---
34
-
35
- ## 安装(标准流程,无需双击安装器)
36
-
37
- 本插件是纯 npm 包形态:bundle 由 `cordis.patch.yml` 自动挂载,首次运行由 `setup.mjs` 写 `service/config.json` 并装好思源侧插件,服务随 DSH 自动拉起。两种安装方式:
38
-
39
- - **方式 A(推荐)**:在 DSH 插件页粘贴仓库地址 `https://github.com/Lau-Jin/dsh-siyuan-bridge` 安装。
40
- - **方式 B**:在 DSH 的 profile 下执行 `pnpm add dsh-siyuan-bridge`,重启 DSH,bundle 自动挂载、服务自动起。
41
-
42
- 安装后 DSH 左侧边栏「思源桥」即可直接使用;浏览器也可访问 `http://127.0.0.1:5599/`。首次打开若还没选笔记数据来源,面板顶部会出现「首次使用」横幅。
43
-
44
- **卸载**:`pnpm remove dsh-siyuan-bridge`,或在 DSH 插件页卸载;稳定数据目录与思源工作空间完整保留。
45
-
46
- ### 安装后自动完成什么
47
-
48
- | # | 动作 | 说明 |
49
- | --- | --- | --- |
50
- | 1 | 注册 bundle | `pnpm add` 把包装进 profile 的 `node_modules`,`cordis.patch.yml` 由 DSH 自动插入并挂载 |
51
- | 2 | 探测环境 | **优先沿用运行中服务在用的工作空间与内核模式**;否则按环境变量 → 常见位置探测,不做全盘扫描 |
52
- | 3 | 写运行时配置 | 首次运行 `setup.mjs` 写稳定数据目录 + 包内 `service/config.json`,**与已有配置合并、写前备份**,零凭据 |
53
- | 4 | 装思源侧插件 | 复制 `service/plugin/` 到工作空间并启用集市状态 |
54
- | 5 | 拉起服务 | Host 半身探测 5599 端口,未在线就拉起 `service/server.mjs` 并等待就绪 |
55
- | 6 | 打开面板 | DSH 侧边栏内嵌面板;默认浏览器访问也可 |
56
-
57
- > **为什么不需要手工配置**:bundle 挂载与挂载点都由 `cordis.patch.yml` 声明,Host 半身(`lib/index.js`)按自身相对路径找 `../service/server.mjs`,浏览器半身由 `package.json` 的 `dsh.client` 声明。装完即可见面板。
58
-
59
- ### 前置条件
60
-
61
- - Node.js **>= 18**(DeepSeek Harness 自带)
62
- - DSH 的 profile 目录可写(安装即写 `node_modules` 与 `cordis.patch.yml`)
63
- - 安装需要 **pnpm**(方式 B)或 DSH 插件页(方式 A);装好后日常使用无需联网、git
64
- - 思源桌面端与工作空间**可选**:没有也能装好,面板会引导选择数据来源
65
-
66
- ---
67
-
68
- ## 首次使用:选笔记数据来源
69
-
70
- **完整包里只有代码(约 1.2 MB),不含任何笔记数据**。这是刻意的:数据仓约 268 MB 且含个人笔记,不随代码分发。
71
-
72
- 装完第一次打开面板,若没探测到工作空间,顶部横幅给四条路:
73
-
74
- | 方式 | 做什么 | 适合谁 |
75
- | --- | --- | --- |
76
- | **自动检测并应用** | 在常见位置找思源与工作空间,找到立刻生效 | 本机已有思源/数据仓 |
77
- | **指定已有工作空间** | 填一个含 `data/` 与 `conf/` 的绝对路径 | 思源装在别处 |
78
- | **从数据仓克隆** | 面板直接 `git clone` + `git lfs pull`,再指向它的 `workspace/` | 换机、新同事 |
79
- | **新建空白工作空间** | 建空工作空间,只要功能不要历史笔记 | 新起点 |
80
-
81
- 选完立刻生效,配置同时写入稳定数据目录,**重装插件也不丢**。
82
-
83
- ### 数据与隐私
84
-
85
- - 包内**零凭据**:内核 token 只存在于思源工作空间的 `conf/conf.json`,由服务端注入请求,浏览器和包都拿不到;
86
- - 服务只监听 `127.0.0.1`,写操作校验同源,**任意公网页面不能改你的笔记**;
87
- - 待入库队列、丢弃归档、备份默认放稳定数据目录(`~/.dsh/siyuan-bridge/`),在 `node_modules` 之外,重装不丢;
88
- - 笔记本体始终在思源工作空间里,与桌面端共享。
89
-
90
- ---
91
-
92
- ## 校验、卸载、升级
93
-
94
- ```bash
95
- node smoke.mjs # 完整自检:隔离端口 + 临时目录 + 假内核
96
- node tools/verify-lifecycle.mjs # 生命周期自检:禁用即停 → 重启用自动恢复
97
- npm run check # 全部脚本语法检查
98
- npm run serve # 手动只起桥接服务
99
- ```
100
-
101
- `smoke.mjs` 全程隔离:不碰真实工作空间、不启动真实内核、不改 profile、不重启现网服务。
102
-
103
- **升级**:`pnpm add dsh-siyuan-bridge@latest`(或 DSH 插件页更新),bundle 与配置自动更新,重复安装不会破坏你后来改过的设置。
104
- **卸载**:`pnpm remove dsh-siyuan-bridge` 或 DSH 插件页卸载;稳定数据目录与笔记数据保留。运行中的桥接服务默认随插件停用而停止,避免打断正在写的笔记。
105
-
106
- ### 命令速查
107
-
108
- | 想做什么 | 命令 |
109
- | --- | --- |
110
- | 安装 | `pnpm add dsh-siyuan-bridge`(或 DSH 插件页) |
111
- | 卸载 | `pnpm remove dsh-siyuan-bridge`(或 DSH 插件页) |
112
- | 自检 | `node smoke.mjs` |
113
- | 生命周期自检 | `node tools/verify-lifecycle.mjs` |
114
- | 只起服务 | `npm run serve` |
115
- | 开机自启(可选) | `node setup.mjs --autostart` |
116
- | 全库体检(渲染是否失真) | `npm run audit` |
117
- | 单篇诊断 | `npm run audit:doc 文档标题` |
118
- | 裸 SQL 整理成代码块 | `npm run fix:sql`(默认预览,`--apply` 才写) |
119
-
120
- ---
121
-
122
- ## 目录
123
-
124
- | 路径 | 内容 |
125
- | --- | --- |
126
- | `smoke.mjs` | 隔离冒烟自检 |
127
- | `setup.mjs` | 首次运行写 `service/config.json` + 装思源侧插件(保留) |
128
- | `plugin.json` | 机器可读清单(入口、自动化、安全、分发约定) |
129
- | `package.json` / `lib/` / `cordis.patch.yml` | DSH 面板插件(Host 半身 + 浏览器半身) |
130
- | `service/server.mjs` | 桥接服务:内核代理、块级 diff 保存、导出、待入库 |
131
- | `service/public/` | 面板网页(原生 JS,无构建) |
132
- | `service/plugin/` | 思源侧插件(在思源里开原生页签) |
133
- | `service/watchdog.vbs` / `start-hidden.vbs` | 静默启动 + 探活自愈(可选) |
134
- | `start.cmd` / `start.sh` | 手动启服务的辅助脚本(保留兼容) |
135
- | `tools/` | 体检、诊断、SQL 整理等维护脚本 |
136
- | `操作使用手册.html` | 自包含单页手册(离线可读) |
137
- | `.gitignore` | 排除安装后生成的本机产物 |
138
-
139
- 安装后会在包内生成 `service/config.json`(Host 自举时没有环境变量,读这一份);运行日志写在稳定数据目录的 `bridge.log`(`SIYUAN_BRIDGE_DATA`,默认 `%LOCALAPPDATA%\siyuan-bridge\data`)。**两者都是本机运行时产物,不属于分发包**(已由 `.gitignore` 排除)。
140
-
141
- ---
142
-
143
- ## 常见问题
144
-
145
- **Q:装完 DSH 侧边栏没出现「思源桥」?**
146
- 先跑 `node smoke.mjs` 看是否通过。多数情况是 profile 目录不对或 `cordis.patch.yml` 被其它配置覆盖。完全退出并重新打开 DSH 可强制重新加载 bundle;用 DSH 插件页安装时确认仓库地址 `https://github.com/Lau-Jin/dsh-siyuan-bridge` 正确。
147
-
148
- **Q:服务没起 / 面板显示「桥接服务没有响应」?**
149
- 手动 `npm run serve` 拉起一次看控制台;日志在稳定数据目录的 `bridge.log`(`SIYUAN_BRIDGE_DATA` 指向哪里就在哪里,默认 `%LOCALAPPDATA%\siyuan-bridge\data`)。Host 半身每 60 秒探活一次,服务挂了会自愈。
150
-
151
- **Q:会不会覆盖我现有的笔记?**
152
- 不会。服务不直接改 `.sy` 文件,一切写入都经思源内核 HTTP API;「待入库」队列里的文档要你确认后才会写进思源。
153
-
154
- **Q:旧机器上的数据怎么迁过来?**
155
- 用面板「从数据仓克隆」,或把思源工作空间整个拷过来后在「指定已有工作空间」里填路径。代码包与数据包分开维护。
156
-
157
- **Q:关掉面板 / 禁用插件之后,服务还在跑吗?**
158
- - **关掉面板**:服务继续跑。面板只是个 iframe,而服务托管着思源内核(6814)、每 15 秒做「待入库」收件——藏起界面不该打断这些。面板左下角会明说:`宿主已连接` / `宿主已关闭 · 服务仍在后台`。
159
- - **禁用或卸载插件**:服务**跟着停**。宿主半身在 dispose 时停掉服务并写暂停标记,看门狗与宿主自愈都不会再拉起——你用界面表达了"不要它",后台就不该还活着。
160
- - **重新启用插件**:服务**自动恢复**(标记里记了来源,见下)。
161
-
162
- 要手动停:点面板左下角 **停止服务**(写暂停标记,思源内核与笔记不受影响)。恢复:运行 `start.cmd` / `start.sh` 或 `npm run serve`——都会清标记并重新武装自愈。
163
-
164
- 暂停标记里记了「谁停的」,两种来源语义不同:`panel` = 你按了停止按钮,只能由你明确恢复,重新启用插件也不会自己爬起来;`plugin-disabled` = 随插件一起停的,插件再次加载就自动恢复。命令行等价物:`curl -X POST http://127.0.0.1:5599/api/shutdown -H "Content-Type: application/json" -d '{"by":"panel"}'`。
165
-
166
- **Q:不装思源能用吗?**
167
- 不能。这不是独立笔记应用,而是**思源数据的访问层**:笔记库是思源的(`.sy` + SQLite 索引),解析、块 ID、全文搜索、资源文件全由思源内核提供。没有内核时服务仍能启动、面板能打开、待入库队列能排队,但笔记本、目录树、正文、搜索、导出、保存全部报 `fetch failed`。
168
- 两种模式都依赖内核,区别只是谁来启动它:**托管模式**由桥接服务拉起 `SiYuan-Kernel.exe`(不用装桌面端),**桌面端模式**连接你已经打开的思源(默认 6806)。
169
- 换句话说:不想要思源、只想要个 Markdown 笔记库,那是另一个产品。
170
-
171
- **Q:卸载会不会删数据?**
172
- 不会。`pnpm remove dsh-siyuan-bridge` 或插件页卸载只移除 DSH 侧的注册,稳定数据目录与思源工作空间完整保留。它会顺手停掉后台服务(与「禁用即停」一致)。
173
-
174
- ---
175
-
176
- ## 更多文档
177
-
178
- - `操作使用手册.html` — 安装、验证、换机、卸载、排障(离线单页)
179
- - 版本变更、面板功能、自动化、同步等技术说明随仓库 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.3'
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,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-siyuan-bridge",
3
- "version": "0.6.3",
3
+ "version": "0.6.6",
4
4
  "type": "module",
5
5
  "description": "思源桥 · 即装即用的完整插件:自动注册 DSH bundle、自动探测思源与工作空间、自动起服务与面板。零第三方依赖、零预置凭据、笔记数据不随包分发。",
6
6
  "repository": {