guanghulab/brain/shuangyan-dev-nav.md

🧭 霜砚开发导航 · 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状态”，然后再开始工作。