For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /zh/docs/web/first-feature.md (or send Accept: text/markdown).
构建你的第一个功能
从 schema 到上线界面的一次端到端走查。
初学者演练
先决条件：阅读下面的两个初学者指南，完成 Web 本地设置，并在编辑器的根目录中打开此 monorepo。网页设置属于apps/web/.env.local； Next.js不读取根.env。默认fake模式下的/dashboard是无数据库演示； /auth 需要迁移数据库。
简而言之：工作区是一个团队的单独用户、数据和设置。服务器是可信后端；让提供商密钥远离浏览器和电话代码。迁移是创建或更新表的版本化数据库更改。人工智能模型是回答的引擎；型号目录是服务器上可用型号 ID 和价格的列表。提供商是一种外部服务，例如人工智能、电子邮件或计费服务。权利是允许工作区使用某项功能的授权。 Webhook 是一个服务发送到另一个服务的 URL 的消息。
1. 在存储库根目录中打开 VS Code，并要求您的编码代理创建 apps/web/app/reports/page.tsx 和 apps/web/src/reports.ts。为其提供报告字段和允许的角色；需要服务器端成员资格检查和由 workspaceId 过滤的查询。
2. 以登录成员身份打开 /reports，并仅确认工作区的记录出现。
3. 尝试注销并使用第二工作区帐户；如果其中任何一个可以读取记录，请停止并修复服务器检查。
对于自定义代码，请从提供的 prompts/README.md 开始，然后复制最接近的提示：对于应用程序屏幕为 prompts/new-app-screen.md，对于公共页面为 prompts/new-landing-page.md。对于服务器、数据库或提供商工作，请为您的编码代理提供本指南的任务，并要求其读取 AGENTS.md、.ai/PROJECT_CONTEXT.md 和匹配的 .ai/ 镜像；检查此处指定的确切源文件；列出文件并在编辑前进行检查；保留工作区所有权和仅限服务器的机密；并向您展示差异。告诉它您想要的行为、输入和输出字段、允许的角色、预期的成功和错误以及测试帐户、提供程序或设备。使用样本值；永远不要粘贴真正的秘密。
创建路线
在 apps/web/app/ 下面添加一个页面。从仪表板或内容路由开始，以便您重用其会话和活动工作区分辨率。当其文件夹包含page.tsx时，路由存在；使用服务器组件进行受保护的读取。
apps/web/app/reports/page.tsx
apps/web/src/reports.ts
.ai/apps/web/app/reports/page.md
.ai/apps/web/src/reports.md验证访问和恢复
测试匿名访问、有效成员、另一个工作区的成员、已撤销的会话以及所需的角色。通过恢复操作添加空和失败加载状态。将该路线保留在公共站点地图之外，并将其前缀添加到 robots disallows。
为记录建模
每个产品记录都始于数据库 schema。在 packages/db 中新增带 workspaceId 列的表，生成迁移，并编写在读写前先解析工作区的仓储助手。
// packages/db/src/schema.ts
export const ideas = pgTable("idea", {
id: uuid().primaryKey(),
workspaceId: uuid().notNull().references(() => workspaces.id),
title: text().notNull(),
createdAt: timestamp().defaultNow(),
});
corepack pnpm --filter @supastack/db db:generate为操作授权
创建一个依次解析会话、工作区与 entitlement 的服务端 action。用 zod schema 校验输入，通过仓储执行变更，并返回界面可渲染的类型化结果。
顺序很关键：在检查工作区归属之前就写入的变更已经越过了边界。在服务端推导归属 —— 绝不信任浏览器发来的工作区 id。
组装界面
用共享组件与设计令牌搭建页面 —— 套件的 blocks 与 ui-web 原语覆盖了常见模式。处理好加载、错误与空状态；只渲染顺利路径的功能不算完成。