learn-rat-stack

用途：trace 一个能力在 Effect、XState、五种投影、CLI 和 Alchemy 之间的流转方式，理解该技术栈的组织结构。\n\n主要能力：以 inspectFile 这样一个能力为线索，说明契约（定义名称、输入、输出、失败与元数据）与处理器（实现动作）的绑定关系；service 是单一职责的命名接口，machine 定义状态与允许的状态迁移事件，projection 从能力构建可调用接口。同一处理器供五种接口复用：CLI、HTTP、MCP、code mode、RPC，其中 RPC 服务浏览器客户端，code mode 让智能体在一个程序中组合调用。涉及组件还包括 Schema（运行时校验）、Layer（构建服务并注入依赖）、XState 的 Effect bridge、TypeScript 7 与 Effect 诊断、Oxlint/Oxfmt/Vitest/lefthook 组成的检查围栏、pnpm 与 Turborepo、以及 Alchemy 声明云资源。\n\n使用方式：先阅读 Effect 基础，再按定义契约、绑定处理器、把文件操作放入 service、为生命周期命名状态、投影已注册动作、连接 CLI、用 Alchemy Stack 组合云资源的顺序追踪。托管内容工具可调用 POST /api/execute 进入 code mode，示例程序先 search 再 read，read 使用 search 返回的确切 ID；可直接用 curl 以 JSON code 字符串发送，例如：curl --request POST 'https://ratstack.sh/api/execute' --header 'content-type: application/json' --data '{"code":"const found = await tools.search({ query: \"cartridges\", limit: 1 }); const page = await tools.read({ id: found.matches[0].id }); return { title: page.title, id: page.id };"}'。修改前应阅读 AGENTS.md（版本锁定、边界与围栏）、VISION.md，以及计划改动的包；Effect 或 XState 相关改动前阅读 node_modules/effect/AGENTS.md 和仓库规则列出的锁定源码。完成后运行完整门禁：pnpm turbo run check test build，修复失败并保持围栏完整，部署检查单独进行。\n\n适用场景：学习或采用该技术栈、理解单一能力多接口投影、按仓库规则实施与验证改动。\n\n限制：资料未说明收费、授权、可用平台版本等细节；教程强调以仓库规则和锁定代码为准，示例可能过时；CLI 中 Node 文件检查与部署的云应用是分开运行的。