dingtalk-document

DingTalk ドキュメントスキル

DingTalk のナレッジベースとドキュメントに関するすべての操作を担当します。本ファイルはポリシーガイドであり、意思決定ロジックとワークフローのみを記載しています。完全な API リクエスト形式については、末尾の「references/api.md 参照インデックス」をご覧ください。

dt_helper.sh は、この SKILL.md と同じディレクトリ内の scripts/dt_helper.sh にあります。

コアコンセプト

• ナレッジベース（Workspace）：ドキュメントコンテナーです。workspaceId と rootNodeId を持ちます
• ノード（Node）：ファイルまたはフォルダーです。type は FILE または FOLDER です
• ドキュメント識別子（/v1.0/doc/suites/documents/{id} 用）：docKey または dentryUuid を使用できます
  • ドキュメント作成時のレスポンスには、docKey、dentryUuid、nodeId が含まれます
  • docKey / dentryUuid は本文の読み書きに使用でき、nodeId は削除およびドキュメント管理系の API に使用します
  • wiki/nodes が返す nodeId は実際には dentryUuid であり、本文の読み書きにそのまま使用できます
• operatorId：すべての API で必須となる unionId パラメーターです。bash scripts/dt_helper.sh --to-unionid で自動変換します

ワークフロー（実行のたびに事前に行うこと）

1. 今回のタスクの種類を特定します → 例：ナレッジベースの一覧表示、ドキュメントの読み取り、ドキュメントの書き込み、ドキュメントの作成、メンバー管理
2. 今回のタスクに必要な設定を確認します → bash scripts/dt_helper.sh --get KEY で読み取ります。今回のタスクで必須の項目だけを確認してください
3. 不足している設定のみを収集します → 項目が不足している場合、不足している値をすべて一度にユーザーに尋ね、bash scripts/dt_helper.sh --set KEY=VALUE で書き込みます
4. Token / operatorId を取得します → bash scripts/dt_helper.sh を直接呼び出します。Token の取得やキャッシュの詳細を気にする必要はありません
5. 操作を実行します → 変数置換、パイプ、または複数行のロジックを含むコマンドは、/tmp/<task>.sh に書き込んでから bash /tmp/<task>.sh で実行してください。複数行のコマンドをターミナルに直接貼り付けないでください（ターミナルツールで切り詰められます）。また、<<'EOF' 構文も使用しないでください（heredoc もツールで切り詰められ、変数が失われるためです）

タスクごとの設定確認（必ず最初に実施）

• すべてのタスクで共通して必須：DINGTALK_APP_KEY、DINGTALK_APP_SECRET、DINGTALK_MY_USER_ID
• ドキュメント／ナレッジベース API 呼び出しを含む場合：DINGTALK_MY_OPERATOR_ID が必須です（未設定の場合は、先に bash scripts/dt_helper.sh --to-unionid で自動変換して書き戻します）
• 作成／読み取り／書き込み／削除／メンバー管理：上記の共通項目以外に、固定で必要な設定キーはありません。workspaceId／nodeId／docKey はタスクパラメーターであり、実行時にユーザー入力または API レスポンスから取得します

ルール：「今回のタスクの設定確認」に合格するまでは、API 呼び出しの手順に進んではいけません。

認証情報を出力にすべて表示することは禁止されています。確認時は先頭 4 文字 + **** のみを表示してください

必要な設定

設定キー	必須	説明	取得方法
DINGTALK_APP_KEY	✅	アプリの AppKey	DingTalk オープンプラットフォーム → アプリ管理 → 認証情報
DINGTALK_APP_SECRET	✅	アプリの AppSecret	同上
DINGTALK_MY_USER_ID	✅	現在のユーザーの企業従業員 ID（userId）	管理コンソール → アドレス帳 → メンバー管理 → 名前をクリックして確認
DINGTALK_MY_OPERATOR_ID	✅	現在のユーザーの unionId（operatorId）	初回に bash scripts/dt_helper.sh --to-unionid で自動変換して書き込みます

識別子の説明

識別子	説明
userId（= staffId）	企業内の従業員 ID です。管理コンソール -> アドレス帳 -> メンバー管理 -> 名前をクリックして確認できます
unionId	企業間／アプリ間で一意の識別子です。bash scripts/dt_helper.sh --to-unionid <userid> で取得できます

実行スクリプトのテンプレート

#!/bin/bash
set -e
HELPER="./scripts/dt_helper.sh"
NEW_TOKEN=$(bash "$HELPER" --token)
OPERATOR_ID=$(bash "$HELPER" --get DINGTALK_MY_OPERATOR_ID)

# 在此追加具体 API 调用，例如查询知识库列表：
WORKSPACES=$(curl -s -X GET "https://api.dingtalk.com/v2.0/wiki/workspaces?operatorId=${OPERATOR_ID}&maxResults=20" \
  -H "x-acs-dingtalk-access-token: $NEW_TOKEN")
echo "知识库列表: $WORKSPACES"

Token の無効時の処理：dt_helper は時間に基づいてキャッシュするだけで、Token が事前に取り消されたことを検知できません。API が 401（Token が無効／期限切れ）を返した場合は、--nocache を使用してキャッシュをスキップし、強制的に再取得してください：

NEW_TOKEN=$(bash "$HELPER" --token --nocache)

references/api.md 参照インデックス

実行する操作が決まったら、次のコマンドで references/api.md から該当する章の完全な API 詳細（リクエスト形式、パラメーターの説明、レスポンス例）を抽出してください：

grep -A 30 "^## 1. 查询知识库列表" references/api.md
grep -A 10 "^## 2. 查询知识库信息" references/api.md
grep -A 35 "^## 3. 查询节点列表" references/api.md
grep -A 10 "^## 4. 查询单个节点" references/api.md
grep -A 15 "^## 5. 通过 URL 查询节点" references/api.md
grep -A 28 "^## 6. 创建文档" references/api.md
grep -A 10 "^## 7. 删除文档" references/api.md
grep -A 30 "^## 8. 读取文档内容" references/api.md
grep -A 15 "^## 9. 覆盖写入文档内容" references/api.md
grep -A 12 "^## 10. 追加文本到段落" references/api.md
grep -A 18 "^## 11. 添加文档成员" references/api.md
grep -A 12 "^## 12. 更新文档成员权限" references/api.md
grep -A 10 "^## 13. 移除文档成员" references/api.md
grep -A 10 "^## 错误码" references/api.md
grep -A 10 "^## 所需应用权限" references/api.md