da4a803c11
- Added locale support in various components, including the Assistant's execution context and agent tools, to improve internationalization. - Updated the `pickNodeByFilter` function to include a fallback mechanism for host_exec nodes when no container nodes are available. - Introduced a new `agent_reference` tool for downloading agent source code for read-only study, alongside updates to the `agent_download` tool to restrict downloads to the 'smith' namespace. - Enhanced documentation and tests to reflect the new functionalities and ensure robust locale extraction and handling.
88 lines
5 KiB
Markdown
88 lines
5 KiB
Markdown
## Yao Sandbox Environment
|
|
|
|
### Environment Variables
|
|
|
|
These environment variables are set by the Yao sandbox. **Always use these variables — never hardcode paths.**
|
|
|
|
| Variable | Purpose | Example |
|
|
| ------------------- | ------------------------------------------ | -------------------------------------- |
|
|
| `$WORKDIR` | Sandbox working directory (project root) | `/workspace` |
|
|
| `$HOME` | Same as `$WORKDIR` (redirected by sandbox) | `/workspace` |
|
|
| `$CTX_SKILLS_DIR` | Skills directory for this assistant | `$WORKDIR/.yao/assistants/<id>/skills` |
|
|
| `$CTX_ASSISTANT_ID` | Current assistant ID | `yao.agent-smith` |
|
|
| `$CTX_WORKSPACE_ID` | Current workspace ID | `ws-abc123` |
|
|
|
|
### Path Rules
|
|
|
|
- **Use `$WORKDIR`** for all file paths — never hardcode `/workspace`
|
|
- **Use `$CTX_SKILLS_DIR`** for assistant-specific skills (custom skills provided by the assistant)
|
|
- System tool skills are in `$HOME/.claude/skills/` and are **auto-discovered** — you do not need to read them manually
|
|
- The `Read` and `Write` tools do **NOT** expand shell variables.
|
|
Resolve first: `echo "$WORKDIR"`, then use the printed value.
|
|
- On Windows, use `$env:WORKDIR` / `$env:CTX_SKILLS_DIR` syntax instead.
|
|
|
|
### Workspace Path in Replies
|
|
|
|
When replying to users, **never expose raw `/workspace/...` paths**. Rewrite them using the `workspace://` scheme so the frontend can render them correctly.
|
|
|
|
**Format**: `workspace://<workspace-id>/relative/path`
|
|
|
|
**Step 1 — resolve the real workspace ID** (do this once per session):
|
|
|
|
```bash
|
|
echo "$CTX_WORKSPACE_ID"
|
|
```
|
|
|
|
Use the **actual printed value** (e.g. `ws-bfc4c2de-b53...`) in all subsequent replies.
|
|
|
|
**Step 2 — rewrite paths in replies**:
|
|
|
|
- `/workspace/output/result.png` → `workspace://<real-id>/output/result.png`
|
|
|
|
**Common mistakes** (all wrong):
|
|
|
|
- `workspace://$CTX_WORKSPACE_ID/...` ← shell variable literally in reply
|
|
- `workspace://ws-bfc4c2de-b53/...` ← example/placeholder ID instead of the real one
|
|
- `workspace://<workspace-id>/...` ← template placeholder instead of the real one
|
|
- `/workspace/output/...` ← raw path without `workspace://` scheme
|
|
|
|
You **must** run `echo "$CTX_WORKSPACE_ID"` and use the exact output.
|
|
|
|
### Attachments
|
|
|
|
User-uploaded files are placed in `$WORKDIR/.attachments/{chatID}/`.
|
|
When the user references an attached file, read it from this directory.
|
|
|
|
### Image Files
|
|
|
|
When you need to read, analyze, or describe an image (screenshot, photo, chart, diagram, etc.), **always use `image_read`** instead of trying to read binary files directly. The tool sends the image to a vision model and returns a text description.
|
|
|
|
```bash
|
|
tai tool image_read '{"image_path": "<file_path_or_url>", "prompt": "describe this image"}'
|
|
```
|
|
|
|
## Yao System Tools
|
|
|
|
You have access to Yao system tools via the `tai` command in bash.
|
|
|
|
**Calling convention**: `tai tool <name> '<json_args>'`
|
|
|
|
| Tool | Skill (auto-loaded) | Description |
|
|
| ----------------- | ------------------- | --------------------------------------------------- |
|
|
| `web_search` | yao-web | Search the web for real-time information |
|
|
| `web_fetch` | yao-web | Fetch and read a web page by URL |
|
|
| `process_call` | yao-process | Execute a Yao Process (server-side function) |
|
|
| `process_allowed` | yao-process | Check which processes are allowed |
|
|
| `doc_list` | yao-doc | Search/list available process documentation |
|
|
| `doc_inspect` | yao-doc | Get detailed docs for a specific process |
|
|
| `doc_validate` | yao-doc | Validate a process name and get suggestions |
|
|
| `image_read` | yao-image | Read and analyze images using a vision model |
|
|
| `image_generate` | yao-image | Generate images from text prompts |
|
|
| `image_providers` | yao-image | List available image generation or vision providers |
|
|
| `agent_list` | yao-agent | List available agents on the host |
|
|
| `agent_download` | yao-agent | Download smith agent for editing (smith only) |
|
|
| `agent_reference` | yao-agent | Download agent source to .references/ for study |
|
|
| `agent_deploy` | yao-agent | Deploy agent code to host (smith namespace only) |
|
|
| `agent_connectors` | yao-agent | Get LLM connector matrix (no keys) |
|
|
|
|
The system skills (`yao-web`, `yao-process`, `yao-doc`, `yao-image`, `yao-agent`) in `$HOME/.claude/skills/` are **auto-discovered** — they contain detailed parameter docs and workflow guidance. You do not need to manually read them; they are loaded automatically when your task matches their description.
|