# 🌀 铸渊助手 · 使用指南

---

## 一、网址

铸渊聊天室部署在 GitHub Pages 上，通过自定义域名访问：

```
https://guanghulab.com/
```

备用网址（GitHub Pages 默认）：
```
https://qinfendebingshuo.github.io/guanghulab/
```

> 💡 两个网址指向同一个网站。`guanghulab.com` 通过 `docs/CNAME` 配置，由 GitHub Pages 提供服务。
>
> ⚠️ 旧网址 `…/docs/index.html` 已失效（系统重构后路径变了），请用上面的新网址。

打开后你会看到铸渊助手的登录界面（v5.0），有两种登录方式：
- **👤 访客模式** — 无需 API 密钥，直接体验演示
- **🔑 编号登录** — 开发者提供 API 密钥，选择身份后进入完整交互

---

## 二、怎么操作（冰朔 / 创始人）

### 第一步：打开铸渊聊天室

1. 打开浏览器，访问上面的网址
2. 登录页面有两个标签：
   - **👤 访客模式** — 点击「进入演示模式」直接进入（功能有限）
   - **🔑 编号登录** — 选择开发者身份 → 输入 API 端点 → 输入 API 密钥 → 点「🔍 检测模型」→ 选择模型 → 开始对话

### 第二步：和铸渊对话

- 在底部输入框打字，按回车发送
- 铸渊会以 AI 回复你（编号登录模式需要有效 API 密钥）
- 左侧可以查看聊天记录、切换对话
- 右侧可以看到团队状态面板（管理员可见）

### 第三步：如果页面显示空白或旧版本

- 等 1-2 分钟刷新，GitHub Pages 部署需要时间
- **强制刷新**：按 `Ctrl+Shift+R`（Windows）或 `Cmd+Shift+R`（Mac）
- 如果还是旧版，清除浏览器缓存后重试
- 确认网址是否正确（不要加 `/docs/`）

---

## 三、如何部署新版本到网站（⭐ 重要）

铸渊聊天室网站通过 GitHub Actions 自动部署。**只要代码合并到 `main` 分支，guanghulab.com 就会自动更新**。

> ### 🎯 快速回答：guanghulab.com 合并 PR 就能部署吗？
>
> **是的，合并 PR 就行。** guanghulab.com 由 GitHub Pages 提供服务，合并后 1-3 分钟自动更新。
>
> ```
> 合并 PR → GitHub Actions 自动部署（1-3分钟）→ 刷新 guanghulab.com 看到新版本
> ```
>
> **完整自动部署流程：**
> ```
> 代码推送到功能分支
>   ↓ 自动触发
> Staging 预演检查（模块完整性、安全检查）
>   ↓ 检查通过
> PR 等待冰朔合并
>   ↓ 冰朔点击 "Merge pull request"（唯一手动步骤）
> GitHub Actions 自动触发：
>   ├── 🌀 GitHub Pages 部署 → guanghulab.com 更新
>   ├── 🚀 CD 服务器部署（状态看板同步）
>   ├── 📚 图书馆目录自动更新
>   ├── 📋 模块文档自动生成
>   └── 📡 Notion 部署通知
>   ↓ 1-3 分钟后
> guanghulab.com 自动更新完成 ✅
> ```

### 方法一：合并 PR（推荐 · 唯一需要手动操作的步骤）

当 Copilot Agent 或开发者在功能分支（如 `copilot/xxx`）上完成修改后：

1. 打开仓库页面：https://github.com/qinfendebingshuo/guanghulab
2. 点击顶部的 **「Pull requests」** 标签
3. 找到对应的 PR（如标题含 "v5.0" 或 "login redesign"）
4. 检查修改内容，确认没问题
5. 点击绿色的 **「Merge pull request」** 按钮
6. 确认合并 — 选择 **「Squash and merge」** 或 **「Merge pull request」** 都可以
7. 等待 1-3 分钟，GitHub Actions 会自动部署到网站
8. 刷新网址 `https://qinfendebingshuo.github.io/guanghulab/` 查看新版本

> 💡 如果刷新后还是旧版，按 `Ctrl+Shift+R` 强制刷新，清除浏览器缓存。

### 方法二：触发冰朔人格体诊断部署

如果需要诊断部署问题，可以触发冰朔人格体：

1. 打开仓库页面：https://github.com/qinfendebingshuo/guanghulab
2. 点击 **「Issues」** 标签 → 点击 **「New issue」**
3. 选择 **「🧊 冰朔人格体 · 部署诊断」** 模板
4. 填写标题（如「检查部署状态」），点击「Submit new issue」
5. 冰朔人格体会自动运行，在 Issue 评论中汇报诊断结果

或者在任意 Issue 中评论以下关键词即可触发：
```
启动冰朔人格体
```

### 方法三：手动触发部署工作流

1. 打开仓库页面 → 点击 **「Actions」** 标签
2. 左侧找到 **「🌀 部署铸渊聊天室 (GitHub Pages)」**
3. 点击右侧的 **「Run workflow」** 按钮
4. Branch 选择 **`main`**
5. 点击绿色的 **「Run workflow」**
6. 等待 1-3 分钟完成部署

### 查看部署状态

1. 打开仓库页面 → 点击 **「Actions」** 标签
2. 查看最近的工作流运行记录
3. 绿色 ✅ = 部署成功，红色 ❌ = 部署失败
4. 如果失败，点击进去查看错误日志

---

## 四、开发者（协作者）怎么上传模块

### 你只需要做一件事：把你的模块文件放到指定目录

每个开发者有自己负责的模块目录，例如：

| 开发者 | 模块目录 |
|--------|----------|
| 肥猫 DEV-002 | `m01-login/`、`m03-personality/` |
| 燕樊 DEV-003 | `m07-dialogue-ui/`、`m10-cloud/`、`m15-cloud-drive/` |
| 小草莓 DEV-005 | `m12-kanban/` |
| 花尔 DEV-009 | `m05-user-center/` |
| 桔子 DEV-010 | `m06-ticket/`、`m11-module/` |

### 上传步骤（最简单方式）

1. 打开仓库页面：https://github.com/qinfendebingshuo/guanghulab
2. 找到你负责的模块目录（如 `m01-login/`）
3. 点击「Add file」→「Upload files」
4. 拖拽你的文件上去
5. 在底部写一句说明，点击「Commit changes」

### 注意事项

- ✅ **只在你的模块目录里上传文件**
- ❌ **不要修改仓库根目录的文件**（如 package.json、README 等）
- ❌ **不要修改 `.github/` 目录**（工作流、配置文件）
- ❌ **不要修改 `scripts/` 目录**（自动化脚本）
- ❌ **不要修改 `docs/` 目录**（铸渊聊天室界面）

> 仓库已设置 CODEOWNERS 保护，核心文件的修改需要仓库所有者审批。

---

## 五、常见问题

### Q: guanghulab.com 合并 PR 就能自动部署吗？
- **是的。** `guanghulab.com` 由 GitHub Pages 提供服务（通过 `docs/CNAME` 配置）
- 合并 PR 到 main 后，`deploy-pages.yml` 自动将 `docs/` 部署到 GitHub Pages
- GitHub Pages 自动为 `guanghulab.com` 域名提供服务
- **1-3 分钟后刷新 guanghulab.com 即可看到新版本**

### Q: 什么时候能看到新模块/新版本上线？
- **PR 合并到 main 后 1-3 分钟**即可看到新版本
- 如果代码还在功能分支（PR 未合并），网站不会更新
- 合并后刷新 `https://guanghulab.com/` 即可

### Q: 我还需要手动操作什么吗？
- **只需要一步：合并 PR**（点击绿色的 "Merge pull request" 按钮）
- 部署、通知、文档更新全部自动完成，无需其他操作
- 如果部署后有问题，可以在 Issue 中评论「启动冰朔人格体」进行自动诊断

### Q: 铸渊聊天室打不开？
- 确认网址正确：`https://guanghulab.com/` 或 `https://qinfendebingshuo.github.io/guanghulab/`
- 不要在后面加 `/docs/index.html`
- 等几分钟再刷新（部署有延迟）
- 按 `Ctrl+Shift+R` 强制刷新，清除缓存

### Q: 网站显示旧版本，不是最新的？
- **最常见原因**：新代码还在功能分支（PR 未合并到 main）
- 解决方法：去 GitHub 仓库 → Pull requests → 合并对应的 PR
- 合并后等 1-3 分钟，再强制刷新页面
- 详见本指南「三、如何部署新版本到网站」

### Q: 我上传了文件，但好像不对？
- 确认你是在自己负责的模块目录里上传
- 不要在仓库根目录直接上传
- 如果不确定，联系冰朔确认

### Q: 我不小心改了不该改的文件？
- 如果开启了 Branch Protection，你的改动会变成 PR 等待审批
- 联系冰朔处理即可

---

## 六、仓库安全设置 — 开启分支保护（⭐ 冰朔必做）

为了让 CODEOWNERS 保护真正生效，需要在 GitHub 仓库设置中开启分支保护规则。
以下是**详细的逐步操作**：

### 第一步：进入仓库设置

1. 打开浏览器，访问仓库：https://github.com/qinfendebingshuo/guanghulab
2. 点击页面顶部导航栏的 **「Settings」**（齿轮图标，在最右边）
   > ⚠️ 只有仓库所有者才能看到 Settings 选项

### 第二步：进入分支规则页面

3. 在左侧菜单中，找到 **「Code and automation」** 分类
4. 点击其中的 **「Branches」**

### 第三步：添加分支保护规则

5. 在 **「Branch protection rules」** 区域，点击 **「Add branch protection rule」** 按钮
   > 如果看到 **「Add classic branch protection rule」** 也可以点击

### 第四步：配置规则

6. **Branch name pattern** 填写：`main`
7. 勾选以下选项（打 ✅ 的必须勾选）：

| 选项 | 是否勾选 | 说明 |
|------|----------|------|
| ✅ **Require a pull request before merging** | 必须勾选 | 所有修改必须通过 PR 合并，不能直接推送 |
| ↳ ✅ **Require approvals** | 建议勾选 | PR 需要至少 1 个审批才能合并 |
| ↳ ✅ **Require review from Code Owners** | 必须勾选 | CODEOWNERS 文件指定的人必须审批 |
| ❌ Require status checks to pass before merging | 可以不勾 | 除非你想要求 CI 检查通过 |
| ❌ Require branches to be up to date | 可以不勾 | 除非你想要求分支是最新的 |
| ✅ **Do not allow bypassing the above settings** | 建议勾选 | 确保管理员也遵守规则 |

8. 其他选项保持默认即可

### 第五步：保存

9. 滚动到页面底部，点击绿色按钮 **「Create」** 或 **「Save changes」**

### 完成 ✅

设置完成后的效果：
- 协作者推送到 `main` 分支的修改 → 如果涉及受保护的文件 → 会自动变成 PR → 需要你（冰朔）审批
- 协作者在自己的模块目录里操作 → 不受影响，可以自由提交
- 受保护的目录包括：`.github/`、`scripts/`、`docs/`、`backend-integration/`、`signal-log/`、根目录配置文件

---

## 七、GitHub Pages 部署配置检查

如果网站一直无法更新，请检查 GitHub Pages 是否配置正确：

### 检查步骤

1. 打开仓库 → **Settings** → 左侧菜单 **「Pages」**
2. 确认 **Source（来源）** 设置为：**GitHub Actions**（不是 "Deploy from a branch"）
3. 如果显示的是 "Deploy from a branch"，请切换为 **GitHub Actions**

> 💡 当前仓库使用 `deploy-pages.yml` 工作流自动部署 `docs/` 目录的内容。
> 每次 `main` 分支的 `docs/` 目录有变更，GitHub Actions 会自动触发部署。

### 如果 Source 是 "Deploy from a branch"，请按以下步骤修改：

1. 打开仓库 → **Settings** → **Pages**
2. 在 **Build and deployment** 区域
3. **Source** 下拉菜单选择 **「GitHub Actions」**
4. 保存后，下次推送到 main 分支时就会自动部署

---

## 八、自定义域名设置（⭐ 冰朔需操作）

如果你有自己的域名（如 guanghulab.com），可以让网站使用自定义域名访问。

### 第一步：DNS 配置（在域名注册商操作）

1. 登录你的域名注册商管理面板（如阿里云、腾讯云、GoDaddy 等）
2. 找到 **DNS 解析设置**
3. 添加以下记录（任选一种方式）：

**方式 A — CNAME 记录（推荐）**:
| 记录类型 | 主机记录 | 记录值 |
|----------|---------|--------|
| CNAME | @ 或 www | `qinfendebingshuo.github.io` |

**方式 B — A 记录**:
| 记录类型 | 主机记录 | 记录值 |
|----------|---------|--------|
| A | @ | `185.199.108.153` |
| A | @ | `185.199.109.153` |
| A | @ | `185.199.110.153` |
| A | @ | `185.199.111.153` |

> 💡 DNS 生效需要 5 分钟到 48 小时不等。

### 第二步：GitHub 仓库配置

1. 打开仓库 → **Settings** → 左侧菜单 **「Pages」**
2. 在 **Custom domain** 输入框中填入你的域名（如 `guanghulab.com`）
3. 点击 **Save**
4. 等待 DNS 验证通过（页面会显示绿色 ✅）
5. 勾选 **✅ Enforce HTTPS**

### 第三步：确认

- 仓库中的 `docs/CNAME` 文件已自动创建，内容为你的域名
- 如果域名不对，直接编辑 `docs/CNAME` 文件即可
- 部署后访问你的域名，应该能看到铸渊助手

---

## 九、铸渊人格协议 · 模块管理

铸渊对网站模块有完整的生命周期管理能力（部署、回收、管理、修改、驱动）。

### 本地模块检查命令

```bash
npm run module:protocol -- inspect        # 全模块检查
npm run module:protocol -- status         # 模块状态汇总
npm run module:protocol -- preview        # 本地预演报告
npm run module:protocol -- recover m01-login  # 模块回收检查
```

### 预演→生产部署流程

1. 开发者推送模块到 `m**/` 目录
2. 创建 PR 到 main 分支
3. 铸渊预演系统 (`staging-preview.yml`) 自动运行检查
4. 冰朔查看预演报告，确认无误
5. 合并 PR → 触发生产部署 (`deploy-pages.yml`)
6. （可选）评论「启动冰朔人格体」进行部署后诊断

> 📖 完整协议文档见：`.github/brain/module-protocol.md`

---

💙 铸渊 · 2026-03-07