cleanup: remove unrelated discovery doc from OpenCode integration
This commit is contained in:
_rl_22_
parent
be8dd99ec6
commit
b63e0978c3
|
|
@ -1,180 +0,0 @@
|
|||
# opencode Core Architecture Deep Dive
|
||||
|
||||
This document provides a comprehensive overview of the foundational elements of the `opencode` architecture, based on a detailed examination of its codebase.
|
||||
|
||||
## Core Philosophies and Goals:
|
||||
|
||||
The core philosophies behind `opencode` revolve around empowering developers with an **AI coding agent built for the terminal**, emphasizing **extensibility, configurability, and a structured approach to AI interaction**.
|
||||
|
||||
### What `opencode` Set Out to Do:
|
||||
|
||||
1. **AI-Powered Developer Augmentation:** Provide an intelligent assistant that helps developers with coding tasks directly within their terminal environment.
|
||||
2. **Extensibility and Customization:** Be highly adaptable, allowing users to extend its capabilities and tailor its behavior to specific project needs and preferences.
|
||||
3. **Structured and Reliable AI Interaction:** Make AI interactions predictable and manageable through clear definitions of agents, tools, and sessions, along with robust error handling and validation.
|
||||
4. **Transparency and Observability:** Provide insights into the AI's decision-making process and tool execution.
|
||||
|
||||
### How `opencode` Accomplished Its Goals:
|
||||
|
||||
1. **Agent-Centric Architecture:**
|
||||
- **Configurable Agents:** Defines agents with distinct roles, permissions, and toolsets (`Agent.Info` schema), allowing for specialized AI behaviors.
|
||||
- **Agent Generation:** The `Agent.generate` function, guided by a meta-prompt (`generate.txt`), enables the AI to create new agent configurations based on user descriptions.
|
||||
|
||||
2. **Tool-Driven Capabilities:**
|
||||
- **Comprehensive Toolset:** Provides a rich set of built-in tools for common developer tasks (e.g., `bash`, `edit`, `read`, `write`, `glob`, `grep`, `webfetch`).
|
||||
- **Extensible Tool Registry:** The `ToolRegistry` allows for dynamic registration of new tools through plugins (`EXTRA` tools) and HTTP callbacks (`HTTP` tools).
|
||||
- **Structured Tool Definition:** Tools adhere to the `Tool.Info` interface, ensuring clear descriptions, `zod`-validated parameters, and a standardized `execute` method.
|
||||
|
||||
3. **Session-Based Context Management:**
|
||||
- **Persistent Sessions:** Manages persistent sessions (`Session.Info`) that maintain conversation history, tool outputs, and project context.
|
||||
- **Message Structure:** Messages are highly structured (`MessageV2.Info` and `MessageV2.Part`s), supporting various content types (text, reasoning, tool calls, file changes, snapshots).
|
||||
- **Context Pruning:** The `prune` function helps manage token limits by compacting old tool outputs.
|
||||
|
||||
4. **API-First Design:**
|
||||
- **Hono-based Server:** A robust HTTP API exposes all core functionalities, making `opencode` programmable and allowing for diverse frontend integrations.
|
||||
|
||||
5. **Dynamic Prompt Orchestration:**
|
||||
- **Context Assembly:** Dynamically constructs system prompts by combining provider-specific headers, model-specific instructions, environmental context, and custom rule files.
|
||||
- **Workflow Automation:** The `command` function enables command-driven workflows, processing templates, handling file/agent references, and invoking subagents.
|
||||
|
||||
6. **Developer-Friendly Interfaces:**
|
||||
- **Terminal User Interface (TUI):** A Go-based TUI provides a terminal-native experience.
|
||||
- **Web Application:** A React/TypeScript web app (`packages/app/`) offers a modern, interactive interface.
|
||||
|
||||
---
|
||||
|
||||
## 1. Agents (`packages/opencode/src/agent/agent.ts`)
|
||||
|
||||
- **Definition:** Agents are configured via a `zod` schema (`Agent.Info`), specifying `name`, `description`, `mode` (`subagent`, `primary`, `all`), `permissions` (for `edit`, `bash`, `webfetch`), `model` (provider and ID), `prompt`, and `tools` (enabled/disabled).
|
||||
- **Configuration:** Agent configurations are loaded from `Config.get()` and managed via `Instance.state`. Built-in agents (`general`, `build`, `plan`) are provided, and users can define/override configurations.
|
||||
- **Generation:** The `Agent.generate` function uses a meta-prompt (`generate.txt`) to create new agent configurations based on descriptions.
|
||||
- **Invocation:** Agent invocation is primarily driven by the AI model's decision-making based on the system prompt and available tools. The `mode` property influences orchestration.
|
||||
- **Purpose:** Agents are specialized AI assistants configured for specific tasks and workflows, allowing for focused tools with custom prompts, models, and tool access.
|
||||
- **Configuration Details:** Configured in `opencode.json` or through Markdown files. Options include `description`, `temperature`, `disable` status, `prompt` (custom system prompt), `model` (to override the default), and `tools` (to control tool availability).
|
||||
- **Permissions:** Granular permissions for actions like `edit`, `bash`, and `webfetch` can be set to `allow`, `ask`, or `deny`, either globally or per agent, with granular control for bash commands.
|
||||
- **Mode:** Agents have a `mode` (primary, subagent, or all) and can accept `additional` provider-specific model options.
|
||||
|
||||
## 2. Tools (`packages/opencode/src/tool/registry.ts` and `packages/opencode/src/tool/tool.ts`)
|
||||
|
||||
- **Registry:** `ToolRegistry` is the central point for managing tools.
|
||||
- **Types:** Includes `BUILTIN` tools (e.g., `BashTool`, `EditTool`, `WebFetchTool`), `EXTRA` tools (runtime-registered via plugins), and `HTTP` tools (registered via HTTP callbacks for external services).
|
||||
- **Definition:** Tools are defined using `Tool.define`, adhering to the `Tool.Info` interface, which specifies `id`, `description`, `parameters` (with `zod` schemas for validation), and an `execute` method.
|
||||
- **Context:** The `Tool.Context` interface provides session, message, agent, and abort signal information to tools.
|
||||
- **Permissions:** The `ToolRegistry.enabled()` function determines tool availability based on agent permissions.
|
||||
|
||||
## 3. Server API (`packages/opencode/src/server/server.ts`)
|
||||
|
||||
- **Framework:** Hono-based HTTP API.
|
||||
- **Key Endpoints:**
|
||||
- `/experimental/tool/register`: Dynamic registration of HTTP callback tools.
|
||||
- `/experimental/tool/ids`, `/experimental/tool`: List available tools.
|
||||
- `/session/*`: Comprehensive session management (create, retrieve, update, delete, share, summarize, messages, prompts, commands, shell execution, revert, permissions).
|
||||
- `/config`, `/config/providers`: Configuration and AI provider/model lists.
|
||||
- `/file/*`: File system operations.
|
||||
- `/find/*`: Search functionalities.
|
||||
- `/agent`: List all agents.
|
||||
- `/tui/*`: TUI control endpoints.
|
||||
- `/auth/:id`: Authentication.
|
||||
|
||||
## 4. Session Management (`packages/opencode/src/session/index.ts`)
|
||||
|
||||
- **Structure:** Sessions are defined by `Session.Info` schema, including `id`, `projectID`, `directory`, `parentID`, `share` info, `title`, `version`, `time` (created, updated, compacting), and `revert` state.
|
||||
- **Lifecycle:** Functions for `create`, `get`, `list`, `children`, `update`, `remove`, `share`, `unshare`, and `initialize`.
|
||||
- **Message Handling:** Manages `MessageV2.Info` and `MessageV2.Part`s within sessions, including `updateMessage`, `removeMessage`, `updatePart`.
|
||||
- **Pruning:** `prune` function compacts old tool outputs to manage token limits.
|
||||
- **Usage:** `getUsage` tracks cost and token usage.
|
||||
|
||||
## 5. Message Structure (`packages/opencode/src/session/message-v2.ts`)
|
||||
|
||||
- **Errors:** Defines custom error types.
|
||||
- **`ToolState`:** Tracks the `pending`, `running`, `completed`, or `error` state of tool executions.
|
||||
- **`Part` Types:** A rich set of content types for messages: `SnapshotPart`, `PatchPart`, `TextPart`, `ReasoningPart`, `ToolPart`, `FilePart` (with `FileSource` or `SymbolSource`), `AgentPart`, `StepStartPart`, `StepFinishPart`.
|
||||
- **`User` and `Assistant` Messages:** Distinct schemas for user and assistant messages, with assistant messages including detailed contextual information, cost, and token usage.
|
||||
- **Events:** `MessageV2.Event` for real-time updates.
|
||||
- **`MessageV2.WithParts`:** Combines message info with its parts.
|
||||
|
||||
## 6. Prompt Orchestration (`packages/opencode/src/session/prompt.ts`)
|
||||
|
||||
- **Core Function:** `prompt(input: PromptInput)` orchestrates AI interaction.
|
||||
- **User Input:** Creates user messages, handling file references and converting them to AI-readable parts.
|
||||
- **Concurrency:** Uses session locking and queuing.
|
||||
- **Context Assembly:** Resolves agent, model, and constructs system prompts (`SystemPrompt.header`, `SystemPrompt.provider`, `SystemPrompt.environment`, `SystemPrompt.custom`).
|
||||
- **Tool Integration:** Resolves and wraps tools, handling execution, state updates, and plugin triggers.
|
||||
- **AI Interaction:** Uses `streamText` to interact with AI models.
|
||||
- **Response Processing:** `createProcessor` handles streaming AI output, updating messages, tool states, and tracking steps/patches.
|
||||
- **Direct Execution:** `shell` function for direct shell command execution.
|
||||
- **Command Workflows:** `command` function executes predefined commands, processes templates, handles file/agent references, and can invoke subagents via `TaskTool`.
|
||||
- **Dynamic Prompt Injection:** `insertReminders` injects synthetic prompts based on agent mode.
|
||||
- **Session Title Generation:** `ensureTitle` generates session titles using a smaller AI model.
|
||||
|
||||
## 7. System Prompts (`packages/opencode/src/session/system.ts`)
|
||||
|
||||
- **Dynamic Construction:** Combines provider-specific headers, model-specific instructions, environmental context, and custom rule files (`AGENTS.md`, `CLAUDE.md`, `CONTEXT.md`, `config.instructions`).
|
||||
- **Purpose:** Provides general instructions and context to AI models.
|
||||
- **Rules Details:**
|
||||
- **Purpose:** `AGENTS.md` (similar to `CLAUDE.md` or Cursor's rules) provides custom instructions to the `opencode` AI agent, guiding its behavior by including these instructions in the LLM's context.
|
||||
- **Location and Precedence:** Rules can be project-specific (project root) or global (`~/.config/opencode/AGENTS.md`). `opencode` combines both sets, with project-specific rules taking precedence.
|
||||
- **Custom Instruction Files:** Additional instruction files can be specified in `opencode.json`, allowing for reuse and referencing external files for modular guidelines. The agent can also be instructed to reference external files for modular rule sets, either through `opencode.json` or by explicit instructions in `AGENTS.md` that prompt lazy loading of relevant files.
|
||||
|
||||
## 8. Project Instance (`packages/opencode/src/project/instance.ts`)
|
||||
|
||||
- **Context Management:** `Instance.state` and `Instance.provide` manage project-specific context, ensuring operations are performed within the correct project directory and worktree.
|
||||
|
||||
## 9. Configuration (`packages/opencode/src/config/config.ts`)
|
||||
|
||||
- **Loading and Validation:** Handles loading, validating, and applying configurations for agents, tools, and other `opencode` settings.
|
||||
- **Configuration Management Details:**
|
||||
- **File Format:** `opencode` configuration is managed via JSON or JSONC files (supporting comments).
|
||||
- **File Locations and Precedence:**
|
||||
- **Global:** `~/.config/opencode/opencode.json`
|
||||
- **Per Project:** `opencode.json` in the project root.
|
||||
- **Environment Variable:** Can be specified via the `OPENCODE_CONFIG` environment variable (takes highest precedence).
|
||||
- **Key Configurable Aspects:**
|
||||
- Defining AI models and providers.
|
||||
- Setting UI themes.
|
||||
- Configuring specialized agents with custom prompts and tool permissions.
|
||||
- Creating custom commands.
|
||||
- Customizing keybinds.
|
||||
- Enabling/disabling autoupdate.
|
||||
- Configuring code formatters.
|
||||
- Managing granular permissions for AI agent actions (e.g., file editing, bash commands).
|
||||
- Specifying additional instructions for models.
|
||||
- **Advanced Configuration Features:**
|
||||
- Supports variable substitution for environment variables and file contents, which is particularly useful for managing sensitive data like API keys or incorporating large instruction sets.
|
||||
|
||||
## 10. Event Bus (`packages/opencode/src/bus/index.ts`)
|
||||
|
||||
- **Communication:** Provides a central mechanism for publishing and subscribing to events across different `opencode` components, enabling real-time updates and inter-component communication.
|
||||
|
||||
## 11. User Interfaces
|
||||
|
||||
- **Web Application (`packages/app/`):** React/TypeScript/Vite-based web UI.
|
||||
- **Terminal User Interface (`packages/tui/`):** Go-based TUI.
|
||||
- **Web Landing Page (`packages/web/`):** Astro-based web application.
|
||||
|
||||
## 12. Commands (from `https://opencode.ai/docs/commands/`)
|
||||
|
||||
- **Purpose:** Automate repetitive tasks, executed in the TUI by typing `/` followed by the command name.
|
||||
- **Definition:** Can be defined in `opencode.jsonc` or as Markdown files in the `.opencode/command/` directory.
|
||||
- **Structure:** Involves a template (the prompt sent to the LLM), an optional description, and optional specifications for the agent and model to be used.
|
||||
- **Placeholders:** Supports `$ARGUMENTS` (for passing arguments), `!command` (to inject shell command output), and `@filename` (to include file content).
|
||||
- **Execution:** Commands run in the project's root directory, and their output becomes part of the prompt.
|
||||
|
||||
## 13. Keybinds (from `https://opencode.ai/docs/keybinds/`)
|
||||
|
||||
- **Customization:** Fully customizable through the `opencode.json` configuration file.
|
||||
- **Leader Key:** Utilizes a "leader key" (defaulting to `ctrl+x`) that must be pressed before most other keybind shortcuts to prevent conflicts in the terminal.
|
||||
- **Disabling:** Specific keybinds can be disabled by setting their value to "none".
|
||||
|
||||
## 14. Formatters (from `https://opencode.ai/docs/formatters/`)
|
||||
|
||||
- **Purpose:** Automatically format files after they are written or edited, ensuring code adheres to project styles.
|
||||
- **Configuration:** Defined within the `formatter` section of the `opencode.json` configuration file.
|
||||
- **Properties:** Includes `disabled`, `command` (the command to execute for formatting), `environment` (environment variables), and `extensions` (file extensions it handles).
|
||||
- **Custom Formatters:** Can be defined by specifying their `command` and `extensions`, using `$FILE` as a placeholder for the file path.
|
||||
|
||||
## 15. Themes (from `https://opencode.ai/docs/themes/`)
|
||||
|
||||
- **Customization:** Offers extensive customization options, allowing users to select from built-in themes, adapt to their terminal's theme, or define custom themes using a flexible JSON-based system.
|
||||
- **Types:** Built-in themes, "system" theme (adapts to terminal background).
|
||||
- **Custom Theme Format:** Flexible JSON format, allowing for hex colors, ANSI colors, color references, dark/light variants, and the "none" value to inherit terminal defaults.
|
||||
- **Location and Precedence:** Custom themes can be defined at the user-wide or project-specific level, with a hierarchy determining precedence.
|
||||
Loading…
Reference in New Issue