guanghulab/docs/使用指南.md

🌀 铸渊助手 · 使用指南

---

一、网址

铸渊聊天室部署在 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 文件即可
• 部署后访问你的域名，应该能看到铸渊助手

---

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

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

本地模块检查命令

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