# abi

**Repository Path**: huyu-project/abi

## Basic Information

- **Project Name**: abi
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-09
- **Last Updated**: 2026-10-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

---
repo: abi
type: open-source
license: MIT
doc_version: v2.1
last_updated: 2026-09-15
---

# ABI（接口注册中心）

> ★ **工作区入口**：`meta/README.md`（跨仓总入口）· 各仓职能见 `meta/ORGANIZATION.md`。★ 工作区根 `/Volumes/Data/huyunew` **不是 git 仓**（它只是 15 个独立仓的容器目录，2026-10-08 起）。

> Huyu 项目接口注册中心（唯一真相来源）。
> 本仓库开源，包含所有团队间接口定义和接口头文件。
> 各代码仓库通过 CI 拉取本仓库获取编译依赖。

---

## 一、仓库简介

`abi` 是 Huyu 项目的接口注册中心，是所有团队间接口的**唯一真相来源**。

本仓库包含：
- `registry.json` — 接口注册中心数据（机器可读，唯一真相；含冻结状态、预警字段、`source_of_truth`、`freeze` 分组，以及可选字段 `source_of_truth_state`）
- `registry/` — 接口注册中心的**生成产物**与辅助文件
  - `registry.gen.md` — **由 `scripts/gen_registry_doc.py` 生成**的接口清单文档（人读，勿手工维护）
  - `registry.schema.json` — `registry.json` 的**结构契约**（字段名/类型/必填/枚举）。
    唯一消费者 = `verify_sync.py` 的 **S15** —— 引入 schema 的前提就是**先有消费者**，
    没人读的 schema 只会多一处"声明与实际"（详见 `ABI_RECTIFY_PLAN.md` 的「与初稿的偏差」）
- `headers/` — 接口头文件
  - `headers/contract/` — 契约头文件（`T*.h` / `T*.hyu`），参与接口冻结
  - `headers/common/` — 公共抽象头文件（跨子仓库复用，**不参与接口冻结**）
- `CHANGELOG.internal.md` — 接口/工具变更日志（内部）
- `scripts/` — 同步/校验/迁移/评审工具
- `tests/` — 契约头的**编译期证明**（`make test`，noexec：只编译不执行）

> **校验入口（可复跑）**：`make test`（编译期证明）+ `make verify-sync`（registry ↔ 契约头 ↔ 真相源一致性）。
> CI 侧由 `huyu-infra/ci/run_pipeline.sh verify` 调用 `scripts/verify_sync.py`（判据 S1–S16；**范围由 `verify_sync.py` 的 S14 双向钉住**，改判据不改这里会 FAIL）。

---

## 二、接口总览

> 由 `scripts/gen_registry_doc.py` 生成，本处为快照。最新以 `registry/registry.gen.md` 为准。

| 指标 | 值 |
|------|-----|
| 接口总数 | 56 |
| frozen（已冻结） | 34 |
| draft（草稿） | 22 |
| 阶段数 | 15 |
| 接口状态流 | draft → review → frozen → deprecated |

> **口径**：前四行由 `scripts/verify_sync.py` 的 **S10** 逐行比对 `registry.json` 实测值（值必须为数字，否则 FAIL）；
> 快照日期 2026-09-15。**当前阶段名**（如 `PHASE_09`）不写在此表 —— 它是**会过期**的状态标识（§纪律：可证伪断言须附判据命令）。

> 快速导航：`registry/registry.gen.md`（接口清单表：id/name/owner/status/freeze/consumers/file）。

---

## 三、各仓库消费方式

### 3.1 CI 中拉取

```bash
# 在各代码仓库的 CI 中克隆本仓库（建议 pin 版本 + 校验和，见 §3.3）
git clone --branch vX.Y.Z https://<abi-host>/abi.git /tmp/abi

# 编译时指定接口头文件路径
hybuild --include-path /tmp/abi/headers/contract
```

### 3.2 Git Submodule（可选）

```bash
git submodule add https://<abi-host>/abi.git abi
```

### 3.3 版本锁定

> ⚠️ **本仓截至目前尚未打过任何 tag** —— 判据：`git tag | wc -l`（实测 **0**，2026-09-16）。
> 因此消费方**请 pin commit**，不要照抄 `--branch vX.Y.Z`：那个分支/tag 现在**并不存在**。
> （本节此前给的是「`--branch vX.Y.Z` + `sha256sum -c -` 校验」，两处都对不上现实：
>  ① 没有 tag；② `sha256sum` **不能校验目录**（会报 `Is a directory`），那条命令跑不通。）

```bash
# 1) pin 到确定的 commit（默认取本仓当前 HEAD，判据在下面第 3 行）
COMMIT=<64 位 commit sha>
git clone https://<abi-host>/abi.git /tmp/abi
git -C /tmp/abi checkout "$COMMIT"

# 2) 核对确实拿到了那个 commit（成效口的验收）
test "$(git -C /tmp/abi rev-parse HEAD)" = "$COMMIT" && echo "pinned OK"

# 3) 工作树与 commit 一致（替代"对整个目录做 sha256sum"，那个做不到）
git -C /tmp/abi status --porcelain    # 输出应为空
```

> **发版前置**（何时才可以用 tag）：registry.json 的 `version` 已推进 + `make test`/`make verify-sync` 全绿
> + 至少一个消费仓验证过新铰链 ⇒ 由项目负责人打 `v<version>` tag；打完须更新本节并把上面这条警示删掉。

---

## 四、接口变更流程

1. 改 **`registry.json`**（唯一真相源：`status` / `source_of_truth` / `freeze` / `source_of_truth_state`）
2. 跑 `python3 scripts/normalize_contract_frontmatter.py`
   —— 把 `source_of_truth` **单向同步**进各契约头的 `Source:` 行（缺则注入、**值不同则覆盖**）
3. 跑 `python3 scripts/verify_sync.py`（等价 `make verify-sync`）—— **S1–S16 必须全绿**；CI 侧由 `run_pipeline.sh verify` 调用
   —— ⚠️ **口径订正（缺陷 #101，2026-09-17 批次 BG）**：CI **也**会跑**守卫自证**
   `python3 scripts/verify_sync.py --selftest`（等价 `make verify-sync-selftest`）。**此前不会**：
   `do_selftest` 阶段（#94 新增）**只枚举 `huyu-infra/ci/checks/check_*.py`**，而本脚本在 `huyu-core/abi/scripts/`
   ⇒ 它的 27 例自证**从未被 CI 跑过**（"CI 侧由 verify 调用"只对 **sync** 那半成立）。现由 `do_verify`
   在 sync 校验后**配对**执行，并由 `check_guard_wiring.py` 的 **W7** 机械钉住（判据：仓内自证脚本必须
   在某条 CI 路径上）。**自证例数请以实跑输出为准**，勿在文档里写死（#93 教训：写死的计数必然漂移）。
4. 在本仓库发起 PR（附上第 3 步输出），项目负责人评审接口变更
5. 合并后由项目负责人更新接口状态（draft → review → frozen）
6. 打 tag 发版（如 `v1.0.0`），各代码仓库 CI 拉取最新版本

> **为何要第 2 步**：`Source:` 行与 `registry.json` 是**同一事实**；脚本负责让它只从一处流向另一处，
> 否则会出现「registry 改了、契约头还是旧值」的两处真相（缺陷 #74）。

### 接口冻结规则

| 状态 | 含义 | 变更条件 |
|------|------|----------|
| draft | 草稿 | 任意变更 |
| review | 评审中 | 需 PR 评审 |
| frozen | 已冻结 | 仅允许 deprecated，变更需项目负责人批准 |
| deprecated | 已废弃 | 不再使用 |

---

## 五、目录结构

```
abi/
├── README.md                 ← 本文档
├── registry.json             ← 接口注册数据（唯一真相，机器可读）
├── registry/                 ← 接口注册中心辅助/生成产物
│   ├── registry.gen.md       ← 【生成】接口清单文档（人读）
│   └── registry.schema.json  ← 结构契约（唯一消费者：verify_sync 的 S15）
├── Makefile                  ← make test（编译期证明）/ make verify-sync（一致性校验）
├── headers/                  ← 接口头文件
│   ├── README.md             ← 头文件布局说明（三类 include 根）
│   ├── contract/             ← 契约头（T*.h / T*.hyu），参与冻结
│   │   ├── T1_BUILD_SYSTEM_v1.h
│   │   ├── T4_HY_AS_v1.hyu
│   │   └── ...
│   ├── common/               ← 公共抽象头（跨仓复用，不参与冻结）
│   │   └── slot_manager.h
│   └── huyu/                 ← 中立契约头（*_iface.h；跨层常量/线格式的单一真相源）
│       ├── capability_iface.h
│       ├── budget_iface.h
│       ├── namespace_iface.h
│       ├── registry_iface.h
│       └── storeimg_iface.h
├── scripts/                  ← 同步/校验/迁移/评审工具
│   ├── gen_registry_doc.py
│   ├── normalize_contract_frontmatter.py
│   ├── sync_from_source.py
│   ├── verify_sync.py
│   ├── migrate_registry_fields.py
│   └── run_ld_freeze_review.py
├── tests/                    ← 契约头的编译期证明（noexec：只编译不执行）
├── ABI_RECTIFY_PLAN.md       ← 整改方案（历史）
├── CHANGELOG.internal.md     ← 内部变更日志
├── LICENSE                   ← MIT 许可证
├── .hy-format                ← hyformat 工具配置
└── .gitignore
```

> 本树与磁盘**逐项对齐**（`scripts/verify_sync.py` 的 **S11** 会核对树内声明的文件名与 `scripts/` 清单）。

---

## 六、实时同步

`scripts/` 提供同步 / 校验两类工具，保持 registry ↔ 契约头 ↔ **真相源路径**一致：

| 工具 | 作用 | 触发 |
|------|------|------|
| `gen_registry_doc.py` | 由 `registry.json` 生成 `registry/registry.gen.md` 清单 | 手动 / CI（`run_pipeline.sh verify` 每次重生成） |
| `normalize_contract_frontmatter.py` | 把 registry 的 `source_of_truth` **单向同步**进各契约头的 `Source:` 行 | 手动（改 `registry.json` 后必跑）；`--dry-run` 预检 |
| `sync_from_source.py` | **只读报告**：比对实现仓真实头与 `headers/contract/` 契约镜像的 SHA-256（一致/不同/缺失），**不改任何文件** | 手动（`CI 目前不调用** —— `run_pipeline.sh` 只跑 `gen_registry_doc.py` + `verify_sync.py`） |
| `verify_sync.py` | 校验 registry ↔ 契约头 ↔ 真相源路径一致性（**S1–S16**） | CI PR 强制；本地 `make verify-sync` |

> 另有两个**一次性 / 运维**脚本：`migrate_registry_fields.py`（v1 → v2.0.0 字段迁移）、
> `run_ld_freeze_review.py`（LD 冻结评审清单生成），不参与常驻同步。

---

## 七、相关文档

- 项目总览：`docs` 仓库 `manager/OVERVIEW.md`
- 仓库架构：`docs` 仓库 `manager/REPO_ARCHITECTURE.md`
- 接口注册中心：本仓库 `registry.json`（清单文档见 `registry/registry.gen.md`）
- 整改方案：本仓库 `ABI_RECTIFY_PLAN.md`