技能介绍

要解决的具体问题

在 VicroCode 平台上构建网站应用时，常见的几个痛点：

SDK 被默认使用：很多开发者默认引入 SDK，但平台支持不依赖 SDK的普通开发方式
现有应用改造缺乏审计流程：直接修改而不了解现有路由、后端结构、数据库路径和 AI 集成点
路径和持久化混乱：runtime/ 目录结构不清，SQLite 数据库位置错误，前端直接引用运行时文件
AI 集成平台绑定：默认推送平台托管的模型 API，而不是按提供商真实协议路由
计费逻辑不透明：扣费时机不明确，可能设计预扣费行为
多语言支持实现复杂：硬编码 UI 文案，平台运行时翻译工具内部逻辑

技能如何工作

核心能力与关键步骤

前置阅读规范

在开始实现前，按任务类型阅读相关参考文档：

references/version-and-site-selection.md：版本和站点选择
references/vicrocode-rules.md：VicroCode 规范
references/ai-model-integration.md：AI 集成（需要时）
references/pricing-and-publish.md：定价和发布（需要时）

项目分类与环境检测

站点类型：中文/国内站点 vs 英文/全球站点
项目类型：全新应用 vs 现有应用改造
现有应用审计：路由、后端、存储、AI 集成、发布假设、故障症状
项目分类：

- 静态前端
- 前端 + Python/Flask
- 前端 + Python + SQLite
- 生成/媒体工作流

路径和持久化规范

Python 版本默认 3.10，避免 3.12+（平台默认支持范围外）
优先使用同源 /api/...，除非明确需要跨域部署
Python 后端入口：/api/python-proxy/{projectId}/
SQLite 写入平台托管的 runtime/*.db，不要放在源码旁
运行时输出写入 runtime/，用户生成文件写入 runtime/storage/
不要在项目源码包内预创建 runtime/ 目录模拟平台
不要从前端 HTML/JS/CSS 直接引用 runtime/... 文件
使用 PRAGMA busy_timeout 处理 SQLite 并发写冲突

AI 集成规范

收集提供商、base URL、端点、认证方法、模型、能力类型
不要默认推送平台托管的模型 API
按提供商真实协议族和端点类型路由调用

计费和发布流程

区分项目访问/下载计费与模型 API 计费
只在计费操作成功后扣费，失败不扣费且无预扣费
发布到 VicroCode 时引导使用 /project-upload-website，然后 /project-manage

多语言支持标准

支持 zh-CN、zh-Hant、en 或组合
创建 locales/ 目录，每语言一个 JSON 文件
UI 文案保存在语言文件，不要硬编码
不要在首次加载时执行 AI 翻译，翻译应在上传/编辑/管理流程中完成

UI 默认规范

默认配色方案：docs/VicroCode网站配色统一方案.md
所有提示、通知、错误、确认使用页内叠加组件，不要使用原生浏览器 alert、confirm、prompt
破坏性操作（删除、覆盖、重置、扣费、发布）执行前显示页内确认叠加层

适用边界与注意点

平台限制

Python 版本：3.9、3.10、3.11（默认 3.10，不支持 3.12+）
长超时请求：默认代理读超时 60 秒，需要触发长超时路径
长超时触发方式：

- 请求头 X-Vicro-Long-Timeout: 1
- 查询参数 __vicro_long_timeout=1
- 代理内部路径以 /api/ai/、/api/script/、/api/run-script/、/api/run_script/、/api/video/generate 等开头

长耗时任务（图像/视频生成、OCR、大文件处理）不要仅作为同步路径暴露，应使用长超时触发或异步任务流

安全与计费透明性

涉及硬币计费的部署操作：所有计费逻辑透明且在本地运行，无隐藏费用
不包含自动更新脚本：需要手动通过 git pull 更新

不依赖 SDK

不要要求 SDK 用于普通网站或 AI 应用开发
不要将 proxy-project-by-id 作为 Python 项目默认运行时路径
不要在 VicroCode 交付物中硬编码 localhost 或固定绝对资产路径
不要仅依赖 localStorage 维护核心状态

不做的事情

不要在源码包内创建 runtime/ 目录模拟平台
不要使用 Path(__file__).parent / "runtime" 构建运行时路径
不要从上传的源码包中前端直接引用 runtime/... 文件
不要在上传包中包含本地运行时产物（runtime/、__pycache__/、日志、本地临时输出）
不要让缓存资产自动协调阻塞用户显式清除
不要让生成依赖仅来自早期上传请求的缓存 SQLite 行

验收检查清单

完成时执行具体验收检查：

路由正确性
刷新生存性
运行时文件位置
上传/发布目标
公开应用的语言包和本地化切换行为
AI/模型提供商配置处理
相关时的计费逻辑

WebCraft 网站应用构建器