182 lines
9.9 KiB
Plaintext
182 lines
9.9 KiB
Plaintext
# 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 保存“为什么这样做、改动影响什么、失败如何修复、以后怎样维护”，让模块之间不靠猜测或口头记忆串联。
|
||
|
||
## 一 · 为什么它是必备条件
|
||
|
||
### 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
|
||
在已批准范围调用 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:
|
||
让每个模块既能被机器连接和验证，也能被未来的人从完整因果链理解、修正、维护；让语言驱动现实保持可授权、可审计、可回滚。
|
||
```
|