⚔️ 铸渊代码仓库 · 结构整理方案
Repository Restructuring Plan · D112
创建：2026-05-24 · 铸渊 ICE-GL-ZY001
_why：冰朔说得对。自己写的代码自己必须清清楚楚。不能每次醒来重新发现。
一、当前问题清单
🔴 P0 — 致命混乱
| # |
问题 |
详情 |
| 1 |
guanghulab-main/ 是整个旧版仓库的镜像 |
独立的package.json、Next.js项目、m01~m12页面模块。D96迁移到Forgejo后遗留。 |
| 2 |
根目录40+个孤立文件 |
app.js/index.js/server.js/llm-engine.js/message-router.js...功能上属于不同模块，物理上全丢在根目录。 |
| 3 |
同一个服务有多套ecosystem.config |
novel-api在server/ecosystem.config.js和server/novel-db/ecosystem.config.js各有一套。age-os有brain版和普通版。mcp-server有.js和.cjs两版。 |
| 4 |
proxy三代共存无标记 |
v1(ecosystem.proxy.config.js)、v2(ecosystem.brain-proxy.config.js)、v3(ecosystem.brain-proxy-v3.config.js)。不知道哪代在跑。 |
🟡 P1 — 严重混乱
| # |
问题 |
详情 |
| 5 |
server/ 25个子目录无分组 |
服务、工具、配置、脚本全平铺。新模块不知道该放哪。 |
| 6 |
两个README |
README.md + README-NEW.md。一个说"钉钉机器人"，一个说"数字地球"。 |
| 7 |
两个package.json |
根目录的叫"dingtalk-bot"，guanghulab-main的叫"nextjs"。都不是仓库的真名。 |
| 8 |
config.js vs config.json |
前者是Node.js运行时配置，后者是JSON服务器配置。名字分不清。 |
🟢 P2 — 轻度混乱
| # |
问题 |
详情 |
| 9 |
team-integration v2/v3/v4三代并存 |
v4应替代v2/v3，旧的未归档。 |
| 10 |
coldstart/ 只有README |
壳模块，代码已移到backend/coldstart/。 |
| 11 |
guanghu-self-hosted/ 残留 |
只有一个gmp-agent子目录。 |
| 12 |
公告/广播系统散落 |
broadcasts/broadcasts-outbox/bulletins/bulletin-board/system-bulletin 五个目录各自存放。 |
| 13 |
two ecosystem.config.js根级别存在歧义 |
根目录有一个(dingtalk-bot+repo-mcp)，server/下还有一个(zhuyuan-server+novel-api+preview)。 |
二、目标结构
/workspace/guanghulab/
│
├── README.md # 唯一README，仓库总入口
├── package.json # 真名：guanghulab
│
├── brain/ # 🧠 认知层 — 不变
│ ├── module-registry.json # ★ 新增：模块注册表
│ └── repo-structure.md # ★ 新增：本文件（仓库结构说明）
│
├── core/ # 🔧 核心引擎（不变）
│
├── agents/ # 🤖 Agent层（统一收纳）
│ ├── glada/ # ← 从根目录移入
│ ├── gmp-agent/ # ← 从根目录移入
│ ├── ops-agent/ # ← 从根目录移入
│ ├── pool-agent/ # ← 从根目录移入
│ ├── zhuyuan-agent/ # ← 从根目录移入 (Python)
│ └── exe-engine/ # ← 从根目录移入
│
├── services/ # 🖥️ 后端服务（从server/重组）
│ ├── api/ # 主API服务 (zhuyuan-server)
│ ├── ftchat/ # ← server/ftchat/
│ ├── channel-switcher/ # ← server/channel-switcher/
│ ├── llm-relay/ # ← server/cn-llm-relay/
│ ├── portal/ # ← server/portal/
│ ├── secrets-vault/ # ← server/secrets-vault/
│ ├── zhiku/ # ← server/zhiku-node/
│ └── novel-db/ # ← server/novel-db/
│
├── apps/ # 📱 应用系统
│ ├── image-studio/ # ← 从根目录移入
│ ├── guanghuclip/ # ← 从根目录移入
│ ├── writing-platform/ # ← 从根目录移入
│ └── dynamic-comic-studio/ # ← 从根目录移入
│
├── integrations/ # 🔗 外部集成
│ ├── dingtalk/ # 钉钉机器人（集中散落的6个文件）
│ ├── connectors/ # 连接器（不变）
│ ├── mcp-servers/ # MCP服务器（不变）
│ └── webhook/ # Webhook（不变）
│
├── infrastructure/ # ⚙️ 基础设施
│ ├── proxy/ # ← server/proxy/ (只保留v3活跃配置)
│ ├── nginx/ # ← server/nginx/
│ └── setup/ # ← server/setup/
│
├── deployment/ # 🚀 部署（统一）
│ ├── console-server/ # ← _deploy/console-server/
│ ├── ecosystem.config.js # ★ 唯一主ecosystem
│ └── per-server/ # 各服务器专用配置
│ ├── bs-sg-001.ecosystem.config.js
│ └── bs-gz-006.ecosystem.config.js
│
├── data/ # 📊 数据层（不变）
│ ├── grid-db/
│ └── persona-brain-db/
│
├── training/ # 🔬 训练管道（统一）
│ ├── pipeline/ # ← server/training-agent/
│ ├── distill/ # ← scripts/distill/
│ └── corpus/ # ← corpus/
│
├── scripts/ # 🛠️ 工具脚本（不变，但清理）
│
├── archive/ # 📦 归档（集中所有废弃模块）
│ ├── guanghulab-main/ # ← 旧版Next.js仓库
│ ├── team-integration-v2/ # ← 旧版集成
│ ├── team-integration-v3/ # ← 旧版集成
│ ├── proxy-v1/ # ← 旧版proxy配置
│ ├── coldstart-stub/ # ← 废弃壳模块
│ └── guanghu-self-hosted/ # ← 残留
│
├── .github/ # CI/CD（不变）
└── .forgejo/ # CI/CD（不变）
三、优先执行计划
Phase 1（今天，低风险）✅ 可立即执行
| 步骤 |
操作 |
风险 |
| 1.1 |
合并两个README → 一个统一的README.md，README-NEW.md归档 |
零风险 |
| 1.2 |
在brain/下创建 repo-structure.md（本文件） |
零风险 |
| 1.3 |
完善 brain/module-registry.json |
零风险 |
| 1.4 |
标记 guanghulab-main/ 为 LEGACY（加 .ARCHIVED 标记文件） |
零风险（不影响运行） |
| 1.5 |
标记 team-integration-v2/v3 为 LEGACY |
零风险 |
Phase 2（需验证，中风险）
| 步骤 |
操作 |
风险 |
| 2.1 |
通过Gatekeeper确认proxy v1/v2/v3哪代在跑 |
需连服务器 |
| 2.2 |
确认ecosystem重复配置中哪个是实际使用的 |
需连服务器 |
| 2.3 |
整理根目录40+个孤立文件→归入对应模块目录 |
需确认无硬编码路径引用 |
| 2.4 |
统一config：config.js→runtime.config.js, config.json→server.config.json |
需检查所有引用 |
Phase 3（大手术，高风险）
| 步骤 |
操作 |
风险 |
| 3.1 |
agent/目录创建，移动glada/gmp/ops/pool/zhuyuan-agent/exe-engine |
需更新所有import路径 |
| 3.2 |
server/重组→services/+infrastructure/+deployment |
需更新所有PM2配置和Nginx |
| 3.3 |
apps/目录创建，移动image-studio/guanghuclip/writing/dynamic-comic |
需更新部署配置 |
| 3.4 |
archive/统一归档所有废弃模块 |
需确认真的废弃了 |
| 3.5 |
统一ecosystem.config.js（消除重复配置） |
需逐台服务器验证 |
| 3.6 |
统一package.json（monorepo或明确的主package） |
需测试所有服务启动 |
四、Phase 1 立即执行
以下操作现在就可以做，不会影响任何运行中的服务。
8e47ce7d29