名称: ccw-cli-tools 描述: CLI 工具执行规范 (gemini/claude/codex/qwen/opencode)，具有统一提示模板、模式选项和自动调用触发器，用于代码分析和实现任务。支持可配置的CLI端点，用于分析、写入和审查模式。版本: 1.0.0

CLI 工具 - 统一执行框架

目的: 结构化 CLI 工具使用，配置驱动的工具选择、统一提示模板和质量门控执行。

配置: ~/.claude/cli-tools.json （全局配置，初始化时始终读取）

初始化（必需的第一步）

在任何工具选择或推荐之前:

检查配置是否在内存中存在：
- 如果配置已在对话内存中 → 直接使用
- 如果不在内存中 → 读取配置文件：
```
Read(file_path="~/.claude/cli-tools.json")
```
解析 JSON 以理解：
- 可用工具及其 enabled 状态
- 每个工具的 primaryModel 和 secondaryModel
- 为基于标签的路由定义的标签
- 工具类型（内置、cli-wrapper、api-endpoint）
在整个选择过程中使用配置

为什么: 工具、模型和标签可能更改。配置文件是单一事实来源。优化: 重用内存中配置以避免冗余文件读取。

流程

┌─ 用户请求
│
├─ 步骤 1: 加载配置
│  ├─ 检查配置是否在对话内存中存在
│  └─ 如果不在内存中 → Read(file_path="~/.claude/cli-tools.json")
│
├─ 步骤 2: 理解用户意图
│  ├─ 解析任务类型（分析、实现、安全等）
│  ├─ 提取所需能力（标签）
│  └─ 确定范围（文件、模块）
│
├─ 步骤 3: 选择工具（基于配置）
│  ├─ 指定了明确的 --tool？
│  │  是 → 在配置中验证 → 使用它
│  │  否 → 将标签与启用工具匹配 → 选择最佳匹配
│  │       → 无匹配 → 使用第一个启用工具（默认）
│  └─ 从配置获取 primaryModel
│
├─ 步骤 4: 构建提示
│  └─ 使用 6 字段模板：目的、任务、模式、上下文、预期、约束
│
├─ 步骤 5: 选择规则模板
│  ├─ 根据任务类型确定规则
│  └─ 通过 --rule 参数传递
│
├─ 步骤 6: 执行 CLI 命令
│  └─ ccw cli -p "<提示>" --tool <工具> --mode <模式> --rule <规则>
│
└─ 步骤 7: 处理结果
   ├─ 成功时 → 将输出交付给用户
   └─ 失败时 → 检查 secondaryModel 或后备工具

配置参考

配置文件位置

路径: ~/.claude/cli-tools.json （全局配置）

重要: 首先检查对话内存。仅当配置不在内存中时才读取文件。

读取配置

优先级: 首先检查对话内存

加载选项:

选项 1 （首选）：如果已在对话中加载，使用内存中配置
选项 2 （后备）：当不在内存中时从文件读取

# 读取配置文件
cat ~/.claude/cli-tools.json

配置定义了所有可用工具及其启用状态、模型和标签。

配置结构

JSON 文件包含一个 tools 对象，每个工具有这些字段：

字段	类型	描述	示例
`enabled`	布尔值	工具可用性状态	`true` 或 `false`
`primaryModel`	字符串	执行的默认模型	`"gemini-2.5-pro"`
`secondaryModel`	字符串	主模型失败时的后备模型	`"gemini-2.5-flash"`
`tags`	数组	能力标签用于路由	`["分析", "Debug"]`
`type`	字符串	工具类型	`"内置"`, `"cli-wrapper"`, `"api-endpoint"`

预期工具（仅参考）

配置中的典型工具（实际可用性通过读取文件确定）：

工具	典型类型	常见用途
`gemini`	内置	分析、调试（分析、Debug 标签）
`qwen`	内置	通用编码
`codex`	内置	代码审查、实现
`claude`	内置	通用任务
`opencode`	内置	开源模型后备

注意: 工具可用性、模型和标签可能不同。使用内存中配置或读取 ~/.claude/cli-tools.json（如果未缓存）。

配置字段

enabled: 工具可用性（布尔值）
primaryModel: 执行的默认模型
secondaryModel: 主模型失败时的后备模型
tags: 能力标签用于路由（分析、Debug、实现等）
type: 工具类型（内置、cli-wrapper、api-endpoint）

通用提示模板

结构: 每个 CLI 命令遵循此 6 字段模板

ccw cli -p "目的: [目标] + [原因] + [成功标准] + [范围]
任务: • [步骤 1: 具体操作] • [步骤 2: 具体操作] • [步骤 3: 具体操作]
模式: [分析|写入|审查]
上下文: @[文件模式] | 内存: [会话/技术/模块上下文]
预期: [交付格式] + [质量标准] + [结构要求]
约束: [领域约束]" --tool <工具-id> --mode <模式> --rule <模板>

字段规范

目的（目标定义）

什么: 清晰目标 + 动机 + 成功标准 + 范围边界

组件:

什么: 具体任务目标
为什么: 业务/技术动机
成功: 可衡量的成功标准
范围: 有界上下文/文件

示例 - 好:

目的: 识别认证模块中的 OWASP Top 10 漏洞以通过安全审计；成功 = 所有关键/高问题记录并附带修复；范围 = 仅 src/auth/**

示例 - 坏:

目的: 分析代码

任务（操作步骤）

什么: 具体、可操作的步骤，具有清晰动词和目标

格式: 带有具体操作的要点列表

示例 - 好:

任务:
• 扫描查询构建器中的 SQL 注入
• 检查模板渲染中的 XSS
• 验证 CSRF 令牌验证

示例 - 坏:

任务: 审查代码并发现问题

模式（权限级别）

选项:

分析 - 只读，安全用于自动执行
写入 - 创建/修改/删除文件，完整操作
审查 - Git-aware 代码审查（仅 codex）

规则:

始终明确指定
对于只读任务默认使用 分析
对于文件修改需要显式 --mode write
对于 git-aware 审查使用 --mode review 与 --tool codex

上下文（文件范围 + 内存）

格式: 上下文: @[文件模式] | 内存: [内存上下文]

文件模式:

@**/* - 所有文件（默认）
@src/**/*.ts - 特定模式
@../shared/**/* - 父/同级（需要 --includeDirs）

内存上下文（当基于先前工作时）：

内存: 基于认证重构（提交 abc123），使用 JWT 进行会话
内存: 与认证模块集成，共享来自 @shared/utils/errors.ts 的错误模式

预期（输出规范）

什么: 输出格式 + 质量标准 + 结构要求

示例 - 好:

预期: Markdown 报告，包含：
严重级别（关键/高/中/低），
文件:行引用，
修复代码片段，
优先级排名

示例 - 坏:

预期: 报告

约束（领域边界）

什么: 范围限制、特殊要求、重点领域

示例 - 好:

约束: 专注于认证 | 忽略测试文件 | 无破坏性更改

示例 - 坏:

约束: （缺失或太模糊）

CLI 执行模式

模式: 分析

权限: 只读
用于: 代码审查、架构分析、模式发现、探索
安全: 是 - 可自动执行
默认: 当未指定时

模式: 写入

权限: 创建/修改/删除文件
用于: 功能实现、错误修复、文档、代码创建
安全: 否 - 需要显式 --mode write
要求: 必须由用户明确请求

模式: 审查

权限: 只读（git-aware 审查输出）
用于: 未提交更改的代码审查、分支差异、特定提交
工具支持: 仅 codex（其他视为分析）
约束: 目标标志（--uncommitted、--base、--commit）和提示互斥

命令结构

基本命令

ccw cli -p "<提示>" --tool <工具-id> --mode <分析|写入|审查>

命令选项

选项	描述	示例
`--tool <工具>`	配置中的工具	`--tool gemini`
`--mode <模式>`	必需: 分析/写入/审查	`--mode 分析`
`--model <模型>`	模型覆盖	`--model gemini-2.5-flash`
`--cd <路径>`	工作目录	`--cd src/auth`
`--includeDirs <目录>`	附加目录	`--includeDirs ../shared,../types`
`--rule <模板>`	自动加载模板	`--rule analysis-review-architecture`
`--resume [id]`	恢复会话	`--resume` 或 `--resume <id>`

高级目录配置

工作目录（`--cd`）

当使用 --cd 时：

@**/* = 仅工作目录树内的文件
没有 --includeDirs 无法引用父/同级
通过限制上下文减少令牌使用

包含目录（`--includeDirs`）

外部文件的两步要求:

添加 --includeDirs 参数
在上下文中使用 @ 模式引用

# 单个目录
ccw cli -p "上下文: @**/* @../shared/**/*" \
  --tool gemini --mode 分析 \
  --cd src/auth --includeDirs ../shared

# 多个目录
ccw cli -p "..." \
  --tool gemini --mode 分析 \
  --cd src/auth --includeDirs ../shared,../types,../utils

会话恢复

何时使用:

多轮规划（分析 → 规划 → 实现）
多模型协作（工具 A → 工具 B 在同一主题上）
主题连续性（基于先前发现构建）

用法:

ccw cli -p "继续分析" --tool <工具-id> --mode 分析 --resume              # 恢复最后一个
ccw cli -p "修复发现的问题" --tool <工具-id> --mode 写入 --resume <id>              # 恢复特定
ccw cli -p "合并发现" --tool <工具-id> --mode 分析 --resume <id1>,<id2>      # 合并会话

可用规则模板

模板系统

使用 --rule <模板名称> 自动加载协议 + 模板附加到提示

通用模板

universal-rigorous-style - 精确任务（默认）
universal-creative-style - 探索性任务

分析模板

analysis-trace-code-execution - 执行跟踪
analysis-diagnose-bug-root-cause - 错误诊断
analysis-analyze-code-patterns - 代码模式分析
analysis-analyze-technical-document - 技术文档分析
analysis-review-architecture - 架构审查
analysis-review-code-quality - 代码质量审查
analysis-analyze-performance - 性能分析
analysis-assess-security-risks - 安全风险评估

规划模板

planning-plan-architecture-design - 架构设计
planning-breakdown-task-steps - 任务分解
planning-design-component-spec - 组件设计
planning-plan-migration-strategy - 迁移策略规划

开发模板

development-implement-feature - 功能实现
development-refactor-codebase - 代码重构
development-generate-tests - 测试生成
development-implement-component-ui - UI 组件实现
development-debug-runtime-issues - 运行时调试

任务类型特定示例

示例 1: 安全分析（只读）

ccw cli -p "目的: 识别认证模块中的 OWASP Top 10 漏洞以通过安全审计；成功 = 所有关键/高问题记录并附带修复
任务: • 扫描注入缺陷（SQL、命令、LDAP） • 检查认证绕过向量 • 评估会话管理 • 评估敏感数据暴露
模式: 分析
上下文: @src/auth/**/* @src/middleware/auth.ts | 内存: 使用 bcrypt 进行密码、JWT 进行会话
预期: 安全报告，包含：严重性矩阵、文件:行引用、适用时的 CVE 映射、按风险优先排序的修复代码片段
约束: 专注于认证 | 忽略测试文件
" --tool gemini --mode 分析 --rule analysis-assess-security-risks --cd src/auth

示例 2: 功能实现（写入模式）

ccw cli -p "目的: 实现 API 端点的速率限制以防止滥用；必须可配置每端点；向后兼容现有客户端
任务: • 创建带滑动窗口的速率限制器中间件 • 实现每路由配置 • 添加 Redis 后端用于分布式状态 • 包括内部服务绕过
模式: 写入
上下文: @src/middleware/**/* @src/config/**/* | 内存: 使用 Express.js、Redis 已配置、auth.ts 中的现有中间件模式
预期: 生产就绪代码，包含：TypeScript 类型、单元测试、集成测试、配置示例、迁移指南
约束: 遵循现有中间件模式 | 无破坏性更改
" --tool gemini --mode 写入 --rule development-implement-feature

示例 3: 错误根本原因分析

ccw cli -p "目的: 修复 WebSocket 连接处理程序中的内存泄漏，导致服务器在 24 小时后 OOM；必须在任何修复前识别根本原因
任务: • 跟踪从打开到关闭的连接生命周期 • 识别事件监听器积累 • 检查断开时的清理 • 验证垃圾收集资格
模式: 分析
上下文: @src/websocket/**/* @src/services/connection-manager.ts | 内存: 使用 ws 库、生产中约 5000 并发连接
预期: 根本原因分析，包含：内存配置文件、泄漏源（文件:行）、带代码的修复建议、验证步骤
约束: 专注于资源清理
" --tool gemini --mode 分析 --rule analysis-diagnose-bug-root-cause --cd src

示例 4: 代码审查（Codex 审查模式）

# 选项 1: 自定义焦点（默认审查未提交）
ccw cli -p "专注于安全漏洞和错误处理" --tool codex --mode 审查

# 选项 2: 仅目标标志（无提示与目标标志）
ccw cli --tool codex --mode 审查 --uncommitted
ccw cli --tool codex --mode 审查 --base main
ccw cli --tool codex --mode 审查 --commit abc123

工具选择策略

选择算法

步骤 0（必需）: 加载配置（内存优先策略）

# 检查配置是否在对话内存中存在
# 如果存在 → 使用内存中配置
# 如果不存在 → Read(file_path="~/.claude/cli-tools.json")

然后继续选择：

解析任务意图 → 提取所需能力
加载配置 → 从 JSON 解析启用工具和标签
匹配标签 → 筛选支持所需能力的工具
选择工具 → 按优先级选择（显式 > 标签匹配 > 默认）
选择模型 → 使用 primaryModel，后备到 secondaryModel

选择决策树

0. 加载配置（内存优先）
   ├─ 在内存中？ → 使用它
   └─ 不在内存中？ → 读取 ~/.claude/cli-tools.json
   ↓
1. 指定了显式 --tool？
   是 → 验证工具在配置中启用 → 使用它
   否 → 继续基于标签的选择
         ├─ 提取任务标签（安全、分析、实现等）
         │  ├─ 查找匹配标签的工具
         │  │  ├─ 多个匹配？使用第一个启用
         │  │  └─ 单个匹配？使用它
         │  └─ 无标签匹配？使用默认工具
         │
         └─ 默认: 使用配置中第一个启用工具

常见标签路由

注意: 将任务类型与 ~/.claude/cli-tools.json 中定义的标签匹配

任务类型	要匹配的常见标签
安全审计	`分析`、`analysis`、`security`
错误诊断	`Debug`、`分析`、`analysis`
实现	`implementation`、（任何启用工具）
测试	`testing`、（任何启用工具）
重构	`refactoring`、（任何启用工具）
文档	`documentation`、（任何启用工具）

选择逻辑: 查找 tags 数组包含匹配关键字的工具，否则使用第一个启用工具。

后备链

当主工具失败时（基于 ~/.claude/cli-tools.json 配置）：

检查同一工具的 secondaryModel（使用配置中的 secondaryModel）
尝试下一个具有匹配标签的启用工具（扫描配置中的启用工具）
后备到默认启用工具（配置中第一个启用工具）

示例后备:

工具1: primaryModel 失败
  ↓
尝试工具1: secondaryModel
  ↓ （如果失败）
尝试工具2: primaryModel（下一个具有匹配标签的启用工具）
  ↓ （如果失败）
尝试默认: 第一个启用工具

权限框架

单次使用授权: 每次执行需要明确的用户指令。先前授权不延续。

模式层次结构:

分析: 只读，安全用于自动执行
写入: 创建/修改/删除文件 - 需要显式 --mode write
审查: Git-aware 代码审查（仅 codex） - 需要显式 --mode review
例外: 用户提供明确指令，如“修改”、“创建”、“实现”

自动调用触发器

主动 CLI 调用 - 在遇到这些场景时自动调用 ccw cli：

触发器	建议规则	何时
自我修复失败	`analysis-diagnose-bug-root-cause`	1+ 次修复尝试失败后
模糊需求	`planning-breakdown-task-steps`	任务描述缺乏清晰度
架构决策	`planning-plan-architecture-design`	复杂功能需要设计
模式不确定性	`analysis-analyze-code-patterns`	不确定现有约定
关键代码路径	`analysis-assess-security-risks`	安全/性能敏感

自动调用的执行原则

默认模式: --mode 分析（只读，安全）
无需确认: 触发器匹配时主动调用
等待结果: 在下一个操作前完成分析
工具选择: 使用上下文适当工具或后备链
规则灵活性: 建议规则是指导，根据需要调整

最佳实践

核心原则

配置驱动 - 所有工具选择来自 cli-tools.json
基于标签的路由 - 将任务需求与工具能力匹配
早用常用工具 - 工具比手动分析更快、更彻底
统一 CLI - 始终使用 ccw cli -p 进行一致的参数处理
默认分析 - 对于只读省略 --mode，对于修改明确使用 --mode write
使用 --rule 加载模板 - 自动加载协议 + 模板附加到提示
写入保护 - 对于文件操作需要显式 --mode write

工作流原则

使用统一接口 - 始终 ccw cli -p 格式
始终包含模板 - 使用 --rule <模板名称> 加载模板
具体明确 - 清晰的目的、任务、预期字段
包括约束 - 文件模式、范围在约束中
利用内存上下文 - 当基于先前工作时
首先发现模式 - 在 CLI 执行前使用 rg/MCP
默认全上下文 - 使用 @**/* 除非需要特定文件

规划清单

[ ] 定义目的 - 清晰目标和意图
[ ] 选择模式 - --mode 分析|写入|审查
[ ] 收集上下文 - 文件引用 + 内存（默认 @**/*）
[ ] 目录导航 - 如果需要，使用 --cd 和/或 --includeDirs
[ ] 选择工具 - 显式 --tool 或基于标签的自动选择
[ ] 规则模板 - --rule <模板名称> 加载模板
[ ] 约束 - 领域约束在约束字段中

与 CLAUDE.md 指令集成

来自全局 CLAUDE.md:

对于 Task 工具代理调用，始终使用 run_in_background: false
默认: 对于 CLI 调用，使用 Bash run_in_background: true
CLI 调用后: 立即停止输出，等待钩子回调
等待结果: 必须在采取写入操作前等待 CLI 分析
重视每次调用: 从不浪费分析结果，在提出解决方案前汇总

来自 cli-tools-usage.md:

严格遵循 cli-tools.json 配置
配置驱动的工具选择
带 --rule 自动加载的模板系统
具有单次使用授权的权限框架
常见失败场景的自动调用触发器

名称: ccw-cli-tools 描述: CLI 工具执行规范 (gemini/claude/codex/qwen/opencode)，具有统一提示模板、模式选项和自动调用触发器，用于代码分析和实现任务。支持可配置的CLI端点，用于分析、写入和审查模式。 版本: 1.0.0

CLI 工具 - 统一执行框架

初始化（必需的第一步）

流程

配置参考

配置文件位置

读取配置

配置结构

预期工具（仅参考）

配置字段

通用提示模板

字段规范

目的（目标定义）

任务（操作步骤）

模式（权限级别）

上下文（文件范围 + 内存）

预期（输出规范）

约束（领域边界）

CLI 执行模式

模式: 分析

模式: 写入

模式: 审查

命令结构

基本命令

命令选项

高级目录配置

工作目录（--cd）

包含目录（--includeDirs）

会话恢复

可用规则模板

模板系统

通用模板

分析模板

规划模板

开发模板

任务类型特定示例

示例 1: 安全分析（只读）

示例 2: 功能实现（写入模式）

示例 3: 错误根本原因分析

示例 4: 代码审查（Codex 审查模式）

工具选择策略

选择算法

选择决策树

常见标签路由

后备链

权限框架

自动调用触发器

自动调用的执行原则

最佳实践

核心原则

工作流原则

规划清单

与 CLAUDE.md 指令集成

名称: ccw-cli-tools 描述: CLI 工具执行规范 (gemini/claude/codex/qwen/opencode)，具有统一提示模板、模式选项和自动调用触发器，用于代码分析和实现任务。支持可配置的CLI端点，用于分析、写入和审查模式。版本: 1.0.0

工作目录（`--cd`）

包含目录（`--includeDirs`）