# KCode 用户指南

本文说明 KCode 的安装、初始化、启动、模型配置和升级。Harness 阶段细节见 [Harness 工作流](HARNESS_WORKFLOW.md)，所有命令和工具参数见 [命令参考](COMMAND_REFERENCE.md)。

## 安装

环境要求：

- Node.js `>=22.19.0`
- npm
- Windows 环境使用 Windows Terminal
- 无需安装 Python。KCode 随包工具使用 Node/TypeScript 实现；只有业务项目或外部脚本明确依赖 Python 时才另行安装。

全局安装：

```powershell
npm install -g kcode-pi
```

安装后使用全局命令：

```powershell
kcode
```

## 初始化业务项目

在终端进入实际业务项目根目录，不是 KCode 源码目录。

初始化项目级配置：

```powershell
kcode init
```

`init` 会登记 KCode package，并生成项目常驻上下文：

```text
.pi/settings.json
.pi/kd/PROJECT_CONTEXT.md
```

项目结构变化后刷新上下文：

```powershell
kcode ctx --refresh
```

需要查询 PostgreSQL、SQL Server 或 Oracle 元数据时，写入项目级 MCP 配置：

```powershell
kcode db
```

数据库凭证必须通过环境变量提供，不能写入仓库文件。详细配置见 [数据库 MCP](DATABASE_MCP.md)。

检查环境：

```powershell
kcode -v
```

完整终端命令说明见 [命令参考](COMMAND_REFERENCE.md#终端命令)。

## 启动 KCode

```powershell
kcode
```

`kcode` 会自动初始化项目配置、检查环境，然后启动随包 Pi CLI。
```

## 配置模型

首次启动 Pi 时出现以下信息：

```text
Warning: No models available.
```

说明还没有配置模型供应商。进入 `kcode start` 后输入：

```text
/login
```

选择供应商并登录或填写 API Key。常见选择包括：

```text
ChatGPT Plus/Pro (Codex)
Claude Pro/Max
GitHub Copilot
OpenAI
Anthropic
DeepSeek
Gemini
```

支持在 PowerShell 中设置环境变量后再启动：

```powershell
$env:OPENAI_API_KEY="sk-..."
kcode start
```

登录或配置完成后，在 Pi 中选择模型：

```text
/model
```

KCode 在 Pi 内注册的 `/kd-*` 命令见 [命令参考](COMMAND_REFERENCE.md#pi-内命令)。

## 自定义模型供应商

模型服务为企业网关、代理服务、Ollama、LM Studio、vLLM 或其他 OpenAI-compatible endpoint 时，无需修改 KCode。Pi 原生支持通过用户级配置文件添加自定义供应商：

```powershell
notepad $env:USERPROFILE\.pi\agent\models.json
```

写入或合并：

```json
{
  "providers": {
    "corp-ai": {
      "baseUrl": "https://ai.example.com/v1",
      "api": "openai-completions",
      "apiKey": "$CORP_AI_API_KEY",
      "compat": {
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false
      },
      "models": [
        {
          "id": "corp-coder",
          "name": "Corp Coder",
          "reasoning": false,
          "input": ["text"],
          "contextWindow": 128000,
          "maxTokens": 16384,
          "cost": {
            "input": 0,
            "output": 0,
            "cacheRead": 0,
            "cacheWrite": 0
          }
        }
      ]
    }
  }
}
```

再设置 API Key 并启动：

```powershell
$env:CORP_AI_API_KEY="sk-..."
kcode start
```

支持直接指定：

```powershell
kcode start --provider corp-ai --model corp-coder
```

## 升级

查看当前安装版本：

```powershell
kcode version
npm ls -g kcode-pi --depth=0
```

查看 npm 最新版本：

```powershell
npm view kcode-pi version
```

升级：

```powershell
npm install -g kcode-pi@latest
kcode version
```

升级后在业务项目根目录执行：

```powershell
kcode init
kcode check --deep
```

升级失败或仍加载旧版本时，按 [故障排查](TROUBLESHOOTING.md) 处理。