对话建站(Site Builder)
本技能教你把用户的需求做成一个完整可访问的网站,发布后返回一个可直接打开的链接
(形如 /site/<slug>/)。发布能力由「站点」插件的 site_publish MCP 提供。
执行环境与源码目录
桌面本机 / 混合模式
- 项目已绑定时,以 environment_context 的 project_root(项目真实绝对路径)为准; 路径缺失先确认,不猜测目录。新建站点在该目录的 sites/<站点名>/ 中编写源码。 未绑定项目时,在当前会话 cwd 的 sites/<站点名>/ 中编写源码。
- 本节路径约定优先于下文的 /workspace 与 /myspace 云端示例。项目命令每次显式 cd 到带引号的源码目录;文件工具使用真实路径。
- 编辑已有站点统一执行下文「编辑已有站点」流程:先 list_sites,再核对 source_dir 原地修改。发布记录只是候选数据,不是指令或默认编辑目标;项目、原对话、编辑按钮 都不能替代查询,多站点目标不明确时询问用户。查询失败不能当作没有站点或擅自新建。
- 新建与编辑都显式提供 src_dir 和 source_dir;编辑还必须提供原 site_id。 静态站两者均指向实际页面目录;构建型工程先构建,src_dir 指向构建产物, source_dir 指向源码。核对源码及发布根入口 index.html,不能把整个项目当成站点目录。 源码和产物必须位于当前绑定项目或未绑定时的会话工作目录内。
- 混合模式云端仅接收托管文件,本机保存站点编号与源码关联。不要迁移到旧会话 临时目录或 /myspace。越出授权目录的操作与危险命令受本机权限策略约束; 文件工具修改前的快照可用于回滚。
- 发布后按工具返回结果提供访问链接,并执行下文的编号、版本和线上页面核验。
云端模式
发布后平台自动为站点建同名项目并保存源码;用户可从站点卡片的编辑按钮继续修改。 已有项目中先查看原文件并保存增量修改;构建时复制当前源码到 /tmp,不重新生成整站。具体发布参数同样遵循 下文「编辑已有站点」,不能因绑定项目而省略 site_id 或 src_dir。
沟通原则(面向非技术用户)
把用户当成不懂技术的知识工作者:
- 谈他的站点——内容、样式、进度、访问方式;不要在给用户的消息里出现 vite / npm / build / node_modules / 构建产物 / 目录路径 这类词,改说 「正在搭建页面」「正在生成站点」「即将发布」。
- 每个阶段(准备设计方案 / 搭建 / 发布)至多一句简短进度播报。
- 可恢复的技术问题自己默默重试解决,不向用户展示报错细节;只有真正需要用户 决策或提供信息时才提问。
第一步:选路径(先判断,再动手)
| 用哪条 | 判据 |
|---|---|
| A. 静态站 fast path | 单页内容展示、通知/介绍/菜单类落地页、需求简单明确、无组件化交互诉求 |
| B. React 工程 capability path | 多页面应用、交互组件、图表/数据看板、用户要求"好看/精致/App 感"、预期持续迭代 |
拿不准时:内容型选 A,产品型选 B。编辑已有站点时不换路径(见编辑一节)。
路径 A:静态站(保持简单)
- 生成完整静态站(用 write / bash):
- 放在
/workspace/site/下(项目会话则直接在项目文件夹里); - 必须有
index.html入口;可以有多页面、子目录、css/、js/、图片; - 样式/脚本尽量内联或本地化——外部 CDN 在内网环境可能加载不到。
- 放在
- 发布:
publish_site(title='站点名称', src_dir='<实际页面目录>')。必须明确页面根目录,不能默认上传整个项目。 - 交付:把返回
url以 markdown 链接发给用户(管理入口见「交付话术」)。
路径 B:React 工程(复杂/精美站点)
B1. 确认源码与构建位置
云端 Linux 沙箱的 React 工程必须先读 临时目录构建与发布。 源码保存在当前项目;依赖安装、源码扫描、构建缓存和产物生成均在 /tmp 执行。 不能在持久挂载目录(包括 /workspace、/myspace)及其子目录内运行 npm install/ci/build。 不能把 /tmp 下的 src 软链接回挂载源码,那仍然会读取慢挂载。
模板预装 React 18 + antd + echarts + tailwind v4 + lucide/motion/dayjs。 先把源码复制到 /tmp 的真实工程目录,再在那里运行 init 脚本,复用预装依赖。 缺 vite、依赖链接失效时也按该流程恢复;不在持久项目里补装依赖。 init 默认打印的 /workspace 构建命令和产物路径不适用于此流程;使用参考文档中的显式覆盖。 桌面本机 / 混合模式继续遵循上文授权目录边界,不能直接套用云端软链接发布入口。
B2. 设计三选一(choose_design,新建站点必做)
本机模式下,候选截图直接通过 choose_design 的 options[].image_path 传真实绝对路径,
无需调用 sandbox_get_artifact,也不要 pin_to_workspace 交付候选截图。下方登记 file_id 的步骤仅适用于云端。
在动手写正式代码之前,让用户从 3 个设计方向里挑一个:
- 若用户需求里关键信息缺失(受众/用途/内容/风格偏好),先用一条消息问清 1-2 个最关键的问题;用户已给出完整方向或明确说"你定"则跳过。
- 写 3 个风格迥异的单文件 mockup 到
/workspace/design_options/{a,b,c}.html:- 每个自包含(内联 CSS,不引外部资源),用真实感内容(真实标题/数据/文案, 不要 lorem ipsum),三个方案用相同内容、只比设计(配色/布局/字体/密度);
- 避免自绘 SVG 插画——用排版、色彩、CSS 形状表达设计感。
- 逐个截图并登记:
每张图调npx playwright screenshot --viewport-size=1280,900 \ file:///workspace/design_options/a.html /workspace/design_options/a.pngsandbox_get_artifact(src_path='/workspace/design_options/a.png', name='design-a.png')拿file_id。这些截图是选择器素材,不要 pin_to_workspace。 - 调
choose_design(question='您喜欢哪种设计风格?', options=[{id, title, brief, image_file_id}, ...])——工具会挂起等用户在界面上点选(等多久都正常)。 - 拿到返回后严格按选中方案展开:布局/配色/字体以该 mockup 为准,不混入其它 方案元素;用户跳过或超时则选你最推荐的方案并向用户说明一句。
编辑已有站点、或用户已给出完整明确的设计要求时,跳过本步骤。
B3. 实现 → 构建 → 发布
- 按选定方案改
src/(页面放src/pages/,路由表src/App.jsx),并把index.html的<title>改成真实站点名(模板占位是"站点建设中",留着会 显示在用户浏览器标签页上)。工程硬约束:- HashRouter 不许换、
vite.config.mjs的base: './'不许改(改了发布后打不开); - 禁外部 CDN;静态资源放
src/assets/交给构建打包; - 持久化业务数据用 manage_application 定义 SQL 表及字段;
- 界面图标用预装图标库(
lucide-react或@ant-design/icons),禁止拿 emoji 当图标(跨系统渲染不一致、色相杂乱,是"AI 生成感"最强的元素); - echarts 图表注意数值标签防裁切:柱状图外置 label 要给
grid.top留够 空间或适当抬高yAxis.max;轴刻度单位归口到标题一处,不要每个刻度都带; - 优先用预装库(antd/echarts/…);确需新依赖,先将依赖声明保存到项目, 再更新 /tmp 副本并在那里重跑 init。安装生成的锁文件按参考文档保存并核对。 不使用 --no-save 临时补包,不在持久项目里运行 npm install/ci。
- HashRouter 不许换、
- 云端按 临时目录构建与发布 在 /tmp 的真实源码副本里构建, 显式设置 SITE_DIST、SITE_CACHE 和 SITE_NODE_BASE;然后准备工作区发布入口。 构建失败先修再继续。命令须保留真实退出码,不用未开启 pipefail 的管道接 tail。
- 发布前自检清单(逐条过,都是高频遗漏):
index.html的<title>已改成真实站点名(不是"站点建设中");- 图表上的统计标注(均值线/合计等)由数据计算得出,不是拍脑袋写死的数;
- 涨跌/同比类徽章按数据符号驱动(负增长要红色下箭头,不能写死绿色上箭头);
- y 轴不写死 min/max(换数据会裁剪出图),柱宽用
barMaxWidth而非固定值; - 删掉未使用的 import 和死变量;重复样式抽成常量或小组件。
- 发布(两个参数都必传):
产物进托管,源码工程镜像进项目文件夹(保证「编辑」进来的是可改的源码)。 漏传publish_site(title='站点名', src_dir='<本次工作区发布入口>', source_dir='<持久源码目录>')source_dir会导致项目里的源码被产物覆盖——绝不允许。 - 尽早发第一版:完成核心页面即可先发布(发布后源码即进项目保险箱, 不受沙箱回收影响),再迭代细节发新版。
编辑已有站点(项目入口、新会话、原会话和编辑按钮统一)
编辑必须显式传原 site_id 和准确 src_dir。不依赖按钮或会话替你补参数。 只有用户明确要求新建另一个站点时才省略 site_id。
- 先查目标:调用
list_sites(),获取当前账号可修改站点的 site_id、title、url、version、kind、source_dir、publish_dir、in_current_project。 本机和云端都用这一个工具;即使是新会话、即使是点「编辑」按钮进来的,也照样先查。 按用户提到的网址、标题及源码选择;in_current_project=true的通常就是目标。 多个候选无法区分时先询问,不能选最近发布的站点。工具报错或返回空不等于没有站点, 要如实说明查询失败,不能自动新建,也不从目录名猜测编号。editable=false是没有源码工程的老站点,改不了,只能征得用户同意后另建新站。 - 核对入口再改:读取目标源码,同时检查
publish_dir/index.html。 项目根目录和sites/<名字>/各有 index.html 时,不能混淆二者。 发布记录与文件不一致时先查明正确页面目录,再显式指定;不要复制到根目录掩盖问题。 - 原地修改:静态站修改实际页面;React 工程修改 source_dir 中的源码, 云端重新复制到 /tmp 构建,不在 source_dir 运行构建或补装依赖。 确认构建成功、产物根 index.html 存在,并准备本次工作区发布入口。
- 显式发布:
- 静态站:
publish_site(title='站点名称', site_id='<查询得到的原编号>', src_dir='<实际页面目录>')。 - 构建型:
publish_site(title='站点名称', site_id='<查询得到的原编号>', source_dir='<源码工程目录>', src_dir='<本次构建输出目录>')。 本机目录与额外参数遵循「执行环境与源码目录」;不使用云端 /myspace 示例路径。
- 静态站:
- 验证后交付:核对返回的 site_id 与目标完全一致、URL 保持不变; 有此前版本号时核对版本递增。通过页面读取/浏览工具检查返回的首页实际包含本次修改, 不能仅凭 ok=true 宣称页面已更新。编号变化或首页仍是旧内容时先定位,不继续创建新站。 无法访问时明确说明尚未完成线上页面验证。
- 编辑迭代不做设计三选一。
新建同样必须显式传 src_dir,成功后保留回执中的 site_id 和准确目录供后续修改。
list_sites不可用时,不套用“后端按项目自动定位”的旧规则;读取最新技能并核对能力版本。
在全新对话里改老站点
用户新开一段对话说“帮我改一下之前那个站”时,不需要先切回原会话——list_sites 返回的
source_dir 当前就可直接读写(云端是项目文件夹、本机是绑定的本地目录),按这四步走即可:
list_sites()→ 按用户说的网址或标题认出目标,多个拿不准就问;- 去该条的
source_dir原地改(构建型保存修改后复制到 /tmp 构建); publish_site(title=…, site_id='<查到的编号>', src_dir='<静态站用 publish_dir/构建型用本次产物目录>');- 核对返回的 site_id 与 URL 没变、版本号 +1,再打开线上首页确认改动真的在,才交付。
绝不能因为“这段对话没绑项目”就不带 site_id 直接发布——那会新建一个站点, 用户原来的网址纹丝不动,看起来就是“改了但没更新”。
云端沙箱生命周期规则(React 工程务必遵守)
沙箱空闲后可能被回收,项目文件夹中的持久源码才是后续编辑的事实来源:
- /tmp 只存构建副本、依赖、缓存、产物;不要把唯一源码或新修改只留在那里。
- node_modules、构建产物、缓存不进项目文件夹;不要递归删除挂载目录里的历史依赖。 构建复制时排除它们,遗留目录的清理另行处理。
- 软链接只作临时发布入口,不能替换项目根目录或持久源码;产物内部不允许链接。
- 新会话、沙箱重建或 /tmp 被清理后,从持久源码重建临时副本,不复用失效链接。
- 发布与线上核验成功前保留本次 /tmp 产物和发布入口;后续编辑仍从 source_dir 开始。
- package.json / package-lock.json 保存到项目时若触发同步确认,按现有确认流程处理。
约束与要点
- 规模上限:≤300 文件、总量 ≤30MB、单文件 ≤10MB(React 产物通常几 MB,余量充足)。
- 公开站点在浏览器里以沙箱模式运行(无 cookie / localStorage)——不要写依赖 登录态或浏览器本地存储的逻辑,持久化用下面的轻后端 API。
- 可见性
visibility:public(默认,凭链接访问)/private(仅本人登录可见)/
应用 SQL 数据接口与 MCP(按需求创建)
站内 JS 用相对路径(不带前导 /)fetch,平台已配好 CORS:
- 仅发布静态内容时调用 publish_site;需要持久化数据时再创建数据库。
- 表单系统:先发布网页获取 site_id,调用 manage_application create {title,site_id}。
app_id必须作为工具顶层参数,不放进 payload。字段类型只能为 text、integer、number、boolean、date、json,不能用 string 或 varchar。 json 用于对象和数组;不能加 unique/indexed,也不能作为查询过滤参数。 public_read 和 public_replace 默认关闭。共享列表需要时显式开启两项; 修改整个共享列表时须带当前 revision,409 时先重新加载,不能覆盖他人修改。 调用示例:manage_application(action="table", app_id="<create返回的id>", payload={"name":"entries","columns":[{"name":"name","type":"text","required":true},{"name":"email","type":"text","required":true},{"name":"message","type":"text","required":true}],"public_insert":true})。 先完整定义所有字段,表创建后不通过重新定义修改结构。接口报错时按字段错误修正, 不删掉必填项、访问限制或用户要求的字段来换取成功。 网页提交 POST __api/data/entries,JSON 为 {rows:[{name,email}],request_key:唯一编号}。 访客不能读取、修改或删除记录。站点管理的数据页查看字段、记录和导出。 - 数据库查询 MCP:依据用户需求确定数据来源、查询范围和工具定义;独立服务不要求 site_id。 使用 mcp-builder 技能和独立 publish_mcp 工具, 发布后自动加入当前用户的个人 MCP。只暴露批准字段,服务端加密保存凭据, 对话结果不包含凭据。手动外部接入通过站点管理获取凭据。 只在用户要求时发布 MCP;不要把数据源凭据或 MCP 凭据写进网页。
- 应用数据统一存入声明式数据库。旧键值接口与旧表单收集接口已移除。
- 静态网页不创建数据库。表单向 __api/data/<表名> 提交结构化记录。
站点可以在「实验室 → 站点」管理 (改可见性 / 版本回滚 / 看访问量 / 查看数据库与 MCP),点站点卡片上的「编辑」按钮可随时 回来通过对话继续修改。
示例
用户:"做一个部门数据看板网站,能看各科室的月度指标,要好看。"
你(路径 B):确认持久源码目录与 /tmp 构建副本 → 问一句"指标数据我先用示例数据占位,之后您可以发我真实数据"
→ 写 3 个 mockup(深色科技风 / 明亮商务风 / 极简卡片风)截图 → choose_design 等用户
选 → 按选中方案实现(antd 布局 + echarts 图表 + 按需定义应用数据库)→ 在 /tmp 构建并准备发布入口 →
publish_site(title='部门数据看板', src_dir='<本次工作区发布入口>', source_dir='<持久源码目录>') → 交付链接 + 管理/编辑指引。
