npm package: @perdream-cli/know-cli
Description: AI-powered Code Review CLI Tool
Author: Perdream
Latest version: 1.0.16


<div align="center">

# 🔍 Know CLI

**AI-Powered Code Review CLI Tool**

[![npm version](https://img.shields.io/npm/v/@perdream-cli/know-cli.svg)](https://www.npmjs.com/package/@perdream-cli/know-cli)
[![license](https://img.shields.io/npm/l/@perdream-cli/know-cli.svg)](./LICENSE)
[![node](https://img.shields.io/node/v/@perdream-cli/know-cli.svg)](https://nodejs.org)

基于 Vercel AI SDK 的智能代码评审工具，支持多 LLM Provider 动态配置、多智能体并行评审、MCP 知识服务器集成。

[快速开始](#-快速开始) · [命令参考](#-命令参考) · [配置指南](#️-配置) · [CI/CD 集成](#-cicd-集成)

</div>

---

## ✨ 特性

- 🤖 **多 Provider 支持** — 内置 Anthropic / OpenAI / Google / Ollama，支持通过配置文件零代码扩展任意 `@ai-sdk/*` Provider
- 🧠 **AI 自适应评审策略** — 规划 Agent 根据变更集特征动态决定分块策略和 Agent 数量，非固定模板
- ⚡ **多智能体并行评审** — 相关文件智能分组，多 Agent 并行处理，大型 PR 评审效率成倍提升
- 🔌 **MCP 知识服务器** — 通过 Model Context Protocol 连接企业知识库，团队规范集中管理、自动同步
- 🎯 **Skill 按需加载** — 只注入规则目录到 Prompt，LLM 自主判断并按需检索完整规则，上下文窗口利用率提升 ~18 倍
- 🔒 **安全修复应用** — 所有代码修复在隔离的 Git Worktree 沙箱中执行，工作目录零风险
- 📊 **多格式输出** — Terminal（彩色）/ Markdown / JSON / SARIF，原生支持 GitHub Code Scanning
- 🔄 **反馈学习闭环** — 用户反馈自动存储并注入为 few-shot 示例，零训练成本的个性化评审
- 🔐 **OAuth 2.0 鉴权** — MCP 服务器连接支持 OAuth 2.0 + PKCE，Token 自动持久化

---

## 📦 安装

```bash
# 全局安装
npm install -g @perdream-cli/know-cli

# 或项目级安装
npm install --save-dev @perdream-cli/know-cli
```

**环境要求：** Node.js >= 18.0.0，Git

---

## 🚀 快速开始

### 1. 初始化项目

```bash
know init
```

这将在项目根目录创建以下结构：

```
.know/
├── rules/
│   ├── security.md      # 安全评审规则
│   ├── performance.md   # 性能评审规则
│   └── style.md         # 代码风格规则
└── mcp.json             # MCP 知识服务器配置
.knowrc.yml              # Know CLI 配置文件
```

### 2. 配置 LLM Provider

编辑 `.knowrc.yml`：

```yaml
provider: anthropic
model: claude-sonnet-4-20250514
apiKey: sk-xxx  # 或设置环境变量 ANTHROPIC_API_KEY
language: zh
```

### 3. 执行评审

```bash
# 评审暂存区变更（默认）
know review

# 评审与 main 分支的差异
know review -b main

# 评审指定文件
know review -f src/app.ts src/utils.ts

# 评审最近 3 次提交
know review -c HEAD~3

# CI 模式，遇到错误返回非零退出码
know review --ci --fail-on error
```

---

## 📋 命令参考

### `know review` — AI 代码评审

核心命令，提取 Git diff 并通过多智能体流水线进行智能评审。

```bash
know review [options]
```

| 参数 | 说明 | 示例 |
|------|------|------|
| `-b, --branch <branch>` | 对比目标分支 | `know review -b main` |
| `-c, --commit <ref>` | 对比提交引用 | `know review -c HEAD~3` |
| `-f, --files <paths...>` | 指定评审文件 | `know review -f src/a.ts src/b.ts` |
| `--format <fmt>` | 输出格式: `terminal` / `markdown` / `json` / `sarif` | `know review --format markdown` |
| `-o, --output <path>` | 输出到文件 | `know review -o report.md` |
| `--ci` | CI 模式（非交互式，问题超阈值返回非零退出码） | `know review --ci` |
| `--fail-on <level>` | CI 失败阈值: `error` / `warning` | `know review --ci --fail-on warning` |
| `--provider <id>` | 覆盖 LLM Provider | `know review --provider openai` |
| `--model <name>` | 覆盖模型名称 | `know review --model gpt-4o` |
| `--lang <language>` | 评审语言: `zh` / `en` | `know review --lang en` |
| `--concurrency <n>` | 最大并发数 | `know review --concurrency 5` |
| `--mcp-config <path>` | MCP 配置文件路径 | `know review --mcp-config ./mcp.json` |
| `--team <team>` | MCP 知识规则团队范围 | `know review --team backend` |
| `--project <project>` | MCP 知识规则项目范围 | `know review --project myapp` |

### `know apply` — 安全应用修复

在隔离的 Git Worktree 沙箱中应用 AI 建议的代码修复，确认前可随时安全回滚。

```bash
know apply [options]
```

| 参数 | 说明 |
|------|------|
| `-a, --all` | 应用所有可修复的问题 |
| `-s, --select <indices>` | 指定问题索引（从 1 开始，逗号分隔，如 `1,3,5`） |
| `--strategy 
` | 合并策略: `cherry-pick`（默认）/ `merge` / `patch` |
| `--validate <cmds...>` | 应用后运行的验证命令（如 `npm test`） |
| `-y, --yes` | 跳过确认提示 |
| `--no-preview` | 不显示 diff 预览 |
| `--provider <provider>` | 覆盖 LLM Provider |
| `--model <model>` | 覆盖模型名称 |

**使用示例：**

```bash
# 交互式选择修复
know apply

# 应用所有修复并运行验证
know apply --all --validate "npm run build" --validate "npm test"

# 生成补丁而非直接合并
know apply --strategy patch
```

### `know feedback` — 反馈学习

对评审结果提供反馈，帮助 AI 学习团队偏好，提高未来评审准确性。

```bash
know feedback [options]
```

| 参数 | 说明 |
|------|------|
| `--accept <indices>` | 按索引接受建议（如 `1,3,5`） |
| `--reject <indices>` | 按索引拒绝建议（如 `2,4`） |
| `-r, --reason <text>` | 拒绝原因 |
| `--stats` | 查看反馈统计 |

```bash
# 交互式逐条反馈
know feedback

# 批量接受
know feedback --accept 1,3,5

# 批量拒绝并附带原因
know feedback --reject 2,4 --reason "团队规范不同"

# 查看统计
know feedback --stats
```

### `know providers` — Provider 管理

查看和管理可用的 LLM Provider。

```bash
# 列出所有可用 Provider
know providers

# 查看特定 Provider 的模型列表
know providers --models openai

# 查看配置文件路径
know providers --config
```

### `know worktree` — Worktree 管理

管理 `know apply` 创建的 Git Worktree 环境。

```bash
# 列出所有活跃的 worktree
know worktree --list

# 清理过期 worktree（超过 24 小时）
know worktree --cleanup
```

### `know init` — 项目初始化

```bash
know init          # 初始化
know init --force  # 强制覆盖已有配置
```

---

## ⚙️ 配置

### 配置优先级

```
CLI 参数 > 环境变量 > 项目配置文件 > Provider 全局配置 > 内置默认值
```

1. CLI 参数（`--provider`、`--model` 等）
2. 环境变量（`KNOW_PROVIDER`、`KNOW_MODEL`、`KNOW_API_KEY`）
3. 项目配置文件（`.knowrc.yml`、`.knowrc.json`、`know.config.js`）
4. Provider 全局配置（`~/.config/know/know.json`）
5. 内置默认值（Provider: `anthropic`，Model: `claude-sonnet-4-20250514`）

### 环境变量

| 变量 | 说明 |
|------|------|
| `KNOW_PROVIDER` | LLM Provider |
| `KNOW_MODEL` | 模型名称 |
| `KNOW_API_KEY` | API Key（通用） |
| `ANTHROPIC_API_KEY` | Anthropic API Key |
| `OPENAI_API_KEY` | OpenAI API Key |
| `GOOGLE_GENERATIVE_AI_API_KEY` | Google AI API Key |
| `KNOW_MCP_CONFIG` | MCP 配置文件路径 |
| `KNOW_MCP_TEAM` | MCP 团队范围 |
| `KNOW_MCP_PROJECT` | MCP 项目范围 |

### 自定义 Provider

编辑 `~/.config/know/know.json`，即可零代码接入任意 `@ai-sdk/*` 兼容 Provider：

```json
{
  "provider": {
    "bailian-coding-plan": {
      "npm": "@ai-sdk/anthropic",
      "name": "百炼模型服务",
      "options": {
        "baseURL": "https://coding.dashscope.aliyuncs.com/apps/anthropic/v1",
        "apiKey": "YOUR_API_KEY"
      },
      "models": {
        "qwen3.5-plus": {
          "name": "Qwen3.5 Plus",
          "modalities": { "input": ["text", "image"], "output": ["text"] },
          "options": { "thinking": { "type": "enabled", "budgetTokens": 8192 } },
          "limit": { "context": 1000000, "output": 65536 }
        },
        "qwen3-coder-plus": {
          "name": "Qwen3 Coder Plus",
          "modalities": { "input": ["text"], "output": ["text"] },
          "limit": { "context": 1000000, "output": 65536 }
        }
      }
    }
  }
}
```

使用方式：

```bash
know review --provider bailian-coding-plan --model qwen3.5-plus
```

### 自定义评审规则

在 `.know/rules/` 目录下创建 Markdown 文件，支持 YAML front matter：

```markdown
---
name: react-hooks
description: React Hooks 最佳实践检查
severity: warning
glob:
  - "**/*.tsx"
  - "**/*.jsx"
---
检查以下 React Hooks 问题：
1. useEffect 缺少依赖项
2. 在循环或条件中使用 Hook
3. 自定义 Hook 未以 "use" 开头
```

---

## 🔌 MCP 知识服务器

通过 MCP（Model Context Protocol）连接企业知识库，统一管理团队评审规范。

编辑 `.know/mcp.json`：

### 静态 Token 鉴权

```json
{
  "mcpServers": {
    "knowledge-server": {
      "url": "https://your-server.com/mcp/http",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}
```

### OAuth 2.0 鉴权

支持 Authorization Code + PKCE 流程，首次连接自动打开浏览器授权，Token 持久化到 `~/.config/know/oauth/<server>/`。

```json
{
  "mcpServers": {
    "knowledge-server": {
      "url": "https://your-server.com/mcp/http",
      "oauth": {
        "clientId": "your-client-id",
        "clientSecret": "your-client-secret",
        "scope": "read write",
        "callbackPort": 8900
      }
    }
  }
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `clientId` | string | 否 | 预注册的 OAuth 客户端 ID |
| `clientSecret` | string | 否 | OAuth 客户端密钥 |
| `scope` | string | 否 | 请求的权限范围（空格分隔） |
| `callbackPort` | number | 否 | 本地回调端口（默认 `8900`） |
| `clientName` | string | 否 | 动态注册时的客户端名称（RFC 7591） |

---

## 🔄 CI/CD 集成

### GitHub Actions

```yaml
name: Code Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 18
      - run: npm install -g @perdream-cli/know-cli
      - run: know review --branch origin/main --ci --fail-on warning --format sarif --output review.sarif
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: review.sarif
```

### GitLab CI

```yaml
code-review:
  image: node:18
  script:
    - npm install -g @perdream-cli/know-cli
    - know review --branch $CI_MERGE_REQUEST_TARGET_BRANCH_NAME --ci --format json --output review.json
  artifacts:
    paths:
      - review.json
  only:
    - merge_requests
```

---

## 📊 输出格式

| 格式 | 说明 | 适用场景 |
|------|------|----------|
| `terminal` | 彩色终端输出，内联 diff 上下文高亮 | 开发者日常使用 |
| `markdown` | 结构化 Markdown 报告 | Pull Request 评论 |
| `json` | 结构化 JSON 数据 | 程序化集成 |
| `sarif` | SARIF 2.1.0 标准格式 | GitHub Code Scanning |

---

## 🛠️ 本地开发

```bash
# 克隆项目
git clone <repo-url>
cd know-cli

# 安装依赖
npm install

# 开发模式运行
npm run dev -- review -b main

# 构建
npm run build

# 全局链接测试
npm link
know review --help
```

---

## 📄 License

[MIT](./LICENSE) © [Perdream](https://github.com/perdream)