跳转至

P6.UB14-pc-host-sdk-export · 导出 ModuleRegistry_Register + 整理 xisound-host.lib

Worker:ClaudeB(P6 主战场 · DSP 算法库 daemon) 部门:DSP · 原生 C(dspalgo/dll/ + 链接器配置) 预计:1.0d 优先级:P1(ADR-14 Phase 1 立即行动 #2 · 与 fork 1 文件正交并行) 状态:dispatched

🔍 触发与解锁链

  • 触发:用户 2026-06-02 09:59 同步指令 start P6.UB14-pc-host-sdk-export(fork 1 在跑 · 文件正交可并行)
  • 本任务 zombie 后解锁:
  • xivst-sdk.UB14-pc-only-bootstrap(SDK 包 hello-effect-v1.dll 模板需链接本 fork 输出的 xisound-host.lib · 2.0d)

任务定义(基于 ADR-14 §2.2 + §2.3)

让第三方 PC dll 可以通过 __declspec(dllimport) 链接 host 进程内的 v7 ModuleRegistry_Register 符号 · 并整理 xisound-host.lib 作为 PC SDK 发布包 lib 入口。本 fork 仅碰 dll/dspalgo_dll.c(导出符号修订)+ CMake target 配置(xisound-host.lib 输出)+ exports 头文件 · 不动 framework/dynchain_loader_pc.c(fork 1 处理)。

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

[U-thread]   P6.UB14-pc-host-sdk-export(ADR-14 §2.2 + §2.3 fork 2 net-new SDK lib)
[部门]       DSP · 原生 C + MSVC 链接器
[Worker CWD] d:/work/25_claude/workspace/AlgoDepartment/04_development/
[Occupies]   P6.K4-include + P6.K5-build-system
[优先级]     P1 · 1.0d · 与 fork 1 文件正交并行
[ADR]        docs/08-implementation/40-aios/ADR/ADR-AIOS-14-pc-dynamic-plugin-loading.md
[上游必读]   docs/03-platform/40-dsp-algo/10-architecture-v7.md(2455 行 · §4.5 公开 API + §5 ModuleRegistry_Register 签名)
[参考文档]   ADR-14 §2.2(dll 入口符号约定 ModuleRegistryRegisterFn)+ §2.3(host 整合点 dspalgo_dll.c)+ §4.1 fork 2 描述
[隔离]       🚀 task · 与 fork 1(framework/dynchain_loader_pc.c)文件正交 · 仅碰 dll/ + CMake exports

【背景】
ADR-14 §2.2 定义第三方 PC dll 单一导出符号 xisound_plugin_register · 入参 ModuleRegistryRegisterFn 是 host 提供的注册回调 · 第三方 dll 通过它把自己的 ModuleFuncTable 注册到 host 的 v7 ModuleRegistry。
本 fork 让 host 进程导出 ModuleRegistry_Register · 让第三方 dll 编译期可链接(__declspec(dllimport))· 整理 xisound-host.lib 作为 SDK 发布包 lib 入口(对齐 fork 5 xivst-sdk.UB14-pc-only-bootstrap 的 lib/windows/xisound-host.lib 路径)。

【执行步骤】

Step 1 · 上游真值核查(必跑)
- 读 v7 §5 dynchain_registry.c · 确认 ModuleRegistry_Register(uint32_t typeNumId, const char *typeName, const ModuleFuncTable *pFuncs) 签名
- 读 v7 §4.5 dynchain_interface.h · 确认现有 DynChain_* 公开 API 已 __declspec(dllexport)(若已有 macro · 直接复用)
- 读 ADR-14 §2.2 ModuleRegistryRegisterFn typedef · 确认与 v7 ModuleRegistry_Register 完全签名一致(无中间适配)
- 读 dll/dspalgo_dll.c 现有导出风格(WINDOWS_EXPORT_ALL_SYMBOLS ON / __declspec / .def 文件 · 任选其一 · 保持现有约定)

Step 2 · 在 dynchain_interface.h 加 ModuleRegistry_Register 显式导出声明
- 包装宏:#ifdef _WIN32 #define XISOUND_HOST_API __declspec(dllexport) #else #define XISOUND_HOST_API __attribute__((visibility("default"))) #endif
- 第三方 dll 编译时:#ifdef _WIN32 (when XISOUND_BUILDING_HOST 未定义) #define XISOUND_HOST_API __declspec(dllimport) #endif(让 vendor 链接)
- 在 dynchain_registry 公开声明 · 加 XISOUND_HOST_API 修饰:
    XISOUND_HOST_API void ModuleRegistry_Register(
        uint32_t typeNumId,
        const char *typeName,
        const ModuleFuncTable *pFuncs);
- 不修改函数实现(v7 §5 已有)· 仅加导出修饰

Step 3 · CMake 整理 xisound-host.lib 输出
- 在顶层或 dll/CMakeLists.txt 加 if(WIN32) target_compile_definitions(DSPAlgo PRIVATE XISOUND_BUILDING_HOST=1) endif()(让本身编译时走 dllexport · 第三方 dll 编译时不定义 → 走 dllimport)
- 确认 DSPAlgo SHARED target 编译产物含 DSPAlgo.lib(MSVC 自动生成的 import lib · 含 ModuleRegistry_Register 导出条目)
- 加 install target 或 build 后 copy 步骤:把 build/Release/DSPAlgo.lib 复制为 build/sdk/xisound-host.lib(或保留原名 · 由 fork 5 xivst-sdk-bootstrap 重命名 · 本 fork 文档中明确路径约定)
- 验证:dumpbin /exports DSPAlgo.dll 应能看到 ModuleRegistry_Register · DynChain_LoadDynamicPlugins(fork 1 同栈合并后)等符号

Step 4 · 加 SDK 公开头文件(单文件 stub · 给 vendor 用)
- 新建 sdk/include/xisound_plugin_sdk.h(本 fork 落 stub · fork 5 xivst-sdk-bootstrap 完善):
    #include "module_interface.h"   // v7 ModuleFuncTable
    #include "dynchain_types.h"     // v7 WireInstance
    #include "module_type_id.h"     // v7 type_id 段位常量
    // ModuleRegistryRegisterFn typedef(对齐 ADR-14 §2.2)
    // 第三方 dll 必须 __declspec(dllexport) 导出 xisound_plugin_register 函数
- 注:本 fork 不实装 hello-effect-v1.dll 模板(留 fork 5)· 仅落 SDK 单头文件 stub + 路径约定文档

Step 5 · 单元测试 / 集成验证
- 加 1 个 MSVC 测试程序(tests/sdk-link-smoke/main.c · 模拟第三方 dll 编译):
    extern "C" __declspec(dllimport) void ModuleRegistry_Register(uint32_t, const char*, const ModuleFuncTable*);
    int main() { /* 不实际调用 · 仅验证链接成功 */ return 0; }
- CMake 加 test target · link_libraries(DSPAlgo)· cl.exe + link.exe 编译通过 = OK
- 不需要跑(只验证链接器能解析 ModuleRegistry_Register 符号 · 等价于 fork 5 vendor dll 编译场景)

Step 6 · 文档 + commit
- 在 dynchain_interface.h 顶部加注释块:"// ABI export: ModuleRegistry_Register exposed to third-party PC dll via __declspec(dllimport) · ADR-14 §2.2"
- 在 sdk/README.md(stub)写明 SDK 用法约定(fork 5 完善):
    1. 第三方 vendor 编译 dll 时 #include <xisound_plugin_sdk.h> + link xisound-host.lib
    2. dll 内部实现 ModuleFuncTable + 导出 xisound_plugin_register 函数
    3. 部署到 plugins/thirdparty/<vendor>/<dll>.dll · host 启动时 fork 1 的 DynChain_LoadDynamicPlugins 自动加载

【验收】
✓ dynchain_interface.h(或 dynchain_registry 公开声明)加 XISOUND_HOST_API 导出修饰
✓ dll/dspalgo_dll.c 不破坏现有 P/Invoke 导出(C# 端 DllImport 全过)
✓ CMake target_compile_definitions XISOUND_BUILDING_HOST=1 仅在 host 编译时定义
✓ build 产物 DSPAlgo.lib 含 ModuleRegistry_Register 导出条目(dumpbin 验证)
✓ sdk/include/xisound_plugin_sdk.h stub 头文件落盘(单文件聚合 v7 ABI)
✓ tests/sdk-link-smoke 链接通过(模拟第三方 dll 编译)
✓ MSVC 编译 0 错 0 警 · 现有 dsp_algo 测试套件 0 回归
✓ DSPAlgoStatic(嵌入式静态库)体积无变化(本 fork 仅影响 PC dll · DSP 端零修改)
✓ commit 含三元组 trailer:[step=6/6] [pid=P6] [uid=UB14-pc-host-sdk-export] [occupies=P6.K4+P6.K5] [files=include/dynchain_interface.h+dll/dspalgo_dll.c+CMakeLists.txt+sdk/+tests/sdk-link-smoke/]

【commit 规范】
subject:feat(P6.UB14/pc-host-sdk-export): 导出 ModuleRegistry_Register + 整理 xisound-host.lib(ADR-14 §2.2)

trailer 必填:
[step=6/6] [pid=P6] [uid=UB14-pc-host-sdk-export] [occupies=P6.K4+P6.K5] [files=...]
[ipc=none]

参考 done/ 12 标本 commit message 结构 · 不允许跳三元组(7 天宽限期内 warning · 6/2 起 strict mode hook 硬拒)

【禁止】
❌ 修改 framework/dynchain_loader_pc.c(fork 1 处理 · 文件正交)
❌ 修改 v7 §5 dynchain_registry.c 实现(冻结 · 仅加导出修饰宏 · 不动函数体)
❌ 修改 v7 §4.2 module_interface.h(冻结 · 仅 SDK 头文件 #include 引用)
❌ 实施 hello-effect-v1.dll 模板(留 fork 5 xivst-sdk-bootstrap)
❌ 改 builtin module 注册流程(modules_config.h + module_registry_all.c 永久不动)
❌ DSP 平台执行任何 dll 导出修订(本 fork CMake 仅 if(WIN32))
❌ 仅靠 typecheck/build 全绿就 commit · 必须跑 tests/sdk-link-smoke 链接验证(ADR-14 §2.5 ⑤ e2e 真值精神)

解锁链(本任务 zombie 后)

  • ✅ xivst-sdk.UB14-pc-only-bootstrap(2.0d · 等本 fork zombie · SDK 包 templates/hello-effect-v1/ 模板需链接 xisound-host.lib)

风险评估

风险 缓解
WINDOWS_EXPORT_ALL_SYMBOLS ON 已开 + 显式 __declspec(dllexport) 双重导出冲突 检查现有 CMake 配置 · 若已开自动导出 · 仅在 sdk/include/xisound_plugin_sdk.h 加 dllimport 修饰即可(host 端无需改)
CMake target_compile_definitions XISOUND_BUILDING_HOST 误定义到 vendor dll 编译流程 严格限定到 DSPAlgo SHARED target 内部 · vendor SDK 编译时不引入此定义
dumpbin /exports 验证缺 ModuleRegistry_Register 符号 改用 .def 文件显式列符号 · 强制 link.exe 导出
与 fork 1 commit 时序冲突(双方都改 dynchain_interface.h) Step 2 仅在 dynchain_interface.h 末尾追加 XISOUND_HOST_API 宏 + 声明 · fork 1 仅在末尾追加 #ifdef _WIN32 #include "dynchain_loader_pc.h" · 行号正交 · git rebase 自动合并
第三方 vendor 链接时 host SDK lib 路径不一致 本 fork 落"build/sdk/xisound-host.lib" · fork 5 xivst-sdk-bootstrap 复制到 SDK 包 lib/windows/x64/xisound-host.lib

历史

时间 事件 hash
2026-06-02 09:59 dispatched · ClaudeB 立即接(与 fork 1 并行) (待 stop 时回填)