Contextile

Quickstart · 约 5 分钟

5 分钟：让 Agent 给你的页面加一个组件

Contextile 应用由页面组成，页面由相互独立的组件在运行时组装。每个组件 = 一段前端 + 一个专属后端函数，小到能完整装进 coding agent 的上下文窗口—— 所以下面这条路径的主角是 Agent，不是你。

00

前置条件

01

创建并点亮

约 1 分钟
npx create-contextile my-app
cd my-app && npm run dev

浏览器自动打开 http://127.0.0.1:4242/p/demo：两张卡片（问候卡 + 活动统计） 已经在页面上。这是一个真实的组件化页面——试着改一下 components/hello-card/frontend/index.tsx 并保存，页面会自动重新发布并刷新。

02

把需求交给 Agent

约 1 分钟

在项目目录里打开 Claude Code（或 Cursor），批准 Contextile MCP 服务器 （只弹一次窗），然后直接说：

“Add a weather card component to the demo page.”

03

看 Agent 干完整个流程

约 3 分钟

Agent 会依次：scaffold 出组件骨架 → 写前端和函数代码 → deploy_component 部署（构建 → 发资产 → 函数上线 → 页面出新版本，每一步状态确定）→ render_page_screenshot 用真实浏览器渲染页面、把截图放进对话里自检 → 不满意就自己迭代。

刷新页面（或等它自动刷新）：天气组件出现。

检查点

时间你应该看到
T+1mindemo 页在浏览器里点亮（两张卡片）
T+2minAgent 开始工作（工具调用滚动）
T+5min新组件上页，对话里有截图证据

卡住了？

先跑逃生口：

npx contextile doctor

它逐项检查 Node、项目文件、dev 服务器、模拟器浏览器、MCP 接线、spec 版本——每个失败项都带修复方法。三个高频问题：

  1. 端口被占：contextile dev 会自动顺延端口，以终端横幅里的 URL 为准； 旧进程可用 doctor 定位后停掉。
  2. 没有浏览器（截图不可用）：npx playwright install chromium 一定能修； 装了桌面版 Chrome 也行。
  3. Agent 看不到 Contextile 工具：MCP 按项目目录注册（.mcp.json 在项目 里）。确认 agent 会话是在项目目录里打开的、弹窗时批准过，npm install 之后重启一次 agent 会话。

下一步