Skip to content

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

Guide explainer prose toward plain Chinese and English

tt-a1i169292cd4b2e
diff --git a/archify/explainer/writing.mjs b/archify/explainer/writing.mjs
index 6f26cbf6..fed1ebdc 100644
--- a/archify/explainer/writing.mjs
+++ b/archify/explainer/writing.mjs
@@ -5,12 +5,18 @@
const RULES = [
{id:'qualification', pattern:/示例|本例|不代表|未实测|仅供参考|\billustrative\b|\bnot measured\b/giu,
reason:'把限定条件写进 scope 或来源', example:'@answer scope="适用于当前请求路径"', fix:'把限定条件写进 scope 或来源,正文直接解释判断和原因。'},
- {id: 'light-verb', pattern: /进行(?:分析|检查|确认)|\b(?:perform an analysis of|carry out an investigation of)\b/giu,
- reason: 'A light-verb construction can obscure the action.', example: '进行检查 → 检查; perform an analysis of → analyze', fix: 'Use the direct action verb where it preserves the meaning; name who performs the action.'},
- {id: 'cliche', pattern: /赋能业务|全方位提升|\b(?:at the end of the day|in today[’']s fast-paced world|unlock the full potential)\b/giu,
- reason: 'This stock phrase gives little information about the concrete outcome.', example: '赋能业务 → 让客服查到订单状态; unlock the full potential → state the specific outcome', fix: 'Replace the stock phrase with the specific action or outcome the reader needs.'},
- {id: 'vague-quantity', pattern: /大量(?:请求|用户|数据)|很多(?:请求|用户|数据)|\b(?:many users|a large number of requests|significantly faster)\b/giu,
- reason: 'The quantity or comparison lacks a stated bound or measurement.', example: '大量请求 → 写明已知请求量或说明未测量; significantly faster → give the measured comparison or say it is unmeasured', fix: 'Add a supported quantity, range or comparison basis; when unknown, state that it is unmeasured. Do not invent a number.'},
+ {id: 'light-verb', pattern: /进行(?![中时])\p{Script=Han}{2}|(?:加以|予以|做出|作出)\p{Script=Han}{2}|\b(?:perform an analysis of|carry out an investigation of|make a decision|give consideration to|conduct an? (?:review|investigation|analysis) of)\b/giu,
+ reason: 'A light-verb construction can obscure the action.', example: '进行检查 → 检查;做出决定 → 决定; make a decision → decide', fix: 'Use the direct action verb where it preserves the meaning; name who performs the action.'},
+ {id: 'cliche', pattern: /赋能|抓手|全方位|多维度|深度融合|至关重要|不可或缺|一站式|底层逻辑|\b(?:at the end of the day|in today[’']s fast-paced world|unlock the full potential|game[- ]changer|cutting[- ]edge|seamless(?:ly)?|delve into)\b/giu,
+ reason: 'This stock phrase gives little information about the concrete outcome.', example: '赋能业务 → 让客服查到订单状态; seamless → name what no longer needs a manual step', fix: 'Replace the stock phrase with the specific action or outcome the reader needs.'},
+ {id: 'filler', pattern: /下面我(?:来|将)|接下来我(?:来|将)|让我(?:们)?来|总的来说|综上所述|总而言之|值得注意的是|众所周知|毋庸置疑|希望(?:这)?(?:对你|对您)有(?:所)?帮助|如有疑问|\b(?:here is an overview|let[’']s (?:dive|take a look)|in conclusion|in summary|it is worth noting that|as we all know|i hope this helps)\b/giu,
+ reason: 'Opening, closing or signposting filler delays the facts.', example: '综上所述,选 A → 选 A; In summary, use A → Use A', fix: 'Delete the phrase and start with the fact; the page ends when the facts end.'},
+ {id: 'vague-quantity', pattern: /大量(?:请求|用户|数据)|很多(?:请求|用户|数据)|若干|尽快|\b(?:many users|a large number of requests|significantly faster|as soon as possible)\b/giu,
+ reason: 'The quantity or comparison lacks a stated bound or measurement.', example: '大量请求 → 写明已知请求量或说明未测量;尽快 → 写明期限; significantly faster → give the measured comparison or say it is unmeasured', fix: 'Add a supported quantity, range, deadline or comparison basis; when unknown, state that it is unmeasured. Do not invent a number.'},
+ {id: 'number-boundary', pattern: /(?<=\d\s*(?:个|次|秒|天|分钟|小时|倍|人|条|项|%|ms|MB|GB|KB|QPS)?\s*)(?:以上|以下|以内)/gu,
+ reason: '“以上/以下/以内” after a number leaves the endpoint unclear.', example: '3 次以上 → 超过 3 次 / 不少于 3 次;1 秒以内 → 不超过 1 秒', fix: 'Say whether the endpoint is included: 超过/不少于, 低于/不超过.'},
+ {id: 'plain-word', pattern: /\b(?:utili[sz]e[sd]?|utili[sz]ation|prior to|in order to|commence[sd]?|facilitate[sd]?|subsequently|in the event that|due to the fact that|at this point in time|endeavou?r)\b/giu,
+ reason: 'A longer word replaces a common one with the same meaning.', example: 'utilize → use; prior to → before; in order to → to; due to the fact that → because', fix: 'Use the shorter common word.'},
{id: 'redundancy', pattern: /提前预先|重复重复|基本基础|\b(?:each and every|future plans|completely eliminate)\b/giu,
reason: 'Adjacent wording may repeat the same meaning.', example: '提前预先 → 提前; each and every → each', fix: 'Keep one expression of the meaning unless both terms carry a necessary distinction.'},
];
@@ -56,12 +62,12 @@ function sentences(text) {
* @param {{mode?:'warn'|'strict'|'off',locale?:string,sentenceLimits?:{zh?:number,en?:number}}} options
* @returns {Array<object>} Existing Archify diagnostics (warning by default).
* Length is Han characters plus English words/numeric tokens; punctuation is excluded.
- * A sentence containing Han uses zh limit (70), otherwise en limit (35).
+ * A sentence containing Han uses zh limit (50), otherwise en limit (28).
*/
export function lintExplainerWriting(entries, {mode = 'warn', locale = 'auto', sentenceLimits = {}} = {}) {
if (!['warn', 'strict', 'off'].includes(mode)) throw new TypeError('Writing mode must be warn, strict or off');
if (mode === 'off') return [];
- const limits = {zh: 70, en: 35, ...sentenceLimits};
+ const limits = {zh: 50, en: 28, ...sentenceLimits};
for (const value of Object.values(limits)) {
if (!Number.isSafeInteger(value) || value < 1) throw new TypeError('Sentence limits must be positive integers');
}
@@ -104,6 +110,11 @@ export function lintExplainerWriting(entries, {mode = 'warn', locale = 'auto', s
const units = han + words;
const language = han ? 'zh' : (words ? 'en' : (locale.startsWith('zh') ? 'zh' : 'en'));
const limit = limits[language];
+ const particles = sentence.text.replace(/目的|的确|的话/gu, '').match(/的/gu)?.length || 0;
+ if (particles >= 3) found.push({offset: sentence.offset + Math.max(0, sentence.text.search(/\S/u)), rule: 'de-chain',
+ reason: `This sentence chains ${particles} “的” modifiers, so the head noun arrives late.`,
+ example: '负责处理用户提交的订单的服务的日志 → 订单服务的日志。它记录用户提交的订单。',
+ fix: 'Split the sentence or move a modifier into its own clause.', matched: sentence.text.trim()});
if (units > limit) {
const leading = sentence.text.search(/\S/u);
found.push({offset: sentence.offset + Math.max(0, leading), rule: 'sentence-length',
diff --git a/archify/references/explainer-authoring.md b/archify/references/explainer-authoring.md
index 96bc6252..0ad8fa94 100644
--- a/archify/references/explainer-authoring.md
+++ b/archify/references/explainer-authoring.md
@@ -80,6 +80,20 @@ A diagram replaces the paragraph that would describe it. When the answer involve
A small answer gets a small page: the conclusion plus one or two panels.
+## Writing
+
+Every sentence gives the reader one fact they need. Write in the user's language.
+
+- Start with the fact. The title asks the question, the conclusion answers it, and the page ends when the facts end.
+- One sentence carries one fact; one panel answers one question. Say each fact once: when a table or diagram shows it, the text adds only what the figure cannot.
+- Call each thing by one name throughout the page, and use the name the reader already knows.
+- Give results with their evidence: a number with its unit, a file position, a source. When a value is unknown or estimated, say so in scope.
+- Write steps as commands with the condition first: “If the build fails, read the log.”
+
+English: short sentences (under about 25 words), common words (use, before, to, because), active voice with a named actor.
+
+中文:短句,每句不超过约 50 字;动词直接用(检查、决定,而不是进行检查、做出决定);一句话里的“的”不超过两个;数字后写清边界(超过 3 次、不超过 1 秒);用具体结果代替套话(赋能、全方位、至关重要)。
+
## Compact native diagrams
Write `@<type> id=<diagram-id> title="..."` followed by pipe rows. Each compiles to a full native Archify diagram, with native validation and layout, and opens in the full Viewer from the page. A document holds up to four native diagrams.
@@ -217,7 +231,7 @@ node archify/bin/archify.mjs finalize explainer candidate.archify.md answer.html
Add `--repo-root <path>` when the draft uses `@code`. Finalize validates, atomically delivers and checks the HTML; it does not launch a browser, and its receipt records the browser gate as not run. A failure names the line, component, reason and a repair example; fix the draft and rerun to the same output path.
-Writing warnings flag qualifiers such as “示例”, “本例”, “不代表”, “未实测”, “仅供参考”, “illustrative” and “not measured” in the conclusion, reasons and body; move them into scope or sources. They also flag a paragraph longer than four sentences or 120 reading units (turn it into a list, steps or a table), a conclusion that is mostly bold (bold only the decisive words) and a scope longer than 50 reading units (short labels separated by “·”). `--writing warn|strict|off` sets the severity.
+Writing warnings apply the [Writing](#writing) rules: sentences over 50 Chinese units or 28 English words, paragraphs over four sentences or 120 units, chained “的”, light verbs, stock phrases and filler, unbounded quantities, “以上/以下/以内” after a number, long English words with a common equivalent, qualifiers such as “示例”, “未实测” or “illustrative” outside scope, a mostly bold conclusion and a scope over 50 units. Each warning names the matched text and a repair; fix it when the repair keeps the meaning. `--writing warn|strict|off` sets the severity.
## Panel replacement
diff --git a/test/explainer-writing.test.mjs b/test/explainer-writing.test.mjs
index 016a90e5..5971bb93 100644
--- a/test/explainer-writing.test.mjs
+++ b/test/explainer-writing.test.mjs
@@ -93,3 +93,13 @@ test('writing: long paragraphs, an all-bold conclusion and a disclaimer-style sc
assert.deepEqual(rules([entry('本页讨论功能方向,尚未实现。依据用户陈述,本次没有核对历史记录。页面只是阅读体验样例,不构成任何法律审查意见,也没有经过实际运行验证。', {component: 'scope'})]), ['scope-length']);
assert.deepEqual(rules([entry('示例 · 8 人团队', {component: 'scope'})]), []);
});
+
+test('writing: Chinese and English controlled-language hints stay precise', () => {
+ const rules = text => lintExplainerWriting([entry(text)]).map(item => item.evidence.rule);
+ assert.deepEqual(rules('综上所述,先做出决定再加以验证。'), ['filler', 'light-verb', 'light-verb']);
+ assert.deepEqual(rules('重试 3 次以上会放大延迟。'), ['number-boundary']);
+ assert.deepEqual(rules('负责处理用户提交的订单的服务的日志很大。'), ['de-chain']);
+ assert.deepEqual(rules('In order to utilize the cache, read it first.'), ['plain-word', 'plain-word']);
+ assert.deepEqual(rules('In summary, this cutting-edge design is seamless.'), ['filler', 'cliche', 'cliche']);
+ assert.deepEqual(lintExplainerWriting(['任务进行中。', '目的的确清楚。', '重试超过 3 次。', '服务以下游为准。', 'Use the cache before the database.'].map(text => entry(text))), []);
+});