---
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. 确认没有修改其他文件。