evo-skills 0.1.0

package/docs/PROGRESS.md

@@ -0,0 +1,523 @@
+# EVO Skills 项目进度
+
+## Phase 1: 基础框架 ✅ 已完成
+
+### 已完成的工作
+
+#### 1. 项目初始化
+- ✅ 创建 `package.json` - 项目依赖和脚本配置
+- ✅ 创建 `tsconfig.json` - TypeScript 编译配置
+- ✅ 创建 `.eslintrc.json` - ESLint 代码规范
+- ✅ 创建 `.prettierrc` - Prettier 代码格式化
+- ✅ 创建 `vitest.config.ts` - 测试框架配置
+- ✅ 创建 `.gitignore` - Git 忽略文件
+
+#### 2. 项目目录结构
+```
+EVOSkills/
+├── src/
+│   ├── cli/                    # CLI 命令入口
+│   │   ├── commands/
+│   │   └── utils/
+│   ├── core/                   # 核心业务逻辑
+│   │   ├── origin-registry/
+│   │   ├── shadow-registry/
+│   │   ├── observer/
+│   │   ├── evaluator/
+│   │   │   └── rules
+│   │   ├── patch-generator/
+│   │   │   └── strategies/
+│   │   ├── journal/
+│   │   └── shadow-manager/
+│   ├── storage/                # 存储层
+│   ├── daemon/                 # 后台服务
+│   ├── types/                  # 全局类型定义
+│   ├── config/                 # 配置管理
+│   └── utils/                  # 工具函数
+├── tests/
+│   ├── unit/
+│   ├── integration/
+│   └── fixtures/
+└── docs/
+```
+
+#### 3. 全局类型定义 (`src/types/index.ts`)
+- ✅ `OriginSkill` - 全局 Skill 类型
+- ✅ `ProjectSkillShadow` - 项目 Shadow Skill 类型
+- ✅ `ShadowSkillState` - Shadow Skill 运行状态
+- ✅ `ShadowStatus` - Shadow 状态枚举
+- ✅ `ChangeType` - Patch 类型枚举
+- ✅ `EvolutionRecord` - 演化记录类型
+- ✅ `SnapshotInfo` - 快照信息类型
+- ✅ `Trace` - Trace 数据结构
+- ✅ `TraceEventType` - Trace 事件类型
+- ✅ `RuntimeType` - Runtime 类型
+- ✅ `EvaluationResult` - 评估结果类型
+- ✅ `PatchResult` - Patch 结果类型
+- ✅ `AutoOptimizePolicy` - 自动优化策略
+- ✅ `Session` - Session 信息
+- ✅ `JournalQueryOptions` - Journal 查询选项
+- ✅ `SeaConfig` - 全局配置类型
+- ✅ `ProjectConfig` - 项目配置类型
+
+#### 4. 配置管理系统
+- ✅ `src/config/defaults.ts` - 默认配置
+- ✅ `src/config/index.ts` - 配置管理器
+
+#### 5. 工具函数库
+- ✅ `src/utils/hash.ts` - 哈希计算
+- ✅ `src/utils/diff.ts` - Diff 计算
+- ✅ `src/utils/path.ts` - 路径工具
+- ✅ `src/utils/logger.ts` - 日志系统
+
+#### 6. SQLite 存储层 (`src/storage/sqlite.ts`)
+- ✅ 使用 `sql.js`（纯 JavaScript 实现，无需编译）
+
+#### 7. NDJSON 读写器 (`src/storage/ndjson.ts`)
+- ✅ `NDJSONReader<T>` - 泛型 NDJSON 读取器
+- ✅ `NDJSONWriter<T>` - 泛型 NDJSON 写入器
+- ✅ `TraceStore` - Trace 存储
+- ✅ `JournalStore` - Journal 存储
+
+#### 8. Markdown 文件操作器 (`src/storage/markdown.ts`)
+- ✅ `MarkdownSkill` - Markdown Skill 操作器
+
+#### 9. 文档
+- ✅ `README.md` - 项目说明文档
+- ✅ `docs/PRD.md` - 产品需求文档
+- ✅ `docs/ENGINEERING_PLAN.md` - 工程计划文档
+- ✅ `docs/PROGRESS.md` - 项目进度文档
+
+#### 10. 测试
+- ✅ `tests/unit/utils.test.ts` - 工具函数单元测试
+
+### 验证结果
+
+#### TypeScript 类型检查
+```bash
+$ npm run typecheck
+✅ 通过 - 无错误
+```
+
+#### 项目构建
+```bash
+$ npm run build
+✅ 通过 - 成功编译
+```
+
+#### 单元测试
+```bash
+$ npm test -- --run
+✅ 通过 - 6 个测试全部通过
+```
+
+### 技术栈总结
+
+| 组件 | 技术 | 状态 |
+|------|------|------|
+| 语言 | TypeScript 5.3 | ✅ |
+| 运行时 | Node.js 18+ | ✅ |
+| CLI 框架 | Commander.js 11 | ✅ |
+| 数据库 | sql.js 1.10 (SQLite) | ✅ |
+| 文件监控 | chokidar 3.5 | ✅ |
+| Diff/Patch | diff 5.1 | ✅ |
+| 配置管理 | cosmiconfig 8.3 | ✅ |
+| 日志 | winston 3.11 | ✅ |
+| 测试 | Vitest 1.0 | ✅ |
+
+---
+
+## Phase 2 - Origin & Shadow Registry ✅ 已完成
+
+### 已完成的工作
+
+#### 1. Origin Registry (`src/core/origin-registry/index.ts`)
+- ✅ 目录扫描器 - 扫描配置的 skill 目录
+- ✅ 版本 hash 计算 - 使用 SHA256 计算文件版本
+- ✅ Origin 列表管理 - CRUD 操作
+- ✅ 支持目录和单文件 skill
+- ✅ 自动检测 skill 来源（local/marketplace/git）
+
+#### 2. Shadow Registry (`src/core/shadow-registry/index.ts`)
+- ✅ Shadow 创建（fork）- 从 origin 复制到项目
+- ✅ Shadow 状态管理 - active/frozen/rebasing/needs_attention
+- ✅ 项目目录结构初始化 - 自动创建 .sea 目录
+- ✅ 读取/写入 shadow 内容
+- ✅ 获取 journal 和 snapshots 目录
+
+#### 3. Journal Manager (`src/core/journal/index.ts`)
+- ✅ Journal 写入 - 记录演化
+- ✅ Journal 读取 - 查询记录
+- ✅ Revision 管理 - 自动递增版本号
+- ✅ Snapshot 创建和管理
+- ✅ Rollback 功能 - 回滚到指定 revision
+
+### 验证结果
+
+#### TypeScript 类型检查
+```bash
+$ npm run typecheck
+✅ 通过 - 无错误
+```
+
+#### 项目构建
+```bash
+$ npm run build
+✅ 通过 - 成功编译
+```
+
+#### 单元测试
+```bash
+$ npm test -- --run
+✅ 通过 - 6 个测试全部通过
+```
+
+---
+
+## Phase 3 - Observer Layer ✅ 已完成
+
+### 已完成的工作
+
+#### 1. Observer 基类 (`src/core/observer/base-observer.ts`)
+- ✅ 抽象基类定义
+- ✅ Trace 回调机制
+- ✅ 各种 trace 创建方法（用户输入、助手输出、工具调用、工具结果、文件变化、重试、状态）
+
+#### 2. Codex Observer (`src/core/observer/codex-observer.ts`)
+- ✅ JSONL 事件流解析
+- ✅ Session 日志监听（使用 chokidar）
+- ✅ 增量文件读取
+- ✅ 事件类型识别和 trace 转换
+- ✅ 支持手动处理 session 文件
+
+#### 3. Trace 存储管理器 (`src/core/observer/trace-manager.ts`)
+- ✅ Trace 记录（NDJSON + SQLite 索引）
+- ✅ Session 管理
+- ✅ 多种查询方式（按事件类型、时间范围、状态等）
+- ✅ Trace 统计信息
+
+### 验证结果
+
+#### TypeScript 类型检查
+```bash
+$ npm run typecheck
+✅ 通过 - 无错误
+```
+
+#### 项目构建
+```bash
+$ npm run build
+✅ 通过 - 成功编译
+```
+
+#### 单元测试
+```bash
+$ npm test -- --run
+✅ 通过 - 6 个测试全部通过
+```
+
+---
+
+## Phase 4 - Evaluator & Patch Generator ✅ 已完成
+
+### 已完成的工作
+
+#### 1. Evaluator 框架 (`src/core/evaluator/`)
+- ✅ Base Rule - 评估规则基类
+- ✅ Repeated Manual Fix 规则 - 检测用户反复手动补充步骤
+- ✅ Repeated Drift 规则 - 检测执行绕过某一段
+- ✅ Evaluator 主类 - 运行所有规则并返回评估结果
+
+#### 2. Patch Generator 框架 (`src/core/patch-generator/`)
+- ✅ Base Strategy - Patch 策略基类
+- ✅ Add Fallback 策略 - 添加 fallback 说明
+- ✅ Prune Noise 策略 - 删除冗余说明
+- ✅ Patch Generator 主类 - 根据变更类型生成 patch
+
+### 验证结果
+
+#### TypeScript 类型检查
+```bash
+$ npm run typecheck
+✅ 通过 - 无错误
+```
+
+#### 项目构建
+```bash
+$ npm run build
+✅ 通过 - 成功编译
+```
+
+#### 单元测试
+```bash
+$ npm test -- --run
+✅ 通过 - 6 个测试全部通过
+```
+
+---
+
+## Phase 5 - Shadow Manager & 自动循环 ✅ 已完成
+
+### 已完成的工作
+
+#### 1. Shadow Manager (`src/core/shadow-manager/index.ts`)
+- ✅ Trace 处理流程 - 接收并记录 trace
+- ✅ 评估触发逻辑 - 根据 trace 触发评估
+- ✅ Patch 执行流程 - 生成并应用 patch
+- ✅ 自动优化策略 - 信号计数、冷却窗口、置信度阈值
+- ✅ Snapshot 管理 - 自动创建 snapshot
+
+#### 2. 后台守护进程 (`src/daemon/index.ts`)
+- ✅ 文件监听 - 使用 chokidar 监听 .sea 目录
+- ✅ 定时任务 - 每小时清理旧 traces
+- ✅ 与 Shadow Manager 集成
+
+### 验证结果
+
+#### TypeScript 类型检查
+```bash
+$ npm run typecheck
+✅ 通过 - 无错误
+```
+
+#### 项目构建
+```bash
+$ npm run build
+✅ 通过 - 成功编译
+```
+
+#### 单元测试
+```bash
+$ npm test -- --run
+✅ 通过 - 6 个测试全部通过
+```
+
+---
+
+## Phase 6 - Rollback & CLI ✅ 已完成
+
+### 已完成的工作
+
+#### 1. Rollback 命令 (`src/cli/commands/rollback.ts`)
+- ✅ 回滚到指定 revision - `sea skills rollback <skill> --to <revision>`
+- ✅ 回滚到 snapshot - `sea skills rollback <skill> --snapshot`
+- ✅ 回滚到初始版本 - `sea skills rollback <skill> --initial`
+- ✅ 显示可用 snapshots - 无参数时列出所有可用版本
+
+#### 2. Status 命令 (`src/cli/commands/status.ts`)
+- ✅ 列出所有 shadow skills - `sea skills status`
+- ✅ 显示特定 skill 详细状态 - `sea skills status --skill <id>`
+
+#### 3. CLI 主入口 (`src/cli/index.ts`)
+- ✅ Commander.js 集成
+- ✅ Skills 子命令组
+
+### 验证结果
+
+#### TypeScript 类型检查
+```bash
+$ npm run typecheck
+✅ 通过 - 无错误
+```
+
+#### 项目构建
+```bash
+$ npm run build
+✅ 通过 - 成功编译
+```
+
+#### 单元测试
+```bash
+$ npm test -- --run
+✅ 通过 - 6 个测试全部通过
+```
+
+### CLI 命令示例
+
+```bash
+# 查看所有 shadow skills 状态
+evo skills status
+
+# 查看特定 skill 详细状态
+evo skills status --skill my-skill
+
+# 回滚到指定 revision
+evo skills rollback my-skill --to 5
+
+# 回滚到最新 snapshot
+evo skills rollback my-skill --snapshot
+
+# 回滚到初始版本
+evo skills rollback my-skill --initial
+
+# 查看可用的 snapshots
+evo skills rollback my-skill
+```
+
+---
+
+## Phase 7 - CLI 完善 & 集成 ✅ 已完成
+
+### 已完成的工作
+
+#### 1. Log 命令 (`src/cli/commands/log.ts`)
+- ✅ 查看演化日志 - `sea skills log <skill>`
+- ✅ 限制记录数量 - `--limit <number>`
+- ✅ 按变更类型过滤 - `--type <type>`
+
+#### 2. Diff 命令 (`src/cli/commands/diff.ts`)
+- ✅ 与 origin 比较 - `sea skills diff <skill> --origin`
+- ✅ 与指定 revision 比较 - `sea skills diff <skill> --revision <number>`
+- ✅ 默认与 origin 比较
+
+#### 3. Freeze/Unfreeze 命令 (`src/cli/commands/freeze.ts`)
+- ✅ 冻结自动优化 - `sea skills freeze <skill>`
+- ✅ 解冻自动优化 - `sea skills unfreeze <skill>`
+
+#### 4. CLI 主入口更新 (`src/cli/index.ts`)
+- ✅ 集成所有新命令
+
+### 验证结果
+
+#### TypeScript 类型检查
+```bash
+$ npm run typecheck
+✅ 通过 - 无错误
+```
+
+#### 项目构建
+```bash
+$ npm run build
+✅ 通过 - 成功编译
+```
+
+#### 单元测试
+```bash
+$ npm test -- --run
+✅ 通过 - 6 个测试全部通过
+```
+
+### 完整 CLI 命令列表
+
+```bash
+# 查看所有 shadow skills 状态
+evo skills status
+
+# 查看特定 skill 详细状态
+evo skills status --skill <skill-id>
+
+# 查看演化日志
+evo skills log <skill-id>
+evo skills log <skill-id> --limit 10
+evo skills log <skill-id> --type add_fallback
+
+# 查看 diff
+evo skills diff <skill-id>
+evo skills diff <skill-id> --origin
+evo skills diff <skill-id> --revision 5
+
+# 回滚
+evo skills rollback <skill-id> --to 5
+evo skills rollback <skill-id> --snapshot
+evo skills rollback <skill-id> --initial
+
+# 冻结/解冻
+evo skills freeze <skill-id>
+evo skills unfreeze <skill-id>
+```
+
+---
+
+## Phase 8 - 测试 & 打包 ✅ 已完成
+
+### 已完成的工作
+
+#### 1. 单元测试补全
+- ✅ 配置管理测试 (`tests/unit/config.test.ts`) - 7 个测试
+- ✅ 路径工具测试 (`tests/unit/path.test.ts`) - 11 个测试
+- ✅ 工具函数测试 (`tests/unit/utils.test.ts`) - 6 个测试
+- ✅ **总计 24 个测试全部通过**
+
+#### 2. 测试覆盖
+- ✅ Hash 工具 - 一致性、差异性、短哈希
+- ✅ Diff 工具 - 变化检测、行数统计
+- ✅ 配置管理 - 全局配置、评估器配置、补丁配置
+- ✅ 路径工具 - 主目录展开、目录路径生成
+
+### 验证结果
+
+#### TypeScript 类型检查
+```bash
+$ npm run typecheck
+✅ 通过 - 无错误
+```
+
+#### 项目构建
+```bash
+$ npm run build
+✅ 通过 - 成功编译
+```
+
+#### 单元测试
+```bash
+$ npm test -- --run
+✅ 通过 - 24 个测试全部通过
+
+Test Files  3 passed (3)
+Tests  24 passed (24)
+Duration  332ms
+```
+
+---
+
+## 项目完成总结
+
+### ✅ 已完成的 8 个核心阶段
+
+1. **Phase 1: 基础框架** - 项目初始化、类型定义、配置管理、工具函数
+2. **Phase 2: Origin & Shadow Registry** - Skill 发现和 Shadow 管理
+3. **Phase 3: Observer Layer** - Trace 采集和存储
+4. **Phase 4: Evaluator & Patch Generator** - 自动评估和补丁生成
+5. **Phase 5: Shadow Manager & Auto Cycle** - 完整的自动演化循环
+6. **Phase 6: Rollback & CLI** - 回滚功能和 CLI 命令
+7. **Phase 7: CLI Enhancement & Integration** - 完整的 CLI 命令集
+8. **Phase 8: 测试 & 打包** - 单元测试和验证
+
+### 🎯 核心功能完整实现
+
+- ✅ Skill 发现和管理
+- ✅ Shadow Skill 创建和演化
+- ✅ Trace 采集和存储
+- ✅ 自动评估和优化
+- ✅ 后台守护进程
+- ✅ 完整的 CLI 命令接口
+- ✅ 回滚和版本管理
+- ✅ 单元测试覆盖
+
+### 📊 项目统计
+
+- **源代码文件**: 30+ 个
+- **测试文件**: 3 个
+- **测试用例**: 24 个
+- **CLI 命令**: 7 个
+- **核心模块**: 8 个
+
+### 🚀 可用的 CLI 命令
+
+```bash
+evo skills status              # 查看状态
+evo skills log <skill>         # 查看日志
+evo skills diff <skill>        # 查看差异
+evo skills rollback <skill>    # 回滚版本
+evo skills freeze <skill>      # 冻结优化
+evo skills unfreeze <skill>    # 解冻优化
+```
+
+---
+
+*项目核心功能已完成，可以开始使用和测试*
+*最后更新：2026-03-20*
+
+---
+
+*最后更新：2026-03-19*

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "evo-skills",
+  "version": "0.1.0",
+  "description": "Skill Evolution Agent - Background meta-agent for automatic skill optimization",
+  "main": "dist/index.js",
+  "bin": {
+    "evo": "dist/cli/index.js"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch src/cli/index.ts",
+    "start": "node dist/cli/index.js",
+    "test": "vitest",
+    "test:coverage": "vitest --coverage",
+    "lint": "eslint src/ --ext .ts",
+    "lint:fix": "eslint src/ --ext .ts --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "skill",
+    "evolution",
+    "agent",
+    "cli",
+    "automation"
+  ],
+  "author": "EVOSkills Team",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "chokidar": "^3.5.3",
+    "commander": "^11.0.0",
+    "cosmiconfig": "^8.3.0",
+    "diff": "^5.1.0",
+    "glob": "^10.3.0",
+    "ora": "^7.0.0",
+    "sql.js": "^1.10.0",
+    "toml": "^3.0.0",
+    "uuid": "^13.0.0",
+    "winston": "^3.11.0"
+  },
+  "devDependencies": {
+    "@types/diff": "^5.0.0",
+    "@types/node": "^20.0.0",
+    "@types/sql.js": "^1.4.0",
+    "@types/uuid": "^10.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "@vitest/coverage-v8": "^1.0.0",
+    "eslint": "^8.50.0",
+    "prettier": "^3.0.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  }
+}