pi-learning-agent 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# 变更记录
+
+## 0.1.0 — 2026-09-17
+
+- 修复模型只调用评分工具时工作台看不到判定与讲解的问题；评分工具要求提供讲解，并在成功后同步反馈。
+- 修正状态提示：评分不再显示等待回答，工具执行结束不再误报整轮讲解结束。
+- 修复单选题数字或字母快捷键选中后焦点不同步，确保方向键从当前选项继续导航。
+- 修复切换主题等待旧题、合法概念名评分失败和评分证据类型不匹配的问题。
+- 保留 Markdown、代码转义和公式结构，避免中文输入法确认候选时误提交；补齐 SSE 先到时的题干。
+- 修复 Monaco 只读区随编辑及草稿刷新后的定位，并保证 Reset 显示与提交一致；增加不调用模型的真实浏览器回归。
+- 停服关闭活动 HTTP 连接，并通知正在执行的本地自测取消。
+
+- 统一评分、重置和 Pi 会话切换的生命周期，阻止跳过题目、重置前旧题和其他会话的旧题计分。
+- Extension 与 Web 共用学习协议和状态类型，发布包包含 `shared/`。
+- 修复旧 HTTP 快照覆盖 SSE 状态、页面退出后旧初始化重新连接的问题。
+- Windows 取消代码运行时等待进程关闭后清理临时目录。
+- 增加真实 tarball 离线安装、Pi 加载、Web 脚本和 Monaco worker 验收。
+- 日常测试与发布检查分开，增加 Windows/Linux、Node.js 22/24 的持续集成配置。
+- 补充贡献、架构、安全和发布文档，明确社区扩展身份与 MIT 许可证。

package/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# 参与贡献
+
+本项目是使用 Pi 官方包格式分发的 MIT 社区扩展。开发基线为 Pi 0.84.0、Node.js >=22.19.0 与 npm >=11。
+
+## 开发与验证
+
+根 `package-lock.json` 管理整个 npm workspace。不要在 `web/` 新建第二份锁文件。
+
+```sh
+npm ci
+npm run check
+npm run build:web
+npm run pi
+```
+
+在 Pi 中运行 `/learn rust trait bounds`。完整交互需要扩展提供的本地 HTTP/SSE 与会话 token。
+
+`npm run check` 包含两端类型检查以及日常测试，不构建发布包。改动安装、协议、目录或静态资源后运行 `npm run check:package` 和 `npm run smoke`；发布前统一运行 `npm run check:release`。
+
+归档验收会真实打包、在系统临时目录离线安装，再用 Pi 加载包内入口并检查工作台和 Monaco worker；使用独立测试目录，不读取个人 Pi 上下文。
+
+真实模型测试通过 `npm run e2e -- a --timeout 540` 与 `npm run e2e:browser` 单独运行。它们使用 Pi 配置的提供商和凭据，会消耗模型额度；浏览器测试要求 Microsoft Edge。普通持续集成不运行模型 E2E。
+
+`npm run test:workspace` 使用真实 Microsoft Edge 和临时 loopback Vite 服务，通过虚构 API 验证 Monaco 编辑行为，不启动 Pi 或调用模型。修改代码编辑、只读范围或草稿恢复时运行它；配置独立于模型 E2E，目前不加入缺少 Edge 的日常 CI。
+
+## 修改约定
+
+保留结构化 tool result、顺序作答、跳过与取消的区别，以及按当前 Pi 分支恢复状态的语义。涉及协议与发布目录时同时检查 shared、package.json.files 和归档验收。
+
+新增行为通过公开入口测试，避免替换内部 Broker/状态对象或依赖私有函数。按一个行为一次的红—绿—重构循环推进；修复确认的失败后再扩大检查范围。
+
+每次落盘修改在 work.md 记录时间、问题、解决方式、变更文件、验证结果与撤回方式。提交 pull request 时说明具体场景、最终行为、检查结果和剩余限制。
+
+不要提交会话 token、模型凭据、个人学习内容、node_modules、web/dist 或本地 .tgz。敏感问题的处理方式见 [SECURITY.md](SECURITY.md)。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 金琦亮
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+# Pi Learning Agent
+
+**在 Pi 中开启一门课，把讲解、练习和反馈放进同一个学习工作台。**
+
+Pi Learning Agent 是 [Pi Coding Agent](https://pi.dev/) 的社区学习扩展。导师根据课程和主题讲解、出题，你在浏览器或终端中作答；答案作为结构化工具结果返回导师，评估后更新知识点掌握度。
+
+## 界面预览
+
+![Pi Learning 学习工作台：左侧是数据库设计讲解，右侧是自由回答练习](docs/images/learning-workspace.png)
+
+*数据库设计学习示例：左侧回顾导师讲解，右侧完成当前练习；顶栏可展开知识点进度。*
+
+## 可以怎样学习
+
+1. **指定方向**：用 `/learn <课程> <主题>` 开始学习，导师从简短诊断切入。
+2. **理解与练习**：阅读讲解，在当前题目中选择答案、描述思路或编写代码。
+3. **获得反馈**：提交后由导师评阅，再根据表现继续讲解和出题。
+4. **查看进度**：按知识点查看掌握度、尝试次数和正确次数。
+
+### 支持的题型
+
+| 作答形式 | 适合的练习 | 交互方式 |
+| --- | --- | --- |
+| 单选题 | 概念辨析、判断正误、预测代码输出 | 选择一个答案后提交 |
+| 多选题 | 规则判断、选择所有满足条件的情况 | 选择多个答案后提交 |
+| 单行简答 | 短答案、简单填空 | 输入文本，按 Enter 提交 |
+| 多行自由回答 | 解释概念、分析场景、描述解题思路 | 输入多段文本，支持 Ctrl/Cmd+Enter 提交 |
+| 代码题 | 函数实现、代码补全、修改错误 | 在 Monaco 编辑器中作答，支持 Ctrl/Cmd+Enter 提交 |
+
+单行与多行回答共用自由回答工具。选择题可以由导师配置是否允许跳过；多空填空、拖拽排序和连线题尚无专用组件。
+
+### 为专注学习设计
+
+- **可调双栏**：拖动分隔条分配讲解与作答空间，也支持方向键调整；手机端自动切换为上下布局。
+- **阅读不被打断**：在底部时跟随导师输出；向上翻阅后暂停跟随，通过“有新内容”回到最新讲解。
+- **按需查看进度**：顶栏显示阶段和掌握度摘要，详细概念进度在侧栏展开，支持 Escape 关闭。
+- **清晰的内容展示**：区分导师讲解与个人回答，支持流式文本、Markdown、代码块和 KaTeX 公式。
+- **保留作答草稿**：自由回答和代码题的草稿保存在当前浏览器本地，刷新后可以继续编辑。
+- **浏览器与终端衔接**：浏览器连接时优先使用 Web 工作台；没有浏览器或等待作答时断开连接，可回退到终端界面（TUI）。
+
+## 快速开始
+
+最低要求为 **Node.js 22.19.0**。已验证的环境基线是 Node.js 24、npm 11、Pi Coding Agent 0.84.0；CI 覆盖 Windows/Linux 与 Node.js 22/24。开始学习前，请确保 Pi 已配置可用模型。
+
+### 从源码运行
+
+```sh
+git clone https://github.com/marskim1130/pi-learning.git
+cd pi-learning
+npm ci
+npm run build:web
+npm run pi
+```
+
+在启动的 Pi 会话中输入：
+
+```text
+/learn 数据库设计 如何设计出一个好的数据库
+```
+
+也可以尝试：
+
+```text
+/learn rust ownership and borrowing
+/learn 算法 二分查找的边界条件
+```
+
+第一个词是课程，其余文本是主题。扩展会打开浏览器工作台；如果窗口未自动出现，在同一个 Pi 会话中运行 `/learn-open`。工作台链接带有会话 token，请勿公开分享。
+
+### 安装为 Pi 扩展包
+
+完成源码构建后，可将本地目录安装到 Pi：
+
+```sh
+pi install /absolute/path/to/pi-learning
+```
+
+将示例路径替换为本机项目目录；路径含空格时使用引号。
+
+从 npm 安装预构建版本：
+
+```sh
+pi install npm:pi-learning-agent@0.1.0
+```
+
+本项目采用 [Pi 官方包格式](https://pi.dev/docs/latest/packages)。当前支持预构建 npm 包与源码构建流程；Pi 0.84.0 的 Git 安装默认省略开发依赖，因此直接使用 `pi install git:...` 无法获得完整的 Web 工作台。
+
+## 常用命令
+
+| 命令 | 用途 |
+| --- | --- |
+| `/learn <课程> <主题>` | 开始学习并启动导师教学 |
+| `/learn-open` | 打开当前浏览器工作台 |
+| `/learn-status` | 查看课程、主题、阶段和等待中的题目 |
+| `/learn-stop` | 停止学习模式，取消等待中的交互 |
+| `/learn-reset` | 确认后清空当前学习进度和题目资格，保留课程与主题 |
+
+## 工作原理与使用边界
+
+扩展向导师提供以下工具，四个作答工具顺序执行：
+
+| 工具 | 作用 |
+| --- | --- |
+| `learning_ask_single_choice` | 单选题，返回 `optionId` 或结构化跳过结果 |
+| `learning_ask_multi_choice` | 多选题，返回 `optionIds` 或结构化跳过结果 |
+| `learning_ask_free_response` | 单行或多行文本回答 |
+| `learning_ask_code` | 代码作答，返回 `language` 和 `code` |
+| `learning_record_attempt` | 记录导师评估与必填讲解，在工作台显示判定和讲解，更新知识点掌握度 |
+
+回答直接结束对应的工具调用，不会被伪装成新的用户消息。跳过的题目不能计分，已完成评分的题目不能重复评分；重置、停止学习和切换 Pi 分支会释放旧交互。
+
+- **代码评阅**：默认把代码交给导师评阅，不在主机执行。只有宿主显式注入 runner 时才开放支持语言的本地自测；该 runner 不构成沙箱。
+- **编辑器能力**：Monaco 提供代码编辑界面，目前没有 Language Server。
+- **进度保存**：学习状态保存在当前 Pi 分支，尚无跨会话长期学习档案；题目完成凭据保存在进程内，重新加载后不恢复未评分旧题的资格。
+- **连接切换**：Web/TUI 断连切换采用轮询。
+
+完整的安全范围见 [SECURITY.md](SECURITY.md)。
+
+## 开发与验证
+
+| 目录或文件 | 职责 |
+| --- | --- |
+| `web/` | React 工作台、作答组件、草稿和事件状态 |
+| `shared/` | Extension 与 Web 共用的协议和学习状态类型 |
+| `extension/learning-session.ts` | 评分资格、重置与会话生命周期 |
+| `extension/server/` | 题目等待、HTTP/SSE、token 与静态资源 |
+| `extension/tools/` | Pi 工具及 Web/TUI 呈现 |
+
+```sh
+npm run check           # 两端类型检查与日常测试
+npm run test:workspace  # 真实 Edge 工作台回归，虚构 API，不调用模型
+npm run build:web       # 构建浏览器工作台
+npm run check:package   # 构建、归档离线安装与 Pi/资源验收
+npm run smoke           # 真实 Pi RPC 加载，不调用模型
+npm run check:release   # 完整本地发布验收
+npm run release:prepare # 验收后生成可发布 .tgz
+```
+
+真实模型端到端测试单独运行，会消耗模型额度：
+
+```sh
+npm run e2e -- a --timeout 540
+npm run e2e:browser
+```
+
+浏览器端到端测试当前要求 Microsoft Edge。[历史端到端报告](docs/e2e-report.md)记录的是对应阶段的验证结果。
+
+`test:workspace` 独立验证真实 Monaco 的只读区移动、刷新恢复和重置后提交一致性，只启动临时本地服务，不需要模型配置。
+
+更多说明：[架构设计](docs/architecture.md) · [贡献指南](CONTRIBUTING.md) · [发布流程](docs/releasing.md) · [更新记录](CHANGELOG.md)。
+
+## 许可证
+
+[MIT](LICENSE)。这是 Pi Coding Agent 的社区扩展。

package/SECURITY.md

@@ -0,0 +1,9 @@
+# 安全说明
+
+本项目采用 Pi 扩展运行机制，扩展代码拥有宿主进程权限。本地 HTTP 工作台只监听 `127.0.0.1`，使用随机会话 token；不要分享包含 token 的工作台链接。
+
+本扩展默认关闭学习者代码执行。`LocalCodeRunner` 是供受控环境注入的实现：临时目录、环境白名单、超时和输出限制不构成沙箱，也不能阻止代码访问宿主文件、网络或启动其他进程。
+
+学习记录通过 Pi 的会话自定义条目保存。涉及问题诊断时，请先删除 token、模型凭据、个人学习内容和本地敏感路径。
+
+发现漏洞时，请优先使用仓库 GitHub 页面提供的私密漏洞报告入口（如果维护者已启用）。若该入口不可用，请先提交不含漏洞利用细节和敏感数据的问题，联系维护者确定私下沟通方式。项目尚未承诺固定的响应时间。

package/docs/architecture.md

@@ -0,0 +1,75 @@
+# 架构
+
+本项目以 Pi Extension 为运行入口，由本地 Web 工作台与 TUI 接收学习者作答。浏览器不启动模型，也不解析 Tutor 自然语言来猜测题型。
+
+## 模块与依赖
+
+```mermaid
+flowchart TD
+  Pi[Pi 运行时] --> Entry[扩展装配]
+  Entry --> Commands[学习命令]
+  Entry --> Tools[学习工具]
+  Commands --> Session[LearningSession]
+  Tools --> Session
+  Session --> State[LearningStateStore]
+  Session --> Broker[InteractionBroker]
+  Tools --> Presenter[Web / TUI 呈现]
+  Presenter --> Broker
+  Broker --> Transport[本地 HTTP / SSE]
+  Transport --> Web[React 工作台]
+  State --> Persistence[Pi 分支快照]
+  Shared[shared 学习协议] -.类型.-> Tools
+  Shared -.类型.-> Transport
+  Shared -.类型.-> Web
+```
+
+| 位置 | 职责 |
+| --- | --- |
+| shared/protocol.ts、shared/learning-state.ts | 题目、答案、事件与快照的唯一类型定义；无 Node、Pi 或 React 运行时依赖 |
+| extension/learning-session.ts | 评分资格、掌握度、停止、重置与会话清理的协调规则 |
+| extension/state/learning-state.ts | 掌握度算法、已计分账本、快照校验与状态变更 |
+| extension/state/session-persistence.ts | 从当前 Pi 分支恢复最新有效 version=1 快照 |
+| extension/server/interaction-broker.ts | 等待 Promise、答案校验、跳过、取消与有界完成凭据 |
+| extension/server/learning-server.ts | loopback HTTP/SSE、token、请求体限制与包内静态资源 |
+| extension/tools/ | Pi 参数与结果翻译，题目在 Web/TUI 间选择和回退 |
+| web/src/state/store.ts | 连接生命周期、权威快照与事件重放、提交去重、Tutor 流式文本 |
+
+## 作答与评分
+
+四个作答工具顺序执行：呈现题目 → Broker 等待 → Web POST 或 TUI 输入 → 校验 → 返回结构化 tool result。只有用户主动执行的学习命令会发出教学启动消息。
+
+评分工具要求提供非空白的 `explanation`，说明正确答案及关键理由。成功结果将讲解保留在 details，同步层通过 `tutor.message` 将中文判定和讲解一起发送到工作台，因此模型只调用工具时也能显示反馈。讲解不改变掌握度算法或持久化快照；旧评分结果缺少讲解时，仅回退显示已有误区说明。修改加载到 Pi 扩展后用于后续评分，历史记录不会自动补回。
+
+状态提示对应真实教学阶段：仅 `learning_ask_*` 作答工具开始时发送 `waiting`，仅 `agent_settled` 发送 `idle`。评分开始不要求学习者作答，工具返回也不代表整轮讲解结束。
+
+完成凭据仅保留题型和是否跳过，最多 1,000 条，不留存整份代码答案。评分时由 LearningSession 检查题目已完成且没有跳过；LearningStateStore 检查是否重复计分。掌握度算法保持既有规则：初始 0.20、按证据形式调整、限制在 0..1，超过 0.75 需要近期连续正确中出现不同证据形式。
+
+重置学习时清空掌握度/计分账本与完成凭据，并取消等待。停止学习只取消等待、关闭学习模式，保留记录。
+
+切换课程或主题时，命令层先中止旧教学轮次并等待宿主空闲；会话层清除旧题等待和完成凭据后设置新目标。已保存的累计概念进度继续保留。评分证据必须与完成凭据的实际题型一致，错误参数不会消耗评分资格。
+
+## Pi 生命周期与持久化
+
+session_start 与 session_tree 共用恢复路径：取消旧等待、清空进程内题目资格和旧学习状态，再从 ctx.sessionManager.getBranch() 恢复最新有效快照，最后刷新工作台。Pi 原生 /tree 不会把上一分支状态写入新分支。
+
+快照版本仍为 1，兼容缺少可选历史字段的旧数据。完成凭据不持久化；恢复进度不代表恢复旧题的计分资格。shutdown 取消等待并关闭 HTTP/SSE。
+
+关闭服务时同时终止活动 HTTP 连接，响应断开通过 AbortSignal 通知注入的 runner 取消。连接关闭不等于 runner 自身的异步资源清理已经完成。
+
+## 浏览器同步
+
+启动先读取 health 与学习快照，再连接 SSE。连接代次使停止后返回的旧请求失效；请求序号阻止旧刷新覆盖新刷新。
+
+重连使用服务器 pending 快照作为基准，重放请求期间的 presented/resolved/cancelled 和本地提交成功操作。因此既能清除断线时漏掉的旧题，也不会重新显示刚完成的题目。会话字段独立保留请求之后到达的更新。POST 与 SSE 到达顺序不会重复添加 transcript。
+
+提交记录在 SSE 到达时保留当前题干，POST 返回后补齐元数据。Markdown 与数学 token 共用一次解析，统一进行 HTML 消毒，保留代码转义及原段落/列表结构。
+
+Monaco 只读区域跟随装饰范围移动；范围和对应代码作为伴随草稿元数据保存，恢复时检查代码一致及范围有效。旧纯文本草稿仍可读取，缺少有效元数据时沿用题目原始范围。Reset 直接恢复编辑器模型并重建原始只读区，避免显示代码与提交内容分离。
+
+## 分发与验证
+
+pi.extensions 定位入口，files 包含 extension、shared、构建后的 Web 和维护文档。Pi 内置库使用 peerDependencies，浏览器依赖打入静态资源。
+
+正式支持 npm 预构建包与本地源码构建。Pi 0.84.0 的 Git 安装省略 devDependencies，不承诺直接 Git 安装能构建 Web。本地 runner 的限制见 SECURITY.md。
+
+日常测试与归档检查分别运行。公开工具/命令、分支恢复、HTTP/SSE 往返、浏览器输入与同步有自动测试；发布检查真实离线安装 tarball，经 Pi 加载包内入口并验证首页、脚本和 Monaco worker。真实模型 E2E 保持独立。

package/docs/releasing.md

@@ -0,0 +1,51 @@
+# 开源发布流程
+
+本项目是社区扩展，采用 [Pi 官方包格式](https://pi.dev/docs/latest/packages)。符合格式不代表官方维护或已经在包目录展示。兼容验证基线为 Pi 0.84.0。
+
+## 发布结构
+
+package.json.pi.extensions 指向 extension/index.ts，pi-package 关键字用于发现。Pi 核心库与 typebox 使用 peerDependencies: "*"；开发依赖实际版本由根锁文件固定。
+
+归档包含 extension、shared、web/dist、README、MIT LICENSE 和维护文档。Monaco、worker、Markdown/KaTeX 资源本地打包，安装者不需要前端源码或构建工具。
+
+prepack 保证普通 npm pack 在打包前构建。支持 npm 包与已构建本地源码；不提供直接 Pi Git 安装支持，因为 Pi 0.84.0 默认运行 npm install --omit=dev。
+
+## 发布准备
+
+在干净检出中运行：
+
+```sh
+npm ci
+npm run release:prepare
+```
+
+release:prepare 依次执行：
+
+1. Extension/Web 类型检查与日常测试。
+2. Web 构建和真实 tarball 验收：离线安装、Pi 入口、五个工具与五个命令、首页、JavaScript 和 Monaco worker。
+3. 真实 Pi RPC smoke，不调用模型。
+4. 使用已验证产物生成根目录 pi-learning-agent-<version>.tgz，最后一步不再构建。
+
+日常开发可分别运行 npm run check、npm run check:package 与 npm run smoke。Windows/Linux、Node.js 22/24 的 CI 配置位于 .github/workflows/ci.yml；本机运行不代表远程矩阵已经执行。
+
+真实模型 E2E 见 CONTRIBUTING.md；历史报告不能代替当前版本验收。
+
+## 发布
+
+维护者核对 npm 包名所有权、版本、仓库地址和全部结果后，发布生成的那个文件：
+
+```sh
+npm publish ./pi-learning-agent-<version>.tgz --access public
+```
+
+将 <version> 替换为实际版本。此步骤需要发布者 npm 权限，准备脚本不会执行它。发布后在干净 Pi 环境验证：
+
+```sh
+pi install npm:pi-learning-agent@<version>
+```
+
+再验证学习启动、作答、停止与分支恢复，并实际检查包目录是否展示该版本。
+
+## 撤回
+
+发布前可删除归档并撤回代码。发布后采用新的修补版本修正；用户可显式安装此前可用版本。不要覆盖已发布版本或未经影响评估执行 npm unpublish。

package/extension/commands.ts

@@ -0,0 +1,181 @@
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext
+} from "@earendil-works/pi-coding-agent";
+
+import type { InteractionBroker } from "./server/interaction-broker.js";
+import type { LearningServer } from "./server/learning-server.js";
+import type { LearningStateStore } from "./state/learning-state.js";
+import type { StartLearningInput } from "./state/learning-state.js";
+import type { LearningSession } from "./learning-session.js";
+import { openWorkspace as defaultOpenWorkspace } from "./utils/browser.js";
+
+export interface LearningCommandDependencies {
+  session: LearningSession;
+  server: LearningServer;
+  /** Injectable for tests; defaults to the system browser opener. */
+  openWorkspace?: (url: string) => Promise<void>;
+}
+
+export function registerLearningCommands(
+  pi: ExtensionAPI,
+  dependencies: LearningCommandDependencies
+): void {
+  const { session, server } = dependencies;
+  const { state, broker } = session;
+  const openWorkspace = dependencies.openWorkspace ?? defaultOpenWorkspace;
+
+  pi.registerCommand("learn", {
+    description: "Start a structured learning session: /learn <course> <topic>",
+    handler: async (args, ctx) => {
+      const target = parseLearningTarget(args);
+      if (target === undefined) {
+        ctx.ui.notify("Usage: /learn <course> <topic>", "warning");
+        return;
+      }
+
+      if (!session.isCurrentTarget(target) && !ctx.isIdle()) {
+        ctx.abort();
+        await ctx.waitForIdle();
+      }
+      session.start(target);
+      pi.setSessionName(
+        `Learn: ${target.course.title} - ${target.topic.title}`
+      );
+      const workspaceUrl = await ensureServerStarted(server, ctx);
+      if (workspaceUrl !== undefined) {
+        await openWorkspace(workspaceUrl);
+      }
+      const workspaceLine =
+        workspaceUrl === undefined ? "" : `\nWorkspace: ${workspaceUrl}`;
+      ctx.ui.notify(
+        `Learning Mode enabled: ${target.course.title} / ${target.topic.title}${workspaceLine}`,
+        "info"
+      );
+
+      const kickoff = [
+        `Begin a structured learning session for ${target.course.title} / ${target.topic.title}.`,
+        "Start with a concise diagnostic and teach interactively.",
+        "Use the registered learning_* tools whenever the learner must respond."
+      ].join(" ");
+      if (ctx.isIdle()) {
+        pi.sendUserMessage(kickoff);
+      } else {
+        pi.sendUserMessage(kickoff, { deliverAs: "followUp" });
+      }
+    }
+  });
+
+  pi.registerCommand("learn-open", {
+    description: "Open the learning workspace in a browser",
+    handler: async (_args, ctx) => {
+      const url = await ensureServerStarted(server, ctx);
+      if (url === undefined) {
+        return;
+      }
+      await openWorkspace(url);
+      ctx.ui.notify(`Learning workspace: ${url}`, "info");
+    }
+  });
+
+  pi.registerCommand("learn-status", {
+    description: "Show the current learning session status",
+    handler: async (_args, ctx) => {
+      ctx.ui.notify(formatLearningStatus(state, broker), "info");
+    }
+  });
+
+  pi.registerCommand("learn-stop", {
+    description: "Stop the current learning session",
+    handler: async (_args, ctx) => {
+      session.stop();
+      ctx.ui.notify("Learning Mode disabled.", "info");
+    }
+  });
+
+  pi.registerCommand("learn-reset", {
+    description: "Reset the current topic's learner state (requires confirmation)",
+    handler: async (_args, ctx) => {
+      const snapshot = state.snapshot();
+      if (!snapshot.enabled || snapshot.topic === undefined) {
+        ctx.ui.notify("No active learning topic to reset.", "warning");
+        return;
+      }
+      const confirmed = await ctx.ui.confirm(
+        "Reset learner state?",
+        `This clears all concepts, mastery and attempt history for "${snapshot.topic.title}". It cannot be undone.`
+      );
+      if (!confirmed) {
+        ctx.ui.notify("Reset cancelled.", "info");
+        return;
+      }
+      session.resetTopic();
+      ctx.ui.notify(
+        `Learner state for "${snapshot.topic.title}" has been reset.`,
+        "info"
+      );
+    }
+  });
+}
+
+export function formatLearningStatus(
+  state: LearningStateStore,
+  broker: InteractionBroker
+): string {
+  const snapshot = state.snapshot();
+  const course = snapshot.course?.title ?? "none";
+  const topic = snapshot.topic?.title ?? "none";
+  const pending = broker.getPending();
+  return [
+    `Learning Mode: ${snapshot.enabled ? "ON" : "OFF"}`,
+    `Course: ${course}`,
+    `Topic: ${topic}`,
+    `Phase: ${snapshot.phase}`,
+    `Pending interaction: ${pending[0]?.id ?? "none"}`,
+    `Concepts: ${Object.keys(snapshot.concepts).length}`
+  ].join("\n");
+}
+
+export function parseLearningTarget(args: string): StartLearningInput | undefined {
+  const parts = args.trim().split(/\s+/u).filter(Boolean);
+  const courseName = parts[0];
+  const topicParts = parts.slice(1);
+  if (courseName === undefined || topicParts.length === 0) {
+    return undefined;
+  }
+
+  const topicName = topicParts.join(" ");
+  return {
+    course: { id: toId(courseName), title: toTitle(courseName) },
+    topic: { id: toId(topicName), title: toTitle(topicName) }
+  };
+}
+
+function toId(value: string): string {
+  return value.trim().toLocaleLowerCase().replace(/\s+/gu, "-");
+}
+
+/** Start the workspace server (lazy) and return its URL, or undefined on failure. */
+async function ensureServerStarted(
+  server: LearningServer,
+  ctx: ExtensionCommandContext
+): Promise<string | undefined> {
+  try {
+    await server.start();
+    return server.url();
+  } catch (error) {
+    ctx.ui.notify(
+      `Learning workspace server failed to start: ${String(error)}`,
+      "warning"
+    );
+    return undefined;
+  }
+}
+
+function toTitle(value: string): string {
+  return value
+    .trim()
+    .split(/\s+/u)
+    .map((part) => `${part.slice(0, 1).toLocaleUpperCase()}${part.slice(1)}`)
+    .join(" ");
+}

package/extension/index.ts

@@ -0,0 +1,50 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { registerLearningCommands } from "./commands.js";
+import { LearningSession } from "./learning-session.js";
+import { InteractionBroker } from "./server/interaction-broker.js";
+import { LearningServer } from "./server/learning-server.js";
+import { LearningStateStore } from "./state/learning-state.js";
+import {
+  LEARNING_STATE_ENTRY_TYPE,
+  LEARNING_STATE_VERSION,
+  registerLearningStatePersistence
+} from "./state/session-persistence.js";
+import { registerLearningTools } from "./tools/index.js";
+import { registerTranscriptSync } from "./transcript-sync.js";
+import { registerTutorPrompt } from "./tutor-prompt.js";
+
+export default function learningExtension(pi: ExtensionAPI): void {
+  const broker = new InteractionBroker();
+  // server 在 onChange 首次触发（/learn、record_attempt）前同步完成构造。
+  let server: LearningServer;
+  const state = new LearningStateStore({
+    // 任何 state 变化（/learn、/learn-stop、learning_record_attempt）后广播。
+    // server 可能未 start：broadcastSessionUpdated 在无 SSE 客户端时安全 no-op。
+    onChange: (snapshot) => {
+      server.broadcastSessionUpdated();
+      pi.appendEntry(LEARNING_STATE_ENTRY_TYPE, {
+        version: LEARNING_STATE_VERSION,
+        state: snapshot
+      });
+    }
+  });
+  server = new LearningServer({ broker, state });
+  const session = new LearningSession(state, broker);
+
+  // Spec 15: a presented question migrates explaining → checking.
+  broker.subscribe({
+    onPresented: () => state.questionPresented()
+  });
+
+  registerLearningTools(pi, { session, server });
+  registerLearningCommands(pi, { session, server });
+  registerTutorPrompt(pi, { state });
+  registerTranscriptSync(pi, server);
+  registerLearningStatePersistence(pi, session, () => server.broadcastSessionUpdated());
+
+  pi.on("session_shutdown", async () => {
+    broker.cancelAll("session_shutdown");
+    await server.close();
+  });
+}