tomevault-io dovelx-init — 项目初始化与 PROJECT.md
输出语言：与用户交互、写入
PROJECT.md与规则说明时使用中文；代码与命令示例保持仓库原有语言。
目标
- 在当前工作区根目录生成或更新
PROJECT.md，集中描述项目 identity、栈、目录、命令、约定，便于每次打开仓库时快速建立上下文。 - 指导将
PROJECT.md接入 Cursor：通过 Project Rules（推荐）或 Hooks（可选）让 Agent 默认遵循该文档。
何时执行
- 用户首次打开陌生仓库、或项目结构经历大改后需要刷新「项目说明书」。
- 用户明确要求初始化、生成
PROJECT.md、或与 Cursor 规则/钩子联动。
Phase 1 — 发现（只读）
在写文件前，必须基于仓库实际情况收集信息（工具可用时用 Glob / Read / Grep，否则用终端）：
| 关注点 | 典型来源 |
|---|---|
| 名称与用途 | README*、package.json name/description、pyproject.toml、服务名 |
| 技术栈 | package.json、pnpm-lock.yaml、requirements.txt、go.mod、Cargo.toml、Dockerfile、*.csproj |
| 入口与脚本 | package.json scripts、Makefile、Taskfile、justfile、docker-compose*.yml |
| 源码布局 | src/、apps/、packages/、lib/、cmd/、internal/ |
| 测试与 CI | vitest、jest、pytest、go test、/.github/workflows/* |
| 配置与环境 | .env.example、config/、appsettings* |
| 既有 AI 约定 | .cursor/rules/、AGENTS.md、CONTRIBUTING.md |
若信息缺失，在 PROJECT.md 对应节目标注 「待补充」，不要编造依赖或命令。
Phase 2 — 生成 PROJECT.md
- 路径：仓库根目录
PROJECT.md（与README.md并存；README面向人，PROJECT.md面向 Agent 与协作者快速对齐上下文）。 - 若已存在：先读取现有内容，合并更新（保留仍有效的段落，更新变更部分），并在文末更新 「文档更新记录」 一行当日摘要。
必须包含的章节结构
按下列顺序输出（无数据则写「暂无 / 待补充」）：
# <项目名>
## 一句话摘要
<本仓库解决什么问题 / 面向谁>
## 技术栈
- 语言 / 运行时：
- 框架与核心库：
- 包管理与锁文件：
- 数据库 / 消息队列 / 外部服务（若有）：
## 仓库地图
（高信号目录与职责，列表即可，不必穷举 node_modules）
## 运行与开发
- 安装依赖：
- 本地启动：
- 构建：
- 测试：
- Lint / 类型检查（若有）：
## 配置与环境变量
- 必需变量（来源 `.env.example` 等）：
- 多环境说明（dev/staging/prod）：
## 架构与关键模块
（入口文件、分层、重要模块名与职责）
## 测试与质量
- 测试命令与目录：
- CI 要点（若可识别）：
## 约定
（代码风格、分支、提交、与本仓库相关的特殊规则；可引用 `.cursor/rules` 已有内容）
## 相关文档
- README / docs 链接（相对路径）
## 给 Agent 的提示
- 修改代码前应阅读的目录或文件：
- 禁止或高风险操作（若有）：
---
文档更新记录：YYYY-MM-DD — <本次变更简述>
Phase 3 — 接入 Cursor（默认应做）
用户希望「每次打开项目能快速分析」→ 优先使用 Project Rules，无需强依赖 Hooks。
3.1 推荐：创建或更新 Rule
在 .cursor/rules/ 下新建或合并一个规则文件，例如 project-context.mdc：
---
description: 项目画像与上下文入口；分析或修改本仓库前优先遵循根目录 PROJECT.md
alwaysApply: true
---
# 项目上下文
- 本仓库的结构、命令、约定与模块说明以**根目录 `PROJECT.md`** 为准。
- 在开始实现、重构或排查问题前，先阅读 `PROJECT.md` 中与当前任务相关的章节，并保持文档与代码变更同步（重大结构或命令变化时更新 `PROJECT.md`）。
- `README.md` 侧重人类快速上手；`PROJECT.md` 侧重全景与 Agent/协作者对齐。
- 若仓库已有
alwaysApply: true的全局规则，避免重复冗长：可将上述要点合并进现有全局规则的一条列表，或保留独立文件但控制总行数（参考 create-rule：单条规则宜精炼）。
3.2 可选：Hooks
仅在用户明确要求使用 Hooks、或需在 session 开始 强制提醒时使用。
- 位置：项目级
.cursor/hooks.json+.cursor/hooks/*。 - 常见事件：
sessionStart（会话开始注入「先读 PROJECT.md」类提示）或beforeSubmitPrompt（策略类校验）。 - 实现要点：遵循 Cursor hooks 的 JSON schema 与 stdin/stdout 协议；失败策略（fail open/closed）需与用户确认。
具体格式与事件列表以 create-hook 技能为准；本技能不强制生成 Hook 文件。
Phase 4 — 收尾
- 向用户说明：
PROJECT.md路径、Rule 文件路径（若创建）、以及「以后结构变了如何刷新」（重新执行本技能或手动编辑PROJECT.md）。 - 若项目无
.gitignore或团队希望忽略本地规则：说明PROJECT.md与.cursor/rules是否应提交（默认建议提交，以便团队与 Agent 一致）。
注意事项
- 不要把密钥、token、真实连接串写入
PROJECT.md。 - 不要把整棵文件树逐文件列出；保持高信号、可维护。
- 与
dovelx-ask等技能协作时：PROJECT.md可作为问答与检索的优先静态索引之一。
附加资源
- Cursor Rule 文件格式与
alwaysApply/globs：见 create-rule 技能。 - Hooks 事件与
hooks.json：见 create-hook 技能。
Source: DoveXiaZi/dovelx-skill — distributed by TomeVault.