FileComment model includes is_whole/quote fields but they are silently ignored when creating comments on docx files

Commencez par le modèle file_comment.py généré et FileCommentBuilder, puis reproduisez POST /open-apis/drive/v1/files/{file_token}/comments avec file_type=docx à l’aide de la requête fournie. Comparez les champs de la requête avec la réponse résultante de List API et avec la documentation officielle « Add a Global Comment ». Le travail est considéré comme terminé lorsque la limitation ou le comportement pris en charge est clairement résolu, sans ignorer silencieusement les champs.

Summary

The FileComment model and its FileCommentBuilder expose is_whole and quote fields, suggesting that inline (non-whole-document) comments can be created via the API. However, when calling POST /open-apis/drive/v1/files/{file_token}/comments with file_type=docx, these fields are silently ignored — the API always creates a global (whole-document) comment regardless of the values passed.

Steps to Reproduce

import httpx

body = {
    "is_whole": False,
    "quote": "目标是验证文档导入与结构化展示",  # exact text from the document
    "reply_list": {
        "replies": [{
            "content": {
                "elements": [
                    {"type": "text_run", "text_run": {"text": "This should be an inline comment"}}
                ]
            }
        }]
    }
}

resp = httpx.post(
    "https://open.larksuite.com/open-apis/drive/v1/files/{file_token}/comments",
    headers={"Authorization": f"Bearer {tenant_access_token}"},
    params={"file_type": "docx"},
    json=body,
    timeout=15,
)

Expected Behavior

The comment should be created as an inline comment anchored to the quoted text, with is_whole=False in the response.

Actual Behavior

The API returns code: 0 (success), but when retrieving the comment via the List API:

{
  "comment_id": "...",
  "is_whole": true,
  "quote": "",
  ...
}

The comment is always a global comment (is_whole=true, quote=""), no matter what is_whole or quote values are sent in the request.

Test Details

Tested with 5 different quote values against a real docx document:

All 5 comments were created as global comments.

The Problem

The SDK's auto-generated FileComment model uses the same class for both request and response, so it exposes builder methods for is_whole() and quote():

# file_comment.py (auto-generated)
class FileCommentBuilder(object):
    def is_whole(self, is_whole: bool) -> "FileCommentBuilder":
        self._file_comment.is_whole = is_whole
        return self

    def quote(self, quote: str) -> "FileCommentBuilder":
        self._file_comment.quote = quote
        return self

This is misleading because:

1. Developers assume these fields are functional for creation since the builder exposes them
2. The API accepts the request without any error or warning — it just silently ignores the fields
3. The official documentation page is titled "Add a Global Comment" but this isn't obvious when using the SDK

Suggestion

One or more of the following would help:

1. Document the limitation — Clarify in the API docs that is_whole and quote are response-only fields, not accepted in the create request body for docx files
2. Separate request/response models — Use a dedicated CreateFileCommentRequestBody that only includes reply_list, instead of reusing FileComment
3. Support inline comments — If this is a missing feature, it would be very useful to support creating inline comments via the API (the UI already supports this)
4. Return an error — If is_whole=False or quote is passed but not supported, return an error code instead of silently ignoring

Environment

• SDK version: latest (lark-oapi from PyPI)
• API base: https://open.larksuite.com/open-apis
• Document type: docx (New Doc)
• Auth: tenant_access_token