Files

HaHafeng 9f256c4a02 feat(rvw): implement Skills architecture (Day 7-10)

- 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>

2026-02-18 10:09:40 +08:00

6.2 KiB

Raw Permalink Blame History

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)

我们采用 "先试点，后下沉" 的稳健策略：

阶段一：孵化 (Incubation) - 当前 (Week 2)
- 开发位置：backend/src/modules/rvw/skills/*
- 任务：在此目录下完整实现 Registry, Executor, SkillInterface。
- 要求：虽然代码在 RVW 目录下，但设计必须通用。不要在 Executor 里写死 "ReviewTask" 这样的字眼，要用泛型 TContext。
阶段二：下沉 (Extraction) - V2.x (1-2个月后)
- 动作：将 modules/rvw/skills/core 剪切移动到 common/skills/core。
- 动作：将 DataForensicsSkill 改造为通用 ForensicsSkill，放入 common/skills/library。
- 验证：如果阶段一的代码写得足够解耦，这个移动过程应该是零痛感的。
阶段三：统一 (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/* 技能。

架构设计通过，准许启动开发。

6.2 KiB Raw Permalink Blame History Unescape Escape