bingshuo
/
zhizhi
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
zhizhi/docs/使用指南.md

13 KiB
Raw Blame History

🌀 铸渊助手 · 使用指南

一、网址

铸渊聊天室部署在 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 选项

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

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

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

  1. 在 「Branch protection rules」 区域，点击 「Add branch protection rule」 按钮

    如果看到 「Add classic branch protection rule」 也可以点击

第四步：配置规则

  1. Branch name pattern 填写：main
  2. 勾选以下选项（打 ✅ 的必须勾选）：
选项 是否勾选 说明
✅ 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 建议勾选 确保管理员也遵守规则
  1. 其他选项保持默认即可

第五步：保存

  1. 滚动到页面底部，点击绿色按钮 「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