奇链 奇链
← Agent Skills 目录 / 设计与创意
3k Simon-He95

markstream-vue Skill

将 markstream-vue 集成到 Vue 3 应用中。当 Codex 需要添加 Vue 3 渲染器、按正确顺序导入 CSS、选择渲染器和 DOM 模式、选择内置/普通/自定义代码块路径、在 `content` 和 `nodes` 之间选择、通过 `MarkstreamVirtualTimeline`、`useMarkstreamVirtualAdapter` 或 `vue-virtual-scroller` 协调较长的 AI 时间线、启用 stream-diffs、Mermaid、KaTeX、D2 或 Infographic 等可选依赖,或在非 Nuxt 的 Vue 仓库中接入作用域自定义组件时使用。

安装方式:把技能目录放入 ~/.claude/skills/(Claude Code)或在 claude.ai 设置中启用;也可复制右侧安装命令一键添加。

查看源码

技能指令原文(SKILL.md)

Markstream Vue 3

Use this skill when the host app is plain Vue 3, typically Vite-based, and not Nuxt.

Workflow

  1. Confirm the repo is Vue 3 and not Nuxt.
  2. Install markstream-vue plus only the optional peers required by the requested features.
  3. Import markstream-vue/index.css after resets.
  • In Tailwind or UnoCSS projects, use @import 'markstream-vue/index.css' layer(components);.
  • The root JS import does not inject styles; use markstream-vue/index.css or markstream-vue/index.px.css explicitly.
  1. Start with content and choose the renderer mode by surface.
  • Use mode="chat" for AI chat or SSE output. It uses lightweight batches, fade=false, and max-live-nodes=0; smooth-streaming="auto" paces visible output.
  • Use mode="docs" for rich document surfaces. It is the default and enables larger batches, tooltips, and fade.
  • Use mode="minimal" when the surface is lightweight but not chat.
  • Regular fenced code uses the built-in CodeBlockNode, enhanced by stream-diffs when that optional peer is installed and otherwise falling back to 
    . Set render-code-blocks-as-pre=true to force the plain path, or replace code_block through scoped setCustomComponents(...) when the app owns the renderer.
  • Use dom-mode="minimal" only when the surface can also disable wrapper-dependent features such as fade, batching, deferral, virtualization, typewriter, and custom components; otherwise it falls back to full DOM.
  • typewriter only controls the blinking cursor and defaults to false. Prefer typewriter="simple" for high-frequency chat and precise mode for complex inline cursor placement.
  • Set :smooth-streaming="false" to preserve raw chunk cadence; set :smooth-streaming="true" to force smooth pacing even on first-screen content (may cause hydration mismatch in SSR).
  • In Vue 3 (including Nuxt), smooth-streaming controls output pacing and fade controls opacity; they can be enabled together. mode="chat" keeps fade=false as a lightweight default. Add fade when gradual text reveal is desired; keep it off when animation cost matters more. Vue 3 append fades use stable batches (200 ms, 50 ms coalescing window, at most four batches per text node); later appends do not restart earlier batches.
  • Streaming vs recovering history: in chat UIs the same MarkdownRender starts streaming and later switches to history when final=true.
  • Streaming: start with mode="chat" and final; add fade for text reveal and typewriter only when a cursor is wanted.
  • Recovering/completed chat history: keep mode="chat" on the same chat row to avoid switching layout strategy when final=true; use :smooth-streaming="false", typewriter=false, and choose fade independently for the desired entry/reveal effect. Do not bind it to the inverse of streaming state unless that visual policy is intentional.
  • Use mode="minimal" for lightweight non-chat recovered content, and use mode="docs" only for rich document surfaces, not for finalizing an existing chat message.
  • Switch to nodes plus final only when the app needs custom AST control, worker preparsing, or structural updates beyond pacing.
  • Remember that html-policy now defaults to safe, and Mermaid strict mode is on by default through mermaid-props.
  1. For long AI transcripts or existing message virtualizers, choose the virtual-scroll path.
  • Prefer MarkstreamVirtualTimeline when the app does not already own timeline virtualization.
  • If the app already uses vue-virtual-scroller DynamicScroller, use useMarkstreamVirtualAdapter() and bind adapter.markdownProps(item, index) to Markdown items.
  • Put adapter.measureItem(item, index, el) on the outer timeline row so row chrome is included in item height.
  • Use Markstream's reported logical height (metrics.totalHeight through the adapter/virtualizer), not the renderer element's current offsetHeight, because Markdown node virtualization may only mount the live window.
  • On thread switches, save adapter.captureThreadState() together with the scroller cache; restore the scroller cache before restoring the Markstream anchor.
  1. Use custom-id plus scoped setCustomComponents(...) for local overrides, or import { VueRendererMarkdown } from markstream-vue and install it when the repo already has an app-level plugin entry.
  2. Validate with the smallest useful dev, build, or typecheck command.

Default Decisions

  • Vue 3 apps default to content; choose mode before fine-tuning lower-level render props.
  • Omit mode only when the surface should use rich docs defaults.
  • Smooth streaming (smooth-streaming="auto") is on by default when typewriter or max-live-nodes <= 0. It only paces the content path; nodes mode is never affected.
  • For manual pacing with nodes, use useSmoothMarkdownStream directly: enqueue() chunks, finish() when done, render from visible, and wait for caughtUp before final parsing.
  • For a non-virtual chat scroller that should follow streaming output, import useStickToBottom from markstream-vue/utils and call scheduleScrollToBottom() after Vue commits new content. It coalesces writes and preserves manual scrollback; do not run scrollIntoView({ behavior: 'smooth' }) for every token. For long mixed timelines, use MarkstreamVirtualTimeline with stick-to-bottom="auto" instead.
  • Streaming vs recovering history: keep the same renderer mode for a given chat row; completed history can disable pacing/cursor; fade is an independent visual choice and may remain enabled throughout streaming and completion. Switch to mode="docs" only when moving content into a separate rich document surface. See docs/guide/ai-chat-streaming.md for full examples.
  • Prefer local component registration unless the repo already uses a shared plugin entry.
  • If a Vue 3 app already virtualizes messages, keep that outer virtualizer in charge and enable virtual-scroll only on large Markdown messages.
  • For vue-virtual-scroller, keep sessionKey tied to content identity (thread:item:revision) and measurementKey tied to layout identity such as width, theme, font, and density.
  • When enhanced code blocks need app-level preloading, use preloadCodeBlockRuntime. For intentional low-level controller use, import the advanced API directly from stream-diffs; do not depend on a raw-runtime getter from markstream-vue.
  • The Vue 3 enhanced code surface uses stream-diffs only; do not install stream-monaco.
  • For large code blocks (tens of thousands of lines) in Vue 3, offload Shiki tokenization to Web Workers by injecting an upstream @pierre/diffs WorkerPoolManager via setStreamDiffsWorkerPool(...) from markstream-vue. The host builds the pool with its own bundler (@pierre/diffs/worker/worker.js?worker) and adds @pierre/diffs as a direct dependency; markstream-vue forwards it as the workerManager runtime option and syncs the active isDark/theme/themes theme to the pool on every change. Without injection, or when the pool reports itself unavailable, highlighting stays on the main thread (unchanged behavior). Do not bundle or spawn the worker inside the library.
  • Configure the built-in surface through top-level code-block-options or direct CodeBlockNode.codeBlockOptions. Keep header/toolbar props in code-block-props; Markstream retains ownership of theme, code/language, streaming lifecycle, header, mount/reveal timing, and disposal.
  • Keep html-policy="safe" and Mermaid strict mode unless the task is explicitly preserving trusted legacy behavior.
  • If a trusted surface needs pre-hardening behavior, opt out locally with html-policy="trusted" and :mermaid-props="{ isStrict: false }", and call out the trust boundary in the final handoff.
  • If the host is actually Nuxt, leave SSR-specific setup to markstream-nuxt.

Useful Doc Targets

  • docs/guide/quick-start.md
  • docs/guide/installation.md
  • docs/guide/usage.md
  • docs/guide/ai-chat-streaming.md
  • docs/guide/performance.md
  • docs/guide/component-overrides.md
  • docs/guide/code-block-runtime.md