核心问题与设计动机

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 暴露能力，以下表格概述其分层职责：

资料来源：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

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

// 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

本地存储层

本地存储承担两件事：技能/伤疤语料库的只读索引，以及个人伤疤的写入路径。

• 技能索引：由 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 在加载索引前执行授权检查；src/logger.ts 提供结构化日志，本地存储失败时统一以 src/errors.ts 中的错误类型抛出，避免静默丢失伤疤记录。

MCP 服务器层

src/index.ts 引导 src/server.ts 注册 MCP 工具与传输层（stdio / 可选 HTTP）。v0.6.0 起全部工具携带 readOnlyHint、destructiveHint、idempotentHint、openWorldHint 注解，作为风险词汇交给宿主代理。

服务器层将所有网络调用收敛到 kira_report 一处，其它工具不直接出网，便于宿主以注解决定是否放行。资料来源：src/server.ts:120-260

Cloudflare Worker 层（Phase A）

v0.5.0 将遥测后端从本地日志文件替换为 worker/src/index.ts 部署的 Cloudflare Worker，定位为「飞轮的数据接收端」。设计原则：

• 隐私优先：客户端在 src/telemetry.ts 内做最小化与脱敏，Worker 仅接收必要的命中/反馈字段。
• 可控开关：遥测默认受 kira_consent 门控，关闭时 kira_report 直接 short-circuit，不出网。
• 幂等接收：Worker 端按上报去重，使 kira_report 满足 idempotentHint。

Worker 与本地存储共享同一份语料库契约（技能 slug、伤疤类别、结果枚举），保证回流数据可被用于索引权重再训练。资料来源：worker/src/index.ts:1-80

数据流与故障隔离

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 分类。这一边界在 v0.8.0 kira_share_scar 中再次强化——该工具只生成 GitHub Issue URL 与 gh 回退命令，不上传任何内容，把「提交」动作留给显式的人工操作。资料来源：src/server.ts:260-340

这 10 个工具围绕"让 agent 找到正确指令、规避已知错误、并把执行结果回流以改进索引"这条飞轮（flywheel）展开：前 6 个是 v0.6.0 之前的检索/上报/状态工具；后 4 个（F1–F4）属于 v0.7.0–v0.8.0 推出的"个人 scar 闭环"系列。

核心检索与上报工具（6 个）

这一组构成 Kira 飞轮的主要数据流：搜索→路由→取详情→上报。

资料来源：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

工作流概览

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，由人审核后再点击提交。

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

二、敏感信息脱敏（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

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/<hash>.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 集成成本最低的同时保留了用户对飞轮管道的可控性。

概述与设计动机

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 的核心字段差异：

资料来源：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。

flowchart LR
  A[routes/*.json<br/>Skills / Scars 原始条目] --> B[scripts/gen-corpus.mjs<br/>聚合 / 归一化]
  B --> C[docs/corpus.json<br/>统一语料]
  C --> D{scripts/validate-entry.mjs<br/>条目校验}
  D -- 通过 --> E[MCP Server<br/>kira_lookup / kira_route / kira_get]
  D -- 失败 --> F[CI 阻断<br/>禁止合并]

检索集成与扩展路径

在 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/<your-route>.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 作为 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_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 协作的最小数据流

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。

概述与定位

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 划分了三个层级：

资料来源：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。

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）

Kira 在 7 个公开版本中完成了从「一次性发布」到「闭环飞轮」的角色转换。下表按版本号梳理关键里程碑：

整体节奏显示，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 的可追溯闭环。

Pitfall Log / 踩坑日志

项目：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