@kpeace/dsh-prompt-notes 0.0.0-stage → 0.3.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/CHANGELOG.md ADDED
@@ -0,0 +1,23 @@
1
+ # Changelog
2
+
3
+ ## 0.3.0
4
+
5
+ - 技能可设「何时使用」与调用方(两者 / 仅模型 / 仅用户)。
6
+ - 助手工具 `note_list` / `note_create` / `note_update` / `note_delete`;助手建的 MCP 便签一律未钉住。
7
+ - 导入 / 导出(先预览再确认,冲突可重命名 / 跳过 / 覆盖);导入的 MCP 一律未钉住。
8
+ - 软删除:8 秒撤销,文件保留最近 50 条 / 30 天(数据文件升到 v3,v1 / v2 自动升级)。
9
+ - MCP 只在存在适用的活动会话时启动;不适用的会话看不到它的工具。
10
+ - 外观更简约:去掉噪点纹理、胶带、回形针,标签与图章压平,倾斜减半;文案精简。
11
+ - 键盘与无障碍:页签方向键、弹层焦点陷阱、纸条不再嵌套按钮、尊重「减少动效」。
12
+ - 修复:路由前缀 404;会话级技能挂不上;工作区作用域因取 cwd 失败被吞而悄悄失效;`note_delete` 的工具描述误称「永久」。
13
+ - 新增隔离的真实 DSH 测试实例(`scripts/e2e.sh`)与 4 组 e2e。
14
+
15
+ ## 0.2.0
16
+
17
+ - 三种便签(提示词 / 技能 / MCP)× 三种作用域(全局 / 工作区 / 会话)。
18
+ - 「系统」页:只读展示 DSH 已有的注入内容。
19
+ - 横向拟物界面;v1 便签自动升级。
20
+
21
+ ## 0.1.0
22
+
23
+ - 右侧栏便签:提示词、总开关、字数预算。
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 aaron1.zhang
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.
package/README.md CHANGED
@@ -1,3 +1,83 @@
1
- # Temporary Holding Version
1
+ # @kpeace/dsh-prompt-notes
2
2
 
3
- 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.
3
+ A **Notes** tab in the DSH right sidebar: a landscape pad of paper notes for standing **prompts, skills and MCP servers**. A push pin turns each one on; each has a **scope**: every session, one workspace, or a single session.
4
+
5
+ ![Notes pad](docs/preview.svg)
6
+
7
+ | Paper | Kind | Goes to |
8
+ |---|---|---|
9
+ | Yellow | Prompt | a section of the system prompt |
10
+ | Blue | Skill | the skill catalog, loaded on demand by its description |
11
+ | Green | MCP | `mcpManager`; tools appear as `mcp__<name>__*` |
12
+ | Tracing paper | System | read-only: what DSH already injects (prompt sections, context, skills, MCP); copy any into your own note |
13
+
14
+ With no notes, all three channels are empty — installing it changes no request.
15
+
16
+ ## Install
17
+
18
+ Needs [dsh-better-sidebar](https://www.npmjs.com/package/dsh-better-sidebar).
19
+
20
+ ```sh
21
+ dsh plugin --profile <profile> add <absolute path of this directory>
22
+ ```
23
+
24
+ On desktop use Plugins → Add plugin. **Restart DSH after updating** (the host half loads at start); client-only changes need a page refresh.
25
+
26
+ ## Config (all optional)
27
+
28
+ ```yaml
29
+ - id: prompt-notes
30
+ name: @kpeace/dsh-prompt-notes
31
+ config:
32
+ maxChars: 8000 # per-session character budget for prompt notes; 0 = unlimited
33
+ order: 100 # system prompt section position (0 = persona, 500 = plan policy)
34
+ file: ~ # data file, default $DSH_HOME/prompt-notes/notes.json
35
+ mcp: true # false = never register MCP notes (they start local processes)
36
+ pollMs: 2000 # how often to check the data file for outside edits (ms)
37
+ enabled: true # false = the whole plugin sleeps
38
+ ```
39
+
40
+ ## Scopes
41
+
42
+ "Applies" is always relative to an observer (session id + working directory). Workspace = the session's cwd is inside that directory.
43
+
44
+ | Channel | How it filters |
45
+ |---|---|
46
+ | Prompt | Computed at every system-prompt assembly; takes effect next turn |
47
+ | Skill | Global + workspace via a global provider; session notes via a provider on that session, gone with it |
48
+ | MCP | The process starts only while an applicable live session exists; other sessions do not see its tools (`tools.restrict`), with `tools.guard` as a call-time backstop |
49
+
50
+ ## Assistant tools
51
+
52
+ `note_list` · `note_create` · `note_update` · `note_delete`, using the same validation as the panel. Assistant-created MCP notes are always unpinned; a pinned MCP note can only have cosmetic fields edited; deletion goes to the trash and the assistant cannot restore it.
53
+
54
+ ## Sharing
55
+
56
+ "Import / export" in the panel: export one, several or all; import previews first, then confirms; name clashes can be renamed (default), skipped or overwritten. **Imported MCP notes are always unpinned**, and the preview lists the command pinning would run; files not made by this plugin are rejected.
57
+
58
+ ## Behavior
59
+
60
+ - Prompts are injected in **creation order**, so editing one does not reshuffle the cache prefix of the rest; the budget counts prompts only, and a note that does not fit is skipped whole, never truncated.
61
+ - The section uses `interpolate: false`: `{{` in a note can never fail the model call or be substituted.
62
+ - Data is one JSON file (v3), hand-editable; writes are atomic and re-read first. A corrupt file is backed up as `.corrupt-<time>`, a single hand-broken note as `.invalid-<time>`; v1 / v2 upgrade automatically.
63
+ - Deletion is soft: 8 seconds of Undo in the panel; the file keeps the last 50 / 30 days.
64
+ - Write routes need a custom header and refuse cross-site origins; new MCP notes are unpinned; `mcp: false` disables the feature.
65
+ - Skills can set "when to use" and who may invoke them (both / model only / user only).
66
+
67
+ ## Limits
68
+
69
+ - Hiding tools lags by up to 2 seconds: right after an MCP connects or a session changes directory, an inapplicable session may briefly see its tools.
70
+ - The deny path of `tools.guard` was not verified with a real model tool call, only by unit test.
71
+ - Assistant-created **prompt** notes are pinned by default (they enter the next session).
72
+ - The look was checked by DOM measurements (contrast, overflow), not by human eyes.
73
+
74
+ ## Dev
75
+
76
+ ```sh
77
+ npm test && npm run check # unit tests + syntax
78
+ scripts/e2e.sh setup && scripts/e2e.sh start # isolated real DSH instance (/tmp, port 48990, never your profile)
79
+ npm run e2e && npm run e2e:scope && npm run e2e:share && npm run e2e:robust
80
+ npm run demo # rebuild demo/demo.html (single file, mocked backend)
81
+ ```
82
+
83
+ Development history and trade-offs: `dev/DEVLOG.md`.
package/README.zh.md ADDED
@@ -0,0 +1,83 @@
1
+ # @kpeace/dsh-prompt-notes
2
+
3
+ DSH 右侧栏的「便签」:一本横向便签簿,管理常驻**提示词、技能、MCP**。图钉决定是否生效,每张可按**作用域**生效:所有会话 / 某个工作区 / 单个会话。
4
+
5
+ ![便签簿](docs/preview.svg)
6
+
7
+ | 纸色 | 类型 | 去向 |
8
+ |---|---|---|
9
+ | 黄 | 提示词 | system prompt 的一个段 |
10
+ | 蓝 | 技能 | 技能目录,模型按描述按需加载 |
11
+ | 绿 | MCP | `mcpManager`,工具以 `mcp__<名>__*` 出现 |
12
+ | 描图纸 | 系统 | 只读:DSH 已有的提示段、上下文、技能、MCP;可复制成自己的便签 |
13
+
14
+ 没有便签时三条通道都是空的,装上不改变任何请求。
15
+
16
+ ## 安装
17
+
18
+ 依赖 [dsh-better-sidebar](https://www.npmjs.com/package/dsh-better-sidebar)。
19
+
20
+ ```sh
21
+ dsh plugin --profile <profile> add <本目录绝对路径>
22
+ ```
23
+
24
+ 桌面版用 Plugins → Add plugin。**更新后需重启 DSH**(Host 半体在启动时载入);只改前端刷新页面即可。
25
+
26
+ ## 配置(均可省略)
27
+
28
+ ```yaml
29
+ - id: prompt-notes
30
+ name: @kpeace/dsh-prompt-notes
31
+ config:
32
+ maxChars: 8000 # 每个会话里提示词便签的字数预算;0 = 不限
33
+ order: 100 # system prompt 段位置(0 = persona,500 = plan policy)
34
+ file: ~ # 数据文件,默认 $DSH_HOME/prompt-notes/notes.json
35
+ mcp: true # false = 不登记任何 MCP 便签(MCP 会启动本地进程)
36
+ pollMs: 2000 # 探测数据文件被外部改动的间隔(毫秒)
37
+ enabled: true # false = 整个插件休眠
38
+ ```
39
+
40
+ ## 作用域
41
+
42
+ 「适用」永远相对一个观察者(会话 id + 工作目录)。工作区 = 会话 cwd 在该目录之内。
43
+
44
+ | 通道 | 过滤方式 |
45
+ |---|---|
46
+ | 提示词 | 每次组装 system prompt 时现算,下一轮生效 |
47
+ | 技能 | 全局 + 工作区走全局提供方;会话级走挂在该会话上的提供方,随会话消亡 |
48
+ | MCP | 只在存在适用的活动会话时才启动进程;不适用的会话看不到它的工具(`tools.restrict`),调用时再由 `tools.guard` 兜底 |
49
+
50
+ ## 助手工具
51
+
52
+ `note_list` · `note_create` · `note_update` · `note_delete`,与面板走同一套校验。助手创建的 MCP 便签一律未钉住;已钉住的 MCP 便签只能改装饰字段;删除进回收站,助手不能恢复。
53
+
54
+ ## 分享
55
+
56
+ 面板里「导入 / 导出」:导出一张、一组或全部;导入先预览再确认,同名冲突可选重命名(默认)/ 跳过 / 覆盖。**导入的 MCP 一律未钉住**,预览会列出钉上后将执行的命令;非本插件的文件会被拒绝。
57
+
58
+ ## 行为
59
+
60
+ - 提示词按**创建先后**注入,编辑某条不会打乱其余内容的缓存前缀;预算只算提示词,放不下的整条放弃、不截断。
61
+ - 注入段 `interpolate: false`:便签里写 `{{` 不会让模型调用失败,也不会被替换。
62
+ - 数据是单个 JSON(v3),可手改;写入原子、先重读再写。坏文件备份为 `.corrupt-<时间>`,手改写坏的单条备份为 `.invalid-<时间>`;v1 / v2 自动升级。
63
+ - 删除是软删除:面板给 8 秒「撤销」,文件里保留最近 50 条 / 30 天。
64
+ - 写接口需自定义请求头并拒绝跨站来源;新建的 MCP 便签默认未钉住;`mcp: false` 可整体禁用。
65
+ - 技能可设「何时使用」与调用方(两者 / 仅模型 / 仅用户)。
66
+
67
+ ## 局限
68
+
69
+ - 隐藏工具有最多 2 秒的延迟:MCP 刚连上、或会话刚切换目录的瞬间,不适用的会话仍可能短暂看到工具。
70
+ - `tools.guard` 的拒绝分支没有用真实的模型工具调用验证过,只有单测覆盖。
71
+ - 助手创建的**提示词**便签默认钉住(会注入下一次会话)。
72
+ - 外观经 DOM 度量检查(对比度、溢出),没有经人眼确认。
73
+
74
+ ## 开发
75
+
76
+ ```sh
77
+ npm test && npm run check # 单测 + 语法
78
+ scripts/e2e.sh setup && scripts/e2e.sh start # 隔离的真实 DSH 实例(/tmp,端口 48990,不碰你的 profile)
79
+ npm run e2e && npm run e2e:scope && npm run e2e:share && npm run e2e:robust
80
+ npm run demo # 重建 demo/demo.html(单文件,模拟后端)
81
+ ```
82
+
83
+ 开发过程与取舍见 `dev/DEVLOG.md`。