MindIE-SD 代码格式规范

本 skill 汇总 MindIE-SD 项目的 Python 代码格式与 lint 规则，适用于代码格式化、lint 修复和代码审查。

事实来源（取值只认 §0/§1 的记录，不要从历史描述或直觉推断）：

• pre-commit/pyproject.toml —— 门禁实际读取的那一份（.pre-commit-config.yaml 用 --config / --rcfile 指定）
• .pre-commit-config.yaml —— 21 个钩子条目（其中 markdownlint 出现 2 次，见别名）
• 根 pyproject.toml —— 不是 pre-commit 用的那份；IDE / 手动 ruff 可能读它，取值不同（见 §0）
• mindiesd/compilation/ 目录下既有代码风格
• 规则正文与示例：references/gate-check-rules.md（单点，本文件只留摘要）

---

0. 先确认门禁读哪一份配置（真实陷阱）

同一条规则在两份文件里取值不同，门禁按左边一列判；右边一列只在本地 IDE / 手动 ruff 时生效：

配置项	门禁生效值（pre-commit/pyproject.toml）	根 pyproject.toml	后果
line-length	120	100	本地按根配置跑 ruff 会在 100 列报 E501，CI 门禁不报（§3.4）
format.quote-style	"preserve"（formatter 不改引号）	未设置 → ruff 默认 double	本地会把单引号统一成双引号 → 无关 diff（§3.6）
format.docstring-code-format	未设置 → disabled	true	本地会格式化 docstring 内代码块，门禁不会
[tool.ruff.lint] select	未声明 → ruff 默认规则集（E4/E7/E9 + F）+ extend-select 的 D209/SIM115（实测 enabled 共 61 条）	E,F,I,N,W,UP,B,C4,SIM,G	I/N/UP/B/C4/G/W/E501/E302 门禁侧均未启用（§1.1、§3.2、§3.5、§3.8）
[tool.ruff.lint] ignore	未声明	B007/B905/E731/F403/F405/UP009/UP032	这些规则门禁侧本就没启用，差异无实际影响
[tool.ruff.lint.per-file-ignores]	"tests/**/*" = ["F401","I","E402"]	mindiesd/__init__.py = ["E402","I001"] 等	门禁侧 tests/ 不报 F401；mindiesd/__init__.py 的例外在门禁侧不生效
exclude	未声明 → ruff 内置默认排除（含 dist、.venv，不含 build）	build、dist	按根配置跑会跳过 build/，门禁侧不跳过（实际以改动文件为输入，影响很小）

自查口径：想复现 CI 门禁用 --config pre-commit/pyproject.toml；想解释"本地 IDE 为什么报错"再用根配置。 两侧取值不必互相迁就：超过 100 列不会让门禁失败，但评审仍按 120 显示列要求排版（§3.4）。

---

1. 配置取值（以门禁实际读取的 pre-commit/pyproject.toml 为准）

1.1 Ruff（ruff-check / ruff-format 都带 --config pre-commit/pyproject.toml）

配置项	生效值	说明
line-length	120	与 pylint max-line-length = 120 同值；由 ruff format 重排可折叠行
target-version	py310	实测 linter.unresolved_target_version = 3.10
format.quote-style	preserve	formatter 保持原引号，不统一
format.docstring-code-format	disabled（未设置）	不格式化 docstring 内代码块
[tool.ruff.lint] extend-select	D209、SIM115	段落末尾空行 / open() 未用 with
select / ignore	未声明	用 ruff 默认规则集，不是根配置那份 E/F/I/N/W/UP/B/C4/SIM/G
per-file-ignores	"tests/**/*" = ["F401","I","E402"]	门禁侧 tests/ 不报未使用导入

实测 enabled 规则集合（61 条）= pycodestyle E4xx/E7xx/E902 + pyflakes Fxxx + D209 + SIM115： 不含 I（isort）、N（命名）、UP（pyupgrade）、B、C4、G、W，也不含 E501。

1.2 pylint（--rcfile=pre-commit/pyproject.toml）

门禁是否拦下某条消息，以 disable 列表为准：列在其中的不会导致失败。

• enable 显式列出：E0100、E0601、E0602、E0603、E0611、E0632（原配置重复列了一次）、E1101、E1120、W0632、W1514
• disable 含（与本 skill 相关的关键项）：protected-access、raise-missing-from、 too-many-arguments、too-many-positional-arguments、too-many-branches、too-many-statements、 too-many-locals、too-many-return-statements、invalid-name、missing-docstring 系列、 line-too-long、broad-except、bare-except、duplicate-code、unused-import/unused-variable/unused-argument
• 阈值（多数因对应消息被 disable 而不产生失败）：max-line-length = 120、max-args = 15、 max-branches = 50、max-statements = 200、max-locals = 50、max-positional-arguments = 20
• 除 disable 覆盖掉的消息外，pylint 其余默认消息中未被 disable 的仍会报（复核见 §5）

1.3 bandit（--config=pre-commit/pyproject.toml）

• severity_level = LOW、confidence_level = LOW → 门限很低，LOW 级问题也报
• tests 含 B110（try/except/pass）、B607（子进程不完整路径）等，两条都不在 skips 内 → 门禁项
• exclude_dirs 含 tests/test/venv/build/dist 等

---

2. Pre-commit 钩子（共 21 个条目；默认 stage 跑 20 个，markdownlint-manual 为 manual 档）

来自 .pre-commit-config.yaml（default_stages: [pre-commit]）：

钩子	行为	备注
trailing-whitespace	删除行尾空白字符
end-of-file-fixer	文件末尾补换行符
check-yaml	YAML 检查（--allow-multiple-documents）
check-added-large-files	拦截超大文件
check-merge-conflict	检测未解决的合并冲突标记
detect-private-key	检测硬编码密钥
check-json	JSON 格式检查
ruff-check	ruff check --config pre-commit/pyproject.toml --output-format github --fix（仅 *.py）	Python lint
ruff-format	ruff format --config pre-commit/pyproject.toml（仅 *.py）	Python 格式化
codespell	拼写检查，--skip *.toml,*.py,*.cpp,*.hpp,*.c,*.h	跳过代码文件
pylint	--rcfile=pre-commit/pyproject.toml（仅 *.py）	见 §1.2
bandit	--config=pre-commit/pyproject.toml --quiet（仅 *.py）	见 §1.3
typos	--force-exclude --config pre-commit/typos.toml	标识符拼写
markdownlint（两个同 id 钩子，见下）	-c .markdownlint.json；markdownlint-manual＝exclude: ^\.agents/ + stages: [manual]；markdownlint-agents＝files: ^\.agents/.*\.md$ 且未覆盖 stages ⇒ 默认档会跑	.agents/** 默认强制（否则改不动）；其余 .md 默认不跑，需显式 --hook-stage manual（§4）；详见 markdown-lint skill
clang-format	--style=file --verbose -i，files: \.(c|h|cpp|hpp|cc|hh|cxx|hxx)$	C++
clang-tidy	repo: local，files: ^csrc/.*\.(cpp|cc|cxx|c)$（排除 csrc/ops/）	依赖宿主机已装 clang-tidy
gitleaks-offline-scan	repo: local，entry: ./gitleaks（本地离线二进制）	密钥扫描

不存在 no-commit-to-branch（本仓不禁止直接提交到 main/master）。 markdownlint 有两个钩子：markdownlint-agents（.agents/**/*.md，走默认 stage，提交/CI 会跑） 与 markdownlint-manual（其余 .md，stages: [manual]）。所以「本地 pre-commit run --all-files 通过 不等于 Markdown 合规」这句话只对 .agents/ 之外的 .md 成立（.agents/** 已被默认档覆盖）； clang-tidy/gitleaks-offline-scan 是 local 钩子，缺少对应二进制时会失败。

---

3. 代码风格约定

3.1 文件头（评审约定）

所有 .py 文件包含：

#!/usr/bin/env python
# coding=utf-8
# Copyright (c) Huawei Technologies Co., Ltd. 2024-2026. All rights reserved.
# MindIE is licensed under Mulan PSL v2.
# You can use this software according to the terms and conditions of the Mulan PSL v2.
# You may obtain a copy of Mulan PSL v2 at:
#          http://license.coscl.org.cn/MulanPSL2
# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND,
# EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT,
# MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE.
# See the Mulan PSL v2 for more details.

门禁侧无"文件头"钩子（detect-private-key/codespell/typos 不检查版权头），本条按评审约定执行。 注意 # coding=utf-8 被 ruff UP009 允许（且门禁侧 UP 组未启用），不要为了"现代化"删掉它。

3.2 导入顺序（评审约定）

顺序要求：标准库（如 contextlib, dataclasses, logging, typing）→ 第三方库（如 torch）→ 本地模块（如 from .compiliation_config import ...），组内按字母序。

门禁侧未启用 I（isort）：ruff check --config pre-commit/pyproject.toml 不会报 I001； 根 pyproject.toml 的 select 含 I，本地按根配置跑才会报。因此两侧都不要求为对方重排既有导入块 （重排会制造无关 diff，§3.10）。

3.3 空白行

• 模块级函数/类定义前 2 个空行、类内方法前 1 个空行：评审约定（门禁侧 E302/E303 未启用）， 由 ruff format 归整
• 过多空白行由 ruff format 处理，不要手工去改未修改行（§3.10）

3.4 行长度（门禁取值 120；不要再用 100 判门禁）

• 门禁取值 line-length = 120（pre-commit/pyproject.toml，ruff 与 pylint max-line-length 同值）。 ruff format 会把可折叠的代码行重排到 120 以内；中文长行、长字符串 formatter 无法折行， 需要人工排版。
• 门禁侧 E501 未启用（select 未声明，enabled 集合里没有 line-too-long）。 实测（2026-09，本地 ruff 0.15.12 + 本仓配置）：同一文件含 102 显示列的中文注释行， ruff check --config pre-commit/pyproject.toml → All checks passed!。
• 只有在根 pyproject.toml / 本地 IDE 下才会报 E501，且那里阈值是 line-length = 100、 按显示列宽计（CJK/全角按 2 列）。同一实测：注释符 # 加 1 个空格再跟 50 个汉字 = 102 列 → E501 Line too long (102 > 100)；跟 49 个汉字 = 100 列 → 通过。 这就是"本地报错、CI 不报"的成因，不要把本地 100 列报错当成门禁结论。
• 评审口径：按 120 显示列排版（中文注释约 60 个汉字即到上限，还要留出缩进与行首注释符的余量）； 按"字符数"估长度会把超限行误判为合规。
• 把中文串写成相邻字面量（"…前半" "后半…"）只要仍在同一行，该行列宽不减； 必须把相邻字面量分到不同行（隐式拼接）才真正降宽。
• 读报错：E501 Line too long (102 > 100) 括号里的数字是检测值（显示列宽）， file:line:col 的 col 是字符位置——中文行两者不一致，回查时按显示列算。

3.5 命名规范（评审约定）

snake_case（函数/变量）、CamelCase（类）、_ 前缀（私有成员）、UPPER_CASE（常量）： 门禁侧 N（pep8-naming）未启用，pylint 的 invalid-name 也在 disable 内，不会让门禁失败。

3.6 引号（quote-style = "preserve"）

formatter 不统一引号：门禁读取的 pre-commit/pyproject.toml 里 format.quote-style = "preserve"， ruff format 保持文件既有引号。不要为了"统一双引号"去改未修改行——改引号风格会制造无关 diff（§3.10）。 （根 pyproject.toml 未设置该项 → 本地按根配置跑 formatter 会向双引号统一，这就是本地/门禁差异。）

3.7 类型注解（评审约定）

• 目标 Python 3.10（target-version = "py310"），可使用 X | Y 联合语法（PEP 604）
• 函数签名建议包含参数和返回值类型注解
• 前向引用使用字符串注解（如 "torch.npu.NPUGraph"）

3.8 日志（评审约定）

使用标准 logging 模块：

logger = logging.getLogger(__name__)
logger.debug("...")
logger.warning("...")

避免在日志字符串中使用 .format() 或 f-string，优先使用 % 风格参数（logging 延迟求值）。 门禁侧 G（flake8-logging-format）未启用，本条按评审约定执行。

3.9 门禁专项规则摘要（正文在 references/gate-check-rules.md）

条目	门禁强制？	说明
except …: pass	是（bandit B110）	见 §5 复核
子进程裸命令名	是（bandit B607，仅覆盖该类场景）	见 §5 复核
open() 未用 with / 段落末尾空行	是（ruff SIM115 / D209）	extend-select
受保护成员访问（protected-access）	否（pylint 已 disable）	评审约定，给出判定命令
异常转译 raise … from（raise-missing-from）	否（pylint 已 disable）	评审约定，给出判定命令
函数参数 ≤5	否（max-args = 15 且 too-many-arguments 已 disable）	评审约定，不由 pre-commit 强制
禁止 __import__（avoid-import-method）	否（无对应钩子；与 UP015 无关）	历史记录·未能复核，按评审约定
禁止非入口 sys.exit() / 方法排序 / 重复字符串	否（无对应钩子）	历史记录·未能复核，按评审约定

规则号纠正：Ruff UP015 的真实语义是 redundant-open-modes（open(f, "r") → open(f)）， 不是 __import__ → importlib.import_module；本仓门禁侧 UP 组也未启用。 __import__ 相关规范属评审约定，不要引用规则号来"强制"它。

3.10 禁止格式化未修改代码行

修改现有文件时，绝对禁止对未涉及功能变更的代码行做任何格式化调整：

• 禁止 ruff format 批量格式化整个文件
• 禁止改变未修改行的引号风格（如 ' → "）
• 禁止调整未修改行的空行数量
• 禁止将单行表达式折叠为多行（如 @unittest.skipIf、raise 语句）
• 禁止改变已有变量命名（如 B,S,N,D → b,s,n,d）
• 禁止改变已有导入别名（如 import torch.nn.functional as F 保持不变）
• 禁止删除已有的注释（如行尾 # FLux.1-dev）
• 禁止保留注释掉的代码行（comment-out-code 检测）。已废弃的代码行应直接删除，不应以注释形式保留
• 描述性注释（自然语言说明）与注释掉代码的区别：前者是 # Step 1: do X，后者是 # old_func(arg)

原因：这些无关 diff 增加 review 负担、引入合并冲突风险，且不改善功能。

仅允许：在需要新增代码的行上使用与周围代码一致的风格。

• 仅对被改动的行运行 ruff check --fix 修复 lint 问题
• 优先使用精确 edit 替换而非整文件 rewrite

3.11 禁止无意义的自动修复重命名

ruff check --fix 的自动修复可能引发不必要的重命名，必须人工审查：

• 禁止改变已有变量名（如 B,S,N,D → b,s,n,d）（N806）
• 禁止改变已有导入别名（如 import torch.nn.functional as F → as nn_functional）（N812）
• 如果 lint 规则与现有代码风格冲突，优先保持现有风格，而非修改代码
• ruff check --fix 的输出 diff 必须逐行审查，不自动放行

上两条引用的 N806/N812 属 N 组：门禁侧未启用（§1.1），风险来自本地按根配置跑 --fix。

---

4. 最小格式化与自查命令

# 按门禁配置格式化 / lint 单个文件（目标文件路径按需替换）
ruff format --config pre-commit/pyproject.toml mindiesd/compilation/target_file.py
ruff check --config pre-commit/pyproject.toml --fix mindiesd/compilation/target_file.py

# 门禁等价：默认 stage（含 markdownlint-agents，覆盖 .agents/**/*.md）
pre-commit run --all-files
pre-commit run --files mindiesd/compilation/target_file.py

# Markdown 全仓（markdownlint-manual 是 stages: [manual]，必须显式指定 hook stage）
pre-commit run --all-files --hook-stage manual
pre-commit run markdownlint-manual --hook-stage manual --files docs/zh/README.md

适用范围（容易误判的三点）：

• pre-commit run --all-files 只跑默认 stage 的钩子：markdownlint-agents（.agents/**/*.md） 在其中，markdownlint-manual（其余 .md）不在其中，后者需按上面的 --hook-stage manual 单独跑
• --all-files 只覆盖 git 跟踪的文件：新建但未 git add 的文件不在扫描范围内
• clang-tidy / gitleaks-offline-scan 是 repo: local 钩子，依赖宿主机存在对应二进制

---

5. 复核：如何判定本技能记录仍然成立（仓规强制）

依据 .agents/README.md「必写复核方法（强制）」：每条问题/陷阱都要写清"如何判定它仍存在"， 先复核、再套用；升级软件栈后逐条复核，不再复现的条目必须删除。 本 skill 的取值全部来自两份配置文件，升级 ruff / pylint / bandit / 改动 pre-commit 配置后必须重跑本节。

命令在仓库根执行（POSIX；Windows 无 grep 时用 Select-String 等价替代）。 多条模式一律写成多个 -e，避免管道符与表格语法冲突：

要复核什么	命令	期望
行长 / 引号 / pylint 阈值	grep -n -e line-length -e quote-style -e max-line-length -e max-args pre-commit/pyproject.toml	line-length = 120、max-line-length = 120、max-args = 15、quote-style = "preserve"
某条 pylint 消息是否仍被禁用	grep -n -e protected-access -e raise-missing-from -e too-many-arguments pre-commit/pyproject.toml	命中位于 disable = [...] 内 → 仍不作为门禁失败项；若挪进 enable → 必须删除 §3.9 对应行与 gate-check-rules.md 对应档位
ruff 实际生效取值与规则集	ruff check --config pre-commit/pyproject.toml --show-settings mindiesd/__init__.py 后接 grep -e "Settings path" -e "^linter.line_length" -e "^formatter.quote_style" -e "^formatter.docstring_code_format"	Settings path 指向 pre-commit/pyproject.toml；linter.line_length = 120；quote_style = preserve；docstring_code_format = disabled
门禁侧是否仍不启用 E501	同上 --show-settings 输出接 grep -c "line-too-long (E501)"	输出 0（enabled 列表里没有它）→ §3.4 结论成立
钩子清单与 manual stage	grep -n -e "^- id:" -e "stages:" .pre-commit-config.yaml，再跑 pre-commit validate-config .pre-commit-config.yaml	21 个 id 条目（markdownlint 出现 2 次：manual / agents）；默认 stage 20 个，manual 档 1 个；无 no-commit-to-branch；配置校验退出码 0
两份配置是否仍不同	grep -n -e line-length -e quote-style -e "^select" -e "^ignore" pyproject.toml pre-commit/pyproject.toml	有差异属预期（100 vs 120、select 有无）；若某天合并成一份，§0 的差异表要重写
门禁专项规则是否仍无强制来源	grep -n -e avoid-import-method -e avoid-using-exit -e function-order -e duplicate-string .pre-commit-config.yaml pre-commit/pyproject.toml	无命中（退出码 1）→ gate-check-rules.md 的"历史记录·未能复核"档位仍正确
bandit 是否仍拦 except: pass / 裸命令名	grep -n -e B110 -e B607 -e skips pre-commit/pyproject.toml	B110、B607 在 tests 内且不在 skips 内

维护纪律：复核后

1. 取值变了（如 line-length 改动）→ 同步 SKILL.md §0/§1/§3.4 与 gate-check-rules.md；
2. 某条不再复现（如 pylint 重新启用 protected-access）→ 删除对应条目或改写档位，不留"以防万一"；
3. 新增条目必须同时给出复核命令，否则不予回填（仓规）。

---

6. 跨文件一致性

Markdown 文件的格式规范由独立的 markdown-lint skill 承接，本 skill 仅覆盖 Python 代码格式。

修改代码时注意与其他编译模块保持一致，参考文件：

• mindiesd/compilation/aclgraph_backend.py
• mindiesd/compilation/mindie_sd_backend.py
• mindiesd/compilation/compiliation_config.py
• mindiesd/compilation/_custom_decomposition.py

Reference Files

• 📋 references/gate-check-rules.md — 加载时机: 需要门禁专项规则的正文/示例、或要判断某条规则是否真由 pre-commit 强制时（本文件 §3.9 只留摘要）

维护与更新

当 ruff / pylint / bandit 版本升级、pre-commit/pyproject.toml 或 .pre-commit-config.yaml 取值变更、 新 lint 规则启用或发现新的代码风格约定时：先按 §5 复核，再更新 §0/§1 与 references/gate-check-rules.md（单点），最后按 dev-workflow 的复盘流程登记。