@tom_doerr: 构建私有公司知识库 https://github.com/agno-agi/scout

构建私有公司知识库 https://t.co/Z75LWo1aPj https://t.co/ChxoOaDCc6 — # agno-agi/scout 来源：https://github.com/agno-agi/scout # Scout：企业情报智能体 Scout 是一个开源的企业情报智能体。它能够浏览实时信息源（网页、Slack、云盘、Wiki、CRM、MCP 服务器），按需整合上下文——并且在了解你公司的过程中，自动构建自己的 Wiki 和 CRM。 YC 2026 夏季 RFS 中提到的“公司大脑”和“公司 AI 操作系统”正是从两个角度阐述了同一理念：将分散在碎片化源中的知识提取出来，转化为 AI 可以操作的形式。大脑是数据层，操作系统运行其上。目前这两者都尚未有成型的产品，但组成它们的模块已经存在。Scout 利用已有的成熟模式将它们拼接在一起：导航优于搜索、上下文提供者、智能体化 SQL 以及持久化记忆。 导航优于搜索。 处理知识源时，默认做法通常是将所有内容摄入向量数据库、分块、嵌入然后祈祷。这有很多原因导致效果不佳。编码智能体找到了正确的方法：它们会导航——ls、grep、打开文件、跟踪导入。Scout 在 Slack、云盘以及其他源上也采用同样的方式。 Scout 维护自己的 Wiki 和 CRM。 在与你协作过程中，Scout 学到的大部分信息都适合放入 Wiki 和 CRM。例如 “Anthropic 的 Josh 分享了一篇新的 RLM 论文”，Scout 会将 Josh 添加到 CRM 中，将论文解析到 Wiki 里，并将二者关联起来。 ## 快速开始 > 前提条件： 已安装并运行 Docker Desktop（安装指南 (https://docs.docker.com/desktop/)）。 sh git clone https://github.com/agno-agi/scout && cd scout cp example.env .env # 在 .env 中设置 OPENAI_API_KEY docker compose up -d --build 现在 Scout 运行在 http://localhost:8000。 ## 与 Scout 对话 1. 打开 os.agno.com (https://os.agno.com?utm_source=github&utm_medium=example-repo&utm_campaign=agent-example&utm_content=scout&utm_term=agentos) 并登录。 2. 点击添加 OS，选择本地，输入 http://localhost:8000，然后连接。 3. 尝试预配置的提示词。 https://github.com/user-attachments/assets/ed49a6c4-926b-4d5d-a105-8a0d15021d3b ## 在 Slack 中与 Scout 对话 Scout 被设计为在 Slack 中作为你的团队成员存在。请按照 docs/SLACK_CONNECT.md 将 Scout 添加到你的 Slack 工作区。 https://github.com/user-attachments/assets/69d1c409-ff94-4c8e-b5e8-64c6e1a0518a ## Scout 的工作原理 Scout 是一个单一的智能体，拥有多个上下文提供者。每个上下文提供者暴露两个自然语言工具用于与信息源交互： - query_：读取 - update_：写入（如果支持） 这一薄层解决了任何拥有多样化工具面的智能体都会遇到的三个问题：过多工具导致的上下文污染、作用域重叠带来的性能下降，以及主智能体因上下文充满工具细节而忘记自身任务。其优势在于：每个提供者背后的子智能体负责处理该源的细节。Scout 看到的是 query_slack，而背后是一个子智能体，它知道在发送私信前先查找用户、按游标分页、对于线程优先使用 conversations.replies。Scout 的上下文永远不会看到这些细节。 > “查找模型 X 的最新基准数据。” → query_web，并引用来源。 > > “将其保存为笔记。” → update_crm → 写入子智能体将数据 INSERT 到 scout.scout_notes 中。 > > “为事件响应创建运行手册。” → update_knowledge → Wiki 子智能体在 wiki/knowledge/runbooks/ 下编写一个 Markdown 页面。 > > “记录我的咖啡摄入：白咖啡，加一份浓缩。” → update_crm → 写入子智能体创建 scout.scout_coffee_orders 表并插入行。按需生成 Schema。 > > “起草一条 Slack 消息宣布发布。” → 首先使用 query_voice 加载风格指南，然后按该风格起草。 ## 上下文提供者 ContextProvider 向智能体暴露一个信息源。 | 提供者 | 触发条件 | 工具 | |—|—|—| | WebContextProvider | 始终开启 | query_web | | WorkspaceContextProvider | 始终开启 | query_workspace — 根目录位于 Scout 仓库，因此 Scout 可以回答关于自身代码库的问题 | | DatabaseContextProvider (CRM) | 始终开启 | query_crm、update_crm — 联系人、项目、笔记、后续任务 | | WikiContextProvider (知识) | 始终开启 | query_knowledge、update_knowledge — Scout 的叙述性记忆 | | WikiContextProvider (风格) | 始终开启 | query_voice — 代码管理的风格指南，用于邮件、Slack、X、长文 | | SlackContextProvider | 需要 SLACK_BOT_TOKEN | query_slack — 对消息、频道历史、线程、用户的只读访问 | | GDriveContextProvider | 需要 GOOGLE_SERVICE_ACCOUNT_FILE | query_gdrive — 对文件、文件夹、内容的只读访问 | | MCPContextProvider | 在 scout/contexts.py 中按服务器配置 | 每个注册的服务器对应一个 query_mcp_（stdio / SSE / streamable-HTTP） | Web 后端使用 Parallel SDK（当设置了 PARALLEL_API_KEY 时），否则使用免费的 Parallel MCP 服务器。 设置指南： - Slack - Google Drive - MCP 服务器 - Git 支持的 Wiki ## 评估 sh python -m evals wiring # 代码级别的不变量（无需 LLM） python -m evals # 行为测试，进程内运行 python -m evals --case # 单个 case python -m evals judges # LLM 评分的质量层级 完整说明见 docs/EVALS.md。 ## 部署到 Railway Scout 可以运行在任何云提供商上。我们提供了用于 Railway 的脚本。 前置条件： 已安装 Railway CLI (https://docs.railway.app/guides/cli) 并执行了 railway login。 ### 1. 设置生产环境 sh cp .env .env.production 如果任何值需要与本地环境不同（例如不同的 Slack 工作区、更大的模型预算、仅生产环境使用的凭证），请编辑 .env.production。Railway 脚本会首先读取 .env.production，若不存在则回退到 .env。 > .env.production 已被 gitignore，不要提交它。 ### 2. 配置并部署 sh ./scripts/railway/up.sh # 首次：Postgres + 应用服务 代码变更后更新环境变量并重新部署的脚本： sh ./scripts/railway/env.sh # 同步 .env.production → Railway ./scripts/railway/redeploy.sh # 在 up.sh 之后推送代码更新 ### 3. 首次部署将会失败。这是预期的。 生产端点默认需要 RBAC 授权（当 RUNTIME_ENV=prd 时 Scout 会启用）。如果没有 JWT_VERIFICATION_KEY，应用将拒绝提供服务。Scout 的职责是保护公司数据不被公开到公网。解决方案是从 AgentOS 生成一个密钥并将其设置到环境变量中。 ### 4. 获取验证密钥 1. 打开 os.agno.com (https://os.agno.com?utm_source=github&utm_medium=example-repo&utm_campaign=agent-example&utm_content=scout&utm_term=agentos)，点击添加 OS → 在线，然后输入你的 Railway 域名。 2. 启用基于令牌的授权 3. 将公钥粘贴到 .env.production 中（完整 PEM 块，不带外围引号）： sh JWT_VERIFICATION_KEY=-----BEGIN PUBLIC KEY----- MIIBIjANBgkq... -----END PUBLIC KEY----- 4. 同步并重新部署： sh ./scripts/railway/env.sh Railway 会在值变更时自动部署，但如果需要手动重新部署： sh ./scripts/railway/redeploy.sh 重新部署后，AgentOS 会连接，Scout 开始处理请求，从此每一个 API 调用（UI、Slack、定时任务）都会经过签名验证。 Agno 控制平面负责 JWT 颁发、会话管理、追踪、指标和 Web UI。Scout 仅验证它看到的 JWT。详情请参见 AgentOS 安全文档 (https://docs.agno.com/agent-os/security/overview)。 ### 关闭 JWT 验证（不推荐） 如果必须在没有认证的情况下运行生产环境（例如在私有 VPC 内，后面还有另一层认证），请在 app/main.py:67 处将 authorization=False 并重新部署。我们强烈建议对于任何持有真实公司数据的部署保持授权开启。否则，任何猜到你的 Railway 域名的人都可以查询你的 CRM、Wiki 和已连接的数据源。 ### 5. 将 Slack 指向新的 URL 1. 复制你的 Railway 域名。 2. 在 Slack App 设置 (https://api.slack.com/apps) 中 → Event Subscriptions，将 Request URL 设置为 https://<你的域名>/slack/events。 3. 等待 Slack 验证。如果你之前本地运行着 ngrok，可以将其关闭。Slack 现在将路由到部署实例。 ### 6. 使用 GitHub 作为知识 Wiki（推荐） 文件系统 Wiki 会在每次容器重启时重置。对于生产环境，建议切换到 Git 支持的 Wiki，这样页面可以持久化，并且有审计轨迹，审阅者可以评论。完整设置指南在 docs/WIKI_GIT.md 中。 1. 创建一个私有 Wiki 仓库，并生成一个细粒度 PAT（权限：Contents 读取和写入，范围限定在此仓库）。 2. 添加到 .env.production： sh WIKI_REPO_URL=https://github.com/your-org/your-wiki.git WIKI_GITHUB_TOKEN=github_pat_*** 3. 同步并重新部署： sh ./scripts/railway/env.sh Scout 在启动时检测到这两个环境变量，会自动将知识 Wiki 切换为 GitBackend —— 无需修改代码。启动时你会在日志中看到 Knowledge wiki: GitBackend ()。 Railway 会在值变更时自动部署，但如果需要手动重新部署： sh ./scripts/railway/redeploy.sh ### 7. 将 Railway 连接到 GitHub 以实现自动部署 到目前为止，每次代码更新都需要运行 ./scripts/railway/redeploy.sh。要实现每次推送到 main 分支时自动部署，可以在 Railway 中连接仓库： 1. 打开 Railway 仪表板 → 你的项目 → scout 服务 → 设置。 2. 在源代码下，点击连接仓库，选择 Scout 所在的仓库。 3. 设置部署分支为 main，然后保存。 之后每次推送到 main 都会触发新的构建和滚动部署。./scripts/railway/env.sh 仍然是同步 .env.production 变更的方式。 > Scout 默认使用 2 个副本部署——在 railway.json 中配置（"numReplicas": 2，每个副本 4Gi 内存、2 vCPU）。两个副本可以实现零停机滚动部署和适度的容错能力。随着使用量增长，请相应调整 numReplicas 和 limits。 ## 下一步计划 - 定时任务。 Scout 会自动展示待处理的后续动作（例如每天上午 8 点汇总 scout_followups 中 due_at <= NOW() 的记录）。 - 主动提供者操作。 update_slack、update_github 按 cron 运行，而不仅仅按需执行。 - GitHub、Gmail、日历提供者。 已在 feat/slack-interface 分支上构建并验证。将在下一个版本中发布，届时我们已使用真实令牌进行了测试。 ## 架构 基于 Agno (https://github.com/agno-agi/agno) 和 AgentOS (docs.agno.com (https://docs.agno.com?utm_source=github&utm_medium=example-repo&utm_campaign=agent-example&utm_content=scout&utm_term=docs)) 构建。实现说明：AGENTS.md。