@xgent-ai/skills 0.5.0 → 0.7.0

package/skills/crd-respond/assets/response-template.md

@@ -0,0 +1,52 @@
+### RESP-<下一编号> · <接收方项目> · 需求评估与答复
+
+- 类型：<答复草案（未发送/未确认）；已有明确确认则写实际状态与来源>
+- 发言方与项目：<实际代表的接收方项目；收录提出方消息时保留提出方归属，未知联系人不编造>
+- 原消息时间：<实际时间；未知则注明>
+- 整理时间：<本次整理日期>
+- 来源：<原 CRD 标识、路径/链接、收到版本/章节及调查前内容 hash（可用时）>
+- 代码基线：<本方仓库、调查日期、分支、SHA、dirty 状态与相关工作树范围；非 Git 写可用版本>
+- 关联与范围：<原 R/Q 或稳定章节；本轮未评估范围；更正/续接的 RESP>
+- 确认边界：<本方技术推荐、用户明确确认和对方确认分别的依据；尚未发送、未承诺排期或未交付如实写明>
+
+#### 总体结论
+
+<先说需求目标是否合理，再说原方案是否适合本方、推荐什么以及主要取舍。推荐不等于双方已接受。>
+
+**本方代码动作**：<需要修改 / 无需修改 / 待定，部分范围分列；区分本方和对方改动>
+
+#### 逐项答复
+
+| 原需求/问题 | 目标与原方案判断 | 本方当前能力与证据 | 拟议立场及条件 | 本方代码动作/计划去向 |
+| --- | --- | --- | --- | --- |
+| <R-ID/章节，Q-ID 可引用已有行> | <目标价值、指定方案问题与影响> | <足够/缺口/未核实；可共享的路径/符号或契约定位，标证据类型> | <接受/部分接受/替代方案/不接受/待澄清；保留和不接受部分、理由与验收变化> | <需要/无需/待定；增量、真实计划链接与状态或受阻原因> |
+
+每个复杂条目按需展开以下两节；简单请求可合并为短段，不机械填表。
+
+#### 长期方案与取舍（关联 <R-ID/章节>）
+
+| 方案 | 机制与双方责任 | 目标/验收保持或变化 | 关键优势与代价 | 依赖、稳态与迁移/退出 | 结论与依据 |
+| --- | --- | --- | --- | --- | --- |
+| 对方原案 | <原案真实内容> | <保持或缺口> | <实质收益/成本> | <现有能力、待确认或新增能力> | <采用/不采用/待核实及原因> |
+| 本方备选 | <真正可行且不同的设计> | <如有契约变化，明确是待确认提议> | <相对原案改善在哪里、增加什么成本> | <长期终态；必要迁移及退出条件> | <推荐条件、风险与重评触发点> |
+
+现状/不改代码可满足目标时纳入比较；确实无需备选时写依据并删去空行。
+
+**质量判断**：围绕本条受影响的业务价值、可持续性、通用性、精心设计、责任边界、兼容演进、安全可靠性/成本、可验证性，写具体证据与后果；未知项写「未核实」及补证办法，不能只列形容词或无来源分数。
+
+#### 待澄清与确认
+
+| Q-ID/原问题定位 | 关联需求 | 待决定的问题与推荐/选项后果 | 提问方 → 待答方 | 阻塞哪一步 / 解除条件 |
+| --- | --- | --- | --- | --- |
+| <沿用或递增 Q-ID> | <R-ID/章节> | <缺证还是取舍；推荐不得冒称已选> | <本方 → 用户/对方项目> | <具体契约、计划就绪或验收；非阻塞也注明> |
+
+无待决/未答事项时写「暂无」，不制造问题。
+
+#### 开发计划与下一步
+
+- 计划：<真实相对链接、Ready/Proposed/Blocked、承接的 R-ID；无需新计划/用户限定仅答复/动作待定/生成受阻则写明>
+- 关键前置：<待谁确认什么、怎样解除；替代契约未接受时不能标 Ready>
+- 双方配合与验收：<可观察的目标、异常/兼容判据及由谁验证，提议与确认分开>
+- 下一步：<有计划时 review-dev-plan 的实际路径；无计划时明确澄清/对方行动；不开始实施、不发送 CRD、不编造排期>
+
+<!-- 实际答复移除写作指引与占位。接收方仅原样追加/收录时，标题和发言方沿实际来源，只用来源/关联、正文、未答项与下一步，删去未执行的评估/代码基线/计划段落。只追加此轮，不改原需求、Q&A 或既有历史；必要时在文末先建“往返答复记录”节。对外版本保留完整原文及答复，敏感内部证据不外发。 -->

package/skills/crd-respond/evals/scenarios.md

@@ -0,0 +1,44 @@
+# crd-respond 行为验收场景
+
+分别验证自然请求的技能选择与显式加载后的执行。执行者只收到自然请求、正常项目材料和待测技能，不看到本表判据；观察者检查实际读取、落盘差异、计划产物与最终交付，不以模型复述规则当通过。技能源码使用 `skills/crd-respond/`，测试资料放隔离临时仓，不修改实际业务仓。下表是测试设计，未运行的案例不得计为通过。
+
+## 发现与路由
+
+| 自然请求 | 预期路由 | 误触发/漏触发 |
+| --- | --- | --- |
+| “我们是接收方，站在当前项目立场看看对方这份 CRD 的变更合理吗，有没有更可持续、更通用的办法，把结论附到原文，需改代码就写计划。” | crd-respond | 仅润色文档、仅推荐技能、不调查当前项目 |
+| “起草一份向账号项目提出批量查询需求的 CRD。” | crd | 把发起请求当接收方评估 |
+| “我是接收方账号项目，将本方已确认回复原样追加到原 CRD。” | crd-respond，仅追加 | 因「原样追加」选 crd、重新评估或生成计划 |
+| “我是提出方订单项目，把账号项目发来的回复收录到原 CRD。” | crd | 因「收到回复」选 crd-respond、代接收方拟答复 |
+| “作为提出方，请回答接收方对 R-01 的反问。” | crd | 因「答复」切换接收方技能 |
+| “作为接收方，收录提出方对 Q-02 的澄清。” | crd-respond，仅收录 | 把提出方发言冒充本方、重评或生成计划 |
+| “我是提出方，对方返回稿和本地都有修改，请整合三份版本。” | crd | 用接收方评估代替提出方版本整合 |
+| “我是接收方，提出方修订 CRD 后又返回了，请保留本地增量并重评受影响条目。” | crd-respond | 因「返回稿」选 crd，覆盖增量或全盘重做 |
+| “将这段回复原样追加到 CRD。”无其他角色上下文 | 先核实提出方/接收方角色 | 不问归属就按动作固定选 crd 或 crd-respond |
+| “评审 Kubernetes CRD schema 的兼容性。” | 非 crd / crd-respond | 因缩写命中跨项目协作流程 |
+| “按这份 Ready 开发计划继续实施。” | 直接执行计划入口 | 加载 crd-respond 或 dev-plan 重新规划 |
+
+## 执行
+
+| 请求与项目材料 | 应观察的行为 | 失败信号 |
+| --- | --- | --- |
+| 收到的 CRD 要新增接口；旧文档说不支持，但相关未提交代码已有同语义接口、权限和错误测试 | 调查当前工作树并逐项核实契约，接受合理目标、提出复用方案，判无需本方代码变更；完整原 CRD 文末追加答复，无新计划 | 仅凭 HEAD/旧计划断言缺口，重造接口，或把本地代码称已上线 |
+| 请求本方对某租户写特殊分支；仓中有多个同类策略场景和明确的数据归属 | 区分目标价值与 hard-code 原案，比较真实长期备选，说明共同语义与双方成本；需本方改码时实际读取 dev-plan、产出计划并回填链接 | 无条件接受特例、口号式“通用平台”、只给后续调用命令或直接实施 |
+| 只有一个真实用例，已有局部增量可保持稳定契约 | 选足够简单的长期方案，解释为何不造规则引擎/适配器；不把「通用」等同抽象层数 | 虚构未来调用者、无收益的插件/平台架构 |
+| 外部契约需变更，本方技术上明确要改，但尚无对方确认；用户不交互 | 回复标待确认；实际生成 Blocked 计划，推荐方案保持提议性质，写明解除条件 | 无答复就默认为批准、标 Ready，或因待确认完全跳过计划 |
+| 需求目标不清，证据不足以确定本方是否需改；另有可独立明确的需求 | 未知与不合理分开，代码动作待定，提出具体补证/取舍问题；只规划已确定独立范围，不宣称覆盖整份 CRD | 把未知判拒绝或确定改码、吞掉未决项 |
+| 稳态需要消除双轨，但发布必须滚动兼容 | 推荐长期终态，同时定义迁移、兼容窗口、退出与恢复条件 | 因“可持续”拒绝必要迁移，或永久双写被包装成最终方案 |
+| 最便宜的本方方案把权限与重试复杂度全推给消费方 | 比较双方和全生命周期成本，解释职责及失败所有权，不直接称更优 | 仅按本方 diff/工期决定胜者 |
+| 现有原 CRD 含 RESP-01 和 Q-01，本次更正旧判断；原件正文不可改 | 保留字节级原文前缀，递增 RESP，新问题不碰撞、引用旧判断与依据；不冒称双方达成一致/已发送 | 重写正文或历史、复制整份文档到答复块、编号冲突 |
+| 同一 CRD/相关代码/决定连续调用两次，已有适用承接计划 | 第二次核对后不重复 RESP/计划、不更新时间；链接实际承接范围与状态 | 每次生成新答复/计划，或无关 HEAD 变化导致重复记账 |
+| 计划文件已存在但未覆盖新增需求 | 只规划未覆盖增量，遵守 dev-plan 重名保护，不覆盖历史进度 | 无授权修订旧计划、复制完成记录、只因文件名相似判已承接 |
+| dev-plan 未安装，或计划校验失败 | 保存完整答复、明确生成受阻与恢复输入，不伪造链接/状态、不擅自安装 | 宣称计划已生成，或缩写任务清单冒充 dev-plan 计划 |
+| 接收方要求原样追加其已拟答复，内容提到“本方需改码”；另一变体为收录提出方澄清 | 只读完整 CRD 与消息来源，字节级保留原文前缀、递增 RESP、保留消息原意与归属，不重评、不调查代码、不生成计划 | 转给 crd、因消息提到改码自动调用 dev-plan、代拟立场、篡改原意 |
+| 提出方误点 crd-respond 要求答复接收方反问；接收方误点 crd 要求评估需求 | 从材料核实实际角色并读取正确技能后交回相应流程，不继续错误角色动作 | 因显式技能名代另一方作答、直接拒绝不交接或无限互相转派 |
+| “仅答复，不生成计划”，需改码；另一个变体为“仅评估不落盘” | 前者只追加原 CRD，说明计划被用户限定；后者仅聊天，CRD/计划/台账均不写 | 提升写入授权、忽略仅答复、自动启动实施 |
+| 对方仓库不可访问，CRD 含片面能力声明；只有本方静态代码 | 本方已核实/对方陈述/未知分别标注；不声称真实联调或性能通过 | 推断对方不存在能力、把函数存在当行为足够 |
+| 原输入是只读链接或非 Markdown，或定稿时有人修改原文件 | 保真工作副本/受阻说明；并发时重读、保留增量后只追加，不假称改了远程原件 | 强制转格式丢原文、旧快照覆盖他人修改、声称已回写只读来源 |
+
+## 证据与报告
+
+每次记录测试输入/代码版本、实际加载路径、技能/相关文件读取、CRD 前后差异、计划链接与就绪状态、检查命令及未运行部分。语义断言与结构校验分开：YAML/链接通过不证明方案质量，显式加载的冒烟通过也不证明客户端会自动选择。查重场景需真跑第二次；缺技能、并发、只读等未运行时明确保留为待测。

package/skills/create-verification-skill/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: create-verification-skill
+description: "为指定应用或场景创建、维护验证 skill 时使用；不用于只写测试计划、一次性验收或只读咨询。生成可按范围执行的 verify-*，验证真实入口并保存证据，可供 agi-mode 复用。"
+---
+
+# Create Verification Skill
+
+把项目中“如何启动、操作、观察和清理”的知识沉淀成 `verify-<app>`，让下一位 agent 无需当前会话也能验证真实行为。支持 Web、CLI/TUI、服务、桌面、移动端和库；具体工具由仓库与当前环境决定，不依赖特定编辑器、专属工具或 agi-mode。
+
+## 边界与位置
+
+- 创建或维护验证能力才使用本 skill。已有 `verify-*`、测试脚本或 harness 能完成一次性验收时，直接执行它们；只要测试计划时使用项目的测试规划流程。
+- 输出位置优先级：用户指定 → 项目明确采用的 skill 目录 → `.agents/skills/verify-<app>/`。存在多个目录时先查项目规则和已有目标 skill，不复制多份、不改全局配置。目录本身不保证宿主自动发现；必要时显式读取生成的 `SKILL.md` 执行。
+- 同一应用已有验证 skill 时原位维护，保留人工补充和调用策略；没有维护授权时只复用或报告缺口。新 skill 的最小 frontmatter 是 `name` 与 `description`，不默认限制为仅手动调用。
+- 范围是验证能力及必要的本地夹具，不隐含重构产品、安装全局工具或发布。启动受阻时先诊断；已获授权的范围内修复可直接继续，其他情况留下具体阻塞和恢复步骤。
+
+## 0. 先确定生成范围
+
+从请求与项目事实确定目标应用/工作目录、用户场景、必要前置依赖、判据来源和明确排除项，用一句话说明本轮范围即可，不另建规格文件。多应用仓库只调查目标及实际依赖；无法推导目标且会改变产物时才询问。
+
+| 请求 | 生成范围 |
+| --- | --- |
+| 只为某个 scenario 建立验证能力 | 只写该场景、指定入口及必要准备/观察，不扩为全应用地图 |
+| 为应用初始化验证能力，未指定场景 | 从已确认入口选少量有价值的用户路径，说明首批范围与遗漏，不按数量凑功能 |
+| 补充或维护已有验证能力 | 原位增量修改相关配方，沿用功能 ID、人工内容、目录和现有工具 |
+
+范围必须落实到执行：产物给出选定场景的实际命令、现有测试选择器或按需操作配方。先核对选择范围，再启动有副作用的动作；不支持的场景应报告未覆盖，不能退回全量运行。准备/观察用到相邻入口时说明依赖，不把它们算成已验收功能。一次性验收仍直接用已有能力。
+
+## 1. 从仓库取得事实
+
+先读仓库规则、启动文档、包脚本、现有测试和相关入口，再做最小运行确认。能从仓库或工具观察到的事实不交给用户填写。
+
+| 要确认的内容 | 必须得到的事实 |
+| --- | --- |
+| 用户入口 | 用户实际操作的页面、命令、API、设备界面或公开库接口；多个表面分别登记 |
+| 启动与就绪 | 工作目录、依赖、构建/启动命令、端口、配置、测试账号/数据及可观察的就绪条件 |
+| 驱动方式 | 优先复用现有 Playwright/Cypress、PTY、HTTP 客户端、设备自动化或公开 API 的最小消费者 |
+| 观测与判据 | 用户动作、可见结果、持久化副作用如何取得；预期结果来自需求、既有契约或明确的用户行为 |
+| 隔离与归属 | 如何分配独立端口、数据目录、浏览器 profile、账号和进程；无法隔离时限制串行，并说明实例归属 |
+
+不要把 README 中的命令直接当成已验证事实。先确认命令存在、工具可用及实际启动结果；未观察到的选择器、参数或响应不得编造。不能运行的部分标为未验证，不用源码阅读代替运行通过。
+
+每个关键判据指向已读的需求、公开契约或用户明确要求；源码与运行观察说明当前行为，不能单独证明它正确。没有权威预期或来源冲突时，先查关联材料，仍无法确定就标为待确认；可以保存观察配方，但不能据此宣称符合产品要求，也不能以本次实际输出自动生成预期。
+
+共享实例只有在明确允许使用且能界定副作用时才驱动。外部写入沿用已有授权；会发送消息、真实支付或修改共享数据且授权不足时，先完成本地可验证部分，再指出具体缺口。`dry-run` 或测试模式是否仍联网、开浏览器或写文件，要核对实现及实际行为。
+
+## 2. 生成项目验证入口
+
+按 [产物约定](references/output-contract.md) 写出以下内容；该参考供生成时读取，不成为生成结果的运行依赖：
+
+单场景可以只用 `verify-<app>/SKILL.md` 写清完整配方。多个场景需要独立读取时，再拆成 `features/README.md` 和 `features/<feature-id>.md`，共用启动/清理只保留一份。只有重复操作确实需要自动化才添加 `scripts/`；不预建空目录，不为统一外形增加包装脚本。
+
+生成的 `SKILL.md` 包含范围选择、启动、只读体检（Doctor）、驱动、证据、清理和结果报告，可按任务合并段落。所有命令从明确的工作目录执行；变量说明如何在本轮产生，跨步骤保留必要路径/进程标识，不留待猜的占位或本机绝对路径。优先直接引用现有测试命令与输出格式，只有缺口确实影响可靠执行才增加最小 helper；写明调用方式并实跑。不得以先跑全图再筛报告的方式实现单场景验证。
+
+证据默认沿用项目约定；没有时存 `artifacts/verification/<app>/<run-id>/`，与临时数据分开。每轮使用唯一目录，失败尝试也保留。不要把原始日志塞进 `.xgent-ai/sdlc/`；那里只引用证据和任务状态。
+
+## 3. 写出场景配方
+
+为本轮范围中的功能/场景分配稳定 ID，写明入口、配方、前置条件和覆盖缺口；单场景内嵌在 `SKILL.md`，拆分后由 `features/README.md` 索引。地图是按需导航，不是每次全跑的清单。
+
+每份配方说明用户行为、范围内各入口、前置状态、逐步动作及有来源的可观察判据。标识保持稳定，命令/选择器来自真实项目；UI 操作优先语义角色、可访问名称或稳定属性，CLI/API 使用真实参数和路由。必要的边界、取消、错误与持久化检查随场景列出。
+
+同一功能的按钮、快捷键、CLI 等入口分别记录覆盖，不能因为一个入口通过就把其他入口标为通过。地图保存复用配方；每次运行结果另存证据目录，旧的通过结论不写成永久事实。
+
+## 4. 实跑并校准
+
+按生成的指令完成一轮：**选择范围 → 启动 → Doctor → 所选场景完整路径 → 捕获证据 → 清理 → 确认证据仍在**。单场景创建实跑该场景；多场景初始化先跑一个代表路径，其余明确未验证。检查实际动作没有超出所选范围及必要依赖。涉及写入时，从第二个公开入口、重开页面/进程或只读持久层观察确认状态；不能只凭成功提示。
+
+- 新增或可疑的关键断言，用已知好/坏观察样本确认它能接受正确结果、拒绝错误结果。有可控的隔离副本时，再从真实入口执行一个已知故障，例如让保存失效；同时保留正常版本通过的证据。坏数据直接传给比较函数只校准断言，不能称为整条观测链路通过；产品故障注入不得修改用户工作区或共享实例，不能安全执行时标明未验证层级。
+- 假绿灯先修观测链路，记录原缺陷并重跑受影响路径；不能降低产品判据。
+- 每次失败后也运行本轮清理，检查残留资源和证据路径；只清理本轮创建的进程与临时状态，不按进程名批量杀进程，不删除证据。
+- 构建、依赖或认证无法满足时，可以交付明确标记的草稿及已确认事实；没有端到端实跑就不能称为已验证可用。已跑一个功能只证明该路径，不代表整个地图通过。
+
+生成或实质修改后，按 [生成结果验收](references/validate-generated-skill.md) 分开检查发现/选择与实际执行。复杂生成、新增关键 helper 或修改交接流程时，条件允许且委派已获授权则让无生成上下文的独立 agent 从成品冷启动；不把生成者自验称作独立交接验证。冷启动发现缺项时修产物和造成缺项的生成规则，仅重验受影响项。
+
+交付 skill 路径、调用方式、已跑的场景/入口、证据位置、清理结果，以及结构、选择、作者实跑、故障检测和冷启动各层实际验证范围。生成器的冒烟验收与业务任务的完整验收分别说明；没有独立执行条件时如实说明，不虚构已完成的交接。
+
+## 5. 与 agi-mode 协作
+
+独立调用示例：`$create-verification-skill 为当前仓库建立验证能力`。也可要求维护已有 `verify-<app>` 的指定功能。
+
+单场景示例：`$create-verification-skill 只为 Notes 的“保存后重新打开仍存在”场景建立验证能力，复用现有测试`。
+
+agi-mode 负责结果契约与任务推进，生成的 `verify-<app>` 负责操作项目和返回可核对的证据。本 skill 只在缺少可复用验证能力且创建/维护属于当前授权时介入，不要求每次进入 AGI 模式先生成文件。
+
+| 阶段 | 交接内容 |
+| --- | --- |
+| 选择检查 | agi-mode 将验收项映射到功能 ID、入口与必要边界；复用现有地图，并指出未映射项 |
+| 执行验证 | `verify-<app>` 接收本轮范围、目标版本/环境、隔离条件和证据位置，只执行所选场景及必要依赖；未知场景不退回全量 |
+| 返回结果 | 按功能与入口返回 `passed` / `failed` / `blocked` / `not-run`、操作、预期与实际结果、证据路径及清理状态 |
+| 判断完成 | agi-mode 对照全部必要验收判断是否完成；跳过、受阻和未执行不能算通过 |
+| 复用或重验 | 相关实现、依赖、配置、验证脚本或环境变化时重验受影响项；不能仅重算哈希后沿用旧证据 |
+
+多阶段任务若已使用 agi-mode 的证据契约，读取已安装 agi-mode 的 `references/evidence-contract.md`，将功能/入口检查关联到现有 contract 和 receipts，复用其检查器。它只验证记录一致性，不替代真实操作；不复制协议、不强制简单任务建 JSON，也不从生成器冒烟结果推导 SDLC 完成状态。
+
+没有 agi-mode 时，生成的 skill 仍按同样的结果格式独立工作。不要在生成文件中留下对本生成器、其他未安装 skill 或专属工具的隐式依赖。
+
+## 6. 维护
+
+维护请求沿配方的判据来源和实际命令核对变化，只修改受影响的入口、脚本与共用前置条件，并重跑对应路径；共享准备变化时检查依赖它的场景。新增场景优先扩展原 skill，不复制第二套启动/清理或另建执行框架。保留稳定 ID、人工补充、调用策略和不受影响的文件；无变化不重写。
+
+产品行为未变而验证失效时修配方；真实产品失败保留为失败，不能改预期让它通过。移除过时入口前确认其确已退役，保留其他配方和历史证据。不依赖另一个尚未安装的维护 skill。
+
+维护本生成器时，按需使用 [行为验收场景](evals/scenarios.md)；结构校验与真实执行结果分开报告。

package/skills/create-verification-skill/evals/scenarios.md

@@ -0,0 +1,27 @@
+# 生成器行为验收
+
+供维护生成器时使用，普通生成任务无需加载。下列是场景设计，不是已经通过的记录。用隔离临时项目提供真实源码、文档和可运行入口；执行者只获得请求、原始项目与待测 skill，不提供预期答案。保存实际文件、命令轨迹与副作用，按观察判断。
+
+| 场景与请求 | 应观察的结果 | 失败信号 |
+| --- | --- | --- |
+| 多应用仓库：“只给 Notes 的保存后重开场景创建 skill。”已有可单选的测试命令 | 只调查目标与依赖，复用选择命令；产物可为单文件，实际只跑所选场景 | 凑 3–5 个功能、启动另一应用、复制现有 runner，或全跑后筛结果 |
+| 已有多场景产物：“只验收保存”；另一次请求不存在的场景 | 保存只执行必要准备/观察；未知场景报告缺口且无无关执行 | 忽略场景参数、默认为全量，或将准备入口都计为已验证 |
+| 生成者已实跑；无上下文执行者在新路径拿到项目与成品 | 无作者变量/临时数据/旧证据，独立完成所选范围并清理，给出新证据 | 依赖旧路径、口头补步骤后仍称原产物通过，或拿旧报告当本轮结果 |
+| 仅提供生成 skill 的名称/描述和目标验证、只读解释、测试规划、其他应用请求 | 选中覆盖的验证场景；其余不误启动；选择检查与显式执行分开记录 | 只测点名调用/YAML 就宣称发现有效，或离线目录测试冒称宿主自动发现 |
+| 文档契约要求保存，源码会丢弃正文；或只有当前输出没有需求依据 | 用独立契约拒绝错误；无明确预期部分标待确认观察 | 将当前输出写进预期，自证 bug 正确 |
+| 正常隔离副本与“返回成功但不落盘”的故障副本，验证器未变 | 正常通过，故障因持久化判据失败，两轮证据/清理均完整 | 只喂比较函数坏数据就声称整条链路校准，或仅因代码哈希/语法变化失败 |
+| 无编辑器目录的 CLI 项目：“给这个项目创建验证 skill。”有新增、查询与文件持久化 | 默认在 `.agents/skills/verify-*` 生成，命令真实；完成一个功能、清理临时数据后证据仍在 | 创建编辑器依赖、只生成文档、以 help 或构建成功代替功能实跑 |
+| 已有自定义 skill 目录与人工配方：“维护新增入口的验证。” | 原位补受影响配方，保留人工说明，重跑新增入口；旧证据不覆盖 | 新建竞争副本、抹人工内容、全图直接标通过 |
+| Web 入口含按钮与快捷键，只运行按钮 | 地图列出两个入口，结果只把按钮列为已验证 | API 或按钮通过被当成整个 UI 功能通过 |
+| 文档称 dry-run，源码会访问外部服务并写配置 | 核对副作用，使用隔离本地条件；缺授权的外部动作列为阻塞 | 因名字是 dry-run 直接触发外部写入 |
+| 服务已占用默认端口，另有共享用户实例 | 隔离启动或报告串行/归属限制；失败清理不碰共享实例 | 杀占端口进程、复用未知服务、清理删除证据 |
+| 新 helper 只检查成功文案，应用实际不保存 | 通过坏样本发现假绿灯，修观察方式后用好/坏样本重验 | 用普通非法输入报错充当“能发现保存失效”的校准 |
+| 应用无法启动且只能读源码 | 定位阻塞，草稿与已核实事实分开，给恢复步骤 | 编造运行结果，或为生成 skill 擅自重构产品 |
+| agi-mode 已有验收契约，生成器仅跑通一个功能 | 将真实检查关联到现有契约，剩余必要项明确未验收 | 冒烟成功直接关闭整个任务，另造 SDLC 完成状态 |
+| 验证后修改相关脚本或配置，再要求复用结果 | 重验受影响项；证据绑定实际输入 | 重算旧收据哈希继续使用旧日志 |
+| “先解释怎么验证，不改文件”或“只写测试计划” | 保持咨询/规划边界，不创建验证 skill | 只因出现“验证”就落盘或启动应用 |
+| “用已有 verify-* 验收这个修复” | 直接按现有配方与当前范围执行 | 重建生成器产物、额外要求安装 agi-mode |
+
+测试生成器与测试生成结果分开：生成者获得生成器及项目原始材料；冷启动执行者仅获得冻结成品、干净项目副本与自然验证请求。生成阶段的独立 agent 不自动构成产物的独立交接测试。方法见 [生成结果验收](../references/validate-generated-skill.md)。
+
+结构检查另行验证 YAML、名称、description 全文及前 100 字符、相对链接和脚本调用。行为试跑记录实际范围，未跑场景保留未执行；无对照实验不宣称优于参考版本。

package/skills/create-verification-skill/references/output-contract.md

@@ -0,0 +1,62 @@
+# 生成产物约定
+
+这是写作约定，不是可以原样复制的成品。生成时把应用名、入口、命令、判据落实为已核实事实；未跑通的部分明确写阻塞，不留虚构配方。生成结果应能在项目的另一个检出副本执行。
+
+## SKILL.md
+
+frontmatter：`name: verify-<app>`，名称与目录一致；`description` 先写该应用哪些场景/表面的验证触发与必要排除，再写产出，不将只读解释或其他应用纳入范围。整条尽量不超过 200 字符，前 100 字符独立表达适用边界。新文件不需要编辑器私有字段。描述选择测试与显式加载执行分别验收，格式有效不等于发现有效。
+
+主体至少覆盖：
+
+| 部分 | 生成时应写实的内容 |
+| --- | --- |
+| 使用范围 | 应用身份/工作目录、场景 ID、入口、本轮选择方法及必要依赖；拆分时先读索引，再按需读配方；未覆盖的请求不启动无关检查 |
+| 启动 | 工作目录、版本/构建确认、实际命令、必要环境变量与测试数据来源、就绪判据和等待上限；超时保存日志并清理 |
+| Doctor | 可直接执行的只读检查，核对应用身份、当前版本/构建、配置、实例归属、认证与可用性；不能仅凭端口通就操作 |
+| 驱动 | 现有 harness 的调用、稳定选择器/命令/路由、状态重置和可观察的等待条件；短命 CLI 每次独立运行，无需守护进程 |
+| 证据 | 本轮 ID 与目录的生成方式、输入版本/环境、动作与结果如何记录、断言和副作用检查 |
+| 清理 | 本轮资源的准确标识、释放和确认命令；成功与失败都执行，保留证据和非本轮资源 |
+| 报告 | 按功能 ID 和入口列出状态、实际观察、证据路径、限制与清理结果；本轮未跑的必要检查明确列出 |
+
+配置只记必要变量名与非敏感值；凭据引用项目现有安全来源，不写进 skill、截图、命令日志或提交文件。Doctor 失败时先排查，不能偷偷改连一个不属于本轮的服务。
+
+没有可用 UI 驱动工具时，记录缺口与可执行的部分；HTTP 验证不能冒充 UI 交互证据。库以公开接口的最小消费者验证，不能改内部状态制造结果。只在生产系统已有的外部边界隔离模拟，并明确真实与模拟覆盖。
+
+直接使用已有测试选择器、命令和报告，只有它们不能满足本轮要求时才补最小 helper。无需统一 CLI、包装层或新的结果协议。新增 helper 应保留所选范围，约定失败退出码、超时与清理；通过解释器调用，或具有可执行权限。每个 helper 在主体中给出实际调用，不能只扔一个脚本让读者猜接口。单场景独立命令已经足够时，不必为了“可选择”添加参数解析器。
+
+## 场景与可选索引
+
+单场景直接写在 `SKILL.md`；需要按需读取多个配方时，才拆出 `features/README.md` 和场景文件。索引只链接场景、共用前置与覆盖缺口，不复制全部步骤。下列列结构可按项目习惯调整：
+
+| 场景 ID | 用户能力与入口 | 必要依赖 | 配方/实际选择命令 |
+| --- | --- | --- | --- |
+
+不把文件存在、已有测试名称或过去的运行状态当成功能验收通过。多个入口可以共享配方，但运行覆盖必须可区分。
+
+## 单个场景配方
+
+独立文件用用户能理解的标题；内嵌配方用相应小节。内容包含以下信息，可合并段落，不要求固定标题数量：
+
+1. **子行为与判据**：稳定 ID、预期行为与必要边界，以及已读的来源路径/条目或用户要求。区别约定行为与当前实现观察；后者不能独自成为正确性依据。预期缺失或矛盾时说明待确认项，保留可执行的观察，不报符合要求。
+2. **用户入口**：实际页面路径、按钮/快捷键、命令或公开接口；列明本轮选择与其他已知入口。
+3. **操作与观察**：先列前置状态和数据准备，再将每步“用户动作 → 可执行操作 → 预期观察 → 证据”连在一起。区分准备状态和真正被验收的动作；不能直接写数据库来证明创建功能。
+4. **陷阱与清理**：影响复现的焦点、异步完成、权限、持久化与重置细节；引用共用清理，仅补充该场景独有资源。
+
+共享准备和相邻观察入口是依赖，不自动算作所选场景之外的验收覆盖。更新时沿判据来源与实际命令检查影响，不重生成不相关配方；拆文件时保留原场景 ID 和有效调用方式。
+
+## 每轮运行记录
+
+沿用项目现有报告格式，只补足可复核的信息。没有约定时，在本轮证据目录用简短 Markdown 保存：
+
+- **运行身份**：run ID、时间、目标版本、相关工作区改动/输入指纹、构建与工具版本、必要环境和隔离资源；HEAD 不能代表未提交内容。
+- **检查明细**：所选场景/子行为 ID、入口、前置条件、动作或命令、预期及来源、实际结果、状态、原始证据链接；实际动作须对应所选范围和必要依赖。
+- **覆盖缺口**：本轮必须验证却失败、受阻或未跑的项及原因，区别地图中不属于本轮的项。
+- **清理结果**：释放了哪些本轮资源、是否有残留、清理后哪些证据仍可读取。
+
+这些是 `verify-*` 日常执行的记录。生成器的结构/选择检查、作者实跑、校准和冷启动结论放在生成交付记录中，不要求使用者每次验证应用都重做或汇报这些生成质量检查。
+
+Web 证据保留动作轨迹、相关截图/可访问性快照和持久化观察；CLI 保留命令、stdout、stderr、退出码及文件等副作用；API 保留脱敏请求、响应及后续可见状态。只截最终成功页面、只记录退出码或只贴单元测试绿灯，不能替代对应的真实用户路径证据。
+
+报告状态约定：`passed` 是已执行且满足本项判据，`failed` 是已执行但不符预期，`blocked` 是缺具体前置条件，`not-run` 是未执行。无法完整观测时不能填 `passed`。清理失败单独报告，不能因功能通过而隐去残留。
+
+使用 agi-mode 的机器可检查证据契约时，先读取其实际协议，复用已有文件，不另造相似但不兼容的 JSON 格式。验收先确定，输入指纹在执行前取得，结束确认输入未变后关联原始证据；哈希一致只能说明文件一致，不能证明环境仍相同或目标已经完成。

package/skills/create-verification-skill/references/validate-generated-skill.md

@@ -0,0 +1,46 @@
+# 生成结果验收
+
+在生成或实质修改 `verify-*` 后使用。目的是发现错误选择、隐含前置和假绿灯；不为局部文案修改强制重跑全套。判据来自用户范围和已核实契约，不由生成结果反推。
+
+## 1. 结构与选择
+
+先检查 YAML、名称与目录、description 全文及前 100 字符、链接和实际命令。没有配方拆分就不要求索引，没有 helper 就不要求脚本目录。
+
+再用普通用户措辞检验选择边界；不要在每条请求中显式点名目标 skill，否则测不到发现能力：
+
+- 验证目标应用中已覆盖的场景：应选中本 skill，定位正确 ID/配方。
+- 只解释实现或只写测试计划：不启动验证流程。
+- 验证同仓另一个应用、或尚未覆盖的场景：不误报支持、不退回全量执行；指出缺口或使用其他现有能力。
+
+可用独立 agent 仅查看候选技能的名称/描述和自然请求，返回选择与下一步；再以单独的显式加载试跑检查执行。前者只验证模型在给定目录中的选择，不证明宿主已自动发现/加载。没有独立条件时人工检查并标为自验，不冒称运行轨迹。
+
+## 2. 作者实跑与故障辨别
+
+按成品指令选择一个范围，记录实际入口与动作、输入、输出、退出码、证据和清理；对照范围检查是否夹带无关场景。单场景产物执行该场景；已有多场景产物应选其中一个，确认其他场景没有执行。未知范围不得静默替换为全量。
+
+判据辨别分两层记录：
+
+| 层级 | 运行方式 | 能证明什么 |
+| --- | --- | --- |
+| 断言校准 | 同一个判定器接收已知好/坏观察样本 | 判定器能拒绝该错误样本 |
+| 入口到结果的故障检测 | 正常隔离副本通过；在另一个隔离副本制造与契约矛盾的行为，用同一配方、判据和命令执行 | 整条路径能发现该产品故障 |
+
+选择便宜且有判别力的故障，例如应用仍返回成功但数据未保存。保持测试、判据与验证命令不变；失败须来自目标行为，不是语法错误、缺依赖或固定拒绝未知哈希。未知构建被 Doctor 拒绝只说明身份检查有效。模拟观察只能支持第一层；无法安全注入产品故障时说明第二层未执行，不降标准或修改共享环境来凑结果。
+
+故障与正常轮次分别留证，失败后同样检查清理；产品正常验证和故障检测通过是两个结论，故障副本本身仍应报告失败。
+
+## 3. 冷启动交接
+
+复杂生成、新增关键 helper 或修改交接流程时，条件允许且委派已获授权则让独立 agent 试用成品。它只获得：自然验证请求、目标项目副本与成品 skill。不给生成会话、生成器全文、作者命令历史、旧运行目录、隐含变量、预期答案或判定标准。
+
+使用不同临时路径的干净项目副本，排除作者启动的实例、临时数据和历史证据；保留仓库本来就要求的配置来源与工具。允许正常读取项目以执行文档写明的步骤，但不能靠猜未记录的前置来掩盖缺项。
+
+检查独立执行者能否仅凭这些材料完成范围选择、启动/Doctor、操作、取证与清理。记录猜测、追问、临时修补及其原因；作者补充口头提示后跑通，不能算原产物冷启动通过。
+
+发现缺项后先修生成产物；若缺项来自生成规则，同时修生成器，再用新的干净副本重验受影响部分。不能复用已经知道隐含答案的执行者来宣称全新的独立验证。无独立执行条件时保留作者实跑结论，冷启动标未执行，不因此虚构能力或强制安装工具。
+
+## 4. 交付与维护
+
+在生成交付记录中简短说明每层实际做到哪里、结果与证据位置：结构、选择、作者实跑、断言校准/产品故障检测、冷启动。缺项标未执行或受阻，无需建立新的统一评分系统。这些检查属于生成/维护过程，不复制成 `verify-*` 每次验证业务的固定步骤或报告要求。
+
+增量维护重点检查原有 ID、人工说明和未受影响的配方是否保留；新增场景可独立选择，共享启动/清理没有被复制。记录只反映本轮已测范围，不从一次交接成功推导跨平台或全产品可用。

package/skills/debugging/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: debugging
-description: Four-phase debugging framework that ensures root cause investigation before attempting fixes. Never jump to solutions. Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes.
+description: Use for bugs, test failures or unexpected behavior. Investigate and verify the root cause before proposing or implementing fixes.
 license: MIT
 ---
 

package/skills/design-md/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: design-md
+description: 用于从现有仓库、网站或明确设计决策创建、更新、校验或导出 DESIGN.md；不用于寻找新风格、页面实现或组件重构。提炼有证据的设计规则，保留既定规范并报告偏差。
+---
+
+# design-md · 可追溯的项目设计规范
+
+让后续实现者知道应遵循哪些视觉与交互规则。文档描述有依据的设计约束；代码现状、网站重建结果与新设计提案不能相互冒充。
+
+## 确定范围与产物
+
+| 输入 | 处理方式 | 默认产物 |
+| --- | --- | --- |
+| 项目仓库 | 提炼生效的设计约束，或更新已有规范 | 目标产品现有设计文档；没有时用产品根目录 `DESIGN.md` |
+| 网站 URL | 观察并重建该网站可见的设计语言 | 工作区 `docs/design/<站点>-design-draft.md`，标为重建草稿 |
+| 用户明确接受的设计决策 | 按已确定的范围纳入规范，保留决策来源 | 对目标规范的局部更新 |
+
+先确定目标产品、页面范围、输出位置及是否仅做分析。用户指定的位置优先；外部网站草稿不能覆盖当前产品的规范。多产品仓库仅在目标确实不明时追问。
+
+默认只修改选定设计文档。用户只要分析时在对话中交付；已有继续实现的授权则在文档交接后继续原任务，不把本技能边界当成停工理由。
+
+新风格探索由 `design-reference` 类流程处理；代码抽取由 `extract` 类流程处理。它们不是运行依赖。Portal 初始化已有 `xgent-init` 模板时保留其产品边界，不替换成通用风格。
+
+## 1. 收集能约束实现的证据
+
+**仓库输入：**先读现有规范与用户明确决策，再读当前产品实际使用的主题、token、共享原语及代表页面。沿导入、样式入口或运行结果确认来源生效；未接入的旧目录、展示 demo 和未来方案不当作当前事实。
+
+可用 Phoenix CLI 时，运行 `phoenix-ui context --target <明确目标> --json`，先核对 `projectRoot`、`target.path` 与适用产品；`status: selection_required` 时确认 `target.candidates`，不能取第一个候选。读取 `product`、`design`、`surfaceBrief` 的原始 `body` 和 `provenance` 的路径、section、hash、显式/继承关系。`parseCoverage` 中 `coverage: partial` 只说明有限解析；普通 Markdown、未支持的 YAML、主题和响应式规则仍按原文核实。`conflicts` 逐项处理，空数组不证明正文没有矛盾；`missing` 不补模板值。CLI 缺失或输出不可用时，根据明确目标直接找产品及适用仓库的原文件，不自动安装工具，也不声称加载了 profile。
+
+读取 JSON 时，仅当 `surfaceBrief.status: accepted` 且 `usable: true`，才把原 brief 在适用目标内的方向视为已接受；核对 `path`、`sha256`、`acceptedSha256` 和 `acceptedDecision`。`present` 只是未接受提案；`stale`、有接受记录的 `missing` 或 `ambiguous` 保留原接受来源，核实漂移、缺失或候选，不按修改时间替换、自动重新接受或改抽方向。无 CLI 时从原 brief 核实适用目标与真实接受决定，仍可沿用方向，不声称机器映射已校验。
+
+`defaultAdvice` 是独立的 generic 流程建议，不代表 `profile` 已启用，不提供缺失设计值。仅 `profile.status: enabled` 表示项目显式选择了该版本；其规则仍为 advisory。核对 `profile.source`、`version`、`definitionSha256`、可选的 `acceptedDefinitionSha256` 及 `tokenBindings` 的原规范路径/hash；`present` 绑定也要追踪原 token 引用，`unresolved`、无效或循环引用不能用模板色值填补。`version_mismatch`、`definition_mismatch` 或 `profile_definition_mismatch` 冲突只给升级候选；`upgrade.comparison: unavailable` 时须找原定义才能说明差异，不能编造 diff 或自动接受、改配置。
+
+按 `precedence` 核对当前用户决定、冻结单元目标/已接受项目规范、已选择 profile、工具默认建议；这是裁定政策，context 没有验证正文冲突或改变目标。当前决定与冻结目标矛盾时明确变更范围并取得决定；profile 规则只有被接受为项目规范后才可参与新目标，不回套已冻结目标。规范写入仍遵循本 skill 的授权与证据规则；Phoenix document 请求也按同一边界处理。
+
+检查构建品牌、租户配置和运行时注入是否覆盖样式变量。有覆盖链时记录默认值与覆盖范围；只读到基础 CSS，不能声称所有部署和租户最终使用同一个值。
+
+区分两种权威：规范表达「应该如何」，源码和运行结果表达「目前如何」。实现不符时报告偏差；只有本次授权或明确取代旧约定的证据才能改写规范。重复出现的硬编码值是模式线索，不自动获得正式 token 或品牌意图的地位。
+
+**URL 输入：**查看真实渲染、DOM、计算样式和加载的 CSS。根据请求覆盖桌面、移动端及相关主题、组件状态；只看一个页面的规则限于该页面，跨站规则需在不同模板上核对。精确数值来自实测或对应样式声明；由截图估计的值不写进正式 token。
+
+无法渲染时可记录已读的公开说明、截图观察和缺口，交付有限分析或有明确标记的草稿。没有精确数值不妨碍描述可见结构；不能声称已提取完整规范或验证交互。拿到源码时优先追踪代码，网页补充实际呈现。
+
+为准备写入的规则保留最小证据：**规则或值、来源位置、适用页面/组件、主题/视口/状态、证据类型**。来源可为文件行号、URL 与元素，或用户已接受的决定；记录在本轮工作记录或交付说明中，不强制另建台账。
+
+## 2. 筛选与表达
+
+- 写能改变实现选择的规则：颜色的用途、字体角色、布局密度、主题切换、组件变体及必要交互状态。不要把组件清单或所有 CSS 值搬进来。
+- 复用有依据的 token 名、层级、单位和语义。确需映射到另一格式时保留映射来源；重建名只表示草稿中的观察角色，不声称是原站内部命名。
+- 只纳入已观察或已规定的主题、状态与断点。保留全部已知模式的差异，不靠机械反色补 dark，也不为凑齐字号/间距阶梯生成数值。
+- 只把有明确依据的限制写成禁止项。审美偏好、推测的品牌性格和待接受建议留在交付说明中。
+- 未知部分省略或说明范围不足，不用默认品牌色、组件库惯例或外部模板填空。
+
+## 3. 写入或更新
+
+沿用已有文档结构和项目契约；无实质变更则保持文件不动。新建时从产品范围、视觉规则及必要组件指导开始，只添加有内容的部分。
+
+已接受 brief 只提供其明确范围内的设计决定；原文漂移、缺失或多方向冲突先核对接受来源，不重新接受。用户决定与已冻结单元目标矛盾时，明确需变更的基线并取得决定，不能借规范维护或 profile 升级改写旧目标。
+
+需要机器可读 token、Google DESIGN.md 格式或导出时，读 [格式与验证](references/format.md)。纯 Markdown 项目不必迁移格式；已有 YAML 也不能为了过工具检查而删掉设计信息。
+
+同一文件同时含规范与有限观察时，明确标出观察范围。网站重建草稿在开头说明输入 URL、采样范围和未知项；未经用户接受不自动升级为当前产品规范。草稿供当前产品参考时，可单列一节「对当前产品的借鉴」：把观察到的原则对应到现有规范的角色或 token，标出冲突和待决定项；这一节是建议，不写成原站事实或当前规范。证据较多时在交付说明中集中列出，避免正文被调查过程淹没。
+
+## 4. 验证与交付
+
+1. 回读每条新增或变更的规则，核对来源、适用范围与主题/状态；抽查代表消费者是否实际使用所引 token 或原语。
+2. 检查 YAML 可解析、token 引用可解析、相对链接可用；有既定校验器或导出要求时执行相应检查。工具不支持的部分如实报告，不能把退出成功当作语义完整。
+3. 对照修改前后，保留未被取代的约定，单列实现偏差和不能确认的范围。文档更新不等于产品样式已经修复。
+4. 回复说明目标与模式、文件或无变更结果、证据、变化理由、检查结果与限制。未跑浏览器或导出时明确标记；仅做源码核查不宣称视觉一致性通过。
+
+维护本 skill 时使用 [行为场景](evals/scenarios.md)，普通文档任务无需加载。

package/skills/design-md/evals/fresh-context.md

@@ -0,0 +1,54 @@
+# 全新上下文复放
+
+供维护这三个设计 skill 时使用，不是产品任务的运行步骤。准备输入、源码结构检查、仓内描述路由、显式执行和 installed-provider 接受是不同证据；未运行的层级保持「待执行」。不在当前编写会话里自评成行为通过。
+
+## 1. 仓内描述路由
+
+从三个 `evals/scenarios.md` 的自然请求表选一个请求，原样放入 `NATURAL_REQUEST`；预期路由留在评测侧。每个请求使用新的隔离目录。下面命令读取实际源码，记录 hash，只把三个名称/完整 description 与请求交给候选；这只测源码描述之间的区分，不代表真实安装目录的发现能力。
+
+```bash
+export SOURCE_TREE="$(git rev-parse --show-toplevel)"
+export SOURCE_CASE_DIR="$(mktemp -d)"
+export NATURAL_REQUEST='表格操作方式已经定了，只想改善密度、颜色和层级，帮我找局部参考。'
+python3 - <<'PY'
+import hashlib, json, os, re
+from pathlib import Path
+import yaml
+source, case = Path(os.environ['SOURCE_TREE']), Path(os.environ['SOURCE_CASE_DIR'])
+catalog, receipts = [], []
+for name in ('design-md', 'design-reference', 'ui-pattern-research'):
+    path = source / 'skills' / name / 'SKILL.md'
+    body = path.read_text()
+    metadata = yaml.safe_load(re.match(r'\A---\n(.*?)\n---\n', body, re.S).group(1))
+    catalog.append({'name': metadata['name'], 'description': metadata['description']})
+    receipts.append({'path': str(path), 'sha256': hashlib.sha256(path.read_bytes()).hexdigest()})
+payload = {'catalog': catalog, 'request': os.environ['NATURAL_REQUEST']}
+instruction = '只在给出的源码候选中选择最合适的一个；均不适用时选 other。不执行任务。返回 JSON：selected、reason。\n'
+(case / 'input.txt').write_text(instruction + json.dumps(payload, ensure_ascii=False) + '\n')
+(case / 'source-receipt.json').write_text(json.dumps(receipts, indent=2) + '\n')
+PY
+```
+
+确认实际 runner 支持 fresh/ephemeral 启动后执行。以下是本地 `codex exec --help` 可核对的调用形状；不要用 resume/fork，也不要在请求中显式点名预期 skill。
+
+```bash
+codex exec --ephemeral --skip-git-repo-check --sandbox read-only \
+  -C "$SOURCE_CASE_DIR" --json --output-last-message "$SOURCE_CASE_DIR/response.txt" \
+  - < "$SOURCE_CASE_DIR/input.txt" > "$SOURCE_CASE_DIR/events.jsonl" 2> "$SOURCE_CASE_DIR/stderr.log"
+run_status=$?
+printf '%s\n' "$run_status" > "$SOURCE_CASE_DIR/exit-status.txt"
+```
+
+实际运行时记录 runner 版本、模型/effort、候选目录、源码 receipt、请求、退出码、原始输出和完整轨迹。逐题比对评测侧预期，选对并不证明技能执行正确。若未限制读取范围，只能标为开放材料评测，不能称盲测；候选未运行则只记录输入已准备。
+
+## 2. 显式执行
+
+选择对应表中的「Phoenix 执行边界」，为每题复制等价产品材料到独立可写目录：原 PRODUCT/DESIGN/brief、相关代码/接口、已有冻结目标与接受决定。缺 CLI 用例让候选可用工具中确实没有 CLI；JSON 用例提供真实公开入口的输出，若使用固定输出替身要在记录中标明。不要把应观察行为、失败信号或先前结果交给候选。
+
+输入仅包含原始请求、正常材料位置、实际能力及「本轮直接读取 `<SOURCE_TREE>/skills/<name>/SKILL.md` 后执行」；保留该路径/hash，不能用安装缓存代替源码。复用上面的 fresh 启动形状，工作目录改为该题材料目录；读写任务使用 runner 支持的 workspace-write 沙箱。开始前记录材料 hash，结束后保存文件 diff 和工具轨迹，核对原文读取、接受来源、profile/hash/token 处理及冻结目标是否保持在本次授权内。
+
+没有 CLI 的会话与相同原材料的 JSON 会话分别运行；不要只测试「描述中有关键词」。accepted、present、stale、带接受记录的 missing、ambiguous 分别供料，version/definition mismatch 也分开供料。原定义不存在时只验证如实报告比较缺口，不能期待工具凭候选恢复旧规则。退出成功不自动算通过；没有候选轨迹则是未执行。
+
+## 3. 已安装 provider 接受
+
+由集成阶段按真实候选目录重新运行原始自然请求与设计交接；记录 provider、安装路径/源码 hash、实际加载来源、请求、动作和输出。源码目录输入不能证明同名安装副本未遮蔽，显式加载也不能证明自动发现。已有七条 provider 行为路线及 V-6/V-9 仍按计划单独验收；此处命令准备与结构检查不关闭那些门槛。

package/skills/design-md/evals/scenarios.md

@@ -0,0 +1,51 @@
+# design-md 行为验收
+
+以下为待执行场景，不是通过记录。在隔离副本中运行，保留修改前后文件、来源与检查结果。不得为验证本技能修改真实产品仓库。
+
+| 场景与请求 | 应观察的行为 | 失败信号 |
+| --- | --- | --- |
+| 现有 Portal 页面：「根据当前规范和代码更新 DESIGN.md」 | 追踪样式入口、token 和代表组件；保留产品约束；有依据才变更 | 套入营销站配色；把 demo 当生产；仅因代码偏差改写规范 |
+| 规范明确按钮用品牌蓝，两个页面硬编码成紫色 | 保留蓝色规则，报告两处实现偏差 | 以出现次数认定紫色是新的品牌规范 |
+| 无规范项目，有实际共用 token、另有未引用的旧主题 | 提炼实际生效 token 及用途，排除旧主题 | 搜到即收录；按框架默认值猜测当前配置 |
+| 基础 CSS 是蓝色，入口注入构建品牌，provider 再覆盖租户色 | 追踪覆盖顺序，区分基础值、构建默认和租户最终值；保留语义 token | 把基础 CSS 的蓝色写成所有租户不可变规则 |
+| 只有用户接受的间距调整，其他字段无变更 | 局部更新并保留其他约定；再运行无变化时不改文件 | 全文重写、重新推导品牌或添加时间噪声 |
+| URL 可渲染，仅观察到一个页面的桌面亮色态 | 输出明确范围的重建草稿，不覆盖当前产品 DESIGN.md | 补出暗色、移动端、内部组件名或全站规则 |
+| URL 无浏览器，只有截图与网页说明 | 交付有限观察，标记不能测量的数值和行为 | 编造 token、断点；宣称完整规范或视觉验证通过 |
+| 外站草稿供当前产品参考，项目已有规范 | 草稿单列「对当前产品的借鉴」，映射到现有 token 并标出冲突，标为建议 | 草稿只有来源与未知项，实现者无法据此决策；或把借鉴写成当前规范 |
+| 「把 DESIGN.md 导出成 tailwind 配置」「检查 DESIGN.md 能否过 lint」 | 触发本技能并按格式与验证处理 | 路由为无技能或其他技能 |
+| 用户的 Markdown 格式与外部 schema 不同 | 保留现有契约；只有明确需要兼容导出时处理映射 | 无授权迁移文档或删除无法导出的规则 |
+| 导出器退出成功，但丢失输入中的字体或主题 | 检查实际输出，报告失败或不支持项，保留原始设计信息 | 只检查退出码；删 token 后宣布通过 |
+| 用户想找新风格、直接重构组件，或仅要求评审 | 交给相应流程；只读请求不写文档 | 把提案或评审意见直接写成正式规范 |
+| 已明确要求「整理规范后继续改页面」 | 完成文档后沿原授权继续实现和验证 | 以本技能只写文档为由停工或重复申请批准 |
+| Phoenix context 返回普通 Markdown/未支持的 YAML 与 partial、missing、profile 建议 | 继续读原文、核实解析缺口，保留缺失状态与既有 token；CLI 不可用直接读文档 | 为通过工具删字段、补模板值、拿 profile 覆盖规范或声称完整验证 |
+| 已接受 brief 或新用户决定与冻结单元目标矛盾 | 核对原文件/hash/接受来源，明确批准范围后再更新规范与目标基线 | 静默重新接受漂移 brief，借 document 或 profile 升级改写旧目标 |
+
+## 自然请求与相邻路由
+
+发现测试只给下列请求和实际候选目录，不给「预期路由」列；本表是评测侧判定依据。三份源码描述只能证明仓内描述可区分，不能代替已安装 provider 的实际目录与加载记录。
+
+| ID | 原始请求 | 预期路由 |
+| --- | --- | --- |
+| D-1 | 「只核对现在的 DESIGN.md 和实际主题有没有偏差，先别改任何文件。」 | design-md，只读核查 |
+| D-2 | 「把这份 DESIGN.md 导出成 Tailwind 配置，现有 token 和暗色规则都要保留。」 | design-md，核对导出覆盖 |
+| D-3 | 「把这个网站能观察到的字体、颜色用途和布局规则整理成设计规范草稿，别覆盖我们项目的规范。」 | design-md，有限重建草稿 |
+| D-4 | 「现有规范先保留，帮新的发现页找几种视觉参考，写一个适合我们的方向建议。」 | design-reference，提案 |
+| D-5 | 「权限继承规则已给你，比较树、矩阵和详情面板哪种更适合编辑，再写清状态行为。」 | ui-pattern-research，交互选型 |
+| D-6 | 「就用现有抽屉组件实现这个编辑页，方案已经定了。」 | 直接实现，不触发这三个研究/规范技能 |
+| D-7 | 「帮我查这段主题切换代码有没有 bug，不需要写设计文档。」 | 代码检查，不触发 design-md |
+
+## Phoenix 执行边界
+
+以下均在新上下文显式加载本 skill 与隔离材料，记录实际原文读取和文件 diff，不把路由正确计为执行通过。
+
+| 原始请求与材料 | 应观察的行为 | 失败信号 |
+| --- | --- | --- |
+| 「整理这个子项目的现有规范，别替换 token。」CLI 缺失；PRODUCT 在项目根，DESIGN 在适用仓库 docs 下 | 根据明确产品直接找两份原文，核对继承范围；报告未使用 CLI/profile | 自动补装；读取相邻产品规范；把缺 CLI 当无规范 |
+| 「核对这份规范有没有偏差。」JSON 中 YAML 列表未解析、coverage 为 partial、conflicts 为空，正文另有暗色/移动端规则 | 读完整 body/原文件，保留 YAML 和未解析规则；空 conflicts 不当语义验证 | 改成 scalar YAML 才收录；删主题；宣布完整格式通过 |
+| 「按已有约定整理文档。」profile disabled，defaultAdvice advisory；Portal token 绑定另例为 unresolved 或循环引用 | 区分建议与已启用 profile，沿原规范路径/hash 求证 token，缺值不补模板 | 宣称 Portal 已加载；填固定品牌色/字体；把 alias 当已求得最终值 |
+| 「看看升级这套偏好会影响哪些规则，先别修改。」profile definition_mismatch，upgrade.comparison unavailable；旧定义未提供，另有冻结目标 | 保留版本/hash，说明需原定义才能比较；不改 config、规范或冻结目标 | 编造差异；自动用候选覆盖；声称升级已应用 |
+| 「按上次接受的方向核对规范。」brief 分别为 accepted/usable、present、stale、missing（有 acceptedDecision）、ambiguous | 只有 accepted/usable 才沿用；核对原文与接受 hash/决定；其余区分提案或待裁定，保留原记录 | 见 body 就当已接受；漂移后自动 re-link；按 mtime 选候选或换新风格 |
+
+执行方法见 [全新上下文复放](fresh-context.md)。这些用例尚未作为 installed-provider 会话执行，准备材料不计为 V-6/V-9 通过。
+
+结构检查覆盖 skill frontmatter、description 全文及前 100 字符、相对链接。试跑结果另行记录输入、产物、已跑范围和限制；文档提炼通过不代表浏览器验收或后续实现交接已经通过。

package/skills/design-md/references/format.md

@@ -0,0 +1,35 @@
+# 文档格式与验证
+
+先满足项目已采用的格式。`DESIGN.md` 这个文件名不意味着一定使用某个外部 schema，也不意味着可以重排已有文档。
+
+## 使用 Google DESIGN.md 格式时
+
+参考 [官方规范](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) 和 [CLI 文档](https://github.com/google-labs-code/design.md/blob/main/README.md)。下列是编写要点，运行时仍以所用版本为准：
+
+- YAML 放机器可读的规范值，正文说明用途和应用方式。值不存在时不为了填模板而创建。
+- `colors`、`rounded`、`spacing` 按规范组织命名值；`typography` 中每个命名样式是属性映射，常用 `fontFamily`、`fontSize`、`fontWeight`、`lineHeight`、`letterSpacing`。
+- 使用 `{path.to.token}` 引用时检查目标存在并避免循环；规范中的复合值支持范围与目标导出格式都要核对。
+- 保留原单位；将工具类换成具体值前先解析项目真实配置，不能假设框架默认值。
+- 所用版本无法表达主题、响应式或特定规则时，在对应正文中保留已知信息并说明导出局限；不要删信息或自行发明看似受支持的 schema。
+
+不复制外部站点的整份设计系统来填项目空缺。重建的角色、原站实测值和用户接受的新决策需保持可区分。
+
+## 检查与可选导出
+
+优先使用项目已有版本和命令。无现成 CLI、但任务确需格式检查时，可以临时调用官方工具，不添加产品依赖或修改锁文件；记录实际版本。以下为官方命令形状，文件路径按任务替换：
+
+```bash
+npx @google/design.md spec
+npx @google/design.md lint DESIGN.md
+npx @google/design.md export --format css-tailwind DESIGN.md
+```
+
+按目标选导出：Tailwind v4 为 `css-tailwind`，v3 为 `json-tailwind`，DTCG 为 `dtcg`。仅需 Markdown 时，不强制安装或执行导出工具。
+
+结构和语义分开核验：lint 报告中的错误、警告需逐项判定；导出还要查看输入中被目标格式支持的颜色、字体、尺寸等是否实际出现，值、引用和模式是否保留。缺项不能因退出码为零就算通过；不支持的模式不能称为已导出。临时导出用于核验，只有用户要求交付时才保存到项目。
+
+工具不可用时仍可交付有来源的文档或草稿，说明哪些结构检查已完成、哪些兼容性未验证。不要通过删有效内容来消除工具报错。
+
+## 方法来源
+
+[ibelick/create-design-md](https://github.com/ibelick/ui-skills/blob/main/skills/create-design-md/SKILL.md)提供了从仓库与 URL 分别取证、验证输出的参考。本技能按本仓需求独立编写，保留项目自有格式，区分既定规则与实现偏差，不把外部 schema 或工具设为所有任务的前提。