npm package: @kaiven_full_stack/kcode
Description: A CLI AI Agent tool based on AI SDK with file operations, code search, and command execution
Author: yuanyuan Wang
Latest version: 0.1.0

# kcode

**AI 驱动的智能编码助手**

[![npm version](https://img.shields.io/npm/v/kcode.svg)](https://www.npmjs.com/package/kcode)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)

[English](#english-documentation) | 简体中文

---

## ✨ 核心特性

### 🤖 智能对话引擎
- **流式响应**：实时流式输出，支持 Markdown 渲染
- **多模型支持**：内置智谱 AI、OpenAI 等多个模型，支持运行时切换
- **智能上下文管理**：自动 token 计算、上下文窗口监控、智能截断
- **项目感知**：自动检测项目类型、包管理器、主要依赖，注入上下文

### 🛠️ 强大的工具系统
- **文件操作**：读取、编辑、写入文件，支持行号范围
- **目录浏览**：列出目录内容，支持递归树形显示
- **代码搜索**：正则表达式搜索，glob 模式过滤
- **命令执行**：安全的 Shell 命令运行，超时控制
- **思考规划**：复杂任务前的推理规划工具
- **插件扩展**：支持自定义插件扩展工具能力

### 🔒 多层安全机制
- **路径安全**：防止目录遍历攻击，保护敏感文件（.env、.git、.ssh 等）
- **命令分级**：四级安全等级（SAFE / CAUTION / DANGEROUS / BLOCKED）
- **交互确认**：所有修改操作需用户确认，支持自动确认模式
- **自定义规则**：通过 .kcoderc.json 配置自定义安全规则

### 💎 优秀的用户体验
- **交互式界面**：REPL 循环、命令面板、Tab 补全
- **可视化展示**：工具调用面板、Diff 预览、Token 统计
- **会话管理**：自动保存/恢复会话、历史记录、命名会话
- **智能提示**：空闲提示、上下文警告、错误友好提示

---

## 📦 安装

### 全局安装（推荐）

```bash
# 使用 npm
npm install -g kcode

# 使用 pnpm
pnpm add -g kcode

# 使用 yarn
yarn global add kcode
```

### 从源码构建

```bash
git clone https://github.com/your-username/kcode.git
cd kcode
pnpm install
pnpm build
node dist/index.js
```

---

## 🚀 快速开始

### 1. 初始化配置

首次运行时，kcode 会自动引导您完成配置：

```bash
kcode
```

或手动初始化：

```bash
kcode init
```

### 2. 配置 API Key

创建 `.env` 文件或设置环境变量：

**智谱 AI（推荐，性价比高）**
```bash
# 获取 API Key: https://open.bigmodel.cn/usercenter/apikeys
OPENAI_API_KEY=your_api_key_here
OPENAI_BASE_URL=https://open.bigmodel.cn/api/paas/v4/
OPENAI_MODEL=GLM-4-Flash
```

**OpenAI**
```bash
OPENAI_API_KEY=sk-xxx
OPENAI_BASE_URL=https://api.openai.com/v1/
OPENAI_MODEL=gpt-4o-mini
```

### 3. 开始使用

```bash
kcode
```

---

## 💡 使用示例

### 代码阅读与分析

```
You: 读取 src/index.ts 文件的第 50-100 行

Agent: [使用 read_file 工具]
       显示文件内容...
       
You: 这个函数的作用是什么？

Agent: 这个函数实现了...
```

### 代码修改

```
You: 把 src/utils/helper.ts 中的 console.log 改成 console.error

Agent: [使用 edit_file 工具]
       显示 Diff 预览
       确认修改？(y/n): y
       ✓ Successfully edited src/utils/helper.ts
```

### 代码搜索

```
You: 搜索项目中所有 TODO 和 FIXME 注释

Agent: [使用 grep_search 工具]
       src/agent.ts:45:    // TODO: add retry logic
       src/tools/index.ts:12:  // FIXME: handle timeout
       ...
       找到 15 处匹配
```

### 命令执行

```
You: 运行测试并查看结果

Agent: [使用 run_command 工具]
       确认执行命令 `pnpm test`？(y/n): y
       ✓ Tests passed (12 suites, 45 tests)
```

### 复杂任务规划

```
You: 帮我重构用户认证模块，需要支持 JWT 和 OAuth

Agent: [使用 think 工具进行规划]
       
       我将按以下步骤进行：
       1. 首先阅读现有的认证模块代码
       2. 设计新的架构
       3. 实现 JWT 认证
       4. 实现 OAuth 认证
       5. 添加测试用例
       
       让我们开始第一步...
```

---

## 🎯 命令系统

### Slash 命令

| 命令 | 描述 |
|------|------|
| `/help` | 显示帮助信息 |
| `/tools` | 查看可用工具列表 |
| `/model` | 查看/切换 AI 模型 |
| `/model list` | 列出所有可用模型 |
| `/model switch <id>` | 切换到指定模型 |
| `/token` | 显示 Token 使用情况 |
| `/status` | 显示会话状态 |
| `/clear` | 清空对话历史 |
| `/save [name]` | 保存当前会话 |
| `/load` | 加载历史会话 |
| `/history` | 显示对话历史摘要 |
| `/undo` | 撤销最近的文件修改 |
| `/security` | 显示安全策略 |
| `/plugins` | 列出已加载的插件 |
| `/exit` | 保存会话并退出 |
| `/quit` | 保存会话并退出 |

### 命令面板

输入 `/` 打开交互式命令面板，支持：
- 模糊搜索命令
- 键盘导航
- 实时预览

### Tab 补全

- 文件路径补全
- 命令补全
- 模型名称补全

---

## ⚙️ 配置

### 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `OPENAI_API_KEY` | AI 服务 API 密钥 | 必填 |
| `OPENAI_BASE_URL` | API 基础 URL | 智谱 AI URL |
| `OPENAI_MODEL` | 默认使用的模型 | `GLM-4-Flash` |

### 命令行参数

```bash
kcode [options]

Options:
  -m, --model <model>    指定 AI 模型
  -r, --resume           恢复上一次会话
  -y, --yes              自动确认所有操作
  -h, --help             显示帮助信息
  -V, --version          显示版本号
```

### 项目配置文件 (.kcoderc.json)

在项目根目录创建 `.kcoderc.json` 自定义行为：

```json
{
  "projectDescription": "我的项目描述",
  "conventions": "使用函数式编程风格，禁止使用 var",
  "ignorePatterns": ["dist/**", "node_modules/**"],
  "additionalContext": "使用 pnpm 作为包管理器",
  "security": {
    "allow": ["npm run build"],
    "block": ["rm -rf dist"]
  }
}
```

---

## 🔌 插件系统

kcode 支持强大的插件系统，可以扩展工具能力。

### 插件位置

1. **项目本地插件**：`.kcode/plugins/` 目录
2. **全局插件**：`~/.kcode/plugins/` 目录
3. **npm 包插件**：`package.json` 中的 `kcodePlugins` 字段

### 插件示例

```javascript
// .kcode/plugins/my-plugin.js
module.exports = {
  name: 'my-plugin',
  version: '1.0.0',
  description: '我的自定义插件',
  
  tools: [
    {
      name: 'my_tool',
      description: '自定义工具描述',
      inputSchema: z.object({
        param: z.string().describe('参数描述'),
      }),
      execute: async (params) => {
        return '工具执行结果';
      },
    },
  ],
  
  setup: async () => {
    console.log('插件初始化');
  },
};
```

---

## 🧠 支持的模型

### 智谱 AI

| 模型 | 上下文窗口 | 描述 |
|------|-----------|------|
| GLM-4-Flash | 128K | 高性价比，速度快，适合日常对话 |
| GLM-4-Plus | 128K | 高性能，推理能力更强 |
| GLM-4-Air | 128K | 平衡型，性价比与性能兼顾 |
| GLM-4-AirX | 8K | 极速模型，响应最快 |
| GLM-4-Long | 1M | 长上下文，支持百万级 token |

### OpenAI

| 模型 | 上下文窗口 | 描述 |
|------|-----------|------|
| gpt-4o | 128K | 最新旗舰模型，多模态能力强 |
| gpt-4o-mini | 128K | 轻量级模型，速度快成本低 |
| gpt-4-turbo | 128K | GPT-4 增强版 |
| gpt-3.5-turbo | 16K | 经典模型，速度快成本低 |

### 自定义模型

支持任何兼容 OpenAI API 的模型：

```bash
OPENAI_BASE_URL=https://your-api-endpoint.com/v1/
OPENAI_MODEL=your-model-id
```

---

## 🗂️ 项目结构

```
kcode/
├── src/
│   ├── index.ts              # CLI 入口
│   ├── agent.ts              # Agent 核心实现
│   ├── prompt.ts             # 系统提示词
│   ├── context.ts            # 上下文模块导出
│   ├── commands/             # Slash 命令系统
│   │   ├── builtin.ts        # 内置命令
│   │   ├── registry.ts       # 命令注册中心
│   │   └── init.ts           # 初始化配置
│   ├── context/              # 上下文管理
│   │   └── index.ts          # 上下文管理器
│   ├── models/               # 模型管理
│   │   ├── index.ts
│   │   └── registry.ts       # 模型注册表
│   ├── plugins/              # 插件系统
│   │   ├── index.ts
│   │   ├── loader.ts         # 插件加载器
│   │   ├── types.ts          # 类型定义
│   │   └── safe-helpers.ts   # 安全辅助函数
│   ├── session/              # 会话管理
│   │   ├── index.ts
│   │   ├── session-manager.ts    # 会话管理器
│   │   └── backup-manager.ts     # 备份管理
│   ├── tools/                # 工具模块
│   │   ├── index.ts          # 工具注册
│   │   ├── registry.ts       # 工具注册表
│   │   ├── create-safe-tool.ts   # 安全工具工厂
│   │   ├── read_file.ts      # 文件读取
│   │   ├── write_file.ts     # 文件写入
│   │   ├── edit_file.ts      # 文件编辑
│   │   ├── list_files.ts     # 目录浏览
│   │   ├── grep_search.ts    # 代码搜索
│   │   ├── run_command.ts    # 命令执行
│   │   └── think.ts          # 思考工具
│   ├── ui/                   # 用户界面
│   │   ├── renderer.ts       # 输出渲染
│   │   ├── tool-panel.ts     # 工具面板
│   │   ├── diff-view.ts      # Diff 预览
│   │   ├── confirm.ts        # 确认对话框
│   │   ├── confirm-state.ts  # 确认状态管理
│   │   ├── command-palette.ts    # 命令面板
│   │   ├── completer.ts      # Tab 补全
│   │   ├── pager.ts          # 分页器
│   │   ├── spinner.ts        # 加载动画
│   │   └── ansi-utils.ts     # ANSI 工具函数
│   └── utils/                # 工具函数
│       ├── path-safety.ts    # 路径安全检查
│       ├── command-safety.ts # 命令安全检查
│       ├── constants.ts      # 常量定义
│       ├── error-types.ts    # 错误类型
│       ├── env-info.ts       # 环境信息
│       ├── tokens.ts         # Token 计算
│       ├── history.ts        # 历史管理
│       ├── input-history.ts  # 输入历史
│       └── truncate.ts       # 文本截断
├── dist/                     # 编译输出
├── package.json
├── tsconfig.json
└── README.md
```

---

## 🔐 安全说明

### 路径安全

自动阻止访问：
- 环境变量文件：`.env`, `.env.local`, `.env.production`
- Git 配置：`.git/config`, `.git/credentials`
- SSH 密钥：`.ssh/` 目录下的所有文件
- 证书文件：`*.pem`, `*.key`, `*.p12`
- 凭据文件：`credentials.json`, `secrets.json`
- 云服务配置：`.aws/`, `.azure/`, `.gcloud/`

### 命令安全分级

| 等级 | 说明 | 示例 | 行为 |
|------|------|------|------|
| **SAFE** | 安全命令 | `ls`, `cat`, `npm install` | 无需确认 |
| **CAUTION** | 需谨慎 | `npm publish`, `git push` | 需确认 |
| **DANGEROUS** | 危险命令 | `rm -rf`, `git push --force` | 需额外确认 |
| **BLOCKED** | 禁止执行 | `rm -rf /`, `mkfs` | 完全阻止 |

### 自动确认模式

使用 `-y` 参数跳过所有确认提示（谨慎使用）：

```bash
kcode -y
```

---

## 🧪 开发指南

### 环境准备

```bash
# 克隆仓库
git clone https://github.com/your-username/kcode.git
cd kcode

# 安装依赖
pnpm install

# 配置环境变量
cp .env.example .env
# 编辑 .env 填入 API Key
```

### 开发命令

```bash
# 开发模式运行
pnpm dev

# 运行测试
pnpm test

# 测试特定文件
pnpm test src/tools/__tests__/read_file.test.ts

# 测试覆盖率
pnpm test --coverage

# 构建生产版本
pnpm build

# 类型检查
pnpm tsc --noEmit
```

### 编写测试

kcode 使用 Vitest 进行测试：

```typescript
import { describe, it, expect } from 'vitest';

describe('MyTool', () => {
  it('should work correctly', async () => {
    const result = await myFunction('input');
    expect(result).toBe('expected output');
  });
});
```

### 调试技巧

```bash
# 启用调试日志
DEBUG=kcode:* pnpm dev

# 查看详细错误信息
pnpm dev 2>&1 | tee debug.log
```

---

## 🤝 贡献指南

欢迎贡献代码、报告问题或提出建议！

### 贡献流程

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

### 代码规范

- 使用 TypeScript 编写代码
- 遵循 ESLint 规则
- 添加必要的单元测试
- 更新相关文档

---

## 📝 更新日志

### v1.0.0 (2025-03-13)

- ✨ 首次发布
- 🎯 支持多模型切换（智谱 AI、OpenAI、自定义模型）
- 🔒 完善的安全机制（路径安全、命令分级）
- 🔌 插件系统支持
- 💎 流式 Markdown 渲染
- 🛠️ 完整的工具集（文件操作、目录浏览、代码搜索、命令执行）
- 📂 会话管理（自动保存/恢复、历史记录）
- 🎨 交互式命令面板和 Tab 补全

---

## ❓ 常见问题

<details>
<summary><b>Q: 如何切换模型？</b></summary>

使用 `/model` 命令查看当前模型，使用 `/model <model-id>` 切换模型：

```
/model gpt-4o
```

或在启动时指定：

```bash
kcode -m gpt-4o
```
</details>

<details>
<summary><b>Q: 如何恢复上次的会话？</b></summary>

使用 `-r` 参数：

```bash
kcode -r
```

或在运行时使用 `/load` 命令。
</details>

<details>
<summary><b>Q: Token 超限怎么办？</b></summary>

kcode 会自动管理上下文窗口：
- 使用 `/clear` 清空对话
- 使用 `/save` 保存当前会话后开始新会话
- 切换到更大上下文窗口的模型（如 GLM-4-Long）
</details>

<details>
<summary><b>Q: 如何添加自定义工具？</b></summary>

创建插件文件 `.kcode/plugins/my-plugin.js`，导出符合 `KcodePlugin` 接口的对象。详见[插件系统](#插件系统)章节。
</details>

---

## 📄 License

MIT License © 2024

---

## 🙏 致谢

- [AI SDK](https://sdk.vercel.ai/) - 强大的 AI 应用开发框架
- [智谱 AI](https://open.bigmodel.cn/) - 高性价比的 AI 模型服务
- [OpenAI](https://openai.com/) - GPT 系列模型
- [Commander](https://github.com/tj/commander.js/) - 命令行参数解析
- [Chalk](https://github.com/chalk/chalk) - 终端彩色输出

---

<div align="center">

**如果这个项目对你有帮助，请给一个 ⭐️ Star！**

Made with ❤️ by the kcode team

</div>

---

# English Documentation

## ✨ Features

### 🤖 Intelligent Conversation Engine
- **Streaming Response**: Real-time streaming output with Markdown rendering
- **Multi-Model Support**: Built-in Zhipu AI, OpenAI models with runtime switching
- **Smart Context Management**: Automatic token calculation, context window monitoring, intelligent truncation
- **Project Awareness**: Auto-detect project type, package manager, main dependencies

### 🛠️ Powerful Tool System
- **File Operations**: Read, edit, write files with line range support
- **Code Search**: Regex search with glob pattern filtering
- **Command Execution**: Safe shell command execution with timeout control
- **Thinking Tool**: Reasoning and planning for complex tasks
- **Plugin Extension**: Custom plugin support for tool extensibility

### 🔒 Multi-layer Security
- **Path Security**: Prevent directory traversal, protect sensitive files
- **Command Classification**: Four-level safety (SAFE/CAUTION/DANGEROUS/BLOCKED)
- **Interactive Confirmation**: All modifications require user confirmation
- **Custom Rules**: Configure security rules via .kcoderc.json

### 💎 Excellent UX
- **Interactive Interface**: REPL loop, command palette, tab completion
- **Visual Display**: Tool call panel, diff preview, token statistics
- **Session Management**: Auto-save/restore, history, named sessions
- **Smart Hints**: Idle hints, context warnings, friendly error messages

## 📦 Installation

```bash
# npm
npm install -g kcode

# pnpm
pnpm add -g kcode

# yarn
yarn global add kcode
```

## 🚀 Quick Start

```bash
# Initialize configuration
kcode init

# Start using
kcode

# Resume last session
kcode -r

# Use specific model
kcode -m gpt-4o
```

## 📄 License

MIT License © 2024