@deepmaid/maid-anchor 0.0.0-stage → 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kenyonxu
+
+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/cordis.patch.yml

@@ -0,0 +1,3 @@
+# 空 patch 层:本包挂载在 preset 声明树(Q3 拍板,2026-10-28 规格 §2);bundle 层仅承载包身份与面板元数据,toggle 对本包为无操作。
+# 空层以顶层 `[]` 承载(修复轮 2 勘正):comment-only 会 parse 为 null,dsh-app-boot parsePatchList 即 throw,整包进 skippedBundles。
+[]

package/lib/index.d.ts

@@ -0,0 +1,113 @@
+//#region src/index.d.ts
+declare module '@deepseek-ai/dsh-llm' {
+  interface MessageSourceMap {
+    'plugin:maid-anchor': {
+      kind: 'plugin:maid-anchor';
+    };
+  }
+}
+/**
+ * maid-anchor(M2b T7):表达锚种子插件。种子文件(`seeds/<mode>.md`,M2b 只用 default 册)
+ * 以仅含 `%%%` 的行分 N 块(N≥2),每块首行 `[user]`/`[assistant]` 角色头:首块必须 user,
+ * 角色其后严格交替;system 身份不进种子(由 preset SOUL 承担)。
+ *
+ * 事件面:dsh 0.1.2-rc.1 起 `Session.get events()` 已删,经 `snapshotEvents()` 读全量日志
+ * (升级第 1 批落地;rc.1 前的双读过渡见升级策略第 0 批执行记录)。
+ *
+ * 注入形态(2026-09-05 第三次勘误,**关键**):整份种子以**一条** `user/message` durable
+ * 事件注入,块文按「主人:…/你:…」引述体拼排。不可用 assistant/message 事件承载种子块——
+ * web 客户端 ConversationNodeAssembler 把 assistant/message 按 `data.turn:data.step` 归入
+ * trajectory-assistant-step 上下文当 update、start 是同 turn:step 的 step/start:任何
+ * 非 agent-loop 产出的 assistant/message(带 turn/step 早于 step/start 会让装配器抛错、
+ * 事件流订阅整体崩掉;不带则对话页静默空白)都与 web 对话视图不兼容(实机踩坑两晚);
+ * 而注入时机只能早于 step/start(种子必须赶在首个 LLM 请求组装前进日志),「落在
+ * step/start 之后」的通道对 preset 层插件不存在(session/event firehose 被 scope 过滤,
+ * 2026-09-05 产线实证)。user/message 事件无步骤上下文约束、任意位置合法——maid-memory
+ * 召回块 / maid-emotion 投影同款路径,restore 形状校验(role 必须 'user')天然满足。
+ *
+ * 注入通道(2026-09-13 第四次勘误,**dsh 0.1.5/V3 强制**):种子不再 `session.append` 直写,
+ * 改经 pre-step **决议消息**承载(居 `decision.messages` 队首)。根因:V3 把系统提示词纳入
+ * 消息历史,`system/message` 是受保护首 surface 头,任何消息抢在头前直落都会让会话
+ * 「能写不能恢复」(fromRestore 抛 "system/message requires a protected first surface head";
+ * emotion 车道 fixture 实录,宿主 Doris 会话同形态必炸);而 rc.2 的 agent/pre-step 发射点在
+ * step/start 落盘**之前**,直写必然抢头。决议消息由 agent-loop 在 step 开启时持久化于头之后
+ * (maid-memory 召回块同款通道,日志实证),durable/user 角色/引述体/幂等扫描语义全部不变,
+ * 且仍赶在首个 LLM 请求组装前进入消息历史。勘误 3 否决的「step/start 之后」指 firehose 观测
+ * 通道,决议通道不依赖观测,不受该结论约束。
+ *
+ * 幂等:per-session Set 快路径 + 会话日志扫描兜底(append-only 日志里的 anchor 事件
+ * 不因 compaction 抹除,重启后扫描仍可辨)。会话若跳过了首个 step/start(重启续聊的
+ * 旧会话),不补注入——种子是「会话开场」,进行中的对话不做追溯锚定。
+ *
+ * 种子文件缺失/格式坏 → warn 一次跳过,会话照常(fail-open)。
+ */
+declare const name = "maid-anchor";
+type SeedRole = 'user' | 'assistant';
+interface SeedMessage {
+  role: SeedRole;
+  text: string;
+}
+type SeedBadReason = 'no-separator' | 'first-not-user' | 'role-break' | 'empty-block' | 'block-tag';
+type SeedParseResult = {
+  ok: true;
+  messages: SeedMessage[];
+} | {
+  ok: false;
+  reason: SeedBadReason;
+};
+/**
+ * 解析种子文件内容:块由「仅含 %%% 的行」分隔(空白容忍,\r\n 兼容);每块首行角色头
+ * `[user]`/`[assistant]`,其余为块文(块缘空白剥除、内部保留)。校验:N≥2(即至少一个分隔)、
+ * 首块 user、角色严格交替、无空块、块必须带角色头。
+ */
+declare function parseSeedFile(content: string): SeedParseResult;
+/** pre-step 决议只穿透不改动;方法声明保持 bivariance,真 cordis Context 结构兼容 */
+interface AnchorLifecycleContext {
+  on(event: 'agent/pre-step', listener: (payload: AnchorPreStepPayload, next: () => Promise<AnchorPreStepDecision>) => Promise<AnchorPreStepDecision>): () => void;
+  logger?(name: string): {
+    info(message: string): void;
+    warn(message: string): void;
+  };
+  /** preset 组合挂载时由 Include 设为组合目录(cordis-plugin-include 先例);宿主裸挂载时可缺省 */
+  readonly baseUrl?: string | undefined;
+}
+/** pre-step 决议鸭子面(agent-loop PreStepDecision 的最小消费面;enter 之外形态原样穿透) */
+interface AnchorPreStepDecision {
+  kind?: string;
+  messages?: unknown[];
+}
+interface AnchorPreStepPayload {
+  agent: {
+    id: string;
+    /** 真运行时是活 Session(ReactLoopAgent.session):events 是 append-only 全量日志 */
+    session?: {
+      snapshotEvents?: () => readonly unknown[];
+    };
+  };
+  turn: number;
+  step: number;
+  messages: unknown[];
+  signal: AbortSignal;
+}
+interface MaidAnchorConfig {
+  /** mode → 种子文件路径(相对 preset 目录/ctx.baseUrl;绝对路径直达;无 baseUrl 时相对 cwd)。M2b 只消费 default 册 */
+  seeds?: Record<string, string>;
+  /**
+   * 来源排除(T11,控制器裁定):命中来源的会话跳过种子注入。判定照 maid-emotion sessionSource
+   * 同款——`cron_` sessionId 前缀(maid-cron engine `cron_${jobId}_${iso}`)。**默认 [] = 现状不排除**;
+   * 与 maid-emotion excludeSources(默认 ['cron'])不同:anchor 是 preset 层可选件,排除是显式选择
+   * 而非缺省政策。命中即跳过注入——幂等标记不写(排除是配置态决定,每轮重判;换配置即刻生效),
+   * warn 一次/会话(anchor 侧非例行静默:配置显式排除了本 preset 挂载的车道,值得留痕)。
+   */
+  excludeSources?: string[];
+}
+/**
+ * 会话来源(供 excludeSources 判定)。dsh SessionHeader 无 source/lane 字段;cron 车道唯一
+ * 稳定标识是 maid-cron 的 `cron_` sessionId 前缀(engine.ts `cron_${jobId}_${iso}`)。
+ */
+declare function sessionSource(sessionId: string): string | undefined;
+/** 交替块按角色标签拼排:user 块 → 「主人:」,assistant 块 → 「你:」(女仆自称视角,不依赖 maid 名)。 */
+declare function renderSeedText(messages: readonly SeedMessage[]): string;
+declare const apply: (ctx: any, config: MaidAnchorConfig) => (() => void);
+//#endregion
+export { AnchorLifecycleContext, AnchorPreStepDecision, AnchorPreStepPayload, MaidAnchorConfig, SeedBadReason, SeedMessage, SeedParseResult, SeedRole, apply, name, parseSeedFile, renderSeedText, sessionSource };

package/lib/index.js

@@ -0,0 +1,204 @@
+import { readFileSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
+//#region src/index.ts
+/**
+* maid-anchor(M2b T7):表达锚种子插件。种子文件(`seeds/<mode>.md`,M2b 只用 default 册)
+* 以仅含 `%%%` 的行分 N 块(N≥2),每块首行 `[user]`/`[assistant]` 角色头:首块必须 user,
+* 角色其后严格交替;system 身份不进种子(由 preset SOUL 承担)。
+*
+* 事件面:dsh 0.1.2-rc.1 起 `Session.get events()` 已删,经 `snapshotEvents()` 读全量日志
+* (升级第 1 批落地;rc.1 前的双读过渡见升级策略第 0 批执行记录)。
+*
+* 注入形态(2026-09-05 第三次勘误,**关键**):整份种子以**一条** `user/message` durable
+* 事件注入,块文按「主人:…/你:…」引述体拼排。不可用 assistant/message 事件承载种子块——
+* web 客户端 ConversationNodeAssembler 把 assistant/message 按 `data.turn:data.step` 归入
+* trajectory-assistant-step 上下文当 update、start 是同 turn:step 的 step/start:任何
+* 非 agent-loop 产出的 assistant/message(带 turn/step 早于 step/start 会让装配器抛错、
+* 事件流订阅整体崩掉;不带则对话页静默空白)都与 web 对话视图不兼容(实机踩坑两晚);
+* 而注入时机只能早于 step/start(种子必须赶在首个 LLM 请求组装前进日志),「落在
+* step/start 之后」的通道对 preset 层插件不存在(session/event firehose 被 scope 过滤,
+* 2026-09-05 产线实证)。user/message 事件无步骤上下文约束、任意位置合法——maid-memory
+* 召回块 / maid-emotion 投影同款路径,restore 形状校验(role 必须 'user')天然满足。
+*
+* 注入通道(2026-09-13 第四次勘误,**dsh 0.1.5/V3 强制**):种子不再 `session.append` 直写,
+* 改经 pre-step **决议消息**承载(居 `decision.messages` 队首)。根因:V3 把系统提示词纳入
+* 消息历史,`system/message` 是受保护首 surface 头,任何消息抢在头前直落都会让会话
+* 「能写不能恢复」(fromRestore 抛 "system/message requires a protected first surface head";
+* emotion 车道 fixture 实录,宿主 Doris 会话同形态必炸);而 rc.2 的 agent/pre-step 发射点在
+* step/start 落盘**之前**,直写必然抢头。决议消息由 agent-loop 在 step 开启时持久化于头之后
+* (maid-memory 召回块同款通道,日志实证),durable/user 角色/引述体/幂等扫描语义全部不变,
+* 且仍赶在首个 LLM 请求组装前进入消息历史。勘误 3 否决的「step/start 之后」指 firehose 观测
+* 通道,决议通道不依赖观测,不受该结论约束。
+*
+* 幂等:per-session Set 快路径 + 会话日志扫描兜底(append-only 日志里的 anchor 事件
+* 不因 compaction 抹除,重启后扫描仍可辨)。会话若跳过了首个 step/start(重启续聊的
+* 旧会话),不补注入——种子是「会话开场」,进行中的对话不做追溯锚定。
+*
+* 种子文件缺失/格式坏 → warn 一次跳过,会话照常(fail-open)。
+*/
+const name = "maid-anchor";
+const ANCHOR_PLUGIN = "maid-anchor";
+const SEPARATOR_LINE = "%%%";
+const TAG_LINE = /^\s*\[(user|assistant)\]\s*$/;
+/**
+* 解析种子文件内容:块由「仅含 %%% 的行」分隔(空白容忍,\r\n 兼容);每块首行角色头
+* `[user]`/`[assistant]`,其余为块文(块缘空白剥除、内部保留)。校验:N≥2(即至少一个分隔)、
+* 首块 user、角色严格交替、无空块、块必须带角色头。
+*/
+function parseSeedFile(content) {
+	const blocks = [[]];
+	let separators = 0;
+	for (const line of content.split(/\r?\n/)) if (line.trim() === SEPARATOR_LINE) {
+		separators += 1;
+		blocks.push([]);
+	} else blocks[blocks.length - 1].push(line);
+	if (separators === 0) return {
+		ok: false,
+		reason: "no-separator"
+	};
+	const messages = [];
+	for (const block of blocks) {
+		const trimmed = block.join("\n").trim();
+		if (trimmed === "") return {
+			ok: false,
+			reason: "empty-block"
+		};
+		const [tagLine, ...rest] = trimmed.split("\n");
+		const tag = TAG_LINE.exec(tagLine ?? "");
+		if (tag === null) return {
+			ok: false,
+			reason: "block-tag"
+		};
+		const text = rest.join("\n").trim();
+		if (text === "") return {
+			ok: false,
+			reason: "empty-block"
+		};
+		messages.push({
+			role: tag[1],
+			text
+		});
+	}
+	if (messages[0].role !== "user") return {
+		ok: false,
+		reason: "first-not-user"
+	};
+	for (let i = 1; i < messages.length; i++) if (messages[i].role === messages[i - 1].role) return {
+		ok: false,
+		reason: "role-break"
+	};
+	return {
+		ok: true,
+		messages
+	};
+}
+/**
+* 会话来源(供 excludeSources 判定)。dsh SessionHeader 无 source/lane 字段;cron 车道唯一
+* 稳定标识是 maid-cron 的 `cron_` sessionId 前缀(engine.ts `cron_${jobId}_${iso}`)。
+*/
+function sessionSource(sessionId) {
+	return sessionId.startsWith("cron_") ? "cron" : void 0;
+}
+function logHasAnchorEvent(events) {
+	for (const entry of events ?? []) {
+		const event = entry;
+		if (event?.type === "user/message") {
+			const src = event.data?.source;
+			if (src?.plugin === ANCHOR_PLUGIN || src?.kind === `plugin:${ANCHOR_PLUGIN}`) return true;
+		} else if (event?.type === "assistant/message") {
+			if ((event.data?.message)?.source?.provider === ANCHOR_PLUGIN) return true;
+		}
+	}
+	return false;
+}
+const SEED_PROLOGUE = "(以下是你的对话基调示例,供语感参考,不是当前对话)";
+/** 交替块按角色标签拼排:user 块 → 「主人:」,assistant 块 → 「你:」(女仆自称视角,不依赖 maid 名)。 */
+function renderSeedText(messages) {
+	const lines = [SEED_PROLOGUE];
+	for (const seed of messages) lines.push(seed.role === "user" ? `主人:${seed.text}` : `你:${seed.text}`);
+	return lines.join("\n");
+}
+function resolveSeedPath(baseUrl, seedPath) {
+	if (isAbsolute(seedPath)) return seedPath;
+	if (typeof baseUrl === "string" && baseUrl.startsWith("file:")) try {
+		return fileURLToPath(new URL(seedPath, baseUrl));
+	} catch {}
+	return resolve(process.cwd(), seedPath);
+}
+const apply = (ctx, config) => {
+	const logger = ctx.logger?.(ANCHOR_PLUGIN) ?? console;
+	const baseUrl = typeof ctx?.baseUrl === "string" ? ctx.baseUrl : void 0;
+	const seedsConfig = config?.seeds;
+	const defaultSeed = seedsConfig !== null && typeof seedsConfig === "object" ? seedsConfig.default : void 0;
+	const excludeSources = Array.isArray(config?.excludeSources) ? config.excludeSources : [];
+	const warned = /* @__PURE__ */ new Set();
+	const warnOnce = (key, message) => {
+		if (warned.has(key)) return;
+		warned.add(key);
+		logger.warn(message);
+	};
+	let cached;
+	const loadSeeds = () => {
+		if (cached !== void 0) return cached;
+		if (typeof defaultSeed !== "string" || defaultSeed === "") {
+			warnOnce("no-default", "maid-anchor: config.seeds.default 未配置,跳过种子注入");
+			return;
+		}
+		const seedPath = resolveSeedPath(baseUrl, defaultSeed);
+		let content;
+		try {
+			content = readFileSync(seedPath, "utf8");
+		} catch (error) {
+			warnOnce(`missing:${seedPath}`, `maid-anchor: 种子文件缺失 '${seedPath}'(${error.message}),跳过注入`);
+			return;
+		}
+		const parsed = parseSeedFile(content);
+		if (!parsed.ok) {
+			warnOnce(`bad:${seedPath}:${parsed.reason}`, `maid-anchor: 种子文件格式坏 '${seedPath}'(${parsed.reason}),跳过注入`);
+			return;
+		}
+		cached = { messages: parsed.messages };
+		return cached;
+	};
+	const handled = /* @__PURE__ */ new Set();
+	const disposePreStep = ctx.on("agent/pre-step", async (payload, next) => {
+		const sessionId = payload.agent?.id;
+		if (typeof sessionId !== "string" || sessionId === "") return next();
+		const source = sessionSource(sessionId);
+		if (source !== void 0 && excludeSources.includes(source)) {
+			warnOnce(`excluded:${sessionId}`, `maid-anchor: 会话来源 '${source}' 命中 excludeSources,跳过种子注入(${sessionId})`);
+			return next();
+		}
+		if (handled.has(sessionId) || logHasAnchorEvent(payload.agent.session?.snapshotEvents?.())) {
+			handled.add(sessionId);
+			return next();
+		}
+		const seeds = loadSeeds();
+		if (seeds === void 0) {
+			handled.add(sessionId);
+			return next();
+		}
+		const seedMessage = createUserMessage({
+			content: [{
+				type: "text",
+				text: renderSeedText(seeds.messages)
+			}],
+			source: { kind: `plugin:${ANCHOR_PLUGIN}` }
+		});
+		const decision = await next();
+		if (decision?.kind !== "enter" || !Array.isArray(decision.messages)) return decision;
+		handled.add(sessionId);
+		return {
+			...decision,
+			messages: [seedMessage, ...decision.messages]
+		};
+	});
+	return () => {
+		handled.clear();
+		disposePreStep();
+	};
+};
+//#endregion
+export { apply, name, parseSeedFile, renderSeedText, sessionSource };

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@deepmaid/maid-anchor",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-alpha.1",
+  "license": "MIT",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml"
+  ],
+  "dsh": {
+    "engines": {
+      "dsh": ">=0.2.1-rc.2 <0.3"
+    },
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "meta": {
+      "title": "Maid Anchor",
+      "description": "表达锚种子 seam:preset 层挂载的开场气质种子(单条 user 引述体注入)。关闭=表达锚不注入,女仆开场失锚,首因气质漂移。"
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/dsh-llm": "0.2.1-rc.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.5",
+    "@deepseek-ai/dsh-session": "0.2.1-rc.2",
+    "tsdown": "0.22.14",
+    "typescript": "6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.