@harmonyos-arkts/d2h 0.1.26 → 0.1.27
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/.claude-plugin/plugin.json +1 -1
- package/agents/d2h.md +13 -14
- package/dist/bin/install-opencode.js +11 -2
- package/dist/src/install-tui-extension.js +133 -0
- package/dist/src/toolchain.js +2 -2
- package/package.json +1 -1
- package/skills/d2h-architecture-plan/SKILL.md +16 -7
- package/skills/d2h-architecture-plan/references/architecture-plan.example.json +357 -0
- package/skills/d2h-architecture-plan/references/directory-creation.md +11 -6
- package/skills/d2h-architecture-plan/references/json-contract.md +111 -0
- package/skills/d2h-architecture-plan/references/plan-contract.md +16 -14
- package/skills/d2h-architecture-plan/references/selection-flow.md +71 -0
- package/skills/d2h-architecture-plan/scripts/architecture_plan.py +281 -0
- package/skills/d2h-architecture-plan/scripts/test_architecture_plan.py +378 -0
- package/skills/d2h-dashboard/SKILL.md +12 -1
- package/skills/d2h-spec-develop/SKILL.md +51 -42
- package/skills/d2h-spec-generate/SKILL.md +30 -29
- package/skills/d2h-spec-plan/SKILL.md +20 -16
- package/skills/d2h-spec-plan/agents/openai.yaml +3 -3
- package/skills/d2h-spec-plan/references/plan-contract.md +32 -7
- package/skills/d2h-spec-plan/references/planning-method.md +12 -62
- package/skills/d2h-spec-plan/references/planning-review.md +9 -21
- package/skills/d2h-spec-plan/references/round-scope-assessment.md +12 -39
- package/skills/d2h-spec-plan/references/work-packets.md +6 -28
|
@@ -0,0 +1,357 @@
|
|
|
1
|
+
{
|
|
2
|
+
"planId": "c9c093cf-94ec-4b49-b919-a89c82eef0d1",
|
|
3
|
+
"project": {
|
|
4
|
+
"name": "NoteSample",
|
|
5
|
+
"summary": "协议示例：一个支持笔记列表、编辑和本地保存的 Android 应用，不代表已分析真实项目。"
|
|
6
|
+
},
|
|
7
|
+
"androidAnalysis": {
|
|
8
|
+
"summary": "单个应用模块承载笔记页面和存储访问，页面通过存储包装读写笔记。",
|
|
9
|
+
"techStack": {
|
|
10
|
+
"language": "Kotlin",
|
|
11
|
+
"ui": "Android 原生界面",
|
|
12
|
+
"storage": "本地保存笔记，具体存储方式未核验",
|
|
13
|
+
"network": "示例未提供联网功能信息"
|
|
14
|
+
},
|
|
15
|
+
"risks": [
|
|
16
|
+
{
|
|
17
|
+
"title": "本地存储需要适配",
|
|
18
|
+
"impact": "需核对鸿蒙存储实现，保证笔记保存与读取行为一致。"
|
|
19
|
+
}
|
|
20
|
+
]
|
|
21
|
+
},
|
|
22
|
+
"proposals": [
|
|
23
|
+
{
|
|
24
|
+
"id": "android-mirror",
|
|
25
|
+
"name": "原结构对照",
|
|
26
|
+
"summary": "保留源模块内的主要包族与 ui/store 层级，适配入口和资源；原开发者可按包族快速回溯；原 ui 包内的职责仍需后续实现时约束。",
|
|
27
|
+
"directoryTree": {
|
|
28
|
+
"name": "NoteSample-HarmonyOS",
|
|
29
|
+
"path": ".",
|
|
30
|
+
"description": "示例目标工程根；仅说明数据形状",
|
|
31
|
+
"children": [
|
|
32
|
+
{
|
|
33
|
+
"name": "AppScope",
|
|
34
|
+
"path": "AppScope",
|
|
35
|
+
"description": "按原工程职责保留的目录",
|
|
36
|
+
"children": [
|
|
37
|
+
{
|
|
38
|
+
"name": "resources",
|
|
39
|
+
"path": "AppScope/resources",
|
|
40
|
+
"description": "应用级资源，具体资源转换由后续阶段完成",
|
|
41
|
+
"children": []
|
|
42
|
+
}
|
|
43
|
+
]
|
|
44
|
+
},
|
|
45
|
+
{
|
|
46
|
+
"name": "entry",
|
|
47
|
+
"path": "entry",
|
|
48
|
+
"description": "本例唯一应用 HAP，负责装配与业务承载",
|
|
49
|
+
"kind": "HAP",
|
|
50
|
+
"children": [
|
|
51
|
+
{
|
|
52
|
+
"name": "src",
|
|
53
|
+
"path": "entry/src",
|
|
54
|
+
"description": "模块源码根",
|
|
55
|
+
"children": [
|
|
56
|
+
{
|
|
57
|
+
"name": "main",
|
|
58
|
+
"path": "entry/src/main",
|
|
59
|
+
"description": "主源集",
|
|
60
|
+
"children": [
|
|
61
|
+
{
|
|
62
|
+
"name": "ets",
|
|
63
|
+
"path": "entry/src/main/ets",
|
|
64
|
+
"description": "ArkTS 源码根",
|
|
65
|
+
"children": [
|
|
66
|
+
{
|
|
67
|
+
"name": "entryability",
|
|
68
|
+
"path": "entry/src/main/ets/entryability",
|
|
69
|
+
"description": "应用入口与依赖装配",
|
|
70
|
+
"children": []
|
|
71
|
+
},
|
|
72
|
+
{
|
|
73
|
+
"name": "com",
|
|
74
|
+
"path": "entry/src/main/ets/com",
|
|
75
|
+
"description": "原包层级",
|
|
76
|
+
"children": [
|
|
77
|
+
{
|
|
78
|
+
"name": "acme",
|
|
79
|
+
"path": "entry/src/main/ets/com/acme",
|
|
80
|
+
"description": "原组织包层级",
|
|
81
|
+
"children": [
|
|
82
|
+
{
|
|
83
|
+
"name": "notes",
|
|
84
|
+
"path": "entry/src/main/ets/com/acme/notes",
|
|
85
|
+
"description": "笔记职责目录",
|
|
86
|
+
"children": [
|
|
87
|
+
{
|
|
88
|
+
"name": "ui",
|
|
89
|
+
"path": "entry/src/main/ets/com/acme/notes/ui",
|
|
90
|
+
"description": "笔记列表与编辑页面，保留原 ui 包族",
|
|
91
|
+
"children": []
|
|
92
|
+
},
|
|
93
|
+
{
|
|
94
|
+
"name": "store",
|
|
95
|
+
"path": "entry/src/main/ets/com/acme/notes/store",
|
|
96
|
+
"description": "本地存储包装，保留原 store 包族；唯一存储包装所有者；实例由应用装配提供，业务状态不复制到基础层",
|
|
97
|
+
"children": []
|
|
98
|
+
}
|
|
99
|
+
]
|
|
100
|
+
}
|
|
101
|
+
]
|
|
102
|
+
}
|
|
103
|
+
]
|
|
104
|
+
}
|
|
105
|
+
]
|
|
106
|
+
},
|
|
107
|
+
{
|
|
108
|
+
"name": "resources",
|
|
109
|
+
"path": "entry/src/main/resources",
|
|
110
|
+
"description": "本 HAP 的页面文案及其他资源，由模块统一管理",
|
|
111
|
+
"children": []
|
|
112
|
+
}
|
|
113
|
+
]
|
|
114
|
+
}
|
|
115
|
+
]
|
|
116
|
+
}
|
|
117
|
+
]
|
|
118
|
+
}
|
|
119
|
+
]
|
|
120
|
+
}
|
|
121
|
+
},
|
|
122
|
+
{
|
|
123
|
+
"id": "harmony-practice",
|
|
124
|
+
"name": "鸿蒙优选",
|
|
125
|
+
"summary": "按业务 feature 与基础存储职责重组，仍使用一个 HAP；页面与展示状态边界清晰；需重新定位原包族，调整引用和装配。",
|
|
126
|
+
"directoryTree": {
|
|
127
|
+
"name": "NoteSample-HarmonyOS",
|
|
128
|
+
"path": ".",
|
|
129
|
+
"description": "示例目标工程根；仅说明数据形状",
|
|
130
|
+
"children": [
|
|
131
|
+
{
|
|
132
|
+
"name": "AppScope",
|
|
133
|
+
"path": "AppScope",
|
|
134
|
+
"description": "按原工程职责保留的目录",
|
|
135
|
+
"children": [
|
|
136
|
+
{
|
|
137
|
+
"name": "resources",
|
|
138
|
+
"path": "AppScope/resources",
|
|
139
|
+
"description": "应用级资源，具体资源转换由后续阶段完成",
|
|
140
|
+
"children": []
|
|
141
|
+
}
|
|
142
|
+
]
|
|
143
|
+
},
|
|
144
|
+
{
|
|
145
|
+
"name": "entry",
|
|
146
|
+
"path": "entry",
|
|
147
|
+
"description": "本例唯一应用 HAP，负责装配与业务承载",
|
|
148
|
+
"kind": "HAP",
|
|
149
|
+
"children": [
|
|
150
|
+
{
|
|
151
|
+
"name": "src",
|
|
152
|
+
"path": "entry/src",
|
|
153
|
+
"description": "模块源码根",
|
|
154
|
+
"children": [
|
|
155
|
+
{
|
|
156
|
+
"name": "main",
|
|
157
|
+
"path": "entry/src/main",
|
|
158
|
+
"description": "主源集",
|
|
159
|
+
"children": [
|
|
160
|
+
{
|
|
161
|
+
"name": "ets",
|
|
162
|
+
"path": "entry/src/main/ets",
|
|
163
|
+
"description": "ArkTS 源码根",
|
|
164
|
+
"children": [
|
|
165
|
+
{
|
|
166
|
+
"name": "entryability",
|
|
167
|
+
"path": "entry/src/main/ets/entryability",
|
|
168
|
+
"description": "应用入口与依赖装配",
|
|
169
|
+
"children": []
|
|
170
|
+
},
|
|
171
|
+
{
|
|
172
|
+
"name": "features",
|
|
173
|
+
"path": "entry/src/main/ets/features",
|
|
174
|
+
"description": "按原工程职责保留的目录",
|
|
175
|
+
"children": [
|
|
176
|
+
{
|
|
177
|
+
"name": "notes",
|
|
178
|
+
"path": "entry/src/main/ets/features/notes",
|
|
179
|
+
"description": "笔记业务所有者",
|
|
180
|
+
"children": [
|
|
181
|
+
{
|
|
182
|
+
"name": "pages",
|
|
183
|
+
"path": "entry/src/main/ets/features/notes/pages",
|
|
184
|
+
"description": "笔记列表及编辑页面",
|
|
185
|
+
"children": []
|
|
186
|
+
},
|
|
187
|
+
{
|
|
188
|
+
"name": "viewmodel",
|
|
189
|
+
"path": "entry/src/main/ets/features/notes/viewmodel",
|
|
190
|
+
"description": "笔记展示状态与交互编排",
|
|
191
|
+
"children": []
|
|
192
|
+
}
|
|
193
|
+
]
|
|
194
|
+
}
|
|
195
|
+
]
|
|
196
|
+
},
|
|
197
|
+
{
|
|
198
|
+
"name": "core",
|
|
199
|
+
"path": "entry/src/main/ets/core",
|
|
200
|
+
"description": "按原工程职责保留的目录",
|
|
201
|
+
"children": [
|
|
202
|
+
{
|
|
203
|
+
"name": "storage",
|
|
204
|
+
"path": "entry/src/main/ets/core/storage",
|
|
205
|
+
"description": "平台持久化适配；唯一存储包装所有者；实例由应用装配提供，业务状态不复制到基础层",
|
|
206
|
+
"children": []
|
|
207
|
+
}
|
|
208
|
+
]
|
|
209
|
+
}
|
|
210
|
+
]
|
|
211
|
+
},
|
|
212
|
+
{
|
|
213
|
+
"name": "resources",
|
|
214
|
+
"path": "entry/src/main/resources",
|
|
215
|
+
"description": "本 HAP 的页面文案及其他资源，由模块统一管理",
|
|
216
|
+
"children": []
|
|
217
|
+
}
|
|
218
|
+
]
|
|
219
|
+
}
|
|
220
|
+
]
|
|
221
|
+
}
|
|
222
|
+
]
|
|
223
|
+
}
|
|
224
|
+
]
|
|
225
|
+
}
|
|
226
|
+
},
|
|
227
|
+
{
|
|
228
|
+
"id": "hybrid",
|
|
229
|
+
"name": "融合",
|
|
230
|
+
"summary": "业务按 feature 组织，基础 store 保留原包族；不额外拆构建模块；原基础包族可追溯，页面有明确业务归属；需维护原包族与新 feature 的映射。",
|
|
231
|
+
"directoryTree": {
|
|
232
|
+
"name": "NoteSample-HarmonyOS",
|
|
233
|
+
"path": ".",
|
|
234
|
+
"description": "示例目标工程根；仅说明数据形状",
|
|
235
|
+
"children": [
|
|
236
|
+
{
|
|
237
|
+
"name": "AppScope",
|
|
238
|
+
"path": "AppScope",
|
|
239
|
+
"description": "按原工程职责保留的目录",
|
|
240
|
+
"children": [
|
|
241
|
+
{
|
|
242
|
+
"name": "resources",
|
|
243
|
+
"path": "AppScope/resources",
|
|
244
|
+
"description": "应用级资源，具体资源转换由后续阶段完成",
|
|
245
|
+
"children": []
|
|
246
|
+
}
|
|
247
|
+
]
|
|
248
|
+
},
|
|
249
|
+
{
|
|
250
|
+
"name": "entry",
|
|
251
|
+
"path": "entry",
|
|
252
|
+
"description": "本例唯一应用 HAP，负责装配与业务承载",
|
|
253
|
+
"kind": "HAP",
|
|
254
|
+
"children": [
|
|
255
|
+
{
|
|
256
|
+
"name": "src",
|
|
257
|
+
"path": "entry/src",
|
|
258
|
+
"description": "模块源码根",
|
|
259
|
+
"children": [
|
|
260
|
+
{
|
|
261
|
+
"name": "main",
|
|
262
|
+
"path": "entry/src/main",
|
|
263
|
+
"description": "主源集",
|
|
264
|
+
"children": [
|
|
265
|
+
{
|
|
266
|
+
"name": "ets",
|
|
267
|
+
"path": "entry/src/main/ets",
|
|
268
|
+
"description": "ArkTS 源码根",
|
|
269
|
+
"children": [
|
|
270
|
+
{
|
|
271
|
+
"name": "entryability",
|
|
272
|
+
"path": "entry/src/main/ets/entryability",
|
|
273
|
+
"description": "应用入口与依赖装配",
|
|
274
|
+
"children": []
|
|
275
|
+
},
|
|
276
|
+
{
|
|
277
|
+
"name": "features",
|
|
278
|
+
"path": "entry/src/main/ets/features",
|
|
279
|
+
"description": "按原工程职责保留的目录",
|
|
280
|
+
"children": [
|
|
281
|
+
{
|
|
282
|
+
"name": "notes",
|
|
283
|
+
"path": "entry/src/main/ets/features/notes",
|
|
284
|
+
"description": "笔记业务与页面组候选",
|
|
285
|
+
"children": [
|
|
286
|
+
{
|
|
287
|
+
"name": "pages",
|
|
288
|
+
"path": "entry/src/main/ets/features/notes/pages",
|
|
289
|
+
"description": "笔记列表与编辑页面",
|
|
290
|
+
"children": []
|
|
291
|
+
},
|
|
292
|
+
{
|
|
293
|
+
"name": "viewmodel",
|
|
294
|
+
"path": "entry/src/main/ets/features/notes/viewmodel",
|
|
295
|
+
"description": "笔记展示状态及交互编排",
|
|
296
|
+
"children": []
|
|
297
|
+
}
|
|
298
|
+
]
|
|
299
|
+
}
|
|
300
|
+
]
|
|
301
|
+
},
|
|
302
|
+
{
|
|
303
|
+
"name": "foundation",
|
|
304
|
+
"path": "entry/src/main/ets/foundation",
|
|
305
|
+
"description": "按原工程职责保留的目录",
|
|
306
|
+
"children": [
|
|
307
|
+
{
|
|
308
|
+
"name": "com",
|
|
309
|
+
"path": "entry/src/main/ets/foundation/com",
|
|
310
|
+
"description": "原包层级",
|
|
311
|
+
"children": [
|
|
312
|
+
{
|
|
313
|
+
"name": "acme",
|
|
314
|
+
"path": "entry/src/main/ets/foundation/com/acme",
|
|
315
|
+
"description": "原组织包层级",
|
|
316
|
+
"children": [
|
|
317
|
+
{
|
|
318
|
+
"name": "notes",
|
|
319
|
+
"path": "entry/src/main/ets/foundation/com/acme/notes",
|
|
320
|
+
"description": "笔记职责目录",
|
|
321
|
+
"children": [
|
|
322
|
+
{
|
|
323
|
+
"name": "store",
|
|
324
|
+
"path": "entry/src/main/ets/foundation/com/acme/notes/store",
|
|
325
|
+
"description": "保留原 store 包族，目标平台适配在实现阶段细化；唯一存储包装所有者；实例由应用装配提供，业务状态不复制到基础层",
|
|
326
|
+
"children": []
|
|
327
|
+
}
|
|
328
|
+
]
|
|
329
|
+
}
|
|
330
|
+
]
|
|
331
|
+
}
|
|
332
|
+
]
|
|
333
|
+
}
|
|
334
|
+
]
|
|
335
|
+
}
|
|
336
|
+
]
|
|
337
|
+
},
|
|
338
|
+
{
|
|
339
|
+
"name": "resources",
|
|
340
|
+
"path": "entry/src/main/resources",
|
|
341
|
+
"description": "本 HAP 的页面文案及其他资源，由模块统一管理",
|
|
342
|
+
"children": []
|
|
343
|
+
}
|
|
344
|
+
]
|
|
345
|
+
}
|
|
346
|
+
]
|
|
347
|
+
}
|
|
348
|
+
]
|
|
349
|
+
}
|
|
350
|
+
]
|
|
351
|
+
}
|
|
352
|
+
}
|
|
353
|
+
],
|
|
354
|
+
"recommendedProposalId": "hybrid",
|
|
355
|
+
"recommendationReason": "示例中既有清晰基础包族，又需要页面业务边界，融合便于回溯与维护；若原包族职责混杂，应重新评估鸿蒙优选。",
|
|
356
|
+
"selectedProposalId": null
|
|
357
|
+
}
|
|
@@ -1,11 +1,15 @@
|
|
|
1
1
|
# 用户确认后的目录落地
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
仅在用户要求落地/搬迁且已确认当前方案时读取。看板“确定”、question 工具回答及明确对话授权都按 [selection-flow.md](selection-flow.md) 先落盘，再由本步骤读取；`select-and-create` 满足创建条件，不追加“是否继续”的询问。本阶段优先复用基础工程，用普通文件工具补齐关键目录；确实无基础工程时才使用本机 DevEco CLI 创建。不实现业务、不构建或运行应用。
|
|
4
4
|
|
|
5
5
|
## 1. 固定实际选择与目标
|
|
6
6
|
|
|
7
|
-
-
|
|
7
|
+
- 运行 `python <本Skill目录>/scripts/architecture_plan.py read-selection <产物目录>/architecture-plan.json`，重新读取磁盘上的规划和同目录 `architecture-selection.json`。两文件的规划身份、选中方案必须一致，动作必须为 `select-and-create` 才创建；`select` 只交接已选型结果。记录来源可以是 dashboard/question/conversation，后续步骤一致。
|
|
8
|
+
- 从刚读取的规划 `proposals` 中按 `selectedProposalId` 获取目录树，确认文件提供请求 ID、来源、意见和创建要求。不从问题工具返回值、内存变量、旧消息或推荐方案直接推导实施目录。确认缺失、不一致或写入未完成时先恢复统一落盘步骤，不能绕过读取检查。
|
|
9
|
+
- 检查读取摘要保留的 `notes`：未处理的布局修改先回到对话修订，不能因为脚本返回创建动作就忽略用户意见；脚本只核验数据一致性，不解释自然语言或判断目标能力。
|
|
10
|
+
- 恢复/重复回传时先读取现有 `shell-receipt.json` 和实际工程。相同请求已完成则核对后返回已有结果；partial/blocked 时核对实际状态，仅继续尚缺且仍获授权的动作。选择记录存在不代表创建已完成，不重复初始化或搬迁。不同方案已有落地时先比较实际冲突，不静默清空旧目录或迁移已有业务。
|
|
8
11
|
- 完整迁移核对调用方交接的目标根、`.migration/config.json` 的 `harmonyProject` 与 Preflight 已建工程位置，沿用同一个实际目标根。方案内的 `products/features/commons` 布局变化不另起工程；目标指向冲突时先查明，不能静默换路径再建一套。用户明确要求更换目标时，交由调用方通过现有 CLI 配置入口同步。
|
|
12
|
+
- 精简 JSON 不重复保存工程绝对路径。创建前结合配置、Preflight、规划 Markdown 与明确用户上下文核对本次规划所属 Android 工程及实际目标根；独立调用缺少目标时只询问该位置。目标变更按统一流程清理当前确认并刷新展示，不将原位置的确认用于新位置；脚本返回创建指令不代表它已核验实际目标。
|
|
9
13
|
- 从选中方案推导目录清单，核对路径位于目标根内，无绝对子路径、上级跳转、大小写冲突或模块嵌套。不得跟随链接写入源/参考工程或目标根之外。
|
|
10
14
|
- 先检查目标实际状态和已有工程；保留用户文件。新增目录通常可直接执行；重用、移动或覆盖存在冲突的内容先查清，未授权覆盖则停止该动作并说明具体冲突。
|
|
11
15
|
- 目标设备/SDK与方案一致；未知设备能力不以默认phone掩盖，也不把所有Android设备名直接写入鸿蒙配置。
|
|
@@ -26,9 +30,9 @@
|
|
|
26
30
|
|
|
27
31
|
只创建选中方案的实际模块/关键子目录。模板之外不生成业务文件、空实现、额外模块配置或提前注册所有HAR/HSP；这些目录须明确标注为待下游配置的目录壳子。
|
|
28
32
|
|
|
29
|
-
|
|
33
|
+
从 `proposals` 中取与 `selectedProposalId` 一致的 `directoryTree`，使用其中相对路径落地（根节点 `.` 表示目标根）。三套树已在选型前展开，不在创建时静默增加未展示的关键目录或改用推荐方案。若发现归属冲突或影响实际布局的待决，局部修订、刷新看板并按实际授权确认后再创建受影响目录，不为创建壳子重做业务分析。
|
|
30
34
|
|
|
31
|
-
|
|
35
|
+
选中融合方案时从已确认目录树创建基础包族与页面 feature 目录，必要时结合 Markdown 的归属说明，不要求 JSON 映射集合。保留逻辑目录和实际模块的区别；单 HAP 的 feature 目录落在实际源码根内，资源服从所属模块规则，不套用独立库的 `src/main`。共享契约和集成所有权随规划交接，不以生成接口桩或复制共享状态充当完成前置。
|
|
32
36
|
|
|
33
37
|
命令成功后检查目标根基础配置、注册产品路径及关键目录确实存在，设备配置与选择一致，已有文件没有被覆盖；若执行中用户修改规划，先核对影响，不能按旧目录继续宣称完整。
|
|
34
38
|
|
|
@@ -39,8 +43,9 @@
|
|
|
39
43
|
在规划产物目录写 `shell-receipt.json`，记录可核验的实际落地结果，复用基础工程并补目录同样需要记录：
|
|
40
44
|
|
|
41
45
|
- `status`：complete / partial / blocked，按真实落地结果填写。
|
|
42
|
-
- `planFile`、`proposalId`、`target
|
|
43
|
-
- `
|
|
46
|
+
- `planFile`、`proposalId`、`target`：当前 `architecture-plan.json`、选中方案和实际目标根；可用 `planViewFile` 附 Markdown 路径。
|
|
47
|
+
- `planId`、`selectionRequestId`：本次执行绑定的规划身份和请求 ID，供恢复核对；旧 receipt 缺少这些字段时结合原授权与实际文件查证，不伪造历史记录。
|
|
48
|
+
- `confirmationFile`、`confirmation`：本次实际读取的 `architecture-selection.json` 路径及用户选择/推荐委托、动作、来源与对应修订，未确认不得执行落地。receipt 保存实际执行依据，主规划不嵌套第二份确认对象。
|
|
44
49
|
- `baseProject`：新建或复用、工程来源与辨别依据、实际注册产品路径、设备类型及本阶段实际使用的 CLI/命令/日志位置。Preflight 已建工程记为复用；引用先前创建证据时注明来源，不冒充本阶段执行。
|
|
45
50
|
- `createdDirectories`、`existingDirectories`、`directoryOnlyModules`：分别记录新增、已存在和未注册的模块目录。
|
|
46
51
|
- `verification`、`remainingIssues`：实际检查结果、路径/配置差异和未完成项，不编造日志或检查。
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
# 看板规划与选择回传契约
|
|
2
|
+
|
|
3
|
+
生成规划和接收选择时读取本文件。完整可解析示例见 [architecture-plan.example.json](architecture-plan.example.json)；它只演示小型单 HAP 的形状，不能代替当前工程分析。
|
|
4
|
+
|
|
5
|
+
辅助脚本要求 Python 3.10+，只使用标准库。命令中的路径替换为实际绝对路径，路径含空格时按当前 shell 加引号。
|
|
6
|
+
|
|
7
|
+
## 三部分展示内容
|
|
8
|
+
|
|
9
|
+
产物目录沿用 `<Android工程同级>/<工程名>-migration/.migration/architecture-plan/`。`architecture-plan.json` 是决策事实源，`architecture-plan.md` 是同步阅读视图；`architecture-selection.json` 保存看板或 question 工具得到的实际确认结果，作为目录实施的输入。JSON 使用 UTF-8，不能包含注释、代码围栏或省略号。
|
|
10
|
+
|
|
11
|
+
JSON 的展示内容只围绕项目简介、原工程分析与风险、三套方案目录组织：
|
|
12
|
+
|
|
13
|
+
| 对象 | 必填字段 | 可选字段 |
|
|
14
|
+
|---|---|---|
|
|
15
|
+
| `project` | `name`（项目名）、`summary`（用途、主要能力；部分迁移时说明本次范围） | 无 |
|
|
16
|
+
| `androidAnalysis` | `summary`（架构概述）、`techStack`（四类技术概况对象）、`risks`（关键迁移风险数组） | 无 |
|
|
17
|
+
| `androidAnalysis.techStack` | `language`（开发语言）、`ui`（界面实现）、`storage`（数据存储）、`network`（网络通信），均为简短字符串 | 无 |
|
|
18
|
+
| `androidAnalysis.risks[]` | `title`（风险名称）、`impact`（对迁移的影响），均为简短字符串 | 无 |
|
|
19
|
+
| `proposals[]` | `id`、`name`、`summary`（目录组织思路、主要取舍或限制）、`directoryTree`（嵌套目录树） | 无 |
|
|
20
|
+
| 目录节点 | `name`、`path`、`description`（路径简介）、`children` | `kind`（模块类型；普通目录省略） |
|
|
21
|
+
|
|
22
|
+
`proposals` 恰好三套，ID 分别为 `android-mirror`、`harmony-practice`、`hybrid`，每套均有自己的完整关键目录树。同构方案允许树相同，不制造无依据差异。
|
|
23
|
+
|
|
24
|
+
`androidAnalysis` 固定使用上述字段，不增加可选分析集合。写作要求：
|
|
25
|
+
|
|
26
|
+
- `summary` 用一到两句日常语言解释“代码如何组织、哪里明显影响迁移”，不重复项目用途，不罗列模块名、类名或阅读过程。
|
|
27
|
+
- `techStack` 每类只写一条简短说明，只保留最能说明实现方式的信息。例如语言写“Kotlin、Java”，界面写“新页面使用 Compose，旧页面仍用 Android View”。不堆叠构建工具、架构缩写、库清单或把同一技术分散列多次；确知无相关能力时说明“无本地存储”等事实，未核实则写“本次未核验”，不猜技术名称。
|
|
28
|
+
- `risks` 最多五项，按对迁移的影响合并同类问题。`title` 直接命名问题，`impact` 用一句话说明可能影响的功能或需要适配的部分，不展开源码论证、接口设计或长篇处置清单。没有已知风险时使用 `[]`，不能据此宣称已完成验证。
|
|
29
|
+
- 移除源码目录清单 `structure` 和未决清单 `openQuestions`。影响迁移的技术未知并入相应风险的 `impact`；源码路径、证据、详细依赖和其他核验记录按需留在 Markdown，不塞入展示摘要。
|
|
30
|
+
|
|
31
|
+
风险及其中尚待核验的事项均为只读展示内容。看板不为它们生成必答表单、确认按钮或风险已读勾选，不将非空数组视为选型/创建的阻塞条件。技术问题由 Agent 后续按需核查，用户不需要逐项处理。
|
|
32
|
+
|
|
33
|
+
用户若希望改变分析或方案，通过对话提出意见，Agent 修改相应 JSON 字段并同步 Markdown。仅调整分析或风险说明时不清空有效选择；影响目录或实际授权范围时更新展示并按选型流程处理。实际创建缺少目标位置等必要输入时，独立询问该缺失信息，不把整份风险或未决清单交给用户作答。
|
|
34
|
+
|
|
35
|
+
JSON 不再包含 `regions`、映射表、依赖图、共享所有者及逐方案收益/成本/风险数组。影响选型的方案取舍写入方案 `summary`，具体职责写入目录 `description`；必要的源到目标归属、依赖方向和共享边界由 Markdown 简记，不生成三份实现交接模型。
|
|
36
|
+
|
|
37
|
+
Android/目标绝对路径、目标工程性质和结合范围属于执行上下文，沿用迁移配置、Preflight 与明确用户指令；按需记入现有 Markdown，不在看板 JSON 重复管理。
|
|
38
|
+
|
|
39
|
+
## 推荐、选择与协议字段
|
|
40
|
+
|
|
41
|
+
以下顶层字段全部保留，用于选型展示和回传校验，不要求看板把协议元数据作为分析内容展示：
|
|
42
|
+
|
|
43
|
+
| 字段 | 类型与含义 |
|
|
44
|
+
|---|---|
|
|
45
|
+
| `planId` | 同一工程本次规划的稳定唯一标识，首次生成 UUID，修订沿用；不同工程不共用 |
|
|
46
|
+
| `recommendedProposalId` | 模型推荐的一个方案 ID，不能作为用户授权 |
|
|
47
|
+
| `recommendationReason` | 当前证据下的推荐理由及会改变推荐的条件 |
|
|
48
|
+
| `selectedProposalId` | 用户最终选中的整套目录方案 ID；未选择为 `null`，不能预填推荐值 |
|
|
49
|
+
|
|
50
|
+
## 嵌套目录节点
|
|
51
|
+
|
|
52
|
+
`directoryTree` 是一个根节点，节点字段固定如下：
|
|
53
|
+
|
|
54
|
+
```json
|
|
55
|
+
{
|
|
56
|
+
"name": "HarmonyOS",
|
|
57
|
+
"path": ".",
|
|
58
|
+
"description": "目标工程根目录；以下子节点均相对此根",
|
|
59
|
+
"children": [
|
|
60
|
+
{
|
|
61
|
+
"name": "entry",
|
|
62
|
+
"path": "entry",
|
|
63
|
+
"description": "应用 HAP，负责启动、装配及本例业务",
|
|
64
|
+
"kind": "HAP",
|
|
65
|
+
"children": []
|
|
66
|
+
}
|
|
67
|
+
]
|
|
68
|
+
}
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
上例仅解释节点形状；实际规划须展开源码根、主要 feature/包族及资源目录，不能只交付空 `entry`。规则：
|
|
72
|
+
|
|
73
|
+
- 根 `path` 固定为 `.`，其余 `name` 是一个目录段，与 `path` 最后一级一致。
|
|
74
|
+
- `path` 是目标根相对路径，统一 `/`，不以 `/` 结尾；每个子节点是父目录的直接下一层。例如 `entry` → `entry/src` → `entry/src/main`，不能跳级或把 `src/main` 当节点名。
|
|
75
|
+
- 节点必须有非空简介和 `children` 数组，叶子为 `[]`。看板以 `proposal.id + ':' + node.path` 为节点键，以 `children.length` 判断展开/折叠；折叠状态由界面维护，不写回规划。
|
|
76
|
+
- `kind` 省略时表示普通 `directory`；实际拟议构建模块根须标 `HAP`、`HAR` 或 `HSP`，不标其 `src/main` 或普通 feature。根节点只能是普通目录，模块不能嵌套；目录存在不等于已注册模块。
|
|
77
|
+
- 每套应用方案至少包含一个 HAP，并展开该 HAP 的 `src/main/ets` 源码根；空树或只标记一个空 HAP 不算可落地目录规划。
|
|
78
|
+
- 不出现绝对子路径、反斜杠、空路径段、`.`/`..` 段（根除外）、Windows 非法目录名、大小写重名、通配符或目录模式占位符。相同路径可出现在不同方案内。
|
|
79
|
+
- 三套方案无需列逐类目录和全量文件，但拟创建的关键目录必须逐节点可见。创建前仍需核对实际目标、链接和用户文件；静态路径校验不替代实际文件系统检查。
|
|
80
|
+
|
|
81
|
+
## 统一确认记录与下一步读取
|
|
82
|
+
|
|
83
|
+
选型、确认落盘和目录实施的统一流程见 [selection-flow.md](selection-flow.md)，两个入口都必须遵守。主规划只用 `selectedProposalId` 展示当前选择，不嵌套完整回传对象；确认细节单独保存在同目录的 `architecture-selection.json`。
|
|
84
|
+
|
|
85
|
+
在已说明“确定后创建或复用基础工程并补齐目录”的交互中，看板“确定”与 OpenCode question 回答都生成同一种记录：
|
|
86
|
+
|
|
87
|
+
```json
|
|
88
|
+
{
|
|
89
|
+
"requestId": "97c333d3-9e02-43d2-8c27-e8202789e02c",
|
|
90
|
+
"planId": "c9c093cf-94ec-4b49-b919-a89c82eef0d1",
|
|
91
|
+
"selectedProposalId": "hybrid",
|
|
92
|
+
"action": "select-and-create",
|
|
93
|
+
"source": "question",
|
|
94
|
+
"notes": ""
|
|
95
|
+
}
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
| 字段 | 规则 |
|
|
99
|
+
|---|---|
|
|
100
|
+
| `requestId` | 每次用户确认生成唯一值，重试沿用原值和内容 |
|
|
101
|
+
| `planId` | 用户正在查看的规划身份，必须匹配主规划 |
|
|
102
|
+
| `selectedProposalId` | 用户实际选择的整套方案 ID，必须在三套方案中 |
|
|
103
|
+
| `action` | `select-and-create` 表示确认并创建；用户只要求记录选择时为 `select` |
|
|
104
|
+
| `source` | 看板为 `dashboard`；OpenCode question 工具为 `question`；已有明确对话指令为 `conversation` |
|
|
105
|
+
| `notes` | 真实修改意见，可为空；要求改变目录时先处理修改，不能按旧目录执行 |
|
|
106
|
+
|
|
107
|
+
以上字段全部必填；记录不接受自带目录、目标根或推荐值。source 是来源记录，不是身份认证，Agent 必须基于实际用户操作/回答，不能自行伪造选择。仅分析文本调整保留有效确认，目录或实际授权范围变化则按统一流程清理原确认。
|
|
108
|
+
|
|
109
|
+
`apply-selection` 从独立请求文件读取用户提交，校验后才保存确认文件、更新主规划的选择字段；看板和文件工具不得用新请求直接覆盖已确认文件。目录实施入口执行 `read-selection`，重新核对两文件的 planId/方案 ID、动作及原始意见，再读取规划内该方案的目录树；不能仅凭 question 返回值或看板选中效果开始创建。写入失败或读取不一致时不进入实施。记录先写、规划后写，不是跨文件原子事务；显式恢复和重复提交规则见统一流程。
|
|
110
|
+
|
|
111
|
+
实际目标根仍由迁移配置、Preflight 和明确上下文核对，不由回传提供。看板服务和会话通知由外部适配方提供，本 Skill 不提供 HTTP 端点或监听服务。风险仅作展示，不增加确认表单。
|
|
@@ -1,28 +1,28 @@
|
|
|
1
1
|
# 规划交付：目录、归属与决策
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
默认交付 `architecture-plan.json` 和 `architecture-plan.md`。前者是看板决策事实源，字段与回传遵循 [json-contract.md](json-contract.md)；后者是从同一规划同步的阅读视图，供现有调用方交接，保留已有用户批注。目标是让开发者能在看板判断采用哪套结构，并据此创建目录。
|
|
4
4
|
|
|
5
5
|
## 1. 共用一次项目理解
|
|
6
6
|
|
|
7
7
|
简述应用用途、原结构、目标范围及实际读取范围。已定位鸿蒙目标时，简记实际目标根、模板壳/已有业务/性质未明的判断及证据；模板壳仅作为落地基础。已有明确的结合/不结合鸿蒙业务实现选择一并简记，后续同范围修订沿用；未答复只记默认 Android，不记为拒绝。基础工程可复用与业务能力已实现分开表述，未读取的目标业务不作为已核验的能力复用依据。
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
JSON 的 `project` 只保存项目名和简介；部分迁移时在简介中注明本次范围。`androidAnalysis` 固定为架构概述 `summary`、四类技术概况 `techStack`、最多五项的迁移风险 `risks`，具体类型与写法见 JSON 契约。概述只解释组织方式和主要耦合，技术按语言/界面/存储/网络各一句说明，风险只写名称与迁移影响。资源、配置、后台/外部入口和 Native/混合栈边界只保留影响迁移的结论，不在 JSON 罗列源码目录、类名、工具库清单或独立未决项。工程路径、目标性质、是否结合业务实现及源码/依赖核验细节按需记入本 Markdown，配置已有值直接引用，不重复维护。
|
|
10
10
|
|
|
11
|
-
## 2.
|
|
11
|
+
## 2. 三套嵌套目录与归属
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
共用上述源范围，在 `proposals` 提供 `android-mirror`、`harmony-practice`、`hybrid` 三套结构选项。每套 JSON 只有 `id/name/summary/directoryTree`，便于看板独立展开与比较；用户已有选择时沿用，不重新选型。信息组织如下：
|
|
14
14
|
|
|
15
|
-
- **关键目录树**：展开全部拟议实际模块及主要职责/feature
|
|
16
|
-
-
|
|
17
|
-
-
|
|
15
|
+
- **关键目录树**：展开全部拟议实际模块及主要职责/feature 目录。基础保留方案体现原模块/关键包族的相对层级；业务方案体现页面/页面组及共享区域。每个节点包含 `name/path/description/children`，实际模块根用 `kind` 标注 HAP/HAR/HSP，普通目录省略；叶子也给 `children: []`。关键目录逐项嵌套列出，不能使用 `{pages,state}`、`<业务>`、省略号或“同推荐方案”等占位；无需列逐类目录或全量文件。
|
|
16
|
+
- **方案说明**：在 `summary` 简述目录组织思路及影响选型的取舍/限制，具体职责放在对应目录的 `description`。不为每套生成收益/成本/风险数组或实现交接模型。
|
|
17
|
+
- **必要交接**：源到目标归属、主要依赖方向与共享所有权只在 Markdown 按需简记，优先围绕推荐/已选方案，不维护三套完整关系图；保留的源边与目标新增/替代边区分，目录不等于独立构建模块。
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
用目录简介及必要的 Markdown 归属说明核对已知职责有去向。混合区域说明保留与移出部分，共享能力有唯一所有者，不让同一粗目录被整体认领多次。不要求机器映射表、职责 ID 或相同粒度的多份交接表。
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
Markdown 可详列推荐/已选方案，另两套保留紧凑对照并链接 JSON；该展示压缩不改变 JSON 中三套树的完整性。同构方案允许树相同，不制造无依据差异。选择另一套后直接使用其树，除非边界出现新问题，不重新扫描源码。
|
|
22
22
|
|
|
23
23
|
## 3. 融合方案的最小交接
|
|
24
24
|
|
|
25
|
-
融合方案采用 [hybrid-design.md](hybrid-design.md)
|
|
25
|
+
融合方案采用 [hybrid-design.md](hybrid-design.md) 的两层原则。目录简介反映职责边界，以下必要交接在 Markdown 中按需简记，足以支持后续细化，不新增 JSON 关系集合或逐页实施计划：
|
|
26
26
|
|
|
27
27
|
| 内容 | 本阶段粒度 |
|
|
28
28
|
|---|---|
|
|
@@ -37,16 +37,18 @@
|
|
|
37
37
|
|
|
38
38
|
比较三套的维护定位、边界清晰度、平台适配与迁移成本，给基于当前证据的推荐及会改变推荐的条件。模块数量、目录命名和“最佳实践”标签不能替代论证；同构方案不为制造差异而拆库。
|
|
39
39
|
|
|
40
|
-
|
|
40
|
+
交付前对照共用范围与目录职责检查：
|
|
41
41
|
|
|
42
42
|
- 已知运行时模块、主要职责与资源/非 UI 入口都有去向；未排除用户业务，三套范围一致。
|
|
43
|
-
-
|
|
43
|
+
- 树、必要归属说明、模块类型及主要依赖互相吻合，原包族保留承诺可定位，共享所有权唯一，无未解释的目标环或反向页面依赖。
|
|
44
44
|
- 方案不夹带未验证的平台替代/进程合并/功能裁剪结论；目录待决与实现前置分开，未读取鸿蒙源码时没有伪称目标已实现。
|
|
45
45
|
- 空模板的目录、模块数量和默认参数未被当成架构约束；已建基础工程的复用安排与所选目录一致，必须调整的配置或路径假设有交接说明。
|
|
46
46
|
- 融合分层与页面候选有证据，已知共同写入点有归属；没有将未细化的契约或目录壳子记为已可开工。
|
|
47
47
|
|
|
48
48
|
有矛盾时局部修订并补查相关证据，不重跑全仓分析。架构选择可以在保留实现风险的情况下完成；未知仍影响具体目录时明确条件分支或草案范围。
|
|
49
49
|
|
|
50
|
-
|
|
50
|
+
风险和未决项以分析结论展示，不要求用户回答或确认，不构成默认暂停条件。Agent 可继续相关技术核查；用户主动通过对话提出调整时，再更新 JSON 和同步阅读视图。仅说明文字的修改保留有效选择，涉及目录或授权范围的变化按选型流程处理。
|
|
51
51
|
|
|
52
|
-
|
|
52
|
+
按 [json-contract.md](json-contract.md) 校验 JSON 后同步 Markdown：包含规划身份、JSON 链接、项目及原结构摘要、推荐与实际选择、关键归属/依赖/共享边界及风险。不维护第二份独立选型状态；已有 Markdown 方案首次转为 JSON 时沿用真实事实与用户确认，不凭旧标题推断选择或创建授权。不生成 `source-inventory.json`、`source-baseline.json`、`plan-input.json` 等扫描/中转文件。
|
|
53
|
+
|
|
54
|
+
只请求规划时交付即可，不强求立即选型。用户选定后按 [selection-flow.md](selection-flow.md) 将看板或 question 的确认统一保存到 `architecture-selection.json`，规划只更新 `selectedProposalId`。下一步重新读取两份 JSON，`select-and-create` 确认一致后按 [directory-creation.md](directory-creation.md) 继续并记录实际结果。不同时落实三套，不把目录落地写成应用迁移完成。
|