# Lexiang Scripts

乐享文档写入辅助脚本集合。

## 安装依赖

### TypeScript 脚本

```bash
npm install -g ts-node typescript
npm install @types/node
```

### Python 脚本

```bash
pip install aiohttp requests
```

## 脚本列表

### sync-folder.ts

本地文件夹增量同步到乐享知识库。

```bash
# Dry run 模式（仅生成计划）
npx ts-node sync-folder.ts --local ./docs --entry-id abc123 --dry-run

# 完整参数
npx ts-node sync-folder.ts \
  --local ./docs \
  --entry-id <parent_entry_id> \
  --space-id <space_id> \
  --state-file .sync-state.json \
  --dry-run
```

### upload-files.py

并行上传文件到乐享。

```bash
# 单文件上传
python upload-files.py --files doc1.md doc2.pdf --entry-id abc123

# 文件夹批量上传
python upload-files.py --folder ./docs --entry-id abc123 --parallel 5

# 输出上传计划到 JSON
python upload-files.py --folder ./docs --entry-id abc123 --output plan.json --dry-run
```



## 工作流示例

### 1. 项目文档同步

```bash
# 1. 首次同步（dry run 检查）
npx ts-node sync-folder.ts --local ./project-docs --entry-id root123 --dry-run

# 2. 执行同步
# 将生成的 MCP 调用序列提供给 AI 助手执行

# 3. 后续增量同步
# 脚本会自动检测变更，只同步修改的文件
```

### 2. Markdown 文档导入

```bash
# 1. 生成上传计划
python upload-files.py --folder ./markdown-docs --entry-id target123 --output plan.json

# 2. 查看计划
cat plan.json

# 3. 执行上传（通过 AI 助手）
# 将 plan.json 中的 MCP 调用提供给 AI 助手
```

## 注意事项

1. **MCP 调用需要通过 AI 助手执行**：脚本生成 MCP 调用参数，实际执行需要 AI 助手的 MCP 能力
2. **文件上传是 3 步流程**：apply_upload → HTTP PUT → commit_upload
3. **同步状态文件**：`.lexiang-sync-state.json` 记录同步状态，请勿删除
4. **大文件建议分批**：单次 MCP 调用的数据量有限制
5. **Block 写入使用 MCP 工具**：直接调用 `block_convert_content_to_blocks` 将 Markdown/HTML 转换为块结构，无需手动构建
