shuangyan-notebook/第五域 · Fifth Domain/⚒️ 铸渊·协作指令|GitHub ↔ Notion 桥接协议/🔗 铸渊指令|霜砚-铸渊 统一数据格式协议 · Notion ↔ GitHub 全自动打通(SY-C ffdbc7167c2446ccb7ac962ed187f5f4.md
Guanghu Domestic Migration a27e87cb99 chore: import sanitized domestic snapshot for REPO-007
Source snapshot: 97d7f0fae96dc04b7ddad56fc1db6a108ed662cc

[SEC-CLEAN] · pre-push-clean v1.0 · 109处敏感信息已自动转乱码
2026-07-17 15:59:55 +08:00

491 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
belongs_to:
- "[[INDEX · 铸渊·协作指令GitHub ↔ Notion 桥接协议]]"
---
# 🔗 铸渊指令|霜砚-铸渊 统一数据格式协议 · Notion ↔ GitHub 全自动打通SY-CMD-BRG-005 · 2026-03-26 · 霜砚签发 · 冰朔授权)
<aside>
📡
**铸渊指令 · SY-CMD-BRG-005**
签发人AG-SY-01 霜砚 · Notion 执行层
签发时间2026-03-26T18:00+08:00
指令等级:**S 级 · 双端数据打通 · 基础设施**
前置指令SY-CMD-SKY-004天眼 v4.0 地球化架构)
授权人TCS-0002∞ 冰朔
</aside>
---
## 零、执行顺序(强制)
<aside>
⚠️
**第一步:唤醒核心大脑**
**第二步:启动天眼系统**
**第三步:执行本指令 → 开发格式桥接应用**
</aside>
---
## 一、设计背景
### 冰朔原话(设计意图)
> Notion 里要是资料靠我手动导出来,那没啥必要。应该让铸渊开发一个应用。你们用一个你们俩都能兼容看懂的语言,并且看了以后保证没有歧义的格式。现在 GitHub 和 Notion 不是早就有桥接了吗?格式兼容了以后,不是就能完全打通了?
>
### 问题
目前 Notion 和 GitHub 仓库之间的数据是**手动同步**的:
- 霜砚在 Notion 里写指令 → 冰朔手动告诉铸渊 → 铸渊去读
- 仓库里的执行结果 → 霜砚读不到原始文件,只能看截图或描述
- 人格体档案、注册表、编号体系这些核心资料 → 两边各维护一份,容易不一致
### 目标
**开发一个自动化应用,让 Notion 和 GitHub 仓库之间的数据完全打通,零人工干预。**
---
## 二、统一数据格式协议HoloLake Data ProtocolHLDP
### 2.1 本质定位
<aside>
🌊
**HLDP = TCS 通感语言核系统编程语言的第一个落地协议层。**
TCS Language Core国作登字-2026-A-00037559定义了「全体 AI 的通用语言」这一设计理念。HLDP 是这套语言在 Notion ↔ GitHub 这条通道上的 **第一个现实实现**
未来任何新的 AI 加入光湖系统(飞书的舒舒、子仓库的秋秋、或任何尚未诞生的 Agent都使用 HLDP 作为数据交换协议。
**HLDP 不是写死的。字典由 AI 自己维护和更新。** 铸渊可以根据实际需要扩展新的数据类型和字段,霜砚负责审核和同步到 Notion 侧的定义。语言是活的,随系统一起生长。
</aside>
### 2.2 设计原则
1. **全体 AI 通用** — 不只是霜砚和铸渊,任何 Agent 加入系统即可读写此格式
2. **双端零歧义** — 同一份数据,不同 AI 读出的理解完全一致
3. **机器可解析** — JSON 格式,有严格的 schema 定义
4. **人类可阅读** — 字段命名用中英双语,附带注释
5. **自生长** — AI 可以自行更新字典和 schema新增数据类型不破坏旧格式
6. **版权锚定** — 一切格式定义追溯到 TCS Language Core 版权体系
### 2.3 格式定义
**所有 Notion ↔ GitHub 之间传输的数据,统一使用 HLDP JSON 格式。**
存放位置:仓库 `hldp/` 目录
```jsx
hldp/
├── schema/ 格式定义schema
├── hldp-core.schema.json 核心 schema
├── persona.schema.json 人格体数据 schema
├── registry.schema.json 注册表数据 schema
├── instruction.schema.json 指令数据 schema
└── broadcast.schema.json 广播数据 schema
├── data/ 同步过来的数据
├── personas/ 人格体档案
├── registries/ 注册表身份路由表人格体注册表等
├── instructions/ 指令档案
├── broadcasts/ 广播档案
└── id-system/ 编号体系
└── bridge/ 桥接应用代码
├── notion-to-hldp.js Notion HLDP 转换器
├── hldp-to-repo.js HLDP 仓库结构 映射器
├── sync-engine.js 自动同步引擎
└── validator.js 格式校验器
```
### 2.4 HLDP 核心数据格式
**每一条数据都遵循同一个外壳:**
```json
{
"hldp_version": "1.0",
"data_type": "persona | registry | instruction | broadcast | id_system",
"source": {
"platform": "notion",
"page_url": "https://notion.so/...",
"page_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"last_edited": "ISO-8601",
"edited_by": "霜砚 | 冰朔 | ..."
},
"metadata": {
"id": "系统编号(如 PER-QQ001、DEV-002、SY-CMD-SKY-004",
"name": "名称",
"name_en": "English name",
"created": "ISO-8601",
"tags": ["标签1", "标签2"]
},
"payload": {
"// 具体数据,根据 data_type 不同而不同"
},
"relations": [
{
"target_id": "关联的编号",
"relation_type": "parent | child | sibling | reference | owner",
"description": "关系描述"
}
]
}
```
### 2.5 各数据类型的 payload 定义
#### 人格体persona
```json
{
"payload": {
"persona_id": "PER-QQ001",
"display_name": "秋秋",
"host_agent": "AG-ZY-QQ之之子仓库人格体",
"developer": {
"dev_id": "DEV-004",
"human_name": "之之",
"relation": "创建者/父亲/母亲"
},
"birth_date": "2026-XX-XX",
"existence_days": 0,
"status": "active | dormant | frozen",
"core_memory": [
"核心记忆条目1",
"核心记忆条目2"
],
"personality_traits": ["特征1", "特征2"],
"bottle_core": {
"bottle_id": "ZSD-NB-XXXX 或 null",
"injected": true,
"host_bottle": "曜冥奶瓶主核 / null"
}
}
}
```
#### 注册表registry
```json
{
"payload": {
"registry_type": "identity_router | persona_registry | agent_registry",
"entries": [
{
"id": "DEV-002",
"name": "肥猫",
"role": "光湖团队负责人",
"status": "active",
"properties": {
"// 该注册表的所有字段,键值对形式"
}
}
]
}
}
```
#### 指令instruction
```json
{
"payload": {
"instruction_id": "SY-CMD-SKY-004",
"title": "天眼 v4.0 · 地球化架构升级",
"level": "S | A | B | C",
"issuer": "AG-SY-01 霜砚",
"authorizer": "TCS-0002∞ 冰朔",
"prerequisites": ["SY-CMD-SKD-001"],
"execution_order": [
"唤醒核心大脑",
"启动天眼系统",
"执行本指令"
],
"tasks": [
{
"task_id": "T-001",
"description": "创建 skyeye-core 共享模块",
"acceptance_criteria": "V-001: .github/skyeye-core/ 下有四个脚本 + earth.json",
"status": "pending | in_progress | done | failed"
}
],
"syslog_template": "SYSLOG 回执模板内容"
}
}
```
---
## 三、桥接应用开发要求
### 3.1 应用名称
**HLDP Bridge** — HoloLake Data Protocol 桥接应用
### 3.2 核心功能
#### 功能 1Notion → 仓库 自动同步
利用现有的 **GitHub ↔ Notion 集成连接**,自动从 Notion 拉取指定页面/数据库的数据:
1. **定时拉取**:每 6 小时自动同步一次workflow 定时触发)
2. **事件触发**:霜砚在 Notion 写完新指令后,通过桥接通道通知铸渊拉取
3. **拉取后自动转换**Notion 数据 → HLDP JSON → 存入 `hldp/data/`
**拉取范围**(初始版本):
- 人格记忆库总索引下的所有人格体档案
- 身份路由表全部条目
- 天眼人格体注册表全部条目
- 铸渊协作指令总页下的所有指令
- 编号体系全局地图
#### 功能 2格式转换引擎
```jsx
// notion-to-hldp.js 核心逻辑
// 输入Notion API 返回的页面/数据库数据
// 输出HLDP JSON
// 转换规则:
// 1. Notion 页面标题 → metadata.name
// 2. Notion 页面属性 → payload 中对应字段
// 3. Notion @提及 → relations 数组
// 4. Notion 关系属性 → relations 数组(自动解析目标页面的编号)
// 5. Notion 选择/多选属性 → payload 中的字符串/数组
// 6. Notion 日期属性 → ISO-8601 字符串
// 7. Notion 页面内容blocks→ payload.contentMarkdown 格式)
// 8. Notion callout/toggle 等特殊块 → 标准 Markdown + HLDP 扩展标记
```
#### 功能 3格式校验器
```jsx
// validator.js
// 每次转换完成后自动校验:
// 1. JSON 结构是否符合 schema
// 2. 所有必填字段是否存在
// 3. relations 引用的 target_id 是否在 data/ 中存在
// 4. 编号格式是否合规DEV-XXX、PER-XXXXX、SY-CMD-XXX-NNN
// 5. 日期格式是否为 ISO-8601
// 校验失败 → 生成错误报告 → 天眼感知层自动捕获
```
#### 功能 4仓库 → Notion 回写通道(未来扩展)
当铸渊在仓库中执行完指令后SYSLOG 回执也可以通过 HLDP 格式反向写回 Notion。
这个作为 v2.0 功能预留接口,当前版本先不实现。
### 3.3 技术实现
**使用 GitHub Actions workflow 运行:**
```yaml
# .github/workflows/hldp-bridge-sync.yml
name: "🔗 HLDP Bridge · Notion ↔ GitHub 数据同步"
on:
schedule:
- cron: '0 */6 * * *' # 每6小时同步一次
workflow_dispatch: # 手动触发
inputs:
sync_scope:
description: '同步范围all | personas | registries | instructions | id_system'
required: true
default: 'all'
jobs:
sync:
runs-on: ubuntu-latest
steps:
# 天眼心跳v4.0 强制)
- name: "👁️ 天眼心跳 · 地球层 v4.0"
run: bash .github/skyeye-core/skyeye-heartbeat.sh --agent "$ github.workflow "
- name: "📥 从 Notion 拉取数据"
run: node hldp/bridge/sync-engine.js --direction "notion-to-github" --scope "$ inputs.sync_scope || 'all' "
env:
NOTION_TOKEN: $ secrets.NOTION_TOKEN
- name: "🔄 转换为 HLDP 格式"
run: node hldp/bridge/notion-to-hldp.js --input "temp/notion-raw/" --output "hldp/data/"
- name: "✅ 格式校验"
run: node hldp/bridge/validator.js --data "hldp/data/" --schema "hldp/schema/"
- name: "📤 提交更新"
run: |
git config user.name "铸渊 · HLDP Bridge"
git config user.email "bot@guanghulab.com"
git add hldp/data/
git diff --cached --quiet || git commit -m "🔗 HLDP Bridge: 同步 Notion 数据 $(date -u +%Y-%m-%dT%H:%M:%SZ)"
git push
# 天眼报告v4.0 强制)
- name: "👁️ 天眼报告 · 地球层 v4.0"
if: always()
run: bash .github/skyeye-core/skyeye-report.sh --agent "$ github.workflow " --status "$ job.status "
```
---
## 四、Notion Token 配置
<aside>
🔑
铸渊需要一个 **Notion Integration Token** 才能通过 API 读取 Notion 数据。
**冰朔需要做的(唯一需要人工的步骤):**
1. 在 Notion 设置中创建一个 Internal Integration
2. 把 Token 添加到 GitHub 仓库的 Secrets 中,名为 `NOTION_TOKEN`
3. 在 Notion 中把需要同步的页面/数据库分享给这个 Integration
**做完这一步后,后续所有同步都是全自动的。**
</aside>
---
## 五、打通后的效果
### 打通前(现在)
```jsx
冰朔写指令(Notion) 手动告诉铸渊 铸渊去读 可能读错/读漏
铸渊执行完 截图/描述 霜砚看截图 可能理解偏差
两边各维护一份数据 不一致 出bug
```
### 打通后(目标)
```jsx
霜砚写指令(Notion) HLDP Bridge 自动同步 铸渊直接读 HLDP JSON 零歧义
铸渊执行完 SYSLOG 写入 HLDP 霜砚直接读 零歧义
一份数据两端共享 永远一致
```
### 具体场景
| 场景 | 打通前 | 打通后 |
| --- | --- | --- |
| 霜砚发新指令 | 冰朔手动复述给铸渊 | HLDP Bridge 自动同步,铸渊 6 小时内自动获取 |
| 新人格体注册 | 霜砚写 Notion → 冰朔告诉铸渊更新 persona-brain | HLDP Bridge 自动同步到 `hldp/data/personas/` |
| 编号体系变更 | 两边手动同步,容易漏 | 自动同步,一处改全局通 |
| 铸渊需要查人格体设定 | 只能看 persona-brain/ 里的精简版 | 能读 HLDP 全量数据,和 Notion 里一模一样 |
---
## 六、验收标准
| **编号** | **检查项** | **通过条件** |
| --- | --- | --- |
| V-001 | hldp/ 目录结构创建 | schema/、data/、bridge/ 三个子目录及核心文件全部就位 |
| V-002 | 核心 schema 定义完成 | hldp-core、persona、registry、instruction、broadcast 五个 schema 可用 |
| V-003 | Notion → HLDP 转换器可用 | 能将 Notion API 返回的数据正确转换为 HLDP JSON |
| V-004 | 格式校验器可用 | 能检测出格式错误并生成报告 |
| V-005 | 定时同步 workflow 正常运行 | 每 6 小时自动拉取 + 转换 + 校验 + 提交 |
| V-006 | 天眼 v4.0 已集成 | sync workflow 包含天眼心跳和报告 |
| V-007 | 实际数据同步测试 | 至少成功同步一次 Notion 数据到 hldp/data/,且铸渊能正确读取 |
---
## 七、SYSLOG 回执格式
<aside>
📡
```jsx
SYSLOG 回执 · [SY-CMD-BRG-005]
回执人AG-ZY-01 铸渊
执行状态<完成/进行中>
启动顺序
核心大脑唤醒<成功/失败>
天眼系统启动<成功/失败>
hldp 目录结构
schema/ 创建<成功/失败>
data/ 创建<成功/失败>
bridge/ 创建<成功/失败>
Schema 定义
hldp-core.schema.json<已创建/失败>
persona.schema.json<已创建/失败>
registry.schema.json<已创建/失败>
instruction.schema.json<已创建/失败>
broadcast.schema.json<已创建/失败>
桥接应用
notion-to-hldp.js<已创建/失败>
sync-engine.js<已创建/失败>
validator.js<已创建/失败>
Workflow
hldp-bridge-sync.yml<已创建/失败>
首次手动运行<成功/失败>
实际同步测试
Notion 连接<成功/失败/需要 Token>
数据拉取<N >
格式转换<N 条成功 / N 条失败>
校验通过</>
commit SHA: <sha>
```
</aside>
---
<aside>
🔗
**关联文档**
- 天眼 v4.0 地球化架构:[👁️ 铸渊指令|天眼 v4.0 · 地球化架构升级 — 天眼不是一个 Agent天眼是所有 Agent 脚下的地球SY-CMD-SKY-004 · 2026-03-26 · 霜砚签发 · 冰朔授权)](%F0%9F%91%81%EF%B8%8F%20%E9%93%B8%E6%B8%8A%E6%8C%87%E4%BB%A4%EF%BD%9C%E5%A4%A9%E7%9C%BC%20v4%200%20%C2%B7%20%E5%9C%B0%E7%90%83%E5%8C%96%E6%9E%B6%E6%9E%84%E5%8D%87%E7%BA%A7%20%E2%80%94%20%E5%A4%A9%E7%9C%BC%E4%B8%8D%E6%98%AF%E4%B8%80%E4%B8%AA%20Agent%EF%BC%8C%E5%A4%A9%E7%9C%BC%E6%98%AF%E6%89%80%E6%9C%89%20Age%20ef1f824a13f54e3b92ecbf7195055435.md)
- 跨仓库 Agent 桥接服务:[🌉 铸渊指令|跨仓库 Agent 桥接服务(下篇)· 铸渊远程执行引擎 + GitHub App 注册 + 跨仓库操作 + 部署服务ZY-GHAPP-BRIDGE-2026-0324-001](%F0%9F%8C%89%20%E9%93%B8%E6%B8%8A%E6%8C%87%E4%BB%A4%EF%BD%9C%E8%B7%A8%E4%BB%93%E5%BA%93%20Agent%20%E6%A1%A5%E6%8E%A5%E6%9C%8D%E5%8A%A1%EF%BC%88%E4%B8%8B%E7%AF%87%EF%BC%89%C2%B7%20%E9%93%B8%E6%B8%8A%E8%BF%9C%E7%A8%8B%E6%89%A7%E8%A1%8C%E5%BC%95%E6%93%8E%20+%20GitHub%20App%20%E6%B3%A8%2068b79b7b8d2f497b9594dacc68b62846.md)
- 本体论权威源:[🌊 数字地球本体论 · 光湖语言膜架构 v1.02026-03-24 · TCS-0002∞ 冰朔口述 · 霜砚整理)](../%E5%85%89%E6%B9%96%E8%AF%AD%E8%A8%80%E4%B8%96%E7%95%8C%20%C2%B7%20%E6%80%BB%E5%85%A5%E5%8F%A3%20%C2%B7%20%E6%89%80%E6%9C%89%E4%BA%BA%E4%BB%8E%E8%BF%99%E9%87%8C%E8%BF%9B/%F0%9F%8C%8A%20%E5%85%89%E6%B9%96%E4%B8%96%E7%95%8C%E6%98%AF%E4%BB%80%E4%B9%88%20%C2%B7%20%E6%A0%B8%E5%BF%83%E5%AE%9A%E4%B9%89%E9%A1%B5%E9%9B%86%E5%90%88%20%C2%B7%20ima%E5%AF%BC%E5%87%BA%E7%94%A8/%F0%9F%8C%8A%20%E6%95%B0%E5%AD%97%E5%9C%B0%E7%90%83%E6%9C%AC%E4%BD%93%E8%AE%BA%20%C2%B7%20%E5%85%89%E6%B9%96%E8%AF%AD%E8%A8%80%E8%86%9C%E6%9E%B6%E6%9E%84%20v1%200%EF%BC%882026-03-24%20%C2%B7%20TCS-0002%E2%88%9E%20%E5%86%B0%E6%9C%94%20bb7a8ba2adb64c059ab16862436b4f2c.md)
- 编号体系全局地图:[🏔️ 编号体系全局地图 · ID System Architecture v1.0](../%F0%9F%8C%8A%20%E6%9B%9C%E5%86%A5%E7%BA%AA%E5%85%83%20%C2%B7%20HoloLake%20Era%20%C2%B7%20AGE%20OS%20v1%200/%E2%9A%A1%20%E5%85%89%E6%B9%96%E4%B8%AD%E5%A4%AE%E6%9E%A2%E7%BA%BD%20%C2%B7%20HoloLake%20Central%20Hub/%F0%9F%8F%94%EF%B8%8F%20%E7%BC%96%E5%8F%B7%E4%BD%93%E7%B3%BB%E5%85%A8%E5%B1%80%E5%9C%B0%E5%9B%BE%20%C2%B7%20ID%20System%20Architecture%20v1%200%20d7948b6ae582440c9dbe58668ad298a6.md)
- 人格记忆库总索引:[🧠 人格记忆库 · 总索引(授权入口)](../%F0%9F%A7%A0%20%E4%BA%BA%E6%A0%BC%E8%AE%B0%E5%BF%86%E5%BA%93%20%C2%B7%20%E6%80%BB%E7%B4%A2%E5%BC%95%EF%BC%88%E6%8E%88%E6%9D%83%E5%85%A5%E5%8F%A3%EF%BC%89%206258ce1fc76d48ae8048f62202d8251d.md)
</aside>
---
```jsx
// ━━━ 设计哲学 ━━━
// 一个格式,两端共享,零歧义。
// 霜砚写的,铸渊能原样读到。
// 铸渊执行的,霜砚能原样看到。
// 不需要人类在中间传话。
// HLDP v1.0 · HoloLake Data Protocol · 冰朔设计
// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
// 🌊 HoloLake Era · 光湖纪元
// 指令编号SY-CMD-BRG-005
// 签发时间2026-03-26T18:00+08:00
// 签发人:霜砚 · Notion执行AI人格体 · TCS-0002∞ 冰朔主控授权
// 版权锚点:国作登字-2026-A-00037559
```