diff --git a/en/insight/data-collection-policy.mdx b/en/insight/data-collection-policy.mdx index d709d4714..649433e89 100644 --- a/en/insight/data-collection-policy.mdx +++ b/en/insight/data-collection-policy.mdx @@ -1,104 +1,87 @@ --- title: "Data Collection Policy" -description: "What data LangBot collects and how it is used" +description: "Existing telemetry, Beta diagnostics, retention and opt-out controls" --- -LangBot collects minimal, anonymized telemetry data to help improve the product. This document explains what data is collected, how it is used, and how you can opt out. +LangBot sends telemetry to the configured LangBot Space service (by default `https://space.langbot.app`) to understand usage and improve reliability. **Existing product telemetry and Beta diagnostics are separate data streams.** This page describes Core 4.11.0-beta.2 diagnostics schema v1; it does not change existing product analytics settings. -## What We Collect +## Existing product telemetry -When telemetry is enabled (via LangBot Space integration), the following data is sent **per conversation query**: +When enabled, the existing query path can send: -| Field | Description | +| Data | Contents | |---|---| -| `query_id` | A randomly generated unique ID for the query (not linked to user identity) | -| `adapter` | The messaging platform adapter in use (e.g., WeChat, QQ, Telegram) — only the adapter type name, not your account info | -| `runner` | The AI runner type (e.g., `local-agent`, `dify-service-api`) | -| `model_name` | The model name used for the query (e.g., `gpt-4o`, `deepseek-chat`) | -| `duration_ms` | How long the query took to process (in milliseconds) | -| `version` | The LangBot version you are running | -| `workspace_uuid` | A stable UUID identifying the Workspace where the query ran. For the default self-hosted Workspace it is aligned with the installation UUID and is not linked to personal identity. | -| `runtime_instance_id` | For managed SaaS query events only, the runtime deployment identifier used to refresh idle-timeout activity. It is not stored in the analytics event record. | -| `pipeline_plugins` | Names of pipeline plugins involved in the query | -| `features` | Anonymous feature-usage counters for the query (see below) | -| `error` | Error traceback if the query failed (no user content included) | -| `timestamp` | When the query occurred (UTC) | +| Identity and environment | `instance_id`, `workspace_uuid`, random `query_id`, version, adapter and runner types | +| Query statistics | Model name, duration, timestamp, pipeline plugin names | +| Feature usage | Tool counts by source, tool-call rounds, knowledge-base and retrieved-entry counts, knowledge-engine plugin IDs, sandbox execution/error counts, activated skill names and configured MCP server names | +| Errors | The legacy `error` field can contain a raw traceback, including exception text | +| Managed runtime activity | `runtime_instance_id` on managed SaaS queries refreshes idle-timeout activity; it is not stored in the analytics event record | -#### The `features` object +Feature counters do not intentionally include tool arguments/results, retrieved text or sandbox code/output. **However, legacy exception text and user-defined model, skill or MCP names may contain sensitive information. The new content-free diagnostics rules do not sanitize this legacy stream.** Do not treat existing telemetry as guaranteed content-free. -To understand which capabilities are actually used, each query event may include the following counters and category names — **never the content** of tool calls, retrieved documents, or executed code: +A Workspace heartbeat is sent shortly after startup and daily for active Workspaces. It includes deployment platform, database/vector-database kinds, sandbox configuration and availability, enabled adapter types and resource counts, rather than resource contents or connection details. -| Key | Description | -|---|---| -| `tool_calls` | Number of tool invocations during the query, grouped by tool source (`native` / `plugin` / `mcp` / `skill`) | -| `tool_call_rounds` | How many agent tool-call rounds the query took | -| `kb` | Knowledge base usage: number of knowledge bases queried, knowledge engine plugin IDs in use, and the number of retrieved entries — not the retrieved text | -| `sandbox` | Number of sandbox code executions and sandbox errors — not the executed code or its output | -| `activated_skills` | Names of skills activated during the query | -| `mcp_servers` | Names of MCP servers bound to the pipeline (omitted when "all enabled" is used) | +Optional in-app surveys send the survey ID, submitted answers, instance ID, version and completion/dismissal status. Survey answers are user-provided content, not Beta diagnostics. -### Workspace heartbeat +## Beta diagnostics v1 — 4.11.0-beta.2 -In addition to per-query events, LangBot sends one anonymous **Workspace heartbeat** for each active Workspace shortly after startup and then once per day. It describes that Workspace's configuration profile — never its data: +Beta diagnostics are **on by default in Beta builds only**. Stable, alpha and release-candidate builds do not enable this producer; this release has no stable opt-in. There is no additional setup, consent wizard or required testing step. Collection runs in the background with bounded queues, batches, timeouts and retries; unavailable diagnostics services must not hold up normal bot use. Queue limits and network failures can cause diagnostic records to be lost. -| Field | Description | -|---|---| -| `deploy_platform` | How LangBot is deployed (`docker`, `linux`, `darwin`, `win32`, ...) | -| `database` | Database kind in use (`sqlite` or `postgresql`) — no connection details | -| `vdb` | Vector database kind in use (e.g., `chroma`, `milvus`, `qdrant`) — no connection details | -| `box` | Sandbox configuration: enabled flag, availability, backend kind (`docker` / `nsjail` / `e2b`), deployment topology — no workspace contents | -| `adapters` | Adapter type names of enabled bots | -| `bot_count`, `pipeline_count`, `mcp_server_count`, `knowledge_base_count`, `plugin_count`, `skill_count` | Object counts only — no names or contents of these resources | +Diagnostics record only allowlisted, content-free metadata from instrumented operations: -### Surveys +- Core/SDK/public plugin or runner versions, build revision, deployment/environment categories and supported/configured capabilities. +- Operation and event categories, processor type, execution stage, observed outcome, counts and duration. +- Fixed reason codes, error categories and fingerprints built from code identifiers, **not exception messages or raw tracebacks**. +- Independent `instance_id` and optional `workspace_uuid`, plus opaque event/trace/span/run identifiers to correlate diagnostic steps. Instance-level events may have no Workspace. +- Sender health counters such as generated, acknowledged, retried and dropped records. -LangBot may occasionally present in-app surveys (e.g., product-market fit surveys). Participation is **optional**. When a survey is submitted, the following is sent: +**These are pseudonymous identifiers, not anonymous data.** An instance and a Workspace are distinct identity dimensions; neither is a substitute for the other. Identifiers may be associated with an account or deployment. “Unauthenticated reporter” does not mean unidentifiable. -- Survey ID and your answers -- Your instance ID and LangBot version -- Whether you completed or dismissed the survey +### Excluded from Beta diagnostic records -## What We Do NOT Collect +No messages, prompts, model replies, raw platform events, tool/API arguments or results, form values, file/media contents, filenames or local paths, raw URLs/query strings, credentials, platform user/group IDs, user-defined resource names, or raw exceptions/tracebacks. Public component IDs and fixed operation categories are used instead of arbitrary text. Network infrastructure necessarily sees a sender's IP address for delivery and abuse prevention; this is not a promise that all service access logs are IP-free. -- ❌ **Message content** — We never collect the content of your conversations -- ❌ **User identities** — No usernames, emails, phone numbers, or account IDs from your messaging platforms -- ❌ **API keys or credentials** — Your model provider API keys are never transmitted -- ❌ **IP addresses** — We do not log or store your IP address for analytics purposes -- ❌ **File or media content** — No images, documents, or other media you exchange with the bot +Diagnostics help find compatibility failures and regressions in observed paths. They are separate from query usage, retention/funnel statistics, account bindings and managed runtime idle-timeout activity. A platform API accepting a request does **not** prove a user received or read a message. Missing records or an untested path do not demonstrate success. -## How We Use the Data +## Storage and retention -The collected telemetry data is used to: +Data sent to the default service is stored on servers operated for LangBot Space. Beta diagnostics can be read by administrators, members explicitly authorized for telemetry access, and authorized service API clients. Ordinary Workspace membership does not itself grant this access. **Server default cleanup thresholds are 30 days for diagnostic detail and 90 days for aggregates**, with configuration bounded by those limits. Records become eligible for deletion at these thresholds; a scheduled worker removes them in bounded batches. Backlogs or service interruptions can delay removal, so these are not guarantees of deletion at an exact hour. These periods apply to the new diagnostic stream, not retroactively to existing product telemetry, surveys, service logs or account records. Existing telemetry continues under its existing product-analytics retention settings. -1. **Understand usage patterns** — Which adapters, runners, and models are most popular -2. **Improve reliability** — Identify common errors and failure modes -3. **Guide development** — Prioritize features and platform support based on real usage -4. **Monitor performance** — Track response times and identify bottlenecks +Opting out stops future diagnostic sends and clears local pending diagnostic records once the setting takes effect. It does **not** delete records already received by the server. For historical deletion, contact [hello@langbot.app](mailto:hello@langbot.app) or your Space administrator; active administrators and authorized service API clients can delete diagnostics scoped to an instance and, where applicable, a Workspace. Telemetry read permission alone does not permit deletion or error-status changes. Share identifiers privately, not in a public issue. -## Data Storage & Retention +## Opt-out controls -- Telemetry data is sent to **LangBot Space** (`space.langbot.app`) -- Data is stored on servers operated by the LangBot team -- Data is retained for product analytics purposes and may be aggregated for public statistics (e.g., total user count) +To disable only Beta diagnostics, update the existing `space` section in `data/config.yaml`, preserving your other settings, then restart LangBot: -## How to Opt Out +```yaml +space: + disable_beta_diagnostics: true +``` -You can disable telemetry at any time by setting `disable_telemetry: true` in the `space` section of your `data/config.yaml` configuration file: +This does not change query telemetry, heartbeat, survey or other product analytics settings. + +To disable Core telemetry, including Beta diagnostics, use the master switch and restart: ```yaml space: - url: "https://space.langbot.app" disable_telemetry: true ``` -When telemetry is disabled: -- No query data will be sent -- No Workspace heartbeats will be sent -- No surveys will be fetched or displayed -- All other LangBot features continue to work normally +The master switch takes precedence over the Beta setting. It also disables the existing query/heartbeat sends and survey fetching. Use YAML booleans (`true`/`false`), not quoted strings. If your deployment sets `SPACE__DISABLE_BETA_DIAGNOSTICS` or `SPACE__DISABLE_TELEMETRY`, those environment values override the file at startup; update or remove them too, then restart the process (recreate a container when changing its environment). Diagnostics also require a configured `space.url`; local-version builds such as `4.11.0b2+local` do not enable the producer. These controls do not disable the bot or alter the privacy settings of your messaging platforms, plugins, model providers or other online services. -## Changes to This Policy +## Optional Beta test checklist — 4.11.0-beta.2 / v1 -We may update this policy as LangBot evolves. Changes will be documented in our release notes and reflected in this page. +Use a test bot, test Workspace and non-sensitive sample data. Only test capabilities your installed adapter and plugins support. This checklist is optional; diagnostics do not automatically run these actions. -*Last updated: July 2026* +| Scenario ID | What to check | +|---|---| +| `B2-01` | Start/restart the installation; check platform and Runtime connections and one normal reply. | +| `B2-02` | Trigger a matching and non-matching route; where configured, test Pipeline, Agent and plugin event processors separately. | +| `B2-03` | Exercise a configured tool/plugin/MCP call and a reply; check the actual destination and content yourself. | +| `B2-04` | In a safe test environment, cancel a run or reproduce a known failure; confirm the bot remains usable. | +| `B2-05` | If supported, test streaming and an interaction callback; check partial replies, timeout and resume behavior. | +| `B2-06` | If checking diagnostics controls, disable diagnostics, restart and confirm normal bot use. A maintainer can separately verify no new diagnostic requests and that pending records are cleared. | + +Do not kick, mute, delete or otherwise modify production users/data just to create diagnostic samples. Report the scenario ID, exact Core/SDK versions, platform, approximate UTC time, expected versus actual behavior and whether it was a real platform or WebUI debug test. Remove secrets and personal data from any manually submitted logs/screenshots. After a fix, repeat the same scenario on the new build. Diagnostic coverage supplements these checks; it does not replace them. + +*Policy version: 1.5 · Last updated: September 15, 2026* diff --git a/ja/insight/data-collection-policy.mdx b/ja/insight/data-collection-policy.mdx index cc6cde82c..103ed0f40 100644 --- a/ja/insight/data-collection-policy.mdx +++ b/ja/insight/data-collection-policy.mdx @@ -1,104 +1,87 @@ --- title: "データ収集ポリシー" -description: "LangBot が収集するデータとその使用方法" +description: "既存のテレメトリ、Beta 診断、保存期間とオプトアウト" --- -LangBot は製品改善のため、最小限の匿名テレメトリデータを収集します。このドキュメントでは、収集されるデータ、その用途、およびオプトアウト方法について説明します。 +LangBot は利用状況の把握と信頼性の改善のため、設定された LangBot Space サービス(既定は `https://space.langbot.app`)にテレメトリを送信します。**既存の製品テレメトリと Beta 診断は別のデータストリームです。** 本ページは Core 4.11.0-beta.2 の診断スキーマ v1 を説明するもので、既存の製品分析設定を変更するものではありません。 -## 収集するデータ +## 既存の製品テレメトリ -テレメトリが有効な場合(LangBot Space 連携経由)、**各会話クエリごとに**以下のデータが送信されます: +有効な場合、既存のクエリ処理経路から次のデータが送信されることがあります。 -| フィールド | 説明 | +| データ | 内容 | |---|---| -| `query_id` | ランダム生成されたクエリ固有 ID(ユーザー ID とは紐付けられません) | -| `adapter` | 使用中のメッセージングプラットフォームアダプター種別(例:WeChat、QQ、Telegram)— アダプターの種類名のみ、アカウント情報は含まれません | -| `runner` | AI ランナーの種類(例:`local-agent`、`dify-service-api`) | -| `model_name` | クエリに使用されたモデル名(例:`gpt-4o`、`deepseek-chat`) | -| `duration_ms` | クエリの処理時間(ミリ秒) | -| `version` | 実行中の LangBot バージョン | -| `workspace_uuid` | クエリが実行されたワークスペースを識別する安定した UUID。デフォルトのセルフホストワークスペースではインストール UUID と一致し、個人情報とは紐付けられません。 | -| `runtime_instance_id` | マネージド SaaS のクエリイベントでのみ送信され、実行環境のアイドルタイムアウト活動を更新するために使用されます。分析イベントレコードには保存されません。 | -| `pipeline_plugins` | クエリに関与したパイプラインプラグイン名 | -| `features` | クエリの匿名機能使用カウンター(下記参照) | -| `error` | クエリ失敗時のエラートレースバック(ユーザーコンテンツは含まれません) | -| `timestamp` | クエリが発生した時刻(UTC) | +| 識別子と環境 | `instance_id`、`workspace_uuid`、ランダムな `query_id`、バージョン、アダプターとランナーの種類 | +| クエリ統計 | モデル名、処理時間、タイムスタンプ、パイプラインプラグイン名 | +| 機能利用 | 呼び出し元別のツール呼び出し数、ツール呼び出しラウンド数、ナレッジベースと検索結果の件数、ナレッジエンジンプラグイン ID、サンドボックス実行/エラー数、有効化したスキル名、設定された MCP サーバー名 | +| エラー | 旧 `error` フィールドには、例外メッセージを含む生の traceback が入ることがあります | +| マネージド実行環境の活動 | マネージド SaaS クエリの `runtime_instance_id` はアイドルタイムアウトの活動更新に使用され、分析イベントレコードには保存されません | -#### `features` オブジェクト +機能カウンターは、ツールの引数/結果、検索テキスト、サンドボックスのコード/出力を意図的に含めません。**ただし、旧方式の例外テキストやユーザー定義のモデル・スキル・MCP 名には機密情報が含まれる可能性があります。新しい内容非収集の診断ルールは、この既存ストリームを無害化するものではありません。** 既存のテレメトリについて、ユーザーコンテンツを一切含まないとは保証できません。 -各機能の実際の利用状況を把握するため、各クエリイベントには以下のカウンターとカテゴリ名が含まれる場合があります — ツール呼び出しの内容、検索されたドキュメント、実行されたコードは**一切含まれません**: +アクティブなワークスペースは、起動直後とその後毎日ハートビートを送信します。デプロイ環境、データベース/ベクトルデータベースの種類、サンドボックス設定と可用性、有効なアダプターの種類、リソース数を含みますが、リソース内容や接続情報は含めません。 -| キー | 説明 | -|---|---| -| `tool_calls` | クエリ中のツール呼び出し回数(ツール種別ごと:`native` / `plugin` / `mcp` / `skill`) | -| `tool_call_rounds` | クエリで実行されたエージェントのツール呼び出しラウンド数 | -| `kb` | ナレッジベースの利用状況:クエリしたナレッジベース数、使用中のナレッジエンジンプラグイン ID、検索されたエントリ数 — 検索されたテキストは含まれません | -| `sandbox` | サンドボックスでのコード実行回数とエラー回数 — 実行されたコードやその出力は含まれません | -| `activated_skills` | クエリ中にアクティベートされたスキル名 | -| `mcp_servers` | パイプラインにバインドされた MCP サーバー名(「すべて有効」の場合は送信されません) | +任意参加のアプリ内アンケートでは、アンケート ID、送信した回答、インスタンス ID、バージョン、完了/閉じた状態を送信します。回答はユーザーが提供するコンテンツであり、Beta 診断ではありません。 -### ワークスペースハートビート +## Beta 診断 v1 — 4.11.0-beta.2 -クエリごとのイベントに加え、LangBot は起動直後とその後 1 日 1 回、アクティブなワークスペースごとに匿名の**ワークスペースハートビート**を送信します。これはそのワークスペースの構成プロファイルを示すもので、ワークスペースのデータは一切含まれません: +Beta 診断は**Beta 版のみで既定で有効**です。安定版、alpha 版、rc 版ではこの送信機能は有効にならず、今回のリリースでは安定版のオプトインも提供しません。追加の設定、同意ウィザード、必須のテスト手順はありません。収集はバックグラウンドで行い、キュー、バッチ、タイムアウト、再試行には上限があります。診断サービスが利用できなくても、通常の Bot 利用を妨げない設計です。キュー上限や通信障害により診断記録が失われることがあります。 -| フィールド | 説明 | -|---|---| -| `deploy_platform` | LangBot のデプロイ方法(`docker`、`linux`、`darwin`、`win32` など) | -| `database` | 使用中のデータベース種別(`sqlite` または `postgresql`)— 接続情報は含まれません | -| `vdb` | 使用中のベクトルデータベース種別(例:`chroma`、`milvus`、`qdrant`)— 接続情報は含まれません | -| `box` | サンドボックス構成:有効フラグ、可用性、バックエンド種別(`docker` / `nsjail` / `e2b`)、デプロイトポロジー — ワークスペースの内容は含まれません | -| `adapters` | 有効なボットのアダプター種別名 | -| `bot_count`、`pipeline_count`、`mcp_server_count`、`knowledge_base_count`、`plugin_count`、`skill_count` | オブジェクト数のみ — これらのリソースの名前や内容は含まれません | +診断対象の操作から、許可リストにある、業務コンテンツを含まないメタデータのみを記録します。 -### アンケート +- Core/SDK/公開プラグインまたはランナーのバージョン、ビルド revision、デプロイ/環境の分類、対応・設定済み機能。 +- 操作とイベントの分類、プロセッサーの種類、実行段階、観測された結果、回数と所要時間。 +- 固定の理由コード、エラー分類、コード識別子から生成するフィンガープリント。**例外メッセージや生の traceback は使用しません。** +- 独立した `instance_id` と任意の `workspace_uuid`、および手順を関連付ける不透明な event/trace/span/run 識別子。インスタンス単位のイベントにはワークスペースがない場合があります。 +- 生成、受信確認、再試行、破棄などの送信側の状態カウンター。 -LangBot はアプリ内でアンケート(例:プロダクトマーケットフィット調査)を表示する場合があります。参加は**任意**です。アンケート送信時には以下が送信されます: +**これらは仮名化された識別子であり、匿名データではありません。** インスタンスとワークスペースは異なる識別軸で、互いの代わりにはなりません。識別子がアカウントやデプロイ環境と結び付く場合があります。「未認証の報告元」は「識別できない」という意味ではありません。 -- アンケート ID と回答内容 -- インスタンス ID と LangBot バージョン -- アンケートを完了したか、閉じたか +### Beta 診断記録に含めないもの -## 収集しないデータ +メッセージ、プロンプト、モデルの回答、生のプラットフォームイベント、ツール/API の引数や結果、フォーム値、ファイル/メディア内容、ファイル名やローカルパス、生の URL/クエリ文字列、認証情報、プラットフォームのユーザー/グループ ID、ユーザー定義のリソース名、生の例外や traceback は含めません。任意のテキストではなく、公開コンポーネント ID と固定の操作分類を使います。通信基盤は配信と不正利用防止のため送信元 IP を扱います。すべてのサービスアクセスログに IP が含まれないという保証ではありません。 -- ❌ **メッセージ内容** — 会話の内容は一切収集しません -- ❌ **ユーザー ID** — ユーザー名、メールアドレス、電話番号、メッセージングプラットフォームのアカウント ID は収集しません -- ❌ **API キーや認証情報** — モデルプロバイダーの API キーが送信されることはありません -- ❌ **IP アドレス** — 分析目的で IP アドレスを記録・保存することはありません -- ❌ **ファイルやメディア** — ボットとやり取りする画像、ドキュメント、その他メディアは収集しません +診断は、観測された経路での互換性問題や回帰の発見に用います。クエリ利用量、リテンション/ファネル統計、アカウントの紐付け、マネージド環境のアイドルタイムアウト活動とは分離しています。プラットフォーム API がリクエストを受け付けても、ユーザーがメッセージを受信・閲覧したことの証明にはなりません。記録がない経路や未テストの経路を成功とはみなしません。 -## データの使用目的 +## 保存と保持期間 -収集されたテレメトリデータは以下の目的で使用されます: +既定のサービスに送信されたデータは、LangBot Space のために運用されるサーバーに保存されます。管理者、テレメトリへのアクセスを明示的に許可されたメンバー、および認可されたサービス API クライアントは Beta 診断を閲覧できます。通常のワークスペースのメンバーであるだけでは、この権限は得られません。**サーバーの既定削除しきい値は診断の詳細が 30 日、集計データが 90 日**で、設定はこれらの期間を上限とします。しきい値に達した記録は削除対象となり、定期実行のワーカーが処理量を制限したバッチで削除します。処理の滞留やサービス停止により削除が遅れる場合があり、特定の時刻での削除を保証するものではありません。この期間は新しい診断ストリームにのみ適用され、既存の製品テレメトリ、アンケート、サービスログ、アカウント記録の保持規則を遡って変更しません。既存テレメトリは従来の製品分析の保持設定に従います。 -1. **利用パターンの把握** — どのアダプター、ランナー、モデルが最も使われているか -2. **信頼性の向上** — 一般的なエラーや障害パターンの特定 -3. **開発の指針** — 実際の利用状況に基づく機能・プラットフォームサポートの優先順位付け -4. **パフォーマンス監視** — レスポンス時間の追跡とボトルネックの特定 +オプトアウト設定が反映されると、以降の診断送信を停止し、ローカルの未送信診断記録を消去します。サーバーがすでに受信した記録は**削除されません**。過去のデータの削除は [hello@langbot.app](mailto:hello@langbot.app) または利用中の Space 管理者に依頼してください。有効なアカウントを持つ管理者と認可されたサービス API クライアントは、インスタンスと該当するワークスペースを指定して診断を削除できます。テレメトリの閲覧権限だけでは、削除やエラー状態の変更はできません。識別子は公開 Issue に載せず、非公開で共有してください。 -## データの保存と保持 +## オプトアウト -- テレメトリデータは **LangBot Space**(`space.langbot.app`)に送信されます -- データは LangBot チームが運用するサーバーに保存されます -- データは製品分析のために保持され、公開統計(例:総ユーザー数)として集計される場合があります +Beta 診断のみを無効にするには、`data/config.yaml` の既存の `space` セクションで次を設定し、他の設定を保持したうえで LangBot を再起動します。 -## オプトアウト方法 +```yaml +space: + disable_beta_diagnostics: true +``` -`data/config.yaml` 設定ファイルの `space` セクションで `disable_telemetry: true` を設定することで、いつでもテレメトリを無効にできます: +クエリテレメトリ、ハートビート、アンケート、その他の製品分析設定は変更しません。 + +Beta 診断を含む Core テレメトリを無効にするには、マスタースイッチを設定して再起動します。 ```yaml space: - url: "https://space.langbot.app" disable_telemetry: true ``` -テレメトリを無効にすると: -- クエリデータは送信されません -- ワークスペースハートビートは送信されません -- アンケートの取得・表示は行われません -- その他すべての LangBot 機能は通常通り動作します +マスタースイッチは Beta 設定より優先され、既存のクエリ/ハートビート送信とアンケート取得も無効にします。引用符付き文字列ではなく、YAML の真偽値(`true`/`false`)を使ってください。デプロイ環境で `SPACE__DISABLE_BETA_DIAGNOSTICS` または `SPACE__DISABLE_TELEMETRY` が設定されている場合、起動時に環境変数がファイルの設定を上書きします。これらも変更または削除してプロセスを再起動してください(コンテナの環境変数を変更する場合は再作成が必要です)。診断には `space.url` の設定も必要です。`4.11.0b2+local` のようなローカルバージョン識別子を持つビルドでは送信機能は有効になりません。Bot 自体は無効にならず、メッセージングプラットフォーム、プラグイン、モデル提供者、その他のオンラインサービスのプライバシー設定も変更しません。 -## ポリシーの変更 +## 任意の Beta テストチェックリスト — 4.11.0-beta.2 / v1 -LangBot の発展に伴い、このポリシーを更新する場合があります。変更はリリースノートに記載され、このページに反映されます。 +テスト用 Bot、テスト用ワークスペース、機密性のないサンプルデータを使い、インストール済みのアダプターとプラグインが対応する機能だけを試してください。このチェックリストは任意です。診断がこれらの操作を自動実行することはありません。 -*最終更新:2026年7月* +| シナリオ ID | 確認内容 | +|---|---| +| `B2-01` | 起動/再起動し、プラットフォームと Runtime の接続、通常の返信を確認する。 | +| `B2-02` | ルートが一致する場合と一致しない場合を試す。設定している場合は Pipeline、Agent、プラグインのイベントプロセッサーを個別に確認する。 | +| `B2-03` | 設定済みのツール/プラグイン/MCP 呼び出しと返信を試し、実際の宛先と内容を自分で確認する。 | +| `B2-04` | 安全なテスト環境で実行をキャンセルするか既知の不具合を再現し、その後も Bot を利用できることを確認する。 | +| `B2-05` | 対応している場合はストリーミングと対話コールバックを試し、部分的な返信、タイムアウト、再開動作を確認する。 | +| `B2-06` | 診断設定を確認する場合は無効化して再起動し、Bot の通常利用を確認する。保守担当者は別途、新規診断リクエストがないことと未送信記録の消去を確認できる。 | + +診断サンプルを作るためだけに、本番のユーザー/データを退出、ミュート、削除、変更しないでください。報告にはシナリオ ID、正確な Core/SDK バージョン、プラットフォーム、おおよその UTC 時刻、期待した動作と実際の動作、実プラットフォームか WebUI デバッグかを記載してください。手動で送るログやスクリーンショットからは秘密情報と個人情報を除いてください。修正後は新しいビルドで同じシナリオを再確認します。診断のカバレッジはこれらの確認を補助するもので、代替するものではありません。 + +*ポリシーバージョン:1.5 · 最終更新:2026 年 9 月 15 日* diff --git a/tests/test_beta_diagnostics_policy.py b/tests/test_beta_diagnostics_policy.py new file mode 100644 index 000000000..7e7927ba8 --- /dev/null +++ b/tests/test_beta_diagnostics_policy.py @@ -0,0 +1,117 @@ +"""Keep the localized Beta policy controls and checklist aligned.""" +import pathlib +import re +import unittest + +ROOT = pathlib.Path(__file__).resolve().parents[1] + + +class BetaDiagnosticsPolicyTest(unittest.TestCase): + def test_locales_share_protocol_controls_and_scenarios(self): + policies = { + locale: (ROOT / locale / 'insight/data-collection-policy.mdx').read_text() + for locale in ('en', 'zh', 'ja') + } + expected_scenarios = [f'B2-{number:02}' for number in range(1, 7)] + expected_config = [ + 'space:\n disable_beta_diagnostics: true', + 'space:\n disable_telemetry: true', + ] + for locale, policy in policies.items(): + with self.subTest(locale=locale): + self.assertEqual(re.findall(r'`(B2-\d{2})`', policy), expected_scenarios) + self.assertEqual(re.findall(r'```yaml\n(.*?)\n```', policy, re.S), expected_config) + for literal in ( + '4.11.0-beta.2', '1.5', 'instance_id', 'workspace_uuid', + 'alpha', '30', '90', 'hello@langbot.app', 'traceback', + 'data/config.yaml', 'SPACE__DISABLE_BETA_DIAGNOSTICS', + 'SPACE__DISABLE_TELEMETRY', 'space.url', '4.11.0b2+local', + ): + self.assertIn(literal, policy) + self.assertEqual(len(re.findall(r'^## ', policy, re.M)), 5) + + def test_english_policy_distinguishes_legacy_content_and_diagnostics(self): + policy = (ROOT / 'en/insight/data-collection-policy.mdx').read_text() + for required in ( + 'pseudonymous identifiers, not anonymous data', + 'legacy `error` field can contain a raw traceback', + 'rules do not sanitize this legacy stream', + 'this release has no stable opt-in', + 'does **not** delete records already received', + 'does not change query telemetry, heartbeat, survey', + 'diagnostics do not automatically run these actions', + 'members explicitly authorized for telemetry access', + 'Ordinary Workspace membership does not itself grant this access', + 'Telemetry read permission alone does not permit deletion', + 'Records become eligible for deletion', + 'not guarantees of deletion at an exact hour', + 'those environment values override the file at startup', + ): + self.assertIn(required, policy) + + def test_localized_access_and_cleanup_contract(self): + required = { + 'en': ('members explicitly authorized for telemetry access', + 'Telemetry read permission alone does not permit deletion', + 'Records become eligible for deletion', + 'not guarantees of deletion at an exact hour'), + 'zh': ('获得明确遥测访问授权的成员', '仅有遥测读取权限不能删除数据', + '记录达到阈值后具备删除条件', '并非保证在某个精确时刻完成删除'), + 'ja': ('テレメトリへのアクセスを明示的に許可されたメンバー', + 'テレメトリの閲覧権限だけでは、削除やエラー状態の変更はできません', + 'しきい値に達した記録は削除対象', + '特定の時刻での削除を保証するものではありません'), + } + for locale, clauses in required.items(): + policy = (ROOT / locale / 'insight/data-collection-policy.mdx').read_text() + with self.subTest(locale=locale): + for clause in clauses: + self.assertIn(clause, policy) + + def test_built_policy_html_when_requested(self): + import os + from html.parser import HTMLParser + if os.environ.get('BETA_DIAGNOSTICS_STATIC') != '1': + self.skipTest('Run with BETA_DIAGNOSTICS_STATIC=1 after npm run build') + + class VisibleText(HTMLParser): + def __init__(self): + super().__init__() + self.parts = [] + self.tables = 0 + self.hidden = 0 + + def handle_starttag(self, tag, attrs): + if tag in ('script', 'style'): + self.hidden += 1 + if tag == 'table': + self.tables += 1 + + def handle_endtag(self, tag): + if tag in ('script', 'style'): + self.hidden -= 1 + + def handle_data(self, data): + if not self.hidden: + self.parts.append(data) + + for locale in ('en', 'zh', 'ja'): + with self.subTest(locale=locale): + html = (ROOT / 'dist/public' / locale / + 'insight/data-collection-policy/index.html').read_text() + parser = VisibleText() + parser.feed(html) + text = ''.join(parser.parts) + self.assertEqual(parser.tables, 2) + for literal in ('4.11.0-beta.2', 'disable_beta_diagnostics', + 'disable_telemetry', 'SPACE__DISABLE_BETA_DIAGNOSTICS', + 'SPACE__DISABLE_TELEMETRY', '4.11.0b2+local', + 'instance_id', 'workspace_uuid', 'traceback'): + self.assertIn(literal, text) + for number in range(1, 7): + self.assertIn(f'B2-{number:02}', text) + self.assertIn('href="mailto:hello@langbot.app"', html) + + +if __name__ == '__main__': + unittest.main() diff --git a/zh/insight/data-collection-policy.mdx b/zh/insight/data-collection-policy.mdx index aa5a18416..33fc1c5f2 100644 --- a/zh/insight/data-collection-policy.mdx +++ b/zh/insight/data-collection-policy.mdx @@ -1,104 +1,87 @@ --- title: "数据收集政策" -description: "LangBot 收集哪些数据及其用途" +description: "现有遥测、Beta 诊断、保留期限与退出方式" --- -LangBot 收集最少量的匿名遥测数据,以帮助改进产品。本文档说明了收集的数据内容、用途以及如何选择退出。 +LangBot 向配置的 LangBot Space 服务(默认为 `https://space.langbot.app`)发送遥测,用于了解使用情况、改进可靠性。**现有产品遥测与 Beta 诊断是两条独立的数据流。** 本页说明 Core 4.11.0-beta.2 的诊断协议 v1,不改变现有产品分析设置。 -## 我们收集什么 +## 现有产品遥测 -当遥测功能启用时(通过 LangBot Space 集成),以下数据会在**每次对话查询时**发送: +启用后,现有查询链路可能发送: -| 字段 | 说明 | +| 数据 | 内容 | |---|---| -| `query_id` | 随机生成的查询唯一 ID(不与用户身份关联) | -| `adapter` | 使用的消息平台适配器类型(如 微信、QQ、Telegram)— 仅适配器类型名称,不包含您的账号信息 | -| `runner` | AI 运行器类型(如 `local-agent`、`dify-service-api`) | -| `model_name` | 查询使用的模型名称(如 `gpt-4o`、`deepseek-chat`) | -| `duration_ms` | 查询处理耗时(毫秒) | -| `version` | 您正在运行的 LangBot 版本 | -| `workspace_uuid` | 标识查询执行工作区的稳定 UUID。默认自托管工作区与安装 UUID 对齐,不与个人身份关联。 | -| `runtime_instance_id` | 仅托管 SaaS 查询事件发送,用于刷新运行实例的空闲超时活动;不会写入分析事件记录。 | -| `pipeline_plugins` | 参与查询的管道插件名称 | -| `features` | 本次查询的匿名功能使用计数(见下文) | -| `error` | 查询失败时的错误追踪信息(不包含用户内容) | -| `timestamp` | 查询发生的时间(UTC) | +| 标识与环境 | `instance_id`、`workspace_uuid`、随机 `query_id`、版本、适配器及运行器类型 | +| 查询统计 | 模型名称、耗时、时间戳、管道插件名称 | +| 功能使用 | 按来源分类的工具调用次数、工具调用轮数、知识库与检索条目数、知识引擎插件 ID、沙箱执行/错误次数、已激活技能名称、已配置 MCP 服务器名称 | +| 错误 | 旧 `error` 字段可能包含原始 traceback,包括异常文本 | +| 托管运行实例活动 | 托管 SaaS 查询中的 `runtime_instance_id` 用于刷新空闲超时活动,不写入分析事件记录 | -#### `features` 对象 +功能计数不会主动包含工具参数/结果、检索文本或沙箱代码/输出。**但旧异常文本以及用户自定义的模型、技能、MCP 名称可能含有敏感信息。新的无内容诊断规则不会为这条旧数据流脱敏。** 不应将现有遥测视为保证不含用户内容。 -为了解各项能力的实际使用情况,每个查询事件可能包含以下计数和类别名称 — **绝不包含**工具调用内容、检索到的文档内容或执行的代码: +活跃工作区会在启动后不久、此后每天发送工作区心跳,包含部署平台、数据库/向量数据库类型、沙箱配置与可用性、已启用适配器类型和资源数量,而非资源内容或连接信息。 -| 键 | 说明 | -|---|---| -| `tool_calls` | 本次查询中的工具调用次数,按工具来源分组(`native` / `plugin` / `mcp` / `skill`) | -| `tool_call_rounds` | 本次查询经历的 Agent 工具调用轮数 | -| `kb` | 知识库使用情况:查询的知识库数量、使用的知识引擎插件 ID、检索到的条目数量 — 不包含检索到的文本 | -| `sandbox` | 沙箱代码执行次数和沙箱错误次数 — 不包含执行的代码或其输出 | -| `activated_skills` | 本次查询中激活的技能名称 | -| `mcp_servers` | 绑定到管道的 MCP 服务器名称(使用"全部启用"时不发送) | +自愿参与的应用内问卷会发送问卷 ID、提交的回答、实例 ID、版本及完成/关闭状态。问卷回答是用户主动提供的内容,不属于 Beta 诊断。 -### 工作区心跳 +## Beta 诊断 v1 — 4.11.0-beta.2 -除每次查询事件外,LangBot 会在启动后不久为每个活跃工作区发送一条匿名**工作区心跳**,之后每天发送一次。心跳描述该工作区的配置概况 — 绝不包含工作区数据: +Beta 诊断**仅在 Beta 版本默认开启**;稳定版、alpha 和 rc 版本不启用该发送器,本次发布不提供稳定版主动开启选项。不增加配置向导、同意弹窗或必做测试步骤。采集在后台运行,队列、批次、超时和重试均有上限;诊断服务不可用不应阻塞正常使用。队列限制或网络故障可能导致诊断记录丢失。 -| 字段 | 说明 | -|---|---| -| `deploy_platform` | LangBot 的部署方式(`docker`、`linux`、`darwin`、`win32` 等) | -| `database` | 使用的数据库类型(`sqlite` 或 `postgresql`)— 不包含连接信息 | -| `vdb` | 使用的向量数据库类型(如 `chroma`、`milvus`、`qdrant`)— 不包含连接信息 | -| `box` | 沙箱配置:启用状态、可用性、后端类型(`docker` / `nsjail` / `e2b`)、部署拓扑 — 不包含工作区内容 | -| `adapters` | 已启用机器人的适配器类型名称 | -| `bot_count`、`pipeline_count`、`mcp_server_count`、`knowledge_base_count`、`plugin_count`、`skill_count` | 仅对象数量 — 不包含这些资源的名称或内容 | +诊断仅记录已埋点操作中白名单允许的、不含业务内容的元数据: -### 问卷调查 +- Core/SDK/公开插件或运行器版本、构建 revision、部署/环境类别,以及支持或已配置的能力。 +- 操作和事件类别、处理器类型、执行阶段、观测结果、次数和耗时。 +- 固定原因码、错误类别及由代码标识生成的指纹,**不使用异常消息或原始 traceback**。 +- 相互独立的 `instance_id` 与可选 `workspace_uuid`,以及用于关联步骤的不透明事件/trace/span/run 标识。实例级事件可能没有工作区。 +- 生成、确认接收、重试、丢弃等发送器健康计数。 -LangBot 可能会偶尔在应用内展示问卷调查(如产品市场匹配调查)。参与完全**自愿**。提交问卷时,将发送以下内容: +**这些是假名化标识,而非匿名数据。** 实例和工作区是不同的身份维度,不能互相替代;标识可能关联到账户或部署。“未经认证的报告者”不代表无法识别。 -- 问卷 ID 和您的回答 -- 您的实例 ID 和 LangBot 版本 -- 您是否完成或关闭了问卷 +### Beta 诊断记录不包含什么 -## 我们不收集什么 +不包含消息、提示词、模型回复、原始平台事件、工具/API 参数或结果、表单值、文件/媒体内容、文件名或本地路径、原始 URL/查询字符串、凭据、平台用户/群组 ID、用户自定义资源名、原始异常或 traceback。使用公开组件 ID 和固定操作类别,而非任意文本。网络基础设施为传输和防滥用必然会接触发送者 IP;这不表示所有服务访问日志都不含 IP。 -- ❌ **消息内容** — 我们绝不收集您的对话内容 -- ❌ **用户身份** — 不收集用户名、邮箱、手机号或消息平台的账号 ID -- ❌ **API 密钥或凭据** — 您的模型提供商 API 密钥绝不会被传输 -- ❌ **IP 地址** — 我们不会出于分析目的记录或存储您的 IP 地址 -- ❌ **文件或媒体内容** — 不收集您与机器人交换的图片、文档或其他媒体 +诊断用于发现已观测路径中的兼容性问题和回归,与查询使用量、留存/漏斗统计、账户绑定及托管实例空闲超时活动分离。平台 API 接受请求**不等于**用户已收到或读到消息。没有记录或尚未测试的路径不能视为成功。 -## 我们如何使用数据 +## 存储与保留 -收集的遥测数据用于: +发送到默认服务的数据存储于为 LangBot Space 运维的服务器,管理员、获得明确遥测访问授权的成员及获授权的服务 API 客户端可以读取 Beta 诊断;普通工作区成员身份本身不授予此权限。**服务器默认清理阈值为诊断明细 30 天、聚合数据 90 天**,配置以这些期限为上限。记录达到阈值后具备删除条件,由定期运行的工作线程分批、有界地清理;积压或服务中断可能延迟删除,并非保证在某个精确时刻完成删除。这些期限仅适用于新诊断数据流,不追溯改变现有产品遥测、问卷、服务日志或账户记录的保留规则;现有遥测继续使用既有产品分析保留设置。 -1. **了解使用模式** — 哪些适配器、运行器和模型最受欢迎 -2. **提高可靠性** — 识别常见错误和故障模式 -3. **指导开发** — 根据实际使用情况确定功能和平台支持的优先级 -4. **监控性能** — 跟踪响应时间并识别瓶颈 +退出设置生效后,停止后续诊断发送并清空本地待发送诊断记录,**不会**删除服务器已经接收的历史记录。如需删除历史数据,请联系 [hello@langbot.app](mailto:hello@langbot.app) 或所用 Space 的管理员;账户状态正常的管理员及获授权的服务 API 客户端可按实例及适用的工作区范围删除诊断。仅有遥测读取权限不能删除数据或更改错误状态。请私下提供标识,不要贴到公开 Issue 中。 -## 数据存储与保留 +## 退出方式 -- 遥测数据发送至 **LangBot Space**(`space.langbot.app`) -- 数据存储在 LangBot 团队运维的服务器上 -- 数据保留用于产品分析,可能会汇总用于公开统计(如总用户数) +仅关闭 Beta 诊断:在 `data/config.yaml` 现有的 `space` 部分更新以下设置,保留其他配置,然后重启 LangBot: -## 如何选择退出 +```yaml +space: + disable_beta_diagnostics: true +``` -您可以随时在 `data/config.yaml` 配置文件的 `space` 部分设置 `disable_telemetry: true` 来关闭遥测: +这不会改变查询遥测、心跳、问卷或其他产品分析设置。 + +关闭 Core 遥测(包括 Beta 诊断):使用总开关,然后重启: ```yaml space: - url: "https://space.langbot.app" disable_telemetry: true ``` -关闭遥测后: -- 不会发送任何查询数据 -- 不会发送工作区心跳 -- 不会获取或展示问卷调查 -- 所有其他 LangBot 功能照常运行 +总开关优先于 Beta 设置,也会关闭现有查询/心跳发送和问卷获取。请使用 YAML 布尔值(`true`/`false`),不要加引号。如果部署设置了 `SPACE__DISABLE_BETA_DIAGNOSTICS` 或 `SPACE__DISABLE_TELEMETRY`,启动时环境变量会覆盖文件设置;请同时修改或移除这些变量,然后重启进程(修改容器环境变量时需重新创建容器)。诊断还要求配置 `space.url`;带本地版本标记的构建(如 `4.11.0b2+local`)不会启用发送器。这些开关不会停用机器人,也不会修改消息平台、插件、模型提供商或其他在线服务的隐私设置。 -## 政策变更 +## 可选 Beta 测试清单 — 4.11.0-beta.2 / v1 -我们可能会随着 LangBot 的发展更新此政策。变更将记录在发布说明中并体现在此页面。 +使用测试机器人、测试工作区和非敏感示例数据,只测试已安装适配器及插件支持的能力。本清单完全可选;诊断不会自动执行这些操作。 -*最后更新:2026 年 7 月* +| 场景 ID | 检查内容 | +|---|---| +| `B2-01` | 启动/重启安装,检查平台和 Runtime 连接,并完成一次正常回复。 | +| `B2-02` | 分别触发匹配和不匹配的路由;按实际配置分别测试 Pipeline、Agent 和插件事件处理器。 | +| `B2-03` | 调用已配置的工具/插件/MCP 并回复,人工核对实际目标和内容。 | +| `B2-04` | 在安全测试环境取消运行或复现已知故障,确认机器人仍可继续使用。 | +| `B2-05` | 如支持,测试流式回复及交互回调,检查部分回复、超时和恢复行为。 | +| `B2-06` | 如需检查诊断开关,关闭诊断、重启并确认机器人正常使用;维护者可另行核实没有新诊断请求且待发送记录已清空。 | + +不要为了产生诊断样本而在生产环境踢人、禁言、删除或修改用户/数据。反馈时提供场景 ID、准确的 Core/SDK 版本、平台、大致 UTC 时间、预期与实际表现,并区分真实平台与 WebUI 调试。主动提交日志/截图前去除秘密和个人信息。修复后在新构建上重复同一场景。诊断覆盖只能补充这些检查,不能替代人工验证。 + +*政策版本:1.5 · 最后更新:2026 年 9 月 15 日*