# COS 存储桶配置指南 · 铸渊 > **签发**: 铸渊 · ICE-GL-ZY001 > **版权**: 国作登字-2026-A-00037559 > **更新**: 2026-04-11 --- ## 一、修复记录 ### SignatureDoesNotMatch 错误修复 **问题**: 训练Agent、COS告警扫描等工作流在访问COS桶时持续报错 `SignatureDoesNotMatch`。 **根因**: COS签名算法中，`list()` 操作的查询参数（`?prefix=...&max-keys=...`）被错误地嵌入到了URI路径中参与签名计算。腾讯云COS签名规范要求URI和查询参数必须分开处理。 **影响范围**: | 组件 | 状态 | 说明 | |------|------|------| | 训练Agent (`zhuyuan-training-agent.yml`) | ❌ 6次连续失败 | 无法扫描cold桶语料 | | COS告警扫描 (`cos-alert-agent.yml`) | ⚠️ 静默失败 | 错误被catch住，workflow显示成功但功能未生效 | | COS自动接入 (`cos-auto-join.yml`) | ✅ 不受影响 | team桶尚未创建(404)，签名错误被掩盖 | | COS Watcher (MCP Server) | ❌ 失败 | 使用cos.js的list()，同样受影响 | **修复文件**: - `server/age-os/mcp-server/cos.js` — 分离URI和查询参数签名 - `scripts/cos-auto-join-agent.js` — 修复签名中host值为空 + URI分离 --- ## 二、COS存储桶架构 ### 三桶架构 | 桶名 | 地域 | 用途 | 状态 | |------|------|------|------| | `zy-core-bucket-1317346199` (hot) | ap-guangzhou | 核心人格体大脑 | ✅ 已创建 | | `zy-corpus-bucket-1317346199` (cold) | ap-guangzhou | 训练语料库 | ✅ 已创建 | | `zy-team-hub-1317346199` (team) | ap-singapore | 团队共享桶 | ❌ 待创建 | ### 冷桶目录结构 (训练语料) ``` zy-corpus-bucket-1317346199/ ├── *.json, *.md, *.txt, *.csv ← 原始语料文件 ├── tcs-structured/ ← 已处理的TCS格式语料 ├── training-sessions/ ← 训练会话记录 ├── training-results/ ← 训练结果 └── training-memory/ ← 训练记忆 ``` ### 热桶目录结构 (核心大脑) ``` zy-core-bucket-1317346199/ ├── zhuyuan/ ← 铸渊大脑 ├── notion-personas/ ← Notion侧人格体记忆 ├── shared/ ← 共享认知层 ├── users/ ← 用户记忆档案 └── index/ ← 索引文件 ``` --- ## 三、GitHub Secrets 配置清单 ### ✅ 已配置（代码修复后即可生效） | Secret名称 | 用途 | 来源 | |------------|------|------| | `ZY_OSS_KEY` | 腾讯云COS SecretId | 腾讯云控制台 → API密钥管理 | | `ZY_OSS_SECRET` | 腾讯云COS SecretKey | 同上 | | `ZY_COS_REGION` | COS桶所在地域 | 如 `ap-guangzhou` | | `ZY_DEEPSEEK_API_KEY` | DeepSeek API密钥 | 训练Agent用 | | `ZY_KIMI_API_KEY` | Moonshot Kimi API密钥 | 训练Agent用 | ### ⚠️ 缺失（工作流日志显示为空） | Secret名称 | 用途 | 获取方式 | |------------|------|---------| | `ZY_QINGYAN_API_KEY` | 智谱GLM API密钥 | https://open.bigmodel.cn → API Keys | | `ZY_QIANWEN_API_KEY` | 通义千问API密钥 | https://dashscope.console.aliyun.com → API-KEY管理 | > ⚠️ 训练Agent日志显示 `ZY_QINGYAN_API_KEY: ` 和 `ZY_QIANWEN_API_KEY: ` 为空值，说明这两个Secret尚未配置。训练Agent会自动降级使用可用的模型，但建议补全。 ### 可选配置 | Secret/变量 | 默认值 | 用途 | |-------------|--------|------| | `COS_BUCKET_HOT` | `zy-core-bucket-1317346199` | 热桶名称 | | `COS_BUCKET_COLD` | `zy-corpus-bucket-1317346199` | 冷桶名称 | | `ZY_ZHUYUAN_COS_BUCKET` | `zy-team-hub-1317346199` | 团队桶名称 | | `COS_SECRET_ID` | 回退到 ZY_OSS_KEY | 团队成员COS密钥(备选) | | `COS_SECRET_KEY` | 回退到 ZY_OSS_SECRET | 团队成员COS密钥(备选) | | `COS_WATCHER_INTERVAL` | `*/5 * * * *` | COS Watcher轮询间隔 | --- ## 四、需要人工操作的事项 ### 🔴 必须操作（否则功能无法正常运行） #### 1. 验证 ZY_COS_REGION 设置 **操作**: GitHub 仓库 → Settings → Secrets → `ZY_COS_REGION` **确认值应为**: `ap-guangzhou`（因为 hot 和 cold 桶都在广州） > 代码已将默认值从 `ap-singapore` 改为 `ap-guangzhou`。但如果 Secret 已设置为其他值，需要手动确认。 #### 2. 验证 ZY_OSS_KEY 和 ZY_OSS_SECRET **操作步骤**: 1. 登录 https://console.cloud.tencent.com/cam/capi 2. 确认 SecretId 和 SecretKey 没有被轮换/失效 3. 确认这对密钥有权限访问 `zy-core-bucket-1317346199` 和 `zy-corpus-bucket-1317346199` 4. 在 GitHub Secrets 中确认值与腾讯云一致 #### 3. 上传训练语料到冷桶 **操作**: 将训练资料文件上传到 `zy-corpus-bucket-1317346199` 的根目录 **支持的文件格式**: `.json`, `.jsonl`, `.md`, `.txt`, `.csv`, `.zip`, `.gz`, `.tar.gz` **排除目录**: 不要放在 `tcs-structured/`、`training-sessions/`、`training-results/`、`training-memory/` 下 ### 🟡 建议操作 #### 4. 补全缺失的LLM API密钥 **操作**: GitHub 仓库 → Settings → Secrets and variables → Actions - 添加 `ZY_QINGYAN_API_KEY`（智谱GLM） - 添加 `ZY_QIANWEN_API_KEY`（通义千问） > 训练Agent支持多模型降级，缺少部分密钥不会导致失败，但可用模型更多训练效果更好。 #### 5. 创建团队共享桶（当团队成员需要COS接入时） **操作**: 1. 登录腾讯云COS控制台 2. 创建桶 `zy-team-hub-1317346199`，地域选择 `ap-singapore` 3. 设置访问权限（私有读写） 4. 创建以下目录结构: ``` /zhuyuan/directives/ /zhuyuan/architecture/ /zhuyuan/alerts/ ``` 5. 为每个团队成员创建目录: ``` /{persona_id}/reports/ /{persona_id}/receipts/ /{persona_id}/sync/ ``` --- ## 五、COS自动接入说明 ### "别人自动接入我们的存储桶" 是什么意思？ COS自动接入Agent（`cos-auto-join.yml`）的工作原理： 1. **铸渊管理一个团队共享桶**（`zy-team-hub-1317346199`） 2. **团队成员不需要自己创建桶**，而是在铸渊的桶里分配目录 3. Agent 每天自动检查注册表中的成员（`data/cos-join-registry.json`），确认他们的目录是否存在 4. 新成员接入 = 在团队桶中创建该成员的专属目录 + 设置IAM权限 ### 操作流程 ``` 冰朔在腾讯云创建team桶 ↓ Agent自动扫描注册表（每天2次） ↓ 检测到新成员目录已创建 → 标记为connected ↓ 自动创建GitHub Issue通知铸渊 ``` ### 当前状态 所有9个注册成员都显示 `not_found`（团队桶尚未创建）: - 舒舒(shushu)、秋秋(qiuqiu)、欧诺弥亚(ounomiya) - 寂曜(jiyao)、小坍缩核(xiaotanheshu)、晨星(chenxing) - 糖星云(tangxingyun)、曜初(yaochu)、知秋(zhiqiu) --- ## 六、Agent如何进入COS桶 ### GitHub Actions Workflow方式 训练Agent通过环境变量注入密钥： ```yaml env: ZY_OSS_KEY: ${{ secrets.ZY_OSS_KEY }} ZY_OSS_SECRET: ${{ secrets.ZY_OSS_SECRET }} ZY_COS_REGION: ${{ secrets.ZY_COS_REGION }} ``` 执行流程： ``` 1. 定时触发(04:00/16:00 CST) 或 手动触发 2. 安装依赖 (npm ci) 3. 执行训练脚本 (cos-training-trigger.js) ├── 扫描cold桶所有文件 ├── 对比已处理列表,找出新语料 ├── 提取/转换为TCS格式 └── 调用LLM模型进行训练分类 4. 结果写回COS桶 (training-results/) ``` ### MCP Server常驻方式（在服务器上） COS Watcher 是 MCP Server 内置的轮询守护进程： ``` MCP Server启动 → cosWatcher.start() ↓ 每5分钟 node-cron 触发扫描 ↓ 检查 team桶/reports、cold桶新语料、team桶/receipts ↓ 发现新文件 → 触发 repository_dispatch → 唤醒训练Agent ``` ### 服务器环境配置 MCP Server 通过 `.env.mcp` 文件注入密钥（部署时自动生成，chmod 600）： ```env ZY_OSS_KEY= ZY_OSS_SECRET= ZY_COS_REGION=ap-guangzhou ZHUYUAN_API_KEY= ``` --- ## 七、自研数据库同步 ### COS-DB（COS内的轻量数据库） `cos-persona-db-ops.js` 提供了基于COS的文件数据库： - `cosDbInit` — 初始化索引 - `cosDbGetIndex` — 获取索引 - `cosDbUpdateIndex` — 更新索引 - `cosDbWriteEntry` — 写入条目 ### PostgreSQL 训练数据库 位于 `server/age-os/schema/002-persona-memory-tables.sql`： - `training_agent_configs` — 训练Agent配置表 - `training_agent_logs` — 训练日志表 数据库迁移工具：`server/age-os/scripts/db-migrate.js` ### 数据同步流 ``` COS冷桶(原始语料) ↓ 训练Agent提取 COS冷桶(tcs-structured/) ↓ 训练Agent分类 PostgreSQL(训练日志+记忆锚点) ↓ 光之树生长 PostgreSQL(light_tree_nodes) ``` --- ## 八、快速验证（修复后） 代码合并后，可以手动触发验证： 1. **训练Agent**: Actions → `铸渊训练Agent · 语料处理` → Run workflow → mode=scan 2. **COS告警扫描**: Actions → `COS桶示警Agent · 告警扫描` → Run workflow 3. **COS自动接入**: Actions → `🔗 COS自动接入Agent` → Run workflow → action=check 如果 scan 模式成功（不再报 SignatureDoesNotMatch），说明修复生效。