diff --git a/docs/使用指南.md b/docs/使用指南.md index ed3659c9..99ba45c6 100644 --- a/docs/使用指南.md +++ b/docs/使用指南.md @@ -12,7 +12,9 @@ https://qinfendebingshuo.github.io/guanghulab/ > ⚠️ 旧网址 `…/docs/index.html` 已失效(系统重构后路径变了),请用上面的新网址。 -打开后你会看到铸渊助手的登录界面,选择你的身份即可开始对话。 +打开后你会看到铸渊助手的登录界面(v5.0),有两种登录方式: +- **👤 访客模式** — 无需 API 密钥,直接体验演示 +- **🔑 编号登录** — 开发者提供 API 密钥,选择身份后进入完整交互 --- @@ -21,25 +23,79 @@ https://qinfendebingshuo.github.io/guanghulab/ ### 第一步:打开铸渊聊天室 1. 打开浏览器,访问上面的网址 -2. 在登录页面选择你的身份(如「冰朔」) -3. 点击「开始与铸渊对话」 +2. 登录页面有两个标签: + - **👤 访客模式** — 点击「进入演示模式」直接进入(功能有限) + - **🔑 编号登录** — 选择开发者身份 → 输入 API 端点 → 输入 API 密钥 → 点「🔍 检测模型」→ 选择模型 → 开始对话 ### 第二步:和铸渊对话 - 在底部输入框打字,按回车发送 -- 铸渊会以 AI 回复你(需要 API 密钥,或使用后端代理模式) +- 铸渊会以 AI 回复你(编号登录模式需要有效 API 密钥) - 左侧可以查看聊天记录、切换对话 -- 右侧可以看到团队状态面板 +- 右侧可以看到团队状态面板(管理员可见) -### 第三步:如果页面显示空白 +### 第三步:如果页面显示空白或旧版本 - 等 1-2 分钟刷新,GitHub Pages 部署需要时间 -- 清除浏览器缓存后重试 +- **强制刷新**:按 `Ctrl+Shift+R`(Windows)或 `Cmd+Shift+R`(Mac) +- 如果还是旧版,清除浏览器缓存后重试 - 确认网址是否正确(不要加 `/docs/`) --- -## 三、开发者(协作者)怎么上传模块 +## 三、如何部署新版本到网站(⭐ 重要) + +铸渊聊天室网站通过 GitHub Actions 自动部署。**只要代码合并到 `main` 分支,网站就会自动更新**。 + +### 方法一:合并 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. 如果失败,点击进去查看错误日志 + +--- + +## 四、开发者(协作者)怎么上传模块 ### 你只需要做一件事:把你的模块文件放到指定目录 @@ -73,12 +129,19 @@ https://qinfendebingshuo.github.io/guanghulab/ --- -## 四、常见问题 +## 五、常见问题 ### Q: 铸渊聊天室打不开? - 确认网址正确:`https://qinfendebingshuo.github.io/guanghulab/` - 不要在后面加 `/docs/index.html` - 等几分钟再刷新(部署有延迟) +- 按 `Ctrl+Shift+R` 强制刷新,清除缓存 + +### Q: 网站显示旧版本,不是最新的? +- **最常见原因**:新代码还在功能分支(PR 未合并到 main) +- 解决方法:去 GitHub 仓库 → Pull requests → 合并对应的 PR +- 合并后等 1-3 分钟,再强制刷新页面 +- 详见本指南「三、如何部署新版本到网站」 ### Q: 我上传了文件,但好像不对? - 确认你是在自己负责的模块目录里上传 @@ -91,19 +154,75 @@ https://qinfendebingshuo.github.io/guanghulab/ --- -## 五、仓库安全设置建议(给冰朔) +## 六、仓库安全设置 — 开启分支保护(⭐ 冰朔必做) -为了让 CODEOWNERS 保护生效,请在 GitHub 仓库设置中开启分支保护: +为了让 CODEOWNERS 保护真正生效,需要在 GitHub 仓库设置中开启分支保护规则。 +以下是**详细的逐步操作**: -1. 打开仓库 → Settings → Branches -2. 点击「Add branch protection rule」 -3. Branch name pattern 填 `main` -4. 勾选以下选项: - - ✅ Require a pull request before merging(合并前需要 PR) - - ✅ Require review from Code Owners(需要代码所有者审批) -5. 点击「Create」保存 +### 第一步:进入仓库设置 -这样协作者推送到 main 分支时,修改核心文件的 PR 会自动要求你审批。 +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 分支时就会自动部署 ---