Verifier State Architect

Verifier-State Architect

目标

为任意领域的目标 Skill 完成业务理解、最小设计、本地实现和验证。Verifier/State 是可插拔外挂，不为展示 Kernel 强行加入；零组件或仅一类组件也可以是正确结果。适合专用组件的新建、现有组件接入与精简，以及已有设计的落实。

默认是设计者兼执行者：人类把目标 Skill 交给本技能后，先保存供 AI 执行、人类事后审查的计划，再连续落地，不等待人类审核计划。仅当用户明确要求“仅计划 / 不修改源码”或只读审查时，分别采用 plan-only / review-only。不负责普通业务重写、Kernel 修复或提升通用组件、发布及远程操作；这些范围只能另行授权，不能作为默认执行的延伸。

流程

输入

输入与模式

• 必需输入：目标 Skill 源目录或完整内容、业务目标和已知约束。执行模式需要可写、已授权的源码目录；只有文本时可以设计，但不能假装已经落地，也不擅自创建未知目标。
• 可选输入：已有计划、Kernel 源码/安装路径、runtime 声明、Pack、测试、历史报告和计划路径。读取 config.yaml 获取默认模式、输出和检查设置。
• 确认目标是开发源码而非系统级已安装副本；记录未提交改动和允许修改范围。用户指定目标并要求本技能设计/接入，默认授权其必要本地变更，不需要第二次计划审批；纯审查或明确只规划不授权源码写入。
• 已有计划先核对当前源码、版本、范围和验收，局部更新偏差后实施，不无理由重做整套规划。模式、依据与未解决缺口写入计划。

执行步骤

核心工作流

理解服务对象

读取目标 SKILL.md、config.yaml、脚本、references、模板、运行声明和适用项目指令；绘制目标、输入/输出、阶段、风险、失败/回退、人工介入和产物。从证据列出稳定命题的 Verifier 候选与持续阶段的 State 候选，不从文件名或关键词臆测。执行前必读本 Skill 的 托管规范 和 落地参考：前者是托管规则的唯一维护文件，后者仅提供操作指引。在本仓库按需核对 ID 文档与正文模板；仓库外使用随 Skill 安装的规范和实际 Kernel 契约，不依赖本开发仓库的绝对路径。

删除影响闸门

逐项回答：

• 删除 Verifier 是否损失可复核的安全/质量边界，而非只少形式检查？
• 删除 State 是否损失恢复、协作、Gate 或阶段可见性，而非只少标签？
• 组件是否改变下一步决策、阻止高代价错误、支持重放/审计或提供可行动的人工复核？
• 是否已有更通用的内置 Pack/State？只有通用组件无法表达稳定命题时才设计专用组件。

若删除不改变能力、决策或审计性，明确“不接入”；零组件或只保留一个均合法。

Kernel 复用与元组件二层审查

在专用设计前完成以下盘点，避免重复造轮子，也不默认新增 Kernel 功能：

1. 从用户提供的 Kernel 源码或当前 Python 环境定位实际包；本仓库源码位于 packages/bensz-skill-kernel/src/bensz_skill_kernel。读取其 verifiers/index.json、states/index.json、对应契约、README 和版本声明；记录 canonical ID、版本、classification/kind、输入契约、入口及限制，不能只看名称/标签。源码与安装版本不同则明确选择并固定验证环境，不混用。
2. 为每个候选标记“直接复用 / 组合复用 / 适配后复用 / 不适用”，比较语义、输入/证据契约、Gate/转移、资源边界、版本兼容和失败路径；事实结构相同而仅词汇不同，优先适配器。
3. 检查是否有可在两个及以上不相邻领域复用、领域无关、契约稳定、可独立版本化和可回放的能力。Verifier 要能用 subject/context/evidence 表达稳定命题；State 要表达跨 Skill 的持续阶段/生命周期，而非动作、标签或一次性 helper。
4. 依赖领域规则、模型偏好、易变阈值、特定格式或单一 Skill 偶然流程的候选，留在 Skill/适配器层；证据不足时标为“待验证的 Kernel 提炼候选”。Kernel 建议只写入计划（范围、契约、兼容/迁移、测试、风险），不直接改 Kernel。
5. 最终计划必须单独列出“Kernel 复用结论”和“Kernel 元组件提炼结论”。无论复用、适配、暂不复用、推荐提炼还是明确不提炼，每项至少用 2 个项目符号说明证据、收益/代价和边界理由；证据不足还要列缺口与验证动作。

AI 与确定性分工

为每个设计项写一行分工：

• 确定性：JSON/Markdown 结构、路径、哈希、存在性、超时、结果枚举、事件完整性等机械边界。
• AI/自然语言：业务语义、质量充分性、相关性、风险解释、冲突处理和下一步规划；结果带理由、证据锚点、置信度及 uncertain/unchecked 路径。
• 混合：脚本只收集/规范化事实，AI 按 VERIFIER.md 与 Evidence Contract 判断；脚本不得编码领域结论。

逐条追问硬编码规则是否稳定、跨模型可复现且能安全 fail-closed；否则改为自然语言契约、证据字段和人工复核条件。语义 Verifier 至少定义 subject、context、evidence、verdict、summary、evidence_refs、confidence、uncertainties；verdict 只用 Kernel 枚举，证据不足/网络不可观测返回 uncertain/unchecked，不得把模型自评当 pass。

Kernel 对接

计划必须说明：

• Verifier 用 owner.domain.capability、State 用 owner.machine.state；版本和 alias 独立维护，不把 Skill 名、模型、实现或 Gate 策略写入 ID。
• Pack 的 VERIFIER.md/STATE.md 负责判断目标、入口条件、不变量、证据边界和转移；集合根的 index.json 是元数据单一来源。脚本组件使用 JSON-stdio，入口留在 Pack 内；Agent/人工组件使用宿主 handoff 和绑定结果回传，不强行配脚本。
• Kernel 只负责发现、协议校验、超时/资源边界、结果归一化、Gate、事件和状态持久化；领域判断留在 Skill 契约或 AI 适配器。
• required/advisory、Gate 放行条件、uncertain/unchecked 人工复核去向、run_id/attempt_id、失败/恢复和事件重放策略。
• 无 Verifier 时将 Gate 写为“不适用/无需验证”，无 State 时说明由普通流程和工作区生命周期承担；接入时 required 缺失必须 fail-closed，advisory 只提示不阻塞。
• 状态图只保留稳定业务节点；动作放入 transition/event/helper；系统工作区状态与 Skill 领域状态分层，不把领域状态硬编码进 Kernel reducer。
• 外部路径、网络、子进程和大输入采用最小权限、超时、体积上限及越界拒绝；入口禁止 ..、绝对路径和 symlink 逃逸。

附“Kernel 复用与提炼决策表”：候选能力、现有 Kernel ID/版本、复用方式、契约差异、是否跨领域、提炼建议、主要理由、验证动作；表格须与两个结论互相引用。

最小设计

使用矩阵：

给出最小状态图（初始、主要阶段、终止/失败、可选回退）和 Verifier 清单；每项写“为什么不可删除”，否则删除或降级为普通说明。

“Kernel 复用与元 Verifier/State 提炼决策”必须包含：

• 现有 Kernel 能力盘点：实际读取的索引/契约及其对应候选。
• Kernel 复用结论：直接、组合、适配或不适用；每项至少两条理由，含契约匹配度及失败/维护成本。
• 元组件提炼结论：推荐、暂缓验证或明确不提炼；每项至少两条理由，含跨领域证据、稳定性、版本化收益及领域耦合风险。
• 对人类决策的影响：采纳/不采纳建议会改变的文件、兼容性、测试、迁移成本和维护责任。

两类结论即使均为“不复用/不提炼”也必须保留并分点说明。计划在目标源码修改前落盘：P0 为安全/完整性/不可恢复错误，P1 为契约/可观测性，P2 为可选改进；每项含文件位置、证据、影响、验证命令、完成条件及回退办法。不把计划生成当成执行模式的完成条件，也不增加“请确认计划后继续”的关卡。

连续落地

plan-only / review-only 在设计/审查结果形成后结束，不写目标源码；implement 紧接计划执行：

1. 按落地参考创建实际使用的 references/verifiers/、references/states/ 集合及索引、契约、必要组件；专用资产随目标 Skill 托管，不写进 Kernel 内置目录。不批量迁移不相关历史资产，不覆盖用户未确认的冲突改动。
2. 在目标 config.yaml 接入真实支持的 runtime 声明；在 SKILL.md 的 ## 控制 说明调用时机、证据、Gate、迁移、失败恢复及人工介入。连接实际业务入口/宿主，而非仅生成孤立文件。只用 Verifier 时不要为通过声明加载硬造无用 State。
3. 机械工作由脚本执行，语义检查由宿主执行并回传证据；required 缺证据不放行。业务本身需要人工判断与“人工审批设计计划”不是一回事，不因默认连续实施而删除前者。
4. 同步目标 Skill 版本、使用文档、变更记录及适用的 BAC；版本只在 config.yaml 维护，Pack 版本在索引中独立维护。保留 canonical/alias 兼容，不改历史事件。
5. 运行只读托管检查和最短真实执行验证；检查复制后的资产发现、错误/缺证据、状态迁移及适用的重放。对照计划逐项记录完成、偏差、不适用和受阻项，再交付。零组件结论需给出删除影响证据，无需生成空目录、无意义 runtime 或虚假执行记录。

输出

输入、输出与工作区

• 执行交付：目标 Skill 中可发现、可调用的组件及接入改动，或有依据的零组件结论；附实际验证、未执行项和剩余风险。
• 可审查计划：项目 docs/plans/{skill-name}-verifier-state-design.md，或用户指定路径。它是流程中间步骤，但持续保留供事后审查；已有文件不是本任务所有时使用不冲突名称，不覆盖。
• 交付对账：计划项 → 修改文件/契约 → 命令或宿主证据 → 结果；明确区分“结构可加载”“实际已执行”“业务语义已验证”。
• 引用用相对路径和行号/标题锚点，日志只写脱敏摘要。复用会话已声明任务根，否则先确认根目录、时间与冲突，公开声明唯一目录后再创建；不依赖 BSK 才能初始化普通工作区。

计划固定结构

# Verifier/State 设计计划：<skill>
## 结论摘要
## 业务流程与风险地图
## 删除影响测试（含“不接入”结论）
## Verifier 设计矩阵
## State 设计矩阵与最小状态图
## AI/确定性分工与 Evidence Contract
## Kernel 对接、Gate、重放与资源边界
## Kernel 复用与元 Verifier/State 提炼决策
## 实施顺序（P0/P1/P2）
## 验收与回归测试
## 已知不确定性、回退方案和不在范围内的事项

输出管理

计划与证据边界

• 计划固定写入项目 docs/plans/ 或用户指定路径；草稿、读取清单和验证日志才写入任务目录。只读且仅需文本的审查可以不落盘。
• 读取清单、决策依据、机器可读摘要和日志写入当前会话已声明任务根目录的 verifier-state-architect/input|output|log/；不把正式计划藏在任务目录中。
• 专用 Pack 源码写入目标 Skill 的标准目录；运行证据、快照、日志、缓存和夹具不得进入发布资产。复制安装验证使用项目临时目录，不覆盖系统级安装副本。

校验

验收与回归测试

• 执行 python3 <本Skill>/scripts/check_integration.py <目标Skill>，需要 Python 3.11+、PyYAML 和与目标声明匹配的 BSK；可从任意工作目录运行。该工具只读取文件、调用加载器，不执行目标组件。报告输出至 stdout，可重定向至任务 output/verification-report.json。
• 工具只证明托管及静态加载，不替代契约语义、组件执行、Gate、恢复/重放和版本迁移验证。具体用例及宿主边界见落地参考；unchecked 不能写成完成。
• 只规划/审查时仅检查可获得证据，不创建实现来凑测试；无组件时登记“不适用”。

质量闸门

• 是否有删掉也不影响能力的组件？若有删除或解释保留理由。
• 是否把领域规则硬编码进 Kernel、脚本阈值或 ID？若有迁移到契约/适配器。
• 是否区分事实收集与语义判断，并保留不确定结果的人工复核？
• 是否逐项核对 Kernel 索引/契约，记录复用或不适用理由？
• 是否找到并论证跨至少两个领域的元组件？若没有，是否说明耦合、证据不足或维护成本原因？
• 是否能从事件/快照重放，且失败不会伪装为通过？
• 测试是否覆盖 canonical/alias、非法输入、超时、越界路径、Gate 缺证据和删除后的回退？
• 计划是否写出目标 Skill/Kernel 版本、读取证据、决策日期、实现位置，以及两个独立结论的分点理由和人类决策影响？

资料不足时只阻塞依赖缺失证据的部分，不凭空补状态/规则。执行模式须实现已选范围且完成必要验证后才标记完成；不得以“计划就绪”“文件生成”替代完成。作为更大任务的环节也遵循选定模式，交付实际源码/证据或明确只读产物，不偷偷退回只输出计划。

失败与恢复

• Kernel 缺失/不兼容、目标源目录不可写或宿主缺执行入口时，保留已读清单和脱敏错误摘要，标记受影响实现/验证为“受阻”；可完成不依赖这些前提的设计，但不声称接入生效，也不擅自升级 Kernel 或修改安装副本。
• 证据不足、组件结果为 uncertain/unchecked 或网络不可观测时，不把不确定结论写成 pass；记录缺口并指定人工复核或后续验证动作。
• 计划落盘失败时不进入实现；实现/测试失败时定位本轮相关原因并最小修复，保留失败证据；必要时按计划只撤销自己的变更，不使用 destructive Git、不清除用户改动。确需扩大授权、冲突无法消解或发生不可逆副作用才请求人类决策，不把普通设计取舍当成审批门槛。

约束

公共硬约束

本块由 docs/templates/skill-common-constraints.md 统一维护；每个 SKILL.md 的 ## 约束 必须逐字同步本块，不得在副本中改写公共规则。

• 任务需要落盘时，使用唯一的 ./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/ 根目录；共享材料放入 shared/，Skill 专属材料放入该 Skill 的 input/、output/、log/。
• 正式交付物、源代码和正式计划按项目约定保存，不写入任务工作区；未经授权不覆盖、删除、迁移或远程写入。
• 项目维护变更检查 BAC 可用性并记录需求、AI 产出、工具结果、文件改动和验证摘要；BAC 只做过程审计，不替代署名、责任或合规判断。
• 不记录 API Key、访问令牌、密码、Cookie、环境/凭据文件、私有 Prompt、身份信息、本地用户名、主机名或不必要的大体积原始数据。
• 文件路径必须规范化并限制在授权项目范围内；外部 URL、子进程和网络访问遵循最小权限，防止路径遍历、SSRF 和命令注入。
• Skill 版本唯一记录在自身 config.yaml:skill_info.version；公开 API、协议、目录或配置变更同步文档与 CHANGELOG.md。
• bensz-collect-bugs 是一个 Agent Skill；仅将 Bensz Agent Skill 或 Bensz 基础设施本身的设计缺陷交给它。先脱敏写入 ~/.bensz-skills/bugs/，当前任务不中断，只有用户明确要求才公开上报，禁止直接修改用户已安装的 Skill 源码。