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>
This commit is contained in:
@@ -0,0 +1,331 @@
|
||||
# RVW V2.0 Day 7-10 开发记录
|
||||
|
||||
**日期**: 2026-02-18
|
||||
**开发阶段**: Week 2 - Day 7-10
|
||||
**开发主题**: Skills 架构核心框架 + Skill 实现
|
||||
**开发状态**: ✅ 完成
|
||||
|
||||
---
|
||||
|
||||
## 1. 开发背景
|
||||
|
||||
### 1.1 任务目标
|
||||
|
||||
根据 RVW V2.0 Skills 架构技术设计文档，Day 7-10 的主要任务是实现完整的 Skills 框架：
|
||||
|
||||
- **Day 7**: Skills 核心框架（types, registry, executor, profile, context）
|
||||
- **Day 8**: DataForensicsSkill（依赖注入、路径安全）
|
||||
- **Day 9**: EditorialSkill + MethodologySkill
|
||||
- **Day 10**: ReviewWorker 改造（集成 SkillExecutor）
|
||||
|
||||
### 1.2 审查意见整合
|
||||
|
||||
Day 7-10 开发前，团队提交了《RVW V2.0 Skills 架构深度审查报告》，核心建议已整合：
|
||||
|
||||
| 建议 | 采纳情况 | 实现位置 |
|
||||
|------|----------|----------|
|
||||
| 使用 Zod 进行配置验证 | ✅ 采纳 | `types.ts`, `BaseSkill.ts` |
|
||||
| 依赖注入（ExtractionClient） | ✅ 采纳 | `DataForensicsSkill.ts` |
|
||||
| 路径安全检查 | ✅ 采纳 | `DataForensicsSkill.ts` |
|
||||
| onSkillComplete 回调预留 | ✅ 采纳 | `executor.ts` |
|
||||
| 泛型设计 | ✅ 采纳 | `types.ts`, `BaseSkill.ts` |
|
||||
| 增量持久化 | ⏸️ 保留 V2.1 | 接口已预留 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 开发成果
|
||||
|
||||
### 2.1 新增文件清单
|
||||
|
||||
| 文件 | 功能 | 代码行数 |
|
||||
|------|------|---------|
|
||||
| `skills/core/types.ts` | 类型定义 + Zod Schema | ~280 |
|
||||
| `skills/core/registry.ts` | Skill 注册表（单例） | ~130 |
|
||||
| `skills/core/executor.ts` | Pipeline 执行引擎 | ~270 |
|
||||
| `skills/core/profile.ts` | Profile 解析器 + 预设配置 | ~200 |
|
||||
| `skills/core/context.ts` | 上下文构建器 | ~130 |
|
||||
| `skills/core/index.ts` | Core 模块导出 | ~25 |
|
||||
| `skills/library/BaseSkill.ts` | Skill 基类（Zod 验证） | ~120 |
|
||||
| `skills/library/DataForensicsSkill.ts` | 数据侦探 Skill | ~200 |
|
||||
| `skills/library/EditorialSkill.ts` | 稿约规范性 Skill | ~150 |
|
||||
| `skills/library/MethodologySkill.ts` | 方法学评估 Skill | ~170 |
|
||||
| `skills/library/index.ts` | Library 模块导出 | ~50 |
|
||||
| `skills/index.ts` | 模块主入口 | ~10 |
|
||||
|
||||
**总计**: 12 个新文件，约 1735 行代码
|
||||
|
||||
### 2.2 修改文件清单
|
||||
|
||||
| 文件 | 修改内容 |
|
||||
|------|---------|
|
||||
| `common/document/ExtractionClient.ts` | 新增 `IExtractionClient` 接口 + `analyzeDocx` 方法 |
|
||||
| `modules/rvw/workers/reviewWorker.ts` | 改造为 Skills 架构，支持 V1/V2 切换 |
|
||||
|
||||
### 2.3 目录结构
|
||||
|
||||
```
|
||||
backend/src/modules/rvw/skills/
|
||||
├── core/ # 核心框架（未来移至 common/skills）
|
||||
│ ├── types.ts # 类型定义 + Zod Schema
|
||||
│ ├── registry.ts # Skill 注册表
|
||||
│ ├── executor.ts # Pipeline 执行引擎
|
||||
│ ├── profile.ts # Profile 配置解析
|
||||
│ ├── context.ts # 上下文管理
|
||||
│ └── index.ts # 统一导出
|
||||
├── library/ # Skill 实现库
|
||||
│ ├── BaseSkill.ts # Skill 基类
|
||||
│ ├── DataForensicsSkill.ts # 数据侦探
|
||||
│ ├── EditorialSkill.ts # 稿约规范性
|
||||
│ ├── MethodologySkill.ts # 方法学评估
|
||||
│ └── index.ts # 注册入口
|
||||
└── index.ts # 模块主入口
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 技术实现详情
|
||||
|
||||
### 3.1 核心类型定义 (types.ts)
|
||||
|
||||
#### 3.1.1 泛型设计
|
||||
|
||||
```typescript
|
||||
// 基础上下文（通用）
|
||||
interface BaseSkillContext<TProfile = unknown> {
|
||||
taskId: string;
|
||||
userId?: string;
|
||||
previousResults: SkillResult[];
|
||||
profile: TProfile;
|
||||
}
|
||||
|
||||
// RVW 扩展字段
|
||||
interface RvwContextExtras {
|
||||
documentPath: string;
|
||||
documentContent: string;
|
||||
tables?: TableData[];
|
||||
methods?: string[];
|
||||
forensicsResult?: ForensicsResult;
|
||||
}
|
||||
|
||||
// RVW 完整上下文
|
||||
interface SkillContext extends BaseSkillContext<JournalProfile>, RvwContextExtras {}
|
||||
```
|
||||
|
||||
#### 3.1.2 Zod 配置 Schema
|
||||
|
||||
```typescript
|
||||
const DataForensicsConfigSchema = z.object({
|
||||
checkLevel: z.enum(['L1', 'L1_L2', 'L1_L2_L25']).default('L1_L2_L25'),
|
||||
tolerancePercent: z.number().min(0).max(1).default(0.1),
|
||||
});
|
||||
|
||||
const EditorialConfigSchema = z.object({
|
||||
standard: z.enum(['default', 'chinese-core', 'international']).default('default'),
|
||||
maxContentLength: z.number().default(100000),
|
||||
});
|
||||
```
|
||||
|
||||
### 3.2 执行引擎 (executor.ts)
|
||||
|
||||
#### 3.2.1 核心功能
|
||||
|
||||
- **Pipeline 执行**：按 Profile 配置顺序执行 Skills
|
||||
- **超时熔断**：可配置超时时间，默认 30 秒
|
||||
- **故障隔离**：单个 Skill 失败不影响整体（可配置）
|
||||
- **上下文传递**：前置 Skill 结果自动注入后续上下文
|
||||
- **回调扩展点**：`onSkillComplete` 预留增量持久化
|
||||
|
||||
#### 3.2.2 执行流程
|
||||
|
||||
```
|
||||
Profile.pipeline.forEach(item => {
|
||||
1. 检查 enabled 状态
|
||||
2. 获取 Skill 实例
|
||||
3. 执行 canRun 前置检查
|
||||
4. 带超时执行 skill.run()
|
||||
5. 调用 onSkillComplete 回调（V2.1）
|
||||
6. 更新上下文 previousResults
|
||||
7. 检查 continueOnError 策略
|
||||
})
|
||||
```
|
||||
|
||||
### 3.3 Profile 配置 (profile.ts)
|
||||
|
||||
#### 3.3.1 预设 Profiles
|
||||
|
||||
| Profile ID | 名称 | Pipeline | 特点 |
|
||||
|------------|------|----------|------|
|
||||
| `default` | 通用期刊配置 | Forensics → Editorial → Methodology | 标准模式 |
|
||||
| `chinese-core` | 中文核心期刊 | 同上 | 严格模式，失败即停止 |
|
||||
| `quick-forensics` | 快速数据侦探 | 仅 Forensics | 快速预览 |
|
||||
|
||||
#### 3.3.2 V1 兼容
|
||||
|
||||
```typescript
|
||||
// 将 V1.0 的 selectedAgents 映射到 V2.0 Skills
|
||||
const AGENT_TO_SKILL_MAP = {
|
||||
'editorial': 'EditorialSkill',
|
||||
'methodology': 'MethodologySkill',
|
||||
'forensics': 'DataForensicsSkill',
|
||||
};
|
||||
|
||||
// ProfileResolver.resolveFromAgents(['editorial', 'methodology'])
|
||||
// → 动态生成包含这些 Skills 的 Profile
|
||||
```
|
||||
|
||||
### 3.4 DataForensicsSkill 安全设计
|
||||
|
||||
#### 3.4.1 路径白名单
|
||||
|
||||
```typescript
|
||||
const ALLOWED_PATH_PREFIXES = [
|
||||
'/app/uploads/', // Docker 容器
|
||||
'D:\\MyCursor\\', // 开发环境
|
||||
'/tmp/rvw-uploads/', // 临时目录
|
||||
];
|
||||
|
||||
canRun(context: SkillContext): boolean {
|
||||
// 安全检查：路径白名单
|
||||
const isPathAllowed = ALLOWED_PATH_PREFIXES.some(prefix =>
|
||||
context.documentPath.startsWith(prefix)
|
||||
);
|
||||
|
||||
// 检查路径遍历
|
||||
if (context.documentPath.includes('..')) {
|
||||
return false; // 拒绝
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 3.4.2 依赖注入
|
||||
|
||||
```typescript
|
||||
class DataForensicsSkill {
|
||||
private readonly extractionClient: IExtractionClient;
|
||||
|
||||
constructor(client?: IExtractionClient) {
|
||||
this.extractionClient = client || extractionClient;
|
||||
}
|
||||
}
|
||||
|
||||
// 测试时可注入 Mock
|
||||
const mockClient: IExtractionClient = { ... };
|
||||
const skill = new DataForensicsSkill(mockClient);
|
||||
```
|
||||
|
||||
### 3.5 ReviewWorker 改造
|
||||
|
||||
#### 3.5.1 架构切换
|
||||
|
||||
```typescript
|
||||
// 环境变量控制
|
||||
const USE_SKILLS_ARCHITECTURE = process.env.RVW_USE_SKILLS !== 'false';
|
||||
|
||||
// 运行时自动选择
|
||||
if (USE_SKILLS_ARCHITECTURE) {
|
||||
// V2.0 Skills 架构
|
||||
const profile = ProfileResolver.resolveFromAgents(agents);
|
||||
const summary = await executor.execute(profile, context);
|
||||
} else {
|
||||
// V1.0 Legacy 架构
|
||||
editorialResult = await reviewEditorialStandards(...);
|
||||
methodologyResult = await reviewMethodology(...);
|
||||
}
|
||||
```
|
||||
|
||||
#### 3.5.2 结果存储
|
||||
|
||||
```typescript
|
||||
// Skills 执行摘要存储到 picoExtract 字段（暂时复用）
|
||||
const skillsContext = {
|
||||
version: '2.0',
|
||||
executedAt: new Date().toISOString(),
|
||||
summary: {
|
||||
overallStatus: skillsSummary.overallStatus,
|
||||
totalSkills: skillsSummary.totalSkills,
|
||||
successCount: skillsSummary.successCount,
|
||||
errorCount: skillsSummary.errorCount,
|
||||
},
|
||||
forensicsResult: skillsSummary.results.find(r => r.skillId === 'DataForensicsSkill')?.data,
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 已知问题
|
||||
|
||||
### 4.1 数据库迁移阻塞
|
||||
|
||||
**问题**：尝试添加 `contextData` 字段时，Prisma migrate 报错（历史迁移问题）
|
||||
|
||||
**临时方案**：将 Skills 执行摘要存储到现有的 `picoExtract` JSON 字段
|
||||
|
||||
**后续计划**：修复历史迁移后，添加专用 `context_data` 字段
|
||||
|
||||
### 4.2 Python Forensics API
|
||||
|
||||
**状态**：`analyzeDocx` 方法已添加到 `ExtractionClient`，但 Python 端 API (`/api/v1/forensics/analyze`) 尚未实现
|
||||
|
||||
**后续计划**：Week 3 实现 Python 端完整 API
|
||||
|
||||
---
|
||||
|
||||
## 5. 测试状态
|
||||
|
||||
### 5.1 TypeScript 编译
|
||||
|
||||
✅ 无 Lint 错误
|
||||
|
||||
### 5.2 集成测试
|
||||
|
||||
⏳ 待 Python API 完成后进行端到端测试
|
||||
|
||||
---
|
||||
|
||||
## 6. 后续计划
|
||||
|
||||
### 6.1 Week 3 计划
|
||||
|
||||
| 任务 | 优先级 | 说明 |
|
||||
|------|--------|------|
|
||||
| Python Forensics API | P0 | 实现 `/api/v1/forensics/analyze` |
|
||||
| 前端表格渲染 | P1 | TaskDetail 页面展示提取的表格 |
|
||||
| 问题高亮 | P1 | 根据 R1C1 坐标高亮问题单元格 |
|
||||
| 端到端测试 | P1 | 完整流程测试 |
|
||||
|
||||
### 6.2 V2.1 规划
|
||||
|
||||
| 功能 | 说明 |
|
||||
|------|------|
|
||||
| `contextData` 专用字段 | 修复迁移后添加 |
|
||||
| 增量持久化 | 实现 `onSkillComplete` 回调 |
|
||||
| Profile 数据库存储 | 支持用户自定义 Profile |
|
||||
| 更多 Skills | 如引用格式检查、图表检查等 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 变更日志
|
||||
|
||||
| 时间 | 变更内容 |
|
||||
|------|---------|
|
||||
| 2026-02-18 09:00 | 开始 Day 7 开发 |
|
||||
| 2026-02-18 09:30 | 创建 skills 目录结构 |
|
||||
| 2026-02-18 10:00 | 完成 types.ts（含 Zod Schema） |
|
||||
| 2026-02-18 10:30 | 完成 registry.ts |
|
||||
| 2026-02-18 11:00 | 完成 executor.ts（含超时熔断） |
|
||||
| 2026-02-18 11:30 | 完成 profile.ts（含 3 个预设 Profile） |
|
||||
| 2026-02-18 12:00 | 完成 context.ts |
|
||||
| 2026-02-18 13:00 | 完成 BaseSkill.ts |
|
||||
| 2026-02-18 13:30 | 扩展 ExtractionClient（IExtractionClient + analyzeDocx） |
|
||||
| 2026-02-18 14:00 | 完成 DataForensicsSkill（含路径安全） |
|
||||
| 2026-02-18 14:30 | 完成 EditorialSkill |
|
||||
| 2026-02-18 15:00 | 完成 MethodologySkill |
|
||||
| 2026-02-18 15:30 | 完成 Skills 注册入口 |
|
||||
| 2026-02-18 16:00 | 改造 reviewWorker |
|
||||
| 2026-02-18 16:30 | 修复 Lint 错误，处理数据库迁移问题 |
|
||||
| 2026-02-18 17:00 | 更新开发文档 |
|
||||
|
||||
---
|
||||
|
||||
*开发记录生成时间: 2026-02-18*
|
||||
*RVW V2.0 Skills 架构*
|
||||
124
docs/03-业务模块/RVW-稿件审查系统/06-开发记录/RVW V2.0 Skills 架构深度审查报告.md
Normal file
124
docs/03-业务模块/RVW-稿件审查系统/06-开发记录/RVW V2.0 Skills 架构深度审查报告.md
Normal file
@@ -0,0 +1,124 @@
|
||||
# **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/\* 技能。
|
||||
|
||||
**架构设计通过，准许启动开发。**
|
||||
Reference in New Issue
Block a user