Imported from jianliu3216-ops/devpilot (skills/jit-project-knowledge-base/SKILL.md). Install upstream with npx skills add jianliu3216-ops/devpilot --skill jit-project-knowledge-base. Copyright stays with the author.

项目知识库构建（Project Knowledge Base Builder）

用于将“历史项目”快速沉淀为结构化文档 PROJECT_KNOWLEDGE_BASE.md，便于后续复用、评审与上手。

前期准备

执行本 Skill 前，AI MUST 主动读取以下同级文件（由 AI 使用读取工具完成，不要求用户手动打开）：

1. reference.md → 字段标准，决定模块字典、工具索引、技术栈、图资产等表格字段
2. examples.md → 输出结构示例，决定 BASE / DETAIL 的呈现形态
3. HISTORY_PROJECT_ANALYSIS_GUIDE.md → 历史项目分析方法，补充宏观认知、模块梳理、资产提取、质量关键点

辅助文件优先级：

• SKILL.md 是唯一运行时主流程；若与辅助文件冲突，以 SKILL.md 为准
• reference.md 的字段定义优先级高于示例文本
• HISTORY_PROJECT_ANALYSIS_GUIDE.md 只提供分析方法与质量检查，不得覆盖 Phase 0.0–0.2 的 preflight / 用户确认 / CodeGraph 规则
• USAGE.md 是给用户和团队看的使用说明，不是运行时必读文件；只有当用户询问“如何使用/如何触发/安装位置/对话模板”时才需要读取

严格遵循 reference.md 的字段定义输出。

前置条件（必做）

开始前请先向用户确认/获取：

1. 项目根目录绝对路径（拿到路径后 MUST 立即执行 Phase 0.0 轻量自检，再读源码内容）
2. 允许读取的范围/是否可全量检索
3. 输出语言（默认中文）
4. 输出文件路径（默认：项目根目录 docs/knowledge-base/PROJECT_KNOWLEDGE_BASE.md + docs/knowledge-base/PROJECT_KNOWLEDGE_DETAIL.md，允许用户指定其他 docs/knowledge-base/ 下路径）
5. 期望深度（三选一，默认：标准完整）：
   • 快速骨架 → 仅 BASE 精简版，不含 DETAIL，适合超大项目快速入门
   • 标准完整 → 双文件结构（推荐默认）：
     • BASE：精简入门版（概览+模块精简+TOP 10 工具+PUML 索引+技术栈+架构+建议）
     • DETAIL：深度备查版（全量模块+全量工具+协议格式+配置分析+所有深度内容）
   • 尽量详尽 → 双文件结构 + 额外的深度分析章节（算法/模型/数据层/安全机制等）
6. 可选：项目领域背景（例如 AIOPS）
7. 可选：你最关心的方向（架构/复用/接口/数据/安全）

任一关键信息缺失 → 先提问再执行。

标准流程（固定顺序，Mandatory Order）

Phase 0.0 - 生成前轻量自检（MUST，第一步）

在读取任何源码内容、执行大范围 grep、或全量分析之前，AI 必须通过工具自动运行 preflight，并向用户展示结果。Phase 0.0 只允许做轻量元数据扫描：统计文件数、项目体积、构建文件数量、.codegraph/ 是否存在、CodeGraph CLI 状态；不得读取源码正文。

执行要求：

• 这是 AI 的内部工具步骤，不是让用户手动复制命令执行
• 在 Cursor/Claude Code 中，AI MUST 使用 Shell/PowerShell 工具执行下列命令
• 若命令失败，AI MUST 把失败原因展示给用户，并按 Phase 0.1 的降级/修复分支处理

# Git Bash / macOS / Linux
bash "$FRAMEWORK/skills/jit-project-knowledge-base/scripts/preflight-kb.sh" "<目标项目绝对路径>"

# Windows PowerShell
powershell -ExecutionPolicy Bypass -File "$FRAMEWORK/skills/jit-project-knowledge-base/scripts/preflight-kb.ps1" "<目标项目绝对路径>"

$FRAMEWORK 来自 ~/.claude/devpilot-framework-path。

默认 preflight 只检测，不执行 codegraph build。

preflight 输出字段（MUST 向用户说明）：

Phase 0.1 - 大项目判定与用户确认（MUST）

根据 Phase 0.0 输出决定后续路径：

大项目询问格式：

检测到项目较大：
- 源码文件数：{SOURCE_FILE_COUNT}
- 项目体积：{PROJECT_SIZE_MB} MB
- CodeGraph 状态：{CODEGRAPH_STATUS}
- 缓存状态：{CODEGRAPH_CACHE_STATUS}

建议使用 CodeGraph 生成依赖图后再构建知识库，可降低上下文压力和漏扫风险。
请选择：
1. 使用 CodeGraph（推荐，确认后执行 preflight-kb --build）
2. 不使用，直接降级扫描（耗时较长，可能不完整）
3. 暂停，先安装/修复 CodeGraph

硬规则：

• 大项目在用户确认前，禁止执行 codegraph build
• 大项目在用户确认前，禁止全量读取源码或大范围 grep
• 小项目也必须展示文件数量和 CodeGraph 状态，但不需要强制询问
• 用户选择直接扫描时，必须在知识库 BASE 的「CodeGraph 状态」小节记录降级原因

Phase 0.2 - CodeGraph build 或降级策略（按用户确认执行）

用户确认使用 CodeGraph 后执行：

bash "$FRAMEWORK/skills/jit-project-knowledge-base/scripts/preflight-kb.sh" "<目标项目绝对路径>" --build
# 或 Windows PowerShell
powershell -ExecutionPolicy Bypass -File "$FRAMEWORK/skills/jit-project-knowledge-base/scripts/preflight-kb.ps1" "<目标项目绝对路径>" -Build

--build vs --rebuild 区别：

硬规则：

• 检测标准以 codegraph build 成功 为准（不是仅 codegraph --version）
• BUILD_FAILED 必须按 build 失败处理，不能误写成 CLI_ONLY
• 知识库 BASE 文档 MUST 包含「CodeGraph 状态」小节（状态 + 用户选择 + 降级原因，若有）

Phase 0.3 - 范围、边界与项目特征标签

• 评估项目规模与预期深度（基于 Phase 0.0 输出，不再重复全量扫描）
• 大项目判定（MUST）：若满足任一条件，默认进入“大项目模式”：自有源码文件数 > 500、仓库体积 > 100MB、多模块/monorepo、或用户选择“标准完整/尽量详尽”
• 大项目模式下 CodeGraph 优先：用户选择使用 CodeGraph 且 preflight 为 BUILD_OK/CACHED_OK 时，Phase 1–2 必须以 .codegraph/ 为优先输入；否则必须记录降级策略
• 自动检测构建系统：
  • 找到 pom.xml → Maven 项目 (Java/Kotlin)
  • 找到 build.gradle / build.gradle.kts → Gradle 项目 (Java/Kotlin)
  • 找到 package.json → Node.js 项目 (JavaScript/TypeScript)
  • 找到 go.mod → Go 项目
  • 找到 CMakeLists.txt → C/C++ 项目 (CMake)
  • 找到 Cargo.toml → Rust 项目
  • 找到 *.rockspec → Lua 项目 (LuaRocks)
  • 多个构建文件 → 向用户确认主构建文件
• 判断架构风格（单体 / 多模块 / monorepo / 微服务聚合）
• 记录假设与限制（未能构建、证据缺失、权限不足、部分目录无法扫描等）

项目特征标签（轻量检测 + 用户多选组合）

核心思路：不把项目硬塞进一个类别，而是用多维度标签组合描述项目特征，不同标签组合决定后续分析侧重。 本阶段允许轻量扫描文件名、目录名、构建文件和少量入口文件关键字；仍禁止全量读取所有源码。全量源码读取只允许在 Phase 1.1 发生。

Step 1 — 自动检测，生成推荐标签

扫描项目文件结构，按以下规则自动匹配推荐标签（可命中多个，用 ✅ 标记）：

Step 2 — 向用户展示并确认标签组合

将自动检测到的推荐标签 ✅ 与全部可选标签一起展示，格式如下：

📌 项目特征标签（可多选组合）

自动检测推荐（✅ = 已检测到）：
  ✅ 🌐 OpenResty网关    ✅ 🔌 自定义协议    ✅ 🔐 加密/国密
  ✅ ⚙️ 硬件交互/FFI     ✅ 🔄 OTA/热更新     ✅ 🛡️ 进程守护

可选补充（根据你的了解勾选）：
  ☐ ☕ Spring后端      ☐ 🐍 Python后端      ☐ 🖥️ 前端SPA
  ☐ 🐳 容器化部署      ☐ ☸️ K8s编排         ☐ 📡 gRPC/Protobuf
  ☐ 📨 消息队列驱动    ☐ 🗄️ 数据库密集      ☐ 🛡️ 认证授权
  ☐ ⏰ 定时任务        ☐ 📊 已有文档资产     ☐ 🚀 CI/CD流水线
  ☐ 🧪 已有测试体系    ☐ 🔲 嵌入式/边缘      ☐ 🤖 AI/ML
  ☐ 📡 IoT/设备接入    ☐ 🏛️ 微服务架构       ☐ 📦 Monorepo
  ☐ 🔧 前端构建工具链  ☐ 📋 审计合规         ☐ 💾 缓存层
  ☐ 🌐 API网关/代理    ☐ 🔨 交叉编译         ☐ 📖 API文档生成
  ☐ 🐹 Go后端

请确认或调整标签组合（可增删）：

Step 3 — 根据标签组合决定分析侧重

不同标签组合会在标准流程基础上激活额外的分析章节或深度要求：

标签组合示例：

• 🌐 OpenResty网关 + 🔌 自定义协议 + 🔐 加密/国密 + ⚙️ 硬件交互/FFI → 典型安全网关场景，侧重协议解析、加密流程、硬件加速
• ☕ Spring后端 + 🗄️ 数据库密集 + 🛡️ 认证授权 + 🐳 容器化部署 → 典型企业后端，侧重数据模型、安全链路、部署配置
• 🖥️ 前端SPA + 🔧 前端构建工具链 + 📦 Monorepo → 前端工程化项目，侧重组件复用、构建优化、包管理
• 🐍 Python后端 + 🤖 AI/ML + 📨 消息队列驱动 → AI 数据平台，侧重模型Pipeline、数据流、调度

Step 4 — 记录标签组合到分析边界说明

最终确认的标签组合写入 Phase 0 产出，作为后续所有 Phase 的分析导向依据。

产出：分析边界说明（boundary notes）+ 项目特征标签组合

Phase 1 - 宏观探索

1. 扫描根目录，识别顶级模块/目录分层
2. 递归扫描每个子目录（排除 .git、node_modules、vendor、第三方源码的 bundle 等），获取完整的目录树（至少 3 层深度），不能只看顶层目录名就跳过
3. 如果存在 README.md → 自动读取并提取项目简介整合到概览
4. 如果存在 git 信息 → 自动提取远程仓库地址和最近变更趋势
5. 读取主构建文件提取项目信息
6. 判断架构风格（单体 / 多模块 / 分层）
7. 归纳项目类型/领域定位

产出：项目概览、模块统计、架构结论

Phase 1.1 - 深度内容探查（强制必做，全量读取）

核心原则：不能只看目录名就推断功能，必须逐个读取每个源文件内容才能给出准确分析。 强约束：不允许只读"关键文件"然后"推断"其余文件，必须全量读取所有自定义源码文件。

对 Phase 1 识别出的每个项目自有模块（非第三方依赖），必须执行：

1. 递归列出目录下所有源码文件（按语言后缀过滤：*.lua, *.c, *.h, *.cs, *.java, *.py, *.go, *.js, *.ts, *.sh 等）
2. 逐个读取所有自定义源文件（全量，不可只读"关键"文件再推断其余）：
   • 入口文件（main.*、app.*、index.*、*_init.lua、nginx.conf 等）
   • 配置文件（*.conf、*.properties、*.yml、*.yaml、*.json 等）
   • 全部业务文件（不仅是 handler/controller/service/router，所有自定义 *.lua、*.py、*.go、*.java 等都必须读取）
   • 头文件/接口定义（*.h、interface.*、*.proto 等）
   • 工具/辅助文件（*utils*、*helper*、*store*、*config* 等）
   • 测试文件（*test*、*spec* 等）
3. 对于 C/C++ 项目：读取 Makefile、CMakeLists.txt、所有头文件（.h）、所有源文件（.c/.cpp）
4. 对于 C# 项目：读取 .csproj、.sln 和所有 .cs 文件
5. 对于 Lua/OpenResty 项目：读取 nginx.conf、所有 *.lua 文件（包括子目录中的）
6. 对每个文件输出：
   • 文件路径
   • 功能摘要（1-3 句话，基于实际读取的代码内容，包含核心函数/方法名和职责）
   • 导出的函数/方法/类列表
   • 依赖的其他模块（基于 require/import/include 语句）
7. 全量读取的验证标准：
   • 自定义源文件读取率必须 100%（不可抽样、不可跳过）
   • 每个文件必须有基于实际内容的摘要，不允许出现"基于文件名推断"的描述
   • 如果因文件过大无法全量读取，必须至少读取核心函数定义和模块导出部分

产出：每个模块的完整源文件清单 + 每个文件的功能摘要 + 模块间调用关系

Phase 2 - 模块业务字典（必做）

把模块分成：

• 聚合入口
• 业务模块
• 基础/通用模块
• 构建/部署模块

重要：每个模块的分析必须基于 Phase 1.1 中实际读取的源文件内容，不能只凭目录名推断。

每个模块提炼：

• 业务含义（一句话，基于实际代码内容描述）
• 核心功能（2-5 点，基于实际读取的函数/类/方法）
• 关键源文件列表（列出模块内的核心文件路径）
• 依赖关系（上游/下游，基于 require/import/include 语句）
• 优先级（高/中/低）

产出：模块业务字典表（必须表格化），且每个模块必须附带关键源文件清单

Phase 3 - 可复用资产提取（Util/Helper，严格要求）

1. 全局检索所有工具类/工具函数，按语言约定：

   语言	检索模式
   Java/Kotlin	*Util*, *Helper*, *Utils
   Go	*util* 包, *helper* 包
   JavaScript/TypeScript	*/utils/*.ts, */helpers/*.ts, *Utils.ts
   Python	utils.py, helpers.py, *_utils.py
   C#	*Helper, *Utility
   C/C++	*utils.h, *helper.h

| Lua | *utils*.lua, *util*.lua, *helper*.lua |

2. 按功能分类（安全/文件/网络/日志/日期/转换/校验/通用等）
3. 评估复用价值与风险
4. 必须递归搜索所有子目录，不能只搜索顶层目录。对于每个找到的工具文件，必须读取其内容，提取：
   • 导出的函数/方法名列表
   • 每个函数的简要功能说明
   • 函数参数和返回值（如果可辨识）

输出强约束：

• Util/Helper 全量索引（不可抽样截断）
• 分类汇总统计（每类数量）
• 每个工具标注复用等级（High/Medium/Low 或同义）
• “高复用 TOP 10”仅作为入口（可选）

Phase 4 - 图文资产整合与 PUML 流程图生成（强制强制执行）

⚠️ 重要提醒：团队成员必须严格遵守本节。偷工减料只生成 1 个图的行为是不允许的！

Step 1 — 检索现有图文资产

检索现有图文资产：

• *.puml, *.plantuml, *.png, *.jpg, *.svg

若存在现成流程图：

• 建立索引（文件路径 + 内容摘要）
• 给出文字流程解释（触发/主链路/异常/输出）

Step 2 — 基于代码分析生成 PUML 流程图（必须独立文件输出）

🚫 错误行为禁止清单（违者返工）： ❌ 不能只在 markdown 中嵌入 plantuml 代码块，不生成独立 .puml 文件 ❌ 不能只生成一个 "综合大图" 包含所有内容 ❌ 不能生成项目中不存在的流程（如没有加密卡就不能画硬件图） ❌ 不能省略源文件路径标注 ❌ 不能随便命名（必须用规范文件名，如 main_flow.puml）

✅ 正确行为：每个有意义的业务流程单独生成一个 .puml 文件，不嵌入 MD，不合并为一个大图。

根据 Phase 1.1 实际读取的代码 + Phase 2 模块依赖关系，识别项目中的所有独立业务流程，每个流程生成一个独立的 PUML 文件。

必须生成的流程图类型（按项目特征标签激活，P0=必选）：

生成规则（强制执行）：

1. 每个 PUML 文件必须独立完整：有自己的 @startuml / @enduml，可单独渲染
2. 只生成有代码证据的流程图：没有对应标签的流程图不生成，不臆造
3. 项目有多个独立流程就生成多个文件：不允许把所有流程塞进一个图
4. 命名规范：{流程类型}.puml，存放在 docs/knowledge-base/ 目录（不存在则创建）
5. 所有 PUML 使用 PlantUML 语法，兼容在线渲染（如 plantuml.com/plantuml）
6. 图中必须标注源码文件路径：每个处理节点旁标注实现它的源文件名（如 packet_handler.lua），方便定位
7. 每个文件头部必须包含元数据：项目名、图类型、生成时间、激活标签
8. [强制] PUML 语言规则：所有 PUML 图的标签、标题、注释、节点描述必须使用中文。代码文件名和类名保持原文。skinparam 元数据注释可使用英文。title 必须为中文。此规则优先级高于模板示例

⚠️ 【强制】PlantUML 语法兼容性规范（必须遵守！）

🚫 不遵守此规则生成的图会导致渲染失败！ 已在多个项目中发现以下语法导致 PUML 打不开。

核心原则：只使用最基础、兼容性最高的 1990 年代 PlantUML 语法，绝对不追新特性。

一、皮肤配置语法（绝对禁止特定类型 skinparam）

【唯一正确】标准皮肤配置（所有图完全相同，禁止任何自定义！）：

skinparam backgroundColor #FEFEFE
skinparam BackgroundColor #E8F4FD
skinparam BorderColor #2196F3
skinparam NoteBackgroundColor #FFF9C4
skinparam NoteBorderColor #FBC02D
skinparam ArrowColor #555555

二、绝对禁止使用的语法黑名单（发现即返工）

三、特殊字符黑名单（发现即返工）

以下字符绝对不能出现在 PUML 文件任何位置：

四、不同类型图的安全语法子集

五、快速检查清单（生成后逐项核对，不通过不能交付）

• 没有 skinparam xxx { ... } 块语法
• skinparam 只有标准 6 行，不包含任何特定元素类型的配置
• 没有 box ... end box 语法
• participant/component/state 名称内没有 \n 换行符
• 没有 hexagon/fork/split/group/partition 等高级语法
• 没有 -[hidden]-> 等箭头修饰符
• State 图内没有 :xxx; Activity 语法
• 文件中没有任何 emoji 或制表符
• 每个文件都有完整的 @startuml / @enduml 包裹
• 所有中文都是纯文本，不含特殊格式

六、每个 PUML 文件的标准模板（直接套用，禁止增删 skinparam）

@startuml
' 项目：[项目名，纯英文，不含特殊字符]
' 流程图类型：[主业务流程/模块依赖/...]
' 生成时间：YYYY-MM-DD
' 激活标签：[对应标签，纯文本，不含emoji]
'
' 变更记录（倒序，纯文本）：
' vX.X - YYYY-MM-DD - [修改内容描述]

' 重要：只使用最通用的 plantuml 语法，确保所有版本兼容
skinparam backgroundColor #FEFEFE
skinparam BackgroundColor #E8F4FD
skinparam BorderColor #2196F3
skinparam NoteBackgroundColor #FFF9C4
skinparam NoteBorderColor #FBC02D
skinparam ArrowColor #555555

title [图标题，必须使用中文，不含特殊字符]

' [图内容 - 所有标签、节点描述、注释必须使用中文]
' State 图和 Activity 图语法绝对不能混用！
' - Activity 图安全子集：start / :xxx; / if/then/else / stop
' - State 图安全子集：[*] --> state / state "xxx" as s1 / note

@enduml

输出目录结构示例：

docs/knowledge-base/
├── main_flow.puml              # 主业务流程
├── module_dependency.puml       # 模块依赖关系
├── protocol_flow.puml           # 协议报文处理（自定义协议）
├── security_flow.puml           # 加密安全流程（加密/国密）
├── hardware_flow.puml           # 硬件交互流程（硬件交互/FFI）
├── ota_flow.puml                # OTA升级流程（OTA/热更新）
└── ... 其他激活标签对应的图

Step 3 — 在知识库 MD 中建立 PUML 索引

在 PROJECT_KNOWLEDGE_BASE.md 中新增独立章节 "PUML 流程图索引"：

1. PUML 文件索引表：文件名、流程类型、激活标签、简述（表格形式）
2. 每个流程图附加文字说明：触发条件、主链路、关键分支、异常路径、输出结果
3. 渲染方式说明：告诉用户如何渲染这些 .puml 文件（在线渲染、VS Code 插件、本地 Java 命令）
4. 文字说明与 PUML 图一一对应，不能只有图没有文字，也不能只有文字没有图

Phase 4.1 - 脚本与配置资产分析（混合语言项目）

对于包含多种类型资产的项目（Java + 脚本 + 配置），增加此阶段分析：

检索并整理以下类型文件（必须递归搜索所有子目录，包括嵌套子目录）：

• 脚本文件：*.py, *.sh, *.bat, *.lua - 整理功能说明、执行位置、依赖环境
• 配置文件：*.properties, *.json, *.yml, *.yaml, *.conf, *.ini - 分类整理关键配置作用
• 部署资产：Dockerfile, docker-compose.yml, k8s/*.yaml, k8s/*.yml - Kubernetes/Docker 部署配置说明
• 打包压缩资产：*.tar, *.zip, *.gz - 说明是什么资产的打包（探针包、依赖包等）

产出要求：

• 按文件类型分表格索引
• 每个文件标注路径、功能、执行上下文
• 必须读取脚本/配置文件内容，基于实际内容描述功能，不能只凭文件名推测
• 关键脚本说明输入输出依赖

深度模式额外要求：阅读脚本内容提取核心逻辑，总结脚本功能。

Phase 4.1.1 - 配置交叉引用解析（强制必做！历史教训：多次遗漏关键配置）

⚠️ 本节是硬性强制要求，不是建议！ 历史上多次发生：扫描到配置文件并列入清单，但未实际读取内容，导致关键信息（如服务注册表、API地址列表等）被遗漏。

核心原则：配置文件之间经常相互引用，只读入口配置不追引用链 = 只看目录不进房间。

Step 1 - 识别配置文件间的引用关系

读取每个配置文件时，识别以下引用模式：

Step 2 - 递归读取所有被引用文件（强制！）

对于 Step 1 发现的每个引用，必须执行以下操作：

1. 解析引用路径：将相对路径转为绝对路径（相对于当前配置文件所在目录或项目根目录）
2. 实际读取被引用文件：用 Read 工具读取文件内容，不能只记录"该文件被引用"
3. 提取被引用文件的核心数据：如 JSON 中的服务列表、YAML 中的路由表、Properties 中的连接参数等
4. 将核心数据写入知识库：不能只在表格中写一行"Cube服务注册配置"，必须展开核心内容
5. 继续检查被引用文件是否又引用了其他文件：递归直到引用链终止

Step 3 - 配置读取验证清单（每个配置文件必须通过）

对 Phase 4.1 中扫描到的每个配置文件，逐一检查：

配置文件读取验证表：
| 文件路径 | 是否已读取内容 | 核心数据是否已提取到知识库 | 引用了哪些文件 | 被引用文件是否已读取 |
|---------|:---:|:---:|---|:---:|
| platform.properties | ✅ | ✅ | cube-service.json, jdbc.properties | ? |
| cube-service.json   | ?   | ?   | - | - |
| ... |

任何一行"被引用文件是否已读取"为 ❌ 的，必须返回读取，不能跳过！

典型遗漏场景（反面教材）：

• ❌ platform.properties 中写了 cube.lookupservice.path=file:config/cube-service.json，但只记录了"Cube服务注册配置"一句话，未读取 JSON 内容提取 70+ 个服务注册条目
• ❌ application.properties 中写了 spring.config.name=application,additional，但未读取 additional.properties
• ❌ redis.properties 中写了集群节点列表，但未展开说明各节点角色
• ✅ 正确做法：读到引用 → 追过去读 → 提取核心数据 → 写入知识库 → 检查是否还有嵌套引用

Phase 5 - 技术栈与架构说明

• 从代码/配置/构建文件提取：语言、框架、中间件、数据库、缓存、MQ
• 版本号只能用“可追溯证据”来源（build file/config）
• 说明层级边界与调用路径（谁调用谁、在哪里落地）

Phase 6 - 问题发现与重构建议（只写有证据的）

每条建议至少包含：

• 证据位置（path/symbol 引用）
• 风险说明（影响、可维护性、性能、安全等）
• 建议动作（怎么改）
• 预期收益（为什么值得改）

Phase 7 - 深度分析（仅尽量详尽模式需要）

根据期望深度，在"尽量详尽"模式下增加以下分析：

7.1 入口点分析

• 找到项目启动入口（main 方法 / SpringBootApplication / 根路由文件等）
• 梳理启动加载流程
• 标注关键配置项位置

7.2 API 接口分析（针对 Web 项目）

• 提取所有 Controller / 路由处理器
• 列出所有接口路径、HTTP 方法、功能简述
• 整理成接口清单表格

7.3 配置文件分析

• 找到主配置文件（application.yml/application.properties/config.* 等）
• 提取关键配置项（数据库连接、端口、密钥、第三方API地址等）
• 说明各配置项作用

7.4 数据层分析（如果有数据库）

• 识别实体模型 / DO / Entity
• 提取核心表结构关系
• 梳理 DAO / Repository 层职责

7.5 定时任务分析

• 找出所有定时任务
• 列出 cron 表达式、任务功能

7.6 安全机制分析

• 识别认证/授权入口
• 梳理安全过滤链路
• 说明权限控制方式

7.7 算法分析（针对算法/机器学习项目）

• 识别核心算法模块与模型文件
• 提取算法类型（分类/回归/聚类/强化学习等）
• 梳理特征工程流程与特征选择逻辑
• 整理模型结构、超参数配置与训练方式
• 标注推理接口输入输出格式
• 说明模型评估指标与性能结果

Phase 8 - 知识库结构校验（生成后 MUST）

知识库文档写入完成后执行：

node "$FRAMEWORK/skills/jit-project-knowledge-base/scripts/validate-kb.js" "<目标项目绝对路径>"
# 大项目且用户选择 CodeGraph 或 preflight 曾为 BUILD_OK/CACHED_OK 时，建议加 --strict
node "$FRAMEWORK/skills/jit-project-knowledge-base/scripts/validate-kb.js" "<目标项目绝对路径>" --strict

校验结果必须写入交付说明。若存在 Error，知识库不算完成；--strict 下大项目缺少 .codegraph/ 视为 Error（除非用户明确选择降级扫描，且 BASE 中已记录降级原因）。

结构校验通过后 MUST 再跑事实门控，刷新准入清单（可无 --query）：

node "$FRAMEWORK/skills/jit-project-knowledge-fact-gate/scripts/verify-kb-facts.js" "<目标项目绝对路径>"

fail 断言写入交付说明即可，不阻断知识库生成完成；但后续任务引用知识库事实时只能用 pass。

最终交付（Final Deliverable）

📦 标准交付 = 分层文件结构 + 多个独立 PUML 文件

分层原则：基于信息维度，而非行数硬约束

• 第一层：PROJECT_KNOWLEDGE_BASE.md = 核心索引层（10 分钟快速上手）
• 第二层：PROJECT_KNOWLEDGE_DETAIL.md = 深度备查层（开发参考手册）
• 第三层：PROJECT_KNOWLEDGE_DETAIL-{模块域}.md = 超大项目分卷（>50 模块时自动拆分）
• PUML 文件：多个独立流程图文件，每个流程一个文件

第一层：PROJECT_KNOWLEDGE_BASE.md（核心索引层）

定位：新人上手、架构评审、快速了解项目全貌
设计目标：10 分钟能看完，回答 3 个核心问题：

1. 「这项目是做什么的？」
2. 「核心架构和依赖是什么？」
3. 「我要改 X 功能应该去哪个文件？」

强制包含内容（内容驱动，而非行数驱动）：

1. 目录导航（TOC）
2. 项目整体概览：项目定位、核心能力（≤5 点）、架构风格
3. PUML 流程图索引：独立章节，列出所有 .puml 文件表格 + 渲染方式说明
4. 模块业务字典（精简版）：只列 Top 20% 核心模块，每模块一句话 + 关键文件路径 + 被引用次数
5. 高复用工具 TOP 10：只列最常用的 10 个，每个一句话说明适用场景
6. 技术栈全景表：语言/框架/中间件/版本，一张表列完
7. 关键架构决策（≤5 点）：最核心的设计选择与取舍
8. 重构建议 TOP 5：最值得优先改进的 5 个问题
9. 分析边界与假设：什么没覆盖、依赖的前提条件
10. 底部加跳转链接：「📚 深度分析请查阅 PROJECT_KNOWLEDGE_DETAIL.md」
11. （超大项目）分卷索引表：列出所有 DETAIL 分卷的文件名和内容范围

第二层：PROJECT_KNOWLEDGE_DETAIL.md（深度备查层）

定位：开发手册、深度排查、代码复用参考
设计目标：所有开发需要的细节都能在这里查到，不需要去翻源码

强制包含内容（内容驱动，而非行数驱动）：

1. 目录导航（TOC）
2. 开头加跳转链接：「📖 快速入门请查阅 PROJECT_KNOWLEDGE_BASE.md」
3. 协议报文格式（如有 🔌 自定义协议标签）：magic 校验、type_val 路由表、编解码逻辑、错误码
4. 模块间完整调用关系图（ASCII 或 Mermaid）
5. 模块业务字典（完整版）：所有模块的所有导出函数 + 完整依赖链 + 输入输出说明
6. 可复用工具全量索引：所有 Util/Helper，分类统计、每个函数参数/返回值/功能说明
7. 脚本与配置资产全索引：所有脚本/配置文件的路径、功能、参数、执行上下文
8. 核心技术/算法详解（如有 🔐 加密/国密 / 🤖 AI/ML 标签）
9. 硬件/FFI 接口分析（如有 ⚙️ 硬件交互/FFI 标签）：所有接口的参数、返回值、错误处理
10. 启动入口分析：完整启动流程、关键配置位置、初始化顺序
11. API 接口清单（Web 项目）：所有接口的路径、方法、参数、返回值、权限要求
12. 关键配置项说明：所有配置项的默认值、作用、合法值范围
13. 安全机制与密钥层次（如有 🔐 加密/国密 / 🛡️ 认证授权标签）
14. 错误码体系：所有错误码的含义、触发场景、排查建议
15. 状态机详解（如有 🔄 OTA/热更新 / ⏰ 定时任务标签）
16. 进程守护机制（如有 🛡️ 进程守护标签）
17. 打包发布流程
18. 需求索引：首次生成时也必须创建空表，后续任务 8.5 追加/更新
19. 函数与接口变更索引：首次生成时创建空表，后续按需求增量维护
20. 更新记录：首次生成写入 v1.0 全量创建记录

初始化模板：

## 需求索引

| 需求标识 | 中文名 | 级别 | 涉及模块 | 完成版本 | 状态 | 备注 |
|---------|-------|:--:|---------|:--:|------|------|

## 函数与接口变更索引

| 模块 | 符号/接口 | 文件路径 | 变更类型 | 摘要 | 调用方/消费者 | 风险 | 需求标识 | 版本 |
|------|----------|----------|----------|------|---------------|------|----------|------|

## 更新记录

| 版本 | 日期 | 需求标识 | 变更范围 | 说明 | 更新文件 |
|------|------|----------|----------|------|----------|
| v1.0 | YYYY-MM-DD | initial | 全量创建 | 初始知识库 | BASE, DETAIL |

第三层：超大项目分卷（>50 模块时自动触发）

触发条件：

• 模块数 > 50
• 或预估 DETAIL.md > 2000 行

分卷规则：

1. 始终保留一个 BASE：核心索引层永远是单文件
2. 公共部分放主 DETAIL：协议格式、工具全量索引、配置分析、启动流程等公共内容
3. 每个业务域一个 DETAIL 分卷：按领域拆分，如：
   • PROJECT_KNOWLEDGE_DETAIL-通信模块域.md
   • PROJECT_KNOWLEDGE_DETAIL-加密模块域.md
   • PROJECT_KNOWLEDGE_DETAIL-升级模块域.md
4. 每个分卷控制在 1000 行以内
5. BASE 中增加「分卷索引表」：列出所有 DETAIL 分卷的文件名和内容范围
6. 每个分卷开头都加跳转链接：「📖 返回索引请查阅 PROJECT_KNOWLEDGE_BASE.md」

PUML 流程图文件（必须单独交付）

必须同时交付以下独立文件，存放在 docs/knowledge-base/ 目录：

• P0 必选 2 个：main_flow.puml、module_dependency.puml
• P1 根据标签激活 N 个：例如有加密标签则交付 security_flow.puml，有协议标签则交付 protocol_flow.puml 等

所有 PUML 文件必须：

• 有完整的 @startuml / @enduml，可独立渲染
• 头部有元数据注释（项目名、图类型、生成时间、激活标签）
• 关键节点标注对应的源码文件路径
• 使用统一的 skinparam 样式模板

质量门槛（Quality Checklist）

⚠️ 执行完成后必须逐条自查，未通过检查的知识库需要返工 ⚠️ 任何一项不通过都不算完成！

一、分层结构检查（所有深度模式必须通过）

• PROJECT_KNOWLEDGE_BASE.md 存在，内容是核心索引层
• PROJECT_KNOWLEDGE_DETAIL.md 存在，内容是深度备查层
• BASE 只放了 TOP 10 工具，不是全量索引（核心索引层不堆细节）
• DETAIL 放了全量工具索引，不是只放 TOP 10
• BASE 只放了模块精简字典（Top 20% 核心模块，一句话说明）
• DETAIL 放了模块完整版字典，含所有模块的所有导出函数
• BASE 底部有跳转链接：「📚 深度分析请查阅 PROJECT_KNOWLEDGE_DETAIL.md」
• DETAIL 顶部有反向链接：「📖 快速入门请查阅 PROJECT_KNOWLEDGE_BASE.md」
• （超大项目）按业务域拆分了 DETAIL 分卷，BASE 中有分卷索引表

二、基础内容检查（所有深度都需要满足）

• 构建文件已解析并给出技术栈版本证据
• Phase 1.1 深度内容探查已执行（每个自有模块都读取了内部源文件，不能只看目录名）
• BASE 中有模块精简字典（每个模块附带关键源文件清单）
• DETAIL 中有全量 Util/Helper 索引（递归搜索所有子目录）
• DETAIL 中有脚本与配置资产全索引（基于实际文件内容描述）
• DETAIL 中已初始化 ## 需求索引
• DETAIL 中已初始化 ## 函数与接口变更索引
• DETAIL 中已初始化 ## 更新记录，且包含 v1.0 全量创建记录
• Phase 4.1.1 配置交叉引用解析已执行（每个被引用的配置文件都已实际读取，核心数据已提取到知识库，不能只在表格中写一句描述）
• 配置读取验证表已填写并全部通过（所有"被引用文件是否已读取"列都是 ✅）
• BASE 中有重构建议（有证据、可落地）
• BASE 中有分析边界与假设说明

三、PUML 流程图专项检查（所有项目必须通过，不通过即返工）

🚨 这是最高优先级的检查项！ 历史数据显示：超过 60% 的交付投诉来自 PUML 渲染失败。

建议：生成完所有 PUML 后，先复制到 plantuml.com/plantuml 在线试渲染一遍，确认无误再交付。

快速自检命令（可选）：

# 检查是否有 block 语法
grep -l "skinparam.*{" *.puml
# 检查是否有特殊字符
grep -P "[\x{1F300}-\x{1F9FF}]" *.puml
# 检查是否有 box 语法
grep -l "^box" *.puml

四、深度分析检查（所有深度都需要满足）

• DETAIL 中有启动入口分析
• DETAIL 中有完整的调用关系图
• DETAIL 中有 API 接口清单（Web 项目）
• DETAIL 中有所有关键配置项说明
• DETAIL 中有安全机制说明（如有相关标签）
• DETAIL 中有错误码体系说明
• DETAIL 中有状态机详解（如有相关标签）

输出风格（Output Style）

• 只用 Markdown
• 索引类章节优先用表格
• 结论先行，证据后置
• 不堆大段原始代码（避免噪音）

失败与降级策略（Failure Handling）

正常流程（默认）

• 所有项目（标准完整/尽量详尽）都默认采用分层文件结构，不是只有内容过多才拆分
• BASE + DETAIL 双文件是标配，不是可选

项目规模分级处理

特殊情况处理

• 权限不足无法读取部分目录：在 BASE 的"分析边界"章节明确标出"无法扫描 X 目录，结果可能不完整"，继续处理可访问部分
• 缺少构建文件/证据：标注"缺证据项"而不是猜测版本号
• 未找到任何工具类：DETAIL 中明确写"未发现独立工具类"，留空表格不如明确说明
• 无流程图资产：自动生成至少 2 个基础流程图（main_flow + module_dependency），不省略章节
• PUML 渲染报错：立即检查语法（是否漏了 @enduml、是否有语法错误），修复后重新生成
• 用户中断：已生成的内容保留，下次继续从断点生成剩余部分