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): add bilingual coding-agent diagramming guide and browser acceptance
tt-a1ie994a5a0f362
diff --git a/website/.gitignore b/website/.gitignoreindex 618867bf..912e21d4 100644--- a/website/.gitignore+++ b/website/.gitignore@@ -3,3 +3,4 @@ dist/dist-cloudflare/.astro/.public/+.browser-evidence/diff --git a/website/package.json b/website/package.jsonindex 8a33bb67..bdb236e0 100644--- a/website/package.json+++ b/website/package.json@@ -12,7 +12,7 @@"preview": "astro preview","check": "astro check","test": "node --test test/*.test.mjs",- "test:browser": "node --test --test-name-pattern=\"real Chrome\" ../test/site-language-continuity.test.mjs test/community-browser.test.mjs test/homepage-browser.test.mjs"+ "test:browser": "node --test --test-name-pattern=\"real Chrome\" ../test/site-language-continuity.test.mjs test/community-browser.test.mjs test/homepage-browser.test.mjs test/agent-diagrams-browser.test.mjs"},"dependencies": {"@astrojs/react": "^6.0.6",diff --git a/website/scripts/check-cloudflare-output.mjs b/website/scripts/check-cloudflare-output.mjsindex 82fa65e3..debf01f8 100644--- a/website/scripts/check-cloudflare-output.mjs+++ b/website/scripts/check-cloudflare-output.mjs@@ -3,11 +3,12 @@ import fs from 'node:fs';import path from 'node:path';import { fileURLToPath, pathToFileURL } from 'node:url';import { parse } from 'parse5';+import { canonicalPath, sitePages } from '../src/data/site-urls.mjs';// Check the deployable files, not only the build configuration. Pages needs a// top-level 404 to disable its implicit single-page-app fallback.export function checkCloudflareOutput(root) {- const pages = ['index.html', 'gallery.html', 'guide.html', 'start.html', 'community.html', 'zh.html', 'zh/gallery.html', 'zh/guide.html', 'zh/start.html', 'zh/community.html', '404.html'];+ const pages = [...sitePages.flatMap(page => ['en', 'zh'].map(lang => `${canonicalPath(page, lang).slice(1) || 'index'}.html`)), '404.html'];let fileCount = 0;const checkAssets = directory => {for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {@@ -53,7 +54,7 @@ export function checkCloudflareOutput(root) {}const sitemap = fs.readFileSync(path.join(root, 'sitemap.xml'), 'utf8');const locations = [...sitemap.matchAll(/<loc>([^<]+)<\/loc>/g)].map(match => match[1]);- assert.ok(locations.length >= 10, 'Sitemap must include both languages');+ assert.ok(locations.length >= sitePages.length * 2, 'Sitemap must include both languages');assert.equal(new Set(locations).size, locations.length, 'Duplicate sitemap URL');for (const location of locations) {const url = new URL(location);diff --git a/website/scripts/indexnow.mjs b/website/scripts/indexnow.mjsindex 17757637..ab4c57e7 100644--- a/website/scripts/indexnow.mjs+++ b/website/scripts/indexnow.mjs@@ -33,7 +33,7 @@ export function parseSitemap(xml) {entries.push(value);body = body.slice(item[0].length);}- requireValue(entries.length === allowedUrls.size, 'Sitemap must contain all ten main pages and selected gallery artifacts');+ requireValue(entries.length === allowedUrls.size, 'Sitemap must contain all main pages and selected gallery artifacts');return entries;}diff --git a/website/src/components/Navigation.astro b/website/src/components/Navigation.astroindex 4e6e86bd..08f518fb 100644--- a/website/src/components/Navigation.astro+++ b/website/src/components/Navigation.astro@@ -1,9 +1,10 @@---import Brand from './Brand';-interface Props { page: 'index' | 'gallery' | 'guide' | 'start' | 'community' }+interface Props { page: 'index' | 'gallery' | 'guide' | 'start' | 'community' | 'agent-diagrams' }const { page } = Astro.props;const home = page === 'index';const identities = {+ 'agent-diagrams': { en: '/ agent diagrams', zh: '/ Agent 画图', label: 'Archify home' },gallery: { en: '/ proof lab', zh: '/ 验证作品集', label: 'Back to Archify home' },guide: { en: '/ guide', zh: '/ 场景指南', label: 'Archify home' },start: { en: '/ start', zh: '/ 快速上手', label: 'Archify project page' },diff --git a/website/src/content/agent-diagrams.en.md b/website/src/content/agent-diagrams.en.mdnew file mode 100644index 00000000..e848eb11--- /dev/null+++ b/website/src/content/agent-diagrams.en.md@@ -0,0 +1,111 @@+# Create diagrams with your coding agent++Archify is an open-source diagram skill for coding agents including Claude Code, Codex, Cursor, OpenCode, and GitHub Copilot. Your agent interprets a description or repository evidence and writes typed JSON. Archify renders and checks that source to produce an interactive HTML diagram.++Use it when you want to explain a system's parts, a process, a sequence of calls, or another supported relationship structure. Start from words if you do not have a repository. Start from code when the diagram needs source evidence.++The generated diagram is a model of the facts its author supplied. Passing its checks does not prove that a running system behaves that way.++<span id="responsibilities" class="section-anchor" aria-hidden="true"></span>++## What your agent does, and what Archify does++Your agent reads the information you provide, asks about important missing facts, chooses a diagram type, and authors or revises the structured source. For a repository-backed task, the agent also examines relevant code.++Archify turns that source into an HTML artifact and applies its rendering and validation checks. The result retains a structured source you can revise through the agent. Readers can inspect the generated artifact in a browser without installing Archify themselves.++That distinction matters: Archify is not an independent source-code discovery service, a live system monitor, or a hosted team editor. A convincing picture is not evidence for a relationship that was never established.++<span id="setup" class="section-anchor" aria-hidden="true"></span>++## Set up your agent++Open the [agent-aware quick start](start.html). Select the agent you actually use and choose a project-scoped or global installation. Follow the command shown there rather than copying another agent's installation path.++The [installation reference](https://github.com/tt-a1i/archify/blob/main/README.md#installation-options) explains supported surfaces and their constraints. The renderer workflow needs an environment with file access and Node.js; requirements can differ by integration. Being able to chat with an AI model alone does not establish that the environment can run the workflow.++Installation instructions are not a guarantee that every agent/version combination has been tested. If setup fails, record the agent, its version, your operating system, and the exact error before changing the diagram itself.++<span id="cache-scenarios" class="section-anchor" aria-hidden="true"></span>++## Try two bounded requests: cache hit and cache miss++A sequence diagram answers “who calls whom, and in what order?” For the stable 3.1.0 workflow described here, make two separate diagrams for these mutually exclusive scenarios rather than putting them on one request timeline. Try this description in your configured agent:++> Use Archify to create two separate sequence diagrams: one for a cache hit and one for a cache miss. Both begin with Browser calling API and API checking Redis. On a hit, API returns the cached result to Browser. On a miss, API queries PostgreSQL, writes the result to Redis, and returns it to Browser. Clearly label the scenario each diagram represents. Do not arrange mutually exclusive paths as the chronological steps of one request. Do not add authentication, queues, retries, or measured timings that were not specified. If missing information would materially affect the order, ask me first.++This is illustrative input, not a claim about your application. The existing [cache-miss example](https://archify.si/gallery/artifacts/cache-miss.sequence.html) illustrates a different, miss-only request with additional authentication and trace details. It is not the output of this prompt; do not copy those extra facts into your own system without evidence.++When reviewing your result, check:++- Are Browser, API, Redis, and PostgreSQL represented with the intended responsibilities?+- Are there two separately labeled diagrams, with no suggestion that a hit and a miss both execute during the same request?+- Does the miss path return a response after the database lookup and cache write described in the input?+- Did the agent introduce any unsupported behavior or timings?++If the diagram is wrong, correct the meaning first. For example: “In our application, cache population is asynchronous. Update that part of the sequence and mark the response timing as unknown until we confirm it.” Only make that correction when it is true for your application.++<span id="repository-evidence" class="section-anchor" aria-hidden="true"></span>++## Map a repository without inventing its architecture++Tell the agent which repository and behavior matter. A focused request is easier to check than “draw everything.”++> Read this repository and use Archify to explain the runtime path for [specific request or job]. Identify the components and relationships supported by the code. Distinguish runtime components from build or development tools. Use repository evidence where supported, state which revision you inspected, and mark unknown deployment details rather than inventing them. Keep implementation detail in supporting cards when it does not help explain the primary path.++Before accepting a repository-backed diagram, check:++- Scope: which request, job, module, or subsystem does it explain?+- Revision: what repository and commit were inspected?+- Evidence: which files support each important component and relationship?+- Boundaries: are external services and ownership or deployment boundaries established, or merely assumed?+- Completeness: are important failure or return paths missing from the story?+- Unknowns: are missing facts visible rather than disguised as certainty?++Where an artifact includes verified source links, inspect them. A source link shows where the diagram's evidence comes from; it does not by itself establish production behavior. Logs, traces, configuration, and human review may still be needed.++For an existing source-backed example, see the [MCO runtime architecture](https://archify.si/cases/mco-runtime.architecture.html) and its [typed source](https://github.com/tt-a1i/archify/blob/main/docs/cases/mco-runtime.architecture.json). The example describes its pinned revision, not the repository's future state.++<span id="review-and-share" class="section-anchor" aria-hidden="true"></span>++## Revise, inspect, and share++Make focused revisions through your agent: explain a missing return, rename a component, or correct a relationship. Preserve facts that have not changed. Ask the agent to rerun the applicable checks and report failures rather than presenting an unchecked revision as complete.++Open the HTML and review both its meaning and readability. Automated checks and a human visual inspection answer different questions. Do not treat one as a substitute for the other.++Share the HTML when readers need its interactions. Use an image export when a document or slide needs a static view. Archify documents PNG, JPEG, WebP, SVG, and WebM exports; availability depends on the format, browser, and local tooling. Inspect the actual artifact's export menu before committing to a delivery format. An exported image does not preserve the HTML's interactive controls.++Before sharing a repository-derived artifact, check its labels, cards, embedded source, and links for information that should not leave your team. A standalone file is portable, not automatically public-safe. The coding agent's own data handling remains separate from Archify's artifact format.++<span id="questions" class="section-anchor" aria-hidden="true"></span>++## Questions people ask++### Is Archify an AI image generator?++It produces structured diagrams through an agent-authored JSON and rendering workflow. Use it for explainable parts, relationships, steps, and states, rather than treating it as a general-purpose illustration generator.++### Which diagram types are available?++The current stable documentation lists architecture, workflow, sequence, dataflow, lifecycle, entity-relationship, class, tree, timeline, and waterfall diagrams. The [scenario guide](guide.html) explains selected starting recipes; it is not a promise that every mode supports every interaction or notation.++### Can I use it for flowcharts or UML?++Workflow mode can describe steps, branches, and participants. Class and sequence modes address particular modeling needs associated with UML. Choose the supported type for your question; do not assume complete UML-standard coverage from the existence of a class or sequence diagram.++### 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.++### Is a repository required?++No. A clear description can be enough. A repository becomes useful when the diagram must explain real code and you want inspectable source evidence.++### Is it free, and which Archify is this?++This guide concerns the [tt-a1i/archify open-source project](https://github.com/tt-a1i/archify), whose official website is [archify.si](https://archify.si). Its code is MIT-licensed. Your agent or other services may have their own costs and terms. A similarly named paid service is not automatically affiliated with this project.++### What should I do next?++Use [Start](start.html) for installation, the [Scenario Guide](guide.html) to choose a recipe, and the [Proof Lab](gallery.html) to inspect existing artifacts and their evidence.diff --git a/website/src/content/agent-diagrams.zh.md b/website/src/content/agent-diagrams.zh.mdnew file mode 100644index 00000000..dbf4b9f3--- /dev/null+++ b/website/src/content/agent-diagrams.zh.md@@ -0,0 +1,111 @@+# 用 Coding Agent 画出可检查的图++Archify 是面向 Coding Agent 的开源画图技能,可配合 Claude Code、Codex、Cursor、OpenCode 和 GitHub Copilot 使用。Agent 理解你的描述或代码仓库证据,编写结构化 JSON;Archify 将其渲染并校验为可交互的 HTML 图。++当你需要讲清系统组成、流程步骤、调用顺序或其他受支持的关系结构时,可以使用它。没有仓库也能从文字开始;需要解释真实代码时,再让 Agent 查阅相关源码。++图表达的是作者提供的事实模型。通过图表校验,不等于证明真实系统确实如此运行。++<span id="responsibilities" class="section-anchor" aria-hidden="true"></span>++## Agent 和 Archify 分别负责什么?++Agent 阅读你提供的信息,询问关键缺失事实,选择图型,并编写或修改结构化源文件。任务涉及真实仓库时,Agent 还需要检查相关代码。++Archify 根据源文件生成 HTML,并执行对应的渲染与校验。你可以保留结构化源文件,继续让 Agent 修改;读者只需在浏览器中打开生成的 HTML,不必安装 Archify。++因此,不要把它理解为独立的代码发现服务、生产监控系统或在线团队编辑器。一张好看的图,不能替一条没有依据的连线作证。++<span id="setup" class="section-anchor" aria-hidden="true"></span>++## 先配置你实际使用的 Agent++打开[快速开始](start.html),选择自己的 Agent,再按需要选择项目级或全局安装。使用页面给出的对应命令,不要套用其他 Agent 的安装目录。++[安装说明](https://github.com/tt-a1i/archify/blob/main/README.md#installation-options)列出了不同使用入口及限制。完整渲染流程需要文件访问和 Node.js 等环境能力,具体要求因集成方式而异。能与模型聊天,不等于当前环境能执行完整工作流。++安装说明也不表示所有 Agent 版本组合都已验证。如果失败,先记录 Agent 及版本、操作系统和完整错误,再判断问题出在配置还是图表本身。++<span id="cache-scenarios" class="section-anchor" aria-hidden="true"></span>++## 第一个例子:分别画缓存命中与未命中++时序图适合回答“谁调用谁,先后顺序怎样”。对于这里介绍的稳定版 3.1.0 工作流,应把这两种互斥场景分别画成两张图,不要放在同一次请求的时间线上。在完成配置的 Agent 中,可以这样描述:++> 用 Archify 分别画两张时序图:缓存命中场景和缓存未命中场景。两者都从 Browser 调用 API、API 查询 Redis 开始。命中时,API 将缓存结果返回 Browser;未命中时,API 查询 PostgreSQL,把结果写入 Redis,再返回 Browser。明确标注每张图对应的场景,不要把互斥路径串成同一次请求的时间顺序。不要添加未说明的鉴权、队列、重试或实测耗时。缺失信息会实质影响顺序时,先问我。++这是演示输入,不是对你应用行为的断言。现有的[缓存未命中示例](https://archify.si/gallery/artifacts/cache-miss.sequence.html)描述的是另一条包含鉴权与追踪细节的未命中路径,不是上述提示词的生成结果。不要把它额外的设定当成自己系统的事实。++检查成品时,重点看:++- Browser、API、Redis 和 PostgreSQL 的职责是否符合描述?+- 是否有两张场景标注明确的独立图,而不是暗示一次请求会同时经历命中与未命中?+- 未命中路径是否按描述完成数据库查询、缓存写入和响应返回?+- Agent 是否擅自添加了行为或耗时?++如果图不准确,先改语义,再调外观。例如,只有在符合实际情况时才补充:“我们的缓存写入是异步的,请修改对应部分;响应的具体时机还没确认,先标为未知。”++<span id="repository-evidence" class="section-anchor" aria-hidden="true"></span>++## 从仓库画架构图,怎样避免编造?++说明要看的仓库和具体行为。比起“把整个项目都画出来”,范围明确的问题更容易验证。++> 阅读这个仓库,用 Archify 解释[某个请求或任务]的运行路径。只画代码支持的组件和关系,区分运行时组件与构建、开发工具。在支持的范围内附上仓库证据,说明检查的版本;未知的部署信息标为未知,不要猜测。不影响主路径理解的实现细节放进补充卡片。++接受成品前,逐项确认:++- 范围:解释的是哪个请求、任务、模块或子系统?+- 版本:检查的是哪个仓库、哪个提交?+- 证据:哪些文件支持关键组件和关系?+- 边界:外部服务、归属和部署边界有依据,还是假设?+- 完整性:是否遗漏影响理解的失败路径或返回路径?+- 未知项:缺失事实是否明确暴露,而不是被画得像定论?++如果成品附有已验证的源码链接,应点开检查。源码链接说明证据来自哪里,不会自动证明生产环境的运行行为;必要时仍需日志、链路追踪、配置及人工确认。++可参考现有的 [MCO 运行时架构示例](https://archify.si/cases/mco-runtime.architecture.html)及其[结构化源文件](https://github.com/tt-a1i/archify/blob/main/docs/cases/mco-runtime.architecture.json)。它解释的是所标明的提交版本,不代表仓库之后永远保持相同结构。++<span id="review-and-share" class="section-anchor" aria-hidden="true"></span>++## 修改、检查和分享++每次提出聚焦的修改:补充一个返回、重命名一个组件,或纠正一条关系。没有变化的事实应保持不变。要求 Agent 重新执行适用检查,遇到失败如实报告,不要把未经检查的版本当成最终交付。++打开 HTML,分别检查内容是否准确、文字和连线是否可读。自动校验与人工视觉检查解决的是不同问题,不能彼此替代。++读者需要交互时,分享 HTML;文档或幻灯片需要静态画面时,再导出图片。文档列出了 PNG、JPEG、WebP、SVG 和 WebM 等导出格式,但具体可用性取决于格式、浏览器及本地工具。先查看实际成品的导出菜单,再承诺交付格式。导出图片不会保留 HTML 中的交互控件。++分享仓库生成的图之前,检查标签、卡片、内嵌源文件和链接是否包含不宜外传的信息。单文件便于携带,并不表示适合公开。你使用的 Coding Agent 如何处理数据,也不能仅凭 Archify 的输出格式推断。++<span id="questions" class="section-anchor" aria-hidden="true"></span>++## 常见问题++### Archify 是 AI 图片生成器吗?++它通过 Agent 编写 JSON、再渲染的方式生成结构化图表。更适合解释组成、关系、步骤和状态,而不是通用插画生成。++### 支持哪些图?++当前稳定版文档列出架构图、工作流、时序图、数据流、生命周期、实体关系图、类图、树图、时间线和瀑布图。[场景指南](guide.html)提供精选配方,但不同图型不一定拥有完全相同的交互和表示能力。++### 能画流程图或 UML 吗?++工作流可表达步骤、分支和参与者;类图与时序图适合 UML 相关的部分建模需求。应按问题选择已支持的图型,不要由“有类图和时序图”推断为完整支持全部 UML 标准。++### 能从 Mermaid 开始吗?++可以让 Agent 理解受支持的 Mermaid 输入,并按含义重新编写 Archify JSON。这不等于承诺完整自动解析或无损往返转换。转换后要检查重要关系和分支是否保留下来。++### 必须有代码仓库吗?++不需要。足够清楚的文字描述即可作为起点。只有当图需要解释真实代码、并希望检查源码证据时,仓库才成为重要输入。++### 免费吗?这里说的是哪个 Archify?++这里指 [tt-a1i/archify 开源项目](https://github.com/tt-a1i/archify),官方网站是 [archify.si](https://archify.si)。项目代码采用 MIT 许可证。你使用的 Agent 或其他服务可能另有费用与条款;名称相似的收费服务不自动构成官方关联。++### 接下来做什么?++去[快速开始](start.html)完成安装,用[场景指南](guide.html)选择配方,再到[验证作品集](gallery.html)查看成品与对应证据。diff --git a/website/src/data/agent-diagrams-head.html b/website/src/data/agent-diagrams-head.htmlnew file mode 100644index 00000000..a25f0206--- /dev/null+++ b/website/src/data/agent-diagrams-head.html@@ -0,0 +1 @@+<link rel="icon" type="image/svg+xml" href="assets/archify-mark.svg"><link href="fonts/fonts.css" rel="stylesheet">diff --git a/website/src/data/localize-html.mjs b/website/src/data/localize-html.mjsindex eff83e37..d4e14a28 100644--- a/website/src/data/localize-html.mjs+++ b/website/src/data/localize-html.mjs@@ -31,7 +31,7 @@ export function localizeHtml(html, { lang, page, cloudflare, copy = {} }) {node.childNodes = [{ nodeName: '#text', value: lang === 'zh' ? 'EN' : '中文', parentNode: node }];} else if (node.tagName === 'a') {const href = get('href');- const match = href?.match(/^(?:(index|guide|start|gallery|community)\.html|(\.\/))([?#].*)?$/);+ const match = href?.match(/^(?:(index|guide|start|gallery|community|agent-diagrams)\.html|(\.\/))([?#].*)?$/);if (match) set('href', localPagePath(match[1] || 'index', lang, cloudflare) + (match[3] || ''));else if (href?.startsWith('#')) set('href', localPagePath(page, lang, cloudflare) + href);}diff --git a/website/src/data/site-metadata.mjs b/website/src/data/site-metadata.mjsindex ddf463a4..13e3185d 100644--- a/website/src/data/site-metadata.mjs+++ b/website/src/data/site-metadata.mjs@@ -1,5 +1,9 @@import { canonicalUrl, canonicalOrigin } from './site-urls.mjs';const descriptions = {+ 'agent-diagrams': {+ en: ['Archify Agent Diagramming Guide — Author, Review, Share', 'Create diagrams with Claude Code, Codex, Cursor and other coding agents. Learn bounded prompts, repository evidence, review checks and safe HTML sharing with Archify.'],+ zh: ['Archify Agent 画图指南 — 编写、检查与分享', '用 Claude Code、Codex、Cursor 等 Coding Agent 画图:从范围明确的提示词和仓库证据开始,检查事实、修改图表,再安全分享 Archify HTML 成品。'],+ },index: {en: ['Archify — Interactive Diagram Skill for AI Coding Agents', 'Create architecture, workflow, and sequence diagrams with Claude Code, Codex, or other coding agents. Archify is an MIT-licensed skill that delivers interactive HTML.'],zh: ['Archify — 面向 AI Agent 的交互式画图工具', '用 Claude Code、Codex 等 AI Agent 从自然语言或代码仓库创建架构图、流程图和时序图。Archify 是采用 MIT 许可证的开源画图 Skill,交付可探索、可导出的交互式 HTML。'],@@ -28,6 +32,7 @@ export function pageMetadata(page, lang, version) {schema: { '@context': 'https://schema.org', '@graph': [{ '@type': 'WebSite', '@id': `${canonicalOrigin}/#website`, url: `${canonicalOrigin}/`, name: 'Archify', inLanguage: ['en', 'zh-Hans'] },{ '@type': 'SoftwareSourceCode', '@id': `${canonicalOrigin}/#source`, name: 'Archify', codeRepository: 'https://github.com/tt-a1i/archify', url: 'https://github.com/tt-a1i/archify', license: 'https://github.com/tt-a1i/archify/blob/main/LICENSE', version, programmingLanguage: 'JavaScript', description: descriptions.index[lang][1] },+ ...(page === 'agent-diagrams' ? [{ '@type': 'TechArticle', '@id': `${canonical}#article`, url: canonical, headline: title, description, inLanguage: lang === 'zh' ? 'zh-Hans' : 'en', isPartOf: { '@id': `${canonicalOrigin}/#website` }, about: { '@id': `${canonicalOrigin}/#source` } }] : []),] },};}diff --git a/website/src/data/site-urls.mjs b/website/src/data/site-urls.mjsindex e77019cd..cb8bebc0 100644--- a/website/src/data/site-urls.mjs+++ b/website/src/data/site-urls.mjs@@ -1,5 +1,5 @@export const canonicalOrigin = 'https://archify.si';-export const sitePages = ['index', 'guide', 'start', 'gallery', 'community'];+export const sitePages = ['index', 'guide', 'start', 'gallery', 'community', 'agent-diagrams'];export function canonicalPath(page, lang = 'en') {return page === 'index' ? (lang === 'zh' ? '/zh' : '/') : `${lang === 'zh' ? '/zh/' : '/'}${page}`;}diff --git a/website/src/layouts/SiteLayout.astro b/website/src/layouts/SiteLayout.astroindex baf17ca6..1dd8286c 100644--- a/website/src/layouts/SiteLayout.astro+++ b/website/src/layouts/SiteLayout.astro@@ -9,7 +9,7 @@ import { productChannel } from '../data/product-facts';import { canonicalUrl } from '../data/site-urls.mjs';import { pageMetadata } from '../data/site-metadata.mjs';import { localizeHtml } from '../data/localize-html.mjs';-interface Props { head: string; css: string; page: 'index' | 'guide' | 'start' | 'gallery' | 'community'; lang?: 'en' | 'zh' }+interface Props { head: string; css: string; page: 'index' | 'guide' | 'start' | 'gallery' | 'community' | 'agent-diagrams'; lang?: 'en' | 'zh' }const { head, css, page, lang = 'en' } = Astro.props;const cloudflare = Astro.site?.origin === 'https://archify.si';const metadata = pageMetadata(page, lang, version);diff --git a/website/src/pages/agent-diagrams.astro b/website/src/pages/agent-diagrams.astronew file mode 100644index 00000000..6aea2356--- /dev/null+++ b/website/src/pages/agent-diagrams.astro@@ -0,0 +1,31 @@+---+import SiteLayout from '../layouts/SiteLayout.astro';+import Navigation from '../components/Navigation.astro';+import { Content as English, getHeadings as englishHeadings } from '../content/agent-diagrams.en.md';+import { Content as Chinese, getHeadings as chineseHeadings } from '../content/agent-diagrams.zh.md';+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', '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] }));++---+<SiteLayout page="agent-diagrams" lang={lang} head={head} css={css}>+ <div class="grid-bg" aria-hidden="true"></div>+ <Navigation page="agent-diagrams" />+ <main class="agent-guide">+ <header class="article-meta">+ <p>{lang === 'zh' ? '实践指南 · 编写 / 检查 / 分享' : 'Field guide · Author / Review / Share'}</p>+ <p>{lang === 'zh' ? '最近核对:2026-10-15 · 稳定版 3.1.0 · 提示词为示例输入,并非 Agent 实测记录。' : 'Last reviewed: 2026-10-15 · Stable 3.1.0 · Prompts are illustrative inputs, not recorded agent runs.'}</p>+ </header>+ <div class="article-grid">+ <nav class="article-toc" aria-label={lang === 'zh' ? '本页目录' : 'On this page'}>+ <p>{lang === 'zh' ? '本页目录' : 'On this page'}</p>+ <ol>{headings.map(heading => <li><a href={`#${heading.slug}`}>{heading.text}</a></li>)}</ol>+ </nav>+ <article class="article-body"><Content /></article>+ </div>+ </main>+ <footer class="article-footer"><a href="start.html">{lang === 'zh' ? '配置你的 Agent →' : 'Set up your agent →'}</a><a href="guide.html">{lang === 'zh' ? '选择图表配方 →' : 'Choose a diagram recipe →'}</a></footer>+</SiteLayout>diff --git a/website/src/pages/guide.astro b/website/src/pages/guide.astroindex 28210fe8..db5682a5 100644--- a/website/src/pages/guide.astro+++ b/website/src/pages/guide.astro@@ -53,6 +53,10 @@ const { lang = 'en' } = Astro.props;<div class="cards" id="cards"></div></section><RecipeReference recipes={guide} />+ <aside class="agent-guide-link" aria-label={lang === 'zh' ? 'Agent 画图指南' : 'Agent diagramming guide'}>+ <a href="agent-diagrams.html" data-en="From prompt to a diagram you can trust →" data-zh="从提示词到可检查的图 →">From prompt to a diagram you can trust →</a>+ <p data-en="Learn how to author, review and share diagrams with your coding agent." data-zh="了解如何用 Coding Agent 编写、检查和分享图表。">Learn how to author, review and share diagrams with your coding agent.</p>+ </aside></main><footer><div class="shell"><span data-i18n="footerLeft">Generated from the same recipe source as the Archify CLI.</span><span>archify guide "your scenario"</span><span data-i18n="versionLabel">Scenario guide / development / v{version}</span></div></footer>diff --git a/website/src/pages/start.astro b/website/src/pages/start.astroindex 28e971d0..2dcf1a98 100644--- a/website/src/pages/start.astro+++ b/website/src/pages/start.astro@@ -94,6 +94,10 @@ const { lang = 'en' } = Astro.props;<span id="copy-status" role="status" aria-live="polite"></span><a href="https://github.com/tt-a1i/archify" data-en="View source on GitHub ↗" data-zh="在 GitHub 查看源码 ↗">View source on GitHub ↗</a></footer>+ <aside class="agent-guide-link" aria-label={lang === 'zh' ? 'Agent 画图指南' : 'Agent diagramming guide'}>+ <a href="agent-diagrams.html" data-en="From prompt to a diagram you can trust →" data-zh="从提示词到可检查的图 →">From prompt to a diagram you can trust →</a>+ <p data-en="Learn how to author, review and share diagrams with your coding agent." data-zh="了解如何用 Coding Agent 编写、检查和分享图表。">Learn how to author, review and share diagrams with your coding agent.</p>+ </aside></main><script is:inline id="start-data" type="application/json" set:html={jsonScript(starts)}></script>diff --git a/website/src/pages/zh/agent-diagrams.astro b/website/src/pages/zh/agent-diagrams.astronew file mode 100644index 00000000..3e25d870--- /dev/null+++ b/website/src/pages/zh/agent-diagrams.astro@@ -0,0 +1,4 @@+---+import Page from '../agent-diagrams.astro';+---+<Page lang="zh" />diff --git a/website/src/scripts/site-language.js b/website/src/scripts/site-language.jsindex 476a36bb..8bf0c89d 100644--- a/website/src/scripts/site-language.js+++ b/website/src/scripts/site-language.js@@ -29,7 +29,7 @@function localizeLinks() {document.querySelectorAll('a[href]').forEach(function (link) {if (link.hasAttribute('data-language-switch')) return;- var match = link.getAttribute('href').match(/^(index|guide|start|gallery|community)\.html([?#].*)?$/);+ var match = link.getAttribute('href').match(/^(index|guide|start|gallery|community|agent-diagrams)\.html([?#].*)?$/);if (match) link.setAttribute('href', pagePath(match[1], language) + (match[2] || ''));});}diff --git a/website/src/styles/agent-diagrams.css b/website/src/styles/agent-diagrams.cssnew file mode 100644index 00000000..a3643f23--- /dev/null+++ b/website/src/styles/agent-diagrams.css@@ -0,0 +1,26 @@+.agent-guide { position:relative; max-width:1180px; margin:auto; padding:120px 24px 64px; }+.article-meta { padding-bottom:2rem; border-bottom:1px solid var(--line-hi); }+.article-meta p:first-child { font-family:var(--font-mono); text-transform:uppercase; letter-spacing:.09em; color:var(--accent-text); font-size:.78rem; }+.article-meta p + p { margin-top:.8rem; color:var(--text-2); font-size:.82rem; line-height:1.7; }+.article-grid { display:grid; grid-template-columns:220px minmax(0,1fr); gap:60px; padding-top:3rem; }+.article-toc { align-self:start; position:sticky; top:92px; font-size:.85rem; line-height:1.6; }+.article-toc > p { font-weight:600; margin-bottom:1rem; }+.article-toc ol { padding-left:1.2rem; }+.article-toc li { margin:.8rem 0; color:var(--text-2); }+.article-toc a { text-decoration:none; }+.article-toc a:hover { color:var(--accent-text); }+.article-body { min-width:0; max-width:760px; font-size:1.02rem; line-height:1.85; overflow-wrap:anywhere; }+.article-body h1 { font-family:var(--font-title); font-size:clamp(2.25rem,4.5vw,3.7rem); line-height:1.13; letter-spacing:-.045em; margin-bottom:2rem; }+.article-body h2 { font-family:var(--font-title); font-size:1.65rem; line-height:1.35; margin:3.2rem 0 1rem; letter-spacing:-.025em; scroll-margin-top:130px; }+.article-body h3 { font-size:1.12rem; line-height:1.5; margin:2rem 0 .6rem; scroll-margin-top:130px; }+.article-body p { margin:1rem 0; color:var(--text-2); }+.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 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; }+@media(max-width:960px) { .agent-guide { padding-top:145px; } .article-grid { grid-template-columns:1fr; gap:2rem; } .article-toc { position:static; padding:1.2rem; border:1px solid var(--line-hi); border-radius:12px; } .article-toc ol { columns:2; column-gap:2rem; } .article-body { max-width:none; } }+@media(max-width:520px) { .agent-guide { padding-left:20px; padding-right:20px; } .article-toc ol { columns:1; } .article-body { font-size:1rem; } }++.section-anchor { display:block; scroll-margin-top:130px; }diff --git a/website/src/styles/site.css b/website/src/styles/site.cssindex 49c84bb5..32682af6 100644--- a/website/src/styles/site.css+++ b/website/src/styles/site.css@@ -69,6 +69,10 @@.grid-bg::after { content:''; position:absolute; inset:0;background:radial-gradient(ellipse 45% 40% at 78% 0%, rgba(var(--accent-rgb),.16), transparent 70%), radial-gradient(ellipse 40% 35% at 12% 6%, rgba(var(--signal-rgb),.07), transparent 70%); }+ .agent-guide-link { margin:3rem 0; padding:1.5rem; border:1px solid var(--line-hi); border-radius:16px; background:var(--surface); }+ .agent-guide-link a { color:var(--accent-text); font-weight:600; text-underline-offset:4px; }+ .agent-guide-link p { margin-top:.65rem; color:var(--text-2); line-height:1.7; }+/* page titles — grotesk statement, Fraunces italic accent */h1 { background:linear-gradient(180deg,var(--title-top) 0%,var(--title-top) 55%,var(--title-end) 100%); -webkit-background-clip:text; background-clip:text; -webkit-text-fill-color:transparent; }html[lang^="zh"] h1 em { font-family:inherit!important; font-style:normal!important; font-weight:600!important; }diff --git a/website/test/agent-diagrams-browser.test.mjs b/website/test/agent-diagrams-browser.test.mjsnew file mode 100644index 00000000..281deb75--- /dev/null+++ b/website/test/agent-diagrams-browser.test.mjs@@ -0,0 +1,175 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import fs from 'node:fs';+import http from 'node:http';+import path from 'node:path';+import { fileURLToPath } from 'node:url';+import { execFileSync } from 'node:child_process';+import { ChromeVisualBrowser, findChrome } from '../../archify/bin/visual-check.mjs';++const website = fileURLToPath(new URL('../', import.meta.url));+const enabled = process.env.ARCHIFY_SITE_INTEGRATION === '1';+const root = path.resolve(process.env.ARCHIFY_SITE_ROOT || path.join(website, 'dist'));+const mount = process.env.ARCHIFY_SITE_BASE ?? '/archify';+const target = mount ? 'github' : 'cloudflare';+const output = path.join(website, '.browser-evidence', target);++test('real Chrome: agent guide stays readable and navigable in both languages, themes and narrow viewports', {+ skip: enabled ? false : 'Set ARCHIFY_SITE_INTEGRATION=1 and ARCHIFY_CHROME to run agent guide browser evidence.',+ timeout: 180000,+}, async () => {+ const chrome = findChrome();+ assert.ok(chrome, 'The requested agent guide gate requires usable Chrome.');+ const server = http.createServer((request, response) => {+ const url = new URL(request.url, 'http://127.0.0.1');+ if (mount && !url.pathname.startsWith(`${mount}/`)) return response.writeHead(404).end();+ let relative = url.pathname.slice(mount.length).replace(/^\/+/, '') || 'index.html';+ // Resolve actual static HTML routes, never an SPA fallback.+ if (!path.extname(relative) && fs.existsSync(path.join(root, `${relative}.html`))) relative += '.html';+ const file = path.resolve(root, relative);+ if (!file.startsWith(`${root}${path.sep}`)) return response.writeHead(404).end();+ try {+ const types = { '.html': 'text/html', '.js': 'text/javascript', '.css': 'text/css', '.svg': 'image/svg+xml', '.woff2': 'font/woff2' };+ response.setHeader('Content-Type', types[path.extname(file)] || 'application/octet-stream');+ response.end(fs.readFileSync(file));+ } catch { response.writeHead(404).end(); }+ });+ let browser;+ fs.mkdirSync(output, { recursive: true });+ const event = process.env.GITHUB_EVENT_PATH ? JSON.parse(fs.readFileSync(process.env.GITHUB_EVENT_PATH, 'utf8')) : null;+ const manifest = {+ capturedAt: new Date().toISOString(), target,+ checkoutSha: execFileSync('git', ['rev-parse', 'HEAD'], { cwd: website, encoding: 'utf8' }).trim(),+ pullRequestHead: event?.pull_request?.head?.sha || null,+ runId: process.env.GITHUB_RUN_ID || null,+ screenshots: [], navigation: [],+ };+ const saveManifest = () => fs.writeFileSync(path.join(output, 'agent-diagrams-manifest.json'), JSON.stringify(manifest, null, 2));+ try {+ await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));+ browser = new ChromeVisualBrowser(chrome);+ const session = await browser.sessionPromise;+ const evaluate = async expression => {+ const result = await browser.cdp.send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true }, session);+ assert.ok(!result.exceptionDetails, JSON.stringify(result.exceptionDetails));+ return result.result.value;+ };+ const settled = () => evaluate('new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)))');+ const loadedAction = async action => {+ const loaded = browser.cdp.waitFor('Page.loadEventFired', session);+ loaded.catch(() => {});+ await action();+ await loaded;+ await evaluate('document.fonts.ready');+ };+ const assertSectionVisible = async () => {+ const position = await evaluate(`(async () => {+ // Let native smooth fragment navigation finish, without overriding it.+ const started = performance.now(); let last = scrollY, stable = 0;+ while (performance.now() - started < 2500) {+ await new Promise(resolve => requestAnimationFrame(resolve));+ stable = Math.abs(scrollY - last) < .5 ? stable + 1 : 0; last = scrollY;+ if (stable >= 5 && performance.now() - started > 200) break;+ }+ const anchor = document.getElementById(location.hash.slice(1));+ const boundary = anchor?.parentElement.tagName === 'P' ? anchor.parentElement : anchor;+ const heading = boundary?.nextElementSibling;+ const box = heading?.getBoundingClientRect();+ return { tag: heading?.tagName, top: box?.top, bottom: box?.bottom, navBottom: document.querySelector('.site-nav').getBoundingClientRect().bottom, height: innerHeight };+ })()`);+ assert.equal(position.tag, 'H2');+ assert.ok(position.top >= position.navBottom - 1 && position.bottom <= position.height, 'fragment target heading is visible below the fixed navigation');+ return position;+ };+ const urlFor = (page, lang) => `http://127.0.0.1:${server.address().port}${mount}/${lang === 'zh' ? 'zh/' : ''}${page}${mount ? '.html' : ''}`;+ const navigate = url => loadedAction(() => browser.cdp.send('Page.navigate', { url }, session));+ await browser.cdp.send('Emulation.setEmulatedMedia', { features: [{ name: 'prefers-reduced-motion', value: 'reduce' }] }, session);+ for (const width of [1440, 390, 320]) for (const lang of ['en', 'zh']) {+ await browser.cdp.send('Emulation.setDeviceMetricsOverride', { width, height: 1000, deviceScaleFactor: 1, mobile: width < 768 }, session);+ await navigate(urlFor('agent-diagrams', lang));+ for (const theme of ['light', 'dark']) {+ await evaluate(`if (document.documentElement.dataset.theme !== ${JSON.stringify(theme)}) document.querySelector('[data-theme-toggle]').click()`);+ await settled();+ const reading = await evaluate(`(() => {+ const article = document.querySelector('.article-body');+ const failures = [];+ const walker = document.createTreeWalker(article, NodeFilter.SHOW_TEXT);+ while (walker.nextNode()) {+ const node = walker.currentNode;+ if (!node.textContent.trim()) continue;+ for (let parent = node.parentElement; parent && parent !== document.body; parent = parent.parentElement) {+ const style = getComputedStyle(parent);+ if (style.visibility !== 'visible' || style.display === 'none' || Number(style.opacity) === 0) failures.push({ text: node.textContent.slice(0, 100), reason: 'hidden text' });+ }+ const range = document.createRange(); range.selectNodeContents(node);+ const rects = [...range.getClientRects()].filter(rect => rect.width > 0 && rect.height > 0);+ if (!rects.length) failures.push({ text: node.textContent.slice(0, 100), reason: 'text has no rendered bounds' });+ for (const rect of rects) {+ if (rect.left < -1 || rect.right > innerWidth + 1) failures.push({ text: node.textContent.slice(0, 100), reason: 'outside viewport horizontally' });+ for (let parent = node.parentElement; parent && parent !== document.body; parent = parent.parentElement) {+ const style = getComputedStyle(parent), box = parent.getBoundingClientRect();+ if (['hidden', 'clip'].includes(style.overflowX) && (rect.left < box.left - 1 || rect.right > box.right + 1)) failures.push({ text: node.textContent.slice(0, 100), reason: 'horizontal clipping' });+ if (['hidden', 'clip'].includes(style.overflowY) && (rect.top < box.top - 1 || rect.bottom > box.bottom + 1)) failures.push({ text: node.textContent.slice(0, 100), reason: 'vertical clipping' });+ }+ }+ }+ return { lang: document.documentElement.lang, theme: document.documentElement.dataset.theme, width: innerWidth, pageWidth: document.documentElement.scrollWidth, failures };+ })()`);+ // 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', 'cache-example', 'review-limits']) {+ const bounds = await evaluate(`(() => {+ const article = document.querySelector('.article-body');+ const start = ${JSON.stringify(region)} === 'opening' ? article.querySelector('h1') : document.getElementById(${JSON.stringify(region === 'cache-example' ? 'cache-scenarios' : 'review-and-share')});+ const end = document.getElementById(${JSON.stringify(region === 'opening' ? 'responsibilities' : region === 'cache-example' ? 'repository-evidence' : 'questions')});+ return { top: start.getBoundingClientRect().top + scrollY, bottom: end.getBoundingClientRect().top + scrollY, nav: document.querySelector('.site-nav').getBoundingClientRect().bottom };+ })()`);+ const inset = bounds.nav + 20;+ const step = 1000 - inset - 40;+ const tiles = Math.max(1, Math.ceil((bounds.bottom - bounds.top) / step));+ assert.ok(tiles <= 12, `${region}: unexpectedly unbounded article region`);+ for (let tile = 0; tile < tiles; tile++) {+ await evaluate(`scrollTo({ top: ${Math.max(0, bounds.top - inset + tile * step)}, behavior: 'instant' })`);+ await settled();+ const receipt = await evaluate(`({ scrollY, viewport: { width: innerWidth, height: innerHeight }, lang: document.documentElement.lang, theme: document.documentElement.dataset.theme })`);+ const name = `agent-diagrams-${lang}-${width}-${theme}-${region}-${tile + 1}.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, tile: tile + 1, tiles, bounds, receipt, reading });+ saveManifest();+ }+ }+ assert.equal(reading.lang, lang === 'en' ? 'en' : 'zh-Hans');+ assert.equal(reading.theme, theme);+ assert.equal(reading.width, width);+ assert.ok(reading.pageWidth <= width + 1, 'no horizontal page overflow');+ assert.deepEqual(reading.failures, [], 'all article text remains visible and unclipped');+ }+ // Exercise real authored links, including section and locale continuity.+ await evaluate(`document.querySelector('.article-toc a[href$="#cache-scenarios"]').click()`);+ await settled();+ assert.equal(await evaluate('location.hash'), '#cache-scenarios');+ const tocPosition = await assertSectionVisible();+ await loadedAction(() => evaluate(`document.querySelector('[data-language-switch]').click()`));+ const other = lang === 'en' ? 'zh' : 'en';+ assert.equal(await evaluate('location.pathname'), new URL(urlFor('agent-diagrams', other)).pathname);+ assert.equal(await evaluate('document.documentElement.lang'), other === 'zh' ? 'zh-Hans' : 'en');+ assert.equal(await evaluate('location.hash'), '#cache-scenarios');+ assert.equal(await evaluate('!!document.getElementById(location.hash.slice(1))'), true);+ const localePosition = await assertSectionVisible();+ await loadedAction(() => evaluate(`document.querySelector('.article-footer a').click()`));+ assert.equal(await evaluate('location.pathname'), new URL(urlFor('start', other)).pathname);+ await loadedAction(() => evaluate(`document.querySelector('.agent-guide-link a').click()`));+ assert.equal(await evaluate('location.pathname'), new URL(urlFor('agent-diagrams', other)).pathname);+ await 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, paths: ['toc', 'language with fragment', 'article to start', 'start to article', 'guide to article'] });+ saveManifest();+ }+ } finally {+ saveManifest();+ if (browser) await browser.close();+ if (server.listening) await new Promise(resolve => server.close(resolve));+ }+});diff --git a/website/test/agent-diagrams.test.mjs b/website/test/agent-diagrams.test.mjsnew file mode 100644index 00000000..26b47175--- /dev/null+++ b/website/test/agent-diagrams.test.mjs@@ -0,0 +1,62 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import fs from 'node:fs';+import { parse } from 'parse5';+import { parseSitemap } from '../scripts/indexnow.mjs';++const cloudflare = process.env.ARCHIFY_SITE_TARGET === 'cloudflare';+const output = new URL(cloudflare ? '../dist-cloudflare/' : '../dist/', import.meta.url);+const nodes = node => [node, ...(node.childNodes || []).flatMap(nodes)];+const attr = (node, name) => node.attrs?.find(item => item.name === name)?.value;+const text = node => node.nodeName === '#text' ? node.value : (node.childNodes || []).map(text).join('');++test('agent guide is readable without JavaScript, honest about examples, and linked from both entry points', () => {+ 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 documentUrl = new URL(`${prefix}agent-diagrams${cloudflare ? '' : '.html'}`, cloudflare ? 'https://archify.si/' : 'https://tt-a1i.github.io/archify/');+ const baseUri = new URL(attr(all.find(node => node.tagName === 'base'), 'href'), documentUrl);+ const 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/ : /不是上述提示词的生成结果/);+ assert.match(text(all.find(node => node.tagName === 'main')), lang === 'en' ? /not recorded agent runs/ : /并非 Agent 实测记录/);+ for (const name of ['Claude Code', 'Codex', 'Cursor', 'OpenCode', 'GitHub Copilot']) assert.ok(visible.includes(name));+ const schema = JSON.parse(text(all.find(node => node.tagName === 'script' && attr(node, 'type') === 'application/ld+json')));+ const structuredArticle = schema['@graph'].find(item => item['@type'] === 'TechArticle');+ assert.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', '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);+ assert.equal(destination.origin + destination.pathname, documentUrl.origin + documentUrl.pathname, 'TOC fragments resolve on this page, not the root base');+ const id = decodeURIComponent(destination.hash.slice(1));+ const anchors = nodes(article).filter(node => attr(node, 'id') === id);+ assert.equal(anchors.length, 1, `unique article anchor: ${id}`);+ const anchor = anchors[0];+ // Markdown wraps a standalone inline span in a paragraph.+ const boundary = anchor.parentNode.tagName === 'p' ? anchor.parentNode : anchor;+ const siblings = boundary.parentNode.childNodes;+ const nextElement = siblings.slice(siblings.indexOf(boundary) + 1).find(node => node.tagName);+ assert.equal(nextElement?.tagName, 'h2', `${id}: anchor immediately precedes its section heading`);+ assert.equal(text(nextElement), text(link), `${id}: TOC label must identify the section it reaches, including after reordering`);+ }+ assert.doesNotMatch(visible, /editorial draft|publication checks|workspace\/shared|factcheck\.md/i);+ for (const entry of ['start', 'guide']) {+ const entryNodes = nodes(parse(fs.readFileSync(new URL(`${prefix}${entry}.html`, output), 'utf8')));+ const guideLink = entryNodes.find(node => node.tagName === 'a' && attr(node, 'href') === `${prefix}agent-diagrams${cloudflare ? '' : '.html'}`);+ assert.ok(guideLink, `${prefix}${entry}: contextual discovery`);+ assert.equal(attr(guideLink.parentNode, 'aria-label'), lang === 'zh' ? 'Agent 画图指南' : 'Agent diagramming guide');+ }+ }+});++test('both agent guide routes are included in the actual sitemap and allowed IndexNow inventory', () => {+ const urls = parseSitemap(fs.readFileSync(new URL('sitemap.xml', output), 'utf8'));+ for (const url of ['https://archify.si/agent-diagrams', 'https://archify.si/zh/agent-diagrams']) assert.ok(urls.includes(url));+});diff --git a/website/test/cloudflare-output.test.mjs b/website/test/cloudflare-output.test.mjsindex 54adc229..2a9b50cb 100644--- a/website/test/cloudflare-output.test.mjs+++ b/website/test/cloudflare-output.test.mjs@@ -1,3 +1,4 @@+import { canonicalPath, sitePages } from '../src/data/site-urls.mjs';import { test } from 'node:test';import assert from 'node:assert/strict';import fs from 'node:fs';@@ -8,7 +9,7 @@ import { checkCloudflareOutput } from '../scripts/check-cloudflare-output.mjs';function fixture(t) {const root = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-cloudflare-output-'));t.after(() => fs.rmSync(root, { recursive: true, force: true }));- const names = ['index', 'gallery', 'guide', 'start', 'community', 'zh', 'zh/gallery', 'zh/guide', 'zh/start', 'zh/community'];+ const names = sitePages.flatMap(page => ['en', 'zh'].map(lang => canonicalPath(page, lang).slice(1) || 'index'));const urls = names.map(name => `https://archify.si/${name === 'index' ? '' : name}`);for (const [index, name] of names.entries()) {fs.mkdirSync(path.dirname(path.join(root, `${name}.html`)), { recursive: true });@@ -27,7 +28,7 @@ function fixture(t) {}test('Cloudflare output accepts static files and extensionless canonical routes', t => {- assert.equal(checkCloudflareOutput(fixture(t)), 11);+ assert.equal(checkCloudflareOutput(fixture(t)), sitePages.length * 2 + 1);});test('Cloudflare output rejects a missing 404 before implicit SPA fallback can ship', t => {@@ -60,7 +61,7 @@ test('Cloudflare output rejects an asset exceeding the Pages upload limit', t =>test('Cloudflare output resolves nested-page assets against the HTML base', t => {const root = fixture(t);fs.appendFileSync(path.join(root, 'zh/guide.html'), '<base href="../"><link href="site.css" rel="stylesheet">');- assert.equal(checkCloudflareOutput(root), 11);+ assert.equal(checkCloudflareOutput(root), sitePages.length * 2 + 1);fs.rmSync(path.join(root, 'site.css'));assert.throws(() => checkCloudflareOutput(root), /missing local target site\.css/);});diff --git a/website/test/deployment-target.test.mjs b/website/test/deployment-target.test.mjsindex 0338d8da..9e73356a 100644--- a/website/test/deployment-target.test.mjs+++ b/website/test/deployment-target.test.mjs@@ -1,3 +1,4 @@+import { sitePages } from '../src/data/site-urls.mjs';import { test } from 'node:test';import assert from 'node:assert/strict';import fs from 'node:fs';@@ -9,7 +10,7 @@ const cloudflare = process.env.ARCHIFY_SITE_TARGET === 'cloudflare';const output = new URL(cloudflare ? '../dist-cloudflare/' : '../dist/', import.meta.url);const nodes = node => [node, ...(node.childNodes || []).flatMap(nodes)];const attr = (node, name) => node?.attrs?.find(item => item.name === name)?.value;-const pages = ['index', 'start', 'guide', 'gallery', 'community'];+const pages = sitePages;test('built deployment uses host-compatible generated assets and canonical metadata in both languages', () => {for (const lang of ['en', 'zh']) for (const page of pages) {diff --git a/website/test/local-fonts.test.mjs b/website/test/local-fonts.test.mjsindex 4f58276c..2de15338 100644--- a/website/test/local-fonts.test.mjs+++ b/website/test/local-fonts.test.mjs@@ -1,3 +1,4 @@+import { sitePages } from '../src/data/site-urls.mjs';import { test } from 'node:test';import assert from 'node:assert/strict';import fs from 'node:fs';@@ -12,7 +13,7 @@ const repo = new URL('../../', import.meta.url);const fonts = new URL('../public/fonts/', import.meta.url);const manifest = JSON.parse(fs.readFileSync(new URL('sources.json', fonts), 'utf8'));const css = fs.readFileSync(new URL('fonts.css', fonts), 'utf8');-const pages = ['index', 'guide', 'start', 'gallery', 'community'];+const pages = sitePages;const sha256 = data => createHash('sha256').update(data).digest('hex');const nodes = node => [node, ...(node.childNodes || []).flatMap(nodes)];const attr = (node, name) => node.attrs?.find(item => item.name === name)?.value;diff --git a/website/test/navigation.test.mjs b/website/test/navigation.test.mjsindex 56f36e54..e55ea899 100644--- a/website/test/navigation.test.mjs+++ b/website/test/navigation.test.mjs@@ -1,3 +1,4 @@+import { sitePages } from '../src/data/site-urls.mjs';import { test } from 'node:test';import assert from 'node:assert/strict';import fs from 'node:fs';@@ -6,17 +7,21 @@ import { parse } from 'parse5';const nodes = node => [node, ...(node.childNodes || []).flatMap(nodes)];const attr = (node, name) => node.attrs?.find(item => item.name === name)?.value;const hasClass = (node, name) => (attr(node, 'class') || '').split(/\s+/).includes(name);-const pages = ['index', 'gallery', 'guide', 'start', 'community'];+const pages = sitePages;+const cloudflare = process.env.ARCHIFY_SITE_TARGET === 'cloudflare';+const output = new URL(cloudflare ? '../dist-cloudflare/' : '../dist/', import.meta.url);+const origin = cloudflare ? 'https://archify.si/' : 'https://tt-a1i.github.io/archify/';+const extension = cloudflare ? '' : '.html';-test('all five built pages expose one shared top navigation and the correct current page', () => {+test('all built pages expose one shared top navigation and the correct current page', () => {for (const lang of ['en', 'zh']) for (const page of pages) {const file = page === 'index' ? (lang === 'zh' ? 'zh.html' : 'index.html') : `${lang === 'zh' ? 'zh/' : ''}${page}.html`;- const hrefFor = target => `https://tt-a1i.github.io/archify/${lang === 'zh' ? 'zh/' : ''}${target}.html`;- const dom = parse(fs.readFileSync(new URL(`../dist/${file}`, import.meta.url), 'utf8'));+ const hrefFor = target => `${origin}${lang === 'zh' ? 'zh/' : ''}${target}${extension}`;+ const dom = parse(fs.readFileSync(new URL(file, output), 'utf8'));const bases = nodes(dom).filter(node => node.tagName === 'base');assert.equal(bases.length, 1, file);assert.equal(attr(bases[0], 'href'), lang === 'zh' && page !== 'index' ? '../' : './', file);- const baseUri = new URL(attr(bases[0], 'href'), `https://tt-a1i.github.io/archify/${file}`);+ const baseUri = new URL(attr(bases[0], 'href'), new URL(cloudflare ? file.replace(/\.html$/, '').replace(/^index$/, '') : file, origin));const resolvedHref = node => new URL(attr(node, 'href'), baseUri).href;const nav = nodes(dom).find(node => node.tagName === 'nav' && hasClass(node, 'site-nav'));assert.ok(nav, page);@@ -25,7 +30,7 @@ test('all five built pages expose one shared top navigation and the correct curr...['guide', 'gallery', 'start', 'community'].map(hrefFor), 'https://github.com/tt-a1i/archify',], page);assert.deepEqual(links.filter(node => attr(node, 'aria-current') === 'page').map(resolvedHref),- page === 'index' ? [] : [hrefFor(page)], page);+ ['index', 'agent-diagrams'].includes(page) ? [] : [hrefFor(page)], page);const community = links.find(node => resolvedHref(node) === hrefFor('community'));if (page === 'index' || page === 'guide') {assert.equal(attr(community, 'data-i18n'), page === 'index' ? 'nav-community' : 'navCommunity', page);@@ -39,11 +44,11 @@ test('all five built pages expose one shared top navigation and the correct curr});test('the homepage retains its footer catalog link alongside the top entry', () => {- const dom = parse(fs.readFileSync(new URL('../dist/index.html', import.meta.url), 'utf8'));+ const dom = parse(fs.readFileSync(new URL('index.html', output), 'utf8'));const footer = nodes(dom).find(node => node.tagName === 'footer');const base = nodes(dom).filter(node => node.tagName === 'base');assert.equal(base.length, 1);assert.equal(attr(base[0], 'href'), './');- const baseUri = new URL(attr(base[0], 'href'), 'https://tt-a1i.github.io/archify/index.html');- assert.ok(nodes(footer).some(node => node.tagName === 'a' && new URL(attr(node, 'href'), baseUri).href === 'https://tt-a1i.github.io/archify/community.html'));+ const baseUri = new URL(attr(base[0], 'href'), new URL(cloudflare ? '' : 'index.html', origin));+ assert.ok(nodes(footer).some(node => node.tagName === 'a' && new URL(attr(node, 'href'), baseUri).href === `${origin}community${extension}`));});diff --git a/website/test/publish-seo.test.mjs b/website/test/publish-seo.test.mjsindex 84e5bb71..805a2dd9 100644--- a/website/test/publish-seo.test.mjs+++ b/website/test/publish-seo.test.mjs@@ -25,7 +25,7 @@ for (const name of ['cloudflare', 'github']) test(`${name}: published discoveryconst root = fixture();try {const urls = publishSeo(root, { name });- assert.equal(urls.length, 10 + CASES.length);+ assert.equal(urls.length, sitePages.length * 2 + CASES.length);assert.equal(new Set(urls).size, urls.length);for (const page of sitePages) for (const lang of ['en', 'zh']) assert.ok(urls.includes(canonicalUrl(page, lang)));const sitemap = fs.readFileSync(path.join(root, 'sitemap.xml'), 'utf8');