@kodax-ai/kodax 0.7.40 → 0.7.42

package/README_CN.md

@@ -1,28 +1,133 @@
-# KodaX
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="assets/logo-light.svg">
+    <img src="assets/logo-light.svg" alt="KodaX" width="640">
+  </picture>
+</p>
+
+<p align="center">
+  <b>开源 AI Coding Agent，跑你能拿到的任何 LLM。</b><br>
+  Anthropic · OpenAI · DeepSeek · Kimi · 智谱 · MiniMax · 小米 MiMo · 火山方舟 · Qwen · Gemini · Codex<br>
+  REPL · CLI · 库 · 免 Node 单文件二进制
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@kodax-ai/kodax"><img alt="npm version" src="https://img.shields.io/npm/v/@kodax-ai/kodax?style=flat-square&color=cb3837"></a>
+  <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square"></a>
+  <a href="https://github.com/icetomoyo/KodaX/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/icetomoyo/KodaX?style=flat-square&logo=github&color=f1c40f"></a>
+  <a href="https://github.com/icetomoyo/KodaX/actions"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/icetomoyo/KodaX/release.yml?style=flat-square&label=release"></a>
+  <img alt="providers" src="https://img.shields.io/badge/LLMs-13_原生_+_OpenAI%2FAnthropic--compat-2ecc71?style=flat-square">
+</p>
+
+<p align="center">
+  <a href="#30-秒上手">安装</a> ·
+  <a href="#四种使用形态">使用形态</a> ·
+  <a href="#为什么用-kodax">为什么用</a> ·
+  <a href="CHANGELOG.md">更新日志</a> ·
+  <a href="docs/FEATURE_LIST.md">Roadmap</a> ·
+  <a href="https://github.com/icetomoyo/KodaX/discussions">讨论</a> ·
+  <a href="README.md">English README</a>
+</p>
+
+<p align="center">
+  <img src="kodax.gif" alt="KodaX 实战演示" width="880">
+</p>
 
-轻量、透明、可定制的 TypeScript AI Coding Agent。
+---
 
-KodaX 既可以作为命令行工具使用，也可以作为库集成到你的项目里，还能打包成**免 Node 运行时**的单文件二进制分发到目标机器。当前支持 12 个模型提供商，包含完整的 REPL、会话、30+ 工具、Skills，以及 Scout-first 自适应多 Agent 工作流。
+## 30 秒上手
 
-## 为什么用 KodaX
+```bash
+npm i -g @kodax-ai/kodax
 
-- 透明：代码结构清晰，便于阅读、修改和调试。
-- 灵活：支持多 provider，方便切换模型和网关。
-- 可定制：prompts、tools、skills、session 流程都能改。
-- 可复用：不只是 CLI，也可以把其中一层当库来使用。
+# 选一个你有 API key 的 provider
+export ZHIPU_API_KEY=...        # 或 KIMI_API_KEY / MINIMAX_API_KEY / MIMO_API_KEY /
+                                # ARK_API_KEY / DEEPSEEK_API_KEY / ANTHROPIC_API_KEY /
+                                # OPENAI_API_KEY / QWEN_API_KEY / GEMINI_API_KEY
 
-如果你关心：
+kodax
+```
+
+就这样。进 REPL，自然语言提问。
 
-- 想理解 AI coding agent 是怎么工作的
-- 不想被单一 provider 绑定
-- 希望 agent 逻辑能自己控制
-- 需要一套适合长期开发任务的工程化工作流
+> **不装 Node 的目标机器**：从 [GitHub Releases](https://github.com/icetomoyo/KodaX/releases) 拿 Bun 编译的单文件二进制（Win / macOS / Linux × x64 + arm64）。详见 [docs/release.md](docs/release.md)。
 
-那 KodaX 会比单纯依赖某个黑盒托管产品更合适。
+---
 
-## 快速开始
+## 四种使用形态
 
-### 1. 安装并构建
+| 形态 | 命令 / 入口 | 什么时候用 |
+|---|---|---|
+| **REPL** | `kodax` | 交互式多轮编码会话，流式 UI + 权限 + slash 命令 |
+| **CLI** | `kodax -p "your task"` | 单次脚本任务、CI、批量处理 |
+| **库** | `import { runKodaX } from '@kodax-ai/kodax'` | 嵌入你自己的工具 / agent / 服务 |
+| **单文件二进制** | `./kodax` | 分发到没装 Node 的机器 |
+
+---
+
+## 为什么用 KodaX
+
+<table>
+  <tr>
+    <td width="33%" align="center" valign="top">
+      <h3>🇨🇳 6 家国内 LLM 原生</h3>
+      <sub>智谱 · Kimi · MiniMax · 小米 MiMo · 火山方舟 · 通义千问</sub>
+      <br><br>
+      first-class 适配器，跨 provider 在 5-alias canonical panel 做过 <a href="benchmark/EVAL_GUIDELINES.md">prompt-eval 校准</a> —— 不是 OpenAI-compat 转发。
+    </td>
+    <td width="33%" align="center" valign="top">
+      <h3>📦 单文件二进制</h3>
+      <sub>Bun --compile · Win / macOS / Linux · x64 + arm64</sub>
+      <br><br>
+      目标机器不装 Node。一份文件随处跑 —— 受管环境、内网、CI runner、断网机器都行。
+    </td>
+    <td width="33%" align="center" valign="top">
+      <h3>🌳 可分叉会话血缘</h3>
+      <sub>fork · rewind · 并行编辑</sub>
+      <br><br>
+      对话历史是 DAG 不是链表。即将发布的 <b>KodaX Space</b> 桌面端基于此。
+    </td>
+  </tr>
+  <tr>
+    <td align="center" valign="top">
+      <h3>🤖 默认多 agent</h3>
+      <sub>V2 Worker + Evaluator + 异步子 agent</sub>
+      <br><br>
+      <code>dispatch_child_task</code>、<code>send_message</code>、<code>task_stop</code>，多实例自动协调（content-hash safety net）。
+    </td>
+    <td align="center" valign="top">
+      <h3>🧩 Skills + 自构造</h3>
+      <sub>Markdown skill，自然语言触发</sub>
+      <br><br>
+      5 阶自改造阶梯（scaffold → validate → stage → test → activate），由 8 条 admission invariant 守护。
+    </td>
+    <td align="center" valign="top">
+      <h3>🛠 30+ 内置工具</h3>
+      <sub>文件 · shell · 搜索 · MCP · ACP</sub>
+      <br><br>
+      repo intelligence、语义搜索、git worktree、web fetch，统一从干净的 tool definition 接口暴露。
+    </td>
+  </tr>
+</table>
+
+## 同类产品对比
+
+| 能力 | **KodaX** | Claude Code | Aider | Codex CLI | Cursor | Cline |
+|---|---|---|---|---|---|---|
+| 开源协议 | ✅ Apache&nbsp;2.0 | ❌ source-available | ✅ Apache&nbsp;2.0 | ✅ Apache&nbsp;2.0 | ❌ 闭源 | ✅ Apache&nbsp;2.0 |
+| 免 Node 单文件 | ✅ Bun | ❌ 需 Node | ❌ 需 Python | ✅ Rust | ❌ Electron | ❌ 插件 |
+| 国内 6 家原生<br><sub>（智谱·Kimi·MiniMax·MiMo·方舟·Qwen）</sub> | ✅ 6 家原生 | ❌ | ⚠ 走 LiteLLM | ❌ OpenAI 主线 | ❌ 无 provider 菜单 | ⚠ Kimi/Qwen/DeepSeek |
+| 可分叉会话血缘 | ✅ fork & rewind | ⚠ routines/sessions | ❌ | ❌ | ❌ | ⚠ checkpoints |
+| Multi-agent + MCP + 30+ 工具 | ✅ 三项全有 | ✅ 三项全有 | ⚠ 有 tools, 无 MCP | ✅ 三项全有 | ⚠ Composer + MCP | ✅ 三项全有 |
+
+<sub>数据于 2026-05 对照官方公开文档核对（[Claude Code](https://github.com/anthropics/claude-code) · [Aider](https://aider.chat/docs/llms.html) · [Codex CLI](https://github.com/openai/codex) · [Cursor](https://cursor.com) · [Cline](https://github.com/cline/cline)）。⚠ 表示部分支持 / 需额外配置 / 非 first-class。欢迎 PR 修正。</sub>
+
+## 详细配置
+
+> 上面的 `npm i -g @kodax-ai/kodax` 一行就够了。下面这一节是给"从源码构建 / 接自定义 provider / 把 KodaX 当库使用"的场景。
+
+### 1. 从源码构建
 
 ```bash
 git clone https://github.com/icetomoyo/KodaX.git
@@ -294,248 +399,18 @@ KodaX 有 30+ 个内置工具，按类别分组如下（实际暴露给 LLM 是
 | `exit_plan_mode` | Plan 模式下提交最终方案给用户审批（仅 REPL） |
 | `emit_managed_protocol` | managed-task 协议侧信道（handoff / verdict 等 role payload）。v0.7.36 FEATURE_114 起默认走 V2 Worker→Evaluator 链。 |
 
-## Repo Intelligence Premium
-
-KodaX 现在支持一套拆分后的 Repo Intelligence 架构：
-
-- 公共 OSS baseline 在 public `KodaX` 仓库里
-- premium intelligence 在 private `KodaX-private` 仓库里
-- premium 通过本地 `repointel` frontdoor 和 daemon 运行
-- KodaX 自身支持原生旗舰路径
-
-一句话理解：
-
-- 没有 premium 时，KodaX 仍然能正常工作
-- 安装 premium 后，KodaX 可以获得更强的仓库理解、影响面分析、上下文压缩和原生自动注入能力
-
-## Repo Intelligence 运行模式
-
-KodaX 支持这些模式：
-
-- `off`
-  - 严格关闭 repo-intelligence 工作面
-  - 不自动注入，也不暴露 repo working tools
-  - 但 `/repointel` 控制命令仍然保留
-- `oss`
-  - 只使用 public OSS baseline
-- `premium-shared`
-  - 使用 premium，但不走 KodaX 原生 auto lane
-  - 适合和其他宿主路径做对比
-- `premium-native`
-  - 使用 premium，并走 KodaX 原生路径
-  - 这是推荐模式，也是最佳体验
-- `auto`
-  - 先尝试 `premium-native`
-  - premium 不可用时自动回退到 `oss`
-
-## native-first 使用方式
-
-当前正式发布推荐使用 native `repointel` 包。
-
-也就是说：
-
-- 正式 GitHub Release 应该发布 native 包
-- offline bundle 只保留给内部验证或特殊场景
-
-### 普通用户最简配置
-
-如果 `repointel` 已经在 `PATH`：
-
-```json
-{
-  "repoIntelligenceMode": "premium-native"
-}
-```
-
-### 不在 PATH 时
-
-```json
-{
-  "repoIntelligenceMode": "premium-native",
-  "repointelBin": "C:\\Tools\\repointel\\repointel.exe"
-}
-```
-
-### 作者同父目录联调
-
-```json
-{
-  "repoIntelligenceMode": "premium-native",
-  "repointelEndpoint": "http://127.0.0.1:47891",
-  "repointelBin": "C:\\path\\to\\KodaX-private\\packages\\repointel-cli\\dist\\index.js",
-  "repoIntelligenceTrace": true
-}
-```
-
-配置模板可参考：
-
-- [config.example.jsonc](./config.example.jsonc)
-
-## `repointelEndpoint` 是什么
-
-`repointelEndpoint` 表示 KodaX 连接本地 premium daemon 的地址。
-
-默认值通常是：
-
-```json
-"repointelEndpoint": "http://127.0.0.1:47891"
-```
-
-大多数用户不需要手动配置它，只有这些情况才建议显式设置：
+## Repo Intelligence（可选 premium 引擎）
 
-- 你改了默认端口
-- 你想同时跑多个 daemon
-- 你在做本地调试或隔离实验
+KodaX 内置 OSS repo intelligence（`repo_overview` / `module_context` / `symbol_context` / `process_context` / `impact_estimate` 等），让 coding agent 不靠零散 grep/glob 就能理解大型仓库。
 
-## REPL 里怎么看当前状态
+可选的 **premium 引擎**（`repointel` 本地 daemon，通过 sibling `KodaX-private` 仓发布）增加主动上下文注入、更深的 module capsule，以及一条 KodaX 原生 auto-lane。premium 不可用时 KodaX 自动 fallback 到 OSS。
 
-启动 `kodax` 后，可以直接使用：
-
-- `/status`
-  - 看简要状态
-- `/repointel`
-  - 看更详细的 repo-intelligence 状态
-- `/repointel status`
-  - 显式探测本地 premium frontdoor
-
-最重要的字段有：
-
-- `mode`
-- `engine`
-- `bridge`
-- `status`
-
-例如：
-
-- `premium-native / premium / native / ok`
-  - 说明 premium 生效了，而且走的是 KodaX 原生旗舰路径
-- `oss / oss / none / ok`
-  - 说明当前实际运行在 OSS baseline
-
-## REPL 里怎么控制 Repo Intelligence
-
-可用命令包括：
-
-- `/repointel`
-- `/repointel status`
-- `/repointel mode premium-native|premium-shared|oss|off|auto`
-- `/repointel trace on|off|toggle`
-- `/repointel warm`
-- `/repointel endpoint ...`
-- `/repointel bin ...`
-
-你也可以用：
-
-- `/clear`
-
-来清空当前会话上下文。
-
-如果要做严格 benchmark，最好每档模式都使用一个全新的 session，避免旧上下文污染结果。
-
-## `repoIntelligenceTrace` 有什么用
-
-`repoIntelligenceTrace` 是一个诊断和对比开关。
-
-打开后，你可以更清楚地看到：
-
-- 当前到底是 `oss` 还是 `premium`
-- 当前是 `shared` 还是 `native`
-- daemon latency
-- cache hit/miss
-- capsule token 估算
-
-普通用户平时通常可以不开；联调、benchmark、排障时再打开。
-
-## `premium-native` 和 `premium-shared` 的区别
-
-两者都使用 premium，但区别在于是否使用 KodaX 原生特权路径：
-
-- `premium-native`
-  - KodaX 旗舰路径
-  - 更早预取 intelligence
-  - 在 planning / routing / prompt build 前就更主动地使用 premium
-- `premium-shared`
-  - 仍然用 premium
-  - 但故意不走 KodaX 原生 auto lane
-  - 更接近其他宿主的共享接入方式
-
-如果你平时自己用 KodaX，推荐 `premium-native`。
-
-## 如何更明显地体现 `repointel` 收益
-
-最容易体现 repo-intelligence 收益的任务，不是“改单一文件”，而是：
-
-- 需要先理解仓库结构
-- 需要缩小范围
-- 需要判断模块、流程、影响面
-
-例如：
-
-```text
-我要给 KodaX 增加一个真正的 /new 命令。先不要写代码，先判断最可能需要改哪些模块、调用链会经过哪里、最值得先看的 8 个文件是什么。
-```
-
-```text
-帮我定位 KodaX 从命令行启动，到进入 REPL 或 ACP，再到真正调用 coding agent 的主入口链。先给我分层图和最关键文件，不要先铺开全部实现。
-```
-
-如果你要做 A/B 测试，建议比较：
-
-- `off`
-- `oss`
-- `premium-shared`
-- `premium-native`
-
-而且每档尽量用全新的 session。
-
-## Clients 目录说明
-
-`clients/` 目录现在已经收敛成极简结构。
-
-它只保留一个共享的开放资产：
-
-- `clients/repointel/`
-
-这份 shared skill 是 Phase 1 多宿主接入的唯一源：
-
-- Codex
-- Claude Code
-- OpenCode
-
-都通过同一份 shared skill 接入本地 `repointel`，而不是各自维护一套 host-pack 目录。
-
-这样做的原因是：
-
-- premium 逻辑在 `KodaX-private` 的 `repointel` 工具里，不在 host 包装层里
-- 多宿主接入本来就是薄层，不应该继续保留一堆 Windows-first 的历史壳目录
-- 共享一个 skill 源更干净、更容易维护，也更符合当前 native-first 的发布方向
-
-现在的标准使用方式是：
-
-- 用 `clients/repointel/scripts/install.mjs` 把 shared skill 安装到目标宿主需要的位置
-- 用 `clients/repointel/scripts/doctor.mjs` 检查本地 premium / daemon / host skill 安装状态
-- 用 `clients/repointel/scripts/demo.mjs` 做本地演示和验证
-
-示例：
-
-```powershell
-node .\clients\repointel\scripts\install.mjs --host codex
-node .\clients\repointel\scripts\install.mjs --host claude --workspace-root C:\path\to\workspace
-node .\clients\repointel\scripts\install.mjs --host opencode --workspace-root C:\path\to\workspace
+```bash
+# 选一个运行模式（off | oss | premium-shared | premium-native | auto）
+kodax --repo-intelligence premium-native --repo-intelligence-trace
 ```
 
-补充说明：
-
-- 可安装的 skill 目录入口是 `clients/repointel/SKILL.md`
-- `clients/repointel/` 整个目录遵循 Claude Code Skills 规范，`SKILL.md` 是入口，`reference.md` 是辅助参考文件
-- `scripts/install.mjs`、`doctor.mjs`、`demo.mjs` 是仓库维护脚本，位于 `scripts/` 子目录
-- 所以 `clients/repointel/` 现在承载的是完整的第三方宿主集成单元，而不只是一个单独的 skill 文件
-
-也就是说：
-
-- `clients/` 不是 build 产物
-- 它现在也不再是“每个宿主一套安装包”
-- 它只是存放 shared repointel skill 的正式源码位置
+完整安装 / 运行模式 / REPL 控制 / config schema / 第三方宿主接入，详见 [docs/REPOINTEL.md](docs/REPOINTEL.md)。
 
 ## 仓库结构
 

package/dist/chunks/chunk-3RKBXWZS.js

@@ -0,0 +1,2 @@
+// @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
+import{a as n}from"./chunk-V4WSBIXB.js";var o=class r{static{n(this,"SpanImpl")}id;traceId;parentId;name;data;startedAt;_endedAt;_error;_children=[];now;nextSpanId;onChildCreated;onSpanEnd;_ended=!1;constructor(e){this.id=e.id,this.traceId=e.traceId,this.parentId=e.parentId,this.name=e.name,this.data=e.data,this.now=e.now??(()=>Date.now()),this.startedAt=e.startedAt??this.now(),this.nextSpanId=e.nextSpanId??I,this.onChildCreated=e.onChildCreated,this.onSpanEnd=e.onSpanEnd}get endedAt(){return this._endedAt}get error(){return this._error}get children(){return this._children}addChild(e,a){let t=new r({id:this.nextSpanId(),traceId:this.traceId,parentId:this.id,name:e,data:a,now:this.now,nextSpanId:this.nextSpanId,onChildCreated:this.onChildCreated,onSpanEnd:this.onSpanEnd});return this._children.push(t),this.onChildCreated&&this.onChildCreated(t),t}setError(e){e instanceof Error?this._error={message:e.message,stack:e.stack}:this._error=e}end(){this._ended||(this._ended=!0,this._endedAt=this.now(),this.onSpanEnd&&this.onSpanEnd(this))}},f=0;function I(){f+=1;let r=Math.random().toString(36).slice(2,8);return`span-${Date.now()}-${f}-${r}`}n(I,"defaultNextSpanId");var g=0;function w(){g+=1;let r=Math.random().toString(36).slice(2,8);return`trace-${Date.now()}-${g}-${r}`}n(w,"defaultNextTraceId");function s(r={}){let e=r.now??(()=>Date.now()),a=r.id??(r.nextTraceId??w)(),t=e(),u=r.name??"trace",T=r.metadata??new Map,x=r.rootSpanData??{kind:"agent",agentName:u},m=!1,h,v,d=new o({id:`${a}-root`,traceId:a,name:u,data:x,startedAt:t,now:e,nextSpanId:r.nextSpanId,onChildCreated:r.onSpanStart,onSpanEnd:r.onSpanEnd});r.onSpanStart&&r.onSpanStart(d);let y={id:a,startedAt:t,rootSpan:d,metadata:T,get endedAt(){return h},get error(){return v??d.error},end(){m||(m=!0,h=e(),d.end(),r.onTraceEnd&&r.onTraceEnd(y))}};return y}n(s,"createTrace");var p=[];function c(r){for(let e of p)try{e.onSpanStart(r)}catch{}}n(c,"_emitSpanStart");function l(r){for(let e of p)try{e.onSpanEnd(r)}catch{}}n(l,"_emitSpanEnd");function S(r){for(let e of p)try{e.onTraceEnd(r)}catch{}}n(S,"_emitTraceEnd");var i=class{static{n(this,"Tracer")}options;constructor(e={}){this.options=e}startTrace(e={}){return s({id:e.id,name:e.name,rootSpanData:e.rootSpanData,metadata:e.metadata,now:this.options.now,nextSpanId:this.options.nextSpanId,nextTraceId:this.options.nextTraceId,onSpanStart:c,onSpanEnd:l,onTraceEnd:S})}},E=new i;export{E as a};