Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
127 lines (94 loc) · 8.34 KB

CONTRIBUTING.md

File metadata and controls

127 lines (94 loc) · 8.34 KB
Raw

贡献指南

感谢改进 Computer Repair Skill。提交 Issue 或 Pull Request 前，请先确认变更属于电脑诊断、修复、安全工作流、平台工具映射或 Playbook 维护范围。

开发原则

  • 保持 SKILL.md 精简，把具体平台和专项流程放在 references/ 中按需加载。
  • 保持只读优先。任何安装、删除、权限、服务、启动项、凭据或安全控制变更，都必须先说明影响、回滚和验证方式，并等待用户确认。
  • 不假设宿主存在 Playbook 中的语义工具名；通过 tool-contract.md 映射到宿主能力或平台原生命令。
  • 不提交密码、令牌、私钥、Cookie、真实设备标识或未经脱敏的日志。
  • 不在网页读取失败后根据标题或 URL 补造内容。

维护 Skill 入口元数据

  • 按 Agent Skills 规范维护 SKILL.md frontmatter。name 和 description 是必填字段；本项目另用 version 对齐发布版本、用 when_to_use 补充中文症状。后两者是项目约定，不应假设所有客户端都会使用它们；不要添加没有实际用途的字段。
  • 按触发描述优化指南让 description 以 Use this skill when ... 表达用户意图，覆盖常见自然语言症状，并写明容易误触的相邻场景。本项目将描述限制为 600 个字符、80 个空格分词，严于规范的 1024 字符上限。
  • 宿主能力、权限、网络和交互要求写在 SKILL.md 正文的能力检查中，避免可选 frontmatter 字段造成客户端兼容差异。
  • 保持 SKILL.md 在 500 行以内。具体平台、工具和专项流程放在 references/，并在核心工作流中明确说明何时加载，避免一次读取全部资料。

修改上游 Playbook

source: bundled 的文件来自 NOTICE 记录的上游基准提交，面向 Agent 的措辞和 author 标记已做中性化适配。项目维护的本地扩展使用 source: local 标记；来源和归属以 NOTICE 为准。同步上游时保留现有行为与中性命名，并在 Pull Request 中注明上游提交、变更文件和行为差异。

项目新增 Playbook 使用以下元数据：

---
name: example-playbook
description: Describe the exact task and trigger
platform: windows
last_reviewed: YYYY-MM-DD
author: computer-repair-skill-maintainers
source: local
---

新 Playbook 还需要：

  • 使用 playbook-<slug>.md 文件名，并登记到 references/playbook-index.md。
  • 让 frontmatter 的 description 不超过 120 个字符且只描述一个明确入口；不要把多个能力堆在同一行。
  • emoji 是可选字段；需要使用时只填一个合适的 emoji，没有合适图标就省略。
  • emoji 的来源约定：source: bundled 的 Playbook 保留上游已有图标，用于在支持图标的 Skill 浏览器中快速识别；source: local 的新 Playbook 默认省略，只有确实有分类价值时才按需添加。emoji 只服务于展示，不参与路由或执行逻辑；校验器会要求它是单个 emoji。
  • 数量统计只包含可执行 Playbook；playbook-authoring.md 和 playbook-index.md 是参考文档，不计入 64 个 Playbook。
  • Tools referenced 中声明的语义工具必须已在 tool-contract.md 或对应平台映射的表格中登记，并与自身 platform 一致：platform: all 的 Playbook 只声明通用工具，不声明 win_*/mac_*/linux_* 专属别名。
  • last_reviewed 填实际复核日期，不能填未来日期。
  • 新增、重命名或重新复核 Playbook 后，结构与复核元数据由 tools/extract_data.py 从 frontmatter 和路由索引重新生成；只需把双语标题、描述和示例提问写进 tools/site_catalog.json，不要手工编辑 docs/assets/js/playbooks.js。随后运行 python scripts/sync_docs_table.py 重建官网的无 JS 回退表格。
  • 官网新增带 data-i18n 的文案时，必须在 tools/i18n_en.json 补上对应英文；缺失或多余的键都会导致验证失败。
  • Markdown 表格单元格里的行内代码遇到竖线要写成 \|，否则会被解析成额外单元格。
  • 给出激活条件、快速只读检查、标准诊断路径、修复前确认、验证、限制和升级信息。
  • 对平台命令提供明确失败处理，不使用宽泛删除或不可审计的命令拼接。
  • 需要凭据时使用宿主安全输入能力，不在上下文或命令历史中回显秘密。

本地验证

仓库构建与核心测试要求 Python 3.10+，无第三方包：

python tools/extract_data.py --check
python tools/build_site.py --check
python tests/validate_skill.py
python -m unittest discover -s tests -p "test_*.py"

官网的 docs/assets/js/playbooks.js 是生成文件。修改 Playbook 的 frontmatter、 路由索引或 tools/site_catalog.json 后，先运行 python tools/extract_data.py 更新 它，再运行上面的 --check；不要直接手工编辑压缩后的 JavaScript。

docs/index.html 里的无 JavaScript 回退表格同样是派生产物。站点数据变化后重建它：

python scripts/sync_docs_table.py
python tools/build_site.py

中文页是唯一需要手工编辑的页面。docs/en/index.html、两个页面里的 JSON-LD、 docs/sitemap.xml 和 docs/llms.txt 都由中文页加 tools/i18n_en.json 的译文生成， 改完中文页或译文后重建：

python tools/build_site.py

英文页是纯静态 HTML，因为不执行 JavaScript 的 AI 爬虫读不到运行时翻译。改中文页时 保留 data-i18n、data-i18n-html 和 data-i18n-attr 属性——生成器靠它们定位可翻译 节点，缺少对应英文译文会直接构建失败。

英文正文只在构建期用得上，所以放在 tools/i18n_en.json（按 data-i18n 的前缀分组）。 docs/assets/js/i18n.js 只留浏览器真正需要的界面字符串——筛选条、计数和详情弹窗的 字段名，不要把正文译文加回去。

文案里的 Playbook 总数（「64 个专项 Playbook」「64 focused playbooks」）和首屏徽标上的 数字不用手工改，build_site.py 会按站点数据统一改写，--check 会拦下过期的数字。

还应在对应平台测试安装器：

test_installers.py 会自动使用已安装的 PowerShell/Bash，在临时目录中验证首次安装、拒绝覆盖、备份、失败回滚、路径重叠、链接目标和并发锁；不会安装到真实 Agent 目录。CI 在 Windows 和 Ubuntu 上执行这些测试。

.\scripts\install.ps1 -Target custom -Destination "$env:TEMP\computer-repair-skills-test"
./scripts/install.sh --target custom --destination "$(mktemp -d)/skills"

官网交互改动可选运行 python tests/browser_site.py --channel chrome（需要本机安装 Python Playwright 和 Chrome，或省略 --channel 使用 Playwright Chromium）。该测试打开本地文件并屏蔽 HTTP(S)，覆盖中英文筛选、焦点、弹窗、复制、移动端和无 JS 回退；不加入无第三方依赖的核心测试。--output <目录> 可保存移动端截图。

发布版本

版本号写在 skills/computer-repair-skill/SKILL.md 与 skills/computer-repair-skill/agents/openai.yaml， 两处必须一致，且 CHANGELOG.md 要有对应的 ## [x.y.z] - YYYY-MM-DD 条目——校验器会检查这三点。 docs/llms.txt 里也带版本号，改完版本记得跑一次 python tools/build_site.py。

具备这些之后不需要手工打 tag：改动合入 main 后，Release 工作流会自动创建 v<version> annotated tag 并发布 GitHub Release，说明正文取自 CHANGELOG.md 的该版本条目。 工作流会先运行 tools/extract_data.py --check、tools/build_site.py --check 与 tests/validate_skill.py，任一失败就不发布； Release 已存在时跳过；只有 tag 而没有 Release 时，检出该 tag、验证后补发，避免把后续提交的内容写进旧版本说明。API 鉴权或网络错误会停止流程。可在 Actions 页面手动 Run workflow 重试。

本地预览某个版本的发布说明：

python tools/release_notes.py                 # 当前版本
python tools/release_notes.py --version 1.1.0

提交前检查 git diff，确保没有打包文件、缓存、凭据或无关改动。安全漏洞不要创建公开 Issue，请按 SECURITY.md 报告。