affaan-m/ECC · error · Error

docs/zh-CN/README.md is missing the quick-start catalog summ

Error message

docs/zh-CN/README.md is missing the quick-start catalog summary

What it means

`parseZhDocsReadmeExpectations` reads `docs/zh-CN/README.md` and matches `/你现在可以使用\s+(\d+)\s+个智能体、\s*(\d+)\s*项技能和\s*(\d+)\s*个命令了/i`. Note this regex intentionally differs from the root README.zh-CN.md one: it requires 智能体 (not 代理), 项 (not 个) for skills, and the sentence-final 了 particle. The throw fires when this exact sentence is missing.

Source

Thrown at scripts/ci/catalog.js:157

function parseZhRootReadmeExpectations(readmeContent) {
  const match = readmeContent.match(/你现在可以使用\s+(\d+)\s+个代理、\s*(\d+)\s*个技能和\s*(\d+)\s*个命令/i);
  if (!match) {
    throw new Error('README.zh-CN.md is missing the quick-start catalog summary');
  }

  return [
    { category: 'agents', mode: 'exact', expected: Number(match[1]), source: 'README.zh-CN.md quick-start summary' },
    { category: 'skills', mode: 'exact', expected: Number(match[2]), source: 'README.zh-CN.md quick-start summary' },
    { category: 'commands', mode: 'exact', expected: Number(match[3]), source: 'README.zh-CN.md quick-start summary' }
  ];
}

function parseZhDocsReadmeExpectations(readmeContent) {
  const expectations = [];

  const quickStartMatch = readmeContent.match(/你现在可以使用\s+(\d+)\s+个智能体、\s*(\d+)\s*项技能和\s*(\d+)\s*个命令了/i);
  if (!quickStartMatch) {
    throw new Error('docs/zh-CN/README.md is missing the quick-start catalog summary');
  }

  expectations.push(
    { category: 'agents', mode: 'exact', expected: Number(quickStartMatch[1]), source: 'docs/zh-CN/README.md quick-start summary' },
    { category: 'skills', mode: 'exact', expected: Number(quickStartMatch[2]), source: 'docs/zh-CN/README.md quick-start summary' },
    { category: 'commands', mode: 'exact', expected: Number(quickStartMatch[3]), source: 'docs/zh-CN/README.md quick-start summary' }
  );

  const tablePatterns = [
    { category: 'agents', regex: /\|\s*智能体\s*\|\s*(?:(?:PASS:|\u2705)\s*)?(\d+)\s*个\s*\|/i, source: 'docs/zh-CN/README.md comparison table' },
    { category: 'commands', regex: /\|\s*命令\s*\|\s*(?:(?:PASS:|\u2705)\s*)?(\d+)\s*个\s*\|/i, source: 'docs/zh-CN/README.md comparison table' },
    { category: 'skills', regex: /\|\s*技能\s*\|\s*(?:(?:PASS:|\u2705)\s*)?(\d+)\s*项\s*\|/i, source: 'docs/zh-CN/README.md comparison table' }
  ];

  for (const pattern of tablePatterns) {
    const match = readmeContent.match(pattern.regex);
    if (!match) {
      throw new Error(`${pattern.source} is missing the ${pattern.category} row`);

View on GitHub (pinned to 01e15490f0)

Solutions

Restore the exact sentence in docs/zh-CN/README.md: `你现在可以使用 N 个智能体、 N 项技能和 N 个命令了` with current counts.
Keep the three distinguishing tokens intact: 智能体 (not 代理), 项 (not 个) for skills, and the trailing 了.
Run `node scripts/ci/catalog.js --write` to regenerate all documented counts from the catalog.
Cross-check against README.zh-CN.md to confirm the two files intentionally use different vocabulary.

Example fix

// before (docs/zh-CN/README.md, 了 dropped and 项→个)
你现在可以使用 68 个智能体、284 个技能和 94 个命令

// after
你现在可以使用 68 个智能体、284 项技能和 94 个命令了

Defensive patterns

Strategy: validation

Validate before calling

const fs = require('fs');
const readme = fs.readFileSync('docs/zh-CN/README.md', 'utf8');
const re = /你现在可以使用\s+(\d+)\s+个智能体、\s*(\d+)\s*项技能和\s*(\d+)\s*个命令了/i;
if (!re.test(readme)) {
  console.error('docs/zh-CN/README.md missing quick-start summary.');
  console.error('Expected: 你现在可以使用 N 个智能体、 N 项技能和 N 个命令了');
  console.error('Required distinguishing tokens: 智能体 (not 代理), 项 (not 个) for skills, trailing 了.');
  process.exit(1);
}

Type guard

function hasZhDocsQuickStart(readmeContent) {
  return /你现在可以使用\s+(\d+)\s+个智能体、\s*(\d+)\s*项技能和\s*(\d+)\s*个命令了/i.test(readmeContent);
}

Try / catch

try {
  runCatalogCheck();
} catch (error) {
  if (/docs\/zh-CN\/README\.md is missing the quick-start/i.test(error.message)) {
    console.error('Restore: 你现在可以使用 N 个智能体、 N 项技能和 N 个命令了');
  }
  throw error;
}

Prevention

docs/zh-CN requires 智能体/项/了 — do not normalize toward the root README.zh-CN.md wording.
Keep the trailing 了 particle; removing it breaks the regex.
Run `--write` to sync counts.
Cross-check both Chinese READMEs after translation passes.

When it happens

Trigger: Triggered when `docs/zh-CN/README.md` is missing or has altered the sentence `你现在可以使用 N 个智能体、 N 项技能和 N 个命令了`. Drift in any of the three distinguishing tokens (智能体, 项技能, 了) or the punctuation (、/和) causes a match failure.

Common situations: A copyeditor removes the 了 particle for conciseness. Someone normalizes the docs/zh-CN copy to match the root README.zh-CN.md wording (代理/个), breaking this stricter regex. The skills counter word is changed from 项 to 个. A translation refresh restructures the quick-start paragraph.

Related errors

AI-assisted analysis of affaan-m/ECC@01e15490f0 (2026-08-13). Data as JSON: /api/errors/42b1812f9d93c51e. Report an issue: GitHub.