asc-devkit 的 AI Agent Skill 仓库架构：.agent 单一事实源与多客户端软链兼容设计

导读

asc-devkit（CANN 昇腾 AI 处理器算子开发语言仓库）为 AI Agent 与人类开发者搭建了一套可维护的 Agent skill 管理体系：以 .agent 目录为唯一事实源，统一维护本地 skill、reference 与 skill 级测试，再通过 .opencode、.claude、.codex 三个兼容入口以软链方式暴露给不同 AI 客户端。本文以仓库内 .opencode/README.md（即 .agent/README.md 的兼容入口）为骨架，完整梳理内置 skill 清单、目录软链结构、公共 skill 安装流程、事实源分级、skill 级测试运行方式与维护边界，并结合 .agent 下的实际脚本与测试源码，说明这套体系如何支撑 AscendC API 的 UT 生成、需求分析、架构事实维护等开发任务。读完本文，你将掌握在该仓库中新增/修改 skill、运行 skill 测试、消费结构化事实的正确姿势，并理解“单一事实源 + 软链兼容”这一设计模式的价值。

一、整体架构：单一事实源与兼容入口

1.1 设计动机

AI 编码客户端（如 OpenCode、Claude、Codex）通常约定从各自的配置目录（.opencode、.claude、.codex）读取 skill 与相关测试。若在多个目录中分别维护同一份 skill 内容，必然导致事实漂移与维护成本失控。asc-devkit 的解决方案是：

• .agent/ 是唯一事实源，维护本地 skill 和 skill 级测试；
• .opencode、.claude、.codex 是兼容入口目录，目录内的 README.md、skills、tests 均为指向 .agent 对应内容的软链，不是独立事实源。

用仓库实际文件系统验证，三个兼容入口的内容完全一致（均为软链）：

.opencode/
  README.md -> ../.agent/README.md
  skills    -> ../.agent/skills
  tests     -> ../.agent/tests
.claude/
  README.md -> ../.agent/README.md
  skills    -> ../.agent/skills
  tests     -> ../.agent/tests
.codex/
  README.md -> ../.agent/README.md
  skills    -> ../.agent/skills
  tests     -> ../.agent/tests

因此本文讨论的 .opencode/README.md 实际内容即 .agent/README.md，两者始终指向同一份事实。

1.2 为什么根目录不能整体软链

文档特别强调：兼容入口的根路径应保持为真实目录，根目录软链可能触发沙箱只读保留路径校验失败。正确形态是“真实目录 + 内部软链”，即 mkdir -p 出目录，再把三个条目分别软链到 .agent。当兼容入口损坏时，应按如下方式恢复：

mkdir -p .opencode .claude .codex
ln -s ../.agent/README.md .opencode/README.md
ln -s ../.agent/skills .opencode/skills
ln -s ../.agent/tests .opencode/tests
ln -s ../.agent/README.md .claude/README.md
ln -s ../.agent/skills .claude/skills
ln -s ../.agent/tests .claude/tests
ln -s ../.agent/README.md .codex/README.md
ln -s ../.agent/skills .codex/skills
ln -s ../.agent/tests .codex/tests

这条规则也意味着：后续新增或修改 skill，只需改 .agent/skills；.opencode、.claude、.codex 不应维护独立内容。

二、内置 skill 清单与职责划分

.agent 当前内置四类本地维护 skill 与一类公共远程 skill，完整清单见下表：

Skill	用途	入口（仓库相对路径）
asc-api-ut-gen	生成或补齐 tests/api/ 下的 AscendC API UT	.agent/skills/asc-api-ut-gen/SKILL.md
asc-ar-dev	AscendC 需求分析、实现方案、host/device 代码评审与验证规划	.agent/skills/asc-ar-dev/SKILL.md
asc-npu-arch	维护芯片、架构、SocVersion、__NPU_ARCH__ 和 dtype 事实	.agent/skills/asc-npu-arch/SKILL.md
public-skills	从 cann-agent/skills 远程仓库安装或更新公共 skill	.agent/skills/public-skills/SKILL.md
gitcode-pr	通过公共远程 skill 处理 GitCode PR、评论、讨论和变更查询	gitcode-pr（由安装脚本装入 _remote/ 后软链暴露）

当前 .agent 通过 asc-ar-dev 覆盖 AscendC 需求分析、实现方案和代码评审；示例工程生成暂不单独维护 skill。

2.1 asc-api-ut-gen：API 单元测试生成

该 skill 面向“为新 API 编写 UT、补充现有测试覆盖、验证分支路径、按覆盖率报告补齐低覆盖用例”等场景，覆盖高阶 API、membase 基础 API、regbase 基础 API、C API、SIMT API、工具类 API 的 UT 生成，包含分支覆盖分析、参数化测试设计与精度验证。其实现有两个关键点：

1. Python 脚本自动生成 UT：核心脚本位于 .agent/skills/asc-api-ut-gen/scripts/，其中 ut_generator_cli.py 是 CLI 入口，ut_generator.py 是包含模板系统与生成器的核心逻辑；
2. 结构化约束驱动：脚本运行时必须加载两个 reference——references/foundations/generation-constraints.json（API 类型列表及 regbase/SIMT 等生成限制）与 asc-npu-arch 的 npu-arch-facts.json（芯片调用名、__NPU_ARCH__、SocVersion、测试目录前缀、dtype 大小与直接初始化规则）。

API 类别与测试目录的对应关系记录在 references/foundations/api-directory-map.md，该表基于仓内 include/、impl/、tests/api/ 的实际目录扫描整理，例如：高阶 API 声明在 include/adv_api/，实现于 impl/adv_api/detail/ 与 impl/adv_api/tiling/，UT 落在 tests/api/adv_api/；regbase 基础 API 的 UT 目录是 tests/api/reg_compute_api/，不能放进 tests/api/basic_api/。此外该 skill 还有明确的边界：当前忽略 Tensor API，不维护 include/experimental/tensor_api/、impl/experimental/tensor_api/、tests/api/tensor_api/ 的生成规则。

2.2 asc-ar-dev：需求分析与实现评审

asc-ar-dev 是仓库覆盖范围最广的 skill，负责把原始任务拆解为 AscendC 需求文档、实现或评审 host/device 代码、规划构建/仿真/NPU/文档/回归验证，并在职责归属明确时把专项工作路由给仓库内更聚焦的 skill（例如 UT 生成归 asc-api-ut-gen，芯片与 dtype 事实归 asc-npu-arch）。它要求在执行仓库相关工作前先收集最小输入集：DEVKIT_PATH、CANN_PATH、SOC_ARCH、TASK_GOAL；DEVKIT_PATH 通过向上查找含 CMakeLists.txt、include/、impl/、tools/、.agent/ 的根目录推导，CANN_PATH 优先采用已验证的环境变量（如 ASCEND_HOME_PATH、ASCEND_TOOLKIT_HOME）。该 skill 的 8 份 reference（references/）分别覆盖格式模板、调用规则、本地环境、devkit 片段、调试 dump、构建元数据、任务目标示例与需求类型路由。

2.3 asc-npu-arch：芯片与 dtype 事实的唯一来源

这是“事实源分级”体系的枢纽。它统一维护芯片调用名、NpuArch/SocVersion/__NPU_ARCH__ 映射、通用 dtype 视图与 dtype 大小。从 .agent/skills/asc-npu-arch/SKILL.md 可以看到完整映射表，例如 ascend910 对应 __NPU_ARCH__=1001、SocVersion=ASCEND910；ascend950pr_9599 对应 3510、ASCEND950，是当前 regbase/SIMT 的主入口；ascend910b1 与 A3 系列共用 2201。结构化事实存放在 references/npu-arch-facts.json，该 JSON 明确声明 version: 2，来源为 npu-arch-guide.md，dtype 来源为仓内 docs/zh/api/context/内置数据类型.md，并以 arch_dir 字段（如 ascendc_case_ascend950pr_9599）记录测试目录前缀——这正是 UT 生成脚本定位测试目录的输入之一。

三、公共 skill 的远程安装与更新机制

仓内本地仅维护 asc-api-ut-gen、asc-ar-dev、asc-npu-arch 与 public-skills；gitcode-pr 等公共通用 skill 通过 .agent/skills/public-skills/scripts/install-public-skills.sh 从 cann-agent/skills 仓库安装到 .agent/skills/_remote/，再以 .agent/skills/gitcode-pr -> _remote/gitcode-pr 这类一级软链暴露给客户端。

更新公共通用 skill 的命令：

bash .agent/skills/public-skills/scripts/install-public-skills.sh

从安装脚本源码可以看到该机制的完整实现细节（install-public-skills.sh）：

• 待安装清单固定为 PUBLIC_SKILLS=("gitcode-pr" "gitcode-issue" "api-doc-generator" "gitcode-pipeline")，远程仓库为 https://gitcode.com/cann-agent/skills.git；
• 安装前先做连通性检查：优先用 curl 探测 gitcode.com 的 HTTP 状态码（200/301/302 视为可达），退化到 wget，再退化到 git ls-remote，不可达时直接报错退出（set -e）；
• 采用 git clone --depth 1 浅克隆到临时目录（优先 mktemp -d，无 mktemp 时回退到 /tmp/skills_install_$$），通过 trap 在退出时清理临时目录；
• 对每个公共 skill 执行“删除旧缓存 → 复制到 _remote/<skill> → 删除旧一级软链 → ln -sfn "_remote/<skill>" 重建软链”，实现原子式更新；
• 安装完成后自动维护 .gitignore：追加 .agent/skills/_remote/ 与 .agent/skills/<skill> 条目，确保远程缓存与软链不入库。

四、事实源分级与消费规则

为避免多个 skill 并行维护芯片表、dtype 表导致冲突，.agent/README.md 明确了“事实源顺序”，按事实类型指向唯一首选来源：

事实类型	首选来源
芯片、架构、SocVersion、__NPU_ARCH__、dtype	.agent/skills/asc-npu-arch/references/npu-arch-facts.json
架构和 dtype 人工说明	.agent/skills/asc-npu-arch/references/npu-arch-guide.md
AscendC 需求分析、实现评审、调用层级和环境解析	.agent/skills/asc-ar-dev/SKILL.md 及 references/
API 类型、目录和 UT 目录映射	.agent/skills/asc-api-ut-gen/references/foundations/api-directory-map.md
API 类型限制和生成器约束	.agent/skills/asc-api-ut-gen/references/foundations/generation-constraints.json
UT 生成流程、覆盖率和报告要求	.agent/skills/asc-api-ut-gen/references/workflows/

配套的消费规则有一条硬性约束：脚本需要消费芯片或 dtype 事实时，必须读取结构化 JSON，不解析 Markdown 表格，也不要在脚本中复制完整事实表。npu-arch-facts.json 正是为此设计——它把芯片枚举名、npu_arch、soc_version、arch_dir 以机器可读形式集中存放，UT 生成脚本、覆盖率脚本都直接消费它。

五、skill 级测试：结构、内容与全量回归

每个 skill 都配有一组 shell 测试脚本，位于 .agent/tests/skills/<skill>/：

.agent/tests/skills/
  asc-api-ut-gen/   # 含 fixtures/、golden/、test-content.sh、test-generation.sh、test-structure.sh、test.sh
  asc-ar-dev/       # test-content.sh、test-structure.sh、test.sh
  asc-npu-arch/     # test-content.sh、test-structure.sh、test.sh
  gitcode-pr/       # test-content.sh、test-structure.sh、test.sh
  run-all.sh

以 asc-npu-arch/test.sh 为例，它聚合执行 test-structure.sh 与 test-content.sh 两个子测试后输出 [PASS]。asc-api-ut-gen 的 test-structure.sh 则验证 SKILL 文档、references/ 目录中的各 API guide、foundations/ 约束文件、workflows/ 文档等必需文件是否存在，保证 skill 结构完整性；其 fixtures/ 中存放了真实 API 输入（如 add_aiv_ascend910b1.json、softmax_adv_ascend610.json），golden/ 存放期望生成的 UT 代码（如 add_aiv_ascend910b1.cpp），test-generation.sh 用脚本生成结果与 golden 对比，实现端到端回归。

运行全部 skill 测试：

bash .agent/tests/skills/run-all.sh

run-all.sh（源码）遍历 tests/skills/*/test.sh，逐个以 bash 执行并打印 [RUN] <skill>，任一失败即因 set -euo pipefail 中断，全部通过则输出 [PASS] all skill tests passed。

单独测试某个 skill：

bash .agent/tests/skills/asc-api-ut-gen/test.sh
bash .agent/tests/skills/asc-ar-dev/test.sh
bash .agent/tests/skills/asc-npu-arch/test.sh

六、给 AI Agent 的维护边界与修改规则

6.1 维护边界

• .agent/skills 是本仓 skill 的唯一事实来源；
• 公共通用 skill 的本仓事实源是 public-skills 的安装脚本；不要在本仓重新实现 gitcode-pr、gitcode-issue、api-doc-generator 或 gitcode-pipeline；
• skills/_remote/ 是远程缓存目录，skills/gitcode-pr 等一级入口应是指向 _remote/<skill> 的软链；
• 不直接编辑 .opencode/skills、.claude/skills 或 .codex/skills，它们都通过软链访问 .agent/skills；
• .opencode、.claude、.codex 的根路径应保持为真实目录，根目录软链可能触发沙箱只读保留路径校验失败。

6.2 修改规则与交付要求

• 修改 skill 正文、reference、脚本或测试后，运行所有相关的 shell 测试脚本，并至少包含相关 skill 的 test.sh，确认执行正确后再交付；
• 跨 skill 或通用事实变更后，运行 bash .agent/tests/skills/run-all.sh 做全量回归；
• 新增 reference 时，同步更新对应 references/README.md 或 skill 的参考索引；
• 新增芯片时，优先更新 asc-npu-arch 的结构化事实（npu-arch-facts.json）；只有 API 类型限制变化时，才更新 asc-api-ut-gen 的 generation-constraints.json。

6.3 UT 任务的标准入口流程

当 AI Agent 处理 API UT 任务时，文档给出了明确的操作序列：

1. 先确认目标 API、API 类型、目标芯片和是否需要构建验证；
2. 读取 asc-npu-arch 确认芯片、架构和 dtype 边界；
3. 读取 asc-api-ut-gen 的 API guide、目录映射和工作流；
4. 生成或修改 UT 后，报告 token 消耗、总耗时、当前覆盖率；无法获取时说明原因；
5. 不声称未执行的构建、UT 或覆盖率验证已经通过。

最后一条是事实边界的硬性要求：Agent 的交付报告必须区分“已执行验证”与“推断结论”，不得虚报验证状态。

七、对仓库开发者的使用说明

• 人类使用者：直接查看 .agent/skills/<skill>/SKILL.md 了解各 skill 能力，通过 .agent/tests/skills/ 下的测试脚本验证 skill 健康度；日常使用无需任何安装步骤。
• AI Agent：按“事实源顺序”消费结构化事实（尤其 npu-arch-facts.json），遵循“只改 .agent/skills、测试通过再交付、不虚报验证状态”三条红线。
• 客户端兼容：OpenCode/Claude/Codex 直接读取各自兼容入口 .opencode/skills、.claude/skills、.codex/skills（均为指向 .agent/skills 的软链），即可获得与 .agent 完全一致的能力；若某个客户端只读取 ${CODEX_HOME:-$HOME/.codex}/skills 这类用户目录，则由客户端或用户环境自行管理，不作为本仓事实源的一部分。

这套“单一事实源 + 软链兼容入口 + 结构化 reference + skill 级回归测试”的设计，让 asc-devkit 的 Agent 能力既能被多种客户端复用，又能在仓库内以可测试、可审计的方式持续演进，值得作为 AI 工程化仓库的组织范本参考。