auricui-skill 0.0.0-stage → 0.1.2

package/skill/assets/upstream/packages/shared/src/markdown-blocks.ts

@@ -0,0 +1,252 @@
+/**
+ * Markdown → blocks and inline pieces: parsing only, no DOM; each view decides its own sizes and colors.
+ *
+ * Deliberately not CommonMark: a chat reply grows token by token and is parsed again each time, so the rules are small.
+ * Half-written syntax (an open ``` fence, a lone `**`) reads as not finished yet: plain text for now, never an error.
+ */
+
+export type MarkdownBlock =
+  | { kind: 'heading'; level: number; text: string; id: string }
+  | { kind: 'paragraph'; text: string }
+  | { kind: 'quote'; text: string }
+  /** `start`: an ordered list's first number, when not 1 (items split by blank lines would all read "1."). */
+  | { kind: 'list'; ordered: boolean; lines: string[]; start?: number }
+  | { kind: 'code'; language: string; text: string }
+  | { kind: 'table'; rows: string[][] }
+  | { kind: 'hr' };
+
+/** What ends a paragraph: the line starts a block of another kind. */
+const BLOCK_START = /^(#{1,6}\s|```|[-*]\s|\d+\.\s|\||>)/;
+
+/** A block and the line it starts on (incremental parsing rescans from there). */
+export interface ScannedBlock {
+  block: MarkdownBlock;
+  startLine: number;
+}
+
+function headingSlugBase(text: string): string {
+  return text.trim().toLowerCase()
+    .replace(/[^\w\u4e00-\u9fff]+/g, '-')
+    .replace(/^-|-$/g, '') || 'section';
+}
+
+/**
+ * Scans from line `from` to the end (starting midway keeps unchanged blocks as the same objects; see rescanMarkdown).
+ * `priorHeadings` are the kept headings' texts, so heading ids stay unique across the whole text.
+ */
+export function scanMarkdownBlocks(
+  lines: string[],
+  from = 0,
+  priorHeadings: readonly string[] = [],
+): ScannedBlock[] {
+  const blocks: ScannedBlock[] = [];
+  const slugCount = new Map<string, number>();
+  for (const heading of priorHeadings) {
+    const base = headingSlugBase(heading);
+    slugCount.set(base, (slugCount.get(base) ?? 0) + 1);
+  }
+  let start = from;
+  const push = (block: MarkdownBlock) => { blocks.push({ block, startLine: start }); };
+  const pushHeading = (level: number, raw: string) => {
+    const clean = raw.trim();
+    const base = headingSlugBase(clean);
+    const n = slugCount.get(base) ?? 0;
+    slugCount.set(base, n + 1);
+    push({ kind: 'heading', level, text: clean, id: n ? `${base}-${n + 1}` : base });
+  };
+  let i = from;
+  while (i < lines.length) {
+    const raw = lines[i] ?? '';
+    const trimmed = raw.trim();
+    if (!trimmed) { i += 1; continue; }
+    // blank lines belong to no block: a block starts on this line
+    start = i;
+    if (trimmed.startsWith('```')) {
+      const language = trimmed.slice(3).trim();
+      const code: string[] = [];
+      i += 1;
+      // an unclosed fence runs to the end: normal while streaming
+      while (i < lines.length && !(lines[i] ?? '').trim().startsWith('```')) {
+        code.push(lines[i] ?? '');
+        i += 1;
+      }
+      i += 1;
+      push({ kind: 'code', language, text: code.join('\n') });
+      continue;
+    }
+    if (/^---+$/.test(trimmed)) { push({ kind: 'hr' }); i += 1; continue; }
+    const heading = /^(#{1,6})\s+(\S.*)$/.exec(trimmed);
+    if (heading) { pushHeading(heading[1]!.length, heading[2]!); i += 1; continue; }
+    if (trimmed.startsWith('>')) {
+      const quoted: string[] = [];
+      while (i < lines.length) {
+        const ct = (lines[i] ?? '').trim();
+        if (!ct.startsWith('>')) break;
+        // one level only: a nested `>` stays in the text
+        quoted.push(ct.replace(/^>\s?/, ''));
+        i += 1;
+      }
+      push({ kind: 'quote', text: quoted.join('\n').trim() });
+      continue;
+    }
+    if (trimmed.startsWith('|') && trimmed.endsWith('|') && i + 1 < lines.length) {
+      const sep = (lines[i + 1] ?? '').trim();
+      if (/^\|[\s:-]+\|/.test(sep)) {
+        const rows: string[][] = [];
+        while (i < lines.length) {
+          const row = (lines[i] ?? '').trim();
+          if (!row.startsWith('|') || !row.endsWith('|')) break;
+          if (/^\|[\s:-]+\|/.test(row)) { i += 1; continue; }
+          rows.push(row.replace(/^\||\|$/g, '').split('|').map((c) => c.trim()));
+          i += 1;
+        }
+        push({ kind: 'table', rows });
+        continue;
+      }
+    }
+    if (/^[-*]\s/.test(trimmed) || /^\d+\.\s/.test(trimmed)) {
+      const ordered = /^\d+\.\s/.test(trimmed);
+      const start = ordered ? Number(/^(\d+)\./.exec(trimmed)![1]) : 1;
+      const acc: string[] = [];
+      while (i < lines.length) {
+        const ct = (lines[i] ?? '').trim();
+        if (ordered ? /^\d+\.\s/.test(ct) : /^[-*]\s/.test(ct)) {
+          acc.push(ct.replace(ordered ? /^\d+\.\s/ : /^[-*]\s/, ''));
+          i += 1;
+        } else break;
+      }
+      push({ kind: 'list', ordered, lines: acc, ...(ordered && start !== 1 ? { start } : {}) });
+      continue;
+    }
+    const para = [trimmed];
+    i += 1;
+    while (i < lines.length) {
+      const ct = (lines[i] ?? '').trim();
+      if (!ct || BLOCK_START.test(ct)) break;
+      para.push(ct);
+      i += 1;
+    }
+    // newlines inside a paragraph are kept: whether they are spaces or breaks is the view's choice
+    push({ kind: 'paragraph', text: para.join('\n') });
+  }
+  return blocks;
+}
+
+/** A scan and the text it was made from (the next scan checks whether it can continue). */
+export interface MarkdownScan {
+  text: string;
+  blocks: ScannedBlock[];
+}
+
+/**
+ * The first block that must be rescanned: the ones before it cannot change, whatever is appended.
+ *
+ * Only a boundary at a blank line is stable (a list can still grow when its next line becomes `- item`); headings and
+ * rules are one line, so the boundary after them is stable too. With no stable boundary, everything is rescanned.
+ */
+function frozenBefore(blocks: readonly ScannedBlock[], lines: readonly string[]): number {
+  for (let k = blocks.length - 1; k > 0; k -= 1) {
+    const kind = blocks[k - 1]!.block.kind;
+    if (kind === 'heading' || kind === 'hr') return k;
+    const start = blocks[k]!.startLine;
+    if (start > 0 && !(lines[start - 1] ?? '').trim()) return k;
+  }
+  return 0;
+}
+
+/**
+ * Continues the previous scan: only the part that may still change is rescanned (see frozenBefore); earlier blocks keep
+ * their identity, so memoized views skip them. Text that does not extend the previous one is scanned whole.
+ */
+export function rescanMarkdown(prev: MarkdownScan | null, text: string): MarkdownScan {
+  if (prev && prev.text === text) return prev;
+  const lines = text.split('\n');
+  if (!prev || prev.blocks.length === 0 || !text.startsWith(prev.text)) {
+    return { text, blocks: scanMarkdownBlocks(lines) };
+  }
+  const from = frozenBefore(prev.blocks, lines);
+  if (from === 0) return { text, blocks: scanMarkdownBlocks(lines) };
+  const kept = prev.blocks.slice(0, from);
+  const priorHeadings = kept
+    .map((entry) => (entry.block.kind === 'heading' ? entry.block.text : null))
+    .filter((heading): heading is string => heading !== null);
+  const rest = scanMarkdownBlocks(lines, prev.blocks[from]!.startLine, priorHeadings);
+  return { text, blocks: kept.concat(rest) };
+}
+
+export type MarkdownInline =
+  | { kind: 'text'; text: string }
+  | { kind: 'code'; text: string }
+  | { kind: 'strong'; text: string }
+  | { kind: 'em'; text: string }
+  | { kind: 'link'; text: string; href: string };
+
+/**
+ * Inline tokens. Code comes first (`` `**x**` `` is code, not emphasis). Italics take a single `*` only, never `_`,
+ * which would split identifiers like `file_path`.
+ */
+const INLINE_TOKEN = /`([^`]+)`|\*\*([^*]+)\*\*|\*([^*\s][^*]*)\*|\[([^[\]\n]*)\]\(([^()\s]*)\)/g;
+
+/** A line → inline pieces. Anything not recognized stays plain text, so half-written syntax spoils nothing. */
+export function parseInlineMarkdown(text: string): MarkdownInline[] {
+  const out: MarkdownInline[] = [];
+  const pushText = (chunk: string) => {
+    if (!chunk) return;
+    const last = out[out.length - 1];
+    if (last?.kind === 'text') last.text += chunk;
+    else out.push({ kind: 'text', text: chunk });
+  };
+  // a global regex keeps its position: start from the beginning each time
+  INLINE_TOKEN.lastIndex = 0;
+  let cursor = 0;
+  let match: RegExpExecArray | null;
+  while ((match = INLINE_TOKEN.exec(text))) {
+    const token = matchToInline(match, text);
+    if (!token) {
+      // not a fit (half syntax, an unsafe link): rescan from the next character; these characters stay text
+      INLINE_TOKEN.lastIndex = match.index + 1;
+      continue;
+    }
+    pushText(text.slice(cursor, match.index));
+    out.push(token);
+    cursor = match.index + match[0]!.length;
+  }
+  pushText(text.slice(cursor));
+  return out;
+}
+
+function matchToInline(match: RegExpExecArray, text: string): MarkdownInline | null {
+  // groups that did not match are undefined
+  const [, code, strong, em, linkText, href]: (string | undefined)[] = match;
+  if (code !== undefined) return { kind: 'code', text: code };
+  if (strong !== undefined) return { kind: 'strong', text: strong };
+  if (em !== undefined) {
+    // next to another `*` it is not italics (inside `**bold**`, or a glob like `**/*.tsx`)
+    if (text[match.index - 1] === '*' || text[match.index + match[0]!.length] === '*') return null;
+    if (/\s$/.test(em)) return null;
+    return { kind: 'em', text: em };
+  }
+  if (linkText !== undefined && href !== undefined) {
+    const safe = safeMarkdownHref(href);
+    if (!safe || !linkText.trim()) return null;
+    return { kind: 'link', text: linkText, href: safe };
+  }
+  return null;
+}
+
+/**
+ * Allowed link targets: http(s) and relative paths only; anything else (`javascript:`, `data:` …) is null and shows as
+ * text. The text is model output, so untrusted. Control characters and spaces are removed before the scheme is checked,
+ * as a browser would, so `java\nscript:` does not slip through.
+ */
+export function safeMarkdownHref(raw: string): string | null {
+  const href = raw.trim();
+  if (!href) return null;
+  const probe = href.replace(/[\u0000-\u0020\u00a0\u2028\u2029]/g, '').toLowerCase();
+  if (!probe) return null;
+  // `//host` leaves the site: not a relative path
+  if (probe.startsWith('//')) return null;
+  const scheme = /^([a-z][a-z0-9+.-]*):/.exec(probe)?.[1];
+  if (scheme && scheme !== 'http' && scheme !== 'https') return null;
+  return href;
+}

package/skill/assets/upstream/packages/shared/src/modality.ts

@@ -0,0 +1,4 @@
+/** What kind of thing a turn makes. Only `video` (a film arranged by film.json) for now. */
+export const MODALITIES = ['video'] as const;
+
+export type Modality = (typeof MODALITIES)[number];

package/skill/assets/upstream/packages/shared/src/prompt-reference.ts

@@ -0,0 +1,113 @@
+/**
+ * The things a message points at (its "pills"), as they are sent and stored.
+ *
+ * Two things here cross process boundaries:
+ *
+ *   1. The token. A pill in the text is an invisible token (`⁣<id>⁣`), and that string is stored with the
+ *      turn, so its shape is a format, not a component's private detail.
+ *   2. What a pill keeps so it can be drawn again. See `promptReferenceSchema`.
+ *
+ * The text sent to the model is not this: the client expands pills into plain words (file paths, "[1: beat 2 0:04]").
+ * This is what the person saw in the composer; both are kept.
+ */
+import { z } from 'zod';
+
+/** The token mark: `U+2063 INVISIBLE SEPARATOR` on both sides of the id. Nobody types it, and a stray one is invisible. */
+export const PROMPT_REFERENCE_MARK = '⁣';
+
+export function promptReferenceToken(id: string): string {
+  return `${PROMPT_REFERENCE_MARK}${id}${PROMPT_REFERENCE_MARK}`;
+}
+
+/* A new one each time: a `g` regex remembers where it stopped. */
+function tokenPattern(): RegExp {
+  return new RegExp(`${PROMPT_REFERENCE_MARK}([^${PROMPT_REFERENCE_MARK}]+)${PROMPT_REFERENCE_MARK}`, 'g');
+}
+
+export type PromptTextSegment =
+  | { kind: 'text'; value: string }
+  | { kind: 'reference'; id: string };
+
+/** Splits tokenized text into alternating text and reference segments (the composer and the chat use the same split). */
+export function splitPromptReferenceText(text: string): PromptTextSegment[] {
+  const segments: PromptTextSegment[] = [];
+  let cursor = 0;
+  for (const match of text.matchAll(tokenPattern())) {
+    const at = match.index ?? 0;
+    if (at > cursor) segments.push({ kind: 'text', value: text.slice(cursor, at) });
+    segments.push({ kind: 'reference', id: match[1]! });
+    cursor = at + match[0].length;
+  }
+  if (cursor < text.length) segments.push({ kind: 'text', value: text.slice(cursor) });
+  return segments;
+}
+
+/** The text without its tokens: what the person actually typed. */
+export function stripPromptReferenceTokens(text: string): string {
+  return text.replace(tokenPattern(), '');
+}
+
+/**
+ * What a pill keeps: enough to draw it and to go back to what it points at.
+ *
+ * `kind` is any string, not an enum: a kind the reader does not know falls back to a generic icon instead of failing.
+ */
+export const promptReferenceSchema = z.object({
+  /** The same id as in the text's token. */
+  id: z.string().min(1).max(512),
+  kind: z.string().min(1).max(32),
+  /** The pill's label (a file name, a beat, a skill's title). */
+  label: z.string().min(1).max(200),
+  /** A short suffix, e.g. a time like 0:12. */
+  detail: z.string().max(64).optional(),
+  /**
+   * A thumbnail: `src` is the host's own address; `crop` is the part it points at, in pixels of `stage` (the image
+   * shows the whole stage).
+   */
+  image: z.object({
+    src: z.string().min(1).max(2048),
+    crop: z.object({ x: z.number(), y: z.number(), w: z.number(), h: z.number() }).optional(),
+    stage: z.object({ w: z.number(), h: z.number() }).optional(),
+  }).optional(),
+  /** What it points at, in the host's own shape (e.g. a Studio reference). Stored and returned as is. */
+  target: z.record(z.string(), z.unknown()).optional(),
+});
+export type PromptReference = z.infer<typeof promptReferenceSchema>;
+
+/** Limits for a field kept only for display (the product's own limit is on the expanded text). */
+export const PROMPT_DISPLAY_MAX_CHARS = 50_000;
+export const PROMPT_DISPLAY_MAX_REFERENCES = 64;
+
+/** A message as it looked in the composer. */
+export const promptDisplaySchema = z.object({
+  /** The text with its tokens. */
+  text: z.string().min(1).max(PROMPT_DISPLAY_MAX_CHARS),
+  /** The pills its tokens point at, in order. A token with no pill is dropped when drawn. */
+  references: z.array(promptReferenceSchema).max(PROMPT_DISPLAY_MAX_REFERENCES),
+});
+export type PromptDisplay = z.infer<typeof promptDisplaySchema>;
+
+/**
+ * The composer view of a message, or undefined when it has no pills (then it equals the sent text).
+ *
+ * `references` is the sender's whole pool; only the ones still in the text are kept (an undo may have removed one).
+ * Over a limit, nothing is kept rather than a partial list: the expanded text still reads whole.
+ */
+export function buildPromptDisplay(
+  text: string,
+  references: readonly PromptReference[],
+): PromptDisplay | undefined {
+  const byId = new Map(references.map((item) => [item.id, item]));
+  const used: PromptReference[] = [];
+  const seen = new Set<string>();
+  for (const segment of splitPromptReferenceText(text)) {
+    if (segment.kind === 'text' || seen.has(segment.id)) continue;
+    seen.add(segment.id);
+    const reference = byId.get(segment.id);
+    if (reference) used.push(reference);
+  }
+  if (!used.length) return undefined;
+  if (text.length > PROMPT_DISPLAY_MAX_CHARS) return undefined;
+  if (used.length > PROMPT_DISPLAY_MAX_REFERENCES) return undefined;
+  return { text, references: used };
+}

package/skill/assets/upstream/packages/shared/src/title.ts

@@ -0,0 +1,76 @@
+/**
+ * Title length policy for session titles.
+ *
+ * A title has to fit one line in cards, the project header, share pages and
+ * download filenames. Counting characters alone does not describe that budget:
+ * a CJK glyph occupies roughly twice the width of a Latin one, so 60 Chinese
+ * characters overflow everywhere that 60 Latin characters fit. We therefore
+ * budget *display width* — CJK and other full-width glyphs cost 2, everything
+ * else costs 1 — which yields the intended "30 Chinese characters or 60 Latin
+ * characters" cap from a single rule.
+ */
+export const TITLE_MAX_WIDTH = 60;
+
+/** Session titles are shorter: about 15 CJK or 30 Latin characters. */
+export const SESSION_TITLE_MAX_WIDTH = 30;
+
+const FULL_WIDTH_RANGES: readonly [number, number][] = [
+  [0x1100, 0x115f], // Hangul Jamo
+  [0x2e80, 0x303e], // CJK radicals, Kangxi, CJK symbols & punctuation
+  [0x3041, 0x33ff], // Hiragana, Katakana, Hangul compat, CJK compat
+  [0x3400, 0x4dbf], // CJK ext A
+  [0x4e00, 0x9fff], // CJK unified
+  [0xa000, 0xa4cf], // Yi
+  [0xac00, 0xd7a3], // Hangul syllables
+  [0xf900, 0xfaff], // CJK compat ideographs
+  [0xfe30, 0xfe6f], // CJK compat forms
+  [0xff00, 0xff60], // Full-width forms
+  [0xffe0, 0xffe6],
+  [0x20000, 0x2fffd], // CJK ext B+
+  [0x30000, 0x3fffd],
+];
+
+function charWidth(codePoint: number): number {
+  return FULL_WIDTH_RANGES.some(([lo, hi]) => codePoint >= lo && codePoint <= hi) ? 2 : 1;
+}
+
+/** Display width of a title: CJK glyphs count as 2, everything else as 1. */
+export function titleWidth(text: string): number {
+  let width = 0;
+  for (const ch of text) width += charWidth(ch.codePointAt(0)!);
+  return width;
+}
+
+/**
+ * Trim a title to the width budget, appending an ellipsis when it was cut.
+ * Whitespace is collapsed first so wrapped or multi-line model output does not
+ * waste the budget on newlines. Surrogate pairs are never split.
+ */
+export function clampTitle(raw: string, maxWidth = TITLE_MAX_WIDTH): string {
+  const text = raw.replace(/\s+/g, ' ').trim();
+  if (titleWidth(text) <= maxWidth) return text;
+  // Leave room for the ellipsis so the result still fits the budget.
+  const budget = Math.max(1, maxWidth - 1);
+  let width = 0;
+  let out = '';
+  for (const ch of text) {
+    const w = charWidth(ch.codePointAt(0)!);
+    if (width + w > budget) break;
+    width += w;
+    out += ch;
+  }
+  return `${out.trimEnd()}…`;
+}
+
+/** Cuts to the width budget without an ellipsis (for an input while typing). */
+export function limitTitleWidth(raw: string, maxWidth = TITLE_MAX_WIDTH): string {
+  let width = 0;
+  let out = '';
+  for (const ch of raw) {
+    const w = charWidth(ch.codePointAt(0)!);
+    if (width + w > maxWidth) break;
+    width += w;
+    out += ch;
+  }
+  return out;
+}

package/skill/assets/upstream/packages/shared/src/turn.ts

@@ -0,0 +1,68 @@
+import type { Modality } from './modality';
+import type { CancelReason, GenResult, TurnAttachment } from './contract';
+import type { PromptDisplay } from './prompt-reference';
+
+/**
+ * A turn: what the person said, and everything the agent did for it. Projects hold sessions, sessions hold turns; a
+ * film a turn makes is a LibraryVideo of its own (an edit makes a new turn and a new film, never changing the parent).
+ */
+export type TurnStatus =
+  | 'generating'
+  | 'failing'
+  | 'canceling'
+  | 'ready'
+  | 'error'
+  | 'cancelled';
+
+export interface Turn {
+  id: string;
+  ownerId: string;
+  /** The project it belongs to. */
+  projectId: string;
+  /** The session it belongs to (the agent's conversation memory). */
+  sessionId: string;
+  /** The session's title, for recents and the conversation; independent of the film's. */
+  sessionTitle: string;
+  /** The film this turn starts from; null for a new one. */
+  baseVideoId?: string | null;
+  modality: Modality;
+  /** Empty: the project's title is shown. */
+  title: string;
+  /** The project's title, when the person gave one. Lists include it; elsewhere it may be absent. */
+  projectTitle?: string;
+  /** A one-line description of the film. */
+  description?: string;
+  /** Content tags (3 to 6). */
+  tags?: string[];
+  status: TurnStatus;
+  /** The person's message as sent to the model. */
+  prompt: string;
+  /**
+   * The same message as it looked in the composer, with its pills (`prompt` is the expanded text sent to the model).
+   * Only when the message has pills.
+   */
+  promptDisplay?: PromptDisplay | null;
+  /** What the person attached (names and thumbnails), for display only. */
+  attachments?: TurnAttachment[] | null;
+  /** What the turn made; null while it runs. */
+  result: GenResult | null;
+  error?: string | null;
+  /** The model it ran on. */
+  model?: string | null;
+  /**
+   * A turn run by a local agent on the person's computer (Codex, Claude Code), kept only there; `model` is the name
+   * shown in its menu (e.g. "gpt-5.5 · Medium").
+   */
+  localAgent?: { id: string; model?: string | null } | null;
+  /** The turn carried pictures. */
+  vision?: boolean;
+  /** When a stop was asked for, and when it stopped. */
+  cancelRequestedAt?: string | null;
+  cancelledAt?: string | null;
+  /** Why it stopped; null means `'user'`. */
+  cancelReason?: CancelReason | null;
+  /** When it was removed from recents (the film stays in the library); absent while it is shown. */
+  removedFromRecentsAt?: string | null;
+  createdAt: string;
+  updatedAt: string;
+}

package/skill/assets/upstream/packages/shared/src/video.ts

@@ -0,0 +1,26 @@
+import type { VideoResult } from './contract';
+
+/**
+ * A finished film in the library; a turn makes at most one. Versions chain by `parentVideoId` (editing v3 makes v4).
+ */
+export interface LibraryVideo {
+  id: string;
+  ownerId: string;
+  /** The project it belongs to. */
+  projectId: string;
+  /** The turn that made it. */
+  turnId: string;
+  /** The session it was made in. */
+  sessionId: string;
+  /** Empty: a film has no name of its own (the project's title is shown). */
+  title: string;
+  /** The project's title, when the person gave one. Lists include it; elsewhere it may be absent. */
+  projectTitle?: string;
+  description?: string;
+  tags?: string[];
+  result: VideoResult;
+  /** The version it was made from; null for a project's first. */
+  parentVideoId: string | null;
+  createdAt: string;
+  updatedAt: string;
+}

package/skill/references/agent-components.md

@@ -0,0 +1,33 @@
+# Agent 与 Personal Agent
+
+基线：`0.1.0-preview.3`。从 `auricui/agent` 导入，CSS 仍只导入一次 `auricui/styles.css`。这些组件不依赖 Chat Provider 或模型 SDK；宿主传入数据、维护状态并实现回调。
+
+| 需求 | 组件 |
+| --- | --- |
+| 消息与滚动 | MessageBubble、MessageActions、MessageList、ResponseSwitcher |
+| 内容与引用 | CodeBlock、Citation、SourceList、ArtifactCard、AttachmentChip |
+| 输入辅助 | Suggestion、PromptTemplate、ContextUsage |
+| 执行状态 | ThinkingIndicator、ReasoningDisclosure、AgentStatus、ToolCall、TaskSteps、RunSummary、Checkpoint |
+| 会话与身份 | AgentCard、ConversationList |
+| 操作确认 | ApprovalCard |
+| 个人助手 | MemoryCard、GoalCard、ScheduleCard、ConnectorCard、ProactiveSuggestion、ActivityTimeline、AutonomyControl、BriefingCard |
+
+先查询真实契约，例如：
+
+```bash
+python3 <Skill目录>/scripts/inspect_api.py --entry agent --symbol ToolCall --project <前端目录>
+python3 <Skill目录>/scripts/inspect_api.py --entry agent --symbol MemoryCard --project <前端目录>
+```
+
+## 容易接错的行为
+
+- MessageList 只在用户位于底部时跟随新增内容；用户向上阅读时保留位置。传入稳定的消息 key，不用随机 key 重建消息。
+- ReasoningDisclosure 展示宿主提供的过程摘要，不生成模型内部思维链。ToolCall 的输入、输出、错误与执行状态也来自宿主。
+- CodeBlock 复制原始字符串，默认没有语法着色；需要时通过 `renderLine` 接入项目的高亮器。
+- Citation 仅接受 HTTP/HTTPS 来源，摘要使用 body Portal，支持 Escape、外部点击和视口边界。Portal 读取全局主题。
+- ResponseSwitcher 索引从 0 开始；Pagination 的页码从 1 开始。ContextUsage 容量未知时传入无效 limit，会展示未知而不是编造百分比。
+- ApprovalCard 的 `status` 来自应用；请求中传 `submitting`，完成后传 `approved` / `rejected`。回调不等同服务端授权。AutonomyControl 只是偏好选择器，权限仍由服务端执行。
+- ScheduleCard 只展示 timezone / nextRun 并通知开关变化，不创建定时任务。ConnectorCard 不实现 OAuth。MemoryCard 的编辑/忘记回调不自动修改存储。
+- ConversationList 的搜索值和筛选结果由宿主管理；PromptTemplate 字段和值受控，提交结果由应用消费。
+
+独立可复制示例位于 `assets/examples/`：MessageList、ToolCall、ApprovalCard、MemoryCard、BriefingCard。示例动作仅改变演示状态，接入应用时替换为实际回调。