# 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 架构*