同步中英文README与当前工程结构，并整理文档目录与构建忽略规则
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Cursor
@@ -1,92 +1,63 @@
|
||||
---
|
||||
name: readme
|
||||
description: 为当前项目生成适配 Gitee / 公司内部代码仓库的中英文双语 README。默认生成 README.md（中文，Gitee 默认展示）和 README_en.md（英文）两个文件，顶部互相链接切换语言。适用于公司项目、算法项目、机器人项目、工程代码仓库。当用户说“写个README”“生成项目介绍”“生成Gitee README”“make a 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.
|
||||
---
|
||||
|
||||
# Gitee 双语 README 生成
|
||||
# README维护
|
||||
|
||||
为当前项目生成两个互相链接的 README 文件：
|
||||
生成或更新准确、简洁、可执行的项目README，不预设托管平台、技术栈、运行环境或文档语言。
|
||||
|
||||
- `README.md`：简体中文，作为 Gitee 默认展示文件
|
||||
- `README_en.md`：英文版，供中英文切换使用
|
||||
## 工作流程
|
||||
|
||||
如果项目中已经存在 `README_zh.md`、`Readme_zh.md`、`Readme_en.md` 等命名，先读取已有文件，并尽量沿用当前仓库已有命名规范；如果没有明确规范，默认使用 `README.md` + `README_en.md`。
|
||||
### 1. 调研仓库
|
||||
|
||||
## 执行目标
|
||||
- 读取适用的`AGENTS.md`、现有README和主要设计文档。
|
||||
- 检查源码目录、项目清单、依赖文件、入口、配置、构建脚本、测试和CI配置。
|
||||
- 使用`rg --files`和针对性搜索；排除`bin`、`obj`、`build`、依赖缓存及其他生成目录。
|
||||
- 从代码和配置确认项目名称、用途、模块边界、环境要求及实际命令，不根据目录名猜测。
|
||||
|
||||
生成符合公司内部 Gitee 仓库风格的 README，不写成 GitHub 开源宣传页。
|
||||
### 2. 确定范围
|
||||
|
||||
README 应该让新同事或项目参与者快速知道：
|
||||
- 优先更新现有README，保留仍然准确的内容和仓库既有风格。
|
||||
- 默认沿用现有文件名和主要语言。
|
||||
- 只有用户明确要求或仓库已有约定时，才创建双语或多份README，并添加相对链接切换语言。
|
||||
- 删除或修正已改名、已删除、不存在或无法验证的内容。
|
||||
|
||||
- 项目是什么
|
||||
- 面向什么设备 / 平台 / 场景
|
||||
- 软件架构大概是什么
|
||||
- 如何安装依赖
|
||||
- 如何编译 / 运行 / 启动
|
||||
- 代码目录怎么组织
|
||||
- 如何按公司流程参与开发
|
||||
### 3. 组织内容
|
||||
|
||||
## 执行步骤
|
||||
根据项目实际情况选择必要章节，不强制套用完整模板。常用顺序为：
|
||||
|
||||
### 1. 调研项目
|
||||
1. 项目名称与一句话说明
|
||||
2. 当前能力与适用范围
|
||||
3. 目录或架构概览
|
||||
4. 环境与依赖
|
||||
5. 构建、运行和测试
|
||||
6. 配置与部署
|
||||
7. 已知限制或故障排查
|
||||
8. 贡献方式与许可证（仅在仓库有依据时）
|
||||
|
||||
先充分了解项目，不要凭空编造内容。
|
||||
- 把最常用的成功路径放在前面。
|
||||
- 仅在能显著解释模块关系或执行流程时使用表格、目录树或Mermaid图。
|
||||
- 使用相对路径链接仓库内文件，避免复制大段源码或生成完整文件清单。
|
||||
|
||||
必须优先读取和分析：
|
||||
### 4. 保证事实准确
|
||||
|
||||
- 项目根目录结构
|
||||
- 已有 README / 文档
|
||||
- 主入口脚本
|
||||
- 启动脚本
|
||||
- `CMakeLists.txt`
|
||||
- `package.xml`
|
||||
- `requirements.txt`
|
||||
- `pyproject.toml`
|
||||
- `package.json`
|
||||
- `docker-compose.yml`
|
||||
- `Dockerfile`
|
||||
- 配置文件
|
||||
- launch 文件
|
||||
- ROS / ROS2 相关目录
|
||||
- 核心源码目录
|
||||
- 设备通信、底盘控制、导航、感知、驱动相关代码
|
||||
- 命令必须来自项目文件、脚本或已验证的工具链；不要编造安装、启动、部署或硬件步骤。
|
||||
- 区分“已验证可用”“根据配置推断”和“尚未验证”，不要把编译成功描述为运行或实机验证成功。
|
||||
- 不编造版本、性能指标、兼容平台、许可证、维护状态或安全保证。
|
||||
- 不在README中写入密码、令牌、内网地址、个人路径或其他敏感信息。
|
||||
- 信息不足时优先省略非必要章节；必要信息缺失时明确标注待确认内容。
|
||||
|
||||
需要识别：
|
||||
### 5. 验证结果
|
||||
|
||||
- 项目名称
|
||||
- 项目用途
|
||||
- 运行平台
|
||||
- 技术栈
|
||||
- 编程语言
|
||||
- ROS / ROS2 版本（如果存在）
|
||||
- 构建方式
|
||||
- 启动方式
|
||||
- 主要模块
|
||||
- 依赖项
|
||||
- 是否有实际设备、仿真环境、域控一体机、阿克曼底盘、CAN、串口、网络通信等内容
|
||||
- 检查README中的名称、路径、文件和命令仍真实存在。
|
||||
- 检查中英文或多语言版本的关键事实、命令和链接保持一致。
|
||||
- 对能够安全执行的核心命令进行适度验证；未执行时明确说明。
|
||||
- 查看最终差异，避免无关重写、重复章节和过度宣传。
|
||||
|
||||
**重要：只写代码和文档中真实存在的内容。**
|
||||
## 写作要求
|
||||
|
||||
不要编造：
|
||||
|
||||
- 未确认的算法
|
||||
- 未确认的性能指标
|
||||
- 未确认的硬件型号
|
||||
- 未确认的 ROS 版本
|
||||
- 未确认的启动命令
|
||||
- 未确认的部署流程
|
||||
- 未确认的许可证
|
||||
|
||||
如果信息不足，用“待补充”明确标注，不要用通用模板假装完整。
|
||||
|
||||
---
|
||||
|
||||
## 2. 文件命名与语言切换
|
||||
|
||||
### 默认文件
|
||||
|
||||
生成：
|
||||
|
||||
```text
|
||||
README.md
|
||||
README_en.md
|
||||
- 面向首次接触仓库的开发者，使用直接、具体、可操作的语言。
|
||||
- 说明“是什么、怎么用、如何验证”，避免空泛的优势描述。
|
||||
- 保持章节简短；复杂设计链接到专门文档，不把README写成完整设计说明书。
|
||||
- 代码块标注正确语言，命令应可复制，并注明必要的工作目录或前置条件。
|
||||
|
||||
Reference in New Issue
Block a user