@1lon/pi-preset 0.0.0-stage → 0.1.0

package/.agents/skills/pi-preset-sync/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: pi-preset-sync
+description: 把本机 ~/.pi/agent 里的自定义扩展和第三方包清单同步回 my-pi-preset 仓库，并在用户确认后提交推送。当用户说「同步 preset」「把这个扩展同步进仓库」「更新我的 pi 扩展清单并提交」时使用。
+---
+
+# pi-preset-sync
+
+在 my-pi-preset 仓库的 clone 根目录中运行。把本机最新的 pi 扩展内容与包清单回写进仓库，
+经用户确认后提交并推送到 GitHub 的 `main`。
+
+`npx -y @1lon/pi-preset sync` 只负责让文件和清单一致；**git 操作由本 skill 编排**，
+因为它们需要用户拍板。
+
+## 流程
+
+### 1. 前置检查
+
+- 确认当前目录是本仓库 clone：`package.json` 的 `name` 为 `@1lon/pi-preset`。不是就停下来，
+  问用户仓库在哪。
+- 确认当前分支是 `main`：`git rev-parse --abbrev-ref HEAD`。不是 `main` 就停下来报告，
+  **不要自动切分支**。
+- 确认 git 身份：`git config user.name` 应为 `kelieCn`，`git config user.email` 应为
+  `kelieCn720@gmail.com`。不符就先提示用户（本仓库是 GitHub 个人仓库，公司身份会导致
+  CLA 校验失败且贡献不计数）。**只提示，绝不擅自修改全局 git 配置**；用户要求时用
+  `git config --local` 在本仓库内修正。
+
+### 2. 执行 sync
+
+```bash
+npx -y @1lon/pi-preset sync
+```
+
+`npx -y` 里的 `-y` 不能省，否则 npx 会停在「是否安装」的交互上。
+
+若用户提到要纳入某个本机新增的扩展文件，加 `--include <文件名>` 后重跑。
+若本机还没装过这个包、或想先确认差异，可先跑 `npx -y @1lon/pi-preset sync --dry-run`。
+
+### 3. 展示改动
+
+把 cli 输出的「新增 / 修改 / 删除」三段原样呈现给用户，**不要改写、不要省略、不要总结成一句话**。
+需要时补充说明：哪些文件变了、清单里都是哪些包、哪些本机包因为不可公开被排除。
+
+若三段皆空（输出「已是最新」），报告一句「已是最新，无需提交」然后结束——**不要提交空 commit**。
+
+### 4. 等用户确认
+
+停下来等明确答复。用户没说「可以 / 提交 / 推送」之前，不执行任何 git 命令。
+用户要求调整时，改完重跑第 2 步。
+
+### 5. 提交并推送
+
+用户确认后：
+
+```bash
+git add <本次 sync 触及的路径>     # 见下方约束
+git commit -m "<message>"
+git push origin main
+```
+
+commit message 按实际改动写，中文，一句话说明这次同步了什么（例如
+`sync: 更新 question-render 扩展并新增 pi-x 包`），不加 emoji。
+
+### 6. 报告
+
+给出 commit sha、推送结果（远端 + 分支），以及工作区是否干净。
+
+## 硬约束
+
+- **`git add` 只能加本次 sync 写过的具体路径**——`extensions/` 下变动的文件、
+  `presets/public.json`。**绝不能 `git add -A`、`git add .`、`git commit -a`**：
+  工作区里可能还有与本次同步无关的改动，一并提交会把它们带进仓库。
+- **commit message 不得包含 `Co-Authored-By` 之类的 AI 协作者 trailer。**
+- 只在当前 `main` 分支上提交推送，不切分支、不建分支、不 `--force`。
+- 推送失败（远端有新提交）时停下来报告，由用户决定 `pull --rebase` 还是合并；
+  不自动处理冲突。
+- 公司内网的包（如 `git:git@gitlab.basemind.com:...`）由 cli 自动排除在公开清单之外。
+  如果发现它出现在将被提交的内容里，**立刻停下**，不要推送。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kelieCn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,125 @@
-# Temporary Holding Version
+# my-pi-preset
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+我自己使用的 [pi](https://pi.dev) 扩展 preset。第三方包清单 + 手写的自定义扩展，
+换机时一条命令恢复，日常一条命令回写。
+
+```
+.
+├── src/
+│   ├── cli/
+│   │   ├── bin.ts             # 进程入口 → dist/cli.js
+│   │   ├── index.ts           # 注册所有命令 + main()
+│   │   ├── pull.ts            # pull 命令
+│   │   └── sync.ts            # sync 命令
+│   ├── types.ts               # 共用类型
+│   ├── paths.ts               # 包根 / agent 目录 / clone 校验
+│   ├── package-source.ts      # source 解析、身份归一、公开性白名单
+│   └── fs-helpers.ts          # 读写 JSON / 托管文件识别 / git 脏状态
+├── dist/cli.js                # 构建产物，bin 指向它
+├── test/unit/                 # vitest 单元套件（import src/，不构建）
+├── test/helpers/sandbox.ts    # 临时目录沙盒 + 子进程封装
+├── test-e2e/cli.e2e.ts        # spawn 真实进程的 e2e
+├── extensions/                # 手写的 pi 扩展
+├── presets/public.json        # 公开的第三方包清单
+└── .agents/skills/pi-preset-sync  # sync → 确认 → 提交推送
+```
+
+## 换机恢复
+
+```bash
+npx -y @1lon/pi-preset pull
+```
+
+做两件事，**只增不删、不改**：
+
+1. 把 `presets/public.json` 里本机还没有的包追加进 `~/.pi/agent/settings.json` 的 `packages`。
+   本机已存在的包原样保留——包括自己调过的资源过滤规则，不会被清单覆盖。
+2. 把 `extensions/` 下的扩展复制到 `~/.pi/agent/extensions/`。本机同名文件若内容不同，
+   先备份到 `.backup-<时间戳>/` 再覆盖。
+
+本机多出来的包（公司内部包、正在试用的包）一律不碰，因此两台机器之间可能出现漂移，
+这是刻意换来的：恢复命令永远不会破坏你正在进行的工作。
+
+跳过不碰的文件：软链、文件头声明 `installed by` / `managed by` 的文件、
+以及旁边带指纹文件（`xxx.js.xxx-hash`）的工具产物。
+
+公司内部使用的扩展不在本清单里，换公司机器时自己 `pi install` 一条。
+
+## 日常回写
+
+改完 `~/.pi/agent/extensions/` 下的扩展、或用 `pi install` / `pi remove` 调整过包之后，
+在本仓库 clone 的根目录触发 `pi-preset-sync` skill：它会跑 `sync`、把「新增/修改/删除」
+列给你确认，确认后执行 `git add`（只加本次同步的文件）/ `commit` / `push`。
+
+手动执行也可以（不提交，只写文件）：
+
+```bash
+npx -y @1lon/pi-preset sync --dry-run              # 只看差异
+npx -y @1lon/pi-preset sync                        # 写回当前目录的 clone
+npx -y @1lon/pi-preset sync --include new-ext.ts   # 顺带把本机新增的扩展纳入仓库
+```
+
+`sync` **不做任何 git 操作**。清单按白名单过滤：只有 `npm:` 和 `github.com` 的 git 源
+会写进 `presets/public.json`，任何内网地址或本地路径都会被丢弃并提示。
+
+`sync` 方向是「家目录覆盖仓库」，所以仓库里那份若有**未提交的改动**，默认跳过并列为
+冲突，不静默覆盖。确实要用家目录版本覆盖时加 `--force`。
+
+## 注意
+
+- 改扩展就改 `~/.pi/agent/extensions/` 下那份，重启 pi 生效，然后跑 sync。
+- **不要在 clone 里 `pi -e ./extensions/xxx.ts`**，也**不要 `pi install` 本仓库**。
+  pi 按解析后的绝对路径去重，同一扩展出现在两个路径下会被加载两次（工具名冲突、
+  renderer 重复注册）。本仓库的 `package.json` 不含 `pi` 字段、也没有 `pi-package` 关键词，
+  避免被当成资源包。
+- `pull` / `sync` 默认读 `~/.pi/agent`，可用 `--agent-dir` 或 `PI_CODING_AGENT_DIR` 指向别处。
+- 本仓库不要发布到公司私服：`publishConfig.registry` 已固定为公开 npm。
+- `extensions/pi-code-skills-dedup.ts` 在启动时从 `$PI_CODING_AGENT_DIR`（默认 `~/.pi/agent`）
+  下的 `npm/node_modules/pi-code/extensions/skills.ts` 解析 pi-code，不写死绝对路径。
+  找不到时只打一条 warning 并跳过 skill 去重，不会让 pi 启动失败。
+
+## 开发
+
+包管理器用 **pnpm**（`packageManager` 字段已锁 `pnpm@9.15.9`）。
+
+**Node 版本**：`engines` 声明 `>=22.19.0`，这是依赖决定的硬下限——
+`commander@15` 要求 `>=22.12.0`，`@earendil-works/*` 这两个 peer 要求 `>=22.19.0`。
+Node 20 装不上，`>=20` 是错的。
+
+本地开发还要再严一点：`tsdown@0.23` 的 `engines` 是
+`^22.18.0 || ^24.11.0 || >=26.0.0`，**排除了 23.x 和 25.x**。
+所以可用的开发版本是 22.19+、24.11+、26+。这条没写进 `engines`，
+因为它只影响构建，装包的人不需要满足。
+
+```bash
+pnpm install          # 装依赖
+pnpm dev --help       # = tsx src/cli/index.ts，改完不用构建
+pnpm typecheck        # tsc --noEmit，覆盖 src / extensions / test / test-e2e
+pnpm build            # tsdown → dist/cli.js
+pnpm test             # vitest 单元套件，进程内跑，不构建
+pnpm test:watch       # 单元套件 watch 模式
+pnpm test:e2e         # vitest e2e，spawn tsx 跑源码，不构建
+pnpm test:e2e:dist    # 先 build，再 spawn node dist/cli.js 验证产物
+pnpm test:all         # 三段全跑
+```
+
+测试分两层，和 `deck-cli` 同一个分法：
+
+- `test/unit/` — 只调纯函数（`planPull` / `planSync` / `parseSource` …），
+  import 的是 `src/`，vitest 自己转译 TypeScript，**改完源码立刻能跑**。
+  全部落在临时目录，不碰真实的 `~/.pi/agent`。
+- `test-e2e/` — spawn 真实进程，断言退出码、stdout/stderr 与落盘效果。
+  默认跑 `tsx src/cli/index.ts`，`E2E_TARGET=dist` 时改跑 `node dist/cli.js`。
+
+commander 的错误路径（未知子命令、未知选项）**只能在 e2e 里测**：
+它在子命令层面直接 `process.exit()`，同进程调用会杀掉测试进程本身。
+
+`bin` 始终指向 `dist/cli.js`，`prepublishOnly` 会先 typecheck 再 build，
+所以发布前不需要手动记住构建这一步。
+
+依赖的划分：
+
+- `dependencies` 只有 `commander`，CLI 运行时真正需要。
+- `@earendil-works/pi-coding-agent` / `pi-tui` 同时写在 `peerDependencies`（`"*"`）
+  和 `devDependencies`。peer 声明表达「`extensions/` 下的代码依赖宿主提供这两个模块」，
+  dev 声明让本仓库能做类型检查。

package/dist/cli.js

@@ -0,0 +1,524 @@
+#!/usr/bin/env node
+import { Command, CommanderError } from "commander";
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import { execFileSync } from "node:child_process";
+// src/paths.ts
+/**
+* 从本模块所在位置向上找最近的 package.json，作为包根。
+* 不能写成 `resolve(dirname(SELF), '..')`：源码在 src/cli/ 下（上两层才是包根），
+* 打包后在 dist/ 下（上一层就是包根），写死层数两边必然有一边错。
+*/
+function findPackageRoot(start) {
+	let dir = start;
+	for (;;) {
+		if (existsSync(join(dir, "package.json"))) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) throw new Error(`从 ${start} 向上找不到 package.json`);
+		dir = parent;
+	}
+}
+const PACKAGE_ROOT = findPackageRoot(dirname(fileURLToPath(import.meta.url)));
+const PACKAGE_JSON = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8"));
+const PACKAGE_NAME = PACKAGE_JSON.name;
+const PACKAGE_VERSION = PACKAGE_JSON.version;
+/** pi 的 agent 目录：可由 PI_CODING_AGENT_DIR 覆盖，默认 ~/.pi/agent。 */
+function resolveAgentDir(explicit) {
+	const candidate = explicit ?? process.env.PI_CODING_AGENT_DIR;
+	if (candidate) return resolve(candidate.replace(/^~(?=\/|$)/, homedir()));
+	return join(homedir(), ".pi", "agent");
+}
+/** 校验某个目录确实是本仓库的 clone，否则 sync 会写到不该写的地方。 */
+function assertRepoRoot(candidate) {
+	const root = resolve(candidate);
+	const pkgPath = join(root, "package.json");
+	if (!existsSync(pkgPath)) throw new Error(`${root} 不是本仓库：缺少 package.json`);
+	const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+	if (pkg.name !== PACKAGE_NAME) throw new Error(`${root} 不是本仓库：package.json 的 name 是 ${pkg.name}，应为 ${PACKAGE_NAME}`);
+	if (!existsSync(join(root, ".git"))) throw new Error(`${root} 不是仓库 clone：缺少 .git`);
+	return root;
+}
+// src/fs-helpers.ts
+/** 文件头出现这些字样说明该文件由别的工具托管，不归本项目管理。 */
+const MANAGED_RE = /\b(installed|managed|generated)\s+by\b/i;
+const MANAGED_HEAD_LINES = 30;
+/** 被当作 pi 扩展的文件后缀。 */
+const EXTENSION_RE = /\.(ts|js|mjs|cjs)$/;
+function readJson(path, fallback) {
+	if (!existsSync(path)) return fallback;
+	return JSON.parse(readFileSync(path, "utf8"));
+}
+function writeJson(path, value) {
+	mkdirSync(dirname(path), { recursive: true });
+	const tmp = `${path}.tmp-${process.pid}`;
+	writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`);
+	renameSync(tmp, path);
+}
+function listDirFiles(dir, filter = () => true) {
+	if (!existsSync(dir)) return [];
+	return readdirSync(dir, { withFileTypes: true }).filter((entry) => entry.isFile() && !entry.name.startsWith(".") && filter(entry.name)).map((entry) => entry.name).sort();
+}
+/**
+* 这个文件是不是由别的工具托管的。两种信号：
+* 1. 文件头若干行里有 "installed by" / "managed by" / "generated by"；
+* 2. 同目录存在以该文件名开头的旁挂文件（如 agentd-probe.js.agentd-hash）。
+* 第二条刻意不写死工具名，这样新工具也能被认出来。
+*/
+function isManagedFile(path) {
+	let text;
+	try {
+		text = readFileSync(path, "utf8");
+	} catch {
+		return false;
+	}
+	const head = text.split("\n", MANAGED_HEAD_LINES).join("\n");
+	if (MANAGED_RE.test(head)) return true;
+	try {
+		const dir = dirname(path);
+		const base = basename(path);
+		return readdirSync(dir).some((name) => name !== base && name.startsWith(`${base}.`));
+	} catch {
+		return false;
+	}
+}
+function sameContent(a, b) {
+	try {
+		return readFileSync(a, "utf8") === readFileSync(b, "utf8");
+	} catch {
+		return false;
+	}
+}
+/**
+* 仓库里这个路径是否有未提交的改动。
+* sync 的方向是「家目录覆盖仓库」，如果仓库那份写着自己还没同步出去的修改，
+* 直接覆盖就是静默丢代码——必须先让用户知道。
+*/
+function hasUncommittedChanges(repoRoot, relativePath) {
+	try {
+		return execFileSync("git", [
+			"-C",
+			repoRoot,
+			"status",
+			"--porcelain",
+			"--",
+			relativePath
+		], {
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim().length > 0;
+	} catch {
+		return false;
+	}
+}
+/** 备份目录用的时间戳，形如 20261026-171305。 */
+function stamp() {
+	const now = /* @__PURE__ */ new Date();
+	const pad = (value) => String(value).padStart(2, "0");
+	return [
+		now.getFullYear(),
+		pad(now.getMonth() + 1),
+		pad(now.getDate()),
+		"-",
+		pad(now.getHours()),
+		pad(now.getMinutes()),
+		pad(now.getSeconds())
+	].join("");
+}
+function indent(items) {
+	return items.map((item) => `  ${item}`).join("\n");
+}
+// src/package-source.ts
+/**
+* 解析一条 package source，与 pi 的 package-manager 保持同一套身份判定。
+* https://github.com/… 与 git@github.com:… 会归一成同一个身份。
+*/
+function parseSource(source) {
+	const raw = source.trim();
+	if (raw.startsWith("npm:")) return {
+		type: "npm",
+		name: npmPackageName(raw.slice(4).trim())
+	};
+	if (/^git:/.test(raw) || /^(https?|ssh|git):\/\//i.test(raw) || /^git@/.test(raw)) {
+		const git = parseGitLocation(raw);
+		if (git) return {
+			type: "git",
+			host: git.host,
+			path: git.path
+		};
+	}
+	return {
+		type: "local",
+		path: resolve(raw)
+	};
+}
+function packageIdentity(source) {
+	const parsed = parseSource(source);
+	if (parsed.type === "npm") return `npm:${parsed.name}`;
+	if (parsed.type === "git") return `git:${parsed.host}/${parsed.path}`;
+	return `local:${parsed.path}`;
+}
+function entrySource(entry) {
+	return typeof entry === "string" ? entry : entry.source;
+}
+/**
+* 公开性白名单。只有明确可以公开的形态才写进 public.json。
+* 刻意写成「谁能进」而不是「谁排除」：将来出现新的内网地址时默认被拒绝。
+*/
+function isPublicSource(source) {
+	const parsed = parseSource(source);
+	if (parsed.type === "npm") return true;
+	if (parsed.type === "git") return parsed.host === "github.com" || parsed.host === "www.github.com";
+	return false;
+}
+function npmPackageName(spec) {
+	if (!spec.startsWith("@")) return spec.split("@")[0] ?? spec;
+	const slash = spec.indexOf("/");
+	if (slash === -1) return spec;
+	const at = spec.indexOf("@", slash);
+	return at === -1 ? spec : spec.slice(0, at);
+}
+function parseGitLocation(raw) {
+	let value = raw.replace(/^git:/, "").trim();
+	const hash = value.indexOf("#");
+	if (hash !== -1) value = value.slice(0, hash);
+	value = value.replace(/\.git$/, "").replace(/\/$/, "");
+	let match = value.match(/^git@([^:]+):(.+)$/);
+	if (match) return {
+		host: match[1],
+		path: match[2]
+	};
+	match = value.match(/^(?:https?|ssh|git):\/\/(?:[^@/]+@)?([^/:]+)(?::\d+)?\/(.+)$/i);
+	if (match) return {
+		host: match[1],
+		path: match[2]
+	};
+	match = value.match(/^([^/:]+\.[^/:]+)\/(.+)$/);
+	if (match) return {
+		host: match[1],
+		path: match[2]
+	};
+	return null;
+}
+// src/cli/pull.ts
+function registerPull(program, withCommon) {
+	withCommon(program.command("pull").description("仓库 → 本机：补齐清单中缺少的包，复制仓库 extensions/ 下的扩展文件").action(runPull));
+}
+function runPull(options) {
+	const agentDir = resolveAgentDir(options.agentDir);
+	const dryRun = Boolean(options.dryRun);
+	const plan = planPull({
+		repoRoot: PACKAGE_ROOT,
+		agentDir
+	});
+	printPullSummary(plan, applyPull(plan, { dryRun }), dryRun);
+}
+/**
+* 只增不删、不改：清单里某个 source 在本机已存在的，条目原样保留
+* （包括本机自己调过的资源过滤规则），本机没有的才追加。
+*/
+function planPull(options) {
+	const manifest = readJson(join(options.repoRoot, "presets", "public.json"), { packages: [] });
+	const settingsPath = join(options.agentDir, "settings.json");
+	const settings = readJson(settingsPath, {});
+	const existing = new Set((settings.packages ?? []).map((entry) => packageIdentity(entrySource(entry))));
+	const toAdd = [];
+	for (const entry of manifest.packages ?? []) {
+		const identity = packageIdentity(entrySource(entry));
+		if (existing.has(identity)) continue;
+		existing.add(identity);
+		toAdd.push(entry);
+	}
+	const sourceDir = join(options.repoRoot, "extensions");
+	const targetDir = join(options.agentDir, "extensions");
+	const files = {
+		added: [],
+		modified: [],
+		unchanged: [],
+		skipped: []
+	};
+	for (const name of listDirFiles(sourceDir, (file) => EXTENSION_RE.test(file))) {
+		const target = join(targetDir, name);
+		let isLink = false;
+		let exists = true;
+		try {
+			isLink = lstatSync(target).isSymbolicLink();
+		} catch {
+			exists = false;
+		}
+		if (!exists) {
+			files.added.push(name);
+			continue;
+		}
+		if (isLink) {
+			files.skipped.push({
+				name,
+				reason: "本机是软链"
+			});
+			continue;
+		}
+		if (isManagedFile(target)) {
+			files.skipped.push({
+				name,
+				reason: "文件头声明由其他工具托管"
+			});
+			continue;
+		}
+		if (sameContent(join(sourceDir, name), target)) files.unchanged.push(name);
+		else files.modified.push(name);
+	}
+	return {
+		settingsPath,
+		settings,
+		toAdd,
+		files,
+		sourceDir,
+		targetDir
+	};
+}
+function applyPull(plan, options) {
+	const { settingsPath, settings, toAdd, files, sourceDir, targetDir } = plan;
+	if (options.dryRun) return {};
+	if (toAdd.length > 0) {
+		settings.packages = [...settings.packages ?? [], ...toAdd];
+		writeJson(settingsPath, settings);
+	}
+	const touching = [...files.added, ...files.modified];
+	let backupDir;
+	if (touching.length > 0) {
+		mkdirSync(targetDir, { recursive: true });
+		if (files.modified.length > 0) {
+			backupDir = join(targetDir, `.backup-${stamp()}`);
+			mkdirSync(backupDir, { recursive: true });
+			for (const name of files.modified) copyFileSync(join(targetDir, name), join(backupDir, name));
+		}
+		for (const name of touching) copyFileSync(join(sourceDir, name), join(targetDir, name));
+	}
+	return { backupDir };
+}
+function printPullSummary(plan, result, dryRun) {
+	const lines = [];
+	const touched = [...plan.files.added, ...plan.files.modified];
+	if (touched.length > 0) {
+		lines.push(`扩展文件 ${dryRun ? "将复制" : "已复制"}：`);
+		lines.push(indent(touched));
+	}
+	if (plan.toAdd.length > 0) {
+		lines.push(`包清单 ${dryRun ? "将新增" : "已新增"} ${plan.toAdd.length} 项：`);
+		lines.push(indent(plan.toAdd.map((entry) => packageIdentity(entrySource(entry)))));
+	}
+	if (plan.files.unchanged.length > 0) lines.push(`未变化：${plan.files.unchanged.length} 个扩展文件`);
+	for (const item of plan.files.skipped) lines.push(`跳过 ${item.name}（${item.reason}）`);
+	if (result.backupDir) lines.push(`旧文件已备份到 ${result.backupDir}`);
+	if (touched.length === 0 && plan.toAdd.length === 0) lines.push("已是最新，无需改动。");
+	process.stdout.write(`${lines.join("\n")}\n`);
+}
+// src/cli/sync.ts
+function registerSync(program, withCommon) {
+	withCommon(program.command("sync").description("本机 → 仓库：把扩展文件与包清单写回当前 clone（不执行 git 操作）").option("--repo <path>", "clone 路径，默认当前目录").option("--include <file>", "把本机某个新扩展文件纳入仓库（可多次指定）", collect, []).option("-f, --force", "忽略「仓库有未提交改动」的保护，用家目录版本覆盖").action(runSync));
+}
+function collect(value, previous) {
+	return [...previous, value];
+}
+function runSync(options) {
+	const repoRoot = assertRepoRoot(options.repo ?? process.cwd());
+	const agentDir = resolveAgentDir(options.agentDir);
+	const dryRun = Boolean(options.dryRun);
+	const plan = planSync({
+		repoRoot,
+		agentDir,
+		include: options.include ?? [],
+		force: Boolean(options.force)
+	});
+	printSyncSummary(plan, dryRun);
+	applySync(plan, { dryRun });
+}
+function planSync(options) {
+	const include = options.include ?? [];
+	const homeExtDir = join(options.agentDir, "extensions");
+	const repoExtDir = join(options.repoRoot, "extensions");
+	const repoFiles = listDirFiles(repoExtDir, (file) => EXTENSION_RE.test(file));
+	const homeFiles = listDirFiles(homeExtDir, (file) => EXTENSION_RE.test(file));
+	const extensions = {
+		added: [],
+		modified: [],
+		missing: [],
+		unmanaged: [],
+		conflicts: []
+	};
+	for (const name of repoFiles) {
+		const home = join(homeExtDir, name);
+		if (!existsSync(home) || isManagedFile(home)) {
+			extensions.missing.push(name);
+			continue;
+		}
+		if (sameContent(join(repoExtDir, name), home)) continue;
+		if (!options.force && hasUncommittedChanges(options.repoRoot, join("extensions", name))) {
+			extensions.conflicts.push({
+				name,
+				reason: "仓库这份有未提交的改动，家目录也不同步；先用 --force 覆盖或手工合并"
+			});
+			continue;
+		}
+		extensions.modified.push(name);
+	}
+	for (const name of homeFiles) {
+		if (repoFiles.includes(name)) continue;
+		if (include.includes(name)) {
+			extensions.added.push(name);
+			continue;
+		}
+		if (isManagedFile(join(homeExtDir, name))) continue;
+		extensions.unmanaged.push(name);
+	}
+	const settings = readJson(join(options.agentDir, "settings.json"), {});
+	const incoming = [];
+	const dropped = [];
+	for (const entry of settings.packages ?? []) {
+		const source = entrySource(entry);
+		if (isPublicSource(source)) incoming.push(entry);
+		else dropped.push(source);
+	}
+	const manifestPath = join(options.repoRoot, "presets", "public.json");
+	const previous = readJson(manifestPath, { packages: [] }).packages ?? [];
+	const previousByIdentity = new Map(previous.map((entry) => [packageIdentity(entrySource(entry)), entry]));
+	const incomingIdentities = /* @__PURE__ */ new Set();
+	const packages = {
+		added: [],
+		modified: [],
+		deleted: []
+	};
+	for (const entry of incoming) {
+		const identity = packageIdentity(entrySource(entry));
+		incomingIdentities.add(identity);
+		const before = previousByIdentity.get(identity);
+		if (before === void 0) packages.added.push(identity);
+		else if (JSON.stringify(before) !== JSON.stringify(entry)) packages.modified.push(identity);
+	}
+	for (const entry of previous) {
+		const identity = packageIdentity(entrySource(entry));
+		if (!incomingIdentities.has(identity)) packages.deleted.push(identity);
+	}
+	return {
+		homeExtDir,
+		repoExtDir,
+		extensions,
+		manifestPath,
+		packages,
+		nextPackages: incoming,
+		dropped
+	};
+}
+function applySync(plan, options) {
+	if (options.dryRun) return;
+	for (const name of [...plan.extensions.added, ...plan.extensions.modified]) copyFileSync(join(plan.homeExtDir, name), join(plan.repoExtDir, name));
+	if (plan.packages.added.length + plan.packages.modified.length + plan.packages.deleted.length > 0) writeJson(plan.manifestPath, { packages: plan.nextPackages });
+}
+/** 输出「新增 / 修改 / 删除」三段，供 pi-preset-sync skill 原样转发给用户确认。 */
+function printSyncSummary(plan, dryRun) {
+	const { extensions, packages } = plan;
+	const added = [...extensions.added, ...packages.added];
+	const modified = [...extensions.modified, ...packages.modified];
+	const deleted = [...packages.deleted];
+	const sections = [];
+	sections.push(dryRun ? "变更预览（--dry-run，未落盘）" : "已同步到当前 clone");
+	for (const [label, items] of [
+		["新增", added],
+		["修改", modified],
+		["删除", deleted]
+	]) {
+		if (items.length === 0) continue;
+		sections.push(`\n${label} (${items.length})`);
+		sections.push(indent(items));
+	}
+	if (added.length + modified.length + deleted.length === 0) sections.push("\n已是最新。");
+	if (extensions.conflicts.length > 0) {
+		sections.push(`\n冲突：仓库有未提交改动，已跳过 (${extensions.conflicts.length})`);
+		sections.push(indent(extensions.conflicts.map((item) => item.name)));
+		for (const item of extensions.conflicts) sections.push(`  ${item.reason}`);
+	}
+	if (extensions.missing.length > 0) {
+		sections.push(`\n本机缺失、已保留仓库版本 (${extensions.missing.length})`);
+		sections.push(indent(extensions.missing));
+	}
+	if (extensions.unmanaged.length > 0) {
+		sections.push(`\n本机新增但未纳入管理 (${extensions.unmanaged.length})`);
+		sections.push(indent(extensions.unmanaged));
+		sections.push("  确认要纳入时重跑：npx -y @1lon/pi-preset sync --include <文件名>");
+	}
+	if (plan.dropped.length > 0) {
+		sections.push(`\n不写入公开清单 (${plan.dropped.length})`);
+		sections.push(indent(plan.dropped));
+	}
+	process.stdout.write(`${sections.join("\n")}\n`);
+}
+// src/cli/index.ts
+/**
+* pi-preset — 把本仓库（清单 + 自定义扩展）与本机 pi 配置双向对齐。
+*
+*   pull   仓库 → 本机
+*   sync   本机 → 仓库（不做 git 操作）
+*
+* 作为 bin（dist/cli.js 或 tsx src/cli/index.ts）直接执行时会自己跑 main()，
+* 被 import 时则什么都不做。
+*/
+/** pull 与 sync 共有的选项。 */
+function withCommonOptions(command) {
+	return command.option("--agent-dir <path>", "pi 配置目录，默认 $PI_CODING_AGENT_DIR 或 ~/.pi/agent").option("-n, --dry-run", "只打印将要做的改动，不落盘");
+}
+function buildProgram() {
+	const program = new Command();
+	program.name("pi-preset").description("个人 pi 扩展 preset：把仓库里的包清单与自定义扩展对齐到本机，或反向写回").version(PACKAGE_VERSION);
+	registerPull(program, withCommonOptions);
+	registerSync(program, withCommonOptions);
+	return program;
+}
+/**
+* 跑一次 CLI，返回退出码。
+*
+* 只对根命令 exitOverride：子命令报错时 commander 仍会直接 process.exit()，
+* 退出码正确，只是超过约 128 KB 的输出可能被截断（本项目输出只有几百字节）。
+*/
+function main(argv = process.argv.slice(2)) {
+	const program = buildProgram();
+	program.exitOverride();
+	program.configureOutput({ writeErr: (str) => process.stderr.write(str) });
+	if (argv.length === 0) {
+		program.outputHelp();
+		return 0;
+	}
+	try {
+		program.parse(argv, { from: "user" });
+		return 0;
+	} catch (error) {
+		if (error instanceof CommanderError) return error.exitCode === 0 ? 0 : 1;
+		throw error;
+	}
+}
+/**
+* 本文件既是 bin 也是可 import 的模块。判断「是否被直接执行」不能只比
+* resolve(argv[1])：通过 npm/pnpm 的 bin 软链调用时 argv[1] 是软链路径，
+* 而 import.meta.url 是 dist/cli.js 的真实路径，两者不相等会让 CLI 静默什么都不做。
+*/
+function isEntryPoint() {
+	const argv1 = process.argv[1];
+	if (!argv1) return false;
+	const self = fileURLToPath(import.meta.url);
+	try {
+		return realpathSync(argv1) === realpathSync(self);
+	} catch {
+		return resolve(argv1) === self;
+	}
+}
+if (isEntryPoint()) try {
+	process.exitCode = main();
+} catch (error) {
+	process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+	process.exitCode = 1;
+}
+export { applyPull, applySync, assertRepoRoot, buildProgram, entrySource, isPublicSource, main, packageIdentity, parseSource, planPull, planSync, printPullSummary, printSyncSummary, resolveAgentDir, runPull, runSync };

package/extensions/pi-code-skills-dedup.ts

@@ -0,0 +1,109 @@
+/**
+ * 为 pi-code 的 Skills 桥接增加按名称去重和原始输入显示。
+ * 保留 Pi 已加载的版本和 Claude 路径中原有的先到先得顺序。
+ * 原始输入单独持久化为不进入模型上下文的条目，不改变动态参数展开。
+ */
+import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { loadSkills, UserMessageComponent, type ExtensionAPI } from '@earendil-works/pi-coding-agent'
+
+const ORIGINAL_INPUT_ENTRY = 'skill-original-input'
+
+/** pi 的 agent 目录：可由 PI_CODING_AGENT_DIR 覆盖，默认 ~/.pi/agent。 */
+function resolveAgentDir(): string {
+  return process.env.PI_CODING_AGENT_DIR
+    ? resolve(process.env.PI_CODING_AGENT_DIR.replace(/^~(?=\/|$)/, homedir()))
+    : join(homedir(), '.pi', 'agent')
+}
+
+/**
+ * 定位 pi-code 的 skills 扩展。
+ * 不能写死绝对路径：换机器、换用户名、或 pi-code 换安装位置都会失效。
+ * 依次尝试：pi 的 agent 目录下的 npm 安装根。
+ */
+function resolvePiCodeSkills(): string | undefined {
+  const agentDir = resolveAgentDir()
+  const candidates = [
+    join(agentDir, 'npm', 'node_modules', 'pi-code', 'extensions', 'skills.ts'),
+    join(agentDir, 'node_modules', 'pi-code', 'extensions', 'skills.ts'),
+  ]
+  return candidates.find(candidate => existsSync(candidate))
+}
+
+export default async function piCodeSkillsDedup(pi: ExtensionAPI) {
+  const skillsPath = resolvePiCodeSkills()
+  if (!skillsPath) {
+    // pi-code 没装（或改了目录结构）：本扩展无事可做，但也不能让 pi 因此报错。
+    // UI 只存在于事件回调的 ctx 上，ExtensionAPI 本身没有 ui，所以推迟到 session_start。
+    pi.on('session_start', (_event, ctx) => {
+      ctx.ui.notify('pi-code-skills-dedup: 未找到 pi-code 的 skills 扩展，已跳过 skill 去重。', 'warning')
+    })
+    return
+  }
+  const piCodeSkills = (await import(skillsPath)).default as (api: ExtensionAPI) => unknown
+
+  pi.registerEntryRenderer<{ text: string }>(ORIGINAL_INPUT_ENTRY, (entry) => {
+    if (typeof entry.data?.text !== 'string') return undefined
+    // 不随 skill 的展开状态折叠；复用 user 组件以兼容现有 UI 样式。
+    return new UserMessageComponent(entry.data.text, undefined, pi.getSettings().outputPad)
+  })
+
+  const wrapped = new Proxy(pi, {
+    get(target, property, receiver) {
+      if (property !== 'on') return Reflect.get(target, property, receiver)
+      return (event: string, handler: (...args: any[]) => any) => {
+        if (event === 'input') {
+          return target.on('input', async (input, ctx) => {
+            const name = input.text.trimStart().match(/^\/skill:([^\s]+)(?:\s|$)/)?.[1]
+            const isUserSkill = input.source !== 'extension' && name && target.getCommands().some(
+              command => command.source === 'skill' && command.name === `skill:${name}`,
+            )
+            if (isUserSkill) {
+              // 在原处理器展开/排队之前追加，确保 user 原文排在 skill 块前。
+              // custom entry 随会话保存，但不会给模型重复注入用户请求。
+              target.appendEntry(ORIGINAL_INPUT_ENTRY, { text: input.text })
+            }
+            return handler(input, ctx)
+          })
+        }
+        if (event !== 'resources_discover') return target.on(event as any, handler)
+        return target.on('resources_discover', async (event, ctx) => {
+          const resources = await handler(event, ctx)
+          if (!resources?.skillPaths?.length) return resources
+
+          const existingNames = new Set(
+            target.getCommands()
+              .filter(command => command.source === 'skill')
+              .map(command => command.name.replace(/^skill:/, '')),
+          )
+          // 使用 Pi 自己的解析器，保持 SKILL.md 命名、忽略规则和软链接语义。
+          const candidates = loadSkills({
+            cwd: ctx.cwd,
+            agentDir: resolveAgentDir(),
+            skillPaths: resources.skillPaths,
+            includeDefaults: false,
+          })
+          const skillPaths = candidates.skills
+            .filter(skill => !existingNames.has(skill.name))
+            .map(skill => skill.filePath)
+
+          // 只消除重名项；损坏的文件仍交回 Pi，让其正常显示解析诊断。
+          const validPaths = new Set(candidates.skills.map(skill => resolve(skill.filePath)))
+          for (const diagnostic of candidates.diagnostics) {
+            if (diagnostic.type === 'collision' && diagnostic.path) {
+              validPaths.add(resolve(diagnostic.path))
+            }
+          }
+          for (const diagnostic of candidates.diagnostics) {
+            if (diagnostic.type !== 'collision' && diagnostic.path && !validPaths.has(resolve(diagnostic.path))) {
+              skillPaths.push(diagnostic.path)
+            }
+          }
+          return { ...resources, skillPaths: [...new Set(skillPaths)] }
+        })
+      }
+    },
+  })
+  return piCodeSkills(wrapped)
+}

package/extensions/question-render.ts

@@ -0,0 +1,93 @@
+/**
+ * Make a batched `question` call readable in the transcript.
+ *
+ * pi-code's `question` tool takes one question (`question` + `options`) or a batch
+ * (`questions: [...]`), and only the single shape renders. For a batch:
+ *
+ *   - Its `renderCall` reads `args.question`, which does not exist, so the call line is empty — and
+ *     pi-compact-tools, which summarizes a custom call from its scalar arguments, finds nothing
+ *     either, leaving the space right of the tool name blank.
+ *   - `execute` returns `{ ...collected[0], questions }`, but its `renderResult` reads
+ *     `details.answer`, so one answer out of three is drawn and `details.questions` is never read.
+ *
+ * Both are fixed by shaping the data rather than the drawing, in two event handlers:
+ *
+ *   - `tool_call` adds a `question` string to the arguments. pi-code prefers `questions` when both
+ *     are present (`questionList`), so execution is unchanged, and both renderers now find a
+ *     summary. compact-tools draws it right of the tool name, in its own style.
+ *   - `tool_result` replaces the result text with one `问：… 答：…` line per question and drops
+ *     `details`. Without details, pi-code's result renderer prints the text verbatim, which
+ *     compact-tools embeds as the expanded body of its row.
+ *
+ * Shaping data instead of wrapping renderers keeps this out of the row-rendering contest:
+ * compact-tools' `session_start` reconciliation replaces the renderer wrapper on every existing
+ * transcript row with its own (`unwrap` only recognizes wrappers it made), which silently undoes a
+ * `registerToolRenderer` wrapper after `/reload`. Values in the data survive that, and are
+ * persisted, so a row keeps rendering correctly in later sessions and in exports.
+ *
+ * The cost of dropping `details`: the structured answers are no longer in the session record, only
+ * the formatted text. Calls made before this extension existed keep their old rendering, since their
+ * data was already written.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+/** pi-code truncates a header to this width for its label slot; matched here. */
+const HEADER_MAX = 12;
+/** How much of a question's text stands in for a missing header. */
+const QUESTION_MAX = 16;
+
+interface QuestionDetails {
+  question: string;
+  header?: string;
+  options: string[];
+  answer: string | null;
+  wasCustom?: boolean;
+  multiSelect?: boolean;
+  timedOut?: boolean;
+}
+
+function clip(text: string, max: number): string {
+  const trimmed = String(text ?? "").trim();
+  return trimmed.length > max ? `${trimmed.slice(0, max - 1)}…` : trimmed;
+}
+
+/** The short label a question is identified by: its header, or the question itself. */
+function tag(entry: { header?: string; question?: string }): string {
+  return entry.header ? clip(entry.header, HEADER_MAX) : clip(entry.question ?? "", QUESTION_MAX);
+}
+
+function batchOf(value: unknown): Array<{ header?: string; question?: string }> | undefined {
+  const list = (value as { questions?: unknown } | undefined)?.questions;
+  return Array.isArray(list) && list.length > 0 ? (list as Array<{ header?: string; question?: string }>) : undefined;
+}
+
+/** What the answer to one question was, in the words of the state it ended in. */
+function answerText(detail: QuestionDetails): string {
+  if (detail.answer === null) return "(已取消)";
+  if (detail.timedOut) return detail.answer ? `(超时自动继续，已选 ${detail.answer})` : "(超时自动继续)";
+  if (detail.wasCustom) return `${detail.answer}（手写）`;
+  if (detail.multiSelect) return detail.answer || "(未选)";
+  const index = detail.options.indexOf(detail.answer) + 1;
+  return index > 0 ? `${index}. ${detail.answer}` : detail.answer;
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on("tool_call", (event) => {
+    if (event.toolName !== "question") return;
+    const input = event.input as Record<string, unknown>;
+    const list = batchOf(input);
+    // Leave a single question, and anything that already has a summary, alone.
+    if (!list || typeof input.question === "string") return;
+    input.question = list.map(tag).join(" / ");
+  });
+
+  pi.on("tool_result", (event) => {
+    if (event.toolName !== "question") return;
+    const list = (event.details as { questions?: QuestionDetails[] } | undefined)?.questions;
+    if (!list?.length) return;
+    const text = list.map((detail, i) => `问：${i + 1}. ${detail.question}  答：${answerText(detail)}`).join("\n");
+    // Returning no `details` clears them, which is what makes pi-code print this text as-is.
+    return { content: [{ type: "text" as const, text }] };
+  });
+}

package/extensions/user-message-frame.ts

@@ -0,0 +1,145 @@
+/**
+ * Frame user messages with a labelled top rule and a plain bottom rule.
+ *
+ * Pi has no public hook for rendering user messages (`registerMessageRenderer` only covers custom
+ * messages), so this wraps `UserMessageComponent.prototype.render`. The wrapper does exactly two
+ * things per render: call the original, and prepend/append one line. No caching, no scanning of the
+ * rendered text, no walking of the Markdown tree, so it cannot become the slow part of a render pass.
+ *
+ * Left and right borders are deliberately omitted: a leading `│` ends up in the clipboard whenever
+ * the message is copied out of the terminal.
+ *
+ * The filled background behind the text is dropped too, and the message text is pinned to the muted
+ * near-white of the reference design. Themes have no say in either: the active theme's
+ * `userMessageBg` and `userMessageText` are rewritten on the fly, which is what a theme declaring
+ * those tokens as `""` and `"#d4d7d9"` would do.
+ *
+ * `customMessageBg` is filled in the same way, for the opposite reason. Skill blocks and custom
+ * messages are drawn as a `Box` painted with that token, and a theme that leaves it at `""` (as
+ * github-dark-pro does) gives them the terminal's own background, so an expanded skill block runs
+ * into the surrounding prose. The theme's own panel color separates it again.
+ *
+ * Everything happens when the extension loads, with no `session_start` handler: `/reload` builds a
+ * new runtime without starting a new session, so a patch installed from a session event would leave
+ * the previous load's wrapper in place and the new code dead.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { UserMessageComponent } from "@earendil-works/pi-coding-agent";
+import {
+  backgroundAnsi,
+  foregroundAnsi,
+  parseColor,
+  stripTerminalSequences,
+  type TerminalColorMode,
+  visibleWidth,
+} from "@earendil-works/pi-tui";
+
+/** Holds the unwrapped render so a `/reload` re-wraps the original instead of stacking wrappers. */
+const ORIGINAL_RENDER = Symbol.for("user-message-frame.originalRender");
+/** Where pi keeps the active theme so every module loader, jiti included, sees the same instance. */
+const THEME_KEY = Symbol.for("@earendil-works/pi-coding-agent:theme");
+
+const LABEL = " User ";
+/**
+ * The rules and the label take the theme's `dim`, the same muted gray the reference screenshot uses
+ * (`#6e7681` under github-dark-pro). Bright white was too loud next to the message text.
+ */
+const RULE_TOKEN = "dim";
+const RESET = "\x1b[0m";
+/** The escape sequence a theme token set to `""` renders as: the terminal's own background. */
+const DEFAULT_BG = "\x1b[49m";
+/** Message text, measured off the reference screenshot. */
+const TEXT_COLOR = parseColor("#d4d7d9");
+/** Panel behind skill blocks and custom messages: github-dark-pro's own card color. */
+const CUSTOM_BG_COLOR = parseColor("#161b22");
+/** Leading OSC sequences, such as the OSC 133 prompt zones pi marks user messages with. */
+const OSC_PREFIX = /^(?:\x1b\][^\x07]*\x07)+/;
+
+/** Themes already adjusted; a theme switch brings a new object, which is adjusted in turn. */
+const adjusted = new WeakSet<object>();
+
+function activeTheme(): ThemeLike | undefined {
+  return (globalThis as Record<symbol, ThemeLike | undefined>)[THEME_KEY];
+}
+
+/** The parts of pi's `Theme` this extension touches. */
+interface ThemeLike {
+  fgAnsi?: Map<string, string>;
+  bgAnsi?: Map<string, string>;
+  getFgAnsi?: (token: string) => string;
+  getColorMode?: () => TerminalColorMode;
+}
+
+/**
+ * Repoint the message tokens this extension owns. `fgAnsi` and `bgAnsi` hold the precomputed escape
+ * sequence per token, so one Map write each covers every later render.
+ */
+function adjustTheme(theme: ThemeLike | undefined): void {
+  if (!theme || adjusted.has(theme)) return;
+  adjusted.add(theme);
+  // Goes through the theme's own color mode, so a 256-color terminal gets the nearest index.
+  const mode = theme.getColorMode?.() ?? "truecolor";
+  if (theme.bgAnsi instanceof Map) {
+    theme.bgAnsi.set("userMessageBg", DEFAULT_BG);
+    theme.bgAnsi.set("customMessageBg", backgroundAnsi(CUSTOM_BG_COLOR, mode));
+  }
+  if (theme.fgAnsi instanceof Map) {
+    theme.fgAnsi.set("userMessageText", foregroundAnsi(TEXT_COLOR, mode));
+  }
+}
+
+function isBlank(line: string): boolean {
+  return stripTerminalSequences(line).trim().length === 0;
+}
+
+function rule(width: number, label: boolean, osc: string, theme: ThemeLike | undefined): string {
+  const fg = theme?.getFgAnsi?.(RULE_TOKEN) ?? "";
+  const labelled = label && width >= visibleWidth(LABEL) + 4;
+  const body = labelled
+    ? `─${LABEL}${"─".repeat(width - 1 - visibleWidth(LABEL))}`
+    : "─".repeat(width);
+  return `${osc}${fg}${body}${fg ? RESET : ""}`;
+}
+
+function patchRender(): void {
+  const proto = UserMessageComponent.prototype as unknown as Record<string | symbol, unknown>;
+  const original = (proto[ORIGINAL_RENDER] ?? proto.render) as
+    | ((width: number) => string[])
+    | undefined;
+  if (typeof original !== "function") return;
+  proto[ORIGINAL_RENDER] = original;
+  proto.render = function framedRender(this: unknown, width: number): string[] {
+    const theme = activeTheme();
+    adjustTheme(theme);
+    const lines = original.call(this, width);
+    if (!Array.isArray(lines) || lines.length === 0) return lines;
+    const w = Math.max(1, Math.floor(width));
+    // The original pads with a blank row above and below the text. The rules take those rows, so
+    // the frame hugs the message the way a border would; the prompt-zone markers pi puts on the
+    // outermost rows move onto the rules with them.
+    let body = lines;
+    let topOsc = "";
+    let bottomOsc = "";
+    const first = body[0];
+    if (body.length > 1 && first !== undefined && isBlank(first)) {
+      topOsc = OSC_PREFIX.exec(first)?.[0] ?? "";
+      body = body.slice(1);
+    }
+    const last = body[body.length - 1];
+    if (body.length > 1 && last !== undefined && isBlank(last)) {
+      bottomOsc = OSC_PREFIX.exec(last)?.[0] ?? "";
+      body = body.slice(0, -1);
+    }
+    return [rule(w, true, topOsc, theme), ...body, rule(w, false, bottomOsc, theme)];
+  };
+}
+
+export default function (pi: ExtensionAPI) {
+  patchRender();
+  // A skill block can be the first thing painted in a session, before any user message pulled the
+  // token overrides in through the render path below.
+  pi.on("session_start", () => {
+    adjustTheme(activeTheme());
+  });
+}

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@1lon/pi-preset",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "My personal pi coding agent preset: package manifest + custom extensions",
+  "type": "module",
+  "packageManager": "pnpm@9.15.9",
+  "bin": {
+    "pi-preset": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "extensions",
+    "presets",
+    ".agents"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "tsx src/cli/index.ts",
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "tsc --noEmit && tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "vitest run --config vitest.config.e2e.ts",
+    "test:e2e:dist": "tsdown && E2E_TARGET=dist vitest run --config vitest.config.e2e.ts",
+    "test:all": "vitest run && npm run test:e2e && npm run test:e2e:dist"
+  },
+  "dependencies": {
+    "commander": "^15.0.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^1.4.0",
+    "@earendil-works/pi-tui": "^1.4.0",
+    "@types/node": "^26.6.5",
+    "tsdown": "^0.23.2",
+    "tsx": "^4.19.0",
+    "typescript": "^7.0.2",
+    "vitest": "^2.1.9"
+  },
+  "license": "MIT"
+}

package/presets/public.json

@@ -0,0 +1,18 @@
+{
+  "packages": [
+    "npm:@tintinweb/pi-subagents",
+    "npm:pi-input-history",
+    "npm:pi-init",
+    "npm:pi-powerline-footer",
+    "git:github.com/obra/superpowers",
+    {
+      "source": "npm:pi-code",
+      "extensions": [
+        "!extensions/mcp/**",
+        "!extensions/subagent/**",
+        "!extensions/skills.ts"
+      ]
+    },
+    "npm:pi-compact-tools"
+  ]
+}