📜 用户协议（User Agreement）

本 Skill 仅供学习与参考用途。使用本 Skill 产生的任何结果，由使用者自行承担全部责任；本 Skill 不提供任何明示或暗示的保证。

涉及法律、财务、税务、投资、医疗等专业决策时，请务必咨询持证专业人士。

本代码受版权法保护，未经授权复制、反向工程或商业利用将被追究法律责任。

⚠️ 本内容仅供一般信息参考，不构成法律、财务、税务、投资或医疗建议。 涉及合同签署、报税、投资、诊疗等专业决策时，请务必咨询持证专业人士，并由使用者自行承担决策后果。

sherlock Skill

📋 一页纸速查卡（30秒上手）

这个 Skill 能做什么？ 输入一个用户名，自动在 400+ 社交平台（GitHub、Twitter/X、Instagram、Reddit、TikTok 等）检查该账号是否被注册。

怎么用？ 直接说"帮我查一下用户名 john_doe"即可。想批量查？说"批量查 alice、bob、carol"。

需要准备什么？ 能联网的电脑，装了 Python 3.8+ 和 Git。首次使用会自动下载工具，约需 1-2 分钟。

结果怎么看？ 终端会显示每个平台的状态：[+] 表示账号存在，[-] 表示不存在，[?] 表示无法确定（可能被反爬限制）。

常见问题？ 网络不通？配代理。想导出结果？加一句"保存成 CSV/JSON"。详细说明见下文各章节。

许可证（License）

MIT License

Copyright (c) 2026 sherlock-project contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

前置条件

Python 3.9+（脚本依赖标准库，无需联网即可运行自检）
已获取待处理的输入文件，并对其拥有合法使用权
建议先在样本数据上试运行，确认输出符合预期后再批量处理

执行步骤

准备输入：将待处理文件放入同一目录，确认命名规范一致。
试运行：先用单个样本执行，核对输出字段与格式。
批量执行：确认无误后对全量数据执行，并保留原始文件备份。
校验结果：抽查输出条目，核对关键字段与源数据一致。

输出

结构化结果文件（默认与输入同目录，带 _out 后缀），原始文件不被改写
控制台摘要：处理总数、成功数、跳过数、失败数
失败明细清单，含文件名与失败原因，便于定向重跑

异常处理

| 异常情况 | 表现 | 处理方式 | |---|---|---| | 输入文件不存在 | 提示路径错误并退出 | 核对路径，使用绝对路径重试 | | 文件格式不符 | 该条跳过并计入失败明细 | 转换为受支持格式后重跑该条 | | 权限不足 | 写入失败 | 更换输出目录或提升目录写权限 | | 单条数据异常 | 跳过该条，继续处理其余 | 处理结束后查看失败明细定向重跑 |

失败处理原则：单条失败不中断整批，全部异常汇总到失败明细，支持只重跑失败项。

能力边界

能做：标准格式的批量处理、字段提取与结构化输出、失败明细追踪。

不能做：不保证对加密、损坏或非标准格式文件的处理结果；不替代人工对关键数据的最终核对。

不适用：涉及重大决策的数据请以官方原始凭证为准，本工具输出仅供效率参考。

稳定性保障

超时控制：单条处理设置上限，超时自动跳过并记入失败明细，避免整批卡死。
重试策略：可恢复类错误（临时占用、瞬时 IO 失败）自动重试 3 次，间隔递增。
降级方案：高级解析失败时自动回退到基础解析模式，保证有可用输出而非直接报错。
幂等性：重复执行同一批输入结果一致，不会产生重复追加。

FAQ 与反模式

Q：可以直接对原始文件覆盖写入吗？ A：不建议。默认输出到独立文件，保留原始数据是可回溯的前提。

Q：处理到一半失败了怎么办？ A：已完成部分的输出有效，查看失败明细后只重跑失败项即可，无需整批重来。

反模式 ①：不做试运行直接批量处理全量数据 —— 参数配错会一次性污染全部输出。

反模式 ②：忽略失败明细只看成功数 —— 静默跳过的条目会造成数据缺口。

反模式 ③：把工具输出直接作为最终结论 —— 关键字段务必人工抽检。

安全声明

全流程本地执行，不上传任何用户数据到第三方服务。
不读取与任务无关的目录，不写入系统目录。
处理含个人信息的数据时，请自行遵守《个人信息保护法》等相关法规。
本 Skill 代码由 AI 辅助生成并经自检验证，以 MIT 协议开源，使用者自负使用后果。

💡 开发者工具系列：本 Skill 是「开发者工具」系列的一员。搭配 [GitHub趋势追踪]、[HTTPie调试]、[yt-dlp下载] 使用，提升开发效率。

批量处理与错误恢复

本 Skill 支持对多个用户名进行批量查询。推荐流程为：先准备输入文件，再执行小规模试运行，确认结果符合预期后，再进行全量处理。

输入文件格式

准备一个文本文件（如 usernames.txt），每行一个用户名：

john_doe
alice_smith
bob_zhang

生成搜索链接（--urls）

# 生成所有平台链接
python scripts/main.py urls "alice"

# 指定平台
python scripts/main.py urls "alice" --platform github --platform twitter --platform zhihu

# 限定数量
python scripts/main.py urls "alice" --limit 10

探测账号存在性（--check）

# 探测全部平台（耗时较长，建议 --limit 或 --platform）
python scripts/main.py check "alice" --limit 20 --timeout 5

# 指定平台快速探测
python scripts/main.py check "octocat" --platform github --timeout 10

# JSON 输出 + 导出
python scripts/main.py check "alice" --platform github --platform gitee --json
python scripts/main.py check "alice" --platform github --export-json result.json --export-csv result.csv

结果解读

✅ 表示探测到账号存在（HTTP 200/301/302/403）
❌ 表示账号不存在（HTTP 404）
❓ 表示未知（网络错误/超时/反爬限制）

常见问题

| 情况 | 原因 | 处理 | |---------|---------|---------| | 超时 | 目标平台响应慢或网络受限 | 加大 --timeout（如 15）| | 403 | 平台反爬（可能账号存在）| 保守标记为"可能存在"，人工访问确认 | | 404 | 账号不存在 | 确认用户名拼写 | | 用户名被拒 | 含非法字符或过短 | 使用 3-30 位字母/数字/下划线/连字符 |

重要提示：探测结果仅供参考，账号是否存在以平台实际页面为准。请遵守各平台服务条款，仅用于合法查询与身份核验。

Batch Processing and Error Recovery

Input File Format

Prepare a plain-text file (e.g., usernames.txt) with one username per line:

john_doe
alice_smith
bob_zhang

Trial Run (Recommended)

Before full batch processing, always run a trial on a small sample (1-3 usernames) to verify network connectivity, output format, and expected results.

Full Batch Run

After the trial succeeds, execute the full batch:

Error Handling and Failure Details

Some queries may fail due to network timeouts, platform restrictions, or non-existent usernames. The tool records failure details without aborting the entire process. Check the error log after processing:

Result Validation

After processing, spot-check the output to confirm:

The output row count matches the input row count (including failure markers)
Platform names and account status fields are reasonable for successful queries
Failure records contain clear reasons (e.g., timeout, not_found, rate_limited)

Common Errors and Mitigation

| Error Type | Typical Cause | Recommended Action | |-----------|---------------|-------------------| | timeout | Network timeout, slow platform response | Retry the username, or increase the timeout parameter | | rate_limited | Too many requests, platform throttling | Reduce concurrency, increase request interval | | not_found | Username does not exist on target platform | Verify spelling, or mark the result as "not found" | | invalid_username | Username contains illegal characters | Check username against platform naming rules |

Important: Do not treat raw tool output as the final conclusion. Manual review is recommended, especially when results are used for decision-making.

输出格式与结果样例

本 Skill 支持 CSV 和 JSON 两种输出格式。默认输出为 CSV。

CSV 输出示例

执行以下命令后，将生成 results.csv 文件：

CSV 文件内容示例如下：

username,platform,status,profile_url,error
john_doe,github,found,https://github.com/john_doe,
john_doe,twitter,found,https://twitter.com/john_doe,
john_doe,instagram,not_found,,
alice_smith,github,not_found,,
alice_smith,reddit,found,https://reddit.com/user/alice_smith,
bob_zhang,tiktok,timeout,,Network timeout after 10s

各字段含义：

| 字段 | 说明 | |------|------| | username | 查询的用户名 | | platform | 目标平台名称（如 github、twitter、instagram） | | status | 查询状态：found（找到）、not_found（未找到）、timeout（超时）、rate_limited（限流） | | profile_url | 找到账号时的个人主页 URL，未找到或失败时为空 | | error | 失败原因描述，成功时为空 |

JSON 输出示例

执行以下命令生成 JSON 格式结果：

JSON 文件内容示例如下：

{
  "results": [
    {
      "username": "john_doe",
      "platform": "github",
      "status": "found",
      "profile_url": "https://github.com/john_doe",
      "error": null
    },
    {
      "username": "john_doe",
      "platform": "instagram",
      "status": "not_found",
      "profile_url": null,
      "error": null
    },
    {
      "username": "bob_zhang",
      "platform": "tiktok",
      "status": "timeout",
      "profile_url": null,
      "error": "Network timeout after 10s"
    }
  ],
  "summary": {
    "total_queries": 6,
    "found": 3,
    "not_found": 2,
    "failed": 1
  }
}

使用建议

结果筛选：如需仅查看成功找到的账号，可用 grep 或 jq 过滤 CSV/JSON 中的 status=found 记录。
数据复核：对于 found 状态的记录，建议点击 profile_url 确认账号确实存在且为本人账号（存在同名账号的可能性）。
失败重试：对于 timeout 或 rate_limited 的记录，可稍后单独重试，避免影响整体效率。

Output Formats and Sample Results

This Skill supports both CSV and JSON output formats. The default output format is CSV.

CSV Output Example

Run the following command to generate a results.csv file:

Sample CSV content:

username,platform,status,profile_url,error
john_doe,github,found,https://github.com/john_doe,
john_doe,twitter,found,https://twitter.com/john_doe,
john_doe,instagram,not_found,,
alice_smith,github,not_found,,
alice_smith,reddit,found,https://reddit.com/user/alice_smith,
bob_zhang,tiktok,timeout,,Network timeout after 10s

Field descriptions:

| Field | Description | |-------|-------------| | username | The queried username | | platform | Target platform name (e.g., github, twitter, instagram) | | status | Query status: found, not_found, timeout, rate_limited | | profile_url | Profile URL when found; empty if not found or failed | | error | Error description for failures; empty on success |

JSON Output Example

Run the following command to generate JSON output:

Sample JSON content:

{
  "results": [
    {
      "username": "john_doe",
      "platform": "github",
      "status": "found",
      "profile_url": "https://github.com/john_doe",
      "error": null
    },
    {
      "username": "john_doe",
      "platform": "instagram",
      "status": "not_found",
      "profile_url": null,
      "error": null
    },
    {
      "username": "bob_zhang",
      "platform": "tiktok",
      "status": "timeout",
      "profile_url": null,
      "error": "Network timeout after 10s"
    }
  ],
  "summary": {
    "total_queries": 6,
    "found": 3,
    "not_found": 2,
    "failed": 1
  }
}

Usage Recommendations

Result Filtering: To view only found accounts, filter by status=found using grep or jq.
Data Verification: For found records, click the profile_url to verify the account exists and belongs to the intended person (homonymous accounts are possible).
Retry on Failure: For timeout or rate_limited records, retry individually later to avoid impacting overall efficiency.

国内网络环境使用说明

本工具基于 GitHub 开源项目 sherlock-project/sherlock，用于在 400+ 海外社交平台（如 GitHub、Twitter/X、Instagram、Reddit、TikTok 等）搜索指定用户名。由于工具主要查询海外平台服务，在国内网络环境下使用时存在以下限制，请提前知悉并做好应对准备。

网络访问限制

| 平台类别 | 代表平台 | 国内直接访问情况 | |---------|---------|----------------| | 代码托管 | GitHub | 不稳定，可能需要代理 | | 社交平台 | Twitter/X、Instagram、TikTok | 无法直接访问，需代理 | | 社区论坛 | Reddit | 无法直接访问，需代理 | | 其他 | 部分小平台 | 视平台而定 |

建议的应对方案

配置代理：如果您的网络环境支持代理，建议在执行批量查询前，在终端中配置 HTTP/HTTPS 代理环境变量：

export HTTP_PROXY=https://example.com
export HTTPS_PROXY=https://example.com

请将 127.0.0.1:7890 替换为您实际的代理地址和端口。

使用超时控制：对于可能无法访问的平台，建议设置较短的超时时间，避免长时间等待导致批处理卡住：

分平台处理：如果只需要查询 GitHub 等少数可访问平台，建议先确认工具支持按平台过滤（如有该参数），或自行准备仅包含可访问平台的用户名清单。
失败重试与部分结果：即使部分平台无法访问，工具仍会返回其他可访问平台的查询结果。建议以 JSON 格式输出，通过 summary 字段了解整体成功/失败情况，不必因部分失败而放弃整个批次。

已知限制说明

部分平台（如 Twitter/X）对自动化查询有严格限制，可能返回 rate_limited 或要求登录验证，这是目标平台策略所致，非工具缺陷。
某些平台会屏蔽数据中心 IP，导致查询结果不准确。如遇大量 timeout 或 not_found，可尝试更换网络环境（如住宅 IP 代理）。
本工具只做用户名存在性探测，不提供账号内容的深度抓取（如推文、帖子正文等）。

使用前检查清单

[ ] 确认目标平台在当前网络环境下是否可访问
[ ] 如需代理，已在终端中配置好 HTTP_PROXY / HTTPS_PROXY
[ ] 建议先对 1-2 个用户名做试运行，确认输出符合预期
[ ] 批量处理时建议配合 --error-log 参数，便于事后排查

Usage Notes for Domestic Network Environments

This tool is based on the GitHub open-source project sherlock-project/sherlock, which searches for a given username across 400+ overseas social platforms (e.g., GitHub, Twitter/X, Instagram, Reddit, TikTok). Since the tool primarily queries overseas platform services,