加了个 SKILL 诊断自己的工程: analyze-project

./agent/skills 里加了一个 Agent Skill analyze-project ，可以对 Voocii-Portal 项目（以及类似的全栈 TypeScript/Next.js/tRPC 现代化工程）进行系统性的代码审查与架构健康诊断。

对工程里的 前端、后端、数据库、测试体系以及整体 Monorepo 代码架构 做全方位自动化诊断，然后输出细分领域的深度评估报告，并最终合成一份高层级决策与演进规划总报告。可以作为后续重构、性能优化和技术演进的依据。

1. 核心设计与执行原则

SKILL的设计兼顾了 “全量代码注入导致的 Context Window 爆炸” 和 “泛泛而谈缺乏代码事实” 的问题，analyze-project 采用了以下核心原则：

graph TD
    A[Phase 1: 发现与规范预聚合] -->|Node.js 快速拓扑扫描| B[Phase 2: 领域分层审查]
    B -->|按需加载 Checklist 规则| C1[2.1 code-structure.md]
    B -->|独立上下文沙箱持久化| C2[2.2 frontend-structure.md]
    B -->|分阶段即时写入外部记忆| C3[2.3 backend-structure.md]
    B -->|检查真实模型与迁移| C4[2.4 database-structure.md]
    B -->|执行真实 Vitest 测试套件| C5[2.5 test-analysis.md]
    C1 & C2 & C3 & C4 & C5 --> D[Phase 3: 决策层两阶段综合合成]
    D --> E[PROJECT_ANALYSIS_REPORT.md]

轻量脚本预聚合 (Pre-aggregation via Scripts)：
- 避免大规模遍历 dump 整个目录树，而是通过专用脚本快速提取工作区拓扑、App Router 路由、Admin 路由与 Prisma 数据库模型摘要。
渐进式披露与按需规则加载 (Progressive Disclosure)：
- 严格在对应阶段独立加载领域检查清单（如 frontend-checklist.md、database-checklist.md），不长期占用工作记忆。
外部记忆分步持久化 (External Memory Persistence)：
- 每完成一个领域的审查，立即将报告落盘到目标目录（如 analysis-report-202608281220/），避免长流程遗忘与跨领域干扰。
两阶段主报告合成 (Two-Pass Executive Synthesis)：
- 最终的总报告基于已生成的 5 份模块化文档直接提炼与比对，无需二次读取原始源码。

2. 审计输出文件清单与主要内容详解

运行 /analyze-project 后，将在目标输出目录中生成以下 6 份结构化 Markdown 报告：

analysis-report-YYYYMMDDHHmm/
├── code-structure.md            # 1. 代码拓扑与工程架构
├── frontend-structure.md        # 2. 前端展示层与 UI 体系
├── backend-structure.md         # 3. 后端服务与 API Gateway
├── database-structure.md        # 4. 数据库、存储与持久层
├── test-analysis.md             # 5. 测试覆盖与 CI/CD 质量门禁
└── PROJECT_ANALYSIS_REPORT.md   # 6. 综合审计主报告与演进路线图

① `code-structure.md`（代码拓扑与工程架构）

Monorepo 结构拓扑：分析 Turborepo 与 pnpm workspaces 的多包组织结构（apps/web 与 @portal/api, @portal/config, @portal/db, @portal/shared, @portal/theme）。
包依赖图谱与模块边界：绘制内部 package 之间的引用关系，检查是否存在循环依赖或跨层级耦合。
构建管线与任务编排：解析 turbo.json 的任务依赖（build, dev, lint, typecheck, clean）与全局环境变量隔离。
端到端执行数据流：绘制客户端发起请求经过中间件、Auth 鉴权、tRPC 路由、Prisma ORM 至存储/搜索服务的时序图。

② `frontend-structure.md`（前端展示层与 UI 体系）

Next.js 16 App Router 体系：国际化 [locale] 动态路由、(site) 公共展示区与 (admin) 后台管理区的组织与嵌套 Layout 架构。
多布局引擎 (Multi-Layout Engine)：Classic（经典博客）与 Metro（磁贴卡片）布局的动态组件解耦加载机制。
主题引擎与 Anti-FOUC 防白屏闪烁：CSS 变量设计 Token 系统、<head> 内联 ThemeScript 注入与 React 19 suppressHydrationWarning 防脱水报错机制。
3 级 MDX 容错渲染管线：SafeMDXRemote 的 AST 预清洗、非法字符自动转义、降级纯文本兜底（确保 0% 出现 500 页面崩溃）。
交互安全与防刷：蜜罐字段（Honeypot）、提交时间戳 Token（Timing Token）与客户端 Zod 即时校验。
Core Web Vitals 优化：next/font 字体优化（零 CLS 偏移）、重型组件（Mermaid、KaTeX、Highlight.js）动态按需加载策略。

③ `backend-structure.md`（后端服务与 API Gateway）

tRPC v11 API 架构：createContext 请求上下文生命周期与多层反向代理客户端 IP 真实解析（cf-connecting-ip $\rightarrow$ x-forwarded-for $\rightarrow$ x-real-ip）。
分级 Procedure Guards 访问控制：publicProcedure（公开访问）、protectedProcedure（登录用户）、adminProcedure（管理员专用）。
Admin 路由模块化解耦：将原单体 Admin 路由拆解为 11 个独立领域子路由（文章、分类、评论、友链、项目、图书、周刊、配置、统计等）。
双通道认证机制：Web 端 Cookie Session (NextAuth.js v5) + 自动化/外部工具 Bearer API Key 认证通道（/api/v1/* REST API）。
全文检索与故障自动降级：MeiliSearch 全文索引同步与异常时无缝降级至 PostgreSQL ILIKE 的高可用搜索管线。
通知与邮件子系统：基于工厂模式支持 Mailgun、Resend 和 Mock 驱动的可插拔邮件提醒模块。

④ `database-structure.md`（数据库、存储与持久层）

关系模型与实体职责：21 个 Prisma 实体模型划分（认证、内容、项目、图书、友链、AI 周刊、遥测分析等）及实体关系图（ER 图）。
索引优化与复合键设计：重点针对高频查询路径配置的复合索引（如 Post(status, publishedAt)、Comment(postId, status)、TrendingRepo(weekOf, starsGrowth)）。
资产存储卸载：二进制大附件全面卸载至 Cloudflare R2 对象存储，数据库仅保存元数据与 CDN 链接。
连接池与单例模式：globalThis.prisma 单例防开发热重载连接泄露机制。
数据库迁移纪律：27 个版本化 SQL 迁移文件的执行历史与字段兼容性审查。

⑤ `test-analysis.md`（测试覆盖与 CI/CD 质量门禁）

测试套件运行指标：Vitest v4 运行结果、套件总数、通过率与执行耗时。
领域测试金字塔分布：统计主题引擎、数据库模型、tRPC 接口、Monorepo 拓扑、Auth 鉴权、MDX 防护等各维度的测试用例数。
测试路径漂移校验：验证重构后的测试断言是否与当前代码路径完全吻合（0 处漂移）。
CI/CD 流水线审计：GitHub Actions 工作流配置、PostgreSQL 16 服务容器编排、依赖冻结锁（--frozen-lockfile）、类型检查、代码规范、测试套件及构建验证。

⑥ `PROJECT_ANALYSIS_REPORT.md`（综合审计主报告）

五维架构成熟度评分卡：从架构设计、前端、后端、数据库、测试等维度给出客观评分。
设计规范 vs 实际落地对照矩阵：对比初始架构设计文档（documents/architecture.md）与代码实际实现情况，评估完成度。
全栈系统拓扑架构图：绘制端到端的 Mermaid 全景架构图。
领域关键发现汇总：归纳各领域的核心优势与潜在风险点。
P0/P1/P2 优先级行动清单：明确提出性能瓶颈、数据清理、安全防范等可落地的优化建议。
多阶段演进路线图：以甘特图形式规划短期（立即）、中期（近期）与长期（长远）的技术演进计划。

3. 运行 SKILL 后的实际输出示例

在终端或 Agent 中输入 /analyze-project，Agent 会全自动执行分层审计并输出如下报告结构：

已按照 analyze-project 规范完成对当前项目的全方位架构与代码审计，并在 analysis-report-202808281021/ 目录下生成了全部审计报告文档。

📊 审计概览与成熟度评分 (Scorecard)

审计领域	得分	状态	核心评价
架构与 Monorepo	10 / 10	🟢 优秀	Turborepo + pnpm 工作区拓扑清晰，`@portal/*` 模块边界严格解耦。
前端与 UI 层	9.5 / 10	🟢 生产就绪	多布局引擎 (Classic/Metro)、`ThemeScript` 防白屏闪烁 (Anti-FOUC)、3 级 MDX 容错渲染管线。
后端与 API Gateway	9.8 / 10	🟢 生产就绪	tRPC v11 路由彻底解耦（11 个领域 Admin 子路由），双通道鉴权 (Session + REST API Key)，MeiliSearch 自动降级。
数据库与持久层	9.5 / 10	🟢 生产就绪	21 个 Prisma 模型，27 个版本化迁移，复合索引完备，二进制附件卸载至 Cloudflare R2。
测试与 CI/CD	9.5 / 10	🟢 生产就绪	18 个测试套件 544 个测试全部通过 (0 失败，476ms)，GitHub Actions 配置 PostgreSQL 16 容器化流水线。

📑 生成的审计文档索引

您可以点击下方链接查阅各领域详细分析报告：

1. 核心设计与执行原则

SKILL的设计兼顾了 “全量代码注入导致的 Context Window 爆炸” 和 “泛泛而谈缺乏代码事实” 的问题，analyze-project 采用了以下核心原则：

graph TD
    A[Phase 1: 发现与规范预聚合] -->|Node.js 快速拓扑扫描| B[Phase 2: 领域分层审查]
    B -->|按需加载 Checklist 规则| C1[2.1 code-structure.md]
    B -->|独立上下文沙箱持久化| C2[2.2 frontend-structure.md]
    B -->|分阶段即时写入外部记忆| C3[2.3 backend-structure.md]
    B -->|检查真实模型与迁移| C4[2.4 database-structure.md]
    B -->|执行真实 Vitest 测试套件| C5[2.5 test-analysis.md]
    C1 & C2 & C3 & C4 & C5 --> D[Phase 3: 决策层两阶段综合合成]
    D --> E[PROJECT_ANALYSIS_REPORT.md]

轻量脚本预聚合 (Pre-aggregation via Scripts)：
- 避免大规模遍历 dump 整个目录树，而是通过专用脚本快速提取工作区拓扑、App Router 路由、Admin 路由与 Prisma 数据库模型摘要。
渐进式披露与按需规则加载 (Progressive Disclosure)：
- 严格在对应阶段独立加载领域检查清单（如 frontend-checklist.md、database-checklist.md），不长期占用工作记忆。
外部记忆分步持久化 (External Memory Persistence)：
- 每完成一个领域的审查，立即将报告落盘到目标目录（如 analysis-report-202608281220/），避免长流程遗忘与跨领域干扰。
两阶段主报告合成 (Two-Pass Executive Synthesis)：
- 最终的总报告基于已生成的 5 份模块化文档直接提炼与比对，无需二次读取原始源码。

2. 审计输出文件清单与主要内容详解

运行 /analyze-project 后，将在目标输出目录中生成以下 6 份结构化 Markdown 报告：

analysis-report-YYYYMMDDHHmm/
├── code-structure.md            # 1. 代码拓扑与工程架构
├── frontend-structure.md        # 2. 前端展示层与 UI 体系
├── backend-structure.md         # 3. 后端服务与 API Gateway
├── database-structure.md        # 4. 数据库、存储与持久层
├── test-analysis.md             # 5. 测试覆盖与 CI/CD 质量门禁
└── PROJECT_ANALYSIS_REPORT.md   # 6. 综合审计主报告与演进路线图

① `code-structure.md`（代码拓扑与工程架构）

Monorepo 结构拓扑：分析 Turborepo 与 pnpm workspaces 的多包组织结构（apps/web 与 @portal/api, @portal/config, @portal/db, @portal/shared, @portal/theme）。
包依赖图谱与模块边界：绘制内部 package 之间的引用关系，检查是否存在循环依赖或跨层级耦合。
构建管线与任务编排：解析 turbo.json 的任务依赖（build, dev, lint, typecheck, clean）与全局环境变量隔离。
端到端执行数据流：绘制客户端发起请求经过中间件、Auth 鉴权、tRPC 路由、Prisma ORM 至存储/搜索服务的时序图。

② `frontend-structure.md`（前端展示层与 UI 体系）

Next.js 16 App Router 体系：国际化 [locale] 动态路由、(site) 公共展示区与 (admin) 后台管理区的组织与嵌套 Layout 架构。
多布局引擎 (Multi-Layout Engine)：Classic（经典博客）与 Metro（磁贴卡片）布局的动态组件解耦加载机制。
主题引擎与 Anti-FOUC 防白屏闪烁：CSS 变量设计 Token 系统、<head> 内联 ThemeScript 注入与 React 19 suppressHydrationWarning 防脱水报错机制。
3 级 MDX 容错渲染管线：SafeMDXRemote 的 AST 预清洗、非法字符自动转义、降级纯文本兜底（确保 0% 出现 500 页面崩溃）。
交互安全与防刷：蜜罐字段（Honeypot）、提交时间戳 Token（Timing Token）与客户端 Zod 即时校验。
Core Web Vitals 优化：next/font 字体优化（零 CLS 偏移）、重型组件（Mermaid、KaTeX、Highlight.js）动态按需加载策略。

③ `backend-structure.md`（后端服务与 API Gateway）

tRPC v11 API 架构：createContext 请求上下文生命周期与多层反向代理客户端 IP 真实解析（cf-connecting-ip $\rightarrow$ x-forwarded-for $\rightarrow$ x-real-ip）。
分级 Procedure Guards 访问控制：publicProcedure（公开访问）、protectedProcedure（登录用户）、adminProcedure（管理员专用）。
Admin 路由模块化解耦：将原单体 Admin 路由拆解为 11 个独立领域子路由（文章、分类、评论、友链、项目、图书、周刊、配置、统计等）。
双通道认证机制：Web 端 Cookie Session (NextAuth.js v5) + 自动化/外部工具 Bearer API Key 认证通道（/api/v1/* REST API）。
全文检索与故障自动降级：MeiliSearch 全文索引同步与异常时无缝降级至 PostgreSQL ILIKE 的高可用搜索管线。
通知与邮件子系统：基于工厂模式支持 Mailgun、Resend 和 Mock 驱动的可插拔邮件提醒模块。

④ `database-structure.md`（数据库、存储与持久层）

关系模型与实体职责：21 个 Prisma 实体模型划分（认证、内容、项目、图书、友链、AI 周刊、遥测分析等）及实体关系图（ER 图）。
索引优化与复合键设计：重点针对高频查询路径配置的复合索引（如 Post(status, publishedAt)、Comment(postId, status)、TrendingRepo(weekOf, starsGrowth)）。
资产存储卸载：二进制大附件全面卸载至 Cloudflare R2 对象存储，数据库仅保存元数据与 CDN 链接。
连接池与单例模式：globalThis.prisma 单例防开发热重载连接泄露机制。
数据库迁移纪律：27 个版本化 SQL 迁移文件的执行历史与字段兼容性审查。

⑤ `test-analysis.md`（测试覆盖与 CI/CD 质量门禁）

测试套件运行指标：Vitest v4 运行结果、套件总数、通过率与执行耗时。
领域测试金字塔分布：统计主题引擎、数据库模型、tRPC 接口、Monorepo 拓扑、Auth 鉴权、MDX 防护等各维度的测试用例数。
测试路径漂移校验：验证重构后的测试断言是否与当前代码路径完全吻合（0 处漂移）。
CI/CD 流水线审计：GitHub Actions 工作流配置、PostgreSQL 16 服务容器编排、依赖冻结锁（--frozen-lockfile）、类型检查、代码规范、测试套件及构建验证。

⑥ `PROJECT_ANALYSIS_REPORT.md`（综合审计主报告）

五维架构成熟度评分卡：从架构设计、前端、后端、数据库、测试等维度给出客观评分。
设计规范 vs 实际落地对照矩阵：对比初始架构设计文档（documents/architecture.md）与代码实际实现情况，评估完成度。
全栈系统拓扑架构图：绘制端到端的 Mermaid 全景架构图。
领域关键发现汇总：归纳各领域的核心优势与潜在风险点。
P0/P1/P2 优先级行动清单：明确提出性能瓶颈、数据清理、安全防范等可落地的优化建议。
多阶段演进路线图：以甘特图形式规划短期（立即）、中期（近期）与长期（长远）的技术演进计划。

3. 运行 SKILL 后的实际输出示例

在终端或 Agent 中输入 /analyze-project，Agent 会全自动执行分层审计并输出如下报告结构：

已按照 analyze-project 规范完成对当前项目的全方位架构与代码审计，并在 analysis-report-202808281021/ 目录下生成了全部审计报告文档。

📊 审计概览与成熟度评分 (Scorecard)

审计领域	得分	状态	核心评价
架构与 Monorepo	10 / 10	🟢 优秀	Turborepo + pnpm 工作区拓扑清晰，`@portal/*` 模块边界严格解耦。
前端与 UI 层	9.5 / 10	🟢 生产就绪	多布局引擎 (Classic/Metro)、`ThemeScript` 防白屏闪烁 (Anti-FOUC)、3 级 MDX 容错渲染管线。
后端与 API Gateway	9.8 / 10	🟢 生产就绪	tRPC v11 路由彻底解耦（11 个领域 Admin 子路由），双通道鉴权 (Session + REST API Key)，MeiliSearch 自动降级。
数据库与持久层	9.5 / 10	🟢 生产就绪	21 个 Prisma 模型，27 个版本化迁移，复合索引完备，二进制附件卸载至 Cloudflare R2。
测试与 CI/CD	9.5 / 10	🟢 生产就绪	18 个测试套件 544 个测试全部通过 (0 失败，476ms)，GitHub Actions 配置 PostgreSQL 16 容器化流水线。

📑 生成的审计文档索引

您可以点击下方链接查阅各领域详细分析报告：

1. 核心设计与执行原则

2. 审计输出文件清单与主要内容详解

① `code-structure.md`（代码拓扑与工程架构）

② `frontend-structure.md`（前端展示层与 UI 体系）

③ `backend-structure.md`（后端服务与 API Gateway）

④ `database-structure.md`（数据库、存储与持久层）

⑤ `test-analysis.md`（测试覆盖与 CI/CD 质量门禁）

⑥ `PROJECT_ANALYSIS_REPORT.md`（综合审计主报告）

3. 运行 SKILL 后的实际输出示例

📊 审计概览与成熟度评分 (Scorecard)

📑 生成的审计文档索引

Comments (0)