简体中文 | English

FactReach

让 Agent 先查，再答；有证据，再下结论。
23 个渠道：全网搜索 · X · 小红书 · 抖音 · 微博 · B站 · YouTube · Reddit · Facebook · Instagram · LinkedIn · GitHub
GitHub Trending · Hacker News · 微信公众号 · 学术论文 · Stack Overflow · 小宇宙 · V2EX · 雪球 · RSS · Exa 语义搜索 · 网页读取
零鉴权优先 · 动态网页 · 真实 Chrome · 系统级实证规则

为什么需要 · 核心能力 · 快速开始 · 支持渠道 · 安全边界 · 更新日志

寻找深圳的 AI 工作机会

作者目前正在寻找深圳的 AI 相关工作机会，重点关注腾讯等大型科技企业及金融机构的 AI 投研产品、FDE 与 AI 咨询 / 解决方案岗位。

兼具金融机构从业经历与 AI 产品实战，持续构建金融市场数据工具和多智能体系统，开源项目累计获得 17K+ GitHub Stars。

联系：[email protected]

为什么需要 FactReach

Agent 能写代码、做分析，却经常在现实信息上直接依赖模型记忆：数据已经变化、页面需要登录、动态内容抓不到，最终仍可能给出语气确定但缺乏证据的答案。

FactReach 把这个问题拆成两层：

1. 行为层：把“外部事实必须先搜索、交叉验证”写进 CLAUDE.md 或 AGENTS.md。
2. 能力层：为 Agent 提供 23 个渠道、多后端、按轻重分层的搜索与读取路线。

Skill 只有在 Agent 已经决定调用它之后才生效，因此不能代替系统级规则。FactReach 提供可预览、可检测、显式授权后才写入的 policy 命令，把这条边界讲清楚。

核心能力

快速开始

把下面这句话交给支持 Shell 的 AI Agent：

帮我安装 FactReach：https://raw.githubusercontent.com/simonlin1212/FactReach/main/docs/install.md

也可以手动安装：

# 如果用 pipx 装过 Agent-Reach，执行：pipx uninstall agent-reach
# 如果同一 Python 环境用 pip 装过，执行下面这条。
# 这不会删除 ~/.agent-reach/ 里的配置、Cookie 或 Token。
python -m pip uninstall agent-reach
pipx install https://github.com/simonlin1212/FactReach/archive/main.zip

# 默认只检查，不修改系统
factreach install --env=auto

# 明确允许安装外部依赖后再执行
factreach install --env=auto --system

# 查看 23 个渠道当前状态
factreach doctor --json

如果使用虚拟环境：

python3 -m venv ~/.factreach-venv
source ~/.factreach-venv/bin/activate
pip install https://github.com/simonlin1212/FactReach/archive/main.zip
factreach doctor

不要在同一个 Python 环境并排安装 agent-reach 和 factreach：二者为兼容旧用户
共享 agent_reach 模块。迁移时先卸载旧发行包，再安装 FactReach；配置目录会保留。

完整安装边界与可选渠道见 安装指南。

让 Agent 先搜索再回答

搜索前置规则必须放在 Agent 启动时读取的系统指令文件中：

• Claude Code：全局 ~/.claude/CLAUDE.md，或项目内 CLAUDE.md
• Codex：全局 ~/.codex/AGENTS.md，或项目内 AGENTS.md

先预览和检查：

factreach policy --show
factreach policy --check --target both --scope user

只有在用户明确授权后才写入：

factreach policy --install --target both --scope user

卸载只移除 FactReach 管理的标记块，不覆盖其他系统提示：

factreach policy --uninstall --target both --scope user

支持渠道

注册表按独立能力计为 23 个渠道。实际可用状态取决于本机依赖和登录态，始终以 factreach doctor --json 为准。

鉴权层级

需要 Cookie 或登录态的平台建议使用专用账号。自动化访问可能触发平台限制；FactReach 不替用户登录，也不会静默扫描浏览器 Cookie。

当前小红书后端顺序为 OpenCLI → xiaohongshu-mcp → xhs-cli。Twitter Cookie 写入兼容配置后只供 Doctor 检查；直接调用 twitter 命令时，当前进程仍需显式提供 TWITTER_AUTH_TOKEN 和 TWITTER_CT0，不得把凭据写进命令行或公开日志。

网页读取路线

普通公开页
  └─ Jina Reader
       └─ 动态渲染失败 → Firecrawl
            └─ 必须登录或交互 → browser-harness（显式选择）

示例：

factreach web read "https://example.com"
factreach web read "https://example.com" --backend firecrawl
factreach web read "https://example.com" --backend browser-harness

factreach douyin resolve "抖音分享文本或链接"
factreach douyin resolve "抖音分享文本或链接" --transcribe

安全边界

• 默认 factreach install 只检查环境；--system 才允许系统级安装和配置写入。
• Cookie、Token 继续存放在兼容目录 ~/.agent-reach/，权限限制为当前用户，不上传仓库。
• browser-harness 为每次读取创建隔离的 daemon、BrowserContext、target 与 CDP session。
• 真实浏览器请求经过公共 DNS 固定代理，并阻断私网、回环、DNS rebinding、弹窗和子 worker 越界访问。
• 输出前清理 URL 凭据和敏感字段；doctor 不通过读取浏览器 Cookie 来伪装后端可用。
• --dry-run 可预览安装和卸载动作。

安全问题请通过 GitHub Private Vulnerability Reporting 私下提交，不要公开 Issue。详见 SECURITY.md。

兼容性

FactReach 延续 Agent-Reach 的配置与命令兼容性。为了不破坏已有安装：

• 主命令为 factreach，同时保留 agent-reach 兼容入口。
• Python 内部模块暂时保留 agent_reach，并新增 FactReach 类别名。
• 原有 ~/.agent-reach/ 配置和凭据继续生效，不自动搬迁。
• 新 Skill 安装目录为 factreach，避免与原有 Skill 混淆。

架构

factreach CLI
├── policy        系统级实证规则
├── doctor        23 渠道状态与后端探测
├── channels      平台能力契约
├── backends      OpenCLI / Firecrawl / browser-harness
├── config        本地凭据与安全写入
└── skill         Agent 路由说明与参考文档

每个平台都有有序后端列表。后端失效时可以调整路由，不必重写整个渠道。

致谢

感谢 Panniantong/Agent-Reach 及其贡献者提供的开源基础。版权、许可与第三方组件归属完整保留在 LICENSE 和 NOTICE。

参与贡献

提交代码前请运行：

pytest -q
ruff check agent_reach tests
mypy agent_reach
python -m build

贡献规范见 CONTRIBUTING.md。安全问题请走私密报告渠道。

免责声明

FactReach 只提供公开信息检索、用户授权会话路由和本地工具配置能力，不保证第三方平台接口永久可用。使用者需要遵守目标网站的服务条款、当地法律及账号规则，并自行承担自动化访问、Cookie 使用和第三方服务费用风险。

赞赏

如果 FactReach 节省了检索和配置时间，可以请作者喝杯咖啡。

License

MIT License

作者： Simon 林 · X @linsizhen · 邮箱：[email protected]