koda

Koda

为编码 Agent 工作流提供验证和记忆。 安装一次，验证重要的更改，记住哪些问题总是反复出现。

Open VSX 上的下载量已超过 1,000 次 — Koda 已经在全球各地的编辑器中监控提交。

---

npm	npm install -g koda-verify (npmjs.com)
IDE	Open VSX — 适用于 VS Code、Cursor、Windsurf、VSCodium
MCP	Registry
主页	aabxtract.github.io/koda

Koda 为何存在

编码 Agent 能在几分钟内编写功能，但谁来验证每次提交？完整测试套件运行太慢，无法在每次提交时执行，因此大多数验证都拖到很晚才进行（或者根本不做）。Koda 填补了这一空白：每次提交时，它只验证发生更改的部分，用时从几秒到几分钟，并记住哪些问题总是反复出现，让你的 Agent 不再重复引入旧错误。

Koda 从不编写代码。它负责协调验证、记忆模式并生成报告，同时提供给开发者和 Agent。

三种使用方式

方式	职责	启用方式
核心 + CLI	验证、报告、记忆、Git 钩子、CI 生成	koda init、koda run
MCP 服务	Agent 调用 koda_verify / koda_report / koda_memory / koda_setup_cicd	配置 MCP 客户端
IDE 扩展	常驻状态栏、报告查看器、一键启用、Git 监控	用户点击 Enable

工作原理 — 流水线

git commit
   │
   ▼
pre-commit ── secret guard (blocks committed API keys / private keys)
   │
   ▼
post-commit ── koda run (background, never blocks you)
   │
   ▼
1. Read diff ──────────── classify files: api / page / component / lib / config / test
2. Impact analysis ────── agent-supplied (MCP) → Groq fallback → deterministic heuristics
3. Kane browser flows ─── headless, scoped to changed UI only (page/component changes)
4. Endpoint checks ────── GET / HEAD / OPTIONS only; regressions flagged (200 → 500)
5. Integration tests ──── Jest / Vitest / Mocha / node:test, matched to changed files
6. Report ─────────────── JSON (agent-readable) + Markdown (human-readable)
7. Memory ─────────────── recurring patterns, resolution history, time-to-fix

大多数提交都不会启动浏览器：仅涉及 API、配置或测试的更改会通过端点检查和测试在几秒内完成验证。只有 UI 文件发生更改时才会运行浏览器流程。

---

快速开始

npm install -g koda-verify
cd your-project
koda init        # creates .koda/, installs git hooks, detects your app's port
koda doctor      # verifies: git, config, Kane CLI, target URL, directories

之后只需继续提交即可——验证会在每次提交时于后台运行。

一次性浏览器设置（可选，每位用户设置一次）

浏览器流程由 Kane CLI 提供支持。IDE 扩展会为你完成配置：点击 Enable，Koda 就会提示你安装 Kane 并关联账户。你也可以手动操作：

npm install -g @testmuai/kane-cli
kane-cli login --oauth        # opens your browser — use (or create) YOUR OWN Kane account

关于 Kane 账户——属于你，而非我们

Koda 不附带任何凭据。每位 Koda 用户都要登录自己的 Kane 账户：

• 扩展的 OAuth 流程会在你的浏览器中打开 Kane 登录页面；新用户可在那里注册
• 你的会话保存在本机的 ~/.testmuai/ 中——绝不会同步，也不会经过代理
• 浏览器流程使用的额度来自你的 Kane 账户，而非开发者的账户
• 在 CI 中，每个代码仓库都会自行配置 KANE_USERNAME / KODA_ACCESS_KEY 等类型的密钥

没有 Kane？没问题。 Koda 会在降级模式下运行：端点检查、集成测试、记忆和报告仍然可用；浏览器流程会如实标记为 SKIPPED，绝不会伪装成已运行。

---

目标 URL — localhost、局域网或托管环境

Koda 会验证应用指向的任意目标。默认值会在运行 koda init 时自动检测（探测常见开发端口：3000、5173、8080、8000、4200、5000……）。可通过以下三种方式覆盖：

koda target https://myapp.vercel.app      # permanent — hosted URL, https auto-detected
koda target 192.168.1.5:8080              # LAN IP, http auto-detected
koda run --target https://preview-123.example.com   # one-off run
KODA_TARGET=https://staging.example.com   # per-session / CI via env

优先级：--target 标志 → KODA_TARGET 环境变量 → .koda/config.json → 自动检测的默认值。

CLI 参考

命令	功能
koda init [--force]	创建 .koda/，安装非破坏性 Git 钩子，并检测目标
koda run [--project <path>] [--commit <sha>] [--target <url>] [--max-flows <n>]	立即验证某个提交
koda report	显示最新报告
koda memory	导出项目记忆（模式、历史记录、修复）
koda target <url>	验证、保存并进行新目标 URL 的健康检查
koda cicd [--force]	生成经过验证的 GitHub Actions 工作流（拒绝覆盖）
koda doctor [--kane]	检查环境；--kane 会通过实测探查 Kane 架构
koda mcp	启动 MCP 服务（stdio）

Agent 集成（MCP）

claude mcp add koda -- npx koda-verify mcp

适用于任何 MCP 客户端：Claude Code、Cursor、Codex、Gemini CLI、Windsurf、Zed。在开发检出目录中：claude mcp add koda node /absolute/path/to/koda/mcp/server.js。

MCP 工具

工具	用途
koda_verify	运行针对性验证。Agent 提供自己的影响分析（flows、endpoints、target、commit、max_flows）——它已经读取过你的代码，因此无需 LLM 开销，也无需猜测。Groq 仅作为非 MCP 运行的后备方案
koda_report	最新的完整 JSON 报告——判定结果、覆盖率、证据路径
koda_memory	项目记忆——反复出现的故障、修复置信度、修复耗时
koda_setup_cicd	生成经过验证的 GitHub Actions 工作流

Agent 工作循环

agent edits code → commits → hook fires koda run → report written
→ agent calls koda_verify (its own flows) / koda_report via MCP
→ reads the verdict → fixes what failed → commits again
→ memory marks the failure RESOLVED (with time-to-fix recorded)

当 Agent 提供了 flows 时，报告会记录 analysis_source: 'agent'，这可验证该工作循环由 Agent 驱动。

---

报告

每次运行都会在 .koda/reports/ 中写入一对带时间戳的文件：

.koda/reports/2026-08-30T14-35-28-909Z-9416b29.json   ← agent-readable
.koda/reports/2026-08-30T14-35-28-909Z-9416b29.md     ← human-readable

JSON 包含：提交元数据、analysis_source（agent / llm-fallback / fallback）、风险等级、每项检查的结果及证据文件路径、记忆上下文（类似故障、模式、修复置信度），以及包含优先级和建议关注重点的 action_required。Markdown 会通过不同样式呈现 PASS / FAIL / SKIPPED，并显示覆盖状态。

Kane 原始会话事件会按流程保存在 .koda/evidence/ 下。

记忆——记住反复出现的问题

• 每项失败的检查都会获得一个稳定键；重复 2 次或以上的失败会成为模式
• 修复完成且检查通过后，该失败会标记为已解决，并记录 time_to_fix_ms
• 覆盖缺口发现（“没有测试覆盖 app/page.js”）会在有通过的测试覆盖这些文件后自动解决
• 被跳过的检查（应用离线）绝不会污染记忆
• 写入操作是原子的；损坏的记忆文件会被隔离，而非删除

安全保证

• 非破坏性钩子——追加内容前会备份已有的 pre-commit/post-commit/pre-push 钩子；尊重 Husky；通过标记实现幂等
• HTTP 默认只读——仅允许 GET / HEAD / OPTIONS；修改方法需要显式启用（allow_mutating_methods: true），并由 Agent 声明端点
• 如实报告结果——如果应用已停止，检查会标记为 SKIPPED，绝不会报告为失败；被跳过的检查不会进入记忆
• 不随包分发机密——软件包不包含任何凭据；pre-commit 防护会阻止意外提交密钥

CI/CD

koda cicd

根据经过验证的模板生成 .github/workflows/koda.yml：设置 Node、执行 npm ci、在存在构建脚本时构建、安装 Kane CLI 并通过 GitHub secrets（KANE_USERNAME、KANE_ACCESS_KEY）进行身份验证、启动应用、等待目标就绪，以及运行 koda run --commit ${{ github.sha }}。优先使用模板——不使用 LLM 生成 YAML。未经 --force 不会覆盖现有文件。

---

配置参考（.koda/config.json）

{
  "kane": {
    "target": "http://localhost:3000",
    "headless": true,
    "max_steps": 30,
    "timeout_ms": 300000
  },
  "tests": {
    "browser_flows": true,
    "endpoint_tests": true,
    "integration_tests": true,
    "allow_mutating_methods": false,
    "expected_statuses": { "GET /api/health": [200] }
  },
  "notify": { "telegram": false, "discord": false }
}

环境变量

可选——Koda 不设置这些变量也能运行。先从项目 .env 加载，找不到时则从 ~/.koda/.env 加载（配置一次，处处使用）：

GROQ_API_KEY=        # Groq fallback impact analysis (agent runs skip this entirely)
KODA_TARGET=         # override target URL (flag > env > config)
KODA_TEST_TOKEN=     # bearer token for authenticated endpoint checks
KODA_PROJECT=        # default project path for CLI/MCP
TELEGRAM_BOT_TOKEN=  # notifications
TELEGRAM_CHAT_ID=
DISCORD_WEBHOOK_URL=

开发

npm install
npm run check    # syntax-check all sources
npm test         # node:test suite
npm link         # local koda binary for development

完整的实现规范请参阅 koda-v3-build-guide.md。

许可证

MIT