00 - 本地服务器 "llmpowerhouse" 时间线

llmpowerhouse 项目代表了一套完全本地化、DIY 的 AI 基础设施，于 2026 年 7 月的一周内在一台 Mac Studio 上搭建而成。本时间线完整追踪了从硬件初始化到搭建具备检索增强生成（RAG）、持久记忆和工具调用能力的完整 Agent 服务器的全过程，记录了将裸机转化为实用知识库引擎的具体日期、技术决策与迭代式问题排查。

| 日期 | 里程碑 | :---||:---| | 7月24日 | Mac 基础配置与初始文档| | 7月25日 | Ollama 安装、三模型套件、公开展示站点、API 网关| | 7月26日 | 知识库填充与 LLM Wiki 自动化 | | 7月27日 | 检索漏洞修复与 Agent 服务器初始化（第一阶段） | | 7月30日 | 核心 Agent 框架开发（“大构建日”） | | 7月29日 | 实时流传输、延迟优化、MCP 工具及运维 SOP | | 7月30日 | 自引用路由网关与学习笔记文档套件 |

短短七天内，一台空白 Mac 蜕变为具备检索增强生成（RAG）、持久记忆、工具集成及公开演示能力的本地 AI 服务器。未采购任何托管云服务；所有部分完全由机主自有硬件运行。

在安装任何 AI 软件之前，项目首先记录了全面的基线配置：backups/hardware_info.txt（Mac Studio、Apple M3 Ultra 芯片、28 核处理器、96 GB 内存）、backups/brew_packages.txt（git、python@3.12、ffmpeg、htop、jq、wget、VS Code 及编解码库），以及 backups/disk_layout.txt（独立于启动盘的专属 1.8 TB /Volumes/AI_DATA APFS 卷，确保整个系统保持“单文件夹结构：可携带、可备份、可重建”）。

在拉取第一个模型之前，项目先行起草了两份核心文档：MAC_BASICS_CHEATSHEET.md（面向新手的终端命令与快捷键参考）和 KNOWLEDGE_MANAGEMENT_GUIDE.md（在知识库内容成型前，勾勒出 RAG/Wiki/Graph 三层架构策略）。“先规划文档、后动手实施”这一原则成为了贯穿全程的固定模式。该项工作直接对应 AI_SERVER_SETUP_GUIDE.md 中的 Phase 0：macOS 更新、禁用睡眠模式、Homebrew/开发工具安装、GitHub SSH 密钥生成，以及初始 AI_DATA 文件夹结构（models/、knowledge-bank/、apps/、logs/、backups/。

第一阶段与第二阶段（Ollama + 模型套件）： 安装了 Ollama，并将权重重定向至 /Volumes/AI_DATA/models/ollama，以避免模型文件占用启动磁盘空间。拉取了三个模型，总计 102 GB：gpt-oss:120b（约 64 GB，作为主要的深度推理器/"主模型"）、qwen3.6:35b-a3b（约 22 GB，用于日常快速使用的混合专家模型），以及 qwen3-vl:30b（约 18 GB，唯一的视觉能力模型）。同时添加了 Whisper (large-v3-turbo) 以支持语音转文本。由于当时 macOS 对兼具视听功能的“全能”架构存在音频限制，视觉与音频功能被拆分到不同的模型中处理。

第三阶段（接口与网络）： 在专用的 Python 虚拟环境中部署了 Open WebUI，作为类似 ChatGPT 的接口，并通过局域网 (llmpowerhouse.local:8080) 暴露服务，同时通过 Tailscale 实现远程访问。配套展示站点 apps/llmpowerhouse-site/ 使用 Next.js/TypeScript/Tailwind 构建，包含互动式安装清单、路线图以及直接桥接至家庭服务器的“现场演示”。其 Git 历史记录显示，仅在 2026-07-25 当天就提交了 18 次提交，快速修复了冷启动超时、历史日志错误、网关进程终止模式，以及在移除速率限制后对桌面端开始/停止/重启按钮的改进。

构建了 gateway.py 网桥（端口 8787），以在公共互联网（通过 Tailscale Funnel）与 Ollama 之间进行中介，强制实行按应用划分的 API 密钥以实现隔离的凭据吊销。完成了 restart-ai-stack.command、stop-ai-stack.command 以及初始的知识库下载脚本 (download-omb-dfas-service-docs.sh、download-sap-oracle-platform-docs.sh、download-gao-audit-service-reports.sh、download-crs-fm-acquisition-reports.sh)，奠定了 DOD-FM 财务管理库的基础。

摄入机制迅速扩展，新增了四个下载脚本，用于构建 K12 教育标准库（包含 AMC/AP/SAT/PSAT 材料、各州课程大纲、精英学校目录）。发现并修复了一个关键的验证漏洞：部分所谓“下载”的文件实际上是保存为 .pdf 扩展名的 HTML 错误页面，它们通过了单纯基于大小的有效性检查。事后审计纠正显示准确数量如下：K12 库（280 个有效 / 15 个损坏 / 26 个无法获取）和 DOD-FM 库（58 个有效 / 0 个损坏 / 26 个无法获取）。

编写了 SYSTEM_OVERVIEW_SUMMARY.md，作为一页纸的架构地图，至今仍是主要的导向指南。记录了一项关键的操作限制：在系统中，AI 的沙箱无法发起出站请求（403 blocked-by-allowlist），因此必须由用户在其本地终端中手动执行所有下载脚本。

知识策略的第二层级实现自动化：部署了 apps/llm-wiki/lw_wiki.py 与由 launchd-managed file watcher (com.llmpowerhouse.wiki-watch.plis), 用于在文档传入后的 ~10 秒内自动起草维基页面(待人工审核)。当天的崩溃修复解决了因 fswatch剥离了 PATH 导致fswatch二进制文件无法调用、裸抛TimeoutError异常中断运行流。stdout buffering delaying progress feedback，以及未过滤的文件名中包含/。当天以 257 篇活跃维基页面收官 (DOD-FM, 182 K1)。

实现了实时Token流式传输，解决了因Ollama的SSE格式与.json()解析器不匹配而导致的502错误。同时部署了HTTP连接池客户端，并基于日志流量测得了基线延迟指标（p50：26.3秒，p90：88.7秒）。两个与已安装SDK不兼容的故障MCP服务器（fetch、secedgar）被静默禁用，而非让其处于持续的失败状态。构建了可执行设置脚本（Setup-MCP-Fetch.command、Setup-MCP-WebSearch.command）以实现一键工具扩容。编写了 SOP-LLM-OPERATIONS.md，将碎片化的团队经验知识规范化为标准的日常运维手册。

通过日志端到端追踪了一个简单查询耗时14.4秒的延迟问题，锁定其根本原因：模型在不需搜索的情况下，过度检索文件系统寻找不存在的文档，而非直接识别系统提示词中已存在的答案。采用了分层修复方案：首先明确提示词逻辑，其次引入快速的正则表达式后备机制，最后校准嵌入相似度阈值（基于日志分数设定为0.80）。整个诊断过程与架构考量均已在本学习笔记集及 AGENT_LATENCY_INVESTIGATION_SUMMARY.md 中完整记录。

• 反应式优于推测式： 每一项重大的架构决策（记忆作用域划分、检索排序、耗时拦截、有效性校验）均来自于对实际使用问题的调试，而非理论规划。
• 原生本地化设计： 整个技术栈直接运行于Mac Studio裸机硬件之上，无任何托管云服务依赖，完全隔离在专用的1.8 TB APFS卷内，以实现最大程度的可移植性和备份简便性。
• 文档优先工作流： 在实施前先行起草架构指南（KNOWLEDGE_MANAGEMENT_GUIDE.md、SYSTEM_OVERVIEW_SUMMARY.md）确立了追踪快速迭代循环所需的严谨纪律。
• 沙盒边界决定工作流： AI无法发起出站请求（403 blocked-by-allowlist）迫使采用手动执行脚本的方式，并由此塑造了整个知识摄入管道的设计。
• 迭代式稳定演进： 从初期的基线缺口（65%通过率），到流式传输修复、MCP SDK兼容性检查及嵌入阈值校准，持续的运营调优将一个原型系统打造成了可靠的基础设施。