ai-agent-helper 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.2.0
+
+- 实现 `config`、`config set key=value`、`config unset`，使用用户级 TOML 文件，保留注释并校验整份配置。
+- 实现经默认代理安装/更新 npm Codex，支持临时代理、预览和重新安装。
+- 实现 `update` 默认更新工具自身，以及 `--self`、`--agent codex`、`--all-agents` 互斥目标。
+- 检查 npm 全局安装来源和 prefix，拒绝覆盖其他渠道或 `npm link` 安装。
+- 增加配置、安装执行及真实 npm 本地代理集成测试。
+
 ## 0.1.1
 
 - 定义 `~/.ai-agent-helper/config.toml` 的配置数据模型：`version`、`proxy`、`no_proxy`。

package/README.md

@@ -1,6 +1,8 @@
 # ai-agent-helper
 
-使用 TypeScript 和 Zod 开发的 AI agent CLI 管理工具。首版 `0.1.0` 仅实现列出本机 PATH 中可找到的 agent，不安装、更新或启动 agent。
+使用 TypeScript 和 Zod 开发的 AI agent CLI 管理工具。检测本机 PATH 中的 agent，管理 TOML 配置，并通过默认代理安装或更新 Codex，也支持更新工具自身。
+
+从 `0.2.0` 起提供 `config`、`install`、`update` 命令；安装和更新 agent 目前先支持 Codex。
 
 需要 Node.js **22.13 或更高版本**。
 
@@ -34,6 +36,16 @@ agent-helper list --help
 agent-helper list --all
 agent-helper list --json
 agent-helper list --all --json
+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 install codex --dry-run
+agent-helper install codex
+agent-helper update --dry-run
+agent-helper update --self
+agent-helper update --agent codex
+agent-helper update --all-agents
 ```
 
 - 无参数时显示帮助。
@@ -85,11 +97,34 @@ agentListSchema.parse(all);
 
 包提供 ESM 导出和类型声明。Zod 校验 CLI 选项及检测结果，并约束已检测到条目必须包含路径、未检测到条目的路径必须为 `null`。
 
-## 配置功能设计
+## 配置与代理
+
+配置文件为 `~/.ai-agent-helper/config.toml`，采用 TOML。`config` 查看配置与默认值；`config set key=value` 可以一次设置多项，只按首个等号分割。修改保留注释、字段顺序和换行风格，写入前校验整份配置，失败不覆盖文件。
+
+```toml
+version = 1
+proxy = "http://127.0.0.1:7890"
+no_proxy = ["localhost", "127.0.0.1", "::1"]
+```
+
+可写项为 `proxy` 和 `no_proxy`；版本字段由工具维护。CLI 中的 `no_proxy` 使用逗号分隔，保存后为 TOML 数组。删除字段使用 `config unset`，空字符串不会当成删除。`config` 展示代理时隐藏账号和密码；文件仍保存实际配置值。
 
-配置采用 `~/.ai-agent-helper/config.toml`，以 TOML 保存注释和配置分组。当前已提供 `configSchema`、`configKeySchema`、`proxyUrlSchema` 及对应 TypeScript 类型；配置文件读写、`config` 命令和代理安装功能尚未实现。
+代理优先级为 `--proxy` → 配置文件的 `proxy` → npm 已有配置。代理及绕过规则只注入安装/更新子进程，不改动系统代理或全局 npm 配置。支持 HTTP/HTTPS 代理地址，绕过规则的匹配语义由 npm 决定。
 
-设计及命令约定见 [配置功能设计](docs/configuration.md)，带注释的文件示例见 [config.toml](examples/config.toml)。初版模型包含配置格式版本 `version`、默认安装代理 `proxy` 和绕过规则 `no_proxy`。
+详细约定见 [配置功能文档](docs/configuration.md)，带注释的示例见 [config.toml](examples/config.toml)。也提供配置模型、`readConfig`、`writeConfig`、`parseAssignments` 等 TypeScript API。
+
+## 安装与更新
+
+- `install codex` 安装 npm 包 `@openai/codex`；已安装时跳过，`--reinstall` 可重装普通 npm 全局安装。
+- `update` 默认等同于 `update --self`，更新 npm 包 `ai-agent-helper`。
+- `update --agent codex` 只更新 Codex；`update --all-agents` 只更新 PATH 中已检测到且当前支持更新的 agent，目前为 Codex。
+- `--self`、`--agent`、`--all-agents` 互斥。其他 agent 保留检测功能，暂不支持安装/更新。
+- 安装/更新通过 npm 官方 registry 查询 `latest`，然后安装查询到的确切版本，保留当前 npm 的全局 prefix；更新不会自动降级。
+- 仅管理当前 npm 全局目录中的普通安装。遇到源码、`npm link`、临时 `npx`、其他 prefix 或其他渠道的安装时，实际更新会报错并提示原安装方式，防止写入另一个位置。
+- `--dry-run` 仅检查本地 npm 目录、已有版本和安装来源，展示计划；不联网查询版本，不执行安装。对于不适用的安装来源会展示原因。
+- 安装完成后验证目标目录内的包版本和命令入口，不启动 Codex、不测试登录。首次安装如果命令目录尚未在 PATH 中，会提示检查 PATH 并重新打开终端。
+
+Codex 的 npm 安装/更新方式见 [OpenAI 官方 CLI 文档](https://developers.openai.com/codex/cli#npm)。
 
 ## 开发与扩展
 
@@ -101,4 +136,6 @@ 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 执行权限等用例。平台专属用例只在对应平台执行。
+`src/list-agents.ts` 负责检测汇总，`src/config/` 负责配置，`src/installation/` 负责 npm 安装与更新，`src/proxy/` 负责子进程代理环境，`src/cli.ts` 负责命令分发。Codex 的 npm 包及入口信息定义在独立 agent 模块中。
+
+测试覆盖 CLI、配置注释保留、原子写入、更新目标互斥、安装来源检查及失败验证。代理集成测试使用真实 npm、本地 HTTP 测试代理和隔离全局目录中的测试包，验证元数据及安装包经过代理，并完成安装和升级；不安装真实 Codex。平台专属用例只在对应平台执行。

package/dist/agents/codex.js

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

package/dist/cli.js

@@ -2,36 +2,82 @@
 import { readFileSync } from "node:fs";
 import { parseArgs } from "node:util";
 import { z } from "zod";
+import { configPath, formatConfig, parseAssignments, readConfig, writeConfig } from "./config/store.js";
+import { configKeySchema } from "./config/schema.js";
+import { managePackage, resolveUpdateTarget } from "./installation/manage.js";
+import { codex } from "./agents/codex.js";
+import { redact } from "./proxy/environment.js";
 import { listAgents } from "./list-agents.js";
-const help = `agent-helper — 列出本地 AI agent CLI
+const help = `agent-helper — 管理本地 AI agent CLI
 
 用法：
   agent-helper list [--all] [--json]
+  agent-helper config [set <key=value> ... | unset <key>]
+  agent-helper install codex [--proxy <url>] [--dry-run] [--reinstall]
+  agent-helper update [--self | --agent codex | --all-agents] [--proxy <url>] [--dry-run]
   agent-helper [--help | --version]
 
 命令：
   list             列出 PATH 中检测到的 agent
+  config           查看所有配置，或设置/删除配置项
+  install codex    通过 npm 安装 Codex
+  update           默认更新工具自身；--agent codex 更新 Codex
 
 选项：
   -a, --all        同时显示未检测到的 agent（仅用于 list）
       --json       输出 JSON 数组（仅用于 list）
   -h, --help       显示帮助，支持 list --help
   -v, --version    显示 agent-helper 版本
+      --self       更新工具自身（update 的默认目标）
+      --agent      指定要更新的 agent，目前仅 codex
+      --all-agents 更新所有已安装且支持更新的 agent，目前仅 codex
+      --proxy      本次安装/更新使用的 HTTP/HTTPS 代理
+      --dry-run    本地预览，不联网查询版本，不执行安装
+      --reinstall  重新安装已存在的 npm Codex（仅用于 install）
 
 示例：
   agent-helper list
   agent-helper list --all
   agent-helper list --json
   agent-helper list --all --json
+  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 install codex
+  agent-helper update
+  agent-helper update --agent codex
 
 检测范围：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),
-});
+list 只查找 PATH 中的入口；安装/更新仅支持 npm Codex 和 npm 全局安装的工具自身。
+配置文件：~/.ai-agent-helper/config.toml；配置只作用于安装/更新子进程。`;
+const commandHelp = {
+    config: `用法：
+  agent-helper config
+  agent-helper config set <key=value> [key=value ...]
+  agent-helper config unset <key>
+
+可写项：proxy（HTTP/HTTPS URL）；no_proxy（逗号分隔的非空规则）。
+配置文件：~/.ai-agent-helper/config.toml；省略 proxy 时继承安装工具原有配置。
+示例：agent-helper config set proxy=http://127.0.0.1:7890 no_proxy=localhost,127.0.0.1
+version 由工具管理；未知键、重复键和无效值会报错，修改保留原有注释。`,
+    install: `用法：agent-helper install codex [--proxy <url>] [--dry-run] [--reinstall]
+仅支持 npm 包 @openai/codex，安装目标为当前 npm 全局目录。
+代理优先级：--proxy → config 中的 proxy → npm 原有配置。
+--dry-run 只做本地检查；不会联网查询、下载或修改安装。
+示例：agent-helper install codex --proxy http://127.0.0.1:7890`,
+    update: `用法：agent-helper update [--self | --agent codex | --all-agents] [--proxy <url>] [--dry-run]
+不指定目标时等同于 --self；三个目标参数互斥。
+--all-agents 仅更新已检测到且支持的 agent，目前只有 codex。
+只支持普通 npm 全局安装；源码、npm link、npx 或其他安装渠道请通过原方式更新。
+--dry-run 不联网、不安装；实际更新先查询 latest，再安装该具体版本。
+示例：agent-helper update --agent codex --dry-run`,
+};
+function printResult(result) {
+    console.log(`${result.target}: ${result.status} (${result.from ?? "未安装"} → ${result.to})`);
+    console.log(`代理：${result.proxy ?? "继承 npm 原有配置"}`);
+    console.log(`命令：npm ${result.args.map((argument) => JSON.stringify(argument)).join(" ")}`);
+    console.log(result.message);
+}
 function printTable(agents) {
     if (agents.length === 0) {
         console.log("未在 PATH 中检测到支持的 agent。使用 agent-helper list --all 查看检测范围。");
@@ -50,36 +96,96 @@ async function main() {
             json: { type: "boolean" },
             help: { type: "boolean", short: "h" },
             version: { type: "boolean", short: "v" },
+            self: { type: "boolean" },
+            agent: { type: "string" },
+            "all-agents": { type: "boolean" },
+            proxy: { type: "string" },
+            "dry-run": { type: "boolean" },
+            reinstall: { type: "boolean" },
         },
         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 查看帮助。`);
+    const command = positionals[0];
+    if (command !== undefined && !["list", "config", "install", "update"].includes(command)) {
+        throw new Error("未知命令。使用 agent-helper --help 查看帮助。");
     }
-    if (options.help) {
-        console.log(help);
+    if (values.help) {
+        console.log(command === undefined ? help : commandHelp[command] ?? help);
         return;
     }
-    if (options.version) {
+    const allowed = {
+        root: ["version"], list: ["all", "json"], config: [],
+        install: ["proxy", "dry-run", "reinstall"],
+        update: ["self", "agent", "all-agents", "proxy", "dry-run"],
+    };
+    for (const key of Object.keys(values)) {
+        if (!allowed[command ?? "root"].includes(key))
+            throw new Error(`当前命令不支持 --${key}。使用 --help 查看帮助。`);
+    }
+    if (values.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 命令一起使用。");
+    if (command === undefined) {
         console.log(help);
         return;
     }
-    const agents = await listAgents({ includeMissing: options.all });
-    if (options.json)
-        console.log(JSON.stringify(agents, null, 2));
-    else
-        printTable(agents);
+    if (command === "list") {
+        if (positionals.length !== 1)
+            throw new Error("list 不接受额外位置参数。");
+        const agents = await listAgents({ includeMissing: values.all ?? false });
+        if (values.json)
+            console.log(JSON.stringify(agents, null, 2));
+        else
+            printTable(agents);
+        return;
+    }
+    if (command === "config") {
+        const action = positionals[1];
+        if (action === undefined)
+            console.log(`# ${configPath()}\n${formatConfig(await readConfig())}`);
+        else if (action === "set") {
+            await writeConfig(parseAssignments(positionals.slice(2)));
+            console.log(`配置已保存：${configPath()}`);
+        }
+        else if (action === "unset" && positionals.length === 3) {
+            const key = configKeySchema.safeParse(positionals[2]);
+            if (!key.success)
+                throw new Error("可删除配置项仅支持 proxy、no_proxy。");
+            await writeConfig(new Map([[key.data, undefined]]));
+            console.log(`配置项已恢复默认：${key.data}`);
+        }
+        else
+            throw new Error("用法：config [set <key=value> ... | unset <key>]");
+        return;
+    }
+    const config = await readConfig();
+    const common = { config, dryRun: values["dry-run"] ?? false, ...(values.proxy === undefined ? {} : { proxy: values.proxy }) };
+    if (command === "install") {
+        if (positionals.length !== 2 || positionals[1] !== "codex")
+            throw new Error("用法：install codex。目前仅支持 codex。");
+        printResult(await managePackage({ ...common, target: "codex", action: "install", reinstall: values.reinstall ?? false }));
+        return;
+    }
+    if (positionals.length !== 1)
+        throw new Error("update 不接受位置参数，请使用 --agent codex。");
+    const target = resolveUpdateTarget({
+        ...(values.self === undefined ? {} : { self: values.self }),
+        ...(values.agent === undefined ? {} : { agent: values.agent }),
+        ...(values["all-agents"] === undefined ? {} : { allAgents: values["all-agents"] }),
+    });
+    if (target.kind === "all-agents") {
+        const installed = await codex.detect({ env: process.env, platform: process.platform, cwd: process.cwd() });
+        if (!installed) {
+            console.log("未在 PATH 中检测到可更新的 Codex；其他 agent 尚未支持更新。");
+            return;
+        }
+    }
+    printResult(await managePackage({ ...common, target: target.kind === "self" ? "self" : "codex", action: "update" }));
 }
 main().catch((error) => {
-    console.error(`agent-helper: ${error instanceof Error ? error.message : String(error)}`);
+    console.error(`agent-helper: ${redact(error instanceof Error ? error.message : String(error))}`);
     process.exitCode = 1;
 });

package/dist/config/store.d.ts

@@ -0,0 +1,10 @@
+import { type Config, type ConfigKey } from "./schema.js";
+export declare function configPath(home?: string): string;
+export declare function readConfig(path?: string): Promise<Config>;
+export type ConfigChanges = Map<ConfigKey, string | string[] | undefined>;
+/** Split on the first equals sign: credentials may themselves contain '='. */
+export declare function parseAssignments(assignments: string[]): ConfigChanges;
+/** Edit only AST value ranges, leaving comments, whitespace and key order intact. */
+export declare function editConfig(source: string, changes: ConfigChanges): string;
+export declare function writeConfig(changes: ConfigChanges, path?: string): Promise<void>;
+export declare function formatConfig(config: Config): string;

package/dist/config/store.js

@@ -0,0 +1,167 @@
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { lstat, mkdir, open, readFile, rename, unlink } from "node:fs/promises";
+import { stringify } from "smol-toml";
+import { getStaticTOMLValue, parseForESLint } from "toml-eslint-parser";
+import { configKeySchema, configSchema } from "./schema.js";
+export function configPath(home = homedir()) {
+    return join(home, ".ai-agent-helper", "config.toml");
+}
+async function readOptional(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw new Error(`无法读取配置文件：${path}`);
+    }
+}
+function validate(value) {
+    const result = configSchema.safeParse(value);
+    if (!result.success) {
+        const fields = [...new Set(result.error.issues.map((issue) => issue.path.join(".") || "根节点/未知字段"))];
+        throw new Error(`配置校验失败（${fields.join("、")}），请检查字段、类型、代理 URL 和格式版本。`);
+    }
+    return result.data;
+}
+function parseConfig(source) {
+    let value;
+    try {
+        value = getStaticTOMLValue(parseForESLint(source, { tomlVersion: "1.0" }).ast);
+    }
+    catch {
+        throw new Error("TOML 语法错误，请检查引号、重复键和数组格式。");
+    }
+    return validate(value);
+}
+export async function readConfig(path = configPath()) {
+    const source = await readOptional(path);
+    try {
+        return parseConfig(source ?? "");
+    }
+    catch (error) {
+        throw new Error(`${path}：${error.message}`);
+    }
+}
+/** Split on the first equals sign: credentials may themselves contain '='. */
+export function parseAssignments(assignments) {
+    if (assignments.length === 0)
+        throw new Error("用法：config set <key=value> [key=value ...]");
+    const changes = new Map();
+    for (const assignment of assignments) {
+        const separator = assignment.indexOf("=");
+        if (separator <= 0)
+            throw new Error("配置格式应为 key=value。");
+        const keyResult = configKeySchema.safeParse(assignment.slice(0, separator));
+        if (!keyResult.success)
+            throw new Error("可写配置项仅支持 proxy、no_proxy。");
+        const key = keyResult.data;
+        if (changes.has(key))
+            throw new Error(`配置项重复：${key}`);
+        const value = assignment.slice(separator + 1);
+        changes.set(key, key === "no_proxy" ? value.split(",") : value);
+    }
+    const candidate = Object.fromEntries(changes);
+    validate(candidate);
+    return changes;
+}
+/** Edit only AST value ranges, leaving comments, whitespace and key order intact. */
+export function editConfig(source, changes) {
+    const current = parseConfig(source);
+    const candidate = { ...current };
+    for (const [key, value] of changes) {
+        configKeySchema.parse(key);
+        if (value === undefined)
+            delete candidate[key];
+        else
+            candidate[key] = value;
+    }
+    validate(candidate);
+    const { ast } = parseForESLint(source, { tomlVersion: "1.0" });
+    const patches = [];
+    const additions = [];
+    const newline = source.includes("\r\n") ? "\r\n" : "\n";
+    const nodes = ast.body[0].body.filter((node) => node.type === "TOMLKeyValue");
+    if (!nodes.some((node) => getStaticTOMLValue(node.key)[0] === "version"))
+        additions.push("version = 1");
+    for (const [key, value] of changes) {
+        const node = nodes.find((node) => getStaticTOMLValue(node.key)[0] === key);
+        const innerComments = node ? ast.comments
+            .filter((comment) => comment.range[0] >= node.value.range[0] && comment.range[1] <= node.value.range[1])
+            .map((comment) => source.slice(comment.range[0], comment.range[1])) : [];
+        if (value === undefined) {
+            if (node)
+                patches.push({ start: node.range[0], end: node.range[1], value: innerComments.join(newline) });
+            continue;
+        }
+        // Let the TOML serializer escape strings instead of treating CLI input as TOML code.
+        const encoded = stringify({ value }).trim().slice("value = ".length);
+        if (node)
+            patches.push({ start: node.value.range[0], end: node.value.range[1], value: encoded.replace(/\n/g, newline) + (innerComments.length ? newline + innerComments.join(newline) : "") });
+        else
+            additions.push(`${key} = ${encoded.replace(/\n/g, newline)}`);
+    }
+    let output = source;
+    for (const patch of patches.sort((a, b) => b.start - a.start)) {
+        output = output.slice(0, patch.start) + patch.value + output.slice(patch.end);
+    }
+    if (additions.length)
+        output += (output && !output.endsWith("\n") ? newline : "") + additions.join(newline) + newline;
+    parseConfig(output);
+    return output;
+}
+export async function writeConfig(changes, path = configPath()) {
+    const original = await readOptional(path);
+    const updated = editConfig(original ?? "", changes);
+    // Unsetting a missing key must not create a new configuration file.
+    if (original === undefined && [...changes.values()].every((value) => value === undefined))
+        return;
+    if (original === updated)
+        return;
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const lockPath = `${path}.lock`;
+    let lock;
+    try {
+        lock = await open(lockPath, "wx", 0o600);
+    }
+    catch {
+        throw new Error(`无法锁定配置文件，请确认没有其他写入进程：${lockPath}`);
+    }
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        if ((await readOptional(path)) !== original)
+            throw new Error("配置文件已被其他进程修改，请重试。");
+        if (original !== undefined && (await lstat(path)).isSymbolicLink())
+            throw new Error("配置文件是符号链接，请直接编辑其目标文件。");
+        const file = await open(temporary, "wx", 0o600);
+        try {
+            await file.writeFile(updated, "utf8");
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        if ((await readOptional(path)) !== original)
+            throw new Error("配置文件已被其他进程修改，请重试。");
+        await rename(temporary, path);
+    }
+    finally {
+        await unlink(temporary).catch(() => { });
+        await lock.close();
+        await unlink(lockPath);
+    }
+}
+export function formatConfig(config) {
+    const copy = { ...config };
+    if (copy.proxy) {
+        const url = new URL(copy.proxy);
+        if (url.username || url.password) {
+            url.username = "REDACTED";
+            url.password = "REDACTED";
+            copy.proxy = url.toString();
+        }
+    }
+    return stringify(copy);
+}

package/dist/detection/types.d.ts

@@ -1,4 +1,5 @@
 import type { AgentDefinition } from "../schema.js";
+import type { NpmAgentInstaller } from "../installation/types.js";
 export interface DetectionContext {
     env: NodeJS.ProcessEnv;
     platform: NodeJS.Platform;
@@ -7,4 +8,5 @@ export interface DetectionContext {
 export interface AgentProvider {
     definition: AgentDefinition;
     detect(context: DetectionContext): Promise<string | null>;
+    installer?: NpmAgentInstaller;
 }

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 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";
+export { configPath, readConfig, writeConfig, parseAssignments, formatConfig, type ConfigChanges } from "./config/store.js";

package/dist/index.js

@@ -1,3 +1,4 @@
 export { listAgents } from "./list-agents.js";
 export { agentDefinitionSchema, agentResultSchema, agentListSchema } from "./schema.js";
 export { configSchema, configKeySchema, proxyUrlSchema } from "./config/schema.js";
+export { configPath, readConfig, writeConfig, parseAssignments, formatConfig } from "./config/store.js";

package/dist/installation/manage.d.ts

@@ -0,0 +1,43 @@
+import type { Config } from "../config/schema.js";
+import type { DetectionContext } from "../detection/types.js";
+import { type NpmRunner } from "./process.js";
+export declare const npmRegistry = "https://registry.npmjs.org/";
+export declare const selfRoot: string;
+export interface ManageOptions {
+    target: "self" | string;
+    action: "install" | "update";
+    config: Config;
+    dryRun?: boolean;
+    proxy?: string;
+    reinstall?: boolean;
+}
+export interface InstallRuntime {
+    context: DetectionContext;
+    selfRoot: string;
+    runNpm: NpmRunner;
+}
+export interface InstallResult {
+    status: "planned" | "skipped" | "installed" | "updated";
+    target: string;
+    packageName: string;
+    from: string | null;
+    to: string;
+    prefix: string;
+    proxy: string | null;
+    args: string[];
+    message: string;
+}
+export declare function managePackage(options: ManageOptions, suppliedRuntime?: InstallRuntime): Promise<InstallResult>;
+export type UpdateTarget = {
+    kind: "self";
+} | {
+    kind: "agent";
+    id: string;
+} | {
+    kind: "all-agents";
+};
+export declare function resolveUpdateTarget(options: {
+    self?: boolean;
+    agent?: string;
+    allAgents?: boolean;
+}): UpdateTarget;

package/dist/installation/manage.js

@@ -0,0 +1,132 @@
+import { access, lstat, readFile, realpath } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import semver from "semver";
+import { z } from "zod";
+import { builtInAgents } from "../agents/index.js";
+import { installationEnvironment, redact } from "../proxy/environment.js";
+import { npmRunner } from "./process.js";
+export const npmRegistry = "https://registry.npmjs.org/";
+const registryArgument = `--registry=${npmRegistry}`;
+const versionSchema = z.string().refine((value) => semver.valid(value) !== null, "无效的包版本");
+const metadataSchema = z.object({ name: z.string(), version: versionSchema });
+export const selfRoot = dirname(fileURLToPath(new URL("../../package.json", import.meta.url)));
+async function metadata(directory, expectedName) {
+    let text;
+    try {
+        text = await readFile(join(directory, "package.json"), "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw new Error(`无法读取已安装的包信息：${directory}`);
+    }
+    let value;
+    try {
+        value = metadataSchema.parse(JSON.parse(text));
+    }
+    catch {
+        throw new Error(`已安装的包信息无效：${directory}`);
+    }
+    if (value.name !== expectedName)
+        throw new Error(`安装位置的包名称不匹配：${directory}`);
+    return value;
+}
+function samePath(a, b, platform) {
+    return platform === "win32" ? resolve(a).toLowerCase() === resolve(b).toLowerCase() : resolve(a) === resolve(b);
+}
+export async function managePackage(options, suppliedRuntime) {
+    const env = installationEnvironment(options.config, options.proxy);
+    const runtime = suppliedRuntime ?? {
+        context: { env, cwd: process.cwd(), platform: process.platform },
+        selfRoot, runNpm: npmRunner(env),
+    };
+    const isSelf = options.target === "self";
+    const provider = builtInAgents.find((provider) => provider.definition.id === options.target);
+    if (!isSelf && !provider?.installer)
+        throw new Error("当前仅支持安装和更新 codex。其他 agent 暂时只支持 list 检测。");
+    if (isSelf && options.action === "install")
+        throw new Error("工具自身请使用 update 或 update --self。");
+    const packageName = isSelf ? "ai-agent-helper" : provider.installer.packageName;
+    const entryPoint = isSelf ? "dist/cli.js" : provider.installer.entryPoint;
+    const [root, prefix] = await Promise.all([runtime.runNpm(["root", "--global"]), runtime.runNpm(["prefix", "--global"])]);
+    if (!root || !prefix)
+        throw new Error("无法确定 npm 全局安装位置。");
+    const directory = join(root, ...packageName.split("/"));
+    const installed = await metadata(directory, packageName);
+    const detected = isSelf ? null : await provider.detect(runtime.context);
+    const command = provider?.definition.command ?? "agent-helper";
+    const expectedBin = runtime.context.platform === "win32" ? prefix : join(prefix, "bin");
+    const executableNames = runtime.context.platform === "win32" ? [command, `${command}.cmd`, `${command}.ps1`] : [command];
+    let detectedInPrefix = detected === null || executableNames
+        .some((name) => samePath(detected, join(expectedBin, name), runtime.context.platform));
+    if (detected !== null && detectedInPrefix && installed && runtime.context.platform !== "win32") {
+        // npm's POSIX entry is a symlink. A same-directory Homebrew/standalone link is a different install.
+        try {
+            detectedInPrefix = samePath(await realpath(detected), await realpath(join(directory, entryPoint)), runtime.context.platform);
+        }
+        catch {
+            detectedInPrefix = false;
+        }
+    }
+    const linked = installed !== null && (await lstat(directory)).isSymbolicLink();
+    let blocked;
+    if (isSelf) {
+        if (!installed || linked || !samePath(await realpath(directory), await realpath(runtime.selfRoot), runtime.context.platform)) {
+            blocked = "当前 helper 不是此 npm 全局目录中的普通安装（可能是源码、npm link、npx 或其他 prefix），请通过原安装方式更新。";
+        }
+    }
+    else if (linked || !detectedInPrefix || (detected !== null && installed === null)) {
+        blocked = "Codex 来自其他目录、安装渠道或 npm link，请使用原安装方式更新，避免产生重复安装。";
+    }
+    const base = {
+        target: options.target, packageName, from: installed?.version ?? null, to: "latest", prefix,
+        proxy: (options.proxy ?? options.config.proxy) ? redact(options.proxy ?? options.config.proxy) : null,
+        args: ["install", "--global", `${packageName}@latest`, "--prefix", prefix, registryArgument],
+    };
+    if (options.action === "install" && !options.reinstall && (installed || detected)) {
+        return { ...base, status: "skipped", message: "已安装，跳过；需要重新安装时使用 --reinstall。" };
+    }
+    if (!isSelf && options.action === "update" && !installed && !detected)
+        throw new Error("Codex 尚未安装，请先运行 agent-helper install codex。");
+    if (options.dryRun)
+        return { ...base, status: "planned", message: blocked ?? "仅预览；未联网查询版本，未执行安装。执行时解析 latest 并固定版本。" };
+    if (blocked)
+        throw new Error(blocked);
+    const response = await runtime.runNpm(["view", `${packageName}@latest`, "version", "--json", registryArgument]);
+    let latest;
+    try {
+        latest = versionSchema.parse(JSON.parse(response));
+    }
+    catch {
+        throw new Error("npm 返回的 latest 版本无效。");
+    }
+    const args = ["install", "--global", `${packageName}@${latest}`, "--prefix", prefix, registryArgument];
+    if (options.action === "update" && installed && semver.gte(installed.version, latest)) {
+        return { ...base, args, to: latest, status: "skipped", message: "当前版本已是最新版或更新的版本。" };
+    }
+    await runtime.runNpm(args, true);
+    const after = await metadata(directory, packageName);
+    if (after?.version !== latest)
+        throw new Error("npm 已退出，但目标目录的包版本验证失败。");
+    try {
+        await access(join(directory, entryPoint));
+    }
+    catch {
+        throw new Error("包版本已写入，但命令入口缺失，安装验证失败。");
+    }
+    const message = isSelf ? "工具已更新，请重新运行 agent-helper。"
+        : detected === null ? `安装已完成；命令目录为 ${expectedBin}，请确认它在 PATH 中并重新打开终端。` : "Codex 包版本及命令入口验证通过。";
+    return { ...base, args, to: latest, status: options.action === "install" ? "installed" : "updated", message };
+}
+export function resolveUpdateTarget(options) {
+    if (Number(options.self === true) + Number(options.agent !== undefined) + Number(options.allAgents === true) > 1) {
+        throw new Error("--self、--agent、--all-agents 不能同时使用。");
+    }
+    if (options.agent !== undefined) {
+        if (options.agent !== "codex")
+            throw new Error("当前仅支持更新 codex。");
+        return { kind: "agent", id: options.agent };
+    }
+    return options.allAgents ? { kind: "all-agents" } : { kind: "self" };
+}

package/dist/installation/process.d.ts

@@ -0,0 +1,2 @@
+export type NpmRunner = (args: string[], stream?: boolean) => Promise<string>;
+export declare function npmRunner(env: NodeJS.ProcessEnv): NpmRunner;

package/dist/installation/process.js

@@ -0,0 +1,64 @@
+import spawn from "cross-spawn";
+import { StringDecoder } from "node:string_decoder";
+import { redact } from "../proxy/environment.js";
+export function npmRunner(env) {
+    const childEnv = Object.fromEntries(Object.entries(env).filter(([key]) => key.toLowerCase() !== "npm_config_update_notifier"));
+    childEnv.npm_config_update_notifier = "false";
+    return (args, stream = false) => new Promise((resolve, reject) => {
+        const child = spawn("npm", args, { env: childEnv, stdio: ["inherit", "pipe", "pipe"], windowsHide: true });
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        let oversized = false;
+        const forwardInterrupt = () => child.kill("SIGINT");
+        const forwardTerminate = () => child.kill("SIGTERM");
+        process.once("SIGINT", forwardInterrupt);
+        process.once("SIGTERM", forwardTerminate);
+        const timer = setTimeout(() => { timedOut = true; child.kill(); }, stream ? 600_000 : 60_000);
+        const cleanup = () => {
+            clearTimeout(timer);
+            process.removeListener("SIGINT", forwardInterrupt);
+            process.removeListener("SIGTERM", forwardTerminate);
+        };
+        const wire = (readable, destination, output) => {
+            const decoder = new StringDecoder("utf8");
+            let pending = "";
+            readable.on("data", (chunk) => {
+                const text = decoder.write(chunk);
+                if (output === "stdout")
+                    stdout += text;
+                else
+                    stderr += text;
+                if (stdout.length + stderr.length > 4_000_000) {
+                    oversized = true;
+                    child.kill();
+                    return;
+                }
+                if (!stream)
+                    return;
+                pending += text;
+                const end = pending.lastIndexOf("\n");
+                if (end >= 0) {
+                    destination.write(redact(pending.slice(0, end + 1)));
+                    pending = pending.slice(end + 1);
+                }
+            });
+            readable.on("end", () => { if (stream)
+                destination.write(redact(pending + decoder.end())); });
+        };
+        wire(child.stdout, process.stdout, "stdout");
+        wire(child.stderr, process.stderr, "stderr");
+        child.once("error", () => { cleanup(); reject(new Error("无法启动 npm，请确认 npm 已安装并位于 PATH 中。")); });
+        child.once("close", (code, signal) => {
+            cleanup();
+            if (timedOut)
+                reject(new Error("npm 操作超时。"));
+            else if (oversized)
+                reject(new Error("npm 输出超出限制。"));
+            else if (code !== 0)
+                reject(new Error(`npm 操作失败（${signal ?? code}）。${stream ? "" : `\n${redact(stderr).trim()}`}`));
+            else
+                resolve(stdout.trim());
+        });
+    });
+}

package/dist/installation/types.d.ts

@@ -0,0 +1,4 @@
+export interface NpmAgentInstaller {
+    packageName: string;
+    entryPoint: string;
+}

package/dist/installation/types.js

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

package/dist/proxy/environment.d.ts

@@ -0,0 +1,3 @@
+import type { Config } from "../config/schema.js";
+export declare function installationEnvironment(config: Config, override?: string, base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function redact(text: string): string;

package/dist/proxy/environment.js

@@ -0,0 +1,37 @@
+import { proxyUrlSchema } from "../config/schema.js";
+export function installationEnvironment(config, override, base = process.env) {
+    const proxy = override ?? config.proxy;
+    const env = { ...base };
+    if (proxy === undefined)
+        return env;
+    proxyUrlSchema.parse(proxy);
+    const replaced = new Set(["http_proxy", "https_proxy", "all_proxy", "npm_config_proxy", "npm_config_https_proxy"]);
+    if (config.no_proxy.length)
+        for (const name of ["no_proxy", "npm_config_noproxy"])
+            replaced.add(name);
+    for (const name of Object.keys(env))
+        if (replaced.has(name.toLowerCase()))
+            delete env[name];
+    Object.assign(env, {
+        HTTP_PROXY: proxy, HTTPS_PROXY: proxy, http_proxy: proxy, https_proxy: proxy,
+        npm_config_proxy: proxy, npm_config_https_proxy: proxy,
+    });
+    if (config.no_proxy.length) {
+        const bypass = config.no_proxy.join(",");
+        Object.assign(env, { NO_PROXY: bypass, no_proxy: bypass, npm_config_noproxy: bypass });
+    }
+    return env;
+}
+export function redact(text) {
+    return text.replace(/https?:\/\/[^\s<>"']+/gi, (value) => {
+        try {
+            const url = new URL(value);
+            if (!url.username && !url.password)
+                return value;
+            return `${url.protocol}//REDACTED:REDACTED@${url.host}${url.pathname}${url.search}${url.hash}`;
+        }
+        catch {
+            return value.replace(/\/\/[^/]*@/, "//REDACTED@");
+        }
+    });
+}

package/docs/configuration.md

@@ -1,6 +1,6 @@
-# 配置功能设计
+# 配置功能
 
-状态：已定义 TypeScript / Zod 数据模型和 TOML 示例。文件读写、`config` 命令、`install` 命令及代理注入尚未实现；本文件中的命令是拟实现的接口。
+从 `0.2.0` 起提供 TOML 配置读写、`config` 命令、Codex 安装/更新及工具自身更新。
 
 ## 文件位置与格式
 
@@ -47,10 +47,13 @@ const defaults = configSchema.parse({});
 agent-helper config
 
 # 设置默认安装代理
-agent-helper config set proxy http://127.0.0.1:7890
+agent-helper config set proxy=http://127.0.0.1:7890
 
-# 数组通过多个参数设置，每个参数对应一条规则
-agent-helper config set no_proxy localhost 127.0.0.1 ::1
+# 数组在命令中用逗号分隔，文件中保存为 TOML 数组
+agent-helper config set no_proxy=localhost,127.0.0.1,::1
+
+# 同时设置多个字段，全部验证通过后才写入
+agent-helper config set proxy=http://127.0.0.1:7890 no_proxy=localhost,127.0.0.1
 
 # 删除代理配置，恢复继承安装工具原有配置
 agent-helper config unset proxy
@@ -59,7 +62,7 @@ agent-helper config unset proxy
 agent-helper config unset no_proxy
 ```
 
-可写配置键由 `configKeySchema` 限定为 `proxy` 和 `no_proxy`。`set proxy` 要求一个字符串值；`set no_proxy` 要求至少一个条目，需要恢复默认空数组时使用 `unset`。写入前应校验修改后的整份配置，而不只是当前字段。帮助文本应列出允许的键、值类型、默认行为、配置路径和示例。
+可写配置键由 `configKeySchema` 限定为 `proxy` 和 `no_proxy`。每个赋值只按第一个等号拆分；代理密码中的等号会保留。重复键、未知键、空值及无效类型会报错。`no_proxy` 要求至少一个条目，需要恢复默认空数组时使用 `unset`。写入前校验修改后的整份配置，而不只是当前字段。`config --help` 列出配置路径、键类型和示例。
 
 `config` 展示配置文件中的值及内置默认值，不将安装工具或当前环境中的代理误标成已保存配置。代理认证信息必须脱敏，包括用户名与密码；`--json` 等将来新增的展示方式也遵循此规则。
 
@@ -73,16 +76,17 @@ agent-helper config unset no_proxy
 
 前两项命中时，安装适配器为本次子进程设置对应代理参数及环境变量，不修改系统代理或安装工具的全局配置。此时，非空 `no_proxy` 明确替换工具继承的绕过规则；空数组不注入绕过规则，保留工具已有设置。代理都未显式指定时，不单独应用 helper 的 `no_proxy`。
 
-`no_proxy` 不宣称统一不同工具对域名、端口、通配符和 CIDR 的匹配语义。适配器必须验证或拒绝其不支持的规则；不能静默忽略并宣称代理已正确应用。首版 URL 模型仅支持 HTTP/HTTPS；其他协议应在安装器支持后再扩展。
+当前安装器仅支持 npm：`no_proxy` 转换为逗号分隔的 `NO_PROXY` / `no_proxy` 和 `npm_config_noproxy`，具体规则的匹配行为由 npm 决定。模型验证非空、无逗号的条目，不宣称各种工具对通配符或 CIDR 的语义一致。首版代理 URL 仅支持 HTTP/HTTPS。
 
 ## 读写要求
 
 - 文件不存在时返回内置默认值；只查看配置不会创建目录或文件。
 - 第一次 `set` 才创建目录与配置文件，写入 `version = 1`。
 - 文件存在但 TOML 语法或数据校验失败时，报告文件位置和字段错误，停止修改，不覆盖原文件。
-- 错误信息和展示结果不得输出包含认证信息的原始 URL。
-- `set` / `unset` 需要使用能保留注释和原有顺序的编辑方式；只解析后重新 stringify 整份文件不能满足要求。
-- 在同目录写入临时文件并原子替换，失败时保留原文件；写入前检查源文件是否变化，避免覆盖外部并发修改。
+- 错误信息和展示结果对代理 URL 中的账号与密码脱敏。文件保存真实 URL，初次创建使用当前用户私有权限（POSIX 为目录 0700、文件 0600；Windows 实际访问权限由系统 ACL 决定）。
+- `set` / `unset` 根据 TOML AST 的范围修改目标值，保留注释、字段顺序和换行风格；多行数组内的注释也保留。`config` 输出的是经过脱敏并补齐默认值的 TOML，不复刻原文件排版。
+- 使用独占 `.lock` 文件协调 helper 写入，在同目录写临时文件并原子替换；写入前检查原文是否变化。锁文件存在时停止操作；若进程异常退出留下锁，确认没有写入进程后可手工删除锁文件。外部编辑器不参与 helper 的锁，原文检查不能彻底消除所有外部写入竞态。
+- 配置文件为符号链接时允许读取，但拒绝通过 helper 修改，提示直接编辑目标文件。
 - 未知字段、未知版本的文件可以由用户手动维护，但当前版本拒绝修改，保留原文。
 
 文件格式版本与 npm 包版本分开维护。后续确有需求时，再为安装器参数或 agent 专属配置添加 TOML 分组及迁移规则。

package/examples/config.toml

@@ -1,5 +1,5 @@
 # 保存到 ~/.ai-agent-helper/config.toml。
-# 本示例属于配置模型设计；当前 CLI 尚未提供 config / install 命令。
+# 从 0.2.0 起提供 config / install / update 命令。
 
 # 配置文件格式版本，由 helper 管理。
 version = 1

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "ai-agent-helper",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "description": "Discover locally installed AI agent CLIs.",
+  "description": "Discover AI agent CLIs, manage TOML configuration, and install or update Codex through a proxy.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/tool-helper/ai-agent-helper.git"
@@ -53,10 +53,16 @@
     "typescript"
   ],
   "dependencies": {
+    "cross-spawn": "^7.0.6",
+    "semver": "^7.8.6",
+    "smol-toml": "^1.9.1",
+    "toml-eslint-parser": "^0.10.1",
     "zod": "^4.6.7"
   },
   "devDependencies": {
+    "@types/cross-spawn": "^6.0.6",
     "@types/node": "^22.20.5",
+    "@types/semver": "^7.8.0",
     "tsx": "^4.23.15",
     "typescript": "^7.0.2"
   }