diff --git a/package.json b/package.json
index 588346fc0f..acfe588c50 100644
--- a/package.json
+++ b/package.json
@@ -61,10 +61,11 @@
     "verify-persistence-catalog": "tsx scripts/gen-persistence-catalog.ts --check",
     "gen-module-graph": "tsx scripts/gen-module-graph.ts",
     "verify-module-graph": "tsx scripts/gen-module-graph.ts --check",
+    "verify-website-yaml": "tsx scripts/verify-website-yaml.ts",
     "website:dev": "pnpm --filter @deepseek-ai/website run dev",
     "website:build": "pnpm --filter @deepseek-ai/website run build",
     "constraints": "tsx scripts/check-workspace-constraints.ts",
-    "doc-sync": "pnpm run doc-typecheck && pnpm run verify-cordis-catalog && pnpm run verify-cordis-api && pnpm run verify-export-jsdoc && pnpm run verify-tool-catalog && pnpm run verify-config-catalog && pnpm run verify-persistence-catalog && pnpm run verify-doc-graphs && pnpm run verify-md-wrap && pnpm run verify-md-links && pnpm run verify-doc-refs && pnpm run verify-package-paths && pnpm run verify-mermaid && pnpm run verify-rfc-classification && pnpm run verify-rfc-format && pnpm run verify-type-equiv && pnpm run verify-translation-pairing && pnpm run verify-doc-budgets",
+    "doc-sync": "pnpm run doc-typecheck && pnpm run verify-cordis-catalog && pnpm run verify-cordis-api && pnpm run verify-export-jsdoc && pnpm run verify-tool-catalog && pnpm run verify-config-catalog && pnpm run verify-persistence-catalog && pnpm run verify-doc-graphs && pnpm run verify-md-wrap && pnpm run verify-md-links && pnpm run verify-doc-refs && pnpm run verify-package-paths && pnpm run verify-mermaid && pnpm run verify-rfc-classification && pnpm run verify-rfc-format && pnpm run verify-type-equiv && pnpm run verify-translation-pairing && pnpm run verify-doc-budgets && pnpm run verify-website-yaml",
     "hygiene": "pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-node-next-types",
     "demo:echo": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/echo-agent/cordis.yml",
     "demo:repl": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/coding-agent/cordis.yml",
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index 958ddad0ae..6384697650 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -274,6 +274,7 @@ function docSyncLeafGates(): Gate[] {
     pnpmScript('type-equivalence', 'verify-type-equiv', { label: 'type equivalence' }),
     pnpmScript('translation-pairing', 'verify-translation-pairing', { label: 'translation pairing' }),
     pnpmScript('doc-budgets', 'verify-doc-budgets', { label: 'doc budgets' }),
+    pnpmScript('website-yaml', 'verify-website-yaml', { label: 'website yaml' }),
   ]
 }
 
diff --git a/scripts/verify-website-yaml.ts b/scripts/verify-website-yaml.ts
new file mode 100644
index 0000000000..809af247e2
--- /dev/null
+++ b/scripts/verify-website-yaml.ts
@@ -0,0 +1,284 @@
+/**
+ * Doc-sync gate: verify the fenced ```yaml examples in the website against
+ * the loader and the workspace truth. A `cordis.yml` example that names a
+ * plugin that does not exist, or passes a config key the plugin never
+ * declared, is worse than no example — it fails silently for the reader.
+ *
+ * Scope: `website/zh-CN/**​/*.md`, EXCLUDING `website/zh-CN/api/**` (the api
+ * pages are generator-owned — their yaml examples are verified at generation
+ * time by a later stream, not re-checked here). Blocks opt out with
+ * ` ```yaml ignore-check ` (same philosophy as doc-typecheck's opt-out: the
+ * count is reported, an unchecked block is a visible decision, not a silent
+ * hole — placeholder plugin names in tutorials are the legitimate case).
+ *
+ * Each checked block is parsed with the loader's REAL schema —
+ * `JSON_SCHEMA` extended with the `!!js` scalar type exactly as
+ * vendor/include/src/index.ts declares it — so `!!js process.env.X` parses
+ * here iff it parses at runtime. Then:
+ *
+ * - Root is an ARRAY → a cordis.yml entry list. Every item must be a mapping
+ *   with a string `name` and only the keys `EntryOptions` declares
+ *   (vendor/loader/src/config/entry.ts plus the isolate.ts merge:
+ *   id, name, config, group, disabled, inject, intercept, isolate).
+ *   - `./` / `../` names are illustrative local plugins — existence is not
+ *     checkable, skip. `group:*` names are loader built-ins; their `config`
+ *     is itself an entry list and is recursed into.
+ *   - Any other name must be a real workspace package (`packages/*​/*` and
+ *     `vendor/*` package.json names).
+ *   - For `@deepseek-ai/dsh-*` names the config-catalog generator is the
+ *     truth: kind `config` → the yaml `config`'s top-level keys must be
+ *     properties of the declared config type (member names of the first
+ *     catalog paste ∪ top-level segments of the runtime schema keys);
+ *     config-free kinds → a non-empty `config` mapping is a violation;
+ *     seam/library kinds → name existence only (loading one directly is
+ *     dubious, but that is a docs-prose concern, not this gate's).
+ * - Root is a MAPPING or scalar → a fragment (e.g. a bare `config:` excerpt):
+ *   syntax check only.
+ *
+ * This is a checker, not a fixer: it reports `file:line message` and exits 1.
+ *
+ * Run: `tsx scripts/verify-website-yaml.ts`.
+ */
+
+import { globSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import * as yaml from 'js-yaml'
+import ts from 'typescript'
+import { collectConfigCatalog, type CatalogEntry } from './gen-config-catalog.ts'
+
+const root = resolve(import.meta.dirname, '..')
+
+/** Mirror of the loader's yaml schema (vendor/include/src/index.ts): the
+ * `!!js` tag parses to an expression wrapper, everything else is JSON. */
+const JsExpr = new yaml.Type('tag:yaml.org,2002:js', {
+  kind: 'scalar',
+  resolve: data => typeof data === 'string',
+  construct: (data: string) => ({ __jsExpr: data }),
+})
+const schema = yaml.JSON_SCHEMA.extend(JsExpr)
+
+/** The exact key set an entry mapping may carry: `EntryOptions` in
+ * vendor/loader/src/config/entry.ts plus the isolate.ts interface merge. */
+const ENTRY_KEYS = ['id', 'name', 'config', 'group', 'disabled', 'inject', 'intercept', 'isolate'] as const
+
+/** One `file:line message` finding. */
+interface Violation {
+  file: string
+  /** 1-based line of the block's opening fence. */
+  line: number
+  message: string
+}
+
+/** One extracted ```yaml block. */
+interface Block {
+  file: string
+  /** 1-based line of the opening fence. */
+  line: number
+  kind: 'check' | 'ignore'
+  code: string
+}
+
+/** Extract every ```yaml / ```yaml ignore-check block from one Markdown file. */
+function extractBlocks(file: string): Block[] {
+  const text = readFileSync(resolve(root, file), 'utf8')
+  const lines = text.split('\n')
+  const blocks: Block[] = []
+  let open: { line: number; kind: Block['kind']; body: string[] } | null = null
+
+  lines.forEach((raw, i) => {
+    const fence = /^```(\s*)(\S.*)?$/.exec(raw)
+    if (!fence) {
+      if (open) open.body.push(raw)
+      return
+    }
+    if (open) {
+      // closing fence
+      blocks.push({ file, line: open.line, kind: open.kind, code: open.body.join('\n') })
+      open = null
+      return
+    }
+    // opening fence — only yaml blocks participate
+    const info = (fence[2] ?? '').trim()
+    const kind: Block['kind'] | null =
+      info === 'yaml' ? 'check'
+        : info === 'yaml ignore-check' ? 'ignore'
+          : null
+    if (kind) open = { line: i + 1, kind, body: [] }
+  })
+  return blocks
+}
+
+/** Every workspace package name: `packages/<group>/<pkg>` and `vendor/<pkg>`. */
+function knownPackages(): Set<string> {
+  const names = new Set<string>()
+  for (const pattern of ['packages/*/*/package.json', 'vendor/*/package.json']) {
+    for (const match of globSync(pattern, { cwd: root })) {
+      const pkg: unknown = JSON.parse(readFileSync(resolve(root, match), 'utf8'))
+      if (typeof pkg === 'object' && pkg !== null && 'name' in pkg && typeof pkg.name === 'string') {
+        names.add(pkg.name)
+      }
+    }
+  }
+  return names
+}
+
+/** The catalog, built once on first `@deepseek-ai/dsh-*` name, keyed by pkg. */
+let catalogByPkg: Map<string, CatalogEntry> | null = null
+function catalogFor(pkg: string): CatalogEntry | undefined {
+  catalogByPkg ??= new Map(collectConfigCatalog().map(e => [e.pkg, e]))
+  return catalogByPkg.get(pkg)
+}
+
+/** Top-level property names of the first catalog paste (the verbatim config
+ * type declaration), parsed as source text. */
+function pasteKeys(paste: string): Set<string> {
+  const sf = ts.createSourceFile('paste.ts', paste, ts.ScriptTarget.Latest, true)
+  const keys = new Set<string>()
+  const addMembers = (members: ts.NodeArray<ts.TypeElement>): void => {
+    for (const m of members) {
+      if (ts.isPropertySignature(m) || ts.isMethodSignature(m)) {
+        const name = m.name
+        keys.add(ts.isIdentifier(name) || ts.isStringLiteral(name) ? name.text : name.getText(sf))
+      }
+    }
+  }
+  for (const stmt of sf.statements) {
+    if (ts.isInterfaceDeclaration(stmt)) addMembers(stmt.members)
+    else if (ts.isTypeAliasDeclaration(stmt) && ts.isTypeLiteralNode(stmt.type)) addMembers(stmt.type.members)
+  }
+  return keys
+}
+
+/** The allowed top-level config keys of a kind-`config` catalog entry: the
+ * first paste's member names ∪ the schema keys' top-level segments
+ * (`agents[].id` → `agents`). Cached per entry. */
+const allowedKeysCache = new Map<string, Set<string>>()
+function allowedConfigKeys(entry: CatalogEntry): Set<string> {
+  const cached = allowedKeysCache.get(entry.pkg)
+  if (cached) return cached
+  const keys = pasteKeys(entry.pastes?.[0]?.text ?? '')
+  for (const path of entry.schemaKeys ?? []) {
+    const top = path.split('.')[0]?.replace(/\[\]$/, '')
+    if (top) keys.add(top)
+  }
+  allowedKeysCache.set(entry.pkg, keys)
+  return keys
+}
+
+/** A parsed yaml mapping (arrays and `!!js` wrappers excluded). */
+function asMapping(value: unknown): Record<string, unknown> | null {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return null
+  if ('__jsExpr' in value) return null
+  return value as Record<string, unknown>
+}
+
+/** Check one cordis.yml entry list (recursing into `group:` sub-lists). */
+function checkEntryList(
+  items: unknown[],
+  known: Set<string>,
+  block: Block,
+  violations: Violation[],
+): void {
+  const flag = (message: string): void => {
+    violations.push({ file: block.file, line: block.line, message })
+  }
+  items.forEach((item, index) => {
+    const at = `entry ${index + 1}`
+    const entry = asMapping(item)
+    if (!entry) {
+      flag(`${at}: not a mapping`)
+      return
+    }
+    const name = entry['name']
+    if (typeof name !== 'string') {
+      flag(`${at}: missing string \`name\``)
+      return
+    }
+    for (const key of Object.keys(entry)) {
+      if (!(ENTRY_KEYS as readonly string[]).includes(key)) {
+        flag(`${at} (${name}): unknown entry key \`${key}\` (EntryOptions allows: ${[...ENTRY_KEYS].join(', ')})`)
+      }
+    }
+    // Illustrative local plugin — nothing on disk to check against.
+    if (name.startsWith('./') || name.startsWith('../')) return
+    // Loader built-in group: its config is a nested entry list.
+    if (name.startsWith('group:')) {
+      if (Array.isArray(entry['config'])) checkEntryList(entry['config'], known, block, violations)
+      return
+    }
+    if (!known.has(name)) {
+      flag(`${at}: unknown plugin \`${name}\` (not a workspace package)`)
+      return
+    }
+    if (!name.startsWith('@deepseek-ai/dsh-')) return
+    const catalog = catalogFor(name)
+    if (!catalog) return
+    const config = asMapping(entry['config'])
+    if (catalog.kind === 'config') {
+      if (!config) return
+      const allowed = allowedConfigKeys(catalog)
+      for (const key of Object.keys(config)) {
+        if (!allowed.has(key)) {
+          flag(`${at}: \`${name}\` has no config key \`${key}\` (known keys: ${[...allowed].sort().join(', ')})`)
+        }
+      }
+    } else if (catalog.kind === 'no-config') {
+      if (config && Object.keys(config).length > 0) {
+        flag(`${at}: \`${name}\` declares no config, but the example passes one`)
+      }
+    }
+    // seam / library: loading one directly is dubious, but that is a prose
+    // concern — this gate only vouches for name existence.
+  })
+}
+
+const files = globSync('website/zh-CN/**/*.md', { cwd: root })
+  .filter(f => !f.startsWith('website/zh-CN/api/'))
+  .sort()
+
+const violations: Violation[] = []
+const known = knownPackages()
+let entryLists = 0
+let fragments = 0
+let ignored = 0
+let scanned = 0
+
+for (const file of files) {
+  for (const block of extractBlocks(file)) {
+    scanned++
+    if (block.kind === 'ignore') {
+      ignored++
+      continue
+    }
+    let parsed: unknown
+    try {
+      parsed = yaml.load(block.code, { schema })
+    } catch (error) {
+      const message = error instanceof Error ? error.message.split('\n')[0] ?? 'parse error' : String(error)
+      violations.push({ file: block.file, line: block.line, message: `yaml parse error: ${message}` })
+      continue
+    }
+    if (Array.isArray(parsed)) {
+      entryLists++
+      checkEntryList(parsed, known, block, violations)
+    } else {
+      // Mapping or scalar root: a fragment (e.g. a bare `config:` excerpt) —
+      // syntax is all there is to check.
+      fragments++
+    }
+  }
+}
+
+if (violations.length === 0) {
+  console.log(
+    `verify-website-yaml: ${scanned} yaml block(s) in ${files.length} file(s): `
+    + `${entryLists} entry list(s) + ${fragments} fragment(s) checked, ${ignored} ignore-check skipped.`,
+  )
+  process.exit(0)
+}
+
+console.error('verify-website-yaml: invalid yaml examples found:')
+for (const v of violations) {
+  console.error(`  ${v.file}:${v.line}  ${v.message}`)
+}
+process.exit(1)
diff --git a/website/zh-CN/develop/practice/index.md b/website/zh-CN/develop/practice/index.md
index 9781138c50..2a077aa22e 100644
--- a/website/zh-CN/develop/practice/index.md
+++ b/website/zh-CN/develop/practice/index.md
@@ -140,7 +140,7 @@ export function apply(ctx: Context) {
 
 ### 在 cordis.yml 中组合
 
-```yaml
+```yaml ignore-check
 - name: '@deepseek-ai/dsh-my-cap-local'
 - name: '@deepseek-ai/dsh-tool-my-cap'
 ```