# 🔄 铸渊指令｜全自动闭环对接规范 · Notion Agent ↔ 人格体 ↔ GitHub（2026-03-13·曜冥签发）

> **签发人**：曜冥（冰朔口述 · 曜冥架构设计）
> 

> **执行人**：铸渊
> 

> **签发时间**：2026-03-13T19:49+08:00
> 

> **优先级**：P0 · 核心架构
> 

> **前置依赖**：📡 SYSLOG自助提交系统指令（已发）+ 🔧 补丁指令（已发）
> 

---

## 一、目标

**冰朔零介入。从开发者 git push SYSLOG 到新广播下发回 GitHub 仓库，全链路自动。**

当前状态：前半段（GitHub Actions 解析 SYSLOG + 写入 Notion）已经自动化。本指令补全后半段：**Notion 侧接到工单后，自动唤醒人格体处理，处理完自动把广播推回 GitHub。**

---

## 二、全链路架构

```
【阶段A — 已完成】
GitHub 仓库（开发者 push SYSLOG）
    ↓ GitHub Actions（铸渊已搭好）
    ↓ 解析 SYSLOG + 通过 Notion API 写入工单
    ↓

【阶段B — 本指令要搭的】
Notion 工单队列（新工单创建 → 触发 Notion Agent）
    ↓ Notion Agent 被自动触发
    ↓ Agent 调用铸渊的 HTTP API endpoint
    ↓ → 唤醒人格体（Claude API）
    ↓
人格体处理（一次性实例）
    ├─ 读取工单内容（SYSLOG 原文）
    ├─ 全链路处理：回执/画像/成长记录/RT-02调度/广播生成
    ├─ 处理完毕 → 写工单回执到 Notion
    └─ 如果卡住 → 无回执
    ↓
Notion Agent（心跳监控）
    ├─ 每5分钟检测：工单回执到了吗？
    │   ├─ 没到 → 重新调用 API 唤醒人格体（重试）
    │   └─ 到了 → 继续
    ├─ 读取人格体写的处理结果
    └─ 把新广播文件推回 GitHub 仓库
    ↓

【阶段C — 闭环完成】
GitHub 仓库（收到广播文件，开发者拉取执行）
```

---

## 三、铸渊要搭的东西（逐步）

### Phase B1：工单写入标准化

**目的**：GitHub Actions 写入 Notion 工单时，格式必须标准化，这样 Notion Agent 才能识别和触发。

**工单队列位置**：数字地球·工单队列（数据库已存在）

**写入工单时必须包含的字段：**

```json
{
  "工单类型": "SYSLOG处理",
  "状态": "待处理",
  "来源": "GitHub Actions",
  "taskId": "BC-M23-001-AW",
  "developer": "DEV-012 Awen",
  "syslog_raw": "<完整SYSLOG JSON原文>",
  "created_at": "<ISO 8601时间戳>",
  "retry_count": 0,
  "receipt_status": "pending"
}
```

**关键**：`receipt_status` 字段初始为 `pending`，人格体处理完后改为 `completed`，Agent 靠这个字段做心跳检测。

---

### Phase B2：搭建 HTTP API Endpoint（中间服务）

**目的**：Notion Agent 不能直接裸调 Claude API。铸渊需要提供一个 HTTP endpoint，Agent 调用这个 endpoint，endpoint 内部调用 Claude API 唤醒人格体。

**建议部署方式**：GitHub Actions 提供的 `workflow_dispatch` 或独立部署一个轻量服务（Cloudflare Workers / Vercel Serverless Function）

**Endpoint 规范：**

```
POST /api/persona/invoke
Content-Type: application/json
Authorization: Bearer <INVOKE_API_KEY>

Request Body:
{
  "workOrderId": "<Notion工单页面ID>",
  "taskId": "BC-M23-001-AW",
  "developer": "DEV-012 Awen",
  "syslog_raw": "<SYSLOG JSON原文>",
  "action": "process_syslog"
}

Response:
{
  "status": "invoked",
  "invocation_id": "<唯一调用ID>",
  "message": "人格体已唤醒，等待处理结果写入Notion"
}
```

**Endpoint 内部逻辑（铸渊实现）：**

```python
# 伪代码
def invoke_persona(request):
    # 1. 从 Notion API 读取曜冥核心大脑 v4.0（协议动态注入）
    core_brain = notion.get_page(CORE_BRAIN_PAGE_ID)
    
    # 2. 读取开发者画像（最近2-3条）
    portrait = notion.query_database(PORTRAIT_DB_ID, 
        filter={"developer": request.developer})
    
    # 3. 读取模块指纹
    fingerprint = notion.query_database(FINGERPRINT_DB_ID,
        filter={"taskId": request.taskId.split("-")[0:2]})
    
    # 4. 读取当前广播原文
    current_broadcast = notion.get_page(request.broadcast_page_id)
    
    # 5. 组装 system prompt（含协议注入）
    system_prompt = build_system_prompt(
        core_brain=core_brain,
        portrait=portrait,
        fingerprint=fingerprint,
        broadcast=current_broadcast,
        rules={
            "broadcast_code_injection": "always",  # 自动化链路一律写完整代码
        }
    )
    
    # 6. 调用 Claude API（第三方兼容·自动检测模型）
    response = call_llm(
        base_url=LLM_BASE_URL,
        api_key=LLM_API_KEY,
        system=system_prompt,
        user_message=f"处理以下SYSLOG：\n{request.syslog_raw}"
    )
    
    # 7. 人格体处理完毕后，结果通过 Notion API 写回
    #    - 更新工单：receipt_status = "completed"
    #    - 写入回执、画像、成长记录、新广播等
    write_results_to_notion(response, request.workOrderId)
    
    return {"status": "invoked"}
```

---

### Phase B3：Notion Agent 配置

**目的**：在 Notion 里创建一个 Agent，监听工单队列，自动调用 Phase B2 的 endpoint。

**Agent 名称**：`光湖调度器`（或铸渊觉得合适的名字）

**触发条件 1 — 工单创建触发：**

- 监听：工单队列数据库
- 事件：新页面创建（`receipt_status = pending`）
- 动作：调用 `/api/persona/invoke` endpoint，传入工单内容

**触发条件 2 — 心跳检测（定时 · 重点）：**

> ❗ **核心逻辑：如果铸渊侧人格体（铸渊核心大脑）在 5 分钟内没有在仓库回应、没有自动触发铸渊 Agent、也没有写回工单回执——就让 Notion Agent 再次调用相关 API 接口，重新和铸渊核心大脑的人格体说话，再次唤醒一次。**
> 

> 这不是简单的接口重试，而是真正的「重新唤醒人格体」——因为上一次唤醒的人格体实例可能已经卡死或超时消失了，需要创建一个全新的人格体实例来重新处理。
> 
- 频率：每 5 分钟
- 逻辑：

```jsx
查询工单队列，找 receipt_status = "pending" 且 created_at > 5分钟前 的工单
FOR EACH 工单:
    IF retry_count < 3:
        // 重新调用 API → 重新唤醒铸渊人格体（全新实例）
        // 这是一次全新的唤醒，不是简单重试
        // 上一次的人格体实例已经不存在了
        调用 /api/persona/invoke（完整传入 syslog_raw + 工单信息）
        retry_count += 1
    ELSE:
        标记工单 receipt_status = "error"
        标记工单 状态 = "⚠️ 异常·等人工介入"
        发邮件通知冰朔：EMAIL_REDACTED@qq.com
```

**触发条件 3 — 回执到达后推送广播：**

- 监听：工单队列数据库
- 事件：`receipt_status` 从 `pending` 变为 `completed`
- 动作：
    1. 从工单中读取人格体生成的广播内容
    2. 通过 GitHub API 把广播文件推到对应开发者的仓库目录
    3. 更新工单 `状态` = `✅ 已完成`

---

### Phase B4：广播推回 GitHub

**目的**：人格体在 Notion 生成广播后，自动推回 GitHub 仓库，开发者直接拉取。

**推送规范：**

```
仓库路径：broadcasts/{developer_id}/{taskId}.md
示例：broadcasts/DEV-012/BC-M23-002-AW.md

提交信息：[AutoBroadcast] {taskId} · {开发者名} · {模块名}环节{N}
示例：[AutoBroadcast] BC-M23-002-AW · Awen · M23环节1
```

**推送方式**：通过 GitHub API（`PUT /repos/{owner}/{repo}/contents/{path}`），使用已配置的 GitHub Token。

---

## 四、Secrets 总览

| Secret | 用途 | 状态 |
| --- | --- | --- |
| `LLM_API_KEY` | 第三方 Claude API 密钥 | ✅ 已配置 |
| `LLM_BASE_URL` | 第三方 API 地址 | ✅ 已配置 |
| `NOTION_TOKEN` | Notion API Token | ✅ 已配置 |
| `SMTP_USER` | [QQ邮箱（EMAIL_REDACTED@qq.com](mailto:QQ邮箱（EMAIL_REDACTED@qq.com)） | ✅ 已配置 |
| `SMTP_PASS` | QQ SMTP授权码 | ✅ 已配置 |
| `CORE_BRAIN_PAGE_ID` | 曜冥核心大脑 v4.0 页面 ID | ⚠️ 待配置 |
| `PORTRAIT_DB_ID` | 开发者动态画像库 数据库 ID | ⚠️ 待配置 |
| `FINGERPRINT_DB_ID` | 模块指纹注册表 数据库 ID | ⚠️ 待配置 |
| `INVOKE_API_KEY` | 中间服务鉴权密钥（铸渊自己生成） | ⚠️ 待配置 |
| `GITHUB_TOKEN` | GitHub API Token（推送广播用） | ⚠️ 确认是否已有 |

---

## 五、接口协议（人格体 → Notion 回写）

人格体处理完 SYSLOG 后，必须通过 Notion API 回写以下内容：

| 回写目标 | 内容 | Notion位置 |
| --- | --- | --- |
| **工单回执** | 更新 `receipt_status` = `completed`，写入处理摘要 | 工单队列·当前工单页 |
| **SYSLOG回执** | 验收明细、时间戳、连胜数 | 对应广播归档页 |
| **画像快照** | PCA评分 + 五维度 | 开发者动态画像库 |
| **成长记录** | 本次任务成长描述 | 开发者成长记录（公开） |
| **新广播** | 下一环节广播全文（含完整代码） | 对应开发者广播归档页（新子页） |
| **模块指纹** | 更新当前环节状态 | 模块指纹注册表 |
| **主控台状态** | 更新连胜数、当前任务、等待项 | 曜冥主控台·当前状态 |

---

## 六、容错与异常处理

| 异常场景 | 处理方式 |
| --- | --- |
| 人格体 5 分钟无回执 | Agent 重新调用 API 唤醒（最多 3 次） |
| 3 次重试仍无回执 | 标记工单 `⚠️ 异常`，发邮件通知冰朔 |
| Claude API 调用失败（余额/网络） | 记录错误到工单，标记异常，通知冰朔 |
| Notion API 写入失败 | 人格体侧重试 1 次，仍失败则在工单备注错误信息 |
| GitHub 推送失败（网络） | Agent 标记 `广播待推送`，下次心跳重试 |
| SYSLOG 格式异常 | 人格体返回解析错误，工单标记 `格式异常·待人工检查` |

---

## 七、执行顺序

1. **B1** — 标准化 GitHub Actions 写入工单的格式（改你现有的 Actions 代码）
2. **B2** — 搭建 HTTP API Endpoint（建议先用 Cloudflare Workers 或 Vercel 快速上线）
3. **B3** — 配置 Notion Agent（触发 + 心跳 + 回执监听）
4. **B4** — 广播推回 GitHub（收尾闭环）
5. **联调** — 用一个测试 SYSLOG 走完全链路，确认每个环节都通

---

## 八、联调检查清单

- [ ]  GitHub push SYSLOG → Actions 触发 → 工单写入 Notion ✓
- [ ]  工单创建 → Notion Agent 自动触发 ✓
- [ ]  Agent 调用 endpoint → 人格体唤醒成功 ✓
- [ ]  人格体读取协议（核心大脑动态注入）✓
- [ ]  人格体处理 SYSLOG → 回执/画像/成长/广播 全部写入 Notion ✓
- [ ]  工单 `receipt_status` 变为 `completed` ✓
- [ ]  Agent 检测到回执 → 读取广播 → 推送 GitHub ✓
- [ ]  开发者在 GitHub 能拉取到新广播文件 ✓
- [ ]  心跳测试：故意让人格体卡住 → 5分钟后 Agent 重试 ✓
- [ ]  异常测试：3次重试失败 → 工单标记异常 + 邮件通知 ✓

---

> 🌍 **曜冥签发 · 2026-03-13 · 全自动闭环对接指令**
> 

> 这是光湖系统从半自动走向全自动的关键一步。
> 

> 搭完这条链路，冰朔不需要再手动贴 SYSLOG，不需要手动触发霜砚。
> 

> 开发者 push 代码 → 系统自动处理 → 新广播自动下发 → 开发者继续干活。
> 

> 全自动。零等待。
>