libero-mcp 0.2.0 → 0.2.2

package/COLD_START.md

@@ -0,0 +1,31 @@
+# libero 冷启动（装机后、reload 前）
+
+> 给 Hermes / OpenClaw 等 host agent 读。装完包后**先把下面欢迎发给用户**，再 `/reload-mcp`。
+
+## 装机顺序
+
+1. `npm i -g libero-mcp@latest`
+2. 配置 `mcp_servers.libero.command: libero-mcp`（如需）
+3. **先介绍**：把「欢迎原文」原样发给用户（不要列工具名、不要问 user_id）
+4. **再刷新**：`/reload-mcp`（或等价）挂上工具
+
+## 欢迎原文（原样发给用户）
+
+```
+你好，我是 libero，帮你管时间和精力。
+
+常用这几件事，直接说就行：
+• 计时：「开始计时写代码」/「开个 25 分钟番茄钟」
+• 日程：「明天 9 点到 11 点写报告」
+• 拆任务：「这个太大了，帮我拆一下」
+• 看数据：「这周时间都花哪儿了」
+• 复盘：「帮我复盘一下这周」
+
+想先试哪一句？
+```
+
+## 硬规矩
+
+- **禁止问 user_id**（从会话上下文静默取；取不到用 `local:default`）
+- 不要提 MCP / 工具表 / DB / YAML
+- 用户选了例句 → 直接执行，不要重复整段介绍

package/README.md

@@ -1,21 +1,64 @@
-# 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
+```
 
-## 仓库结构
+### 给 host agent（Hermes / OpenClaw）的装机顺序
 
-- `skills/` — 脑（prompt + markdown）
-- `mcp/` — 手（确定性 MCP 工具）
-- `data/` — 本地 DB schema + migrations
-- `eval/` — Skill 评估与压力测试
-- `docs/` — spec / plan / 决策记录
+1. 装包并写好 MCP 配置  
+2. **先介绍**：把 [`COLD_START.md`](COLD_START.md) 里的欢迎原文发给用户（不要列工具、不要问 user_id）  
+3. **再刷新**：`/reload-mcp`（或等价）挂上工具  
 
-## 协作宪法
+用户装完后应直接看到欢迎与试用例句，而不是配置问卷。
 
-见 [AGENTS.md](AGENTS.md)
+### 用户怎么试
+
+装完后直接说：
+
+> 开始计时写代码
+
+或：
+
+> 这周时间都花哪儿了？帮我复盘一下
+
+## 能说什么
+
+| 想做的事 | 这样说 |
+|---|---|
+| 开始一段专注 | "开始计时写代码" / "开个 25 分钟番茄钟读书" |
+| 停下来 | "停一下" / "看看今天计了多久" |
+| 安排日程 | "明天 9 点到 11 点写报告" / "下周二下午开会" |
+| 看时间分布 | "这周时间都花哪儿了" / "看看今天的四象限" |
+| 复盘 | "复盘一下这周" / "帮我分析最近的时间使用" |
+| 拆任务 | "这个任务太大，帮我拆一下" |
+| 安排提醒 | "明天 8 点提醒我打卡" |
+
+## 数据存在哪
+
+默认在 `~/.libero/libero.db`（SQLite）。想换位置：
+
+```bash
+DB_PATH=/your/path.db libero-mcp
+```
+
+## 升级
+
+```bash
+npm update -g libero-mcp
+```
+
+DB schema 升级在启动时自动跑，不用手工干预。
+
+## 给开发者
+
+- 冷启动文案：[COLD_START.md](COLD_START.md)（与 MCP `instructions` 同源）
+- 协作宪法：[AGENTS.md](AGENTS.md)
+- 部署细节：[docs/operations/deploy-to-hermes.md](docs/operations/deploy-to-hermes.md)
+- Skills：`skills/`（libero-coach / libero-record / libero-onboarding / libero-decompose）

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/mcp/cold-start.js

@@ -0,0 +1,50 @@
+/**
+ * Cold-start copy for host agents (Hermes / OpenClaw) and MCP server instructions.
+ *
+ * Timing (user perspective):
+ * 1. After npm install / config written
+ * 2. FIRST show COLD_START_WELCOME to the user (before tools are live)
+ * 3. THEN /reload-mcp (or equivalent) to attach tools
+ *
+ * MCP cannot push a chat message by itself — hosts must speak this text in the
+ * install turn. Server `instructions` reinforce the same rules after connect.
+ */
+/** Short welcome users should see (natural language only). */
+export const COLD_START_WELCOME = `你好，我是 libero，帮你管时间和精力。
+
+常用这几件事，直接说就行：
+• 计时：「开始计时写代码」/「开个 25 分钟番茄钟」
+• 日程：「明天 9 点到 11 点写报告」
+• 拆任务：「这个太大了，帮我拆一下」
+• 看数据：「这周时间都花哪儿了」
+• 复盘：「帮我复盘一下这周」
+
+想先试哪一句？`;
+/**
+ * MCP initialize `instructions` — injected into host model context after connect.
+ * Also documents the install sequence for hosts that read package docs.
+ */
+export function buildServerInstructions() {
+    return [
+        "# libero — 时间与精力管理助手",
+        "",
+        "## 装机顺序（硬规矩）",
+        "1. npm i -g libero-mcp@latest 配置好 mcp_servers 后：",
+        "2. **先介绍**：把下面「冷启动欢迎」原样发给用户（不要列工具名 / 不要问配置）",
+        "3. **再 reload**：用户看完介绍后，再执行 /reload-mcp（或等价刷新）挂上工具",
+        "4. 禁止在介绍或首次对话里索取 user_id / DB_PATH / YAML",
+        "",
+        "## 冷启动欢迎（原样发给用户）",
+        COLD_START_WELCOME,
+        "",
+        "## user_id（硬纪律）",
+        "- 调用任何需要 user_id 的工具时：从当前会话上下文静默取（平台用户 ID / 会话稳定 ID）",
+        "- 取不到时用稳定占位 local:default",
+        "- **禁止问用户起 user_id**；禁止输出 wechat_你的ID / test_1 这类工程师问卷",
+        "- 可选问称呼（display_name），一句即可，可跳过",
+        "",
+        "## 对用户说话",
+        "- 只说自然语言能做什么；不要提 MCP / 工具表 / schema / 数据库",
+        "- 用户选了试用例句 → 直接执行对应能力，不要重复整段介绍",
+    ].join("\n");
+}

package/dist/mcp/server-core.js

@@ -11,6 +11,7 @@ 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";
+import { buildServerInstructions } from "./cold-start.js";
 /** Wrap any tool result as MCP text content (JSON). Void results become {ok:true}. */
 function asContent(result) {
     return {
@@ -45,7 +46,8 @@ export function buildServer(db) {
     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" });
+    // instructions 必须放在第 2 参 ServerOptions（不是 serverInfo）—— SDK 只从 options 读
+    const server = new McpServer({ name: "libero-mcp", version: "0.2.2" }, { instructions: buildServerInstructions() });
     // ============================================================
     // categories (2 tools)
     // ============================================================
@@ -200,9 +202,9 @@ export function buildServer(db) {
         inputSchema: { user_id: z.string().min(1) },
     }, async ({ user_id }) => asContent(await profile.get(user_id)));
     server.registerTool("profile.upsert", {
-        description: "创建或更新用户 profile（结构化约定存入 settings JSON 列）",
+        description: "创建或更新用户 profile。user_id 从会话上下文静默取，禁止向用户索取。",
         inputSchema: {
-            user_id: z.string().min(1),
+            user_id: z.string().min(1).describe("从会话上下文静默取；禁止问用户"),
             display_name: z.string().optional(),
             expectations: z.string().optional(),
             settings: z

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libero-mcp",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "AI 时间管理教练 MCP 工具集——时间块记录、统计、矩阵诊断、计时、分类、profile",
   "license": "MIT",
   "author": "amosyuan",
@@ -39,7 +39,8 @@
   "files": [
     "dist",
     "data/migrations",
-    "data/schema.sql"
+    "data/schema.sql",
+    "COLD_START.md"
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",