diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml new file mode 100644 index 00000000..bf1ebb1e --- /dev/null +++ b/.github/workflows/deploy-docs.yml @@ -0,0 +1,59 @@ +name: Deploy Documentation + +on: + push: + branches: + - main + paths: + - 'docs/**' + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: pages + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version: 20 + cache: npm + + - name: Setup Pages + uses: actions/configure-pages@v4 + + - name: Install dependencies + run: npm ci + + - name: Build with VitePress + run: npm run docs:build + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: docs/.vitepress/dist + + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + needs: build + runs-on: ubuntu-latest + name: Deploy + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index ec44cfac..f19d27b8 100644 --- a/.gitignore +++ b/.gitignore @@ -45,3 +45,7 @@ logs/ *.log dist/ + +# Docs +docs/.vitepress/dist +docs/.vitepress/cache \ No newline at end of file diff --git a/assets/friday_setting.png b/assets/friday_setting.png new file mode 100644 index 00000000..9243cd16 Binary files /dev/null and b/assets/friday_setting.png differ diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts new file mode 100644 index 00000000..9b90e6b1 --- /dev/null +++ b/docs/.vitepress/config.mts @@ -0,0 +1,125 @@ +import { defineConfig } from 'vitepress'; + +// Shared configuration +const sharedThemeConfig = { + socialLinks: [ + { + icon: 'github', + link: 'https://github.com/agentscope-ai/agentscope-studio', + }, + ], +}; + +// https://vitepress.dev/reference/site-config +export default defineConfig({ + srcDir: 'tutorial', + + title: 'AgentScope-Studio', + description: 'A development-oriented visualization toolkit for AgentScope', + + rewrites: { + 'en/:rest*': ':rest*', + }, + + locales: { + root: { + label: 'English', + lang: 'en', + themeConfig: { + ...sharedThemeConfig, + nav: [ + { text: 'Home', link: '/' }, + { text: 'Tutorial', link: '/tutorial/overview' }, + ], + sidebar: [ + { + text: 'Tutorial', + items: [ + { + text: 'Overview', + link: '/tutorial/overview', + }, + { + text: 'Quick Start', + link: '/tutorial/quick_start', + }, + { + text: 'Contributing', + link: '/tutorial/contributing', + }, + ], + }, + { + text: 'Develop', + items: [ + { text: 'Project', link: '/develop/project' }, + { text: 'Tracing', link: '/develop/tracing' }, + { + text: 'Evaluation', + link: '/develop/evaluation', + }, + ], + }, + { + text: 'Agent', + items: [{ text: 'Friday', link: '/agent/friday' }], + }, + ], + }, + }, + zh_CN: { + label: '简体中文', + lang: 'zh-CN', + link: '/zh_CN/', + themeConfig: { + ...sharedThemeConfig, + nav: [ + { text: '首页', link: '/zh_CN/' }, + { text: '教程', link: '/zh_CN/tutorial/overview' }, + ], + sidebar: [ + { + text: '教程', + items: [ + { + text: '概览', + link: '/zh_CN/tutorial/overview', + }, + { + text: '快速开始', + link: '/zh_CN/tutorial/quick_start', + }, + { + text: '贡献指南', + link: '/zh_CN/tutorial/contributing', + }, + ], + }, + { + text: '开发', + items: [ + { + text: '项目管理', + link: '/zh_CN/develop/project', + }, + { + text: '运行追踪', + link: '/zh_CN/develop/tracing', + }, + { + text: '应用评测', + link: '/zh_CN/develop/evaluation', + }, + ], + }, + { + text: '智能体', + items: [ + { text: 'Friday', link: '/zh_CN/agent/friday' }, + ], + }, + ], + }, + }, + }, +}); diff --git a/docs/tutorial/en/agent/assets/friday_setting.png b/docs/tutorial/en/agent/assets/friday_setting.png new file mode 100644 index 00000000..9243cd16 Binary files /dev/null and b/docs/tutorial/en/agent/assets/friday_setting.png differ diff --git a/docs/tutorial/en/agent/friday.md b/docs/tutorial/en/agent/friday.md new file mode 100644 index 00000000..81b492dd --- /dev/null +++ b/docs/tutorial/en/agent/friday.md @@ -0,0 +1,49 @@ +# AgentScope-Friday + +Friday is an experimental local-deployed agent built by AgentScope, aims at + +- answering questions about the AgentScope, +- providing a quick secondary development environment for developers, +- integrating all available features in AgentScope to build a more powerful agent, and +- testing and integrating the advanced features in AgentScope. + +Its source code is also open-sourced in the [AgentScope-Studio repository](https://github.com/agentscope-ai/agentscope-studio/tree/main/packages/app). + +The code structure is as follows: + +``` +packages/ + app/ + friday/ + tool/ + utils/ + connect.py # The websocket connection used for realtime steering/interruption + ... + main.py # The entry point of Friday agent + args.py # The argument parser for Friday agent + hook.py # The hook functions used to push messages to AgentScope-Studio frontend + model.py # Initialize the LLM based on the configuration + requirements.txt # The dependencies for Friday agent +``` + +## How to Use + +At the first time using Friday, you need to configure the agent in the following page, including the model, API KEY, +tools, and other parameters. + +![Friday Configuration Page](assets/friday_setting.png) + +After that, you can start chatting with Friday in the chat page. + +## Equipped Features + +We are continuously integrating more features into Friday. The current and upcoming features include: + +- [x] Basic chat functionality with LLMs +- [x] Support meta tool +- [x] Support realtime steering/interruption +- [x] Support state/Session management +- [ ] 🚧 Support planning and plan visualization +- [ ] 🚧 Support long-term memory +- [ ] Support anthropic agent skill +- [ ] Support user to add MCP server dynamically diff --git a/docs/tutorial/en/develop/assets/project-management.png b/docs/tutorial/en/develop/assets/project-management.png new file mode 100644 index 00000000..7b5f4843 Binary files /dev/null and b/docs/tutorial/en/develop/assets/project-management.png differ diff --git a/docs/tutorial/en/develop/assets/react-agent-example.png b/docs/tutorial/en/develop/assets/react-agent-example.png new file mode 100644 index 00000000..f84dd2d5 Binary files /dev/null and b/docs/tutorial/en/develop/assets/react-agent-example.png differ diff --git a/docs/tutorial/en/develop/assets/run-management.png b/docs/tutorial/en/develop/assets/run-management.png new file mode 100644 index 00000000..e44b2730 Binary files /dev/null and b/docs/tutorial/en/develop/assets/run-management.png differ diff --git a/docs/tutorial/en/develop/assets/tracing_detail_attributes.png b/docs/tutorial/en/develop/assets/tracing_detail_attributes.png new file mode 100644 index 00000000..9f0f9c8f Binary files /dev/null and b/docs/tutorial/en/develop/assets/tracing_detail_attributes.png differ diff --git a/docs/tutorial/en/develop/assets/tracing_detail_chat_history.png b/docs/tutorial/en/develop/assets/tracing_detail_chat_history.png new file mode 100644 index 00000000..960bb7f1 Binary files /dev/null and b/docs/tutorial/en/develop/assets/tracing_detail_chat_history.png differ diff --git a/docs/tutorial/en/develop/assets/tracing_overview.png b/docs/tutorial/en/develop/assets/tracing_overview.png new file mode 100644 index 00000000..8e26a1dd Binary files /dev/null and b/docs/tutorial/en/develop/assets/tracing_overview.png differ diff --git a/docs/tutorial/en/develop/assets/user-input-flow.png b/docs/tutorial/en/develop/assets/user-input-flow.png new file mode 100644 index 00000000..1e1c1fec Binary files /dev/null and b/docs/tutorial/en/develop/assets/user-input-flow.png differ diff --git a/docs/tutorial/en/develop/evaluation.md b/docs/tutorial/en/develop/evaluation.md new file mode 100644 index 00000000..5c001cf0 --- /dev/null +++ b/docs/tutorial/en/develop/evaluation.md @@ -0,0 +1,3 @@ +# Evaluation + +Coming soon ... diff --git a/docs/tutorial/en/develop/project.md b/docs/tutorial/en/develop/project.md new file mode 100644 index 00000000..cd2c22c1 --- /dev/null +++ b/docs/tutorial/en/develop/project.md @@ -0,0 +1,315 @@ +# Project Management + +AgentScope-Studio provides powerful project management capabilities to help you visually manage your AgentScope +projects. Through the organizational structure of Projects and Runs, you can clearly separate and manage your +observability data. + +## Concepts + +In AgentScope-Studio, a **Project** contains multiple **Runs**. Specifically: + +- **Projects**: Used to organize and isolate different AI applications or experiments +- **Runs**: Individual execution instances within a project, similar to sessions, tracking a complete running process + +## Project Management + +The Projects page in AgentScope-Studio provides an overview and management functionality for running projects: + +![Project Management](assets/project-management.png) + +Click on any project in the project list to enter the run management interface and view all run instances under that project. + +## Run Instance Management + +### Run Visualization + +Run instances contain complete execution tracking and status monitoring functionality. +In the (left) sidebar, all run instances under the project are stacked in chronological order. Click on any run instance to view its complete interaction history and status in a Chatbot-style UI. +In addition, the right panel provides detailed information and statistics for that run. + +![Run Management](assets/run-management.png) + +In AgentScope, a single agent reply (i.e., calling the `reply` function once) generates multiple messages (`Msg` objects). These messages may be prompt messages to guide the LLM (with role "user"), or tool execution results (with role "system"). + +Therefore, at the visualization level, we introduce the concept of **reply** above the message level to organize multiple messages together into a complete agent reply unit. +In the run visualization interface, developers can choose to view messages by `replyId` or `msg.id`. + +### User Input Hosting + +When an AgentScope project connects to Studio, Studio automatically hosts user input and pushes it in real-time to the Python agent application via WebSocket. Studio also supports multiple different `UserAgent` instances within a single run instance, enabling multi-user collaborative interaction scenarios. + +### Run Trace Visualization + +AgentScope-Studio also provides OpenTelemetry-based trace data visualization in the right panel, helping developers understand detailed inputs and outputs of agent objects, LLM calls, tool usage, and other components during each run. + +## API Protocol + +The API protocols related to project management in AgentScope-Studio are as follows: + +> **Note**: For detailed information about Trace data format, push mechanism, and integration examples, please refer to the [Trace documentation](tracing.md). + +| Function | Endpoint | Method | Purpose | +| ------------------ | ------------------------ | ------ | ---------------------------------------- | +| Register Run | `/trpc/registerRun` | POST | Register a new Agent run instance | +| Push Message | `/trpc/pushMessage` | POST | Send Agent messages to the Web interface | +| Request User Input | `/trpc/requestUserInput` | POST | Agent actively requests user input | + +### 1. Register Run Protocol + +Register a run instance on Studio. + +| Field | Type | Required | Description | +| ----------- | ------ | -------- | ------------------------------------------------- | +| `id` | string | ✓ | Run instance ID | +| `project` | string | ✓ | Project name | +| `name` | string | ✓ | Run instance name | +| `timestamp` | string | ✓ | ISO timestamp | +| `pid` | number | ✓ | Process ID | +| `status` | enum | ✓ | Run status (e.g., "running", "finished", "error") | + +### 2. Message Push Protocol + +Send `Msg` objects to Studio for display. + +| Field | Type | Required | Description | +| --------------- | ------------- | -------- | --------------------------------------------------------- | +| `runId` | string | ✓ | Run instance ID | +| `replyId` | string | ✓ | Reply message ID | +| `replyName` | string | ✓ | Name of the replier | +| `replyRole` | string | ✓ | Role of the replier (e.g., "assistant", "user") | +| `msg.id` | string | ✓ | Message ID | +| `msg.name` | string | ✓ | Message sender name | +| `msg.role` | string | ✓ | Message sender role (e.g., "assistant", "user", "system") | +| `msg.content` | ContentBlocks | ✓ | Message content | +| `msg.metadata` | object | ✓ | Message metadata | +| `msg.timestamp` | string | ✓ | Message ISO timestamp | + +**ContentBlocks Format:** + +`ContentBlocks` is an array of content blocks. Each block has a `type` field that determines its structure. Supported content block types include: + +- **Text Block** (`type: "text"`): Contains a `text` field storing message content +- **Thinking Block** (`type: "thinking"`): Contains a `thinking` field storing reasoning content +- **Image Block** (`type: "image"`): Contains a `source` field, can be base64 data or URL +- **Audio Block** (`type: "audio"`): Contains a `source` field, can be base64 data or URL +- **Video Block** (`type: "video"`): Contains a `source` field, can be base64 data or URL +- **Tool Use Block** (`type: "tool_use"`): Contains `id`, `name`, and `input` fields +- **Tool Result Block** (`type: "tool_result"`): Contains `id`, `name`, and `output` fields + +For media blocks (image, audio, video), `source` can be: + +- **Base64 Source**: `{ type: "base64", media_type: string, data: string }` +- **URL Source**: `{ type: "url", url: string }` + +**Example:** + +```python +content_blocks = [ + { + "type": "text", + "text": "Greetings from your agent!" + }, + { + "type": "image", + "source": { + "type": "base64", + "media_type": "image/jpeg", + "data": "data:image/jpeg;base64,/9j/4AAQSkZJRg..." + } + }, + { + "type": "tool_use", + "id": "tool-123", + "name": "search", + "input": {"query": "weather"} + } +] +``` + +### 3. User Input Protocol + +Request user input on the Studio frontend page with a specific role/name/identity. + +**Request Fields:** + +| Field | Type | Required | Description | +| ----------------- | ------ | -------- | ------------------------------------- | +| `requestId` | string | ✓ | User input request ID | +| `runId` | string | ✓ | Run instance ID | +| `agentId` | string | ✓ | Agent ID | +| `agentName` | string | ✓ | Agent name | +| `structuredInput` | object | | JSON Schema for structured input form | + +The specific implementation logic for user input involves multi-party interaction between the Python application, Studio server, and frontend. Below is the detailed interaction flow: + +![User Input Flow](assets/user-input-flow.png) + +1. **Agent Sends Request**: The Agent sends a user input request to the Studio server via POST request +2. **Server Saves Request**: The Studio server saves the request to the database and pushes it to the Web client via WebSocket +3. **User Input**: The user enters content in the Web interface +4. **Client Sends**: The Web client sends the user input back to the server via WebSocket +5. **Server Forwards**: The server validates and forwards the user input to the Agent's WebSocket connection +6. **Agent Receives**: The Agent receives the user input via WebSocket and continues execution + +## Integration Example + +The following example demonstrates how to integrate project management-related protocols: + +```python +from agentscope.message import Msg +from datetime import datetime +from queue import Queue +from threading import Event +from typing import Any, List + +import requests +import shortuuid +import socketio + + +class StudioClient: + """Complete Studio client for custom Agent integration""" + + def __init__(self, studio_url: str): + self.studio_url = studio_url + self.sio = socketio.Client() + self.input_queues = {} + self.input_events = {} + + def register_run( + self, + id: str, + project: str, + name: str, + timestamp: str, + pid: int, + status: str, + ) -> None: + """Register a run instance""" + response = requests.post( + f"{self.studio_url}/trpc/registerRun", + json={ + "id": id, + "project": project, + "name": name, + "timestamp": timestamp, + "pid": pid, + "status": status, + }, + timeout=10 + ) + response.raise_for_status() + + # Connect WebSocket to receive user input + self.sio.connect( + self.studio_url, + namespaces=["/python"], + auth={"run_id": id} + ) + + # Listen for user input + @self.sio.on("forwardUserInput", namespace="/python") + def receive_user_input( + request_id: str, + blocks_input: List[dict], + structured_input: dict[str, Any], + ) -> None: + if request_id in self.input_queues: + self.input_queues[request_id].put({ + "blocks_input": blocks_input, + "structured_input": structured_input, + }) + self.input_events[request_id].set() + + def push_message( + self, + run_id: str, + reply_id: str, + reply_name: str, + reply_role: str, + msg: Msg + ) -> None: + """Push message to Studio""" + payload = { + "runId": run_id, + "replyId": reply_id, + "replyName": reply_name, + "replyRole": reply_role, + "msg": msg.to_dict() + } + + response = requests.post( + f"{self.studio_url}/trpc/pushMessage", + json=payload, + timeout=10 + ) + response.raise_for_status() + + def request_user_input(self, run_id: str, agent_id: str, agent_name: str, + structured_input=None): + """Request user input from Studio""" + + request_id = shortuuid.uuid() + self.input_queues[request_id] = Queue() + self.input_events[request_id] = Event() + + try: + response = requests.post( + f"{self.studio_url}/trpc/requestUserInput", + json={ + "requestId": request_id, + "runId": run_id, + "agentId": agent_id, + "agentName": agent_name, + "structuredInput": structured_input + }, + timeout=10 + ) + response.raise_for_status() + + # Wait for user response + self.input_events[request_id].wait(timeout=300) + if request_id in self.input_queues: + return self.input_queues[request_id].get() + else: + raise TimeoutError("User input timeout") + finally: + # Cleanup + if request_id in self.input_queues: + del self.input_queues[request_id] + if request_id in self.input_events: + del self.input_events[request_id] + + +# Usage example +client = StudioClient("http://localhost:3000") + +# Register run +client.register_run( + id="run-12345", + project="my-project", + name="custom-agent", + timestamp=datetime.now().strftime("%Y-%m-%d %H:%M:%S"), + pid=12345, + status="running" +) + +# Create a prompt message +msg = Msg("my-agent", "You should now...", "user") +# Push message +client.push_message( + run_id="run-12345", + reply_id="reply-1", + reply_name="my-agent", + reply_role="assistant", + msg=msg +) + +# Request user input +user_response = client.request_user_input( + run_id="run-12345", + agent_id="agent-1", + agent_name="My Agent" +) +print(f"User responded: {user_response}") +``` diff --git a/docs/tutorial/en/develop/tracing.md b/docs/tutorial/en/develop/tracing.md new file mode 100644 index 00000000..a1c3f596 --- /dev/null +++ b/docs/tutorial/en/develop/tracing.md @@ -0,0 +1,272 @@ +# Run Tracing + +In the Trace page of the Studio sidebar, you can view detailed information about run tracing, including inputs and outputs of various modules, tool call information, execution time, and other runtime information. + +This feature is built on the [OpenTelemetry semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/) and [OTLP protocol](https://opentelemetry.io/docs/specs/otlp/). It not only provides out-of-the-box reception and storage of various observability information reported by AgentScope, but also supports integration of data reported by any collection tools/AI application frameworks based on OpenTelemetry or LoongSuite. + +![Trace](assets/tracing_detail_chat_history.png) + +## Overview Page + +On this page, you can view basic information about trace data reported to Studio. + +> 💡 **Tip**: Hover your mouse over the icon next to the trace name to view basic metadata of that trace, such as Trace ID. + +![Trace](assets/tracing_overview.png) + +## Details Page + +Click on any trace in the overview page to view the call sequence and call relationships of that trace. Further select calls at different levels to see detailed context when these calls occurred. + +In the Metadata area, you can view the input and output of calls. +For AI-related calls, such as LLM, Agent, etc., inputs and outputs will be displayed according to the [structure](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/#recording-content-on-attributes) defined by the OpenTelemetry semantic conventions. For regular calls, such as Function, Format, etc., inputs and outputs will be displayed according to the AgentScope extended [semantic conventions](#agentscope-extended-conventions). + +![Trace](assets/tracing_detail_chat_history.png) + +In the All Attributes area, you can see all key metadata of this call, with naming following the [semantic conventions](#semantic-conventions). + +![Trace](assets/tracing_detail_attributes.png) + +## Semantic Conventions + +AgentScope-Studio's observability data follows semantic conventions based on [OpenTelemetry](#opentelemetry-generative-ai). Data following these semantic conventions will receive more accurate and clear processing and display in Studio. + +> 💡 **Tip**: The native observability capabilities of the AgentScope library already follow these semantic conventions. Even if observability data from other sources does not yet follow these semantic conventions, trace data can still be displayed normally, but some key information may not be highlighted/specially displayed. + +### OpenTelemetry Generative AI + +OpenTelemetry provides a set of semantic convention standards for observability data of Generative AI applications. For detailed definitions, see [Semantic conventions for generative client AI spans](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/) and [Semantic Conventions for GenAI agent and framework spans](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-agent-spans/). + +> 💡 **Tip**: Studio currently follows OpenTelemetry semantic conventions version 1.38.0. + +Current semantic conventions include: + +- [**Inference**](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/#inference): model calls +- [**Invoke agent span**](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-agent-spans/#invoke-agent-span): agent calls +- [**Execute tool span**](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/#execute-tool-span): toolkit calls + +### AgentScope Extended Conventions + +In addition to various semantic conventions defined in OpenTelemetry, AgentScope has extended semantic conventions for some specific call processes to display the call process more clearly. + +#### Common Call + +Applicable to all key call processes occurring in AI applications. + +| Key | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | +| ---------------------------- | ----------------------------------------------------------------------------------------------------- | ---------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `agentscope.function.name` | `Recommended` | string | The name of the method/function called. | `DashScopeChatModel.__call__`; `ToolKit.callTool` | +| `agentscope.function.input` | `Opt-In` | string | The input of the method/function. [1] | {
  "tool_call": {
    "type": "tool_use",
    "id": "call_83fce0d1d2684545a13649",
    "name": "multiply",
    "input": {
      "a": 5,
      "b": 3
    }
  }
} | +| `agentscope.function.output` | `Opt-In` | string | The return value of the method/function. [2] | `ToolResponse(content=[{'type': 'text', 'text': '5 × 3 = 15'}], metadata=None, stream=False, is_last=True, is_interrupted=False, id='2025-11-28 00:38:52.733_cc4ead')` | + +**[1] `agentscope.function.input`**: Method/function input parameters. **Must** be serialized in JSON format. + +**[2] `agentscope.function.output`**: The return value of the method/function. Serialized in JSON or toString format. + +#### Format Call + +This span represents the preparation and formatting process of the request before initiating a model call. In AgentScope, this method corresponds to the invocation of the Formatter tool. + +`gen_ai.operation.name` **should** be `format`. + +**Span name should** be `format {agentscope.format.target}`. + +**Span kind should** be `INTERNAL`. + +**Span status should** follow the [recording errors](https://opentelemetry.io/docs/specs/semconv/general/recording-errors/) documentation. + +**Attributes:** + +| Key | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | +| ---------------------------- | ----------------------------------------------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `gen_ai.operation.name` | `Required` | string | The name of the operation being performed. | `chat`; `generate_content`; `text_completion` | +| `error.type` | `Conditionally Required` if the operation ended in an error | string | The error thrown when the operation aborted. | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | +| `agentscope.format.target` | `Required` | string | The target type to format to. If the target type cannot be resolved, set to 'unknown'. | `dashscope`; `openai` | +| `agentscope.format.count` | `Recommended` | int | The actual number of messages formatted. [1] | `3` | +| `agentscope.function.name` | `Recommended` | string | The name of the method/function called. | `DashScopeChatModel.__call__`; `ToolKit.callTool` | +| `agentscope.function.input` | `Opt-In` | string | The input of the method/function. [2] | {
  "tool_call": {
    "type": "tool_use",
    "id": "call_83fce0d1d2684545a13649",
    "name": "multiply",
    "input": {
      "a": 5,
      "b": 3
    }
  }
} | +| `agentscope.function.output` | `Opt-In` | string | The return value of the method/function. [3] | `ToolResponse(content=[{'type': 'text', 'text': '5 × 3 = 15'}], metadata=None, stream=False, is_last=True, is_interrupted=False, id='2025-11-28 00:38:52.733_cc4ead')` | + +**[1] `agentscope.format.count`**: The actual number of messages formatted. The value is consistent with the size of the message list returned after the formatting function is executed. If truncation or message trimming is performed during formatting, this value may be less than the size of the incoming message list. + +**[2] `agentscope.function.input`**: Method/function input parameters. **Must** be serialized in JSON format. + +**[3] `agentscope.function.output`**: The return value of the method/function. Serialized in JSON or toString format. + +#### Function Call + +This span represents the process of initiating any key call. In AgentScope, this method corresponds to the execution process of regular functions, and only takes effect when users add trace tracking capability to methods/functions through the methods provided by AgentScope. + +`gen_ai.operation.name` **should** be `invoke_generic_function`. + +**Span name should** be `invoke_generic_function {agentscope.function.name}`. + +**Span kind should** be `INTERNAL`. + +**Span status should** follow the [recording errors](https://opentelemetry.io/docs/specs/semconv/general/recording-errors/) documentation. + +**Attributes:** + +| Key | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | +| ---------------------------- | ----------------------------------------------------------------------------------------------------- | ---------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `gen_ai.operation.name` | `Required` | string | The name of the operation being performed. | `chat`; `generate_content`; `text_completion` | +| `error.type` | `Conditionally Required` if the operation ended in an error | string | The error thrown when the operation aborted. | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | +| `agentscope.function.name` | `Recommended` | string | The name of the method/function called. | `DashScopeChatModel.__call__`; `ToolKit.callTool` | +| `agentscope.function.input` | `Opt-In` | string | The input of the method/function. [1] | {
  "tool_call": {
    "type": "tool_use",
    "id": "call_83fce0d1d2684545a13649",
    "name": "multiply",
    "input": {
      "a": 5,
      "b": 3
    }
  }
} | +| `agentscope.function.output` | `Opt-In` | string | The return value of the method/function. [2] | `ToolResponse(content=[{'type': 'text', 'text': '5 × 3 = 15'}], metadata=None, stream=False, is_last=True, is_interrupted=False, id='2025-11-28 00:38:52.733_cc4ead')` | + +**[1] `agentscope.function.input`**: Method/function input parameters. **Must** be serialized in JSON format. + +**[2] `agentscope.function.output`**: The return value of the method/function. Serialized in JSON or toString format. + +## Integration + +AgentScope Studio provides services that comply with the [OpenTelemetry Protocol (OTLP)](https://opentelemetry.io/docs/specs/otlp/) specification. + +By default, after AgentScope Studio starts, it exposes the following service endpoints: + +- **OTLP/Trace/gRPC**: `localhost:4317`, you can adjust the gRPC service endpoint by modifying the `GRPC_PORT` environment variable. +- **OTLP/Trace/HTTP**: `localhost:3000`, you can adjust the HTTP service endpoint by modifying the `PORT` environment variable. + +> 💡 **Tip**: Studio currently only supports receiving Trace type data. + +### AgentScope Application Integration + +The AgentScope framework natively supports Trace data collection and export. You can add some additional code to your application to implement Trace data reporting. + +#### AgentScope Python Application + +Add the following initialization code before your application code. + +```python +import agentscope + +agentscope.init(studio_url="http://localhost:3000") # Replace this with Studio's HTTP service endpoint + +# your application code +``` + +#### AgentScope Java Application + +1. Introduce the dependencies required to connect to Studio in your project. + +maven: + +```xml + + io.agentscope + agentscope-extensions-studio + +``` + +gradle: + +```gradle +implementation("io.agentscope:agentscope-extensions-studio") +``` + +2. Add the following initialization code before your application code. + +```Java +public static void main() { + StudioManager.init() + .studioUrl("http://localhost:3000") + .initialize() + .block(); + + // your application code +} +``` + +### LoongSuite/OpenTelemetry Agent Integration + +LoongSuite agents are non-intrusive observability data collection tools for multi-language AI applications, developed by the Alibaba Cloud Cloud Native team based on OpenTelemetry agents. These agents achieve non-intrusive observability through compile-time/runtime code enhancement mechanisms by completing code instrumentation of application code. + +The data collected by LoongSuite agents and OpenTelemetry agents are both exported using OTLP Exporter, so they can be directly received and stored by AgentScope Studio. Currently supported agents include: + +- [LoongSuite Python Agent](https://github.com/alibaba/loongsuite-python-agent) +- [LoongSuite Go Agent](https://github.com/alibaba/loongsuite-go-agent) +- [LoongSuite Java Agent](https://github.com/alibaba/loongsuite-java-agent) +- [OpenTelemetry Python Agent](https://github.com/open-telemetry/opentelemetry-python-contrib) +- [OpenTelemetry Java Agent](https://github.com/open-telemetry/opentelemetry-java-instrumentation) +- [OpenTelemetry JavaScript Agent](https://github.com/open-telemetry/opentelemetry-js-contrib) +- ...(Any other data collectors that support OTLP Exporter) + +#### LoongSuite Python Agent Integration + +1. Refer to the [LoongSuite Python Agent official documentation](https://github.com/alibaba/loongsuite-python-agent/tree/main/instrumentation-loongsuite/loongsuite-instrumentation-agentscope) to install the agent +2. Modify the startup parameters to export data to AgentScope Studio. Please replace `exporter_otlp_endpoint` with your Studio's gRPC service address + +```shell +loongsuite-instrument \ + --traces_exporter otlp \ + --metrics_exporter console \ + --service_name your-service-name \ + --exporter_otlp_endpoint 0.0.0.0:4317 \ + python myapp.py +``` + +#### OpenTelemetry Java Agent Integration + +1. Refer to the [OpenTelemetry Java Agent official documentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation) to install the agent +2. Modify the startup parameters to export data to AgentScope Studio. Please replace `otel.exporter.otlp.traces.endpoint` with your Studio's gRPC service address + +```shell +java -javaagent:path/to/opentelemetry-javaagent.jar \ + -Dotel.resource.attributes=service.name=your-service-name \ + -Dotel.traces.exporter=otlp \ + -Dotel.metrics.exporter=console \ + -Dotel.exporter.otlp.traces.endpoint=http://localhost:4317 \ + -jar myapp.jar +``` + +### Advanced Integration: Import Custom Trace Data + +If you need to export observability data from any source as trace data to AgentScope Studio, you can assemble the data according to the [OTLP protocol](https://opentelemetry.io/docs/specs/otlp/). AgentScope Studio receives trace data encoded in Protobuf format and provides both HTTP and gRPC services. The service exposure methods follow the [OTLP/HTTP](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/collector/trace/v1/trace_service_http.yaml) and [OTLP/gRPC](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/collector/trace/v1/trace_service.proto) conventions, and the data body follows the [OTLP Protobuf](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/trace/v1/trace.proto) definition. + +#### Export Data Using OTLP Exporter + +To ensure data correctness, it is strongly recommended that you use OTLP Exporter for data export. You can find more detailed tutorials in the [OTLP official documentation](https://opentelemetry.io/docs/specs/otel/protocol/exporter/). Here is an OTLP Exporter example in Python: + +> 💡 **Tip**: This section partially references the [OpenTelemetry Python API](https://opentelemetry-python.readthedocs.io/en/latest/exporter/otlp/otlp.html). + +Create an OTLP Exporter and initialize TracerProvider: + +```Python +from opentelemetry.sdk.trace import TracerProvider +from opentelemetry.sdk.trace.export import BatchSpanProcessor +from opentelemetry.exporter.otlp.proto.http.trace_exporter import ( + OTLPSpanExporter, +) + +tracer_provider = TracerProvider() +# OTLP/HTTP for OpenTelemetry Python SDK by default +exporter = OTLPSpanExporter(endpoint="http://localhost:3000") +span_processor = BatchSpanProcessor(exporter) +tracer_provider.add_span_processor(span_processor) +``` + +Use TracerProvider to create a Tracer and build Span: + +```Python +# create tracer +tracer = tracer_provider.get_tracer("test_module", "1.0.0") + +# create span +# attributes maybe set here +with tracer.start_as_current_span("test") as span: + try: + # do something + # attributes may be set here + span.set_attributes({"test_key": "test_value"}) + span.set_status(trace_api.StatusCode.OK) + return res + + except Exception as e: + span.set_status( + trace_api.StatusCode.ERROR, + str(e), + ) + span.record_exception(e) + raise e from None +``` diff --git a/docs/tutorial/en/index.md b/docs/tutorial/en/index.md new file mode 100644 index 00000000..7ecd00e4 --- /dev/null +++ b/docs/tutorial/en/index.md @@ -0,0 +1,21 @@ +--- +# https://vitepress.dev/reference/default-theme-home-page +layout: home + +hero: + name: 'AgentScope-Studio' + text: 'A development-oriented visualization toolkit for AgentScope' + tagline: 'Transparent, Simple, and Fun' + actions: + - theme: brand + text: Tutorial + link: /tutorial/overview + +features: + - title: Project Management + details: Running management and chatbot-style interface for your AgentScope projects + - title: Tracing Visualization + details: LLM calls, token usage, and agent invocations, all are clearly visible + - title: Agent Evaluation + details: Evaluate your agent system from a new statistical perspective +--- diff --git a/docs/tutorial/en/tutorial/contributing.md b/docs/tutorial/en/tutorial/contributing.md new file mode 100644 index 00000000..1ebb610f --- /dev/null +++ b/docs/tutorial/en/tutorial/contributing.md @@ -0,0 +1,163 @@ +# Contributing to AgentScope-Studio + +## Welcome! 🎉 + +Thank you for your interest in contributing to AgentScope-Studio! As an open-source project, we warmly welcome and encourage contributions from the community. Whether you're fixing bugs, adding new features, improving documentation, or sharing ideas, your contributions help make AgentScope-Studio better for everyone. + +## How to Contribute + +To ensure smooth collaboration and maintain the quality of the project, please follow these guidelines when contributing: + +### 1. Check Existing Plans and Issues + +Before starting your contribution, please review our development roadmap: + +- **Check the [Projects](https://github.com/orgs/agentscope-ai/projects/3) page** and **[Issues with `roadmap` label](https://github.com/agentscope-ai/agentscope-studio/issues?q=is%3Aissue%20state%3Aopen%20label%3ARoadmap)** to see our planned development tasks. + - **If a related issue exists** and is marked as unassigned or open: + - Please comment on the issue to express your interest in working on it + - This helps avoid duplicate efforts and allows us to coordinate development + + - **If no related issue exists**: + - Please create a new issue describing your proposed changes or feature + - Our team will respond promptly to provide feedback and guidance + - This helps us maintain the project roadmap and coordinate community efforts + +### 2. Commit Message Format + +We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification. This leads to a more readable commit history and enables automatic changelog generation. + +**Format:** + +``` +(): +``` + +**Types:** + +- `feat:` A new feature +- `fix:` A bug fix +- `docs:` Documentation only changes +- `style:` Changes that do not affect the meaning of the code (white-space, formatting, etc.) +- `refactor:` A code change that neither fixes a bug nor adds a feature +- `perf:` A code change that improves performance +- `test:` Adding missing tests or correcting existing tests +- `chore:` Changes to the build process or auxiliary tools and libraries + +**Examples:** + +```bash +feat(models): add support for Claude-3 model +fix(agent): resolve memory leak in ReActAgent +docs(readme): update installation instructions +refactor(formatter): simplify message formatting logic +test(models): add unit tests for OpenAI integration +``` + +### 3. Code Development Guidelines + +#### a. Code Formatting + +Before submitting code, you must run the formatting command to ensure code quality and consistency: + +**Running the formatter:** + +```bash +npm run format +``` + +This command will automatically run: + +- **Prettier**: Formats your code style +- **ESLint**: Checks and fixes code quality issues + +Make sure to run this command before committing your changes to ensure all code follows the project's style guidelines. + +#### b. Directory Structure + +Please adhere to the following directory structure when adding or modifying files: + +``` +packages/ + client/src/ + assets/ # Static assets like images and icons + components/ # React components for the frontend UI + context/ # React Context providers for state management and data fetching + i18n/ # Internationalization files + pages/ # Page components for different routes + utils/ # Utility functions and helpers + ... + server/src/ + dao/ # Data Access Objects for database interactions + migrations/ # Database migration scripts + models/ # Database models + otel/ # OpenTelemetry tracing setup + trpc/ # tRPC API route handlers + utils/ # Utility functions and helpers + database.ts # Database connection setup + index.ts # Server entry point + ... +``` + +#### c. Frontend Development Guidelines + +When contributing to the frontend (React/TypeScript), please follow these architectural principles: + +**Separation of Concerns:** + +The **communication and state management** logic must be separated from the **UI components**. Specifically, data fetching and state management should be handled by context providers located in `packages/client/src/context/`, leaving the UI components focused solely on rendering and user interaction. + +**Styling with Tailwind CSS:** + +- All styling must use **Tailwind CSS** utility classes +- Avoid inline styles or separate CSS files for component-specific styling + +```tsx +// ✅ DO: Use Tailwind classes +
+

Title

+ +
+ +// ❌ DON'T: Inline styles +
...
+``` + +#### d. Documentation + +- Update relevant documentation for new features +- Update the README.md if your changes affect user-facing functionality + +## Do's and Don'ts + +### ✅ DO: + +- **Start small**: Begin with small, manageable contributions +- **Communicate early**: Discuss major changes before implementing them +- **Write tests**: Ensure your code is well-tested +- **Document your code**: Help others understand your contributions +- **Follow commit conventions**: Use conventional commit messages +- **Be respectful**: Follow our Code of Conduct +- **Ask questions**: If you're unsure about something, just ask! + +### ❌ DON'T: + +- **Don't surprise us with big pull requests**: Large, unexpected PRs are difficult to review and may not align with project goals. Always open an issue first to discuss major changes +- **Don't ignore CI failures**: Fix any issues flagged by continuous integration +- **Don't mix concerns**: Keep PRs focused on a single feature or fix +- **Don't forget to update tests**: Changes in functionality should be reflected in tests +- **Don't break existing APIs**: Maintain backward compatibility when possible, or clearly document breaking changes +- **Don't add unnecessary dependencies**: Keep the core library lightweight + +## Getting Help + +If you need assistance or have questions: + +- 💬 Open a [Discussion](https://github.com/agentscope-ai/agentscope-studio/discussions) +- 🐛 Report bugs via [Issues](https://github.com/agentscope-ai/agentscope-studio/issues) +- 📧 Contact the maintainers via DingTalk or Discord (links in the README.md) + +--- + +Thank you for contributing to AgentScope-Studio! Your efforts help build a better tool for the entire community. 🚀 diff --git a/docs/tutorial/en/tutorial/overview.md b/docs/tutorial/en/tutorial/overview.md new file mode 100644 index 00000000..86b29ac0 --- /dev/null +++ b/docs/tutorial/en/tutorial/overview.md @@ -0,0 +1,41 @@ +# Overview + +## _What is AgentScope-Studio?_ + +AgentScope-Studio is a visualization toolkit designed for developers working with the +[AgentScope library](https://github.com/agentscope-ai/agentscope). +It provides a **transparent**, **simple**, and **fun** way to develop, debug, +and evaluate agent-based applications. + +## _Why AgentScope-Studio?_ + +AgentScope-Studio provides: + +- Project management and chatbot-style visualization +- OpenTelemetry-based tracing visualization +- Evaluation-oriented analysis and visualization +- A built-in agent (AgentScope-Friday) for quick secondary development + +## _How Does AgentScope-Studio Work?_ + +AgentScope-Studio is built with + +- frontend: Typescript, React, Vite, TailwindCSS +- communication: TRPC over HTTP, websocket +- backend: Node.js, Express +- database: TypeORM with SQLite + +> 💡 **Tip**: We are currently migrating the codebase to TailwindCSS. + +AgentScope-Studio is released on the NPM registry as the package `@agentscope/studio` under the Apache-2.0 license. + +## _How to Contribute?_ + +AgentScope-Studio is an open-source project, and we welcome contributions from the community. Please refer to our +[contribution guide](./contributing) for more details on how to get involved. + +## _By the Way_ + +While we may not be professionals in frontend and backend development, we are committed to building the most transparent, +simple, and fun user experience for developers using AgentScope. +Any suggestions and contributions are highly appreciated! diff --git a/docs/tutorial/en/tutorial/quick_start.md b/docs/tutorial/en/tutorial/quick_start.md new file mode 100644 index 00000000..5f0af1ce --- /dev/null +++ b/docs/tutorial/en/tutorial/quick_start.md @@ -0,0 +1,63 @@ +# QuickStart + +## Prerequisites + +- Node.js >= 20.0.0 +- npm >= 10.0.0 + +> 💡 **Tip**: If you're using nvm, you can run nvm use to automatically switch to the required Node.js version. + +How to check your Node.js version: + +```bash +node --version +npm --version +``` + +## Install + +### From NPM + +```bash +npm install -g @agentscope/studio + +# Then run the following command to start AgentScope-Studio: +as_studio +``` + +### From Source + +```bash +git clone https://github.com/agentscope-ai/agentscope-studio +cd agentscope-studio +npm install + +# Then run the following command to start AgentScope-Studio: +npm run dev +``` + +## Connect to AgentScope-Studio + +In an AgentScope project, set the `studio_url` field in the `init` function as follows: + +```python +import agentscope + +agentscope.init( + ... + # Replace with the port you started AgentScope-Studio on + studio_url="http://localhost:3000", +) +``` + +## Configuration + +To configure AgentScope-Studio settings, you can create a `.env` file where you start AgentScope-Studio. +Here are some common configuration options: + +> 💡 **Tip**: We are working on adding more configuration options. Stay tuned! + +```env +PORT=3000 +GRPC_PORT=4317 +``` diff --git a/docs/tutorial/zh_CN/agent/assets/friday_setting.png b/docs/tutorial/zh_CN/agent/assets/friday_setting.png new file mode 100644 index 00000000..9243cd16 Binary files /dev/null and b/docs/tutorial/zh_CN/agent/assets/friday_setting.png differ diff --git a/docs/tutorial/zh_CN/agent/friday.md b/docs/tutorial/zh_CN/agent/friday.md new file mode 100644 index 00000000..6c132f30 --- /dev/null +++ b/docs/tutorial/zh_CN/agent/friday.md @@ -0,0 +1,48 @@ +# AgentScope-Friday + +Friday 是一个由 AgentScope 构建的实验性本地部署智能体，旨在： + +- 回答有关 AgentScope 的问题， +- 为开发者提供快速的二次开发环境， +- 集成 AgentScope 中所有可用的功能来构建更强大的智能体， +- 测试和集成 AgentScope 中的高级功能。 + +它的源代码也在 [AgentScope-Studio 仓库](https://github.com/agentscope-ai/agentscope-studio/tree/main/packages/app)中开源。 + +代码结构如下： + +``` +packages/ + app/ + friday/ + tool/ + utils/ + connect.py # 用于实时操控/中断的 websocket 连接 + ... + main.py # Friday 智能体的入口点 + args.py # Friday 智能体的参数解析器 + hook.py # 用于将消息推送到 AgentScope-Studio 前端的钩子函数 + model.py # 基于配置初始化 LLM + requirements.txt # Friday 智能体的依赖项 +``` + +## 如何使用 + +第一次使用 Friday 时，需要在以下页面中配置智能体，包括模型、API KEY、工具和其他参数。 + +![Friday 配置页面](assets/friday_setting.png) + +之后，就可以在聊天页面开始与 Friday 对话了。 + +## 已配备的功能 + +我们正在持续为 Friday 集成更多功能。当前和即将推出的功能包括： + +- [x] 与 LLM 的基本聊天功能 +- [x] 支持元工具（meta tool） +- [x] 支持实时操控/中断 +- [x] 支持状态/会话管理 +- [ ] 🚧 支持规划和规划可视化 +- [ ] 🚧 支持长期记忆 +- [ ] 支持 Anthropic 智能体技能 +- [ ] 支持用户动态添加 MCP 服务器 diff --git a/docs/tutorial/zh_CN/develop/assets/project-management.png b/docs/tutorial/zh_CN/develop/assets/project-management.png new file mode 100644 index 00000000..7b5f4843 Binary files /dev/null and b/docs/tutorial/zh_CN/develop/assets/project-management.png differ diff --git a/docs/tutorial/zh_CN/develop/assets/react-agent-example.png b/docs/tutorial/zh_CN/develop/assets/react-agent-example.png new file mode 100644 index 00000000..f84dd2d5 Binary files /dev/null and b/docs/tutorial/zh_CN/develop/assets/react-agent-example.png differ diff --git a/docs/tutorial/zh_CN/develop/assets/run-management.png b/docs/tutorial/zh_CN/develop/assets/run-management.png new file mode 100644 index 00000000..e44b2730 Binary files /dev/null and b/docs/tutorial/zh_CN/develop/assets/run-management.png differ diff --git a/docs/tutorial/zh_CN/develop/assets/tracing_detail_attributes.png b/docs/tutorial/zh_CN/develop/assets/tracing_detail_attributes.png new file mode 100644 index 00000000..9f0f9c8f Binary files /dev/null and b/docs/tutorial/zh_CN/develop/assets/tracing_detail_attributes.png differ diff --git a/docs/tutorial/zh_CN/develop/assets/tracing_detail_chat_history.png b/docs/tutorial/zh_CN/develop/assets/tracing_detail_chat_history.png new file mode 100644 index 00000000..960bb7f1 Binary files /dev/null and b/docs/tutorial/zh_CN/develop/assets/tracing_detail_chat_history.png differ diff --git a/docs/tutorial/zh_CN/develop/assets/tracing_overview.png b/docs/tutorial/zh_CN/develop/assets/tracing_overview.png new file mode 100644 index 00000000..8e26a1dd Binary files /dev/null and b/docs/tutorial/zh_CN/develop/assets/tracing_overview.png differ diff --git a/docs/tutorial/zh_CN/develop/assets/user-input-flow.png b/docs/tutorial/zh_CN/develop/assets/user-input-flow.png new file mode 100644 index 00000000..1e1c1fec Binary files /dev/null and b/docs/tutorial/zh_CN/develop/assets/user-input-flow.png differ diff --git a/docs/tutorial/zh_CN/develop/evaluation.md b/docs/tutorial/zh_CN/develop/evaluation.md new file mode 100644 index 00000000..12f886b4 --- /dev/null +++ b/docs/tutorial/zh_CN/develop/evaluation.md @@ -0,0 +1,3 @@ +# 评测 + +即将更新 ... diff --git a/docs/tutorial/zh_CN/develop/project.md b/docs/tutorial/zh_CN/develop/project.md new file mode 100644 index 00000000..3d9516d0 --- /dev/null +++ b/docs/tutorial/zh_CN/develop/project.md @@ -0,0 +1,317 @@ +# 项目管理 + +AgentScope-Studio 提供了强大的项目管理功能，帮助你可视化地管理你的 AgentScope 项目。通过 Projects 和 Runs 的组织结构，你可以清晰地分离和管理你的可观测性数据。 + +## 概念 + +在 AgentScope-Studio 中，一个**项目（Projects）**包含多个**运行实例（Runs）**。具体而言： + +- **项目（Projects）**：用于组织和隔离不同的 AI 应用或实验 +- **运行实例（Runs）**：项目内的单次执行实例，类似于会话（Session），跟踪一次完整的运行过程 + +## 项目管理 + +AgentScope-Studio 的项目页面（Projects）提供了运行项目的总览和管理功能： + +![项目管理](assets/project-management.png) + +点击项目列表中的任意项目，可以进入运行管理界面，查看该项目下的所有运行实例。 + +## 运行实例管理 + +### 运行可视化 + +运行实例中包含了完整的执行跟踪和状态监控功能。 +在（左）侧栏中，按照时间顺序堆叠了该项目下所有的运行实例。点击任意运行实例，可以在 Chatbot 风格的 UI 中查看该运行的完整交互历史和状态。 +除此之外，右侧的面板还提供了该运行的详细信息和统计数据。 + +![运行管理](assets/run-management.png) + +在 AgentScope 中，智能体一次回复（即调用一次 `reply` 函数）对应会产生多条消息（`Msg` 对象），这些消息的可能是用来引导大模型的提示消息 +（角色为 "user"），也可能是工具运行结果（角色为 "system"）。 + +因此，在可视化的层面，我们在消息的层次之上引入了**回复（reply）**的概念， +用于将多条消息组织在一起，形成一个完整的智能体回复单元。 +在运行可视化界面中，开发者可以选择按照 `replyId` 或 `msg.id` 来查看消息。 + +### 用户输入托管 + +当 AgentScope 项目连接到 Studio 后，Studio 会自动托管用户的输入，并通过 WebSocket 实时推送到 Python 的智能体应用中。并且 Studio 支持 +在一个运行实例中包含多个不同的 `UserAgent` 实例，从而实现多用户协同交互的场景。 + +### 运行追踪可视化 + +AgentScope-Studio 在右侧面板中同时提供了基于 OpenTelemetry 的追踪数据可视化功能，帮助开发者详细了解每一次运行过程中智能体对象、 +大模型调用、工具使用等各个单元的详细输入输出。 + +## API 协议 + +AgentScope-Studio 中项目管理相关的 API 协议如下： + +> **注意**: 关于 Trace 数据格式、推送机制和集成示例的详细信息，请参考 [Trace 文档](tracing.md)。 + +| 功能 | 接口路径 | 方法 | 用途 | +| ------------ | ------------------------ | ---- | -------------------------- | +| 注册运行实例 | `/trpc/registerRun` | POST | 注册新的 Agent 运行实例 | +| 推送消息 | `/trpc/pushMessage` | POST | 发送 Agent 消息到 Web 界面 | +| 请求用户输入 | `/trpc/requestUserInput` | POST | Agent 主动请求用户输入 | + +### 1. 注册运行协议 + +在 Studio 上注册运行实例。 + +| 字段 | 类型 | 必需 | 说明 | +| ----------- | ------ | ---- | --------------------------------------------- | +| `id` | string | ✓ | 运行实例的 ID | +| `project` | string | ✓ | 项目名称 | +| `name` | string | ✓ | 运行实例名称 | +| `timestamp` | string | ✓ | ISO 时间戳 | +| `pid` | number | ✓ | 进程 ID | +| `status` | enum | ✓ | 运行状态（如 "running"、"finished"、"error"） | + +### 2. 消息推送协议 + +将 `Msg` 对象发送到 Studio 进行显示。 + +| 字段 | 类型 | 必需 | 说明 | +| --------------- | ------------- | ---- | -------------------------------------------------- | +| `runId` | string | ✓ | 运行实例 ID | +| `replyId` | string | ✓ | 回复消息 ID | +| `replyName` | string | ✓ | 回复者的名字 | +| `replyRole` | string | ✓ | 回复者的角色（如 "assistant"、"user"） | +| `msg.id` | string | ✓ | 消息 ID | +| `msg.name` | string | ✓ | 消息发送者名字 | +| `msg.role` | string | ✓ | 消息发送者角色（如 "assistant"、"user"、"system"） | +| `msg.content` | ContentBlocks | ✓ | 消息内容 | +| `msg.metadata` | object | ✓ | 消息元数据 | +| `msg.timestamp` | string | ✓ | 消息 ISO 时间戳 | + +**ContentBlocks 格式：** + +`ContentBlocks` 是一个内容块数组。每个块都有一个 `type` 字段，用于确定其结构。支持的内容块类型包括： + +- **文本块** (`type: "text"`): 包含 `text` 字段，存储消息内容 +- **思考块** (`type: "thinking"`): 包含 `thinking` 字段，存储推理内容 +- **图片块** (`type: "image"`): 包含 `source` 字段，可以是 base64 数据或 URL +- **音频块** (`type: "audio"`): 包含 `source` 字段，可以是 base64 数据或 URL +- **视频块** (`type: "video"`): 包含 `source` 字段，可以是 base64 数据或 URL +- **工具使用块** (`type: "tool_use"`): 包含 `id`、`name` 和 `input` 字段 +- **工具结果块** (`type: "tool_result"`): 包含 `id`、`name` 和 `output` 字段 + +对于媒体块（图片、音频、视频），`source` 可以是： + +- **Base64 源**: `{ type: "base64", media_type: string, data: string }` +- **URL 源**: `{ type: "url", url: string }` + +**示例：** + +```python +content_blocks = [ + { + "type": "text", + "text": "来自你的智能体的问候！" + }, + { + "type": "image", + "source": { + "type": "base64", + "media_type": "image/jpeg", + "data": "data:image/jpeg;base64,/9j/4AAQSkZJRg..." + } + }, + { + "type": "tool_use", + "id": "tool-123", + "name": "search", + "input": {"query": "weather"} + } +] +``` + +### 3. 用户输入协议 + +要求用户在 Studio 的前端页面上以某个角色/名字/身份进行输入。 + +**请求字段：** + +| 字段 | 类型 | 必需 | 说明 | +| ----------------- | ------ | ---- | ---------------------------- | +| `requestId` | string | ✓ | 用户输入请求 ID | +| `runId` | string | ✓ | 运行实例 ID | +| `agentId` | string | ✓ | Agent ID | +| `agentName` | string | ✓ | Agent 名称 | +| `structuredInput` | object | | 结构化输入表单的 JSON Schema | + +用户输入的具体实现逻辑涉及 Python 应用、Studio 服务器和前端之间的多方交互。以下是详细的交互流程： + +![用户输入流程](assets/user-input-flow.png) + +1. **Agent 发送请求**：Agent 通过 POST 请求向 Studio 服务器发送用户输入请求 +2. **服务器保存请求**：Studio 服务器将请求保存到数据库，并通过 WebSocket 推送到 Web 客户端 +3. **用户输入**：用户在 Web 界面中输入内容 +4. **客户端发送**：Web 客户端通过 WebSocket 将用户输入发送回服务器 +5. **服务器转发**：服务器验证并转发用户输入到 Agent 的 WebSocket 连接 +6. **Agent 接收**：Agent 通过 WebSocket 接收用户输入并继续执行 + +## 集成示例 + +以下示例展示如何集成项目管理的相关协议： + +```python +from agentscope.message import Msg +from datetime import datetime +from queue import Queue +from threading import Event +from typing import Any, List + +import requests +import shortuuid +import socketio + + +class StudioClient: + """用于自定义 Agent 集成的完整 Studio 客户端""" + + def __init__(self, studio_url: str): + self.studio_url = studio_url + self.sio = socketio.Client() + self.input_queues = {} + self.input_events = {} + + def register_run( + self, + id: str, + project: str, + name: str, + timestamp: str, + pid: int, + status: str, + ) -> None: + """注册运行实例""" + response = requests.post( + f"{self.studio_url}/trpc/registerRun", + json={ + "id": id, + "project": project, + "name": name, + "timestamp": timestamp, + "pid": pid, + "status": status, + }, + timeout=10 + ) + response.raise_for_status() + + # 连接 WebSocket 以接收用户输入 + self.sio.connect( + self.studio_url, + namespaces=["/python"], + auth={"run_id": id} + ) + + # 监听用户输入 + @self.sio.on("forwardUserInput", namespace="/python") + def receive_user_input( + request_id: str, + blocks_input: List[dict], + structured_input: dict[str, Any], + ) -> None: + if request_id in self.input_queues: + self.input_queues[request_id].put({ + "blocks_input": blocks_input, + "structured_input": structured_input, + }) + self.input_events[request_id].set() + + def push_message( + self, + run_id: str, + reply_id: str, + reply_name: str, + reply_role: str, + msg: Msg + ) -> None: + """推送消息到 Studio""" + payload = { + "runId": run_id, + "replyId": reply_id, + "replyName": reply_name, + "replyRole": reply_role, + "msg": msg.to_dict() + } + + response = requests.post( + f"{self.studio_url}/trpc/pushMessage", + json=payload, + timeout=10 + ) + response.raise_for_status() + + def request_user_input(self, run_id: str, agent_id: str, agent_name: str, + structured_input=None): + """从 Studio 请求用户输入""" + + request_id = shortuuid.uuid() + self.input_queues[request_id] = Queue() + self.input_events[request_id] = Event() + + try: + response = requests.post( + f"{self.studio_url}/trpc/requestUserInput", + json={ + "requestId": request_id, + "runId": run_id, + "agentId": agent_id, + "agentName": agent_name, + "structuredInput": structured_input + }, + timeout=10 + ) + response.raise_for_status() + + # 等待用户响应 + self.input_events[request_id].wait(timeout=300) + if request_id in self.input_queues: + return self.input_queues[request_id].get() + else: + raise TimeoutError("User input timeout") + finally: + # 清理 + if request_id in self.input_queues: + del self.input_queues[request_id] + if request_id in self.input_events: + del self.input_events[request_id] + + +# 使用示例 +client = StudioClient("http://localhost:3000") + +# 注册运行 +client.register_run( + id="run-12345", + project="my-project", + name="custom-agent", + timestamp=datetime.now().strftime("%Y-%m-%d %H:%M:%S"), + pid=12345, + status="running" +) + +# 创建一条提示消息 +msg = Msg("my-agent", "你现在应该...", "user") +# 推送消息 +client.push_message( + run_id="run-12345", + reply_id="reply-1", + reply_name="my-agent", + reply_role="assistant", + msg=msg +) + +# 请求用户输入 +user_response = client.request_user_input( + run_id="run-12345", + agent_id="agent-1", + agent_name="My Agent" +) +print(f"User responded: {user_response}") +``` diff --git a/docs/tutorial/zh_CN/develop/tracing.md b/docs/tutorial/zh_CN/develop/tracing.md new file mode 100644 index 00000000..eedaed17 --- /dev/null +++ b/docs/tutorial/zh_CN/develop/tracing.md @@ -0,0 +1,274 @@ +# 运行追踪 + +在 Studio 侧边栏的 Trace 页面中可以查看运行追踪的详细信息。包括各个模块的输入、输出、工具调用情况、执行耗时等各种运行信息。 + +该功能基于 [OpenTelemetry 语义规范](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/)和 [OTLP 协议](https://opentelemetry.io/docs/specs/otlp/)构建，不仅可以开箱即用地接收和存储 AgentScope 上报的各种可观测信息， +还支持任意的基于 OpenTelemetry 或 LoongSuite 的采集工具/AI 应用框架上报的数据的集成。 + +![Trace](assets/tracing_detail_chat_history.png) + +## 概览页面 + +在本页面可以查看上报到 Studio 的链路数据的基本信息。 + +> 💡 **提示**：将鼠标移动到链路名称后面的图标上可以查看到该条链路的基本元信息，如 Trace ID。 + +![Trace](assets/tracing_overview.png) + +## 详情页面 + +单击概览页面中的任意一条链路可以查看这条链路的调用顺序与调用关系；进一步点选不同层级的调用，可以看到这些调用发生时详细的上下文。 + +在 Metadata 区域可以查看调用的输入和输出。 +对于 AI 相关的调用，如 LLM、Agent 等，输入输出会按照 OpenTelemetry 语义规范定义的[结构](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/#recording-content-on-attributes)进行展示。对于常规调用，如 Function、Format 等，输入输出会遵循 AgentScope 扩展[语义规范](#agentscope-扩展规范)展示。 + +![Trace](assets/tracing_detail_chat_history.png) + +在 All Attributes 区域，能够看到本次调用的所有关键的元信息，命名遵循[语义规范](#语义规范)。 + +![Trace](assets/tracing_detail_attributes.png) + +## 语义规范 + +AgentScope-Studio 的可观测性数据遵循基于 [OpenTelemetry](#opentelemetry-generative-ai) 的语义规范。遵循该语义规范的数据会在 Studio 中得到更加准确、清晰的处理 +与展示。 + +> 💡 **提示**：AgentScope 库原生的可观测能力已经遵循该语义规范。即便其他来源的可观测数据暂不遵循该语义规范，依然可以正常展示链路数据，但部分关键信息可能无法高亮/专门展示。 + +### OpenTelemetry Generative AI + +OpenTelemetry 面向 Generative AI 类应用的可观测数据提供了一组语义规范标准，详细定义参见 [Semantic conventions for generative client AI spans](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/) 与 [Semantic Conventions for GenAI agent and framework spans](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-agent-spans/)。 + +> 💡 **提示**：Studio 当前遵循的 OpenTelemetry 语义规范版本为 1.38.0。 + +当前遵循的语义规范包括： + +- [**Inference**](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/#inference): model 调用 +- [**Invoke agent span**](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-agent-spans/#invoke-agent-span): agent 调用 +- [**Execute tool span**](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/#execute-tool-span): toolkit 调用 + +### AgentScope 扩展规范 + +除定义在 OpenTelemetry 中的各种语义规范外，为了更清晰地展示调用过程，AgentScope 对一些特定的调用过程进行了语义规范的扩展。 + +#### Common 调用 + +适用于 AI 应用中发生的所有关键调用过程。 + +| Key | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | +| ---------------------------- | ----------------------------------------------------------------------------------------------------- | ---------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `agentscope.function.name` | `Recommended` | string | 调用的方法/函数名。 | `DashScopeChatModel.__call__`; `ToolKit.callTool` | +| `agentscope.function.input` | `Opt-In` | string | 方法/函数的输入。[1] | {
  "tool_call": {
    "type": "tool_use",
    "id": "call_83fce0d1d2684545a13649",
    "name": "multiply",
    "input": {
      "a": 5,
      "b": 3
    }
  }
} | +| `agentscope.function.output` | `Opt-In` | string | 方法/函数的返回值。[2] | `ToolResponse(content=[{'type': 'text', 'text': '5 × 3 = 15'}], metadata=None, stream=False, is_last=True, is_interrupted=False, id='2025-11-28 00:38:52.733_cc4ead')` | + +**[1] `agentscope.function.input`**: 方法/函数入参。**需要**按照 JSON 的格式序列化。 + +**[2] `agentscope.function.output`**: 方法/函数的返回值。按照 JSON 或 toString 的方式序列化。 + +#### Format 调用 + +该 span 代表发起 model 调用前对请求的准备和格式化过程。在 AgentScope 中，该方法对应 Formatter 工具的调用。 + +`gen_ai.operation.name` **应该**为`format`。 + +**Span 名称应该**为`format {agentscope.format.target}`。 + +**Span kind 应该**为`INTERNAL`。 + +**Span status 应该**遵循[记录错误](https://opentelemetry.io/docs/specs/semconv/general/recording-errors/)文档。 + +**Attributes:** + +| Key | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | +| ---------------------------- | ----------------------------------------------------------------------------------------------------- | ---------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `gen_ai.operation.name` | `Required` | string | 正在执行的操作的名称。 | `chat`; `generate_content`; `text_completion` | +| `error.type` | `Conditionally Required` if the operation ended in an error | string | 操作中止时抛出的错误。 | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | +| `agentscope.format.target` | `Required` | string | 格式化要转为的目标类型。如果无法解析到目标类型，则设置为'unknown'。 | `dashscope`; `openai` | +| `agentscope.format.count` | `Recommended` | int | 实际被格式化的消息数量。[1] | `3` | +| `agentscope.function.name` | `Recommended` | string | 调用的方法/函数名。 | `DashScopeChatModel.__call__`; `ToolKit.callTool` | +| `agentscope.function.input` | `Opt-In` | string | 方法/函数的输入。[2] | {
  "tool_call": {
    "type": "tool_use",
    "id": "call_83fce0d1d2684545a13649",
    "name": "multiply",
    "input": {
      "a": 5,
      "b": 3
    }
  }
} | +| `agentscope.function.output` | `Opt-In` | string | 方法/函数的返回值。[3] | `ToolResponse(content=[{'type': 'text', 'text': '5 × 3 = 15'}], metadata=None, stream=False, is_last=True, is_interrupted=False, id='2025-11-28 00:38:52.733_cc4ead')` | + +**[1] `agentscope.format.count`**: 实际被格式化的消息数量。取值与格式化函数执行后返回的消息列表大小一致，如果在格式化过程中进行了截断或消息裁剪，则该取值可能小于传入的消息列表大小。 + +**[2] `agentscope.function.input`**: 方法/函数入参。**需要**按照 JSON 的格式序列化。 + +**[3] `agentscope.function.output`**: 方法/函数的返回值。按照 JSON 或 toString 的方式序列化。 + +#### Function 调用 + +该 span 代表发起一次任意的关键调用的过程。在 AgentScope 中，该方法对应常规函数的执行过程，当且仅当使用者通过 AgentScope 提供的方式为方法/函数添加链路追踪能力时生效。 + +`gen_ai.operation.name` **应该**为`invoke_generic_function`。 + +**Span 名称应该**为`invoke_generic_function {agentscope.function.name}`。 + +**Span kind 应该**为`INTERNAL`。 + +**Span status 应该**遵循[记录错误](https://opentelemetry.io/docs/specs/semconv/general/recording-errors/)文档。 + +**Attributes:** + +| Key | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | +| ---------------------------- | ----------------------------------------------------------------------------------------------------- | ---------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `gen_ai.operation.name` | `Required` | string | 正在执行的操作的名称。 | `chat`; `generate_content`; `text_completion` | +| `error.type` | `Conditionally Required` if the operation ended in an error | string | 操作中止时抛出的错误。 | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | +| `agentscope.function.name` | `Recommended` | string | 调用的方法/函数名。 | `DashScopeChatModel.__call__`; `ToolKit.callTool` | +| `agentscope.function.input` | `Opt-In` | string | 方法/函数的输入。[1] | {
  "tool_call": {
    "type": "tool_use",
    "id": "call_83fce0d1d2684545a13649",
    "name": "multiply",
    "input": {
      "a": 5,
      "b": 3
    }
  }
} | +| `agentscope.function.output` | `Opt-In` | string | 方法/函数的返回值。[2] | `ToolResponse(content=[{'type': 'text', 'text': '5 × 3 = 15'}], metadata=None, stream=False, is_last=True, is_interrupted=False, id='2025-11-28 00:38:52.733_cc4ead')` | + +**[1] `agentscope.function.input`**: 方法/函数入参。**需要**按照 JSON 的格式序列化。 + +**[2] `agentscope.function.output`**: 方法/函数的返回值。按照 JSON 或 toString 的方式序列化。 + +## 集成 + +AgentScope Studio 提供 [OpenTelemetry 协议(OTLP)](https://opentelemetry.io/docs/specs/otlp/) 规范的服务。 + +默认情况下，AgentScope Studio 启动后，会暴露以下服务端点： + +- **OTLP/Trace/gRPC**: `localhost:4317`，可以通过修改 `GRPC_PORT` 环境变量来调整 gRPC 的服务端点。 +- **OTLP/Trace/HTTP**: `localhost:3000`，可以通过修改 `PORT` 环境变量来调整 HTTP 的服务端点。 + +> 💡 **提示**：当前 Studio 仅支持接收 Trace 类型数据。 + +### AgentScope 应用集成 + +AgentScope 框架原生支持了 Trace 数据的采集与导出，您可以在应用中增加一些额外的代码实现 Trace 数据的上报。 + +#### AgentScope Python 应用 + +在您的应用代码前增加以下初始化代码。 + +```python +import agentscope + +agentscope.init(studio_url="http://localhost:3000") # 将此处替换为 Studio 的 HTTP 服务端点 + +# your application code +``` + +#### AgentScope Java 应用 + +1. 在您的项目中引入连接 Studio 所需的依赖。 + +maven: + +```xml + + io.agentscope + agentscope-extensions-studio + +``` + +gradle: + +```gradle +implementation("io.agentscope:agentscope-extensions-studio") +``` + +2. 在您的应用代码前增加以下初始化代码。 + +```Java +public static void main() { + StudioManager.init() + .studioUrl("http://localhost:3000") + .initialize() + .block(); + + // your application code +} +``` + +### LoongSuite/OpenTelemetry 探针集成 + +LoongSuite 探针是阿里云云原生团队基于 OpenTelemetry 探针研发的，面向多语言 AI 应用的无侵入可观测数据采集工具。这些探针通过编译时/运行时代码增强的机制，通过对应用代码完成代码插桩实现无侵入的可观测性。 + +LoongSuite 探针和 OpenTelemetry 探针所采集的数据均使用 OTLP Exportor 进行导出，因此可以直接被 AgentScope Studio 接收和存储。当前支持的探针包括： + +- [LoongSuite Python Agent](https://github.com/alibaba/loongsuite-python-agent) +- [LoongSuite Go Agent](https://github.com/alibaba/loongsuite-go-agent) +- [LoongSuite Java Agent](https://github.com/alibaba/loongsuite-java-agent) +- [OpenTelemetry Python Agent](https://github.com/open-telemetry/opentelemetry-python-contrib) +- [OpenTelemetry Java Agent](https://github.com/open-telemetry/opentelemetry-java-instrumentation) +- [OpenTelemetry JavaScript Agent](https://github.com/open-telemetry/opentelemetry-js-contrib) +- ...(其他任何支持的 OTLP Exporter 的数据采集器) + +#### LoongSuite Python 探针集成 + +1. 参考 [LoongSuite Python 探针官方文档](https://github.com/alibaba/loongsuite-python-agent/tree/main/instrumentation-loongsuite/loongsuite-instrumentation-agentscope)，安装探针 +2. 修改启动参数，将数据导出到 AgentScope Studio，请将 `exporter_otlp_endpoint` 替换为您 Studio 的 gRPC 服务地址 + +```shell +loongsuite-instrument \ + --traces_exporter otlp \ + --metrics_exporter console \ + --service_name your-service-name \ + --exporter_otlp_endpoint 0.0.0.0:4317 \ + python myapp.py +``` + +#### OpenTelemetry Java 探针集成 + +1. 参考 [OpenTelemetry Java 探针官方文档](https://github.com/open-telemetry/opentelemetry-java-instrumentation)，安装探针 +2. 修改启动参数，将数据导出到 AgentScope Studio，请将 `otel.exporter.otlp.traces.endpoint` 替换为您 Studio 的 gRPC 服务地址 + +```shell +java -javaagent:path/to/opentelemetry-javaagent.jar \ + -Dotel.resource.attributes=service.name=your-service-name \ + -Dotel.traces.exporter=otlp \ + -Dotel.metrics.exporter=console \ + -Dotel.exporter.otlp.traces.endpoint=http://localhost:4317 \ + -jar myapp.jar +``` + +### 高级集成：导入自定义链路数据 + +如果您需要将任意来源的可观测数据作为链路数据导出到 AgentScope Studio，可以参照 [OTLP 协议](https://opentelemetry.io/docs/specs/otlp/)对数据进行组装。AgentScope Studio 接收 Protobuf 格式编码的链路数据，并同时提供 HTTP 和 gRPC 服务，服务暴露方式分别遵循 [OTLP/HTTP](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/collector/trace/v1/trace_service_http.yaml) 和 [OTLP/gRPC](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/collector/trace/v1/trace_service.proto) 约定，数据体遵循 [OTLP Protobuf](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/trace/v1/trace.proto) 定义。 + +#### 使用 OTLP Exporter 导出数据 + +为保证数据正确性，强烈建议您使用 OTLP Exporter 进行数据导出。您可以在 [OTLP 官方文档](https://opentelemetry.io/docs/specs/otel/protocol/exporter/)中找到更详细的教程。以下是 Python 语言的 OTLP Exporter 示例: + +> 💡 **提示**：本节部分参考自 [OpenTelemetry Python API](https://opentelemetry-python.readthedocs.io/en/latest/exporter/otlp/otlp.html)。 + +创建 OTLP Exporter 并初始化 TracerProvider： + +```Python +from opentelemetry.sdk.trace import TracerProvider +from opentelemetry.sdk.trace.export import BatchSpanProcessor +from opentelemetry.exporter.otlp.proto.http.trace_exporter import ( + OTLPSpanExporter, +) + +tracer_provider = TracerProvider() +# OTLP/HTTP for OpenTelemetry Python SDK by default +exporter = OTLPSpanExporter(endpoint="http://localhost:3000") +span_processor = BatchSpanProcessor(exporter) +tracer_provider.add_span_processor(span_processor) +``` + +使用 TracerProvider 创建 Tracer 并构建 Span： + +```Python +# create tracer +tracer = tracer_provider.get_tracer("test_module", "1.0.0") + +# create span +# attributes maybe set here +with tracer.start_as_current_span("test") as span: + try: + # do something + # attributes may be set here + span.set_attributes({"test_key": "test_value"}) + span.set_status(trace_api.StatusCode.OK) + return res + + except Exception as e: + span.set_status( + trace_api.StatusCode.ERROR, + str(e), + ) + span.record_exception(e) + raise e from None +``` diff --git a/docs/tutorial/zh_CN/index.md b/docs/tutorial/zh_CN/index.md new file mode 100644 index 00000000..c8323d36 --- /dev/null +++ b/docs/tutorial/zh_CN/index.md @@ -0,0 +1,21 @@ +--- +# https://vitepress.dev/reference/default-theme-home-page +layout: home + +hero: + name: 'AgentScope-Studio' + text: 'AgentScope 开发者的可视化开发组件' + tagline: '透明，简单，有趣' + actions: + - theme: brand + text: 使用教程 + link: /zh_CN/tutorial/overview + +features: + - title: 项目管理 + details: 可视化地管理你的 AgentScope 项目，项目详情、运行历史一目了然 + - title: 可视化追踪 + details: LLM 调用、工具使用、智能体调用过程清晰可见，轻松调试智能体应用 + - title: 应用评测 + details: 提供面向智能体应用的评测、分析和归因，从统计的角度评估智能体性能 +--- diff --git a/docs/tutorial/zh_CN/tutorial/contributing.md b/docs/tutorial/zh_CN/tutorial/contributing.md new file mode 100644 index 00000000..63163dbc --- /dev/null +++ b/docs/tutorial/zh_CN/tutorial/contributing.md @@ -0,0 +1,163 @@ +# 为 AgentScope-Studio 做贡献 + +## 欢迎！🎉 + +感谢对 AgentScope-Studio 的关注！作为一个开源项目，我们热烈欢迎并鼓励来自社区的贡献。无论是修复 bug、添加新功能、改进文档，还是分享想法，你的贡献都能让 AgentScope-Studio 变得更好！ + +## 如何贡献 + +为了确保顺畅的协作并保持项目质量，请在贡献时遵循以下指南： + +### 1. 检查现有开发计划和 Issue + +在开始贡献之前，请查看我们的开发路线图： + +- **查看 [Projects](https://github.com/orgs/agentscope-ai/projects/3) 页面**和**[带有 `roadmap` 标签的 Issues](https://github.com/agentscope-ai/agentscope-studio/issues?q=is%3Aissue%20state%3Aopen%20label%3ARoadmap)**，了解我们计划中的开发任务。 + - **如果存在相关 issue** 且标记为未分配或开放状态： + - 请在 issue 下评论表达你对该任务的兴趣 + - 这有助于避免重复工作，让我们能够协调开发进度 + + - **如果不存在相关 issue**： + - 请创建一个新的 issue，描述你建议的更改或功能 + - 我们的团队会及时回复并提供反馈和指导 + - 这有助于我们维护项目路线图并协调社区工作 + +### 2. 提交信息格式 + +我们遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范。这有助于生成更易读的提交历史，并支持自动生成变更日志。 + +**格式：** + +``` +(): +``` + +**类型：** + +- `feat:` 新功能 +- `fix:` bug 修复 +- `docs:` 仅文档更改 +- `style:` 不影响代码含义的更改（空格、格式化等） +- `refactor:` 既不修复 bug 也不添加功能的代码更改 +- `perf:` 提升性能的代码更改 +- `test:` 添加缺失的测试或修正现有测试 +- `chore:` 构建过程或辅助工具和库的更改 + +**示例：** + +```bash +feat(models): add support for Claude-3 model +fix(agent): resolve memory leak in ReActAgent +docs(readme): update installation instructions +refactor(formatter): simplify message formatting logic +test(models): add unit tests for OpenAI integration +``` + +### 3. 代码开发指南 + +#### a. 代码格式化 + +在提交代码之前，必须运行格式化命令以确保代码质量和一致性： + +**运行格式化工具：** + +```bash +npm run format +``` + +此命令将自动运行： + +- **Prettier**：格式化代码风格 +- **ESLint**：检查并修复代码质量问题 + +请确保在提交更改前运行此命令，以保证所有代码符合项目的风格规范。 + +#### b. 目录结构 + +在添加或修改文件时，请遵循以下目录结构： + +``` +packages/ + client/src/ + assets/ # 静态资源，如图片和图标 + components/ # 前端 UI 的 React 组件 + context/ # 用于状态管理和数据获取的 React Context 提供者 + i18n/ # 国际化文件 + pages/ # 不同路由的页面组件 + utils/ # 工具函数和辅助功能 + ... + server/src/ + dao/ # 数据访问对象，用于数据库交互 + migrations/ # 数据库迁移脚本 + models/ # 数据库模型 + otel/ # OpenTelemetry 追踪设置 + trpc/ # tRPC API 路由处理器 + utils/ # 工具函数和辅助功能 + database.ts # 数据库连接设置 + index.ts # 服务器入口点 + ... +``` + +#### c. 前端开发指南 + +在为前端（React/TypeScript）做贡献时，请遵循以下架构原则： + +**关注点分离：** + +**通信和状态管理**逻辑与 **UI 组件**分离。具体来说，数据获取和状态管理应由位于 `packages/client/src/context/` 的 context 提供者处理，使 UI 组件专注于渲染和用户交互。 + +**使用 Tailwind CSS 进行样式设计：** + +- 所有样式必须使用 **Tailwind CSS** 工具类 +- 避免使用内联样式或单独的 CSS 文件进行组件特定的样式设计 + +```tsx +// ✅ 推荐：使用 Tailwind 类 +
+

标题

+ +
+ +// ❌ 不推荐：内联样式 +
...
+``` + +#### d. 文档 + +- 为新功能更新相关文档 +- 如果你的更改影响面向用户的功能，请更新 README.md + +## 该做和不该做的事 + +### ✅ 该做： + +- **从小做起**：从小型、可管理的贡献开始 +- **及早沟通**：在实施重大更改之前先讨论 +- **编写测试**：确保你的代码经过充分测试 +- **为代码编写文档**：帮助他人理解你的贡献 +- **遵循提交规范**：使用规范化的提交信息 +- **保持尊重**：遵循我们的行为准则 +- **提出问题**：如果对某些事情不确定，尽管提问！ + +### ❌ 不该做： + +- **不要突然提交大型 Pull Request**：大型的、意外的 PR 难以审查，可能与项目目标不符。重大更改请务必先开启 issue 讨论 +- **不要忽略 CI 失败**：修复持续集成标记的任何问题 +- **不要混杂关注点**：保持 PR 专注于单一功能或修复 +- **不要忘记更新测试**：功能的更改应该在测试中体现 +- **不要破坏现有 API**：尽可能保持向后兼容性，或明确记录破坏性更改 +- **不要添加不必要的依赖**：保持核心库的轻量级 + +## 获取帮助 + +如果需要帮助或有疑问： + +- 💬 开启 [Discussion](https://github.com/agentscope-ai/agentscope-studio/discussions) +- 🐛 通过 [Issues](https://github.com/agentscope-ai/agentscope-studio/issues) 报告 bug +- 📧 通过钉钉或 Discord 联系维护者（链接见 README.md） + +--- + +感谢为 AgentScope-Studio 做出贡献！你的努力帮助我们为整个社区打造更好的工具。🚀 diff --git a/docs/tutorial/zh_CN/tutorial/overview.md b/docs/tutorial/zh_CN/tutorial/overview.md new file mode 100644 index 00000000..9617505c --- /dev/null +++ b/docs/tutorial/zh_CN/tutorial/overview.md @@ -0,0 +1,37 @@ +# 概览 + +## _什么是 AgentScope-Studio？_ + +AgentScope-Studio 是一个专为 [AgentScope ](https://github.com/agentscope-ai/agentscope) 开发服务的，**本地部署**的可视化开发组件。 +我们希望它可以帮助开发者以一种**透明**、**简单**且**有趣**的方式来开发、调试和评测基于 AgentScope 搭建的智能体应用。 + +## _为什么选择 AgentScope-Studio？_ + +AgentScope-Studio 提供： + +- 项目管理功能和 Chatbot 风格的可视化 +- 基于 OpenTelemetry 的追踪可视化 +- 面向评估的分析和可视化 +- 内置智能体（AgentScope-Friday）用于快速二次开发 + +## _AgentScope-Studio 是如何工作的？_ + +AgentScope-Studio 构建于： + +- 前端：Typescript、React、Vite、TailwindCSS +- 通信：基于 HTTP 的 TRPC、WebSocket +- 后端：Node.js、Express +- 数据库：TypeORM with SQLite + +> 💡 **提示**：我们目前正在将代码风格迁移到 TailwindCSS。 + +AgentScope-Studio 作为 `@agentscope/studio` 包发布在 NPM 上，采用 Apache-2.0 许可证。 + +## _如何贡献？_ + +AgentScope-Studio 是一个开源项目，我们欢迎来自社区的贡献。请参阅我们的[贡献指南](./contributing)了解更多关于如何参与的详细信息。 + +## _顺便说一句_ + +也许我们不是专业的前端 & 后端开发人员，但我们致力于为使用 AgentScope 的开发者打造最透明、最简单、最有趣的用户体验。 +非常感谢任何建议和贡献！ diff --git a/docs/tutorial/zh_CN/tutorial/quick_start.md b/docs/tutorial/zh_CN/tutorial/quick_start.md new file mode 100644 index 00000000..69f91195 --- /dev/null +++ b/docs/tutorial/zh_CN/tutorial/quick_start.md @@ -0,0 +1,63 @@ +# 快速开始 + +## 前置要求 + +- Node.js >= 20.0.0 +- npm >= 10.0.0 + +> 💡 **提示**：如果你使用 nvm，可以运行 nvm use 自动切换到所需的 Node.js 版本。 + +如何检查 Node.js 版本： + +```bash +node --version +npm --version +``` + +## 安装 + +### 从 NPM 安装 + +```bash +npm install -g @agentscope/studio + +# 然后运行以下命令启动 AgentScope-Studio： +as_studio +``` + +### 从源码安装 + +```bash +git clone https://github.com/agentscope-ai/agentscope-studio +cd agentscope-studio +npm install + +# 然后运行以下命令启动 AgentScope-Studio： +npm run dev +``` + +## 连接到 AgentScope-Studio + +在 AgentScope 项目中，在 `init` 函数中设置 `studio_url` 字段，如下所示： + +```python +import agentscope + +agentscope.init( + ... + # 替换为你启动 AgentScope-Studio 的端口 + studio_url="http://localhost:3000", +) +``` + +## 配置 + +要配置 AgentScope-Studio 设置，可以在启动 AgentScope-Studio 的位置创建一个 `.env` 文件。 +以下是一些常用的配置选项： + +> 💡 **提示**：我们正在添加更多配置选项。敬请期待！ + +```env +PORT=3000 +GRPC_PORT=4317 +``` diff --git a/eslint.config.mjs b/eslint.config.mjs index 2ef4d809..23b919bf 100644 --- a/eslint.config.mjs +++ b/eslint.config.mjs @@ -33,6 +33,7 @@ export default tseslint.config( '.git/**', '.vscode/**', '.idea/**', + '**/cache/**', ], }, eslint.configs.recommended, diff --git a/package-lock.json b/package-lock.json index b990b870..33b2a4b3 100644 --- a/package-lock.json +++ b/package-lock.json @@ -42,7 +42,8 @@ "eslint": "^9.25.0", "prettier": "^3.5.3", "typescript": "^5.8.3", - "typescript-eslint": "^8.30.1" + "typescript-eslint": "^8.30.1", + "vitepress": "^2.0.0-alpha.13" }, "engines": { "node": ">=20.0.0", @@ -500,6 +501,23 @@ "@jridgewell/sourcemap-codec": "^1.4.10" } }, + "node_modules/@docsearch/css": { + "version": "4.3.2", + "resolved": "https://registry.npmjs.org/@docsearch/css/-/css-4.3.2.tgz", + "integrity": "sha512-K3Yhay9MgkBjJJ0WEL5MxnACModX9xuNt3UlQQkDEDZJZ0+aeWKtOkxHNndMRkMBnHdYvQjxkm6mdlneOtU1IQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/@docsearch/js": { + "version": "4.3.2", + "resolved": "https://registry.npmjs.org/@docsearch/js/-/js-4.3.2.tgz", + "integrity": "sha512-xdfpPXMgKRY9EW7U1vtY7gLKbLZFa9ed+t0Dacquq8zXBqAlH9HlUf0h4Mhxm0xatsVeMaIR2wr/u6g0GsZyQw==", + "dev": true, + "license": "MIT", + "dependencies": { + "htm": "3.1.1" + } + }, "node_modules/@emotion/hash": { "version": "0.8.0", "resolved": "https://registry.npmjs.org/@emotion/hash/-/hash-0.8.0.tgz", @@ -1263,6 +1281,23 @@ "url": "https://github.com/sponsors/nzakas" } }, + "node_modules/@iconify-json/simple-icons": { + "version": "1.2.59", + "resolved": "https://registry.npmjs.org/@iconify-json/simple-icons/-/simple-icons-1.2.59.tgz", + "integrity": "sha512-fYx/InyQsWFW4wVxWka3CGDJ6m/fXoTqWBSl+oA3FBXO5RhPAb6S3Y5bRgCPnrYevErH8VjAL0TZevIqlN2PhQ==", + "dev": true, + "license": "CC0-1.0", + "dependencies": { + "@iconify/types": "*" + } + }, + "node_modules/@iconify/types": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/@iconify/types/-/types-2.0.0.tgz", + "integrity": "sha512-+wluvCrRhXrhyOmRDJ3q8mux9JkKy5SJ/v8ol2tu4FVjyYvtEzkc/3pK15ET6RKg4b4w4BmTk1+gsCUhf21Ykg==", + "dev": true, + "license": "MIT" + }, "node_modules/@isaacs/cliui": { "version": "8.0.2", "resolved": "https://registry.npmjs.org/@isaacs/cliui/-/cliui-8.0.2.tgz", @@ -3204,6 +3239,91 @@ "win32" ] }, + "node_modules/@shikijs/core": { + "version": "3.15.0", + "resolved": "https://registry.npmjs.org/@shikijs/core/-/core-3.15.0.tgz", + "integrity": "sha512-8TOG6yG557q+fMsSVa8nkEDOZNTSxjbbR8l6lF2gyr6Np+jrPlslqDxQkN6rMXCECQ3isNPZAGszAfYoJOPGlg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/types": "3.15.0", + "@shikijs/vscode-textmate": "^10.0.2", + "@types/hast": "^3.0.4", + "hast-util-to-html": "^9.0.5" + } + }, + "node_modules/@shikijs/engine-javascript": { + "version": "3.15.0", + "resolved": "https://registry.npmjs.org/@shikijs/engine-javascript/-/engine-javascript-3.15.0.tgz", + "integrity": "sha512-ZedbOFpopibdLmvTz2sJPJgns8Xvyabe2QbmqMTz07kt1pTzfEvKZc5IqPVO/XFiEbbNyaOpjPBkkr1vlwS+qg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/types": "3.15.0", + "@shikijs/vscode-textmate": "^10.0.2", + "oniguruma-to-es": "^4.3.3" + } + }, + "node_modules/@shikijs/engine-oniguruma": { + "version": "3.15.0", + "resolved": "https://registry.npmjs.org/@shikijs/engine-oniguruma/-/engine-oniguruma-3.15.0.tgz", + "integrity": "sha512-HnqFsV11skAHvOArMZdLBZZApRSYS4LSztk2K3016Y9VCyZISnlYUYsL2hzlS7tPqKHvNqmI5JSUJZprXloMvA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/types": "3.15.0", + "@shikijs/vscode-textmate": "^10.0.2" + } + }, + "node_modules/@shikijs/langs": { + "version": "3.15.0", + "resolved": "https://registry.npmjs.org/@shikijs/langs/-/langs-3.15.0.tgz", + "integrity": "sha512-WpRvEFvkVvO65uKYW4Rzxs+IG0gToyM8SARQMtGGsH4GDMNZrr60qdggXrFOsdfOVssG/QQGEl3FnJ3EZ+8w8A==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/types": "3.15.0" + } + }, + "node_modules/@shikijs/themes": { + "version": "3.15.0", + "resolved": "https://registry.npmjs.org/@shikijs/themes/-/themes-3.15.0.tgz", + "integrity": "sha512-8ow2zWb1IDvCKjYb0KiLNrK4offFdkfNVPXb1OZykpLCzRU6j+efkY+Y7VQjNlNFXonSw+4AOdGYtmqykDbRiQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/types": "3.15.0" + } + }, + "node_modules/@shikijs/transformers": { + "version": "3.15.0", + "resolved": "https://registry.npmjs.org/@shikijs/transformers/-/transformers-3.15.0.tgz", + "integrity": "sha512-Hmwip5ovvSkg+Kc41JTvSHHVfCYF+C8Cp1omb5AJj4Xvd+y9IXz2rKJwmFRGsuN0vpHxywcXJ1+Y4B9S7EG1/A==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/core": "3.15.0", + "@shikijs/types": "3.15.0" + } + }, + "node_modules/@shikijs/types": { + "version": "3.15.0", + "resolved": "https://registry.npmjs.org/@shikijs/types/-/types-3.15.0.tgz", + "integrity": "sha512-BnP+y/EQnhihgHy4oIAN+6FFtmfTekwOLsQbRw9hOKwqgNy8Bdsjq8B05oAt/ZgvIWWFrshV71ytOrlPfYjIJw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/vscode-textmate": "^10.0.2", + "@types/hast": "^3.0.4" + } + }, + "node_modules/@shikijs/vscode-textmate": { + "version": "10.0.2", + "resolved": "https://registry.npmjs.org/@shikijs/vscode-textmate/-/vscode-textmate-10.0.2.tgz", + "integrity": "sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg==", + "dev": true, + "license": "MIT" + }, "node_modules/@socket.io/component-emitter": { "version": "3.1.2", "resolved": "https://registry.npmjs.org/@socket.io/component-emitter/-/component-emitter-3.1.2.tgz", @@ -4061,6 +4181,24 @@ "dev": true, "license": "MIT" }, + "node_modules/@types/linkify-it": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/@types/linkify-it/-/linkify-it-5.0.0.tgz", + "integrity": "sha512-sVDA58zAw4eWAffKOaQH5/5j3XeayukzDk+ewSsnv3p4yJEZHCCzMDiZM8e0OUrRvmpGZ85jf4yDHkHsgBNr9Q==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/markdown-it": { + "version": "14.1.2", + "resolved": "https://registry.npmjs.org/@types/markdown-it/-/markdown-it-14.1.2.tgz", + "integrity": "sha512-promo4eFwuiW+TfGxhi+0x3czqTYJkG8qB17ZUJiVF10Xm7NLVRSLUsfRTU/6h1e24VvRnXCx+hG7li58lkzog==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/linkify-it": "^5", + "@types/mdurl": "^2" + } + }, "node_modules/@types/mdast": { "version": "4.0.4", "resolved": "https://registry.npmjs.org/@types/mdast/-/mdast-4.0.4.tgz", @@ -4070,6 +4208,13 @@ "@types/unist": "*" } }, + "node_modules/@types/mdurl": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/@types/mdurl/-/mdurl-2.0.0.tgz", + "integrity": "sha512-RGdgjQUZba5p6QEFAVx2OGb8rQDL/cPRG7GiedRzMcJ1tYnUANBncjbSB1NRGwbvjcPeikRABz2nshyPk1bhWg==", + "dev": true, + "license": "MIT" + }, "node_modules/@types/mime": { "version": "1.3.5", "resolved": "https://registry.npmjs.org/@types/mime/-/mime-1.3.5.tgz", @@ -4201,6 +4346,13 @@ "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", "license": "MIT" }, + "node_modules/@types/web-bluetooth": { + "version": "0.0.21", + "resolved": "https://registry.npmjs.org/@types/web-bluetooth/-/web-bluetooth-0.0.21.tgz", + "integrity": "sha512-oIQLCGWtcFZy2JW77j9k8nHzAOpqMHLQejDA48XXMWH6tjCQHz5RCFz1bzsmROyL6PUm+LLnUiI4BCn221inxA==", + "dev": true, + "license": "MIT" + }, "node_modules/@types/ws": { "version": "8.18.1", "resolved": "https://registry.npmjs.org/@types/ws/-/ws-8.18.1.tgz", @@ -4496,6 +4648,296 @@ "vite": "^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0" } }, + "node_modules/@vitejs/plugin-vue": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/@vitejs/plugin-vue/-/plugin-vue-6.0.1.tgz", + "integrity": "sha512-+MaE752hU0wfPFJEUAIxqw18+20euHHdxVtMvbFcOEpjEyfqXH/5DCoTHiVJ0J29EhTJdoTkjEv5YBKU9dnoTw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@rolldown/pluginutils": "1.0.0-beta.29" + }, + "engines": { + "node": "^20.19.0 || >=22.12.0" + }, + "peerDependencies": { + "vite": "^5.0.0 || ^6.0.0 || ^7.0.0", + "vue": "^3.2.25" + } + }, + "node_modules/@vitejs/plugin-vue/node_modules/@rolldown/pluginutils": { + "version": "1.0.0-beta.29", + "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-beta.29.tgz", + "integrity": "sha512-NIJgOsMjbxAXvoGq/X0gD7VPMQ8j9g0BiDaNjVNVjvl+iKXxL3Jre0v31RmBYeLEmkbj2s02v8vFTbUXi5XS2Q==", + "dev": true, + "license": "MIT" + }, + "node_modules/@vue/compiler-core": { + "version": "3.5.24", + "resolved": "https://registry.npmjs.org/@vue/compiler-core/-/compiler-core-3.5.24.tgz", + "integrity": "sha512-eDl5H57AOpNakGNAkFDH+y7kTqrQpJkZFXhWZQGyx/5Wh7B1uQYvcWkvZi11BDhscPgj8N7XV3oRwiPnx1Vrig==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/parser": "^7.28.5", + "@vue/shared": "3.5.24", + "entities": "^4.5.0", + "estree-walker": "^2.0.2", + "source-map-js": "^1.2.1" + } + }, + "node_modules/@vue/compiler-core/node_modules/entities": { + "version": "4.5.0", + "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz", + "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==", + "dev": true, + "license": "BSD-2-Clause", + "engines": { + "node": ">=0.12" + }, + "funding": { + "url": "https://github.com/fb55/entities?sponsor=1" + } + }, + "node_modules/@vue/compiler-dom": { + "version": "3.5.24", + "resolved": "https://registry.npmjs.org/@vue/compiler-dom/-/compiler-dom-3.5.24.tgz", + "integrity": "sha512-1QHGAvs53gXkWdd3ZMGYuvQFXHW4ksKWPG8HP8/2BscrbZ0brw183q2oNWjMrSWImYLHxHrx1ItBQr50I/q2zw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@vue/compiler-core": "3.5.24", + "@vue/shared": "3.5.24" + } + }, + "node_modules/@vue/compiler-sfc": { + "version": "3.5.24", + "resolved": "https://registry.npmjs.org/@vue/compiler-sfc/-/compiler-sfc-3.5.24.tgz", + "integrity": "sha512-8EG5YPRgmTB+YxYBM3VXy8zHD9SWHUJLIGPhDovo3Z8VOgvP+O7UP5vl0J4BBPWYD9vxtBabzW1EuEZ+Cqs14g==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/parser": "^7.28.5", + "@vue/compiler-core": "3.5.24", + "@vue/compiler-dom": "3.5.24", + "@vue/compiler-ssr": "3.5.24", + "@vue/shared": "3.5.24", + "estree-walker": "^2.0.2", + "magic-string": "^0.30.21", + "postcss": "^8.5.6", + "source-map-js": "^1.2.1" + } + }, + "node_modules/@vue/compiler-ssr": { + "version": "3.5.24", + "resolved": "https://registry.npmjs.org/@vue/compiler-ssr/-/compiler-ssr-3.5.24.tgz", + "integrity": "sha512-trOvMWNBMQ/odMRHW7Ae1CdfYx+7MuiQu62Jtu36gMLXcaoqKvAyh+P73sYG9ll+6jLB6QPovqoKGGZROzkFFg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@vue/compiler-dom": "3.5.24", + "@vue/shared": "3.5.24" + } + }, + "node_modules/@vue/devtools-api": { + "version": "8.0.5", + "resolved": "https://registry.npmjs.org/@vue/devtools-api/-/devtools-api-8.0.5.tgz", + "integrity": "sha512-DgVcW8H/Nral7LgZEecYFFYXnAvGuN9C3L3DtWekAncFBedBczpNW8iHKExfaM559Zm8wQWrwtYZ9lXthEHtDw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@vue/devtools-kit": "^8.0.5" + } + }, + "node_modules/@vue/devtools-kit": { + "version": "8.0.5", + "resolved": "https://registry.npmjs.org/@vue/devtools-kit/-/devtools-kit-8.0.5.tgz", + "integrity": "sha512-q2VV6x1U3KJMTQPUlRMyWEKVbcHuxhqJdSr6Jtjz5uAThAIrfJ6WVZdGZm5cuO63ZnSUz0RCsVwiUUb0mDV0Yg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@vue/devtools-shared": "^8.0.5", + "birpc": "^2.6.1", + "hookable": "^5.5.3", + "mitt": "^3.0.1", + "perfect-debounce": "^2.0.0", + "speakingurl": "^14.0.1", + "superjson": "^2.2.2" + } + }, + "node_modules/@vue/devtools-shared": { + "version": "8.0.5", + "resolved": "https://registry.npmjs.org/@vue/devtools-shared/-/devtools-shared-8.0.5.tgz", + "integrity": "sha512-bRLn6/spxpmgLk+iwOrR29KrYnJjG9DGpHGkDFG82UM21ZpJ39ztUT9OXX3g+usW7/b2z+h46I9ZiYyB07XMXg==", + "dev": true, + "license": "MIT", + "dependencies": { + "rfdc": "^1.4.1" + } + }, + "node_modules/@vue/reactivity": { + "version": "3.5.24", + "resolved": "https://registry.npmjs.org/@vue/reactivity/-/reactivity-3.5.24.tgz", + "integrity": "sha512-BM8kBhtlkkbnyl4q+HiF5R5BL0ycDPfihowulm02q3WYp2vxgPcJuZO866qa/0u3idbMntKEtVNuAUp5bw4teg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@vue/shared": "3.5.24" + } + }, + "node_modules/@vue/runtime-core": { + "version": "3.5.24", + "resolved": "https://registry.npmjs.org/@vue/runtime-core/-/runtime-core-3.5.24.tgz", + "integrity": "sha512-RYP/byyKDgNIqfX/gNb2PB55dJmM97jc9wyF3jK7QUInYKypK2exmZMNwnjueWwGceEkP6NChd3D2ZVEp9undQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@vue/reactivity": "3.5.24", + "@vue/shared": "3.5.24" + } + }, + "node_modules/@vue/runtime-dom": { + "version": "3.5.24", + "resolved": "https://registry.npmjs.org/@vue/runtime-dom/-/runtime-dom-3.5.24.tgz", + "integrity": "sha512-Z8ANhr/i0XIluonHVjbUkjvn+CyrxbXRIxR7wn7+X7xlcb7dJsfITZbkVOeJZdP8VZwfrWRsWdShH6pngMxRjw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@vue/reactivity": "3.5.24", + "@vue/runtime-core": "3.5.24", + "@vue/shared": "3.5.24", + "csstype": "^3.1.3" + } + }, + "node_modules/@vue/server-renderer": { + "version": "3.5.24", + "resolved": "https://registry.npmjs.org/@vue/server-renderer/-/server-renderer-3.5.24.tgz", + "integrity": "sha512-Yh2j2Y4G/0/4z/xJ1Bad4mxaAk++C2v4kaa8oSYTMJBJ00/ndPuxCnWeot0/7/qafQFLh5pr6xeV6SdMcE/G1w==", + "dev": true, + "license": "MIT", + "dependencies": { + "@vue/compiler-ssr": "3.5.24", + "@vue/shared": "3.5.24" + }, + "peerDependencies": { + "vue": "3.5.24" + } + }, + "node_modules/@vue/shared": { + "version": "3.5.24", + "resolved": "https://registry.npmjs.org/@vue/shared/-/shared-3.5.24.tgz", + "integrity": "sha512-9cwHL2EsJBdi8NY22pngYYWzkTDhld6fAD6jlaeloNGciNSJL6bLpbxVgXl96X00Jtc6YWQv96YA/0sxex/k1A==", + "dev": true, + "license": "MIT" + }, + "node_modules/@vueuse/core": { + "version": "14.0.0", + "resolved": "https://registry.npmjs.org/@vueuse/core/-/core-14.0.0.tgz", + "integrity": "sha512-d6tKRWkZE8IQElX2aHBxXOMD478fHIYV+Dzm2y9Ag122ICBpNKtGICiXKOhWU3L1kKdttDD9dCMS4bGP3jhCTQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/web-bluetooth": "^0.0.21", + "@vueuse/metadata": "14.0.0", + "@vueuse/shared": "14.0.0" + }, + "funding": { + "url": "https://github.com/sponsors/antfu" + }, + "peerDependencies": { + "vue": "^3.5.0" + } + }, + "node_modules/@vueuse/integrations": { + "version": "14.0.0", + "resolved": "https://registry.npmjs.org/@vueuse/integrations/-/integrations-14.0.0.tgz", + "integrity": "sha512-5A0X7q9qyLtM3xyghq5nK/NEESf7cpcZlkQgXTMuW4JWiAMYxc1ImdhhGrk4negFBsq3ejvAlRmLdNrkcTzk1Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "@vueuse/core": "14.0.0", + "@vueuse/shared": "14.0.0" + }, + "funding": { + "url": "https://github.com/sponsors/antfu" + }, + "peerDependencies": { + "async-validator": "^4", + "axios": "^1", + "change-case": "^5", + "drauu": "^0.4", + "focus-trap": "^7", + "fuse.js": "^7", + "idb-keyval": "^6", + "jwt-decode": "^4", + "nprogress": "^0.2", + "qrcode": "^1.5", + "sortablejs": "^1", + "universal-cookie": "^7 || ^8", + "vue": "^3.5.0" + }, + "peerDependenciesMeta": { + "async-validator": { + "optional": true + }, + "axios": { + "optional": true + }, + "change-case": { + "optional": true + }, + "drauu": { + "optional": true + }, + "focus-trap": { + "optional": true + }, + "fuse.js": { + "optional": true + }, + "idb-keyval": { + "optional": true + }, + "jwt-decode": { + "optional": true + }, + "nprogress": { + "optional": true + }, + "qrcode": { + "optional": true + }, + "sortablejs": { + "optional": true + }, + "universal-cookie": { + "optional": true + } + } + }, + "node_modules/@vueuse/metadata": { + "version": "14.0.0", + "resolved": "https://registry.npmjs.org/@vueuse/metadata/-/metadata-14.0.0.tgz", + "integrity": "sha512-6yoGqbJcMldVCevkFiHDBTB1V5Hq+G/haPlGIuaFZHpXC0HADB0EN1ryQAAceiW+ryS3niUwvdFbGiqHqBrfVA==", + "dev": true, + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/antfu" + } + }, + "node_modules/@vueuse/shared": { + "version": "14.0.0", + "resolved": "https://registry.npmjs.org/@vueuse/shared/-/shared-14.0.0.tgz", + "integrity": "sha512-mTCA0uczBgurRlwVaQHfG0Ja7UdGe4g9mwffiJmvLiTtp1G4AQyIjej6si/k8c8pUwTfVpNufck+23gXptPAkw==", + "dev": true, + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/antfu" + }, + "peerDependencies": { + "vue": "^3.5.0" + } + }, "node_modules/abbrev": { "version": "1.1.1", "resolved": "https://registry.npmjs.org/abbrev/-/abbrev-1.1.1.tgz", @@ -5120,6 +5562,16 @@ "file-uri-to-path": "1.0.0" } }, + "node_modules/birpc": { + "version": "2.8.0", + "resolved": "https://registry.npmjs.org/birpc/-/birpc-2.8.0.tgz", + "integrity": "sha512-Bz2a4qD/5GRhiHSwj30c/8kC8QGj12nNDwz3D4ErQ4Xhy35dsSDvF+RA/tWpjyU0pdGtSDiEk6B5fBGE1qNVhw==", + "dev": true, + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/antfu" + } + }, "node_modules/bl": { "version": "4.1.0", "resolved": "https://registry.npmjs.org/bl/-/bl-4.1.0.tgz", @@ -5758,6 +6210,22 @@ "node": ">=6.6.0" } }, + "node_modules/copy-anything": { + "version": "4.0.5", + "resolved": "https://registry.npmjs.org/copy-anything/-/copy-anything-4.0.5.tgz", + "integrity": "sha512-7Vv6asjS4gMOuILabD3l739tsaxFQmC+a7pLZm02zyvs8p977bL3zEgq3yDk5rn9B0PbYgIv++jmHcuUab4RhA==", + "dev": true, + "license": "MIT", + "dependencies": { + "is-what": "^5.2.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/mesqueeb" + } + }, "node_modules/copy-to-clipboard": { "version": "3.3.3", "resolved": "https://registry.npmjs.org/copy-to-clipboard/-/copy-to-clipboard-3.3.3.tgz", @@ -7371,6 +7839,16 @@ "dev": true, "license": "ISC" }, + "node_modules/focus-trap": { + "version": "7.6.6", + "resolved": "https://registry.npmjs.org/focus-trap/-/focus-trap-7.6.6.tgz", + "integrity": "sha512-v/Z8bvMCajtx4mEXmOo7QEsIzlIOqRXTIwgUfsFOF9gEsespdbD0AkPIka1bSXZ8Y8oZ+2IVDQZePkTfEHZl7Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "tabbable": "^6.3.0" + } + }, "node_modules/for-each": { "version": "0.3.5", "resolved": "https://registry.npmjs.org/for-each/-/for-each-0.3.5.tgz", @@ -7961,6 +8439,30 @@ "url": "https://opencollective.com/unified" } }, + "node_modules/hast-util-to-html": { + "version": "9.0.5", + "resolved": "https://registry.npmjs.org/hast-util-to-html/-/hast-util-to-html-9.0.5.tgz", + "integrity": "sha512-OguPdidb+fbHQSU4Q4ZiLKnzWo8Wwsf5bZfbvu7//a9oTYoqD/fWpe96NuHkoS9h0ccGOTe0C4NGXdtS0iObOw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "@types/unist": "^3.0.0", + "ccount": "^2.0.0", + "comma-separated-tokens": "^2.0.0", + "hast-util-whitespace": "^3.0.0", + "html-void-elements": "^3.0.0", + "mdast-util-to-hast": "^13.0.0", + "property-information": "^7.0.0", + "space-separated-tokens": "^2.0.0", + "stringify-entities": "^4.0.0", + "zwitch": "^2.0.4" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, "node_modules/hast-util-to-jsx-runtime": { "version": "2.3.6", "resolved": "https://registry.npmjs.org/hast-util-to-jsx-runtime/-/hast-util-to-jsx-runtime-2.3.6.tgz", @@ -8110,6 +8612,20 @@ "integrity": "sha512-PDEfEF102G23vHmPhLyPboFCD+BkMGu+GuJe2d9/eH4FsCwvgBpnc9n0pGE+ffKdph38s6foEZiEjdgHdzp+IA==", "license": "CC0-1.0" }, + "node_modules/hookable": { + "version": "5.5.3", + "resolved": "https://registry.npmjs.org/hookable/-/hookable-5.5.3.tgz", + "integrity": "sha512-Yc+BQe8SvoXH1643Qez1zqLRmbA5rCL+sSmk6TVos0LWVfNIB7PGncdlId77WzLGSIB5KaWgTaNTs2lNVEI6VQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/htm": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/htm/-/htm-3.1.1.tgz", + "integrity": "sha512-983Vyg8NwUE7JkZ6NmOqpCZ+sh1bKv2iYTlUkzlWmA5JD2acKoxd4KVxbMmxX/85mtfdnDmTFoNKcg5DGAvxNQ==", + "dev": true, + "license": "Apache-2.0" + }, "node_modules/html-parse-stringify": { "version": "3.0.1", "resolved": "https://registry.npmjs.org/html-parse-stringify/-/html-parse-stringify-3.0.1.tgz", @@ -8904,6 +9420,19 @@ "url": "https://github.com/sponsors/ljharb" } }, + "node_modules/is-what": { + "version": "5.5.0", + "resolved": "https://registry.npmjs.org/is-what/-/is-what-5.5.0.tgz", + "integrity": "sha512-oG7cgbmg5kLYae2N5IVd3jm2s+vldjxJzK1pcu9LfpGuQ93MQSzo0okvRna+7y5ifrD+20FE8FvjusyGaz14fw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/mesqueeb" + } + }, "node_modules/isarray": { "version": "2.0.5", "resolved": "https://registry.npmjs.org/isarray/-/isarray-2.0.5.tgz", @@ -9218,6 +9747,7 @@ "os": [ "freebsd" ], + "peer": true, "engines": { "node": ">= 12.0.0" }, @@ -9239,6 +9769,7 @@ "os": [ "linux" ], + "peer": true, "engines": { "node": ">= 12.0.0" }, @@ -9260,6 +9791,7 @@ "os": [ "linux" ], + "peer": true, "engines": { "node": ">= 12.0.0" }, @@ -9281,6 +9813,7 @@ "os": [ "linux" ], + "peer": true, "engines": { "node": ">= 12.0.0" }, @@ -9302,6 +9835,7 @@ "os": [ "linux" ], + "peer": true, "engines": { "node": ">= 12.0.0" }, @@ -9323,6 +9857,7 @@ "os": [ "linux" ], + "peer": true, "engines": { "node": ">= 12.0.0" }, @@ -9344,6 +9879,7 @@ "os": [ "win32" ], + "peer": true, "engines": { "node": ">= 12.0.0" }, @@ -9365,6 +9901,7 @@ "os": [ "win32" ], + "peer": true, "engines": { "node": ">= 12.0.0" }, @@ -9599,6 +10136,13 @@ "license": "ISC", "optional": true }, + "node_modules/mark.js": { + "version": "8.11.1", + "resolved": "https://registry.npmjs.org/mark.js/-/mark.js-8.11.1.tgz", + "integrity": "sha512-1I+1qpDt4idfgLQG+BNWmrqku+7/2bi5nLf4YwF8y8zXvmfiTBY3PV3ZibfrjBueCByROpuBjLLFCajqkgYoLQ==", + "dev": true, + "license": "MIT" + }, "node_modules/markdown-table": { "version": "3.0.4", "resolved": "https://registry.npmjs.org/markdown-table/-/markdown-table-3.0.4.tgz", @@ -10668,6 +11212,13 @@ "integrity": "sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A==", "license": "ISC" }, + "node_modules/minisearch": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/minisearch/-/minisearch-7.2.0.tgz", + "integrity": "sha512-dqT2XBYUOZOiC5t2HRnwADjhNS2cecp9u+TJRiJ1Qp/f5qjkeT5APcGPjHw+bz89Ms8Jp+cG4AlE+QZ/QnDglg==", + "dev": true, + "license": "MIT" + }, "node_modules/minizlib": { "version": "2.1.2", "resolved": "https://registry.npmjs.org/minizlib/-/minizlib-2.1.2.tgz", @@ -10687,6 +11238,13 @@ "integrity": "sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A==", "license": "ISC" }, + "node_modules/mitt": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/mitt/-/mitt-3.0.1.tgz", + "integrity": "sha512-vKivATfr97l2/QBCYAkXYDbrIWPM2IIKEl7YPhjCvKlG3kE2gm+uBo6nEXK3M5/Ffh/FLpKExzOQ3JJoJGFKBw==", + "dev": true, + "license": "MIT" + }, "node_modules/mkdirp": { "version": "1.0.4", "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-1.0.4.tgz", @@ -11054,6 +11612,25 @@ "wrappy": "1" } }, + "node_modules/oniguruma-parser": { + "version": "0.12.1", + "resolved": "https://registry.npmjs.org/oniguruma-parser/-/oniguruma-parser-0.12.1.tgz", + "integrity": "sha512-8Unqkvk1RYc6yq2WBYRj4hdnsAxVze8i7iPfQr8e4uSP3tRv0rpZcbGUDvxfQQcdwHt/e9PrMvGCsa8OqG9X3w==", + "dev": true, + "license": "MIT" + }, + "node_modules/oniguruma-to-es": { + "version": "4.3.3", + "resolved": "https://registry.npmjs.org/oniguruma-to-es/-/oniguruma-to-es-4.3.3.tgz", + "integrity": "sha512-rPiZhzC3wXwE59YQMRDodUwwT9FZ9nNBwQQfsd1wfdtlKEyCdRV0avrTcSZ5xlIvGRVPd/cx6ZN45ECmS39xvg==", + "dev": true, + "license": "MIT", + "dependencies": { + "oniguruma-parser": "^0.12.1", + "regex": "^6.0.1", + "regex-recursion": "^6.0.2" + } + }, "node_modules/opener": { "version": "1.5.2", "resolved": "https://registry.npmjs.org/opener/-/opener-1.5.2.tgz", @@ -11318,6 +11895,13 @@ "node": ">=8" } }, + "node_modules/perfect-debounce": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/perfect-debounce/-/perfect-debounce-2.0.0.tgz", + "integrity": "sha512-fkEH/OBiKrqqI/yIgjR92lMfs2K8105zt/VT6+7eTjNwisrsh47CeIED9z58zI7DfKdH3uHAn25ziRZn3kgAow==", + "dev": true, + "license": "MIT" + }, "node_modules/picocolors": { "version": "1.1.1", "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz", @@ -12795,6 +13379,33 @@ "node": ">=6" } }, + "node_modules/regex": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/regex/-/regex-6.0.1.tgz", + "integrity": "sha512-uorlqlzAKjKQZ5P+kTJr3eeJGSVroLKoHmquUj4zHWuR+hEyNqlXsSKlYYF5F4NI6nl7tWCs0apKJ0lmfsXAPA==", + "dev": true, + "license": "MIT", + "dependencies": { + "regex-utilities": "^2.3.0" + } + }, + "node_modules/regex-recursion": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/regex-recursion/-/regex-recursion-6.0.2.tgz", + "integrity": "sha512-0YCaSCq2VRIebiaUviZNs0cBz1kg5kVS2UKUfNIx8YVs1cN3AV7NTctO5FOKBA+UT2BPJIWZauYHPqJODG50cg==", + "dev": true, + "license": "MIT", + "dependencies": { + "regex-utilities": "^2.3.0" + } + }, + "node_modules/regex-utilities": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/regex-utilities/-/regex-utilities-2.3.0.tgz", + "integrity": "sha512-8VhliFJAWRaUiVvREIiW2NXXTmHs4vMNnSzuJVhscgmGav3g9VDxLrQndI3dZZVVdp0ZO/5v0xmX516/7M9cng==", + "dev": true, + "license": "MIT" + }, "node_modules/regexp.prototype.flags": { "version": "1.5.4", "resolved": "https://registry.npmjs.org/regexp.prototype.flags/-/regexp.prototype.flags-1.5.4.tgz", @@ -12970,6 +13581,13 @@ "node": ">=0.10.0" } }, + "node_modules/rfdc": { + "version": "1.4.1", + "resolved": "https://registry.npmjs.org/rfdc/-/rfdc-1.4.1.tgz", + "integrity": "sha512-q1b3N5QkRUWUl7iyylaaj3kOpIT0N2i9MqIEQXP73GVsN9cw3fdx8X63cEmWhJGi2PPCF23Ijp7ktmd39rawIA==", + "dev": true, + "license": "MIT" + }, "node_modules/rimraf": { "version": "3.0.2", "resolved": "https://registry.npmjs.org/rimraf/-/rimraf-3.0.2.tgz", @@ -13351,6 +13969,23 @@ "url": "https://github.com/sponsors/ljharb" } }, + "node_modules/shiki": { + "version": "3.15.0", + "resolved": "https://registry.npmjs.org/shiki/-/shiki-3.15.0.tgz", + "integrity": "sha512-kLdkY6iV3dYbtPwS9KXU7mjfmDm25f5m0IPNFnaXO7TBPcvbUOY72PYXSuSqDzwp+vlH/d7MXpHlKO/x+QoLXw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/core": "3.15.0", + "@shikijs/engine-javascript": "3.15.0", + "@shikijs/engine-oniguruma": "3.15.0", + "@shikijs/langs": "3.15.0", + "@shikijs/themes": "3.15.0", + "@shikijs/types": "3.15.0", + "@shikijs/vscode-textmate": "^10.0.2", + "@types/hast": "^3.0.4" + } + }, "node_modules/side-channel": { "version": "1.1.0", "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.1.0.tgz", @@ -13754,6 +14389,16 @@ "integrity": "sha512-zC8zGoGkmc8J9ndvml8Xksr1Amk9qBujgbF0JAIWO7kXr43w0h/0GJNM/Vustixu+YE8N/MTrQ7N31FvHUACxQ==", "dev": true }, + "node_modules/speakingurl": { + "version": "14.0.1", + "resolved": "https://registry.npmjs.org/speakingurl/-/speakingurl-14.0.1.tgz", + "integrity": "sha512-1POYv7uv2gXoyGFpBCmpDVSNV74IfsWlDW216UPjbWufNf+bSU6GdbDsxdcxtfwb4xlI3yxzOTKClUosxARYrQ==", + "dev": true, + "license": "BSD-3-Clause", + "engines": { + "node": ">=0.10.0" + } + }, "node_modules/sql-highlight": { "version": "6.1.0", "resolved": "https://registry.npmjs.org/sql-highlight/-/sql-highlight-6.1.0.tgz", @@ -14112,6 +14757,19 @@ "integrity": "sha512-yQ3rwFWRfwNUY7H5vpU0wfdkNSnvnJinhF9830Swlaxl03zsOjCfmX0ugac+3LtK0lYSgwL/KXc8oYL3mG4YFQ==", "license": "MIT" }, + "node_modules/superjson": { + "version": "2.2.5", + "resolved": "https://registry.npmjs.org/superjson/-/superjson-2.2.5.tgz", + "integrity": "sha512-zWPTX96LVsA/eVYnqOM2+ofcdPqdS1dAF1LN4TS2/MWuUpfitd9ctTa87wt4xrYnZnkLtS69xpBdSxVBP5Rm6w==", + "dev": true, + "license": "MIT", + "dependencies": { + "copy-anything": "^4" + }, + "engines": { + "node": ">=16" + } + }, "node_modules/supports-color": { "version": "8.1.1", "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-8.1.1.tgz", @@ -14148,6 +14806,13 @@ "dev": true, "license": "MIT" }, + "node_modules/tabbable": { + "version": "6.3.0", + "resolved": "https://registry.npmjs.org/tabbable/-/tabbable-6.3.0.tgz", + "integrity": "sha512-EIHvdY5bPLuWForiR/AN2Bxngzpuwn1is4asboytXtpTgsArc+WmSJKVLlhdh71u7jFcryDqB2A8lQvj78MkyQ==", + "dev": true, + "license": "MIT" + }, "node_modules/tailwind-merge": { "version": "3.4.0", "resolved": "https://registry.npmjs.org/tailwind-merge/-/tailwind-merge-3.4.0.tgz", @@ -15330,6 +15995,158 @@ "url": "https://github.com/sponsors/jonschlinkert" } }, + "node_modules/vitepress": { + "version": "2.0.0-alpha.13", + "resolved": "https://registry.npmjs.org/vitepress/-/vitepress-2.0.0-alpha.13.tgz", + "integrity": "sha512-bnUfnyL3TRqqYvOxQ68MxbFyI6qkQ8IQnhwIiGLSMF9GXloyfBCV1hnVJE6yA+Rlk+T+y19gzDKjKIMpiCIUvA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@docsearch/css": "^4.3.2", + "@docsearch/js": "^4.3.2", + "@iconify-json/simple-icons": "^1.2.58", + "@shikijs/core": "^3.15.0", + "@shikijs/transformers": "^3.15.0", + "@shikijs/types": "^3.15.0", + "@types/markdown-it": "^14.1.2", + "@vitejs/plugin-vue": "^6.0.1", + "@vue/devtools-api": "^8.0.3", + "@vue/shared": "^3.5.24", + "@vueuse/core": "^14.0.0", + "@vueuse/integrations": "^14.0.0", + "focus-trap": "^7.6.6", + "mark.js": "8.11.1", + "minisearch": "^7.2.0", + "shiki": "^3.15.0", + "vite": "^7.2.2", + "vue": "^3.5.24" + }, + "bin": { + "vitepress": "bin/vitepress.js" + }, + "peerDependencies": { + "markdown-it-mathjax3": "^4", + "oxc-minify": "*", + "postcss": "^8" + }, + "peerDependenciesMeta": { + "markdown-it-mathjax3": { + "optional": true + }, + "oxc-minify": { + "optional": true + }, + "postcss": { + "optional": true + } + } + }, + "node_modules/vitepress/node_modules/fdir": { + "version": "6.5.0", + "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz", + "integrity": "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12.0.0" + }, + "peerDependencies": { + "picomatch": "^3 || ^4" + }, + "peerDependenciesMeta": { + "picomatch": { + "optional": true + } + } + }, + "node_modules/vitepress/node_modules/picomatch": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.3.tgz", + "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/jonschlinkert" + } + }, + "node_modules/vitepress/node_modules/vite": { + "version": "7.2.2", + "resolved": "https://registry.npmjs.org/vite/-/vite-7.2.2.tgz", + "integrity": "sha512-BxAKBWmIbrDgrokdGZH1IgkIk/5mMHDreLDmCJ0qpyJaAteP8NvMhkwr/ZCQNqNH97bw/dANTE9PDzqwJghfMQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "esbuild": "^0.25.0", + "fdir": "^6.5.0", + "picomatch": "^4.0.3", + "postcss": "^8.5.6", + "rollup": "^4.43.0", + "tinyglobby": "^0.2.15" + }, + "bin": { + "vite": "bin/vite.js" + }, + "engines": { + "node": "^20.19.0 || >=22.12.0" + }, + "funding": { + "url": "https://github.com/vitejs/vite?sponsor=1" + }, + "optionalDependencies": { + "fsevents": "~2.3.3" + }, + "peerDependencies": { + "@types/node": "^20.19.0 || >=22.12.0", + "jiti": ">=1.21.0", + "less": "^4.0.0", + "lightningcss": "^1.21.0", + "sass": "^1.70.0", + "sass-embedded": "^1.70.0", + "stylus": ">=0.54.8", + "sugarss": "^5.0.0", + "terser": "^5.16.0", + "tsx": "^4.8.1", + "yaml": "^2.4.2" + }, + "peerDependenciesMeta": { + "@types/node": { + "optional": true + }, + "jiti": { + "optional": true + }, + "less": { + "optional": true + }, + "lightningcss": { + "optional": true + }, + "sass": { + "optional": true + }, + "sass-embedded": { + "optional": true + }, + "stylus": { + "optional": true + }, + "sugarss": { + "optional": true + }, + "terser": { + "optional": true + }, + "tsx": { + "optional": true + }, + "yaml": { + "optional": true + } + } + }, "node_modules/void-elements": { "version": "3.1.0", "resolved": "https://registry.npmjs.org/void-elements/-/void-elements-3.1.0.tgz", @@ -15339,6 +16156,28 @@ "node": ">=0.10.0" } }, + "node_modules/vue": { + "version": "3.5.24", + "resolved": "https://registry.npmjs.org/vue/-/vue-3.5.24.tgz", + "integrity": "sha512-uTHDOpVQTMjcGgrqFPSb8iO2m1DUvo+WbGqoXQz8Y1CeBYQ0FXf2z1gLRaBtHjlRz7zZUBHxjVB5VTLzYkvftg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@vue/compiler-dom": "3.5.24", + "@vue/compiler-sfc": "3.5.24", + "@vue/runtime-dom": "3.5.24", + "@vue/server-renderer": "3.5.24", + "@vue/shared": "3.5.24" + }, + "peerDependencies": { + "typescript": "*" + }, + "peerDependenciesMeta": { + "typescript": { + "optional": true + } + } + }, "node_modules/web-namespaces": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/web-namespaces/-/web-namespaces-2.0.1.tgz", diff --git a/package.json b/package.json index 97a52fd2..97d4625a 100644 --- a/package.json +++ b/package.json @@ -29,7 +29,10 @@ "build:server": "npm run build --workspace=packages/server", "build:python": "cp -r packages/app dist/app", "prepublishOnly": "npm run build", - "format": "prettier --write . && eslint . --ext .js,.jsx,.ts,.tsx --fix" + "format": "prettier --write . && eslint . --ext .js,.jsx,.ts,.tsx --fix", + "docs:dev": "vitepress dev docs", + "docs:build": "vitepress build docs", + "docs:preview": "vitepress preview docs" }, "devDependencies": { "@eslint/js": "^9.25.0", @@ -39,7 +42,8 @@ "eslint": "^9.25.0", "prettier": "^3.5.3", "typescript": "^5.8.3", - "typescript-eslint": "^8.30.1" + "typescript-eslint": "^8.30.1", + "vitepress": "^2.0.0-alpha.13" }, "dependencies": { "@grpc/grpc-js": "^1.14.1", diff --git a/packages/server/src/trpc/router.ts b/packages/server/src/trpc/router.ts index 9ca7dc53..69ccdf82 100644 --- a/packages/server/src/trpc/router.ts +++ b/packages/server/src/trpc/router.ts @@ -102,9 +102,10 @@ export const appRouter = t.router({ project: z.string(), name: z.string(), timestamp: z.string(), - run_dir: z.string(), pid: z.number(), status: z.enum(Object.values(Status) as [string, ...string[]]), + // Deprecated + run_dir: z.string().optional().nullable(), }), ) .mutation(async ({ input }) => { @@ -113,7 +114,7 @@ export const appRouter = t.router({ project: input.project, name: input.name, timestamp: input.timestamp, - run_dir: input.run_dir, + run_dir: input.run_dir || '', // Deprecated pid: input.pid, status: input.status, } as RunData; @@ -199,8 +200,8 @@ export const appRouter = t.router({ z.object({ runId: z.string(), replyId: z.string().optional().nullable(), - name: z.string(), - role: z.string(), + replyName: z.string().optional().nullable(), + replyRole: z.string().optional().nullable(), msg: z.object({ id: z.string(), name: z.string(), @@ -209,6 +210,9 @@ export const appRouter = t.router({ metadata: z.unknown(), timestamp: z.string(), }), + // The name and role here are deprecated, use replyName and replyRole instead + name: z.string().optional().nullable(), + role: z.string().optional().nullable(), }), ) .mutation(async ({ input }) => { @@ -230,8 +234,8 @@ export const appRouter = t.router({ await ReplyDao.saveReply({ runId: input.runId, replyId: input.replyId, - replyRole: input.role, - replyName: input.name, + replyRole: input.replyRole ?? input.role, + replyName: input.replyName ?? input.name, createdAt: input.msg.timestamp, } as RegisterReplyParams); }