zco-claude 0.0.8__py3-none-any.whl

ClaudeSettings/skills/zco-help/SKILL.md

@@ -0,0 +1,601 @@
+---
+name: zco-help
+description: 显示当前项目中可用的 Claude Code 工具（skills、commands、rules）及其用途和使用方式。
+allowed-tools: Bash, Read, Glob
+---
+
+# Claude Code 工具帮助
+
+## 🎯 Skill 用途
+
+快速查看当前项目中可用的 Claude Code 工具及其使用方法。
+
+**核心功能**：
+- **扫描 Skills**：列出所有自定义技能（zco-* 前缀）
+- **扫描 Commands**：列出可执行命令脚本
+- **扫描 Rules**：列出编码规范和开发规则
+- **提取信息**：从 SKILL.md 的 YAML front matter 提取工具描述
+- **分类展示**：按类型分类，表格形式展示
+- **详细查看**：支持查看特定 skill 的详细信息
+
+## 📋 何时使用此 Skill
+
+当用户需要了解项目中可用的 Claude Code 工具时：
+
+1. **查看所有工具**
+   - "有哪些可用的 skills？"
+   - "显示帮助信息"
+   - "/zco-help"
+
+2. **查看特定类型**
+   - "显示所有 skills"
+   - "列出编码规范"
+   - "/zco-help skills"
+   - "/zco-help rules"
+
+3. **查看特定工具详情**
+   - "zco-plan 怎么用？"
+   - "show me details of zco-plan"
+   - "/zco-help zco-plan"
+
+## 📥 参数说明
+
+**命令格式**：
+```bash
+zco-help [filter]
+```
+
+**参数**：
+- `[filter]` - 可选参数，过滤类型或特定 skill 名称
+  - 不传参数：显示所有工具
+  - `skills`: 只显示 skills
+  - `commands`: 只显示 commands
+  - `rules`: 只显示 rules
+  - `{skill-name}`: 显示特定 skill 的详细信息
+
+**示例**：
+```bash
+zco-help                # 显示所有工具
+zco-help skills         # 只显示 skills
+zco-help rules          # 只显示 rules
+zco-help commands       # 只显示 commands
+zco-help zco-plan       # 显示 zco-plan 详细信息
+```
+
+## 🚀 执行流程
+
+### Step 1: 解析参数
+
+提取过滤参数（如果提供）：
+
+```bash
+# 示例
+filter=""           # 无参数 → 显示所有
+filter="skills"     # 只显示 skills
+filter="zco-plan"   # 显示特定 skill
+```
+
+### Step 2: 扫描 Skills
+
+使用 Glob 扫描 `ClaudeSettings/skills/` 目录：
+
+```bash
+# 查找所有 SKILL.md 文件
+ClaudeSettings/skills/*/SKILL.md
+
+# 遍历每个 skill 目录
+for skill_dir in ClaudeSettings/skills/*/; do
+    skill_name=$(basename "$skill_dir")
+    skill_file="$skill_dir/SKILL.md"
+
+    # 读取 YAML front matter
+    # ...
+done
+```
+
+**提取信息**：
+- `name`: Skill 名称（从 YAML 或目录名）
+- `description`: 简短描述
+- `allowed-tools`: 允许使用的工具（可选）
+
+### Step 3: 扫描 Commands
+
+使用 Bash 扫描 `.claude/commands/` 目录：
+
+```bash
+# 查找所有可执行文件
+ls -1 .claude/commands/
+
+# 提取命令名称和简短描述（如果有注释）
+for cmd in .claude/commands/*; do
+    cmd_name=$(basename "$cmd")
+    # 尝试从脚本第一行提取描述
+    cmd_desc=$(head -2 "$cmd" | grep -E '^#' | sed 's/^# *//')
+done
+```
+
+### Step 4: 扫描 Rules
+
+使用 Bash 扫描 `ClaudeSettings/rules/` 目录：
+
+```bash
+# 查找所有 .md 和 .sh 文件
+find ClaudeSettings/rules -type f \( -name "*.md" -o -name "*.sh" \)
+
+# 提取文件相对路径和第一行标题（如果是 .md）
+for rule_file in ...; do
+    rel_path=$(relative_path_from_rules)
+    # 如果是 .md，提取第一个 # 标题作为描述
+done
+```
+
+### Step 5: 格式化输出
+
+根据过滤参数，生成格式化输出：
+
+**无过滤（显示所有）**：
+```
+🔧 Claude Code 工具帮助
+
+📁 当前项目：{project_name}
+📂 配置目录：.claude/
+
+================================================================================
+📚 Skills (自定义技能)
+================================================================================
+
+名称             | 描述                                    | 用法
+-----------------|----------------------------------------|----------------------
+zco-plan         | 执行结构化开发计划                      | zco-plan {seq}
+zco-plan-new     | 创建新的开发计划                        | zco-plan-new <描述>
+zco-docs-update  | 更新 CLAUDE.md Git 元信息               | zco-docs-update
+zco-help         | 显示 Claude 工具帮助信息                | zco-help [类型]
+
+详细文档：cat ClaudeSettings/skills/{skill-name}/SKILL.md
+
+================================================================================
+📋 Commands (命令脚本)
+================================================================================
+
+名称              | 描述
+------------------|------------------------------------------
+show_env          | 显示环境变量
+zco-clean         | 清理临时文件
+zco-git-summary   | Git 仓库摘要
+zco-git-tag       | Git 标签管理
+
+详细信息：cat .claude/commands/{command-name}
+
+================================================================================
+📖 Rules (编码规范)
+================================================================================
+
+名称                        | 描述
+----------------------------|------------------------------------------
+go/coding-standards.md      | Go 项目编程标准
+go/go-testing.md            | Go 测试规范
+go/check-standards.sh       | 代码标准检查脚本
+go/list-comments.sh         | 列出所有非代码注释
+
+详细文档：cat ClaudeSettings/rules/{rule-path}
+
+================================================================================
+💡 提示
+================================================================================
+
+- 查看 skill 详情：zco-help {skill-name}
+- 查看所有计划：ls docs/plans/
+- 执行计划：zco-plan {seq}
+- 创建计划：zco-plan-new <任务描述>
+
+📚 更多信息：cat CLAUDE.md
+```
+
+**过滤 skills**：
+```
+📚 Claude Code Skills
+
+名称             | 描述                                    | 用法
+-----------------|----------------------------------------|----------------------
+zco-plan         | 执行结构化开发计划                      | zco-plan {seq}
+zco-plan-new     | 创建新的开发计划                        | zco-plan-new <描述>
+zco-docs-update  | 更新 CLAUDE.md Git 元信息               | zco-docs-update
+zco-help         | 显示 Claude 工具帮助信息                | zco-help [类型]
+
+查看详情：zco-help {skill-name}
+```
+
+**查看特定 skill**：
+```
+📚 Skill 详情：zco-plan
+
+名称：zco-plan
+描述：执行结构化开发计划
+允许工具：Bash, Read, Glob
+
+## 用途
+
+自动读取 docs/plans/ 目录下的结构化计划文档，理解任务需求，并以 plan 模式设计实施方案。
+
+## 使用方法
+
+zco-plan {seq_number}
+
+示例：
+  zco-plan 002  # 执行计划 002
+  zco-plan 010  # 执行计划 010
+
+## 详细文档
+
+ClaudeSettings/skills/zco-plan/SKILL.md
+```
+
+## 🔧 实现细节
+
+### YAML Front Matter 解析
+
+**提取字段**：
+
+```bash
+# 提取 name 字段
+name=$(sed -n '/^---$/,/^---$/p' SKILL.md | grep '^name:' | cut -d: -f2- | xargs)
+
+# 提取 description 字段
+desc=$(sed -n '/^---$/,/^---$/p' SKILL.md | grep '^description:' | cut -d: -f2- | xargs)
+
+# 提取 allowed-tools 字段
+tools=$(sed -n '/^---$/,/^---$/p' SKILL.md | grep '^allowed-tools:' | cut -d: -f2- | xargs)
+```
+
+**注意事项**：
+- 使用 `sed` 提取 YAML 块（两个 `---` 之间）
+- 使用 `grep` 匹配特定字段
+- 使用 `cut` 和 `xargs` 清理空格
+
+### Markdown 内容提取
+
+**提取 "## 🎯 Skill 用途" 章节**：
+
+```bash
+# 提取从 "## 🎯 Skill 用途" 到下一个 "##" 之间的内容
+sed -n '/^## 🎯 Skill 用途/,/^##/p' SKILL.md | head -n -1
+```
+
+**提取使用示例**：
+
+```bash
+# 查找包含 "zco-{skill-name}" 的代码块
+grep -A 2 "^zco-${skill_name}" SKILL.md
+```
+
+### 符号链接处理
+
+**问题**：`.claude/skills/` 下的是符号链接
+
+**解决方案**：
+- 使用 `readlink -f` 获取真实路径
+- 或者直接扫描 `ClaudeSettings/skills/`（推荐）
+
+```bash
+# 方式 1：解析符号链接
+for link in .claude/skills/*; do
+    real_path=$(readlink -f "$link")
+    skill_file="$real_path/SKILL.md"
+done
+
+# 方式 2：直接扫描源目录（推荐）
+for skill_dir in ClaudeSettings/skills/*/; do
+    skill_file="$skill_dir/SKILL.md"
+done
+```
+
+### 错误处理
+
+**缺失目录**：
+```bash
+if [ ! -d ".claude/commands" ]; then
+    echo "暂无自定义命令"
+fi
+```
+
+**缺失文件**：
+```bash
+if [ ! -f "$skill_file" ]; then
+    echo "警告：$skill_name 缺少 SKILL.md"
+    continue
+fi
+```
+
+**YAML 解析失败**：
+```bash
+if [ -z "$name" ]; then
+    # 从目录名推断
+    name=$(basename "$skill_dir")
+fi
+```
+
+## 📋 使用示例
+
+### 示例 1: 显示所有工具
+
+**用户输入**：
+```bash
+zco-help
+```
+
+**执行流程**：
+1. ✅ 扫描 Skills：找到 zco-plan, zco-plan-new, zco-docs-update, zco-help
+2. ✅ 扫描 Commands：找到 show_env, zco-clean, zco-git-summary, zco-git-tag
+3. ✅ 扫描 Rules：找到 go/ 下的规则文件
+4. ✅ 格式化输出：分类展示所有工具
+
+**输出**：
+```
+🔧 Claude Code 工具帮助
+
+📁 当前项目：zco-claude-init
+📂 配置目录：.claude/
+
+================================================================================
+📚 Skills (自定义技能)
+================================================================================
+
+名称             | 描述                                    | 用法
+-----------------|----------------------------------------|----------------------
+zco-docs-update  | 更新 CLAUDE.md Git 元信息               | zco-docs-update
+zco-help         | 显示 Claude 工具帮助信息                | zco-help [类型]
+zco-plan         | 执行结构化开发计划                      | zco-plan {seq}
+zco-plan-new     | 创建新的开发计划                        | zco-plan-new <描述>
+
+详细文档：cat ClaudeSettings/skills/{skill-name}/SKILL.md
+
+================================================================================
+📋 Commands (命令脚本)
+================================================================================
+
+名称              | 描述
+------------------|------------------------------------------
+show_env          | 显示环境变量
+zco-clean         | 清理临时文件
+zco-git-summary   | Git 仓库摘要
+zco-git-tag       | Git 标签管理
+
+详细信息：cat .claude/commands/{command-name}
+
+================================================================================
+📖 Rules (编码规范)
+================================================================================
+
+名称                                 | 描述
+-------------------------------------|------------------------------------------
+go/GoBuildAutoVersion.v250425.md     | Go 构建自动版本管理
+go/check-standards.sh                | 代码标准检查脚本
+go/coding-standards.md               | Go 项目编程标准
+go/go-testing.md                     | Go 测试规范
+go/list-comments.sh                  | 列出所有非代码注释
+
+详细文档：cat ClaudeSettings/rules/{rule-path}
+
+================================================================================
+💡 提示
+================================================================================
+
+- 查看 skill 详情：zco-help {skill-name}
+- 查看所有计划：ls docs/plans/
+- 执行计划：zco-plan {seq}
+- 创建计划：zco-plan-new <任务描述>
+
+📚 更多信息：cat CLAUDE.md
+```
+
+### 示例 2: 只显示 Skills
+
+**用户输入**：
+```bash
+zco-help skills
+```
+
+**执行流程**：
+1. ✅ 解析参数：filter = "skills"
+2. ✅ 扫描 Skills：找到所有 zco-* skills
+3. ✅ 格式化输出：只显示 skills 表格
+
+**输出**：
+```
+📚 Claude Code Skills
+
+名称             | 描述                                    | 用法
+-----------------|----------------------------------------|----------------------
+zco-docs-update  | 更新 CLAUDE.md Git 元信息               | zco-docs-update
+zco-help         | 显示 Claude 工具帮助信息                | zco-help [类型]
+zco-plan         | 执行结构化开发计划                      | zco-plan {seq}
+zco-plan-new     | 创建新的开发计划                        | zco-plan-new <描述>
+
+查看详情：zco-help {skill-name}
+详细文档：cat ClaudeSettings/skills/{skill-name}/SKILL.md
+```
+
+### 示例 3: 显示特定 Skill 详情
+
+**用户输入**：
+```bash
+zco-help zco-plan
+```
+
+**执行流程**：
+1. ✅ 解析参数：filter = "zco-plan"
+2. ✅ 查找 skill：ClaudeSettings/skills/zco-plan/SKILL.md
+3. ✅ 读取文件：提取完整信息
+4. ✅ 格式化输出：显示详细信息
+
+**输出**：
+```
+📚 Skill 详情：zco-plan
+
+名称：zco-plan
+描述：读取并执行 docs/plans/ 目录下的项目开发计划。当用户需要执行某个编号的计划任务时使用此 Skill。
+允许工具：Bash, Read, Glob
+
+## 🎯 用途
+
+自动读取 docs/plans/ 目录下的结构化计划文档，理解任务需求，并以 plan 模式设计实施方案。
+
+核心功能：
+- 查找计划文档：根据序号在 docs/plans/ 目录中定位计划文件
+- 读取计划内容：解析 YAML front matter 和 Markdown 内容
+- 执行任务：以 plan 模式理解需求并设计实施方案
+- 智能匹配：支持多版本计划自动选择最新版本
+
+## 📥 使用方法
+
+命令格式：
+  zco-plan {seq_number}
+
+参数：
+  seq_number - 计划序号（必需），任意位数字（1、02、003、0100 均可）
+
+示例：
+  zco-plan 002  # 执行计划 002
+  zco-plan 010  # 执行计划 010
+
+## 📄 详细文档
+
+ClaudeSettings/skills/zco-plan/SKILL.md
+```
+
+### 示例 4: 只显示 Rules
+
+**用户输入**：
+```bash
+zco-help rules
+```
+
+**输出**：
+```
+📖 Claude Code Rules (编码规范)
+
+名称                                 | 描述
+-------------------------------------|------------------------------------------
+go/GoBuildAutoVersion.v250425.md     | Go 构建自动版本管理
+go/check-standards.sh                | 代码标准检查脚本
+go/coding-standards.md               | Go 项目编程标准
+go/go-testing.md                     | Go 测试规范
+go/list-comments.sh                  | 列出所有非代码注释
+
+详细文档：cat ClaudeSettings/rules/{rule-path}
+```
+
+## ⚠️ 注意事项
+
+### 必须遵守的规则
+
+1. **目录扫描**：
+   - Skills：扫描 `ClaudeSettings/skills/`（源目录）
+   - Commands：扫描 `.claude/commands/`（实际目录）
+   - Rules：扫描 `ClaudeSettings/rules/`（源目录）
+
+2. **YAML 解析**：
+   - 必须正确处理多行描述
+   - 处理缺失字段（使用默认值）
+   - 处理格式错误（跳过或警告）
+
+3. **符号链接**：
+   - 正确识别符号链接
+   - 访问真实文件路径
+   - 避免重复扫描
+
+4. **错误处理**：
+   - 目录不存在 → 显示 "暂无..."
+   - 文件读取失败 → 跳过并警告
+   - YAML 解析失败 → 使用目录名作为 fallback
+
+### 推荐做法
+
+1. **表格对齐**：
+   - 使用固定宽度列
+   - 中文字符按 2 个宽度计算
+   - 使用 `|` 分隔列
+
+2. **排序**：
+   - Skills：按字母顺序排序
+   - Commands：按字母顺序排序
+   - Rules：按路径排序
+
+3. **简洁输出**：
+   - 描述限制在 50 字符内
+   - 过长描述使用 "..." 截断
+   - 提供 "查看详情" 提示
+
+### 常见错误
+
+1. **找不到 SKILL.md**：
+   ```
+   警告：zco-example 缺少 SKILL.md 文件
+   → 跳过该 skill
+   ```
+
+2. **YAML 格式错误**：
+   ```
+   警告：zco-example/SKILL.md YAML 解析失败
+   → 使用目录名作为 skill 名称
+   ```
+
+3. **权限问题**：
+   ```
+   错误：无法读取 .claude/commands/script
+   → 检查文件权限
+   ```
+
+## 🔗 相关资源
+
+### 相关文件
+
+- **Skill 源目录**: `ClaudeSettings/skills/`
+- **Rules 源目录**: `ClaudeSettings/rules/`
+- **Commands 目录**: `.claude/commands/`
+- **项目文档**: `CLAUDE.md`
+- **Skills 开发指南**: `ClaudeSettings/skills/README.md`
+
+### 相关 Skills
+
+- `zco-plan` - 执行开发计划
+- `zco-plan-new` - 创建新计划
+- `zco-docs-update` - 更新文档
+- `zco-help` - 显示帮助信息（本 Skill）
+
+### 技术参考
+
+- **Bash 脚本**: 用于扫描目录和解析文件
+- **YAML 解析**: 使用 sed/grep 提取字段
+- **Markdown 格式**: 表格、列表、代码块
+- **符号链接**: readlink, realpath 命令
+
+## 💡 最佳实践
+
+### 1. 保持 SKILL.md 完整
+
+每个 skill 都应该包含：
+- ✅ YAML front matter（name, description, allowed-tools）
+- ✅ 用途说明章节
+- ✅ 使用方法章节
+- ✅ 示例章节
+
+### 2. 使用清晰的描述
+
+描述应该：
+- ✅ 简洁明了（50 字符以内）
+- ✅ 说明核心功能
+- ✅ 避免技术术语过多
+
+### 3. 定期更新
+
+当添加新 skill 时：
+- ✅ 确保 SKILL.md 格式正确
+- ✅ 测试 zco-help 能正确识别
+- ✅ 更新 CLAUDE.md 中的 skills 列表
+
+---
+
+**Skill 版本**: 1.0.0
+**最后更新**: 2026-01-13
+**维护者**: 开发团队