docs: add design spec for migrating review agents to unified costrict-review repo
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
kingboung
parent
ea410c861c
commit
65c347a151
|
|
@ -0,0 +1,245 @@
|
|||
# 迁移 Review Agents 到统一 costrict-review 仓库
|
||||
|
||||
**日期**: 2026-05-06
|
||||
**参考 PR**: https://github.com/zgsm-sangfor/opencode/pull/360
|
||||
**分支**: `feat/migrate-review-agents`
|
||||
|
||||
## 目标
|
||||
|
||||
将 opencode PR #360 的 review 资源迁移改造对标到 csc。用统一方案替代当前的单仓库 skill 生成（`zgsm-ai/security-review-skill`），从 `zgsm-ai/costrict-review` 仓库同时下载 review agents（CoStrictReviewer、CoStrictValidator）和 review skills（security-review），由 `index.json` manifest 驱动。
|
||||
|
||||
## 关键决策
|
||||
|
||||
| 决策项 | 选择 | 理由 |
|
||||
|--------|------|------|
|
||||
| 生成脚本 | 完全替代 `generate-skills.ts` | 单一数据源，统一管理 |
|
||||
| Agent 集成 | 合并到现有 `getBuiltInAgents()` | 复用 `BuiltInAgentDefinition` 类型和加载流程 |
|
||||
| `/review` 命令 | 路由到 CoStrictReviewer agent | 对标 opencode 行为，无需降级 |
|
||||
| 多语言支持 | zh-CN + en 双语 | 对标 opencode，由 `preferredLanguage` 配置 + `getResolvedLanguage()` 驱动 |
|
||||
| Frontmatter 合并 | 合并 `index.json` 中的 `claudecode` 字段 | `index.json` 有 `claudecode` key 存放 csc 专用字段 |
|
||||
|
||||
## 架构
|
||||
|
||||
### Locale 机制
|
||||
|
||||
csc 现有的语言系统：
|
||||
- **配置项**: `GlobalConfig.preferredLanguage`，存储在 `~/.claude/.claude.json`，值为 `'auto' | 'en' | 'zh'`
|
||||
- **解析函数**: `getResolvedLanguage()`（`src/utils/language.ts`），返回 `'en' | 'zh'`，无状态 pull-based
|
||||
- **解析优先级**: 配置值 → 系统 locale（`Intl.DateTimeFormat`）→ 默认 `'en'`
|
||||
- **Locale 映射**: csc 用 `'zh'`/`'en'`，costrict-review 仓库用 `'zh-CN'`/`'en'`，需要在运行时做 `'zh' → 'zh-CN'` 映射
|
||||
|
||||
各组件 locale 获取方式（均通过 `getResolvedLanguage()` 内部调用，无需修改 `ToolUseContext.options`）：
|
||||
|
||||
| 组件 | 获取方式 | 说明 |
|
||||
|------|----------|------|
|
||||
| Agent `getSystemPrompt` | 内部调用 `getResolvedLanguage()` → 映射后选 prompt 常量 | 无需改接口签名 |
|
||||
| Skill 初始化 | `initializeBuiltinSkills()` 内部调用 `getResolvedLanguage()` | 传给 `extractBundledSkill()` |
|
||||
| 命令模板 | `CommandLocale.get()` 内部调用 `getResolvedLanguage()` | 选择对应 locale 的 .txt |
|
||||
|
||||
### 数据流
|
||||
|
||||
```
|
||||
zgsm-ai/costrict-review 仓库
|
||||
├── index.json (manifest: agents + skills，按 locale 分路径)
|
||||
├── zh-CN/ (agent markdown + skill 文件)
|
||||
└── en/ (agent markdown + skill 文件)
|
||||
│
|
||||
▼ scripts/generate-review-builtin.ts (构建时执行)
|
||||
│
|
||||
┌───────┴───────────────────────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
agent/builtin.ts skill/builtin.ts
|
||||
(BuiltInAgentDefinition[]) (SKILL_FILES + 提取函数)
|
||||
│ │
|
||||
▼ ▼
|
||||
builtInAgents.ts extension.ts → 缓存目录
|
||||
(getBuiltInAgents spread) (~/.claude/skills/<name>/)
|
||||
```
|
||||
|
||||
## 第一部分：生成脚本
|
||||
|
||||
**文件**: `scripts/generate-review-builtin.ts`（新增，替代 `scripts/generate-skills.ts`）
|
||||
|
||||
从 opencode 移植，适配点：
|
||||
- 路径调整：`scripts/` 而非 `packages/opencode/script/`
|
||||
- 输出路径：`src/costrict/review/agent/builtin.ts` 和 `src/costrict/review/skill/builtin.ts`
|
||||
- 缓存目录：`packages/builtin-tools/bundled-review/`
|
||||
- Agent 生成输出 `BuiltInAgentDefinition[]` 而非 `ReviewAgentEntry`
|
||||
- 使用 `index.json` 中的 `claudecode` 字段（而非 `opencode`）合并 frontmatter
|
||||
|
||||
**核心逻辑**：
|
||||
1. `git ls-remote` 获取 SHA，与缓存 SHA 比对
|
||||
2. `git clone --depth 1` 到临时目录
|
||||
3. 读取 `index.json` manifest
|
||||
4. 按 locale 复制 skill 目录和 agent 文件到 `bundled-review/{locale}/`
|
||||
5. 通过 `gray-matter` 将 `claudecode` 字段合并到 agent markdown frontmatter
|
||||
6. 生成 `agent/builtin.ts`：解析合并后的 frontmatter，提取 `agentType`、`whenToUse`、`tools`、`permissionMode`、`model`、`visibleTo`、`disallowedTools` 等，将 locale prompt 嵌入为字符串常量，导出 `REVIEW_AGENTS: BuiltInAgentDefinition[]`
|
||||
7. 生成 `skill/builtin.ts`：将所有 skill 文件嵌入为字符串常量，导出 `SKILL_FILES`（locale → skillName → files）、版本跟踪、提取函数
|
||||
8. 清理临时 clone 目录
|
||||
|
||||
**依赖**: `gray-matter`（用于 frontmatter 解析/合并）
|
||||
|
||||
## 第二部分：Agent 生成产物与集成
|
||||
|
||||
**生成的 `src/costrict/review/agent/builtin.ts`** 导出：
|
||||
|
||||
```ts
|
||||
import { getResolvedLanguage } from 'src/utils/language.js'
|
||||
|
||||
const LOCALE_MAP: Record<string, string> = { zh: 'zh-CN', en: 'en' }
|
||||
|
||||
// 嵌入的 locale prompt 常量（由生成脚本填充）
|
||||
const REVIEWER_PROMPTS: Record<string, string> = {
|
||||
'zh-CN': '...<中文 prompt>...',
|
||||
'en': '...<English prompt>...',
|
||||
}
|
||||
|
||||
export const REVIEW_AGENTS: BuiltInAgentDefinition[] = [
|
||||
{
|
||||
agentType: 'CoStrictReviewer',
|
||||
whenToUse: '<从合并后的 frontmatter 提取>',
|
||||
tools: ['Glob', 'Grep', 'Read', 'TodoWrite', 'Bash', 'Agent'],
|
||||
permissionMode: 'plan',
|
||||
model: 'inherit',
|
||||
source: 'built-in',
|
||||
baseDir: 'built-in',
|
||||
getSystemPrompt: () => {
|
||||
const lang = getResolvedLanguage()
|
||||
const locale = LOCALE_MAP[lang] ?? 'zh-CN'
|
||||
return REVIEWER_PROMPTS[locale] ?? REVIEWER_PROMPTS['zh-CN']
|
||||
},
|
||||
},
|
||||
// CoStrictValidator 同理，使用 VALIDATOR_PROMPTS
|
||||
]
|
||||
```
|
||||
|
||||
- Prompt 内容以 locale 为 key 的 `Record<string, string>` 嵌入（由生成脚本填充）
|
||||
- `getSystemPrompt` 内部调用 `getResolvedLanguage()`（无状态函数，可直接调用）
|
||||
- 通过 `LOCALE_MAP` 将 csc 的 `'zh'` 映射为 costrict-review 仓库的 `'zh-CN'`
|
||||
- `CoStrictValidator` 无 `Agent` tool → 列入 `disallowedTools`
|
||||
- `CoStrictReviewer` 通过 `visibleTo` 限制可见性（仅可通过 `/review` 命令或特定 agent 调用）
|
||||
|
||||
**集成到 `packages/builtin-tools/src/tools/AgentTool/builtInAgents.ts`**：
|
||||
|
||||
```ts
|
||||
import { REVIEW_AGENTS } from 'src/costrict/review/agent/builtin.js'
|
||||
|
||||
// 在 getBuiltInAgents() 返回数组末尾：
|
||||
return [
|
||||
...existingAgents,
|
||||
...REVIEW_AGENTS,
|
||||
]
|
||||
```
|
||||
|
||||
## 第三部分：Skill 生成产物与初始化
|
||||
|
||||
**生成的 `src/costrict/review/skill/builtin.ts`** 导出：
|
||||
|
||||
```ts
|
||||
export const SKILL_FILES: Record<string, Record<string, Record<string, string>>> = {
|
||||
"zh-CN": {
|
||||
"security-review": {
|
||||
"SKILL.md": "...",
|
||||
"knowledge/security/api_security.md": "...",
|
||||
// ... 所有文件
|
||||
}
|
||||
},
|
||||
"en": { /* 同结构 */ }
|
||||
}
|
||||
|
||||
export const SKILL_VERSIONS: Record<string, string> = {
|
||||
"security-review": "<commit-sha>"
|
||||
}
|
||||
|
||||
export function listBuiltinSkills(): string[]
|
||||
export function getBuiltinSkillVersion(name: string): string | undefined
|
||||
export function listSkillFiles(name: string, locale: string): string[]
|
||||
export async function extractBundledSkill(name: string, targetDir: string, locale: string): Promise<void>
|
||||
```
|
||||
|
||||
**`src/costrict/review/extension.ts`** — 从 opencode 适配，去除 Effect 依赖：
|
||||
|
||||
- `initializeBuiltinSkills(locale?: string)` — 内部调用 `getResolvedLanguage()` 获取 locale（映射 `'zh' → 'zh-CN'`），检查缓存版本，需要时从 `SKILL_FILES` 提取到磁盘
|
||||
- 缓存目录：`~/.claude/skills/<name>/`（csc 配置目录，非 `~/.config/costrict/`）
|
||||
- 版本文件：`.version`，内容为 `<sha>:<locale>`
|
||||
- `getBuiltinSkillsDir()` — 返回缓存目录供 skill 发现扫描
|
||||
|
||||
**Skill 系统集成（`src/skills/bundled/index.ts`）**：
|
||||
|
||||
- 移除 `registerCodeReviewSecuritySkill()` 调用（旧的内联注册方式）
|
||||
- 新增 `Extension.initializeBuiltinSkills()` 调用（不传参，内部自动获取 locale）
|
||||
- 确保 skill 发现机制扫描 builtin skills 缓存目录
|
||||
|
||||
## 第四部分：命令改动
|
||||
|
||||
### `/review` 命令（`src/commands/review.ts`）
|
||||
|
||||
- 替换当前 gh CLI 本地 review，改为 agent 路由方式
|
||||
- 命令注册时设置 `agent: 'CoStrictReviewer'`
|
||||
- 模板通过 `CommandLocale.get('review')` 获取（内部调用 `getResolvedLanguage()` 选择对应 locale 的 .txt）
|
||||
- `ultrareview` 导出保持不变（远程 bughunter 路径）
|
||||
|
||||
### `/security-review` 命令（`src/commands/security-review.ts`）
|
||||
|
||||
- 替换内联的 `SECURITY_REVIEW_MARKDOWN`，改为简化后的 Skill 工具引导 prompt
|
||||
- zh-CN: `# 安全代码审查\n\n请使用 Skill 工具加载 \`security-review\` 技能来对以下内容执行安全代码审查：$ARGUMENTS\n\n全程请使用中文进行回答与文件写入。`
|
||||
- en: `# Code Security Review\n\nPlease use the Skill tool to load the \`security-review\` skill to perform a security review on: $ARGUMENTS\n\nPlease respond and write all files in English throughout the entire process.`
|
||||
|
||||
### Locale 模板（`src/costrict/command/locales/`）
|
||||
|
||||
新增文件：
|
||||
- `zh-CN/review.txt`
|
||||
- `en/review.txt`
|
||||
|
||||
更新文件：
|
||||
- `zh-CN/security-review.txt`（简化）
|
||||
- `en/security-review.txt`（简化）
|
||||
|
||||
**`CommandLocale` 模块**（`src/costrict/command/locales/index.ts`）：
|
||||
- 导入各 locale 的 .txt 文件为字符串常量
|
||||
- `CommandLocale.get(name)` 内部调用 `getResolvedLanguage()` → 映射 `'zh' → 'zh-CN'` → 返回对应模板
|
||||
|
||||
## 第五部分：清理与构建集成
|
||||
|
||||
### 删除的文件
|
||||
- `scripts/generate-skills.ts`
|
||||
- `src/costrict/skills/builtin.ts`
|
||||
- `src/costrict/skills/codeReviewSecurity.ts`
|
||||
|
||||
### 修改的文件
|
||||
- `src/skills/bundled/index.ts` — 移除旧注册，新增初始化调用
|
||||
- `packages/builtin-tools/src/tools/AgentTool/builtInAgents.ts` — spread `REVIEW_AGENTS`
|
||||
- `.gitignore` — 添加生成文件规则
|
||||
- `build.ts` — pre-build 步骤调用 `generate-review-builtin.ts`
|
||||
- `scripts/dev.ts` — dev 模式调用生成脚本
|
||||
|
||||
### 新增 `.gitignore` 规则
|
||||
```
|
||||
src/costrict/review/agent/builtin.ts
|
||||
src/costrict/review/skill/builtin.ts
|
||||
```
|
||||
|
||||
### Stub 文件（提交到 git）
|
||||
- `src/costrict/review/agent/builtin.ts` — `export const REVIEW_AGENTS: BuiltInAgentDefinition[] = []`
|
||||
- `src/costrict/review/skill/builtin.ts` — 空结构 + 抛错的提取函数
|
||||
|
||||
### 构建集成
|
||||
- `build.ts`: pre-build 步骤调用 `bun run scripts/generate-review-builtin.ts`
|
||||
- `scripts/dev.ts`: dev 启动时调用生成脚本
|
||||
- `ci.yml`: 添加 SSH agent 配置 + review agent 生成步骤
|
||||
|
||||
### 依赖
|
||||
- `gray-matter` — 检查 `package.json`，如不存在则新增
|
||||
|
||||
## 新增文件汇总
|
||||
|
||||
| 文件 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `scripts/generate-review-builtin.ts` | 脚本 | 从 costrict-review 下载并生成 builtin 文件 |
|
||||
| `src/costrict/review/index.ts` | 模块入口 | 统一导出 Extension、SkillBuiltin、agents |
|
||||
| `src/costrict/review/extension.ts` | 运行时 | Skill 缓存初始化与版本跟踪 |
|
||||
| `src/costrict/review/agent/builtin.ts` | 生成产物 | CoStrictReviewer + CoStrictValidator agent 定义 |
|
||||
| `src/costrict/review/skill/builtin.ts` | 生成产物 | security-review skill 文件 + 版本跟踪 |
|
||||
| `src/costrict/command/locales/zh-CN/review.txt` | 模板 | `/review` zh-CN prompt |
|
||||
| `src/costrict/command/locales/en/review.txt` | 模板 | `/review` en prompt |
|
||||
Loading…
Reference in New Issue
Block a user