techstack

技术栈

全局规则

• Effect 是 TS 领域和 IO 的骨干——用于结构化错误、DI、资源安全、重试，而不是临时拼凑的 Promise
• 每个服务只使用一种主要服务端技术栈
• 发生冲突时，遵循仓库约定，而非全新项目的默认做法
• 每个边界都要有类型约束——对不可信输入进行运行时解码和校验
• 全新项目安装：注册表发布至少等待七天——参见 domains/security.md
• TS 相对导入（所有应用、包、路由、组件）：始终省略扩展名——from './module'，绝不使用 from './module.js' 或 from './module.ts'
• Effect 仓库中的 Effect 实现深度 → effect-ts 技能

默认方案一览

这些信息足以帮助选择库和方向；实现细节前请阅读链接的文件。

前端

• Web SPA：React + Bun + Tailwind v4 + coss-ui + Effect Atom + TanStack Router
• 在 Effect 程序中处理客户端 IO；状态放在 atom 中——不要在组件里直接使用 fetch
• 移动端：React Native + Expo + NativeWind + React Native Reusables（适合基于文件的路由时再搭配 Expo Router）
• 单体仓库（SPA 前端 + Rust/Python 后端）：Bun workspaces + Vite+ tasks（vp run）；contracts + client + utils + ui-headless + ui + web-app
• 单体仓库（Next.js / Vercel 全栈）：Bun workspaces + Turborepo（turbo run）
• 构建工具链、lint/format、组件安装 → tooling 技能
• → domains/frontend.md

后端

• TS API：在 Bun 上使用 @effect/platform（HttpApi 或 HttpRouter）——不要使用单独的路由框架
• Python API/脚本：FastAPI + Pydantic v2 + uv
• Rust API：Axum + serde + utoipa
• Effect 服务中的 WebSocket：Effect Platform Socket
• 使用 Python 制作原型；使用 Rust 加固并分发
• → domains/backend.md

桌面端

• UI 优先：使用 Electron 打包相同的 Web 技术栈
• 独立进程：通过 WebSocket 在 localhost 上运行配套后端；preload/IPC 仅用于 OS API
• 原生 UI：egui（Rust 工具/模拟）或 Qt 6（工业组件）——如果重点是原生性能，就不要用 Electron
• → domains/desktop.md

Agent

• 在 Vercel 上构建持久化 Agent 应用：Next.js + Eve（文件系统优先）+ json-render（生成式 UI）+ agent-browser + wterm/just-bash + Vercel Workflow/Sandbox/Drop
• 通过 Ollama 使用模型（兼容 OpenAI）：使用 AI SDK openai provider 连接 http://127.0.0.1:11434/v1；云端模型使用 {model}:cloud
• Agent 是 agent/ 下的目录：包含指令、工具、技能、渠道、连接、沙盒、子 Agent、计划任务
• 通过受约束的 json-render 目录实现生成式 UI
• 将不可信代码放入沙盒；对高影响操作使用 needsApproval
• 通过 Vercel Drop 制作原型；转移到 git 中迭代
• → domains/agent.md

静态站点

• 内容丰富的站点（博客、文档、营销站点）：Astro + 静态输出 + Tailwind v4 + Bun
• 使用 Islands 实现客户端交互；除非站点本身就是应用，否则避免使用 SPA 技术栈
• 使用 Content Collections 管理有类型的结构化内容；使用 MDX 实现丰富布局
• → domains/static.md

科学计算

• C++ 成像：CMake + Qt 6 + VTK + ITK
• Rust 数值计算：使用 ndarray 生态系统——不要手动移植 NumPy
• → domains/scientific.md

契约

• TS ↔ TS：在单体仓库中共享 Effect Schema + HttpApi——应用和 API 之间不使用代码生成
• TS ↔ Python：FastAPI OpenAPI → openapi-typescript；WebSocket → AsyncAPI
• TS ↔ Rust：utoipa OpenAPI → openapi-typescript；WebSocket → AsyncAPI 或 asyncapi-rust
• IPC（Electron/Tauri）：Specta 或 pydantic-to-typescript
• → domains/contracts.md

按领域选择

领域	阅读
面向用户的 SPA 或移动端 UI	domains/frontend.md
API、服务、脚本或数据任务	domains/backend.md
桌面应用或原生应用	domains/desktop.md
Agent 应用（Eve + json-render + agent-browser + wterm + Vercel 原语；通过 Ollama（127.0.0.1:11434/v1）提供模型，使用 AI SDK openai + {model}:cloud）	domains/agent.md
静态内容、博客、文档或营销网站	domains/static.md
成像、数值计算或科学计算	domains/scientific.md
UI/服务边界或跨语言类型	domains/contracts.md
供应链、安装加固、发布版本时效门控	domains/security.md
开发工具、lint/format、CI、脚手架	tooling skill

脚手架

全新项目的起始结构位于 tooling/scaffolds/。生成文件前请先阅读 tooling/scaffolds/README.md。

组合方案

• 桌面 UI + 本地后端 → domains/desktop.md + domains/backend.md + domains/contracts.md
• 完整 Agent 技术栈（Next.js + Eve + json-render + agent-browser + wterm + Vercel + 通过 AI SDK openai 使用 Ollama）：domains/agent.md
• 新仓库设置 → 领域文件 + tooling skill（tooling/domains/dev.md、tooling/scaffolds/）+ domains/security.md