{"id":"d95ee53c-78ea-488e-9b65-e27c80d67ae9","slug":"kkcode","kind":"mcp","name":"KKCode","summary":"轻量级终端coding agent KKCode — Terminal AI coding agent with two-layer context compaction, MCP lazy-loading, multi-agent team & OS sandbox","owner":"wcy12378","repoUrl":"https://github.com/wcy12378/KKCode","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-08-15T07:44:17.000Z","addedAt":"2026-10-21T21:45:00.860Z","logoUrl":"https://avatars.githubusercontent.com/u/192684309?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["memory-knowledge"],"tags":[],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T04:22:10.863Z","sample":false,"url":"https://conduits.dev/tools/kkcode","language":"Python","transports":["stdio"],"install":{"pypi":"kkcode"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"
\n\n
\n\n\n

\n \"KKCode\n

\n\n\n\"KKCode\"\n\n# KKCode\n\n

\n 轻量级 · 多协议 · 终端 AI 编程助手
\n 面向长会话的工程化 Agent —— 两层上下文压缩、MCP 延迟加载、六层权限裁决与多 Agent 协作\n

\n\n

\n \"License\"\n \"Python\"\n \"Tests\"\n \"Type\n \"CI\"\n \"Architecture\"\n

\n\n
\n\n---\n\n## 💭 为什么再造一个 Coding Agent\n\nClaude Code 已经很好了。但我决定自己造一遍，原因有两个：\n\n### 工程角度——黑盒里看不清路\n\n光看 Claude Code 的输入输出，搞不清内部每一层是怎么取舍的。\n\nAgent Loop 看起来就是一个 while 循环加几个条件判断，几十行代码。\n但真写下来才发现**坑全在边界上**：\n\n> 用户中途按 ESC 打断，模型返回的三个工具调用只执行完一个，\n> 剩下两个不补结果，下一轮调 API 直接报错；\n> 压缩切点恰好落在 tool_use 和 tool_result 之间，历史又不合法了。\n\n这些约束是**协议层面**的，框架替你兜不住，用框架的人一样会撞上。\n自己写完这一遍，Agent 里每一层为什么这么设计，才算真的说清楚。\n\n### 产品角度——闭源不可审计\n\nClaude Code 本质上是闭源的（即使有泄漏的开源快照，那个版本迟早过时）。\n自研版本可以审计每一步行为，落地到企业内部更可控。\n\n至于为什么不用 LangChain 之类的现成框架——我认真调研过，最后没用。\nLangChain 最值钱的部分在广度上：能接很多模型、连很多数据源、搭 RAG 应用确实省事。\n但我的场景很窄很深：只需要 Anthropic 和 OpenAI 两套协议、\n几个内置工具加 MCP 扩展。它最强的部分恰好是我用不上的。\n\n后来去看 Claude Code、Codex、OpenCode 这些做得比较好的产品，\n发现它们也都没用 Agent 框架，Loop 都是自己写的。\n说明这个选择不是我一个人这么想。\n\n### 不是替代，是讲明白\n\n这个项目的定位**不是替代 Claude Code**，\n而是把 Coding Agent 的每一层拆开来讲清楚。\n从 ReAct 循环到协议约束，从流式解析到上下文压缩，\n每一行都能解释为什么这么写。\n\n---\n\n## ✨ 核心特性\n\n| # | 特性 | 机制说明 | 代码位置 |\n|---|------|---------|---------|\n| 1 | 🧠 **ReAct Agent 引擎** | Thought → Action → Observation 循环；批量工具调用、流式中断恢复、紧急压缩重试 | [`kkcode/agent.py`](kkcode/agent.py) |\n| 2 | 🔌 **MCP 三策略延迟加载** | `EAGER` / `NATIVE` / `DISPATCH` 按 schema 占窗口比例自动选择，按需展开工具定义，避免上下文窗口被工具描述挤占 | [`kkcode/mcp/loading_strategy.py`](kkcode/mcp/loading_strategy.py) |\n| 3 | 🗜️ **两层上下文压缩** | Layer1 幂等落盘大工具结果 + Layer2 LLM 结构化摘要；含熔断器、PTL 重试与恢复段保尾 | [`kkcode/context/manager.py`](kkcode/context/manager.py) |\n| 4 | 🔒 **六层权限裁决 + OS 沙箱** | Layer 0–5 分级裁定 + Linux `bwrap` / macOS `seatbelt` 内核级隔离 + Pattern 记忆减少重复确认 | [`kkcode/permissions/`](kkcode/permissions) · [`kkcode/sandbox/`](kkcode/sandbox) |\n| 5 | 👥 **多 Agent Team 协作** | 网状通信、文件锁邮箱、Git Worktree 隔离、Coordinator 调度并行 worker | [`kkcode/teams/`](kkcode/teams) · [`kkcode/worktree/`](kkcode/worktree) |\n| 6 | 💾 **会话持久化与记忆** | JSONL 落盘断点恢复 + 长期记忆 consolidation 自动提炼 | [`kkcode/conversation.py`](kkcode/conversation.py) · [`kkcode/memory/`](kkcode/memory) |\n\n> 设计目标是让 Agent 在**长时间连续编程会话**中保持上下文连贯、工具可用、执行安全 —— 而不是一次性的问答玩具。\n\n---\n\n## 🏗️ 架构\n\n

\n \"KKCode\n

\n\n> **LLM-Powered Autonomous Coding Agent Runtime** —— 从用户交互层到执行环境层的完整技术栈。核心为 ReAct Agent Loop（Reason → Act → Observe），外围覆盖多 Agent 协作、MCP 动态工具加载、多层记忆、六层权限裁决与 OS 沙箱隔离。\n\n详细机制拆解见 [核心机制详解](#-核心机制详解)。\n\n---\n\n## 🚀 快速开始\n\n> 需要 Python ≥ 3.11 与 [`uv`](https://github.com/astral-sh/uv)（也支持 `pip`）。\n\n### 1. 安装\n\n```bash\ngit clone https://github.com/wcy12378/KKCode.git\ncd KKCode\nuv sync # 或使用: pip install -e .\n```\n\n### 2. 配置 LLM\n\n复制配置模板并填入你的 API Key：\n\n```bash\ncp .kkcode/config.yaml.example .kkcode/config.yaml\n```\n\n```yaml\n# .kkcode/config.yaml\nproviders:\n - name: deepseek\n api_key: \"sk-your-key-here\" # 或使用环境变量 ${DEEPSEEK_API_KEY}\n model: deepseek-chat\n base_url: https://api.deepseek.com/v1\n\nmcp_servers:\n - name: context7\n command: npx\n args: [\"-y\", \"@upstash/context7-mcp\"]\n```\n\n> 完整配置项（模型、权限模式、MCP 加载策略、沙箱开关等）见 [docs/configuration.md](docs/configuration.md)。\n\n### 3. 运行\n\n```bash\nkkcode # 安装后直接使用 CLI\n# 或\npython -m kkcode # 等价于上面\n```\n\n### 安装说明\n\n- **依赖管理**：推荐使用 [`uv`](https://docs.astral.sh/uv/)（零配置 Python 包管理器），`uv sync` 会自动创建隔离虚拟环境并锁定依赖版本；也支持传统 `pip install -e .`。\n- **配置隔离**：API Key 通过 `.kkcode/config.yaml` 配置（模板见 `.kkcode/config.yaml.example`，已被 `.gitignore` 忽略，不会提交到仓库）；也支持通过环境变量注入——**优先读取环境变量，缺失时回退配置文件**（见下方）。\n- **状态保留**：会话通过 JSONL 落盘，关闭后重新打开可从断点恢复；恢复时会自动校验对话链合法性，截断不完整的轮次。\n\n---\n\n## 📚 核心机制详解\n\n每一篇都链接到**真实代码位置**，可直接 `git clone` 后对照阅读：\n\n| 机制 | 文档 | 关键代码 |\n|------|------|---------|\n| MCP 三策略延迟加载 | [docs/mcp-lazy-loading.md](docs/mcp-lazy-loading.md) | `mcp/loading_strategy.py` |\n| 两层上下文压缩 | [docs/context-compaction.md](docs/context-compaction.md) | `context/manager.py` |\n| 六层权限裁决与 OS 沙箱 | [docs/permissions-sandbox.md](docs/permissions-sandbox.md) | `permissions/checker.py` · `sandbox/` |\n| 多 Agent Team 协作 | [docs/team-collaboration.md](docs/team-collaboration.md) | `teams/` · `worktree/` |\n| 系统架构总览 | [docs/architecture.md](docs/architecture.md) | — |\n| 记忆系统 | [docs/memory-system.md](docs/memory-system.md) | `memory/` |\n\n延伸阅读：[快速上手](docs/getting-started.md) · [配置参考](docs/configuration.md) · [开发指南](docs/DEVELOPMENT.md)\n\n---\n\n## ⚖️ 与主流方案的差异\n\n### 一句话定位\n\nKKCode 是一个**学习型参考实现**——目标是把终端 AI 编程助手的每一层架构走通、讲清楚，\n提供一个完全透明、可审计、可修改的 Code Agent 运行时。\n\n### 对比总览\n\n| 维度 | KKCode | Claude Code | Codex / OpenCode |\n|------|--------|-------------|------------------|\n| **定位** | 学习项目 / 可审计参考实现 | 商业产品（~2000 TS 文件，专职团队） | 商业产品 |\n| **架构透明度** | 每一层从零编写，无黑盒依赖 | 闭源（有泄漏快照但会过时） | 闭源 |\n| **LLM 支持** | Anthropic + OpenAI 兼容（DeepSeek/GLM 等），配置切换 | 硬绑 Anthropic 协议 | 各自有绑定 |\n| **上下文管理** | 两层压缩（L1 落盘 / L2 摘要 + 熔断器） | 5-6 层多粒度压缩策略 | 各有方案 |\n| **工具生态** | 8 内置核心工具 + MCP 扩展 | 50+ 覆盖垂直场景 | 各有方案 |\n| **企业适配** | 可审计、可私有部署、可替换任意 LLM 后端 | 受限于 Anthropic 生态 | 受限于各自厂商 |\n| **产品成熟度** | 学习阶段，骨架正确，细节打磨中 | 生产级（LSP/OAuth/语音/IDE Bridge） | 生产级 |\n\n### KKCode 的取舍优势\n\n**架构完全透明**：权限五层怎么短路、压缩怎么分级、\n多 Agent 消息怎么投递，每一行都能解释为什么这么写。\n\n**多模型原生**：LLM Client 从一开始就抽象了两套协议，\n实际跑过 DeepSeek、GLM 等兼容端点。Claude Code 硬绑 Anthropic，这方面反而受限。\n\n**可控性**：不依赖任何闭源运行时，适合需要审计每一步行为的场景。\n\n### 诚实的差距\n\n不在架构，在**细节打磨和边界覆盖**。\n产品级意味着每一个异常路径都要有优雅降级，\n每一个用户交互都要有合理反馈。\n\n比如 Claude Code 的 StreamingToolExecutor 里有 sibling abort 机制——\n一个 Bash 工具报错能立刻终止同批次其他子进程；\n有 file history 做文件级 checkpoint，改坏了能 undo。\n这些都是真实用户踩坑之后才补上的防御层，\n不是架构设计阶段能预见的。\n\nKKCode 的架构骨架是对的，但从骨架到产品之间差的是几千个这样的细节。\n\n---\n\n## 🧩 能力一览\n\n| 模块 | 一句话说明 | 入口 |\n|------|-----------|------|\n| **ReAct Agent 引擎** | Thought → Action → Observation 主循环；批量工具调用、流式中断恢复 | [`kkcode/agent.py`](kkcode/agent.py) |\n| **MCP 客户端** | stdio / HTTP-SSE 双模式；三策略延迟加载（EAGER/NATIVE/DISPATCH） | [`kkcode/mcp/`](kkcode/mcp/) |\n| **上下文压缩** | L1 大结果幂等落盘（>50K 自动 spill-to-disk）+ L2 LLM 结构化摘要；熔断器 + PTL 重试 | [`kkcode/context/`](kkcode/context/) |\n| **权限引擎** | 六层分级裁决（Layer 0–5）；Pattern 记忆避免重复确认；会话级临时授权 | [`kkcode/permissions/`](kkcode/permissions/) |\n| **OS 沙箱** | Linux bubblewrap / macOS seatbelt 内核级隔离 | [`kkcode/sandbox/`](kkcode/sandbox/) |\n| **多 Agent 团队** | TeamManager 调度 + Worktree 隔离 + 文件锁邮箱 + Coordinator 后端 | [`kkcode/teams/`](kkcode/teams/) |\n| **Git Worktree** | 每个 Agent 独立 checkout + 分支，并行修改互不干扰 | [`kkcode/worktree/`](kkcode/worktree/) |\n| **记忆系统** | 自动记忆 + consolidation 定期提炼；长期记忆跨会话持久化 | [`kkcode/memory/`](kkcode/memory/) |\n| **内置工具** | ReadFile / WriteFile / Grep / Glob / Bash / Edit 等 8 个核心工具 | [`kkcode/tools/`](kkcode/tools/) |\n| **会话持久化** | JSONL 落盘 + 断点恢复；对话链校验防孤儿 tool_use | [`kkcode/conversation.py`](kkcode/conversation.py) |\n| **TUI 交互层** | Textual 终端界面（≥2.1）；CLI 单发模式（`-p`） | [`kkcode/app.py`](kkcode/app.py) · [`kkcode/remote.py`](kkcode/remote.py) |\n| **Hooks 引擎** | 生命周期钩子（pre_tool / post_tool / on_compact 等） | [`kkcode/hooks/`](kkcode/hooks/) |\n\n---\n\n## 💡 可运行示例\n\n`examples/` 下每个脚本独立演示一项核心能力，配置好 `config.yaml` 后可直接 `python examples/.py` 运行：\n\n| 示例 | 演示内容 |\n|------|---------|\n| [`basic_chat.py`](examples/basic_chat.py) | 非交互式对话：Agent 自动读/写文件、执行命令 |\n| [`mcp_lazy_loading.py`](examples/mcp_lazy_loading.py) | MCP 三策略（EAGER/NATIVE/DISPATCH）决策与 Token 开销对比 |\n| [`multi_agent_team.py`](examples/multi_agent_team.py) | 多 Agent 团队协作架构（Worktree 隔离 + 文件锁邮箱） |\n| [`context_compaction.py`](examples/context_compaction.py) | 两层上下文压缩机制（熔断器 + 恢复段快照） |\n\n> 运行前：`uv sync` 安装依赖，并在 `.kkcode/config.yaml` 配置 LLM API Key。\n\n---\n\n## 🛠️ 技术栈\n\n| 类别 | 选型 |\n|------|------|\n| 语言 | Python ≥ 3.11（类型注解全量 `mypy` 检查） |\n| TUI | [Textual](https://github.com/Textualize/textual) ≥ 2.1 |\n| LLM | Anthropic API / OpenAI 兼容端点（DeepSeek、GPT 等） |\n| 工具协议 | MCP（Model Context Protocol，stdio + HTTP/SSE） |\n| 并发隔离 | Git Worktree · 文件锁邮箱 · asyncio |\n| 沙箱 | Linux `bwrap` (bubblewrap) · macOS `seatbelt` (sandbox-exec) |\n| 质量门禁 | `pytest` · `ruff` · `mypy` · GitHub Actions |\n\n---\n\n## 📊 项目状态\n\n| 指标 | 数值 |\n|------|------|\n| 核心代码 | 141 个 `.py` / ~24k 行 |\n| 单元测试 | 30 个测试文件 / 670+ 用例通过 |\n| 类型检查 | `mypy` 全量通过 |\n| 风格检查 | `ruff` 全量通过 |\n| 持续集成 | Python 3.11 / 3.12 / 3.13 矩阵 |\n\n---\n\n## 🔬 为什么你可以信这个项目\n\n这不是一个一次性导出的代码快照。以下是开发过程中**真实发生**的事件：\n\n### 真实用户反馈驱动迭代\n\n我把 KKCode 放给一起学的同学和身边几个开发者用。最直接的反馈是\n**「真能用」带来的意外**——大家平时用 Claude Code 当黑盒用，\n看到一个自己人写的、能在终端里自主读文件改代码跑命令的 Agent，\n第一反应是原来这东西没那么神秘。\n\n具体的改进反馈：\n\n| 反馈 | 来源 | 迭代结果 |\n|------|------|---------|\n| grep 大目录，几万行输出刷爆终端 | 同学 | >50K 字符工具结果自动落盘，对话内只留预览 |\n| 权限确认太烦，每个命令都要点 | 同学 | 会话级临时授权，同类操作一次确认 |\n| 不知道为什么 Agent 自己停了 | 同学 | 强化可观测性反馈，补使用说明文档 |\n| 多 Agent 配置复杂、文档没跟上 | 同学 | 承认是短板，持续补文档（本仓库即响应） |\n\n最大的触动：**我觉得理所当然的设计，到别人手里全是问题。**\n默认大家都懂 Agent Loop 怎么回事，但同学的第一个问题是\n「它为什么自己停下来了」。从那以后才意识到可观测性比想象中重要得多。\n\n### 协议层踩坑（三个场景，同一个根因）\n\nFunction Calling 有一个隐含硬约束：**每个 tool_use 必须有且仅有一个 tool_result**。\n缺了或多了一个，下一轮调 API 直接报错，整个会话崩掉。\n\n这个约束在三种场景下各触发了一次：\n\n1. **用户中断**：模型返回 3 个工具调用，用户按 ESC，只执行完 1 个。\n 剩下 2 个孤儿 tool_use 没补结果 → 下一轮炸。\n2. **会话恢复**：进程被 kill，JSONL 日志末尾可能只有 assistant 消息没有 tool_result。\n 恢复时不校验 → 加载非法历史 → 下一轮炸。\n3. **上下文压缩**：切点恰好落在 tool_use 和 tool_result 之间。\n 替换后的历史不合法 → 下一轮炸。\n\n最终统一修复：**对话链校验逻辑**——检测孤儿 tool_use 就截断到最近完整轮次；\n压缩按轮分组保证切点永远在完整轮次之间。\n\n### 评测驱动的优化\n\n用 SWE-bench-Live 数据集做了正式评测（20 道 2026 年最新 GitHub issue），\n发现多轮压缩后关键信息保留率仅 1/6。排查根因：\n摘要 prompt 把用户指令和工具输出等量齐观，早期用户指令被当成不重要内容丢了。\n改为**不对称压缩**（用户消息原样保留、工具输出激进压缩）后，\n信息保留率直接到 100%，**代码一行没动**。\n\n### 工程质量底线\n\n| 指标 | 数值 |\n|------|------|\n| 核心代码 | 141 个 `.py` / ~24k 行 |\n| 单元测试 | 30 个文件 / 670+ 用例 |\n| CI 矩阵 | Python 3.11 / 3.12 / 3.13 全部通过 |\n| 类型检查 | `mypy` 全量通过 |\n| 风格检查 | `ruff` 全量通过 |\n\n> **核心原则：设计与实现均由真实代码支撑。**\n> 上面每一条都有对应的代码、测试或 commit 可以追溯。\n\n---\n\n## 📁 项目结构（精简）\n\n```\nKKCode/\n├── kkcode/ # 核心包\n│ ├── agent.py # ReAct Agent 主循环\n│ ├── context/ # 两层上下文压缩\n│ ├── mcp/ # MCP 客户端 + 三策略延迟加载\n│ ├── permissions/ # 六层权限裁决\n│ ├── sandbox/ # OS 级沙箱 (bwrap/seatbelt)\n│ ├── teams/ # 多 Agent 协作\n│ ├── worktree/ # Git Worktree 隔离\n│ ├── memory/ # 会话记忆与 consolidation\n│ ├── tools/ # 内置工具 + MCP 调用\n│ ├── conversation.py # 会话持久化 (JSONL 落盘 + 断点恢复)\n│ └── hooks/ # 生命周期钩子\n├── docs/ # 机制详解文档\n├── tests/ # 单元测试\n└── .github/ # CI / Issue / PR 模板\n```\n## 🤝 贡献指南\n\n欢迎 Issue 与 PR！请先阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 与 [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)。\n\n---\n\n## 📄 License & About\n\n\n> KKCode 是一个**学习型项目**——目标是把终端 AI 编程助手的每一层架构走通、讲清楚。\n> 它不是要替代 Claude Code 或任何商业产品，而是提供一个\n> **完全透明、可审计、可修改**的参考实现。\n>\n> 如果你正在学习 Agent 工程、准备技术面试、\n> 或需要在企业内部部署可控的 Coding Agent，\n> 这个仓库的设计决策和踩坑记录可能对你有用。\n\n

\n Built as a showcase project · 设计与实现均由真实代码支撑\n

\n"}