# https://github.com/manufosela/karajan-code 项目说明书

生成时间：2026-07-19 17:30:17 UTC

## 目录

- [项目概览与快速开始](#page-1)
- [系统架构、流水线与角色](#page-2)
- [核心功能：规划、HUs、RAG 与质量保障](#page-3)
- [部署、安装配置文件与故障排除](#page-4)

<a id='page-1'></a>

## 项目概览与快速开始

### 相关页面

相关主题：[系统架构、流水线与角色](#page-2), [部署、安装配置文件与故障排除](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/manufosela/karajan-code/blob/main/README.md)
- [docs/GETTING-STARTED.md](https://github.com/manufosela/karajan-code/blob/main/docs/GETTING-STARTED.md)
- [package.json](https://github.com/manufosela/karajan-code/blob/main/package.json)
- [bin/kj.js](https://github.com/manufosela/karajan-code/blob/main/bin/kj.js)
- [bin/karajan-mcp.js](https://github.com/manufosela/karajan-code/blob/main/bin/karajan-mcp.js)
- [bin/kj-tail](https://github.com/manufosela/karajan-code/blob/main/bin/kj-tail)
</details>

# 项目概览与快速开始

karajan-code（命令行入口 `kj`）是一个面向真实代码仓库的「编排型 AI 编码助手」。它把高层意图（用户故事 / 需求单元 / HU）拆解为可执行的迭代流水线，调用本地或托管的编码代理（Gemini CLI、Kimi、DeepSeek 等），并把改动通过 git worktree 落到隔离分支里，最后自动创建 PR 或本地提交。整个流程由预算、并行度和步进开关统一约束，避免失控运行 资料来源：[README.md:1-40]()。

## 项目定位与能力范围

karajan-code 的设计目标不是「又一个聊天式 AI CLI」，而是把多 HU（Historical Unit）迭代、模型路由、工具治理和提交自动化整合成一个可审计的管道。核心能力包括：

- **多 HU 计划与执行**：从一份需求文档派生 N 个独立 HU，每个 HU 走完整生命周期（plan → code → review → approve）。`kj run` 是流水线主入口。
- **并行泳道**：`kj run --parallel N` 在 git worktree 中开辟 N 条独立泳道，每条泳道在落地前会先 bootstrap（submodules + `session.worktree_setup` 或 `npm ci`） 资料来源：[README.md:60-90]()`KJC-TSK-0630`。该特性在 v3.14.1 之前曾静默退化为串行执行，已修复。
- **步进模式**：`kj run --step` 在每一次迭代后暂停并打印紧凑报告，便于人工监督 资料来源：[README.md:90-110]()`KJC-TSK-0628`。
- **预算护栏**：每次运行默认 `max_budget_usd = 5`，防止卡死循环烧光订阅额度 资料来源：[package.json:30-60]()`KJC-TSK-0621`。
- **工具治理**：`kj harden` 会识别仓库已有的格式化 / 静态检查工具（如 Biome），避免重复植入 eslint + prettier 资料来源：[README.md:110-140]()`KJC-TSK-0614`。
- **MCP 桥接**：`bin/karajan-mcp.js` 把 karajan 的能力以 Model Context Protocol 形式暴露给 IDE / 客户端。

## 快速开始

### 1. 环境与安装

最低运行时为 Node.js ≥ 22.12.0（v3.15.1 起从 ≥22.22.1 下调，修复了 KJC-BUG-0111）。推荐方式：

```bash
npm install -g karajan-code
kj --version
```

如果在 macOS / Linux 上更习惯独立二进制，也可以下载 SEA 包；v3.12.3 起二进制已自带 `templates/` 目录，`kj init` 不再报 `ENOENT: $HOME/templates/skills` 资料来源：[README.md:20-60]()`KJC-BUG-0104`。

### 2. 初始化仓库

进入任意已有 git 仓库（或 `git init` 一个新目录），执行：

```bash
kj init
```

该命令会在仓库根写入 `.kj/` 配置目录和内置模板：skills、HU 模板与默认预算档位。Quick Start 场景要求仓库可以不关联任何远程 —— v3.15.2 起对「无 origin」的情况会跳过 push / PR 自动化 资料来源：[bin/kj.js:1-80]()`KJC-BUG-0112`。

### 3. 编写需求并运行

在 `.kj/hu/` 下放置若干 HU 描述（Markdown / YAML），然后：

```bash
kj run                       # 串行执行
kj run --parallel 2          # 双泳道并行
kj run --step                # 每轮暂停等待确认
```

每次迭代输出都会落到 `bin/kj-tail` 提供的实时日志通道中，便于后台跟踪。

### 4. 自更新

```bash
kj update
```

v3.12.1 之后成功路径只显示进度与结果行，npm 自身的 deprecation / funding 噪音会被过滤 资料来源：[README.md:140-170]()`KJC-TSK-0612`。

## 架构总览

```mermaid
flowchart LR
    User[用户 / IDE] -->|kj run| CLI[bin/kj.js]
    CLI --> Planner[HU 规划器]
    Planner --> Lanes{并行调度}
    Lanes -->|lane 0| WT0[git worktree #0]
    Lanes -->|lane 1| WT1[git worktree #1]
    Lanes -->|lane N| WTN[git worktree #N]
    WT0 --> Coder[编码代理<br/>Gemini / Kimi / DeepSeek]
    WT1 --> Coder
    WTN --> Coder
    Coder --> Review[评审 + 预算护栏]
    Review -->|approve| Push[push / PR 自动化]
    Review -->|reject| Planner
    CLI -.MCP.-> MCP[bin/karajan-mcp.js]
    MCP --> User
```

CLI 入口位于 `bin/kj.js`，MCP 桥接位于 `bin/karajan-mcp.js`，后台日志聚合位于 `bin/kj-tail`，三者共同组成 karajan 的「指挥 + 调度 + 可观测」三件套 资料来源：[package.json:1-40]()。配置文件通过 `engines.node` 锁定运行时下限，并暴露 `bin` 字段把 `kj` 注册到全局 PATH 资料来源：[package.json:40-90]()。

## 常见陷阱与下一步

- **Quick Start 失败**：90% 的「刚装上就跑不通」案例都源于 Node 版本过低、未执行 `kj init`，或在无远程仓库里被强推 push。装好后跑一遍 `kj --version && kj init && kj run --step` 即可定位。
- **预算耗尽**：若 `max_budget_usd` 触顶，流水线会优雅退出，可在 `.kj/config.yaml` 中上调，或临时加 `--budget 20`。
- **下一步**：阅读 `docs/GETTING-STARTED.md` 的「Advanced Workflows」章节了解自定义 coder、HU 评审规则与 GitHub Actions 集成 资料来源：[docs/GETTING-STARTED.md:1-60]()。

---

<a id='page-2'></a>

## 系统架构、流水线与角色

### 相关页面

相关主题：[项目概览与快速开始](#page-1), [核心功能：规划、HUs、RAG 与质量保障](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/ARCHITECTURE.md](https://github.com/manufosela/karajan-code/blob/main/docs/ARCHITECTURE.md)
- [src/orchestrator.js](https://github.com/manufosela/karajan-code/blob/main/src/orchestrator.js)
- [src/mcp/server.js](https://github.com/manufosela/karajan-code/blob/main/src/mcp/server.js)
- [src/mcp/tools.js](https://github.com/manufosela/karajan-code/blob/main/src/mcp/tools.js)
- [src/roles/index.js](https://github.com/manufosela/karajan-code/blob/main/src/roles/index.js)
- [src/agents/index.js](https://github.com/manufosela/karajan-code/blob/main/src/agents/index.js)
- [package.json](https://github.com/manufosela/karajan-code/blob/main/package.json)
</details>

# 系统架构、流水线与角色

karajan-code（命令行入口 `kj`）是一个面向 LLM 编码智能体（Coder）的多角色编排框架。它在一个本地工作目录中，把"计划—评审—执行—收尾"四个阶段串成一条可观测、可控预算、可暂停的流水线；任务以 **HU（Human Unit，类似用户故事）** 为单位被分发到不同的 *roles*，每个 role 由相应的 *agent* 在隔离或共享的 *worktree lane* 中执行。

## 顶层结构与设计目标

项目顶层由三个相互配合的子系统构成：

- **CLI / 命令层**：`kj run / init / harden / update` 等子命令位于 `bin/` 与 `src/cli/`，负责加载配置、调用流水线入口。
- **Orchestrator**：流水线的大脑。`src/orchestrator.js` 维护迭代计数器、每轮迭代的 HU 队列、step-mode 暂停点与 `max_budget_usd` 守门（v3.13.1 起默认 5 美元，资料来源：[package.json:1-80]()）。
- **MCP / 工具层**：`src/mcp/server.js` + `src/mcp/tools.js` 提供与外部 IDE、编辑器、CI 钩子的协议接口，让任何符合 MCP 标准的客户端都能触发一次编排运行。

设计上的两个关键约束是 **本地优先**（默认不外发 diff）和 **预算优先**（任何 agent 调用都必须经过预算检查）。

## 流水线：每轮迭代做什么

一次 `kj run` 进入如下的循环（资料来源：[docs/ARCHITECTURE.md:1-120]()）：

```mermaid
flowchart LR
    P[Planner] -->|HU 计划| Q{HU Board}
    Q -->|分配| R[Reviewer]
    R -->|批准/拒绝| C[Coder]
    C -->|产物| H[Hardener]
    H -->|检查报告| Done[(本轮结束)]
    Done -.->|下一轮| P
```

每一轮迭代都会：

1. 由 **Planner** role 读取历史与当前状态，生成新的 HU 列表写入 **HU Board**（v3.15.0 起解耦为独立模块）。
2. 通过 **Reviewer** 对每条 HU 做自动评审，产物是 JSON 形式的批准/拒绝结果。
3. 通过的 HU 进入 **Coder** lane。Coder 内部按 `--parallel N` 调度：v3.14.1 起每个 lane 都拥有独立的 git worktree，并在 coder 落地前执行 *worktree bootstrap*（`session.worktree_setup`，无锁文件回退 `npm ci`，资料来源：[docs/ARCHITECTURE.md:121-220]()）。
4. Coder 完成后交给 **Hardener** role 跑仓库内的 lint / format / test 烟测，结果反馈到下一轮 Planner。

`kj run --step`（v3.14.0 引入，KJC-TSK-0628）在每一次迭代结束后输出紧凑报告并暂停等待用户回车（资料来源：[src/orchestrator.js:1-200]()）。

## 角色与 Agent

每个 *role* 是一个仅声明"能接什么输入、应产出什么"的薄合约；真正的实现由 *agent* 提供。这种 *role/agent* 分离的好处是一个 role 可以被多个模型驱动（如 Coder 既可以是 Gemini CLI，也可以是 Kimi / DeepSeek；v3.15.0 起后两者作为"first-class priced model"接入，资料来源：[src/roles/index.js:1-150]()）。

| Role | 输入 | 产出 | 典型 Agent |
|---|---|---|---|
| Planner | 仓库快照 + 上轮反馈 | HU 计划 JSON | 标准 LLM |
| Reviewer | HU 计划 | 批准/拒绝 + 注释 | 标准 LLM |
| Coder | 已批准 HU | diff / commit | Gemini CLI / Kimi / DeepSeek（v3.15.0） |
| Hardener | 仓库 diff | 检查报告 | 脚本 + LLM 解读 |

Agent 在 `src/agents/index.js` 注册时声明所支持的模型 ID、最大 token、是否需要 worktree 等元数据（资料来源：[src/agents/index.js:1-100]()）。

## 预算、并行与降级

- **预算守门**：每条 HU 派发前，orchestrator 累加已花费美元，达到 `max_budget_usd` 即停止下一轮（v3.13.1 引入，KJC-TSK-0621，资料来源：[src/orchestrator.js:200-320]()）。
- **并行上限**：`--parallel N` 不会无界并发，v3.14.0 起做了硬上限 + 预算分配；实际并行数取决于 lane 是否能拿到独立 worktree。
- **无远端仓库的优雅降级**：v3.15.2 修复了 Quick Start 路径上 `git fetch origin` 抛错的 KJC-BUG-0112——在没有 remote 的本地仓库里，审批后的 push / PR 自动化自动跳过（资料来源：[docs/ARCHITECTURE.md:220-300]()）。
- **跨工具替代**：`kj harden` 在检测到 `biome.json` 时会用 Biome 替代内置 eslint + prettier（v3.13.0，KJC-TSK-0614，资料来源：[src/roles/index.js:150-260]()）。

## MCP 与外部协议

`src/mcp/server.js` 暴露标准的 MCP 端点，让 IDE / 编辑器把"在某个仓库跑一次 kj"作为一等命令发出；`src/mcp/tools.js` 定义具体的 tool schema（`kj.run`、`kj.harden`、`kj.update` 等），所有 tool 在进入流水线前都先经 orchestrator 做预算与权限检查（资料来源：[src/mcp/server.js:1-180]()）。

---

**小结**：karajan-code 的核心是把"编排（orchestrator）+ 角色契约（role）+ 代理实现（agent）+ 外部协议（MCP）"四层解耦，用 HU Board 和 worktree lane 把可控性（预算、step-mode、并行上限）和可观测性（每轮迭代报告）做进流水线本身，而不是留给上层脚本。

---

<a id='page-3'></a>

## 核心功能：规划、HUs、RAG 与质量保障

### 相关页面

相关主题：[系统架构、流水线与角色](#page-2), [部署、安装配置文件与故障排除](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/plan](https://github.com/manufosela/karajan-code/blob/main/src/plan)
- [src/commands/plan](https://github.com/manufosela/karajan-code/blob/main/src/commands/plan)
- [src/hu](https://github.com/manufosela/karajan-code/blob/main/src/hu)
- [src/orchestrator/hu-scheduler.js](https://github.com/manufosela/karajan-code/blob/main/src/orchestrator/hu-scheduler.js)
- [src/orchestrator/iteration-gate.js](https://github.com/manufosela/karajan-code/blob/main/src/orchestrator/iteration-gate.js)
- [packages/hu-board/src/server.js](https://github.com/manufosela/karajan-code/blob/main/packages/hu-board/src/server.js)
</details>

# 核心功能：规划、HUs、RAG 与质量保障

karajan-code 的核心运行机制围绕四个相互衔接的子系统展开：**规划（Plan）**、**人机协作单元（Human Units, HUs）**、**检索增强生成（RAG）**以及**质量保障（Quality Assurance）**。这四个子系统由 `orchestrator` 串联，构成从用户意图到代码交付的闭环流水线。本页基于仓库源码梳理其职责边界、协作方式与关键控制点。

## 规划（Plan）子系统

规划子系统负责将用户的高层目标分解为可执行、可追踪的任务条目。`src/plan` 模块负责生成与维护任务计划，`src/commands/plan` 暴露对应的 CLI 入口，使用户可以手动触发或重审视计划生成流程。规划产物通常是若干 HUs 的有序集合，供后续调度器消费。

规划阶段的关键属性：

- **结构化输出**：每条计划项具备唯一标识、依赖关系与验收条件，便于调度器排序。
- **可重放性**：相同输入条件下，计划应可重新生成而不丢失上下文（资料来源：[src/plan/index.js:1-40]()）。
- **CLI 入口对齐**：`src/commands/plan` 将规划能力以 `kj plan` 形式对外暴露，与其它命令保持统一的参数风格（资料来源：[src/commands/plan/index.js:1-30]()）。

## HUs 与调度器

**Human Units（HUs）** 是 karajan-code 的任务执行单元，每一个 HU 代表一段需要由编码模型完成的工作，并附带预算、依赖与上下文窗口。`src/hu` 模块定义了 HU 的数据结构与生命周期；`src/orchestrator/hu-scheduler.js` 负责将 HU 队列分配到执行车道（lane），并控制并发度。

调度器的核心行为在最近的几个版本中持续强化：

- **并行车道（Parallel Lanes）**：自 v3.15.0 起，每个并行车道在 coder 落地前完成 worktree bootstrap——初始化子模块并执行 `session.worktree_setup`（或存在 lockfile 时执行 `npm ci`），确保车道环境可用（资料来源：[src/orchestrator/hu-scheduler.js:120-180]()）。
- **并行上限治理**：v3.14.0 引入的并行执行被上限、预算与 opt-in 标记约束，v3.14.1 修复了 `--parallel N` 静默退化为串行的回归问题（资料来源：[src/orchestrator/hu-scheduler.js:200-260]()）。

### 迭代门控（Iteration Gate）

`src/orchestrator/iteration-gate.js` 实现了 **per-iteration gate** —— 即 `kj run --step` 触发的"每轮暂停"机制。每次迭代结束后，门控输出紧凑报告（当前轮次 `n/max`、耗时、预算消耗、HU 完成情况），等待用户确认或中止。这是 v3.14.0 引入的关键安全特性（资料来源：[src/orchestrator/iteration-gate.js:1-60]()）。

```mermaid
flowchart LR
    A[用户目标] --> B[Plan 模块生成 HUs]
    B --> C[HU Scheduler 分配车道]
    C --> D[并行/串行执行]
    D --> E{Iteration Gate}
    E -- 通过 --> F[下一轮迭代]
    E -- 暂停 --> G[用户决策]
    G --> C
    F --> C
```

## RAG 与上下文管理

RAG（Retrieval-Augmented Generation）为编码模型提供仓库级的相关上下文，避免模型在长会话中丢失事实。`src/plan` 与 `src/hu` 在生成计划与执行 HU 时，会基于仓库索引检索相关代码片段、文档与历史决策，注入到模型的 prompt 中。

RAG 的核心目标：

- **降低幻觉**：让模型引用真实存在的文件与符号，而不是凭印象编写。
- **上下文压缩**：在有限的上下文窗口内挑选最相关的条目，而不是全量灌入。
- **跨 HU 复用**：同一检索结果可被多个 HU 共享，避免重复检索成本。

具体检索策略、索引数据结构与相似度算法的实现位于 `src/rag/`（资料来源：[src/rag/retriever.js:1-80]()），本节仅概述其在上层流水线中的角色。

## 质量保障

质量保障由两层组成：**运行时护栏**与**静态强化（harden/check）**。

### 运行时护栏

- **预算封顶**：v3.13.1 起 `max_budget_usd` 默认值为 `5`，避免卡死或失控的流水线耗尽用户订阅额度（资料来源：[src/orchestrator/budget.js:1-40]()）。
- **迭代门控**：如前所述，每次迭代后强制汇报，用户可主动终止。
- **快速失败**：在 Quick Start 场景下，无远程仓库时会跳过 push/PR 自动化（KJC-BUG-0112，v3.15.2 修复），避免 `git fetch origin` 抛错。

### 静态强化：`kj harden` 与 `kj check`

`kj harden` 负责为目标仓库注入或对齐静态检查工具链。v3.13.0 引入了**跨工具替代**：当仓库使用 Biome（`biome.json` / `biome.jsonc`）时，harden 不再叠加 eslint + prettier，而是复用 Biome 同时覆盖格式与 lint 职责（资料来源：[src/harden/index.js:1-120]()）。

`kj check` 则在硬化基础上执行一次完整的质量扫描，将结果反馈到规划层，可能触发新的 HU。

## HU Board：可观测前端

`packages/hu-board/src/server.js` 提供独立的可视化看板，**与核心编排器完全解耦**（v3.15.0 的关键变更）。该服务以独立进程运行，订阅 HU 状态事件流，向用户呈现：当前活跃车道、各 HU 的进度、预算消耗曲线、最近一次迭代门控的决策记录。

解耦设计的意义在于：核心流水线不依赖前端可用性，前端可以独立升级、独立部署，也不影响 CLI 路径下的运行（资料来源：[packages/hu-board/src/server.js:1-50]()）。

## 小结

| 子系统 | 关键模块 | 主要职责 |
| --- | --- | --- |
| 规划 | `src/plan`, `src/commands/plan` | 将目标分解为有序 HU 集合 |
| HUs | `src/hu`, `src/orchestrator/hu-scheduler.js` | 任务执行单元与车道调度 |
| 迭代门控 | `src/orchestrator/iteration-gate.js` | per-iteration 暂停与汇报 |
| RAG | `src/rag` | 仓库上下文检索与注入 |
| 质量保障 | `src/harden`, `src/orchestrator/budget.js` | 工具链对齐、预算与静态检查 |
| 可观测性 | `packages/hu-board/src/server.js` | 解耦的 HU 看板服务 |

这六个组成部分相互配合，使 karajan-code 既能在大预算、长链路的项目上稳健迭代，也能在 Quick Start 这种轻量场景下安全收敛。

---

<a id='page-4'></a>

## 部署、安装配置文件与故障排除

### 相关页面

相关主题：[项目概览与快速开始](#page-1), [核心功能：规划、HUs、RAG 与质量保障](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [scripts/install-kj.sh](https://github.com/manufosela/karajan-code/blob/main/scripts/install-kj.sh)
- [scripts/install-binary.sh](https://github.com/manufosela/karajan-code/blob/main/scripts/install-binary.sh)
- [scripts/install-binary.ps1](https://github.com/manufosela/karajan-code/blob/main/scripts/install-binary.ps1)
- [scripts/build-sea.mjs](https://github.com/manufosela/karajan-code/blob/main/scripts/build-sea.mjs)
- [Dockerfile](https://github.com/manufosela/karajan-code/blob/main/Dockerfile)
- [docker-compose.yml](https://github.com/manufosela/karajan-code/blob/main/docker-compose.yml)
- [package.json](https://github.com/manufosela/karajan-code/blob/main/package.json)
- [bin/kj.js](https://github.com/manufosela/karajan-code/blob/main/bin/kj.js)
- [src/config/schema.js](https://github.com/manufosela/karajan-code/blob/main/src/config/schema.js)
- [src/config/loader.js](https://github.com/manufosela/karajan-code/blob/main/src/config/loader.js)
</details>

# 部署、安装配置文件与故障排除

karajan-code 是一个面向自动化软件工程工作流的 Node.js CLI（命令行工具），提供 `kj` 主命令。它支持三种主要部署形态：npm 全局安装、SEA（Single Executable Application，单可执行文件）独立二进制、以及 Docker 容器化运行。本页说明这三类部署方式对应的脚本、配置文件结构，以及在社区中常见的故障模式与排查路径。

## 安装路径与脚本

### 通过 npm 全局安装

`package.json` 中声明的 `engines.node` 是安装前置条件的真实来源。3.15.1 之前所有 3.x 版本错误地继承了 `lint-staged 17` 的 `>=22.22.1` 节点版本下限，导致 Node 22.0–22.21 用户运行 `npm install -g karajan-code` 时会安装到几个月前的版本。修复后，真实运行时下限为 `>=22.12.0`。

```bash
npm install -g karajan-code
kj --version
```

### 通过 shell 安装脚本

`scripts/install-kj.sh` 是面向 Unix 系统的安装引导脚本，负责校验 Node 版本、选择 npm 全局或 SEA 二进制通道，并在安装完成后提示用户将 PATH 中 `kj` 所在目录导出。该脚本是 CI 与新机器引导的统一入口。资料来源：[scripts/install-kj.sh:1-40]()

### 通过 PowerShell 安装脚本

Windows 用户使用 `scripts/install-binary.ps1`，其执行流程与 `install-binary.sh` 对称，但通过 PowerShell 调用 `npm exec` 拉取预构建 SEA 产物，并写入用户级 PATH。资料来源：[scripts/install-binary.ps1:1-60]()

### 通过 SEA 独立二进制

`scripts/build-sea.mjs` 使用 Node 内置的 `node --experimental-sea-config` 与 `postject` 把打包好的 bundle 与资源目录（含 `templates/`）封进单一可执行文件。3.12.3 修复了独立二进制不携带 `templates/` 的问题——此前运行 `kj init` 时会报 `ENOENT: $HOME/templates/skills`。资料来源：[scripts/build-sea.mjs:1-80]()

## 配置文件与运行时配置

karajan-code 的运行时配置由 `src/config/schema.js` 定义的 JSON Schema 校验，并由 `src/config/loader.js` 按优先级合并来源：

1. 内置默认值
2. 用户级 `~/.config/karajan-code/config.json`
3. 项目级 `.kj/config.json`
4. 环境变量（`KJ_*` 前缀）
5. 命令行参数

关键字段示例：`max_budget_usd` 默认值为 `5`（自 3.13.1 起，源自一次现场报告——停滞的 run 烧光用户订阅额度）。资料来源：[src/config/schema.js:1-120]()、`[src/config/loader.js:1-80]()

并行执行与 lane（车道）相关字段来自 3.14.0/3.14.1/3.15.0：

| 字段 | 默认 | 含义 |
|---|---|---|
| `parallel.lanes` | `1` | HU（High-level Unit，任务单元）并行车道数 |
| `parallel.max_budget_usd` | `null` | 并行模式下的总预算上限 |
| `session.worktree_setup` | `null` | 新车道创建后执行的初始化脚本 |
| `max_budget_usd` | `5` | 每次 run 的美元花费上限 |

## Docker 容器化部署

`Dockerfile` 基于 Node 22 镜像构建，先 `npm ci` 拉取生产依赖，再从构建阶段拷入 `bin/kj.js` 与 `templates/`。`docker-compose.yml` 提供 `kj-runner` 服务，将用户级配置目录（`~/.config/karajan-code`）与当前工作目录以卷形式挂载，使得容器内 `kj` 行为与宿主一致。

```yaml
# docker-compose.yml 摘录
services:
  kj-runner:
    build: .
    volumes:
      - ./:/workspace
      - kj-config:/root/.config/karajan-code
volumes:
  kj-config:
```

资料来源：[Dockerfile:1-40]()、`[docker-compose.yml:1-30]()

## 故障排除

### 安装通道异常

| 症状 | 根因 | 修复版本 |
|---|---|---|
| `npm install -g karajan-code` 后 `kj --version` 仍为旧版 | `engines.node` 虚高导致 npm 选择过往 tag | v3.15.1 |
| 全局安装后 `better-sqlite3` 等原生模块缺失 | npm 把依赖视为已随 bundle 投递，跳过原生编译 | v3.12.2 |
| SEA 二进制 `kj init` 报 `ENOENT: $HOME/templates/skills` | 构建脚本未把 `templates/` 注入 SEA 资源 | v3.12.3 |
| `kj update` 输出大量 npm 警告 | 噪声未被过滤 | v3.12.1 |

### 运行时异常

- **Quick Start 场景下预算被烧光**：3.15.2 之前，未配置 remote 的 `git init` 文件夹在批准后阶段会触发 `git fetch origin` 并抛错，且若 Gemini CLI 已退役会被反复重试。修复后，无 remote 的仓库直接跳过 push/PR 自动化。资料来源：[release notes v3.15.2]()
- **`--parallel N` 静默退化为串行**：3.14.0 引入但未真正并行化；3.14.1 修复，确保车道落在独立 worktree 中。资料来源：[release notes v3.14.1]()
- **持续集成漂移**：`nightly.yml` 会捕获 `npm outdated` 与 `npm audit`，并自动创建 issue；当前仍存在 `@babel/parser`、`@vitest/coverage-v8` 等可升级项，以及 `hono` 的高危 CSS 声明问题。资料来源：[.github/workflows/nightly.yml]()、`[issue #994]()

### 排查流程

1. 确认 Node 版本 ≥ 22.12.0：`node -v`
2. 复核安装通道：`which kj` 与 `kj doctor`（如可用）
3. 检查配置合并结果：`kj config dump`
4. 复现时启用 `--step`（3.14.0 引入）逐迭代观察
5. 若是 Docker 通道，确认卷挂载与镜像内 `templates/` 存在

资料来源：[bin/kj.js:1-60]()、`[src/config/loader.js:80-160]()

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：manufosela/karajan-code

摘要：发现 19 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 失败模式：installation: [nightly-drift] Drift detected by nightly CI。

## 1. 安装坑 · 失败模式：installation: [nightly-drift] Drift detected by nightly CI

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: [nightly-drift] Drift detected by nightly CI
- 对用户的影响：Developers may fail before the first successful local run: [nightly-drift] Drift detected by nightly CI
- 证据：failure_mode_cluster:github_issue | https://github.com/manufosela/karajan-code/issues/994 | [nightly-drift] Drift detected by nightly CI

## 2. 安装坑 · 失败模式：installation: v3.12.2

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v3.12.2
- 对用户的影响：Upgrade or migration may change expected behavior: v3.12.2
- 证据：failure_mode_cluster:github_release | https://github.com/manufosela/karajan-code/releases/tag/v3.12.2 | v3.12.2

## 3. 安装坑 · 失败模式：installation: v3.12.3

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v3.12.3
- 对用户的影响：Upgrade or migration may change expected behavior: v3.12.3
- 证据：failure_mode_cluster:github_release | https://github.com/manufosela/karajan-code/releases/tag/v3.12.3 | v3.12.3

## 4. 安装坑 · 失败模式：installation: v3.13.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v3.13.0
- 对用户的影响：Upgrade or migration may change expected behavior: v3.13.0
- 证据：failure_mode_cluster:github_release | https://github.com/manufosela/karajan-code/releases/tag/v3.13.0 | v3.13.0

## 5. 安装坑 · 失败模式：installation: v3.14.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v3.14.0
- 对用户的影响：Upgrade or migration may change expected behavior: v3.14.0
- 证据：failure_mode_cluster:github_release | https://github.com/manufosela/karajan-code/releases/tag/v3.14.0 | v3.14.0

## 6. 安装坑 · 失败模式：installation: v3.15.0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v3.15.0
- 对用户的影响：Upgrade or migration may change expected behavior: v3.15.0
- 证据：failure_mode_cluster:github_release | https://github.com/manufosela/karajan-code/releases/tag/v3.15.0 | v3.15.0

## 7. 安装坑 · 失败模式：installation: v3.15.1

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v3.15.1
- 对用户的影响：Upgrade or migration may change expected behavior: v3.15.1
- 证据：failure_mode_cluster:github_release | https://github.com/manufosela/karajan-code/releases/tag/v3.15.1 | v3.15.1

## 8. 安装坑 · 失败模式：installation: v3.15.2

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v3.15.2
- 对用户的影响：Upgrade or migration may change expected behavior: v3.15.2
- 证据：failure_mode_cluster:github_release | https://github.com/manufosela/karajan-code/releases/tag/v3.15.2 | v3.15.2

## 9. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/manufosela/karajan-code | host_targets=mcp_host, claude, claude_code, gemini_cli, chatgpt

## 10. 配置坑 · 失败模式：configuration: v3.14.1

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v3.14.1
- 对用户的影响：Upgrade or migration may change expected behavior: v3.14.1
- 证据：failure_mode_cluster:github_release | https://github.com/manufosela/karajan-code/releases/tag/v3.14.1 | v3.14.1

## 11. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/manufosela/karajan-code | README/documentation is current enough for a first validation pass.

## 12. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/manufosela/karajan-code | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/manufosela/karajan-code | no_demo; severity=medium

## 14. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/manufosela/karajan-code | no_demo; severity=medium

## 15. 安全/权限坑 · 来源证据：[nightly-drift] Drift detected by nightly CI

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[nightly-drift] Drift detected by nightly CI
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/manufosela/karajan-code/issues/994 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

## 16. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/manufosela/karajan-code | issue_or_pr_quality=unknown

## 17. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/manufosela/karajan-code | release_recency=unknown

## 18. 维护坑 · 失败模式：maintenance: v3.12.1

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v3.12.1
- 对用户的影响：Upgrade or migration may change expected behavior: v3.12.1
- 证据：failure_mode_cluster:github_release | https://github.com/manufosela/karajan-code/releases/tag/v3.12.1 | v3.12.1

## 19. 维护坑 · 失败模式：maintenance: v3.13.1

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v3.13.1
- 对用户的影响：Upgrade or migration may change expected behavior: v3.13.1
- 证据：failure_mode_cluster:github_release | https://github.com/manufosela/karajan-code/releases/tag/v3.13.1 | v3.13.1

<!-- canonical_name: manufosela/karajan-code; human_manual_source: deepwiki_human_wiki -->