# 风格对齐（Style Alignment / 风格嗅探协议）

## 适用场景

二次开发（二开）、插件开发、在**已有代码库**中新增或修改模板/功能文件时**强制启用**。
仅当目标项目确为空白、无任何可参照文件时跳过（回退到兜底约定并标注）。

## 核心原则

生成的代码风格必须与**目标项目已有的实际代码**一致，而不是 Agent 自身的默认风格，也不是本技能内嵌的示例风格。

- 与「基于实码，不凭记忆」一致：风格也来自真实文件，不靠想象。
- 本技能内置的风格约定（cms-development 第七步命名表、Karpathy 原则3「匹配现有风格」）仅作为「项目无参照时的兜底」，不是首选。
- 这正是解决"二开写插件时 Agent 凭想象自由发挥模板样式"的根治手段：把"匹配现有风格"从一句声明变成**强制的取样+提取+对齐**三步动作。

## 执行步骤（生成/修改前强制）

### 1. 取样代表性文件

按目标类型各取 1-2 个**已存在**的文件，优先取**与目标目录/模块相同**的文件（风格最贴近）：

- 模板/前端：一个已有的 `.php` / `.html` 混编模板
- 后台/插件：一个已有的功能文件或后台页面
- 表单片段：一个已有的 `fhtml` / 表单 / 列表片段
- 配置/类：一个已有的 `config.php` / 类定义（看类、函数命名与注释风格）
- 若项目根存在 `.editorconfig` / `phpcs.xml` / `.prettierrc` / `eslintrc`，**优先读之**作为权威基线（高于人工嗅探）

### 2. 提取风格标记（逐项记录）

| 标记 | 取值示例 |
| - | - |
| 缩进 | tab / 2 空格 / 4 空格 |
| 开标签 | `<?php` / `<?` |
| 括号位置 | K&R（同行列 `{`）/ Allman（换行 `{`） |
| 数组键引号 | 加引号 `$a['x']` / 不加 `$a[x]` |
| 引号习惯 | 单引号优先 / 双引号优先 |
| 注释头 | 有无文件头注释块、格式样式 |
| 模板变量命名 | `$navinfor` / `$empire` / `$public_r` 等项目约定 |
| PHP/HTML 混编 | 缩进如何对齐、块间空行如何留 |
| 函数/类命名 | camelCase / PascalCase / 下划线 |
| 全等 | `===` 统一 / 混用 `==` |
| 空行/折行 | 块间空行、链式调用折行习惯 |

### 3. 产出「风格基线」块（生成前必输出）

```
## 风格基线（取自 <文件1>, <文件2>）
- 缩进: 4 空格
- 开标签: <?php
- 括号: K&R
- 数组键: 加引号
- 引号: 单引号优先
- 模板变量: 沿用 $navinfor/$empire 约定
- 全等: 统一 ===
- 混编: PHP 块与 HTML 同级缩进对齐
```

生成的每一行都必须对齐该基线。若基线的某项与**安全红线 / PHP8 兼容**冲突（如数组键不加引号违反 PHP8 兼容），以安全红线为准，并标注偏差原因。

### 4. 兜底

仅当目标项目确为空白、无任何可参照文件时，才回退到 cms-development 第七步内置命名约定，并明确标注「无原项目风格可参照，已用技能默认约定」。

## 与现有流程衔接

- `code-generation.md` 第三步「需求分析 → 加载项目规范」处强制调用本协议。
- `cms-development.md` 第七步「代码风格与质量」改为「先嗅探原项目代表文件 → 再套用」，内置命名表降为兜底。
- `karpathy-coding-guidelines.md` 原则3「匹配现有风格，即使你自己会不同做法」由本协议提供具体提取手段。

## 失败回退

| 场景 | 动作 |
| - | - |
| 取样文件读取失败 / 不存在 | 标注，回退兜底约定，不阻塞生成 |
| 多个样本风格冲突 | 取与目标目录同模块者优先；仍冲突取多数派，标注少数派差异 |
| 项目为空白无参照 | 用兜底约定并标注「无原项目风格可参照」 |