dev-playbooks-cn 2.2.1 → 2.3.1

package/skills/devbooks-docs-consistency/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: devbooks-docs-consistency
+description: devbooks-docs-consistency：检查并维护项目文档与代码的一致性，支持增量扫描、自定义规则与完备性检查。可在变更包内按需运行或全局检查。旧名称 devbooks-docs-sync 保留为别名并输出弃用提示。
+recommended_experts: ["Technical Writer", "System Architect"]
+allowed-tools:
+  - Glob
+  - Grep
+  - Read
+  - Edit
+  - Write
+  - Bash
+---
+
+# DevBooks：文档一致性（Docs Consistency）
+
+## 前置：配置发现（协议无关）
+
+执行前**必须**按以下顺序查找配置（找到后停止）：
+1. `.devbooks/config.yaml`（如存在）→ 解析并使用其中的映射
+2. `dev-playbooks/project.md`（如存在）→ Dev-Playbooks 协议，使用默认映射
+3. `project.md`（如存在）→ template 协议，使用默认映射
+4. 若仍无法确定 → **停止并询问用户**
+
+---
+
+## 兼容与弃用
+
+- 旧名称：`devbooks-docs-sync`
+- 当前名称：`devbooks-docs-consistency`
+- 行为：旧名称作为别名继续可用，并输出弃用提示。
+- 运行提示：别名通过软链接指向新目录，可执行 `scripts/alias.sh` 输出提示。
+
+弃用提示示例：
+
+```
+devbooks-docs-sync 已弃用，请使用 devbooks-docs-consistency。
+```
+
+---
+
+## 角色定义
+
+**docs-consistency** 是 DevBooks Apply 阶段的文档一致性检查角色，负责识别文档与代码之间的偏差并生成报告，不直接修改代码。
+
+### 文档分类
+
+| 文档类型 | 目标受众 | 是否由本 Skill 检查 | 示例 |
+|----------|----------|:-------------------:|------|
+| **活体文档** | 最终用户 | ✅ | README.md, docs/*.md, API.md |
+| **历史文档** | 最终用户 | ⚠️（只做最低限度检查） | CHANGELOG.md |
+| **概念性文档** | 设计/架构 | ✅（结构性检查） | architecture/*.md |
+
+分类规则可配置，默认规则见 `references/doc-classification.yaml`。
+
+---
+
+## 运行模式
+
+### 模式一：增量扫描（Change-Scoped）
+
+**触发条件**：在变更包上下文中运行。
+
+**行为**：
+1. 读取变更范围
+2. 仅扫描变更文件
+3. 记录 token 消耗与扫描时间
+4. 输出检查报告
+
+### 模式二：全量扫描（Global Check）
+
+**触发条件**：用户显式请求全局检查（如 `devbooks-docs-consistency --global`）。
+
+**行为**：
+1. 扫描所有用户文档
+2. 生成差异报告
+3. 输出改进建议
+
+### 模式三：检查模式（Check Only）
+
+**触发条件**：用户使用 `--check` 参数。
+
+**行为**：只检查、不修改，输出报告。
+
+---
+
+## 命令示例
+
+```
+# 规则引擎：持续规则
+bash scripts/rules-engine.sh --rules references/docs-rules-schema.yaml --input README.md
+
+# 规则引擎：一次性任务
+bash scripts/rules-engine.sh --once "remove:@augment" --input README.md
+
+# 文档分类
+bash scripts/doc-classifier.sh README.md
+
+# 完备性检查
+bash scripts/completeness-checker.sh --input README.md --config references/completeness-dimensions.yaml --output evidence/completeness-report.md
+```
+
+---
+
+## 完备性检查
+
+对活体文档执行完备性检查，默认覆盖：环境依赖、安全权限、故障排查、配置说明、API 文档。
+
+- 维度配置：`references/completeness-dimensions.yaml`
+- 报告输出：`<change-root>/<change-id>/evidence/completeness-report.md`
+- 方法论参考：[完备性思维框架](../_shared/references/完备性思维框架.md)
+
+---
+
+## 风格偏好
+
+风格偏好读取优先级：命令行参数 > 配置文件 > 默认值。
+
+- 文档维护元数据：`dev-playbooks/specs/_meta/docs-maintenance.md`
+
+---
+
+## 输出与报告
+
+默认输出以下报告（变更包上下文）：
+
+- `evidence/completeness-report.md`
+- `evidence/token-usage.log`
+- `evidence/scan-performance.log`
+
+---
+
+## 与工作流的集成
+
+在归档阶段由 `devbooks-archiver` 触发，在存量初始化时由 `devbooks-brownfield-bootstrap` 生成文档维护元数据。
+
+---
+
+## MCP 说明
+
+本 Skill 不依赖 MCP 服务，无需运行时检测。
+
+---
+
+## 元数据
+
+| 字段 | 值 |
+|------|-----|
+| Skill 名称 | devbooks-docs-consistency |
+| 阶段 | Apply（实现后、归档前） |
+| 产物 | 文档一致性检查报告 |
+| 约束 | 只检查、不修改代码 |
+
+---
+
+*此 Skill 文档遵循 devbooks-* 规范。*

package/skills/devbooks-docs-consistency/references/completeness-dimensions.yaml

@@ -0,0 +1,25 @@
+- name: 环境依赖
+  patterns:
+    - "Node.js"
+    - "Python"
+    - "依赖"
+- name: 安全权限
+  patterns:
+    - "权限"
+    - "安全"
+    - "密钥"
+- name: 故障排查
+  patterns:
+    - "故障"
+    - "排查"
+    - "Troubleshooting"
+- name: 配置说明
+  patterns:
+    - "配置"
+    - "config"
+    - "配置文件"
+- name: API 文档
+  patterns:
+    - "API"
+    - "接口"
+    - "Endpoint"

package/skills/devbooks-docs-consistency/references/doc-classification.yaml

@@ -0,0 +1,11 @@
+living_docs:
+  - "README.md"
+  - "docs/**/*.md"
+  - "API.md"
+  - "docs/*.md"
+history_docs:
+  - "CHANGELOG.md"
+  - "**/CHANGELOG.md"
+concept_docs:
+  - "architecture/*.md"
+  - "architecture/**/*.md"

package/skills/devbooks-docs-consistency/references/docs-rules-schema.yaml

@@ -0,0 +1,11 @@
+rules:
+  - id: forbid-smart
+    type: persistent
+    target: content
+    action: check
+    pattern: "智能"
+  - id: remove-augment
+    type: once
+    target: content
+    action: remove
+    pattern: "@augment"

package/skills/devbooks-docs-consistency/scripts/alias.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "devbooks-docs-sync 已弃用，请使用 devbooks-docs-consistency。" >&2
+exit 0

package/skills/devbooks-docs-consistency/scripts/completeness-checker.sh

@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: completeness-checker.sh --input <file> --config <dimensions.yaml> [--output <report>]
+EOF
+}
+
+INPUT_PATH=""
+CONFIG_PATH=""
+OUTPUT_PATH=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --input)
+      INPUT_PATH="$2"
+      shift 2
+      ;;
+    --config)
+      CONFIG_PATH="$2"
+      shift 2
+      ;;
+    --output)
+      OUTPUT_PATH="$2"
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+if [[ -z "$INPUT_PATH" || -z "$CONFIG_PATH" ]]; then
+  echo "Missing --input or --config" >&2
+  usage >&2
+  exit 2
+fi
+
+if [[ ! -f "$INPUT_PATH" ]]; then
+  echo "input not found: $INPUT_PATH" >&2
+  exit 2
+fi
+
+if [[ ! -f "$CONFIG_PATH" ]]; then
+  echo "config not found: $CONFIG_PATH" >&2
+  exit 2
+fi
+
+report_line() {
+  local name="$1"
+  local ok="$2"
+  local msg="$3"
+  if [[ "$ok" == "1" ]]; then
+    printf "- %s: ✓ %s\n" "$name" "$msg"
+  else
+    printf "- %s: ✗ %s\n" "$name" "$msg"
+  fi
+}
+
+read_dimension_patterns() {
+  local key="$1"
+  python3 - "$CONFIG_PATH" "$key" <<'PY'
+import sys
+
+config_path = sys.argv[1]
+target = sys.argv[2]
+patterns = []
+current = None
+collecting = False
+
+with open(config_path, "r", encoding="utf-8") as fh:
+    for raw in fh:
+        line = raw.rstrip("\n")
+        stripped = line.strip()
+        if stripped.startswith("- name:"):
+            current = stripped.split(":", 1)[1].strip()
+            collecting = False
+            continue
+        if current == target and stripped.startswith("patterns:"):
+            collecting = True
+            continue
+        if collecting:
+            if stripped.startswith("-"):
+                value = stripped.lstrip("-").strip().strip('"')
+                if value:
+                    patterns.append(value)
+            elif stripped and not stripped.startswith("#"):
+                collecting = False
+
+for item in patterns:
+    print(item)
+PY
+}
+
+dimensions=()
+while IFS= read -r line; do
+  dimensions+=("$line")
+done < <(python3 - "$CONFIG_PATH" <<'PY'
+import sys
+
+config_path = sys.argv[1]
+with open(config_path, "r", encoding="utf-8") as fh:
+    for raw in fh:
+        stripped = raw.strip()
+        if stripped.startswith("- name:"):
+            print(stripped.split(":", 1)[1].strip())
+PY
+)
+
+if [[ "${#dimensions[@]}" -eq 0 ]]; then
+  echo "no dimensions defined" >&2
+  exit 2
+fi
+
+output=""
+output+="# 完备性检查报告\n\n"
+
+for dim in "${dimensions[@]}"; do
+  ok=0
+  msg=""
+  patterns=()
+  while IFS= read -r line; do
+    patterns+=("$line")
+  done < <(read_dimension_patterns "$dim")
+  if [[ "${#patterns[@]}" -eq 0 ]]; then
+    msg="无匹配规则"
+  else
+    for pattern in "${patterns[@]}"; do
+      if grep -q "$pattern" "$INPUT_PATH"; then
+        ok=1
+        msg="命中: $pattern"
+        break
+      fi
+    done
+    if [[ "$ok" -eq 0 ]]; then
+      msg="缺少: ${patterns[*]}"
+    fi
+  fi
+  output+="$(report_line "$dim" "$ok" "$msg")"$'\n'
+done
+
+if [[ -n "$OUTPUT_PATH" ]]; then
+  printf "%b" "$output" > "$OUTPUT_PATH"
+else
+  printf "%b" "$output"
+fi

package/skills/devbooks-docs-consistency/scripts/doc-classifier.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DEFAULT_RULES="${SCRIPT_DIR}/../references/doc-classification.yaml"
+
+RULES_PATH="${DOC_CLASSIFICATION_RULES:-$DEFAULT_RULES}"
+DOC_PATH="${1:-}"
+
+if [[ -z "$DOC_PATH" ]]; then
+  echo "usage: doc-classifier.sh <path>" >&2
+  exit 2
+fi
+
+if [[ ! -f "$RULES_PATH" ]]; then
+  echo "rules file not found: $RULES_PATH" >&2
+  exit 2
+fi
+
+normalize_path() {
+  local input="$1"
+  echo "${input#./}"
+}
+
+collect_patterns() {
+  local key="$1"
+  python3 - "$RULES_PATH" "$key" <<'PY'
+import sys
+
+rules_path = sys.argv[1]
+key = sys.argv[2]
+patterns = []
+collecting = False
+
+with open(rules_path, "r", encoding="utf-8") as fh:
+    for raw in fh:
+        line = raw.rstrip("\n")
+        if line.startswith(f"{key}:"):
+            collecting = True
+            continue
+        if collecting:
+            stripped = line.strip()
+            if not stripped.startswith("-"):
+                if stripped and not stripped.startswith("#"):
+                    collecting = False
+                elif not stripped:
+                    continue
+            if stripped.startswith("-"):
+                value = stripped.lstrip("-").strip()
+                if value.startswith("\"") and value.endswith("\""):
+                    value = value[1:-1]
+                if value:
+                    patterns.append(value)
+
+for item in patterns:
+    print(item)
+PY
+}
+
+matches_pattern() {
+  local path="$1"
+  local pattern="$2"
+  python3 - "$path" "$pattern" <<'PY'
+import sys
+from pathlib import PurePosixPath
+
+path = PurePosixPath(sys.argv[1])
+pattern = sys.argv[2]
+print("1" if path.match(pattern) else "0")
+PY
+}
+
+doc_path=$(normalize_path "$DOC_PATH")
+
+living_patterns=()
+history_patterns=()
+concept_patterns=()
+while IFS= read -r line; do
+  living_patterns+=("$line")
+done < <(collect_patterns "living_docs")
+while IFS= read -r line; do
+  history_patterns+=("$line")
+done < <(collect_patterns "history_docs")
+while IFS= read -r line; do
+  concept_patterns+=("$line")
+done < <(collect_patterns "concept_docs")
+
+match_types=()
+
+for pattern in "${living_patterns[@]:-}"; do
+  if [[ -n "$pattern" && $(matches_pattern "$doc_path" "$pattern") == "1" ]]; then
+    match_types+=("living")
+    break
+  fi
+done
+
+for pattern in "${history_patterns[@]:-}"; do
+  if [[ -n "$pattern" && $(matches_pattern "$doc_path" "$pattern") == "1" ]]; then
+    match_types+=("history")
+    break
+  fi
+done
+
+for pattern in "${concept_patterns[@]:-}"; do
+  if [[ -n "$pattern" && $(matches_pattern "$doc_path" "$pattern") == "1" ]]; then
+    match_types+=("concept")
+    break
+  fi
+done
+
+if [[ "${#match_types[@]}" -eq 0 ]]; then
+  echo "unknown"
+  exit 0
+fi
+
+if [[ "${#match_types[@]}" -gt 1 ]]; then
+  echo "conflict: ${match_types[*]}"
+  exit 0
+fi
+
+echo "${match_types[0]}"

package/skills/devbooks-docs-consistency/scripts/git-adapter.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+command="${1:-}"
+
+if [[ -z "$command" ]]; then
+  echo "usage: git-adapter.sh <getChangedFiles|getDiff> [ref]" >&2
+  exit 2
+fi
+
+case "$command" in
+  getChangedFiles)
+    ref="${2:-HEAD~1}"
+    if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+      echo "git not available" >&2
+      exit 1
+    fi
+    git diff --name-only "$ref"
+    ;;
+  getDiff)
+    ref="${2:-HEAD~1}"
+    if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+      echo "git not available" >&2
+      exit 1
+    fi
+    git diff "$ref"
+    ;;
+  *)
+    echo "unknown command: $command" >&2
+    exit 2
+    ;;
+esac