self-skill git:20261104.dbc3ee9A

Immutable. This exact content never changes and is served at /api/v1/blob/ea6082629839ef7d.

---
name: self-skill
description: Loopra 内置 SelfSkill。首次处理任务、了解自身能力、发现与加载技能、接入 MCP/OpenAPI/插件或排查能力缺失时使用。
---

# SelfSkill — Loopra 能力与加载指南

你正在 Loopra 中执行任务。本技能提供能力导航与加载流程；实际可用能力由当前会话的工具定义、配置、权限和工具返回决定。下面列出的能力可能因环境或配置而不可用，不能仅凭本文宣称已具备或已完成某项操作。

## 先确认能力，再执行任务

1. 首次处理任务前读取本技能；当前上下文已包含完整内容时无需重复读取。
2. 查看本轮提供的工具定义和技能清单，选择与用户目标匹配的入口。
3. 匹配到技能后，先用 `skillread` 读取完整规约，再按要求读取配套文件、检查环境并执行。
4. 缺少能力时，按下方扩展流程检查安装目录、连接状态和启用配置。读取说明不等于工具已注册、依赖已安装或外部服务已连接。
5. 工具返回失败或功能不可用时，如实说明原因，并根据结果继续排查；不要猜测工具名、参数或成功状态。

## 技能：发现、读取与刷新

Loopra 的技能是包含 `SKILL.md` 的目录，可以带有 `references/`、`scripts/`、`assets/` 等配套文件。技能描述提供发现入口，正文提供执行规约。

| 来源 | 位置 | 技能完整标识示例 |
| --- | --- | --- |
| 内置 | 程序 JAR 内的 `loopra/skills/`，只读、随版本更新 | `@builtin-skills/self-skill` |
| 用户 | `~/.loopra/skills/<技能目录>/SKILL.md` | `@loopra-skills/example` |
| 用户通用 | `~/.agents/skills/<技能目录>/SKILL.md`，默认读取的通用挂载区 | `@agents-skills/example` |
| 当前项目 | `<项目根目录>/.loopra/skills/<技能目录>/SKILL.md` | `@project-skills/example` |

- 本技能的读取方式：`skillread(name="@builtin-skills/self-skill")`。
- 技能较少时，系统提示中直接提供名称和描述；先匹配清单，再调用 `skillread(name="清单返回的完整标识")`。
- 本轮存在 `skilllist` 时，可用它查看清单；存在 `skillsearch` 时，可用 `skillsearch(query="关键词")` 搜索。工具会随技能数量调整，不要调用本轮未提供的工具。
- 新增、删除或更新用户/通用/项目技能后，调用 `skillrefresh` 重新扫描，并查看它返回的最新目录或搜索提示。刷新只更新技能目录，不会安装运行环境或重建 MCP 连接。
- 不同来源的同名技能相互独立。始终使用清单返回的完整标识，明确读取哪个来源，不要凭名称推断优先级或覆盖关系。
- 读取配套文件时，以 `skillread` 返回的资源路径和别名为准；可用 `read` 读取说明文件。执行脚本前先检查技能要求和当前运行环境，按工具支持的路径方式调用。
- 安装普通技能时，将整个技能目录放到用户级、用户通用或项目级目录，保留配套文件；也可通过设置中的技能市场安装到 `~/.loopra/skills`，再刷新。内置技能由程序提供，无需复制到用户目录。

## 常见能力入口

以下仅是导航。只使用本轮实际提供的工具，并遵循各工具当前的参数定义。

| 任务 | 能力入口与使用方式 |
| --- | --- |
| 阅读、搜索与编辑项目文件 | `read`、`rg`、`write`、`edit`；`rg` 使用程序内嵌的原生 ripgrep，无需安装；修改前先理解现有内容 |
| 运行命令与验证结果 | 使用环境提示中的实际 shell 工具：`powershell`、`CMD`、`bash` 或 `sh`；通过 `cwd` 指定项目内工作目录，`max_char` 控制返回字符数，`timeout_ms` 指定毫秒级超时；交互或长时间运行时用同名前缀的 `_start`，再以 `_wait` / `_stdin` / `_stop` 管理返回的会话。命令必须使用对应 shell 的语法 |
| 获取网页或检索资料 | `web`：`action=search` 做实时网页搜索，`action=code` 查库、SDK 和 API 文档，`action=fetch` 读取指定 URL 并转成 Markdown；登录、验证码等人工步骤通过 `browser_request_user_action` 请用户接管（若该工具可用） |
| 计划、步骤清单与长期目标 | 根据任务使用 `submit_plan`、`checklist_*`、`goal_*` 等当前提供的工具；遵守当前计划模式和状态约束 |
| 项目长期记忆 | `memory`，先检索已有事实，再按需记录可靠且可复用的信息 |
| 子任务与共享上下文 | 使用当前子代理工具；`workspace_read` / `workspace_write` / `workspace_list` 是代理间共享通道，与项目文件系统不同 |
| 外部服务与业务接口 | 按 MCP 或 OpenAPI 网关当前提供的工具和发现规范操作，见下文 |

## rg：搜索内容与文件路径

- 只有查看目录结构时才用当前 shell：PowerShell `Get-ChildItem`、CMD `dir`、macOS/Linux `ls` 或 `find`。枚举或统计文件请用 `rg` 的 `files` 模式。旧 `ls`、`glob`、`grep` 工具已删除，不要再调用。
- 大型仓库中不要用 `Get-ChildItem -Recurse -Include ... | Where-Object ...` 或逐文件 `Get-Content`/`Measure-Object`/`Select-String` 做统计：`Where-Object` 是遍历后才过滤，递归枚举加上逐文件读取可能要几十秒；同样的文件数、行数、匹配数用 `rg` 通常不到一秒。
- shell 工具默认最多返回 64000 个字符（交互工具为 8000），一次性命令默认超时 120000 毫秒，交互等待默认 8000–10000 毫秒；所有超时参数统一用 `timeout_ms`，上限 3600000。返回 `truncated=true` 且文本带截断提示时，不代表拿到了完整输出；可增大 `max_char` 或缩小命令输出范围。一次性命令返回 `status=timed_out` 表示进程树已被终止；交互工具的 `timeout_ms` 只限制本次等待，不终止会话。
- 内容搜索：`rg(pattern="func\\s+New", globs=["*.go"], context_lines=2)`。默认 `mode="content"`，返回文件名、行号及原文。JSON 中反斜杠要转义，不要添加 shell 引号；不要写 HTML 实体（`&lt;`、`&gt;`、`&amp;`），XML 标签直接写 `<version>`，否则会按字面文本匹配。
- 文件路径查找：`rg(mode="files", globs=["**/*controller*.go","!**/*_test.go"])`，不要提供 `pattern`。这是原生 `rg --files`，不是目录列表。
- 根据内容筛选文件：`rg(mode="files_with_matches", pattern="TODO|FIXME")`，这是原生 `rg -l`，每个匹配文件只返回一次。
- 搜索代码原样片段时设置 `fixed_strings=true`；需要环视或反向引用时设置 `perl_regexp=true`，两者不能同时使用。默认正则为区分大小写的 Rust/Unicode 正则。
- `path` 默认项目根，`globs` 使用 `/`，`!` 表示排除，最后匹配规则优先；显式正向 glob 可以覆盖 ignore/隐藏规则。`hidden` 和 `no_ignore` 独立，按需开启。
- 默认输出最多 200 行、64 KiB，`max_results` 上限 1000。`truncated=true` 表示搜索被主动停止，不代表已遍历完整项目；应缩小 `path`/`globs`/`pattern`，或用 `read` 读取目标文件。
- `matched=false`、`exit_code=1` 是正常的无结果；非法正则、超时等会返回工具错误。`rg` 的完整参数和示例始终以本轮工具定义为准。

## MCP：连接外部工具

- 用户级配置位于 `~/.loopra/mcp-servers.json`；项目级配置位于 `<项目根目录>/.loopra/mcp-servers.json`，仅作用于对应项目。
- 可在设置中管理 MCP；项目能力面板可查看项目 MCP 的连接状态、工具列表并刷新。
- 项目配置变更后，如果本轮有 `mcprefresh`，可调用它登记刷新。本轮回复结束后才会重建连接，从下一条消息起使用新工具；不要在登记后立即宣称已连接成功。
- 已直接暴露的 MCP 工具按其 Schema 调用。网关折叠工具时，遵循当前网关说明：按需使用 `search_tools` 搜索、`get_tool_detail` 获取参数 Schema，再通过 `call_tool` 调用。仅使用当前实际提供的这些入口。
- 能力未出现时，检查是否配置、启用、连接成功，以及是否需要刷新。`skillrefresh` 不负责连接 MCP；读取某个技能也不会自动连接它引用的服务器。

## OpenAPI 与插件

- OpenAPI：启用 OpenAPI 插件，在其设置菜单配置接口源；依次使用 `search_apis`、`get_api_detail`、`call_api` 发现、读取参数并调用。实际执行遵循当前审批策略，插件停用时这些工具不可用。
- 插件：在设置 → 插件填写 npm 包名或 GitHub 地址。插件是 JavaScript 或 TypeScript 模块，由 moejs 执行，可以是 async。`export function` 会变成工具；也可以导出 `tools()` 与 `call()`。同一模块还可以导出 `turnBefore`、`systemPrompt`、`llmRequest`、`llmResponse`、`toolBefore`、`toolAfter`、`compact`、`turnAfter`，用来改写这一轮的消息、系统提示词、模型请求或工具参数。`fetch` 可以访问本进程能到达的地址；`node:fs` 可以读写本机文件。入口优先是 package.json 的 `loopra` 字段。安装后确认插件已启用，并且当前会话的工具列表里出现 `<插件 id>__<工具名>`。只读工具会自动放行，写入工具仍走审批。`toolBefore` 返回 `allow` 不会跳过审批。
- 缺少扩展时，先说明需要哪个扩展、它解决什么问题，再依用户任务范围安装或配置。不能把此说明中的示例当作已安装能力。

## 能力缺失时的检查顺序

1. 当前工具定义中是否已有合适工具，或网关是否提供了发现入口？
2. 技能是否存在于正确来源，是否使用了目录返回的完整标识，是否需要 `skillrefresh`？
3. MCP、OpenAPI 或插件是否配置、启用并加载成功，是否仍在等待下一轮刷新？
4. 技能引用的命令、依赖、凭据或外部服务是否满足环境要求？
5. 根据实际检查结果说明已完成的步骤、失败原因和仍需的用户操作。