KedaCode (kc)

把 GitHub Issue 变成本地 AI Agent 队列。给 Issue 打上 agent/ready，kc 就会创建隔离 worktree、驱动 Claude / Codex / Kimi 改代码、跑验证、做 code review、推分支开 Draft PR，并可按配置检查 PR 上的 CI 与评论变化；需要持续跟进时，可以显式启动监督 daemon。你不想用命令行时，kc console 一条命令打开内置的管理面板。

装什么、敲什么：uv tool install kedacode 之后主命令是 kc，也可以直接敲包名 kedacode（两者完全等价，见下方安装一节）；不想安装时可用 uvx --from kedacode kc <命令> 临时运行。旧命令 iar 长期作为弃用别名保留，新旧对照与迁移步骤见 docs/guides/migrating-from-iar.md。

仓库同时是一套可复用的 Python 工程骨架——Clean Architecture 四层依赖由 pre-commit 强制校验，配套 worktree 脚本、PRD 驱动流程与 just 工具链，可以整体拿去起新项目。

注：本仓库与 CNCF 毕业项目 KEDA（keda.sh，Kubernetes 事件驱动自动扩缩）无关。

_{Issue 认领后的执行链全貌——分诊、PRD 生成、发布档位与合并收尾；细节见 docs/guides/agent-runner.md。}

Agent 生命周期

下面按职责分成三个彼此独立的功能区，它们不组成一条统一流程。每个功能区都有自己的入口和触发条件；同一功能区内的阶段也只在各自条件满足时运行。

Issue 执行与交付

生命周期	触发时机	做什么
实现（implementation）	kc run / kc daemon 认领 agent/ready Issue	根据 Issue 和 PRD 需求，在隔离 worktree 中完成代码改动。
修复（fix）	实现后的验证失败	针对失败结果修正代码。
收尾（closeout）	交付门禁失败	处理阻碍交付的问题。
校验（verifier）	发布前的验证阶段	独立复核实现结果与验证证据，作为质量门禁。
审核（review）	创建 Draft PR 之前	做代码审查，检查 findings 并推动问题收敛。
监督（supervisor）	发布链创建 Draft PR 后，或显式运行 kc supervise	与创建 Draft PR 前的代码审核（review）分开：它检查 PR 变更、CI 和讨论，决定等待、修复 / rebase、请求人工输入或转交人工审查，本身不合并 PR。发布链内的调用受 post_pr_supervisor.enabled 和发布档位控制（本仓库默认配置启用，--direct-pr 会跳过）；常驻进程不会由 kc run 自动常驻启动，可运行 kc supervise-daemon；通过 kc registry start 启动托管进程时默认会一并启动，想跳过可用 --no-supervise-daemon。

讨论与内容生成

生命周期	触发时机	做什么
辩论（deliberate）	agent/deliberate Issue 的讨论阶段	围绕复杂 Issue 做异步多角色讨论，整理澄清问题和结论，供后续 PRD 落地。
内容生成（content_generation）	创建 Issue、从讨论生成 PRD，或创建 Draft PR 时	辅助生成 Issue 内容、PRD、Draft PR 标题和正文。

独立决策入口

生命周期	触发时机	做什么
决策（planner）	kc ask	把自然语言请求整理成受限操作计划，默认先展示计划，确认后再执行；不依赖 Issue 流水线。

各阶段的配置、消费点与覆盖规则见生命周期 Agent 矩阵。

一键安装

无需克隆仓库，一条命令装上 kc CLI 并打开管理面板。三条等价入口任选其一；装完执行 kc --version 验证，在任意目录 kc console 打开管理面板。详见 docs/getting-started/installation.md。

macOS（Homebrew）：

brew install ZataZhang/tap/kedacode

任何平台（uv / pipx，含 Windows PowerShell）：

uv tool install kedacode      # 推荐：uv 隔离环境，Windows 原生可用
# 或
pipx install kedacode

install.sh（自动选择 uv / pipx / pip --user，零 sudo，失败有明确提示）：

curl -fsSL https://raw.githubusercontent.com/ZataZhang/keda/main/install.sh | bash

默认 --source auto 从 GitHub release tarball 安装；加 --source pypi 改从 PyPI 安装：

curl -fsSL https://raw.githubusercontent.com/ZataZhang/keda/main/install.sh | bash -s -- --source pypi

安装参数速查：

选项	说明
--version <tag>	安装指定 release tag / PyPI 版本（默认: latest）
--method uv|pipx|pip	强制使用指定安装器（默认自动选择）
--source auto|pypi|tarball	安装源（默认: auto = GitHub tarball）
--check	dry-run，只打印计划
--uninstall	卸载 kedacode 工具环境与 kc binary

环境变量等价：KEDA_VERSION、KEDA_INSTALL_METHOD、KEDA_SOURCE、KEDA_PYPI=1（legacy，等价于 --source pypi）。

安装 Agent Skills

prd 与 code-reviewer 由远程 zata-codes-template 仓库维护，不随 Keda wheel 分发。kc init 会仅下载这两个 Skill 并安装到用户级目录，绝不会写入项目目录；因此同一台 机器上的所有项目共用同一份规范。安装目标首位是 keda 自有目录 ~/.kedacode/skills——runner 解析 PRD 时优先取这份，所以用户删掉 agent 目录里的副本也不会让 kc 失去解析能力；其后 是 Codex、Claude、Kimi Code 等已检测到的 agent 配置目录。可用 KEDACODE_SKILLS_DIR 覆盖安装 根目录（CI / 测试把安装落到临时目录时用），用 KEDACODE_PRD_SKILL_PATH 直接指定某一份 SKILL.md。

前置要求

• Python >= 3.11
• uv — Python 包管理器（安装器会自动 bootstrap）
• just — 命令运行器
• Node.js（如需运行前端）

快速开始

# 1. 克隆仓库并进入目录
git clone <repository-url>
cd keda

# 2. 初始化开发环境（安装依赖 + pre-commit hooks）
uv sync --all-extras
uv run pre-commit install

# 3. 启动服务（后端 + 前端，分别开终端）
uv run python -m backend.main          # 后端（默认 8000 端口）

# 前端使用 pnpm workspace（frontend-public + frontend-admin）
pnpm install                            # 安装两个前端的依赖
pnpm --filter frontend-public dev       # Agent Runner 管理终端（Next.js，默认 3000 端口）
pnpm --filter frontend-admin dev        # 管理平台（Vite，默认 5173 端口）

项目提供了 justfile 作为便捷封装（如 just dev、just run、just test），如果你使用 just，可以直接调用。下文只列出底层命令。

kc CLI 使用说明

kc（KedaCode，原 issue-agent-runner）是本项目的核心工具，用于将 GitHub Issues 转为本地 AI Agent 任务队列，自动创建 Git Worktree 并驱动 Agent 执行。

Recovery Flow

当 Agent 提交遇到 pre-commit、测试或 verification 失败时，kc 不会直接失败退出，而是按下面两层 escalator 逐步修复，最大限度减少人工干预和 API 浪费：

1. Fix Agent：对简单局部问题（如 lint 逻辑错误、单测失败、遗漏 import），启动一个只聚焦当前 verification 失败的轻量 agent，使用更短的 fix_timeout_seconds。
2. Recovery Agent：对复杂或全局失败（evidence、PRD checklist、commit request 等），启动完整 recovery agent，使用独立的 recovery_timeout_seconds。

为了降低重复犯错和重复摸索的概率，runner 会在各阶段 prompt 中透传 verification 上下文：

• 首次实现 prompt 会列出 runner 将要执行的完整 verification_commands。
• Fix Agent / Recovery Agent 的 prompt 会附带具体失败的命令、exit code、stdout/stderr。
• 跨 claim 续作 prompt 会继承上一次失败的 verification 输出。

如果某轮修复仍未通过，runner 会先创建一个 [Agent][WIP] Issue #N checkpoint commit 保存进度，使其能跨 claim 续作；这些 checkpoint 在最终合并时由 GitHub/GitLab squash 收敛为干净历史，不再由 runner 内部压平。

安装 kc 全局命令

本项目通过 pyproject.toml 的 [project.scripts] 注册了两个等价入口：主命令 kc，以及与分发名对齐的别名 kedacode（装完想不起来敲什么时，敲包名也能用）。开发本仓库时推荐以可编辑模式安装为全局命令，这样源码改动可直接反映到 kc，无需每次重新构建安装：

# 在仓库根目录安装（推荐）
uv tool install --reinstall --editable .

# 或从任意目录指定项目路径
uv tool install --reinstall --editable /path/to/keda

uv tool install 的参数应是项目目录或包名，不要传入 README.md 等普通文件路径。当 pyproject.toml 的依赖或 CLI 入口变更后，需要重新执行可编辑安装命令：

uv tool install --reinstall --editable .

安装后可直接使用 kc <command>；未安装时可用 uv run kc <command> 代替。CLI 基于 Typer/Rich，kc --help 会展示分组命令、参数和别名。

安装 shell 自动补全

安装补全后，zsh 中输入 kc is<Tab> 可补全到 issue：

# zsh（推荐）
kc completion install --shell zsh
source ~/.zshrc

# 仅查看补全脚本，不写入 shell 配置
kc completion show --shell zsh

也支持 --shell bash 和 --shell fish。

初始化与配置

前置步骤：所有 kc 子命令（除 kc init 本身外）都要求目标仓库已经执行过 kc init。未初始化时命令会立即失败并提示运行 kc init。

# 在目标仓库初始化本地配置
kc init
# 或未安装全局命令时
uv run kc init

# 把 preview workflow 模板（GitHub Actions + deploy/vps-traefik + scripts/）复制到当前仓库
kc workflow install preview

# 同步当前仓库的 GitHub Labels
kc labels sync

# 同步指定仓库 Labels
kc labels sync --repo-id keda

从 PRD 创建 Issue

# 从 PRD 创建 GitHub Issue，标记为 ready（默认发布 PRD）
kc issue create tasks/pending/example.md --repo-id keda --agent codex --ready

运行 Agent

# 单次执行（dry-run 预览，不实际执行）
kc run --dry-run

# 单次执行（当前仓库）
kc run

# 处理 registry 中所有启用的仓库
kc run --all

# Daemon 模式轮询（默认每 120 秒处理当前仓库；加 --all 处理所有启用仓库）
kc daemon

# Post-PR supervisor daemon 模式轮询（默认每 120 秒处理当前仓库；加 --all 处理所有启用仓库）
kc supervise-daemon

# 只监控单个仓库
kc daemon --repo-id keda

管理终端（kc console）

frontend-public 构建出的管理终端静态产物会随 wheel 一起分发。装好 kc 后，在任意目录一条命令即可启动 Web 管理终端（API + 内置面板），无需 clone 本仓库、无需 Node / pnpm / just：

# 启动管理终端并自动打开浏览器（前台运行）
kc console

# 指定端口（省略时先复用已在运行的实例，没有则在 config.toml [agent_runner.console].port 起自动挑选空闲端口）
kc console --port 8600

# 只启动服务，不自动开浏览器
kc console --no-browser

kc console 可重复调用：若已有 console 在监听，再敲一次只会打开它当前监听的 URL 并退出，不会因为默认端口被自己占住而顺延开第二个实例——关掉浏览器后想再看面板，直接再跑一次 kc console，无需重启服务。确实要并行跑第二个实例（例如另一套状态目录），显式指定一个空闲 --port。

面板提供所有已注册仓库的队列状态、Issue 事件时间线、运行历史与完成度统计，并支持启停 daemon、重试 failed Issue、管理 backlog 队列。默认只监听本机（127.0.0.1）；更多配置见 docs/guides/agent-runner.md 的「统一管理终端」一节。

自然语言决策入口（kc ask）

kc ask 是一个受限自然语言决策入口。默认只生成计划并写入审计文件，不执行任何副作用：

# 默认只输出计划
uv run kc ask "帮我判断现在应该创建 issue 还是启动任务"

# 显式指定 planner agent（默认 codex）
uv run kc ask "从 pending PRD 中挑一个最适合创建 issue 的任务" --agent codex

# 只打印计划，适合 CI 验证
uv run kc ask "现在可以跑一个 ready issue 吗" --plan-only

# 进入确认执行流程（TTY 中要求输入 decision_id）
uv run kc ask "从 tasks/pending/example.md 创建 issue" --execute

# 非交互执行（仅允许 low/medium 风险动作）
uv run kc ask "运行一次 dry-run 看看 ready 队列" --execute --yes

白名单动作包括：show_status、run_deliberation、create_issue_from_prd、mark_issue_ready、run_once_dry_run、run_once、review_once_dry_run、review_once、needs_clarification、no_op。禁止动作包括 git_push、git_merge、daemon、任意 shell 命令等。Planner agent 必须通过可验证只读命令运行；目前仅 codex 被验证为安全。

清理已关闭 Issue 的本地分支

kc worktree cleanup 用于清理本地遗留的 issue-<number> 分支及 .iar-worktrees/issue-<number> worktree。默认只预览；只有传入 --yes 才会删除。 清理前会执行 git fetch <remote> --prune，并且默认只删除同时满足“GitHub Issue 已关闭、远端同名分支已不存在、worktree 干净、分支已合入远端 base branch”的分支。 历史 <repo>-worktrees/tasks/issue-<number> worktree 不会被该命令自动删除，应按需 手动清理。

# 预览将会清理哪些本地 issue 分支
kc worktree cleanup --dry-run

# 执行安全清理
kc worktree cleanup --yes

# 同时删除脏 worktree 或未合入分支（谨慎）
kc worktree cleanup --yes --force

多仓库配置

在 config.toml 中配置多个仓库：

[agent_runner.repositories.keda]
path = "/Users/zata/code/keda"
enabled = true

[agent_runner.repositories.backend_service]
path = "/Users/zata/code/backend-service"
enabled = true

每个仓库根目录应有自己的 .kedacode.toml 文件，用于覆盖 runner、git、labels 等配置。

Git Worktree 工作流

本项目内置 Git Worktree 脚本，用于隔离开发环境：

# 创建并进入新 worktree（自动同步远程 base branch）
./scripts/shared/worktree/create.sh feature-branch

# 基于远程分支创建 worktree
./scripts/shared/worktree/create.sh feature-login --checkout origin/feature-login

# 指定来源分支
./scripts/shared/worktree/create.sh issue-15 --checkout zata/issue-15

# 强制新建本地分支（忽略同名远程分支）
./scripts/shared/worktree/create.sh feature-x --new

# 打开已有 worktree
./scripts/shared/worktree/open.sh feature-branch

# 合并 worktree 并清理
./scripts/shared/worktree/merge.sh feature-branch

# 删除 worktree
./scripts/shared/worktree/merge.sh feature-branch -d

# 诊断 worktree 状态
./scripts/shared/worktree/merge.sh --doctor

创建 worktree 后会自动安装 Python 和前端依赖。

PRD 驱动开发

# 从 PRD 自动创建 worktree 并启动 AI 工具
./scripts/shared/worktree/create.sh feature-x --subdir tasks
cp tasks/pending/feature-x.md ../tasks/feature-x/tasks/pending/feature-x.md
# 然后在 worktree 中启动 AI 工具执行 PRD

更完整的 PRD → worktree → AI 实现流程可参考 justfile.shared 中的 implement recipe。

测试

# 运行本地测试（无需 API Key）
# 第一次会完整执行并生成 .testmondata；后续仅运行与当前变更相关的测试
just test

# 强制运行全部测试，忽略 .testmondata
just test all

# 强制运行需要真实 API 的测试，忽略 .testmondata
just test real

# 直接调用 pytest（同样默认启用 --testmon）
uv run pytest tests/ -v

# 运行 Playwright E2E 测试（需先安装）
cd tests/playwright-e2e && npm install && npx playwright install chromium
cd tests/playwright-e2e && npm test
cd tests/playwright-e2e && npm run test:smoke      # 仅冒烟测试
cd tests/playwright-e2e && npm run test:no-auth    # 无需登录的公开页面测试
cd tests/playwright-e2e && npm run report          # 打开测试报告

文档

# 本地预览（带热重载，默认 8000 端口）
WATCHDOG_USE_POLLING=1 uv run mkdocs serve -a 127.0.0.1:8000

# 构建静态文档
uv run mkdocs build --strict

配置说明

• 全局配置：config.toml — 应用、数据库、模型、Agent Runner 等全局设置
• 仓库级配置：.kedacode.toml — 每个目标仓库根目录的 runner 覆盖配置
• 敏感信息：.env — 密码、API Key 等（已加入 .gitignore）

主要配置项：

• app.name / app.log_level — 应用名称与日志级别
• database.* — PostgreSQL 数据库配置
• chat_model.* — LLM 模型配置（provider、temperature 等）
• agent_runner.* — Agent Runner 完整配置（labels、git、worktree、runner、safety、prompts）

wheel 默认只装轻量核心依赖；以下能力按需安装 extras（源码开发用 uv sync --all-extras 一次装齐）：

uv pip install "kedacode[db]"       # 数据库能力：alembic、psycopg2、pymysql
uv pip install "kedacode[llm]"      # LLM 能力：langchain-openai / anthropic / core
uv pip install "kedacode[backup]"   # 云备份：boto3

架构概览

源码目录约定：

src/backend/
  api/           → 请求接入层（API、WebSocket、CLI）
  core/          → 核心编排层（用例、Agent 编排、领域契约）
  engines/       → 平台能力层（skills、RAG、可插拔能力）
  infrastructure/ → 基础设施层（模型、存储、HTTP、配置、日志）

依赖方向严格向下：api → core → engines → infrastructure，由 hooks/shared/check_architecture.py 在 pre-commit 强制校验。

Docker 部署

# Docker Compose 启动
docker compose up --build

详见 docker-compose.yml 和 docker-compose.dokploy.yml。

开发规范

• 公共 Python API 使用 Google Style Docstrings
• 变量命名需具有来源、类型或状态语义，避免 data、item、res
• Python 文本文件 I/O 必须显式写 encoding="utf-8"
• 新增代码前先搜索现有实现；参数超过 4 个时收敛到对象
• 单代码文件非空行不超过 1000 行
• 提交前会自动运行 pre-commit hooks

许可证

本项目基于 Apache License 2.0 开源发布 —— 你可以自由使用、修改、分发，也可以将其用于商业产品，但需保留版权声明并随分发物附带 LICENSE 文件。

Copyright 2026 zata
Licensed under the Apache License, Version 2.0

完整文本见 LICENSE。Apache 2.0 的关键条款：

• ✅ 商用、私有 fork、修改、再分发
• ✅ 授予使用者专利使用权（patent grant）
• ⚠️ 必须保留版权、商标与归属声明
• ⚠️ 修改文件需显著标注
• 🚫 不得使用 keda / kc 商标暗示官方背书

致谢

• FastAPI · Typer · Rich — 后端 & CLI 栈
• uv · just — 工具链
• MkDocs Material — 文档站
• Anthropic Claude · OpenAI Codex — 驱动 kc 的 AI Agent