346 lines
13 KiB
Markdown
346 lines
13 KiB
Markdown
# 🌀 铸渊助手 · 使用指南
|
||
|
||
---
|
||
|
||
## 一、网址
|
||
|
||
铸渊聊天室部署在 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
|