sherpy-cli

Sherpy CLI

根据架构验证 Sherpy YAML 文档，并将其转换为格式化的 Markdown。确保规划文档符合结构要求，再用于实施工作流。

使用场景

在以下情况下调用此技能：

• 验证 Sherpy YAML 文档（业务需求、技术需求、里程碑、任务、时间线、QA 计划、差距分析）
• 转换有效的 YAML，生成易读的 Markdown 文档
• 检查文档结构，确保其符合规划工作流的要求
• 生成规划材料的文档
• 检查规划文档中的验证错误或警告

支持的文档类型

类型	文件模式	用途
business-requirements	business-requirements.yaml	包含角色和用例的业务需求
technical-requirements	technical-requirements.yaml	技术规格和架构决策
milestones	milestones.yaml	包含依赖关系的项目里程碑
milestone-tasks	milestone-m*.tasks.yaml	详细的任务分解（每项 30-150 分钟）
timeline	timeline.yaml	包含倒排日期的交付时间线
qa-test-plan	qa-test-plan.yaml	QA 测试套件和测试用例
gap-analysis	gap-analysis-worksheet.yaml	差距分析工作表

用法

基本验证

# Validate a document
sherpy validate -t business-requirements -f docs/business-requirements.yaml

# Validate with strict mode (warnings become errors)
sherpy validate -t business-requirements -f docs/business-requirements.yaml --strict

转换为 Markdown

# Convert to stdout
sherpy to-markdown -t business-requirements -f docs/business-requirements.yaml

# Convert to file
sherpy to-markdown -t business-requirements -f docs/business-requirements.yaml -o output.md

列出文档类型

sherpy types

加载技能提示词说明

输出供 AI Agent 使用的技能提示词说明（仅限 CLI 功能）：

# List available prompts
sherpy prompt --list

# Output specific skill instructions (for AI agents)
sherpy prompt -t business-requirements-interview
sherpy prompt -t implementation-planner
sherpy prompt -t qa-test-plan

sherpy prompt 命令会输出内嵌的技能说明，不包含 YAML frontmatter。与单独安装技能文件相比，这种方式可以更高效地使用令牌。内容会在构建时嵌入二进制文件。

可用提示词：

• gap-analysis-worksheet、business-requirements-interview、technical-requirements-interview
• style-anchors-collection、implementation-planner、implementation-plan-review
• definition-of-done、architecture-decision-record、delivery-timeline
• qa-test-plan、developer-summary、executive-summary

另请参阅：sherpy-cli-planner 技能，了解通过 CLI 编排规划工作流。

验证功能

Sherpy CLI 可执行全面验证：

架构验证

• ✅ 必填字段存在且类型正确
• ✅ 字段长度限制（最小/最大字符数）
• ✅ 枚举值（优先级、类型、策略）
• ✅ 日期格式（YYYY-MM-DD）

跨字段验证

• ✅ ID 连续递增（FR-1、FR-2、FR-3）
• ✅ ID 引用（用例中的参与者必须存在于角色中）
• ✅ 依赖关系解析（任务引用有效的任务 ID）
• ✅ 检测循环依赖

业务规则

• ✅ 里程碑数量与时间线条目一致
• ✅ 任务时长不超过上限
• ✅ 倒排日期计算
• ✅ QA 覆盖率
• ✅ 分配比例总和为 100%

输出模式

• 默认：显示错误，将警告作为信息显示
• 严格：将警告提升为错误（用于 CI/CD）
• 详细：提供带上下文的详细错误消息

安全功能

Sherpy CLI 包含多项安全防护：

路径遍历防护

• 验证文件路径，防止 ../../etc/passwd 攻击
• 强制执行 MaxDepth
• 检测并阻止符号链接

文件大小限制

• 文件最大为 10MB
• 提前拒绝超大文件，避免内存耗尽
• 防御 DoS 攻击

安全权限

• 输出文件以 0600 权限创建（仅用户可读写）
• 不允许组或其他用户访问
• 保护敏感的规划文档

注入防护

• 转义 Markdown 特殊字符
• 对 HTML 实体进行编码
• 防止生成的文档中出现 XSS

ReDoS 防护

• MaxIDLength = 100 个字符
• 在执行正则表达式之前验证长度
• 防止 CPU 耗尽攻击

工作流集成

Sherpy 规划工作流

使用 Sherpy 规划技能时，请在生成文档后进行验证：

# After business-requirements-interview
sherpy validate -t business-requirements -f docs/requirements/business-requirements.yaml --strict

# After technical-requirements-interview
sherpy validate -t technical-requirements -f docs/requirements/technical-requirements.yaml --strict

# After implementation-planner
sherpy validate -t milestones -f docs/implementation/milestones.yaml --strict
sherpy validate -t milestone-tasks -f docs/implementation/tasks/milestone-m0.tasks.yaml --strict

# After delivery-timeline
sherpy validate -t timeline -f docs/delivery/timeline.yaml --strict

# After qa-test-plan
sherpy validate -t qa-test-plan -f docs/delivery/qa-test-plan.yaml --strict

提交前验证

在提交前钩子中添加验证，以便尽早发现错误：

#!/bin/bash
# .git/hooks/pre-commit

echo "Validating Sherpy documents..."

# Find all YAML files in docs/
for file in docs/**/*.yaml; do
  if [ -f "$file" ]; then
    # Determine type from path
    case "$file" in
      *business-requirements.yaml)
        sherpy validate -t business-requirements -f "$file" --strict || exit 1
        ;;
      *technical-requirements.yaml)
        sherpy validate -t technical-requirements -f "$file" --strict || exit 1
        ;;
      *milestones.yaml)
        sherpy validate -t milestones -f "$file" --strict || exit 1
        ;;
      *tasks.yaml)
        sherpy validate -t milestone-tasks -f "$file" --strict || exit 1
        ;;
      *timeline.yaml)
        sherpy validate -t timeline -f "$file" --strict || exit 1
        ;;
      *qa-test-plan.yaml)
        sherpy validate -t qa-test-plan -f "$file" --strict || exit 1
        ;;
      *gap-analysis*.yaml)
        sherpy validate -t gap-analysis -f "$file" --strict || exit 1
        ;;
    esac
  fi
done

echo "✓ All documents validated successfully"

CI/CD 集成

GitHub Actions

name: Validate Sherpy Documents

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install Sherpy CLI
        run: go install github.com/validkeys/sherpy@latest
      
      - name: Validate Planning Documents
        run: |
          sherpy validate -t business-requirements -f docs/requirements/business-requirements.yaml --strict
          sherpy validate -t technical-requirements -f docs/requirements/technical-requirements.yaml --strict
          sherpy validate -t milestones -f docs/implementation/milestones.yaml --strict

GitLab CI

validate-docs:
  stage: test
  image: golang:1.26
  script:
    - go install github.com/validkeys/sherpy@latest
    - sherpy validate -t business-requirements -f docs/requirements/business-requirements.yaml --strict
    - sherpy validate -t technical-requirements -f docs/requirements/technical-requirements.yaml --strict

生成文档

从所有规划产物生成 Markdown 文档：

#!/bin/bash
# generate-docs.sh

set -e

echo "Generating documentation from YAML sources..."

# Validate all documents first
echo "1. Validating documents..."
sherpy validate -t business-requirements -f docs/requirements/business-requirements.yaml --strict
sherpy validate -t technical-requirements -f docs/requirements/technical-requirements.yaml --strict
sherpy validate -t milestones -f docs/implementation/milestones.yaml --strict

# Convert to markdown
echo "2. Converting to markdown..."
mkdir -p docs/generated

sherpy to-markdown -t business-requirements \
  -f docs/requirements/business-requirements.yaml \
  -o docs/generated/business-requirements.md

sherpy to-markdown -t technical-requirements \
  -f docs/requirements/technical-requirements.yaml \
  -o docs/generated/technical-requirements.md

sherpy to-markdown -t milestones \
  -f docs/implementation/milestones.yaml \
  -o docs/generated/milestones.md

echo "✓ Documentation generated in docs/generated/"

常见验证错误

顺序 ID 错误

# ❌ Wrong: Non-sequential IDs
functional_requirements:
  - id: FR-1
  - id: FR-3  # Error: expected FR-2

# ✅ Correct: Sequential IDs
functional_requirements:
  - id: FR-1
  - id: FR-2

循环依赖错误

# ❌ Wrong: Circular dependency
milestones:
  - id: m0
    dependencies: [m1]
  - id: m1
    dependencies: [m0]  # Error: circular dependency

# ✅ Correct: Linear dependencies
milestones:
  - id: m0
    dependencies: []
  - id: m1
    dependencies: [m0]

无效引用错误

# ❌ Wrong: Reference to non-existent persona
use_cases:
  - actor: "AdminUser"  # Error: AdminUser not in personas

# ✅ Correct: Reference existing persona
personas:
  - name: "AdminUser"
    role: "Administrator"

use_cases:
  - actor: "AdminUser"  # OK

任务时长错误

# ❌ Wrong: Task exceeds max duration
tasks:
  - id: m0-001
    estimate_minutes: 200  # Error: exceeds max 150 minutes

# ✅ Correct: Task within limits
tasks:
  - id: m0-001
    estimate_minutes: 120  # OK

最佳实践

1. 转换前先验证

转换为 Markdown 前，务必先验证文档：

sherpy validate -t business-requirements -f input.yaml --strict && \
  sherpy to-markdown -t business-requirements -f input.yaml -o output.md

2. 在 CI/CD 中使用严格模式

在自动化工作流中启用严格模式，以便发现所有问题：

sherpy validate -t business-requirements -f docs/file.yaml --strict

3. 每个规划步骤后都进行验证

运行任何 Sherpy 规划技能后，都要验证输出：

# After /business-requirements-interview
sherpy validate -t business-requirements -f docs/requirements/business-requirements.yaml --strict

# After /implementation-planner
sherpy validate -t milestones -f docs/implementation/milestones.yaml --strict
for file in docs/implementation/tasks/*.yaml; do
  sherpy validate -t milestone-tasks -f "$file" --strict
done

4. 检查文件权限

确认输出文件具有安全的权限：

sherpy to-markdown -t business-requirements -f input.yaml -o output.md
ls -l output.md  # Should show -rw------- (600)

5. 在脚本中使用绝对路径

避免自动化过程中的路径混淆：

DOCS_DIR="$(cd "$(dirname "$0")" && pwd)/docs"
sherpy validate -t business-requirements -f "$DOCS_DIR/requirements/business-requirements.yaml"

6. 批量验证已更改的文件

只验证已修改的文档：

git diff --name-only HEAD | grep '\.yaml$' | while read file; do
  type=$(basename "$file" .yaml)
  sherpy validate -t "$type" -f "$file" --strict
done

退出代码

• 0 - 成功（验证通过，转换成功）
• 1 - 验证失败或命令错误
• 2 - 文件未找到或读取错误

安装

从源代码安装

git clone https://github.com/validkeys/sherpy.git
cd sherpy
make build
sudo make install

使用 Go 安装

go install github.com/validkeys/sherpy@latest

验证安装

sherpy types

故障排除

错误："file not found"

检查文件是否存在，并使用绝对路径：

ls -la docs/business-requirements.yaml
sherpy validate -t business-requirements -f "$(pwd)/docs/business-requirements.yaml"

错误："unknown document type"

列出有效类型并检查拼写：

sherpy types
# Use exact type name: business-requirements (not business_requirements)

错误："failed to parse YAML"

检查 YAML 语法：

yamllint docs/business-requirements.yaml
# Common issues: mixed tabs/spaces, incorrect indentation, unquoted special chars

错误："path traversal blocked"

不要使用父目录引用：

# ❌ Blocked
sherpy validate -t business-requirements -f ../../etc/passwd

# ✅ Use absolute paths or paths within working directory
sherpy validate -t business-requirements -f /absolute/path/to/file.yaml
sherpy validate -t business-requirements -f ./docs/file.yaml

错误："file exceeds maximum size"

文件必须小于 10MB：

# Check file size
stat -f%z docs/file.yaml  # macOS
stat -c%s docs/file.yaml  # Linux

# Maximum: 10485760 bytes (10MB)

相关技能

• business-requirements-interview - 生成 business-requirements.yaml
• technical-requirements-interview - 生成 technical-requirements.yaml
• implementation-planner - 生成 milestones.yaml 和任务文件
• delivery-timeline - 生成 timeline.yaml
• qa-test-plan - 生成 qa-test-plan.yaml
• gap-analysis-worksheet - 生成 gap-analysis-worksheet.yaml
• sherpy-flow - 编排完整的规划工作流并进行验证

文档

• GitHub：https://github.com/validkeys/sherpy
• README：README.md
• 使用指南：USAGE.md
• 安全：SECURITY.md

示例

验证目录中的所有文档

#!/bin/bash
# validate-all.sh

DOCS_DIR="docs"
ERRORS=0

for file in "$DOCS_DIR"/**/*.yaml; do
  if [ -f "$file" ]; then
    echo "Validating $file..."
    
    # Determine type from filename/path
    case "$file" in
      *business-requirements.yaml) type="business-requirements" ;;
      *technical-requirements.yaml) type="technical-requirements" ;;
      *milestones.yaml) type="milestones" ;;
      *tasks.yaml) type="milestone-tasks" ;;
      *timeline.yaml) type="timeline" ;;
      *qa-test-plan.yaml) type="qa-test-plan" ;;
      *gap-analysis*.yaml) type="gap-analysis" ;;
      *) continue ;;
    esac
    
    if ! sherpy validate -t "$type" -f "$file" --strict; then
      ERRORS=$((ERRORS + 1))
    fi
  fi
done

if [ $ERRORS -eq 0 ]; then
  echo "✓ All documents validated successfully"
  exit 0
else
  echo "✗ Validation failed for $ERRORS document(s)"
  exit 1
fi

将所有文档转换为 Markdown

#!/bin/bash
# convert-all.sh

mkdir -p docs/generated

TYPES=(
  "business-requirements:docs/requirements/business-requirements.yaml"
  "technical-requirements:docs/requirements/technical-requirements.yaml"
  "milestones:docs/implementation/milestones.yaml"
  "timeline:docs/delivery/timeline.yaml"
  "qa-test-plan:docs/delivery/qa-test-plan.yaml"
)

for entry in "${TYPES[@]}"; do
  IFS=':' read -r type file <<< "$entry"
  
  if [ -f "$file" ]; then
    output="docs/generated/$(basename "$file" .yaml).md"
    echo "Converting $file -> $output"
    
    if sherpy validate -t "$type" -f "$file" --strict; then
      sherpy to-markdown -t "$type" -f "$file" -o "$output"
      echo "✓ Converted $type"
    else
      echo "✗ Validation failed for $file, skipping conversion"
    fi
  fi
done

echo "✓ Conversion complete - see docs/generated/"

集成到 Makefile

.PHONY: validate validate-strict convert-all docs

# Validate all Sherpy documents
validate:
	@echo "Validating Sherpy documents..."
	@sherpy validate -t business-requirements -f docs/requirements/business-requirements.yaml
	@sherpy validate -t technical-requirements -f docs/requirements/technical-requirements.yaml
	@sherpy validate -t milestones -f docs/implementation/milestones.yaml
	@echo "✓ Validation complete"

# Validate with strict mode (for CI/CD)
validate-strict:
	@echo "Validating Sherpy documents (strict mode)..."
	@sherpy validate -t business-requirements -f docs/requirements/business-requirements.yaml --strict
	@sherpy validate -t technical-requirements -f docs/requirements/technical-requirements.yaml --strict
	@sherpy validate -t milestones -f docs/implementation/milestones.yaml --strict
	@sherpy validate -t timeline -f docs/delivery/timeline.yaml --strict
	@sherpy validate -t qa-test-plan -f docs/delivery/qa-test-plan.yaml --strict
	@echo "✓ Strict validation passed"

# Convert all documents to markdown
convert-all:
	@mkdir -p docs/generated
	@echo "Converting Sherpy documents to markdown..."
	@sherpy to-markdown -t business-requirements -f docs/requirements/business-requirements.yaml -o docs/generated/business-requirements.md
	@sherpy to-markdown -t technical-requirements -f docs/requirements/technical-requirements.yaml -o docs/generated/technical-requirements.md
	@sherpy to-markdown -t milestones -f docs/implementation/milestones.yaml -o docs/generated/milestones.md
	@sherpy to-markdown -t timeline -f docs/delivery/timeline.yaml -o docs/generated/timeline.md
	@sherpy to-markdown -t qa-test-plan -f docs/delivery/qa-test-plan.yaml -o docs/generated/qa-test-plan.md
	@echo "✓ Conversion complete"

# Generate all documentation
docs: validate-strict convert-all
	@echo "✓ Documentation generated in docs/generated/"

总结

Sherpy CLI 是 Sherpy 规划文档的验证和转换引擎。使用它可以：

1. 验证 使用前根据架构检查 YAML 文档
2. 转换 有效的 YAML，生成易读的 Markdown 文档
3. 集成 将验证纳入 CI/CD 流水线
4. 执行 使用严格模式落实文档质量标准
5. 生成 根据规划产物生成文档

规划技能生成文档后，务必进行验证，以便尽早发现结构错误。在自动化工作流中使用严格模式，确保规划文档达到生产就绪标准。