@buyi1net/pi-toolkit 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 buyi1net
+
+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,45 @@
+# pi-toolkit
+
+pi-toolkit 把日常编码中会用到的工具聚合进一个 Pi 扩展包，当前包含视觉辅助、子代理编排和供应商状态与外观三个模块，后续会继续加入 MCP 连接器等新能力。所有配置通过一个控制菜单完成，菜单的观感和操作方式与 Pi 原生 `/settings` 完全一致，支持英语、简体中文、繁体中文。
+
+## 安装
+
+```bash
+pi install npm:@buyi1net/pi-toolkit
+```
+
+或从 GitHub 安装：
+
+```bash
+pi install git:github.com/buyi1net/pi-toolkit
+```
+
+安装后在 Pi TUI 输入 `/pi-toolkit` 打开控制菜单。
+
+## 模块
+
+三个模块都可以在菜单顶层独立开关，关闭的模块不注册任何工具和钩子。
+
+**视觉辅助（来自 pi-eyes）**：为纯文本模型自动补充图片理解能力，原生多模态模型直接旁路。主模型可通过 `vision_query` 工具针对最近截图追问。切换视觉模型前会先跑一次探测自检，不通过则保持原选择。
+
+**子代理编排（来自 pi-subagents）**：spawn、调度、回收子代理。自动任务默认 headless 后台进程，演示型任务用 herdr 或 tmux 分屏，结果自动回注主会话。支持 tier 模型路由（fast / balanced / deep）与团队协作。`ask_question` 让子代理在卡住时向主会话提问。
+
+**供应商状态与外观（来自 pi-tui）**：编辑器状态边框、Header、项目状态 Footer、启动与 reload 转场、单轮遥测，附带 16 个主题。供应商余额与套餐查询需要凭据时读取 `~/.pi/agent/pi-tui.json`（该文件由你手工维护，插件只读）。
+
+## 配置
+
+菜单改动写入 `~/.pi/agent/pi-toolkit.json`。子代理的 tier 路由也可被环境变量 `PI_SUBAGENTS_CONFIG`、项目或全局的 `pi-subagents.json` 覆盖，优先级与 pi-subagents 一致。
+
+视觉辅助的图像预处理依赖 sharp，属于可选依赖：只在视觉模块启用且首次处理图片时加载；缺失时会提示安装命令，不影响其它模块。
+
+## 隐私与边界
+
+视觉图片只发送给你配置的 Pi 视觉模型 provider。凭据文件 `pi-tui.json` 永远不被本插件写入。子代理进程与你共享同一台机器的权限，请只派发可信任务。
+
+## 致谢
+
+子代理编排模块源自 [amosblomqvist/pi-interactive-subagents](https://github.com/amosblomqvist/pi-interactive-subagents)（MIT），在原实现基础上完成了 herdr 表面适配与进程内裁剪。
+
+## 开源协议
+
+pi-toolkit 的自有代码以 MIT License 发布。

package/assembler.ts

@@ -0,0 +1,127 @@
+// 装配器：把模块定义按配置落成实际注册。
+// 关键约束：enabled=false 的模块在这里被完全跳过，register 与 menuItems 都不会被触碰。
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ToolkitConfig } from "./config.ts";
+import type { Translator } from "./i18n.ts";
+import {
+  assertModuleDefinition,
+  ENABLED_FIELD,
+  normalizeConfigValue,
+  type ModuleConfigRecord,
+  type ModuleConfigScalar,
+  type ModuleContext,
+  type ModuleDefinition,
+} from "./module.ts";
+import type { ServiceRegistry } from "./services.ts";
+
+/** 通过校验并成功注册的模块 */
+export interface ActiveModule {
+  readonly definition: ModuleDefinition;
+}
+
+export interface ModuleFailure {
+  readonly definition: ModuleDefinition;
+  readonly error: unknown;
+}
+
+export interface ModuleContextOptions {
+  readonly pi: ExtensionAPI;
+  readonly services: ServiceRegistry;
+  readonly t: Translator;
+  readonly getModuleConfig: (moduleId: string) => ModuleConfigRecord;
+  readonly reloadConfig: () => Promise<void>;
+  readonly setModuleConfig: (moduleId: string, key: string, value: ModuleConfigScalar) => Promise<ModuleConfigScalar>;
+}
+
+export interface AssembleOptions extends ModuleContextOptions {
+  readonly modules: readonly ModuleDefinition[];
+  readonly config: ToolkitConfig;
+}
+
+export interface AssemblyResult {
+  readonly loaded: readonly ActiveModule[];
+  readonly failures: readonly ModuleFailure[];
+}
+
+export function moduleDefaults(definition: ModuleDefinition): ModuleConfigRecord {
+  const defaults: ModuleConfigRecord = {};
+  for (const [key, field] of Object.entries(definition.configSchema)) {
+    defaults[key] = field.default;
+  }
+  return defaults;
+}
+
+/**
+ * schema 默认值 + 磁盘取值。
+ * schema 声明的键做规范化（非法值丢弃并用默认值兜底）；schema 之外的键原样透传，
+ * 供模块读取自己的结构化配置（如视觉路由），菜单不渲染这些键。
+ */
+export function resolveModuleConfig(
+  definition: ModuleDefinition,
+  stored: ModuleConfigRecord | undefined,
+): ModuleConfigRecord {
+  const resolved = moduleDefaults(definition);
+  if (!stored) return resolved;
+  for (const [key, value] of Object.entries(stored)) {
+    const field = definition.configSchema[key];
+    if (!field) {
+      resolved[key] = value;
+      continue;
+    }
+    const normalized = normalizeConfigValue(field, value);
+    if (normalized !== undefined) resolved[key] = normalized;
+  }
+  return resolved;
+}
+
+export function isModuleEnabled(config: ModuleConfigRecord): boolean {
+  return config[ENABLED_FIELD] !== false;
+}
+
+/** 模块菜单项 id：`<moduleId>.<field>`，模块自定义行自行避让该前缀 */
+export function moduleFieldId(moduleId: string, field: string): string {
+  return `${moduleId}.${field}`;
+}
+
+function createModuleContext(
+  definition: ModuleDefinition,
+  options: ModuleContextOptions,
+): ModuleContext {
+  return {
+    moduleId: definition.id,
+    pi: options.pi,
+    services: options.services,
+    t: options.t,
+    getConfig: () => options.getModuleConfig(definition.id),
+    reloadConfig: () => options.reloadConfig(),
+    setConfig: (key, value) => options.setModuleConfig(definition.id, key, value),
+  };
+}
+
+export function assembleModules(options: AssembleOptions): AssemblyResult {
+  const loaded: ActiveModule[] = [];
+  const failures: ModuleFailure[] = [];
+  const seen = new Set<string>();
+
+  for (const definition of options.modules) {
+    assertModuleDefinition(definition);
+    if (seen.has(definition.id)) {
+      throw new Error(`模块 id 重复：${definition.id}`);
+    }
+    seen.add(definition.id);
+
+    const config = resolveModuleConfig(definition, options.config.modules[definition.id]);
+    if (!isModuleEnabled(config)) continue;
+
+    try {
+      definition.register(createModuleContext(definition, options));
+    } catch (error) {
+      failures.push({ definition, error });
+      continue;
+    }
+    loaded.push({ definition });
+  }
+
+  return { loaded, failures };
+}

package/config.ts

@@ -0,0 +1,201 @@
+// pi-toolkit 统一配置文件：<agentDir>/pi-toolkit.json
+// 结构：schemaVersion + language + 各模块配置节。
+// 写盘沿用 pi-eyes 的安全行为：剥掉敏感键、0600 权限、临时文件 + rename 原子替换。
+
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { isLanguageSetting, type LanguageSetting } from "./i18n.ts";
+import type { ModuleConfigRecord, ModuleConfigValue } from "./module.ts";
+
+export const TOOLKIT_CONFIG_FILENAME = "pi-toolkit.json";
+export const TOOLKIT_SCHEMA_VERSION = 1;
+
+export interface ToolkitConfig {
+  readonly schemaVersion: number;
+  readonly language: LanguageSetting;
+  /** 模块 id → 该模块的配置节（未经 schema 校验的原始值） */
+  readonly modules: Readonly<Record<string, ModuleConfigRecord>>;
+}
+
+export interface ToolkitConfigUpdate {
+  readonly language?: LanguageSetting;
+  readonly modules?: Readonly<Record<string, ModuleConfigRecord>>;
+}
+
+export interface LoadedToolkitConfig {
+  readonly config: ToolkitConfig;
+  /** 文件缺失不算问题；解析异常、取值非法逐条记录，交给菜单展示 */
+  readonly problems: readonly string[];
+}
+
+export const DEFAULT_TOOLKIT_CONFIG: ToolkitConfig = {
+  schemaVersion: TOOLKIT_SCHEMA_VERSION,
+  language: "auto",
+  modules: {},
+};
+
+export function getToolkitConfigPath(agentDir: string): string {
+  return join(agentDir, TOOLKIT_CONFIG_FILENAME);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** 配置节可存的值：标量、标量数组，或嵌套的对象/数组（模块私有结构） */
+function isConfigValue(value: unknown): value is ModuleConfigValue {
+  if (value === null) return true;
+  const type = typeof value;
+  if (type === "string" || type === "number" || type === "boolean") return true;
+  if (Array.isArray(value)) return value.every(isConfigValue);
+  if (isRecord(value)) return Object.values(value).every(isConfigValue);
+  return false;
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export function parseToolkitConfig(raw: Record<string, unknown>, source: string, problems: string[]): ToolkitConfig {
+  const version = typeof raw.schemaVersion === "number" ? raw.schemaVersion : TOOLKIT_SCHEMA_VERSION;
+  if (version > TOOLKIT_SCHEMA_VERSION) {
+    problems.push(`${source}: schemaVersion ${version} 高于当前支持的 ${TOOLKIT_SCHEMA_VERSION}，未识别的内容会原样保留`);
+  }
+
+  let language: LanguageSetting = "auto";
+  if (raw.language !== undefined) {
+    if (isLanguageSetting(raw.language)) {
+      language = raw.language;
+    } else {
+      problems.push(`${source}: language 取值无效，已回退为 auto`);
+    }
+  }
+
+  const modules: Record<string, ModuleConfigRecord> = {};
+  if (raw.modules !== undefined && !isRecord(raw.modules)) {
+    problems.push(`${source}: modules 不是对象，已忽略`);
+  } else if (isRecord(raw.modules)) {
+    for (const [moduleId, section] of Object.entries(raw.modules)) {
+      if (!isRecord(section)) {
+        problems.push(`${source}: 模块 ${moduleId} 的配置节不是对象，已忽略`);
+        continue;
+      }
+      const record: ModuleConfigRecord = {};
+      for (const [key, value] of Object.entries(section)) {
+        if (isConfigValue(value)) {
+          record[key] = value;
+        } else {
+          problems.push(`${source}: 模块 ${moduleId} 的字段 ${key} 取值类型不受支持，已忽略`);
+        }
+      }
+      modules[moduleId] = record;
+    }
+  }
+
+  return { schemaVersion: TOOLKIT_SCHEMA_VERSION, language, modules };
+}
+
+export async function loadToolkitConfig(path: string): Promise<LoadedToolkitConfig> {
+  const problems: string[] = [];
+  let text: string;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      problems.push(`${path}: 读取失败（${describeError(error)}），本次使用默认配置`);
+    }
+    return { config: DEFAULT_TOOLKIT_CONFIG, problems };
+  }
+
+  try {
+    const parsed: unknown = JSON.parse(text);
+    if (!isRecord(parsed)) {
+      problems.push(`${path}: 顶层不是对象，本次使用默认配置`);
+      return { config: DEFAULT_TOOLKIT_CONFIG, problems };
+    }
+    return { config: parseToolkitConfig(parsed, path, problems), problems };
+  } catch (error) {
+    problems.push(`${path}: 解析失败（${describeError(error)}），本次使用默认配置`);
+    return { config: DEFAULT_TOOLKIT_CONFIG, problems };
+  }
+}
+
+function sensitiveKey(key: string): boolean {
+  const normalized = key.toLowerCase().replace(/[^a-z0-9]/g, "");
+  return (
+    normalized === "auth" ||
+    normalized === "authorization" ||
+    normalized === "headers" ||
+    normalized.includes("apikey") ||
+    normalized.includes("token") ||
+    normalized.includes("secret") ||
+    normalized.includes("password") ||
+    normalized.includes("credential")
+  );
+}
+
+function sanitizeForWrite(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sanitizeForWrite);
+  if (!isRecord(value)) return value;
+  const result: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (!sensitiveKey(key) && entry !== undefined) result[key] = sanitizeForWrite(entry);
+  }
+  return result;
+}
+
+function mergeRaw(base: Record<string, unknown>, update: Record<string, unknown>): Record<string, unknown> {
+  const result = { ...base };
+  for (const [key, value] of Object.entries(update)) {
+    if (value === undefined) continue;
+    const current = result[key];
+    result[key] = isRecord(current) && isRecord(value) ? mergeRaw(current, value) : value;
+  }
+  return result;
+}
+
+async function atomicWrite(path: string, text: string): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  const temp = join(dirname(path), `.${basename(path)}.${process.pid}-${randomUUID()}.tmp`);
+  try {
+    await writeFile(temp, text, { encoding: "utf8", mode: 0o600 });
+    await rename(temp, path);
+  } finally {
+    await rm(temp, { force: true });
+  }
+}
+
+async function readRaw(path: string): Promise<Record<string, unknown> | undefined> {
+  try {
+    const parsed: unknown = JSON.parse(await readFile(path, "utf8"));
+    return isRecord(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function toRawUpdate(update: ToolkitConfigUpdate): Record<string, unknown> {
+  return {
+    ...(update.language !== undefined ? { language: update.language } : {}),
+    ...(update.modules !== undefined ? { modules: update.modules } : {}),
+  };
+}
+
+/**
+ * 合并写入：保留磁盘上未识别的键（合并进现有内容），剥掉敏感键后原子替换。
+ * 覆盖前把上一版内容留一份 `<path>.bak`。
+ */
+export async function saveToolkitConfig(path: string, update: ToolkitConfigUpdate): Promise<ToolkitConfig> {
+  const existing = await readRaw(path);
+  const cleanExisting = existing ? (sanitizeForWrite(existing) as Record<string, unknown>) : {};
+  const merged = mergeRaw(cleanExisting, toRawUpdate(update));
+  merged.schemaVersion = TOOLKIT_SCHEMA_VERSION;
+
+  const config = parseToolkitConfig(merged, path, []);
+  if (existing) {
+    await atomicWrite(`${path}.bak`, `${JSON.stringify(cleanExisting, null, 2)}\n`);
+  }
+  await atomicWrite(path, `${JSON.stringify(merged, null, 2)}\n`);
+  return config;
+}