内容
<div align="center">
<img src="https://raw.githubusercontent.com/plumpslabs/kuma/main/public/kuma.png" alt="Kuma Logo" width="200" />
# Kuma
**适用于 AI 编程代理的安全工具包**
[](https://www.npmjs.com/package/@plumpslabs/kuma)
[](LICENSE)
[](https://nodejs.org/)
与 **13 个 AI 编程代理** 兼容 — Claude Code, Cursor, Windsurf, GitHub Copilot Editor, Cline, Aider, Antigravity CLI, OpenCode, Codex CLI, Qwen Code, Kiro, OpenClaw, CodeWhale — 以及任何 MCP 兼容客户端。
**无需手动配置。** 只需运行 `npx @plumpslabs/kuma init`。
</div>
---
## 快速开始
```bash
# 为所有支持的 AI 代理生成配置文件
npx @plumpslabs/kuma init --all
# 或为特定代理生成配置文件
npx @plumpslabs/kuma init --cursor --claude --aider
# 查看所有选项
npx @plumpslabs/kuma init --help
```
或手动将 Kuma MCP 服务器添加到任何 MCP 客户端：
```json
{
"mcpServers": {
"kuma": {
"command": "npx",
"args": ["-y", "@plumpslabs/kuma"]
}
}
}
```
---
## 支持的代理
`kuma init` 为 **13 个 AI 编程代理** 生成原生配置文件 — 无需手动查找文件格式：
| # | 代理 | 生成的文件 | 方法 |
|---|-------|----------------|----------|
| 1 | **Claude Code** | `CLAUDE.md` | 回退说明（通过 `/plugin install` 插件） |
| 2 | **Cursor** | `.cursor/rules/kuma.mdc` | 带有 YAML 前言的规则文件 (`alwaysApply: true`) |
| 3 | **Windsurf** | `.windsurfrules` | 静态规则文件 |
| 4 | **GitHub Copilot Editor** | `AGENTS.md` + `.github/skills/kuma/SKILL.md` | AGENTS.md + 技能文件 |
| 5 | **Cline** | `.clinerules/kuma.md` | 带有 `paths` 前言的规则文件 |
| 6 | **Aider** | `CONVENTIONS.md` + `.aider.conf.yml` | 通过 `read: CONVENTIONS.md` 引用的约定文件 |
| 7 | **Antigravity CLI** | `.agents/skills/kuma/SKILL.md` + `.agents/mcp_config.json` | 技能（按需加载） |
| 8 | **OpenCode** | `opencode.json` | 插件配置 JSON |
| 9 | **Codex CLI (OpenAI)** | `AGENTS.md` + `.codex/config.toml` | AGENTS.md + MCP 服务器（TOML） |
| 10 | **Qwen Code** | `AGENTS.md` + `settings.json` | AGENTS.md + MCP 服务器（JSON） |
| 11 | **Kiro** | `.kiro/steering/kuma.md` | 带有 YAML 前言的转向文件 (`inclusion: always`) |
| 12 | **OpenClaw** | `skills/kuma/SKILL.md` | 技能（按需加载） |
| 13 | **CodeWhale** | `skills/kuma/SKILL.md` + `.codewhale/mcp.json` | 技能 + MCP 服务器配置 |
> `AGENTS.md` 包括所有选择代理的读取部分 — 一个文件，无冲突。
> `skills/kuma/SKILL.md` 被多个代理共享，它们从工作区根目录加载技能。
---
## Kuma 的承诺
**Kuma 的设计目的只有一个：确保 AI 代理不会破坏您的项目。**
Kuma 中的每个工具都内置了安全网 — 不是作为事后补充，而是作为核心设计原则。以下是 Kuma 的保证：
| # | 发生这种情况时... | Kuma 执行以下操作... |
|---|---|---|
| 1 | LSP 服务器未安装 | **回退到正则表达式** — 永不硬失败 |
| 2 | 编辑破坏某些内容 | **回滚到任何版本** — 版本备份 |
| 3 | AI 在测试失败时循环 | **电路中断器停止它** — 防止无限重试 |
| 4 | 文件路径无法解析 | **显示其查找位置** — 当前工作目录 vs 项目根目录 |
| 5 | 命令危险 | **阻止它** — `rm -rf`、`git push --force`、`curl | bash` |
大多数工具使 AI 更智能。 **Kuma 使 AI 不会破坏事物。**
---
## 工具（17）
### 🔍 上下文 — 了解代码库
| 工具 | 描述 |
|------|-------------|
| `smart_grep` | 使用正则表达式搜索代码。返回文件名、行号和上下文。缓存结果。 |
| `smart_file_picker` | 使用智能分块读取文件：`full`（整个文件）、`smart`（签名 + 尾部）、`outline`（仅导出）。 |
| `project_structure` | 项目布局的树视图。深度控制、文件夹模式、包含/排除模式。 |
| `git_log` | 带有可选文件筛选的结构化提交历史记录。 |
| `git_diff` | 结构化差异输出。支持暂存/未暂存、文件筛选、引用范围。 |
| `lsp_query` | 通过 TypeScript Language Server 进行定义跳转、查找引用、获取类型信息或重命名符号。 **当 LSP 不可用时回退到正则表达式。** |
| `project_conventions` | 自动检测框架、测试运行器、包管理器、导入别名、 **monorepo 工作区**。 |
### ✏️ 执行 — 安全地进行更改
| 工具 | 描述 |
|------|-------------|
| `precise_diff_editor` | 具有精确 → 空格 → 模糊回退的搜索和替换。 **每次编辑前自动备份**。使用 `action: "rollback"` 撤销。 |
| `batch_file_writer` | 一次创建最多 15 个文件。写入前验证路径。 |
| `static_analysis` | 运行 ESLint / TypeScript / Prettier / Ruff 并 **将输出解析为结构化结果**。从项目配置中自动检测工具。 |
### 🧪 验证 — 验证后再破坏
| 工具 | 描述 |
|------|-------------|
| `execute_safe_test` | 运行 `test`/`build`/`lint`/`typecheck` 并带有 **超时、电路中断器和进程树终止**。 |
| `code_reviewer` | 高级静态分析。关注模式：正确性、约定、安全、性能和 **过度工程检测**。 |
### 🧠 内存 — 记录发生了什么
| 工具 | 描述 |
|------|-------------|
| `get_session_memory` | 会话状态跟踪器。显示已修改的文件、未解决的失败、工具历史记录。加载特定内存主题 `{ topic }`。 |
| `search_session_memory` | **关键字搜索** 跨工具调用、内存文件、错误、已修改的文件和依赖关系图。 |
| `write_memory` | 将项目知识（决策、词汇）持久化到 `.kuma/memories/`。追加、prepend 或覆盖。 |
| `kuma_reflect` | **反射工具** — 检查是否正常运行、检测漂移（无测试的编辑、循环、未解决的失败）并建议下一步操作。 |
| `kuma_context` | **快照管理器** — 在高风险操作前保存/恢复项目状态（已修改的文件、错误、git 差异）。 |
---
## 安全
| 功能 | 它执行的操作 |
|---------|-------------|
| **沙盒** | 所有文件操作锁定到项目目录。阻止路径遍历。保护系统目录。 |
| **自动备份** | `.agent-backups/<timestamp>/` 在每次编辑前快照。回滚到任何版本。 |
| **电路中断器** | 3 次相同失败后停止。防止 AI 循环。 |
| **超时** | 所有命令都有可配置的超时（最大 180 秒）。超时时终止进程树。 |
| **命令白名单** | 仅 `test`、`build`、`lint`、`typecheck` 和显式自定义命令。 |
| **危险模式阻止** | 默认阻止 `rm -rf`、`git push --force`、`npm publish`、`curl | bash`。 |
| **LSP 降级** | 当 TypeScript Language Server 不可用时，LSP 工具 **回退到正则表达式** 而不是硬失败。 |
---
## Kuma 的独特之处
- **工作流组合** — `project_conventions + smart_grep + smart_file_picker + precise_diff_editor + execute_safe_test + code_reviewer` 作为无缝管道。
- **安全是默认的，而不是可选的** — 回滚、电路中断器、沙盒、超时、危险模式阻止内置于每个工具中。
- **降级** — 当依赖项丢失（LSP、linters）时，Kuma 回退而不是崩溃。
- **过度工程检测** — 带有 `focus: "over-engineering"` 的 `code_reviewer` 捕获不必要的抽象。
- **漂移检测** — `kuma_reflect` 捕获无测试的编辑、工具调用循环、未解决的失败。
- **持久内存** — 知识通过 `.kuma/memories/` 在会话之间存活。自动生成架构和约定文档。
- **Monorepo 感知** — 检测工作区、扫描 `apps/*`、`packages/*`、`services/*` 和 pnpm/yarn/npm 工作区。
---
## Kuma 的 DNA
1. **零设置，零摩擦** — 内置工具，无需配置。无需 DB，无需 API 密钥。
2. **安全第一** — 每个工具都有安全网：超时、电路中断器、回滚、沙盒。
3. **降级，而不是崩溃** — 每个工具在失败前都有回退。LSP 不可用？正则表达式。文件未找到？显示已解析的路径。差异不匹配？空格 → 模糊重试。测试失败？电路中断器停止循环。
4. **有意见的工作流** — 工具设计为一起使用：`conventions → grep → pick → diff → test → review`。
5. **最小表面** — 17 个专注的工具。每个工具都有一个工作且做得很好。无重叠，无混淆。
---
## 贡献
详见 [CONTRIBUTING.md](CONTRIBUTING.md)。
---
## 许可证
[MIT](LICENSE)
<div align="center">
**为所有 AI 代理制作 🐻**
[报告 Bug](https://github.com/farhank15/kuma/issues) · [请求功能](https://github.com/farhank15/kuma/issues)
</div>
