@vobs/cli 1.8.5 → 1.8.6

package/src/commands/agent-doc.test.ts

@@ -0,0 +1,151 @@
+/*
+ * `vobs agent-doc` —— 把框架契约**生成**到项目里，供任何 LLM / agent 读取。
+ *
+ * ## 为什么是"生成"而不是"手写"
+ *
+ * 契约随框架演进（1.8.0 加 `Show`/`ClientOnly`、1.8.3 加 `on()`/`VOBS_C106`、
+ * 1.8.4 加 `VOBS_C107`、1.8.5 改 fix 文案）。手写的话每个项目一份副本，**必然漂移**。
+ * 生成则与版本绑定 —— 升级框架后重新生成即可。
+ *
+ * ## 要锁住的四条行为
+ *
+ * 1. **标记块**：只替换 `vobs:begin`/`vobs:end` 之间，块外是项目自有约定
+ * 2. **不覆盖手写的 `AGENTS.md`**：没有标记块时**追加**生成块，原有内容全保留
+ *    （丢掉别人的规则比不生成更糟）
+ * 3. **`CLAUDE.md` 只写一行 `@AGENTS.md`**：内容只有一份，避免两份副本漂移
+ * 4. **`--check`**：不一致时 exit 1，可进 CI —— 把"文档漂移"从"靠人记得"变成"机器拦"
+ */
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { agentDocCommand } from './agent-doc'
+
+const created: string[] = []
+function makeProject(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'vobs-agent-doc-'))
+  created.push(dir)
+  return dir
+}
+afterEach(() => {
+  while (created.length > 0) rmSync(created.pop()!, { recursive: true, force: true })
+})
+
+/** 跑一次命令并吃掉它的 stdout（测试只关心退出码与文件）。 */
+async function run(dir: string, options: Record<string, boolean>): Promise<void> {
+  const write = vi.spyOn(process.stdout, 'write').mockImplementation(() => true)
+  const log = vi.spyOn(console, 'log').mockImplementation(() => undefined)
+  vi.spyOn(console, 'error').mockImplementation(() => undefined)
+  try {
+    await agentDocCommand({ dir, ...options })
+  } finally {
+    write.mockRestore(); log.mockRestore(); vi.restoreAllMocks()
+  }
+}
+
+describe('vobs agent-doc', () => {
+  it('--write 生成 AGENTS.md 与 CLAUDE.md，契约要点都在', async () => {
+    const dir = makeProject()
+    await run(dir, { write: true })
+
+    const agents = readFileSync(join(dir, 'AGENTS.md'), 'utf8')
+    // 契约必须覆盖这轮落地的关键约束 —— 缺一条就等于没同步
+    for (const key of ['run-once', 'RouterView', 'on(deps', 'VOBS_C107', 'VOBS_C210', 'parseNumber', 'ClientOnly']) {
+      expect(agents, `契约里缺 ${key}`).toContain(key)
+    }
+    // 标记块存在（--check 靠它比对）
+    expect(agents).toContain('vobs:begin')
+    expect(agents).toContain('vobs:end')
+    // 内容只有一份：CLAUDE.md 是指针，不是副本
+    expect(readFileSync(join(dir, 'CLAUDE.md'), 'utf8').trim()).toBe('@AGENTS.md')
+  })
+
+  it('**手写的 AGENTS.md 不被覆盖** —— 生成块追加在后', async () => {
+    const dir = makeProject()
+    writeFileSync(join(dir, 'AGENTS.md'), '# 我的项目约定\n- 目录：src/pages\n', 'utf8')
+    await run(dir, { write: true })
+
+    const agents = readFileSync(join(dir, 'AGENTS.md'), 'utf8')
+    expect(agents, '原有的项目约定被覆盖了').toContain('我的项目约定')
+    expect(agents).toContain('目录：src/pages')
+    expect(agents).toContain('vobs:begin')
+  })
+
+  it('再次 --write 只替换契约块，块外的新内容保留', async () => {
+    const dir = makeProject()
+    await run(dir, { write: true })
+    // 用户在块外补自己的内容
+    const first = readFileSync(join(dir, 'AGENTS.md'), 'utf8')
+    writeFileSync(join(dir, 'AGENTS.md'), `${first}\n- 我的新增规则\n`, 'utf8')
+
+    await run(dir, { write: true })
+    const second = readFileSync(join(dir, 'AGENTS.md'), 'utf8')
+    expect(second, '块外的用户内容被清掉了').toContain('我的新增规则')
+    // 契约块仍然只有一份（不会重复追加）
+    expect(second.match(/vobs:begin/gu)?.length).toBe(1)
+  })
+
+  it('--check：未生成时 exit 1，生成后通过', async () => {
+    const dir = makeProject()
+    process.exitCode = 0
+    await run(dir, { check: true })
+    expect(process.exitCode, '没生成却通过了检查').toBe(1)
+
+    process.exitCode = 0
+    await run(dir, { write: true })
+    await run(dir, { check: true })
+    expect(process.exitCode, '生成之后仍然检查失败').toBe(0)
+    process.exitCode = 0
+  })
+
+  it('--check：契约块被手改后报不一致', async () => {
+    const dir = makeProject()
+    await run(dir, { write: true })
+    const agents = readFileSync(join(dir, 'AGENTS.md'), 'utf8')
+    // 手改块内内容 —— 模拟框架升级后项目里那份没同步
+    writeFileSync(join(dir, 'AGENTS.md'), agents.replace('run-once', 'run-once-手改过'), 'utf8')
+
+    process.exitCode = 0
+    await run(dir, { check: true })
+    expect(process.exitCode, '块被改动了却通过检查').toBe(1)
+    process.exitCode = 0
+  })
+
+  it('--check：CLAUDE.md 被改成副本而非指针时也有提示', async () => {
+    const dir = makeProject()
+    await run(dir, { write: true })
+    writeFileSync(join(dir, 'CLAUDE.md'), '# 我把内容抄了一份\n', 'utf8')
+
+    process.exitCode = 0
+    await run(dir, { check: true })
+    expect(process.exitCode, 'CLAUDE.md 没指向 AGENTS.md 却通过了').toBe(1)
+    process.exitCode = 0
+  })
+
+  it('--body 只输出契约正文（无标记块）', async () => {
+    const dir = makeProject()
+    let captured = ''
+    const write = vi.spyOn(process.stdout, 'write').mockImplementation((chunk: unknown) => {
+      captured += String(chunk)
+      return true
+    })
+    try {
+      await agentDocCommand({ dir, body: true })
+    } finally {
+      write.mockRestore()
+    }
+    expect(captured).toContain('run-once')
+    expect(captured, '--body 不该带标记块').not.toContain('vobs:begin')
+  })
+
+  it('不加任何开关时打到 stdout、不写文件', async () => {
+    const dir = makeProject()
+    const write = vi.spyOn(process.stdout, 'write').mockImplementation(() => true)
+    try {
+      await agentDocCommand({ dir })
+    } finally {
+      write.mockRestore()
+    }
+    expect(existsSync(join(dir, 'AGENTS.md')), '没加 --write 却写了文件').toBe(false)
+  })
+})

package/src/commands/agent-doc.ts

@@ -0,0 +1,142 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { AGENT_CONTRACT } from '../templates/agent-contract.js'
+
+/**
+ * `vobs agent-doc` —— 把框架契约**生成**到当前项目，供任何 LLM / agent 读取。
+ *
+ * ## 为什么是"生成"而不是"手写"
+ *
+ * 契约随框架演进（1.8.0 加 `Show`/`ClientOnly`、1.8.3 加 `on()` 与 `VOBS_C106`、
+ * 1.8.4 加 `VOBS_C107`、1.8.5 改 fix 文案）。手写的话，每个项目一份副本，
+ * **必然各自漂移**；而且写的人未必知道最新契约。
+ *
+ * 生成则天然与版本绑定：`@vobs/cli@1.8.x` 产出 1.8.x 的契约。
+ *
+ * ## 设计要点
+ *
+ * 1. **标记块**：只替换 `<!-- vobs:begin -->` 与 `<!-- vobs:end -->` 之间的内容，
+ *    块外的**项目自有约定原样保留** —— 重新生成不会覆盖你自己的东西。
+ * 2. **`--check`**：校验项目里那份是否与当前框架版本一致，不一致 exit 1。
+ *    可以进 CI —— 这样"文档漂移"从"靠人记得"变成"机器拦"。
+ * 3. **`CLAUDE.md` 只写一行 `@AGENTS.md`**：内容只有一份，避免两份副本漂移。
+ * 4. 由**框架**产出，不由用户手抄；工具无关（内容里不提任何特定 LLM）。
+ */
+
+const BEGIN = '<!-- vobs:begin 由 `vobs agent-doc --write` 生成，请勿手改 -->'
+const END = '<!-- vobs:end -->'
+
+export interface AgentDocOptions {
+  /** 目标目录，默认当前工作目录。 */
+  readonly dir?: string
+  /** 写入文件（否则打到 stdout）。 */
+  readonly write?: boolean
+  /** 校验项目里那份是否与当前框架版本一致；不一致 exit 1。 */
+  readonly check?: boolean
+  /** 只输出框架契约正文（不含标记块外的说明）。 */
+  readonly body?: boolean
+}
+
+/** 契约正文内联在 `templates/agent-contract.ts`（见那里的注释：读文件在全量测试下会失败）。 */
+function readContract(): string {
+  return AGENT_CONTRACT.trim()
+}
+
+/** 把契约包进标记块 —— 块外是项目自己的内容，重新生成不会动它。 */
+function buildAgentsDoc(contract: string): string {
+  return [
+    BEGIN,
+    '',
+    contract,
+    '',
+    END,
+    '',
+    '<!-- 以下是本项目的自有约定，`vobs agent-doc --write` 不会覆盖。 -->',
+    '',
+    '## 本项目约定',
+    '',
+    '（在这里写你自己的目录结构、命名、业务流程等规则。）',
+    ''
+  ].join('\n')
+}
+
+/** 取出文件里的标记块内容（没有标记块时返回 null）。 */
+function extractBlock(text: string): string | null {
+  const start = text.indexOf(BEGIN)
+  const end = text.indexOf(END)
+  if (start < 0 || end < 0 || end < start) return null
+  return text.slice(start, end + END.length)
+}
+
+/**
+ * 合并：保留块外内容，只替换块。
+ *
+ * 没有标记块的既有 `AGENTS.md`（用户手写的）**不直接覆盖** ——
+ * 把生成块**追加在后**，用户原有内容全部保留。丢掉别人的规则比不生成更糟。
+ */
+function mergeAgentsDoc(existing: string | null, generated: string): string {
+  if (existing === null) return generated
+  const block = extractBlock(generated)
+  if (block === null) return generated
+  if (extractBlock(existing) === null) return `${existing.trimEnd()}\n\n${block}\n`
+  return existing.replace(extractBlock(existing)!, block)
+}
+
+export async function agentDocCommand(options: AgentDocOptions = {}): Promise<void> {
+  const root = resolve(options.dir ?? process.cwd())
+  const contract = readContract()
+
+  if (options.body === true) {
+    process.stdout.write(`${contract}\n`)
+    return
+  }
+
+  const generated = buildAgentsDoc(contract)
+  const agentsPath = resolve(root, 'AGENTS.md')
+  const claudePath = resolve(root, 'CLAUDE.md')
+  // 内容只有一份：CLAUDE.md 只做入口，避免两份副本漂移
+  const claudeDoc = '@AGENTS.md\n'
+
+  if (options.check === true) {
+    const problems: string[] = []
+    if (!existsSync(agentsPath)) {
+      problems.push('AGENTS.md 不存在 —— 跑 `vobs agent-doc --write` 生成')
+    } else {
+      const existing = readFileSync(agentsPath, 'utf8')
+      const block = extractBlock(existing)
+      if (block === null) {
+        problems.push('AGENTS.md 里找不到 vobs 标记块 —— 跑 `vobs agent-doc --write` 补上')
+      } else if (block !== extractBlock(generated)) {
+        problems.push('AGENTS.md 的 vobs 契约块与当前框架版本不一致 —— 跑 `vobs agent-doc --write` 同步')
+      }
+    }
+    if (!existsSync(claudePath)) {
+      problems.push('CLAUDE.md 不存在 —— 跑 `vobs agent-doc --write` 生成（内容只需一行 `@AGENTS.md`）')
+    } else if (!readFileSync(claudePath, 'utf8').includes('@AGENTS.md')) {
+      problems.push('CLAUDE.md 没有指向 @AGENTS.md')
+    }
+
+    if (problems.length > 0) {
+      console.error('[agent-doc] 契约与框架版本不同步：')
+      for (const problem of problems) console.error(`  - ${problem}`)
+      process.exitCode = 1
+      return
+    }
+    console.log('[agent-doc] 契约与当前框架版本一致 ✓')
+    return
+  }
+
+  if (options.write !== true) {
+    process.stdout.write(generated)
+    return
+  }
+
+  const existingAgents = existsSync(agentsPath) ? readFileSync(agentsPath, 'utf8') : null
+  writeFileSync(agentsPath, mergeAgentsDoc(existingAgents, generated), 'utf8')
+  writeFileSync(claudePath, claudeDoc, 'utf8')
+  console.log(`[agent-doc] 已写入 ${agentsPath}`)
+  console.log(`[agent-doc] 已写入 ${claudePath}（内容为 @AGENTS.md）`)
+  if (existingAgents !== null && extractBlock(existingAgents) === null) {
+    console.log('[agent-doc] 你原有的 AGENTS.md 内容已保留，vobs 契约块追加在后。')
+  }
+}

package/src/templates/agent-contract.md

@@ -0,0 +1,107 @@
+# vobs 框架契约（写代码前必读）
+
+vobs 是**编译型 / 细粒度 / 响应式**框架，与 React 的心智模型有几处**根本不同**。
+下面的每一条都来自真实事故，**违反时通常编译通过、运行期才错**。
+
+> 本文档由 `vobs agent-doc` 从框架版本生成 —— 不要手改生成的块。
+> 每条后面括号里是**违反时框架会报的诊断码**。
+
+## 一、组件体只执行一次（run-once）
+
+**组件函数体只在创建时跑一次**，之后只有 JSX 里订阅的位置更新。
+
+- ❌ `const filtered = list.value.filter(...)` —— 一次快照，之后永不更新
+- ✅ 派生放进 JSX：`<div>{list.value.filter(...).map(render)}</div>`
+- ❌ 组件体里取快照给回调用：`const v = name.value; onClick={() => save(v)}`
+- ✅ 回调内重读：`onClick={() => save(name.value)}`
+- 动态 props 用 getter 形态，不要传求值后的值
+
+## 二、条件渲染：**不要在组件体里 `return` 分支**（`VOBS_C107` / `VOBS_C104`）
+
+组件体里读信号的 `return` 在挂载时固化，**三种写法坏得一模一样**：
+
+```tsx
+return cond.value ? <A/> : <B/>        // ❌ 冻结
+if (cond.value) return <A/>            // ❌ 冻结
+return cond.value ? <A/> : null        // ❌ 冻结
+```
+
+顶层 `return` 处**没有 parent/anchor**，所以两支都是 JSX 也一样不会重分支。
+
+| 场景 | 用什么 |
+|---|---|
+| **路由分支** | **`<RouterView/>`**（声明式，内部 `insertDynamic` + `resetKey`） |
+| 保留挂载、只切显隐 | **`<Show when={cond}>`**（切 `hidden` + `inert`，焦点/滚动/内部状态不丢） |
+| 只切类名 | `class="base" classList={{ 'is-on': cond.value }}` |
+| 普通条件渲染 | 放进 **JSX 子节点位置**：`<div>{cond.value ? <A/> : <B/>}</div>` |
+
+## 三、effect 里不要写自己读过的信号（`VOBS_C210` / `VOBS_C211`）
+
+**依赖是自动收集的**：effect 运行期间读到的**任何**信号都会变成依赖。
+
+- ❌ `effect(() => { count.value++ })` —— 读+写同一个信号 = 自订阅循环
+- ❌ `effect(() => { if (session.value) void sync() })` —— **「只调了个函数」不等于没依赖**：
+  被调函数在**首个 `await` 之前**的代码是**同步执行**的，它读的信号算在 effect 头上
+- ✅ 只想声明依赖：**`effect(on(deps, () => { … }))`** —— 回调在 untrack 作用域里跑，
+  它调用的函数碰什么信号都不会反向订阅
+- ✅ 派生值用 `memo`，不要"读 A 写 B"
+- 兜底才是 `untrack(() => { X.value = next })`
+
+**别在 effect 里调 async 函数**（`VOBS_C106`）：`effect` 不等它，
+且首个 `await` 之前的部分是同步的。异步取数用 **`@vobs/resource`**。
+
+## 四、客户端副作用与 SSR
+
+- 定时器 / 监听 / `matchMedia` / `localStorage` → **`onMount` 启动、`onDestroy` 清理**
+  （**不要手写 `typeof window` 守卫**）
+- **渲染输出本身**依赖浏览器（窗口尺寸 / `localStorage` 回填 / `Date.now` / 随机值）
+  → **`<ClientOnly fallback={…}>`**（首轮两侧都渲染 fallback，水合对得上）
+- 模块顶层**禁止** JSX（`VOBS_C105`）：import 求值早于渲染器安装
+
+## 五、列表与数据
+
+- **数组更新必须换引用**：`list.value = [...list.value, item]`；
+  原地 `push` / 改字段**不触发更新**
+- JSX **子节点位置**只放四种形态：组件标签 / 元素 / 两分支三元 / `.map()`
+- 数据结构里**只存纯描述**（字符串/样式/结构字段），**节点对象别进数据常量**
+  （SSG 序列化会炸，产物出现 `[object Xxx]` 时框架会直接报错）
+
+## 六、输入
+
+- **数字输入走 `parseNumber`**（`<Field type="number">` 已内置）：
+  空串 / 非法 / 超界**不提交**，保持原值
+  —— `Number('') === 0` 会把输入清成 0 并沿联动链路清零兄弟维度
+- `<select>` 的 value 直接绑，**不要写 ref 兜底**（1.5.1+ 已修时序）
+
+## 七、图标与 SVG
+
+- **SVG 直接写 JSX**（`<svg><path/></svg>`，1.7.4+ 按 namespace 创建与水合）
+- 图标要**登记进白名单**；查表 miss 时 `@vobs/icon-core` 会警告点名（但仍应登记）
+
+## 八、提交前自测
+
+```bash
+pnpm run check:source            # = vobs check，全仓一次列出全部诊断
+pnpm run check:runtime           # 真实浏览器逐路由跑护栏（需 Chrome）
+pnpm run check:runtime:interact  # 再点所有按钮、触发所有输入
+```
+
+`vite build` **会**打印编译期警告（`C104`/`C105`/`C106`/`C107`），但只覆盖它编译到的文件；
+`check:source` 才是全仓入口。
+
+---
+
+## 一句话速记
+
+| 主题 | 一句话 |
+|---|---|
+| 组件体 | 只跑一次，派生进 JSX |
+| 回调 | 触发时重读 `.value` |
+| 条件渲染 | 路由用 `RouterView`，显隐用 `Show`，别在组件体 return 分支 |
+| effect | 别写自己读的信号，用 `on(deps, fn)` |
+| async | 别塞进 effect，用 `@vobs/resource` |
+| 客户端 | `onMount`/`onDestroy`/`ClientOnly`，别手写 `typeof window` |
+| 列表 | 换引用 |
+| 数字 | `parseNumber` |
+| SVG | 直接写 |
+| 自测 | `check:source` + `check:runtime` |

package/src/templates/agent-contract.ts

@@ -0,0 +1,119 @@
+/**
+ * vobs 框架契约正文 —— `vobs agent-doc` 的输出来源。
+ *
+ * 为什么是 TS 模块而不是 .md 文件：读文件要靠 `import.meta.url` 解析相对路径，
+ * 而**全量测试时 vitest 会转换模块**，`import.meta.url` 指向虚拟路径，
+ * `new URL('../../src/templates/…')` 就找不到文件（实测：单独跑 8 条全过、
+ * 全量跑 8 条全红）。内联成字符串**免疫打包与转换**，也省掉发布时拷模板。
+ *
+ * 内容由 `packages/cli/src/templates/agent-contract.md` 生成（保留 .md 作可读源）；
+ * 改契约请改 .md 后重新生成，或直接改这里的字符串。
+ */
+export const AGENT_CONTRACT = `# vobs 框架契约（写代码前必读）
+
+vobs 是**编译型 / 细粒度 / 响应式**框架，与 React 的心智模型有几处**根本不同**。
+下面的每一条都来自真实事故，**违反时通常编译通过、运行期才错**。
+
+> 本文档由 \`vobs agent-doc\` 从框架版本生成 —— 不要手改生成的块。
+> 每条后面括号里是**违反时框架会报的诊断码**。
+
+## 一、组件体只执行一次（run-once）
+
+**组件函数体只在创建时跑一次**，之后只有 JSX 里订阅的位置更新。
+
+- ❌ \`const filtered = list.value.filter(...)\` —— 一次快照，之后永不更新
+- ✅ 派生放进 JSX：\`<div>{list.value.filter(...).map(render)}</div>\`
+- ❌ 组件体里取快照给回调用：\`const v = name.value; onClick={() => save(v)}\`
+- ✅ 回调内重读：\`onClick={() => save(name.value)}\`
+- 动态 props 用 getter 形态，不要传求值后的值
+
+## 二、条件渲染：**不要在组件体里 \`return\` 分支**（\`VOBS_C107\` / \`VOBS_C104\`）
+
+组件体里读信号的 \`return\` 在挂载时固化，**三种写法坏得一模一样**：
+
+\`\`\`tsx
+return cond.value ? <A/> : <B/>        // ❌ 冻结
+if (cond.value) return <A/>            // ❌ 冻结
+return cond.value ? <A/> : null        // ❌ 冻结
+\`\`\`
+
+顶层 \`return\` 处**没有 parent/anchor**，所以两支都是 JSX 也一样不会重分支。
+
+| 场景 | 用什么 |
+|---|---|
+| **路由分支** | **\`<RouterView/>\`**（声明式，内部 \`insertDynamic\` + \`resetKey\`） |
+| 保留挂载、只切显隐 | **\`<Show when={cond}>\`**（切 \`hidden\` + \`inert\`，焦点/滚动/内部状态不丢） |
+| 只切类名 | \`class="base" classList={{ 'is-on': cond.value }}\` |
+| 普通条件渲染 | 放进 **JSX 子节点位置**：\`<div>{cond.value ? <A/> : <B/>}</div>\` |
+
+## 三、effect 里不要写自己读过的信号（\`VOBS_C210\` / \`VOBS_C211\`）
+
+**依赖是自动收集的**：effect 运行期间读到的**任何**信号都会变成依赖。
+
+- ❌ \`effect(() => { count.value++ })\` —— 读+写同一个信号 = 自订阅循环
+- ❌ \`effect(() => { if (session.value) void sync() })\` —— **「只调了个函数」不等于没依赖**：
+  被调函数在**首个 \`await\` 之前**的代码是**同步执行**的，它读的信号算在 effect 头上
+- ✅ 只想声明依赖：**\`effect(on(deps, () => { … }))\`** —— 回调在 untrack 作用域里跑，
+  它调用的函数碰什么信号都不会反向订阅
+- ✅ 派生值用 \`memo\`，不要"读 A 写 B"
+- 兜底才是 \`untrack(() => { X.value = next })\`
+
+**别在 effect 里调 async 函数**（\`VOBS_C106\`）：\`effect\` 不等它，
+且首个 \`await\` 之前的部分是同步的。异步取数用 **\`@vobs/resource\`**。
+
+## 四、客户端副作用与 SSR
+
+- 定时器 / 监听 / \`matchMedia\` / \`localStorage\` → **\`onMount\` 启动、\`onDestroy\` 清理**
+  （**不要手写 \`typeof window\` 守卫**）
+- **渲染输出本身**依赖浏览器（窗口尺寸 / \`localStorage\` 回填 / \`Date.now\` / 随机值）
+  → **\`<ClientOnly fallback={…}>\`**（首轮两侧都渲染 fallback，水合对得上）
+- 模块顶层**禁止** JSX（\`VOBS_C105\`）：import 求值早于渲染器安装
+
+## 五、列表与数据
+
+- **数组更新必须换引用**：\`list.value = [...list.value, item]\`；
+  原地 \`push\` / 改字段**不触发更新**
+- JSX **子节点位置**只放四种形态：组件标签 / 元素 / 两分支三元 / \`.map()\`
+- 数据结构里**只存纯描述**（字符串/样式/结构字段），**节点对象别进数据常量**
+  （SSG 序列化会炸，产物出现 \`[object Xxx]\` 时框架会直接报错）
+
+## 六、输入
+
+- **数字输入走 \`parseNumber\`**（\`<Field type="number">\` 已内置）：
+  空串 / 非法 / 超界**不提交**，保持原值
+  —— \`Number('') === 0\` 会把输入清成 0 并沿联动链路清零兄弟维度
+- \`<select>\` 的 value 直接绑，**不要写 ref 兜底**（1.5.1+ 已修时序）
+
+## 七、图标与 SVG
+
+- **SVG 直接写 JSX**（\`<svg><path/></svg>\`，1.7.4+ 按 namespace 创建与水合）
+- 图标要**登记进白名单**；查表 miss 时 \`@vobs/icon-core\` 会警告点名（但仍应登记）
+
+## 八、提交前自测
+
+\`\`\`bash
+pnpm run check:source            # = vobs check，全仓一次列出全部诊断
+pnpm run check:runtime           # 真实浏览器逐路由跑护栏（需 Chrome）
+pnpm run check:runtime:interact  # 再点所有按钮、触发所有输入
+\`\`\`
+
+\`vite build\` **会**打印编译期警告（\`C104\`/\`C105\`/\`C106\`/\`C107\`），但只覆盖它编译到的文件；
+\`check:source\` 才是全仓入口。
+
+---
+
+## 一句话速记
+
+| 主题 | 一句话 |
+|---|---|
+| 组件体 | 只跑一次，派生进 JSX |
+| 回调 | 触发时重读 \`.value\` |
+| 条件渲染 | 路由用 \`RouterView\`，显隐用 \`Show\`，别在组件体 return 分支 |
+| effect | 别写自己读的信号，用 \`on(deps, fn)\` |
+| async | 别塞进 effect，用 \`@vobs/resource\` |
+| 客户端 | \`onMount\`/\`onDestroy\`/\`ClientOnly\`，别手写 \`typeof window\` |
+| 列表 | 换引用 |
+| 数字 | \`parseNumber\` |
+| SVG | 直接写 |
+| 自测 | \`check:source\` + \`check:runtime\` |
+`