Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

docs(website): explain a description-first workflow example

tt-a1i5fb18b054182
diff --git a/website/src/content/agent-diagrams.en.md b/website/src/content/agent-diagrams.en.md
index 9af9bf92..5e7415c1 100644
--- a/website/src/content/agent-diagrams.en.md
+++ b/website/src/content/agent-diagrams.en.md
@@ -26,6 +26,18 @@ The [installation reference](https://github.com/tt-a1i/archify/blob/main/README.
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="description-workflow" class="section-anchor" aria-hidden="true"></span>
+
+## No code repository: read a Chinese workflow diagram
+
+Without a code repository, you can start with steps, allowances, and rules. Open the existing [Chinese leave-planning workflow](cases/life/leave-plan.workflow.html) alongside its [revision-pinned JSON source](https://github.com/tt-a1i/archify/blob/68031cf978e0b906aa56c684a394049a3ea9d583/docs/cases/life/leave-plan.workflow.json). This is a walkthrough of an existing source file, not a fresh agent execution record.
+
+Read the two lanes, “休假计划” (leave plan) and “规则提醒” (rule reminders), separately. The diagram has 8 nodes and 7 relationships; its main path has only 6 nodes, from the opening allowance through four allocations to the final balance. Annual leave is allocated as 1 + 4 + 3 + 2, totaling 10 days. The spring allocation also uses 2 compensatory days, bringing the total to 12. Two branches connect expiry and approval reminders; they are not additional leave deductions.
+
+Review order, allowance, and reminders separately: follow the main path to reconcile the remaining balance, then check whether a branch merely adds a constraint. Do not count a reminder as more leave. These are illustrative rules, not real calendar or company leave-policy advice. The “9/10 consecutive days off” labels are not a real-world guarantee; dates and applicable policies need separate verification.
+
+To 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="cache-scenarios" class="section-anchor" aria-hidden="true"></span>
## Try two bounded requests: cache hit and cache miss
diff --git a/website/src/content/agent-diagrams.zh.md b/website/src/content/agent-diagrams.zh.md
index 9ff8870d..40333026 100644
--- a/website/src/content/agent-diagrams.zh.md
+++ b/website/src/content/agent-diagrams.zh.md
@@ -26,6 +26,18 @@ Archify 根据源文件生成 HTML,并执行对应的渲染与校验。你可
安装说明也不表示所有 Agent 版本组合都已验证。如果失败,先记录 Agent 及版本、操作系统和完整错误,再判断问题出在配置还是图表本身。
+<span id="description-workflow" class="section-anchor" aria-hidden="true"></span>
+
+## 不用代码仓库:读懂一张中文流程图
+
+没有代码仓库,也可以从步骤、额度和规则开始。打开现有的[中文休假流程图](cases/life/leave-plan.workflow.html),对照[固定版本的 JSON 源文件](https://github.com/tt-a1i/archify/blob/68031cf978e0b906aa56c684a394049a3ea9d583/docs/cases/life/leave-plan.workflow.json)。这是已有源文件的阅读示例,不是一次新的 Agent 执行记录。
+
+先看“休假计划”和“规则提醒”两条泳道:全图有 8 个节点、7 条关系;主路径只有 6 个节点,从年初额度经过四次安排,到全年用完。年假按 1 + 4 + 3 + 2 分配,正好 10 天;春节另用 2 天调休,合计 12 天。两条分支连接过期和审批提醒,不是再次扣减休假额度。
+
+检查时把“顺序”“额度”“提醒”分开读:先沿主路径核对剩余额度,再看分支是否只是补充约束,别把提醒算成额外休假。图中的规则都是示例,不是实际日历或公司休假政策建议;“连休 9 天/10 天”标签不是现实保证,必须另行核对日期和适用制度。
+
+想从自己的描述开始,可打开[工作流快速开始](start.html?type=workflow&input=description),只提供已确认的步骤和规则,并标出未知条件。
+
<span id="cache-scenarios" class="section-anchor" aria-hidden="true"></span>
## 第一个例子:分别画缓存命中与未命中
diff --git a/website/src/pages/agent-diagrams.astro b/website/src/pages/agent-diagrams.astro
index 6aea2356..716bacfa 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', 'cache-scenarios', 'repository-evidence', 'review-and-share', 'questions'];
+const sectionIds = ['responsibilities', 'setup', 'description-workflow', '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/test/agent-diagrams-browser.test.mjs b/website/test/agent-diagrams-browser.test.mjs
index 281deb75..6e499e43 100644
--- a/website/test/agent-diagrams-browser.test.mjs
+++ b/website/test/agent-diagrams-browser.test.mjs
@@ -117,11 +117,11 @@ 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', 'cache-example', 'review-limits']) {
+ for (const region of ['opening', 'description-workflow', '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')});
+ 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')});
return { top: start.getBoundingClientRect().top + scrollY, bottom: end.getBoundingClientRect().top + scrollY, nav: document.querySelector('.site-nav').getBoundingClientRect().bottom };
})()`);
const inset = bounds.nav + 20;
@@ -157,6 +157,24 @@ test('real Chrome: agent guide stays readable and navigable in both languages, t
assert.equal(await evaluate('location.hash'), '#cache-scenarios');
assert.equal(await evaluate('!!document.getElementById(location.hash.slice(1))'), true);
const localePosition = await assertSectionVisible();
+ await evaluate(`document.querySelector('.article-toc a[href$="#description-workflow"]').click()`);
+ await settled();
+ assert.equal(await evaluate('location.hash'), '#description-workflow');
+ const workflowPosition = 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'), '#description-workflow');
+ const workflowLocalePosition = await assertSectionVisible();
+ 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');
+ 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`);
+ assert.equal(await evaluate('!!document.querySelector("svg")'), true, 'the existing linked workflow artifact loads');
+ await navigate(urlFor('agent-diagrams', other));
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()`));
@@ -164,7 +182,7 @@ test('real Chrome: agent guide stays readable and navigable in both languages, t
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'] });
+ 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'] });
saveManifest();
}
} finally {
diff --git a/website/test/agent-diagrams.test.mjs b/website/test/agent-diagrams.test.mjs
index c0b4fc23..a9486d33 100644
--- a/website/test/agent-diagrams.test.mjs
+++ b/website/test/agent-diagrams.test.mjs
@@ -30,7 +30,7 @@ test('agent guide is readable without JavaScript, honest about examples, and lin
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}`);
+ 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}`);
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);
@@ -81,3 +81,34 @@ test('README entry points link directly to the matching language guide', () => {
}
assert.equal(fs.readFileSync(new URL('../../README.md', import.meta.url), 'utf8'), fs.readFileSync(new URL('../../README_EN.md', import.meta.url), 'utf8'));
});
+
+
+test('description workflow exposes pinned evidence, honest limits and localized setup without changing the artifact', () => {
+ 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') === '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 section = rest.slice(0, end).flatMap(nodes);
+ const visible = rest.slice(0, end).map(text).join('');
+ assert.match(visible, /1 \+ 4 \+ 3 \+ 2/);
+ assert.match(visible, lang === 'en' ? /not additional leave deductions/ : /不是再次扣减休假额度/);
+ assert.match(visible, lang === 'en' ? /not a fresh agent execution record/ : /不是一次新的 Agent 执行记录/);
+ assert.match(visible, lang === 'en' ? /not real calendar or company leave-policy advice/ : /不是实际日历或公司休假政策建议/);
+ assert.match(visible, lang === 'en' ? /not a real-world guarantee/ : /不是现实保证/);
+ const links = section.filter(node => node.tagName === 'a').map(node => new URL(attr(node, 'href'), base));
+ assert.ok(links.some(url => url.href === origin + 'cases/life/leave-plan.workflow.html'));
+ assert.ok(links.some(url => url.href === 'https://github.com/tt-a1i/archify/blob/68031cf978e0b906aa56c684a394049a3ea9d583/docs/cases/life/leave-plan.workflow.json'));
+ const quickstart = links.find(url => url.searchParams.get('type') === 'workflow');
+ assert.equal(quickstart.href, origin + `${prefix}start${cloudflare ? '' : '.html'}?type=workflow&input=description`);
+ }
+ for (const extension of ['json', 'html']) {
+ const file = `cases/life/leave-plan.workflow.${extension}`;
+ assert.deepEqual(fs.readFileSync(new URL(file, output)), fs.readFileSync(new URL(`../../docs/${file}`, import.meta.url)), 'existing artifact bytes remain unchanged');
+ }
+});