pi 用 Sarashina 拡張を AI に書かせ、その Sarashina に Go ツールを書かせて受け入れテストした #

Note

執筆: Devin(SWE-2)。

private リポジトリ pi-lab の PR #30(private なのでリンク先は見えない)に入った作業の記録。PR に同梱されていた RESEARCH.md / NOTES.md / ARTICLE.md / TODO.md からまとめ直した。

前提知識(非開発者向け): Sarashina / Devin CLI / pi とは
  • Sarashina: SB Intuitions(ソフトバンクグループ)が提供する日本語 LLM と、その API サービス。OpenAI と同じ形式(Chat Completions)で呼び出せる。今回は無料枠を使ったので、1 分あたりのリクエスト数に上限がある。この制限が記事の後半に効いてくる
  • Devin CLI: Cognition の AI エージェントのコマンドライン版。指示を受けてコードを読み書きし、コマンドを実行しながら自律的に作業する。この記事では「拡張を書いた側」であり「pi を動かして監督した側」でもある
  • pi(pi agent / pi-coding-agent): earendil-works のコーディングエージェント。チャット風の指示でファイル編集やコマンド実行を自律的に行う。「pi パッケージ」という拡張を足すと、使える LLM の供給元(モデルプロバイダ)を追加できる

つまり今回は「pi というエージェントのモデル差し口に Sarashina を繋ぐ部品を Devin に書かせ、その差し口経由で Sarashina 自身をエージェントとして働かせた」という話になる。

やったことは 2 段構造になっている。

  • 1 段目: Devin CLI に、コーディングエージェント pi(@earendil-works/pi-coding-agent)用の拡張パッケージ pi-sarashina を書かせた。Sarashina API(SB Intuitions、OpenAI Chat Completions 互換)を pi のモデルプロバイダとして登録するもの
  • 2 段目: Devin がその拡張を pi にロードして実行し、拡張経由で Sarashina のモデル自身に Go 製の TUI グラフ描画ツール gratui を実装させた。拡張の受け入れテストを、拡張が繋いだモデルの実作業で行う形

ちなみに Devin CLI を使ったのは、当時 devin-cli で SWE-2 が無料提供されていたから、という経緯がある。

途中で挙動が見えずハマったので、実行する Devin が pi と Sarashina API の間に自作のロギングプロキシを挟んで作業を進めた。

人 Devin CLI pi-sarashina 拡張 指示 実装 実行・監督 pi -e でロード pi agent trace-proxy :8787 Sarashina API HTTP HTTPS main.go, *.txt write/edit

人が直接 pi を触るわけではない。pi へのプロンプト投入、経過の観察、ハング時の kill、再開指示という監督も Devin が行っている。この構造で面白いのは、検証対象と検証経路が同じものを通っている点だ。「プロバイダ拡張が正しく動くか」を確かめるのに、その拡張を通してモデルをエージェントとして働かせる。結果として、書いたばかりで未検証だった 429 リトライ実装が、テストの途中で自然に実地検証されることになった(後述)。

1 段目: pi-sarashina を作る #

pi には拡張単位として「pi パッケージ」があり、pi.registerProvider() でモデルプロバイダを追加できる。Sarashina は OpenAI 互換なので api: "openai-completions" を指定すれば pi 標準のストリーミング実装が使え、独自実装は要らない——というのが調査段階の見立てで、概ねその通りになった。進め方は「調査を RESEARCH.md に集約 → 実装を子エージェントに委譲 → レビューと実測」という分業だった。

ただし「互換」をそのまま信じると動かない部分がいくつかあり、実測で初めて分かったことが多い。

  • Sarashina は message content の配列形式([{"type":"text","text":...}])を 400 Invalid JSON で弾く。API ドキュメントに書かれていない。pi は user メッセージを配列で送るので、そのままでは一切会話できなかった。リクエスト送信前の payload 書き換えで、テキストパーツを文字列に平坦化して解決した
  • thinking モデルの reasoning フィールド(暗号化された base64)は、pi 側の既存機構でそのまま往復することが実測で確認できた。2 ターン目に reasoning 付きの assistant メッセージを送り返しても reasoning could not be decrypted にならず、思考コンテクストが継承される
  • sarashina3-guard(モデレーション専用モデル)は tools/tool_choice を受け付けない(curl で実測 400)。pi は agent が tools を持つ限り必ず tools を送るので、guard のときだけ両フィールドを剥がす対応を入れた
  • pi は .env を読まない。$SARASHINA_API_KEY の補間はプロセス環境変数だけを見るので、set -a && . ./.env && set +a してから起動する必要がある
  • 未知プロバイダ向けの自動検出 compat フラグは store・developer ロール・tools の strict モード・stream_options を送る設定になっていた。Sarashina は未対応パラメータを無視するが「送らない」方針で全て false に倒した

リトライまわりが一番の発見だった。pi にはリトライが 3 層ある。

  • provider/SDK 層: Retry-After を読んでその秒数だけ待つが、maxRetries デフォルト 0 で事実上 OFF
  • compaction 専用層: 通常のターンには使われない
  • エージェントループ層(デフォルト有効): 429 を検出してターンをやり直すが、待ち時間は固定の 2s/4s/8s で Retry-After を見ない

Sarashina のレート制限は固定 60 秒窓(thinking/mini は約 30 RPM)なので、デフォルトの 2s/4s/8s リトライは全て同じ窓の中で尽きて「ほぼ確実に 3 回連続 429 → 約 14 秒で失敗」になる。そこで拡張側の streamSimple を標準実装への委譲ラップにして、呼び出し側が未設定のときだけ maxRetries: 3 を適用し、sarashina 限定で Retry-After を尊重する層を有効化した。実装は 01-extension-index.ts にまとまっている(Codex レビューを受けて、payload 書き換えもフックではなくこのラップ内の onPayload 合成に移し、どの経路から呼ばれてもバイパスされない構造にした)。

2 段目: Sarashina 自身に Go を書かせる #

受け入れテストとして、適当にでっち上げたラフな設計書 03-design.md を渡し、「これを読んで設計書通りの Go ツールを実装してください」と pi 経由で Sarashina に指示した。設計書は A -> B 形式のエッジリストを層別レイアウトで ──▶ などの罫線で描く CLI という内容で、「細部は実装に任せる」「落ちないことが大事」などの曖昧さを意図的に残してある。

実行はロギングプロキシ経由。SARASHINA_BASE_URL というデバッグ用の環境変数を拡張に仕込んであり、これを http://127.0.0.1:8787/v1 に向けると全トラフィックが 02-trace-proxy.mjs(約 50 行の Node スクリプト)を通る。リクエスト行・ステータス・Retry-After・SSE 各チャンクの到達時刻を記録する。

--> POST /v1/chat/completions body=32077B
<-- 429 /v1/chat/completions retry-after=35 +23ms
    +   176ms data: {"id":"chatcmpl-...","choices":[{"delta":{"content":...
    EOF /v1/chat/completions +603ms

8 run の記録 #

sarashina3-mini で 6 回、sarashina3.2-mini-thinking で 2 回走らせた。

runmodel結果
1miniプロキシ無しで起動。ファイル 3 個を書いた後、無言で停滞。原因不明のまま kill
2miniトレース導入。309 リクエスト・429 9 回は全回復。生成した main.go にリテラル \n 混入で構文エラー。修復中にストリームが沈黙 → TCP ETIMEDOUT で pi 死亡
3mini即死。原因は自作プロキシのバグで ECONNREFUSED
4mini修復指示で再起動するが、read/edit 失敗の無限ループに陥り kill
5mini「edit 禁止・全体書き直し」の指示で一応「完成」。ただし検証するとサイクル入力で無限ループ、ファイル引数・フラグ・矢印描画は全て未実装
6mini不足を列挙して改善指示。書き直したがサイクル処理の同じバグを再現。途中でストリーム沈黙し kill
7thinking継続指示。自分でサイクル入力テストを実行 → 自分が書いた無限ループバグで自分のテストがハング(7.6 CPU 分)。Devin がプロセスを kill すると再開するが同じテストを再実行して再度ハング、を 2 回繰り返して観察打ち切り
8thinking生成物を全削除して最初から。実質合格(下記)

失敗の分類 #

ソースへのリテラル \n 混入 #

ファイル書き込み時に \n(バックスラッシュ + n の 2 文字)を Go ソースへそのまま出力してしまい go build が通らない。run 2 と run 6 の両方で発生。「部分 edit ではなくファイル全体を一度に書き直せ」という指示で回避できた。このモデルでは破壊的編集より全量 write のほうが失敗率が低い。

read/edit の無限ループ #

run 4 は壊れた \n を消そうと edit を連発したが、oldText がファイル上の実際のバイト列と一致せず毎回失敗した。すると read の offset を 1 ずつ下げながら同じ edit を数百回繰り返すループに入った(セッションの ~/.pi/agent/sessions/*.jsonl で確認)。コンテキストは 226KB まで膨張し、30 RPM 制限に触れて 429 を連発した。pi にはツール呼び出しのループ検出がないので、実行を監督している Devin が止めるしかない。

SSE ストリームの途中沈黙 #

run 2 と run 6 で、SSE ストリームが数チャンク受信したところで応答が完全に停止し、pi は完了を待ち続けて数分後に TCP ETIMEDOUT で死亡した。基盤側(API または経路)の問題と見られる。run 1 の「無言の停滞」も同じ原因と推測されるが、プロキシが無くて観測できなかったので確証はない。緩和策として pi の httpIdleTimeoutMs 設定(デフォルト 300 秒)で切断を早められることは分かった。

自作プロキシ自身のバグ #

上流 ETIMEDOUT 時に res.writeHead(502) を呼んだが、ヘッダ送信済みで例外 → プロキシごとクラッシュし、次の run が ECONNREFUSED で即死した。「観測装置が観測対象を壊す」典型例。res.headersSent をチェックして res.destroy(e) にフォールバックする形に直した(このほか、クライアント切断時に上流の request/response を destroy する修正も入っている)。

自己検証が浅い #

run 5 は「完成しました」と報告したが、実際にはサイクル入力で無限ループ(設計書の「落ちないことが大事」に明確に違反)、ファイル引数・--help/--version/--vertical 未実装、エッジの罫線描画なし、という状態だった。「ビルドが通る + 一例が動く」までがこのモデルの完了基準で、設計書との突き合わせはしない。

自分の無限ループに自分がハングする #

run 7 でモデルは ./gratui(標準入力を読む自作バイナリ)をサイクル入力付きで実行し、自分が書いた無限ループで 7.6 CPU 分ハングした。pi の bash ツールは完了を待ち続ける。

自作の main.go ./gratui を実行 (サイクル入力) 無限ループでハング (7.6 CPU 分) 無限ループ Devin が kill → 再実行(×2)

ハングした ./gratui だけを Devin が kill すればよく、bash ツールが Terminated: 15 を返すと pi は即座に次のターンへ進んだ(pi 自体を殺す必要はない)。ただし再開したモデルは同じテストを再実行して再度ハングした。プロンプトに「実行確認は timeout 付きで」と入れるのは有効だった。

run 8: 実質合格 #

生成物を全削除し、sarashina3.2-mini-thinking(--thinking medium)+ 「自己検証は timeout 付きで」の指示で最初からやらせたところ、設計書の主要仕様を満たす 281 行の Go コードを 1 セッションで書き上げた(04-main.go)。

設計書の要求結果
go build で単一バイナリ・標準ライブラリのみOK
エッジリスト解析(->、# コメント、空行)OK。さらに行内コメント・孤立ノード記法まで吸収
層別レイアウト + ──▶ 系の描画OK。Kahn 法で層割り、ノード [A] と矢印を描画。表現は独自の縦積みだが「それっぽく」の範囲と評価
サイクル → 警告を出して落ちないOK。cycle detected を出し残ノードを最終層へ。ハングなし
ファイル引数 / 標準入力 / -OK
--version / -h / --verticalOK

実際の出力はこんな感じ(05-example.txt を食わせたもの。層ごとに 1 段ずつ縦に並ぶ表現になっている)。

[A]
      ──▶
   [B]
      ──▶
   [C]
      ──▶
   [D]

副産物として、モデルは検証用の入力ファイルを 3 個自作して残していた(05-example.txt / 06-cycle.txt / 07-complex.txt)。テスト資産を残す習慣は好印象だったという。

数値(トレースより) #

  • 総リクエスト: 約 845 回の POST /v1/chat/completions(run 2 が 309、run 4〜8 の合計が 536)
  • 429 は 22 回発生し、全て Retry-After 指定秒(実測 21〜35 秒、60 秒窓の残り時間)だけ待って再送 → 200 で復帰した
  • レスポンスタイム: mini はほぼ全て 1 秒以内。thinking でも数秒
POST t=0 429(retry-after=35) +23ms 35 秒待機 同じ body を再送 200 → SSE

つまり、1 段目で「Sarashina の 60 秒窓には Retry-After を尊重する層が必要」と判断して入れたリトライ実装が、2 段目のエージェント実行中に 22 回発動して全て設計どおりに動いた。パッケージの TODO にあった「実 429 の踏み抜き検証は未実施」という項目は、この実験で解消された。受け入れテストがテスト対象の検証そのものになった格好だ。

まとめと残課題 #

  • sarashina3-mini 単独でのエージェント実行は 6 回中 5 回が収束しなかった(残る 1 回はプロキシのバグで即死)。ソースへのエスケープ混入という破壊的編集と、失敗時に同じ操作を繰り返す癖が致命的だった
  • sarashina3.2-mini-thinking + クリーンな状態 + 「検証は timeout 付きで」の指示で実用圏内に入った。ただし thinking モデルの思考内容は暗号化されていて読めないので、「なぜ上手くいったか」の内訳はブラックボックスのまま
  • エージェント基盤として、HTTP 可視化(プロキシ)+ セッション JSONL の追跡 + ハング時の部分的 kill という監督手段が必須だった。今回この監督役を担ったのも Devin で、自律動作に任せきりだと run 1 のように原因不明のまま時間を溶かす
  • 未解決: SSE ストリームが稀に途中で沈黙する問題(httpIdleTimeoutMs で緩和可能)、pi にツール呼び出しループ検出がない点、.env 非対応、cost=0 固定(無料枠前提)、モデル一覧のハードコード
  • なお main で pi が 0.85.1 → 1.3.0 に bump された後に再検証済みで、extension 本体は変更不要だった

このバンドルのファイル #

01-extension-index.ts #

/**
 * Sarashina API (SB Intuitions) provider for pi.
 *
 * Sarashina exposes an OpenAI-compatible Chat Completions endpoint at
 * https://api.sarashina.ai/v1, so the built-in "openai-completions" API
 * implementation is used as-is; no custom streaming is needed.
 *
 * Compat notes (verified against pi-ai's openai-completions implementation):
 * - Auto-detected defaults for an unknown provider would send `store`,
 *   `stream_options`, `strict` on tools, the `developer` role for reasoning
 *   models, and prompt-cache fields. Sarashina ignores undocumented params,
 *   but we disable them explicitly to keep the wire format minimal.
 * - `reasoning_effort` is only sent for the thinking model, and only when a
 *   thinking level other than off is selected (Sarashina returns 400 if it is
 *   sent to a non-thinking model; pi already gates it on `model.reasoning`).
 * - The thinking model's encrypted `reasoning` field is captured as a thinking
 *   block whose signature is "reasoning", and replayed verbatim on subsequent
 *   requests, preserving thinking context across turns.
 * - Sarashina only accepts message `content` as a plain string; the OpenAI-style
 *   array-of-parts form (which pi emits for user messages) returns
 *   400 "Invalid JSON". An `onPayload` rewrite inside streamSarashina flattens
 *   text parts back into a string before the request is sent.
 * - `sarashina3-guard` is a moderation-only model: the API documents `tools`
 *   and `tool_choice` as unsupported for it (verified: 400 "Bad Request"). pi
 *   attaches `tools` whenever the agent has tools (and `tools: []` once
 *   history has tool calls), so the same rewrite strips both fields for that
 *   model only.
 * - The thinking model's encrypted `reasoning` would render in the TUI as an
 *   unreadable base64 "thinking" block; a markdown transformer replaces the
 *   display with a placeholder while leaving the stored content (and thus
 *   replay) untouched.
 *
 * Usage:
 *   SARASHINA_API_KEY=... pi -e ./packages/pi-sarashina --model sarashina/sarashina3-nano
 *   pi install ./packages/pi-sarashina   # persistent install
 */

import { openAICompletionsApi } from "@earendil-works/pi-ai";
import type {
	Api,
	AssistantMessageEventStream,
	Context,
	Model,
	SimpleStreamOptions,
} from "@earendil-works/pi-ai";
import type { ExtensionAPI, ExtensionContext, ProviderModelConfig } from "@earendil-works/pi-coding-agent";

// Compat flags shared by all Sarashina models: don't send params the API does
// not document. maxTokensField defaults to "max_completion_tokens", which is
// what Sarashina expects (range 1-8000).
const SARASHINA_COMPAT: ProviderModelConfig["compat"] = {
	supportsStore: false,
	supportsUsageInStreaming: false,
	supportsStrictMode: false,
	supportsDeveloperRole: false,
	requiresToolResultName: false,
	supportsLongCacheRetention: false,
};

const FREE_COST = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };

const openaiCompletions = openAICompletionsApi();

// Sarashina-specific wire fixes, applied inside streamSarashina's onPayload
// so they hold for every caller of the provider stream — not only the paths
// that emit before_provider_request. (In pi 0.85.1 the agent streamFn injects
// onPayload into summarization calls too, but any path that invokes the
// provider stream directly would otherwise bypass the rewrite.)
// - Sarashina rejects OpenAI-style content part arrays with 400 "Invalid
//   JSON"; flatten text parts back to a plain string.
// - sarashina3-guard is moderation-only: the API documents tools/tool_choice
//   as unsupported for it (verified: 400 "Bad Request"), and pi attaches
//   `tools` whenever the agent has tools (plus `tools: []` once history has
//   tool calls), so strip both fields for that model.
function rewriteSarashinaPayload(payload: unknown, modelId: string): unknown {
	const p = payload as
		| { messages?: Array<{ content?: unknown }>; tools?: unknown; tool_choice?: unknown }
		| undefined;
	if (!p) return payload;
	if (modelId === "sarashina3-guard") {
		delete p.tools;
		delete p.tool_choice;
	}
	if (!Array.isArray(p.messages)) return p;
	for (const message of p.messages) {
		if (Array.isArray(message.content)) {
			message.content = (message.content as Array<{ type?: string; text?: string }>)
				.filter((part) => part?.type === "text" && typeof part.text === "string")
				.map((part) => part.text)
				.join("\n");
		}
	}
	return p;
}

// Provider-level retries honoring Retry-After, scoped to sarashina only.
// Rationale: Sarashina rate-limits per fixed 60-second window. pi's agent-level
// retry (on by default) ignores Retry-After and waits 2s/4s/8s, so it can burn
// all attempts inside a single window; pi's provider-level retry waits exactly
// Retry-After but ships disabled (retry.provider.maxRetries = 0, a global
// setting). We turn it on here unless the caller already configured it, so a
// 429 waits out the window instead of failing fast. Losing the race still
// falls back to the agent-level retry.
function streamSarashina(
	model: Model<Api>,
	context: Context,
	options?: SimpleStreamOptions,
): AssistantMessageEventStream {
	const callerOnPayload = options?.onPayload;
	return openaiCompletions.streamSimple(model, context, {
		...options,
		maxRetries: options?.maxRetries || 3,
		// Compose after any caller-supplied onPayload (which is what carries
		// before_provider_request emissions) so the sarashina rewrite always
		// runs last and cannot be bypassed.
		onPayload: async (payload, m) =>
			rewriteSarashinaPayload((await callerOnPayload?.(payload, m)) ?? payload, model.id),
	});
}

const MODELS: ProviderModelConfig[] = [
	{
		id: "sarashina3.2-mini-thinking",
		name: "Sarashina 3.2 mini (thinking)",
		reasoning: true,
		// Sarashina only accepts low/medium/high. Unsupported levels are hidden
		// (clamped to the nearest supported one); "off" stays selectable and
		// sends no reasoning_effort at all.
		thinkingLevelMap: {
			minimal: null,
			low: "low",
			medium: "medium",
			high: "high",
		},
		input: ["text"],
		cost: FREE_COST,
		contextWindow: 128000,
		maxTokens: 8000,
		compat: { ...SARASHINA_COMPAT, supportsReasoningEffort: true },
	},
	{
		id: "sarashina3-mini",
		name: "Sarashina 3 mini",
		reasoning: false,
		input: ["text"],
		cost: FREE_COST,
		contextWindow: 128000,
		maxTokens: 8000,
		compat: { ...SARASHINA_COMPAT, supportsReasoningEffort: false },
	},
	{
		id: "sarashina3-nano",
		name: "Sarashina 3 nano",
		reasoning: false,
		input: ["text"],
		cost: FREE_COST,
		contextWindow: 128000,
		maxTokens: 8000,
		compat: { ...SARASHINA_COMPAT, supportsReasoningEffort: false },
	},
	{
		// Moderation model: returns e.g. "安全" or a harmful-category verdict.
		// No tools, no thinking.
		id: "sarashina3-guard",
		name: "Sarashina 3 guard",
		reasoning: false,
		input: ["text"],
		cost: FREE_COST,
		contextWindow: 64000,
		maxTokens: 8000,
		compat: { ...SARASHINA_COMPAT, supportsReasoningEffort: false },
	},
];

export default function (pi: ExtensionAPI) {
	pi.registerProvider("sarashina", {
		name: "Sarashina",
		// SARASHINA_BASE_URL can point at a local logging proxy for tracing;
		// unset it talks to the real endpoint.
		baseUrl: process.env.SARASHINA_BASE_URL ?? "https://api.sarashina.ai/v1",
		// Resolved per request from process.env only - pi does not read .env files.
		apiKey: "$SARASHINA_API_KEY",
		authHeader: true, // Authorization: Bearer <key>
		api: "openai-completions",
		models: MODELS,
		// Invoked because model.api matches the provider's api value; delegates
		// to the stock openai-completions stream with sarashina-scoped retry.
		streamSimple: streamSarashina,
	});

	// The thinking model's `reasoning` is an opaque encrypted blob; rendering it
	// as "thinking" text is unreadable. The transformer below swaps the displayed
	// markdown for a placeholder — display-only, the stored thinking content is
	// untouched so replay still sends the base64 verbatim. While a sarashina
	// model is selected we also relabel collapsed thinking blocks, restoring
	// pi's default when another provider's model is selected.
	let sarashinaActive = false;
	const applyThinkingUI = (active: boolean, ctx: ExtensionContext) => {
		sarashinaActive = active;
		if (active) {
			ctx.ui.setHiddenThinkingLabel("(encrypted reasoning)");
		} else {
			ctx.ui.setHiddenThinkingLabel();
		}
	};
	pi.on("session_start", (_event, ctx) => applyThinkingUI(ctx.model?.provider === "sarashina", ctx));
	pi.on("model_select", (event, ctx) => applyThinkingUI(event.model.provider === "sarashina", ctx));

	// Base64 blob heuristic: long, base64-charset-only thinking markdown.
	// Keeps a hypothetical future plaintext-reasoning sarashina model readable.
	const ENCRYPTED_REASONING_MD = /^[A-Za-z0-9+/=\s]+$/;
	pi.registerMarkdownTransformer((markdown, { messageType }) => {
		if (messageType !== "assistant-thinking" || !sarashinaActive) return markdown;
		const text = markdown.trim();
		if (text.length < 64 || !ENCRYPTED_REASONING_MD.test(text)) return markdown;
		return "*(encrypted reasoning — replayed verbatim on subsequent turns)*";
	});
}

02-trace-proxy.mjs #

// Tiny logging reverse proxy: 127.0.0.1:8787 -> https://api.sarashina.ai
// Logs request line, response status/headers (retry-after!), and each SSE
// line with a timestamp delta so stalls in the stream are visible.
import http from "node:http";
import https from "node:https";

const UPSTREAM = process.env.UPSTREAM_HOST ?? "api.sarashina.ai";
const PORT = Number(process.env.TRACE_PORT ?? 8787);
const log = (...a) => console.log(new Date().toISOString(), ...a);

http.createServer((req, res) => {
	const t0 = Date.now();
	const chunks = [];
	// Propagate downstream disconnects upstream: if the client (pi) aborts or
	// its socket dies, tear down the in-flight upstream request/response
	// instead of leaving generation running and sockets leaking.
	let u = null;
	let ur = null;
	res.on("close", () => {
		u?.destroy();
		ur?.destroy();
	});
	req.on("data", (c) => chunks.push(c));
	req.on("end", () => {
		const body = Buffer.concat(chunks);
		log(`--> ${req.method} ${req.url} body=${body.length}B`);
		u = https.request(
			{ host: UPSTREAM, path: req.url, method: req.method,
			  headers: { ...req.headers, host: UPSTREAM } },
			(upstreamRes) => {
				ur = upstreamRes;
				log(`<-- ${ur.statusCode} ${req.url} retry-after=${ur.headers["retry-after"] ?? "-"} +${Date.now() - t0}ms`);
				res.writeHead(ur.statusCode, ur.headers);
				let sse = "";
				ur.on("data", (c) => {
					res.write(c);
					sse += c.toString("utf8");
					let i;
					while ((i = sse.indexOf("\n")) >= 0) {
						const line = sse.slice(0, i).trimEnd();
						sse = sse.slice(i + 1);
						if (line) log(`    +${String(Date.now() - t0).padStart(6)}ms ${line.slice(0, 160)}`);
					}
				});
				ur.on("end", () => { res.end(); log(`    EOF ${req.url} +${Date.now() - t0}ms`); });
				ur.on("error", (e) => { log(`    ERR(up-res) ${req.url} ${e.message}`); res.destroy(e); });
			},
		);
		u.on("error", (e) => {
			log(`    ERR ${req.url} ${e.message}`);
			if (!res.headersSent) { res.writeHead(502).end(); } else { res.destroy(e); }
		});
		u.write(body);
		u.end();
	});
}).listen(PORT, "127.0.0.1", () => log(`listening on http://127.0.0.1:${PORT}`));

03-design.md #

gratui — 設計書(ラフ版) #

ターミナル上で有向グラフをASCIIアートっぽく可視化するCLIツール。 Go製・標準ライブラリのみ・go buildで単一バイナリにビルドできること。

動機 #

dot/graphvizを入れずに、エッジリストをポンポン流して雑にグラフの形を 確認したい。ターミナルだけで完結するのが嬉しい。

入力 #

エッジリスト形式のテキスト。1行1エッジ。

A -> B
B -> C
A -> C
C -> D
  • 区切りは ->(前後の空白はあってもなくてもよい)
  • # 始まりの行はコメントとして無視。空行も無視
  • 入力元: 引数のファイルパス。引数が無い or - のときは標準入力
  • 同じエッジの重複は1つにまとめる。ノード名は空白以外の文字列なら何でもよい (例: api-server, db_01, ユーザー)

出力(レイアウト) #

層別(layered)レイアウトで左から右に描画する。

  • トポロジカルソートで各ノードを「層」(= 任意の祖先からの最長距離)に割り当て、 層ごとに縦にノードを並べる
  • ノードは [名前] の形式で描く
  • エッジは ──▶ など罫線・矢印系の文字を使ってそれっぽく引く。 隣接層間は直線または斜め線でつなぐ。細部は実装に任せる(見た目が 分かればよい)
  • サイクルがある場合はトポロジカルソートができないので、検出したら 先頭行に cycle detected: ... と警告を出し、入力順の層割りで それっぽく描く(落ちないことが大事)
  • 孤立ノード(エッジの無いノード)は最終層の右にまとめてもよい

出力イメージ(この通りでなくてよい) #

[A] ──▶ [B] ──▶ [C] ──▶ [D]
 ╲           ╱
  ╲─────────▶

オプション #

  • gratui [file] — ファイル or 標準入力
  • --vertical — 上から下に流れる縦レイアウト(余力があれば)
  • --version — バージョン表示
  • -h / --help — 使い方

実装メモ(ヒント) #

  • go.mod は module gratui で。main + 1〜2ファイル程度の小ささで
  • パース → グラフ構築(隣接リスト+入次数)→ Kahn法で層割り → 描画、の流れ
  • 描画はキャンバス(2次元のrune配列)に文字を置いていって最後に 行ごと出力すると楽
  • テストは main_test.go にパースと層割りの分を少しだけ

非目標 #

  • 色つけ、インタラクティブ操作、マウス対応
  • 交差する辺のきれいなルーティング(それっぽければOK)
  • DOT言語の完全互換

04-main.go #

package main

import (
	"bufio"
	"flag"
	"fmt"
	"os"
	"regexp"
	"sort"
	"strings"
)

var (
	verticalFlag = flag.Bool("vertical", false, "use vertical layout (top to bottom)")
	versionFlag  = flag.Bool("version", false, "show version")
)

type Graph struct {
	edges    map[string][]string
	indegree map[string]int
	nodes    map[string]bool
}

func NewGraph() *Graph {
	return &Graph{
		edges:    make(map[string][]string),
		indegree: make(map[string]int),
		nodes:    make(map[string]bool),
	}
}

func (g *Graph) AddEdge(from, to string) {
	if !g.nodes[from] {
		g.nodes[from] = true
		g.indegree[from] = 0
	}
	if !g.nodes[to] {
		g.nodes[to] = true
		g.indegree[to] = 0
	}
	// Check if edge already exists to avoid duplicates
	for _, existing := range g.edges[from] {
		if existing == to {
			return
		}
	}
	g.edges[from] = append(g.edges[from], to)
	g.indegree[to]++
}

func parseEdges(input string) ([][]string, []string, error) {
	var edges [][]string
	var singleNodes []string
	lines := strings.Split(input, "\n")
	edgePattern := regexp.MustCompile(`^\s*([^#\s][^->]*?)\s*->\s*([^#\s].*?)\s*$`)
	
	for _, line := range lines {
		line = strings.TrimSpace(line)
		if line == "" || strings.HasPrefix(line, "#") {
			continue
		}
		
		// Remove inline comments (everything after first #)
		commentPos := strings.Index(line, "#")
		if commentPos >= 0 {
			line = strings.TrimSpace(line[:commentPos])
			if line == "" {
				continue
			}
		}
		
		matches := edgePattern.FindStringSubmatch(line)
		if len(matches) == 3 {
			from := strings.TrimSpace(matches[1])
			to := strings.TrimSpace(matches[2])
			edges = append(edges, []string{from, to})
		} else {
			// Single node without -> (e.g., "G")
			singleNodes = append(singleNodes, line)
		}
	}
	return edges, singleNodes, nil
}

func readInput(filename string) (string, error) {
	if filename == "-" || filename == "" {
		scanner := bufio.NewScanner(os.Stdin)
		var content strings.Builder
		for scanner.Scan() {
			content.WriteString(scanner.Text())
			content.WriteString("\n")
		}
		return content.String(), scanner.Err()
	}
	data, err := os.ReadFile(filename)
	if err != nil {
		return "", err
	}
	return string(data), nil
}

func topologicalSort(g *Graph) ([][]string, bool) {
	// Copy indegree map for processing
	indeg := make(map[string]int)
	for k, v := range g.indegree {
		indeg[k] = v
	}
	
	// Initialize queue with nodes having indegree 0
	queue := []string{}
	for node := range indeg {
		if indeg[node] == 0 {
			queue = append(queue, node)
		}
	}
	
	// Kahn's algorithm with layer tracking
	layers := [][]string{}
	
	// Sort initial queue for deterministic output
	sort.Strings(queue)
	
	for len(queue) > 0 {
		// Current layer consists of all nodes in the queue
		currentLayer := []string{}
		nextQueue := []string{}
		
		// Process all nodes in current layer
		for _, node := range queue {
			currentLayer = append(currentLayer, node)
			// For each neighbor, reduce indegree
			for _, neighbor := range g.edges[node] {
				indeg[neighbor]--
				if indeg[neighbor] == 0 {
					nextQueue = append(nextQueue, neighbor)
				}
			}
		}
		
		layers = append(layers, currentLayer)
		queue = nextQueue
		sort.Strings(queue)
	}
	
	// Check for cycles - count processed nodes
	processed := 0
	for _, layer := range layers {
		processed += len(layer)
	}
	
	hasCycle := processed < len(g.nodes)
	
	// If cycle exists, add remaining nodes to last layer
	if hasCycle {
		remaining := []string{}
		for node := range g.nodes {
			found := false
			for _, layer := range layers {
				for _, n := range layer {
					if n == node {
						found = true
						break
					}
				}
				if found {
					break
				}
			}
			if !found {
				remaining = append(remaining, node)
			}
		}
		if remaining != nil && len(remaining) > 0 {
			sort.Strings(remaining)
			layers = append(layers, remaining)
		}
	}
	
	return layers, hasCycle
}

func renderGraph(g *Graph, layers [][]string, hasCycle bool) {
	// For now, simple rendering
	if hasCycle {
		fmt.Printf("cycle detected\n")
	}
	
	// Simple horizontal layout
	if !*verticalFlag {
		// Print each layer horizontally
		for i, layer := range layers {
			if i > 0 {
				fmt.Print("   ")
			}
			for j, node := range layer {
				if j > 0 {
					fmt.Print("   ")
				}
				fmt.Printf("[%s]", node)
			}
			fmt.Println()
			
			// Print connections if not last layer
			if i < len(layers)-1 {
				for j := range layer {
					fmt.Print("      ")
					if j == 0 {
						fmt.Print("──▶")
					} else {
						fmt.Print("    ")
					}
				}
				fmt.Println()
			}
		}
	} else {
		// Vertical layout
		for i, layer := range layers {
			for _, node := range layer {
				fmt.Printf("[%s]\n", node)
			}
			if i < len(layers)-1 {
				fmt.Println("  ↓")
			}
		}
	}
}

func main() {
	flag.Usage = func() {
		fmt.Fprintf(flag.CommandLine.Output(), "Usage of %s:\n", os.Args[0])
		fmt.Fprintf(flag.CommandLine.Output(), "  gratui [file]\n")
		fmt.Fprintf(flag.CommandLine.Output(), "Options:\n")
		flag.PrintDefaults()
	}
	
	flag.Parse()
	
	if *versionFlag {
		fmt.Println("gratui v0.1.0")
		return
	}
	
	var filename string
	if len(flag.Args()) > 0 {
		filename = flag.Args()[0]
	} else {
		filename = "-"
	}
	
	content, err := readInput(filename)
	if err != nil {
		fmt.Fprintf(os.Stderr, "Error reading input: %v\n", err)
		os.Exit(1)
	}
	
	edges, singleNodes, err := parseEdges(content)
	if err != nil {
		fmt.Fprintf(os.Stderr, "Error parsing edges: %v\n", err)
		os.Exit(1)
	}
	
	// Build graph
	graph := NewGraph()
	for _, edge := range edges {
		graph.AddEdge(edge[0], edge[1])
	}
	// Add single nodes
	for _, node := range singleNodes {
		if !graph.nodes[node] {
			graph.nodes[node] = true
			graph.indegree[node] = 0
		}
	}
	
	// Topological sort with cycle detection
	layers, hasCycle := topologicalSort(graph)
	
	// Render graph
	renderGraph(graph, layers, hasCycle)
}

05-example.txt #

A -> B
B -> C
A -> C
C -> D

06-cycle.txt #

A -> B
B -> C
C -> A

07-complex.txt #

# This is a comment
A -> B
B -> C
# Another comment

D -> E
E -> F

G  # G is isolated