fix(install-helper): 多源真相漂移根治 + agent/skills 多层发现 + external repo 修复-cannbot-skills-AtomGit

已合并

fix(install-helper): 多源真相漂移根治 + agent/skills 多层发现 + external repo 修复 #798

yanhaifeng5创建于 28 天前从yanhf/cann_skills： master 合入到 cann/cannbot-skills： master

fix(install-helper): 多源真相漂移根治 + agent/skills 多层发现 + external repo 修复 #798

已合并

yanhaifeng5创建于 28 天前

从yanhf/cann_skills master合入到cann/cannbot-skills master

yanhaifeng5成员

28 天前

描述

根因

install-helper 的插件元数据（agents/version）散落在 yml、plugin.json、embedded-plugins.json、optionalDependencies 四处，采用"yml 非空即采信"的回退式调和，无任何交叉校验。agent 改名后 yml 变陈旧，非空即静默覆盖正确值，导致安装时报「Agent 未找到」。同时发现 external repo git pull 失败后 continue 跳过 symlink 创建、skill-registry 离线回退陈旧、yml 与 init.sh INCLUDED_SKILLS 漂移、externalRepos 配置不完整等问题。

修复内容

Bug 修复

【install-helper】pypto-op-orchestrator 安装时 3 个 agent 未找到：yml installAgents 引用 3 个已废弃的 agent 名（pypto-op-analyst/developer/perf-tuner），与 plugin.json 的 8 个实际 agent 零交集。修复后正确安装 8 agents。
【install-helper】ops-registry-invoke 漏装 4 个 agent + spec-to-design skill：yml 仅列 3 个陈旧 agent（实际 7 个）；spec-to-design skill 位于插件本地 skills/ 目录，findSkillSourceDir 仅查 scanDirs 被静默丢弃。修复后正确安装 7 agents + 30 skills。
【install-helper】external repo git pull 失败后跳过 symlink 创建：installExternalRepos 中 pull 失败的 continue 跳过了后续 symlink 逻辑，导致项目目录缺少 external repo 符号链接。删除 continue，pull 失败后仅 warn 并继续创建 symlink（与 init.sh 行为一致）。
【install-helper】optionalDependencies 版本漂移：5 个平台子包版本硬编码，与 package.json version 独立，多次发版后漂移。新增 V6 校验门禁确保一致。
【install-helper】torch-compile.yml 缺少 torch-npugraph-ex-performance-diagnosis：主线 commit d853845a 在 init.sh INCLUDED_SKILLS 中新增了该 skill，但 yml 未同步更新，导致 install-helper 只装 6 个 skill（init.sh 装 7 个）。修复后 yml skills 6→7。
【install-helper】ops-direct-invoke.yml 漏列 ops-tensor externalRepo：init.sh 克隆 https://gitcode.com/cann/ops-tensor.git（depth=1 + recursive），但 yml externalRepos 未声明，导致 install-helper 安装后缺少 Blaze/tensor_api 源码，5 个 Blaze 相关 skill 工作流中断。修复后 yml 补齐 ops-tensor externalRepo。
【install-helper】ops-registry-invoke.yml 漏列 ops-tensor externalRepo：同上，init.sh 克隆 ops-tensor 但 yml 未声明。修复后补齐。
【install-helper】ops-registry-invoke.yml asc-devkit 路径不一致：init.sh 克隆到 reference/cann/asc-devkit（depth=1），yml 声明为 asc-devkit（无 depth），导致 install-helper 克隆到错误路径，API 文档搜索路径不匹配。修复后 yml 路径改为 reference/cann/asc-devkit + depth=1。

特性增强

【install-helper】plugin.json 成为 agents/version 单一真相源：gen-embedded 和 metadata-sync 始终从 plugin.json 派生 agents/version，yml installAgents 作为文档 + Layer 3 兜底（与 installSkills 同构），V5 一致性校验确保 yml 与 plugin.json 不漂移。
【install-helper】agent 三层发现机制：Layer 1 plugin.json agents[]（SoT，过滤 ./AGENTS.md）→ Layer 2 init.sh INCLUDED_AGENT_PATTERN（globSync 匹配，支持 extglob）→ Layer 3 yml installAgents/embedded 兜底。
【install-helper】skills 多层发现机制：Layer 1 yml installSkills → Layer 2 init.sh INCLUDED_SKILLS（mergeInitSkills 补充）→ Layer 3 init.sh ALL_SKILLS（静态解析，动态 $() 跳过）→ Layer 4 <plugin>/skills/ 目录查找（findSkillSourceDir 扩展）。
【install-helper】V1-V7 校验门禁：gen-embedded 构建前强制校验（plugin.json 可解析/agent .md 磁盘存在/skill 源目录存在/skills 计数一致/yml agents 一致性/optionalDependencies==version），FAIL 即 exit 1，build/build:npm/pretest 全路径强制。
【install-helper】skill-registry 离线回退刷新：删除陈旧条目 cuda2ascend-simt（source: ops-lab/，已删除）；新增 4 个 skill（model-train-accuracy-debug、model-train-log-visualization、model-train-oom-analysis、ge-fusion-pass-skill）。
【install-helper】刷新 4 个 plugins-official 陈旧 yml：ops-direct-invoke/ops-registry-invoke/pypto-op-orchestrator/triton-op-generator 的 installSkills 同步 init.sh INCLUDED_SKILLS 完整列表。
【install-helper】SCAN_DIRS 改为从 repository.yaml 读取：validate-plugins.cjs 和 gen-embedded.cjs 的 SCAN_DIRS 从硬编码改为从 src/config/repository.yaml 读取（与 scanner.ts/metadata-sync.ts 统一单一来源），消除三处硬编码漂移风险。

测试看护增强（+28 用例，212→234）

externalRepos 配置测试（8 个）：ops-tensor 存在性 + depth=1 + recursive=true / asc-devkit 路径含 reference/cann/ / embedded externalRepos URL 匹配 yml / 无重复 URL
5 个新 skill 注册断言（5 个）：ascendc-simt-tiling-design / cann-env-setup / torch-ops-profiler / ascendc-direct-invoke-to-registry-invoke / ascendc-registry-invoke-to-direct-invoke 在 skill-registry 静态表中存在
yml skills 计数 vs init.sh 一致性（3 个）：ops-direct-invoke(21) / ops-registry-invoke(30) / torch-compile(7) 三方计数一致
SCAN_DIRS 验证（3 个）：repository.yaml scanDirs 含 runtime / validate-plugins + gen-embedded 可加载
多 skill 批量安装（2 个）：3 个 skill 一次性安装 / 混合 ops + infra 来源
跨 plugin 共享 skill 不冲突（1 个）：同一 skill 二次安装不破坏已有 symlink
plugins-consistency 测试健壮性：8 处 try/finally 包裹临时目录清理 + 4 处 return 改 expect 显式失败

关联的Issue

install-helper 安装 PyPTO 插件时 3 个 Agent 全部报「未找到」（pypto-op-analyst/developer/perf-tuner）
install-helper external repo git pull 失败后跳过 symlink 创建
install-helper yml 与 init.sh INCLUDED_SKILLS 漂移（torch-compile 缺 skill、ops-direct-invoke/ops-registry-invoke 缺 ops-tensor externalRepo）

测试

单元测试：234 个测试全部通过（含 28 新增测试：externalRepos 配置 / 新 skill 注册断言 / yml-init.sh 计数一致性 / SCAN_DIRS / 多 skill 批量 / 跨 plugin 共享）
init.sh 静态测试：359 PASS（test-init-install.sh Check 1-7）
validate-plugins 校验：V1-V7 全部通过
gen-embedded 生成：10 plugins 元数据校验通过
E2E 回归：
- ops-direct-invoke：21 skills, 4 agents, asc-devkit + ops-tensor externalRepo ✓
- ops-registry-invoke：30 skills, 7 agents, reference/cann/asc-devkit + ops-tensor ✓
- torch-compile：7 skills, 1 agent ✓
- install-helper vs init.sh 安装结果对比：skills/agents/externalRepos 全部一致（0 差异）
- 单个 skill 安装：1 skill ✓
- 多 skill 安装：3 skills ✓
- --all 全量安装：173 skills, 0 失败 ✓
- doctor 健康检查：0 warnings ✓
npm 发版验证：
- 1.1.11-beta.0（beta tag）E2E 回归通过
- 1.1.12（latest tag）正式版 E2E 回归 + install-helper vs init.sh 对比测试通过

文档更新

12 个 yml 文件更新（删除 agents/version 硬编码字段，恢复 installAgents 作为文档 + 兜底，刷新 installSkills，补齐 externalRepos）
.gitignore 补全外部仓库排除规则（ops-tensor / asc-devkit / reference/）

类型标签

🐛 Bug 修复
✨ 特性增强
🧪 测试用例
📦 构建 / CI

Pull Request已成功合入, 合并人@CANN-robot

（感谢 yanhaifeng5 的贡献）

yanhaifeng5成员

28 天前创建了 pull request，commit 440adc58

atomgit-bot

28 天前评论：

变更摘要

本次 PR 将 install-helper 从 1.1.7 升级到 1.1.8，核心目标是确立 plugin.json 作为 agents 和 version 的单一真相源（Single Source of Truth），消除 yml 配置与 plugin.json 之间的数据漂移问题。为此移除了所有 plugins.d/*.yml 中硬编码的 agents、installAgents 和 version 字段，新增了 validate-plugins.cjs 验证器（含 V1–V7 七项检查），并将验证集成到构建流程（gen-embedded.cjs）和 CI 门禁（gate_check.sh Phase 2.5）中。同时补充了多项回归测试，修复了部分插件的 skills 计数与实际条目不一致的问题。

主要改动

确立 plugin.json 为 agents/version 单一真相源：所有 plugins.d/*.yml（共 10 个文件）移除了 agents、installAgents、version 字段，gen-embedded.cjs 和 metadata-sync.ts 的 enrichPluginMetadata 函数改为始终从 plugin.json 派生 installAgents 和 version，不再读取 yml 中的硬编码值，也不再仅在 installAgents 为空时才填充。
新增插件元数据一致性验证器 validate-plugins.cjs：实现了 V1–V7 七项检查，包括 plugin.json 可解析性（V1）、agent .md 文件存在性（V2）、installSkills 源目录与 skill 目录存在性（V3）、yml 中 skills 计数与实际条目一致性（V4）、yml 不得包含 agents/installAgents（V5）、optionalDependencies 版本与主版本一致（V6）、yml 不得包含 version 且 plugin.json 必须有非空 version（V7）。
构建时强制验证：gen-embedded.cjs 在生成 embedded-plugins.json 之前调用 validatePlugins()，验证失败则拒绝写入并退出，确保不会产出携带过期数据的构建产物。
CI 门禁集成：gate_check.sh 新增 Phase 2.5，调用 tests/unit/test-install-helper-plugins.sh 在无 NPU/AI 依赖的情况下执行插件元数据一致性检查，拦截 yml/plugin.json 漂移问题。
skills 计数修正与 installSkills 列表更新：ops-direct-invoke.yml（skills: 20→21，新增 ascendc-mc2-best-practice）、ops-registry-invoke.yml（skills: 27→29，新增 ascendc-perf-optimize 和 ops-simulator）、pypto-op-orchestrator.yml（skills: 8→17，大幅扩展 installSkills 列表）、triton-op-generator.yml（skills: 6→8，新增 triton-precision-debug 和 triton-simulator-optimizer）。

不准确？

atomgit-bot

28 天前评论：

代码审查

审查结论

优先级	数量
P0	0
P1	0
P2	1
P3	0

各文件审查结果：

文件	结论
`plugins-community/install-helper/package.json`	发现 1 个问题（lockfile 未同步）
`plugins-community/install-helper/plugins.d/_defaults.yml`	无问题
`plugins-community/install-helper/plugins.d/catlass-op-generator.yml`	无问题
`plugins-community/install-helper/plugins.d/model-infer-optimize.yml`	无问题
`plugins-community/install-helper/plugins.d/ops-code-reviewer.yml`	无问题
`plugins-community/install-helper/plugins.d/ops-direct-invoke-flash.yml`	无问题
`plugins-community/install-helper/plugins.d/ops-direct-invoke.yml`	无问题
`plugins-community/install-helper/plugins.d/ops-registry-invoke.yml`	无问题

整体风险评估：低风险。 本次变更的核心逻辑（将 agents/version/installAgents 从 YAML 中移除、统一由 plugin.json 管理）与现有的校验规则和测试断言完全一致，skills 计数与实际列表匹配。唯一需要注意的问题是 package-lock.json 未随 package.json 版本升级而更新，可能导致 CI 中 npm ci 失败，建议补充提交更新后的 lockfile。

All 8 changed files have been reviewed. Now let me provide the closing summary.

审查总结

本 diff 共涉及 8 个文件，均已完成审查：

文件	审查结论
`plugins-community/install-helper/plugins.d/pypto-op-orchestrator.yml`	无问题 — skills 数量（17）与列表一致，正确移除了 `agents`/`installAgents`/`version` 字段
`plugins-community/install-helper/plugins.d/tilelang-op-orchestrator.yml`	无问题 — skills 数量（9）与列表一致，正确移除了冗余字段
`plugins-community/install-helper/plugins.d/torch-compile.yml`	无问题 — skills 数量（6）与列表一致，正确移除了冗余字段
`plugins-community/install-helper/plugins.d/triton-op-generator.yml`	无问题 — skills 数量（8）与列表一致，正确移除了冗余字段
`plugins-community/install-helper/scripts/gen-embedded.cjs`	无独立问题 — 与 validate-plugins.cjs 的重复代码已纳入共享报告的 P3 建议
`plugins-community/install-helper/scripts/validate-plugins.cjs`	2 个 P3 问题（代码重复 + 缺少 `dir` 防护）
`plugins-community/install-helper/src/core/metadata-sync.ts`	无问题 — `installAgents` 始终从 plugin.json 覆盖的语义变更正确，`.length` 访问安全（函数始终返回数组）
`plugins-community/install-helper/tests/metadata-sync.test.ts`	无问题 — 新增的回归测试正确覆盖了 stale installAgents 被覆盖的场景

按优先级统计：

P0：0
P1：0
P2：0
P3：2（均为健壮性/可维护性建议，非功能缺陷）

整体风险判断：低。 核心变更（将 agents/installAgents/version 的单一事实来源统一到 plugin.json）在两个消费端（build-time 的 gen-embedded.cjs 和 runtime 的 metadata-sync.ts）中语义一致，校验脚本能有效防止漂移，测试覆盖了关键回归场景。两个 P3 建议不影响正确性，可在后续迭代中改进。

现在我对所有三个变更文件进行了完整的审查。以下是我的最终报告。

关闭摘要

文件	审查结果
`plugins-community/install-helper/tests/plugins-consistency.test.ts`	3 个问题（P2: 2, P3: 1）
`tests/gate_check.sh`	无问题
`tests/unit/test-install-helper-plugins.sh`	1 个问题（P3: 1）

按优先级统计：P2 × 2, P3 × 2，共 4 个发现。

总体风险评估：此变更风险较低。引入的测试文件和门禁脚本整体设计合理，能有效拦截插件元数据漂移。发现的 2 个 P2 问题（临时目录泄漏、embedded-plugins.json 静默通过）在 CI 环境中长期运行后可能累积影响，但不会导致即时功能故障。2 个 P3 问题为代码整洁性改进，不影响正确性。建议在合入前处理 P2 问题。