pi-from-scratch レビュー：600 行の nano-pi を読んで coding agent のループを掴む

pi の工程詳細を削って残したもの

このリポジトリが解こうとしているのは、coding agent の実装を学ぶときの「読む対象が大きすぎる」問題である。README は本家 pi（earendil-works/pi）を参照先として挙げ、そこから「工程细节」を削り、「核心思想」だけを残したと説明している。対象読者は、agent loop や tool calling という言葉は知っているが、実際のデータの流れを追ったことがない TypeScript 開発者だ。600 行という規模は、フレームワークの抽象を追うのではなく、モデル呼び出しと tool 実行の往復を 1 ファイル単位で目で追える範囲に収めるための数字だと読める。ドキュメントは「这是一篇文章，不是一本书」と位置づけており、リファレンス実装ではなく読み物として設計されている。つまり、npm で入れて本番に置く類のものではなく、手元で動かしながら写経する前提の教材である。

nano-pi が回すループと Trace の役割

README から確認できる構成は 2 つに分かれている。nano-pi 本体と、それを読むための web サイトだ。nano-pi 側は OpenAI 互換 API に対してリクエストを投げ、返ってきた tool call を処理し、その結果を会話に戻すという agent loop を回す。ファイル読み書きとコマンド実行が tool として並ぶ。データの流れそのものは README に図解されているわけではないので、正確な関数名やモジュール分割は本文の記述からは確定できない。web 側の説明のほうが具体的で、記事を読み進めると右側のエディタにコードが段階的に補完され、読み終えた時点で nano-pi の全体がエディタ上に揃うと書かれている。加えて Trace という機能があり、ブレークポイントを置いて 1 行ずつ実行を追える。ここは注意点がある。README は「线上 trace 是预先生成的静态数据」と明記しており、サイトを閲覧してもモデルへのリクエストは発生しない。つまり Trace で見える実行は誰かの環境で事前に取られた記録であり、自分のモデルや API キーで同じ出力が出る保証はない。学習用の固定教材としては妥当だが、挙動の検証手段として使うと裏切られる。

動かすまでに設定する 3 つの値

実行手順は README にそのまま載っている。前提は Node.js 22 以上と、OpenAI 互換の API である。リポジトリのルートで npm install を実行し、NANOPI_API_KEY に自分のキーを export してから npm run dev を叩く。オプションの環境変数は 2 つで、NANOPI_MODEL がモデル名、NANOPI_BASE_URL が OpenAI 互換エンドポイントのアドレスだ。BASE_URL を省略した場合は https://api.openai.com/v1 が使われる。ここは実務上いちばん効く設定で、OpenAI 本体を使わず中継サービスやローカルの互換サーバーに向けたい場合、この 1 行を差し替えるだけで済む。逆に言えば、OpenAI 互換の口を持たないモデルはこの構成では扱えない。教材サイトのほうをローカルで見たい場合は、ディレクトリを web に移して npm install、npm run dev を実行する。README には web 側の Node バージョン要件が書かれていないため、nano-pi と同じ 22 以上を前提に考えるのが無難だ。

教材としては強いが、ツールとしては弱い

最大の制約は、これが agent 製品ではなく教材だという点である。README の説明はすべて「読んで理解する」文脈で書かれており、エラーハンドリングの網羅、リトライ、レート制限、並行実行、権限分離といった運用に必要な要素には触れていない。600 行に収めるという目標そのものが、そうした要素を意図的に落としていることを意味する。tool 実行の部分も同様で、ファイル書き換えやコマンド実行をどの範囲で許可するかの制御については記述がない。手元の検証なら問題にならないが、権限の広い環境で nano-pi をそのまま走らせるのは筋が悪い。もう 1 つの落とし穴は Trace の性質で、前述のとおり静的データである以上、教材サイトで見た実行と自分の手元の実行は別物になる。学習の入口としてサイトを読み、理解の確認は手元の npm run dev で行う、という二段構えが前提の設計だと考えるべきだ。

本家 pi と pi-book、どちらを読むか

比較対象として README 自身が挙げているのは本家 pi と pi-book（books.antinomie.org/pi/）である。本家 pi は実際に使う側の実装で、工程の詳細を含む分だけ読む量が多く、抽象も多い。pi-from-scratch はそこから詳細を削って流れだけを残したもので、同じ対象を「使うためのコード」と「理解するためのコード」に分けた関係にある。pi-book はさらに別の軸で、nano-pi を書き終えたあとに pi 本体へ進むための読み物として README が紹介している。つまり順序としては、pi-from-scratch でループの形を手に馴染ませ、pi-book で背景を補い、本家 pi の実装に入るという段階が想定されている。逆に、すでに agent loop を書いた経験がある読者にとっては、600 行の写経は得るものが少ない。本家 pi のコードを直接読むほうが速い。

MIT とメンテナンスの見え方

ライセンスは MIT で、リポジトリの LICENSE ファイルに従う。MIT なのでコードを自分の教材や社内勉強会の資料に取り込み、改変して配ることは可能だが、これは法的助言ではないので、実際の利用条件は必ず LICENSE の原文と自組織の規程で確認してほしい。メンテナンス面で材料から言えることは限られる。最終 push は 2026-08-18 で、アーカイブはされておらず、取得できたリリースはない。リリースを切らない方針なのか、単にまだ切っていないのかは README からは判断できない。依存は npm install で入る構成なので、Node.js 22 以上という前提が変われば追従が必要になる。教材としては、対象である本家 pi の設計が動けば内容の前提も動く。読む時期によって説明と実装がずれる可能性は残る。

読む前に決めておくこと

最初に決めるのは、nano-pi のコードを書くのか、web の記事と Trace を読むだけなのかだ。後者なら Node.js も API キーも不要で、ブラウザだけで完結する。前者なら Node.js 22 以上と OpenAI 互換 API のキーが必要で、NANOPI_API_KEY、必要なら NANOPI_MODEL と NANOPI_BASE_URL を設定して npm run dev を実行する。手元のモデルで tool call が期待どおりに返るかは、BASE_URL の先のサービス次第で変わる。ここが最初に確認すべき点だ。もう 1 つ、Trace は静的データなので、サイトで見た流れを自分の環境の正解として扱わないこと。理解の確認は必ず手元の実行で行う。

編集部の結論

nano-pi は、coding agent がどの順序でモデルを呼び、tool call をどう処理し、結果をどこで会話履歴に戻すのかを、自分の手で書きながら確認したい開発者に向いている。逆に、既に動く agent を業務に投入したい人、Node.js 22 未満の環境しか持たない人、OpenAI 互換 API を用意できない人には向かない。読む前に確認すべきは 3 点で、Node.js のバージョン、NANOPI_BASE_URL に指定できる OpenAI 互換エンドポイントの有無、そして nano-pi 側のコードを読むのか web 側の教材サイトだけを読むのかという目的の切り分けである。web の Trace はプリ生成された静的データなので、そこで見た挙動は自分の API キーで再現されるとは限らない。手元で確かめるなら NANOPI_API_KEY を設定して npm run dev を実行し、自分のモデルで同じ流れが出るかを先に見ておきたい。

公式情報源

1. Issues
2. License: MIT
3. Project website
4. README
5. SaladDay/pi-from-scratch on GitHub