配图类型	Style prefix	宽高比
架构/数据流	Technical diagram, vector style	16:9
功能关系

SDD Global Init — 工作区初始化与全局 Spec 生成

概述

初始化 SDD 工作区：

1. 让用户选择或创建工作区目录
在工作区创建 spec/global/ 知识库目录
扫描工作区中的代码库生成完整的全局文档集合（概述、架构、约束、功能清单、索引）
包含配图生成

触发方式： 手动触发，用户运行 /sdd-global-init

关键概念

- 工作区 (Workspace)： 用户指定的用于存放所有 SDD 文档和代码的根目录
工作区配置： 初始化时在工作区根目录创建 .sdd-workspace 文件，记录工作区路径，供后续 SDD skill 使用

步骤 0：获取工作区路径

0.1 检查是否存在已有工作区配置

检查当前 OpenClaw workspace 中是否存在 .sdd-workspace 配置文件：

- 如果存在，读取其中的 workspace_path 作为默认工作区
询问用户是继续使用现有工作区还是新建工作区

0.2 选择或创建工作区

如果无现有配置，或用户选择新建，使用 AskUserQuestion 展示选项：

1. 使用 OpenClaw 当前 workspace — 使用 /home/maqb11/.openclaw/workspace/ 作为工作区
指定已有目录 — 用户输入一个已有的目录路径
创建新目录 — 用户输入新目录名，在 OpenClaw workspace 下创建

选项展示：

📂 请选择工作区目录：

1. 使用当前 workspace: /home/maqb11/.openclaw/workspace/
指定已有目录（请输入路径）
创建新目录（请输入目录名）

使用 AskUserQuestion 让用户选择，然后验证目录是否存在：

- 选择 1：使用当前 workspace
选择 2：验证目录是否存在，不存在则提示错误
选择 3：创建新目录 {workspace}/{dirname}/

0.3 记录工作区配置

在选定的工作区根目录创建 .sdd-workspace 配置文件：

json
{
workspace_path: /path/to/workspace,
initialized_at: 2026-03-16T17:00:00+08:00,
sdd_version: 1.0
}

后续所有 SDD skill 都通过读取这个配置文件获取工作区路径。

步骤 1：模型检查

检查当前模型是否为 Opus（检查 system prompt 中的模型信息）。如果不是 Opus，输出以下纯文本提示并继续（非阻塞）：

⚠️ 当前模型不是 Opus，全局 spec 初始化需要较强的理解和摘要能力，建议切换到 Opus。输入 /model 切换模型。

步骤 2：工作区存在性检查

从 .sdd-workspace 读取工作区路径 {workspace}，检查 {workspace}/spec/global/ 目录是否存在：

- 如果存在： 显示工作区 [{workspace}] 的全局 spec 目录已存在，无需重复初始化。如需修改全局文档，请使用 /sdd-global-change。并停止。
如果不存在： 继续步骤 3。

步骤 3：扫描项目

在工作区目录中扫描项目以构建全面的图景：

AI 扫描工作区中的代码库：

- 技术栈： package.json, requirements.txt, go.mod, Cargo.toml 等
目录结构与模块边界： src/, components/, routes/ 等
路由/页面/API 端点： 推断功能模块
README, CLAUDE.md, 配置文件： 推断业务目标、外部依赖
Docker/部署配置： 推断系统边界和部署拓扑
框架选择、CI/CD 配置、编码规范

注意： 工作区目录下可能包含多个项目，优先扫描主要项目。

步骤 4：生成大纲并确认

展示所有待生成文档的大纲（目录结构 + 每个文档的核心要点）。使用 AskUserQuestion 一次性让用户确认或请求修改。

大纲格式示例：

📋 全局 Spec 初始化大纲

{workspace}/spec/global/
├── constraints.md — 项目架构约束
│ ├── 技术栈: TypeScript, React, Express...
│ ├── 架构决策: Monorepo, RESTful...
│ └── 编码规范 / 部署方式 / 安全约束
├── overview.md — 项目概述
│ ├── 项目目标: ...
│ ├── 核心用户: ...
│ ├── 系统边界: ...（外部依赖）
│ └── 核心业务流程: ...
├── architecture.md — 架构全景
│ ├── 系统组件图: ...
│ ├── 模块划分: ...
│ ├── 数据流: ...
│ └── 部署拓扑: ...
├── features.md — 已有功能清单
│ ├── 模块A: 功能点1, 功能点2...
│ ├── 模块B: 功能点1, 功能点2...
│ └── ...
├── index.md — 归档索引（空表）
├── images/ — 配图目录
└── domains/ — 领域目录（空）

将 ... 占位符替换为扫描发现的实际信息。

如果用户选择需要修改，询问要修改什么，调整大纲后重新确认。

步骤 5：生成所有文档

用户确认大纲后，一次性生成所有文档——不逐个文档确认：

1. 创建 {workspace}/spec/ 目录
创建 {workspace}/spec/global/ 目录
创建 {workspace}/spec/global/domains/ 目录（空）
创建 {workspace}/spec/global/images/ 目录（空）
创建 {workspace}/spec/global/domains/images/ 目录（空）
使用约束模板写入 {workspace}/spec/global/constraints.md，填入发现的信息。无法确定的维度使用（未检测到）。
使用概述模板写入 {workspace}/spec/global/overview.md，填入发现的信息。
使用架构模板写入 {workspace}/spec/global/architecture.md，填入发现的信息。
使用功能清单模板写入 {workspace}/spec/global/features.md，填入发现的信息。
使用索引模板写入 {workspace}/spec/global/index.md，包含空的功能表。

constraints.md 与 architecture.md 的区别：

- constraints.md = 约束规则 — 应该如何做（技术栈选择、编码规范、API 风格规则、安全约束）
architecture.md = 实际现状 — 系统实际是如何组织的（组件图、模块边界、数据流、部署拓扑、外部集成技术细节）

配图占位： 每个文档模板都包含引用。在文档写作时根据配图触发规则插入这些引用。

步骤 6：同步配图生成

所有文档写完后，收集配图需求并逐一生成配图。

6.1 收集配图清单

扫描所有生成的文档中的引用。为每个引用构建清单条目：

json
{
description: 描述文字（用于图片生成 prompt）,
type: architecture|feature-relationship|tech-stack|concept,
style: 根据 Style Mapping 确定,
aspect_ratio: 16:9 或 1:1,
output_path: spec/global/images/NN-type.png
}

配图始终输出到 {workspace}/spec/global/images/ 或 {workspace}/spec/global/domains/images/。

6.2 同步配图生成

遍历清单，逐一生成配图：

对于清单中的每个配图：

1. 显示进度：🖼️ 正在生成第 X/N 张：{description}...
调用 /gen-image skill，参数：prompt={description + style prefix}, aspectratio, size=1K, output={workspace}/spec/global/images/{filename}
成功时：显示 ✅ 已保存: {outputpath}
失败时：重试一次。如果仍然失败，显示 ⚠️ 生成失败: {description}，已跳过并继续下一个配图

所有配图处理完后，显示总结：

- 全部成功：🖼️ 配图全部生成完成（{N} 张）
部分失败：🖼️ 配图生成完成: {X} 张成功

sdd-global-init初始化SDD工作区

sdd-global-init

SDD Global Init — 工作区初始化与全局 Spec 生成

Overview

关键概念