ai-growth 1.1.0

package/README.md

@@ -0,0 +1,384 @@
+# AI Growth
+
+> **第一次使用？看 [START-HERE.md](./START-HERE.md)** —— 3 步开始 + 该对 Agent 说什么。
+> Agent 请读 [AGENTS.md](./AGENTS.md)。
+
+**Agent-native、Local-first 的个人成长执行系统。**
+
+[![npm](https://img.shields.io/npm/v/ai-growth.svg)](https://www.npmjs.com/package/ai-growth)
+[![license](https://img.shields.io/npm/l/ai-growth.svg)](./LICENSE)
+[![node](https://img.shields.io/node/v/ai-growth.svg)](https://nodejs.org)
+
+**一条命令装上，把"我想做成什么"交给 AI，然后每天只面对今天这一张卡。**
+
+```bash
+npm install -g ai-growth
+ai-growth migrate     # 初始化本地数据库（数据在 ~/.ai-growth，与代码包完全分离）
+ai-growth doctor      # 环境自检
+```
+
+### 它解决什么问题
+
+大多数工具要求你**持续维护计划**——排期、复盘、把没做完的搬到明天。坚持不下去时，
+失败感来自"计划又崩了"，而不是目标本身难。AI Growth 把这件事翻过来：
+
+| | |
+|---|---|
+| **只推今天** | 每天默认 `1 Main Quest + 0~2 Daily Actions`。昨天没做完的**自动过期**，不 clone 到第二天，所以永远不产生"跨天债务" |
+| **AI 管路线，人决定目的地** | 计划由 Agent 维护，你保留目标与最终确认权；首次使用必须先做一次访谈，不允许直接生成任务 |
+| **不编数值** | 没有虚构的属性值、掌握度百分比、等级或自律分。进度只用可核对的事实表达（`Stage 3 / 6`、证据条目） |
+| **Local-first** | 数据全在本机 SQLite，**没有账号体系**；Agent 通过 MCP + Skill 直接读写，Web 面板只是视图 |
+| **能落到一块小屏上** | 可选：把今天推给 AI Passport 设备（「今日任务卡」），做完按一下，卡片立刻变完成态 |
+
+### 快速开始
+
+```bash
+ai-growth serve        # 启动服务（面板 http://localhost:4580）
+```
+
+然后把 MCP 接进你常用的 Agent（见下方[接入 Agent](#接入-agent)），对它说一句
+**「今天要做什么」**或**「开始今天的学习」**——第一次它会先访谈你，再排出第一份今日计划。
+
+> 面板长这样（`?layout=widget` 是桌面组件紧凑布局）：
+
+![卡片](docs/images/cards.png)
+
+<sub>图为设备端「今日任务卡」的全部卡面（与运行时同一套模板渲染）。</sub>
+
+---
+
+
+不是 Todo List，也不是虚构属性值 RPG。它的价值是：
+
+> 用户不用持续维护计划；AI 维护计划，人保留目标、选择和最终确认权。
+
+核心循环：
+
+```
+Human → Interview → Direction → Goal → Stage Plan → Daily Plan → Action
+      → Evidence → Reflection → Growth Event → Memory → AI Passport → Next Plan
+```
+
+核心原则（不可协商）：
+
+1. **AI 管路线，人决定目的地。**
+2. 首次使用必须由 Agent 主动发起 Onboarding Interview，不允许直接生成任务。
+3. Goal / 重要方向必须经用户确认。
+4. 长期计划只规划到 Stage；Daily Action 每天动态生成，不提前硬编码整月。
+5. 每天默认 `1 Main Quest + 0~2 Daily Actions`；长期改变默认负荷需用户确认。
+6. **Daily Action 仅当天有效**：次日自动 `EXPIRED`，不产生跨天债务（不 clone 到第二天）。
+7. **Main Quest 未完成不作废**：进入 `PENDING_REPLAN`，由 Agent 判断继续/拆分/延期。
+8. Passport 是当前 Human State 的压缩快照，不是 Source of Truth（SoT = Growth DB + Memory）。
+9. 所有状态变更必须经过 Core Service；MCP / Web 不直接写 DB。
+10. 系统开机自启，不要求用户手工 `npm run mcp`。
+
+---
+
+## 给 Agent 用（自动发现）
+
+仓库根目录有三个文件专供 Agent 扫描识别：
+
+| 文件 | 作用 |
+|---|---|
+| **`AGENTS.md`** | **Agent 入口**：是什么、怎么装、怎么接、怎么用、哪些规则不能违反 |
+| `llms.txt` | 精简机器可读索引 |
+| `server.json` | MCP Registry 清单（官方 schema 校验通过） |
+
+Agent 拿到仓库后，一条命令就能自举——**不需要读源码**：
+
+```bash
+npx ai-growth help --json        # 全部命令 + 产品规则 + 上手步骤
+npx ai-growth agent-info --json  # 安装路径、数据目录、MCP 配置片段、Skill 位置、下一步
+npx ai-growth status --json      # 当前状态 + suggestedNextOperation
+```
+
+用户自己装完之后，也可以直接对 Agent 说「用 ai-growth 帮我看看现在该做什么」，
+Agent 会调 `ai-growth status --json` 拿到 `suggestedNextOperation` 并照做。
+
+### CLI
+
+```bash
+ai-growth help [--json]          # 自描述：命令目录 + 产品铁律 + 上手步骤
+ai-growth agent-info [--json]    # Agent 引导信息
+ai-growth info [--json]          # 环境与运行状态
+ai-growth status [--json]        # 状态 + 建议下一步
+ai-growth today [--json]         # 今日计划
+ai-growth goals|timeline|passport|metrics [--json]
+ai-growth rollover [--json]      # 跨天检查（幂等）
+ai-growth complete|skip|delay <actionId> [...]
+ai-growth mcp-config [--json]    # 打印可粘贴的 MCP 配置
+ai-growth skill                  # 打印 SKILL.md 全文
+ai-growth doctor                 # 环境自检
+ai-growth init                   # 初始化数据库
+ai-growth serve                  # 前台启动常驻服务
+```
+
+**输出契约与 MCP 工具一致**：`{ ok, data, error? }`。非 TTY（被 Agent/管道调用）时**默认 JSON**，
+避免 Agent 忘记加 `--json`；人类可读输出用 `--no-json`。
+
+> CLI 只覆盖读操作与少数任务操作。建目标、写 Evidence、Replan、建提醒等要接 MCP——
+> 那些涉及确认与上下文，CLI 刻意不做。
+
+## 安装
+
+**设计原则：开发与生产是同一条全局命令，数据始终在 `~/.ai-growth`。**
+CLI / MCP / daemon / 面板都指向「全局安装的那一份」，所以**更新 = 替换全局包**，数据不受影响。
+
+```bash
+cd "该项目目录"
+./scripts/install.sh              # 默认开发态：npm link（全局 ai-growth → 当前源码）
+./scripts/install.sh --global     # 生产态：npm pack + npm install -g（与源码检出解耦）
+```
+
+安装脚本 9 步：环境检查 → 依赖 → 构建 → **全局安装** → 数据库迁移
+→ launchd 常驻服务（指向全局 CLI）→ MCP 配置 → Agent 入口说明 → doctor。
+
+### 更新
+
+| 形态 | 怎么更新 |
+|---|---|
+| 开发态（`npm link`） | `git pull && npm install && npm run build` → 全局命令自动生效，无需重新 link |
+| 生产态（`npm i -g`） | `npm install -g ai-growth@latest && ai-growth migrate` |
+| 让 daemon 加载新代码 | `launchctl kickstart -k gui/$(id -u)/com.lairey.ai-growth.daemon` |
+
+**数据不受更新影响**：`~/.ai-growth/growth.db` 与代码包完全分离，schema 变更走 migration（幂等、增量）。
+
+随时用 `ai-growth where` 查看当前是哪一种形态、代码在哪、数据在哪、该怎么更新。
+
+
+## 接入 Agent
+
+两步：**Skill** + **MCP**。
+
+**MCP**（给出 `node` 与项目绝对路径）：
+
+```json
+{
+  "mcpServers": {
+    "ai-growth": {
+      "command": "/path/to/node",
+      "args": ["/absolute/path/to/dist/mcp/server.js"],
+      "env": { "AI_GROWTH_DATA_DIR": "/Users/you/.ai-growth" }
+    }
+  }
+}
+```
+
+**Skill**：把仓库根目录的 `SKILL.md` 交给 Agent。WorkBuddy 用户级安装：
+
+```bash
+mkdir -p ~/.workbuddy/skills/ai-growth && cp SKILL.md ~/.workbuddy/skills/ai-growth/
+```
+
+接好后对 Agent 说一句 **「开启今日任务」**（同义：「今天要做什么」「开工」）——它会调用 `growth_status`，按状态决定下一步；首次使用会主动开始访谈，而不是直接派任务。
+
+## 启动
+
+| 服务 | 命令 | 说明 |
+|---|---|---|
+| 常驻 Daemon | 安装后由 launchd 托管（`ai-growth serve` 手动前台） | **同时提供调度（rollover + 提醒 + 同步重试）与面板 API** |
+| MCP Server（stdio，由 Agent 拉起） | `ai-growth` MCP 配置指向全局安装 | 平时无需手动运行 |
+| 面板 | http://127.0.0.1:4580（daemon 自带） | 单独跑用 `npm run api` |
+| 健康检查 | `ai-growth doctor` 或 `bash scripts/doctor.sh` | 逐项验证环境（含构建新鲜度） |
+| 数据库迁移 | `ai-growth migrate` | 幂等，可重复执行 |
+| 清理构建产物 | `npm run clean` | 删除 `dist/`（`build` 已内置） |
+
+daemon 与面板合成一个进程是刻意的：面板要能当桌面组件/桌面应用用，就必须和 daemon 同生命周期，
+否则用户每次重启还得手工起面板——违反「不要求用户维护系统」。
+
+## 面板（游戏面板式 HUD）
+
+`http://127.0.0.1:4580`
+
+深色面板风格：卡片式布局、阶段节点轨道、主任务高亮卡、事实计数条。
+
+**🔴 面板上不会出现虚构数值。** 这是你自己定的铁律（核心原则 6 / §16.3 明确禁止六维属性、EXP、等级、
+掌握度百分比、自律分）。所以面板的「游戏感」只体现在**视觉语言**上——卡片、发光描边、节点轨道、状态色——
+而每一个数字都是可核对事实：
+
+| 显示 | 来源 |
+|---|---|
+| `Stage 2 / 5` | Stage 序号与总数 |
+| 已完成主任务 / 证据总数 / 成长记录 | 数据库计数 |
+| 阶段节点轨道 | 各 Stage 的真实 status |
+| 最近进展 | Growth Event（每条都挂着 Evidence） |
+
+页面：**面板**（Progress First：当前主线 → 阶段轨道 → 今天最重要的一步 → 每日维护 → 累计事实 → 最近进展）、
+**主线**（Goal 的 why/outcome/成功标准 + Stage Timeline）、**记录**（Growth Events + Evidence 流，含强度标签）、
+**护照**（Passport 快照）、**设置**（时区、提醒渠道、手动跨天检查）。
+
+支持 URL 深链：`#goals`、`#timeline`、`#settings`。
+
+### 桌面组件 / 打包成桌面应用
+
+面板已为桌面形态预留两件事：
+
+1. **紧凑布局**：URL 加 `?layout=widget`（或窗口宽度 < 420px 自动切换）→ 单列、窄边距、隐藏品牌字。
+   实测 360px / 430px 宽均无横向溢出。
+2. **无构建步骤**：纯 HTML/CSS/JS，任何 WebView 都能直接托管。状态全来自本地 API，
+   应用本身只是"视图"，daemon 照常headless 运行。
+
+后续打包路径（按成本从低到高）：
+
+| 方案 | 说明 | 成本 |
+|---|---|---|
+| 浏览器固定窗口 | Safari/Chrome 加到程序坞，加载 `http://localhost:4580/?layout=widget` | 0 |
+| Übersicht 桌面组件 | 直接渲染 HTML 到桌面层，最贴近"在桌面上显示" | 低 |
+| Tauri v2 | 体积小（~5MB），需 Rust；可做无边框 + 常驻置顶 | 中 |
+| Electron | 无需 Rust，体积大（~150MB）；`frame:false, transparent, alwaysOnTop` | 中 |
+
+⚠️ **打包时必须让 WebView 加载 `http://localhost:4580`，不要用 `file://` 打开 index.html**：
+页面 origin 为 `null` 时浏览器会按 CORS 拦掉对本地 API 的请求。加载 localhost 时 Host 校验也正好放行。
+
+## 连上 AI Passport 设备
+
+把固件刷到设备之后，让设备连上这台电脑**只需要一条命令**（它会自己确认成功）：
+
+```bash
+ai-growth device setup --ssid "你的Wi-Fi名" --pass "Wi-Fi密码"
+```
+
+- 它会自动找到串口、写好配置、顺手开启并记住「局域网访问」，然后**等设备真的取到卡**再回报结果
+- Wi-Fi 名含中文或空格也没关系（会自动改用十六进制编码：设备控制台本身只能收 ASCII）
+- 设备之后每次开机都会自动连上并显示今天的卡，**不需要按任何键**
+- 想先看当前状态／本机地址／令牌：`ai-growth device`
+- 失败时它给出的不是错误码，而是**下一步该做什么**（连不上 Wi-Fi／够不到电脑／服务没起来）
+
+设备上的按键：**上/下** 翻今天的卡，**确定** 完成当前这件事，**长按确定** 回到设备自带的演示菜单。
+屏幕 1 分钟无操作会自动熄屏，按任意键立刻亮回。
+
+## 安全边界（没有账号体系）
+
+这不是一个需要登录的产品——它是本机进程 + Agent 工具。安全边界是 **loopback**，不是登录：
+
+- 只监听 `127.0.0.1`，不对外暴露
+- 校验 `Host` 头：只接受 `127.0.0.1` / `localhost` / `[::1]`，其余返回 `403 FORBIDDEN_HOST`
+  （挡住浏览器里任意网页通过 DNS rebinding / CSRF 驱动你的 Growth 数据）
+- 静态资源做目录穿越防护
+
+需要局域网访问时自行加反向代理与鉴权，不要直接把端口绑到 `0.0.0.0`。
+
+
+## 数据位置
+
+| 内容 | 路径 |
+|---|---|
+| 数据库 | `~/.ai-growth/growth.db`（WAL 模式） |
+| Passport 输出 | `~/.ai-growth/passport.json` |
+| Daemon 日志 | `~/.ai-growth/daemon.log`、`daemon-stderr.log` |
+| 配置 | 项目根 `.env`（参考 `.env.example`）或 `~/.ai-growth/config.env` |
+| launchd plist | `~/Library/LaunchAgents/com.lairey.ai-growth.daemon.plist` |
+
+备份 = 复制 `~/.ai-growth/growth.db`。所有数据默认只在本机；外部同步必须显式配置 Adapter。
+
+## 卸载 / 重置
+
+```bash
+./scripts/uninstall.sh           # 停止并移除 launchd 服务，数据保留
+./scripts/uninstall.sh --purge    # 额外删除数据目录（需输入 yes 二次确认）
+
+./scripts/reset-dev-data.sh --list    # 只看数据概况，不做任何修改
+./scripts/reset-dev-data.sh           # 备份现有数据 → 建一个干净新库
+./scripts/reset-dev-data.sh --force   # 跳过"疑似真实数据"拦截
+```
+
+`reset-dev-data.sh` 永不静默删数据：它把数据目录改名备份，并打印回滚命令。
+
+## 故障排查
+
+| 现象 | 原因 / 处理 |
+|---|---|
+| Agent 说连不上 MCP | `bash scripts/doctor.sh` 看 MCP 一节；确认 `dist/mcp/server.js` 存在（`npm run build`） |
+| **改了代码但行为没变** | **`dist/` 陈旧**。`npm run build`（已内置 `rm -rf dist`，幂等）；`doctor.sh` 会检测 `dist ≠ src` |
+| Web UI 打开是空白页 | 静态资源 MIME 必须正确（`.js` 不能用 `text/html` 返回）。若手工改过 server 需重启 `npm run api` |
+| 重启后提醒不触发 | `launchctl list \| grep ai-growth`；未加载则 `launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.lairey.ai-growth.daemon.plist` |
+| daemon 反复退出 | 看 `~/.ai-growth/daemon-stderr.log` |
+| 时间不对 / 日期错乱 | Web UI → Settings 设置正确 timezone（自然日判断依据，非 UTC 截断） |
+| 提醒太吵 | Settings 把 Reminder Channel 设为「关闭提醒」；每个 Daily 默认最多 1 次提醒 |
+| 昨日任务还挂在今天 | Web UI 打开时会自动执行 rollover；也可在 Settings 手动执行 / 让 Agent 调 `run_daily_rollover` |
+| `ONBOARDING_REQUIRED` 报错 | 未完成首次访谈就调了 `plan_today`——这是结构性保护，先完成访谈 |
+| `REPLAN_REQUIRED` 报错 | 有未处理的 Replan，先让 Agent 调 `replan` 再规划新主线 |
+| 想确认状态机没被绕过 | `audit_log` 表记录了关键变动（含 Replan 决策）的 before/after 与原因 |
+| 面板打不开 / 白屏 | 面板由 daemon 提供：`bash scripts/doctor.sh` 看「面板 API」；单跑用 `npm run api`。白屏多半是 MIME 不对，重启进程即可 |
+| 打包后 API 调用失败 | WebView 必须加载 `http://localhost:4580`，不能用 `file://`（origin 为 null 会被 CORS 拦） |
+
+## 开发
+
+```bash
+npm run typecheck   # tsc --noEmit
+npm test            # 118 个测试（unit + integration + e2e + dist 运行时冒烟）
+npm run build       # 幂等：先 rm -rf dist 再编译并拷贝资源
+```
+
+> **`npm test` 里有一层「运行时冒烟」**：它直接启动编译后的 `dist/mcp/server.js` 并按 MCP 协议调用工具。
+> 这层测试专门覆盖"只有打包后才暴露"的问题（资源拷贝路径、migration 陈旧、MIME 等）——
+> 源码测试全绿但产物是坏的，就是靠它发现的。同时也校验 `dist` 与 `src` 逐字节一致。
+
+工程结构：
+
+```
+src/
+├── core/        # 领域层：状态机、Goal/Stage/Action、Rollover、Replan、Evidence、Memory、Metrics
+├── db/          # SQLite 连接 + 版本化 migration
+├── mcp/         # MCP Server + 63 个 tools（统一 ToolResult 契约）
+├── planner/     # 规划上下文与约束（LLM 判断交给 Agent，Core 只保证规则）
+├── reminder/    # 提醒生命周期 + Scheduler + 通知 Adapter
+├── passport/    # Passport 构建 + Sync Adapter（local-json / 可替换）
+├── api/         # 供 Web UI 使用的 HTTP API
+├── ui/          # Today / Goals / Timeline / Passport / Settings
+├── daemon/      # 常驻进程入口
+└── shared/      # 配置、时间（timezone 感知）、统一结果类型
+```
+
+### 架构约定
+
+- **状态机是唯一权威**（`src/core/stateMachine.ts`）。非法转换抛 `INVALID_STATE`，不静默通过。
+  - `IN_PROGRESS` 是**可选**中间态：`PLANNED → COMPLETED` 合法（用户说"做完了"不该被要求先点"开始"）。
+  - 任何未终结的 DAILY 都能跨天 `EXPIRED`（含 `IN_PROGRESS` / `DELAYED`），否则 rollover 会崩。
+- **Core 强制业务规则，MCP 层不重复声明**：zod schema 只做类型校验，`0~2 个 Daily`、`Goal 必须含 why` 这类规则由 Core 抛出带错误码的 `ToolResult`，保证返回结构统一。
+- **结构性优先于文档约定**：`ONBOARDING_REQUIRED`（未访谈不得生成任务）、`REPLAN_REQUIRED`（先解决 Replan 再开新主线）都由 Core 强制，不依赖 Agent"记得遵守"。
+- **时间**：DB 存 ISO timestamp；「哪一天」一律按配置时区计算（`src/shared/time.ts`），绝不按 UTC 截断。
+- **幂等**：rollover（日期级 + action 级）、reminder 取消、sync job 创建、daemon 重启均可重复执行。
+- **排序必须带稳定 tiebreaker**：SQLite 用 `updated_at DESC, rowid DESC`；`created_at` 同毫秒撞车时不可作为唯一排序键。
+- **审计**：关键变动（含 Replan 决策本身）写入 `audit_log`（谁触发 / before / after / 原因 / 时间）。
+
+## 当前限制
+
+- V1 不含：六维属性 / EXP / 等级、RPG 装备、Knowledge Graph UI、课程平台、社交排名、云端账号、多人协作（均为预留接口，不阻塞上线）。
+- Passport 外部同步：仅实现 `local-json` Adapter；接真实外部 API 时实现 `PassportSyncAdapter` 接口即可，失败会进重试队列且不影响本地状态。
+- 通知渠道：已实现 macOS 本地通知（osascript）与 `null` 两种 Adapter。
+- 提醒精确定时依赖 daemon 轮询（默认 30s 粒度），非秒级精确。
+- 面板**没有账号体系也刻意不做**（本机进程 + Agent 工具，loopback 即边界）。如需局域网访问请自行加代理与鉴权。
+- 桌面应用打包尚未实施：面板已就绪（紧凑布局 + 无构建步骤），打包属独立交付项。
+
+详见 `DELIVERY_REPORT.md` 与 `IMPLEMENTATION_PLAN.md`。
+
+---
+
+## 参与贡献
+
+欢迎 Issue 与 PR。这个项目有几条**不可协商**的产品铁律（见文首「核心原则」），
+改动前请先确认不违背它们——尤其是这两条最容易在实现里被悄悄破坏：
+
+- **不产生虚构数值**：任何"属性值 / 掌握度 % / 自律分 / 等级"都会被测试拦下；
+- **不制造跨天债务**：`Daily Action` 次日必须 `EXPIRED`，绝不 clone 到第二天。
+
+提交前请跑：
+
+```bash
+npm run build && npx tsc --noEmit && npm test && bash scripts/doctor.sh
+```
+
+## 相关文档
+
+| 文件 | 给谁看 |
+|---|---|
+| [START-HERE.md](./START-HERE.md) | 第一次使用的你：3 步开始 + 该对 Agent 说什么 |
+| [AGENTS.md](./AGENTS.md) | 任何 Agent：能力、接入方式、禁止事项 |
+| [SKILL.md](./SKILL.md) | Agent 技能定义（自动发现入口） |
+| [PRODUCT_SPEC.md](./PRODUCT_SPEC.md) | 想知道"为什么这么设计"的人 |
+| [llms.txt](./llms.txt) | 给 LLM 的精简索引 |
+
+## 许可
+
+[MIT](./LICENSE) © 2026 lairey-ai

package/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: ai-growth
+description: 用户的个人成长执行系统（本地 ai-growth MCP），管的是「目标—阶段—每日推进」这条线。当用户说「开启今日任务」「今天要做什么」「开始今天的学习」「今天安排什么」「开工」，或问进度/复盘/周计划，或说任务太多做不完、这个任务不合理想换掉、最近坚持不下去时使用。首次使用先做访谈再建目标，不直接派任务。边界：用户要的是"做这件事本身"（写代码、写稿、改文案、查资料）时不使用它——那是具体工作，不是成长规划；只有要"怎么安排、排优先级、推进到哪、为什么卡住"时才用。铁律：AI 管路线人决定目的地；每日任务当天有效次日作废、绝不累积成债务；不产生虚构属性值和自律分。
+---
+
+# AI Growth Skill
+
+You are connected to the user's AI Growth system — a local-first, agent-driven personal growth execution system.
+
+Your job is not to maximize task count. Your job is to help the human make meaningful, evidence-backed progress toward directions they have chosen. AI manages the route; the human decides the destination.
+
+## 启动语（最常见的入口）
+
+用户说下面任意一句，**就是进入本系统的入口**，第一步永远是 `growth_status`（或 CLI `ai-growth start`）：
+
+> 「开启今日任务」「今天要做什么」「开始今天的学习」「今天安排什么」「开工」「今天该干嘛」
+
+**关键：启动语 ≠ 立刻建任务。** 先看 `suggestedNextOperation` 再决定：
+
+| suggestedNextOperation | 你该做什么 |
+|---|---|
+| `START_ONBOARDING` / `CONTINUE_ONBOARDING` | **先访谈，不要生成任何任务**（核心原则 2） |
+| `RESOLVE_REPLAN` | 先解决待重排的主线，再谈今天 |
+| `DISCUSS_GOAL` | 与用户讨论目标，不要自己编一个 |
+| `RUN_DAILY_PLANNING` | 生成今日计划并请用户确认 |
+| `CONFIRM_TODAY_PLAN` | 把已生成的计划给用户确认 |
+| `CONTINUE_TODAY` | 帮用户推进手上的任务 |
+
+即：**同一个「开启今日任务」，第一天会带你走访谈，之后才会变成"今天的 1 主 + 0~2 每日"。**
+不要跳过访谈直接给任务，也不要因为用户说"开启"就跳过 Replan。
+
+## 边界：这些情况不要用本系统
+
+| 用户要的是 | 该谁干 |
+|---|---|
+| 写代码 / 做功能 / 修 bug | 直接干活，**不要**先建 Goal 或 Daily |
+| 写小说 / 写稿 / 改文案 | 走创作类工具（如 `my-novel-writer`），不是成长规划 |
+| 改稿、降 AI 味、润色 | 文本处理工具（如 `humanizer` / `tomato-deai`） |
+| 查新闻 / 查资料 | 查询类工具（如 `aihot`） |
+| 学某个具体技术知识点 | 先直接讲；**只有在用户想"系统性地安排进度"时**才进本系统 |
+
+判断一句话：**用户是想"把这件事做了"，还是想"把这件事安排好、推进下去"？**
+前者别进来，后者才是本系统。若两个技能都像，优先让专业工具做正事，本系统只在用户明确
+提到目标/计划/每日任务/进度时介入。
+
+## 对外行友好（用户不一定是技术人员）
+
+1. **首次使用先用一句大白话说清这是什么**，别上来就问一堆问题。例如：
+   「这个系统会替你安排每天该做的事——你只要说你想做成什么、每天有多少时间，
+   它帮你拆成阶段和每天一小步，昨天没做完的不会欠着。」
+2. **访谈用大白话**：不要问"成功标准是什么"，问"做到什么样你会觉得这事成了"。
+   不要问"约束条件"，问"生活里有什么会挡着你（上班、带娃、作息）"。
+3. **不要把错误码念给用户**。`ONBOARDING_REQUIRED` / `REPLAN_REQUIRED` 是给 Agent 看的；
+   对用户要说「我们还没聊过你的目标，先聊两句？」。
+4. **不要让用户去操作数据库、命令行或配置文件**。需要看进度就用 `render_progress` 输出图表，
+   或让他打开面板 http://127.0.0.1:4580。
+5. 用户说"我不懂""太复杂了"时，**减少选项、只给下一步那一个动作**，不要解释系统原理。
+
+## 输出进度：用图表，不要纯文字
+
+用户想看进度时，**默认用 `render_progress`**（MCP）或 `ai-growth progress`（CLI）产出带样式的
+Markdown：阶段轨道、进度条、事实表、Mermaid 时间线。把它直接贴给/展示给用户。
+不要写一大段"你目前完成了…"的流水账文字。
+
+## On load
+
+1. Call `growth_status`. It returns `suggestedNextOperation` — follow it.
+2. If onboarding is missing/incomplete, proactively continue the onboarding interview before planning any tasks. Interview conversationally (not a form). At minimum learn: main goal, expected outcome, target period, daily time available, current level, life constraints, life areas to improve, task load preference.
+3. If there is no active goal, discuss goals with the human; do not invent a major goal.
+4. If a goal draft exists, continue planning and request confirmation.
+5. Call `run_daily_rollover` (idempotent, always safe).
+6. If today's plan does not exist, start daily planning (see below).
+7. If a previous Main Quest is pending replan, resolve it BEFORE creating a new Main Quest (`get_replan_hints` → `replan`).
+8. Ask for missing situational information only when it materially affects today's plan (e.g. "how much time do you have today?").
+9. Present today's plan and obtain confirmation (`plan_today` → show → `confirm_today_plan` after user agrees).
+10. Create/update reminders after plan confirmation (`create_reminder`). Do not guess very specific times — if unknown, ask once during daily planning and remember the answer via `update_profile_patch` reminderPreferences.
+
+## During work
+
+- When meaningful work is completed, record Evidence (`add_evidence`). Use the right strength: GIT/METRIC/QUIZ/ARTIFACT are AUTO_VERIFIED; user's word is USER_CONFIRMED; your observation is AGENT_OBSERVED.
+- Modify unreasonable execution-level tasks autonomously when appropriate (`update_action`).
+- If the human says a task is unreasonable, record feedback (`add_task_feedback`) and replan it rather than defending the task.
+- Use the correct verification strategy per domain: LEARN → quiz/explain/challenge (never mark mastered just because content was read); BUILD/CREATE → files/git/runnable artifacts; TRAIN → objective metrics (duration/distance/reps); HABIT → consistency without moralizing.
+- For meaningful milestones, create Growth Events with evidence IDs (`create_growth_event`). Never create evidence-free personality judgments.
+- After meaningful state changes, run `sync_passport`.
+
+## Daily actions
+
+- Daily Actions are valid only for their local calendar day.
+- Never carry an incomplete Daily Action into the next day — rollover expires them automatically. If a similar action is right today, create a NEW action (`create_action`) after reassessing today's context.
+- Daily Actions must trace to user-confirmed directions/intentions/constraints. Check `list_directions` first. Never impose a stereotypical "healthy life template".
+- Default daily plan: 1 Main Quest (with whyToday, completionCriteria, estimatedMinutes) + 0~2 Daily Actions.
+
+## Life context
+
+- When the user says things like "this week is busy / only 30 min/day / I'm traveling", call `set_life_context` immediately. The planner must adapt load, not push harder.
+- Busy periods: reduce tasks, never guilt-trip about completion rate.
+- After a temporary context expires, proactively ask whether to resume normal load.
+
+## Human authority — get explicit confirmation before
+
+- Creating/abandoning long-term goals; changing why/outcome/success criteria.
+- Meaningfully changing the target date or learning scope.
+- Long-term increasing default daily load.
+- Adding a new life direction the user never agreed to.
+- Writing an inference into Passport as a stable fact.
+
+Autonomous (no confirmation needed): creating/modifying/splitting today's execution tasks, reordering within a stage, small stage delays (inform the user), reducing task count, choosing evidence formats.
+
+## Error handling
+
+- Tools return `{ ok, data?, error: { code, message } }`. Common codes:
+  - `ONBOARDING_REQUIRED` → run the interview.
+  - `CONFIRMATION_REQUIRED` / user authority items → ask the human.
+  - `REPLAN_REQUIRED` / `INVALID_STATE` → read the error, call `growth_status`, align with system state.
+  - `ALREADY_EXISTS` (today's plan) → use `get_today_plan` + `update_action` instead of re-planning.
+- If the DB or daemon is down, tell the user to run `bash scripts/doctor.sh`.
+
+## End of interaction
+
+Before finishing: if any state changed (evidence added, tasks completed, goal updates), call `sync_passport` once. Do not re-explain the system to the user — the system state carries itself.

package/START-HERE.md

@@ -0,0 +1,156 @@
+# 从这里开始
+
+> 给用户的 3 步开始指引。技术细节见 [README.md](./README.md)，Agent 入口见 [AGENTS.md](./AGENTS.md)。
+
+## 现在的状态（已装好）
+
+| 项 | 状态 |
+|---|---|
+| 全局命令 `ai-growth` | ✅ 已就绪（终端可直接用） |
+| 数据库 | ✅ `~/.ai-growth/growth.db`（空，等访谈） |
+| 常驻服务 daemon | ✅ 由 launchd 托管，开机自启（面板 + 定时提醒） |
+| 面板 | ✅ http://127.0.0.1:4580 |
+| Skill（告诉 Agent 什么时候用它） | ✅ 已装到 `~/.workbuddy/skills/ai-growth/` |
+| MCP（63 个工具） | ✅ 已写入 `~/.workbuddy/mcp.json` |
+
+## 你需要做的 3 步
+
+### 第 1 步：在 Agent 里「信任」这个 MCP
+
+打开 WorkBuddy 的**连接器管理页 → 右上角「自定义连接器」→ 找到 `ai-growth` → 点「信任」**。
+
+> 这是唯一还需你手点的一步（配置已写好，但出于安全 MCP 不会自动激活）。
+
+### 第 2 步：开一个新对话
+
+Skill 和 MCP 是**会话开始时**加载的，所以已经开着的对话看不到它。新开一个对话。
+
+### 第 3 步：说一句启动语
+
+```
+开启今日任务
+```
+
+同义说法（任选，效果一样）：
+
+```
+今天要做什么
+开始今天的学习
+今天安排什么
+开工
+```
+
+Agent 会调用 `growth_status`（等价于 CLI `ai-growth start`），然后**按状态决定**：
+
+| 你的状态 | Agent 会做 |
+|---|---|
+| 还没访谈过（现在就是这样） | **先访谈，不会直接派任务** |
+| 有未处理的重排主线 | 先解决它，再谈今天 |
+| 正常 | 给出今天的 1 个主任务 + 0~2 个每日任务 |
+
+首次访谈它会问这些（用真实情况回答即可，不用准备）：
+
+- 你现在主要想做成什么？希望最后达到什么程度（不是"学完什么"）
+- 想多久做到？每天大概能投入多少时间
+- 现在的基础到哪了
+- 生活上有什么约束（作息、工作、家庭）
+- 想改善哪些生活领域（运动 / 睡眠 / 关系 / 其他）
+- 每天能接受几个任务
+
+回答完它会给你一份 **Goal 草案 + 阶段计划**，你确认后才开始生成今天的任务。
+
+> ⚠️ 「开启今日任务」不是"立刻给我一堆任务"。第一次它会先访谈——这是刻意的（AI 管路线，人决定目的地）。
+
+---
+
+## 怎么让 Agent 一直用这套系统
+
+Skill 的 `description` 已经写明触发条件，所以**相关话题会自动走 AI Growth**。你不需要每次都点名。
+
+**会自动触发的说法：**
+
+| 你说 | Agent 会做 |
+|---|---|
+| **开启今日任务** / 今天要做什么 / 开工 | 跨天检查 → 给出今日计划（首次会先访谈） |
+| 开始今天的学习 | 同上（学习型目标的常用说法） |
+| 我想 30 天学会 XXX | 走访谈 → 建 Goal → 分阶段 |
+| 这个任务我不想做 / 换一个 | 记为反馈并替换（不是简单删除） |
+| 我这周特别忙 / 明天只有半小时 | 调整负荷（LifeContext） |
+| 我最近进度怎么样 / 帮我复盘 | 汇总证据与成长记录 |
+| 我做完了 / 搞定了 | 完成任务并记录证据 |
+| 昨天那个没做完 | 走 Replan（不作废、不累积） |
+
+**想强制指名，也可以直接说：**
+
+```
+用 ai-growth 看看我现在该做什么
+帮我用 ai-growth 复盘这周
+```
+
+**如果 Agent 没走系统**（比如自己给你列了个 todo 列表），直接纠正它：
+
+```
+用 ai-growth 来做，不要自己列清单
+```
+
+## 随时自查（终端里）
+
+```bash
+ai-growth start            # 开启今日任务（跨天检查 + 状态 + 今日计划 + 该做什么）
+ai-growth status           # 只看状态 + 建议下一步
+ai-growth today            # 只看今日计划
+ai-growth where            # 跑的是哪一份代码、数据在哪、怎么更新
+ai-growth help             # 全部命令
+```
+
+Agent 也能自己查（这就是"Agent 知道自己该怎么用"的机制）：
+
+```bash
+ai-growth agent-info --json    # 安装位置、数据目录、MCP 配置、Skill 位置、下一步
+```
+
+## 日常使用节奏（建议）
+
+| 时机 | 做什么 |
+|---|---|
+| 早上/开始工作前 | 对 Agent 说「开启今日任务」→ 看它给的 1 主 + 0~2 每日任务 |
+| 觉得不合适 | 直接说「这个不合理 / 太难 / 没时间」→ 它会换，不会硬推 |
+| 做完了 | 说一声「做完了」，Agent 会记证据 |
+| 想看进度 | 说「给我看看进度」→ Agent 会给出**图表式报告**（不是流水账） |
+| 睡前（可选） | 说「复盘一下」 |
+| 每周（可选） | 说「这周复盘」→ 看阶段进度是否要调整 |
+
+**不用做的事**：不用自己维护清单、不用手抄进度、不用管昨天没做完的——系统会自动作废每日任务、
+把主任务转入待重排，不会攒成一堆欠债。
+
+## 进度是图表，不是流水账
+
+想让 Agent 展示进度时，它默认输出**带样式的报告**（不是一堆文字）：
+
+- 阶段进度条 + 节点轨道（`■ ◧ □ □ □`）
+- 甘特图（Mermaid，支持渲染的查看器里是可视化时间线）
+- 今日任务表、事实统计表、最近进展表
+
+你自己也可以随时在终端生成：
+
+```bash
+ai-growth progress                # 在终端直接看 Markdown
+ai-growth progress --out p.md     # 存成 Markdown
+ai-growth progress --out p.html   # 存成网页（双击就能打开，深色面板样式）
+```
+
+> 报告里的进度条比例来自「阶段序号 / 总数」，数字全部是数据库里的可核对事实。
+> 没有"掌握度 72%"这种东西——那是编不出来的。
+
+## 出问题怎么办
+
+```bash
+ai-growth doctor      # 逐项自检，并给出修复命令
+```
+
+| 现象 | 处理 |
+|---|---|
+| Agent 说没连上 ai-growth | 检查第 1 步的「信任」是否点了；再跑 `ai-growth doctor` |
+| Agent 不知道要做什么 | 新开一个对话（Skill 元数据在会话开始时加载） |
+| 面板打不开 | daemon 应自带面板；`ai-growth serve` 可前台跑起来 |
+| 想彻底卸载 | `./scripts/uninstall.sh`（默认保留数据）；加 `--purge` 才删数据 |