---
name: readme
description: Create, update, audit, or synchronize repository README documentation from evidence in the codebase. Use when the user asks to write or improve a README, document setup/build/run/test workflows, explain project structure or architecture, fix stale README content, or maintain multilingual README files for any software project.
---

# README维护

生成或更新准确、简洁、可执行的项目README，不预设托管平台、技术栈、运行环境或文档语言。

## 工作流程

### 1. 调研仓库

- 读取适用的`AGENTS.md`、现有README和主要设计文档。
- 检查源码目录、项目清单、依赖文件、入口、配置、构建脚本、测试和CI配置。
- 使用`rg --files`和针对性搜索；排除`bin`、`obj`、`build`、依赖缓存及其他生成目录。
- 从代码和配置确认项目名称、用途、模块边界、环境要求及实际命令，不根据目录名猜测。

### 2. 确定范围

- 优先更新现有README，保留仍然准确的内容和仓库既有风格。
- 默认沿用现有文件名和主要语言。
- 只有用户明确要求或仓库已有约定时，才创建双语或多份README，并添加相对链接切换语言。
- 删除或修正已改名、已删除、不存在或无法验证的内容。

### 3. 组织内容

根据项目实际情况选择必要章节，不强制套用完整模板。常用顺序为：

1. 项目名称与一句话说明
2. 当前能力与适用范围
3. 目录或架构概览
4. 环境与依赖
5. 构建、运行和测试
6. 配置与部署
7. 已知限制或故障排查
8. 贡献方式与许可证（仅在仓库有依据时）

- 把最常用的成功路径放在前面。
- 仅在能显著解释模块关系或执行流程时使用表格、目录树或Mermaid图。
- 使用相对路径链接仓库内文件，避免复制大段源码或生成完整文件清单。

### 4. 保证事实准确

- 命令必须来自项目文件、脚本或已验证的工具链；不要编造安装、启动、部署或硬件步骤。
- 区分“已验证可用”“根据配置推断”和“尚未验证”，不要把编译成功描述为运行或实机验证成功。
- 不编造版本、性能指标、兼容平台、许可证、维护状态或安全保证。
- 不在README中写入密码、令牌、内网地址、个人路径或其他敏感信息。
- 信息不足时优先省略非必要章节；必要信息缺失时明确标注待确认内容。

### 5. 验证结果

- 检查README中的名称、路径、文件和命令仍真实存在。
- 检查中英文或多语言版本的关键事实、命令和链接保持一致。
- 对能够安全执行的核心命令进行适度验证；未执行时明确说明。
- 查看最终差异，避免无关重写、重复章节和过度宣传。

## 写作要求

- 面向首次接触仓库的开发者，使用直接、具体、可操作的语言。
- 说明“是什么、怎么用、如何验证”，避免空泛的优势描述。
- 保持章节简短；复杂设计链接到专门文档，不把README写成完整设计说明书。
- 代码块标注正确语言，命令应可复制，并注明必要的工作目录或前置条件。
