tiny-agent

閱讀繁體中文教學書

用 TypeScript、Go、Python、Rust 實作的四個 minimal AI coding agent：

tiny-ts / tiny-go / tiny-py / tiny-rs

四個版本都能呼叫 OpenRouter、執行 bash/read/write/edit、讀取 AGENTS.md 與 skills，並支援 MCP、Session 恢復、compaction、usage/cache 與 cancellation。完整原理與實作解說請閱讀 tiny-agent Book。

安裝

先 clone repository：

git clone https://github.com/geminixiang/tiny-agent.git
cd tiny-agent

安裝想使用的版本：

make install-ts   # Node.js 22+
make install-go   # Go 1.25+
make install-py   # Python 3.14+ 與 uv
make install-rs   # Rust 1.85+

也可以一次安裝四個版本：

make install

使用

設定 OpenRouter API key：

export OPENROUTER_API_KEY=sk-or-...

執行任一版本：

tiny-ts "讀取 README 並摘要"
tiny-go "讀取 README 並摘要"
tiny-py "讀取 README 並摘要"
tiny-rs "讀取 README 並摘要"

預設模型是 openai/gpt-5.6-luna。這個選擇來自跨 runtime 完整 eval 與重複的速度、穩定性、收斂和 token 效率比較；完整依據記錄在 eval/README.md。使用 TINY_MODEL 選擇其他 OpenRouter 模型：

TINY_MODEL=anthropic/claude-sonnet-4.5 tiny-ts "修正測試"

預設使用目前 shell 的工作目錄。也可以用 --cwd 指定 workspace；AGENTS.md、skills、tools、sessions 與背景 process 都會以該目錄為準：

tiny-ts --cwd /path/to/project "讀取 README 並摘要"

Session 保存在 workspace 的 .tiny-agent/sessions/。使用 Session ID 繼續工作：

tiny-ts --session <session-id>

互動模式支援：

/compact
/skill:<name>
/exit
Esc      中止目前操作
Ctrl+C   離開

MCP

Repository 已提供 .tiny-agent/mcp.json，其中只記錄 GitHub endpoint、tool allowlist 與 credential 的環境變數名稱，不包含 token。

設定 catalog 路徑與 GitHub token：

export TINY_MCP_CONFIG="$PWD/.tiny-agent/mcp.json"
export GITHUB_MCP_TOKEN="$(gh auth token)"
tiny-ts --mcp github --plugin read "只使用 GitHub MCP 的 get_file_contents，讀取 geminixiang/tiny-agent 的 README"

TINY_MCP_CONFIG 是使用 MCP 時唯一的 catalog 來源。tiny-agent 不會自動讀取 repository 或 home directory 內的設定。

tiny-ts 另支援固定的 Metabase API key auth，不接受任意 header。私有 Server 請放在 deployment-owned catalog，不要提交 hostname 或 key：

{
    "servers": {
        "analytics": {
            "url": "https://{your-metabase.example.com}/api/metabase-mcp",
            "auth": {
                "type": "metabaseApiKey",
                "tokenEnv": "METABASE_MCP_API_KEY"
            },
            "allowedTools": ["execute_question"],
            "callTimeoutMs": 30000
        }
    }
}

四個版本都使用官方 MCP SDK；TypeScript、Go、Python 由 SDK 自動協商 protocol，Rust 使用 SDK 的 auto lifecycle mode。

OpenTelemetry

TypeScript 可選擇性地用官方 OpenTelemetry SDK，透過 OTLP/HTTP protobuf 即時輸出 startup、operation、model、tool 與 MCP traces。one-shot、--json、interactive prompt、/skill、/compact、session recovery 與 Esc cancellation 都共用同一個 committed lifecycle：

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
export OTEL_SERVICE_NAME=tiny-ts
tiny-ts "讀取 README 並摘要"

未設定 OTLP endpoint 時完全停用。Endpoint、headers、TLS 等只接受標準 OTEL_* 部署環境設定，不接受 model 或 tool 參數。JSON 與 OTLP 都投影同一個 lifecycle；logical terminal 只在 Session fact 寫入成功後發布。OTLP 預設只輸出 IDs、名稱、usage、outcome 等 metadata，不輸出 prompt、回答、tool arguments/results、error messages、request headers 或 endpoint。Exporter 與 flush 失敗不會改變 agent 執行結果；append-only Session facts 仍是 recovery 的唯一權威資料。

OTLP spans 同時提供 OpenTelemetry GenAI 與 OpenInference metadata：Session 使用 session.id／gen_ai.conversation.id，operation、model、tool 分別標記為 AGENT、LLM、TOOL，並保留 tiny.* durable identities。這讓 Phoenix 等 AI observability backend 能直接建立 Session 與 Agent trace tree，而不改變 tiny-agent 的 lifecycle authority。Phoenix 本機範例：

uvx --from arize-phoenix phoenix serve
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:6006 OTEL_SERVICE_NAME=tiny-ts tiny-ts "讀取 README 並摘要"

致謝

Tiny-agent 受到 Pi 對 agent loop、Tool、skills、compaction 與可理解工程設計的啟發。Tiny-agent 不是 Pi 的 fork 或移植。

License

MIT © 2026 Ying Xiang