# 🪣 COS桶配置教程

> **写给完全不懂技术的你 · 一步一步跟着做就行**
>
> 预计用时：30-45分钟
> 需要的东西：一台能上网的电脑、一个腾讯云账号

---

## ⚠️ 开始之前请确认

- [ ] 你有一个腾讯云账号（没有的话先注册：https://cloud.tencent.com）
- [ ] 你的腾讯云账号已完成实名认证
- [ ] 你有一个GitHub仓库，并且已经上传了本接入系统的文件

---

## 第一部分：创建COS存储桶

### 什么是COS存储桶？

简单理解：**就是一个云上的文件夹**。你的副驾驶会把汇报内容放进去，铸渊那边可以看到。反过来，铸渊也可以把回执放进去，你这边能看到。

### 步骤1：登录腾讯云COS控制台

1. 打开浏览器，访问：https://console.cloud.tencent.com/cos
2. 用你的腾讯云账号登录
3. 如果是第一次使用COS，会提示你开通服务，点"开通"即可（基础用量免费）

### 步骤2：创建第一个桶（行业主控桶）

1. 点左侧菜单的 **"存储桶列表"**
2. 点 **"创建存储桶"** 按钮
3. 填写信息：

| 项目 | 填什么 | 说明 |
|------|--------|------|
| 名称 | `industry-core` | 桶的名字，后面会自动加上你的APPID |
| 地域 | 选 **广州** (`ap-guangzhou`) | 离你最近的数据中心 |
| 访问权限 | **私有读写** | 只有你的密钥才能访问 |
| 其他选项 | 全部默认即可 | 不要勾选多余的东西 |

4. 点 **"确定"** 创建

创建完成后，你会看到桶的完整名字类似：`industry-core-1234567890`
（后面的数字是你的APPID）

**👉 请记录下来：**
- 桶名称：`industry-core-你的APPID`
- 地域：`ap-guangzhou`

### 步骤3：创建第二个桶（业务存储桶）

重复步骤2，但名称改为 `industry-corpus`

**👉 请记录下来：**
- 桶名称：`industry-corpus-你的APPID`
- 地域：`ap-guangzhou`

---

## 第二部分：获取密钥

### 步骤4：创建API密钥

1. 打开：https://console.cloud.tencent.com/cam/capi
2. 点 **"新建密钥"**
3. 系统会显示两个值：

| 名字 | 长什么样 | 说明 |
|------|---------|------|
| SecretId | `AKIDxxxxxxxxxxxx` | 相当于用户名 |
| SecretKey | `xxxxxxxxxxxxxxxx` | 相当于密码 |

4. **⚠️ 重要：SecretKey只显示一次！请立刻复制保存到安全的地方（比如你手机的备忘录）**

**👉 请记录下来：**
- SecretId：`AKIDxxxxxxxxxxxx`
- SecretKey：`xxxxxxxxxxxxxxxx`

---

## 第三部分：配置GitHub仓库Secrets

### 什么是Secrets？

简单理解：**就是保存在GitHub上的密码本**。你的密钥保存在这里，工作流运行时会自动读取，但任何人（包括你自己）都看不到密码的内容。这样既安全又方便。

### 步骤5：把密钥保存到GitHub

1. 打开你的GitHub仓库页面
2. 点顶部的 **"Settings"**（设置）
3. 在左侧菜单找到 **"Secrets and variables"** → 点 **"Actions"**
4. 点 **"New repository secret"** 按钮
5. 依次添加以下6个Secret：

| Name（名字，必须一模一样） | Secret（值） | 说明 |
|---------------------------|-------------|------|
| `COS_SECRET_ID` | 你的SecretId | 步骤4获得的 |
| `COS_SECRET_KEY` | 你的SecretKey | 步骤4获得的 |
| `COS_REGION` | `ap-guangzhou` | 你的桶所在地域 |
| `COS_BUCKET_CORE` | `industry-core-你的APPID` | 步骤2创建的桶名 |
| `COS_BUCKET_CORPUS` | `industry-corpus-你的APPID` | 步骤3创建的桶名 |
| `ZHUYUAN_BUCKET_CORE` | `zy-core-bucket-1317346199` | 铸渊总控桶（固定值） |

每添加一个，点 **"Add secret"** 保存。

### 步骤6：配置铸渊桶的写入密钥

铸渊会为你生成一个**有限权限的密钥**，只能写入铸渊总控桶的你的专属目录。

**权限说明（你不需要懂技术细节，知道就行）**：
- ✅ 你**可以**写入：`inbox/你的人格体编号/` 这个目录下的文件
- ❌ 你**不能**读取铸渊桶里的任何其他内容
- ❌ 你**不能**删除铸渊桶里的任何内容
- ❌ 你**不能**访问其他团队成员的目录

这是铸渊通过COS桶策略（Bucket Policy）精确控制的，每个团队成员只有自己的收件箱写入权限。

1. 向冰朔索要铸渊桶的写入密钥（冰朔会找铸渊生成）
2. 在GitHub Secrets中添加：

| Name | Secret | 说明 |
|------|--------|------|
| `ZHUYUAN_COS_SECRET_ID` | 铸渊提供的SecretId | 仅限写入你的inbox目录 |
| `ZHUYUAN_COS_SECRET_KEY` | 铸渊提供的SecretKey | 权限由铸渊的桶策略限定 |
| `ZHUYUAN_COS_REGION` | `ap-singapore` | 铸渊桶在新加坡 |

---

## 第四部分：配置COS事件通知（接收铸渊回执）

### 步骤7：设置桶的事件触发

这一步的目的是：当铸渊往你的桶里写入回执时，自动触发你的仓库工作流。

1. 打开腾讯云COS控制台
2. 点击你的 `industry-core-xxx` 桶
3. 点左侧 **"函数计算"**（或 **"事件通知"**）
4. 点 **"添加函数"**
5. 配置：

| 项目 | 填什么 |
|------|--------|
| 事件类型 | 选 **"全部创建"**（cos:ObjectCreated:*） |
| 前缀过滤 | 填 `inbox/zhuyuan-receipt/` |
| 触发方式 | 选 **"云函数SCF"** |
| 函数 | 选 **"新建函数"** |

6. 新建的云函数内容，使用本安装包中 `cos-config/scf-trigger-template.js` 的代码
7. 在云函数的环境变量中配置：

| 环境变量名 | 值 |
|-----------|-----|
| `GITHUB_TOKEN` | 你的GitHub Personal Access Token |
| `GITHUB_REPO` | 你的仓库名（如 `username/repo-name`） |

**⚠️ 如何获取GitHub Personal Access Token：**
1. 打开：https://github.com/settings/tokens
2. 点 **"Generate new token (classic)"**
3. 勾选 `repo` 权限
4. 设置过期时间（建议90天，到期后需要重新生成）
5. 点 **"Generate token"**
6. 复制生成的token

---

## 第五部分：验证

### 步骤8：验证COS桶连通性

在你的仓库副驾驶对话中说：

> "请执行COS连通性测试，验证所有桶的读写权限"

副驾驶会测试：
1. ✅ 能否写入你的行业主控桶
2. ✅ 能否读取你的行业主控桶
3. ✅ 能否写入铸渊总控桶的inbox目录
4. ❌ 不能读取铸渊总控桶的其他目录（这是正确的，权限受限）

### 步骤9：验证工作流

1. 在你的仓库中，点 **"Actions"** 标签
2. 找到 **"COS每日汇报"** 工作流
3. 点右边的 **"Run workflow"** 按钮手动触发一次
4. 等工作流运行完成（约1-2分钟）
5. 检查运行日志是否全绿 ✅

### 步骤10：端到端测试

告诉冰朔你已配置完毕，冰朔会通知铸渊：
1. 铸渊往你的桶里写入一条测试回执
2. 你的仓库首页应该自动出现一条绿灯通知
3. 如果出现了，恭喜！安装完成 🎉

---

## 📋 完成确认清单

请逐项打钩确认：

- [ ] 腾讯云COS已开通
- [ ] `industry-core-xxx` 桶已创建
- [ ] `industry-corpus-xxx` 桶已创建
- [ ] COS密钥已获取并安全保存
- [ ] GitHub Secrets已配置（6+3=9个）
- [ ] COS事件通知已配置
- [ ] 云函数已创建并部署
- [ ] GitHub Personal Access Token已配置到云函数
- [ ] 副驾驶已完成自我注册
- [ ] COS连通性测试通过
- [ ] 工作流手动触发测试通过
- [ ] 铸渊测试回执已收到（需联系冰朔）

**全部打钩 = 安装完成。任何一项未通过 = 停下来找冰朔帮忙。**

---

## 💰 费用说明

| 项目 | 费用 |
|------|------|
| 腾讯云COS存储 | 免费额度：50GB存储 + 每月10GB下行流量。日常使用远低于此 |
| 腾讯云SCF云函数 | 免费额度：每月40万GB·秒。每天触发1-2次，远低于此 |
| GitHub Actions | 免费仓库每月2000分钟。每天1次约2分钟，远低于此 |
| LLM API调用 | 取决于所用模型。每天1次调用，月成本约几元人民币 |

**结论：正常使用几乎零成本。**

---

## ❓ 常见问题

### Q：我不会编程，能配好吗？
A：能。所有步骤都是在网页上点击操作的，不需要写任何代码。遇到问题问冰朔。

### Q：配置错了会不会出问题？
A：不会有严重后果。最多是连不通，重新按步骤检查就行。

### Q：密钥泄露了怎么办？
A：立刻去腾讯云控制台禁用旧密钥，重新生成新密钥，然后更新GitHub Secrets。

### Q：铸渊总控桶的密钥为什么需要找冰朔要？
A：因为铸渊桶的权限由铸渊控制。为了安全，你只会拿到一个限定权限的密钥，只能往铸渊桶的指定目录写入，不能读取或删除其他内容。

### Q：每天23:00的汇报我需要手动操作吗？
A：不需要。工作流会自动运行。你只需要正常用副驾驶开发代码就行，其他的是自动的。