名称： openkm-rest
描述： 通过 REST API 访问 OpenKM 文档管理系统（文件夹、文档、元数据、版本控制、搜索、工作流）
元数据：
openclaw:
emoji: "📁"
requires:
bins: ["python"]
env:
- OPENKM_BASE_URL
- OPENKM_USERNAME
- OPENKM_PASSWORD
primaryEnv: OPENKM_BASE_URL
user-invocable: true
disable-model-invocation: false

OpenKM REST 技能

此技能提供了一个本地 CLI 工具，仅通过 REST API 访问 OpenKM（不使用 SOAP 或 CMIS）。

代理通过调用 shell 命令 openkm_cli.py 来执行操作。

环境变量（必需）

OPENKM_BASE_URL=https://openkm.example.com   # 不要包含 /OpenKM
OPENKM_USERNAME=okm_admin
OPENKM_PASSWORD=secret

文件夹操作

列出文件夹内容

python3 openkm_cli.py list --folder-path /okm:root

创建文件夹结构

如果父文件夹不存在，会自动创建：

python3 openkm_cli.py ensure-structure --parts Folder1 Subfolder

文档操作

上传文档

python3 openkm_cli.py upload --okm-path /okm:root/Folder/file.pdf --local-path /path/file.pdf

下载文档

python3 openkm_cli.py download --doc-id <uuid> --local-path /path/file.pdf

移动文档

将文档移动到另一个文件夹（使用文件夹 UUID 作为目标）：

python3 openkm_cli.py move --doc-id <doc-uuid> --target-path <folder-uuid>

重命名文档

python3 openkm_cli.py rename --doc-id <uuid> --new-name new_filename.pdf

删除文档

python3 openkm_cli.py delete --doc-id <uuid>

元数据与组织

获取文档属性

显示标题、描述、关键词、分类及其他元数据：

python3 openkm_cli.py properties --doc-id <uuid>

设置标题和描述

python3 openkm_cli.py set-properties --doc-id <uuid> --title "我的标题" --description "我的描述"

添加关键词

python3 openkm_cli.py add-keyword --doc-id <uuid> --keyword "发票"

移除关键词

python3 openkm_cli.py remove-keyword --doc-id <uuid> --keyword "发票"

添加分类

分类 ID 可以是 UUID 或路径（例如 /okm:categories/Finance）：

python3 openkm_cli.py add-category --doc-id <uuid> --category-id <category-uuid-or-path>

移除分类

python3 openkm_cli.py remove-category --doc-id <uuid> --category-id <category-uuid-or-path>

版本控制

获取版本历史

python3 openkm_cli.py versions --doc-id <uuid>

下载特定版本

python3 openkm_cli.py download-version --doc-id <uuid> --version 1.0 --local-path /path/file_v1.pdf

恢复版本

将文档恢复到指定历史版本：

python3 openkm_cli.py restore-version --doc-id <uuid> --version 1.0

搜索

按内容搜索（全文）

python3 openkm_cli.py search-content --content "发票 托管"

按文件名搜索

python3 openkm_cli.py search-name --name "hetzner"

按关键词搜索

python3 openkm_cli.py search-keywords --keywords "发票,托管"

带筛选条件的通用搜索

python3 openkm_cli.py search --content "服务器" --author "john.doe" --path "/okm:root"

工作流

注意： 工作流功能要求 OpenKM 中已配置相应工作流。
如果未启用工作流，相关命令将返回 404 错误。

列出可用工作流

python3 openkm_cli.py workflows
python3 openkm_cli.py workflows --name "approval"

启动工作流

python3 openkm_cli.py start-workflow --workflow-uuid <workflow-uuid> --doc-id <doc-uuid>

列出任务

# 获取文档相关任务
python3 openkm_cli.py tasks --doc-id <uuid>

# 获取指定执行人相关任务
python3 openkm_cli.py tasks --actor-id john.doe

完成任务

python3 openkm_cli.py complete-task --task-id <task-id> --transition "approve"

为任务添加评论

python3 openkm_cli.py comment-task --task-id <task-id> --message "审核完成"

分配任务给执行人

python3 openkm_cli.py assign-task --task-id <task-id> --actor-id john.doe

注意事项

• API 要求在 POST 请求中，若以路径作为请求体，需设置 Content-Type: application/xml
• 作为查询参数传递时，路径必须进行 URL 编码
• fldId、docId、dstId、nodeId、catId 等参数接受 UUID 或路径（例如 /okm:root/Folder）
• 移动操作中，target-path 应为目标文件夹的 UUID
• 重命名操作只需提供新文件名（无需完整路径）
• 关键词是自由文本标签；分类在 OpenKM 中预定义
• 版本名称通常为数字，如 1.0、1.1、2.0 等
• 搜索结果包含相关性评分
• 工作流功能要求 OpenKM 中已正确配置工作流

API 参考

本技能使用 OpenKM 6.3 REST API 端点：

文件夹：
- GET /folder/getChildren - 列出文件夹内容
- POST /folder/createSimple - 创建文件夹

文档：
- POST /document/createSimple - 上传文档
- GET /document/getContent - 下载文档
- GET /document/getProperties - 获取文档元数据
- PUT /document/setProperties - 更新标题/描述
- PUT /document/move - 移动文档
- PUT /document/rename - 重命名文档
- DELETE /document/delete - 删除文档

版本控制：
- GET /document/getVersionHistory - 获取版本历史
- PUT /document/restoreVersion - 恢复到指定版本
- GET /document/getContentByVersion - 下载特定版本

属性/元数据：
- POST /property/addKeyword - 添加关键词
- DELETE /property/removeKeyword - 移除关键词
- POST /property/addCategory - 添加分类
- DELETE /property/removeCategory - 移除分类

搜索：
- GET /search/find - 带筛选条件的通用搜索
- GET /search/findByContent - 全文搜索
- GET /search/findByName - 按文件名搜索
- GET /search/findByKeywords - 按关键词搜索

工作流：
- GET /workflow/getAllProcessDefinitions - 列出所有工作流
- GET /workflow/getAllProcessDefinitionsByName - 按名称查找工作流
- POST /workflow/runProcessDefinition - 启动工作流
- GET /workflow/findTaskInstances - 按文档获取任务
- GET /workflow/findTaskInstancesByActor - 按执行人获取任务
- POST /workflow/setTaskInstanceValues - 完成任务
- POST /workflow/addTaskInstanceComment - 添加任务评论
- POST /workflow/setTaskInstanceActor - 分配任务