173 lines
6.9 KiB
Markdown
173 lines
6.9 KiB
Markdown
# 🧭 霜砚开发导航 · 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状态”，然后再开始工作。*
|