chore(docs): migrate toolchain to vite-plus standard by honghuangdc · Pull Request #102 · soybeanjs/soybean-admin-docs

honghuangdc · 2026-10-13T03:01:08Z

User description

What

Replace the scattered Prettier / ESLint / lint-staged / simple-git-hooks stack with the unified vite-plus toolchain from the SoybeanJS templates/vue-ts standard, and refresh the docs pages that described the old tooling.

Also bumps three dependencies.

Toolchain

add vite.config.ts — staged / lint / fmt sourced from @soybeanjs/oxc-config, resolve.tsconfigPaths: true
add eslint.config.mjs using @soybeanjs/eslint-config-vue, drop eslint.config.js
add .vite-hooks/pre-commit (vp staged) and prepare: vp config --no-agent
add AGENTS.md, .github/workflows/pr-agent.yml
align .editorconfig, .gitattributes, .vscode/{settings,extensions,launch}.json with the template
package.json — drop @soybeanjs/eslint-config, eslint-plugin-vue, vue-eslint-parser; add @soybeanjs/oxc-config, tsx, vite-plus
pnpm-workspace.yaml — add the vite / typescript catalogs
bump vitepress to 2.0.0-alpha.20, which requires vite 8 and now resolves to the vite shipped by vite-plus

dev / build / preview intentionally stay on the native vitepress commands: VitePress drives its own internal createServer / build and ignores the project vite.config.ts.

Dependencies

package	from	to
`@types/node`	`^26.6.4`	`^26.6.5`
`vue-tsc`	`^3.3.12`	`^3.3.13`
`vitepress-plugin-llms`	`^1.13.1`	`^1.14.0`

Docs (zh / en / jp)

rewrite standard/lint, standard/tools, guide/cli/git-hooks around vp fmt / vp lint / vp staged / vp config
drop stale Prettier / simple-git-hooks references in guide/intro and guide/quick-start
fix vue/no-template-target-blank in .vitepress/theme/NoticeBar.vue

Verification

pnpm fmt / pnpm lint / pnpm typecheck / pnpm build all exit 0
committing triggers the hook and prints vp check --fix
git config core.hooksPath is .vite-hooks/_

Notes

One non-obvious blocker hit along the way: with vue 3.5.38, VitePress 2.0.0-alpha.20 splits @vue/shared into two copies and watch(lang, fn) fails with error TS2769: No overload matches this call in NoticeBar.vue. Fixed by bumping vue to 3.5.43 — pnpm install alone does not pick it up, since package.json pinned ^3.5.38 and pnpm reuses the lockfile version.

^{Need help on this PR? Tag @codesmith-bot with what you need.}

PR Type

Enhancement, Documentation, Other

Description

将分散的 Prettier / ESLint / lint-staged / simple-git-hooks 工具链统一迁移到 vite-plus（vp fmt / vp lint / vp staged / vp config）
重写 zh / en / jp 三语文档，介绍新工具链并移除过时的 prettier、simple-git-hooks 说明
新增 PR-Agent CI 工作流、AGENTS.md 编码规范与 .nvmrc 固定 Node 版本
升级依赖（vitepress 2.0.0-alpha.20、vue、vue-tsc 等）并将 engines 提升至 Node >=22.18.0、pnpm >=10.0.0
修复 NoticeBar.vue 中 target="_blank" 缺少 rel 的 lint 问题；其余文件按新格式化规则调整 import 排序

Diagram Walkthrough

flowchart LR
  A["旧工具链 Prettier/ESLint/lint-staged/simple-git-hooks"] -- "替换" --> B["vite-plus 统一工具链"]
  B -- "提供命令" --> C["vp fmt / vp lint / vp staged / vp config"]
  C -- "提交前检查" --> D[".vite-hooks/pre-commit"]
  B -- "文档同步" --> E["zh/en/jp 三语规范与指南重写"]
  F["依赖升级与 engines 提升"] --> B
  G["新增 PR-Agent 工作流 + AGENTS.md"] --> H["CI 自动评审"]

File Walkthrough

Relevant files

Enhancement

2 files

vite.config.ts `新增 vite-plus 配置（staged、lint、fmt）`	+16/-0
pr-agent.yml `新增 PR-Agent 自动评审工作流`	+109/-0

Dependencies

1 files

package.json `更新脚本与依赖至 vite-plus 工具链`	+28/-24

Configuration changes

9 files

pnpm-workspace.yaml `新增 vite 与 typescript catalog 及 overrides`	+8/-0
eslint.config.mjs `新配置改用 @soybeanjs/eslint-config-vue`	+3/-0
eslint.config.js `删除旧版 eslint 配置文件`	+0/-8
pre-commit `新增 pre-commit 钩子执行 vp staged`	+1/-0
.nvmrc `固定 Node 版本为 24.15.0`	+1/-0
settings.json `切换默认格式化器为 Oxc`	+5/-17
extensions.json `更新推荐插件列表加入 Oxc`	+7/-4
launch.json `更新调试配置改用 tsx 运行`	+8/-6
tsconfig.json `新增 skipLibCheck 编译选项`	+2/-1

Documentation

7 files

AGENTS.md `新增 AI 编码规范与提交约定`	+12/-0
lint.md `重写英文格式化检查文档为 vite-plus`	+39/-29
lint.md `重写中文格式化检查文档为 vite-plus`	+39/-29
lint.md `重写日文格式化检查文档为 vite-plus`	+39/-29
tools.md `重写中文工具规范为 vite-plus 工具链`	+52/-46
tools.md `重写日文工具规范为 vite-plus 工具链`	+132/-1
quick-start.md `更新快速开始的脚本与插件说明`	+6/-6

Bug fix

1 files

NoticeBar.vue `修复链接缺少 rel 属性问题`	+7/-2

Additional files

22 files

.gitattributes	+1/-16
config.ts	+4/-4
index.ts	+2/-2
index.md	+1/-1
git-hooks.md	+4/-2
use-table.md	+1/-1
intro.md	+1/-1
usage.md	+2/-2
git-hooks.md	+6/-2
use-table.md	+1/-1
intro.md	+1/-1
quick-start.md	+5/-5
usage.md	+2/-2
index.md	+2/-2
git-hooks.md	+4/-2
use-table.md	+1/-1
intro.md	+1/-1
quick-start.md	+6/-6
usage.md	+2/-2
synthesis.md	+0/-3
ts.md	+0/-1
other.md	+1/-1

Replace the scattered Prettier/ESLint/lint-staged/simple-git-hooks stack with the unified vite-plus toolchain described by the SoybeanJS standard templates, and refresh the docs pages that described the old tooling. Toolchain: - add vite.config.ts (staged/lint/fmt from @soybeanjs/oxc-config) - add eslint.config.mjs using @soybeanjs/eslint-config-vue, drop eslint.config.js - add .vite-hooks/pre-commit and the `prepare: vp config --no-agent` script - add AGENTS.md, .github/workflows/pr-agent.yml, .editorconfig, .gitattributes - align .vscode settings/extensions/launch with the template - package.json: drop @soybeanjs/eslint-config, eslint-plugin-vue, vue-eslint-parser; add @soybeanjs/oxc-config, tsx, vite-plus - pnpm-workspace.yaml: add the vite/typescript catalogs - bump vitepress to 2.0.0-alpha.20, which requires vite 8 and now resolves to the vite shipped by vite-plus Docs: - rewrite standard/lint, standard/tools and guide/cli/git-hooks (zh/en/jp) to describe vp fmt, vp lint, vp staged and vp config - drop stale prettier/simple-git-hooks references in intro and quick-start - fix vue/no-template-target-blank in .vitepress/theme/NoticeBar.vue

github-actions · 2026-10-13T03:07:57Z

+* text=auto
+*.* text eol=lf


二进制文件损坏风险

*.* text eol=lf 对所有带扩展名的文件显式设置 text，会绕过 git 的二进制自动检测，强制执行 CRLF→LF 归一化。PNG 等二进制资源的文件签名本身就包含 0D 0A 字节（PNG magic 为 89 50 4E 47 0D 0A 1A 0A），一旦被 git add 或 git add --renormalize 就会被改写而损坏；文档站通常会包含 public 下的图片、favicon 等二进制资产。建议只保留 * text=auto（可安全识别二进制），或补充 *.png、*.ico、*.woff2 等文件的 binary 覆盖规则。

github-actions · 2026-10-13T03:07:57Z

+> 1、把 `package.json` 的 `prepare` 脚本删掉
 >
-> 2、执行 `simple-git-hooks` 命令
+> 2、删除 `.vite-hooks/` 目录下的钩子脚本（例如 `pre-commit`）


文档步骤不完整

「永久关闭校验」的两个步骤并不能真正关闭钩子：core.hooksPath 已被 prepare 指向 .vite-hooks/_，删除 prepare 脚本和 .vite-hooks/ 下的源脚本后，_ 目录中已生成的 pre-commit 钩子依然生效（轻则继续执行检查，重则因源脚本缺失报错而阻断提交）。已在本地执行过安装的开发者照做后会发现校验并未关闭，应补充 git config --unset core.hooksPath 或删除 .vite-hooks/_ 目录。英文版（src/guide/cli/git-hooks.md）与日文版（src/jp/guide/cli/git-hooks.md）存在同样问题。

github-actions · 2026-10-13T03:07:57Z

@@ -94,8 +94,8 @@ pnpm i
  "gen-route": "sa gen-route",
  // eslint check and auto fix
  "lint": "eslint . --fix",


文档不一致

中文版 quick-start 已把示例脚本更新为 "lint": "vp lint --fix && eslint --fix ."，但英文版与日文版同一示例中 lint 仍是 "eslint . --fix"，与本次迁移到 vite-plus 后的命令及仓库实际 package.json 不一致；读者按英文/日文文档配置会得到与规范不符的 lint 命令。建议同步更新两个语言版本。

github-actions · 2026-10-13T03:08:00Z

PR Reviewer Guide 🔍

(Review updated until commit `0949a75`)

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 3 🔵🔵🔵⚪⚪
🧪 No relevant tests
🔒 No security concerns identified
⚡ No major issues detected

✅ Resolved findings

package.json

Possible Issue

本 PR 在 pnpm-workspace.yaml 中新增了 catalog: 协议（typescript、vite-plus、vite 均指向 catalog），该协议要求 pnpm >= 9.5 才能解析，但 engines.pnpm 仍停留在 >=8.7.0。使用 pnpm 8.x / 9.0-9.4 的贡献者（满足 engines 下限，且 pnpm 默认不强制 engine-strict，仅 packageManager 字段对启用 corepack 的环境生效）执行 pnpm install 时会在解析 "typescript": "catalog:" 这类声明处直接报错，且报错信息难以定位。建议把 pnpm 下限提升到与 catalog 用法匹配的版本（如 >=10）。

AGENTS.md

Documentation Inconsistency

AGENTS.md 明显是从模板直接复制而未适配本仓库：其一，"Never commit Chinese text" 与本仓库 package.json 中保留的 commit:zh 脚本（soy git-commit -l=zh-cn 交互式生成中文提交信息）直接矛盾；其二，提交 scope 的示例给的是 ubean、proposals、agents 等，均与 soybean-admin-docs 仓库的实际改动区域无关。AGENTS.md 的目标读者是 AI 代理，这些强制性指令会与其可用的仓库工具链冲突或产生误导。

src/jp/standard/tools.md:78-85

文档不一致

新增的日语文档中 engines 示例仍写 "node": ">=20.19.0"，而同一 PR 已将本仓库 package.json 的 engines 提升为 >=22.18.0（.nvmrc 也升到 24.15.0）。该页面正是向用户介绍新版 vite-plus 工具链的入口，却展示过时的 Node 最低版本，可能误导用户在不满足实际要求的旧 Node 环境下安装运行。建议与本次迁移后的实际约束（>=22.18.0）对齐，并顺带核对中文版对应段落是否同样过时。

.gitattributes:1-2

二进制文件损坏风险

*.* text eol=lf 对所有带扩展名的文件显式设置 text，会绕过 git 的二进制自动检测，强制执行 CRLF→LF 归一化。PNG 等二进制资源的文件签名本身就包含 0D 0A 字节（PNG magic 为 89 50 4E 47 0D 0A 1A 0A），一旦被 git add 或 git add --renormalize 就会被改写而损坏；文档站通常会包含 public 下的图片、favicon 等二进制资产。建议只保留 * text=auto（可安全识别二进制），或补充 *.png、*.ico、*.woff2 等文件的 binary 覆盖规则。

src/zh/guide/cli/git-hooks.md:34-36

文档步骤不完整

「永久关闭校验」的两个步骤并不能真正关闭钩子：core.hooksPath 已被 prepare 指向 .vite-hooks/_，删除 prepare 脚本和 .vite-hooks/ 下的源脚本后，_ 目录中已生成的 pre-commit 钩子依然生效（轻则继续执行检查，重则因源脚本缺失报错而阻断提交）。已在本地执行过安装的开发者照做后会发现校验并未关闭，应补充 git config --unset core.hooksPath 或删除 .vite-hooks/_ 目录。英文版（src/guide/cli/git-hooks.md）与日文版（src/jp/guide/cli/git-hooks.md）存在同样问题。

src/guide/quick-start.md:96

文档不一致

中文版 quick-start 已把示例脚本更新为 "lint": "vp lint --fix && eslint --fix ."，但英文版与日文版同一示例中 lint 仍是 "eslint . --fix"，与本次迁移到 vite-plus 后的命令及仓库实际 package.json 不一致；读者按英文/日文文档配置会得到与规范不符的 lint 命令。建议同步更新两个语言版本。

Cloudflare Pages only sets NODE_VERSION for the production environment, so preview builds fell back to the build image default of node 18.17.1. vite-plus requires node ^22.18.0 || ^24.11.0 || >=26, and its `vp` bin is an extensionless ESM entry, so the `prepare` script died with ERR_UNKNOWN_FILE_EXTENSION and took the whole build down. Add a repo-level .nvmrc so every environment resolves the same node version, and raise the engines floor to match what vite-plus needs.

- .gitattributes: use the template `* text=auto eol=lf` instead of a separate `*.* text eol=lf` rule, which forced `text` on every file with an extension and could mangle binary assets - quick-start: the en and jp `lint` example still read `eslint . --fix`; align it with the zh version and with the actual `package.json` - quick-start: eslint.config.js is now eslint.config.mjs - git-hooks: deleting the `prepare` script does not disable hooks on its own; core.hooksPath already points at the generated dispatcher, so document `vp hooks disable` for all three locales

cloudflare-workers-and-pages · 2026-10-13T03:22:11Z

Deploying soybean-admin-docs with Cloudflare Pages

Latest commit:	`0949a75`
Status:	✅ Deploy successful!
Preview URL:	https://24fc1eb8.soybean-admin-docs-d90.pages.dev
Branch Preview URL:	https://chore-standardize.soybean-admin-docs-d90.pages.dev

View logs

github-actions · 2026-10-13T03:28:54Z

+```json
+{
+  "engines": {
+    "node": ">=20.19.0",
+    "pnpm": ">=8.7.0"
+  }
+}
+```


文档不一致

新增的日语文档中 engines 示例仍写 "node": ">=20.19.0"，而同一 PR 已将本仓库 package.json 的 engines 提升为 >=22.18.0（.nvmrc 也升到 24.15.0）。该页面正是向用户介绍新版 vite-plus 工具链的入口，却展示过时的 Node 最低版本，可能误导用户在不满足实际要求的旧 Node 环境下安装运行。建议与本次迁移后的实际约束（>=22.18.0）对齐，并顺带核对中文版对应段落是否同样过时。

github-actions · 2026-10-13T03:28:58Z

Persistent review updated to latest commit 948eb26

vite-plus requires node ^22.18.0 || ^24.11.0 || >=26, so the engines floor is now >=22.18.0. Update the two `engines` examples in the tools pages and the tutorial note that still advertised >=20.19.0.

github-actions · 2026-10-13T03:39:08Z

Persistent review updated to latest commit caadaaf

- AGENTS.md carried the template's `ubean` / `proposals` / `agents` scope examples, which match nothing in this repository; point them at the real areas instead - `catalog:` in pnpm-workspace.yaml needs pnpm >= 9.5, so raising the engines floor to >=10.0.0 keeps installs from failing on declarations the pinned pnpm would reject; sync the two docs examples

github-actions · 2026-10-13T03:49:58Z

Persistent review updated to latest commit 0949a75

honghuangdc added 2 commits October 13, 2026 10:45

chore(deps): update deps

98ac12e

github-actions Bot reviewed Oct 13, 2026

View reviewed changes

github-actions Bot added the Review effort 3/5 label Oct 13, 2026

honghuangdc added 2 commits October 13, 2026 11:21

github-actions Bot reviewed Oct 13, 2026

View reviewed changes

docs(standard): sync node requirement with vite-plus

caadaaf

vite-plus requires node ^22.18.0 || ^24.11.0 || >=26, so the engines floor is now >=22.18.0. Update the two `engines` examples in the tools pages and the tutorial note that still advertised >=20.19.0.

honghuangdc merged commit 3b433de into main Oct 13, 2026
2 checks passed

honghuangdc deleted the chore/standardize branch October 13, 2026 04:02

Navigation Menu

Repository navigation

chore(docs): migrate toolchain to vite-plus standard - #102

chore(docs): migrate toolchain to vite-plus standard#102
honghuangdc merged 6 commits into
mainfrom
chore/standardize

honghuangdc commented Oct 13, 2026 •

edited by github-actions Bot

Loading

Uh oh!

github-actions Bot Oct 13, 2026

Uh oh!

github-actions Bot Oct 13, 2026

Uh oh!

github-actions Bot Oct 13, 2026

Uh oh!

github-actions Bot commented Oct 13, 2026 •

edited

Loading

package.json

AGENTS.md

src/jp/standard/tools.md:78-85

.gitattributes:1-2

src/zh/guide/cli/git-hooks.md:34-36

src/guide/quick-start.md:96

Uh oh!

cloudflare-workers-and-pages Bot commented Oct 13, 2026 •

edited

Loading

Uh oh!

github-actions Bot Oct 13, 2026

Uh oh!

github-actions Bot commented Oct 13, 2026

Uh oh!

github-actions Bot commented Oct 13, 2026

Uh oh!

github-actions Bot commented Oct 13, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

honghuangdc commented Oct 13, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

User description

What

Toolchain

Dependencies

Docs (zh / en / jp)

Verification

Notes

PR Type

Description

Diagram Walkthrough

File Walkthrough

Uh oh!

github-actions Bot Oct 13, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Oct 13, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Oct 13, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Oct 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Reviewer Guide 🔍

(Review updated until commit 0949a75)

package.json

AGENTS.md

src/jp/standard/tools.md:78-85

.gitattributes:1-2

src/zh/guide/cli/git-hooks.md:34-36

src/guide/quick-start.md:96

Uh oh!

cloudflare-workers-and-pages Bot commented Oct 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying soybean-admin-docs with Cloudflare Pages

Uh oh!

github-actions Bot Oct 13, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Oct 13, 2026

Uh oh!

github-actions Bot commented Oct 13, 2026

Uh oh!

github-actions Bot commented Oct 13, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

honghuangdc commented Oct 13, 2026 •

edited by github-actions Bot

Loading

github-actions Bot commented Oct 13, 2026 •

edited

Loading

(Review updated until commit `0949a75`)

cloudflare-workers-and-pages Bot commented Oct 13, 2026 •

edited

Loading