diff --git a/.claude/skills/one-shot-card/SKILL.md b/.claude/skills/one-shot-card/SKILL.md new file mode 100644 index 0000000..fd8c187 --- /dev/null +++ b/.claude/skills/one-shot-card/SKILL.md @@ -0,0 +1,163 @@ +--- +name: one-shot-card +description: Use when a wiki concept/entity/source page or a mm chapter needs a visual TL;DR card. Produces a `.mdx` file that renders through `` in the Astro site. Design-first workflow — different cards should LOOK different. +argument-hint: [lang=zh|en] +user-invocable: true +--- + +# One-Shot Card + +Generate a TL;DR "一图流" card — a poster-style visual summary of any +main-content page — as a `.mdx` file consumed by Astro's `cards` +collection and rendered through ``. + +## Core principle (north star) + +> **充分利用有效面积，用版面体现重要性，最后再叠加审美。** + +Before you pick blocks, do **design-first thinking**. An A4 vertical +card is a *poster*, not a document. Content does NOT simply flow from +top to bottom in paragraphs — the visual weight of each region should +mirror how important that content is. If there's a hero idea, give it a +hero zone. If there's a core one-liner, give it its own band. If there +are siblings, put them side-by-side. + +Never let a card finish at 60% height with a half-empty bottom. Fill the +surface, or cut content until what remains fills it gracefully. + +**Different cards should LOOK different.** Do not default to the same +template each time. The point of one-shot cards is that each is a +dedicated poster, not a row in a uniform grid. + +## Inputs + +- Source file path — e.g. `wikis/concepts/causal-dag.md`, + `docs/zh/mental-models/ch-02-cybernetics/01-helmsman.md`, or a mm + chapter root. +- Target language — `zh` (default) or `en`. + +## Process (MANDATORY ORDER — do not skip design) + +### 1 · Read the source + +Parse the source file. Note: title, tagline candidates, core structure +(h2/h3 + first bullet of each), cross-references, cited sources, +(for source kind) author/year/URL. + +### 2 · Design-first: rank and allocate + +Before writing a single line of MDX, answer these questions: + +1. **What are the 3–5 things this card must communicate?** Rank by + importance (most → least). +2. **Which is the hero?** The single most important idea / the + signature visual. This gets the biggest surface area. +3. **Is there a signature visual?** (An SVG topology, a compare table, a + formula, a timeline, a matrix.) If yes, it IS the hero. +4. **What natural structure does this content have?** (N-case breakdown + / compare-contrast / timeline / hierarchical / quote + takeaways / KV + biographical.) This picks the layout pattern. +5. **What is the 1-line core definition?** The sentence that if a reader + reads nothing else, they got the concept. This deserves its own band. + +### 3 · Pick a layout approach — let different cards look different + +Do **NOT** default to the same template for every card. Choose per-content: + +| Content signature | Layout approach | Good fit for | +|---|---|---| +| One signature SVG + elaboration | **Hero-on-top** (bleed): large hero band, then tan core band, then small detail/refs band | concepts with a structural diagram (causal-dag, fractal) | +| Compare/contrast two sides | **Dual-column split** (bleed, ``): two panels side-by-side | pros vs cons, challenges vs strengths, symbol vs connectionist | +| N ordered steps / rules | **Rule-stack** (bleed with stacked bands; ink accent for 1st) | `do-calculus` three rules, multi-step processes | +| One person + their facts | **Portrait-KV** (bleed; 2-col top: hero-han + KV stack; bottom caption) | `entities/judea-pearl`, historical figures | +| One killer quote + 2–3 takeaways | **Quote-hero + takeaways-foot** (bleed; tan band with `` quote on top; paper-sunk band with numbered takeaways) | source cards, paper digests | +| Narrative chapter TL;DR | **Band-rhythm** (bleed; alternating tone bands each carrying one idea) | `chapters/ch-*`, overview cards | + +None are mandatory — the table is a *menu*. If a card's content +suggests a different composition, follow that. + +### 4 · Decide: `default` or `bleed` layout + +- **`default`** (layout field omitted): shell renders kind badge + seal + + title block + footer refs/source; body slots into a padded middle + region. Good when the card is small and you want the shell to frame + it. +- **`bleed`** (`layout: bleed` in frontmatter): shell renders ONLY the + A4 frame + palette lock. The body composes everything edge-to-edge + using `` / `` / `` / `` and inline + SVG/KV/Quote/etc. You are responsible for putting the title, kind + tag, and footer refs somewhere in the composition (usually: an ink or + tan top-band for title+kicker, and a paper-sunk or ink bottom-band + for refs+source). + +**Default for rich cards is `bleed`.** It's the only way to get real +infographic composition with color zones. + +### 5 · Compose the MDX + +- Start from a layout skeleton (menu in §3 or invent one). +- Fill content into zones. Each zone's content should be the minimum + needed to do its job — no filler to "fill space". If content doesn't + fit, adjust zone sizes. +- Use `` on the zone that should absorb any leftover vertical + space (typically the hero / compare zone, never the footer). +- Inline SVG is encouraged — 400×100 of 3 topologies tells more than + three text pillars. Use `currentColor` and token-driven fill/stroke + so dark mode flips automatically. +- Unusual compositions welcome: rotated text, vertical rails, hero + number accents, compare-matrix tables. The A4 frame is the only hard + limit. + +### 6 · Write to disk + +Path: `site/src/content/cards/{lang}/{kind-plural}/{slug}.mdx` + +`{kind-plural}` ∈ `concepts` / `entities` / `sources` / `chapters`. + +**Never set `kind` or `slug` in frontmatter** — derived from path. + +### 7 · Hand off + +Return: +- Path of the file written. +- 1-sentence statement of the layout approach chosen and *why*. +- Review URL: + - wiki entries: `http://localhost:4321/{lang}/wiki/{kind-plural}/{slug}` + - any card (isolated view): `http://localhost:4321/card-fragment/{lang}/{kind-plural}/{slug}?theme=dark` + +The author will eyeball and iterate. + +## Hard constraints (imposed by the component — can't escape) + +- A4 vertical aspect ratio (1 : 1.414). +- `max-height: calc(100vh - 120px)`. +- `overflow: hidden` — the card clips. If content overflows, the author + sees it and will trim. Do NOT add internal scrolling. +- Palette locked to `tokens.css`. Never hard-code hex values. + +## Non-constraints (you choose freely) + +- Number of zones / bands / SVG panels. +- Vertical rhythm — bleed bands can be any height you want. +- Typographic weights/sizes within the provided fonts. +- Whether the kind tag / title / footer lives in the shell's default + chrome (default layout) or inside a band you author (bleed layout). + +## Background + +- `references/aesthetic.md` — tokens + voice +- `references/blocks.md` — block kit catalog (incl. new ``, + ``, ``, ``) +- `references/layouts.md` — the 6 layout approaches above with worked + MDX skeletons +- `references/sources-card.md` — source-kind special fields +- `references/exemplars/` — real mdx files annotated with *why* each + layout choice was made + +## Skill chain + +- Produce one sample; author reviews. +- If layout is wrong (feels flat, feels crowded, feels samey), iterate: + swap the approach, re-generate. +- Phase-2 targets ~5 异质 samples, one per archetype. Batch-regen for + P3 is a separate spec — don't try to mass-produce here. diff --git a/.claude/skills/one-shot-card/references/aesthetic.md b/.claude/skills/one-shot-card/references/aesthetic.md new file mode 100644 index 0000000..a9ca708 --- /dev/null +++ b/.claude/skills/one-shot-card/references/aesthetic.md @@ -0,0 +1,57 @@ +# Card Aesthetic — Palette & Voice + +## Palette (tokens.css) + +- `--paper` — main background (宣纸底) +- `--paper-raised` — card body background (展签纸) +- `--paper-sunk` — recessed slots (contained code, chips) +- `--ink` — primary text +- `--ink-soft` — body prose +- `--ink-faint` — captions, meta labels +- `--rule` — hairlines +- `--vermilion` — seal, accent; use sparingly (印章 only, or one chip) +- `--gold` — quieter accent (entity seal, source year) +- `--celadon` — rarest accent (rare structural emphasis) + +The dark-mode palette flips automatically via `[data-theme="dark"]`. +Your card should not hard-code any hex value. + +### Gotcha — day/night inversion of `--paper` and `--ink` + +In light mode `--paper` is cream, `--ink` is near-black. +In dark mode they flip: `--paper` is near-black, `--ink` is cream. + +So a rule like `color: var(--paper)` on an "ink-dark band" gives cream text in +light mode but near-black text in dark mode — invisible either way depending +on the band. + +**Always inherit the enclosing band's text color for body/chip text** — +use `color: currentColor` (the band already sets the correct text color +via ``'s own CSS, flipped for both modes). + +For semi-transparent variants use `color-mix(in oklab, currentColor 70%, transparent)` +or simply `opacity: 0.75` — both track the band's text direction. + +Never write `color: var(--paper)` / `color: var(--ink)` directly inside a +card's ` + ``` +- **Avoid `{/* comments */}` inside deeply nested SVG** — strip them. +- **Don't set `kind` or `slug` in frontmatter** — derived from path. diff --git a/.claude/skills/one-shot-card/references/exemplars/concept-causal-dag.mdx b/.claude/skills/one-shot-card/references/exemplars/concept-causal-dag.mdx new file mode 100644 index 0000000..2244c4d --- /dev/null +++ b/.claude/skills/one-shot-card/references/exemplars/concept-causal-dag.mdx @@ -0,0 +1,29 @@ +{/* exemplar: concept card showing 3-case structural breakdown via PillarGrid + Divider + Formula. Good when a concept has a clean "N patterns + one unifying rule" shape. */} + +--- +schemaVersion: one-shot-card/v1 +title: 因果有向无环图 +titleAlt: Causal DAG +tagline: 链 / 叉 / 对撞 · d-分离 · 去混淆的桥 +refs: + - concepts/structural-causal-model + - concepts/do-calculus +sourceLine: 参 Pearl (2009); Book of Why (2018) +--- + +import PillarGrid from '~/components/card/blocks/PillarGrid.astro'; +import Pillar from '~/components/card/blocks/Pillar.astro'; +import Divider from '~/components/card/blocks/Divider.astro'; +import Formula from '~/components/card/blocks/Formula.astro'; + + + `A → B → C`
条件化 B 阻断 + `A ← B → C`
B 是混淆因子 + `A → B ← C`
条件化反而打开 + + + + +**d-分离** — 给定 Z 阻断 X→Y 的所有路径 ⇒ X ⊥ Y | Z。 + +P(Y | do(X)) = Σz P(Y | X, Z=z) P(Z=z) diff --git a/.claude/skills/one-shot-card/references/exemplars/entity-judea-pearl.mdx b/.claude/skills/one-shot-card/references/exemplars/entity-judea-pearl.mdx new file mode 100644 index 0000000..043ef1d --- /dev/null +++ b/.claude/skills/one-shot-card/references/exemplars/entity-judea-pearl.mdx @@ -0,0 +1,24 @@ +{/* exemplar: entity card with KV stack for biographical metadata + trailing Caption punchline. Good when the entity has a few crisp facts that warrant a structured table rather than prose. */} + +--- +schemaVersion: one-shot-card/v1 +title: Judea Pearl +tagline: 因果革命的奠基者 · 图灵奖 2011 · UCLA CS 教授 +refs: + - concepts/causal-dag + - concepts/do-calculus +sourceLine: Causality (2009); The Book of Why (2018) +--- + +import KV from '~/components/card/blocks/KV.astro'; +import Stack from '~/components/card/blocks/Stack.astro'; +import Caption from '~/components/card/blocks/Caption.astro'; + + + 1936— + UCLA Computer Science + 2011 "因果与概率推理基础性贡献" + 结构因果模型 · do 演算 · 因果之梯 + + +把因果推理从哲学思辨提升为可操作的数学学科。 diff --git a/.claude/skills/one-shot-card/references/exemplars/source-anthropic-ctx-eng.mdx b/.claude/skills/one-shot-card/references/exemplars/source-anthropic-ctx-eng.mdx new file mode 100644 index 0000000..959ef5e --- /dev/null +++ b/.claude/skills/one-shot-card/references/exemplars/source-anthropic-ctx-eng.mdx @@ -0,0 +1,27 @@ +{/* exemplar: source card with Quote + 3 takeaway bullets via Stack. Good when a source has one killer quote and a handful of distilled insights. */} + +--- +schemaVersion: one-shot-card/v1 +title: Effective Context Engineering for AI Agents +tagline: Anthropic 官方 · 长时程 agent 的上下文工程总论 +author: Anthropic Applied AI team +year: 2026 +url: https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents +refs: + - concepts/context-engineering + - concepts/context-rot +sourceLine: Anthropic Engineering, July 2026 +--- + +import Quote from '~/components/card/blocks/Quote.astro'; +import Stack from '~/components/card/blocks/Stack.astro'; + + + 注意力预算是稀缺资源 —— just-in-time、compaction、note-taking、sub-agent 是四种抵御 context rot 的工程手法。 + + + +
**① just-in-time context** — 按需注入而非 upfront 堆砌
+
**② compaction** — 旧轮次摘要化；保留结构，丢弃细节
+
**③ note-taking** — agent 自持外部笔记，跨 session 回忆
+ diff --git a/.claude/skills/one-shot-card/references/layouts.md b/.claude/skills/one-shot-card/references/layouts.md new file mode 100644 index 0000000..7718000 --- /dev/null +++ b/.claude/skills/one-shot-card/references/layouts.md @@ -0,0 +1,278 @@ +# Layout Approaches + +Six reference layouts. Each is a menu item, not a required template. +Pick the one that fits the content. If none do, compose your own. + +All examples assume `layout: bleed` unless noted. Import primitives: + +```mdx +import Band from '~/components/card/blocks/Band.astro'; +import Kicker from '~/components/card/blocks/Kicker.astro'; +import HeroHan from '~/components/card/blocks/HeroHan.astro'; +import CoreDef from '~/components/card/blocks/CoreDef.astro'; +import KV from '~/components/card/blocks/KV.astro'; +import Formula from '~/components/card/blocks/Formula.astro'; +import Quote from '~/components/card/blocks/Quote.astro'; +``` + +--- + +## 1 · Hero-on-top + +A signature SVG/diagram occupies the top 55-65% of the card. Below it, +a tan band with the core definition; then a smaller detail / refs band. + +Good for: concepts that have a structural diagram (Causal DAG, Fractal, +Orthogonality). + +```mdx + + 概念 · CAUSAL DAG + + + +

因果有向无环图

+

Causal DAG

+ + … + + + + 条件化中间节点阻断链/叉；条件化对撞反而打开。 + + + + P(Y | do(X)) = Σz P(Y | X, Z=z) P(Z=z) + + + + + +``` + +--- + +## 2 · Dual-column split + +Two equal-width columns comparing two things. Often with a common core +band above or below. + +Good for: challenges vs strengths, symbol vs connectionist, before vs +after, two schools of thought. + +```mdx + + 概念 · SYMBOL ↔ CONNECTIONIST + + + +

两种表征

+

离散符号 vs 连续向量

+ + + + 同一目标，两种地图——翻译的代价决定哪一种适合哪一类问题。 + + + +
+ SYMBOL +
    …
+
+
+ CONNECTIONIST +
    …
+
+ + +…refs + source… +``` + +--- + +## 3 · Rule-stack + +Sequential rules or steps presented as equal bands, optionally with +different tones to denote ordering (ink for the strongest / first, +paper-sunk for details). + +Good for: do-calculus three rules, Ashby's requisite variety ladder, +onboarding steps. + +```mdx + + 概念 · DO-CALCULUS +

do 演算

+

Pearl's three rules

+ + + + 插入/删除观测 —— 若 Y ⊥ Z | X, W 在 G(X̄) 中成立 + + + 动作 ↔ 观测 —— 若 Y ⊥ Z | X, W 在 G(X̄, Z̲) 中成立 + + + 插入/删除动作 —— 若 Y ⊥ Z | X, W 在 G(X̄, Z̄(W)) 中成立 + + + + P(y | do(x)) = Σz P(y | x, z) P(z) + + +…refs + source… +``` + +--- + +## 4 · Portrait-KV + +A 2-column top region: left column a hero-han (一 or 两 or the person's +surname in Han), right column a KV stack of biographical facts. Below, +a caption band with the signature contribution. + +Good for: entity cards (Judea Pearl, Herbert Simon, Karpathy). + +```mdx + +
+ 实体 · 图灵奖 2011 + Pearl +
+
+

Judea Pearl

+

因果革命的奠基者 · UCLA CS 教授

+
+ + + + 1936— + UCLA Computer Science + 2011 "因果与概率推理基础性贡献" + 结构因果模型 · do 演算 · 因果之梯 + + + + 把因果推理从哲学思辨提升为可操作的数学学科。 + + +…refs + source… +``` + +--- + +## 5 · Quote-hero + takeaways + +A big tan band at the top contains a `` with the source's +killer quote. Below, a paper-sunk band lists 2-3 numbered takeaways. + +Good for: source cards (paper / blog / engineering doc digests). + +```mdx + + 源头 · ANTHROPIC ENGINEERING · 2026 + + + +

Effective Context Engineering for AI Agents

+

长时程 agent 的上下文工程总论

+ + + + 注意力预算是稀缺资源 —— just-in-time / compaction / note-taking / sub-agent 是四种抵御 context rot 的工程手法。 + + + +
+ ① JUST-IN-TIME +

按需注入，而非 upfront 堆砌。

+
+
+ ② COMPACTION +

旧轮次摘要化；保留结构，丢弃细节。

+
+
+ ③ NOTE-TAKING +

agent 自持外部笔记，跨 session 回忆。

+
+
+ ④ SUB-AGENT +

拆分长任务到多个独立上下文。

+
+ + +…refs + source line… +``` + +--- + +## 6 · Band-rhythm (for chapter cards) + +Four or five bands alternating tones, each carrying one big idea from +the chapter as a bold heading + one-line explanation. + +Good for: mm chapter TL;DRs (control / entropy / fractal / causality / +symbols). + +```mdx + +
+ 篇 II · CYBERNETICS + 舵 +
+
+

控制论

+

Helmsman · Feedback · Requisite Variety

+
+ + + + 舵手 +

设定航向的是舵手不是舵；模型是舵，harness 是舵手。

+ + + + 反馈 +

观测 → 误差 → 修正；没有反馈环的 agent 无法收敛。

+ + + + 必要多样性 (Ashby) +

控制器的复杂度必须不小于被控系统；越难的域需要越会 reason 的 agent。

+ + + + 二阶控制 +

当外界扰动超出一阶环的纠偏范围，让一阶目标本身变为变量。

+ + +…refs + source… +``` + +--- + +## CSS classes available to all layouts + +The card title / subtitle typography you can use in any band: + +```css +/* in global CSS / tokens — available everywhere */ +.card-title { font-family: var(--font-han-display); font-weight: 400; font-size: clamp(1.4rem, 2.4vw, 2rem); line-height: 1.2; letter-spacing: 0.03em; color: var(--ink); margin: 0 0 4px; } +.card-subtitle { font-family: var(--font-latin); font-style: italic; font-size: 0.95rem; color: var(--ink-faint); margin: 0; } +.card-title-on-ink { font-family: var(--font-han-display); font-weight: 400; font-size: clamp(1.4rem, 2.4vw, 2rem); line-height: 1.2; color: var(--paper); margin: 0 0 4px; } +.card-subtitle-on-ink { font-family: var(--font-latin); font-style: italic; font-size: 0.95rem; color: color-mix(in oklab, var(--paper) 70%, transparent); margin: 0; } +``` + +If those classes aren't registered yet when you write your card, fall +back to inline styles or `` blocks (MDX requires +CSS to be template-literal-wrapped to avoid JSX object-literal parsing). + +## MDX gotchas + +- ``. +- JSX comments `{/* */}` CAN be used between top-level bands but tend to + break inside deeply nested SVG. Strip them in SVG. +- When refs chips appear in a bleed card, write them manually in a + paper-sunk or ink footer band. The shell's default `.oscard__foot` is + NOT rendered in bleed mode. diff --git a/.claude/skills/one-shot-card/references/sources-card.md b/.claude/skills/one-shot-card/references/sources-card.md new file mode 100644 index 0000000..fc5e3d4 --- /dev/null +++ b/.claude/skills/one-shot-card/references/sources-card.md @@ -0,0 +1,30 @@ +# Source Card Variant + +Source cards (kind = `sources` in the folder path) have richer frontmatter +than concepts / entities — they cite external work with structured +metadata. + +## Extra frontmatter + +```yaml +author: Anthropic Applied AI team +year: 2026 +url: https://www.anthropic.com/engineering/... +``` + +The `` shell does not yet surface these visually (phase 3 +work — an "author · year" line in the header). For now, the author +field is still authoritative in the mdx and will be picked up by later +shell enhancements. + +## Body pattern + +A source card shines when it distills the source into: + +1. **One killer quote** (the most quotable sentence in the source), + rendered via ``. +2. **2-3 takeaways** (the author's 讨论 of why it matters), as a + `` of bullet/prose lines. + +Avoid listing every section of the source — that's the source's job, +not the card's. diff --git a/docs/zh/mental-models/ch-02-cybernetics/01-helmsman.md b/docs/zh/mental-models/ch-02-cybernetics/01-helmsman.md index e10d2bd..e72637c 100644 --- a/docs/zh/mental-models/ch-02-cybernetics/01-helmsman.md +++ b/docs/zh/mental-models/ch-02-cybernetics/01-helmsman.md @@ -67,3 +67,5 @@ Harness 是一个整体，但它内部有职责分工。控制论用三个角色 - [Agentic Systems](../../wiki/concepts/agentic-systems.md) — 本文讨论的反馈机制是 agentic system 运行的核心结构 - [Context Management](../../wiki/concepts/context-management.md) — 文中将上下文管理类比为"信号滤波与降噪"，这里展开了具体机制 - [Guardrails](../../wiki/concepts/guardrails.md) — 文中提到的权限系统、沙箱隔离等约束边界的详细资料 + +

本节和的结构思考相呼应 —— 点开看它的一图流卡。

diff --git a/site/src/components/WikiAtlas.astro b/site/src/components/WikiAtlas.astro index 323940b..4e0a74a 100644 --- a/site/src/components/WikiAtlas.astro +++ b/site/src/components/WikiAtlas.astro @@ -18,6 +18,8 @@ import type { Locale } from "~/i18n/strings"; import { wikiEntry } from "~/lib/urls"; import manifest from "~/content/wiki/_manifest.json"; +import { getCollection } from "astro:content"; +import OneShotCard from "~/components/card/OneShotCard.astro"; interface ManifestEntry { kind: "concepts" | "entities" | "sources"; @@ -45,6 +47,9 @@ const labels = locale === "zh" ? { concepts: "概念", entities: "实体", sources: "源头", all: "全部", random: "抽卡", cards: "展陈", index: "目录" } : { concepts: "Concepts", entities: "Entities", sources: "Sources", all: "All", random: "Draw", cards: "Exhibits", index: "Index" }; +const oneShotEntries = await getCollection("cards"); +const cardEntryIds = new Set(oneShotEntries.map((c) => c.id)); + // Cards section = concepts + entities (image-forward) const cardEntries = [...byKind.concepts, ...byKind.entities].sort((a, b) => a.slug.localeCompare(b.slug)); --- @@ -87,32 +92,43 @@ const cardEntries = [...byKind.concepts, ...byKind.entities].sort((a, b) => a.sl
{ - cardEntries.map((e) => ( - - {e.card && ( - - )} -
- {e.kind === "concepts" ? "念" : "实"} - {labels[e.kind]} -
-
-

{e.title}

- {e.desc &&

{e.desc}

} -
- - )) + cardEntries.map((e) => { + const hasOneShot = cardEntryIds.has(`${locale}/${e.kind}/${e.slug}`); + return ( + + {hasOneShot ? ( +
+ +
+ ) : ( + <> + {e.card && ( + + )} +
+ {e.kind === "concepts" ? "念" : "实"} + {labels[e.kind]} +
+
+

{e.title}

+ {e.desc &&

{e.desc}

} +
+ + )} + + ); + }) }
@@ -151,16 +167,10 @@ const cardEntries = [...byKind.concepts, ...byKind.entities].sort((a, b) => a.sl {/* ── Gacha overlay (hidden until 抽卡 clicked) ───────────────── */} -