joeseesun/qiaomu-github-publisher

Qiaomu GitHub Publisher

将工作项目转化为一个人们能够理解、尝试、收藏、安装和信任的 GitHub 仓库。

Copyright (c) 向阳乔木

• X: https://x.com/vista8
• GitHub: https://github.com/joeseesun/
• Profile source: ~/.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 的门面。对于乔木拥有的仓库，默认必须是中文优先且双语。
   • 中文在前，英文在后。除非用户明确要求仅英文，或者仓库有记录的、非乔木的上游要求。
   • 允许单独的 README.zh-CN.md，但这本身并不满足要求；默认的 README.md 必须首先显示中文。
   • 英文可以是一个由 # English 锚定的完整下部区域、一个链接的 README.en.md，或一个紧凑的镜像区域，但安装/尝试、验证、限制和许可/访问期望必须让英文读者能够理解。
   • 构建一个易于扫描的组成：语言切换、真实英雄媒体、简短故事钩子、证据条、紧凑徽章、“是什么/为什么”、功能矩阵、最快的快速启动、可展开的手动设置、使用、产品巡览、兼容性/生态系统目录、工作流/架构、验证、限制和信任链接。
   • 使用真实截图或输出样本（如有）；不要捏造截图。
4. 设置 GitHub 关于：
   • 对于乔木拥有的公开仓库，默认使用紧凑的双语描述，中文在前，英文在后。
   • 存在实时演示时添加主页 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 呈现为紧凑的发布页面。它以语言访问、真实英雄图像、三行起源故事、获得的外部证据、演示、量化结果、聚焦徽章开始，然后进入项目内容、功能、快速启动、使用、工作流、结构、技术栈、免责声明和联系方式。当适合乔木仓库时重用该排序逻辑，但永远不要捏造新闻、社区、下载、收藏、用户成功或使用声明。

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

README 标准

语言门

对于乔木拥有的公共仓库，发布前 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

[Live Demo] [Install] [Docs] [License] [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 关于标准

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

```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/构建、许可证、包