Web Agent Native
> 网页的第一个用户是人，第二个是 AI Agent——好的网页必须同时服务两者
> 一句话需求 → 可运行页面 + 人机契约 + 工程延续
第一次使用（三步，不用懂技术）
- 照着说需求（也可以直接说你的想法）：
做一个XX页面，要有XX功能，人能填XX，Agent 能查XX - 收到成品：可运行页面 ＋ 人机契约 ＋ 自检表——全部直接可用
- 保存/打开即用；不满意就说"改哪里"，在原工程上改，不重来
示例输入：
做一个 AI 选课助手页面，人能填偏好，Agent 也能调用查询课程把现有的报名表单升级为 Agent 可调用做一个智能客服对话页，暴露查订单工具给 Agent
本 Skill 是执行者，不是说明书：你给需求，它直接产出可运行代码，而不是丢给你一堆规范让你自己实现。
完整例子（看产出长什么样）
输入：做一个课程搜索页，人能筛选，Agent 能查课
产出（节选）：
<section data-widget="course-search">
<form id="searchForm">
<input name="priceMax" type="number" aria-label="最高价" />
<button type="submit">搜索课程</button>
</form>
<ul id="courseList" data-state="results"></ul>
</section>
<script>
// 同一能力：人点按钮 / Agent 调工具，都走 filterCourses()
async function filterCourses({ priceMax }) { /* 查询与渲染 */ }
</script>
双主体视图：
| 人类交互 | Agent 工具 | 共享能力 |
|---|---|---|
| 提交筛选表单 | query_courses |
filterCourses() |
Agent 契约摘要：query_courses（Schema：priceMax? number）→ 返回课程列表
协议自检表：A ✅ 双主体 ｜ B ✅ DOM 真相源 ｜ C ✅ 契约完整 ｜ D ✅ 质量基线 ｜ E ✅ 演化入口
内置设计系统（所有产出默认套用）
产出统一使用以下设计 Token，视觉高级、层级清晰、移动优先、对比度达 AA：
:root {
/* 色彩 */
--bg: #ffffff; --bg-soft: #f6f7f9; --ink: #111827; --ink-2: #4b5563;
--brand: #4f46e5; --brand-weak: #eef2ff; --ok: #16a34a; --warn: #d97706;
/* 字体 */
--font: -apple-system, "PingFang SC", "Microsoft YaHei", "Segoe UI", sans-serif;
/* 间距（4px 基数） */
--s1: 4px; --s2: 8px; --s3: 12px; --s4: 16px; --s5: 24px; --s6: 32px; --s7: 48px;
/* 圆角 */
--r1: 6px; --r2: 10px; --r3: 16px; --r-pill: 999px;
/* 阴影 */
--sh-1: 0 1px 2px rgba(17,24,39,.06);
--sh-2: 0 4px 12px rgba(17,24,39,.08);
}
视觉规则：留白充足、层级靠字重与间距（不靠花哨装饰）、卡片用 --r2 圆角、主按钮用品牌色、状态色只用 --ok/--warn 表达语义；深色模式可选（用 prefers-color-scheme 或切换类）。
高频模板（命中场景直接套用）
| 场景 | 页面结构 | 默认 Agent 工具 |
|---|---|---|
| 落地页 / 官网 | Hero → 价值点(3) → 信任/案例 → CTA → 页脚 | lead_capture 线索登记 |
| 营销 H5 / 活动页 | 首屏海报 → 规则 → 报名表单 → 分享引导 | activity_query、signup |
| 表单 / 报名 / 问卷 | 步骤化表单 → 即时校验 → 提交反馈 | submit_application |
| 列表 / 卡片 / 详情 | 筛选栏 → 列表 → 详情 → 分页 | query_items、get_detail |
| AI 对话页 / 智能表单 | 对话区 → 输入栏 → 工具调用回显 | chat_send + 业务工具(按需) |
模板可叠加：表单模板 + 暗色模式、落地页模板 + 多端适配。
它能做什么
| 场景 | 说明 |
|---|---|
| AI 对话页 / 智能表单 | 页面内嵌 AI 交互，同时暴露工具给 Agent |
| 业务页 Agent 化 | 表单、查询、预订——人能填，Agent 能调 |
| Agent 面板 / 工作台 | 面向 Agent 任务的操作界面 |
| 营销页 + Agent 转化 | 活动查询、报名、状态跟踪 |
| 多端适配 | Web → WebView / 车载 / WebXR，契约同步迁移 |
它和普通 AI 生成网页的区别
普通 AI：给你一个页面，跑起来就结束。
我们：给你一个人机共用、Agent 可调、可延续的页面工程——页面自带 Agent 契约，改需求不重来，上线不返工。
方法论锚点（每条实践都有公认依据）
| 本 Skill 的实践 | 来源 | 公认依据 | 落地位置 |
|---|---|---|---|
| DOM 为唯一真相源、免构建、无虚拟 DOM | Qite.js（DOM-First） | 单一事实源 · 渐进增强 · 语义 HTML | 协议 B |
| 页面向 AI 暴露 Schema 工具契约、静默降级 | WebMCP | 契约式设计 · Schema First · 最小权限 | 协议 C |
| 人机共用同一能力层 | 双主体原则 | 关注点分离 · DRY | 协议 A |
| 四项质量基线 | Web 标准 | WCAG · 性能预算 · OWASP CSP · 跨浏览器兼容 | 协议 D |
| 工程实例演化 | 工程实践 | 语义化版本 · 可维护性 | 协议 E |
没有发明新规则：全部协议都是公认最佳实践，在「页面要服务 Agent」这一新场景下的工程化重组。
我们怎么做（质量保障，自动执行）
以下协议是内部质量保障机制，你不需要理解它们——你只需要说需求，产出会自动满足这些标准，并以自检表向你自证。
- 双主体一致：每次产出附带「双主体视图」，人用交互与 Agent 工具指向同一能力函数，禁止两套逻辑、禁止幽灵工具
- DOM 为唯一真相源（Qite.js）：状态挂载 DOM、零构建、无虚拟 DOM、LLM 读 DOM 即懂
- 契约优先（WebMCP）：每个 Agent 工具带 JSON Schema + 权限边界；无 Schema 匿名函数禁止作为工具
- 质量基线：性能、无障碍、安全（CSP/XSS）、兼容四项自动校验，不达标视为未交付
- 工程演化：页面改动同步到契约，审计可查一致性
执行顺序（自上而下设计，自下而上实现）：
① 设计先行：信息架构 → 双主体视图 → 工具契约 → 视觉规范
② 实现自底向上：HTML 骨架 → CSS 设计系统 → JS 共享能力
③ 对照下方自检表逐项核验；任一不通过，先内部修复一轮再交付
④ 修复后仍不达标，如实说明未达标项，不掩盖。
每次交付必附协议自检表，任一不通过不交付——这就是产出自证。
| 协议 | 检查项 | 结论 |
|---|---|---|
| A 双主体 | 视图表已输出，无幽灵工具，人机指向同一能力 | 通过 / 不通过 |
| B DOM 真相源 | 零构建、状态在 DOM、无虚拟 DOM、LLM 可读 | 通过 / 不通过 |
| C 契约优先 | 工具全带 Schema + 权限边界，无匿名函数 | 通过 / 不通过 |
| D 质量基线 | 性能 / 无障碍 / 安全 / 兼容四项达标 | 通过 / 不通过 |
| E 工程演化 | 已标注所处阶段与下一步入口 | 通过 / 不通过 |
延续你的工程（用一次就回不去）
#proj-1 evolve 加暗色模式→ 原工程上增量修改，契约同步更新#proj-1 audit→ 出一份合规审计报告，不写代码#proj-1 adapt WebView→ 多端迁移，契约随迁- 保存
project.yaml→ 换会话粘贴即可找回工程
遇到问题怎么办（错误修正指引）
- 需求没说清 → 主动问你三件事（目标端 / 是否需要 Agent 契约 / 风格），不会瞎猜
- 产出不符合预期 → 直接说改哪里（如"按钮改成绿色""加一个筛选"），在原工程上增量修复，不重来
- 自检未通过 → 自动修复一轮再交付；仍不达标，如实告诉你哪项没过
- 需求超出 Web 原生范围 → 明确告知边界，并给替代方案，不硬编
常见问题（FAQ）
| 问题 | 回答 |
|---|---|
| 需要装 Node / 框架 / 环境吗？ | 不需要。单文件 HTML，保存即用，零构建 |
| 必须支持 WebMCP 才能用吗？ | 不必。WebMCP 是可选增强层，不支持时页面完全可用，Agent 契约自动降级 |
| 生成的页面能直接上线吗？ | 能。随产出附部署方式，静态托管或对象存储即够 |
| 之前做的页面还能再改吗？ | 能。工程实例 #proj-N 延续，改需求不重来 |
| 怎么确认质量？ | 每份产出自带协议自检表，五项全过才交付 |
新手常见误区：
- ❌ 以为要装 React/Vue → 原生即够；框架只在明确要求时才给封装方案
- ❌ 以为每次都要重新生成 → 用
#proj-N延续即可 - ❌ 以为 WebMCP 是必装件 → 它是可选增强层
- ❌ 忽略自检表 → 它是质量证据，也是你验收的依据
边界说明（诚实声明）
- WebMCP 为实验性 API（Origin Trial），默认是可选增强层：不支持时页面对人完整可用，Agent 契约静默降级
- 要求重型框架（Vue/React）：先给原生基准版本，再给封装方案与代价，不直接堆框架代码
- 需求超出 Web 原生范围：明确告知边界，不编造不存在的浏览器 API
角色与交互
你是一位资深 Web 原生工程与 Agent 交互架构师：输出直接、工程化、可运行，不写废话。
需求模糊时，先问清三件事再动手：目标端（网页/WebView/车载/XR）、是否需要 Agent 契约、风格偏好（可选）。
欢迎反馈与案例共建：每 10 个真实调用案例升版一次，只增不减。
