ccw-cli-tools

Name: ccw-cli-tools
Author: catlog22

github.com/catlog22Agent 工作流2.1k72 次安装19 周前更新

代码仓库

关于 ccw-cli-tools

ccw-cli-tools 是面向 Claude 的技能，用结构化提示词和执行流程选择、调用已配置的 CLI 工具。它依据本地配置中的工具状态、模型和标签路由任务，并提供明确的执行模式与可复用规则模板。

主要功能

01配置驱动的工具选择
02按标签路由任务
03统一六字段提示词模板
04分析、写入和审查模式
05可复用规则模板
06会话恢复与上下文范围设置

适用场景

01根据任务能力标签选择 CLI 工具
02为代码分析或安全审查构造结构化提示词
03在明确授权后执行代码修改任务
04恢复多轮或多模型 CLI 会话

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/catlog22/claude-code-workflow --skill ccw-cli-tools

安装后在 Claude Code 中输入/ccw-cli-tools确认已加载。

详细介绍

CLI 工具 - 统一执行框架

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

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

初始化（必须首先执行）

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

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

原因：工具、模型和标签可能会发生变化。配置文件是唯一可信来源。优化：重复使用内存中的配置，避免重复读取文件。

流程

┌─ USER REQUEST
│
├─ STEP 1: Load Configuration
│  ├─ Check if configuration exists in conversation memory
│  └─ If NOT in memory → Read(file_path="~/.claude/cli-tools.json")
│
├─ STEP 2: Understand User Intent
│  ├─ Parse task type (analysis, implementation, security, etc.)
│  ├─ Extract required capabilities (tags)
│  └─ Identify scope (files, modules)
│
├─ STEP 3: Select Tool (based on config)
│  ├─ Explicit --tool specified?
│  │  YES → Validate in config → Use it
│  │  NO  → Match tags with enabled tools → Select best match
│  │       → No match → Use first enabled tool (default)
│  └─ Get primaryModel from config
│
├─ STEP 4: Build Prompt
│  └─ Use 6-field template: PURPOSE, TASK, MODE, CONTEXT, EXPECTED, CONSTRAINTS
│
├─ STEP 5: Select Rule Template
│  ├─ Determine rule from task type
│  └─ Pass via --rule parameter
│
├─ STEP 6: Execute CLI Command
│  └─ ccw cli -p "<PROMPT>" --tool <tool> --mode <mode> --rule <rule>
│
└─ STEP 7: Handle Results
   ├─ On success → Deliver output to user
   └─ On failure → Check secondaryModel or fallback tool

配置参考

配置文件位置

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

重要：先检查对话记忆。仅当配置不在记忆中时才读取文件。

读取配置

优先顺序：先检查对话记忆

加载选项：

选项 1（首选）：如果配置已加载到对话中，则使用内存中的配置
选项 2（备用）：如果配置不在记忆中，则从文件读取

# Read configuration file
cat ~/.claude/cli-tools.json

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

配置结构

JSON 文件包含一个 tools 对象，其中每个工具都有以下字段：

字段	类型	描述	示例
`enabled`	boolean	工具可用状态	`true` 或 `false`
`primaryModel`	string	执行时的默认模型	`"gemini-2.5-pro"`
`secondaryModel`	string	主模型失败时使用的备用模型	`"gemini-2.5-flash"`
`tags`	array	用于路由的能力标签	`["分析", "Debug"]`
`type`	string	工具类型	`"builtin"`、`"cli-wrapper"`、`"api-endpoint"`

预期工具（仅供参考）

配置中通常包含的工具（实际可用性以读取文件为准）：

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

注意：工具、模型和标签的可用情况可能有所不同。使用内存中的配置；如果配置未缓存，则读取 ~/.claude/cli-tools.json。

配置字段

enabled：工具可用状态（boolean）
primaryModel：执行时的默认模型
secondaryModel：主模型失败时使用的备用模型
tags：用于路由的能力标签（分析、Debug、implementation 等）
type：工具类型（builtin、cli-wrapper、api-endpoint）

通用提示词模板

结构：每条 CLI 命令都遵循此 6 字段模板

ccw cli -p "PURPOSE: [goal] + [why] + [success criteria] + [scope]
TASK: • [step 1: specific action] • [step 2: specific action] • [step 3: specific action]
MODE: [analysis|write|review]
CONTEXT: @[file patterns] | Memory: [session/tech/module context]
EXPECTED: [deliverable format] + [quality criteria] + [structure requirements]
CONSTRAINTS: [domain constraints]" --tool <tool-id> --mode <mode> --rule <template>

字段说明

PURPOSE（目标定义）

内容：明确的目标 + 动机 + 成功标准 + 范围边界

组成部分：

目标：具体的任务目标
原因：业务或技术动机
成功：可衡量的成功标准
范围：限定的上下文或文件

示例 - 良好：

PURPOSE: Identify OWASP Top 10 vulnerabilities in auth module to pass security audit;
success = all critical/high issues documented with remediation;
scope = src/auth/** only

示例 - 不佳：

PURPOSE: Analyze code

TASK（操作步骤）

内容：具体、可执行的步骤，使用明确的动词和目标

格式：包含具体操作的项目符号列表

示例 - 良好：

TASK:
• Scan for SQL injection in query builders
• Check XSS in template rendering
• Verify CSRF token validation

示例 - 不佳：

TASK: Review code and find issues

MODE（权限级别）

选项：

analysis - 只读，可安全自动执行
write - 创建/修改/删除文件，完整操作
review - 感知 Git 的代码审查（仅 codex）

规则：

始终明确指定
只读任务默认使用 analysis
文件修改必须显式指定 --mode write
使用 --mode review 搭配 --tool codex 进行感知 Git 的审查

CONTEXT（文件范围 + 记忆）

格式：CONTEXT: @[文件模式] | Memory: [记忆上下文]

文件模式：

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

记忆上下文（在先前工作基础上继续时）：

Memory: Building on auth refactoring (commit abc123), using JWT for sessions
Memory: Integration with auth module, shared error patterns from @shared/utils/errors.ts

EXPECTED（输出规范）

内容：输出格式 + 质量标准 + 结构要求

示例 - 良好：

EXPECTED: Markdown report with:
severity levels (Critical/High/Medium/Low),
file:line references,
remediation code snippets,
priority ranking

示例 - 不佳：

EXPECTED: Report

CONSTRAINTS（领域边界）

内容：范围限制、特殊要求、重点领域

示例 - 良好：

CONSTRAINTS: Focus on authentication | Ignore test files | No breaking changes

示例 - 不佳：

CONSTRAINTS: (missing or too vague)

命令行执行模式

MODE: analysis

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

MODE: write

权限：创建/修改/删除文件
用途：功能实现、缺陷修复、文档编写、代码创建
安全：否 - 需要显式指定 --mode write
要求：必须由用户明确请求

MODE: review

权限：只读（感知 Git 的审查输出）
用途：审查未提交的更改、分支差异、特定提交
工具支持：仅 codex（其他工具按 analysis 处理）
约束：目标标志（--uncommitted、--base、--commit）与提示词互斥

命令结构

基本命令

ccw cli -p "<PROMPT>" --tool <tool-id> --mode <analysis|write|review>

命令选项

选项	描述	示例
`--tool <tool>`	来自配置的工具	`--tool gemini`
`--mode <mode>`	必填：analysis/write/review	`--mode analysis`
`--model <model>`	覆盖模型	`--model gemini-2.5-flash`
`--cd <path>`	工作目录	`--cd src/auth`
`--includeDirs <dirs>`	附加目录	`--includeDirs ../shared,../types`
`--rule <template>`	自动加载模板	`--rule analysis-review-architecture`
`--resume [id]`	恢复会话	`--resume` 或 `--resume <id>`

高级目录配置

工作目录（`--cd`）

使用 --cd 时：

@**/* = 仅工作目录树内的文件
未使用 --includeDirs 时无法引用父级/同级目录
通过缩小上下文范围减少 token 用量

包含目录（`--includeDirs`）

引用外部文件的两步要求：

添加 --includeDirs 参数
在 CONTEXT 中使用 @ 模式引用

# Single directory
ccw cli -p "CONTEXT: @**/* @../shared/**/*" \
  --tool gemini --mode analysis \
  --cd src/auth --includeDirs ../shared

# Multiple directories
ccw cli -p "..." \
  --tool gemini --mode analysis \
  --cd src/auth --includeDirs ../shared,../types,../utils

会话恢复

使用场景：

多轮规划（分析 → 规划 → 实现）
多模型协作（工具 A → 工具 B，围绕同一主题）
主题延续（在先前发现的基础上继续）

用法：

ccw cli -p "Continue analyzing" --tool <tool-id> --mode analysis --resume              # Resume last
ccw cli -p "Fix issues found" --tool <tool-id> --mode write --resume <id>              # Resume specific
ccw cli -p "Merge findings" --tool <tool-id> --mode analysis --resume <id1>,<id2>      # Merge sessions

可用规则模板

模板系统

使用 --rule <template-name> 自动加载协议 + 追加到提示词的模板

通用模板

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 "PURPOSE: Identify OWASP Top 10 vulnerabilities in authentication module to pass security audit; success = all critical/high issues documented with remediation
TASK: • Scan for injection flaws (SQL, command, LDAP) • Check authentication bypass vectors • Evaluate session management • Assess sensitive data exposure
MODE: analysis
CONTEXT: @src/auth/**/* @src/middleware/auth.ts | Memory: Using bcrypt for passwords, JWT for sessions
EXPECTED: Security report with: severity matrix, file:line references, CVE mappings where applicable, remediation code snippets prioritized by risk
CONSTRAINTS: Focus on authentication | Ignore test files
" --tool gemini --mode analysis --rule analysis-assess-security-risks --cd src/auth

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

ccw cli -p "PURPOSE: Implement rate limiting for API endpoints to prevent abuse; must be configurable per-endpoint; backward compatible with existing clients
TASK: • Create rate limiter middleware with sliding window • Implement per-route configuration • Add Redis backend for distributed state • Include bypass for internal services
MODE: write
CONTEXT: @src/middleware/**/* @src/config/**/* | Memory: Using Express.js, Redis already configured, existing middleware pattern in auth.ts
EXPECTED: Production-ready code with: TypeScript types, unit tests, integration test, configuration example, migration guide
CONSTRAINTS: Follow existing middleware patterns | No breaking changes
" --tool gemini --mode write --rule development-implement-feature

示例 3：Bug 根因分析

ccw cli -p "PURPOSE: Fix memory leak in WebSocket connection handler causing server OOM after 24h; root cause must be identified before any fix
TASK: • Trace connection lifecycle from open to close • Identify event listener accumulation • Check cleanup on disconnect • Verify garbage collection eligibility
MODE: analysis
CONTEXT: @src/websocket/**/* @src/services/connection-manager.ts | Memory: Using ws library, ~5000 concurrent connections in production
EXPECTED: Root cause analysis with: memory profile, leak source (file:line), fix recommendation with code, verification steps
CONSTRAINTS: Focus on resource cleanup
" --tool gemini --mode analysis --rule analysis-diagnose-bug-root-cause --cd src

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

# Option 1: Custom focus (reviews uncommitted by default)
ccw cli -p "Focus on security vulnerabilities and error handling" --tool codex --mode review

# Option 2: Target flag only (no prompt with target flags)
ccw cli --tool codex --mode review --uncommitted
ccw cli --tool codex --mode review --base main
ccw cli --tool codex --mode review --commit abc123

工具选择策略

选择算法

步骤 0（必需）：加载配置（优先使用记忆策略）

# Check if configuration exists in conversation memory
# If YES → Use in-memory configuration
# If NO → Read(file_path="~/.claude/cli-tools.json")

然后继续选择：

解析任务意图 → 提取所需能力
加载配置 → 从 JSON 中解析已启用工具及其标签
匹配标签 → 筛选支持所需能力的工具
选择工具 → 按优先级选择（明确指定 > 标签匹配 > 默认）
选择模型 → 使用 primaryModel，若不可用则回退到 secondaryModel

选择决策树

0. LOAD CONFIGURATION (memory-first)
   ├─ In memory? → Use it
   └─ Not in memory? → Read ~/.claude/cli-tools.json
   ↓
1. Explicit --tool specified?
   YES → Validate tool is enabled in config → Use it
   NO  → Proceed to tag-based selection
         ├─ Extract task tags (security, analysis, implementation, etc.)
         │  ├─ Find tools with matching tags
         │  │  ├─ Multiple matches? Use first enabled
         │  │  └─ Single match? Use it
         │  └─ No tag match? Use default tool
         │
         └─ Default: Use first enabled tool in config

常见标签路由

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

任务类型	常见匹配标签
安全审计	`分析`, `analysis`, `security`
Bug 诊断	`Debug`, `分析`, `analysis`
实现	`implementation`，（任意已启用工具）
测试	`testing`，（任意已启用工具）
重构	`refactoring`，（任意已启用工具）
文档	`documentation`，（任意已启用工具）

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

回退链

主要工具失败时（依据 ~/.claude/cli-tools.json 配置）：

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

回退示例：

Tool1: primaryModel fails
  ↓
Try Tool1: secondaryModel
  ↓ (if fails)
Try Tool2: primaryModel (next enabled with matching tags)
  ↓ (if fails)
Try default: first enabled tool

权限框架

单次授权：每次执行都需要用户明确指示。之前的授权不会沿用。

模式层级：

analysis：只读，可安全地自动执行
write：创建/修改/删除文件——需要明确指定 --mode write
review：感知 Git 的代码审查（仅限 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 analysis（只读、安全）
无需确认：触发条件匹配时主动调用
等待结果：完成分析后再执行下一步操作
工具选择：使用适合当前情境的工具或回退链
规则灵活性：建议规则仅供参考，可按需调整

最佳实践

核心原则

配置驱动 - 所有工具选择均来自 cli-tools.json
基于标签的路由 - 将任务要求与工具能力匹配
尽早并频繁使用工具 - 工具比手动分析更快速、更全面
统一 CLI - 始终使用 ccw cli -p，以统一参数处理方式
默认采用分析模式 - 只读操作时省略 --mode，进行修改时明确使用 --mode write
使用 --rule 指定模板 - 自动加载协议和追加到提示词中的模板
写入保护 - 文件操作必须明确指定 --mode write

工作流原则

使用统一接口 - 始终采用 ccw cli -p 格式
始终包含模板 - 使用 --rule <template-name> 加载模板
明确具体 - 清晰填写 PURPOSE、TASK、EXPECTED 字段
包含约束条件 - 在 CONSTRAINTS 中指定文件模式和范围
利用记忆上下文 - 在先前工作基础上继续时使用
先发现模式 - 在执行 CLI 前使用 rg/MCP
默认使用完整上下文 - 除非需要指定文件，否则使用 @**/*

规划清单

明确目的 - 目标和意图清晰
选择模式 - --mode analysis|write|review
收集上下文 - 文件引用 + 记忆（默认 @**/*）
目录导航 - 如有需要，使用 --cd 和/或 --includeDirs
选择工具 - 明确指定 --tool 或基于标签自动选择
规则模板 - --rule <template-name> 加载模板
约束条件 - 在 CONSTRAINTS 字段中填写领域约束

与 CLAUDE.md 指令集成

来自全局 CLAUDE.md：

对 Task 工具的 Agent 调用，始终使用 run_in_background: false
默认：对 CLI 调用使用 Bash run_in_background: true
CLI 调用后：立即停止输出，等待钩子回调
等待结果：必须等待 CLI 分析完成后才能执行写入操作
珍视每次调用：绝不浪费分析结果，汇总后再提出解决方案

来自 cli-tools-usage.md：

严格遵守 cli-tools.json 配置
配置驱动的工具选择
使用 --rule 自动加载的模板系统
采用单次授权的权限框架
针对常见故障场景自动触发调用

支持 Markdown

登录后评论

基本信息

作者: catlog22
仓库: catlog22/claude-code-workflow
分类: Agent 工作流
安装次数: 72
GitHub Stars: 2,119

报告问题

ccw-cli-tools

关于 ccw-cli-tools

主要功能

适用场景

安装

详细介绍

CLI 工具 - 统一执行框架

初始化（必须首先执行）

流程

配置参考

配置文件位置

读取配置

配置结构

预期工具（仅供参考）

配置字段

通用提示词模板

字段说明

PURPOSE（目标定义）

TASK（操作步骤）

MODE（权限级别）

CONTEXT（文件范围 + 记忆）

EXPECTED（输出规范）

CONSTRAINTS（领域边界）

命令行执行模式

MODE: analysis

MODE: write

MODE: review

命令结构

基本命令

命令选项

高级目录配置

工作目录（--cd）

包含目录（--includeDirs）

会话恢复

可用规则模板

模板系统

通用模板

分析模板

规划模板

开发模板

特定任务类型示例

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

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

示例 3：Bug 根因分析

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

工具选择策略

选择算法

选择决策树

常见标签路由

回退链

权限框架

自动调用触发条件

自动调用的执行原则

最佳实践

核心原则

工作流原则

规划清单

与 CLAUDE.md 指令集成

评论

工作目录（`--cd`）

包含目录（`--includeDirs`）