DESIGN.md@agent/ui/visuals/tai_chi git:20261009.9353b84A

Immutable. This exact content never changes and is served at /api/v1/blob/bba8ad56f1e509fd.

# Tai Chi Visual Effect Design

## 1. 设计目标

Tai Chi 是一个连续演化的全屏视觉特效，用动画表现：

> 一画开天 → 阴阳分化 → 太极成形 → 五层演化 → 八卦归位

整个过程不是多个互不相关的画面切换，而是一条连续时间线。前一阶段已经存在的图形应尽量作为下一阶段的动画起点，避免突然消失、重新生成或位置跳变。

视觉基调：

- 背景保持应用当前主题背景，不额外覆盖不透明底色。
- 文字以 `ColorBase.primary_text` 和 `ColorBase.secondary_text` 为主。
- 强调色统一使用 `ThemeColor.alpha_theme_color(alpha)`。
- 强调色只承担轮廓、卦线、微光和轨迹作用，不使用高饱和实色大面积填充。
- 所有位置和尺寸根据 `Control.size` 动态计算，支持不同窗口比例。

## 2. 文件职责

| 文件 | 职责 |
| --- | --- |
| `TaiChi.gd` | 总控制器，驱动各阶段、维护 Shader 图层并决定当前绘制阶段。 |
| `TaiChiOpeningFlow.gd` | 绘制“一画开天”的水平线和开场文字。 |
| `TaiChiDualityFlow.gd` | 将一条线分化为阳爻和阴爻。 |
| `TaiChiFormationFlow.gd` | 将两仪线条变形成完整太极。 |
| `TaiChiEvolutionFlow.gd` | 太极缩小、移动，并从下到上生成五层结构。 |
| `TaiChiBaguaFlow.gd` | 将横排八卦连续移动成圆阵，并将太极移到圆心。 |
| `TaiChiLineAura.gdshader` | 开场线条和两仪阶段的柔和流动光效。 |
| `TaiChiFill.gdshader` | 绘制黑白太极填充图案。 |

## 3. 总时间线

阶段按以下顺序自动启动：

1. Opening：`2.25s`
2. Duality：`2.2s`
3. Formation：`3.2s`
4. Evolution：`14.4s`
5. Bagua：`5.8s`

`TaiChi._process()` 每帧推进当前阶段。当一个阶段的 `progress()` 达到 `1.0` 时，启动下一个阶段。

所有 Flow 均遵循相同生命周期：

- `reset()`：清空时间并停用。
- `begin()`：从零开始并激活。
- `advance(delta)`：累加时间，返回画面是否需要重绘。
- `progress()`：返回经过缓动处理的 `0.0–1.0` 进度。

## 4. 阶段一：一画开天

实现文件：`TaiChiOpeningFlow.gd`

### 步骤

1. 在画面中下部确定水平线中心。
2. 水平线从中心向左右两端同时延伸。
3. “一画开天”四个字同步出现。
4. 文字从中心向外展开，避免像普通淡入字幕。
5. Shader 在水平线周围添加非常轻的流动光带。

### 完成条件

`line_progress() == 1.0` 后启动两仪阶段。

## 5. 阶段二：两仪分化

实现文件：`TaiChiDualityFlow.gd`

### 步骤

1. 开场水平线分离成上下两行。
2. 上行保持完整，表示阳。
3. 下行从中心打开缺口，表示阴。
4. 左右辅助文字随动画后半段出现。
5. 开场标题逐渐退场。

### 完成条件

`progress() == 1.0` 后启动太极成形阶段。

## 6. 阶段三：太极成形

实现文件：`TaiChiFormationFlow.gd`

### 步骤

1. 阳爻弯曲为太极外圆的构造线。
2. 阴爻两段分别收束为上下两个鱼眼。
3. 中央 S 形分界线由上至下绘制。
4. 构造线逐渐退去。
5. `TaiChiFill.gdshader` 的黑白填充逐渐显现。
6. 太极下方显示“易有太极，是生两仪”及英文副标题。

### 关键进度

- `outer_progress()`：外圆构造。
- `upper_inner_progress()`：上方鱼眼。
- `lower_inner_progress()`：下方鱼眼。
- `divider_progress()`：S 形分界。
- `fill_progress()`：黑白填充。

### 完成条件

`progress() == 1.0` 后启动五层演化阶段。

## 7. 阶段四：太极缩小和标题退场

实现文件：`TaiChiEvolutionFlow.gd`

该阶段前半部分先处理太极和标题，再开始生成层级。缩小与移动不能同时发生。

### 步骤

1. 太极保持在成形阶段的中心位置。
2. `shrink_progress()` 驱动太极半径从大尺寸缓慢缩小。
3. 原标题保持相同字距和排版同步缩小。
4. 标题在缩小后半段逐渐透明并完全消失。
5. 太极缩小完成后，`move_progress()` 才开始改变位置。
6. 太极移动到最下层“两仪”内容区域的水平中心。

最终横坐标使用：

```gdscript
content_area(canvas_size).get_center().x
```

这不是整个窗口的几何中心，而是“阳”和“阴”两个内容格之间的正中间。

## 8. 阶段五：五层结构生成

实现文件：`TaiChiEvolutionFlow.gd`

五层从下到上排列：

1. 太极
2. 两仪
3. 四象
4. 八卦
5. 六十四卦

`row_from_bottom == 0` 表示太极层，`row_from_bottom == 4` 表示最上层。

### 层级位置

- 最下层位于画面高度约 `84%`。
- 最上层位于画面高度约 `14%`。
- 中间层通过线性插值均匀分布。
- 左侧约 `8.5%` 宽度用于层级标题。
- 右侧内容区域从画面宽度 `20%` 开始，占据约 `72%`。

### 启动顺序

`row_progress()` 让各层从下到上依次启动，并保留少量时间重叠，使整体动画连续而不拖沓。

每层内部由 `item_progress()` 继续拆分：

- 左侧图案最先启动。
- 后续图案依次延迟。
- 每个图案拥有独立的完整飞行时间。

### 天外飞入动画

除太极以外的图案都从画面顶部之外飞入。

`flying_position()` 的计算过程：

1. 起点 Y 位于 `-70px` 以上，确保图案初始不可见。
2. 起点 X 在画面中心附近形成扇形分布。
3. 使用缓动插值从起点飞向目标位置。
4. 偶数和奇数索引使用相反的横向弧线。
5. 中段弧线偏移最大，起点和终点偏移为零。
6. 图案从小尺寸逐渐恢复到最终尺寸。
7. 飞行中段绘制低透明度短拖尾。
8. 到达目标位置时拖尾自动归零。

当前 Evolution 总时长为 `14.4s`，用于保证飞行过程足够舒缓。

## 9. 卦象编码规则

三爻从画面上方向下绘制，最低有效位对应最上面一爻。

标准编码如下：

| 卦名 | 图形 | 二进制 | 十进制 |
| --- | --- | --- | --- |
| 乾 | ☰ | `111` | 7 |
| 兑 | ☱ | `110` | 6 |
| 离 | ☲ | `101` | 5 |
| 震 | ☳ | `100` | 4 |
| 巽 | ☴ | `011` | 3 |
| 坎 | ☵ | `010` | 2 |
| 艮 | ☶ | `001` | 1 |
| 坤 | ☷ | `000` | 0 |

`TaiChiEvolutionFlow.TRIGRAM_VALUES` 是唯一编码来源。横排阶段和圆阵阶段必须共同使用该数组，禁止分别维护两套编码。

## 10. 阶段六：八卦归位

实现文件：`TaiChiBaguaFlow.gd`

五层完全生成后，八个横排卦象移动成圆阵。

### 无缝交接

1. `TaiChi.gd` 调用 `evolution.draw(..., false)`，停止由 Evolution 绘制八卦行。
2. Bagua Flow 在完全相同的源坐标绘制同一组卦象。
3. 初始尺寸、线距、透明度和文字位置与横排阶段一致。
4. 因此画面中没有“旧图消失、新图出现”的一帧跳变。

### 卦象移动

1. 八个卦象仍按横排从左到右依次启动。
2. 每个卦象从原横排位置直接移动。
3. 中途加入向上的浅弧线，使轨迹更自然。
4. 卦象移动时同步旋转为径向方向。
5. 卦线宽度、线距和整体尺寸逐渐放大。
6. 卦名和图案使用同一轨迹同步移动。

### 最终方位

- 上：乾
- 左上：兑
- 左：离
- 左下：震
- 右上：巽
- 右：坎
- 右下：艮
- 下：坤

这些方位由 `TARGET_ANGLES` 定义。

## 11. 太极进入圆心

太极不淡出，也不创建替代图片。

### 步骤

1. 使用 Evolution 阶段最终的太极坐标作为起点。
2. `taiji_progress()` 独立控制太极移动时间。
3. 太极缓慢移动到 `canvas_size * 0.5`。
4. 移动过程中半径逐渐增加到短边的约 `15.5%`。
5. Shader 始终使用同一个 `FillLayer`，所以黑白图案连续稳定。

## 12. 圆阵框架

当卦象接近最终位置后，`frame_progress()` 开始绘制圆阵：

1. 从正上方顺时针绘制第一条外圆。
2. 绘制第二条较淡的外圆。
3. 绘制包围中央太极的内圆。
4. 沿外圆依次生成 64 个刻度。
5. 每隔 8 个刻度使用较长线段，标记八卦主方位。

圆环和刻度使用低 Alpha 主题色，不能压过中央太极和八个卦象。

## 13. 主题色与透明度

禁止直接使用不透明主题色绘制大面积元素。

推荐形式：

```gdscript
ThemeColor.alpha_theme_color(alpha)
```

主要透明度范围：

- 卦线：约 `0.32–0.58`，取决于阶段和强调程度。
- 单元格边框：约 `0.24`。
- 亮格填充：约 `0.07`。
- 拖尾：最高约 `0.055`。
- 圆环：约 `0.09–0.16`。
- 刻度：最高约 `0.20`。

主题色变化时，`TaiChi.on_theme_changed()` 会更新 Shader 参数并触发重绘。

## 14. 绘制层级

`TaiChi.gd` 中的主要绘制层：

1. `LineAura`：`z_index = -2`，开场和两仪阶段光效。
2. `FillLayer`：`z_index = -1`，Shader 太极填充。
3. `_draw()`：构造线、层级结构、卦象、圆环和文字。

进入太极成形阶段后，LineAura 隐藏。FillLayer 从成形阶段一直复用到最终圆阵。

## 15. 响应式规则

- 太极尺寸基于窗口短边计算。
- 层级 Y 坐标按窗口高度比例分布。
- 内容区按窗口宽度比例计算。
- 字号使用窗口高度比例，并通过 `clampi()` 限制最小和最大值。
- 圆阵半径使用窗口短边的约 `34%`。
- 小窗口下仍需保证太极、文字和圆环不互相覆盖。

## 16. 测试要求

测试场景：

```text
res://agent/test/visual/tai_chi_unit/TaiChiTest.tscn
```

关键断言包括：

- 各 Flow 能正确开始、推进和结束。
- 五层必须按从下到上的顺序启动。
- 飞行图案初始位置位于画面外，结束位置等于目标位置。
- 横排八卦编码必须为 `[7, 6, 5, 4, 3, 2, 1, 0]`。
- Bagua 阶段必须保持从左到右的启动顺序。
- 最终太极中心必须等于画布中心。
- 最终太极半径必须大于五层结构中的小太极半径。
- Shader 图层必须存在，并使用正确的透明主题色。

修改动画后至少执行：

```powershell
godot --headless --path . res://agent/test/visual/tai_chi_unit/TaiChiTest.tscn
```

新增脚本或修改复杂绘制函数时，还应显式检查脚本解析：

```powershell
godot --headless --path . --check-only --script res://agent/ui/visuals/tai_chi/TaiChiEvolutionFlow.gd
godot --headless --path . --check-only --script res://agent/ui/visuals/tai_chi/TaiChiBaguaFlow.gd
```

## 17. 后续修改原则

1. 优先延续已有图形，不用淡出后重新创建的方式模拟移动。
2. 修改卦象编码时只改 `TRIGRAM_VALUES`。
3. 修改层级位置时同时检查太极与“两仪”中心对齐。
4. 修改八卦源位置时确保 Bagua Flow 与 Evolution Flow 使用相同坐标公式。
5. 增加主题色强度时优先调整 Alpha，不要改为不透明颜色。
6. 修改阶段时长后，检查快速 Agent 任务结束时是否仍有足够播放时间。
7. 所有新增函数遵循项目 GDScript 规范：显式返回类型，且无显式 `return` 的命名函数以 `pass` 结束。