@maxiaochao/pi-toolkit 0.9.2 → 0.9.4

package/packages/tiny-subagent/src/runner.ts

@@ -0,0 +1,319 @@
+import { createWriteStream, existsSync, realpathSync } from "node:fs";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { tmpdir } from "node:os";
+import { spawn } from "node:child_process";
+
+export const MAX_INLINE_BYTES = 16 * 1024;
+const CHILD_ENV = "PI_SUBAGENT_CHILD";
+const BINARY_ENV = "PI_TINY_SUBAGENT_PI_BINARY";
+
+export interface TinySubagentOptions {
+ model?: string;
+ thinking?: string;
+ tools?: string[];
+ systemPrompt?: string;
+ cwd?: string;
+ signal?: AbortSignal;
+ onUpdate?: (result: TinySubagentResult) => void;
+}
+
+export interface TinySubagentArtifacts {
+ directory: string;
+ stdout: string;
+ stderr: string;
+ finalOutput?: string;
+ cleanup: "remove directory when no longer needed";
+}
+
+export interface TinySubagentContent {
+ type?: string;
+ text?: string;
+ name?: string;
+ arguments?: Record<string, unknown>;
+}
+
+export interface TinySubagentMessage {
+ role?: string;
+ content?: string | TinySubagentContent[];
+ toolCallId?: string;
+ toolName?: string;
+ isError?: boolean;
+ stopReason?: string;
+ errorMessage?: string;
+ model?: string;
+}
+
+export interface TinySubagentResult {
+ ok: boolean;
+ output: string;
+ outputBytes: number;
+ stderr: string;
+ stderrBytes: number;
+ stdout: string;
+ stdoutBytes: number;
+ protocolErrors: string[];
+ errorMessage?: string;
+ stopReason?: string;
+ exitCode: number | null;
+ signal: NodeJS.Signals | null;
+ model?: string;
+ cwd: string;
+ durationMs: number;
+ messages: TinySubagentMessage[];
+ artifacts?: TinySubagentArtifacts;
+}
+
+interface JsonEvent {
+ type?: string;
+ message?: TinySubagentMessage;
+}
+
+class Capture {
+	private readonly stream;
+	private inline = "";
+	private truncated = false;
+	bytes = 0;
+
+	readonly path: string;
+	constructor(path: string) {
+		this.path = path;
+		this.stream = createWriteStream(path, { encoding: "utf8", mode: 0o600 });
+	}
+
+
+	write(text: string): void {
+		this.bytes += Buffer.byteLength(text, "utf8");
+		this.stream.write(text);
+		if (this.truncated) return;
+		const next = this.inline + text;
+		if (Buffer.byteLength(next, "utf8") <= MAX_INLINE_BYTES) {
+			this.inline = next;
+			return;
+		}
+		this.inline = truncateUtf8(next, MAX_INLINE_BYTES);
+		this.truncated = true;
+	}
+
+	async close(): Promise<void> {
+		await new Promise<void>((resolve, reject) => {
+			this.stream.once("error", reject);
+			this.stream.once("finish", resolve);
+			this.stream.end();
+		});
+	}
+
+	preview(): string {
+		return this.truncated ? `${this.inline}\n[truncated after ${MAX_INLINE_BYTES} bytes; see artifact file]` : this.inline;
+	}
+}
+
+function truncateUtf8(text: string, maxBytes: number): string {
+	let result = text.slice(0, maxBytes);
+	while (Buffer.byteLength(result, "utf8") > maxBytes) result = result.slice(0, -1);
+	return result;
+}
+
+function getFinalText(messages: TinySubagentMessage[]): string {
+ for (let i = messages.length - 1; i >= 0; i--) {
+  const message = messages[i];
+  if (message.role !== "assistant" || !Array.isArray(message.content)) continue;
+  return message.content
+   .filter((part) => part.type === "text" && typeof part.text === "string")
+   .map((part) => part.text as string)
+   .join("");
+ }
+ return "";
+}
+
+function parseLine(line: string, messages: TinySubagentMessage[], protocolErrors: string[]): boolean {
+ if (!line.trim()) return false;
+ try {
+  const event = JSON.parse(line) as JsonEvent;
+  if ((event.type === "message_end" || event.type === "tool_result_end") && event.message) {
+   messages.push(event.message);
+   return true;
+  }
+ } catch {
+  if (protocolErrors.length < 20) protocolErrors.push(truncateUtf8(line, 4096));
+ }
+ return false;
+}
+
+function getPiInvocation(args: string[]): { command: string; args: string[] } {
+	const configuredBinary = process.env[BINARY_ENV]?.trim();
+	if (configuredBinary) return { command: configuredBinary, args };
+
+	const entry = process.argv[1];
+	if (entry && existsSync(entry) && /\.(?:mjs|cjs|js)$/i.test(entry)) {
+		try {
+			const resolved = realpathSync(entry);
+			if (resolved === entry || existsSync(resolved)) return { command: process.execPath, args: [entry, ...args] };
+		} catch {
+			// Fall through to the Pi binary on PATH.
+		}
+	}
+
+	if (/^pi(?:\.exe)?$/i.test(basename(process.execPath))) return { command: process.execPath, args };
+	return { command: "pi", args };
+}
+
+function stopReasonIsFailure(stopReason: string | undefined): boolean {
+	return stopReason === "error" || stopReason === "aborted";
+}
+
+export async function runTinySubagent(prompt: string, options: TinySubagentOptions = {}): Promise<TinySubagentResult> {
+	const cwd = options.cwd ?? process.cwd();
+	const artifactDirectory = await mkdtemp(join(tmpdir(), "pi-tiny-subagent-"));
+	const stdoutCapture = new Capture(join(artifactDirectory, "stdout.jsonl"));
+	const stderrCapture = new Capture(join(artifactDirectory, "stderr.log"));
+	const args = ["--mode", "json", "--print", "--no-session", "--no-extensions", "--no-skills"];
+	if (options.model?.trim()) args.push("--model", options.model.trim());
+	if (options.thinking?.trim()) args.push("--thinking", options.thinking.trim());
+	if (options.tools?.length) args.push("--tools", options.tools.join(","));
+	if (options.systemPrompt?.trim()) {
+		const systemPromptPath = join(artifactDirectory, "system-prompt.md");
+		await writeFile(systemPromptPath, options.systemPrompt, { encoding: "utf8", mode: 0o600 });
+		args.push("--append-system-prompt", systemPromptPath);
+	}
+	args.push("--", prompt);
+
+	const startedAt = Date.now();
+	const messages: TinySubagentMessage[] = [];
+	const protocolErrors: string[] = [];
+	let stdoutBuffer = "";
+	let errorMessage: string | undefined;
+	let aborted = false;
+	let exitCode: number | null = null;
+	let childSignal: NodeJS.Signals | null = null;
+	let spawnError: Error | undefined;
+	let child: ReturnType<typeof spawn> | undefined;
+	const invocation = getPiInvocation(args);
+
+
+	const emitUpdate = () => {
+		if (!options.onUpdate) return;
+		const output = getFinalText(messages);
+		const lastAssistant = [...messages].reverse().find((message) => message.role === "assistant");
+		options.onUpdate({
+			ok: false,
+			output,
+			outputBytes: Buffer.byteLength(output, "utf8"),
+			stderr: stderrCapture.preview(),
+			stderrBytes: stderrCapture.bytes,
+			stdout: stdoutCapture.preview(),
+			stdoutBytes: stdoutCapture.bytes,
+			protocolErrors: [...protocolErrors],
+			...(lastAssistant?.stopReason ? { stopReason: lastAssistant.stopReason } : {}),
+			exitCode,
+			signal: childSignal,
+			...(options.model ?? lastAssistant?.model ? { model: options.model ?? lastAssistant?.model } : {}),
+			cwd,
+			durationMs: Date.now() - startedAt,
+			messages: messages.slice(),
+		});
+	};
+
+	emitUpdate();
+	await new Promise<void>((resolve) => {
+		let settled = false;
+		const finish = () => {
+			if (settled) return;
+			settled = true;
+			resolve();
+		};
+		try {
+			child = spawn(invocation.command, invocation.args, {
+				cwd,
+				shell: false,
+				stdio: ["ignore", "pipe", "pipe"],
+				env: { ...process.env, [CHILD_ENV]: "1" },
+			});
+		} catch (error) {
+			spawnError = error instanceof Error ? error : new Error(String(error));
+			finish();
+			return;
+		}
+		child.stdout?.on("data", (chunk: Buffer | string) => {
+			const text = chunk.toString();
+			stdoutCapture.write(text);
+			stdoutBuffer += text;
+			const lines = stdoutBuffer.split("\n");
+			stdoutBuffer = lines.pop() ?? "";
+			for (const line of lines) {
+				if (parseLine(line, messages, protocolErrors)) emitUpdate();
+			}
+		});
+		child.stderr?.on("data", (chunk: Buffer | string) => stderrCapture.write(chunk.toString()));
+		child.once("error", (error) => {
+			spawnError = error;
+		});
+		child.once("close", (code, signal) => {
+			if (stdoutBuffer && parseLine(stdoutBuffer, messages, protocolErrors)) emitUpdate();
+			// Node may report a negative pseudo-exit code for ENOENT; expose a stable process failure code and keep the real error in errorMessage.
+			exitCode = spawnError ? 1 : code;
+			childSignal = signal;
+			finish();
+		});
+
+		const terminate = () => {
+			if (aborted) return;
+			aborted = true;
+			child?.kill("SIGTERM");
+			setTimeout(() => {
+				if (child && !child.killed) child.kill("SIGKILL");
+			}, 5000).unref();
+		};
+		if (options.signal) {
+			if (options.signal.aborted) terminate();
+			else options.signal.addEventListener("abort", terminate, { once: true });
+		}
+	});
+
+	await Promise.all([stdoutCapture.close(), stderrCapture.close()]);
+	const finalOutput = getFinalText(messages);
+	const lastAssistant = [...messages].reverse().find((message) => message.role === "assistant");
+	const stopReason = lastAssistant?.stopReason;
+	errorMessage = spawnError?.message ?? lastAssistant?.errorMessage;
+	if (aborted) errorMessage ||= "Tiny subagent was aborted";
+	if (!finalOutput && exitCode === 0 && !stopReason) errorMessage ||= "No assistant output received";
+	if (protocolErrors.length > 0 && !finalOutput && !errorMessage) errorMessage = "Pi emitted invalid JSON output";
+	if (stopReasonIsFailure(stopReason)) errorMessage ||= `Subagent stopped with reason: ${stopReason}`;
+
+	const outputBytes = Buffer.byteLength(finalOutput, "utf8");
+	const keepArtifacts = stdoutCapture.bytes > MAX_INLINE_BYTES || stderrCapture.bytes > MAX_INLINE_BYTES || outputBytes > MAX_INLINE_BYTES;
+	let artifacts: TinySubagentArtifacts | undefined;
+	if (keepArtifacts) {
+		const finalOutputPath = join(artifactDirectory, "final-output.txt");
+		if (outputBytes > 0) await writeFile(finalOutputPath, finalOutput, { encoding: "utf8", mode: 0o600 });
+		artifacts = {
+			directory: artifactDirectory,
+			stdout: stdoutCapture.path,
+			stderr: stderrCapture.path,
+			cleanup: "remove directory when no longer needed",
+			...(outputBytes > MAX_INLINE_BYTES ? { finalOutput: finalOutputPath } : {}),
+		};
+	} else {
+		await rm(artifactDirectory, { recursive: true, force: true });
+	}
+
+	return {
+		ok: !errorMessage && exitCode === 0 && childSignal === null && !stopReasonIsFailure(stopReason),
+		output: outputBytes > MAX_INLINE_BYTES ? `${truncateUtf8(finalOutput, MAX_INLINE_BYTES)}\n[truncated after ${MAX_INLINE_BYTES} bytes; see artifact file]` : finalOutput,
+		outputBytes,
+		stderr: stderrCapture.preview(),
+		stderrBytes: stderrCapture.bytes,
+		stdout: stdoutCapture.preview(),
+		stdoutBytes: stdoutCapture.bytes,
+		protocolErrors,
+		...(errorMessage ? { errorMessage } : {}),
+		...(stopReason ? { stopReason } : {}),
+		exitCode,
+		signal: childSignal,
+		...(options.model ?? lastAssistant?.model ? { model: options.model ?? lastAssistant?.model } : {}),
+		cwd,
+		durationMs: Date.now() - startedAt,
+		messages: messages.slice(),
+		...(artifacts ? { artifacts } : {}),
+	};
+}

package/packages/tiny-subagent/tests/run-tests.mjs

@@ -0,0 +1,111 @@
+import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { discoverPackageAgents, parseAgentMarkdown } from "../src/personas.ts";
+import { MAX_INLINE_BYTES, runTinySubagent } from "../src/runner.ts";
+
+let passed = 0;
+let failed = 0;
+function check(name, condition, detail = "") {
+	if (condition) {
+		passed += 1;
+		console.log(`PASS ${name}`);
+	} else {
+		failed += 1;
+		console.log(`FAIL ${name} ${detail}`);
+	}
+}
+
+const root = mkdtempSync(join(tmpdir(), "pi-tiny-subagent-test-"));
+const fakePi = join(root, "fake-pi.mjs");
+writeFileSync(fakePi, `#!/usr/bin/env node
+import { appendFileSync, readFileSync } from "node:fs";
+const args = process.argv.slice(2);
+const capture = process.env.TINY_CAPTURE;
+if (capture) appendFileSync(capture, JSON.stringify({ args, cwd: process.cwd(), child: process.env.PI_SUBAGENT_CHILD, promptFile: args[args.indexOf("--append-system-prompt") + 1] ? readFileSync(args[args.indexOf("--append-system-prompt") + 1], "utf8") : null }) + "\\n");
+const mode = process.env.TINY_MODE || "success";
+if (mode === "abort") { setTimeout(() => {}, 30000); }
+if (mode === "success") {
+  process.stdout.write(JSON.stringify({ type: "message_end", message: { role: "assistant", model: "fake/model", stopReason: "stop", content: [{ type: "text", text: "worker result" }] } }) + "\\n");
+} else if (mode === "events") {
+  process.stdout.write(JSON.stringify({ type: "message_end", message: { role: "assistant", content: [{ type: "toolCall", name: "bash", arguments: { command: "printf live" } }] } }) + "\\n");
+  process.stdout.write(JSON.stringify({ type: "tool_result_end", message: { role: "toolResult", toolName: "bash", toolCallId: "call-1", isError: false, content: [{ type: "text", text: "live result" }] } }) + "\\n");
+  process.stdout.write(JSON.stringify({ type: "message_end", message: { role: "assistant", model: "fake/model", stopReason: "stop", content: [{ type: "text", text: "event result" }] } }) + "\\n");
+} else if (mode === "error") {
+  process.stderr.write("provider failed\\n");
+  process.stdout.write(JSON.stringify({ type: "message_end", message: { role: "assistant", stopReason: "error", errorMessage: "rate limited", content: [] } }) + "\\n");
+  process.exitCode = 7;
+} else if (mode === "protocol") {
+  process.stdout.write("not-json\\n");
+  process.exitCode = 2;
+} else if (mode === "large") {
+  const text = "x".repeat(${MAX_INLINE_BYTES + 1000});
+  process.stderr.write("e".repeat(${MAX_INLINE_BYTES + 1000}));
+  process.stdout.write(JSON.stringify({ type: "message_end", message: { role: "assistant", stopReason: "stop", content: [{ type: "text", text }] } }) + "\\n");
+}
+`, { encoding: "utf8", mode: 0o700 });
+chmodSync(fakePi, 0o700);
+
+const capture = join(root, "capture.jsonl");
+const oldEnv = { ...process.env };
+function setEnv(values) {
+	for (const key of Object.keys(process.env)) delete process.env[key];
+	Object.assign(process.env, oldEnv, values);
+}
+function restoreEnv() {
+	for (const key of Object.keys(process.env)) delete process.env[key];
+	Object.assign(process.env, oldEnv);
+}
+
+try {
+	setEnv({ PI_TINY_SUBAGENT_PI_BINARY: fakePi, TINY_CAPTURE: capture, TINY_MODE: "success" });
+	const success = await runTinySubagent("hello", { cwd: root, model: "fake/model", tools: ["read"], systemPrompt: "You are a worker." });
+	const launch = JSON.parse(readFileSync(capture, "utf8").trim());
+	check("success output", success.ok && success.output === "worker result");
+	check("model, tools, and fresh-process flags", launch.args.includes("--model") && launch.args.includes("fake/model") && launch.args.includes("--tools") && launch.args.includes("read") && launch.args.includes("--no-session") && launch.args.includes("--no-extensions") && launch.args.includes("--no-skills"));
+	check("cwd and child marker", launch.cwd === root && launch.child === "1");
+	check("persona system prompt file", launch.promptFile === "You are a worker.");
+
+ setEnv({ PI_TINY_SUBAGENT_PI_BINARY: fakePi, TINY_MODE: "events" });
+ const updates = [];
+ const events = await runTinySubagent("events", { cwd: root, onUpdate: (partial) => updates.push(partial) });
+ check("event transcript and live updates", events.ok && events.output === "event result" && events.messages.length === 3 && events.messages[0].content?.[0]?.type === "toolCall" && events.messages[1].role === "toolResult" && updates.length >= 4 && updates.at(-1).messages.length === 3);
+
+	setEnv({ PI_TINY_SUBAGENT_PI_BINARY: fakePi, TINY_MODE: "error" });
+	const error = await runTinySubagent("fail", { cwd: root });
+	check("Pi error details", !error.ok && error.exitCode === 7 && error.stopReason === "error" && error.errorMessage === "rate limited" && error.stderr.includes("provider failed"));
+	setEnv({ PI_TINY_SUBAGENT_PI_BINARY: fakePi, TINY_MODE: "protocol" });
+	const protocol = await runTinySubagent("bad", { cwd: root });
+	check("protocol error details", !protocol.ok && protocol.exitCode === 2 && protocol.protocolErrors.includes("not-json"));
+
+	setEnv({ PI_TINY_SUBAGENT_PI_BINARY: "/definitely/missing/pi", TINY_MODE: "success" });
+	const missing = await runTinySubagent("missing", { cwd: root });
+	check("spawn error details", !missing.ok && missing.exitCode === 1 && missing.errorMessage?.includes("ENOENT"));
+
+	setEnv({ PI_TINY_SUBAGENT_PI_BINARY: fakePi, TINY_MODE: "large" });
+	const large = await runTinySubagent("large", { cwd: root });
+	check("large output spills to artifacts", large.ok && large.artifacts && large.artifacts.cleanup.includes("remove directory") && large.output.includes("see artifact file") && large.outputBytes > MAX_INLINE_BYTES && large.artifacts.finalOutput && readFileSync(large.artifacts.finalOutput, "utf8").length > MAX_INLINE_BYTES);
+	if (large.artifacts) rmSync(large.artifacts.directory, { recursive: true, force: true });
+
+	setEnv({ PI_TINY_SUBAGENT_PI_BINARY: fakePi, TINY_MODE: "abort" });
+	const controller = new AbortController();
+	const pending = runTinySubagent("abort", { cwd: root, signal: controller.signal });
+	setTimeout(() => controller.abort(), 50);
+	const aborted = await pending;
+	check("abort details", !aborted.ok && aborted.errorMessage === "Tiny subagent was aborted");
+
+	const definition = parseAgentMarkdown(`---\nname: reviewer\ndescription: Review code\nmodel: fake/model\ntools: read, grep\n---\nReview carefully.`, "reviewer.md");
+	check("persona frontmatter parsing", definition.name === "reviewer" && definition.model === "fake/model" && definition.tools?.join(",") === "read,grep" && definition.systemPrompt === "Review carefully.");
+	const agentsDir = join(root, "agents");
+	await import("node:fs/promises").then(({ mkdir }) => mkdir(agentsDir));
+	writeFileSync(join(agentsDir, "worker.md"), `---\nname: worker\ndescription: Worker\n---\nDo work.`);
+	writeFileSync(join(agentsDir, "broken.md"), "not frontmatter");
+	const discovery = discoverPackageAgents(agentsDir);
+	check("persona discovery and diagnostics", discovery.agents.length === 1 && discovery.agents[0].name === "worker" && discovery.diagnostics.length === 1);
+} finally {
+	restoreEnv();
+	rmSync(root, { recursive: true, force: true });
+}
+
+console.log(`${passed} passed, ${failed} failed`);
+if (failed > 0) process.exitCode = 1;

package/packages/todo/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 2026-09-30 - v0.1.0
+
+- 从 `@maxiaochao/pi-toolkit` 提取 todo 权威源码，支持主包捆绑和独立安装。

package/packages/todo/README.md

@@ -0,0 +1,63 @@
+# @maxiaochao/pi-todo
+
+Pi 的会话清单扩展，提供 `todo` 工具、自动推进的生命周期、活跃任务 widget 和 `/todos` 历史视图。
+
+![Todo 真实状态机运行截图](docs/screenshot.png)
+
+## 为什么有这个包
+
+这是 pi-toolkit 自研的计划执行模块，用明确状态替代只存在于对话文本里的计划。它解决计划替换后旧任务残留、多个任务同时 doing、完成后不自动推进，以及 UI 序号与持久 ID 混用的问题。
+
+## 演示
+
+![Todo 生命周期演示](docs/demo.gif)
+
+```text
+todo({ action: "replace", items: ["Inspect callers", "Implement", "Verify"] })
+todo({ action: "update", id: 1, status: "done" })
+/todos
+```
+
+第一项完成后下一项自动进入 `doing`；`/todos` 同时展示活跃队列和关闭历史。
+
+## 安装
+
+完整工具包已经包含本扩展：
+
+```bash
+pi install npm:@maxiaochao/pi-toolkit
+```
+
+只需要 todo 时单独安装：
+
+```bash
+pi install npm:@maxiaochao/pi-todo
+```
+
+两种方式二选一，避免重复注册。
+
+## 更新
+
+```bash
+pi update npm:@maxiaochao/pi-toolkit  # 更新主包内置版本
+pi update npm:@maxiaochao/pi-todo     # 更新独立子包
+```
+
+两个 npm 包版本独立。Todo 源码变更只有在发布新主包后才会到达主包用户，发布子包本身不会更新主包。
+
+## 行为
+
+- `replace` 用新计划替换旧计划，并将未完成旧任务标记为取消。
+- `add`、`update`、`remove`、`clear` 管理任务。
+- 同一时间最多一个任务为 `doing`，完成后自动推进下一项。
+- widget 使用连续队列位置；持久记录保留稳定内部 ID。
+
+## 开发与测试
+
+权威源码位于 `extensions/` 和 `src/`。测试流程、用例和最近验证结果见 [TESTING.md](TESTING.md)。
+
+```bash
+npm --prefix packages/todo test
+npm --prefix packages/todo run load-test
+npm pack ./packages/todo --dry-run
+```

package/packages/todo/TESTING.md

@@ -0,0 +1,20 @@
+# Todo 测试方案
+
+## 流程
+
+1. `npm --prefix packages/todo test`：运行纯状态机确定性测试。
+2. `npm --prefix packages/todo run load-test`：让 Pi 加载真实扩展入口。
+3. `npm pack ./packages/todo --dry-run`：确认发布文件完整。
+4. 确认由真实状态机输出生成的 `docs/screenshot.png` 和 `docs/demo.gif` 可打开且进入 tarball。
+
+## 用例数据
+
+- 恢复旧格式记录并修复非法生命周期。
+- `replace` 取消旧的活跃任务并建立新队列。
+- 完成当前任务后自动推进下一项。
+- 删除、清空、非法 ID 和非法状态处理。
+- widget 队列位置连续，内部 ID 保持稳定。
+
+## 最近验证结果
+
+迁移基线：状态机测试全部通过，扩展可由 Pi 独立加载。发布前必须重新运行上述三步；跳过的检查不算通过。

package/{extensions → packages/todo/extensions}/todo.ts

@@ -19,7 +19,7 @@ import {
 	type TodoAction,
 	type TodoState,
 	type TodoStatus,
-} from "./todo-state.ts";
+} from "../src/todo-state.ts";
 
 interface TodoDetails {
 	action: TodoAction;

package/packages/todo/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@maxiaochao/pi-todo",
+  "version": "0.1.0",
+  "description": "Session checklist and todo lifecycle extension for Pi.",
+  "type": "module",
+  "keywords": ["pi-package", "pi-extension", "todo"],
+  "files": ["extensions", "src", "docs", "README.md", "TESTING.md", "CHANGELOG.md"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chaochaoxiaochao/pi-toolkit.git",
+    "directory": "packages/todo"
+  },
+  "pi": { "extensions": ["./extensions/todo.ts"] },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types tests/todo-state.mjs",
+    "load-test": "pi -ne -e ./extensions/todo.ts"
+  },
+  "publishConfig": { "access": "public" }
+}

package/{extensions → packages/todo}/tests/todo-state.mjs

@@ -4,7 +4,7 @@ import {
 	activeTodos,
 	applyTodoAction,
 	restoreTodoState,
-} from "../todo-state.ts";
+} from "../src/todo-state.ts";
 
 const empty = { todos: [], nextId: 1 };
 

package/packages/worktree/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 2026-09-30 - v0.1.0
+
+- 将 pi-worktree CLI、bash completion 和 Pi skill 合并为可独立安装的子包。

package/packages/worktree/README.md

@@ -0,0 +1,60 @@
+# @maxiaochao/pi-worktree
+
+`pi-worktree` CLI 与配套 Pi skill。CLI 创建、检查和清理 Git worktree，并在隔离目录中启动 Pi。
+
+![Worktree 在真实临时 Git 仓库中的运行截图](docs/screenshot.png)
+
+## 为什么有这个包
+
+这个包把原来分散在主包中的 shell CLI、bash completion、安装逻辑和 agent skill 合成一个发布单元。它让人和 agent 使用同一套隔离流程，避免在主 checkout 中混入并行任务改动。
+
+## 演示
+
+![Worktree 隔离流程演示](docs/demo.gif)
+
+```bash
+pi-worktree start feature -p "implement the feature"
+pi-worktree info feature
+pi-worktree out
+pi-worktree remove feature
+```
+
+`start` 从当前分支创建或复用 `.worktrees/feature`，记录 base，并在该目录启动 Pi。
+
+## 安装
+
+完整工具包已经包含 CLI 和 skill：
+
+```bash
+pi install npm:@maxiaochao/pi-toolkit
+```
+
+只需要 worktree 能力时单独安装：
+
+```bash
+pi install npm:@maxiaochao/pi-worktree
+```
+
+postinstall 会把 CLI 复制到 `~/.local/bin/pi-worktree`，把 bash completion 安装到 `~/.local/share/bash-completion/completions/pi-worktree`。两种安装方式二选一。
+
+## 更新
+
+```bash
+pi update npm:@maxiaochao/pi-toolkit  # 更新主包内置的 CLI 与 skill
+pi update npm:@maxiaochao/pi-worktree # 更新独立子包
+```
+
+更新会重新运行安装逻辑并覆盖 `~/.local/bin/pi-worktree` 和 completion。主包与子包版本独立，不要同时安装。
+
+## 命令
+
+```bash
+pi-worktree start <name> [pi args...]
+pi-worktree list
+pi-worktree info <name>
+pi-worktree out
+pi-worktree remove <name>
+pi-worktree prune
+```
+
+Agent 用法见 `skills/pi-worktree/SKILL.md`。测试流程、夹具和结果见 [TESTING.md](TESTING.md)。

package/packages/worktree/TESTING.md

@@ -0,0 +1,21 @@
+# Worktree 测试方案
+
+## 流程
+
+1. `npm --prefix packages/worktree test`：在临时 Git 仓库中使用假的 `pi` 命令运行 CLI。
+2. `npm pack ./packages/worktree --dry-run`：确认 CLI、completion、skill 和安装脚本进入 tarball。
+3. 手工验收发布包的 `pi-worktree start` 交互流程。
+4. 确认 README 示例、真实临时 Git 仓库输出 `docs/screenshot.png` 和 `docs/demo.gif` 进入 tarball。
+
+## 用例数据
+
+- `--help` 输出命令说明。
+- `start` 从当前分支创建 `.worktrees/<name>` 并记录 base。
+- 假 Pi 收到正确工作目录和参数。
+- `list` 标记主 checkout 和子 worktree。
+- `info` 报告 clean、branch、base 和 ahead。
+- postinstall 把可执行 CLI 与 completion 复制到隔离 HOME，并保持执行权限。
+
+## 最近验证结果
+
+迁移基线要求全部 shell 断言通过，且 `npm pack --dry-run` 包含 `bin/`、`skills/` 和 `scripts/install.mjs`。