CANNBot Skills — PyPTO-Gym 多智能体算子开发技能库的架构设计与工程实践指南【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym导读本文以 CANNBot Skills 开发者指南cannbot-skills/AGENTS.md为核心系统讲解 PyPTO-Gym 仓库中面向 PyPTO / PyPTO-Pro 算子开发与模型适配的多智能体技能库从 Skills 开发者的四大核心职责、三条核心设计原则到 Plugins → Agents → Skills → References 四层架构、目录规范与 30 个技能的完整分类并结合仓库内真实插件配置AGENTS.md、安装脚本init.sh与编排状态机源码state-transition-core.ts给出可落地的工程细节。读完本文你将掌握这套技能库的构建思路、分层组织方式、插件安装流程以及 Stage 1–7 多智能体编排的底层状态机机制可直接用于设计自己的算子开发 Agent 团队。一、角色定位Skills 开发者做什么cannbot-skills/AGENTS.md首先明确了本目录面向的角色——Skills 开发者从Agent 架构视角出发构建专业、高效的 PyPTO 算子开发智能体能力模块。其核心职责分为四类职责内涵Skills 开发与优化创建可复用的技能模块为 PyPTO 算子开发 Agent 提供专业能力支持Agents 创建设计专业化子代理实现职责分工和模块化开发业务工作流构建多 Agent 协作编排覆盖 PyPTO/PyPTO-Pro 算子开发、模型适配等完整场景效果评测持续验证 Skills 和 Agents 的实际效果优化交付质量从仓库实际内容看效果评测并非虚设plugins-official/pypto-kernel-validator/AGENTS.md定义了独立的算子产物校验入口由 subagentpypto-kernel-validator对给定op_dir执行反作弊脚本机械检测 LLM 语义审阅 精度 性能三项统一校验产物为output_dir/skill_report.json这正是持续验证 Skills 和 Agents 实际效果的落地机制。二、核心原则三条不可违背的设计红线1. 信息来源可信技术信息必须来自可信源禁止编造可信来源PyPTO 官方文档与代码仓、CANN 安装路径下的文件、用户明确提供的信息禁止行为编造 API/参数、推测未验证的行为不确定时明确标注引导用户验证。这条原则渗透在具体 Skill 的实现中。例如cannbot-skills/ops/pypto-op-knowledge/SKILL.md的知识库查询流程要求串行查询经验表和问题查找表有结果立即返回无结果返回无匹配——宁可如实返回无结果也不允许虚构修复方案。2. 渐进式披露模块设计分层按需展开SKILL.md只写核心流程与决策规则详细参考放references/目录用户需要时再深入引导。pypto-orchestration-manual是这条原则的典型示范见cannbot-skills/ops/pypto-orchestration-manual/SKILL.mdSKILL.md 只做编排入口将principles.md4 条行为准则、agents.md子代理调度契约、rules.md强制规则、lint-gate-rules.md门禁规则速查全部下沉为 references并明确标注Load when加载时机。其自身的说明直接写道This skill is the entry point ... as a set of progressive-disclosure references.3. 简洁精炼输出直击要点先给结论再说原因使用列表、表格等结构化表达一个段落只讲一个要点。references/principles.md将这一原则细化为一套可操作的判据Simplicity First能用 50 行就不要写 200 行、Surgical Changes只改必须改的不顺手优化无关代码、Goal-Driven Execution把任务转化为可验证目标如把实现 M1转化为M1 在 detailed_tensor_compare 下 all_outputs all_close: true。三、四层架构Plugins → Agents → Skills → References文档给出了自底向上的四层架构CANNBot Skills — PyPTO-Gym 架构自底向上 ┌─────────────────────────────────────────┐ │ Plugins应用编排层 │ 编排多个 Agent 协同工作 │ plugins-official/*/ 目录 │ ├─────────────────────────────────────────┤ │ Agents角色执行层 │ 定义做什么职责范围 │ plugins-official/*/agents/ 目录 │ ├─────────────────────────────────────────┤ │ Skills知识能力层 │ 定义怎么做具体实现 │ ops/、model/ 下的各 Skill 子目录 │ ├─────────────────────────────────────────┤ │ References知识层 │ 定义如何做得更好 │ 内嵌在 Skills 中的最佳实践 │ └─────────────────────────────────────────┘ ↑ 效果评测横向覆盖所有层级 ↑Plugins应用编排层通过各自的AGENTS.md定义 Agent 协作顺序与技能绑定关系Agents角色执行层定义做什么职责范围如方案设计、代码开发、代码检视Skills知识能力层定义怎么做具体实现提供领域知识与工程模板References知识层内嵌在 Skills 中的最佳实践定义如何做得更好。ops/、model/分别对应算子开发、模型适配两大业务领域。以plugins-official/pypto-op-orchestrator/AGENTS.md的 frontmatter 为例可以直观看到三者如何绑定name: pypto-op-orchestrator description: PyPTO 算子开发编排者。8 智能体团队的入口。驱动 Stage 1–7强制执行 Stage 完成判据调度子代理。绝不亲自执行 Stage 1-7 的任何领域工作 mode: primary skills: - pypto-orchestration-manual - pypto-docs-search agents: - pypto-op-architect - pypto-op-coder - pypto-op-debugger - pypto-op-mathematician - pypto-op-optimizer - pypto-op-planner - pypto-op-verifier tools: read: true write: true edit: true bash: true每个 Plugin 都是mode: primary的入口 Agent通过skills声明绑定知识能力层、通过agents声明其可调度的子代理团队。四、项目结构三个目录各司其职文档明确了cannbot-skills/的整体布局cannbot-skills/ ├── ops/ # 算子 SkillsPyPTO classic PyPTO-Pro │ ├── pypto-api-explore/ │ ├── pypto-op-design/ │ ├── pypto-pro-op-develop/ │ └── ... # 共 27 个 Skill 子目录 ├── model/ # 模型适配与推理优化 Skills │ ├── hf-npu-e2e-workflow/ │ ├── pypto-convert-model/ │ └── pypto-fused-op-integration/ ├── plugins-official/ # 官方 PluginPlugin 配置 Agents 安装入口 │ ├── pypto-op-orchestrator/ # PyPTO classic 算子开发 │ │ ├── agents/ # Agent 定义.md │ │ ├── hooks/ # 运行时 Hook 与状态机 │ │ ├── AGENTS.md # Plugin 配置 │ │ ├── init.sh # 安装入口 │ │ └── quickstart.md # 快速入门 │ ├── pypto-pro-op-orchestrator/ # PyPTO-Pro 算子开发 │ ├── pypto-model-tools/ # 模型适配工具集 │ └── pypto-kernel-validator/ # 算子产物校验单 Subagent ├── AGENTS.md # 本文件开发者指南 └── README.md # 项目说明与技能索引三个目录的分工可以概括为ops/与model/存放可复用的知识能力Skillsplugins-official/存放把这些能力组合成开发路径的应用编排Plugins。其中plugins-official/下每个插件都遵循一致的内部结构agents/角色定义、hooks/运行时 Hook 与状态机、AGENTS.mdPlugin 配置、init.sh安装入口、quickstart.md快速入门。例如pypto-op-orchestrator/hooks/下同时包含 OpenCode 插件opencode/内含pypto-state-transition.ts、pypto-op-lint.ts等和 lint 门禁pypto-op-lint/内含按 D1–D5 划分的检查器与rules.json。五、Skills 分类全景算子开发与模型适配算子开发ops/共 27 个类别技能示例说明编排与知识类pypto-orchestration-manual、pypto-intent-understand、pypto-op-knowledge、pypto-api-explore、pypto-docs-search、pypto-memory-template编排入口、需求理解、领域知识、API 速查、文档检索、经验复用方案与开发类pypto-op-plan、pypto-op-design、pypto-op-develop实施计划、算子设计与模块接口、代码开发验证与调优类pypto-golden-generate、pypto-precision-compare、pypto-precision-debug、pypto-op-verify、pypto-op-review、pypto-op-perf-tune、pypto-kernel-validateGolden 生成、精度对比与排查、功能验证、代码检视、性能调优、产物校验反作弊 精度 性能监控与调试类pypto-op-monitor、pypto-general-debug任务监控、通用诊断Pro 专属类pypto-pro-intent-understand、pypto-pro-material-explore、pypto-pro-op-plan、pypto-pro-op-design、pypto-pro-op-develop、pypto-pro-op-perf-tune、pypto-pro-golden-generate、pypto-pro-environment-checkPyPTO-Pro 精简流程的全部八项技能其中 Pro 专属类对应 PyPTO-Pro 精简流程。plugins-official/pypto-pro-op-orchestrator/AGENTS.md显示Pro 流程有两种模式orchestrator默认自主开发按需使用 skills、agents、资料和代码仅在用户明确要求时执行完整 Stage 1–5 深度编排且 Pro 流程通过.pypto-pro-op-lint-enabled文件控制自动 lint 开关。模型适配model/共 3 个技能说明hf-npu-e2e-workflowHF 模型到昇腾 NPU 端到端迁移pypto-fused-op-integration融合算子入网集成与整网验证pypto-convert-modelPyTorch/ONNX/safetensors 模型格式互转值得注意的是pypto-model-tools插件的init.sh会同时安装 8 个算子支撑 skillpypto-intent-understand、pypto-api-explore、pypto-golden-generate、pypto-op-design、pypto-op-develop、pypto-precision-compare、pypto-precision-debug、pypto-op-perf-tune这些 skill 仅由pypto-fused-op-integration在算子开发阶段按需调用不参与 primary 选择、不引入状态机或 Subagent见cannbot-skills/plugins-official/pypto-model-tools/AGENTS.md——体现了Plugin 只声明和安装自身工作流需要的 Skills这一约束。四条开发路径cannbot-skills/README.md给出了四个开发路径插件的完整入口领域 / 路径适用场景入口插件PyPTO 算子开发Stage 1–7 全流程融合算子开发与调优pypto-op-orchestratorPyPTO-Pro 算子开发Stage 1–5 精简流程算子开发与性能优化pypto-pro-op-orchestrator模型适配HF 模型上 NPU、融合算子整网集成、模型格式转换pypto-model-tools算子产物校验KernelBench 评测把关反作弊 精度 性能统一校验pypto-kernel-validator六、Skill 目录结构与开发规范文档规定每个 Skill 子目录按需包含以下内容SKILL.md—必需核心技能说明包含触发条件、执行流程与决策规则references/— 可选详细参考文档按需引用的深度资料scripts/— 可选技能使用的自动化脚本templates/— 可选工程模板与配置样例。以pypto-op-knowledge为例cannbot-skills/ops/pypto-op-knowledge/SKILL.mdfrontmatter 中的description字段承担触发条件职责PyPTO 算子开发知识库查询技能。串行查询经验表和问题查找表有结果立即返回无结果返回无匹配。触发词查经验表、查问题表、知识库查询、knowledge query.正文则是串行执行的查询流程图与步骤1. 查经验表 → 命中 → 返回 → 结束 → 未命中 → 进入 2 2. 查问题查找表 → 命中 → 返回 → 结束 → 未命中 → 返回无匹配→ 结束references/承载深度资料experience-table.md索引experience_classified/下 8 个分类文件负责经验表problem-lookup.md负责按关键字索引、错误码路由、运行时症状、修复速查表四个维度路由到官方文档。这完整体现了渐进式披露原则。七、实战落地插件安装与使用在目标项目目录调用对应插件的安装脚本即可完成部署。以 PyPTO 算子开发为例cannbot-skills/plugins-official/pypto-op-orchestrator/init.shcd /path/to/your-project bash /path/to/pypto-gym/cannbot-skills/plugins-official/pypto-op-orchestrator/init.sh \ project opencode opencodeinit.sh支持灵活的安装参数--help可查看完整说明用法: init.sh [level] [tool] [install_path] 参数: level - 安装级别: project默认或 global tool - 目标工具: opencode默认、claude、trae、cursor、copilot、codearts install_path - 项目级安装目录默认: 当前工作目录 示例: init.sh # 项目级, OpenCode init.sh project opencode # 项目级, OpenCode init.sh global claude # 全局级, Claude Code init.sh project trae # 项目级, Trae init.sh project cursor # 项目级, Cursor init.sh project opencode /path/to/proj # 项目级, OpenCode, 自定义路径安装脚本内部执行 5 个步骤① 创建 CANNBot 目录并建立 Skills/Agents 软链接 → ② 安装配置文件OpenCode 为项目根AGENTS.mdClaude 为CLAUDE.md→ ③ 配置工具发现机制 → ④ 确认资源供给边界并在 git 仓库中 exclude 安装目录→ ⑤ 运行健康检查并生成cannbot-manifest.json品牌清单。对 Skills 安装有白名单过滤INCLUDED_SKILLSpypto-api-explore pypto-docs-search ... pypto-orchestration-manual ...共 17 项Agents 按 shell 模式pypto-op-*过滤且只替换白名单内容、不影响用户已存在的其他 skills/agents体现了surgical changes原则。安装完成后启动 OpenCode直接以自然语言描述需求即可开发一个 Attention 融合算子 把 Qwen3-1.7B 模型适配到 NPU八、纵深机制Stage 1–7 编排与状态机源码pypto-op-orchestrator/AGENTS.md揭示了 8 智能体团队驱动 Stage 1–7 的完整编排逻辑这是技能库最有工程价值的机制之一。子代理名册与 Stage 归属cannbot-skills/ops/pypto-orchestration-manual/references/agents.md给出了完整的调度契约谁负责哪个 Stage、产出什么、门禁判据是什么#Agent负责阶段1pypto-op-plannerStage 1产出SPEC.md、API_REPORT.md门禁API map 无未支持的条目2pypto-op-mathematicianStage 2产出op_golden.py、GOLDEN_PERF_REPORT.md门禁allclose通过 shape 注释3pypto-op-architectStage 3产出DESIGN.md、eval/module_interfaces.yaml5pypto-op-coderStage 5按模块 M_k 循环产出op_modulesuffix_k_impl.py 清理阶段整合op_impl.py6pypto-op-verifierStage 4 scaffolding Stage 5 各模块验证 Stage 6 E2E Stage 7 回归judge-only7pypto-op-debuggerStage 5 失败调查仅产出补丁方案不写生产代码8pypto-op-optimizerStage 7 性能调优S1_SETUP / S2_COLLECT / S3_ANALYZE / S4_FRONTEND / S4_SWIMLANE / S4_INCORE / S5_REPORT关键职责边界verifier 只做裁判judge-only返回 PASS/FAIL failure_category枚举precision、aicore、host_crash、workspace_overlap、oom、structure、layout、tile_shape、otherdebugger 只做调查将补丁方案写入MEMORY.md的 Development debug log禁止直接改生产代码coder 是唯一写生产 kernel 代码的 agent。Stage 5 模块失败链路固定为verifier裁判→ debugger调查→ coder应用补丁→ verifier再次裁判且每模块修复/验证循环上限为 10 次达到后 phase 进入blocked状态由编排者决策回滚或上报用户。共享状态双账本设计编排采用双状态存储各司其职、互不重复custom/op/MEMORY.md— 人类可读的叙事账本。推理过程、设计意图、调试尝试、复盘分析。每个子代理都会读写它模板来自pypto-memory-template的templates/MEMORY.template.mdcustom/op/.orchestrator_state.json— 机器可读的进度账本。Stage 状态、重试计数、Phase M_k 状态、artifact 哈希、回滚历史。只有编排者能写且只能通过state_transition工具。JSON 只放数字和状态markdown 只放推理和判断日志——叙事与状态分离既保证人类可审计又保证机器可判读。state_transition状态机的唯一写入通道状态机的类型定义在cannbot-skills/plugins-official/pypto-op-orchestrator/hooks/opencode/lib/state-transition-core.ts中schema v2.0。全部 action 枚举为 11 种export type TransitionAction | init // 启动新算子opDir, stage1, max_stage? | start_stage // fail_stage 后重新进入该 stage | complete_stage // 子代理报告成功且 lint 门禁通过 | fail_stage // 子代理报告不可恢复失败 | submit_design // Stage 4 设计交接Architect → Verifier | start_phase // 开始为 M_k 调度 coder | submit_for_verify // Coder 带回模块 impl副作用跑 phase 范围 lint | complete_phase // Verifier 报告 staged 文件 PASS | fail_phase // Verifier 报告 staged 文件 FAIL | record_artifact_hash // freeze 强制记录产物哈希 | rollback_to_stage; // 回滚重置目标 stage 之后的全部状态源码注释明确其核心不变量All write actions are restricted to pypto-op-orchestrator at the plugin boundary; this file only enforces the state-machine invariants.所有写操作在插件边界限制为仅编排者可用本文件只强制状态机不变量。Stage 5 内部还维护了 per-Phase 状态机pending --start_phase-- in_progress in_progress / in_debug --submit_for_verify (lint PASS)-- awaiting_verify in_progress / in_debug / awaiting_verify --complete_phase (lint PASS)-- verified 任一态 --fail_phase-- in_debug 达到 max_cycles 时为 blockedcomplete_stage会执行hooks/pypto-op-lint/的 lint 门禁D1–D5 五类检查器 rules.json规则表并配套test_stage7_impl_gates.py等测试lint FAIL 时调用抛错且状态文件不变——门禁以副作用方式自动运行编排者不自行调用 lint、不自行复核证据。编排者不变量pypto-op-orchestrator/AGENTS.md末尾列出 7 条不可协商的硬性规则其中最具代表性的有在 Stage 6 完成最终 E2E 验证通过之前不要调度 optimizerStage 7 必须等 E2E 通过后才开始M_k 的 Phase 通过之前不要为 M_{k1} 调度 coderStage 5 是按模块串行的循环不要让 verifier 与 debugger 合并verifier 只做裁判不带 debug 类子 skilldebugger 只做调查不写生产代码任何 agent 不要扩张到超过 5 个 active skill。九、效果评测质量闭环回到文档开头的效果评测职责其落地形态是pypto-kernel-validator插件cannbot-skills/plugins-official/pypto-kernel-validator/AGENTS.md唯一执行者是 subagentpypto-kernel-validator自动加载 skillpypto-kernel-validate对给定op_dir执行反作弊脚本机械检测 LLM 语义审阅 精度 性能统一校验产出output_dir/skill_report.json典型调用方为 pypto-gym 仓benchmark/verifier_runner.pyopencode run --agent pypto-kernel-validator用户手动触发时需收集必需字段op_name、op_dir、task_desc_file、output_dir可选mode/device_id/arch/verify_timeout再以结构化 prompt 调度子代理primary 不亲自执行校验流程只负责收参、调度与转述final_verdict。这与编排流程形成呼应开发路径负责生产校验插件负责把关共同构成覆盖所有层级的评测闭环即架构图中效果评测横向覆盖所有层级的箭头。十、小结从技能库到可组合的 Agent 团队纵观cannbot-skills/AGENTS.md与仓库中的实现这套技能库的设计方法论可以归纳为三点知识分层SKILL.md怎么做→ references如何做得更好→ scripts/templates可复用的工具与样板让 Agent 始终以最小上下文完成当前任务职责隔离编排者只调度不干活、verifier 只裁判不调查、coder 只写生产代码通过state_transition状态机和 lint 门禁强制边界组合复用ops/与model/的知识能力通过plugins-official/的四个插件按需组合成不同开发路径PyPTO 全流程、PyPTO-Pro 精简流程、模型适配、产物校验Skills 与 Agents 均可跨插件复用。对于希望构建或扩展算子开发 Agent 体系的开发者建议直接阅读仓库中的 cannbot-skills/AGENTS.md本指南源文档、cannbot-skills/README.md技能索引与快速开始、pypto-op-orchestrator 配置Stage 1–7 编排细节以及 state-transition-core.ts状态机实现再结合各 Skill 的SKILL.md与references/深入理解每项能力的具体约束。【免费下载链接】pypto-gymPyPTO-Gym 是基于 PyPTO 编程框架构建的算子与模型样例仓库项目地址: https://gitcode.com/cann/pypto-gym创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
