Ehsas317/people-helper

# 人员 Helper [](https://www.python.org/downloads/) [](https://opensource.org/licenses/MIT) [](#testing) People Helper 会读取你的 GitHub 仓库（始终为只读），识别出值得提取的独立组件，验证它们是否确实能独立运行，在 GitHub 上搜索类似项目，并生成一份包含评分、差异化分析和建议名称的结构化报告。使用 `--extract` 参数，它还可以将文件复制出来并生成包的基础脚手架（pyproject.toml、package.json、Cargo.toml、go.mod、README、LICENSE-REVIEW.md、SOURCE-LICENSE）。 ## 它的功能（与局限性） **功能：** - 发现你仓库中可提取的代码 - 验证其是否真正独立（相对导入、同级文件解析、缺失同级文件拦截） - 从 6 个维度（代码质量、实用性、独特性、相关性、可维护性、需求度）对候选对象进行评分 - 在 GitHub 上搜索类似项目，以评估需求和独特性 - 生成结构化的 Markdown 报告 - 使用 `--extract`：复制出文件，保留源版权声明，生成包的脚手架，将源 LICENSE 复制为 SOURCE-LICENSE，生成 LICENSE-REVIEW.md 引导你了解 5 种许可证情况 **局限性：** - 不会为你编写测试 - 不会自动调整导入（你需要审查并修复） - 不会发布到 PyPI/npm/crates.io - 无法很好地处理存在跨包依赖的 monorepo（单体仓库） - 不会自动分配许可证（你 MUST 进行审查并选择 — 参见 LICENSE-REVIEW.md） ## 快速开始 ``` pipx install people-helper export PEOPLE_HELPER_PAT=github_pat_your_token_here people-helper --repo your-username/your-repo ``` 或者从源码运行： ``` git clone https://github.com/Ehsas317/people-helper.git cd people-helper python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -e . people-helper --repo your-username/your-repo ``` ## 局限性 在使用前请注意以下几点： 1. **所有 13 种语言均支持圈复杂度计算。** Python 使用基于 AST 的复杂度计算（最准确）。其他语言使用基于正则表达式的复杂度计算（统计 if/for/while/case/catch/&&/||/? 的数量 —— 这是一种近似方法，但评分相对公平）。扇入（Fan-in）和导入循环检测仅支持 Python。 2. **大型仓库（>5万 个文件）可能会很慢。** 该工具会遍历每个文件。对于拥有 15万+ 个文件的仓库（如 gcc、Azure SDK），建议使用 `--language` 进行过滤。 3. **语言检测遵循 GitHub linguist 规则**（按代码行数统计）。像 numpy 这样的仓库会被识别为 C 语言（C 扩展代码比 Python 代码多），尽管它是一个“Python 库”。这是正确的行为，但可能会让你感到意外。 4. **`--extract` 功能生成的是一个起点，而不是一个完整的包。** 源码的版权头信息会被保留（这是大多数许可证的要求）。工具会生成一个 LICENSE-REVIEW.md 文件 —— 在发布前，你 MUST 确定正确的开源许可证。源仓库的 LICENSE 文件将被复制为 SOURCE-LICENSE 供参考。你仍然需要审查代码、调整导入、添加测试并验证编译。 5. **GitHub Search API 的速率限制**为**已验证身份的请求每分钟 30 次**（与未验证身份的请求相同）。Core API 的限制是每小时 5000 次，但 Search API 要低得多。对于大规模分析，请使用 `--no-network` 并单独运行搜索。当受到速率限制时，工具会返回中性的独特性得分（5.0），而不是具有误导性的“真正独特”得分 8.0。 ## 工作原理 ``` Your repo │ ▼ ┌────────────────┐ ┌────────────────────┐ ┌─────────────────────┐ │ Shallow clone │───▶│ Detect files │───▶│ Verify extraction │ │ (read-only) │ │ that pass │ │ • relative imports │ └────────────────┘ │ extractable │ │ • sibling resolve │ │ heuristics │ │ • license present │ └────────────────────┘ └──────────┬──────────┘ │ ┌────────────────────┐ ┌─────────────────────┐ │ │ Markdown report │◀───│ Score candidates │◀──────────┘ │ • 6 dimensions │ │ 6 dimensions, │ │ • Extraction type │ │ verified │ │ • License status │ │ standalone-ness │ │ • Starter code │ └─────────────────────┘ └────────────────────┘ ``` ## 核心问题：“它真的是独立的吗？” 大多数寻找“可提取”代码的工具只是检查启发式条件 —— 如文件大小、导入数量、是否有文档字符串。但是，一个文件可能通过了所有这些检查，但在你提取它的那一刻**仍然会报错**，因为它包含像 `from .utils import helper` 这样的相对导入。 People Helper 会**验证**独立性，而不是仅仅靠猜： | 信号 | 检查内容 | 重要性 | |---|---|---| | **相对导入** | `from . import X`, `from .X import Y`, `./utils`, `super::X` | 这些是结构性依赖 —— 没有同级文件，该文件实际上无法运行 | | **同级文件解析** | 引用的同级文件是否存在于仓库中？ | 如果存在 → 需多文件提取。如果不存在 → 强制拦截（会产生损坏的代码） | | **许可证存在性** | 仓库根目录下是否有 LICENSE/COPYING/UNLICENSE 文件？ | 没有许可证，提取在法律上等同于“保留所有权利” | 每个候选对象都会被标记上一个**提取类型**： - `✅ single` — 验证为独立，无相对导入，可直接按原样提取 - `⚠ multi` — 需要连同同级文件一起提取（在报告中列出） - `⛔ blocked` — 引用了缺失的同级文件，会产生损坏的代码（跳过） ## 评分 共六个维度，均基于完整的文件内容进行计算： | 维度 | 权重 | 衡量标准 | |---|---|---| | **代码质量** | 25% | 有测试 (+2.5)，有文档 (+1.5)，无内部导入 (+1.5)，外部依赖少 (+1.5)，已验证独立 (+1.0)，实用类文件名 (+0.5)，扇入=0 (+0.5)；对高复杂度、循环依赖、无测试无文档扣分 (-1.5)；优秀加分 (+1.0) | | **实用性** | 20% | 通用函数名 (+1.5)，通用文件名 (+1.0)，50-300 行代码 (LOC) (+1.0)，API 数量 ≥3 (+1.0)，仅使用标准库 (+0.5)；对无 API 扣分 (-1.0)，仅代码片段扣分 (-0.5) | | **独特性** | 15% | GitHub 上类似项目越少得分越高（0个结果: 8，1-2个: 6，3-5个: 4，6个以上: 2）。--no-network 模式或被限流：中性得分 5.0 | | **相关性** | 15% | 验证为单文件 (+2.5)，多文件 (-1.5)，仅使用标准库 (+2.0)，API ≥3 (+1.5)，无许可证 (-1.0)，包含特定项目引用 (-2.0) | | **可维护性** | 15% | 注释率 ≥15% (+2.0)，有文档字符串 (+1.0)，低复杂度 (+1.5)，50-200 行代码 (LOC) (+1.0)，有测试 (+0.5) | | **需求信号** | 10% | 类似项目的 Star 数、fork 数和打开的 issue 数（线性封顶，按排名加权） | **计算公式：** `combined = 0.25×quality + 0.20×usefulness + 0.15×uniqueness + 0.15×relevance + 0.15×maintainability + 0.10×demand` 如果 `relevance < 3.0`，总得分将减半 —— 一个并非真正独立的文件是无法仅靠良好的代码质量来挽救的。 ## 安装 ### 选项 A：pipx（推荐用于 CLI 使用） ``` pipx install people-helper ``` ### 选项 B：从源码安装 ``` git clone https://github.com/Ehsas317/people-helper.git cd people-helper python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -e . ``` ### 选项 C：直接运行脚本（无需安装） ``` git clone https://github.com/Ehsas317/people-helper.git cd people-helper pip install -r requirements.txt # only httpx python people_helper.py --repo you/repo ``` **要求 Python 3.10+**（使用了 PEP 604 的 `X | None` 语法）。 ## 设置（仅需一次） 创建一个 **细粒度的 GitHub PAT**： 1. 前往 [github.com/settings/personal-access-tokens/new](https://github.com/settings/personal-access-tokens/new) 2. Resource owner：你自己 3. Repository access：**Only select repositories** → 选择你想要分析的仓库 4. Permissions： - **Contents**：Read - **Metadata**：Read（自动选中） 5. Expiration：90 天或更短 6. 复制 token ``` export PEOPLE_HELPER_PAT=github_pat_your_token_here ``` ### 可选：为提取的包配置作者信息 如果你使用了 `--extract`，生成的清单文件（如 pyproject.toml、package.json 等）会包含作者信息。请设置这些环境变量以避免出现 "Your Name" 占位符： ``` export PEOPLE_HELPER_AUTHOR_NAME="Jane Doe" export PEOPLE_HELPER_AUTHOR_EMAIL="jane@example.com" ``` ## 使用方法 ``` # 基本用法（生成 report.md） people-helper --repo your-username/your-repo # 指定输出路径 people-helper --repo your-username/your-repo --output my-report.md # Verbose 模式（查看每个步骤） people-helper --repo your-username/your-repo --verbose # Debug 模式（在出错时显示 stack traces） people-helper --repo your-username/your-repo --debug # 显示版本 people-helper --version # 仅限本地（不进行 GitHub 搜索，速度更快） people-helper --repo your-username/your-repo --no-network # 按语言筛选（根据支持的语言进行验证） people-helper --repo your-username/your-repo --language Python # 提取热门候选者到 ./extracted/（创建 package scaffolds） people-helper --repo your-username/your-repo --extract ./extracted/ # 使用自定义阈值进行提取 people-helper --repo your-username/your-repo --extract ./extracted/ --max-extract 3 --extract-min-score 7.0 # 控制输出大小 people-helper --repo your-username/your-repo --max-candidates 5 --min-stars 10 ``` 你也可以作为 Python 模块调用： ``` python -m people_helper --repo you/repo ``` 或者在不安装的情况下，通过克隆的仓库运行： ``` python people_helper.py --repo you/repo ``` ## 检测目标 如果一个文件符合以下条件，则被视为**高价值可提取候选对象**： - 至少包含 10 行实际代码（无严格上限 —— 对于大文件会实施阶梯式的可维护性扣分：超过 500 行的部分，每 150 LOC 扣 0.1 分） - 拥有模块级别的 docstring、JSDoc 或包注释 - 包含零个或一个内部项目导入（自包含） - 外部导入很少（依赖占用空间小） - 有对应的测试文件 - 具有实用性质的文件名（如 `util`、`helper`、`parser`、`validator` 等） - **已验证是独立的**（无相对导入，或者对于多文件提取存在同级文件） - **不是**框架的路由文件（如 Next.js pages、SvelteKit routes 等） - **本身不是**测试文件 - **不是** CLI 入口点 - **不是**配置文件、SWIG 输出或声明文件 ## 报告输出 生成的 Markdown 报告会为每个候选对象提供以下信息： - **评分**：包含全部 6 个维度及综合得分 - **提取类型**：`✅ single`、`⚠ multi` 或 `⛔ blocked` - **必需的同级文件**：如果是多文件提取，列出必须一起提取的文件 - **源仓库许可证**：该仓库是否拥有许可证文件 - **功能描述**：从文档字符串或代码中提取 - **可提取的原因**：基于分析得出的确凿理由 - **类似项目**：GitHub 搜索结果，包含 star 数、fork 数和最后提交日期 - **你的差异化优势**：具体的比较点 - **建议名称**：简洁且可发布的包名 - **建议标签**：用于提升发现率的 GitHub topics - **起始脚手架（前 30 行）**：包含自动隐去敏感信息的代码预览 ## 信任边界 People Helper **在设计上是只读的**： - 使用细粒度的 PAT，且仅具有 **Contents: Read** 和 **Metadata: Read** 权限 - 强制拒绝具有写入权限范围（`repo`、`admin:*`、`write:*`、`delete:*`）的经典 PAT - 注意：经典 PAT 的范围会经过严格验证；细粒度 PAT 的范围无法通过 API 进行内部检查，因此用户必须正确遵循设置说明 —— 工具会发出警告但不会强制阻止。 - 无写入操作 —— 没有推送、没有 PR、不创建 issue - 代码保留在你的计算机上；仅调用 GitHub 公开的搜索 API - 每次运行后（包括超时在内的所有失败路径下）都会清理临时克隆 - 克隆完成后，会清除 `.git/config` 中的 PAT（深度防御） - 所有错误消息和异常参数中涉及的 PAT 都会被隐去 - 报告内容经过净化处理：转义了三个反引号，过滤了 `