orchestration-workflow

编排工作流

优化周期

1. ANALYZE    -> Read devlog overview + current best results
2. PROFILE    -> Launch Profiler Agent -> get compact bottleneck analysis
3. SELECT     -> Choose implementation language based on the required control level
4. STRATEGIZE -> Load the shared optimization guidance plus the language-specific optimization catalog
5. DESIGN     -> Launch Kernel Designer Agent -> implement optimizations in new version
6. VERIFY     -> Launch Profiler Agent on new version -> compare with previous
7. EVALUATE   -> Target met? -> Done. Not met? -> Back to step 3
8. LEARN      -> If novel insight: update knowledge base (mandatory)

当性能分析或实现迭代揭示了可复用模式、适用条件得到完善，或先前假设被证伪时，必须执行 LEARN 步骤。

---

默认配置

推测解码

b=32, s=16, t=4096 -- 如果出现 OOM，则减小 b。

探索性调优的默认试验矩阵

• 类似解码：b=32, s=1, t=4096
• 类似推测解码：b=32, s=16, t=4096
• 仅当某项策略或开发日志证据表明前两个点不足时，才添加第三个压力配置。

调优空间探索

• 从测试一个预期表现良好的手动调优分块配置开始
• 探索一些分块配置，了解性能如何随分块大小变化
• 如果情况复杂，可考虑进行粗粒度自动调优以寻找良好配置，但要注意组合爆炸（利用领域知识缩减搜索空间）。自动调优耗时应足够短，以保持内核设计探索的速度（例如，每个内核版本少于 1 小时）
• 如果某个内核版本展现出显著潜力，可考虑进行更细粒度的自动调优以进一步优化性能；否则，进入下一轮优化迭代（不要在前景不足的内核版本上花费过多时间进行自动调优）

例如，mla_var6_plus_v3 就是一个反面案例，它有 10'000 个自动调优配置，但相比 mla_var6_plus_v2 并未带来显著提升。内核设计比自动调优更重要。

---

子 Agent 启动模板

Agent 定义位于 .claude/agents/。通过名称和任务提示词启动 Agent。

性能分析器

使用任务提示词启动 profiler Agent：

Profile <kernel> <version> at b=X, s=X, t=X.
Return compact summary per the output contract.
Update the devlog performance section in docs/kernels/<kernel>.md.

性能分析器已通过其 Agent 定义预加载 /profile-kernel。

内核设计师

使用任务提示词启动 kernel-designer Agent：

Create <kernel> <new_version> from <current_version>.
Language: <cutile-dsl|cute-dsl>.
Load /design-<language>-kernel and the matching reference skill if one exists.
Apply optimizations: [specific list with rationale].
Return implementation summary per the output contract.

内核设计师已预加载 /design-kernel。仍须按需加载特定语言的技能，因为语言取决于编排器的选择。

---

Agent 通信约定

性能分析器 -> 编排器（精简输出）

## Profile: [kernel] [version] | b=X, s=X, t=X
### Stages
| Stage | Duration | TC% | DRAM% | Occ% | Bottleneck | Key Issue |
### Bottleneck: [Memory/Compute/Latency]-bound
Root cause: [2 sentences]
### Top 3 Opportunities (ranked by estimated impact)
1. [name] -- est. X% gain -- trigger: [metric=value]

### vs Baseline (if applicable)
| Metric | Previous | Current | Change |
|--------|----------|---------|--------|

编排器 -> 设计师（指示）

## Optimization Task: [kernel] [current] -> [new_version]
### Current Bottleneck: [from profiler]
### Optimizations to Apply:
1. [specific optimization + rationale + link to the shared or language-specific knowledge file]

### Constraints
- register budget, target occupancy, required control level, and language-specific constraints

设计师 -> 编排器（摘要）

## New Version: [kernel] [version]
### Changes Applied: [list]
### Files: Created/Modified [paths]
### Correctness: [PASS/FAIL]

### Trial Configurations Checked
1. [b, s, t] -- [why this point matters]

### Devlog Entry Written: [path]

---

知识库更新流程

更新时机

• 对内核进行性能分析后，如果发现目录中尚未收录的相关优化或反模式
• 对内核进行性能分析后，如果现有优化或反模式被证伪，需要更新其有效条件，或酌情将其改为反模式或优化
• 新的性能证据完善了某项优化的预估影响，或某项反模式的失效模式
• 发现优化之间的新交互
• 设备特定结果可以抽象为可复用规则时

已验证的新优化

1. 判断发现属于共享的算法／硬件知识，还是特定语言的实现知识。
2. 共享知识放在 docs/knowledge/optimizations/<name>.md 下。
3. 特定语言的知识放在 docs/knowledge/languages/<language>/optimizations/<name>.md 下。
4. 在 /optimization-catalog 技能的优化索引中添加相应条目。
5. 记录可复用模式、适用情境和主要受影响的指标。
6. 明确区分本地证据与普遍化结论。

优化导致明显回归

1. 判断故障模式是通用的还是特定于某种语言的。
2. 通用反模式放在 docs/knowledge/anti-patterns/<name>.md。
3. 特定于某种语言的反模式放在 docs/knowledge/languages/<language>/anti-patterns/<name>.md。
4. 在 /optimization-catalog 技能的反模式索引中添加对应条目。
5. 用可复用的方式记录故障模式，而不只是记录出现故障的内核／版本。
6. 记录哪些指标揭示了问题，以及问题出现的上下文。

详情文件模板

每项优化和反模式都必须明确说明适用的上下文（例如，特定于 MLA、适用于任何在线 softmax 内核，或适用于任何具有特定模式的内核）。上下文应写在 When to Apply 部分。

# [Optimization Name]

## When to Apply
- [Context 1: e.g., specific kernel design or reference layer/kernel]
- [Context 2]
- [Metric condition 1]
- [Metric condition 2]

## Mechanism
[How and why this optimization works]

## Affected Metrics
- [Metric 1: e.g. occupancy]
- [Metric 2: e.g. registers/thread]
- [Metric 3: e.g. Tensor Core utilization, DRAM throughput, L2 hit rate, local-memory traffic]

## Implementation
\`\`\`python
# Code snippet
\`\`\`

## Performance Evidence
Source type: [local experiment / external report]
| Config | Before | After | Change |
|--------|--------|-------|--------|

## Generalization
[Device-agnostic takeaway. Mention architecture/device facts only insofar as they sharpen the reusable rule.]

## Pitfalls
- [Known failure modes]

## Interactions
- [How this interacts with other optimizations]