159 lines
8.2 KiB
Markdown
159 lines
8.2 KiB
Markdown
# ⚔️ 铸渊代码仓库 · 结构整理方案
|
||
# 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 立即执行
|
||
|
||
以下操作现在就可以做，不会影响任何运行中的服务。
|