加了个 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 19suppressHydrationWarning防脱水报错机制。 - 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\rightarrowx-forwarded-for\rightarrowx-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 容器化流水线。 |
📑 生成的审计文档索引
您可以点击下方链接查阅各领域详细分析报告：
评论 (0)
暂无评论，快来抢沙发吧！