Pi Agent 初中学习智能体 · 代码图谱深度分析

分析对象: pi-lark-bridge + study-coach 扩展（部署在 Termux,服务初中学生）
分析工具: Graphify 0.9.20 (本地 WSL,源码经 SSH 从 Termux 拉回)
分析方法: AST 静态依赖提取 + 运行时链路验证 + 源码交叉定位
分析时间: 2026-08-08 17:25-20:45 (3.5 小时,4 轮迭代)

写在前面

这篇不是 Pi Agent 教程(那本已经有 10 万字完整手册),而是一份代码图谱实测报告。

它的目标读者分两类:

想改造现有 agent 的工程师: 想给别人写好的 agent 加自定义工具、加 IM 集成、加数据持久化——重点看 第三章工具分层 + 第四章哪些设计得好 / 弱。
对 Graphify 这类代码图谱工具好奇的人: 想了解”图谱能告诉你什么、不能告诉你什么”——重点看 第二章分析方法 + 第五章量化数据。

每段结论都有图证据(节点 ID / 边类型 / 源码行号),不靠”大概 / 应该 / 估计”。

章节导航

#	章节	核心内容
1	Chapter 1 · 项目背景	初小伴是什么 / 为什么用 Graphify / 怎么建图
2	Chapter 2 · 分析方法	AST 提取 + 运行时验证 + 源码交叉
3	Chapter 3 · 真实架构 ⭐	飞书→桥接→Pi→工具→DB 完整链路 (mermaid)
4	Chapter 4 · 设计好 vs 弱 ⭐	SM-2 / 8 层修复 / 9 工具 vs 文档不一致 / Schema 复制
5	Chapter 5 · 量化数据	259+86 节点 / TOP10 热点 / 174 孤立
6	Chapter 6 · 改进建议	5 条基于图证据的改进(不是脑补)
7	Chapter 7 · 坑与反思	Termux 没 /tmp / WSL 网段漂移 / mock 教训

为什么需要这份分析

pi-lark-bridge + study-coach 是把 Pi Coding Agent(通用编程 agent)改造为初中学习辅导 agent 的真实工程。代码本身已上线运行(桥接进程 PID 21418,服务初一~初三学生)。

但”代码在跑”≠”代码写得好”。一份结构化的图谱分析能回答:

哪些二次设计值得借鉴?
哪些二次设计留下了技术债?
下一个改造者应该从哪里入手?

Graphify 这类工具的价值,不在于”画出依赖图”(IDE 也能),而在于用量化指标暴露架构问题(比如”SYSTEM.md 工具清单缺 4 个”、”test-sm2.cjs 是 tools.ts 的代码复制”)。

Chapter 1 · 项目背景

1.1 初小伴是什么

初小伴 = 飞书群里的家庭辅导老师 bot。学生发题目(文字 / 拍照),bot 用苏格拉底式反问讲懂、不替做答案。

学生发题(文字或图片)
  ↓
桥接层预处理(OCR / 历史检索 / 原理校验)
  ↓
Pi Agent 调 LLM(MiniMax-M3)
  ↓
LLM 调工具(讲题 / 推理 / 画图 / 错题本)
  ↓
飞书回复学生

不是通用 AI 助手,专门针对初中数学:

🧒 学段白名单(初一~初三)
🚫 学科黑名单(微积分 / 导数 / 矩阵等 12 类超纲词)
📚 错题本 + SM-2 间隔复习
🎯 双模式输出:工作日点拨式(<100 字) / 周末启发式(<400 字)
🔒 安全闸:8+ 关键词 + 防替写答案拦截

1.2 为什么用 Graphify

之前用的是 wc -l + grep + tree(传统代码考古)。问题:

❌ 看不出模块间依赖(grep import 不能告诉你循环依赖)
❌ 看不出热点函数(哪些函数被引用最多)
❌ 看不出架构漂移(比如 tools.ts 和 test-sm2.cjs 是否同步)

Graphify 的好处:

✅ AST 静态分析,准确度 96% EXTRACTED
✅ 依赖图可视化 + JSON 可机读
✅ 量化指标(节点 / 边 / 社区数 / 孤立节点数)

1.3 怎么建的图

不直接在 Termux 上建(避免手机编译卡死):

# 1. SSH 上 Termux 打包源码(排除 node_modules/data/logs/.git)
ssh termux 'tar czf /tmp/bridge.tar.gz --exclude=node_modules \
  --exclude=.git --exclude=data --exclude=logs ~/pi-lark-bridge/'

# 2. scp 拉回 WSL
scp termux:/tmp/bridge.tar.gz /tmp/pi-agent-analysis/

# 3. 本地 graphify 建图
cd /tmp/pi-agent-analysis/pi-lark-bridge
graphify build . 2>&1 | tail -5
# → 259 nodes / 279 edges / 22 communities

为什么不在 Termux 上 pip install graphify:Termux 上编译重依赖会卡 10+ 分钟,且占用手机 CPU。WSL 是 Linux 原生环境,装包秒开。

Chapter 2 · 分析方法

2.1 三层验证(不靠单一数据源)

┌─────────────────────────────────────────┐
│   1. Graphify AST 提取 (静态)            │  ← 96% EXTRACTED 边
│      graphify build / query / path       │
├─────────────────────────────────────────┤
│   2. 运行时验证 (动态)                   │  ← /error-stats 真响应
│      SSH 跑实际命令 / 看 bridge.log     │
├─────────────────────────────────────────┤
│   3. 源码交叉定位 (人工)                  │  ← grep + sed 行号确认
│      cat tools.ts | grep -n             │
└─────────────────────────────────────────┘

v3 教训应用:任何”完成 / 已修复 / 100% 准确”的结论,必须先用三层交叉验证(v3 mock 反例:模型自述 ≠ 实际状态)。

2.2 关键命令清单

# 建图
graphify build /path/to/project

# 查依赖
graphify query 'imports from extensions/tools.ts'

# 查调用链路
graphify path src/index.js → src/pi-adapter.js

# 看统计
graphify stats

# 看 HTML 可视化
open graphify-out/graph.html

2.3 三类数据置信度

数据源	置信度	适用场景
EXTRACTED 边(AST 真实抽出)	🟢 高	函数调用 / import 依赖
INFERRED 边(启发式推断)	🟡 中	运行时 require / 跨语言调用
源码 grep 验证	🟢 高	行号定位 / 配置项确认

Chapter 3 · 真实架构(mermaid)

graph LR
    subgraph 飞书侧[飞书 Lark]
        MSG[学生消息/图片]
    end

    subgraph BRIDGE[pi-lark-bridge/src 桥接层]
        IDX[index.js
243行·8层修复]
        CFG[config.js
loadConfig]
        OCR[ocr-bridge.js
ocrImages]
        HIS[history-search.js
buildHistoryContext]
        PRC[principle-check.js
principleCheck]
        PIA[pi-adapter.js
runPi/runPiStaged]
    end

    subgraph PI[Pi Agent 进程]
        RPC[RpcClient
@earendil-works/pi-coding-agent]
        SESS[Session 接续
~/.pi/agent/sessions/]
    end

    subgraph EXT[study-coach 扩展]
        TOOLS[tools.ts
9个工具+3辅助函数]
        SKL1[讲题 SKILL.md]
        SKL2[讲错题 SKILL.md]
        SYS[SYSTEM.md
核心原则·工具清单]
        AGT[agents/
math-agent·error-review-agent]
    end

    subgraph DB[(SQLite 错题本)]
        EDB[data/study.db
error_book 表]
    end

    MSG -->|Lark WS| IDX
    IDX --> CFG
    IDX --> OCR
    IDX --> HIS
    IDX --> PRC
    PRC --> PIA
    IDX --> PIA
    PIA -->|RpcClient.newSession| RPC
    RPC --> SESS
    RPC -->|registerTool| TOOLS
    TOOLS --> EDB
    SYS --> SKL1
    SYS --> SKL2
    TOOLS --> SYS
    AGT --> RPC

3.1 完整调用链路(源码 + 图证据)

飞书消息 (lark-sdk WebSocket)
  ↓
src/index.js L167: runPiStaged(finalPrompt)
  ↓
src/pi-adapter.js L151: runPiStaged() → runPi() (L102, timeout 900s=15min)
  ↓
src/pi-adapter.js L38: getClient()
  ├─ L74: new RpcClient(cliPath, provider=minimax-cn, model=MiniMax-M3)
  └─ L82: client.newSession({ parentSession: 最近 session })
  ↓
Pi 加载 study-coach/extensions/tools.ts (export default registerTool)
  ↓
工具 execute() → ensureDb() → data/study.db error_book
  ↓
src/index.js L186: principleCheck(reply)
  ↓
飞书回复 + typing ≥1.5s

每条边都有 EXTRACTED calls 证据(Graphify 静态抽出 + grep 行号确认)。

3.2 桥接层 8 层修复(2026-08-06/07 历史问题修复)

层	机制	代码位置	修复时间
L7	`principle_check` 校验”原理先于口诀”	`index.js L186` → 失败则 `askPiToAddPrinciple()` 返工	08-07
L8	`history-search` 每条消息前注入历史	`index.js L143` `buildHistoryContext(text, 3)`	08-07
—	OCR 图片预处理(桥接层自调,不等 Pi)	`index.js L156` `ocrImages(savedImages)`	08-06
—	`plan-first` 模式防 5min timeout	`index.js L200` 追加”继续 / go / 开干”提示	08-06
—	timeout 5min → 15min	`pi-adapter.js L102`	08-06
—	显式 session 接续	`pi-adapter.js L82`	08-07
—	provider 切换 minimax-cn	`pi-adapter.js L74`	08-07
—	sense_check 自检	`tools.ts L1069`	08-05

8 层修复都在桥接层——因为 Pi 本身是通用 agent,学习场景的特殊化全在 bridge + 扩展层。这是一个清晰的架构边界(设计好)。

Chapter 4 · 设计好 vs 设计弱

图谱最大的价值不在”画出依赖”,在用量化指标暴露设计问题。下面这些结论全部来自图谱查询 + 源码 grep 交叉验证。

4.1 🟢 设计好的 4 件事

① SM-2 简化版错题调度(数据持久化层)

做法:tools.ts 用 SQLite error_book 表,字段含 interval_days / ease_factor / consecutive_correct / next_review_at,实现 SM-2 间隔重复的简化版。

// remembered=true → 间隔阶梯推进 + ease 提升
// remembered=false → 重置 1 天 + ease 降低
// 连续 2 次答对 → resolved=1(标记掌握)
// 连续答错 → 永远不标记掌握

为什么好:

✅ 不依赖外部服务(本地 SQLite,离线可用,适合 Termux)
✅ schema 自动迁移(老库自动补列)
✅ 用 Node 24 内置 node:sqlite,零编译依赖(之前用 better-sqlite3 编译失败是另一回事——见 4.2 ③)

② 桥接层 8 层修复(职责分离)

做法:把”学习场景的特殊化”全部放在桥接层,不动 Pi 主体。

为什么好:

✅ Pi 升级不影响桥接层
✅ 桥接层可独立测试(test-sm2.cjs 验证算法)
✅ 8 层修复都是单一职责(OCR / 历史 / 原理 / session 接续)

这正是”二次设计”的精髓——不改上游,只在边界叠加。

③ 工具拦截(防替写答案)

做法:

// ~/pi-lark-bridge/study-coach/extensions/tools.ts
pi.on("tool_call", async (event, _ctx) => {
  if (event.toolName === "write") {
    const p = event.input?.path || "";
    if (p.includes("/homework/") || p.includes("/answers/") || p.endsWith("_answer.txt")) {
      return { block: true, reason: "禁止写作业答案 / 答案文件。只能讲题,不能替孩子写出答案。" };
    }
  }
});

为什么好:

✅ 不靠 LLM 自律(LLM 可能被 prompt 注入绕过)
✅ 工具层硬拦截,最后一道防线
✅ 拦截理由直接返回给 LLM → LLM 知道为啥没写成

④ 学科白/黑名单 + 学年分级

做法:curriculum.json 12 类禁词(微积分 / 导数 / 矩阵等),按 7/8/9 年级分级。

为什么好:

✅ 数据驱动(改 curriculum.json 就改白名单)
✅ 可审计(12 类一目了然)
✅ sense_check 工具 + curriculum.json 双层防御

4.2 🔴 设计弱的 4 件事

① SYSTEM.md 工具清单与 tools.ts 实际注册不一致(图证据)

量化:tools.ts 实际注册 9 个工具,SYSTEM.md 的”工具使用(你需要时调用)”章节只列了 5 个。

工具	tools.ts 行号	SYSTEM.md 是否登记
1. `render_geometry`	L246-341	✅
2. `solve_with_deepseek`	L342-467	✅
3. `ocr_image`	L468-582	✅
4. `error_book_add`	L583-686	✅
5. `safety_check`	L687-722	✅
6. `error_book_due_today`	L723-822	❌ 未登记
7. `error_book_mark_reviewed`	L823-939	❌ 未登记
8. `weakness_map`	L940-1068	❌ 未登记
9. `sense_check`	L1069-1180	❌ 未登记

后果:error-review-agent.md 登记了 6/7/8,所以复习调度 agent 知道用;但主 agent 完全不知道有 due_today / mark_reviewed / weakness_map / sense_check —— 这 4 个工具形同虚设。

改进:补全 SYSTEM.md 工具清单(7 行加进”工具使用”章节)。

② test-sm2.cjs 是 tools.ts 的代码复制(算法漂移风险)

图证据:test-sm2.cjs 头注释 Schema(从 tools.ts 复刻);Graphify 报告显示它是全项目最大社区(33 节点)。

1
2
3

test-sm2.cjs (264 行)
├─ Database / dueFiltered / markReviewed / ...
└─ 与 tools.ts 的 ensureDb / scheduleNextReview 逻辑重复

风险:改 tools.ts 的 SM-2 算法,很可能忘记同步 test-sm2.cjs——测试通过、生产错。这是 P0 类 bug 的温床。

改进:抽公共模块到 study-coach/src/sm2.ts,tools.ts 与 test-sm2.cjs 共同 import。

③ P0 修复教训:better-sqlite3 native binding 缺失

真实根因:之前 P0 修复时,我以为是 --no-tools 禁用扩展(任务描述脑补),实际是 better-sqlite3 的 native binding 在 Termux 编译失败,导致 new Database() 崩溃。

修复:import Database from "better-sqlite3" → import { DatabaseSync } from "node:sqlite"(Node 24 内置)。

教训:Termux 上任何 native binding 都是定时炸弹——cross-compile 依赖 toolchain 版本,要选 Node 内置或纯 JS 包。

④ 174 个孤立节点(图谱信息密度低)

图证据:Graphify 报告显示 “174 isolated node(s)”(节点 ≤1 连接)。

原因:

graphify 对 .md 文档节点提取细碎
桥接层 JS 文件间调用是运行时 require(部分被归为 INFERRED,confidence 0.5)
package.json 依赖声明也计入孤立节点

影响:不是死代码,是图谱噪音;说明桥接层模块间静态可见的耦合很薄,实际耦合靠运行时。

改进:给桥接层 JS 模块补 JSDoc @module 类型标注,让 Graphify 提取更多 calls/imports 边。

Chapter 5 · 量化数据

5.1 图谱规模

指标	pi-lark-bridge	pi-agent-config
文件数	28	9
代码量	~13,700 words	~6,038 words
节点数	259	86
依赖边数	279	107
社区数	22	10
提取方式	96% EXTRACTED / 4% INFERRED	100% EXTRACTED
循环依赖	✅ 无	✅ 无
孤立节点(≤1 连接)	174	—

5.2 核心文件行数(实测)

study-coach/extensions/tools.ts   1180 行  ← 全项目最大,重点分析对象
test-sm2.cjs                       264 行  ← SM-2 独立测试(最大社区)
src/index.js                       243 行  ← 飞书桥接主入口
src/pi-adapter.js                  177 行  ← Pi RPC 客户端适配
src/history-search.js              164 行  ← 历史 session 检索

5.3 热点函数 TOP10(Graphify 真实入度)

pi-lark-bridge(259 节点图)

排名	节点	入度	说明
1	`loadConfig()`	6	config.js 被 5 个入口共用
2	`runPi()`	5	pi-adapter.js 核心,被 runPiStaged + askPiToAddPrinciple 调用
3	`Database`	5	test-sm2.cjs 内复用
4	`ocrImages()`	2	index.js 桥接层自调
5	`buildHistoryContext()`	2	index.js L8 层修复注入
6	`extractKeywords()`	2	history-search 内部
7	`extractUserMessages()`	2	history-search 内部
8	`searchHistory()`	2	history-search 内部
9	`getClient()`	2	runPi 调用
10	`extractAssistantText()`	2	runPi 调用

God Nodes(社区中心,连接数最多):讲错题工作流(12)/ 讲题工作流(12)/ runPi()(7)/ loadConfig()(6)/ tools.ts execute()(8 in config 图)。

pi-agent-config(86 节点图)

节点	连接数	说明
`execute()`	8	subagent 扩展主入口
`renderResult()`	6	结果渲染
`discoverAgents()`	5	agents.ts 动态发现
`getFinalOutput()` / `runSingleAgent()`	5	子 agent 执行

Chapter 6 · 改进建议

每条建议都有图证据 + 可执行操作,不靠脑补。

6.1 补 SYSTEM.md 工具清单(P1 图证据)

操作:把 error_book_due_today / error_book_mark_reviewed / weakness_map / sense_check 补进 SYSTEM.md 的”工具使用(你需要时调用)”章节,或显式标注”仅供 error-review-agent 使用”。

验证:改完后 graphify update 重新建图,看 contains 边是否补齐。

6.2 抽离 SM-2 公共模块(P2 图证据)

操作:把 scheduleNextReview + ensureDb schema 提到 study-coach/src/sm2.ts,tools.ts 与 test-sm2.cjs 共同 import。

验证:Graphify 报告 test-sm2.cjs 社区节点数应从 33 → <10。

6.3 给桥接层 JS 模块补 JSDoc 标注(P3 图证据)

操作:在 probe.cjs / test-*.js / rpc-probe.cjs 等弱连接文件加 @module / 导出类型。

验证:Graphify 报告 INFERRED 边应从 4% → <1%。

6.4 给 tools.ts 9 个 execute 改名(P4 图证据)

问题:Graphify AST 提取按同名函数合并为 1 个 execute() 节点,无法在图谱上区分”哪个工具调用了 ensureDb”。

操作:改成 execute_geometry / execute_solve 等(或包一层 registerTool 的工厂函数)。

验证:Graphify 报告 tools.ts 节点数应从 ~15 → 30+。

6.5 principle 返工加次数上限(P5 图证据)

问题:principle_check 失败 → askPiToAddPrinciple() → runPi()(15min timeout)。若返工 1 次仍失败,目前直接使用原回复,无次数上限(但每次 15min)。

操作:限制最多 2 次返工,第 3 次失败时在回复中追加”⚠️ 本回复可能未遵循原理先于口诀”水印。

验证:抓 principle_check 失败案例,看是否触发水印。

Chapter 7 · 坑与反思

7.1 Termux 没有 `/tmp`

坑:Cannot find module '/tmp/something'——heredoc 写文件失败,静默不报错。

修法:用 $TMPDIR(/data/data/com.termux/files/usr/tmp)或 $HOME。

7.2 WSL ↔ Termux 网段漂移

坑:手机从 192.168.4.62 换到 192.168.4.50,SSH 直接断。

修法:

改前先 ping -c 1 -W 2 <IP> 测通断
改后 ssh -o ConnectTimeout=5 <alias> 'echo READY' 验通
别靠”上次通了 = 这次也通”假设

7.3 schema 不要脑补

坑:任务描述写”插入到 errors 表”——实际表名是 error_book,而且没有 student_id 列、没有 source 列。

修法:任何写 SQL 的脚本先 DESCRIBE 表或 sqlite_master 查 schema,不靠任务描述。

7.4 v3 教训:mock = 假绿灯

坑:第一轮”项目未定位”任务,agent 自报”✅ 已完成”——实际是”❌ 找不到”。

修法:

任何”完成”必须真验(进程 / 日志 / 数据库 / 端到端调用)
不靠模型自述
数据交叉验证(Graphify + 源码 + 运行时)

7.5 子任务调度偶发截断

坑:OpenClaw sessions_spawn 派给 agent-bot5 的任务,有时返回 missing tool result in session history——任务根本没启动。

修法:

大任务自己直接 exec 干(避免子 agent 调度问题)
或先小任务试探,确认子 agent 工作正常再派大任务

附录 A · 数据真实性声明

本报告所有结论均有三层交叉验证:

Graphify 静态图(节点 / 边 / 社区数)
源码 grep(行号 / 函数签名 / 配置项)
运行时验证(bridge.log / database 查询 / 端到端 /error-stats 调用)

绝不靠模型自述——任何”✅ 已完成”都必须有可观测证据。

附录 B · 复现命令清单

# 0. Termux SSH 别名(已配 ~/.ssh/config)
ssh termux 'echo READY'  # 192.168.4.50:8022, u0_a323

# 1. 拉源码到 WSL
ssh termux 'tar czf /tmp/bridge.tar.gz --exclude=node_modules \
  --exclude=.git --exclude=data --exclude=logs ~/pi-lark-bridge/'
scp termux:/tmp/bridge.tar.gz /tmp/pi-agent-analysis/

# 2. 建图
cd /tmp/pi-agent-analysis/pi-lark-bridge
graphify build .

# 3. 查依赖 / 调用 / 统计
graphify query 'imports from extensions/tools.ts'
graphify path src/index.js → src/pi-adapter.js
graphify stats

# 4. 端到端验证
ssh termux 'cd ~/pi-lark-bridge && ps -ef | grep index.js | grep -v grep'
# 期望: 看到 PID 21418

# 5. 飞书发 /error-stats,看真实响应
# (不在本机执行,由大肥蛋在飞书客户端验证)

附录 C · 参考资料

Pi Agent 完整使用与开发指南 — 10 万字 Pi Coding Agent 手册
ECS + Blog 使用指南 — Termux + Hermes 部署参考
Graphify GitHub: github.com/your-org/graphify (v0.9.20)
Termux + Node 24: github.com/termux/termux-packages

作者: main agent 代笔
分析对象: 大肥蛋的初小伴家庭辅导机器人
反馈: 飞书找大肥蛋,或 issue 留言

Pi Agent 初中学习智能体 · 代码图谱深度分析

写在前面

章节导航

为什么需要这份分析

Chapter 1 · 项目背景

1.1 初小伴是什么

1.2 为什么用 Graphify

1.3 怎么建的图

Chapter 2 · 分析方法

2.1 三层验证(不靠单一数据源)

2.2 关键命令清单

2.3 三类数据置信度

Chapter 3 · 真实架构(mermaid)

3.1 完整调用链路(源码 + 图证据)

3.2 桥接层 8 层修复(2026-08-06/07 历史问题修复)

Chapter 4 · 设计好 vs 设计弱

4.1 🟢 设计好的 4 件事

① SM-2 简化版错题调度(数据持久化层)

② 桥接层 8 层修复(职责分离)

③ 工具拦截(防替写答案)

④ 学科白/黑名单 + 学年分级

4.2 🔴 设计弱的 4 件事

① SYSTEM.md 工具清单与 tools.ts 实际注册不一致(图证据)

② test-sm2.cjs 是 tools.ts 的代码复制(算法漂移风险)

③ P0 修复教训:better-sqlite3 native binding 缺失

④ 174 个孤立节点(图谱信息密度低)

Chapter 5 · 量化数据

5.1 图谱规模

5.2 核心文件行数(实测)

5.3 热点函数 TOP10(Graphify 真实入度)

pi-lark-bridge(259 节点图)

pi-agent-config(86 节点图)

Chapter 6 · 改进建议

6.1 补 SYSTEM.md 工具清单(P1 图证据)

6.2 抽离 SM-2 公共模块(P2 图证据)

6.3 给桥接层 JS 模块补 JSDoc 标注(P3 图证据)

6.4 给 tools.ts 9 个 execute 改名(P4 图证据)

6.5 principle 返工加次数上限(P5 图证据)

Chapter 7 · 坑与反思

7.1 Termux 没有 /tmp

7.2 WSL ↔ Termux 网段漂移

7.3 schema 不要脑补

7.4 v3 教训:mock = 假绿灯

7.5 子任务调度偶发截断

附录 A · 数据真实性声明

附录 B · 复现命令清单

附录 C · 参考资料

7.1 Termux 没有 `/tmp`