内容
<p align="center">
<img src="assets/social-preview.png" alt="Kilo-Kit social preview" width="100%">
</p>
<p align="center">
<a href="https://github.com/VoDaiLocz/KILO-KIT/stargazers"><img src="https://img.shields.io/github/stars/VoDaiLocz/KILO-KIT?style=for-the-badge&logo=github&label=stars&color=18181b&labelColor=0f172a" alt="GitHub stars"></a>
<a href="https://github.com/VoDaiLocz/KILO-KIT/commits/main"><img src="https://img.shields.io/github/last-commit/VoDaiLocz/KILO-KIT?style=for-the-badge&logo=git&label=last%20commit&color=22c55e&labelColor=0f172a" alt="Last commit"></a>
<a href="https://github.com/VoDaiLocz/KILO-KIT/graphs/contributors"><img src="https://img.shields.io/github/contributors/VoDaiLocz/KILO-KIT?style=for-the-badge&logo=github&label=contributors&color=f97316&labelColor=0f172a" alt="Contributors"></a>
<a href="https://github.com/VoDaiLocz/KILO-KIT/actions/workflows/publish.yml"><img src="https://img.shields.io/github/actions/workflow/status/VoDaiLocz/KILO-KIT/publish.yml?style=for-the-badge&logo=githubactions&label=publish&color=22c55e&labelColor=0f172a" alt="Publish workflow"></a>
<a href="https://www.npmjs.com/package/@vodailoc/kilo-kit-mcp"><img src="https://img.shields.io/npm/v/@vodailoc/kilo-kit-mcp?style=for-the-badge&logo=npm&label=npm&color=ef4444&labelColor=0f172a" alt="npm version"></a>
<a href="https://www.npmjs.com/package/@vodailoc/kilo-kit-mcp"><img src="https://img.shields.io/npm/dm/@vodailoc/kilo-kit-mcp?style=for-the-badge&logo=npm&label=downloads&color=0284c7&labelColor=0f172a" alt="npm downloads"></a>
<a href="LICENSE"><img src="https://img.shields.io/github/license/VoDaiLocz/KILO-KIT?style=for-the-badge&label=license&color=64748b&labelColor=0f172a" alt="License"></a>
</p>
<p align="center">
<img src="https://img.shields.io/badge/skills-134-06b6d4?style=for-the-badge&labelColor=0f172a" alt="134 skills">
<img src="https://img.shields.io/badge/MCP-ready-14b8a6?style=for-the-badge&logo=modelcontextprotocol&labelColor=0f172a" alt="MCP ready">
<img src="https://img.shields.io/badge/Codex-ready-111827?style=for-the-badge&logo=openai&labelColor=0f172a" alt="Codex ready">
<img src="https://img.shields.io/badge/Trusted%20Publishing-OIDC-8b5cf6?style=for-the-badge&logo=githubactions&labelColor=0f172a" alt="Trusted publishing">
<img src="https://img.shields.io/badge/Node-%3E%3D20-339933?style=for-the-badge&logo=nodedotjs&labelColor=0f172a" alt="Node >=20">
<img src="https://img.shields.io/badge/TypeScript-5.9-3178c6?style=for-the-badge&logo=typescript&labelColor=0f172a" alt="TypeScript 5.9">
</p>
# Kilo-Kit：MCP 工作流门控，用于编码代理
> **版本：** 1.3.1
> **作者：** Kilo-Kit 团队
> **许可证：** Apache 2.0
Kilo-Kit 是一个本地优先的 MCP 服务器和技能库，用于使编码代理遵循更安全、可重复的工作流，在它们触及代码之前。
在代理跳过规划、忽略项目工作流规则、忘记有用上下文或在验证之前声称工作已完成时使用它。
它包含一个精选的 `skills/` 库、一个 MCP 服务器和一个 C4 工作流门控，将用户请求转换为可审计的循环：
```text
请求 -> 路由 -> 规划门控 -> 内存检查 -> 工作流发布 -> 验证门控
```
已发布的软件包是 `@vodailoc/kilo-kit-mcp`。
## 为什么使用它
| 问题 | Kilo-Kit 行为 |
| --- | --- |
| 代理过早开始编码 | C4 需要在实质性工作之前进行规划/集思广益。 |
| 代理忘记存储库特定的偏好 | 可选内存建议在执行之前进行以前的决定。 |
| 代理选择随机指令 | 技能路由返回工作流和要加载的第一个技能。 |
| 代理在没有证据的情况下声称“完成” | 验证门控必须在完成之前满足。 |
| 不同代理表现不同 | `kilo-kit-init` 为 Gemini、Codex 和 Claude 编写相同的 C4 规则。 |
## 它提供什么
| 领域 | 目的 |
| --- | --- |
| 技能库 | 可安装的 `SKILL.md` 工作流，按工程、生产力、调试、设计、操作、文档等分组。 |
| MCP 服务器 | stdio 服务器，暴露路由、技能加载、验证、C4 协调、内存和路由报告。 |
| C4 门控 | 一个闭环工作流门控，在遵循和批准真正的集思广益技能之前阻止实质性工作。 |
| 内存 | 可选的 SQLite 支持的事实、决定、会话和工作流结果。 |
| 审计 | C4 状态转换和路由决策的可选 JSONL 跟踪。 |
| 验证 | 代理必须在声称完成之前满足的返回验证门控。 |
## 两步安装
步骤 1：在客户端安装 MCP 服务器。
在任何支持 MCP 的主机中使用已发布的软件包：
```json
{
"mcpServers": {
"kilo-kit": {
"command": "npx",
"args": ["-y", "@vodailoc/kilo-kit-mcp"]
}
}
}
```
步骤 2：在项目中引导主机代理规则。
```bash
npx -y --package=@vodailoc/kilo-kit-mcp kilo-kit-init init --client gemini
npx -y --package=@vodailoc/kilo-kit-mcp kilo-kit-init init --client codex
npx -y --package=@vodailoc/kilo-kit-mcp kilo-kit-init init --client claude
```
或初始化所有支持的主机文件：
```bash
npx -y --package=@vodailoc/kilo-kit-mcp kilo-kit-init init --client all
```
这将 Kilo-Kit C4 块写入：
| 客户端 | 文件 |
| --- | --- |
| Gemini CLI | `GEMINI.md` |
| OpenAI Codex | `AGENTS.md` |
| Claude Code | `CLAUDE.md` |
该块包裹在 `KILO-KIT:C4` 标记中，因此再次运行命令会更新 Kilo-Kit 部分，而不会删除现有的项目规则。
对于 Windows 上的 Codex CLI，请在源代码检查之外使用 npm 前缀，以便 npm 不会解析本地检查：
```toml
[mcp_servers.kilo-kit]
command = "npm"
args = ["exec", "--prefix", "C:\\Users\\Admin", "--yes", "--package=@vodailoc/kilo-kit-mcp", "--", "kilo-kit-mcp"]
startup_timeout_sec = 60
enabled = true
```
## 为什么需要引导
MCP 公开工具、提示、资源和服务器指令。它不会强制每个主机代理自动调用这些工具。
Kilo-Kit 在四个地方提供 C4 规则：
- MCP 服务器指令。
- MCP 资源 `kilo://rules/c4`。
- MCP 提示 `kilo-c4-workflow`。
- `kilo-kit-init` 创建的主机引导文件。
引导文件是可靠的部分。它告诉主机代理在实施前调用 C4 而不是等待用户手动请求 MCP 使用。
## C4 工作流
`kilo_orchestrate_task` 是主要的 C4 入口点。它不执行代码。它路由请求，记录状态，并在门控条件满足时释放下一个工作流。
预期的流程是：
```text
1. 用户发送实质性任务。
2. 代理调用 kilo_orchestrate_task(message, context)。
3. C4 路由任务并注入生产力/集思广益。
4. 状态变为 brainstorming_required。
5. 代理使用 kilo_get_skill 加载生产力/集思广益。
6. 代理遵循该技能并获得用户批准。
7. 代理使用相同的 sessionId 和 brainstormingApproved=true 再次调用 kilo_orchestrate_task。
8. C4 检查内存建议。
9. 如果存在建议，状态变为 awaiting_memory_confirmation。
10. 代理使用 memoryConfirmations 接受或拒绝建议。
11. 状态变为 ready。
12. C4 返回没有生产力/集思广益的最终工作流。
13. 代理使用 kilo_get_skill 加载第一个工作流技能。
14. 代理还在内部技能列表中检查其他相关技能，然后再编码。
15. 代理执行工作流，并在完成前满足返回的 verificationGate。
```
只读请求（如状态、显示、读取或解释）可以跳过集思广益门控。
### C4 状态
| 状态 | 含义 |
| --- | --- |
| `brainstorming_required` | 在加载、遵循和批准 `productivity/brainstorming` 之前，实质性工作被阻止。 |
| `awaiting_memory_confirmation` | C4 找到记住的操作偏好。代理必须在执行之前接受或拒绝它们。 |
| `ready` | C4 已释放后集思广益工作流和验证门控。 |
### 返回的工作流
当 C4 准备就绪时，它会返回：
- `finalWorkflow`：任务模式的有序 Kilo-Kit 技能步骤。
- `firstSkillToLoad`：代理应使用 `kilo_get_skill` 加载的第一个技能。
- `verificationGate`：代理必须在完成前通过的命令和理由。
- `nextAction`：代理的即时指令。
- `auditRef`：当启用编排审计 JSONL 时存在。
返回的工作流是一个主要路由，而不仅仅是一个上下文源。代理还必须检查自己的可用技能列表，并在实施前加载其他相关技能。
## MCP 工具
| 工具 | 目的 |
| --- | --- |
| `kilo_orchestrate_task` | 实质性工作的 C4 门控。内部路由，强制先进行集思广益，检查内存，并释放最终工作流。 |
| `kilo_route_intent` | 将请求路由到推荐的技能、任务模式、工作流顺序、规则层次和决策轨迹。 |
| `kilo_search_skills` | 通过自然语言查询搜索技能目录。 |
| `kilo_get_skill` | 加载具有上下文安全截断的精确 `SKILL.md`。 |
| `kilo_route_report` | 报告路由遥测、顶级技能、工作流、平均分数和冲突惩罚。 |
| `kilo_memory_report` | 报告 C4 内存事实、决策、建议、会话和工作流结果。 |
| `kilo_validate_skills` | 运行技能验证门控。 |
## MCP 资源
| 资源 | 目的 |
| --- | --- |
| `kilo://skills/index` | 用于发现的轻量级技能索引。 |
| `kilo://core/master` | 核心 Kilo-Kit 主指令。 |
| `kilo://rules/c4` | C4 工作流的最小主机代理操作规则。 |
| `kilo://skills/{category}/{skill}` | 一个技能的动态技能资源。 |
## 持久性
路由遥测默认存储在内存中。通过以下方式启用 JSONL 决策持久性：
```bash
KILO_KIT_WRITE_DECISIONS=true
KILO_KIT_DECISION_TRAIL_PATH=/absolute/path/decision-trail.jsonl
```
如果未设置 `KILO_KIT_DECISION_TRAIL_PATH`，路由决策将写入 `.kilo/decision-trail.jsonl`，位于 `KILO_KIT_REPO_ROOT` 下。
C4 内存使用 `node:sqlite`，默认情况下使用：
```text
~/.kilo-kit/orchestrator.sqlite
```
覆盖 C4 路径：
```bash
KILO_KIT_MEMORY_PATH=/absolute/path/orchestrator.sqlite
KILO_KIT_ORCHESTRATION_AUDIT_PATH=/absolute/path/orchestration-audit.jsonl
```
C4 内存存储结构化事实、决策、编排会话和工作流结果。审计文件存储追加状态转换事件。
## 技能库
`skills/` 是随软件包提供的 工作流表面。
| 路径 | 目的 |
| --- | --- |
| `skills/SKILLS_INDEX.md` | 用于路由和发现的轻量级索引。 |
| `skills/kilo-kit/` | 核心 Kilo-Kit 框架技能。 |
| `skills/engineering/` | 工程和框架工作流。 |
| `skills/productivity/` | 代理工作流和规划技能。 |
| `skills/problem-solving/` | 调试和推理技能。 |
| `skills/design/` | 前端和产品设计技能。 |
| `skills/operations/` | DevOps、MCP、shell、浏览器和服务器技能。 |
| `skills/writing-docs/` | 文档、幻灯片、PDF、电子表格和图表。 |
安装完整的技能库：
```bash
npx skills@latest add VoDaiLocz/KILO-KIT
```
安装一个类别：
```bash
npx skills@latest add VoDaiLocz/KILO-KIT/skills/engineering
```
安装一个技能：
```bash
npx skills@latest add VoDaiLocz/KILO-KIT/skills/engineering/tdd
```
## 仓库布局
```text
.
|-- .claude-plugin/ Claude Code 入口指令
|-- .codex/ Codex 入口指令
|-- .cursor-plugin/ Cursor 入口指令
|-- .mcp/ MCP 配置示例
|-- .opencode/ OpenCode 入口指令
|-- commands/ 可重用工作流命令
|-- docs/ 架构和规划文档
|-- examples/ 示例工作流
|-- mcp/ TypeScript MCP 服务器
|-- skills/ 可安装的技能库
|-- src/core/ 核心框架文档和验证器入口文件
`-- src/tools/ 技能初始化和验证工具
```
## 本地开发
安装、构建、测试和烟雾检查 MCP 服务器：
```bash
npm --prefix mcp install
npm --prefix mcp run build
npm --prefix mcp run typecheck
npm --prefix mcp test
npm --prefix mcp run smoke
node src/tools/validate-skill.js --all skills
```
在开发过程中使用本地 MCP 服务器：
```json
{
"mcpServers": {
"kilo-kit": {
"command": "node",
"args": ["/absolute/path/to/KILO-KIT/mcp/dist/server.js"],
"env": {
"KILO_KIT_REPO_ROOT": "/absolute/path/to/KILO-KIT"
}
}
}
}
```
## 发布
根软件包通过 GitHub Actions 从 npm Trusted Publishing 发布。
配置 npm 一次：
| 字段 | 值 |
| --- | --- |
| 提供者 | GitHub Actions |
| 仓库 | `VoDaiLocz/KILO-KIT` |
| 工作流文件名 | `publish.yml` |
然后运行 `发布 npm 包` 工作流或推送版本标签：
```bash
git tag v1.3.1
git push origin v1.3.1
```
发布工作流运行构建、类型检查、测试、烟雾、技能验证、软件包干运行和 `npm publish --access public --ignore-scripts`。
## 路线图
- v1.3.x：C4 门控强化、内存/审计清晰度、文档清理。
- v2.0.0：用于 C4 会话、内存和审计审查的本地可视化工作流构建器。
## 许可证
Apache 2.0。参见 [LICENSE](./LICENSE)。
