当前位置：首页 > news >正文

CANN/cannbot-skills迁移手册

news 2026/5/9 20:27:08

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:

Inspect the original tree.
Remove obsolete top-level content.
Move repository tools into the skill surface.
Move runnable examples into the skill surface.
Convertagent/into a real skill entrypoint.
Archive the runtime/docs payload and add an initialization script.
Rename the repository root.
Repair documentation, routes, and path references.
Apply the required license headers.
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. Convert`agent/`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:

start from the migrated repository root
runbash agent/scripts/init.sh
confirm thateasyasc/,doc/, anddoc_cn/are restored
runpython agent/example/kernels/a5/matmul_float_mmad.py
confirm that the example validates both:
- OpExec(..., simulator=True)
- OpExec(..., simulator=False)
if the validation run generates freshb.sh,r.sh, or runtime source files, rerun the license-header pass
rebuildagent/assets/ops-easyasc-dsl-runtime.tar.gzif the restored trees were edited during validation or repair
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