@winspan/claude-forge 8.41.0 → 8.51.0

package/docs/skills-third-party.md

@@ -0,0 +1,183 @@
+# 第三方 Skills 集成指南
+
+## 概述
+
+claude-forge 集成了 [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) 作为第三方 skill 库，提供 22 个经过实战验证的成熟 skills。
+
+### 为什么引入 agent-skills？
+
+- **成熟度高**：由 Google Chrome 团队的 Addy Osmani 维护，经过大量实际项目验证
+- **覆盖面广**：涵盖代码审查、性能优化、安全检查、文档生成等常见场景
+- **MIT 授权**：开源友好，可自由使用和修改
+- **持续更新**：上游仓库活跃维护，可定期同步最新改进
+
+### 集成策略
+
+agent-skills 作为 **补充库** 存在，与 claude-forge 的 `OFFICIAL_SKILLS` 共存：
+
+- **官方 skills** (`src/skills/official/`)：claude-forge 内置，针对 SDLC 流程优化
+- **第三方 skills** (`~/.claude/skills/agent-skills/`)：通用场景，按需加载
+
+## 同步策略
+
+### 首次同步
+
+```bash
+npm run sync:agent-skills
+```
+
+执行后会：
+1. 从 GitHub clone `addyosmani/agent-skills` 到 `~/.claude/skills/agent-skills/`
+2. 记录 upstream commit hash 到 `.sync-metadata.json`
+3. 生成 MIT License 合规文件 `NOTICE`
+
+### 定期更新
+
+重复运行 `npm run sync:agent-skills` 会自动执行 `git pull` 更新到最新版本。
+
+### 同步元数据
+
+同步完成后，`~/.claude/skills/agent-skills/.sync-metadata.json` 记录：
+
+```json
+{
+  "upstream_repo": "https://github.com/addyosmani/agent-skills.git",
+  "commit_hash": "abc123...",
+  "synced_at": "2026-05-10T12:00:00.000Z"
+}
+```
+
+可通过此文件追溯当前使用的上游版本。
+
+## 去重策略
+
+> **注意**：此部分待 Task #38 完成后填充。
+
+当前已知的潜在重叠 skills：
+
+- `OFFICIAL_SKILLS` 中的某些 skill 可能与 agent-skills 功能重叠
+- 去重分析将在 Task #38 中完成，届时会更新本文档
+
+### 优先级规则（待确认）
+
+预期的加载优先级（待 Task #38 验证）：
+
+1. 用户自定义 skills (`~/.claude/skills/<name>.md`)
+2. 官方 skills (`src/skills/official/`)
+3. 第三方 skills (`~/.claude/skills/agent-skills/skills/`)
+
+## 自定义覆盖
+
+如果需要修改 agent-skills 中的某个 skill，**不要直接编辑** `~/.claude/skills/agent-skills/` 目录（会被 `git pull` 覆盖）。
+
+正确做法：
+
+1. 复制要修改的 skill 到 `~/.claude/skills/<skill-name>.md`
+2. 在复制的文件中进行修改
+3. skill registry 会优先加载用户自定义版本
+
+示例：
+
+```bash
+# 覆盖 agent-skills 的 code-review skill
+cp ~/.claude/skills/agent-skills/skills/code-review/skill.md \
+   ~/.claude/skills/code-review.md
+
+# 编辑自定义版本
+vim ~/.claude/skills/code-review.md
+```
+
+## License 合规
+
+### 授权说明
+
+agent-skills 采用 **MIT License**，允许：
+
+- ✅ 商业使用
+- ✅ 修改
+- ✅ 分发
+- ✅ 私有使用
+
+要求：
+
+- 📄 保留原始版权声明和许可证文本
+- 📄 在分发时包含 NOTICE 文件
+
+### NOTICE 文件
+
+同步脚本会自动生成 `~/.claude/skills/agent-skills/NOTICE` 文件，包含：
+
+- 上游仓库信息
+- MIT License 全文
+- 版权声明
+- 同步时间和 commit hash
+
+### 合规检查清单
+
+- [x] 保留 upstream 的 LICENSE 文件
+- [x] 生成 NOTICE 文件记录来源
+- [x] 在文档中说明第三方依赖
+- [x] 不修改 upstream 仓库的版权声明
+
+## 故障排查
+
+### 同步失败
+
+**症状**：`npm run sync:agent-skills` 报错
+
+**可能原因**：
+
+1. **网络问题**
+   ```bash
+   # 检查网络连接
+   ping github.com
+   
+   # 尝试手动 clone
+   git clone https://github.com/addyosmani/agent-skills.git /tmp/test
+   ```
+
+2. **Git 未安装**
+   ```bash
+   # 检查 git 版本
+   git --version
+   
+   # macOS 安装
+   brew install git
+   ```
+
+3. **权限问题**
+   ```bash
+   # 检查目录权限
+   ls -la ~/.claude/skills/
+   
+   # 修复权限
+   chmod -R u+w ~/.claude/skills/
+   ```
+
+### 本地修改冲突
+
+**症状**：`git pull` 时提示本地有未提交的修改
+
+**解决方案**：
+
+```bash
+cd ~/.claude/skills/agent-skills/
+
+# 查看修改
+git status
+
+# 方案 1：放弃本地修改（推荐）
+git reset --hard HEAD
+npm run sync:agent-skills
+
+# 方案 2：保存修改到用户目录
+cp skills/xxx/skill.md ~/.claude/skills/xxx.md
+git reset --hard HEAD
+npm run sync:agent-skills
+```
+
+## 参考资料
+
+- [agent-skills 官方仓库](https://github.com/addyosmani/agent-skills)
+- [MIT License 说明](https://opensource.org/licenses/MIT)
+- [claude-forge Skills Registry 设计](../src/skills/README.md)（待创建）

package/docs/testing/tasks-filter-pagination-test-report.md

@@ -0,0 +1,86 @@
+# Tasks Filter + Pagination — Test Report
+
+**Date**: 2026-05-18
+**Feature**: tasks-filter-pagination
+
+## Summary
+
+| Suite | Tests | Passed | Failed | Notes |
+|-------|-------|--------|--------|-------|
+| Unit: routes-tasks | 19 | 19 | 0 | All A1-A8 acceptance criteria covered |
+| Integration: tasks-filter | 10 | 10 | 0 | Real SQLite, JOIN + COUNT verification |
+| Full suite (npm test) | 324 | 323 | 1 | 1 pre-existing failure in sqlite-refactor-harness.test.ts (non-UUID event_id, unrelated) |
+| TypeScript (tsc --noEmit) | — | pass | 0 | Clean |
+
+## Unit Tests (routes-tasks.test.ts)
+
+### Paginated response group (7 tests)
+
+| Test | Result |
+|------|--------|
+| Returns empty page when no tasks (A1) | PASS |
+| Returns items newest-first with total and has_more (A1) | PASS |
+| Items include project_path from joined sessions | PASS |
+| Honours session filter | PASS |
+| Respects limit param and sets has_more | PASS |
+| Clamps limit to 200 (A6) | PASS |
+| Task items contain expected fields | PASS |
+
+### Filter params group (5 tests)
+
+| Test | Result |
+|------|--------|
+| Filters by single project (A2) | PASS |
+| Filters by multiple projects OR (A3) | PASS |
+| Filters by from/to time range (A4) | PASS |
+| Filters by search (title LIKE) (A5) | PASS |
+| Returns 400 for invalid query params | PASS |
+
+### Pagination group (1 test)
+
+| Test | Result |
+|------|--------|
+| Offset increments page, total stays constant (A8) | PASS |
+
+### /api/tasks/projects group (3 tests)
+
+| Test | Result |
+|------|--------|
+| Returns empty array when no tasks | PASS |
+| Returns distinct project paths that have tasks | PASS |
+| De-duplicates when multiple sessions share a project | PASS |
+
+### GET /api/tasks/:taskId group (3 tests) — unchanged route
+
+| Test | Result |
+|------|--------|
+| Returns 404 for non-existent task | PASS |
+| Returns task detail with timeline + injections + skill invocations | PASS |
+| Marks Agent calls in timeline with agent_detail | PASS |
+
+## Integration Tests (tasks-filter.integration.test.ts)
+
+Real in-memory SQLite validating JOIN correctness and COUNT accuracy.
+
+| Test | Result |
+|------|--------|
+| JOIN preserves project_path from sessions | PASS |
+| COUNT(*) matches items length when no pagination | PASS |
+| COUNT remains constant across pages (A8) | PASS |
+| Project filter via JOIN correctly isolates tasks (A2) | PASS |
+| Multi-project OR filter returns union correctly (A3) | PASS |
+| Search filter uses LIKE on title (A5) | PASS |
+| from/to date range filter (A4) | PASS |
+| queryTaskProjects returns distinct paths with tasks only | PASS |
+| Limit clamp: storage-level enforces max 200 | PASS |
+| has_more is accurate at boundary (exactly limit items) | PASS |
+
+## Pre-existing Failure
+
+`tests/unit/storage/sqlite-refactor-harness.test.ts` > `linkEventToTask associates events with tasks` — uses literal `'ev-prompt'` event_id which fails Zod UUID validation. This failure existed before this feature branch. Out of scope.
+
+## Notes
+
+- ISO 8601 date string comparison uses lexicographic sort. Test data uses `.000Z` suffix consistently to avoid `.000Z` vs `Z` sort anomaly.
+- Title LIKE search is case-insensitive for ASCII on SQLite default collation.
+- Frontend (index.html) changes are not covered by automated tests; manual E2E verification per A7 required.

package/forge

@@ -0,0 +1,321 @@
+#!/usr/bin/env bash
+# Claude Forge - 一键启动脚本
+
+set -e
+
+FORGE_DIR="$HOME/.claude-forge"
+CLAUDE_DIR="$HOME/.claude"
+SETTINGS_FILE="$CLAUDE_DIR/settings.json"
+PID_FILE="$FORGE_DIR/daemon.pid"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# 自动选择运行方式：优先 dist/，否则自动 build
+ensure_built() {
+    if [ ! -f "$SCRIPT_DIR/dist/cli/index.js" ]; then
+        info "首次运行，正在编译..."
+        cd "$SCRIPT_DIR" && npx tsc 2>&1
+        if [ ! -f "$SCRIPT_DIR/dist/cli/index.js" ]; then
+            error "编译失败，请检查 TypeScript 错误"
+            exit 1
+        fi
+        success "编译完成"
+    fi
+}
+
+run_cli() {
+    ensure_built
+    node "$SCRIPT_DIR/dist/cli/index.js" "$@"
+}
+
+# 颜色输出
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+info() {
+    echo -e "${BLUE}ℹ${NC} $1"
+}
+
+success() {
+    echo -e "${GREEN}✓${NC} $1"
+}
+
+warn() {
+    echo -e "${YELLOW}⚠${NC} $1"
+}
+
+error() {
+    echo -e "${RED}✗${NC} $1"
+}
+
+# 检查是否已初始化
+is_initialized() {
+    [ -f "$SETTINGS_FILE" ] && grep -q "claude-forge" "$SETTINGS_FILE" 2>/dev/null
+}
+
+# 检查守护进程是否运行
+is_daemon_running() {
+    if [ -f "$PID_FILE" ]; then
+        local pid=$(cat "$PID_FILE")
+        kill -0 "$pid" 2>/dev/null
+        return $?
+    fi
+    return 1
+}
+
+# 初始化
+do_init() {
+    info "正在初始化 Claude Forge..."
+    run_cli init
+    success "初始化完成"
+}
+
+# 启动守护进程
+do_start() {
+    if is_daemon_running; then
+        warn "守护进程已在运行"
+        return
+    fi
+
+    info "正在启动守护进程..."
+    run_cli daemon start
+    sleep 1
+
+    if is_daemon_running; then
+        success "守护进程已启动"
+    else
+        error "守护进程启动失败"
+        exit 1
+    fi
+}
+
+# 停止守护进程
+do_stop() {
+    if ! is_daemon_running; then
+        warn "守护进程未运行"
+        return
+    fi
+
+    info "正在停止守护进程..."
+    run_cli daemon stop
+    success "守护进程已停止"
+}
+
+# 查看状态
+do_status() {
+    echo ""
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo "  Claude Forge 状态"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo ""
+
+    # 初始化状态
+    if is_initialized; then
+        success "已初始化"
+    else
+        error "未初始化"
+    fi
+
+    # 守护进程状态
+    if is_daemon_running; then
+        success "守护进程运行中 (PID: $(cat $PID_FILE))"
+    else
+        error "守护进程未运行"
+    fi
+
+    # 统计信息
+    if [ -f "$FORGE_DIR/data.db" ]; then
+        echo ""
+        run_cli query stats
+    fi
+
+    echo ""
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+}
+
+# 查看日志
+do_logs() {
+    local log_file="$FORGE_DIR/daemon.log"
+    if [ ! -f "$log_file" ]; then
+        warn "日志文件不存在"
+        return
+    fi
+
+    tail -f "$log_file"
+}
+
+# 配置 API
+do_config_api() {
+    echo ""
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo "  配置 Claude API"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo ""
+
+    # 显示当前配置
+    info "当前配置："
+    run_cli config show 2>/dev/null | grep -E "(api_key|base_url)" || echo "  未配置"
+    echo ""
+
+    # 询问是否设置 API Key
+    read -p "设置 API Key? (留空跳过): " api_key
+    if [ -n "$api_key" ]; then
+        run_cli config set distill.api_key "$api_key"
+    fi
+
+    # 询问是否设置 Base URL
+    read -p "设置 Base URL? (留空使用默认): " base_url
+    if [ -n "$base_url" ]; then
+        run_cli config set distill.base_url "$base_url"
+    fi
+
+    echo ""
+    success "配置已更新"
+    warn "需要重启守护进程才能生效"
+    read -p "是否现在重启? (Y/n) " -n 1 -r
+    echo
+    if [[ ! $REPLY =~ ^[Nn]$ ]]; then
+        do_stop
+        sleep 1
+        do_start
+    fi
+}
+
+# 主菜单
+show_menu() {
+    echo ""
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo "  Claude Forge"
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo ""
+    echo "  1) 启动 (start)"
+    echo "  2) 停止 (stop)"
+    echo "  3) 重启 (restart)"
+    echo "  4) 状态 (status)"
+    echo "  5) 查看日志 (logs)"
+    echo "  6) 查看会话 (sessions)"
+    echo "  7) 手动蒸馏 (distill)"
+    echo "  8) 备份数据 (backup)"
+    echo "  9) 配置 API (config)"
+    echo "  r) 重置配置 (reset)"
+    echo "  u) 卸载 (uninit)"
+    echo "  0) 退出"
+    echo ""
+    echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    echo ""
+}
+
+# 处理菜单选择
+handle_choice() {
+    case $1 in
+        1|start)
+            do_start
+            ;;
+        2|stop)
+            do_stop
+            ;;
+        3|restart)
+            do_stop
+            sleep 1
+            do_start
+            ;;
+        4|status)
+            do_status
+            ;;
+        5|logs)
+            do_logs
+            ;;
+        6|sessions)
+            run_cli query sessions
+            ;;
+        7|distill)
+            info "正在蒸馏..."
+            run_cli distill
+            ;;
+        8|backup)
+            info "正在备份..."
+            run_cli backup
+            ;;
+        9|config)
+            do_config_api
+            ;;
+        r|reset)
+            read -p "确定要重置配置吗？(y/N) " -n 1 -r
+            echo
+            if [[ $REPLY =~ ^[Yy]$ ]]; then
+                run_cli config reset
+                success "配置已重置"
+            fi
+            ;;
+        u|uninit)
+            read -p "确定要卸载吗？(y/N) " -n 1 -r
+            echo
+            if [[ $REPLY =~ ^[Yy]$ ]]; then
+                run_cli uninit
+                success "已卸载"
+            fi
+            ;;
+        0|exit|quit)
+            exit 0
+            ;;
+        *)
+            error "无效选择"
+            ;;
+    esac
+}
+
+# 主流程
+main() {
+    # 如果有参数，直接执行
+    if [ $# -gt 0 ]; then
+        handle_choice "$1"
+        exit 0
+    fi
+
+    # 首次运行检查
+    if ! is_initialized; then
+        echo ""
+        warn "检测到首次运行，需要初始化"
+        read -p "是否现在初始化？(Y/n) " -n 1 -r
+        echo
+        if [[ ! $REPLY =~ ^[Nn]$ ]]; then
+            do_init
+            echo ""
+            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+            warn "重要：Hook 已注入到 Claude Code 配置"
+            warn "需要重新启动 Claude Code 才能生效！"
+            echo ""
+            echo "  请执行以下操作："
+            echo "  1. 输入 /exit 退出当前 Claude Code 会话"
+            echo "  2. 重新运行 claude 命令"
+            echo "  3. Hook 会自动生效，所有工具调用将被记录"
+            echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+        else
+            exit 0
+        fi
+    fi
+
+    # 自动启动守护进程
+    if ! is_daemon_running; then
+        info "守护进程未运行"
+        read -p "是否启动守护进程？(Y/n) " -n 1 -r
+        echo
+        if [[ ! $REPLY =~ ^[Nn]$ ]]; then
+            do_start
+        fi
+    fi
+
+    # 交互式菜单
+    while true; do
+        show_menu
+        read -p "请选择 [0-9]: " choice
+        echo ""
+        handle_choice "$choice"
+        echo ""
+        read -p "按回车继续..."
+    done
+}
+
+main "$@"