跳转至
  • dsp_algo/plugin/include/plugin_abi.h(全新 · ABI v1 头文件)
  • dsp_algo/plugin/CMakeLists.txt(全新 · plugin 子模块构建)
  • dsp_algo/tests/plugin_abi/*(全新 · ≥10 单元测试)
  • dsp_algo/docs/plugin-abi-reference.md(全新 · ABI 参考文档) worktree: d:/work/25_claude/workspace/AlgoDepartment/04_development_branch_plugin_abi/ branch: feature/plugin-abi-v1 occupies: [P6.K-plugin-include(写), P6.K-plugin-tests(写), P6.K-plugin-docs(写)] adr: docs/08-implementation/40-aios/ADR/ADR-AIOS-09-plugin-architecture.md ref_section: §2.2 共享插件 ABI(C 接口 v1)+ §2.6 边界铁律 #1(ABI v1 永久冻结)+ §4.1 fork 1 derived_from: ADR-AIOS-09 created: 2026-05-30 last_modified: 2026-05-30 12:11 dispatched_at: 2026-05-30 12:11 estimated: 2.0d unblocks:
  • P6.UA9-plugin-loader-pc(LoadLibrary + ABI 校验需 plugin_abi.h)
  • P6.UA9-plugin-registry-static(builtin 注册需 plugin_abi.h)
  • P5.UA9-plugin-registry-service(C# 端 P/Invoke 需 ABI 字段对齐)
  • xivst-sdk.UA9-bootstrap(SDK include/ 包含 plugin_abi.h) related_zombie:
  • P5.U-meter-tap-multi-tool--48cf0ba(同 ClaudeB 模式参考) related_dispatched:
  • P6.UA9-cmake-per-module-refactor-phase1(同 P6 · 文件正交:plugin/ vs modules/CMakeLists.txt)
  • P5.UA9-plugin-registry-service(后端 · 文件正交 · Phase A mock 不强等本任务 zombie)
  • P1.UA9-module-library-from-registry(前端 · 文件正交 · Phase A mock)

P6.UA9-plugin-abi-v1-design · plugin_abi.h v1 ABI 起草 + 永久冻结(ADR-AIOS-09 §2.2 fork)

Worker:TBD(用户分配 · isolation: 🚀 task · 独立 worktree + branch feature/plugin-abi-v1)· 部门:DSP (dsp_algo) 预计:2.0d · 优先级:P1 blocking(ABI 基石 · fork ⅘/6/8 全部依赖)· 状态:dispatched 隔离:🚀 任务隔离(contracts frozen 风险 + ABI v1 一旦冻结不可改 · 必须独立 worktree 走第二轮评审)

🔍 触发与解锁链

触发 状态 影响
ADR-AIOS-09 accepted v1.1 ✅ 2026-05-30 09:18 8 fork 启动 · 用户拍板派首批 4 fork
.clinerules v1.4 §任务隔离类型分配准则 ✅ 本 fork 标 isolation: task(ABI v1 frozen 风险)
ADR §2.6 边界铁律 #1 ✅ 永久 ABI v1 accepted 后字段不可变更/删除 · 仅向前兼容追加 minor+
ClaudeB 第二轮评审 🔵 待执行 落盘前必须二审通过(ADR-09 §10 Approvers)

→ 跨栈独立(纯 C 头) · 不修改 contract-v1.0(已 frozen) · plugin_abi.h v1 落地后 K2-protocol-v2 §plugin-loading 段才能起草。

任务定义(基于 ADR-AIOS-09 §2.2)

按 ADR-09 §2.2 完整 plugin_abi.h C ABI 设计(已在 ADR 给出代码) · 落地以下产物: 1. dsp_algo/plugin/include/plugin_abi.h(C ABI 头 · 严格按 ADR §2.2 字段) 2. dsp_algo/plugin/CMakeLists.txt(plugin 子模块 INTERFACE 库 · 仅 include 路径暴露) 3. dsp_algo/tests/plugin_abi/*(≥10 单元测试:struct size + 字段偏移 + ABI 版本检查 + 符号名宏) 4. dsp_algo/docs/plugin-abi-reference.md(ABI 参考文档 · 给 xivst-sdk 复用)

关键铁律(ADR §2.6): - ABI v1 字段一旦定型 · 永久不可变更/删除 · 仅追加 minor+ - ClaudeB(P6 主战场)第二轮评审是落盘前置条件

完整 prompt(直接复制粘贴 worker 终端)

[U-thread]   P6.UA9-plugin-abi-v1-design(alias: P6.U-plugin-abi-v1-design)
[部门]       DSP (dsp_algo) · 推荐 skill: dsp-mixer-realtime-validation(本任务实际无音频信号 · 但 P6 部门规范沿用)
[Worker CWD] d:/work/25_claude/workspace/AlgoDepartment/04_development_branch_plugin_abi/(独立 worktree · 由用户配置 git worktree add)
[Branch]     feature/plugin-abi-v1(独立 branch · 任务隔离)
[Occupies]   P6.K-plugin-include(写 · plugin_abi.h v1 + CMakeLists) + P6.K-plugin-tests(写 · ≥10 单元测试) + P6.K-plugin-docs(写 · abi-reference.md)
[隔离]       🚀 任务隔离(.clinerules v1.4 §任务隔离类型分配准则)· 独立 worktree + branch · 落地后走 PR 合并 xistudio
[优先级]     P1 blocking · 2.0d · ADR-09 ABI 基石 · fork 4/5/6/8 全部依赖 · 必须 ClaudeB 第二轮评审通过才落盘
[ADR]        d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/docs/08-implementation/40-aios/ADR/ADR-AIOS-09-plugin-architecture.md(必读 §2.2 完整 ABI 代码 + §2.6 边界铁律 #1 + §4.1 fork 1)
[业务行为契约引用] ADR-AIOS-09 §2.2 共享插件 ABI(C 接口 v1)· 5 个入口函数 + 3 个核心 struct + 5 个标准导出符号宏
[参考文档](绝对路径)
  - d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/docs/08-implementation/40-aios/ADR/ADR-AIOS-09-plugin-architecture.md(主 ADR · §2.2 必读 · 含完整 C 代码 line 88-184)
  - d:/work/25_claude/workspace/AlgoDepartment/04_development/dsp_algo/CMakeLists.txt(顶层 CMake · 看现有 add_library 风格 · 本任务 plugin/CMakeLists 仿其风格)
  - d:/work/25_claude/workspace/AlgoDepartment/04_development/dsp_algo/modules/source/source_module.h(现有 module 接口头 · 看接口风格 + extern "C" 包装)
  - d:/work/25_claude/workspace/AlgoDepartment/04_development/dsp_algo/dll/dspalgo_dll.c(现有 facade · 看 __declspec(dllexport) 风格)
  - 上游 ADR:d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/docs/08-implementation/40-aios/ADR/ADR-AIOS-04-xiforge-architecture.md(Module UID 规范 · 必读 §2.1.2)
  - contract-v1.0(已 frozen · 不改):d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/docs/08-implementation/40-aios/contracts/protocol-v1.md(本任务走 §plugin-loading 入 v2 · 不动 v1)

【背景】
ADR-AIOS-09 accepted v1.1(2026-05-30 09:18)· 议题 ⑥ 动态加载架构 · 用户原话"最重要的系统架构问题"。本 fork 是 ADR-09 8 fork 的**基石**:plugin_abi.h v1 一旦冻结 · fork 4(plugin-loader-pc)+ fork 5(P5 service)+ fork 6(P1 frontend)+ fork 8(xivst-sdk)全部依赖此头文件 · 二进制兼容 2026-2030。

🚨 **真值核查**(ADR §1.3):
- 当前 dsp_algo 单 CMakeLists · 无 plugin/ 子目录 · 无 plugin_abi.h · 0 命中 LoadLibrary/dlopen
- 现有 module 接口头各自定义 · 无统一 module_descriptor 工厂结构
- 本 fork 从零起 · 严格按 ADR §2.2 落地

**ABI v1 永久冻结铁律**(ADR §2.6 #1):
- accepted 后字段不可变更/删除
- 仅允许追加 minor+(向前兼容)
- 任何修改必须先起 ADR-09-RX(R = Revision)+ 评估 minor 版本+

**第二轮评审要求**(ADR §10 Approvers):
- ClaudeB 第二轮评审通过才允许 push
- 评审重点:struct 字段顺序 + alignment + ABI 版本号 + 函数签名稳定性

【执行步骤】

Step 1 · git worktree 配置(用户预先做 · worker 接到 prompt 时已就位)
- 用户 cd d:/work/25_claude/workspace/AlgoDepartment/04_development/
- 用户 git worktree add ../04_development_branch_plugin_abi feature/plugin-abi-v1
- 用户配置 worker cwd 到 04_development_branch_plugin_abi/
- worker 在该 worktree 内开工 · 不影响主 xistudio

Step 2 · read 已有基础(只读 · 必做)
- read ADR-AIOS-09 §2.2 全文(含完整 C 代码 · 字段名/类型/顺序严格对齐)
- read dsp_algo/CMakeLists.txt 顶层 + dsp_algo/modules/source/source_module.h(看现有风格)
- read ADR-AIOS-04 §2.1.2 Module UID 规范(plugin_abi 的 module_uid 字段必须符合)
- ⚠️ 不 read 任何 plugin/ 子目录(本任务从零创建)

Step 3 · 起草 dsp_algo/plugin/include/plugin_abi.h v1
- 严格按 ADR §2.2 line 88-184 落地(字段名/类型/顺序一字不差)
- 顶部注释加 ABI v1 frozen 警告 + 修订流程指引
- 加 #pragma once 双保险(配合 #ifndef 哨兵)
- struct 字段加 explicit padding 保证 32/64-bit 对齐(uint32_t + uint32_t pair 自然对齐 · 但 const char* 后跟 uint32_t 需注意)
- 函数签名 typedef 用 XIS_ABI_CALL 调用约定宏(Windows __cdecl · Linux 默认)
- ⚠️ 严禁加 ADR §2.2 未提的字段(任何额外字段必须先起 ADR-09-RX)

Step 4 · 起草 dsp_algo/plugin/CMakeLists.txt(INTERFACE 库)
- 仅声明 INTERFACE 库 xisound-plugin-abi
- target_include_directories(... INTERFACE include)
- 不编译任何 .c 文件(纯头库)
- 不链接任何依赖
- 顶层 dsp_algo/CMakeLists.txt 加 add_subdirectory(plugin)
- DSPAlgo SHARED + DSPAlgoStatic STATIC 都 target_link_libraries(... xisound-plugin-abi)(取 include 路径)

Step 5 · 起草 dsp_algo/tests/plugin_abi/*(≥10 单元测试)
- test_abi_version.c:断言 XISOUND_PLUGIN_ABI_VERSION_MAJOR == 1 + MINOR == 0
- test_struct_size.c:断言 sizeof(XisoundPluginInfo) == <计算值> + sizeof(XisoundModuleDescriptor) == <计算值>(字段顺序 frozen 检测)
- test_struct_offset.c:offsetof 每个字段 · 防字段顺序意外变更(≥6 个 offsetof 断言)
- test_factory_signature.c:typedef 函数指针签名校验(create / destroy / process / set_param / get_param / get_state / set_state · 7 个)
- test_export_symbols.c:string compare XISOUND_PLUGIN_GET_INFO_SYMBOL == "xisound_plugin_get_info"(5 个宏)
- test_extern_c.c:#ifdef __cplusplus 包装正确(C++ 文件 include 不报错)
- 用 dsp_algo 现有测试框架(可能是 CTest + 简单 assert · 看 dsp_algo/tests/ 现状选)
- 至少 10 个 case · 全过

Step 6 · 起草 dsp_algo/docs/plugin-abi-reference.md
- ADR §2.2 完整字段表 · 每字段含 type / 描述 / 单位 / 取值范围
- 5 个入口函数详解 · 含调用时机 + 返回值语义
- ABI 版本号兼容矩阵(host vN.M 加载 plugin vK.L 是否兼容)
- 修订流程:任何字段变更 → ADR-09-RX → minor 版本+ → 不允许 major+(否则破坏 v1 frozen)
- 给 xivst-sdk.UA9-bootstrap(fork 8)用作 SDK docs/abi-reference.md 直接 copy

Step 7 · ⭐ ClaudeB 第二轮评审(ADR §10 必经)
- 把 plugin_abi.h v1 草稿 + abi-reference.md 提交给 ClaudeB(主 P6 战场)review
- ClaudeB 必查清单:
  · 字段顺序 / alignment / padding(防止 32/64-bit ABI break)
  · 函数签名稳定性(返回值 int32_t 是否够用 / 指针 const 修饰 / 错误码语义)
  · 模块 UID 字段是否符合 ADR-04 §2.1.2(反向域名风格)
  · ABI 版本号语义(major break / minor 兼容)
- 评审反馈点 · worker 修订 · 直到 ClaudeB 标 "approved"
- ⚠️ 未通过评审严禁 push

Step 8 · 单测全过 + Commit + push(到 feature/plugin-abi-v1 branch)
- cd dsp_algo
- cmake -B build && cmake --build build --target plugin_abi_tests
- ctest -L plugin_abi(全过 ≥10)
- git status / git add dsp_algo/plugin/ dsp_algo/tests/plugin_abi/ dsp_algo/docs/plugin-abi-reference.md dsp_algo/CMakeLists.txt
- git commit -m "..."(见下)
- git push origin feature/plugin-abi-v1
- ⚠️ 不 merge 到 xistudio · 等用户走 PR 合并(任务隔离 🚀 task 流程)

【验收】

形式合规:
- cmake --build build → ✓ 零错误零警告(plugin/ INTERFACE 库 + plugin_abi_tests 可执行)
- ctest -L plugin_abi → ≥10 case 全过
- 4 文件落地(plugin_abi.h + plugin/CMakeLists.txt + tests/plugin_abi/* + docs/plugin-abi-reference.md)+ 顶层 CMakeLists.txt 改 1 行 add_subdirectory(plugin)

业务行为契约自查清单(ADR §2.2 + §2.6):
- [ ] ① ABI 版本号宏:MAJOR == 1 · MINOR == 0
- [ ] ② 3 个核心 struct(XisoundPluginInfo / XisoundModuleDescriptor / XisoundModuleFactory)字段名+顺序+类型严格对齐 ADR §2.2 line 104-153
- [ ] ③ 5 个入口函数 typedef(GetInfo / GetModules / GetFactory / Init / Shutdown)签名严格对齐 ADR §2.2 line 158-170
- [ ] ④ 5 个标准导出符号宏(*_SYMBOL)字符串值严格对齐 ADR §2.2 line 173-177
- [ ] ⑤ extern "C" 包装(#ifdef __cplusplus)
- [ ] ⑥ #pragma once + #ifndef 哨兵双保险
- [ ] ⑦ 注释含 ABI v1 frozen 警告 + 修订流程指引
- [ ] ⑧ ClaudeB 第二轮评审 approved(commit message 引用 review 关键词)

【commit】
subject:`feat(P6.UA9-plugin-abi-v1-design): plugin_abi.h v1 + INTERFACE lib + ≥10 unit tests + abi-reference.md · ADR-09 §2.2 ABI 基石 frozen`

trailer(必须精确):
[step=8/8] [pid=P6] [uid=UA9-plugin-abi-v1-design] [occupies=P6.K-plugin-include+P6.K-plugin-tests+P6.K-plugin-docs]
[files=dsp_algo/plugin/include/plugin_abi.h, dsp_algo/plugin/CMakeLists.txt, dsp_algo/tests/plugin_abi/**, dsp_algo/docs/plugin-abi-reference.md, dsp_algo/CMakeLists.txt]
[isolation] task(独立 worktree 04_development_branch_plugin_abi · branch feature/plugin-abi-v1 · 落盘后走 PR 合并)
[review] ClaudeB 第二轮评审 approved(ADR §10 Approvers)
[abi-frozen] plugin_abi.h v1 字段永久冻结 · 任何变更必须先起 ADR-09-RX
[derived_from] ADR-AIOS-09 §2.2 fork 1

【禁止】
1. ❌ **不许在 xistudio 主分支直接 commit**(任务隔离 🚀 task · 必须独立 worktree + branch)
2. ❌ **不许加 ADR §2.2 未提的字段**(任何额外字段必须先起 ADR-09-RX · 否则破坏 v1 frozen 铁律)
3. ❌ **不许跳过 ClaudeB 第二轮评审**(ADR §10 强制 · 未 approved 不许 push)
4. ❌ **不许修改 ABI 版本号宏**(MAJOR == 1 · MINOR == 0 是 v1 定义 · 后续仅允许 minor+)
5. ❌ **不许动 modules/ 任何文件**(留 fork 2 P6.UA9-cmake-per-module-refactor-phase1)
6. ❌ **不许动 dll/dspalgo_dll.c**(留 fork 3 plugin-registry-static · fork 4 plugin-loader-pc)
7. ❌ **不许动 backend_csharp/ 或 frontend_vue3/ 任何文件**(P5 fork 5 + P1 fork 6 拥有)
8. ❌ **不许修改 contracts/protocol-v1.md**(已 frozen · plugin-loading 入 v2)
9. ❌ **不许嵌入式 lib 集成示例**(留 fork 2 phase1 · fork 7 phase2)
10. ❌ **不许跳验收**(cmake build / ctest 任一红必须修到全绿)
11. ❌ **不许省略三元组 trailer**(含 [review] + [abi-frozen] + [isolation] 三个特殊标记)
12. ❌ **不许自改本 prompt 文件**

解锁链(本任务 zombie 后)

  • ✅ fork 4 P6.UA9-plugin-loader-pc 解锁(LoadLibrary + ABI 校验需 plugin_abi.h v1)
  • ✅ fork 3 P6.UA9-plugin-registry-static 解锁(builtin 注册需 plugin_abi.h)
  • ✅ fork 5 P5.UA9-plugin-registry-service Phase B 切真接口(C# 端 P/Invoke 需 ABI 字段对齐 · Phase A mock 用 hardcoded ABI 字段)
  • ✅ fork 8 xivst-sdk.UA9-bootstrap 解锁(SDK include/ 直接 copy plugin_abi.h v1 + docs/abi-reference.md)
  • ✅ K2-protocol-v2 §plugin-loading 起草解锁(ABI 字段是契约 §plugin-loading 的核心 schema)
  • ✅ ADR-09 §2.6 #1 边界铁律启动(plugin_abi.h v1 永久 frozen · 任何修订走 ADR-09-RX)

风险评估

风险 缓解
⚠️ ABI v1 字段设计错误 · 冻结后无法改 ClaudeB 第二轮评审强制 · ADR §3.2 已标"早期设计错误代价高 · 落盘前必须有第二轮 ABI 评审"
⚠️ 32/64-bit 平台 ABI alignment 差异 struct 字段加 explicit padding · 单测 sizeof + offsetof 在 32/64-bit 都跑(CI 双平台 · 若有)
⚠️ 字段顺序意外变更(后续 fork 修订引入) offsetof 单测全覆盖 · CI 检测字段偏移变更即 fail
⚠️ Windows __cdecl vs Linux 默认调用约定 XIS_ABI_CALL 宏抽象 · Windows 显式 __cdecl · Linux 空(默认 cdecl)
⚠️ ClaudeB 评审反复 worker 修订 → ClaudeB review 循环 · 直到 approved · 不强求一次过
⚠️ worktree 配置错误(用户未先 git worktree add) step 1 强制用户预配置 · worker 接 prompt 时检查 worker_cwd 是否存在

历史

时间 事件 hash
2026-05-30 12:11 dispatched · ADR-09 4 fork 首批派发(B 方向 · fork 1+2+5+6 跨栈并行)· UID v1.4 命名 P6.UA9 · isolation: task 独立 worktree —