视觉规范实景演示 · Format Showcase v1.0

本页是 nav-demo/format-demo-0-current.html 在 mkdocs 站点内的实景对照页。任何 P1-P3 阶段智能体在写作时,对照本页可以直接抄写每个视觉组件的 raw HTML 模板。

9 条视觉决议 + 12 类 admonition(6 组语义)+ 双轨数学公式 + 产品 6 色堆叠,本页全部演示一遍。

1. 引言/箴言卡 · `.xy-quote`(决议 1)

让上游算法看不见数据来自哪里 —— Source 模块的存在意义。
上游只关心采样块流,不关心信号源是真实麦克风、合成正弦波、还是 WAV 文件回放。

XiStudio Architecture Council · 2026

延伸: 这是行业 DSP 框架的通行做法 — JUCE 的 AudioIODevice、SuperCollider 的 Server、Apple Core Audio 的 AudioUnit 都采用了类似的输入抽象。

2. 术语网格 · `.xy-glossary`(决议 2)

XiStudio L4 工具

羲音工坊 IDE · 可视化 DSP 算法编排平台,面向调音师与声学工程师。

XiAlgo L3 算法

羲音算法引擎 · DSP Core,提供 Source/Sink/Mixer/EQ 等 9 大模块。

XiDSP L0 芯片

羲音芯 · 车规级音频 DSP 芯片,L0 芯片基础层。

DSP

Digital Signal Processing · 数字信号处理。

WASAPI

Windows Audio Session API · 微软原生音频会话 API。

Source 模块

音频源抽象 · 统一 device / tone / wav 三类输入。

3. Admonition 6 组语义配色(决议 3)

12 类 admonition 严格按 6 组语义选用,违反语义即 PR 拒绝(见 agent-handoff-spec.md §3.5 / R9)。

3.1 信息组 · 紫霞(`note / info / abstract`)

信息组示例 · info

Source 模块的实例由 SourceFactory::create() 创建,所有实例共享同一个 audio_clock。WASAPI loopback 在 Windows 11 24H2 之前的版本有 ~2ms 时延抖动。

信息组示例 · note

本节为 v0.3 版本撰写,后续如有架构调整请同步更新本文与 tech-arch.md。

信息组示例 · abstract

本文档摘要:介绍 Source 模块的三种输入类型抽象、性能基线、错误处理策略,以及与 Sink 模块的对接接口约定。

3.2 提示组 · 极光青(`tip / success / question`)

提示组示例 · tip

在 dev 环境用 tone 源做端到端测试比 device 源更稳定 — 没有外部硬件依赖,可重现。

提示组示例 · success

P0.5 试点 6 commit 已全部 mkdocs build 通过,0 ERROR + warning 数稳定。

提示组示例 · question

是否需要支持 ASIO?目前评估中,详见 migration-plan-2026Q2.md §6.3 P3 任务。

3.3 警告组 · 玫瑰金(`warning`)

警告组示例 · warning

切换 device_id 时如果当前流正在跑,会丢一帧 — 上层需要处理 SourceSwitched 事件做平滑过渡。

3.4 危险组 · 赤陶(`failure / danger / bug`)

危险组示例 · danger

不要在 RT 线程内调用 device_enumerate(),会触发 COM 初始化阻塞,直接导致音频丢帧。

危险组示例 · failure

BUG-2026-042:WASAPI loopback 在某些 Realtek 驱动下首帧静音,workaround 见 _dev/wasapi-loopback-workaround.md。

危险组示例 · bug

已知问题:Tone 源在采样率切换瞬间会有一个 click,P1 阶段修复中。

3.5 示例组 · 古铜金(`example`)

示例组示例 · example

创建 1kHz 正弦音源并跑 100ms 的最小示例:SourceFactory::create(SourceType::Tone) → set_param("freq", 1000.0f) → start() → sleep_for(100ms) → stop()。

3.6 引用组 · 中性灰(`quote`)

引用组示例 · quote

"From Silicon to Sound" — 从芯片到声音,是 Xisound 的核心命题。Apple Core Audio 的 AudioUnit 抽象走得更远 — 把 source 和 sink 合并为统一的 IO 端口。

4. Tabs 多语言代码切换(决议 4)

激活 tab = 玫瑰金实色填充 + 白字,非激活 = 浅底灰字。

PythonTypeScriptCC#

import xistudio as xs

src = xs.Source.tone(freq=1000.0, amp=0.5)
src.start()

import { Source, SourceType } from '@xisound/xistudio'

const src = new Source(SourceType.Tone)
await src.setParam('freq', 1000)
await src.start()

#include <xistudio/source.h>

source_t* src = source_create(SOURCE_TYPE_TONE);
source_set_param(src, "freq", 1000.0f);
source_start(src);

var src = SourceFactory.Create(SourceType.Tone);
src.SetParam("freq", 1000.0f);
src.Start();

5. Mermaid 流程图 + Subgraph 子图浅底(决议 5)

5.1 简单 Source-Pipeline-Sink 流程

flowchart LR
  A[Device 输入]:::xyL1 --> B[Source 模块]:::xyL3
  B --> C[DSP Pipeline]:::xyL3
  C --> D[Sink 输出]:::xyL0

5.2 多层架构(子图按产品色系浅底)

flowchart TB
  subgraph SG1[L1 · 信号输入层]:::xySgL1
    direction LR
    A1[Device IO]:::xyL1
    A2[Tone Gen]:::xyL1
    A3[WAV Reader]:::xyL1
  end

  subgraph SG2[L3 · 算法引擎层]:::xySgL3
    direction LR
    B1[SourceModule]:::xyL3
    B2[Mixer]:::xyL3
    B3[EQ]:::xyL3
  end

  subgraph SG3[L4 · 工具层]:::xySgL4
    C1[XiStudio IDE]:::xyL4
  end

  SG1 --> SG2 --> SG3

智能体写作提示:节点用 :::xyL{0..5},子图用 :::xySgL{0..5},永不手写 style A fill:#xxx(违反 R8)。

6. Mermaid 甘特图(决议 6 · Mermaid 双轨之 Mermaid 轨)

gantt
    title Source 模块 P0-P2 路线图(2026 Q1-Q2)
    dateFormat YYYY-MM-DD
    axisFormat %m

    section P0 · 基础三源
    Device 实现       :done,    p0a, 2026-03-01, 14d
    Tone 实现         :done,    p0b, after p0a, 7d
    WAV 实现          :done,    p0c, after p0b, 10d

    section P1 · 性能优化
    WASAPI 抖动修复    :active,  p1a, 2026-04-01, 14d
    Tone FM 调制      :         p1b, after p1a, 10d

    section P2 · 高级特性
    多通道路由         :         p2a, 2026-05-15, 21d
    ASIO 评估         :         p2b, after p2a, 7d

上图通过 xiyin-mermaid.js 中注入的 themeVariables.ganttDoneColor / ganttActiveColor / ganttPlannedColor 自动配色。

由 xiyin-mermaid-zoom.js 自动给所有 .mermaid 容器右上角注入 ⛶ 放大按钮。点击进入全屏 modal,ESC 或点击空白处关闭。 本页所有 mermaid 图都已自动启用此功能,无需写额外 HTML。

8. 数学公式(决议 8 · 双轨之 KaTeX 轨)

本页 frontmatter 已设 katex: true,KaTeX 已动态加载。

8.1 行内公式

声压级行内公式: $L_p = 20 \cdot \log_{10}(p / p_0)$ dB,其中 $p_0 = 20\,\mu\text{Pa}$ 为参考声压。

8.2 块级公式

信噪比 SNR 定义:

\[ \text{SNR} = 20 \cdot \log_{10} \frac{A_{\text{signal}}}{A_{\text{noise}}} \quad [\text{dB}] \]

Nyquist 采样定理:

\[ f_s \geq 2 \cdot f_{\max} \]

FIR 滤波器卷积运算:

\[ y[n] = \sum_{k=0}^{N-1} h[k] \cdot x[n-k] \]

8.3 Unicode + HTML 备用方案(决议 8a · 不依赖 KaTeX 时)

如果某页不希望加载 KaTeX(katex: false),可用 .xy-frac + Unicode 字符渲染分数:

SNR = 20 · log₁₀ A_signal A_noise [dB]

公式 8a-1 · SNR 定义(Unicode + HTML 备用方案)

9. 产品 6 色层级栈 · `.xy-stack`(决议 9)

L5
XiMind 云端智能
Cloud · 远程编排 · 模型推理
CLOUD
L4
XiStudio 工坊 IDE
Tooling · 可视化算法编辑器
TOOL
L3
XiAlgo 算法引擎
Algorithm · DSP Core · Source/Sink/Mixer/EQ
CORE
L2
XiTune / XiTest 调音测试
Tuning & Test · 调音师工具
TUNE
L1
XiAmp / XiBox 硬件
Hardware · 功放 / 音频盒
HW
L0
XiDSP 芯片
Silicon · 车规级音频 DSP
SoC

上图最显眼的"⭐ 本文重点"标记由 .xy-stack-layer.highlight 自动叠加,本页演示放在 L3 算法层。

10. 表格(性能基线表)

配置	单帧 CPU%	内存峰值	备注
`tone @ 48k/256`	0.08%	1.2 MB	纯合成,无 IO
`wav @ 48k/256`	0.15%	8.4 MB	含 mmap 缓冲
`device @ 48k/256`	0.32%	2.1 MB	含 WASAPI driver

11. 任务清单

Source 模块 P0 完成(device + tone + wav)
试点迁移 6 commit 落地
v0.3 应用 9 条改进意见
P0 基础设施全部完成
Sink 模块 P0 启动
端到端联调测试
P1 内容迁移阶段启动

12. 给智能体的写作模板速查

下表是本页用到的所有视觉组件的 raw HTML 模板,智能体可以直接复制粘贴使用:

组件	章节	抄写位置
引言箴言卡	§1	`<div class="xy-quote" markdown>`
术语网格	§2	`<div class="xy-glossary" markdown>`
Admonition 6 组	§3	用 `!!! <type> "标题"` Markdown 语法
Tabs	§4	用 `=== "标签"` Markdown 语法
Mermaid 节点配色	§5.1	`:::xyL0` ~ `:::xyL5`
Mermaid 子图配色	§5.2	`:::xySgL0` ~ `:::xySgL5`
甘特图	§6	```mermaid \n gantt ...
数学公式	§8	`$inline$ / $$block$$`(frontmatter `katex: true`)
Unicode 数学备用	§8.3	`<div class="xy-math" markdown>`
产品 6 色栈	§9	`<div class="xy-stack" markdown>`
性能表	§10	标准 Markdown 表格(不嵌 HTML!)
任务清单	§11	`- [x] / - [ ]`

重要:本页所有 raw HTML 都加了 markdown 属性,这是 md_in_html 扩展的语法,确保 HTML 内的 Markdown 会被继续解析。智能体写作时必须保留 markdown 属性,否则 HTML 内的 **bold** / 链接 / 列表都不会被处理。

13. 修订记录

版本	日期	修订人	改动
1.0.0	2026-05-11	Cline / AlgoDepartment Doc Council	首版 · P0 完成时同步发布,作为 9 决议在 mkdocs 内的实景对照 + 智能体抄写模板

下一步:智能体在 P2 内容增强阶段需要给某份文档加视觉组件时,回到本页 §12 速查表,复制对应 raw HTML 模板,然后填入自己的内容。视觉问题 → 不要猜测,先看本页是怎么实现的;本页没演示的组件 → 看 format-spec-changelog.md。