qufei1993/skills-hub

# 设计有效测试，修复不可靠的验证

阅读[项目上下文](references/project-context.md)和[验证证据](references/evidence.md)。新增覆盖或审查覆盖情况时选择测试设计；已经观察到间歇性失败时选择偶发失败诊断。任务需要时才组合两者。诊断或测试计划请求保持只读，除非用户要求实现。

## 设计或审查测试覆盖

1. 阅读[测试选择](references/test-strategy.md)。将变化的行为对应到真实调用方和失败风险，再检查已有覆盖与必需检查。
2. 对每个重要缺口，选择测试层级、真实入口、测试替身和独立断言。说明 mock 会绕过什么。手工组装的单元样例无法检出缺陷时，使用真实入口验证组件组装。
3. 复用已经能够发现风险的测试。只有用户要求实现覆盖时才添加测试；计划任务给出具体用例和期望结果。
4. 已实现的回归测试或防护检查，应有会失败的错误对照和会通过的合法样例。执行相关检查和项目必需检查，分清实际执行、建议执行与受阻的检查。

## 诊断偶发失败

阅读[测试可靠性](references/test-reliability.md)。

# 构建和审查易用的客户端界面

阅读[项目上下文](references/project-context.md)和[UI 规则](references/ui.md)。运行验证使用[验证证据](references/evidence.md)。审计任务保持只读；视觉审查本身不授权重新设计。

1. 明确用户任务、已有组件和设计变量体系、语言资源维护位置及平台。改变呈现方式前，先追踪状态和用户操作。
2. 梳理适用的加载、空内容、已编辑、保存中、成功、失败和取消状态。反馈的持续时间应匹配尚未完成的工作。失败时保留草稿与选择，并提供用户能找到的恢复操作。
3. 检查交互责任：禁用和等待行为、重复触发、键盘与焦点、弹窗进入退出及焦点返回。保证背景内容与浮层顺序一致。不绕过语言资源管理，把产品文字直接写在其他位置。
4. 使用目标项目的组件和设计变量实现响应式布局。按项目无障碍要求，检查窄屏、桌面、长内容及缩放状态。
5. 按项目文档启动或识别当前构建。确认实际运行的产物，再使用可用浏览器工具操作真实控件并查看截图。检查失败反馈和键盘行为，不能只看 DOM 元素存在。缺少浏览器或运行环境访问时，标明视觉验证受阻。

报告受影响的用户状态、视口和交互证据，以及剩余缺口。仅凭静态代码检查，不能认定视觉或响应式验收完成。

# 按真实行为要求审查代码

阅读[项目上下文](references/project-context.md)、[验证证据](references/evidence.md)以及改动区域的实际需求。除非用户要求修复，否则保持只读。未经用户授权，不向外部发布审查意见。

1. 明确准确的基线与目标提交，或本地差异及暂存、未暂存等修改层。审查远端 PR 时获取其当前引用；目标分支或内容更新后重新确认。
2. 将变化的接口对应到实际数据提供方和调用方。判断差异前，阅读周边代码、相关决策和项目必需检查。
3. 优先检查正确性、安全、生命周期和必需行为是否损坏。资源或错误处理变化读[生命周期](references/lifecycle.md)；异步测试读[测试可靠性](references/test-reliability.md)；可见界面读[UI](references/ui.md)；文字变更读[文档写作](references/prose.md)。默认值、校验、依赖或抽象变化读[编码规范](references/code-conventions.md)；覆盖率或测试设计问题读[测试选择](references/test-strategy.md)。
4. 追踪校验是否真正保护了目标操作，包括其他入口和直接调用方。检查边界值、最终输出或保留内容的大小，计入元数据和多字节文本。核实取消、部分成功、资源释放和派生状态。
5. 检查实际交付入口、公开导出、构建是否为当前版本以及真实测试证据。重要结果应有独立断言，新增约束应有会失败的错误样例。检查全绿或作者自述不能代替语义审查，也不要无故重跑无关的高成本检查。
6. 检查必要性：每个抽象、兼容分支和通用 API 都应有当前行为要求或调用方。不要仅凭文本搜索结果猜测并移除受支持行为。
7. 确认当前文档、默认值、错误和界面文字与代码一致。翻译改动已经在范围内时检查含义，不自行启动翻译任务。

只报告可采取行动的问题，包含文件和行号、具体触发条件、影响及证据。区分缺陷与可选建议，不为凑数量而编造问题。没有充分依据的问题时直接说明，并指出重要覆盖限制。审查发现不等于获得修改或推送权限。

# 维护有用的工程文档

阅读[项目上下文](references/project-context.md)和[文档写作](references/prose.md)。创建文档前，先找到现有负责维护相关事实的位置。

1. 明确读者、任务和实际源码行为。涉及默认值、输入输出、失败恢复及兼容性时，阅读实现和真实示例。
2. 选择下面与任务有关的流程，只组合请求需要的部分。
3. 优先修改事实的现有维护文档，更新导航和指向它的链接，并在任务范围内清理矛盾的重复说明。沿用项目的文档约定和语言。
4. 验证示例、路径和链接，对照代码检查语义。格式检查不能证明事实正确或内容完整。适用时执行项目必需检查。

## 当前行为文档

说明前置条件、受支持用法、代表性示例、重要限制和失败行为。注释解释行为约定或不明显的选择，不记录修改过程。公开行为变化时，在同一次改动中更新读者实际使用的入口文档。

## 决策和事故记录

# 应用和维护 DSH 工程规范

先读[项目上下文](references/project-context.md)和[验证证据](references/evidence.md)。按用户任务选择下面的流程。普通开发使用“用于日常开发”；接入或迁移项目规范需要对应的任务要求。

## 用于日常开发

1. 阅读受影响的代码、实际调用方和项目必需检查。先明确要实现的行为，再选择抽象或调整约定。
2. 涉及实现或设计选择时，读[编码规范](references/code-conventions.md)；涉及行为变化时，读[测试选择](references/test-strategy.md)。按当前任务检查默认值、输入校验、依赖方向、扩展点和测试覆盖，不顺带清理无关代码。
3. 用户要求实现时完成实现；要求设计或审查时给出具体方案或结论。验证相应真实入口和必需检查，区分已执行与建议执行的检查。已安装且与任务有关时，使用专门的审查、错误处理、UI 或性能 Skill；本 Skill 自带所需的基础规则。
4. 必要时更新现有行为文档。不要仅因开发一个功能或修复一个问题，就创建接入记录、新的 Agent 指令或工程手册。完成时说明行为变化、实际证据和重要限制。

## 修改规范前先诊断

1. 明确请求属于诊断、接入、更新还是撤销。诊断保持只读。

# 明确失败行为及处理责任

阅读[项目上下文](references/project-context.md)、[生命周期](references/lifecycle.md)和[验证证据](references/evidence.md)。沿用项目现有的错误约定。

1. 追踪操作的公开入口、状态负责方、外部副作用和最终报告。建立简短对应关系：触发条件 → 错误分类 → 状态保证 → 处理者 → 用户可见结果。区分响应失败与操作失败。
2. 用稳定标识区分已知业务错误；保留意外错误的原因，不把所有异常都转成成功默认值或同一个通用业务错误码。
3. 明确失败后状态属于未变化、部分完成、已提交还是结果未知。只有状态负责方能证明恢复和继续执行的前提；无法证明时停止依赖该状态的后续工作。写入结果不明确时，使用真实服务支持的核对或幂等机制，不能仅根据异常文字无条件重试。
4. 确保取消、回调错误和清理失败到达适当的处理位置。避免重复报告；保留足够的处理线索，不泄露秘密。
5. 通过真实调用方验证副作用发生前后的失败，包括“已经提交但响应丢失”。分别断言可观察状态和报告内容；支持恢复时，覆盖恢复成功和恢复失败。

完成时说明明确的状态保证、负责的处理者和实际测试的失败场景。服务行为约定不足以建立保证时，如实报告结果未知。

# 在保留行为的前提下简化维护

阅读[项目上下文](references/project-context.md)和[验证证据](references/evidence.md)。涉及保留状态或资源负责方时读[生命周期](references/lifecycle.md)；涉及依赖方向、默认值或扩展点的实际必要性时读[编码规范](references/code-conventions.md)。

1. 明确必须保持的行为：公开入口、受支持版本和数据、错误、顺序、取消，以及当前调用方。审查请求给出建议；实现请求可以落实有依据的简化。
2. 追踪候选抽象、重复状态和兼容路径的实际提供方与调用方，包括动态注册、插件、反射和外部使用者。没有直接文本匹配，不能证明公开 API 无人使用。
3. 优先移除多余的负责方、重复约束、不必要的状态转换或无用选项。解释减少了哪些维护责任。仅仅减少行数，可能掩盖职责或把复杂性转移给每个调用方。
4. 用必须保留的行为要求评估一个具体、更小的设计。已发布数据或调用方需要适配器时保留它，不为猜测中的需求增加兼容逻辑。
5. 需要实现时做聚焦改动，验证真实入口和边界情况。用独立断言比较输出、失败行为和生命周期。维护模型变化时更新其负责文档。

报告减少的维护责任、保留的行为、验证证据，以及阻止进一步简化的兼容约束。不顺带重写无关部分。

# 验证是否具备交付条件

阅读[项目上下文](references/project-context.md)和[验证证据](references/evidence.md)。本流程负责验证；推送、提交和部署须属于相应任务范围。

1. 检查当前改动、适用指令、清单、构建脚本和 CI。将必需检查与有针对性的辅助检查分开。即使只改文档，也保留项目要求的完整检查。
2. 确认前置条件以及实际测试的源码或构建产物。需要时重新构建，并验证运行入口确实使用该产物。根据实际进程和产物识别旧服务，不能只看熟悉的端口或页面标题。
3. 执行必需检查，记录命令、退出状态、选中的用例和输出。查明失败原因，不通过删除断言、盲改期望、串行化测试或添加重试掩盖问题。资源或并发故障使用[测试可靠性](references/test-reliability.md)。不得隐瞒工具缺失或网络失败。
4. 验收规则变化时，在隔离样例中故意违反规则，确认真实检查入口会拒绝，再确认合法样例通过。现有检查未覆盖的行为，应通过真实调用方验证并查看结果。
5. 检查最终差异和工作区状态，确认没有意外修改、生成产物遗漏或陈旧文档。修复改变了被测内容时，重跑受影响检查；不能声称早先证据适用于后来的文件状态。

只有全部必需检查和变化的行为都有证据支持时，才报告“可以交付”。否则明确列出失败、跳过、未运行或环境阻塞的检查，以及下一步最小操作。单元测试通过，但必需集成检查失败或交付构建陈旧，仍不具备交付条件。

# 录制并核验真实应用演示

用户要求浏览器演示 GIF 时使用。阅读[项目上下文](references/project-context.md)和[验证证据](references/evidence.md)。默认在本地采集；上传、发布或发送须属于用户明确要求的范围。不得伪造应用画面或成功状态。

1. 设计简短的用户操作过程，通常包含 3–6 个有意义的状态。检查项目启动和构建命令，确认实际运行的产物与版本。全程使用相同的应用源地址、进程或运行实例、视口和会话。录制前先处理旧服务，不能录完再解释。
2. 使用可用浏览器工具真实操作并截图或录屏。优先用环境已有工具，项目声明的浏览器测试库可作备用。缺少浏览器或凭据意味着受阻，不允许合成画面代替。
3. 等待可观察状态，不靠固定休眠。逐一查看采集状态，不隐藏相关失败，避免暴露凭据和私有用户数据。将原始采集文件及状态说明保存在本地证据目录。
4. 确认已安装 `ffmpeg` 和 `ffprobe`，运行自带[编码器](scripts/encode_gif.py)：
   `python3 <skill-dir>/scripts/encode_gif.py <frames-dir> <output.gif> --durations 1,2,2`。
   视频裁剪、速度和末帧停留参数见 `--help`。至少需要两帧，且尺寸一致。默认限制为 5 MiB、宽度 1200、10 fps，可按目标用途调整。没有覆盖原文件的意图时，不使用 `--force`。
5. 读取编码器实际退出状态，以及 JSON 中的尺寸、帧数、时长和大小。编码失败仍可能留下输出文件，文件存在不等于成功。必须从 GIF 本身解码检查帧顺序、调色板、时间和可读性；仅查看源截图无法验证编码结果。
6. 返回本地 GIF，附简短说明和当前应用运行证据。文件过大或不可读时，保留操作过程，调整时长或缩放后重新核验。查看最终文件后，只发布到用户明确指定的目标。

# 优化实际测量的用户路径性能

阅读[项目上下文](references/project-context.md)和[验证证据](references/evidence.md)。明确真实负载和独立正确性判据前，不开始优化。

1. 确定用户可见操作、入口、代表性输入规模、环境和性能现象。定义正确性、延迟或吞吐量，以及有关的峰值和保留内存指标。分开测冷启动与预热后的稳定状态。
2. 在真实产物上建立基线。记录版本、构建、运行环境、输入、命令、重复次数和结果分布，不能只取最快一次；保留可观察输出。
3. 用性能分析或测量代码定位怀疑的瓶颈，验证一个因果假设。加入错误对照，区分真正瓶颈、测量噪声和悄悄省略的工作。不得牺牲必需记录、顺序或错误行为。
4. 实施有依据的最小优化。涉及缓存时，按[生命周期](references/lifecycle.md)验证缓存键是否完整、失效规则、存续时间和保留内存上限。
5. 重新构建，在等价条件下复测；有帮助时交替测优化前后。独立验证输出等价和失败行为。变化可能在冷路径、热路径或内存之间产生取舍时，检查相应指标。同时报告收益和退步；噪声淹没差异时，说明改进尚未证实。

报告实际数字、测量条件、正确性证据和取舍。不得将复杂度估算、微基准测试或省略工作得到的结果，当作已经测得的端到端提升。

# 翻译或同步明确指定的文档

只有用户明确调用本翻译流程时才执行。代码或文档审查、源文件变化、配对哈希过期，都不自动授权翻译。阅读[项目上下文](references/project-context.md)和[文档写作](references/prose.md)。

1. 明确源语言、目标语言、变化的文档，以及项目术语和配对约定。一次修改可以以任一语言为准，不默认英文永远优先。只有双边修改冲突、无法安全选择时才询问，同时继续无歧义文档。
2. 完整阅读相关段落及实际技术上下文。翻译指定变化，并根据连贯性需要处理周边文字；保留结构、链接、代码块、协议标识符、示例和可执行命令。
3. 逐句比较含义：义务、否定、默认值、条件、数值限制、例外和恢复行为。译文应自然，但不能把“禁止”弱化成建议，也不能补造缺失行为。
4. 保留两边各自的独立修改，在具体冲突段落明确解决。完成语义审查后才更新配对元数据；项目已有配对工具时使用该工具。
5. 检查链接、呈现和必需检查。报告翻译路径、源语言方向、术语选择和未解决的歧义。哈希一致只是记录一致，不能证明翻译准确。

# Manage Skills Hub

Translate the user's requested Skill operation into the trusted `skillshub-cli` commands below. By default, an AI installation includes syncing to detected, enabled tools in Skills Hub; explicit user scope takes precedence. Keep device sync, automation, credentials, and application settings in the desktop app.

## Resolve a trusted CLI before every workflow

1. Inspect `~/.skills-hub/bin` without executing a binary. Only when that directory is completely absent, inspect `~/.skills-hub-dev/bin` as the desktop development bridge. These desktop profiles share the Skill library, but keep credentials separate. On Windows expand the user's home directory and use `skillshub-cli.exe`; otherwise use `skillshub-cli`. Never switch to another bridge when the selected directory exists but fails validation.
2. If that bridge directory exists (including a broken link or inaccessible path), require a regular executable binary and both regular stamp files `skillshub-cli.version` and `skillshub-cli.sha256` in that directory. Read only these public stamps. Validate a nonempty version and a 64-digit hexadecimal SHA-256 value, then compute the binary's SHA-256 with the platform's hashing utility and require an exact match. Reject symlinked stamps/binaries and unresolvable paths. Do not execute an unverified binary.
3. After hash validation, bind `$CLI` to that absolute binary path and run `$CLI --json version`. Require exit 0, `ok: true`, and `data.version` equal to the version stamp. Missing files, invalid stamps, mismatched hash/version, execution failure, and malformed output mean **bridge damaged**: fail closed, stop, and ask the user to open Settings → AI management in the desktop app and click Enable in one click to install or repair the CLI bridge. First-time installation or repair requires this explicit click; update the CLI and official Skill explicitly in Settings → AI management. Startup only checks status and does not update them. Never fall back to PATH when the bridge location exists but fails validation. Do not repair or edit stamps yourself.
4. Only when the desktop bridge directory is completely absent, resolve `skillshub-cli` from PATH for a CLI-only environment. Bind `$CLI` to the resolved absolute path and run `$CLI --json version`. If unavailable, explain installing Skills Hub and enabling AI management in Settings. Do not silently install software.

`$CLI` below denotes that verified executable, not a literal command or shell fragment. Pass arguments as distinct values; quote paths correctly and never evaluate user input as shell code. Read-only bridge inspection and hashing are the only filesystem work this workflow needs.

## Interpret machine results