Back to Details

nium-wiki

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Nium Wiki Generator

Nium Wiki Generator

Produce professional-grade, domain-organized project Wiki under the 
.nium-wiki/
directory.
Core Principle: Generated documentation must be detailed, structured, diagrammed, and cross-linked, meeting enterprise-level technical documentation standards.
在
.nium-wiki/
目录下生成专业级、按领域划分的项目Wiki文档。
核心原则：生成的文档必须详细、结构化、配有图表且具备交叉链接，符合企业级技术文档标准。

Quality Gate for Generated Documentation

生成文档的质量门槛

MANDATORY: Every piece of generated documentation MUST satisfy the following criteria:
强制要求：所有生成的文档必须满足以下标准：

Depth of Coverage

覆盖深度

  • Provide full context for every topic — never leave bare lists or placeholder outlines
  • Write specific, explanatory descriptions that address the WHY and HOW behind each concept
  • Supply runnable code examples paired with their expected output (🔴 secrets must be sanitized - see "Secret & Credential Sanitization")
  • Call out edge cases, caveats, and common mistakes explicitly
Substantive content: A section has real content if it contains ≥ 3 non-empty, non-heading lines, OR at least one code block, diagram, or table. A heading followed by a single sentence or a bare list does not count.
  • 为每个主题提供完整上下文——绝不留下空列表或占位符大纲
  • 撰写具体、具备解释性的描述，阐明每个概念背后的原因与实现方式
  • 提供可运行的代码示例及预期输出（🔴 必须清理敏感信息 - 参见「机密信息与凭证脱敏」）
  • 明确标注边缘情况、注意事项及常见错误
实质性内容定义：若某章节包含≥3条非空、非标题的内容，或至少一个代码块、图表、表格，则视为具备真实内容。仅标题加单句或空列表不满足要求。

Structural Conventions

结构规范

  • Organize content with hierarchical headings (H2 → H3 → H4) to form a clear information hierarchy
  • Summarize key concepts in tables for scanability
  • Illustrate processes and flows using Mermaid diagrams
  • Interconnect documents via cross-links
  • 使用层级标题（H2 → H3 → H4）组织内容，形成清晰的信息层级
  • 将关键概念汇总为表格，提升可读性
  • 使用Mermaid图表展示流程与逻辑
  • 通过交叉链接实现文档间的互联互通

🔴 MANDATORY: Link Path Format

🔴 强制要求：链接路径格式

ALL source file links MUST use project-root-relative POSIX paths starting with 
/
. NEVER use 
file://
URIs, absolute filesystem paths, or OS-specific paths. The IDE/editor may provide file paths as 
file:///Users/.../project/src/foo.ts
— you MUST strip the prefix and convert to 
/src/foo.ts
.
❌ Wrong✅ CorrectReason
[foo.ts](file:///Users/x/project/src/foo.ts#L1-L50)
[foo.ts](/src/foo.ts#L1-L50)
Strip 
file://
prefix + absolute path
[foo.ts](src/foo.ts#L1-L50)
[foo.ts](/src/foo.ts#L1-L50)
Must start with 
/
[foo.ts](C:\Users\x\project\src\foo.ts)
[foo.ts](/src/foo.ts)
No Windows paths
Conversion rule: Given any absolute path, remove everything up to and including the project root directory name, then prepend 
/
. Example: 
file:///home/user/my-project/src/core/foo.ts
→ 
/src/core/foo.ts
.
所有源文件链接必须使用以
/
开头的、相对于项目根目录的POSIX路径。 禁止使用
file://
URI、绝对文件系统路径或特定操作系统路径。 若IDE/编辑器提供的文件路径为
file:///Users/.../project/src/foo.ts
，必须移除前缀并转换为
/src/foo.ts
。
❌ 错误格式✅ 正确格式原因
[foo.ts](file:///Users/x/project/src/foo.ts#L1-L50)
[foo.ts](/src/foo.ts#L1-L50)
移除
file://
前缀及绝对路径部分
[foo.ts](src/foo.ts#L1-L50)
[foo.ts](/src/foo.ts#L1-L50)
必须以
/
开头
[foo.ts](C:\Users\x\project\src\foo.ts)
[foo.ts](/src/foo.ts)
禁止使用Windows路径
转换规则：对于任意绝对路径，移除项目根目录名称及之前的所有内容，然后添加前缀
/
。示例：
file:///home/user/my-project/src/core/foo.ts
→ 
/src/core/foo.ts
。

🔴 MANDATORY: Secret & Credential Sanitization

🔴 强制要求：机密信息与凭证脱敏

CRITICAL: NEVER include actual secrets, credentials, API keys, or sensitive information in generated documentation.
MANDATORY sanitization rules:
ScenarioActionExample
Hard-coded API keys in sourceReplace with placeholders
sk_live_abc123
→ 
sk_live_XXXXXXXXXXXX
Database credentialsRedact or use example values
password: "mysecret123"
→ 
password: "***REDACTED***"
Private tokens/keysMask with descriptive placeholders
TOKEN=secret123
→ 
TOKEN=<your-api-token-here>
Environment vars with secretsShow safe example values
AWS_SECRET_ACCESS_KEY=xyz
→ 
AWS_SECRET_ACCESS_KEY=<your-secret-key>
Sanitization pattern library:
  • API keys: 
    sk_live_XXXXXXXX
    , 
    pk_test_XXXXXXXX
    , 
    api_key_XXXXXXXX
  • Passwords: 
    ***REDACTED***
    , 
    <your-password-here>
  • Tokens: 
    <your-access-token>
    , 
    <auth-token-here>
  • Generic: 
    XXXXXXXX
    , 
    <secret-value>
    , 
    <sensitive-data>
Exception: Mermaid diagrams, source file path links, and markdown structure MUST still be preserved unchanged (except for secret removal within code blocks).
关键要求：绝不在生成的文档中包含真实的机密信息、凭证、API密钥或敏感数据。
强制脱敏规则：
场景操作示例
源代码中硬编码的API密钥替换为占位符
sk_live_abc123
→ 
sk_live_XXXXXXXXXXXX
数据库凭证隐藏或使用示例值
password: "mysecret123"
→ 
password: "***REDACTED***"
私有令牌/密钥使用描述性占位符掩码
TOKEN=secret123
→ 
TOKEN=<your-api-token-here>
包含机密信息的环境变量展示安全示例值
AWS_SECRET_ACCESS_KEY=xyz
→ 
AWS_SECRET_ACCESS_KEY=<your-secret-key>
脱敏模板库：
  • API密钥：
    sk_live_XXXXXXXX
    , 
    pk_test_XXXXXXXX
    , 
    api_key_XXXXXXXX
  • 密码：
    ***REDACTED***
    , 
    <your-password-here>
  • 令牌：
    <your-access-token>
    , 
    <auth-token-here>
  • 通用占位符：
    XXXXXXXX
    , 
    <secret-value>
    , 
    <sensitive-data>
例外情况：Mermaid图表、源文件路径链接及Markdown结构必须保持不变（代码块中的机密信息除外，需移除）。

Diagram Requirements (at least 2-3 per document)

图表要求（每份文档至少2-3个）

Content TypeDiagram TypeCondition
System architecture
flowchart TB
with subgraphs		always
Request / data flow
sequenceDiagram
always
Lifecycle / state transitions
stateDiagram-v2
only for stateful modules
Class / Interface shape
flowchart LR
showing type/module relationships		only when source is read
Module dependencies
flowchart LR
always
Data models / ORM
erDiagram
when project has database/ORM
Module conceptual relationships
mindmap
optional, for abstract module relationships only (NOT file trees)
Diagram diversity: Count ≥ 2 distinct diagram types toward the minimum. Three identical flowcharts do not satisfy the requirement — use 
flowchart LR
, 
sequenceDiagram
, 
stateDiagram-v2
, 
erDiagram
as appropriate for the module.
Note: 
mindmap
is optional and does not count toward the ≥ 2 distinct types requirement. It may supplement but never replace the required diagram types above.
Layout rules: Choose direction by content — 
TB
for hierarchies, 
LR
for flows/dependencies. Use 
subgraph
to group related nodes when count > 6. Apply 
style
color coding to highlight key nodes.
File/directory structure MUST use plain-text tree format (
├──
└──
), NEVER use Mermaid diagrams (including 
mindmap
). Mermaid 
mindmap
is only for showing abstract conceptual relationships between modules, never for file paths or directory trees.
内容类型图表类型适用条件
系统架构带子图的
flowchart TB
始终适用
请求/数据流
sequenceDiagram
始终适用
生命周期/状态转换
stateDiagram-v2
仅适用于有状态模块
类/接口结构展示类型/模块关系的
flowchart LR
仅在读取源代码时使用
模块依赖
flowchart LR
始终适用
数据模型/ORM
erDiagram
当项目包含数据库/ORM时适用
模块概念关系
mindmap
可选，仅用于展示抽象模块关系（不用于文件树）
图表多样性要求：至少需要2种不同类型的图表满足最低要求。三个相同的流程图不符合要求——需根据模块情况选择
flowchart LR
、
sequenceDiagram
、
stateDiagram-v2
、
erDiagram
等合适的类型。
注意：
mindmap
为可选图表，不计算在≥2种不同类型的要求内。它可作为补充，但绝不能替代上述必填图表类型。
布局规则：根据内容选择方向——
TB
用于层级结构，
LR
用于流程/依赖关系。当节点数量>6时，使用
subgraph
对相关节点进行分组。使用
style
颜色编码突出关键节点。
文件/目录结构必须使用纯文本树形格式（
├──
└──
），禁止使用Mermaid图表（包括
mindmap
）。 Mermaid 
mindmap
仅用于展示模块间的抽象概念关系，绝不用于文件路径或目录树。

🔴 Mermaid Syntax Safety Rules (MANDATORY — Read Before Every Diagram)

🔴 Mermaid语法安全规则（强制要求——生成图表前必读）

⚠️ HARD REQUIREMENT: Before generating ANY Mermaid diagram, you MUST read refs/mermaid-syntax.md in full. Generating without reading this file is a hard requirement violation.
✅ Hard Rules — parser errors (must fix). ⚠️ Suggestions — best practices.
CategoryRuleWrong ❌Correct ✅
✅subgraph ID must not collide with node ID
subgraph CLI[...]\nCLI[...]
subgraph CL[...]\nCLI[...]
✅Unescaped quotes in plain labels
A[Config "x" val]
A[Config &quot;x&quot; val]
or 
A["Config \"x\" val"]
✅Reserved keywords as IDs
class[class]
NodeClass[class]
(keywords: 
class
, 
graph
, 
digraph
, 
subgraph
, 
end
, 
click
, 
style
, 
state
, 
note
)
⚠️Plain labels preferred for simple text
A["Label"]
A[Label]
⚠️Alphanumeric IDs preferred
Core.1[Core]
Core_1[Core]
⚠️English subgraph IDs preferred
subgraph 核心层[...]
subgraph Core[...]
Complexity grouping (when nodes > 6):
Node CountStrategy
≤ 6Linear — no grouping needed
7-12
subgraph
grouping, 2-4 nodes per group
13-20Layered abstraction (overview + detail)
> 20Split into multiple diagrams
Example — Grouped vs waterfall:
mermaid
%% WRONG — narrow waterfall
flowchart TD
    A --> B --> C --> D --> E --> F --> G --> H
%% CORRECT — grouped by phase
flowchart TD
    subgraph Phase1[Phase 1]
        A --> B
    end
    subgraph Phase2[Phase 2]
        C --> D --> E
    end
    Phase1 --> Phase2
⚠️ 硬性要求：在生成任何Mermaid图表之前，必须完整阅读refs/mermaid-syntax.md。未阅读此文件即生成图表属于严重违规。
✅ 硬性规则——解析错误（必须修复）。⚠️ 建议——最佳实践。
类别规则错误示例 ❌正确示例 ✅
✅子图ID不能与节点ID冲突
subgraph CLI[...]\nCLI[...]
subgraph CL[...]\nCLI[...]
✅纯文本标签中的引号必须转义
A[Config "x" val]
A[Config &quot;x&quot; val]
或 
A["Config \"x\" val"]
✅保留关键字不能作为ID
class[class]
NodeClass[class]
（关键字包括：
class
、
graph
、
digraph
、
subgraph
、
end
、
click
、
style
、
state
、
note
）
⚠️简单文本优先使用纯标签
A["Label"]
A[Label]
⚠️优先使用字母数字ID
Core.1[Core]
Core_1[Core]
⚠️子图ID优先使用英文
subgraph 核心层[...]
subgraph Core[...]
复杂度分组策略（节点数>6时）：
节点数量策略
≤ 6线性排列——无需分组
7-12使用
subgraph
分组，每组2-4个节点
13-20分层抽象（概览+细节）
> 20拆分为多个图表
示例——分组式 vs 瀑布式：
mermaid
%% WRONG — 狭窄瀑布式
flowchart TD
    A --> B --> C --> D --> E --> F --> G --> H
%% CORRECT — 按阶段分组
flowchart TD
    subgraph Phase1[Phase 1]
        A --> B
    end
    subgraph Phase2[Phase 2]
        C --> D --> E
    end
    Phase1 --> Phase2

🔴 MANDATORY: Source File Back-References

🔴 强制要求：源文件反向引用

Each section MUST end with links back to the originating source files (see "Link Path Format" above for path rules):
markdown
**Source references**
- [cli.ts](/src/cli.ts#L1-L50)
- [index.ts](/src/index.ts#L20-L80)

**Diagram data sources**
- [core/analyzeProject.ts](/src/core/analyzeProject.ts#L1-L100)
每个章节末尾必须添加指向原始源文件的链接（路径规则参见「链接路径格式」）：
markdown
**源文件参考**
- [cli.ts](/src/cli.ts#L1-L50)
- [index.ts](/src/index.ts#L20-L80)

**图表数据源**
- [core/analyzeProject.ts](/src/core/analyzeProject.ts#L1-L100)

🔴 MANDATORY: Source Attribution for Code Block Excerpts

🔴 强制要求：代码块摘录的源文件归属标注

Any code block that is a direct excerpt from a source file (function body, class definition, type definition, import/export statement) MUST carry a source attribution line immediately above the code block. This applies to 
.ts
, 
.js
, 
.py
, 
.go
, 
.rs
, 
.java
, and other language source files.
⚠️ CRITICAL: The attribution line MUST be placed outside the code fence (above the opening ```), using plain text format without any language-specific comment syntax (no 
//
, 
#
, 
/* */
, etc.). The attribution line is plain text, and the Markdown link inside it will be rendered as a clickable link.
✅ CORRECT format:
markdown
[Source: cli.ts](/src/cli.ts#L42-L67)
```typescript
const result = cli.parse(process.argv);

**❌ WRONG formats (links will NOT be clickable)**:

```markdown
// Wrong: Inside the code block as a comment — the link won't work
```typescript
// Source: [cli.ts](/src/cli.ts#L42-L67)
const result = cli.parse(process.argv);
markdown
// Wrong: Uses comment syntax (//, #, etc.) — renders as code, not text
// [Source: cli.ts](/src/cli.ts#L42-L67)
```typescript
const result = cli.parse(process.argv);

Attribution is **not required** for:

| Content type | Example | Why no attribution |
|---|---|---|
| Usage / call-site examples | `cli.run(['--help'])` | Calling code, not source excerpt |
| Teaching / invented examples | Any code that does not exist in the source | Not in any source file |
| Mermaid / shell / CLI commands | `flowchart TD\n  A --> B` | Not source code |
| Output / runtime results | `// Output: { id: 1 }` | Results, not source |
任何直接从源文件摘录的代码块（函数体、类定义、类型定义、导入/导出语句）必须在代码块上方立即添加源文件归属标注行。此规则适用于
.ts
、
.js
、
.py
、
.go
、
.rs
、
.java
等各类语言的源文件。
⚠️ 关键要求：归属标注行必须放在代码围栏外部（在开头```上方），使用纯文本格式禁止使用任何语言特定的注释语法（如
//
、
#
、
/* */
等）。归属标注行是纯文本，其中的Markdown链接会被渲染为可点击的链接。
✅ 正确格式：
markdown
[Source: cli.ts](/src/cli.ts#L42-L67)
```typescript
const result = cli.parse(process.argv);

**❌ 错误格式（链接无法点击）**：

```markdown
// 错误：放在代码块内作为注释——链接无法生效
```typescript
// Source: [cli.ts](/src/cli.ts#L42-L67)
const result = cli.parse(process.argv);
markdown
// 错误：使用注释语法（//、#等）——会被渲染为代码而非文本
// [Source: cli.ts](/src/cli.ts#L42-L67)
```typescript
const result = cli.parse(process.argv);

以下内容无需添加归属标注：

| 内容类型 | 示例 | 无需标注原因 |
|---|---|---|
| 使用/调用示例 | `cli.run(['--help'])` | 调用代码，而非源文件摘录 |
| 教学/虚构示例 | 任何不存在于源文件中的代码 | 不属于任何源文件 |
| Mermaid/Shell/CLI命令 | `flowchart TD\n  A --> B` | 不属于源代码 |
| 输出/运行结果 | `// Output: { id: 1 }` | 运行结果，而非源代码 |

🔴 MANDATORY: Complexity-Scaled Quality Targets

🔴 强制要求：按复杂度分级的质量目标

Quality standards scale with module complexity — not fixed numbers.
Module RoleDoc DepthCode ExamplesDiagrams
coreComprehensive (use 
module.md
)		5+2+
util / configConcise (use 
module-simple.md
)		1-21
test / exampleMinimal (use 
module-simple.md
)		1optional
General rules: larger source files → longer docs; more exports → more examples; more dependents → more diagrams.
In incremental mode, these targets are overridden — see Mode Overrides.
质量标准随模块复杂度调整——而非固定数值。
模块角色文档深度代码示例数量图表数量
core（核心模块）全面（使用
module.md
模板）		5+2+
util / config（工具/配置模块）简洁（使用
module-simple.md
模板）		1-21
test / example（测试/示例模块）极简（使用
module-simple.md
模板）		1可选
通用规则：源文件越大→文档越长；导出内容越多→示例越多；依赖模块越多→图表越多。
在增量模式下，这些目标会被覆盖——参见「模式覆盖」。

Module Document Sections

模块文档章节

Use 
module.md
(11 sections) for core modules, 
module-simple.md
(6 sections) for util/config/helper modules.
Full template (
module.md
) — for core modules:
#SectionContentLines TargetDiagram
1OverviewIntro + value proposition + architecture role2-3 paragraphs—
2Architecture PositionMermaid diagram highlighting module position—flowchart TB
3Feature TableFeatures with related APIsN features—
4File StructureFile tree + responsibilitiestree—
5Core WorkflowMermaid flowchart—sequenceDiagram
6State Diagram⚡ OPTIONAL — only for stateful modulesOPTIONALstateDiagram-v2
7API SummaryOverview table + link to api.md (no detailed signatures)table + link—
8Usage Examples1-3 examples (first = Quick Start)5+ (core) / 1-2 (util)—
9Best PracticesRecommended / avoid patternsrecommended/avoid—
10Design Decisions⚡ OPTIONAL — only for core modules with significant choicesOPTIONAL—
11Dependencies & Related DocsDependency diagram + cross-links—flowchart LR
Lightweight template (
module-simple.md
) — for util/config/helper/test modules:
#SectionContent
1Overview1 paragraph
2API SummaryOverview table + link to api.md
3Usage Examples1-2 examples
4File StructureFile tree
5Best Practices⚡ OPTIONAL
6Related DocsCross-links
Template selection: Before generating each module's documentation, run 
cd <skill-root> && node scripts/index.cjs analyze-module <module-path> --json
to get structured signals. Use 
docScope
as the primary signal — it appears as 
"docScope": "core"
in the JSON output:
docScope
Use this templateLines targetDiagrams
core
module.md
(11-section)		400+2+ distinct types required
overview
overview.md
(5-section)		80-150optional
_index
_index.md
only		30-50none
The 
templateRecommendation
and 
roleRecommendation
fields are also present in the output and are based on quantifiable metrics but are overrideable: your semantic understanding of the module's business role takes precedence.
Code provides signals. You make the final decision.
核心模块使用
module.md
（11个章节），工具/配置/辅助模块使用
module-simple.md
（6个章节）。
完整模板（
module.md
）——适用于核心模块：
#章节内容行数目标图表类型
1概述介绍+价值定位+架构角色2-3段—
2架构定位展示模块位置的Mermaid图表—flowchart TB
3特性表格特性及相关APIN个特性—
4文件结构文件树+职责说明树形结构—
5核心工作流Mermaid流程图—sequenceDiagram
6状态图⚡ 可选——仅适用于有状态模块可选stateDiagram-v2
7API摘要概览表格+指向api.md的链接（不含详细签名）表格+链接—
8使用示例1-3个示例（第一个为快速入门）核心模块≥5行 / 工具模块1-2行—
9最佳实践推荐/避免的模式推荐/避免项—
10设计决策⚡ 可选——仅适用于有重大选择的核心模块可选—
11依赖与相关文档依赖图表+交叉链接—flowchart LR
轻量模板（
module-simple.md
）——适用于工具/配置/辅助/测试模块：
#章节内容
1概述1段文字
2API摘要概览表格+指向api.md的链接
3使用示例1-2个示例
4文件结构文件树
5最佳实践⚡ 可选
6相关文档交叉链接
模板选择规则：在生成每个模块的文档前，运行
cd <skill-root> && node scripts/index.cjs analyze-module <module-path> --json
获取结构化信号。以
docScope
作为主要判断信号——JSON输出中会显示
"docScope": "core"
：
docScope
使用模板行数目标图表要求
core
module.md
（11章节）		≥400行至少2种不同类型
overview
overview.md
（5章节）		80-150行可选
_index
仅
_index.md
30-50行无
输出中还包含
templateRecommendation
和
roleRecommendation
字段，它们基于量化指标生成，但可被覆盖：你对模块业务角色的语义理解优先级更高。
代码提供信号，最终决策由你做出。

🔴 Code Examples

🔴 代码示例要求

Every code example must:
  1. Complete and runnable: Include import, initialization, invocation, result handling
  2. Cover exported interfaces: At least 1 example per major exported API
  3. Include comments: Explain key steps and design intent
  4. Match project language: Follow language best practices
  5. Tiered examples for core APIs (minimum 5 examples per core doc): Three levels — basic usage, advanced usage, and error handling — for each major exported function
  6. Sanitized secrets: NO actual credentials — use placeholders (see "Secret & Credential Sanitization" above)
每个代码示例必须满足：
  1. 完整可运行：包含导入、初始化、调用、结果处理
  2. 覆盖导出接口：每个主要导出API至少1个示例
  3. 包含注释：解释关键步骤与设计意图
  4. 匹配项目语言：遵循语言最佳实践
  5. 核心API的分层示例（核心文档至少5个示例）：每个主要导出函数需提供三个层级的示例——基础用法、高级用法、错误处理
  6. 敏感信息脱敏：禁止包含真实凭证——使用占位符（参见「机密信息与凭证脱敏」）

Cross-Document Linking

跨文档链接

  • Every document MUST contain a "Related Documents" section at the end
  • Module docs should link outward to: architecture position, API reference, dependency graph
  • API docs should link back to: parent module, usage examples, type definitions
Path format rules for "Related Docs" table ("Related Docs" in 
module-simple.md
/ "Dependencies & Related Docs" in 
module.md
):
  • Wiki page links: Use relative paths from the current doc's location. E.g., from 
    modules/badge.md
    : 
    [version]({{ ../api/version.md }})
    → resolved to 
    ../api/version.md
  • Source file references: Do NOT put source files (
    .ts
    , 
    .js
    , etc.) in the Related Docs table. Source files belong in section footers with absolute paths: 
    [version.ts](/src/utils/version.ts#L1)
  • Wrong: 
    [version.ts](/wiki/utils/version.md)
    — mixes wiki path prefix with source file name
  • Wrong: 
    [version.ts](../modules/version.md)
    — links to a wiki page, not the source file
  • Correct (source): 
    [version.ts](/src/utils/version.ts#L1)
  • Correct (wiki page): 
    [API reference](../api/version.md)
  • 每份文档末尾必须包含**「相关文档」**章节
  • 模块文档应向外链接：架构定位、API参考、依赖图
  • API文档应向内链接：父模块、使用示例、类型定义
「相关文档」表格的路径格式规则（
module-simple.md
中的「相关文档」/ 
module.md
中的「依赖与相关文档」）：
  • Wiki页面链接：使用相对于当前文档位置的相对路径。例如，从
    modules/badge.md
    链接：
    [version]({{ ../api/version.md }})
    → 解析为
    ../api/version.md
  • 源文件参考：不要将源文件（
    .ts
    、
    .js
    等）放在「相关文档」表格中。源文件应放在章节页脚，使用绝对路径：
    [version.ts](/src/utils/version.ts#L1)
  • 错误示例：
    [version.ts](/wiki/utils/version.md)
    ——混合了wiki路径前缀与源文件名
  • 错误示例：
    [version.ts](../modules/version.md)
    ——链接到wiki页面而非源文件
  • 正确示例（源文件）：
    [version.ts](/src/utils/version.ts#L1)
  • 正确示例（wiki页面）：
    [API参考](../api/version.md)

Facts-First Rule

事实优先规则

Before writing any API description, function signature, or export list for a module:
  1. Read 
    .nium-wiki/cache/facts/<module-path-with-slashes-replaced-by-double-underscores>.json
  2. All export names and signatures in the documentation MUST match 
    exports[]
    in the facts file
  3. If a symbol is not in 
    exports[]
    , do not document it as a public API. If 
    exports[]
    contains symbols not yet in the document, add them.
  4. If the facts file does not exist, run 
    cd <skill-root> && node scripts/index.cjs analyze-batch <project-root>
    before proceeding — this writes facts to 
    .nium-wiki/cache/facts/
    . Do NOT generate documentation without facts.
在撰写任何模块的API描述、函数签名或导出列表前：
  1. 读取
    .nium-wiki/cache/facts/<模块路径（斜杠替换为双下划线）>.json
  2. 文档中的所有导出名称和签名必须与事实文件中的
    exports[]
    匹配
  3. 若某个符号不在
    exports[]
    中，请勿将其作为公共API记录。若
    exports[]
    包含文档中未提及的符号，需添加进去。
  4. 若事实文件不存在，先运行
    cd <skill-root> && node scripts/index.cjs analyze-batch <project-root>
    ——此命令会将事实写入
    .nium-wiki/cache/facts/
    。禁止在无事实文件的情况下生成文档。

Multi-Module Generation Mode

多模块生成模式

When generating documentation for multiple modules at once using 
analyze-batch
:
  1. Run 
    cd <skill-root> && node scripts/index.cjs discover-modules <project-root> --json
    to get the full module list
  2. Run 
    cd <skill-root> && node scripts/index.cjs analyze-batch <project-root>
    to extract facts for all modules
  3. Output one summary table before starting generation:
    • Total modules discovered
    • Modules with 
      needsReview: true
      (list paths and reasons)
    • Estimated documents to generate
  4. For modules with 
    needsReview: true
    : pause and list them with their reason (
    confidence < 0.3
    or 
    secret detected
    ). Wait for user confirmation before generating those modules. All other modules proceed automatically.
  5. Do NOT output a per-module Exploration Report in Multi-Module Generation Mode — the summary table replaces it.
当使用
analyze-batch
同时生成多个模块的文档时：
  1. 运行
    cd <skill-root> && node scripts/index.cjs discover-modules <project-root> --json
    获取完整模块列表
  2. 运行
    cd <skill-root> && node scripts/index.cjs analyze-batch <project-root>
    提取所有模块的事实
  3. 在开始生成前输出一个汇总表格：
    • 发现的模块总数
    • 标记为
      needsReview: true
      的模块（列出路径及原因）
    • 预计生成的文档数量
  4. 对于标记为
    needsReview: true
    的模块：暂停并列出它们及原因（
    confidence < 0.3
    或检测到敏感信息）。等待用户确认后再生成这些模块。其他模块自动继续。
  5. 在多模块生成模式下，请勿输出每个模块的探索报告——汇总表格替代了该报告。

Incremental Facts Rule

增量事实规则

On patch operations (updating existing documentation after code changes), run this before Step 1 (Read the baseline) of the Surgical Edit sequence:
  1. Re-read the module's 
    facts.json
    even if the document already exists
  2. The facts file is the authoritative source for what the current API looks like
  3. The existing document is a starting point for structure, not a source of truth for API signatures
在补丁操作（代码变更后更新现有文档）时，在「精准编辑：修改现有文档」流程的**步骤1（读取基线）**之前运行以下操作：
  1. 重新读取模块的
    facts.json
    ，即使文档已存在
  2. 事实文件是当前API状态的权威来源
  3. 现有文档仅作为结构起点，而非API签名的事实来源

Mode Overrides

模式覆盖

Applies when: Running in incremental mode, triggered by the 
incremental
pipeline. Priority: These overrides take precedence over the Quality Gate rules above. See Surgical Edit: Modifying Existing Docs for the full execution guide.
Quality Gate RuleIncremental Mode Behavior
core doc ≥ 5 code examplesAdd 0–1 example only when a new API is introduced by the changed source
≥ 2 distinct diagram typesDo NOT regenerate any diagram — preserve existing diagrams unchanged
Full 11-section 
module.md
template		Patch only the affected section(s) based on which source files are listed in 
triggeredBy
flowchart LR
for type/module relationships		Skip unless the class was modified and its source was read
API summary must cover all exportsOnly cover exports that changed
core doc ≥ 400 linesNo minimum — a 50-line targeted patch is preferable to a 400-line rewrite
≥ 3 source reference linksOnly links related to changed source files
适用场景：在增量模式下运行，由
incremental
流水线触发。 优先级：这些覆盖规则优先于上述质量门槛规则。 完整执行指南参见「精准编辑：修改现有文档」。
质量门槛规则增量模式行为
核心文档≥5个代码示例仅当变更的源代码引入新API时，添加0–1个示例
≥2种不同类型的图表不重新生成任何图表——保留现有图表不变
使用完整的11章节
module.md
模板		仅修补受影响的章节，基于
triggeredBy
中列出的源文件
使用
flowchart LR
展示类型/模块关系		跳过，除非类被修改且其源文件已被读取
API摘要必须覆盖所有导出仅覆盖变更的导出
核心文档≥400行无最低行数要求——50行的针对性补丁优于400行的重写
≥3个源文件参考链接仅包含与变更源文件相关的链接

Input Classification

输入分类

Before invoking any CLI commands, parse the user input to determine the execution path:
InputTypeTrigger PhrasesExecution Path
FULL
"generate wiki", "create docs", "rebuild wiki"Full pipeline — all modules
MODULE_TARGETED
"generate wiki for X", "update X docs", "upgrade X docs"Module-level pipeline
MAINTENANCE
"upgrade wiki", "refresh wiki", "audit docs"Maintenance pipeline
EXPLORE
"analyze module X", "explore X"Read-only analysis, no file writes
在调用任何CLI命令前，解析用户输入以确定执行路径：
输入类型触发短语执行路径
FULL
"generate wiki"、"create docs"、"rebuild wiki"完整流水线——所有模块
MODULE_TARGETED
"generate wiki for X"、"update X docs"、"upgrade X docs"模块级流水线
MAINTENANCE
"upgrade wiki"、"refresh wiki"、"audit docs"维护流水线
EXPLORE
"analyze module X"、"explore X"只读分析，不写入文件

Module-Targeted Generation

模块定向生成

Applies when: InputType = 
MODULE_TARGETED
(user specifies a specific module). Otherwise: For 
FULL
mode (no module specified, e.g. "generate wiki" / "rebuild wiki"), skip this entire section and follow Multi-Module Generation Mode — the summary table there replaces the per-module Exploration Report.
适用场景：输入类型 = 
MODULE_TARGETED
（用户指定特定模块）。 其他情况：对于
FULL
模式（未指定模块，例如"generate wiki" / "rebuild wiki"），跳过本节并遵循「多模块生成模式」——该模式下的汇总表格替代了每个模块的探索报告。

Step 0 — Path Resolution

步骤0 — 路径解析

Extract the module path from user input:
"generate wiki for src/core/analyzeProject"  →  src/core/analyzeProject
"update modules/auth docs"                   →  modules/auth
"explore utils/fileWalker"                   →  src/utils/fileWalker
Normalize all paths relative to the project root.
从用户输入中提取模块路径：
"generate wiki for src/core/analyzeProject"  →  src/core/analyzeProject
"update modules/auth docs"                   →  modules/auth
"explore utils/fileWalker"                   →  src/utils/fileWalker
将所有路径归一化为相对于项目根目录的路径。

Step 1 — Pre-flight Check

步骤1 — 预检

bash
cd <skill-root> && node scripts/index.cjs analyze-module <module-path> --json
Read the returned 
docScope
and 
roleRecommendation
:
docScope: core      →  module.md (11-section, 400+ lines, 2+ diagrams)
docScope: overview   →  overview.md (5-section, 80-150 lines)
docScope: _index     →  _index.md only
Also read the module's facts file (Facts-First Rule):
<project-root>/.nium-wiki/cache/facts/<module-path-with-slashes-as-double-underscores>.json
If missing, run 
cd <skill-root> && node scripts/index.cjs analyze-batch <project-root>
first.
Determine document state:
if wiki file already exists for this module:
    →  EXPLORE_THEN_PATCH (surgical edit, preserve existing content)
else:
    →  EXPLORE_THEN_GENERATE (first-time generation)
bash
cd <skill-root> && node scripts/index.cjs analyze-module <module-path> --json
读取返回的
docScope
和
roleRecommendation
：
docScope: core      →  module.md（11章节，≥400行，≥2个图表）
docScope: overview   →  overview.md（5章节，80-150行）
docScope: _index     →  仅_index.md
同时读取模块的事实文件（事实优先规则）：
<project-root>/.nium-wiki/cache/facts/<模块路径（斜杠替换为双下划线）>.json
若文件缺失，先运行
cd <skill-root> && node scripts/index.cjs analyze-batch <project-root>
。
确定文档状态：
若该模块的wiki文件已存在：
    →  EXPLORE_THEN_PATCH（精准编辑，保留现有内容）
否则：
    →  EXPLORE_THEN_GENERATE（首次生成）

Step 2 — Code Exploration (Read-Only, No File Writes)

步骤2 — 代码探索（只读，不写入文件）

Read the actual source code — do not rely on file names or structure alone:
read_file: all source files in the module directory (*.ts/*.js, *.py, *.go, *.rs, *.java, *.cs, *.rb, *.php, etc.)
read_file: entry/index file (index.ts, __init__.py, mod.rs, package-info.java, etc.)
read_file: type/interface definitions if present (types.ts, types.d.ts, interfaces/, etc.)
Analyze:
  • Function signatures: purpose, parameters, return values, side effects
  • Class hierarchies and inheritance
  • Data flow paths and state mutations
  • Error handling strategies
  • Design patterns in use
  • 🔴 Secrets detection: identify hard-coded credentials, API keys, tokens
读取实际源代码——不要仅依赖文件名或结构：
read_file: 模块目录下的所有源文件（*.ts/*.js、*.py、*.go、*.rs、*.java、*.cs、*.rb、*.php等）
read_file: 入口/索引文件（index.ts、__init__.py、mod.rs、package-info.java等）
read_file: 类型/接口定义文件（若存在，如types.ts、types.d.ts、interfaces/等）
分析内容：
  • 函数签名：用途、参数、返回值、副作用
  • 类层次结构与继承关系
  • 数据流路径与状态变更
  • 错误处理策略
  • 使用的设计模式
  • 🔴 敏感信息检测：识别硬编码的凭证、API密钥、令牌

Step 3 — Exploration Report (Output to User, No File Writes)

步骤3 — 探索报告（输出给用户，不写入文件）

Display a structured report and await user confirmation before proceeding:
markdown
undefined
展示结构化报告并等待用户确认后再继续：
markdown
undefined

Module Exploration Report: <module-name>

模块探索报告：<模块名称>

Role: <roleRecommendation> Template: <module.md / module-simple.md> State: <EXPLORE_THEN_GENERATE / EXPLORE_THEN_PATCH>
角色：<roleRecommendation> 模板：<module.md / module-simple.md> 状态：<EXPLORE_THEN_GENERATE / EXPLORE_THEN_PATCH>

Key Findings

关键发现

  • Exports: N functions, M types
  • Dependents: N modules depend on this
  • 导出内容：N个函数，M个类型
  • 依赖模块：N个模块依赖此模块

Recommended Sections

推荐章节

(see Module Document Sections for section list, lines targets, and diagram types)
Proceed with generation? [yes / no / customize]

**This step is mandatory.** A confirmation gate prevents generating content before understanding the code. Do not skip to Step 4 without presenting this report.
（参见「模块文档章节」获取章节列表、行数目标及图表类型）
是否继续生成？[是 / 否 / 自定义]

**此步骤为强制要求**。确认环节可避免在理解代码前生成内容。未展示此报告请勿跳至步骤4。

Step 4 — User Response

步骤4 — 用户响应

ResponseAction
yes
Proceed to Step 5 using the recommended template
no
Exit — write nothing, report nothing
customize
Apply user-specified section additions or removals, then proceed
响应操作
yes
使用推荐模板继续步骤5
no
退出——不写入任何内容，不生成报告
customize
应用用户指定的章节增删，然后继续

Step 5 — Execution

步骤5 — 执行

If 
incremental
returns empty (no code changes detected, but user explicitly specified a module):
Skip incremental dependency computation
Use user-specified module path as the sole target
Do NOT treat as surgical patch (no old doc to compare against)
Resume from Step 1 Pre-flight Check, then proceed to generation
If 
incremental
returns affected docs: use the pipeline's 
triggeredBy
+ 
updateStrength
to decide full vs. surgical.
若
incremental
返回空（未检测到代码变更，但用户明确指定了模块）：
跳过增量依赖计算
使用用户指定的模块路径作为唯一目标
不视为精准补丁（无旧文档可对比）
从步骤1预检重新开始，然后继续生成
若
incremental
返回受影响的文档：使用流水线的
triggeredBy
+ 
updateStrength
决定是完整生成还是精准补丁。

Full Decision Tree

完整决策树

User Input
  │
  ├─ "generate wiki" (no module specified)
  │    ├─ .nium-wiki does not exist → init → FULL pipeline (Sections 1–9, + Section 10 if multi-language)
  │    └─ .nium-wiki exists → FULL pipeline (Sections 1–9, + Section 10 if multi-language)
  │         │
  │         ├─ Section 4 runs: build-deps → discover-modules → analyze-batch
  │         │    └─ Follow Multi-Module Generation Mode rules during Section 8 (Content Generation)
  │         │
  │         └─ After Section 4: check project size
  │              ├─ module count > 10 OR source files > 50 OR LOC > 10,000
  │              │    └─ Switch to Progressive Scanning (see "Progressive Scanning for Large Projects")
  │              └─ otherwise → continue full pipeline normally
  │
  ├─ "generate wiki for <module>"
  │    ├─ .nium-wiki does not exist → init → MODULE_TARGETED
  │    └─ .nium-wiki exists
  │         ├─ incremental has changes → affected docs from pipeline
  │         └─ incremental is empty  → use user-specified module as target
  │    → Exploration Report → User confirms → Generate
  │
  ├─ "upgrade <module> docs"
  │    └─ MODULE_TARGETED + force full regeneration
  │
  ├─ "analyze module X"
  │    └─ Run `cd <skill-root> && node scripts/index.cjs analyze-module <module-path> --json` — JSON signals only, no wiki files written
  │
  └─ "refresh / upgrade wiki" (no module)
       └─ MAINTENANCE → audit → regenerate failing docs
用户输入
  │
  ├─ "generate wiki"（未指定模块）
  │    ├─ .nium-wiki不存在 → 初始化 → FULL流水线（章节1–9，若为多语言则加章节10）
  │    └─ .nium-wiki存在 → FULL流水线（章节1–9，若为多语言则加章节10）
  │         │
  │         ├─ 执行章节4：build-deps → discover-modules → analyze-batch
  │         │    └─ 在章节8（内容生成）期间遵循多模块生成模式规则
  │         │
  │         └─ 章节4完成后：检查项目规模
  │              ├─ 模块数>10 或 源文件数>50 或 代码行数>10,000
  │              │    └─ 切换为渐进式扫描（参见「大型项目的渐进式扫描」）
  │              └─ 否则 → 正常继续完整流水线
  │
  ├─ "generate wiki for <module>"
  │    ├─ .nium-wiki不存在 → 初始化 → MODULE_TARGETED
  │    └─ .nium-wiki存在
  │         ├─ incremental检测到变更 → 流水线返回受影响的文档
  │         └─ incremental返回空  → 使用用户指定的模块作为目标
  │    → 探索报告 → 用户确认 → 生成
  │
  ├─ "upgrade <module> docs"
  │    └─ MODULE_TARGETED + 强制完整重新生成
  │
  ├─ "analyze module X"
  │    └─ 运行`cd <skill-root> && node scripts/index.cjs analyze-module <module-path> --json`——仅输出JSON信号，不写入wiki文件
  │
  └─ "refresh / upgrade wiki"（未指定模块）
       └─ MAINTENANCE → 审核 → 重新生成不合格文档

Workflow

工作流程

1. CLI Commands Quick Reference

1. CLI命令速查

🔴 Execution context: Skill CWD is not guaranteed to be the skill root across Coding Agents, so 
scripts/index.cjs
cannot be resolved from the default CWD. Every runnable example is written as 
cd <skill-root> && node scripts/index.cjs ...
— the Agent MUST 
cd
in first, then pass 
<project-root>
as an argument.
<skill-root>
is the directory containing this 
SKILL.md
file. Resolve it from this file's absolute path, do not guess from agent-specific conventions.
bash
undefined
🔴 执行上下文：在不同的编码Agent中，Skill的当前工作目录（CWD）不一定是Skill根目录，因此无法从默认CWD解析
scripts/index.cjs
。每个可运行示例都写为
cd <skill-root> && node scripts/index.cjs ...
——Agent必须先
cd
到该目录，再传入
<project-root>
作为参数。
<skill-root>
是包含此
SKILL.md
文件的目录。需从此文件的绝对路径解析，不要根据Agent特定的约定猜测。
bash
undefined

Signatures (paths shown without the 
cd <skill-root> &&
prefix for readability)

签名（为便于阅读，示例中省略了
cd <skill-root> &&
前缀）

node scripts/index.cjs init <project-root> --lang <code> # Initialize .nium-wiki directory (lang: zh/en/ja/ko/fr/de) node scripts/index.cjs build-deps <project-root> # Build import/require dependency graph node scripts/index.cjs discover-modules <project-root> # Discover all modules via import graph + directory scan node scripts/index.cjs analyze-batch <project-root> [--force] [--min-confidence <n>] # Extract facts for all modules node scripts/index.cjs analyze-module <module-path> [--json] # Analyze one module: classify role, recommend template node scripts/index.cjs incremental <project-root> [--no-commit] [-v] # Full pipeline: diff → deps → doc-index → affected docs node scripts/index.cjs diff-index <project-root> # Detect file changes (--no-update to skip hash write) node scripts/index.cjs build-index <project-root> # Build source ↔ doc mapping index node scripts/index.cjs generate-sidebar <wiki-path> [--all] # Generate sidebar.json for all language directories node scripts/index.cjs audit-docs <wiki-path> [--verbose|--json|--mermaid-strict|--role <role>] # Check doc quality node scripts/index.cjs serve <wiki-path> # Start docsify server

For detailed usage, see `cd <skill-root> && node scripts/index.cjs --help`

> **⚠️ Path argument convention**: This document uses four distinct path notations — do not confuse them:
>
> | Notation | Meaning |
> |---|---|
> | `<skill-root>` | **The directory containing this `SKILL.md` file.** Always `cd` here before invoking `node scripts/index.cjs ...` so the relative path `scripts/index.cjs` resolves regardless of the Agent's default CWD |
> | `<project-root>` | **Absolute path of the user's current workspace root** — the directory the user is working in (e.g. `/Users/alice/repos/my-app`). Passed as a command argument, NOT as CWD |
> | `<module-path>` | Project-root-relative path to a single module (e.g. `src/core/analyzeProject`). Used only with `analyze-module` |
> | `<wiki-path>` | Path to the `.nium-wiki` directory, usually `<project-root>/.nium-wiki`. Used with `generate-sidebar`, `audit-docs`, `serve`, `i18n` |
>
> The Agent is responsible for substituting every placeholder with a real value before executing. Do NOT
> pass the placeholder string literally, and do NOT pass `.` — `.` would resolve against an unpredictable
> CWD depending on the host Agent.
node scripts/index.cjs init <project-root> --lang <code> # 初始化.nium-wiki目录（语言代码：zh/en/ja/ko/fr/de） node scripts/index.cjs build-deps <project-root> # 构建导入/依赖关系图 node scripts/index.cjs discover-modules <project-root> # 通过导入图+目录扫描发现所有模块 node scripts/index.cjs analyze-batch <project-root> [--force] [--min-confidence <n>] # 提取所有模块的事实 node scripts/index.cjs analyze-module <module-path> [--json] # 分析单个模块：分类角色，推荐模板 node scripts/index.cjs incremental <project-root> [--no-commit] [-v] # 完整流水线：差异检测 → 依赖分析 → 文档索引 → 受影响文档 node scripts/index.cjs diff-index <project-root> # 检测文件变更（--no-update跳过哈希写入） node scripts/index.cjs build-index <project-root> # 构建源代码 ↔ 文档的映射索引 node scripts/index.cjs generate-sidebar <wiki-path> [--all] # 为所有语言目录生成sidebar.json node scripts/index.cjs audit-docs <wiki-path> [--verbose|--json|--mermaid-strict|--role <role>] # 检查文档质量 node scripts/index.cjs serve <wiki-path> # 启动docsify服务器

详细用法参见`cd <skill-root> && node scripts/index.cjs --help`

> **⚠️ 路径参数约定**：本文档使用四种不同的路径表示法——请勿混淆：
>
> | 表示法 | 含义 |
> |---|---|
> | `<skill-root>` | **包含此`SKILL.md`文件的目录**。调用`node scripts/index.cjs ...`前必须先`cd`到此处，这样相对路径`scripts/index.cjs`才能在Agent的默认CWD不确定的情况下正确解析 |
> | `<project-root>` | **用户当前工作区根目录的绝对路径**——用户正在工作的目录（例如`/Users/alice/repos/my-app`）。作为命令参数传入，而非作为CWD |
> | `<module-path>` | 相对于项目根目录的单个模块路径（例如`src/core/analyzeProject`）。仅与`analyze-module`一起使用 |
> | `<wiki-path>` | `.nium-wiki`目录的路径，通常为`<project-root>/.nium-wiki`。与`generate-sidebar`、`audit-docs`、`serve`、`i18n`一起使用 |
>
> Agent负责在执行前将所有占位符替换为真实值。请勿直接传入占位符字符串，也不要传入`.`——`.`会根据宿主Agent的不同解析为不可预测的CWD。

2. Language Detection (MANDATORY)

2. 语言检测（强制要求）

⚠️ CRITICAL: This step must be completed BEFORE any other operation.
Before running any CLI commands or generating any documentation:
  1. Check if 
    .nium-wiki/config.json
    exists
  2. If exists: Read the 
    language
    field — this is the primary documentation language and the source of truth
  3. If not exists: You will set it when running 
    init --lang <code>
    (determine from project's natural language + user conversation language)
Rule: The 
language
field in 
config.json
is the only authoritative source for documentation language. Do NOT infer language from source code comments, README, file names, or conversation context.
⚠️ 关键要求：此步骤必须在任何其他操作之前完成。
在运行任何CLI命令或生成任何文档前：
  1. 检查
    .nium-wiki/config.json
    是否存在
  2. 若存在：读取
    language
    字段——这是主要文档语言，也是唯一的事实来源
  3. 若不存在：运行
    init --lang <code>
    时设置该字段（根据项目的自然语言+用户对话语言确定）
规则：
config.json
中的
language
字段是文档语言的唯一权威来源。 请勿从源代码注释、README、文件名或对话上下文推断语言。

2.1 Language Conflict Resolution

2.1 语言冲突解决

🔴 CRITICAL: Never modify 
config.json
directly via file write or text replacement. Use the following procedures instead:
ScenarioAction
Config exists, user wants to add a secondary language (e.g. config=
en
, user wants to also generate 
zh
)		Run 
cd <skill-root> && node scripts/index.cjs init <project-root> --lang zh
— appends 
zh
as a secondary language to config
User wants to change the primary language (e.g. config=
en
, user wants 
zh
as primary)		Run 
cd <skill-root> && node scripts/index.cjs init <project-root> --lang zh --force
— overwrites primary language to 
zh
User wants to generate docs in a language already in configNo config change needed — run 
cd <skill-root> && node scripts/index.cjs incremental <project-root>
directly
Why: Direct file edits to 
config.json
bypass the CLI's validation and can corrupt the JSON structure. Always go through the CLI.
🔴 关键要求：绝不通过文件写入或文本替换直接修改
config.json
。 请改用以下流程：
场景操作
配置已存在，用户想要添加次要语言（例如配置=
en
，用户还想生成
zh
）		运行
cd <skill-root> && node scripts/index.cjs init <project-root> --lang zh
——将
zh
作为次要语言添加到配置中
用户想要更改主要语言（例如配置=
en
，用户想要
zh
作为主要语言）		运行
cd <skill-root> && node scripts/index.cjs init <project-root> --lang zh --force
——将主要语言覆盖为
zh
用户想要生成已在配置中的语言文档无需更改配置——直接运行
cd <skill-root> && node scripts/index.cjs incremental <project-root>
原因：直接编辑
config.json
会绕过CLI的验证，可能破坏JSON结构。始终通过CLI进行操作。

3. Language Configuration

3. 语言配置

Read 
.nium-wiki/config.json
and extract the 
language
setting. Format is slash-separated: the first language is the primary language (e.g. 
zh
, 
en
, 
zh/en
).
  • Generate all primary documentation in the primary language to 
    .nium-wiki/wiki/
    .
  • If secondary languages are configured (e.g. 
    zh/en
    means primary=zh, secondary=en), after primary docs are written, translate all wiki documents into 
    wiki_{lang}/
    directories (e.g. 
    .nium-wiki/wiki_en/
    ). See Section 10 for details.
Convention: 
wiki/
= primary language, 
wiki_{lang}/
= secondary language. The translated directory must mirror the exact same structure and filenames as 
wiki/
.
🔴 IMPORTANT: Single-language output only. Templates contain bilingual headings (e.g. 
## Architecture Preview / 架构预览
) for reference purposes only. When generating documentation, output only the primary language. Do NOT mix languages or copy the 
English / 中文
format into the output.
  • If 
    language
    is 
    en
    : headings should be 
    ## Architecture Preview
    , NOT 
    ## Architecture Preview / 架构预览
  • If 
    language
    is 
    zh
    : headings should be 
    ## 架构预览
    , NOT 
    ## Architecture Preview / 架构预览
读取
.nium-wiki/config.json
并提取
language
设置。格式为斜杠分隔：第一个语言是主要语言（例如
zh
、
en
、
zh/en
）。
  • 将所有主要文档以主要语言生成到
    .nium-wiki/wiki/
    目录。
  • 若配置了次要语言（例如
    zh/en
    表示主要语言=zh，次要语言=en），在生成主要文档后，将所有wiki文档翻译到
    wiki_{lang}/
    目录（例如
    .nium-wiki/wiki_en/
    ）。详情参见章节10。
约定：
wiki/
= 主要语言，
wiki_{lang}/
= 次要语言。翻译后的目录必须与
wiki/
的结构和文件名完全一致。
🔴 重要提示：仅输出单一语言。 模板包含双语标题（例如
## Architecture Preview / 架构预览
）仅作为参考。生成文档时，仅输出主要语言。请勿混合语言或复制
English / 中文
格式到输出中。
  • 若
    language
    为
    en
    ：标题应为
    ## Architecture Preview
    ，而非
    ## Architecture Preview / 架构预览
  • 若
    language
    为
    zh
    ：标题应为
    ## 架构预览
    ，而非
    ## Architecture Preview / 架构预览

4. Project Analysis (Deep)

4. 项目深度分析

Run the following commands to build the dependency graph, discover modules, and extract facts:
bash
cd <skill-root> && node scripts/index.cjs build-deps <project-root>
cd <skill-root> && node scripts/index.cjs discover-modules <project-root>
cd <skill-root> && node scripts/index.cjs analyze-batch <project-root>
build-deps
is auto-triggered by 
discover-modules
and 
analyze-batch
if 
dep-graph.json
is missing — you can skip it if the graph is already up to date.
  1. Identify tech stack: Check dependency manifests (e.g. package.json, requirements.txt, go.mod, Cargo.toml, pom.xml, etc.)
  2. Find entry points: Locate main source files (e.g. src/index.ts, main.py, main.go, main.rs, src/main/java/App.java, etc.)
  3. Identify modules: Use 
    discover-modules
    output — it merges import-graph discovery with directory scan for full coverage
  4. Find existing docs: README.md, CHANGELOG.md, etc.
运行以下命令构建依赖关系图、发现模块并提取事实：
bash
cd <skill-root> && node scripts/index.cjs build-deps <project-root>
cd <skill-root> && node scripts/index.cjs discover-modules <project-root>
cd <skill-root> && node scripts/index.cjs analyze-batch <project-root>
若
dep-graph.json
缺失，
discover-modules
和
analyze-batch
会自动触发
build-deps
——若依赖图已更新，可跳过
build-deps
。
  1. 识别技术栈：检查依赖清单（例如package.json、requirements.txt、go.mod、Cargo.toml、pom.xml等）
  2. 找到入口点：定位主源文件（例如src/index.ts、main.py、main.go、main.rs、src/main/java/App.java等）
  3. 识别模块：使用
    discover-modules
    的输出——它结合了导入图发现与目录扫描，实现全覆盖
  4. 查找现有文档：README.md、CHANGELOG.md等

5. Deep Code Analysis (CRITICAL)

5. 深度代码分析（关键步骤）

IMPORTANT: For every module, read the actual source code — do not rely on file names or directory structure alone:
  1. Read source files: Open key files with read_file tool
  2. Parse semantics: Determine what the code does, not merely how it is organized
  3. Capture details:
    • Function signatures: purpose, parameters, return values, side effects
    • Class hierarchies and inheritance chains
    • Data flow paths and state mutations
    • Error handling strategies
    • Design patterns in use
    • 🔴 Secrets detection: Identify hard-coded credentials, API keys, tokens, and sensitive data that need sanitization
  4. Map relationships: Module dependencies, call graphs, data flow
  5. Flag complexity hotspots: Functions with deep nesting (> 4 levels), high branching (> 10 conditions), or excessive length (> 100 LOC). Document these in module docs with logic explanations and refactoring suggestions.
重要提示：对于每个模块，读取实际源代码——不要仅依赖文件名或目录结构：
  1. 读取源文件：使用read_file工具打开关键文件
  2. 解析语义：确定代码的功能，而非仅关注其组织方式
  3. 捕获细节：
    • 函数签名：用途、参数、返回值、副作用
    • 类层次结构与继承链
    • 数据流路径与状态变更
    • 错误处理策略
    • 使用的设计模式
    • 🔴 敏感信息检测：识别需要脱敏的硬编码凭证、API密钥、令牌和敏感数据
  4. 映射关系：模块依赖、调用图、数据流
  5. 标记复杂度热点：深度嵌套（>4层）、高分支（>10个条件）或过长（>100行）的函数。在模块文档中记录这些内容，并提供逻辑说明和重构建议。

6. Change Detection

6. 变更检测

Use the automated incremental pipeline to detect changes and compute the precise list of affected docs in one step:
bash
cd <skill-root> && node scripts/index.cjs incremental <project-root> [--no-commit] [-v]
This runs the full pipeline: 
diff-index
→ 
build-deps
→ 
build-index
→ transitive-impact → doc-dep analysis. It outputs:
  • Which source files changed (+added, ~modified, -deleted)
  • Which wiki docs need regeneration (with reason: source_changed, dep_changed, doc_dep_changed, inferred)
  • Which docs will be deleted
  • Which docs are preserved (unchanged)
If wiki doesn't exist yet: the pipeline automatically falls back to full-generation mode.
IMPORTANT: Always run 
incremental
before generating, not 
diff-index
alone. 
diff-index
only detects source changes — it does NOT map them to wiki docs. After 
incremental
completes, always check i18n sync status (see Section 10) before declaring the update done.
使用自动化增量流水线一步检测变更并计算受影响文档的精确列表：
bash
cd <skill-root> && node scripts/index.cjs incremental <project-root> [--no-commit] [-v]
此命令运行完整流水线：
diff-index
→ 
build-deps
→ 
build-index
→ 传递性影响分析 → 文档依赖分析。输出内容包括：
  • 哪些源文件发生了变更（+新增，~修改，-删除）
  • 哪些wiki文档需要重新生成（原因：source_changed、dep_changed、doc_dep_changed、inferred）
  • 哪些文档将被删除
  • 哪些文档保留不变（未变更）
若wiki尚未存在：流水线自动回退到完整生成模式。
重要提示：生成前始终运行
incremental
，而非仅运行
diff-index
。 
diff-index
仅检测源代码变更——无法将变更映射到wiki文档。 
incremental
完成后，在宣布更新完成前始终检查i18n同步状态（参见章节10）。

7. Target Docs (resolved by the pipeline above)

7. 目标文档（由上述流水线解析）

The 
incremental
command in Section 6 already resolves this. Each affected doc includes:
  • docPath
    : relative wiki path (e.g. 
    modules/core/source-index.md
    )
  • reason
    : why it needs updating
  • triggeredBy
    : source files that triggered the update
Manual fallback (if pipeline not available): Read 
.nium-wiki/cache/doc-index.json
→ 
sourceToDoc
field. If a changed source file has no entry, infer by naming convention: 
src/fooBar.ts
→ 
modules/foo-bar.md
, and nested paths: 
src/core/analyzeProject.ts
→ 
modules/core/analyze-project.md
.
章节6中的
incremental
命令已解析出目标文档。每个受影响的文档包含：
  • docPath
    ：相对wiki路径（例如
    modules/core/source-index.md
    ）
  • reason
    ：需要更新的原因
  • triggeredBy
    ：触发更新的源文件
手动回退方案（若流水线不可用）：读取
.nium-wiki/cache/doc-index.json
→ 
sourceToDoc
字段。若变更的源文件无对应条目，按命名约定推断：
src/fooBar.ts
→ 
modules/foo-bar.md
，嵌套路径：
src/core/analyzeProject.ts
→ 
modules/core/analyze-project.md
。

8. Content Generation

8. 内容生成

🔴 Language: use 
language
from 
.nium-wiki/config.json
— see Section 3. Do NOT infer from source code or conversation.
Generate content adhering to the quality gate defined above:
🔴 语言要求：使用
.nium-wiki/config.json
中的
language
设置——参见章节3。请勿从源代码或对话推断语言。
生成内容时需遵守上述质量门槛：

8.1 Template Selection Rules

8.1 模板选择规则

Read the named template file from 
templates/
before writing each doc. Not all templates are needed for every project — apply these rules:
DocTemplate fileWhen to generateNotes
index.md
templates/index.md
always—
architecture.md
templates/architecture.md
always—
modules/<name>.md
templates/module.md
(core) or 
templates/module-simple.md
(util/config/helper/test)		always (choose by 
docScope
)		Module docs only contain an API overview table + link. Detailed signatures and type definitions belong exclusively in 
api.md
.
<domain>/_index.md
templates/_index.md
one per domain directory under 
wiki/
Short overview + architecture diagram + sub-module table. No detailed API docs.
getting-started.md
templates/getting-started.md
project has install steps OR is a library/framework—
api/<name>.md
templates/api.md
project exports programmatic APIs (functions/classes/types)Single source of truth for all API signatures/types. Mark 
@deprecated
with migration guidance. Include parameter constraints where applicable (e.g. "must not be empty", "range 0-100").
doc-map.md
templates/doc-map.md
module count >= 5—
在撰写每个文档前，从
templates/
目录读取指定的模板文件。并非所有模板都适用于每个项目——请遵循以下规则：
文档模板文件生成时机说明
index.md
templates/index.md
始终生成—
architecture.md
templates/architecture.md
始终生成—
modules/<name>.md
templates/module.md
（核心模块）或
templates/module-simple.md
（工具/配置/辅助/测试模块）		始终生成（根据
docScope
选择）		模块文档仅包含API概览表格+链接。详细签名和类型定义仅放在
api.md
中。
<domain>/_index.md
templates/_index.md
wiki/
下每个领域目录生成一个		简短概述+架构图+子模块表格。无详细API文档。
getting-started.md
templates/getting-started.md
项目包含安装步骤或为库/框架时生成—
api/<name>.md
templates/api.md
项目导出可编程API（函数/类/类型）时生成所有API签名/类型的唯一事实来源。标记
@deprecated
并提供迁移指南。包含参数约束（例如"不能为空"、"范围0-100"）。
doc-map.md
templates/doc-map.md
模块数≥5时生成—

8.2 Source Links

8.2 源文件链接

Attach navigable source links next to documented symbols:
markdown
undefined
在记录的符号旁添加可导航的源文件链接：
markdown
undefined

functionName
📄

functionName
📄

undefined
undefined

9. Save

9. 保存

  • Write wiki files to 
    .nium-wiki/wiki/
  • Sanitize link paths and build indexes after wiki files are written:
bash
cd <skill-root> && node scripts/index.cjs sanitize-links <project-root>
cd <skill-root> && node scripts/index.cjs build-index <project-root>
cd <skill-root> && node scripts/index.cjs diff-index <project-root>  # --no-update to skip hash write
sanitize-links
scans all wiki 
.md
files and converts any 
file://
absolute paths to project-root-relative paths. MUST run before 
build-index
. 
build-index
scans source path links in wiki files to build 
cache/doc-index.json
(source ↔ doc mapping for incremental updates). 
diff-index
(without 
--no-update
) is called last so the hash snapshot reflects the final state.
  • Refresh 
    meta.json
    timestamp
  • 🔴 MANDATORY — Generate sidebar:
bash
cd <skill-root> && node scripts/index.cjs generate-sidebar <wiki-path> --all
This generates 
sidebar.json
for all language directories. It is idempotent — if 
sidebar.json
already exists it will be skipped. If a legacy 
_sidebar.md
exists it will be migrated automatically. This step is mandatory after every wiki generation — the preview server and all modern tooling depend on 
sidebar.json
. Do NOT skip it.
  • 将wiki文件写入
    .nium-wiki/wiki/
    目录
  • 在wiki文件写入后，清理链接路径并构建索引：
bash
cd <skill-root> && node scripts/index.cjs sanitize-links <project-root>
cd <skill-root> && node scripts/index.cjs build-index <project-root>
cd <skill-root> && node scripts/index.cjs diff-index <project-root>  # --no-update跳过哈希写入
sanitize-links
扫描所有wiki 
.md
文件，将任何
file://
绝对路径转换为相对于项目根目录的路径。必须在
build-index
之前运行。 
build-index
扫描wiki文件中的源路径链接，构建
cache/doc-index.json
（用于增量更新的源代码 ↔ 文档映射）。 最后调用
diff-index
（不带
--no-update
），使哈希快照反映最终状态。
  • 更新
    meta.json
    的时间戳
  • 🔴 强制要求——生成侧边栏：
bash
cd <skill-root> && node scripts/index.cjs generate-sidebar <wiki-path> --all
此命令为所有语言目录生成
sidebar.json
。它是幂等的——若
sidebar.json
已存在则跳过。若存在旧版
_sidebar.md
会自动迁移。每次wiki生成后必须运行此步骤——预览服务器和所有现代工具都依赖
sidebar.json
。请勿跳过。

10. Multi-language Translation

10. 多语言翻译

Applies to both full generation and incremental updates. Every time 
wiki/
is modified, secondary language files in 
wiki_{lang}/
that correspond to changed docs must be kept in sync — do not leave them stale.
Skip this step if 
language
contains only one language.
适用于完整生成和增量更新。每次
wiki/
目录被修改时，必须同步
wiki_{lang}/
目录中对应变更文档的次要语言文件——请勿让它们过期。
若
language
仅包含一种语言，跳过此步骤。

10.1 Build Translation Task List

10.1 构建翻译任务列表

Run 
cd <skill-root> && node scripts/index.cjs i18n status <wiki-path>
to get the sync report. Extract every file marked 
Missing
or 
Outdated
into an explicit checklist (e.g. 
❌ [Missing] index.md
, 
⚠️ [Outdated] architecture.md
).
You MUST translate every file in this list — no exceptions, no skipping.
Incremental mode: If this is a partial update (incremental pipeline detected changes), only translate files that are 
Outdated
or 
Missing
— do NOT re-translate all 
Synced
files. Full generation mode: Translate all 
Missing
files (
Outdated
may not exist yet since memory has not been populated).**
运行
cd <skill-root> && node scripts/index.cjs i18n status <wiki-path>
获取同步报告。将每个标记为
Missing
或
Outdated
的文件提取到明确的检查清单中（例如
❌ [Missing] index.md
、
⚠️ [Outdated] architecture.md
）。
必须翻译清单中的每个文件——无例外，无跳过。
增量模式：若为部分更新（增量流水线检测到变更），仅翻译
Outdated
或
Missing
的文件——请勿重新翻译所有
Synced
文件。 完整生成模式：翻译所有
Missing
文件（由于内存尚未填充，可能不存在
Outdated
文件）。**

10.2 Translate Files One by One

10.2 逐个翻译文件

🔴 MANDATORY: Process EVERY file in the checklist sequentially.
For each file:
  1. Read the primary wiki file from 
    wiki/
  2. Translate content to the target language
  3. Write to 
    wiki_{lang}/
    with identical path and filename (e.g. 
    wiki/core/auth.md
    → 
    wiki_en/core/auth.md
    )
  4. Preserve unchanged: all Mermaid diagrams, code blocks (EXCEPT sanitize any secrets/credentials if found), source path links, and markdown structure
    • Secret sanitization exception: If code blocks contain secrets/credentials, sanitize them using the rules from the "Secret & Credential Sanitization" section
After each file, report progress: 
✅ [3/17] wiki_en/core/_index.md
Batching rule: If the file count exceeds 10, translate in batches of 5. After each batch, report progress and continue immediately — do NOT stop or ask the user unless you hit a context limit. If you must stop, clearly list the remaining untranslated files so the user can say "continue" to resume.
🔴 强制要求：按顺序处理清单中的每个文件。
对于每个文件：
  1. 从
    wiki/
    目录读取主要语言的wiki文件
  2. 将内容翻译为目标语言
  3. 写入
    wiki_{lang}/
    目录，保持完全相同的路径和文件名（例如
    wiki/core/auth.md
    → 
    wiki_en/core/auth.md
    ）
  4. 保留不变内容：所有Mermaid图表、代码块（若发现敏感信息/凭证则需脱敏）、源路径链接和Markdown结构
    • 敏感信息脱敏例外：若代码块包含敏感信息/凭证，需按照「机密信息与凭证脱敏」章节的规则进行脱敏
每个文件翻译完成后，报告进度：
✅ [3/17] wiki_en/core/_index.md
批量规则：若文件数量超过10个，每5个为一批进行翻译。每批完成后报告进度并立即继续——除非遇到上下文限制，否则不要停止或询问用户。若必须停止，需明确列出剩余未翻译的文件，以便用户说"continue"时继续。

10.3 Finalize

10.3 完成

After ALL files are translated:
bash
cd <skill-root> && node scripts/index.cjs i18n sync-memory <wiki-path>
Run 
cd <skill-root> && node scripts/index.cjs i18n status <wiki-path>
again to verify all files show as 
Synced
. If any files are still 
Missing
or 
Outdated
, go back and translate them.
Delete rule: When deleting any file from 
wiki/
(e.g. because the source file was deleted), you MUST also delete the corresponding file from ALL 
wiki_{lang}/
directories.
所有文件翻译完成后：
bash
cd <skill-root> && node scripts/index.cjs i18n sync-memory <wiki-path>
再次运行
cd <skill-root> && node scripts/index.cjs i18n status <wiki-path>
验证所有文件显示为
Synced
。若仍有文件标记为
Missing
或
Outdated
，返回重新翻译。
删除规则：当从
wiki/
目录删除任何文件（例如源文件被删除），必须同时从所有
wiki_{lang}/
目录删除对应的文件。

Surgical Edit: Modifying Existing Docs

精准编辑：修改现有文档

Applies when: Updating 1-3 existing wiki documents (incremental pipeline result), not full generation.
When an existing doc already exists, your goal is to patch the minimum surface area, not regenerate the full file. Every line you leave untouched is a line that does not need to be reviewed, diffed, or reverted.
适用场景：更新1-3个现有wiki文档（增量流水线结果），而非完整生成。
当文档已存在时，目标是最小化修改范围，而非重新生成整个文件。每一行未修改的内容都是无需审核、对比或回滚的内容。

🔴 Quality Gate Disabled During Incremental Updates

🔴 增量更新期间禁用质量门槛

⚠️ CRITICAL: When running in incremental mode (triggered by 
incremental
pipeline), the global Quality Gate rules above do NOT apply to existing docs being surgically patched. Applying those rules blindly is the primary cause of oversized diffs and unnecessary rewrites.
See Mode Overrides for the full table of Quality Gate rule overrides in incremental mode.
updateStrength
from the 
incremental
pipeline controls patch depth:
updateStrength
MeaningAction
full
Function signature changed OR module role changedFull regeneration of this doc
incremental
Transitive/dep/doc-dep propagationSurgical patch only — no quality gate, no template
Rule: If the pipeline says 
updateStrength: incremental
for a doc, treat it as a targeted patch — update only the section that mentions the triggering source, leave everything else untouched.
⚠️ 关键要求：在增量模式下（由
incremental
流水线触发），上述全局质量门槛规则不适用于正在进行精准补丁的现有文档。盲目应用这些规则是导致差异过大和不必要重写的主要原因。
增量模式下的质量门槛规则覆盖详情参见「模式覆盖」。
增量流水线返回的
updateStrength
控制补丁深度：
updateStrength
含义操作
full
函数签名变更或模块角色变更完整重新生成此文档
incremental
传递性/依赖/文档依赖传播仅精准补丁——无质量门槛，无模板
规则：若流水线标记某文档的
updateStrength: incremental
，则将其视为针对性补丁——仅更新提及触发源的章节，其余内容保持不变。

Mandatory Steps (Execute in Order)

强制步骤（按顺序执行）

Never start from the template when updating an existing doc.
Step 1 — Read the baseline
  • read_file: the existing wiki doc (read-only, this is what you are preserving)
  • read_file: all source files that triggered the update (from 
    incremental
    output)
Step 2 — Evaluate match degree Cross-read the existing doc against the changed source files. Answer:
  • Which sections of the existing doc directly correspond to the changed code?
  • Which sections are completely unaffected?
  • What is your overall match degree?
Step 3 — Decide strategy by match degree
Match degreeSignalsAction
≥ 80%Internal change only (comment, variable rename, refactor); function signatures unchanged; core topics not touchedDefault: PRESERVE — update version footer only, do not touch the body. If no version footer exists, create one (a single line).
40–80%One function's behavior changed; new export added; file structure changedPatch only the affected sections — leave everything else untouched
< 40%Function renamed or signature changed; module role changed; multiple sections invalidatedFull regeneration of this document
Step 4 — Write the patched doc
  • Output MUST be a minimal diff from the original — significantly smaller than a full regeneration
  • Do not use the module template as the starting point for an existing doc
Step 5 — Self-verify Before finalizing, mentally check: does the new file differ from the original in anything beyond the source-change-affected sections, newly-added sections, and now-incorrect sections? If yes, you are rewriting too much — restore the preserved sections.
更新现有文档时绝不要从模板开始。
步骤1 — 读取基线
  • read_file：现有wiki文档（只读，这是需要保留的内容）
  • read_file：所有触发更新的源文件（来自
    incremental
    输出）
步骤2 — 评估匹配度 交叉读取现有文档与变更的源文件。回答以下问题：
  • 现有文档的哪些章节与变更的代码直接对应？
  • 哪些章节完全不受影响？
  • 整体匹配度是多少？
步骤3 — 根据匹配度决定策略
匹配度信号操作
≥ 80%仅内部变更（注释、变量重命名、重构）；函数签名未变更；核心主题未触及默认：保留——仅更新版本页脚，不修改正文。若无版本页脚，添加一行。
40–80%某个函数的行为变更；新增导出；文件结构变更仅修补受影响的章节——其余内容保持不变
< 40%函数重命名或签名变更；模块角色变更；多个章节失效完整重新生成此文档
步骤4 — 写入补丁后的文档
  • 输出必须与原始文档的差异最小——远小于完整重新生成的差异
  • 不要以模块模板作为现有文档的起点
步骤5 — 自我验证 最终确定前，检查：新文件与原始文件的差异是否仅涉及受源变更影响的章节、新增章节和现在不正确的章节？若是，则修改范围过大——恢复保留的章节。

Principle 1 — Preservation Priority

原则1 — 优先保留

Unless the source has actually changed, the following MUST be preserved exactly as-is:
Content typeWhen to update
Accurate description paragraphsNever (unless source logic changed)
Correct code examplesNever (unless the code itself changed)
Mermaid diagramsNever (unless the underlying flow/calls changed)
File structure treeOnly when files were added/removed
API summary tableOnly when function signatures changed
Best practices sectionNever (unless the module logic changed)
Cross-linksOnly when linked docs were moved/renamed
除非源代码实际变更，否则以下内容必须完全保留：
内容类型更新时机
准确的描述段落绝不更新（除非源代码逻辑变更）
正确的代码示例绝不更新（除非代码本身变更）
Mermaid图表绝不更新（除非底层流程/调用变更）
文件结构树仅在文件新增/删除时更新
API摘要表格仅在函数签名变更时更新
最佳实践章节绝不更新（除非模块逻辑变更）
交叉链接仅在链接的文档被移动/重命名时更新

Principle 2 — Change Scope Isolation

原则2 — 隔离变更范围

Before editing, write down the minimum scope:
Change type → Minimum doc impact

1. Function logic changed (signature unchanged)
   → Update only that function's description paragraph
   → Code example only if the behavior changed in a user-visible way (callers must change)
   → If change only affects internal call chains, not external callers: update version footer only
   → Do NOT rewrite other functions' descriptions

2. New exported function added
   → Append one row to the API summary table
   → Add one usage example (optional)
   → Do NOT rewrite existing examples

3. File added/removed
   → Update the File Structure tree
   → Do NOT regenerate Architecture Position diagram (unless the module's position actually changed)

4. Bug fix (doc described old/wrong behavior)
   → Fix only the affected paragraph
   → Do NOT restructure the entire section
编辑前，写下最小变更范围：
变更类型 → 最小文档影响

1. 函数逻辑变更（签名未变）
   → 仅更新该函数的描述段落
   → 仅当行为变更对用户可见（调用者必须修改）时，更新代码示例
   → 若变更仅影响内部调用链，不影响外部调用者：仅更新版本页脚
   → 不要重写其他函数的描述

2. 新增导出函数
   → 在API摘要表格中添加一行
   → 可选：添加一个使用示例
   → 不要重写现有示例

3. 文件新增/删除
   → 更新文件结构树
   → 不要重新生成架构定位图（除非模块的实际位置变更）

4. bug修复（文档描述了旧的/错误的行为）
   → 仅修复受影响的段落
   → 不要重构整个章节

Principle 3 — When in Doubt, Don't Touch

原则3 — 存疑时，请勿修改

🔴 PRESERVE is the default at ≥ 80% match. If a paragraph is accurate (correctly describes the code) and not outdated (code hasn't changed in a way that contradicts it), leave it alone. Rewriting for style, phrasing, or "cleaner" expression is always wrong — a smaller diff beats a prettier paragraph. The burden of proof is on rewriting, not on preserving.
🔴 匹配度≥80%时默认保留。若段落准确（正确描述代码）且未过期（代码变更未与之矛盾），则保留原样。为了风格、措辞或"更简洁"的表达而重写始终是错误的——更小的差异优于更漂亮的段落。重写的举证责任在你，而非保留。

Bug-Level Violations (Anti-Patterns + Hard Rules)

严重违规（反模式+硬性规则）

Treat the following as bugs, not stylistic choices:
ViolationWhy it's wrong
Starting from the module template when patching an existing docCreates massive diff for no reason; contradicts "read the baseline first"
Full regeneration when function signature is unchangedInternal implementation change ≠ doc invalidation
Rewriting a paragraph that remains accurateAccurate = leave alone; "improving" wording yields diff noise
Rewriting code examples whose code has not changedEven correct examples get rephrased
Regenerating a Mermaid diagram whose source has not changedDiagram was fine before
Reordering sectionsChanges diff noise, no factual benefit
Rephrasing the file structure treeOnly update when structure changed
Writing to an existing doc without reading it firstYou can't preserve what you haven't read
将以下情况视为错误，而非风格选择：
违规行为错误原因
补丁现有文档时从模块模板开始无理由产生大量差异；违反"先读取基线"规则
函数签名未变更时完整重新生成文档内部实现变更≠文档失效
重写仍然准确的段落准确=保留；"改进"措辞会产生差异噪声
重写未变更代码的示例即使正确的示例也被改写
重新生成未变更源代码的Mermaid图表图表原本没问题
重新排序章节产生差异噪声，无实际益处
改写文件结构树仅在结构变更时更新
未读取现有文档就写入内容无法保留未读取的内容

Output Structure

输出结构

🔴 MANDATORY: Domain-Based Directory Hierarchy (No Flat Layout!)

🔴 强制要求：基于领域的目录层级（禁止扁平布局！）

Organize by business domain, not flat modules/ directory.
Directory naming rule: All wiki directory names MUST use lowercase + hyphens (kebab-case), e.g. 
core/
, 
language-handlers/
, 
utils/
. Never use PascalCase or camelCase.
.nium-wiki/
├── config.json
├── meta.json
├── cache/
├── wiki/                              # Primary language docs
│   ├── index.md                    # Project homepage
│   ├── architecture.md             # System architecture
│   ├── getting-started.md          # Quick start
│   ├── doc-map.md                  # Document relationship map
│   │
│   ├── <Domain-1>/                 # Business domain 1
│   │   ├── _index.md              # Domain overview
│   │   ├── <Sub-domain>/          # Sub-domain
│   │   │   ├── _index.md
│   │   │   └── <module>.md        # 400+ lines
│   │   └── ...
│   │
│   ├── <Domain-2>/                 # Business domain 2
│   │   └── ...
│   │
│   └── api/                        # API reference
├── wiki_en/                           # Secondary language (if configured)
│   ├── index.md                    # Same structure as wiki/
│   ├── architecture.md
│   └── ...
按业务领域组织，而非扁平的modules/目录。
目录命名规则：所有wiki目录名称必须使用小写+连字符（kebab-case），例如
core/
、
language-handlers/
、
utils/
。禁止使用PascalCase或camelCase。
.nium-wiki/
├── config.json
├── meta.json
├── cache/
├── wiki/                              # 主要语言文档
│   ├── index.md                    # 项目首页
│   ├── architecture.md             # 系统架构
│   ├── getting-started.md          # 快速入门
│   ├── doc-map.md                  # 文档关系图
│   │
│   ├── <Domain-1>/                 # 业务领域1
│   │   ├── _index.md              # 领域概述
│   │   ├── <Sub-domain>/          # 子领域
│   │   │   ├── _index.md
│   │   │   └── <module>.md        # ≥400行
│   │   └── ...
│   │
│   ├── <Domain-2>/                 # 业务领域2
│   │   └── ...
│   │
│   └── api/                        # API参考
├── wiki_en/                           # 次要语言（若配置）
│   ├── index.md                    # 与wiki/结构完全相同
│   ├── architecture.md
│   └── ...

Automatic Domain Discovery

自动领域发现

Infer business domains from the project's directory structure, package boundaries, and import graph. Group modules that share a cohesive responsibility into the same domain directory. Each domain MUST contain:
FileDescription
_index.md
Domain overview, architecture diagram, sub-module list
Sub-domain dirsRelated modules grouped by function
Each documentDepth scales with module role — see Complexity-Scaled Quality Targets
从项目的目录结构、包边界和导入图推断业务领域。将具有内聚职责的模块分组到同一个领域目录中。每个领域必须包含：
文件描述
_index.md
领域概述、架构图、子模块列表
子领域目录按功能分组的相关模块
每个文档深度随模块角色调整——参见「按复杂度分级的质量目标」

Progressive Scanning for Large Projects

大型项目的渐进式扫描

When module count > 10, source files > 50, or LOC > 10,000, switch to Progressive Scanning:
  1. Prioritize modules — entry points (weight 5) > dependents (4) > has docs (3) > code size (2) > recently modified (1)
  2. Generate 1-2 modules per batch — depth scales with complexity
  3. Track progress in 
    cache/progress.json
    — record completed/pending modules and current batch number
  4. After each batch — run 
    cd <skill-root> && node scripts/index.cjs audit-docs <wiki-path> --verbose --mermaid-strict
    , report results to user, then prompt: 
    • "continue"
      — next batch
    • "audit docs"
      — re-run validation
    • "regenerate <module>"
      — redo a specific module
    • If 
      --mermaid-strict
      reports errors: fix them before continuing — Mermaid syntax errors degrade the diagram catalog silently and accumulate technical debt.
  5. Resume — when user says "continue wiki generation", read 
    cache/progress.json
    and pick up where you left off
当模块数>10、源文件数>50或代码行数>10,000时，切换为渐进式扫描：
  1. 模块优先级——入口点（权重5）> 被依赖模块（4）> 已有文档（3）> 代码规模（2）> 最近修改（1）
  2. 每批生成1-2个模块——深度随复杂度调整
  3. 在
    cache/progress.json
    中跟踪进度——记录已完成/待完成的模块及当前批次号
  4. 每批完成后——运行
    cd <skill-root> && node scripts/index.cjs audit-docs <wiki-path> --verbose --mermaid-strict
    ，向用户报告结果，然后提示： 
    • "continue"
      ——下一批
    • "audit docs"
      ——重新运行验证
    • "regenerate <module>"
      ——重新生成特定模块
    • 若
      --mermaid-strict
      报告错误：修复后再继续——Mermaid语法错误会悄然降低图表质量并积累技术债务。
  5. 恢复——当用户说"continue wiki generation"时，读取
    cache/progress.json
    并从上次中断处继续

Documentation Upgrade & Maintenance

文档升级与维护

When existing wiki docs are outdated or below quality gate, use one of these strategies:
StrategyWhen to UseUser Command
full_refresh
Large version gap or poor overall quality"refresh all wiki"
incremental_upgrade
Many modules, want to keep existing content"upgrade wiki"
targeted_upgrade
Only specific modules need attention"upgrade <module> docs"
Execution: scan existing docs with 
cd <skill-root> && node scripts/index.cjs audit-docs <wiki-path> --mermaid-strict
, generate an upgrade report, then re-generate failing docs batch by batch. Always include 
--mermaid-strict
 so that Mermaid syntax errors block the upgrade and prevent bad diagrams from entering the wiki.
Version footer — append to every generated document: 
*Generated by [Nium-Wiki v{{ NIUM_WIKI_VERSION }}](https://github.com/niuma996/nium-wiki) | {{ GENERATED_AT }}*
当现有wiki文档过期或未达到质量门槛时，使用以下策略之一：
策略使用场景用户命令
full_refresh
版本差距大或整体质量差"refresh all wiki"
incremental_upgrade
模块多，想要保留现有内容"upgrade wiki"
targeted_upgrade
仅特定模块需要关注"upgrade <module> docs"
执行流程：使用
cd <skill-root> && node scripts/index.cjs audit-docs <wiki-path> --mermaid-strict
扫描现有文档，生成升级报告，然后分批重新生成不合格的文档。始终包含
--mermaid-strict
，以便Mermaid语法错误阻止升级，防止不良图表进入wiki。
版本页脚——添加到每个生成的文档末尾： 
*Generated by [Nium-Wiki v{{ NIUM_WIKI_VERSION }}](https://github.com/niuma996/nium-wiki) | {{ GENERATED_AT }}*

Finalization Checklist (MANDATORY — Run After Every Generation)

最终检查清单（强制要求——每次生成后运行）

Applies after every wiki generation: full pipeline, module-targeted, incremental, or surgical patch. This checklist is the last step of every execution path. Do not skip any item.
  • cd <skill-root> && node scripts/index.cjs generate-sidebar <wiki-path> --all
    → Generates 
    sidebar.json
    for all language directories. Idempotent — safe to run multiple times. → Migrates legacy 
    _sidebar.md
    to 
    sidebar.json
    automatically if encountered. → ⚠️ Do NOT skip: the preview server and modern tooling depend on 
    sidebar.json
    .
  • cd <skill-root> && node scripts/index.cjs i18n sync-memory <wiki-path>
    (if multi-language) → Updates translation memory so subsequent runs show accurate sync status.
  • cd <skill-root> && node scripts/index.cjs audit-docs <wiki-path> --mermaid-strict
    (full generation only) → Validates all Mermaid diagrams. Mermaid errors block the run — fix them before declaring done.
Rule: These finalization steps must run after all wiki content is written and after all translation files are updated. They are not optional cleanup — they are part of the generation contract. (read version from 
scripts/version.json
— 
version
field)
适用于每次wiki生成：完整流水线、模块定向、增量或精准补丁。 此清单是每个执行路径的最后一步。请勿跳过任何项。
  • cd <skill-root> && node scripts/index.cjs generate-sidebar <wiki-path> --all
    → 为所有语言目录生成
    sidebar.json
    。幂等——可安全多次运行。 → 若遇到旧版
    _sidebar.md
    会自动迁移为
    sidebar.json
    。 → ⚠️ 请勿跳过：预览服务器和现代工具依赖
    sidebar.json
    。
  • cd <skill-root> && node scripts/index.cjs i18n sync-memory <wiki-path>
    （多语言时） → 更新翻译记忆，以便后续运行显示准确的同步状态。
  • cd <skill-root> && node scripts/index.cjs audit-docs <wiki-path> --mermaid-strict
    （仅完整生成时） → 验证所有Mermaid图表。Mermaid错误会阻止运行——修复后再宣布完成。
规则：这些最终步骤必须在所有wiki内容写入后、所有翻译文件更新后运行。它们不是可选的清理步骤——而是生成契约的一部分。 (版本从
scripts/version.json
的
version
字段读取)