Skip to content

README.zh-cn.md

Latest commit

 

History

History
303 lines (226 loc) · 6.74 KB

README.zh-cn.md

File metadata and controls

303 lines (226 loc) · 6.74 KB

Kkachi

面向编码代理的可移植 Top-1 贪心循环引擎。

Kkachi 将选择策略集中在一个 Python 核心中，并提供以下薄集成层：

  • Gemini CLI extension
  • OpenCode（项目级/全局）
  • 可在 Codex / Claude Code / OpenCode 共用的 Shell 循环

多语言文档：

核心思路

每次迭代强制执行同一合同：

  1. 对 pending 任务打分
  2. 只选择一个 Top-1
  3. 只执行该任务并验证
  4. 记录 success|fail

这样可以避免一次做多件事导致的漂移，并通过文件状态（tasks.json、state JSON）持续跟踪进度。

默认评分公式

score =
  + 5 * fail_first
  + 4 * priority
  + 3 * kkachi-unblock
  + 2 * quick_win
  + 2 * impact
  + 1 * info_gain
  - 3 * risk
  - 2 * effort
  - 4 * failures

规则说明：

  • fail_first：仅当 --tests-failing 开启且 kind=="fix" 时为 1
  • quick_win：当 effort<=2 且 risk<=2 时为 1
  • 同分排序：effort 低 -> risk 低 -> priority 高 -> id 字典序
  • 支持 --epsilon 的 epsilon-greedy 探索

内置模式

python3 kkachi_greedy.py modes
python3 kkachi_greedy.py modes --json
模式 目标 默认 epsilon
kkachi-ship-fast 快速产出可见结果 0.05
kkachi-stabilize 稳定性和低风险优先 0.0
kkachi-unblock 优先打通依赖瓶颈 0.05
kkachi-discover 在不确定场景下提高信息增益 0.2
kkachi-debt-burn 控制风险地清理技术债 0.02
kkachi-incident 故障/CI 紧急模式 0.0

权重合并顺序：

  1. 默认 Weights
  2. 模式 weights
  3. --weights-file（或 config）覆盖

运行依赖

  • python3（CI 使用 3.11）
  • jq
  • bash

可选：

  • gemini CLI（安装 Gemini 扩展时）
  • OpenCode 运行环境（使用 OpenCode 命令时）

快速开始

初始化：

bash scripts/init.sh
bash scripts/doctor.sh .kkachi/tasks.json .kkachi/config.json

查看排序：

python3 kkachi_greedy.py rank .kkachi/tasks.json \
  --weights-file .kkachi/config.json \
  --mode kkachi \
  --json

执行一次迭代：

bash scripts/setup.sh "Implement feature X with tests"
bash scripts/status.sh
TASK_ID=$(bash scripts/next.sh)
bash scripts/render_step_prompt.sh
# 实施 + 验证
bash scripts/mark.sh "$TASK_ID" success

检查是否完成：

python3 kkachi_greedy.py pending .kkachi/tasks.json

任务 JSON 结构

tasks.json 必须是 JSON 数组。

字段 类型 默认值 说明
id string 必填 必须唯一
title string id 展示标题
priority int 1 >=0
impact int 1 >=0
effort int 1 >=0
risk int 1 >=0
kkachi-unblock int 0 >=0
info_gain int 0 >=0
kind string feature fail-first 需使用 fix
status string pending `pending
failures int 0 >=0

doctor 会检查：

  • 重复 ID
  • 非法状态
  • 负数值
  • 模式/权重/运行时参数错误

配置 (config.json)

参考 examples/config.json：

  • 循环参数：tests_failing, seed, block_after, max_iterations, completion_promise, mode
  • 权重覆盖：可用顶层权重键或 weights 对象

scripts/setup.sh 会：

  • 从 examples/ 自动生成缺失文件
  • 读取 config，并允许 CLI 参数覆盖
  • 将运行状态写入 .gemini/kkachi/state.json

CLI 命令概览 (kkachi_greedy.py)

  • rank：输出排序及当前选择
  • select：输出选择的 task id（或 JSON），无待办时退出码 1
  • pending：输出 pending 数量
  • apply：写入 success|fail（支持 --block-after）
  • loop：模拟循环（--max-steps, --auto-success-rate, --write）
  • explain：输出单任务评分分解
  • doctor：校验输入（--json），失败退出码 2
  • modes：列出模式（--json）

脚本说明 (scripts/)

脚本 作用
init.sh 初始化 tasks/config 并执行 doctor
setup.sh 根据提示与配置初始化循环状态
status.sh 显示当前迭代状态和 Top-1
next.sh 选择下一条 Top-1
render_step_prompt.sh 生成单步执行提示
mark.sh 记录任务执行结果
doctor.sh 依赖检查 + Python doctor 包装
cancel.sh 停止循环并删除 state
install_gemini.sh 安装 Gemini 扩展
uninstall_gemini.sh 卸载 Gemini 扩展
install_opencode.sh 安装 OpenCode 集成
uninstall_opencode.sh 卸载 OpenCode 集成

Gemini CLI Extension

关键文件：

  • gemini-extension.json
  • commands/kkachi/*.toml
  • hooks/hooks.json
  • hooks/stop-hook.sh

安装：

bash scripts/install_gemini.sh

手动安装：

gemini extensions install <repo-url> --auto-update

命令：

  • /kkachi:init
  • /kkachi:loop "<goal prompt>" [options]
  • /kkachi:status
  • /kkachi:modes
  • /kkachi:cancel
  • /kkachi:help

/kkachi:loop 常用参数：

  • --tasks-file, --config-file, --weights-file
  • --mode, --mode-file, --mode-dir
  • --max-iterations, --completion-promise
  • --tests-failing, --epsilon, --seed, --block-after

Hook（AfterAgent）停止条件：

  • pending == 0
  • 检测到 completion promise
  • 提示词不匹配
  • 达到最大迭代次数

卸载：

bash scripts/uninstall_gemini.sh

OpenCode 集成

项目级安装：

bash scripts/install_opencode.sh

全局安装：

bash scripts/install_opencode.sh --global

安装产物：

  • .opencode/kkachi/（core/scripts/examples/modes）
  • .opencode/commands/kkachi-*.md
  • .opencode/plugins/kkachi-idle.ts
  • .opencode/rules/kkachi.md
  • opencode.json 中合并 instructions

OpenCode 命令：

  • /kkachi-init
  • /kkachi-loop
  • /kkachi-status
  • /kkachi-modes
  • /kkachi-cancel

卸载：

bash scripts/uninstall_opencode.sh
bash scripts/uninstall_opencode.sh --global

仓库结构

.
├─ kkachi_greedy.py
├─ modes/
├─ examples/
├─ scripts/
├─ commands/kkachi/
├─ hooks/
├─ integrations/opencode/template/
├─ agents/
├─ prompts/
├─ docs/
├─ tests/
└─ .github/workflows/ci.yml

开发与校验

python3 -m unittest kkachi-discover -s tests -p "test_*.py"
bash -n hooks/stop-hook.sh scripts/*.sh
python3 kkachi_greedy.py doctor examples/tasks.json --weights-file examples/config.json
python3 kkachi_greedy.py modes
python3 kkachi_greedy.py explain examples/tasks.json CI-01 --weights-file examples/config.json

补充文档：

  • docs/INSTALL.md
  • docs/CROSS_CLI.md
  • CONTRIBUTING.md