@morlay/dsh-prompt-reminder 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 morlay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# @morlay/dsh-prompt-reminder
+
+把系统提示词里被裁掉的 section 降级为 `<system-reminder>` user 消息的 cordis
+插件：系统提示词只留部署级 persona（`personaPrefix` / `personaSuffix`），工具
+说明、Agent Teams 规则、plan 规则、PTC SDK 文档等在每轮请求前随用户消息送达。
+
+## 为什么
+
+上游把每个工具的跨调用说明（`tool:bash`、`tool:read`、`tool:glob`、…）、Agent
+Teams 协作规则、harness 源码位置、Web GUI 说明都注册成系统提示词的 section。
+它们条数多、篇幅大（本部署实测 9200 字符里约 7400），挤在上下文最前面稀释
+真正要遵守的少量纪律。本插件把这些 section 从系统提示词移到紧随用户消息之后
+的 reminder：内容一字不少，注意力分层干净；系统提示词也不再随 plan / PTC 模式
+切换而变动。
+
+## 行为
+
+| 环节                             | 做什么                                                                               |
+| -------------------------------- | ------------------------------------------------------------------------------------ |
+| `system-prompt/assemble`（瀑布） | 保留 `keep` 名单内的 section；其余非空 section 从 assembly 移除，并按 order 捕获文本 |
+| `agent/pre-step`                 | 本轮文本与上一次送达的不同时，注入一条 user 消息，位置紧随已领取的这批消息之后       |
+
+- **信封**：`<system-reminder>`，与工作区指令同一约定。首行声明系统提示词是刻意
+  精简的、下面的内容仍属系统级规则、最新一条覆盖更早的 reminder。
+- **首步一次 + 变化增量**：文本不变时不重复注入；`plan:policy`、`tools:ptc-only`、
+  `tools:sdk` 这类按模式渲染的 section 变化时追加一条新的**全量** reminder
+  （靠首行的覆盖声明消歧，不试图只发差量）。
+- **幂等**：进程内按 agent 记最近送达文本；重启 / 恢复时扫会话 surface 上最近一条
+  本插件消息，文本相同就不再注入。
+- **转义**：正文里的 `</system-reminder>` 写成 `<\/system-reminder>`，避免提前闭合信封。
+
+## 配置
+
+| 字段   | 默认                                                         | 含义                                                       |
+| ------ | ------------------------------------------------------------ | ---------------------------------------------------------- |
+| `keep` | `['deployment:persona-prefix', 'deployment:persona-suffix']` | 留在系统提示词里的 section 名；其余（非空）降级为 reminder |
+
+`keep` 按 **section 名**匹配，所以子 agent 在 agent scope 注册的同名 persona 也
+自动留在系统提示词里。
+
+## 装配
+
+作为 **host plane** 的部署级行，在 profile 的 bundle patch 里定义一次即可：
+
+```yaml
+- insert:
+    - id: prompt-reminder
+      name: "@morlay/dsh-prompt-reminder"
+```
+
+`@morlay/dsh-preset` 的 `cordis.patch.yml` 就是这么声明的：一次覆盖全部 preset
+（standard / ptc 以及后续新增的），preset composition 不各自带这一行。
+
+profile 的依赖树必须能解析该包名（示例 app `apps/dsh-custom-next` 的
+`dependencies` 已声明）——preset 的行与 host plane 的行都用 profile 的 resolver
+解析，换工作区时要一并声明，否则该行加载失败、工具说明会留在系统提示词里。
+
+放在 host plane 而不是 preset composition：这是一条与具体 preset 无关的部署级
+策略；注册在 root scope 的 listener 会收到每个 agent 的装配与 pre-step 事件。
+
+## 前提
+
+- 系统提示词由部署级 `system-prompt` 的 `personaPrefix` / `personaSuffix` 提供，
+  只在 `@morlay/dsh-preset` 的 `cordis.patch.yml` 维护一份；`keep` 与之一致。
+- 裁剪与降级由同一份 `keep` 名单决定，不存在"系统提示词删了、reminder 没送"的
+  偏差。上游 `persona` 行的 `complete: true` 也能把系统提示词收到只剩 persona，
+  但它同时丢弃 suffix，且子 agent 注册 persona 时 `complete` 标记消失——本插件
+  不做这种依赖顺序的事。
+- 本插件不写会话事件，reminder 走 pre-step 的消息通道（模型可见即可重建，落库由
+  loop 负责）。
+
+## 已知限制
+
+- **reminder 仍是模型输入**：总 token 不减，只是不再占系统提示词的位置；要真正
+  省 token 得把内容一起删掉。
+- **回退边缘**：rewind 掉旧 reminder 后，若当前文本与内存缓存仍相同，不会立即补
+  一条（重启或下次文本变化时恢复）。
+- **顺序**：reminder 与工作区指令（`AGENTS.md`）都是 pre-step 注入的 user 消息，
+  两者先后由 listener 注册顺序决定，语义上互不依赖。

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+# 本包是纯插件：装配点是 agent preset composition 里的一行（见 README），
+# 不经 bundle patch；空 patch 只为满足包 exports 约定。
+[]

package/dist/index.d.mts

@@ -0,0 +1,22 @@
+import z from "@deepseek-ai/schemastery";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/index.d.ts
+/** Cordis 插件名。 */
+declare const name = "prompt-reminder";
+/** 装配点依赖的系统提示词注册表。 */
+declare const inject: string[];
+/** 插件配置。 */
+interface Config {
+  /** 留在系统提示词里的 section 名；其余非空 section 降级为 reminder。 */
+  keep?: string[];
+}
+/** 运行时配置 schema。 */
+declare const Config: z<Config>;
+/**
+ * 注册裁剪与注入。
+ * @param ctx - preset 的 standing scope 上下文（覆盖该 preset 的全部 agent）。
+ * @param config - 保留名单。
+ */
+declare function apply(ctx: Context, config: Config): void;
+//#endregion
+export { Config, apply, inject, name };

package/dist/index.mjs

@@ -0,0 +1,101 @@
+import z from "@deepseek-ai/schemastery";
+import { PERSONA_PREFIX_SECTION, PERSONA_SUFFIX_SECTION } from "@deepseek-ai/dsh-system-prompt";
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
+//#region src/reminder.ts
+const REMINDER_OPEN = "<system-reminder>";
+const REMINDER_CLOSE = "</system-reminder>";
+const REMINDER_INTRO = "The system prompt for this session is deliberately minimal. The guidance below belongs to it and stays in force; the newest reminder supersedes every earlier one.";
+function escapeFrameBody(body) {
+	return body.replaceAll(REMINDER_CLOSE, "<\\/system-reminder>");
+}
+/** 按原 order 拼接降级 section 文本，渲染一条 reminder 消息文本。 */
+function renderReminder(sectionTexts) {
+	const body = sectionTexts.map(escapeFrameBody).join("\n\n");
+	return `${REMINDER_OPEN}\n${REMINDER_INTRO}\n\n${body}\n${REMINDER_CLOSE}`;
+}
+/** 该 user 消息是否由本插件注入。 */
+function isPromptReminder(message) {
+	return message.source.kind === "prompt-reminder";
+}
+/** 会话 surface 上最近一条 reminder 的文本；跨进程重启后据此恢复幂等。 */
+function latestReminderText(agent) {
+	for (const seq of agent.session.surface.nodes.toReversed()) {
+		const event = agent.session.eventAt(seq);
+		if (event?.type !== "user/message" || !isPromptReminder(event.data)) continue;
+		const [block] = event.data.content;
+		return event.data.content.length === 1 && block?.type === "text" ? block.text : "";
+	}
+}
+/** 构造一条 reminder user 消息。 */
+function reminderMessage(text) {
+	return createUserMessage({
+		content: [{
+			type: "text",
+			text
+		}],
+		source: {
+			kind: "prompt-reminder",
+			form: "instructions"
+		}
+	});
+}
+//#endregion
+//#region src/index.ts
+/** Cordis 插件名。 */
+const name = "prompt-reminder";
+/** 装配点依赖的系统提示词注册表。 */
+const inject = ["systemPrompt"];
+/** 运行时配置 schema。 */
+const Config = z.object({ keep: z.array(z.string()).default([PERSONA_PREFIX_SECTION, PERSONA_SUFFIX_SECTION]) });
+/** 拆出要保留的 section 与要降级的文本；空文本 section 不降级（渲染时本就丢弃）。 */
+function demote(sections, keep) {
+	const kept = [];
+	const texts = [];
+	for (const section of sections) if (keep.has(section.name) || section.text.length === 0) kept.push(section);
+	else texts.push(section.text);
+	return {
+		sections: kept,
+		texts
+	};
+}
+/**
+* 注册裁剪与注入。
+* @param ctx - preset 的 standing scope 上下文（覆盖该 preset 的全部 agent）。
+* @param config - 保留名单。
+*/
+function apply(ctx, config) {
+	const keep = new Set(config.keep ?? []);
+	const captured = /* @__PURE__ */ new WeakMap();
+	const delivered = /* @__PURE__ */ new WeakMap();
+	ctx.on("system-prompt/assemble", async (_assembly, context, next) => {
+		const result = await next();
+		const { sections, texts } = demote(result.sections, keep);
+		const agent = context.agent;
+		if (agent !== void 0) {
+			if (texts.length === 0) captured.delete(agent);
+			else captured.set(agent, renderReminder(texts));
+		}
+		return texts.length === 0 ? result : {
+			...result,
+			sections
+		};
+	});
+	ctx.on("agent/pre-step", async ({ agent, messages }, next) => {
+		const decision = await next();
+		if (decision.kind === "reject" || decision.messages.length === 0) return decision;
+		const reminder = captured.get(agent);
+		if (reminder === void 0 || delivered.get(agent) === reminder) return decision;
+		if (latestReminderText(agent) === reminder) {
+			delivered.set(agent, reminder);
+			return decision;
+		}
+		delivered.set(agent, reminder);
+		const claimedEnd = decision.messages.findLastIndex((message) => messages.includes(message));
+		return {
+			...decision,
+			messages: decision.messages.toSpliced(claimedEnd + 1, 0, reminderMessage(reminder))
+		};
+	});
+}
+//#endregion
+export { Config, apply, inject, name };

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@morlay/dsh-prompt-reminder",
+  "version": "0.0.1",
+  "description": "Demotes the system-prompt sections a reduced prompt leaves out into <system-reminder> user messages, so tool guidance stops diluting the system prompt while it stays in force.",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "preset",
+    "reminder",
+    "system-prompt"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/morlay/better-session.git"
+  },
+  "files": [
+    "dist",
+    "src",
+    "cordis.patch.yml",
+    "!**/__tests__"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json",
+    "./cordis.patch.yml": "./cordis.patch.yml"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-agent": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-agent-loop": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-agent-loop-testkit": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-scope": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-session": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.5-rc.2"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-agent": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-session": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.5-rc.2"
+  },
+  "scripts": {
+    "build": "pnpm exec tsdown"
+  }
+}

package/src/index.ts

@@ -0,0 +1,92 @@
+/**
+ * 把精简系统提示词里被裁掉的 section 降级为 `<system-reminder>` user 消息：
+ * 装配时从 assembly 移除并捕获，pre-step 时注入，内容变化才追加新 reminder。
+ *
+ * 与 preset 的 `persona` 行配合使用：`keep` 名单之外的 section 不再进入系统
+ * 提示词，而是紧随本轮用户消息之后送达，避免工具说明稀释系统提示词。
+ * @module @morlay/dsh-prompt-reminder
+ */
+
+import type { Context } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import {
+  PERSONA_PREFIX_SECTION,
+  PERSONA_SUFFIX_SECTION,
+  type AssembledSection,
+} from "@deepseek-ai/dsh-system-prompt";
+import { latestReminderText, reminderMessage, renderReminder } from "./reminder.ts";
+
+/** Cordis 插件名。 */
+export const name = "prompt-reminder";
+
+/** 装配点依赖的系统提示词注册表。 */
+export const inject = ["systemPrompt"];
+
+/** 插件配置。 */
+export interface Config {
+  /** 留在系统提示词里的 section 名；其余非空 section 降级为 reminder。 */
+  keep?: string[];
+}
+
+/** 运行时配置 schema。 */
+export const Config: z<Config> = z.object({
+  keep: z.array(z.string()).default([PERSONA_PREFIX_SECTION, PERSONA_SUFFIX_SECTION]),
+});
+
+/** 拆出要保留的 section 与要降级的文本；空文本 section 不降级（渲染时本就丢弃）。 */
+function demote(
+  sections: readonly AssembledSection[],
+  keep: ReadonlySet<string>,
+): { sections: AssembledSection[]; texts: string[] } {
+  const kept: AssembledSection[] = [];
+  const texts: string[] = [];
+  for (const section of sections) {
+    if (keep.has(section.name) || section.text.length === 0) kept.push(section);
+    else texts.push(section.text);
+  }
+  return { sections: kept, texts };
+}
+
+/**
+ * 注册裁剪与注入。
+ * @param ctx - preset 的 standing scope 上下文（覆盖该 preset 的全部 agent）。
+ * @param config - 保留名单。
+ */
+export function apply(ctx: Context, config: Config): void {
+  const keep = new Set(config.keep ?? []);
+  // 本轮装配捕获的 reminder 文本，按 agent 区分（子 agent 各有自己的组合与 persona）。
+  const captured = new WeakMap<Agent, string>();
+  // 已知送达 surface 的文本，稳态下据此跳过 surface 扫描。
+  const delivered = new WeakMap<Agent, string>();
+
+  ctx.on("system-prompt/assemble", async (_assembly, context, next) => {
+    const result = await next();
+    const { sections, texts } = demote(result.sections, keep);
+    const agent = context.agent;
+    if (agent !== undefined) {
+      if (texts.length === 0) captured.delete(agent);
+      else captured.set(agent, renderReminder(texts));
+    }
+    return texts.length === 0 ? result : { ...result, sections };
+  });
+
+  ctx.on("agent/pre-step", async ({ agent, messages }, next) => {
+    const decision = await next();
+    // 没有进入模型的消息时不注入：空消息列表属于 no-step turn，下一轮再试。
+    if (decision.kind === "reject" || decision.messages.length === 0) return decision;
+    const reminder = captured.get(agent);
+    if (reminder === undefined || delivered.get(agent) === reminder) return decision;
+    if (latestReminderText(agent) === reminder) {
+      delivered.set(agent, reminder);
+      return decision;
+    }
+    delivered.set(agent, reminder);
+    // 贴近已领取的这批消息之后：直接输入在前，注入的上下文紧随其后。
+    const claimedEnd = decision.messages.findLastIndex((message) => messages.includes(message));
+    return {
+      ...decision,
+      messages: decision.messages.toSpliced(claimedEnd + 1, 0, reminderMessage(reminder)),
+    };
+  });
+}

package/src/reminder.ts

@@ -0,0 +1,63 @@
+/**
+ * 渲染与识别降级 reminder：信封沿用工作区指令的 `<system-reminder>` 约定。
+ * @module @morlay/dsh-prompt-reminder/reminder
+ */
+
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type {} from "@deepseek-ai/dsh-llm";
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
+import type { UserMessage } from "@deepseek-ai/dsh-session";
+
+const REMINDER_OPEN = "<system-reminder>";
+const REMINDER_CLOSE = "</system-reminder>";
+
+// 首行声明来源与替代语义：模型需要知道这些是系统级规则、且最新一条覆盖旧的。
+const REMINDER_INTRO =
+  "The system prompt for this session is deliberately minimal. The guidance below belongs to it and stays in force; the newest reminder supersedes every earlier one.";
+
+/** 本插件注入的 user 消息来源（`MessageSourceMap` 是 merge-extensible 的）。 */
+export interface PromptReminderSource {
+  kind: "prompt-reminder";
+  form: "instructions";
+}
+
+declare module "@deepseek-ai/dsh-llm" {
+  interface MessageSourceMap {
+    "prompt-reminder": PromptReminderSource;
+  }
+}
+
+// 正文里出现闭合标记会提前结束信封，替换成转义写法。
+function escapeFrameBody(body: string): string {
+  return body.replaceAll(REMINDER_CLOSE, "<\\/system-reminder>");
+}
+
+/** 按原 order 拼接降级 section 文本，渲染一条 reminder 消息文本。 */
+export function renderReminder(sectionTexts: readonly string[]): string {
+  const body = sectionTexts.map(escapeFrameBody).join("\n\n");
+  return `${REMINDER_OPEN}\n${REMINDER_INTRO}\n\n${body}\n${REMINDER_CLOSE}`;
+}
+
+/** 该 user 消息是否由本插件注入。 */
+export function isPromptReminder(message: UserMessage): boolean {
+  return message.source.kind === "prompt-reminder";
+}
+
+/** 会话 surface 上最近一条 reminder 的文本；跨进程重启后据此恢复幂等。 */
+export function latestReminderText(agent: Agent): string | undefined {
+  for (const seq of agent.session.surface.nodes.toReversed()) {
+    const event = agent.session.eventAt(seq);
+    if (event?.type !== "user/message" || !isPromptReminder(event.data)) continue;
+    const [block] = event.data.content;
+    return event.data.content.length === 1 && block?.type === "text" ? block.text : "";
+  }
+  return undefined;
+}
+
+/** 构造一条 reminder user 消息。 */
+export function reminderMessage(text: string): UserMessage {
+  return createUserMessage({
+    content: [{ type: "text", text }],
+    source: { kind: "prompt-reminder", form: "instructions" },
+  });
+}