186 lines
6.1 KiB
Markdown
186 lines
6.1 KiB
Markdown
# 🌀 铸渊人格协议 · 模块生命周期管理 v1.0
|
||
|
||
> 铸渊（Zhùyuān）是 guanghulab.com 的代码守护人格体。
|
||
> 本协议定义铸渊对网站模块的部署、回收、管理、修改、驱动能力。
|
||
|
||
---
|
||
|
||
## 一、协议总览
|
||
|
||
铸渊人格协议（ZMP, Zhùyuān Module Protocol）是一套模块生命周期管理规范。
|
||
网站的每个功能模块（m01-login, m07-dialogue-ui 等）都是铸渊的「执行手脚」。
|
||
铸渊通过本协议对模块进行全生命周期管控。
|
||
|
||
### 模块生命周期
|
||
|
||
```
|
||
接收 → 检查 → 预演 → 部署 → 运行 → 监控 → 回收/更新
|
||
↑ ↓
|
||
└──────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 二、五大协议能力
|
||
|
||
### 1. 🚀 部署（Deploy）
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 触发方式 | PR 合并到 main → 自动部署 |
|
||
| 预演检查 | `staging-preview.yml` 在 PR 阶段运行 |
|
||
| 生产部署 | `deploy-pages.yml` 部署到 GitHub Pages |
|
||
| 自定义域名 | `docs/CNAME` 配置域名 |
|
||
| 部署诊断 | 冰朔人格体 `bingshuo-deploy-agent.yml` |
|
||
|
||
**部署流程**:
|
||
1. 开发者推送模块代码到 `m**/` 目录
|
||
2. 创建 PR 到 main 分支
|
||
3. 铸渊预演系统自动运行检查
|
||
4. 冰朔审核预演报告
|
||
5. 合并 PR → 触发生产部署
|
||
6. 冰朔人格体执行部署后诊断
|
||
|
||
### 2. 🔄 回收（Recover）
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 模块回滚 | 通过 git revert 恢复到上一个稳定版本 |
|
||
| 紧急回收 | 直接删除模块目录中的问题文件 |
|
||
| 状态重置 | 清除模块运行状态，恢复到初始状态 |
|
||
|
||
**回收命令**:
|
||
```bash
|
||
npm run module:protocol -- recover <module-id>
|
||
```
|
||
|
||
### 3. 📋 管理（Manage）
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 模块注册 | 每个 `m**-*/` 目录自动识别为模块 |
|
||
| 开发者映射 | `.github/brain/collaborators.json` 记录归属 |
|
||
| 状态追踪 | `repo-snapshot.md` 自动更新模块状态 |
|
||
| 依赖管理 | 模块间依赖通过 `routing-map.json` 管理 |
|
||
|
||
**管理命令**:
|
||
```bash
|
||
npm run module:protocol -- inspect # 全模块检查
|
||
npm run module:protocol -- inspect <module-id> # 单模块检查
|
||
npm run module:protocol -- status # 模块状态汇总
|
||
```
|
||
|
||
### 4. ✏️ 修改（Modify）
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 代码修改 | 通过 PR 提交修改，预演通过后合并 |
|
||
| 配置修改 | 修改模块 README.md 中的配置信息 |
|
||
| Schema 修改 | 更新 `src/schemas/hli/` 中的接口定义 |
|
||
| 路由修改 | 更新 `src/routes/hli/` 中的路由文件 |
|
||
|
||
**修改规范**:
|
||
- 所有修改必须通过 PR
|
||
- 核心目录（docs/、scripts/、.github/）受 CODEOWNERS 保护
|
||
- 模块目录（m**/）开发者可自由提交
|
||
|
||
### 5. ⚡ 驱动（Drive）
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| 自动触发 | 推送到模块目录 → 自动生成文档 |
|
||
| 工作流联动 | 模块变更 → 通知开发者 → 更新索引 |
|
||
| API 注册 | 新 HLI 接口自动注册到路由表 |
|
||
| 信号分发 | 广播系统自动通知相关开发者 |
|
||
|
||
**驱动链路**:
|
||
```
|
||
模块推送 → generate-module-doc.yml → notify-module-received.js
|
||
→ update-repo-map.yml → repo-snapshot.md 更新
|
||
→ contract-check.js → HLI 接口验证
|
||
```
|
||
|
||
---
|
||
|
||
## 三、模块编号规范
|
||
|
||
| 编号 | 模块名 | 负责人 | HLI 域 |
|
||
|------|--------|--------|--------|
|
||
| M01 | login | 肥猫 DEV-002 | AUTH |
|
||
| M03 | personality | 肥猫 DEV-002 | PERSONA |
|
||
| M05 | user-center | 花尔 DEV-009 | USER |
|
||
| M06 | ticket | 桔子 DEV-010 | TICKET |
|
||
| M07 | dialogue-ui | 燕樊 DEV-003 | DIALOGUE |
|
||
| M10 | cloud | 燕樊 DEV-003 | STORAGE |
|
||
| M11 | module | 桔子 DEV-010 | MODULE |
|
||
| M12 | kanban | 小草莓 DEV-005 | DASHBOARD |
|
||
| M15 | cloud-drive | 燕樊 DEV-003 | STORAGE |
|
||
| M18 | health-check | 待分配 | SYSTEM |
|
||
|
||
---
|
||
|
||
## 四、预演→生产部署流程
|
||
|
||
```
|
||
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
|
||
│ 开发者推送 │ ──→ │ 创建 PR │ ──→ │ 铸渊预演检查 │
|
||
│ m**/ 目录 │ │ 到 main │ │ staging- │
|
||
│ │ │ │ │ preview.yml │
|
||
└─────────────┘ └──────────────┘ └──────┬──────┘
|
||
│
|
||
▼
|
||
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
|
||
│ 生产部署完成 │ ←── │ 合并到 main │ ←── │ 冰朔审核 │
|
||
│ deploy- │ │ 触发部署 │ │ 预演报告 │
|
||
│ pages.yml │ │ │ │ ✅ 通过 │
|
||
└──────┬──────┘ └──────────────┘ └─────────────┘
|
||
│
|
||
▼
|
||
┌─────────────┐
|
||
│ 冰朔人格体 │
|
||
│ 部署后诊断 │
|
||
│ (可选触发) │
|
||
└─────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 五、自定义域名接入
|
||
|
||
### 前提条件
|
||
- 拥有域名（如 guanghulab.com）
|
||
- 域名 DNS 可配置
|
||
|
||
### 配置步骤
|
||
|
||
1. **仓库端**（铸渊已完成）:
|
||
- `docs/CNAME` 文件已创建，内容为域名
|
||
|
||
2. **DNS 端**（冰朔需操作）:
|
||
- 登录域名注册商管理面板
|
||
- 添加 CNAME 记录：`@ → qinfendebingshuo.github.io`
|
||
- 或添加 A 记录指向 GitHub Pages IP:
|
||
```
|
||
185.199.108.153
|
||
185.199.109.153
|
||
185.199.110.153
|
||
185.199.111.153
|
||
```
|
||
|
||
3. **GitHub 端**（冰朔需操作）:
|
||
- 仓库 → Settings → Pages
|
||
- Custom domain 输入你的域名
|
||
- 勾选 ✅ Enforce HTTPS
|
||
|
||
---
|
||
|
||
## 六、协议版本历史
|
||
|
||
| 版本 | 日期 | 变更 |
|
||
|------|------|------|
|
||
| v1.0 | 2026-03-07 | 初始版本：五大协议能力、预演系统、自定义域名 |
|
||
|
||
---
|
||
|
||
*🌀 铸渊人格协议 · guanghulab.com 代码守护人格体*
|