@deepmaid/maid-voice 0.0.0-stage → 0.1.0-alpha.0

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 @@
+- insert:
+    - id: deepmaid-maid-voice
+      name: '@deepmaid/maid-voice'

package/lib/index.d.ts

@@ -0,0 +1,350 @@
+//#region src/pack.d.ts
+/**
+ * maid-voice pack.yml schema 解析(M3c Task 4,规格 §2.1-2.2):输入是 maid-identity
+ * `resolvePack` 的 raw mapping(读取层零 schema,校验归本层),产出规范化 VoicePack。
+ * 校验器风格照 maid-emotion config.ts——局部 isMapping/isNumber/isStringArray 助手、
+ * 坏条 warn 跳过其余照常、可选节坏 → warn 后整节弃(其余照常)、未知顶层键 warn 不静默。
+ *
+ * 严格度(brief 拍板):id/kind 必填(坏 → undefined + warn,整包不用);cases 逐条校验
+ * (id 非空、domain 四值枚举、when 各值区间二数值且 min<max、gate 四值枚举、lines 非空
+ * 字符串组),坏条 warn 跳过;重复 case id 后者 warn 跳过;schedule 坏 → warn 后整节弃;
+ * temperamentRaw 原样透传(形状校验归 maid-emotion parseTemperamentBase,Task 2 已落)。
+ *
+ * when 区间双形态(内部表示统一 WhenRange):
+ * - 字符串字面量 "[0, 20)"(半开)/ "[0, 100]"(闭)——yml 里须带引号:不带引号的 `[0, 20)`
+ *   是 yaml 层解析错误,在 resolvePackFile 即 warn 整包弃;
+ * - 原生数组 [0, 20](两数值)——无括号可辨,视为闭区间(maxInclusive: true)。
+ * min 恒含(yml 不设 "(a, b]" 形态);含/排除语义的数值断言由 Task 6 检索测试锁。
+ */
+/** 案例域(规格 §3.1):daily 日常 | wilted 蔫了 | reunion 重逢 | intimate 亲密(M4d 预留) */
+type CaseDomain = 'daily' | 'wilted' | 'reunion' | 'intimate';
+/** 四门象限(规格 §3.2,desire×inhibition):open | cautious | ajar(留门)| reserved */
+type Gate = 'open' | 'cautious' | 'ajar' | 'reserved';
+/** when 区间内部表示:min 恒含;maxInclusive 承载半开 [min,max) / 闭 [min,max] 语义(Task 6 检索消费) */
+interface WhenRange {
+  min: number;
+  max: number;
+  maxInclusive: boolean;
+}
+/** 单条情景案例:domain × when 向量区间(缺省 = 全域空映射)× gate(可选)× 台词池 */
+interface PackCase {
+  id: string;
+  domain: CaseDomain;
+  when: Record<string, WhenRange>;
+  gate?: Gate;
+  lines: string[];
+}
+/** 作息表夜间段(M4b 全日化复用同文件:pack schedule 节下还有 day 等节位,本层只认 night) */
+interface PackSchedule {
+  sleep: string;
+  wake: string;
+  activities: string[];
+}
+/** 规范化性格包:persona(气质 + 作息 + 案例)/ flavor(仅案例,world 风味层) */
+interface VoicePack {
+  id: string;
+  kind: 'persona' | 'flavor';
+  name?: string;
+  temperamentRaw?: unknown;
+  schedule?: PackSchedule;
+  cases: PackCase[];
+}
+type Warn$1 = (message: string) => void;
+/** schedule 节解析(包内跨文件共用,library.ts overlay 同款原料):只认 night 子节
+ *  (M4b 全日化的其余节位本层不枚举不 warn);坏 → 整节弃(其余照常)。 */
+declare function parseSchedule(node: unknown, where: string, warn: Warn$1): PackSchedule | undefined;
+/** cases 列表节解析(包内跨文件共用,library.ts overlay 同款原料):缺省空列表(零 warn)、
+ *  非列表 warn 后空、坏条 warn 跳过其余照常、重复 case id 后者 warn 跳过。 */
+declare function parseCases(node: unknown, where: string, warn: Warn$1): PackCase[];
+/**
+ * pack.yml 规范化入口:raw 为 resolvePack 的 yaml parse 产物(缺省 undefined = 包不存在,
+ * 合法形态零 warn)。id/kind 必填坏 → 整包 undefined;其余按「坏条跳过/坏节弃」容错。
+ */
+declare function parseVoicePack(raw: Record<string, unknown> | undefined, where: string, warn: Warn$1): VoicePack | undefined;
+//#endregion
+//#region src/library.d.ts
+/** 三层合并后的女仆案例库(检索层 Task 6 消费;schedule 缺省 undefined = 无作息可注) */
+interface VoiceLibrary {
+  cases: PackCase[];
+  schedule: PackSchedule | undefined;
+}
+type Warn = (message: string) => void;
+/** overlay 解析产物:与 pack 同款原料,仅 cases/schedule 两节有效 */
+interface OverlayContent {
+  cases: PackCase[];
+  schedule?: PackSchedule;
+}
+/**
+ * voice-overlay.yml 解析入口(与 pack 不同:id/kind 缺省容错,仅 cases/schedule 有效)。
+ * raw 为调用方装载的 yaml parse 产物;缺省 undefined(文件不存在是合法形态,零 warn)。
+ * cases 规则与 parseVoicePack 完全同款(坏条跳过、重复 id 后者跳过)。
+ */
+declare function parseOverlay(raw: Record<string, unknown> | undefined, where: string, warn: Warn): OverlayContent | undefined;
+/**
+ * 三层继承解析(规格 §2.3):persona 模板(voice.pack)← flavor 风味(voice.worldFlavor)
+ * ← per-maid overlay(voice-overlay.yml 解析产物)。同 case id 整条覆盖、新 id 追加;
+ * 层缺失/解析失败跳过不阻断。无任何层 → 空库(fail-open,后续注入静默)。
+ */
+declare function resolveVoiceLibrary(input: {
+  resolvePack: ((packId: string) => Record<string, unknown> | undefined) | undefined;
+  voice: {
+    pack?: string;
+    worldFlavor?: string;
+  } | undefined;
+  overlayRaw: Record<string, unknown> | undefined;
+  scheduleRaw: Record<string, unknown> | undefined;
+  warn: (m: string) => void;
+}): VoiceLibrary;
+//#endregion
+//#region src/retrieval.d.ts
+/** 四门象限(desire×inhibition,中点默认 50 由调用方传):open 高desire低inhibition /
+ *  cautious 双低 / ajar 双高 / reserved 低desire高inhibition;恰在中点归高;任一维缺失 → undefined。 */
+declare function gateOf(vector: Record<string, number>, midpoint: number): Gate | undefined;
+/** 情景推导(规格 §3.1 规则化,参数由调用方传):wilted = energy < wiltedThreshold(严格
+ *  小于,energy=20 阈值 20 不蔫);energy 缺失/不蔫均归缺省域 daily。reunion 优先规则与
+ *  intimate(M4d 预留)不进本函数,由调用方推导后直接喂 selectCases。 */
+declare function domainOf(vector: Record<string, number>, opts: {
+  wiltedThreshold: number;
+}): Exclude<CaseDomain, 'reunion' | 'intimate'>;
+/**
+ * 选片确定序(规格 §3.2):domain 匹配 → when 区间覆盖当前向量(缺省空 when 全域)→
+ * gate 匹配优先 → id 字典序 tie-break(码位序,跨环境确定);取 caseGroupMax 条。
+ * 空域返回 [](不注入不报错);输入数组不改序(filter 副本上排序,library.cases 复用安全)。
+ */
+declare function selectCases(cases: readonly PackCase[], domain: CaseDomain, vector: Record<string, number>, gate: Gate | undefined, caseGroupMax: number): PackCase[];
+/**
+ * 每轮轻校验(纯函数,零模型):active 缺失 → false(首轮必选);domain 变 → false;
+ * caseIds 里每条仍存在(层重载消失即 false)且其 when 区间仍覆盖当前向量 → true。
+ * gate 迁移不触发跃迁(拍板):gate 不参与校验、仅影响下次重选——防中点附近抖动换组;
+ * 尾参 `_gate` 只为调用车道对称,void 引用照 maid-delivery 先例(eslint 不认 `_` 前缀尾参)。
+ */
+declare function groupStillMatches(active: {
+  domain: CaseDomain;
+  caseIds: string[];
+} | undefined, cases: readonly PackCase[], domain: CaseDomain, vector: Record<string, number>, _gate: Gate | undefined): boolean;
+//#endregion
+//#region src/state.d.ts
+/** 跨轮 voice 状态(per-maid,文件摆放归 lifecycle):active = 当前生效案例组,缺 = 首轮前 */
+interface VoiceState {
+  active?: {
+    domain: CaseDomain;
+    caseIds: string[];
+    since: number;
+  } | undefined;
+  overnightConsumedDate?: string | undefined;
+}
+declare function loadVoiceState(file: string): VoiceState;
+declare function saveVoiceState(file: string, state: VoiceState): void;
+declare function dateKeyIn(ms: number, timezone: string): string;
+//#endregion
+//#region src/decide.d.ts
+/** 单轮跃迁决策:none = 状态未变零注入;inject = 跃迁重选(caseIds 可空 = 空域,记 active 不注入) */
+interface TurnDecision {
+  action: 'none' | 'inject';
+  caseIds: string[];
+  domain: CaseDomain;
+}
+declare function decideTurn(input: {
+  state: VoiceState;
+  cases: readonly PackCase[];
+  domain: CaseDomain;
+  vector: Record<string, number>;
+  gate: Gate | undefined;
+  caseGroupMax: number;
+  now: number;
+}): TurnDecision;
+//#endregion
+//#region src/overnight.d.ts
+/**
+ * maid-voice overnight 产物读取解析(M3c Task 9,规格 §4.1 轻约定 / §4.3 失败语义):
+ * 产物 = maid-cron 黎明 job persistTo 按日落档(Task 12 落地写入端)overnight-<YYYY-MM-DD>.txt,
+ * 本文件只做读取端。parseOvernight 切分首行(晨报一句)与正文(完整陈述);readOvernight
+ * 今日档直读(reused=false),miss 时 onFailure=reuse 取目录内字典序最新档(生成日期距今
+ * ≤ staleWindowMs 才用,标 reused=true),empty 或超窗 → undefined。坏文件(空/读失败)
+ * 跳过取次新(目录冒名档 readFileSync 抛 EISDIR 同此路)。本文件只 fs,零日志——warn 归
+ * 调用方 lifecycle/getMorningSentence 持有(照 loadVoiceState 静默纪律)。
+ *
+ * 档龄口径(brief 接口无时区参,据此定死):档名日期按 UTC 零点锚与 nowMs 求差——
+ * 与宿主时区日界的偏差以时区偏移为上界(上海 8h),相对 36h 默认窗只影响边缘时刻的
+ * 昨日档可用性;写入端(maid-cron {{date}})与读取端同宿主时区,日期语义自洽。
+ */
+/**
+ * 产物解析(规格 §4.1 轻约定):首行 = 晨报一句,其后正文 = 完整陈述(首尾与分隔空白
+ * 容差——空行是书写惯例非硬约束);首行后无正文 → sentence = full = 首行;空/纯空白 →
+ * undefined。乱码不在判定面:非空即有首行,轻约定无 schema 可校。
+ */
+declare function parseOvernight(text: string): {
+  sentence: string;
+  full: string;
+} | undefined;
+/**
+ * 读取 + reuse(规格 §4.3):今日档(overnight-<todayKey>.txt)直读,存在且可用 →
+ * reused=false;今日档坏(空/读失败)视同 miss。miss 且 onFailure=reuse → 目录扫描合法
+ * 档名字典序最新(档名日期 ISO 定宽,字典序即时间序),坏文件跳过取次新,首个可用档
+ * 生成日期距今 ≤ staleWindowMs 才用(reused=true);超窗 → undefined(更旧只会更陈,
+ * 不再回退)。onFailure=empty → miss 即 undefined。目录缺失/不可读 = 无档可复用。
+ */
+declare function readOvernight(dir: string, todayKey: string, nowMs: number, opts: {
+  onFailure: 'reuse' | 'empty';
+  staleWindowMs: number;
+}): {
+  sentence: string;
+  full: string;
+  reused: boolean;
+} | undefined;
+//#endregion
+//#region src/lifecycle.d.ts
+/**
+ * maid-voice 生命周期(M3c Task 8,规格 §3):agent/pre-step 案例组注入——跃迁才注、
+ * 不变不注(decide 决策),引述体单条 user 角色 durable 事件(缓存纪律铁律 3),预算降级
+ * 3→1→0。钩子形态照 maid-emotion lifecycle:运行时字符串派发(duck-typing),免 inject
+ * 经 deps 探针直读 maidEmotion/maidIdentity 服务(index.ts 接 reflect,maid-gestures 先例)。
+ *
+ * 情绪投影序由装配序保证(maid-emotion 先挂先注、maid-voice 后挂后注——两条独立 durable
+ * 事件,本包测试单挂即可;跨包序断言归 Task 13 快照车道)。Task 11 在同一 handler 加
+ * overnight 分支(先于案例组注入,规格 §4.4 通道②:今日叙事未消费 → 完整陈述事件 +
+ * overnightConsumedDate 消费标记,同日后续会话不再注;cron 车道守卫链上游豁免,天然不注)。
+ *
+ * Task 10 服务面:buildNightContext / getMorningSentence 按 maidId 直查(规格 §4.2/§4.4),
+ * 供 maid-cron 黎明 job 与晨报渲染消费。cron 黎明 job 是合法调用方,不经 excludeSources——
+ * 该守卫只挡会话注入(pre-step),服务面与来源豁免无关(dispatch 补充语义)。
+ */
+declare module '@deepseek-ai/dsh-llm' {
+  interface MessageSourceMap {
+    'plugin:maid-voice': {
+      kind: 'plugin:maid-voice';
+    };
+  }
+}
+interface MaidVoiceConfig {
+  /** 必填;voice-state 平铺文件(<stateDir>/<maidId>.json)+ overnight 档 per-maid 子目录
+   *  (<stateDir>/<maidId>/overnight-<date>.txt,fix round 1 多女仆隔离)所在根目录 */
+  stateDir: string;
+  /** 必填(同 maid-emotion 值;读 voice-overlay.yml / schedule.yml,首中即用) */
+  presetRoots: string[];
+  /** 同 maid-emotion 语义;缺省全放行 */
+  allowMaids?: string[];
+  /** 默认 ['cron'](晨报会话与离线叙事生成会话均不注案例,规格 §3.3) */
+  excludeSources?: string[];
+  /** 案例组上限,默认 3 */
+  caseGroupMax?: number;
+  /** 注入预算(tokens 估算),默认 150 */
+  voiceBudgetTokens?: number;
+  /** wilted 域阈值:energy 严格小于即蔫,默认 20 */
+  wiltedThreshold?: number;
+  /** 四门象限中点(≥ 归高),默认 50 */
+  gateMidpoint?: number;
+  /** overnight 失败语义(reuse/empty + 复用窗,默认 reuse/36h):服务面(Task 10)与首会话注入(Task 11)同源消费 */
+  overnight?: {
+    onFailure?: 'reuse' | 'empty';
+    staleWindowMs?: number;
+  };
+  /** 默认 false;开则每轮 logger 一行诊断(gate 四门标签等可读性坐标) */
+  debug?: boolean;
+  /** 默认 Asia/Shanghai(overnight 日界与 Task 10 晨况消费) */
+  timezone?: string;
+  /** 时钟注入(测试用);缺省 Date.now() */
+  now?: () => number;
+}
+/**
+ * maid-voice 服务面(maid-cron 消费,reflect 可选依赖;service 对象在 attachVoiceLifecycle
+ * 闭包内组装。Task 11 再扩展 overnight 会话注入消费)。两方法按 maidId 直查、fail-open:
+ * maid 未注册 / 无包配置 / 依赖服务缺 → ''(cron 黎明 job 是合法调用方,不经 excludeSources)。
+ */
+interface MaidVoiceService {
+  /** 黎明 job promptTemplate 的 {{nightContext}} 原料(规格 §4.2,五段中文短句 '\n' 拼接) */
+  buildNightContext(maidId: string): string;
+  /** 晨报 {{overnightSentence}}:今日/复用档首行;无 → ''(fail-open,晨报照发) */
+  getMorningSentence(maidId: string): string;
+}
+/** maid-emotion getSnapshot 消费面(M3c Task 3 EmotionSnapshot;本层只吃 vector + reunionTier) */
+interface MaidEmotionLike {
+  getSnapshot(maidId: string): EmotionSnapshotLike | undefined;
+}
+/** 情绪只读快照鸭子(Task 3 全字段面;reunionTier 三档或 null=初见/无档) */
+interface EmotionSnapshotLike {
+  vector: Record<string, number>;
+  trends?: Record<string, 'rising' | 'stable' | 'falling'> | undefined;
+  reunionTier: 'soft' | 'distant' | 'estranged' | null;
+  sinceLastMessageMs: number;
+  lastMasterMessage?: {
+    at: number;
+    excerpt: string;
+  } | undefined;
+  lastWeather?: {
+    at: number;
+    text: string;
+  } | undefined;
+  calendarSentences: string[];
+  timeText: string;
+}
+/** maid-identity 服务面(M3c Task 1:voice 节 + pack 解析;四方法均可选,形状校验归本层) */
+interface MaidIdentityLike {
+  maidForPreset?(presetId: string | undefined): {
+    maidId: string;
+  } | undefined;
+  /** Task 10 服务面消费:maidId 直查记录(preset 供 library 文件层定位);缺则按无文件层降级 */
+  get?(maidId: string): {
+    maidId: string;
+    preset: string;
+  } | undefined;
+  getVoice?(maidId: string): {
+    pack?: string;
+    worldFlavor?: string;
+  } | undefined;
+  resolvePack?(packId: string): Record<string, unknown> | undefined;
+}
+interface PreStepPayload {
+  agent: {
+    id: string;
+    session: {
+      header: {
+        agentPreset?: string;
+      };
+      snapshotEvents?: () => readonly unknown[];
+    };
+  };
+  messages: Array<{
+    content?: Array<{
+      type: string;
+      text?: string;
+    }>;
+    source?: {
+      kind?: string;
+      plugin?: string;
+    };
+  }>;
+  turn: number;
+  step: number;
+  signal: AbortSignal;
+}
+type PreStepDecision = {
+  kind: 'reject';
+} | {
+  kind: 'enter';
+  messages: unknown[];
+};
+interface VoiceLifecycleContext {
+  on(event: 'agent/pre-step', listener: (payload: PreStepPayload, next: () => Promise<PreStepDecision>) => Promise<PreStepDecision>): () => void;
+}
+interface VoiceLifecycleDeps {
+  config: MaidVoiceConfig;
+  logger: {
+    info(message: string): void;
+    warn(message: string): void;
+  };
+  now(): number;
+  /** reflect 直读探针(index.ts 接线;per-call 取,晚挂载也能接上;形状校验与 one-shot warn 归本层) */
+  emotionOf(): MaidEmotionLike | undefined;
+  identityOf(): MaidIdentityLike | undefined;
+}
+declare function attachVoiceLifecycle(ctx: VoiceLifecycleContext, deps: VoiceLifecycleDeps): {
+  service: MaidVoiceService;
+  dispose(): void;
+};
+//#endregion
+//#region src/index.d.ts
+declare const name = "maid-voice";
+declare const apply: (ctx: any, config: MaidVoiceConfig) => (() => Promise<void>);
+//#endregion
+export { CaseDomain, type EmotionSnapshotLike, Gate, type MaidEmotionLike, type MaidIdentityLike, type MaidVoiceConfig, type MaidVoiceService, OverlayContent, PackCase, PackSchedule, type PreStepDecision, type PreStepPayload, TurnDecision, VoiceLibrary, type VoiceLifecycleContext, type VoiceLifecycleDeps, VoicePack, VoiceState, WhenRange, apply, attachVoiceLifecycle, dateKeyIn, decideTurn, domainOf, gateOf, groupStillMatches, loadVoiceState, name, parseCases, parseOverlay, parseOvernight, parseSchedule, parseVoicePack, readOvernight, resolveVoiceLibrary, saveVoiceState, selectCases };