hahhforest/pi-textbook を読む: 15 の checkpoint で Pi-style Agent を組み立てる中国語教材
《动手学 Pi》：沿 15 个真实 checkpoint 从零构建 Pi-style Agent
ひと目でわかる
- これは何？
- TypeScript で coding agent を自作するための中国語オンライン教材。教材本文、実在の commit、聚焦テスト、故障実験の四点で各章が閉じる構成を、採用判断の観点から整理する。
- 誰に向いている？
- Pi の内部実装を写経ではなく自分の手で再構成したい TypeScript 経験者には向く。逆に、動く coding agent を最短で手に入れたい人、API キーを渡すだけでモデルを差し替えたい人には向かない。
- 商用利用できる？
- できます。MIT は寛容なライセンスで、著作権表示とライセンス表示を残せば、使用・改変・販売が可能です。
- 今もメンテナンスされている？
- されています。最後のコミットは 55 日前です。
- 何の言語で書かれている？
- 主に TypeScript です（GitHub の言語統計による）。
回答はプロジェクトの GitHub データ（最終同期：2026年9月15日）と当サイトの分析に基づくもので、法的助言ではありません。
オープンソース詳細解説
教材が相手にしているのは、Agent を動かしたい人ではなく組み立てたい人である
このリポジトリは HTML 教材とウェブサイト本体であり、動作する Agent の配布物ではない。README は「沿 15 个 checkpoint，从一条离线轨迹开始，亲手实现一个 Pi-style coding agent」と述べ、序章から checkpoint 14 までを同じ Agent 実行チェーンに沿って積み上げる構成を取る。対象は TypeScript を読み書きでき、モデル呼び出し、ツール契約、会話履歴の永続化といった層を自分のコードとして書きたい読者である。逆に、既存の coding agent を導入して今日の作業を片付けたい読者には何も提供しない。README の冒頭が「课程代码不是伪代码演示，而是一条可以 checkout、运行和验证的 Git 历史」と書いている点が、この教材の性格を最もよく表している。読む対象は文章だけではなく、checkout できる履歴そのものだ。
checkpoint 00 から 14 が辿る四つの層
章立ては四つの部分に分かれる。I はモデルとプロトコルで、checkpoint 01 の TypeScript 生存集から 05 の Provider 変換まで、メッセージ表現とイベント配信を扱う。02 の EventStream は「事件先到」と「消费者先等」という二つの時系列のどちらでも過程項目と最終結果を届ける必要があり、ここで非同期の設計判断が一度入る。II はツールとループで、06 の echo 呼び出しが schema、Registry、executor を通って元の call id を保ったまま結果を返す流れ、07 の README 往復がモデルを二度呼ぶ流れ、08 の read、write、edit、bash が同一 workspace 内で動く話に進む。III は状態と履歴で、09 の購読、キャンセル、実行中指令、follow-up、再入を抱えた状態付き Agent、10 の親ポインタ付き JSONL によるセッション木、11 の token 予算内で後缀を残し構造化要約で早期事実を補う Context Compaction を扱う。IV は拡張と検証で、12 の Skill とテンプレートの按需投入、13 の Runtime 接続、14 の独立 Eval で閉じる。層の順序そのものが、Agent を書くときに詰まる順序と一致している。
教材本文、commit、聚焦テスト、故障実験という四点セットの意味
各章が四つの部品で閉じるという主張は、この教材の差別化点であり、同時に読者への要求でもある。教材本文だけを読むと普通の解説記事と変わらないが、对应する commit があり、その章に焦点を当てたテストがあり、故障実験がある。故障実験が付くということは、正常系の実装を写したあとに、わざと壊して挙動を観察する手順が用意されているという意味だ。ここは評価が分かれる。手を動かす時間を確保できる読者には、テストと故障実験の組は理解の定着に効く。逆に本文を通読して概念だけ掴みたい読者には、四部品のうち二つが完全に無駄になる。README は読了後に何ができるようになるかを明示していないので、この四点セットが自分の学習スタイルに合うかは、序章の「一次 README 读取请求怎样走完 Agent 闭环」を開いて判断するのが早い。
手元で動かすまでの手順と、checkpoint と practice の違い
教材サイトをローカルで動かす場合は次のとおり。
git clone https://github.com/hahhforest/pi-textbook.git cd pi-textbook npm install npm run dev
コースコードは別リポジトリのコースブランチにあり、README は次の手順を示す。
git clone --branch course/build-your-own-pi https://github.com/hahhforest/pi.git cd pi npm install npm run checkpoint -w @pi/course -- 05 npm run practice -w @pi/course -- 05 ../pi-practice-05
checkpoint はその章の parent、target、聚焦テストの位置を示す。practice は答えと Git 履歴を含まない練習ディレクトリを作る。この二つの役割分担は実用的で、checkpoint で現在地を確認し、practice で白紙から書き、詰まったら本文と commit に戻るという往復が想定されている。README は「把本章网页、命令输出与练习目录中的 LEARNING.md 一起交给陪学 Agent 即可」とも書いており、練習ディレクトリに LEARNING.md が生成される前提で読者を想定している。なお、この記事の執筆時点で当該コマンドを実行した検証は行っていない。出力内容は README の記述に基づく。
上流 commit 8479bd84 への固定がもたらす制約
課程分支は固定した上流 commit 8479bd84 から出発し、course(00) から course(14) で履歴を構成する。pi-course-v1 と course-v1/00 から course-v1/14 のタグが第一版を固定している。この設計は教材としては正しい。上流が動いても教材の前提が崩れないからだ。ただし読者にとっては、教材が教える実装が上流の最新状態と一致しない可能性を常に抱えることを意味する。第一版のタグが切られている以上、改訂は別のタグとして積まれる形になるはずで、どの版を読んでいるのかを意識しないと、本文と手元のコードの食い違いに遭遇しうる。ここは README からは改訂方針まで読み取れない。読み始める前に course-v1 系のタグと course 系のタグのどちらを使うかを決めておくべきで、その判断材料は現状 README には十分にない。
中国語教材であることの実務的な重み
本文は簡体字中国語で書かれ、README_EN.md という英語版も併置されている。ただし英語版がどこまで本編に追従しているかは、与えられた資料からは判断できない。日本語話者にとって、中国語の技術文章は漢字語彙の重なりで概要は追いやすいが、たとえば「会话树」「上下文按预算重建」のような用語は日本語の技術語彙と一対一に対応しない。用語の揺れを自分で吸収しながら読む必要がある。逆に、中国語の技術コミュニティで流通している Agent 実装の語彙に直接触れられる利点はある。README は LINUX DO への謝辞を載せており、中国語圏の技術交流空間を前提にした教材であることが伺える。日本語の解説記事を探しても、この粒度で Agent の各層を積み上げる教材は多くない。
Pi 本体のコードを読むのと何が違うのか
同じ Pi を学ぶ手段として、上流リポジトリのコードを直接読む方法がある。違いは明確だ。上流を読む場合、完成した実装がそこにあり、なぜその順序で書かれたのか、どの層で何が壊れやすいのかは読者が自分で再構成するしかない。この教材は、その再構成の順序を 15 段に切り、各段にテストと故障実験を添える。得られるものは動くコードではなく、設計判断の連鎖である。ただし上流を読む方法に比べて、教材は著者の切り取り方に依存する。15 段に割る過程で落ちた論点は、教材を読んだだけでは見えない。両者は排他ではない。教材で層の順序を掴んでから上流の該当箇所を読み、差分を確認する使い方が、この教材の固定 commit という制約を踏まえると現実的である。
ライセンス区分と、読む前に確認すべきこと
ライセンスは一様ではない。README は、アプリと原创コードが MIT License、教材正文と原创媒体が CC BY 4.0、Pi 上流コードはその原ライセンスと作者帰属に従うと述べている。つまり、教材サイトの文章を引用したり翻訳したりする場合と、コースコードを自分のプロジェクトに取り込む場合とで、従う条件が変わる。詳細は LICENSE と LICENSE-CONTENT に分けて置かれている。法的助言はできないが、コードと文章で境界が引かれている点は把握しておく価値がある。また、この教材はコミュニティによる非公式コースであり、Pi / Earendil Works に所属も代表もしないと明記されている。公式ドキュメントとして参照すると、上流の仕様変更を拾い損ねる。維持コストの面では、上流 commit を固定している以上、上流が動いたときの追従作業はコース側の負担になる。読者側の負担は、自分が読んでいるタグを把握し続けることだ。
編集部の結論
Pi の内部実装を写経ではなく自分の手で再構成したい TypeScript 経験者には向く。逆に、動く coding agent を最短で手に入れたい人、API キーを渡すだけでモデルを差し替えたい人には向かない。採用前に確認すべきは、course/build-your-own-pi ブランチが固定する上流 commit 8479bd84 の時点で本編がどこまで追従しているか、そして checkpoint 00 から 14 のうち何章が自分の関心領域に重なるかである。まず npm run checkpoint -w @pi/course -- 00 を実行し、出力される parent と target が期待する章を指すかを確かめてから読み始めるのが無駄が少ない。
コミュニティノート