@kodax-ai/kodax 0.7.41 → 0.7.43

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
+
+# 选一个你有 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
+```
 
-- 透明：代码结构清晰，便于阅读、修改和调试。
-- 灵活：支持多 provider，方便切换模型和网关。
-- 可定制：prompts、tools、skills、session 流程都能改。
-- 可复用：不只是 CLI，也可以把其中一层当库来使用。
+就这样。进 REPL，自然语言提问。
 
-如果你关心：
+> **不装 Node 的目标机器**：从 [GitHub Releases](https://github.com/icetomoyo/KodaX/releases) 拿 Bun 编译的单文件二进制（Win / macOS / Linux × x64 + arm64）。详见 [docs/release.md](docs/release.md)。
 
-- 想理解 AI coding agent 是怎么工作的
-- 不想被单一 provider 绑定
-- 希望 agent 逻辑能自己控制
-- 需要一套适合长期开发任务的工程化工作流
+---
+
+## 四种使用形态
 
-那 KodaX 会比单纯依赖某个黑盒托管产品更合适。
+| 形态 | 命令 / 入口 | 什么时候用 |
+|---|---|---|
+| **REPL** | `kodax` | 交互式多轮编码会话，流式 UI + 权限 + slash 命令 |
+| **CLI** | `kodax -p "your task"` | 单次脚本任务、CI、批量处理 |
+| **库** | `import { runKodaX } from '@kodax-ai/kodax'` | 嵌入你自己的工具 / agent / 服务 |
+| **单文件二进制** | `./kodax` | 分发到没装 Node 的机器 |
 
-## 快速开始
+---
 
-### 1. 安装并构建
+## 为什么用 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 单循环 + Sidecar Verifier + 异步子 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
@@ -100,14 +205,17 @@ const result = await runKodaX(
 如果只想用某个子能力，按 subpath 引入更轻量，bundler 也能更好地 tree-shake：
 
 ```typescript
-import { Runner } from '@kodax-ai/kodax/agent';        // Agent runtime
-import { createProvider } from '@kodax-ai/kodax/llm';  // LLM 抽象（12 家 provider）
-import { runKodaX } from '@kodax-ai/kodax/coding';     // Coding tools + prompts
-import { SkillRegistry } from '@kodax-ai/kodax/skills'; // 零依赖 skill loader
-import { loadConfig } from '@kodax-ai/kodax/repl';     // REPL 配置 / session 工具
+import { Runner } from '@kodax-ai/kodax/agent';                // Agent runtime
+import { createProvider } from '@kodax-ai/kodax/llm';           // LLM 抽象（12 家 provider）
+import { runKodaX } from '@kodax-ai/kodax/coding';              // Coding tools + prompts
+import { SkillRegistry } from '@kodax-ai/kodax/skills';         // 零依赖 skill loader
+import { loadConfig } from '@kodax-ai/kodax/repl';              // REPL 配置 / session 工具
+import { createMcpManager } from '@kodax-ai/kodax/mcp';         // MCP popout manager（v0.7.42 起）
 ```
 
-6 个入口（root + 5 subpath）通过 ESM 共享 chunk 复用底层代码 —— 只 import `/agent` 不会把 `/repl` 的 Ink + React 一起拉进来。
+7 个入口（root + 6 subpath）通过 ESM 共享 chunk 复用底层代码 —— 只 import `/agent` 不会把 `/repl` 的 Ink + React 一起拉进来。
+
+> **SDK 是 ESM-only**。在 CommonJS 上下文（Electron main 进程、传统 Webpack CJS bundle、`require()` 调用方）必须用 `await import('@kodax-ai/kodax/...')` 代替 `require()`。详见 [docs/SDK_EMBEDDER_GUIDE.md §5](docs/SDK_EMBEDDER_GUIDE.md#5-consuming-from-a-commonjs-context-electron-main-cjs-bundles)，含 Electron main 完整 recipe + 为什么大多数 subpath 物理上无法做 dual ESM/CJS bundle。
 
 ### 5. 自定义 Provider（OpenAI / Anthropic 兼容端点）
 
@@ -292,283 +400,71 @@ KodaX 有 30+ 个内置工具，按类别分组如下（实际暴露给 LLM 是
 | `task_stop` | 请求指定 child 优雅退出。当前 tool 原子结束后 child 看到 `<coordinator-stop-request>` 并 emit 最终摘要。仅 coordinator 可用。(FEATURE_120, v0.7.39) |
 | `ask_user_question` | 向用户发起单选 / 多选 / 自由文本提问 |
 | `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"
-```
-
-大多数用户不需要手动配置它，只有这些情况才建议显式设置：
-
-- 你改了默认端口
-- 你想同时跑多个 daemon
-- 你在做本地调试或隔离实验
+| `emit_managed_protocol` | managed-task 协议侧信道（verdict role payload）。v0.7.42 FEATURE_184 起默认走 V2 Worker 单循环 + Sidecar Verifier；v0.7.43 FEATURE_193 退役 V1 chain。 |
 
-## REPL 里怎么看当前状态
+## Repo Intelligence（可选 premium 引擎）
 
-启动 `kodax` 后，可以直接使用：
+KodaX 内置 OSS repo intelligence（`repo_overview` / `module_context` / `symbol_context` / `process_context` / `impact_estimate` 等），让 coding agent 不靠零散 grep/glob 就能理解大型仓库。
 
-- `/status`
-  - 看简要状态
-- `/repointel`
-  - 看更详细的 repo-intelligence 状态
-- `/repointel status`
-  - 显式探测本地 premium frontdoor
+可选的 **premium 引擎**（`repointel` 本地 daemon，通过 sibling `KodaX-private` 仓发布）增加主动上下文注入、更深的 module capsule，以及一条 KodaX 原生 auto-lane。premium 不可用时 KodaX 自动 fallback 到 OSS。
 
-最重要的字段有：
-
-- `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)。
 
 ## 仓库结构
 
-KodaX 是基于 npm workspaces 的 TypeScript monorepo，源码层 9 个 workspace 包，npm 上以单 bundle 包 `@kodax-ai/kodax` 发布 + 5 个 SDK subpath exports（ADR-022 + ADR-024，v0.7.39）。核心包：
+KodaX 是基于 npm workspaces 的 TypeScript monorepo，**源码层 4 个 workspace 包**（FEATURE_194 v0.7.43 包合并 — 9 → 4，ADR-036），npm 上以单 bundle 包 `@kodax-ai/kodax` 发布 + SDK subpath exports（`/agent`、`/llm`、`/coding`、`/repl`；ADR-022 + ADR-024 v0.7.39）。核心包：
 
 | Workspace 包 | 作用 | 主要依赖 |
 |----|------|---------|
 | `@kodax-ai/llm` | LLM 抽象层（12 个内置 provider + 自定义 provider 注册），可独立使用 | `@anthropic-ai/sdk`, `openai` |
-| `@kodax-ai/agent` | 通用 Agent 框架 —— Runner / runFanOut / runWithIdleYield / ChildTaskRegistry + 会话管理 + tokenization + 可插拔 compaction（ADR-021 standalone-consumable） | `@kodax-ai/llm`, `js-tiktoken` |
-| `@kodax-ai/skills` | Agent Skills 标准实现（自然语言触发、变量解析） | 零外部依赖 |
-| `@kodax-ai/coding` | Coding Agent：30+ 工具（含 `dispatch_child_task` / `send_message` / `task_stop`）、role prompts、agent loop、auto-continue | `@kodax-ai/llm`, `@kodax-ai/agent`, `@kodax-ai/skills` |
+| `@kodax-ai/agent` | 通用 Agent 框架 —— Runner / runFanOut / runWithIdleYield / ChildTaskRegistry + 会话管理 + tokenization + 可插拔 compaction + **inline 后**:session-lineage 子树 + capabilities (mcp + skills + builtin) + tracing（subpaths: `/session-lineage`、`/capabilities/mcp`、`/capabilities/skills`、`/tracing`） | `@kodax-ai/llm`, `js-tiktoken`, `fflate`, `yaml` |
+| `@kodax-ai/coding` | Coding Agent:30+ 工具(含 `dispatch_child_task`/`send_message`/`task_stop`)、role prompts、agent loop、auto-continue + repo-intelligence protocol(v0.7.43 inline) | `@kodax-ai/llm`, `@kodax-ai/agent` |
 | `@kodax-ai/repl` | 完整交互式终端 UI（Ink / React、权限模式、命令系统、流式渲染） | `@kodax-ai/coding`, `ink`, `react` |
 
-辅助包：`@kodax-ai/mcp`、`@kodax-ai/repointel-protocol`、`@kodax-ai/session-lineage`、`@kodax-ai/tracing`（按需依赖）。
+根目录 `src/kodax_cli.ts` 是 CLI 入口；`src/sdk-{agent,llm,coding,repl,skills,mcp,session}.ts` 是 SDK subpath 入口；构建产物在 `dist/`，单文件二进制在 `dist/binary/<target>/`。
+
+### 源码层 vs npm 发布层
+
+KodaX 有两层结构，SDK 用户需要分开理解：
+
+- **源码层**：上面 4 个 workspace 包（开发者读代码时看到的物理结构）。
+- **npm 发布层**：单个 bundled 包 `@kodax-ai/kodax`，对外暴露 7 个 SDK subpath（SDK 消费者 `import` 时看到的接口）。subpath 分两种角色：
+  - **完整包 subpath**（`/agent`、`/llm`、`/coding`、`/repl`）—— 每个 1:1 对应一个源码包，暴露完整公开 API。
+  - **窄子集 subpath**（`/skills`、`/mcp`、`/session`）—— 从 `/agent` 或 `/repl` 切出聚焦的能力子集，让"只用 Skills/MCP/会话管理"的消费者引入更小的依赖。
+
+| 源码包 | npm subpath | 类型 | 内容 | 典型消费者 |
+|---|---|---|---|---|
+| `packages/llm`    | `@kodax-ai/kodax/llm`     | 完整包 | 12 provider LLM 抽象 (77 exports) | 独立 LLM 客户端 |
+| `packages/agent`  | `@kodax-ai/kodax/agent`   | 完整包 | Runner / fan-out / session-lineage / capabilities / tracing (202 exports) | 自定义 agent 框架 |
+| `packages/agent`  | `@kodax-ai/kodax/skills`  | **窄子集** | 仅 Skills 系统 —— `SkillRegistry` / `loadFullSkill` / `expandSkillForLLM` 等 (26 exports = v0.7.43 之前 `@kodax-ai/skills` 完整 API) | Skill 加载器、IDE 插件 |
+| `packages/agent`  | `@kodax-ai/kodax/mcp`     | **窄子集** | 仅 MCP —— `McpCapabilityProvider` / `createMcpTransport` / `searchMcpCatalog` 等 (11 exports = v0.7.43 之前 `@kodax-ai/mcp` 完整 API) | MCP server 宿主 |
+| `packages/coding` | `@kodax-ai/kodax/coding`  | 完整包 | Coding agent + 30+ 工具 + repo-intelligence (342 exports) | 构建 Claude Code 形态产品 |
+| `packages/repl`   | `@kodax-ai/kodax/repl`    | 完整包 | Ink TUI + 权限模式 + 命令系统 (193 exports) | 终端 UI 消费者 |
+| `packages/repl`   | `@kodax-ai/kodax/session` | **窄子集** | 仅会话管理 —— `listSessions` / `forkSession` / `watchSessions` 等 (9 exports) | 读取 session 历史的 IDE 插件 |
 
-根目录 `src/kodax_cli.ts` 是 CLI 入口；`src/sdk-{agent,llm,coding,repl,skills}.ts` 是 5 个 SDK subpath 入口；构建产物在 `dist/`，单文件二进制在 `dist/binary/<target>/`。
+**经验法则**：需要 Runner / Agent / fan-out 时从 `/agent` 引入；只需要 skills 或 mcp API 时从 `/skills` 或 `/mcp` 引入，bundle 更小。窄子集是完整包的真子集 —— **不会**有额外符号。
 
 ```
-KodaX/
+KodaX/                       # 4 workspace packages(FEATURE_194 v0.7.43)
 ├── packages/
-│   ├── ai/                  # @kodax-ai/llm —— 12 个 LLM provider 实现
-│   ├── agent/               # @kodax-ai/agent —— Runner / fan-out / idle-yield / session
-│   ├── skills/              # @kodax-ai/skills —— 零依赖 skill 加载器
-│   │   └── builtin/         # 内置 skills：code-review / tdd / git-workflow / skill-creator
+│   ├── llm/                 # @kodax-ai/llm —— 12 个 LLM provider 实现
+│   ├── agent/               # @kodax-ai/agent —— Runner / fan-out / idle-yield + 子树:
+│   │   ├── session-lineage/ # 分支 session tree (v0.7.43 inline)
+│   │   ├── capabilities/
+│   │   │   ├── mcp/         # MCP 集成 (v0.7.43 inline)
+│   │   │   └── skills/      # Skills 标准实现 + builtin (v0.7.43 inline)
+│   │   └── tracing/         # 追踪 / 可观测性 (v0.7.43 inline)
 │   ├── coding/              # @kodax-ai/coding —— tools + prompts + agent loop
-│   ├── repl/                # @kodax-ai/repl —— Ink TUI
-│   ├── mcp/                 # @kodax-ai/mcp
-│   ├── repointel-protocol/  # @kodax-ai/repointel-protocol
-│   ├── session-lineage/     # @kodax-ai/session-lineage
-│   └── tracing/             # @kodax-ai/tracing
+│   │   └── repo-intelligence/ # 含 protocol.ts (v0.7.43 inline)
+│   └── repl/                # @kodax-ai/repl —— Ink TUI
 ├── src/
 │   ├── kodax_cli.ts         # CLI 主入口（bin: `kodax`）
-│   └── sdk-*.ts             # 5 个 SDK subpath 入口 → @kodax-ai/kodax/{agent,llm,coding,repl,skills}
+│   └── sdk-*.ts             # SDK subpath 入口 → @kodax-ai/kodax/{agent,llm,coding,repl}
 ├── scripts/
 │   ├── build-bundle.mjs     # esbuild 单 bundle 多 entry 打包（CLI + 6 SDK entry + chunks）
 │   ├── build-binary.mjs     # Bun --compile 单文件二进制打包