dev-playbooks-cn 2.5.3 → 2.6.0

package/CHANGELOG.md

@@ -5,6 +5,56 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.6.0] - 2026-01-25
+
+### Added
+
+- **MCP 增强功能**：
+  - 新增 MCP 检测脚本 `scripts/detect-mcp.sh`
+  - 增强所有 skill 的 MCP 集成模板
+  - 新增 MCP 相关规格文档和指导
+
+- **长期指导和参考文档**：
+  - 新增 `skills/_shared/references/人类建议校准提示词.md`
+  - 新增 `skills/devbooks-archiver/references/归档流程与规则.md`
+  - 新增 `skills/devbooks-convergence-audit/references/` 目录
+  - 新增 `skills/devbooks-delivery-workflow/references/编排禁令与阶段表.md`
+  - 新增 `skills/devbooks-router/references/` 目录
+
+- **规格文档完善**：
+  - 新增 `dev-playbooks/specs/README.md` 规格索引
+  - 完善 MCP、共享方法论、样式清理等规格文档
+
+### Changed
+
+- **文档结构优化**：
+  - 更新所有 skill 的 SKILL.md 文档
+  - 优化 README.md 和使用指南
+  - 清理过时的文档文件
+
+- **归档变更包**：
+  - 归档 `20260124-0636-enhance-devbooks-longterm-guidance` 变更包
+
+---
+
+## [2.5.4] - 2026-01-23
+
+### Fixed
+
+- **修正 ignore 规则**：
+  - 移除 `.ckb/` - 这是外部工具 CKB 的缓存，不属于 DevBooks
+  - 将 `dev-playbooks/changes/*/evidence/` 改为 `dev-playbooks/` - 整个工作目录都应该被 ignore
+
+### Changed
+
+- **更准确的 ignore 范围**：
+  - `dev-playbooks/` - DevBooks 工作目录（包含所有运行时产生的内容）
+  - `.devbooks/` - DevBooks 本地配置
+  - `evidence/` - 测试证据目录
+  - `*.tmp`, `*.bak` - 临时文件
+
+---
+
 ## [2.5.3] - 2026-01-23
 
 ### Added
@@ -215,7 +265,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 #### Documentation
 
-- Added `docs/v2.0.0-修改总结.md`: Comprehensive summary of v2.0.0 changes
 - Updated README.md with v2.0.0 features section (both Chinese and English versions)
 
 ### Changed

package/README.md

@@ -23,6 +23,17 @@
 
 ---
 
+## 定位与文本规范
+
+DevBooks 本体是非 MCP 工具，但提供 MCP 可选集成点，便于按需接入外部能力，同时保留少量自检脚本作为护栏。
+DevBooks 是一套围绕协议、工作流、文本规范的协作体系，强调可追溯与可验证。
+
+约束：核心流程必须保持可追溯与可审计。
+取舍：更重视一致性检查，接受部分自动化效率降低。
+影响：文档可扫描性提高，协作成本下降。
+
+---
+
 ## 我们解决的核心问题
 
 ### 问题 1：逻辑幻觉与事实捏造
@@ -98,8 +109,6 @@ dev-playbooks-cn update
 
 - [使用指南](docs/使用指南.md) - 完整工作流程和最佳实践
 - [Skill 详解](docs/Skill详解.md) - 18 个 Skills 的特色和功能
-- [配置指南](dev-playbooks/docs/DevBooks配置指南.md) - 配置说明
-- [推荐 MCP](dev-playbooks/docs/推荐MCP.md) - MCP 服务器推荐
 
 ---
 
@@ -109,9 +118,9 @@ dev-playbooks-cn update
 
 Test Owner 与 Coder **必须在独立对话**中工作。这不是建议，是硬性约束。
 
-**为什么？**
-- 同一对话中写测试又写代码 → 测试沦为"通过性测试"
-- 独立对话 → 测试真正验证规格
+**隔离执行基线：**
+- 同一对话不同时编写测试与实现
+- 测试用于验证规格
 
 ### 2. 规格驱动（Spec-Driven）
 
@@ -182,7 +191,7 @@ Test Owner 与 Coder **必须在独立对话**中工作。这不是建议，是
 
 ---
 
-## 为什么选择 DevBooks？
+## 传统 AI 编程对照
 
 ### 对比传统 AI 编程
 

package/bin/devbooks.js

@@ -652,14 +652,13 @@ function getGitIgnoreEntries(toolIds) {
     '# DevBooks 本地配置（包含用户偏好，不应提交）',
     '.devbooks/',
     '',
+    '# DevBooks 工作目录（运行时产生的内容）',
+    'dev-playbooks/',
+    '',
     '# DevBooks 工作流产生的临时文件',
     'evidence/',
-    'dev-playbooks/changes/*/evidence/',
     '*.tmp',
-    '*.bak',
-    '',
-    '# CKB 代码知识库缓存',
-    '.ckb/'
+    '*.bak'
   ];
 
   // 根据选择的工具添加对应的 AI 工具目录
@@ -738,10 +737,7 @@ function getNpmIgnoreEntries() {
     '# DevBooks 工作流临时文件',
     'evidence/',
     '*.tmp',
-    '*.bak',
-    '',
-    '# CKB 缓存',
-    '.ckb/'
+    '*.bak'
   ];
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dev-playbooks-cn",
-  "version": "2.5.3",
+  "version": "2.6.0",
   "description": "AI-driven spec-based development workflow",
   "keywords": [
     "devbooks",

package/scripts/config-discovery.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
-# scripts/config-discovery.sh
+# scripts/config-discovery.sh (devbooks)
 # DevBooks Protocol Discovery Layer - 配置发现脚本
 #
 # 用途：发现并输出当前项目的 DevBooks 配置

package/scripts/detect-mcp.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF' >&2
+usage: detect-mcp.sh [--dry-run]
+
+Detect MCP server configuration from local user config files.
+
+Environment:
+  MCP_CONFIG_PATH  Override config file path (JSON).
+
+Output:
+  Writes key=value lines. Always exits 0 in --dry-run mode.
+EOF
+}
+
+dry_run=false
+
+if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+  usage
+  exit 0
+fi
+
+if [[ "${1:-}" == "--dry-run" ]]; then
+  dry_run=true
+  shift
+fi
+
+if [[ $# -gt 0 ]]; then
+  usage
+  exit 2
+fi
+
+config_path="${MCP_CONFIG_PATH:-}"
+
+if [[ -z "$config_path" ]]; then
+  for candidate in \
+    "${HOME}/.claude.json" \
+    "${HOME}/.claude/mcp.json"; do
+    if [[ -f "$candidate" ]]; then
+      config_path="$candidate"
+      break
+    fi
+  done
+fi
+
+echo "mcp_detected=false"
+
+if [[ -z "$config_path" ]]; then
+  echo "mcp_config_path="
+  echo "mcp_server_count=0"
+  echo "mcp_note=no_config_found"
+  exit 0
+fi
+
+echo "mcp_config_path=${config_path}"
+
+if [[ ! -f "$config_path" ]]; then
+  echo "mcp_server_count=0"
+  echo "mcp_note=config_not_found"
+  exit 0
+fi
+
+if command -v jq >/dev/null 2>&1; then
+  servers="$(jq -r '(.mcpServers // {}) | keys[]' "$config_path" 2>/dev/null || true)"
+  if [[ -z "$servers" ]]; then
+    echo "mcp_server_count=0"
+    echo "mcp_note=no_mcpServers_key"
+    exit 0
+  fi
+
+  count="$(printf "%s\n" "$servers" | wc -l | tr -d ' ')"
+  echo "mcp_detected=true"
+  echo "mcp_server_count=${count}"
+  while IFS= read -r name; do
+    [[ -n "$name" ]] || continue
+    echo "mcp_server=${name}"
+  done <<<"$servers"
+  exit 0
+fi
+
+echo "mcp_server_count=0"
+echo "mcp_note=jq_not_found"
+exit 0
+

package/skills/_shared/MCP/345/242/236/345/274/272/346/250/241/346/235/277.md

@@ -1,140 +1,30 @@
-# MCP 增强模板（MCP Enhancement Template）
+# MCP 提示模板（推荐 MCP 能力类型）
 
-> 本模板供各 SKILL.md 引用，定义 MCP 运行时检测与降级策略的标准章节格式。
+> 本模板供各 `skills/**/SKILL.md` 引用，用于提示“本任务适合使用哪些 MCP 能力类型”。
+> 不绑定任何具体 MCP 服务/工具名，不描述运行时检测、超时、失败处理与降级策略。
 
 ---
 
-## 核心原则
-
-1. **2s 超时**：所有 MCP 调用必须在 2s 内返回，否则视为不可用
-2. **优雅降级**：MCP 不可用时，Skill 继续执行基础功能，不阻塞
-3. **静默检测**：检测过程对用户透明，只在降级时输出提示
-
----
-
-## 标准章节格式
-
-每个 SKILL.md 的"MCP 增强"章节应包含以下内容：
+## 标准章节格式（复制到 SKILL.md）
 
 ```markdown
-## MCP 增强
-
-本 Skill 支持 MCP 运行时增强，自动检测并启用高级功能。
-
-### 依赖的 MCP 服务
-
-| 服务 | 用途 | 超时 |
-|------|------|------|
-| `mcp__ckb__getStatus` | 检测 CKB 索引可用性 | 2s |
-| `mcp__ckb__getHotspots` | 获取热点文件 | 2s |
-
-### 检测流程
-
-1. 调用 `mcp__ckb__getStatus`（2s 超时）
-2. 若返回成功 → 启用增强模式
-3. 若超时或失败 → 降级到基础模式
-
-### 增强模式 vs 基础模式
-
-| 功能 | 增强模式 | 基础模式 |
-|------|----------|----------|
-| 热点检测 | CKB 实时分析 | Git 历史统计 |
-| 影响分析 | 符号级引用 | 文件级 grep |
-| 调用图 | 精确调用链 | 不可用 |
-
-### 降级提示
-
-当 MCP 不可用时，输出以下提示：
-
-```
-⚠️ CKB 不可用（超时或未配置），使用基础模式执行。
-如需启用增强功能，请手动生成 SCIP 索引。
+## 推荐 MCP 能力类型
+- 代码检索（code-search）
+- 引用追踪（reference-tracking）
+- 影响分析（impact-analysis）
+- 文档检索（doc-retrieval）
 ```
-```
-
----
-
-## 按 Skill 分类
-
-### 无 MCP 依赖的 Skills
 
-以下 Skills 不依赖 MCP，无需 MCP 增强章节：
+## 规则（SKILL.md 专用）
 
-- devbooks-design-doc（纯文档生成）
-- devbooks-implementation-plan（纯计划生成）
-- devbooks-proposal-author（纯文档生成）
-- devbooks-proposal-challenger（纯评审）
-- devbooks-proposal-judge（纯裁决）
-- devbooks-design-backport（文档回写）
-- devbooks-archiver（文件整理）
-- devbooks-test-reviewer（测试评审）
-
-对于这些 Skills，MCP 增强章节应写：
-
-```markdown
-## MCP 增强
-
-本 Skill 不依赖 MCP 服务，无需运行时检测。
-```
-
-### 有 MCP 依赖的 Skills
-
-以下 Skills 依赖 MCP，需要完整 MCP 增强章节：
-
-| Skill | MCP 依赖 | 增强功能 |
-|-------|----------|----------|
-| devbooks-coder | mcp__ckb__getHotspots | 热点文件预警 |
-| devbooks-reviewer | mcp__ckb__getHotspots | 热点文件高亮 |
-| devbooks-impact-analysis | mcp__ckb__analyzeImpact, findReferences | 精确影响分析 |
-| devbooks-brownfield-bootstrap | mcp__ckb__* | COD 模型生成 |
-| devbooks-router | mcp__ckb__getStatus | 索引可用性检测 |
-| devbooks-spec-contract | mcp__ckb__findReferences | 引用检测 |
-| devbooks-entropy-monitor | mcp__ckb__getHotspots | 热点趋势分析 |
-| devbooks-delivery-workflow | mcp__ckb__getStatus | 索引检测 |
-| devbooks-test-owner | mcp__ckb__analyzeImpact | 测试覆盖分析 |
-
----
-
-## 检测代码示例
-
-### Bash 检测脚本
-
-```bash
-#!/bin/bash
-# mcp-detect.sh - MCP 可用性检测
-
-TIMEOUT=2
-
-# 检测 CKB
-check_ckb() {
-  # 模拟 MCP 调用（实际由 Claude Code 执行）
-  # 若 2s 内无响应，返回降级状态
-  echo "⚠️ CKB 检测需要在 Claude Code 环境中执行"
-}
-
-# 输出检测结果
-detect_mcp() {
-  local ckb_status="unknown"
-
-  # 检查 index.scip 文件是否存在（文件级检测）
-  if [ -f "index.scip" ]; then
-    ckb_status="available (file-based)"
-  else
-    ckb_status="unavailable"
-  fi
-
-  echo "MCP 检测结果："
-  echo "- CKB 索引：$ckb_status"
-}
-
-detect_mcp
-```
+- 只写能力类型清单（中文名 + 可选英文标识）。
+- 不写具体 MCP 服务名称、函数名或命令（例如 `ckb`、`context7`、`mcp__*`）。
+- 不写运行时检测/超时阈值/失败处理/降级提示。
 
 ---
 
-## 注意事项
+## 旧版“## MCP 增强”章节（弃用）
 
-1. **不要在 SKILL.md frontmatter 中添加不存在的 MCP 工具**
-2. **超时检测应在 Skill 执行开始时进行，不要多次检测**
-3. **降级后不要重复提示，只在首次检测时输出一次**
-4. **增强功能是可选的，基础功能必须完整可用**
+`skills/**/SKILL.md` 不再使用"## MCP 增强/依赖的 MCP 服务/增强模式 vs 基础模式"等结构。
+如需描述 MCP 的运行时检测与失败处理，仅在规格中维护：
+- 规格：`dev-playbooks/specs/mcp/spec.md`

package/skills/_shared/references//344/272/272/347/261/273/345/273/272/350/256/256/346/240/241/345/207/206/346/217/220/347/244/272/350/257/215.md

@@ -0,0 +1,27 @@
+# 人类建议校准提示词
+
+> 该模板用于高影响或不确定决策的人工建议校准。
+> 仅定义触发条件、边界与输出格式；不包含实现步骤。
+
+## 触发条件（至少满足一项）
+
+- 跨模块或对外契约变更
+- 多方案取舍（存在两个及以上可选方向）
+- 长期维护风险（涉及共享规范、模板或守门规则）
+- 安全或合规风险
+
+## 边界
+
+- 不替代 proposal/design/spec 的决策记录
+- 不用于纯执行型修改或低影响的格式调整
+- 不输出实现步骤、命令或代码细节
+
+## 最小提示词模板
+
+```markdown
+【人类建议校准】
+
+直觉价值：
+偏离最佳实践/不成熟点：
+推荐方案：
+```