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

package/lib/index.d.ts

@@ -0,0 +1,240 @@
+//#region src/state.d.ts
+interface MoodState {
+  label: string;
+  intensity: number;
+  since: number;
+  cause?: string;
+}
+interface SignalState {
+  lastMessageAt: number;
+  lastMessageChars: number;
+  todayTurnCount: number;
+  todayDate: string;
+  lastMessageExcerpt?: string | undefined;
+}
+type EmotionTier = 'fast' | 'mid' | 'deep';
+type EmotionTrend = 'rising' | 'stable' | 'falling';
+interface EmotionDimensionState {
+  value: number;
+  trend: EmotionTrend;
+  tier: EmotionTier;
+}
+interface MasterMoodState {
+  label: string;
+  intensity: number;
+  since: number;
+}
+/** per-maid 情绪子树(M3a 规格 §4.1):跨会话延续;缺 = v1.x maid 或旧格式(读取时懒初始化) */
+interface EmotionSubtree {
+  dimensions: Record<string, EmotionDimensionState>;
+  masterMood: MasterMoodState | null;
+  updatedAt: number;
+}
+interface HistoryEntry {
+  t: number;
+  vectors: Record<string, number>;
+  emotion?: Record<string, number> | undefined;
+}
+interface MaidEmotionState {
+  vectors: Record<string, number>;
+  prevVectors: Record<string, number>;
+  mood: MoodState | null;
+  signals: SignalState;
+  cumulativeTurns: number;
+  updatedAt: number;
+  history: HistoryEntry[];
+  emotion?: EmotionSubtree | undefined;
+}
+//#endregion
+//#region src/drivers.d.ts
+/** LLM judge 产物(providers/judge.ts 同型;强度档 0-3——LLM 打档比打分稳) */
+interface EmotionJudgeResult {
+  praised: number;
+  deepTalk: number;
+  physicalIntimacy: number;
+  masterEmotion: {
+    label: string;
+    intensity: number;
+    explicit: boolean;
+  } | null;
+}
+//#endregion
+//#region src/config.d.ts
+/**
+ * emotion.yml 配置加载与校验(T5 正式类型落点)。
+ * 文件缺省 → undefined(女仆不带情绪配置是合法形态,零 warn);
+ * 坏文件(YAML 解析失败/非 mapping)→ warn 后 undefined;
+ * 坏行(单条维度/规则不合法)→ warn 跳过该条,其余照常(规格 §7)。
+ * yml 键用 snake_case(static_rules/time_slots/…),映射到消费面的 camelCase 字段。
+ */
+/** mood 规则:pattern 为正则源(装载时编译校验),narrative 为情绪叙事句模板(T6 组装 moodNarrative 用) */
+interface MoodRule {
+  event: string;
+  pattern: string;
+  mood: string;
+  intensity: number;
+  narrative?: string;
+}
+/** 单个表达向量维度(v1.x score_rules 四元组全量映射 + maxPerTurn/floor/ceiling 增强) */
+interface DimensionConfig {
+  label: string;
+  keywords: string[];
+  score: number;
+  weight?: number;
+  missPenalty?: number;
+  maxPerTurn: number;
+  floor?: number;
+  ceiling?: number;
+  decayScale?: number;
+}
+//#endregion
+//#region src/engine.d.ts
+/** 一轮判定输入:仅主人原始输入(白名单过滤在 lifecycle,引擎结构性只见 userText) */
+interface TurnInput {
+  userText: string;
+  at: number;
+  sessionId: string;
+}
+interface EmotionConfigLike {
+  dimensions: Record<string, DimensionConfig>;
+  turnStages?: Record<string, string[]>;
+  moodRules?: MoodRule[];
+  keywordRules?: {
+    pattern: string;
+    rules: string[];
+  }[];
+}
+/** 一轮判定产物:deltas 供 applyTurn 累加;moodEvent 供情绪状态机迁移 */
+interface EngineResult {
+  vectorDeltas: Record<string, number>;
+  moodEvent: MoodRule | null;
+  turnStageKey: string | null;
+}
+declare function scoreTurn(vectors: Record<string, number>, input: TurnInput, cfg: EmotionConfigLike): EngineResult;
+type ReunionTier = 'soft' | 'distant' | 'estranged';
+//#endregion
+//#region src/providers/judge.d.ts
+/** 判定 provider 接缝(M3 LLM 判分同面插拔,不动 engine) */
+interface JudgeProvider {
+  id: string;
+  score(vectors: Record<string, number>, input: TurnInput, cfg: EmotionConfigLike): ReturnType<typeof scoreTurn>;
+}
+/** 判分输入:本轮主人消息 + 前 N 条(窗口默认 2,可配 0-3;只装主人原始输入,白名单在 lifecycle) */
+interface EmotionJudgeInput {
+  current: string;
+  previous: string[];
+}
+interface EmotionJudgeProvider {
+  id: string;
+  /** null = 本轮零内容事件(fail-open:abort/空路由/llm 不可用/解析失败,均已在内部 warn 消化) */
+  judge(input: EmotionJudgeInput, signal?: AbortSignal): Promise<EmotionJudgeResult | null>;
+}
+//#endregion
+//#region src/state-store.d.ts
+/**
+ * 状态存取缝(接口先行,M3a 规格 §2 拍板:状态底座并入 maid-emotion,存取抽接口;
+ * M4 world 状态需要共享时再提升独立 seam——届时消费方(lifecycle/service)零改动)。
+ */
+interface StateStore {
+  load(maidId: string): MaidEmotionState | undefined;
+  save(maidId: string, state: MaidEmotionState): void;
+}
+//#endregion
+//#region src/lifecycle.d.ts
+declare module '@deepseek-ai/dsh-llm' {
+  interface MessageSourceMap {
+    'plugin:maid-emotion': {
+      kind: 'plugin:maid-emotion';
+    };
+  }
+}
+/**
+ * maid-emotion 生命周期(T6 装配):turn/end 消费主人原始输入 → judge → 状态落盘;
+ * agent/pre-step 注入叙事投影(durable user 面 <system-reminder> 事件,缓存纪律铁律 3)。
+ * 钩子形态照 maid-memory lifecycle:agent/pre-step 运行时字符串派发(duck-typing),
+ * turn/end 经 session/event firehose(durable SessionEvent,非 cordis 钩子)。
+ */
+interface MaidEmotionConfig {
+  stateFile: string;
+  presetRoots: string[];
+  allowMaids?: string[];
+  excludeSources?: string[];
+  weather?: {
+    location?: string;
+    lat?: number;
+    lon?: number;
+    detail?: 'brief' | 'full';
+    ttlMs?: number;
+    primary?: string;
+    fallback?: string;
+  };
+  projectionBudgetTokens?: number;
+  vectorHalfLifeMs?: number;
+  moodHalfLifeMs?: number;
+  trendBand?: number;
+  debug?: boolean;
+  timezone?: string;
+  /** 测试注入(照 maid-memory distiller 先例):缺省 rulesJudge(T4) */
+  judge?: JudgeProvider;
+  /** 情绪内容判分(测试注入缝);缺省:emotionJudgeRoute 建 llmJudge;均无 → 内容驱动停用(行为规则仍生效) */
+  emotionJudge?: EmotionJudgeProvider;
+  /** 生产副脑路由(M1b syncTurn 同款);模型可配,不必是主对话模型 */
+  emotionJudgeRoute?: {
+    provider: string;
+    model: string;
+  };
+  /** 状态存取缝(测试注入,照 config.judge 先例);缺省 createJsonFileStateStore(stateFile) */
+  store?: StateStore;
+  /** 时钟注入(测试用);缺省 Date.now() */
+  now?: () => number;
+}
+interface MaidEmotionService {
+  /** 可观测读:maidId → 对齐后的当前持久状态(只读快照,不触发衰减物化) */
+  stateOf(maidId: string): MaidEmotionState | undefined;
+  /**
+   * 统一活力入口(maid-gestures 前置,重逢回补管线同款):deltas 键过滤到 emotionVectors
+   * 声明集 → applyEmotionTurn(增益/trend 管线)→ 落盘。true=落账成功;false=maid 未注册 /
+   * preset 无情绪配置 / 过滤后空集 / 管线异常(warn)。tier 护栏在调用方——服务面只做管线,不管 tier。
+   */
+  applyDeltas(maidId: string, deltas: Record<string, number>): boolean;
+  /**
+   * 只读快照(M3c Task 3,maid-voice reflect 消费面):投影路径同款 load → align →
+   * applyDecay(now) 惰性组装,**绝不写 store**;未注册 maid / 无情绪配置 → undefined。
+   */
+  getSnapshot(maidId: string): EmotionSnapshot | undefined;
+}
+/**
+ * 情绪快照(M3c Task 3 规格 §4):跨 seam 只读投影视图。lastWeather 是进程内最近读数
+ * (重启即失,规格 §4.2 已知简化——不落盘);其余字段全部可从持久状态 + 配置组装。
+ */
+interface EmotionSnapshot {
+  vector: Record<string, number>;
+  trends: Record<string, EmotionTrend> | undefined;
+  reunionTier: ReunionTier | null;
+  sinceLastMessageMs: number;
+  lastMasterMessage: {
+    at: number;
+    excerpt: string;
+  } | undefined;
+  lastWeather: {
+    at: number;
+    text: string;
+  } | undefined;
+  calendarSentences: string[];
+  timeText: string;
+}
+/**
+ * 会话来源(供 excludeSources 判定)。执行期核对(dsh 0.1.2-alpha.3):SessionHeader 字段集为
+ * version/id/createdAt/cwd/parentSession/seedLength/origin('subagent')/delegationDepth/agentPreset,
+ * **无 source/lane 字段**;cron 车道唯一稳定标识是 maid-cron 的 `cron_` sessionId 前缀
+ * (maid-cron engine.ts:108 `cron_${jobId}_${iso}`)——M1c cron-lane 快照同源判定路径。
+ */
+declare function sessionSource(sessionId: string): string | undefined;
+declare function alignStateToConfig(state: MaidEmotionState, dimensionIds: readonly string[], emotionTiers?: Record<string, EmotionTier>): MaidEmotionState;
+//#endregion
+//#region src/index.d.ts
+declare const name = "maid-emotion";
+declare const inject: string[];
+declare const apply: (ctx: any, config: MaidEmotionConfig) => (() => Promise<void>);
+//#endregion
+export { type EmotionSnapshot, type MaidEmotionConfig, type MaidEmotionService, alignStateToConfig, apply, inject, name, sessionSource };