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：

请使用这个项目里的 pbl-install-guide skill，帮我部署和连接 Parent Compass / 养育罗盘：https://github.com/oralzl/parent-compass

完整安装说明见 docs/agent-installation.md。

npm install
npm run dev

打开终端显示的本地地址，通常是：

http://127.0.0.1:3000

首次 API 或 MCP 调用会自动初始化 SQLite schema，并在空库时创建 active child：默认孩子。网页侧边栏可以轻量修改孩子名字。

npm run setup 仍然保留，但只是可选的本地准备/诊断命令：

npm run setup

它会确保数据库和默认孩子存在，并打印数据库路径、active child、token 鉴权状态和下一步命令。

MCP 主入口

给 agent 配置本仓库的 MCP server，建议命名为 parent-compass：

npm run mcp

MCP server 使用 stdio，本地读写默认数据库：

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：

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 数据。想体验完整界面时可以手动运行：

npm run db:seed

软删除 demo 数据：

npm run db:clear-demo

Demo 数据使用 metadata.demo = true 或等价标记，清理命令不会删除真实数据。

API 示例

默认无 token：

BASE=http://127.0.0.1:3000
curl "$BASE/api/children"

如果设置了 LOCAL_AUTH_TOKEN：

TOKEN=你的本地token
BASE=http://127.0.0.1:3000
curl "$BASE/api/children" -H "Authorization: Bearer $TOKEN"

创建 RawLog：

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。

验证

npm run typecheck
npm run verify
npm run build

手动验收清单见 docs/verification.md。