feat: add reusable engineering skill collection
This commit is contained in:
@@ -0,0 +1,182 @@
|
||||
---
|
||||
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. 确认没有修改其他文件。
|
||||
@@ -0,0 +1,7 @@
|
||||
interface:
|
||||
display_name: "维护中英文 README"
|
||||
short_description: "根据项目真实内容同步创建或更新中英文 README"
|
||||
default_prompt: "使用 $readme 根据当前项目的真实代码和配置，同步创建或更新英文 README.md 与中文 README_zh.md。"
|
||||
|
||||
policy:
|
||||
allow_implicit_invocation: false
|
||||
Reference in New Issue
Block a user