common/hermes
2
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

feat: add Feishu document comment intelligent reply with 3-tier access control

Browse Source 
- Full comment handler: parse drive.notice.comment_add_v1 events, build
  timeline, run agent, deliver reply with chunking support.
- 5 tools: feishu_doc_read, feishu_drive_list_comments,
  feishu_drive_list_comment_replies, feishu_drive_reply_comment,
  feishu_drive_add_comment.
- 3-tier access control rules (exact doc > wildcard "*" > top-level >
  defaults) with per-field fallback. Config via
  ~/.hermes/feishu_comment_rules.json, mtime-cached hot-reload.
- Self-reply filter using generalized self_open_id (supports future
  user-identity subscriptions). Receiver check: only process events
  where the bot is the @mentioned target.
- Smart timeline selection, long text chunking, semantic text extraction,
  session sharing per document, wiki link resolution.

Change-Id: I31e82fd6355173dbcc400b8934b6d9799e3137b9
This commit is contained in:
liujinkun
2026-04-16 20:51:11 +08:00
committed by Teknium
parent 9b14b76eb3
commit 85cdb04bd4
9 changed files with 3059 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

136
tools/feishu_doc_tool.py Normal file
View File

@@ -0,0 +1,136 @@
"""Feishu Document Tool -- read document content via Feishu/Lark API.
Provides ``feishu_doc_read`` for reading document content as plain text.
Uses the same lazy-import + BaseRequest pattern as feishu_comment.py.
"""
import asyncio
import json
import logging
import threading
from tools.registry import registry, tool_error, tool_result
logger = logging.getLogger(__name__)
# Thread-local storage for the lark client injected by feishu_comment handler.
_local = threading.local()
def set_client(client):
"""Store a lark client for the current thread (called by feishu_comment)."""
_local.client = client
def get_client():
"""Return the lark client for the current thread, or None."""
return getattr(_local, "client", None)
# ---------------------------------------------------------------------------
# feishu_doc_read
# ---------------------------------------------------------------------------
_RAW_CONTENT_URI = "/open-apis/docx/v1/documents/:document_id/raw_content"
FEISHU_DOC_READ_SCHEMA = {
"name": "feishu_doc_read",
"description": (
"Read the full content of a Feishu/Lark document as plain text. "
"Useful when you need more context beyond the quoted text in a comment."
),
"parameters": {
"type": "object",
"properties": {
"doc_token": {
"type": "string",
"description": "The document token (from the document URL or comment context).",
},
},
"required": ["doc_token"],
},
}
def _check_feishu():
try:
import lark_oapi # noqa: F401
return True
except ImportError:
return False
def _handle_feishu_doc_read(args: dict, **kwargs) -> str:
doc_token = args.get("doc_token", "").strip()
if not doc_token:
return tool_error("doc_token is required")
client = get_client()
if client is None:
return tool_error("Feishu client not available (not in a Feishu comment context)")
try:
from lark_oapi import AccessTokenType
from lark_oapi.core.enum import HttpMethod
from lark_oapi.core.model.base_request import BaseRequest
except ImportError:
return tool_error("lark_oapi not installed")
request = (
BaseRequest.builder()
.http_method(HttpMethod.GET)
.uri(_RAW_CONTENT_URI)
.token_types({AccessTokenType.TENANT})
.paths({"document_id": doc_token})
.build()
)
try:
response = asyncio.get_event_loop().run_until_complete(
asyncio.to_thread(client.request, request)
)
except RuntimeError:
# No running event loop -- call synchronously
response = client.request(request)
code = getattr(response, "code", None)
if code != 0:
msg = getattr(response, "msg", "unknown error")
return tool_error(f"Failed to read document: code={code} msg={msg}")
raw = getattr(response, "raw", None)
if raw and hasattr(raw, "content"):
try:
body = json.loads(raw.content)
content = body.get("data", {}).get("content", "")
return tool_result(success=True, content=content)
except (json.JSONDecodeError, AttributeError):
pass
# Fallback: try response.data
data = getattr(response, "data", None)
if data:
if isinstance(data, dict):
content = data.get("content", "")
else:
content = getattr(data, "content", str(data))
return tool_result(success=True, content=content)
return tool_error("No content returned from document API")
# ---------------------------------------------------------------------------
# Registration
# ---------------------------------------------------------------------------
registry.register(
name="feishu_doc_read",
toolset="feishu_doc",
schema=FEISHU_DOC_READ_SCHEMA,
handler=_handle_feishu_doc_read,
check_fn=_check_feishu,
requires_env=[],
is_async=False,
description="Read Feishu document content",
emoji="\U0001f4c4",
)

433
tools/feishu_drive_tool.py Normal file
View File

@@ -0,0 +1,433 @@
"""Feishu Drive Tools -- document comment operations via Feishu/Lark API.
Provides tools for listing, replying to, and adding document comments.
Uses the same lazy-import + BaseRequest pattern as feishu_comment.py.
The lark client is injected per-thread by the comment event handler.
"""
import asyncio
import json
import logging
import threading
from tools.registry import registry, tool_error, tool_result
logger = logging.getLogger(__name__)
# Thread-local storage for the lark client injected by feishu_comment handler.
_local = threading.local()
def set_client(client):
"""Store a lark client for the current thread (called by feishu_comment)."""
_local.client = client
def get_client():
"""Return the lark client for the current thread, or None."""
return getattr(_local, "client", None)
def _check_feishu():
try:
import lark_oapi # noqa: F401
return True
except ImportError:
return False
def _do_request(client, method, uri, paths=None, queries=None, body=None):
"""Build and execute a BaseRequest, return (code, msg, data_dict)."""
from lark_oapi import AccessTokenType
from lark_oapi.core.enum import HttpMethod
from lark_oapi.core.model.base_request import BaseRequest
http_method = HttpMethod.GET if method == "GET" else HttpMethod.POST
builder = (
BaseRequest.builder()
.http_method(http_method)
.uri(uri)
.token_types({AccessTokenType.TENANT})
)
if paths:
builder = builder.paths(paths)
if queries:
builder = builder.queries(queries)
if body is not None:
builder = builder.body(body)
request = builder.build()
try:
response = asyncio.get_event_loop().run_until_complete(
asyncio.to_thread(client.request, request)
)
except RuntimeError:
response = client.request(request)
code = getattr(response, "code", None)
msg = getattr(response, "msg", "")
# Parse response data
data = {}
raw = getattr(response, "raw", None)
if raw and hasattr(raw, "content"):
try:
body_json = json.loads(raw.content)
data = body_json.get("data", {})
except (json.JSONDecodeError, AttributeError):
pass
if not data:
resp_data = getattr(response, "data", None)
if isinstance(resp_data, dict):
data = resp_data
elif resp_data and hasattr(resp_data, "__dict__"):
data = vars(resp_data)
return code, msg, data
# ---------------------------------------------------------------------------
# feishu_drive_list_comments
# ---------------------------------------------------------------------------
_LIST_COMMENTS_URI = "/open-apis/drive/v1/files/:file_token/comments"
FEISHU_DRIVE_LIST_COMMENTS_SCHEMA = {
"name": "feishu_drive_list_comments",
"description": (
"List comments on a Feishu document. "
"Use is_whole=true to list whole-document comments only."
),
"parameters": {
"type": "object",
"properties": {
"file_token": {
"type": "string",
"description": "The document file token.",
},
"file_type": {
"type": "string",
"description": "File type (default: docx).",
"default": "docx",
},
"is_whole": {
"type": "boolean",
"description": "If true, only return whole-document comments.",
"default": False,
},
"page_size": {
"type": "integer",
"description": "Number of comments per page (max 100).",
"default": 100,
},
"page_token": {
"type": "string",
"description": "Pagination token for next page.",
},
},
"required": ["file_token"],
},
}
def _handle_list_comments(args: dict, **kwargs) -> str:
client = get_client()
if client is None:
return tool_error("Feishu client not available")
file_token = args.get("file_token", "").strip()
if not file_token:
return tool_error("file_token is required")
file_type = args.get("file_type", "docx") or "docx"
is_whole = args.get("is_whole", False)
page_size = args.get("page_size", 100)
page_token = args.get("page_token", "")
queries = [
("file_type", file_type),
("user_id_type", "open_id"),
("page_size", str(page_size)),
]
if is_whole:
queries.append(("is_whole", "true"))
if page_token:
queries.append(("page_token", page_token))
code, msg, data = _do_request(
client, "GET", _LIST_COMMENTS_URI,
paths={"file_token": file_token},
queries=queries,
)
if code != 0:
return tool_error(f"List comments failed: code={code} msg={msg}")
return tool_result(data)
# ---------------------------------------------------------------------------
# feishu_drive_list_comment_replies
# ---------------------------------------------------------------------------
_LIST_REPLIES_URI = "/open-apis/drive/v1/files/:file_token/comments/:comment_id/replies"
FEISHU_DRIVE_LIST_REPLIES_SCHEMA = {
"name": "feishu_drive_list_comment_replies",
"description": "List all replies in a comment thread on a Feishu document.",
"parameters": {
"type": "object",
"properties": {
"file_token": {
"type": "string",
"description": "The document file token.",
},
"comment_id": {
"type": "string",
"description": "The comment ID to list replies for.",
},
"file_type": {
"type": "string",
"description": "File type (default: docx).",
"default": "docx",
},
"page_size": {
"type": "integer",
"description": "Number of replies per page (max 100).",
"default": 100,
},
"page_token": {
"type": "string",
"description": "Pagination token for next page.",
},
},
"required": ["file_token", "comment_id"],
},
}
def _handle_list_replies(args: dict, **kwargs) -> str:
client = get_client()
if client is None:
return tool_error("Feishu client not available")
file_token = args.get("file_token", "").strip()
comment_id = args.get("comment_id", "").strip()
if not file_token or not comment_id:
return tool_error("file_token and comment_id are required")
file_type = args.get("file_type", "docx") or "docx"
page_size = args.get("page_size", 100)
page_token = args.get("page_token", "")
queries = [
("file_type", file_type),
("user_id_type", "open_id"),
("page_size", str(page_size)),
]
if page_token:
queries.append(("page_token", page_token))
code, msg, data = _do_request(
client, "GET", _LIST_REPLIES_URI,
paths={"file_token": file_token, "comment_id": comment_id},
queries=queries,
)
if code != 0:
return tool_error(f"List replies failed: code={code} msg={msg}")
return tool_result(data)
# ---------------------------------------------------------------------------
# feishu_drive_reply_comment
# ---------------------------------------------------------------------------
_REPLY_COMMENT_URI = "/open-apis/drive/v1/files/:file_token/comments/:comment_id/replies"
FEISHU_DRIVE_REPLY_SCHEMA = {
"name": "feishu_drive_reply_comment",
"description": (
"Reply to a local comment thread on a Feishu document. "
"Use this for local (quoted-text) comments. "
"For whole-document comments, use feishu_drive_add_comment instead."
),
"parameters": {
"type": "object",
"properties": {
"file_token": {
"type": "string",
"description": "The document file token.",
},
"comment_id": {
"type": "string",
"description": "The comment ID to reply to.",
},
"content": {
"type": "string",
"description": "The reply text content (plain text only, no markdown).",
},
"file_type": {
"type": "string",
"description": "File type (default: docx).",
"default": "docx",
},
},
"required": ["file_token", "comment_id", "content"],
},
}
def _handle_reply_comment(args: dict, **kwargs) -> str:
client = get_client()
if client is None:
return tool_error("Feishu client not available")
file_token = args.get("file_token", "").strip()
comment_id = args.get("comment_id", "").strip()
content = args.get("content", "").strip()
if not file_token or not comment_id or not content:
return tool_error("file_token, comment_id, and content are required")
file_type = args.get("file_type", "docx") or "docx"
body = {
"content": {
"elements": [
{
"type": "text_run",
"text_run": {"text": content},
}
]
}
}
code, msg, data = _do_request(
client, "POST", _REPLY_COMMENT_URI,
paths={"file_token": file_token, "comment_id": comment_id},
queries=[("file_type", file_type)],
body=body,
)
if code != 0:
return tool_error(f"Reply comment failed: code={code} msg={msg}")
return tool_result(success=True, data=data)
# ---------------------------------------------------------------------------
# feishu_drive_add_comment
# ---------------------------------------------------------------------------
_ADD_COMMENT_URI = "/open-apis/drive/v1/files/:file_token/new_comments"
FEISHU_DRIVE_ADD_COMMENT_SCHEMA = {
"name": "feishu_drive_add_comment",
"description": (
"Add a new whole-document comment on a Feishu document. "
"Use this for whole-document comments or as a fallback when "
"reply_comment fails with code 1069302."
),
"parameters": {
"type": "object",
"properties": {
"file_token": {
"type": "string",
"description": "The document file token.",
},
"content": {
"type": "string",
"description": "The comment text content (plain text only, no markdown).",
},
"file_type": {
"type": "string",
"description": "File type (default: docx).",
"default": "docx",
},
},
"required": ["file_token", "content"],
},
}
def _handle_add_comment(args: dict, **kwargs) -> str:
client = get_client()
if client is None:
return tool_error("Feishu client not available")
file_token = args.get("file_token", "").strip()
content = args.get("content", "").strip()
if not file_token or not content:
return tool_error("file_token and content are required")
file_type = args.get("file_type", "docx") or "docx"
body = {
"file_type": file_type,
"reply_elements": [
{"type": "text", "text": content},
],
}
code, msg, data = _do_request(
client, "POST", _ADD_COMMENT_URI,
paths={"file_token": file_token},
body=body,
)
if code != 0:
return tool_error(f"Add comment failed: code={code} msg={msg}")
return tool_result(success=True, data=data)
# ---------------------------------------------------------------------------
# Registration
# ---------------------------------------------------------------------------
registry.register(
name="feishu_drive_list_comments",
toolset="feishu_drive",
schema=FEISHU_DRIVE_LIST_COMMENTS_SCHEMA,
handler=_handle_list_comments,
check_fn=_check_feishu,
requires_env=[],
is_async=False,
description="List document comments",
emoji="\U0001f4ac",
)
registry.register(
name="feishu_drive_list_comment_replies",
toolset="feishu_drive",
schema=FEISHU_DRIVE_LIST_REPLIES_SCHEMA,
handler=_handle_list_replies,
check_fn=_check_feishu,
requires_env=[],
is_async=False,
description="List comment replies",
emoji="\U0001f4ac",
)
registry.register(
name="feishu_drive_reply_comment",
toolset="feishu_drive",
schema=FEISHU_DRIVE_REPLY_SCHEMA,
handler=_handle_reply_comment,
check_fn=_check_feishu,
requires_env=[],
is_async=False,
description="Reply to a document comment",
emoji="\u2709\ufe0f",
)
registry.register(
name="feishu_drive_add_comment",
toolset="feishu_drive",
schema=FEISHU_DRIVE_ADD_COMMENT_SCHEMA,
handler=_handle_add_comment,
check_fn=_check_feishu,
requires_env=[],
is_async=False,
description="Add a whole-document comment",
emoji="\u2709\ufe0f",
)