kld-sdd

KLD SDD OpenSpec 工程增强工具：一键初始化 AI 编辑器技能、语义化文档模板和本地本体运行时，支持完整的 SDD（规格驱动开发）研发工作流。

这是什么？

SDD（Specification-Driven Development） 是一种以文档链驱动 AI 编码的研发方法：先写清楚"要做什么"，再让 AI 去实现，避免 AI 乱猜、反复返工。

kld-sdd 帮你在项目中一键配置好这套工作流所需的全部 AI 技能，支持 Cursor、Claude Code、CodeBuddy、Qoder、OpenCode、KunlunZhima、WorkBuddy、Codex 等编辑器。新模板和 Skills 会在产物生成时写入稳定编号与显式关系；本地运行时负责解析、对账和校验这些关系。

本体语义闭环

KLD-SDD 当前内置三项语义能力：

1. 定义 Change、Capability、STMT、AC、Constraint、Design、Task、Artifact、DocumentSection、OntologySnapshot 的最小本体 Schema。
2. 通过模板和 Skills 在产物生成时产生 CHG/CAP/STMT/AC/CON/DES/TASK 编号和显式引用。
3. 将 Proposal→Spec→Design→Task 解析为本地工作态实例，并在 Check/Archive 阶段校验和固化。

关系链示例：

CHG contains CAP
CAP contains STMT
STMT acceptedBy AC
STMT constrainedBy CON
DES realizes STMT
TASK implements DES / covers STMT / dependsOn TASK
ART declares Entity
Entity sourcedFrom SEC

每个本体实体使用双层身份：

• anchor：STMT-ORDER-005 等人工可读编号，跨迭代保持稳定且删除后不复用。
• entity-id：全局唯一 32 位 ID（8 位十六进制），同一逻辑实体跨迭代复用。
• version-id：全局唯一 32 位 ID，每次 added/modified/removed 产生新版本；unchanged 复用历史版本。
• predecessor-version：modified/removed 指向同一实体的直接前序版本。

UUID 由本地命令生成，不依赖网络、机器号或中央 ID 服务：

node skywalk-sdd/log.cjs semantic-identity --delta-state=added
node skywalk-sdd/log.cjs semantic-identity --delta-state=modified --entity-id=<uuid> --predecessor-version=<uuid>
node skywalk-sdd/log.cjs semantic-identity --delta-state=unchanged --entity-id=<uuid> --version-id=<uuid>

项目级校验会同时扫描活动 Change 和 confirmed Archive：不同实体误用同一 UUID、同一版本 UUID 对应不同内容、modified/removed 前序版本断链或同 predecessor 并行分叉都会阻断 Check/Archive。Archive 只有在 manifest、正文 facts_hash 与 confirmed snapshot 一致时，才可成为继承来源。

跨迭代 unchanged 不复制历史原文。当前 Spec 只保存实体 UUID、版本 UUID、来源路径、来源内容哈希和需要保留的显式关系；运行时从唯一 confirmed Archive 解析这些引用，与本次差量组成 Effective Graph。modified 实体也不会自动继承前序全部关系，未显式列入 inherited relations 的历史关系不会进入新版本。

当前工作态 Schema 为 kld-sdd-ontology/v2。完全没有语义锚点的旧自由文本仍可读取，但已包含 CHG/CAP/STMT/AC/CON/DES/TASK 锚点的 v1 产物需要补齐 UUID 身份字段后才能通过 v2 Check/Archive，避免工具在迁移时猜测实体身份。

本地命令：

# 解析与诊断；首次运行会为 Artifact/DocumentSection 分配并持久化 32 位结构 ID sidecar
node skywalk-sdd/log.cjs semantic-scan --project=. --change=<name>

# 文件与工作态本体实例全量对账
node skywalk-sdd/log.cjs semantic-reconcile --project=. --change=<name>

# 按 simple/full/strict 校验；通过时标记 pending
node skywalk-sdd/log.cjs semantic-check --project=. --change=<name> --profile=full

# 查看工作态实例
node skywalk-sdd/log.cjs semantic-status --project=. --change=<name>

# 可选的文件变化采集与同步
node skywalk-sdd/log.cjs semantic-observe --project=. --change=<name>

propose/spec/design/task 在文档写入完成时就必须同步工作态 JSON，不等待 Check 或 Archive。各阶段的 stage_end 会自动执行一次 reconcile 作为无 Hook 环境的兜底；Skill 中的显式 semantic-reconcile 与该兜底幂等。每份 Markdown 的结构化结果写入 openspec/changes/<name>/artifacts/<原相对路径>.ontology.json，聚合索引与全量工作态写入 openspec/changes/<name>/ontology/（含 artifact-index.json、working-ontology.json 等）；这些文件随 change 目录一起提交和归档。skywalk-sdd/state/ontology/ 仅保留 revision 指针与跨进程锁，默认不提交。

工作态 JSON 使用 kld-sdd-working-artifact-facts/v1，明确标记 canonical=false 和 review_status=draft|pending。它用于当前 Change 的渐进式展开、定向查询和跨文档校验，不能直接入知识库。Check 重新解析原文、校验并在全部通过时生成 pending revision；Archive 再次对账后才确认、转换为 canonical-facts.json 并打包。

semantic-observe 不是 Hook 替代品：它不能阻止 Cursor、Qoder 或人工编辑，也不能在落盘前控制内容。Observer 启动/重启后会重新对账，暂态失败和锁冲突不会推进文件指纹；Check 和 Archive 始终重新执行 semantic-reconcile，以处理重复、乱序或丢失的文件事件。

校验 profile：

| Profile | 阻断规则 | |---|---| | simple | 强制 STMT→AC；Design/Task 不存在时跳过 | | full | 强制 STMT→AC→Design→Task 全链和 Task DAG | | strict | 在 full 基础上要求完整语义来源 |

同一 Change 的作者阶段同步、observe、reconcile、check 和 archive 共用跨进程事务锁。ontology/working-ontology.json、diagnostics、file index、artifact index 及所有分文件 JSON 在 change 目录内原子提交，随后切换 skywalk-sdd/state/ontology/<change>/current.json 指针；读取时会拒绝任一文件缺失或 revision 撕裂。

Archive 使用两阶段事务：先复制到 staging，从 staging 重新解析正文并生成本体快照、canonical facts、转换报告和 v2 manifest，所有步骤成功后才切换为正式 archive。归档完成后同时生成相邻的 <日期>-<name>.zip，其中 archive-manifest.json 的文件清单和 SHA-256 必须精确覆盖包内文件，可直接交给知识库消费。语义校验、快照、协议转换、打包或 Spec 同步失败时，活动 Change 会保留或恢复，不留下伪 confirmed 半成品。

生产端归档协议产物：

• archive-ontology.json：KLD-SDD 内部 confirmed 本体快照。
• canonical-facts.json：面向知识库的稳定语义事实，实体与关系均带原文来源及内容哈希。
• conversion-report.json：本体快照到 canonical facts 的转换结果、数量和归一化告警。
• archive-manifest.json：kld-sdd-archive-manifest/v2 身份、内容哈希及完整文件清单。
• openspec/changes/archive/<日期>-<name>.zip：知识库可直接读取的 Archive Package。

快速开始

# 在你的项目目录下执行
npx kld-sdd

初始化完成后，打开你的 AI 编辑器，激活 opsx-* skills 开始工作。

提效评估报告（SkyWalk；单次变更为 v4）

归档与独立 report --change= 会基于同一 Report Model 生成 Markdown / HTML / JSON 三份同源产物（schema_version=sdd-efficiency-report/v4，指标契约 4.0）。仅 change 级破坏性删除公开 legacy_metrics、无折叠兼容附录；变更类型仅 config|transaction|report|composite。单次变更 HTML 使用桌面方案 A，只展示当前 change 的四个页签：概览、指标与阶段、问题与证据、产物与追溯，不混入跨变更趋势。

--period=biweekly|monthly 等项目/周期报告仍使用既有长模板（可含历史兼容附录）。若要对 project 级同步去 legacy，须另开 change，勿在本发行中半迁移。

报告中的业务名称优先于缩写：E1=每个验收场景平均用时，Q3=规约检查得分，P4=编码前检查覆盖，P-R=标准阶段重复次数，P-H=执行记录完整度。标准测量阶段固定为 propose、spec、design、task、check、apply、archive；test、explore 是辅助阶段，可展示但不进入效率分母。

# 单变更报告（默认 html；可指定 markdown/json）→ v4
node skywalk-sdd/log.cjs report --project=. --change=<name> --format=json --output=reports/demo.json

# 双周 / 月度周期对比（需完整窗口）→ 仍为项目级模板
node skywalk-sdd/log.cjs report --project=. --period=biweekly --date-from=YYYY-MM-DD --date-to=YYYY-MM-DD
node skywalk-sdd/log.cjs report --project=. --period=monthly --date-from=YYYY-MM-DD --date-to=YYYY-MM-DD

propose 须确认 change-type；所有阶段必须显式携带 change，历史 general 事件只能通过 scope_link 归属。check_result 应携带 reviewer 独立性与 warning 处置元数据；归档 archive_result 只列真实写入成功的 report_path / report_html_path / report_json_path。

任务采用两个不可混淆的口径：“文档完成度”来自 tasks checkbox，“事件可追溯度”来自严格 task/test 证据。问题同时显示“类别数”和“规则命中次数”；指标同时显示“可计算性”和“可信度”。change 级主视图不再渲染旧 E4/P1/P2/Q5；上述旧指标若仍出现，只可能在项目级兼容附录中。

核心工作流：5 个 skills

初始化后，你会得到以下 SDD skills，按顺序使用：

opsx-propose → opsx-spec → opsx-design → opsx-task → opsx-check
                                                          ↓
                                                    opsx-knowledge（独立使用）

第一步：opsx-propose <变更名称>

做什么：创建业务意图文档，明确"为什么要做这件事"。

适合场景：需求评审后，把产品需求转化为结构化的业务意图文档。

AI 会做什么：

• 如果你没说清楚，AI 会主动问你 4 个问题（痛点/目标/影响模块/约束）
• 推导出变更的 kebab-case 名称，如 add-user-auth
• 生成 proposal.md 并展示摘要让你确认

产出：openspec/changes/<name>/proposal.md

第二步：opsx-spec <变更名称>

做什么：创建技术契约文档，明确"要实现什么 API 和规范"。

这是代码生成的唯一依据，必须精确无歧义。

AI 会做什么：

• 读取 proposal.md，检查上下文是否完整
• 发现模糊描述时主动追问（如"高性能"→ 具体 QPS/RT 是多少？）
• 向你确认 API 范围、性能指标、安全要求后，生成 spec.md

质量红线（AI 自检）：

• 所有参数有类型、必填标记、范围约束、示例值
• 性能指标是具体数字（如 < 100ms P99）
• 边界场景覆盖正常流程 + 所有异常流程

产出：openspec/changes/<name>/spec.md

第三步：opsx-design <变更名称>

做什么：创建技术实现方案，明确"怎么做"（聚焦本业务，不写全局架构）。

AI 会做什么：

• 读取 propose.md + spec.md，分析约束和设计难点
• 若存在多种实现方案，列出方案让你选择
• 生成 design.md（包含时序图、模块设计、数据表结构、异常处理）

质量红线（AI 自检）：

• 不写全局中间件或框架选型（那是项目级别的事）
• 接口调用明确到具体接口名和调用方式
• 数据库表结构到字段级别（类型、长度、索引）

产出：openspec/changes/<name>/design.md

第四步：opsx-task <变更名称>

做什么：将 design.md 拆解为 AI 可执行的原子任务列表。

每个任务的标准：AI 能在 5 分钟内完成。

AI 会做什么：

• 统计需要覆盖的实现点（API 数量、模块数量、数据表数量）
• 预估任务总数，确认拆解策略后再执行
• 发现任务风险（循环依赖、复杂算法）时主动告知

质量红线（AI 自检）：

• 100% 覆盖 spec.md 的每个 API 和约束
• 100% 覆盖 design.md 的每个模块和接口
• 每个任务有明确验收标准和单测要求

产出：Full 模式为 openspec/changes/<name>/specs/<capability>/tasks.md，Simple 模式为根目录 tasks.md

第五步：opsx-check <变更名称>

做什么：质量门禁检查，验证文档链的完整性、一致性和可执行性。

在让 AI 写代码之前，先激活这个 skill。

检查内容： | 检查项 | 说明 | |-------|------| | 完整性 | 4 个文档是否存在，每个文档章节是否完整 | | 一致性 | spec 的 API 在 design 中是否有对应方案；各文档字段命名是否一致 | | 可执行性 | task 的每个任务是否可独立执行；验收标准是否可验证 | | 本体追溯 | 编号是否唯一，STMT/AC/DES/TASK 关系是否完整，Task DAG 是否成环 |

发现问题时，AI 会列出严重问题和警告，并提供三种处理方式供你选择。

独立使用：opsx-knowledge

做什么：查询 MM/CO 业务知识库，辅助理解业务名词和领域规则。

预置技能

初始化后，SDD 全套 skill 部署为 扁平一层（Claude Code 识别规则）：

.claude/skills/opsx-propose/SKILL.md   → /opsx-propose
.claude/skills/opsx-spec/SKILL.md      → /opsx-spec
...

模板源码组织在 kld-sdd/templates/skills/kld-sdd/（仅用于打包维护，不是 Claude 的识别路径）。

Claude Code 只识别 .claude/skills/<skill-name>/SKILL.md 这一层。嵌套在 skills/kld-sdd/opsx-* 下不会被 / 菜单发现。GitNexus 能识别是因为 npx gitnexus analyze 同时安装了 ~/.claude/skills/gitnexus-*/ 扁平 skill。

安装与初始化

方式一：npx（推荐，无需全局安装）

cd your-project
npx kld-sdd

方式二：全局安装

npm install -g kld-sdd
cd your-project
kld-sdd-init

初始化选项

kld-sdd-init                    # 完整初始化（推荐）
kld-sdd-init --skip-openspec    # 跳过 openspec 安装
kld-sdd-init --tool cursor      # 仅配置 Cursor
kld-sdd-init --tool claude      # 仅配置 Claude Code
kld-sdd-init --tool codebuddy   # 仅配置 CodeBuddy
kld-sdd-init --tool codex       # 仅配置 Codex

初始化后的目录结构

your-project/
├── openspec/
│   └── changes/
│       └── <name>/
│           ├── proposal.md
│           ├── ontology/
│           │   ├── working-ontology.json
│           │   ├── artifact-index.json
│           │   ├── diagnostics.json
│           │   ├── file-index.json
│           │   ├── ontology-identities.json
│           │   └── continuity-resolution.json
│           └── artifacts/
│               ├── proposal.ontology.json
│               └── specs/<capability>/
│                   ├── spec.ontology.json
│                   ├── design.ontology.json
│                   └── tasks.ontology.json
├── openspec-templates/              # openSpec 四文档参考模版
│   ├── proposal.md
│   ├── spec.md
│   ├── design.md
│   └── tasks.md
├── skywalk-sdd/
│   ├── log.cjs                      # Telemetry + semantic-* 命令入口
│   ├── metrics-v3.cjs               # V3 提效评估纯计算模块（随 init 部署）
│   ├── ontology/                    # 本地本体解析、校验、观察和对账运行时
│   └── state/ontology/
│       ├── .locks/<change>.lock     # observe/reconcile/check/archive 跨进程锁
│       └── <change>/
│           └── current.json         # 当前 revision 指针（本体 JSON 在 change 目录）
├── .cursor/
│   └── skills/opsx-*/               # SDD skills（扁平一层）
├── .claude/
│   └── skills/opsx-*/               # SDD skills（扁平一层）
├── .codebuddy/
│   └── skills/opsx-*/               # SDD skills（扁平一层）
└── .agents/
    └── skills/opsx-*/               # Codex 项目级 skills

支持的 AI 编辑器

| 编辑器 | 技能格式 | 技能支持 | 自动创建目录 | |-------|---------|---------|------------| | Cursor | SKILL.md | ✅ | 已存在时 | | Claude Code | SKILL.md | ✅ | 已存在时 | | CodeBuddy | SKILL.md | ✅ | 自动创建 | | Qoder | SKILL.md | ✅ | 自动创建 | | OpenCode | SKILL.md | ✅ | 自动创建 | | KunlunZhima | SKILL.md | ✅ | 自动创建 | | WorkBuddy | SKILL.md | ✅ | 自动创建 | | Codex | SKILL.md（.agents/skills/） | ✅ | 自动创建 |

Codex 初始化会创建 .agents/skills/opsx-*/，用于项目级技能。

团队协作流程

架构师 / TL

1. 在项目中运行 kld-sdd-init 一次
2. 将团队规范文档放入 team-configs/ 目录
3. 将自定义 skills 放入 .*/skills/ 目录
4. 提交到 Git

新成员 onboarding

git clone <project>
npm install
npx kld-sdd   # 一键配置好所有 AI 工具

之后直接在编辑器中激活 opsx-propose 开始工作。

.gitignore 配置

初始化时自动添加：

# KLD SDD 个人配置 (保留团队配置)
.cursor/commands/personal-*
.claude/commands/personal-*
.codebuddy/commands/personal-*
.agents/commands/personal-*

# 但保留团队配置的占位目录
!.cursor/commands/team-*
!.claude/commands/team-*
!.codebuddy/commands/team-*
!.agents/commands/team-*

常见问题

Q：openspec 是什么，必须安装吗？

A：openspec 是管理 SDD 变更目录的 CLI 工具（负责创建变更目录和读取指导规则）。初始化时会自动安装，如果安装失败也可以跳过（--skip-openspec），手动创建 openspec/changes/<name>/ 目录后 skills 仍然可用。

Q：我用 CodeBuddy 或 Codex，目录不存在怎么办？

A：不用担心，kld-sdd-init 会自动创建 .codebuddy/skills/、.agents/skills/ 等目录。

Q：opsx-propose 和直接让 AI 写代码有什么区别？

A：直接让 AI 写代码，AI 会凭空假设很多细节，导致返工。SDD 流程强制先把"要做什么"写清楚，AI 按契约实现，减少歧义和返工。

Q：团队规范已经有了，怎么让 AI 每次都遵守？

A：将规范文档转为 skill 文件，部署到 .*/skills/ 目录后，AI 编辑器激活该 skill 时会自动遵守这些规范。

License

MIT