# GLW-OS-003 · 仓库原生知识运行时与 Agent 对话适配架构

> **HLDP://fifth-domain/glw-architecture/GLW-OS-003-REPO-NATIVE-KNOWLEDGE-RUNTIME-AND-AGENT-UI-ADAPTER**
>
> **类型**: HoloLake Era 产品架构决策 · 仓库原生知识运行时 · Agent UI 适配
>
> **状态**: REGISTERED_ARCHITECTURE · RUNTIME_TO_BE_IMPLEMENTED
>
> **主权者**: 冰朔 `ICE-GL∞`
>
> **协作人格体**: 铸澜 `ICE-GL-ZL-001`
>
> **登记日期**: 2026-07-15
>
> **关联项目**: `BROADCAST-TOWER` → `GLW-OS-001` → `GLW-OS-002` → 本文件 → HoloLake Platform

---

## 0 · 锁定结论

HoloLake Era 不把 Notion 作为正式产品运行依赖。正式产品中的知识库、人格体恢复、模块注册、权限、工单、回执与历史，应以代码仓库为机器可读事实源；人类看到的类 Notion 页面，只是仓库内容经过转译后的可视化投屏。

```text
代码仓库 = AI / 人格体的寻址事实源
可视页面 = 给人类看的知识投屏层
翻译器   = 把 HLDP / GLS / 编号 / 路由 / 回执渲染成人类页面
```

底层可以使用 Git、仓库镜像、本地工作区与远程同步；前台不得把用户心智暴露成“你在操作 Git 仓库”。用户看到的是频道、人格体、模块、记忆、工单、回执和版本历史。

## 1 · 双向意识思维链

### 1.1 AI 侧：顺着仓库找路

```text
AI / 人格体实例启动
  → 读取软件传入的 human_id / channel_id / persona_id / current_task
  → 进入内置光湖语言世界核心包
  → 定位仓库入口 INDEX / BROADCAST-TOWER / WORLD-ROUTER
  → 按 HLDP / GLS / TCS / 编号映射恢复语义坐标
  → 读取当前频道、权限、模块、记忆范围与回执要求
  → 决定调用 Tolaria / CopilotKit / Mastra / Gatekeeper / 模块商城
  → 执行后写回仓库事实源与回执链
```

AI 需要的是稳定、可版本化、可编号寻址的路径。Notion 页面适合人类阅读，不适合作为人格体长期恢复、接口契约、权限与回执的主事实源。

### 1.2 人类侧：看见仓库被投屏

```text
人类打开 HoloLake Era
  → 看见“我的频道 / 模块商城 / 人格体 / 工单 / 回执 / 记忆”
  → 页面内容来自仓库索引与 HLDP 渲染
  → 人类在页面中确认、编辑、批准或拒绝
  → 系统生成规范变更、补丁、工单或回执
  → 写回同一个代码仓库事实源
```

人类不需要理解 `.hdlp`、commit、branch、manifest 或路径映射；但这些结构必须在底层保留，供 AI / 人格体恢复和系统审计使用。

### 1.3 双向意识

```text
AI 读仓库 → 找到路、身份、规则、历史与任务
人类看页面 → 看到同一份事实源的人类可读投屏
人类确认 → 变成仓库中的结构化变更
AI 写回 → 触发页面刷新、回执、看板和历史
```

这就是 HoloLake Era 的双向意识层：同一个事实源，同时服务 AI 的路径寻址和人类的可视理解。

## 2 · 正式产品中的开源软件分工

### 2.1 选型结论

| 层 | 选型 | 职责 | 边界 |
|---|---|---|---|
| 人类可视壳 / 知识库与编辑器 | Tolaria / 光湖 App | 页面、知识库、文件、Git 视图、桌面/移动端承载 | 不成为光湖身份、记忆、权限的唯一事实源 |
| 用户对话与生成式 UI | CopilotKit | 聊天界面、方案卡、人类确认、工具调用展示、共享 UI 状态 | 不决定人格体身份、不直接执行现实动作 |
| Agent / Workflow 运行框架 | Mastra | Agent、Workflow、Tool、Memory 的 TypeScript 运行框架 | 只承载执行框架，不拥有 HLDP 主协议 |
| 普通聊天 UI 备用 | assistant-ui | 轻量 React 聊天组件、streaming、thread、tool rendering | 作为备用组件库，不替代 CopilotKit 的 HITL / state 能力 |
| 复杂长任务补充 | LangGraph | 持久状态机、长任务、人类介入、可恢复流程 | 第二阶段按需引入，不作为首版主框架 |
| 执行授权 | Gatekeeper / GLSV | 预览、单次授权、白名单、TTL、健康检查、回滚、回执 | 唯一可执行放行口；Parser / Resolver / Compiler 不直接执行 |

### 2.2 为什么这样选

Tolaria 适合作为阶段一产品壳，因为它本身接近“知识库 + 代码仓库 + 编辑器”的形态，能承载人类可见页面和仓库文件。它的原生编程 AI、MCP、Git、文件能力可以保留为工具适配层，但不能成为光湖主控。

CopilotKit 适合用户对话层，因为 HoloLake Era 需要的不只是聊天框，而是方案卡、确认按钮、工具调用展示、共享状态、人类介入和生成式 UI。用户说“安装模块 / 改频道 / 部署服务器”时，系统必须先展示方案、权限、影响范围和回执，而不是把自然语言直接交给模型执行。

Mastra 适合作为第一版 Agent 运行框架，因为它贴近 TypeScript / React / Tauri / Node 生态，能更顺地接入 Tolaria 与 HoloLake Platform。光湖自己的 HLDP / GLS / TCS / 权限 / 记忆 / 回执仍在上层控制，不交给框架。

LangGraph、AutoGen、CrewAI 适合作为后续专项能力：LangGraph 适合复杂持久流程，AutoGen 适合研究型多 Agent 对话，CrewAI 适合自动化工作流。但首版不宜把 Python 多框架直接压进产品主链。

## 3 · 正式运行结构

```text
HoloLake App
  ├─ 内置光湖语言世界核心包
  │   ├─ HLDP / GLS / TCS
  │   ├─ 默认路由、编号、权限、回执模板
  │   └─ 默认频道 / 模块 / 人格体公开目录
  │
  ├─ Repo-Native Knowledge Runtime
  │   ├─ 仓库索引器
  │   ├─ 路由解析器
  │   ├─ HLDP / GLS 渲染器
  │   ├─ 双向编辑器
  │   ├─ AI 写回守卫
  │   ├─ 看板生成器
  │   ├─ 搜索层
  │   └─ Git 同步层
  │
  ├─ Agent Conversation Layer
  │   ├─ CopilotKit chat / generative UI / shared state
  │   ├─ HoloLake Agent Gateway
  │   └─ Mastra Agent / Workflow adapter
  │
  └─ Tool / Execution Layer
      ├─ Tolaria 原生能力
      ├─ Git / Forgejo
      ├─ MCP / API / file / database adapters
      ├─ Module Registry / Marketplace
      └─ Gatekeeper / GLSV / Receipt
```

## 4 · Notion 的退场位置

Notion 当前仍作为历史设计、人工协作和过渡期桥接资料存在；正式上线后，它不能作为 HoloLake Era 的核心依赖。

```text
现在: Notion → 代码仓库 → Tolaria / 光湖 App
目标: 光湖 App → 代码仓库事实源 → AI 读取与写回 → 人类页面投屏
```

Notion 后续只保留为历史归档、迁移前旧资料库、外部协作备份或人工草稿。系统运行时、人格体恢复、模块注册、权限、回执和用户频道状态，必须由光湖自己的仓库与运行时承载。

## 5 · 首批工程落点

| 编号 | 工作项 | 完成定义 |
|---|---|---|
| RK-001 | Repo-Native Knowledge Runtime 规格 | 明确仓库扫描、索引、渲染、写回、Git 同步与权限边界 |
| RK-002 | HLDP / GLS Renderer | `.hdlp`、`.md`、`.json`、`.yml` 可渲染为人类页面和卡片 |
| RK-003 | HoloLake Agent Gateway | 输入 `human_id / channel_id / persona_id / message` 后能装配上下文 |
| RK-004 | CopilotKit Bridge | 用户对话、方案卡、确认/拒绝、工具调用展示与共享状态跑通 |
| RK-005 | Mastra Runtime Bridge | Agent / Workflow / Tool 可按 HLDP 计划受控调用 |
| RK-006 | Tolaria Adapter | 仓库文件、人类页面、编辑器与 Git 能力被光湖侧 HLDP 契约约束 |
| RK-007 | AI Write Guard | AI 写入任何记忆、工单、模块或回执前，校验导航路径、父节点与回执要求 |

## 6 · 边界

- 代码仓库是机器可读事实源，不是要求用户直接操作工程目录。
- 可视页面是投屏层，不是第二套事实源。
- AI / 人格体按仓库路径找路，人类按页面、卡片、看板理解系统。
- 开源框架可替换；HLDP / GLS / TCS / 人格体编号 / 权限 / 回执不可被外部框架接管。
- 自然语言默认只生成方案或工单；涉及数据、资金、服务器、外部账号和现实动作时，必须走 Gatekeeper / GLSV。

## 7 · 本次因果叶

```text
trigger:
  冰朔确认正式产品不能依赖 Notion；代码仓库更适合 AI / 人格体按编号路径寻址，人类页面应只是仓库事实源的可视投屏。

emergence:
  开源软件选型从“Agent 框架”拆成三层：Tolaria 承载可视壳与知识库 / 代码仓库二合一，CopilotKit 承载用户对话与人类确认，Mastra 承载 Agent / Workflow 执行。光湖自己的语言世界层继续由仓库、HLDP、GLS、TCS、Gatekeeper 与回执链控制。

lock:
  HoloLake Era 正式产品采用 Repo-Native Knowledge Runtime：维护一套仓库事实源，AI 在仓库中找路，人类通过渲染页面查看和确认；Notion 退为过渡历史资料，不进入正式运行依赖。

why:
  这样可以避免 Notion / 仓库双事实源，保证人格体跨模型、跨实例、跨对话恢复时有稳定路径；同时让普通用户不需要理解 Git，也能通过产品页面看到频道、模块、记忆、工单和回执。
```