refactor: 精简 package.json scripts，引入 eslint-plugin-prettier 统一格式检查

删除 start/build:web/format:check，简化 check 为 typecheck+lint+test 引入 eslint-plugin-prettier 将 Prettier 集成至 ESLint，统一质量检查入口简化 lint-staged 配置，扩展 clean 清理范围至 dist/
2026-05-12 21:43:20 +08:00
parent 9a71b7967c
commit ad87be6956
9 changed files with 78 additions and 34 deletions
--- a/.lintstagedrc.json
+++ b/.lintstagedrc.json
@@ -1,4 +1,4 @@
 {
-  "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
+  "*.{ts,tsx}": ["eslint --fix"],
  "*.{md,json,yaml,yml}": ["prettier --write"]
 }
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -548,7 +548,7 @@ bun run build

 ```bash
 bun run clean
-# 清理 .build/ 缓存和 *.bun-build 临时文件
+# 清理 dist/ 构建产物、.build/ 缓存和 *.bun-build 临时文件
 ```

 ### 3.4 开发工作流
@@ -640,15 +640,14 @@ bun run test:smoke

 ## 代码质量

-项目使用多层代码质量保障体系：ESLint 类型感知规则 + Perfectionist 导入排序 + Prettier 格式化 + TypeScript 严格模式 + Git hooks 自动化。
+项目使用多层代码质量保障体系：ESLint 类型感知规则 + Perfectionist 导入排序 + Prettier 格式化（通过 eslint-plugin-prettier 集成至 ESLint）+ TypeScript 严格模式 + Git hooks 自动化。

 ```bash
-bun run lint          # ESLint 检查（含类型感知规则、导入排序、导入验证）
-bun run format:check  # Prettier 格式检查
+bun run lint          # ESLint 检查（含类型感知规则、导入排序、导入验证、Prettier 格式）
 bun run format        # Prettier 自动格式化
 bun run typecheck     # TypeScript 类型检查（含 noUnusedLocals、noPropertyAccessFromIndexSignature）
 bun test              # 运行所有测试
-bun run check         # 一键运行 typecheck + lint + format:check + test
+bun run check         # 一键运行 typecheck + lint + test
 ```

 `check` 是日常开发推荐的质量检查命令。
@@ -657,17 +656,18 @@ bun run check         # 一键运行 typecheck + lint + format:check + test

 配置文件：`eslint.config.js`

-| 配置来源                                          | 用途                                               |
-| ------------------------------------------------- | -------------------------------------------------- |
-| `@eslint/js` recommended                          | JavaScript 基础规则                                |
-| `typescript-eslint` recommended-type-checked      | TypeScript 类型感知规则（no-floating-promises 等） |
-| `typescript-eslint` stylistic-type-checked        | TypeScript 风格规则（命名规范、语法选择等）        |
-| `eslint-plugin-perfectionist` recommended-natural | 导入语句和命名导出自动排序                         |
-| `eslint-plugin-import`                            | 导入路径验证、循环依赖检测、重复导入合并           |
+| 配置来源                                                        | 用途                                               |
+| --------------------------------------------------------------- | -------------------------------------------------- |
+| `@eslint/js` recommended                                        | JavaScript 基础规则                                |
+| `typescript-eslint` recommended-type-checked                    | TypeScript 类型感知规则（no-floating-promises 等） |
+| `typescript-eslint` stylistic-type-checked                      | TypeScript 风格规则（命名规范、语法选择等）        |
+| `eslint-plugin-perfectionist` recommended-natural               | 导入语句和命名导出自动排序                         |
+| `eslint-plugin-import`                                          | 导入路径验证、循环依赖检测、重复导入合并           |
+| `eslint-plugin-prettier` recommended + `eslint-config-prettier` | 将 Prettier 格式集成为 ESLint 规则，禁用冲突规则   |

 ### Prettier 配置

-配置文件：`.prettierrc.json`
+配置文件：`.prettierrc.json`，通过 `eslint-plugin-prettier` 集成为 ESLint 规则（`lint` 命令同时检查格式），也可通过 `format` 命令独立运行。

 显式声明所有格式化参数（`printWidth: 120`、`semi: true`、`singleQuote: false`、`trailingComma: "all"`、`endOfLine: "lf"` 等），确保不同开发环境产出完全一致的格式化结果。

@@ -686,10 +686,10 @@ bun run check         # 一键运行 typecheck + lint + format:check + test

 通过 husky 在 commit 阶段自动执行检查：

-| Hook         | 行为                                                           |
-| ------------ | -------------------------------------------------------------- |
-| `pre-commit` | lint-staged 对变更文件运行 `eslint --fix` + `prettier --write` |
-| `commit-msg` | commitlint 校验提交信息格式 `类型: 简短描述`                   |
+| Hook         | 行为                                                                                                           |
+| ------------ | -------------------------------------------------------------------------------------------------------------- |
+| `pre-commit` | lint-staged 对变更文件运行 `eslint --fix`（TS/TSX，含 Prettier 格式修复）或 `prettier --write`（MD/JSON/YAML） |
+| `commit-msg` | commitlint 校验提交信息格式 `类型: 简短描述`                                                                   |

 提交类型限定：`feat`、`fix`、`refactor`、`docs`、`style`、`test`、`chore`。

@@ -698,7 +698,7 @@ bun run check         # 一键运行 typecheck + lint + format:check + test
 ## 测试

 ```bash
-bun run check    # 日常开发（类型检查 + lint + 格式 + 单元测试）
+bun run check    # 日常开发（类型检查 + lint（含格式） + 单元测试）
 bun run verify   # 完整验证（check + 构建 + smoke test）
 ```

--- a/bun.lock
+++ b/bun.lock
@@ -26,9 +26,11 @@
        "@types/react-dom": "^19.2.3",
        "@vitejs/plugin-react": "^6.0.1",
        "eslint": "^10.3.0",
+        "eslint-config-prettier": "^10.1.8",
        "eslint-import-resolver-typescript": "^4.4.4",
        "eslint-plugin-import": "^2.32.0",
        "eslint-plugin-perfectionist": "^5.9.0",
+        "eslint-plugin-prettier": "^5.5.5",
        "eslint-plugin-react-hooks": "^7.1.1",
        "eslint-plugin-react-refresh": "^0.5.2",
        "husky": "^9.1.7",
@@ -157,6 +159,8 @@

    "@oxc-project/types": ["@oxc-project/types@0.128.0", "https://registry.npmmirror.com/@oxc-project/types/-/types-0.128.0.tgz", {}, "sha512-huv1Y/LzBJkBVHt3OlC7u0zHBW9qXf1FdD7sGmc1rXc2P1mTwHssYv7jyGx5KAACSCH+9B3Bhn6Z9luHRvf7pQ=="],

+    "@pkgr/core": ["@pkgr/core@0.2.9", "https://registry.npmmirror.com/@pkgr/core/-/core-0.2.9.tgz", {}, "sha512-QNqXyfVS2wm9hweSYD2O7F0G06uurj9kZ96TRQE5Y9hU7+tgdZwIkbAKc5Ocy1HxEY2kuDQa6cQ1WRs/O5LFKA=="],
+
    "@popperjs/core": ["@popperjs/core@2.11.8", "https://registry.npmmirror.com/@popperjs/core/-/core-2.11.8.tgz", {}, "sha512-P1st0aksCrn9sGZhp8GMYwBnQsbvAWsZAX44oXNNvLHGqAOcoVxmjZiohstwQ7SqKnbR47akdNi+uleWD8+g6A=="],

    "@reduxjs/toolkit": ["@reduxjs/toolkit@2.11.2", "https://registry.npmmirror.com/@reduxjs/toolkit/-/toolkit-2.11.2.tgz", { "dependencies": { "@standard-schema/spec": "^1.0.0", "@standard-schema/utils": "^0.3.0", "immer": "^11.0.0", "redux": "^5.0.1", "redux-thunk": "^3.1.0", "reselect": "^5.1.0" }, "peerDependencies": { "react": "^16.9.0 || ^17.0.0 || ^18 || ^19", "react-redux": "^7.2.1 || ^8.1.3 || ^9.0.0" }, "optionalPeers": ["react", "react-redux"] }, "sha512-Kd6kAHTA6/nUpp8mySPqj3en3dm0tdMIgbttnQ1xFMVpufoj+ADi8pXLBsd4xzTRHQa7t/Jv8W5UnCuW4kuWMQ=="],
@@ -501,6 +505,8 @@

    "eslint": ["eslint@10.3.0", "https://registry.npmmirror.com/eslint/-/eslint-10.3.0.tgz", { "dependencies": { "@eslint-community/eslint-utils": "^4.8.0", "@eslint-community/regexpp": "^4.12.2", "@eslint/config-array": "^0.23.5", "@eslint/config-helpers": "^0.5.5", "@eslint/core": "^1.2.1", "@eslint/plugin-kit": "^0.7.1", "@humanfs/node": "^0.16.6", "@humanwhocodes/module-importer": "^1.0.1", "@humanwhocodes/retry": "^0.4.2", "@types/estree": "^1.0.6", "ajv": "^6.14.0", "cross-spawn": "^7.0.6", "debug": "^4.3.2", "escape-string-regexp": "^4.0.0", "eslint-scope": "^9.1.2", "eslint-visitor-keys": "^5.0.1", "espree": "^11.2.0", "esquery": "^1.7.0", "esutils": "^2.0.2", "fast-deep-equal": "^3.1.3", "file-entry-cache": "^8.0.0", "find-up": "^5.0.0", "glob-parent": "^6.0.2", "ignore": "^5.2.0", "imurmurhash": "^0.1.4", "is-glob": "^4.0.0", "json-stable-stringify-without-jsonify": "^1.0.1", "minimatch": "^10.2.4", "natural-compare": "^1.4.0", "optionator": "^0.9.3" }, "peerDependencies": { "jiti": "*" }, "optionalPeers": ["jiti"], "bin": { "eslint": "bin/eslint.js" } }, "sha512-XbEXaRva5cF0ZQB8w6MluHA0kZZfV2DuCMJ3ozyEOHLwDpZX2Lmm/7Pp0xdJmI0GL1W05VH5VwIFHEm1Vcw2gw=="],

+    "eslint-config-prettier": ["eslint-config-prettier@10.1.8", "https://registry.npmmirror.com/eslint-config-prettier/-/eslint-config-prettier-10.1.8.tgz", { "peerDependencies": { "eslint": ">=7.0.0" }, "bin": { "eslint-config-prettier": "bin/cli.js" } }, "sha512-82GZUjRS0p/jganf6q1rEO25VSoHH0hKPCTrgillPjdI/3bgBhAE1QzHrHTizjpRvy6pGAvKjDJtk2pF9NDq8w=="],
+
    "eslint-import-context": ["eslint-import-context@0.1.9", "https://registry.npmmirror.com/eslint-import-context/-/eslint-import-context-0.1.9.tgz", { "dependencies": { "get-tsconfig": "^4.10.1", "stable-hash-x": "^0.2.0" }, "peerDependencies": { "unrs-resolver": "^1.0.0" }, "optionalPeers": ["unrs-resolver"] }, "sha512-K9Hb+yRaGAGUbwjhFNHvSmmkZs9+zbuoe3kFQ4V1wYjrepUFYM2dZAfNtjbbj3qsPfUfsA68Bx/ICWQMi+C8Eg=="],

    "eslint-import-resolver-node": ["eslint-import-resolver-node@0.3.10", "https://registry.npmmirror.com/eslint-import-resolver-node/-/eslint-import-resolver-node-0.3.10.tgz", { "dependencies": { "debug": "^3.2.7", "is-core-module": "^2.16.1", "resolve": "^2.0.0-next.6" } }, "sha512-tRrKqFyCaKict5hOd244sL6EQFNycnMQnBe+j8uqGNXYzsImGbGUU4ibtoaBmv5FLwJwcFJNeg1GeVjQfbMrDQ=="],
@@ -513,6 +519,8 @@

    "eslint-plugin-perfectionist": ["eslint-plugin-perfectionist@5.9.0", "https://registry.npmmirror.com/eslint-plugin-perfectionist/-/eslint-plugin-perfectionist-5.9.0.tgz", { "dependencies": { "@typescript-eslint/utils": "^8.58.2", "natural-orderby": "^5.0.0" }, "peerDependencies": { "eslint": "^8.45.0 || ^9.0.0 || ^10.0.0" } }, "sha512-8TWzg02zmnBdZwCkWLi8jhzqXI+fE7Z/RwV8SL6xD45tJ8Bp3wGuYL2XtQgfe/Wd0eBqOUX+s6ey73IyszvKTA=="],

+    "eslint-plugin-prettier": ["eslint-plugin-prettier@5.5.5", "https://registry.npmmirror.com/eslint-plugin-prettier/-/eslint-plugin-prettier-5.5.5.tgz", { "dependencies": { "prettier-linter-helpers": "^1.0.1", "synckit": "^0.11.12" }, "peerDependencies": { "@types/eslint": ">=8.0.0", "eslint": ">=8.0.0", "eslint-config-prettier": ">= 7.0.0 <10.0.0 || >=10.1.0", "prettier": ">=3.0.0" }, "optionalPeers": ["@types/eslint", "eslint-config-prettier"] }, "sha512-hscXkbqUZ2sPithAuLm5MXL+Wph+U7wHngPBv9OMWwlP8iaflyxpjTYZkmdgB4/vPIhemRlBEoLrH7UC1n7aUw=="],
+
    "eslint-plugin-react-hooks": ["eslint-plugin-react-hooks@7.1.1", "https://registry.npmmirror.com/eslint-plugin-react-hooks/-/eslint-plugin-react-hooks-7.1.1.tgz", { "dependencies": { "@babel/core": "^7.24.4", "@babel/parser": "^7.24.4", "hermes-parser": "^0.25.1", "zod": "^3.25.0 || ^4.0.0", "zod-validation-error": "^3.5.0 || ^4.0.0" }, "peerDependencies": { "eslint": "^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0-0 || ^9.0.0 || ^10.0.0" } }, "sha512-f2I7Gw6JbvCexzIInuSbZpfdQ44D7iqdWX01FKLvrPgqxoE7oMj8clOfto8U6vYiz4yd5oKu39rRSVOe1zRu0g=="],

    "eslint-plugin-react-refresh": ["eslint-plugin-react-refresh@0.5.2", "https://registry.npmmirror.com/eslint-plugin-react-refresh/-/eslint-plugin-react-refresh-0.5.2.tgz", { "peerDependencies": { "eslint": "^9 || ^10" } }, "sha512-hmgTH57GfzoTFjVN0yBwTggnsVUF2tcqi7RJZHqi9lIezSs4eFyAMktA68YD4r5kNw1mxyY4dmkyoFDb3FIqrA=="],
@@ -535,6 +543,8 @@

    "fast-deep-equal": ["fast-deep-equal@3.1.3", "https://registry.npmmirror.com/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz", {}, "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q=="],

+    "fast-diff": ["fast-diff@1.3.0", "https://registry.npmmirror.com/fast-diff/-/fast-diff-1.3.0.tgz", {}, "sha512-VxPP4NqbUjj6MaAOafWeUn2cXWLcCtljklUtZf0Ind4XQ+QPtmA0b18zZy0jIQx+ExRVCR/ZQpBmik5lXshNsw=="],
+
    "fast-json-stable-stringify": ["fast-json-stable-stringify@2.1.0", "https://registry.npmmirror.com/fast-json-stable-stringify/-/fast-json-stable-stringify-2.1.0.tgz", {}, "sha512-lhd/wF+Lk98HZoTCtlVraHtfh5XYijIjalXck7saUtuanSDyLMxnHhSXEDJqHxD7msR8D0uCmqlkwjCV8xvwHw=="],

    "fast-levenshtein": ["fast-levenshtein@2.0.6", "https://registry.npmmirror.com/fast-levenshtein/-/fast-levenshtein-2.0.6.tgz", {}, "sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw=="],
@@ -833,6 +843,8 @@

    "prettier": ["prettier@3.8.3", "https://registry.npmmirror.com/prettier/-/prettier-3.8.3.tgz", { "bin": { "prettier": "bin/prettier.cjs" } }, "sha512-7igPTM53cGHMW8xWuVTydi2KO233VFiTNyF5hLJqpilHfmn8C8gPf+PS7dUT64YcXFbiMGZxS9pCSxL/Dxm/Jw=="],

+    "prettier-linter-helpers": ["prettier-linter-helpers@1.0.1", "https://registry.npmmirror.com/prettier-linter-helpers/-/prettier-linter-helpers-1.0.1.tgz", { "dependencies": { "fast-diff": "^1.1.2" } }, "sha512-SxToR7P8Y2lWmv/kTzVLC1t/GDI2WGjMwNhLLE9qtH8Q13C+aEmuRlzDst4Up4s0Wc8sF2M+J57iB3cMLqftfg=="],
+
    "prop-types": ["prop-types@15.8.1", "https://registry.npmmirror.com/prop-types/-/prop-types-15.8.1.tgz", { "dependencies": { "loose-envify": "^1.4.0", "object-assign": "^4.1.1", "react-is": "^16.13.1" } }, "sha512-oj87CgZICdulUohogVAR7AjlC0327U4el4L6eAvOqCeudMDVU0NThNaV+b9Df4dXgSP1gXMTnPdhfe/2qDH5cg=="],

    "punycode": ["punycode@2.3.1", "https://registry.npmmirror.com/punycode/-/punycode-2.3.1.tgz", {}, "sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg=="],
@@ -937,6 +949,8 @@

    "supports-preserve-symlinks-flag": ["supports-preserve-symlinks-flag@1.0.0", "https://registry.npmmirror.com/supports-preserve-symlinks-flag/-/supports-preserve-symlinks-flag-1.0.0.tgz", {}, "sha512-ot0WnXS9fgdkgIcePe6RHNk1WA8+muPa6cSjeR3V8K27q9BB1rTE3R1p7Hv0z1ZyAc8s6Vvv8DIyWf681MAt0w=="],

+    "synckit": ["synckit@0.11.12", "https://registry.npmmirror.com/synckit/-/synckit-0.11.12.tgz", { "dependencies": { "@pkgr/core": "^0.2.9" } }, "sha512-Bh7QjT8/SuKUIfObSXNHNSK6WHo6J1tHCqJsuaFDP7gP0fkzSfTxI8y85JrppZ0h8l0maIgc2tfuZQ6/t3GtnQ=="],
+
    "tdesign-icons-react": ["tdesign-icons-react@0.6.4", "https://registry.npmmirror.com/tdesign-icons-react/-/tdesign-icons-react-0.6.4.tgz", { "dependencies": { "@babel/runtime": "^7.16.5", "classnames": "^2.2.6" }, "peerDependencies": { "react": ">=16.13.1", "react-dom": ">=16.13.1" } }, "sha512-USAoi9vBWcwcJT45VqR3dRqX1MeAsn/RhHVx4bLwplhrlvE80ZQ1N9V+6F3HqE1Qe9mMDbtRM8Ul80+lALScww=="],

    "tdesign-react": ["tdesign-react@1.16.9", "https://registry.npmmirror.com/tdesign-react/-/tdesign-react-1.16.9.tgz", { "dependencies": { "@babel/runtime": "~7.26.7", "@popperjs/core": "~2.11.2", "@types/sortablejs": "^1.10.7", "@types/validator": "^13.1.3", "classnames": "~2.5.1", "dayjs": "1.11.10", "hoist-non-react-statics": "~3.3.2", "lodash-es": "^4.17.21", "mitt": "^3.0.0", "raf": "~3.4.1", "react-fast-compare": "^3.2.2", "react-is": "^18.2.0", "react-transition-group": "~4.4.1", "sortablejs": "^1.15.0", "tdesign-icons-react": "^0.6.4", "tslib": "~2.3.1", "validator": "~13.15.0" }, "peerDependencies": { "react": ">=16.13.1", "react-dom": ">=16.13.1" } }, "sha512-C3uZRTkJ1iQ62BrMkuvqvBK+4HEuhl82rABxa6kAHGHL3eBI4DPfzAJGF0T3b+DKCBeJxb0x10elumT6NkQEaw=="],
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -1,6 +1,7 @@
 import js from "@eslint/js";
 import importPlugin from "eslint-plugin-import";
 import perfectionist from "eslint-plugin-perfectionist";
+import eslintPluginPrettierRecommended from "eslint-plugin-prettier/recommended";
 import reactHooks from "eslint-plugin-react-hooks";
 import reactRefresh from "eslint-plugin-react-refresh";
 import tseslint from "typescript-eslint";
@@ -88,4 +89,5 @@ export default tseslint.config(
      "react-refresh/only-export-components": ["warn", { allowConstantExport: true }],
    },
  },
+  eslintPluginPrettierRecommended,
 );
--- a/openspec/specs/code-quality-gates/spec.md
+++ b/openspec/specs/code-quality-gates/spec.md
@@ -36,22 +36,23 @@
 - **THEN** 系统 MUST 排除 `dist/`、`.build/`、`node_modules/`、`openspec/`、`.opencode/`、`.claude/`、`.codex/`、`*.bun-build`、`bun.lock`、`data/` 等非源码目录

 ### Requirement: Prettier 代码格式门禁
-项目 SHALL 提供 Prettier 格式化和格式检查命令，用于统一代码风格。Prettier 配置 SHALL 显式声明 `printWidth`、`semi`、`singleQuote`、`trailingComma`、`bracketSpacing`、`arrowParens`、`endOfLine`、`tabWidth`、`useTabs` 全部格式化参数。
+
+项目 SHALL 通过 `eslint-plugin-prettier` 将 Prettier 格式检查集成为 ESLint 规则，使 `lint` 命令同时覆盖代码质量和格式检查（原独立的 `format:check` 命令不再存在，格式检查统一通过 `lint` 完成）。项目仍保留独立的 `format` 命令（`prettier --write`）用于快速格式化。Prettier 配置 SHALL 显式声明 `printWidth`、`semi`、`singleQuote`、`trailingComma`、`bracketSpacing`、`arrowParens`、`endOfLine`、`tabWidth`、`useTabs` 全部格式化参数。

 #### Scenario: 检查代码格式
- **WHEN** 开发者运行文档化的格式检查命令
- **THEN** 系统 SHALL 使用 Prettier 检查受管理文件，并在发现未格式化文件时以非零状态退出
+- **WHEN** 开发者运行 `bun run lint`
+- **THEN** ESLint SHALL 通过 eslint-plugin-prettier 检查受管理文件格式，并在发现未格式化文件时以非零状态退出

 #### Scenario: 自动格式化代码
- **WHEN** 开发者运行文档化的格式化命令
+- **WHEN** 开发者运行 `bun run format` 或 `eslint --fix`
 - **THEN** 系统 SHALL 使用 Prettier 重写受管理文件的格式

 #### Scenario: 排除 OpenSpec 文档和生成产物
- **WHEN** Prettier 格式化或格式检查运行
+- **WHEN** Prettier 格式化或格式检查运行（通过 ESLint 或独立 Prettier 命令）
 - **THEN** 系统 MUST 排除 `openspec/`、`dist/`、`.build/`、`node_modules/`、`bun.lock`、`skills-lock.json`、`.agents/`、`data/`、`*.bun-build`、`.opencode/`、`.claude/`、`.codex/` 和临时构建产物

 #### Scenario: 格式化配置一致性
- **WHEN** 不同开发者在不同操作系统上运行 `prettier --write`
+- **WHEN** 不同开发者在不同操作系统上运行格式化（通过 ESLint 或独立 Prettier）
 - **THEN** 由于所有格式化参数均显式定义，产物 SHALL 完全一致

 ### Requirement: TypeScript 未使用变量检测
@@ -95,11 +96,12 @@
 - **THEN** lint 命令 MUST 报告 `import/no-cycle` 警告

 ### Requirement: 快速检查命令
+
 项目 SHALL 提供快速 `check` 命令，用于日常开发期间验证代码质量和基础行为。

 #### Scenario: 运行快速检查
 - **WHEN** 开发者运行 `bun run check`
- **THEN** 系统 SHALL 依次执行类型检查、lint、格式检查和单元测试
+- **THEN** 系统 SHALL 依次执行类型检查、lint（含格式检查）和单元测试

 #### Scenario: 快速检查失败
 - **WHEN** `check` 中任一子检查失败
--- a/openspec/specs/commit-quality-gates/spec.md
+++ b/openspec/specs/commit-quality-gates/spec.md
@@ -5,18 +5,19 @@
 ## Requirements

 ### Requirement: pre-commit 自动质量检查
-项目 SHALL 通过 husky 和 lint-staged 在 git commit 前自动对变更文件运行 ESLint 和 Prettier 检查。
+
+项目 SHALL 通过 husky 和 lint-staged 在 git commit 前自动对变更文件运行 ESLint（含 Prettier 格式）检查。由于 eslint-plugin-prettier 已集成格式检查，lint-staged SHALL 仅运行 `eslint --fix` 即可同时修复代码质量和格式问题。

 #### Scenario: 变更 TypeScript 文件后提交
 - **WHEN** 开发者 stage 了 `.ts` 或 `.tsx` 文件并执行 `git commit`
- **THEN** lint-staged SHALL 自动对变更文件运行 `eslint --fix` 和 `prettier --write`，修复后继续提交
+- **THEN** lint-staged SHALL 自动对变更文件运行 `eslint --fix`（含格式修复），修复后继续提交

 #### Scenario: 变更 Markdown 或 JSON 文件后提交
 - **WHEN** 开发者 stage 了 `.md`、`.json`、`.yaml` 或 `.yml` 文件并执行 `git commit`
 - **THEN** lint-staged SHALL 自动对变更文件运行 `prettier --write`

 #### Scenario: lint 检查失败阻止提交
- **WHEN** 变更文件存在无法自动修复的 ESLint 错误
+- **WHEN** 变更文件存在无法自动修复的 ESLint 错误（含格式错误）
 - **THEN** pre-commit hook MUST 以非零状态退出，阻止提交

 #### Scenario: 无变更文件提交
--- a/openspec/specs/eslint-prettier-integration/spec.md
+++ b/openspec/specs/eslint-prettier-integration/spec.md
@@ -0,0 +1,25 @@
+## Purpose
+
+定义 ESLint 与 Prettier 集成方案，通过 eslint-plugin-prettier 将 Prettier 格式检查统一纳入 ESLint 工作流，减少独立工具调用，提升开发体验。
+
+## Requirements
+
+### Requirement: ESLint 集成 Prettier 格式检查
+
+项目 SHALL 通过 `eslint-plugin-prettier` 将 Prettier 格式规则集成为 ESLint 规则，使单次 `eslint .` 运行同时报告代码质量问题和格式问题。ESLint 配置 SHALL 注册 `plugin:prettier/recommended` 规则集，该规则集自动加载 Prettier 配置并禁用与 Prettier 冲突的 ESLint 规则。
+
+#### Scenario: lint 运行同时检查格式
+- **WHEN** 开发者运行 `bun run lint`
+- **THEN** ESLint SHALL 同时报告代码质量违规和 Prettier 格式违规
+
+#### Scenario: lint --fix 自动格式化
+- **WHEN** 开发者运行 `eslint --fix` 或 lint-staged 自动触发 `eslint --fix`
+- **THEN** ESLint SHALL 对可自动修复的代码质量问题和格式问题一并修正，包括调用 Prettier 重写文件格式
+
+#### Scenario: Prettier 配置被正确读取
+- **WHEN** ESLint 通过 eslint-plugin-prettier 检查代码格式
+- **THEN** 检查结果 SHALL 与独立运行 `prettier --check` 的结果完全一致
+
+#### Scenario: 不因集成降低 lint 性能
+- **WHEN** 开发者运行 `bun run lint`
+- **THEN** 运行时间 SHOULD 不超过原 `eslint .` + `prettier --check` 总耗时的 120%
--- a/package.json
+++ b/package.json
@@ -6,13 +6,10 @@
    "dev": "bun run scripts/dev.ts",
    "dev:server": "bun --watch src/server/dev.ts",
    "dev:web": "bunx --bun vite --host 127.0.0.1",
-    "build:web": "bunx --bun vite build",
    "build": "bun run scripts/build.ts",
-    "start": "bun src/server/dev.ts",
    "lint": "eslint .",
    "format": "prettier . --write",
-    "format:check": "prettier . --check",
-    "check": "bun run typecheck && bun run lint && bun run format:check && bun test",
+    "check": "bun run typecheck && bun run lint && bun test",
    "verify": "bun run check && bun run build && bun run test:smoke",
    "test": "bun test",
    "test:smoke": "bun run scripts/smoke.ts",
@@ -30,9 +27,11 @@
    "@types/react-dom": "^19.2.3",
    "@vitejs/plugin-react": "^6.0.1",
    "eslint": "^10.3.0",
+    "eslint-config-prettier": "^10.1.8",
    "eslint-import-resolver-typescript": "^4.4.4",
    "eslint-plugin-import": "^2.32.0",
    "eslint-plugin-perfectionist": "^5.9.0",
+    "eslint-plugin-prettier": "^5.5.5",
    "eslint-plugin-react-hooks": "^7.1.1",
    "eslint-plugin-react-refresh": "^0.5.2",
    "husky": "^9.1.7",
--- a/scripts/clean.ts
+++ b/scripts/clean.ts
@@ -4,7 +4,8 @@ import { resolve } from "node:path";
 const root = resolve(import.meta.dir, "..");

 const patterns: Array<{ desc: string; glob: string }> = [
-  { desc: "Bun 构建缓存", glob: ".build/" },
+  { desc: "构建产物", glob: "dist/**" },
+  { desc: "Bun 构建缓存", glob: ".build/**" },
  { desc: "Bun 构建临时文件", glob: ".*.bun-build" },
 ];