@westwall/dsh-friendly-expression 0.0.0-stage → 0.1.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.
@@ -0,0 +1,6 @@
1
+ # dsh-friendly-expression bundle patch:把本插件行插入 profile 阵容。
2
+ # 作为 bundle 层(package.json#dsh.bundle.patch)叠加到 dsh-base 之上:
3
+ # dsh plugin --profile web add link:$(pwd)/packages/friendly-expression
4
+ - insert:
5
+ - id: friendly-expression
6
+ name: '@westwall/dsh-friendly-expression'
package/docs/DESIGN.md ADDED
@@ -0,0 +1,257 @@
1
+ # 友好表达 · 设计
2
+
3
+ > 状态:v0.1 MVP 已实现(功能以 `designs/friendly-expression/` 的三张设计稿为准)。
4
+ > 设计稿与本文冲突时,功能以设计稿为准;实现方式以 DSH 当前插件最佳实践为准。
5
+
6
+ ## 1. 定位
7
+
8
+ 本插件不负责「命令的渲染」,也不负责工具卡片的渲染;它负责 **Agent 的友好表达**。
9
+
10
+ 友好表达分成两层,后续所有能力都归到其中一层:
11
+
12
+ | 层 | 解决什么 | 由谁定义 | 当前载体 |
13
+ |---|---|---|---|
14
+ | 表达方式 | 说什么、按什么结构说、信息密度、语气、称呼、语言约束 | 用户可编辑的提示词 | system prompt section |
15
+ | 表达形态 | 用什么承载:图、表、列表 | 渲染层,自动内置 | Mermaid;后续由 skill 提供更丰富的形态 |
16
+
17
+ Mermaid 和后续 skill 只属于形态层。方式层不依赖具体形态:用户可以把提示词改成「不要用英文」「每段先称呼我」,渲染层不变;反过来,以后加 SVG 或别的形态,也不要求用户改提示词。
18
+
19
+ 这条边界是插件的核心:**方式可配置、形态可扩展,两者不互相绑架。**
20
+
21
+ ## 2. 产品原则
22
+
23
+ 1. **默认可用,允许修改,随时恢复。** 默认提示词是一份可直接使用的推荐文案,不是空模板。
24
+ 2. **只承诺渲染层支持的形态。** 默认提示词里不写 SVG、PlantUML 或未安装的 skill,否则模型会输出渲染层接不住的东西。
25
+ 3. **图形服务解释,不服务装饰。** 简单内容(例如三步以内的线性过程)用有序列表说清;不要为了「看起来专业」而画图。
26
+ 4. **成本封顶。** 提示词上限 800 字符(默认 164 字),每轮都会随 system prompt 发送;这是用户可感知的硬上限,不做隐式扩写。正文之外还有一行固定的英文引导语,见 3.2。
27
+ 5. **作用域跟随 profile。** 配置是 profile 级的;不同 profile 可以有不同的表达风格。
28
+ 6. **新会话生效,会话内冻结。** 提示词注入 system prompt;为了不破坏模型的前缀缓存,每个会话在创建时固化一份提示词快照,之后修改设置不影响已存在会话,重启/恢复后也从快照恢复。
29
+ 7. **不注入子代理。** 友好表达面向用户和 Agent 的对话;子代理的输出是给父代理看的结构化文本,不需要表达风格和图形。
30
+ 8. **形态自动内置。** 不提供「表达形态」开关;插件启用后自动接管 mermaid 围栏。用户改不了渲染器,也不需要改。
31
+ 9. **失败可自救。** Mermaid 渲染失败时给出错误摘要和「复制给 Agent」按钮,让用户能直接把问题交回给模型重生成,而不是只看到一坨源码。
32
+
33
+ ## 3. 表达方式:可编辑提示词
34
+
35
+ ### 3.1 设置页
36
+
37
+ - **入口**:设置面板左侧一级导航「友好表达」,对应宿主 `settings.section`,**不是**插件详情页的 bundle/row 配置。
38
+ - **页面结构**(设计稿定版):标题「友好表达」与副标题「让 Agent 说得清楚,也画得明白。」;一张「表达方式」卡片;卡片内是 textarea、`164 / 800` 计数、`恢复默认` 与 `保存`;底部提示「恢复默认会回到系统推荐文案;已有会话保持原提示词。」
39
+ - **没有「表达形态」卡片**:Mermaid 渲染是内置行为,不需要配置。
40
+ - **控件自绘**:使用宿主主题 token 和自绘 textarea/按钮,不引入 `@deepseek-ai/dsh-client-ui-primitives`;宿主不保证这些客户端 primitives 的跨版本兼容。
41
+ - **保存语义**:保存后只对新会话生效;已经打开/已存在的会话保持其快照,不因这次保存改变 system prompt。
42
+ - **恢复默认语义**:移除用户覆盖、回落到 schema 默认值;已存在会话的快照不变。
43
+
44
+ ### 3.2 配置
45
+
46
+ Host 半体声明 `Config`:
47
+
48
+ | 字段 | 类型 | 默认 | 说明 |
49
+ |---|---|---|---|
50
+ | `stylePrompt` | string | 推荐文案(164 字) | 最长 800 字符;`.volatile()`,保存后不重启插件即可被 Host 读取 |
51
+
52
+ `stylePrompt` 使用 `.volatile()` 的原因:DSH 的设置服务只投影 volatile 字段,普通字段只能改 YAML;volatile 还能让配置在运行中更新。插件在会话创建时读取它并固化快照,因此新会话用新值,已有会话保持不变。
53
+
54
+ 字符上限按 UTF-16 长度(`string.length`)计算,与 Host schema 的 `max(800)` 保持一致;设置页的计数器使用同一口径。
55
+
56
+ 注册时宿主在正文前拼一行固定的英文引导语:
57
+
58
+ ````text
59
+ When talking with the user, follow these principles:
60
+ <正文>
61
+ ````
62
+
63
+ - 引导语不进入 `stylePrompt`:textarea、`164 / 800` 计数和 `恢复默认` 都只处理正文,Host schema 的 `max(800)` 也只约束正文。
64
+ - 正文为空时不拼引导语,也不注册 section。
65
+ - 捕获快照时冻结的是「引导语 + 换行 + 正文」整段文本,之后改引导语常量不会改动已有会话。
66
+ - 快照里只有正文的旧会话按原样注册,不加引导语、不做迁移,system prompt 逐字节不变。
67
+ - 存储 schema 的上限按「引导语 + 换行 + 800 字正文」设,覆盖最长正文;旧快照的纯正文同样在范围内。
68
+
69
+ ### 3.3 注入机制与会话快照
70
+
71
+ 在 Host 半体里注册 system prompt section:
72
+
73
+ ```ts
74
+ ctx.agents // 逐 Agent 注册
75
+ agent.ctx.systemPrompt.section({
76
+ name: 'westwall:friendly-expression',
77
+ order: 9500,
78
+ text: snapshot, // static string, captured once per session
79
+ })
80
+ ```
81
+
82
+ - **按 Agent 注册 scoped section**,不注册全局 section。这样每个会话可以有不同的快照,并且能自然排除子代理。
83
+ - **只对 Web/桌面注入**:装配时检查 `ctx.get('webApp')`(必要时兼容 `webServer`);CLI/headless 没有客户端渲染面,不注入,避免终端里出现 Mermaid 源码块。
84
+ - **子代理不注入**:`agent.session.header.origin === 'subagent'` 的 Agent 不注册 section。
85
+ - **每个会话一份持久化快照**:使用 `ctx.storageDomain` 打开域 `friendly_expression`,表 `sessions` 以 `SessionId` 为 key,值为 `{ prompt, capturedAt }`。新会话在 `agent/created` 时捕获当前 `stylePrompt`;判定依据是「`source === 'startup'`、没有快照、没有既有消息、非 seeded、非 subagent」。已有会话没有快照就不注册 section,避免在会话中途改变 system prompt。
86
+ - **恢复会话**:只读快照;有快照就注册同样的文本,没有就视为「该会话不启用友好表达」。重启/恢复不会改用最新设置。
87
+ - **前缀缓存**:同一会话内每次请求的 system prompt 文本保持逐字节一致,模型的前缀缓存不会因为设置变更而失效;新会话才换新文案。
88
+ - **存储依赖与降级**:`storageDomain` 是声明依赖,插件在它可用后才激活;打开失败或写入失败时退回进程内 `Map<SessionId, string>`,当前运行内行为不变,重启/恢复后失去快照。不阻塞会话创建。
89
+ - **数据保留**:快照是插件卸载也不会自动清理的持久数据(会话级 <1 KB)。README 需要说明这一点,并提供清理位置;不在会话删除时做不可靠的自动清理。
90
+
91
+ 选择 scoped section 而不是下面两种方案:
92
+
93
+ - **不用 `agent-instructions`。** 它是文件驱动的上下文插件:读取用户全局或项目里的 `AGENTS.md`,注入 durable 的 user 消息。那是用户自己的文件,插件不应该去写,也没有「设置项」概念。
94
+ - **不用 `systemPrompt.context`。** 那是 user-role 的「当前运行上下文」快照,可被 `includeRuntimeContext: false` 抑制,语义上不是行为规则。
95
+
96
+ ### 3.4 默认提示词
97
+
98
+ 默认正文是 164 字(设计稿定版)。设置页、计数器和 `恢复默认` 都只处理这段正文:
99
+
100
+ ````text
101
+ 紧扣问题,先给结论,再给必要依据。不确定的地方明确标注,不编造。只讲相关信息,不复述已知内容。长内容分点,按重要性排序;语气自然直接,不堆客套。禁止使用 ASCII 方框和箭头画图;默认用 Mermaid 11.x表达,简单内容不强行画图。对比用表格,线性步骤用有序列表,文件树保留缩进。用户明确要求其他形式时,以用户要求为准。
102
+ ````
103
+
104
+ 这段默认正文就是插件里的「受控表达」:一段可编辑的约束文本,不是 ASD-STE100 之类的标准或认证;用户可以把正文换成自己的约束。
105
+
106
+ 设计取舍:
107
+
108
+ - **把格赖斯四原则写成动作,不抄原文。** 「信息充分、真实、相关、清晰」对模型的行为改变很弱,还容易和基础提示词里的简洁要求打架;写成「先结论后依据、只讲相关信息、不编造、分点排序」更可执行。
109
+ - **明确「简单内容不强行画图」。** 否则只是把 ASCII 泛滥换成 Mermaid 泛滥。
110
+ - **不列图类型白名单。** 渲染层支持 Mermaid 11.15.0 内置的全部图表类型;ZenUML 等外部插件不在包内。正文只说默认用 Mermaid 表达。列出少数类型会把模型限制在名单里,名单外本来能渲染的图就不会被用到。
111
+ - **保留例外条款。** 用户明确要求 ASCII 草图或其他形式时听用户的,避免规则和直接指令冲突。
112
+ - **默认不用满 800 字。** 上限是给用户改的,不是默认目标。
113
+ - **允许保存空字符串。** 空字符串表示新会话不注入任何表达提示词,也不加引导语;设置页不额外做开关。
114
+
115
+ ## 4. 表达形态:Mermaid
116
+
117
+ ### 4.1 渲染接入
118
+
119
+ - 客户端半体声明 `dsh.client`(`platform: 'web'`),在 `apply` 里注册围栏层:
120
+
121
+ ```ts
122
+ ctx.slots.inject('conversation.chat.markdown.fence', () => ctx.slots.register({
123
+ name: 'conversation.chat.markdown.fence',
124
+ id: '@westwall/dsh-friendly-expression/fence/mermaid',
125
+ key: 'mermaid',
126
+ }, MermaidFenceLayer))
127
+ ```
128
+
129
+ - 槽位按小写围栏语言分发,`key: 'mermaid'` 即接管 mermaid 语言的代码块。
130
+ - 流式阶段渲染 `children`(普通代码块),落定后再解析渲染;避免半截语法报错。
131
+ - 层内部捕获 mermaid 的解析/渲染异常,回退到源码块并附错误提示;框架本身也会在层崩溃时回退到 `children`。
132
+ - 按可视区懒渲染:`IntersectionObserver` + 单并发渲染队列,避免一屏外几十张图同时解析;缓存键包含 `code + theme`。
133
+
134
+ ### 4.2 内联卡片
135
+
136
+ 按设计稿:
137
+
138
+ - 卡片头部:Mermaid 图标 + `MERMAID` 标识;右侧 `源码` 切换、复制源码、放大查看。
139
+ - 图区域:按容器宽度自适应,限制最大高度;右下角保留「点击放大」提示。
140
+ - 点击图(或放大按钮)打开浮窗;工具栏按钮不触发打开。
141
+ - 流式阶段显示源码;落定后显示图;用户切到「源码」时也显示源码。
142
+ - 解析失败时显示错误块,而不是空白或半截图;源码仍然可见。
143
+
144
+ ### 4.3 浮窗
145
+
146
+ - 注册在根 `shell.overlay` 槽位,覆盖整个窗口;组件用 `position: fixed` 自己撑满视口,带 `role="dialog"`、`aria-modal`、焦点陷阱、Esc 关闭、点遮罩关闭,关闭后焦点回到触发卡片。
147
+ - 面板尺寸跟窗口走:宽 72vw、高 78vh,最小保持旧的 940×656(小窗口不缩),最大 1600×1000,并且永远不超出遮罩内容盒。大屏上同一张图因此能按更大的倍率显示。
148
+ - 标题:围栏本身没有标题。优先取 Mermaid frontmatter 的 `title:` 或围栏 `meta`(如 ` ```mermaid 加载流程 `);都没有时,用 `mermaid.detectType(code)` 识别图类型并显示本地化名称(流程图、时序图、状态图、ER 图等),失败则显示「Mermaid 图表」。**不**从节点标签猜测标题。
149
+ - 头部操作:复制源码、下载 SVG、关闭。
150
+ - 底部缩放条:`−`、当前百分比、`+`、`适合窗口`、`1:1`;滚轮缩放以指针为中心,拖拽平移,缩放范围约 20%–800%;打开时默认「适合窗口」。
151
+ - 主题跟随宿主:用 `base` 主题 + 从宿主 token 映射的变量,监听 `theme/change` 重绘;缓存键包含主题标识。
152
+ - 内联卡片和浮窗都用 Blob `<img>` 显示 SVG,避免同一份 inline SVG 在页面里出现两次导致 id 冲突;下载也直接用这份 SVG 字符串。
153
+ - 设计稿已去掉的操作说明文字(「滚轮缩放 · 拖拽平移 · Esc 关闭」「Mermaid · 4 个节点」)不再添加。
154
+
155
+ ### 4.4 错误与自救
156
+
157
+ - 解析失败、渲染超时、空内容一律回退为错误块,并显示一行错误摘要;源码通过「查看源码」切换,不再在错误块下重复渲染;不阻塞消息其余部分。
158
+ - 错误块提供:
159
+ - `复制错误给 Agent`:复制以下文本,用户粘贴回会话即可让模型重生成:
160
+ ```text
161
+ Mermaid 渲染失败,请重新生成。错误信息:
162
+ <完整错误信息>
163
+ ```
164
+ - `查看源码`:切换到源码块,方便用户手动检查或修改。
165
+ - 复制成功后给轻量反馈(「已复制,粘贴发送给 Agent」);不自动发送。
166
+ - 错误块只显示截断后的短摘要,避免把整段 parser 输出塞进 UI;「复制错误给 Agent」使用未截断的原始错误,保留换行、完整 token 列表和 `^` 指针;控制台仍记录原始错误。
167
+
168
+ ### 4.5 会话徽章
169
+
170
+ - 位置:`conversation.session.header.utilities`,会话头部右上角的小图标/徽章,悬停或键盘聚焦时显示提示「友好表达已开启」。
171
+ - 显示条件:插件启用且当前 `stylePrompt` 非空。提示词为空时隐藏;CLI/headless 没有客户端,不显示。
172
+ - 徽章是**插件级**状态,不逐会话判断是否已经捕获快照;如果后续需要严格的「当前会话已开启」精度,再增加 Host 侧的会话状态查询或会话投影。
173
+ - 仅作为轻量标记,不改变布局、不占工具栏宽度;配色使用主题 token,暗色/亮色都可读。
174
+
175
+ ### 4.6 安全、体积与版本
176
+
177
+ - `securityLevel: 'strict'`;设置 `maxTextSize: 20000`、`maxEdges: 500` 上限,防止超图拖垮页面;`suppressErrorRendering: true`,异常时清理临时节点。
178
+ - 只处理 assistant 消息里的围栏;工具卡片、详情页、用户消息不在 MVP 范围。
179
+ - 体积(实测 `dist/mermaid.min.js`,raw / gzip):
180
+ - mermaid 11.15.0:约 3.31 MB / 0.91 MB
181
+ - mermaid 12.3.0:约 5.54 MB / 1.59 MB
182
+ - 版本选择:12.3.0 很新(12.0.0 于 2026-09 发布),主要变化是 ELK 成为默认布局、`neo` 成为默认外观、解析器升级;渲染层不做类型白名单;Mermaid 11.15.0 内置图表类型的基础语法没有变。模型对 11.x 的先验更强,因此 **MVP 默认锁 11.15.0**;发布前用一组真实模型输出的固定语料做 11.15.0 vs 12.3.0 的 A/B,若 12.3.0 的解析成功率不劣于 11.15.0,则升级到 12.3.0(安全修复与后续维护更好)。如果用 12.3.0,显式设置 `layout: 'dagre'`、`look: 'classic'`、`theme: 'base'`,抵消默认布局/外观变化。
183
+ - 当前锁文件已解析到 DOMPurify 3.4.17;升级 Mermaid 时保持该下限,并在发布前做一次依赖审计。
184
+ - mermaid 采用 MIT 许可,`client.js` 内联其版权声明;构建产物加体积护栏,记录实际大小。
185
+
186
+ ## 5. 设置页读写
187
+
188
+ - 注册 `settings.section`(`id: 'friendly-expression'`,`order` 约 15.5,位于「内置插件」和「OpenCode 调色板」之间),并用 `settings.section.icon` 注册同 id 的导航图标。
189
+ - 数据读写走客户端 `ctx.configForms`:
190
+ - `ctx.inject(['slots', 'configForms'], ...)`,避免把 Mermaid 渲染能力绑在设置服务上。
191
+ - `ctx.configForms.whileServed(['friendly-expression'], register)`:只有当 Host 正在服务该配置命名空间时才显示页面;`whileServed` 不存在时(更旧版本)退化为直接注册。
192
+ - `ctx.configForms.get('friendly-expression')` 返回 `getSnapshot / subscribe / set / unset / mutate`;保存用 `set('stylePrompt', text)`,恢复默认用 `unset('stylePrompt')`,revision 冲突由 `configForms` 处理。
193
+ - `snapshot.writable === false` 时只读;`snapshot.status === 'unavailable'` 时显示不可用提示。
194
+ - **不使用自定义 Host Remote**:设置页只需要读写本插件 Config,`configForms` 已经覆盖传输、schema 校验和 revision 冲突。
195
+ - `namespace` 是 Loader 行 id `friendly-expression`,不是包名;这个 id 一旦安装过就不要改。
196
+
197
+ ## 6. MVP 范围
198
+
199
+ | 做 | 不做 |
200
+ |---|---|
201
+ | Config(800 字提示词,volatile) | SVG / 图表 / 其他围栏语言 |
202
+ | 设置面板一级页(textarea + 计数 + 保存 + 恢复默认) | 按 schema 自动生成表单、`ConfigField` 依赖 |
203
+ | Host 端按 Agent 注册 system prompt section,仅 Web/桌面注入 | CLI/headless 注入 |
204
+ | 每个会话持久化提示词快照,新会话生效、会话内冻结 | 已存在会话的追溯注入 |
205
+ | 子代理排除 | 按 agent 类型/来源做更细的排除策略 |
206
+ | Mermaid 围栏渲染、流式回退、错误降级 | 工具卡片、详情页、用户消息的 Mermaid |
207
+ | 内联卡片(源码/复制/放大)与浮窗(缩放/平移/适合窗口/1:1) | 多套风格预设、按会话切换风格 |
208
+ | 错误块「复制错误给 Agent」 | 自动重试、自动改写 prompt |
209
+ | 会话头部「友好表达已开启」小徽章 | 严格的逐会话徽章状态(后续再加) |
210
+ | 复制源码、下载 SVG、主题跟随、缓存、懒渲染 | 图片生成、A2UI/Generative UI |
211
+
212
+ ## 7. 验收标准
213
+
214
+ Host:
215
+
216
+ - 新会话在创建时捕获当前提示词;之后修改设置,已有会话的 system prompt 文本不变。
217
+ - 重启/恢复会话后,持有快照的会话继续使用快照;没有快照的旧会话不注入。
218
+ - 子代理不注册 section,输出中不出现友好表达提示词。
219
+ - CLI/headless profile 不注入。
220
+ - 恢复默认后,新会话回落到 schema 默认值;旧会话保持快照。
221
+ - 存储不可用时降级为进程内快照,当前运行行为不变。
222
+
223
+ 客户端:
224
+
225
+ - 流式阶段显示代码块,落定后显示图;图不溢出消息容器。
226
+ - 点击可弹窗缩放、平移、滚动;主题切换后重绘。
227
+ - 非法 Mermaid 回退为源码块和错误块;「复制错误给 Agent」写入正确的文案。
228
+ - 同一 `code + theme` 只渲染一次;长会话滚动不卡顿。
229
+ - 设置页保存、恢复默认、800 字校验、只读状态和冲突提示都可用。
230
+ - 提示词非空时,会话头部出现徽章;提示词清空后消失。
231
+
232
+ 端到端:
233
+
234
+ - 在 Web 会话中要求解释一段流程,模型输出 Mermaid 代码块,界面渲染成图。
235
+ - 修改设置后新开会话使用新文案;旧会话回复风格不变。
236
+ - 卸载插件后,Mermaid 恢复为普通代码块,新会话不再注入。
237
+
238
+ ## 8. 风险与待验证
239
+
240
+ 1. **会话快照的持久化依赖**:新增 `storageDomain` + `zod` 依赖;需要验证最低 DSH 版本、存储后端路由、域打开失败时的降级,以及卸载后数据保留的用户告知。
241
+ 2. **快照捕获时机**:`agent/created` 的 `source` 与 `SessionHeader` 是否足以区分「新会话 / 恢复 / fork / 子代理」;需要在真实桌面端和 Web 端各验证一遍。
242
+ 3. **缓存收益的可观测性**:目前只能通过 system prompt 文本稳定和 provider cache 命中日志间接验证;需要在真实 DeepSeek 账户下观察 `cacheReadTokens` 或等价指标。
243
+ 4. **mermaid 12 的默认布局/外观**:ELK 和 `neo` 会改变图的观感;若升级 12,必须显式固定 `layout`、`look`、`theme` 并回归视觉。
244
+ 5. **一次生成成功率**:默认提示词不列图类型白名单,模型可选用 Mermaid 11.15.0 内置的全部图表类型;仍可能出现节点 id 冲突、括号/引号不配对、`end` 缺失等错误。错误块和复制自救是兜底,但发布前要用真实模型输出做 A/B 语料测试。
245
+ 6. **bundle 体积与首屏**:11.15.0 约 3.3 MB(gzip 约 0.9 MB),12.3.0 约 5.5 MB(gzip 约 1.6 MB);需要实测页面启动解析耗时和首次渲染延迟。
246
+ 7. **徽章精度**:当前是插件级状态,不区分旧会话是否真的持有快照;文案避免过度承诺「当前会话」。
247
+ 8. **非交互会话**:定时任务、工作流等会话没有可靠的类型标记,当前会按普通会话处理;若需要排除,后续再加判断。
248
+ 9. **pre-stable API**:围栏槽位、`settings.section`、`configForms`、`systemPrompt` 都是 DSH 的 pre-stable 接口,升级 DSH 版本时要回归。
249
+ 10. **设置页成本**:自定义页面、计数器、保存/恢复默认、只读和冲突状态都要测;不要低估这部分工作量。
250
+ 11. **主题映射**:Mermaid 的 `base` 主题变量与宿主 token 不是一一对应;需要在亮色/暗色下检查对比度,特别是 sequence/state/ER。
251
+ 12. **安全**:strict、`maxTextSize`/`maxEdges`、SVG 下载内容都要检查;停留在 11.x 时要覆盖 DOMPurify 版本并记录残余风险。
252
+
253
+ ## 9. 与后续 skill 的关系
254
+
255
+ - skill 手动触发,只在被调用时把更丰富的形态说明加载进上下文,不增加每轮成本。
256
+ - skill 提供的形态必须先在渲染层实现;默认提示词不提及它们,避免模型输出接不住的内容。
257
+ - 候选形态:消毒后的 SVG、受约束的图文卡片/时间线。具体取舍放到 skill 阶段再定,不提前写进默认提示词。
@@ -0,0 +1,84 @@
1
+ # 迭代路线
2
+
3
+ > 状态:v0.1 MVP。功能以 `designs/friendly-expression/` 的设计稿为准,实现方式以 DSH 当前插件最佳实践为准。
4
+
5
+ ## v0:设计与骨架(已完成)
6
+
7
+ - 建立 `@westwall/dsh-friendly-expression` 包骨架、bundle patch、locale 与图标占位。
8
+ - 写清定位、注入机制、默认提示词、MVP 范围与验收([DESIGN.md](DESIGN.md))。
9
+ - 安装后不改变宿主行为。
10
+
11
+ ## v0.1:MVP(当前)
12
+
13
+ 目标:一段可编辑的提示词,加上一个能看的 Mermaid 图。
14
+
15
+ Host:
16
+
17
+ - `Config`:`stylePrompt`(≤800 字符,`.volatile()`,默认 164 字正文;注册时另加一行固定英文引导语,不计入这 800 字符)。
18
+ - 按 Agent 注册 system prompt section,仅 Web/桌面注入。
19
+ - 新会话创建时把提示词写入 `storageDomain` 快照;已有会话使用快照,重启/恢复不变。子代理不注入。
20
+ - 设置页:`settings.section` + `settings.section.icon`,用 `ctx.configForms` 读写,自绘 textarea,不加 `ConfigField` 依赖。
21
+
22
+ 客户端:
23
+
24
+ - 声明 `dsh.client`,注册 `conversation.chat.markdown.fence` 的 `mermaid` 层。
25
+ - 流式显示源码,落定渲染;解析/渲染失败回退源码块,并提供「复制错误给 Agent」。
26
+ - 内联卡片:源码切换、复制、放大。
27
+ - 浮窗:滚轮缩放、拖拽平移、适合窗口、1:1、复制源码、下载 SVG。
28
+ - `shell.overlay` 承载浮窗;`<img>` + Blob URL 显示 SVG,避免重复 id 和脚本执行。
29
+ - 主题跟随、`code + theme` 缓存、可视区懒渲染。
30
+ - 会话头部「友好表达已开启」小徽章;插件级状态,提示词为空时隐藏。
31
+ - Mermaid 11.15.0,构建进 `client.js`;动态加载,初始化时固定 `securityLevel: 'strict'`、`maxTextSize: 20000`、`maxEdges: 500`。
32
+
33
+ 验收:
34
+
35
+ - Web 会话里模型输出 Mermaid 代码块能渲染成图,点击可放大查看。
36
+ - 非法语法不影响整条消息,错误信息可复制给 Agent。
37
+ - 800 字符超限被拒绝;恢复默认回落到推荐文案。
38
+ - 旧会话保持快照,重启/恢复后 system prompt 不变;子代理不注入。
39
+ - CLI/headless 不注入提示词。
40
+ - 设置页、徽章、浮窗在 Web/桌面实际界面可用。
41
+ - 记录 `client.js` 体积(当前 3.28 MiB);首屏解析耗时待补测。
42
+
43
+ ## v0.2:打磨
44
+
45
+ - 主题令牌映射细化,暗色模式对比度检查。
46
+ - 错误提示与重试、空图/超大图的边界。
47
+ - 可访问性:标题/描述、键盘操作、焦点管理。
48
+ - 国际化补齐:配置页、错误文案、浮窗和徽章全部走 locale。
49
+ - 源码切换、复制、下载之外的操作为实际需要再加。
50
+ - 测试补齐:层渲染、回退、浮窗交互、配置页 reset。
51
+ - 评估严格的逐会话徽章状态;现在徽章只表示插件已开启。
52
+ - 评估 Mermaid 12.x:用真实模型输出做 11.15.0 与 12.x 的 A/B,若成功率不劣再升级。
53
+
54
+ ## v1.0:手动触发的 skill
55
+
56
+ 目标:在用户明确需要「更丰富的视觉表达」时,提供比 Mermaid 更自由、但成本更高的形态。
57
+
58
+ - skill 手动触发,不进入默认提示词;加载时才把形态说明与约束放进上下文。
59
+ - 先实现渲染层支持的形态,再写 skill 说明;候选是消毒后的 SVG 或受约束的图文卡片/时间线。
60
+ - skill 的说明要写清触发条件、体积/成本边界和失败回退,避免模型滥用。
61
+ - 验收:未触发时行为与 v0.2 完全一致;触发时输出可渲染、可回退,且不污染普通回复。
62
+
63
+ ## 候选(未排期)
64
+
65
+ 这些能力都可以从「表达方式」入口扩展,不需要改渲染层:
66
+
67
+ - 语气预设:幽默、调皮、正式、简洁;每段称呼用户。
68
+ - 语言约束:回复中不出现英文、术语必须给中文解释。
69
+ - 长度约束:先给一句话结论,展开不超过 N 段。
70
+ - 按 profile 或按会话切换风格(当前是 profile 级)。
71
+ - 更多形态:数据图表、交互式卡片;只在有稳定需求时评估。
72
+
73
+ ## 明确不采用
74
+
75
+ - **A2UI / AG-UI / Vercel Generative UI 全栈**:它们是「agent 生成应用界面」的协议,不是聊天里的低成本图形表达;引入 SDK + catalog + surface 状态不划算。
76
+ - **通用图表 DSL / Graphviz / D2 / PlantUML**:渲染器更重、模型先验更弱,收益不如 Mermaid + 表格。
77
+ - **图片生成**:延迟、成本、不可复现,不适合每轮表达。
78
+ - **CLI 注入**:终端没有渲染面,Mermaid 源码比 ASCII 更难读。
79
+ - **工具卡片/详情页渲染**:本插件只处理对话里的 assistant 消息,工具结果有自己的展示机制。
80
+
81
+ ## 发布节奏
82
+
83
+ - v0.1 之前保持 `private: true`,只走本地 `link:` 或固定 commit。
84
+ - 首次发布在 v0.1 打磨完成、走完 [RELEASING.md](../../../docs/RELEASING.md) 之后;tag 形如 `dsh-friendly-expression@<version>`。
package/icon-180.png ADDED
Binary file
package/icon-512.png ADDED
Binary file
package/icon.svg ADDED
@@ -0,0 +1,6 @@
1
+ <svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
2
+ <path d="M7 9.5h22a3 3 0 0 1 3 3v9a3 3 0 0 1-3 3H17l-6.5 4.5V24.5H7a3 3 0 0 1-3-3v-9a3 3 0 0 1 3-3Z" stroke="#3D5A80" stroke-width="2" stroke-linejoin="round"/>
3
+ <circle cx="13" cy="17" r="1.5" fill="#3D5A80"/>
4
+ <circle cx="18" cy="17" r="1.5" fill="#3D5A80"/>
5
+ <circle cx="23" cy="17" r="1.5" fill="#3D5A80"/>
6
+ </svg>
package/lib/index.d.ts ADDED
@@ -0,0 +1,19 @@
1
+ /** Host half freezes one expression prompt per new Web session and injects it scoped to that agent. */
2
+ import type { Context } from '@deepseek-ai/cordis';
3
+ import z from '@deepseek-ai/schemastery';
4
+ export declare const name = "friendly-expression";
5
+ export declare const inject: string[];
6
+ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
7
+ stylePrompt: z<string, string, "volatile-defined">;
8
+ }>>, Schemastery.ObjectT<NoInfer<{
9
+ stylePrompt: z<string, string, "volatile-defined">;
10
+ }>>, "plain">;
11
+ interface FriendlyExpressionConfig {
12
+ stylePrompt: string | {
13
+ get(): string;
14
+ } | undefined;
15
+ }
16
+ /** Read a volatile config field whether the Host handed back a raw string or a reference. */
17
+ export declare function readStylePrompt(value: FriendlyExpressionConfig['stylePrompt']): string;
18
+ export declare function apply(ctx: Context, config: FriendlyExpressionConfig): Promise<void>;
19
+ export {};
package/lib/index.js ADDED
@@ -0,0 +1,89 @@
1
+ import z from '@deepseek-ai/schemastery';
2
+ import { DEFAULT_STYLE_PROMPT, MAX_PROMPT_CHARS, renderSection, SECTION_NAME, SECTION_ORDER, } from "./prompt.js";
3
+ import { openSnapshotStore, shouldCapture } from "./snapshot.js";
4
+ export const name = 'friendly-expression';
5
+ export const inject = ['systemPrompt', 'storageDomain'];
6
+ export const Config = z.object({
7
+ stylePrompt: z.string().max(MAX_PROMPT_CHARS).default(DEFAULT_STYLE_PROMPT).volatile(),
8
+ });
9
+ /** Read a volatile config field whether the Host handed back a raw string or a reference. */
10
+ export function readStylePrompt(value) {
11
+ if (typeof value === 'string')
12
+ return value;
13
+ return value?.get() ?? '';
14
+ }
15
+ function hasWebSurface(ctx) {
16
+ return ctx.get('webApp') !== undefined || ctx.get('webServer') !== undefined;
17
+ }
18
+ function warn(message, error) {
19
+ console.warn(`[dsh-friendly-expression] ${message}`, error);
20
+ }
21
+ export async function apply(ctx, config) {
22
+ const store = await openSnapshotStore(ctx);
23
+ const sections = new Map();
24
+ const registerSection = (agent, prompt) => {
25
+ const sessionId = agent.session.id;
26
+ const existing = sections.get(sessionId);
27
+ if (prompt.length === 0) {
28
+ existing?.dispose();
29
+ sections.delete(sessionId);
30
+ return;
31
+ }
32
+ if (existing?.agent === agent)
33
+ return;
34
+ existing?.dispose();
35
+ const promptCtx = agent.ctx;
36
+ const dispose = agent.ctx.effect(() => promptCtx.systemPrompt.section({
37
+ name: SECTION_NAME,
38
+ order: SECTION_ORDER,
39
+ text: prompt,
40
+ }), 'friendly-expression prompt section');
41
+ sections.set(sessionId, { agent, dispose });
42
+ };
43
+ ctx.effect(() => () => store.close(), 'friendly-expression snapshot store');
44
+ ctx.effect(() => () => {
45
+ for (const entry of sections.values())
46
+ entry.dispose();
47
+ sections.clear();
48
+ }, 'friendly-expression prompt sections');
49
+ ctx.on('agent/created', ({ agent }) => {
50
+ if (!hasWebSurface(ctx))
51
+ return undefined;
52
+ if (agent.session.header.origin === 'subagent')
53
+ return undefined;
54
+ // A stored snapshot registers verbatim. Sections captured before the prefix
55
+ // existed stay body-only, which keeps their system prompt byte-identical.
56
+ let prompt = store.get(agent.session.id);
57
+ if (prompt === undefined) {
58
+ const fresh = shouldCapture({
59
+ isSubagent: false,
60
+ isSeeded: agent.session.header.isSeeded,
61
+ hasMessages: agent.session.surface.nodes.length > 0,
62
+ });
63
+ if (!fresh)
64
+ return undefined;
65
+ prompt = renderSection(readStylePrompt(config.stylePrompt));
66
+ void store.capture(agent.session.id, prompt).catch((error) => {
67
+ warn(`failed to capture the prompt snapshot for session ${agent.session.id}`, error);
68
+ });
69
+ }
70
+ registerSection(agent, prompt);
71
+ return undefined;
72
+ });
73
+ ctx.on('agent/disposed', ({ agent }) => {
74
+ const entry = sections.get(agent.session.id);
75
+ if (entry?.agent === agent)
76
+ sections.delete(agent.session.id);
77
+ });
78
+ const registry = ctx.get('agents');
79
+ if (registry !== undefined && hasWebSurface(ctx)) {
80
+ for (const agent of registry.list()) {
81
+ if (agent.session.header.origin === 'subagent')
82
+ continue;
83
+ const prompt = store.get(agent.session.id);
84
+ if (prompt !== undefined)
85
+ registerSection(agent, prompt);
86
+ }
87
+ }
88
+ }
89
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,20 @@
1
+ /** Prompt budget, default copy, hidden prefix, and the per-agent system prompt seat. */
2
+ /** Hard cap shared by the Host schema and the settings counter. It measures the editable body, not the registered section. */
3
+ export declare const MAX_PROMPT_CHARS = 800;
4
+ /**
5
+ * Fixed English lead-in prepended at capture. Settings never see it: the
6
+ * textarea, the counter, and 恢复默认 all deal in the body alone. Capture
7
+ * freezes prefix and body together, so changing this text cannot alter a
8
+ * session that already has a snapshot.
9
+ */
10
+ export declare const SECTION_PREFIX = "When talking with the user, follow these principles:";
11
+ /** Recommended copy. UTF-16 length is 164. */
12
+ export declare const DEFAULT_STYLE_PROMPT = "\u7D27\u6263\u95EE\u9898\uFF0C\u5148\u7ED9\u7ED3\u8BBA\uFF0C\u518D\u7ED9\u5FC5\u8981\u4F9D\u636E\u3002\u4E0D\u786E\u5B9A\u7684\u5730\u65B9\u660E\u786E\u6807\u6CE8\uFF0C\u4E0D\u7F16\u9020\u3002\u53EA\u8BB2\u76F8\u5173\u4FE1\u606F\uFF0C\u4E0D\u590D\u8FF0\u5DF2\u77E5\u5185\u5BB9\u3002\u957F\u5185\u5BB9\u5206\u70B9\uFF0C\u6309\u91CD\u8981\u6027\u6392\u5E8F\uFF1B\u8BED\u6C14\u81EA\u7136\u76F4\u63A5\uFF0C\u4E0D\u5806\u5BA2\u5957\u3002\u7981\u6B62\u4F7F\u7528 ASCII \u65B9\u6846\u548C\u7BAD\u5934\u753B\u56FE\uFF1B\u9ED8\u8BA4\u7528 Mermaid 11.x\u8868\u8FBE\uFF0C\u7B80\u5355\u5185\u5BB9\u4E0D\u5F3A\u884C\u753B\u56FE\u3002\u5BF9\u6BD4\u7528\u8868\u683C\uFF0C\u7EBF\u6027\u6B65\u9AA4\u7528\u6709\u5E8F\u5217\u8868\uFF0C\u6587\u4EF6\u6811\u4FDD\u7559\u7F29\u8FDB\u3002\u7528\u6237\u660E\u786E\u8981\u6C42\u5176\u4ED6\u5F62\u5F0F\u65F6\uFF0C\u4EE5\u7528\u6237\u8981\u6C42\u4E3A\u51C6\u3002";
13
+ /** Longest stored section: the prefix, one newline, and a maximum-length body. */
14
+ export declare const MAX_SECTION_CHARS: number;
15
+ /** Compose the text registered for a session. An empty body means no section at all. */
16
+ export declare function renderSection(prompt: string): string;
17
+ /** Stable section name, registered per agent rather than globally. */
18
+ export declare const SECTION_NAME = "westwall:friendly-expression";
19
+ /** Sits after first-party guidance and before deployment paths. */
20
+ export declare const SECTION_ORDER = 9500;
package/lib/prompt.js ADDED
@@ -0,0 +1,23 @@
1
+ /** Prompt budget, default copy, hidden prefix, and the per-agent system prompt seat. */
2
+ /** Hard cap shared by the Host schema and the settings counter. It measures the editable body, not the registered section. */
3
+ export const MAX_PROMPT_CHARS = 800;
4
+ /**
5
+ * Fixed English lead-in prepended at capture. Settings never see it: the
6
+ * textarea, the counter, and 恢复默认 all deal in the body alone. Capture
7
+ * freezes prefix and body together, so changing this text cannot alter a
8
+ * session that already has a snapshot.
9
+ */
10
+ export const SECTION_PREFIX = 'When talking with the user, follow these principles:';
11
+ /** Recommended copy. UTF-16 length is 164. */
12
+ export const DEFAULT_STYLE_PROMPT = `紧扣问题,先给结论,再给必要依据。不确定的地方明确标注,不编造。只讲相关信息,不复述已知内容。长内容分点,按重要性排序;语气自然直接,不堆客套。禁止使用 ASCII 方框和箭头画图;默认用 Mermaid 11.x表达,简单内容不强行画图。对比用表格,线性步骤用有序列表,文件树保留缩进。用户明确要求其他形式时,以用户要求为准。`;
13
+ /** Longest stored section: the prefix, one newline, and a maximum-length body. */
14
+ export const MAX_SECTION_CHARS = SECTION_PREFIX.length + 1 + MAX_PROMPT_CHARS;
15
+ /** Compose the text registered for a session. An empty body means no section at all. */
16
+ export function renderSection(prompt) {
17
+ return prompt.length === 0 ? '' : `${SECTION_PREFIX}\n${prompt}`;
18
+ }
19
+ /** Stable section name, registered per agent rather than globally. */
20
+ export const SECTION_NAME = 'westwall:friendly-expression';
21
+ /** Sits after first-party guidance and before deployment paths. */
22
+ export const SECTION_ORDER = 9500;
23
+ //# sourceMappingURL=prompt.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"prompt.js","sourceRoot":"","sources":["../src/prompt.ts"],"names":[],"mappings":"AAAA,wFAAwF;AAExF,8HAA8H;AAC9H,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAA;AAEnC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,sDAAsD,CAAA;AAEpF,8CAA8C;AAC9C,MAAM,CAAC,MAAM,oBAAoB,GAAG,sKAAsK,CAAA;AAE1M,kFAAkF;AAClF,MAAM,CAAC,MAAM,iBAAiB,GAAG,cAAc,CAAC,MAAM,GAAG,CAAC,GAAG,gBAAgB,CAAA;AAE7E,wFAAwF;AACxF,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,OAAO,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,cAAc,KAAK,MAAM,EAAE,CAAA;AAClE,CAAC;AAED,sEAAsE;AACtE,MAAM,CAAC,MAAM,YAAY,GAAG,8BAA8B,CAAA;AAE1D,mEAAmE;AACnE,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,CAAA"}
@@ -0,0 +1,39 @@
1
+ /**
2
+ * One frozen section plus its capture time, stored per session. `prompt` holds
3
+ * the full section text for captures made by this version, prefix included.
4
+ * Snapshots written before the prefix existed hold the body alone and are
5
+ * registered exactly as stored.
6
+ */
7
+ export interface PromptSnapshot {
8
+ prompt: string;
9
+ capturedAt: number;
10
+ }
11
+ /** Read a prompt by session id and persist one capture. */
12
+ export interface SnapshotStore {
13
+ get(sessionId: string): string | undefined;
14
+ capture(sessionId: string, prompt: string): Promise<void>;
15
+ close(): Promise<void>;
16
+ }
17
+ export declare const promptSnapshotDomain: {
18
+ name: string;
19
+ version: number;
20
+ layout: "per-record";
21
+ invalidRecords: "backup-and-skip";
22
+ tables: {
23
+ sessions: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<string, PromptSnapshot>;
24
+ };
25
+ };
26
+ interface SnapshotContext {
27
+ get(name: string): unknown;
28
+ }
29
+ /** Process-local fallback. A capture is readable before its returned promise settles. */
30
+ export declare function createMemorySnapshotStore(now?: () => number): SnapshotStore;
31
+ /** Open the durable domain when the Host provides it, otherwise keep snapshots for this run. */
32
+ export declare function openSnapshotStore(ctx: SnapshotContext): Promise<SnapshotStore>;
33
+ /** Only a brand new, non-subagent, non-seeded, empty session captures a prompt. */
34
+ export declare function shouldCapture(input: {
35
+ isSubagent: boolean;
36
+ isSeeded: boolean;
37
+ hasMessages: boolean;
38
+ }): boolean;
39
+ export {};