dev-playbooks-cn 1.6.0 → 1.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dev-playbooks-cn",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "description": "AI-driven spec-based development workflow",
   "keywords": [
     "devbooks",
@@ -29,7 +29,8 @@
     "LICENSE",
     "bin/",
     "templates/",
-    "skills/"
+    "skills/",
+    "scripts/"
   ],
   "engines": {
     "node": ">=18"

package/scripts/config-discovery.sh

@@ -0,0 +1,260 @@
+#!/bin/bash
+# scripts/config-discovery.sh
+# DevBooks Protocol Discovery Layer - 配置发现脚本
+#
+# 用途：发现并输出当前项目的 DevBooks 配置
+# 返回格式：key=value（每行一个），可被 Shell 或 AI 解析
+#
+# 优先级：
+#   1. .devbooks/config.yaml（优先检查 root: dev-playbooks/）
+#   2. dev-playbooks/（无 config.yaml 时）
+#   3. project.md（通用模板协议）
+#
+# 用法：
+#   ./config-discovery.sh [project-root]
+#   source <(./config-discovery.sh)  # 直接导入为 shell 变量
+#
+# 功能：
+#   - 支持 dev-playbooks/ 路径
+#   - 自动加载 constitution.md
+#   - 纯 Bash YAML 解析（无 yq 依赖）
+#   - 弃用警告：truth_root/change_root 别名（建议迁移到 paths.specs/paths.changes）
+
+set -euo pipefail
+
+PROJECT_ROOT="${1:-.}"
+
+# 颜色输出（仅在 stderr）
+log_info() { echo "[INFO] $*" >&2; }
+log_warn() { echo "[WARN] $*" >&2; }
+log_error() { echo "[ERROR] $*" >&2; }
+
+# ============================================
+# 纯 Bash YAML 解析（无 yq 依赖）
+# ============================================
+
+# 读取简单键值对
+get_yaml_value() {
+    local file="$1" key="$2"
+    grep "^${key}:" "$file" 2>/dev/null | sed 's/^[^:]*: *//' | tr -d '"'"'" | tr -d '/' || true
+}
+
+# 读取嵌套键（一层深度）
+get_yaml_nested_value() {
+    local file="$1" parent="$2" key="$3"
+    # 查找 parent: 下的 key:
+    awk -v parent="$parent" -v key="$key" '
+        $0 ~ "^" parent ":" { in_parent = 1; next }
+        in_parent && /^[a-z]/ { in_parent = 0 }
+        in_parent && $0 ~ "^  " key ":" {
+            gsub(/^[^:]*: */, "")
+            gsub(/["'"'"']/, "")
+            print
+            exit
+        }
+    ' "$file" 2>/dev/null || true
+}
+
+# ============================================
+# 解析真理根目录
+# ============================================
+
+resolve_truth_root() {
+    local root="$1"
+
+    # 从 config.yaml 读取 root 配置
+    if [[ -f "${root}/.devbooks/config.yaml" ]]; then
+        local config_root
+        config_root=$(get_yaml_value "${root}/.devbooks/config.yaml" "root")
+        if [[ -n "$config_root" && -d "${root}/${config_root}" ]]; then
+            echo "${config_root}"
+            return 0
+        fi
+    fi
+
+    # 检查 dev-playbooks/ 目录
+    if [[ -d "${root}/dev-playbooks" ]]; then
+        echo "dev-playbooks"
+        return 0
+    fi
+
+    # 未找到
+    echo ""
+    return 1
+}
+
+# ============================================
+# 加载宪法
+# ============================================
+
+load_constitution() {
+    local config_root="$1"
+    local constitution_file="${PROJECT_ROOT}/${config_root}/constitution.md"
+
+    if [[ -f "$constitution_file" ]]; then
+        log_info "Loading constitution from: $constitution_file"
+        echo "constitution_loaded=true"
+        echo "constitution_path=${config_root}/constitution.md"
+        return 0
+    else
+        # 检查是否强制要求宪法
+        local require_constitution="false"
+        if [[ -f "${PROJECT_ROOT}/.devbooks/config.yaml" ]]; then
+            require_constitution=$(get_yaml_nested_value "${PROJECT_ROOT}/.devbooks/config.yaml" "constraints" "require_constitution")
+        fi
+
+        if [[ "$require_constitution" == "true" ]]; then
+            log_error "Constitution file missing: $constitution_file"
+            echo "constitution_loaded=false"
+            echo "constitution_path="
+            echo "constitution_error=missing"
+            return 1
+        fi
+
+        log_warn "Constitution file not found (optional): $constitution_file"
+        echo "constitution_loaded=false"
+        echo "constitution_path="
+        return 0
+    fi
+}
+
+# ============================================
+# 检查文件是否存在
+# ============================================
+
+check_file() {
+    [[ -f "$PROJECT_ROOT/$1" ]]
+}
+
+# ============================================
+# 输出配置
+# ============================================
+
+output_config() {
+    echo "config_source=$1"
+    echo "protocol=$2"
+    echo "truth_root=$3"
+    echo "change_root=$4"
+    echo "agents_doc=$5"
+
+    # 可选字段
+    [[ -n "${6:-}" ]] && echo "project_profile=$6"
+    [[ -n "${7:-}" ]] && echo "apply_requires_role=$7"
+}
+
+# ============================================
+# 新格式输出（Dev-Playbooks）
+# ============================================
+
+output_config_v2() {
+    local config_root="$1"
+
+    echo "# Dev-Playbooks Configuration"
+    echo "devbooks_version=2.0"
+    echo "config_root=${config_root}"
+
+    # 从 config.yaml 读取路径配置
+    if [[ -f "${PROJECT_ROOT}/.devbooks/config.yaml" ]]; then
+        local specs_path changes_path staged_path
+        specs_path=$(get_yaml_nested_value "${PROJECT_ROOT}/.devbooks/config.yaml" "paths" "specs")
+        changes_path=$(get_yaml_nested_value "${PROJECT_ROOT}/.devbooks/config.yaml" "paths" "changes")
+        staged_path=$(get_yaml_nested_value "${PROJECT_ROOT}/.devbooks/config.yaml" "paths" "staged")
+
+        echo "specs_dir=${config_root}/${specs_path:-specs/}"
+        echo "changes_dir=${config_root}/${changes_path:-changes/}"
+        echo "staged_dir=${config_root}/${staged_path:-specs/_staged/}"
+    else
+        echo "specs_dir=${config_root}/specs/"
+        echo "changes_dir=${config_root}/changes/"
+        echo "staged_dir=${config_root}/specs/_staged/"
+    fi
+
+    # 适应度配置
+    if [[ -f "${PROJECT_ROOT}/.devbooks/config.yaml" ]]; then
+        local fitness_mode fitness_rules
+        fitness_mode=$(get_yaml_nested_value "${PROJECT_ROOT}/.devbooks/config.yaml" "fitness" "mode")
+        fitness_rules=$(get_yaml_nested_value "${PROJECT_ROOT}/.devbooks/config.yaml" "fitness" "rules_file")
+
+        echo "fitness_mode=${fitness_mode:-warn}"
+        echo "fitness_rules=${config_root}/${fitness_rules:-specs/architecture/fitness-rules.md}"
+    fi
+
+    # AC 追溯配置
+    if [[ -f "${PROJECT_ROOT}/.devbooks/config.yaml" ]]; then
+        local coverage_threshold
+        coverage_threshold=$(get_yaml_nested_value "${PROJECT_ROOT}/.devbooks/config.yaml" "tracing" "coverage_threshold")
+        echo "ac_coverage_threshold=${coverage_threshold:-80}"
+    fi
+}
+
+# ============================================
+# 主逻辑
+# ============================================
+
+main() {
+    # 解析真理根目录
+    local truth_root
+    truth_root=$(resolve_truth_root "$PROJECT_ROOT") || {
+        log_warn "No DevBooks configuration found"
+        log_warn "Searched for:"
+        log_warn "  - .devbooks/config.yaml with root: dev-playbooks/"
+        log_warn "  - dev-playbooks/"
+        log_warn "  - dev-playbooks/project.md"
+        log_warn "  - project.md"
+
+        echo "config_source=none"
+        echo "protocol=unknown"
+        echo "truth_root="
+        echo "change_root="
+        echo "agents_doc="
+
+        exit 1
+    }
+
+    log_info "Found configuration root: $truth_root"
+
+    # 加载宪法（如果存在）
+    load_constitution "$truth_root" || {
+        log_error "Constitution loading failed"
+        exit 1
+    }
+
+    # 根据目录判断协议类型
+    case "$truth_root" in
+        dev-playbooks)
+            # DevBooks 协议
+            log_info "Using DevBooks protocol"
+
+            output_config \
+                ".devbooks/config.yaml" \
+                "devbooks" \
+                "${truth_root}/specs/" \
+                "${truth_root}/changes/" \
+                "${truth_root}/project.md" \
+                "${truth_root}/specs/_meta/project-profile.md" \
+                "true"
+
+            echo ""
+            output_config_v2 "$truth_root"
+            ;;
+
+        *)
+            # Template 协议
+            log_info "Using template protocol"
+
+            output_config \
+                "project.md" \
+                "template" \
+                "specs/" \
+                "changes/" \
+                "project.md" \
+                "specs/_meta/project-profile.md" \
+                "false"
+            ;;
+    esac
+
+    exit 0
+}
+
+# 运行主函数
+main

package/scripts/install-dependencies.sh

@@ -0,0 +1,244 @@
+#!/bin/bash
+# DevBooks 系统依赖安装脚本
+# 支持 macOS (Homebrew) 和 Linux (apt/yum)
+#
+# 用法: ./scripts/install-dependencies.sh [--all | --minimal | --dev]
+#   --minimal  只安装必需依赖 (jq, ripgrep)
+#   --all      安装所有依赖（默认）
+#   --dev      额外安装开发依赖 (shellcheck)
+
+set -euo pipefail
+
+# 颜色输出
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+log_info() { echo -e "${GREEN}[INFO]${NC} $1"; }
+log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
+log_error() { echo -e "${RED}[ERROR]${NC} $1"; }
+
+# 检测操作系统
+detect_os() {
+  case "$(uname -s)" in
+    Darwin*) echo "macos" ;;
+    Linux*)  echo "linux" ;;
+    *)       echo "unknown" ;;
+  esac
+}
+
+# 检测包管理器
+detect_package_manager() {
+  if command -v brew &>/dev/null; then
+    echo "brew"
+  elif command -v apt-get &>/dev/null; then
+    echo "apt"
+  elif command -v yum &>/dev/null; then
+    echo "yum"
+  elif command -v dnf &>/dev/null; then
+    echo "dnf"
+  else
+    echo "unknown"
+  fi
+}
+
+# 检查命令是否存在
+check_command() {
+  command -v "$1" &>/dev/null
+}
+
+# 安装单个工具
+install_tool() {
+  local tool="$1"
+  local pkg_manager="$2"
+
+  if check_command "$tool"; then
+    log_info "$tool 已安装 ($(which $tool))"
+    return 0
+  fi
+
+  log_info "安装 $tool..."
+  case "$pkg_manager" in
+    brew)
+      case "$tool" in
+        radon) pip3 install radon ;;
+        gocyclo)
+          if check_command go; then
+            go install github.com/fzipp/gocyclo/cmd/gocyclo@latest
+          else
+            log_warn "跳过 gocyclo（需要 Go 环境）"
+            return 0
+          fi
+          ;;
+        *) brew install "$tool" ;;
+      esac
+      ;;
+    apt)
+      case "$tool" in
+        ripgrep) sudo apt-get install -y ripgrep ;;
+        radon) pip3 install radon ;;
+        scc)
+          log_warn "scc 需要手动安装: https://github.com/boyter/scc#installation"
+          return 0
+          ;;
+        gocyclo)
+          if check_command go; then
+            go install github.com/fzipp/gocyclo/cmd/gocyclo@latest
+          else
+            log_warn "跳过 gocyclo（需要 Go 环境）"
+            return 0
+          fi
+          ;;
+        *) sudo apt-get install -y "$tool" ;;
+      esac
+      ;;
+    yum|dnf)
+      case "$tool" in
+        radon) pip3 install radon ;;
+        scc)
+          log_warn "scc 需要手动安装: https://github.com/boyter/scc#installation"
+          return 0
+          ;;
+        gocyclo)
+          if check_command go; then
+            go install github.com/fzipp/gocyclo/cmd/gocyclo@latest
+          else
+            log_warn "跳过 gocyclo（需要 Go 环境）"
+            return 0
+          fi
+          ;;
+        *) sudo "$pkg_manager" install -y "$tool" ;;
+      esac
+      ;;
+    *)
+      log_error "未知包管理器，请手动安装 $tool"
+      return 1
+      ;;
+  esac
+}
+
+# 主函数
+main() {
+  local mode="${1:---all}"
+  local os=$(detect_os)
+  local pkg_manager=$(detect_package_manager)
+
+  log_info "检测到操作系统: $os"
+  log_info "检测到包管理器: $pkg_manager"
+  echo ""
+
+  # 必需依赖
+  local required_tools=(jq ripgrep)
+
+  # 推荐依赖（复杂度计算）
+  local recommended_tools=(scc radon gocyclo)
+
+  # 开发依赖
+  local dev_tools=(shellcheck)
+
+  # 根据模式选择安装范围
+  local tools_to_install=()
+  case "$mode" in
+    --minimal)
+      tools_to_install=("${required_tools[@]}")
+      log_info "安装模式: 最小依赖"
+      ;;
+    --dev)
+      tools_to_install=("${required_tools[@]}" "${recommended_tools[@]}" "${dev_tools[@]}")
+      log_info "安装模式: 全部 + 开发依赖"
+      ;;
+    --all|*)
+      tools_to_install=("${required_tools[@]}" "${recommended_tools[@]}")
+      log_info "安装模式: 全部推荐依赖"
+      ;;
+  esac
+  echo ""
+
+  # 安装工具
+  local failed=()
+  for tool in "${tools_to_install[@]}"; do
+    if ! install_tool "$tool" "$pkg_manager"; then
+      failed+=("$tool")
+    fi
+  done
+  echo ""
+
+  # 验证安装
+  log_info "=== 安装验证 ==="
+  echo ""
+  echo "必需工具:"
+  for tool in "${required_tools[@]}"; do
+    if check_command "$tool"; then
+      echo "  ✅ $tool: $(which $tool)"
+    else
+      echo "  ❌ $tool: 未安装"
+    fi
+  done
+  echo ""
+  echo "复杂度工具:"
+  for tool in "${recommended_tools[@]}"; do
+    if check_command "$tool"; then
+      echo "  ✅ $tool: $(which $tool)"
+    else
+      echo "  ⚠️ $tool: 未安装（可选）"
+    fi
+  done
+  echo ""
+
+  if [[ "$mode" == "--dev" ]]; then
+    echo "开发工具:"
+    for tool in "${dev_tools[@]}"; do
+      if check_command "$tool"; then
+        echo "  ✅ $tool: $(which $tool)"
+      else
+        echo "  ⚠️ $tool: 未安装（可选）"
+      fi
+    done
+    echo ""
+  fi
+
+  # 总结
+  if [ ${#failed[@]} -eq 0 ]; then
+    log_info "✅ 所有依赖安装完成！"
+  else
+    log_warn "以下工具安装失败，请手动安装: ${failed[*]}"
+  fi
+}
+
+# 帮助信息
+if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
+  cat << 'EOF'
+DevBooks 系统依赖安装脚本
+
+用法:
+  ./scripts/install-dependencies.sh [选项]
+
+选项:
+  --minimal   只安装必需依赖 (jq, ripgrep)
+  --all       安装所有推荐依赖（默认）
+  --dev       额外安装开发依赖 (shellcheck)
+  --help      显示此帮助信息
+
+依赖说明:
+  必需依赖:
+    - jq        JSON 处理（Hook 输出格式化）
+    - ripgrep   代码搜索（符号定义查找）
+
+  推荐依赖:
+    - scc       通用复杂度计算（JS/TS/Go/Java 等）
+    - radon     Python 圈复杂度
+    - gocyclo   Go 圈复杂度
+
+  开发依赖:
+    - shellcheck  Shell 脚本静态分析
+
+示例:
+  ./scripts/install-dependencies.sh           # 安装全部推荐依赖
+  ./scripts/install-dependencies.sh --minimal # 只安装必需依赖
+  ./scripts/install-dependencies.sh --dev     # 安装全部 + 开发依赖
+EOF
+  exit 0
+fi
+
+main "$@"