iwiki-doc

name: iwiki-doc description: 专门用于与腾讯企业内部iWiki文档交互的集成接口。支持针对 iwiki.woa.com 域名、iwiki/iWiki关键词相关的全生命周期文档管理。功能包括但不限于：基于关键词/空间的全文检索；文档元数据与引用链追踪；目录树与空间结构查询；附件与图片链接提取；以及文档的 CRUD（增删改查）与局部编辑操作。当 Prompt 涉及 iWiki 实体时，必须作为首选 Tool 执行。 version: 0.0.4 author: josonyang

iWiki Skill

iWiki 是一个用于与 iWiki 文档系统交互的 Model Context Protocol 服务，提供文档管理、搜索、创建、编辑和多维表格操作能力。

概述

本 Skill 帮助你高效使用 iWiki 工具进行文档操作，包括：

• 📖 文档搜索与阅读：搜索、获取文档内容和元数据
• ✍️ 文档创建与编辑：创建、保存、仅改标题、局部更新文档
• 🏷️ 标签管理：添加、删除、查询文档标签
• 📊 多维表格操作：操作 Smartsheet 字段、视图和记录
• 💬 评论互动：获取、添加文档评论和划词批注

快速开始

0. 连接 MCP Server

在使用 iWiki 功能之前，先从环境变量或者本地.env读取TAI_PAT_TOKEN，然后连接 MCP Server。

使用 Python 脚本连接（推荐）

1. 安装依赖：

pip install requests

2. 设置环境变量：

export TAI_PAT_TOKEN="your_tai_pat_token_here"

3. 运行连接脚本验证：

# 仅验证连接
python scripts/connect_mcp.py

# 验证连接并获取文档
python scripts/connect_mcp.py call getDocument '{"docid": "4017403457"}'

脚本会：

• 发送 initialize 请求验证 MCP 连接
• 获取 tools/list 显示所有可用工具
• （可选）调用 getDocument 获取指定文档

认证方式

所有请求需要在 Header 中携带 Bearer Token：

Authorization: Bearer TAI_PAT_TOKEN

0.5 导入文档（无需连接 MCP Server）

文件导入功能通过独立的 HTTP 端点 POST /import 实现，不需要先连接 MCP Server（无需 initialize 和 tools/list 步骤），可直接调用。

支持的文件类型

• Markdown 文件（.md）
• Word 文档（.docx）
• 包含.md 和.docx 的 zip 压缩包(支持包含附件)

使用限制

• 不支持导入到需要审批的文档目录
• 默认覆盖同名文档

命令行导入

# 1. 设置环境变量
export TAI_PAT_TOKEN="your_tai_pat_token_here"

# 2. 上传 Markdown 文件到指定父目录
python scripts/connect_mcp.py upload ./doc.md 4017403457

# 指定任务类型
python scripts/connect_mcp.py upload ./doc.docx 4017403457 --task-type md_import

# 不覆盖同名文档
python scripts/connect_mcp.py upload ./doc.md 4017403457 --no-cover

Python 代码调用

from scripts.connect_mcp import MCPClient

client = MCPClient(token="your_tai_pat_token")
result = client.upload_file(
    file_path="./doc.md",
    parent_id=4017403457,
    task_type="md_import",  # 导入任务类型，默认 md_import
    cover=True,             # 是否覆盖同名文档，默认 True
)
print(result)  # {"success": True, "msg": "导入成功", "data": [...]}

导入参数说明

内部流程

导入操作在服务端自动完成以下步骤：

1. 获取预签名 URL
2. 上传文件到 COS 对象存储
3. 启动导入任务
4. 轮询等待导入完成（最多 180 秒）

1. 查找文档

优先使用 searchDocument 进行传统关键词搜索（支持按类型、空间、标签、作者筛选，也支持通过 offset 做结果翻页）。 当传统搜索无结果、查询词为句子时，再使用 aiSearchDocument 进行 AI 语义搜索（推荐）：

搜索关键词: "项目需求文档"
offset: 20   # 跳过前 20 条结果，获取下一页

2. 读取文档

获取到 docid 后，使用 getDocument 获取完整内容：

docid: "123456"

3. 创建文档

使用 createDocument 创建新文档：

spaceid: 12345         # 空间ID
parentid: 67890        # 父文档ID
title: "新文档标题"
body: "文档内容..."
contenttype: "MD"      # MD/DOC/FOLDER
is_html: false         # false=MarkdownTransformer，true=HtmlTransformer

createDocument 会先将 body 转成 JSON 后再写入：

• is_html=true：通过 HtmlTransformer 转换
• is_html=false：通过 MarkdownTransformer 转换
• body_mode 为兼容旧参数保留，通常不需要再传

核心工具列表

🔍 搜索类工具

📄 文档读取工具

✏️ 文档写入工具

🏷️ 标签工具

💬 评论工具

📊 多维表格（Smartsheet）工具

📥 文档导入工具

🏠 空间管理工具

使用规范

⚠️ 重要约定

1. 搜索优先

   • 当问题是”某个词是什么意思时“，优先使用 glossaryTermSearch
   • 首先使用 searchDocument 或 aiSearchDocument 找到目标文档
   • 当需要翻页或跳过前面结果时，优先给 searchDocument 传 offset
   • 获取 docid 后再进行其他操作

2. 确认空间 ID

   • 创建文档前必须确认 spaceid 和 parentid
   • 使用 getSpaceInfoByKey 或 getSpaceInfoByName 获取空间信息
   • 当空间名包含空格、斜杠或其他特殊字符时，优先直接传原始空间名，让工具自动编码处理

3. 内容非空检查

   • createDocument 和 saveDocument 的 body 参数不能为空
   • 仅修改标题时应使用 renameDocumentTitle，不要给 saveDocument 传空 body
   • MCP 服务会拒绝空内容的写入

4. 审批文档限制

   • 需要审批的文档不支持创建/更新/移动/复制
   • 操作前会自动检查，如遇到审批文档会返回提示

5. 文档复制说明

   • 使用 copyDocument 复制文档到新位置
   • is_single=1 只复制单个文档，is_single=0 复制整个文档树（包含所有子文档）
   • 复制操作会返回任务ID，可用于查询复制进度
   • 复制的文档不会保留原文档的评论和标签

6. 更新删除约定

   • 仅修改标题时使用 renameDocumentTitle
   • 追加内容时优先使用 saveDocumentParts（在头部/尾部追加）
   • 全量更新使用 saveDocument
   • 所有的高危操作(如：deleteDocumentTag, moveDocument, smartsheetDeleteField,smartsheetDeleteRecords)都需要用户二次确认

7. 内容格式

   • createDocument 与 saveDocument 均通过 is_html 决定正文转换方式：true 使用 HtmlTransformer，false 使用 MarkdownTransformer
   • 当传 Markdown 内容时，建议显式传 is_html: false
   • 当传 HTML/XHTML 富文本内容时，建议显式传 is_html: true
   • body_mode 为兼容旧参数保留；当前正文会先转换为 JSON，通常无需再依赖 body_mode
   • 添加评论时内容时，使用XHTML格式
   • XHTML基本元素：，-, , , , , ,

     1. ，表格：/ 结构

        ，内容一定要用合适的XHTML标签包装 文件限制 在创建、更新等使用场景下，先创建临时文本文件，然后执行完成后，再删除掉这个临时文本文件 在同步一个仓库的md到iWiki时，先找出md里包含的附件，并将附件与md一起打包成临时的zip文件，然后再导入操作 📝 URL 格式说明 URL 类型 示例 说明 个人空间 https://iwiki.woa.com/space/~myname Key 为 ~myname 普通空间 https://iwiki.woa.com/space/devcloud Key 为 devcloud 文档页面 https://iwiki.woa.com/p/123456 docid 为 123456 专题 https://iwiki.woa.com/topic/1232323 topic_id 为 1232323 📊 多维表格操作流程 了解表格结构 smartsheetGetFields(doc_id) -> 获取所有字段定义 smartsheetGetViews(doc_id) -> 获取视图列表 查询数据 smartsheetGetRecords(doc_id, { pageNum: 1, pageSize: 100, filterByFormula: "条件表达式", fields: "字段1,字段2" }) 写入数据 smartsheetAddRecords(doc_id, fieldKey: "name", records: [ { fields: { "字段名": "值" } } ]) 支持的字段类型 SingleText, Text, SingleSelect, MultiSelect, Number, Currency, Percent, DateTime, Attachment, Member, Checkbox, Rating, URL, Phone, Email, WorkDoc, OneWayLink, TwoWayLink, MagicLookUp, Formula, AutoNumber, CreatedTime, LastModifiedTime, CreatedBy, LastModifiedBy, Button 支持的视图类型 Grid（表格）, Gallery（画廊）, Kanban（看板）, Gantt（甘特图）, Calendar（日历）, Architecture（架构） 常见场景 场景 1：搜索并阅读文档 graph LR A[searchDocument] --> B{找到文档?} B -->|是| C[getDocument] B -->|否| D[aiSearchDocument] D --> E{找到文档?} E -->|是| C E -->|否| F[尝试其他关键词或调整 offset] C --> G[阅读/分析内容] 场景 2：创建新文档 graph LR A[确定目标空间] --> B[getSpaceInfoByKey] B --> C[获取 spaceid] C --> D[确定父目录 parentid] D --> E[createDocument] 场景 3：更新文档 graph LR A{更新范围} A -->|仅改标题| B[renameDocumentTitle] A -->|追加内容| C[saveDocumentParts] A -->|全量更新| D[saveDocument] B --> E[提供 id 和 new_title] C --> F[指定 before/after] D --> G[提供完整 body] 场景 3.5：复制文档 graph LR A[确定源文档ID] --> B[确定目标父目录ID] B --> C{复制范围} C -->|单个文档| D[copyDocument is_single=1] C -->|整个文档树| E[copyDocument is_single=0] D --> F[返回任务ID] E --> F 场景 4：导入本地文件（无需连接 MCP） graph LR A[准备本地文件] --> B[确定父目录 parent_id] B --> C[upload 命令上传] C --> D{导入成功?} D -->|是| E[文档已创建] D -->|否| F[检查文件/权限] 场景 5：操作多维表格 graph LR A[smartsheetGetFields] --> B[了解字段结构] B --> C{操作类型} C -->|查询| D[smartsheetGetRecords] C -->|新增| E[smartsheetAddRecords] C -->|更新| F[smartsheetUpdateRecords] C -->|删除| G[smartsheetDeleteRecords] 错误处理 错误信息 原因 解决方案 body 为空值 内容参数为空 确保传入有效的文档内容 MCP不支持审批流程 文档需要审批 手动在 iWiki 网页操作 参考资料 API 参考文档 Install via CLI npx skills add https://github.com/alfredhuang211/my_skills --skill iwiki-doc content_copy Copy Command Repository Details star Stars 0 call_split Forks 0 navigation Branch main article Path SKILL.md More from Creator alfredhuang211 Explore all skills →