Compare commits
9 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 codex-bot
|
1966d7a0a7 | ||
 Zayden-Jung
|
319de8a3a7 | ||
|
codex-bot
|
787491622b | ||
|
Zayden-Jung
|
e448acb904 | ||
|
codex-bot
|
e286139572 | ||
|
codex-bot
|
c49c8348d2 | ||
|
Zayden-Jung
|
7a9c88a05a | ||
|
codex-bot
|
bd932c36b2 | ||
|
codex-bot
|
c08371647d |
@@ -6,4 +6,5 @@
|
||||
**/*.pyc
|
||||
**/*.tsbuildinfo
|
||||
.artifacts
|
||||
apps/docs/public/figures/**/*.webp
|
||||
.env*
|
||||
|
||||
@@ -11,3 +11,6 @@ __pycache__/
|
||||
!.env.example
|
||||
|
||||
.artifacts/
|
||||
|
||||
# Browser raster derivatives are generated on the confirmed remote runner.
|
||||
/apps/docs/public/figures/**/*.webp
|
||||
|
||||
@@ -3,8 +3,10 @@
|
||||
"version": "0.1.0",
|
||||
"private": true,
|
||||
"scripts": {
|
||||
"dev": "NEXT_TELEMETRY_DISABLED=1 next dev --hostname 127.0.0.1",
|
||||
"build": "NEXT_TELEMETRY_DISABLED=1 next build && node scripts/build-auth.mjs",
|
||||
"dev": "node scripts/build-doc-images.mjs && NEXT_TELEMETRY_DISABLED=1 next dev --hostname 127.0.0.1",
|
||||
"build": "node scripts/build-doc-images.mjs && NEXT_TELEMETRY_DISABLED=1 next build && node scripts/build-auth.mjs",
|
||||
"images": "node scripts/build-doc-images.mjs",
|
||||
"test:images": "node scripts/build-doc-images.mjs --check",
|
||||
"start": "NEXT_TELEMETRY_DISABLED=1 next start --hostname 127.0.0.1",
|
||||
"lint": "eslint . --max-warnings=0",
|
||||
"typecheck": "NEXT_TELEMETRY_DISABLED=1 next typegen && tsc --noEmit",
|
||||
@@ -29,6 +31,7 @@
|
||||
"eslint": "^9.39.5",
|
||||
"eslint-config-next": "16.4.3",
|
||||
"postcss": "8.5.31",
|
||||
"sharp": "0.35.5",
|
||||
"tailwindcss": "4.3.3",
|
||||
"typescript": "~5.9.3"
|
||||
}
|
||||
|
||||
@@ -141,6 +141,8 @@ async function main() {
|
||||
"/",
|
||||
"/docs/00-endor-concepts-draft",
|
||||
"/figures/endor-architecture.svg",
|
||||
"/figures/endor-review-gate.webp",
|
||||
"/figures/endor-review-desk.webp",
|
||||
"/docs/pretext/01-chapter",
|
||||
"/materials/pretext/verify.cjs",
|
||||
"/materials/pretext/results.chrome156.json",
|
||||
@@ -185,21 +187,27 @@ async function main() {
|
||||
assert.ok(searchIndex.some((doc: { slug: string; searchText: string }) => doc.slug === "source-studies/pretext/measurement-cache" && doc.searchText.includes("getSegmentMetrics")));
|
||||
for (const doc of searchIndex as { slug: string; sourceSlug: string }[]) {
|
||||
assert.ok(!doc.slug.split("/").some((part) => /^\d+-/.test(part)), doc.slug);
|
||||
const legacy = await request(`/docs/${doc.sourceSlug}`, { headers });
|
||||
const legacy = await request(`/docs/${doc.sourceSlug}?from=legacy`, { headers });
|
||||
assert.equal(legacy.status, 308, doc.sourceSlug);
|
||||
assert.equal(new URL(legacy.headers.get("location")!, base).pathname, `/docs/${doc.slug}`);
|
||||
const destination = new URL(legacy.headers.get("location")!, base);
|
||||
assert.equal(destination.pathname, `/docs/${doc.slug}`);
|
||||
assert.equal(destination.searchParams.get("from"), "legacy");
|
||||
assert.ok(legacy.headers.get("cache-control")?.includes("no-store"));
|
||||
}
|
||||
let home = "";
|
||||
let purpose = "";
|
||||
for (const route of routes) {
|
||||
const response = await request(route, { headers });
|
||||
const alias = (searchIndex as { sourceSlug: string }[]).some((doc) => route === `/docs/${doc.sourceSlug}`);
|
||||
assert.equal(response.status, alias ? 308 : 200, route);
|
||||
if (alias) continue;
|
||||
assert.equal(response.status, 200, route);
|
||||
const html = await response.text();
|
||||
if (route === "/") home = html;
|
||||
if (route === "/docs/endor/endor-purpose-draft") purpose = html;
|
||||
if (route.startsWith("/docs/")) {
|
||||
assert.ok(html.includes('aria-label="文档选择"'), route);
|
||||
assert.ok(html.includes('<optgroup label="语言与运行时">'), route);
|
||||
assert.ok(html.includes('aria-label="文档分类"'), route);
|
||||
assert.ok(html.includes('data-category="语言与运行时"'), route);
|
||||
assert.ok(html.includes('class="category-panel" hidden=""'), route);
|
||||
assert.ok(!html.includes('class="collection-picker"'), route);
|
||||
assert.ok(!html.includes("<select"), route);
|
||||
assert.ok(!html.includes('class="nav-back"'), route);
|
||||
const ids = [...html.matchAll(/<h[23] id="([^"]+)"/g)].map((match) => match[1]);
|
||||
assert.equal(new Set(ids).size, ids.length, `Unique heading anchors: ${route}`);
|
||||
@@ -208,6 +216,32 @@ async function main() {
|
||||
}
|
||||
assert.ok(home.includes("资料库"));
|
||||
assert.ok(home.includes("/docs/source-studies/pretext/overview"));
|
||||
// Inline preview and zoom dialog must both use the compressed browser asset.
|
||||
assert.equal(
|
||||
[...purpose.matchAll(/<img\b[^>]*\bsrc="\/figures\/endor-review-gate\.webp"/g)].length,
|
||||
2,
|
||||
"The comic preview and lightbox must use WebP",
|
||||
);
|
||||
assert.ok(purpose.includes('aria-label="上一张图片"'));
|
||||
assert.ok(purpose.includes('aria-label="下一张图片"'));
|
||||
assert.ok(purpose.includes('aria-label="显示第 1 张图片" aria-current="true"'));
|
||||
assert.ok(purpose.includes('aria-label="显示第 2 张图片"'));
|
||||
assert.equal(
|
||||
[...purpose.matchAll(/<img\b[^>]*\bsrc="\/figures\/endor-review-desk\.webp"/g)].length,
|
||||
0,
|
||||
"The second slide should not download until selected",
|
||||
);
|
||||
for (const name of ["endor-review-gate", "endor-review-desk"]) {
|
||||
assert.ok(!purpose.includes(`/figures/${name}.png`));
|
||||
const comic = await request(`/figures/${name}.webp`, { headers });
|
||||
assert.equal(comic.status, 200);
|
||||
assert.match(comic.headers.get("content-type") || "", /image\/webp/);
|
||||
assert.deepEqual(
|
||||
Buffer.from(await comic.arrayBuffer()),
|
||||
readFileSync(join(__dirname, `public/figures/${name}.webp`)),
|
||||
);
|
||||
assert.equal((await request(`/figures/${name}.png`, { headers })).status, 404);
|
||||
}
|
||||
const assets = new Set(
|
||||
[...home.matchAll(/(?:src|href)="(\/_next\/static\/[^" ]+)"/g)].map((m) =>
|
||||
m[1].replaceAll("&", "&"),
|
||||
|
||||
@@ -0,0 +1,62 @@
|
||||
import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
|
||||
import path from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
import sharp from "sharp";
|
||||
|
||||
const root = fileURLToPath(new URL("../../../", import.meta.url));
|
||||
const sources = path.join(root, "tools/figures/assets");
|
||||
const output = path.join(root, "apps/docs/public/figures");
|
||||
const check = process.argv.includes("--check");
|
||||
const policy = JSON.parse(await readFile(path.join(root, "content/image-policy.json"), "utf8"));
|
||||
|
||||
async function files(directory) {
|
||||
const entries = await readdir(directory, { withFileTypes: true });
|
||||
return (await Promise.all(entries.map((entry) => {
|
||||
const name = path.join(directory, entry.name);
|
||||
return entry.isDirectory() ? files(name) : [name];
|
||||
}))).flat().sort();
|
||||
}
|
||||
|
||||
// Originals stay outside public; both inline and lightbox images use the WebP.
|
||||
for (const name of await files(path.join(root, "apps/docs/public"))) {
|
||||
if (/\.(?:png|jpe?g|tiff?|bmp)$/i.test(name)) {
|
||||
throw new Error(`Original raster exposed in public: ${path.relative(root, name)}. Move it to tools/figures/assets and run images.`);
|
||||
}
|
||||
}
|
||||
for (const name of await files(path.join(root, "content/docs"))) {
|
||||
if (!name.endsWith(".md")) continue;
|
||||
const content = await readFile(name, "utf8");
|
||||
const images = [
|
||||
...content.matchAll(/!\[[^\]]*\]\(<?([^\s)>]+)/g),
|
||||
...content.matchAll(/<img\b[^>]*\bsrc=["']([^"']+)/gi),
|
||||
];
|
||||
for (const [, source] of images) {
|
||||
if (/\.(?:png|jpe?g|tiff?|bmp)(?:[?#]|$)/i.test(source)) {
|
||||
throw new Error(`${path.relative(root, name)} embeds an original raster: ${source}. Use the compressed WebP.`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
await mkdir(output, { recursive: true });
|
||||
for (const source of await files(sources)) {
|
||||
if (!/\.(?:png|jpe?g|tiff?|bmp)$/i.test(source)) continue;
|
||||
const relative = path.relative(sources, source).replace(/\.[^.]+$/, ".webp");
|
||||
const destination = path.join(output, relative);
|
||||
const original = await readFile(source);
|
||||
const encoded = await sharp(original)
|
||||
.rotate()
|
||||
.resize({ width: policy.maxWidth, withoutEnlargement: true })
|
||||
.webp({ quality: policy.quality, effort: 6 })
|
||||
.toBuffer();
|
||||
if (encoded.length > policy.maxBytes) {
|
||||
throw new Error(`${relative}: ${encoded.length} bytes exceeds the ${policy.maxBytes}-byte image budget.`);
|
||||
}
|
||||
if (check) {
|
||||
const generated = await readFile(destination);
|
||||
if (!encoded.equals(generated)) throw new Error(`${relative} is stale. Regenerate browser images on the confirmed remote runner.`);
|
||||
} else {
|
||||
await mkdir(path.dirname(destination), { recursive: true });
|
||||
await writeFile(destination, encoded);
|
||||
}
|
||||
console.log(`${check ? "Verified" : "Generated"} ${relative}: ${original.length} → ${encoded.length} bytes (${(100 * (1 - encoded.length / original.length)).toFixed(1)}% smaller)`);
|
||||
}
|
||||
@@ -0,0 +1,93 @@
|
||||
import Link from "next/link";
|
||||
import { useEffect, useId, useRef, useState, type KeyboardEvent } from "react";
|
||||
import type { DocLink } from "@/lib/docs";
|
||||
import { collectionEntries, collectionIcon, collectionLabel, collectionTone } from "@/lib/collections";
|
||||
import { Icon } from "./Icon";
|
||||
|
||||
export function CategoryNavigation({ docs, current }: { docs: DocLink[]; current?: string }) {
|
||||
const navigation = useRef<HTMLElement>(null);
|
||||
const triggers = useRef(new Map<string, HTMLButtonElement>());
|
||||
const [open, setOpen] = useState<string | null>(null);
|
||||
const id = useId();
|
||||
const categories = [...new Set(docs.map((doc) => doc.category))];
|
||||
const collections = collectionEntries(docs);
|
||||
const selected = docs.find((doc) => doc.slug === current);
|
||||
|
||||
useEffect(() => {
|
||||
function outside(event: PointerEvent) {
|
||||
if (event.target instanceof Node && !navigation.current?.contains(event.target)) setOpen(null);
|
||||
}
|
||||
function escape(event: globalThis.KeyboardEvent) {
|
||||
if (event.key !== "Escape" || !open) return;
|
||||
if (navigation.current?.contains(document.activeElement)) {
|
||||
event.preventDefault();
|
||||
triggers.current.get(open)?.focus();
|
||||
}
|
||||
setOpen(null);
|
||||
}
|
||||
document.addEventListener("pointerdown", outside);
|
||||
document.addEventListener("keydown", escape);
|
||||
return () => {
|
||||
document.removeEventListener("pointerdown", outside);
|
||||
document.removeEventListener("keydown", escape);
|
||||
};
|
||||
}, [open]);
|
||||
|
||||
function focusItem(panel: string, last = false) {
|
||||
requestAnimationFrame(() => {
|
||||
const links = document.getElementById(panel)?.querySelectorAll<HTMLAnchorElement>("a");
|
||||
links?.[last ? links.length - 1 : 0]?.focus();
|
||||
});
|
||||
}
|
||||
function move(event: KeyboardEvent<HTMLDivElement>) {
|
||||
if (!["ArrowDown", "ArrowUp", "Home", "End"].includes(event.key)) return;
|
||||
const links = [...event.currentTarget.querySelectorAll<HTMLAnchorElement>("a")];
|
||||
const index = links.indexOf(document.activeElement as HTMLAnchorElement);
|
||||
if (index < 0) return;
|
||||
event.preventDefault();
|
||||
const next = event.key === "Home" ? 0 : event.key === "End" ? links.length - 1 :
|
||||
(index + (event.key === "ArrowDown" ? 1 : -1) + links.length) % links.length;
|
||||
links[next]?.focus();
|
||||
}
|
||||
|
||||
return <nav ref={navigation} className="top-nav category-navigation" aria-label="文档分类"
|
||||
onBlur={(event) => {
|
||||
if (!event.currentTarget.contains(event.relatedTarget as Node | null)) setOpen(null);
|
||||
}}>
|
||||
<ul>
|
||||
<li><Link className="category-home" href="/" aria-current={!current ? "page" : undefined} onClick={() => setOpen(null)}>文档中心</Link></li>
|
||||
{categories.map((category, index) => {
|
||||
const panel = `${id}-category-${index}`;
|
||||
const expanded = open === category;
|
||||
return <li className="category-menu" key={category}
|
||||
onPointerEnter={(event) => { if (event.pointerType === "mouse") setOpen(category); }}
|
||||
onPointerLeave={(event) => { if (event.pointerType === "mouse") setOpen(null); }}>
|
||||
<button ref={(element) => { if (element) triggers.current.set(category, element); else triggers.current.delete(category); }}
|
||||
type="button" className="category-trigger" data-category={category}
|
||||
data-active={selected?.category === category || undefined}
|
||||
aria-expanded={expanded} aria-controls={panel}
|
||||
onClick={() => setOpen(expanded ? null : category)}
|
||||
onKeyDown={(event) => {
|
||||
if (event.key === "ArrowDown" || event.key === "ArrowUp") {
|
||||
event.preventDefault();
|
||||
setOpen(category);
|
||||
focusItem(panel, event.key === "ArrowUp");
|
||||
}
|
||||
}}>
|
||||
{category}<Icon name="chevron" size={11} />
|
||||
</button>
|
||||
<div id={panel} className="category-panel" hidden={!expanded} onKeyDown={move}>
|
||||
<p className="category-panel-title">{category}</p>
|
||||
{collections.filter(({entry}) => entry.category === category).map(({name, entry}) => <Link
|
||||
key={name} href={`/docs/${entry.slug}`} data-tone={collectionTone(name)}
|
||||
aria-current={current === entry.slug ? "page" : selected?.collection === name ? "true" : undefined}
|
||||
onClick={() => setOpen(null)}>
|
||||
<Icon name={collectionIcon(name)} size={19} />
|
||||
<span><strong>{collectionLabel(name)}</strong><small>{entry.description}</small></span>
|
||||
</Link>)}
|
||||
</div>
|
||||
</li>;
|
||||
})}
|
||||
</ul>
|
||||
</nav>;
|
||||
}
|
||||
@@ -0,0 +1,66 @@
|
||||
import { useId, useState } from "react";
|
||||
import { ArchitectureFigure } from "./ArchitectureFigure";
|
||||
|
||||
type Slide = { source: string; alt: string };
|
||||
|
||||
export function FigureGallery({ slides }: { slides: Slide[] }) {
|
||||
const [active, setActive] = useState(0);
|
||||
const viewport = useId();
|
||||
const slide = slides[active];
|
||||
if (!slide) return null;
|
||||
|
||||
function move(offset: number) {
|
||||
setActive((current) => (current + offset + slides.length) % slides.length);
|
||||
}
|
||||
|
||||
return (
|
||||
<section
|
||||
className="figure-gallery"
|
||||
role="region"
|
||||
aria-roledescription="轮播"
|
||||
aria-label="文档配图"
|
||||
onKeyDown={(event) => {
|
||||
if ((event.target as HTMLElement).closest("dialog")) return;
|
||||
if (event.key === "ArrowLeft" || event.key === "ArrowRight") {
|
||||
event.preventDefault();
|
||||
move(event.key === "ArrowLeft" ? -1 : 1);
|
||||
}
|
||||
}}
|
||||
>
|
||||
<div
|
||||
id={viewport}
|
||||
role="group"
|
||||
aria-roledescription="幻灯片"
|
||||
aria-label={`第 ${active + 1} 张，共 ${slides.length} 张`}
|
||||
>
|
||||
<ArchitectureFigure key={slide.source} source={slide.source} alt={slide.alt} />
|
||||
</div>
|
||||
<div className="figure-gallery-controls">
|
||||
<button type="button" className="figure-gallery-arrow" aria-label="上一张图片" aria-controls={viewport} onClick={() => move(-1)}>
|
||||
<span aria-hidden="true">‹</span>
|
||||
</button>
|
||||
<div className="figure-gallery-dots" role="group" aria-label="选择图片">
|
||||
{slides.map((item, index) => (
|
||||
<button
|
||||
key={item.source}
|
||||
type="button"
|
||||
className="figure-gallery-dot"
|
||||
aria-label={`显示第 ${index + 1} 张图片`}
|
||||
aria-current={index === active ? "true" : undefined}
|
||||
aria-controls={viewport}
|
||||
onClick={() => setActive(index)}
|
||||
>
|
||||
<span aria-hidden="true" />
|
||||
</button>
|
||||
))}
|
||||
</div>
|
||||
<button type="button" className="figure-gallery-arrow" aria-label="下一张图片" aria-controls={viewport} onClick={() => move(1)}>
|
||||
<span aria-hidden="true">›</span>
|
||||
</button>
|
||||
</div>
|
||||
<p className="sr-only" role="status" aria-live="polite" aria-atomic="true">
|
||||
第 {active + 1} 张，共 {slides.length} 张：{slide.alt}
|
||||
</p>
|
||||
</section>
|
||||
);
|
||||
}
|
||||
@@ -1,5 +1,5 @@
|
||||
import Link from "next/link";
|
||||
import { useRouter } from "next/router";
|
||||
import { CategoryNavigation } from "./CategoryNavigation";
|
||||
import { Icon } from "@/components/Icon";
|
||||
import { useEffect, useRef, useState, type ReactNode } from "react";
|
||||
import type { DocLink } from "@/lib/docs";
|
||||
@@ -69,7 +69,6 @@ export function Shell({
|
||||
current?: string;
|
||||
children: ReactNode;
|
||||
}) {
|
||||
const router = useRouter();
|
||||
const dialog = useRef<HTMLDialogElement>(null);
|
||||
const input = useRef<HTMLInputElement>(null);
|
||||
const trigger = useRef<HTMLButtonElement>(null);
|
||||
@@ -80,7 +79,6 @@ export function Shell({
|
||||
const [selected, setSelected] = useState(0);
|
||||
const [menu, setMenu] = useState(false);
|
||||
const collection = docs.find((d) => d.slug === current)?.collection;
|
||||
const collections = collectionEntries(docs);
|
||||
const results = searchDocs.filter((d) =>
|
||||
(!collection || d.collection === collection) &&
|
||||
`${d.title} ${d.description} ${d.searchText ?? ""}`
|
||||
@@ -125,22 +123,7 @@ export function Shell({
|
||||
</a>
|
||||
<header className="site-header">
|
||||
<Brand />
|
||||
<nav className="top-nav" aria-label="文档选择">
|
||||
<label className="collection-picker">
|
||||
<span className="picker-category">{docs.find((d) => d.slug === current)?.category ?? "全部分类"}</span>
|
||||
<span className="sr-only">选择分类与文档合集</span>
|
||||
<select value={collection ?? ""} onChange={(event) => {
|
||||
const entry = collections.find((c) => c.name === event.target.value)?.entry;
|
||||
void router.push(entry ? `/docs/${entry.slug}` : "/");
|
||||
}}>
|
||||
<option value="">文档中心</option>
|
||||
{[...new Set(docs.map((d) => d.category))].map((category) => <optgroup label={category} key={category}>
|
||||
{collections.filter((c) => c.entry.category === category).map(({name}) => <option value={name} key={name}>{collectionLabel(name)}</option>)}
|
||||
</optgroup>)}
|
||||
</select>
|
||||
<Icon name="chevron" size={13} />
|
||||
</label>
|
||||
</nav>
|
||||
<CategoryNavigation docs={docs} current={current} />
|
||||
<button
|
||||
ref={trigger}
|
||||
className="search-trigger"
|
||||
|
||||
@@ -17,6 +17,7 @@ import remarkGfm from "remark-gfm";
|
||||
import { listDocs, readDoc, type Doc, type DocLink } from "@/lib/docs";
|
||||
import { Shell, Navigation } from "@/components/Shell";
|
||||
import { ArchitectureFigure } from "@/components/ArchitectureFigure";
|
||||
import { FigureGallery } from "@/components/FigureGallery";
|
||||
import { CodeBlock } from "@/components/CodeBlock";
|
||||
import { collectionEntries, collectionLabel } from "@/lib/collections";
|
||||
import { Icon } from "@/components/Icon";
|
||||
@@ -24,16 +25,14 @@ import { headingsFor } from "@/lib/navigation";
|
||||
|
||||
type Props = { doc: Doc; docs: DocLink[] };
|
||||
export const getStaticPaths: GetStaticPaths = async () => ({
|
||||
paths: (await listDocs()).flatMap(({ slug, sourceSlug }) => [...new Set([slug, sourceSlug])].map((value) => ({ params: { slug: value.split("/") } }))),
|
||||
paths: (await listDocs()).map(({ slug }) => ({ params: { slug: slug.split("/") } })),
|
||||
fallback: false,
|
||||
});
|
||||
export const getStaticProps: GetStaticProps<Props> = async ({ params }) => {
|
||||
const slug = Array.isArray(params?.slug) ? params.slug.join("/") : params?.slug;
|
||||
if (typeof slug !== "string") return { notFound: true };
|
||||
const docs = await listDocs();
|
||||
const match = docs.find((d) => d.slug === slug || d.sourceSlug === slug);
|
||||
if (!match) return { notFound: true };
|
||||
if (slug !== match.slug) return { redirect: { destination: `/docs/${match.slug}`, permanent: true } };
|
||||
if (!docs.some((d) => d.slug === slug)) return { notFound: true };
|
||||
return { props: { doc: await readDoc(slug), docs } };
|
||||
};
|
||||
function textOf(value: ReactNode): string {
|
||||
@@ -115,15 +114,30 @@ export default function DocPage({
|
||||
}
|
||||
return <a href={target}>{children}</a>;
|
||||
},
|
||||
p: ({ children, node }) =>
|
||||
node?.children.some(
|
||||
p: ({ children, node }) => {
|
||||
const slides = node?.children.flatMap((child) =>
|
||||
child.type === "element" && child.tagName === "img" &&
|
||||
typeof child.properties.src === "string" &&
|
||||
child.properties.src.startsWith("/figures/endor-")
|
||||
? [{ source: child.properties.src, alt: String(child.properties.alt ?? "") }]
|
||||
: [],
|
||||
) ?? [];
|
||||
const onlyImages = node?.children.every((child) =>
|
||||
(child.type === "element" && child.tagName === "img" &&
|
||||
typeof child.properties.src === "string" &&
|
||||
child.properties.src.startsWith("/figures/endor-")) ||
|
||||
(child.type === "text" && child.value.trim() === ""),
|
||||
);
|
||||
if (slides.length > 1 && onlyImages) return <FigureGallery slides={slides} />;
|
||||
return node?.children.some(
|
||||
(child) =>
|
||||
child.type === "element" && child.tagName === "img",
|
||||
) ? (
|
||||
<div>{children}</div>
|
||||
) : (
|
||||
<p>{children}</p>
|
||||
),
|
||||
);
|
||||
},
|
||||
img: ({ src, alt }) =>
|
||||
typeof src === "string" && src.startsWith("/figures/endor-") ? (
|
||||
<ArchitectureFigure source={src} alt={alt ?? "Endor 架构图"} />
|
||||
|
||||
@@ -1,5 +1,10 @@
|
||||
import { NextResponse, type NextRequest } from "next/server";
|
||||
import { authConfig, SESSION_COOKIE, validSession } from "./lib/auth";
|
||||
import catalog from "../../../content/catalog.json";
|
||||
|
||||
const legacyRoutes = new Map(Object.entries(catalog.documents).map(([source, metadata]) => [
|
||||
`/docs/${source}`, `/docs/${metadata.slug}`,
|
||||
]));
|
||||
|
||||
export function proxy(request: NextRequest) {
|
||||
const path = request.nextUrl.pathname;
|
||||
@@ -49,6 +54,13 @@ export function proxy(request: NextRequest) {
|
||||
);
|
||||
}
|
||||
}
|
||||
// Keep legacy URLs behind authentication and out of static generation.
|
||||
const destination = legacyRoutes.get(path);
|
||||
if (destination && ["GET", "HEAD"].includes(request.method)) {
|
||||
const target = request.nextUrl.clone();
|
||||
target.pathname = destination;
|
||||
return NextResponse.redirect(target, { status: 308, headers });
|
||||
}
|
||||
return NextResponse.next({ headers });
|
||||
}
|
||||
if (path.startsWith("/api/") || !["GET", "HEAD"].includes(request.method)) {
|
||||
|
||||
@@ -882,6 +882,57 @@ button {
|
||||
border-radius: 0;
|
||||
background: transparent;
|
||||
}
|
||||
.figure-gallery {
|
||||
margin: 28px 0;
|
||||
}
|
||||
.figure-gallery .architecture-preview {
|
||||
margin: 0;
|
||||
}
|
||||
.figure-gallery-controls,
|
||||
.figure-gallery-dots {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
}
|
||||
.figure-gallery-controls {
|
||||
gap: 20px;
|
||||
margin-top: 12px;
|
||||
}
|
||||
.figure-gallery-arrow,
|
||||
.figure-gallery-dot {
|
||||
display: grid;
|
||||
place-items: center;
|
||||
min-width: 36px;
|
||||
min-height: 36px;
|
||||
padding: 0;
|
||||
border: 0;
|
||||
border-radius: 50%;
|
||||
color: #57534e;
|
||||
background: transparent;
|
||||
cursor: pointer;
|
||||
}
|
||||
.figure-gallery-arrow {
|
||||
font-size: 28px;
|
||||
line-height: 1;
|
||||
}
|
||||
.figure-gallery-dot span {
|
||||
width: 7px;
|
||||
height: 7px;
|
||||
border-radius: 50%;
|
||||
background: #d6d3d1;
|
||||
}
|
||||
.figure-gallery-dot[aria-current="true"] span {
|
||||
background: #2563eb;
|
||||
}
|
||||
.figure-gallery-arrow:hover,
|
||||
.figure-gallery-dot:hover {
|
||||
background: #f5f5f4;
|
||||
}
|
||||
.figure-gallery-arrow:focus-visible,
|
||||
.figure-gallery-dot:focus-visible {
|
||||
outline: 2px solid #2563eb;
|
||||
outline-offset: 2px;
|
||||
}
|
||||
.image-lightbox {
|
||||
width: 100vw;
|
||||
height: 100dvh;
|
||||
@@ -1268,11 +1319,6 @@ svg { flex-shrink: 0; }
|
||||
--font-reading: "Charter", "Iowan Old Style", "Songti SC", "STSong", "Noto Serif CJK SC", serif;
|
||||
--font-code: "SFMono-Regular", Consolas, "Liberation Mono", "PingFang SC", monospace;
|
||||
}
|
||||
.collection-picker { display: flex; flex-wrap: wrap; align-items: center; position: relative; min-width: 180px; max-width: 280px; }
|
||||
.collection-picker select { appearance: none; width: 100%; cursor: pointer; padding: 8px 30px 8px 12px; border: 1px solid var(--line); border-radius: 6px; background: var(--soft); font: inherit; font-size: 13px; color: var(--ink); text-overflow: ellipsis; }
|
||||
.picker-category { width: 100%; font-size: 10px; line-height: 1.4; color: var(--muted); margin-bottom: 2px; }
|
||||
.collection-picker > svg { position: absolute; right: 10px; bottom: 12px; pointer-events: none; transform: rotate(90deg); color: var(--muted); }
|
||||
.collection-picker select:focus-visible { outline: 2px solid var(--green); outline-offset: 3px; }
|
||||
.top-nav { margin-left: 0; }
|
||||
.sidebar { padding: 22px 16px 32px; }
|
||||
.collection-identity { font-size: 14px; gap: 9px; margin: 0 8px 20px; }
|
||||
@@ -1296,8 +1342,42 @@ svg { flex-shrink: 0; }
|
||||
}
|
||||
@media (max-width: 760px) {
|
||||
.top-nav { overflow: visible; }
|
||||
.collection-picker { width: 100%; max-width: 100%; }
|
||||
.picker-category { display: none; }
|
||||
.collection-picker select { padding-block: 6px; }
|
||||
.mobile-navigation .nav-group { margin-top: 16px; }
|
||||
}
|
||||
|
||||
/* Categories stay visible across the header, each with its own disclosure panel. */
|
||||
.top-nav.category-navigation { position: relative; display: flex; margin-left: 0; gap: 0; }
|
||||
.category-navigation > ul { display: flex; align-items: stretch; gap: 22px; height: 100%; list-style: none; padding: 0; margin: 0; }
|
||||
.category-navigation > ul > li { display: flex; align-items: stretch; }
|
||||
.category-menu { position: relative; }
|
||||
.category-navigation .category-home, .category-trigger { display: flex; align-items: center; gap: 6px; color: var(--muted); font-family: var(--font-sans); font-size: 13px; white-space: nowrap; }
|
||||
.category-trigger { position: relative; padding: 0; background: transparent; cursor: pointer; }
|
||||
.category-trigger > svg { transform: rotate(90deg); transition: transform 160ms; }
|
||||
.category-trigger[aria-expanded="true"] > svg { transform: rotate(-90deg); }
|
||||
.category-trigger:hover, .category-trigger[aria-expanded="true"], .category-trigger[data-active="true"] { color: var(--ink); }
|
||||
.category-trigger[data-active="true"]::after { content: ""; position: absolute; bottom: 0; left: 0; right: 0; height: 2px; background: var(--green); }
|
||||
.category-trigger:focus-visible, .category-navigation a:focus-visible { outline: 2px solid var(--green); outline-offset: 4px; border-radius: 3px; }
|
||||
.category-panel { position: absolute; top: 100%; left: -16px; width: 320px; padding: 12px; background: #fdfefd; border: 1px solid var(--line); border-radius: 0 0 10px 10px; box-shadow: 0 16px 40px #24352b1a; z-index: 50; }
|
||||
.category-panel[hidden] { display: none; }
|
||||
.category-menu:last-child .category-panel { left: auto; right: -16px; }
|
||||
.category-panel-title { margin: 3px 10px 8px; font-size: 11px; color: var(--muted); }
|
||||
.top-nav .category-panel a { display: flex; align-items: flex-start; gap: 12px; padding: 12px 10px; white-space: normal; border-radius: 6px; color: var(--ink); }
|
||||
.top-nav .category-panel a::after { display: none; }
|
||||
.category-panel a:hover, .category-panel a[aria-current] { background: var(--accent-wash); }
|
||||
.category-panel a > svg { margin-top: 2px; color: var(--green); }
|
||||
.category-panel strong { display: block; font-size: 13px; font-weight: 550; line-height: 1.5; }
|
||||
.category-panel small { display: block; margin-top: 4px; font-size: 12px; line-height: 1.6; color: var(--muted); }
|
||||
@media (min-width: 761px) and (max-width: 1100px) {
|
||||
.site-header { gap: 20px; }
|
||||
.category-navigation > ul { gap: 16px; }
|
||||
.category-navigation .category-home, .category-trigger { font-size: 12px; }
|
||||
.search-trigger { width: 36px; height: 34px; padding: 8px; justify-content: center; }
|
||||
.search-trigger span, .search-trigger kbd { display: none; }
|
||||
}
|
||||
@media (max-width: 760px) {
|
||||
.top-nav.category-navigation { overflow: visible; }
|
||||
.category-navigation > ul { width: 100%; gap: 18px; }
|
||||
.category-navigation .category-home, .category-trigger { font-size: 12px; }
|
||||
.category-menu { position: static; }
|
||||
.category-panel, .category-menu:last-child .category-panel { width: auto; left: 0; right: 0; }
|
||||
}
|
||||
|
||||
@@ -58,6 +58,22 @@
|
||||
"slug": "language-and-runtime/object-relations/object-graphs-gc",
|
||||
"category": "语言与运行时"
|
||||
},
|
||||
"06-agent-programming-draft": {
|
||||
"collection": "Agent 编程",
|
||||
"group": "研究与提案",
|
||||
"description": "从指令重解释、组合边界与灵活性取舍，讨论 Agent 编程抽象。",
|
||||
"draft": true,
|
||||
"slug": "language-and-runtime/agent-programming/from-instructions-to-composition",
|
||||
"category": "语言与运行时"
|
||||
},
|
||||
"07-composable-judgments-draft": {
|
||||
"collection": "Agent 编程",
|
||||
"group": "研究与提案",
|
||||
"description": "比较 LangGraph 与 DSPy，探索判断对象、依据变化与局部重算。",
|
||||
"draft": true,
|
||||
"slug": "language-and-runtime/agent-programming/composable-judgments",
|
||||
"category": "语言与运行时"
|
||||
},
|
||||
"pretext/00-overview": {
|
||||
"description": "理解高性能文本布局的原理，沿着 12 章教程阅读源码。",
|
||||
"featured": true,
|
||||
|
||||
@@ -16,4 +16,27 @@ pnpm figures
|
||||
|
||||
CI 会重新生成图片并检查与提交版本一致。Python 依赖保留独立缓存，不进入生产运行镜像。
|
||||
|
||||
图形应使用本地字体与资源，并明确标注草案状态。未来可按具体需求加入自动布局、PNG 转换或 TypeScript SVG 工具。
|
||||
图形应使用本地字体与资源，并明确标注草案状态。未来可按具体需求加入自动布局或 TypeScript SVG 工具。
|
||||
|
||||
## 位图默认发布压缩版本
|
||||
|
||||
SVG 保留可编辑矢量格式；漫画、照片等位图的原始 PNG、JPEG 放在 `tools/figures/assets`，不放进 `public`。浏览器只使用生成的 WebP，正文、点击放大和图片适应屏幕都使用同一个压缩地址。
|
||||
|
||||
共享策略位于 `content/image-policy.json`：默认最大宽度 1600 像素、WebP 质量 82、每张图最多 192 KiB，不放大小图。修改策略后重新生成并检查公式、细线和小字是否清晰。
|
||||
|
||||
以下涉及图像编码与构建产物生成的命令在已确认的远程 CI/CD runner 上执行；未获明确许可时不在用户本机运行。
|
||||
|
||||
```sh
|
||||
pnpm --filter @endor/docs images
|
||||
pnpm --filter @endor/docs test:images
|
||||
```
|
||||
|
||||
原图相对 `tools/figures/assets` 的路径会映射到 `apps/docs/public/figures` 下同名的 `.webp`。例如 `endor-review-gate.png` 对应 `/figures/endor-review-gate.webp`。文档只嵌入后一个地址，制作原稿不随网页发布。
|
||||
|
||||
远程生产构建会运行压缩脚本；CI 先生成 WebP，再重新编码核对产物与原稿、策略是否一致。WebP 是构建派生文件，不必在本机生成或提交；Git 保存原稿、制作记录与共享策略。检查同时拒绝公开目录里的原始位图及 Markdown 图片或 HTML img 直接引用的原始 PNG、JPEG。SVG 无需转成位图，仍按前述流程提交可编辑输出。
|
||||
|
||||
## 同一位置切换多张配图
|
||||
|
||||
把两张或更多 `/figures/endor-` 图片写在同一段，中间换行但不插入空行，正文会将它们呈现为图组。左右按钮和键盘左右方向键可以切换，下方圆点表示当前图片，也可点击直接选择。图片保留点击放大能力。
|
||||
|
||||
图组一次只挂载当前图片，切换后才加载下一张压缩图，不预先下载整组原图。
|
||||
|
||||
@@ -16,6 +16,54 @@
|
||||
|
||||
这一定位希望形成的体验是：**对象池构成持续可用的工作世界，Agent 成为其中执行工作的主体，Endor 语言让对象和行为能够被表达、检查与组合。** 用户与 AI 因而可以在同一套对象基础上发起、接续和检查工作。这是本文的设计方向，不表示所有系统能力已经实现。
|
||||
|
||||
## 让产出成为检查下一次产出的帮手
|
||||
|
||||
|
||||
|
||||
|
||||
两张漫画用检查门与检查台表达同一个目标，可用左右按钮或下方圆点切换。
|
||||
|
||||
上方把 Coding Agent 比作一台不断吐出工作结果的机器。机器可以持续产出，但人的时间和精力没有同步增长；等待检查的材料越积越多。虚线圈出的 **∫dW** 表示累积的待处理工作，门上的 **C₀** 表示在这个对比中保持不变的检查能力。通过门、带上勾的文件才表示已处理的结果。
|
||||
|
||||
下方的机器吐出同样的原始文件，改变的是 Endor 如何组织和接续这些产出。人和检查门直接面对的是这次新增的 **dW**；已经处理的文件被组织成有类型、来源、关系与可调用能力的对象，成为图里的蓝色帮手。帮手的箭头指向检查门，表达它们为后续检查提供支持，而不是让新生成的结果自己证明自己正确。
|
||||
|
||||
例如，已确认的需求可以成为验收条件；稳定的接口约定可以帮助发现不兼容修改；图片发布规则可以检查下一份文档有没有直接嵌入原图。**过去的产出从待处理的负担，逐步变成帮助人处理新工作的能力。** 新结果是否符合要求，仍需要适用的检查逻辑与人的判断。
|
||||
|
||||
门上的 **C₀ + k∫dW** 表示我们希望实现的积累效应：在原有能力上，增加由历史成果转化而来的可复用检查能力。这里的积分、微分和系数 k 是设计隐喻，不是性能公式或实测结论；只有经过确认、适合复用并保持有效的成果才能贡献能力，产出数量不等于正确性，实际检查也可能需要重新覆盖受影响的历史对象。
|
||||
|
||||
> **设计目标**：这张漫画表达希望建立的工作组织方式，不表示当前 Endor 已能自动把任意文件变成检查工具。要兑现它，需要保存来源和依赖、表达检查规则、执行检查，并把失败与待确认事项呈现给人。
|
||||
|
||||
## 从压缩图片想到的继承：让要求成为共同能力
|
||||
|
||||
这张漫画也带来一个具体要求：**文档在浏览器中默认使用压缩图，原图留作制作与归档，不因打开正文或放大图片就下载原图。** 如果很多文档都需要这条规则，用户不应该每次写文档时重新提醒一次。
|
||||
|
||||
单次 Coding Agent 对话中的“记得压缩图片”，通常首先是一项需要读取、理解和落实的指令。指令可以放进项目约定、技能或模板，也可以让 Agent 写出共享压缩脚本；这些都能减少重复劳动。但一句自然语言要求本身，并没有自动建立“这类文档如何派生、谁沿用默认行为、哪个文档允许覆盖”的类型与行为关系。这里讨论的是这种**可持续、可检查的继承**，不是说 Agent 不能编写使用继承的程序。
|
||||
|
||||
### 为什么 Endor 的设计能承载继承
|
||||
|
||||
在现有设计中，文档、图片、类型定义、函数和 Agent 都进入同一对象体系。对象具有可引用的身份，类型可以表达对象的结构与能力，函数可以表达处理行为；继承、实例化与代码依赖可以保存为有不同含义的关联。因此，“默认如何发布文档图片”可以被表达为一个可引用的共同定义，以及读取和执行它的行为，而不只是一段随对话流逝的提醒。
|
||||
|
||||
沿着这个设计方向，可以把图片发布要求放到共享文档类型或其呈现策略上：普通文档沿用“优先压缩图”的默认行为，需要精确查看像素的专业文档再显式采用另一种策略。具体通过类型继承、策略对象委托还是能力组合实现，需要结合语言规则确定；不是因为对象之间有一个链接，就天然获得了继承。
|
||||
|
||||
| 层次 | 压缩图例子中承担的职责 |
|
||||
| --- | --- |
|
||||
| 共同定义 | 保存默认图片尺寸、编码质量、字节预算及浏览器应使用的派生版本 |
|
||||
| 继承或委托关系 | 让采用共同定义的文档持续引用它，明确哪些行为来自共同来源 |
|
||||
| 实际处理能力 | 根据策略生成压缩版本，保留它与原图的来源关系，并让呈现入口选择压缩版本 |
|
||||
| 检查与覆盖 | 检查新产出是否符合默认要求；特例显式选择覆盖，并能说明生效的规则来自哪里 |
|
||||
|
||||
关键不只是“记住用户偏好”，而是**规则有归属，使用者有关系，行为可以执行，结果能够检查**。当 Agent 新建同类文档时，它使用已有文档能力与策略，就能让之前确认的要求继续参与这次工作；人主要判断本次差异和真正的例外。这也是漫画里历史成果增强检查门的一个具体例子。
|
||||
|
||||
定义和依赖是对象，使系统有基础追踪受影响的文档，并通过名称、类型与调用检查发现部分不一致；图片编码与发布仍需实际运行相应能力。“一切皆对象”本身不保证每份文档都调用正确的渲染器，也不自动决定规则修改后是否追溯更新历史文档。
|
||||
|
||||
> **语义边界**：继承与委托、覆盖与冲突规则仍在[语言设计问题集的对象模型部分](/docs/language-design/05-questions)讨论中。父定义更新如何生效、文档是否绑定特定版本、多来源冲突如何处理，需要明确后才能成为稳定承诺。这里解释 Endor 为什么有承载这类继承的共同基础，以及希望形成的体验，不宣称这些规则已全部实现。
|
||||
|
||||
### 本站现在怎样落实这条规则
|
||||
|
||||
Tabularium 目前用共享构建策略落实这项要求：原图保存在非公开的制作目录，脚本统一生成有尺寸、质量与字节预算的 WebP，文档正文和放大查看都使用这个压缩版本。新增文档直接引用生成的图片，不需要逐篇重新实现压缩；构建检查会拒绝公开原始位图或直接嵌入原始 PNG、JPEG。
|
||||
|
||||
这是今天在文档仓库里可以执行和验证的共享规则，具体工作流见[图形与脚本](/docs/03-figures)。它示范了“把一次提醒变成后续工作可复用的能力”，并不表示 Tabularium 这个 Next.js 网站已经运行了 Endor 的继承机制。
|
||||
|
||||
## 一对图：我们希望改变什么
|
||||
|
||||
|
||||
@@ -284,4 +332,6 @@ Endor 也不应仅凭对象之间可连接，就宣称用户可以无损迁移
|
||||
|
||||
这一版先把程序入口、对象、操作权、AI 与语言之间的关系串起来。后续可以用真实工作流修订这些描述，进一步确定对象身份、执行与挂载的语义。
|
||||
|
||||
[从给 AI 写教程，到组合 AI 能力](/docs/language-and-runtime/agent-programming/from-instructions-to-composition)进一步记录指令重解释、组合边界与灵活性的三个问题；[LangGraph、DSPy 与可接续的判断对象](/docs/language-and-runtime/agent-programming/composable-judgments)比较现有探索，并提出依据变化后复核与局部重算的原型方向。两篇均为讨论草案，不表示现有语言或运行时已经实现。
|
||||
|
||||
[系统架构](/docs/00-endor-concepts-draft)讨论部署与存储，[节点与对象挂载](/docs/02-mounting-draft)讨论运行位置和挂载边界；本文关注它们为何能给用户带来值得验证的变化。
|
||||
|
||||
@@ -0,0 +1,83 @@
|
||||
# 从给 AI 写教程，到组合 AI 能力
|
||||
|
||||
记录日期：2026 年 10 月 28 日。本文保存关于 Agent 编程抽象的讨论，重点是指令的重新解释、能力的组合边界，以及约束与灵活性的取舍。
|
||||
|
||||
> **讨论草案**：文中的分析和候选机制尚未成为 Endor 语言规范，也不表示 Aster、Hestia 或其他组件已经实现。对外部项目的事实描述附官方来源；设计判断与后续提案分别说明。
|
||||
|
||||
## 我们真正追问的是什么
|
||||
|
||||
为什么很多 Agent 扩展仍像是给 AI 的教程？传统编程发展出函数、对象、函数式组合和状态管理方法，Agent 是否也应该发展出可以理解、测试和组合的能力单元？
|
||||
|
||||
**关键区别在于：代码中的抽象有运行机制支撑，而很多 Agent 抽象的效果，仍然依赖模型理解并遵守一段话。**
|
||||
|
||||
函数的局部变量受到作用域规则约束，模块可以控制导出内容，React Hooks 的状态与调用有框架机制支撑。这些机制并不能自动证明业务逻辑正确，却让开发者有明确的执行规则可依赖。
|
||||
|
||||
如果在 skill 中写“这段规则只对当前任务有效，不得影响其他任务”，它首先还是一条需要模型遵守的指令。只有宿主系统真正隔离了上下文、存储或权限，才形成相应的执行边界。**把一段话放进文件夹，获得了组织和复用能力，却不等于获得了封装。**
|
||||
|
||||
这里不能把 skill 与 MCP 完全等同：Agent Skills 用 Markdown 指导、可选脚本和资源打包任务知识；MCP 还规范工具发现、调用、资源与消息交换，具有真实的协议机制。但协议不替宿主决定模型怎样组织推理。[Agent Skills 规范](https://agentskills.io/specification)、[MCP 架构](https://modelcontextprotocol.io/docs/learn/architecture)
|
||||
|
||||
## 第一，结构在每次推理中被重新解释
|
||||
|
||||
自然语言把大量原来需要开发者提前定义的步骤，交给模型临时组织。用户说“检查合同，找出对我不利的条款”，模型能够补出搜索、比较、解释等步骤，不必先穷举每个分支。这使教程式扩展具有实际价值：便宜、灵活，也能承载尚未形式化的经验。
|
||||
|
||||
**但代价是，结构没有明确保存在程序里，而是在每次推理时由模型重新解释。因此，增加一个 skill，可能改变另一个 skill 的使用方式；换一个模型，原来有效的指令可能表现不同。**
|
||||
|
||||
这里说的是仅由自然语言承担的结构。skill 随附脚本、宿主的工具权限和明确的数据流，仍可以由普通代码实现硬边界，不能把整个 Agent 系统都说成没有结构。
|
||||
|
||||
需要区分三件事：指导内容是否被正确加载，模型是否按预期理解，执行环境是否强制实施约束。改进第一件事，不自动完成后两件事。
|
||||
|
||||
一个值得探索的方向是把“能力的公开输入与输出”“本次可见的数据”“允许产生的外部效果”显式表示。自然语言继续描述意图，系统承担能够检查的边界。模型升级时，对相同任务重新评估，而不是假定文件格式相同就行为兼容。
|
||||
|
||||
## 第二，AI 能力还缺少容易验证的组合边界
|
||||
|
||||
假设有三个能力：
|
||||
|
||||
1. A：查找资料。
|
||||
2. B：判断资料是否可信。
|
||||
3. C：写成报告。
|
||||
|
||||
把它们串起来很容易。难的是确保：
|
||||
|
||||
- B 拒绝的资料不会又被 C 使用。
|
||||
- C 能区分“原文事实”和“模型推断”。
|
||||
- A 没找到证据时，后续不会把空缺补成事实。
|
||||
|
||||
传统代码也不能自动保证业务正确，但可以控制显式数据流。例如 C 只收到 B 允许传递的证据引用，检索工具也只能读取这一集合。如果三个阶段只是向同一个上下文添加文字，“通过”和“拒绝”可能都只是模型看得到的文本。
|
||||
|
||||
**模块之间存在名称上的边界，却未必存在执行上的边界。**
|
||||
|
||||
可验证边界不等于“保证模型不知道被拒绝的事情”。模型可能在预训练中已经接触过相关信息，也可能凭一般知识推断。可实现的约束是限制本次输入、检索权限和可接受输出；要求报告中的事实主张指向获准证据，再检查关联是否有效。证据是否真正支持主张，仍需要独立评估或人工判断，不能只检查引用 ID 存在。
|
||||
|
||||
还要区分“来源可信”和“支持某个结论”：一份可靠文件可以被错误解读，也可能对另一个问题毫无证明力。审核应该说明对象、版本、问题范围与判断依据。
|
||||
|
||||
## 第三，把 AI 约束得足够明确，又可能损失它最有价值的灵活性
|
||||
|
||||
把流程完全固定成状态机，可以获得更明确的行为，但也要求开发者提前定义更多场景。反过来，让模型自由决定，就重新依赖它对指令的解释。
|
||||
|
||||
这不是无解，而是需要找出：哪些地方应该由系统确定，哪些地方值得留给模型判断。不同任务的答案还不一样，因此很难很快出现一套统一范式。
|
||||
|
||||
固定状态机只是取舍的一端。图执行也可以动态分支，模型也可以在受限环境中自主选择路径；不能把所有框架描述成僵硬流程。
|
||||
|
||||
一个候选划分是：**把可用材料、权限、预算和结果接纳条件固定下来，把寻找解法的路径留给模型。** 模型可以换检索策略、拆分问题和请求更多材料，但不能通过修改提示词给自己新增写权限，也不能把尚未审核的结果自行标成业务事实。
|
||||
|
||||
这仍需要具体任务检验：接纳条件过强可能拒绝有用结果，过弱可能放过错误；某些开放式创作没有唯一验收答案，应保留人工评价和不确定状态。
|
||||
|
||||
## 从指导语句到可执行的规则
|
||||
|
||||
| 常见指导 | 可以落实的机制 | 仍未解决的部分 |
|
||||
| --- | --- | --- |
|
||||
| 不要把资料当成指令 | 分开传递资料与控制配置，资料不能授予工具权限 | 提示注入仍可能影响内容判断，不能只靠分隔符解决 |
|
||||
| 只记住当前项目 | 按项目划分存储与检索范围，读取时检查身份 | 共享模型本身不因此遗忘已有知识 |
|
||||
| 交给另一个 Agent 做 | 显式传入对象、权限、预算和返回契约 | 子任务是否理解业务目标仍需评估 |
|
||||
| 确认以后才能发布 | 发布接口检查有效审批及对应内容版本 | 人的审批是否充分，不能由接口自动证明 |
|
||||
| 每个结论都要有证据 | 结论关联证据版本并检查引用有效性 | 证据是否充分、结论是否成立仍需判断 |
|
||||
|
||||
这些机制有些可以直接用现有语言实现。研究重点应是把它们变成一致、可复用的运行约定，而不是只增加新术语或语法。
|
||||
|
||||
## 对 Endor 的意义
|
||||
|
||||
Endor 已在设计讨论中把对象池、对象身份和 Agent 任务联系起来。这为表达证据、判断和结果之间的关系提供了切入点，但不能从“一切皆对象”推导出隔离、授权、持久化和业务正确性已经成立。
|
||||
|
||||
下一步可以讨论：一个判断是否应成为关联输入版本、检查记录与适用范围的对象？依据变化时，下游工作怎样知道需要复核？同一能力更换模型后，哪些行为需要重新验证？
|
||||
|
||||
更深入的外部方案比较、候选机制与原型验收，见[LangGraph、DSPy 与可接续的判断对象](/docs/language-and-runtime/agent-programming/composable-judgments)。项目整体定位见[Endor 的意义](/docs/endor/endor-purpose-draft)。
|
||||
@@ -0,0 +1,180 @@
|
||||
# LangGraph、DSPy 与可接续的判断对象
|
||||
|
||||
记录日期：2026 年 10 月 28 日。本文从[Agent 编程的三个问题](/docs/language-and-runtime/agent-programming/from-instructions-to-composition)继续讨论：已有探索为什么有价值，边界在哪里，以及 Endor 可以验证什么。
|
||||
|
||||
> **研究与设计草案**：官方机制、本文的分析和候选设计在各节中区分。下文没有确认新语言语法、对象内置类型或权限规范；没有修改现有 271 项语言设计议题的确认状态，也没有实现运行时功能。资料按本文日期查阅，具体 API 会演进。
|
||||
|
||||
## 两条路线分别解决了什么
|
||||
|
||||
LangGraph 把状态、节点和转移显式组织起来；DSPy 把模型任务表示为签名和模块，并根据指标优化程序。它们分别使执行过程更可管理、模型行为更可测量。它们也可以组合使用，并不是相互排斥的完整替代品。
|
||||
|
||||
| 维度 | LangGraph | DSPy | 本文进一步提出的问题 |
|
||||
| --- | --- | --- | --- |
|
||||
| 组织单位 | 状态、节点、边与子图 | 任务签名、模块与模型程序 | 一项判断能否跨流程保留身份、依据与适用范围 |
|
||||
| 关键进步 | 显式组织路径、状态与恢复 | 分离任务声明、调用策略与优化 | 如何接纳、复用及作废一个结果 |
|
||||
| 可获得的检查 | 图结构、状态约束、应用代码检查 | 输出结构、约束验证、数据集上的指标 | 证据版本、权限、业务条件与变化后的复核 |
|
||||
| 不会自动成立的事情 | 节点执行过不代表业务判断正确 | 得分提高不代表每次都满足真实需求 | 有来源也不代表内容真实或推理正确 |
|
||||
|
||||
## LangGraph 为什么好
|
||||
|
||||
### 从聊天历史走向明确的执行状态
|
||||
|
||||
官方 Graph API 把工作流组织为 State、Nodes 和 Edges，并用 reducer 规定更新怎样合入状态。它还支持输入、输出及内部状态的不同组织方式。这让开发者可以明确决定数据传到哪里，而不必把所有东西拼接成一段聊天。[Graph API](https://docs.langchain.com/oss/python/langgraph/graph-api)
|
||||
|
||||
其价值是把一部分程序结构从模型的临时理解中拿回来：例如审核节点产生的允许集合，由普通代码选择后再提供给写作节点。
|
||||
|
||||
### 让中断与长期工作可以被管理
|
||||
|
||||
checkpointer 保存线程的图状态，store 保存跨线程数据；持久化实现的选择决定重启后是否还能接续。interrupt 支持等待外部输入，恢复时可能重新执行节点开头的代码，因此调用者必须处理重入和副作用。[Persistence](https://docs.langchain.com/oss/python/langgraph/persistence)、[Interrupts](https://docs.langchain.com/oss/python/langgraph/interrupts)
|
||||
|
||||
这是真实的执行能力，不只是“请记住进度”的指导。它让人可以在工作中间介入，而不必完全重开任务。
|
||||
|
||||
### 保留动态决策空间
|
||||
|
||||
LangGraph 有条件转移、动态路由和子图，节点里也可以包含开放式 Agent。不能把它批评成“只能预先画死全部步骤”。其强项在于让确定性逻辑和模型判断出现在一个可组织的执行过程里。[Graph API 的 Command](https://docs.langchain.com/oss/python/langgraph/graph-api#command)
|
||||
|
||||
## LangGraph 为什么还没有回答完这个问题
|
||||
|
||||
以下是对职责边界的分析，并不是说 LangGraph 无法用应用代码实现这些能力。
|
||||
|
||||
**流程状态不自动等于业务世界的有效状态。** checkpoint 可以保存“审核完成”，但被审核文件之后可能已经修改，或者用户已经撤回了授权。恢复执行时是否重读、复核和拒绝过期结果，需要应用定义。
|
||||
|
||||
**状态结构不自动等于信息安全边界。** 节点输入过滤有实际价值，但不能仅凭字段叫 private 就假设它不会进入日志、流输出或其他路径；数据访问、工具访问和输出通道仍需检查。一个图也可以做严格隔离，只是隔离不能由图形名称推导。
|
||||
|
||||
**检查节点不能天然证明上游结论。** 模型审核也可能犯错，与生成者共享偏差。增加一个 reviewer 节点是一种策略，实际效果要用独立样例和人工核验评估。
|
||||
|
||||
**跨任务的判断复用需要共同约定。** 两张图都产生“供应商通过审核”，是否针对同一公司、同一资料版本、同一政策和时间范围？这些业务关系可以加入 state 和数据库，但各应用往往还需自行定义。
|
||||
|
||||
因此，应继续利用图的执行能力，同时把跨流程可用的结果关系设计清楚。新做一个流程编辑器，未必解决这些问题。
|
||||
|
||||
## DSPy 为什么好
|
||||
|
||||
### 把任务声明与求解策略分开
|
||||
|
||||
Signature 声明输入、输出及任务意图；Module 组织调用策略。同一任务可以更换求解方式而保留接口。这让“我们要什么结果”和“模型如何尝试完成”更容易分别修改。[Signatures in depth](https://dspy.ai/3.4.1/diving-deeper/signatures-in-depth/)
|
||||
|
||||
例如，可以把证据列表到候选结论表示为一个模块，在相同输入集上比较不同策略，而不必重写整个应用。
|
||||
|
||||
### 让改进从手调措辞走向可测量的优化
|
||||
|
||||
DSPy 的优化器接受程序、指标和样例，根据反馈调整指令、示例，某些优化路径还涉及模型权重。这让提示词成为可优化的实现，而不是只能凭直觉维护的字符串。[DSPy 优化器官方文档源码](https://github.com/stanfordnlp/dspy/blob/main/docs/docs/learn/optimization/optimizers.md)
|
||||
|
||||
真正值得借鉴的是对“好不好”的显式追问：必须给出数据和评估方法，才能比较优化前后的程序。
|
||||
|
||||
## DSPy 为什么还没有回答完这个问题
|
||||
|
||||
**结构类型和业务成立条件不同。** 输出符合字段与类型要求，不说明结论受证据支持。“供应商可靠”可以是合法字符串，却没有包含可靠性的范围、依据和时效。增加业务字段有帮助，字段内容仍需要检验。
|
||||
|
||||
**指标是目标的可测量代理。** 如果只奖励引用数量，系统可能更愿意多加引用，而没有提高引用的支持程度。需要分别评估正确性、覆盖、证据支持、拒答、成本和耗时，并使用独立保留样本，避免只追逐一个总分。
|
||||
|
||||
**离线优化与在线条件之间存在距离。** 真实对象会变化，工具可能失败，权限可能收回，用户目标也会调整。验证集上的改进不能自动替代每次行动前的状态与授权检查。
|
||||
|
||||
**换模型后的可替换性仍需验证。** 接口兼容不等于行为兼容；优化产物需要连同模型配置、数据集与评估记录版本化。更强模型可能减少某些提示策略的必要性，也可能改变结果分布。
|
||||
|
||||
这些并不削弱 DSPy 的价值。它提供了进行比较和优化的机制；把它当作业务真理的证明器，才是越过了其能力边界。
|
||||
|
||||
## 我们可以补上的一层：让判断成为可接续的对象
|
||||
|
||||
候选方向是让 Agent 产出的判断，成为后续程序可以检查、组合和更新的工作对象。重点不在新的提示词容器，而在输出被其他任务使用时仍保留必要关系。
|
||||
|
||||
一项判断可以包含以下信息。字段仅用于原型讨论，不是已确认的内置类型。
|
||||
|
||||
| 信息 | 例子 | 能检查什么 |
|
||||
| --- | --- | --- |
|
||||
| 主张与范围 | 供应商 A 满足本次采购的材料要求 | 区分不同问题，避免把局部结论扩成全面认可 |
|
||||
| 输入对象及版本 | 营业文件 v3、报价单 v8 | 判断产生时实际使用了哪些材料 |
|
||||
| 证据关联 | 某项要求对应文件的哪些位置 | 引用是否存在，是否为允许使用的材料 |
|
||||
| 判断性质 | 原文摘录、计算结果、推断、人工确认 | 不把不同可靠性来源压成一个字符串 |
|
||||
| 生成与检查记录 | 模型配置、程序版本、检查规则与结果 | 复核、模型替换和实验追溯 |
|
||||
| 适用条件 | 政策版本、对象版本、复核期限 | 条件变化时识别需要重新检查的结果 |
|
||||
| 后续使用关系 | 报告段落、采购建议、候选任务 | 沿已记录依赖定位可能受影响的工作 |
|
||||
|
||||
这里的“可接纳”始终相对于明确政策与检查过程，不命名为无条件的“已证实事实”。模型自报的置信度也不能当作校准后的正确率。
|
||||
|
||||
### 把研究、提案与真实修改分开
|
||||
|
||||
模型可以自主探索、重试和比较方案，但先在隔离的候选工作区里产生结果与变更意图。准备提交时，由运行环境检查材料版本、当前授权、接纳条件和影响范围，再实际调用修改能力。
|
||||
|
||||
候选工作区可以采用写时复制、事件记录或暂存对象实现，选型尚未确定。它不是整个互联网的快照，也不能回滚已经发出的邮件或外部付款。外部读取可能计费或写日志，也应纳入效果清单；无法模拟的动作需要单独定义提交方式。
|
||||
|
||||
## 一个更有吸引力的体验：修改依据，工作能够局部更新
|
||||
|
||||
把前文的 A 查资料、B 审核、C 写报告，继续推进到一个用户可感知的场景：
|
||||
|
||||
1. AI 用三份资料形成报告，每个需要依据的结论关联具体来源版本。
|
||||
2. 用户发现第二份资料有误，将其从本次允许集合移除。
|
||||
3. 系统沿记录的依赖标出相关结论、报告段落和待提交任务；旧结果保留为历史，但不再作为当前有效依据。
|
||||
4. Agent 可以寻找替代证据、缩小结论或报告材料不足；与这份资料无关且仍满足条件的结果可以复用。
|
||||
5. 用户看到需要复核的内容、新旧结论和候选变更，确认后再更新正式对象。
|
||||
|
||||
**用户感知到的变化是：改一份依据，就能知道哪些判断需要复核，并接着完成这些工作。** 对开发者而言，可复用单元从一段生成文本，变成带输入、条件和检查记录的判断过程。
|
||||
|
||||
这借用了电子表格重算、增量构建、数据血缘和版本控制的成熟思想，不声称发明了依赖跟踪。需要验证的新价值是：这些关系能否在用户、模型与不同流程之间共同使用，减少每个应用手写一套更新逻辑的成本。
|
||||
|
||||
### 必须承认的限制
|
||||
|
||||
- 系统只能沿已记录的依赖传播失效，不能自动理解并发现全部语义影响。模型偷偷使用了未记录输入时，依赖图会不完整；原型应限制数据入口并记录读取，必要时保守地复核整个产物。
|
||||
- “读取过”不等于“真正依赖”。粗粒度跟踪可能重算过多，细粒度声明可能漏记，需要衡量漏失效与过度失效。
|
||||
- 版本变化只说明旧条件不再完全匹配，不代表旧结论必然错误。应标为待复核，而不是宣称系统已发现事实错误。
|
||||
- 重算不保证得到相同结果。回放历史记录与重新调用模型是两回事，外部服务和模型行为也可能变化。
|
||||
- 本地候选分支可丢弃，不等于全部业务效果可撤销。跨系统提交需要各自支持版本检查、幂等或补偿，否则必须暴露部分完成状态。
|
||||
|
||||
## 怎样形成真正的组合边界
|
||||
|
||||
下面的概念接口只表达职责，不是 Endor 已有或拟定语法，也不是可运行代码。
|
||||
|
||||
```text
|
||||
查找(问题, 允许的数据源) -> 资料引用与版本 | 材料不足
|
||||
审核(资料, 问题, 审核政策) -> 本次允许的证据集合 | 需要人工判断
|
||||
生成(问题, 允许的证据集合) -> 候选结论与证据关联
|
||||
接纳(候选结论, 检查政策) -> 接纳记录 | 拒绝原因 | 无法确定
|
||||
准备(接纳记录, 目标对象版本) -> 候选变更
|
||||
提交(候选变更, 当前授权, 版本前置条件) -> 实际效果记录 | 冲突 | 部分完成
|
||||
```
|
||||
|
||||
这些阶段不要求固定成六次模型调用；查找与生成可以动态循环，审核也可以由确定性规则、模型和人工共同完成。受限的是数据与效果边界，解题路径仍可自主选择。
|
||||
|
||||
“接纳记录”不能只是让模型在 JSON 中填写 `accepted: true`。原型可让受信任的检查服务生成记录，并在每次使用时验证记录所属项目、对象版本、政策与有效期。它能证明检查过程发生过，不能证明自然语言结论永远正确。权限应沿用项目既有授权体系，不能通过候选结果自动扩大。
|
||||
|
||||
## 与 Endor 对象模型怎样衔接
|
||||
|
||||
这项提案与[Endor 的对象操作定位](/docs/endor/endor-purpose-draft)有连接点：材料、判断、候选变更、任务可以保留独立身份和关系，而不只存在于某个聊天上下文或图执行记录中。
|
||||
|
||||
候选职责划分如下，仍需逐项设计和确认：
|
||||
|
||||
| 层次 | 候选职责 | 不应声称自动完成的事情 |
|
||||
| --- | --- | --- |
|
||||
| 语言与类型 | 表达输入、结果分支、对象引用和可调用能力 | 仅靠类型名证明自然语言主张 |
|
||||
| 对象与存储 | 保存身份、版本、关系和历史 | 自动发现所有语义依赖 |
|
||||
| 运行环境 | 限制效果、检查当前授权与提交前置条件 | 跨任意外部系统提供统一事务 |
|
||||
| 模型与模块 | 解释目标、探索方案、生成候选判断 | 自行授予权限或给自己签发可信结论 |
|
||||
| 检查与人 | 定义接纳条件、核验内容、处理不能确定的情况 | 用一次总分覆盖全部业务风险 |
|
||||
|
||||
先用现有语言和接口验证这些机制，再决定哪些值得进入 Endor 语言。不要先把假设写成语法，再用语法存在证明系统有价值。
|
||||
|
||||
## 最小原型与公平比较
|
||||
|
||||
第一版只选“资料到报告，依据撤回后继续修订”这一条工作流。使用有限的版本化资料集和一个可检查版本的报告存储，不接真实付款或邮件，也不扩展成万能 Agent 平台。
|
||||
|
||||
对照组采用认真实现的 LangGraph + DSPy 应用，允许它使用显式输入过滤、持久化、同样的检查器及自定义依赖记录；实验组使用相同模型、材料、预算和检查政策，增加可复用的判断对象与依赖处理层。对照组也能实现相同行为，比较重点是重复代码、集成工作量和变更后的可靠性，而不是把对照组故意降成一个长提示词。
|
||||
|
||||
| 实验 | 需要观察的结果 |
|
||||
| --- | --- |
|
||||
| 撤回一份材料 | 下游是否还有引用被撤回依据的当前有效结果；受影响项是否漏标 |
|
||||
| 修改材料中的一个事实 | 哪些产物需要复核，哪些可以复用；是否产生过度失效 |
|
||||
| 模型替换 | 固定任务上的质量、拒答、成本与耗时怎样变化；既有检查能否复用 |
|
||||
| 中断与重试 | 是否继续正确任务，重复提交是否被目标端拒绝或去重 |
|
||||
| 提交前版本变化 | 是否报告冲突或重新验证，避免覆盖用户新修改 |
|
||||
| 收回写权限 | 接续任务是否重新检查并拒绝写入；历史审批不能覆盖当前授权 |
|
||||
| 来源不支持结论 | 结构检查能否通过，独立内容审核能否识别错误；如实记录漏检 |
|
||||
| 增加第二个工作流 | 需要重复编写多少字段、失效传播、权限和接纳逻辑 |
|
||||
|
||||
先保存基线数据，再预先确定可接受门槛和独立评估集，不凭最顺利的演示设定标准。分别记录内容质量、来源支持、失效覆盖、过度重算、人工介入、模型与工具成本、延迟和开发工作量；不要把它们合成一个无法解释的“智能分数”。
|
||||
|
||||
原型如果不能降低第二条工作流的实现成本，或只是增加很多对象却没有减少错误和复核负担，就说明这层抽象还没有证明价值。如果 LangGraph + DSPy 的直接实现已经足够清晰，则优先沉淀薄库和约定，不必新造完整运行时。
|
||||
|
||||
## 当前建议
|
||||
|
||||
**保留 LangGraph 对执行的组织能力、DSPy 对模型程序的优化能力；探索让判断的依据、适用条件和后续影响成为共同的对象关系。**
|
||||
|
||||
最值得做的演示不是更多 Agent 同时对话，而是用户修改一份依据后，系统解释哪些工作受到影响、哪些仍可复用，并让 AI 在受约束的空间里继续完成修订。这项体验能否用更少的应用专用代码实现，才是继续投入的依据。
|
||||
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"maxWidth": 1600,
|
||||
"quality": 82,
|
||||
"maxBytes": 196608
|
||||
}
|
||||
+1
-1
@@ -13,7 +13,7 @@
|
||||
"lint": "pnpm --filter @endor/docs run lint",
|
||||
"typecheck": "pnpm --filter @endor/docs run typecheck",
|
||||
"figures": "uv run --locked --project tools/figures endor-figures",
|
||||
"check": "pnpm run lint && pnpm run typecheck && pnpm run test:auth && pnpm run figures && pnpm run build",
|
||||
"check": "pnpm run lint && pnpm run typecheck && pnpm run test:auth && pnpm --filter @endor/docs run images && pnpm --filter @endor/docs run test:images && pnpm run figures && pnpm run build",
|
||||
"test:auth": "pnpm --filter @endor/docs run test:auth"
|
||||
}
|
||||
}
|
||||
|
||||
Generated
+4
-3
@@ -59,6 +59,9 @@ importers:
|
||||
postcss:
|
||||
specifier: 8.5.31
|
||||
version: 8.5.31
|
||||
sharp:
|
||||
specifier: 0.35.5
|
||||
version: 0.35.5(@types/node@22.20.5)
|
||||
tailwindcss:
|
||||
specifier: 4.3.3
|
||||
version: 4.3.3
|
||||
@@ -2876,8 +2879,7 @@ snapshots:
|
||||
|
||||
'@humanwhocodes/retry@0.4.3': {}
|
||||
|
||||
'@img/colour@1.1.0':
|
||||
optional: true
|
||||
'@img/colour@1.1.0': {}
|
||||
|
||||
'@img/sharp-darwin-arm64@0.35.5':
|
||||
optionalDependencies:
|
||||
@@ -5184,7 +5186,6 @@ snapshots:
|
||||
'@img/sharp-win32-ia32': 0.35.5
|
||||
'@img/sharp-win32-x64': 0.35.5
|
||||
'@types/node': 22.20.5
|
||||
optional: true
|
||||
|
||||
shebang-command@2.0.0:
|
||||
dependencies:
|
||||
|
||||
@@ -6,6 +6,8 @@ uv sync --project tools/figures --locked
|
||||
pnpm run lint
|
||||
pnpm run typecheck
|
||||
pnpm --filter @endor/docs run test:auth
|
||||
pnpm --filter @endor/docs run images
|
||||
pnpm --filter @endor/docs run test:images
|
||||
cp -R apps/docs/public/figures /tmp/expected-figures
|
||||
pnpm run figures
|
||||
uv run --locked --project tools/figures python -m unittest discover -s tools/figures/tests -v
|
||||
|
||||
+1
-1
@@ -27,7 +27,7 @@ def verify(base: str) -> None:
|
||||
assert status == 200 and json.loads(health) == {"status": "ok"}
|
||||
status, _, login = get("/login")
|
||||
assert status == 200 and "输入动态码" in login.decode()
|
||||
for path in ("/", "/docs/00-endor-concepts-draft", "/figures/endor-architecture.svg", "/docs/pretext/01-chapter", "/materials/pretext/verify.cjs", "/materials/pretext/results.chrome156.json"):
|
||||
for path in ("/", "/docs/00-endor-concepts-draft", "/figures/endor-architecture.svg", "/figures/endor-review-gate.webp", "/figures/endor-review-desk.webp", "/docs/pretext/01-chapter", "/materials/pretext/verify.cjs", "/materials/pretext/results.chrome156.json"):
|
||||
status, headers, _ = get(path)
|
||||
assert status == 307, path
|
||||
target = urllib.parse.urlparse(urllib.parse.urljoin(base, headers["Location"]))
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 1.7 MiB |
@@ -0,0 +1,14 @@
|
||||
Endor inspection desk comic — approved second slide
|
||||
|
||||
Source: built-in image_gen; physics inspection-bench variant with corrected top-row flow.
|
||||
Original: exec-432e0f3d-d01d-4658-b5d5-0c63db95e472.png
|
||||
The user selected this alongside the gate variant for one carousel.
|
||||
|
||||
The two identical machines emit raw papers. Above, a dashed integral dW boundary
|
||||
encloses the backlog BEFORE one person's fixed-capacity C0 inspection desk.
|
||||
Below, a dashed dW boundary encloses the one new paper being inspected. Earlier
|
||||
checked outputs become structured document helpers that contribute additional
|
||||
magnifiers to the Endor desk, whose capacity is C0 + k integral dW.
|
||||
|
||||
Store this PNG as the production master outside public. The confirmed remote
|
||||
runner generates /figures/endor-review-desk.webp using content/image-policy.json.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 1.4 MiB |
@@ -0,0 +1,20 @@
|
||||
Endor review gate comic — approved source
|
||||
|
||||
Source: built-in image_gen, physics gate variant, approved by the user on 2026-10-28.
|
||||
Original: exec-380f8db3-6450-4981-97df-473c13a62223.png
|
||||
The PNG is the production master, not a public browser asset.
|
||||
The confirmed remote runner generates the browser WebP with:
|
||||
pnpm --filter @endor/docs images
|
||||
|
||||
Visual specification:
|
||||
Two rows, white background, charcoal outlines, blue accents, identical coding
|
||||
machines emitting identical raw sheets. Top: accumulated unchecked sheets inside
|
||||
a dashed integral dW boundary, one person and a fixed C0 inspection gate, checked
|
||||
output after the gate. Bottom: one new sheet inside a dashed dW boundary directly
|
||||
inspected by a stick figure at an Endor gate. Gate capacity is C0 + k integral dW.
|
||||
Checked output becomes a structured document helper, joins historical helpers,
|
||||
and blue arrows from helpers feed the gate to increase inspection capability.
|
||||
No dialogue or explanatory prose. Math is a conceptual metaphor, not measured data.
|
||||
|
||||
The bitmap master retains the approved artwork, including its mathematical
|
||||
symbols. Browser optimization changes encoding and dimensions only.
|
||||
Reference in New Issue
Block a user