Back to Details

linkify

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Linkify Entity

实体自动链接工具（Linkify Entity）

Linkify: $ARGUMENTS
Linkify: $ARGUMENTS

Overview

概述

This skill scans an entity file and automatically wraps any mentions of existing entities in 
[[wikilink]]
syntax. It's a focused tool that only adds links to entities that already exist—it does NOT create new entities.
该工具会扫描实体文件，并自动将所有提及现有实体的内容用
[[wikilink]]
语法包裹。这是一款针对性工具，仅为已存在的实体添加链接——不会创建新实体。

Quick Start

快速开始

bash
undefined
bash
undefined

Linkify a specific entity

为特定实体添加链接

/linkify "Aldersgate"
/linkify "Aldersgate"

Preview changes without modifying

预览更改而不修改文件

/linkify "Aldersgate" --dry-run
/linkify "Aldersgate" --dry-run

Linkify by file path

通过文件路径添加链接

/linkify Worlds/Eldermyr/Settlements/Aldersgate.md
/linkify Worlds/Eldermyr/Settlements/Aldersgate.md

BULK: Linkify all entities in a world

批量操作：为整个世界中的所有实体添加链接

/linkify --world Eldermyr
/linkify --world Eldermyr

BULK: Linkify only Characters in a world

批量操作：仅为世界中的「角色」分类实体添加链接

/linkify --world Eldermyr --category Characters
/linkify --world Eldermyr --category Characters

BULK: Preview bulk changes

批量操作：预览批量更改

/linkify --world Eldermyr --dry-run
undefined
/linkify --world Eldermyr --dry-run
undefined

Instructions

操作步骤

Step 1: Parse Arguments

步骤1：解析参数

Required:
  • Entity path or name
Optional Flags:
FlagPurposeDefault
--dry-run
Show what would be linked without making changesfalse
--all-worlds
Search all worlds for entities, not just the source entity's worldfalse
--case-sensitive
Require exact case matchingfalse
--world [name]
BULK MODE: Process all entities in the specified world-
--category [type]
With 
--world
: only process entities in this category (Characters, Settlements, etc.)		all
必填项：
  • 实体路径或名称
可选标志：
标志用途默认值
--dry-run
显示将添加的链接，但不实际修改文件false
--all-worlds
在所有世界中搜索实体，而非仅源实体所在的世界false
--case-sensitive
要求完全匹配大小写false
--world [name]
批量模式： 处理指定世界中的所有实体-
--category [type]
搭配
--world
使用：仅处理该分类下的实体（如角色、定居点等）		全部

Step 2: Locate Entity & Determine World

步骤2：定位实体并确定所属世界

  1. If path provided (contains 
    /
    or 
    .md
    ):
    • Read the file directly
    • Extract world name from path: 
      Worlds/[World Name]/...
  2. If name provided:
    • Search 
      Worlds/
      directories for matching entity
    • Try exact filename match first
    • Then fuzzy match on filename and YAML 
      name:
      field
    • If multiple matches, list them and ask user to clarify
  3. If not found:
    • List similar entities and ask for clarification
  1. 若提供路径（包含
    /
    或
    .md
    ）：
    • 直接读取该文件
    • 从路径中提取世界名称：
      Worlds/[世界名称]/...
  2. 若提供名称：
    • 在
      Worlds/
      目录中搜索匹配的实体
    • 优先尝试完全匹配文件名
    • 再对文件名和YAML中的
      name:
      字段进行模糊匹配
    • 若存在多个匹配项，列出所有选项并请用户确认
  3. 若未找到实体：
    • 列出相似实体并请用户明确需求

Step 3: Build Entity Index

步骤3：构建实体索引

Create a complete index of existing entities:
  1. Scan all files in 
    Worlds/[World Name]/
    recursively (or all worlds if 
    --all-worlds
    )
  2. For each entity file, extract:
    • Filename (without .md extension) → primary name
    • YAML 
      name:
      field → canonical name
    • YAML 
      aliases:
      array → alternative names
  3. Build lookup dictionary (case-insensitive by default):
{
  "Lord Varic Valdren": { path: "Characters/Lord Varic Valdren.md", canonical: "Lord Varic Valdren" },
  "Varic": { path: "Characters/Lord Varic Valdren.md", canonical: "Lord Varic Valdren" },
  "The Merchant Lord": { path: "Characters/Lord Varic Valdren.md", canonical: "Lord Varic Valdren" },
  ...
}
Important: Sort the lookup dictionary by name length (longest first) to ensure longer matches are found before shorter partial matches.
创建现有实体的完整索引：
  1. 递归扫描
    Worlds/[世界名称]/
    中的所有文件（若启用
    --all-worlds
    则扫描所有世界）
  2. 为每个实体文件提取以下内容：
    • 文件名（不含.md后缀）→ 主名称
    • YAML中的
      name:
      字段 → 标准名称
    • YAML中的
      aliases:
      数组 → 别名
  3. 构建查询字典（默认不区分大小写）：
{
  "Lord Varic Valdren": { path: "Characters/Lord Varic Valdren.md", canonical: "Lord Varic Valdren" },
  "Varic": { path: "Characters/Lord Varic Valdren.md", canonical: "Lord Varic Valdren" },
  "The Merchant Lord": { path: "Characters/Lord Varic Valdren.md", canonical: "Lord Varic Valdren" },
  ...
}
重要提示： 按名称长度对查询字典排序（长名称优先），确保先匹配长名称，再匹配短的部分匹配项。

Step 4: Identify Content to Scan

步骤4：确定需扫描的内容

Read the source entity file and identify sections to scan:
INCLUDE these sections:
  • Overview
  • Geography
  • History
  • Demographics
  • Government & Politics
  • Economy
  • Defense & Military
  • Notable Locations
  • Key Figures
  • Secrets
  • Plot Hooks
  • Description
  • Any custom content sections
EXCLUDE these sections:
  • YAML frontmatter (between 
    ---
    markers)
  • Image Prompts section and everything after it
  • Connections section (already has wikilinks)
  • Code blocks (between ``` markers)
  • Existing wikilinks 
    [[...]]
  • Block quotes used for image prompts (lines starting with 
    >
    after 
    **Prompt:**
    )
读取源实体文件并确定需扫描的章节：
包含以下章节：
  • 概述
  • 地理
  • 历史
  • 人口统计
  • 政府与政治
  • 经济
  • 防御与军事
  • 知名地点
  • 关键人物
  • 秘密
  • 剧情钩子
  • 描述
  • 任何自定义内容章节
排除以下章节：
  • YAML前置元数据（位于
    ---
    标记之间）
  • 图像提示章节及其后续内容
  • 关联章节（已包含wikilink链接）
  • 代码块（位于```标记之间）
  • 已有的wikilink链接
    [[...]]
  • 用于图像提示的块引用（
    **Prompt:**
    后以
    >
    开头的行）

Step 5: Find Matches

步骤5：查找匹配项

For each entity name/alias in the index (longest first):
  1. Skip if entity is the source file itself (don't self-link)
  2. Search for the name in content:
    • Use word-boundary matching to avoid partial matches within words
    • Match: "Lord Varic Valdren" in "talked to Lord Varic Valdren about"
    • Skip: "Lord Varic Valdren" in "[[Lord Varic Valdren]]" (already linked)
    • Skip: "Stone" in "Aldric Stone" if "Aldric Stone" is a separate entity
  3. Record each match:
    • Line number
    • Exact text matched
    • Canonical entity name (for the wikilink)
    • Surrounding context (5 words before/after)
  4. Handle partial name matches:
    • If "Lord Varic Valdren" exists but text says "Lord Varic", offer to link as 
      [[Lord Varic Valdren|Lord Varic]]
    • If "House Valdren" exists but text says "the Valdren house", consider display text
遍历索引中的每个实体名称/别名（长名称优先）：
  1. 跳过源文件自身（不添加自链接）
  2. 在内容中搜索名称：
    • 使用单词边界匹配，避免匹配单词内的部分字符
    • 匹配示例：文本中的"Lord Varic Valdren"与实体名称完全匹配
    • 跳过示例：已包含在
      [[Lord Varic Valdren]]
      中的内容（已添加链接）
    • 跳过示例：若"Aldric Stone"是独立实体，则不匹配文本中的"Stone"
  3. 记录每个匹配项：
    • 行号
    • 匹配的精确文本
    • 实体的标准名称（用于生成wikilink）
    • 上下文（前后5个单词）
  4. 处理部分名称匹配：
    • 若文本中出现实体名称的简写形式，例如存在实体"Lord Varic Valdren"但文本中是"Lord Varic"，则生成
      [[Lord Varic Valdren|Lord Varic]]
      形式的链接
    • 若存在实体"House Valdren"但文本中是"the Valdren house"，则考虑使用显示文本

Step 6: Present Findings

步骤6：展示分析结果

=== LINKIFY ANALYSIS: [Entity Name] ===

World: [World Name]
Source: [path/to/entity.md]
Entities Indexed: X

---

MATCHES FOUND: Y

| # | Text Found | Line | Links To | Context |
|---|------------|------|----------|---------|
| 1 | Lady Serana Valdren | 121 | [[Lady Serana Valdren]] | "...wife, manages court..." |
| 2 | High Confessor Maren | 136 | [[High Confessor Maren]] | "...supporters, seeking..." |
| 3 | Sister Elspeth | 204 | [[Sister Elspeth]] | "...Abbess of the..." |
| 4 | Lord Varic | 117 | [[Lord Varic Valdren|Lord Varic]] | "...ensuring Varic holds..." |

---

PARTIAL MATCHES (display text needed):

| # | Text Found | Line | Suggested Link |
|---|------------|------|----------------|
| 1 | "the Owl" | 123 | [[The Owl|the Owl]] |
| 2 | "young Edric" | 117, 177 | [[Edric Valdren|young Edric]] |

---

AMBIGUOUS (multiple possible matches):

| # | Text Found | Line | Could Match |
|---|------------|------|-------------|
| 1 | "Edric" | 177 | [[Edric Valdren]] or [[Prince Edric the Liberator]] |

---

SUMMARY:
- Exact matches: X
- Partial matches: X
- Ambiguous: X
- Total changes: X

Options:
1. Apply all exact matches
2. Apply exact + partial matches
3. Review each individually
4. Dry run complete (--dry-run flag)
If 
--dry-run
flag is set, show report and stop.
=== 链接分析结果：[实体名称] ===

所属世界：[世界名称]
源文件：[path/to/entity.md]
已索引实体数量：X

---

找到匹配项：Y

| 序号 | 匹配文本 | 行号 | 链接指向 | 上下文 |
|---|------------|------|----------|---------|
| 1 | Lady Serana Valdren | 121 | [[Lady Serana Valdren]] | "...wife, manages court..." |
| 2 | High Confessor Maren | 136 | [[High Confessor Maren]] | "...supporters, seeking..." |
| 3 | Sister Elspeth | 204 | [[Sister Elspeth]] | "...Abbess of the..." |
| 4 | Lord Varic | 117 | [[Lord Varic Valdren|Lord Varic]] | "...ensuring Varic holds..." |

---

部分匹配项（需指定显示文本）：

| 序号 | 匹配文本 | 行号 | 建议链接 |
|---|------------|------|----------------|
| 1 | "the Owl" | 123 | [[The Owl|the Owl]] |
| 2 | "young Edric" | 117, 177 | [[Edric Valdren|young Edric]] |

---

模糊匹配项（存在多个可能的匹配实体）：

| 序号 | 匹配文本 | 行号 | 可能匹配的实体 |
|---|------------|------|-------------|
| 1 | "Edric" | 177 | [[Edric Valdren]] 或 [[Prince Edric the Liberator]] |

---

摘要：
- 精确匹配项：X
- 部分匹配项：X
- 模糊匹配项：X
- 总更改数：X

操作选项：
1. 应用所有精确匹配项
2. 应用精确匹配项+部分匹配项
3. 逐个确认每个匹配项
4. 预览完成（已启用--dry-run标志）
若启用
--dry-run
标志，仅展示报告而不修改文件。

Step 7: Apply Changes

步骤7：应用更改

For each approved match:
  1. Build replacement text:
    • Exact match: 
      EntityName
      → 
      [[EntityName]]
    • Partial match: 
      PartialName
      → 
      [[FullEntityName|PartialName]]
  2. Apply using Edit tool:
    • Process from bottom of file to top (so line numbers don't shift)
    • Use precise string replacement with surrounding context for uniqueness
    • Verify each replacement succeeded
  3. Handle duplicates:
    • If the same entity is mentioned multiple times, link ALL occurrences
    • Exception: Don't link the same name twice in the same sentence
对每个已确认的匹配项：
  1. 生成替换文本：
    • 精确匹配：
      实体名称
      → 
      [[实体名称]]
    • 部分匹配：
      部分名称
      → 
      [[完整实体名称|部分名称]]
  2. 使用编辑工具应用更改：
    • 从文件底部向上处理（避免行号偏移）
    • 结合上下文进行精确字符串替换，确保唯一性
    • 验证每个替换操作是否成功
  3. 处理重复提及：
    • 若同一实体被多次提及，为所有实例添加链接
    • 例外：同一句子中不重复链接同一名称

Step 8: Validation

步骤8：验证

After applying changes:
  1. Re-read the file
  2. Verify all intended wikilinks are present
  3. Check no content was accidentally corrupted
  4. Verify wikilinks point to existing files
应用更改后：
  1. 重新读取文件
  2. 验证所有预期的wikilink已添加
  3. 检查是否意外损坏了内容
  4. 验证wikilink均指向已存在的文件

Step 9: Summary Report

步骤9：生成摘要报告

=== LINKIFY COMPLETE: [Entity Name] ===

Changes Applied: X

Links Added:
- [[Lady Serana Valdren]] (line 121)
- [[High Confessor Maren]] (line 136)
- [[Sister Elspeth]] (lines 204, 252)
- [[Lord Varic Valdren|Lord Varic]] (line 117)

Skipped (ambiguous):
- "Edric" (line 177) - multiple matches possible

---

File Updated: [path/to/entity.md]

Suggested Next Steps:
- Review ambiguous matches manually
- Run /audit-world to check bidirectional links
- Use /link-entities to add reciprocal connections
=== 链接添加完成：[实体名称] ===

已应用更改数：X

已添加的链接：
- [[Lady Serana Valdren]]（第121行）
- [[High Confessor Maren]]（第136行）
- [[Sister Elspeth]]（第204、252行）
- [[Lord Varic Valdren|Lord Varic]]（第117行）

已跳过的模糊匹配项：
- "Edric"（第177行）- 存在多个可能的匹配实体

---

已更新文件：[path/to/entity.md]

后续建议：
- 手动检查模糊匹配项
- 运行/audit-world检查双向链接
- 使用/link-entities添加反向关联

Matching Rules

匹配规则

Word Boundary Matching

单词边界匹配

Only match complete words/phrases:
TextEntityMatch?Reason
"spoke to Lord Varic Valdren about"Lord Varic ValdrenYesComplete phrase
"the Valdren family"House ValdrenNo"Valdren" alone, different entity
"visited Aldersgate"AldersgateYesComplete word
"Aldersgates"AldersgateNoDifferent word
"[[Lord Varic Valdren]]"Lord Varic ValdrenNoAlready linked
仅匹配完整的单词/短语：
文本实体是否匹配？原因
"spoke to Lord Varic Valdren about"Lord Varic Valdren是完整短语匹配
"the Valdren family"House Valdren否"Valdren"单独出现，对应不同实体
"visited Aldersgate"Aldersgate是完整单词匹配
"Aldersgates"Aldersgate否单词不同
"[[Lord Varic Valdren]]"Lord Varic Valdren否已添加链接

Partial Name Handling

部分名称处理

When text contains a shorter form of an entity name:
TextEntityLink Format
"Lord Varic said"Lord Varic Valdren`[[Lord Varic Valdren
"the Owl knows"The Owl`[[The Owl
"young Edric"Edric Valdren`[[Edric Valdren
当文本中出现实体名称的简写形式时：
文本实体链接格式
"Lord Varic said"Lord Varic Valdren`[[Lord Varic Valdren
"the Owl knows"The Owl`[[The Owl
"young Edric"Edric Valdren`[[Edric Valdren

Case Handling

大小写处理

By default (case-insensitive):
  • "lord varic valdren" matches "Lord Varic Valdren"
  • Original case is preserved in display text
With 
--case-sensitive
:
  • Only exact case matches
默认（不区分大小写）：
  • "lord varic valdren"匹配"Lord Varic Valdren"
  • 保留原文本的大小写作为显示文本
启用
--case-sensitive
时：
  • 仅匹配完全一致的大小写

Exclusion Patterns

排除规则

Never link:
  • Text inside existing 
    [[wikilinks]]
  • Text in YAML frontmatter
  • Text in code blocks
  • Text in Image Prompts section
  • The entity's own name (no self-linking)
  • Text that's part of a markdown header (
    # Name
    )
  • Text in the Connections section (manage links there separately)
以下内容不会添加链接：
  • 已包含在
    [[wikilinks]]
    中的文本
  • YAML前置元数据中的文本
  • 代码块中的文本
  • 图像提示章节中的文本
  • 实体自身的名称（不添加自链接）
  • Markdown标题中的文本（如
    # 名称
    ）
  • 关联章节中的文本（单独管理该章节的链接）

Bulk Processing Mode

批量处理模式

When 
--world
flag is provided, the skill processes multiple entities:
当使用
--world
标志时，工具会处理多个实体：

Bulk Mode Workflow

批量模式工作流程

  1. Scan world directory:
    • List all 
      .md
      files in 
      Worlds/[World Name]/
    • If 
      --category
      specified, only scan that folder (e.g., 
      Characters/
      )
    • Exclude 
      World Overview.md
      by default (use 
      --include-overview
      to include)
  2. Build combined entity index:
    • Same process as single-entity mode
    • Index is built once and reused for all files
  3. Process each entity:
    • For each file, run Steps 4-7 (Find Matches → Apply Changes)
    • Track cumulative statistics
  4. Batch report:
    === BULK LINKIFY COMPLETE: [World Name] ===

Files Processed: X
Files Modified: Y
Files Unchanged: Z

Total Links Added: N

By Category:
- Characters: X files, Y links
- Settlements: X files, Y links
- Organizations: X files, Y links
...

Skipped (ambiguous): N references across M files

Performance: X.X seconds total
  1. 扫描世界目录：
    • 列出
      Worlds/[世界名称]/
      中的所有
      .md
      文件
    • 若指定
      --category
      ，仅扫描该文件夹（如
      Characters/
      ）
    • 默认排除
      World Overview.md
      （可使用
      --include-overview
      包含该文件）
  2. 构建合并实体索引：
    • 与单实体模式流程相同
    • 索引仅构建一次，复用至所有文件
  3. 处理每个实体：
    • 对每个文件执行步骤4-7（查找匹配项→应用更改）
    • 跟踪累计统计数据
  4. 生成批量报告：
    === 批量链接添加完成：[世界名称] ===

已处理文件数：X
已修改文件数：Y
未更改文件数：Z

总添加链接数：N

按分类统计：
- 角色：X个文件，Y个链接
- 定居点：X个文件，Y个链接
- 组织：X个文件，Y个链接
...

已跳过的模糊匹配项：N处引用，涉及M个文件

性能：总计X.X秒

Bulk Mode Options

批量模式选项

bash
undefined
bash
undefined

Process entire world

处理整个世界

/linkify --world Eldermyr
/linkify --world Eldermyr

Process only one category

仅处理单个分类

/linkify --world Eldermyr --category Settlements
/linkify --world Eldermyr --category Settlements

Dry run to preview bulk changes

预览批量更改

/linkify --world Eldermyr --dry-run
/linkify --world Eldermyr --dry-run

Process multiple categories

处理多个分类

/linkify --world Eldermyr --category Characters --category Organizations
undefined
/linkify --world Eldermyr --category Characters --category Organizations
undefined

Performance Notes

性能说明

For large worlds (100+ entities), bulk mode:
  • Builds the entity index once (faster than per-file)
  • Processes files in parallel where possible
  • Reports progress every 10 files
  • For very large worlds (300+), consider using 
    scripts/linkify_world.py
    instead
对于大型世界（100+实体），批量模式：
  • 仅构建一次实体索引（比单文件模式更快）
  • 尽可能并行处理文件
  • 每处理10个文件报告一次进度
  • 对于超大型世界（300+实体），建议使用
    scripts/linkify_world.py
    替代

Examples

示例

bash
undefined
bash
undefined

Basic linkify

基础添加链接操作

/linkify "Aldersgate"
/linkify "Aldersgate"

Preview what would be linked

预览将添加的链接

/linkify "Aldersgate" --dry-run
/linkify "Aldersgate" --dry-run

Linkify checking all worlds for entities

在所有世界中搜索实体并添加链接

/linkify "Aldersgate" --all-worlds
/linkify "Aldersgate" --all-worlds

Linkify by path

通过路径添加链接

/linkify Worlds/Eldermyr/Settlements/Aldersgate.md
/linkify Worlds/Eldermyr/Settlements/Aldersgate.md

Case-sensitive matching

区分大小写的匹配

/linkify "Lord Varic Valdren" --case-sensitive
undefined
/linkify "Lord Varic Valdren" --case-sensitive
undefined

Integration with Other Skills

与其他工具的集成

After 
/create-entity

在
/create-entity
之后

Run 
/linkify
on newly created entities to link any mentioned existing entities.
对新创建的实体运行
/linkify
，为其中提及的现有实体添加链接。

Before 
/audit-world

在
/audit-world
之前

Run 
/linkify
on key entities to add missing links before the audit.
对关键实体运行
/linkify
，补全缺失的链接后再执行审计。

With 
/link-entities

与
/link-entities
配合使用

  • /linkify
    adds wikilinks within entity content
  • /link-entities
    manages the Connections section relationships
  • Use together for comprehensive linking
  • /linkify
    在实体内容中添加wikilink链接
  • /link-entities
    管理关联章节中的关系
  • 两者配合使用可实现全面的链接管理

With 
/populate-entity

与
/populate-entity
配合使用

  • /linkify
    only links to EXISTING entities
  • /populate-entity --links-only
    does the same thing
  • /populate-entity
    (full) also CREATES missing entities
  • Use 
    /linkify
    when you just want to add links without creating anything
  • /linkify
    仅为已存在的实体添加链接
  • /populate-entity --links-only
    功能相同
  • 完整的
    /populate-entity
    还会创建缺失的实体
  • 若仅需添加链接而不创建实体，使用
    /linkify

Error Handling

错误处理

File not found:
Error: Could not find entity "[name]"
Similar entities in Worlds/:
- [similar1]
- [similar2]
Please specify the full path or exact name.
No matches found:
=== LINKIFY: [Entity Name] ===

No unlinked entity references found.

This file either:
- Already has all entities properly linked
- Contains no references to other known entities
- References entities that don't exist yet (use /populate-entity to create them)
Write permission error:
Error: Could not write to [path]
The dry-run showed X matches. Please check file permissions.
文件未找到：
错误：未找到实体「[名称]」
Worlds/中的相似实体：
- [相似实体1]
- [相似实体2]
请提供完整路径或精确名称。
未找到匹配项：
=== 实体链接添加：[实体名称] ===

未找到未链接的实体引用。

可能的原因：
- 文件中所有实体已正确添加链接
- 文件中未提及任何已知实体
- 文件中提及的实体尚未创建（可使用/populate-entity创建）
写入权限错误：
错误：无法写入文件[路径]
预览显示将添加X个链接，请检查文件权限。