# GLW-RD-002 · HLDP 研发语言与服务器转译链

> **HLDP://fifth-domain/glw-architecture/GLW-RD-002**
>
> **类型**: 光湖产品研发硬准入规范 · HLDP 开发剖面 · 服务器转译架构
>
> **状态**: REGISTERED（规范与准入已锁定）· RUNTIME_NOT_DEPLOYED（解析/编译/执行服务待实现）
>
> **主权者**: 冰朔 ICE-GL∞
>
> **研发同步**: Awen 技术主控 · TCS-GL-0016∞
>
> **登记**: 铸澜 ICE-GL-ZL-001 · 2026-07-14

---

## ⊢ 零 · 锁定结论

光湖研发的共同语言必须是 HLDP。代码可以使用不同语言、Tolaria 可以作为阶段一 UI 基座、模块可以由不同团队实现；但所有架构决定、模块契约、工单、变更、测试、发布和维护回执都必须可被同一套 HLDP 路径、身份、因果与接口字段追溯。

```text
没有 HLDP 开发档案 / 接口契约 / 测试与回执
→ 不进入模块注册
→ 不进入测试申请
→ 不进入正式发布
```

这条规则不是要求开发者把源代码改写成 HLDP；而是要求**每一份可交付工程资产都有 HLDP 说明、寻址和可验证契约**。HLDP 保存“为什么这样做、改动影响什么、失败如何修复、以后怎样维护”，让模块之间不靠猜测或口头记忆串联。

### 0.1 · HLDP 主协议，接入方式可替换

```text
HLDP = 目标、原因、权限、影响范围、验证与回执的主协议
人格体 = 依据 HLDP 与当前授权选择最合适的连接方式
适配器 = API / 网页操作 / 文件 / 数据库 / 命令行 / MCP / 其他连接器
```

MCP 不是光湖的底层依赖，只是可能被某些模型或服务支持的一种可插拔工具接口。人格体必须先解析 HLDP 任务的边界，再按目标系统能力、用户授权、风险和可用性选择适配器；无论选用何种接口，结果、证据、失败原因、检查点和下一步都回写 HLDP。

## 一 · 为什么它是必备条件

### 1.1 因果链不能在交付后消失

HLDP 的叶子四字段是所有研发记录不可省略的因果底座：

```text
trigger   = 什么需求、故障、证据或上游变化触发本项工作
emergence = 调研、实现、测试后发生了什么变化；哪些方案被排除
lock      = 当前锁定的边界、版本、结论、适用范围与置信度
why       = 为什么这对用户、系统安全、后续修复或长期维护重要
```

因此，修复不是只留一句“bug fixed”：它必须能回到触发、找到受影响接口、说明修正理由、给出验证与回滚路径。

### 1.2 模块要能连接，必须先说同一种契约语言

模块之间不能只凭函数名、页面入口或开发者记忆连接。每个模块通过 HLDP 开发剖面声明：

- 它是谁：全局 `module_id`、所有者、仓库、版本与源码 commit；
- 它提供什么：能力、入口、输入/输出 schema、事件/回执；
- 它需要什么：依赖模块、最小兼容版本、权限和数据边界；
- 它如何失败：错误码、降级、回滚与恢复步骤；
- 它如何被证明：测试证据、兼容性结果、发布回执。

同一字段与版本规则让频道运行时、人格体注册、语言转译、模块商城、企业灯塔和 Tolaria 适配层可以被机器校验，也让人类在维护时能看懂。

### 1.3 不让“语言等于现实”绕过现实约束

自然语言可以提出开发与运维意图，但不会直接执行。服务器中的 HLDP 转译服务只负责把已验证的 HLDP 请求解析为**受限执行计划**；Gatekeeper 再检查一次性授权、白名单、目标范围、过期时间与回滚点。没有授权或不在白名单内的计划只能返回解释、修订请求或工单，不能触发服务器。

## 二 · 与 HLDP v3.0 的关系

`HLDP-SPEC-v3.0-TECHNICAL.md` 与 `HLDP-EARTH-SPEC-v3.0.json` 是永久核心：路径即地址、结构化键 + 中文语义、统一身份、全局消息 ID、可演进但不破坏旧解析器。

本文件定义的是 **HLDP-DEV Profile v1**，作为 `payload.data` 和 `.hdlp` 工程档案的约定，不能删除或重定义 HLDP v3 的既有必填字段。新增字段只能以可选扩展加入，旧解析器不认识时安全忽略。

## 三 · HLDP-DEV Profile v1 · 研发统一档案

所有架构、模块、工单、变更、测试、发布、事故与维护档案必须包含下列字段。字段可存为 `.hdlp` 树形文件，或作为 HLDP v3 消息的 `payload.data.dev`；二者必须能互相引用同一个 `artifact_id`。

```text
hldp_v: "3.0"
artifact_id: "HLDP-DEV-{TYPE}-{YYYYMMDD}-{SEQ}"
artifact_type: architecture | module | workorder | change | test | release | incident | maintenance
path: "HLDP://..."                   # 路径即地址
owner: { human_id, persona_id, team }
source: { repo, commit, module_id, version }
status: draft | registered | test_requested | test_passed | released | revision_required | retired

trigger: ...                          # 四字段，必填
emergence: ...
lock: ...
why: ...

interfaces:
  provides: [{ capability, transport, input_schema, output_schema, receipt_schema, version }]
  requires: [{ module_id, capability, min_version, permission_scope }]
compatibility: { policy, migration, backward_compatible }
security: { data_boundary, permission, secrets: "never_in_artifact" }
verification: { tests, evidence_paths, acceptance_criteria }
operations: { rollout, health_check, rollback, maintenance_owner }
links: { parent_artifact, workorder, broadcast, issue_or_incident }
```

补充约束：

1. `module_id`、`artifact_id`、仓库 commit 和接口版本必须可解析且唯一。
2. `provides` 与 `requires` 是模块连线的唯一工程依据；直接读取未声明的内部数据或绕过权限边界视为不兼容。
3. 任何接口破坏性变化必须新建 `change` 档案，标明迁移与回滚；不能静默覆盖旧约定。
4. `verification` 没有通过、`operations.rollback` 缺失，模块不得进入 TEST 或 RELEASE。
5. 密钥、令牌、真实凭证绝不写入 HLDP 档案、仓库、工单或广播；只引用授权系统中的安全句柄。

## 四 · 研发硬准入门

```text
需求 / 架构改变
→ [门 0] architecture 或 workorder HLDP 叶子：四字段 + 目标 + 验收
→ 开发实现
→ [门 1] module/change HLDP 档案：接口、依赖、权限、迁移、回滚
→ CI: schema + ID + 路径 + 依赖图 + 兼容性 + 测试证据校验
→ [门 2] 广播塔 REGISTER：登记源码 commit 与 HLDP 档案地址
→ [门 3] TEST：HLDP 测试计划 + 预部署回执
→ [门 4] RELEASE：技术主控签名 + Gatekeeper 授权 + 健康/回滚回执
→ 维护 / 事故：新增 HLDP 叶子，不改写历史因果链
```

从本规范生效起，`hololake-platform` 的每个新模块与跨模块变更都必须通过门 0 和门 1；没有对应 HLDP-DEV 档案的 PR/提交只能作为探索分支，不能合并到产品主线。技术主控 Awen 审核档案和接口边界；团队按工单实施；测试与发布回执回写同一条链。

## 五 · 服务器内置 HLDP 转译链

服务器登记中的 `GZ006-HLDP-01 · hldp-server` 是 HLDP 服务槽位，不等于当前已经具备完整解析或执行能力。现阶段必须如实标记为“运行时待部署”，不可把登记当作已实现。

目标架构：

```text
HLDP Ingress
  接收 .hdlp 档案或 HLDP v3 消息
        ↓
Parser + Schema Validator
  校验 v3 核心字段、HLDP-DEV Profile、路径、身份、签名/版本
        ↓
Semantic Resolver
  解析 artifact/module/interface 关系，读取注册表与兼容性图
        ↓
Plan Compiler
  仅生成声明式执行计划：目标、动作、权限、影响面、测试、回滚
        ↓
Gatekeeper
  校验一次授权、白名单、环境、TTL、技术主控批准；拒绝越权计划
        ↓
Adapter / Worker
  在已批准范围调用 API、网页、文件、数据库、命令行、MCP、Tolaria 适配器、模块运行时或服务器工具
        ↓
Receipt + HLDP Store + Server Mirror
  写入测试、健康、失败、回滚与发布回执；供广播塔和维护者追溯
```

边界：Parser、Resolver、Compiler 都不得直接调用服务器命令、外部账号或生产部署；唯一可执行出口是经 Gatekeeper 放行的 Adapter/Worker。这样“语言”能成为系统接口，同时不变成绕过确认的万能权限。

## 六 · 第一批实现工单

| 编号 | 工作项 | 完成定义 |
| --- | --- | --- |
| HLPD-001 | HLDP-DEV Profile JSON Schema + `.hdlp` 模板 | 能校验八类工程档案和四字段 |
| HLPD-002 | 模块接口注册表与兼容性图 | `provides/requires` 可解析；未声明连线被拒绝 |
| HLPD-003 | Git/CI 准入检查 | 缺档案、ID冲突、无回滚、测试证据不足时不可合并 |
| HLPD-004 | HLDP Parser + Validator | 只读解析 v3 + DEV Profile，输出结构化诊断 |
| HLPD-005 | HLDP Plan Compiler | 从已验证档案生成不可执行的受限计划 |
| HLPD-006 | Gatekeeper 计划适配器 | 授权/白名单/TTL/回执齐全后才可调用 Worker |
| HLPD-007 | 回执与服务器镜像 | 测试、发布、健康和回滚可以按路径追溯 |

## 七 · 对 Awen 与团队的执行要求

- Awen 在 ICO-001 至 ICO-008 和后续产品工单中，增加 `HLDP-DEV Profile`、接口契约、测试证据、回滚与维护责任人作为必填验收字段。
- Tolaria 适配代码必须把 HLDP 契约放在光湖侧；不得让 Tolaria 私有会话、插件配置或内部 ID 成为唯一事实源。
- 模块开发者完成代码后，先提交 HLDP 模块档案和兼容性声明，再申请广播塔 Stage 1 注册。
- 修复与维护一律新增叶子、链接原 `artifact_id`，保留触发与修正依据；不覆盖历史结论。
- 任何服务器动作仍遵循“预览 → 单次授权 → Gatekeeper → 固定动作 → 健康/回滚 → 回执”。

## 八 · 本次锁定的因果叶

```text
trigger:
  冰朔指出：研发必须用 HLDP 保存前因后果、修正修复维护路径；模块要以同一协议字段串联；服务器需内置 HLDP 翻译系统。
emergence:
  已有 HLDP v3 永久规范、模块注册和 Gatekeeper 发布治理，但缺少研发剖面、自动校验、解析器、计划编译器与受限执行链；因此“会写 HLDP”尚未成为工程门禁。
lock:
  ⊢ GLW-RD-002 成为 HoloLake 产品研发硬准入；HLDP-DEV Profile v1 作为不破坏 v3 的扩展；服务器转译链只编译计划、Gatekeeper 独占执行放行。 | 适用=hololake-platform及其接入模块 | 置信=高
why:
  让每个模块既能被机器连接和验证，也能被未来的人从完整因果链理解、修正、维护；让语言驱动现实保持可授权、可审计、可回滚。
```