| name | bb-mas |
| description | 生成芯片功能模块微架构文档（MAS、FSM、数据通路、验证计划、DFT）。Generate microarchitecture specification for chiplet modules. Trigger: /bb-mas, 微架构文档, MAS, FSM, datapath, verification plan, DFT |
| user-invocable | true |
| self-adaptive | true |
| version | 1.0.0 |
| arguments | [{"name":"project_dir","description":"芯片项目目录路径（如 ./myChip），auto-detect by default","required":false},{"name":"module_type","description":"模块类型：compute|storage|interconnect|io|all","required":false,"default":"all"},{"name":"auto_approve","description":"跳过用户批准点，自动生成所有文档","required":false,"default":"false"},{"name":"finetune","description":"Enable finetune mode for detailed intermediate output","required":false},{"name":"update","description":"更新模式：auto（自动检测变更）| full（强制归档+全量重建）| patch（强制就地更新，不归档）","required":false,"default":"auto"}] |
| handoffs | [{"target":"bb-spec-review","condition":"MAS documents completed","session_note":"必须执行对抗性 spec-review 才能进入 RTL 实现"}] |
| evolution | {"enabled":true,"trigger":"on_failure","max_attempts":3,"protected_zones":["frontmatter.name","frontmatter.description","HARD-GATE section","Self-Adaptive 初始化 section"],"depth_policy":{"conservative":"auto","local":"auto","system":"confirm"},"data_sources":["execution_log","evolution_history","failed_paths"]} |
output_dir: ./spec_mas
language: zh-CN
finetune: false
auto_approve: false
project_dir: auto-detect
module_type: all
update: auto
Self-Adaptive 初始化
初始化目录结构：.skills_local/bb-mas/，并收集项目上下文信息。
HARD-GATE 定义
<HARD-GATE>
在任何 MAS 生成操作前，必须完成以下步骤：
1. Self-Adaptive 初始化 + 项目上下文收集 + 路径解析（MANDATORY）
```bash
SCRIPT_DIR=~/.claude/scripts
python3 "$SCRIPT_DIR/adaptive/adaptive_init.py" \
--skill "bb-mas" \
--project-dir "{{ PROJECT_DIR }}"
-
加载配置文件（MANDATORY）
import json
with open(".skills_local/bb-mas/project_context.json") as f:
CONTEXT = json.load(f)
PROJECT_DIR = CONTEXT["project"]["root"]
INPUT_DIR = CONTEXT["resolved_paths"]["INPUT_DIR"]
OUTPUT_DIR = CONTEXT["resolved_paths"]["OUTPUT_DIR"]
MODULE_TYPE = CONTEXT["config"]["module_type"]
-
创建执行日志目录
mkdir -p "${LOG_DIR}"
LOG_FILE="${LOG_DIR}/mas-$(date -u +%Y%m%dT%H%M%S).log"
禁止行为（在完成初始化前）：
- 加载 spec_arch 输入
- 启动模块树生成
- 输出 MAS 文档
---
## Pipeline Position
spec_arch/ ──→ [bb-mas] ──→ spec_mas/ ──→ bb-spec-review ──→ bb-rtl-coder
OUTPUT_DIR
---
## 铁律（违反即停止）
> 以下规则不受 auto_approve 影响，任何模式下均不得绕过。
1. **Spec 先行铁律**：`spec_arch/` 中有效文档少于 2 份 → 拒绝执行，返回 bb-arch 阶段
2. **叶子优先铁律**：子模块未完成 → 禁止开始父模块；违反此顺序父模块内容必然不准确
3. **五文件完整铁律**：每个模块��须有 MAS.md + FSM.md + datapath.md + verification.md + DFT.md，缺一不可；"简单模块不需要 FSM" 是借口
4. **Frontmatter 状态铁律**：`status: pending` 的文件不计入完成统计，不触发后续流程
5. **并行上限铁律**：同时运行子 agent ≤ 6 个；超出会导致上下文污染和路径混乱
---
## 模块类型分类
| 类型 | 典型模块 | MAS 重点章节 |
|------|---------|-------------|
| **compute** | ALU、CPU Core、MAC、DSP | 数据通路、FSM、流水线 |
| **storage** | Cache、SRAM、DRAM Controller | 访存协议、替换策略、一致性 |
| **interconnect** | NoC、Bus、Crossbar、Router | 路由算法、仲裁、带宽 |
| **io** | GPIO、PCIe、DDR、SerDes | 协议适配、CDC、时序 |
---
## Global Paths
PROJECT_DIR = {{ project_dir 参数 或 auto-detect }}
INPUT_DIR = {{ PROJECT_DIR }}/spec_arch
OUTPUT_DIR = {{ PROJECT_DIR }}/spec_mas
TEMPLATE_DIR = ~/.claude/skills/bb-mas/templates
PROGRESS_DIR = {{ OUTPUT_DIR }}/.progress
CHECKPOINT_DIR = {{ OUTPUT_DIR }}/.checkpoint
SCRIPT_DIR = ~/.claude/scripts
PROJECT_SCRIPTS = {{ PROJECT_DIR }}/scripts
SKILL_FILE = ~/.claude/skills/bb-mas/SKILL.md
---
## 增量更新机制
每次成功完成后，将输入文件哈希写入 `<output_dir>/.archive/input_snapshot.json`。下次执行时在前置检查之前自动比对。
### 输入快照格式
```json
{
"snapshot_time": "<ISO8601+08:00>",
"skill": "bb-mas",
"input_files": {
"<relative-path>": "<sha256>"
}
}
Phase -1: 变更检测（前置检查前强制执行）
IF update=full → 跳过检测，走 MAJOR 路径
IF update=patch → 跳过检测，走 MINOR 路径
ELSE (auto):
IF input_snapshot.json 不存在
→ FULL RUN（首次执行，不归档）
ELSE
sha256sum arch_spec/ 下所有 .md 文件
与 snapshot 对比
IF 哈希全部一致 → 输出 "输入未变更，跳过生成" 并退出
IF 哈希有差异 → 按下表分类
变更分类
| 条件（满足任意一条） | 分类 |
|---|
| arch_spec/ 中文件数量变化（增删文件） | MAJOR |
| arch_doc.md 中模块数量变化 | MAJOR |
| 接口协议列表变更（增删/重命名） | MAJOR |
| 时钟域数量或名称变更 | MAJOR |
| arch_spec/ 总字符数变化 > 30% | MAJOR |
| 其他所有变更（模块描述更新、预算调整、时序约束细化等） | MINOR |
MAJOR 路径：归档 + 全量重建
TIMESTAMP=$(date -u +%Y%m%dT%H%M%S)
ARCHIVE="{{ OUTPUT_DIR }}/.archive/$TIMESTAMP"
mkdir -p "$ARCHIVE"
for item in "{{ OUTPUT_DIR }}"/*.md "{{ OUTPUT_DIR }}"/*.json \
"{{ OUTPUT_DIR }}"/fsm "{{ OUTPUT_DIR }}"/datapath; do
[ -e "$item" ] && mv "$item" "$ARCHIVE/"
done
echo "{\"reason\":\"MAJOR\",\"timestamp\":\"$TIMESTAMP\"}" > "$ARCHIVE/CHANGE_REASON.json"
归档完成后执行 FULL RUN（从前置检查正常继续）。
MINOR 路径：就地更新
仅重新生成哈希发生变化的模块文档，其余模块保持不变：
| 变更内容 | 处理 |
|---|
| 某模块 MAS.md 对应的 arch_spec 段变更 | 重新生成该模块 MAS.md + FSM/Datapath |
| 全局计划（verif_plan_seed.md、dft_plan_seed.md）相关内容变更 | 重新生成全局计划文件 |
| 仅描述文字变更 | 仅更新受影响模块的描述段落 |
完成后更新 {{ OUTPUT_DIR }}/.archive/input_snapshot.json。
前置检查
-
定位 spec_arch 目录：
-
验证必需文档（至少 2 份，来自 bb-arch 实际输出）：
chip_overview.md 或 block_overview.md — 芯片/模块概述block_diagram.md — 系统/模块框图clock_reset_spec.md — 时钟复位架构memory_map.md — 存储架构与地址映射power_spec.md — 电源架构io_pinout.md — IO 与引脚定义ip_blocks/*.md — IP 模块详细设计（scope=chip 时）
-
创建输出目录：
mkdir -p {{ OUTPUT_DIR }}
mkdir -p {{ PROGRESS_DIR }}
mkdir -p {{ CHECKPOINT_DIR }}
阶段 1：构建模块树
1.1 输入规模检测
TOTAL_SIZE=$(find "${INPUT_DIR}" -name "*.md" -exec wc -c {} + | tail -1 | awk '{print $1}')
if [ "$TOTAL_SIZE" -lt 100000 ]; then READ_MODE="full"
elif [ "$TOTAL_SIZE" -lt 300000 ]; then READ_MODE="section"
else READ_MODE="subagent"
fi
1.2 构建嵌套模块树
拆分判据：模块职责覆盖 3+ 独立子功能 → 拆分
命名规则：
- L1：
M01_模块名/（如 M01_ALU/）
- L2：
M01a_子模块名/（如 M01a_IntegerALU/）
- L3：
M01a1_原子模块/（如 M01a1_Adder/）
Chiplet 特定标注：
@D2D — Die-to-Die 接口模块@CDC — 跨时钟域模块@PWR — 电源管理相关
1.3 输出模块树文档
写入 {{ OUTPUT_DIR }}/module_tree.md
1.4 创建目录结构
为每个模块创建子目录和 5 个文件：
{{ OUTPUT_DIR }}/
├── module_tree.md
├── plan.md（占位）
├── .progress/
├── .checkpoint/
└── M01_*/
├── MAS.md # 微架构文档
├── FSM.md # 状态机设计
├── datapath.md # 数据通路图
├── verification.md # 验证计划
├── DFT.md # 可测性设计
└── tasks.md # 实现任务
阶段 2：填充叶子模块文档（并行）
子 agent 指令模板
## 任务：填充模块 MAS 文档
**路径规范**：
- 输出文件：{{ OUTPUT_DIR }}/{{ MODULE_PATH }}/MAS.md
- 模板文件：{{ TEMPLATE_DIR }}/MAS-template.md
- 上下文：{{ INPUT_DIR }}/architecture_spec.md, functional_spec.md
**要求**：
1. 读取模板文件
2. 按模板章节结构填充内容
**芯片特定质量要求**：
- §2.1 接口定义：信号名、位宽、方向、协议（AXI/APB/自定义）
- §2.2 时序规格：Cycle 延迟、吞吐、带宽
- §3 数据通路：流水线级数、关键路径、Mermaid/WaveDrom 图
- §4 状态机：FSM 定义、状态编码、转移条件
- §5 验证策略：功能覆盖点、断言、仿真场景
- §6 DFT 方案：扫描链、BIST、JTAG 接口
- §10 需求追踪矩阵：REQ_ID 列表 + 验收标准
3. frontmatter 格式：
---
module: {{ MODULE_ID }}
type: MAS
status: complete
parent: {{ PARENT_ID }}
module_type: compute|storage|interconnect|io
generated: {{ NOW }}
---
REQ_ID 分配与标注
分配规则：
- 从 arch_spec 中的 REQ-SYS/ARCH 分解到模块级 REQ-M##-F##
- 使用
$PROJECT_SCRIPTS/allocate_req_id.py 自动分配编号（禁止手动编号）
- 每个功能点对应一个 REQ_ID（P-4: 禁止复用；P-5: 禁止一对多）
标注规则：
- MAS.md §10：生成需求追踪矩阵表
- 章节标题下：添加 HTML 注释
<!-- REQ-M##-F01, REQ-M##-F02 -->
- 表格中：在 REQ_ID 列直接标注
示例：
## 3. 流水线结构
<!-- REQ-M01-F01, REQ-M01-F02, REQ-M01-F03 -->
| 级 | 名称 | REQ_ID | 功能 | 延迟 |
|-----|------|--------|------|------|
| IF | 取指 | F01 | AXI Burst 读 | 1–8 cycle |
## 10. 需求追踪矩阵
| REQ_ID | 需求描述 | 优先级 | 验收标准 | 边界条件 | RTL 组件 | 测试用例 |
|--------|---------|--------|---------|---------|---------|---------|
| REQ-M01-F01 | IF 取指 | P0 | IQ 填充延迟 ≤8 cycle | IQ 满时 back-pressure | M01_DataflowController | TC-M01-L1-001 |
阶段 3：填充 FSM/Datapath/Verification/DFT（并行）
每个叶子模块启动子 agent 依次填充 4 个文件。
FSM.md 质量要求
## FSM 定义
### 状态列表
| 状态 | 编码 | 描述 |
|------|------|------|
### 状态转移表
| 当前状态 | 转移条件 | 目标状态 | 输出 |
|----------|---------|----------|------|
### Mermaid 状态图
```mermaid
stateDiagram-v2
[*] --> Idle
Idle --> Active: start
...
### Datapath.md 质量要求
```markdown
## 数据通路
### 模块框图（Mermaid）
```mermaid
graph TB
A[输入] --> B[处理]
B --> C[输出]
流水线结构
关键路径分析
### Verification.md 质量要求
```markdown
## 验证计划
### 功能覆盖点
| 覆盖点 | 类型 | 描述 |
|--------|------|------|
### 断言列表
| 断言 | 条件 | 严重性 |
|------|------|------|
### 仿真场景
- 正常场景
- 边界场景
- 异常场景
DFT.md 质量要求
## 可测性设计
### 扫描链配置
- 链数
- 长度
- 接口
### BIST 方案
- 类型（MBIST/LBIST）
- 覆盖范围
### JTAG 接口
- TCK/TMS/TDI/TDO
- 支持指令
阶段 4：逐层上卷父模块
从最深的父模块开始，逐层向上填充。
父模块特殊内容：
- MAS.md：子模块编排表、数据流图、聚合接口
- FSM.md：顶层状态机协调
- datapath.md：模块间连接图
- verification.md：集成验证场景
- DFT.md：顶层测试访问
阶段 5：生成全局计划 + Traceability CSV
5.1 全局计划
汇总所有模块的 tasks，生成 {{ OUTPUT_DIR }}/plan.md：
- 模块依赖关系图（Mermaid）
- 实现阶段定义
- 并行实现矩阵
- 验证里程碑
5.2 Traceability CSV 生成
从所有模块 MAS.md §10 提取 REQ_ID，生成 traceability/requirements_matrix.arch.csv：
uv run $PROJECT_SCRIPTS/babel_traceability.py arch
5.3 唯一性验证
uv run $PROJECT_SCRIPTS/check_req_uniqueness.py --check-deleted
5.4 完成标准追加
5.5 生成 MAS handoff 新鲜度哈希（CR-5）
bba-architect 没有 Bash 工具，无法运行 sha256sum。本 skill 提供 scripts/hash_outputs.py
供 architect（经 IC_ADAPTER）填充 mas.json 的 inputs[]（消费的 idea/arch 文件）与
outputs[]（产出的 PRD/arch_spec/MAS 文档），二者均为 mas.schema.json 必填项；下游 RTL
重算 outputs[] 哈希以检测 MAS 漂移。
uv run python scripts/hash_outputs.py --base designs/<name> \
designs/<name>/idea/parsed_idea.json designs/<name>/arch_spec/*.md
uv run python scripts/hash_outputs.py --base designs/<name> \
designs/<name>/PRD.md designs/<name>/arch_spec/*.md \
designs/<name>/mas/mas.md designs/<name>/mas/fsm/* designs/<name>/mas/datapath/*
脚本输出按 path 排序的 [{path, sha256}] JSON；缺失文件 → 退出码 1 且不伪造哈希（fail-closed）。
Chiplet 特定章节
当模块涉及 D2D 接口时，MAS.md 必须包含：
D2D 接口规范
## D2D 接口
### 协议类型
- UCIe / BoW / AIB / 自定义
### 信号定义
| 信号 | 方向 | 位宽 | 协议 |
|------|------|------|------|
### 时序参数
- 延迟：`xx cycles`
- 吞吐：`xx Gbps`
### CDC 方案
- 同步器类型
- MTBF 估算
电源域
## 电源域
### 域划分
| 域 | 电压 | 模块 |
|------|------|------|
### 电源序列
1. 域 A 上电
2. 域 B 上电
...
Frontmatter 格式规范
---
module: M[0-9]{2}[a-z]?
type: MAS | FSM | datapath | verification | DFT | tasks
status: pending | complete
parent: [父模块编号]
module_type: compute | storage | interconnect | io
chiplet_features: [D2D, CDC, PWR]
generated: [ISO 8601 时间戳]
---
输出模板
详见 templates/ 目录：
MAS-template.md — 微架构文档模板FSM-template.md — 状态机模板datapath-template.md — 数据通路模板verification-template.md — 验证计划模板DFT-template.md — DFT 模板tasks-template.md — 任务模板
辅助脚本
详见 scripts/ 目录：
progress_check.sh — 进度检查checkpoint_manager.sh — checkpoint 管理analyze_spec.sh — 文档质量分析hash_outputs.py — 计算文件 sha256 填充 mas.json inputs[]/outputs[]（供无 Bash 的 architect 使用，CR-5）
操作原则
- 路径绝对化：所有路径使用绝对路径
- 格式统一：frontmatter 仅使用
status: complete
- 进度可追踪：每个文件完成后更新进度文件
- 支持恢复：每个阶段完成时创建 checkpoint
- 底层优先：叶子模块先完成，再逐层上卷
- 并行加速：同层无依赖模块并行处理（最大 6 个）
- 阶段压缩：每完成一个阶段执行
/compact
常见借口（均无效）
| Agent 的借口 | 为什么错 |
|---|
| "���个模块很简单，FSM.md 可以留空" | 无 FSM 文档意味着 RTL 工程师在无规范情况下写状态机，必然引入缺陷，review 时也无法检查 |
| "DFT.md 是 DFT 工程师的事，MAS 阶段不需要" | DFT 需求影响模块端口（scan_en），MAS 阶段未定则 RTL 需要返工接口 |
| "父模块可以先写，子模块并行填充" | 父模块内容依赖子模块接口定义；子模块未完成则父模块内容必然不准确，后续级联错误 |
| "verification.md 场景太多，列几个代表性的就行" | 不完整的验证计划等于不完整的测试；漏掉的场景在 silicon 上暴露，成本以流片次数计 |
| "先标 status: complete，内容后续完善" | 错误的 complete 标记会让 bb-spec-review 跳过实际未完成模块，掩盖质量问题 |
| "输入文档不够清晰，猜测一下先继续" | 基于猜测的 MAS 文档等于技术债；在 RTL 实现阶段被发现时已无法低成本修复 |
降级策略
| 场景 | 降级方案 |
|---|
| 子 agent 超时 | 重试一次；再次失败则记录至 .progress/failed_modules.md 并继续其他模块 |
模板文件缺失（templates/） | 使用各阶段"质量要求"小节中的内联最小化模板结构 |
| 输入规模超过单 agent 处理能力 | 切分为 300KB chunks，依次送入子 agent，结果合并 |
| bb-spec-review 不可用 | 使用阶段 5 plan.md 内联质量检查清单代替，结果写入 .checkpoint/manual_check.md |
spec_arch/ 缺少某类文档 | 从已有文档推断，标注 "⚠️ 基于推断，需人工确认：{缺失文档}" |
最终验证实证（完成标准）
以下条件全部满足才可声明 bb-mas 完成，并触发 bb-spec-review handoff。缺一不可。
禁止在上述条件未满足时触发 bb-rtl-coder handoff。
Evolution Trigger Point
When any Phase fails:
- Detect failure: Read
{{ OUTPUT_DIR }}/execution.log
- Invoke framework:
bash {{ EVOLUTION_FRAMEWORK }}/evolve.sh \
--skill "{{ SKILL_FILE }}" \
--output "{{ OUTPUT_DIR }}" \
--failure-phase "{{ FAILED_PHASE }}"
- Framework handles: Analyze, modify, validate, rollback
- Retry or escalate
