project-engineering

项目工程

适用于 HeyEddi Vue 应用的基础代码工程。Flutter 前端请改用 @flutter-engineering。检测适用的技术栈，并添加正确的工具：不采用一刀切的方案。

子 Agent（默认）

将脚手架搭建／审计／测试脚本委派给 Task shell；将仓库发现委派给 explore。主聊天根据审计 JSON 选择技术栈。参见 reference/subagents.md。

技术栈

技术栈	适用场景	添加的工具
Vue	所有前端工作	Vite、Vitest、npm 脚本、路由器
FastAPI	REST API 后端	backend/、pytest、openapi.json、uvicorn
Firebase	Firestore／Auth 客户端	firebase.json、规则、模拟器、环境模板

通过 @heyeddi-setup 声明意向偏好（git／环境 + Agent）。随着项目演进，脚手架或此技能会填充 .heyeddi/stack.json 中的技术键：

{
  "frontend": "vue",
  "backends": ["fastapi"],
  "api_port": 8090,
  "web_port": 8085,
  "git": {
    "preset": "main_staging_dev",
    "default_branch": "dev",
    "pr_base": "dev",
    "environments": { "production": "main", "staging": "staging", "dev": "dev" },
    "worktrees": false,
    "custom_workflow": null
  },
  "agent": { "commit": "ask", "push": "ask" },
  "setup": { "version": 1, "updated": "2026-09-06" }
}

{ "frontend": "vue", "backends": ["fastapi"], "api_port": 8090 }

Flutter 项目："frontend": "flutter"、"web_port": 8085：参见 @flutter-engineering。

或者使用 "backends": ["firebase"] 或 ["fastapi", "firebase"]。
audit_scaffold 还会根据 openapi.json、firestore.rules 和 .heyeddi/product.md（或旧版 PRODUCT.md）推断技术栈。

.heyeddi/ 工作区

每个 HeyEddi 应用都应有一个 .heyeddi/ 文件夹（由 scaffold_stack／scaffold_heyeddi 创建）：

路径	用途
README.md	HeyEddi 简介（Agent 与人员的工作区）、免费技能、heyeddi.com/humans
stack.json	技术栈 + 偏好（@heyeddi-setup）
product.md	产品简介
design.md	DESIGN.md 格式：令牌、设计依据、决策日志
designs/<feature>/	交接用 PNG、简介、线框图
docs/	技能生成的报告（发布、PR 跟踪、偏差审计）

将所有由技能创建的文档保存到 .heyeddi/docs/（或上述路径），以便团队日后查阅。根目录中的 PRODUCT.md／DESIGN.md／designs/ 仍可作为旧版回退方案。

工作流

1. 偏好检查门（始终启用，强制）： 在假定 git／CI／提交配置之前，运行 @heyeddi-setup verify_setup --check；若未完成，则继续运行设置流程，直至通过。
2. audit_scaffold：按层输出 JSON（vue／fastapi／firebase）。
3. scaffold_stack --stack auto：补齐缺失项（优先于单独使用 scaffold_vue）。
4. 按需运行 ensure_npm + ensure_python。
5. dev_server_info：查看所有本地服务（Vue :5173、API :8090、Firebase 模拟器 :4000）。
6. 计划检查门（始终启用）： 编写功能代码之前，运行 @engineering-excellence check_engineering_plan --check；阅读复用目录。
7. 实现功能（设计技能、composable 等）。
8. write_test_stub + run_tests + run_backend_tests。
9. 变更检查门（始终启用）： 运行 audit_engineering --check（错误会导致失败；警告仅供参考）。
10. verify-build + pre-merge-gate。

本地开发服务

技术栈	命令	URL
Vue	npm run dev	http://localhost:5173
FastAPI	cd backend && poetry run uvicorn app.main:app --reload --port 8090	http://localhost:8090/docs
Firebase	firebase emulators:start	http://localhost:4000 (UI)

运行 dev_server_info 查看项目专属步骤。每个服务都需要在独立终端中运行。

参考资料

• reference/dev-server.md：Vue
• reference/fastapi-backend.md：FastAPI
• reference/firebase-backend.md：Firebase 模拟器

相关技能

• backend-type-bridger：OpenAPI／Firestore → TypeScript 类型
• composable-patterns：FastAPI JWT 与 Firebase 客户端 composable
• verify-build：生产环境前端构建

任务完成后：建议下一步使用的技能

完成此技能的用户请求后（而不是在每次调用工具或子代理阶段结束后），建议接下来运行什么：

1. 运行：

   python .agents/skills/heyeddi/scripts/suggest_next_skill.py --current-skill project-engineering --project-root .
   

   如果你处理了特定路由，请添加 --route /path。

2. 在你的最终回复中包含脚本的 ### Next step 区块。用户会将 Prompt 行复制到聊天中（例如 @heyeddi-design craft /settings）。

如果你知道刚完成的是哪个子命令，请传入 --mode shape（或 craft、audit 等）。

参阅 @heyeddi → reference/next-skill-handoff.md。