verifier-state-architect

Files (10)

• CHANGELOG.md
• README.md
• README_EN.md
• SKILL.md
• config.yaml
• bsk-managed-runtime.md · references/
• bsk-orchestration.md · references/
• implementation.md · references/
• skill-pack-hosting.md · references/
• check_integration.py · scripts/

SKILL.md (first lines)

# Verifier-State Architect

## 目标

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

默认先保存计划再连续落地，不等待计划审批；明确“仅计划 / 不修改源码”或只读审查时才采用 `plan-only` / `review-only`。不负责普通业务重写、Kernel 修改、发布或远程操作，除非另行授权。

## 流程

### 输入

#### 输入与模式

- **必需**：目标 Skill 源码或完整内容、业务目标和约束。实施需要已授权的可写开发源码；只有文本时仅设计，不虚构落地。
- **可选**：已有计划、Kernel 路径、`runtime`、Pack、测试、报告和计划路径；默认设置见 `config.yaml`。
- 记录未提交改动与授权范围，不改系统安装副本。用户指定目标并要求设计/接入即授权必要本地变更；只读意图除外。
- 已有计划先核对源码、版本、范围和验收，只更新实质偏差；模式、依据和缺口写入计划。

### 执行步骤

#### 核心工作流

##### 理解服务对象

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

##### 删除影响闸门

逐项回答：

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

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

##### Kernel 复用与元组件二层审查

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

1. 只要目标采用 BSK，先完整读取并执行 [BSK 最新生产版运行规范](references/bsk-managed-runtime.md)：目标 Skill 只声明依赖，不声明最低/精确 Kernel 版本或 capability 门禁；在实现、集成检查和真实执行前用安装器强制确认最新生产版，并固定使用 Bensz 托管入口。更新未成功时只完成不依赖运行时的设计，不把旧版或项目环境冒充为已验证。
2. 从最新生产版 BSK 读取索引、契约、README 和实际版本，记录 Pack ID/version、分类、输入、入口与限制；仓库中的 `packages/bensz-skill-kernel` 只用于 Kernel 自身开发，不是目标 Skill 的生产运行入口。
3. 每个候选标记“直接 / 组合 / 适配复用 / 不适用”，比较语义、证据、Gate/转移、资源、版本与失败路径；仅词汇不同则优先适配。
4. 仅把跨两个以上不相邻领域、领域无关、契约稳定、可独立版本化和重放的能力列为提炼候选。Verifier 表达稳定命题；State 表达持续阶段，而非动作或一次性 helper。
5. 领域规则、模型偏好、易变阈值、特定格式和单一 Skill 流程留在 Skill/适配器；证据不足标记待验证。Kernel 建议只写计划，不直接实施。
6. 计划分别给出复用与元组件提炼结论；每项至少两条证据/收益代价/边界理由，证据不足时列缺口和验证动作。

##### 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 逃逸。

##### BSK 单一编排入口闸门

目标 Skill 同时用 BSK 管理领域 State 和至少一个 required Verifier 时，必须读取并落实 [Skill 自有 BSK 编排入口](references/bsk-orchestration.md)。这是 P0 接入条件，不能降级成建议，也不能只交付 Pack、`runtime` 声明或供 Agent 自由拼接的 BSK 命令。

目标必须在 `config.yaml.runtime.orchestration` 声明 Skill 内 `scripts/` 单一入口及 action 的 current/target State 映射，并在 `## 控制` 将其设为 Agent 执行受控 action 的正常唯一路径。入口必须统一：读取 BSK 当前 State；准备同一 run/attempt 的 Verifier 请求；从 `runtime.verifiers` 解析并执行全部 required Verifier；让 BSK 生成和记录 Gate；只在 Gate 明确放行且绑定完整后调用 BSK transition；严格校验每个 BSK 协议、ID/version、结果、Gate、运行身份和新状态回执。未知、缺失、不一致、`uncertain/unchecked`、超时或非放行结果一律 fail-closed。

仅 State、仅 Verifier或无 required Verifier时不强制生成入口。静态声明通过不代表入口已执行；必须补成功和失败行为证据，尤其覆盖未知 action、State 不匹配、required 漏跑/失败/未完成、Gate 错绑/非放行和 transition 回执异常。

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

##### 最小设计

使用矩阵：

| 候选 | 保留/删除 | 稳定命题或状态含义 | AI/脚本分工 | 输入与证据 | Gate/转移 | 失败与人工复核 |
| --- | --- | --- | --- | --- | --- | --- |

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

“Kernel 复用与元 Verifier/State 提炼决策”须包含：实际能力盘点；直接/组合/适配/不适用结论及契约匹配、失败和维护成本；推荐/暂缓/不提炼结论及跨领域证据、稳定性、版本化收益和耦合风险；对文件、兼容、测试、迁移和责任的影响。两类结论即使都是否定也保留至少两条理由。

计划须在修改源码前落盘。P0/P1/P2 分别表示安全完整性、契约可观测性和可选改进；每项写位置、证据、影响、验证、完成条件和回退。计划不是执行完成条件，也不增加审批关卡。

##### 连续落地

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

1. 按落地参考创建实际使用的 Pack、索引、契约和组件；专用资产随目标 Skill 托管，不进 Kernel，也不迁移无关资产或覆盖冲突改动。
2. 在 `config.yaml` 接入真实 `runtime`；在 `SKILL.md:## 控制` 写调用、证据、Gate、迁移、恢复和人工介入，并连接业务入口。只用 Verifier 时不造占位 State。
3. 适用 BSK 单一编排入口闸门时，先实现 `runtime.orchestration` 和实际命令入口，再把正常业务调用改接该入口；底层 BSK 命令只留给入口内部、诊断或恢复。机械工作由脚本执行，语义检查由宿主执行并回传证据；required 缺证据不放行。
4. 同步版本、使用文档、变更记录和 BAC；Skill 版本只在 `config.yaml`，Pack 版本在索引。保留 canonical/alias 和历史事件。
5. 运行托管检查和最短真实执行，覆盖复制发现、错误/缺证据、迁移及适用重放；按计划记录完成、偏差、不适用和受阻。零组件只交付删除影响证据，不建空目录/runtime/记录。

### 输出

#### 输入、输出与工作区

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

#### 计划固定结构

```markdown
# Verifier/State 设计计划：<skill>
## 结论摘要
## 业务流程与风险地图

From huangwb8/skills, MIT.

More from huangwb8/skills