# ai-agent-config

**Repository Path**: jiangqiang1996/ai-agent-config

## Basic Information

- **Project Name**: ai-agent-config
- **Description**: 用于ai代理的一些通用配置
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-06
- **Last Updated**: 2026-04-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

use skill tool to list skills# Codebase Review 代码库巡检插件

> 为 OpenCode 提供状态化分步代码库巡检工作流，支持断点续跑、人工干预和提前终止。

## 功能简介

`codebase-review` 是一个 **状态保持的分步式代码库巡检引擎**，它将大规模代码审查拆解为多步骤流水线，自动管理上下文，支持从断点恢复执行，并允许在手动模式下对中间步骤输出做人工校正。

提供三种预设巡检 `profile`：

| Profile | 流程 | 适用场景 |
|---------|------|----------|
| `scan`  | 综合审计 → 终止 | 只需要出问题报告，不需要修改代码 |
| `fix`   | 综合审计 → 修复计划 → 执行修复 → 复盘沉淀 | 发现问题后按计划直接修复 |
| `deep`  | 综合审计 → 根因深潜 → 修复计划 → 执行修复 → 复盘沉淀 | 需要对已识别问题做深入根因分析 |

### 核心特性
- **状态持久化**：每一步执行后都会保存到 `.codebase-review-state.json`，支持断点续跑。
- **自动提前终止**：如果 `audit` 阶段结论是 `VERDICT: CLEAN`（无需要修复的实质性问题），`fix` 和 `deep` 会自动跳过后续步骤，节省计算。`scan` 固定终止于审计。
- **两种运行模式**：`auto` 模式每一步自动链式推进；`step` 模式每一步完成后暂停，方便人工审阅和编辑。
- **步骤编辑**：手动模式下可对任意已完成步骤的输出做修改，后续步骤会自动使用新版本。

## 工具列表与使用说明

### 1. `codebase-review`
**启动一次新的巡检工作流**。首次调用必须指定 `profile` 和 `mode`；若未指定或传 `?`，会返回选项让你选择。

**参数说明**：
- `profile`（`scan` / `fix` / `deep`）：
  - `scan`：仅做综合审计，不修改代码，扫描完成即终止。
  - `fix`：审计 → 计划 → 修复 → 复盘的全流程巡检修复。
  - `deep`：在 `fix` 基础上增加根因深潜环节，对问题做更透彻分析。
- `mode`（`auto` / `step`）：
  - `auto`：自动模式，每一步执行完成后自动继续下一步，无需人工干预。
  - `step`：手动模式，每一步完成后暂停，等待人工继续或编辑。

**调用示例**：
```
codebase-review(profile="scan", mode="auto")
```

**注意**：同一时间只能有一个进行中的工作流。如果已有未完成任务，需要先执行 `review-reset` 清除状态。

---

### 2. `review-continue`
**从当前断点继续执行下一步**。仅在有进行中的工作流时可用。

**参数说明**：
- `mode`（可选，覆盖保存的模式）：`auto` 或 `step`。

**使用场景**：
- `auto` 模式一般无需手动调用，系统会自动链式推进；
- `step` 模式每一步完成后必须手动调用 `review-continue` 才能继续；
- 如果中途想切换自动/手动模式，可以在这里指定新 `mode`。

---

### 3. `review-edit`
**修改某个已完成步骤的输出**。后续步骤会自动使用修改后的结果。在 `step` 模式下可做人工校正和结论调整。

**参数说明**：
- `stepId`：要修改的步骤 ID，例如 `audit`、`plan`、`deep-dive`、`fix`、`retro`。
- `content`：替换后的完整输出内容。

---

### 4. `review-status`
查询当前工作流的执行状态：使用哪个 `profile`、哪些步骤已完成、哪些待执行、是否有提前跳过的步骤等。

**调用方式**：
```
review-status
```

---

### 5. `review-reset`
清除当前工作流的状态文件 `.codebase-review-state.json`，丢弃所有已执行步骤结果。下次调用 `codebase-review` 将会从头开始。

**调用方式**：
```
review-reset
```

## 使用步骤

### 快速开始（扫描巡检）
1. 在项目根目录调用：
   ```
   codebase-review(profile="scan", mode="auto")
   ```
2. 等待审计执行完成，查看报告。若有问题需要修复，执行 `review-reset` 后改用 `profile="fix"` 或 `profile="deep"` 重新启动。

### 巡检修复流程
1. 启动工作流：
   ```
   codebase-review(profile="fix", mode="auto")
   ```
2. 插件会依次执行：
   - **综合审计**：扫描代码正确性、架构边界、历史债务、文档一致性等维度，给出问题清单。
   - 如果审计结论为清洁，则提前终止；否则继续生成修复计划。
   - 按优先级执行修复，每步记录改动和验证结果。
   - 最后做复盘沉淀，提取可复用经验。
3. 全程 `auto` 模式会自动走完，不需要额外操作。

### 手动干预流程
1. 启动时指定 `mode="step"`：
   ```
   codebase-review(profile="deep", mode="step")
   ```
2. 每一步执行完成后会暂停，你可以：
   - 使用 `review-status` 查看进度；
   - 如果需要校正结论，使用 `review-edit(stepId="audit", content="...")` 修改输出；
   - 确认无误后调用 `review-continue` 继续下一步。
3. 直到所有步骤完成。

### 断点恢复
若对话中断或你手动停止了执行，下次打开对话只需要调用 `review-continue` 就能从断点处恢复，已完成步骤结果会自动复用。

## 状态文件说明

插件会在项目根目录生成 `.codebase-review-state.json`，用于保存：
- 当前使用的 `profile` 和 `mode`；
- 已完成的步骤清单和每一步的完整输出；
- 会话元数据便于断点恢复。

该文件**不应提交到 Git**，建议在 `.gitignore` 中添加：
```
.codebase-review-state.json
```

当工作流正常完成或需要重新开始时，执行 `review-reset` 会自动删除该文件。

## 注意事项

1. **提前终止规则**：
   - `scan` profile 始终在 `audit` 后终止；
   - `fix` / `deep` profile 当 `audit` 结论为 `VERDICT: CLEAN` 时，会跳过后续修复步骤直接终止；
   - 这意味着只要审计未发现问题，就不会产生任何代码修改。

2. **同一项目不能同时跑多个工作流**：如果需要切换 profile 或重新开始，必须先 `review-reset` 清除状态。

3. **人工编辑**：`review-edit` 只修改保存在状态文件中的输出，不会修改源码文件；要修改源码仍然需要走后续修复步骤。

4. **结果判定**：插件通过审计报告末尾的 `VERDICT: ISSUES_FOUND` / `VERDICT: CLEAN` 判断是否存在问题；如果结论行丢失，会通过关键词 fallback 检测。

## 许可

遵循当前仓库的整体许可协议。