182 lines
5.7 KiB
Markdown
182 lines
5.7 KiB
Markdown
|
---
|
|||
|
|
name: readme
|
|||
|
|
description: "根据项目中的真实代码、配置和文档，同时创建、审查或更新英文 README.md 与中文 README_zh.md，确保两份项目说明内容一致、环境要求准确、使用命令可执行。仅在用户显式调用 $readme 时使用。"
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# 维护中英文项目 README
|
|||
|
|
|
|||
|
|
根据项目真实内容，同时创建或更新准确、简洁、可执行的英文和中文 README。
|
|||
|
|
|
|||
|
|
## 定位项目
|
|||
|
|
|
|||
|
|
1. 如果用户指定了项目路径，优先使用该路径。
|
|||
|
|
2. 否则使用当前 Git 仓库根目录。
|
|||
|
|
3. 如果当前目录不是 Git 仓库：
|
|||
|
|
- 工作区内只有一个仓库时，使用该仓库；
|
|||
|
|
- 存在多个仓库时，让用户选择；
|
|||
|
|
- 没有 Git 仓库时，将当前目录作为项目根目录。
|
|||
|
|
4. 读取当前项目适用的 `AGENTS.md`。
|
|||
|
|
5. 默认维护项目根目录中的中英文 README。
|
|||
|
|
|
|||
|
|
不要根据文件夹名称猜测项目类型、用途或技术栈。
|
|||
|
|
|
|||
|
|
## 目标文件
|
|||
|
|
|
|||
|
|
默认维护：
|
|||
|
|
|
|||
|
|
- `README.md`：英文版本；
|
|||
|
|
- `README_zh.md`：简体中文版本。
|
|||
|
|
|
|||
|
|
如果项目已经使用 `README_CN.md`、`README_zh-CN.md` 等中文文件名，沿用已有命名，不重复创建中文 README。
|
|||
|
|
|
|||
|
|
如果两份 README 都存在，同时检查和更新。
|
|||
|
|
|
|||
|
|
如果只存在其中一份，根据已确认的项目内容创建缺少的版本。
|
|||
|
|
|
|||
|
|
如果 `README.md` 当前主要使用中文，且不存在独立中文版本：
|
|||
|
|
|
|||
|
|
1. 先将仍然准确的中文内容保留到 `README_zh.md`；
|
|||
|
|
2. 再将 `README.md` 整理为英文版本；
|
|||
|
|
3. 确保原有有效信息没有丢失。
|
|||
|
|
|
|||
|
|
如果两份都不存在，同时创建英文和中文版本。
|
|||
|
|
|
|||
|
|
## 调研项目
|
|||
|
|
|
|||
|
|
优先检查：
|
|||
|
|
|
|||
|
|
- 已有 README 和主要设计文档；
|
|||
|
|
- 项目清单、依赖文件和包管理配置；
|
|||
|
|
- 源码入口和核心模块；
|
|||
|
|
- 构建、运行、测试和部署脚本；
|
|||
|
|
- 配置示例和环境变量说明；
|
|||
|
|
- CI 配置、许可证和贡献规范；
|
|||
|
|
- `docs/` 中的索引或概览文档。
|
|||
|
|
|
|||
|
|
使用 `rg --files` 或等效方式进行针对性检查。
|
|||
|
|
|
|||
|
|
默认排除：
|
|||
|
|
|
|||
|
|
- `.git`；
|
|||
|
|
- `bin`、`obj`、`build`、`dist`；
|
|||
|
|
- 日志、缓存和编译产物；
|
|||
|
|
- 第三方依赖目录；
|
|||
|
|
- 与 README 无关的大型数据和生成文件。
|
|||
|
|
|
|||
|
|
避免为了维护 README 扫描整个大型仓库。
|
|||
|
|
|
|||
|
|
## 同步规则
|
|||
|
|
|
|||
|
|
英文和中文 README 必须表达相同的项目事实，包括：
|
|||
|
|
|
|||
|
|
- 项目目标和适用范围；
|
|||
|
|
- 当前已经实现的功能；
|
|||
|
|
- 环境和依赖要求；
|
|||
|
|
- 安装、构建、运行和测试命令；
|
|||
|
|
- 配置方法；
|
|||
|
|
- 项目结构；
|
|||
|
|
- 已知限制；
|
|||
|
|
- 许可证和贡献方式。
|
|||
|
|
|
|||
|
|
两份 README 不要求逐字翻译，但章节含义、命令、路径、版本和项目状态必须一致。
|
|||
|
|
|
|||
|
|
代码、命令、配置键、类名、函数名和文件路径保持原文，不进行翻译。
|
|||
|
|
|
|||
|
|
如果只修改其中一份中的事实性内容，必须同步检查另一份。
|
|||
|
|
|
|||
|
|
不要让中文版本成为英文版本的简略摘要，也不要让其中一份长期落后于另一份。
|
|||
|
|
|
|||
|
|
## 语言切换
|
|||
|
|
|
|||
|
|
在英文 README 顶部添加中文版本链接，例如：
|
|||
|
|
|
|||
|
|
`English | [简体中文](README_zh.md)`
|
|||
|
|
|
|||
|
|
在中文 README 顶部添加英文版本链接，例如：
|
|||
|
|
|
|||
|
|
`[English](README.md) | 简体中文`
|
|||
|
|
|
|||
|
|
如果中文 README 使用其他文件名，应使用实际相对路径。
|
|||
|
|
|
|||
|
|
已有语言切换格式时，优先沿用现有格式。
|
|||
|
|
|
|||
|
|
## 确定修改范围
|
|||
|
|
|
|||
|
|
优先更新现有 README，保留仍然准确的内容和既有写作风格。
|
|||
|
|
|
|||
|
|
除非用户明确要求，默认只允许修改：
|
|||
|
|
|
|||
|
|
- 英文 README；
|
|||
|
|
- 中文 README。
|
|||
|
|
|
|||
|
|
不修改业务代码、配置、脚本或其他文档。
|
|||
|
|
|
|||
|
|
不创建中英文以外的语言版本。
|
|||
|
|
|
|||
|
|
复杂架构、接口和设计决策应链接到专门文档，不要全部复制进 README。
|
|||
|
|
|
|||
|
|
## 组织内容
|
|||
|
|
|
|||
|
|
根据项目实际情况选择必要章节，不强制套用完整模板。可以包括：
|
|||
|
|
|
|||
|
|
1. 项目名称和一句话说明；
|
|||
|
|
2. 当前能力和适用范围；
|
|||
|
|
3. 快速开始；
|
|||
|
|
4. 环境与依赖；
|
|||
|
|
5. 构建、运行和测试；
|
|||
|
|
6. 项目结构或架构概览；
|
|||
|
|
7. 配置与部署；
|
|||
|
|
8. 已知限制和故障排查；
|
|||
|
|
9. 贡献方式和许可证。
|
|||
|
|
|
|||
|
|
把最常用、最可靠的使用路径放在前面。
|
|||
|
|
|
|||
|
|
两份 README 的主要章节和排列顺序应尽量保持一致。
|
|||
|
|
|
|||
|
|
只在确实有助于理解时使用表格、目录树或 Mermaid 图。
|
|||
|
|
|
|||
|
|
不要把 README 写成完整源码清单、开发日志或冗长设计文档。
|
|||
|
|
|
|||
|
|
## 保证准确
|
|||
|
|
|
|||
|
|
所有说明必须来自代码、配置、脚本、测试或现有文档。
|
|||
|
|
|
|||
|
|
命令必须能够在项目中找到依据，不得编造安装、构建、启动、测试、部署或硬件操作。
|
|||
|
|
|
|||
|
|
明确区分：
|
|||
|
|
|
|||
|
|
- 已验证可用；
|
|||
|
|
- 根据配置推断；
|
|||
|
|
- 尚未验证。
|
|||
|
|
|
|||
|
|
不要把编译成功描述成运行成功、部署成功或实机验证成功。
|
|||
|
|
|
|||
|
|
不要编造版本、兼容平台、性能指标、维护状态或许可证。
|
|||
|
|
|
|||
|
|
不要写入密码、令牌、私有地址、个人绝对路径或其他敏感信息。
|
|||
|
|
|
|||
|
|
信息不足时优先省略非必要内容；必要信息缺失时标记为“待确认”。
|
|||
|
|
|
|||
|
|
已有中英文内容存在冲突时，以当前代码、配置和测试结果为准，并在结果中说明修正。
|
|||
|
|
|
|||
|
|
## 验证结果
|
|||
|
|
|
|||
|
|
完成后：
|
|||
|
|
|
|||
|
|
- 检查两份 README 引用的文件和相对路径真实存在；
|
|||
|
|
- 检查语言切换链接有效；
|
|||
|
|
- 检查两份 README 的项目事实、命令和状态保持一致；
|
|||
|
|
- 检查示例命令与项目文件保持一致；
|
|||
|
|
- 安全且成本较低时，验证最关键的构建或测试命令；
|
|||
|
|
- 未执行的命令必须明确说明；
|
|||
|
|
- 检查最终 diff，避免无关重写、重复章节和格式噪声；
|
|||
|
|
- 确认没有修改中英文 README 之外的文件。
|
|||
|
|
|
|||
|
|
最后报告：
|
|||
|
|
|
|||
|
|
1. 创建或修改了哪些 README；
|
|||
|
|
2. 主要新增或修正了什么内容；
|
|||
|
|
3. 两份 README 同步了哪些信息；
|
|||
|
|
4. 执行了哪些验证；
|
|||
|
|
5. 哪些信息仍然待确认；
|
|||
|
|
6. 确认没有修改其他文件。
|