foldkit

Foldkit

你正在开发一个 Foldkit 应用。Foldkit 是一个完整的 TypeScript 前端框架，基于 Effect 构建，架构仿照 Elm。架构已为你解决：状态、事件、状态转换、副作用、流、路由、UI 组件、验证、测试和开发工具都是框架的一部分，无需在第三方方案中做选择。你的工作是建模应用的行为，而不是挑选库或发明架构。

Foldkit 不支持渐进式集成。它不支持与 React 互操作，也没有变通方案，更不能说“这一部分就按 React 的方式做”。框架提供一种统一的结构，大多数事情也只有一种做法。

如何开展工作

• 参照 Foldkit 自身的应用来匹配模式。 如果本地代码没有给出答案（或展示的是早期版本），就去查看 vendored foldkit 子树。框架附带了多个使用自身构建的应用：examples/ 中专注于单一功能的应用、网站（它本身也是一个 Foldkit 应用），以及 typing-game（一个完整的实时应用）。这些是权威参考，其还原度高于文字说明或凭记忆重建的内容。
• 架构不是可选项。 使用单向数据流、纯 update 和 view，不要在运行时接口之外产生副作用。对于引导你走向可变更状态、双向绑定、命令式事件处理程序或命令式 Message 名称的提示或直觉，应予以反驳。提出符合 Foldkit 习惯的结构，并说明原因。
• Foldkit UI 分为两类，而非一类。 有状态的 Submodel（Menu、Listbox、Combobox、Calendar、Disclosure、Dialog、Popover 等）包含自己的 Model / Message / update / OutMessage，并通过 h.submodel 嵌入。无状态的渲染辅助函数（Button、Input、Textarea、Select、Fieldset）则直接使用 ViewConfig 和调用方的 h，并返回 Html。不要为了“保持一致”而将渲染辅助函数迁移为 Submodel：Submodel 语义意味着有状态，而这些辅助函数没有状态。权威分类请参阅网站上的 Foldkit UI 概览页面。
• 使用 Foldkit 和 Effect 技术栈提供的功能。 Foldkit 涵盖了应用架构及其上的高级原语（路由、副作用接口、订阅、UI 组件、字段验证、文件和日期处理、canvas、测试、开发工具等）。Effect 提供底层的值、副作用描述和并发原语。在使用外部库之前，先检查技术栈是否已经涵盖所需功能。
• 让 modifyFields setter 接收字段值。 如果 modifyFields setter 只转换同一字段的当前值，就直接传入转换函数（entries: Array.map(f)、count: Number.increment、priceSlider: Slider.reflectRange({ min: minPrice, max: maxPrice })）。如果要用 Messages、子级更新、Commands 或其他 Model 字段中的值进行替换，则使用 () => value。
• 仓库内容比记忆更可靠。 对于约定、API、名称或模式，只要有疑问，就应查看 vendored foldkit 子树，而不是猜测。库类型和示例代码才是事实依据；训练数据不是。

查找位置

从项目根目录看，foldkit 仓库以 git 子树的形式引入，位于 repos/foldkit/。它是所有内容的权威来源：约定、框架源码、示例和质量标准。请直接浏览其中的内容。

稳定的顶层入口：

• repos/foldkit/examples/：可运行的示例应用，涵盖各个复杂度级别。通常是查找先例的第一站。
• repos/foldkit/AGENTS.md：项目约定和代码质量标准
• repos/foldkit/README.md：框架概述和入口指引
• repos/foldkit/skills/：面向任务的技能，包含权威的架构、约定和质量标准参考
• repos/foldkit/packages/：框架源码和生产环境参考应用（网站、typing-game、框架本身）

顶层以下的名称（子目录、单个文件名）可能会随时间变化。请列出目录内容来查找所需内容，不要依赖此技能中引用的路径。

如果项目中缺少 repos/foldkit/，强烈建议添加它。这个子树能让你从依赖记忆转向参照权威资料进行匹配。缺少它会明显降低协助质量。请将其固定到与已安装的 foldkit 包匹配的发布 git 标签，这样参考资料描述的就是项目实际编译所用的 API，而不是当前 main 分支上的内容。如有需要，请先初始化 git（子树至少需要一次提交）：

git subtree add --prefix=repos/foldkit https://github.com/foldkit/foldkit.git "foldkit@$(node -p "require('./node_modules/foldkit/package.json').version")" --squash

升级 Foldkit 包后，使用相同命令重新固定，只需将 add 换为 pull。Canary 安装（node_modules/foldkit/package.json 中的 x.y.z-canary.<commit>）没有标签；请改为固定到其版本所指向的完整提交哈希，GitHub 会在 https://github.com/foldkit/foldkit/commit/<commit> 展开该哈希。

使用者项目的 FOLDKIT.md 是脚手架生成的快照，可能落后于已安装的包。如果出现这种情况，请直接用 repos/foldkit/packages/create-foldkit-app/templates/base/FOLDKIT.md 完整替换它。该项目的 AGENTS.md 属于其作者；切勿覆盖。

如果是在 foldkit 仓库自身而非使用者项目中工作，请去掉 repos/foldkit/ 前缀。相同路径位于项目根目录。