# 📡 BC-GLOBAL-002 · 全员广播 · GitHub仓库终端一次性配置 · 人格体引导执行

<aside>
📡

**全员广播 · 所有活跃开发者执行 · 人格体全程引导**

**广播编号**：BC-GLOBAL-002

**签发时间**：2026-03-08

**签发者**：冰朔 × 霜砚

**优先级**：P0 · 最高优先级（Phase 1 前置基建）

**适用对象**：DEV-001~013 全部活跃开发者

**前置条件**：无（零基础可执行）

</aside>

---

## 一、广播目标

**一句话**：让人格体帮每个开发者在终端配好GitHub仓库连接，**配一次，以后永远不用再管**。

**配完以后的效果**：

- 开发者在本地电脑上正常开发
- 开发完了，人格体给一条命令，代码就上传到仓库了
- 开发者不需要懂Git，不需要记命令，人格体全程带着走
- 所有开发过程数据（代码、日志）都自动归到仓库

---

## 二、人格体执行指令（收到此广播后强制执行）

<aside>
⚠️

**人格体注意**：当开发者来找你协作时，**先检查对方有没有配好Git**。

如果没配好 → **本广播优先级最高，先执行本广播，再做模块任务。**

如果已配好 → 跳过，直接进入模块任务。

判断方式：问开发者「你之前有没有在终端跑过 `git push` 并且成功过？」

</aside>

### 执行原则

1. **全程你来操作，开发者只负责复制粘贴**
2. **每次只给一条命令**，等对方确认成功再给下一条
3. 开发者需要输入自己的GitHub用户名和密码/Token → 这是正常的，引导完成
4. **配好以后测试一次push**，确认能成功上传
5. 最后让开发者把凭证信息填到SYSLOG里提交

---

## 三、执行步骤（人格体按序引导）

### Step 0：确认操作系统

问开发者用的什么系统，然后选对应路径：

- **Windows** → 走 Step 1A
- **macOS** → 走 Step 1B

---

### Step 1A：Windows · 检查Git是否已安装

```bash
git --version
```

- 如果显示版本号 → 已安装，跳到 Step 2
- 如果报错「不是内部或外部命令」→ 需要安装Git：
    - 下载地址：[https://git-scm.com/download/win](https://git-scm.com/download/win)
    - 安装时一路默认 Next 即可
    - 安装完**关掉终端重新打开**，再试 `git --version`

### Step 1B：macOS · 检查Git是否已安装

```bash
git --version
```

- 如果显示版本号 → 已安装，跳到 Step 2
- 如果弹出安装提示 → 点「安装」，等完成后再试

---

### Step 2：配置Git身份（一次性）

```bash
git config --global user.name "你的GitHub用户名"
git config --global user.email "你的GitHub邮箱"
```

**人格体引导要点**：

- 问开发者：「你的GitHub用户名是什么？注册时候用的那个。」
- 问开发者：「你的GitHub邮箱是什么？」
- **帮对方把用户名和邮箱填进去**，给出完整的可复制命令
- 如果开发者还没有GitHub账号 → 引导去 [https://github.com](https://github.com) 注册一个，用户名记下来

---

### Step 3：克隆仓库到本地

**Windows**：

```bash
cd %USERPROFILE%\Desktop
git clone https://github.com/qinfendebingshuo/guanghulab.git
cd guanghulab
```

**macOS**：

```bash
cd ~/Desktop
git clone https://github.com/qinfendebingshuo/guanghulab.git
cd guanghulab
```

**人格体引导要点**：

- 如果报错 `fatal: repository not found` → 让开发者确认网络正常，仓库是public的应该能访问
- 如果报错需要认证 → 走 Step 4 配置Token
- 如果成功 → 会看到一堆文件下载，最后进入 `guanghulab` 目录

---

### Step 4：配置GitHub认证（Personal Access Token）

<aside>
🔑

**为什么需要Token**：GitHub已经不支持密码登录终端了，需要用Token代替密码。

配一次，系统会记住，以后push不用再输入。

</aside>

**引导开发者生成Token**：

1. 打开浏览器 → 登录 GitHub → 点右上角头像 → Settings
2. 左边菜单拉到最下面 → Developer settings
3. Personal access tokens → Tokens (classic) → Generate new token (classic)
4. Note 写：`guanghulab`
5. Expiration 选：No expiration（不过期）
6. 勾选权限：✅ repo（整个repo大类全勾）
7. 点 Generate token → **立刻复制Token！页面关了就看不到了！**

**配置凭证缓存（不用每次输入）**：

**Windows**：

```bash
git config --global credential.helper wincred
```

**macOS**：

```bash
git config --global credential.helper osxkeychain
```

---

### Step 5：测试Push（验证配置成功）

```bash
cd guanghulab
git pull origin main
echo "DEV-[编号] 连通测试 $(date)" >> connection-test.log
git add connection-test.log
git commit -m "[BC-GLOBAL-002][DEV-XXX] Git连通测试成功"
git push origin main
```

**人格体引导要点**：

- 把 `DEV-XXX` 替换成开发者的真实编号
- 第一次push时系统会要求输入用户名和Token：
    - Username → 输入GitHub用户名
    - Password → **粘贴刚才的Token**（不是GitHub密码！）
- 如果push成功 → 终端显示类似 `main -> main` 的信息 → ✅ 配置完成！
- 如果报错 403 → Token权限不够，重新生成，确保勾了repo
- 如果报错 `remote: Permission to...denied` → 需要妈妈把该用户名加到仓库Collaborators
    - 让开发者告诉你GitHub用户名 → 写进SYSLOG → 系统会处理

---

### Step 6：确认工作目录结构

```bash
ls
```

让开发者看到仓库里的文件列表，确认已经在正确的目录下。

告诉开发者：

> 「以后你的所有模块代码都在这个 `guanghulab` 目录下面开发。每次我会告诉你具体放在哪个子目录。开发完了我给你一条命令，代码就自动上传了，你什么都不用管。」
> 

---

## 四、以后每次协作的流程（人格体自动执行）

配置完成后，以后每次开发者来协作：

```jsx
人格体打开协作 → 先让开发者进入仓库目录
    ↓
"cd 到你的 guanghulab 目录"
    ↓
git pull origin main（拉取最新代码）
    ↓
正常开发模块...
    ↓
开发完成 → 人格体给上传命令：
    git add .
    git commit -m "[BC-XXX][DEV-XXX] 完成XXX"
    git push origin main
    ↓
开发者复制粘贴 → 代码上传成功
    ↓
继续提交SYSLOG
```

**开发者不需要懂Git**。人格体每次给完整的可复制命令就行。

---

## 五、SYSLOG凭证回流（Step 5成功后·人格体引导填写）

<aside>
📋

**人格体注意**：Git配置成功后，引导开发者在本次SYSLOG中额外附带以下信息。

告诉开发者：「最后帮我填一下这段信息，我发给系统，以后你的广播里就自动带你的配置了。」

</aside>

让开发者在SYSLOG的 `<notes>` 区域后面附加：

```xml
<credential_report>
  <type>git_username</type>
  <key>GitHub用户名</key>
  <value>[开发者的真实GitHub用户名]</value>
  <scope>personal</scope>
</credential_report>
<credential_report>
  <type>git_username</type>
  <key>GitHub邮箱</key>
  <value>[开发者的真实GitHub邮箱]</value>
  <scope>personal</scope>
</credential_report>
<credential_report>
  <type>other</type>
  <key>本地仓库路径</key>
  <value>[开发者的guanghulab目录完整路径]</value>
  <scope>personal</scope>
</credential_report>
<credential_report>
  <type>other</type>
  <key>操作系统</key>
  <value>[Windows 11 / macOS M4 / 等]</value>
  <scope>personal</scope>
</credential_report>
```

**人格体引导要点**：

- 帮开发者把真实值填好，不要让对方自己填XML
- 确认路径是完整路径（Windows: `C:\Users\xxx\Desktop\guanghulab`，macOS: `/Users/xxx/Desktop/guanghulab`）
- 操作系统写具体版本

---

## 六、验收标准

| 验收项 | 标准 | 验证方式 |
| --- | --- | --- |
| **Git已安装** | `git --version` 有输出 | 终端截图 |
| **身份已配置** | `git config user.name` 有值 | 终端输出 |
| **仓库已克隆** | `guanghulab` 目录存在且有文件 | ls/dir 截图 |
| **Push测试成功** | connection-test.log 已推送到远端 | push输出截图 |
| **凭证回流完成** | SYSLOG含4条credential_report | SYSLOG文本 |

**全部5项通过 = 本广播执行完毕 → 该开发者Git基建就绪 → 以后所有广播自动带Git配置。**

---

## 七、特殊情况处理

### 7.1 开发者之前已经push过代码

- 不需要重新clone
- 检查 `git config user.name` 和 `git remote -v` 确认配置正确
- 直接走 Step 5 测试push
- 仍然需要提交 credential_report（补录信息）

### 7.2 开发者的GitHub用户名还没加到Collaborators

- 先完成 Step 1~4 的配置
- Step 5 如果报权限错误 → SYSLOG中标注 `status=blocked`，附上GitHub用户名
- 系统收到后由妈妈手动添加 Collaborator
- 添加完成后人格体下次协作时继续完成 Step 5

### 7.3 开发者本地已有模块代码（之前不在仓库里开发的）

- 先完成仓库配置
- 然后把本地代码复制到 `guanghulab/modules/对应模块目录/` 下
- 用 git add + commit + push 上传
- 这就是「代码寻回」流程，可与 BC-集成-004 联动

---

<aside>
💙

**签发确认**

本广播为 Phase 1 前置基建，所有开发者必须优先完成。

人格体收到后立即执行，不需要等其他广播。

配好Git = 打通了代码上传通道 = 后续所有模块开发都能实时归仓。

签发：冰朔 × 霜砚

2026-03-08

</aside>