joeseesun/qiaomu-github-publisher

Qiaomu GitHub Publisher

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

Copyright (c) 向阳乔木

• X: https://x.com/vista8
• GitHub: https://github.com/joeseesun/
• Profile 源: ~/.agents/skills/qiaomu-profile

核心工作流程

1. 在编写之前检查仓库：
   • README.md, package.json / 项目元数据、截图、示例、文档、许可证、部署脚本、测试脚本。
   • GitHub 和社区界面：关于描述、主页、话题、社交预览、许可证、SECURITY.md、CONTRIBUTING.md、CODE_OF_CONDUCT.md、问题模板、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、问题模板和 PR 模板。
   • 对于仅展示仓库，解释为何有意省略贡献/社区文件。
6. 验证 README 中的承诺：
   • 在相关时运行项目提供的 lint/构建/测试命令。
   • 对于技能，验证 npx skills add 的可发现性/可安装性。
   • 对于网站，在部署后验证实时 URL/API/健康状态（如适用）。
7. 通过干净的 GitHub 流程发布：
   • 使用特性分支和 PR。
   • 绝不直接推送到 main。
   • 如果验证通过且用户未明确要求暂缓，将 PR 合并到 main。
   • 在最终响应中包含 PR URL 和合并提交。

基于源的展示模型

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

• README：GitHub 表示仓库 README 应解释项目做什么、为何有用、用户如何入门、去哪里寻求帮助以及谁维护它。GitHub 会自动向访问者显示已识别的 README。
• 话题：GitHub 话题帮助人们根据目的、主题领域、社区、语言或其他重要特性发现仓库。
• 许可证：GitHub 的许可证指南指出，公共仓库需要开源许可证，其他人才明确可以自由使用、修改和分发。
• 社区简介：GitHub 的公共仓库检查清单关注 README、许可证、行为准则、贡献指南、安全策略和问题/PR 模板。
• 安全策略：SECURITY.md 告诉人们如何报告漏洞。
• 问题和 PR 模板：模板标准化了贡献者在打开问题或拉取请求时提供的信息。
• 社交预览：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

[在线演示] [安装] [文档] [许可证] [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 评价变成产品研究证据，发现痛点、机会和版本风险
• 把任意资料整理成 NotebookLM 可用知识包

话题应窄而有用：

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

避免通用话题如 tool, website, ai，除非它们增加可发现性。

主页、徽章和社交预览

• 将主页设置为在线演示、文档、安装页面或产品主页。如果不存在，留空而不是指向无关页面。
• 使用小徽章行：CI/构建、许可证、包注册表版本（如适用）、覆盖范围（如已验证）、代码质量（如已验证）和已知使用/改编行。
• 对于公开发布，创建或请求社交预览图片。如果无法自动化，记录手动步骤作为后续跟进。社交预览在透明背景可能渲染不可预测时使用纯色背景。

许可证标准

• 对于公共仓库，许可证必须存在且匹配项目文档：Apache 2.0、MIT、GPLv3、AGPLv3、BSD-2/3-Clause、MPL 2.0、Unlicense、CC0、CC-BY-4.0、Elastic-2.0 或其他经过审查的开源批准许可证。
• 如果仓库缺少许可证，停止并要求在更改任何其他文件之前添加许可证。
• 如果仓库使用非标准或已停止的许可证（JSON 许可证、CC 用于代码、FPL、SSPL、不编写的 BUSL），停止并要求澄清。
• 如果仓库是多许可证（基本上是“选择”或“并且”），验证许可证文件是否列出所有选项、贡献者是否被覆盖以及用户是否有绝对最低选择。
• 如果仓库是文档、示例或规范，使用 CC-BY-4.0 可能是合适的；验证内容类型和预期使用。

社区文件标准

• 对于外部贡献者项目，在启动 PR 之前确保 CONTRIBUTING.md、CODE_OF_CONDUCT.md、SECURITY.md、问题模板和 PR 模板存在且合理填写。
• 如果仓库是仅展示产品站点或定义明确的个人工具，如果根本不需要外部工作，省略社区文件是可以接受的。
• 如果任何文件缺失，在 PR 中创建/更新它。
• 问题模板：当还有复现步骤、环境、行为与预期、日志和截图时，使用单个“问题”模板是足够的；如果仓库有多个类型（错误、功能请求、问题），使用多个模板。
• PR 模板应包括相关问题链接、检查清单、测试与验证步骤以及破坏性更改说明。
• CODE_OF_CONDUCT.md 应指向标准源头（贡献者公约 2.1 或类似）并包括报告联系人。当仓库有多个维护者提供报告路径时，使用总括行为准则。
• SECURITY.md 应说明如何报告漏洞；如果安全处理是实践的，它应是具体的；如果仓库是仅展示，它可以指向父项目或如实说明报告选项。
• CONTRIBUTING.md 应解释贡献类型、环境设置、工作流程（PR 与分支）、编码标准、测试期望、维护者、许可条款和任何政策。

发布 / 变更日志标准

• 如果仓库发布发布，检查 release 页面：如果发布/a，存在可变链接；如果不存在永久链接，文件是未来证明的。
• 变更日志是可选的但推荐。如果存在，验证它是否匹配当前发布。不修理，但记录。
• 发布验证检查包括 + gh release list --limit 10 + + + 验证提交或标签是否匹配代码状态。

转义门

• 当项目开始于非乔姆的现有上游仓库 fork 时。这种 fork 到 Qiaomu GitHub 组织是许可的，因为其上游许可是开源的。
• 当用户提供严格的设计、语言或内容要求：跟随用户的明确指令。
• 当用户明确指示在编辑 README 之前应联系维护者或开放问题：遵循该协议。
• 当仓库是纯内部或私有时：跳过社区文件、发布 v准备工作和 GitHub 关于设置。仍然可以应用 README 内部质量标准。
• 当仓库的贡献、使用或内容限制其公开存在时：相应地调整。

如果用户明确要求单语、中文优先或英文优先的 README，遵循该请求。

技能调用

# 从项目目录
npx skills add joeseesun/qiaomu-github-publisher