@kkelly-offical/kkcode 0.1.6 → 0.2.1

package/README.md

@@ -1,387 +1,452 @@
-# kkcode
-
-[![npm version](https://img.shields.io/npm/v/@kkelly-offical/kkcode)](https://www.npmjs.com/package/@kkelly-offical/kkcode)
-![Node](https://img.shields.io/badge/Node.js-%3E%3D22-green)
-![License](https://img.shields.io/badge/License-GPL--3.0-blue)
-![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)
-![Models](https://img.shields.io/badge/Models-Qwen%20%7C%20GLM%20%7C%20DeepSeek%20%7C%20Claude%20%7C%20GPT%20%7C%20Ollama-orange)
-
-面向团队协作的终端 AI Coding Agent。
-
-**可执行** — 内置 16+ 工具链，子智能体委派，主动规划与审批。
-**可治理** — 三级权限策略，会话审计，Token 预算控制。
-**可长跑** — LongAgent 阶段并行编排，自动重试与门禁闭环。
-**多模型** — 原生支持 Qwen3.5、GLM-5、DeepSeek、Claude、GPT、Ollama 本地模型。
-
----
-
-## 目录
-
-- [快速开始](#快速开始)
-- [支持的模型](#支持的模型)
-- [模式系统](#模式系统)
-- [LongAgent 编排](#longagent-编排)
-- [主动规划](#主动规划)
-- [权限系统](#权限系统)
-- [内置工具](#内置工具)
-- [子智能体](#子智能体)
-- [Auto Memory](#auto-memory)
-- [MCP 接入](#mcp-接入)
-- [GitHub 集成](#github-集成)
-- [扩展机制](#扩展机制)
-- [会话与审计](#会话与审计)
-- [TUI 交互](#tui-交互)
-- [项目结构](#项目结构)
-- [配置](#配置)
-- [常见问题](#常见问题)
-- [致谢](#致谢)
-- [License](#license)
-
----
-
-## 快速开始
-
-### 环境要求
-
-- Node.js `>=22`
-- npm / pnpm
-- 建议终端：Windows Terminal、iTerm2 或现代 Linux terminal
-
-### 安装与运行
-
-**从 npm 安装（推荐）：**
-
-```bash
-npm install -g @kkelly-offical/kkcode
-kkcode
-```
-
-**从源码运行（开发用）：**
-
-```bash
-git clone https://github.com/kkelly-offical/kkcode.git
-cd kkcode
-npm install
-npm run start
-```
-
-### 初始化项目配置
-
-```bash
-kkcode init -y
-```
-
-配置文件按优先级自动查找：
-
-- 用户级：`~/.kkcode/config.yaml`
-- 项目级：`./kkcode.config.yaml` 或 `./.kkcode/config.yaml`
-
----
-
-## 支持的模型
-
-kkcode 通过统一的 Provider 抽象层支持多种模型，开箱即用：
-
-| 提供商 | 模型 | 类型 | 配置样例 |
-|--------|------|------|----------|
-| 阿里 DashScope | Qwen3.5-Plus、Qwen3-Max、Qwen3-Coder | `openai-compatible` | [`config-qwen3.5.yaml`](configs/config-qwen3.5.yaml) |
-| 智谱 AI | GLM-5、GLM-4.5 | `openai-compatible` | [`config-glm5.yaml`](configs/config-glm5.yaml) |
-| DeepSeek | DeepSeek-Chat (V3)、DeepSeek-Reasoner (R1) | `openai-compatible` | [`config-deepseek.yaml`](configs/config-deepseek.yaml) |
-| Anthropic | Claude Opus 4.6、Sonnet 4.6 | `anthropic` | [`config.example.yaml`](docs/config.example.yaml) |
-| OpenAI | GPT-5.3-Codex、GPT-5.2 | `openai` | [`config.example.yaml`](docs/config.example.yaml) |
-| Ollama | Qwen3、DeepSeek-Coder、LLaMA 等本地模型 | `ollama` | [`config-ollama.yaml`](configs/config-ollama.yaml) |
-| 任意 OpenAI 兼容 API | Kimi、Yi、Moonshot 等 | `openai-compatible` | [`config-multi-provider.yaml`](configs/config-multi-provider.yaml) |
-
-切换模型只需修改配置文件中的 `provider.default`，或在 TUI 中使用 `/provider` 和 `/model` 命令。
-
----
-
-## 模式系统
-
-| 模式 | 目标 | 工具权限 | 典型场景 |
-|---|---|---|---|
-| `ask` | 问答 / 解释 | 只读 | 理解代码、解释报错 |
-| `plan` | 方案拆解 | 只读 | 先出执行计划 |
-| `agent` | 单轮执行 | 全工具 | 快速改代码 + 运行命令 |
-| `longagent` | 长程编排 | 全工具 + 调度 | 跨文件 / 多阶段任务 |
-
-TUI 中按 `Tab` 一键轮换模式。
-
----
-
-## LongAgent 编排
-
-LongAgent 是 kkcode 的核心差异能力，支持两种编排模式：
-
-**Hybrid 模式**（默认）— 7 阶段流水线：
-
-```
-Intake → Preview → Blueprint → Git分支 → Scaffold+并行编码 → Debugging → 门禁验证 → Git合并
-```
-
-**4-Stage 模式** — 4 阶段顺序执行：
-
-```
-Preview(只读) → Blueprint(只读) → Coding(写入) → Debugging(写入)
-```
-
-### 关键机制
-
-- **阶段并行** — 同阶段任务由独立 worker 并发执行，`max_concurrency` 控制并发数
-- **文件隔离** — 每个文件仅归属一个 task，plan 阶段即检测冲突
-- **自动重试** — 失败任务自动重试，优先续写未完成文件
-- **门禁闭环** — build / test / review / health / budget 五项质量门禁
-- **Git 集成** — 自动创建特性分支，每阶段提交，完成后合并
-- **防卡死** — 检测探索循环，强制推进到下一阶段
-
----
-
-## 主动规划
-
-Agent 执行中可主动进入规划模式，无需用户手动切换：
-
-1. Agent 遇到复杂任务时调用 `enter_plan`
-2. 在规划模式下分析代码、设计方案
-3. 调用 `exit_plan` 提交计划，TUI 弹出审批面板
-4. 用户 Approve 或 Reject（可附反馈）
-5. 批准后按计划执行，驳回则修订
-
----
-
-## 权限系统
-
-采用 **策略 + 交互审批 + 会话缓存授权** 组合模型。
-
-- `permission.default_policy`: `ask | allow | deny`
-- `permission.rules[]`: 按工具 / 模式 / 文件模式 / 命令前缀匹配细粒度规则
-- 审批一次后同会话内同类操作自动放行
-
-提供三级权限模板：[严格](configs/permission-strict.yaml) | [标准](configs/permission-standard.yaml) | [宽松](configs/permission-permissive.yaml)
-
-TUI 审批面板：`1` allow once / `2` allow session / `3` deny / `Esc` deny
-
----
-
-## 内置工具
-
-| 工具 | 说明 |
-|------|------|
-| `read` | 读取文件内容（支持 offset/limit 分页） |
-| `write` | 原子写文件（overwrite / append / insert） |
-| `edit` | 事务性字符串替换 + 自动回滚 |
-| `patch` | 按行号范围替换文件内容 |
-| `glob` | 按模式搜索文件 |
-| `grep` | 按正则搜索文件内容 |
-| `bash` | 执行 shell 命令 |
-| `task` | 委派子智能体执行子任务 |
-| `todowrite` | 结构化任务管理 |
-| `question` | 向用户提问 |
-| `enter_plan` / `exit_plan` | 主动规划与审批 |
-| `webfetch` / `websearch` | 网页抓取与搜索 |
-| `codesearch` | 代码搜索引擎 |
-
-写入安全特性：原子写、事务回滚、外部修改检测、读前编辑约束、file lock 串行化。
-
----
-
-## 子智能体
-
-通过 `task` 工具委派专项子智能体：
-
-| 类型 | 说明 | 权限 |
-|------|------|------|
-| `build` | 通用构建执行 | 全工具 |
-| `explore` | 快速代码探索 | 只读 |
-| `reviewer` | 代码审查（bug / 安全 / 质量） | 只读 |
-| `researcher` | 深度研究 + Web 搜索 | 只读 + 网络 |
-
-支持通过 YAML/MJS 自定义子智能体，或 `/create-agent` 自动生成。
-
----
-
-## Auto Memory
-
-为每个项目维护独立持久记忆，跨会话保存项目知识。
-
-- 存储位置：`~/.kkcode/projects/<项目名>_<hash>/memory/MEMORY.md`
-- 每次会话启动时自动注入系统提示词（限 200 行）
-- Agent 可直接读写记忆文件
-- 状态栏显示 `MEM` 徽章表示已加载
-
----
-
-## MCP 接入
-
-支持三种传输协议：
-
-| 传输 | 适用场景 | 关键字段 |
-|------|----------|----------|
-| `stdio` | 本地子进程 | `command`, `args` |
-| `sse` | 远程 Streamable HTTP | `url`, `headers` |
-| `http` | REST 风格 | `url`, `headers` |
-
-自动发现：合并 `.mcp.json`、`.kkcode/mcp.json`、`~/.kkcode/mcp.json` 中的配置。
-
-```bash
-kkcode mcp test          # 健康状态
-kkcode mcp tools         # 可用工具列表
-```
-
----
-
-## GitHub 集成
-
-通过 GitHub Device Flow 实现安全的仓库访问，无需手动配置 Token。
-
-```bash
-kkcode --github                    # 登录并选择仓库
-kkcode --github logout             # 登出
-```
-
-工作流程：登录 → 选择仓库/分支 → 选择本地或云端模式 → 进入 REPL → 退出时询问是否推送。
-
----
-
-## 扩展机制
-
-| 扩展类型 | 目录 | 说明 |
-|----------|------|------|
-| 命令模板 | `.kkcode/commands/` | Markdown 模板，支持变量替换 |
-| 技能 | `.kkcode/skills/` | 可编程技能，`/create-skill` 生成 |
-| 子智能体 | `.kkcode/agents/` | YAML/MJS 定义，`/create-agent` 生成 |
-| 自定义工具 | `.kkcode/tools/` | .mjs 自动加载，`/reload` 热更新 |
-| 插件/Hook | `.kkcode/plugins/` | Hook 事件脚本 |
-| 规则 | `.kkcode/rules/` | 项目级提示词规则 |
-| 指令文件 | `KKCODE.md` | 项目级指令，自动注入提示词 |
-
----
-
-## 会话与审计
-
-- 会话存储：`~/.kkcode/sessions/`
-- 审计日志：`~/.kkcode/audit-log.json`
-- 事件日志：`~/.kkcode/events.log`
-- 三层用量追踪：turn / session / global
-- 预算策略：`warn | block`
-
-```bash
-kkcode doctor --json         # 完整诊断
-kkcode session list          # 会话列表
-kkcode session gc            # 过期清理
-kkcode usage show            # 用量统计
-kkcode longagent status      # LongAgent 状态
-```
-
----
-
-## TUI 交互
-
-### 状态栏
-
-底部实时显示：`MODE` `MODEL` `TOKENS` `COST` `CONTEXT` `MEM` `PERMISSION` `LONG`
-
-### 快捷键
-
-| 按键 | 功能 |
-|------|------|
-| `Enter` | 发送 |
-| `Ctrl+J` | 换行 |
-| `Tab` | 模式轮换 |
-| `Up/Down` | 输入历史 |
-| `Ctrl+Up/Down` | 滚动日志区 |
-| `Esc` | 清空输入 |
-| `Ctrl+L` | 清空活动区 |
-| `Ctrl+C` | 退出 |
-
-支持 `@图片路径` 或 `@图片URL` 引用多模态输入。
-
-### 常用 Slash 命令
-
-`/help` `/status` `/history` `/new` `/resume` `/mode` `/provider` `/model` `/permission` `/paste` `/commands` `/reload` `/clear` `/exit`
-
----
-
-## 项目结构
-
-```
-kkcode/
-├── src/
-│   ├── index.mjs              # CLI 入口
-│   ├── repl.mjs               # TUI 主循环
-│   ├── core/                  # 核心类型、常量、事件总线
-│   ├── config/                # 配置加载、Schema 校验、默认值
-│   ├── session/               # 会话引擎、消息循环、LongAgent 编排
-│   ├── tool/                  # 工具注册、执行、事务管理
-│   ├── agent/                 # 子智能体（explore/reviewer/researcher）
-│   ├── provider/              # 多 Provider 适配
-│   ├── permission/            # 权限引擎
-│   ├── mcp/                   # MCP 客户端（stdio/sse/http）
-│   ├── orchestration/         # 后台任务管理与并行 worker
-│   ├── observability/         # 可观测性（Metrics/Tracer）
-│   ├── ui/                    # Dashboard 渲染
-│   ├── storage/               # 会话/任务持久化
-│   ├── usage/                 # Token 计量与预算
-│   └── util/                  # 通用工具函数
-├── configs/                   # 配置样例与权限模板
-├── test/                      # 单元测试与集成测试
-├── package.json
-├── LICENSE                    # GPL-3.0
-└── NOTICE.md                  # 第三方致谢与声明
-```
-
----
-
-## 配置
-
-完整配置参考：[`docs/config.example.yaml`](docs/config.example.yaml)
-
-### 配置样例（configs/ 目录）
-
-| 文件 | 说明 |
-|------|------|
-| [`config-qwen3.5.yaml`](configs/config-qwen3.5.yaml) | 通义千问 Qwen3.5 系列 |
-| [`config-qwen3.yaml`](configs/config-qwen3.yaml) | 通义千问 Qwen3 系列 |
-| [`config-glm5.yaml`](configs/config-glm5.yaml) | 智谱 GLM-5 / GLM-4.5 |
-| [`config-deepseek.yaml`](configs/config-deepseek.yaml) | DeepSeek V3 / R1 |
-| [`config-ollama.yaml`](configs/config-ollama.yaml) | 本地 Ollama |
-| [`config-multi-provider.yaml`](configs/config-multi-provider.yaml) | 多 Provider 组合 |
-| [`permission-strict.yaml`](configs/permission-strict.yaml) | 严格权限（生产环境） |
-| [`permission-standard.yaml`](configs/permission-standard.yaml) | 标准权限（日常开发） |
-| [`permission-permissive.yaml`](configs/permission-permissive.yaml) | 宽松权限（个人/CI） |
-
----
-
-## 常见问题
-
-**Q: LongAgent 为什么拒绝"你好"？**
-LongAgent 是执行型编排器，非编码目标会被意图识别拦截。请使用 `ask` 模式进行对话。
-
-**Q: enter_plan 和 /plan 有什么区别？**
-`/plan` 是用户手动切换模式。`enter_plan` 是 agent 执行中主动进入规划，审批通过后继续执行。
-
-**Q: 如何切换模型？**
-TUI 中使用 `/provider` 切换提供商，`/model` 切换模型。或修改配置文件中的 `provider.default`。
-
-**Q: Auto Memory 会无限增长吗？**
-注入系统提示时限制 200 行。Agent 会保持精简并删除过时条目。
-
-**Q: 支持哪些国产模型？**
-原生支持通义千问 Qwen3.5/3 系列、智谱 GLM-5/4.5、DeepSeek V3/R1，以及任何 OpenAI 兼容 API。
-
----
-
-## 致谢
-
-kkcode 的设计受到以下项目的启发：
-
-- **[Claude Code](https://github.com/anthropics/claude-code)** — Anthropic 官方 AI Coding CLI。工具体系、子智能体架构、提示词工程等核心设计以此为标杆。
-- **[OpenCode](https://github.com/nicepkg/opencode)** — 开源终端 AI Coding 助手。多 Provider 支持、主题系统等借鉴了其设计。
-- **[Everything Claude Code](https://github.com/affaan-m/everything-claude-code)** — Instinct 自动学习、Hook Recipes、TDD 工作流等能力受此启发。
-
----
-
-## License
-
-本项目基于 [GNU General Public License v3.0](LICENSE) 开源。
-
-Copyright (C) 2026 kkcode team
+# kkcode
+
+[![npm version](https://img.shields.io/npm/v/@kkelly-offical/kkcode?label=v0.2.1)](https://www.npmjs.com/package/@kkelly-offical/kkcode)
+[![GitHub Release](https://img.shields.io/github/v/release/kkelly-offical/kkcode)](https://github.com/kkelly-offical/kkcode/releases)
+![Node](https://img.shields.io/badge/Node.js-%3E%3D22-green)
+![License](https://img.shields.io/badge/License-GPL--3.0-blue)
+![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)
+
+**Terminal-first personal assistant with dedicated Coding Agent and LongAgent modes for governed execution and extensible local workflows.**
+
+**终端优先、可治理、可扩展的个人助手，内置专门 Coding Agent 与 LongAgent 模式。**
+kkcode 把问答、规划、事务型修改、多阶段长任务编排放在同一个 CLI 工作台里，并且把权限、预算、审计、后台任务、MCP、技能与插件一起纳入统一执行面。
+
+---
+
+<a id="table-of-contents"></a>
+## Table of Contents / 目录
+
+- [Overview / 概览](#overview)
+- [Why kkcode / 为什么选择 kkcode](#why-kkcode)
+- [Installation / 安装](#installation)
+- [Quick Start / 快速开始](#quick-start)
+- [Capability Snapshot / 能力总览](#capability-snapshot)
+- [Modes & LongAgent / 模式与 LongAgent](#modes-and-longagent)
+- [Safety & Permissions / 权限与安全](#safety-and-permissions)
+- [Delegation & Subagents / 委派与子智能体](#delegation-and-subagents)
+- [Integrations / 集成](#integrations)
+- [Extensions / 扩展机制](#extensions)
+- [TUI & CLI Reference / TUI 与命令参考](#tui-and-cli-reference)
+- [Configuration & Project Layout / 配置与项目结构](#configuration-and-project-layout)
+- [Release Status / 发布状态](#release-status)
+- [Compatibility, Limits & Roadmap / 兼容性、边界与路线图](#compatibility-limits-and-roadmap)
+- [FAQ / 常见问题](#faq)
+- [Contributing / 贡献](#contributing)
+- [License / 许可证](#license)
+- [Further Reading / 延伸阅读](#further-reading)
+
+---
+
+<a id="overview"></a>
+## Overview / 概览
+
+**English**
+- kkcode is a terminal-native personal assistant designed for local work, governed execution, coding, and multi-stage delivery.
+- It keeps four public lanes — `assistant`, `plan`, `agent`/`code`, and `longagent` — under one CLI surface.
+- It is optimized for **CLI-first** and **LongAgent-first** workflows rather than GUI-first or marketplace-first product patterns.
+
+**中文**
+- kkcode 是一个面向终端原生工作流的个人助手，强调本地事务、可治理执行、编码和多阶段交付。
+- 它把四条公开执行航道 —— `assistant`、`plan`、`agent`/`code`、`longagent` —— 收敛在同一个 CLI 入口下。
+- 它优先服务 **CLI-first**、**LongAgent-first** 的工程工作流，而不是 GUI 优先或 marketplace 优先的平台形态。
+
+---
+
+<a id="why-kkcode"></a>
+## Why kkcode / 为什么选择 kkcode
+
+**English**
+- **CLI-first**: core workflows stay in the terminal.
+- **LongAgent-first**: large tasks are planned, staged, and verified instead of improvised in one prompt.
+- **Governed execution**: permissions, budgets, audit logs, and recovery are built in.
+- **Local extensibility**: MCP, skills, commands, hooks, tools, and custom agents can all be mounted locally.
+
+**中文**
+- **CLI-first**：核心工作流都在终端内完成。
+- **LongAgent-first**：复杂任务先规划、分阶段、带门禁，而不是靠单轮 prompt 硬顶。
+- **可治理执行**：权限、预算、审计、恢复、后台任务都是内建能力。
+- **本地可扩展**：MCP、skills、commands、hooks、tools、custom agents 都能本地挂载。
+
+---
+
+<a id="installation"></a>
+## Installation / 安装
+
+**Requirements / 环境要求**
+- Node.js `>=22`
+- npm or pnpm
+- A modern terminal on Windows, macOS, or Linux
+
+**Install from npm / 通过 npm 安装**
+```bash
+npm install -g @kkelly-offical/kkcode
+kkcode
+```
+
+**Run from source / 从源码运行**
+```bash
+git clone https://github.com/kkelly-offical/kkcode.git
+cd kkcode
+npm install
+npm run start
+```
+
+**Useful links / 常用链接**
+- [npm package](https://www.npmjs.com/package/@kkelly-offical/kkcode)
+- [GitHub Releases](https://github.com/kkelly-offical/kkcode/releases)
+- [Example config](docs/config.example.yaml)
+
+---
+
+<a id="quick-start"></a>
+## Quick Start / 快速开始
+
+**1. Launch / 启动**
+```bash
+kkcode
+```
+
+**2. Initialize project config / 初始化项目配置**
+```bash
+kkcode init -y
+```
+
+**3. Verify the install / 验证安装**
+```bash
+kkcode --help
+kkcode doctor
+```
+
+**First-run behavior / 首次启动行为**
+- On first launch, kkcode runs onboarding and records your preferences.
+- Use `/profile` to inspect or update personal preferences.
+- Use `/like` to rerun onboarding.
+
+**Configuration search order / 配置查找顺序**
+- User-level: `~/.kkcode/config.yaml`
+- Project-level: `./kkcode.config.yaml` or `./.kkcode/config.yaml`
+
+---
+
+<a id="capability-snapshot"></a>
+## Capability Snapshot / 能力总览
+
+| Area / 能力面 | Status / 状态 | Notes / 说明 |
+| --- | --- | --- |
+| Assistant / 个人助手 | Supported | Default CLI lane for terminal-native personal work, explanation, and code understanding |
+| Plan / 方案规划 | Supported | Planning without mutating the repo |
+| Agent / 默认事务航道 | Supported | Local inspect/patch/verify loops |
+| LongAgent / 长程编排 | Supported | Multi-stage execution, retries, gates, resumable flow |
+| Permissions / 权限治理 | Supported | Policy + approvals + session cache |
+| Background tasks / 后台任务 | Supported | Launch, inspect, wait, retry, cancel |
+| MCP / 模型上下文协议 | Supported | Local MCP discovery and registry |
+| Skills / Commands / Hooks | Supported | Local-first extensibility surface |
+| Plugins / 插件包 | MVP | Local plugin manifests and component toggles |
+| GUI / IDE / desktop automation | Not promised | README does not claim GUI-first product support |
+
+For a deeper boundary matrix, see [CLI General Assistant Capability Matrix](docs/cli-general-assistant-capability-matrix.md).
+
+---
+
+<a id="modes-and-longagent"></a>
+## Modes & LongAgent / 模式与 LongAgent
+
+### Public lanes / 公开执行航道
+
+| Mode | Purpose | Typical use |
+| --- | --- | --- |
+| `assistant` | default personal assistant | local files, logs, system checks, web lookup, Git/GitHub, notes, tasks |
+| `plan` | specification / planning | producing an execution plan before mutations |
+| `agent` / `code` / `coding` | dedicated coding execution | inspect + patch + verify small/medium coding tasks |
+| `longagent` | staged orchestration | multi-file, multi-step, ownership-driven delivery |
+
+**English**
+- `assistant` is the default terminal personal-assistant lane.
+- `agent` / `code` / `coding` is the dedicated coding lane.
+- Only escalate to `longagent` when the task is clearly multi-stage or system-wide.
+- Interrupted work can be resumed with the same session context.
+
+**中文**
+- `assistant` 是默认的终端个人助手航道。
+- `agent` / `code` / `coding` 是专门编码航道。
+- 只有在任务明显跨文件、跨阶段、影响面较大时，才建议升级到 `longagent`。
+- 中断后的工作可以在同一会话中继续，不需要从零开始。
+- **路由理由可见**：当 kkcode 自动建议模式变化时，会尽量解释为什么当前任务更适合留在 `assistant` / `agent` 或升级到 `longagent`。
+
+### CLI 通用助手能力边界（0.1.13）
+
+**公共模式契约**
+
+- `assistant`：默认终端个人助手航道，承接本地文件、日志、系统信息、网页查询、Git/GitHub、笔记、任务整理、解释、答疑和分析。
+- `plan`：**只产出规格，不执行文件变更**。
+- `agent` / `code` / `coding`：专门编码航道，承接 inspect / patch / verify 小闭环事务。
+- **只有出现明确重型证据时，才从 `assistant` 或 `agent` 升级到 `longagent`**。
+
+**能力边界速览**
+- 系统 / 运行时信息
+- 本地目录 / 文件 / 日志检查
+- 仓库 / 发布辅助
+- 这**不代表** kkcode 已经承诺 GUI / 桌面自动化能力
+- 默认先在 `assistant` 内处理普通终端事务；明确编码修改进入 `agent` / `code`，再判断是否需要升级
+
+**Further reading / 延伸阅读**
+- [0.1.13 Mode Lane Contract](docs/kkcode-0.1.13-mode-lane-contract.md)
+- [Agent Mode Tolerance Contract](docs/kkcode-0.1.12-agent-mode-tolerance-contract.md)
+
+---
+
+<a id="safety-and-permissions"></a>
+## Safety & Permissions / 权限与安全
+
+**English**
+- kkcode uses a policy-driven permission model with optional approvals.
+- Session-scoped grants can reduce repeated prompts while preserving boundaries.
+- Budget and usage controls are designed to keep long-running sessions governable.
+
+**中文**
+- kkcode 使用策略驱动的权限模型，并可叠加交互式审批。
+- 会话级授权缓存可减少重复确认，同时保持边界清晰。
+- 预算与用量控制让长会话、长任务仍然处于可治理状态。
+
+**Policy examples / 策略示例**
+- `permission.default_policy: ask | allow | deny`
+- rule-based overrides by tool / mode / file pattern / command prefix
+
+---
+
+<a id="delegation-and-subagents"></a>
+## Delegation & Subagents / 委派与子智能体
+
+**English**
+- kkcode supports bounded delegation through the `task` surface.
+- Use `fresh_agent` for isolated implementation work.
+- Use `fork_context` for read-only sidecar work such as research or verification.
+- Do not outsource core understanding when the main thread must synthesize the result.
+
+**中文**
+- kkcode 通过 `task` 能力支持有边界的委派。
+- `fresh_agent` 适合隔离实现任务。
+- `fork_context` 适合研究、审计、验证这类只读 sidecar 任务。
+- 如果主线程必须综合判断，就不要把理解工作本身外包出去。
+
+**Background task contract / 后台任务契约**
+- 通过 `background_output` 查看后台任务输出
+- 通过 `background_cancel` 取消后台任务
+- 终态固定为 `completed` / `cancelled` / `error` / `interrupted`
+
+**Further reading / 延伸阅读**
+- [Task Delegation Contract Matrix](docs/task-delegation-contract-matrix.md)
+- [Agent / LongAgent Extension Guide](docs/agent-longagent-compat-extension-guide.md)
+
+---
+
+<a id="integrations"></a>
+## Integrations / 集成
+
+### MCP
+- Discover local MCP definitions and mount tools into the runtime.
+- Inspect registered MCP servers from the CLI.
+- Use MCP as part of the same governed tool surface.
+
+### GitHub
+- Authenticate, inspect repositories, and run GitHub-related flows from the terminal.
+- Repository helpers live under `src/github/`.
+
+### Git automation
+- Local git-aware helpers support safe status, patch, and snapshot workflows.
+- See [GIT_AUTO_USAGE.md](docs/GIT_AUTO_USAGE.md).
+
+---
+
+<a id="extensions"></a>
+## Extensions / 扩展机制
+
+**Local-first extension surface / 本地优先扩展面**
+- commands
+- skills
+- agents
+- tools
+- hooks
+- plugin manifests
+
+**Directory conventions / 目录约定**
+- `.kkcode/commands/`
+- `.kkcode/skills/`
+- `.kkcode/agents/`
+- `.kkcode/tools/`
+- `.kkcode/plugins/`
+- `.kkcode/hooks/`
+- `.kkcode-plugin/plugin.json`
+
+**English**
+- kkcode’s extension story is local-first and explicit.
+- Plugins are currently an MVP surface, not a marketplace platform promise.
+
+**中文**
+- kkcode 的扩展机制是本地优先、显式可控的。
+- 当前插件能力是 MVP，不代表已经承诺 marketplace 平台形态。
+
+**Further reading / 延伸阅读**
+- [ClaudeNext Agent / LongAgent Skills Compatibility](docs/claudenext-agent-longagent-skills-compat.md)
+- [Agent / LongAgent Extension Guide](docs/agent-longagent-compat-extension-guide.md)
+
+---
+
+<a id="tui-and-cli-reference"></a>
+## TUI & CLI Reference / TUI 与命令参考
+
+### Common TUI slash commands / 常用 TUI slash 命令
+- `/help` — show help
+- `/status` — show runtime and operator status
+- `/commands` — inspect command / skill / capability surface
+- `/reload` — reload commands, skills, and agents
+- `/new`, `/resume`, `/history` — session lifecycle
+- `/provider`, `/model` — provider/model switching
+- `/permission` — permission policy management
+- `/create-skill`, `/create-agent` — generate local extensions
+
+**Interrupt semantics / 中断语义**
+- `Esc` 可用于**中断当前 turn**、退出部分选择态或拒绝当前交互式请求，具体行为取决于当前上下文。
+
+### Main CLI commands / 主要 CLI 子命令
+- `chat`
+- `session`
+- `background`
+- `agent`
+- `longagent`
+- `mcp`
+- `skill`
+- `config`
+- `doctor`
+- `usage`
+- `review`
+- `audit`
+
+Run `kkcode --help` or `kkcode <command> --help` for the full surface.
+
+---
+
+<a id="configuration-and-project-layout"></a>
+## Configuration & Project Layout / 配置与项目结构
+
+### Key config themes / 关键配置主题
+- provider/model selection
+- permission and trust policy
+- agent / longagent behavior
+- usage and budget limits
+- UI / theme settings
+- MCP and extension loading
+
+### Project structure / 项目结构
+- `src/repl.mjs` — main REPL assembly surface
+- `src/repl/` — extracted REPL seams
+- `src/ui/` — REPL panels and render helpers
+- `src/session/` — execution loop, memory, recovery, prompts
+- `src/orchestration/` — background and longagent orchestration
+- `src/skill/`, `src/plugin/`, `src/mcp/` — extension systems
+
+**Useful docs / 推荐文档**
+- [Example config](docs/config.example.yaml)
+- [REPL roadmap](docs/repl-roadmap-0.1.27-0.1.36.md)
+
+---
+
+<a id="release-status"></a>
+## Release Status / 发布状态
+
+**Current stable / 当前稳定版本**: `v0.2.1`
+**Latest releases / 最新发布**: [GitHub Releases](https://github.com/kkelly-offical/kkcode/releases)  
+**Package / 包地址**: [npm](https://www.npmjs.com/package/@kkelly-offical/kkcode)
+
+**English**
+- `0.2.1` rebuilds kkcode around Assistant as the default general-purpose lane, with dedicated Agent and LongAgent modes for coding work.
+- The public Ask lane has been removed; question, explanation, and lightweight personal-assistant tasks now route to Assistant.
+
+**中文**
+- `0.2.1` 将 kkcode 重构为以 Assistant 为默认入口的通用个人助手，同时保留专门面向代码工作的 Agent 和 LongAgent 模式。
+- 公共 Ask 通道已移除；问答、解释和轻量个人助手任务现在统一路由到 Assistant。
+
+---
+
+<a id="compatibility-limits-and-roadmap"></a>
+## Compatibility, Limits & Roadmap / 兼容性、边界与路线图
+
+**What this README does claim / 本 README 明确声明的能力**
+- terminal-native coding workflows
+- governed execution and permissions
+- staged LongAgent orchestration
+- MCP and local extension surfaces
+- session/background/task visibility
+
+**What this README does not promise / 本 README 不承诺的能力**
+- GUI-first product workflows
+- IDE-native UX parity
+- desktop automation platform behavior
+- marketplace-style plugin ecosystem
+
+**Roadmap references / 路线图参考**
+- [REPL roadmap 0.1.27 → 0.1.36](docs/repl-roadmap-0.1.27-0.1.36.md)
+- [kkcode vs claudenext compatibility notes](docs/kkcode-vs-claudenext-private-agent-longagent-compat.md)
+- [kkcode vs claudenext report](docs/kkcode-vs-claudenext-private-agent-longagent-report.md)
+
+---
+
+<a id="faq"></a>
+## FAQ / 常见问题
+
+**Q: When should I use `longagent`? / 什么时候该用 `longagent`？**  
+A: Use it when the task is clearly multi-stage, cross-file, or needs ownership/gates. Ordinary terminal assistance should stay in `assistant`; small coding inspect/patch/verify loops should stay in `agent` / `code`.
+
+**Q: Can kkcode work with multiple providers? / kkcode 支持多模型厂商吗？**  
+A: Yes. Provider switching is built into config and the REPL command surface.
+
+**Q: Can I extend kkcode locally? / 可以本地扩展吗？**  
+A: Yes. Commands, skills, hooks, tools, agents, and plugin manifests all have local-first support.
+
+**Q: Does kkcode promise GUI or IDE parity? / 是否承诺 GUI 或 IDE 对等体验？**  
+A: No. This release line is CLI-first and does not overclaim GUI-first capability.
+
+---
+
+<a id="contributing"></a>
+## Contributing / 贡献
+
+**English**
+- Keep changes small, testable, and reviewable.
+- Run validation before pushing:
+  - `npm run lint`
+  - `npm run typecheck`
+  - `node ./scripts/run-node-tests.mjs`
+  - `npm run release:verify`
+
+**中文**
+- 贡献尽量保持小步、可验证、可审阅。
+- 推送前建议至少运行：
+  - `npm run lint`
+  - `npm run typecheck`
+  - `node ./scripts/run-node-tests.mjs`
+  - `npm run release:verify`
+
+欢迎中英双语 issue / PR。
+
+---
+
+<a id="license"></a>
+## License / 许可证
+
+kkcode is licensed under **GPL-3.0**.  
+See [LICENSE](LICENSE) for the full text.
+
+---
+
+<a id="further-reading"></a>
+## Further Reading / 延伸阅读
+
+- [CLI General Assistant Capability Matrix](docs/cli-general-assistant-capability-matrix.md)
+- [0.1.13 Mode Lane Contract](docs/kkcode-0.1.13-mode-lane-contract.md)
+- [Task Delegation Contract Matrix](docs/task-delegation-contract-matrix.md)
+- [Agent / LongAgent Extension Guide](docs/agent-longagent-compat-extension-guide.md)
+- [ClaudeNext Agent / LongAgent Skills Compatibility](docs/claudenext-agent-longagent-skills-compat.md)
+- [REPL roadmap 0.1.27 → 0.1.36](docs/repl-roadmap-0.1.27-0.1.36.md)
+- [Git automation usage](docs/GIT_AUTO_USAGE.md)
+- [Edit diagnostics feedback contract](docs/edit-diagnostics-feedback-contract.md)