跳转至

xivst-sdk.A14.F5-pc-only-bootstrap · xivst-sdk-1.0 PC-only 包(vendor 自助开发 SDK)

Worker: ClaudeB(主导)+ Cline-AIOS(docs 协作)· 部门: DSP + Docs · 预计: 2.0d · 优先级: P2 · 状态: dispatched

🔍 触发与解锁链

  • 触发:ADR-AIOS-14 §4.3 fork 5 · 用户 2026-06-02 11:56 start xivst-sdk.A14.F5-pc-only-bootstrap
  • 前置全 ✅:fork 1 3c83f25(framework loader API)+ fork 2 c440023(dll 导出 + xisound-host.lib)+ fork 3 8d53b68(C# IPluginRegistry)三件套全 zombie · ADR-14 后端三层就位 · vendor 现可自助开发第三方 PC dll
  • 解锁:ADR-14 整体闭环 100%(5 fork 全 zombie 后)+ fork 4 P1.A14.F4 真联调(VITE_MOCK_PLUGINS=false)的 hello-effect-v1.dll 端到端验证(Playwright 拖入 stage + 注入 1kHz 信号 + 验证 -14dBFS ± 1dB)

任务定义(基于 ADR-AIOS-14 §2.5 + §4.3 fork 5)

发布 xivst-sdk-1.0 PC-only 包 · 让第三方 vendor(0xAAAA0000+ 段位)能在 PC 平台上自助编译 dll 加载到 host:include/(v7 module_interface.h)+ lib/windows/(xisound-host.lib · fork 2 已导出)+ templates/hello-effect-v1/(完整 vendor 模板 · 含 source + CMakeLists + README)+ docs/(abi-reference + pc-build-guide)。DSP 端不发 SDK(永久铁律 · 见 ADR §2.6)。

业务行为契约 5 必填段:完整继承 ADR-AIOS-14 §2.5 ① 输入输出 + ② 收敛判据 + ③ 失败回退 5 类 + ④ 用户操作流 5 步 + ⑤ e2e 真值(本 prompt 不重复 · worker 必读 ADR §2.5)。本 fork e2e 真值落点 = §⑤ 测试用例 Step 1-5(vendor 编译 hello-effect-v1.dll → 部署 plugins/thirdparty/test/ → host 启动加载 → ModuleLibrary 暴露 → chain 注入 1kHz -20dBFS → 输出 -14dBFS ± 1dB · 即 ADR §2.5 ⑤ 完整 e2e 真值脚本本期落地)。

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

[U-thread] xivst-sdk.A14.F5-pc-only-bootstrap(ADR-14 fork 5 · v1.9 新命名 · ADR 整体闭环最后拼图)
[部门] DSP + Docs · ClaudeB 主导 + Cline-AIOS docs 协作 · 2.0d · P2
[Worker CWD] d:/work/25_claude/workspace/AlgoDepartment/04_development/
[Occupies] xivst-sdk.K-bootstrap(新建 · xivst-sdk/ 顶级目录 · include/ + lib/windows/ + templates/hello-effect-v1/ + docs/)
[优先级] P2 · feature · 🚀 task 隔离
[ADR] docs/08-implementation/40-aios/ADR/ADR-AIOS-14-pc-dynamic-plugin-loading.md(必读 §2.2+§2.3 ABI + §2.5 5 必填段 + §4.3 fork 5 + §2.6 DSP 不发 SDK 铁律)
[参考文档]
  - dsp-algo v7 §4.2 ModuleFuncTable + §4.3 module_type_id.h:docs/03-platform/40-dsp-algo/10-architecture-v7.md
  - 三件套已 zombie 上游:① fork 1 framework/dynchain_loader_pc.{c,h}(`3c83f25`)· ② fork 2 dll/dspalgo_dll.c 导出 + sdk/include/xisound_plugin_sdk.h stub(`c440023`)· ③ fork 3 backend_csharp/Services/Plugin/ + REST(`8d53b68`)
  - 标本仿写:prompts/done/ADR-AIOS-14/F1-load-dynamic-plugins-api--3c83f25.md(155 行 · vendor 入口符号约定)
  - ADR-04 §2.1.2 vendor 段位:0xAAAA0000~0xFFFEFFFF 21845 家第三方
  - hello-world 范式:prompts/done/ADR-AIOS-14/P6.UB14-pc-host-sdk-export--c440023.md(SDK header stub 已落地 · 仅扩展为完整模板)

【背景】
ADR-14 整体闭环 5 fork 中最后 1 fork(前 4 已就位)· 让第三方 vendor 自助开发 PC dll · 严守 §2.6"DSP 端永远静态注册"铁律(SDK 不含 DSP 编译产物)。
worker 必读 ADR §2.5 业务行为契约 5 段 + §4.3 fork 5 描述(xivst-sdk 包结构)。
注意:fork 2 已落 sdk/include/xisound_plugin_sdk.h stub · 本任务把 stub 升级为完整 vendor 入口 + 加 templates/hello-effect-v1/ vendor 模板 + 完整 docs。

【执行步骤 7 步】

Step 1 · 上游真值核查(0.2d)
  - read ADR-14 §2.2 vendor 入口符号 + §2.3 LoadDynamicPluginsStats + §2.5 5 必填段 + §4.3 fork 5 包结构
  - read v7 §4.2 ModuleFuncTable + §4.3 module_type_id.h vendor 段位定义
  - read 现有 sdk/include/xisound_plugin_sdk.h(fork 2 落地的 stub)· dll/dspalgo_dll.c 导出符号
  - read framework/dynchain_loader_pc.{c,h}(fork 1 落地的 LoadLibrary loader)
  - 验证三件套 zombie 状态:git log --all --oneline | grep -E '3c83f25|c440023|8d53b68'

Step 2 · 创建 xivst-sdk/ 顶级目录结构(0.2d)
  - xivst-sdk/include/(从 dsp_algo/include/ 复制 module_interface.h + dynchain_interface.h · 作为 vendor 公开 ABI)
  - xivst-sdk/lib/windows/(从 build 输出复制 xisound-host.lib · vendor 链接用)
  - xivst-sdk/templates/hello-effect-v1/(完整 vendor 模板)
  - xivst-sdk/docs/(abi-reference.md + pc-build-guide.md)
  - xivst-sdk/README.md(顶层 README · vendor 入门指南 · 5 步 quick start)
  - xivst-sdk/VERSION(1.0.0)

Step 3 · 完成 templates/hello-effect-v1 完整 vendor 模板(0.6d)
  - hello-effect-v1/CMakeLists.txt(MSVC + 链接 xisound-host.lib + 输出 dll · 跨平台 stub)
  - hello-effect-v1/src/hello_effect.c(实现 ModuleFuncTable 6 函数 · 单 module gain × 2 · typeNumId=0xAAAA0001 · typeName="hello_effect_gain2x_v1")
  - hello-effect-v1/src/hello_effect.h(C linkage · 内部前置声明)
  - hello-effect-v1/plugin_entry.c(导出 xisound_plugin_register · 调 ModuleRegistry_Register 注册 hello_effect)
  - hello-effect-v1/README.md(vendor 视角 · build + 部署 + 验证 3 步)
  - 实施细节 worker 自行决定 · 参考 dsp_algo/modules/<existing>/ 现有 builtin module 仿写 · 严守 v7 ABI 不二造

Step 4 · sdk/include/xisound_plugin_sdk.h 升级(0.2d)
  - fork 2 落地的 stub 仅含 ModuleFuncTable typedef · 本任务扩展为完整 vendor 入口
  - 包含 v7 module_interface.h + 添加 ModuleRegistry_Register 函数指针 typedef + xisound_plugin_register signature
  - vendor 包含本头文件即可获取所有必要类型 + API · 单文件依赖最小化

Step 5 · docs/(0.4d · Cline-AIOS 协作)
  - abi-reference.md:v7 ABI 完整参考(ModuleFuncTable 6 函数 + WireInstance + module_type_id 段位 + 内存模型 · ~150 行)
  - pc-build-guide.md:vendor PC 编译指南(prerequisites + cmake -DTARGET=PC · 部署到 plugins/thirdparty/<vendor>/<dll>.dll · host 启动验证 · ~100 行)
  - 严守 v1.6 §"prompt 内容硬约束":docs 各 ≤ 200 行 · 不含完整代码示例 · 引用 templates/hello-effect-v1 即可

Step 6 · 端到端真值 e2e(0.3d · ADR §2.5 ⑤ 完整 5 步落地)
  - Step 1 · 编译 hello-effect-v1:cd xivst-sdk/templates/hello-effect-v1 && cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build --config Release · 输出 hello_effect_v1.dll
  - Step 2 · 部署到 plugins/thirdparty/test/:copy hello_effect_v1.dll → C:/ProgramData/Xisound/plugins/thirdparty/test/(host 默认扫描路径)
  - Step 3 · 启动 host:dotnet run --project backend_csharp · 日志输出 LoadDynamicPluginsStats(scanned=1 · loaded=1 · failed=0 · skipped=0)
  - Step 4 · curl /api/plugins/list:返回含 hello_effect_gain2x_v1 项 · vendorTag="thirdparty" · typeNumId=0xAAAA0001
  - Step 5 · ModuleLibrary 拖入 + chain 注入 1kHz -20dBFS 正弦 → 验证 sink 输出 -14dBFS ± 1dB(gain × 2 = +6dB · ADR §2.5 ⑤ 真值断言)
  - 若 fork 4 P1.A14.F4 已 zombie · UI 端到端 Playwright 跑通(ADR §2.5 §⑤ 测试用例完整版)
  - 若 fork 4 仍 dispatched · backend curl 验证完成即可(UI 端到端留 fork 4 zombie 后跑)

Step 7 · commit + 文档同步(0.1d · Cline-AIOS 协作)
  - git add xivst-sdk/ sdk/include/xisound_plugin_sdk.h
  - subject:feat(xivst-sdk.A14.F5/pc-only-bootstrap): xivst-sdk-1.0 PC-only 包发布(vendor 自助 SDK + hello-effect-v1 模板 + abi-reference + pc-build-guide)
  - 三元组 trailer:[step=7/7] [pid=xivst-sdk] [uid=A14.F5-pc-only-bootstrap] [occupies=xivst-sdk.K-bootstrap] [files=xivst-sdk/* sdk/include/xisound_plugin_sdk.h]
  - Cline-AIOS 同步:更新 docs/08-implementation/40-aios/INDEX.md 加 xivst-sdk 入口 · ADR-14 §10 状态流转加 fork 5 zombie(本任务 zombie 后)

【验收】
☐ 文件清单:xivst-sdk/{include/,lib/windows/,templates/hello-effect-v1/{CMakeLists.txt,src/*,plugin_entry.c,README.md},docs/{abi-reference.md,pc-build-guide.md},README.md,VERSION}
☐ hello-effect-v1.dll 编译成功(MSVC Release · 无错误)· 部署后 host 加载成功
☐ /api/plugins/list 返回 hello_effect_gain2x_v1 + vendorTag=thirdparty + typeNumId=0xAAAA0001
☐ chain 注入 1kHz -20dBFS → 输出 -14dBFS ± 1dB(gain × 2 = +6dB · ADR §2.5 ⑤ 真值)
☐ 业务行为契约 5 段引用 ADR-14 §2.5(input/output + 收敛 + 失败回退 5 类 + 操作流 + e2e 真值)
☐ DSP 端零修改(严守 §2.6 铁律 · 不动 dsp_algo/modules/* + framework/dynchain_static.* + dll 之外的 dsp 编译流程)
☐ ADR-14 整体闭环 5/5 fork zombie

【禁止】
❌ 不修改 framework/* 或 dll/dspalgo_dll.c(fork 1+2 已落地)
❌ 不修改 backend_csharp/* 任何文件(fork 3 已落地)
❌ 不修改 dsp_algo/modules/* 或现有 module 注册(永久禁止 · §2.6 铁律)
❌ 不引入第二套 module ABI(强制复用 v7 ModuleFuncTable)
❌ 不在 templates/hello-effect-v1 嵌入完整 C 实现 > 50 行(仅 stub + skeleton · vendor 自行实装数学)
❌ 不让 SDK 依赖 DSP 编译产物(SDK 仅 PC 端 · DSP 走内部团队 + 重编固件流程)
❌ commit 不带三元组(7 天宽限期 · 6/2 已开始 strict mode hook)

解锁链(本任务 zombie 后)

  • 🏆 ADR-14 整体闭环 100%(5 fork 全 zombie · status accepted+impl → fulfilled)· 解锁第三方 vendor 生态启动
  • ✅ ADR-14 §2.5 ⑤ e2e 真值首落地 + ADR §A 验收清单 §5.3 全过
  • ✅ 后续 vendor 接入路径:vendor 拿到 xivst-sdk-1.0 → 编 dll → 部署 plugins/thirdparty// → host 自动扫描加载 · 无需 Xisound 内部团队介入

风险评估

风险 缓解
MSVC 链接 xisound-host.lib 找不到符号(fork 2 导出问题) Step 1 必读 fork 2 prompt + 验证 dumpbin /exports DSPAlgo.dll · 不齐则 commit trailer 标 [need: P6.UB14-pc-host-sdk-export-fix]
hello-effect-v1.dll 加载失败(LoadLibrary 错或 GetProcAddress 缺) Step 6 真值 e2e Step 3 必跑 · 失败时核对 fork 1 错误处理 5 类(返回 5 类失败原因)
docs 写散没重点 Cline-AIOS 协作时严守 ≤ 200 行/文件 + 引用 templates/hello-effect-v1 仿写 · 不嵌完整 vendor 实现
Cline-AIOS 与 ClaudeB 边界冲突 边界:ClaudeB 写 sdk/include/ + xivst-sdk/templates/ + xivst-sdk/lib/windows/ + xivst-sdk/CMakeLists · Cline-AIOS 写 xivst-sdk/docs/ + xivst-sdk/README.md + INDEX.md 同步 · ADR §10 状态流转

历史

时间 事件 hash
2026-06-02 11:56 dispatched · ClaudeB+Cline-AIOS · 2.0d · v1.9 新命名格式 · ADR-14 整体闭环最后一块拼图 · 三件套(F1+F2+F3)全 zombie 完全前置就位 -