libero-mcp 0.1.0 → 0.2.1

package/README.md

@@ -1,21 +1,57 @@
-# libero 2.0
+# libero
 
-AI 辅助人类精力管理：观察实绩 → 发现问题 → 对齐方案 → AI 辅助达成，PDCA 闭环。
+AI 辅助的精力管理教练：观察实绩 → 发现问题 → 对齐方案 → AI 辅助达成。
 
-2.0 = 一组 Skills（脑）+ 一层 MCP 工具（手）+ 一个数据后端（记忆），骑 Openclaw，本地优先。
+> 2.0 = 一组 Skills（脑）+ 一层 MCP 工具（手）+ 一个数据后端（记忆），骑 Hermes / OpenClaw，本地优先。
 
 ## 快速开始
 
-> MV-0 排雷中，runbook 待补充。
+```bash
+npm i -g libero-mcp@latest
+```
 
-## 仓库结构
+装完后，在你的 agent 入口（Hermes / OpenClaw）里直接说一句：
 
-- `skills/` — 脑（prompt + markdown）
-- `mcp/` — 手（确定性 MCP 工具）
-- `data/` — 本地 DB schema + migrations
-- `eval/` — Skill 评估与压力测试
-- `docs/` — spec / plan / 决策记录
+> 帮我记一下从现在开始写代码
 
-## 协作宪法
+libero 会自动建库、建用户、开始计时。下次想看时间花哪儿了，就问：
 
-见 [AGENTS.md](AGENTS.md)
+> 这周时间都花哪儿了？帮我复盘一下
+
+## 能说什么
+
+libero 是个教练，不是表格工具——所有功能都通过自然语言触发：
+
+| 想做的事 | 这样说 |
+|---|---|
+| 开始一段专注 | "开始计时写代码" / "开个 25 分钟番茄钟读书" |
+| 停下来 | "停一下" / "看看今天计了多久" |
+| 安排日程 | "明天 9 点到 11 点写报告" / "下周二下午开会" |
+| 看时间分布 | "这周时间都花哪儿了" / "看看今天的四象限" |
+| 复盘 | "复盘一下这周" / "帮我分析最近的时间使用" |
+| 拆任务 | "这个任务太大，帮我拆一下" |
+| 安排提醒 | "明天 8 点提醒我打卡" |
+
+## 数据存在哪
+
+默认在 `~/.libero/libero.db`（SQLite）。想换位置：
+
+```bash
+DB_PATH=/your/path.db libero-mcp
+```
+
+## 升级
+
+```bash
+npm update -g libero-mcp
+```
+
+DB schema 升级在启动时自动跑，不用手工干预。
+
+## 给开发者
+
+- 协作宪法：[AGENTS.md](AGENTS.md)
+- 部署细节 / 故障排查：[docs/operations/deploy-to-hermes.md](docs/operations/deploy-to-hermes.md)
+- MCP 工具清单（41 个）：见同上文档「仅排查时参考」段
+- Skills 源在 `skills/`（libero-coach / libero-record / libero-onboarding / libero-decompose）
+- 仓库结构 / spec / 决策记录：见 `docs/`

package/data/migrations/007_reminders.sql

@@ -0,0 +1,17 @@
+CREATE TABLE IF NOT EXISTS reminders (
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL,
+  timeblock_id TEXT,
+  content TEXT NOT NULL,
+  remind_at TEXT NOT NULL,
+  channel TEXT NOT NULL DEFAULT 'session',
+  status TEXT NOT NULL DEFAULT 'pending',
+  attempts INTEGER NOT NULL DEFAULT 0,
+  sent_at TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  deleted_at TEXT,
+  FOREIGN KEY (user_id) REFERENCES user_profile(id)
+);
+CREATE INDEX IF NOT EXISTS idx_reminders_due
+  ON reminders (status, remind_at) WHERE deleted_at IS NULL;

package/data/migrations/008_timer_target_ms.sql

@@ -0,0 +1,5 @@
+-- 008_timer_target_ms: add focus target duration to timer_sessions
+-- S26: pomodoro v1 — target_ms tracks the goal duration (e.g. 25min = 1500000ms)
+-- NULL = normal timer (backward compatible)
+
+ALTER TABLE timer_sessions ADD COLUMN target_ms INTEGER;

package/data/migrations/009_tasks.sql

@@ -0,0 +1,22 @@
+-- 009_tasks: 任务拆解（P2-3, S29 §3.1）
+-- coaching 制品：低摩擦冷启动 + ≤25min 子任务方案
+
+CREATE TABLE IF NOT EXISTS tasks (
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL,
+  parent_id TEXT,                       -- NULL=根任务, 否则子任务(自引用)
+  title TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'draft', -- draft/aligned/executing/done/abandoned
+  est_minutes INTEGER,                  -- 预估(冷启动不限, 其余≤25min)
+  category_id TEXT,
+  linked_timeblock_id TEXT,             -- 排/执行时关联 time_block
+  order_index INTEGER DEFAULT 0,        -- 同级顺序
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  deleted_at TEXT,
+  FOREIGN KEY (user_id) REFERENCES user_profile(id),
+  FOREIGN KEY (parent_id) REFERENCES tasks(id),
+  FOREIGN KEY (category_id) REFERENCES categories(id),
+  FOREIGN KEY (linked_timeblock_id) REFERENCES time_blocks(id)
+);
+CREATE INDEX IF NOT EXISTS idx_tasks_user_parent ON tasks (user_id, parent_id);

package/data/migrations/010_timer_task_id.sql

@@ -0,0 +1,4 @@
+-- 010_timer_task_id: timer_sessions 加 task_id（S29 §3.2）
+-- 子任务开工走计时器时关联 task_id；计时结束 → 凭 task_id 触发闭环反馈
+
+ALTER TABLE timer_sessions ADD COLUMN task_id TEXT REFERENCES tasks(id);

package/dist/data/db.js

@@ -1,6 +1,7 @@
 import Database from "better-sqlite3";
-import { readFileSync, readdirSync } from "node:fs";
-import { join } from "node:path";
+import { mkdirSync, readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 let instance = null;
 function runMigrations(db) {
@@ -33,6 +34,9 @@ export function initDb(dbPath) {
         instance.close();
         instance = null;
     }
+    // 父目录不存在时自动创建（recursive），避免 SQLITE_CANTOPEN
+    // 2026-07-17：hermes 装机后默认 cwd 无 ./data/ → 用户看到"缺少数据库目录"
+    mkdirSync(dirname(dbPath), { recursive: true });
     const db = new Database(dbPath);
     db.pragma("journal_mode = WAL");
     db.pragma("foreign_keys = ON");
@@ -54,7 +58,8 @@ export function closeDb() {
 }
 const entry = process.argv[1];
 if (entry && fileURLToPath(import.meta.url) === entry) {
-    const dbPath = process.env.DB_PATH ?? join(import.meta.dirname, "libero.db");
+    // CLI 模式：默认 ~/.libero/libero.db（与 server.ts 保持一致）
+    const dbPath = process.env.DB_PATH ?? join(homedir(), ".libero", "libero.db");
     initDb(dbPath);
     console.log(`DB initialized at ${dbPath}`);
     closeDb();

package/dist/data/migrations/007_reminders.sql

@@ -0,0 +1,17 @@
+CREATE TABLE IF NOT EXISTS reminders (
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL,
+  timeblock_id TEXT,
+  content TEXT NOT NULL,
+  remind_at TEXT NOT NULL,
+  channel TEXT NOT NULL DEFAULT 'session',
+  status TEXT NOT NULL DEFAULT 'pending',
+  attempts INTEGER NOT NULL DEFAULT 0,
+  sent_at TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  deleted_at TEXT,
+  FOREIGN KEY (user_id) REFERENCES user_profile(id)
+);
+CREATE INDEX IF NOT EXISTS idx_reminders_due
+  ON reminders (status, remind_at) WHERE deleted_at IS NULL;

package/dist/data/migrations/008_timer_target_ms.sql

@@ -0,0 +1,5 @@
+-- 008_timer_target_ms: add focus target duration to timer_sessions
+-- S26: pomodoro v1 — target_ms tracks the goal duration (e.g. 25min = 1500000ms)
+-- NULL = normal timer (backward compatible)
+
+ALTER TABLE timer_sessions ADD COLUMN target_ms INTEGER;

package/dist/data/migrations/009_tasks.sql

@@ -0,0 +1,22 @@
+-- 009_tasks: 任务拆解（P2-3, S29 §3.1）
+-- coaching 制品：低摩擦冷启动 + ≤25min 子任务方案
+
+CREATE TABLE IF NOT EXISTS tasks (
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL,
+  parent_id TEXT,                       -- NULL=根任务, 否则子任务(自引用)
+  title TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'draft', -- draft/aligned/executing/done/abandoned
+  est_minutes INTEGER,                  -- 预估(冷启动不限, 其余≤25min)
+  category_id TEXT,
+  linked_timeblock_id TEXT,             -- 排/执行时关联 time_block
+  order_index INTEGER DEFAULT 0,        -- 同级顺序
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  deleted_at TEXT,
+  FOREIGN KEY (user_id) REFERENCES user_profile(id),
+  FOREIGN KEY (parent_id) REFERENCES tasks(id),
+  FOREIGN KEY (category_id) REFERENCES categories(id),
+  FOREIGN KEY (linked_timeblock_id) REFERENCES time_blocks(id)
+);
+CREATE INDEX IF NOT EXISTS idx_tasks_user_parent ON tasks (user_id, parent_id);

package/dist/data/migrations/010_timer_task_id.sql

@@ -0,0 +1,4 @@
+-- 010_timer_task_id: timer_sessions 加 task_id（S29 §3.2）
+-- 子任务开工走计时器时关联 task_id；计时结束 → 凭 task_id 触发闭环反馈
+
+ALTER TABLE timer_sessions ADD COLUMN task_id TEXT REFERENCES tasks(id);

package/dist/mcp/server-core.js

@@ -1,12 +1,15 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { SqliteCategoryRepo, SqliteTimeBlockRepo, SqliteStatsRepo, SqliteTimerRepo, SqliteProfileRepo, } from "./src/repo/sqlite.js";
+import { SqliteCategoryRepo, SqliteTimeBlockRepo, SqliteStatsRepo, SqliteTimerRepo, SqliteProfileRepo, SqliteReminderRepo, } from "./src/repo/sqlite.js";
 import { createCategoryTools } from "./src/categories/index.js";
 import { createTimeBlockTools } from "./src/timeblock/index.js";
 import { createStatsTools } from "./src/stats/index.js";
 import { createMatrixTools } from "./src/matrix/index.js";
 import { createTimerTools } from "./src/timer/index.js";
 import { createProfileTools } from "./src/profile/index.js";
+import { createReminderTools } from "./src/reminder/index.js";
+import { createSchedulerTools } from "./src/scheduler/index.js";
+import { createTaskTools } from "./src/task/index.js";
 import { nowLocal, formatTime, parseTime } from "./src/clock/index.js";
 /** Wrap any tool result as MCP text content (JSON). Void results become {ok:true}. */
 function asContent(result) {
@@ -31,13 +34,17 @@ export function buildServer(db) {
     const statsRepo = new SqliteStatsRepo(db);
     const timerRepo = new SqliteTimerRepo(db);
     const profileRepo = new SqliteProfileRepo(db);
+    const reminderRepo = new SqliteReminderRepo(db);
     // ── inject tool factories ──
     const categories = createCategoryTools(categoryRepo);
     const tb = createTimeBlockTools(timeblockRepo);
     const stats = createStatsTools(statsRepo);
     const matrix = createMatrixTools(statsRepo); // matrix reuses StatsRepo
-    const timer = createTimerTools(timerRepo);
+    const timer = createTimerTools(timerRepo, timeblockRepo);
     const profile = createProfileTools(profileRepo);
+    const reminder = createReminderTools(reminderRepo);
+    const scheduler = createSchedulerTools(timeblockRepo, reminderRepo, categoryRepo);
+    const task = createTaskTools(db);
     const server = new McpServer({ name: "libero-mcp", version: "0.1.0" });
     // ============================================================
     // categories (2 tools)
@@ -53,13 +60,39 @@ export function buildServer(db) {
             user_id: z.string().min(1),
             event: z.string().min(1),
             categoryId: z.string().optional(),
+            task_id: z.string().optional(),
         },
-    }, async ({ user_id, event, categoryId }) => asContent(await timer.start(user_id, event, categoryId)));
+    }, async ({ user_id, event, categoryId, task_id }) => asContent(await timer.start(user_id, event, categoryId, task_id)));
     server.registerTool("timer.pause", { description: "暂停当前计时", inputSchema: { user_id: z.string().min(1) } }, async ({ user_id }) => asContent(await timer.pause(user_id)));
     server.registerTool("timer.resume", { description: "恢复已暂停的计时", inputSchema: { user_id: z.string().min(1) } }, async ({ user_id }) => asContent(await timer.resume(user_id)));
-    server.registerTool("timer.stop", { description: "停止计时并返回记录", inputSchema: { user_id: z.string().min(1) } }, async ({ user_id }) => asContent(await timer.stop(user_id)));
+    server.registerTool("timer.stop", {
+        description: "停止计时并返回记录（传 rating 时自动落盘 timeblock）",
+        inputSchema: {
+            user_id: z.string().min(1),
+            rating: z.number().min(1).max(5).optional(),
+            rating_reason: z.string().optional(),
+        },
+    }, async ({ user_id, rating, rating_reason }) => asContent(await timer.stop(user_id, { rating, rating_reason })));
     server.registerTool("timer.status", { description: "查询某用户当前计时状态", inputSchema: { user_id: z.string().min(1) } }, async ({ user_id }) => asContent(await timer.status(user_id)));
     server.registerTool("timer.elapsed", { description: "查询当前计时已过毫秒数", inputSchema: { user_id: z.string().min(1) } }, async ({ user_id }) => asContent(await timer.elapsed(user_id)));
+    server.registerTool("timer.statusAll", { description: "查询所有用户的当前计时状态（调试/兜底用）", inputSchema: {} }, async () => asContent(await timer.statusAll()));
+    // ── S26: pomodoro v1 tools ──
+    server.registerTool("timer.startFocus", {
+        description: "开始一个专注计时（番茄钟），带目标时长",
+        inputSchema: {
+            user_id: z.string().min(1),
+            event: z.string().min(1),
+            focusMin: z.number().positive().optional(),
+            categoryId: z.string().optional(),
+            task_id: z.string().optional(),
+        },
+    }, async ({ user_id, event, focusMin, categoryId, task_id }) => asContent(await timer.startFocus(user_id, event, focusMin, categoryId, task_id)));
+    server.registerTool("timer.remaining", {
+        description: "查询专注计时剩余时间（负数=超时）",
+        inputSchema: {
+            user_id: z.string().min(1),
+        },
+    }, async ({ user_id }) => asContent(await timer.remaining(user_id)));
     // ============================================================
     // timeblock (5 tools — single-object args)
     // ============================================================
@@ -178,5 +211,165 @@ export function buildServer(db) {
                 .optional(),
         },
     }, async (input) => asContent(await profile.upsert(input)));
+    // ============================================================
+    // reminder (6 tools — S11)
+    // ============================================================
+    server.registerTool("reminder.create", {
+        description: "创建一条提醒",
+        inputSchema: {
+            user_id: z.string().min(1),
+            content: z.string().min(1),
+            remind_at: z.string().min(1),
+            channel: z.string().optional(),
+            timeblock_id: z.string().optional(),
+        },
+    }, async (input) => asContent(await reminder.create(input)));
+    server.registerTool("reminder.getDue", {
+        description: "获取到期且待发送的提醒列表",
+        inputSchema: {
+            user_id: z.string().optional(),
+            until: z.string().optional(),
+        },
+    }, async (input) => asContent(await reminder.getDueReminders(input)));
+    server.registerTool("reminder.getNextDue", {
+        description: "获取下一条待发送提醒的时间",
+        inputSchema: {
+            user_id: z.string().optional(),
+        },
+    }, async (input) => asContent(await reminder.getNextDue(input)));
+    server.registerTool("reminder.getMissed", {
+        description: "获取过期但未送达的提醒（被动补发用）",
+        inputSchema: {
+            user_id: z.string().min(1),
+        },
+    }, async ({ user_id }) => asContent(await reminder.getMissedReminders({ user_id })));
+    server.registerTool("reminder.markSent", {
+        description: "标记提醒为已发送（幂等）",
+        inputSchema: { id: z.string().min(1) },
+    }, async ({ id }) => asContent(await reminder.markSent(id)));
+    server.registerTool("reminder.cancel", {
+        description: "取消一条提醒（幂等）",
+        inputSchema: { id: z.string().min(1) },
+    }, async ({ id }) => asContent(await reminder.cancelReminder(id)));
+    // ============================================================
+    // scheduler (3 tools — S27, reuses timeblockRepo)
+    // ============================================================
+    server.registerTool("scheduler.createSchedule", {
+        description: "创建一个日程（planned 时间块）",
+        inputSchema: {
+            user_id: z.string().min(1),
+            title: z.string().min(1),
+            category_id: z.string().optional(),
+            start_time: z.string(),
+            end_time: z.string(),
+            duration_minutes: z.number().optional(),
+            rating: z.number().min(1).max(5).optional(),
+            rating_reason: z.string().optional(),
+            notes: z.string().optional(),
+        },
+    }, async (input) => asContent(await scheduler.createSchedule(input)));
+    server.registerTool("scheduler.listSchedules", {
+        description: "列出用户的日程（仅 planned 时间块）",
+        inputSchema: {
+            user_id: z.string().min(1),
+            from: z.string().optional(),
+            to: z.string().optional(),
+        },
+    }, async (input) => asContent(await scheduler.listSchedules(input)));
+    server.registerTool("scheduler.checkConflict", {
+        description: "检查时间段是否与已有日程冲突",
+        inputSchema: {
+            user_id: z.string().min(1),
+            start_time: z.string(),
+            end_time: z.string(),
+        },
+    }, async (input) => asContent(await scheduler.checkConflict(input)));
+    // ============================================================
+    // task (7 tools — S29 P2-3 + 事一 draft/commit, takes raw db)
+    // ============================================================
+    server.registerTool("task.create", {
+        description: "建单个独立任务（不挂任何 timeblock）。⚠️ 拆解请用 decompose.split，本工具一次只能建一个任务、不能建子任务。",
+        // S33 v3: 用 z.object().strict() 显式拒 parent_id（zod 默认 strip 不报错，
+        // 严格模式让多余键触发 safeParse 失败 → MCP 返回 isError）。
+        // 底层 createTask 仍保留 parent_id 能力（task.test.ts 单测不破）。
+        inputSchema: z
+            .object({
+            user_id: z.string().min(1),
+            title: z.string().min(1),
+            est_minutes: z.number().optional(),
+        })
+            .strict(),
+    }, async (input) => asContent(await task.createTask(input)));
+    server.registerTool("task.get", {
+        description: "按 id 获取任务（含递归子树）",
+        inputSchema: { id: z.string().min(1) },
+    }, async ({ id }) => asContent(await task.getTask(id)));
+    server.registerTool("task.list", {
+        description: "列出任务（parent_id=null 仅根；给定则该父的子；省略则全部）",
+        inputSchema: {
+            user_id: z.string().min(1),
+            parent_id: z.string().nullable().optional(),
+        },
+    }, async (input) => asContent(await task.listTasks(input)));
+    server.registerTool("task.update", {
+        description: "更新任务（title/est_minutes/status；状态机校验非法流转）",
+        inputSchema: {
+            id: z.string().min(1),
+            title: z.string().optional(),
+            est_minutes: z.number().optional(),
+            status: z.string().optional(),
+        },
+    }, async ({ id, ...rest }) => asContent(await task.updateTask(id, rest)));
+    server.registerTool("task.linkTimeblock", {
+        description: "把任务关联到一个时间块（子任务开工执行时）",
+        inputSchema: {
+            task_id: z.string().min(1),
+            block_id: z.string().min(1),
+        },
+    }, async ({ task_id, block_id }) => asContent(await task.linkTimeblock(task_id, block_id)));
+    server.registerTool("task.findPlan", {
+        description: "按事件名 exact-match 查拆解计划：返回根任务 + 第一块未完成子任务（record 开工时链 task_id，驱动闭环正反馈）",
+        inputSchema: {
+            user_id: z.string().min(1),
+            title: z.string().min(1),
+        },
+    }, async (input) => asContent(await task.findPlan(input)));
+    // S33 v3: task.draftPlan / task.commitPlan 从 MCP 工具列表移除（不再暴露给 mimo）。
+    // 拆解唯一入口 = decompose.split（见下方 decompose 段）。
+    // 底层 draftPlan/commitPlan 方法保留在 mcp/src/task/index.ts（被 decompose.split 复用 + task.test.ts 单测覆盖）。
+    // ============================================================
+    // decompose (1 tool — S33 v3：动作分离重构)
+    // decompose.split = 拆解唯一入口。状态机强制 draft→confirm→commit。
+    // 错误返回 isError content（不 throw），避 hermes 熔断器（v2 实证坑）。
+    // ============================================================
+    server.registerTool("decompose.split", {
+        description: "拆解 timeblock 为结构化子任务树（拆解唯一入口）。第一次调用出方案（不写库），第二次带 confirm_token 落地。状态机强制 draft→confirm→commit。⚠️ 拆子任务请用本工具，不要用 task.create。",
+        inputSchema: {
+            user_id: z.string().min(1),
+            timeblock_id: z.string().min(1),
+            children: z
+                .array(z.object({
+                title: z.string().min(1),
+                est_minutes: z.number().optional(),
+            }))
+                .min(1),
+            confirm_token: z.string().optional(),
+        },
+    }, async (input) => {
+        const result = await task.splitDecompose(input);
+        // DecomposeErrorResult → isError content（不 throw，避 hermes 熔断器）
+        if ("ok" in result && result.ok === false) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(result),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        return asContent(result);
+    });
     return server;
 }

package/dist/mcp/server.js

@@ -3,14 +3,18 @@
  * libero MCP server — stdio transport entry point (S10 §3.3).
  *
  * Usage:
- *   DB_PATH=/path/to/libero.db node mcp/server.ts
- *   DB_PATH=/path/to/libero.db npx tsx mcp/server.ts
- *   libero-mcp                    (if package.json bin + tsx is configured)
+ *   libero-mcp                            # 默认 DB 在 ~/.libero/libero.db
+ *   DB_PATH=/path/to/libero.db libero-mcp  # 自定义 DB 路径
  */
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { homedir } from "node:os";
+import { join } from "node:path";
 import { initDb, closeDb } from "../data/db.js";
 import { buildServer } from "./server-core.js";
-const DB_PATH = process.env.DB_PATH ?? "./data/libero.db";
+// 默认 DB 在用户家目录的 ~/.libero/libero.db（跨平台、不污染 cwd、符合 XDG-ish 约定）
+// 2026-07-17：原默认 "./data/libero.db" 是相对路径，hermes 启动 libero-mcp 时 cwd 无 ./data/
+// → better-sqlite3 抛 SQLITE_CANTOPEN → 用户看到"缺少数据库目录"。改绝对路径根治。
+const DB_PATH = process.env.DB_PATH ?? join(homedir(), ".libero", "libero.db");
 if (!DB_PATH) {
     console.error("FATAL: DB_PATH environment variable not set.");
     process.exit(1);

package/dist/mcp/src/clock/index.js

@@ -55,3 +55,19 @@ export function parseTime(isoString) {
 export function getLocalOffset() {
     return -new Date().getTimezoneOffset();
 }
+/** Convert any ISO string (UTC or with offset) to local timezone ISO string with offset suffix. */
+export function toLocalIso(isoString) {
+    const d = new Date(isoString);
+    if (isNaN(d.getTime())) {
+        throw new Error(`Invalid ISO time string: ${isoString}`);
+    }
+    const offset = getLocalOffset();
+    const sign = offset >= 0 ? "+" : "-";
+    const abs = Math.abs(offset);
+    const h = String(Math.floor(abs / 60)).padStart(2, "0");
+    const m = String(abs % 60).padStart(2, "0");
+    // Shift UTC timestamp by local offset to get "fake UTC" representing local time
+    const local = new Date(d.getTime() + offset * 60000);
+    const iso = local.toISOString().replace("Z", "");
+    return `${iso}${sign}${h}:${m}`;
+}

package/dist/mcp/src/reminder/hermes-channel.js

@@ -0,0 +1,40 @@
+/**
+ * HermesChannel — delivers reminders via `hermes send -t <target>` (T2).
+ *
+ * Uses CommandRunner abstraction (default: child_process.spawn, arrays only — no shell injection).
+ * DI `run` for testability; env HERMES_BIN overrides the binary path.
+ */
+import { spawn } from "node:child_process";
+/** Default runner: spawn `hermes` (HERMES_BIN override or PATH) with array args. */
+function defaultRunner(args) {
+    const bin = process.env.HERMES_BIN || "hermes";
+    return new Promise((resolve) => {
+        const child = spawn(bin, args, { stdio: "ignore" });
+        child.on("close", (code) => resolve(code ?? 1));
+        child.on("error", () => resolve(1));
+    });
+}
+export class HermesChannel {
+    defaultTarget;
+    run;
+    constructor(opts) {
+        this.defaultTarget = opts?.defaultTarget;
+        this.run = opts?.run ?? defaultRunner;
+    }
+    async send(r) {
+        // LLM 注入优先：只有 platform:address 格式（含 ':'）才算有效 direct target。
+        // 'session' / '' / 无 ':' → 视为无 direct target，走 defaultTarget 常量兜底。
+        const direct = r.channel && r.channel.includes(":") ? r.channel : null;
+        const target = direct ?? this.defaultTarget;
+        // §4.5 静默折叠：无送达目标 → warn + return false。
+        // 吞掉的原因：reminder 可能由无渠道上下文的途径创建（如 session fallback），
+        // 或 schema default='session' 且 LLM 未注入有效 channel。
+        if (!target) {
+            console.warn(`[HermesChannel] no target for reminder ${r.id}`);
+            return false;
+        }
+        const code = await this.run(["send", "-t", target, r.content]);
+        // 不抛——失败交 reminder-tick 的 releaseOrFail 重试/死信。
+        return code === 0;
+    }
+}

package/dist/mcp/src/reminder/index.js

@@ -0,0 +1,50 @@
+import { nowLocal } from "../clock/index.js";
+/**
+ * Validate and delegate reminder operations to the repository.
+ * ADR-0001: Dependency-injected — the caller provides the repo.
+ *
+ * @param repo  ReminderRepo implementation
+ * @param getNow  Clock injection for determinism; defaults to clock.nowLocal()
+ */
+export function createReminderTools(repo, getNow) {
+    const now = getNow ?? (() => nowLocal());
+    const create = async (input) => {
+        if (!input.content || input.content.trim() === "") {
+            throw new Error("提醒内容不能为空");
+        }
+        if (input.remind_at <= now()) {
+            throw new Error("提醒时间不能早于当前时间");
+        }
+        const userOk = await repo.userExists(input.user_id);
+        if (!userOk) {
+            throw new Error("用户不存在");
+        }
+        return repo.create(input);
+    };
+    const getDueReminders = async (input) => {
+        return repo.getDueReminders({
+            user_id: input.user_id,
+            until: input.until ?? now(),
+        });
+    };
+    const getNextDue = async (input) => {
+        return repo.getNextDue(input ?? {});
+    };
+    const getMissedReminders = async (input) => {
+        return repo.getMissedReminders({ ...input, now: now() });
+    };
+    const markSent = async (id) => {
+        return repo.markSent(id);
+    };
+    const cancelReminder = async (id) => {
+        return repo.cancelReminder(id);
+    };
+    return {
+        create,
+        getDueReminders,
+        getNextDue,
+        getMissedReminders,
+        markSent,
+        cancelReminder,
+    };
+}

package/dist/mcp/src/reminder/push-channel.js

@@ -0,0 +1,10 @@
+/**
+ * LogChannel — development fallback. Prints to console, always returns true.
+ * No real delivery; used when no credentials are configured.
+ */
+export class LogChannel {
+    async send(r) {
+        console.log(`[reminder] ${r.content} @ ${r.remind_at}`);
+        return true;
+    }
+}