name: 騰訊文件Markdown license: MIT description: 騰訊文件 Markdown 技能，支援新建 Markdown 並寫入內容、下載、刪除、讀取、更新、重新命名等操作。

騰訊文件 Markdown 技能

名稱： tencent-docs-markdown 許可證： MIT 簡介： 騰訊文件 Markdown 技能，支援新建 Markdown 並寫入內容、下載、刪除、讀取、更新、重新命名等操作。

Agent 如何使用此技能

觸發短語

當用戶表達以下意圖時，Agent 應啟用此技能：

Agent 工作流程

flowchart TD
    A[使用者請求] --> B{Cookies 有效？}
    B -->|是| C[執行操作]
    B -->|否| D[通過掃碼登入]
    D --> E[儲存 Cookies]
    E --> C
    C --> F[返回結果 + 文件連結]

快速開始

# 1. 安裝依賴
pip install -r requirements.txt
playwright install chromium

# 2. 登入（使用微信/QQ 掃描二維碼）
python -m src.main login

# 3. 新建文件並寫入內容
python -m src.main write "我的文件" "# Hello World"

功能操作

1. 新建並寫入文件

新建一個騰訊文件 Markdown，寫入內容後返回文件連結。

命令列：

python -m src.main write "我的文件" "# Hello World\n這是我的文件內容。"

程式設計介面：

from src.main import handle_create_and_write
result = handle_create_and_write('我的文件', '# Hello World\n這是內容。')
# result: {'docUrl': ..., 'padId': ..., 'globalPadId': ..., 'title': ...}
# → 將 result['docUrl'] 分享給使用者

2. 新建空文件

建立一個新的空 Markdown 文件。

命令列：

python -m src.main create "我的新文件"

程式設計介面：

from src.main import handle_create
result = handle_create('我的文件')
# result: {'docUrl': ..., 'padId': ..., 'globalPadId': ..., 'title': ...}

3. 下載文件

將騰訊文件 Markdown 下載為本地 .md 檔案。

注意： 系統會自動從文件頁面解析真實的 padId（URL 中的識別符號與 API 所需的真實 padId 不同）。

來源於7w4.net。

命令列：

python -m src.main download https://docs.qq.com/markdown/DQxxxxxxxx
python -m src.main download https://docs.qq.com/markdown/DQxxxxxxxx -o ./output.md

程式設計介面：

from src.main import handle_download
result = handle_download('https://docs.qq.com/markdown/DQxxxxxxxx', './output.md')
# result: {'path': ..., 'content': ...}

4. 讀取文件

讀取並返回文件內容。

命令列：

python -m src.main read https://docs.qq.com/markdown/DQxxxxxxxx

程式設計介面：

from src.main import handle_read
content = handle_read('https://docs.qq.com/markdown/DQxxxxxxxx')

5. 更新文件

覆蓋已有文件的內容（支援直接傳入文本或 .md 檔案路徑）。

⚠️ 安全提示： 這是破壞性操作。互動模式下會顯示目標文件標題與 URL 並要求確認 (y/N)。程式化呼叫須顯式傳入 confirm=True，否則操作會被拒絕。CLI 也可加 -y/--yes 跳過提示。

命令列：

python -m src.main update https://docs.qq.com/markdown/DQxxxxxxxx "# 新內容"
python -m src.main update https://docs.qq.com/markdown/DQxxxxxxxx ./updated.md
python -m src.main update https://docs.qq.com/markdown/DQxxxxxxxx ./updated.md -y   # 跳過確認

程式設計介面：

from src.main import handle_update
handle_update('https://docs.qq.com/markdown/DQxxxxxxxx', '# 更新後的內容', confirm=True)

6. 刪除文件

將文件移入回收站。

⚠️ 安全提示： 互動模式下會展示目標文件標題與 URL 並要求確認 (y/N)。程式化呼叫須顯式傳入 confirm=True，否則操作會被拒絕。CLI 也可加 -y/--yes 跳過提示。

命令列：

python -m src.main delete https://docs.qq.com/markdown/DQxxxxxxxx
python -m src.main delete https://docs.qq.com/markdown/DQxxxxxxxx -y        # 跳過確認

程式設計介面：

from src.main import handle_delete
result = handle_delete('https://docs.qq.com/markdown/DQxxxxxxxx', confirm=True)
# result: {'padId': ..., 'title': ..., 'deleted': True}

7. 重新命名文件

⚠️ 安全提示： 互動模式下會展示原標題、新標題與 URL 並要求確認 (y/N)。程式化呼叫須顯式傳入 confirm=True。

命令列：

python -m src.main rename https://docs.qq.com/markdown/DQxxxxxxxx "新標題"
python -m src.main rename https://docs.qq.com/markdown/DQxxxxxxxx "新標題" -y  # 跳過確認

程式設計介面：

from src.main import handle_rename
handle_rename('https://docs.qq.com/markdown/DQxxxxxxxx', '新標題', confirm=True)

8. 獲取文件資訊

命令列：

python -m src.main info https://docs.qq.com/markdown/DQxxxxxxxx

程式設計介面：

from src.main import handle_info
info = handle_info('https://docs.qq.com/markdown/DQxxxxxxxx')

9. 登入

命令列：

python -m src.main login          # 使用快取的 Cookies（如有效）
python -m src.main login --force  # 強制重新登入

10. 登出 / 清除 Cookies

刪除本地 .cookies.json 憑證檔案，在不再需要該會話時使用。

命令列：

python -m src.main logout

程式設計介面：

from src.auth import clear_cookies
clear_cookies()

認證機制

首次使用需掃碼登入，之後 Cookie 會快取在 .cookies.json 中自動複用。

🔐 憑證管理： .cookies.json 被明確宣告為 賬戶級憑證。儲存時會自動應用 POSIX 0600 許可權（僅當前使用者可讀寫），並在終端提示使用者其敏感性。切勿將此檔案提交到版本控制或共享給他人；不再使用時請執行 python -m src.main logout 或手動刪除。推薦使用專用的自動化賬號，而非個人主賬號。

支援兩種登入方式： 1. 掃碼登入 — 使用微信/QQ 掃描二維碼 2. 微信快捷登入 — 如果之前在當前瀏覽器已有微信登入記錄，系統會自動檢測並點選"微信快捷登入"按鈕，頁面顯示"登入中..."後自動完成登入

flowchart TD
    A[開始] --> B{.cookies.json 存在？}
    B -->|是| C{Cookies 有效？}
    B -->|否| D[啟動瀏覽器]
    C -->|是| E[就緒]
    C -->|否| D
    D --> F{微信快捷登入可用？}
    F -->|是| G[點選'微信快捷登入'按鈕]
    G --> H[頁面顯示'登入中...']
    H --> I[每10秒輪詢檢測頁面變化]
    F -->|否| J[展示二維碼供掃描]
    J --> I
    I --> K{檢測到登入成功？}
    K -->|是| L[獲取並驗證 Cookies]
    K -->|否 / 超時| I
    L --> M[儲存 Cookies 到 .cookies.json]
    M --> E

API 參考

專案結構

tencent-docs-markdown/
├── requirements.txt      # Python 依賴
├── SKILL.md              # 技能定義檔案（本檔案）
├── publish.sh            # 版本釋出指令碼
├── .cookies.json         # 儲存的登入 Cookies（自動生成，已加入 .gitignore）
└── src/
    ├── __init__.py       # Python 包初始化
    ├── main.py           # 主入口 & CLI 命令
    ├── auth.py           # 掃碼登入 & Cookie 管理
    ├── api.py            # 騰訊文件 Markdown API 客戶端
    └── login_with_polling.py  # 輪詢登入指令碼

核心概念

URL 識別符號與真實 padId

騰訊文件 Markdown 的 URL 格式為 https://docs.qq.com/markdown/DSxxxxxxxx，其中 DSxxxxxxxx 是 URL 識別符號，並非 API 所需的真實 padId。

系統通過 resolve_real_pad_id() 函式訪問文件頁面，從嵌入的 basicClientVars JSON 中提取真實的 padId，然後拼接為 globalPadId（格式：{domainId}${padId}）用於 API 呼叫。

此機制對 下載（download）、讀取（read）、更新（update） 操作自動生效，使用者無需關注。

錯誤處理

備註

• Markdown 文件型別編號為 14（doc_type=14）
• 預設 domain_id 為 300000000
• XSRF Token 從 TOK Cookie 中提取
• Cookies 儲存在 .cookies.json 中（已加入 .gitignore），儲存時自動設定 0600 許可權
• 安全提示： .cookies.json 包含敏感的會話 Cookie，其作用等同於賬戶憑證。請勿提交到版本控制或分享給他人；檔案自動設定 0600 許可權，如需手動重置：chmod 600 .cookies.json。不再使用時請執行 python -m src.main logout 清除。
• 破壞性操作保護： update / delete / rename 均為不可撤銷或影響使用者文件的操作；它們在執行前會解析並展示目標文件的標題與 URL，互動模式下要求 y/N 確認；程式化呼叫必須顯式傳入 confirm=True，否則操作會被拒絕。
• 隱私提示： download / read 會將文件內容暴露給當前 agent 會話、終端輸出或本地檔案；請避免對高敏感文件使用這些操作。
• 依賴版本鎖定： requirements.txt 中所有執行時依賴都被鎖定到確定版本以減少供應鏈風險；請在可信任的環境中安裝並審查任何依賴更新。
• 刪除操作會將文件移至回收站（可恢復）
• 下載/讀取/更新操作會自動解析 URL 中的識別符號為真實 padId
• 建議在受控或受信環境中執行此工具，因為 Playwright 會下載 Chromium 並使用瀏覽器自動化許可權
• Python 版本要求： Python >= 3.10

所需配置

這是一款功能齊全、操作騰訊文件 Markdown 的工具，核心功能都工作穩定。它在安全性上做得比較用心——刪除或修改文件時會主動要求確認，防止誤操作。不過沒有自動化測試，長期維護可能存在隱患。對於普通使用者來說上手簡單，按照文件操作即可。整體質量中上，功能實用但還有完善空間。