npm - ai-growth - Versions diffs - 1.1.0 → 1.1.1 - Mend

ai-growth 1.1.0 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -1,383 +1,89 @@
 # AI Growth
-> **第一次使用？看 [START-HERE.md](./START-HERE.md)** —— 3 步开始 + 该对 Agent 说什么。
-> Agent 请读 [AGENTS.md](./AGENTS.md)。
-**Agent-native、Local-first 的个人成长执行系统。**
+> **让 Agent 陪你成长。** 你说想成为什么样的人，Agent 把路铺到今天 —— 你每天只需要做今天这一件事。
 [![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，然后每天只面对今天这一张卡。**
+> 第一次使用？看 [START-HERE.md](./START-HERE.md)（3 步开始 + 该对 Agent 说什么）。
+> **Agent 请读 [AGENTS.md](./AGENTS.md)** —— 那是给 AI 的主入口，本文是给人看的。
-```bash
-npm install -g ai-growth
-ai-growth migrate     # 初始化本地数据库（数据在 ~/.ai-growth，与代码包完全分离）
-ai-growth doctor      # 环境自检
-```
+## 它是什么
-### 它解决什么问题
+`ai-growth` 是一个跑在**你自己电脑上**的个人成长系统。它把「目标 → 阶段 → 今天做什么」这条线交给 Agent 维护，把「目标是什么、要不要继续」留给你。
-大多数工具要求你**持续维护计划**——排期、复盘、把没做完的搬到明天。坚持不下去时，
-失败感来自"计划又崩了"，而不是目标本身难。AI Growth 把这件事翻过来：
+每天只给你 **1 件主线任务 + 0~2 件小事**；**昨天没做完的第二天自动过期**，不会攒成债务。你不需要自己排期、复盘、把任务搬到明天 —— 那些是 Agent 的事。
-| | |
+| 它是 | 它不是 |
 |---|---|
-| **只推今天** | 每天默认 `1 Main Quest + 0~2 Daily Actions`。昨天没做完的**自动过期**，不 clone 到第二天，所以永远不产生"跨天债务" |
-| **AI 管路线，人决定目的地** | 计划由 Agent 维护，你保留目标与最终确认权；首次使用必须先做一次访谈，不允许直接生成任务 |
-| **不编数值** | 没有虚构的属性值、掌握度百分比、等级或自律分。进度只用可核对的事实表达（`Stage 3 / 6`、证据条目） |
-| **Local-first** | 数据全在本机 SQLite，**没有账号体系**；Agent 通过 MCP + Skill 直接读写，Web 面板只是视图 |
-| **能落到一块小屏上** | 可选：把今天推给 AI Passport 设备（「今日任务卡」），做完按一下，卡片立刻变完成态 |
+| 让 **Agent 帮你维护成长计划** 的系统 | 又一个待办清单（排期和搬运都不归你管） |
+| 每天**只面对今天**的执行界面 | 打卡 App（没有连续天数、没有断签焦虑） |
+| 用**可核对的事实**表达进度（`Stage 3 / 6`、证据条目） | 游戏化 RPG（**没有**属性值、等级、掌握度百分比、自律分） |
+| **本地优先**：数据在自己机器上，不需要账号 | 云服务（不注册、不上传，离线也能跑） |
-### 快速开始
+## 3 分钟开始
 ```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
+npm install -g ai-growth     # 1. 安装
+ai-growth init               # 2. 初始化本地数据（数据在 ~/.ai-growth）
+ai-growth mcp-config         # 3. 打印 MCP 配置 → 粘进你的 Agent 并信任它
 ```
-核心原则（不可协商）：
+然后把 [`SKILL.md`](./SKILL.md) 交给 Agent 当行为准则，对它说一句：
-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                  # 前台启动常驻服务
+你说想法 → Agent 访谈 → 方向 → 目标 → 阶段计划 → 今日计划 → 今日任务
+                                                              ↓
+       下一次对话 ← 记忆 ← 成长事件 ← 复盘 ← 证据 ← 完成 / 过期
 ```
-**输出契约与 MCP 工具一致**：`{ ok, data, error? }`。非 TTY（被 Agent/管道调用）时**默认 JSON**，
-避免 Agent 忘记加 `--json`；人类可读输出用 `--no-json`。
+三条**不可协商**的规则（写在代码与测试里，不只写在文档里）：
-> CLI 只覆盖读操作与少数任务操作。建目标、写 Evidence、Replan、建提醒等要接 MCP——
-> 那些涉及确认与上下文，CLI 刻意不做。
+1. **AI 管路线，人决定目的地。** 它不替你决定人生方向。
+2. **每天只推今天。** 每日任务次日必定过期，绝不顺延成跨天债务。
+3. **不编数值。** 进度只用可核对的事实表达；任何"属性值 / 掌握度 % / 自律分 / 等级"都会被测试拦下。
-## 安装
+## 你会看到什么
-**设计原则：开发与生产是同一条全局命令，数据始终在 `~/.ai-growth`。**
-CLI / MCP / daemon / 面板都指向「全局安装的那一份」，所以**更新 = 替换全局包**，数据不受影响。
+- **面板**：`http://localhost:4580`，网页形态，也可以当桌面组件（`?layout=widget`）
+- **对话**：平时你就是在 Agent 里说一句话，不必打开面板
+- **可选的小屏**：把今天推给 AI Passport 设备，做完按一下，卡片立刻变成完成态
-```bash
-cd "该项目目录"
-./scripts/install.sh              # 默认开发态：npm link（全局 ai-growth → 当前源码）
-./scripts/install.sh --global     # 生产态：npm pack + npm install -g（与源码检出解耦）
-```
+![设备端卡面](docs/images/cards.png)
-安装脚本 9 步：环境检查 → 依赖 → 构建 → **全局安装** → 数据库迁移
-→ launchd 常驻服务（指向全局 CLI）→ MCP 配置 → Agent 入口说明 → doctor。
+<sub>图为设备端「今日任务卡」的全部卡面，与运行时同一套模板渲染。</sub>
-### 更新
+## 常见问题
-| 形态 | 怎么更新 |
+| 问题 | 回答 |
 |---|---|
-| 开发态（`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`。
-### 桌面组件 / 打包成桌面应用
+| 我的数据在哪？ | `~/.ai-growth/growth.db`（本地 SQLite）。代码包与数据完全分离，更新不影响数据 |
+| 需要注册账号吗？ | **不需要**。没有账号体系，也没有任何上传；服务只监听本机 |
+| 一定要用 MCP 吗？ | 不一定。Agent 不支持 MCP 时可用 CLI（`ai-growth status/today/complete`，全部支持 `--json`） |
+| 会不会给我打自律分？ | 不会。这是硬规则，见上文第 3 条 |
+| 怎么卸载？ | 见 [安装与使用](./docs/usage.md) 里的「卸载 / 重置」 |
-面板已为桌面形态预留两件事：
+## 给 Agent
-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
-```
+**Agent 请读 [`AGENTS.md`](./AGENTS.md)**（主入口）；行为准则是 [`SKILL.md`](./SKILL.md)；精简索引是 [`llms.txt`](./llms.txt)。
-## 相关文档
+## 进一步阅读
-| 文件 | 给谁看 |
+| 文档 | 内容 |
 |---|---|
-| [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 的精简索引 |
+| [`START-HERE.md`](./START-HERE.md) | 第一次使用：3 步 + 该对 Agent 说什么 |
+| [`docs/usage.md`](./docs/usage.md) | 安装与使用细节：接入 Agent、面板与桌面组件、设备、数据位置、卸载、故障排查 |
+| [`docs/agent.md`](./docs/agent.md) | 给 Agent / 自动化：自动发现清单与 CLI 参考 |
+| [`docs/development.md`](./docs/development.md) | 开发、架构约定、当前限制、参与贡献 |
+| [`PRODUCT_SPEC.md`](./PRODUCT_SPEC.md) | 完整产品规范（想知道"为什么这么设计"） |
 ## 许可

package/docs/agent.md ADDED Viewed

@@ -0,0 +1,49 @@
+# 给 Agent / 自动化用
+> Agent 的主入口是 [AGENTS.md](../AGENTS.md)，行为准则是 [SKILL.md](../SKILL.md)，
+> 精简索引是 [llms.txt](../llms.txt)。本文是自动发现与 CLI 参考。
+## 给 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 刻意不做。

package/docs/development.md ADDED Viewed

@@ -0,0 +1,74 @@
+# 开发与贡献
+> 架构约定、当前限制、提交规范。
+## 开发
+```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
+```

package/docs/usage.md ADDED Viewed

@@ -0,0 +1,188 @@
+# 安装与使用
+> 本文是 README 里"细节部分"的完整版（安装、接入、面板、设备、数据、卸载、排查）。
+> 想快速上手，看 [README](../README.md) 的「3 分钟开始」。
+## 安装
+**设计原则：开发与生产是同一条全局命令，数据始终在 `~/.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 分钟无操作会自动熄屏，按任意键立刻亮回。
+---
+## 数据位置
+| 内容 | 路径 |
+|---|---|
+| 数据库 | `~/.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 拦） |

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "ai-growth",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Agent-native、Local-first 的个人成长执行系统：AI 维护计划，人保留目标与最终确认权。",
   "mcpName": "io.github.lairey-ai/ai-growth",
   "type": "module",
@@ -33,7 +33,7 @@
     "dist/",
     "scripts/",
     "launchd/",
-    "docs/images/",
+    "docs/",
     "SKILL.md",
     "AGENTS.md",
     "START-HERE.md",

package/server.json CHANGED Viewed

@@ -3,7 +3,7 @@
   "name": "io.github.lairey-ai/ai-growth",
   "title": "AI Growth",
   "description": "Agent-native 的个人成长执行系统：访谈定目标、动态生成每日少量任务、跨天自动作废旧任务、用真实证据积累成长记录，并同步为可迁移的 AI Passport。",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "websiteUrl": "https://github.com/lairey-ai/ai-growth",
   "repository": {
     "url": "https://github.com/lairey-ai/ai-growth",
@@ -14,7 +14,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "ai-growth",
-      "version": "1.1.0",
+      "version": "1.1.1",
       "transport": {
         "type": "stdio"
       },