opencode/yao
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Enhance JSAPI documentation with new methods and properties

Browse source 
- Added new methods to the `ctx.trace` object for improved tracing capabilities, including `EndBlock`, `MessageID`, `BlockID`, and `ThreadID`.
- Expanded the documentation to clarify the purpose of the `ctx.trace` object, detailing its properties and methods for user transparency and developer debugging.
- Updated examples to reflect changes in method usage and added new sections for trace lifecycle and space operations, enhancing overall clarity and guidance for developers.
This commit is contained in:
Max 2025-12-09 19:42:13 +08:00
parent 98d0d749ed
commit ab45ca1dc5
1 changed files with 288 additions and 105 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

393
agent/context/JSAPI.md
View file

@ -56,6 +56,10 @@ The Context provides several methods for sending messages to the client:
| `Merge(message_id, data, path?)` | Merge data into message | - | - | | `Merge(message_id, data, path?)` | Merge data into message | - | - |
| `Set(message_id, data, path)` | Set a field in message | - | - | | `Set(message_id, data, path)` | Set a field in message | - | - |
| `End(message_id, final_content?)` | Finalize streaming message | ✅ Yes | - | | `End(message_id, final_content?)` | Finalize streaming message | ✅ Yes | - |
| `EndBlock(block_id)` | End a message block | - | - |
| `MessageID()` | Generate unique message ID | - | - |
| `BlockID()` | Generate unique block ID | - | - |
| `ThreadID()` | Generate unique thread ID | - | - |
> **Note:** `Append`, `Replace`, `Merge`, and `Set` only work with messages started via `SendStream()`. Messages sent via `Send()` are immediately finalized and cannot be updated. > **Note:** `Append`, `Replace`, `Merge`, and `Set` only work with messages started via `SendStream()`. Messages sent via `Send()` are immediately finalized and cannot be updated.
@ -926,7 +930,36 @@ try {
## Trace API ## Trace API
The `ctx.trace` object provides comprehensive tracing capabilities for debugging and monitoring agent execution. The `ctx.trace` object provides tracing capabilities for:
1. **User Transparency** - Expose the agent's working and thinking process to users. The frontend will render these trace nodes to show users what the agent is doing.
2. **Developer Debugging** - Help developers debug agent execution by recording detailed steps and data.
> **Note:** Trace is primarily designed for developers to expose the agent's process to users. The frontend has corresponding UI components to render these trace nodes.
### Properties
- `ctx.trace.id`: String - The unique identifier of the trace
### Methods Summary
| Method | Description |
| ------------------------- | ------------------------------- |
| `Add(input, option)` | Create a sequential trace node |
| `Parallel(inputs)` | Create parallel trace nodes |
| `Info(message)` | Add info log to current node |
| `Debug(message)` | Add debug log to current node |
| `Warn(message)` | Add warning log to current node |
| `Error(message)` | Add error log to current node |
| `SetOutput(output)` | Set output for current node |
| `SetMetadata(key, value)` | Set metadata for current node |
| `Complete(output?)` | Mark current node as completed |
| `Fail(error)` | Mark current node as failed |
| `MarkComplete()` | Mark entire trace as complete |
| `IsComplete()` | Check if trace is complete |
| `CreateSpace(option)` | Create a visual space container |
| `GetSpace(id)` | Get a trace space by ID |
| `Release()` | Release trace resources |
### Node Operations ### Node Operations
@ -943,11 +976,12 @@ Creates a new trace node (sequential step).
```typescript ```typescript
interface TraceNodeOption { interface TraceNodeOption {
label: string; // Display label label: string; // Display label in UI
type: string; // Node type identifier type?: string; // Node type identifier
icon: string; // Icon identifier icon?: string; // Icon identifier
description: string; // Node description description?: string; // Node description
metadata?: Record<string, any>; // Additional metadata metadata?: Record<string, any>; // Additional metadata
autoCompleteParent?: boolean; // Auto-complete parent node(s) when this node is created (default: true)
} }
``` ```
@ -1009,45 +1043,123 @@ const parallel_nodes = ctx.trace.Parallel([
### Logging Methods ### Logging Methods
Add log entries to the current trace node: Add log entries to the current trace node. Each method takes a single string message and returns the trace object for chaining.
```javascript ```javascript
// Information logs // Information logs
ctx.trace.Info("Processing started", { step: 1 }); ctx.trace.Info("Processing started");
// Debug logs // Debug logs
ctx.trace.Debug("Variable value", { value: 42 }); ctx.trace.Debug("Variable value: 42");
// Warning logs // Warning logs
ctx.trace.Warn("Deprecated feature used", { feature: "old_api" }); ctx.trace.Warn("Deprecated feature used");
// Error logs // Error logs
ctx.trace.Error("Operation failed", { error: "timeout" }); ctx.trace.Error("Operation failed: timeout");
``` ```
### Node Status Operations ### Trace-Level Operations
These methods operate on the current trace node (managed by the trace manager).
#### `ctx.trace.SetOutput(output)`
Sets the output data for the current trace node.
```javascript
ctx.trace.SetOutput({ result: "success", data: [...] });
```
#### `ctx.trace.SetMetadata(key, value)`
Sets metadata for the current trace node.
```javascript
ctx.trace.SetMetadata("duration", 1500);
ctx.trace.SetMetadata("source", "cache");
```
#### `ctx.trace.Complete(output?)`
Marks the current trace node as completed (optionally with output).
```javascript
ctx.trace.Complete({ status: "done" });
```
#### `ctx.trace.Fail(error)`
Marks the current trace node as failed with an error message.
```javascript
ctx.trace.Fail("Connection timeout");
```
### Node Object
The `ctx.trace.Add()` and `ctx.trace.Parallel()` methods return Node objects. Each node has the following properties and methods:
#### Properties
- `id`: String - The unique identifier of the node
#### `node.Add(input, option)`
Creates a child node under this node.
```javascript
const parent_node = ctx.trace.Add({ step: "process" }, { label: "Process" });
const child_node = parent_node.Add(
{ action: "validate" },
{ label: "Validate Input", type: "validation" }
);
```
#### `node.Parallel(inputs)`
Creates multiple parallel child nodes under this node.
```javascript
const parent_node = ctx.trace.Add({ step: "fetch" }, { label: "Fetch Data" });
const child_nodes = parent_node.Parallel([
{ input: { source: "db" }, option: { label: "Database Query" } },
{ input: { source: "api" }, option: { label: "API Call" } },
]);
```
#### `node.Info(message)`, `node.Debug(message)`, `node.Warn(message)`, `node.Error(message)`
Add log entries to the node. All methods return the node for chaining.
```javascript
const search_node = ctx.trace.Add({ query: "search" }, { label: "Search" });
search_node
.Info("Starting search")
.Debug("Query parameters validated")
.Warn("Cache miss, fetching from source");
```
#### `node.SetOutput(output)` #### `node.SetOutput(output)`
Sets the output data for a node. Sets the output data for a node. Returns the node for chaining.
```javascript ```javascript
const search_node = ctx.trace.Add({ query: "search" }, options); const search_node = ctx.trace.Add({ query: "search" }, { label: "Search" });
search_node.SetOutput({ results: [...] }); search_node.SetOutput({ results: [...], count: 10 });
``` ```
#### `node.SetMetadata(key, value)` #### `node.SetMetadata(key, value)`
Sets metadata for a node. Sets metadata for a node. Returns the node for chaining.
```javascript ```javascript
search_node.SetMetadata("duration", 1500); search_node.SetMetadata("duration", 1500).SetMetadata("cache_hit", true);
search_node.SetMetadata("cache_hit", true);
``` ```
#### `node.Complete(output?)` #### `node.Complete(output?)`
Marks a node as completed (optionally with output). Marks a node as completed (optionally with output). Returns the node for chaining.
```javascript ```javascript
search_node.Complete({ status: "success", data: [...] }); search_node.Complete({ status: "success", data: [...] });
@ -1055,99 +1167,91 @@ search_node.Complete({ status: "success", data: [...] });
#### `node.Fail(error)` #### `node.Fail(error)`
Marks a node as failed with an error. Marks a node as failed with an error message. Returns the node for chaining.
```javascript ```javascript
try { try {
// Operation // Operation
} catch (error) { } catch (error) {
search_node.Fail(error); search_node.Fail(error.message);
} }
``` ```
### Query Operations ### Trace Lifecycle
#### `ctx.trace.GetRootNode()` #### `ctx.trace.IsComplete()`
Returns the root node of the trace tree. Checks if the trace is complete.
```javascript ```javascript
const root_node = ctx.trace.GetRootNode(); if (ctx.trace.IsComplete()) {
console.log(root_node.id, root_node.label); console.log("Trace completed");
}
``` ```
#### `ctx.trace.GetNode(id)` #### `ctx.trace.MarkComplete()`
Retrieves a specific node by ID. Marks the entire trace as complete.
```javascript ```javascript
const target_node = ctx.trace.GetNode("node-123"); ctx.trace.MarkComplete();
``` ```
#### `ctx.trace.GetCurrentNodes()` ### Trace Space Operations
Returns the current active nodes (may be multiple if in parallel state). Trace spaces are visual containers for organizing trace nodes in the frontend UI. They help group related operations together for better presentation to users.
```javascript > **Note:** Trace spaces are purely for visual organization and presentation. They do not store data - use `ctx.space` for data storage between hooks.
const current_nodes = ctx.trace.GetCurrentNodes();
```
### Memory Space Operations
#### `ctx.trace.CreateSpace(option)` #### `ctx.trace.CreateSpace(option)`
Creates a memory space for storing key-value data. Creates a visual space container for grouping trace nodes.
**Option Structure:**
```typescript
interface TraceSpaceOption {
label: string; // Display label in UI
type?: string; // Space type identifier
icon?: string; // Icon identifier
description?: string; // Space description
ttl?: number; // Time to live in seconds (for display only)
metadata?: Record<string, any>; // Additional metadata
}
```
**Example:**
```javascript ```javascript
const memory_space = ctx.trace.CreateSpace({ const visual_space = ctx.trace.CreateSpace({
label: "Context Memory", label: "Search Results",
type: "context", type: "search",
icon: "database", icon: "search",
description: "Stores conversation context", description: "Knowledge base search operations",
}); });
``` ```
#### `ctx.trace.GetSpace(id)` #### `ctx.trace.GetSpace(id)`
Retrieves a memory space by ID. Retrieves a trace space by ID.
```javascript ```javascript
const context_space = ctx.trace.GetSpace("context"); const search_space = ctx.trace.GetSpace("search-space-id");
```
#### `ctx.trace.HasSpace(id)`
Checks if a memory space exists.
```javascript
if (ctx.trace.HasSpace("context")) {
// Space exists
}
```
#### `ctx.trace.DeleteSpace(id)`
Deletes a memory space.
```javascript
ctx.trace.DeleteSpace("temp_storage");
```
#### `ctx.trace.ListSpaces()`
Lists all memory spaces.
```javascript
const all_spaces = ctx.trace.ListSpaces();
all_spaces.forEach((space) => {
console.log(space.id, space.label);
});
``` ```
## Space API ## Space API
The `ctx.space` object provides a shared data space for passing data between requests and agent calls. This is useful for storing temporary data that needs to be accessed across different hooks or nested agent calls. The `ctx.space` object provides a shared data space for passing data between requests and agent calls. This is useful for storing temporary data that needs to be accessed across different hooks or nested agent calls.
### Methods Summary
| Method | Description |
| ----------------- | ------------------------------------- |
| `Get(key)` | Get a value from the space |
| `Set(key, value)` | Set a value in the space |
| `Delete(key)` | Delete a key from the space |
| `GetDel(key)` | Get a value and immediately delete it |
### Methods ### Methods
#### `ctx.space.Get(key): any` #### `ctx.space.Get(key): any`
@ -1272,101 +1376,180 @@ function Next(ctx, payload) {
The `ctx.mcp` object provides access to Model Context Protocol operations for interacting with external tools, resources, and prompts. The `ctx.mcp` object provides access to Model Context Protocol operations for interacting with external tools, resources, and prompts.
### Methods Summary
| Method | Description |
| ------------------------------------ | -------------------------------- |
| `ListResources(client, cursor?)` | List available resources |
| `ReadResource(client, uri)` | Read a specific resource |
| `ListTools(client, cursor?)` | List available tools |
| `CallTool(client, name, args?)` | Call a single tool |
| `CallTools(client, tools)` | Call multiple tools sequentially |
| `CallToolsParallel(client, tools)` | Call multiple tools in parallel |
| `ListPrompts(client, cursor?)` | List available prompts |
| `GetPrompt(client, name, args?)` | Get a specific prompt |
| `ListSamples(client, type, name)` | List samples for a tool/resource |
| `GetSample(client, type, name, idx)` | Get a specific sample by index |
### Resource Operations ### Resource Operations
#### `ctx.mcp.ListResources(client)` #### `ctx.mcp.ListResources(client, cursor?)`
Lists available resources from an MCP client. Lists available resources from an MCP client.
**Parameters:**
- `client`: String - MCP client ID
- `cursor`: String (optional) - Pagination cursor
```javascript ```javascript
const fs_resources = ctx.mcp.ListResources("filesystem"); const resources = ctx.mcp.ListResources("echo", "");
console.log(resources.resources); // Array of resources
``` ```
#### `ctx.mcp.ReadResource(client, uri)` #### `ctx.mcp.ReadResource(client, uri)`
Reads a specific resource. Reads a specific resource.
**Parameters:**
- `client`: String - MCP client ID
- `uri`: String - Resource URI
```javascript ```javascript
const file_content = ctx.mcp.ReadResource( const info = ctx.mcp.ReadResource("echo", "echo://info");
"filesystem", console.log(info.contents); // Array of content items
"file:///path/to/file.txt"
);
``` ```
### Tool Operations ### Tool Operations
#### `ctx.mcp.ListTools(client)` #### `ctx.mcp.ListTools(client, cursor?)`
Lists available tools from an MCP client. Lists available tools from an MCP client.
**Parameters:**
- `client`: String - MCP client ID
- `cursor`: String (optional) - Pagination cursor
```javascript ```javascript
const available_tools = ctx.mcp.ListTools("toolkit"); const tools = ctx.mcp.ListTools("echo", "");
console.log(tools.tools); // Array of tools
``` ```
#### `ctx.mcp.CallTool(client, name, args)` #### `ctx.mcp.CallTool(client, name, arguments?)`
Calls a single tool. Calls a single tool.
**Parameters:**
- `client`: String - MCP client ID
- `name`: String - Tool name
- `arguments`: Object (optional) - Tool arguments
```javascript ```javascript
const calc_result = ctx.mcp.CallTool("calculator", "add", { const result = ctx.mcp.CallTool("echo", "ping", { count: 3 });
a: 10, console.log(result.content); // Tool result content
b: 32,
});
``` ```
#### `ctx.mcp.CallTools(client, calls)` #### `ctx.mcp.CallTools(client, tools)`
Calls multiple tools sequentially. Calls multiple tools sequentially.
**Parameters:**
- `client`: String - MCP client ID
- `tools`: Array - Array of tool call objects
```javascript ```javascript
const tool_results = ctx.mcp.CallTools("toolkit", [ const results = ctx.mcp.CallTools("echo", [
{ name: "tool1", args: { param: "value1" } }, { name: "ping", arguments: { count: 1 } },
{ name: "tool2", args: { param: "value2" } }, { name: "status", arguments: { verbose: true } },
]); ]);
console.log(results.results); // Array of results
``` ```
#### `ctx.mcp.CallToolsParallel(client, calls)` #### `ctx.mcp.CallToolsParallel(client, tools)`
Calls multiple tools in parallel. Calls multiple tools in parallel.
**Parameters:**
- `client`: String - MCP client ID
- `tools`: Array - Array of tool call objects
```javascript ```javascript
const parallel_results = ctx.mcp.CallToolsParallel("toolkit", [ const results = ctx.mcp.CallToolsParallel("echo", [
{ name: "api1", args: { endpoint: "/users" } }, { name: "ping", arguments: { count: 1 } },
{ name: "api2", args: { endpoint: "/posts" } }, { name: "status", arguments: { verbose: false } },
]); ]);
console.log(results.results); // Array of results (order may vary)
``` ```
### Prompt Operations ### Prompt Operations
#### `ctx.mcp.ListPrompts(client)` #### `ctx.mcp.ListPrompts(client, cursor?)`
Lists available prompts from an MCP client. Lists available prompts from an MCP client.
**Parameters:**
- `client`: String - MCP client ID
- `cursor`: String (optional) - Pagination cursor
```javascript ```javascript
const available_prompts = ctx.mcp.ListPrompts("prompt_library"); const prompts = ctx.mcp.ListPrompts("echo", "");
console.log(prompts.prompts); // Array of prompts
``` ```
#### `ctx.mcp.GetPrompt(client, name, args?)` #### `ctx.mcp.GetPrompt(client, name, arguments?)`
Retrieves a specific prompt. Retrieves a specific prompt with optional arguments.
**Parameters:**
- `client`: String - MCP client ID
- `name`: String - Prompt name
- `arguments`: Object (optional) - Prompt arguments
```javascript ```javascript
const review_prompt = ctx.mcp.GetPrompt("prompt_library", "code_review", { const prompt = ctx.mcp.GetPrompt("echo", "test_connection", {
language: "javascript", detailed: "true",
}); });
console.log(prompt.messages); // Array of prompt messages
``` ```
### Sample Operations ### Sample Operations
#### `ctx.mcp.CreateSample(client, uri, sample)` #### `ctx.mcp.ListSamples(client, type, name)`
Creates a sample for a resource. Lists available samples for a tool or resource.
**Parameters:**
- `client`: String - MCP client ID
- `type`: String - Sample type ("tool" or "resource")
- `name`: String - Tool or resource name
```javascript ```javascript
ctx.mcp.CreateSample("filesystem", "file:///examples", { const samples = ctx.mcp.ListSamples("echo", "tool", "ping");
name: "example1", console.log(samples.samples); // Array of samples
content: "Sample content", ```
});
#### `ctx.mcp.GetSample(client, type, name, index)`
Gets a specific sample by index.
**Parameters:**
- `client`: String - MCP client ID
- `type`: String - Sample type ("tool" or "resource")
- `name`: String - Tool or resource name
- `index`: Number - Sample index (0-based)
```javascript
const sample = ctx.mcp.GetSample("echo", "tool", "ping", 0);
console.log(sample.name, sample.input); // Sample name and input data
``` ```
## Hooks ## Hooks