@zmskco/dsh-notebook 0.1.0 → 0.2.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/LICENSE CHANGED
@@ -1,23 +1,23 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 dsh-notebook contributors
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
22
-
23
- The bundled icons are drawn from Lucide (https://lucide.dev), ISC licensed.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 dsh-notebook contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
22
+
23
+ The bundled icons are drawn from Lucide (https://lucide.dev), ISC licensed.
package/README.md CHANGED
@@ -1,96 +1,238 @@
1
- # 笔记本 (Notebook)
2
-
3
- DeepSeek Harness(DSH)插件:**工作区里的 markdown 笔记本** —— 目录树、所见即所得编辑、自动保存,右侧嵌着 AI 对话。
4
-
5
- - **Host 半边**:一个认证过的 JSON 控制面(读树、读写文件、建文件/目录、打开资源管理器、写工作区 README)。
6
- - **Client 半边**:侧边栏入口 + 三栏面板(目录 · 文档 · 对话)。
7
- - **没有工具、没有 skill、没有渲染管线**:面板编辑的就是工作区里的真实文件,模型用自己的 `read`/`write` 工具读写同一批文件。
8
-
9
- ## 安装(npm)
10
-
11
- 发布到 npm 后,在 DSH 里安装这个 bundle:
12
-
13
- ```text
14
- 安装 @zmskco/dsh-notebook 这个插件
15
- ```
16
-
17
- (等价于让插件管理把这个包加进 profile 的依赖与 bundle 列表。)要求:DSH `^0.2.2-alpha.2`、Node `>=20`,声明在 `package.json` 的 `engines` 里,版本不符会被管理工具拒绝安装。装好后侧边栏出现「笔记本」。
18
-
19
- ## 功能
20
-
21
- | 区域 | 用法 |
22
- | --- | --- |
23
- | 目录区(左) | 工作区文件树:点文件夹展开/折叠,点文件在中间打开;行首是文件夹/文件图标 |
24
- | 文档区(中) | 默认所见即所得;`写作` / `源码` 两个按钮切换;字数与保存状态在右端 |
25
- | 对话区(右) | 当前会话的对话;可隐藏(标题行最右端),隐藏只是不绘制,不卸载 |
26
-
27
- - **两个新建图标 + 刷新 + 打开资源管理器**在目录列标题行右端,紧挨对话开关:`new-dir` / `new-file` / `refresh` / `reveal`。
28
- - 新建是**就地命名**:点图标后目标目录里出现一行空名字,回车创建;空名字回车或 Esc 取消;输入法组字时回车不误触发。
29
- - **文件名就是输入的名字,不补 `.md`**:输「第一章」得到 `第一章`;输「素材.md」得到 `素材.md`。重名时在扩展名前加序号(`名-2.md`)。
30
- - **首次打开写一份 `README.md` 到工作区根目录**(`op=ensure-readme`),内容固定,且**只写不覆盖**。
31
- - **排版**:字体 `黑 / 宋 / 霞 / 阿`(本机字体栈,不打包字体文件)、字号 13–24、纸色 `简白 / 雅致 / 黑夜 / 绿荫`——**纸色作用于整个面板**(左栏、编辑区、对话区同一张纸),默认简白。
32
- - **编辑器**:ProseMirror 内核;markdown ↔ 文档模型双向转换,schema 表达不了的块(front matter、表格)作为 raw 块逐字保留;**文件里单个换行在页面上就是换行**(写回为行尾两空格 + 换行)。
33
- - **自动保存**:停笔 900ms 写盘,`Ctrl/Cmd+S` 立即保存;切换文件先把当前缓冲写掉。**没有保存按钮**。
34
- - **目录树**:`node_modules` 与点开头条目不列出;大目录有 2000 条上限。
35
-
36
- ## 树根与权限
37
-
38
- **树根 = 调用方 Session 的 `header.cwd`**,也就是操作者打开的工作区:
39
-
40
- | 规则 | 触发条件 | 结果 |
41
- | --- | --- | --- |
42
- | `override` | profile 行里配了 `rootDir` | 用该目录 |
43
- | `workspace` | 有 Session 且未配 `rootDir` | 该 Session 的工作区 |
44
- | `fallback` | 无 Session、无 `rootDir` | 部署写边界,否则 `<DSH_HOME>/glimmer` |
45
-
46
- 每次调用都从调用方 Session 解析,所以写入天然落在该 Session 沙箱已允许的目录里;写盘带 `{ mode, workspaceRoot }` 盖章。`op=focus` 把会话工作目录对齐到同一目录,让模型的相对路径与面板一致。
47
-
48
- ## 配置
49
-
50
- `cordis.patch.yml` 的 `notebook` 行只有一个字段:
51
-
52
- | 字段 | 默认 | 说明 |
53
- | --- | --- | --- |
54
- | `rootDir` | `null` | 面板的根目录;绝对路径,或相对工作区边界的相对路径。不设则跟随工作区 |
55
-
56
- ## HTTP 控制面
57
-
58
- 所有操作走 `/api/notebook?op=<动作>`,继承 Connection 的 Host/Origin 校验与浏览器认证。
59
-
60
- | `op` | 参数 | 说明 |
61
- | --- | --- | --- |
62
- | `state` | — | 根目录、选择规则、沙箱报告 |
63
- | `files` | `project=''` | 树的平铺清单(目录 + 文件) |
64
- | `file` | `project=''`, `path` | 读一个文本文件 |
65
- | `save-file` | `project=''`, `path`, `content` | 写一个文本文件 |
66
- | `create-dir` | `project=''`, `name`, `dir` | 建目录(名字带分隔符 400,重名 409) |
67
- | `create-file` | `project=''`, `title`, `dir` | 用输入的名字原样建文件;散文名带 `# 标题` |
68
- | `focus` | `project=''` | 把调用方会话的工作目录切到工作区 |
69
- | `reveal` | — | 用系统文件管理器打开工作区;`dryRun` 只回答会启动什么命令 |
70
- | `ensure-readme` | — | 工作区 `README.md`:不存在则写(201),已存在则 `created:false`(200) |
71
-
72
- `project` 只接受空串(工作区本身);故事/分镜/设定集相关的操作在这次简化中全部移除。
73
-
74
- ## 开发
75
-
76
- ```powershell
77
- pnpm install
78
- pnpm run build # host(tsc) + client(tsdown) + 产物契约检查
79
- pnpm test # 类型检查 + 沙箱 + Host 冒烟
80
- npm pack --dry-run # 看 tarball 内容
81
- ```
82
-
83
- - `scripts/check-client.mjs`:产物是 lazy-CJS(`__ModuleLoader__.load`,只用 `react` 外部);槽位注册、字典、树、布局、字体/纸色、编辑器往返、图标与样式契约、以及「故事机制零残留」。
84
- - `scripts/smoke-host.mjs`:不用 DSH 进程即可驱动整个控制面(40 项断言):建文件/目录、读写、路径逃逸、README、reveal、focus、写边界盖章。
85
- - `scripts/check-sandbox.mjs`:写边界报告。
86
-
87
- ## 限制
88
-
89
- - markdown 是子集:嵌套列表、HTML 块、引用式链接、脚注按普通文字处理;表格与 front matter 作为 raw 块保存,不在文档视图里做表格编辑。
90
- - 不渲染 mermaid 之类的文本作图。
91
- - 字体不打包,用本机字体栈;没装会退到同类系统字体。
92
- - 重命名与删除请用系统资源管理器(标题行的「打开」)或让模型操作。
93
-
94
- ## 许可
95
-
96
- MIT。内置图标来自 [Lucide](https://lucide.dev)(ISC)。
1
+ # 笔记本 (Notebook)
2
+
3
+ DeepSeek Harness(DSH)插件:**工作区里的 markdown 笔记本** —— 目录树、所见即所得编辑、自动保存,右侧嵌着 AI 对话。
4
+
5
+ - **Host 半边**:一个认证过的 JSON 控制面(读树、读写文件、建文件/目录、打开资源管理器、写工作区 README)。
6
+ - **Client 半边**:侧边栏入口 + 三栏面板(目录 · 文档 · 对话)。
7
+ - **没有工具、没有 skill、没有渲染管线**:面板编辑的就是工作区里的真实文件,模型用自己的 `read`/`write` 工具读写同一批文件。
8
+
9
+ # 预览效果
10
+
11
+ ![预览效果](./assets/dsh-notebook1.png)
12
+
13
+ ![预览效果](./assets/dsh-notebook3.png)
14
+
15
+ ## 安装
16
+
17
+ deepseek harness 对话安装
18
+
19
+ ```text
20
+ 安装 @zmskco/dsh-notebook 这个插件
21
+ ```
22
+
23
+ 插件选项里面 Github 地址安装
24
+
25
+ ```text
26
+ https://github.com/zmskco/dsh-notebook
27
+ ```
28
+
29
+ 插件选项里面 npmjs 名称安装
30
+
31
+ ```text
32
+ @zmskco/dsh-notebook
33
+ ```
34
+
35
+
36
+
37
+ ## 功能
38
+
39
+ | 区域 | 用法 |
40
+ | --- | --- |
41
+ | 目录区(左) | 工作区文件树:点文件夹展开/折叠,点文件在中间打开(多次点开多个标签页);行首是 **Material Icon Theme** 的类型图标(见下) |
42
+ | 文档区(中) | 顶部是**固定**的排版工具栏 + 文件标签页;下面是正文,只有正文滚动。`写作` / `源码` 两个按钮切换,字数与保存状态在标签行右端 |
43
+ | 对话区(右) | 当前会话的对话;可隐藏(**编辑区工具栏最右端**的对话图标),隐藏只是不绘制,不卸载 |
44
+
45
+ - **目录列标题行右端六个图标**,两组:先 `new-dir` / `new-file`,再 `rename` / `delete`,最后 `refresh` / `reveal`(打开资源管理器)。
46
+ - **重命名与删除是标题行的图标,也是右键菜单项**。标题行这两个不另设「选中」——树里已经有「正在编辑的文件」和「新建落在哪个文件夹」两种标记,再加第三种高亮,会出现三行都像是当前项。所以它们跟着**最后一次手势**:点开一个文件、展开/收起一个文件夹、把标签切到前面、新建出东西——每一个都恰好是「我正在弄这个」。没有目标时两个按钮**禁用**,tooltip 里指名道姓(`重命名「第一章」`);工作区根永远不是目标,它不在自己的树里。
47
+ - **对话区的开关在编辑区工具栏最右端**,不在目录列里:它藏的是整块面板,不是某个文件,所以它跟着那条横贯面板的 header 走。工具栏本身不滚动,只有中间的排版控件在自己的区域里横向滚动——钉在右边缘的开关不能是需要横着找才能找到的东西。
48
+ - **右键菜单**:树里任意一行(以及列标题「笔记本」)右键,出六个动作——新建文件、新建文件夹、重命名、删除、刷新、在资源管理器中打开。见下。
49
+ - 新建是**就地命名**:点图标后目标目录里出现一行空名字,回车创建;空名字回车或 Esc 取消;输入法组字时回车不误触发。
50
+ - **文件名就是输入的名字,不补 `.md`**:输「第一章」得到 `第一章`;输「素材.md」得到 `素材.md`。重名时在扩展名前加序号(`名-2.md`)。
51
+ - **首次打开写一份 `README.md` 到工作区根目录**(`op=ensure-readme`),内容固定,且**只写不覆盖**。
52
+ - **排版**:字体 `黑 / 宋 / 霞 / 阿`(本机字体栈,不打包字体文件)、字号 13–24、纸色 `简白 / 雅致 / 黑夜 / 绿荫`——**纸色作用于整个面板**(左栏、编辑区、对话区同一张纸),默认简白。
53
+ - **编辑器**:ProseMirror 内核;markdown ↔ 文档模型双向转换,schema 表达不了的块(front matter、表格)作为 raw 块逐字保留;**文件里单个换行在页面上就是换行**(写回为行尾两空格 + 换行)。
54
+ - **自动保存**:停笔 900ms 写盘,`Ctrl/Cmd+S` 立即保存;切换/关闭标签页先把该文件缓冲写掉。**没有保存按钮**。
55
+ - **目录树**:`node_modules` 与点开头条目不列出;大目录有 2000 条上限。
56
+ - **缩进**:每层 14px(`rowIndent`),最深 160px —— 再深也不再加,否则窄列里连行首图标都放不下。层级画在行的**左内边距**上,而行宽始终等于列的宽度(`box-sizing:border-box`),所以缩进只吃名字的宽度,不会把行撑出列外;列表也**不横向滚动**(`overflow-x:clip`)。这两条是同一个缺陷的两半:内边距撑宽了行 → 列表有了横向滚动位置 → 新建/重命名那行自动聚焦时浏览器把它滚进视口,整棵树就按这一行的层级往左滑,行首图标被顶出列外。层级越深、偏得越多,正是这个原因。
57
+
58
+ ## 编辑区:固定的工具栏 + 标签页
59
+
60
+ 文档区被分成两段:**上面一段固定不动,下面一段滚动**。
61
+
62
+ ```
63
+ ┌─ 排版工具栏(黑 宋 霞 阿 | 13 ▾ | 简白 雅致 黑夜 绿荫 | 写作 源码) 💬 ← 永远不动
64
+ ├─ 标签页 [▤ 第一章 ×] [▤ 素材.md ●×] 212 字 未保存 ← 永远不动,横向滚动
65
+ ├──────────────────────────────────────────────────────────────
66
+ │ 正文(渲染页或源码) ← 只有这里滚动
67
+ └──────────────────────────────────────────────────────────────
68
+ ```
69
+
70
+ 最右端那枚对话图标是**整块对话区的开关**(`toggle-chat`)。它原来在目录列标题行上,现在挪到了这条横贯面板的 header 的最右边:它藏的是右侧那一列,不是某个文件,所以不属于目录列。
71
+
72
+ - **为什么固定**:工具栏是「这份文档怎么显示」的开关,滚到 800 行之后再往回找它,就变成了不用。固定的是 `flex:none` 的 `editorHead`,编辑区整列 `overflow:hidden`(列不能滚,否则固定头会被一起卷走),滚动只落在正文自己的容器里(ProseMirror 的滚动宿主或源码 textarea)。
73
+ - **字数与保存状态放在标签行右端,不放在工具栏里**:工具栏那一行是固定 44px 的,窄栏里它不换行(换行会被 44px 裁掉),只让中间的排版控件横向滚动;而一个字数在打字时多一位,仍可能挤动工具栏里的排版控件。标签行不换行,这两项在那里是固定的。
74
+ - **高度稳定**:标签行即使一个文件都没开也保留 36px,所以开第一个文件不会让正文跳动;工具栏固定 44px,窄栏时只有中间的排版控件横向滚动,右端的对话开关始终在位。
75
+ - **多文件**:点目录里的文件就开一个标签页;**每个标签页有自己的缓冲、脏标记和写作/源码模式**,切走再切回来不会重新读盘,未保存的句子还在。同一个文件再点一次只是把它的标签页切到前面,不重读。
76
+ - **标签标题 = 图标 + 文件名**,图标**就是目录树那一枚**(同一个 `TreeIcon` 组件、同一套 Material Icon Theme 关联表,只是按 14px 而非 16px 画),所以 `.md` 章在树上和标签上长得一样。**同名文件会自动带上目录名**(`笔记.md · 第一章`),否则一章一个文件夹的工作区里会出现两个一样的标签。
77
+ - **未保存**:工具栏右端有「未保存」三个字;标签上的小圆点只出现在**不是当前页**的脏标签上——同一行里出现两个「未保存」信号,读起来像两个问题。
78
+ - **关闭**:`×`(悬停或当前页显示)、鼠标中键、或在标签上按 `Delete`/`Backspace`。关掉有改动的那一页会**先写盘再关**;**写盘失败就不关**,那一页留着,字还在(错误显示在上方横幅)。关闭后焦点落到右邻,关最后一个落到左邻,全关掉就是空编辑器(工具栏仍在,好让下一个文件沿用当前的字体/纸色)。
79
+ - **不会互相覆盖**:续读会等同一路径正在进行的写盘落盘;一次读盘**不会覆盖你已经敲过字的缓冲**(读到一半就开始写的那句话不会被旧内容顶掉);自动保存盯着**所有**脏标签,不只是当前页。
80
+ - **键盘**:整个标签条只有一个 Tab 停靠点(当前页),`←`/`→` 切换并带走焦点,`Enter`/`空格` 激活,`Delete` 关闭,`Ctrl/Cmd+S` 保存**所有**脏标签。
81
+ - **无障碍**:`role=tablist` / `role=tab` / `role=tabpanel` 齐备,每个标签 `aria-controls` 指向正文、正文 `aria-labelledby` 指向当前标签,脏标签的可及名字带「未保存」。
82
+ - 树里**已打开但不是当前页**的文件,行名用品牌色、但没有选中条——打开是标签页的事实,不是第二个选中态。
83
+
84
+ ## 目录树右键菜单
85
+
86
+ DSH 本身**支持**右键菜单:`ui-context-menu` 是 web-app bundle 的一行,它注册 `ctx.contextMenus` 服务,并通过 `ctx.slots.provideRoot` 把 `useContextMenu()` 注入每个 Slot 作用域。弹层的位置、键盘移动、焦点归还、关闭、以及「手势发生时的目标快照」都由它负责;插件只声明**目标家族**和动作。
87
+
88
+ 本插件注册了**自己的目标家族** `notebookEntry`,而不是往自带的 `file` / `directory` 家族里加动作——那两个家族是文件侧栏和对话里的文件引用在用的,挂到上面会让"在这里新建文件夹"出现在别处的文件上。
89
+
90
+ **手势用的是 `ctx.contextMenus.open()`,不是 `useContextMenu()`。** 后者是 DSH 文档里的推荐路径(`provideRoot` 注入每个 Slot 作用域),但实测没有传到本面板的组件上——行上仍然是浏览器的原生菜单(返回 / 重新加载 / 另存为)。`open()` 是文档中另一条明确支持的路径("special editors and canvases can call it directly"),所以行自己 `preventDefault()` 后按视口坐标打开;键盘的 `Shift+F10` / ContextMenu 键同样由本插件处理,锚在行的左下角。
91
+
92
+ **服务是「等」来的,不是 `ctx.get` 探来的。** 这里踩过一个只有重启才暴露的坑:插件热安装时 `ctx.get('contextMenus')` 能拿到服务,重启后不行——重启后本 bundle 先激活,`ui-context-menu` 那时还没 `provide`,`get` 返回 `undefined`,菜单就静默退回浏览器原生。现在用 `ctx.inject(['contextMenus'], child => …)`,回调在服务就绪后才跑(DSH 自己的 `ui-file-actions` 就是这种写法)。
93
+
94
+ 与之配套,行的 `onContextMenu` **在事件发生时**才读服务(而不是渲染时决定要不要绑):服务可能晚于首帧渲染到达,按渲染时的结果绑定会让首屏那一次永远绑不上、也不会有第二次渲染。服务尚未就绪时,手势被完全放行——不 `preventDefault`、不 `stopPropagation`,浏览器菜单照常出现,而不是被吞掉后什么也不弹。
95
+
96
+ | 菜单项 | 行为 |
97
+ | --- | --- |
98
+ | 新建文件 / 新建文件夹 | 右键**文件夹**→建在里面;右键**文件**→建在它旁边;右键列标题或目录区空白处→建在工作区根目录 |
99
+ | 重命名 | 该行原地变成输入框,回车确认、Esc 取消、失焦也确认;默认选中主名、保留扩展名 |
100
+ | 删除 | 弹确认框,文件夹会先统计里面有多少文件并写进问题里;确认按钮是唯一的红色按钮 |
101
+ | 刷新 | 重新读一遍工作区 |
102
+ | 在资源管理器中打开 | 文件夹打开它本身,文件打开它所在的目录(Host 侧解析并校验路径,页面从不接触绝对路径) |
103
+
104
+ 几处刻意的取舍:
105
+
106
+ - **整列都能触发**:右键手势绑在目录列本身(目标=工作区根),行各自绑自己的并在事件里 `stopPropagation()`。所以行上出的是该行的菜单,行之间的空白、列表末尾的空白、列标题出的都是根菜单——空工作区里想新建第一个文件,不必去点标题行的图标。没有 `stop` 的话行的事件会冒泡到列,列再开一次同一点的菜单,共享弹层会把它当成"再点一次"而关掉。
107
+ - **根目标不能改名/删除**:列标题与空白区域代表工作区本身,它不在自己的树里,没有可指向的对象。
108
+ - **重命名是一个片段,不是移动**:新名字按"单个路径段"校验,带分隔符直接 400,所以重命名不会把一章的文件夹挪到别处。
109
+ - **改名会带着标签页一起走**:标签的 path 是写盘的键,所以改完名后该文件的标签留在原位、缓冲不丢;整个文件夹改名时,其下所有标签的路径一起重写。
110
+ - **删除会关掉该路径下的所有标签**,当前页落到相邻标签上——指向一个已不存在文件的标签就是往空处写。
111
+ - **只读部署会拒绝**:文件走 `ctx.fs`(自带策略),目录走 `node:fs`(没有策略),所以 API 层对目录类操作单独做了一次只读检查,和写文件给出同一段说明。
112
+ - **没有菜单也能用**:`ui-context-menu` 不在时面板照常工作,行上不吞手势、保留浏览器自己的菜单。服务是可选增强(`ctx.inject`),没有写进 `inject` 数组,所以缺它不会让插件不激活。
113
+
114
+ 删写在 Host 侧对应两个新 op(`rename` / `delete`,另有只读的 `count` 供确认框统计);文件用 `fs.moveFile` / `fs.deleteFile`,目录用 `node:fs` 的 `rename` / `rm`,两者都先经 `resolveInside` 证明在根内。
115
+
116
+ ## 目录树图标
117
+
118
+ 目录树的每个文件/文件夹行都用 **VS Code 插件 [Material Icon Theme](https://github.com/material-extensions/vscode-material-icon-theme)** 的图标,按它自己的关联规则选图:`README.md` 是 README 图标、`package.json` 是 Node 图标、`package-lock.json`/`tsconfig.json` 各有自己的标、`笔记.md` 是 markdown、`数据.yaml` 是 YAML、`src/` 是源码文件夹(展开时换成 `-open` 版)。规则顺序与插件一致,只有第 4 条是本插件的补充:
119
+
120
+ 1. **完整文件名**(不区分大小写)最优先——`package.json`、`README.md`、`LICENSE`、`docker-compose.yml`;
121
+ 2. 否则按**最长后缀**匹配扩展名——`.md` / `.markdown` / `.txt` / `.json` / `.jsonl` / `.yml` / `.yaml` / `.csv`;
122
+ 3. 文件夹按**名字**匹配,展开/收起是两张图;
123
+ 4. **没有扩展名的名字按编辑器的判定当文档**——这是唯一一处不照主题的表来画:编辑器本来就把无后缀名字当 markdown(`isMarkdownPath`,图标直接复用同一个判定,不另写一份),而新建文件的默认名字就是 `第一章` 而不是 `第一章.md`,所以这条规则决定了整本小说的大部分行;
124
+ 5. 其余落到主题自己的通用 `file` / `folder` / `folder-open`——和 VS Code 里一样,不会出现没有图标或裂图的行。
125
+
126
+ ### 为什么只有文本类图标
127
+
128
+ 目录树**只列文本文件**:Host 侧的 `isTextFile` 白名单(`.md .markdown .txt .json .jsonl .yml .yaml .csv` 与无后缀名)决定了哪些文件能进树,不然工作区里的图片、压缩包、系统垃圾会淹掉笔记。所以树里的文件行只可能是这几种类型,`.ts`、`.png`、`.pdf` 之类的行**根本不存在**——它们的图标收进来也永远不会被画出来,只会在每次加载时被下载。
129
+
130
+ 因此收录清单是**推导**出来的,不是手写的:`scripts/vendor-material-icons.mjs` 里的 `HOST_TEXT_EXTENSIONS` 必须与 Host 的 `TEXT_EXTENSIONS` 一致(`check:client` 会读这两处并比对,漂移就报错),然后只保留这些名字/扩展名真正指向的图。想增加一种文件类型,改的是 Host 的白名单,不是这份清单。
131
+
132
+ ### 收录方式
133
+
134
+ 不是运行时去读 VS Code 扩展目录,而是**把美术资源与关联表一起收进仓库**:
135
+
136
+ | 位置 | 内容 |
137
+ | --- | --- |
138
+ | `scripts/vendor-material-icons.mjs` | 从本机已安装的 `pkief.material-icon-theme` 复制选中的 SVG 并生成关联表;`--dry-run` 只校验不写盘;`MATERIAL_ICON_THEME_DIR` 可指定安装位置 |
139
+ | `assets/material-icons/icons/*.svg` | 收进来的 240 张图(约 169 KiB),逐字节原样复制(仅把元素 id 加上图标名前缀,见下) |
140
+ | `src/client/icons/material.generated.ts` | 由脚本生成:每张图的 import + 文件名/扩展名/文件夹/展开的文件夹四张关联表(**不要手改**) |
141
+ | `src/client/icons/material.tsx` | 查找逻辑与 `TreeIcon` 组件;构建把 SVG 以文本内联进 `lib/client.js` |
142
+ | `assets/material-icons/LICENSE.txt`、`NOTICE.md` | 上游 MIT 许可与来源说明,随包发布 |
143
+
144
+ 两处安全/健壮性处理:
145
+
146
+ - **元素 id 加前缀**:这些 SVG 会被内联进同一个文档,主题里有几张图都用 `id="a"` 并用 `url(#a)`/`href="#a"` 引用它;同一个页面出现两份就会互相抢引用。脚本把每个 id 与它的引用一起改成 `<图标名>-a`,所以每张图都是自包含的。
147
+ - **只收静态图**:脚本拒绝 `<script>`、`<foreignObject>`、`on*=` 事件属性和 `javascript:` 目标;查找表用 `Object.hasOwn` 读,所以名为 `constructor` 的文件不会被当成原型链上的函数当成图标 id。
148
+
149
+ 代价:图标美术(169 KiB)+ 关联表(130 KiB)给 `lib/client.js` 增加约 300 KiB 原始体积、约 65 KiB gzip,产物总计约 886 KiB / 231 KiB gzip(剩下的是编辑器与 Prosemirror)。所以只收「树里画得出来」的类型,没有整包搬运 1251 张。升级主题时跑一次 `pnpm run vendor:icons` 再提交结果。
150
+
151
+ > **新建行的图标跟着输入走**:在空名字行里打到 `笔记.md`,行首就从通用文件变成 markdown 图标;名字还空着时画的是通用文件/文件夹。
152
+
153
+ ## 树根与权限
154
+
155
+ **树根 = 调用方 Session 的 `header.cwd`**,也就是操作者打开的工作区。没有第二个根,也没有可配的目录:
156
+
157
+ | 情形 | 结果 |
158
+ | --- | --- |
159
+ | 有 Session(面板的每一次请求都带) | 该 Session 的工作区 |
160
+ | 无 Session(脚本直接调控制面) | 部署写边界,否则 `<DSH_HOME>/notebook` |
161
+
162
+ 每次调用都从调用方 Session 解析,所以写入天然落在该 Session 沙箱已允许的目录里;写盘带 `{ mode, workspaceRoot }` 盖章,`mode` 取该 Session 自己的模式。`op=focus` 把会话工作目录对齐到同一目录,让模型的相对路径与面板一致。
163
+
164
+ ### 为什么没有 `rootDir`
165
+
166
+ 早先的版本有 `rootDir` 这个字段,能 pin 一个工作区之外的库。它被删掉了,因为它从来没有真正生效过,而它许诺的那个形态本来就是错的:
167
+
168
+ - **它不生效。** 面板的请求永远带着活 Session,而根在 `root.ts` 里优先取会话工作区;`rootDir` 只在无 Session 的脚本调用里当回退值。旧版的 `op=state` 却仍把 `rootSource` 报成 `override`——日志和界面都在说一个没发生的事。
169
+ - **它许诺的形态是“半通”的。** 插件给自己盖的边界是那个目录本身,所以面板照常读写;但模型自己的 `write`/`edit` 与 `pwsh` 的边界是本会话的 `header.cwd`,在 pin 出去的目录里会被 `fs-sandbox` 拒绝。同一个面板里出现“人能存、模型写不进”,而从界面上看不出来。
170
+ - **它绕过了操作者的选择。** 沙箱边界表达的是“我把哪个目录交给了这个 agent”。插件自己发明第二个根,等于把这个决定重新解释一遍。
171
+
172
+ **想换目录,就换工作区**:在 Web UI 里把那个目录添加为工作区并打开,新会话的树、模型的相对路径、`pwsh` 的 cwd 就都是它。一个目录,一个决定,由打开它的那个人做。
173
+
174
+ 旧 profile 里若还留着 `rootDir`,激活时会打印 `notebook: rootDir is no longer a configuration field`,其余字段报 `unknown configuration field`。它不会悄悄生效,也不会悄悄失效——改 pin 是删掉那两行,不是重启。
175
+
176
+ ## 配置
177
+
178
+ **没有配置字段。** `cordis.patch.yml` 的 `notebook` 行只有 `id` 和 `name`。
179
+
180
+ ## HTTP 控制面
181
+
182
+ 所有操作走 `/api/notebook?op=<动作>`,继承 Connection 的 Host/Origin 校验与浏览器认证。
183
+
184
+ | `op` | 参数 | 说明 |
185
+ | --- | --- | --- |
186
+ | `state` | — | 根目录(= 调用方工作区)与沙箱报告 |
187
+ | `files` | `project=''` | 树的平铺清单(目录 + 文件) |
188
+ | `file` | `project=''`, `path` | 读一个文本文件 |
189
+ | `save-file` | `project=''`, `path`, `content` | 写一个文本文件 |
190
+ | `create-dir` | `project=''`, `name`, `dir` | 建目录(名字带分隔符 400,重名 409) |
191
+ | `create-file` | `project=''`, `title`, `dir` | 用输入的名字原样建文件;散文名带 `# 标题` |
192
+ | `focus` | `project=''` | 把调用方会话的工作目录切到工作区 |
193
+ | `reveal` | `path?`, `dryRun?` | 用系统文件管理器打开:`path` 为空时开工作区,指向文件夹开它本身,指向文件开它所在目录;Host 解析并校验路径在根内 |
194
+ | `rename` | `project=''`, `path`, `name` | 就地改名(`name` 必须是单个路径段;重名 409,不存在 404) |
195
+ | `delete` | `project=''`, `path` | 删除文件或整个文件夹(递归);返回 `{ path, directory }` |
196
+ | `count` | `project=''`, `path` | 文件夹里有多少个文件,供删除确认框显示 |
197
+ | `ensure-readme` | — | 工作区 `README.md`:不存在则写(201),已存在则 `created:false`(200) |
198
+
199
+ `project` 只接受空串(工作区本身);故事/分镜/设定集相关的操作在这次简化中全部移除。
200
+
201
+ 写操作分两条路:**文件**走 `ctx.fs`(`moveFile` / `deleteFile`,盖同一套沙箱策略),**文件夹**走 `node:fs`(`rename` / `rm`,provider 没有对应方法)。后者不受 `ctx.fs` 的策略约束,所以 API 层对这三个目录/改名操作做了单独的只读检查,与写文件给出同一段说明。
202
+
203
+ ## 插件图标
204
+
205
+ 插件在清单里的那张图只有一个文件:**`icon.png`**(彩色宝石,256×256)。它同时用在两处,所以两处永远一致:
206
+
207
+ - **插件管理里的卡片与详情页**:DSH 读 `package.json` 的 `icon`(这里指向 `./icon` → `icon.png`)。DSH 只接受 SVG / PNG / JPEG / WebP(≤256 KiB),写 `.ico` 会被判为无效图标并退回默认图。
208
+ - **侧边栏「笔记本」那一枚**:`src/client/icons/material.tsx` 隔壁的 `src/client/glyphs.tsx` 直接 `<img>` 画它。客户端读不到包内文件,所以 `tsdown.config.ts` 里一行 `loader: {'.png': 'dataurl'}` 让构建把 `icon.png` 内联进 `lib/client.js`。
209
+
210
+ 换图就是覆盖 `icon.png` 后重新 `pnpm run build`,没有生成步骤、没有中间文件。`pnpm run check:client` 会核对清单指向、尺寸和「侧边栏画的就是这张图」。(目录树那套类型图标是另一件事,见上。)
211
+
212
+ ## 开发
213
+
214
+ ```powershell
215
+ pnpm install
216
+ pnpm run build # host(tsc) + client(tsdown) + 产物契约检查
217
+ pnpm test # 类型检查 + 沙箱 + Host 冒烟
218
+ pnpm run vendor:icons # 升级 Material Icon Theme 后重新收录图标(--dry-run 只校验)
219
+ npm pack --dry-run # 看 tarball 内容
220
+ ```
221
+
222
+ - `scripts/check-client.mjs`:产物是 lazy-CJS(`__ModuleLoader__.load`,只用 `react` 外部);槽位注册、字典、树、布局、字体/纸色、编辑器往返、标签页模型(开关/切换/关闭落点/同名标签/脏标记)、固定头与滚动区、两栏 header 的控件归属(标题行六个图标与顺序、禁用态、`cursor` 跟着改名/删除走;对话开关在工具栏最右端且只有它不随窄栏滚动)、缩进(单一 `rowIndent`、160px 上限、「缩进不撑宽行」与「列表不横向滚动」、上限 ≤ 最窄列留给图标的余量)、目录树类型图标的查找规则、以及「故事机制零残留」。
223
+ - `scripts/smoke-host.mjs`:不用 DSH 进程即可驱动整个控制面(61 项断言):建文件/目录、读写、路径逃逸、README、reveal、focus、写边界盖章、「根跟着调用方 Session 走」、「旧 rootDir 只警告不生效」。
224
+ - `scripts/check-sandbox.mjs`:写边界报告(只读/模式/盖章/引导文案/根解析),35 项;最后的兜底根两条分支都**显式钉住** `DSH_HOME`(设有/未设各一条),不读环境里碰巧是什么。
225
+ - `scripts/vendor-material-icons.mjs`:从本机 VS Code 扩展目录收图标、生成关联表;用 `MATERIAL_ICON_THEME_DIR` 可指定别的安装位置。
226
+
227
+ ## 限制
228
+
229
+ - markdown 是子集:嵌套列表、HTML 块、引用式链接、脚注按普通文字处理;表格与 front matter 作为 raw 块保存,不在文档视图里做表格编辑。
230
+ - 不渲染 mermaid 之类的文本作图。
231
+ - 字体不打包,用本机字体栈;没装会退到同类系统字体。
232
+ - 目录树图标只收文本类(树里只列文本文件)与常见文件夹名,其余显示通用文件/文件夹图标(与 VS Code 的默认表现一致)。
233
+ - 重命名与删除可以右键条目完成、用标题行的两个图标完成,也可以在系统资源管理器(标题行的「打开」)或让模型操作。标题行那两个图标作用于**最后一次手势指向的条目**——没点过任何行时是禁用的,因为树里没有第三种「选中」标记可以读。
234
+ - 标签页**不跨刷新保留**:重开页面是空编辑器。文件在面板外被删除时标签页不会消失(缓冲还在),但**在面板里再敲一个字就会把文件写回来**(Host 的写盘会建出缺失的父目录),这是 Host 侧行为,面板不拦。
235
+
236
+ ## 许可
237
+
238
+ MIT。面板内的工具栏线性图标来自 [Lucide](https://lucide.dev)(ISC);目录树的类型图标来自 [Material Icon Theme](https://github.com/material-extensions/vscode-material-icon-theme)(MIT,Copyright (c) 2025 Material Extensions,全文在 `assets/material-icons/LICENSE.txt`);插件图标 `icon.png` 由本仓库的 `icon.ico` 转出(同一版美术资源)。
@@ -0,0 +1,8 @@
1
+ The MIT License (MIT)
2
+ Copyright (c) 2025 Material Extensions
3
+
4
+ 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:
5
+
6
+ The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
7
+
8
+ 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.
@@ -0,0 +1,13 @@
1
+ # Material Icon Theme artwork
2
+
3
+ The SVGs in `icons/` are the drawings of [Material Icon Theme](https://github.com/material-extensions/vscode-material-icon-theme) 5.39.0
4
+ by Material Extensions, MIT licensed. The full licence text is in `LICENSE.txt`,
5
+ and vendored artwork is covered by the package licence notice.
6
+
7
+ Files are copied from the installed extension by `scripts/vendor-material-icons.mjs`
8
+ with one mechanical edit and no redrawing: each drawing's element ids are prefixed
9
+ with its icon name (the SVG is inlined into one page, where duplicate ids would
10
+ resolve across drawings). Everything else is byte-for-byte the theme's file. Both
11
+ the artwork and `src/client/icons/material.generated.ts` are committed so a build
12
+ needs no VS Code installation. Regenerate with `pnpm run vendor:icons` after
13
+ upgrading the extension, then commit the result.
package/cordis.patch.yml CHANGED
@@ -1,7 +1,9 @@
1
1
  # One row activates both halves: the Host plugin (lib/index.js, via the package
2
2
  # `exports["."]`) and the Client bundle (lib/client.js, via `dsh.client`).
3
+ #
4
+ # No `config`: the panel's tree is the workspace the calling Session opened, so
5
+ # there is no root to configure. A profile that still carries `rootDir` is warned
6
+ # about at activation and otherwise ignored — see README 「树根与权限」.
3
7
  - insert:
4
8
  - id: notebook
5
9
  name: '@zmskco/dsh-notebook'
6
- config:
7
- rootDir: null
package/icon.png ADDED
Binary file