学习进度

当前阶段

先手动运行原项目，再围绕真实启动路径阅读源码。第一篇为 从源码运行 Pi。

2026-11-07 按用户本轮请求增加独立的 Shell 支线：逐行读懂 pi-test.sh，范围仅为该脚本；主线的安装、启动与模型连接状态仍等待用户反馈。

项目	状态
根目录背景与 Agent 约定	已建立
VitePress 配置与第一篇文章	已建立
Shell 脚本支线	pi-test.sh 逐行／逐块文档、示例和自测题已建立；用户理解情况待反馈
文档站点验证	本轮静态构建通过；2026-11-06 已检查第一篇文章的开发服务与浏览器页面
Pi 依赖安装、构建、CLI 启动	等待用户按文章手动执行；Agent 未代为运行
模型登录与首次对话	待用户验证
p2 浏览器应用	可选，尚未运行
完整功能盘点与复现路线	尚未展开
c-pi/ 功能实现	尚未开始

当前源码基线

• 本轮检查日期：2026-11-07，Asia/Taipei。
• 参考仓库：pi/，origin 指向 https://github.com/Atmizz/pi.git。
• 本轮检查分支：pi-1107-2026，工作区干净；本次未切换、创建或同步分支。
• 完整 SHA：e12dbfc9299049dc2e7a974612fec32001a7ba8a，为 Shell 支线的源码依据。
• 2026-11-06 的运行指南保留原有历史基线：main，SHA 63bc4da65adc2b45b1674d85a303d5eaefe3ae07；当时本地未发现 pi-1106-2026。本轮不据此推断其他分支的创建或同步过程。
• c-pi/ 由根目录 pi-study 的 Git 仓库跟踪。根仓库使用 main，远端为私有仓库 Atmizz/pi-study。pi/ 保留独立的 Git 历史，由根目录 .gitignore 整体排除。
• 历史环境检查为 Node v26.12.1 与 npm 11.20.0；本轮 Shell 示例使用 Bash 3.2.57。这些检查均不代表 Pi 已运行成功。

用户手动操作记录

尚未收到操作结果。请保留第一篇文章末尾的各项记录，完成或遇到错误后在这里更新。

文档站点验证记录

• 2026-11-06：在 c-pi/docs/ 执行 npm install --ignore-scripts，安装 VitePress 2.0.0-alpha.21；安装检查报告 0 个已知漏洞。
• npm run docs:build 成功，页面已生成到 .vitepress/dist/。
• 临时启动 npm run docs:dev，确认 http://127.0.0.1:5173/guide/01-run-pi 在浏览器显示完整文章、导航、侧栏和本页目录；验证服务在检查后停止，阅读时由用户按首页命令启动。
• 以上只验证文档站点，不代表文章中的 Pi 安装、构建、运行步骤已实际通过。

Shell 支线验证记录

• 2026-11-07：原脚本 bash -n pi/pi-test.sh 通过；Bash 错误处理、空数组展开、URL 编码与文中的三组教学实验均已验证。
• 用临时 Node 替身检查原脚本：无参数、--help、--no-env --help 以及带空格、空字符串、字面量通配符的参数均按预期交接；虚构 key 按开关清除，调用目录保留。
• 替身在第 84 行委托真实 Node 做 URL 转换，第 85 行只记录交接信息；没有执行 Pi 的解析器与 CLI，没有安装、构建、登录或调用模型。临时验证文件已清理。
• 在 c-pi/docs/ 执行 npm run docs:build 通过，Shell 支线已加入导航、侧栏和首页。
• 2026-11-07 补充六组深入示例：错误规则、命令替换的子 Shell、单／双引号与参数拆分、环境变量继承、数组展开、Node 预加载顺序。每组提供运行方法、预期输出、原因及对应源码说明；Bash 示例与 Node v24.15.0 的加载示例已实际验证，文档重新构建通过。学习约定同步补充「重要知识点配深入示例」。

Wiki 归档记录

2026-11-07 文档归档调整：将 docs/shell/ 移至 docs/wiki/shell/，同步首页、导航、侧栏及文章相对链接。docs/wiki/ 今后承载单一知识点专题，此约定已写入根目录 AGENTS.md；迁移后 npm run docs:build 通过。

下一步

本轮先由用户阅读 Shell 支线、对照原文件并尝试参数实验，根据疑问继续解释这一个脚本。主线仍由用户按运行指南手动操作；若报错，解决当前失败步骤并补回确认有效的方法。恢复主线时先核对实际运行基线，再梳理原项目功能与学习路线。