内容
# Parent Compass / 养育罗盘
养育罗盘是本地优先、单用户、离线运行的儿童观察与 PBL 项目工作台。主要入口是 AI agent 通过 MCP 写入和维护本机 SQLite；网页只是审计 view，用来浏览 raw logs、洞察、PBL 项目和发展图谱。
默认无鉴权，适合本机或可信内网使用。不要把它裸露到公网。
## 它适合什么场景
Parent Compass 面向愿意用 AI agent 做家庭观察助手的家长。它不替你给孩子打分，也不把发展变成 KPI；它帮助你把日常片段保存下来，让 agent 从证据里整理出可追溯的理解和下一步陪伴建议。
典型场景：
- **记录日常观察**：孩子洗澡时反复倒水、搭积木时坚持调整结构、和同伴冲突后尝试协商，这些零散片段可以通过 agent 写成结构化观察日志。
- **从日志生成养育洞察**：agent 可以把多条观察连接到语言、身体、情绪、探索、执行、创造、社会关系、成人环境等维度，解释“这个行为可能在发展什么”，并保留来源证据。
- **发现最近发展区**：发展图谱会优先展示孩子已经点亮、正在靠近、以及下一步可能被支架支持的能力，而不是展示一张冷冰冰的完整能力清单。
- **把兴趣转成 PBL 小项目**：当孩子持续对水、影子、符号、工具、规则或角色游戏感兴趣时，agent 可以基于已有洞察生成一个轻量项目，包含为什么现在适合、可以怎么开始、需要什么材料、要注意什么。
- **审计 AI 写了什么**：网页不是主要输入口，而是家长检查 agent 工作的地方。你可以看到原始日志、洞察、项目、来源快照和发展图谱关系，发现不对就让 agent 修改。
- **保护家庭数据**：默认数据留在本机 SQLite，不依赖云端账号；适合本地单用户或可信内网使用。
## 可以配合哪些 Agent
Parent Compass 不绑定某一个 AI 客户端。常见的本地 agent 都可以接入，例如 Codex、Claude Code、OpenClaw、Hermes 等。
接入条件很简单：
- agent 能配置 stdio MCP server；
- agent 能读取或安装本项目的 `.agents/skills/`；
- 家长把观察和修改意见告诉 agent，agent 通过 MCP 写入本地数据库。
## 快速开始
面向 agent 的首次部署，可以直接让 agent 使用仓库里的安装引导 skill：
```text
请使用这个项目里的 pbl-install-guide skill，帮我部署和连接 Parent Compass / 养育罗盘：https://github.com/oralzl/parent-compass
```
完整安装说明见 [docs/agent-installation.md](docs/agent-installation.md)。
```bash
npm install
npm run dev
```
打开终端显示的本地地址，通常是：
```text
http://127.0.0.1:3000
```
首次 API 或 MCP 调用会自动初始化 SQLite schema，并在空库时创建 active child：`默认孩子`。网页侧边栏可以轻量修改孩子名字。
`npm run setup` 仍然保留，但只是可选的本地准备/诊断命令：
```bash
npm run setup
```
它会确保数据库和默认孩子存在，并打印数据库路径、active child、token 鉴权状态和下一步命令。
## MCP 主入口
给 agent 配置本仓库的 MCP server，建议命名为 `parent-compass`：
```bash
npm run mcp
```
MCP server 使用 stdio，本地读写默认数据库：
```text
data/pbl-so.sqlite
```
常用工具包括：
- `create_raw_log`
- `list_raw_logs`
- `create_insight`
- `list_insights`
- `create_pbl_project`
- `list_pbl_projects`
- `get_child_development_map`
- `list_tech_tree_nodes`
- `get_tech_tree_node`
没有 active child 时，MCP 会自动准备 `默认孩子`，所以 agent 第一条调用不需要先手动建档案。
## 网页审计 View
网页用于审计和浏览：
- 养育日志
- 养育洞察
- PBL 项目
- 发展图谱
- 洞察/项目的来源快照
网页默认不需要 token。它会直接请求本地 API，并在空库时触发自动初始化。
## 可选 Token 保护
如果你要把网页放到家庭局域网、Tailscale、NAS 或其他非单机环境，可以手动设置 `LOCAL_AUTH_TOKEN`：
```bash
cat > .env.local <<'EOF'
LOCAL_AUTH_TOKEN=replace-with-a-long-random-token
DATABASE_URL=file:data/pbl-so.sqlite
EOF
```
设置后：
- API 请求必须带 `Authorization: Bearer <token>`。
- 网页首次请求会显示 token 输入页。
- MCP 仍然是本地 stdio，不走 HTTP token。
更推荐的公网保护方式是反代鉴权、Tailscale、Cloudflare Access 或 Basic Auth。不要裸露默认无鉴权实例。
## 数据文件
- `data/pbl-so.sqlite`：个人本地数据，不应提交。
- `data/child-development-tech-tree.db`：内置儿童发展能力图谱，可以随 repo 更新。
更新内置图谱时，用户 `git pull` 即可拿到新版图谱；个人观察、洞察、点亮状态继续留在 `data/pbl-so.sqlite`，不会被覆盖。
维护图谱时请保持已有 node id 稳定。删除能力节点前，优先考虑 deprecated/disabled 策略，避免用户本地 flags 或 insight links 指向孤儿节点。
## Demo 数据
默认不会自动写入 demo 数据。想体验完整界面时可以手动运行：
```bash
npm run db:seed
```
软删除 demo 数据：
```bash
npm run db:clear-demo
```
Demo 数据使用 `metadata.demo = true` 或等价标记，清理命令不会删除真实数据。
## API 示例
默认无 token：
```bash
BASE=http://127.0.0.1:3000
curl "$BASE/api/children"
```
如果设置了 `LOCAL_AUTH_TOKEN`：
```bash
TOKEN=你的本地token
BASE=http://127.0.0.1:3000
curl "$BASE/api/children" -H "Authorization: Bearer $TOKEN"
```
创建 RawLog：
```bash
curl -X POST "$BASE/api/raw-logs" \
-H "Content-Type: application/json" \
${TOKEN:+-H "Authorization: Bearer $TOKEN"} \
-d '{
"content": "今天洗澡时反复把杯子装满再倒掉。",
"source": "manual_web",
"scene": "洗澡",
"participants": ["孩子", "爸爸"],
"metadata": {}
}'
```
不传 `child_id` 时会写入当前 active child。
## 验证
```bash
npm run typecheck
npm run verify
npm run build
```
手动验收清单见 [docs/verification.md](docs/verification.md)。
