aidev-bkplugin 2.2.2rc310__tar.gz → 2.2.4__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (118) hide show
  1. aidev_bkplugin-2.2.4/PKG-INFO +54 -0
  2. aidev_bkplugin-2.2.4/aidev_bkplugin/apps.py +242 -0
  3. aidev_bkplugin-2.2.4/aidev_bkplugin/migrations/0002_event_delivery.py +47 -0
  4. aidev_bkplugin-2.2.4/aidev_bkplugin/models.py +85 -0
  5. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/packages/checkpoint/bk_django_saver.py +126 -31
  6. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/packages/drf/renderers.py +8 -1
  7. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/serializers/chat_completion.py +2 -1
  8. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/services/agent_bkplugin.py +1 -0
  9. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/services/agent_builder.py +19 -5
  10. aidev_bkplugin-2.2.4/aidev_bkplugin/services/agent_config.py +254 -0
  11. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/services/agent_execution.py +34 -10
  12. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/services/agent_session.py +40 -6
  13. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/services/approval_resume.py +68 -12
  14. aidev_bkplugin-2.2.4/aidev_bkplugin/services/chat_tracing.py +34 -0
  15. aidev_bkplugin-2.2.4/aidev_bkplugin/services/database_event_bus.py +165 -0
  16. aidev_bkplugin-2.2.4/aidev_bkplugin/services/event_resource_manager.py +37 -0
  17. aidev_bkplugin-2.2.4/aidev_bkplugin/services/event_tracing.py +39 -0
  18. aidev_bkplugin-2.2.4/aidev_bkplugin/services/execution.py +181 -0
  19. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/services/llm.py +8 -4
  20. aidev_bkplugin-2.2.4/aidev_bkplugin/services/metric_runtime.py +30 -0
  21. aidev_bkplugin-2.2.4/aidev_bkplugin/services/otel_metrics.py +495 -0
  22. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/settings.py +8 -10
  23. aidev_bkplugin-2.2.4/aidev_bkplugin/tasks.py +82 -0
  24. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/views/agent.py +0 -2
  25. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/views/base.py +2 -1
  26. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/views/chat.py +25 -16
  27. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/views/flow_agent.py +3 -2
  28. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/views/llm.py +1 -0
  29. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/views/session.py +83 -16
  30. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/pyproject.toml +8 -2
  31. aidev_bkplugin-2.2.4/readme.md +42 -0
  32. aidev_bkplugin-2.2.4/tests/database_events/conftest.py +29 -0
  33. aidev_bkplugin-2.2.4/tests/database_events/test_bus.py +143 -0
  34. aidev_bkplugin-2.2.4/tests/database_events/test_resource_manager.py +40 -0
  35. aidev_bkplugin-2.2.4/tests/database_events/test_tracing.py +34 -0
  36. aidev_bkplugin-2.2.4/tests/packages/drf/test_renderers_trace.py +25 -0
  37. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/tests/packages/test_bk_django_saver.py +115 -3
  38. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/tests/packages/test_bk_django_saver_async.py +19 -0
  39. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/tests/services/agent/test_agent_config_fetcher.py +115 -17
  40. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/tests/services/agent/test_builder.py +10 -4
  41. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/tests/services/agent/test_session_manager.py +50 -4
  42. aidev_bkplugin-2.2.4/tests/services/test_approval_resume.py +31 -0
  43. aidev_bkplugin-2.2.4/tests/services/test_approval_resume_tracing.py +83 -0
  44. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/tests/services/test_bkplugin.py +15 -3
  45. aidev_bkplugin-2.2.4/tests/services/test_chat_tracing.py +23 -0
  46. aidev_bkplugin-2.2.4/tests/services/test_event_tracing.py +27 -0
  47. aidev_bkplugin-2.2.4/tests/services/test_execution.py +56 -0
  48. aidev_bkplugin-2.2.4/tests/services/test_llm.py +35 -0
  49. aidev_bkplugin-2.2.4/tests/services/test_otel_metrics.py +610 -0
  50. aidev_bkplugin-2.2.4/tests/services/test_resume_consumer.py +33 -0
  51. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/tests/services/test_thread_chat_completion.py +36 -0
  52. aidev_bkplugin-2.2.4/tests/test_apps.py +236 -0
  53. aidev_bkplugin-2.2.4/tests/test_management_metrics.py +104 -0
  54. aidev_bkplugin-2.2.4/tests/views/__init__.py +0 -0
  55. aidev_bkplugin-2.2.4/tests/views/test_agent_view.py +57 -0
  56. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/tests/views/test_chat_agent_code_propagation.py +7 -2
  57. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/tests/views/test_chat_completion_serializer.py +23 -1
  58. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/tests/views/test_session_pv_files_views.py +112 -20
  59. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/tests/views/test_session_view.py +172 -1
  60. aidev_bkplugin-2.2.2rc310/PKG-INFO +0 -40
  61. aidev_bkplugin-2.2.2rc310/aidev_bkplugin/apps.py +0 -117
  62. aidev_bkplugin-2.2.2rc310/aidev_bkplugin/models.py +0 -47
  63. aidev_bkplugin-2.2.2rc310/aidev_bkplugin/services/agent_config.py +0 -199
  64. aidev_bkplugin-2.2.2rc310/aidev_bkplugin/tasks.py +0 -32
  65. aidev_bkplugin-2.2.2rc310/readme.md +0 -30
  66. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/__init__.py +0 -0
  67. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/constants.py +0 -0
  68. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/enums.py +0 -0
  69. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/management/__init__.py +0 -0
  70. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/management/commands/__init__.py +0 -0
  71. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/management/commands/upgrade_sessions.py +0 -0
  72. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/migrations/0001_initial.py +0 -0
  73. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/migrations/__init__.py +0 -0
  74. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/openapi/__init__.py +0 -0
  75. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/openapi/urls.py +0 -0
  76. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/openapi/views.py +0 -0
  77. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/packages/__init__.py +0 -0
  78. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/packages/apigw/__init__.py +0 -0
  79. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/packages/apigw/permissions.py +0 -0
  80. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/packages/checkpoint/__init__.py +0 -0
  81. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/packages/drf/__init__.py +0 -0
  82. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/packages/drf/authentication.py +0 -0
  83. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/packages/drf/decorators.py +0 -0
  84. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/packages/drf/exception.py +0 -0
  85. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/permissions.py +0 -0
  86. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/private/__init__.py +0 -0
  87. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/private/permissions.py +0 -0
  88. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/private/urls.py +0 -0
  89. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/private/views.py +0 -0
  90. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/serializers/__init__.py +0 -0
  91. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/serializers/agent.py +0 -0
  92. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/serializers/llm.py +0 -0
  93. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/serializers/user_operation.py +0 -0
  94. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/services/__init__.py +0 -0
  95. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/services/agent_helpers.py +0 -0
  96. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/services/user_operation.py +0 -0
  97. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/urls.py +0 -0
  98. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/utils.py +0 -0
  99. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/views/__init__.py +0 -0
  100. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/views/chat_group.py +0 -0
  101. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/aidev_bkplugin/views/user_operation.py +0 -0
  102. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/tests/__init__.py +0 -0
  103. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/tests/apps.py +0 -0
  104. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/tests/conftest.py +0 -0
  105. {aidev_bkplugin-2.2.2rc310/tests/packages → aidev_bkplugin-2.2.4/tests/database_events}/__init__.py +0 -0
  106. {aidev_bkplugin-2.2.2rc310/tests/views → aidev_bkplugin-2.2.4/tests/packages}/__init__.py +0 -0
  107. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/tests/private/__init__.py +0 -0
  108. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/tests/private/test_private_views.py +0 -0
  109. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/tests/services/__init__.py +0 -0
  110. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/tests/services/agent/__init__.py +0 -0
  111. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/tests/services/agent/conftest.py +0 -0
  112. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/tests/services/test_agent_completion.py +0 -0
  113. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/tests/services/test_agui_handler.py +0 -0
  114. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/tests/services/test_user_operation.py +0 -0
  115. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/tests/settings.py +0 -0
  116. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/tests/test_constants.py +0 -0
  117. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/tests/views/test_chat_flow_agent.py +0 -0
  118. {aidev_bkplugin-2.2.2rc310 → aidev_bkplugin-2.2.4}/tests/views/test_chat_stream_status.py +0 -0
@@ -0,0 +1,54 @@
1
+ Metadata-Version: 2.1
2
+ Name: aidev-bkplugin
3
+ Version: 2.2.4
4
+ Summary: AiDev Agent Bkplugin builtin functions
5
+ Requires-Python: <3.12,>=3.11
6
+ Requires-Dist: aidev-agent>=2.2.4
7
+ Requires-Dist: blueapps<5.0,>=4.15.1
8
+ Requires-Dist: django<5.0,>=4.2.28
9
+ Provides-Extra: opentelemetry
10
+ Requires-Dist: aidev-agent[opentelemetry]>=2.2.2rc17; extra == "opentelemetry"
11
+ Description-Content-Type: text/markdown
12
+
13
+ # AI 小鲸后台服务
14
+
15
+ 本插件需与智能体模板配合使用,用于开发和管理智能体插件。
16
+
17
+ 审批 Web 回调与企业微信跨进程联动见 [DatabaseEventBus 使用说明](docs/database-events.md)。
18
+
19
+ ## 管理命令的指标和 Trace 采集
20
+
21
+ 通过 `manage.py` 或 `django-admin` 运行一次性管理命令(如 `migrate`、
22
+ `collectstatic`、`shell`)时,插件同时关闭指标和 Trace,避免进程退出时等待上报,
23
+ 也不会为初始化 OT 获取远程配置。
24
+ 该策略同时覆盖直连 OTLP 和经 Celery 上报,即使环境或平台配置启用了指标也不会启动。
25
+
26
+ `runserver`、`celery`(含 worker/beat)、`run_wxaibot_ws` 保留原有指标和 Trace 配置;
27
+ 直接启动的 Gunicorn、Celery 不受影响。常规应用日志不变。
28
+ 策略位于插件初始化入口,已有模板升级插件即可生效,无需修改 `bin/manage.py`。
29
+
30
+ ## 本地调试智能体插件
31
+
32
+ ### 环境准备
33
+
34
+ 在开始前,请确保已安装以下工具:
35
+ - `uv`: Python 包管理工具
36
+ - `cookiecutter`: 项目模板工具
37
+
38
+ ### SDK 打包
39
+
40
+ 在 Git 仓库根目录执行以下命令,构建小鲸智能体插件:
41
+
42
+ ```bash
43
+ make build-aidev-bkplugin
44
+ ```
45
+
46
+ ### 生成测试智能体
47
+
48
+ 使用 cookiecutter 快速生成示例智能体,可在任意目录执行:
49
+
50
+ ```bash
51
+ GIT_ROOT=$(git rev-parse --show-toplevel)
52
+ cd /tmp
53
+ python -m cookiecutter ${GIT_ROOT} --directory template/builtin --no-input
54
+ ```
@@ -0,0 +1,242 @@
1
+ # -*- coding: utf-8 -*-
2
+
3
+ import logging
4
+ import sys
5
+ from pathlib import Path
6
+
7
+ from aidev_agent.utils.module_loading import import_string
8
+ from django.apps import AppConfig
9
+ from django.conf import settings
10
+
11
+ from aidev_bkplugin.services.metric_runtime import set_metric_service
12
+
13
+ try:
14
+ import bkoauth
15
+ except ImportError:
16
+ bkoauth = None
17
+
18
+ # OpenTelemetry 是可选 extras,未安装时降级为 no-op。
19
+ # 安装方式:pip install aidev-bkplugin[opentelemetry]
20
+ try:
21
+ from aidev_agent.packages.opentelemetry import BkAidevAgentInstrumentor
22
+ from aidev_agent.packages.opentelemetry.config import OTelConfig
23
+ from aidev_agent.packages.opentelemetry.utils import (
24
+ get_otel_endpoint_by_agent_info,
25
+ get_otel_endpoint_by_env,
26
+ get_otel_endpoint_by_json_str,
27
+ )
28
+ except ImportError:
29
+ BkAidevAgentInstrumentor = None
30
+ OTelConfig = None
31
+ get_otel_endpoint_by_agent_info = None
32
+ get_otel_endpoint_by_env = None
33
+ get_otel_endpoint_by_json_str = None
34
+
35
+ try:
36
+ from aidev_agent.packages.opentelemetry.metrics import configure_metric_identity
37
+
38
+ from aidev_bkplugin.services.otel_metrics import (
39
+ BkPluginMetricService,
40
+ MetricExportSettings,
41
+ )
42
+ except ImportError:
43
+ configure_metric_identity = None
44
+ BkPluginMetricService = None
45
+ MetricExportSettings = None
46
+
47
+ try:
48
+ from aidev_bkplugin.tasks import enqueue_bkm_metrics_task
49
+ except ImportError:
50
+ enqueue_bkm_metrics_task = None
51
+
52
+ try:
53
+ from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor
54
+ except ImportError:
55
+ HTTPXClientInstrumentor = None
56
+
57
+ try:
58
+ from opentelemetry.instrumentation.threading import ThreadingInstrumentor
59
+ except ImportError:
60
+ ThreadingInstrumentor = None
61
+
62
+ logger = logging.getLogger(__name__)
63
+
64
+
65
+ def _deduplicate_otel_endpoints(endpoints: list[dict]) -> list[dict]:
66
+ """Keep the highest-priority config for each effective OTLP destination."""
67
+ deduplicated = []
68
+ seen = set()
69
+ for endpoint in endpoints:
70
+ exporter_type = endpoint.get("exporter_type")
71
+ exporter_type = getattr(exporter_type, "value", exporter_type)
72
+ identity = (
73
+ str(endpoint.get("url", "")).rstrip("/"),
74
+ str(exporter_type),
75
+ str(endpoint.get("token", "")),
76
+ )
77
+ if identity in seen:
78
+ continue
79
+ seen.add(identity)
80
+ deduplicated.append(endpoint)
81
+ return deduplicated
82
+
83
+
84
+ def _is_one_off_management_command() -> bool:
85
+ if not sys.argv or Path(sys.argv[0]).name not in {"manage.py", "django-admin", "django-admin.py"}:
86
+ return False
87
+ return sys.argv[1:2] not in (["runserver"], ["celery"], ["run_wxaibot_ws"])
88
+
89
+
90
+ def init_bk_aidev_agent_otel() -> None:
91
+ """
92
+ 初始化 BK AIDEV Agent OpenTelemetry。
93
+
94
+ 按优先级收集所有 OTEL Endpoint 配置:
95
+ 1. BKAI_AGENT_OTEL_ENDPOINTS 环境变量(支持多地址)
96
+ 2. agent_info 中的 otel_url / otel_token(单地址)
97
+ 3. OTEL_GRPC_URL + OTEL_BK_DATA_TOKEN 环境变量(单地址)
98
+
99
+ 如果未安装 opentelemetry extras,跳过初始化。
100
+ """
101
+ if BkAidevAgentInstrumentor is None:
102
+ logger.info(
103
+ "[aidev_bkplugin] OpenTelemetry extras 未安装,跳过自动 instrument;"
104
+ "如需启用请安装 aidev-bkplugin[opentelemetry]。"
105
+ )
106
+ return
107
+
108
+ # 先解析全局开关,避免本地评测或显式关闭 OTel 的进程仍为 endpoint/identity
109
+ # 发起 Agent 配置远程请求。默认值保持开启,不改变线上既有初始化行为。
110
+ otel_config = OTelConfig(otel_endpoints=[])
111
+ if not getattr(otel_config, "enabled", True):
112
+ logger.info("[aidev_bkplugin] OpenTelemetry disabled; remote initialization skipped")
113
+ set_metric_service(None)
114
+ return
115
+
116
+ if _is_one_off_management_command():
117
+ # 一次性命令不采集指标或 Trace,避免退出时等待上报;无需获取远程 OT 配置。
118
+ otel_config.enable_metrics = False
119
+ otel_config.enable_traces = False
120
+ set_metric_service(None)
121
+ BkAidevAgentInstrumentor(config=otel_config).instrument()
122
+ logger.info("[aidev_bkplugin] metrics and traces disabled for one-off management command")
123
+ return
124
+
125
+ if getattr(otel_config, "trace_exporter", "otlp") == "logging":
126
+ # 本地评测只需要 trace/span,禁用远程 endpoint 探测和指标上报,
127
+ # 由 Agent SDK 的 LoggingSpanExporter 写入应用日志。
128
+ otel_config.enable_metrics = False
129
+ otel_config.enable_logs = False
130
+ set_metric_service(None)
131
+ BkAidevAgentInstrumentor(config=otel_config).instrument()
132
+ logger.info("[aidev_bkplugin] OpenTelemetry local logging export enabled")
133
+ return
134
+
135
+ from aidev_bkplugin.services.agent_config import AgentConfigFetcher
136
+
137
+ endpoints = []
138
+ # 1. 从 BKAI_AGENT_OTEL_ENDPOINTS 解析多地址
139
+ try:
140
+ endpoints.extend(get_otel_endpoint_by_json_str())
141
+ except ValueError as e:
142
+ logger.warning(
143
+ "[aidev_bkplugin] 解析 BKAI_AGENT_OTEL_ENDPOINTS 失败:%s,跳过该配置来源。",
144
+ e,
145
+ )
146
+ # 2. 从 agent_info 获取单地址
147
+ agent_info = AgentConfigFetcher.get_info()
148
+ endpoints.extend(get_otel_endpoint_by_agent_info(agent_info=agent_info))
149
+ # 3. 从 OTEL_GRPC_URL 和 OTEL_BK_DATA_TOKEN 获取单地址
150
+ endpoints.extend(get_otel_endpoint_by_env())
151
+ deduplicated_endpoints = _deduplicate_otel_endpoints(endpoints)
152
+ if len(deduplicated_endpoints) != len(endpoints):
153
+ logger.info(
154
+ "[aidev_bkplugin] removed %d duplicate OpenTelemetry endpoint(s)",
155
+ len(endpoints) - len(deduplicated_endpoints),
156
+ )
157
+ endpoints = deduplicated_endpoints
158
+
159
+ otel_config.otel_endpoints = endpoints
160
+ if configure_metric_identity is None or BkPluginMetricService is None or MetricExportSettings is None:
161
+ logger.info("[aidev_bkplugin] metric OpenTelemetry extras unavailable; metric export skipped")
162
+ otel_config.enable_metrics = False
163
+ BkAidevAgentInstrumentor(config=otel_config).instrument()
164
+ return
165
+ try:
166
+ metric_settings = MetricExportSettings.from_agent_info(
167
+ agent_info,
168
+ default_enabled=otel_config.enable_metrics,
169
+ )
170
+ otel_config.enable_metrics = metric_settings.enabled
171
+ otel_config.metric_export_interval_millis = metric_settings.export_interval_millis
172
+ otel_config.metric_export_timeout_millis = metric_settings.export_timeout_millis
173
+ configure_metric_identity(
174
+ agent_info.get("agent_code") or otel_config.service_name,
175
+ agent_info.get("agent_name"),
176
+ agent_info.get("agent_sdk_version"),
177
+ )
178
+ if metric_settings.has_bkm_config:
179
+ metric_service = BkPluginMetricService(
180
+ service_name=otel_config.service_name,
181
+ endpoints=endpoints,
182
+ agent_info=agent_info,
183
+ settings=metric_settings,
184
+ enqueue_bkm_metrics=enqueue_bkm_metrics_task,
185
+ )
186
+ set_metric_service(metric_service)
187
+ otel_config.enable_metrics = metric_service.start()
188
+ otel_config.metric_provider_managed_externally = otel_config.enable_metrics
189
+ if not otel_config.enable_metrics:
190
+ set_metric_service(None)
191
+ else:
192
+ # 直连 OTLP 继续复用 Agent SDK 原有的 MetricProvider / MetricExporter;
193
+ # bkplugin 只负责根据 agent_info 选择该路径并传入配置。
194
+ set_metric_service(None)
195
+ otel_config.metric_provider_managed_externally = False
196
+ except Exception: # noqa: BLE001
197
+ logger.exception("[aidev_bkplugin] metric export initialization failed; continuing without metrics")
198
+ set_metric_service(None)
199
+ otel_config.enable_metrics = False
200
+ BkAidevAgentInstrumentor(config=otel_config).instrument()
201
+
202
+
203
+ class AgentConfig(AppConfig):
204
+ default_auto_field = "django.db.models.BigAutoField"
205
+ name = "aidev_bkplugin"
206
+
207
+ def ready(self) -> None:
208
+ from aidev_agent.packages.resource_manager import resource_manager
209
+ from aidev_agent.services.common_agent import (
210
+ CommonQAAgent,
211
+ common_agent_factory,
212
+ )
213
+
214
+ if bkoauth:
215
+ bkoauth._init_function()
216
+
217
+ # 仅当 AIDEV_AGENT 解析出的类与 SDK 默认 CommonQAAgent 不一致时,实例化后注入;
218
+ # 缺省值即继续使用 SDK 默认实例(来自 common_agent_factory 的 default)。
219
+ custom_agent_cls = import_string(settings.AIDEV_AGENT)
220
+ if custom_agent_cls is not CommonQAAgent:
221
+ common_agent_factory.replace_defaults(custom_agent_cls())
222
+
223
+ custom_resource_manager = getattr(settings, "AIDEV_RESOURCE_MANAGER", "")
224
+ if custom_resource_manager:
225
+ resource_manager.replace_defaults(import_string(custom_resource_manager)())
226
+
227
+ # 初始化 OpenTelemetry
228
+ init_bk_aidev_agent_otel()
229
+
230
+ # 注入 httpx (LLM 网关底层 HTTP 客户端) 的 trace 传播
231
+ # 使 LLM 调用自动携带 traceparent header,网关可加入分布式追踪
232
+ try:
233
+ HTTPXClientInstrumentor().instrument()
234
+ except Exception: # noqa: BLE001
235
+ logger.debug("opentelemetry-instrumentation-httpx not available, skipping httpx instrumentation")
236
+ # 注入跨线程的 trace 传递,因为知识库中 LLM 提交是异步的
237
+ try:
238
+ ThreadingInstrumentor().instrument()
239
+ except Exception: # noqa: BLE001
240
+ logger.debug("opentelemetry-instrumentation-threading not available, skipping httpx instrumentation")
241
+
242
+ return super().ready()
@@ -0,0 +1,47 @@
1
+ from django.db import migrations, models
2
+ import django.db.models.deletion
3
+
4
+
5
+ class Migration(migrations.Migration):
6
+ dependencies = [("aidev_bkplugin", "0001_initial")]
7
+
8
+ operations = [
9
+ migrations.CreateModel(
10
+ name="EventSubscription",
11
+ fields=[
12
+ ("id", models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name="ID")),
13
+ ("key", models.CharField(max_length=64, unique=True)),
14
+ ("scope_key", models.CharField(max_length=64, db_index=True)),
15
+ ("subscriber", models.CharField(max_length=255)),
16
+ ("event_name", models.CharField(max_length=128)),
17
+ ("app_code", models.CharField(max_length=255)),
18
+ ("session_code", models.CharField(max_length=255)),
19
+ ("enabled", models.BooleanField(default=True)),
20
+ ("property", models.JSONField(default=dict)),
21
+ ("created_at", models.DateTimeField(auto_now_add=True)),
22
+ ],
23
+ ),
24
+ migrations.CreateModel(
25
+ name="EventDelivery",
26
+ fields=[
27
+ ("id", models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name="ID")),
28
+ ("event_id", models.CharField(max_length=64)),
29
+ ("envelope", models.JSONField(default=dict)),
30
+ ("route", models.JSONField(default=dict)),
31
+ ("status", models.CharField(default="pending", max_length=16)),
32
+ ("attempts", models.PositiveIntegerField(default=0)),
33
+ ("available_at", models.DateTimeField()),
34
+ ("lease_token", models.CharField(default="", max_length=32)),
35
+ ("lease_until", models.DateTimeField(null=True)),
36
+ ("progress", models.PositiveIntegerField(default=0)),
37
+ ("error_type", models.CharField(default="", max_length=128)),
38
+ ("created_at", models.DateTimeField(auto_now_add=True)),
39
+ ("updated_at", models.DateTimeField(auto_now=True)),
40
+ ("subscription", models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to="aidev_bkplugin.eventsubscription")),
41
+ ],
42
+ options={
43
+ "indexes": [models.Index(fields=["status", "available_at"], name="event_delivery_ready")],
44
+ "constraints": [models.UniqueConstraint(fields=("subscription", "event_id"), name="unique_event_delivery")],
45
+ },
46
+ ),
47
+ ]
@@ -0,0 +1,85 @@
1
+ # -*- coding: utf-8 -*-
2
+
3
+ from django.db import models
4
+
5
+ __all__ = ["Checkpoint", "Write", "EventSubscription", "EventDelivery"]
6
+
7
+
8
+ class Checkpoint(models.Model):
9
+ thread_id = models.CharField(max_length=255)
10
+ checkpoint_ns = models.CharField(max_length=255, default="")
11
+ checkpoint_id = models.CharField(max_length=255)
12
+ parent_checkpoint_id = models.TextField(null=True, blank=True)
13
+ type = models.TextField(null=True, blank=True)
14
+ checkpoint = models.BinaryField()
15
+ metadata = models.JSONField(default=dict)
16
+ created_at = models.DateTimeField(auto_now_add=True, null=True)
17
+ updated_at = models.DateTimeField(auto_now=True, null=True)
18
+
19
+ class Meta:
20
+ indexes = [
21
+ models.Index(fields=["thread_id", "checkpoint_ns"]),
22
+ models.Index(fields=["checkpoint_id"]),
23
+ models.Index(fields=["created_at"]),
24
+ models.Index(fields=["updated_at"]), # 清理任务使用此索引
25
+ ]
26
+
27
+
28
+ class Write(models.Model):
29
+ thread_id = models.CharField(max_length=255)
30
+ checkpoint_ns = models.CharField(max_length=255, default="")
31
+ checkpoint_id = models.CharField(max_length=255)
32
+ task_id = models.CharField(max_length=255)
33
+ task_path = models.TextField()
34
+ idx = models.IntegerField()
35
+ channel = models.TextField()
36
+ type = models.TextField(null=True, blank=True)
37
+ value = models.BinaryField()
38
+ created_at = models.DateTimeField(auto_now_add=True, null=True)
39
+ updated_at = models.DateTimeField(auto_now=True, null=True)
40
+
41
+ class Meta:
42
+ indexes = [
43
+ models.Index(fields=["thread_id", "checkpoint_ns", "checkpoint_id"]),
44
+ models.Index(fields=["task_id", "idx"]),
45
+ models.Index(fields=["created_at"]),
46
+ models.Index(fields=["updated_at"]), # 清理任务使用此索引
47
+ ]
48
+
49
+
50
+ class EventSubscription(models.Model):
51
+ """Durable, application/session-scoped subscription, installed by trusted code."""
52
+
53
+ key = models.CharField(max_length=64, unique=True)
54
+ scope_key = models.CharField(max_length=64, db_index=True)
55
+ subscriber = models.CharField(max_length=255)
56
+ event_name = models.CharField(max_length=128)
57
+ app_code = models.CharField(max_length=255)
58
+ session_code = models.CharField(max_length=255)
59
+ enabled = models.BooleanField(default=True)
60
+ property = models.JSONField(default=dict)
61
+ created_at = models.DateTimeField(auto_now_add=True)
62
+
63
+
64
+ class EventDelivery(models.Model):
65
+ """One immutable event per subscriber; the lease/progress belong to delivery."""
66
+
67
+ subscription = models.ForeignKey(EventSubscription, on_delete=models.CASCADE)
68
+ event_id = models.CharField(max_length=64)
69
+ envelope = models.JSONField(default=dict)
70
+ route = models.JSONField(default=dict)
71
+ status = models.CharField(max_length=16, default="pending")
72
+ attempts = models.PositiveIntegerField(default=0)
73
+ available_at = models.DateTimeField()
74
+ lease_token = models.CharField(max_length=32, default="")
75
+ lease_until = models.DateTimeField(null=True)
76
+ progress = models.PositiveIntegerField(default=0)
77
+ error_type = models.CharField(max_length=128, default="")
78
+ created_at = models.DateTimeField(auto_now_add=True)
79
+ updated_at = models.DateTimeField(auto_now=True)
80
+
81
+ class Meta:
82
+ constraints = [
83
+ models.UniqueConstraint(fields=["subscription", "event_id"], name="unique_event_delivery"),
84
+ ]
85
+ indexes = [models.Index(fields=["status", "available_at"], name="event_delivery_ready")]
@@ -19,14 +19,17 @@ to the current version of the project delivered to anyone in the future.
19
19
  from __future__ import annotations
20
20
 
21
21
  import json
22
+ import logging
22
23
  import random
23
24
  import threading
24
25
  import time
25
26
  from collections.abc import AsyncIterator, Iterator, Sequence
26
- from typing import Any, Optional, Tuple, cast
27
+ from contextlib import contextmanager, suppress
28
+ from typing import Any, Callable, Optional, Tuple, cast
27
29
 
28
30
  from asgiref.sync import sync_to_async
29
- from django.db import OperationalError, close_old_connections, connections, router, transaction
31
+ from django.conf import settings
32
+ from django.db import InterfaceError, OperationalError, close_old_connections, connections, router, transaction
30
33
  from langchain_core.runnables import RunnableConfig
31
34
  from langgraph.checkpoint.base import (
32
35
  WRITES_IDX_MAP,
@@ -42,9 +45,95 @@ from langgraph.checkpoint.base import (
42
45
  from langgraph.checkpoint.serde.jsonplus import JsonPlusSerializer
43
46
  from langgraph.checkpoint.serde.types import ChannelProtocol
44
47
 
48
+ logger = logging.getLogger(__name__)
49
+
45
50
  RETRYABLE_DATABASE_ERROR_CODES = {1205, 1213}
51
+ # 服务端或中间代理关闭连接后,客户端要到下一次使用时才发现;语句本身没有问题,重建连接即可恢复。
52
+ CONNECTION_LOST_DATABASE_ERROR_CODES = {2006, 2013, 2055}
46
53
  CHECKPOINT_WRITE_MAX_RETRIES = 3
47
54
  CHECKPOINT_WRITE_RETRY_DELAY_SECONDS = 0.05
55
+ _SQLITE_WRITE_LOCKS: dict[str, threading.RLock] = {}
56
+ _SQLITE_WRITE_LOCKS_GUARD = threading.Lock()
57
+
58
+
59
+ def _database_vendor(model) -> tuple[str, str]:
60
+ alias = router.db_for_write(model)
61
+ return alias, connections[alias].vendor
62
+
63
+
64
+ @contextmanager
65
+ def _database_write_lock(model):
66
+ """Serialize only local SQLite writes across saver instances in this process."""
67
+ alias, vendor = _database_vendor(model)
68
+ if vendor != "sqlite":
69
+ yield
70
+ return
71
+
72
+ with _SQLITE_WRITE_LOCKS_GUARD:
73
+ lock = _SQLITE_WRITE_LOCKS.setdefault(alias, threading.RLock())
74
+ with lock:
75
+ yield
76
+
77
+
78
+ def _is_connection_lost_error(exc: Exception) -> bool:
79
+ """判断异常是否来自已经失效的数据库连接。
80
+
81
+ ``InterfaceError`` 表示驱动层连接已不可用(例如 socket 已被置空),
82
+ ``CONNECTION_LOST_DATABASE_ERROR_CODES`` 表示连接在使用中被对端关闭。
83
+ """
84
+ if isinstance(exc, InterfaceError):
85
+ return True
86
+ error_code = exc.args[0] if exc.args else None
87
+ return error_code in CONNECTION_LOST_DATABASE_ERROR_CODES
88
+
89
+
90
+ def _is_retryable_database_error(exc: Exception, model) -> bool:
91
+ error_code = exc.args[0] if exc.args else None
92
+ if error_code in RETRYABLE_DATABASE_ERROR_CODES:
93
+ return True
94
+ if _is_connection_lost_error(exc):
95
+ return True
96
+ _, vendor = _database_vendor(model)
97
+ return vendor == "sqlite" and "database is locked" in str(exc).lower()
98
+
99
+
100
+ def _discard_connection(model) -> None:
101
+ """丢弃写库当前线程持有的连接,确保重试不会复用同一个坏 socket。
102
+
103
+ 只靠 ``close_old_connections()`` 不够:它依赖 ``CONN_MAX_AGE`` 是否到期以及驱动 ping 的结果,
104
+ 而 pymysql 的 ``ping()`` 默认会自动重连并把连接判定为可用。
105
+ """
106
+ alias, _ = _database_vendor(model)
107
+ with suppress(Exception):
108
+ connections[alias].close()
109
+
110
+
111
+ def _is_best_effort_write() -> bool:
112
+ """连接持续不可用时,是否放弃本次写入而不是让整轮会话失败。"""
113
+ return bool(getattr(settings, "CHECKPOINT_WRITE_BEST_EFFORT", True))
114
+
115
+
116
+ def _run_database_write_with_retry(operation: Callable[[], None], model, description: str = "") -> None:
117
+ for attempt in range(CHECKPOINT_WRITE_MAX_RETRIES):
118
+ try:
119
+ operation()
120
+ return
121
+ except (OperationalError, InterfaceError) as exc:
122
+ connection_lost = _is_connection_lost_error(exc)
123
+ exhausted = attempt == CHECKPOINT_WRITE_MAX_RETRIES - 1
124
+ if not _is_retryable_database_error(exc, model):
125
+ raise
126
+ if exhausted:
127
+ if not (connection_lost and _is_best_effort_write()):
128
+ raise
129
+ # 推理结果由平台侧单独持久化,这里放弃写入只影响 interrupt / resume 的可恢复性,
130
+ # 比让已经产出回答的会话整体失败更可接受。
131
+ logger.exception("放弃 checkpoint 写入,数据库连接持续不可用:%s", description)
132
+ return
133
+ if connection_lost:
134
+ _discard_connection(model)
135
+ close_old_connections()
136
+ time.sleep(CHECKPOINT_WRITE_RETRY_DELAY_SECONDS * (2**attempt))
48
137
 
49
138
 
50
139
  async def run_db_in_thread(func, *args, **kwargs):
@@ -628,28 +717,27 @@ class BKDjangoSaver(BaseCheckpointSaver[str]):
628
717
  raw_metadata = get_checkpoint_metadata(config, metadata)
629
718
  # 通过 json 序列化再反序列化来确保所有值都是 JSON 兼容类型
630
719
  serialized_metadata = json.loads(json.dumps(raw_metadata, default=str).replace("\\u0000", ""))
631
- # 使用Django的update_or_create方法
632
- with self.lock:
633
- for attempt in range(CHECKPOINT_WRITE_MAX_RETRIES):
634
- try:
635
- self.checkpoint_model.objects.update_or_create(
636
- thread_id=thread_id,
637
- checkpoint_ns=checkpoint_ns,
638
- checkpoint_id=checkpoint["id"],
639
- defaults={
640
- "parent_checkpoint_id": config["configurable"].get("checkpoint_id"),
641
- "type": type_,
642
- "checkpoint": serialized_checkpoint,
643
- "metadata": serialized_metadata,
644
- },
645
- )
646
- break
647
- except OperationalError as exc:
648
- error_code = exc.args[0] if exc.args else None
649
- if error_code not in RETRYABLE_DATABASE_ERROR_CODES or attempt == CHECKPOINT_WRITE_MAX_RETRIES - 1:
650
- raise
651
- close_old_connections()
652
- time.sleep(CHECKPOINT_WRITE_RETRY_DELAY_SECONDS * (2**attempt))
720
+
721
+ def save_checkpoint() -> None:
722
+ self.checkpoint_model.objects.update_or_create(
723
+ thread_id=thread_id,
724
+ checkpoint_ns=checkpoint_ns,
725
+ checkpoint_id=checkpoint["id"],
726
+ defaults={
727
+ "parent_checkpoint_id": config["configurable"].get("checkpoint_id"),
728
+ "type": type_,
729
+ "checkpoint": serialized_checkpoint,
730
+ "metadata": serialized_metadata,
731
+ },
732
+ )
733
+
734
+ # SQLite 只允许单写者;跨 saver 实例串行本进程写入,MySQL 等数据库仍保持并行。
735
+ with self.lock, _database_write_lock(self.checkpoint_model):
736
+ _run_database_write_with_retry(
737
+ save_checkpoint,
738
+ self.checkpoint_model,
739
+ f"checkpoint thread_id={thread_id} checkpoint_id={checkpoint['id']}",
740
+ )
653
741
 
654
742
  return {
655
743
  "configurable": {
@@ -681,11 +769,10 @@ class BKDjangoSaver(BaseCheckpointSaver[str]):
681
769
  checkpoint_id = str(config["configurable"]["checkpoint_id"])
682
770
  writes_objects = []
683
771
 
684
- with self.lock:
685
- for idx, (channel, value) in enumerate(writes):
686
- type_, serialized_value = self.serde.dumps_typed(value)
687
-
688
- write_obj = self.writes_model(
772
+ for idx, (channel, value) in enumerate(writes):
773
+ type_, serialized_value = self.serde.dumps_typed(value)
774
+ writes_objects.append(
775
+ self.writes_model(
689
776
  thread_id=thread_id,
690
777
  checkpoint_ns=checkpoint_ns,
691
778
  checkpoint_id=checkpoint_id,
@@ -695,8 +782,9 @@ class BKDjangoSaver(BaseCheckpointSaver[str]):
695
782
  type=type_,
696
783
  value=serialized_value,
697
784
  )
698
- writes_objects.append(write_obj)
699
- # 根据写入类型选择策略
785
+ )
786
+
787
+ def save_writes() -> None:
700
788
  if all(w[0] in WRITES_IDX_MAP for w in writes):
701
789
  # 如果所有写入都在WRITES_IDX_MAP中,使用bulk_create with update_conflicts
702
790
  bulk_upsert(
@@ -711,6 +799,13 @@ class BKDjangoSaver(BaseCheckpointSaver[str]):
711
799
  ignore_conflicts=True,
712
800
  )
713
801
 
802
+ with self.lock, _database_write_lock(self.writes_model):
803
+ _run_database_write_with_retry(
804
+ save_writes,
805
+ self.writes_model,
806
+ f"writes thread_id={thread_id} checkpoint_id={checkpoint_id} task_id={task_id}",
807
+ )
808
+
714
809
  def delete_thread(self, thread_id: str) -> None:
715
810
  """删除与线程ID关联的所有检查点和写入记录
716
811
 
@@ -18,6 +18,7 @@ to the current version of the project delivered to anyone in the future.
18
18
 
19
19
  import json
20
20
 
21
+ from aidev_agent.utils.tracing import get_current_trace_id
21
22
  from pydantic import BaseModel
22
23
  from rest_framework import status
23
24
  from rest_framework.renderers import JSONRenderer
@@ -32,6 +33,12 @@ class BKAIDevJSONRenderer(encoders.JSONEncoder):
32
33
  return super().default(obj)
33
34
 
34
35
 
36
+ def get_response_trace_id(request) -> str | None:
37
+ """Resolve the request trace ID, falling back to the active OTel span."""
38
+
39
+ return getattr(request, "otel_trace_id", None) or get_current_trace_id()
40
+
41
+
35
42
  class APIRenderer(JSONRenderer):
36
43
  """
37
44
  统一的结构封装返回内容
@@ -45,7 +52,7 @@ class APIRenderer(JSONRenderer):
45
52
  统一处理返回数据
46
53
  """
47
54
  response = renderer_context["response"]
48
- trace_id = getattr(renderer_context.get("request"), "otel_trace_id", None)
55
+ trace_id = get_response_trace_id(renderer_context.get("request"))
49
56
 
50
57
  if is_success(response.status_code):
51
58
  response.status_code = status.HTTP_200_OK