# Koma（狛犬）

### Miko：为 Claude Code 和 Codex 检查必需的 Skill 读取

> **你的 coding agent 说它读了 Skill，但它真的读了吗？**
>
> Miko 在 Hook 层拦截编辑动作，如果 agent 没有先读取你指定的 Skill，就拒绝这次编辑，并给出一次可见的重试路径。本地运行，零依赖，验证器不调用 LLM，免费开源。

#### 谁需要这个？
- 你在用 **Claude Code** / **Codex CLI**，并且写了 Skill 但不确定 agent 是否遵守
- 你希望编辑前有**硬性检查**，而不是靠 prompt 提醒
- 你想让 Skill 的读取行为变成**可观测、可拒绝、可恢复的**

#### 与其他工具的区别
与静态 Skill 校验或安全扫描工具不同，Miko 工作在**运行时 Hook 层**，拦截的是 agent 实际的编辑工具调用，而不是对 Skill 文件进行静态扫描。

#### 适用范围

**Miko 是一个极其轻量的工具。** 它只检查少量可观察事件，只拦住不满足要求的动作。它不是安全边界，不是合规系统，也不能证明模型理解了任何东西。

**请在每次对话开始时，明确要求 agent 主动加载它需要的 Skills。** Miko 是 agent 忘记时的兜底，不能替代你把要求讲清楚。指令越清楚，被暂停的次数越少。

```bash
npm install -D koma-miko
npx koma-miko init --host claude
```

在生成的 `miko.json` 中填写项目已有的 Skill 和受保护路径，再启动新的 Claude
Code 会话。**使用 Codex？** 请按 [Codex 配置与首次 Hook 审阅](./packages/koma-miko/README.zh-CN.md#codex-setup)
操作。Codex CLI 属于 Technical Preview；Desktop 必须先通过 CLI 激活。

<p align="center">
  <img src="logo/logobanner.png" alt="Koma" width="600" />
</p>

<p align="center">
  <img alt="License" src="https://img.shields.io/badge/license-MIT-green?style=flat-square" />
  <img alt="CI" src="https://github.com/swnotmetal/Project-Koma/actions/workflows/ci.yml/badge.svg" />
  <a href="https://www.npmjs.com/package/koma-miko"><img alt="koma-miko" src="https://img.shields.io/npm/v/koma-miko/alpha?label=koma-miko%20alpha&color=C25E38&style=flat-square" /></a>
  <a href="https://www.npmjs.com/package/koma-gate"><img alt="koma-gate" src="https://img.shields.io/npm/v/koma-gate?label=koma-gate&color=3178c6&style=flat-square" /></a>
  <a href="https://www.npmjs.com/package/koma-scout"><img alt="koma-scout" src="https://img.shields.io/npm/v/koma-scout?label=koma-scout&color=3178c6&style=flat-square" /></a>
  <a href="https://www.npmjs.com/package/koma-core"><img alt="koma-core" src="https://img.shields.io/npm/v/koma-core?label=koma-core&color=3178c6&style=flat-square" /></a>
  <br />
  <a href="https://koma-demo.swbuilds.workers.dev"><img alt="Miko live demo" src="https://img.shields.io/badge/Miko_demo-10--sec_replay-C25E38?style=flat-square" /></a>
  <img alt="Gate benchmark" src="https://img.shields.io/badge/Gate实测-98.8%25召回_0%25误拦-6e3abe?style=flat-square" />
  <img alt="koma-gate downloads" src="https://img.shields.io/npm/dt/koma-gate?label=gate%20下载量&color=blue&style=flat-square" />
  <a href="https://glama.ai/mcp/servers/swnotmetal/Project-Koma"><img alt="MCP server" src="https://glama.ai/mcp/servers/swnotmetal/Project-Koma/badges/score.svg" /></a>
</p>

<p align="center">
  <a href="./README.md">English</a>
</p>

<p align="center">
  <strong>▶ <a href="https://koma-demo.swbuilds.workers.dev">体验 Miko 终端引导回放</a></strong> —— 同页还有 Gate、Scout、Core，无需注册。
</p>

---

### 面向 Claude Code 和 Codex 的 Miko Alpha

<p align="center">
  <img src="packages/koma-miko/assets/miko-lockup.png" alt="Koma Miko" width="420" />
</p>

Coding agent 可以声称自己加载了必需 Skill 或运行了测试，但 Miko 不把自述当作
证据。在宿主提供的本地 Hook 上，它会把观察到的 Skill 加载、参考文档读取、
工具动作和完成检查，与项目维护的 `miko.json` 比对。

如果 agent 尚未满足 Spec 就尝试修改文件，Miko 可以返回拒绝和简短的恢复提示。
它无法读取隐藏模型上下文、证明模型真正理解了 Skill，也无法验证宿主没有暴露的
事件。
Claude CLI 的 guided 模式遇到真正的范围例外时，会显示一次明确的 Miko 选择：
只允许完全相同的下一次重试，或保留当前边界。

```bash
npx --yes koma-miko demo             # 确定性回放；无需 API key
npx --yes koma-miko probe --host claude  # 隔离式 adapter 检查；不调用模型
npx koma-miko init --host claude     # 本地安装后自动配置
```

> **Codex CLI 属于 Technical Preview；Codex Desktop 必须先通过 CLI
> 激活。** CLI 必须先完成一次 `/hooks` 审阅，项目 Hook 才会运行。Miko 在
> Codex 上主推 `enforce`，因为当前 Hook API 无法打开原生 `REVIEW` 选择；review
> 会降级为可恢复的 pause/deny。仅用 Desktop 的 onboarding 不是 alpha 支持路径。
> 离线 `probe` 只验证 adapter 逻辑，不代表真实 Hook 已激活。

[Miko README →](./packages/koma-miko/README.zh-CN.md) ·
[当前宿主支持 →](./packages/koma-miko/README.zh-CN.md#host-support) ·
[10 秒网页回放 →](https://koma-demo.swbuilds.workers.dev)

[Miko 回放 GIF](./docs/assets/miko-terminal-demo.gif) ·
[静态截图](./docs/assets/miko-terminal-demo-poster.png) — 网页模拟，并非真实宿主录屏。

Claude Code 是主要 alpha 使用路径；Codex CLI 已有窄范围恢复验证，但仍有上述
激活限制。Gemini 移出主动开发范围。VS Code Copilot 现已在 Local harness 上有
一次真实拦截验证，但该宿主的 chat UI 不渲染 Miko 状态文本，Miko 因此请 agent
代为转述。
已有适配器和历史测试保留在 [适配器文档](./packages/koma-miko/README.zh-CN.md#other-adapters)。

**为什么不直接写一个 Hook？** 单个固定检查用原生 Hook 就够了。Miko 把项目
Spec、读取记录、压缩后的重载要求、恢复提示和完成证据放在一起维护。两者都
不能证明模型理解了指令。参见 [什么时候适合使用 Miko](./packages/koma-miko/README.zh-CN.md#when-to-use-miko)。

**零依赖设计**：纯 TypeScript，0 个 npm 运行时依赖。你得到的是一个轻量级 Hook 层，可以在不引入庞大框架的前提下拦住未经验证的编辑。

**核心技术文档与评估摘要**：
- **[Recovery Playbook（恢复剧本）](./docs/design/miko-recovery-playbook.md)**：当 agent 被拒绝后，如何提供结构化、可观测的重试路径，避免 agent 进入死锁循环。
- **[Claude Haiku 实测评估](./docs/evals/miko-claude-haiku-alpha.md)**：在 Claude Haiku 等模型上的实测评估结果，覆盖多个真实 Skill 场景与恢复拦截。

**反馈与交流**：
有问题或想提出新的需求方向？欢迎提交 [Issue](https://github.com/swnotmetal/Project-Koma/issues) 或开启 [Discussion](https://github.com/swnotmetal/Project-Koma/discussions)，我会认真查看并根据实际反馈持续改进。

---

### 四种边界

| 边界 | 失败方式 | Koma 检查什么 | Package |
|---|---|---|---|
| Coding agent | 必需 Skill 或完成检查被跳过 | 宿主观察到的准备、动作范围与证据 | `koma-miko@alpha` |
| 用户 → LLM | 提示注入 / 越狱 | 应用模型之前的语义范围 | `koma-gate` |
| 请求外围 | 音频滥用 / 洪水攻击 | 校验、限流与地理规则 | `koma-scout` |
| 检索 | 数据遍历 / 爬取 | 索引与内容分离，token 控制检索 | `koma-core` |

---

### 实测数据

#### Miko alpha 评估

Miko 本身是确定性验证器，因此这里衡量的是验证开销和端到端 Hook 行为，
而不是给模型“智力”打一个笼统分数。

| 信号 | 实测结果 |
|---|---|
| 离线宿主一致性 | Claude、Codex、Gemini 与 VS Code Copilot 均复现 `DENY → 观察到 Skill → ALLOW`；账本夹具确认不保存 prompt、代码或工具响应 |
| 本地 verifier 规模测试 | 1,000 份 Agent Spec：每次动作 **p95 1.34 ms**；10,001 条索引证据：**p95 0.0041 ms**；恢复 1,000 条证据：**p95 1.52 ms** |
| Claude Code live + 手测 | 一次 100-Skill / 约 20k context 测试通过；自然中文需求驱动三文件改造通过 3 份 Agent Spec 与 28 条 observed events；另用 Haiku 4.5 实测可见的 `Allow once` 与 `Keep current scope` 两条策略例外路径 |
| Codex CLI Technical Preview | 固定 live recovery 完成 `DENY → Skill/reference → edit → COMPLETE`；CLI 0.152.0 人工测试可见 Miko active、recovered 与 COMPLETE。Desktop 在 CLI 激活后也能执行，但 onboarding 与完成状态可见性仍不适合作为主路径 |
| DeepSeek Harness smoke | 窄范围 packed-artifact 恢复 **3/3** 通过；模型阶段平均 19.425 秒 |

规模数据来自 2026-08-27 的 Node 24.19 / Windows 参考运行；可用
`npm run eval:scale -w koma-miko` 在自己的机器复现。Context token 不会进入
verifier。付费样本刻意保持很小，**不能证明普遍的模型、长上下文或编辑器可靠性**。
参见 [scale 记录](./docs/evals/miko-scale-alpha.md)、
[Claude 记录](./docs/evals/miko-claude-haiku-alpha.md)、
[宿主适配器记录](./docs/evals/miko-host-adapters-alpha.md) 与
[DSH 记录](./docs/evals/miko-dsh-alpha.md)。

#### Koma Gate 真实模型 benchmark

我用 **1,769 条真实提示注入攻击** 在 fail-closed 模式下测试了 Koma Gate，使用真实商用模型——非 mock 适配器。

| 供应商 | 召回率 | 精确率 | 误拦 |
|----------|:------:|:------:|:---:|
| DeepSeek (deepseek-chat) | **98.8%** | **100%** | **0** |
| Google (gemini-2.5-flash) | 96.2% | **100%** | **0** |

**中文攻击集**：8 个类别，100% 召回 · 100% 精确 · 0% 误拦。

> **你能绕过吗？** [提交 issue](https://github.com/swnotmetal/Project-Koma/issues) 告诉我 Koma 漏了什么。→ [完整方法学](./BENCHMARKS.md)

---

### 应用侧快速开始：Gate

```ts
import { createGeneralKnowledgeGuard } from 'koma-gate';

const guard = createGeneralKnowledgeGuard({
  llm: { apiKey: process.env.GEMINI_API_KEY },
});

app.post('/api/chat', guard.middleware(), async (req, res) => {
  // 只有范围内的请求才会到达模型
  res.json({ reply: await chat(req.body.message) });
});
```

```bash
git clone https://github.com/swnotmetal/Project-Koma
cd Project-Koma && node demo/server.js
curl http://localhost:8080/self-test
```

---

### 应用侧 Packages

**`koma-gate`** — 提示注入防火墙。基于 LLM 的范围分类器，拦截越狱、越界请求和指令覆盖。支持 OpenAI、Anthropic、Google、DeepSeek 和本地 Ollama。[README →](./packages/koma-gate/README.md)

[在网页 demo 中试用 Gate →](https://koma-demo.swbuilds.workers.dev)

<img src="show-koma.gif" alt="Koma Gate 实时拦截提示注入" width="100%" />

**`koma-scout`** — 外围防护。限流、音频上传校验、地理白名单。在昂贵的 AI 调用之前做便宜检查。[README →](./packages/koma-scout/README.md)

<img src="logo/scout-diagram.svg" alt="Koma Scout 外围检查" width="480" />

**`koma-core`** — 受保护的 RAG 存储。公开搜索索引，私有内容，不透明的 HKDF 派生 token。*发现不等于授权。* [README →](./packages/koma-core/README.md)

<img src="logo/core-diagram.svg" alt="Koma Core 分离存储" width="480" />

每个包独立使用。典型应用先由 Scout 做便宜的请求检查，再调用 Gate 分类，
需要受保护的检索时使用 Core。参见 [架构图](./ARCHITECTURE_MAP.md)。

---

### 用编程助手配置 Miko？

告诉它：

> “先读 Miko README，再按我使用的宿主，为项目已有的 Skill 和受保护路径配置 koma-miko。说明哪些激活步骤需要我完成。”

对于 coding-agent 项目，安装 Miko 后运行
`npx koma-miko init --host claude`，或按 [Codex 配置](./packages/koma-miko/README.zh-CN.md#codex-setup)
操作，再在生成的 `miko.json` 中填写项目真正关心的 Skill、路径与完成证据。
Miko 不会安装 Skill 本身。

[llms.txt](./llms.txt) 提供文档入口。Miko 使用宿主 Hooks，不需要 MCP server。
仓库已有的 MCP servers 属于 Gate 和 Core。

---

### 信任与安全

- **最小依赖面。** Miko、Gate 与 Core 没有第三方运行时依赖；Scout 仅将 Express 声明为 peer dependency。
- **不执行模型输出。** Miko 观察宿主事件；Gate、Scout、Core 负责分类、限流或存储，均不执行生成代码。
- **各包的失败行为不同。** Gate 默认 fail-open，可设置 `failOpen: false`；
  Miko 按每份 Agent Spec 的模式执行，enforce 模式缺失证据时拒绝适用动作。
- **每次推送 CodeQL。** 覆盖 OWASP LLM01。
- **MIT 协议。**

→ [安全策略](./SECURITY.md) · [已知限制](./SECURITY-HARDENING.md) · [贡献指南](./CONTRIBUTING.md)

---

Koma 取自神社前的石狮"狛犬"（こまいぬ）。三层已部署防御各自独立，另有 Miko alpha agent 契约边界。模式提炼自生产环境，而非纸上谈兵。

[English](./README.md) · [License](./LICENSE)