od-contribute

od-contribute — OpenDesign 首次贡献流程

专用于 nexu-io/open-design。根据贡献类型而非 Issue 进行分支。用特定类型的无代码验证器替代开发循环。旨在让没有任何编程背景的产品用户也能提交真正的 PR。

语言

所有面向用户的消息都应使用与用户相同的语言，包括 AskUserQuestion 的标签和描述、状态更新、错误说明。根据用户的第一条消息检测语言；不确定时，默认使用英语。

生成的产物（PR 标题、提交消息、PR/Issue 正文文件、分支名称）无论用户的聊天语言是什么，都必须使用英语。 GitHub 惯例、维护者审核和搜索都默认使用英语。templates/ 下的模板已经是英语——渲染时保持原样。

脚本位于 scripts/ 下。任何脚本都可以引入共享辅助函数：

source "$(dirname "$0")/config.sh"

下文中的 SKILL_DIR = 包含此 SKILL.md 的目录。

---

第 1 步 — 前置条件检查（始终首先执行）

bash "$SKILL_DIR/scripts/check-prereqs.sh"

• 退出码为 0：从标准输出中获取 GH_USER=<login>。默认设置 TARGET_FORK="${GH_USER}/open-design"。
• 退出码为 2：逐字向用户展示打印出的安装 / 身份验证提示，然后停止。不要尝试绕过令牌验证。

如果 gh repo view "$TARGET_FORK" 失败，询问用户（一次 AskUserQuestion）是否现在通过 gh repo fork nexu-io/open-design --clone=false 创建 Fork。默认选择是。

第 2 步 — 选择贡献类型

单次 AskUserQuestion（标题："Contribution"，multiSelect: false），提供四个选项。将选项标签 / 描述翻译成用户的聊天语言；分支路由保持不变。

1. 🎨 提交我用 OD 制作的内容 — 我想向上游贡献的 Skill、Design System、HyperFrame 或模板 → 分支 3a
2. 🌍 翻译 OD 文档 — 将 README / QUICKSTART / CONTRIBUTING 翻译成一种新语言 → 分支 3b
3. 📝 修正文档 / 写博客 / 修正拼写错误 — 修正拼写错误、修复失效链接、撰写用例 → 分支 3c
4. 🐛 报告 Bug — 出了问题；我会协助将其整理成高质量 Issue → 分支 3d（Issue 路径，不创建 PR）

以下各分支均为独立流程。第 7–8 步（预览 + 推送）由分支 3a/3b/3c 共用。分支 3d 完全跳过这两步。

---

第 3a 步 — OD 产品提交（Skill / Design System）

3a.1 询问用户："你想提交的产物在本地的路径是什么？"（单条自由文本，用用户的聊天语言提问）。常见路径：文件夹路径（Skill）或单个 DESIGN.md 文件（Design System）。

3a.2 检测类型：

# Skill: folder containing SKILL.md with frontmatter.
# Design System: file matching DESIGN.md anatomy.

如果无法确定，请用户确认。

3a.3 运行设置：

bash "$SKILL_DIR/scripts/setup-workspace.sh" skill <slug>
# or
bash "$SKILL_DIR/scripts/setup-workspace.sh" design-system <slug>

<slug> 是对 Skill name 前置元数据字段或品牌名称调用 od::slugify 的结果。从标准输出中获取 WORKDIR。

3a.4 将产物复制到工作区中相应的目标目录：

• Skill → $WORKDIR/skills/<slug>/
• Design System → $WORKDIR/design-systems/<brand-slug>/DESIGN.md（以及同一文件夹中的任何同级资源）

3a.5 验证：

bash "$SKILL_DIR/scripts/validate-skill-submission.sh" "$WORKDIR/skills/<slug>"
# or, with 1-2 reference DESIGN.md files passed in:
bash "$SKILL_DIR/scripts/validate-design-system.sh" \
  "$WORKDIR/design-systems/<slug>/DESIGN.md" \
  --reference "$WORKDIR/design-systems/airbnb/DESIGN.md" \
  --reference "$WORKDIR/design-systems/apple/DESIGN.md"

如果验证失败，逐字展示 FAIL 行，要求用户修复，然后重试。绝不要推送未通过验证的产物。

3a.6 通过 AskUserQuestion 提出 3 个简短问题（将标签翻译成用户的聊天语言）：

• "PR 中应使用什么名称署名？" — 自由文本
• "用一句话介绍这个 Skill / Design System？" — 自由文本
• "截图路径（可选）？" — 自由文本

3a.7 使用以下替换项渲染 templates/PR-BODY-skill.md（或 PR-BODY-design-system.md）：

• {{SKILL_NAME}}、{{SKILL_SLUG}}（或 {{BRAND_NAME}}、{{BRAND_SLUG}}）
• {{PITCH}}（一句话介绍）
• {{MOTIVATION}}（自由文本——Agent 可以根据 Skill 正文提供草稿，但需由用户确认）
• {{TRY_PROMPT}}（建议尝试的提示词——Agent 提供默认建议，用户确认）
• {{SCREENSHOT_BLOCK}}（如果提供了截图路径，则使用 Markdown 图片块；否则留空）
• {{DISCORD_INVITE}}，取自 $OD_DISCORD_INVITE

写入 $WORKDIR/.od-contrib/PR-BODY.md。

→ 跳转到第 7 步。

---

步骤 3b — i18n 翻译

3b.1 设置工作区（如果已知，slug = translate-<doc>-<lang>，否则为 translate）：

bash "$SKILL_DIR/scripts/setup-workspace.sh" i18n translate
# capture WORKDIR

3b.2 发现待补全项：

bash "$SKILL_DIR/scripts/discover-i18n-gaps.sh" "$WORKDIR" > /tmp/od-i18n-gaps.json

每行都是 JSON。按以下顺序排序：

• 优先 status: "missing"（补充缺失语言的收益最高）
• 然后是 status: "stale"，按 english_commits_since_translation 降序排列
• README 系列优先于 QUICKSTART，QUICKSTART 优先于 CONTRIBUTING

3b.3 选取排名靠前的 3–4 个待补全项，通过 AskUserQuestion 呈现（标题：「翻译目标」）。每个选项的标签类似于：README → 한국어 (Korean) / QUICKSTART (zh-CN) refresh — 12 commits behind。将标题文本翻译成用户聊天所用的语言，但选项标签要清晰易懂（语言名称使用其本国语言的文字）。

3b.4 用户选择后，将分支重命名为具体名称：

git -C "$WORKDIR" branch -m "od-contrib/i18n/<doc>-<lang>-<date>"

（或者，如果用户此前已确认，可以在步骤 3b.1 中预先设置 slug。）

3b.5 翻译。阅读英文源文件。翻译时保留结构：

• 代码块：不翻译
• 品牌／产品名称：不翻译
• 行内代码中的文件名：不翻译
• 图片／链接目标：不翻译；如果链接文档有本地化版本，则将链接替换为本地化文件
• 标题：翻译，保持标题层级不变
• 表格：只翻译单元格文本，保持对齐方式／竖线不变

将结果写入 $WORKDIR/<TRANSLATED_PATH>（例如 QUICKSTART.es.md）。向用户展示与英文源文件对比的 unified diff，供其快速检查（行数差异在 ±15% 内是合理的参考信号）。

3b.6 根据英文源文件验证译文。--reference 标志会告诉验证器忽略源文件中已有的失效相对引用——OD 文档经常会链接到网站路由 slug（例如 skills/blog-post/），而这些并非磁盘上的文件；我们不希望结构保持一致的翻译因为源文件中已有的失效引用而验证失败。

bash "$SKILL_DIR/scripts/validate-markdown.sh" \
  "$WORKDIR/<TRANSLATED_PATH>" \
  --reference "$WORKDIR/<ENGLISH_PATH>"

如果失败 → 原样呈现失败信息，修复并重试。

3b.7 使用 {{DOC_NAME}}、{{LANG_DISPLAY_NAME}}、{{LANG_CODE}}、{{TRANSLATED_PATH}}、{{ENGLISH_PATH}}、{{STATUS}}、{{TRANSLATION_NOTES}}（由 Agent 撰写的一段说明：任何棘手之处、保留不译的术语等）、{{DISCORD_INVITE}} 渲染 templates/PR-BODY-i18n.md。

→ 步骤 7。

---

步骤 3c — 文档／博客／错别字

3c.1 设置工作区（slug 为 docs）：

bash "$SKILL_DIR/scripts/setup-workspace.sh" docs <slug>

3c.2 向用户提问（调用一次 AskUserQuestion）：

1. 自动发现小型修复项（运行 discover-doc-gaps，挑选一项）
2. 我有明确的修复想法（自由文本）
3. 我想写一篇博客／案例研究（自由文本——使用场景是什么？）

3c.3（自动发现分支） 运行：

bash "$SKILL_DIR/scripts/discover-doc-gaps.sh" "$WORKDIR" > /tmp/od-doc-gaps.json

按 kind（typo / deadlink / todo）分组。通过 AskUserQuestion 向用户展示最多 6 个候选项。用户选择后，在代码中应用修复（typo：替换词语；deadlink：询问用户新的 URL；todo：这属于正式任务，请用户补写缺失内容）。

3c.4（特定修复分支） 阅读文件，应用用户描述的更改。通过 diff 确认。

3c.5（博客分支） 首先检查 OD 是否有博客目录：

ls "$WORKDIR/docs" 2>/dev/null

如果存在 docs/blog/ 或类似目录，将新文章放在那里。如果没有，询问用户希望放在哪里，默认使用 docs/<slug>.md。生成大纲 → 用户补充特定于自己的内容（使用场景、截图、使用的提示词、渲染结果）→ Agent 将内容整合成最终的 Markdown。

3c.6 验证所有已更改／新增的文件。对于仓库中已存在的文件（错别字修复、失效链接修复、文档编辑），传入指向 HEAD 版本的 --reference，这样我们只会对用户引入的相对引用失败，而不会因已有的路由 slug 而失败：

# For modifications to existing files:
git -C "$WORKDIR" show "HEAD:<path>" > "/tmp/od-contrib-orig-<basename>" 2>/dev/null
bash "$SKILL_DIR/scripts/validate-markdown.sh" \
  "$WORKDIR/<changed-path>" \
  --reference "/tmp/od-contrib-orig-<basename>"

# For brand-new files (e.g. a blog post the user is creating from scratch),
# omit --reference. The validator will skip the relative-ref check entirely
# (since it can't tell route slugs from real paths in isolation).

3c.7 使用 {{ONE_LINE_SUMMARY}}、{{DETAILS}}、{{FILES_LIST}}、{{DISCORD_INVITE}} 渲染 templates/PR-BODY-docs.md。

→ 步骤 7。

---

步骤 3d — Bug 报告（issue 路径，不创建 PR）

3d.1 在运行时读取 OD 的实际 schema，确保我们与其保持一致：

gh api "repos/${TARGET_REPO}/contents/.github/ISSUE_TEMPLATE/bug-report.yml" --jq .content | base64 -d > /tmp/od-bug-report.yml

如果 schema 与模板（templates/ISSUE-BODY-bug.md）不一致，请重新生成正文以匹配。

3d.2 通过 AskUserQuestion 向用户提问，每个关键字段使用一个结构化问题。使用通俗易懂的语言，不要使用 YAML 字段名：

Bug 报告字段	向用户提问
description	“出了什么问题？用一句话说明即可。”
steps	“如何复现？请逐步说明。”
expected	“你预期会发生什么？”
version	“你正在运行哪个 OD 版本？（查看 About 菜单，或运行 od --version）”
platform	下拉选项：macOS（Apple Silicon）/ macOS（Intel）/ Windows / Linux / Other
logs	“可以粘贴任何错误日志吗？没有的话可以跳过。”
screenshots	“截图路径是什么？没有的话可以跳过。”

运行时将上述每个问题翻译成用户的聊天语言。

3d.3 自动收集可获取的信息（无需询问用户）：

• 使用 uname 获取 OS 系列
• 如果相关，使用 node -v 获取 Node 版本

3d.4 去重：从描述中提取 3–5 个关键词，运行：

gh search issues "<keywords>" --repo "$TARGET_REPO" --state open --limit 5 --json number,title,url

如果找到匹配项，通过 AskUserQuestion 呈现给用户（翻译成用户的语言）：“这些已有 issue 看起来与此相关。你想要：（a）在现有 issue 下评论，（b）仍然创建新 issue，（c）取消？”

3d.5 如果决定创建新 issue，渲染 templates/ISSUE-BODY-bug.md 并提交：

bash "$SKILL_DIR/scripts/create-issue.sh" \
  --title "$TITLE" \
  --body-file "$WORKDIR_OR_TMP/.od-contrib/ISSUE-BODY.md" \
  --dedupe-keywords "<keywords>"

3d.6 单独一行打印 issue URL。不要从此分支推送分支或创建 PR。

---

步骤 7 — 预览并确认（共用，仅适用于 PR 分支）

向用户展示简洁的摘要：

About to commit:
  Branch:  od-contrib/<type>/<slug>-<date>
  Files:
    + skills/foo/SKILL.md            (1.2 KB)
    + skills/foo/preview.png         (54 KB)
  Push to:  <fork or upstream>
  Open PR:  nexu-io/open-design:main ← <fork>:<branch>

然后运行 git -C "$WORKDIR" diff --stat，并查看渲染后的 PR 正文前 40 行（head -40），以检查显示效果。

必须通过 AskUserQuestion 请求确认（翻译成用户的语言）：“推送此 PR 吗？”，并提供三个选项：

• 提交 — 继续执行步骤 8
• 让我修改 — 返回相关的步骤 3 子步骤
• 取消 — 将工作区保留在磁盘上，告知用户路径以便之后返回，然后退出

未经明确确认“提交”，绝不推送。

步骤 8 — 推送并创建 PR

bash "$SKILL_DIR/scripts/create-pr.sh" \
  --workdir "$WORKDIR" \
  --type "<skill|design-system|i18n|docs>" \
  --title "<PR title from references/newcomer-tone.md>" \
  --body-file "$WORKDIR/.od-contrib/PR-BODY.md"

单独一行打印 PR URL。完成。

---

安全护栏（必需）

• 绝不推送到 main / master / develop。推送脚本会拒绝此操作。
• 绝不使用 --force 推送。切勿这样做。
• 所有工作区活动都必须位于 $OD_WORK_ROOT 下（默认为 $HOME/od-contrib-work）。od::assert_in_workroot 会强制执行此规则。
• Bug 报告路径在运行 gh issue create 前始终执行去重搜索。
• 遵循用户记忆：从任何贡献者查询中跳过 GitHub 用户 xxiaoxiong（[[feedback_no_outreach_xxiaoxiong]]）。

何时不应使用此技能

• 用户想修复 daemon / web Bug，或通过代码更改添加功能 → 改用 auto-github-contributor（它包含 TDD 循环）。此技能有意不运行 lint/typecheck/tests，因为内容路径不需要这些检查。
• 用户想从头开始生成 Skill / Design System → 那就是 OpenDesign 本身。先运行 OD 并获取产物，然后再回到这里发布。