teamai-cli 0.16.8 → 0.17.0

package/skills/team-wiki-codebase/references/methodology/phase4-quality.md

@@ -0,0 +1,232 @@
+# Phase 4: 质量评估与迭代优化
+
+> 辅助工具: `scripts/validate_kb.py` — 自动校验链接完整性、anchor 覆盖率、AI 快速理解表覆盖率、双向链接、README 索引收录率
+
+## 五维评估模型
+
+| 维度 | 权重 | 达标标准 |
+|------|------|---------|
+| **覆盖率** | 25% | ≥ 90% 核心组件有文档 |
+| **深度** | 25% | ≥ 80% 代码入口可直接定位 |
+| **一致性** | 20% | 0 死链接，0 矛盾描述 |
+| **AI 可用性** | 20% | RAG 检索准确率 ≥ 85% |
+| **时效性** | 10% | 核心文档更新滞后 ≤ 30 天 |
+
+## 覆盖率检查
+
+```
+□ 每个代码仓库有对应的组件设计文档？
+□ 每个核心 API 有产品-代码映射？
+□ 每个数据表在某份文档中有 Schema 说明？
+□ 每个 MQ Exchange/Topic/Queue 在拓扑图中标注？
+□ 每个错误码在映射表中？
+□ 每个配置项在配置说明中？
+□ 每个定时任务在某份文档中说明？
+```
+
+## RAG 检索测试用例
+
+| 测试类型 | 示例问题 | 期望命中 |
+|---------|---------|---------|
+| 组件定位 | "{组件名}的代码入口在哪？" | 组件设计文档 |
+| 流程追踪 | "{API名}的内部调用链路？" | 产品-代码映射 |
+| 约束查询 | "{操作}的批量上限？" | 规则速查表 |
+| 状态查询 | "处于{状态}时可执行什么操作？" | 状态互斥规则 |
+| 错误排查 | "遇到{错误码}怎么排查？" | 反模式/排障记录 |
+| 代码生成 | "写一个{功能}的 Handler" | SOP + 接口契约 |
+| 概念辨析 | "{A}和{B}区别？" | 产品知识文库 |
+
+## 增量更新触发表
+
+| 触发条件 | 更新动作 |
+|---------|---------|
+| 新增代码仓库 | 生成 Type-4 组件文档 |
+| API 接口变更 | 更新 Type-5 映射 + Type-6 速查表 |
+| 新增产品功能 | 更新 Type-2 业务架构 + Type-8a 知识文库 |
+| 线上故障 | 新增 Type-8d 排障记录 + 更新 Type-8b 反模式 |
+| 架构重构 | 更新 Type-1 架构总览 + 受影响 Type-4 |
+| 配置变更 | 更新对应组件文档的配置章节 |
+
+## 版本管理规范
+
+每份文档底部维护变更记录：
+
+```markdown
+## 📝 文档更新记录
+
+### vX.Y (YYYY-MM-DD)
+- ✅ **新增**: {新增内容描述}
+- ✅ **修复**: {修复内容描述}
+- ✅ **更新**: {更新内容描述}
+- ⚠️ **废弃**: {废弃内容描述}
+```
+
+## 常见质量问题修复
+
+| 问题 | 修复方法 |
+|------|---------|
+| 死链接 | 全局 grep `](` 链接，或运行 `scripts/validate_kb.py` |
+| 术语不一致 | 建立术语表全局替换 |
+| 代码入口过时 | 定期与代码仓库 diff |
+| 约束值过时 | 定期与产品文档交叉比对 |
+| AI 检索失败 | 补充 search-anchor 关键词 |
+| 文档孤岛 | 补充双向链接 |
+
+---
+
+## 完整生成流水线 Checklist
+
+### Phase 0 Checklist: 源材料采集
+
+```
+□ 所有核心代码仓库已克隆
+□ 产品 API 文档已采集 (接口名/入参/出参/错误码)
+□ 产品使用文档已采集 (使用限制/FAQ/计费说明)
+□ 数据库 Schema 已提取 (DDL/表结构)
+□ 流程编排配置已提取 (workflow_config 等)
+□ Proto/IDL 文件已提取
+□ 错误码定义已提取
+```
+
+### Phase 1 Checklist: 架构逆向工程
+
+```
+□ 代码知识图谱已构建 (节点+边)
+□ 架构分层已确定 (≥4 层)
+□ 组件关系矩阵已构建 (N×N)
+□ 核心调用链已追踪 (≥5 条核心 API)
+□ MQ 拓扑已推断 (Exchange/Topic/Queue/Routing Key)
+□ 数据库 ER 模型已构建
+□ 术语表已整理 (内外部映射)
+```
+
+### Phase 2 Checklist: 文档生成
+
+```
+□ [Type-1] 技术架构总览文档 (1份)
+  □ 包含读者导航指南
+  □ 包含 AI 检索路由规则
+  □ 包含核心链路时序图 (≥5 条)
+  □ 包含组件关系矩阵
+  □ 包含 AI 专用第 9 章
+  □ 包含术语表
+
+□ [Type-2] 业务架构文档 (1份)
+  □ 包含产品能力矩阵
+  □ 包含计费模型（如适用）
+  □ 包含核心实体生命周期状态机
+
+□ [Type-3] 部署架构文档 (1份)
+  □ 包含服务部署矩阵
+  □ 包含环境配置
+
+□ [Type-4] 组件设计文档 (N份)
+  □ 每份包含 AI 快速理解表
+  □ 每份包含双向链接
+  □ 每份包含代码入口 (精确到函数)
+  □ 每份包含架构图 (ASCII Art)
+  □ 每份包含核心流程说明
+
+□ [Type-5] 产品-代码映射文档
+  □ 覆盖所有核心 API
+  □ 每个 API 包含约束表
+  □ 每个 API 包含调用链路
+  □ 每个 API 包含错误码映射
+
+□ [Type-6] 产品规则速查表
+  □ 覆盖所有规则类别
+  □ 约束值精确
+  □ 包含状态互斥矩阵
+
+□ [Type-7] 业务开发规范 SOP
+  □ 包含可运行的代码模板
+  □ 包含错误码对照表
+  □ 包含 AI 评审 CheckList
+
+□ [Type-8] 知识增强文档
+  □ [8a] 产品知识文库 (概念辨析)
+  □ [8b] 反模式与踩坑指南
+  □ [8c] RPC 接口契约
+  □ [8d] 排障案例记录
+```
+
+### Phase 3 Checklist: AI-Native 增强
+
+```
+□ 所有组件文档包含 AI 快速理解表
+□ 主架构文档包含检索路由规则
+□ 所有文档包含 search-anchor
+□ 双向链接网络完整 (0 死链接)
+□ QA 对已生成 (10~20 个)
+□ 文档优先级已定义
+```
+
+### Phase 3b Checklist: 图谱文档集 (Graph RAG)
+
+```
+□ [G1] 组件依赖关系矩阵
+  □ N×N 通信矩阵完整
+  □ 正向/反向依赖索引
+  □ 外部服务依赖
+
+□ [G2] 组件调用链路全景 + 状态机
+  □ 核心 API 端到端链路 (读+写)
+  □ 完整 mermaid 状态机流转图
+  □ 核心状态字段值流转路径表（如有内部状态码）
+  □ 用户可见状态↔内部状态映射关系（如有多层状态）
+  □ 操作-状态约束速查矩阵 (✅/❌)
+  □ AI 状态判断推理规则
+
+□ [G3] 数据流与存储依赖图
+  □ 存储系统依赖矩阵
+  □ MQ 队列拓扑
+  □ 缓存策略矩阵
+
+□ [G4] 错误码组件映射表
+  □ 错误码段分配表
+  □ 外部→内部错误码映射
+
+□ [G5] 跨组件交互场景手册
+  □ ≥10 个场景的 mermaid 时序图
+  □ 每个场景有异常处理
+
+□ [G6] 知识图谱三元组
+  □ Ontology 定义 (实体类型+关系类型)
+  □ 显式三元组 ≥100 条
+  □ 多跳依赖路径索引
+  □ 反向可达索引
+
+□ [G7] 架构风险与影响面分析
+  □ 组件风险等级总表
+  □ 爆炸半径分析 (≥3 个关键组件)
+  □ 聚类分析
+  □ 变更风险评估矩阵
+
+□ [G8] 核心配置参数索引
+  □ 分层配置架构图 (mermaid)
+  □ 每层配置参数表 (配置项/默认值/影响行为/变更风险/生效方式)
+  □ 配置变更影响面速查矩阵
+
+□ [G9] 业务规则约束矩阵
+  □ 操作前置条件矩阵
+  □ 硬件约束详表
+  □ 迁移约束决策树 (mermaid)
+  □ 计费约束详表
+  □ 特殊实例类型约束汇总 (✅/❌/⚠️)
+  □ AI 推理规则速查 (mermaid 流程图)
+
+□ 图谱目录 README.md 索引完整
+  □ 按问题类型查找表
+  □ 检索路由规则建议
+```
+
+### Phase 4 Checklist: 质量评估
+
+```
+□ 覆盖率 ≥ 90%
+□ 代码入口精确度 ≥ 80%
+□ 死链接 = 0 (运行 validate_kb.py 确认)
+□ RAG 检索准确率 ≥ 85%
+□ 核心文档更新滞后 ≤ 30 天
+□ 术语一致性检查通过
+```

package/skills/team-wiki-codebase/references/templates/project-overview.md

@@ -0,0 +1,148 @@
+# 知识库总览模板
+
+> 用于生成 `<output_dir>/README.md`，在 Phase K2 批次5 生成（知识库顶层索引）。
+
+```markdown
+# <项目名称> — 深度知识库
+<!-- search-anchor: <项目名称>, <项目英文名>, 知识库, 架构总览, 快速导航, 组件文档, Graph RAG, 图谱 -->
+
+> **AI 读取指引**：本目录是 AI-Native 知识库。请先阅读本文件了解全局和认知边界，
+> 再按检索路由规则进入对应文档查阅详情。**禁止一次性读取整个知识库目录。**
+
+## 🤖 知识库检索路由指引（AI 专用）
+
+### 按问题类型快速导航
+
+| 我想了解… | 应该读… | 路径 |
+|---------|---------|------|
+| 系统整体架构和分层 | 技术架构文档 | `./{项目名} 技术架构.md` |
+| 某个组件的设计和实现 | 组件设计说明 | `./XX_{组件名}设计说明.md` |
+| 组件之间的依赖关系 | G1 依赖矩阵 | `./graph/G1_*.md` |
+| 某个 API 经过哪些模块 | G2 调用链路全景 | `./graph/G2_*.md` |
+| 数据存在哪里、MQ 拓扑 | G3 数据流 | `./graph/G3_*.md` |
+| 错误码是哪个模块的 | G4 错误码映射 | `./graph/G4_*.md` |
+| 某个业务场景的完整流程 | G5 交互场景手册 | `./graph/G5_*.md` |
+| A 间接依赖谁（多跳查询） | G6 知识图谱三元组 | `./graph/G6_*.md` |
+| X 组件挂了影响多大 | G7 风险分析 | `./graph/G7_*.md` |
+| 怎么修改某个配置 | G8 配置参数索引 | `./graph/G8_*.md` |
+| 某个操作能不能执行 | G9 业务规则约束 | `./graph/G9_*.md` |
+| 产品约束→代码位置映射 | 核心API映射文档 | `./XX_*产品代码映射.md` |
+| 业务开发 SOP | 业务开发规范 | `./XX_*业务开发规范SOP.md` |
+
+### 检索规则
+
+- **规则 1 — 先读索引后深入**：遇到不确定的组件，先读本文件找到正确路径，再深入组件文档
+- **规则 2 — 组件内部问题查组件文档**：核心机制、代码入口、数据模型 → `XX_{组件名}设计说明.md`
+- **规则 3 — 跨组件关系问题查图谱**：依赖矩阵、调用链路、影响面 → `graph/` 目录
+- **规则 4 — 操作可行性问题查 G9**：约束矩阵 + 决策树 → `graph/G9_*.md`
+- **规则 5 — `[UNVERIFIED]` 标注的内容不可用于代码生成**，需先人工确认
+- **规则 6 — `AMBIGUOUS` 关系不可用于变更影响评估**，需先明确
+
+---
+
+## 🚧 认知边界声明（AI 必读）
+
+> 本节声明此知识库**不知道什么**。AI 在回答问题时，如果涉及以下范围，
+> **必须主动告知用户"此信息超出知识库覆盖范围，建议查看源代码/产品文档/联系团队"**，
+> 而不是尝试推断或幻觉。
+
+### 覆盖范围
+
+| 维度 | 覆盖 | 说明 |
+|------|------|------|
+| 代码基准 | `<commit SHA>` (`<tag>`) | 此版本**之后**的变更不在覆盖范围内 |
+| 生成时间 | `<YYYY-MM-DDTHH:MM:SSZ>` | 知识库与代码的时间锚点 |
+| 核心组件（P0） | <P0组件列表> | 文档深度最高，接口级覆盖 |
+| 重要组件（P1） | <P1组件列表> | 文档深度中等，核心机制覆盖 |
+| 辅助组件（P2） | <P2组件列表> | 文档深度有限，仅架构层面 |
+
+### 明确不覆盖（AI 不应尝试回答）
+
+| 领域 | 原因 |
+|------|------|
+| 第三方 SDK/库内部实现 | 知识库只记录调用方式，不涉及第三方源码 |
+| 运维/部署细节（ansible/k8s 配置） | 超出代码知识库范围，需查阅运维文档 |
+| 非代码产出（UI 设计、产品 PRD 原文） | 仅 Type-5/6 桥梁文档有产品约束映射 |
+| 历史架构变迁 | 仅反映当前代码基准版本的架构 |
+| 性能基准数据 | 知识库不包含压测数据 |
+| <项目特定不覆盖项> | <原因> |
+
+### 低可信度区域（AI 回答时需额外警告）
+
+| 区域 | 原因 | 建议 |
+|------|------|------|
+| P2 辅助组件的内部细节 | 文档深度有限 | 引用时加"基于有限文档分析" |
+| `[UNVERIFIED]` 标注内容 | 无法回溯到代码 | 必须告知用户"此信息未经代码验证" |
+| `AMBIGUOUS` 关系 | 置信度 < 0.3 | 必须告知用户"此关系存在不确定性" |
+| 产品文档缺失时的 Type-5/6 | 无产品文档输入 | 标注 `[PRODUCT_DOC_MISSING]` |
+
+### 知识库更新说明
+
+- **增量更新**：使用 `code-to-knowledge --update` 可仅更新变更文件对应的文档
+- **全量重建**：代码发生大规模重构时建议全量重建
+- **上次更新**：`<ISO8601>`
+
+---
+
+## 项目简介
+
+<!-- 1-3 句话：项目背景、核心业务目标、主要用户 -->
+
+## 技术栈
+
+| 类别 | 技术 | 说明 |
+|------|------|------|
+| 语言 | Go / Python | ... |
+| 框架 | go-zero / FastAPI | ... |
+| 数据库 | MySQL / PostgreSQL | ... |
+| 缓存 | Redis | ... |
+| 消息队列 | Kafka / RabbitMQ | （如有） |
+
+## 知识库文档索引
+
+### 架构层文档
+| 文档 | 类型 | 规模 | 说明 |
+|------|------|------|------|
+| {项目名} 技术架构.md | Type-1 | ~200KB | 架构总览 |
+| {项目名} 业务架构.md | Type-2 | ~70KB | 产品能力+生命周期 |
+| {项目名} 部署架构.md | Type-3 | ~40KB | 部署拓扑 |
+
+### 组件设计文档
+| 编号 | 组件 | 架构层 | 核心度 | 规模 |
+|------|------|--------|--------|------|
+| 01 | <组件名> | <层级> | P0 | ~NKB |
+
+### 桥梁文档（有产品文档时生成）
+| 文档 | 类型 | 说明 |
+|------|------|------|
+| 核心API产品代码映射 | Type-5 | 产品约束→代码位置 |
+| 产品规则速查表 | Type-6 | 使用限制/FAQ→代码 |
+| 业务开发规范SOP | Type-7 | 开发/变更操作规范 |
+
+### 图谱文档集（Graph RAG）
+| 文档 | 用途 | 规模 |
+|------|------|------|
+| G1~G9 | 跨组件关系索引 | 详见 `graph/README.md` |
+
+## 知识库质量概览
+
+| 指标 | 数值 | 状态 |
+|------|------|------|
+| 文档总数 | N 份 | — |
+| 内容准确率（有代码引用） | X% | ✅/⚠️ |
+| [UNVERIFIED] 比例 | X% | 目标<15% |
+| 接口覆盖率（非 NONE 组件） | X% | 目标≥90% |
+| AMBIGUOUS 关系数 | N 条 | 需人工确认 |
+
+> 详细质量报告见 `_review/k4-quality-report.md`
+
+## 代码基准版本
+
+> ⚠️ 本知识库基于以下版本代码生成，代码演进后请运行 `code-to-knowledge --update` 增量更新。
+
+- **Commit**：`<git commit SHA>`
+- **Tag**：`<tag 或 "无 tag">`
+- **生成时间**：`<YYYY-MM-DDTHH:MM:SSZ>`
+
+> 版本信息来源：`_review/metadata.json`
+```

package/skills/team-wiki-codebase/scripts/scan_repo.py

@@ -0,0 +1,224 @@
+#!/usr/bin/env python3
+"""
+scan_repo.py — 代码仓库结构扫描与统计工具
+
+用途: Phase 0 源材料采集阶段，快速扫描目标仓库/目录，输出：
+  1. 目录结构树（2层深度）
+  2. 代码统计（语言分布、文件数、总行数）
+  3. 关键文件发现（入口文件、配置文件、Proto/IDL、错误码定义）
+  4. 代码热点（文件行数 Top 20）
+
+使用方式:
+  python3 scan_repo.py /path/to/repo
+  python3 scan_repo.py /path/to/repo --depth 3 --top 30
+"""
+
+import os
+import sys
+import argparse
+from pathlib import Path
+from collections import defaultdict, Counter
+
+# 关键文件匹配模式
+KEY_FILE_PATTERNS = {
+    "入口文件": [
+        "main.py", "main.go", "app.py", "app.ts", "app.js",
+        "server.py", "server.go", "wsgi.py", "manage.py",
+        "cmd/*/main.go", "index.ts", "index.js",
+    ],
+    "路由/Handler": [
+        "*handler*", "*router*", "*controller*", "*dispatch*",
+        "*route*", "*api.*", "*endpoint*",
+    ],
+    "配置文件": [
+        "*.yaml", "*.yml", "*.toml", "*.ini", "*.conf",
+        "*config*", "*.env", "*.env.*",
+    ],
+    "Proto/IDL": [
+        "*.proto", "*.thrift", "*.graphql", "*schema*",
+    ],
+    "数据库/模型": [
+        "*model*", "*dao*", "*repository*", "*migration*",
+        "*schema*", "*.sql", "*db*",
+    ],
+    "常量/错误码": [
+        "*const*", "*constant*", "*error*", "*code*",
+        "*enum*", "*define*", "*exception*",
+    ],
+    "测试文件": [
+        "*_test.*", "test_*", "*.spec.*", "*_spec.*",
+    ],
+}
+
+# 语言扩展名映射
+LANG_MAP = {
+    ".py": "Python", ".go": "Go", ".js": "JavaScript", ".ts": "TypeScript",
+    ".java": "Java", ".rs": "Rust", ".rb": "Ruby", ".php": "PHP",
+    ".c": "C", ".cpp": "C++", ".h": "C/C++ Header",
+    ".proto": "Protobuf", ".thrift": "Thrift", ".graphql": "GraphQL",
+    ".sql": "SQL", ".sh": "Shell", ".bash": "Shell",
+    ".yaml": "YAML", ".yml": "YAML", ".toml": "TOML",
+    ".json": "JSON", ".xml": "XML", ".md": "Markdown",
+}
+
+# 忽略目录
+IGNORE_DIRS = {
+    ".git", ".svn", "node_modules", "__pycache__", ".tox", ".mypy_cache",
+    "venv", ".venv", "env", ".env", "vendor", "dist", "build",
+    ".idea", ".vscode", ".eggs", "*.egg-info",
+}
+
+
+def should_ignore(path: Path) -> bool:
+    for part in path.parts:
+        if part in IGNORE_DIRS or part.endswith(".egg-info"):
+            return True
+    return False
+
+
+def count_lines(filepath: Path) -> int:
+    try:
+        with open(filepath, "r", encoding="utf-8", errors="ignore") as f:
+            return sum(1 for _ in f)
+    except (OSError, UnicodeDecodeError):
+        return 0
+
+
+def match_pattern(filename: str, pattern: str) -> bool:
+    """简单的通配符匹配"""
+    import fnmatch
+    return fnmatch.fnmatch(filename.lower(), pattern.lower())
+
+
+def scan_repository(repo_path: Path, depth: int = 2, top_n: int = 20):
+    """扫描仓库，返回统计结果"""
+
+    all_files = []
+    lang_stats = Counter()       # 语言 -> (文件数, 行数)
+    lang_lines = Counter()
+    key_files = defaultdict(list)
+    dir_tree = []
+
+    # 遍历文件
+    for root, dirs, files in os.walk(repo_path):
+        rel_root = Path(root).relative_to(repo_path)
+
+        # 忽略目录
+        dirs[:] = [d for d in dirs if d not in IGNORE_DIRS and not d.endswith(".egg-info")]
+
+        # 目录树（限制深度）
+        level = len(rel_root.parts)
+        if level <= depth:
+            indent = "  " * level
+            dirname = rel_root.parts[-1] if rel_root.parts else str(repo_path.name)
+            dir_tree.append(f"{indent}├── {dirname}/")
+
+        for fname in files:
+            fpath = Path(root) / fname
+            if should_ignore(fpath.relative_to(repo_path)):
+                continue
+
+            ext = fpath.suffix.lower()
+            lines = count_lines(fpath)
+            rel_path = str(fpath.relative_to(repo_path))
+
+            all_files.append((rel_path, ext, lines))
+
+            # 语言统计
+            lang = LANG_MAP.get(ext)
+            if lang:
+                lang_stats[lang] += 1
+                lang_lines[lang] += lines
+
+            # 关键文件匹配
+            for category, patterns in KEY_FILE_PATTERNS.items():
+                for pattern in patterns:
+                    if match_pattern(fname, pattern):
+                        key_files[category].append((rel_path, lines))
+                        break
+
+    return all_files, lang_stats, lang_lines, key_files, dir_tree
+
+
+def print_report(repo_path: Path, all_files, lang_stats, lang_lines, key_files, dir_tree, top_n: int):
+    """输出扫描报告"""
+
+    total_files = len(all_files)
+    total_lines = sum(f[2] for f in all_files)
+
+    print("=" * 70)
+    print(f"  代码仓库扫描报告: {repo_path.name}")
+    print(f"  路径: {repo_path}")
+    print("=" * 70)
+
+    # 1. 基本统计
+    print(f"\n## 1. 基本统计\n")
+    print(f"| 指标 | 数值 |")
+    print(f"|------|------|")
+    print(f"| 总文件数 | {total_files} |")
+    print(f"| 总代码行数 | {total_lines:,} |")
+    print(f"| 语言种类 | {len(lang_stats)} |")
+
+    # 2. 语言分布
+    print(f"\n## 2. 语言分布\n")
+    print(f"| 语言 | 文件数 | 代码行数 | 占比 |")
+    print(f"|------|--------|---------|------|")
+    for lang, count in lang_stats.most_common(15):
+        lines = lang_lines[lang]
+        pct = f"{lines / total_lines * 100:.1f}%" if total_lines > 0 else "0%"
+        print(f"| {lang} | {count} | {lines:,} | {pct} |")
+
+    # 3. 目录结构
+    print(f"\n## 3. 目录结构（前 30 行）\n")
+    print("```")
+    for line in dir_tree[:30]:
+        print(line)
+    if len(dir_tree) > 30:
+        print(f"  ... ({len(dir_tree) - 30} more directories)")
+    print("```")
+
+    # 4. 关键文件发现
+    print(f"\n## 4. 关键文件发现\n")
+    for category, files in key_files.items():
+        if files:
+            print(f"\n### {category} ({len(files)} 个)\n")
+            # 去重并排序
+            seen = set()
+            for fpath, lines in sorted(files, key=lambda x: -x[1])[:10]:
+                if fpath not in seen:
+                    seen.add(fpath)
+                    print(f"- `{fpath}` ({lines:,} 行)")
+
+    # 5. 代码热点
+    print(f"\n## 5. 代码热点 (Top {top_n})\n")
+    print(f"| 排名 | 文件 | 行数 |")
+    print(f"|------|------|------|")
+    sorted_files = sorted(all_files, key=lambda x: -x[2])
+    for i, (fpath, ext, lines) in enumerate(sorted_files[:top_n], 1):
+        print(f"| {i} | `{fpath}` | {lines:,} |")
+
+    print(f"\n{'=' * 70}")
+    print(f"  扫描完成。共 {total_files} 个文件，{total_lines:,} 行代码。")
+    print(f"{'=' * 70}")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="代码仓库结构扫描与统计工具")
+    parser.add_argument("repo_path", help="要扫描的仓库/目录路径")
+    parser.add_argument("--depth", type=int, default=2, help="目录树深度 (默认 2)")
+    parser.add_argument("--top", type=int, default=20, help="代码热点 Top N (默认 20)")
+    args = parser.parse_args()
+
+    repo_path = Path(args.repo_path).resolve()
+    if not repo_path.is_dir():
+        print(f"错误: {repo_path} 不是有效目录", file=sys.stderr)
+        sys.exit(1)
+
+    all_files, lang_stats, lang_lines, key_files, dir_tree = scan_repository(
+        repo_path, depth=args.depth, top_n=args.top
+    )
+    print_report(repo_path, all_files, lang_stats, lang_lines, key_files, dir_tree, args.top)
+
+
+if __name__ == "__main__":
+    main()