HaHafeng
9f256c4a02
- Add Skills core framework (types, registry, executor, profile, context) - Implement DataForensicsSkill with DI, path security, graceful degradation - Implement EditorialSkill and MethodologySkill wrapping existing services - Extend ExtractionClient with IExtractionClient interface and analyzeDocx - Refactor reviewWorker to support V1/V2 architecture switching - Add Zod config validation and generic type support - Update development docs and module status Day 7: Skills core framework (~700 lines) Day 8: DataForensicsSkill + ExtractionClient extension (~400 lines) Day 9: EditorialSkill + MethodologySkill (~350 lines) Day 10: ReviewWorker integration (~280 lines) Co-authored-by: Cursor <cursoragent@cursor.com>
124 lines
6.2 KiB
Markdown
124 lines
6.2 KiB
Markdown
# **RVW V2.0 Skills 架构深度审查报告**
|
||
|
||
**审查对象：** RVW V2.0 Skills 架构技术设计文档 (v1.0)
|
||
|
||
**审查日期：** 2026-02-17
|
||
|
||
**审查结论：** ✅ **架构设计通过 (Approved)**
|
||
|
||
**核心评价：** 结构清晰，扩展性强。**不仅满足 V2.0 需求，更确立了全系统 Agentic AI 的演进基石。**
|
||
|
||
## **1\. 🟢 架构亮点 (Strengths)**
|
||
|
||
这份设计文档在以下几个方面表现卓越，值得团队坚持：
|
||
|
||
### **1.1 "优雅降级" 的教科书级示范**
|
||
|
||
在 DataForensicsSkill.ts 的设计中（第 5.2 节），当 Python 服务不可用（ECONNREFUSED）时，系统没有直接抛出 500 错误，而是返回 status: 'warning' 并提示用户“服务暂不可用，已跳过验证”。
|
||
|
||
* **价值**：这是极佳的用户体验设计。它保证了即使高级功能挂了，基础的审稿流程（LLM 部分）依然能跑通，系统韧性极强。
|
||
|
||
### **1.2 上下文设计的 "轻重分离"**
|
||
|
||
在 SkillContext 设计中（第 4.1 节），同时保留了 documentPath（用于 Python 读取文件）和 documentContent（用于 LLM 读取文本）。
|
||
|
||
* **价值**：这避免了将巨大的二进制文件加载到 Node.js 内存中，只传递路径给 Python 服务处理，符合“云原生”的高效原则。
|
||
|
||
### **1.3 Profile 的 "硬编码" 策略**
|
||
|
||
在 MVP 阶段选择将 Profile 硬编码在 profile.ts 中（第 4.4 节），而不是直接上数据库表。
|
||
|
||
* **价值**：极其务实。这避免了在 Week 2 开发繁琐的 CRUD 管理界面，让团队能聚焦于核心逻辑，同时代码结构又预留了未来切换到数据库的能力。
|
||
|
||
## **2\. 🟡 潜在风险与改进建议 (Risks & Improvements)**
|
||
|
||
尽管大框架完美，但在工程细节上，有以下优化建议：
|
||
|
||
### **2.1 配置验证的类型安全 (Type Safety in Config)**
|
||
|
||
* **问题**：目前 SkillConfig 定义为 any。
|
||
* **建议**：引入 **Zod** 库进行运行时 Schema 验证。
|
||
// 示例：在 DataForensicsSkill 中
|
||
import { z } from 'zod';
|
||
const ConfigSchema \= z.object({
|
||
checkLevel: z.enum(\['L1', 'L1\_L2'\]).default('L1\_L2'),
|
||
tolerancePercent: z.number().min(0).max(1).default(0.1)
|
||
});
|
||
// 在 run 方法开头: const safeConfig \= ConfigSchema.parse(config);
|
||
|
||
### **2.2 状态持久化的时机 (State Persistence Timing)**
|
||
|
||
* **问题**：目前的 ReviewWorker 是在所有 Skill 执行完毕后一次性更新数据库。
|
||
* **建议**：在 SkillExecutor 中增加 onSkillComplete 回调，**每执行完一个 Skill 就更新一次数据库**（增量更新），实现应用层断点续传。
|
||
|
||
### **2.3 测试的可模拟性 (Mockability)**
|
||
|
||
* **建议**：采用**依赖注入**。在 Skill 的构造函数中注入 ExtractionClient 实例，确保单元测试可以 Mock Python 服务。
|
||
|
||
### **2.4 ⚠️ 核心框架的耦合风险 (Coupling Risk)**
|
||
|
||
* **问题**：skills/core 目录下的代码（Registry, Executor）如果引入了 modules/rvw 下的业务类型，会导致未来无法提取为通用模块。
|
||
* **红线**：skills/core 下的文件 **严禁 import** modules/rvw/services 或 modules/rvw/types 中的业务特定代码。它必须是纯粹的、通用的。
|
||
|
||
## **3\. 🛡️ 安全性审查 (Security Review)**
|
||
|
||
* **路径遍历风险**：确保 documentPath 来源于系统可信的存储服务生成，防止恶意读取。
|
||
* **资源耗尽风险**：在 EditorialSkill 前置检查中增加文本长度限制（如 \>10万字截断）。
|
||
|
||
## **4\. 🏛️ 系统架构演进战略 (System Architecture Evolution Strategy)**
|
||
|
||
**本章节至关重要。请开发团队在编码时时刻铭记：你们不仅仅是在做 RVW 模块，你们是在为全公司搭建 Skills 基础设施。**
|
||
|
||
### **4.1 战略定位：RVW 作为“架构试验田”**
|
||
|
||
Skills 架构不仅仅服务于 RVW，未来将上升为 IIT、AIA、ASL 等所有模块的通用底座。
|
||
|
||
* **现状**：各模块（IIT, AIA）都在重复造“工具调用”的轮子。
|
||
* **目标**：通过 RVW V2.0 项目，孵化出一套标准的 Skills 框架。
|
||
|
||
### **4.2 演进路线图 (The Roadmap)**
|
||
|
||
我们采用 **"先试点，后下沉"** 的稳健策略：
|
||
|
||
1. **阶段一：孵化 (Incubation) \- 当前 (Week 2\)**
|
||
* **开发位置**：backend/src/modules/rvw/skills/\*
|
||
* **任务**：在此目录下完整实现 Registry, Executor, SkillInterface。
|
||
* **要求**：虽然代码在 RVW 目录下，但**设计必须通用**。不要在 Executor 里写死 "ReviewTask" 这样的字眼，要用泛型 TContext。
|
||
2. **阶段二：下沉 (Extraction) \- V2.x (1-2个月后)**
|
||
* **动作**：将 modules/rvw/skills/core 剪切移动到 common/skills/core。
|
||
* **动作**：将 DataForensicsSkill 改造为通用 ForensicsSkill，放入 common/skills/library。
|
||
* **验证**：如果阶段一的代码写得足够解耦，这个移动过程应该是零痛感的。
|
||
3. **阶段三：统一 (Unification) \- V3.0**
|
||
* **动作**：IIT 模块重构，弃用内部的 ToolsService，改为调用 common/skills。
|
||
|
||
### **4.3 对 IIT 模块的协同建议**
|
||
|
||
* 虽然 IIT 目前不重构，但新开发的 Tool **接口定义（Input/Output Schema）应尽量与 RVW 的 Skill 标准保持一致**，以便未来无缝迁移。
|
||
|
||
## **5\. 📝 最终执行建议 (Action Plan)**
|
||
|
||
### **Day 7: 核心框架开发 (The Foundation)**
|
||
|
||
* **目标**：搭建 skills/core。
|
||
* **关键指令**：
|
||
* 编写 types.ts 和 registry.ts 时，**忘掉 RVW 这个业务**，假设你是在写一个开源的 agent-skill-engine 库。
|
||
* 引入 Zod 做配置验证。
|
||
|
||
### **Day 8: 技能实现 (The Implementation)**
|
||
|
||
* **目标**：开发 DataForensicsSkill。
|
||
* **关键指令**：
|
||
* 将 Python 调用逻辑封装严密。
|
||
* 确保 documentPath 的处理逻辑是安全的。
|
||
|
||
### **Day 9: 业务迁移 (The Migration)**
|
||
|
||
* **目标**：将 editorialService 封装为 Skill。
|
||
* **关键指令**：
|
||
* 这是一次“搬家”。将原有逻辑原封不动地搬进 run() 方法，不要搞破坏性重构。
|
||
|
||
**结论：**
|
||
|
||
**RVW V2.0 是全系统迈向 Agentic AI 的第一步。** 请开发团队以“编写通用框架”的高标准来要求 skills/core 的代码质量，但以“快速交付业务”的务实态度来实现具体的 library/\* 技能。
|
||
|
||
**架构设计通过，准许启动开发。** |