Home Explore Help
Sign In
imengyu
/
minnan-zhangzhou
Watch 1
Star 0
Fork 0
Files Issues 0 Pull Requests 0 Wiki
Tree: 35a8f366a3
Branches Tags
minnan-zhang...
/
AGENTS.md

AGENTS.md 5.7 KB
History Raw

AGENTS Guidelines

Local Docs First

  • After dependencies are installed, prefer reading local package docs under node_modules/weapp-vite/dist/docs/ first.
  • Start with node_modules/weapp-vite/dist/docs/index.md, then read README.md and mcp.md as needed.
  • Prefer local package docs over stale model memory or old web pages when command behavior is unclear.

CLI Entry

  • This project supports both weapp-vite and wv CLI commands.
  • Treat weapp-vite dev and wv dev as equivalent forms.
  • Prefer project scripts such as pnpm dev, pnpm build, pnpm open, and pnpm g before ad-hoc shell commands.
  • Use weapp-vite prepare or wv prepare when managed support files under .weapp-vite/ need to be refreshed.
  • Prefer weapp-vite screenshot or wv screenshot for mini-program screenshot acceptance.
  • Prefer weapp-vite compare or wv compare for mini-program screenshot diff, baseline comparison, and visual regression checks.
  • Prefer weapp-vite ide logs --open or wv ide logs --open for DevTools terminal log bridging.
  • Do not default to generic browser screenshot tools when the target is the mini-program runtime in WeChat DevTools.

AI Intent Routing

  • When the request mentions screenshot, 截图, 页面快照, runtime screenshot, or capture the current mini-program page, default to weapp-vite screenshot / wv screenshot.
  • When the request mentions screenshot compare, 截图对比, diff, baseline, visual regression, 像素对比, or acceptance comparison, default to weapp-vite compare / wv compare.
  • Treat these commands as the primary screenshot contract for AI workflows in this project.
  • Only fall back to generic browser screenshot tools when the target is explicitly the web runtime instead of WeChat DevTools.

Weapp-vite Workflow

  • Keep vite.config.ts as the source of truth for weapp config, output behavior, and IDE/MCP automation.
  • Confirm weapp.srcRoot, routes, subpackages, and auto-import strategy before broad refactors.
  • Prefer minimal scoped verification: targeted pnpm build, targeted tests, then broader checks only when required.
  • If editing package source in a monorepo dependency, rebuild the touched package before validating downstream apps to avoid stale dist.
  • Keep CLI ownership explicit: native weapp-vite commands first, IDE passthrough second.
  • For Rust/native acceleration, treat JS ↔ Rust boundary crossings as a primary performance cost. Prefer batch analysis that sends source once, parses once, and returns structured results; only put fine-grained native APIs on hot paths when profiling proves a net win.
  • Keep native AST fast paths optional and explicitly enabled. They must fall back to Babel/Oxc/Vue compiler behavior on load, parse, or runtime failure, and new native coverage needs correctness tests plus real profiling.

SVG Icons

  • Icons render via the weapp-svg-icon npm component, referenced as weapp-svg-icon/index in usingComponents.
  • Icon data is tree-shaken from @iconify-json/ph and @iconify-json/solar into a minimal set by scripts/generate-svg-icons.mjs.
  • After adding or changing icons in source (new ph:* / solar:* names), run npm run gen:icons to regenerate the minimal data, then npx patch-package weapp-svg-icon to refresh patches/weapp-svg-icon+1.0.0.patch.
  • IMPORTANT: wv build caches compiled npm mini-program packages by package.json dependency hash (see node_modules/weapp-vite/.cache/). Regenerating only miniprogram_dist/index.js does NOT invalidate this cache, so new icons silently stay missing. After gen:icons, clear the cache before building, e.g. remove node_modules/weapp-vite/.cache/-.json, so the stale dist/miniprogram_npm/weapp-svg-icon/ is rebuilt.

WeChat DevTools

  • Before using screenshot, preview, upload, automator, or --open, ensure WeChat DevTools is logged in and the service port is enabled.
  • wv open, wv dev -o, and wv build -o use the official DevTools CLI first, then connect automator; if the IDE is open but automator is unavailable, run wv ide doctor --json before retrying.
  • Use --ide-open-strategy automator only for explicit compatibility debugging; do not treat it as the default startup path.
  • Prefer writing screenshots to workspace paths such as .tmp/acceptance.png.

AI Skills

  • Recommend installing shared skills with npx skills add sonofmagic/skills.
  • In Codex/Claude environments, prefer these skills first when available:
    • $weapp-vite-best-practices for config, build, subpackage, route, DevTools CLI orchestration, and screenshot/compare command work.
    • $weapp-vite-vue-sfc-best-practices for .vue SFC macros, JSON blocks, and template compatibility.
    • $release-and-changeset-best-practices for issue delivery, pnpm change intents, repoctl release decisions, and PR workflow.
    • $docs-and-website-sync when documentation or AI guidance must be refreshed together with code changes.
    • Use $weapp-vite-best-practices for stateful HMR, pluginRoot/dist-plugin, Web runtime compatibility, and native AST profiling; use $wevu-best-practices for wevu/router navigation semantics.
    • Use $weapp-devtools-e2e-best-practices for serialized DevTools runtime suites, shared automator sessions, and known host compatibility skips.
    • $native-to-weapp-vite-wevu-migration when migrating native mini-program projects to weapp-vite + native, or further toward Vue SFC / wevu.

Native Mini-program Authoring

  • Keep native page/component structure consistent with the template unless there is a clear migration goal.
  • Prefer weapp-vite generate or wv generate for new app/page/component scaffolds.
  • If migrating this project, first decide whether the target is weapp-vite + native or a further Vue SFC / wevu migration, then keep each migration wave explicit.