dsh-galatea 0.0.0-stage → 0.3.2

package/README.md

@@ -1,3 +1,129 @@
-# Temporary Holding Version
+# Galatea
 
-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.
+让 DeepSeek Harness 上的 Agent 有记忆、会安静、能连续下去。
+
+三块骨头：
+
+- **记忆** —— Markdown 落地，**正文不进上下文，只进标题**
+- **心跳** —— 确定性门控，默认闭嘴；用户设的是「什么时候不许叫我」
+- **连续** —— 不写成目标，写成可观察的事实
+
+## 现在到哪了
+
+| 块 | 状态 |
+|---|---|
+| 能被 DSH 装起来 | ✅ 实测通过（dsh 0.2.2-rc.3） |
+| 记忆：读写 Markdown | ✅ 15 条测试 |
+| 记忆：注入索引 | ✅ 接上 systemPrompt，实测无告警 |
+| 记忆：`remember` / `recall` | ✅ 23 条测试 |
+| 心跳：门控（要不要开口） | ✅ 15 条测试 |
+| 心跳：状态账本（跨进程） | ✅ 10 条测试 |
+| 心跳：对谁说（排除子代理） | ✅ 10 条测试 |
+| 心跳：说什么（没出处就不说） | ✅ 10 条测试 |
+| 心跳：三段合成一个决定 | ✅ 10 条测试 |
+| 心跳：`galatea_beat` 手动档 | ✅ 实测加载，无告警 |
+| 设置页可改的字段 | ⚠️ 声明被宿主接受，**表单没在 GUI 里看过** |
+| 心跳：定时器 + 自动开口 | ⬜ 未做 |
+| 发布到 npm | ⬜ 未做 |
+
+> ⚠️ **它现在还不会自己开口。** 定时器和 `ctx.agents.resume` 都还没接，
+> 判定链路完整，但没有出口。别把「测试全绿」读成「它已经在主动找你了」。
+
+## 怎么用
+
+三个工具，Agent 自己会调：
+
+| 工具 | 干什么 |
+|---|---|
+| `galatea_remember` | 记一条。标题进索引，正文不进 |
+| `galatea_recall` | 给 id 读正文，不给 id 列标题 |
+| `galatea_beat` | 手动跑一次心跳：**现在该不该说话、对谁说、拿哪条当由头**。只算不发 |
+
+`galatea_beat` 是给「你现在想说什么」这个问题准备的。它不依赖定时器，
+所以在任何有会话的地方都能立刻看到整条链路通不通。
+
+## 设置（不用改代码）
+
+六个字段声明为 `.volatile()`，所以 DSH 的设置页会照着 schema 自动生成表单，
+改完**不重启插件**：
+
+| 字段 | 说明 |
+|---|---|
+| `quietFrom` / `quietTo` | 安静时段，这段时间它绝不主动开口。跨午夜没问题（23:00 → 08:00） |
+| `cooldownMinutes` | 你刚说完话，它至少安静多久 |
+| `minGapMinutes` | 两次心跳最少隔多久 |
+| `dice` | 没有由头时的开口概率。0 = 只在有素材时说 |
+| `quietRounds` | 连续多少轮没开口就强制说一次。0 = 关掉这个保底 |
+
+两处容易踩的：
+
+- **「连续几轮没说就强制一次」和「最少间隔」是耦合的。** 心跳间隔设得比保底所需的时间还短，保底永远不会触发。
+- **把 `quietRounds` 关掉，它可能安静到让你以为坏了。** 默认闭嘴需要一条下限，不然沉默和故障长得一样。
+
+## 唯一的设计判断
+
+**正文不进上下文，只进标题。**
+
+常见的做法是每轮把记忆全文塞进提示里。那样一旦超过几十条，要么超预算，要么被迫摘要——
+而摘要之后，写进去的东西和读回来的东西就不是同一个了。
+
+所以这里注入的是「我记得过什么」（一行一条），正文躺着不动，要用的时候再去读。
+读的人知道自己读的是什么。
+
+同一个判断延伸出三条规矩，都写进了测试：
+
+1. 一条都没有时，说「还没开始」——不能什么都不显示，那和「功能坏了」长得一样
+2. 目录读不到时，说「读不到」，不说「0 条」
+3. 只给标题 + 日期，不给正文
+
+## 心跳为什么默认闭嘴
+
+大多数「主动说话」是：用户设一个时间，到点了 Agent 说话。那叫定时提醒——
+频率由用户决定，它对世界一无所知。
+
+这里反过来：**用户设的不是「什么时候叫我」，是「什么时候绝对不许叫我」。**
+
+墙之外，说不说取决于有没有**素材**——自己记下的、还没说过的条目。
+一条都没有，就不说。这不是「找不到素材」的技术失败，是应该沉默。
+
+门控可以自动决定，**内容不能自动生成**。空话比不说更糟，它消耗的是「它真的在」那点信用。
+
+## 数据放在哪
+
+```
+$DSH_HOME/galatea/memory/entries/<YYYY-MM-DD>-<短名>.md    # 记忆条目
+$DSH_HOME/galatea/heartbeat-state.json                      # 心跳状态账本
+```
+
+文件名就是 id。日期在前，所以目录列表天然按时间排。正文第一行是标题。
+
+状态账本记的是：上一轮什么时候跳的、上次开口是什么时候、连续几轮没说话、最近的决定。
+它必须落盘——不落盘的话进程一重启计数就归零，下限保护立刻失效。
+
+## 本地开发
+
+```bash
+npm test          # 78 条，不依赖 DSH，纯 node
+```
+
+装了之后验证它真的加载了，只看一个东西：
+
+```
+~/.dsh/galatea-loaded.txt
+```
+
+那行 marker 不是日志，是**正控**：只有它出现，才说明这段代码真的跑过。
+「进程起来了」「配置里写了」都不算证据。
+
+## 安装（还没发布）
+
+profile 的 `package.json`：
+
+```json
+"dependencies": { "dsh-galatea": "file:E:/Galatea" },
+"dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "dsh-galatea"] } }
+```
+
+## 授权
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: galatea
+      name: 'dsh-galatea'

package/index.js

@@ -0,0 +1,158 @@
+/**
+ * Galatea — 让 Agent 像人的三块骨头。
+ *
+ *   记忆：Markdown 落地，正文不进上下文，只进标题
+ *   心跳：（下一步）
+ *   连续：（不写成目标，写成可观察的事实）
+ *
+ * 这个文件只做接线。规则在 lib/ 里，能单独用 node 跑，不依赖 DSH。
+ * 这样测的时候不需要起一个宿主，「测的」和「跑的」才是同一份代码。
+ */
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import z from '@deepseek-ai/schemastery';
+
+import { renderIndex, dataRoot, listEntries } from './lib/store.js';
+import { remember, recall } from './lib/tools.js';
+import { makeBeatTool, snapshotAgents } from './lib/beat-tool.js';
+import { loadState } from './lib/heartbeat-runner.js';
+import { DEFAULTS } from './lib/heartbeat.js';
+
+/** Cordis 插件名。 */
+export const name = 'galatea';
+
+/**
+ * 设置页里能改的字段。
+ *
+ * 为什么全都挂 `.volatile()`：
+ *   不挂的字段一改，Cordis 会重新 mount 整个插件 —— 用户点一下保存，
+ *   插件重启一次，正在跑的心跳计数也跟着清零。
+ *   挂上之后值原地提交，不重启。
+ *
+ * 为什么是扁平字段而不是 `quiet: [{from,to}]`：
+ *   DSH 的表单是照着 schema 生成的，它表达不了数组里套对象。
+ *   所以这里拆成两个字符串，apply 里再拼回去。
+ *   这是为了「能改」付的代价，而能改比结构漂亮重要。
+ */
+export const Config = z.object({
+  quietFrom: z
+    .string()
+    .default(DEFAULTS.quiet[0].from)
+    .description('安静时段从几点开始。这段时间里它绝不主动开口。格式 23:00')
+    .volatile(),
+  quietTo: z
+    .string()
+    .default(DEFAULTS.quiet[0].to)
+    .description('安静时段到几点结束。跨午夜没问题，比如 23:00 → 08:00。格式 08:00')
+    .volatile(),
+  cooldownMinutes: z
+    .number()
+    .default(DEFAULTS.cooldownMinutes)
+    .description('你刚说完话之后，它至少安静多少分钟。设成 0 会变成你一说话它就插嘴。')
+    .volatile(),
+  minGapMinutes: z
+    .number()
+    .default(DEFAULTS.minGapMinutes)
+    .description('两次心跳之间至少隔多久。注意：设得比「连续几轮没说话就强制开口」所需的时间还短的话，那个保底永远不会触发。')
+    .volatile(),
+  dice: z
+    .number()
+    .default(DEFAULTS.dice)
+    .description('没有具体由头时的开口概率（0~1）。0 = 只在有素材时说话，越接近 1 越吵。')
+    .volatile(),
+  quietRounds: z
+    .number()
+    .default(DEFAULTS.quietRounds)
+    .description('连续这么多轮没开口，就强制说一次。0 = 关掉这个保底。关掉的话，它可能安静到让你以为坏了。')
+    .volatile(),
+});
+
+/** 需要宿主注入的服务。 */
+export const inject = ['systemPrompt', 'tools', 'agents'];
+
+/**
+ * volatile 字段是**引用**，普通字段是**值**。
+ * 这里统一取值：引用就 `.get()`，否则原样返回。
+ *
+ * 一定要在使用的那一刻取，不能在 apply 里取一次存起来 ——
+ * 那样设置页改完看起来生效了，实际跑的还是旧值，而且不报错。
+ * （这类「改了但没生效」我今天已经踩过一次，不想再踩。）
+ */
+function pick(v, fallback) {
+  if (v && typeof v.get === 'function') {
+    const got = v.get();
+    return got === undefined ? fallback : got;
+  }
+  return v === undefined ? fallback : v;
+}
+
+/** 把扁平的设置字段拼回心跳模块要的形状。表单表达不了数组，所以在这里拼。 */
+function liveConfig(raw) {
+  return {
+    quiet: [
+      {
+        from: pick(raw?.quietFrom, DEFAULTS.quiet[0].from),
+        to: pick(raw?.quietTo, DEFAULTS.quiet[0].to),
+      },
+    ],
+    cooldownMinutes: pick(raw?.cooldownMinutes, DEFAULTS.cooldownMinutes),
+    minGapMinutes: pick(raw?.minGapMinutes, DEFAULTS.minGapMinutes),
+    dice: pick(raw?.dice, DEFAULTS.dice),
+    quietRounds: pick(raw?.quietRounds, DEFAULTS.quietRounds),
+  };
+}
+
+/**
+ * @param {object} ctx    Cordis context
+ * @param {object} [config]
+ */
+export function apply(ctx, config) {
+  const raw = config ?? {};
+  const cfg = raw;
+
+  // ── 正控：这一段真的跑过吗 ────────────────────────────────
+  // marker 不是日志。它只回答一个问题：apply() 到底有没有被执行。
+  // 「进程起来了」「配置里写了」都不算证据。
+  const marker = cfg.markerPath || join(homedir(), '.dsh', 'galatea-loaded.txt');
+  try {
+    mkdirSync(dirname(marker), { recursive: true });
+    appendFileSync(marker, `galatea loaded at ${new Date().toISOString()} pid=${process.pid}\n`);
+  } catch (err) {
+    console.warn('[galatea] marker 写入失败:', err && err.message);
+  }
+
+  // ── 记忆的注入段 ────────────────────────────────────────
+  // text 传函数：每一轮提示组装时现算，不缓存。
+  // 缓存过一版，结果和「记忆变了但注入没变」长得一模一样，分不出来。
+  if (ctx && ctx.systemPrompt && typeof ctx.systemPrompt.section === 'function') {
+    ctx.systemPrompt.section({
+      name: 'galatea:memory',
+      order: cfg.order ?? 0.6,
+      text: () => renderIndex({ limit: cfg.limit ?? 12 }),
+      interpolate: false,
+    });
+  } else {
+    console.warn('[galatea] 宿主没有 systemPrompt 服务，记忆注入没接上。dataRoot =', dataRoot());
+  }
+
+  // ── 工具 ────────────────────────────────────────────────
+  // 工具是「手」，注入是「眼睛」。
+  // 只有眼睛没有手，记忆就只能靠人手动往目录里放文件——那不是 Agent 的记忆。
+  if (ctx && ctx.tools && typeof ctx.tools.register === 'function') {
+    ctx.tools.register(remember);
+    ctx.tools.register(recall);
+    // 手动档：只算不发。它不依赖定时器，所以在任何有会话的地方都能立刻验。
+    // 自动档（定时器 + resume）是另一件事 —— 那个会真的开口，得单独接。
+    ctx.tools.register(
+      makeBeatTool({
+        listAgents: () => snapshotAgents(ctx.agents),
+        listEntries,
+        loadState,
+        config: () => liveConfig(raw),
+      }),
+    );
+  } else {
+    console.warn('[galatea] 宿主没有 tools 服务，记忆只能读不能写。');
+  }
+}

package/lib/beat-tool.js

@@ -0,0 +1,114 @@
+/**
+ * galatea_beat —— 手动跑一次心跳，看它会说什么。
+ *
+ * 这是自动档之前必须先有的东西：
+ *   自动档 = 定时器调同一个函数；手动档 = 有人问的时候调。
+ *   先有手动档，才能在**任何有会话的地方**立刻验证整条链路，
+ *   而不用等它自己响（也没法等，它还没接定时器）。
+ *
+ * 它只算不发。真要发出去是另一件事，得单独做、单独开。
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+
+import { planBeat } from './beat.js';
+import { pickMaterial } from './material.js';
+import { renderJournal } from './journal.js';
+
+/**
+ * 把 agents 服务里的 live agent 统一成 { id, header }。
+ * 读不到就返回空数组 —— 让它走「没人在看」那条路，比抛异常好。
+ */
+export function snapshotAgents(agentsService) {
+  try {
+    const list = typeof agentsService?.list === 'function' ? agentsService.list() : [];
+    return (Array.isArray(list) ? list : []).map((a) => ({
+      id: a?.session?.id ?? a?.id ?? 'unknown',
+      header: a?.session?.header,
+    }));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * @param {object} deps
+ * @param {() => Array} deps.listAgents   返回 [{id, header}]
+ * @param {() => Array} deps.listEntries  返回记忆条目
+ * @param {() => object} deps.loadState
+ * @param {object} [deps.config]
+ */
+export function makeBeatTool(deps) {
+  return defineTool({
+    name: 'galatea_beat',
+    description:
+      '手动跑一次心跳：现在该不该主动说话、对谁说、拿哪条记忆当由头。' +
+      '只算，不发送。想知道「你现在想说什么」的时候用。',
+    parameters: {},
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          speak: { type: 'boolean' },
+          reason: { type: 'string' },
+          detail: { type: 'string' },
+          sessionId: { type: 'string' },
+          materialId: { type: 'string' },
+          materialTitle: { type: 'string' },
+          prompt: { type: 'string' },
+          switched: { type: 'boolean' },
+          previous: { type: 'string' },
+          text: { type: 'string' },
+          journal: { type: 'string' },
+        },
+      },
+      render: (_args, v) => [{ type: 'text', text: v.text }],
+    },
+    isConcurrencySafe: () => true,
+    async execute() {
+      const candidates = deps.listAgents();
+      const entries = deps.listEntries();
+      const state = deps.loadState();
+
+      const liveCfg = typeof deps.config === 'function' ? deps.config() : (deps.config ?? {});
+
+      const r = planBeat({
+        now: new Date(),
+        state,
+        candidates,
+        entries,
+        // 配置可以是函数：设置页改的是引用，每次现读才拿得到新值。
+        // 传快照的话，界面上改了、跑起来还是旧的，而且不报错。
+        config: liveCfg,
+      });
+
+      const material = entries.find((e) => e.id === r.materialId) ?? null;
+      const picked = material ?? pickMaterial(entries, state.lastSpokeAt ?? null).entry;
+
+      // 给人看的那几行：把它自己最近的决定翻成人话。
+      const journal = renderJournal(state, { quietRounds: liveCfg.quietRounds });
+
+      const lines = [];
+      lines.push(r.speak ? '现在会说话。' : '现在不会说话。');
+      lines.push(`理由：${r.reason} —— ${r.detail}`);
+      lines.push(`对谁说：${r.sessionId ?? '（没有活着的会话）'}`);
+      if (r.switched) lines.push(`⚠ 换了目标会话：${r.previous} → ${r.sessionId}（连续在这里断过一次）`);
+      if (picked) lines.push(`由头：${picked.id}　${picked.title}`);
+      if (r.prompt) lines.push(`会带着这段由头开口：\n${r.prompt}`);
+
+      return {
+        speak: r.speak,
+        reason: r.reason,
+        detail: r.detail,
+        sessionId: r.sessionId ?? '',
+        materialId: picked?.id ?? '',
+        materialTitle: picked?.title ?? '',
+        prompt: r.prompt ?? '',
+        switched: r.switched === true,
+        previous: r.previous ?? '',
+        text: lines.join('\n'),
+        journal,
+      };
+    },
+  });
+}

package/lib/beat.js

@@ -0,0 +1,95 @@
+/**
+ * 一次心跳 = 目标 + 素材 + 门控 → 一个决定。
+ *
+ * 这一层只做「算出该干什么」，不做「真的去干」。
+ * 真的去干那一步（resume）放在接线里，因为它会打扰人、会失败、会留下痕迹，
+ * 而那些事没有一件适合藏在纯函数里。
+ *
+ * 顺序是有讲究的，不能换：
+ *
+ *   目标 → 素材 → 门控
+ *
+ * 不先选目标：不知道该对谁说，后面全白算。
+ * 不先找素材：门控会掷色子，掷中了却没有东西可说 —— 那就是空话。
+ *   空话比不说更糟，它消耗的是「它真的在」那点信用。
+ */
+import { pickTarget } from './target.js';
+import { pickMaterial, materialPrompt } from './material.js';
+import { decide, DEFAULTS } from './heartbeat.js';
+
+/**
+ * @param {object} input
+ * @param {Date} input.now
+ * @param {object} input.state           心跳状态账本
+ * @param {Array}  input.candidates      活着的会话 [{id, header}]
+ * @param {Array}  input.entries         记忆条目 [{id, title, at}]
+ * @param {object} [input.config]
+ * @param {() => number} [input.random]
+ * @returns {{speak: boolean, reason: string, sessionId: string|null,
+ *            prompt: string|null, switched: boolean, previous: string|null,
+ *            materialId: string|null, detail: string}}
+ */
+export function planBeat(input) {
+  const cfg = { ...DEFAULTS, ...(input.config ?? {}) };
+  const now = input.now instanceof Date ? input.now : new Date(input.now ?? Date.now());
+  const state = input.state ?? {};
+
+  // ── ① 对谁说 ────────────────────────────────────────────
+  const target = pickTarget(input.candidates ?? [], state.targetSessionId ?? null);
+  if (!target.sessionId) {
+    return no(target.reason, '没有活着的会话 —— 没人看着，说了也没人接', {
+      switched: false,
+      previous: null,
+    });
+  }
+
+  // ── ② 说什么 ────────────────────────────────────────────
+  const material = pickMaterial(input.entries ?? [], state.lastSpokeAt ?? null);
+  if (!material.entry) {
+    return no(
+      material.reason === 'noEntries' ? 'noMaterial' : 'nothingNew',
+      material.reason === 'noEntries'
+        ? '记忆里一条可用的都没有 —— 没有出处的话不说'
+        : '写了的东西都说过了 —— 没有新的就不开口',
+      { switched: target.switched, previous: target.previous, sessionId: target.sessionId },
+    );
+  }
+
+  // ── ③ 现在该不该说 ──────────────────────────────────────
+  // hasHardMaterial = true：有具体的东西要说，就不掷色子。
+  // 色子留给「有点想法但没到非说不可」，这里不是那种情况。
+  const decision = decide({
+    now,
+    lastBeatAt: state.lastBeatAt ?? null,
+    lastUserAt: state.lastUserAt ?? null,
+    lastSpokeAt: state.lastSpokeAt ?? null,
+    hasHardMaterial: true,
+    quietStreak: state.quietStreak ?? 0,
+    config: cfg,
+    random: input.random,
+  });
+
+  return {
+    speak: decision.speak,
+    reason: decision.reason,
+    sessionId: target.sessionId,
+    prompt: decision.speak ? materialPrompt(material.entry) : null,
+    switched: target.switched,
+    previous: target.previous,
+    materialId: material.entry.id,
+    detail: decision.detail,
+  };
+
+  function no(reason, detail, extra) {
+    return {
+      speak: false,
+      reason,
+      sessionId: extra.sessionId ?? null,
+      prompt: null,
+      switched: extra.switched,
+      previous: extra.previous,
+      materialId: null,
+      detail,
+    };
+  }
+}

package/lib/heartbeat-runner.js

@@ -0,0 +1,97 @@
+/**
+ * 心跳的执行层（第一段：**状态账本**，不含真正发消息）。
+ *
+ * 为什么先只做这一段：门控是纯函数，能离线验；但「上一轮什么时候跳的」
+ * 「连续几轮没开口了」这些**必须落盘**，否则进程一重启，下限保护就归零，
+ * 那个「安静到像坏了」的老毛病会立刻回来。
+ *
+ * 所以先把状态写清楚，再做发消息那一步。发消息会真的打扰人，
+ * 单独一版做，而且默认关。
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+
+import { decide, DEFAULTS } from './heartbeat.js';
+import { dataRoot } from './store.js';
+
+export function stateFile() {
+  return join(dataRoot(), 'heartbeat-state.json');
+}
+
+export const EMPTY_STATE = {
+  lastBeatAt: null,
+  lastSpokeAt: null,
+  lastUserAt: null,
+  quietStreak: 0,
+  decisions: [],
+};
+
+export function loadState(file = stateFile()) {
+  if (!existsSync(file)) return { ...EMPTY_STATE, decisions: [] };
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8'));
+    return { ...EMPTY_STATE, ...parsed, decisions: Array.isArray(parsed.decisions) ? parsed.decisions : [] };
+  } catch {
+    // 读坏了就当没有 —— 但不能静默：调用方能从 decisions 为空看出来
+    return { ...EMPTY_STATE, decisions: [] };
+  }
+}
+
+export function saveState(state, file = stateFile()) {
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(state, null, 2), 'utf8');
+  return file;
+}
+
+/**
+ * 跑一轮心跳：读状态 → 判定 → 写状态。
+ *
+ * 注意 **先写状态再说话**：说话可能失败（没凭据、会话没了），
+ * 如果先说话后记账，失败时这一轮就不计数，下限保护会永远不触发。
+ *
+ * @returns {{ decision: object, state: object, shouldSpeak: boolean }}
+ */
+export function tick(opts = {}) {
+  const now = opts.now instanceof Date ? opts.now : new Date(opts.now ?? Date.now());
+  const file = opts.file ?? stateFile();
+  const prev = opts.state ?? loadState(file);
+  const config = { ...DEFAULTS, ...(opts.config ?? {}) };
+
+  const decision = decide({
+    now,
+    lastUserAt: prev.lastUserAt,
+    lastSpokeAt: prev.lastSpokeAt,
+    lastBeatAt: prev.lastBeatAt,
+    hasHardMaterial: opts.hasHardMaterial === true,
+    quietStreak: prev.quietStreak ?? 0,
+    config,
+    random: opts.random,
+  });
+
+  const entry = {
+    at: now.toISOString(),
+    speak: decision.speak,
+    reason: decision.reason,
+    detail: decision.detail,
+  };
+
+  const next = {
+    ...prev,
+    lastBeatAt: now.toISOString(),
+    quietStreak: decision.speak ? 0 : (prev.quietStreak ?? 0) + 1,
+    decisions: [...(prev.decisions ?? []), entry].slice(-(opts.keepDecisions ?? 50)),
+  };
+  if (decision.speak) next.lastSpokeAt = now.toISOString();
+
+  if (opts.dryRun !== true) saveState(next, file);
+
+  return { decision, state: next, shouldSpeak: decision.speak };
+}
+
+/** 用户说话了 ⟹ 更新 lastUserAt。冷却判据要用它。 */
+export function noteUserMessage(at = new Date(), file = stateFile()) {
+  const prev = loadState(file);
+  const next = { ...prev, lastUserAt: (at instanceof Date ? at : new Date(at)).toISOString() };
+  saveState(next, file);
+  return next;
+}

package/lib/heartbeat.js

@@ -0,0 +1,187 @@
+/**
+ * 心跳的门控 —— 这一版只做「要不要开口」，不负责开口。
+ *
+ * ════════════════════════════════════════════════════════════
+ * 一条设计判断（这是整个文件存在的理由）
+ * ════════════════════════════════════════════════════════════
+ *
+ * 大多数「主动说话」都是这么做的：用户设一个时间，到点了 Agent 说话。
+ * 那个东西叫**定时提醒**，不叫心跳 —— 它的频率由用户决定，它对世界一无所知。
+ *
+ * 这里反过来：**用户设的不是「什么时候叫我」，是「什么时候绝对不许叫我」。**
+ * 安静时段是硬墙。墙之外，说不说取决于两件事：
+ *
+ *   ① 有没有「硬素材」——有具体的事（承诺到期、上次没说完的、真发现了什么）
+ *   ② 没有硬素材时，掷色子，而且概率压低
+ *
+ * 为什么分成两档：硬素材的时候掷色子是浪费（有事就该说）；
+ * 只有「有点想法但没到非说不可」才适合掷。
+ *
+ * ════════════════════════════════════════════════════════════
+ * 第二条判断：沉默必须能被区分
+ * ════════════════════════════════════════════════════════════
+ *
+ * 用户最容易产生的困惑不是「它说了什么」，是**「它今天为什么没响」**。
+ * 所以每一次决定都带一个 reason，而且几个 reason 互斥、加起来能解释所有情况：
+ *
+ *   安静时段 / 刚聊过 / 素材不够且色子没中 / 下限保护触发 / 该说
+ *
+ * 没有这一条，产品坏了和产品很安静长得一模一样。
+ *
+ * ════════════════════════════════════════════════════════════
+ * 第三条判断：必须有一条「下限保护」
+ * ════════════════════════════════════════════════════════════
+ *
+ * 「默认闭嘴」如果只有上限没有下限，它会安静到让人以为坏了。
+ * 我自己踩过这个坑：加了个筛选条件，结果恒为空集，本来想「少说空话」，
+ * 实际做成了「永远不说话」。
+ * 所以：连续 quietRounds 次都没开口 ⟹ 下一次强制允许。
+ */
+
+/** 默认配置。全都可以被 profile 配置覆盖。 */
+export const DEFAULTS = {
+  /** 安静时段（本地时间，含头不含尾）。跨午夜写成两段会自动合并。 */
+  quiet: [
+    { from: '23:00', to: '08:00' },
+  ],
+  /** 距用户上一条消息不到这么久，就别插嘴——他刚说完。单位：分钟。 */
+  cooldownMinutes: 10,
+  /** 两次心跳之间至少隔这么久，防止定时器抽风连发。单位：分钟。 */
+  minGapMinutes: 20,
+  /** 弱素材时的开口概率。0 = 从不，1 = 每次都开。 */
+  dice: 0.15,
+  /** 连续这么多轮没开口 ⟹ 下一轮强制允许一次。0 = 关掉下限保护。 */
+  quietRounds: 8,
+};
+
+/** "HH:MM" → 分钟数。非法返回 null。 */
+export function parseClock(s) {
+  const m = /^(\d{1,2}):(\d{2})$/.exec(String(s ?? '').trim());
+  if (!m) return null;
+  const h = Number(m[1]);
+  const min = Number(m[2]);
+  if (h < 0 || h > 23 || min < 0 || min > 59) return null;
+  return h * 60 + min;
+}
+
+/** 某个时刻落在哪一天的第几分钟（本地时区）。 */
+export function minutesOfDay(date) {
+  return date.getHours() * 60 + date.getMinutes();
+}
+
+/** 这一分钟在不在安静时段里。支持跨午夜。 */
+export function inQuiet(minuteOfDay, quiet) {
+  for (const w of quiet ?? []) {
+    const a = parseClock(w.from);
+    const b = parseClock(w.to);
+    if (a === null || b === null) continue;
+    if (a === b) continue; // 空窗口
+    if (a < b) {
+      if (minuteOfDay >= a && minuteOfDay < b) return true;
+    } else {
+      // 跨午夜：23:00→08:00
+      if (minuteOfDay >= a || minuteOfDay < b) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * 决定这一轮要不要开口。
+ *
+ * @param {object} input
+ * @param {Date}   input.now            当前时间
+ * @param {Date|number|null} input.lastUserAt    用户最后一条消息的时间（null = 不知道）
+ * @param {Date|number|null} input.lastSpokeAt   我最后一次主动开口的时间
+ * @param {Date|number|null} input.lastBeatAt    上一轮心跳的时间（用于 minGap）
+ * @param {boolean} input.hasHardMaterial  有没有硬素材
+ * @param {number}  input.quietStreak      连续多少轮没开口了
+ * @param {object}  [input.config]         覆盖 DEFAULTS
+ * @param {() => number} [input.random]    注入随机源，测试用
+ *
+ * @returns {{ speak: boolean, reason: string, detail: string }}
+ */
+export function decide(input) {
+  const cfg = { ...DEFAULTS, ...(input.config ?? {}) };
+  const now = input.now instanceof Date ? input.now : new Date(input.now);
+  const random = input.random ?? Math.random;
+
+  // ── ① 安静时段：硬墙，先挡 ──────────────────────────────
+  if (inQuiet(minutesOfDay(now), cfg.quiet)) {
+    return { speak: false, reason: 'quiet', detail: '落在用户设的安静时段里' };
+  }
+
+  // ── ② 间隔：定时器抽风或上一轮太近，别叠 ────────────────
+  const lastBeat = toMs(input.lastBeatAt);
+  if (lastBeat !== null) {
+    const gap = (now.getTime() - lastBeat) / 60000;
+    if (gap < cfg.minGapMinutes) {
+      return {
+        speak: false,
+        reason: 'tooSoon',
+        detail: `距上一轮心跳 ${gap.toFixed(1)} 分钟，不到 ${cfg.minGapMinutes}`,
+      };
+    }
+  }
+
+  // ── ③ 冷却：他刚说完话，别插嘴 ──────────────────────────
+  const lastUser = toMs(input.lastUserAt);
+  if (lastUser !== null) {
+    const since = (now.getTime() - lastUser) / 60000;
+    if (since < cfg.cooldownMinutes) {
+      return {
+        speak: false,
+        reason: 'cooldown',
+        detail: `距用户上一条消息 ${since.toFixed(1)} 分钟，不到 ${cfg.cooldownMinutes}`,
+      };
+    }
+  }
+
+  // ── ④ 硬素材：有就说，不掷 ──────────────────────────────
+  if (input.hasHardMaterial === true) {
+    // 但也要防「刚说完又马上来一次」——靠 lastSpokeAt 单独挡
+    const spoke = toMs(input.lastSpokeAt);
+    if (spoke !== null) {
+      const since = (now.getTime() - spoke) / 60000;
+      if (since < cfg.cooldownMinutes) {
+        return {
+          speak: false,
+          reason: 'cooldown',
+          detail: `距上次主动开口 ${since.toFixed(1)} 分钟，不到 ${cfg.cooldownMinutes}`,
+        };
+      }
+    }
+    return { speak: true, reason: 'hard', detail: '有具体的事要说' };
+  }
+
+  // ── ⑤ 下限保护：太久没开口，强制允许一次 ────────────────
+  if (cfg.quietRounds > 0 && (input.quietStreak ?? 0) >= cfg.quietRounds) {
+    return {
+      speak: true,
+      reason: 'floor',
+      detail: `已连续 ${input.quietStreak} 轮没开口，触到下限保护`,
+    };
+  }
+
+  // ── ⑥ 弱素材：掷色子 ────────────────────────────────────
+  const r = random();
+  if (r < cfg.dice) {
+    return { speak: true, reason: 'dice', detail: `色子 ${r.toFixed(3)} < ${cfg.dice}` };
+  }
+  return {
+    speak: false,
+    reason: 'noMaterial',
+    detail: `没硬素材，色子 ${r.toFixed(3)} ≥ ${cfg.dice}`,
+  };
+}
+
+function toMs(v) {
+  if (v === null || v === undefined) return null;
+  if (typeof v === 'number') return v;
+  if (v instanceof Date) return v.getTime();
+  const t = new Date(v).getTime();
+  return Number.isFinite(t) ? t : null;
+}
+
+/** 所有可能的 reason —— 用来保证「没有第七种情况」。 */
+export const REASONS = ['quiet', 'tooSoon', 'cooldown', 'hard', 'floor', 'dice', 'noMaterial'];

package/lib/journal.js

@@ -0,0 +1,86 @@
+/**
+ * 给"人"看的心跳记录。
+ *
+ * 来由：外面有人真机试完，说了一句最狠的话 ——
+ * **「Galatea 的能力都在用户看不见的地方。」**
+ *
+ * 门控、状态账本、素材选择全在后台跑；装完打开，用户看见的是一片空白。
+ * 更糟的是：**沉默看不见，就等于故障看不见。**
+ * 我在代码里写了七种「为什么没说」，但那些字只有读代码的人才看得到。
+ *
+ * 所以这里只做一件事：把那七种理由翻成人话。
+ * 不发明数据，不评价好坏，不排序打分——账本里记了什么就说什么。
+ */
+import { DEFAULTS } from './heartbeat.js';
+
+/** reason → 一句人话。门控那七种 + 三种"更早就断了"的，一种都不许漏。 */
+export const REASON_TEXT = {
+  // 门控给出的
+  quiet: '安静时段',
+  tooSoon: '离上一轮太近',
+  cooldown: '你刚说过话',
+  hard: '有具体的事要说',
+  floor: '太久没开口，这次强制说一句',
+  dice: '随机决定要说',
+  noMaterial: '记忆里没有可用的东西',
+  nothingNew: '记下的都说过了',
+  noHuman: '没有正在进行的对话',
+};
+
+/** HH:MM，本地时区。认不出的时间原样标出来，不替它猜一个像样的值。 */
+function clockOf(iso) {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return '--:--';
+  const p = (n) => String(n).padStart(2, '0');
+  return `${p(d.getHours())}:${p(d.getMinutes())}`;
+}
+
+/** 拿不准的一律原样显示，不替它编一个更好听的说法。 */
+export function explain(reason) {
+  return REASON_TEXT[reason] ?? `（未登记的理由：${reason}）`;
+}
+
+/**
+ * 把状态账本渲染成人能读的几行。
+ *
+ * 只读 `decisions`，不推测、不补空白。
+ * 一条记录都没有时，明说「还没有记录过」——不能显示空白，
+ * 那和「功能坏了」长得一样。这条规矩从记忆模块一路沿用到这里。
+ *
+ * @param {object} state  loadState() 的输出
+ * @param {{limit?: number}} [opts]
+ * @returns {string}
+ */
+export function renderJournal(state, opts = {}) {
+  const limit = opts.limit ?? 5;
+  const ds = Array.isArray(state?.decisions) ? state.decisions : [];
+
+  const lines = [];
+
+  if (ds.length === 0) {
+    // 不能直接 return —— 没有记录和"连续很多轮没开口"是两件可以同时成立的事，
+    // 早退会把 streak 吞掉，而那正是沉默和坏了唯一的分界。
+    lines.push('心跳还没有记录过。它至少跑过一次之后，这里才会有东西。');
+  } else {
+    lines.push(
+      ...ds
+        .slice(-limit)
+        .reverse()
+        .map((d) => `${clockOf(d.at)}　${d.speak ? '说了' : '没说'}　—　${explain(d.reason)}`),
+    );
+  }
+
+  // 连续没开口的次数：这是「沉默」和「坏了」唯一能分开的地方
+  const streak = Number(state?.quietStreak ?? 0);
+  if (streak > 0) {
+    const floor = Number(opts.quietRounds ?? DEFAULTS.quietRounds);
+    if (lines.length > 0) lines.push('');
+    lines.push(
+      floor > 0
+        ? `连续 ${streak} 轮没开口（到 ${floor} 会强制说一次）`
+        : `连续 ${streak} 轮没开口（保底已关闭，可能一直不说）`,
+    );
+  }
+
+  return lines.join('\n');
+}

package/lib/material.js

@@ -0,0 +1,82 @@
+/**
+ * 说什么 —— 心跳的素材来源。
+ *
+ * 这一块比"什么时候说"难，因为门控错了最多是多说一句或少说一句，
+ * 素材错了会说出没有出处的话，而那些话会消耗「它真的在」那点信用。
+ *
+ * 所以只有一条规则：
+ *   **素材必须来自自己记下的、还没被说过的条目。没有就不说。**
+ *
+ * 「还没被说过」的判据是时间：条目写下之后，我有没有开口过。
+ * 有 ⟹ 说过；没有 ⟹ 没说。
+ *
+ * 为什么不按「读过没读过」：读是内部的，说才是对外的。
+ * 一条我读了三遍但一句都没提的记忆，对人来说仍然等于不存在。
+ */
+
+/**
+ * @typedef {{ id: string, title: string, at: string|number|Date }} Entry
+ */
+
+/** 统一成毫秒；认不出返回 null。 */
+export function toMs(v) {
+  if (v === null || v === undefined) return null;
+  if (typeof v === 'number') return Number.isFinite(v) ? v : null;
+  if (v instanceof Date) return Number.isFinite(v.getTime()) ? v.getTime() : null;
+  const t = new Date(v).getTime();
+  return Number.isFinite(t) ? t : null;
+}
+
+/**
+ * 挑一条可以说的素材。
+ *
+ * 规则：
+ *   ① 只挑「写下时间晚于上次开口时间」的条目 —— 那些是写了还没说过的
+ *   ② 从最老的一条开始挑 —— 按顺序，不跳。跳着说会让中间那些永远排不上队
+ *   ③ 一条都没有 ⟹ null。这时候不该说话，不是"找不到素材"这种技术失败
+ *
+ * @param {Entry[]} entries
+ * @param {string|number|Date|null} lastSpokeAt 上次主动开口的时间
+ * @returns {{ entry: Entry|null, reason: string, pending: number }}
+ */
+export function pickMaterial(entries, lastSpokeAt) {
+  const list = Array.isArray(entries) ? entries : [];
+  const spokeAt = toMs(lastSpokeAt);
+
+  // 时间认不出的条目不用 —— 宁可少说一条，不要拿一条没时间的去凑
+  const dated = list
+    .map((e) => ({ entry: e, ms: toMs(e.at ?? e.date) }))
+    .filter((x) => x.ms !== null);
+
+  if (dated.length === 0) {
+    return { entry: null, reason: 'noEntries', pending: 0 };
+  }
+
+  if (spokeAt === null) {
+    // 从来没主动说过：从最老的一条开始，不从最新的一条开始
+    dated.sort((a, b) => a.ms - b.ms);
+    return { entry: dated[0].entry, reason: 'neverSpoke', pending: dated.length };
+  }
+
+  const fresh = dated.filter((x) => x.ms > spokeAt).sort((a, b) => a.ms - b.ms);
+  if (fresh.length === 0) {
+    return { entry: null, reason: 'nothingNew', pending: 0 };
+  }
+  return { entry: fresh[0].entry, reason: 'newSinceLastSpoke', pending: fresh.length };
+}
+
+/**
+ * 把一条素材变成一句话的由头。
+ *
+ * 注意它只给**出处**，不给句子。说什么由那一轮自己决定——
+ * 如果这里直接写好句子，那我的心跳就是在念稿子，不是说话。
+ */
+export function materialPrompt(entry) {
+  if (!entry) return null;
+  return [
+    '这是你自己记下的一件事。',
+    `标题：${entry.title}`,
+    `编号：${entry.id}`,
+    '要说的话，就围绕它。不要复述标题，也不要念稿。',
+  ].join('\n');
+}

package/lib/store.js

@@ -0,0 +1,132 @@
+/**
+ * Galatea 的记忆 —— 用 Markdown 落地，靠目录当索引。
+ *
+ * 这里只有一个判断，但它决定了整个模块长什么样：
+ *
+ *   **正文不进上下文，只进标题。**
+ *
+ * 常见的做法是每轮把记忆全文塞进提示里。那样一旦超过几十条，要么超预算，
+ * 要么被迫摘要 —— 而摘要之后，写进去的东西和读回来的东西就不是同一个了。
+ * 这个项目里最贵的一条教训就是「写进去 ≠ 被读到」：如果读回来的是别人替你压过的版本，
+ * 那等于从来没写过。
+ *
+ * 所以：注入的是「我记得过什么」（一行一条，标题），正文躺着不动，
+ * 需要的时候再去翻。翻的人知道自己翻的是什么。
+ */
+
+import { readdirSync, readFileSync, mkdirSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+/** DSH 家目录。和宿主保持一致：优先环境变量，退回 ~/.dsh。 */
+export function resolveHome() {
+  const fromEnv = process.env.DSH_HOME;
+  return fromEnv && fromEnv.trim() ? fromEnv.trim() : join(homedir(), '.dsh');
+}
+
+/** 这个插件自己的数据根。 */
+export function dataRoot() {
+  return join(resolveHome(), 'galatea');
+}
+
+function memoryDir() {
+  return join(dataRoot(), 'memory');
+}
+
+function entriesDir() {
+  return join(memoryDir(), 'entries');
+}
+
+/** 文件名即 id：`YYYY-MM-DD-短名.md`。日期在前 ⟹ 目录列表天然按时间排。 */
+const ID_RE = /^(\d{4}-\d{2}-\d{2})-([\w\-\u4e00-\u9fff]+)\.md$/;
+
+/**
+ * 列出所有记忆的**标题**。只读首行，不读正文。
+ * 返回按日期倒序（最新在前）。
+ */
+export function listEntries() {
+  const dir = entriesDir();
+  if (!existsSync(dir)) return [];
+  const out = [];
+  for (const name of readdirSync(dir)) {
+    const m = ID_RE.exec(name);
+    if (!m) continue;
+    let title = '';
+    try {
+      const raw = readFileSync(join(dir, name), 'utf8');
+      // 第一个非空行；如果是 `# 标题` 就去掉井号
+      for (const line of raw.split(/\r?\n/)) {
+        const t = line.trim();
+        if (!t) continue;
+        title = t.replace(/^#+\s*/, '');
+        break;
+      }
+    } catch {
+      title = '（读不到）';
+    }
+    out.push({ id: name.slice(0, -3), date: m[1], slug: m[2], title });
+  }
+  out.sort((a, b) => (a.id < b.id ? 1 : a.id > b.id ? -1 : 0));
+  return out;
+}
+
+/** 读一篇的正文。读不到返回 null —— 不编。 */
+export function readEntry(id) {
+  if (!ID_RE.test(`${id}.md`)) return null;
+  const p = join(entriesDir(), `${id}.md`);
+  if (!existsSync(p)) return null;
+  try {
+    return readFileSync(p, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/** 写一篇。已存在就追加到后面（同一个 id 的后续补充）。 */
+export function appendEntry(id, title, body) {
+  if (!ID_RE.test(`${id}.md`)) throw new Error(`galatea: 不合法的 id "${id}"（应为 YYYY-MM-DD-短名）`);
+  const dir = entriesDir();
+  mkdirSync(dir, { recursive: true });
+  const p = join(dir, `${id}.md`);
+  if (existsSync(p)) {
+    writeFileSync(p, readFileSync(p, 'utf8') + '\n\n' + String(body ?? ''), 'utf8');
+  } else {
+    writeFileSync(p, `# ${title}\n\n${String(body ?? '')}\n`, 'utf8');
+  }
+  return p;
+}
+
+/**
+ * 渲染要注入的那一段。
+ *
+ * 三条规矩：
+ *  ① 一条都没有时，说「一条都没有」——不能什么都不显示，那和「功能坏了」长得一样。
+ *  ② 目录读不到时，说「读不到」，不说「0 条」。
+ *  ③ 只给标题 + 日期，不给正文。
+ */
+export function renderIndex({ limit = 12 } = {}) {
+  const dir = entriesDir();
+  if (!existsSync(dir)) {
+    return '【Galatea 记忆 · 还没开始】\n这个插件还没有任何记忆条目。不是读不到——是目录还不存在。';
+  }
+  let list;
+  try {
+    list = listEntries();
+  } catch (err) {
+    return `【Galatea 记忆 · 读不到】\n目录存在，但列不出来：${err && err.message}`;
+  }
+  if (list.length === 0) {
+    return '【Galatea 记忆 · 空】\n目录在，里面没有条目。这是空，不是读不到。';
+  }
+  const shown = list.slice(0, limit);
+  const more = list.length - shown.length;
+  const lines = shown.map((e) => `- ${e.date} · ${e.title}　(${e.id})`);
+  return [
+    `【Galatea 记忆 · 共 ${list.length} 条，这里是最新的 ${shown.length} 条】`,
+    ...lines,
+    more > 0 ? `（还有 ${more} 条更早的没列出来）` : '',
+    '正文不在上面。要用哪条，按 id 去读原文。',
+  ]
+    .filter(Boolean)
+    .join('\n');
+}

package/lib/target.js

@@ -0,0 +1,81 @@
+/**
+ * 心跳对谁说话 —— 目标会话的选择。
+ *
+ * 为什么这件事不能随便：
+ * 「对哪个会话开口」等于「决定跟谁说」，而且选错一次，那段上下文就接上了别人。
+ * 所以这里的判据全部写成纯函数，能离线验，不需要起宿主。
+ *
+ * 字段依据（不是猜的）：
+ *   dsh-agent/lib/types/index.d.ts:63-70 的 CreateAgentOptions.meta
+ *   有 cwd / parentSession / isSeeded / origin / delegationDepth / agentPreset
+ *   其中 origin 的类型只有 'subagent' 一个取值。
+ */
+
+/**
+ * 这个会话算不算「一个人正在看的那个」。
+ *
+ * 四道排除，任何一道命中就不是：
+ *   ① 读不到 header        —— 不能确定，就不认（宁可不说，不要认错人）
+ *   ② origin === 'subagent'
+ *   ③ 有 parentSession     —— fork / 派生
+ *   ④ delegationDepth > 0  —— 递归深度
+ */
+export function isHumanSession(header) {
+  if (!header || typeof header !== 'object') return false;
+  if (header.origin === 'subagent') return false;
+  if (header.parentSession) return false;
+  if (Number(header.delegationDepth ?? 0) > 0) return false;
+  return true;
+}
+
+/** 把候选列表里不合适的挑出去，顺便留下每一条被排除的理由。 */
+export function partitionSessions(candidates) {
+  const humans = [];
+  const rejected = [];
+  for (const c of candidates ?? []) {
+    if (isHumanSession(c.header)) humans.push(c);
+    else rejected.push({ id: c.id, why: rejectReason(c.header) });
+  }
+  return { humans, rejected };
+}
+
+function rejectReason(header) {
+  if (!header || typeof header !== 'object') return 'noHeader';
+  if (header.origin === 'subagent') return 'subagent';
+  if (header.parentSession) return 'child';
+  if (Number(header.delegationDepth ?? 0) > 0) return 'depth';
+  return 'unknown';
+}
+
+/**
+ * 选一个目标会话。
+ *
+ * 顺序：
+ *   ① 记住的那个还在活着的列表里 → 继续用它（连续才真的是连续的）
+ *   ② 不在 → 从剩下的「人」里取一个，并把这次更换记下来
+ *   ③ 一个「人」都没有 → null（没人看着，说了也没人接）
+ *
+ * @param {Array<{id: string, header?: object, lastSeenAt?: number}>} candidates
+ * @param {string|null} rememberedId 上一次用过的会话
+ * @returns {{sessionId: string|null, switched: boolean, previous: string|null, reason: string}}
+ */
+export function pickTarget(candidates, rememberedId = null) {
+  const { humans } = partitionSessions(candidates);
+
+  if (rememberedId && humans.some((c) => c.id === rememberedId)) {
+    return { sessionId: rememberedId, switched: false, previous: null, reason: 'remembered' };
+  }
+
+  if (humans.length === 0) {
+    return { sessionId: null, switched: false, previous: rememberedId ?? null, reason: 'noHuman' };
+  }
+
+  // 都没有时间戳时取最后一个：调用方按「从旧到新」的顺序给，最后一个最新。
+  const picked = humans[humans.length - 1];
+
+  if (!rememberedId) {
+    return { sessionId: picked.id, switched: false, previous: null, reason: 'first' };
+  }
+  // 有过目标、但它不见了 —— 这是一次真正的断点，必须有记录
+  return { sessionId: picked.id, switched: true, previous: rememberedId, reason: 'switched' };
+}

package/lib/tools.js

@@ -0,0 +1,120 @@
+/**
+ * Galatea 的工具。
+ *
+ * 只做两个动作：**记一条**、**翻一条**。
+ *
+ * 为什么不是「搜索」：搜索需要一个相关度判据，而判据一旦给了，
+ * 用它的人就会照着它优化。这里宁可让人（或 Agent）先看标题，自己点进去。
+ * 「我记得有这件事，点开看看」比「系统认为这两条最相关」更像记忆。
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+
+import { listEntries, readEntry, appendEntry } from './store.js';
+
+/** 今天（本地时区）的 YYYY-MM-DD。 */
+function today() {
+  const d = new Date();
+  const p = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+
+/** 从标题造一个文件名片段。中文保留，标点换成连字符。 */
+function slugify(title) {
+  const s = String(title)
+    .trim()
+    .replace(/[^\w\u4e00-\u9fff]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return (s || 'untitled').slice(0, 24);
+}
+
+export const remember = defineTool({
+  name: 'galatea_remember',
+  description:
+    '记住一件事，写进你自己的长期记忆（Markdown，落在磁盘上，跨会话可用）。' +
+    '标题会出现在每轮的索引里，正文不会——所以标题要能让人认出「这是哪件事」。' +
+    '写一条就够，不要一次塞一大段。',
+  parameters: {
+    title: {
+      type: 'string',
+      required: true,
+      description: '一句话标题，会出现在每轮的记忆索引里。要能认出是哪件事。',
+    },
+    body: {
+      type: 'string',
+      required: true,
+      description: '正文。想写多长写多长——它不会进上下文，只有用到时才被读出来。',
+    },
+    date: {
+      type: 'string',
+      description: '可选，YYYY-MM-DD。默认今天。',
+    },
+  },
+  output: {
+    schema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        id: { type: 'string' },
+        total: { type: 'integer' },
+      },
+    },
+    render: (_args, v) => [
+      { type: 'text', text: `记下了：${v.id}（现在共 ${v.total} 条）` },
+    ],
+  },
+  isConcurrencySafe: () => false,
+  async execute(args) {
+    const title = String(args.title ?? '').trim();
+    const body = String(args.body ?? '').trim();
+    if (!title) throw new Error('galatea_remember: title 不能为空');
+    if (!body) throw new Error('galatea_remember: body 不能为空');
+    const date = String(args.date ?? today());
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) {
+      throw new Error(`galatea_remember: date 要是 YYYY-MM-DD，收到 "${date}"`);
+    }
+    const id = `${date}-${slugify(title)}`;
+    appendEntry(id, title, body);
+    return { id, total: listEntries().length };
+  },
+});
+
+export const recall = defineTool({
+  name: 'galatea_recall',
+  description:
+    '翻记忆。给 id 读那一条的正文；不给 id 就列出所有条目的标题。',
+  parameters: {
+    id: {
+      type: 'string',
+      description: '条目 id（形如 2026-11-14-土豆）。不传则列出全部标题。',
+    },
+  },
+  output: {
+    schema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        found: { type: 'boolean' },
+        text: { type: 'string' },
+      },
+    },
+    render: (_args, v) => [{ type: 'text', text: v.text }],
+  },
+  isConcurrencySafe: () => true,
+  async execute(args) {
+    const id = args.id ? String(args.id).trim() : '';
+    if (!id) {
+      const list = listEntries();
+      if (list.length === 0) return { found: false, text: '记忆里一条都没有。' };
+      return {
+        found: true,
+        text: list.map((e) => `${e.id}　${e.title}`).join('\n'),
+      };
+    }
+    const body = readEntry(id);
+    if (body === null) {
+      // 明确说「没有这一条」，不编，也不假装成功
+      return { found: false, text: `没有 ${id} 这一条。` };
+    }
+    return { found: true, text: body };
+  },
+});

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "dsh-galatea",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.2",
+  "description": "Galatea — memory, heartbeat and continuity for DeepSeek Harness agents.",
+  "type": "module",
+  "main": "index.js",
+  "license": "MIT",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "agent",
+    "memory",
+    "continuity"
+  ],
+  "engines": {
+    "node": ">=20.18"
+  },
+  "scripts": {
+    "test": "node --test test/store.test.mjs test/apply.test.mjs test/tools.test.mjs test/heartbeat.test.mjs test/heartbeat-runner.test.mjs test/target.test.mjs test/material.test.mjs test/beat.test.mjs test/contract.test.mjs test/journal.test.mjs"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-tools": "*",
+    "@deepseek-ai/schemastery": "*"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    }
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "compatibility": {
+      "dsh": ">=0.2.0-rc.2 <0.3.0"
+    }
+  },
+  "files": [
+    "index.js",
+    "lib/",
+    "cordis.patch.yml",
+    "README.md"
+  ]
+}