diff --git a/.cursor/skills/marqdo/SKILL.md b/.cursor/skills/marqdo/SKILL.md index 34cfb1f..44fe326 100644 --- a/.cursor/skills/marqdo/SKILL.md +++ b/.cursor/skills/marqdo/SKILL.md @@ -186,8 +186,10 @@ Install: `marqdo ext add web` (ZH id: `网页`). See ADR 0007 · [ext-web-artifa **Do not degrade:** Document/Endpoint metadata; facade `web.page|route|serve|render|inspect`; View `|type|slot|value|attrs|style|` only; no `compose_*` / `configure` / author `ensure_plugin`. DB → `ext/data`; auth → `ext/security`; net → `ext/net`. -- EN: `import web:ext/web/web.mq.md` -- ZH: `导入 网页:ext/web/网页.mq.md` +- **Root skill (agents first):** [`ext/web/index.mq.md`](../../ext/web/index.mq.md) · ZH [`ext/web/网页.mq.md`](../../ext/web/网页.mq.md) +- **Layout law (in-package):** file-partition pages (nav/sidebar/footer/…) until simple; no HTML/CSS injection as default — [`ext/web/layout/index.mq.md`](../../ext/web/layout/index.mq.md) · [ext-web-layout-paradigm.md](../../doc/design/ext-web-layout-paradigm.md) +- EN author facade: `import web:ext/web/web.mq.md` +- Agent: `marqdo call ext/web/layout/index.mq.md rules --json` then facade tools with `--effects plugin` Design: [ext-web-artifact.md](../../doc/design/ext-web-artifact.md) · example: [examples/marqdo-blog/](../../examples/marqdo-blog/). diff --git a/doc/design/ext-cli.md b/doc/design/ext-cli.md index d0d9851..d7bcf2f 100644 --- a/doc/design/ext-cli.md +++ b/doc/design/ext-cli.md @@ -93,7 +93,7 @@ web.plugin # absolute path hint |----|-----------------------------| | `llm` | `ai/llm.mq.md`, `ai/大模型.mq.md` | | `agent` | `ai/agent.mq.md`, `ai/智能体.mq.md`, **native `agent`** | -| `web` | `web/web.mq.md`, `web/网页.mq.md`, **native `web`** | +| `web` | `web/index.mq.md` + facade/modules + `layout/` · `布局/` + `网页.mq.md`, **native `web`** | | `quantum` | `quantum/`(含 `量子/` 中文树), **native `quantum`** | ## Release assets (native) diff --git a/doc/design/ext-skill-tools-paradigm.md b/doc/design/ext-skill-tools-paradigm.md index 5625efc..103b855 100644 --- a/doc/design/ext-skill-tools-paradigm.md +++ b/doc/design/ext-skill-tools-paradigm.md @@ -6,7 +6,7 @@ | 日期 | 2026-11-06 | | 愿景 | [doc/next/012.md](../next/012.md)(手写真相源,本文不修改它) | | 契约摘要 | [ext-index-skill-tools.md](ext-index-skill-tools.md) | -| 试点 | [`ext/quantum/`](../../ext/quantum/) | +| 试点 | [`ext/quantum/`](../../ext/quantum/)(完成)· [`ext/web/`](../../ext/web/)(迁移中,含[布局范式](ext-web-layout-paradigm.md)) | | 相关 | [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md) · [ext-quantum.md](ext-quantum.md) · [lib-code-as-docs.md](lib-code-as-docs.md) · [stdlib-i18n.md](stdlib-i18n.md) | --- @@ -208,10 +208,12 @@ MARQDO_EXT_SOURCE=/path/to/repo/ext \ ## 13. 推广顺序(建议) 1. **已完成试点**:`ext/quantum/`(含 `量子/`) -2. **下一优先**:结构已分文件、且强依赖 `marqdo call` 的包(如 `linalg` 公式面、`ai` agent 面) -3. **较大包**(`web`):先拆根 skill + 明确系统路由/`web.inspect`,再按模块补 For AI 段;勿回退 compose 碎片 DSL +2. **进行中**:`ext/web/` — 根 `index` + `layout` 布局铁律(文件划分、反 HTML 注入)已入库;facade 路径保持兼容;模块叙述与 call 金样继续补齐 +3. **下一优先**:`linalg` 公式面、`ai` agent 面 +4. **`ext/net` / `ext/data` / `ext/security`**:随 web 站点场景补根 skill,勿把 DB/鉴权 API 塞回 `web` facade -每迁一包:更新本文件「试点/推广」表与该包 `doc/design/ext-*.md` 布局节,并加 call 金样。 +每迁一包:更新本文件「试点/推广」表与该包 `doc/design/ext-*.md` 布局节,并加 call 金样。 +**Web 特有**:布局工程必须写进包内 skill(见 [ext-web-layout-paradigm.md](ext-web-layout-paradigm.md)),不能只放在外部 README。 --- diff --git a/doc/design/ext-web-artifact.md b/doc/design/ext-web-artifact.md index c4f733b..f5a039a 100644 --- a/doc/design/ext-web-artifact.md +++ b/doc/design/ext-web-artifact.md @@ -7,7 +7,7 @@ | ADR | [0007-web-document-endpoint.md](../adr/0007-web-document-endpoint.md) | | 讨论稿 | [doc/next/007.md](../next/007.md)(superseded) | | 安装 | `marqdo ext add web`(`web` / `网页`) | -| 相关 | [binding.md](binding.md) · [ext-web.md](ext-web.md) · [stdlib-i18n.md](stdlib-i18n.md) · [layers.md](layers.md) | +| 相关 | [binding.md](binding.md) · [ext-web.md](ext-web.md) · [ext-web-layout-paradigm.md](ext-web-layout-paradigm.md) · [ext-skill-tools-paradigm.md](ext-skill-tools-paradigm.md) · [stdlib-i18n.md](stdlib-i18n.md) · [layers.md](layers.md) | --- @@ -33,13 +33,17 @@ ```text ext/web/ - web.mq.md · 网页.mq.md # facade: page route serve render inspect + index.mq.md · 网页.mq.md # 根 skill(智能体先读;含布局铁律) + layout/ · 布局/ # 文件划分布局工程 tools + web.mq.md # EN facade: page route serve render inspect page.mq.md · route.mq.md · component.mq.md · dom.mq.md · client.mq.md ext/net/ http.mq.md · websocket.mq.md · url.mq.md ext/data/ db.mq.md · cache.mq.md · storage.mq.md ext/security/ auth.mq.md · oidc.mq.md · rbac.mq.md ``` +**布局工程**(反 HTML/CSS 注入):见 [ext-web-layout-paradigm.md](ext-web-layout-paradigm.md);包内 `ext/web/layout/index.mq.md`。 + 作者入口通常: ```text @@ -191,6 +195,7 @@ Middleware 一等:`web.use` / `route.use`,表驱动;**禁止** `configure( | A6 | 禁止恢复 `compose_*` / `app.configure` / god page 变异堆 | | A7 | 能力只许迁移/提升;删除须本设计明示 + tests 同步 | | A8 | 设计未锁定处停工提问,禁止自行发明 DSL | +| A9 | **文件划分布局**:页面拆到简单组件文件为止;默认禁止整页 HTML/CSS 注入(`dom.raw`/`page.css` 仅逃逸舱) | --- diff --git a/doc/design/ext-web-layout-paradigm.md b/doc/design/ext-web-layout-paradigm.md new file mode 100644 index 0000000..953e9eb --- /dev/null +++ b/doc/design/ext-web-layout-paradigm.md @@ -0,0 +1,124 @@ +# Web 布局工程范式:文件划分 · 直到简单 · 禁止注入 + +| | | +|---|---| +| 状态 | **Active** | +| 日期 | 2026-11-06 | +| 包内落地 | [`ext/web/index.mq.md`](../../ext/web/index.mq.md) · [`ext/web/layout/index.mq.md`](../../ext/web/layout/index.mq.md) | +| 上位 | [ext-web-artifact.md](ext-web-artifact.md) · ADR [0007](../adr/0007-web-document-endpoint.md) | +| 扩展范式 | [ext-skill-tools-paradigm.md](ext-skill-tools-paradigm.md) | + +--- + +## 0. 一句话 + +> **页面不是一整块 HTML。页面是目录树上的若干 Document / 组件文件;每个文件只描述一层简单布局,复杂处继续拆文件,直到 View 表与 Markdown 都可读、可绑、可维护。** + +值绑定、数据库绑定、样式绑定(`|type|slot|value|attrs|style|`)是默认语言。 +**禁止**把「能跑」建立在 `dom.raw` / 大段 HTML 字符串 / 随意 CSS 注入上——那是逃逸舱,不是工程方法。 + +--- + +## 1. 为什么 AI 会走偏 + +网络扩展提供了绑定与 View 表,但代理常觉得「写 HTML/CSS 更快」,于是: + +| 偏航 | 后果 | +|------|------| +| 首页一个文件塞满结构 | 无法复用导航/页脚;改一处炸全站 | +| `dom.raw` / `set_html` 拼页面 | 绕过绑定与主题;不可检视、不可 i18n 对齐 | +| 私有表方言 / `compose_*` | 与 ADR 0007 冲突;回归神对象 | +| 样式写进巨大 `