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

Bắt đầu với model file_comment.py được tạo và FileCommentBuilder, sau đó tái hiện POST /open-apis/drive/v1/files/{file_token}/comments với file_type=docx bằng request được cung cấp. So sánh các trường của request với response List API nhận được và tài liệu chính thức “Add a Global Comment”. Công việc được xem là hoàn tất khi giới hạn hoặc hành vi được hỗ trợ đã được giải quyết rõ ràng mà không âm thầm bỏ qua các trường.

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