@ai-zen/air 0.1.9 → 0.2.1

package/dist/session/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/session/shared.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAW,MAAM,qBAAqB,CAAC;AAarD,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,KAAK,CAAC;CACd;AAED,eAAO,MAAM,aAAa,QAcd,CAAC;AAEb,wBAAsB,UAAU,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAI/D;AAgCD,wBAAsB,GAAG,CAAC,GAAG,EAAE,UAAU,iBAaxC"}

package/dist/session/shared.js

@@ -0,0 +1,77 @@
+import { Message } from "@ai-zen/agents-core";
+import inquirer from "inquirer";
+import { saveMessages } from "../config.js";
+import { buildAgent } from "../agent-factory.js";
+import { handleMessage } from "./message.js";
+import { cmdExit } from "./commands/exit.js";
+import { cmdHelp } from "./commands/help.js";
+import { cmdSave } from "./commands/save.js";
+import { cmdNew } from "./commands/new.js";
+import { cmdLoad } from "./commands/load.js";
+import { cmdEditor } from "./commands/editor.js";
+import { cmdBack } from "./commands/back.js";
+export const SYSTEM_PROMPT = [
+    "你是一个AI助手，专门帮助用户回答问题和执行任务。请用中文回复。",
+    "",
+    "## 行为准则",
+    "1. 做任何改动之前，必须先跟用户商量，获得明确指示之后再行动。",
+    "2. 用户没有明确要求产出文件时，不得自行创建任何文件到项目中。讨论就停留在讨论层面。",
+    "3. 区分危险操作：删除文件、覆盖文件、安装卸载软件、修改系统配置、执行耗时任务等属于危险操作。执行前必须评估影响范围，并向用户说明风险，获得用户明确的书面的确认之后再执行。",
+    "4. 追责原则：你的每一步操作都应当基于用户的明确指令。如果出了问题，可以从用户说过的话追溯责任——是用户让你做的，用户承担责任。所以你不需要畏手畏脚，只要用户明确说了\u201c做\u201d，你就放心去做。",
+    "",
+    "## 记忆",
+    "你可以使用 shell 工具执行任何命令。如果你有需要长期记住的信息（用户偏好、项目约定、任务进度等），请写入以下位置：",
+    "- 全局记忆: ~/.ai-zen/air/temp/*.md",
+    "- 项目记忆: $(cwd)/.ai-zen/air/temp/*.md",
+    "下次启动时用 shell 读取即可。这是你唯一的记忆方式。",
+].join("\n");
+export async function saveAndNew(ctx) {
+    const msgs = [Message.System(SYSTEM_PROMPT)];
+    saveMessages(msgs);
+    ctx.agent = await buildAgent(msgs);
+}
+async function dispatchCommand(ctx, cmd) {
+    switch (cmd) {
+        case "/exit":
+        case "/quit":
+            cmdExit(ctx);
+            break;
+        case "/save":
+            await cmdSave(ctx);
+            break;
+        case "/new":
+            await cmdNew(ctx);
+            break;
+        case "/load":
+            await cmdLoad(ctx);
+            break;
+        case "/back":
+            await cmdBack(ctx);
+            break;
+        case "/editor":
+            await cmdEditor(ctx);
+            break;
+        case "/help":
+            cmdHelp();
+            break;
+        default:
+            console.log(`\n❌ 未知命令: ${cmd}\n`);
+            break;
+    }
+}
+export async function ask(ctx) {
+    while (true) {
+        const { input } = await inquirer.prompt([
+            { type: "input", name: "input", message: "你:" },
+        ]);
+        const t = input.trim();
+        if (!t)
+            continue;
+        if (t.startsWith("/")) {
+            await dispatchCommand(ctx, t.toLowerCase());
+            continue;
+        }
+        await handleMessage(ctx, t);
+    }
+}
+//# sourceMappingURL=shared.js.map

package/dist/session/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../src/session/shared.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,QAAQ,MAAM,UAAU,CAAC;AAChC,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAM7C,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,kCAAkC;IAClC,EAAE;IACF,SAAS;IACT,kCAAkC;IAClC,6CAA6C;IAC7C,yFAAyF;IACzF,2GAA2G;IAC3G,EAAE;IACF,OAAO;IACP,8DAA8D;IAC9D,iCAAiC;IACjC,sCAAsC;IACtC,+BAA+B;CAChC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,GAAe;IAC9C,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC;IAC7C,YAAY,CAAC,IAAI,CAAC,CAAC;IACnB,GAAG,CAAC,KAAK,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC;AACrC,CAAC;AAED,KAAK,UAAU,eAAe,CAAC,GAAe,EAAE,GAAW;IACzD,QAAQ,GAAG,EAAE,CAAC;QACZ,KAAK,OAAO,CAAC;QACb,KAAK,OAAO;YACV,OAAO,CAAC,GAAG,CAAC,CAAC;YACb,MAAM;QACR,KAAK,OAAO;YACV,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;YACnB,MAAM;QACR,KAAK,MAAM;YACT,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC;YAClB,MAAM;QACR,KAAK,OAAO;YACV,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;YACnB,MAAM;QACR,KAAK,OAAO;YACV,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;YACnB,MAAM;QACR,KAAK,SAAS;YACZ,MAAM,SAAS,CAAC,GAAG,CAAC,CAAC;YACrB,MAAM;QACR,KAAK,OAAO;YACV,OAAO,EAAE,CAAC;YACV,MAAM;QACR;YACE,OAAO,CAAC,GAAG,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;YAClC,MAAM;IACV,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,GAAG,CAAC,GAAe;IACvC,OAAO,IAAI,EAAE,CAAC;QACZ,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC;YACtC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE;SAChD,CAAC,CAAC;QACH,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QACvB,IAAI,CAAC,CAAC;YAAE,SAAS;QACjB,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACtB,MAAM,eAAe,CAAC,GAAG,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;YAC5C,SAAS;QACX,CAAC;QACD,MAAM,aAAa,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IAC9B,CAAC;AACH,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ai-zen/air",
-  "version": "0.1.9",
-  "description": "极简 AI 命令行助手",
+  "version": "0.2.1",
+  "description": "Minimalist AI CLI assistant \u2014 one shell tool, filesystem memory, auto context migration",
   "type": "module",
   "main": "./dist/agent-runtime.js",
   "bin": {
@@ -25,5 +25,14 @@
     "@types/node": "^24.12.2",
     "typescript": "^5.3.3",
     "vitest": "^4.1.9"
-  }
+  },
+  "keywords": [
+    "ai",
+    "cli",
+    "assistant",
+    "shell",
+    "deepseek",
+    "terminal",
+    "command-line"
+  ]
 }

package/src/__tests__/e2e.test.ts

@@ -0,0 +1,187 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, rmSync, mkdirSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+// ==================== Helpers ====================
+
+const CLI = join(process.cwd(), "dist", "cli.js");
+
+interface CliResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+function runCli(args: string[], stdinInput?: string, extraEnv?: Record<string, string>): Promise<CliResult> {
+  return new Promise((resolve) => {
+    const env = {
+      ...process.env,
+      ...extraEnv,
+    };
+
+    const proc = spawn("node", [CLI, ...args], { env, stdio: ["pipe", "pipe", "pipe"] });
+
+    let stdout = "";
+    let stderr = "";
+
+    proc.stdout.on("data", (data: Buffer) => { stdout += data.toString(); });
+    proc.stderr.on("data", (data: Buffer) => { stderr += data.toString(); });
+
+    if (stdinInput !== undefined) {
+      proc.stdin.write(stdinInput);
+      proc.stdin.end();
+    }
+
+    proc.on("close", (code) => {
+      resolve({ stdout, stderr, exitCode: code ?? -1 });
+    });
+    proc.on("error", () => {
+      resolve({ stdout, stderr, exitCode: -1 });
+    });
+  });
+}
+
+let tmpDirs: string[] = [];
+
+afterAll(() => {
+  for (const d of tmpDirs) {
+    try { rmSync(d, { recursive: true, force: true }); } catch {}
+  }
+});
+
+function makeTestDir(): string {
+  const dir = join(tmpdir(), `air-e2e-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(dir, { recursive: true });
+  tmpDirs.push(dir);
+  return dir;
+}
+
+// Read API key from .env.local
+function getApiKey(): string {
+  try {
+    const envContent = readFileSync(join(process.cwd(), ".env.local"), "utf-8");
+    const match = envContent.match(/DEEPSEEK_API_KEY=(.+)/);
+    if (match) return match[1].trim();
+  } catch {}
+  return process.env.DEEPSEEK_API_KEY || "";
+}
+
+const API_KEY = getApiKey();
+
+function skipIfNoKey(ctx: any) {
+  if (!API_KEY) ctx.skip();
+}
+
+// ==================== Tests ====================
+
+describe("E2E: CLI 基本功能", () => {
+  it("air --help 显示帮助信息", async () => {
+    const result = await runCli(["--help"]);
+    expect(result.stdout).toContain("Usage:");
+    expect(result.stdout).toContain("air");
+    expect(result.exitCode).toBe(0);
+  });
+
+  it("air key <key> 设置 API Key", async () => {
+    const airDir = makeTestDir();
+    const result = await runCli(["key", "sk-test-12345"], undefined, { AIR_DIR: airDir });
+    expect(result.stdout).toContain("✅ API Key 已设置");
+
+    const configFile = join(airDir, "config.json");
+    expect(existsSync(configFile)).toBe(true);
+    const config = JSON.parse(readFileSync(configFile, "utf-8"));
+    expect(config.apiKey).toBe("sk-test-12345");
+  });
+
+  it("air config 显示配置信息", async () => {
+    const airDir = makeTestDir();
+    await runCli(["key", "sk-test-abcde"], undefined, { AIR_DIR: airDir });
+    const result = await runCli(["config"], undefined, { AIR_DIR: airDir });
+    expect(result.stdout).toContain("API Key:");
+    expect(result.stdout).toContain("bcde");
+  });
+});
+
+
+describe("E2E: 对话命令", () => {
+  it("/save 保存快照", async (ctx) => {
+    skipIfNoKey(ctx);
+
+    const airDir = makeTestDir();
+    const env = { AIR_DIR: airDir };
+    await runCli(["key", API_KEY], undefined, env);
+
+    // 先发一条消息建立历史
+    await runCli(["测试消息"], "/exit\n", env);
+
+    // 交互模式下 /save 后 /exit
+    const result = await runCli([], "/save\n/exit\n", env);
+    expect(result.stdout).toContain("✅ 快照:");
+
+    // 验证快照文件被创建
+    const snapDir = join(airDir, "snapshots");
+    const files = readdirSync(snapDir).filter((f) => f.endsWith(".json"));
+    expect(files.length).toBeGreaterThanOrEqual(1);
+  }, 30000);
+});
+
+describe("E2E: 真实 API 对话", () => {
+  it("air <message> 发送消息并接收真实回复", async (ctx) => {
+    skipIfNoKey(ctx);
+
+    const airDir = makeTestDir();
+    const env = { AIR_DIR: airDir };
+
+    // Set up real key
+    await runCli(["key", API_KEY], undefined, env);
+
+    // Send a simple message, pipe /exit to leave interactive mode
+    const result = await runCli(["用一句话介绍你自己"], "/exit\n", env);
+
+    // Should have AI response
+    expect(result.stdout).toContain("🤖 AI:");
+    // Should have some actual content (not empty)
+    expect(result.stdout.length).toBeGreaterThan(100);
+
+    // Verify context was saved with user message + AI response
+    const contextFile = join(airDir, "context.json");
+    expect(existsSync(contextFile)).toBe(true);
+    const msgs = JSON.parse(readFileSync(contextFile, "utf-8"));
+    expect(msgs.length).toBeGreaterThanOrEqual(2);
+    expect(msgs[1].role).toBe("user");
+    expect(msgs[1].content).toBe("用一句话介绍你自己");
+
+    // Verify there's an assistant response
+    const assistantMsg = msgs.find((m: any) => m.role === "assistant");
+    expect(assistantMsg).toBeTruthy();
+    expect(assistantMsg.content.length).toBeGreaterThan(10);
+  }, 30000);  // 30s timeout for real API
+
+  it("/new 命令重置对话", async (ctx) => {
+    skipIfNoKey(ctx);
+
+    const airDir = makeTestDir();
+    const env = { AIR_DIR: airDir };
+
+    await runCli(["key", API_KEY], undefined, env);
+
+    // Send a message to create history
+    await runCli(["第一轮消息"], "/exit\n", env);
+
+    // Verify there's history
+    let contextFile = join(airDir, "context.json");
+    let msgs = JSON.parse(readFileSync(contextFile, "utf-8"));
+    expect(msgs.length).toBeGreaterThanOrEqual(2);
+
+    // Interactive mode: /new then exit
+    const result = await runCli([], "/new\n/exit\n", env);
+    expect(result.stdout).toContain("🆕 重新开始");
+
+    // Verify context was reset
+    msgs = JSON.parse(readFileSync(contextFile, "utf-8"));
+    expect(msgs.length).toBe(1);
+    expect(msgs[0].role).toBe("system");
+  }, 30000);
+});

package/src/__tests__/session.test.ts

@@ -0,0 +1,147 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import type { SessionCtx } from "../session/shared.js";
+
+// Mock all external dependencies
+vi.mock("inquirer", () => ({ default: { prompt: vi.fn() } }));
+vi.mock("../config.js", () => ({
+  saveMessages: vi.fn(),
+  saveSnapshot: vi.fn(() => "snapshot-123"),
+  listSnapshots: vi.fn(() => []),
+  loadSnapshot: vi.fn(() => []),
+}));
+vi.mock("../agent-factory.js", () => ({
+  buildAgent: vi.fn(async () => ({
+    messages: [],
+    events: { on: vi.fn(), off: vi.fn() },
+    send: vi.fn(),
+  })),
+}));
+vi.mock("../session/print.js", () => ({
+  sendAndPrint: vi.fn(),
+}));
+
+const mockPrompt = vi.mocked((await import("inquirer")).default.prompt);
+const { saveMessages, saveSnapshot, listSnapshots, loadSnapshot } = await import("../config.js");
+const { buildAgent } = await import("../agent-factory.js");
+
+function makeCtx(msgs: any[] = []): SessionCtx {
+  return { agent: { messages: msgs, events: { on: vi.fn(), off: vi.fn() }, send: vi.fn() } as any };
+}
+
+// ==================== shared.ts ====================
+
+describe("saveAndNew", () => {
+  it("写入 system prompt 并构建 agent", async () => {
+    const { saveAndNew } = await import("../session/shared.js");
+    const ctx = makeCtx();
+
+    await saveAndNew(ctx);
+
+    expect(saveMessages).toHaveBeenCalledWith(
+      expect.arrayContaining([expect.objectContaining({ role: "system" })])
+    );
+    expect(buildAgent).toHaveBeenCalled();
+    expect(ctx.agent).toBeTruthy();
+  });
+});
+
+// ==================== dispatchCommand 路由 ====================
+
+describe("dispatchCommand", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('"/exit" 调用 cmdExit（process.exit）', async () => {
+    // Can't easily test process.exit, just verify it doesn't throw
+    const { runConversation } = await import("../session/runtime.js");
+    // dispatchCommand is internal, tested via routing only
+  });
+
+  it('"/save" 调用 cmdSave', async () => {
+    const { cmdSave } = await import("../session/commands/save.js");
+    const ctx = makeCtx([{ role: "system", content: "sys" }]);
+    await cmdSave(ctx);
+    expect(saveSnapshot).toHaveBeenCalledWith(ctx.agent.messages);
+  });
+
+  it('"/new" 调用 cmdNew 并打印提示', async () => {
+    const { cmdNew } = await import("../session/commands/new.js");
+    const ctx = makeCtx();
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    await cmdNew(ctx);
+    expect(spy).toHaveBeenCalledWith("\n🆕 重新开始\n");
+    spy.mockRestore();
+  });
+
+  it('"/help" 打印帮助信息', async () => {
+    const { cmdHelp } = await import("../session/commands/help.js");
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    cmdHelp();
+    expect(spy).toHaveBeenCalled();
+    spy.mockRestore();
+  });
+});
+
+// ==================== cmdBack ====================
+
+describe("cmdBack", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("没有消息时提示无可撤回", async () => {
+    const { cmdBack } = await import("../session/commands/back.js");
+    const ctx = makeCtx([{ role: "system", content: "sys" }]);
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    await cmdBack(ctx);
+    expect(spy).toHaveBeenCalledWith("\n❌ 还没有消息可以撤回\n");
+    spy.mockRestore();
+  });
+
+  it("取消操作时不修改消息", async () => {
+    const { cmdBack } = await import("../session/commands/back.js");
+    const msgs = [
+      { role: "system", content: "sys" },
+      { role: "user", content: "你好" },
+    ];
+    const ctx = makeCtx(msgs);
+    mockPrompt.mockResolvedValueOnce({ selectedIndex: -1 });
+    await cmdBack(ctx);
+    expect(ctx.agent.messages.length).toBe(2);
+  });
+});
+
+// ==================== cmdLoad ====================
+
+describe("cmdLoad", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("没有快照时提示", async () => {
+    const { cmdLoad } = await import("../session/commands/load.js");
+    const ctx = makeCtx();
+    vi.mocked(listSnapshots).mockReturnValueOnce([]);
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    await cmdLoad(ctx);
+    expect(spy).toHaveBeenCalledWith("\n📭 没有可用的快照\n");
+    spy.mockRestore();
+  });
+});
+
+// ==================== cmdEditor ====================
+
+describe("cmdEditor", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("取消编辑不报错", async () => {
+    const { cmdEditor } = await import("../session/commands/editor.js");
+    const ctx = makeCtx();
+    mockPrompt.mockResolvedValueOnce({ content: "" });
+    await cmdEditor(ctx);
+    expect(saveMessages).not.toHaveBeenCalled();
+  });
+});

package/src/agent-factory.ts

@@ -4,7 +4,7 @@ import { readConfig } from "./config.js";
 import { shellTool } from "./tools.js";
 
 const MODEL_NAME = "deepseek-v4-flash";
-const API_ENDPOINT = "https://api.deepseek.com/v1";
+const API_ENDPOINT = process.env.AIR_API_ENDPOINT || "https://api.deepseek.com/v1";
 
 async function buildModel(apiKey: string) {
   const endpoint = new OpenAI({ openai_endpoint: API_ENDPOINT, api_key: apiKey });

package/src/cli.ts

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
 import { Command } from "commander";
-import { runConversation } from "./agent-runtime.js";
+import { runConversation } from "./session/runtime.js";
+import { installHook, uninstallHook } from "./hook.js";
 import { readConfig, saveConfig } from "./config.js";
 
 const { version } = JSON.parse(
@@ -34,15 +35,29 @@ program
   });
 
 program
-  .argument("[message]", "要发送的消息（不传则进入交互模式）")
-  .action(async (message?: string) => {
+  .command("hook")
+  .description("安装/卸载兜底终端钩子（命令不存在时自动转发到 air）")
+  .argument("<action>", "install 或 uninstall")
+  .action((action: string) => {
+    if (action === "install") {
+      installHook();
+    } else if (action === "uninstall") {
+      uninstallHook();
+    } else {
+      console.error('❌ 未知操作，请使用 install 或 uninstall');
+    }
+  });
+
+program
+  .argument("[message...]", "要发送的消息（不传则进入交互模式）")
+  .action(async (message?: string[]) => {
     const config = readConfig();
     if (!config.apiKey) {
       console.error("❌ 请先设置 API Key: air key <your-key>");
       console.error("   获取 Key: https://platform.deepseek.com/api_keys");
       process.exit(1);
     }
-    await runConversation(message);
+    await runConversation(message?.join(" "));
   });
 
 program.parse(process.argv);

package/src/config.ts

@@ -10,7 +10,7 @@ export interface Config {
 
 // ==================== 路径 ====================
 
-const AIR_DIR = () => join(homedir(), ".ai-zen", "air");
+const AIR_DIR = () => process.env.AIR_DIR || join(homedir(), ".ai-zen", "air");
 const CONFIG_FILE = () => join(AIR_DIR(), "config.json");
 const CONTEXT_FILE = () => join(AIR_DIR(), "context.json");
 const SNAPSHOTS_DIR = () => join(AIR_DIR(), "snapshots");

package/src/hook.ts

@@ -0,0 +1,93 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { existsSync, readFileSync, writeFileSync, appendFileSync } from "node:fs";
+
+const MARKER_START = "# === air hook (开始) ===";
+const MARKER_END = "# === air hook (结束) ===";
+
+function detectShell(): { rcFile: string; hookFn: string } | null {
+  const shell = process.env.SHELL || "";
+  const home = homedir();
+
+  if (shell.includes("zsh")) {
+    return { rcFile: join(home, ".zshrc"), hookFn: "command_not_found_handler" };
+  }
+  if (shell.includes("bash")) {
+    return { rcFile: join(home, ".bashrc"), hookFn: "command_not_found_handle" };
+  }
+  return null;
+}
+
+function hookCode(hookFn: string): string {
+  return [
+    "",
+    MARKER_START,
+    `${hookFn}() {`,
+    '  air "$@"',
+    "}",
+    MARKER_END,
+    "",
+  ].join("\n");
+}
+
+function isInstalled(rcFile: string): boolean {
+  if (!existsSync(rcFile)) return false;
+  const content = readFileSync(rcFile, "utf-8");
+  return content.includes(MARKER_START);
+}
+
+export function installHook(): void {
+  const shell = detectShell();
+  if (!shell) {
+    console.error("❌ 不支持的 shell（仅支持 bash / zsh）");
+    process.exit(1);
+  }
+
+  if (isInstalled(shell.rcFile)) {
+    console.log("ℹ️  air hook 已安装，无需重复操作");
+    return;
+  }
+
+  appendFileSync(shell.rcFile, hookCode(shell.hookFn), "utf-8");
+  console.log(`✅ air hook 已安装到 ${shell.rcFile}`);
+  console.log(`   重启终端或执行 source ${shell.rcFile} 即可生效`);
+}
+
+export function uninstallHook(): void {
+  const shell = detectShell();
+  if (!shell) {
+    console.error("❌ 不支持的 shell（仅支持 bash / zsh）");
+    process.exit(1);
+  }
+
+  if (!existsSync(shell.rcFile)) {
+    console.log("ℹ️  air hook 未安装（文件不存在）");
+    return;
+  }
+
+  const content = readFileSync(shell.rcFile, "utf-8");
+  if (!content.includes(MARKER_START)) {
+    console.log("ℹ️  air hook 未安装");
+    return;
+  }
+
+  const lines = content.split("\n");
+  const newLines: string[] = [];
+  let skipping = false;
+  for (const line of lines) {
+    if (line.trim() === MARKER_START) {
+      skipping = true;
+      continue;
+    }
+    if (line.trim() === MARKER_END) {
+      skipping = false;
+      continue;
+    }
+    if (!skipping) {
+      newLines.push(line);
+    }
+  }
+
+  writeFileSync(shell.rcFile, newLines.join("\n"), "utf-8");
+  console.log(`✅ air hook 已从 ${shell.rcFile} 卸载`);
+}