用 Weft 语言构建带类型校验和持久执行的 AI…

当你需要用 Weft 这门 Rust 实现的 AI 编程语言编写、调试或扩展 AI 工作流时使用，涵盖环境搭建、节点编排、人类审批、自定义节点等。

适用场景

解决思路

1. 安装前置依赖：Docker（用于 PostgreSQL）、Node.js；macOS 需执行 `brew install bash` 安装 Bash 4+；Rust、Restate、pnpm 由 `dev.sh` 自动安装。
2. 克隆并配置项目：`git clone https://github.com/WeaveMindAI/weft.git`，`cd weft`，`cp .env.example .env`，然后编辑 `.env` 填入 API keys。
3. 按需在 `.env` 中配置环境变量：`OPENROUTER_API_KEY`（LLM 节点必需）、`TAVILY_API_KEY`（Web Search 节点）、`ELEVENLABS_API_KEY`（Speech-to-Text 节点）、`APOLLO_API_KEY`（Apollo 富化节点）、`DISCORD_BOT_TOKEN`（Discord 节点）；所有 key 启动时可选，缺失只在对应节点执行时报运行时错误。
4. 启动开发环境：终端 1 运行 `./dev.sh server`（PostgreSQL、Restate 及所有服务），终端 2 运行 `./dev.sh dashboard`（SvelteKit，http://localhost:5173），或直接 `./dev.sh all` 同时启动。
5. VS Code 中使用 **Dev Local All** 任务在分屏终端同时启动 server 和 dashboard。
6. 常用开发命令：`./dev.sh server`、`./dev.sh dashboard`、`./dev.sh all`、`./dev.sh extension`（构建浏览器扩展）。
7. 清理命令：`./cleanup.sh`（停止全部并清空 Restate 与数据库）、`./cleanup.sh --no-db`（保留数据库）、`./cleanup.sh --services`（仅停服务）、`./cleanup.sh --db-destroy`（彻底删除 PostgreSQL 容器）。
8. 离线构建与测试：`cargo build` 和 `cargo test` 无需运行 PostgreSQL（使用已提交的 `.sqlx` 快照）。
9. 如需使用会创建 K8s 资源的节点（如 Postgres Database）：下载 kind（`curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.31.0/kind-$(uname -s | tr '[:upper:]' '[:lower:]')-amd64`，`chmod +x ./kind && sudo mv ./kind /usr/local/bin/kind`），然后以 `INFRASTRUCTURE_TARGET=local ./dev.sh server` 启动。
10. 掌握核心概念：Nodes（带类型的计算单元）、Connections（端口间带类型边，编译器校验）、Groups（把一组节点折叠为可复用单节点）、Durable execution（通过 Restate 检查点，长暂停透明）。
11. 使用节点语法：`node_name = NodeType -> (output_port: OutputType) { label: "..." config_key: "value" }`，并用 `node_name.input_port = other_node.output_port` 连接端口。
12. 按需选用内置节点：AI（`LlmConfig`、`LlmInference`）、数据（`Text`、`Number`、`Dict`、`List`、`Pack`/`Unpack`）、流程（`Gate`、`HumanQuery`、`HumanTrigger`）、通信（`Discord`、`Slack`、`Telegram`、`WhatsApp`、`Email`、`X`）、存储（`Postgres`、`Memory`）、富化（`Apollo`、`WebSearch`、`SpeechToText`）、触发器（`Cron`、webhooks、polling）、工具（`Debug`、`Template`、`HTTP`、`Code`（Python 执行））。
13. 模式 1（LLM + 结构化配置）：用 `Text` 提供输入，`WebSearch` 抓取内容，`LlmConfig` 配置 model/systemPrompt/temperature，`LlmInference` 调用，`Debug` 输出，并用端口赋值连接各节点。
14. 模式 2（Human-in-the-Loop 审批）：LLM 起草内容后接 `HumanQuery`（返回 `approved: Boolean, feedback: String`，会无限期暂停直到人类响应），再接 `Gate` 按 `approval.approved` 分支，最后用 `Discord` 等发布。
15. 模式 3（Gate 条件分支）：用 `LlmConfig` + `LlmInference` 做分类（如情感），把分类结果接到 `Gate.condition`，把原值接到 `Gate.value`，再路由到 `Slack` 等下游节点。
16. 模式 4（Cron 触发流水线）：用 `Cron` 节点设置 `expression`（如 `0 8 * * *`），接 `WebSearch` 抓取，接 `LlmConfig` + `LlmInference` 生成摘要，最后用 `Email` 发送。
17. 模式 5（多步研究 Agent）：`Text` 查询 → `WebSearch` → `Apollo` 富化 → 用 `Pack` 把多个来源打包成 `Dict` → `LlmInference` 生成结构化报告 → `Postgres` 存储 → `Slack` 通知。
18. 添加自定义节点：在 `catalog/` 下创建 `catalog/<category>/<node>/` 目录，包含 `backend.rs` 和 `frontend.ts` 两个文件，无需注册，`inventory` crate 会在启动时自动发现。
19. 编写 `backend.rs`：引入 `weft_nodes::prelude::*` 与 serde，定义 `Config`/`Inputs`/`Outputs` 结构体，实现 `Node` trait（关联类型 `Config`、`Inputs`、`Outputs`，以及 `async fn run(config, inputs) -> Result<Outputs, NodeError>`）。
20. 编写 `frontend.ts`：导出 `NodeDefinition`，包含 `type`、`label`、`icon`（Lucide 图标名）、`category`、`inputs`（name/type/required）、`outputs`（name/type）、`config`（name/type/default）。
21. 添加两个文件后运行 `./dev.sh server`，节点立即可用。
22. 理解类型系统：`String`、`Number`、`Boolean`、`Dict`、`List`、`T?`（可空，null 会在图中传播）、`T | U`（联合类型）；编译器在执行前校验所有连接，类型不匹配、缺失必需连接、架构断裂都在编译期捕获。
23. 参考项目布局：`catalog/`（节点定义，唯一真源，含 ai/code/communication/data/enrichment/flow/storage/triggers 子目录）、`crates/`（`weft-core` 类型系统/编译器/执行器/Restate 对象，`weft-nodes` Node trait/注册表/沙箱/运行器，`weft-api` REST API，`weft-orchestrator` Restate 服务 + Axum 项目执行器）、`dashboard/`（SvelteKit + Svelte 5）、`extension/`（WXT 浏览器扩展）、`scripts/catalog-link.sh`（把 catalog 软链到 crates 与 dashboard）。
24. 排障：`./dev.sh server` 立即失败时确认 Docker 运行（`docker ps`）、端口 5432/8080/9070 空闲，并执行 `./cleanup.sh` 后重试。
25. 排障：节点运行时提示 "API key missing" 时，在 `.env` 补上对应 key 并重启服务（`./cleanup.sh --services && ./dev.sh server`）。
26. 排障：类型不匹配编译错误时，检查源节点输出端口类型与目标输入端口类型是否一致；用 `Pack` 把多个值打包成 `Dict` 再传给期望 `Dict` 的节点；可空类型 `T?` 可能传播 null，消费前用 `Gate` 节点守卫。
27. 排障：崩溃后 Restate 状态陈旧时执行 `./cleanup.sh` 清空 Restate journal 与数据库做完整重置。
28. 排障：新节点未出现在 dashboard 时，确认 `catalog/<category>/<node>/` 下 `backend.rs` 与 `frontend.ts` 都存在，手动运行 `./scripts/catalog-link.sh` 后重启服务，并检查服务日志中的 inventory 发现错误。
29. 查阅资源：文档 https://weavemind.ai/docs、入门 https://weavemind.ai/docs/hello-world、语言参考（Nodes/Connections/Types/Groups/Parallel）、仓库根目录的 `DESIGN.md`、`ROADMAP.md`、`CONTRIBUTING.md`、社区 Discord https://discord.com/invite/FGwNu6mDkU、许可证 O'Saasy License（MIT + 禁止竞争性托管服务）https://osaasy.dev。

适用边界 · 注意事项

• 不使用 Weft 语言或不需要其节点编排/持久执行能力时，不必引入本技能。
• 无法运行 Docker、Node.js 或无法安装 Bash 4+ 的环境下无法完成本地开发环境搭建。
• 依赖特定节点（如 Apollo、Discord、ElevenLabs、Tavily）时，若没有对应付费/授权 API key，相关节点只能在运行时失败。