SuperAPI AI Directory
Partner中文AI newsFavorites
Skillslx-block

lx-block

Office & productivity

View repository

Updated 10-16 08:53

About this skill

Document block editing

Prerequisites: Requires lx CLI to be configured and logged in.

⚡ When to use this skill?

Entry scenarios:

  • User says "edit a page"/"modify a section"/"change a table"
  • User says "insert content into the document"/"append content"
  • User says "replace content under a certain heading"/"import markdown into the document"
  • Agent needs to make multiple modifications to the document

Prohibited in this skill:

  • Do not create new pages: user says "create a new page" → immediately switch to the lx-entry skill
  • Do not push modifications to the remote: user says "push"/"commit"/"push" → immediately switch to the lx-git skill
  • Do not browse the directory structure: user says "browse the knowledge base"/"look at the directory" → immediately switch to the lx-sh skill

⚡ Agent workflow

When the Agent needs to edit a document, follow this standard process:

Standard editing loop

1. 定位页面 → lx entry list-children / search_kb_search
2. 获取 entry_id 和 page block 信息
3. 查找目标块 → lx block find -q "关键词" -e <entry_id>
4. 执行编辑 → lx block update / insert-after / replace-section / table-set ...
5. 验证结果 → lx block get -b <block_id> -e <entry_id> --format mdx

Scenario of multiple modifications to the same document

When multiple modifications are needed to the same page:

# Step 1: 先用 find 定位所有需要修改的块，一次性获取所有 block_id
lx block find -q "API" -e <entry_id> --limit 20
# 输出: [1] h2 5b9490... "什么是 API"
#       [2] h3 e06877... "API 设计原则"

# Step 2: 用获取到的 block_id 逐一修改
lx block update -b 5b9490629433... -e <entry_id> --text "新内容"
lx block update -b e06877de8115... -e <entry_id> --text "更新后的原则"

Key rule: do not let the agent read the full MDX to find content. Use lx block find for index-style locating.

Scenario Recommended approach Avoid
Find a specific heading find -m heading -q "完整标题文本" Reading all MDX then grepping
Find blocks containing a certain word find -q "关键词" export full text then search
Find all tables find -m type -q "table" Traversing the entire tree
Find headings at a specific level find -m type -q "h2" + filter Manual traversal

Parameter passing conventions

All block operations require --entry-id / -e <entry_id>, which is a required parameter of the MCP server.

# 正确 ✅ — 总是带 entry_id
lx block ls -e <entry_id>
lx block find -q "关键词" -e <entry_id>
lx block update -b <block_id> -e <entry_id> --text "新内容"

⚡ How to choose a command? (Decision tree)

├── 需要**查找/定位**块？
│   ├── 按文本搜索? → lx block find -q "关键词" [-m text]
│   ├── 按标题精确匹配? → lx block find -q "标题文本" [-m heading]
│   ├── 按类型过滤? → lx block find -q "h2/table/code" [-m type]
│   └── 看树形结构? → lx block tree
├── 修改表格?
│   ├── 读取表格 → lx block table-get
│   ├── 改单元格 → lx block table-set
│   ├── 加一行 → lx block table-add-row
│   └── 删一行 → lx block table-del-row
├── 替换某个章节? → lx block replace-section
├── 在某处插入内容? → lx block insert-after
├── 在页面末尾追加? → lx block append
├── 导入整个 markdown 文件? → lx block import
├── 导出文档内容? → lx block export
└── 精细控制单个块?
    ├── 读取块 → lx block get
    ├── 创建块 → lx block create
    ├── 更新块 → lx block update
    ├── 删除块 → lx block delete
    ├── 移动块 → lx block move
    └── 转换内容 → lx block convert

⚠️ High-risk operations and default preferred path

High-level commands first, atomic commands as fallback:

  • If high-level commands can be used (table-* / replace-section / import, etc.), do not read atomic commands
  • Atomic commands are only used when high-level commands cannot express it
  • For queries, prefer find, not ls + manual filtering

Default preferred path:

  1. Query first, then modify → find locate the target block → then perform the modification
  2. Table operations → use table-* high-level commands
  3. Section replacement → use replace-section
  4. Batch import → use import --chunk-size 20 automatic batching
  5. Fine-grained control of a single block → only then fall back to atomic commands

Large documents must be batched:

  • Large document imports use lx block import --chunk-size 20 automatic batching to avoid a single request being too large

Available tools

Query (new)

Command Description
lx block find Search blocks by text/title/type

Three search modes:

# 文本子串搜索（不区分大小写）
lx block find -q "API" -e <entry_id>

# 标题精确匹配（需完整标题文本）
lx block find -q "一、什么是 Harness Engineering" -m heading -e <entry_id>

# 按类型过滤
lx block find -q "h2" -m type -e <entry_id>      # 所有二级标题
lx block find -q "table" -m type -e <entry_id>     # 所有表格
lx block find -q "code" -m type -e <entry_id>      # 所有代码块

Output format: readable summary + JSON (for programmatic consumption)

[1]   [h2] 5b9490629433 "一、什么是 Harness Engineering"
     path:  → 5b94906294334f7aaf29190a5e4ab20e

{
  "query": "...",
  "mode": "text",
  "count": 1,
  "matches": [{ "id": "...", "block_type": "H2", "text": "...", "path": [...] }]
}

Core CRUD

Command Description
lx block ls List child blocks (supports -r recursion)
lx block get Get block details (supports --format mdx export as MDX)
lx block create Create child block (supports automatic MDX conversion)
lx block update Update block (supports automatic MDX conversion)
lx block delete Delete block and its descendants
lx block move Move block to a new position

Advanced commands (preferred by default)

Command Description Reference
lx block table-get Read table structure block-advanced.md
lx block table-set Modify cell block-advanced.md
lx block table-add-row Append row block-advanced.md
lx block table-del-row Delete row block-advanced.md
lx block replace-section Replace section by title block-advanced.md
lx block insert-after Insert after a specified block block-advanced.md
lx block append Append to the end block-advanced.md
lx block export Export as markdown/json block-advanced.md
lx block tree Display block tree structure block-advanced.md
lx block import Import markdown (automatically batched) block-advanced.md

Conversion

Command Description
lx block convert Local MDX ↔ Block JSON conversion (does not go through the server)
lx block export --format mdx Export page as MDX format
lx block import Import from Markdown/MDX file (automatically batched)

MDX format reference: mdx-reference.md

Typical combined workflows

Standard workflow for Agent editing documents

# 1. 确认目标页面（从上下文或搜索获得 entry_id）
ENTRY_ID="26ab85ae2ff74cf3a22564846920d628"

# 2. 查找需要修改的块
lx block find -q "API" -e $ENTRY_ID
# 结果: [1] h2 xxx "API 接口说明" → block_id=5b9490629433...

# 3. 执行修改（用上一步获得的 block_id）
lx block update -b 5b9490629433... -e $ENTRY_ID \
  --content "## API 接口说明（已更新）"

# 4. 验证修改结果
lx block get -b 5b9490629433... -e $ENTRY_ID --format mdx

Modify multiple unrelated blocks

# 一次搜索找到所有目标
lx block find -q "TODO" -e $ENTRY_ID --limit 50
# 输出 10+ 个匹配块，每个都有 block_id

# 逐个修改
for bid in $(cat find_result.json | jq -r '.matches[].id'); do
  lx block update -b "$bid" -e $ENTRY_ID --text "已完成"
done

Modify table cells

# 查看
lx block table-get -b tbl_xxx

# 修改
lx block table-set -b tbl_xxx --row 2 --col 1 --text "修正值"

Replace a section in the document

lx block replace-section -b root_xxx --heading "## API 参考" \
  --file ./updated-api.md

Use atomic commands for fine-grained editing

# 创建块（MDX 自动转换）
lx block create -b parent_xxx -e $ENTRY_ID --content "## 新章节\n\n详细内容..."

# 批量更新
lx block update -b blk_xxx -e $ENTRY_ID --descendant '<blocks JSON>'

Import AI-generated MDX structured content

# 方式 1：直接导入 .mdx 文件
lx block import -b page_xxx --file ./doc.mdx --chunk-size 20

# 方式 2：导出页面为 MDX 格式
lx block export -b page_xxx --format mdx --output ./doc.mdx

# 方式 3：转换预览（不写入，只看结果）
lx block convert --from mdx --to blocks --content "<MyCallout title='注意'>...</MyCallout>"

See MDX format reference for the complete MDX component syntax and corresponding Block JSON structure.