Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
HTML agent-skillsai-agentsarchitecture-diagramclaude-codeclaude-skillscodexcoding-agentsdeepseek-harnessdeveloper-toolsdiagramsdiagrams-as-codedsh-pluginflowchartllmmermaidopencodesequence-diagramsoftware-architecturesystem-designvisualization
docs(website): guide Mermaid input through an agent
tt-a1ie871a2ef8790
diff --git a/website/src/content/agent-diagrams.en.md b/website/src/content/agent-diagrams.en.mdindex 5e7415c1..e1fbe1db 100644--- a/website/src/content/agent-diagrams.en.md+++ b/website/src/content/agent-diagrams.en.md@@ -38,6 +38,35 @@ Review order, allowance, and reminders separately: follow the main path to reconTo start from your own description, open the [workflow quick start](start.html?type=workflow&input=description), provide only confirmed steps and rules, and mark unknown conditions.+<span id="mermaid-input" class="section-anchor" aria-hidden="true"></span>++## Use Mermaid as input, not as a promise of automatic conversion++If you already have a Mermaid diagram, paste its source into your configured coding agent. The agent reads the relationships and authors fresh Archify JSON; Archify then renders and checks that JSON. This is not a Mermaid parser, a theme replacement, or a lossless round-trip converter.++For example, this small flowchart describes four steps and four directed relationships:++<pre><code>flowchart LR+ A[Submit request] --> B[Review request]+ B -->|Approved| C[Proceed]+ B -->|Changes needed| D[Revise request]+ D --> B</code></pre>++Ask your agent:++> Use Archify to turn this Mermaid input into an interactive workflow diagram. Preserve the four steps, the Approved and Changes needed branch labels, and the return from Revise request to Review request. Do not invent people, deadlines, or additional steps. If a construct cannot be represented faithfully, explain the limitation before simplifying it.++This is illustrative input, not a recorded conversion or a checked output.++Review meaning before appearance:++- Does each original step still have the same role?+- Do both branches retain their labels and destinations?+- Does revision return to review rather than ending the process?+- Has anything been omitted, merged, or added?++Keep the original Mermaid alongside the new JSON so you can compare them. Mermaid styling, layout directives, and callbacks should not be assumed to carry over. The [pinned Skill](https://github.com/tt-a1i/archify/blob/88d1ae4498b6a1df610badf690c5406882622d15/archify/SKILL.md#mermaid-input) describes the supported input families. If your goal is to retain Mermaid syntax and render it directly on a web page, use [Mermaid’s own rendering workflow](https://mermaid.ai/open-source/config/usage.html) instead.+<span id="cache-scenarios" class="section-anchor" aria-hidden="true"></span>## Try two bounded requests: cache hit and cache miss@@ -110,7 +139,7 @@ Workflow mode can describe steps, branches, and participants. Class and sequence### Can I start with Mermaid?-Yes, an agent can interpret supported Mermaid input and author Archify JSON from its meaning. This is not a promise of complete automatic parsing or lossless round-trip conversion. Check that the relationships and alternatives you need survive the conversion.+Yes. See [how to use Mermaid as agent input](#mermaid-input) for a small example, a careful prompt, and the meaning to check before accepting the result.### Is a repository required?diff --git a/website/src/content/agent-diagrams.zh.md b/website/src/content/agent-diagrams.zh.mdindex 40333026..10c4d275 100644--- a/website/src/content/agent-diagrams.zh.md+++ b/website/src/content/agent-diagrams.zh.md@@ -38,6 +38,35 @@ Archify 根据源文件生成 HTML,并执行对应的渲染与校验。你可想从自己的描述开始,可打开[工作流快速开始](start.html?type=workflow&input=description),只提供已确认的步骤和规则,并标出未知条件。+<span id="mermaid-input" class="section-anchor" aria-hidden="true"></span>++## 把 Mermaid 交给 Agent,而不是承诺自动转换++如果已有 Mermaid 图,可以把源文本交给已配置好的 Coding Agent。Agent 理解其中的关系,再编写新的 Archify JSON;Archify 渲染并检查这份 JSON。这不是 Mermaid 解析器、换肤工具,也不承诺无损往返转换。++例如,下面的流程图描述了四个步骤和四条有方向的关系:++<pre><code>flowchart LR+ A[Submit request] --> B[Review request]+ B -->|Approved| C[Proceed]+ B -->|Changes needed| D[Revise request]+ D --> B</code></pre>++可以这样要求 Agent:++> 用 Archify 把这段 Mermaid 输入画成交互式工作流图。保留四个步骤、Approved 和 Changes needed 两个分支标签,以及从 Revise request 返回 Review request 的关系。不要添加人物、期限或额外步骤。如果某种结构无法忠实表达,先说明限制,再讨论简化方式。++这是示例输入,不是一次实测转换,也不是已经校验过的成品。++先检查含义,再看外观:++- 原来的每个步骤是否仍承担相同职责?+- 两个分支的标签和目标是否保留?+- 修改后是否回到审阅,而不是直接结束?+- 是否遗漏、合并或新增了内容?++保留原始 Mermaid,与新的 JSON 对照检查。不要假定 Mermaid 的样式、布局指令或回调会一并保留。[固定版本的 Skill](https://github.com/tt-a1i/archify/blob/88d1ae4498b6a1df610badf690c5406882622d15/archify/SKILL.md#mermaid-input) 说明了受支持的输入类型。如果只想保留 Mermaid 语法并在网页中直接渲染,应使用 [Mermaid 自己的渲染方式](https://mermaid.ai/open-source/config/usage.html)。+<span id="cache-scenarios" class="section-anchor" aria-hidden="true"></span>## 第一个例子:分别画缓存命中与未命中@@ -110,7 +139,7 @@ Archify 根据源文件生成 HTML,并执行对应的渲染与校验。你可### 能从 Mermaid 开始吗?-可以让 Agent 理解受支持的 Mermaid 输入,并按含义重新编写 Archify JSON。这不等于承诺完整自动解析或无损往返转换。转换后要检查重要关系和分支是否保留下来。+可以。参见[怎样把 Mermaid 交给 Agent](#mermaid-input),了解一个小例子、提示词,以及接受结果前要检查的含义。### 必须有代码仓库吗?diff --git a/website/src/pages/agent-diagrams.astro b/website/src/pages/agent-diagrams.astroindex 716bacfa..8f48d0ab 100644--- a/website/src/pages/agent-diagrams.astro+++ b/website/src/pages/agent-diagrams.astro@@ -7,7 +7,7 @@ import head from '../data/agent-diagrams-head.html?raw';import css from '../styles/agent-diagrams.css?raw';const { lang = 'en' } = Astro.props;const Content = lang === 'zh' ? Chinese : English;-const sectionIds = ['responsibilities', 'setup', 'description-workflow', 'cache-scenarios', 'repository-evidence', 'review-and-share', 'questions'];+const sectionIds = ['responsibilities', 'setup', 'description-workflow', 'mermaid-input', 'cache-scenarios', 'repository-evidence', 'review-and-share', 'questions'];const headings = (lang === 'zh' ? chineseHeadings() : englishHeadings()).filter(heading => heading.depth === 2).map((heading, index) => ({ ...heading, slug: sectionIds[index] }));---diff --git a/website/src/pages/start.astro b/website/src/pages/start.astroindex 2dcf1a98..204fa673 100644--- a/website/src/pages/start.astro+++ b/website/src/pages/start.astro@@ -33,6 +33,7 @@ const { lang = 'en' } = Astro.props;<button class="input-path" type="button" role="tab" data-input="description"><strong data-en="Just describe it" data-zh="直接描述">直接描述</strong><span data-en="Start in any chat. No files or repository needed." data-zh="在任意对话里开始,不需要文件或代码库。">Start in any chat. No files or repository needed.</span></button><button class="input-path" type="button" role="tab" data-input="repository"><strong data-en="Use a repository" data-zh="从代码库开始">Use a repository</strong><span data-en="Let the agent inspect code when source evidence matters." data-zh="需要源码证据时,再让 Agent 检查代码。">Let the agent inspect code when source evidence matters.</span></button></div>+ <p class="question mermaid-guide-link"><a href="agent-diagrams.html#mermaid-input" data-en="Already have Mermaid? Learn how to use it as agent input →" data-zh="已有 Mermaid?了解怎样把它交给 Agent →">Already have Mermaid? Learn how to use it as agent input →</a></p><p class="type-label" id="type-label"><span data-en="Choose the question shape" data-zh="选择问题形态">Choose the question shape</span><strong data-en={`${Object.keys(starts).length} starting recipes`} data-zh={`${Object.keys(starts).length} 个入门配方`}>{Object.keys(starts).length} starting recipes</strong></p><SupportedDiagrams /><div class="type-tabs" role="tablist" aria-label="Diagram type">diff --git a/website/src/styles/agent-diagrams.css b/website/src/styles/agent-diagrams.cssindex a3643f23..ee4e9cfc 100644--- a/website/src/styles/agent-diagrams.css+++ b/website/src/styles/agent-diagrams.css@@ -17,6 +17,8 @@.article-body a, .article-footer a { color:var(--accent-text); text-underline-offset:4px; }.article-body ul { padding-left:1.3rem; color:var(--text-2); }.article-body li { margin:.65rem 0; }+.article-body pre { margin:1.5rem 0; padding:1rem; border:1px solid var(--line-hi); border-radius:12px; background:var(--surface); color:var(--text); font:400 .85rem/1.75 var(--font-mono); white-space:pre-wrap; overflow-wrap:anywhere; }+.article-body pre code { font:inherit; }.article-body blockquote { margin:1.5rem 0; padding:.6rem 1.4rem; border-left:3px solid var(--accent); background:var(--surface); border-radius:0 12px 12px 0; }.article-body blockquote p { color:var(--text); }.article-footer { position:relative; max-width:1180px; margin:auto; padding:2rem 24px 4rem; border-top:1px solid var(--line-hi); display:flex; flex-wrap:wrap; gap:2rem; }diff --git a/website/test/agent-diagrams-browser.test.mjs b/website/test/agent-diagrams-browser.test.mjsindex 6e499e43..95fd2393 100644--- a/website/test/agent-diagrams-browser.test.mjs+++ b/website/test/agent-diagrams-browser.test.mjs@@ -117,11 +117,17 @@ test('real Chrome: agent guide stays readable and navigable in both languages, t})()`);// Capture bounded viewport tiles so long mobile prompts and limits are not// silently cropped or squeezed into an unreadable full-page thumbnail.- for (const region of ['opening', 'description-workflow', 'cache-example', 'review-limits']) {+ for (const [region, startId, endId] of [+ ['opening', null, 'responsibilities'],+ ['description-workflow', 'description-workflow', 'mermaid-input'],+ ['mermaid-input', 'mermaid-input', 'cache-scenarios'],+ ['cache-example', 'cache-scenarios', 'repository-evidence'],+ ['review-limits', 'review-and-share', 'questions'],+ ]) {const bounds = await evaluate(`(() => {const article = document.querySelector('.article-body');- const start = ${JSON.stringify(region)} === 'opening' ? article.querySelector('h1') : document.getElementById(${JSON.stringify(region === 'description-workflow' ? 'description-workflow' : region === 'cache-example' ? 'cache-scenarios' : 'review-and-share')});- const end = document.getElementById(${JSON.stringify(region === 'opening' ? 'responsibilities' : region === 'description-workflow' ? 'cache-scenarios' : region === 'cache-example' ? 'repository-evidence' : 'questions')});+ const start = ${JSON.stringify(startId)} ? document.getElementById(${JSON.stringify(startId)}) : article.querySelector('h1');+ const end = document.getElementById(${JSON.stringify(endId)});return { top: start.getBoundingClientRect().top + scrollY, bottom: end.getBoundingClientRect().top + scrollY, nav: document.querySelector('.site-nav').getBoundingClientRect().bottom };})()`);const inset = bounds.nav + 20;@@ -165,11 +171,46 @@ test('real Chrome: agent guide stays readable and navigable in both languages, tassert.equal(await evaluate('location.pathname'), new URL(urlFor('agent-diagrams', lang)).pathname);assert.equal(await evaluate('location.hash'), '#description-workflow');const workflowLocalePosition = await assertSectionVisible();+ await evaluate(`document.querySelector('.article-toc a[href$="#mermaid-input"]').click()`);+ await settled();+ assert.equal(await evaluate('location.hash'), '#mermaid-input');+ const mermaidPosition = await assertSectionVisible();+ await loadedAction(() => evaluate(`document.querySelector('[data-language-switch]').click()`));+ assert.equal(await evaluate('location.pathname'), new URL(urlFor('agent-diagrams', other)).pathname);+ assert.equal(await evaluate('location.hash'), '#mermaid-input');+ const mermaidLocalePosition = await assertSectionVisible();+ await loadedAction(() => evaluate(`document.querySelector('[data-language-switch]').click()`));+ assert.equal(await evaluate('location.pathname'), new URL(urlFor('agent-diagrams', lang)).pathname);+ assert.equal(await evaluate('location.hash'), '#mermaid-input');await loadedAction(() => evaluate(`document.querySelector('.article-body a[href*="type=workflow"]').click()`));assert.equal(await evaluate('location.pathname'), new URL(urlFor('start', lang)).pathname);assert.equal(await evaluate('new URL(location.href).searchParams.get("input")'), 'description');assert.equal(await evaluate(`document.querySelector('[data-type="workflow"]').getAttribute('aria-selected')`), 'true');assert.equal(await evaluate(`document.querySelector('[data-input="description"]').getAttribute('aria-selected')`), 'true');+ for (const theme of ['light', 'dark']) {+ await evaluate(`if (document.documentElement.dataset.theme !== ${JSON.stringify(theme)}) document.querySelector('[data-theme-toggle]').click()`);+ await evaluate(`document.querySelector('.mermaid-guide-link').scrollIntoView({ block: 'center', behavior: 'instant' })`);+ await settled();+ const help = await evaluate(`(() => {+ const link = document.querySelector('.mermaid-guide-link a'), style = getComputedStyle(link);+ const range = document.createRange(); range.selectNodeContents(link);+ const rects = [...range.getClientRects()];+ return { theme: document.documentElement.dataset.theme, pageWidth: document.documentElement.scrollWidth, visible: style.visibility === 'visible' && style.display !== 'none', rects: rects.map(({ left, right, top, bottom }) => ({ left, right, top, bottom })), navBottom: document.querySelector('.site-nav').getBoundingClientRect().bottom };+ })()`);+ assert.equal(help.theme, theme);+ assert.ok(help.visible && help.rects.length > 0, 'Start help is visible');+ assert.ok(help.pageWidth <= width + 1, 'Start has no horizontal page overflow');+ assert.ok(help.rects.every(box => box.left >= 0 && box.right <= width && box.top >= help.navBottom && box.bottom <= 1000), 'the complete Start help link is readable below navigation');+ const name = `agent-diagrams-${lang}-${width}-${theme}-start-help.png`;+ const image = await browser.cdp.send('Page.captureScreenshot', { format: 'png' }, session);+ fs.writeFileSync(path.join(output, name), Buffer.from(image.data, 'base64'));+ manifest.screenshots.push({ file: name, width, height: 1000, lang, theme, region: 'start-help', reading: help });+ saveManifest();+ }+ await loadedAction(() => evaluate(`document.querySelector('.mermaid-guide-link a').click()`));+ assert.equal(await evaluate('location.pathname'), new URL(urlFor('agent-diagrams', lang)).pathname);+ assert.equal(await evaluate('location.hash'), '#mermaid-input');+ const mermaidStartPosition = await assertSectionVisible();await navigate(urlFor('agent-diagrams', other));await loadedAction(() => evaluate(`document.querySelector('.article-body a[href="cases/life/leave-plan.workflow.html"]').click()`));assert.equal(await evaluate('location.pathname'), `${mount}/cases/life/leave-plan.workflow.html`);@@ -182,7 +223,7 @@ test('real Chrome: agent guide stays readable and navigable in both languages, tawait navigate(urlFor('guide', lang));await loadedAction(() => evaluate(`document.querySelector('.agent-guide-link a').click()`));assert.equal(await evaluate('location.pathname'), new URL(urlFor('agent-diagrams', lang)).pathname);- manifest.navigation.push({ width, lang, result: 'passed', tocPosition, localePosition, workflowPosition, workflowLocalePosition, paths: ['toc', 'language with fragment', 'workflow section and locale', 'workflow description quick start', 'existing leave artifact', 'article to start', 'start to article', 'guide to article'] });+ manifest.navigation.push({ width, lang, result: 'passed', tocPosition, localePosition, workflowPosition, workflowLocalePosition, mermaidPosition, mermaidLocalePosition, mermaidStartPosition, paths: ['toc', 'language with fragment', 'workflow section and locale', 'Mermaid section and locale', 'workflow description quick start', 'Start Mermaid help', 'existing leave artifact', 'article to start', 'start to article', 'guide to article'] });saveManifest();}} finally {diff --git a/website/test/agent-diagrams.test.mjs b/website/test/agent-diagrams.test.mjsindex 2a9d4780..74bd9105 100644--- a/website/test/agent-diagrams.test.mjs+++ b/website/test/agent-diagrams.test.mjs@@ -20,7 +20,6 @@ test('agent guide is readable without JavaScript, honest about examples, and linconst article = all.find(node => node.tagName === 'article');assert.ok(article);assert.equal(nodes(article).filter(node => node.tagName === 'h1').length, 1);- assert.equal(nodes(article).filter(node => node.tagName === 'blockquote').length, 2);const visible = text(article);assert.match(visible, lang === 'en' ? /two separate sequence diagrams/i : /分别画两张时序图/);assert.match(visible, lang === 'en' ? /not the output of this prompt/ : /不是上述提示词的生成结果/);@@ -31,7 +30,7 @@ test('agent guide is readable without JavaScript, honest about examples, and linassert.equal(structuredArticle.url, `https://archify.si/${prefix}agent-diagrams`);assert.equal(structuredArticle.inLanguage, lang === 'zh' ? 'zh-Hans' : 'en');const ids = new Set(all.map(node => attr(node, 'id')).filter(Boolean));- for (const id of ['responsibilities', 'setup', 'description-workflow', 'cache-scenarios', 'repository-evidence', 'review-and-share', 'questions']) assert.ok(ids.has(id), `${lang}: stable cross-language section ${id}`);+ for (const id of ['responsibilities', 'setup', 'description-workflow', 'mermaid-input', 'cache-scenarios', 'repository-evidence', 'review-and-share', 'questions']) assert.ok(ids.has(id), `${lang}: stable cross-language section ${id}`);const toc = all.find(node => attr(node, 'class') === 'article-toc');for (const link of nodes(toc).filter(node => node.tagName === 'a')) {const destination = new URL(attr(link, 'href'), baseUri);@@ -94,7 +93,7 @@ test('description workflow exposes pinned evidence, honest limits and localizedconst start = nodes(article).find(node => attr(node, 'id') === 'description-workflow').parentNode;const siblings = start.parentNode.childNodes;const rest = siblings.slice(siblings.indexOf(start) + 1);- const end = rest.findIndex(node => nodes(node).some(child => attr(child, 'id') === 'cache-scenarios'));+ const end = rest.findIndex(node => nodes(node).some(child => attr(child, 'id') === 'mermaid-input'));const section = rest.slice(0, end).flatMap(nodes);const visible = rest.slice(0, end).map(text).join('');assert.match(visible, /1 \+ 4 \+ 3 \+ 2/);@@ -115,3 +114,52 @@ test('description workflow exposes pinned evidence, honest limits and localizedassert.deepEqual(original, fs.readFileSync(new URL(`../../docs/${file}`, import.meta.url)), 'existing artifact bytes remain unchanged outside the publication metadata block');}});++test('Mermaid guidance preserves the literal example, explains semantic reauthoring and is linked from localized Start pages', () => {+ const origin = cloudflare ? 'https://archify.si/' : 'https://tt-a1i.github.io/archify/';+ for (const lang of ['en', 'zh']) {+ const prefix = lang === 'zh' ? 'zh/' : '';+ const all = nodes(parse(fs.readFileSync(new URL(`${prefix}agent-diagrams.html`, output), 'utf8')));+ const base = new URL(attr(all.find(node => node.tagName === 'base'), 'href'), origin + `${prefix}agent-diagrams.html`);+ const article = all.find(node => node.tagName === 'article');+ const start = nodes(article).find(node => attr(node, 'id') === 'mermaid-input').parentNode;+ const siblings = start.parentNode.childNodes;+ const rest = siblings.slice(siblings.indexOf(start) + 1);+ const end = rest.findIndex(node => nodes(node).some(child => attr(child, 'id') === 'cache-scenarios'));+ assert.ok(end > 0, 'the Mermaid section is bounded before the next topic');+ const section = rest.slice(0, end).flatMap(nodes);+ const visible = rest.slice(0, end).map(text).join('');+ const source = text(section.find(node => node.tagName === 'pre'));+ assert.match(source, /^flowchart LR\n/);+ assert.deepEqual(Object.fromEntries([...source.matchAll(/([A-Z])\[([^\]]+)\]/g)].map(match => [match[1], match[2]])), {+ A: 'Submit request', B: 'Review request', C: 'Proceed', D: 'Revise request',+ });+ const relationships = [...source.matchAll(/^\s*([A-Z])(?:\[[^\]]+\])?\s*-->(?:\|([^|]+)\|)?\s*([A-Z])/gm)]+ .map(([, from, label = '', to]) => ({ from, to, label }));+ assert.deepEqual(relationships, [+ { from: 'A', to: 'B', label: '' },+ { from: 'B', to: 'C', label: 'Approved' },+ { from: 'B', to: 'D', label: 'Changes needed' },+ { from: 'D', to: 'B', label: '' },+ ]);+ assert.match(visible, lang === 'en' ? /authors fresh Archify JSON/ : /编写新的 Archify JSON/);+ assert.match(visible, lang === 'en' ? /not a Mermaid parser.*lossless round-trip converter/ : /不是 Mermaid 解析器.*不承诺无损往返转换/);+ assert.match(visible, lang === 'en' ? /not a recorded conversion or a checked output/ : /不是一次实测转换,也不是已经校验过的成品/);+ const prompt = text(section.find(node => node.tagName === 'blockquote'));+ for (const label of ['Approved', 'Changes needed', 'Revise request', 'Review request']) assert.ok(prompt.includes(label));+ assert.match(prompt, lang === 'en' ? /explain the limitation before simplifying/ : /先说明限制,再讨论简化方式/);+ assert.equal(section.filter(node => node.tagName === 'li').length, 4, 'the semantic review checklist is readable without JavaScript');+ const links = section.filter(node => node.tagName === 'a').map(node => new URL(attr(node, 'href'), base).href);+ assert.ok(links.includes('https://github.com/tt-a1i/archify/blob/88d1ae4498b6a1df610badf690c5406882622d15/archify/SKILL.md#mermaid-input'));+ assert.ok(links.includes('https://mermaid.ai/open-source/config/usage.html'));+ assert.ok(nodes(article).some(node => node.tagName === 'a' && new URL(attr(node, 'href'), base).hash === '#mermaid-input'), 'the FAQ points to the full explanation');++ const entryNodes = nodes(parse(fs.readFileSync(new URL(`${prefix}start.html`, output), 'utf8')));+ const entryBase = new URL(attr(entryNodes.find(node => node.tagName === 'base'), 'href'), origin + `${prefix}start.html`);+ const help = entryNodes.find(node => (attr(node, 'class') || '').split(/\s+/).includes('mermaid-guide-link'));+ const link = nodes(help).find(node => node.tagName === 'a');+ assert.equal(text(link), lang === 'en' ? 'Already have Mermaid? Learn how to use it as agent input →' : '已有 Mermaid?了解怎样把它交给 Agent →');+ assert.equal(new URL(attr(link, 'href'), entryBase).href, origin + `${prefix}agent-diagrams${cloudflare ? '' : '.html'}#mermaid-input`);+ assert.deepEqual(entryNodes.filter(node => attr(node, 'data-input')).map(node => attr(node, 'data-input')), ['description', 'repository'], 'Mermaid help does not introduce a new input mode');+ }+});