docs: 标准化命令文档格式,移除表情符号并添加命令模板规范

更新所有命令文档以提高可读性和一致性:
- 移除所有表情符号(⚠️, , , ▸等),使用纯文本替代
- 统一标题格式,改进章节结构
- 简化状态指示器和格式标记
- 添加三个新的命令模板规范文档

新增文档:
- COMMAND_FLOW_STANDARD.md - 标准命令流程规范
- COMMAND_TEMPLATE_EXECUTOR.md - 执行器命令模板
- COMMAND_TEMPLATE_ORCHESTRATOR.md - 编排器命令模板

影响范围:
- CLI命令(cli-init, codex-execute, discuss-plan, execute)
- 内存管理命令(skill-memory, tech-research, workflow-skill-memory)
- 任务管理命令(breakdown, create, execute, replan)
- 工作流命令(所有workflow相关命令)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
2025-11-05 21:48:43 +08:00
parent e898ebc322
commit 967e3805b7
25 changed files with 863 additions and 310 deletions

274
COMMAND_FLOW_STANDARD.md Normal file
View File

@@ -0,0 +1,274 @@
# Command Flow Expression Standard
**用途**规范命令文档中Task、SlashCommand、Skill和Bash调用的标准表达方式
**版本**v2.1.0
---
## 核心原则
1. **统一格式** - 所有调用使用标准化格式
2. **清晰参数** - 必需参数明确标注,可选参数加方括号
3. **减少冗余** - 避免不必要的echo命令和管道操作
4. **工具优先** - 优先使用专用工具Write/Read/Edit而非Bash变通
5. **可读性** - 保持缩进和换行的一致性
---
## 1. Task调用标准Agent启动
### 标准格式
```javascript
Task(
subagent_type="agent-type",
description="Brief description",
prompt=`
FULL TASK PROMPT HERE
`
)
```
### 规范要求
- `subagent_type`: Agent类型字符串
- `description`: 简短描述5-10词动词开头
- `prompt`: 完整任务提示(使用反引号包裹多行内容)
- 参数字段缩进2空格
### 正确示例
```javascript
// CLI执行agent
Task(
subagent_type="cli-execution-agent",
description="Analyze codebase patterns",
prompt=`
PURPOSE: Identify code patterns for refactoring
TASK: Scan project files and extract common patterns
MODE: analysis
CONTEXT: @src/**/*
EXPECTED: Pattern list with usage examples
`
)
// 代码开发agent
Task(
subagent_type="code-developer",
description="Implement authentication module",
prompt=`
GOAL: Build JWT-based authentication
SCOPE: User login, token validation, session management
CONTEXT: @src/auth/**/* @CLAUDE.md
`
)
```
---
## 2. SlashCommand调用标准
### 标准格式
```javascript
SlashCommand(command="/category:command-name [flags] arguments")
```
### 规范要求
单行调用 | 双引号包裹 | 完整路径`/category:command-name` | 参数顺序: 标志→参数值
### 正确示例
```javascript
// 无参数
SlashCommand(command="/workflow:status")
// 带标志和参数
SlashCommand(command="/workflow:session:start --auto \"task description\"")
// 变量替换
SlashCommand(command="/workflow:tools:context-gather --session [sessionId] \"description\"")
// 多个标志
SlashCommand(command="/workflow:plan --agent --cli-execute \"feature description\"")
```
---
## 3. Skill调用标准
### 标准格式
```javascript
Skill(command: "skill-name")
```
### 规范要求
单行调用 | 冒号语法`command:` | 双引号包裹skill-name
### 正确示例
```javascript
// 项目SKILL
Skill(command: "claude_dms3")
// 技术栈SKILL
Skill(command: "react-dev")
// 工作流SKILL
Skill(command: "workflow-progress")
// 变量替换
Skill(command: "${skill_name}")
```
---
## 4. Bash命令标准
### 核心原则:优先使用专用工具
**工具优先级**:
1. **Write工具** → 创建/覆盖文件内容
2. **Edit工具** → 修改现有文件内容
3. **Read工具** → 读取文件内容
4. **Bash命令** → 仅用于真正的系统操作git, npm, test等
### 标准格式
```javascript
bash(command args)
```
### 合理使用Bash的场景
```javascript
// ✅ Git操作
bash(git status --short)
bash(git commit -m "commit message")
// ✅ 包管理器和测试
bash(npm install)
bash(npm test)
// ✅ 文件系统查询和文本处理
bash(find .workflow -name "*.json" -type f)
bash(rg "pattern" --type js --files-with-matches)
```
### 避免Bash的场景
```javascript
// ❌ 文件创建/写入 → 使用Write工具
bash(echo "content" > file.txt) // 错误
Write({file_path: "file.txt", content: "content"}) // 正确
// ❌ 文件读取 → 使用Read工具
bash(cat file.txt) // 错误
Read({file_path: "file.txt"}) // 正确
// ❌ 简单字符串处理 → 在代码中处理
bash(echo "text" | tr '[:upper:]' '[:lower:]') // 错误
"text".toLowerCase() // 正确
```
---
## 5. 组合调用模式(伪代码准则)
### 核心准则
直接写执行逻辑无FUNCTION/END包裹| 用`#`注释分段 | 变量赋值`variable = value` | 条件`IF/ELSE` | 循环`FOR` | 验证`VALIDATE` | 错误`ERROR + EXIT 1`
### 顺序调用(依赖关系)
```pseudo
# Phase 1-2: Session and Context
sessionId = SlashCommand(command="/workflow:session:start --auto \"description\"")
PARSE sessionId from output
VALIDATE: bash(test -d .workflow/{sessionId})
contextPath = SlashCommand(command="/workflow:tools:context-gather --session {sessionId} \"desc\"")
context_json = READ(contextPath)
# Phase 3-4: Conditional and Agent
IF context_json.conflict_risk IN ["medium", "high"]:
SlashCommand(command="/workflow:tools:conflict-resolution --session {sessionId}")
Task(subagent_type="action-planning-agent", description="Generate tasks", prompt=`SESSION: {sessionId}`)
VALIDATE: bash(test -f .workflow/{sessionId}/IMPL_PLAN.md)
RETURN summary
```
### 并行调用(无依赖)
```pseudo
PARALLEL_START:
check_git = bash(git status)
check_count = bash(find .workflow -name "*.json" | wc -l)
check_skill = Skill(command: "project-name")
WAIT_ALL_COMPLETE
VALIDATE results
RETURN summary
```
### 条件分支调用
```pseudo
IF task_type CONTAINS "test": agent = "test-fix-agent"
ELSE IF task_type CONTAINS "implement": agent = "code-developer"
ELSE: agent = "universal-executor"
Skill(command: "project-name")
Task(subagent_type=agent, description="Execute task", prompt=build_prompt(task_type))
VALIDATE output
RETURN result
```
---
## 6. 变量和占位符规范
| 上下文 | 格式 | 示例 |
|--------|------|------|
| **Markdown说明** | `[variableName]` | `[sessionId]`, `[contextPath]` |
| **JavaScript代码** | `${variableName}` | `${sessionId}`, `${contextPath}` |
| **Bash命令** | `$variable` | `$session_id`, `$context_path` |
---
## 7. 快速检查清单
**Task**: subagent_type已指定 | description≤10词 | prompt用反引号 | 缩进2空格
**SlashCommand**: 完整路径 `/category:command` | 标志在前 | 变量用`[var]` | 双引号包裹
**Skill**: 冒号语法 `command:` | 双引号包裹 | 单行格式
**Bash**: 能用Write/Edit/Read工具吗| 避免不必要echo | 真正的系统操作
---
## 8. 常见错误及修复
```javascript
// ❌ 错误1: Bash中不必要的echo
bash(echo '{"status":"active"}' > status.json)
// ✅ 正确: 使用Write工具
Write({file_path: "status.json", content: '{"status":"active"}'})
// ❌ 错误2: Task单行格式
Task(subagent_type="agent", description="Do task", prompt=`...`)
// ✅ 正确: 多行格式
Task(subagent_type="agent", description="Do task", prompt=`...`)
// ❌ 错误3: Skill使用等号
Skill(command="skill-name")
// ✅ 正确: 使用冒号
Skill(command: "skill-name")
```