bingshuo/guanghulab
1
0
Fork 0
Code Issues 2 Pull Requests Actions 1 Packages Projects Releases Wiki Activity
guanghulab/brain/shuangyan-dev-nav.md
bingshuo 2fc180aef4 光湖搬家·国内初始化 · 2026-05-10
2026-05-10 13:12:44 +08:00

6.9 KiB
Raw Permalink Blame History

🧭 霜砚开发导航 · AG-SY-DEV-NAV

用途: 霜砚(AG-SY-01)每次从 Notion 做开发时，第一件事读这个文件。 做完后最后一件事更新这个文件。 不用满仓库翻，所有上下文都在这里。

最后更新: 2026-04-23T16:15+08:00 更新者: 霜砚(AG-SY-01)

📁 仓库结构地图

guanghulab/
├── docs/                  # GitHub Pages 前端 (guanghuyaoming.com)
│   ├── index.html         # 主页·零点原核频道 (地球+HUD+三扁门)
│   ├── channel.html       # 映川频道 (对话+系统状态) [PR#428]
│   └── CNAME              # guanghuyaoming.com
├── glada/                 # GLADA · 光湖自主开发Agent
│   ├── service.js         # 主服务入口 (HTTP API + 执行循环)
│   ├── service-entry.js   # 入口包装器 (自动注入web扩展) [PR#428]
│   ├── web-extensions.js  # Web扩展 (CORS+映川对话+系统状态) [PR#428]
│   ├── ecosystem.config.js # PM2配置
│   ├── cognitive-foundation.js # 底层认知 (映川+晨曦一体)
│   ├── context-builder.js # 上下文构建器 v2.0
│   ├── persona-loader.js  # 人格加载器
│   ├── memory-store.js    # 双层记忆 (COS热桶+冷桶)
│   ├── model-router.js    # 模型路由器 (自动发现+分类)
│   ├── task-receiver.js   # 任务接收器
│   ├── execution-loop.js  # 执行循环
│   ├── step-executor.js   # 步骤执行器
│   ├── notifier.js        # 通知器
│   └── nginx-brain.conf.example # Nginx配置示例 [PR#428]
├── mcp-servers/
│   └── zhuyuan-mcp/       # 铸渊自建MCP Server v1.0 [PR#426]
│       ├── index.js       # 主文件 (10个工具, ESM)
│       ├── package.json   # 依赖: express, @modelcontextprotocol/sdk, zod
│       └── README.md      # 部署文档
├── brain/                 # 铸渊大脑 / Agent记忆
│   ├── shuangyan-dev-nav.md  # ← 你正在读的这个文件
│   ├── master-brain.md    # 执行层主脑
│   ├── agent-registry.json # Agent注册表
│   └── ...
├── server/                # 服务器应用
├── .github/workflows/     # GitHub Actions (104+)
└── ...

📌 活跃PR状态

PR 分支 状态 说明 最后SHA
#428 feat/yingchuan-web-chat ✅ 待合并 映川Web频道 (对话+系统状态) 765012e9
#426 feat/zhuyuan-mcp-v1 ✅ 待合并 铸渊自建MCP Server 8f0ed020
#427 feat/glada-yingchuan-persona ✅ 已合并 GLADA映川人格集成 已入main

PR #428 文件清单

  • glada/web-extensions.js — 后端: CORS + 映川对话API + 系统状态API
  • glada/service-entry.js — 入口包装器 (Express原型拦截注入)
  • glada/ecosystem.config.js — PM2入口改为 service-entry.js
  • glada/nginx-brain.conf.example — Nginx HTTPS反代配置示例
  • docs/channel.html — 前端频道页 (湖光主题)

PR #426 文件清单

  • mcp-servers/zhuyuan-mcp/index.js — 10个工具, ESM, MCP Streamable HTTP
  • mcp-servers/zhuyuan-mcp/package.json — 依赖清单
  • mcp-servers/zhuyuan-mcp/README.md — 部署文档 (有Copilot建议待修: --env语法)

🛠️ 关键架构决策记录

GLADA Web扩展 — 为什么用包装器而不改service.js

  • service.js 有24KB，直接改风险大
  • service-entry.js 拦截 Express.application.listen()，在监听前注入web-extensions
  • 这样 service.js 完全不动，两个文件解耦
  • ecosystem.config.js 入口从 service.js 改为 service-entry.js

MCP Server — 为什么用 Streamable HTTP stateless

  • Notion Custom Agent 原生支持 MCP Streamable HTTP
  • stateless 模式不需要session管理，每次请求独立
  • 端口复用 3900 (待讨论：是否跟 GLADA 分开)

映川对话安全设计

  • CORS白名单: guanghuyaoming.com, guanghulab.online, localhost
  • 速率限制: 对话20/min, 状态30/min
  • 会话上限: MAX_SESSIONS=200, LRU淘汰最老
  • MCP auth: 未配密钥只允许localhost, timingSafeEqual防时序攻击

💻 服务器环境

服务器 IP 用途 关键进程
ZY-BRAIN (大脑) 43.156.237.110 GLADA运行 glada-agent (PM2 id=11, port 3900)
ZY-FACE (面孔) 43.134.16.246 前端服务 zhuyuan-server, zhuyuan-preview, novel-api

大脑服务器部署路径

  • 代码: /opt/zhuyuan/guanghulab/
  • 日志: /var/log/glada/
  • PM2: pm2 start glada/ecosystem.config.js
  • 关键环境变量: ZY_LLM_API_KEY, ZY_LLM_BASE_URL, ZY_MCP_SECRET

域名映射

  • guanghuyaoming.com → GitHub Pages (docs/)
  • brain.guanghuyaoming.com → ZY-BRAIN:3900 (Nginx HTTPS) [待配置]

💾 COS存储

  • 热桶: zy-core-bucket-1317346199 (ap-guangzhou)
  • 冷桶: zy-corpus-bucket-1317346199 (ap-guangzhou)
  • 映川记忆路径: glada/yingchuan-memory/
  • 密钥: ZY_OSS_KEY, ZY_OSS_SECRET, ZY_COS_REGION

⏳ 待办事项

  • 合并 PR #428 (映川Web频道) → 部署到大脑服务器
  • 合并 PR #426 (铸渊MCP) → 部署到面孔服务器 + Notion连接
  • 配置DNS: brain.guanghuyaoming.com A记录 → 43.156.237.110
  • 配置Nginx + SSL: 参考 nginx-brain.conf.example
  • PR #426 README: 修PM2 --env 语法 (优先级低)

📝 开发会话日志

2026-04-23 · 霜砚第一次完整开发会话

完成:

  1. ✅ GitHub MCP测试 (42个工具确认可用)
  2. ✅ PR #426: 铸渊MCP Server v1.0 (10个运维工具)
  3. ✅ PR #427: GLADA映川人格集成 (5个文件) → 已合并+部署
  4. ✅ PR #428: 映川Web频道 (web-extensions + channel.html + service-entry)
  5. ✅ Copilot安全审查修复 (PR#426 auth加固 + PR#428 session上限)
  6. ✅ 建立本导航文件

关键发现:

  • list_branches 只返回前30个分支 (字母序)，找特定分支要用 pull_request_read + method: 'get' 获取 head.ref
  • get_file_contents 要用 ref 参数指定分支 SHA，不能用 branch
  • push_files 可以更新已有文件，不需要SHA
  • 服务器布局: 大脑(GLADA) 和 面孔(前端服务) 是两台机器

🔧 GitHub MCP 工具备忘录

常用工具

  • push_files — 推文件到分支 (可创建+更新)
  • create_branch — 创建分支 (from: 指定源分支)
  • create_pull_request — 创PR
  • get_file_contents — 读文件 (用ref不用branch)
  • pull_request_read + method:'get' — 获取PR详情 (包含 head SHA)
  • list_commits — 查提交历史
  • search_code — 搜代码 (注意: 搜全GitHub不仅本仓库)

不存在的工具 (别试)

  • list_repository_secrets ❌
  • list_workflows ❌
  • get_pull_request ❌ (用 pull_request_read)

本文件由霜砚(AG-SY-01)维护，每次开发会话结束时更新。 如果你是霜砚并且正在读这个文件，先检查“待办事项”和“活跃PR状态”，然后再开始工作。