ai-agent-helper 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.1
+
+- 定义 `~/.ai-agent-helper/config.toml` 的配置数据模型：`version`、`proxy`、`no_proxy`。
+- 导出配置相关 Zod schemas 和 TypeScript 类型。
+- 增加配置设计文档、带注释的 TOML 示例及模型校验测试。
+- npm 包包含配置设计文档和示例。
+
+本版本只增加配置模型，尚未实现配置文件读写、`config` / `install` 命令或代理安装。
+
+## 0.1.0
+
+- 检测 PATH 中的六种 AI agent CLI，每种 agent 使用独立检测模块。
+- 提供 `list`、`--all`、`--json`、帮助和版本信息。

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# ai-agent-helper
 
-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.
+使用 TypeScript 和 Zod 开发的 AI agent CLI 管理工具。首版 `0.1.0` 仅实现列出本机 PATH 中可找到的 agent，不安装、更新或启动 agent。
+
+需要 Node.js **22.13 或更高版本**。
+
+## 安装与使用
+
+```sh
+npm install -g ai-agent-helper --registry=https://registry.npmjs.org/
+agent-helper --help
+agent-helper list
+```
+
+## 从源码运行
+
+```sh
+npm install
+npm run build
+node dist/cli.js --help
+node dist/cli.js list
+```
+
+需要使用本地源码提供的 `agent-helper` 命令时，可在构建后于项目目录执行 `npm link`。
+
+## 命令
+
+```sh
+agent-helper --help
+agent-helper -h
+agent-helper --version
+agent-helper list
+agent-helper list --help
+agent-helper list --all
+agent-helper list --json
+agent-helper list --all --json
+```
+
+- 无参数时显示帮助。
+- `list` 默认只列出检测到的 agent，输出名称、命令、状态和路径。
+- `--all` / `-a` 同时列出未检测到的 agent。
+- `--json` 输出纯 JSON 数组；没有检测到时返回 `[]`。
+- 正常查询（包括没有检测到）退出码为 `0`；无效参数或检测异常为 `1`，错误写入 stderr。
+
+JSON 示例：
+
+```json
+[
+  {
+    "id": "claude-code",
+    "name": "Claude Code",
+    "command": "claude",
+    "installed": true,
+    "path": "/usr/local/bin/claude"
+  }
+]
+```
+
+`--all` 中未检测到的条目使用 `installed: false` 和 `path: null`。
+
+## 首版检测范围
+
+| Agent | 命令 | 独立检测模块 |
+| --- | --- | --- |
+| Claude Code | `claude` | `src/agents/claude-code.ts` |
+| Codex | `codex` | `src/agents/codex.ts` |
+| Gemini CLI | `gemini` | `src/agents/gemini.ts` |
+| OpenCode | `opencode` | `src/agents/opencode.ts` |
+| Aider | `aider` | `src/agents/aider.ts` |
+| GitHub Copilot | `copilot` | `src/agents/github-copilot.ts` |
+
+按当前进程的 PATH 顺序查找，只返回首个匹配的可执行入口。Windows 使用 PATHEXT（未设置时使用 `.COM;.EXE;.BAT;.CMD`），支持 npm 的 `.cmd` 入口、大小写不敏感的环境变量名称和带引号的 PATH 目录。macOS/Linux 要求文件有执行权限，支持符号链接。
+
+`installed` 表示找到了对应名称的可执行文件，不保证文件身份、运行正常、版本或登录状态。不会执行 `--version`、读取密钥、联网或加载 shell 配置。PATH 之外的安装、桌面应用、shell alias/function、旧版 `gh copilot` 扩展和未知 agent 不在首版检测范围内。空 PATH 项会跳过；显式的相对 PATH 项相对于当前工作目录解析。
+
+## TypeScript API
+
+```ts
+import { listAgents, agentListSchema, type AgentResult } from "ai-agent-helper";
+
+const installed: AgentResult[] = await listAgents();
+const all = await listAgents({ includeMissing: true });
+agentListSchema.parse(all);
+```
+
+包提供 ESM 导出和类型声明。Zod 校验 CLI 选项及检测结果，并约束已检测到条目必须包含路径、未检测到条目的路径必须为 `null`。
+
+## 配置功能设计
+
+配置采用 `~/.ai-agent-helper/config.toml`，以 TOML 保存注释和配置分组。当前已提供 `configSchema`、`configKeySchema`、`proxyUrlSchema` 及对应 TypeScript 类型；配置文件读写、`config` 命令和代理安装功能尚未实现。
+
+设计及命令约定见 [配置功能设计](docs/configuration.md)，带注释的文件示例见 [config.toml](examples/config.toml)。初版模型包含配置格式版本 `version`、默认安装代理 `proxy` 和绕过规则 `no_proxy`。
+
+## 开发与扩展
+
+```sh
+npm run dev -- list --all
+npm run check
+npm pack
+```
+
+每种 agent 在 `src/agents/` 中独立实现 `AgentProvider.detect()`，在 `src/agents/index.ts` 注册。当前共用 `src/detection/find-executable.ts` 的 PATH 查找能力；以后可在各自模块内添加专用安装路径或其他识别逻辑，不必修改 CLI。
+
+`src/list-agents.ts` 负责汇总和 Zod 校验，`src/cli.ts` 负责参数解析与展示。测试使用临时目录和伪可执行入口，不启动本机 agent；包含 CLI 帮助、错误参数、JSON、PATH 优先级、Windows PATHEXT、POSIX 执行权限等用例。平台专属用例只在对应平台执行。

package/dist/agents/aider.d.ts

@@ -0,0 +1,2 @@
+import type { AgentProvider } from "../detection/types.js";
+export declare const aider: AgentProvider;

package/dist/agents/aider.js

@@ -0,0 +1,7 @@
+import { findExecutable } from "../detection/find-executable.js";
+export const aider = {
+    definition: { id: "aider", name: "Aider", command: "aider" },
+    async detect(context) {
+        return findExecutable("aider", context);
+    },
+};

package/dist/agents/claude-code.d.ts

@@ -0,0 +1,2 @@
+import type { AgentProvider } from "../detection/types.js";
+export declare const claudeCode: AgentProvider;

package/dist/agents/claude-code.js

@@ -0,0 +1,7 @@
+import { findExecutable } from "../detection/find-executable.js";
+export const claudeCode = {
+    definition: { id: "claude-code", name: "Claude Code", command: "claude" },
+    async detect(context) {
+        return findExecutable("claude", context);
+    },
+};

package/dist/agents/codex.d.ts

@@ -0,0 +1,2 @@
+import type { AgentProvider } from "../detection/types.js";
+export declare const codex: AgentProvider;

package/dist/agents/codex.js

@@ -0,0 +1,7 @@
+import { findExecutable } from "../detection/find-executable.js";
+export const codex = {
+    definition: { id: "codex", name: "Codex", command: "codex" },
+    async detect(context) {
+        return findExecutable("codex", context);
+    },
+};

package/dist/agents/gemini.d.ts

@@ -0,0 +1,2 @@
+import type { AgentProvider } from "../detection/types.js";
+export declare const gemini: AgentProvider;

package/dist/agents/gemini.js

@@ -0,0 +1,7 @@
+import { findExecutable } from "../detection/find-executable.js";
+export const gemini = {
+    definition: { id: "gemini", name: "Gemini CLI", command: "gemini" },
+    async detect(context) {
+        return findExecutable("gemini", context);
+    },
+};

package/dist/agents/github-copilot.d.ts

@@ -0,0 +1,2 @@
+import type { AgentProvider } from "../detection/types.js";
+export declare const githubCopilot: AgentProvider;

package/dist/agents/github-copilot.js

@@ -0,0 +1,7 @@
+import { findExecutable } from "../detection/find-executable.js";
+export const githubCopilot = {
+    definition: { id: "github-copilot", name: "GitHub Copilot", command: "copilot" },
+    async detect(context) {
+        return findExecutable("copilot", context);
+    },
+};

package/dist/agents/index.d.ts

@@ -0,0 +1,2 @@
+import type { AgentProvider } from "../detection/types.js";
+export declare const builtInAgents: readonly AgentProvider[];

package/dist/agents/index.js

@@ -0,0 +1,7 @@
+import { aider } from "./aider.js";
+import { claudeCode } from "./claude-code.js";
+import { codex } from "./codex.js";
+import { gemini } from "./gemini.js";
+import { githubCopilot } from "./github-copilot.js";
+import { opencode } from "./opencode.js";
+export const builtInAgents = [claudeCode, codex, gemini, opencode, aider, githubCopilot];

package/dist/agents/opencode.d.ts

@@ -0,0 +1,2 @@
+import type { AgentProvider } from "../detection/types.js";
+export declare const opencode: AgentProvider;

package/dist/agents/opencode.js

@@ -0,0 +1,7 @@
+import { findExecutable } from "../detection/find-executable.js";
+export const opencode = {
+    definition: { id: "opencode", name: "OpenCode", command: "opencode" },
+    async detect(context) {
+        return findExecutable("opencode", context);
+    },
+};

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { z } from "zod";
+import { listAgents } from "./list-agents.js";
+const help = `agent-helper — 列出本地 AI agent CLI
+
+用法：
+  agent-helper list [--all] [--json]
+  agent-helper [--help | --version]
+
+命令：
+  list             列出 PATH 中检测到的 agent
+
+选项：
+  -a, --all        同时显示未检测到的 agent（仅用于 list）
+      --json       输出 JSON 数组（仅用于 list）
+  -h, --help       显示帮助，支持 list --help
+  -v, --version    显示 agent-helper 版本
+
+示例：
+  agent-helper list
+  agent-helper list --all
+  agent-helper list --json
+  agent-helper list --all --json
+
+检测范围：Claude Code、Codex、Gemini CLI、OpenCode、Aider、GitHub Copilot。
+仅查找 PATH 中的可执行入口，不启动 agent，不检查登录状态或版本。`;
+const cliOptionsSchema = z.object({
+    all: z.boolean().default(false),
+    json: z.boolean().default(false),
+    help: z.boolean().default(false),
+    version: z.boolean().default(false),
+});
+function printTable(agents) {
+    if (agents.length === 0) {
+        console.log("未在 PATH 中检测到支持的 agent。使用 agent-helper list --all 查看检测范围。");
+        return;
+    }
+    const rows = [["AGENT", "COMMAND", "STATUS", "PATH"], ...agents.map((agent) => [
+            agent.name, agent.command, agent.installed ? "found" : "not found", agent.path ?? "-",
+        ])];
+    const widths = [0, 1, 2].map((column) => Math.max(...rows.map((row) => row[column].length)));
+    console.log(rows.map((row) => row.map((value, column) => column < 3 ? value.padEnd(widths[column] + 2) : value).join("")).join("\n"));
+}
+async function main() {
+    const { values, positionals } = parseArgs({
+        options: {
+            all: { type: "boolean", short: "a" },
+            json: { type: "boolean" },
+            help: { type: "boolean", short: "h" },
+            version: { type: "boolean", short: "v" },
+        },
+        allowPositionals: true,
+        strict: true,
+    });
+    const options = cliOptionsSchema.parse(values);
+    if (positionals.length > 1 || (positionals[0] !== undefined && positionals[0] !== "list")) {
+        throw new Error(`未知命令：${positionals.join(" ")}。使用 agent-helper --help 查看帮助。`);
+    }
+    if (options.help) {
+        console.log(help);
+        return;
+    }
+    if (options.version) {
+        const metadata = z.object({ version: z.string().min(1) }).parse(JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")));
+        console.log(metadata.version);
+        return;
+    }
+    if (positionals.length === 0) {
+        if (options.all || options.json)
+            throw new Error("--all 和 --json 需要与 list 命令一起使用。");
+        console.log(help);
+        return;
+    }
+    const agents = await listAgents({ includeMissing: options.all });
+    if (options.json)
+        console.log(JSON.stringify(agents, null, 2));
+    else
+        printTable(agents);
+}
+main().catch((error) => {
+    console.error(`agent-helper: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+});

package/dist/config/schema.d.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+/** HTTP(S) proxy endpoint used by installation subprocesses. */
+export declare const proxyUrlSchema: z.ZodString;
+/** Validate the object produced by a TOML parser; never persist resolved environment values. */
+export declare const configSchema: z.ZodObject<{
+    version: z.ZodDefault<z.ZodLiteral<1>>;
+    proxy: z.ZodOptional<z.ZodString>;
+    no_proxy: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+/** Only these keys are writable through `config set` / `config unset`. */
+export declare const configKeySchema: z.ZodEnum<{
+    no_proxy: "no_proxy";
+    proxy: "proxy";
+}>;
+/** User-provided fields, before defaults are applied. */
+export type ConfigInput = z.input<typeof configSchema>;
+/** Validated configuration with defaults, independent of runtime environment. */
+export type Config = z.output<typeof configSchema>;
+export type ConfigKey = z.infer<typeof configKeySchema>;

package/dist/config/schema.js

@@ -0,0 +1,30 @@
+import { z } from "zod";
+/** HTTP(S) proxy endpoint used by installation subprocesses. */
+export const proxyUrlSchema = z.string().min(1).superRefine((value, context) => {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        context.addIssue({ code: "custom", message: "代理必须是有效的 HTTP/HTTPS URL。" });
+        return;
+    }
+    if (value !== value.trim() || /\s/.test(value)) {
+        context.addIssue({ code: "custom", message: "代理 URL 不能包含空白字符。" });
+    }
+    if (!/^https?:\/\//i.test(value) || !["http:", "https:"].includes(url.protocol) || !url.hostname) {
+        context.addIssue({ code: "custom", message: "代理仅支持 http:// 或 https://。" });
+    }
+    if ((url.pathname !== "" && url.pathname !== "/") || url.search || url.hash) {
+        context.addIssue({ code: "custom", message: "代理 URL 不能包含路径、查询参数或片段。" });
+    }
+});
+const noProxyEntrySchema = z.string().min(1).refine((value) => !/[\s,]/.test(value), "每个 no_proxy 条目必须是单独的非空规则，不能包含空白或逗号。");
+/** Validate the object produced by a TOML parser; never persist resolved environment values. */
+export const configSchema = z.strictObject({
+    version: z.literal(1).default(1),
+    proxy: proxyUrlSchema.optional(),
+    no_proxy: z.array(noProxyEntrySchema).default([]),
+});
+/** Only these keys are writable through `config set` / `config unset`. */
+export const configKeySchema = z.enum(["proxy", "no_proxy"]);

package/dist/detection/find-executable.d.ts

@@ -0,0 +1,3 @@
+import type { DetectionContext } from "./types.js";
+/** Search PATH in order without running the executable or loading shell profiles. */
+export declare function findExecutable(command: string, context: DetectionContext): Promise<string | null>;

package/dist/detection/find-executable.js

@@ -0,0 +1,46 @@
+import { constants } from "node:fs";
+import { access, stat } from "node:fs/promises";
+import { posix, win32 } from "node:path";
+function getEnv(context, name) {
+    if (context.platform !== "win32")
+        return context.env[name];
+    const key = Object.keys(context.env).find((key) => key.toUpperCase() === name);
+    return key === undefined ? undefined : context.env[key];
+}
+async function isExecutable(file, windows) {
+    try {
+        if (!(await stat(file)).isFile())
+            return false;
+        await access(file, windows ? constants.F_OK : constants.X_OK);
+        return true;
+    }
+    catch (error) {
+        const code = error.code;
+        if (["ENOENT", "ENOTDIR", "EACCES", "EPERM", "ELOOP"].includes(code ?? ""))
+            return false;
+        throw error;
+    }
+}
+/** Search PATH in order without running the executable or loading shell profiles. */
+export async function findExecutable(command, context) {
+    const windows = context.platform === "win32";
+    const paths = windows ? win32 : posix;
+    const extensions = windows
+        ? (getEnv(context, "PATHEXT") ?? ".COM;.EXE;.BAT;.CMD")
+            .split(";")
+            .filter((extension) => /^\.[a-z0-9]+$/i.test(extension))
+        : [""];
+    const directories = (getEnv(context, "PATH") ?? "").split(paths.delimiter);
+    for (const rawDirectory of directories) {
+        // Empty PATH entries do not implicitly opt into scanning the current directory.
+        const directory = windows ? rawDirectory.replace(/^"(.*)"$/, "$1") : rawDirectory;
+        if (!directory)
+            continue;
+        for (const extension of extensions) {
+            const candidate = paths.resolve(context.cwd, directory, `${command}${extension}`);
+            if (await isExecutable(candidate, windows))
+                return candidate;
+        }
+    }
+    return null;
+}

package/dist/detection/types.d.ts

@@ -0,0 +1,10 @@
+import type { AgentDefinition } from "../schema.js";
+export interface DetectionContext {
+    env: NodeJS.ProcessEnv;
+    platform: NodeJS.Platform;
+    cwd: string;
+}
+export interface AgentProvider {
+    definition: AgentDefinition;
+    detect(context: DetectionContext): Promise<string | null>;
+}

package/dist/detection/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { listAgents, type ListAgentsOptions } from "./list-agents.js";
+export { agentDefinitionSchema, agentResultSchema, agentListSchema, type AgentDefinition, type AgentResult } from "./schema.js";
+export { configSchema, configKeySchema, proxyUrlSchema, type ConfigInput, type Config, type ConfigKey } from "./config/schema.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { listAgents } from "./list-agents.js";
+export { agentDefinitionSchema, agentResultSchema, agentListSchema } from "./schema.js";
+export { configSchema, configKeySchema, proxyUrlSchema } from "./config/schema.js";

package/dist/list-agents.d.ts

@@ -0,0 +1,6 @@
+import type { DetectionContext } from "./detection/types.js";
+import { type AgentResult } from "./schema.js";
+export interface ListAgentsOptions extends Partial<DetectionContext> {
+    includeMissing?: boolean;
+}
+export declare function listAgents(options?: ListAgentsOptions): Promise<AgentResult[]>;

package/dist/list-agents.js

@@ -0,0 +1,14 @@
+import { builtInAgents } from "./agents/index.js";
+import { agentListSchema } from "./schema.js";
+export async function listAgents(options = {}) {
+    const context = {
+        env: options.env ?? process.env,
+        platform: options.platform ?? process.platform,
+        cwd: options.cwd ?? process.cwd(),
+    };
+    const results = await Promise.all(builtInAgents.map(async (provider) => {
+        const path = await provider.detect(context);
+        return { ...provider.definition, installed: path !== null, path };
+    }));
+    return agentListSchema.parse(results).filter((agent) => options.includeMissing || agent.installed);
+}

package/dist/schema.d.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+export declare const agentDefinitionSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    command: z.ZodString;
+}, z.core.$strip>;
+export declare const agentResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    command: z.ZodString;
+    installed: z.ZodLiteral<true>;
+    path: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    command: z.ZodString;
+    installed: z.ZodLiteral<false>;
+    path: z.ZodNull;
+}, z.core.$strip>], "installed">;
+export declare const agentListSchema: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    command: z.ZodString;
+    installed: z.ZodLiteral<true>;
+    path: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    command: z.ZodString;
+    installed: z.ZodLiteral<false>;
+    path: z.ZodNull;
+}, z.core.$strip>], "installed">>;
+export type AgentDefinition = z.infer<typeof agentDefinitionSchema>;
+export type AgentResult = z.infer<typeof agentResultSchema>;

package/dist/schema.js

@@ -0,0 +1,11 @@
+import { z } from "zod";
+export const agentDefinitionSchema = z.object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    command: z.string().min(1),
+});
+export const agentResultSchema = z.discriminatedUnion("installed", [
+    agentDefinitionSchema.extend({ installed: z.literal(true), path: z.string().min(1) }),
+    agentDefinitionSchema.extend({ installed: z.literal(false), path: z.null() }),
+]);
+export const agentListSchema = z.array(agentResultSchema);

package/docs/configuration.md

@@ -0,0 +1,88 @@
+# 配置功能设计
+
+状态：已定义 TypeScript / Zod 数据模型和 TOML 示例。文件读写、`config` 命令、`install` 命令及代理注入尚未实现；本文件中的命令是拟实现的接口。
+
+## 文件位置与格式
+
+用户级配置固定为 `~/.ai-agent-helper/config.toml`，采用 TOML。使用 `os.homedir()` 定位用户主目录，不依赖 shell 展开 `~`。Windows 对应 `%USERPROFILE%\.ai-agent-helper\config.toml`。首版只加载用户级配置。
+
+```toml
+# 配置格式版本
+version = 1
+
+# 所有 agent 安装操作共用的默认代理
+proxy = "http://127.0.0.1:7890"
+
+# 具体匹配行为由所使用的安装工具决定
+no_proxy = ["localhost", "127.0.0.1", "::1"]
+```
+
+完整带注释示例见 `examples/config.toml`。
+
+## 持久化数据模型
+
+模型定义位于 `src/config/schema.ts`。字段采用 snake_case，与 TOML 示例保持一致。
+
+| 字段 | 类型 | 省略时 | 校验及含义 |
+| --- | --- | --- | --- |
+| `version` | 字面量整数 `1` | 按 `1` 读取 | 配置格式版本，首次创建时写入；不允许通过 `config set` 修改 |
+| `proxy` | 可选字符串 | 继承安装工具原有代理配置 | 必须是 HTTP/HTTPS 代理 URL；支持主机、端口、IPv6 及 URL 编码的认证信息；禁止空白、业务路径、查询参数和片段 |
+| `no_proxy` | 字符串数组 | `[]` | 每个非空条目是一条绕过规则，不含空白或逗号；安装器负责转换和兼容性检查 |
+
+不允许未知字段，避免拼写错误被悄悄忽略。不支持的 `version` 应报错并停止写入，不能用当前模型覆盖未来版本的文件。TOML 没有 `null`，可选配置通过省略字段表示。
+
+`ConfigInput` 表示 TOML 解析后的输入，允许省略默认字段；`Config` 表示 Zod 校验并补齐默认值后的数据。默认配置为：
+
+```ts
+const defaults = configSchema.parse({});
+// { version: 1, no_proxy: [] }
+```
+
+`proxy` 不使用虚构的默认地址，也不把环境变量中的值写回文件。
+
+## 命令接口
+
+```sh
+# 查看已保存的配置及内置默认值，以 TOML 展示
+agent-helper config
+
+# 设置默认安装代理
+agent-helper config set proxy http://127.0.0.1:7890
+
+# 数组通过多个参数设置，每个参数对应一条规则
+agent-helper config set no_proxy localhost 127.0.0.1 ::1
+
+# 删除代理配置，恢复继承安装工具原有配置
+agent-helper config unset proxy
+
+# 删除绕过规则，恢复内置默认空数组
+agent-helper config unset no_proxy
+```
+
+可写配置键由 `configKeySchema` 限定为 `proxy` 和 `no_proxy`。`set proxy` 要求一个字符串值；`set no_proxy` 要求至少一个条目，需要恢复默认空数组时使用 `unset`。写入前应校验修改后的整份配置，而不只是当前字段。帮助文本应列出允许的键、值类型、默认行为、配置路径和示例。
+
+`config` 展示配置文件中的值及内置默认值，不将安装工具或当前环境中的代理误标成已保存配置。代理认证信息必须脱敏，包括用户名与密码；`--json` 等将来新增的展示方式也遵循此规则。
+
+## 安装时的解析规则
+
+默认代理针对安装子进程。安装代理选择按以下顺序进行：
+
+1. 本次安装命令显式指定的 `--proxy`。
+2. 配置文件中的 `proxy`。
+3. 安装工具本来的配置和环境变量；由安装工具自行解释其优先级。
+
+前两项命中时，安装适配器为本次子进程设置对应代理参数及环境变量，不修改系统代理或安装工具的全局配置。此时，非空 `no_proxy` 明确替换工具继承的绕过规则；空数组不注入绕过规则，保留工具已有设置。代理都未显式指定时，不单独应用 helper 的 `no_proxy`。
+
+`no_proxy` 不宣称统一不同工具对域名、端口、通配符和 CIDR 的匹配语义。适配器必须验证或拒绝其不支持的规则；不能静默忽略并宣称代理已正确应用。首版 URL 模型仅支持 HTTP/HTTPS；其他协议应在安装器支持后再扩展。
+
+## 读写要求
+
+- 文件不存在时返回内置默认值；只查看配置不会创建目录或文件。
+- 第一次 `set` 才创建目录与配置文件，写入 `version = 1`。
+- 文件存在但 TOML 语法或数据校验失败时，报告文件位置和字段错误，停止修改，不覆盖原文件。
+- 错误信息和展示结果不得输出包含认证信息的原始 URL。
+- `set` / `unset` 需要使用能保留注释和原有顺序的编辑方式；只解析后重新 stringify 整份文件不能满足要求。
+- 在同目录写入临时文件并原子替换，失败时保留原文件；写入前检查源文件是否变化，避免覆盖外部并发修改。
+- 未知字段、未知版本的文件可以由用户手动维护，但当前版本拒绝修改，保留原文。
+
+文件格式版本与 npm 包版本分开维护。后续确有需求时，再为安装器参数或 agent 专属配置添加 TOML 分组及迁移规则。

package/examples/config.toml

@@ -0,0 +1,13 @@
+# 保存到 ~/.ai-agent-helper/config.toml。
+# 本示例属于配置模型设计；当前 CLI 尚未提供 config / install 命令。
+
+# 配置文件格式版本，由 helper 管理。
+version = 1
+
+# 安装 agent 时的默认 HTTP/HTTPS 代理。
+# 取消注释前请替换为自己的代理地址；省略时继承安装工具原有设置。
+# proxy = "http://127.0.0.1:7890"
+
+# 使用默认或临时代理时，交给各安装器处理的绕过规则。
+# 不需要绕过规则时可以省略此项。
+no_proxy = ["localhost", "127.0.0.1", "::1"]

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "ai-agent-helper",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "description": "Discover locally installed AI agent CLIs.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tool-helper/ai-agent-helper.git"
+  },
+  "homepage": "https://github.com/tool-helper/ai-agent-helper#readme",
+  "bugs": {
+    "url": "https://github.com/tool-helper/ai-agent-helper/issues"
+  },
+  "type": "module",
+  "bin": {
+    "agent-helper": "dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "docs/configuration.md",
+    "examples/config.toml"
+  ],
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "typecheck": "tsc -p tsconfig.check.json",
+    "test": "node --import tsx --test test/*.test.ts",
+    "check": "npm run typecheck && npm test && npm run build",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "agent",
+    "cli",
+    "claude",
+    "codex",
+    "gemini",
+    "typescript"
+  ],
+  "dependencies": {
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "tsx": "^4.23.15",
+    "typescript": "^7.0.2"
+  }
+}