Project / Module Overview Generator

用途 / What this skill does

这个 skill 会对指定的代码仓库或代码仓库内的某个模块/子目录做全面扫描，产出一份 Markdown 说明文档。核心目标是：让一个从没接触过这段代码的人，读完这一份文档后，能够：

1. 知道这个项目/模块是什么、解决什么问题、在系统里扮演什么角色
2. 跑起来它（仅项目级）/ 集成/调用它（仅模块级）
3. 理解核心抽象 / 核心子模块 / 关键流程
4. 能够开始阅读源码或修改源码

🎯 两种分析模式（Two Modes）

两种模式共享大部分流程（识别语言 → 扫描结构 → 提取核心 → 生成文档），但章节组织、关注重点、附加内容不同。详见下文 Phase 0 的范围判断与各模式文档模板。

📥 两种代码来源（Two Sources）

详见下文 Phase 0 的 0.1 确定输入类型。

🎯 核心理念（Guiding Principles）

1. 完备 > 简洁：不限制文档长度。项目大就写长，项目小就写短。宁可冗余，不可遗漏。
2. 图文并茂：架构、依赖、数据流都用 Mermaid 图表达。
3. 代码即说明：核心模块要展示函数签名 + 关键逻辑代码。关键逻辑很长就照抄，无关部分用注释/伪代码省略。
4. 语言无关：通过识别项目标识文件（go.mod / package.json / pyproject.toml / pom.xml / Cargo.toml 等）自动适配。
5. 一键式：用户一句话触发，全流程自动执行，不打断用户确认（除非项目规模极大需要分块）。

🚀 工作流（Workflow）

⚠️ 严格按 Phase 顺序执行。每个 Phase 的输出是下一 Phase 的输入。

Phase 0：确定路径 + 分析范围（Project / Module）

0.1 确定输入类型（本地路径 vs Git 链接）

先判断用户给的是本地路径还是Git 链接：

Git 链接的识别规则（满足任一即视为 Git 链接）：
- 以 http:// / https:// / git@ / ssh:// 开头
- 匹配 github.com / gitlab.com / bitbucket.org / git.*.com / gitee.com 等域名
- 以 .git 结尾
- 形如 org/repo（GitHub 短格式，需二次确认）

根据输入类型处理：

① 本地路径（直接使用）

• 用户明确给了本地路径 → 直接使用
• 用户没给路径 → 默认用当前工作目录（cwd）
• 跳过 0.1.1 小节，直接进入 0.2

② Git 链接（先 clone 再分析）

步骤：

1. 选择克隆目标目录：使用 session temp 目录 作为 clone 根目录。从 <user_info> 读取 Session Temp Directory 路径。
   - 克隆路径：{session-temp-dir}/cloned-repos/{repo-name}
   - {repo-name} 从 URL 末段提取（如 https://github.com/org/repo.git → repo）

2. 在 clone 之前，简要告知用户（一行即可）：
   > 检测到 Git 链接，将 clone 到临时目录 {session-temp-dir}/cloned-repos/{repo-name} 后分析。

3. 执行 clone（用 execute_command）：
   bash mkdir -p "{session-temp-dir}/cloned-repos" git clone --depth 1 "{git-url}" "{session-temp-dir}/cloned-repos/{repo-name}"

参数说明：
- --depth 1：只拉最新提交，加速 clone 并节省磁盘（分析用途不需要历史）
- 如果 clone 失败（私有仓库、认证错、网络错），立即停止并向用户反馈：
- 失败原因（stderr 前若干行）
- 建议：配置 SSH key / 切换公有仓库 / 手动 clone 后再调用本 skill

4. clone 成功后：
   - 使用 {session-temp-dir}/cloned-repos/{repo-name} 作为后续分析路径
   - 分析完成后：文档写在克隆的项目根目录内（即 {cloned-path}/{project-name}_overview.md），然后额外拷贝一份到 Output Directory 方便用户取用（命名一致）
   - 向用户明确说明：由于原仓库是 Git 链接，生成的文档位于临时克隆目录，副本已放到 Output Directory

5. Git 链接形如 org/repo 的短格式：
   - 默认视为 https://github.com/org/repo.git
   - 但在 clone 前向用户一行确认："将按 GitHub 链接 https://github.com/org/repo 处理，继续？"
   - 用户否定则停止

③ 特殊情况

• URL 指向某个子目录（如 https://github.com/org/repo/tree/main/packages/foo）：
• 先 clone 整个仓库
• 再把分析路径设为 {cloned-path}/packages/foo

• 这种情况天然适合 Module Mode（因为用户显式指向了子目录）

• 用户一次给了多个 Git 链接：一个一个来，做完一个再做下一个

0.2 判断分析范围（Project vs Module）⭐ 重要

按以下顺序判断，第一个满足的条件决定模式：

1. 用户明确说了 → 按用户说的做
   - "分析这个项目" / "项目概览" / "summarize project" → Project Mode
   - "分析这个模块/包/目录" / "module overview" / "说说这个包" → Module Mode

2. 路径自身含语言标识文件 → Project Mode
   - 路径下直接有 go.mod / package.json / pyproject.toml / setup.py / pom.xml / build.gradle / Cargo.toml / Gemfile / composer.json 之一

3. 路径向上追溯能找到标识文件 → Module Mode
   - 从目标路径开始，向上逐级查找最多 5 层父目录，若找到标识文件 → 当前是该项目内的一个模块
   - 记录父项目根路径和项目语言，模块分析时要用

4. 都找不到标识文件 → 询问用户意图
   - 可能是纯文档目录、脚本集合、多项目聚合等特殊情况
   - 让用户选择：按 Project Mode 处理 / 按 Module Mode 处理 / 跳过

0.3 提取命名

• Project Mode：{project-name} = 项目根目录名
• Module Mode：
• {module-name} = 目标目录名
• {parent-project-name} = 父项目根目录名（用于"模块在项目中的定位"章节）
• {module-rel-path} = 模块相对父项目根的路径（如 internal/app/task）

0.4 向用户展示判断结果（简短）

在开始 Phase 1 前，一句话告诉用户识别结果：
> 识别为 Project Mode：将分析 {path} 作为独立项目。
>
> 或：
>
> 识别为 Module Mode：将分析 {module-rel-path}，它是父项目 {parent-project-name} 的一个模块。

不需要用户确认，直接继续（除非模式判断失败需要用户介入）。

Phase 1：语言与框架识别（Language & Framework Detection）

扫描标识文件。详见 references/language_signals.md。

Project Mode：扫描项目根目录的标识文件。
Module Mode：扫描父项目根目录的标识文件（模块本身通常没有独立的标识文件）。

最低限度要识别出：
- 主语言（Go / JS / TS / Python / Java / Rust / …）
- 主要框架（如 Gin / tRPC / Express / FastAPI / Spring Boot / React / Vue / …）
- 项目类型（Web 服务 / CLI / Library / Microservice / Monorepo / Frontend App / …）
- 构建/运行方式（Makefile / npm scripts / Dockerfile / docker-compose / …）

> 模块级分析也需要这些信息，因为"模块在什么技术栈中运行"是理解模块的前提。

Phase 2：结构扫描（Structure Scan）

通用忽略目录

node_modules, vendor, dist, build, target, .git, .idea, .vscode,
__pycache__, .pytest_cache, coverage, .next, .nuxt

Project Mode

1. 列出顶层目录和文件
2. 识别入口文件（main.go / cmd/*/main.go / index.ts / app.py / Main.java / main.rs 等）
3. 识别配置文件（Dockerfile / *.yaml / .env.example / config/ / conf/）
4. 识别文档（README.md / docs/ / CHANGELOG.md）— 务必优先精读 README，它是"项目定位"和"典型场景"的金矿
5. 统计每个顶层目录的文件数/代码行数，作为识别"核心模块"的权重依据

Module Mode

1. 列出模块目录内的子目录和文件（所有分析都限定在模块目录内部）
2. 识别模块入口/门面文件（优先级从高到低）：
   - index.ts / index.js / mod.rs / __init__.py / package.go
   - service.* / handler.* / api.* / main.*
   - 与模块同名的文件（如模块 task/，则 task.go / task.py 为候选入口）
3. 读取模块内的文档（若有）：
   - 模块内的 README.md / doc.go / __init__.py 顶注释
   - 父项目 docs/ 中明确提到该模块的段落
4. 上溯扫描"调用方"（模块级独有）：
   - 用 search_content 在父项目根范围内搜索对本模块的 import/引用
   - 记录所有引用点，作为"上游调用方"清单（参见 references/module_analysis.md）
5. 扫描"下游依赖"（模块级独有）：
   - 读取模块内所有源文件的 import 语句
   - 区分"内部依赖（父项目其他模块）"和"外部依赖（第三方库）"

Phase 3：核心分析（Core Analysis）

Project Mode — 模块维度分析

对每个源码目录（通常是 src/ / internal/ / app/ / lib/ / packages/ 下的子目录）：

1. 判断是否为"核心模块"：参见 references/core_signals.md。不限数量，只要满足核心信号就列出。
2. 提取每个模块的职责（读 README、入口文件、目录名、doc.go / __init__.py / 顶层注释）
3. 提取核心函数/类（信号见下方"核心符号信号"）
4. 分析模块间的依赖关系（import / require / use）

Module Mode — 子包/文件维度分析

对模块内部的每个子目录和关键文件：

1. 识别模块内的子包/核心文件（粒度比 Project Mode 更细）：
   - 每个子目录都要分析
   - 每个核心源文件都要展开
2. 提取核心函数/类（同下方信号）
3. 分析子包之间的内部依赖
4. 提取"对外暴露的 API"（模块级独有且最重要）：
   - 识别所有可被外部调用的符号：公开函数、公开类型、公开常量、公开接口
   - Go：首字母大写的符号
   - JS/TS：export / export default
   - Python：不以 _ 开头的符号，或 __all__ 中列出的
   - Java：public 修饰符
   - Rust：pub 修饰符
5. 识别接口契约（Interface / Abstract / Protocol）：
   - 这是上游依赖本模块时的"合同"，必须列出

核心符号信号（通用，两种模式共享）

• 入口函数 / 模块初始化函数
• 被引用多次的公开函数（Project ≥ 3 次 / Module ≥ 2 次）
• 实现关键 interface / abstract class 的方法
• 命名含 Handle / Execute / Process / Run / Dispatch / Serve / Start / Init 的公开方法
• 文件名为 service / handler / controller / manager / scheduler / engine 里的公开方法

Phase 4：关键场景识别（Critical Flow Detection）

Project Mode — 关键业务场景

综合使用以下策略，优先业务相关的场景：

1. 从 README 和 docs/ 里提取关键词/场景描述（如"扩容"、"下单"、"登录"、"发布"）
2. 扫描测试文件名（TestXxx / test_xxx.py / *.spec.ts）— 测试覆盖的就是核心场景
3. 寻找最长的调用链（从 API/路由入口 → Service → DAO/外部依赖）
4. 寻找带业务关键词的 RPC / API handler

不要只选 1 个，尽量多列几个关键场景。每个场景都要：
- 描述业务含义
- 画出调用链
- 列出涉及的文件和关键函数
- 画 Mermaid 时序图或流程图

Module Mode — 模块使用场景

场景的视角不同：这里关注"外部如何使用本模块"和"本模块内部如何处理一次典型调用"。

1. 上游调用场景（典型使用模式）：
   - 从 Phase 2 得到的"上游调用方"清单里，挑 2-3 个有代表性的调用点
   - 展示：调用方怎么传参 → 模块内部如何处理 → 返回什么
2. 模块内部流程（一次典型调用的内部处理）：
   - 从模块入口到最深调用的完整链路
   - Mermaid 时序图展示内部组件交互
3. 扩展点 / 定制点（若有）：
   - 若模块暴露接口/钩子让上游定制，列出这些扩展点
   - 参考 references/module_analysis.md 的"扩展点识别"

Phase 5：同类项目对比判断（仅 Project Mode）

> Module Mode 跳过此 Phase。模块级分析不做对比（模块强绑定父项目上下文，类比意义不大）。

触发条件（只要满足其一就尝试对比）：
- 项目根目录有 LICENSE 文件
- README.md 有 GitHub star badge、下载量 badge
- .git/config 有 github/gitlab remote 且是公开仓库
- 项目名或 README 中提到是"开源"、"Open Source"、"AI Agent"、"热门框架"等
- 项目属于热门技术领域（AI Agent、大模型、区块链、云原生、开发者工具等）

满足条件时，执行：
1. 提取项目的核心定位关键词（如"AI agent framework"、"RPC framework"、"code editor"）
2. 用 web_search 搜索 3-5 个同类项目
3. 从定位、技术栈、核心能力、设计理念、适用场景五个维度做对比
4. 输出一个对比表格

不满足条件时：跳过该章节，不要强行对比。

Phase 6：生成文档（Assemble）

按模式选择对应模板组装 Markdown：

• Project Mode → 写入 {project-path}/{project-name}_overview.md，用下文 📄 Project Mode 文档模板
• Module Mode → 写入 {module-path}/{module-name}_overview.md，用下文 📄 Module Mode 文档模板

Phase 7：验证（Verify）

生成后，做一次快速检查：
- ✅ 所有 Mermaid 代码块语法正确（graph / flowchart / sequenceDiagram / classDiagram 等）
- ✅ 所有相对路径引用存在
- ✅ 所有代码示例有语言标签（```go / ```python 等）
- ✅ 章节编号连续，标题层级正确

向用户汇报：
- 分析模式（Project / Module）
- 代码来源（本地路径 / Git 链接 clone）
- 文档路径（如果来源是 Git，同时给出"项目内原始文档路径"和"Output 副本路径"）
- 章节数、字数估算
- 识别出的核心模块/子包数、关键场景数
- 是否包含对比章节（仅 Project Mode）
- （Module Mode）识别到的对外暴露符号数、上游调用方数

📄 Project Mode 文档模板（Project Mode Template）

Project Mode 生成的文档必须包含以下 10 个章节（第 10 章按需）。每个章节下给出了写作要点。

# {project-name} 项目概览

> 本文档由 project-overview-generator 自动生成。基于对 `{扫描的顶层目录}` 等目录的分模块阅读整理，面向希望快速上手本项目的新开发者。

---

## 一、项目是什么

### 一句话定位
**{project-name}** 是一个 {领域 + 核心能力} 的 {项目类型}。

### 核心价值
- {价值点 1}
- {价值点 2}
- {价值点 3}

### 适用场景 / 使用人群
- {场景/角色 1}
- {场景/角色 2}

### 项目状态
- 版本：{从 package.json / VERSION / git tag 推断}
- 活跃度：{从 git log 最近 commit 推断}
- 许可证：{从 LICENSE 推断}

---

## 二、快速开始（Quick Start）

### 前置要求
- {语言运行时版本}
- {必要的基础设施，如 Docker / 数据库 / Redis 等}

### 安装与运行
```bash
# 1. 克隆代码
git clone {repo-url}
cd {project-name}

# 2. 安装依赖
{根据语言填充：go mod download / npm install / pip install -r requirements.txt / mvn install / cargo build}

# 3. 配置（如需）
{从 .env.example / config/*.example 填充}

# 4. 启动
{从 Makefile / package.json scripts / README 填充实际启动命令}
```

### 验证运行
{从 README / 源码推断验证方式，如访问 http://localhost:8080/health}

### 常见启动问题
{从 README FAQ / ISSUES 模板推断，如果没有就先留空或写"首次启动如遇问题请查阅 X"}

---

## 三、核心概念（Core Concepts）

> 理解这些概念后再读代码，会事半功倍。

### 1. {概念1名称}
- **是什么**：{1-2 句话}
- **为什么重要**：{在项目中扮演的角色}
- **涉及代码**：`{path/to/key/file}`

### 2. {概念2名称}
...

---

## 四、技术栈（Tech Stack）

| 分类 | 选型 | 说明 |
|------|------|------|
| 语言 | {Go 1.21 / Node 18 / ...} | |
| 主框架 | {tRPC-Go / Express / Django / ...} | |
| Web/RPC | | |
| 数据存储 | {MySQL / PostgreSQL / Redis / ...} | |
| 消息队列 | {Kafka / RabbitMQ / ...} | |
| 基础设施 | {Docker / K8s / ...} | |
| 构建工具 | {Make / Webpack / Gradle / ...} | |
| 测试 | {go test / Jest / pytest / ...} | |
| CI/CD | {GitHub Actions / GitLab CI / ...} | |

---

## 五、系统架构（Architecture）

### 整体架构图

```mermaid
flowchart TD
    {按识别的层次绘制}
```

### 模块依赖图

```mermaid
graph LR
    {按 import 关系绘制核心模块之间的依赖}
```

### 核心数据流 / 主流程

```mermaid
sequenceDiagram
    {画 1 个最典型的请求/任务流}
```

---

## 六、目录结构（Directory Layout）

### 顶层目录

```
{project-name}/
├── {dir1}/      # {职责说明}
├── {dir2}/      # {职责说明}
...
```

### 设计约定
- {项目中发现的约定，如 "每个模块内自建 dao/service" / "Controller 不直接调用 Repository"}
- {命名约定}
- {其他约定}

---

## 七、核心模块详解（Core Modules）

> 核心理念：**每个核心模块都要展开讲清楚**，不限制篇幅。包含职责、文件清单、核心函数签名和关键逻辑代码。

### 1. `{module-path}` — {模块一句话定位}

**职责**：
- {职责 1}
- {职责 2}

**文件清单**：

| 文件 | 职责 |
|------|------|
| `{file1}` | {一句话职责} |
| `{file2}` | {一句话职责} |

**核心函数 / 类**：

#### `FunctionName(args) ReturnType`
- **位置**：`path/to/file.go:42`
- **职责**：{为什么存在、做什么}
- **调用关系**：被 `XxxCaller` 调用；调用 `YyyDep`、`ZzzDep`

**关键逻辑**：

```go
func (s *Service) Handle(ctx context.Context, req *Request) (*Response, error) {
    // 1. 参数校验
    if err := req.Validate(); err != nil {
        return nil, err
    }

    // 2. 核心业务 —— 这段是整个函数的精髓
    result, err := s.engine.Process(ctx, req.Data)
    if err != nil {
        // 失败回滚，保证幂等
        s.rollback(ctx, req.ID)
        return nil, err
    }

    // 3. 异步通知（非关键路径，略）
    go s.notify(ctx, result)

    return &Response{Data: result}, nil
}
```

**说明 / 注意事项**：
- {坑点、隐含约定、并发安全性等}

---

### 2. `{module-path}` — ...

{按同样的模板展开}

---

(继续列出所有核心模块，不限数量)

---

## 八、关键业务场景 / 路径分析（Critical Flows）

> 基于 README、测试用例、最长调用链综合识别。每个场景都画出完整的代码路径。

### 场景 1：{场景名，如"用户登录"/"任务扩容"}

**业务含义**：{1-2 句话描述}

**触发入口**：`{API / CLI / 定时任务}`

**调用链**：

```
[1] api/auth/login.go:Login()               ← HTTP/RPC handler
    ↓
[2] internal/app/auth/service.go:Auth()     ← 业务逻辑
    ↓
[3] internal/pkg/jwt/token.go:Generate()    ← JWT 签发
    ↓
[4] internal/pkg/db/user_repo.go:FindByEmail() ← DB 查询
```

**时序图**：

```mermaid
sequenceDiagram
    participant C as Client
    participant A as API Handler
    participant S as Auth Service
    participant D as Database

    C->>A: POST /login {email, password}
    A->>S: Auth(email, password)
    S->>D: FindByEmail(email)
    D-->>S: User{hash}
    S->>S: bcrypt.Compare(password, hash)
    S-->>A: JWT token
    A-->>C: 200 {token}
```

**涉及文件**：
- `api/auth/login.go`
- `internal/app/auth/service.go`
- `internal/pkg/jwt/token.go`
- `internal/pkg/db/user_repo.go`

**新手建议阅读顺序**：
1. 先读 `{入口文件}`
2. 再读 `{核心逻辑文件}`
3. 最后读 `{依赖细节}`

---

### 场景 2：...

(继续列出所有识别到的关键场景，不限数量)

---

## 九、如何运行 / 部署（How to Run）

### 本地开发
{从 Makefile / scripts / README 填充}

### 运行测试
```bash
{实际命令}
```

### 构建镜像 / 打包
```bash
{实际命令}
```

### 部署
{从 Dockerfile / k8s manifests / CI 配置推断}

### 环境变量 / 配置清单
{从 .env.example / config 模板枚举}

### 关键运行时日志 / 观测
- 日志位置：
- 健康检查：
- 监控指标：

---

## 十、与同类项目对比（仅当识别为知名/开源项目）

> 本章节仅在项目被识别为开源项目时生成。

### 同类项目选型

| 项目 | 定位 | 技术栈 | 主要差异 |
|------|------|--------|----------|
| **{本项目}** | {定位} | {栈} | — |
| {竞品A} | {定位} | {栈} | {关键差异} |
| {竞品B} | {定位} | {栈} | {关键差异} |

### 关键维度对比

#### 定位
- **{本项目}**：...
- **{竞品A}**：...

#### 技术栈
- **{本项目}**：...
- **{竞品A}**：...

#### 核心能力
- **{本项目}**：...
- **{竞品A}**：...

#### 设计理念
- **{本项目}**：...
- **{竞品A}**：...

#### 适用场景
- **{本项目}**：...
- **{竞品A}**：...

### 推荐阅读顺序
如果你熟悉 **{竞品A}**，那么理解 **{本项目}** 可以从对比 {具体模块} 开始...

---

## 附录

### 术语表 / Glossary
| 缩写 | 全称 | 含义 |
|------|------|------|
| | | |

### 文档自动生成说明
- 生成时间：{date}
- 生成工具：`project-overview-generator` skill（Project Mode）
- 代码来源：{本地路径 `/path/to/project` 或 Git 链接 `https://github.com/xxx/xxx` @ commit `abc1234`}
- 扫描范围：{顶层目录列表}
- 识别核心模块数：{N}
- 识别关键场景数：{M}

📄 Module Mode 文档模板（Module Mode Template）

Module Mode 生成的文档必须包含以下 8 个章节。更关注"角色、边界、内部结构、使用方式"，不做独立运行和同类对比。

# {module-name} 模块概览

> 本文档由 project-overview-generator 自动生成（Module Mode）。
> 所属项目：**{parent-project-name}** · 模块路径：`{module-rel-path}`
> 面向希望快速上手本模块的开发者（贡献者、调用方、新成员）。

---

## 一、模块定位（What This Module Does）

### 一句话定位
`{module-rel-path}` 是 **{parent-project-name}** 项目中负责 {模块职责} 的模块。

### 在系统中的角色
- **上游（谁会用它）**：{从"上游调用方"清单概括}
- **下游（它依赖谁）**：{关键依赖}
- **分层位置**：{API 层 / 业务层 / 基础设施层 / 工具层 / ...}

### 何时需要关注本模块
- 修改 / 扩展 {模块职责} 相关功能时
- 排查涉及 {关键词} 的问题时
- （其他触发场景）

---

## 二、核心概念（Core Concepts）

> 本模块内部的关键抽象。读完本节再看代码能少走弯路。

### 1. {概念1}
- **是什么**：
- **为什么重要**：
- **涉及文件**：`{path}`

### 2. {概念2}
...

---

## 三、模块架构（Module Architecture）

### 内部结构图

```mermaid
flowchart TD
    {画模块内部的子包/核心组件关系}
```

### 与外部的边界

```mermaid
flowchart LR
    Upstream["上游调用方<br/>(api/xxx, service/yyy)"]
    M["【本模块】<br/>{module-name}"]
    Down1["依赖: internal/pkg/db"]
    Down2["依赖: 第三方 xxx/yyy"]

    Upstream -->|调用| M
    M --> Down1
    M --> Down2
```

### 典型调用时序

```mermaid
sequenceDiagram
    participant U as 上游调用方
    participant M as 模块入口
    participant C as 内部组件
    U->>M: Method(ctx, req)
    M->>C: ...
    C-->>M: ...
    M-->>U: resp
```

---

## 四、目录结构（Internal Layout）

```
{module-name}/
├── {subdir1}/   # 职责说明
├── {subdir2}/   # 职责说明
├── {file1}      # 职责说明
├── {file2}      # 职责说明
...
```

### 模块内部约定
- {命名约定 / 分层约定 / 依赖注入规则}
- {子包之间是否允许互相调用、依赖方向限制等}

---

## 五、核心符号详解（Core Symbols）

> 把**模块内部重要的类型、函数、接口**逐个展开。不限数量，凡满足核心信号都列出。

### 1. `{子包/文件}`

**职责**：
- ...

**文件清单**：

| 文件 | 职责 |
|------|------|
| ... | ... |

#### `SymbolName` — {签名}
- **位置**：`path/to/file.ext:LINE`
- **角色**：{入口 / 核心编排 / 状态管理 / 工具类 / ...}
- **调用关系**：被 {哪些地方} 调用；调用 {哪些下游}
- **关键逻辑**：

```{language}
// 按 core_signals.md 的"关键逻辑代码展示规则"裁剪
```

**说明 / 注意事项**：
- {坑点、并发安全、幂等、性能考量等}

---

### 2. `{子包/文件}`
...（按同样模板展开所有核心子包/文件）

---

## 六、🔌 模块边界（Boundary & Contract）⭐ 模块模式关键章节

### 6.1 对外暴露的 API（Exported Surface）

所有可被外部调用的符号清单：

| 符号 | 类型 | 签名 / 形态 | 职责 | 稳定性 |
|------|------|-------------|------|--------|
| `NewService` | Constructor | `func NewService(cfg Config) *Service` | 模块实例化入口 | ✅ 稳定 |
| `Config` | Struct | `struct { ... }` | 模块配置 | ✅ 稳定 |
| `Service.Handle` | Method | `func (s *Service) Handle(ctx, req) (resp, error)` | 核心方法 | ✅ 稳定 |
| `SomeInterface` | Interface | `interface { M1(); M2() }` | 扩展点 | ⚠️ 内部可能调整 |
| ... | ... | ... | ... | ... |

### 6.2 接口契约（Interface Contracts）

列出模块对外定义的接口/协议：

```{language}
type XxxInterface interface {
    // 契约：...
    Method1(ctx context.Context, req *Req) (*Resp, error)
}
```

**契约说明**：
- 上游通过接口依赖本模块，便于 mock 和替换
- 实现要求：{并发安全 / 幂等 / 超时约定 / 错误语义}

### 6.3 上游调用方（Who Uses This Module）

> 扫描父项目得到的所有引用点，分组列出（按调用方模块归纳）：

| 调用方 | 引用位置 | 使用方式 |
|--------|----------|----------|
| `{parent-project}/api/xxx` | `api/xxx/handler.go:45` | 直接调用 `NewService` 并 Handle |
| `{parent-project}/app/yyy` | `app/yyy/service.go:123` | 通过 DI 注入 `XxxInterface` |
| ... | ... | ... |

**共 N 处引用**。典型用法：{概括 2-3 句}

### 6.4 下游依赖（What This Module Depends On）

#### 内部依赖（父项目其他模块）
- `internal/pkg/db` — 用于持久化
- `internal/pkg/cache` — 用于缓存
- ...

#### 外部依赖（第三方库）
- `github.com/xxx/yyy` — ...
- `redis/go-redis` — ...

### 6.5 扩展点（Extension Points）

> 若模块提供钩子 / 插件机制 / 可替换组件，在此说明。

- **{扩展点名}**：实现 `XxxInterface` 并通过 `RegisterXxx()` 注册
- ...

---

## 七、典型使用场景（Usage Scenarios）

> 从"怎么用"的视角展示模块，帮助调用方上手。

### 场景 1：{典型场景}

**使用方**：{调用方模块 / 上层业务}

**代码示例**（来自实际调用点 `path/to/caller.ext:LINE`）：

```{language}
// 上游调用方的真实代码片段
```

**内部处理流程**：

```mermaid
sequenceDiagram
    ...
```

**注意事项**：
- ...

### 场景 2：{另一个场景}
...

---

## 八、修改与贡献指南（How to Modify）

### 常见修改任务
- **新增一个 {子功能}**：
  1. 在 `{path}` 添加 ...
  2. 注册到 `{哪里}`
  3. 更新测试 `{path}`
- **修改现有 {功能}**：重点文件 `{path}`
- **新增一个 {扩展点实现}**：实现 `XxxInterface` 并在 `{path}` 注册

### 本模块的测试
```bash
{运行模块测试的命令，如 go test ./internal/app/task/...}
```

### 调试技巧
- 打开日志级别：`{具体方式}`
- 模拟外部依赖：`{mock 方式}`
- 常见坑点：{如"并发访问 X 需加锁"}

### 新手建议阅读顺序
1. 先读 **第六章 · 模块边界** — 弄清楚模块"从外面看是什么"
2. 再读 **第三章 · 模块架构** — 弄清楚内部是怎么组织的
3. 然后按 **第五章 · 核心符号** 的顺序读代码
4. 最后用 **第七章 · 使用场景** 里的实际调用点串联验证

---

## 附录

### 术语表
| 缩写 | 全称 | 含义 |
|------|------|------|

### 文档自动生成说明
- 生成时间：{date}
- 生成工具：`project-overview-generator` skill（Module Mode）
- 代码来源：{本地路径 `/path/to/project` 或 Git 链接 `https://github.com/xxx/xxx` @ commit `abc1234`}
- 所属项目：`{parent-project-name}`
- 模块路径：`{module-rel-path}`
- 核心子包/文件数：{N}
- 对外暴露符号数：{M}
- 上游引用数：{K}

📚 参考资源

按需加载以下 references：

• references/language_signals.md — 各语言的识别规则、入口文件、典型目录布局
• references/core_signals.md — 核心模块 / 核心函数的判定信号（加权规则）
• references/mermaid_templates.md — Mermaid 图常用模板（架构图、时序图、依赖图）
• references/section_templates.md — Project Mode 各章节的详细写作范例（core_admin 最佳实践）
• references/module_analysis.md — Module Mode 专属：模块边界识别、上游扫描、API 提取、扩展点识别等策略

💡 写作原则（对 Agent 的提醒）

1. 不要偷懒摘要：每个核心模块的职责必须明确描述，不能用"提供各种功能"这种空话。
2. 代码示例要真：从项目里抄真实代码，不要自己编造。遇到过长的函数，保留签名和关键分支，用注释 // 略：{几句话说清楚做了什么} 替代。
3. 发现项目约定要记录：比如"DAO 不跨模块调用"、"所有 service 通过接口注入" —— 这些约定对新手极有价值，写在「目录结构 - 设计约定」或「核心模块 - 说明」里。
4. Mermaid 图宁少勿错：语法错误的图会破坏阅读体验。生成后务必检查，至少画 3 张（架构、依赖、主流程时序）。
5. 遇到不确定就明说：实在推断不出来的地方（比如部署方式），写 {待补充：未在代码中找到明确说明}，而不是瞎编。
6. 中文输出：默认生成中文文档（因为用户是中文用户）。如果项目本身是英文项目且 README 是英文，可以保留英文术语但整体用中文说明。
7. 对比章节要公允：不要贬低竞品。如实描述差异，不做价值判断。
8. Module Mode 特殊提醒：
   - 一定要扫上游：模块最珍贵的信息是"谁在用我、怎么用"，漏掉这部分等于文档砍半
   - 对外 API 必须枚举完整：即使一个模块有 30 个公开符号，也要全部列表（可用表格压缩）
   - 优先展示接口而非实现：模块的"契约"比"实现细节"对上游更重要
   - 不要写"如何启动模块"：模块不能独立启动，写了就是误导
9. Git 链接来源的特殊提醒：
   - 附录必须注明来源：在文档附录写明 来源：{git-url}，commit hash（可用 git rev-parse HEAD 获取）
   - "快速开始"章节用原始 URL：git clone {git-url} 要写原始链接，不要写临时目录路径
   - Output 副本与原始文档内容一致：两份文档内容完全相同，只是路径不同
   - clone 失败不要重试超过 2 次：频繁失败立刻让用户介入，不要卡死流程