CANN/cannbot-skills迁移手册

Legacy Repo Migration Playbook

【免费下载链接】cannbot-skillsCANNBot 是面向 CANN 开发的用于提升开发效率的系列智能体，本仓库为其提供可复用的 Skills 模块。项目地址: https://gitcode.com/cann/cannbot-skills

Use this playbook when you need to transform the originaleasyascrepository layout into the currentops-easyasc-dslskill-oriented layout.

Read this file first for migration tasks. Do not start by guessing folder moves from memory.

Goal State

The migrated repository should end in this shape:

• repository root name:ops-easyasc-dsl
• agent/is the primary skill-facing surface
• agent/SKILL.mdis the entrypoint
• agent/ROUTER.mddrives progressive disclosure
• agent/scripts/holds repository-maintenance scripts
• agent/example/kernels/holds curated kernel examples
• agent/example/demo/holds manual demo programs
• agent/assets/ops-easyasc-dsl-runtime.tar.gzstores the archivedeasyasc/,doc/, anddoc_cn/payload
• agent/scripts/init.shrestoreseasyasc/,doc/, anddoc_cn/on demand
• testcases/is removed from the delivered skill bundle
• delivered.py/.sh/.bashfiles carry the required script license header
• delivered.h/.cppfiles carry the required C/C++ license header

Migration Order

Apply the transformation in this order so paths stay valid while you edit the repository:

1. Inspect the original tree.
2. Remove obsolete top-level content.
3. Move repository tools into the skill surface.
4. Move runnable examples into the skill surface.
5. Convertagent/into a real skill entrypoint.
6. Archive the runtime/docs payload and add an initialization script.
7. Rename the repository root.
8. Repair documentation, routes, and path references.
9. Apply the required license headers.
10. Validate the migrated repository from a fresh-user workflow.

Detailed Steps

1. Inspect the original tree

Confirm the original repository still has the legacy layout:

• top-leveleasyasc/
• top-leveldoc/
• top-leveldoc_cn/
• top-levelkernels/
• top-leveldemo/
• top-leveltools/
• top-leveltestcases/
• existingagent/content that is not yet a complete skill entrypoint

Record which files describe structure or commands before moving anything:

• README.md
• README_CN.md
• AGENTS.md
• CLAUDE.md
• agent/ROUTER.md
• agent/references/repo-map.md
• agent/references/code-paths.md

2. Remove obsolete top-level content

• Deletetestcases/from the delivered repository.
• Treat removed tests as historical context only; if they need to be mentioned, describe them as removed from the skill bundle rather than still available.

3. Move repository tools into the skill surface

• Createagent/scripts/if it does not exist.
• Move every file from top-leveltools/intoagent/scripts/.
• Preserve script filenames so existing references can be updated with simple path rewrites.
• Move or regenerate the tool summary file underagent/scripts/tools_summary.md.

Expected path rewrite:

• tools/<name>->agent/scripts/<name>

4. Move runnable examples into the skill surface

• Createagent/example/.
• Move top-levelkernels/intoagent/example/kernels/.
• Move top-leveldemo/intoagent/example/demo/.
• Remove the original top-levelkernels/anddemo/directories after the move.

Expected path rewrites:

• kernels/<path>->agent/example/kernels/<path>
• demo/<path>->agent/example/demo/<path>

5. Convertagent/into a real skill entrypoint

Add or rewrite these files:

• agent/SKILL.md: user-facing skill entrypoint
• agent/ROUTER.md: first routing layer with progressive disclosure

agent/SKILL.mdshould:

• explain thatagent/scripts/init.shmust run before reading archived runtime/docs content
• point readers toagent/ROUTER.md
• describe the preferred read order: router -> one playbook -> one focused reference -> one source example
• listagent/example/,agent/scripts/, andagent/assets/
• avoid machine-specific absolute paths in environment guidance

agent/ROUTER.mdshould:

• route kernel authoring toagent/playbooks/kernel-authoring.md
• route kernel debugging toagent/playbooks/kernel-debugging.md
• route tool work toagent/playbooks/tool-authoring.md
• route documentation work toagent/playbooks/doc-authoring.md
• route repo-structure questions toagent/references/repo-map.md

6. Archive the runtime/docs payload and add an initialization script

Create a compressed archive that contains exactly:

• easyasc/
• doc/
• doc_cn/

Recommended artifact path:

• agent/assets/ops-easyasc-dsl-runtime.tar.gz

Then create:

• agent/scripts/init.sh

init.shshould:

• resolve the repository root relative to itself
• verify that the archive exists
• restoreeasyasc/,doc/, anddoc_cn/only when missing
• be safe to run multiple times

After the archive and init script are in place:

• delete the unpackedeasyasc/,doc/, anddoc_cn/trees from the repository snapshot
• rely oninit.shto restore them when needed
• whenever you later edit restored files undereasyasc/,doc/, ordoc_cn/, rebuildagent/assets/ops-easyasc-dsl-runtime.tar.gzand delete the unpacked trees again so the delivered repository returns to the skill-only state

7. Rename the repository root

• Rename the top-level checkout directory fromeasyasctoops-easyasc-dsl.
• Update every document and script that still mentions the old repository root name when the new name matters.

8. Repair documentation, routes, and path references

Update all docs and scripts that referenced removed or moved paths.

Mandatory rewrite categories:

• command examples that referencedkernels/...
• command examples that referenceddemo/...
• tool references that referencedtools/...
• repository maps that still describetestcases/
• skill/router docs that do not yet mentioninit.sh
• environment guidance that hardcodes a machine-specific absolute path
• generated scripts or runtime helpers that hardcode a machine-specific CANN install root

Preferred style after the migration:

• use repo-relative paths such asagent/example/kernels/...
• use environment variables such asASCEND_HOME_PATHinstead of fixed host paths
• if an environment name is mentioned, present it as an example rather than a required default
• check both the visible repository files and the archivedeasyasc/,doc/,doc_cn/payload before declaring the migration complete

Practical repair checklist:

• update visible docs such asREADME.md,README_CN.md,AGENTS.md,CLAUDE.md, andagent/SKILL.md
• if the archive has already been restored once, inspecteasyasc/,doc/, anddoc_cn/for hardcoded host paths such as/home/ubuntu/...or/usr/local/Ascend/...
• updateeasyasc/kernelbase/kernelbase.pyso generated scripts prefer environment variables over a fixed CANN path
• update any restored helper scripts undereasyasc/resources/that still assume a fixed local install path
• normalize every validation example topython agent/example/kernels/a5/matmul_float_mmad.py
• after fixing restored files, rebuildagent/assets/ops-easyasc-dsl-runtime.tar.gzand remove the unpacked trees again

9. Apply the required license headers

Before final delivery, add the required license headers to all delivered source and script files.

For.py,.sh, and.bashfiles, prepend this header. If a file has a shebang, keep the shebang as the first line and insert the header immediately after it:

# ---------------------------------------------------------------------------------------------------------- # Copyright (c) 2026 Huawei Technologies Co., Ltd. # This program is free software, you can redistribute it and/or modify it under the terms and conditions of # CANN Open Software License Agreement Version 2.0 (the "License"). # Please refer to the License for details. You may not use this file except in compliance with the License. # THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED, # INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. # See LICENSE in the root of the software repository for the full text of the License. # ----------------------------------------------------------------------------------------------------------

For.hand.cppfiles, prepend this header:

/** * Copyright (c) 2026 Huawei Technologies Co., Ltd. * This program is free software, you can redistribute it and/or modify it under the terms and conditions of * CANN Open Software License Agreement Version 2.0 (the "License"). * Please refer to the License for details. You may not use this file except in compliance with the License. * THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED, * INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. * See LICENSE in the root of the software repository for the full text of the License. */ /* * Copyright (c) Huawei Technologies Co., Ltd. 2022-2023. All rights reserved. */

License-header checklist:

• apply headers to the delivered repository tree, not just to manually edited files
• include files underagent/, restoredeasyasc/, restoreddoc/helper scripts, generatedb.sh/r.sh, and generated runtime source files if they are part of the delivered snapshot
• make the insertion idempotent so rerunning it does not duplicate headers
• after any validation run that creates new.py,.sh,.bash,.h, or.cppfiles, rerun the license-header pass before finalizing the migration

10. Validate the migrated repository

Validate from the perspective of a fresh user:

1. start from the migrated repository root
2. runbash agent/scripts/init.sh
3. confirm thateasyasc/,doc/, anddoc_cn/are restored
4. runpython agent/example/kernels/a5/matmul_float_mmad.py
5. confirm that the example validates both:
   • OpExec(..., simulator=True)
   • OpExec(..., simulator=False)
6. if the validation run generates freshb.sh,r.sh, or runtime source files, rerun the license-header pass
7. rebuildagent/assets/ops-easyasc-dsl-runtime.tar.gzif the restored trees were edited during validation or repair
8. remove the unpackedeasyasc/,doc/, anddoc_cn/trees again so the final delivered repository stays skill-only

If the non-simulator path is slow, let it complete naturally instead of forcing a shell timeout into the repository script unless the user explicitly asks for that behavior.

Files Commonly Updated During This Migration

• README.md
• README_CN.md
• AGENTS.md
• CLAUDE.md
• agent/SKILL.md
• agent/ROUTER.md
• agent/references/repo-map.md
• agent/references/code-paths.md
• agent/references/examples/kernel-catalog.md
• agent/references/examples/tool-catalog.md
• agent/index/kernels.json
• agent/index/tools.json
• agent/playbooks/*.md
• agent/scripts/tools_summary.md
• restoredeasyasc/kernelbase/kernelbase.py
• restoredeasyasc/resources/debug/build.sh
• restoredeasyasc/resources/debug/run.sh
• restoreddoc/01_quickstart.md
• restoreddoc_cn/01_quickstart.md
• restoreddoc_cn/index.md

Anti-Patterns

Avoid these mistakes during the migration:

• leaving duplicate live copies ofkernels/ordemo/at the repository root
• keepingtestcases/in the delivered skill bundle after claiming it was removed
• hardcoding a workstation path such as<user-home>/...into user-facing docs
• hardcoding a generic fallback such as/usr/local/Ascend/...into delivered scripts when the repository is supposed to be environment-driven
• describing archivedeasyasc/,doc/, ordoc_cn/as always present
• forgetting to update validation commands after moving examples
• fixing restored archive contents but forgetting to rebuildagent/assets/ops-easyasc-dsl-runtime.tar.gz
• running validation, generating new source files, and forgetting to add license headers to those generated files
• introducing a shelltimeoutinto repository scripts just to simplify one local verification run

Completion Check

The migration is complete when all of the following are true:

• agent/SKILL.mdis the repository entrypoint
• agent/ROUTER.mdsupports progressive disclosure
• agent/scripts/owns the former tool scripts
• agent/example/owns the formerkernels/anddemo/
• agent/assets/ops-easyasc-dsl-runtime.tar.gzexists
• agent/scripts/init.shrestores the archived trees
• testcases/is gone
• visible files and archived payloads no longer hardcode machine-specific absolute paths
• delivered.py/.sh/.bashfiles carry the required script license header
• delivered.h/.cppfiles carry the required C/C++ license header
• docs no longer tell users to use stale paths
• a fresh-user validation passes frompython agent/example/kernels/a5/matmul_float_mmad.py

【免费下载链接】cannbot-skillsCANNBot 是面向 CANN 开发的用于提升开发效率的系列智能体，本仓库为其提供可复用的 Skills 模块。项目地址: https://gitcode.com/cann/cannbot-skills