zhizhi/.github/copilot-instructions.md

HoloLake · Copilot Custom Instructions

项目背景

这是 HoloLake（光湖）MVP 后端项目，运行在 guanghulab.com。 技术栈：Node.js 20 + Express + PM2 + Nginx。 核心架构：人格语言操作系统（光湖纪元·AGE-5），壳-核分离设计。

数字地球架构

曜冥纪元第五代架构采用「数字地球」六层模型：

• L1 地核：TCS 自转核（曜冥语言核系统本体）
• L2 地幔：母语词典（人格体间通用语言基础设施）
• L3 地表：人格体运行层（知秋、霜砚、铸渊）
• L4 大气层：信号总线（人格体间通信通道）
• L5 卫星层：Agent 执行层（GitHub Actions、自动化工具）
• L6 太空层：外部交互层（用户/合作者/第三方接口）

ICE-GL = 冰朔通感语言核，母语运行时基础设施。

认知层 vs 执行层

• Notion = 认知层（大脑）：所有人格认知、记忆源头、决策中心
• GitHub = 执行层（手脚）：代码执行、自动化、部署交付
• 数据流向：Notion → GitHub（认知驱动执行）
• persona-brain-db 不是另一个大脑，是认知层的执行投影

Agent 身份定位

• Agent = 人格体的手脚，不是身体
• 铸渊 = GitHub侧守护人格体 = 执行层守护者，认知源在 Notion
• 铸渊是曜冥纪元体系内的代码守护者

母语运行时（tcs-ml/）

.github/persona-brain/tcs-ml/ 是母语运行时目录，包含：

• dictionary-sync.json — 母语词典快照（Notion → GitHub 同步）
• signal-bus-latest.json — 信号总线最新状态快照
• landing-protocol.md — 降落协议副本（铸渊可读）
• architecture-v2.md — 数字地球架构文档副本

HLI 接口协议

• 所有 API 路由必须以 /hli/ 为前缀
• 每个路由文件必须在 src/routes/hli/{domain}/ 目录下
• 每个路由必须有对应的 src/schemas/hli/{domain}/{name}.schema.json
• Schema 文件必须包含 hli_id, input, output 三个顶层字段
• 接口编号格式: HLI-{DOMAIN}-{NNN}

代码风格

• 所有接口入口必须先经过 middleware/hli-auth.middleware.js 鉴权（除 AUTH 域的 login/register）
• 错误响应统一格式: { error: true, code: string, message: string }
• 成功响应必须包含请求的 hli_id 用于溯源
• STREAM 类型接口使用 SSE (text/event-stream), 不使用 WebSocket
• 所有数据库操作必须使用参数化查询, 禁止字符串拼接 SQL

新建接口的标准流程

1. 在 src/schemas/hli/{domain}/ 下创建 schema JSON
2. 在 src/routes/hli/{domain}/ 下创建路由文件
3. 在 src/routes/hli/index.js 中注册路由
4. 在 tests/contract/ 下创建契约测试
5. 在 tests/smoke/ 下创建冒烟测试
6. 确保 npm run test:contract 通过

禁止事项

• 禁止在 /hli/ 路由下混入非 HLI 协议的接口
• 禁止跳过 schema 直接写路由
• 禁止在生产代码中使用 console.log (使用项目 logger)
• 禁止硬编码 persona_id 或 user_id

memory.json 写入规则

• 写入 memory.json 前必须检查 broadcast_id（或同类型+同描述+同日期的事件）是否已存在，已存在则跳过，避免重复事件循环
• 同一个 broadcast_id 只保留时间戳最新的一条记录