源仓布局与双发布路径的映射成本优化-ohos-delivery-kit-AtomGit

已开启

源仓布局与双发布路径的映射成本优化 #123

LuBo创建于 7月27日

LuBo成员

7月27日创建

问题背景

ohos-delivery-kit 有两条发布路径，各自的布局和占位符体系不同：

渠道	布局根	占位符	替换者
marketplace (`distribute-skills.sh`)	dist 各平台目录	`{{PLUGIN_ROOT}}` / `{{CMD_PREFIX}}` / `{{EXECUTABLE_ROOT}}`	distribute-skills.sh sed 替换
oh-skillhub (openharmony-skills)	`runtime/assets/`	`{{ASSET_ROOT}}`	oh-skillhub installer

源仓目录结构与发布布局的映射关系：

源仓                              marketplace               oh-skillhub
core/skills/                  →   dist/{platform}/skills/       →  skills/
core/templates/               →   dist/{platform}/templates/    →  runtime/assets/templates/
core/profiles/                →   dist/{platform}/profiles/     →  runtime/assets/profiles/
core/contracts/               →   dist/{platform}/contracts/    →  runtime/assets/contracts/
core/rules/                   →   dist/{platform}/rules/        →  runtime/assets/rules/
core/adapters/                →   dist/{platform}/adapters/     →  runtime/assets/adapters/
scripts/validate-artifacts-   →   (不分发)                      →  runtime/executables/
  contract.py
scripts/lib/odk_yaml.py       →   (不分发)                      →  runtime/executables/lib/
docs/{adapters,contracts,     →   (不分发)                      →  (不分发，skill 引用已移除)
  template-injection}.md

当前痛点

1. 占位符体系不统一

marketplace 用 {{PLUGIN_ROOT}}、{{CMD_PREFIX}}、{{EXECUTABLE_ROOT}}（distribute-skills.sh sed 替换）
oh-skillhub 用 {{ASSET_ROOT}}（plugin.yaml variables: ASSET_ROOT: runtime/assets）
源仓 skills 必须选择一套占位符，但另一套渠道不认识
PR #81 曾尝试引入 {{ASSET_ROOT}} 到 skill 引用，但 distribute-skills.sh 不替换它 → dist 残留字面量（BLOCKER）
最终改为移除 docs 引用（skill 自包含），并在 distribute-skills.sh 追加 {{ASSET_ROOT}} 替换作为前瞻性措施

2. distribute-skills.sh 的占位符替换列表持续膨胀

当前需替换 4 个占位符：

sed "s|{{PLUGIN_ROOT}}|$plugin_root|g" | \
  sed "s|{{CMD_PREFIX}}|$cmd_prefix|g" | \
  sed "s|{{EXECUTABLE_ROOT}}|$executable_root|g" | \
  sed "s|{{ASSET_ROOT}}|$plugin_root|g"    # PR #81 追加

每新增一个占位符就要改两个写入函数（write_platform_skill + write_opencode_skill）+ 两个残留检查脚本（validate-distribution.sh + test-opencode-install.sh）= 4 处同步修改。

3. validate-artifacts-contract.py 需要双布局路径检测

PR #81 修复了 ROOT 未定义问题（H3），改为双布局检测：

_SOURCE_CONTRACT = SCRIPT_DIR.parent / "core" / "contracts" / "artifacts.yaml"
_PUBLISHED_CONTRACT = SCRIPT_DIR.parent / "assets" / "contracts" / "artifacts.yaml"
CONTRACT_PATH = _SOURCE_CONTRACT if _SOURCE_CONTRACT.is_file() else _PUBLISHED_CONTRACT

lib 路径也需要同步适配（scripts/lib/ vs runtime/executables/lib/）。每新增一种布局就要加分支。

4. docs 文件分发策略反复

V1：将 docs/ 下的 3 个文件复制到 core/docs/，纳入分发 → 但 skill 引用 {{ASSET_ROOT}}/docs/ 在 marketplace 不被替换（BLOCKER）
V2：移除 docs 引用，skill 自包含，不分发 docs → 正确但丢失了原本的设计意图
根因：源仓 docs/ 目录定位模糊——既是开发者文档又曾被 skill 引用为运行时参考

5. 共享资源复制列表需手动维护

distribute-skills.sh 的 copy_shared_resource 循环：

for resource in templates profiles contracts adapters; do
  copy_shared_resource "$platform" "$resource"
done

新增资源目录（如 rules、docs）时容易遗漏。PR #81 曾追加 docs 后又回退。

6. 残留检查覆盖范围需手动同步

validate-distribution.sh 和 test-opencode-install.sh 的 residue grep 需要手动维护占位符列表：

grep -r '{{PLUGIN_ROOT}}\|{{CMD_PREFIX}}\|{{EXECUTABLE_ROOT}}\|{{ASSET_ROOT}}'

新增占位符时容易遗漏检查脚本更新。

优化方向建议

方向 A：统一源仓目录结构，与 oh-skillhub 发布布局对齐

将 core/ 下的目录结构调整为与 oh-skillhub 一致：

core/
  skills/           (不变)
  runtime/assets/
    templates/
    profiles/
    contracts/
    rules/
    adapters/
  runtime/executables/
    validate-artifacts-contract.py
    lib/odk_yaml.py

好处：源仓和 oh-skillhub 布局一致，__file__ 相对路径在两者中相同。
代价：marketplace distribute-skills.sh 需从 runtime/assets/ 复制；源仓目录大迁移。

方向 B：引入路径/占位符注册表，配置驱动

在源仓维护一个 path-registry.yaml，声明所有占位符及其在各渠道下的替换值：

placeholders:
  PLUGIN_ROOT:
    marketplace: "${OHOS_PLUGIN_ROOT}"
    oh-skillhub: "{{ASSET_ROOT}}"
  ASSET_ROOT:
    marketplace: "${OHOS_PLUGIN_ROOT}"
    oh-skillhub: "{{ASSET_ROOT}}"
resources:
  - skills
  - templates
  - profiles
  - contracts
  - rules
  - adapters

distribute-skills.sh 和残留检查脚本从注册表读取，不再硬编码。

方向 C：单一占位符 + 自动化残留检查

源仓统一用 {{PLUGIN_ROOT}} 一个占位符
所有渠道的构建/安装流程负责替换为各自布局的路径
残留检查脚本从 distribute-skills.sh 的替换列表自动推导，不需手动维护 grep pattern

方向 D：构建期 skill 资产引用校验

在 validate-distribution.sh 或新增脚本中，扫描所有 skill 中的资产路径引用：

凡是引用 templates/、profiles/、contracts/ 等目录的，必须带占位符前缀
裸路径在源仓虽能工作但发布后断裂，应构建期拦截
同 spec-for-ai Issue #57 的方向 D

期望效果

新增发布渠道时，只需加配置不需改代码
占位符替换列表和残留检查不再需要手动同步
docs 文件定位清晰（开发者文档 vs 运行时参考），分发策略不反复
共享资源列表自动发现，不需手动维护循环

关联

本仓 PR #81：修复了这些问题的症状（H3/M7/M8 + B1/B2/B3/M1/L1），最终采用 V2 策略（移除 docs 引用 + 前瞻性 {{ASSET_ROOT}} 替换）
spec-for-ai Issue #57：https://gitcode.com/oshunter/spec-for-ai/issues/57 — 同类问题在 spec-for-ai 仓的记录，含 4 个优化方向的详细分析
上游 openharmony-skills PR #308：https://gitcode.com/openharmonyinsight/openharmony-skills/pull/308 — ohos-sdd 插件发布，触发本轮修复
上游 openharmony-skills PR #309：https://gitcode.com/openharmonyinsight/openharmony-skills/pull/309 — ODK 插件发布，触发本轮修复
上游 oh-skillhub Issue #7：https://gitcode.com/qs_han/oh-skillhub/issues/7 — oh-skillhub 安装后缺少平台原生 manifest，与路径映射问题相关

LuBo成员

7月27日评论：

更新：PR #308/#309 review 轮次中发现的新场景问题

经过 4 轮 review 迭代，以下问题在实际发布检视中被发现，补充到本 issue 作为后续重构的输入。

新场景 1：`{{PLUGIN_ROOT}}` → `{{ASSET_ROOT}}` 转换遗漏（medium，27 处）

ODK skills 中 27 处 {{PLUGIN_ROOT}} 未转换为 {{ASSET_ROOT}}。根因与 spec-for-ai Issue #57 相同——手动 sync 绕过了 publish-plugins.sh 的自动转换。

已修复：全局替换 16 个文件中 27 处。但根因未解决——下次 sync 仍可能遗漏。

新场景 2：workspace.yaml PR 自包含问题（medium）

workspace.yaml 引用 workflows/ohos-sdd/plugin.yaml，但该文件在 PR #308 中，不在 PR #309 中。reviewer 两轮指出此问题。

已修复：workspace.yaml 移除 ohos-sdd 条目，PR #309 只声明 ODK。两 PR 都合入后需 follow-up 追加 ohos-sdd。

根因：workspace.yaml 是共享文件，但每个 PR 只包含一个插件。没有自动化检查"workspace.yaml 引用的 path 是否都在 PR 文件树中"。

新场景 3：passthrough 输出路径未纳入 contract（low）

odk-ms-validation/SKILL.md 中 passthrough 模式输出到 .codespec/changes/<id>/validation.md，但此路径不在 artifacts.yaml 中声明。

已修复：改为 evidence/reviews/validation.md，与 contract 的 evidence 目录约定对齐。

根因：skill 声明的输出路径与 artifact contract 之间无交叉检查。

新场景 4：provenance commit 过时（medium）

provenance.yaml 记录的源仓 commit 9b46a7c 在 PR #81 合入后未更新为 4a2cae2。

已修复：更新到 dev HEAD。

新场景 5：plugin.yaml schema 与 ohos-sdd 不一致（medium）

ODK plugin.yaml 使用标准 schema，但 ohos-sdd 使用自定义 schema，缺少 id/components/compatibility 等字段。

已修复：ohos-sdd plugin.yaml 重写为标准格式（在 PR #308 中修复）。

场景问题与优化方向的映射

新场景	对应优化方向
1. 占位符转换遗漏	方向 C（单一占位符 + 自动残留检查）
2. workspace.yaml 自包含	PR CI 检查（workspace path 存在性验证）
3. 输出路径 vs contract	方向 D 扩展（构建期 skill 输出路径校验）
4. provenance 过时	sync 流程自动化
5. plugin.yaml schema 不一致	方向 B 扩展（plugin.yaml 模板注册表）

关联

spec-for-ai Issue #57：https://gitcode.com/oshunter/spec-for-ai/issues/57 （含 6 个新场景详细分析）
上游 PR #308：https://gitcode.com/openharmonyinsight/openharmony-skills/pull/308
上游 PR #309：https://gitcode.com/openharmonyinsight/openharmony-skills/pull/309
上游 oh-skillhub Issue #7：https://gitcode.com/qs_han/oh-skillhub/issues/7