规范上下文加载

发现并加载项目规范、进行中的变更和需求，以提供上下文。

快速开始

上下文加载可帮助回答：

• 项目有哪些规范？
• 目前有哪些进行中的变更？
• 已定义了哪些需求？
• 系统具备哪些能力？
• 某项功能在何处有所规范？

基本模式：搜索 → 阅读 → 总结

发现命令

注意将控制台与管道输出编码统一为 UTF-8，确保中文字符正确显示。

列出所有规范

# 查找所有规范文件
find spec/specs -name "spec.md" -type f

# 查找所有能力目录
find spec/specs -mindepth 1 -maxdepth 1 -type d

# 显示规范树
tree spec/specs/  # 若已安装 tree
# 或
ls -R spec/specs/

输出格式：

spec/specs/
├── authentication/
│   └── spec.md
├── billing/
│   └── spec.md
└── notifications/
    └── spec.md

列出进行中的变更

# 显示所有进行中的变更
find spec/changes -maxdepth 1 -type d -not -path "spec/changes" -not -path "*/archive" | sort

# 显示修改时间
find spec/changes -maxdepth 1 -type d -not -path "spec/changes" -not -path "*/archive" -exec ls -ld {} \;

# 统计进行中的变更数量
find spec/changes -maxdepth 1 -type d -not -path "spec/changes" -not -path "*/archive" | wc -l

列出已归档的变更

# 显示所有已归档变更
ls -1 spec/archive/

# 显示日期
ls -la spec/archive/

# 查找最近 7 天归档的变更
find spec/archive/ -maxdepth 1 -type d -mtime -7

搜索需求

# 查找所有需求
grep -r "### Requirement:" spec/specs/

# 在特定能力中查找需求
grep "### Requirement:" spec/specs/authentication/spec.md

# 列出唯一需求名称
grep -h "### Requirement:" spec/specs/**/*.md | sed 's/### Requirement: //' | sort

搜索场景

# 查找所有场景
grep -r "#### Scenario:" spec/specs/

# 统计每个规范中的场景数量
for spec in spec/specs/**/spec.md; do
    count=$(grep -c "#### Scenario:" "$spec")
    echo "$spec: $count scenarios"
done

关键词搜索

# 查找提到 "authentication" 的规范
grep -r -i "authentication" spec/specs/

# 查找与 "password" 相关的需求
grep -B 1 -A 5 -i "password" spec/specs/**/*.md | grep -A 5 "### Requirement:"

# 查找提到 "error" 的场景
grep -B 1 -A 10 -i "error" spec/specs/**/*.md | grep -A 10 "#### Scenario:"

常见查询

查询 1："项目有哪些规范？"

# 列出所有能力
find spec/specs -mindepth 1 -maxdepth 1 -type d -exec basename {} \;

# 统计每个能力的需求数量
for cap in spec/specs/*/; do
    name=$(basename "$cap")
    count=$(grep -c "### Requirement:" "$cap/spec.md" 2>/dev/null || echo "0")
    echo "$name: $count requirements"
done

响应格式：

## 现有规范

项目具备以下能力的规范：

- **authentication**：8 条需求
- **billing**：12 条需求
- **notifications**：5 条需求

合计：3 个能力，25 条需求

查询 2："当前有哪些变更在进行？"

# 附带提案摘要的列表
for change in spec/changes/*/; do
    if [ "$change" != "spec/changes/archive/" ]; then
        id=$(basename "$change")
        echo "=== $id ==="
        head -n 20 "$change/proposal.md" | grep -A 3 "## Why"
    fi
done

响应格式：

## 进行中的变更

当前进行中的变更：

### add-user-auth
**Why**：用户需要安全的认证...

### update-billing-api
**Why**：支付处理需要 v2 API...

合计：2 个进行中变更

查询 3："查找 authentication 规范"

# 阅读完整规范
cat spec/specs/authentication/spec.md

# 或展示摘要
echo "需求："
grep "### Requirement:" spec/specs/authentication/spec.md

echo "场景："
grep "#### Scenario:" spec/specs/authentication/spec.md

响应格式：

## Authentication 规范

（包含 spec.md 的完整内容）

摘要：
- 8 条需求
- 16 个场景
- 最近修改时间：[来自 git log 的日期]

查询 4："查找与 password 相关的规范"

# 关键词搜索
grep -r -i "password" spec/specs/ -A 5

# 显示提到该关键词的规范
grep -r -i "password" spec/specs/ -l

响应格式：

## Specs Mentioning "Password"

发现于：
- spec/specs/authentication/spec.md（3 条需求）
- spec/specs/security/spec.md（1 条需求）

相关需求：
### Requirement: Password Validation
### Requirement: Password Reset
### Requirement: Password Strength

查询 5："变更 X 的具体内容是什么？"

# 展示完整的变更上下文
CHANGE_ID="add-user-auth"

echo "=== 提案 ==="
cat spec/changes/$CHANGE_ID/proposal.md

echo "\n=== 任务 ==="
cat spec/changes/$CHANGE_ID/tasks.json

echo "\n=== 规范变更 ==="
find spec/changes/$CHANGE_ID/specs -name "*.md" -exec echo "File: {}" \; -exec cat {} \;

仪表盘视图

创建全面的项目概览：

#!/bin/bash
# 项目规范仪表盘

echo "===  规范仪表盘 ==="
echo ""

# 能力
echo "## 能力"
CAPS=$(find spec/specs -mindepth 1 -maxdepth 1 -type d | wc -l)
echo "能力总数: $CAPS"
for cap in spec/specs/*/; do
    name=$(basename "$cap")
    reqs=$(grep -c "### Requirement:" "$cap/spec.md" 2>/dev/null || echo "0")
    echo "  - $name: $reqs 条需求"
done
echo ""

# 需求
echo "## 需求"
TOTAL_REQS=$(grep -r "### Requirement:" spec/specs/ | wc -l)
TOTAL_SCENARIOS=$(grep -r "#### Scenario:" spec/specs/ | wc -l)
echo "需求总数: $TOTAL_REQS"
echo "场景总数: $TOTAL_SCENARIOS"
echo "每个需求平均场景数: $(echo "scale=1; $TOTAL_SCENARIOS/$TOTAL_REQS" | bc)"
echo ""

# 变更
echo "## 变更"
ACTIVE=$(find spec/changes -maxdepth 1 -type d -not -path "spec/changes" -not -path "*/archive" | wc -l)
ARCHIVED=$(ls -1 spec/archive/ | wc -l)
echo "进行中的变更: $ACTIVE"
echo "已归档的变更: $ARCHIVED"
echo ""

# 最近活动
echo "## 最近活动"
echo "最近修改的规范:"
find spec/specs -name "spec.md" -type f -exec ls -lt {} \; | head -5

响应格式：

# Specification Dashboard

## Capabilities
Total capabilities: 3
  - authentication: 8 requirements
  - billing: 12 requirements
  - notifications: 5 requirements

## Requirements
Total requirements: 25
Total scenarios: 52
Avg scenarios per requirement: 2.1

## Changes
Active changes: 2


...