java-code-reviewer

name	java-code-reviewer
description	Java代码审查、代码检查、发现Bug和安全漏洞、性能优化、架构评估、技术债挖掘。15维度全面审查，支持fast/standard/deep/security模式和增量/存量审查。

用途

当用户要求审查Java代码、代码检查、发现Bug、安全漏洞、性能问题、潜在风险、技术债挖掘、安全检查、性能优化、架构评估时使用此技能。

常见触发场景：

• "帮我审查这个项目"
• "检查一下代码有没有问题"
• "发现潜在Bug和安全漏洞"
• "评估代码质量和架构"
• "挖掘技术债和改进点"
• "代码安全检查"
• "性能优化建议"

快速启动模式

适用于定时任务、自动化脚本、CI/CD 集成等无需人工交互的场景。用户在调用时通过 -- 参数直接传入全部审查配置，跳过交互式确认，直接执行审查。

模式判定

检测规则：如果用户输入中包含 --mode 参数，则进入快速启动模式；否则进入交互式模式（默认）。

参数规范

参数	是否必填	取值范围	说明
--mode	必填	fast / standard / deep / security	审查模式
--type	必填	incremental / stock	审查类型（增量/存量）
--scope	条件必填	见下方规则	审查范围
--branch	可选	任意分支名	审查分支，默认当前分支
--upload	可选	no / doc / bitable / both	飞书上传选项，默认 no（不上传）

--scope 条件必填规则：

--type 值	--scope 是否必填	合法值	默认值
incremental	必填	正整数（提交次数），如 5	无，缺则报错
stock + 多模块项目	必填	full 或逗号分隔的 Maven 模块名称，如 user-service,order-service	无，缺则报错
stock + 单模块项目	可选	full（唯一合法值）	自动设为 full

参数映射

快速启动参数与交互式变量的映射关系：

快速启动参数	映射变量	值转换
--mode fast	REVIEW_MODE=fast	直接使用
--type incremental	REVIEW_TYPE=增量审查	转换为中文
--type stock	REVIEW_TYPE=存量审查	转换为中文
--scope 5（incremental）	REVIEW_SCOPE=最近5次提交	转换为中文
--scope full（stock）	REVIEW_SCOPE=全量代码	转换为中文
--scope user-service,order-service	REVIEW_SCOPE=user-service,order-service	直接使用
--branch develop	TARGET_BRANCH=develop	直接使用
--upload no	FEISHU_UPLOAD_OPTION=仅显示报告	转换为中文
--upload doc	FEISHU_UPLOAD_OPTION=上传到云文档	转换为中文
--upload bitable	FEISHU_UPLOAD_OPTION=上传到多维表格	转换为中文
--upload both	FEISHU_UPLOAD_OPTION=同时上传两者	转换为中文
未提供 --upload	FEISHU_UPLOAD_OPTION=仅显示报告	使用默认值

校验规则

1. 必填参数校验：--mode 和 --type 必须存在，缺失任何一个立即报错终止
2. 参数值校验：每个参数的值必须在合法取值范围内，不合法立即报错
3. 条件必填校验：根据 --type 的值校验 --scope 是否缺失
4. 分支存在性校验：--branch 指定的分支如果不存在，报错并列出可用分支
5. 模块存在性校验：当 --type stock --scope 为具体模块名（非 full）时，校验每个模块是否存在于预扫描结果的 MODULE: 行中；不存在的模块报错并列出可用模块
6. lark-cli 校验：如果 --upload 不是 no 但未检测到 lark-cli，警告并降级为 仅显示报告

校验失败时的输出格式：

❌ 快速启动参数校验失败

缺少必填参数：
  - --mode: 审查模式（fast/standard/deep/security）
  - --scope: 审查范围（增量审查时为提交次数，存量审查多模块时为 Maven 模块名称）

正确格式示例：
  帮我审查 /path/to/project --mode fast --type incremental --scope 5
  帮我审查 /path/to/project --mode standard --type stock --scope full --upload doc

请补充缺失参数后重新调用。

快速启动模式下的执行流程

预扫描阶段                  → 正常执行（项目识别 + 分支探测 + 项目扫描 + lark-cli 检测）
参数校验                    → 校验所有必填参数，失败则终止
交互式确认                  → ⏭️ 完全跳过
代码审查阶段：代码审查            → 直接执行（不展示执行计划确认）

启动提示（快速启动模式专用）：

校验通过后，输出以下提示后立即调用子agent：

🚀 快速启动模式 — 正在启动独立代码审查子代理...

📋 任务配置：{REVIEW_MODE} 模式 · {REVIEW_TYPE} · {REVIEW_SCOPE}
🌿 审查分支：{TARGET_BRANCH 或 CURRENT_BRANCH}
📤 飞书上传：{FEISHU_UPLOAD_OPTION}
⏱️ 预估耗时：{预估时间}
📌 子代理将独立执行完整审查流程，完成后自动返回结果。

注意：快速启动模式不输出「💡 温馨提示」和「执行计划确认」，因为调用方是自动化脚本/定时任务。

快速启动调用示例

# 增量审查 — 最近5次提交，快速扫雷
帮我审查 /path/to/project --mode fast --type incremental --scope 5

# 存量审查 — 全量代码，标准模式，上传飞书云文档
帮我审查 /path/to/project --mode standard --type stock --scope full --upload doc

# 存量审查 — 指定模块，深度模式，同时上传飞书两者
帮我审查 /path/to/project --mode deep --type stock --scope user-service,order-service --upload both

# Git 仓库 + 指定分支 + 增量审查
帮我审查 https://github.com/org/repo.git --mode standard --type incremental --scope 3 --branch develop --upload bitable

# 定时任务场景（最简形式，增量快速扫雷，仅显示报告）
帮我审查 /path/to/project --mode fast --type incremental --scope 1

---

工作流程

模式判定（首先执行）

检测用户输入中是否包含 --mode 参数：

检测结果	执行路径
包含 --mode	→ 快速启动模式：执行预扫描 → 参数校验 → 直接跳到代码审查阶段
不包含 --mode	→ 交互式模式（默认）：执行预扫描 → 交互式确认（逐步确认）→ 代码审查阶段

---

预扫描阶段（自动执行，在第一次用户交互前全部完成）

目标：在用户等待期间，一次性完成项目识别、分支探测、项目扫描和 lark-cli 检测，收集所有后续交互所需的环境数据。

⚠️ 核心原则：此阶段所有脚本按顺序自动执行，不与用户交互，全部完成后统一输出预扫描摘要，然后进入交互阶段。

执行步骤

按以下顺序依次执行 4 个脚本：

步骤 1：项目识别

bash scripts/phase1-detect-project.sh "<用户输入的路径>"

脚本输出：

• PROJECT_DIR=<项目绝对路径>
• PROJECT_SOURCE=local|git-cache

步骤 2：分支探测

bash scripts/phase2-detect-branches.sh "$PROJECT_DIR"

脚本输出：

• IS_GIT_REPO=true/false
• CURRENT_BRANCH=<分支名>
• BRANCH: 分支名 | 提交日期 | 提交信息（本地分支列表）
• BRANCH_REMOTE: origin/分支名 | 提交日期 | 提交信息（远程分支列表）

步骤 3：项目扫描

bash scripts/phase3-project-scan.sh "$PROJECT_DIR"

脚本输出：

• PROJECT_TYPE=maven-single|maven-multi|gradle-single|gradle-multi|unknown
• MODULE:模块名|相对路径|Java文件数|代码行数
• 项目概况和模块树的可视化展示

步骤 4：lark-cli 检测

bash scripts/phase4-detect-lark-plugin.sh

脚本输出：

• LARK_PLUGIN_INSTALLED=true|false
• LARK_PLUGIN_NAME=lark-cli（仅当 LARK_PLUGIN_INSTALLED=true 时输出）

说明：飞书上传功能依赖 lark-cli 命令行工具及配套的 lark-doc（云文档）和 lark-base（多维表格）两个 skill。此处仅检测 lark-cli 是否安装，子 agent 执行上传时会自动调用对应的 skill。

预扫描摘要输出

4 个脚本全部执行完成后，必须向用户输出以下统一摘要（这是预扫描阶段的唯一输出，之后进入交互阶段）：

🔍 预扫描完成

📂 项目：{项目名称}
- 来源：{PROJECT_SOURCE 对应展示，本地路径 / Git仓库缓存}
- 路径：{PROJECT_DIR}
- 类型：{PROJECT_TYPE 展示名，如 Maven 单模块 / Gradle 多模块 / 未知}

🌿 Git：{IS_GIT_REPO=true 时显示}
- 当前分支：{CURRENT_BRANCH}
- 可用分支：{分支数量} 个{分支数 > 1 时显示"（需选择）"，否则显示"（自动使用）"}

📊 规模：
- Java 文件：{N} 个
- 代码行数：{M} 行
{多模块时追加以下行}
- 模块数量：{K} 个
- 模块列表：{模块1名称}({n1}类), {模块2名称}({n2}类), ...

🔌 lark-cli：{LARK_PLUGIN_INSTALLED=true 时显示 "✅ lark-cli 已安装" / false 时显示 "⚠️ 未安装"}

注意：

• 预扫描摘要是所有环境数据的统一展示，让用户在交互前对项目有全面了解
• 分支列表解析说明：BRANCH: 行为本地分支，BRANCH_REMOTE: 行为远程分支（需去掉 origin/ 前缀展示）
• 模块结构解析说明：MODULE: 行格式为 MODULE:模块名|相对路径|Java文件数|代码行数，主agent在交互步骤3（方案B）动态生成模块选项时，应解析这些行提取模块信息

---

交互式确认（通过文本选项交互）

🚫 工具禁用规则（最高优先级）：

• 禁止使用 AskUserQuestion 工具：交互式确认的所有步骤，绝对不允许调用 AskUserQuestion 工具
• 禁止使用任何结构化用户输入收集工具：所有选项必须以纯文本形式直接输出到聊天中，等待用户自由输入回复
• 唯一允许的输出方式：将选项文本作为普通聊天消息输出，输出后立即停止，等待用户在下一轮对话中回复
• 违反复核：每次准备输出交互选项前，先自检——"我是否正准备在一次回复中输出多个步骤的选项？"如果是，立即停止，只保留第一个步骤

⚠️ 严格单步执行规则（必须遵守）：

1. 一次只执行一个步骤：每次只输出当前步骤的选项文本，然后立即停止输出，等待用户回复。即使上一个步骤的回复确认和下一个步骤的选项，也必须在同一个回复中只出现一组选项
2. 禁止合并步骤：绝不允许在一次回复中同时展示多个步骤的选项（例如：不能在同一个回复中同时展示步骤1和步骤2的选项）
3. 收到用户回复后再进入下一步：只有处理完用户对当前步骤的回复后，才能继续到下一个步骤
4. 禁止跳过任何步骤：即使参数看起来已经明确，也必须逐个展示选项

正确做法：输出步骤1选项 → 等用户回复 → 处理回复 + 输出步骤2选项 → 等用户回复 → ... 错误做法：在一个回复中同时输出步骤1、2、3、4、5、6的所有选项 ← 绝对禁止

典型错误（必须避免）： ❌ 在一次回复中同时展示两个或多个步骤的选项：

📌 [审查范围] 请选择要审查的模块（可多选，用逗号分隔）
A) 全量代码 — 审查所有模块
B) user-service — ...
📌 [审查模式] 请选择审查模式
A) fast — 快速扫雷...
B) standard — 标准审查...

这种合并展示是绝对禁止的，无论任何理由。每组选项必须独占一个回复，等用户回答后再出现下一组。

每个步骤必须严格按照以下定义输出选项文本，不得自行增减选项或修改文案。

通用交互格式：

📌 [标题] 问题文本

A) 选项标签1 — 选项描述1
B) 选项标签2 — 选项描述2
...

请输入选项编号（如 A），或直接输入自定义内容：

通用解析规则：

• 不区分大小写（a=A, b=B）
• 多选用逗号分隔（A,C 或 a,c）
• 用户输入不匹配任何选项时，视为自定义输入
• 自定义输入需校验是否与当前问题相关且合理
• 校验失败时：提示输入无效，重新展示选项，最多重试 3 次，超过 3 次终止流程
• 校验失败提示格式：

  ⚠️ 输入无效，请输入选项编号（如 A）或输入与问题相关的有效内容：
  
  A) ... ...
  B) ... ...
  
  请重新选择：
  

步骤1：选择审查分支（条件步骤）

判断逻辑（基于预扫描阶段的 IS_GIT_REPO 和分支数量）：

条件	动作
快速启动模式且提供了 --branch	自动切换到指定分支，跳过交互
快速启动模式且未提供 --branch	跳过，自动使用当前分支
IS_GIT_REPO=false	跳过，非 Git 项目
仅有 1 个本地分支且无远程分支补充	跳过，自动使用当前分支
多个分支存在	必须询问（仅交互式模式）

仅输出以下选项文本，然后立即停止输出，等待用户输入：

📌 [选择分支] 检测到 Git 仓库（当前分支：{CURRENT_BRANCH}），请选择要审查的分支

A) {分支名1} (当前) — {提交日期} · {提交信息前30字}
B) {分支名2} — {提交日期} · {提交信息前30字}
...

请输入选项编号（如 A），或直接输入分支名：

变量赋值规则：

用户输入	变量赋值
A（选择第一个选项）	TARGET_BRANCH={分支名1}
B（选择第二个选项）	TARGET_BRANCH={分支名2}
自定义分支名（如 feature/login）	TARGET_BRANCH=feature/login

注意：

• 选项列表从预扫描阶段的 BRANCH: / BRANCH_REMOTE: 行中动态生成，最多展示 8 个
• 当前分支标记 (当前) 放在标签末尾
• 远程分支的标签使用去掉远程前缀的短名称（如 origin/feature-x → feature-x），但 TARGET_BRANCH 记录带前缀的完整名（如 origin/feature-x），供切换时使用
• 自定义输入需校验是否为合理的分支名（非空、非乱码），校验失败时重新展示选项

输入校验规则：

• 不区分大小写（a=A, b=B）
• 用户输入不匹配任何选项时，视为自定义分支名
• 无效输入（空值、乱码、与分支选择无关的内容）：提示重新输入，最多重试 3 次

用户选择分支后，自动执行切换：

如果选择的不是当前分支，执行切换脚本：

bash scripts/phase2-switch-branch.sh "$PROJECT_DIR" "{TARGET_BRANCH}" "$CURRENT_BRANCH" "$PROJECT_SOURCE"

脚本会自动判断分支类型（本地/远程）并执行相应切换操作。

本地项目保护：

• 当 PROJECT_SOURCE=local 且工作区存在未提交改动时，脚本不会切换分支
• 此时会提示用户并继续使用当前分支审查，避免影响本地工作区
• 当 PROJECT_SOURCE=git-cache 时，仍允许自动切换分支

切换失败时的处理：

1. 脚本会输出警告：⚠️ 分支切换失败，将使用当前分支 {CURRENT_BRANCH} 继续审查
2. 继续执行后续流程，不阻塞
3. 在执行计划确认环节（步骤6）中明确显示实际使用的分支

⚠️ 此步骤结束后必须立即停止输出，等待用户回复后再进入下一步骤。

---

步骤2：选择审查类型

仅输出以下选项文本，然后立即停止输出，等待用户输入：

📌 [审查类型] 请选择审查类型

A) 增量审查 — 审查最近 N 次提交的变更文件及其关联代码
B) 存量审查 — 审查指定模块或全量代码

请输入选项编号（如 A）：

变量赋值：

用户输入	变量赋值
A	REVIEW_TYPE=增量审查
B	REVIEW_TYPE=存量审查

⚠️ 此步骤结束后必须立即停止输出，等待用户回复后再进入下一步骤。不得在本步骤的回复中同时输出步骤3（审查范围）的选项。

---

步骤3：选择审查范围（条件步骤）

判断逻辑（基于步骤2结果和预扫描的 PROJECT_TYPE）：

条件	动作
步骤2 = 增量审查	必须询问（方案 A）
步骤2 = 存量审查 且 PROJECT_TYPE 为 *-single	跳过此步骤，自动设 REVIEW_SCOPE=全量代码
步骤2 = 存量审查 且 PROJECT_TYPE 为 *-multi	必须询问（方案 B）

方案 A：增量审查 — 选择提交次数

仅输出以下选项文本，然后立即停止输出，等待用户输入：

📌 [提交次数] 审查最近几次提交的变更？

A) 最近 1 次 — 仅审查最近一次提交
B) 最近 3 次 — 审查最近 3 次提交
C) 最近 5 次 — 审查最近 5 次提交（推荐）
D) 最近 10 次 — 审查最近 10 次提交

请输入选项编号（如 C），或直接输入自定义次数（如 20）：

变量赋值：

用户输入	变量赋值
A	REVIEW_SCOPE=最近1次提交
B	REVIEW_SCOPE=最近3次提交
C	REVIEW_SCOPE=最近5次提交
D	REVIEW_SCOPE=最近10次提交
自定义数字（如 20）	REVIEW_SCOPE=最近20次提交

⚠️ 此步骤结束后必须立即停止输出，等待用户回复后再进入下一步骤。不得在本步骤的回复中同时输出步骤4（审查模式）的选项。

方案 B：存量审查（多模块）— 选择审查模块

仅输出以下选项文本，然后立即停止输出，等待用户输入：

📌 [审查范围] 请选择要审查的模块（可多选，用逗号分隔）

A) 全量代码 — 审查所有模块
B) {模块1名称} — {模块1相对路径}，{N} 类 {M} 行
C) {模块2名称} — {模块2相对路径}，{N} 类 {M} 行
...

请输入选项编号（可多选，如 B,C），或直接输入模块路径：

变量赋值：

用户输入	变量赋值
A	REVIEW_SCOPE=全量代码
B	REVIEW_SCOPE 追加 {模块1路径}
B,C	REVIEW_SCOPE={模块1路径},{模块2路径}
自定义路径	REVIEW_SCOPE=自定义路径

注意：

• 模块列表从预扫描结果中动态生成，每个模块的名称、路径和统计信息都来自预扫描输出
• 多选时用逗号分隔（如 B,C）
• 如果用户同时选了「全量代码」（A）和具体模块，以「全量代码」为准
• 用户选择具体模块后，REVIEW_SCOPE 为逗号分隔的模块相对路径，如 user-service,order-service

⚠️ 此步骤结束后必须立即停止输出，等待用户回复后再进入下一步骤。不得在本步骤的回复中同时输出步骤4（审查模式）的选项。

---

步骤4：选择审查模式

仅输出以下选项文本，然后立即停止输出，等待用户输入：

📌 [审查模式] 请选择审查模式

A) fast — 快速扫雷，聚焦关键风险，约 5 分钟内出结果
B) standard — 标准审查，覆盖常规核心维度 + API设计 + 缓存基础 + 核心测试缺失，日常迭代推荐
C) deep — 深度审查，全量 15 维度，适合大版本上线前
D) security — 安全专项，聚焦安全核心维度

请输入选项编号（如 B）：

变量赋值：

用户输入	变量赋值
A	REVIEW_MODE=fast
B	REVIEW_MODE=standard
C	REVIEW_MODE=deep
D	REVIEW_MODE=security

⚠️ 此步骤结束后必须立即停止输出，等待用户回复后再进入下一步骤。不得在本步骤的回复中同时输出步骤5（飞书上传）的选项。

---

步骤5：选择飞书上传选项（条件步骤）

判断逻辑（基于预扫描的 lark-cli 检测结果）：

条件	动作
LARK_PLUGIN_INSTALLED=true	必须询问
LARK_PLUGIN_INSTALLED=false	跳过此步骤，自动设 FEISHU_UPLOAD_OPTION=lark-cli未安装

跳过时：在上一条用户回复的确认中简短说明跳过原因（如"未检测到 lark-cli，跳过飞书上传选项"），然后继续到步骤6。跳过本身也需要一个输出，不能静默跳过。

仅输出以下选项文本，然后立即停止输出，等待用户输入：

📌 [飞书上传] 检测到 lark-cli 已安装，请选择审查结果的处理方式

A) 仅显示报告 — 只在聊天中显示完整审查报告
B) 上传到云文档 — 审查报告上传到飞书云文档，聊天中显示精简摘要
C) 上传到多维表格 — 问题清单录入飞书多维表格，聊天中显示精简摘要
D) 同时上传两者 — 同时上传云文档和多维表格，聊天中显示精简摘要

请输入选项编号（如 A）：

变量赋值：

用户输入	变量赋值
A	FEISHU_UPLOAD_OPTION=仅显示报告
B	FEISHU_UPLOAD_OPTION=上传到云文档
C	FEISHU_UPLOAD_OPTION=上传到多维表格
D	FEISHU_UPLOAD_OPTION=同时上传两者

⚠️ 此步骤结束后必须立即停止输出，等待用户回复后再进入下一步骤。

---

步骤6：确认执行计划

必须展示完整执行计划并等待用户确认后，才能进入代码审查阶段。

仅输出以下文本，然后立即停止输出，等待用户输入：

📋 执行计划：
- 项目路径：{PROJECT_DIR}
- 项目类型：{PROJECT_TYPE}
- 审查分支：{CURRENT_BRANCH 或 TARGET_BRANCH}（仅 Git 项目显示）
- 审查类型：{REVIEW_TYPE}
- 审查范围：{REVIEW_SCOPE}
- 审查模式：{REVIEW_MODE}
- 启用维度：{根据模式 × 维度矩阵列出具体维度名称}
- 飞书上传：{FEISHU_UPLOAD_OPTION}

A) ✅ 确认执行 — 按以上配置开始审查
B) ❌ 取消 — 取消本次审查

请输入选项编号（A/B）：

注意：用户输入 A（确认执行）后进入代码审查阶段调用子agent；输入 B（取消）则终止流程。

⚠️ 此步骤结束后必须立即停止输出，等待用户回复。用户确认后才能进入代码审查阶段。

步骤6确认后的启动提示

用户确认后、调用子agent之前，必须立即输出以下格式的提示信息，让用户清楚知道正在启动独立子代理执行长时间任务。

计时要求：在输出启动提示的同一时刻，主agent应记录当前时间作为 START_TIME，子agent返回后用于计算执行耗时。

🚀 正在启动独立代码审查子代理...

📋 任务配置：{REVIEW_MODE} 模式 · {REVIEW_TYPE} · {REVIEW_SCOPE}
⏱️ 预估耗时：{预估时间}
📌 子代理将独立执行完整审查流程，完成后自动返回结果。

{FEISHU_UPLOAD_OPTION 不是「仅显示报告」/「lark-cli未安装」时，追加以下行}
📤 审查完成后将自动上传到飞书（{FEISHU_UPLOAD_OPTION}），无需手动操作。

💡 温馨提示：审查期间您可以继续使用 OpenClaw 进行其他操作。

预估时间参考（根据 REVIEW_MODE + 项目规模估算）：

模式	小型项目（<50 类）	中型项目（50-200 类）	大型项目（>200 类）
fast	2-3 分钟	3-5 分钟	5-8 分钟
standard	5-8 分钟	8-15 分钟	15-25 分钟
deep	10-15 分钟	15-30 分钟	30-60 分钟
security	5-10 分钟	10-20 分钟	20-35 分钟

项目规模从预扫描的「Java文件总数」获取。增量审查的时间按变更文件数估算，通常比全量快 30-50%。

---

代码审查阶段：代码审查（使用子agent执行）

目标：将用户确认的审查配置和项目信息作为参数注入子agent prompt，由子agent独立完成代码审查和飞书上传（可选），最后将结果汇总返回主agent。

子agent调用方式

使用openclaw的sessions_spawn工具委派子agent，按以下方式构造调用：

sessions_spawn工具调用参数（参考格式）：

{
  "task": "执行 Java 代码审查任务（审查参数已注入）",
  "runtime": "subagent",
  "mode": "run"
}

注意：openclaw飞书channel不支持子代理的 thread 绑定，无需设置

参数说明：

• task: 子代理的任务描述
• runtime: 固定为 "subagent"
• mode: 固定为 "run"

Prompt 构造方式（在调用 Agent 工具时传入的 prompt 参数）：

1. 注入审查参数（替换 {变量名} 为实际值）：

## 审查任务参数（外部注入，请直接使用，无需再次确认）

| 参数 | 值 |
|------|-----|
| 项目路径 | {PROJECT_DIR} |
| 项目名称 | {PROJECT_NAME} |
| 项目类型 | {PROJECT_TYPE} |
| 审查类型 | {REVIEW_TYPE} |
| 审查范围 | {REVIEW_SCOPE} |
| 审查模式 | {REVIEW_MODE} |
| 飞书上传选项 | {FEISHU_UPLOAD_OPTION} |
| 审查文件数量 | {REVIEW_FILE_COUNT} |
| 审查代码行数 | {REVIEW_LINE_COUNT} |

### 项目概况（预扫描结果）
{PROJECT_SCAN_RESULT}

> 以下数据已由预扫描获取，子agent **禁止重复执行**：项目类型、模块结构（MODULE:行）、文件数、行数统计。子agent应直接利用这些数据确定审查范围，仅需对目标文件执行 grep/read 操作。

### 增量提交记录（仅增量审查时提供）
{GIT_LOG_OUTPUT}

### 变更文件列表（仅增量审查时提供）
{CHANGED_FILES_OUTPUT}

### 变更统计概览（仅增量审查时提供）
{DIFF_STATS_OUTPUT}

2. 附加 agent 提示词内容：读取 {baseDir}/prompts/java-code-reviewer.md 的完整内容并追加到 prompt 中。注意：提示词中包含 {baseDir} 占位符（用于引用 references/review-framework.md），读取后需将所有 {baseDir} 替换为本技能的实际根目录绝对路径（即 SKILL.md 所在目录），确保子agent能正确找到审查框架文件。

3. 附加执行指令：

请基于以上审查参数，立即开始执行代码审查。不要进行任何用户交互或询问，直接从代码审查开始执行。

参数来源说明

变量名	来源	示例值
PROJECT_DIR	预扫描项目识别输出	/tmp/{仓库名} 或本地路径
PROJECT_SOURCE	预扫描项目识别输出	local / git-cache
PROJECT_NAME	basename "$PROJECT_DIR" 自动提取	spring-ai-agent-utils
PROJECT_TYPE	预扫描项目扫描输出	maven-single / maven-multi / gradle-single / gradle-multi / unknown
REVIEW_TYPE	交互步骤2用户选择 / 快速启动 --type	增量审查 / 存量审查
REVIEW_SCOPE	交互步骤3用户选择 / 快速启动 --scope	最近5次提交 / 全量代码 / user-service,order-service
REVIEW_MODE	交互步骤4用户选择 / 快速启动 --mode	fast / standard / deep / security
FEISHU_UPLOAD_OPTION	交互步骤5用户选择 / 快速启动 --upload	仅显示报告 / 上传到云文档 / 上传到多维表格 / 同时上传两者 / lark-cli未安装
PROJECT_SCAN_RESULT	预扫描完整输出	项目概况、模块结构的原始输出
REVIEW_FILE_COUNT	从 PROJECT_SCAN_RESULT 解析	本次审查涉及的 Java 文件数量（如 76）
REVIEW_LINE_COUNT	从 PROJECT_SCAN_RESULT 解析	本次审查涉及的代码总行数（如 16637）
GIT_LOG_OUTPUT	条件生成（见下方）	git log --oneline -N 的输出
CHANGED_FILES_OUTPUT	条件生成（仅增量审查）	git diff --name-only 的输出，变更文件路径列表
DIFF_STATS_OUTPUT	条件生成（仅增量审查）	git diff --stat 的输出，各文件改动行数统计

增量审查预处理（仅增量审查时执行）

在调用子agent之前，先执行以下命令获取提交记录、变更文件列表和变更统计。注意：脚本会自动处理提交数不足 N 的情况，防止 HEAD~N 越界。

执行脚本：

bash scripts/phase5-prepare-incremental.sh "$PROJECT_DIR" {N}

脚本输出（三个部分用 # === 分隔）：

1. # === 提交记录 === 之后的内容 → GIT_LOG_OUTPUT
2. # === 变更文件列表 === 之后的内容 → CHANGED_FILES_OUTPUT
3. # === 变更统计 === 之后的内容 → DIFF_STATS_OUTPUT

主 Agent 需解析脚本输出，分别提取三个部分作为独立变量注入子 Agent。

异常情况处理：

• 如果 CHANGED_FILES_OUTPUT 为空（没有变更文件），主agent应：
  1. 告知用户：选择的提交范围内没有变更文件
  2. 询问是否调整提交次数或切换到存量审查
  3. 不应调用子agent处理空文件列表

子agent返回结果

子agent执行完成后，根据飞书上传选项返回不同格式的结果，主agent需将此结果展示给用户。

已上传飞书时（简化汇总 + 飞书链接）：

✅ 代码审查已完成！⏱️ 耗时 {X} 分 {Y} 秒

📊 审查结果：{问题总数} 个问题（P0: {n} / P1: {n} / P2: {n} / P3: {n} / 待确认: {n}）

🔥 最高风险项：
  - P0-1: {问题一句话描述} — {位置}
  （最多列 5 条）

📄 审查报告：{链接}
📋 问题清单：{链接}

💡 建议：{一句话关键建议}
👉 详细报告请点击上方飞书链接查看。

耗时计算：当前时间 - START_TIME，格式为 X 分 Y 秒（不足1分钟时只显示秒）。

未上传飞书时（完整报告）：子agent会将第三步生成的完整审查报告原样输出，包含所有章节（审查配置快照、执行摘要、各级别问题详情、修复优先级、总结等）。主agent在展示结果时，需在报告末尾追加耗时汇总：

✅ 代码审查已完成！⏱️ 耗时 {X} 分 {Y} 秒

📊 审查结果：{从报告中提取问题总数}
💡 建议：{从报告中提取一句话关键建议}

异常降级：如果飞书上传步骤失败，子agent会降级为输出完整报告，并说明失败原因。主agent应将结果直接展示给用户。

---

重要规则

强制规则

快速启动模式豁免：当检测到 --mode 参数进入快速启动模式时，以下标有 ⚡ 的规则不适用，其余规则仍然生效。

1. 必须使用纯文本选项交互 ⚡：所有用户交互（分支选择、审查类型选择、模块选择、模式选择、飞书上传选项、执行确认）都必须通过纯文本输出选项、等待用户自由文本输入的方式完成。禁止使用 AskUserQuestion 等结构化输入工具
2. 输入校验：用户自定义输入必须与当前问题相关且合理，无效输入需提示重新选择，每步最多重试 3 次
3. 执行前强制确认 ⚡：必须展示执行计划并通过文本选项等待用户确认，不能跳过
4. 三个核心选项必须全部明确：审查类型 + 审查范围 + 审查模式，缺一不可
5. 强制交互流程 ⚡：无论用户是否提供参数，都必须依次通过文本选项引导用户完成所有步骤
6. 强制中文输出：所有交互和报告都必须使用中文
7. 最终确认前零审查动作：不得在用户确认前执行任何代码扫描
8. 禁止跳过步骤 ⚡：任何时候都不能跳过任何交互步骤，即使参数已经明确
9. 禁止合并交互步骤 ⚡：每个回复中只能出现一组交互选项。输出当前步骤的选项文本后立即停止输出，等待用户回复。绝不允许在一次回复中展示多个步骤的选项（例如将「审查范围」和「审查模式」放在同一个回复中）
10. 快速启动参数完整性：快速启动模式下，--mode 和 --type 必须同时存在，--scope 根据条件必填规则校验，缺少任一必填参数立即报错终止，不允许降级为交互式模式

条件步骤规则

1. 单模块项目自动跳过步骤3：如果 PROJECT_TYPE 为 maven-single 或 gradle-single 且步骤2选择了「存量审查」，步骤3（选择审查范围）必须跳过，自动设 REVIEW_SCOPE=全量代码
2. lark-cli 检测：预扫描阶段检测 lark-cli 是否安装，根据结果决定是否执行步骤5（飞书上传选项）；未安装时自动设 FEISHU_UPLOAD_OPTION=lark-cli未安装
3. 飞书上传执行：子agent根据 FEISHU_UPLOAD_OPTION 参数执行对应上传动作。上传飞书云文档必须使用 lark-doc skill，上传多维表格必须使用 lark-base skill，均通过 lark-cli 命令行工具执行
4. Git 分支选择：步骤1仅在项目为 Git 仓库且存在多个活跃分支时执行；非 Git 项目或单分支项目自动跳过

---

错误处理

如果用户输入无法识别或与当前问题无关：

• 输出 ⚠️ 输入无效 提示，重新展示当前步骤的选项文本
• 每个步骤最多重试 3 次
• 超过 3 次仍无效时，输出 ❌ 多次输入无效，已终止本次审查 并结束流程

---

示例对话

完整的示例对话（5个场景：本地单模块、Git多模块、快速启动、参数校验失败、指定分支+飞书上传）详见 {baseDir}/references/examples.md。

核心要点回顾：

• 交互式模式：严格单步，每组选项独占一个回复
• 快速启动模式：预扫描 → 参数校验 → 直接启动子agent，无交互
• 子agent完成后：已上传飞书则显示精简摘要+链接，未上传则显示完整报告