From a15e7c2dc1870bfb2a2500a86293c2badd9bc74d Mon Sep 17 00:00:00 2001
From: HomeAgent Agent <agent@homeagent.local>
Date: Sun, 13 Sep 2026 21:59:10 +0800
Subject: [PATCH] =?UTF-8?q?chore(lint):=20=E5=8A=A0=20.golangci.yml?=
 =?UTF-8?q?=EF=BC=88funlen/gocyclo/lll/dupl=EF=BC=8Cwarn-only=EF=BC=89+=20?=
 =?UTF-8?q?make=20lint-full?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

main 上曾有 4 个 >=300 行函数、12 个 >=200 行函数；没有复杂度 linter 是它们
长期存活的直接原因。先以 warn-only（issues.exit-code:0）立阈值、只出清单，
历史债下降后再收成硬门禁。测试与 testdata/third_party 排除长度类规则。
---
 .golangci.yml | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 Makefile      | 11 +++++++++++
 2 files changed, 57 insertions(+)
 create mode 100644 .golangci.yml

diff --git a/.golangci.yml b/.golangci.yml
new file mode 100644
index 0000000..1d52531
--- /dev/null
+++ b/.golangci.yml
@@ -0,0 +1,46 @@
+# golangci-lint 配置 —— 「超大函数/超大文件」治理的防复发闸门。
+#
+# 背景：main 上曾有 4 个 ≥300 行函数、12 个 ≥200 行函数（见审查报告）。
+# 没有复杂度 linter 是它们能长期存活的直接原因。本配置先以 **warn-only**
+# 起步：`issues.exit-code: 0`，只产出清单、不阻断构建。等历史债降到可接受
+# 水位后，再把 exit-code 改成 1 收成硬门禁。
+#
+# 运行：make lint-full（需先 `go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest`）
+# 注意：这是 golangci-lint v1 的配置格式（v2 的 `linters.default` 写法不同）。
+run:
+  timeout: 5m
+  tests: true
+
+linters:
+  disable-all: true
+  enable:
+    - funlen   # 函数长度
+    - gocyclo  # 圈复杂度
+    - lll      # 行宽
+    - dupl     # 重复代码
+    - govet    # 与 make lint 对齐的基线
+
+linters-settings:
+  funlen:
+    lines: 150
+    statements: 100
+  gocyclo:
+    min-complexity: 30
+  lll:
+    line-length: 140
+  dupl:
+    threshold: 200
+
+issues:
+  # 起步阶段不阻断（warn-only）。收紧后改为 1。
+  exit-code: 0
+  max-issues-per-linter: 0
+  max-same-issues: 0
+  exclude-rules:
+    # 测试与生成/夹具代码不受长度类规则约束。
+    - path: _test\.go
+      linters: [funlen, dupl, gocyclo]
+    - path: internal/plugin/proc/testdata
+      linters: [funlen, dupl]
+    - path: third_party/
+      linters: [funlen, dupl, gocyclo, lll]
diff --git a/Makefile b/Makefile
index 5d4af9a..0b71eb1 100644
--- a/Makefile
+++ b/Makefile
@@ -61,3 +61,14 @@ fmt:
 
 lint:
 	$(GO) vet ./...
+
+# lint-full：在 vet 之外跑 golangci-lint（阈值见 .golangci.yml，起步 warn-only）。
+# 未安装时给出可执行的安装提示与跳过原因，而不是静默成功。
+.PHONY: lint-full
+lint-full:
+	@if command -v golangci-lint >/dev/null 2>&1; then \
+		golangci-lint run; \
+	else \
+		echo "golangci-lint 未安装，跳过（阈值见 .golangci.yml）"; \
+		echo "  go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest"; \
+	fi