storage-zk

个人 Wiki：使用 wiki CLI

快速入门：wiki CLI

wiki CLI 会智能发现你的笔记本路径。

wiki new --title "My Note"
wiki list --match="pattern"
wiki list --format=json | jq .

使用已发现的笔记本（在内部自动发现路径）

使用 wiki CLI 的常见工作流

单条笔记：创建 → 链接 → 搜索 → 导出

# 1. Create new note (auto-discovers notebook)
NOTE_PATH=$(wiki new --title "Research Topic" --print-path)
# 2. Edit file and add links (manual)
echo -e "\n\nRelated: [existing-note-id](Existing Note Title)" >> "$NOTE_PATH"
# 3. Search for related notes
wiki list --match="Research" --format=long
# 4. Export results
wiki list --match="Research" --format=json | jq .

将项目注册到笔记本

# Register current project with notebook (for context matching)
wiki project add

导出项目中的所有笔记

# Get notebook, then export
NOTEBOOK=$(wiki project discover)
wiki list --format=json > all-notes.json
# Validate export
jq . < all-notes.json > /dev/null && echo "Valid JSON"

适用场景

症状：

• 需要以各种格式导出笔记
• 希望自动建立项目与笔记本的映射
• 同时处理多个项目和笔记本 不适用场景：
• 编辑笔记本配置（请参阅 zk 文档中的 config.toml）
• 高级模板（模板使用 Handlebars，请参阅 zk 文档）
• 配置 LSP（语言服务器集成，使用单独的配置）

wiki 与直接使用 zk 命令

场景	使用方式	示例
自动发现笔记本	wiki CLI	wiki new --title "Note"（自动发现）
明确控制笔记本	直接使用 zk	zk list -W /path --match="x"（明确控制）
注册项目上下文	wiki project add	帮助今后发现此项目的笔记本

快速参考：wiki CLI 命令

任务	命令	说明
创建笔记	wiki new --title "Title" --print-path	自动发现笔记本；返回路径
列出所有笔记	wiki list	默认使用表格格式
搜索模式	wiki list --match="pattern"	正则表达式或纯文本
导出 JSON	wiki list --format=json > file.json	使用重定向输出
导出 CSV	wiki list --format=csv > file.csv	符合 RFC 4180；请使用 CSV 解析器
导出单行格式	wiki list --format=oneline > file.txt	格式精简，便于解析
查找反向链接	wiki list --linked-by=<note-id>	显示链接到目标笔记的笔记
显示笔记详情	wiki list --match=<note-id> --format=long	包含元数据和预览

快速参考：直接使用 zk 命令（需要明确控制时）

任务	命令	说明
创建笔记	zk new -W <dir> --title "Title" --print-path	必须明确指定笔记本路径
列出所有笔记	zk list -W <dir>	始终包含 -W 标志
搜索模式	zk list -W <dir> --match="pattern"	正则表达式或纯文本
导出 JSON	zk list -W <dir> --format=json > file.json	使用重定向输出
导出 CSV	zk list -W <dir> --format=csv > file.csv	符合 RFC 4180；请使用 CSV 解析器
查找反向链接	zk list -W <dir> --linked-by=<note-id>	显示链接到目标笔记的笔记

筛选选项

筛选条件	语法	示例	说明
标题/正文	--match="pattern"	zk list -W /nb --match="daily"	正则表达式或纯文本搜索
链接来源	--linked-by=<id>	zk list -W /nb --linked-by=abc123	显示链接到 abc123 的笔记
其他筛选条件	查看 zk list --help	zk list --help | grep -i filter	ZK 可能还有未列出的筛选条件
**重要：**对于此处未列出的筛选方式，在假设其语法前，请务必先通过 zk list --help 确认。ZK 可能会在较新版本中添加新的筛选条件。

了解笔记本发现机制

wiki CLI 使用智能搜索算法自动处理笔记本发现。无需手动指定 -W 标志。

wiki 如何发现你的笔记本

运行任何 wiki 命令时，它会按以下顺序搜索：

1. 环境变量 NOTEBOOK_PATH（如果已明确设置）
2. 上级目录中的 .zk/config.toml（查找项目本地笔记本）
3. ~/Notes/ 中的上下文注册表（将项目路径与已注册的笔记本匹配）
4. 全局回退路径 ~/.config/zk/config.toml（如果其中定义了 notebook.dir） **优点：**无需担心路径是否正确，直接运行 wiki 命令即可。

直接使用 zk 命令：必须显式指定 -W 标志

如果绕过 wiki，直接使用 zk，必须始终包含 -W：

# ❌ DON'T - unsafe, ambiguous which notebook is used
zk list --match="search"
# ✅ DO - explicit notebook path
zk list -W /path/to/notebook --match="search"

如果你位于 ~/projects/project-a/notes/，却在未指定 -W 的情况下运行 zk list，它可能会找到 ~/projects/.zk。

故障排除：确认当前启用的笔记本

# Using wiki (recommended)
wiki project discover
# Returns: /path/to/notebook
# Using direct zk with explicit path
zk info -W /path/to/notebook
# Shows: notebook path, config, note count

链接创建模式

ZK 没有 zk link 命令。创建链接的方式是直接编辑 Markdown 文件：

Wiki 风格链接（最常见）

This note connects to [[other-note-id]] and [[another-one]].

ZK 会自动将这些链接解析为匹配的笔记 ID。ID 可以是去掉扩展名的文件名，也可以是笔记 frontmatter 中的显式 ID 字段。

Markdown 链接（同样有效）

See [related note](/path/to/note.md) for details.

ZK 能识别这两种格式。交叉引用时，优先使用 Wiki 风格的 [[]]。

查找反向链接

查找所有链接到指定笔记的笔记：

zk list -W /notebook --linked-by=target-note-id

导出工作流

**模式：**使用带有 --format 标志的 zk list 命令，并将输出重定向到文件

批量导出前：安全检查清单

批量导出（100 条以上笔记）如果未经验证，可能会有风险：

• 是否已备份笔记本？（cp -r /notebook /notebook.backup）
• 是否先导出测试数据？（先使用 --match="test" 验证格式）
• 是否清楚要导出什么？（链接作为引用？完整正文？元数据？）
• 输出格式是否有效？（使用 head -5 export.json | jq . 测试） 示例：安全的批量导出

# 1. Validate on one note
zk list -W /notebook --match="note-id" --format=json | jq .
# 2. Check structure is what you expect
# (inspect the JSON output)
# 3. Export to temp file first
zk list -W /notebook --format=json > /tmp/export.json
# 4. Validate output is valid JSON
jq . < /tmp/export.json > /dev/null && echo "Valid JSON"
# 5. Move to final location
mv /tmp/export.json ~/exports/notes.json

JSON 导出（程序化处理）

zk list -W /notebook --match="tag:project" --format=json > export.json

输出包含：ID、标题、路径、正文、标签、关系

CSV 导出（导入电子表格）

zk list -W /notebook --format=csv > notes.csv

输出列：标题、路径、修改日期。请使用 CSV 读取器解析，而不是 awk。

单行导出（便于 Grep 搜索）

zk list -W /notebook --format=oneline > index.txt

输出：每条笔记占一行，格式为 id - title - path

常见错误

错误	问题	修复方法
未使用 -W 标志运行 zk	无法确定使用的是哪个笔记本	使用 wiki CLI（自动发现）或显式指定 -W /path
zk export	不存在导出命令	使用 wiki list --format=X > file（或 zk list -W <dir>...）
zk link note1 note2	不存在链接命令	编辑 Markdown 文件，手动添加 [[note-id]]
wiki list --match="x" 失败	未发现笔记本	运行 wiki project discover 以确认路径
--format json（未重定向）	输出会打印到标准输出，而非文件	使用 > file.json 捕获输出
使用 [[filepath]] 而不是 [[id]]	Wiki 链接使用 ID，而不是路径	使用笔记 ID 或去掉扩展名的文件名
假设链接由 CLI 创建	链接需要手动编辑	始终直接编辑笔记文件来添加链接
在脚本中硬编码笔记本路径	项目移动后会失效	改用 wiki CLI 或 wiki project discover

参考：输出格式

表格（默认）

id | title | path

长格式（包含元数据）

id: xxx
title: My Note
path: /notebook/notes/xxx.md
links: [[id1]], [[id2]]

JSON（用于程序化解析）

[{"id":"xxx","title":"My Note","tags":["tag1"],"path":"/notebook/notes/xxx.md"}]

CSV（导入电子表格）——符合 RFC 4180

**格式：**字段带引号、以逗号分隔，包含标题行

title,path,modified
"My Note",/notebook/notes/xxx.md,2025-01-15
"Note with, comma",/notebook/notes/yyy.md,2025-01-14

**重要：**请使用正规的 CSV 解析器解析 CSV，而不是 awk -F','，因为标题中可能包含逗号。以下是使用 Python 的示例：

import csv
with open('notes.csv') as f:
    for row in csv.DictReader(f):
        print(row['title'], row['path'])

单行格式（便于 Grep 搜索）

xxx - My Note - /notebook/notes/xxx.md

工作流示例

单条笔记：创建 → 链接 → 搜索 → 导出（使用 wiki CLI）

# 1. Create new note (notebook auto-discovered)
NOTE_PATH=$(wiki new --title "Research Topic" --print-path)
# 2. Edit file and add links (manual)
echo -e "\n\nRelated: [[existing-note-id]]" >> "$NOTE_PATH"
# 3. Search for related notes
wiki list --match="Research" --format=long
# 4. Export results
wiki list --match="Research" --linked-by="research-topic-id" --format=json > related-notes.json

**优点：**无需手动查找笔记本路径，wiki 会自动处理。

单条笔记：直接使用 zk（需要显式控制时）

# 1. Create new note with explicit notebook path
NOTEBOOK="/path/to/notebook"
NOTE_PATH=$(zk new -W "$NOTEBOOK" --title "Research Topic" --print-path)
# 2. Edit file and add links (manual)
echo -e "\n\nRelated: [[existing-note-id]]" >> "$NOTE_PATH"
# 3. Search for related notes
zk list -W "$NOTEBOOK" --match="Research" --format=long
# 4. Export results
zk list -W "$NOTEBOOK" --match="Research" --linked-by="research-topic-id" --format=json > related-notes.json

**注意：**步骤 2 需要手动编辑文件。没有 CLI 命令可以创建链接；你需要将链接添加到 Markdown 内容中。

批量操作：创建多条笔记并链接到主笔记（使用 wiki）

要创建 10 条以上都链接到主笔记的笔记：

#!/bin/bash
MASTER_ID="master-index"
# Create notes in a loop (notebook auto-discovered)
for i in {1..10}; do
  NOTE_PATH=$(wiki new \
    --title "Topic $i" \
    --print-path)
  
  # Add link to master note
  echo "" >> "$NOTE_PATH"
  echo "See master: [[${MASTER_ID}]]" >> "$NOTE_PATH"
done
# Verify all notes link to master
wiki list --linked-by="$MASTER_ID" --format=long

**优点：**无需查找或传入笔记本路径，wiki 会自动处理。

批量操作：直接使用 zk（显式指定笔记本路径）

要显式控制笔记本：

#!/bin/bash
NOTEBOOK="/path/to/notebook"
MASTER_ID="master-index"
# Create notes in a loop
for i in {1..10}; do
  NOTE_PATH=$(zk new -W "$NOTEBOOK" \
    --title "Topic $i" \
    --print-path)
  
  # Add link to master note
  echo "" >> "$NOTE_PATH"
  echo "See master: [[${MASTER_ID}]]" >> "$NOTE_PATH"
done
# Verify all notes link to master
zk list -W "$NOTEBOOK" --linked-by="$MASTER_ID" --format=long

**限制：**ZK 没有批量创建链接的命令。通过脚本手动编辑是标准做法。

安全导出大型笔记本（使用 wiki）

#!/bin/bash
EXPORT_DIR="$HOME/exports"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
# Create export directory with timestamp
mkdir -p "$EXPORT_DIR"
# Test export format on small sample (notebook auto-discovered)
echo "=== Testing format on 1 note ==="
wiki list -l 1 --format=json | jq . > /dev/null
if [ $? -ne 0 ]; then
  echo "ERROR: JSON validation failed"
  exit 1
fi
# Full export
echo "=== Exporting all notes ==="
wiki list --format=json > "$EXPORT_DIR/export_${TIMESTAMP}.json"
# Validate output
jq . < "$EXPORT_DIR/export_${TIMESTAMP}.json" > /dev/null
if [ $? -eq 0 ]; then
  echo "✓ Export successful: $EXPORT_DIR/export_${TIMESTAMP}.json"
else
  echo "✗ Export failed: JSON is invalid"
  exit 1
fi

安全导出大型笔记本（直接使用 zk 并指定路径）

#!/bin/bash
NOTEBOOK="/path/to/notebook"
EXPORT_DIR="$HOME/exports"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
# Create export directory with timestamp
mkdir -p "$EXPORT_DIR"
# Test export format on small sample
echo "=== Testing format on 1 note ==="
zk list -W "$NOTEBOOK" -l 1 --format=json | jq . > /dev/null
if [ $? -ne 0 ]; then
  echo "ERROR: JSON validation failed"
  exit 1
fi
# Full export
echo "=== Exporting all notes ==="
zk list -W "$NOTEBOOK" --format=json > "$EXPORT_DIR/export_${TIMESTAMP}.json"
# Validate output
jq . < "$EXPORT_DIR/export_${TIMESTAMP}.json" > /dev/null
if [ $? -eq 0 ]; then
  echo "✓ Export successful: $EXPORT_DIR/export_${TIMESTAMP}.json"
else
  echo "✗ Export failed: JSON is invalid"
  exit 1
fi

实际影响

没有此技能： Agent 会浪费时间猜测不存在的命令（zk export、zk link），被 -W 标志搞糊涂，还会在格式选项上遇到困难。 有了此技能： Agent 能准确了解哪些命令确实存在，理解工作目录的行为，掌握导出模式，并避免在不存在的命令上白费功夫。