> [!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

独立安装（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/*.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 服务防御

故障排查

前置依赖

无第三方依赖（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）。