qqzhangyanhua/learn-opencode-agent

Purpose and Runtime

This is a Chinese AI-agent engineering learning site, not an agent runtime. It publishes structured tutorials, source-code analyses, runnable TypeScript exercises, decision guides, and interactive visualizations. It runs on Bun with VitePress/Vue; production serves the built static site through Caddy on port 3000. Key entry points: package.json, .vitepress/config.mts, Caddyfile.

Site Composition and Navigation

VitePress configuration defines routing, navigation, sidebars, search, and page metadata; the documentation tree supplies route-backed Markdown content. The homepage and major hubs direct learners into OpenCode analysis, practice, intermediate topics, selection guidance, animation lab, interviews, and enterprise-agent material. Paths: docs/index.md, docs/discover/index.md, docs/learning-paths/index.md.

Theme Application Layer

The custom Vue theme is the client-side presentation and interaction boundary. It registers globally usable educational components, provides layout behavior, and owns site-wide styling and legacy selection-route redirects. Markdown pages embed these components rather than owning application logic. Paths: .vitepress/theme/index.ts, .vitepress/theme/Layout.vue, .vitepress/theme/custom.css, .vitepress/theme/agent-selection-redirects.ts.

Structured Content Data

Theme data modules are the canonical structured inputs for content-driven experiences: discovery, learning paths, practice catalogs, and animation scenarios. UI hubs consume this data to render cards, routes, progress, and simulations; content additions often require synchronized Markdown, data, and navigation updates. Paths: .vitepress/theme/data/content-index.data.ts, .vitepress/theme/data/learning-paths.data.ts, .vitepress/theme/data/practice-projects.ts.

Interactive Simulation System

Interactive teaching demos model Agent workflows in Vue, with scenario/state logic separated from rendering in several features. The animation laboratory is explicitly data-driven: experiment definitions feed a shared canvas/player rather than independent navigation or bespoke pages. Some scenario modules have colocated unit tests, making state transitions a tested boundary. Paths: .vitepress/theme/components/animation-lab/FlowExperimentCanvas.vue, .vitepress/theme/data/animation-lab-experiments.ts, .vitepress/theme/components/flowScenario.ts.

Educational Content Domains

Markdown is organized as independently navigable curricula: core OpenCode material, source-analysis series for Claude Code and Hermes, enterprise-agent design, practices, intermediate topics, selection guides, and interview resources. The docs are static source content; references to external Agent systems are explanatory source snapshots, not bundled integrations. Paths: docs/02-agent-core/index.md, docs/new-claude/part-1-主业务流/04-query-主循环如何驱动整个系统.md, docs/enterprise-agent/index.md.

Runnable Practice Boundary

Practice scripts are standalone TypeScript learning artifacts paired one-to-one with practice documentation and catalog metadata. They demonstrate concepts such as tool use, RAG, planning, MCP, multi-agent coordination, and deployment, rather than acting as services used by the site. MCP is represented by a dedicated server example. Paths: practice/p01-minimal-agent.ts, practice/p14-mcp-server.ts, docs/practice/p14-mcp/index.md.

Quality and Delivery Pipeline

Node/Bun scripts enforce cross-boundary consistency: required content metadata, navigation and hub entry reachability, practice-to-doc mappings, learning data, and animation registrations. build:strict sequences these checks before the static build; TypeScript checking focuses on the VitePress theme. Output is .vitepress/dist/, then Caddy serves it. Paths: scripts/check.sh, scripts/check-practice-entries.mjs, scripts/check-animation-lab.mjs.