快速上手 (Getting Started)

本教程带你从零跑通 KKCode，并体验其核心能力：配置 LLM、使用 MCP 工具、开启多 Agent Team。

1. 安装

需要 Python ≥ 3.11 与 uv。

git clone https://github.com/wcy12378/KKCode.git
cd KKCode

# 方式 A：uv（推荐）
uv sync

# 方式 B：pip
python -m venv .venv && source .venv/bin/activate
pip install -e .

2. 配置 LLM

KKCode 通过 .kkcode/config.yaml 读取配置。首次使用请复制模板：

cp .kkcode/config.yaml.example .kkcode/config.yaml

编辑 .kkcode/config.yaml：

providers:
  - name: deepseek
    protocol: openai          # Anthropic 用 anthropic
    base_url: https://api.deepseek.com/v1
    api_key: "sk-your-key-here"   # 或 ${DEEPSEEK_API_KEY} 引用环境变量
    model: deepseek-chat
    thinking: false

permission_mode: default      # default | plan | bypass

所有配置项见 configuration.md。

3. 启动

kkcode                # 安装后
# 或
python -m kkcode

进入 TUI 后，直接输入自然语言任务即可，例如：

> 给当前仓库写一个读取 CSV 并统计列均值的脚本

Agent 会进入 ReAct 循环：规划 → 调用工具（读写文件、运行命令）→ 观察结果 → 继续，直到任务完成。

4. 接入 MCP 工具

在 config.yaml 的 mcp_servers 下追加服务，重启动即可获得新工具：

mcp_servers:
  - name: context7
    command: npx
    args: ["-y", "@upstash/context7-mcp"]

stdio 类型：提供 command + args。
HTTP / SSE 类型：提供 url，可选 transport: http | sse 与 headers。

KKCode 会按 MCP 三策略延迟加载自动决定工具描述何时进入上下文，避免窗口被挤占。

5. 多 Agent 协作（Team 模式）

当任务可拆分为相互独立的子任务时，可开启 Team 模式，由 Coordinator 并行派发：

> /team 把 src 下三个模块分别做单元测试补全，最后汇总

每个 teammate 在独立 Git Worktree 中工作，通过文件锁邮箱通信，互不踩文件。详见 team-collaboration.md。

6. 长会话与上下文

在 8 小时级连续会话中，KKCode 会自动：

将超大工具结果落盘（Layer1），仅保留预览；
在历史逼近阈值时做 LLM 结构化摘要（Layer2），并保住近期原文；
失败时触发熔断器 / PTL 重试，保证会话不中断。

详见 context-compaction.md。

7. 下一步

阅读配置参考解锁权限模式、沙箱、Coordinator 等高级选项。
阅读架构总览理解整体设计。
阅读贡献指南参与开发。

FilesExpand file tree

getting-started.md

Latest commit

History