CANN/cannbot-skills Ops-Easyasc-DSL指南

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

• The user-facing skill entrypoint isskill/SKILL.md; the reusable workflow lives underagent/.
• Before reading archived runtime/docs or examples, runbash agent/scripts/init.shto restoreeasyasc/,doc/,doc_cn/, andagent/example/.
• Start every conversation by readingagent/ROUTER.mdfirst
• Follow the router-first reading order:
  1. readagent/ROUTER.md
  2. read only one matching playbook for the current task when possible
  3. read only the focused constraint, pattern, example, or map file that the playbook/router points to
  4. read source files only after the smaller guidance layers stop being enough
• Do not start by loading giant summaries when a smaller route already answers the task
• High-level owner files:
  • agent/references/repo-map.md: top-level repository layout and ownership map
  • agent/references/code-paths.md: implementation-path lookup for operations and behaviors
  • doc/11_architecture_for_contributors.md: contributor-level architecture and subsystem ownership fallback (restored on demand)
  • agent/scripts/tools_summary.md: tool fallback; preferagent/references/examples/tool-catalog.mdandagent/playbooks/tool-authoring.mdfirst
• For kernel authoring tasks:
  • firstdoagent/playbooks/clarify-first.mdto settle the Contract Template before any code — this is a hard prerequisite, not an optional step
  • then startagent/playbooks/kernel-authoring.md
  • then read only the specific constraint files you need
  • then useagent/references/examples/kernel-catalog.mdto choose source examples
• For kernel debugging tasks:
  • start withagent/playbooks/kernel-debugging.md
  • then read only the matching constraint file for the suspected failure mode
• For tool changes:
  • start withagent/playbooks/tool-authoring.md
  • useagent/references/examples/tool-catalog.mdbefore opening tool code
• For documentation changes:
  • start withagent/playbooks/doc-authoring.md
  • then useREADME.md,README_CN.md,agent/references/repo-map.md, anddoc/11_architecture_for_contributors.mdas needed
• For repo-structure questions:
  • start withagent/references/repo-map.md
  • then useagent/references/code-paths.mdif the question is really about implementation location
  • then usedoc/11_architecture_for_contributors.mdonly when the smaller maps are not enough

Repository working rules

• Before guessing, inspect the real implementation path for the target behavior inside this repository.
  • check the relevant files undereasyasc/stub_functions/
  • then parser lowering undereasyasc/parser/
  • then simulator behavior undereasyasc/simulator/when execution semantics matter
• Existing kernels are for study, not copy-paste. Use them to understand repository semantics, constraints, and synchronization patterns.
• Unless the user explicitly requests otherwise or the task is already tied to an existing kernel file, implement a new kernel in a new file by default.
• In this repository, "kernel" means a function decorated with@kernel. User-visible inputs and outputs must map strictly to theGMTensorarguments and returnedGMTensorobjects of that@kernelfunction.
• Build kernels incrementally: reason about tile strategy first, then implement and validate stage by stage instead of trying to finish the whole kernel in one jump.
• Justify each operation, cast, buffer, synchronization edge, and datamove from the target formula and hardware behavior. Do not keep a step only because another kernel happened to use it.
• Before golden inputs enter the kernel, only shape-only transforms are allowed, such assqueeze,unsqueeze, andreshape. Do not useexpand,tile,permute, or other layout-changing transforms unless the user explicitly wants that behavior.
• If any part of the reasoning is ambiguous or cannot be justified from repository evidence, stop and ask instead of guessing. For kernel authoring specifically, the Contract Template inagent/playbooks/clarify-first.mdmust be fully settled before you begin Step 1 ofagent/playbooks/kernel-authoring.md; do not substitute "reasonable assumptions" for questions on fields the playbook marks ASK.
• Treat warnings as signals that the mental model is incomplete. Investigate the root cause instead of accepting a passing result with unresolved warnings.
• Forauto_syncwarnings specifically, understand the synchronization model first, then either adjust the kernel or propose a concrete parser/autosync change.

Update owner docs, not giant summaries

When stable repository knowledge changes, refresh the owner files that actually describe that area:

• repository structure or subsystem ownership ->agent/references/repo-map.mdand/ordoc/11_architecture_for_contributors.md

• implementation-path lookup ->agent/references/code-paths.md

• kernel additions or meaningful kernel changes ->agent/references/examples/kernel-catalog.md

• tool additions or tool behavior changes ->agent/scripts/tools_summary.md

• demo boundaries ->agent/example/demo/README.md

• documentation entry maps ->README.md,README_CN.md, and the affecteddoc/ordoc_cn/pages

• If atorch210npuconda environment is available it is a convenient example environment; otherwise use the default environment with the required dependencies.

• Typehints should be compatible with python3.8.

• All codes, error messages, and readme files should be written in English.

• Refer to theagent/example/kernelsfolder for templates.

Environment setup

The simulator-only path (OpExec(..., simulator=True)) needs only a working Python + PyTorch environment. The non-simulator path (OpExec(..., simulator=False),cannsimsmoke runs, and real on-device validation) additionally needs a Linux host and a local CANN install.

Python / conda environment

• Create (or reuse) a Python environment. A conda env namedtorch210npuis the conventional example; any environment with the listed dependencies works.

  # example only — adjust to your local setup conda create -n torch210npu python=3.10 -y conda activate torch210npu

• Install the Python dependencies listed inrequirements.txt:

  pip install -r requirements.txt

  Currentrequirements.txtcontents:numpy,torch,torch-npu,einops,prettytable,rich,sympy,setuptools,decorator,scipy,attrs,psutil. Keeptorch/torch-npualigned with your local CANN version. CANN itself is not a pip package and must be installed separately (see below).

• Typehints in this repository must stay compatible with Python 3.8.

CANN install (Linux only)

cannsimand real on-device validation require a Linux host plus a local CANN toolkit install. macOS / Windows arenotsupported for the non-simulator path.

• Download the CANN package matching your target architecture from:https://ascend.devcloud.huaweicloud.com/artifactory/cann-run-mirror/software/master/20260415000324328/

• Install the toolkit following the official CANN install guide, then export the install root so generatedb.sh/r.shscripts and restored helpers can find it:

  export ASCEND_HOME_PATH=<path-to-your-CANN-install> # the directory that contains bin/setenv.bash # optional: prepend a Python-with-NumPy for CANN opbuild # export EASYASC_PYTHON_BIN=<conda-env>/bin source "${ASCEND_HOME_PATH}/bin/setenv.bash"

• Do not hardcode workstation-specific paths such as/home/<user>/...or/usr/local/Ascend/...into the delivered repository. Delivered scripts must stay environment-driven viaASCEND_HOME_PATH/ASCEND_INSTALL_PATH.

What runs without CANN vs. what requires it

• Simulator-only kernel validation (OpExec(..., simulator=True)) — works on any OS with PyTorch installed; no CANN needed.
• OpExec(..., simulator=False),cannsimsmoke runs, and real NPU validation —requirea Linux host and a local CANN install withASCEND_HOME_PATHset.

Python formatting

For Python code, do not automatically rewrite function signatures or calls into a one-argument-per-line style.

• Prefer compact formatting.
• Keep arguments on the same line if the result is still easy to read.
• Wrap only when necessary for readability or line length.
• If wrapping is needed, use a compact multi-line layout instead of placing every argument on its own line unless there is a clear readability benefit.
• Avoid unnecessary trailing commas that encourage vertical expansion.

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