@ai-zen/air 0.1.9 → 0.2.1

package/README.md

@@ -1,16 +1,16 @@
 # air
 
-用 1% 的功能完成 99% 的事情。
+> Do 99% of things with 1% of the features.
 
-一个极简的 AI 命令行助手。只有一个 shell 工具，AI 自己用文件系统记东西，上下文满了自动迁移。
+A minimalist AI CLI assistant. Just one shell tool — the AI remembers things by writing to the filesystem, and automatically migrates context when it gets too long.
 
-## 安装
+## Installation
 
 ```bash
-# 全局安装（推荐）
+# Global install (recommended)
 npm install -g @ai-zen/air
 
-# 或从源码构建
+# Or build from source
 git clone git@github.com:ai-zen/air.git
 cd air
 npm install
@@ -18,72 +18,89 @@ npm run build
 npm install -g .
 ```
 
-## 使用
+## Usage
 
 ```bash
-# 设置 API Key（DeepSeek）
+# Set API Key (DeepSeek)
 air key sk-xxxxxxxxxxxxxxxx
 
-# 交互模式（自动恢复上次对话）
+# Interactive mode (auto-resumes last conversation)
 air
 
-# 直接发一条消息
-air 用 shell 帮我看看当前目录有哪些文件
+# One-shot message
+air use shell to list files in current directory
 
-# 查看配置
+# View config
 air config
+
+# Install fallback hook (redirects unknown commands to air)
+air hook install
+
+# Uninstall fallback hook
+air hook uninstall
 ```
 
-### 交互命令
+### Interactive Commands
+
+| Command | Description |
+|---------|-------------|
+| `/exit` `/quit` | Exit |
+| `/save` | Save snapshot |
+| `/load` | Load snapshot |
+| `/new` | Clear context and start fresh |
+| `/back` | Recall a message (optionally edit and resend) |
+| `/editor` | Open system editor for multi-line input |
+| `/help` | Help |
+
+### Fallback Terminal Hook
 
-| 命令 | 说明 |
-|------|------|
-| `/exit` `/quit` | 退出 |
-| `/save` | 保存快照 |
-| `/load` | 加载快照 |
-| `/new` | 清空上下文重新开始 |
-| `/back` | 撤回消息（可选修改后重发） |
-| `/editor` | 打开系统编辑器输入多行文本 |
-| `/help` | 帮助 |
+When installed, any command that doesn't exist in your shell gets automatically forwarded to `air`. The AI will interpret what you meant and help you out.
+
+```bash
+$ gred "hello" file.txt
+# → command not found → auto-redirects to air
+# → AI: "Did you mean grep?"
+```
 
-## 设计
+## Design
 
 ```
 ~/.ai-zen/air/
 ├── config.json       # { "apiKey": "sk-xxx" }
-├── context.json      # [ { role, content }, ... ]    当前对话
-├── snapshots/        # /save 或迁移前自动快照
-└── temp/             # AI 自己写入的长期记忆 (*.md)
+├── context.json      # [ { role, content }, ... ]    Current conversation
+├── snapshots/        # Auto snapshots before migration or /save
+└── temp/             # Long-term memory written by AI (*.md)
 ```
 
-### 核心理念
+### Core Philosophy
 
-- **模型**: DeepSeek-V4-Flash（写死，只有一个）
-- **工具**: 只有一个 `shell`，AI 用它执行命令、读写文件
-- **记忆**: AI 自己决定记什么，用 shell 写入 `temp/*.md`，下次启动时读取。air 不做额外的持久化机制
-- **上下文**: JSON 序列化后超过 50 万字符自动迁移，迁移前拍快照
-- **行为准则**: 先商量再动手，危险操作必须获得用户书面确认。追责原则——每一步基于用户指令，用户承担责任
+- **Model**: DeepSeek-V4-Flash (hardcoded, only one)
+- **Tool**: Just one `shell` tool — the AI executes commands, reads and writes files through it
+- **Memory**: The AI decides what to remember, writes to `temp/*.md` via shell, reads on next startup. No extra persistence mechanism
+- **Context**: Auto-migrates when JSON serialization exceeds 500K chars, takes a snapshot before migration
+- **Rules**: Consult the user before making changes. Dangerous operations require explicit written confirmation. The user takes responsibility for their own instructions
 
-## 项目结构
+## Project Structure
 
 ```
 src/
-├── cli.ts              # CLI 入口，commander (48行)
-├── config.ts           # 配置与文件读写 (109行)
-├── delta-renderer.ts   # 流式渲染器 (126行，复用自 agents 项目)
-├── tools.ts            # 工具定义——shell (23行)
-├── agent-factory.ts    # Agent 工厂——构建模型与 Agent (23行)
-├── migration.ts        # 上下文计数与任务迁移 (72行)
-├── agent-runtime.ts    # 运行时——对话循环与命令处理 (256行)
+├── cli.ts              # CLI entry, commander
+├── config.ts           # Config read/write
+├── delta-renderer.ts   # Stream renderer (from agents project)
+├── tools.ts            # Tool definitions — shell
+├── agent-factory.ts    # Agent factory — build model & agent
+├── migration.ts        # Context counting & migration
+├── agent-runtime.ts    # Runtime — conversation loop & commands
+├── hook.ts             # Fallback terminal hook (install/uninstall)
 └── __tests__/
-    ├── config.test.ts  # 配置/上下文/快照测试 (110行)
-    ├── main.test.ts    # contextSize/shouldMigrate 测试 (43行)
-    └── tools.test.ts   # shell 工具结构测试 (15行)
+    ├── config.test.ts  # Config/context/snapshot tests
+    ├── main.test.ts    # contextSize/shouldMigrate tests
+    └── tools.test.ts   # Shell tool structure tests
 ```
 
-共 40 KB，826 行。
+~46 KB, 870 lines.
 
-## 测试
+## Tests
 
 ```bash
 npm test

package/README.zh.md

@@ -0,0 +1,97 @@
+# air
+
+用 1% 的功能完成 99% 的事情。
+
+一个极简的 AI 命令行助手。只有一个 shell 工具，AI 自己用文件系统记东西，上下文满了自动迁移。
+
+## 安装
+
+```bash
+# 全局安装（推荐）
+npm install -g @ai-zen/air
+
+# 或从源码构建
+git clone git@github.com:ai-zen/air.git
+cd air
+npm install
+npm run build
+npm install -g .
+```
+
+## 使用
+
+```bash
+# 设置 API Key（DeepSeek）
+air key sk-xxxxxxxxxxxxxxxx
+
+# 交互模式（自动恢复上次对话）
+air
+
+# 直接发一条消息
+air 用 shell 帮我看看当前目录有哪些文件
+
+# 查看配置
+air config
+
+# 安装兜底终端钩子（命令不存在时自动转发到 air）
+air hook install
+
+# 卸载兜底终端钩子
+air hook uninstall
+```
+
+### 交互命令
+
+| 命令 | 说明 |
+|------|------|
+| `/exit` `/quit` | 退出 |
+| `/save` | 保存快照 |
+| `/load` | 加载快照 |
+| `/new` | 清空上下文重新开始 |
+| `/back` | 撤回消息（可选修改后重发） |
+| `/editor` | 打开系统编辑器输入多行文本 |
+| `/help` | 帮助 |
+
+## 设计
+
+```
+~/.ai-zen/air/
+├── config.json       # { "apiKey": "sk-xxx" }
+├── context.json      # [ { role, content }, ... ]    当前对话
+├── snapshots/        # /save 或迁移前自动快照
+└── temp/             # AI 自己写入的长期记忆 (*.md)
+```
+
+### 核心理念
+
+- **模型**: DeepSeek-V4-Flash（写死，只有一个）
+- **工具**: 只有一个 `shell`，AI 用它执行命令、读写文件
+- **记忆**: AI 自己决定记什么，用 shell 写入 `temp/*.md`，下次启动时读取。air 不做额外的持久化机制
+- **上下文**: JSON 序列化后超过 50 万字符自动迁移，迁移前拍快照
+- **行为准则**: 先商量再动手，危险操作必须获得用户书面确认。追责原则——每一步基于用户指令，用户承担责任
+
+## 项目结构
+
+```
+src/
+├── cli.ts              # CLI 入口，commander
+├── config.ts           # 配置与文件读写
+├── delta-renderer.ts   # 流式渲染器（复用自 agents 项目）
+├── tools.ts            # 工具定义——shell
+├── agent-factory.ts    # Agent 工厂——构建模型与 Agent
+├── migration.ts        # 上下文计数与任务迁移
+├── agent-runtime.ts    # 运行时——对话循环与命令处理
+├── hook.ts             # 兜底终端钩子（install/uninstall）
+└── __tests__/
+    ├── config.test.ts  # 配置/上下文/快照测试
+    ├── main.test.ts    # contextSize/shouldMigrate 测试
+    └── tools.test.ts   # shell 工具结构测试
+```
+
+共 46 KB，870 行。
+
+## 测试
+
+```bash
+npm test
+```

package/dist/agent-factory.js

@@ -2,7 +2,7 @@ import { Agent, Message, OpenAI, ChatGPT } from "@ai-zen/agents-core";
 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) {
     const endpoint = new OpenAI({ openai_endpoint: API_ENDPOINT, api_key: apiKey });
     return new ChatGPT({

package/dist/agent-factory.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-factory.js","sourceRoot":"","sources":["../src/agent-factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEtE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,MAAM,UAAU,GAAG,mBAAmB,CAAC;AACvC,MAAM,YAAY,GAAG,6BAA6B,CAAC;AAEnD,KAAK,UAAU,UAAU,CAAC,MAAc;IACtC,MAAM,QAAQ,GAAG,IAAI,MAAM,CAAC,EAAE,eAAe,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IAChF,OAAO,IAAI,OAAO,CAAC;QACjB,YAAY,EAAE,EAAE;QAChB,cAAc,EAAE,MAAM,QAAQ,CAAC,cAAc,CAAC,UAAU,CAAC;KAC1D,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,aAAoB;IACnD,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,MAAM,KAAK,GAAG,MAAM,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC9C,MAAM,QAAQ,GAAsB,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,IAAI,aAAa;QAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7D,OAAO,IAAI,KAAK,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;AAC5D,CAAC"}
+{"version":3,"file":"agent-factory.js","sourceRoot":"","sources":["../src/agent-factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEtE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,MAAM,UAAU,GAAG,mBAAmB,CAAC;AACvC,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,6BAA6B,CAAC;AAEnF,KAAK,UAAU,UAAU,CAAC,MAAc;IACtC,MAAM,QAAQ,GAAG,IAAI,MAAM,CAAC,EAAE,eAAe,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IAChF,OAAO,IAAI,OAAO,CAAC;QACjB,YAAY,EAAE,EAAE;QAChB,cAAc,EAAE,MAAM,QAAQ,CAAC,cAAc,CAAC,UAAU,CAAC;KAC1D,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,aAAoB;IACnD,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,MAAM,KAAK,GAAG,MAAM,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC9C,MAAM,QAAQ,GAAsB,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,IAAI,aAAa;QAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7D,OAAO,IAAI,KAAK,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;AAC5D,CAAC"}

package/dist/agent-runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-runtime.d.ts","sourceRoot":"","sources":["../src/agent-runtime.ts"],"names":[],"mappings":"AAwDA,wBAAsB,eAAe,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgN5E"}
+{"version":3,"file":"agent-runtime.d.ts","sourceRoot":"","sources":["../src/agent-runtime.ts"],"names":[],"mappings":"AA0RA,wBAAsB,eAAe,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAyC5E"}