mxchen-xyz/knowledge-graph-skill-zh

Bulk Knowledge Graph Generator

📌 Version History

Version	Date	Changes
2.2.0	2026-09-02	Complete upgrade practice from large-scale projects: ① Skeleton card upgrade strategy – triggers full upgrade when users report "too many missing details/overly simple rules", dispatches sub-agents per domain in parallel + main agent monitors output (grep remaining "to-be-supplemented" count), takes over when agents stall; ② Mermaid node labels forbid nested parentheses (top cause of rendering failures) and batch regex fix script; ③ Sub-agents often make errors with cross-module relative paths (../.. levels), final check must run bidirectional-link validation; ④ Update statistics write-back and README after upgrade
2.1.0	2026-09-01	Fix Obsidian wiki link path conventions (important): Obsidian [[...]] wiki links do not support ../ relative paths (../ is treated as a note name and becomes unclickable), changed all to full paths starting from the knowledge base root (`[[domain/module/function.md
2.0.0	2026-08-24	Fix Obsidian bidirectional-link compatibility: Fifth batch QA added "no dot syntax + per-link relative path resolution validation", generated knowledge base navigates correctly in Obsidian
1.0.0	Initial version	5-batch generation strategy (L1+L2 skeleton → L3 module index → core function cards → remaining function skeletons → global QA) basic capabilities

Overview

Knowledge engineering for large-scale projects. When a project has complete code/documentation, over 50 function nodes, and requires generating a complete knowledge base of hundreds of nodes in one go, it follows a batch strategy for efficient generation, avoiding single-output overload. All file content must follow the template conventions defined in the business-knowledge-graph-generator skill (references/templates.md).

When to Use

• Large-scale projects with more than 50 functions
• Complete project code directory structure + core code file content available (can be provided in batches)
• Need to generate a complete knowledge base of hundreds of nodes in one go

Input requirements: Provide the complete project code directory structure + core code file content (can be provided in batches).

Batch Processing Strategy

When function count exceeds 50, process in the following 5 batches in order:

Batch 1: L1 + L2 Skeleton (Global Structure) – Expected output: 6~20 files

1. Generate knowledge/_index.md (L1 overview)
2. Generate <domain>/_index.md for each domain (L2 domain view)
3. Quality check: Confirm all domains and modules are covered, no omissions

Batch 2: L3 Module Index (Function List) – Expected output: 20~50 files

1. Generate <domain>/<module>/_index.md for each module (L3 module view)
2. Quality check: Confirm each module's function list is complete, all functions are named

Batch 3: High-Priority Function Cards (Core Flows) – Expected output: 20~30 files

1. Identify core functions of the system (the 20% most used by users, e.g., login, order, payment)
2. Generate complete L4 cards for these functions (including flows, rules, events, dependencies, code locations)
3. Quality check: Core flows include exception branches, code locations are accurate to line numbers

Batch 4: Remaining Function Skeleton Cards – Expected output: 50~200+ files

1. Generate minimal cards for remaining functions (at least frontmatter + function description + basic rules)
2. Mark with Status: To Be Supplemented for later manual completion
3. Quality check: All functions have corresponding .md files, no function is missed

Batch 5: Global Quality Check and Index Update

1. Verify all bidirectional links are Obsidian-compatible relative paths ([[../module/function.md|alias]]), no dot syntax like [[domain.module.function]]
2. Traverse validation: after resolving each link relative to the current file, the target .md file must exist
3. Mark all dangling links, generate a fix list
4. Update statistics (module count, function count) in each level's _index.md
5. Generate knowledge/README.md usage instructions

Priority Judgment Rules

Priority	Judgment Criteria	Example Functions
Core	>80% daily user scenarios, fund security-related	Login, Order, Payment, Refund
Important	30%~80% daily user scenarios, data management-related	Order Query, Logistics Tracking, Update Info
General	Admin backend functions, low-frequency operations, configuration	Category Management, Log Query, Report Generation

Output Requirements

1. Output by batch, report progress after each batch completes, and wait for user confirmation before proceeding to the next batch
2. When outputting each batch, list the files generated in this batch
3. After Batch 3 (core functions) completes, pause and wait for the user to specify the next priority domain
4. All file content must follow the template conventions defined in references/templates.md of business-knowledge-graph-generator

Batch Report Format

## Batch X Complete ✅

**Files Generated**: XX
**Domains Involved**: Domain A, Domain B
**File List**:

- knowledge/domain_a/_index.md
- knowledge/domain_a/module_a/_index.md
- ...

**Next Batch Plan**: Generate core function cards for domain XXX

Please confirm to continue?

Important Notes

• Batch delivery: If the project has over 100 functions, first complete L1 and L2 skeletons, then gradually drill down to L3, and finally batch generate L4
• Code reading limit: If there are too many code files, ask the user to first provide 5~10 key files of the core module, others can be described by directory structure only
• Manual supplementation: The skill generates 80% of the content (structure, flow, rule framework), but specific historical pitfalls and responsible person information need to be manually supplemented by the user

Practical Experience (2026-09-01 jetlinks project insights)

1. Obsidian links must use knowledge base root path + omit .md extension (most critical): Obsidian wiki links do not support ../ relative paths (../ is treated as note name), and do not support .md extension ([[Note.md]] is treated as a note named "Note.md" instead of "Note", making it unclickable). All links should be written uniformly as [[domain/module/function|alias]] (starting from knowledge/ root, without .md); in mermaid diagrams use plain text nodes (A[function] --> B[function]), forbid [[...]] syntax.
2. Sub-agent 429 rate-limit downgrade: During large-scale exploration/generation, sub-agents may trigger rate limiting (429), then downgrade to main session direct generation: first use Glob/Grep to locate all Controller @RequestMapping and HTTP method annotations (can be accurate to line numbers), then write file by file.
3. QA script must skip code blocks: L4 cards often include "link convention" examples in backtick code blocks; the QA regex must first exclude `...` and mermaid block content, otherwise examples will be falsely reported as dangling links.
4. Function count write-back mechanism: Module function counts in L2 index are estimates; after L3 generation, use actual counts; in Batch 5, use a script to automatically rewrite L2 statistics column and L1 size statistics.
5. Batch generation with script: For Batch 4 skeleton cards (100+ files), use a Python script to regex extract function name/type/description from L3 index table and batch write, ensuring naming and link consistency, more efficient and less error-prone than hand-writing file by file.

Practical Experience (2026-09-02 large-scale project full upgrade insights)

6. Skeleton card upgrade fully triggered, no waiting for naming: When users are dissatisfied with "to-be-supplemented / too simple rules", trigger full upgrade, upgrade all skeleton cards to full detail level (see "L4 card detail standard" in business skill).
7. Parallel sub-agents dispatched by domain + main agent monitoring: Dispatch one sub-agent per domain (prompt includes template examples, mermaid rules, code survey requirements); main agent uses grep -rl "Status: To Be Supplemented" <domain> | wc -l to periodically check remaining count; when agent stalls (no new file output for a while), directly takes over to complete, no waiting.
8. Mermaid node labels forbid nested parentheses (top cause of rendering failure): In flowchart nodes [..]/{..}, if () appears (e.g., A[Foo(x)]), it causes parse error "Expecting SQE, DOUBLECIRCLEEND..."; delete function signature parameters or separate with spaces. Batch fix: regex scan only mermaid blocks, replace [label(args)] with [label args] (remove parentheses, change comma to space).
9. Sub-agents prone to cross-module relative path errors: Sub-agents often miscalculate ../.. levels when writing cross-module links (e.g., transaction_management/transaction_log/ pointing to market_data/portfolio_management/ should be ../../market_data/portfolio_management/_index.md instead of ../portfolio_management/); final check must run bidirectional-link validation script and list broken links for repair.
10. Final three-in-one check: After upgrade completes, run ① bidirectional-link integrity script (traverse all .md files, parse [[...]] relative paths, validate target existence) ② mermaid parentheses scan ③ residual "to-be-supplemented" count (grep -rl "Status: To Be Supplemented" | wc -l should be 0); update README statistics and deliver.

Batch Skeleton Card Upgrade Operation Guide

When knowledge/ already has a large number of skeleton cards needing upgrade:

1. Count remaining: grep -rl "Status: To Be Supplemented" knowledge/*/ | wc -l   (break down by domain)
2. Parallel dispatch sub-agents by domain (each prompt must include: absolute path to template examples, mermaid rules,
   code survey requirement "at least 1-2 real function names + line numbers, mark as to-be-located if not found, never fabricate", output report format)
3. Main agent periodic check: find recently modified files / grep remaining "to-be-supplemented" count; take over if stalled
4. Final check: bidirectional-link validation script + mermaid parentheses scan + "to-be-supplemented" count to zero
5. Update README statistics and each level _index statistics

Resources

• business-knowledge-graph-generator/references/templates.md: L1~L4 template conventions (must follow)