提示词润色助手shengyvself/narrative-prompt-polish

[!IMPORTANT]
本仓已迁移 → 请使用 dsh-prompt-only-forge（v0.3.0+，2026-09-14 首发）。
旧仓 narrative-prompt-polish 保持只读状态，不再接受新提交；历史版本（v0.0.26 / v0.0.27 / v0.1.0 / v0.2.0）仍可通过 Releases 页获取。
新仓定位：纯注入（no send action）提示词润色，独立于 better-sidebar 侧栏对话，架构与 API 完全重写。

— shengyv, 2026-09-14

narrative-prompt-polish

Shengyv's Writing Architecture 的提示词优化插件：主会话输入框右座 ✨ 一键起一个
可对话的子代理，把草稿打磨成清晰、具体、可直接交给 AI Agent 执行的提示词——
在子代理会话里多轮追问，满意后手动复制回主输入框。

核心特性
- 主框 ✨ → 可对话子代理打磨（默认主流程，0.2.0+）：点击主框 ✨ 不直接改草稿，
而是由服务端 POST /api/polish.start 在主会话下起一个 continuable 子代理
（ctx.subagents.startContinuable，provider 默认 fork：seed 主会话已完成轮、
继承父 Agent 的 provider/model/推理档与预设），把「任务书 + 草稿」投进它的首轮；
客户端随后 ctx.sessions.openSubagent 打开该子代理会话——它是原生会话界面，
输入框可写，可多轮追问，满意后复制回主输入框。子代理起不来时显式报错
（红线 9：绝不静默降级到单次 polish）。
- 0.2.0 前该主流程依赖 better-sidebar 的 sidechat；better-sidebar 已从本部署架构移除
（0.1.5 起右侧栏面板一律走官方 keyed 槽位），故主路径改为内核原生子代理。
- C 方案（full，默认）：ctx.sessions.get() → deriveMessages() + requestHeader().system/config，
完整复刻 [system]+[...history] 前缀直调 ctx.llm.stream——前缀与主会话一致即命中 prompt cache，
只增量计算草稿与润色指令。非 live 会话走 sessionQuery.readSession() 离线折叠兜底。
- 降级链：full → partial（readSurface 近期对话）→ none（裸草稿），
每次降级在响应 fallbackReasons 与 trace 中留痕；strictFull: true 可改为硬失败（no-session）。
- 意图骨架：本地正则分类 debug/implement/explain/chat；partial/none 下骨架进 system，
full 下骨架折进末尾 user 指令（不动 system 前缀以保缓存）。
- CAS 写回（历史单次 polish 路径）：点击时捕获草稿指纹，返回后若草稿已变则弹
「草稿已变，未应用润色」且不覆盖。
- 错误细分：rejected(empty/references/too-large)、no-session、route-unavailable、
stream-failed、empty-result、context-fallback、settings-unavailable。
- trace：每次调用追加 JSONL 到 lore/traces/prompt-polish/YYYY-MM-DD.jsonl
（intent/contextMode/fallbacks/cacheHit/tokens/hash 等；hash 不落全文）。设置页可关。
- 事件总线（外部模块联动，0.2.0 收窄）：window 上广播
narrative:prompt-polish:trigger（{triggerSource, draft?, targetElement?}）→ 本插件代跑
单次 /api/polish（不占用子代理）→ CAS 回写 target → 广播 …:result；不带
targetElement 则只广播、模块自理回写。契约见 docs/sidebar-integration.md。
- sidebar 浮按钮（0.2.0 已移除）：随 better-sidebar 一并删除（宿主 DOM 标记
[data-dsh-better-sidebar] 在本部署已不存在）；配置键 sidebarFloatingButtonEnabled
仅保留以免已存设置文档失配，无任何行为。

红线遵守
- 不写主会话历史：无 append、llm.stream 不传 sessionId（不进会话调度）。
- 无野生 DOM 注入：UI 走官方 slot conversation.input.right + settings.section。
- 服务端零 @deepseek-ai/ 静态 import（dsh-session 仅离线路径动态 import 且失败自动降级），
杜绝缺依赖崩 web。

API
| 方法 | 说明 |
|---|---|
| POST /narrative-prompt-polish/api/polish.start | {sessionId,text,triggerSource?,provider?} → {childId,messageId,intent,subagentProvider}（主路径：起可对话子代理，任务书投首轮） |
| POST /narrative-prompt-polish/api/polish | {sessionId,text,mode?,strictFull?,triggerSource?,mergeSidebarContext?,sidebarContext?}（单次直调路径：事件总线 / headless / 自动化） |
| POST .../api/config /config.get /config.update | 配置读改（settings 服务缺位时 update 返回 503） |
| POST .../api/traces.recent | {limit} 最近 trace |
| POST .../api/apply-report | 客户端 CAS 结果回传（applied/changed），trace 行按 traceTs 配对 |

独立安装（GitHub）
dsh plugin --profile web add github:shengyvself/narrative-prompt-polish
或克隆后：
dsh plugin --profile web add ./narrative-prompt-polish
安装后重启 DSH Web 即生效。无第三方依赖：主路径走内核原生 ctx.subagents（continuable）
+ ctx.sessions.openSubagent，要求内核版本含子代理编排服务（DSH ≥ 0.1.5 实测）。
默认配置开箱即用（子代理继承当前会话的 provider/model/预设；trace 写入
/lore/traces/prompt-polish/，可在设置页改为绝对路径锚定你的工作区）。

License

本项目以 MIT 发布。

开发
npm run build   # src → lib 直拷
npm test        # node --test tests/

验证链（改插件红线）：node --check → preflight 4 关 → build → import 冒烟 → 加 bundle → 重启 → 3 连测 200 → dump-config → 日志扫描。

文件结构
src/index.js            host 入口（围栏路由 + settings 防御式注册）
src/api.js              方法表 + polish 主流程（校验→意图→上下文→直调→清洗→trace）
src/context-assembler.js C 方案探测链 full→partial→none
src/surface-fold.js     readSurface 过滤折叠（纯函数）
src/intent.js           4 类意图骨架
src/polish.js           流组装/输出清洗/usage 提取（纯函数）
src/trace-recorder.js   JSONL trace
src/trust-fence.js      浏览器信任围栏
src/wire.js             JSON 信封
src/taskbook.js         主路径任务书文本（服务端；与 /api/polish 共用意图判定）
src/client.bundle.js    客户端（PolishButton/PolishSettings + 事件总线 + startPolishSubagent 子代理打磨）
tests/unit.test.mjs     32 例单测（node --test）
scripts/smoke-apply.mjs 服务端 apply 冒烟（真 apply + 假 cordis ctx，16 断言）
docs/decisions.md       设计决策记录
docs/sidebar-integration.md  联动层集成指南
架构概览

本插件按职责划分为以下子层:

| 层 | 文件 | 职责 |
|---|---|---|
| 入口 | src/index.js | DSH host 半边挂载点 + trust fence 围栏 |
| API 路由 | src/api.js | /api/polish /api/config /api/traces.recent /api/apply-report 方法表 |
| 上下文 | src/context-assembler.js | C 方案: deriveMessages + requestHeader 复刻 [system]+[history] |
| 表面 | src/surface-fold.js | partial 降级时 readSurface 读近期对话 |
| 意图 | src/intent.js | 4 类意图骨架: debug / implement / explain / chat |
| 流组装 | src/polish.js | 拼请求 + 调 ctx.llm.stream + 清洗 |
| Trace | src/trace-recorder.js | 每次调用追加 JSONL 到 lore/traces/prompt-polish/YYYY-MM-DD.jsonl |
| 错误细分 | src/wire.js + src/api.js | rejected / no-session / route-unavailable / stream-failed / empty-result / context-fallback / settings-unavailable |
| 主路径 | src/taskbook.js + src/api.js#polish.start | 任务书 → ctx.subagents.startContinuable（continuable 子代理） |
| 客户端 | src/client.bundle.js | PolishButton + PolishSettings + 事件总线 + startPolishSubagent |

构建流程: src/.js → scripts/build.mjs 直拷 → lib/.js (md5 一致; 用 scripts/preflight.sh 防回归)。

测试策略

- 单元测试: node --test tests/unit.test.mjs (32 用例, 全绿)
- Preflight: bash scripts/preflight.sh (build 前 5 关: 语法 / 大小无异常翻倍 / 单一 __ModuleLoader__.load / 核心防御未丢 / better-sidebar 耦合为 0)
- apply 冒烟: node scripts/smoke-apply.mjs (真 apply + 假 cordis ctx: 围栏 403 / 405 / polish.start 200 / no-live-agent 409 / rejected 400)
- 端到端: DSH web 装上 plugin → 主框输入草稿 → 点 ✨ → 子代理会话被打开（任务书进首轮）→ 多轮追问 → 手动复制回填
- 回归：8/27 incident 教训——client.bundle.js 56K 重复 bug，由 preflight 关 3（单一 __ModuleLoader__.load）防回归；关 4 守 slots 服务防御

故障排查

| 现象 | 可能原因 | 处置 |
|---|---|---|
| 点 ✨ 报「sessions 服务未注入」 | 客户端插件未挂载（0.1.5 需重启生效） | 重启 DSH Web 后刷新页面 |
| 点 ✨ 报「主会话没有 live agent」 | 会话未激活 / agent 已被回收 | 在当前会话里重试 |
| 报「子代理已创建但客户端目录未就绪」 | 客户端会话目录刷新延迟 | 在会话列表的「子代理」目录里手动打开该 childId |
| 子代理起不来 | 内核缺 ctx.subagents / provider 未注册 | dsh --profile web --dump-config \| grep subagent 核对 |
| 提示词无变化 | strictFull=true 但会话非 live | 改 strictFull=false（允许降级到 partial/none） |
| 草稿被覆盖 | 草稿在 polish 期间被用户改了 | CAS 拒绝覆盖，重试时用最新草稿 |
| TRACE 太大 | 没设置 pageSize 限制 | 设置页可关 / 设保留天数 |
| slots 注入失败（console.warn） | DSH 启动顺序 race | 正常降级，主壳照常加载，✨ 与设置页暂时不可见 |

前置依赖

无第三方依赖（0.2.0 起）。主路径需要内核提供 ctx.subagents（continuable 子代理）与
ctx.sessions.openSubagent；本部署（DSH 0.1.5-rc.2）已具备。子代理 provider 默认 fork
（dsh-subagent-fork-in-process，seed 母会话已完成轮），可在设置里切 spawn（全新子代理）。

自检：两个 provider 在组合树里
dsh --profile web --dump-config | grep -A2 subagent

降级说明：/api/polish 单次直调路径仍在（事件总线 / headless / 自动化用），但主框 ✨
不会*在子代理失败时退到它（红线 9）。