2026Technology-Competition/docs/superpowers/specs/2026-08-14-sqlfluff-dialect-display-design.md

SQLFluff 方言只读展示 — 设计 Spec

日期：2026-08-14 状态：已审批 关联流程：① 用户提出 → ② 需求澄清 → ③ 方案设计 → ④ 人类审批

1. 背景

侧边栏"设置"面板（codeReviewer.setupView）的 SQLFluff 适配器卡片目前只展示 "创建项目配置 / 修改全局设置"两个按钮，不直接展示 SQL 审查当前生效的方言。 用户希望在卡片内以"内置规则"徽章的同款样式，只读展示当前生效方言。

2. 共识（Stage ② 确认）

• 呈现形式：只读展示，不可在侧边栏直接修改；修改仍需去 VS Code 设置（sqlfluff.dialect）。
• 位置：SQLFluff 卡片徽章行，紧跟"内置规则/项目配置/全局配置"模式徽章之后。
• 样式：徽章配色随方言实际来源变化（显式=蓝/全局配置=黄/项目配置=绿/内置=紫），一眼可辨方言由哪个配置控制。
• 展示内容：当前实际生效方言（非占位文案），按运行时优先级完整解析。
• 解析深度（Stage ② 最终确认）：含全局配置文件解析。

3. 方案

3.1 架构概览

无需架构调整，改动局限在设置面板三件套 + i18n 文案 + 方言解析逻辑集中在 src/adapters/sqlfluff.ts，保证展示值与适配器实际使用完全一致。

数据流（复用现有链路）：

collectAdapterStatus()  ──pushConfig()──>  postMessage(initConfig.adapterStatus)
                                              └─> setupView.js renderAdapters() 渲染方言徽章

设置变更实时刷新：setupView.ts:266-275 已监听 vscode-code-reviewer.sqlfluff 变更并触发 pushConfig()，方言徽章自动跟随更新，无需额外订阅。

3.2 生效方言解析链（与 sqlfluff.ts 运行时行为逐一对齐）

优先级	来源	生效值
1	显式设置 sqlfluff.dialect（受支持集合内）	该值（经 --dialect 覆盖一切）
2	全局 sqlfluff.configFile	解析该文件 [sqlfluff]/[tool.sqlfluff] 段 dialect；无该键则 sqlfluff 默认 ansi
3	项目配置（.sqlfluff/setup.cfg/tox.ini/pep8.ini/pyproject.toml）	同上，解析 dialect，无则 ansi
4	无任何配置 → 插件内置配置	oracle（SQL/PLSQL 兜底方言）

3.3 文件变更清单

文件	变更	说明
src/adapters/sqlfluff.ts	修改	SUPPORTED_DIALECTS 改 export const；hasProjectSqlfluffConfig 重构为 findProjectSqlFluffConfig()（返回文件路径）；新增 readDialectFromConfigFile()；resolveSqlFluffDialect() 返回 { dialect, source }（source: explicit/global/project/builtin）
src/views/setupView.ts	修改	引入 resolveSqlFluffDialect；AdapterConfigStatus 加 sqlfluffDialect?: string 与 sqlfluffDialectSource?；collectAdapterStatus() 填充；pushConfig() i18n 加 label；新增 .adapter-badge-explicit 蓝色徽章样式
src/views/setupView.js	修改	renderAdapters() 对 sqlfluff 在模式徽章后追加方言徽章，按 sqlfluffDialectSource 映射徽章 class（explicit→蓝/global→warn/ project→ok/builtin→info）
src/i18n/messages.ts	修改	新增 setup.adapter.sqlfluffDialectLabel 三语文案

无新建、无删除。

3.3.1 方言徽章配色映射

source	含义	徽章 class	颜色
explicit	显式设置 sqlfluff.dialect	adapter-badge-explicit	蓝 #388bfd
global	全局 sqlfluff.configFile	adapter-badge-warn	黄 #d29922
project	项目 .sqlfluff 等	adapter-badge-ok	绿 #3fb950
builtin	插件内置默认	adapter-badge-info	紫 #8b5cf6

3.4 关键实现

sqlfluff.ts

export const SUPPORTED_DIALECTS = [ 'ansi', ..., 'vertica' ];

function findProjectSqlFluffConfig(workspaceRoot: string): string | undefined {
  // 由 hasProjectSqlfluffConfig 重构：返回实际命中的文件路径
}

function readDialectFromConfigFile(filePath: string): string | undefined {
  // 行扫描 [sqlfluff] / [tool.sqlfluff] 段内 dialect = X 或 dialect = "X"
}

export type SqlFluffDialectSource = 'explicit' | 'global' | 'project' | 'builtin';
export interface SqlFluffDialectInfo { dialect: string; source: SqlFluffDialectSource; }

export function resolveSqlFluffDialect(workspaceRoot: string): SqlFluffDialectInfo {
  const explicit = getSqlFluffDialect();
  if (explicit && SUPPORTED_DIALECTS.includes(explicit)) {
    return { dialect: explicit, source: 'explicit' };
  }
  const globalCfg = getSqlFluffConfigFile();
  if (globalCfg && globalCfg.trim() !== '') {
    return { dialect: readDialectFromConfigFile(globalCfg) ?? 'ansi', source: 'global' };
  }
  const projectFile = findProjectSqlFluffConfig(workspaceRoot);
  if (projectFile) {
    return { dialect: readDialectFromConfigFile(projectFile) ?? 'ansi', source: 'project' };
  }
  return { dialect: 'oracle', source: 'builtin' };
}

setupView.ts

import { resolveSqlFluffDialect, type SqlFluffDialectSource } from '../adapters/sqlfluff';

interface AdapterConfigStatus {
  // ...原有字段
  sqlfluffDialect?: string;   // 仅 sqlfluff 生效
  sqlfluffDialectSource?: SqlFluffDialectSource;
}

// collectAdapterStatus() sqlfluff 分支：
const dialectInfo = id === 'sqlfluff'
  ? resolveSqlFluffDialect(vscode.workspace.workspaceFolders?.[0]?.uri.fsPath ?? '')
  : undefined;
status.sqlfluffDialect = dialectInfo?.dialect;
status.sqlfluffDialectSource = dialectInfo?.source;

setupView.js renderAdapters()

var dialectBadgeClassMap = {
  explicit: 'adapter-badge-explicit',
  global: 'adapter-badge-warn',
  project: 'adapter-badge-ok',
  builtin: 'adapter-badge-info',
};
var dialectBadgeClass = dialectBadgeClassMap[a.sqlfluffDialectSource] || 'adapter-badge-info';
var dialectBadge = a.id === 'sqlfluff'
  ? '<span class="adapter-badge ' + dialectBadgeClass + '">' +
      escapeHtml(i18n.sqlfluffDialectLabel) + ' ' +
      escapeHtml(a.sqlfluffDialect || '') +
    '</span>'
  : '';

messages.ts 新增 key

key	zh-CN	en	ja
setup.adapter.sqlfluffDialectLabel	方言	Dialect	方言

3.5 影响范围

• 仅设置面板 SQLFluff 卡片的 UI 展示，不影响分析执行逻辑、配置优先级、package.json。
• sqlfluff.dialect 设置值本身不变；src/config/linter.ts 的 getSqlFluffDialect/getSqlFluffConfigFile 被复用。
• 新增对 adapters/sqlfluff 模块的跨层 import（仅常量与纯函数，无副作用）。

3.6 验证方式

1. npm test（lint → compile → test）。
2. 手工四态：显式 postgres / 全局配置文件含方言 / 项目 .sqlfluff 含方言 / 无配置 → 侧边栏 SQLFluff 卡片分别显示"方言 postgres（蓝）" / 对应值（黄） / 对应值（绿） / "方言 oracle（紫）"。

4. 风险

• "无配置默认 oracle"与"有配置文件但无 dialect → ansi"的差异语义：与运行时行为一致， 展示的是真实生效值，属预期。
• SUPPORTED_DIALECTS 与 package.json enum 清单重复维护，本次仅复用代码内既有常量，不新增重复。