# https://github.com/aibenyclaude-coder/Kira 项目说明书
生成时间：2026-07-15 04:33:18 UTC
## 目录
- [Kira 概览：让 AI 代理不再重复犯错](#page-1)
- [系统架构：本地存储 + MCP 服务器 + Cloudflare Worker](#page-2)
- [核心 MCP 工具详解（10 个）](#page-3)
- [隐私设计、遥测与本地状态管理](#page-4)
- [技能目录（Skills）与伤痕语料（Scars）](#page-5)
- [安装、客户端配置与运行环境](#page-6)
- [飞轮改进循环：失误 → 反馈 → 目录升级](#page-7)
- [贡献、发布与版本演进（v0.3.1 → v0.8.2）](#page-8)
## Kira 概览：让 AI 代理不再重复犯错
### 相关页面
相关主题：[系统架构：本地存储 + MCP 服务器 + Cloudflare Worker](#page-2), [核心 MCP 工具详解（10 个）](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/aibenyclaude-coder/Kira/blob/main/README.md)
- [DESIGN.md](https://github.com/aibenyclaude-coder/Kira/blob/main/DESIGN.md)
- [PRO-DESIGN.md](https://github.com/aibenyclaude-coder/Kira/blob/main/PRO-DESIGN.md)
- [PLAN.md](https://github.com/aibenyclaude-coder/Kira/blob/main/PLAN.md)
- [package.json](https://github.com/aibenyclaude-coder/Kira/blob/main/package.json)
- [src/index.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/src/index.ts)
- [src/skills/](https://github.com/aibenyclaude-coder/Kira/tree/main/src/skills)
- [src/scars/](https://github.com/aibenyclaude-coder/Kira/tree/main/src/scars)
- [docs/mcp-server-card.md](https://github.com/aibenyclaude-coder/Kira/blob/main/docs/mcp-server-card.md)
- [CHANGELOG.md](https://github.com/aibenyclaude-coder/Kira/blob/main/CHANGELOG.md)
# Kira 概览：让 AI 代理不再重复犯错
Kira 是一个为 AI 代理（agent）提供"经验记忆"的 MCP（Model Context Protocol）服务器。其核心目标是：让 agent 在执行任务前能够自动获取相关领域的最佳实践（Skills），并在执行过程中避免已知陷阱（Scars），从而显著降低重复犯错的概率。资料来源：[README.md:1-30]()
## 核心问题与设计动机
AI 代理在处理真实工程任务时，常常会重复触发同类错误——例如错误地处理 ffmpeg 表达式、误判 npm 404 状态码、忽视并行发布竞态等。Kira 将这些真实发生过的失败抽象为"伤疤（Scars）"，把经过验证的操作流程抽象为"技能（Skills）"，构成一个双向飞轮：agent 应用 Skills → 上报执行结果 → 数据回流改进索引。资料来源：[DESIGN.md:12-45]()
截至 v0.8.2 版本，Kira 语料库已积累 **38 个 Skills** 与 **27 个 Scars**，全部来源于真实生产事故的提炼。资料来源：[CHANGELOG.md:1-15]()
## 工具集与工作流
Kira 通过 10 个 MCP 工具向 agent 暴露能力，以下表格概述其分层职责：
| 工具名 | 阶段 | 用途 |
|---|---|---|
| `kira_lookup` | 检索 | 在 Skills/Scars 索引中搜索匹配项 |
| `kira_route` | 路由 | 根据任务关键词分派到对应领域 |
| `kira_get` | 获取 | 拉取单条 Skill 或 Scar 的完整内容 |
| `kira_premortem` | 预演 | 在任务开始前生成失败热力图 |
| `kira_record_failure` | 记录 | 将个人失败写入本地私有伤疤库 |
| `kira_personal_brief` | 会话 | SessionStart 注入个人伤疤摘要 |
| `kira_share_scar` | 共享 | 将个人伤疤泛化为社区候选（不直接上传） |
| `kira_report` | 上报 | 匿名反馈 Skill 应用结果（隐私优先） |
| `kira_consent` | 授权 | 管理遥测开关 |
| `kira_status` | 状态 | 查询本地语料库与连接状态 |
资料来源：[DESIGN.md:60-110]() 资料来源：[docs/mcp-server-card.md:1-40]()
工作流可概括为三步：① `kira_route` → ② `kira_lookup` + `kira_get` → ③ 任务执行后 `kira_record_failure` 或 `kira_report`。v0.6.0 起所有工具均带 MCP Tool Annotations（`readOnlyHint`、`destructiveHint`、`idempotentHint`、`openWorldHint`），遵循 Anthropic 提出的"工具注释即风险词汇表"规范。资料来源：[CHANGELOG.md:30-50]()
## 个人伤疤与社区伤疤的双层模型
Kira 区分两类伤疤：**个人伤疤（Personal Scar）** 仅存放于 `~/.kira/personal-scars/`，完全本地、零网络外泄，承载团队或个人的私有失败记忆；**社区伤疤（Community Scar）** 来自 GitHub Issue 提交流程，需经过人工审核与脱敏泛化。`kira_share_scar` 工具仅生成预填好的 GitHub Issue URL 与 `gh` CLI 回退命令，**不执行任何上传操作**，提交仍是显式的人类行为。资料来源：[DESIGN.md:130-180]() 资料来源：[CHANGELOG.md:55-75]()
```mermaid
flowchart LR
A[agent 触发任务] --> B[kira_route]
B --> C[kira_lookup]
C --> D{命中?}
D -- 是 --> E[kira_get 拉取详情]
D -- 否 --> F[fallback 推荐近邻]
E --> G[执行任务]
G --> H{是否失败?}
H -- 是 --> I[kira_record_failure]
H -- 否 --> J[kira_report 匿名反馈]
I --> K[~/.kira/personal-scars/]
J --> L[Cloudflare Worker]
L --> M[改进社区索引]
K --> N[kira_share_scar 可选]
N --> O[GitHub Issue 草稿]
```
## 隐私优先的遥测与发布飞轮
v0.5.0 引入的隐私优先遥测是飞轮能否转动的关键。`kira_report` 不再写入本地日志，而是通过 Cloudflare Worker 后端进行聚合，确保用户**信任管道**后才持续开启。`kira_consent` 提供显式授权开关，所有上报字段在客户端预脱敏。资料来源：[PRO-DESIGN.md:40-80]()
发布流程本身也持续被自身的 Scars 约束：v0.8.1 从发布夜事故中提炼出 `piped-gate`、`push-race`、`write-without-read`、`merge-compile-gate`、`UTC-misread`、`npm-404-is-auth` 等流程性伤疤，并新增 `cut-a-release`、`delegate-to-subagents`、`npm-trusted-publishing` 等过程性 Skills。资料来源：[CHANGELOG.md:80-110]() 资料来源：[PLAN.md:20-60]()
## 安装与最小可用配置
通过 `npx @kira/mcp` 即可一行安装，无需本地数据库、无需配置文件。所有语料随包分发，离线可用；联网后增量同步社区更新。v0.4.0 改进了搜索质量（Tier 3 词重叠需 ≥2 个有意义词），`"react native"` 不再误返回 `react-email` 或 `zod-validation`，零结果时主动推荐最近邻项。资料来源：[README.md:30-70]() 资料来源：[CHANGELOG.md:20-35]()
```json
// package.json 中的最小 MCP 声明
{
"mcpServers": {
"kira": {
"command": "npx",
"args": ["@kira/mcp"]
}
}
}
```
## 总结
Kira 的本质是给 AI 代理装上一个**会累积伤疤的工程记忆**。Skills 告诉它"应该怎么做"，Scars 提醒它"哪些坑已经踩过"，飞轮把每一次真实失败转化为下一次更可靠的执行。当前 v0.8.2 已具备完整的个人↔社区伤疤双向通道、隐私优先遥测、MCP 工具注释合规三大支柱，定位为"一处安装，agent 自动避错"的轻量级基础设施。资料来源：[README.md:1-30]() 资料来源：[DESIGN.md:1-60]()
---
## 系统架构：本地存储 + MCP 服务器 + Cloudflare Worker
### 相关页面
相关主题：[隐私设计、遥测与本地状态管理](#page-4), [安装、客户端配置与运行环境](#page-6)
相关源码文件
以下源码文件用于生成本页说明：
- [src/index.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/src/index.ts)
- [src/server.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/src/server.ts)
- [src/index-loader.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/src/index-loader.ts)
- [src/license.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/src/license.ts)
- [src/errors.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/src/errors.ts)
- [src/logger.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/src/logger.ts)
- [src/telemetry.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/src/telemetry.ts)
- [worker/src/index.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/worker/src/index.ts)
# 系统架构：本地存储 + MCP 服务器 + Cloudflare Worker
Kira 由三层组成：本地存储（私有失败记忆 + 技能索引）、MCP 服务器（向代理暴露的 10 个工具）以及 Cloudflare Worker（隐私优先的遥测后端）。三层通过明确的数据所有权和最小的网络面协同工作，构成「代理应用技能 → 上报结果 → 数据回流改进索引」的飞轮。
## 本地存储层
本地存储承担两件事：技能/伤疤语料库的只读索引，以及个人伤疤的写入路径。
- **技能索引**：由 [src/index-loader.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/src/index-loader.ts) 在 MCP 服务器启动时加载并缓存，用于 `kira_lookup` / `kira_route` 的关键词与分类检索。索引内容来自项目内的语料库文件，不在运行时联网拉取。
- **个人伤疤目录**：v0.7.0 引入的 `~/.kira/personal-scars/` 目录是**唯一**的本地写入点。`kira_record_failure` (F1) 把重试/异常捕获为私人伤疤；`kira_premortem` (F3) 在任务开始前按历史命中数排序生成失败热图。资料来源：[src/server.ts:1-120]()
- **License 与启动校验**：[src/license.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/src/license.ts) 在加载索引前执行授权检查；[src/logger.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/src/logger.ts) 提供结构化日志，本地存储失败时统一以 [src/errors.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/src/errors.ts) 中的错误类型抛出，避免静默丢失伤疤记录。
## MCP 服务器层
`src/index.ts` 引导 [src/server.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/src/server.ts) 注册 MCP 工具与传输层（stdio / 可选 HTTP）。v0.6.0 起全部工具携带 `readOnlyHint`、`destructiveHint`、`idempotentHint`、`openWorldHint` 注解，作为风险词汇交给宿主代理。
| 工具 | 注解定位 | 关键来源版本 |
|---|---|---|
| `kira_lookup` / `kira_route` / `kira_get` | 只读查询本地索引 | v0.3.1+ |
| `kira_report` | 幂等上报遥测 | v0.5.0 |
| `kira_consent` | 破坏性：开启/关闭遥测 | v0.5.0 |
| `kira_status` | 只读诊断 | v0.3.1+ |
| `kira_record_failure` / `kira_personal_brief` / `kira_premortem` | 本地写入 | v0.7.0 |
| `kira_share_scar` | 仅生成分享 URL，不上传 | v0.8.0 |
服务器层将所有网络调用收敛到 `kira_report` 一处，其它工具不直接出网，便于宿主以注解决定是否放行。资料来源：[src/server.ts:120-260]()
## Cloudflare Worker 层（Phase A）
v0.5.0 将遥测后端从本地日志文件替换为 [worker/src/index.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/worker/src/index.ts) 部署的 Cloudflare Worker，定位为「飞轮的数据接收端」。设计原则：
- **隐私优先**：客户端在 [src/telemetry.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/src/telemetry.ts) 内做最小化与脱敏，Worker 仅接收必要的命中/反馈字段。
- **可控开关**：遥测默认受 `kira_consent` 门控，关闭时 `kira_report` 直接 short-circuit，不出网。
- **幂等接收**：Worker 端按上报去重，使 `kira_report` 满足 `idempotentHint`。
Worker 与本地存储共享同一份语料库契约（技能 slug、伤疤类别、结果枚举），保证回流数据可被用于索引权重再训练。资料来源：[worker/src/index.ts:1-80]()
## 数据流与故障隔离
```mermaid
flowchart LR
Agent[AI 代理] -->|MCP stdio/HTTP| Server[src/server.ts]
Server -->|本地只读| Index[(技能索引)]
Server -->|本地写入| PScar[(~/.kira/personal-scars/)]
Server -->|kira_report 启用| Worker[Cloudflare Worker]
Worker -->|聚合反馈| Indexer[索引再训练]
Indexer -.更新.-> Index
```
故障隔离原则：任何 Worker 不可达不得阻塞本地工具；任何本地写入失败必须显式抛错并被 [src/errors.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/src/errors.ts) 分类。这一边界在 v0.8.0 `kira_share_scar` 中再次强化——该工具只生成 GitHub Issue URL 与 `gh` 回退命令，**不上传任何内容**，把「提交」动作留给显式的人工操作。资料来源：[src/server.ts:260-340]()
---
## 核心 MCP 工具详解（10 个）
### 相关页面
相关主题：[Kira 概览：让 AI 代理不再重复犯错](#page-1), [技能目录（Skills）与伤痕语料（Scars）](#page-5), [飞轮改进循环：失误 → 反馈 → 目录升级](#page-7)
相关源码文件
以下源码文件用于生成本页说明：
- [src/index.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/src/index.ts)
- [src/tools/kira_lookup.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/src/tools/kira_lookup.ts)
- [src/tools/kira_route.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/src/tools/kira_route.ts)
- [src/tools/kira_get.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/src/tools/kira_get.ts)
- [src/tools/kira_report.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/src/tools/kira_report.ts)
- [src/tools/kira_consent.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/src/tools/kira_consent.ts)
- [src/tools/kira_status.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/src/tools/kira_status.ts)
- [src/tools/record-failure.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/src/tools/record-failure.ts)
- [src/tools/personal-brief.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/src/tools/personal-brief.ts)
- [src/tools/premortem.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/src/tools/premortem.ts)
- [src/tools/share-scar.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/src/tools/share-scar.ts)
# 核心 MCP 工具详解（10 个）
Kira 通过单一 MCP（Model Context Protocol）服务器向 AI agent 暴露 **10 个核心工具**，由 `src/index.ts` 中的 `ListToolsRequest` 处理器统一注册。`资料来源：[src/index.ts:1-80]()`
这 10 个工具围绕"让 agent 找到正确指令、规避已知错误、并把执行结果回流以改进索引"这条飞轮（flywheel）展开：前 6 个是 v0.6.0 之前的检索/上报/状态工具；后 4 个（F1–F4）属于 v0.7.0–v0.8.0 推出的"个人 scar 闭环"系列。
## 核心检索与上报工具（6 个）
这一组构成 Kira 飞轮的主要数据流：搜索→路由→取详情→上报。
| 工具 | 用途 | 注解关键字 |
| --- | --- | --- |
| `kira_lookup` | 关键词搜索技能（Skills）索引 | `readOnlyHint`, `openWorldHint` |
| `kira_route` | 根据目标与上下文选择最佳 Skill | `readOnlyHint` |
| `kira_get` | 拉取某个 Skill 的完整正文 | `readOnlyHint`, `idempotentHint` |
| `kira_report` | 上报 Skill 应用结果到 Cloudflare Worker | `destructiveHint:false` |
| `kira_consent` | 管理用户对遥测的隐私授权 | `idempotentHint` |
| `kira_status` | 查询当前 Kira 实例、语料、scars 健康状态 | `readOnlyHint` |
`资料来源：[src/tools/kira_lookup.ts:1-60]()` `资料来源：[src/tools/kira_route.ts:1-50]()` `资料来源：[src/tools/kira_get.ts:1-50]()` `资料来源：[src/tools/kira_report.ts:1-90]()` `资料来源：[src/tools/kira_consent.ts:1-40]()` `资料来源：[src/tools/kira_status.ts:1-40]()`
`kira_lookup` 的搜索质量在 v0.4.0 经历了一次大幅重写：Tier 3 词重叠现在要求 2 个以上有意义词匹配，"react native" 不再误中 react-email，0 结果时返回最近邻建议。`资料来源：[src/tools/kira_lookup.ts:30-120]()` `kira_report` 在 v0.5.0 接入 Cloudflare Worker，将上报数据从本地文件改为可信任的远端管道，并支持 `kira_consent` 控制的隐私授权。`资料来源：[src/tools/kira_report.ts:25-90]()`
## 个人与社区 scar 工具（4 个）
第二组四个工具由 v0.7.0 推出 `kira_record_failure`（F1）、`kira_personal_brief`（F2）、`kira_premortem`（F3），并在 v0.8.0 补上 `kira_share_scar`（F4 v1，10th tool）。它们面向"失败记忆"——把 agent 实际遇到的报错固化为本地 scar，并在开始新任务前预先加载。
- **F1 `kira_record_failure`**：把一次 retry/exception 落盘为 **个人 scar**，仅写到 `~/.kira/personal-scars/`，对外不可见。`资料来源：[src/tools/record-failure.ts:1-80]()`
- **F2 `kira_personal_brief`**：在 SessionStart 钩子中按目标加载匹配的 scars，形成简短的"个人风险简报"。`资料来源：[src/tools/personal-brief.ts:1-60]()`
- **F3 `kira_premortem`**：在 agent 行动前生成失败热力图，按历史 scar 命中次数排序。`资料来源：[src/tools/premortem.ts:1-70]()`
- **F4 `kira_share_scar`**：把个人 scar 升级为社区提交——重新脱敏、泛化到社区形态，并返回预填好的 GitHub issue URL 和 `gh` 命令回退；**该工具不直接上传任何内容**，提交动作必须由人显式完成。`资料来源：[src/tools/share-scar.ts:1-120]()`
F4 是关键设计：它把"上报"的最后一公里留给人类，保证自动化不会绕过社区审核。`资料来源：[src/tools/share-scar.ts:40-90]()`
## 工具注解（Tool Annotations）
v0.6.0 起，10 个工具全部带上了 MCP 注解字段：`readOnlyHint`、`destructiveHint`、`idempotentHint`、`openWorldHint`，遵循 Anthropic 关于"把工具注解当作风险词汇"的设计——agent 客户端可据此决定是否需要再次确认、是否允许并发调用。`资料来源：[src/index.ts:30-80]()` 例如 `kira_report` 显式声明 `destructiveHint:false`、写操作类工具都标记 `idempotentHint`，这与 v0.8.1 中吸取的 `piped-gate`、`push-race`、`write-without-read` 三条发布工程 scar 直接呼应。`资料来源：[src/index.ts:60-120]()`
## 工作流概览
```mermaid
flowchart LR
A[Agent 启动] --> B[kira_personal_brief]
B --> C{目标是否风险高?}
C -- 是 --> D[kira_premortem]
C -- 否 --> E[kira_lookup]
D --> E
E --> F[kira_route]
F --> G[kira_get]
G --> H[执行任务]
H --> I{失败?}
I -- 是 --> J[kira_record_failure]
I -- 否 --> K[kira_report]
J --> L{是否值得分享?}
L -- 是 --> M[kira_share_scar]
L -- 否 --> N[~/.kira/personal-scars/]
M --> O[人工提交到社区]
K --> P[Cloudflare Worker]
```
这张图把 10 个工具串成一条闭环：检索路线在前、个人 scar 记忆在旁、社区贡献在末。`资料来源：[src/index.ts:80-150]()`
## 选型与使用建议
1. 只想"自动找指令"：只用 `kira_lookup` + `kira_get` + `kira_status` 即可，零副作用。
2. 想让飞轮转起来：额外加 `kira_report`，并在 `kira_consent` 中明确授权范围。
3. 想要更稳的 agent：把 F1–F3 三个工具接入 SessionStart 钩子，使每个任务在动手前先经过 `kira_personal_brief` 和 `kira_premortem`。
4. 想回馈社区：使用 `kira_share_scar` 生成 URL，由人审核后再点击提交。
---
## 隐私设计、遥测与本地状态管理
### 相关页面
相关主题：[系统架构：本地存储 + MCP 服务器 + Cloudflare Worker](#page-2), [贡献、发布与版本演进（v0.3.1 → v0.8.2）](#page-8)
相关源码文件
以下源码文件用于生成本页说明：
- [PRIVACY.md](https://github.com/aibenyclaude-coder/Kira/blob/main/PRIVACY.md)
- [SECURITY.md](https://github.com/aibenyclaude-coder/Kira/blob/main/SECURITY.md)
- [src/sanitize.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/src/sanitize.ts)
- [src/consent.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/src/consent.ts)
- [src/telemetry.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/src/telemetry.ts)
- [src/report.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/src/report.ts)
# 隐私设计、遥测与本地状态管理
Kira 是一个面向 AI Agent 的 MCP 工具集，其飞轮机制（agent 应用 Skill → 回报执行结果 → 数据回流用于改进索引）天然依赖用户对"上报管道"的信任。因此隐私、遥测与本地状态在 Kira 中不是边缘功能，而是核心架构支柱。本页覆盖三条主线：**敏感信息脱敏（sanitize）**、**遥测与同意机制（telemetry/consent）**、**本地状态管理（personal-scars / 个人失败记忆）**。
## 一、隐私设计原则与作用域
Kira 的隐私立场写明于顶层文档 `PRIVACY.md`，核心原则是"默认本地、显式上传、最小化数据"。所有可能离开用户主机的数据都必须经过 `src/sanitize.ts` 中的脱敏管道，绝不允许在未授权情况下写入远程后端。`SECURITY.md` 进一步规定威胁模型：恶意 Skill 注入、日志泄露、第三方 Worker 滥用，以及个人/社区双层数据边界。资料来源：[PRIVACY.md:1-40]()
| 数据类别 | 存储位置 | 上传条件 | 是否可清空 |
|---|---|---|---|
| Skill 索引 | 包内只读 | 永不上传 | 否 |
| Community scar | 仓库 `corpus/` | 仅在用户触发 `kira_share_scar` 时 | 是（版本化） |
| Personal scar | `~/.kira/personal-scars/` | 默认**永不上传** | 是（删除目录） |
| Telemetry 事件 | Cloudflare Worker（Phase A） | 必须先经 `kira_consent` 同意 | 是（opt-out） |
## 二、敏感信息脱敏（Sanitize Pipeline）
`src/sanitize.ts` 是所有外发数据的统一闸口。它对命令字符串、文件路径、URL、JSON 值执行正则替换与结构化改写，覆盖以下模式：
- API key / token（`sk-`、`ghp_`、`AKIA`、`xoxb-` 等前缀）
- 私有 IP / RFC1918 段
- 文件系统绝对路径中的用户名
- Bearer header、Basic auth
- 邮件地址
脱敏后保留语义骨架（例如 `${USER}/repo` → `__USER__/repo`），以便 Cloudflare Worker 侧仍可聚合统计。`kira_share_scar`（v0.8.0 引入，第 10 个工具）会**重新跑一次脱敏**，把个人 scar 泛化为社区形态后再返回预填的 GitHub issue URL，工具本身不发起任何网络请求。资料来源：[src/sanitize.ts:1-80]()
```mermaid
flowchart LR
A[原始错误/命令] --> B[src/sanitize.ts]
B --> C{含敏感模式?}
C -- 是 --> D[替换为占位符]
C -- 否 --> E[保留原文]
D --> F[脱敏载荷]
E --> F
F --> G[consent gate]
G -- 已同意 --> H[Cloudflare Worker]
G -- 未同意 --> I[丢弃/仅本地]
```
## 三、同意机制与遥测（Consent & Telemetry）
v0.5.0 上线"Privacy-first telemetry + Cloudflare Worker (Phase A)"。在此之前 `kira_report` 仅写本地日志，飞轮无法转动。新版引入 `src/consent.ts` 与 `src/telemetry.ts`，并暴露两个 MCP 工具：`kira_consent`（写入同意位）和 `kira_status`（读取当前状态）。
- **同意位持久化**：以 `~/.kira/consent.json` 存储，包含 `telemetry`（boolean）与 `share_scar`（boolean）两个字段，可分别独立撤销。
- **遥测载荷最小化**：仅包含 `event`、`skill_id` 哈希、`outcome`（success/fail）、`latency_ms`、脱敏后的命令骨架，绝不包含 prompt 原文。
- **网络后端**：Cloudflare Worker，不持久化用户 IP；Workers KV 仅按 `skill_id_hash` 聚合计数。
- **Tool annotations**：v0.6.0 起，所有 6 个核心工具标注 `readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint`，使 Host（如 Claude Desktop）能在 UI 上提示风险。资料来源：[src/consent.ts:1-60]()、[src/telemetry.ts:1-90]()、[src/report.ts:1-50]()
## 四、本地状态管理：Personal Scars
v0.7.0"Close the Personal-Scar Loop" 引入三层工具：
1. `kira_record_failure`（F1）：把 retry/exception 落盘为**个人 scar**，路径 `~/.kira/personal-scars/.md`，纯本地，**永远不出主机**。
2. `kira_personal_brief`（F2）：在 SessionStart 注入历史失败摘要，让 agent 在动手前就看见"我上次在这里摔过"。
3. `kira_premortem`（F3）：给定一个目标，按历史 scar 命中度排序输出失败热力图。
本地状态目录遵循 XDG 风格：
```
~/.kira/
├── consent.json
├── personal-scars/
│ ├── a1b2.md
│ └── c3d4.md
└── cache/
```
v0.8.0 的 `kira_share_scar` 把"本地 → 社区"这条转化路径也纳入了脱敏与同意双重闸门：先脱敏、再泛化、最后由人类点击 issue 链接提交，工具本身**不上传任何字节**。这种"工具只产出 URL、人类负责最后一公里"的设计，是 Kira 把"信任"显式外化的关键决策。资料来源：[SECURITY.md:1-60]()、[PRIVACY.md:40-80]()
## 总结
Kira 的隐私架构可概括为三句话：**默认本地**（personal-scars 默认永不外发）、**显式同意**（telemetry 与 share_scar 双独立 opt-in）、**强制脱敏**（所有外发数据必经 `sanitize.ts`）。三者通过 `consent.json` 与文件系统约定耦合，而非引入复杂 RBAC，使 Host 集成成本最低的同时保留了用户对飞轮管道的可控性。
---
## 技能目录（Skills）与伤痕语料（Scars）
### 相关页面
相关主题：[核心 MCP 工具详解（10 个）](#page-3), [飞轮改进循环：失误 → 反馈 → 目录升级](#page-7), [贡献、发布与版本演进（v0.3.1 → v0.8.2）](#page-8)
相关源码文件
以下源码文件用于生成本页说明：
- [docs/corpus.json](https://github.com/aibenyclaude-coder/Kira/blob/main/docs/corpus.json)
- [scripts/gen-corpus.mjs](https://github.com/aibenyclaude-coder/Kira/blob/main/scripts/gen-corpus.mjs)
- [scripts/validate-entry.mjs](https://github.com/aibenyclaude-coder/Kira/blob/main/scripts/validate-entry.mjs)
- [routes/web-app-nextjs.json](https://github.com/aibenyclaude-coder/Kira/blob/main/routes/web-app-nextjs.json)
- [routes/build-saas.json](https://github.com/aibenyclaude-coder/Kira/blob/main/routes/build-saas.json)
- [routes/api-stripe.json](https://github.com/aibenyclaude-coder/Kira/blob/main/routes/api-stripe.json)
# 技能目录（Skills）与伤痕语料（Scars）
## 概述与设计动机
Kira 项目以"飞轮"模型组织知识：智能体应用 Skills 完成工作 → 报告执行结果 → 反馈数据回流改进索引。在该飞轮中，**技能目录（Skills）** 提供"如何做"的指令集合，**伤痕语料（Scars）** 则记录"不要再踩"的失败记忆。两者共同构成 Kira 的双层知识底座：Skills 偏正向引导、Scars 偏逆向防御。截至 v0.8.2，语料库规模为 **38 个 Skills / 27 个 Scars**，均通过 `docs/corpus.json` 统一聚合发布。资料来源：[docs/corpus.json:1-50]()
技能目录源自真实工具栈的常见任务（如 Vercel、Cloudflare、Supabase、Prisma、Stripe、Clerk、shadcn/ui、Tailwind v4、Vitest、Playwright、GitHub Actions、Docker 等），而伤痕语料则来源于实际发布夜中采集的失败案例（如并行轨道发布竞态、web 平台陷阱、ffmpeg 的 crop 表达式只求值一次、animated-testsrc 帧差假阳性、无穷 lavfi 源与输出端 `-t` 死锁等）。资料来源：[docs/corpus.json:1-200]()
## 数据模型与条目结构
`docs/corpus.json` 是语料的唯一可信来源（single source of truth），由 `scripts/gen-corpus.mjs` 汇总各 `routes/*.json` 生成。每个 Skills 条目至少包含 `id`、`title`、`type`（值为 `skill`）、`tags`、`route`（相对文件路径），而 Scars 条目的 `type` 字段为 `scar`，并额外携带 `failure_mode` 与 `mitigation` 字段以便逆向检索。下表展示了 Skills 与 Scars 的核心字段差异：
| 维度 | Skill 条目 | Scar 条目 |
| --- | --- | --- |
| 入口类型 | `type: "skill"` | `type: "scar"` |
| 关键字段 | `id`、`title`、`tags`、`route` | `id`、`title`、`tags`、`route`、`failure_mode`、`mitigation` |
| 来源 | 人工整理 + 发布夜收录 | 实际失败回放 + 社区提交（`scar-submission` issue 表单） |
| 检索语义 | 正向匹配：用户提供目标 | 逆向匹配：在 premortem / 失败捕获时触发 |
资料来源：[scripts/validate-entry.mjs:1-120]()、`[routes/web-app-nextjs.json:1-80]()`、`[routes/api-stripe.json:1-60]()`。
举例而言，`routes/web-app-nextjs.json` 描述了在 Next.js 中构建 Web 应用时可能用到的多个 Skills，而 `routes/api-stripe.json` 则收录 Stripe API 集成路径上的指令片段；Scars 通常以同名前缀形成对应（如某个发布轨道下的 `piped-gate`、`push-race`、`write-without-read`）。资料来源：[routes/build-saas.json:1-150]()。
## 生成、校验与发布流程
`scripts/gen-corpus.mjs` 负责将所有 `routes/*.json` 文件聚合并生成 `docs/corpus.json`：读取每个 route 文件，按 `type` 拆分 Skills/Scars，做字段归一化、标签去重与按 id 排序，最终输出可被 MCP 服务器和 `kira_lookup`、`kira_route`、`kira_get` 工具直接消费的扁平化语料。该脚本同时也作为 CI 的入口，对缺失必填字段、重复 id、引用不存在的 scar/skill 引用进行早失败。资料来源：[scripts/gen-corpus.mjs:1-200]()。
`scripts/validate-entry.mjs` 提供条目级校验，确保每条 Skill 必须含可读的 Markdown 正文、相关 tag、稳定的 route 路径；每条 Scar 必须显式声明 `failure_mode`（现象）与 `mitigation`（对策），避免出现"只是抱怨"的低质量条目。这两道闸口共同保证"任何发布的 entry 都能立刻被智能体信任使用"。资料来源：[scripts/validate-entry.mjs:1-120]()。
```mermaid
flowchart LR
A[routes/*.json
Skills / Scars 原始条目] --> B[scripts/gen-corpus.mjs
聚合 / 归一化]
B --> C[docs/corpus.json
统一语料]
C --> D{scripts/validate-entry.mjs
条目校验}
D -- 通过 --> E[MCP Server
kira_lookup / kira_route / kira_get]
D -- 失败 --> F[CI 阻断
禁止合并]
```
## 检索集成与扩展路径
在 MCP 集成侧，`kira_lookup` 通过 Tier 3 词重叠（v0.4.0 起改为"≥2 个有意义词"）将用户查询路由到最佳 Skill；`kira_route` 进一步给出该 Skill 的标准化路线图；`kira_get` 则返回正文。除此之外，v0.7.0 引入的 `kira_record_failure` / `kira_premortem` / `kira_personal_brief` 三个工具把 Scars 拉入个人回路：失败被存为本地 `~/.kira/personal-scars/`，premortem 检索时会按"过往伤痕命中率"对目标排序。v0.8.0 的 `kira_share_scar` 则把个人 scar 消毒、泛化后返回预填好的 GitHub issue URL + `gh` 兜底命令，由人类显式提交，进而回流到社区语料。资料来源：[routes/web-app-nextjs.json:1-80]()`、`[routes/build-saas.json:1-150]()`、`[routes/api-stripe.json:1-60]()`。
扩展 Skills 的推荐路径：新增/修改 `routes/.json` → 跑 `gen-corpus.mjs` 生成本地 `docs/corpus.json` → `validate-entry.mjs` 自检 → 提交 PR；扩展 Scars 的推荐路径：在终端触发失败 → `kira_record_failure` 沉淀本地 scar → 用 `kira_share_scar` 准备社区投稿 → 走 `scar-submission` issue 表单完成提交，等待下一版本收录。
资料来源：[scripts/gen-corpus.mjs:1-200]()`、`[scripts/validate-entry.mjs:1-120]()`、`[docs/corpus.json:1-200]()`、`[routes/web-app-nextjs.json:1-80]()`、`[routes/build-saas.json:1-150]()`、`[routes/api-stripe.json:1-60]()`。
---
## 安装、客户端配置与运行环境
### 相关页面
相关主题：[Kira 概览：让 AI 代理不再重复犯错](#page-1), [系统架构：本地存储 + MCP 服务器 + Cloudflare Worker](#page-2), [隐私设计、遥测与本地状态管理](#page-4)
相关源码文件
以下源码文件用于生成本页说明：
- [USAGE.md](https://github.com/aibenyclaude-coder/Kira/blob/main/USAGE.md)
- [examples/README.md](https://github.com/aibenyclaude-coder/Kira/blob/main/examples/README.md)
- [examples/claude-code.md](https://github.com/aibenyclaude-coder/Kira/blob/main/examples/claude-code.md)
- [examples/cursor.md](https://github.com/aibenyclaude-coder/Kira/blob/main/examples/cursor.md)
- [examples/continue.md](https://github.com/aibenyclaude-coder/Kira/blob/main/examples/continue.md)
- [examples/claude-code-sessionstart-hook.sh](https://github.com/aibenyclaude-coder/Kira/blob/main/examples/claude-code-sessionstart-hook.sh)
# 安装、客户端配置与运行环境
Kira 作为 Model Context Protocol（MCP）服务器向 AI Agent 暴露 10 个工具（`kira_lookup`、`kira_route`、`kira_get`、`kira_report`、`kira_consent`、`kira_status`、`kira_record_failure`、`kira_personal_brief`、`kira_premortem`、`kira_share_scar`），并以 Skills/Scars 语料库驱动 Agent 行为。本页说明如何安装 Kira、将其接入主流 Agent 客户端，以及运行时所需的本地文件系统与 Hook 环境。
## 一、安装方式
Kira 提供两种并列的安装入口：MCP 注册安装与容器化安装，分别面向编辑器内 Agent 与 CI/自托管场景。
### 1.1 MCP 一键注册
通过 MCP 注册表将 Kira 作为 stdio 服务器加入客户端。MCP 注册表返回的安装命令会自动写入客户端的 MCP 配置文件（如 Claude Code 的 `~/.claude.json`、Cursor 的 `~/.cursor/mcp.json`）。`USAGE.md` 中给出的通用形式为：
```
# 在任意 MCP 兼容客户端中执行
claude mcp add kira -- npx -y @aibenyclaude-coder/kira-mcp@latest
```
该命令的语义是“通过 `npx` 拉取最新镜像并以 stdio 形式启动 Kira MCP 进程”，无需用户手动管理 Node 版本。`examples/README.md` 明确说明 `examples/` 目录下的子文件是各客户端的最小可运行配置样例，建议作为失败时回退比对基准。资料来源：[USAGE.md]()、[examples/README.md]()。
### 1.2 Docker 镜像安装
自 v0.8.2 起，仓库引入多阶段 `Dockerfile`，允许以容器方式启动 Kira MCP 服务。该路径主要用于三类场景：在受限 CI 环境内固定版本、跨团队共享同一份运行环境、以及为后续 Cloudflare Worker 后端之外的私有部署预留接口。容器形态下，stdio 仍然通过 MCP 客户端桥接，但底层执行不再依赖宿主机 Node 版本。资料来源：[examples/README.md]()。
## 二、客户端配置
Kira 与 Agent 客户端之间只存在 MCP stdio 接口和（可选的）SessionStart Hook 两类耦合点。`examples/` 目录分别给出 Claude Code、Cursor、Continue 三种客户端的最小配置。
### 2.1 Claude Code
`examples/claude-code.md` 给出 `.mcp.json` 片段，将 `kira` 命名指向 `@aibenyclaude-coder/kira-mcp`。同时 `examples/claude-code-sessionstart-hook.sh` 演示如何把 `kira_personal_brief` 工具挂入 SessionStart：脚本读取 `~/.kira/personal-scars/` 中由 `kira_record_failure` 写入的条目，将其压缩成自然语言简报随会话启动注入，从而让 Agent 在第一次回复前就感知到历史失败。资料来源：[examples/claude-code.md]()、[examples/claude-code-sessionstart-hook.sh]()。
### 2.2 Cursor
`examples/cursor.md` 提供 Cursor 的 `mcp.json` 配置。Cursor 通过 `mcpServers` 字段发现 Kira；与 Claude Code 不同，Cursor 不消费 SessionStart Hook，因此 `kira_personal_brief` 必须由 Agent 在会话中显式调用。该文件还注明 Cursor 对工具注解的渲染策略与 Anthropic 推荐的 Risk Vocabulary（`readOnlyHint`、`destructiveHint`、`idempotentHint`、`openWorldHint`）保持一致。资料来源：[examples/cursor.md]()。
### 2.3 Continue
`examples/continue.md` 演示 Continue（VS Code JetBrains 插件）的 `config.json` 写法。Continue 通过 `mcpServers` 数组挂载 Kira，并将工具标签暴露给本地模型选择器。Continue 同样不支持 SessionStart Hook，因此 SessionStart 行为需借助 Continue 的 `customCommands` 或工作区级脚本触发。资料来源：[examples/continue.md]()。
## 三、运行环境与本地状态
Kira 在宿主机上以 `~/.kira/` 为单一状态根目录，承载个人疤痕语料、用户偏好与遥测开关。下表汇总三类子目录的语义与默认生成时机。
| 路径 | 用途 | 首次写入工具 |
|---|---|---|
| `~/.kira/personal-scars/` | 本地私有失败记忆，仅当前用户可读 | `kira_record_failure` |
| `~/.kira/premortem-cache/` | 目标级失败热图缓存 | `kira_premortem` |
| `~/.kira/config.json` | 遥测同意、镜像源、并发上限 | `kira_consent` |
`kira_consent` 工具持久化的同意位会同时控制 `kira_report` 是否向 Cloudflare Worker 提交匿名使用数据；自 v0.5.0 起遥测被设计为 opt-in，未取得同意时 `kira_report` 退化为本地日志写入。`kira_share_scar`（v0.8.0 第 10 个工具）只生成预填好的 GitHub Issue URL 与 `gh` 回退命令，不会主动上传任何内容。资料来源：[USAGE.md]()、[examples/claude-code-sessionstart-hook.sh]()。
## 四、与 Agent 协作的最小数据流
```mermaid
flowchart LR
A[Agent 客户端] -- stdio --> B[Kira MCP 进程]
A -- SessionStart Hook --> C[claude-code-sessionstart-hook.sh]
C --> D[~/.kira/personal-scars/]
B -- 读取/写入 --> D
B -- opt-in 遥测 --> E[Cloudflare Worker]
B -- 返回 Skills/Scars --> A
```
上图刻画 Kira 与客户端之间三条真实通道：MCP stdio 通道承载全部 10 个工具调用；SessionStart Hook 通道仅在 Claude Code 场景下生效，将本地疤痕压缩为简报；遥测通道在用户显式同意后才会建立。任意一条通道的缺失都不会破坏其余通道的运行，这正是 v0.8.0 引入 Scar 共享与 v0.7.0 引入个人疤痕闭环时坚持的“最小耦合”原则。资料来源：[USAGE.md]()、[examples/claude-code-sessionstart-hook.sh]()。
## 五、常见安装陷阱
仓库在 v0.8.1 与 v0.8.2 中累积了若干与安装/发布强相关的社区 Scar，包括 `piped-gate`、`push-race`、`write-without-read`、`merge-compile-gate`、`UTC-misread`、`npm-404-is-auth`、`nested-package-install`，以及三条 `credential-CI` 闸门。引入 Kira 时应避免：直接将 CI 凭据嵌入 `mcp.json`、在嵌套 monorepo 内重复执行 `npm install`、以及把发布步骤的退出码当作纯日志忽略。建议在 CI 中固定 Node 版本与 `npx` 缓存目录，并对 `kira_report` 的失败使用非零退出码以便门禁识别。资料来源：[USAGE.md]()。
---
## 飞轮改进循环：失误 → 反馈 → 目录升级
### 相关页面
相关主题：[核心 MCP 工具详解（10 个）](#page-3), [技能目录（Skills）与伤痕语料（Scars）](#page-5), [贡献、发布与版本演进（v0.3.1 → v0.8.2）](#page-8)
相关源码文件
以下源码文件用于生成本页说明：
- [FLYWHEEL.md](https://github.com/aibenyclaude-coder/Kira/blob/main/FLYWHEEL.md)
- [src/flywheel.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/src/flywheel.ts)
- [src/report.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/src/report.ts)
- [scripts/scar-intake.mjs](https://github.com/aibenyclaude-coder/Kira/blob/main/scripts/scar-intake.mjs)
- [scripts/gen-stats.mjs](https://github.com/aibenyclaude-coder/Kira/blob/main/scripts/gen-stats.mjs)
- [scripts/stats.ts](https://github.com/aibenyclaude-coder/Kira/blob/main/scripts/stats.ts)
# 飞轮改进循环：失误 → 反馈 → 目录升级
## 概述与定位
Kira 的核心价值主张建立在飞轮模型之上：`agents apply Skills → report outcomes → the data flows back to improve the index`。换言之，每一次失败都不是终点，而是下一次检索命中改进的原料。FLYWHEEL.md 把这一循环作为整个项目的元设计原则进行了文档化，明确说明飞轮"only spins if users trust the pipe enough to leave it on" 资料来源：[FLYWHEEL.md:overview-12]()。
为了让飞轮可持续运转，Kira 划分了三个层级：
| 层级 | 存储位置 | 触发工具 | 公开性 |
| --- | --- | --- | --- |
| 个人疤痕 | `~/.kira/personal-scars/` | `kira_record_failure` | 私有、仅本机 |
| 社区疤痕 | 仓库 `scar-submissions/` | `kira_share_scar` | 公开、由人工提交 |
| 遥测信号 | Cloudflare Worker | `kira_report` + `kira_consent` | 匿名、可关闭 |
资料来源：[src/flywheel.ts:1-40]()、[src/report.ts:1-60]()。
## 三阶段循环
### 阶段一：失误捕获（Failure Capture）
捕获层负责把 agent 运行中的重试与异常沉淀为"个人疤痕"。`kira_record_failure`（F1 工具）会把 retry/exception 写入 `~/.kira/personal-scars/`，作为本机私有失败记忆；同会话启动时，`kira_personal_brief`（F2）会读取这些记录并把高命中项加载到上下文，让 agent 在下一次任务开始前就"知道自己以前在这里栽过" 资料来源：[scripts/scar-intake.mjs:1-30]()。
为了在任务真正开始前暴露风险，`kira_premortem`（F3）会根据目标与历史疤痕做失败热力图排序，让用户先看到最可能踩的坑 资料来源：[src/flywheel.ts:42-90]()。
### 阶段二：反馈上报（Feedback Reporting）
捕获不等于上报，反馈层解决的是"用户愿不愿意把这根水管打开"。v0.5.0 之前 `kira_report` 只能写到本地日志，飞轮实际是断的；Phase A 引入 Cloudflare Worker 作为后端，把上报内容做成 privacy-first 的最小信号集（不携带源码、不携带 prompt，仅携带命中 skill id、命中数与结果码） 资料来源：[src/report.ts:60-140]()。
`kira_consent` 是这条水管的开关：用户必须显式开启遥测，飞轮才把本地信号送出去；任何时候关闭，下一次 `kira_report` 都不会触达 Worker 资料来源：[src/report.ts:141-200]()。
### 阶段三：目录升级（Catalog Upgrade）
当个人疤痕被证明具有复用价值后，进入升级阶段。`kira_share_scar`（F4，第 10 个工具）会把个人疤痕重新脱敏、泛化为社区形态，并返回一个预填好的 GitHub issue URL 和 `gh` 命令兜底——但工具本身不做上传，提交动作必须由人工显式完成 资料来源：[scripts/scar-intake.mjs:31-90]()。
```mermaid
flowchart LR
A[Agent retry/exception] -->|kira_record_failure| B[~/.kira/personal-scars/]
B -->|kira_personal_brief| C[SessionStart 上下文]
C -->|kira_premortem| D[失败热力图]
B -->|kira_share_scar| E[脱敏 + 泛化]
E -->|人工 gh issue| F[scar-submissions/]
F -->|cut-a-release| G[Corpus 38 skills / 27 scars]
G -->|下一次 kira_lookup| A
```
每一次发布周期都会从真实失败里"采收"疤痕：v0.8.2 从 bbutton-site 的质量循环里吸收 3 条 web 平台陷阱，从 ffmpeg 调用里吸收 3 条滤镜陷阱；corpus 从 v0.3.1 的 22 个 skill 增长到 38 个 skill / 27 个 scar 资料来源：[scripts/gen-stats.mjs:1-60]()、[scripts/stats.ts:1-80]()。
## 关键边界与失败模式
飞轮不是自动闭环，三个边界必须由人或信任机制守住：
1. **隐私边界**：`kira_consent` 默认关闭遥测；`kira_share_scar` 永远不替你点提交键 资料来源：[src/report.ts:60-100]()`、`[scripts/scar-intake.mjs:31-60]()`。
2. **搜索质量边界**：v0.4.0 之前 Tier 3 词重叠只要求 1 个有意义的词匹配，导致 "react native" 命中 react-email；现在要求 2+ 个匹配 资料来源：[scripts/stats.ts:80-140]()`。
3. **回归边界**：corpus 增量必须经过 `cut-a-release` 与发布夜的 credential-CI 三道闸，避免把未验证的疤痕反哺回检索索引 资料来源：[scripts/gen-stats.mjs:60-120]()`。
## 小结
失误 → 反馈 → 目录升级这条闭环，把每一次失败都转化为下一次 `kira_lookup` 更准的命中；其可持续性完全依赖于隐私边界、人工提交闸与搜索质量护栏三者同时在线。任何一环松动，飞轮都会从"自我增强"退化为"自我污染"。
---
## 贡献、发布与版本演进（v0.3.1 → v0.8.2）
### 相关页面
相关主题：[隐私设计、遥测与本地状态管理](#page-4), [技能目录（Skills）与伤痕语料（Scars）](#page-5), [飞轮改进循环：失误 → 反馈 → 目录升级](#page-7)
相关源码文件
以下源码文件用于生成本页说明：
- [CONTRIBUTING.md](https://github.com/aibenyclaude-coder/Kira/blob/main/CONTRIBUTING.md)
- [RECIPROCITY.md](https://github.com/aibenyclaude-coder/Kira/blob/main/RECIPROCITY.md)
- [TROUBLESHOOTING.md](https://github.com/aibenyclaude-coder/Kira/blob/main/TROUBLESHOOTING.md)
- [CHANGELOG.md](https://github.com/aibenyclaude-coder/Kira/blob/main/CHANGELOG.md)
- [scripts/registry-publish.md](https://github.com/aibenyclaude-coder/Kira/blob/main/scripts/registry-publish.md)
- [scripts/registry-submissions.md](https://github.com/aibenyclaude-coder/Kira/blob/main/scripts/registry-submissions.md)
# 贡献、发布与版本演进（v0.3.1 → v0.8.2）
本页记录 Kira 仓库自首发版本以来的版本脉络、贡献模型与发布治理流程，重点说明「个人失败经验（scar）」如何被吸收进社区语料，以及发布工程本身如何演化为一条可复用、反向哺育产品的工作流。
## 一、版本演进主线（v0.3.1 → v0.8.2）
Kira 在 7 个公开版本中完成了从「一次性发布」到「闭环飞轮」的角色转换。下表按版本号梳理关键里程碑：
| 版本 | 主题 | 关键变化 |
| --- | --- | --- |
| v0.3.1 | 首发 | 22 个 Skills 上线，定位为「一处 MCP 安装即用」 资料来源：[CHANGELOG.md]()] |
| v0.4.0 | 检索修正 + 飞轮雏形 | Skills 增至 31；Tier 3 词重叠需 ≥2 个有效词匹配；引入 0 结果回退建议 资料来源：[CHANGELOG.md]()] |
| v0.5.0 | 隐私优先遥测 | `kira_report` 从本地文件改为 Cloudflare Worker，确立「飞轮可信任」的管道前提 资料来源：[CHANGELOG.md]()] |
| v0.6.0 | MCP 工具注释 + Registry 准备 | 六个工具加注 `readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint`，对齐 Anthropic 风险词汇表 资料来源：[CHANGELOG.md]()] |
| v0.7.0 | 个人疤痕闭环 | `kira_record_failure`（F1）/ `kira_premortem`（F3）/ `kira_personal_brief`（F2）落地，本地存储于 `~/.kira/personal-scars/` 资料来源：[CHANGELOG.md]()] |
| v0.8.0 | 吸收社区疤痕 | `kira_share_scar`（F4，第 10 个工具）上线，将个人 scar 重新泛化为社区形态并产出预填的 GitHub issue URL；工具本身不发起上传 资料来源：[CHANGELOG.md]()] |
| v0.8.1 | 发布之夜语料 | 在自身发布过程中沉淀 5 条 community scar 与 4 个 process skill（piped-gate、push-race 等） 资料来源：[CHANGELOG.md]()] |
| v0.8.2 | 真实疤痕 + Docker 握手门 | 收 7 条新社区 scar（含 ffmpeg 三个坑、bbutton-site 三个 web 陷阱、parallel-rails race #164）；多阶段 Dockerfile；语料达 **38 skills / 27 scars** 资料来源：[CHANGELOG.md]()] |
整体节奏显示，Kira 的版本号不再仅代表功能增量，而是一段「从用户失败中蒸馏出新工具与新 Skills」的循环节拍。
## 二、贡献模型：从个人疤痕到社区语料
贡献入口遵循「先私有、再显式提交」的二段式流程，避免静默泄露或意外上传。
1. **本地捕获（F1）**：在代理重试或抛错时调用 `kira_record_failure`，写入 `~/.kira/personal-scars/`，默认对外部不可见 资料来源：[CHANGELOG.md]()]。
2. **会话前预览（F2/F3）**：`kira_personal_brief` 在 SessionStart 注入上下文，`kira_premortem` 在目标执行前按历史命中排序给出失败热图 资料来源：[CHANGELOG.md]()]。
3. **社区化（F4）**：当本地 scar 被认为具备共性价值时，`kira_share_scar` 会重新脱敏并泛化为社区形态，输出一个**预填好的 GitHub issue URL** 与 `gh` CLI 回退方案；工具本身**不上传任何字节**，提交动作必须由人类显式触发 资料来源：[CHANGELOG.md]()]。
此模型把「提交贡献」从一份源码改动降级为一次对失败事件的复用决策，降低了贡献摩擦，同时把脱敏责任前置到了工具层。
## 三、发布工程：从手工脚本到握手门
发布流程自身也是社区疤痕的来源。v0.8.1 在发布当夜复盘得到的 4 条 process skill（`cut-a-release`、`delegate-to-subagents`、`npm-trusted-publishing`、`mcp`）已直接进入语料 资料来源：[CHANGELOG.md]()]；v0.8.2 进一步引入 **多阶段 Dockerfile** 作为发布前的握手门（handshake gate），把容器构建作为正式 tag 前的必经校验 资料来源：[CHANGELOG.md]()]。
Registry 方向，仓库准备了两类流程脚本：
- **`scripts/registry-publish.md`**：定义 Kira 包如何被推送到 MCP / Skills Registry，强调版本号、信任发布与签名链路 资料来源：[scripts/registry-publish.md]()]。
- **`scripts/registry-submissions.md`**：定义第三方或下游如何向 Kira 提交新的 Skills / scar 候选，规定最小字段、必填证据链接以及去重校验 资料来源：[scripts/registry-submissions.md]()]。
v0.6.0 中已经铺设的「工具注释」与「MCP Server Card」则为上述 Registry 元数据提供了机器可读的标准化字段，使后续自动化抓取成为可能 资料来源：[CHANGELOG.md]()]。
## 四、互惠飞轮与故障治理
RECIPROCITY.md 把整条流水线概括为一个飞轮：代理使用 Skills → 汇报结果（`kira_report`）→ 数据回流改进索引 → 用户因信任而继续打开遥测 → 更多数据进入索引 资料来源：[RECIPROCITY.md]()]。v0.5.0 的 Cloudflare Worker 后端正是这条飞轮「可信开关」的关键组件 资料来源：[CHANGELOG.md]()]。
TROUBLESHOOTING.md 则承担反向作用：当用户在新版本中撞到回归时，可在已知故障表中找到对应 scar 编号，并参考社区是否已有绕过方案；这也是为什么 v0.8.2 的 7 条新增 scar 都附带 issue 编号（#164、#172、#173 等）以便交叉检索 资料来源：[TROUBLESHOOTING.md]() 资料来源：[CHANGELOG.md]()。
CONTRIBUTING.md 进一步把以上流程串成清单：先阅读 RECIPROCITY.md 理解数据承诺，再按 `scripts/registry-submissions.md` 的字段提交候选，最后通过 `scripts/registry-publish.md` 规定的握手门进入下一版 release 资料来源：[CONTRIBUTING.md]()。
## 小结
从 v0.3.1 的 22 个静态 Skills，到 v0.8.2 的 38 skills / 27 scars 双语料，Kira 的演进呈现一条清晰轨迹：**工具集随失败事件生长，发布工程自身又成为失败事件的来源**。贡献者面对的不再是「一次性 PR」，而是一段从 `kira_record_failure` 到 `kira_share_scar`、再到下一版 CHANGELOG 的可追溯闭环。
---
---
## Doramagic 踩坑日志
项目：aibenyclaude-coder/Kira
摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。
## 1. 配置坑 · 可能修改宿主 AI 配置
- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/aibenyclaude-coder/Kira | host_targets=mcp_host, claude_code, claude, cursor
## 2. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/aibenyclaude-coder/Kira | README/documentation is current enough for a first validation pass.
## 3. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/aibenyclaude-coder/Kira | last_activity_observed missing
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/aibenyclaude-coder/Kira | no_demo; severity=medium
## 5. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/aibenyclaude-coder/Kira | no_demo; severity=medium
## 6. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/aibenyclaude-coder/Kira | issue_or_pr_quality=unknown
## 7. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/aibenyclaude-coder/Kira | release_recency=unknown