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

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

@@ -0,0 +1,52 @@
+# README 与 QUICKSTART
+
+## 模块范围
+
+插件根目录的 `README.md` 和 `QUICKSTART.md`，以及它们引用的使用与设计资料。
+
+## 设计思想
+
+README 解释工作流的能力、设计和完整使用规则，QUICKSTART 提供最短上手路径，共同描述同一个实际可用的工作流，避免维护两套重复的操作说明。
+
+### README.md：新特性、设计与功能
+
+README 按以下顺序组织：
+
+1. **新特性**：放在文档最开头，即标题后的首个内容部分，介绍当前新增或有重要变化的能力及用户可见影响。只描述已实现的特性，不将规划写成已经支持。
+2. **设计思想**：说明工作流的目标、PM 与子 Agent 的分工、围绕 harness 的组织方式，以及仓库知识分层等核心设计。
+3. **支持的功能**：介绍适用场景、能力范围和实际限制，并提供 QUICKSTART 的入口。
+4. **结构组织**：放在靠后的位置，介绍目录、组件职责与相互关系，帮助维护者定位实现。
+
+完整安装参数、来源与版本策略、环境要求、定制、恢复及维护回归说明放在 README。首次安装的最短步骤链接到 QUICKSTART，避免复制两套教程。
+
+### QUICKSTART.md：安装与使用
+
+QUICKSTART 面向第一次使用工作流的人，按两类用户给出可直接执行的最短路径：
+
+- 普通用户：推荐在目标工作区用 npx 安装，无需克隆仓库。
+- 开发者：推荐克隆仓库后用 init 安装，并展示如何复用本地 cannbot-skills 仓。
+- 共用的启动命令、一个任务示例及结果位置。
+
+前提只列必需项，详细说明链接到 README。不要在快速入门中展开参数全集、SHA 与 dirty 规则、资产布局、恢复或回归操作。说明以实际支持的客户端与安装方式为准，不把某一个客户端的路径、文件格式或命令当成所有客户端的通用行为。
+
+## 为什么运行说明与设计理由分开
+
+执行任务需要的是能力入口、操作约定与交付要求，维护任务需要的是设计目的和变更边界。父仓、子仓、替换原则等架构解释放在 README 或维护资料中，不要求执行者为完成一个节点读完整套设计历史。
+
+Skill 入口保留必要的框架、基础概念和资料路由，细节按需加载；维护 Skill 的工作区结构与基础设计思想保留在入口，避免读者尚未建立概念就被要求跳转。触发条件写在元数据中，正文不重复说明何时加载。
+
+每条知识保留明确的权威来源，其他资料引用它而不是复制全文。开发者和 Agent 共享的仓库知识优先维护在仓内文档，具体分层见 [repo-* Skills](repo-skills.md)。示例只引入理解规则所需的背景，不让读者为了读懂示例额外调查无关领域。
+
+## 维护方法
+
+**每次维护工作流，都必须检查 README 与 QUICKSTART 的一致性，即使本次修改没有直接涉及文档。** 检查应结合本次变更及真实实现：
+
+- 两份文档是否存在，职责和内容顺序是否符合上述约定，交叉链接是否有效。
+- README 的新特性、支持功能和限制，是否与当前实现及 QUICKSTART 的使用方法一致。
+- 安装前提、客户端支持、命令参数、路径、Skill 和角色名称是否仍准确。
+- 工作流入口、节点组织、交付位置或恢复方式发生变化后，相关说明和示例是否同步。
+- 子仓同名 Skill 覆盖方式与实际安装行为是否一致。
+
+发现不一致时同步修订对应文档；检查后无需修改则保留原文，不为满足检查要求制造文档差异。新增用户可见能力时更新 README 开头的新特性说明，并在影响安装或使用时同步更新 QUICKSTART。
+
+文档中的支持声明必须有实现依据。命令或执行示例仅在实际验证后才能描述为已验证，不能把模拟执行、文档检查或启动成功写成完整功能验证通过。

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

@@ -0,0 +1,67 @@
+# ops-direct-invoke Skill 的设计思想
+
+## 为什么需要独立的算子流程入口
+
+PM 承接的工作不局限于完整算子开发，因此通用 PM 指引不应内置算子的全部流程。将算子开发规则集中在 `ops-direct-invoke` Skill，使 PM 在收到相应需求时才加载这些约束，也让流程演进不影响其他任务。
+
+入口负责指导 PM 将需求组织为可执行工作流，不代替子 Agent 完成任务，也不承担调度器的职责。
+
+## 为什么把任务内容与合作关系分开
+
+`tasks/` 表达单个节点要完成什么、如何产出和验收；`workflows/` 表达节点之间如何合作。一个任务可以被不同流程复用，同一流程也可以调整依赖和预算，而不必复制、改写整段任务提示词。
+
+维护时将节点的业务契约放在 task，将本轮合作关系放在 workflow。不要把某一张图中的顺序、节点编号或重试预算当成任务本身不可改变的属性。具体字段归属应遵循组装接口，但接口实现不应被当成永久设计限制。
+
+Skill 提供知识和方法，task 显式声明本节点所需能力。这样角色身份可以保持稳定，父仓的通用流程也能通过子仓的同名 Skill 适配不同工程环境。
+
+## 为什么在下发前组装完整 YAML
+
+可复用模板适合维护，完整任务定义适合执行。组装层负责把 task 引用、本轮参数和产物引用转成明确输入，让 harness 接收到自包含的节点定义，不需要理解业务模板体系。
+
+组装是确定性的转换，不替 PM 选择业务路线，也不根据模糊任务名称推断能力。错误输入应在下发前被发现，不能留下看似可执行的半成品。
+
+共享模板与单轮执行文件分开，使未来的模板修改不会改变已经启动或需要恢复的工作流。维护共享定义时保留已有运行记录；同轮恢复沿用原输入，新一轮使用独立目录并明确引用有效的前轮产物。
+
+## 为什么围绕 harness 组织，而不再写一套调度器
+
+本工作流负责“下发什么”，harness 负责“如何执行调度”。启动包装层只处理必要的参数和进程接口，不自行实现派发、重试、回滚、裁决或状态推进。
+
+这使业务流程可以演进，而无需维护两套互相竞争的状态机。维护时把 harness 当作可信依赖，通过公开接口使用它；回归测试检查我们是否改坏了输入和调用衔接，不重新证明框架内部机制正确。
+
+报告用于保存业务事实和证据，不能代替框架裁决，也不能通过修改报告或内部状态强行推进流程。
+
+## 为什么执行必须有界、可观测且可恢复
+
+自动执行的价值在于减少人工盯守，不能以无限重试换取表面上的自主性。可能循环的节点和多轮修复应有明确预算或停止条件；不能在预算耗尽后无条件新开一轮规避上限。无法继续时保留失败证据、阻塞点和已完成交付，向用户说明需要的决策。
+
+进度和恢复依据必须落在外部可追溯记录中，不能只存在于 PM 的上下文。调度状态与恢复使用 harness 的公开能力，业务事实由任务报告承载，不另建竞争的状态机。恢复复用已通过且仍有效的产物；仅对变化影响或证据失效的范围重新执行。
+
+PM 通过框架状态了解执行进度，按需读取阻塞证据，不在运行期间反复通读产物。这样既保持可观测性，也避免把静默执行变成持续消耗上下文的人工监工。
+
+## 为什么扩展必须有契约并保持基线独立
+
+附加流程应自带明确的输入、输出、完成条件、失败处理和有界执行约定，使扩展可以作为清晰的任务单元理解与复用。执行和验收仍须分离，不能因为是扩展就放宽交付要求。
+
+通用流程依赖扩展点的契约，不依赖某个具体扩展的内部实现；未启用扩展时，基线仍应独立完成其承诺的交付。启用扩展时明确接入位置、依赖和写入范围，出现顺序或资源冲突先解决歧义，不依靠隐含执行顺序。扩展输出必须满足后续任务的输入契约。
+
+这些原则用于指导能力扩展，不要求建立独立的插件注册、固定阶段挂载或额外调度机制；具体组合仍由 workflow 表达并交给 harness 执行。
+
+## 为什么支持动态实现子图
+
+算子实现应按实际设计拆分，而不是预设固定数量的开发节点。只有形成设计、实现单元和验证义务后，才有足够信息组织具体实现任务。
+
+动态子图把这些业务产物转换为同一 harness 能执行的节点图，既保留按任务拆分的灵活性，又不引入另一套执行循环。依赖应反映能力前提；并行任务的写入范围应避免冲突，无法确认独立性时不盲目并行。
+
+运行期生成子图应是主图明确声明的任务产物，不意味着 PM 可以随意改写已启动的流程。子图定义、业务报告和框架状态即使位于相邻目录，也应保持各自的写入边界。
+
+## 为什么将设计汇总和文档模板独立出来
+
+分文件设计便于按主题维护，部分消费者需要完整设计输入；汇总层解决表示形式差异，不应重新设计、补造事实或形成另一份独立维护的设计。
+
+文档模板统一交付格式，使证据容易被消费和验收。模板不负责调度，也不自行定义新的交付范围；由 task 明确产出者、路径和验收方法。避免在模板、task 与入口重复维护同一规则。
+
+## 维护约束
+
+修改时先判断影响的是知识、节点契约、合作关系、组装接口还是启动接口，再修改对应层。接口变化同时检查生产方与消费方，不靠下游猜测新格式。
+
+修改 task 的内容组织与验收边界时，阅读 [Task 组织规范](task-authoring.md)。具体可用模板、脚本名称、参数和目录清单由 README、QUICKSTART 及实际实现说明，不在这里固定。

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

@@ -0,0 +1,85 @@
+# repo-* Skills
+
+## 模块范围
+
+插件 `skills/` 下以 `repo-` 开头的七个 Skill，构成工作流面向具体算子仓的知识与工程能力层。task 通过稳定的 Skill 名称引用它们，实际内容由目标仓提供。
+
+## 设计思想：父仓与子仓的知识分层
+
+一些算子仓会把本工作流安装到自己的项目内。不同仓的构建、编码约束、领域背景和测试框架并不相同，不能要求所有仓使用同一套仓库知识，也不应为适配每个仓复制一套工作流。
+
+这里参考面向对象的“基类与子类”思想：
+
+- **父仓（基类仓）**：维护通用工作流、角色和 task，并提供默认的 `repo-*` Skill 实现。
+- **子仓（具体算子仓）**：复用工作流，以同名 Skill 替换默认实现，提供本仓知识与工程方法。
+- **稳定名称是能力接口**：task 仍引用 `repo-build-guide`、`repo-test-develop` 等名称；安装后的同名 Skill 决定这些任务如何适配当前仓库。
+
+这是能力契约和知识维护上的继承关系，不是 Git 仓库继承，也不是运行时自动合并两份 Skill 正文。同名替换后，以实际安装的 Skill 内容为准；子仓需要保留的默认内容由子仓显式维护，不能假设父仓规则会自动叠加。
+
+```text
+父仓：通用 workflow / task → 引用稳定的 repo-* 名称
+                                      ↓
+                  默认实现 或 子仓提供的同名实现
+                                      ↓
+                  当前算子仓的知识、构建与验证方法
+```
+
+父仓维护工作流机制，子仓维护本仓事实。子仓新增或调整本仓知识时，应落入对应 `repo-*` Skill，避免把仓库特例写回通用 task、PM 入口或公共领域 Skill。
+
+## 为什么采用 SOLID 原则
+
+| 原则 | 设计目的与维护边界 |
+|---|---|
+| 单一职责 | 每个 Skill 负责一个知识或工程能力域，使一种知识变化只需修改一个归属明确的位置。不要把编码红线、构建方法和测试方法混在一起。 |
+| 开闭原则 | 仓库差异通过同名能力扩展，避免每接入一个子仓就修改通用编排。通用流程自身的演进仍由父仓维护，不能借覆盖仓库知识改变调度和角色边界。 |
+| 里氏替换 | 子仓实现保持逻辑名称、职责和约定的输入输出，让调用方无需识别实际实现来自哪个仓库。替换不得悄悄删去调用方依赖的能力。 |
+| 接口隔离 | 子仓只覆盖需要定制的 Skill，其余沿用默认实现；不能为了替换一个 Skill，要求复制或重写整套能力。单个被替换 Skill 的内容仍须完整，不自动合并父仓正文。 |
+| 依赖倒置 | task 依赖抽象能力契约，不指定子仓 Skill 的章节结构、内部路径或实现方法，使不同仓库能独立维护。 |
+
+### 为什么兼容责任是双向的
+
+子仓替换不能破坏调用契约，父仓演进也不能随意破坏已接入子仓的覆盖实现。已发布的能力名称、输入输出与调用约定应保持兼容；扩展优先采用不改变旧含义的方式，新增可选配置应有明确默认行为。确需破坏性调整时说明受影响的调用方和子仓、提供迁移办法，不能让旧覆盖静默失效，也不为尚不存在的消费者预设兼容层。
+
+### 为什么知识需要单一来源
+
+仓库事实由仓库维护，Skill 负责帮助 Agent 定位和使用这些事实。开发者同样需要的编码规范、测试框架和领域说明，优先存放在仓内共享文档；Skill 引用权威原文并补充必要的任务指导，避免复制出第二套会独立过期的知识。
+
+仓库知识围绕自身职责组织，不写死调用角色、工作流阶段或前后节点。跨 Skill 的组合由 task 或 PM 声明；引用仓内资料不意味着把其他 Skill 的内部规则复制进来。
+
+## 仓库能力的正交职责
+
+| Skill | 设计目的与应包含的内容 | 职责边界 |
+|---|---|---|
+| `repo-build-guide` | 介绍当前仓库的编译框架：如何从源码、配置和依赖构建出所需产物，构建入口、目标、产物位置与使用方式 | 环境前提归 `repo-env-check`；测试接入、用例执行和验证充分性归 `repo-test-develop` |
+| `repo-coding-rules` | 介绍仅本仓持有的特殊编码规范，一般以红线条款呈现，明确禁止或必须遵守的仓库约束 | 不复制通用语言规范、领域知识或构建测试流程 |
+| `repo-env-check` | 介绍本仓开发所依赖的环境，以及如何确认环境具备开发条件，例如工具链、依赖、设备与必要配置 | 环境可用不代表产物构建成功，更不代表算子功能已通过测试 |
+| `repo-knowledge` | 介绍本仓特殊的领域背景、术语、标准与语义约束，为理解需求和实现提供依据 | 解释“本仓业务是什么、为何如此”，不承担编译命令、编码红线或测试框架操作说明 |
+| `repo-op-templates` | 提供本仓新增一个算子所需交付件的模板和组织方式，为从零开发提供参考 | 模板展示交付件形态；如何构建、接入和验证分别由对应 Skill 说明，不在此复制整套流程 |
+| `repo-requirement` | 引导 PM 对齐需求，一般用 checklist 提示应确认的接口、范围、约束和交付标准 | 负责把需求问清楚，不替用户决定未确认事项，不代做方案设计或执行验证 |
+| `repo-test-develop` | 介绍本仓算子测试框架：用例如何编写、接入和执行，算子代码变更后需要哪些验证及证据，才能证明变更已得到完整验证 | 构建产物的方法归 `repo-build-guide`；本 Skill 负责测试覆盖、回归范围和验证充分性，不能将构建成功等同于验证完成 |
+
+这里的“templates”对应实际 Skill 名称 `repo-op-templates`，不等同于 `ops-direct-invoke/templates/` 下的工作流报告格式模板。
+
+例如，BLAS 算子仓涉及标准语义：标准背景与仓库约定应归入该仓的 `repo-knowledge`，而不是散落在构建、编码和测试说明中。
+
+## 维护方法
+
+### 判断知识归属
+
+先判断改动属于通用工作流机制、跨仓领域能力，还是当前仓库事实。当前仓库事实按上表落到唯一负责的 `repo-*` Skill；多个 Skill 使用同一事实时，保留明确的归属，不复制成多套独立规则。需要组合多个 Skill 的任务，由 PM 或 task 显式绑定。
+
+新增条款时检查是否侵入其他 Skill 的职责。例如，测试执行命令与回归覆盖要求不应同时维护在 build-guide 和 test-develop 中；领域标准的背景不应混入 coding-rules 的仓库红线。
+
+### 同名替换与安装
+
+同名替换保留 task 面向的能力接口，同时改变知识来源。子仓实现应保留对应名称，并提供完整说明及所需资源，不能只写一段补丁并假定未提供的内容会自动从父仓继承。具体安装参数见 [README](../../../README.md#工作区资产与定制)。
+
+覆盖后核对实际安装路径、软链接或副本指向子仓实现，且 task 引用的名称仍可解析。保留能力契约：例如 build-guide 仍说明如何构建产物，test-develop 仍给出测试接入与完整验证方法。具体路径、命令和框架可以因仓而异；与 task 约定的输入输出不兼容时，必须显式处理，不能靠同名掩盖缺失能力。
+
+子仓局部知识调整不应直接改动指向父仓源码的软链接目标，以免影响其他工作区；应维护子仓自己的实现并通过安装覆盖机制选用。新增 Skill 或在 task 中引入新的 Skill 名称时，仍遵循入口中外部来源注册与插件内自动发现的规则，并确认工作区实际可加载。同名替换已有 Skill 无需重复创建同名注册项。
+
+### 验证与同步
+
+修改后按该 Skill 的实际职责验证：构建指南核对构建入口与产物，模板核对交付件结构，测试指南核对接入、执行及回归证据要求，需求 checklist 核对信息是否足以支持后续规划。不能仅凭文档可读取就认定能力适配完成。
+
+若改动涉及稳定名称或输入输出契约，同步检查 task、workflow 及其他消费者；若只是子仓内部实现变化且契约不变，保持通用工作流不受影响。

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

@@ -0,0 +1,43 @@
+# 子 Agent：身份层
+
+## 模块范围
+
+插件 `agents/` 下的三个角色定义，以及安装器为不同客户端生成的对应角色配置。角色职责与 `AGENTS.md` 中的介绍保持一致。
+
+## 设计思想
+
+子 Agent 只承担身份层：定义“我是谁、负责哪类工作、有哪些权限边界”。领域知识和工作方法由 Skill 提供，当前任务的输入、输出和验收要求由 task 声明。
+
+| Agent | 职责 | 典型交付件 |
+|---|---|---|
+| `ops-direct-invoke-architect` | 负责所有规划、探索类工作 | 设计文档或探索报告 |
+| `ops-direct-invoke-developer` | 负责代码开发、功能验证等需要具体执行的工作 | 具体代码或执行结果 |
+| `ops-direct-invoke-verifier` | 负责所有验收类工作 | 通过或不通过的结论，可附被验收内容的修改意见 |
+
+这些角色按工作性质划分，不按某个算子、开发语言、仓库或固定流程阶段划分。同一身份可承担不同业务任务，所需知识随 task 选择的 Skill 变化。
+
+### 身份与知识分离
+
+- 角色文件不绑定具体 Skill，不维护必读 Skill 清单，也不嵌入领域知识、仓库规范或具体操作教程。
+- PM 或 task 根据实际任务显式组合 Skill；执行者使用的能力写在执行提示词中，验收者使用的能力写在验收提示词中，遵循 task 的字段可见性边界。
+- 修改知识或工作方法时维护对应 Skill；修改角色的职责、权限和通用行为边界时才维护角色文件。
+
+角色层不负责流程编排或派发其他 Agent。PM 组织任务，harness 负责实际调度；子 Agent 在当前任务及角色边界内工作。
+
+### 执行与验收的分工
+
+developer 负责实际功能验证、性能测量等执行工作并交付完整证据；verifier 负责独立审查和裁决，不重复运行同一批用例，也不以执行者自述代替证据。证据不足时指出缺口并退回执行节点处理。具体 task 的证据与复用约定见 [Task 组织规范](task-authoring.md#6-执行产生证据验收独立审查不重复执行)。
+
+### 为什么执行与验收必须是不同实例
+
+同一个实例容易沿用自己的实现假设，把自检结论当成验收依据。执行者与验收者应由不同 Agent 实例承担，验收职责由 verifier 承担；只切换称呼或要求执行者再读一遍产物不能形成独立验收。实例隔离由 harness 调度实现，工作流使用该能力，不另行看护框架内部机制。
+
+独立实例通过交付契约和证据协作，无需了解对方的内部思考或完整上下文。独立性要求的是独立判断，不要求重复执行昂贵的测试。
+
+## 维护方法
+
+1. 修改角色时，对照 `AGENTS.md` 核对三类职责与典型交付件，避免出现两套不同的角色定义。
+2. 检查新增内容是否属于身份层：通用职责和权限可以保留；具体 Skill 名称绑定、领域规则及操作步骤应放回 task 或 Skill，不随角色常驻加载。
+3. 不因新增工作阶段就新增角色或将现有角色固定在该阶段；按规划探索、具体执行、验收的工作性质选择已有身份。
+4. 角色名称是 task 与客户端配置之间的引用契约。修改名称时同步核对 task、workflow、动态子图生成器和安装声明，确保实际客户端能加载对应角色。
+5. 修改角色源文件后，核对安装生成的配置是否同步。客户端格式可以不同，但身份、职责和权限语义应一致；遵循入口中的安装副本维护要求。

package/assets/ops-direct-invoke/skills/ops-direct-invoke-maintain/reference/task-authoring.md

@@ -0,0 +1,83 @@
+# Task 组织与节点字段规范
+
+## 字段语义与可见性
+
+| YAML 字段 | 含义 | 执行者可见 | 验收者可见 |
+|---|---|---|---|
+| `goal` | 本节点的总体目标 | 是 | 是 |
+| `approach` | 执行者的执行方法 | 是 | 否 |
+| `procedure` | 验收者的验收方法 | 否 | 是 |
+| `acceptance` | 双方共同确认的交付件清单 | 是 | 是 |
+| `out_of_scope` | 本节点禁止的操作 | 是 | 是 |
+
+可见性是硬边界：`approach` 只下发给执行者，`procedure` 只下发给验收者。双方都需要的信息只能写在 `goal`、`acceptance`、`out_of_scope` 中，并遵循各字段语义；写在对方不可见字段里的约定等于不存在。
+
+## 为什么只下发必要信息和权限
+
+节点应获得完成本任务所需的输入、相关约束、Skill 和证据路径，避免把整段会话、其他算子信息或无关全局上下文注入任务。最小信息不等于缺少契约：双方需要的约定必须在共享字段中完整表达。
+
+写入范围和操作权限以任务需要为限，避免无关代码、上游交付件和调度状态被误改。权限应结合具体任务配置，不能把“开发者不得修改测试”之类的阶段特例写成身份层的永久限制。
+
+每个节点有明确交付件和可判定的完成标准，使下游不必猜测任务是否完成。交付件放在 `acceptance`，内容判定放在 `procedure`，不为可观测性重复注入对方不可见的内部方法。
+
+## 1. 无条件信任上游产物，不做重复校验
+
+上游交付件在流入本节点前已由上游节点的验收者验收通过。本节点直接使用，不对其内容重新校验；使用前只确认产物存在且可读取。若使用中发现上游产物缺陷，按第 3 条就地终止并说明，不在本节点补做上游的验收工作。
+
+## 2. goal 只写目标，保持简短
+
+`goal` 只回答“本节点要达成什么”。不写执行方法、交付件清单或验收标准，它们分别属于 `approach`、`acceptance` 和 `procedure`。
+
+自检方法：`goal` 中一旦出现具体步骤、文件名或判定条件，说明写多了，应移入对应字段。
+
+## 3. 问题就地解决或就地终止，不得后移
+
+本节点发现的问题（输入缺陷、环境阻塞、能力缺失）由本节点闭环：能解决的当节点解决并记录证据；无法解决的按执行协议终止本节点，将证据写入本节点报告。禁止绕过问题继续交付，禁止把问题留给下游节点处理。
+
+### 就地处理不能越过上游决策边界
+
+上游设计可能包含当前节点未持有的约束，因此本节点可以复现问题、缩小范围并给出根因证据，但不能擅自改动已确认的架构、接口或实现策略。就地解决仅限当前任务及权限范围；需要改变上游决策时终止本节点并报告，由 PM 通过 harness 安排负责该决策的角色处理，不带着已知缺陷继续向下游交付。
+
+## 4. acceptance 只列交付件和存在性检查
+
+`acceptance` 是执行者与验收者共同接受的交付件契约。为防止重复验收，只写交付件清单及其存在性检查，每条给出可直接执行的测试指令，例如：
+
+```bash
+test -s "$WORK_DIR/{{id}}-测试执行记录.md"
+```
+
+不写内容正确性、质量标准、检查步骤或异常处理。
+
+## 5. 内容验收方法只写在 procedure
+
+交付件内容是否正确、质量是否达标，其检查方法、判定依据和不合格处理全部写在 `procedure`，由验收者独立执行。`acceptance` 与 `procedure` 不得描述同一项检查。
+
+## 6. 执行产生证据，验收独立审查，不重复执行
+
+`approach` 描述执行者如何产出交付件。功能验证、性能测试和环境探测本身可以是执行任务：执行者实际运行这些工作，交付代码、原始记录及结果报告，但不替验收者裁决自己的交付件是否满足要求。不要按“检查”“验证”等词机械划分字段，应区分实际执行与验收裁决。
+
+`procedure` 描述验收者如何独立审查交付件及证据。独立验收不等于重复运行：尤其对耗时的性能用例，不要求 developer 和 verifier 各跑一遍。verifier 检查测试代码、执行记录和报告的真实性、完整性、相互一致性及与当前实现版本的对应关系，再按任务标准给出结论，不能只接受执行者的“通过”自述。
+
+### 执行证据与复用边界
+
+- 执行者交付完整的测试或性能用例代码、运行命令与参数、环境信息、实现及用例版本、退出码、逐例原始结果和汇总报告。证据按任务所需记录，每次执行的原始资料保留一份，报告引用其路径，不重复抄录。
+- 验收者检查用例是否实际测量了目标行为、是否覆盖约定范围，报告能否追溯到原始结果，是否存在跳过、缺失、版本不符、相互矛盾或疑似伪造的证据。根据原始结果核对指标与判定依据，不重复跑同一批构建、测试或性能测量。
+- 证据足够支撑判定时直接验收；证据不足、可信性无法确认或结果不满足要求时不通过，指出需要补充或修复的具体内容，交回执行节点处理。verifier 不通过自己重跑来替执行者补交付件。
+- 补充证据不等于全量重跑。仍有效的代码和记录继续复用；只有相关实现、输入、用例或环境变化使原证据失效，或者必要证据缺失时，才由执行者完成所需范围的重新执行。
+
+两者职责是“执行并提供可审查证据”与“审查证据并独立裁决”。无需重复执行不能成为降低证据要求的理由；未真实执行的工作不得写成已验证。
+
+## 边界对照示例
+
+| 字段 | 错误写法 | 正确写法 |
+|---|---|---|
+| `goal` | 生成 `$WORK_DIR/spec.yaml` 并通过 12 项校验 | 将已确认需求转换为结构化算子规格 |
+| `approach` | 执行性能用例后自行认定已通过验收 | 执行性能用例，保存代码、参数、版本、逐例原始结果和报告 |
+| `acceptance` | `spec.yaml` 覆盖全部接口、无 TODO、校验返回 0 | `test -s "$WORK_DIR/spec.yaml"` |
+| `procedure` | 把 developer 已执行的整批性能用例再跑一遍 | 审查用例代码及执行证据，核对真实性、完整性、版本对应关系和性能指标；不足时退回补齐 |
+
+## 维护检查
+
+修改 task 提示词或组装逻辑时，分别从执行者和验收者实际可见的字段检查约定是否完整，再逐项核对上述六条规则。重点检查是否重复验收上游、把内容质量要求放进 `acceptance`、把验收动作放进 `approach`，或将本节点问题后移。
+
+组装后的节点仍须保留字段语义与可见性边界，不能通过合并提示词把 `approach` 和 `procedure` 同时下发给双方。

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

@@ -0,0 +1,33 @@
+# 工作流维护回归的设计思想
+
+## 为什么需要这批测试
+
+工作流维护不仅改变提示词，也可能改变脚本、参数、路径和生成文件。完整回归用于发现这次修改是否破坏原本可用的行为，使维护者不必依赖人工重新走完整个算子开发流程。
+
+测试随维护 Skill 分发，使维护者在源仓或安装后的工作区都能使用同一批验证。每次工作流改动后必须完整运行，不能用单类或部分用例通过代表整体通过。
+
+## 为什么只看护工作流自身
+
+harness 是可信依赖。测试应该检查我们的模板能否被发现、引用和参数能否正确转换、生成内容是否完整、启动接口有没有传错，以及已有文件是否受到保护。
+
+保留必要的接口贯通验证，是为了发现我们与 harness 的衔接被改坏，不是重新证明其调度、重试、回滚或裁决反馈机制正确。不依赖内部状态断言，也不为同一个框架机制在插件中再维护一套测试。
+
+## 为什么不锁死流程现状
+
+模板数量、节点数量与业务顺序、角色分配、Skill 选择、重试预算和提示词措辞都可能合理变化。复制当前配置作为固定预期，只会迫使维护者同时修改实现与快照，不能证明行为正确。
+
+优先用小型、独立的输入检验稳定契约，例如参数是否原样传递、变量是否串节点、产物引用是否正确展开。测试应在行为被错误改动时失败，而非在合法重构时失败。
+
+## 为什么需要区分验证结论
+
+脚本回归通过证明转换与接口行为得到检查，不证明真实模型遵守提示词，也不证明设备上的算子功能或性能达标。使用替身或模拟执行时保持这一结论边界，不把维护测试包装成真实业务验收。
+
+测试不应污染工作区、修改共享模板或留下运行状态；临时产物与实际用户任务分开。完整入口应覆盖所有测试分类，避免存在必须靠维护者记忆手动补跑的文件。
+
+## 如何维护这批验证
+
+新增特性时，评估是否引入新的参数、转换、文件操作或调用分支；有真实回归风险就补充最小可复现用例。纯文字调整或可变配置不机械增加断言。需要真实设备或模型验证时，向用户提出具体建议并说明自动回归不能覆盖的部分。
+
+测试失败时定位原因：错误改动应修复，合法接口变化应同步更新相应测试，不通过跳过失败用例得到通过结论。修复后完整重跑并报告结果。
+
+运行命令统一见 [维护入口](../SKILL.md#通用维护要求)；环境准备和其他安装布局的使用方式见插件 [README](../../../README.md#维护与验证)，不在设计资料中维护另一份操作手册。