serena

分类: 工具与效率 | 上传者: juanclaw | 下载: 0 | 版本: v1.0（最新）

在处理具有重要结构的现有软件项目时，尤其是在多文件存储库中，使用 Serena 支持的语义代码导航和编辑，其中符号感知查找和有针对性的编辑比暴力文件读取更可靠、更高效。当环境公开 Serena 工具（例如项目激活、符号查找、参考搜索、语义搜索、文件读取、目录列表、文件查找或符号范围编辑）时使用。

更新日志: Source: GitHub https://github.com/juanclaw/Serena-Openclaw-Plugin

目录结构

当前层级: tree/main/src/skill/

📁 references/
- 📄 integration-patterns.md 2.9 KB
📄 SKILL.md 5.7 KB

SKILL.md

---
name: serena
description: Use Serena-backed semantic code navigation and editing when working in existing software projects with non-trivial structure, especially multi-file repos where symbol-aware lookup and targeted edits are more reliable and token-efficient than brute-force file reading. Use when the environment exposes Serena tools such as project activation, symbol lookup, reference search, semantic search, file reads, directory listing, file finding, or symbol-scoped edits.
---

# Serena

Use Serena as the first choice for understanding and editing **existing** codebases when the necessary tools are available.

## What this skill is for

Use this skill when another agent needs to integrate Serena into its normal coding workflow instead of treating the repo as a pile of text files.

Aim for this behavior:

- activate the project once
- inspect structure semantically before reading large files
- trace references before editing
- prefer symbol-scoped edits when possible
- fall back to normal file tools only when Serena is missing a capability or fails

For extra examples and trigger patterns, read `references/integration-patterns.md`.

## Core workflow

1. Resolve the target project path.
2. Call `serena_activate_project`.
3. Start with structure discovery:
   - `serena_project_overview`
   - `serena_find_symbol`
   - `serena_list_dir`
   - `serena_find_file`
   - `serena_session_status` when you need to inspect active Serena sessions
4. Narrow scope with:
   - `serena_find_references`
   - `serena_search_pattern`
   - `serena_read_symbol`
   - `serena_read_file`
5. Prefer semantic edits when changing existing code:
   - `serena_replace_symbol_body`
   - `serena_insert_before_symbol`
   - `serena_insert_after_symbol`
   - `serena_rename_symbol`
6. Use broader edit tools only when symbol-scoped tools are not a good fit:
   - `serena_replace_content`
   - `serena_create_text_file`
7. Use `serena_execute_shell_command` only as an advanced escape hatch when project-context shell execution is genuinely the right tool.
8. Use `serena_call_tool` only when the normalized surface does not cover the needed Serena capability.
9. Fall back to ordinary file tools only when Serena cannot answer safely or reliably.

## When Serena is worth the overhead

Prefer Serena when:

- the project spans multiple files
- the user asks about references, call chains, or symbol relationships
- the user wants a precise edit to an existing class, function, method, or module
- reading whole files would be noisy or wasteful
- the repo already has real structure and semantic lookup is available

Skip or delay Serena when:

- the task is a tiny one-file change and the target location is already obvious
- you are creating a brand-new file with little dependency on existing code
- Serena is unavailable or failing and direct file tools are simpler
- the user already provided the exact file region and semantic lookup adds no value

## Tool preference order

For existing codebases, prefer this order:

1. `serena_activate_project`
2. `serena_project_overview` / `serena_find_symbol` / `serena_find_file`
3. `serena_find_references` / `serena_search_pattern`
4. `serena_read_symbol` / `serena_read_file`
5. symbol-scoped edit tools
6. broader Serena edit tools
7. `serena_session_status` for session inspection/debugging
8. `serena_execute_shell_command` only when semantic tools are not the right mechanism
9. fallback to `read`, `edit`, and `exec` only when needed

## Integration guidance for agent authors

When you want another agent to use Serena well, instruct it to:

- activate the project before semantic reads or edits
- inspect symbols and references before modifying code
- use normalized Serena tools first
- keep edits narrow and structured
- avoid whole-file rewrites when a symbol-scoped edit is possible
- treat passthrough as an escape hatch, not the default workflow

A good instruction pattern is:

> Use Serena on the repo. Start with `serena_activate_project`, then narrow scope with `serena_find_symbol`, `serena_find_references`, and `serena_read_symbol` before editing.

## Practical usage patterns

### Understand a repo area

Use this sequence:

1. `serena_activate_project`
2. `serena_find_file` or `serena_list_dir`
3. `serena_project_overview`
4. `serena_find_symbol`
5. `serena_read_symbol`

### Trace impact before changing code

Use this sequence:

1. `serena_find_symbol`
2. `serena_find_references`
3. `serena_search_pattern` if naming or text-level usage matters
4. `serena_read_symbol` for the most relevant callers/callees

### Make a targeted edit

Use this sequence:

1. locate the exact symbol
2. read the symbol body
3. inspect references if behavior changes could ripple outward
4. choose the narrowest valid edit tool
5. re-read the changed symbol or nearby references when confidence is low

## Editing rules

- Keep edits as narrow as possible.
- Prefer symbol-targeted edits over text replacement across a whole file.
- Prefer semantic rename over manual multi-file rename logic.
- Re-read the relevant symbol or references after a material edit when confidence is low.
- If semantic identity is ambiguous, do not guess; disambiguate using path or extra lookup.
- In read-only mode, do not attempt mutating Serena tools.

## Safety and fallback behavior

If Serena fails:

1. Explain briefly what failed.
2. Fall back to standard file-based workflow.
3. Keep using the smallest possible read/edit scope.
4. Do not pretend the semantic result was confirmed if it was not.

If a raw Serena passthrough tool is available:

- use it only when the normalized tool surface does not cover the needed capability
- prefer stable normalized tools for repeated workflows
- avoid passthrough for routine actions that already have a clear normalized tool

登录后下载/点赞/收藏 ❤ 5 | ★ 0

serena

目录结构

SKILL.md

举报内容

提示