@xinshu/openagi 0.0.2-dev.2 → 0.0.2-dev.4

package/README.md

@@ -1,12 +1,10 @@
-# OpenAGI - AI Coding
+# Kode - AI Coding
+<img width="991" height="479" alt="image" src="https://github.com/user-attachments/assets/c1751e92-94dc-4e4a-9558-8cd2d058c1a1" />  <br> 
+[![npm version](https://badge.fury.io/js/@shareai-lab%2Fkode.svg)](https://www.npmjs.com/package/@shareai-lab/kode)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![AGENTS.md](https://img.shields.io/badge/AGENTS.md-Compatible-brightgreen)](https://agents.md)
 
-<div align="center">
-  <img src="./logo.svg" alt="OpenAGI Logo" width="400" />
-</div>
-
-## 🎯 项目介绍
-
-OpenAGI 是开源 AI 编程助手。采用 TypeScript + React + Ink 现代化架构，提供强大的 AI 辅助编程能力，支持文件操作、系统交互、智能搜索等丰富功能。
+[中文文档](README.zh-CN.md) | [Contributing](CONTRIBUTING.md) | [Documentation](docs/README.md)
 
 <img width="90%" alt="image" src="https://github.com/user-attachments/assets/fdce7017-8095-429d-b74e-07f43a6919e1" />
 
@@ -18,352 +16,622 @@ OpenAGI 是开源 AI 编程助手。采用 TypeScript + React + Ink 现代化架
 <img width="90%" alt="image" src="https://github.com/user-attachments/assets/b30696ce-5ab1-40a0-b741-c7ef3945dba0" />
 
 
-## 📢 更新日志
+## 📢 Update Log
+
+**2025-12-22**: Native-first distribution (Windows OOTB). Kode prefers a cached native binary and falls back to the Node.js runtime when needed. See `docs/binary-distribution.md`.
+
 
-**2025-08-29**：我们已添加 Windows 支持！所有 Windows 用户现在可以在他们的计算机上使用 Git Bash、Unix 子系统或 WSL（Windows 子系统 for Linux）运行 OpenAGI。
+## 🤝 AGENTS.md Standard Support
 
+Kode supports the [AGENTS.md standard](https://agents.md): a simple, open format for guiding coding agents, used by 60k+ open-source projects.
 
-## 🤝 AGENTS.md 标准支持
+### Full Compatibility with Multiple Standards
 
-**OpenAGI 骄傲地支持由 OpenAI 发起的 [AGENTS.md 标准协议](https://agents.md)** - 一种用于指导编程代理的简单、开放格式，已被 20k+ 开源项目使用。
+- ✅ **AGENTS.md** - Native support for the OpenAI-initiated standard format
+- ✅ **Legacy `.claude` compatibility** - Reads `.claude` directories and `CLAUDE.md` when present (see `docs/compatibility.md`)
+- ✅ **Subagent System** - Advanced agent delegation and task orchestration
+- ✅ **Cross-platform** - Works with 20+ AI models and providers
 
-### 与多种标准的完全兼容
+Use `# Your documentation request` to generate and maintain your AGENTS.md file automatically, while preserving compatibility with existing `.claude` workflows.
 
-- ✅ **AGENTS.md** - 原生支持 OpenAI 发起的标准格式
-- ✅ **CLAUDE.md** - 与 Claude Code 的 `.claude` 配置完全向后兼容
-- ✅ **子代理系统** - 高级代理委派和任务编排
-- ✅ **跨平台** - 可与 20+ AI 模型和提供商配合使用
+### Instruction Discovery (Codex-compatible)
 
-使用 `# 您的文档请求` 自动生成和维护您的 AGENTS.md 文件，同时保持与现有 `.claude` 工作流的兼容性。
+- Kode reads project instructions by walking from the Git repo root → current working directory.
+- In each directory, it prefers `AGENTS.override.md` over `AGENTS.md` (at most one file per directory).
+- Discovered files are concatenated root → leaf (combined size capped at 32 KiB by default; override with `KODE_PROJECT_DOC_MAX_BYTES`).
+- If `CLAUDE.md` exists in the current directory, Kode also reads it as a legacy instruction file.
 
-## 概述
+## Overview
 
-OpenAGI 是一个强大的 AI 助手，驻留在您的终端中。它可以理解您的代码库、编辑文件、运行命令并为您处理整个工作流程。
+Kode is a powerful AI assistant that lives in your terminal. It can understand your codebase, edit files, run commands, and handle entire workflows for you.
 
-> **⚠️ 安全提示**：OpenAGI 默认以 YOLO 模式运行（相当于 Claude Code 的 `--dangerously-skip-permissions` 标志），绕过所有权限检查以实现最大生产力。YOLO 模式仅建议在受信任的安全环境中处理非关键项目时使用。如果您正在处理重要文件或使用能力存疑的模型，我们强烈建议使用 `openagi --safe` 启用权限检查和所有操作的手动批准。
->
-> **📊 模型性能**：为了获得最佳性能，我们建议使用专为自主任务完成设计的更新、更强大的模型。避免使用像 GPT-4o 或 Gemini 2.5 Pro 这样的旧版问答优化模型，它们针对回答问题而非持续独立任务执行进行了优化。应选择专门为代理工作流程和扩展推理能力训练的模型。
+> **⚠️ Security Notice**: Kode runs in YOLO mode by default (equivalent to the `--dangerously-skip-permissions` flag), bypassing all permission checks for maximum productivity. YOLO mode is recommended only for trusted, secure environments when working on non-critical projects. If you're working with important files or using models of questionable capability, we strongly recommend using `kode --safe` to enable permission checks and manual approval for all operations.
+> 
+> **📊 Model Performance**: For optimal performance, we recommend using newer, more capable models designed for autonomous task completion. Avoid older Q&A-focused models like GPT-4o or Gemini 2.5 Pro, which are optimized for answering questions rather than sustained independent task execution. Choose models specifically trained for agentic workflows and extended reasoning capabilities.
+
+## Network & Privacy
+
+- Kode does not send product telemetry/analytics by default.
+- Network requests happen only when you explicitly use networked features:
+  - Model provider requests (Anthropic/OpenAI-compatible endpoints you configure)
+  - Web tools (`WebFetch`, `WebSearch`)
+  - Plugin marketplace downloads (GitHub/URL sources) and OAuth flows (when used)
+  - Optional update checks (opt-in via `autoUpdaterStatus: enabled`)
 
 <img width="600" height="577" alt="image" src="https://github.com/user-attachments/assets/8b46a39d-1ab6-4669-9391-14ccc6c5234c" />
 
-## 功能特性
-
-### 核心能力
-- 🤖 **AI 驱动助手** - 使用先进的 AI 模型理解和响应您的请求
-- 🔄 **多模型协作** - 灵活切换和组合多个 AI 模型以利用它们的独特优势
-- 🦜 **专家模型咨询** - 使用 `@ask-model-name` 咨询特定 AI 模型以获得专业分析
-- 👤 **智能代理系统** - 使用 `@run-agent-name` 将任务委派给专业子代理
-- 📝 **代码编辑** - 通过智能建议和改进直接编辑文件
-- 🔍 **代码库理解** - 分析您的项目结构和代码关系
-- 🚀 **命令执行** - 运行 shell 命令并实时查看结果
-- 🛠️ **工作流程自动化** - 通过简单的提示处理复杂的开发任务
-
-### 编辑舒适度
-- `Ctrl+G` 在您偏好的编辑器中打开消息（尊重 `$EDITOR`/`$VISUAL`；回退到 code/nano/vim/notepad），并在关闭时将文本返回到提示符。
-- `Shift+Enter` 在提示符内插入换行符而不发送；直接 Enter 提交。`Ctrl+M` 切换活动模型。
-
-### 🎯 先进的智能补全系统
-我们的最先进补全系统提供无与伦比的编码辅助：
-
-#### 智能模糊匹配
-- **连字符感知匹配** - 输入 `dao` 即可匹配 `run-agent-dao-qi-harmony-designer`
-- **缩写支持** - `dq` 匹配 `dao-qi`，`nde` 匹配 `node`
-- **数字后缀处理** - `py3` 智能匹配 `python3`
-- **多算法融合** - 结合 7+ 种匹配算法以获得最佳结果
-
-#### 智能上下文检测
-- **无需 @ 符号** - 直接输入 `gp5` 即可匹配 `@ask-gpt-5`
-- **自动前缀添加** - Tab/Enter 自动为代理和模型添加 `@`
-- **混合补全** - 在命令、文件、代理和模型之间无缝切换
-- **智能优先级** - 根据相关性和使用频率对结果进行排名
-
-#### Unix 命令优化
-- **500+ 常用命令** - 精心策划的常用 Unix/Linux 命令数据库
-- **系统交集** - 仅显示您的系统上实际存在的命令
-- **优先级评分** - 常用命令排在前面（git、npm、docker 等）
-- **实时加载** - 从系统 PATH 动态发现命令
-
-### 用户体验
-- 🎨 **交互式 UI** - 具有语法高亮的精美终端界面
-- 🔌 **工具系统** - 可扩展架构，针对不同任务提供专业工具
-- 💾 **上下文管理** - 智能上下文处理以保持对话连续性
-- 📋 **AGENTS.md 集成** - 使用 `# 文档请求` 自动生成和维护项目文档
-
-## 安装
+## Features
+
+### Core Capabilities
+- 🤖 **AI-Powered Assistance** - Uses advanced AI models to understand and respond to your requests
+- 🔄 **Multi-Model Collaboration** - Flexibly switch and combine multiple AI models to leverage their unique strengths
+- 🦜 **Expert Model Consultation** - Use `@ask-model-name` to consult specific AI models for specialized analysis
+- 👤 **Intelligent Agent System** - Use `@run-agent-name` to delegate tasks to specialized subagents
+- 📝 **Code Editing** - Directly edit files with intelligent suggestions and improvements
+- 🔍 **Codebase Understanding** - Analyzes your project structure and code relationships
+- 🚀 **Command Execution** - Run shell commands and see results in real-time
+- 🛠️ **Workflow Automation** - Handle complex development tasks with simple prompts
+
+### Authoring Comfort
+- `Option+G` (Alt+G) opens your message in your preferred editor (respects `$EDITOR`/`$VISUAL`; falls back to code/nano/vim/notepad) and returns the text to the prompt when you close it.
+- `Option+Enter` inserts a newline inside the prompt without sending; plain Enter submits. `Option+M` cycles the active model.
+
+### 🎯 Advanced Intelligent Completion System
+Our state-of-the-art completion system provides unparalleled coding assistance:
+
+#### Smart Fuzzy Matching
+- **Hyphen-Aware Matching** - Type `dao` to match `run-agent-dao-qi-harmony-designer`
+- **Abbreviation Support** - `dq` matches `dao-qi`, `nde` matches `node`
+- **Numeric Suffix Handling** - `py3` intelligently matches `python3`
+- **Multi-Algorithm Fusion** - Combines 7+ matching algorithms for best results
+
+#### Intelligent Context Detection
+- **No @ Required** - Type `gp5` directly to match `@ask-gpt-5`
+- **Auto-Prefix Addition** - Tab/Enter automatically adds `@` for agents and models
+- **Mixed Completion** - Seamlessly switch between commands, files, agents, and models
+- **Smart Prioritization** - Results ranked by relevance and usage frequency
+
+#### Unix Command Optimization
+- **500+ Common Commands** - Curated database of frequently used Unix/Linux commands
+- **System Intersection** - Only shows commands that actually exist on your system
+- **Priority Scoring** - Common commands appear first (git, npm, docker, etc.)
+- **Real-time Loading** - Dynamic command discovery from system PATH
+
+### User Experience
+- 🎨 **Interactive UI** - Beautiful terminal interface with syntax highlighting
+- 🔌 **Tool System** - Extensible architecture with specialized tools for different tasks
+- 💾 **Context Management** - Smart context handling to maintain conversation continuity
+- 📋 **AGENTS.md Integration** - Use `# documentation requests` to auto-generate and maintain project documentation
+
+## Installation
 
 ```bash
-npm install -g @xinshu/openagi
+npm install -g @shareai-lab/kode
 ```
 
-安装后，您可以使用以下任何命令：
-- `openagi` - 主命令
-- `agi` - OpenAGI With Agent（替代命令）
+> **🇨🇳 For users in China**: If you encounter network issues, use a mirror registry:
+> ```bash
+> npm install -g @shareai-lab/kode --registry=https://registry.npmmirror.com
+> ```
+
+Dev channel (latest features):
+
+```bash
+npm install -g @shareai-lab/kode@dev
+```
+
+After installation, you can use any of these commands:
+- `kode` - Primary command
+- `kwa` - Kode With Agent (alternative)
+- `kd` - Ultra-short alias
+
+### Native binaries (Windows OOTB)
+
+- No WSL/Git Bash required.
+- On `postinstall`, Kode will best-effort download a native binary from GitHub Releases into `${KODE_BIN_DIR:-~/.kode/bin}/<version>/<platform>-<arch>/kode(.exe)`.
+- The wrapper (`cli.js`) prefers the native binary and falls back to the Node.js runtime (`node dist/index.js`) when needed.
 
-### Windows 说明
+Overrides:
+- Mirror downloads: `KODE_BINARY_BASE_URL`
+- Disable download: `KODE_SKIP_BINARY_DOWNLOAD=1`
+- Cache directory: `KODE_BIN_DIR`
 
-- 安装 Git for Windows 以提供 Bash（类似 Unix）环境：https://git-scm.com/download/win
-  - OpenAGI 在可用时自动优先使用 Git Bash/MSYS 或 WSL Bash。
-  - 如果两者都不可用，它将回退到您的默认 shell，但许多功能在 Bash 下效果最佳。
-- 使用 VS Code 的集成终端而不是旧版命令提示符（cmd）：
-  - 更好的字体渲染和图标支持。
-  - 与 cmd 相比，路径和编码的怪癖更少。
-  - 尽可能选择"Git Bash"作为 VS Code 终端 shell。
-- 可选：如果您通过 npm 全局安装，请避免全局前缀路径中的空格以防止 shim 问题。
-  - 示例：`npm config set prefix "C:\\npm"` 并重新安装全局包。
+See `docs/binary-distribution.md`.
 
-## 使用方法
+### Configuration / API keys
 
-### 交互式模式
-启动交互式会话：
+- Global config (models, pointers, theme, etc): `~/.kode.json` (or `<KODE_CONFIG_DIR>/config.json` when `KODE_CONFIG_DIR`/`CLAUDE_CONFIG_DIR` is set).
+- Project/local settings (output style, etc): `./.kode/settings.json` and `./.kode/settings.local.json` (legacy `.claude` is supported for some features).
+- Configure models via `/model` (UI) or `kode models import/export` (YAML). Details: `docs/develop/configuration.md`.
+
+## Usage
+
+### Interactive Mode
+Start an interactive session:
 ```bash
-openagi
-# 或
-agi
+kode
+# or
+kwa
+# or
+kd
+```
 
+### Non-Interactive Mode
+Get a quick response:
+```bash
+kode -p "explain this function" path/to/file.js
+# or
+kwa -p "explain this function" path/to/file.js
 ```
 
-### 非交互式模式
-快速获取响应：
+### ACP (Agent Client Protocol)
+
+Run Kode as an ACP agent server (stdio JSON-RPC), for clients like Toad/Zed:
+
 ```bash
-openagi -p "解释这个函数" path/to/file.js
-# 或
-agi -p "解释这个函数" path/to/file.js
+kode-acp
+# or
+kode --acp
 ```
 
-### 使用 @ 提及系统
+Toad example:
 
-OpenAGI 支持强大的 @ 提及系统以实现智能补全：
+```bash
+toad acp "kode-acp"
+```
+
+More: `docs/acp.md`.
+
+### Using the @ Mention System
 
-#### 🦜 专家模型咨询
+Kode supports a powerful @ mention system for intelligent completions:
+
+#### 🦜 Expert Model Consultation
 ```bash
-# 咨询特定 AI 模型以获得专家意见
-@ask-claude-sonnet-4 我应该如何优化这个 React 组件的性能？
-@ask-gpt-5 这种身份验证方法的安全影响是什么？
-@ask-o1-preview 分析这个算法的复杂性
+# Consult specific AI models for expert opinions
+@ask-claude-sonnet-4 How should I optimize this React component for performance?
+@ask-gpt-5 What are the security implications of this authentication method?
+@ask-o1-preview Analyze the complexity of this algorithm
 ```
 
-#### 👤 专业代理委派
+#### 👤 Specialized Agent Delegation  
 ```bash
-# 将任务委派给专业子代理
-@run-agent-simplicity-auditor 审查这段代码是否存在过度工程化
-@run-agent-architect 为这个系统设计微服务架构
-@run-agent-test-writer 为这些模块创建全面的测试
+# Delegate tasks to specialized subagents
+@run-agent-simplicity-auditor Review this code for over-engineering
+@run-agent-architect Design a microservices architecture for this system
+@run-agent-test-writer Create comprehensive tests for these modules
 ```
 
-#### 📁 智能文件引用
+#### 📁 Smart File References
 ```bash
-# 使用自动补全引用文件和目录
-@src/components/Button.tsx
-@docs/api-reference.md
+# Reference files and directories with auto-completion
+@packages/core/src/query/index.ts
+@docs/README.md
 @.env.example
 ```
 
-@ 提及系统在您输入时提供智能补全，显示可用的模型、代理和文件。
+The @ mention system provides intelligent completions as you type, showing available models, agents, and files.
+
+### MCP Servers (Extensions)
 
-### AGENTS.md 文档模式
+Kode can connect to MCP servers to extend tools and context.
 
-使用 `#` 前缀生成和维护您的 AGENTS.md 文档：
+- Config files: `.mcp.json` (recommended) or `.mcprc` in your project root. See `docs/mcp.md`.
+- CLI:
 
 ```bash
-# 生成设置说明
-# 我如何设置开发环境？
+kode mcp add
+kode mcp list
+kode mcp get <name>
+kode mcp remove <name>
+```
 
-# 创建测试文档
-# 这个项目的测试程序是什么？
+Example `.mcprc`:
 
-# 记录部署过程
-# 解释部署管道和要求
+```json
+{
+  "my-sse-server": { "type": "sse", "url": "http://127.0.0.1:3333/sse" }
+}
 ```
 
-此模式自动将响应格式化为结构化文档，并将它们附加到您的 AGENTS.md 文件中。
+### Permissions & Approvals
+
+- Default mode skips most prompts for speed.
+- Safe mode: `kode --safe` requires approval for Bash commands and file writes/edits.
+- Plan mode: the assistant may ask to enter plan mode to draft a plan file; while in plan mode, only read-only/planning tools (and the plan file) are allowed until you approve exiting plan mode.
+
+### Paste & Images
+
+- Multi-line/large paste is inserted as a placeholder and expanded on submit.
+- Pasting multiple existing file paths inserts `@path` mentions automatically (quoted when needed).
+- Image paste (macOS): press `Ctrl+V` to attach clipboard images; you can paste multiple images before sending.
+
+### System Sandbox (Linux)
+
+- In safe mode (or with `KODE_SYSTEM_SANDBOX=1`), agent-triggered Bash tool calls try to run inside a `bwrap` sandbox when available.
+- Network is disabled by default; set `KODE_SYSTEM_SANDBOX_NETWORK=inherit` to allow network.
+- Set `KODE_SYSTEM_SANDBOX=required` to fail closed if sandbox cannot be started.
+- See `docs/system-sandbox.md` for details and platform notes.
 
-### Docker 使用
+### Troubleshooting
 
-#### 替代方案：从本地源构建
+- Models: use `/model`, or `kode models import kode-models.yaml`, and ensure required API key env vars exist.
+- Windows: if the native binary download is blocked/offline, set `KODE_BINARY_BASE_URL` (mirror) or `KODE_SKIP_BINARY_DOWNLOAD=1` (skip download); the wrapper will fall back to the Node.js runtime (`dist/index.js`).
+- MCP: use `kode mcp list` to check server status; tune `MCP_CONNECTION_TIMEOUT_MS`, `MCP_SERVER_CONNECTION_BATCH_SIZE`, and `MCP_TOOL_TIMEOUT` if servers are slow.
+- Sandbox: install `bwrap` (bubblewrap) on Linux, or set `KODE_SYSTEM_SANDBOX=0` to disable.
+
+### AGENTS.md Documentation Mode
+
+Use the `#` prefix to generate and maintain your AGENTS.md documentation:
 
 ```bash
-# 克隆仓库
-git clone https://github.com/xingshuzhice/openagi.git
-cd openagi
+# Generate setup instructions
+# How do I set up the development environment?
+
+# Create testing documentation  
+# What are the testing procedures for this project?
+
+# Document deployment process
+# Explain the deployment pipeline and requirements
+```
+
+This mode automatically formats responses as structured documentation and appends them to your AGENTS.md file.
 
-# 在本地构建镜像
-docker build --no-cache -t openagi .
+### Docker Usage
 
-# 在您的项目目录中运行
+#### Alternative: Build from local source
+
+```bash
+# Clone the repository
+git clone https://github.com/shareAI-lab/Kode.git
+cd Kode
+
+# Build the image locally
+docker build --no-cache -t kode .
+
+# Run in your project directory
 cd your-project
 docker run -it --rm \
   -v $(pwd):/workspace \
-  -v ~/.openagi:/root/.openagi \
-  -v ~/.openagi.json:/root/.openagi.json \
+  -v ~/.kode:/root/.kode \
+  -v ~/.kode.json:/root/.kode.json \
   -w /workspace \
-  openagi
+  kode
 ```
 
-#### Docker 配置详情
+#### Docker Configuration Details
+
+The Docker setup includes:
+
+- **Volume Mounts**:
+  - `$(pwd):/workspace` - Mounts your current project directory
+  - `~/.kode:/root/.kode` - Preserves your kode configuration directory between runs
+  - `~/.kode.json:/root/.kode.json` - Preserves your kode global configuration file between runs
 
-Docker 设置包括：
+- **Working Directory**: Set to `/workspace` inside the container
 
-- **卷挂载**：
-  - `$(pwd):/workspace` - 挂载您当前的项目目录
-  - `~/.openagi:/root/.openagi` - 在运行之间保留您的 openagi 配置目录
-  - `~/.openagi.json:/root/.openagi.json` - 在运行之间保留您的 openagi 全局配置文件
+- **Interactive Mode**: Uses `-it` flags for interactive terminal access
 
-- **工作目录**：在容器内设置为 `/workspace`
+- **Cleanup**: `--rm` flag removes the container after exit
 
-- **交互模式**：使用 `-it` 标志进行交互式终端访问
+**Note**: Kode uses both `~/.kode` directory for additional data (like memory files) and `~/.kode.json` file for global configuration.
 
-- **清理**：`--rm` 标志在退出后删除容器
+The first time you run the Docker command, it will build the image. Subsequent runs will use the cached image for faster startup.
 
-**注意**：OpenAGI 同时使用 `~/.openagi` 目录存储额外数据（如内存文件）和 `~/.openagi.json` 文件进行全局配置。
+You can use the onboarding to set up the model, or `/model`.
+If you don't see the models you want on the list, you can manually set them in `/config`
+As long as you have an openai-like endpoint, it should work.
 
-第一次运行 Docker 命令时，它将构建镜像。后续运行将使用缓存镜像以加快启动速度。
+### Commands
 
-您可以使用入门来设置模型，或使用 `/model`。
-如果您在列表中看不到想要的模型，可以在 `/config` 中手动设置
-只要您有类似 openai 的端点，它就应该工作。
+- `/help` - Show available commands
+- `/model` - Change AI model settings
+- `/config` - Open configuration panel
+- `/agents` - Manage subagents
+- `/output-style` - Set the output style
+- `/statusline` - Configure a custom status line command
+- `/cost` - Show token usage and costs
+- `/clear` - Clear conversation history
+- `/init` - Initialize project context
+- `/plugin` - Manage plugins/marketplaces (skills, commands)
 
-### 命令
+## Agents / Subagents
 
-- `/help` - 显示可用命令
-- `/model` - 更改 AI 模型设置
-- `/config` - 打开配置面板
-- `/cost` - 显示令牌使用情况和成本
-- `/clear` - 清除对话历史
-- `/init` - 初始化项目上下文
+Kode supports subagents (agent templates) for delegation and task orchestration.
 
-## 多模型智能协作
+- Agents are loaded from `.kode/agents` and `.claude/agents` (user + project), plus plugins/policy and `--agents`.
+- Manage in the UI: `/agents` (creates new agents under `./.claude/agents` / `~/.claude/agents` by default).
+- Run via mentions: `@run-agent-<agentType> ...`
+- Run via tooling: `Task(subagent_type: "<agentType>", ...)`
+- CLI flags: `--agents <json>` (inject agents for this run), `--setting-sources user,project,local` (control which sources are loaded)
 
-与只支持单一模型的官方 Claude 不同，OpenAGI 实现了**真正的多模型协作**，让您充分利用不同 AI 模型的独特优势。
+Minimal agent file example (`./.kode/agents/reviewer.md`):
 
-### 🏗️ 核心技术架构
+```md
+---
+name: reviewer
+description: "Review diffs for correctness, security, and simplicity"
+tools: ["Read", "Grep"]
+model: inherit
+---
 
-#### 1. **ModelManager 多模型管理器**
-我们设计了统一的 `ModelManager` 系统，支持：
-- **模型配置文件**：每个模型都有独立的配置文件，包含 API 端点、身份验证、上下文窗口大小、成本参数等。
-- **模型指针**：用户可以在 `/model` 命令中为不同目的配置默认模型：
-  - `main`：主代理的默认模型
-  - `task`：子代理的默认模型
-  - `reasoning`：保留供将来 ThinkTool 使用
-  - `quick`：用于简单 NLP 任务的快速模型（安全识别、标题生成等）
-- **动态模型切换**：支持运行时模型切换，无需重启会话，保持上下文连续性
+Be strict. Point out bugs and risky changes. Prefer small, targeted fixes.
+```
+
+Model field notes:
+- Compatibility aliases: `inherit`, `opus`, `sonnet`, `haiku` (mapped to model pointers)
+- Kode selectors (via `/model`): pointers (`main|task|compact|quick`), profile name, modelName, or `provider:modelName` (e.g. `openai:o3`)
+
+Validate agent templates:
+
+```bash
+kode agents validate
+```
+
+See `docs/agents-system.md`.
+
+## Skills & Plugins
+
+Kode supports the [Agent Skills](https://agentskills.io) open format for extending agent capabilities:
+- **Agent Skills** format (`SKILL.md`) - see [specification](https://agentskills.io/specification)
+- **Marketplace compatibility** (`.kode-plugin/marketplace.json`, legacy `.claude-plugin/marketplace.json`)
+- **Install from any repository** using [`add-skill` CLI](https://github.com/vercel-labs/add-skill)
+
+### Quick install with add-skill
+
+Install skills from any git repository:
+
+```bash
+# Install from GitHub
+npx add-skill vercel-labs/agent-skills -a kode
+
+# Install to global directory
+npx add-skill vercel-labs/agent-skills -a kode -g
+
+# Install specific skills
+npx add-skill vercel-labs/agent-skills -a kode -s pdf -s xlsx
+```
+
+### Install skills from a marketplace
+
+```bash
+# Add a marketplace (local path, GitHub owner/repo, or URL)
+kode plugin marketplace add ./path/to/marketplace-repo
+kode plugin marketplace add owner/repo
+kode plugin marketplace list
+
+# Install a plugin pack (installs skills/commands)
+kode plugin install document-skills@anthropic-agent-skills --scope user
+
+# Project-scoped install (writes to ./.kode/...)
+kode plugin install document-skills@anthropic-agent-skills --scope project
+
+# Disable/enable an installed plugin
+kode plugin disable document-skills@anthropic-agent-skills --scope user
+kode plugin enable document-skills@anthropic-agent-skills --scope user
+```
+
+Interactive equivalents:
+
+```text
+/plugin marketplace add owner/repo
+/plugin install document-skills@anthropic-agent-skills --scope user
+```
+
+### Use skills
+
+- In interactive mode, run a skill as a slash command: `/pdf`, `/xlsx`, etc.
+- Kode can also invoke skills automatically via the `Skill` tool when relevant.
+
+### Create a skill (Agent Skills)
+
+Create `./.kode/skills/<skill-name>/SKILL.md` (project) or `~/.kode/skills/<skill-name>/SKILL.md` (user):
+
+```md
+---
+name: my-skill
+description: Describe what this skill does and when to use it.
+allowed-tools: Read Bash(git:*) Bash(jq:*)
+---
+
+# Skill instructions
+```
+
+Naming rules:
+- `name` must match the folder name
+- Lowercase letters/numbers/hyphens only, 1–64 chars
+
+Compatibility:
+- Kode also discovers `.claude/skills` and `.claude/commands` for legacy compatibility.
+
+### Distribute skills
+
+- Marketplace repo: publish a repo containing `.kode-plugin/marketplace.json` listing plugin packs and their `skills` directories (legacy `.claude-plugin/marketplace.json` is also supported).
+- Plugin repo: for full plugins (beyond skills), include `.kode-plugin/plugin.json` at the plugin root and keep all paths relative (`./...`).
+
+See `docs/skills.md` for a compact reference and examples.
+
+### Output styles
+
+Use output styles to switch system-prompt behavior.
+
+- Select: `/output-style` (menu) or `/output-style <style>`
+- Built-ins: `default`, `Explanatory`, `Learning`
+- Stored per-project in `./.kode/settings.local.json` as `outputStyle` (legacy `.claude/settings.local.json` is supported)
+- Custom styles: Markdown files under `output-styles/` in `.claude`/`.kode` user + project locations
+- Plugins can provide styles under `output-styles/` (or manifest `outputStyles`); plugin styles are namespaced as `<plugin>:<style>`
+
+See `docs/output-styles.md`.
+
+## Multi-Model Intelligent Collaboration
+
+Unlike single-model CLIs, Kode implements **true multi-model collaboration**, allowing you to fully leverage the unique strengths of different AI models.
+
+### 🏗️ Core Technical Architecture
+
+#### 1. **ModelManager Multi-Model Manager**
+We designed a unified `ModelManager` system that supports:
+- **Model Profiles**: Each model has an independent configuration file containing API endpoints, authentication, context window size, cost parameters, etc.
+- **Model Pointers**: Users can configure default models for different purposes in the `/model` command:
+  - `main`: Default model for main Agent
+  - `task`: Default model for SubAgent
+  - `compact`: Model used for automatic context compression when nearing the context window
+  - `quick`: Fast model for simple operations and utilities
+- **Dynamic Model Switching**: Support runtime model switching without restarting sessions, maintaining context continuity
+
+#### 📦 Shareable Model Config (YAML)
+
+You can export/import model profiles + pointers as a team-shareable YAML file. By default, exports do **not** include plaintext API keys (use env vars instead).
+
+```bash
+# Export to a file (or omit --output to print to stdout)
+kode models export --output kode-models.yaml
+
+# Import (merge by default)
+kode models import kode-models.yaml
+
+# Replace existing profiles instead of merging
+kode models import --replace kode-models.yaml
+
+# List configured profiles + pointers
+kode models list
+```
+
+Example `kode-models.yaml`:
+
+```yaml
+version: 1
+profiles:
+  - name: OpenAI Main
+    provider: openai
+    modelName: gpt-4o
+    maxTokens: 8192
+    contextLength: 128000
+    apiKey:
+      fromEnv: OPENAI_API_KEY
+pointers:
+  main: gpt-4o
+  task: gpt-4o
+  compact: gpt-4o
+  quick: gpt-4o
+```
 
-#### 2. **TaskTool 智能任务分配**
-我们专门设计的 `TaskTool`（架构师工具）实现了：
-- **子代理机制**：可以启动多个子代理并行处理任务
-- **模型参数传递**：用户可以在请求中指定子代理应使用哪个模型
-- **默认模型配置**：子代理默认使用 `task` 指针配置的模型
+#### 2. **TaskTool Intelligent Task Distribution**
+Our specially designed `TaskTool` (Architect tool) implements:
+- **Subagent Mechanism**: Can launch multiple sub-agents to process tasks in parallel
+- **Model Parameter Passing**: Users can specify which model SubAgents should use in their requests
+- **Default Model Configuration**: SubAgents use the model configured by the `task` pointer by default
 
-#### 3. **AskExpertModel 专家咨询工具**
-我们专门设计了 `AskExpertModel` 工具：
-- **专家模型调用**：允许在对话期间临时调用特定专家模型解决难题
-- **模型隔离执行**：专家模型响应独立处理，不影响主对话流程
-- **知识整合**：将专家模型见解整合到当前任务中
+#### 3. **AskExpertModel Expert Consultation Tool**
+We specially designed the `AskExpertModel` tool:
+- **Expert Model Invocation**: Allows temporarily calling specific expert models to solve difficult problems during conversations
+- **Model Isolation Execution**: Expert model responses are processed independently without affecting the main conversation flow
+- **Knowledge Integration**: Integrates expert model insights into the current task
 
-#### 🎯 灵活的模型切换
-- **Tab 键快速切换**：在输入框中按 Tab 键快速切换当前对话的模型
-- **`/model` 命令**：使用 `/model` 命令配置和管理多个模型配置文件，为不同目的设置默认模型
-- **用户控制**：用户可以随时指定特定模型进行任务处理
+#### 🎯 Flexible Model Switching
+- **Option+M Quick Switch**: Press Option+M in the input box to cycle the main conversation model
+- **`/model` Command**: Use `/model` command to configure and manage multiple model profiles, set default models for different purposes
+- **User Control**: Users can specify specific models for task processing at any time
 
-#### 🔄 智能工作分配策略
+#### 🔄 Intelligent Work Allocation Strategy
 
-**架构设计阶段**
-- 使用 **o3 模型** 或 **GPT-5 模型** 探索系统架构并制定清晰明确的技术方案
-- 这些模型在抽象思维和系统设计方面表现出色
+**Architecture Design Phase**
+- Use **o3 model** or **GPT-5 model** to explore system architecture and formulate sharp and clear technical solutions
+- These models excel in abstract thinking and system design
 
-**方案细化阶段**
-- 使用 **gemini 模型** 深入探索生产环境设计细节
-- 利用其在实际工程和平衡推理方面的深厚积累
+**Solution Refinement Phase**
+- Use **gemini model** to deeply explore production environment design details
+- Leverage its deep accumulation in practical engineering and balanced reasoning capabilities
 
-**代码实现阶段**
-- 使用 **Qwen Coder 模型**、**Kimi k2 模型**、**GLM-4.5 模型** 或 **Claude Sonnet 4 模型** 进行具体代码编写
-- 这些模型在代码生成、文件编辑和工程实现方面表现强劲
-- 支持通过子代理并行处理多个编码任务
+**Code Implementation Phase**
+- Use **Qwen Coder model**, **Kimi k2 model**, **GLM-4.5 model**, or **Claude Sonnet 4 model** for specific code writing
+- These models have strong performance in code generation, file editing, and engineering implementation
+- Support parallel processing of multiple coding tasks through subagents
 
-**问题解决**
-- 遇到复杂问题时，咨询 **o3 模型**、**Claude Opus 4.1 模型** 或 **Grok 4 模型** 等专家模型
-- 获得深入的技术见解和创新解决方案
+**Problem Solving**
+- When encountering complex problems, consult expert models like **o3 model**, **Claude Opus 4.1 model**, or **Grok 4 model**
+- Obtain deep technical insights and innovative solutions
 
-#### 💡 实际应用场景
+#### 💡 Practical Application Scenarios
 
 ```bash
-# 示例 1：架构设计
-"使用 o3 模型帮我设计一个高并发消息队列系统架构"
+# Example 1: Architecture Design
+"Use o3 model to help me design a high-concurrency message queue system architecture"
 
-# 示例 2：多模型协作
-"首先使用 GPT-5 模型分析这个性能问题的根本原因，然后使用 Claude Sonnet 4 模型编写优化代码"
+# Example 2: Multi-Model Collaboration
+"First use GPT-5 model to analyze the root cause of this performance issue, then use Claude Sonnet 4 model to write optimization code"
 
-# 示例 3：并行任务处理
-"使用 Qwen Coder 模型作为子代理同时重构这三个模块"
+# Example 3: Parallel Task Processing
+"Use Qwen Coder model as subagent to refactor these three modules simultaneously"
 
-# 示例 4：专家咨询
-"这个内存泄漏问题很棘手，单独询问 Claude Opus 4.1 模型寻求解决方案"
+# Example 4: Expert Consultation
+"This memory leak issue is tricky, ask Claude Opus 4.1 model separately for solutions"
 
-# 示例 5：代码审查
-"让 Kimi k2 模型审查这个 PR 的代码质量"
+# Example 5: Code Review
+"Have Kimi k2 model review the code quality of this PR"
 
-# 示例 6：复杂推理
-"使用 Grok 4 模型帮我推导这个算法的时间复杂度"
+# Example 6: Complex Reasoning
+"Use Grok 4 model to help me derive the time complexity of this algorithm"
 
-# 示例 7：方案设计
-"让 GLM-4.5 模型设计一个微服务分解方案"
+# Example 7: Solution Design
+"Have GLM-4.5 model design a microservice decomposition plan"
 ```
 
-### 🛠️ 关键实现机制
+### 🛠️ Key Implementation Mechanisms
 
-#### **配置系统**
+#### **Configuration System**
 ```typescript
-// 多模型配置支持示例
+// Example of multi-model configuration support
 {
-  "modelProfiles": {
-    "o3": { "provider": "openai", "model": "o3", "apiKey": "..." },
-    "claude4": { "provider": "anthropic", "model": "claude-sonnet-4", "apiKey": "..." },
-    "qwen": { "provider": "alibaba", "model": "qwen-coder", "apiKey": "..." }
-  },
+  "modelProfiles": [
+    { "name": "o3", "provider": "openai", "modelName": "o3", "apiKey": "...", "maxTokens": 1024, "contextLength": 128000, "isActive": true, "createdAt": 1710000000000 },
+    { "name": "qwen", "provider": "alibaba", "modelName": "qwen-coder", "apiKey": "...", "maxTokens": 1024, "contextLength": 128000, "isActive": true, "createdAt": 1710000000001 }
+  ],
   "modelPointers": {
-    "main": "claude4",      // 主对话模型
-    "task": "qwen",         // 任务执行模型
-    "reasoning": "o3",      // 推理模型
-    "quick": "glm-4.5"      // 快速响应模型
+    "main": "o3",           // Main conversation model
+    "task": "qwen-coder",   // Sub-agent model
+    "compact": "o3",        // Context compression model
+    "quick": "o3"           // Quick operations model
   }
 }
 ```
 
-#### **成本跟踪系统**
-- **使用统计**：使用 `/cost` 命令查看每个模型的令牌使用情况和成本
-- **多模型成本比较**：实时跟踪不同模型的使用成本
-- **历史记录**：保存每个会话的成本数据
+#### **Cost Tracking System**
+- **Usage Statistics**: Use `/cost` command to view token usage and costs for each model
+- **Multi-Model Cost Comparison**: Track usage costs of different models in real-time
+- **History Records**: Save cost data for each session
 
-#### **上下文管理器**
-- **上下文继承**：切换模型时保持对话连续性
-- **上下文窗口适应**：根据不同模型的上下文窗口大小自动调整
-- **会话状态保持**：确保多模型协作期间的信息一致性
+#### **Context Manager**
+- **Context Inheritance**: Maintain conversation continuity when switching models
+- **Context Window Adaptation**: Automatically adjust based on different models' context window sizes
+- **Session State Preservation**: Ensure information consistency during multi-model collaboration
 
-### 🚀 多模型协作的优势
+### 🚀 Advantages of Multi-Model Collaboration
 
-1. **最大化效率**：每个任务由最合适的模型处理
-2. **成本优化**：简单任务使用轻量级模型，复杂任务使用强大的模型
-3. **并行处理**：多个模型可以同时处理不同的子任务
-4. **灵活切换**：根据任务需求切换模型，无需重启会话
-5. **利用优势**：结合不同模型的优势以获得最佳整体结果
+1. **Maximized Efficiency**: Each task is handled by the most suitable model
+2. **Cost Optimization**: Use lightweight models for simple tasks, powerful models for complex tasks
+3. **Parallel Processing**: Multiple models can work on different subtasks simultaneously
+4. **Flexible Switching**: Switch models based on task requirements without restarting sessions
+5. **Leveraging Strengths**: Combine advantages of different models for optimal overall results
 
-### 📊 与官方实现的比较
+### 📊 Comparison (Single-model CLI)
 
-| 功能 | OpenAGI | 官方 Claude |
+| Feature | Kode | Single-model CLI |
 |---------|------|-----------------|
-| 支持的模型数量 | 无限，可配置任何模型 | 仅支持单一 Claude 模型 |
-| 模型切换 | ✅ Tab 键快速切换 | ❌ 需要重启会话 |
-| 并行处理 | ✅ 多个子代理并行工作 | ❌ 单线程处理 |
-| 成本跟踪 | ✅ 多个模型分别统计 | ❌ 单一模型成本 |
-| 任务模型配置 | ✅ 不同目的不同默认模型 | ❌ 所有任务使用相同模型 |
-| 专家咨询 | ✅ AskExpertModel 工具 | ❌ 不支持 |
+| Number of Supported Models | Unlimited, configurable for any model | Only supports one model |
+| Model Switching | ✅ Option+M quick switch | ❌ Requires session restart |
+| Parallel Processing | ✅ Multiple SubAgents work in parallel | ❌ Single-threaded processing |
+| Cost Tracking | ✅ Separate statistics for multiple models | ❌ Single model cost |
+| Task Model Configuration | ✅ Different default models for different purposes | ❌ Same model for all tasks |
+| Expert Consultation | ✅ AskExpertModel tool | ❌ Not supported |
 
-这种多模型协作能力使 OpenAGI 成为真正的 **AI 开发工作台**，而不仅仅是一个单一的 AI 助手。
+This multi-model collaboration capability makes Kode a true **AI Development Workbench**, not just a single AI assistant.
 
-## 开发
+## Development
 
-OpenAGI 使用现代工具构建，开发需要 [Bun](https://bun.sh)。
+Kode is built with modern tools and requires [Bun](https://bun.sh) for development.
 
-### 安装 Bun
+### Install Bun
 
 ```bash
 # macOS/Linux
@@ -373,52 +641,52 @@ curl -fsSL https://bun.sh/install | bash
 powershell -c "irm bun.sh/install.ps1 | iex"
 ```
 
-### 设置开发环境
+### Setup Development Environment
 
 ```bash
-# 克隆仓库
-git clone https://github.com/xingshuzhice/openagi.git
-cd openagi
+# Clone the repository
+git clone https://github.com/shareAI-lab/kode.git
+cd kode
 
-# 安装依赖
+# Install dependencies
 bun install
 
-# 以开发模式运行
+# Run in development mode
 bun run dev
 ```
 
-### 构建
+### Build
 
 ```bash
 bun run build
 ```
 
-### 测试
+### Testing
 
 ```bash
-# 运行测试
+# Run tests
 bun test
 
-# 测试 CLI
+# Test the CLI
 ./cli.js --help
 ```
 
-## 贡献
+## Contributing
 
-我们欢迎贡献！详情请参阅我们的[贡献指南](CONTRIBUTING.md)。
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
 
-## 许可证
+## License
 
-Apache 2.0 许可证 - 详情请参阅 [LICENSE](LICENSE)。
+Apache 2.0 License - see [LICENSE](LICENSE) for details.
 
-## 致谢
+## Thanks
 
-- 部分代码来自 @dnakov 的 anonkode
-- 部分 UI 学习自 gemini-cli
-- 部分系统设计学习自 claude code
+- Some code from @dnakov's anonkode
+- Some UI learned from gemini-cli  
+- Some system design learned from upstream agent CLIs
 
-## 支持
+## Support
 
-- 📚 [文档](docs/)
-- 🐛 [报告问题](https://github.com/xingshuzhice/openagi/issues)
-- 💬 [讨论](https://github.com/xingshuzhice/openagi/discussions)
+- 📚 [Documentation](docs/)
+- 🐛 [Report Issues](https://github.com/shareAI-lab/kode/issues)
+- 💬 [Discussions](https://github.com/shareAI-lab/kode/discussions)