From 9dbcd91b94f2b194b1124a959b78f2389605023a Mon Sep 17 00:00:00 2001 From: wehub-skill-sync Date: Mon, 13 Jul 2026 21:37:12 +0800 Subject: [PATCH] chore: import zh skill V3 Core Implementation --- README.wehub.md | 9 + SKILL.md | 801 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 810 insertions(+) create mode 100644 README.wehub.md create mode 100644 SKILL.md diff --git a/README.wehub.md b/README.wehub.md new file mode 100644 index 0000000..08f53f3 --- /dev/null +++ b/README.wehub.md @@ -0,0 +1,9 @@ +# WeHub 来源说明 + +- Skill 名称：`V3 Core Implementation` +- 中文类目：Ruflo V3 核心实现 +- 上游仓库：`ruvnet__ruflo` +- 上游路径：`.agents/skills/v3-core-implementation/SKILL.md` +- 上游链接：https://github.com/ruvnet/ruflo/blob/HEAD/.agents/skills/v3-core-implementation/SKILL.md +- 本仓库为 WeHub 中文 Skill 汉化包，基于 skill 市场筛选 Top200 清单整理 +- 原作者、版权和许可证信息以上游仓库为准 diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..e3f3039 --- /dev/null +++ b/SKILL.md @@ -0,0 +1,801 @@ +--- + +```yaml +--- +name: "V3 Core Implementation" +description: "Core module implementation for claude-flow v3. Implements DDD domains, clean architecture patterns, dependency injection, and modular TypeScript codebase with comprehensive testing." +--- +``` + +# V3 核心实现 + +## 本技能的功能 + +按照领域驱动设计原则、整洁架构模式和现代 TypeScript 最佳实践，实现 claude-flow v3 的核心 TypeScript 模块，并附带全面的测试覆盖。 + +## 快速开始 + +```bash +# 初始化核心实现 +Task("Core foundation", "Set up DDD domain structure and base classes", "core-implementer") + +# 领域实现（并行） +Task("Task domain", "Implement task management domain with entities and services", "core-implementer") +Task("Session domain", "Implement session management domain", "core-implementer") +Task("Health domain", "Implement health monitoring domain", "core-implementer") +``` + +## 核心实现架构 + +### 领域结构 +``` +src/ +├── core/ +│ ├── kernel/ # 微内核模式 +│ │ ├── claude-flow-kernel.ts +│ │ ├── domain-registry.ts +│ │ └── plugin-loader.ts +│ │ +│ ├── domains/ # DDD 有界上下文 +│ │ ├── task-management/ +│ │ │ ├── entities/ +│ │ │ ├── value-objects/ +│ │ │ ├── services/ +│ │ │ ├── repositories/ +│ │ │ └── events/ +│ │ │ +│ │ ├── session-management/ +│ │ ├── health-monitoring/ +│ │ ├── lifecycle-management/ +│ │ └── event-coordination/ +│ │ +│ ├── shared/ # 共享内核 +│ │ ├── domain/ +│ │ │ ├── entity.ts +│ │ │ ├── value-object.ts +│ │ │ ├── domain-event.ts +│ │ │ └── aggregate-root.ts +│ │ │ +│ │ ├── infrastructure/ +│ │ │ ├── event-bus.ts +│ │ │ ├── dependency-container.ts +│ │ │ └── logger.ts +│ │ │ +│ │ └── types/ +│ │ ├── common.ts +│ │ ├── errors.ts +│ │ └── interfaces.ts +│ │ +│ └── application/ # 应用服务 +│ ├── use-cases/ +│ ├── commands/ +│ ├── queries/ +│ └── handlers/ +``` + +## 基础领域类 + +### 实体基类 +```typescript +// src/core/shared/domain/entity.ts +export abstract class Entity { + protected readonly _id: T; + private _domainEvents: DomainEvent[] = []; + + constructor(id: T) { + this._id = id; + } + + get id(): T { + return this._id; + } + + public equals(object?: Entity): boolean { + if (object == null || object == undefined) { + return false; + } + + if (this === object) { + return true; + } + + if (!(object instanceof Entity)) { + return false; + } + + return this._id === object._id; + } + + protected addDomainEvent(domainEvent: DomainEvent): void { + this._domainEvents.push(domainEvent); + } + + public getUncommittedEvents(): DomainEvent[] { + return this._domainEvents; + } + + public markEventsAsCommitted(): void { + this._domainEvents = []; + } +} +``` + +### 值对象基类 +```typescript +// src/core/shared/domain/value-object.ts +export abstract class ValueObject { + protected readonly props: T; + + constructor(props: T) { + this.props = Object.freeze(props); + } + + public equals(object?: ValueObject): boolean { + if (object == null || object == undefined) { + return false; + } + + if (this === object) { + return true; + } + + return JSON.stringify(this.props) === JSON.stringify(object.props); + } + + get value(): T { + return this.props; + } +} +``` + +### 聚合根 +```typescript +// src/core/shared/domain/aggregate-root.ts +export abstract class AggregateRoot extends Entity { + private _version: number = 0; + + get version(): number { + return this._version; + } + + protected incrementVersion(): void { + this._version++; + } + + public applyEvent(event: DomainEvent): void { + this.addDomainEvent(event); + this.incrementVersion(); + } +} +``` + +## 任务管理领域实现 + +### 任务实体 +```typescript +// src/core/domains/task-management/entities/task.entity.ts +import { AggregateRoot } from '../../shared/domain/aggregate-root'; +import { TaskId } from '../value-objects/task-id.vo'; +import { TaskStatus } from '../value-objects/task-status.vo'; +import { Priority } from '../value-objects/priority.vo'; +import { TaskAssignedEvent } from '../events/task-assigned.event'; + +interface TaskProps { + id: TaskId; + description: string; + priority: Priority; + status: TaskStatus; + assignedAgentId?: string; + createdAt: Date; + updatedAt: Date; +} + +export class Task extends AggregateRoot { + private props: TaskProps; + + private constructor(props: TaskProps) { + super(props.id); + this.props = props; + } + + static create(description: string, priority: Priority): Task { + const task = new Task({ + id: TaskId.create(), + description, + priority, + status: TaskStatus.pending(), + createdAt: new Date(), + updatedAt: new Date() + }); + + return task; + } + + static reconstitute(props: TaskProps): Task { + return new Task(props); + } + + public assignTo(agentId: string): void { + if (this.props.status.equals(TaskStatus.completed())) { + throw new Error('Cannot assign completed task'); + } + + this.props.assignedAgentId = agentId; + this.props.status = TaskStatus.assigned(); + this.props.updatedAt = new Date(); + + this.applyEvent(new TaskAssignedEvent( + this.id.value, + agentId, + this.props.priority + )); + } + + public complete(result: TaskResult): void { + if (!this.props.assignedAgentId) { + throw new Error('Cannot complete unassigned task'); + } + + this.props.status = TaskStatus.completed(); + this.props.updatedAt = new Date(); + + this.applyEvent(new TaskCompletedEvent( + this.id.value, + result, + this.calculateDuration() + )); + } + + // Getters + get description(): string { return this.props.description; } + get priority(): Priority { return this.props.priority; } + get status(): TaskStatus { return this.props.status; } + get assignedAgentId(): string | undefined { return this.props.assignedAgentId; } + get createdAt(): Date { return this.props.createdAt; } + get updatedAt(): Date { return this.props.updatedAt; } + + private calculateDuration(): number { + return this.props.updatedAt.getTime() - this.props.createdAt.getTime(); + } +} +``` + +### 任务值对象 +```typescript +// src/core/domains/task-management/value-objects/task-id.vo.ts +export class TaskId extends ValueObject { + private constructor(value: string) { + super({ value }); + } + + static create(): TaskId { + return new TaskId(crypto.randomUUID()); + } + + static fromString(id: string): TaskId { + if (!id || id.length === 0) { + throw new Error('TaskId cannot be empty'); + } + return new TaskId(id); + } + + get value(): string { + return this.props.value; + } +} + +// src/core/domains/task-management/value-objects/task-status.vo.ts +type TaskStatusType = 'pending' | 'assigned' | 'in_progress' | 'completed' | 'failed'; + +export class TaskStatus extends ValueObject { + private constructor(status: TaskStatusType) { + super({ value: status }); + } + + static pending(): TaskStatus { return new TaskStatus('pending'); } + static assigned(): TaskStatus { return new TaskStatus('assigned'); } + static inProgress(): TaskStatus { return new TaskStatus('in_progress'); } + static completed(): TaskStatus { return new TaskStatus('completed'); } + static failed(): TaskStatus { return new TaskStatus('failed'); } + + get value(): TaskStatusType { + return this.props.value; + } + + public isPending(): boolean { return this.value === 'pending'; } + public isAssigned(): boolean { return this.value === 'assigned'; } + public isInProgress(): boolean { return this.value === 'in_progress'; } + public isCompleted(): boolean { return this.value === 'completed'; } + public isFailed(): boolean { return this.value === 'failed'; } +} + +// src/core/domains/task-management/value-objects/priority.vo.ts +type PriorityLevel = 'low' | 'medium' | 'high' | 'critical'; + +export class Priority extends ValueObject { + private constructor(level: PriorityLevel) { + super({ value: level }); + } + + static low(): Priority { return new Priority('low'); } + static medium(): Priority { return new Priority('medium'); } + static high(): Priority { return new Priority('high'); } + static critical(): Priority { return new Priority('critical'); } + + get value(): PriorityLevel { + return this.props.value; + } + + public getNumericValue(): number { + const priorities = { low: 1, medium: 2, high: 3, critical: 4 }; + return priorities[this.value]; + } +} +``` + +## 领域服务 + +### 任务调度服务 +```typescript +// src/core/domains/task-management/services/task-scheduling.service.ts +import { Injectable } from '../../shared/infrastructure/dependency-container'; +import { Task } from '../entities/task.entity'; +import { Priority } from '../value-objects/priority.vo'; + +@Injectable() +export class TaskSchedulingService { + public prioritizeTasks(tasks: Task[]): Task[] { + return tasks.sort((a, b) => + b.priority.getNumericValue() - a.priority.getNumericValue() + ); + } + + public canSchedule(task: Task, agentCapacity: number): boolean { + if (agentCapacity <= 0) return false; + + // Critical tasks always schedulable + if (task.priority.equals(Priority.critical())) return true; + + // Other logic based on capacity + return true; + } + + public calculateEstimatedDuration(task: Task): number { + // Simple heuristic - would use ML in real implementation + const baseTime = 300000; // 5 minutes + const priorityMultiplier = { + low: 0.5, + medium: 1.0, + high: 1.5, + critical: 2.0 + }; + + return baseTime * priorityMultiplier[task.priority.value]; + } +} +``` + +## 仓储接口与实现 + +### 任务仓储接口 +```typescript +// src/core/domains/task-management/repositories/task.repository.ts +export interface ITaskRepository { + save(task: Task): Promise; + findById(id: TaskId): Promise; + findByAgentId(agentId: string): Promise; + findByStatus(status: TaskStatus): Promise; + findPendingTasks(): Promise; + delete(id: TaskId): Promise; +} +``` + +### SQLite 实现 +```typescript +// src/core/domains/task-management/repositories/sqlite-task.repository.ts +@Injectable() +export class SqliteTaskRepository implements ITaskRepository { + constructor( + @Inject('Database') private db: Database, + @Inject('Logger') private logger: ILogger + ) {} + + async save(task: Task): Promise { + const sql = ` + INSERT OR REPLACE INTO tasks ( + id, description, priority, status, assigned_agent_id, created_at, updated_at + ) VALUES (?, ?, ?, ?, ?, ?, ?) + `; + + await this.db.run(sql, [ + task.id.value, + task.description, + task.priority.value, + task.status.value, + task.assignedAgentId, + task.createdAt.toISOString(), + task.updatedAt.toISOString() + ]); + + this.logger.debug(`Task saved: ${task.id.value}`); + } + + async findById(id: TaskId): Promise { + const sql = 'SELECT * FROM tasks WHERE id = ?'; + const row = await this.db.get(sql, [id.value]); + + return row ? this.mapRowToTask(row) : null; + } + + async findPendingTasks(): Promise { + const sql = 'SELECT * FROM tasks WHERE status = ? ORDER BY priority DESC, created_at ASC'; + const rows = await this.db.all(sql, ['pending']); + + return rows.map(row => this.mapRowToTask(row)); + } + + private mapRowToTask(row: any): Task { + return Task.reconstitute({ + id: TaskId.fromString(row.id), + description: row.description, + priority: Priority.fromString(row.priority), + status: TaskStatus.fromString(row.status), + assignedAgentId: row.assigned_agent_id, + createdAt: new Date(row.created_at), + updatedAt: new Date(row.updated_at) + }); + } +} +``` + +## 应用层 + +### 用例实现 +```typescript +// src/core/application/use-cases/assign-task.use-case.ts +@Injectable() +export class AssignTaskUseCase { + constructor( + @Inject('TaskRepository') private taskRepository: ITaskRepository, + @Inject('AgentRepository') private agentRepository: IAgentRepository, + @Inject('DomainEventBus') private eventBus: DomainEventBus, + @Inject('Logger') private logger: ILogger + ) {} + + async execute(command: AssignTaskCommand): Promise { + try { + // 1. 验证命令 + await this.validateCommand(command); + + // 2. 加载聚合 + const task = await this.taskRepository.findById(command.taskId); + if (!task) { + throw new TaskNotFoundError(command.taskId); + } + + const agent = await this.agentRepository.findById(command.agentId); + if (!agent) { + throw new AgentNotFoundError(command.agentId); + } + + // 3. 业务逻辑 + if (!agent.canAcceptTask(task)) { + throw new AgentCannotAcceptTaskError(command.agentId, command.taskId); + } + + task.assignTo(command.agentId); + agent.acceptTask(task.id); + + // 4. 持久化变更 + await Promise.all([ + this.taskRepository.save(task), + this.agentRepository.save(agent) + ]); + + // 5. 发布领域事件 + const events = [ + ...task.getUncommittedEvents(), + ...agent.getUncommittedEvents() + ]; + + for (const event of events) { + await this.eventBus.publish(event); + } + + task.markEventsAsCommitted(); + agent.markEventsAsCommitted(); + + // 6. 返回结果 + this.logger.info(`Task ${command.taskId.value} assigned to agent ${command.agentId}`); + + return AssignTaskResult.success({ + taskId: task.id, + agentId: command.agentId, + assignedAt: new Date() + }); + + } catch (error) { + this.logger.error(`Failed to assign task ${command.taskId.value}:`, error); + return AssignTaskResult.failure(error); + } + } + + private async validateCommand(command: AssignTaskCommand): Promise { + if (!command.taskId) { + throw new ValidationError('Task ID is required'); + } + if (!command.agentId) { + throw new ValidationError('Agent ID is required'); + } + } +} +``` + +## 依赖注入配置 + +### 容器配置 +```typescript +// src/core/shared/infrastructure/dependency-container.ts +import { Container } from 'inversify'; +import { TYPES } from './types'; + +export class DependencyContainer { + private container: Container; + + constructor() { + this.container = new Container(); + this.setupBindings(); + } + + private setupBindings(): void { + // Repositories + this.container.bind(TYPES.TaskRepository) + .to(SqliteTaskRepository) + .inSingletonScope(); + + this.container.bind(TYPES.AgentRepository) + .to(SqliteAgentRepository) + .inSingletonScope(); + + // Services + this.container.bind(TYPES.TaskSchedulingService) + .to(TaskSchedulingService) + .inSingletonScope(); + + // Use Cases + this.container.bind(TYPES.AssignTaskUseCase) + .to(AssignTaskUseCase) + .inSingletonScope(); + + // Infrastructure + this.container.bind(TYPES.Logger) + .to(ConsoleLogger) + .inSingletonScope(); + + this.container.bind(TYPES.DomainEventBus) + .to(InMemoryDomainEventBus) + .inSingletonScope(); + } + + get(serviceIdentifier: symbol): T { + return this.container.get(serviceIdentifier); + } + + bind(serviceIdentifier: symbol): BindingToSyntax { + return this.container.bind(serviceIdentifier); + } +} +``` + +## 现代 TypeScript 配置 + +### 严格 TypeScript 设置 +```json +// tsconfig.json +{ + "compilerOptions": { + "target": "ES2022", + "lib": ["ES2022"], + "module": "NodeNext", + "moduleResolution": "NodeNext", + "declaration": true, + "outDir": "./dist", + "strict": true, + "exactOptionalPropertyTypes": true, + "noImplicitReturns": true, + "noFallthroughCasesInSwitch": true, + "noUncheckedIndexedAccess": true, + "noImplicitOverride": true, + "experimentalDecorators": true, + "emitDecoratorMetadata": true, + "skipLibCheck": true, + "forceConsistentCasingInFileNames": true, + "resolveJsonModule": true, + "esModuleInterop": true, + "allowSyntheticDefaultImports": true, + "baseUrl": ".", + "paths": { + "@/*": ["src/*"], + "@core/*": ["src/core/*"], + "@shared/*": ["src/core/shared/*"], + "@domains/*": ["src/core/domains/*"] + } + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"] +} +``` + +## 测试实现 + +### 领域单元测试 +```typescript +// src/core/domains/task-management/__tests__/entities/task.entity.test.ts +describe('Task Entity', () => { + let task: Task; + + beforeEach(() => { + task = Task.create('Test task', Priority.medium()); + }); + + describe('creation', () => { + it('should create task with pending status', () => { + expect(task.status.isPending()).toBe(true); + expect(task.description).toBe('Test task'); + expect(task.priority.equals(Priority.medium())).toBe(true); + }); + + it('should generate unique ID', () => { + const task1 = Task.create('Task 1', Priority.low()); + const task2 = Task.create('Task 2', Priority.low()); + + expect(task1.id.equals(task2.id)).toBe(false); + }); + }); + + describe('assignment', () => { + it('should assign to agent and change status', () => { + const agentId = 'agent-123'; + + task.assignTo(agentId); + + expect(task.assignedAgentId).toBe(agentId); + expect(task.status.isAssigned()).toBe(true); + }); + + it('should emit TaskAssignedEvent when assigned', () => { + const agentId = 'agent-123'; + + task.assignTo(agentId); + + const events = task.getUncommittedEvents(); + expect(events).toHaveLength(1); + expect(events[0]).toBeInstanceOf(TaskAssignedEvent); + }); + + it('should not allow assignment of completed task', () => { + task.assignTo('agent-123'); + task.complete(TaskResult.success('done')); + + expect(() => task.assignTo('agent-456')) + .toThrow('Cannot assign completed task'); + }); + }); +}); +``` + +### 集成测试 +```typescript +// src/core/domains/task-management/__tests__/integration/task-repository.integration.test.ts +describe('TaskRepository Integration', () => { + let repository: SqliteTaskRepository; + let db: Database; + + beforeEach(async () => { + db = new Database(':memory:'); + await setupTasksTable(db); + repository = new SqliteTaskRepository(db, new ConsoleLogger()); + }); + + afterEach(async () => { + await db.close(); + }); + + it('should save and retrieve task', async () => { + const task = Task.create('Test task', Priority.high()); + + await repository.save(task); + const retrieved = await repository.findById(task.id); + + expect(retrieved).toBeDefined(); + expect(retrieved!.id.equals(task.id)).toBe(true); + expect(retrieved!.description).toBe('Test task'); + expect(retrieved!.priority.equals(Priority.high())).toBe(true); + }); + + it('should find pending tasks ordered by priority', async () => { + const lowTask = Task.create('Low priority', Priority.low()); + const highTask = Task.create('High priority', Priority.high()); + + await repository.save(lowTask); + await repository.save(highTask); + + const pending = await repository.findPendingTasks(); + + expect(pending).toHaveLength(2); + expect(pending[0].id.equals(highTask.id)).toBe(true); // High priority first + expect(pending[1].id.equals(lowTask.id)).toBe(true); + }); +}); +``` + +## 性能优化 + +### 实体缓存 +```typescript +// src/core/shared/infrastructure/entity-cache.ts +@Injectable() +export class EntityCache> { + private cache = new Map(); + private readonly ttl: number = 300000; // 5 minutes + + set(id: string, entity: T): void { + this.cache.set(id, { entity, timestamp: Date.now() }); + } + + get(id: string): T | null { + const cached = this.cache.get(id); + if (!cached) return null; + + // Check TTL + if (Date.now() - cached.timestamp > this.ttl) { + this.cache.delete(id); + return null; + } + + return cached.entity; + } + + invalidate(id: string): void { + this.cache.delete(id); + } + + clear(): void { + this.cache.clear(); + } +} +``` + +## 成功指标 + +- [ ] **领域隔离**：100% 干净的依赖边界 +- [ ] **测试覆盖率**：领域逻辑单元测试覆盖率 >90% +- [ ] **类型安全**：严格 TypeScript 编译，零 any 类型 +- [ ] **性能**：平均用例执行时间 <50ms +- [ ] **内存效率**：核心领域堆内存使用 <100MB +- [ ] **插件架构**：模块化领域加载能力 + +## 相关 V3 技能 + +- `v3-ddd-architecture` - DDD 架构设计 +- `v3-mcp-optimization` - MCP 服务器集成 +- `v3-memory-unification` - AgentDB 仓储集成 +- `v3-swarm-coordination` - Swarm 领域实现 + +## 使用示例 + +### 完整核心实现 +```bash +# Full core module implementation +Task("Core implementation", + "Implement all core domains with DDD patterns and comprehensive testing", + "core-implementer") +``` + +### 特定领域实现 +```bash +# Single domain implementation +Task("Task domain implementation", + "Implement task management domain with entities, services, and repositories", + "core-implementer") +```