设计与 UI
dev-workflow
Build, lint, test, and verification workflow for the portal-tunnel Go+frontend monorepo. Use when setting up the repo, running CI-equivalent checks, or before committing changes.
gosuda · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add gosuda/portal-tunnel --skill dev-workflow技能说明
name: dev-workflow description: Build, lint, test, and verification workflow for the portal-tunnel Go+frontend monorepo. Use when setting up the repo, running CI-equivalent checks, or before committing changes.
portal-tunnel dev workflow
Toolchain
- Go pinned to
go1.26.4viago.mod; the Makefile exportsGOTOOLCHAIN=go1.26.4, somaketargets self-pin even on other Go installs. make installinstalls the pinned dev tools:goimports@v0.41.0andgolangci-lint@v2.11.1(into$(go env GOPATH)/bin, usually~/go/bin— put it on PATH).- Frontend build/test needs Node 22+.
bunis needed only formake build-docs.
Verification (CI commands, from AGENTS.md)
Run these three before pushing; they are what CI enforces:
make vet # go vet ./cmd/... ./portal/... ./sdk/... ./types/... ./utils/...
make lint # golangci-lint run (same package set)
make test # go test -coverprofile=coverage.out (same set) + `cd frontend && npm test` (vitest)
Per AGENTS.md, run tests only when needed/asked; make tidy is local maintenance, not a CI gate.
Pre-commit hooks
.pre-commit-config.yaml runs whitespace/EOL/BOM fixers, golangci-lint (config-verify, --new-from-rev HEAD --fix, and full --fix), plus local make fmt and go vet ./....
make fmtrunsgofmt -w .thengoimports -w ., sogoimportsMUST be on PATH or the commit hook fails withgoimports: No such file or directory— runmake installfirst.- Note the golangci-lint version differs between pre-commit (
v2.10.1) and the Makefile (v2.11.1); expect minor lint-behavior drift.
Build
make build→build-tunnel+build-server(full artifacts).make build-frontendbuilds the SPA (cd frontend && npm ci && npm run build) and copiesfrontend/dist/.intocmd/relay-server/dist/app(embedded by the relay via//go:embed dist/*).make build-server-bincompiles onlybin/relay-server; it assumesdist/appalready exists (use afterbuild-frontend, or the binary fails at startup asking you to runmake build-frontend).make build-tunnelcross-compilescmd/portal-tunnelfor linux/darwin/windows × amd64/arm64.- Shared Go build flags live in the Makefile var
GO_BUILD_FLAGS(-trimpath -ldflags "-s -w"); the Dockerfile callsmake build-server-binrather than duplicating them.
Making changes (AGENTS.md conventions — enforce in review)
- Shared contracts, constants, and public path strings belong in
types/(e.g.types/paths.go), never duplicated in runtime/helpers. - Stateless shared transforms go in
utils/; stateful/domain logic stays with its real owner (sdk/orportal/). - Prefer one owner per contract; no speculative abstraction, wrappers, or dead fields — remove them while touching nearby code.