Pi 学习笔记

从运行原项目开始，阅读源码，再逐步在 c-pi/ 中重新实现 Pi。每次只学习一个能够解释、运行和验证的小单元。

文中的 /path/to/pi-study 代表你的 pi-study 工作区，请按实际路径替换。

第一篇文章

01 · 从源码运行 Pi

文章以当前本地源码为依据，按「在哪个目录执行 → 命令做什么 → 应该看到什么」展开。先走 Pi CLI 主线，最后再按需体验实验性的 p2 浏览器应用。

在浏览器中阅读

在一个独立终端执行：

cd /path/to/pi-study/c-pi/docs
npm run docs:dev

打开终端显示的地址，默认是 http://127.0.0.1:5173。端口被占用时以终端输出为准。保持这个终端运行，再开另一个终端按文章操作 Pi。停止文档服务使用 Ctrl+C。

文档依赖已由 Agent 安装。换电脑或依赖目录不存在时，先在上述 docs/ 目录执行：

npm ci --ignore-scripts

这里只安装文档站点的依赖。Pi 源码仓库的依赖需要按第一篇文章单独安装。

Wiki · 单一知识点

wiki/ 用于承载单一知识点的专题文档，按主题建立子目录；Shell 脚本专题放在 wiki/shell/。

Shell 支线：逐行读懂 pi-test.sh

这条支线只讲 pi-test.sh：从 Shell 零基础出发，按源码顺序逐行、逐块解释，配合参数演算和一个不启动 Pi 的练习。可以按需阅读，不改变主线的学习顺序。

文档站点的最小结构

c-pi/docs/
├── .vitepress/config.mts  # 标题、导航、侧栏、搜索与中文界面
├── .gitignore            # 忽略依赖目录、缓存和构建产物
├── package.json          # VitePress 依赖与三个运行脚本
├── package-lock.json     # 文档站点依赖的锁定记录
├── index.md              # 当前首页
├── guide/01-run-pi.md     # 第一篇文章
├── wiki/                 # 单一知识点专题
│   └── shell/pi-test.md  # 只学习 pi-test.sh 的 Shell 支线
└── progress.md           # 学习进度与验证状态

配置与脚本按 VitePress 官方入门文档 建立，固定使用 2.0.0-alpha.21。这是官网当前文档对应的 2.x 预发布版本；选择它是因为安装检查发现 1.6.4 的旧工具链有已知漏洞。文档站点后续升级应重新验证构建。依赖放在 docs/ 中，后续 c-pi/ 根目录可以继续按 Pi 原项目结构搭建。

需要生成静态页面时，在 docs/ 执行 npm run docs:build；构建完成后用 npm run docs:preview 查看，地址以终端输出为准。平时边读边改文档只需 docs:dev。

学习与报错记录

进度见 学习进度。尚未由你手动操作成功的 Pi 运行步骤都保留为待验证。

操作时一次执行一条命令，确认成功后再进入下一步。如果失败，保留当前命令、完整错误信息和所在目录，把文字或截图发回对话；我们从失败处继续，并将确认有效的解决办法补回文章。