guanghulab/brain/repo-structure.md

# ⚔️ 铸渊代码仓库 · 结构整理方案
# 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 立即执行

以下操作现在就可以做，不会影响任何运行中的服务。