OpenGHz/开源项目打磨

开源项目打磨 是做什么的？

目标

将一个现有项目文件夹转化为高质量的开源仓库，方法是改进面向公众的文档、社区文件、仓库元数据和Git/GitHub设置，同时保留原始源代码。

硬性边界

• 除非用户明确要求，否则不得修改原始产品/源代码、生成的逻辑、测试、笔记本、资产或运行时行为。
• 允许的更改仅限于面向项目的元数据和文档，例如README、LICENSE、CONTRIBUTING、CODE_OF_CONDUCT、SECURITY、CHANGELOG、SUPPORT、CITATION、问题/PR模板、发布说明、徽章、.gitignore、.gitattributes、.editorconfig以及GitHub工作流/文档脚手架。
• 绝不要在README或公开文档中包含用户特定的本地机器路径，例如/home/<user>/...、/Users/<user>/...、驱动器字母路径、个人工作区名称、下载文件夹或特定于机器的绝对项目路径。应使用相对路径、$HOME、<repo>或占位符。
• 当没有许可证且没有用户偏好覆盖时，默认使用MIT许可证。
• 对于没有Git远程的文件夹，默认自动发布到公共GitHub。如果目标所有者/名称不明显，则进行推断，然后创建一个公共远程并在秘密检查通过后仅推送文档更改。
• 如果网络/GitHub命令失败，在宣布远程步骤受阻前，使用配置的本地代理重试一次。
• 尽可能保留现有文档和社区文件；渐进式改进，而不是替换有用内容。

缺失时需要澄清的输入

只询问那些对不可逆或面向公众的操作有实质性影响的信息：

1. 目标范围：工作区项目路径，或者如果已经明确，则为当前文件夹。
2. 公开身份：在创建任何远程之前，如果无法从文件夹和已验证的GitHub账户推断出来，则询问GitHub所有者/仓库名称。
3. 许可证覆盖：如果存在现有许可证则使用；否则默认应用MIT，除非用户请求其他许可证。
4. 项目定位：一句话的价值主张、目标用户以及如果无法从代码/文档推断则询问成熟度。
5. 源代码编辑：假设禁止；在触及元数据/文档之外的任何内容之前询问。

流程

1. 审计项目状态

• 检查文件夹结构、现有的README/文档、包清单、构建文件、示例、许可证文件和Git状态。
• 检查.git是否存在以及是否配置了任何远程。
• 在创建或推送任何远程之前，识别存在机密风险的文件：.env、凭据、令牌、大型二进制文件、数据集、私人笔记、本地日志和特定于机器的路径。
• 总结现有优势、缺失的开源必需品以及任何需要用户输入的不确定性。

2. 规划非代码添加

创建一个涵盖仅允许的文档和元数据工作的简洁计划：

• 使用create-readme技能作为结构、语气和GitHub风格Markdown的基础来改进README。
• 默认生成双语README：在主要（英文）README定稿后，生成一个中文版本保存为README.zh-CN.md，并互相链接。直接创作镜像副本；对于术语密集的长文档，保留使用baoyu-translate技能，以确保全局术语一致性。
• 社区健康文件：默认MIT许可证、贡献指南、行为准则、安全策略、支持指南、更新日志、引用、治理、问题模板、PR模板。
• 仓库卫生：.gitignore、.gitattributes、.editorconfig、文档索引、示例索引、徽章、项目描述、主题、资金/赞助元数据（如果相关）。
• Git/GitHub设置：如果不存在则初始化Git，如果不存在则创建公共远程，设置默认分支，并在安全检查后仅推送文档更改。

3. 改进README

使用create-readme技能来创建或刷新README。确保README简洁、有吸引力且有用：

• 清晰的项目名称、标语和简短的价值主张。
• 仅当真实且可维护时添加徽章。
• 尽可能提供带有已验证命令的快速入门。
• 命令必须可以从仓库根目录复制粘贴，并且不得包含当前用户的绝对本地路径；优先使用./script.sh、$HOME/...、/path/to/...或<repo>/...示例。
• 安装、使用、配置、示例、项目结构、故障排除以及指向专用文件的链接。
• 不要在README中重复完整的LICENSE、CONTRIBUTING、CHANGELOG或SECURITY内容；链接到这些文件。
• 保留现有的项目特定知识和示例。

英文README.md定稿后，默认生成中文翻译：

• 默认情况下，英文README.md必须在靠近顶部位置包含一个语言切换行，例如English | [简体中文](README.zh-CN.md)。即使中文文件仍在同一运行中生成，也要添加它——该链接指向工作流完成时将存在的路径。
• 从README.md生成中文README.zh-CN.md。对于典型的README（主要由简短散文加上必须保持原样的代码/命令组成），优先直接创作镜像副本；只有当README很长或术语密集，并且受益于其分析/翻译/审查流程和共享词汇表时，才调用baoyu-translate技能。
• 中文README.zh-CN.md在顶部携带镜像切换行，例如[English](README.md) | 简体中文。
• 保持所有代码块、命令、路径、链接、徽章和占位符不变；仅翻译散文。
• 仅当用户明确选择退出时才跳过中文版本。如果项目主要是中文的，则将README.md视为中文版本，翻译为README.en.md，并在每个文件顶部放置相应的切换行。

4. 添加社区文件

仅在文件有助于使项目看起来完整且值得信赖时添加或更新：

• LICENSE：如果存在现有许可证则使用；否则默认添加MIT许可证，并在适当位置包含检测到的当前年份和所有者/项目名称。
• CONTRIBUTING.md：开发设置、分支/提交约定（如果可以推断）、测试期望、问题/PR流程。
• CODE_OF_CONDUCT.md：使用标准简洁的贡献者契约风格，除非用户有其他策略。
• SECURITY.md：支持的版本、负责任的披露渠道占位符、漏洞报告期望。
• CHANGELOG.md：初始化为Unreleased和当前的公共基线；不要编造发布历史。
• SUPPORT.md：在哪里提问、报告错误和请求功能。
• .github/ISSUE_TEMPLATE/*和.github/PULL_REQUEST_TEMPLATE.md：为项目量身定制的实用表单/清单。
• CITATION.cff：仅用于研究/学术/科学项目，或者当有作者元数据可用时。

5. 仓库卫生

• 根据检测到的语言/工具创建或完善.gitignore，但不要排除可能是源工件的文件。
• 添加.gitattributes用于文本规范化和常见的二进制模式（如果有用）。
• 添加.editorconfig，使用与仓库风格匹配的保守空白默认值。
• 除非已知或已验证构建/测试命令，否则不要添加CI工作流；如果添加，保持最小化且非侵入性。

6. Git 和远程处理

对于没有Git的文件夹：

1. 在验证文件夹路径后为目标文件夹初始化一个仓库。
2. 仅暂存由该工作流创建或更改的元数据/文档文件。
3. 当继续发布时，使用专注于文档的消息提交。

对于没有远程的Git仓库：

1. 从gh认证推断GitHub所有者，并在可能时从文件夹推断仓库名称；仅在不明确时询问。
2. 在创建远程之前检查gh认证。
3. 默认创建一个公共GitHub仓库。
4. 添加origin，设置默认分支，并在审查暂存更改并确认不包含机密后推送。

推荐的GitHub CLI流程，适配到项目：

git status --short
git remote -v
gh auth status
gh repo create OWNER/REPO --public --source=. --remote=origin --push

如果网络命令失败，使用以下命令重试一次：

export {HTTP_PROXY,HTTPS_PROXY,ALL_PROXY,http_proxy,https_proxy,all_proxy}=http://127.0.0.1:7890

7. 质量检查

在最终确定之前：

• 重新打开已更改的Markdown片段以验证标题、链接、代码围栏和可复制粘贴的命令缩进。
• 在最终确定之前搜索README和公开文档中的本地机器路径，包括/home/、/Users/、驱动器字母路径、个人工作区名称和从当前环境复制的绝对路径。
• 确认未经明确批准未修改任何源代码文件。
• 确认所有指向本地文件的链接都指向存在的文件。
• 如果生成了中文README，确认README.zh-CN.md存在，两个文件中的语言切换链接都能解析，并且代码/命令/路径与英文版本保持一致。
• 如果可用，运行轻量级格式化或Markdown linting；除非用户同意，不要为此工作流安装重依赖。
• 显示git diff --stat并汇总更改的文件。
• 如果创建了远程，报告URL、可见性、默认分支以及是否推送了任何内容。

决策点

• 现有README很强：保留结构并修补缺失的部分，而不是重写。
• 没有已验证的安装/测试命令：包含明确标记的占位符或“尚未记录”的注释，而不是编造命令。
• 许可证未知：默认添加MIT，除非用户请求不同的许可证。
• 可能存在机密或私人数据：停止远程创建/推送并报告有风险的路径。
• 没有gh CLI或未认证：为用户提供要运行的确切命令，但仍完成本地文档打磨，并在安全的情况下准备一个仅限文档的提交。
• 单仓库：仅在包边界清晰时创建或更新根社区文件和每个包的README文件。

完成摘要

以以下内容结束：

• 新增/更新的文件。
• 有意未触及的内容，尤其是源代码。
• 执行的验证。
• 远程仓库状态（如果适用）。
• 建议的后续步骤，例如启用CI、添加示例、进行首次发布或创建项目主题。