Bản đồ monorepo

Repo earendil-works/pi là một monorepo dùng npm workspaces: mọi package nằm dưới packages/, cùng chung một package-lock.json và cùng số phiên bản (mọi package ở tag này đều là 1.4.0). Chương này vẽ bản đồ để bạn biết mỗi thư mục làm gì, package nào dựa trên package nào, và nên đọc theo thứ tự nào.

Mười một package#

Số dòng dưới đây đếm các file .ts/.tsx trong src/ của từng package ở v1.4.0 (không gồm test); số file test đếm trong test/. README gốc liệt kê bảy package công khai chính (README.md:72–84); bốn package còn lại là phụ trợ.

Bài công bố Pi Durable nói harness này khoảng 15.000 dòng không tính test. Ở v1.4.0, thư mục src/ của nó đã khoảng 27.000 dòng, vì gồm cả các backend storage, bộ kiểm thử tuân thủ trong src/testing/, môi trường Node và code mode bền; phần lõi harness vẫn nhỏ hơn nhiều.

Đồ thị phụ thuộc: hai chồng tách biệt#

Điều quan trọng nhất cần nhận ra khi nhìn các file package.json: Pi không phải một khối, mà là hai chồng dùng chung tầng dưới.

  Chồng coding agent (CLI pi)                    Chồng Pi Durable (thư viện, thử nghiệm)

      pi-telemetry                                    pi-telemetry
           │                                          │          │
           ▼                                          ▼          ▼
         pi-ai                                      pi-ai      chord      pi-codemode
           │                                          │          │            │
           ▼                                          └──────────┼────────────┘
     pi-agent-core    pi-tui    pi-mcp    pi-codemode            ▼
           │            │         │           │              pi-durable
           └────────────┴─────────┴─────┬─────┘                  │
                                        ▼                        ▼
                                 pi-coding-agent              pi-env

Phụ thuộc nội bộ của coding agent nằm ngay đầu khối dependencies:

"dependencies": {	"@earendil-works/pi-agent-core": "1.4.0",	"@earendil-works/pi-ai": "1.4.0",	"@earendil-works/pi-codemode": "1.4.0",	"@earendil-works/pi-mcp": "1.4.0",	"@earendil-works/pi-tui": "1.4.0",

Còn Pi Durable dựa trên Chord, pi-ai, pi-codemode và pi-telemetry, không có pi-agent-core:

"dependencies": {	"@earendil-works/chord": "1.4.0",	"@earendil-works/pi-ai": "1.4.0",	"@earendil-works/pi-codemode": "1.4.0",	"@earendil-works/pi-telemetry": "1.4.0",

Thứ tự build trong package.json gốc chính là một thứ tự topo của đồ thị trên: telemetry, chord, tui, codemode, mcp, ai, durable, env, agent, rồi coding-agent.

"workspaces": [	"packages/*",	"apps/*",	"packages/coding-agent/examples/extensions/with-deps",	"packages/coding-agent/examples/extensions/custom-provider-anthropic",	"packages/coding-agent/examples/extensions/custom-provider-gitlab-duo",	"packages/coding-agent/examples/extensions/sandbox",	"packages/coding-agent/examples/extensions/gondolin"],"scripts": {	"clean": "npm run clean --workspaces",	"build": "cd packages/telemetry && npm run build && cd ../chord && npm run build && cd ../tui && npm run build && cd ../codemode && npm run build && cd ../mcp && npm run build && cd ../ai && npm run build && cd ../durable && npm run build && cd ../env && npm run build && cd ../agent && npm run build && cd ../coding-agent && npm run build",

Phụ thuộc bên ngoài đáng chú ý#

Danh sách phụ thuộc bên ngoài cho biết mỗi package tự làm gì và giao gì cho thư viện khác:

• pi-ai dùng SDK chính thức của từng provider (@anthropic-ai/sdk, openai, @google/genai, AWS Bedrock), partial-json để đọc đối số tool khi nó còn đang stream, và typebox cho schema của tool (ai/package.json).
• pi-coding-agent dùng jiti để nạp extension viết bằng TypeScript lúc chạy, quickjs-wasi cho codemode, @silvia-odwyer/photon-node để xử lý ảnh, diff cho tool edit, highlight.js để tô màu code trong terminal, undici cho HTTP, proper-lockfile để khoá file cấu hình khi nhiều tiến trình cùng ghi (coding-agent/package.json).
• pi-tui chỉ cần marked (parse Markdown) và get-east-asian-width (độ rộng ký tự CJK); phần còn lại, kể cả thuật toán vẽ, là tự viết.
• pi-durable dùng @silvia-odwyer/photon (bản WebAssembly, chạy được cả trên Cloudflare), diff và typebox; còn lại đều là code của chính nó và Chord.

Các package thư viện công khai nhiều điểm vào con (subpath exports) để ứng dụng chỉ nạp phần mình cần. Ví dụ pi-ai có ./models, ./providers/*, ./api/*, ./oauth (ai/package.json:13), còn pi-durable tách riêng từng backend storage (./storage/sqlite/node, ./storage/sqlite/cloudflare, ./storage/jsonl/node, ./storage/indexeddb), các tool (./tools), code mode (./codemode) và bộ kiểm thử tuân thủ (./testing) (durable/package.json:8). Nhờ vậy một Durable Object trên Cloudflare không phải kéo theo code chỉ dành cho Node.

Ngoài packages/#

Một prompt template của maintainer trông như sau: frontmatter có mô tả và gợi ý đối số, thân là chỉ dẫn, và $ARGUMENTS được thay bằng những gì gõ sau lệnh. Cơ chế này được giải thích trong chương Extensions.

---description: Analyze GitHub issues (bugs or feature requests)argument-hint: "<issue>"---Analyze GitHub issue(s): $ARGUMENTS

Quy ước kỹ thuật#

TypeScript chạy thẳng, không biên dịch khi phát triển

Từ 0.99.0 repo dùng TypeScript 7.0 (target ES2024) để kiểm kiểu và build, còn khi chạy từ mã nguồn thì dùng chế độ bỏ kiểu có sẵn của Node thay cho tsx (CHANGELOG:463). Hệ quả là quy tắc chỉ dùng cú pháp xoá được (AGENTS.md:24), và các import tương đối ghi rõ đuôi .ts.

Định dạng và lint bằng Biome

Thụt lề bằng tab, dòng tối đa 120 ký tự; file models.generated.ts được loại khỏi kiểm tra (biome.json:19–36). Trang này hiển thị tab rộng 2 ký tự.

Danh mục mô hình được sinh ra

Không ai sửa tay packages/ai/src/models.generated.ts; nó được sinh bằng script, còn dữ liệu mô hình chi tiết trong providers/data/ bị gitignore (AGENTS.md:28). Vì vậy bản clone của bạn không có dữ liệu đó; chương pi-ai giải thích nó được nạp thế nào.

Tài nguyên của coding agent đi qua src/config.ts

Code không dùng __dirname trực tiếp mà gọi helper trong config.ts, vì cùng một mã phải chạy từ checkout, từ gói npm và từ binary độc lập (AGENTS.md:22).

Test cô lập

test.sh tạo HOME, thư mục tạm và cache npm riêng, chỉ cho qua các biến môi trường cần thiết, và bỏ qua test cần gọi LLM thật khi không có khoá API (test.sh:4–13). Phần lớn test dùng vitest; riêng pi-tui dùng node:test.

Điểm vào của lệnh pi ngắn đúng sáu dòng; mọi thứ còn lại bắt đầu từ main(), được giải thích trong chương Các chế độ chạy:

#!/usr/bin/env nodeimport { setupCli } from "./cli/setup.ts";import { main } from "./main.ts";setupCli();main(process.argv.slice(2));

Những package đã biến mất#

Nếu đọc issue cũ, changelog hay blog, bạn sẽ gặp các package không còn trong packages/. Lịch sử git cho biết chúng đi đâu:

Nên đọc theo thứ tự nào#

Tài liệu này đi từ dưới lên, khớp với đồ thị phụ thuộc. Nếu bạn có mục tiêu cụ thể, có thể nhảy thẳng: