feat: docs update

2026-07-20 05:27:59 +08:00 · 2026-02-27 16:03:47 +08:00
parent d891312032
commit 6db22827f2
97 changed files with 2801 additions and 1354 deletions
--- a/docs/en/tools/bash.mdx
+++ b/docs/en/tools/bash.mdx
@@ -0,0 +1,30 @@
+---
+title: bash - Terminal
+description: Execute system commands
+---
+
+# bash
+
+Execute Bash commands in the current working directory, returns stdout and stderr. API keys configured via `env_config` are automatically injected into the environment.
+
+## Dependencies
+
+No extra dependencies, available by default.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `command` | string | Yes | Command to execute |
+| `timeout` | integer | No | Timeout in seconds |
+
+## Use Cases
+
+- Install packages and dependencies
+- Run code and tests
+- Deploy applications and services (Nginx config, process management, etc.)
+- System administration and troubleshooting
+
+<Frame>
+  <img src="https://cdn.link-ai.tech/doc/20260203121008.png" width="800" />
+</Frame>
--- a/docs/en/tools/browser.mdx
+++ b/docs/en/tools/browser.mdx
@@ -0,0 +1,27 @@
+---
+title: browser - Browser
+description: Access and interact with web pages
+---
+
+# browser
+
+Use a browser to access and interact with web pages, supports JavaScript-rendered dynamic pages.
+
+## Dependencies
+
+| Dependency | Install Command |
+| --- | --- |
+| `browser-use` ≥ 0.1.40 | `pip install browser-use` |
+| `markdownify` | `pip install markdownify` |
+| `playwright` + chromium | `pip install playwright && playwright install chromium` |
+
+## Use Cases
+
+- Access specific URLs to get page content
+- Interact with web page elements (click, type, etc.)
+- Verify deployed web pages
+- Scrape dynamic content requiring JS rendering
+
+<Note>
+  The browser tool has heavy dependencies. If not needed, skip installation. For lightweight web content retrieval, use the `web-fetch` skill instead.
+</Note>
--- a/docs/en/tools/edit.mdx
+++ b/docs/en/tools/edit.mdx
@@ -0,0 +1,26 @@
+---
+title: edit - File Edit
+description: Edit files via precise text replacement
+---
+
+# edit
+
+Edit files via precise text replacement. If `oldText` is empty, appends to the end of the file.
+
+## Dependencies
+
+No extra dependencies, available by default.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `path` | string | Yes | File path |
+| `oldText` | string | Yes | Original text to replace (empty to append) |
+| `newText` | string | Yes | Replacement text |
+
+## Use Cases
+
+- Modify specific parameters in configuration files
+- Fix bugs in code
+- Insert content at specific positions in files
--- a/docs/en/tools/env-config.mdx
+++ b/docs/en/tools/env-config.mdx
@@ -0,0 +1,38 @@
+---
+title: env_config - Environment
+description: Manage API keys and secrets
+---
+
+# env_config
+
+Manage environment variables (API keys and secrets) in the workspace `.env` file, with secure conversational updates. Built-in security protection and desensitization.
+
+## Dependencies
+
+| Dependency | Install Command |
+| --- | --- |
+| `python-dotenv` ≥ 1.0.0 | `pip install python-dotenv>=1.0.0` |
+
+Included when installing optional dependencies: `pip3 install -r requirements-optional.txt`
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `action` | string | Yes | Operation type: `get`, `set`, `list`, `delete` |
+| `key` | string | No | Environment variable name |
+| `value` | string | No | Environment variable value (only for `set`) |
+
+## Usage
+
+Tell the Agent what key you need to configure, and it will automatically invoke this tool:
+
+- "Configure my BOCHA_API_KEY"
+- "Set OPENAI_API_KEY to sk-xxx"
+- "Show configured environment variables"
+
+Configured keys are automatically injected into the `bash` tool's execution environment.
+
+<Frame>
+  <img src="https://cdn.link-ai.tech/doc/20260202234939.png" width="800" />
+</Frame>
--- a/docs/en/tools/index.mdx
+++ b/docs/en/tools/index.mdx
@@ -0,0 +1,50 @@
+---
+title: Tools Overview
+description: CowAgent built-in tools system
+---
+
+Tools are the core capability for Agent to access operating system resources. The Agent intelligently selects and invokes tools based on task requirements, performing file operations, command execution, web search, scheduled tasks, and more. Tools are implemented in the `agent/tools/` directory.
+
+## Built-in Tools
+
+The following tools are available by default with no extra configuration:
+
+<CardGroup cols={2}>
+  <Card title="read - File Read" icon="file" href="/en/tools/read">
+    Read file content, supports text, images, PDF
+  </Card>
+  <Card title="write - File Write" icon="pen" href="/en/tools/write">
+    Create or overwrite files
+  </Card>
+  <Card title="edit - File Edit" icon="pen-to-square" href="/en/tools/edit">
+    Edit files via precise text replacement
+  </Card>
+  <Card title="ls - Directory List" icon="folder-open" href="/en/tools/ls">
+    List directory contents
+  </Card>
+  <Card title="bash - Terminal" icon="terminal" href="/en/tools/bash">
+    Execute system commands
+  </Card>
+  <Card title="send - File Send" icon="paper-plane" href="/en/tools/send">
+    Send files or images to user
+  </Card>
+  <Card title="memory - Memory" icon="brain" href="/en/tools/memory">
+    Search and read long-term memory
+  </Card>
+</CardGroup>
+
+## Optional Tools
+
+The following tools require additional dependencies or API key configuration:
+
+<CardGroup cols={2}>
+  <Card title="env_config - Environment" icon="key" href="/en/tools/env-config">
+    Manage API keys and secrets
+  </Card>
+  <Card title="scheduler - Scheduler" icon="clock" href="/en/tools/scheduler">
+    Create and manage scheduled tasks
+  </Card>
+  <Card title="web_search - Web Search" icon="magnifying-glass" href="/en/tools/web-search">
+    Search the internet for real-time information
+  </Card>
+</CardGroup>
--- a/docs/en/tools/ls.mdx
+++ b/docs/en/tools/ls.mdx
@@ -0,0 +1,25 @@
+---
+title: ls - Directory List
+description: List directory contents
+---
+
+# ls
+
+List directory contents, sorted alphabetically, directories suffixed with `/`, includes hidden files.
+
+## Dependencies
+
+No extra dependencies, available by default.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `path` | string | Yes | Directory path, relative paths are based on workspace directory |
+| `limit` | integer | No | Maximum entries to return, default 500 |
+
+## Use Cases
+
+- Browse project structure
+- Find specific files
+- Check if a directory exists
--- a/docs/en/tools/memory.mdx
+++ b/docs/en/tools/memory.mdx
@@ -0,0 +1,38 @@
+---
+title: memory - Memory
+description: Search and read long-term memory
+---
+
+# memory
+
+The memory tool contains two sub-tools: `memory_search` (search memory) and `memory_get` (read memory files).
+
+## Dependencies
+
+No extra dependencies, available by default. Managed by the Agent Core memory system.
+
+## memory_search
+
+Search historical memory with hybrid keyword and vector retrieval.
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `query` | string | Yes | Search query |
+
+## memory_get
+
+Read the content of a specific memory file.
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `path` | string | Yes | Relative path to memory file (e.g. `MEMORY.md`, `memory/2026-01-01.md`) |
+| `start_line` | integer | No | Start line number |
+| `end_line` | integer | No | End line number |
+
+## How It Works
+
+The Agent automatically invokes memory tools in these scenarios:
+
+- When the user shares important information → stores to memory
+- When historical context is needed → searches relevant memory
+- When conversation reaches a certain length → extracts summary for storage
--- a/docs/en/tools/read.mdx
+++ b/docs/en/tools/read.mdx
@@ -0,0 +1,26 @@
+---
+title: read - File Read
+description: Read file content
+---
+
+# read
+
+Read file content. Supports text files, PDF files, images (returns metadata), and more.
+
+## Dependencies
+
+No extra dependencies, available by default.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `path` | string | Yes | File path, relative paths are based on workspace directory |
+| `offset` | integer | No | Start line number (1-indexed), negative values read from the end |
+| `limit` | integer | No | Number of lines to read |
+
+## Use Cases
+
+- View configuration files, log files
+- Read code files for analysis
+- Check image/video file info
--- a/docs/en/tools/scheduler.mdx
+++ b/docs/en/tools/scheduler.mdx
@@ -0,0 +1,42 @@
+---
+title: scheduler - Scheduler
+description: Create and manage scheduled tasks
+---
+
+# scheduler
+
+Create and manage dynamic scheduled tasks with flexible scheduling and execution modes.
+
+## Dependencies
+
+| Dependency | Install Command |
+| --- | --- |
+| `croniter` ≥ 2.0.0 | `pip install croniter>=2.0.0` |
+
+Included in core dependencies: `pip3 install -r requirements.txt`
+
+## Scheduling Modes
+
+| Mode | Description |
+| --- | --- |
+| One-time | Execute once at a specified time |
+| Fixed interval | Repeat at fixed time intervals |
+| Cron expression | Define complex schedules using Cron syntax |
+
+## Execution Modes
+
+- **Fixed message**: Send a preset message when triggered
+- **Agent dynamic task**: Agent intelligently executes the task when triggered
+
+## Usage
+
+Create and manage scheduled tasks with natural language:
+
+- "Send me a weather report every morning at 9 AM"
+- "Check server status every 2 hours"
+- "Remind me about the meeting tomorrow at 3 PM"
+- "Show all scheduled tasks"
+
+<Frame>
+  <img src="https://cdn.link-ai.tech/doc/20260202195402.png" width="800" />
+</Frame>
--- a/docs/en/tools/send.mdx
+++ b/docs/en/tools/send.mdx
@@ -0,0 +1,25 @@
+---
+title: send - File Send
+description: Send files to user
+---
+
+# send
+
+Send files to the user (images, videos, audio, documents, etc.), used when the user explicitly requests to send/share a file.
+
+## Dependencies
+
+No extra dependencies, available by default.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `path` | string | Yes | File path, can be absolute or relative to workspace |
+| `message` | string | No | Accompanying message |
+
+## Use Cases
+
+- Send generated code or documents to the user
+- Send screenshots, charts
+- Share downloaded files
--- a/docs/en/tools/web-search.mdx
+++ b/docs/en/tools/web-search.mdx
@@ -0,0 +1,34 @@
+---
+title: web_search - Web Search
+description: Search the internet for real-time information
+---
+
+# web_search
+
+Search the internet for real-time information, news, research, and more. Supports two search backends with automatic fallback.
+
+## Dependencies
+
+Requires at least one search API key (configured via `env_config` tool or workspace `.env` file):
+
+| Backend | Environment Variable | Priority | How to Get |
+| --- | --- | --- | --- |
+| Bocha Search | `BOCHA_API_KEY` | Primary | [Bocha Open Platform](https://open.bochaai.com/) |
+| LinkAI Search | `LINKAI_API_KEY` | Fallback | [LinkAI Console](https://link-ai.tech/console/interface) |
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `query` | string | Yes | Search keywords |
+| `count` | integer | No | Number of results (1-50, default 10) |
+| `freshness` | string | No | Time range: `noLimit`, `oneDay`, `oneWeek`, `oneMonth`, `oneYear`, or date range like `2025-01-01..2025-02-01` |
+| `summary` | boolean | No | Return page summaries (default false) |
+
+## Use Cases
+
+When the user asks about latest information, needs fact-checking, or real-time data, the Agent automatically invokes this tool.
+
+<Note>
+  If no search API key is configured, this tool will not be loaded.
+</Note>
--- a/docs/en/tools/write.mdx
+++ b/docs/en/tools/write.mdx
@@ -0,0 +1,29 @@
+---
+title: write - File Write
+description: Create or overwrite files
+---
+
+# write
+
+Write content to a file. Creates the file if it doesn't exist, overwrites if it does. Automatically creates parent directories.
+
+## Dependencies
+
+No extra dependencies, available by default.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `path` | string | Yes | File path |
+| `content` | string | Yes | Content to write |
+
+## Use Cases
+
+- Create new code files or scripts
+- Generate configuration files
+- Save processing results
+
+<Note>
+  Single writes should not exceed 10KB. For large files, create a skeleton first, then use the edit tool to add content in chunks.
+</Note>