CANN/cannbot-skills迁移手册

Legacy Repo Migration Playbook【免费下载链接】cannbot-skillsCANNBot 是面向 CANN 开发的用于提升开发效率的系列智能体本仓库为其提供可复用的 Skills 模块。项目地址: https://gitcode.com/cann/cannbot-skillsUse 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 StateThe migrated repository should end in this shape:repository root name:ops-easyasc-dslagent/is the primary skill-facing surfaceagent/SKILL.mdis the entrypointagent/ROUTER.mddrives progressive disclosureagent/scripts/holds repository-maintenance scriptsagent/example/kernels/holds curated kernel examplesagent/example/demo/holds manual demo programsagent/assets/ops-easyasc-dsl-runtime.tar.gzstores the archivedeasyasc/,doc/, anddoc_cn/payloadagent/scripts/init.shrestoreseasyasc/,doc/, anddoc_cn/on demandtestcases/is removed from the delivered skill bundledelivered.py/.sh/.bashfiles carry the required script license headerdelivered.h/.cppfiles carry the required C/C license headerMigration OrderApply 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 Steps1. Inspect the original treeConfirm 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 entrypointRecord which files describe structure or commands before moving anything:README.mdREADME_CN.mdAGENTS.mdCLAUDE.mdagent/ROUTER.mdagent/references/repo-map.mdagent/references/code-paths.md2. Remove obsolete top-level contentDeletetestcases/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 surfaceCreateagent/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/name4. Move runnable examples into the skill surfaceCreateagent/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/pathdemo/path-agent/example/demo/path5. Convertagent/into a real skill entrypointAdd or rewrite these files:agent/SKILL.md: user-facing skill entrypointagent/ROUTER.md: first routing layer with progressive disclosureagent/SKILL.mdshould:explain thatagent/scripts/init.shmust run before reading archived runtime/docs contentpoint readers toagent/ROUTER.mddescribe the preferred read order: router - one playbook - one focused reference - one source examplelistagent/example/,agent/scripts/, andagent/assets/avoid machine-specific absolute paths in environment guidanceagent/ROUTER.mdshould:route kernel authoring toagent/playbooks/kernel-authoring.mdroute kernel debugging toagent/playbooks/kernel-debugging.mdroute tool work toagent/playbooks/tool-authoring.mdroute documentation work toagent/playbooks/doc-authoring.mdroute repo-structure questions toagent/references/repo-map.md6. Archive the runtime/docs payload and add an initialization scriptCreate a compressed archive that contains exactly:easyasc/doc/doc_cn/Recommended artifact path:agent/assets/ops-easyasc-dsl-runtime.tar.gzThen create:agent/scripts/init.shinit.shshould:resolve the repository root relative to itselfverify that the archive existsrestoreeasyasc/,doc/, anddoc_cn/only when missingbe safe to run multiple timesAfter the archive and init script are in place:delete the unpackedeasyasc/,doc/, anddoc_cn/trees from the repository snapshotrely oninit.shto restore them when neededwhenever 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 state7. Rename the repository rootRename 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 referencesUpdate 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.shenvironment guidance that hardcodes a machine-specific absolute pathgenerated scripts or runtime helpers that hardcode a machine-specific CANN install rootPreferred style after the migration:use repo-relative paths such asagent/example/kernels/...use environment variables such asASCEND_HOME_PATHinstead of fixed host pathsif an environment name is mentioned, present it as an example rather than a required defaultcheck both the visible repository files and the archivedeasyasc/,doc/,doc_cn/payload before declaring the migration completePractical repair checklist:update visible docs such asREADME.md,README_CN.md,AGENTS.md,CLAUDE.md, andagent/SKILL.mdif 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 pathupdate any restored helper scripts undereasyasc/resources/that still assume a fixed local install pathnormalize every validation example topython agent/example/kernels/a5/matmul_float_mmad.pyafter fixing restored files, rebuildagent/assets/ops-easyasc-dsl-runtime.tar.gzand remove the unpacked trees again9. Apply the required license headersBefore 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 filesinclude files underagent/, restoredeasyasc/, restoreddoc/helper scripts, generatedb.sh/r.sh, and generated runtime source files if they are part of the delivered snapshotmake the insertion idempotent so rerunning it does not duplicate headersafter any validation run that creates new.py,.sh,.bash,.h, or.cppfiles, rerun the license-header pass before finalizing the migration10. Validate the migrated repositoryValidate from the perspective of a fresh user:start from the migrated repository rootrunbash agent/scripts/init.shconfirm thateasyasc/,doc/, anddoc_cn/are restoredrunpython agent/example/kernels/a5/matmul_float_mmad.pyconfirm that the example validates both:OpExec(..., simulatorTrue)OpExec(..., simulatorFalse)if the validation run generates freshb.sh,r.sh, or runtime source files, rerun the license-header passrebuildagent/assets/ops-easyasc-dsl-runtime.tar.gzif the restored trees were edited during validation or repairremove the unpackedeasyasc/,doc/, anddoc_cn/trees again so the final delivered repository stays skill-onlyIf 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 MigrationREADME.mdREADME_CN.mdAGENTS.mdCLAUDE.mdagent/SKILL.mdagent/ROUTER.mdagent/references/repo-map.mdagent/references/code-paths.mdagent/references/examples/kernel-catalog.mdagent/references/examples/tool-catalog.mdagent/index/kernels.jsonagent/index/tools.jsonagent/playbooks/*.mdagent/scripts/tools_summary.mdrestoredeasyasc/kernelbase/kernelbase.pyrestoredeasyasc/resources/debug/build.shrestoredeasyasc/resources/debug/run.shrestoreddoc/01_quickstart.mdrestoreddoc_cn/01_quickstart.mdrestoreddoc_cn/index.mdAnti-PatternsAvoid these mistakes during the migration:leaving duplicate live copies ofkernels/ordemo/at the repository rootkeepingtestcases/in the delivered skill bundle after claiming it was removedhardcoding a workstation path such asuser-home/...into user-facing docshardcoding a generic fallback such as/usr/local/Ascend/...into delivered scripts when the repository is supposed to be environment-drivendescribing archivedeasyasc/,doc/, ordoc_cn/as always presentforgetting to update validation commands after moving examplesfixing restored archive contents but forgetting to rebuildagent/assets/ops-easyasc-dsl-runtime.tar.gzrunning validation, generating new source files, and forgetting to add license headers to those generated filesintroducing a shelltimeoutinto repository scripts just to simplify one local verification runCompletion CheckThe migration is complete when all of the following are true:agent/SKILL.mdis the repository entrypointagent/ROUTER.mdsupports progressive disclosureagent/scripts/owns the former tool scriptsagent/example/owns the formerkernels/anddemo/agent/assets/ops-easyasc-dsl-runtime.tar.gzexistsagent/scripts/init.shrestores the archived treestestcases/is gonevisible files and archived payloads no longer hardcode machine-specific absolute pathsdelivered.py/.sh/.bashfiles carry the required script license headerdelivered.h/.cppfiles carry the required C/C license headerdocs no longer tell users to use stale pathsa fresh-user validation passes frompython agent/example/kernels/a5/matmul_float_mmad.py【免费下载链接】cannbot-skillsCANNBot 是面向 CANN 开发的用于提升开发效率的系列智能体本仓库为其提供可复用的 Skills 模块。项目地址: https://gitcode.com/cann/cannbot-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考