jfox-cli 0.2.0__tar.gz → 0.2.1__tar.gz

{jfox_cli-0.2.0 → jfox_cli-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jfox-cli
-Version: 0.2.0
+Version: 0.2.1
 Summary: JFox - Zettelkasten 知识管理 CLI 工具
 Project-URL: Homepage, https://github.com/zhuxixi/jfox
 Project-URL: Repository, https://github.com/zhuxixi/jfox

jfox_cli-0.2.1/docs/superpowers/specs/2026-04-13-pr-auto-code-review-design.md

@@ -0,0 +1,286 @@
+# PR 自动 Code Review 系统设计
+
+## 概述
+
+本系统实现当 GitHub 上任何仓库创建或更新 PR 时，自动触发 Claude Code 的 code review，并将结果提交到 PR 评论中。
+
+**核心目标：**
+- 全自动：PR 创建/更新后自动触发，无需人工干预
+- 多仓库：支持监控账号下所有可访问的仓库
+- 轻量级：单 Python 脚本，资源占用低
+- 易部署：Windows 环境一键启动
+
+---
+
+## 架构
+
+```
+┌─────────────────┐     ┌─────────────┐     ┌──────────────────────────┐
+│  GitHub Webhook │────▶│  smee.io    │────▶│  Flask Webhook Receiver  │
+│  (PR opened/    │     │  (proxy)    │     │  (Windows 本地运行)       │
+│   synchronize)  │     └─────────────┘     └──────────┬───────────────┘
+└─────────────────┘                                    │
+                                                       ▼
+                                              ┌──────────────────────┐
+                                              │ 调用 Claude Code     │
+                                              │ claude code          │
+                                              │   --print            │
+                                              │   /code-review:code-review <PR_URL>
+                                              └──────────┬───────────┘
+                                                         │
+                                                         ▼
+                                              ┌──────────────────────┐
+                                              │ 提交 Review 评论     │
+                                              │ (gh pr review ...)   │
+                                              └──────────────────────┘
+```
+
+---
+
+## 组件说明
+
+### 1. smee.io（Webhook 代理）
+
+GitHub Webhook 需要公网地址，smee.io 是 GitHub 官方提供的免费代理服务，将 webhook 事件转发到本地。
+
+- 访问 https://smee.io 获取一个唯一 URL
+- 本地客户端连接到 smee.io，接收事件
+- 无需暴露本地端口到公网
+
+### 2. Flask Webhook 接收器
+
+核心服务，负责：
+
+1. **接收事件**：监听来自 smee.io 的 POST 请求
+2. **过滤事件**：只处理 `pull_request.opened` 和 `pull_request.synchronize`
+3. **提取信息**：从 payload 获取 PR URL、仓库、分支等信息
+4. **触发 Review**：调用 Claude Code 执行 code review
+5. **提交结果**：使用 `gh` CLI 将 review 结果提交到 PR
+
+**技术栈：**
+- Python 3.10+
+- Flask（轻量级 web 框架）
+- requests（HTTP 客户端）
+
+### 3. Claude Code 调用
+
+通过 subprocess 调用本地安装的 Claude Code：
+
+```bash
+claude code --print /code-review:code-review <PR_URL>
+```
+
+Claude Code 会分析 PR 并返回 review 结果（JSON 或文本格式）。
+
+### 4. GitHub CLI (gh)
+
+用于提交 review 评论，复用已有的认证：
+
+```bash
+gh pr review <PR_URL> --comment -b "<review_result>"
+```
+
+---
+
+## 数据流
+
+### PR 创建场景
+
+```
+1. 用户在 GitHub 创建 PR
+2. GitHub 发送 webhook 到配置的 smee.io URL
+3. smee.io 转发到本地 Flask 服务
+4. Flask 验证事件签名（可选）
+5. Flask 提取 PR URL: https://github.com/owner/repo/pull/123
+6. Flask 调用: claude code --print /code-review:code-review <URL>
+7. Claude Code 返回 review 结果
+8. Flask 调用: gh pr review <URL> --comment -b "<result>"
+9. 评论出现在 PR 中
+```
+
+### PR 更新场景（push 新代码）
+
+```
+1. 用户 push 新 commit 到 PR 分支
+2. GitHub 发送 `pull_request.synchronize` 事件
+3. 同上流程，重新执行 code review
+4. 新评论追加到 PR
+```
+
+---
+
+## 配置
+
+配置文件：`config.json`
+
+```json
+{
+  "smee_url": "https://smee.io/YOUR_UNIQUE_CHANNEL",
+  "port": 3000,
+  "log_level": "INFO",
+  "review_on_open": true,
+  "review_on_sync": true,
+  "skip_drafts": true,
+  "max_pr_age_hours": 24
+}
+```
+
+**配置项说明：**
+
+| 配置项 | 说明 | 默认值 |
+|--------|------|--------|
+| `smee_url` | smee.io 提供的唯一 URL | 必填 |
+| `port` | 本地 Flask 服务端口 | 3000 |
+| `log_level` | 日志级别 | INFO |
+| `review_on_open` | PR 创建时自动 review | true |
+| `review_on_sync` | PR 更新时自动 review | true |
+| `skip_drafts` | 跳过 Draft PR | true |
+| `max_pr_age_hours` | 只 review 24 小时内创建的 PR（防止误触发历史 PR） | 24 |
+
+---
+
+## 安装与运行
+
+### 前置依赖
+
+1. Python 3.10+
+2. Claude Code 已安装并登录
+3. GitHub CLI (gh) 已安装并登录
+
+### 安装
+
+```bash
+# 克隆或下载项目
+git clone <repo>
+cd pr-auto-reviewer
+
+# 创建虚拟环境
+python -m venv venv
+venv\Scripts\activate
+
+# 安装依赖
+pip install -r requirements.txt
+```
+
+### 配置
+
+1. 访问 https://smee.io 获取一个新的 channel URL
+2. 复制 `config.example.json` 为 `config.json`
+3. 将 smee_url 填入配置
+
+### 启动
+
+```bash
+# 方式1：直接运行（前台）
+python webhook_server.py
+
+# 方式2：后台运行（Windows）
+start /B python webhook_server.py
+```
+
+### 配置 GitHub Webhook
+
+对于要监控的仓库，在 Settings > Webhooks 中添加：
+
+- **Payload URL**: 你的 smee.io URL (如 `https://smee.io/abc123`)
+- **Content type**: `application/json`
+- **Events**: 选择 "Pull requests"
+- **Active**: 勾选
+
+**注意**：每个仓库都需要单独配置 webhook。如果想要监控所有仓库，可以考虑使用 GitHub App（需要额外配置）。
+
+---
+
+## 错误处理
+
+| 错误场景 | 处理方式 |
+|----------|----------|
+| smee.io 连接断开 | 自动重连，指数退避 |
+| Claude Code 调用失败 | 记录日志，重试 3 次 |
+| gh CLI 认证过期 | 记录错误，通知用户 |
+| PR 不存在或无权访问 | 跳过，记录警告 |
+| 网络超时 | 重试 3 次，每次间隔 5 秒 |
+| Review 结果为空 | 跳过提交评论 |
+
+---
+
+## 日志
+
+日志输出到控制台和文件 `logs/webhook.log`：
+
+```
+2026-04-13 10:30:15 [INFO] 收到 webhook: pull_request.opened, repo=owner/repo, pr=#123
+2026-04-13 10:30:15 [INFO] 开始 review: https://github.com/owner/repo/pull/123
+2026-04-13 10:31:02 [INFO] Review 完成，提交评论
+2026-04-13 10:31:03 [INFO] 评论提交成功
+```
+
+---
+
+## 安全考虑
+
+1. **Webhook 签名验证**（可选）：
+   - 配置 GitHub webhook secret
+   - 本地验证 HMAC 签名，防止伪造请求
+
+2. **Token 安全**：
+   - 复用 gh CLI 的认证，不存储 PAT
+   - gh CLI 使用系统密钥管理器存储 token
+
+3. **访问控制**：
+   - Flask 服务只绑定 localhost（`127.0.0.1`）
+   - 不暴露到公网
+
+4. **日志脱敏**：
+   - 不记录敏感信息
+   - PR URL 等基础信息正常记录
+
+---
+
+## 扩展性
+
+### 未来可扩展的功能
+
+1. **更细粒度的控制**：
+   - 按仓库配置不同的 review 规则
+   - 支持 `.github/code-review-config.yml`
+
+2. **更多触发条件**：
+   - 只在特定标签的 PR 上触发
+   - 只在特定分支的 PR 上触发
+
+3. **结果通知**：
+   - 发送到 Slack/飞书
+   - 发送邮件通知
+
+4. **Review 缓存**：
+   - 对相同 commit 的 PR 返回缓存结果
+   - 减少 API 调用和计算成本
+
+---
+
+## 文件结构
+
+```
+pr-auto-reviewer/
+├── webhook_server.py      # 主服务
+├── config.py              # 配置加载
+├── github_client.py       # GitHub API 封装
+├── reviewer.py            # Claude Code 调用封装
+├── requirements.txt       # 依赖
+├── config.example.json    # 配置示例
+├── config.json            # 实际配置（gitignore）
+├── logs/                  # 日志目录
+│   └── webhook.log
+└── README.md              # 使用说明
+```
+
+---
+
+## 成功标准
+
+- [ ] PR 创建后 1 分钟内自动触发 review
+- [ ] Review 结果成功提交到 PR 评论
+- [ ] PR 更新后自动重新 review
+- [ ] 服务稳定运行 7 天无崩溃
+- [ ] 支持同时监控多个仓库

{jfox_cli-0.2.0 → jfox_cli-0.2.1}/jfox/__init__.py

@@ -1,5 +1,5 @@
 """JFox - Zettelkasten 知识管理工具"""
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"
 __author__ = "User"
 __email__ = "user@example.com"

{jfox_cli-0.2.0 → jfox_cli-0.2.1}/jfox/cli.py

@@ -1702,15 +1702,29 @@ def _index_impl(action: str, output_format: str):
             console.print("[yellow]Rebuilding index...[/yellow]")
             count = indexer.index_all()
 
+            # 同时重建 BM25 索引
+            from . import note as note_module
+            from .bm25_index import get_bm25_index
+
+            bm25_index = get_bm25_index()
+            notes = note_module.list_notes(limit=10000)
+            bm25_success = bm25_index.rebuild_from_notes(notes)
+
             result = {
                 "success": True,
                 "indexed": count,
+                "bm25_rebuilt": bm25_success,
+                "bm25_indexed": len(notes),
             }
 
             if output_format == "json":
                 print(output_json(result))
             else:
                 console.print(f"[green]✓[/green] Indexed {count} notes")
+                if bm25_success:
+                    console.print(f"[green]✓[/green] BM25 index rebuilt: {len(notes)} notes")
+                else:
+                    console.print("[yellow]⚠[/yellow] ChromaDB rebuilt, but BM25 rebuild failed")
 
         elif action == "verify":
             verification = indexer.verify_index()
@@ -2155,6 +2169,115 @@ def kb(
 # =============================================================================
 
 
+def _ingest_log_impl(
+    repo_path: str,
+    limit: int,
+    note_type: str,
+    batch_size: int,
+    output_format: str,
+    json_output: bool,
+):
+    """从 Git 仓库提取 commit 历史并导入为笔记"""
+    from .git_extractor import commits_to_notes, extract_commits
+    from .performance import bulk_import_notes
+
+    # 提取 commits
+    commits = extract_commits(repo_path, limit=limit)
+
+    if not commits:
+        result = {
+            "success": True,
+            "imported": 0,
+            "total": 0,
+            "message": "没有找到 commit 记录",
+        }
+        if output_format == "json":
+            print(output_json(result))
+        else:
+            console.print("[yellow]![/yellow] 没有找到 commit 记录")
+        return
+
+    # 转换为笔记格式
+    notes_data = commits_to_notes(commits, repo_path=repo_path)
+
+    if output_format != "json":
+        console.print(f"[yellow]提取了 {len(notes_data)} 条 commit，正在导入...[/yellow]")
+
+    import_result = bulk_import_notes(
+        notes_data=notes_data,
+        note_type=note_type,
+        batch_size=batch_size,
+        show_progress=output_format != "json",
+    )
+
+    result = {
+        "success": True,
+        "repo_path": str(Path(repo_path).resolve()),
+        "commits_extracted": len(commits),
+        **import_result,
+    }
+
+    if output_format == "json":
+        print(output_json(result))
+    else:
+        console.print(f"[green]✓[/green] 导入: {import_result['imported']}")
+        console.print(f"[red]✗[/red] 失败: {import_result['failed']}")
+        console.print(f"总计: {import_result['total']}")
+
+
+@app.command()
+def ingest_log(
+    repo_path: str = typer.Argument(..., help="本地 Git 仓库路径"),
+    limit: int = typer.Option(50, "--limit", "-n", help="提取 commit 数量"),
+    note_type: str = typer.Option("fleeting", "--type", "-t", help="笔记类型"),
+    batch_size: int = typer.Option(32, "--batch-size", "-b", help="批处理大小"),
+    kb: Optional[str] = typer.Option(None, "--kb", "-k", help="目标知识库名称"),
+    output_format: str = typer.Option("table", "--format", "-f", help="输出格式: json, table"),
+    json_output: bool = typer.Option(
+        False, "--json", help="JSON 输出（快捷方式，等同于 --format json）"
+    ),
+):
+    """
+    从 Git 仓库提取 commit 历史并导入为笔记
+
+    使用 block 分隔符格式提取 git log，自动处理 UTF-8 编码和路径规范化。
+
+    示例:
+        jfox ingest-log ./my-project --limit 50
+        jfox ingest-log ./my-project --kb work --type permanent
+    """
+    try:
+        # 处理 --json 快捷方式
+        if json_output:
+            output_format = "json"
+
+        # 如果指定了知识库，临时切换
+        if kb:
+            from .config import use_kb
+
+            with use_kb(kb):
+                _ingest_log_impl(
+                    repo_path, limit, note_type, batch_size, output_format, json_output
+                )
+        else:
+            _ingest_log_impl(repo_path, limit, note_type, batch_size, output_format, json_output)
+
+    except ValueError as e:
+        result = {"success": False, "error": str(e)}
+        if output_format == "json":
+            print(output_json(result))
+        else:
+            console.print(f"[red]✗[/red] {e}")
+        raise typer.Exit(1)
+    except Exception as e:
+        result = {"success": False, "error": str(e)}
+        if output_format == "json":
+            print(output_json(result))
+        else:
+            console.print(f"[red]✗[/red] Error: {e}")
+        raise typer.Exit(1)
+
+
 @app.command()
 def bulk_import(
     file_path: str = typer.Argument(..., help="JSON 文件路径，包含笔记数据"),

jfox_cli-0.2.1/jfox/git_extractor.py

@@ -0,0 +1,178 @@
+"""Git 仓库数据提取模块
+
+从本地 Git 仓库提取 commit 历史，转换为结构化数据。
+"""
+
+import logging
+import subprocess
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+# git log block 分隔符
+_COMMIT_DELIMITER = "---COMMIT_START---"
+# git log format 模板
+_GIT_LOG_FORMAT = (
+    f"{_COMMIT_DELIMITER}%n" f"Hash: %H%n" f"Subject: %s%n" f"Author: %an%n" f"Date: %ad%n" f"%n%b"
+)
+
+
+def parse_git_log_output(raw: str) -> List[Dict[str, str]]:
+    """
+    解析 git log block 分隔符格式的输出
+
+    Args:
+        raw: git log 原始输出
+
+    Returns:
+        commit 列表，每项包含 hash, subject, author, date, body
+    """
+    if not raw.strip():
+        return []
+
+    commits = []
+    blocks = raw.split(_COMMIT_DELIMITER)
+
+    for block in blocks:
+        block = block.strip()
+        if not block:
+            continue
+
+        commit: Dict[str, str] = {
+            "hash": "",
+            "subject": "",
+            "author": "",
+            "date": "",
+            "body": "",
+        }
+
+        lines = block.split("\n")
+        i = 0
+        body_lines = []
+
+        # Parse header fields
+        for i, line in enumerate(lines):
+            line = line.rstrip()
+            if line.startswith("Hash:"):
+                commit["hash"] = line[5:].strip()
+            elif line.startswith("Subject:"):
+                commit["subject"] = line[8:].strip()
+            elif line.startswith("Author:"):
+                commit["author"] = line[7:].strip()
+            elif line.startswith("Date:"):
+                commit["date"] = line[5:].strip()
+            elif line == "":
+                # Empty line marks end of headers, start collecting body
+                body_lines = lines[i + 1 :]
+                break
+
+        # Join body lines with newlines
+        commit["body"] = "\n".join(body_lines).strip()
+
+        if commit["hash"]:
+            commits.append(commit)
+
+    return commits
+
+
+def extract_commits(repo_path: str, limit: int = 50) -> List[Dict[str, str]]:
+    """
+    从 Git 仓库提取 commit 历史
+
+    Args:
+        repo_path: 仓库路径（支持 Windows / Git Bash 路径）
+        limit: 最大提取条数
+
+    Returns:
+        commit 列表，每项包含 hash, subject, author, date, body
+
+    Raises:
+        ValueError: 路径不是 Git 仓库 或 git 未安装
+    """
+    repo = Path(repo_path).resolve()
+
+    cmd = [
+        "git",
+        "-C",
+        str(repo),
+        "log",
+        f"--format={_GIT_LOG_FORMAT}",
+        "--date=short",
+        f"-{limit}",
+    ]
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+        )
+    except FileNotFoundError:
+        raise ValueError("git 命令未找到，请确认 git 已安装")
+
+    if result.returncode != 0:
+        stderr = result.stderr.strip()
+        raise ValueError(f"git log 执行失败: {stderr}")
+
+    return parse_git_log_output(result.stdout)
+
+
+def commits_to_notes(
+    commits: List[Dict[str, str]],
+    repo_name: Optional[str] = None,
+    repo_path: Optional[str] = None,
+) -> List[Dict[str, Any]]:
+    """
+    将 commit 列表转换为 bulk-import 兼容的笔记格式
+
+    Args:
+        commits: parse_git_log_output 的返回值
+        repo_name: 仓库名称（用于标签），None 时从 repo_path 提取
+        repo_path: 仓库路径（repo_name 为 None 时使用）
+
+    Returns:
+        笔记数据列表，兼容 bulk_import_notes() 输入格式
+    """
+    if not commits:
+        return []
+
+    if not repo_name:
+        if repo_path:
+            repo_name = Path(repo_path).resolve().name
+        else:
+            repo_name = "unknown"
+
+    notes = []
+    for c in commits:
+        short_hash = c["hash"][:7]
+
+        # 清理 body：去掉 Co-authored-by 行和末尾空行
+        body = c.get("body", "")
+        body_lines = [
+            line
+            for line in body.split("\n")
+            if line.strip() and not line.strip().lower().startswith("co-authored-by:")
+        ]
+        clean_body = "\n".join(body_lines).strip()
+
+        content_parts = [
+            f"Commit: {short_hash}",
+            f"Author: {c['author']}",
+            f"Date: {c['date']}",
+        ]
+        if clean_body:
+            content_parts.append("")
+            content_parts.append(clean_body)
+
+        notes.append(
+            {
+                "title": c["subject"],
+                "content": "\n".join(content_parts),
+                "tags": [f"source:{repo_name}", "source:git-log"],
+            }
+        )
+
+    return notes

{jfox_cli-0.2.0 → jfox_cli-0.2.1}/jfox/performance.py

@@ -251,6 +251,10 @@ def bulk_import_notes(
                 documents = [f"{n.title}\n{n.content}" for n in notes]
                 embeddings = backend.encode(documents).tolist()
 
+                # 确保 VectorStore 已初始化
+                if vector_store.collection is None:
+                    vector_store.init()
+
                 # 批量添加到 ChromaDB
                 ids = [n.id for n in notes]
                 metadatas = [

{jfox_cli-0.2.0 → jfox_cli-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "jfox-cli"
-version = "0.2.0"
+version = "0.2.1"
 description = "JFox - Zettelkasten 知识管理 CLI 工具"
 readme = "README.md"
 license = {text = "MIT"}