菜单
Patterns and conventions for working on the devctl Vue 3 SPA — Pinia stores, API wrappers, shadcn-vue components, Tailwind v4, and the Vite/go:embed pipeline
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
How to write and run devctl integration tests — where tests live, how to write failing tests first (TDD), and how to run them safely inside an Incus container without touching live host data.
Full workflow for tagging and publishing a devctl release and/or a PHP binaries release — versioning, release note generation from TODO.md, clearing TODO.md completed items, and the exact git/GitHub CLI steps for each release type.
How to add a new CLI command to devctl — writing the Cmd struct, registering it with init(), adding Client methods, using output helpers, and documenting it in README.md
How to add a new dashboard screenshot for a new or existing feature — wiring up scripts/screenshots.js, seeding data into the demo container via scripts/demo.sh, and adding the image reference to the README.
How to create, update, or maintain agent skills for this project — file structure, frontmatter rules, naming constraints, and where OpenCode discovers them
Full workflow for picking up and completing a TODO item from TODO.md — read the backlog, clarify, implement, install, browser-test, update docs, and move the item to Completed.
| name | vue-frontend |
| description | Patterns and conventions for working on the devctl Vue 3 SPA — Pinia stores, API wrappers, shadcn-vue components, Tailwind v4, and the Vite/go:embed pipeline |
| license | MIT |
| compatibility | opencode |
| metadata | {"layer":"frontend","language":"typescript"} |
The frontend is a Vue 3 + TypeScript SPA in frontend/. The Vite build outputs to ui/dist/, which is embedded into the Go binary at compile time via //go:embed ui/dist. During dev, Vite proxies /api and /ws to the Go server on :4000.
| Path | Purpose |
|---|---|
frontend/src/App.vue | App shell — sidebar nav, dark mode, SSE/WebSocket init on mount |
frontend/src/router/index.ts | vue-router routes (/services, /sites, /php, /dumps, /mail, /settings) |
frontend/src/views/ | One .vue file per route |
frontend/src/stores/ | Pinia stores (services, sites, dumps, settings) |
frontend/src/lib/api.ts | All typed fetch wrappers — always add new API calls here |
frontend/src/components/ui/ | shadcn-vue primitives — use these, don't write raw HTML controls |
frontend/src/composables/ | Small reusable composables (e.g. useDarkMode) |
All REST calls go through frontend/src/lib/api.ts. The internal request<T> helper handles fetch, JSON, and errors uniformly:
// Add a typed wrapper:
export const getExample = (id: string) =>
request<Example>('GET', `/api/example/${id}`)
export const createExample = (body: CreateExampleInput) =>
request<Example>('POST', '/api/example', body)
Errors thrown by request() are plain Error objects — catch them in the store or handler and show a toast via vue-sonner.
Follow the pattern in existing stores (stores/services.ts, stores/sites.ts):
import { defineStore } from 'pinia'
import { ref } from 'vue'
import { getExample } from '@/lib/api'
export const useExampleStore = defineStore('example', () => {
const items = ref<Example[]>([])
const loading = ref(false)
async function fetchAll() {
loading.value = true
try {
items.value = await getExample()
} finally {
loading.value = false
}
}
return { items, loading, fetchAll }
})
setup() style) in stores — not options API.api.ts functions.api.ts directly.frontend/src/views/ExampleView.vue.frontend/src/router/index.ts.App.vue (icon from lucide-vue-next, label, path).Use shadcn-vue components from frontend/src/components/ui/. Available:
Badge, Button, Card (+ CardHeader/CardContent/CardFooter), Dialog, Sheet, Select, Table, Sonner, Separator, Input, Label, Switch, Tooltip, and more.
Don't install new UI libraries — compose from existing primitives.
The project uses Tailwind CSS v4 (CSS-first config, no tailwind.config.js). Configuration is in frontend/src/style.css. Use standard utility classes; the dark mode variant is dark:.
Dark mode is toggled via the useDarkMode composable which persists to localStorage and toggles a dark class on <html>.
The services store opens an EventSource to /api/services/events in App.vue on mount. To consume it in a new store, follow stores/services.ts — listen to the shared EventSource reference, parse JSON.parse(event.data).
The dumps WebSocket (/ws/dumps) is also opened once in App.vue and shared via stores/dumps.ts. New real-time features should follow this hub-and-store pattern rather than opening additional WebSocket connections.
# From repo root:
make dev-ui # Vite HMR dev server (proxies /api + /ws to :4000)
make build-ui # Production Vite build → ui/dist/
make build # build-ui + go build
# From frontend/:
npm run dev # same as make dev-ui
npm run build # production build
npm run type-check # vue-tsc type checking
main.go embeds ui/dist with //go:embed ui/dist. The ui/dist/ directory is git-ignored. Always run make build-ui (or make build) before building the binary with a working UI.