@cannbot-plugin/cannbot-harness 0.0.0-stage → 0.1.4

package/assets/ops-direct-invoke/skills/ops-direct-invoke/templates//347/231/275/347/233/222/346/265/213/350/257/225/350/256/276/350/256/241.md

@@ -0,0 +1,37 @@
+# {算子名称} 白盒测试设计与用例接入
+
+> 算子实现后，developer 依据真实源码生成用例，直接写入已有 ST 框架。本文记录设计依据和接入结果，不能代替可执行用例。
+
+## 输入与版本
+
+- 算子源码及当前版本：
+- 已确认需求与黑盒方案：
+- 现有测试框架、入口与版本：
+
+## 源码分支清单
+
+| 分支 ID | 文件/函数/行号或条件原文 | 触发条件 | 边界及适用依据 |
+|---------|-------------------------|----------|----------------|
+
+> 枚举全部有效的尾核、尾块、非对齐、多核、dtype 与 tilingkey 等分支；不适用项给出源码依据。知识搜集草稿不限制实际分支。
+
+## 白盒用例与框架接入
+
+| 用例 ID | 源码分支 | shape/dtype/参数 | 数据构造与预期结果 | 测试文件/入口 | 复用的黑盒用例 |
+|---------|----------|-----------------|--------------------|---------------|----------------|
+
+- 全量执行命令：
+- 新增/修改文件与用例发现方式：
+- golden、精度及预期异常依据：
+
+## 覆盖记录
+
+| 源码分支 | 对应用例 | 设计覆盖依据 | 实际命中或受阻状态 | 证据路径 |
+|----------|----------|--------------|--------------------|----------|
+
+## 问题交接
+
+| 问题 | 算子缺陷/测试问题/框架问题 | 复现步骤与证据 | 受影响路径 | 修复要求 |
+|------|--------------------------|----------------|------------|----------|
+
+> 测试与框架问题须在本节点修正；用例正确但暴露的算子缺陷交给下游代码修复。没有缺陷时如实记录，无需制造问题。

package/assets/ops-direct-invoke/skills/ops-direct-invoke/templates//347/237/245/350/257/206/346/220/234/351/233/206.md

@@ -0,0 +1,25 @@
+# {算子名称} 知识搜集与实现草稿
+
+> 中立参考，不是锁定方案或路线可行性证明。只记录本轮重点，引用需求文件而非复述全文；不要求遍历资料库或给全部阅读文件计算哈希。
+
+## 关键资料与结论
+
+| 要解决的问题 | 关键结论 | 来源路径/链接、版本与位置 | 适用条件及限制 |
+|-------------|----------|--------------------------|----------------|
+
+决定路线或 API 使用的引用须可核对。非关键资料未找到时记录未知，删除无依据断言；不为凑齐参考资料展开无关检索。新增 Skill 建议注明适用节点与阶段，仅供整轮结束后编排，不改变本轮清单。
+
+## 初版实现草稿
+
+| 候选路线及 API 组合/数据流 | 代表性 shape 分组 | 多核/块大小/Buffer/尾块设想 | 依据与待验证项 |
+|---------------------------|------------------|----------------------------|----------------|
+
+区分资料已证实、推导建议和待验证假设；不逐个展开完整 shape 笛卡尔积，不宣称已实测或已完成性能验证。
+
+## 关键风险与下一步
+
+- 建议优先验证的关键组合与理由：
+- 未确认限制或规则冲突及依据：
+- 本次未覆盖的范围：
+
+重试只追加问题编号、修正结论及证据变化；保留历史，不重写未变内容。

package/assets/ops-direct-invoke/skills/ops-direct-invoke/templates//351/252/214/346/224/266/346/212/245/345/221/212.md

@@ -0,0 +1,39 @@
+# {节点 ID} {步骤名称} 验收报告
+
+> 仅 verifier 编写。通过、失败及阻塞均须落盘。验收者核对当前产物和执行证据，不代替执行者构建、运行全量测试或补造日志。
+
+## 验收对象与证据
+
+- 本轮节点及验收次数：
+- 需求及输入版本：
+- 当前交付件路径、源码/测试哈希或变更快照：
+- 执行报告、固定版本的证据清单与原始结果索引路径：
+- 本次变更及复用核对：{新执行 / 复用来源；当前版本差异与有效性判断}
+- 实际加载的补充 Skill 与依据（无则记无）：
+
+## 逐项结论
+
+| 验收项 | 通过 / 失败 / 阻塞 / 不适用 | 事实依据与文件位置 |
+|--------|--------------------------|--------------------|
+
+涉及执行结果时，核对命令、工作目录、退出码、源码/测试/构建产物哈希、运行时加载路径和当前阶段用例计数、逐项结果。穿刺只要求下发范围的关键组合与代表用例真实设备证据；正式交付要求全量，二者不能互相代替。执行者自述通过不足以证明通过；缺失或无法核对的证据判失败。知识和文档节点按其交付标准审阅，不要求构建日志；知识搜集重点核对关键引用，不重做全库检索或要求所有阅读文件的哈希。报告只列结论和证据位置，不复制原始输出或已有哈希清单。按测试执行记录模板的证据复用规则核对当前版本及差异，原始日志与结果仍须可读取，不能只信上游 pass；复用结果不记为本次新执行。
+
+涉及代码检视时，列明检查范围、规则、问题位置和结论，可引用本节点的代码检视报告。白盒节点分别给出测试质量与算子功能结论：正确用例暴露算子缺陷时列出证据和下游修复要求，不宣称算子功能通过。
+
+## 问题与修改意见
+
+| 问题编号 | 严重程度 | 位置与证据 | 要求修正的内容 | 完成判据 |
+|----------|----------|------------|----------------|----------|
+
+无问题写“无”。失败时给出可执行的修改要求，不只写 fail；超出本节点授权范围的缺口明确记录，不要求执行者越权修改。
+
+## 最终结论
+
+- 本节点：{pass / fail；阻塞属于 fail，并说明依据}
+- 本阶段测试：{通过 / 不通过 / 本节点不适用；注明穿刺代表用例或正式全量范围}
+- 代码检视：{通过 / 不通过 / 本节点不适用}
+- 下游修复事项（仅已有流程允许时）：
+
+同节点重试时，执行者只读本报告；验收者核对当前产物版本，复用未变且仍有效的证据，仅复核受影响项并追加本次结论，保留此前问题与处理记录，旧通过结论不能批准新版本。
+
+确定性阻塞条件未变时注明条件与依据，维持失败；不要求执行者重复同一完整调查，也不把阻塞标为通过。

package/assets/ops-direct-invoke/skills/ops-direct-invoke/templates//351/273/221/347/233/222/346/265/213/350/257/225/350/256/276/350/256/241.md

@@ -0,0 +1,130 @@
+# {算子名称} 黑盒测试设计
+
+> 黑盒测试设计阶段产出。本仓采用 direct launch 工程架构。architect 依据已确认需求设计 golden、分级用例与覆盖矩阵，复用符合契约的测试资产并补齐覆盖缺口。
+> 本模板规定方案文档的格式与填写要求，覆盖维度分解、用例设计、精度口径及覆盖矩阵。
+
+## 1. 概述
+
+### 1.1 算子信息
+
+| 项目 | 内容 |
+|------|------|
+| 算子名称 | {算子名} |
+| 接口原型 | `{签名}` |
+| 支持数据类型 | {dtype 列表} |
+| 目标芯片/架构 | {芯片} / {archXX} |
+
+### 1.2 算子功能
+
+{一句话描述算子功能}
+
+## 2. Golden 对齐方案
+
+### 2.1 Golden 计算方案
+
+| 项目 | 内容 |
+|------|------|
+| golden 实现位置 | {现有或计划实现的文件路径、调用入口} |
+| Golden 计算路径 | {与需求数学定义一致，独立于被测 Kernel} |
+| 精度比对方式 | {逐元素 / 统计指标；具体判定指标与阈值填 2.3 口径表} |
+
+### 2.2 测试工程与执行入口
+
+| 项目 | 内容 |
+|------|------|
+| 用例文件 | {实际或计划交付的用例文件路径} |
+| 数据生成 | {输入生成入口、随机种子及预期输出生成方式} |
+| 测试入口 | {编译、运行和比对命令，包含全量用例和补充用例} |
+| 结果记录 | {用例计数、逐输出误差与判定的报告路径} |
+
+### 2.3 精度判定口径表（权威源对齐）
+
+> **本节记录精度判定的生效取值及权威来源，不得留「参考 XXX 标准」式引用**。逐**输出张量**填写：不同输出可能走不同口径（如整型输出按逐元素误差、浮点输出按相对误差统计量），不合并、不省略。逐项记录需求依据、指标定义和实际断言位置。
+>
+> 指标和阈值以已确认需求为准，逐项记录出处；资料或判定实现与需求冲突时记录差异及阻塞证据，不自行选取或放宽标准。
+
+| 输出张量 | dtype | 判定指标（公式或名称） | 阈值 | 权威源出处（文件路径 / 字段） | 实际 checker / 附加断言位置 |
+|----------|-------|------------------------|------|------------------------------|------------------|
+| | | | | | |
+
+**辅助交叉核对**（可选，不作通过依据）：
+
+| 输出张量 | 辅助容差（atol / rtol 等） | 用途 |
+|----------|---------------------------|------|
+| | | 交叉核对，与权威口径结论不一致时以权威口径为准 |
+
+**口径一致性声明**：{本地判定口径与权威源逐项一致 / 存在差异——逐条列出差异项、差异原因、风险评估，并明确该差异对当前验收的阻塞影响}
+
+## 3. 覆盖维度分解
+
+> 把每个输入/属性拆成正交因子，逐因子列出取值集，作为下方场景与用例的推导源与覆盖矩阵的行。
+
+### 3.1 参数因子表
+
+| 参数 | 因子（存在性/format/rank/dtype/取值域/长度/值） | 取值集 | 来源（需求文档条目） |
+|------|------|------|------|
+
+### 3.2 边界与特殊值清单
+
+> 按算子语义勾选适用项，删不适用带（如非负输入删负值）。
+
+- 数值边界：{ dtype min/max / 最小正规 / 次正规 }
+- shape 边界：{ 最小 shape [1] / 单元素 / 末维非对齐 / 空 tensor / 0 维 }
+- 特殊值：{ ±0 / +inf / -inf / nan }
+- 广播（如适用）：{ 等长 / 少维 / 多维 / 含 1 维 / 扩 1 轴 }
+
+## 4. 测试场景
+
+### 4.1 正常场景
+
+| 编号 | 场景描述 | 参数 |
+|------|----------|------|
+
+### 4.2 边界场景
+
+| 编号 | 场景描述 | 参数 |
+|------|----------|------|
+
+### 4.3 异常场景（参数校验）
+
+| 编号 | 异常输入 | 预期行为 |
+|------|----------|----------|
+
+### 4.4 特殊值场景
+
+| 编号 | 场景描述 | 参数 |
+|------|----------|------|
+
+## 5. 分级用例设计
+
+> L0 门槛（单因子最小覆盖，常规 shape/dtype，快，开发时验证）；L1 功能（离散因子 pairwise + 典型/竞品 shape）；L2 异常（每异常场景一条 + 空 tensor 派生）。逐项记录选值及其覆盖的需求维度。
+
+### 5.1 L0 门槛用例
+
+| 编号 | 描述 | 参数 | 预期结果 |
+|------|------|------|----------|
+
+### 5.2 L1 功能用例
+
+| 编号 | 描述 | 参数 | 预期结果 |
+|------|------|------|----------|
+
+### 5.3 L2 异常用例
+
+| 编号 | 描述 | 参数 | 预期结果 |
+|------|------|------|----------|
+
+## 6. 覆盖矩阵
+
+> 从需求独立枚举声明维度，与全部用例逐维对照，供 verifier 核对。不得留「任意 / 不限」式开放上界；覆盖缺口在补充用例列标注。
+
+| 声明维度（dtype / shape 范围 / 边界 / 特殊值 / 广播） | 取值 | 命中用例编号 | 是否命中 | 补充用例编号（未命中时） |
+|------|------|------|------|------|
+
+## 7. 汇总
+
+| 分级 | 用例数 |
+|------|--------|
+| L0 | |
+| L1 | |
+| L2 | |

package/assets/ops-direct-invoke/skills/ops-direct-invoke/workflows/ascendc/basic.yaml

@@ -0,0 +1,57 @@
+# 仅在路线明确或穿刺通过后启动。PM 下发 Skill、复用路径和预算；task 路径相对本文件。
+use_when: 一般算子开发任务
+workflow: ops-direct-invoke
+max_parallel: 2
+nodes:
+- id: '0.0'
+  yaml: ../../tasks/ascendc/知识搜集.yaml
+  depends_on: []
+  max_retries: 3
+  variables:
+    executor_skills: 无补充 Skill。
+    verifier_skills: 无补充 Skill。
+    research_focus: 重点搜集算子专项资料、目标芯片 API 组合和不同 shape 的初版 Tiling。
+- id: '0.1'
+  yaml: ../../tasks/ascendc/黑盒测试设计.yaml
+  depends_on: []
+  max_retries: 3
+- id: '1'
+  yaml: ../../tasks/ascendc/测试工程开发.yaml
+  depends_on:
+  - '0.0'
+  - '0.1'
+  max_retries: 3
+- id: '2'
+  yaml: ../../tasks/ascendc/算子开发.yaml
+  depends_on:
+  - '1'
+  max_retries: 3
+  variables:
+    executor_skills: |
+      候选 Skill（仅在实际证据命中时加载）：
+      - 自测或复现出现输出错误、精度不达标时，必须加载 `ascendc-precision-debug` Skill，按其中的要求执行。
+      - 自测或复现出现卡死、超时、崩溃或内存访问异常时，必须加载 `ascendc-crash-debug` Skill，按其中的要求执行。
+    verifier_skills: 无补充 Skill。
+    knowledge_documents: $WORK_DIR/0.0-知识搜集.md
+- id: '3'
+  yaml: ../../tasks/ascendc/白盒测试设计.yaml
+  depends_on:
+  - '2'
+  max_retries: 3
+- id: '4'
+  yaml: ../../tasks/ascendc/代码修复.yaml
+  depends_on:
+  - '3'
+  max_retries: 3
+  variables:
+    executor_skills: |
+      候选 Skill（仅在实际证据命中时加载）：
+      - 自测或复现出现输出错误、精度不达标时，必须加载 `ascendc-precision-debug` Skill，按其中的要求执行。
+      - 自测或复现出现卡死、超时、崩溃或内存访问异常时，必须加载 `ascendc-crash-debug` Skill，按其中的要求执行。
+    verifier_skills: 无补充 Skill。
+    repair_requirements: 根据本轮白盒测试设计节点的验收报告、测试执行记录与源码覆盖记录，修复暴露的算子代码缺陷；同步受影响的白盒用例，完成全量黑盒、白盒回归并提供证据供代码检视。没有待修复缺陷且当前版本已有有效全量证据时复用并记录依据，否则补齐验证。
+- id: '5'
+  yaml: ../../tasks/ascendc/文档准备.yaml
+  depends_on:
+  - '4'
+  max_retries: 3

package/assets/ops-direct-invoke/skills/ops-direct-invoke/workflows/ascendc/feasibility.yaml

@@ -0,0 +1,13 @@
+# 路线有关键疑点时先独立穿刺；PM 下发前具体化范围和 Skill 清单，退出后再编排正式开发。
+use_when: 快速验证方案有效性
+workflow: ops-direct-invoke
+max_parallel: 1
+nodes:
+- id: '0'
+  yaml: ../../tasks/ascendc/技术穿刺.yaml
+  depends_on: []
+  max_retries: 3
+  variables:
+    spike_scope: 在已确认需求的芯片、架构和精度约束下，用最小代表 shape 验证待开发算子的关键端到端组合；覆盖原始任务中列出的技术疑点，记录未验证范围。不改变已确认的单 Kernel 或数据驻留要求。
+    executor_skills: 无补充 Skill。
+    verifier_skills: 无补充 Skill。

package/assets/ops-direct-invoke/skills/ops-direct-invoke/workflows/cannbot-dsl/op-dev.graph-preview.yaml

@@ -0,0 +1,18 @@
+# 只供 workflow-graph 展示运行时生成的子图，不传给 harness。
+subgraphs:
+  implementation-loop:
+    title: 实现与检视 Agent Loop
+    runtime_file: $WORK_DIR/.workflow/implementation-tasks.yaml
+    summary: 按原生 Unit 与 TDD/Golden 逐步实现，并遵循 cannbot-dsl-best-practice 生产代码规范；集成或检视失败回到修复节点，通过后进入全量精度测试。
+    note: 这里展示生成规则。真实 implement-Uxx 节点数量与依赖由原生 units/Uxx.yaml、testcase.csv 确定；test-generator 执行阶段生成并校验 implementation-tasks.yaml，验收通过后调度子图。回滚次数由主工作流 max_rollbacks 限制。
+    stages:
+    - title: implement-Uxx × N
+      description: 每个节点绑定原生 units/Uxx.yaml、TDD case、<op>_golden.py 与允许修改范围；按 cannbot-dsl-best-practice 生产代码规范实现，微模块知识按需读取，重叠写集串行。
+    - title: 单元 Red → Green
+      description: 新增能力先确认可信 Red 再实现 Green；重试复用有效 Red，已有能力提供复用与当前验证证据，并执行任务要求的回归。
+    - title: implementation-fix
+      description: 首轮核对实现与测试清单；回滚时根据集成或检视报告修复代码，不改冻结设计、Golden、TDD 断言或精度阈值。
+    - title: unit-integration ↩ implementation-fix
+      description: 汇合全部 Unit，实现全量单元 TDD、Golden、白盒及必要黑盒回归；失败回滚到 implementation-fix。
+    - title: implementation-review ↩ implementation-fix
+      description: 检视实现及完整测试证据；发现问题回滚到 implementation-fix，复验通过后 Agent Loop 才完成并进入全量精度测试。

package/assets/ops-direct-invoke/skills/ops-direct-invoke/workflows/cannbot-dsl/op-dev.yaml

@@ -0,0 +1,142 @@
+# CANNBot-DSL 完整算子开发工作流
+use_when: CANNBotDSL 算子开发全流程（需求、规格、设计、TDD 实现、精度与性能验证、交付）
+workflow: op-dev
+max_parallel: 4
+max_rollbacks: 4
+nodes:
+- id: create-workspace
+  task_type: normal
+  yaml: ../../tasks/cannbot-dsl/创建工作区.yaml
+  depends_on: []
+  executor: ops-direct-invoke-developer
+  verifier: ops-direct-invoke-verifier
+  max_retries: 1
+  on_exhaust: exit
+- id: environment
+  task_type: normal
+  yaml: ../../tasks/cannbot-dsl/环境就绪.yaml
+  depends_on:
+  - create-workspace
+  executor: ops-direct-invoke-developer
+  verifier: ops-direct-invoke-verifier
+  max_retries: 2
+  on_exhaust: exit
+- id: requirements
+  task_type: normal
+  yaml: ../../tasks/cannbot-dsl/需求分析.yaml
+  depends_on:
+  - create-workspace
+  executor: ops-direct-invoke-architect
+  verifier: ops-direct-invoke-verifier
+  max_retries: 2
+  on_exhaust: exit
+- id: spec
+  task_type: normal
+  yaml: ../../tasks/cannbot-dsl/规格生成.yaml
+  depends_on:
+  - requirements
+  executor: ops-direct-invoke-architect
+  verifier: ops-direct-invoke-verifier
+  max_retries: 2
+  on_exhaust: exit
+- id: blackbox-design
+  task_type: normal
+  yaml: ../../tasks/cannbot-dsl/黑盒用例设计.yaml
+  depends_on:
+  - spec
+  executor: ops-direct-invoke-architect
+  verifier: ops-direct-invoke-verifier
+  max_retries: 2
+  on_exhaust: exit
+- id: solution-design
+  task_type: normal
+  yaml: ../../tasks/cannbot-dsl/方案设计.yaml
+  depends_on:
+  - spec
+  - environment
+  executor: ops-direct-invoke-architect
+  verifier: ops-direct-invoke-verifier
+  max_retries: 2
+  on_exhaust: exit
+- id: implementation-gate
+  task_type: normal
+  yaml: ../../tasks/cannbot-dsl/实现门禁.yaml
+  depends_on:
+  - solution-design
+  executor: ops-direct-invoke-architect
+  verifier: ops-direct-invoke-verifier
+  max_retries: 0
+  on_exhaust: exit
+- id: unit-planning
+  task_type: normal
+  yaml: ../../tasks/cannbot-dsl/单元任务拆分.yaml
+  depends_on:
+  - implementation-gate
+  executor: ops-direct-invoke-architect
+  verifier: ops-direct-invoke-verifier
+  max_retries: 2
+  on_exhaust: exit
+- id: test-generator
+  task_type: normal
+  yaml: ../../tasks/cannbot-dsl/测试生成.yaml
+  depends_on:
+  - implementation-gate
+  - unit-planning
+  - blackbox-design
+  executor: ops-direct-invoke-architect
+  verifier: ops-direct-invoke-verifier
+  max_retries: 2
+  on_exhaust: exit
+- id: implementation-loop
+  task_type: subgraph
+  file: .workflow/implementation-tasks.yaml
+  depends_on:
+  - test-generator
+- id: precision-validation
+  task_type: normal
+  yaml: ../../tasks/cannbot-dsl/精度验证.yaml
+  depends_on:
+  - implementation-loop
+  - blackbox-design
+  - test-generator
+  executor: ops-direct-invoke-developer
+  verifier: ops-direct-invoke-verifier
+  max_retries: 2
+  on_exhaust: exit
+- id: performance
+  task_type: normal
+  yaml: ../../tasks/cannbot-dsl/性能优化.yaml
+  depends_on:
+  - precision-validation
+  executor: ops-direct-invoke-developer
+  verifier: ops-direct-invoke-verifier
+  max_retries: 3
+  on_exhaust: exit
+- id: documentation
+  task_type: normal
+  yaml: ../../tasks/cannbot-dsl/文档生成.yaml
+  depends_on:
+  - performance
+  executor: ops-direct-invoke-developer
+  verifier: ops-direct-invoke-verifier
+  max_retries: 2
+  on_exhaust: exit
+- id: code-review
+  task_type: normal
+  yaml: ../../tasks/cannbot-dsl/代码检视.yaml
+  depends_on:
+  - documentation
+  - performance
+  executor: ops-direct-invoke-verifier
+  verifier: ops-direct-invoke-verifier
+  max_retries: 2
+  on_exhaust: exit
+- id: delivery
+  task_type: normal
+  yaml: ../../tasks/cannbot-dsl/交付.yaml
+  depends_on:
+  - code-review
+  executor: ops-direct-invoke-developer
+  verifier: ops-direct-invoke-verifier
+  max_retries: 1
+  on_exhaust: exit

package/assets/ops-direct-invoke/skills/ops-direct-invoke-maintain/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: ops-direct-invoke-maintain
+description: 维护 ops-direct-invoke 工作流的架构与设计思想。修改用户项目中的 AGENTS.md 或 CLAUDE.md 插件指引、客户端 agents 目录中的 ops-direct-invoke-* 角色、Skill 目录（.agents/skills/ 或客户端配置目录下的 skills/）中的 ops-direct-invoke、workflow-orchestrator 及本工作流关联 Skill、.cannbot/plugins/ops-direct-invoke/ 插件资产，以及维护 Skill 内的 test/、插件 README、QUICKSTART 等文档、安装与调度集成时，必须加载本 Skill。普通算子代码开发、任务产物和单轮工作流编排不触发。
+---
+
+# ops-direct-invoke 工作流维护
+
+## 工作区目录结构
+
+本文的“工作区”指用户当前任务所在的项目目录。以用户指定的项目路径和当前会话上下文定位，再结合项目指引文件与客户端配置目录中的 `cannbot-plugin.json` 安装记录确认；不要把 Skill 软链接指向的源码目录当作项目根目录。
+
+不同客户端使用不同的配置目录、角色格式和 Skill 路径。下面的 `<客户端配置目录>`、`<Skill目录>` 是布局占位符，不是实际目录名；具体位置以项目文件和安装记录为准：
+
+```text
+<工作区>/
+├── AGENTS.md 或 CLAUDE.md           # 最外层 Agent 的 PM 指引
+├── <Skill目录>/
+│   ├── ops-direct-invoke-maintain/  # 本维护 Skill
+│   ├── ops-direct-invoke/           # 流程入口、tasks、workflows、scripts、templates
+│   ├── workflow-orchestrator/       # harness 调度接口与执行能力
+│   ├── repo-*/                      # 仓库约定与工程能力
+│   └── <公共 Skill>/               # DSL、AscendC 等领域能力
+├── <客户端配置目录>/
+│   ├── agents/                     # ops-direct-invoke-* 子 Agent 角色配置
+│   └── cannbot-plugin.json          # 插件安装记录
+└── .cannbot/
+    ├── plugins/ops-direct-invoke/   # 角色原始文件等插件资产
+    ├── dependencies/ops-direct-invoke/ # 依赖仓库
+    └── <任务名>/workflow<序号>/     # 单轮输入、产物与运行状态
+```
+
+Skill 目录可能是 `.agents/skills/`，也可能是客户端配置目录下的 `skills/`；角色配置由安装器按客户端要求生成。安装记录列出插件的指引、角色、Skill 和资产路径，用它定位实际文件，不假定固定扩展名或单一客户端布局。源码安装时 Skill 目录可能是软链接，打包安装时则可能是副本。
+
+下文用 `AGENTS.md` 指代插件的 PM 指引设计；客户端使用其他入口文件名时，同样适用。
+
+## 整体架构
+
+各组件的职责如下：
+
+| 模块 | 职责 |
+|---|---|
+| 项目指引（`AGENTS.md` 或 `CLAUDE.md`） | 最外层 Agent 的 PM 入口，负责需求对齐、任务规划和交付组织 |
+| 子 Agent 角色 | 仅定义架构师、开发者、验收者的身份、职责与权限，不绑定具体 Skill |
+| `ops-direct-invoke` Skill | 算子开发流程入口，组织 task、workflow 模板及组装与启动脚本 |
+| `repo-*` 与公共 Skill | 提供仓库约定、工作方法和领域能力 |
+| harness / `workflow-orchestrator` | 下发子 Agent 任务并执行工作流 |
+| 维护 Skill 内的 `test/` | 工作流维护后的脚本与接口回归验证 |
+| `README.md` / `QUICKSTART.md` | README 介绍新特性、设计、功能和结构；QUICKSTART 介绍安装与使用 |
+| 安装与来源配置 | 将指引、角色和 Skill 安装到项目中，维护能力来源与路径映射 |
+
+## 基础设计思想
+
+- **PM 入口保持薄层。** 最外层 Agent 加载项目指引并承担需求对齐、规划和交付组织，具体工程工作交给子 Agent。
+- **工作区承接多种任务。** 完整算子开发只是其中一种。非算子开发需求由 PM 自由规划 Skill 和流程；算子开发需求必须加载 `ops-direct-invoke` Skill，严格按其要求组织。
+- **子 Agent 统一通过 harness 调度。** 无论任务类型如何，都不绕过 harness 直接拉起子 Agent。
+- **各层分工明确。** 角色定义职责与权限，Skill 提供工作方法，task 描述具体任务和交付契约，workflow 组织依赖关系，harness 负责执行调度。详细规则由对应模块维护，避免在 PM 入口重复展开。
+
+### 分层与依赖方向
+
+分层的目的是让组件可以独立理解、复用和替换。PM 组织任务，workflow 组织依赖，task 组合角色与能力，角色和 Skill 不依赖自己被哪个阶段、哪个调用方使用。仓内知识文档不承担 Agent 调度职责；同层组件通过公开契约合作，不依赖彼此的内部步骤。
+
+工作流依赖能力名称和输入输出契约，不依赖某份 Skill 的章节、内部资源布局或具体仓库实现。详细的单一职责、扩展与替换原则见 [repo-* Skills](reference/repo-skills.md)。维护 Skill 需要理解跨模块关系以判断变更影响，因此可以引用各层设计；这种跨层视野不应注入普通执行任务。
+
+### 约束应落在合适的机制中
+
+确定性的转换、输入检查和权限边界优先使用脚本、框架接口或客户端已有机制，避免仅靠 Agent 记住提示词。业务判断和设计理由由文档表达，不为难以机械判断的语义堆叠拦截器。harness 已提供的机制直接使用，不在工作流中重复实现或测试。
+
+原则用于保护职责和契约，不用于锁死实现。设计需要调整时，明确调整理由及对调用方的影响，同步相关模块资料；不要把旧版的文件名、挂载方式或检查清单当成永久限制。
+
+## 通用维护要求
+
+先检查相关 Skill 的软链接目标，并按需读取客户端配置目录中的 `cannbot-plugin.json` 确认插件归属和安装方式。源码安装下，编辑 Skill 链接中的文件会影响其源目录及使用该源码的其他工作区。
+
+项目指引文件的管理区块、客户端角色配置与插件资产是安装生成的文件，不等同于 Skill 软链接。维护可复用规则时定位其源文件和生成逻辑，不只修改安装副本；用户明确要求工作区局部调整时保留该范围。更新 PM 指引时保留管理区块之外的用户内容。安装记录用于定位，不靠手改记录完成同步。
+
+新增 Skill 或在 task 中引用新 Skill 时，按来源处理：
+
+- **外部 Skill**：必须在插件 `skills/` 下创建并提交指向对应仓库目录的相对软链接；已有链接不重复添加。
+- **插件内 Skill**：已经随本代码仓提供，由安装器发现插件 `skills/` 下的内容，不需要额外配置来源。
+
+外部注册路径按 `skillsRepository` 解析；两类 Skill 都须确认目录和 `SKILL.md` 存在，task 引用名称与元数据 `name` 一致，并实际安装到工作区。源码安装时核对链接及其目标有效，打包安装时核对复制的完整资源；不能以源仓存在文件代替工作区可加载的验证。
+
+修改 Skill 或角色名称、脚本参数、产物路径或文件格式时，检查生产方、消费方、安装配置、测试及文档是否需要同步。改变已有使用方式时说明影响和迁移办法；兼容性处理以实际使用需求为准，不为假设中的消费者添加额外机制。
+
+每次维护工作流都必须检查 `README.md` 与 `QUICKSTART.md` 是否与实际实现及彼此一致，按 [文档维护规范](reference/documentation.md) 完成检查并修订不一致之处。
+
+**每次修改工作流后，必须完整运行本 Skill 的 `test/ut/test_all.py`，确认未改坏已有脚本、参数处理和工作流接口。** 运行方式与测试边界见 [测试体系](reference/tests.md)；不能用单类通过或部分用例通过替代完整回归。
+
+**新增特性时，必须考虑是否需要新增测试。** 根据脚本行为和接口的回归风险决定，必要时补充最小用例；也可以向用户提出具体测试建议，说明要防止的问题及验证方式，避免为固定配置或提示词措辞增加无意义的看护。
+
+维护资料记录“为什么这样设计”和由此产生的职责边界、维护约束，不记录当前模板清单、固定数量或脚本实现现状。具体功能、参数和操作说明由 README、QUICKSTART 与实现维护，避免把实现现状固化为禁止重构的约束。
+
+完整回归入口（将路径替换为本 Skill 的实际位置）：
+
+```bash
+python3 /absolute/skills/ops-direct-invoke-maintain/test/ut/test_all.py
+```
+
+## 模块资料路由
+
+每份资料介绍一个完整模块的设计目的、职责边界和维护方法。按本次修改涉及的模块读取，不默认加载全部资料；跨模块修改时读取相关项。
+
+下表中的源码路径相对于插件目录 `plugins-official/ops-direct-invoke/`；工作区中的安装文件按安装记录与软链接映射回对应模块。
+
+| 模块及涉及的修改 | 详细资料 |
+|---|---|
+| `AGENTS.md`：PM 入口、职责边界与任务分流 | [PM 入口](reference/agents-entry.md) |
+| `agents/`：architect、developer、verifier 三个子 Agent 的职责、权限与协作 | [子 Agent](reference/subagents.md) |
+| `skills/ops-direct-invoke-maintain/test/`：维护回归、覆盖范围与完整运行方式 | [测试体系](reference/tests.md) |
+| `README.md`、`QUICKSTART.md`：文档分工与每次维护的一致性检查 | [文档](reference/documentation.md) |
+| `skills/ops-direct-invoke/`：算子流程分层、组装边界及围绕 harness 组织的设计目的 | [算子开发流程 Skill](reference/ops-direct-invoke.md) |
+| `ops-direct-invoke` 中的 task 组织、字段语义与可见性、执行与验收契约 | [Task 组织规范](reference/task-authoring.md) |
+| `skills/repo-*/`：父仓与子仓的同名覆盖、仓库知识分层及七个 Skill 的正交职责 | [repo-* Skills](reference/repo-skills.md) |
+
+尚未讨论的模块先保留框架，详细设计逐项补充。用户明确要求变更设计思想时，同步更新对应模块资料；新增模块时在此补充路由。Skill 注册等通用维护要求在入口统一维护，不单独划为模块。

package/assets/ops-direct-invoke/skills/ops-direct-invoke-maintain/reference/agents-entry.md

@@ -0,0 +1,23 @@
+# AGENTS.md：PM 入口
+
+## 工作区 Agent 的入口
+
+在工作区中启动 harness 工具时，最外层 Agent 加载 `AGENTS.md`，按照其中的约定承担 PM 职责：与用户对齐需求、规划任务、组织子 Agent 协作并汇总交付。
+
+`AGENTS.md` 保持为薄层入口，描述 PM 的通用工作方式；算子开发的具体流程由 `ops-direct-invoke` Skill 承担，不在入口重复维护。
+
+## 为什么先对齐需求，再静默执行
+
+用户应在需求对齐开始时知道还需参与问卷，并在对齐结束后明确知道可以离开。这样既避免实现阶段反复追问，也不把缺失需求变成未经确认的承诺。
+
+静默执行减少非必要交互和进度噪声，不改变权限、验收、重试预算和恢复边界。已确认范围内由 PM 自主推进；遇到无法在授权范围内解决的阻塞时，保留状态并集中说明需要的决定。用户没有回复不能自动视为接受需求变更或授权越界。
+
+## 为什么入口定制不能改变 PM 身份
+
+子仓可以补充本仓约束，但入口仍需保留需求对齐、任务分流、必须加载的能力和统一调度边界。否则同一工作流会随安装位置改变基本职责，子 Agent 和 Skill 的契约也会失去稳定前提。入口不承载仓库知识正文，也不通过定制让 PM 接管工程执行。
+
+## 维护方法
+
+修改 PM 指引时保留通用任务与算子开发的分流，只将通用职责、需求对齐、任务规划、执行与交付约定放在入口中。具体算子流程与能力绑定留在对应 Skill 和 task 中。
+
+不同客户端可能使用 `AGENTS.md` 或 `CLAUDE.md` 承载项目指引，以上设计同样适用。更新安装后的指引时保留插件管理区块之外的用户内容；涉及源文件与安装副本同步时，遵循 [入口中的通用维护要求](../SKILL.md#通用维护要求)。