docs: update AGENTS guidance
This commit is contained in:
YeonGyu-Kim
@@ -0,0 +1,54 @@
|
||||
# src/tools/ast-grep/ -- AST-Aware Search and Rewrite
|
||||
|
||||
**Generated:** 2026-05-18
|
||||
|
||||
## OVERVIEW
|
||||
|
||||
Two always-on tools: `ast_grep_search` (find AST patterns) and `ast_grep_replace` (rewrite AST patterns). 25 languages supported via `@ast-grep/napi` as primary backend with fallback to `sg` CLI.
|
||||
|
||||
Pattern syntax uses AST meta-variables, not regex. `$VAR` matches one AST node. `$$$` matches zero or more nodes. `$$$VAR` captures a named list. Patterns must be complete, parseable source code.
|
||||
|
||||
`ast_grep_replace` defaults to dry-run. Pass `dryRun=false` to apply changes.
|
||||
|
||||
## FILE CATALOG
|
||||
|
||||
| File | Role |
|
||||
|------|------|
|
||||
| `tools.ts` | `createAstGrepTools` factory -- returns Record with 2 tool entries |
|
||||
| `cli.ts` | `runSg` -- spawns sg process, handles two-pass rewrite |
|
||||
| `cli-binary-path-resolution.ts` | Async init wrapper with singleton promise dedup |
|
||||
| `sg-cli-path.ts` | Resolve sg via node_modules, platform subpackages, Homebrew, or cache |
|
||||
| `downloader.ts` | Auto-download from GitHub releases if missing |
|
||||
| `environment-check.ts` | Verify CLI + NAPI availability at startup |
|
||||
| `language-support.ts` | 25 CLI languages + 5 NAPI languages + extension map |
|
||||
| `pattern-hints.ts` | Detect regex misuse and language-specific mistakes |
|
||||
| `result-formatter.ts` | Format matches with file:line:column for LLM |
|
||||
| `sg-compact-json-output.ts` | Parse `sg --json=compact` into `SgResult` |
|
||||
| `tool-descriptions.ts` | Tool description constants |
|
||||
| `process-output-timeout.ts` | 300s timeout wrapper for spawn |
|
||||
| `types.ts` | `CliMatch`, `SgResult`, `AnalyzeResult`, etc. |
|
||||
| `constants.ts` | Re-exports from language-support, environment-check, sg-cli-path |
|
||||
| `index.ts` | Barrel |
|
||||
|
||||
## KEY BEHAVIORS
|
||||
|
||||
- Dual binary detection: NAPI primary, CLI fallback
|
||||
- Fallback chain: node_modules → platform subpackage → Homebrew → cached download
|
||||
- Dry-run protection: `ast_grep_replace` defaults to preview; pass `dryRun=false` to apply
|
||||
- Two-pass rewrite: when rewrite + apply both requested, cli.ts runs `--json=compact` first, then `--update-all`
|
||||
- Output limits: 1MB max output or 500 matches, whichever comes first
|
||||
- Timeout: 300s cap via `process-output-timeout.ts`; kills process and returns truncated result
|
||||
|
||||
## LANGUAGES
|
||||
|
||||
25 CLI languages: bash, c, cpp, csharp, css, elixir, go, haskell, html, java, javascript, json, kotlin, lua, nix, php, python, ruby, rust, scala, solidity, swift, typescript, tsx, yaml.
|
||||
|
||||
5 NAPI languages (native bindings): html, javascript, tsx, css, typescript.
|
||||
|
||||
## PATTERN HINTS
|
||||
|
||||
When a search returns zero matches, `pattern-hints.ts` scans for regex-style misuse (`|`, `.*`, `\w`, `[a-z]`) and returns a corrective hint redirecting to ast-grep meta-variable syntax. Also catches language-specific mistakes like trailing colons in Python def/class patterns or incomplete function signatures in JS/Go/Rust.
|
||||
|
||||
## RELATED
|
||||
|
||||
Doctor check at `src/cli/doctor/checks/tools.ts` verifies both NAPI and CLI availability.
|
||||
@@ -0,0 +1,52 @@
|
||||
# src/tools/look-at/ -- Image and PDF Analysis Tool
|
||||
|
||||
**Generated:** 2026-05-18
|
||||
|
||||
## OVERVIEW
|
||||
|
||||
14 files. The `look_at` tool delegates image, PDF, and diagram analysis to the `multimodal-looker` subagent. Conditional gate: tool is only registered when `multimodal-looker` is not in `disabled_agents`. Default subagent model: gpt-5.5 medium. This is a summary extractor, not a precise reader.
|
||||
|
||||
## EXECUTION FLOW
|
||||
|
||||
1. **Args** (`look-at-arguments.ts`) -- normalize `file_path`/`image_data` aliases, validate one-of requirement, reject remote URLs
|
||||
2. **Prep** (`look-at-input-preparer.ts`) -- resolve path, detect MIME from extension or Base64 header, convert unsupported images to JPEG
|
||||
3. **Spawn** (`look-at-session-runner.ts`) -- create child session with `multimodal-looker` agent, attach file as message part, disable `task`/`call_omo_agent`/`look_at` to prevent recursion
|
||||
4. **Poll** (`session-poller.ts`) -- wait until idle (1s interval, 120s timeout)
|
||||
5. **Extract** (`assistant-message-extractor.ts`) -- pull latest assistant text from session messages
|
||||
6. **Return** -- summary text back to caller
|
||||
|
||||
## FILE CATALOG
|
||||
|
||||
| File | Responsibility |
|
||||
|------|----------------|
|
||||
| `tools.ts` | `createLookAt()` factory -- tool schema + entry point |
|
||||
| `look-at-arguments.ts` | Zod arg schema, normalize aliases, validate inputs |
|
||||
| `look-at-input-preparer.ts` | Build `LookAtFilePart` from path or base64; trigger conversion if needed |
|
||||
| `look-at-prompt.ts` | System prompt for the multimodal session |
|
||||
| `look-at-session-runner.ts` | Orchestrate child session creation, prompt dispatch, message fetch |
|
||||
| `session-poller.ts` | Poll session status until idle |
|
||||
| `assistant-message-extractor.ts` | Extract latest assistant text from raw session messages |
|
||||
| `image-converter.ts` | Convert HEIC/WebP/RAW/PSD to JPEG via sips or ImageMagick |
|
||||
| `mime-type-inference.ts` | Detect MIME from file extension or Base64 header |
|
||||
| `missing-file-error.ts` | Clear `ENOENT` error message when file is missing |
|
||||
| `multimodal-agent-metadata.ts` | Resolve actual model for multimodal-looker from config or dynamic pipeline |
|
||||
| `multimodal-fallback-chain.ts` | Build vision-capable fallback chain: kimi-k2.6, glm-4.6v, gpt-5-nano |
|
||||
| `constants.ts` | `MULTIMODAL_LOOKER_AGENT`, `LOOK_AT_DESCRIPTION` |
|
||||
| `types.ts` | `LookAtArgs` interface |
|
||||
|
||||
## GATE
|
||||
|
||||
Conditional. Tool is registered only when `multimodal-looker` is absent from `disabled_agents`.
|
||||
|
||||
## USE CASE
|
||||
|
||||
PDFs, screenshots, diagrams -- quick summary extraction. NOT for visual precision, aesthetic evaluation, or exact accuracy. Use the Read tool for those cases instead.
|
||||
|
||||
## DISTINCTION
|
||||
|
||||
This is the TOOL that DELEGATES TO the `multimodal-looker` AGENT. The agent lives in `src/agents/builtin-agents/multimodal-looker.ts`; this tool is the invocation harness.
|
||||
|
||||
## NOTES
|
||||
|
||||
- Temporary converted images are cleaned up in `finally` blocks
|
||||
- The subagent has `read` tool disabled by default (`READ_ENABLED = false`); the file is passed as an attachment
|
||||
@@ -0,0 +1,48 @@
|
||||
# src/tools/skill/ -- Skill and Command Loader Tool
|
||||
|
||||
**Generated:** 2026-05-18
|
||||
|
||||
## OVERVIEW
|
||||
|
||||
The `skill` tool. Dual purpose: (1) load a skill by name to inject its SKILL.md content into context, (2) invoke a slash command by name (omit leading slash). Skills may spin up embedded MCP servers on demand. Commands route through the autoSlashCommand hook.
|
||||
|
||||
## FILE CATALOG
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `tools.ts` | `createSkillTool` factory -- resolves name, loads body, returns formatted output |
|
||||
| `skill-body.ts` | Extracts `<skill-instruction>` block or full SKILL.md template |
|
||||
| `skill-matcher.ts` | Exact match, short-name fallback, partial-match suggestions |
|
||||
| `scope-priority.ts` | 4-scope priority: project (4) > user (3) > opencode (2) > builtin/plugin (1) |
|
||||
| `native-skills.ts` | Merges `PluginInput.skills` entries into discovered skill list |
|
||||
| `description-formatter.ts` | Builds LLM-visible `<available_items>` listing with scope tags |
|
||||
| `mcp-capability-formatter.ts` | Lists skill-embedded MCP tools/resources/prompts for `skill_mcp` calls |
|
||||
| `session-skill-cache.ts` | Dedupes repeated skill loads per session via `seenSessionIDs` |
|
||||
| `types.ts` | `SkillArgs`, `SkillInfo`, `SkillLoadOptions` |
|
||||
| `constants.ts` | Tool name and description prefix |
|
||||
| `index.ts` | Barrel exports |
|
||||
|
||||
## EXECUTION FLOW
|
||||
|
||||
```
|
||||
skill(name="git-master")
|
||||
-> matchSkillByName() # exact, then short-name
|
||||
-> ask(permission) # host skill permission gate
|
||||
-> extractSkillBody() # load SKILL.md content
|
||||
-> formatMcpCapabilities() # if skill has mcpConfig
|
||||
-> return "## Skill: ..." + body + MCP info
|
||||
```
|
||||
|
||||
## SCOPE PRIORITY
|
||||
|
||||
Project configs override user configs, which override opencode builtins. `sortByScopePriority` applies to both skills and slash commands in the `<available_items>` listing.
|
||||
|
||||
## TEST MOCKS
|
||||
|
||||
`zauc-mocks-skill-tools/` -- `mock.module()` setup for skill tool tests. Loads alphabetically before consuming tests via the `zauc-` prefix sort-order hack.
|
||||
|
||||
## INTEGRATION
|
||||
|
||||
- Discovery: `opencode-skill-loader` feature module scans `.opencode/skills/`, `~/.config/opencode/skills/`, and built-in paths
|
||||
- MCP spawn: `skill-mcp-manager` feature module starts embedded MCP servers per session on demand
|
||||
- Commands: `slashcommand/` module feeds discovered commands into the tool description
|
||||
Reference in New Issue
Block a user