@wingsbutterfly/pi-zh 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wings1848
+
+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

@@ -0,0 +1,107 @@
+# pi-zh — Pi 汉化插件
+
+[![npm version](https://img.shields.io/npm/v/@wingsbutterfly/pi-zh)](https://www.npmjs.com/package/@wingsbutterfly/pi-zh)
+[![license](https://img.shields.io/npm/l/@wingsbutterfly/pi-zh)](LICENSE)
+[![CI](https://github.com/wings1848/pi-zh/actions/workflows/ci.yml/badge.svg)](https://github.com/wings1848/pi-zh/actions/workflows/ci.yml)
+
+统一汉化 Pi 及其生态插件的界面文案。**默认不启用**，通过 `/pi-zh on` 优雅开启，`/pi-zh off` 一键还原。零侵入：不改动任何上游 API 行为，仅做**可逆幂等补丁**与 Telegram API 同步。
+
+## 安装
+
+```bash
+# 方式一：npm 包（推荐）
+pi install npm:@wingsbutterfly/pi-zh
+
+# 方式二：GitHub 仓库
+pi install git:github.com/wings1848/pi-zh@v0.3.0
+```
+
+安装后重启 pi，执行 `/pi-zh on` 启用汉化。
+
+## 使用
+
+```text
+/pi-zh          # 查看状态
+/pi-zh on       # 启用汉化（立即打补丁 + 安装 i18n SDK + 同步 Telegram 命令）
+/pi-zh off      # 关闭并还原全部文件到英文
+```
+
+配置文件：`~/.pi/agent/pi-zh.json`（`{ "enabled": true, "targets": [...] }`，缺省 = 全部已安装）
+
+## 覆盖范围（存在才处理，缺省自动跳过）
+
+| target | 内容 | 方式 |
+| --- | --- | --- |
+| `pi` | 内置 slash 命令补全（23 条）、/hotkeys 面板（3 节 + 30+ 动作）、/session 面板（15+ 字段）、/settings 面板（35 设置项 + thinking 级别） | 补丁 `dist/.../slash-commands.js` + bundle chunk |
+| `telegram` | /start 菜单卡片、状态卡、子菜单标题 | 补丁 `@llblab/pi-telegram/lib/*.ts` |
+| `cache-optimizer` | `/cache-optimizer` 命令与提示 | 补丁 `pi-cache-optimizer/index.ts` |
+| i18n SDK | rpiv-todo / rpiv-ask-user-question 等自带 `locales/zh.json` | 自动安装 `@juicesharp/rpiv-i18n`，`/languages` 切换 |
+
+> 工具 schema（如 codegraph / mcp-adapter 的 description）**不汉化**——那是给 AI 看的功能说明，汉化反而降低准确率。
+
+## 架构
+
+```
+~/.pi/agent/pi-zh/
+├── package.json
+├── extensions/index.ts            # 入口：开关编排 + /pi-zh 命令
+├── lib/
+│   ├── config.ts                  # 开关配置（默认关）
+│   ├── dict.ts                    # ★ 词典总表（唯一数据源，按 target 分组）
+│   ├── patch.ts                   # 双向补丁引擎（patch/restore 幂等可逆）
+│   ├── targets.ts                 # 插件探测（存在才处理）
+│   ├── sdk.ts                     # rpiv-i18n SDK 管理
+│   └── telegram-commands.ts       # Telegram 命令同步（30s 防回滚）
+└── scripts/zh-dict.mjs            # outbound 词典脚本（telegram.json 引用）
+```
+
+## 设计要点
+
+- **默认不启用**：无配置文件或 `enabled !== true` 一律关闭，启动零开销
+- **可逆还原**：restore 按词典反向替换（zh→en），与 patch 共用同一数据源，无备份文件依赖
+- **安全降级**：任一 target 探测/补丁失败不影响其他 target 与 pi 本身；匹配不到原文时静默跳过
+- **更新安全**：pi/插件更新覆盖补丁后，下次启动或 `/pi-zh on` 自动重打；SDK 缺失时插件回退英文，**不产生异常**
+- **新增汉化**：编辑 `lib/dict.ts` 加一行 `{ en, zh, targetFiles?, note? }`；新增插件则加一个 target 定义（`targets.ts`）并挂上词典
+
+## 与 pi-di18n 共存（自动分工，无冲突）
+
+每个字符串只有一个 owner：
+
+| pi-di18n 状态 | pi 本体负责 | pi-zh 负责 |
+| --- | --- | --- |
+| 激活（locale 非 en，含 LANG=zh_CN 自动触发） | pi-di18n（运行时 300+ 条） | telegram / cache-optimizer |
+| 未激活 | pi-zh（磁盘补丁） | telegram / cache-optimizer |
+
+- 判定依据：pi-di18n 配置 locale / 环境变量（LANG、PI_LOCALE）是否非 en，且 `coreHacksEnabled !== false`
+- 让位原因：pi-di18n 的 slash 命令翻译以运行时数组的 "original" 为基准，若 pi-zh 先磁盘补丁成中文会造成基准错位与措辞覆盖（重复汉化）→ 让位根治
+- 已安装 pi-di18n 但未激活时，pi-zh 仍全量接管；`/pi-zh status` 会显示当前 owner
+
+## 新增 target 步骤
+
+1. `lib/targets.ts` 加探测定义（包根候选 + marker + probeFiles）
+2. `lib/dict.ts` 加 `TARGET_DICTS[名称] = [...]`
+3. `lib/patch.ts` 无需改动（通用）
+4. `extensions/index.ts` 如有默认文件路径需求，加 `defaults` 映射
+
+## 验证
+
+```bash
+# 启用后重启 pi 的日志：
+[pi-zh] patched pi:dist/core/slash-commands.js (23)
+[pi-zh] patched telegram:lib/commands.ts (6)
+[pi-zh] telegram commands synced (1/1)
+```
+
+## 开发
+
+```bash
+bun install          # 安装依赖
+bun run typecheck    # 类型检查
+bun test             # 单元测试（bun:test）
+```
+
+新增汉化/新 target 指南见 [CONTRIBUTING.md](CONTRIBUTING.md)，版本历史见 [CHANGELOG.md](CHANGELOG.md)。
+
+## License
+
+[MIT](LICENSE) © 2026 wings1848

package/extensions/index.ts

@@ -0,0 +1,195 @@
+/**
+ * pi-zh — Pi 汉化插件（统一入口 v0.3）
+ *
+ * 功能（按配置开关，默认关闭）：
+ * 1. Pi 内置 slash 命令补全 + TUI 文案汉化（target: pi）
+ * 2. pi-telegram 菜单卡片/状态卡汉化（target: telegram）
+ * 3. pi-cache-optimizer 命令与提示汉化（target: cache-optimizer）
+ * 4. rpiv-i18n SDK 激活（内置 locales 插件的中文支持，如 rpiv-todo）
+ * 5. Telegram bot 命令菜单中文同步（30s 防回滚轮询）
+ *
+ * 架构：
+ * - lib/config.ts   开关配置（~/.pi/agent/pi-zh.json，默认关）
+ * - lib/dict.ts     词典总表（唯一数据源，按 target 分组）
+ * - lib/targets.ts  插件探测（存在才处理）
+ * - lib/patch.ts    双向补丁引擎（patch/restore 幂等可逆）
+ * - lib/sdk.ts      rpiv-i18n SDK 管理
+ *
+ * 启用/关闭：TUI 中执行 /pi-zh on | off | status
+ * 安全：任何 target 探测失败/补丁失败都不影响其他 target 与 pi 本身。
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { getPiTargetOwner, isPiDi18nActive } from "../lib/coexist.ts";
+import { disableConfig, enableConfig, readConfig, getConfigPath } from "../lib/config.ts";
+import { TARGET_DICTS } from "../lib/dict.ts";
+import { applyTargets, type PatchTarget } from "../lib/patch.ts";
+import { ensureI18nSdk, isI18nSdkInstalled } from "../lib/sdk.ts";
+import { getInstalledTargets, getTargetByName, resolveTargetRoot, type TargetDefinition } from "../lib/targets.ts";
+import { ensureZhCommands, readBotTokens, syncAllTokens } from "../lib/telegram-commands.ts";
+
+// ---------------------------------------------------------------------------
+// 补丁编排
+// ---------------------------------------------------------------------------
+
+/** 生成某 target 的补丁目标文件列表（按词典 targetFiles 集合 + 包根） */
+function buildTargetFiles(target: TargetDefinition): PatchTarget[] {
+  const root = resolveTargetRoot(target);
+  if (!root) return [];
+  const entries = TARGET_DICTS[target.name] ?? [];
+  const files = new Set<string>();
+  for (const entry of entries) {
+    for (const file of entry.targetFiles ?? []) {
+      files.add(file);
+    }
+  }
+  // 无 targetFiles 限定的条目（如 pi 的 slash-commands 需特殊处理）在 files 为空时补默认文件
+  const defaults: Record<string, string[]> = {
+    pi: [
+      "dist/core/slash-commands.js",
+      "dist/bundle/chunks/chunk-OMWWHBTG.js",
+    ],
+    telegram: ["lib/commands.ts", "lib/status.ts", "lib/menu-status.ts", "lib/menu-model.ts", "lib/menu-thinking.ts", "lib/menu-queue.ts", "lib/menu-settings.ts"],
+    "cache-optimizer": ["index.ts"],
+  };
+  const targetFiles = files.size > 0 ? files : new Set(defaults[target.name] ?? []);
+  return [...targetFiles].map((f) => ({
+    filePath: join(root, f),
+    label: `${target.name}:${f}`,
+  }));
+}
+
+/** 对某 target 执行 patch 或 restore，返回修改数 */
+function applyTarget(
+  target: TargetDefinition,
+  mode: "patch" | "restore",
+): { changed: boolean; reports: Array<{ label: string; applied: number }> } {
+  const entries = TARGET_DICTS[target.name] ?? [];
+  const files = buildTargetFiles(target);
+  return applyTargets(files, entries, mode);
+}
+
+/** 对全部已安装 target 执行操作（on=patch，off=restore），自动协调 pi-di18n 分工 */
+function applyAll(mode: "patch" | "restore"): Array<{ target: string; applied: number }> {
+  const results: Array<{ target: string; applied: number }> = [];
+  const piOwner = getPiTargetOwner();
+  for (const target of getInstalledTargets()) {
+    // 协调：pi-di18n 激活时，pi target 让它负责（避免 slash 命令双 owner、基准错位）
+    if (target.name === "pi" && piOwner === "pi-di18n" && mode === "patch") {
+      console.log("[pi-zh] pi target delegated to pi-di18n (active), skipping");
+      results.push({ target: target.name, applied: 0 });
+      continue;
+    }
+    // restore 时仍需处理 pi：若之前 pi-zh 打过补丁，还原之（幂等：未打过则无操作）
+    const outcome = applyTarget(target, mode);
+    const applied = outcome.reports.reduce((sum, r) => sum + r.applied, 0);
+    for (const report of outcome.reports) {
+      console.log(`[pi-zh] ${mode === "patch" ? "patched" : "restored"} ${report.label} (${report.applied})`);
+    }
+    results.push({ target: target.name, applied });
+  }
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// 开关动作（供 /pi-zh 命令与启动逻辑共用）
+// ---------------------------------------------------------------------------
+
+/** 启用：写配置 + 立即打补丁 + 确保 i18n SDK + 同步 Telegram 命令 */
+async function turnOn(targetList?: string[]): Promise<string> {
+  enableConfig(targetList);
+  const results = applyAll("patch");
+  const sdkOk = ensureI18nSdk();
+  const counts = results.map((r) => `${r.target}:${r.applied}`).join(" ");
+  return `✅ pi-zh 已启用${targetList ? `（${targetList.join(", ")}）` : ""}（${counts}）${sdkOk ? "，i18n SDK 就绪" : "，i18n SDK 安装失败"}`;
+}
+
+/** 关闭：还原所有已汉化文件 + 写配置 */
+function turnOff(): string {
+  const results = applyAll("restore");
+  disableConfig();
+  const counts = results.map((r) => `${r.target}:${r.applied}`).join(" ");
+  return `✅ pi-zh 已关闭，已还原（${counts}）`;
+}
+
+/** 状态：显示配置、已安装 target、SDK 状态、pi-di18n 分工 */
+function status(): string {
+  const config = readConfig();
+  const installed = getInstalledTargets().map((t) => t.name).join(", ") || "无";
+  const enabledTargets = config.targets?.join(", ") ?? "全部";
+  const piOwner = getPiTargetOwner();
+  return [
+    `📋 pi-zh 状态：${config.enabled ? "启用中" : "已关闭（默认）"}`,
+    `   配置：${getConfigPath()}`,
+    `   已安装 target：${installed}`,
+    `   启用范围：${enabledTargets}`,
+    `   pi 本体负责：${piOwner === "pi-di18n" ? "pi-di18n（已激活，避免重复）" : "pi-zh"}`,
+    `   i18n SDK：${isI18nSdkInstalled() ? "已安装" : "未安装"}`,
+    `   用法：/pi-zh on | off | status`,
+  ].join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// 扩展入口
+// ---------------------------------------------------------------------------
+
+const POLL_INTERVAL_MS = 30_000;
+const TG_TOKENS = readBotTokens();
+
+export default async function (pi: ExtensionAPI) {
+  // ---- 启动时按配置执行（默认关）----
+  const config = readConfig();
+  if (config.enabled) {
+    applyAll("patch");
+    if (["pi", "telegram", "cache-optimizer"].every((t) => config.targets?.includes(t) || !config.targets)) {
+      ensureI18nSdk();
+    }
+    if (TG_TOKENS.length > 0) {
+      const ok = await syncAllTokens();
+      console.log(`[pi-zh] telegram commands synced (${ok}/${TG_TOKENS.length})`);
+    }
+  } else {
+    console.log("[pi-zh] disabled (default) — enable with /pi-zh on");
+  }
+
+  // ---- /pi-zh 命令：优雅开关 ----
+  pi.registerCommand("pi-zh", {
+    description: "管理 pi-zh 汉化（on/off/status）",
+    handler: async (args, ctx) => {
+      const cmd = (args ?? "").trim().toLowerCase();
+      let message: string;
+      if (cmd === "on") {
+        message = await turnOn();
+      } else if (cmd === "off") {
+        message = turnOff();
+      } else if (cmd === "status" || cmd === "") {
+        message = status();
+      } else {
+        message = `用法：/pi-zh on | off | status`;
+      }
+      await ctx.ui.notify(message, "info");
+    },
+  });
+
+  // ---- Telegram 命令防回滚轮询（无论开关，若此前启用了命令菜单中文，保底修复）----
+  // 仅在已启用时轮询，避免无谓 API 调用
+  if (config.enabled && TG_TOKENS.length > 0) {
+    let pollTimer: NodeJS.Timeout | undefined;
+    pi.on("session_start", async () => {
+      if (pollTimer) return;
+      pollTimer = setInterval(() => {
+        for (const token of TG_TOKENS) {
+          ensureZhCommands(token).catch(() => {});
+        }
+      }, POLL_INTERVAL_MS);
+    });
+    pi.on("session_shutdown", () => {
+      if (pollTimer) {
+        clearInterval(pollTimer);
+        pollTimer = undefined;
+      }
+    });
+  }
+}

package/lib/coexist.ts

@@ -0,0 +1,86 @@
+/**
+ * pi-zh 与 pi-di18n 的协调层
+ *
+ * 分工原则（每个字符串只有一个 owner，避免冲突/重复汉化）：
+ * - pi-di18n 激活（locale 非 en）→ pi 本体 runtime 文案（slash 命令描述、TUI 面板、
+ *   通知/错误提示等 300+ 条）归 pi-di18n；pi-zh 自动让位 pi target，只保留
+ *   telegram / cache-optimizer（pi-di18n 不覆盖的生态）。
+ * - pi-di18n 未激活 → pi-zh 全管线接管（含 pi target）。
+ *
+ * 为什么让位：
+ * pi-di18n 的 patchCoreBuiltinSlashCommandDescriptions 会 import dist 的
+ * BUILTIN_SLASH_COMMANDS 数组并记录 "original" 作为翻译基准。若 pi-zh
+ * 先磁盘补丁成中文，pi-di18n 会把中文误当基准（基准错位），再按它的
+ * bundle 覆盖（措辞/繁简差异 = 重复汉化）。让位即可根治。
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** pi-di18n 包是否已安装（在 pi 扩展包目录） */
+function isPiDi18nInstalled(): boolean {
+  const pkg = join(
+    homedir(),
+    ".pi/agent/npm/node_modules/pi-di18n/package.json",
+  );
+  return existsSync(pkg);
+}
+
+/** pi-di18n 的状态目录（与它源码 config.ts 保持一致） */
+function getPiDi18nConfigPath(): string {
+  return join(homedir(), ".pi/agent/state/pi-di18n/config.json");
+}
+
+/** 读 pi-di18n 配置文件中的 locale（仿照其 loadI18nConfig 优先级） */
+function readPiDi18nLocale(): string | undefined {
+  try {
+    const path = getPiDi18nConfigPath();
+    if (!existsSync(path)) return undefined;
+    const cfg = JSON.parse(readFileSync(path, "utf8")) as {
+      locale?: string;
+      fallbackLocale?: string;
+      coreHacksEnabled?: boolean;
+    };
+    // coreHacks 被显式禁用 → pi-di18n 不碰内核 → pi-zh 可接管
+    if (cfg.coreHacksEnabled === false) return undefined;
+    return cfg.locale ?? cfg.fallbackLocale;
+  } catch {
+    return undefined;
+  }
+}
+
+/** pi-di18n 运行时 locale（模拟它的 detectLocaleFromEnv） */
+export function readPiDi18nEnvLocale(): string | undefined {
+  const candidates = [
+    process.env.PI_LOCALE,
+    process.env.LC_ALL,
+    process.env.LANG,
+  ].filter(Boolean) as string[];
+  for (const raw of candidates) {
+    const s = raw.trim();
+    if (!s) continue;
+    const base = (s.split(".")[0] ?? s).replace(/_/g, "-");
+    if (base) return base;
+  }
+  return undefined;
+}
+
+/** locale 是否为英文/中性环境（en、en-US、C、POSIX 等 → 未激活） */
+export function isEnglishLocale(locale: string | undefined): boolean {
+  if (!locale || locale.trim() === "") return true;
+  const lang = locale.toLowerCase().split("-")[0]!;
+  return lang === "en" || lang === "c" || lang === "posix";
+}
+
+/** pi-di18n 是否激活（已安装 + locale 非 en + coreHacks 未禁用） */
+export function isPiDi18nActive(): boolean {
+  if (!isPiDi18nInstalled()) return false;
+  const locale = readPiDi18nLocale() ?? readPiDi18nEnvLocale();
+  return !isEnglishLocale(locale);
+}
+
+/** 协调结果：当前 pi target 由谁负责 */
+export function getPiTargetOwner(): "pi-zh" | "pi-di18n" {
+  return isPiDi18nActive() ? "pi-di18n" : "pi-zh";
+}

package/lib/config.ts

@@ -0,0 +1,71 @@
+/**
+ * pi-zh 开关配置模块
+ *
+ * 配置文件：~/.pi/agent/pi-zh.json
+ * 默认不启用（文件缺失或 enabled !== true 均视为关闭）。
+ *
+ * 格式：
+ * {
+ *   "enabled": true,
+ *   "targets": ["pi", "telegram"]  // 可选，缺省为全部可用 target
+ * }
+ *
+ * 优雅启用：在 TUI 中执行 /pi-zh on（写入配置并立即生效），
+ * 关闭执行 /pi-zh off（还原所有已汉化文件）。
+ */
+
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export interface PiZhConfig {
+  /** 是否启用汉化（默认 false） */
+  enabled: boolean;
+  /** 启用的 target 列表（缺省 = 全部可用） */
+  targets?: string[];
+}
+
+const CONFIG_PATH = join(homedir(), ".pi/agent/pi-zh.json");
+
+/** 读取配置；文件不存在或无效返回默认关闭配置 */
+export function readConfig(path: string = CONFIG_PATH): PiZhConfig {
+  try {
+    if (!existsSync(path)) return { enabled: false };
+    const raw = JSON.parse(readFileSync(path, "utf8")) as Partial<PiZhConfig>;
+    return {
+      enabled: raw.enabled === true,
+      ...(Array.isArray(raw.targets) ? { targets: raw.targets } : {}),
+    };
+  } catch {
+    return { enabled: false };
+  }
+}
+
+/** 写入配置（原子写：先写临时文件再 rename） */
+export function writeConfig(config: PiZhConfig, path: string = CONFIG_PATH): void {
+  const parent = dirname(path);
+  if (!existsSync(parent)) return;
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, JSON.stringify(config, null, 2) + "\n", "utf8");
+  // 同步替换避免读到半截文件
+  renameSync(tmp, path);
+}
+
+/** 简易启用：写入 enabled 配置 */
+export function enableConfig(targets?: string[], path: string = CONFIG_PATH): PiZhConfig {
+  const config: PiZhConfig = { enabled: true, ...(targets ? { targets } : {}) };
+  writeConfig(config, path);
+  return config;
+}
+
+/** 简易关闭：写入 enabled:false（并清空 targets 以便下次重新探测） */
+export function disableConfig(path: string = CONFIG_PATH): PiZhConfig {
+  const config: PiZhConfig = { enabled: false };
+  writeConfig(config, path);
+  return config;
+}
+
+/** 配置路径（供状态显示/调试） */
+export function getConfigPath(): string {
+  return CONFIG_PATH;
+}