VLCode-Lite/AGENTS.md

VLCode-Lite — Project Instructions

Test Project Convention

All test/demo VL projects used for workflow testing or feature verification live under:

~/Documents/VLProjects/_tests/
├── AdjustTest/          ← adjustment workflow test project
│   ├── Config/
│   │   └── ProjectConfig
│   ├── Apps/
│   ├── Sections/
│   ├── Services/
│   ├── Database/
│   ├── Theme/
│   └── .vl-code/
│       └── ProjectMeta.json
├── CompileTest/         ← compile workflow test
└── ...

Rules:

• Root: ~/Documents/VLProjects/_tests/ — test-only projects, not production
• Naming: PascalCase, suffix with Test for clarity
• Cleanup: Test projects can be deleted freely; they carry no production data
• Never mix: Do NOT put test projects inside VLCode-Lite source tree

Workspace Management (WorkspaceManager Tool)

AI Assistant can create, switch, and list workspaces via the WorkspaceManager tool. The left-side file tree syncs automatically after any create/switch operation.

Action	Parameters	Description
create	projectName, parentDir?, autoSwitch?	Scaffold new VL project, add to workspace list, auto-switch
switch	dirPath	Switch active workspace, file tree + tabs update
list	(none)	List all registered workspaces

Creation Rules:

• projectName: PascalCase, English-only (e.g. MyApp, not my-app or 我的应用)
• parentDir defaults: ~/Documents/VLProjects for production, ~/Documents/VLProjects/_tests for test projects
• autoSwitch: defaults to true — after creation, workspace switches and file tree updates immediately
• Standard structure created automatically: Apps/, Sections/, ExtComponents/, Services/, Database/, Theme/, Config/, .vl-code/
• Existing directory: if target already exists and is non-empty, tool warns instead of overwriting

Usage Examples:

# Create test project (AI tool call)
WorkspaceManager({ action: "create", projectName: "AdjustTest", parentDir: "~/Documents/VLProjects/_tests" })

# Switch to existing project
WorkspaceManager({ action: "switch", dirPath: "/Users/ivx/Documents/VLProjects/SmartCampus" })

# List all workspaces
WorkspaceManager({ action: "list" })

Adjustment Workflow System

VLCode-Lite provides multiple adjustment workflows via the VLAdjust tool:

Workflow	JSON File	Use Case
add-page	add-page.json	Add a new page/section/route
add-service	add-service.json	Add a new backend service domain
theme-customize	theme-customize.json	Modify theme tokens
general	incremental-update.json	General modifications (meta diff → regen)
add-feature	feature-adjust.json	Add feature to existing page (button, form, chart)
modify-data	data-adjust.json	Add/modify database fields with cascade
batch	batch-adjust.json	Multiple small adjustments in one pass

Development

• Port: 3300 (dev server)
• Entry: bin/vlcode-lite.js
• Tools: src/tools/ (factory pattern, registered in src/tools/index.js)
• Workflows: .vl-code/workflows/ (runtime JSON currently 3.16; canonical spec doc is DocCenter Path 3, VL Workflow Spec 3.18)