乔沐 GitHub 发布工具 | Qiaomu GitHub Publisher

Qiaomu GitHub Publisher

将工作项目转化为人们能理解、尝试、加星、安装和信任的 GitHub 仓库。

版权所有 (c) 向阳乔木

• X: https://x.com/vista8
• GitHub: https://github.com/joeseesun/
• 配置来源：~/.agents/skills/qiaomu-profile

核心工作流程

1. 写入前检查仓库：
   • README.md、package.json / 项目元数据、截图、示例、文档、许可证、部署脚本、测试脚本。
   • GitHub 及社区展示面：简介、主页、主题、社交预览、许可证、SECURITY.md、CONTRIBUTING.md、CODE_OF_CONDUCT.md、Issue 模板、PR 模板、发布/变更日志（若存在）。
   • 通过 gh repo view --json name,description,homepageUrl,repositoryTopics,url,defaultBranchRef,isPrivate,licenseInfo 检查 GitHub 远程状态。
2. 确定公共定位：
   • 中英文一句钩子，中文优先。
   • 目标用户及他们应立刻尝试的理由。
   • 明确区分产品价值、技术架构和私有/本地设置。
   • 预期的发布姿态：纯展示、用户可安装的工具、外部贡献者项目、库/包或已部署产品。
3. 将 README 重写或修补为产品页：
   • README.md 是 GitHub 的门面。对于 Qiaomu 拥有的仓库，默认必须中文优先且双语。
   • 中文在前，英文在后。除非用户明确要求纯英文或仓库有记录的非 Qiaomu 上游要求。
   • 允许独立的 README.zh-CN.md，但单独存在不满足此要求；默认的 README.md 必须先显示中文。
   • 英文可以是锚定 # English 的完整下方部分、链接的 README.en.md 或紧凑的镜像部分，但安装/试用、验证、限制和许可/访问期望必须能让英文读者理解。
   • 构建适合扫描的组成结构：语言切换、真实主视觉、短篇故事钩子、证明条、紧凑徽章、“是什么/为什么”、功能矩阵、最快快速入门、可展开的手动安装、用法、产品巡游、兼容性/生态目录、工作流/架构、验证、限制和信任链接。
   • 使用真实截图或输出样本；不要编造截图。
4. 设置 GitHub 简介：
   • 对于 Qiaomu 拥有的公共仓库，默认使用紧凑的双语描述，中文在前，英文在后。
   • 若有在线演示，添加主页 URL。
   • 添加聚焦的主题；避免主题垃圾。
   • 对于公开发布的精益求精，创建或请求社交预览图。如果无法自动化，将手动 GitHub 设置步骤记录为后续事项，而不是假装已设置。
5. 根据发布姿态改进信任展示：
   • 对于开源仓库，始终验证许可证状态。
   • 对于外部贡献者项目，当缺少或过时时，添加或更新 CONTRIBUTING.md、CODE_OF_CONDUCT.md、SECURITY.md、Issue 模板和 PR 模板。
   • 对于纯展示仓库，说明为什么有意省略贡献/社区文件。
6. 验证 README 承诺的内容：
   • 在相关时运行项目提供的 lint/build/test 命令。
   • 对于技能，验证 npx skills add 的可发现性/可安装性。
   • 对于网站，在部署后验证实时 URL/API/健康状态。
7. 通过干净的 GitHub 流程发布：
   • 使用功能分支和 PR。
   • 切勿直接推送到 main。
   • 如果验证通过且用户未明确要求保留，将 PR 合并到 main。
   • 在最终响应中包含 PR URL 和合并提交。

源支撑的展示模型

此技能基于 GitHub 自身的仓库展示面：

• README：GitHub 表示仓库 README 应解释项目做什么、为什么有用、用户如何开始、从哪里获得帮助以及谁在维护。GitHub 自动向访问者展示可识别的 README。
• 主题：GitHub 主题帮助人们按目的、领域、社区、语言或其他重要品质发现仓库。
• 许可证：GitHub 的许可证指南指出，公共仓库需要开源许可证，其他人才能自由使用、修改和分发。
• 社区资料：GitHub 的公共仓库清单要求包含 README、许可证、行为准则、贡献指南、安全策略以及 Issue/PR 模板。
• 安全策略：SECURITY.md 告知人们如何报告漏洞。
• Issue 和 PR 模板：模板标准化贡献者打开 Issue 或 Pull Request 时提供的信息。
• 社交预览：GitHub 允许仓库维护者从仓库设置中设置社交预览图；当透明度可能渲染不可预测时，使用纯色背景。

当此指南与博客清单冲突时，优先使用官方文档。

参考案例（学习而非盲目复制）：santifer/career-ops 将其 README 呈现为紧凑的启动页面。它以语言入口、真实英雄图、三行起源故事、获得的外部证明、演示、量化成果、聚焦徽章开头，然后转向它的内容、功能、快速入门、用法、工作流、结构、技术栈、免责声明和联系方式。当 Qiaomu 仓库合适时，重用该排序逻辑，但绝不编造媒体、社区、下载、星标、用户成功或使用量声明。

复杂产品的参考案例：nexu-io/open-design 将其 README 视为大型生态系统的产品地图。它使用发布/CTA 通知、强大的产品巡游部分、分组演示画廊、平台兼容性表格、多路径快速入门、代理/MCP 使用、技能/设计系统/插件目录、架构和安全说明、路线图、社区/贡献表格、维护者、仓库活动和谱系/来源。将其作为 Qiaomu 仓库（具有多个面）的模块化清单重用，但除非在当前仓库中验证，否则绝不复制规模数字、支持矩阵、付费服务声明、社区声明、安全保证或第三方谱系。

README 标准

语言入口

对于 Qiaomu 拥有的公共仓库，发布前 README.md 必须为中文优先的双语：

• 首个视口：项目名称、中文价值主张、英文价值主张、徽章/链接以及可见的语言切换，如 **中文** | [English](#english)。
• 主体：中文部分优先，作为默认的读者体验。
• 英文访问：提供有实质内容的英文部分或链接的英文 README。至少，英文读者必须理解它做什么、如何试用/安装、什么已验证以及主要限制/前提条件。
• 可能存在 README.zh-CN.md 和 README.en.md 等翻译文件，但 GitHub 默认的 README.md 仍必须以中文开头，除非用户明确批准了不同的受众。
• 如果 README.md 是纯英文、英文优先或依赖单独的英文文件来提供中文体验，请在打开/合并发布 PR 前停止并修复。

首个视口入口

README.md 的顶部应通过 60 秒陌生人测试：

• 用一句话具体说明这是什么？
• 它适用于谁，消除了什么痛点？
• 我可以立即点击、安装或试用什么？
• 我能看到什么证明：截图、演示、示例输出、CI 徽章或已验证的命令？
• 我应该信任什么：许可证、维护者、安全/隐私边界以及最后验证状态？

避免徽章墙、抽象标语和以架构开头。架构应放在用户理解产品价值之后。

公共 README 必须快速回答五个问题：

• 这解决了什么痛点？
• 安装/运行后我能得到什么？
• 我能在截图、演示或示例输出中看到证明吗？
• 我如何在五分钟内尝试它？
• 有什么限制、成本或前提条件？

组成入口

使用既可作为产品页面又可作为技术文档的 README 布局：

• 在内部结构之前，以成果和证明开头：项目名称、语言切换、真实产品媒体、一到两句具体价值线、主要操作链接和一条可信的证明行。
• 使证明具体且可验证：在线演示、安装命令、包/发布徽章、CI 结果、截图、示例输出、基准测试、案例研究、用户成果、媒体报道或星标图。如果未验证或未获得，则省略。
• 当有 4 个以上功能时使用功能表。每行应将命名的功能映射到用户可见的结果，而不仅仅是列出模块。
• 将最快的成功路径放在手动设置之前。首先使用一个命令或最短的已验证路径，然后将较长的手动设置隐藏在 <details> 中，以免淹没页面。
• 快速入门之后，添加用法命令、工作流/工作原理、项目结构和技术栈。这些部分应帮助认真的用户检查系统，而不会延迟第一次尝试。
• 将隐私、数据所有权、成本、第三方条款、“非托管服务” 和 “不执行 X” 的边界放在可见的限制/免责声明部分中（如相关）。
• 保持视觉资产有目的性。英雄图、演示 GIF、徽标、徽章和图表应证明产品或状态；它们不应成为装饰或借用权威。

复杂产品目录入口

当仓库不仅仅是单个应用/库时使用此门：多平台应用、代理生态系统、插件/模板目录、设计系统、媒体管线、MCP 服务器、自托管栈或具有大量社区/贡献面的项目。

• 在深入内部结构之前添加产品巡游。按用户面或工件类型分组截图/演示，并为每个项目提供一行结果：入口应用、工作室/编辑器、仪表盘、插件市场、生成输出、API、CLI、MCP、移动/桌面视图等。
• 当产品在多个平台、代理、提供商、操作系统、部署模式或包管理器上运行时，添加兼容性矩阵。列应具体：目标、状态、安装命令、验证命令和已知限制。
• 为技能、插件、模板、设计系统、提供商、示例或集成添加生态目录。仅当从仓库生成或最新验证时使用计数；否则使用 “许多” 或链接到目录。好的列：项目、分类/模式、受众、输出、源路径。
• 按角色/路径提供快速入门：桌面或托管应用、仅 CLI/代理、Docker/自托管、从源代码的开发者路径。将推荐路径放在首位，并为每个路径提供成功检查。
• 当仓库有守护进程、MCP 服务器、代理、本地数据库、凭据、生成工件或网络边界时，一起展示架构和安全。最好使用紧凑图表/表格，链接到权威深度文档，并避免重复容易漂移的存储或秘密处理细节。
• 当仓库邀请外部工作或捆绑第三方资产时，添加路线图、社区、贡献、维护者和来源部分。来源应命名上游项目、许可证边界以及适应或捆绑的内容。
• 控制目录密度：对扫描使用表格，对长清单使用 <details>，对详尽列表使用深度文档。README 应引导新用户，而不成为整个手册。

推荐结构：

# 项目名称

**中文** | [English](#english)

![产品截图或英雄图](docs/assets/product-screenshot.png)

> 中文价值主张
> English value proposition

[在线演示] [安装] [文档] [许可证] [CI]

**已验证:** `npm test` / `npx skills add ...` / 实时健康检查 / 示例输出

## 这是什么
## 为什么值得用
## 核心能力

| 能力 | 用户得到什么 |
|---|---|
| ... | ... |

## 样例输出
## 快速开始

### 最快路径

```bash
...

...

使用方式

产品巡游 / Demo

平台兼容 / 生态目录

工作流 / 原理

架构与安全模型

项目结构

部署 / API / Skill

路线图 / 社区 / 贡献

来源谱系 / License 边界

实测验证

限制、隐私与边界

Troubleshooting

关于向阳乔木

---

English section

### 证明与媒体

- 在顶部附近优先使用一张真实截图、演示 GIF、终端记录、API 响应、生成工件或托管演示。
- 每个截图或样本必须与当前已验证状态匹配。除非明确标记为设计原型，否则不要使用模拟图像。
- 量化声明应保持最新且有来源：示例包括处理项目数、生成工件数、已安装版本、兼容性目标、目录计数、基准测试结果或已发布的案例研究。如果仓库无法从代码、生成的元数据、测试、发布工件或文档中证明数字，请改用已验证的命令/输出。
- 对于 CLI/工具，包括短的命令成功记录和失败/故障排除示例。
- 对于网站/应用，包括实时 URL、部署目标、健康/API 检查以及在可行时的桌面/移动截图。
- 将 README 大小舒适地保持在 GitHub 的 500 KiB 渲染截断限制以下；如果文档变得很大，将更深的内容拆分到 `docs/` 并链接它。

## GitHub 展示面标准

### GitHub 简介标准

对于 Qiaomu 拥有的公共仓库，默认使用紧凑的双语形式：

```text
中文短描述 | English short description.

保持具体。好的示例：

• 把 App Store 评价变成产品研究证据，发现痛点、机会和版本风险 | Turn App Store reviews into product research evidence: pain points, opportunities, and version risks.
• 把任意资料整理成 NotebookLM 可用知识包 | Turn messy sources into NotebookLM-ready knowledge packs.

主题应窄且有针对性：

• 领域：app-store、app-reviews、notebooklm、geo
• 技术栈：nextjs、agent-skill、deepseek
• 受众/工作流：product-management、ai-workflow

避免像 tool、website、ai 这样的通用主题，除非它们能增加可发现性。

主页、徽章和社交预览

• 将主页设置为在线演示、文档、安装页面或产品主页。如果不存在，则留空，而不是指向不相关的页面。
• 使用小的徽章行：CI/构建、许可证、包