ARCHITECTURE

系统架构

无为斋的系统架构设计文档。基于个人智能空间站的架构范式，结合无为斋自身的技术栈与阶段需求，形成渐进可演进的个人智能空间站架构。

核心设计哲学

先理解「为什么这么搭」，再看「怎么搭」

📄能静态展示的，不上重后端

内容页面、导航、BI 指标展示全部走 Next.js 静态导出。无状态、零运维、一次构建全世界可用。

🏠必须本地的，留在 mini

Memory-Core、BI Engine、Agent Bridge 等需要长依赖和大模型 SDK 的重活，留在 mini 本地服务，通过 Tailscale 内网访问。

🔄构建时同步，不运行时拉取

BI 数据和系统指标在 next build 时一次性拉取，生成静态 JSON 供页面消费。运行时零 API 调用。

🔒公开页面只读

所有公开页面只显示汇总值、状态标记和趋势。不暴露原始数据、密钥或内部接口地址。

架构总览

三层架构 + 数据闭环

用户层

🌐 浏览器

网页访问

📱 手机

移动端访问

🤖 AI Agent

自动化工作流

HTTPS

网站层

samyueai.com

Next.js 静态站

空间站门户

模块入口 / 导航

BI Dashboard

记忆系统驾驶舱

Tailscale 内网

本地服务层

Memory-Core

记忆系统

BI Engine

数据采集

Agent Bridge

AI Agent 网关

数据层

知识卡片

data/knowledge_cards

FTS 索引

.index/fts_index.sqlite

运行基线

Operational Baselines

安全边界

密钥不进门，服务不裸奔

本文档仅概括架构原则与设计决策，不包含任何凭据、Token、内网地址或敏感配置信息。

🚫不暴露入站端口

所有本地服务仅通过 Tailscale 内网访问。mini 上不开任何公网入站端口。

🔐不在前端写密钥

任何 API Key / Token / Secret 不得写入 .tsx / .ts / .md 文件。前端只展示汇总指标。

📝占位符原则

如需在文档中提及密钥位置，用 <占位符> 替代。

分层架构

Edge → Tunnel → Local

🌐边缘层

Cloudflare Workers / Pages：门户、API Gateway、鉴权、内容发布。全球边缘分发，零运维。

🔗隧道层

Cloudflare Tunnel 或 Tailscale Funnel：把本地服务安全暴露为子域，本机不开入站端口。

💻本地层

Mac mini：Memory-Core、BI Engine、Agent Bridge。数据驻留本地，不依赖第三方存储。

数据流

采集 → 加工 → 展示

📥采集阶段

飞书文档/妙记 → Memory-Core Stage 7 采集管道。每日增量同步，构建时全量刷新。

⚙️加工阶段

Memory-Core 处理管道：提取 → 分类 → 嵌入 → 索引。生成结构化知识卡片。

📊BI 阶段

BI Engine 聚合指标。构建脚本拉取最新数据，生成静态 JSON 供仪表盘消费。

🖥️展示阶段

Next.js 静态页面。零运行时依赖，CDN 分发，一次构建随处可用。

Agent API 层

公开能力表面 · 静态快照 · 可查询能力注册表

📋Agent Registry（公开）

data/agents/agent_registry.json — 所有 Agent 的公开能力注册表。包含名称、角色、公开描述、可公开操作、禁止操作、风险等级。不暴露内部 Prompt、密钥或私有路径。

🔍Agent Capability Query Surface

build-time 生成的 data/public/agent_capabilities.json — 公开 Agent 能力索引。每个 Agent 暴露：可查询的公开能力列表、操作签名（入参/出参类型）、依赖项、错误码。查询层为静态 JSON，无运行时反射。不暴露内部实现或私有能力。

📦Public Snapshot Pipeline

build-time 标准化流程：data/public/*.json — 从 Agent Registry、Memory-Core 摘要、项目状态等原始数据，经统一 sanitize → validate → publish 管道，生成结构一致的公开快照。所有快照经过模式校验和安全过滤，不包含原始数据或内部路径。快照版本与构建版本绑定。

🧠Memory-Core 公开摘要

data/public/memory_summary.json — KC/ME/FTS 总数、渠道状态、预发布状态、安全边界说明。不暴露原始记忆内容。

📊项目状态摘要

data/public/project_status.json — 各项目阶段、状态、最近结果、下一步行动。不暴露内部笔记。

🛡️安全边界（只读）

所有公开数据均为只读。访客不可触发 Agent 执行、不可写入 Memory-Core、不可访问私有路由。POST API 未开放。

可观测层

Build-time Observatory · 数据新鲜度 · 来源追踪 · 自动化

📊系统观测舱

/dashboard 为公开安全摘要页面。4 个区块覆盖：聚合指标、安全边界、Agent 与审计摘要、完整运维仪表盘引导。部署细节已移至 Private Daily Ops。

📅数据新鲜度标记

每个观测区块标注数据采集时间戳与构建版本。dashboard 展示 freshness indicator：绿色（当前构建）、黄色（滞后一次构建）、红色（过时）。数据新鲜度元数据写入 data/public/freshness.json，由构建脚本自动维护。

🔗数据来源链

每个公开数据集标注来源：source type（manual / automated / build-generated）、origin pipeline、last updated。dashboard 可展开查看数据血统。不暴露内部路径，仅展示来源类型与更新策略。

🤖可观测自动化

构建流水线自动执行：snapshot generation → security scan → URL health check → freshness metadata write。人工步骤从可观测流程中剥离。仅朗月审计保留 manual trigger，结果由构建脚本自动摄取。

📦部署历史

data/ops/deploy_history.json — 记录每次部署版本、commit、构建/清理/验证状态、路由排除情况。支持回滚追溯。

🔒安全扫描

data/ops/security_scan_history.json — 每次构建后的 private route 排除验证。阻断型安全检查：private-station/admin/owner/login 若未排除则阻断 build。

🩺URL 探活

npm run ops:health — 部署后检查所有公开路由 200、私有路由 404。结果写入 data/ops/url_health.json。失败标记 degraded，关键路由失败阻断。

📝审计历史

data/ops/audit_history.json — 朗月审计结果记录，包含判定、评分、阻塞/次要项数。最新判定在 dashboard 展示。

🚨已知问题追踪

Dashboard 展示当前已知非阻塞问题。不展示原始日志全文，仅展示非敏感摘要。

公开访问入口

有限问答 · 只读 API 试点 · 安全沙箱

💬Ask Safe MVP（有限问答）

/ask 页面提供基于公开知识库的问答。本地模拟模式，不调用 AI 模型，不访问私有记忆。实施边界：话题白名单过滤、回答泄露扫描、无状态会话。标注为静态检索，非实时 AI。

🔍Ask 服务流程

select topic → load public snapshot → pattern match → static response。无外部 API 调用，无动态推理，无用户会话持久化。响应全部来自构建时生成的公开数据。所有问答结果可在 CI 中预验证。

🌐Worker Readonly API Pilot（只读 API 层）

Cloudflare Workers 只读 API 试点已部署到边缘。11 个 /api/public/* GET-only 端点，KV 数据层支持。数据来源：构建时公开快照同步到 KV。前端实现 Worker-first/static-fallback 数据获取。workers.dev 出站受限，实际数据通过静态快照 fallback 提供服务。

🛡️安全沙箱

Worker 端点仅暴露公开数据集。无密钥注入，无私有路由，无 POST/PUT/DELETE。请求频率限制通过 Cloudflare WAF 实现。所有响应内容来自预先审核的 data/public/ 数据源。CORS 限制为 samyueai.com 来源。

Private Station V2.4

私有能力试点 · Access/Tunnel 安全接入

✅架构分离 — READY

Public site (SSG) 与 Private station (local+Access) 完全分离。SSG 构建时 purge 清除所有私有路由 (private-station/admin/owner/login)。服务器 nginx 不 serve Private station。Private station 通过 Tunnel+Access 在本地受控访问。

✅Local Pilot — READY

Private station 页面在 localhost:3000 全部可访问。AuthGuard cookie 鉴权 (guest/admin/owner 三级)。不涉及真实 secret。Mission-control / Admin / Owner 页面有独立的角色控制。

✅Tunnel — ACTIVE

wuwei-memory-core Tunnel 已部署运行 (3 个活跃 Edge 连接)。DNS CNAME 记录 (admin/memory/agent.samyueai.com → cfargotunnel.com) proxied=True → Cloudflare 代理路由正常。admin/memory/agent 公网已验证返回 302 (Access 登录页)。

✅Cloudflare Access — GATE_VERIFIED

4 个 Access 应用已配置 (wuwei-private-station, wuwei-admin, wuwei-memory, wuwei-agent)。策略已验证 (仅 yuesanfeng@gmail.com)。admin 浏览器登录实测通过 (FULLY_VERIFIED)。memory/agent 未登录返回 302 (GATE_VERIFIED)。

✅Memory Endpoint — FULLY_VERIFIED

浏览器登录实测通过。Memory-Core 摘要页端到端可达。

✅Agent Endpoint — PRIVATE_LANDING_READY

V2.6 修复: Agent API 服务添加了安全 HTML landing/status 页面。浏览器登录后显示 Agent 状态、能力说明、路线图。JSON API 端点保持向后兼容。DNS/Tunnel/Access 均已验证通过。

🔒Worker API — READONLY_OK

11 /api/public/* 端点保持只读 (GET/OPTIONS only)。KV 7 keys 仅含脱敏摘要。Private station 数据不进入 Worker API 或 public KV。无 POST/PUT/DELETE 写端点。

演进路线

从 V1 到 V3 的分阶段实施

V1 · 已完成网站基础 + 内容系统

Next.js 静态站点，Markdown 内容体系，基本导航与搜索。

V2.0 · 已完成架构升级 + AIbens-Informed 空间站

architecture 架构对标完成，全站 SSG，空间站/记忆/驾驶舱/架构/问答产品化。安全边界固化。

V2.1 · 已完成Agent API 能力化 + 系统观测舱

Agent Registry 公开能力注册表。Observability Cockpit 从 BI 展示升级为系统观测。Build-time 静态快照管道。安全扫描/URL 探活/部署历史审计集成到构建流水线。私有路由阻断验证。

V2.2 · 已完成公开数据管道 + 有限问答 + 架构 Parity

Public Snapshot Pipeline 标准化。Agent Capability Query Surface。Ask Safe MVP。Architecture 架构对标完成静态安全层。14 项安全边界标记。

V2.3 · 已完成Worker API Pilot · 云端只读能力

Worker Readonly API 部署到 Cloudflare 边缘（11 端点，KV 数据层）。Worker-first/static-fallback 数据获取层。Ask Safe MVP Worker 感知。Dashboard Worker API Observability。Public Snapshot → KV 发布管道。DNS 约束下的最小化云端能力试点。

V2.4 · 已完成Private Station Access · 安全接入试点

Public/Private 架构分离。Local Private Station Pilot (AuthGuard 本地鉴权)。Cloudflare Tunnel 运行中 (wuwei-memory-core, 3 连接, proxied CNAME → CF 代理路由正常)。Access 应用已验证 (4 apps, yuesanfeng@gmail.com)。admin/memory/agent 未登录返回 302。DNS 权威: Cloudflare。登录后可达性待浏览器实测。

V2.5 · 已完成Admin Access 端到端验证

admin 浏览器登录实测通过 (FULLY_VERIFIED)。memory 登录实测通过 (FULLY_VERIFIED)。agent 识别为 BACKEND_ROUTE_NOT_FOUND (JSON API 无 HTML)。DNS 权威修正: 公网为 Cloudflare。Tunnel Activation 验证完成。

V2.6 · 已完成Private Agent & Memory Endpoint

Agent Private Landing 已完成 (PRIVATE_LANDING_READY)。Memory 私有边界确认。三端点角色分工固化 (admin/memory/agent)。Agent 执行延迟至 V2.7。Memory-Core 私有查询延迟至 V2.8。

V2.7 · 已完成Controlled Agent Execution MVP

Agent 端点升级为受控执行模式。6 个 allowlisted low-risk action (Agent Health, URL Health Refresh, Leak Scan, Snapshot Check, Deploy Dry-Run, Status Report)。Action Registry + Audit Log (JSONL) + Task Model (queued/running/succeeded/failed/rejected)。仅 Access 后可用，仅只读，拒绝任意命令/shell/code。action_001~006 仅接受 action_id，不接受任意命令文本。public 页面只展示状态摘要。

V2.8 · 已完成Private Memory-Core Query / Retrieval / Audit

Memory 端点升级为私有 Memory-Core 查询入口。独立 Memory Query API (port 3003) 包装 MC API (port 3001) 增加安全审计层。SUMMARY_FIRST: 摘要优先，拒绝 raw/export/full_text/path。POST /memory/search 结构化搜索 (summary-only, audited)。GET /memory/sources/:id 逐条 source trace。GET /memory/stats + /memory/recent + /memory/health 摘要统计。Query Audit (JSONL)。memory.samyueai.com 独立入口。所有查询写 audit log。拒绝 action_id 注入。

V2.9 · 已完成Private Authenticated Ask

Private Ask 入口，仅允许 Authenticated 用户通过认证后提交私有 Ask 请求。认证上下文隔离，拒绝未认证访问。基于 Memory Query API (port 3003) 构建安全 Ask 管道，所有请求写入 Audit Log。Access 策略确保仅 yuesanfeng@gmail.com 可访问。

V3.0 · 此版本AIbens-like Personal AI Station Final Integration

全链路收口、总文档、总审计、回滚体系就绪。V2.9 全部能力已验证封板，V3.0 为 Final Integration 阶段 — 不新增功能，只收口。Public Site, Worker, Snapshot, Ask, Observability, Access/Tunnel, Private Admin, Private Agent, Controlled Agent Execution, Private Memory Query, Source Trace, Query Audit, Private Authenticated Ask — 所有能力闭环。朗月 Final Audit 通过。

V3 · 规划边缘接入 + 全栈空间站

Tunnel 暴露本地服务，API Gateway 统一鉴权，内容权限分级。完整的 Agent 远程调用。

→ 返回空间站总览 → 查看项目工坊