AIclinicalresearch/docs/03-业务模块/RVW-稿件审查系统/06-开发记录/2026-02-18-Day7-10-Skills架构开发记录.md

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 泛型设计

// 基础上下文（通用）
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

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

// 将 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 路径白名单

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 依赖注入

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 架构切换

// 环境变量控制
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 结果存储

// 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 架构