karajan-code 项目说明书

Doramagic 项目包 · 项目说明书

karajan-code 项目

本地多智能体编程编排工具，内置 22 个流水线角色，支持 TDD 强制约束、SonarQube 集成与自动化代码审查，兼容 Claude、Codex、Gemini、OpenCode 与 Aider，自带 MCP 服务器，无需额外 API 费用，直接复用你已有的订阅。

项目概览与快速开始

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

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 1. 环境与安装

继续阅读本节完整说明和来源证据。

章节 2. 初始化仓库

继续阅读本节完整说明和来源证据。

章节 3. 编写需求并运行

继续阅读本节完整说明和来源证据。

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-90KJC-TSK-0630。该特性在 v3.14.1 之前曾静默退化为串行执行，已修复。
步进模式：kj run --step 在每一次迭代后暂停并打印紧凑报告，便于人工监督资料来源：README.md:90-110KJC-TSK-0628。
预算护栏：每次运行默认 max_budget_usd = 5，防止卡死循环烧光订阅额度资料来源：package.json:30-60KJC-TSK-0621。
工具治理：kj harden 会识别仓库已有的格式化 / 静态检查工具（如 Biome），避免重复植入 eslint + prettier 资料来源：README.md:110-140KJC-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）。推荐方式：

npm install -g karajan-code
kj --version

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

2. 初始化仓库

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

kj init

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

3. 编写需求并运行

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

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

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

4. 自更新

kj update

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

架构总览

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。

来源：https://github.com/manufosela/karajan-code / 项目说明书

系统架构、流水线与角色

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

章节 相关页面

继续阅读本节完整说明和来源证据。

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）：

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

每一轮迭代都会：

由 Planner role 读取历史与当前状态，生成新的 HU 列表写入 HU Board（v3.15.0 起解耦为独立模块）。
通过 Reviewer 对每条 HU 做自动评审，产物是 JSON 形式的批准/拒绝结果。
通过的 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）。
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）。

来源：https://github.com/manufosela/karajan-code / 项目说明书

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

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

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 迭代门控（Iteration Gate）

继续阅读本节完整说明和来源证据。

章节 运行时护栏

继续阅读本节完整说明和来源证据。

章节 静态强化：kj harden 与 kj check

继续阅读本节完整说明和来源证据。

规划（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）。

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 这种轻量场景下安全收敛。

来源：https://github.com/manufosela/karajan-code / 项目说明书

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

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

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 通过 npm 全局安装

继续阅读本节完整说明和来源证据。

章节 通过 shell 安装脚本

继续阅读本节完整说明和来源证据。

章节 通过 PowerShell 安装脚本

继续阅读本节完整说明和来源证据。

安装路径与脚本

通过 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。

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 按优先级合并来源：

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

关键字段示例：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 行为与宿主一致。

# 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

排查流程

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

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

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

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

medium 失败模式：installation: [nightly-drift] Drift detected by nightly CI

Developers may fail before the first successful local run: [nightly-drift] Drift detected by nightly CI

medium 失败模式：installation: v3.12.2

Upgrade or migration may change expected behavior: v3.12.2

medium 失败模式：installation: v3.12.3

Upgrade or migration may change expected behavior: v3.12.3

medium 失败模式：installation: v3.13.0

Upgrade or migration may change expected behavior: v3.13.0

Pitfall Log / 踩坑日志

项目：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

来源：Doramagic 发现、验证与编译记录