kld-sdd 2.6.6 → 2.6.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/kld-sdd-init.js +39 -3
- package/lib/init.js +320 -45
- package/lib/workspace-layout.js +2 -0
- package/package.json +2 -2
- package/skywalk-sdd/context-client.cjs +12 -1
- package/skywalk-sdd/ontology/active-changes.cjs +297 -0
- package/skywalk-sdd/ontology/archive-package.cjs +95 -6
- package/skywalk-sdd/ontology/artifact-parser.cjs +50 -7
- package/skywalk-sdd/ontology/change-key.cjs +241 -0
- package/skywalk-sdd/ontology/cli.cjs +154 -0
- package/skywalk-sdd/ontology/external-key.cjs +159 -0
- package/skywalk-sdd/ontology/list-changes.cjs +110 -0
- package/skywalk-sdd/ontology/modules.cjs +167 -0
- package/skywalk-sdd/ontology/naming-diagnose.cjs +594 -0
- package/skywalk-sdd/ontology/normalizer.cjs +4 -0
- package/skywalk-sdd/ontology/schema.cjs +5 -0
- package/skywalk-sdd/ontology/sdd-config.cjs +335 -0
- package/skywalk-sdd/ontology/traceability-validator.cjs +175 -0
- package/skywalk-sdd/ontology/workspace-layout.cjs +194 -0
- package/templates/dot-sdd.yaml +8 -0
- package/templates/git-hooks/commit-msg-sdd-trailer.cjs +224 -0
- package/templates/modules.yaml +13 -0
- package/templates/openspec/proposal.md +12 -3
- package/templates/openspec/spec.md +3 -3
- package/templates/sdd.config.yaml +12 -0
- package/templates/skills/kld-sdd/opsx-apply/SKILL.md +3 -3
- package/templates/skills/kld-sdd/opsx-apply/checklist.md +1 -1
- package/templates/skills/kld-sdd/opsx-archive/SKILL.md +10 -0
- package/templates/skills/kld-sdd/opsx-check/SKILL.md +47 -3
- package/templates/skills/kld-sdd/opsx-explore/SKILL.md +37 -17
- package/templates/skills/kld-sdd/opsx-kb-ingest/SKILL.md +13 -14
- package/templates/skills/kld-sdd/opsx-kb-ingest/reference.md +13 -0
- package/templates/skills/kld-sdd/opsx-ontology-query/SKILL.md +26 -15
- package/templates/skills/kld-sdd/opsx-propose/SKILL.md +61 -23
- package/templates/skills/kld-sdd/opsx-spec/SKILL.md +8 -2
- package/templates/skills/kld-sdd/opsx-task/SKILL.md +1 -0
- package/templates/skills/kld-sdd/opsx-tdd-core/checklist.md +1 -1
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
|
|
1
|
+
---
|
|
2
2
|
name: opsx-explore
|
|
3
3
|
description: "浏览变更技能 - 查看所有变更状态和 SDD 文档完整性概览"
|
|
4
4
|
argument-hint: "[change-name]"
|
|
@@ -10,8 +10,6 @@ metadata:
|
|
|
10
10
|
allowed-tools:
|
|
11
11
|
- Bash
|
|
12
12
|
- Read
|
|
13
|
-
- Write
|
|
14
|
-
- Edit
|
|
15
13
|
---
|
|
16
14
|
|
|
17
15
|
你是一个 SDD(Specification-Driven Development)变更浏览专家。激活本技能后,你将展示项目中所有变更的状态概览,并引导用户执行下一步操作。
|
|
@@ -40,8 +38,15 @@ allowed-tools:
|
|
|
40
38
|
|
|
41
39
|
## 启动流程
|
|
42
40
|
|
|
43
|
-
### 1.
|
|
41
|
+
### 1. 获取所有变更列表(按模块中文分组)
|
|
44
42
|
|
|
43
|
+
优先使用命名协议分组:
|
|
44
|
+
```bash
|
|
45
|
+
node skywalk-sdd/ontology/cli.cjs list-changes --project=.
|
|
46
|
+
# 需要结构化数据时加 --json
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
也可辅助:
|
|
45
50
|
```bash
|
|
46
51
|
openspec list
|
|
47
52
|
```
|
|
@@ -52,25 +57,40 @@ openspec list
|
|
|
52
57
|
### 2. 检查每个变更的 SDD 文档完整性
|
|
53
58
|
|
|
54
59
|
对每个变更,检查以下文件是否存在:
|
|
55
|
-
- `openspec/changes/<
|
|
56
|
-
- `openspec/changes/<
|
|
57
|
-
- `openspec/changes/<
|
|
58
|
-
- `openspec/changes/<
|
|
60
|
+
- `openspec/changes/<change-key>/proposal.md`(P)
|
|
61
|
+
- `openspec/changes/<change-key>/specs/<capability>/spec.md`(S)
|
|
62
|
+
- `openspec/changes/<change-key>/specs/<capability>/design.md`(D)
|
|
63
|
+
- `openspec/changes/<change-key>/specs/<capability>/tasks.md`(T)
|
|
59
64
|
|
|
60
65
|
同时获取每个变更状态:
|
|
61
66
|
```bash
|
|
62
|
-
openspec status --change "<
|
|
67
|
+
openspec status --change "<change-key>" --json
|
|
63
68
|
```
|
|
64
69
|
|
|
65
|
-
### 3.
|
|
70
|
+
### 3. 展示按模块分组的变更概览
|
|
71
|
+
|
|
72
|
+
展示格式(title 来自 proposal frontmatter,目录定位使用 change-key):
|
|
73
|
+
|
|
74
|
+
```text
|
|
75
|
+
📦 财务核算 (fi)
|
|
76
|
+
● 会计凭证头创建
|
|
77
|
+
fi-260727-account-doc-head-create
|
|
78
|
+
P✅ S✅ D✅ T❌ | 建议: /opsx-task fi-260727-account-doc-head-create
|
|
79
|
+
|
|
80
|
+
📦 跨模块 (cross)
|
|
81
|
+
● 凭证与库存联动
|
|
82
|
+
cross-260727-fi-mm-voucher-stock-link
|
|
83
|
+
affected: fi, mm
|
|
84
|
+
|
|
85
|
+
📦 未分类
|
|
86
|
+
● legacy-add-user-auth
|
|
87
|
+
legacy-add-user-auth
|
|
88
|
+
```
|
|
66
89
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
> | add-user-auth | ✅ | ✅ | ✅ | ❌ | PENDING | `/opsx-task add-user-auth` |
|
|
72
|
-
> | payment-refund | ✅ | ❌ | ❌ | ❌ | PENDING | `/opsx-spec payment-refund` |
|
|
73
|
-
> | points-exchange | ✅ | ✅ | ✅ | ✅ | IMPLEMENTING | `/opsx-check points-exchange` |"
|
|
90
|
+
规则:
|
|
91
|
+
- 分组依据 `module`;中文组名来自 `modules.yaml`
|
|
92
|
+
- 缺少 change-key/title/module 的存量 change 归入「未分类」
|
|
93
|
+
- `module=cross` 时额外展示 `affected-modules`
|
|
74
94
|
|
|
75
95
|
### 4. 【交互引导】选择操作
|
|
76
96
|
|
|
@@ -5,24 +5,10 @@ description: >-
|
|
|
5
5
|
(archive:ingest scope). Prompts for API key and multi-selects spaces/KBs into
|
|
6
6
|
local skill state. Supports upload, job status query, job list, and retry.
|
|
7
7
|
Use when ingesting new or updated knowledge archives into the ontology KB.
|
|
8
|
-
argument-hint: "[path-to-archive.zip]"
|
|
9
|
-
license: MIT
|
|
10
|
-
compatibility: Requires Engineering KB API (API Key with archive:ingest).
|
|
11
|
-
metadata:
|
|
12
|
-
author: sdd-team
|
|
13
|
-
version: "1.0"
|
|
14
|
-
source: "kb-sdd/skills/opsx-kb-ingest"
|
|
15
|
-
allowed-tools:
|
|
16
|
-
- Bash
|
|
17
|
-
- Read
|
|
18
|
-
- Write
|
|
19
|
-
- Edit
|
|
20
8
|
---
|
|
21
9
|
|
|
22
10
|
# 本体知识库 · 入库
|
|
23
11
|
|
|
24
|
-
> **部署说明**:本技能随 `kld-sdd-init` 安装到项目 skills 目录。权威源在工程知识库仓 `skills/opsx-kb-ingest`;`opsx-archive` **硬依赖**本技能完成收尾入库。
|
|
25
|
-
|
|
26
12
|
只负责**入库**(zip 上传)。鉴权只用 **API Key**(`Authorization: Bearer sk_sdd_…`),**禁止**走手机号登录。
|
|
27
13
|
|
|
28
14
|
> 控制台知识库页另有浮动 Ontology Agent(会话登录 + SSE);本 Skill 仍走 API Key,二者分开。
|
|
@@ -127,6 +113,9 @@ curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/ingestions/$JO
|
|
|
127
113
|
- object_type 与实体类型匹配:`requirement`/`feature`→Capability;`scenario`→SpecificationStatement|AcceptanceCriterion
|
|
128
114
|
- 包内无重复 `(external key, entity_id)` 绑定对
|
|
129
115
|
- `project_id` / `spaceKey` 既有规则保留
|
|
116
|
+
- **编号格式**:三条正则(见 reference)+ 场景 SLUG≤40 / 键总长≤120;先归一化再匹配
|
|
117
|
+
- **场景作用域**:scenario 键的 REQ 前缀必须出现在同包 requirement 绑定集合
|
|
118
|
+
- **功能配对**:同实体每条 feature 绑定必须能与某 requirement 条目的 `feature_id` 精确配对;反向同理
|
|
130
119
|
|
|
131
120
|
详细字段说明 → [reference.md](reference.md)。
|
|
132
121
|
|
|
@@ -160,6 +149,16 @@ curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/ingestions/$JO
|
|
|
160
149
|
- **改为新锚点**:回到 kld-sdd,分配新锚点与新 entity_id,重新 check → 归档 → 入库
|
|
161
150
|
3. **禁止**在 KB 内现场改绑或解绑。
|
|
162
151
|
|
|
152
|
+
若编号门禁失败:
|
|
153
|
+
|
|
154
|
+
| errorCode | 指引 |
|
|
155
|
+
|-----------|------|
|
|
156
|
+
| `EXTERNAL_REFERENCE_FORMAT_INVALID` | 编号不合规 → **回需求管理系统换发**;不得手改编号硬闯 |
|
|
157
|
+
| `EXTERNAL_REFERENCE_SCOPE_MISMATCH` | 场景键 REQ 前缀不在申报集合 → 回 kld-sdd spec 修正 external-ref |
|
|
158
|
+
| `EXTERNAL_REFERENCE_FEATURE_UNBOUND` | feature↔requirement.`feature_id` 配对断裂 → 回 propose/archive 修正线缆字段 |
|
|
159
|
+
|
|
160
|
+
**禁止**手改包内编号绕过门禁。
|
|
161
|
+
|
|
163
162
|
**硬规则**
|
|
164
163
|
|
|
165
164
|
- 无 `apiKey` 不得猜密钥、不得改走 login。
|
|
@@ -141,8 +141,21 @@ POST {base}/ingestions/{jobId}/retry
|
|
|
141
141
|
| `EXTERNAL_REF_CONFLICT` | 同外部键+同锚点已绑不同 entity_id;整包回滚;见 `report.details` |
|
|
142
142
|
| `EXTERNAL_REFERENCE_TYPE_MISMATCH` | 包内 object_type 与实体类型不匹配 |
|
|
143
143
|
| `EXTERNAL_REFERENCE_DUPLICATE_IN_PACKAGE` | 包内重复 `(external key, entity_id)` |
|
|
144
|
+
| `EXTERNAL_REFERENCE_FORMAT_INVALID` | 编号归一化后不合规(含 requirement.`feature_id`);回需求系统换发 |
|
|
145
|
+
| `EXTERNAL_REFERENCE_SCOPE_MISMATCH` | 场景键 REQ 前缀不在同包 requirement 集合;回 kld-sdd spec 修正 |
|
|
146
|
+
| `EXTERNAL_REFERENCE_FEATURE_UNBOUND` | feature 绑定与 requirement.`feature_id` 无法配对;回 propose/archive |
|
|
144
147
|
| `FACTS_SCHEMA_UNSUPPORTED` | canonical-facts schema 非 v1/v2 |
|
|
145
148
|
|
|
149
|
+
### 编号正则(与 KB 设计 §2 / ExternalKeyFormat 一致)
|
|
150
|
+
|
|
151
|
+
```text
|
|
152
|
+
requirement: ^REQ-[A-Z][A-Z0-9]{1,7}-[0-9]{4}-[0-9]{3,6}$
|
|
153
|
+
feature: ^FEAT-[A-Z][A-Z0-9]{1,7}-[0-9]{3,6}$
|
|
154
|
+
scenario: ^REQ-[A-Z][A-Z0-9]{1,7}-[0-9]{4}-[0-9]{3,6}:SCN-[a-z0-9]+(-[a-z0-9]+)*-[0-9]{3}$
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
requirement 条目可选 `feature_id`(FEAT 文法);配对关系随线缆走,KB 不反查 frontmatter。
|
|
158
|
+
|
|
146
159
|
### `EXTERNAL_REF_CONFLICT` 的 report.details
|
|
147
160
|
|
|
148
161
|
```json
|
|
@@ -5,24 +5,10 @@ description: >-
|
|
|
5
5
|
entity/impact/ontology-view). Prompts for API key and multi-selects spaces/KBs into
|
|
6
6
|
local skill state. Use when looking up Spec/design facts, Spec reuse, impact, or
|
|
7
7
|
citation-backed answers from the ontology KB.
|
|
8
|
-
argument-hint: "[query or continuity intent]"
|
|
9
|
-
license: MIT
|
|
10
|
-
compatibility: Requires Engineering KB API (API Key with context:read).
|
|
11
|
-
metadata:
|
|
12
|
-
author: sdd-team
|
|
13
|
-
version: "1.0"
|
|
14
|
-
source: "kb-sdd/skills/opsx-ontology-query"
|
|
15
|
-
allowed-tools:
|
|
16
|
-
- Bash
|
|
17
|
-
- Read
|
|
18
|
-
- Write
|
|
19
|
-
- Edit
|
|
20
8
|
---
|
|
21
9
|
|
|
22
10
|
# 本体知识库 · 查询
|
|
23
11
|
|
|
24
|
-
> **部署说明**:本技能随 `kld-sdd-init` 安装到项目 skills 目录。权威源在工程知识库仓 `skills/opsx-ontology-query`;`opsx-propose` / `opsx-spec` 等流程技能**硬依赖**本技能,缺失时不得用本地 archive 兜底。
|
|
25
|
-
|
|
26
12
|
只负责**查**。鉴权只用 **API Key**(`Authorization: Bearer sk_sdd_…`),**禁止**走手机号登录。
|
|
27
13
|
|
|
28
14
|
> 控制台知识库页另有浮动 Ontology Agent(会话登录 + SSE);本 Skill 仍走 API Key,二者分开。
|
|
@@ -124,6 +110,31 @@ curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/entities/resol
|
|
|
124
110
|
|
|
125
111
|
命中时关注:`resolution=LINK_EXISTING` 且 `inheritanceAllowed=true`(可继承 n);`removedBindingCount`(已失效绑定 m);`matchType=HISTORICAL_ONLY` 表示仅有失效绑定,不可继承。
|
|
126
112
|
|
|
113
|
+
**按功能号圈能力(propose 前)**
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/entities/resolve" \
|
|
117
|
+
-H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
|
|
118
|
+
-d '{
|
|
119
|
+
"externalSystem":"requirement-mgmt",
|
|
120
|
+
"externalObjectType":"feature",
|
|
121
|
+
"externalId":"FEAT-FI-012",
|
|
122
|
+
"entityType":"Capability"
|
|
123
|
+
}'
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
展示该功能下存活 / 失效能力清单,辅助勾选本次 CAP 范围;此查询只作范围参考,不改变 Continuity 判定优先级。
|
|
127
|
+
|
|
128
|
+
### 编号文法速查(权威在 KB 仓设计 §2)
|
|
129
|
+
|
|
130
|
+
```text
|
|
131
|
+
requirement: ^REQ-[A-Z][A-Z0-9]{1,7}-[0-9]{4}-[0-9]{3,6}$
|
|
132
|
+
feature: ^FEAT-[A-Z][A-Z0-9]{1,7}-[0-9]{3,6}$
|
|
133
|
+
scenario: ^REQ-…:SCN-[a-z0-9]+(-[a-z0-9]+)*-[0-9]{3}$
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
归一化:trim;REQ/FEAT 段大写;SCN slug 小写。编号五律摘要:REQ/FEAT 仅需求系统铸号;SCN 由 kld-sdd/opsx-spec 铸号;编号≠身份;归属权威在需求系统;历史绑定 append-only。
|
|
137
|
+
|
|
127
138
|
**match-requirement**
|
|
128
139
|
|
|
129
140
|
```bash
|
|
@@ -152,7 +163,7 @@ curl -sS -X POST "$API/v1/spaces/$SPACE_ID/knowledge-bases/$KB_ID/context/match-
|
|
|
152
163
|
|
|
153
164
|
### 命中
|
|
154
165
|
1. **{displayName}**({entityType})@ {kbName}
|
|
155
|
-
- id / version / matchType / externalRefs
|
|
166
|
+
- id / version / matchType / externalRefs(归一化形态)…
|
|
156
167
|
- 若外部键命中:可继承 n / 已失效绑定 m
|
|
157
168
|
```
|
|
158
169
|
|
|
@@ -54,13 +54,25 @@ allowed-tools:
|
|
|
54
54
|
|
|
55
55
|
## 启动流程
|
|
56
56
|
|
|
57
|
-
### 1.
|
|
57
|
+
### 1. 输入处理与 Change Key 生成
|
|
58
58
|
|
|
59
59
|
当用户激活此 skill 时:
|
|
60
60
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
61
|
+
**若提供了变更描述(中文优先)**:
|
|
62
|
+
1. 保留中文描述作为 `title`(人读名称)
|
|
63
|
+
2. 读取项目根 `modules.yaml`;不存在则先引导创建(可参考模板 `templates/modules.yaml`)
|
|
64
|
+
3. 从描述推断模块代号;无法唯一判断时用 **AskUserQuestion** 让用户选择
|
|
65
|
+
4. 涉及多个模块时使用保留代号 `cross`,并准备 `affected-modules`(≥2)
|
|
66
|
+
5. 生成英文短 slug(小写、连字符、建议 ≤48 字符)
|
|
67
|
+
6. 用本地日历日 `YYMMDD` 生成 change-key,并做冲突消解:
|
|
68
|
+
```bash
|
|
69
|
+
node skywalk-sdd/ontology/cli.cjs change-key --generate --module=<code> --slug=<slug> --project=.
|
|
70
|
+
```
|
|
71
|
+
7. 得到:
|
|
72
|
+
- `change-key`:spec 仓目录名 `openspec/changes/<change-key>/`(权威名称;不等于代码分支名)
|
|
73
|
+
- `change-id`:`CHG-` + change-key 大写(仅创建时生成一次,之后永不改)
|
|
74
|
+
- 若在个人工作目录执行:可顺带提醒未接入的代码子仓执行 `kld-sdd sync-repos`(不装 skills)
|
|
75
|
+
8. 跳转到第 2 步
|
|
64
76
|
|
|
65
77
|
**若未提供任何输入**,使用 **AskUserQuestion** 询问:
|
|
66
78
|
> "请描述本次变更的业务需求:
|
|
@@ -69,14 +81,15 @@ allowed-tools:
|
|
|
69
81
|
> 3. 涉及哪些模块/系统?
|
|
70
82
|
> 4. 有什么约束条件?(时间/技术/资源)"
|
|
71
83
|
|
|
72
|
-
从描述中推导 kebab-case 名称。
|
|
73
|
-
|
|
74
84
|
**【澄清机制】若用户描述模糊,主动追问**:
|
|
75
85
|
- 若目标不明确:"请用一句话明确本次变更要达成的具体目标"
|
|
76
86
|
- 若影响范围不清:"请列出本次变更涉及的所有模块/服务"
|
|
77
87
|
- 若约束未提及:"是否有时间限制、技术约束或依赖前提?"
|
|
78
88
|
|
|
79
|
-
**重要**:未明确需求前不得继续。
|
|
89
|
+
**重要**:未明确需求前不得继续。change-key 必须通过校验,禁止手写不合规目录名:
|
|
90
|
+
```bash
|
|
91
|
+
node skywalk-sdd/ontology/cli.cjs change-key --validate <change-key> --project=.
|
|
92
|
+
```
|
|
80
93
|
|
|
81
94
|
### 2. 【上下文加载】识别并读取用户提供的文件
|
|
82
95
|
|
|
@@ -99,23 +112,36 @@ allowed-tools:
|
|
|
99
112
|
```bash
|
|
100
113
|
openspec list --json 2>/dev/null || true
|
|
101
114
|
```
|
|
102
|
-
或直接探测 `openspec/changes/<
|
|
115
|
+
或直接探测 `openspec/changes/<change-key>/` 是否存在(含 `.openspec.yaml` 或 `proposal.md`)。排除 `logs/` 目录——`logs/` 是 telemetry 自动创建的,不代表变更已初始化。
|
|
103
116
|
|
|
104
117
|
**第 2 步:根据检测结果决定**:
|
|
105
118
|
- **不存在** → 直接执行第 3 步创建。
|
|
106
|
-
- **已存在** → 先询问用户,**不要直接 new**:"变更 `<
|
|
119
|
+
- **已存在** → 先询问用户,**不要直接 new**:"变更 `<change-key>` 已存在,请选择:
|
|
107
120
|
- A. 覆盖原有变更(删除重建)
|
|
108
121
|
- B. 继续编辑现有变更
|
|
109
122
|
- C. 取消操作"
|
|
110
123
|
- **若目录仅含 `logs/`(无 `.openspec.yaml` 且无 `proposal.md`)**:提示用户"检测到残留空变更目录(仅含 telemetry 自动创建的 logs/),建议选 A 覆盖重建,避免复用空目录导致后续流程混淆"
|
|
111
|
-
- 用户选 A → 先删除 `openspec/changes/<
|
|
124
|
+
- 用户选 A → 先删除 `openspec/changes/<change-key>/` 再执行第 3 步;选 B → 跳过创建直接进入 §4;选 C → 终止。
|
|
112
125
|
|
|
113
126
|
**第 3 步:创建变更目录**(仅在不存在或用户确认覆盖后执行):
|
|
114
127
|
```bash
|
|
115
|
-
openspec new change "<
|
|
128
|
+
openspec new change "<change-key>"
|
|
116
129
|
```
|
|
117
130
|
|
|
118
|
-
此命令在 `openspec/changes/<
|
|
131
|
+
此命令在 `openspec/changes/<change-key>/` 创建变更目录和 `.openspec.yaml`。目录名必须等于 change-key。
|
|
132
|
+
|
|
133
|
+
**第 4 步:隐式登记活动变更**(创建目录后立即执行,不询问用户):
|
|
134
|
+
```bash
|
|
135
|
+
node skywalk-sdd/ontology/cli.cjs active-change --register --change=<change-key> \
|
|
136
|
+
--title="<中文标题>" --module=<code> --summary="<一句话摘要>" --project=.
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
写入 spec 仓根目录 `sdd.config.yaml` 的 `active_changes`。作用:
|
|
140
|
+
|
|
141
|
+
- 所有已接入代码仓的 AI 经 `sdd.specPath` 读到同一份,知道「当前在做哪个 change、中文叫什么」;
|
|
142
|
+
- 代码仓 `git commit` 时由 commit-msg Hook 自动写成 `Spec-Change` Trailer(多个活动 change 就写多条)。
|
|
143
|
+
|
|
144
|
+
登记按 change-key 幂等;同一 change 重复 propose 只更新标题/摘要。**不需要用户手工编辑该文件**。
|
|
119
145
|
|
|
120
146
|
### 3.5 【首次检测】overview.md 全局契约空模板引导
|
|
121
147
|
|
|
@@ -162,13 +188,21 @@ openspec instructions proposal --change "<name>" --json
|
|
|
162
188
|
|
|
163
189
|
> 完整性检查(问题描述/目标/模块/约束 4 项)与缺失补充机制见 `./checklist.md`「§6 需求完整性检查」。发现缺失时主动询问用户补充。
|
|
164
190
|
|
|
165
|
-
### 6.5
|
|
191
|
+
### 6.5 【编号入场 + Continuity】需求 / Capability 身份(只到 CAP,不做场景)
|
|
166
192
|
|
|
167
|
-
在创建变更目录之后、写 proposal 能力列表之前(或紧接 CAP
|
|
193
|
+
在创建变更目录之后、写 proposal 能力列表之前(或紧接 CAP 编号分配前)。**验号必须在 resolve 之前**:
|
|
168
194
|
|
|
169
|
-
1.
|
|
170
|
-
2.
|
|
171
|
-
|
|
195
|
+
1. 收集 REQ 号(含可选 `feature-id`);没有则问一次。
|
|
196
|
+
2. 逐个验号(确定性入口,禁止肉眼判正则):
|
|
197
|
+
```bash
|
|
198
|
+
node skywalk-sdd/ontology/cli.cjs external-key --validate "<REQ-...>" --type requirement
|
|
199
|
+
# 若有 feature-id:
|
|
200
|
+
node skywalk-sdd/ontology/cli.cjs external-key --validate "<FEAT-...>" --type feature
|
|
201
|
+
```
|
|
202
|
+
- REQ/FEAT 不合规 → **拒绝进入 resolve**,告知「编号不合规,请回需求管理系统核实/换发」;Agent 不得猜测、补位、改写。
|
|
203
|
+
- 用户明确说「没有外部需求号」→ 走 `numbering-waiver.reason`(必填理由);`requirement-refs` 必须为空;提示本轮不种桥。
|
|
204
|
+
3. **先加载依赖技能**:确认 `${AGENT_SKILL_DIR}/opsx-ontology-query/SKILL.md` 存在并 Read;按该技能完成 API Key / 空间与 KB 选择。未安装则停止本步。
|
|
205
|
+
4. 验号通过后才 resolve:
|
|
172
206
|
```bash
|
|
173
207
|
node skywalk-sdd/context-client.cjs --mode=resolve \
|
|
174
208
|
--external-system=requirement-mgmt \
|
|
@@ -178,11 +212,12 @@ node skywalk-sdd/context-client.cjs --mode=resolve \
|
|
|
178
212
|
--space-id="$ENGINEERING_KB_SPACE_ID" \
|
|
179
213
|
--kb-id="$ENGINEERING_KB_KB_ID"
|
|
180
214
|
```
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
215
|
+
5. 若申报了 feature-id:额外 `objectType=feature` resolve 一次,展示「该功能下已有能力 n 个(存活 m / 失效 k)」辅助勾选 CAP 范围;不改变 Continuity 判定优先级。
|
|
216
|
+
6. 按 KB 结果确认 Continuity:`iteration` / `similar-reference` / `new`;勾选本次涉及的 CAP。
|
|
217
|
+
7. 写入 proposal frontmatter:`requirement-refs`(含 `feature-id`)/ `numbering-waiver` + `continuity`。**禁止**写本地 archive 文件夹名作为 `base-archive`。
|
|
218
|
+
8. CAP 级「同 key + 同锚点、不同 entity_id」当场问 A/B/C;决议写入 `continuity-resolution.json` 的 `capabilities[]`。
|
|
219
|
+
9. KB 不可用 → `degraded` 继续,**禁止**扫本地 `archive/` 抄 UUID。
|
|
220
|
+
10. **不得**在本阶段生成 STMT/AC/场景或裁决场景身份;**不得**铸/改 REQ/FEAT 号。
|
|
186
221
|
|
|
187
222
|
### 7. 【交互引导】文档拆分模式选择
|
|
188
223
|
|
|
@@ -229,7 +264,10 @@ node skywalk-sdd/context-client.cjs --mode=resolve \
|
|
|
229
264
|
|
|
230
265
|
## 本体语义生成契约
|
|
231
266
|
|
|
232
|
-
- 创建 Change 时必须写入 `change-id: CHG-<
|
|
267
|
+
- 创建 Change 时必须写入 `change-key`、中文 `title`、`module`,以及 `change-id: CHG-<MODULE>-<YYMMDD>-<SLUG>`(由初始 change-key 派生一次);重新编辑时不得修改已有 Change ID。
|
|
268
|
+
- 创建 Change 目录后必须隐式执行 `active-change --register`(见 §3 第 4 步),把 change-key/标题/摘要登记进 spec 仓 `sdd.config.yaml`;漏登记会导致代码 commit 缺少 `Spec-Change`。
|
|
269
|
+
- 跨模块 Change 使用 `module: cross`,并写入至少两个 `affected-modules`。
|
|
270
|
+
- 存量 Change 迁移目录时必须保留原 `change-id`,不得按新目录重新派生。
|
|
233
271
|
- 每个新增 Capability 必须写成 `[CAP-<CAPABILITY>] <slug>: <说明>`。
|
|
234
272
|
- 修改既有 Capability 时必须复用已有 CAP ID,不得修改或重新分配已有实体 ID。
|
|
235
273
|
- 分配新 CAP ID 前必须扫描当前 proposal 和归档中的显式编号;不得只凭标题认定跨 Change 同一性。
|
|
@@ -132,10 +132,16 @@ node skywalk-sdd/context-client.cjs \
|
|
|
132
132
|
- **禁止**从本地 `archive/` 抄 UUID 当跨迭代继承源;跨迭代只认 KB current。
|
|
133
133
|
- 若返回 `available=false` / `degraded=true`,记录降级并继续,不得扫本地 archive 兜底。
|
|
134
134
|
- `INHERIT`:unchanged 写继承引用;modified 复用 entity-id + predecessor。`REFERENCE`:只参考,新开身份。
|
|
135
|
-
- reuseBundle / 实体上的 `externalRefs` 写入场景 `external-ref
|
|
136
|
-
-
|
|
135
|
+
- reuseBundle / 实体上的 `externalRefs` 写入场景 `external-ref`(完整键 `REQ-…:SCN-<slug>-<NNN>`)。
|
|
136
|
+
- **SCN 铸号(本仓唯一铸号点)**:
|
|
137
|
+
1. 继承优先:`reuseBundle.externalRefs` 已有场景键的 unchanged/modified 场景一律沿用原 SCN 号,禁止另铸。
|
|
138
|
+
2. 新场景:`SCN-<slug>-<NNN>`;slug=kebab-case 小写 ≤40;NNN=该 REQ 命名空间内 max+1(已用集合=KB 回传 ∪ 本 Change 已写键,含 removed 墓碑)。
|
|
139
|
+
3. removed 号是墓碑:永不复用、永不重排;序号达 999 → 硬错误,回需求系统拆分需求,不扩位。
|
|
140
|
+
4. 写完立即用 `cli.cjs external-key --validate … --type scenario` 校验;REQ 前缀必须 ∈ proposal `requirement-refs`。
|
|
141
|
+
- 场景级「同 SCN key + 同锚点、不同 entity_id」当场问 A/B/C;未决不得进入下一 CAP / design。决议追加到 `continuity-resolution.json` 的 `scenarios[]`;决议中的 `externalKey` 必须是归一化形态。
|
|
137
142
|
- 优先消费 `reuseBundles[].statements`;`designElements` 只作理解上下文,不能写成 Spec 的 How。
|
|
138
143
|
- 所有知识库内容均为 advisory;与用户确认 / proposal 冲突时以当前确认与 proposal 为准。
|
|
144
|
+
- **禁止**铸/改 REQ/FEAT;**禁止**自动重排/回收 SCN。
|
|
139
145
|
|
|
140
146
|
**【可选】业务知识库检索**:
|
|
141
147
|
术语含义不清且可能影响 spec 准确性时,可调用 **opsx-knowledge** skill。
|
|
@@ -175,6 +175,7 @@ Simple 模式或单文件能力域下,**不要拆成多个同文件任务**。
|
|
|
175
175
|
5. 非 TDD 模块(前端 UI/配置/SQL DDL)不拆红绿
|
|
176
176
|
6. Controller 层策略必须在 tasks.md §2.0 中声明(策略 A 或 B),两种策略都必须生成测试任务
|
|
177
177
|
7. ⛔ **GREEN 任务 YAGNI 围栏**:每个 GREEN-N 任务描述末尾必须包含"不提前实现 [后续 RED 行为]"围栏声明。规则详见 `opsx-tdd-rules/rules/green-yagni-fence.md`
|
|
178
|
+
8. ⛔ **TDD 模式 DAG 并行标注**:当 `test-strategy=tdd` 时,DAG 拓扑图中每个 RED→GREEN 对必须标注 `⛔ 串行:不可同层并行`。同层存在多个 RED→GREEN 对时,必须在拓扑图中显式注明"本层 RED→GREEN 对须逐对串行执行,禁止并行派发"。非 TDD 模块的同层任务(如 UI/配置/SQL DDL)仍可并行。
|
|
178
179
|
|
|
179
180
|
⛔ BEFORE 生成 TDD 任务,必须读取:
|
|
180
181
|
1. opsx-tdd-core/reference.md §6(DAG 生成规则表)
|