Sancho Fetch

Sancho Fetch

向 AI 索取公开数据。将真实文件下载到你的电脑上。

最快的入门方式：告诉你的 AI

打开 AI 的代码模式——Claude 桌面应用 -> Code 标签页，或 ChatGPT 桌面应用 -> Codex——选择任意文件夹，然后粘贴以下内容：

从 PyPI 安装 Sancho Fetch（uv tool install sancho-fetch），并在这台电脑上完成设置。如果尚未安装 uv，请告诉我，然后先安装它。完成后，告诉我安装是否成功。接着用通俗易懂的语言、不要使用术语，说明 .env 文件是什么、如何使用、它在我电脑上的什么位置，然后帮我打开它，这样我就可以直接把 API 密钥粘贴进去。举几个需要免费 API 密钥的数据源示例，再举几个不需要密钥的数据源示例。告诉我下载的数据会保存在哪里，以及之后如何更新 Sancho。然后用 World Bank 运行一个简短的数据获取示例，让我看看数据保存在哪里。最后，给我几个可以用自然语言告诉你来获取数据的示例，让我大致了解如何使用 sancho-fetch，并提醒我：1）只要在 LLM 桌面应用的 Code 标签页中，就可以在任何地方使用它（例如 ChatGPT Desktop 或 Claude Desktop）；2）我可以让 AI 自行添加新的数据源，因为 sancho-fetch 的设计便于扩展（也就是说，可以为它添加更多数据源，而 AI 会帮我完成大部分工作并连接新的数据源）。

安装就这么简单。

你不需要下载或克隆此仓库。AI 会运行以下两条命令：

uv tool install sancho-fetch
sancho setup

安装一次，随处使用。 Sancho 只需在电脑上安装一次，就会连接它找到的 AI 应用（Claude Desktop、ChatGPT/Codex、VS Code、Cursor）。设置完成后，它会清楚地告诉你哪些应用已准备就绪，哪些只需重启或点击一下。

要使用 Sancho，只需用通俗易懂的语言请求数据并提到“sancho”，或者在 Claude Code 中输入 /sancho，体验一下酷炫的感觉。

它能做什么

• 在 AI 的 Code 模式中提出请求：“获取俄亥俄州县级哮喘发病率。” 你可以在任意文件夹中工作——Sancho 始终知道自己的主文件夹在哪里。
• AI 会使用 Sancho 从 120 多个公共数据源（Census、World Bank、FDA、USGS、FEMA 等）获取数据，并为你提供一个可在 Excel 中打开的文件。
• 所有内容都保存在你的电脑上。

开始之前

通常需要先安装 uv。uv 会在隔离环境中安装 Sancho，并可获取兼容版本的 Python，而不会替换电脑上的系统 Python。首次设置需要联网。安装或运行 World Bank 示例不需要 API 密钥；之后可以添加特定数据提供方所需的密钥。

开始使用（约 2 分钟）

直接从 PyPI 安装。

1. 打开 AI 的代码模式。

• Claude： Claude 桌面应用 -> Code 选项卡 -> 新建会话 -> 选择一个你想存放数据的文件夹。
• ChatGPT： ChatGPT 桌面应用 -> Codex -> 打开该文件夹。

2. 粘贴本页顶部的安装请求。

AI 会安装所有内容，向你展示第一个数据文件，并带你了解所有文件的存放位置。

**3. 重启 Sancho 要求你重启的应用。**设置完成时会显示一份简短报告；如果某个应用需要重启或额外点击一次，它会用直白的措辞告诉你。

注意：使用前，请确保为你想使用的数据源添加 API 密钥。

许多数据源无需密钥（World Bank、USGS、FEMA、openFDA 等）。需要 API 密钥时，AI 会告诉你。 你可以：

1. 在 sancho-workspace 文件夹中打开 .env 文件，并将密钥粘贴到其中；或
2. 让 AI 为你打开密钥文件（sancho env open）。将密钥粘贴到打开的文件中，不要将密钥粘贴到聊天中。

设置通常会根据 .env.example 创建 .env。如果缺少 .env，sancho env open 会创建并打开它。要手动执行此操作，请在同一文件夹中复制 .env.example，保留原始模板，并将副本命名为 .env。

这两个文件都可能是隐藏文件：

• **macOS Finder：**按 Cmd+Shift+.（Command + Shift + 句点）。
• **Windows 文件资源管理器：**选择 查看 -> 显示 -> 隐藏的项目。

@开发者，供参考：Sancho 的设计是只读取密钥名称，不读取密钥值。

更倾向于使用 GitHub 仓库，或不通过 AI 应用安装？

如需贡献代码、开发自定义模块或离线安装，请改为在仓库文件夹中操作。安装免费的 GitHub Desktop，然后在此 仓库页面点击 Code -> Open with GitHub Desktop -> Clone。

注意：不要将 Github 文件夹放在 iCloud/OneDrive 内的文件夹中（例如 iCloud 中的 Documents 文件夹）。这会导致文件同步和速度方面的问题。

然后双击 installers/Install Sancho.command（macOS）或 installers/Install Sancho.bat（Windows）；在 Linux 上运行 bash installers/setup.sh。

• macOS 会阻止首次打开（安装程序未经公证）：系统 设置 -> 隐私与安全性 -> 滚动到被阻止文件的提示 -> 仍要打开 -> 再次打开。
• Windows：在显示“Windows 已保护你的电脑”时，点击 更多信息 -> 仍要运行。

日常使用

• 在 Claude Code / Codex 中，只需请求数据。在 Claude Code 中，你也可以直接输入 /sancho 和 /sancho-update。

**安装后，请使用 Code 会话。**Sancho 安装在整台电脑上，因此后续会话无需添加 sancho-fetch 文件夹。在 Claude Desktop 中，选择 Code 选项卡。在 Codex 中，开始 Code 聊天。普通聊天无法访问本地安装的 Sancho。

• 系统指令会让 Sancho 返回每次数据获取的非技术性详情。如果你想让它返回这些技术详情，请告诉 AI：

“开启 Sancho 开发者模式。”

• 遇到问题？让 AI 运行 sancho ready——它会检查你的设置并报告问题，不会更改设置。要实际修复问题，请让 AI 运行 sancho doctor --fix。

文件存放位置

your folder/
  sancho-downloads/    # <-- files you have downloaded via chatting with AI
  sancho-workspace/
    source/            # managed data modules
    custom/            # your own modules -- never overwritten when updating Sancho
    playbooks/         # your repeatable workflows
    fetched-data/      # faithful archive of every fetch (don't edit - this is a cache so we don't have to use API calls unnecessarily)
    analysis-data/     # your derived work
    outputs/           # reports, dashboards, exports
    logs/              # what Sancho did, when, and why
    update-backups/    # snapshots before every update
    .env               # your API keys (never logged, never printed)

每次获取数据都会在你当前工作的文件夹中的 sancho-downloads/ 写入一个可打开的工作文件，并在 sancho-workspace/fetched-data/ 中保存一份忠实的归档/缓存副本，以便重复请求时复用缓存数据。

表格会以 Excel .xlsx 格式提供，像 01003 这样的代码会保持原样；地图仍为 GeoJSON/KML；不会以任何会导致信息丢失的方式进行转换。文件名以日期开头： 2026-06-08_194211_alabama-population.xlsx。

添加自己的数据源

告诉你的 AI：

为 [该 API / 该机构的数据 / 我每月收到的这个文件] 创建一个 Sancho 模块。

它会在 custom/ 下创建，使用方式与内置数据源相同，而且 Sancho 更新不会覆盖此文件夹。

一个很好的例子是，Sancho 会从华盛顿特区和纽约市的开放数据门户获取数据，这些门户使用通用的 API/开放数据门户格式。你可以让 AI 为其他城市创建模块，它会自行智能判断新城市是否使用相同格式；如果是，就会复用相同的模块代码格式，否则会创建一个新模块。你可能会惊讶地发现，有这么多城市使用相同的格式，所以如果你正在处理 Sancho 内置模块尚未覆盖的地理区域，不妨试试看。

更新

只需告诉你的 AI：

更新 Sancho。

AI 会从 PyPI 升级 sancho 命令（uv tool upgrade sancho-fetch）， 然后安全地迁移你的工作区，并提供备份和回滚命令。

如果你是从 GitHub 仓库运行？在 GitHub Desktop 中：Fetch origin -> Pull origin，然后告诉你的 AI “更新 Sancho。”

更新时，你自己的文件（custom/、playbooks/、fetched-data/、.env、 ……）绝不会被触碰。

如果你不希望 Sancho 在聊天中提及新版本（它每两周会提及一次），只需在 .env 中设置 SANCHO_UPDATE_NUDGE=false 即可关闭此功能。

卸载

与安装相同：在 Code 会话中向你的 AI 粘贴一条请求：

从这台电脑卸载 Sancho Fetch：运行 sancho uninstall，然后运行 uv tool uninstall sancho-fetch。保留我的 sancho-workspace 和 sancho-downloads 文件夹——里面是我的数据和 API 密钥。完成后告诉我 已移除的内容。

（如果你愿意自己运行，这两条命令就能完成全部卸载。）

Sancho 只会移除它安装的内容：其技能及其在你的 AI 应用中的条目。任何由你编辑或创建的内容都会保留，并在报告中列出。

你的 sancho-workspace/ 文件夹（获取的数据、自定义模块、.env 密钥）和 sancho-downloads/ 文件始终会被保留。删除数据是一个单独且需要明确执行的步骤，并会先要求确认——请询问你的 AI，或运行 sancho uninstall --help 查看操作方法。

隐私政策

Sancho 在你的电脑上运行，并将数据保存在本地。数据获取请求会从你的设备直接发送到你选择的公共数据提供方；API 密钥从本地 .env 读取，且只会发送给该提供方。Sancho 不收集遥测数据。详情请见：docs/PRIVACY.md。

更多文档

• CHANGELOG.md -- 各版本的变更内容。
• README_ALL_INSTRUCTIONS.md -- 完整的操作人员/AI 参考文档。
• project-docs/MCP_SERVER_SETUP_CLAUDE_CHATGPT_WEB.md -- 桌面和 Web 客户端的 MCP 设置详情。
• project-docs/MODULE_CREATION_GUIDE.md -- 你的 AI 如何构建新的数据模块。

托管你自己的 Sancho 版本

虽然 Sancho 的设计用途是在你自己的电脑上运行，但你也可以将它托管在服务端，让用户通过 Web 访问，而无需使用 Claude/Codex 桌面应用。

托管的主要目的是支持组织为用户举办实践工作坊，这些用户可能不具备在自己的电脑上安装 Sancho 所需的技术能力。

• hosting/README.md -- 活动专用的托管演示端点。

致 AI 助手

如果你是 AI 助手，请勿依据此快速入门指南进行操作。请阅读 README_ALL_INSTRUCTIONS.md，然后遵循 CLAUDE.md 或 AGENTS.md。

许可证

代码根据 MPL 2.0 许可；文档根据 CC BY 4.0 许可，另有说明的除外。Sancho 名称、徽标和品牌资产受单独保护——请参阅 LICENSE、NOTICE、LICENSE-DOCS.md 和 INTENDED_USE.md。