affaan-m/ECC · error · Error

docs/zh-CN/AGENTS.md is missing the catalog summary line

Error message

docs/zh-CN/AGENTS.md is missing the catalog summary line

What it means

`parseZhAgentsDocExpectations` reads `docs/zh-CN/AGENTS.md` and matches the Chinese summary `/提供\s+(\d+)\s+个专业代理、\s*(\d+)(\+)?\s*项技能、\s+(\d+)\s+条命令/i`. Expected form: `提供 N 个专业代理、 N(+) 项技能、 N 条命令`. The optional `+` after skills marks a minimum expectation. The throw fires when this sentence is absent or its wording drifted.

Source

Thrown at scripts/ci/catalog.js:279

    if (!match) {
      throw new Error(`${pattern.source} is missing the ${pattern.category} entry`);
    }

    expectations.push({
      category: pattern.category,
      mode: pattern.mode === 'minimum' && match[2] ? 'minimum' : pattern.mode,
      expected: Number(match[1]),
      source: `${pattern.source} (${pattern.category})`
    });
  }

  return expectations;
}

function parseZhAgentsDocExpectations(agentsContent) {
  const summaryMatch = agentsContent.match(/提供\s+(\d+)\s+个专业代理、\s*(\d+)(\+)?\s*项技能、\s*(\d+)\s+条命令/i);
  if (!summaryMatch) {
    throw new Error('docs/zh-CN/AGENTS.md is missing the catalog summary line');
  }

  const expectations = [
    { category: 'agents', mode: 'exact', expected: Number(summaryMatch[1]), source: 'docs/zh-CN/AGENTS.md summary' },
    {
      category: 'skills',
      mode: summaryMatch[3] ? 'minimum' : 'exact',
      expected: Number(summaryMatch[2]),
      source: 'docs/zh-CN/AGENTS.md summary'
    },
    { category: 'commands', mode: 'exact', expected: Number(summaryMatch[4]), source: 'docs/zh-CN/AGENTS.md summary' }
  ];

  const structurePatterns = [
    {
      category: 'agents',
      mode: 'exact',
      regex: /^\s*agents\/\s*[—–-]\s*(\d+)\s+个专业子代理\s*$/im,

View on GitHub (pinned to 01e15490f0)

Solutions

Restore the exact sentence in docs/zh-CN/AGENTS.md: `提供 68 个专业代理、284+ 项技能、94 条命令` (with `+` only if skills is a floor).
Preserve the three distinct counters: 个 (agents), 项 (skills), 条 (commands), and the ideographic comma 、.
Run `node scripts/ci/catalog.js --write` to auto-sync counts; syncZhAgents rewrites only digits.
Confirm the skills mode (exact vs minimum) matches the English AGENTS.md.

Example fix

// before (docs/zh-CN/AGENTS.md, 条→个)
提供 68 个专业代理、284+ 项技能、94 个命令

// after
提供 68 个专业代理、284+ 项技能、94 条命令

Defensive patterns

Strategy: validation

Validate before calling

const fs = require('fs');
const agents = fs.readFileSync('docs/zh-CN/AGENTS.md', 'utf8');
const re = /提供\s+(\d+)\s+个专业代理、\s*(\d+)(\+)?\s*项技能、\s+(\d+)\s+条命令/i;
if (!re.test(agents)) {
  console.error('docs/zh-CN/AGENTS.md missing summary line.');
  console.error('Expected: 提供 N 个专业代理、 N(+) 项技能、 N 条命令 (counters 个/项/条).');
  process.exit(1);
}

Type guard

function hasZhAgentsSummary(agentsContent) {
  return /提供\s+(\d+)\s+个专业代理、\s*(\d+)(\+)?\s*项技能、\s+(\d+)\s+条命令/i.test(agentsContent);
}

Try / catch

try {
  runCatalogCheck();
} catch (error) {
  if (/docs\/zh-CN\/AGENTS\.md is missing the catalog summary/i.test(error.message)) {
    console.error('Restore: 提供 N 个专业代理、 N(+) 项技能、 N 条命令');
  }
  throw error;
}

Prevention

Preserve the three counters: 个 (agents), 项 (skills), 条 (commands).
Keep the ideographic comma 、 and the verb 提供.
Run `--write` to sync counts.
Validate after any Chinese AGENTS.md rewrite.

When it happens

Trigger: Triggered by the catalog check when `docs/zh-CN/AGENTS.md` lacks the exact `提供 ... 个专业代理、 ... 项技能、 ... 条命令` sentence. Drift in counters (个/项/条), conjunctions (、), or the leading 提供 verb causes a match failure.

Common situations: A translator changes 条命令 → 个命令 for consistency, or 项技能 → 个技能, breaking the counter-specific regex. The `提供` verb is swapped for another. The `+` floor marker is removed.

Related errors

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