羽毛笔笔记 enchangcui340-cloud/QuillPen

羽毛笔 · 用户版 / QuillPen (User Edition)

把「笔记」面板插件与「羽毛笔」AI 助手模式装进 DSH。这是给最终用户用的版本。

A DSH plugin that adds a Notes panel and a QuillPen AI assistant mode.
This is the end-user edition.

中文在前，English 在后 ｜ Chinese first, English below. English readers: jump to English

这是什么

- 「笔记」面板 —— 笔记、白板（可手绘图形）、待办、标签、回收站、附件、文档读取（含扫描版 PDF）。
- 「羽毛笔」模式 —— 一个 DSH Agent 预设，内置 42 个笔记工具，可以直接让 AI 帮你写笔记、画白板、整理资料。

移植自 Quill（本地优先的笔记 / 待办 / 白板应用），适配 DSH 的插件架构。

本版特点

| 项 | 说明 |
| AI 助手模式 | 羽毛笔（42 个笔记工具） |
| 新建云数据目录 | ❌ 没有（软件里既没有入口，也没有创建所需凭据） |
| 用 key 连接已有云数据目录 | ✅ 保留（由管理员创建并发放 key） |
| 默认笔记库 | 干净新库 ~/Documents/QuillNotes |

云数据目录怎么来：由管理员创建好后把一串 QC1-… 或 QS2-… 的 key 给你，在「笔记本 → 云端库 → 连接云数据目录」里粘贴即可。key 请勿公开分享（里面含该目录的凭据）。

为什么"没有新建能力"反而是好事，见下面 为什么"没有新建云数据目录"也能放心。

安装

1. 要求：DSH 桌面版。目前仅支持 Windows x64（macOS 尚未适配，但代码里已预留平台分支，未写死路径）。
2. 在 DSH 里让 Agent 执行安装：

plugin_manager install_bundle <本目录>/packages/dsh-quill-user

3. 装好后：侧边栏出现「笔记」入口；新建会话时模式下拉里出现「羽毛笔」。
4. 首次打开会自动在 ~/Documents/QuillNotes 建一个空库。
想用别的目录：在插件配置里写 libraryRoot，或设置环境变量 DSH_QUILL_LIBRARY_ROOT。

详细的逐步安装说明（写给另一台电脑上的 AI 看的）：见 《安装说明-给AI.md》。

用 key 连接云数据目录

云数据目录由管理员创建，他给你一串 key 后在「笔记本 → 云端库 → 连接云数据目录」里粘贴。

正常情况下你不需要做任何配置 —— 服务器地址写在插件目录里的 cloud-endpoint.json（打包时一并带上）。

如果提示「连不上云服务器」，说明插件没拿到服务器地址：

1. 地址文件没跟着过来（比如用 git archive 导出，会漏掉它 —— 它在 .gitignore 里）。
解决：在 ~/.dsh/profiles/desktop/cordis.patch.yml 末尾追加下面这段，然后重启 DSH：

- id: quill-notes-user
name: 'dsh-quill-user'
config:
cloudHost: '<管理员告诉你的服务器地址>' cloudPort: 22

2. 管理员还没给你地址 → 找他要。

如果拿到的是 QC1-… 开头的长 key（700 多字符），它自带地址，无需任何配置。

为什么"没有新建云数据目录"也能放心

软件里不存在创建云目录所需的任何东西 —— 这既是产品决定，也是安全设计：

| 层 | 具体做法 |
| 没有凭据 | 包里不含 provision.key（连一个私钥文件都没有） |
| 没有代码 | 创建函数（createCloudDir）与密钥读取（provisionKey）已删除 |
| 没有通道 | cloud:create 通道已删除（即使有会话凭据也调不到） |
| 没有入口 | 对话框只保留「用 key 连接」 |
| 构建期兜底 | node tools/check-user-edition.mjs 扫描：出现任何创建相关符号或私钥 → 失败 |

即使有人（或 AI）拿到完全的文件权限，也无法在这台机器上创建云目录 ——除非他去别处拿到管理员的服务器凭据。这也是本版本发布时该守的边界。

主要功能

笔记

Markdown 编辑（CodeMirror）、实时预览、frontmatter 标题、库内搜索、标签、笔记夹拖拽整理。

白板

- 卡片（文字 / 图片 / 笔记引用 / 外部链接）四边连线
- 手绘图形：矩形、椭圆、三角形、菱形、直线、箭头、曲线、自由绘制
- 曲线是"点两下成线 → 点线段中部插控制点 → 拖动变形 → 点空白锁定"（Adobe 手感）
- 图形与卡片同级：可框选、拖动、复制粘贴、删除
- 连线画下即固定：接在哪条边由创建时决定，之后移动卡片不会自己改（想换就删了重画）

待办

收件箱式快速添加、截止日期、标签、与笔记双向关联。

文档读取

PDF（含扫描件，逐页渲染成图）、Word / Excel / PPT、HTML、CSV、纯文本 —— 都能转成文字喂给 AI。

常见问题

Q：粘贴 key 后提示"key 无效，或这个云目录已经不存在了"？ A：key 没复制全（含空格/换行），或该云目录已被管理员删除。先确认 key 完整，再找管理员确认。

Q：提示"连不上云服务器"？ A：见上文「用 key 连接云数据目录」。多半是地址文件没跟着过来。

Q：我原来的笔记去哪了？ A：用户版是干净新库，不会自动接管旧库。要沿用旧目录：在插件配置里写 libraryRoot，或设环境变量 DSH_QUILL_LIBRARY_ROOT。

Q：画白板时拖拽会选中卡片里的文字？ A：已在 CSS 层处理（世界层 user-select: none，只有双击进入编辑态才允许选字）。若仍能选中，说明装的是旧版本。

开发与验证

安装依赖
pnpm install

构建（css → host → client）
node build.mjs all

用户版专属验收（无创建能力 / 无密钥 / 通道已删 / 干净新库 / 命名）
node tools/check-user-edition.mjs

全量测试（36 套，含真浏览器端到端）
node tools/run-all.mjs

只跑快的（跳过真浏览器与云端套件）
node tools/run-all.mjs --fast

tools/run-all.mjs 会自动发现 tools/ 下所有 check-.mjs / smoke-.mjs 并汇总。
其中几套需要真浏览器（用系统已装的 Edge/Chrome，无需额外配置）。

许可

MIT（见 LICENSE）。本项目移植自 Quill（本地笔记 / 待办 / 白板）。
云数据目录需要自备服务端；源码中不含任何服务器地址或凭据（通过插件配置 / 环境变量提供）。

这是什么

- 笔记面板 —— 笔记、白板（支持手绘图形）、待办、标签、回收站、附件、文档阅读（含扫描版 PDF）。
- QuillPen 模式 —— 一套 DSH 智能体预设，打包了 42 个笔记工具，让 AI 帮你写笔记、画白板、整理素材。

移植自 Quill（本地优先的笔记 / 待办 / 白板应用），跑在 DSH 的插件架构上。

这个版本里有什么

| 项目 | 说明 |
| AI 助手模式 | QuillPen / 羽毛笔（42 个笔记工具） |
| 创建云数据目录 | ❌ 没有 —— 既没有 UI 入口，也没有凭据去做这件事 |
| 用密钥连接已有云目录 | ✅ 保留（管理员创建好，把密钥交给你） |
| 默认库 | 全新的空库，位于 ~/Documents/QuillNotes |

云目录从哪来？ 管理员创建好，再给你一个 QC1-… 或 QS2-… 密钥。
把它粘贴到 Notebook → Cloud library → Connect cloud directory。
请不要公开分享密钥 —— 里面装着那个目录的凭据。

至于为什么没有创建能力反而是件好事，见为什么「创建云目录」缺失是安全的。

安装

1. 需要 DSH 桌面应用。目前只支持 Windows x64（macOS 尚未支持，不过代码里有平台分支，也没有硬编码路径）。
2. 让 DSH 智能体来安装：

plugin_manager install_bundle <this-dir>/packages/dsh-quill-user

3. 装完之后：侧边栏会出现 Notes 入口，新建会话的模式下拉框里会出现 QuillPen。
4. 首次启动会在 ~/Documents/QuillNotes 创建一个空库。
想换别的目录，就在插件配置里设置 libraryRoot，或者设置 DSH_QUILL_LIBRARY_ROOT 环境变量。

一份写给目标机器上的 AI 的分步指南：见 《安装说明-给AI.md》（中文）。

用密钥连接云目录

管理员创建好云目录，把密钥交给你；把它粘贴到 Notebook → Cloud library → Connect cloud directory。

通常你完全不需要配置 —— 服务器地址就在插件文件夹里的 cloud-endpoint.json 中（随包一起发布）。

如果你看到 「无法连接云服务器」，说明插件没拿到地址：
1. 地址文件没有跟着安装包一起走（比如用 git archive 导出时被跳过了——它在 .gitignore 里）。
修复：把下面这段追加到 ~/.dsh/profiles/desktop/cordis.patch.yml，然后重启 DSH：

- id: quill-notes-user
name: 'dsh-quill-user'
config:
cloudHost: '<管理员给你的服务器地址>' cloudPort: 22

2. 管理员还没给你地址 → 直接去问。

如果你拿到的是以 QC1-… 开头的长密钥（700+ 字符），地址就藏在密钥里——不用配置。

为什么缺少「创建云目录」是安全的

要创建云目录，这个软件里什么都不具备。这既是产品决策，也是安全设计：

| 层面 | 做了什么 |
| 没有凭据 | 安装包里没有 provision.key——一个私钥文件都没有 |
| 没有代码 | 创建函数（createCloudDir）和密钥读取器（provisionKey）都删掉了 |
| 没有通道 | cloud:create IPC 通道删掉了（就算有会话凭据也调不到） |
| 没有入口 | 对话框只提供「用密钥连接」 |
| 构建期防护 | node tools/check-user-edition.mjs 一旦发现任何创建符号或私钥就让构建失败 |

就算能完全访问文件系统，人和 AI 都无法在这台机器上创建云目录——他们得去别处搞到管理员的服务器凭据。这个版本要守住的边界就在这里。

功能

笔记

Markdown 编辑（CodeMirror）、实时预览、frontmatter 标题、库内搜索、标签、拖拽整理文件夹。

白板

- 卡片（文本 / 图片 / 笔记引用 / 外部链接），四边都能连边
- 手绘图形：矩形、椭圆、三角形、菱形、直线、箭头、曲线、自由手绘
- 曲线按 Adobe 的方式操作：点两下画一条线 → 点线段中间插入控制点 → 拖动改形状 → 点空白处锁定
- 图形的行为和卡片一样：框选、拖动、复制/粘贴、删除
- 边一旦画好就固定：连在哪一边在创建时就定了；移动卡片不会重新布线（想改就删掉重画）

待办

收件箱式快速添加、截止日期、标签、与笔记双向链接。

文档阅读

PDF（包括扫描件，逐页渲染）、Word / Excel / PowerPoint、HTML、CSV、纯文本——都能转成文本喂给 AI。

常见问题

问：粘贴密钥后提示「密钥无效，或该云目录已不存在」？ 答：要么密钥没复制全（多了空格/换行），要么管理员删掉了那个目录。先核对密钥，再去问管理员。

问：「无法连接云服务器」？ 答：见上文连接到云目录——通常是地址文件没有跟着安装包一起走。

问：我原来的笔记去哪了？ 问：这个版本会接管旧库吗？ 答：不会。这个版本从全新的空库开始，不会接管旧库。想复用旧目录，在插件配置里设置 libraryRoot，或者设置环境变量 DSH_QUILL_LIBRARY_ROOT。

问：在白板上拖拽会选中卡片里的文字？ 答：已在 CSS 层修好（world 层加 user-select: none；只有双击进入编辑模式后文字才可选中）。如果还能复现，说明你跑的是旧构建。

开发与验证

Install dependencies
pnpm install

Build (css → host → client)
node build.mjs all

User-edition acceptance (no creation ability / no keys / channel removed / fresh library / naming)
node tools/check-user-edition.mjs

Full test suite (36 suites, including real-browser end-to-end)
node tools/run-all.mjs

Fast subset (skips real-browser and cloud suites)
node tools/run-all.mjs --fast

tools/run-all.mjs 会自动发现 tools/ 下所有 check-.mjs / smoke-.mjs，并汇总结果。
少数套件会驱动真实浏览器（用系统里已装好的 Edge/Chrome，无需额外配置）。

License

MIT — 见 LICENSE。移植自 Quill（本地优先的笔记 / 待办 / 白板）。
云端目录需要你自己的服务器；源码里不含任何服务器地址或凭据（这些通过插件配置或环境变量传入）。