Release check-平芜编程栈

人工智能
AI Agent
交互助手
工具调用
MCP Clients
本地部署
Agent 工作流
RAG

【免费下载链接】zeroclaw

Fast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 🦀

项目地址：https://gitcode.com/gh_mirrors/ze/zeroclaw

点击查看免费下载

Review the release notes, changelog, version tags, and migration notes before confirming that a release is ready.

这里有几个关键约定： - **目录名即技能名**； - 当没有 frontmatter description 时，ZeroClaw 把正文中第一个非标题段落作为 description； - `skills add` / `edit` 的写入路径与运行时加载路径由同一个 [SkillsService](https://link.gitcode.com/i/976876b8903f0926d8a86f4f3519c688) 解析，杜绝“创建了却加载不到”的漂移问题。 ### frontmatter 元数据 `SKILL.md` 支持简单的 YAML frontmatter： ```markdown --- name: release-check description: Check release readiness before tagging version: 0.1.0 author: zeroclaw_user tags: [release, docs] --- # Release check Review the release notes, changelog, version tags, and migration notes before confirming that a release is ready.

支持的 frontmatter 字段为：name、description、author、version、tags、always、slash_options。源码层面的字段定义见 frontmatter.rs 的SkillFrontmatter结构体（还额外支持license与category）。其中description是 skill 发现的关键：它会被注入系统提示词，因此应当以第三人称写明“技能做什么、何时使用”。SkillFrontmatter::prop_fields()提供了完整的字段规格表，含必填标记、类型与说明（见 frontmatter.rs）。

always: true 与安全策略技能

always: true会让技能的完整指令在compact 技能提示词模式（该模式下其他技能只保留摘要、指令按需通过read_skill加载）中依然完整内联在系统提示词里，默认值为false。它应当保留给策略类或安全关键型技能，而不是发布检查这类常规工作流技能：

--- name: security-policy description: Non-negotiable safety rules the agent must follow every turn. version: 0.1.0 author: zeroclaw_user tags: [policy] always: true --- # Security policy Never exfiltrate secrets, never disable audit logging, and always ask for approval before touching production credentials.

always字段在Skill结构体与 frontmatter 中均有对应（mod.rs），它的底层语义是“系统提示词中始终可见”，而非隔离边界。

创建 TOML 技能（SKILL.toml）

当技能需要结构化提示词或工具定义时，使用SKILL.toml。[skill]表要求name与description；version缺省为0.1.0；author、tags、prompts、always可选（always默认false）。工具条目可使用kind = "shell"、kind = "http"或kind = "script"，工具描述要窄而具体，让模型能准确判断何时调用。

从源码看，SkillTool（mod.rs）支持shell/http/script/builtin/mcp五种 kind：builtin通过target委托给内置工具，mcp通过target引用{server}__{tool}格式的 MCP 工具（如images__generate）；shell/script可通过timeout_secs设置超时上限（默认回退到SKILL_SHELL_TIMEOUT_SECS的 60 秒，长任务如构建流水线应显式调大）。

HTTP 工具还有一套严格的出网约束：只允许http/httpsURL；参数在插入前做百分号编码；禁用重定向与环境代理；解析后的目标地址必须通过 ZeroClaw 的公网 egress 策略，私有或元数据目标被拒绝；响应体超过 1 MB 会被截断，防止撑爆运行时内存。

Slash 命令选项与本地化

带有slash标签的技能会作为聊天频道的斜杠命令浮出（例如 Discord 上的/search）。它可以声明类型化的[[skill.slash_options]]；未声明任何选项的技能回退为单个必填自由文本输入。命令描述与每个选项描述都支持description_localizations映射（按 locale code 键控）；未知或不支持的 locale code 会被丢弃并告警，而不会阻塞命令注册——所以一个拼写错误永远不会卡死注册流程：

[skill] name = "search" description = "Search the web" tags = ["slash"] # Localized command descriptions, keyed by locale code. description_localizations = { fr = "Rechercher sur le web", ja = "ウェブを検索" } [[skill.slash_options]] name = "query" description = "The search query" type = "string" required = true # Localized option descriptions, same form. description_localizations = { fr = "La requête de recherche" }

SkillSlashOption在源码中完整支持 8 种类型：string、integer、number、boolean、user、channel、role、mentionable（见 mod.rs 与SlashOptionKind）。类型能力上有明确规则：choices仅适用于 string/integer/number；min/max数值边界仅适用于 integer/number；min_length/max_length仅适用于 string。该模型仿照 Discord Application Command Option 建模但保持频道无关，斜杠能力频道会自行映射到其线格式。这些能力信息由slash_option_kinds()以描述符形式发布给 API 表面与 Web 控制台（mod.rs）。

管理已安装技能：CLI 全命令参考

列出与审计

# 列出完整库存 zeroclaw skills list # 精确列出某个 agent 运行时实际加载的技能 zeroclaw skills list --agent default # 直接列出某个 bundle zeroclaw skills list --bundle ops # 审计一个已安装技能或本地技能目录 zeroclaw skills audit release-check zeroclaw skills audit ./release-check

skills list --agent default展示的是该 agent 的effective skill set——这是诊断“技能装了但 agent 没用起来”的第一入口。SkillsService::resolve_effective_skills会合并工作区技能与所有已配置 bundle 技能，并携带来源标注（SkillOrigin::Workspace / OpenSkills / Plugin / Bundle）与“被遮蔽”（shadowed）信息：同名技能存在时，工作区技能优先于 bundle 技能（first-write wins），失败方会被记录为 shadow（见 service.rs 与相关测试 service.rs）。审计结果还会区分“没有任何技能配置”（skills 与 dropped 均为空）与“全部技能审计失败”（skills 空、dropped 非空）两种状态，便于控制台给出精确提示。

安装技能

# 从本地目录安装 zeroclaw skills install ./release-check --bundle ops # 从 Git URL 安装 zeroclaw skills install https://example.com/zeroclaw-release-check.git --bundle ops # 安装到指定 agent zeroclaw skills install release-check --agent default # 从 Git 目录仓库按名安装（仓库技能位于 skills/<name>/） zeroclaw skills install https://github.com/vercel-labs/skills --skill find-skills

安装目标优先级（自高到低）：

显式--bundle <alias>；
目标 agent 唯一分配的 bundle——--agent <alias>选择目标 agent，缺省时使用当前运行 agent；
全局目录<install>/data/skills/。

注意：如果目标 agent 配置了多个 bundle，必须显式传--bundle，否则目标不明确；如果回退到全局目录，技能会被安装并列出，但没有 agent 会自动加载它——需要把它挂到 bundle 上才可在运行时生效。源码中的解析逻辑见 src/skills/mod.rs。

卸载技能

zeroclaw skills remove release-check --bundle ops zeroclaw skills remove release-check --agent default

从 bundle 中移除会归档技能目录以便恢复；从全局目录移除则会在既有的路径包含检查通过后彻底删除全局副本。归档目标为<install>/shared/skills/_deleted/<bundle>-<name>-<unix-ts>/，对应RemoveMode::Archive（见 constants.rs 与 service.rs）。源码还实现了可编辑性守卫：只允许写/删 bundle 技能，对工作区等非 bundle 来源的技能目录（无清单）会返回NotEditable而非误导性的NotFound，相关测试见 service.rs。

测试技能

# 测试单个技能（运行其 TEST.sh） zeroclaw skills test release-check # 测试所有已安装技能，详细输出 zeroclaw skills test --verbose

zeroclaw skills test会在技能存在TEST.sh时运行它。安全提醒：运行来自不信任来源的技能测试前，务必先检查TEST.sh的内容——这与下述脚本审计策略一脉相承。

技能可见但 agent 未使用怎么办

如果zeroclaw skills list显示了某个技能但 agent 没有使用它，先看运行时视图：

zeroclaw skills list --agent default

当技能只出现在 global 分组时，把它安装进一个 bundle，并确保 agent 配置中的agents.<alias>.skill_bundles列出了该 bundle。

想了解如何把内置工具改造成可复用的运维工作流，可参考使用关系记忆的技能模板。

脚本安全：默认拦截与显式放行

ZeroClaw 在加载或安装技能前会先审计技能目录。类脚本文件（.sh、.bash、.ps1以及带 shell shebang 的文件）默认被拦截。如果你确实要使用带脚本的技能，需开启skills.allow_scripts；在信任技能来源并审查过脚本内容之前，请保持该选项关闭。

源码实现非常严谨（audit.rs）：当allow_scripts为 false 且检测到不支持的脚本文件时，审计报告会标记scripts_blocked，加载器会跳过该技能目录并给出可操作的修复提示（Set skills.allow_scripts = true ...，见 mod.rs）。脚本识别基于文件后缀（.sh、.bash、.zsh、.ksh、.fish、.ps1、.bat、.cmd）或前若干字节的 shebang 行解析。相关的read_skill测试也验证了allow_scripts = true时带configure.sh的技能可以正常返回（read_skill.rs）。

Python 特定执行模式、解释器策略以及 native 与 Docker 的取舍，参见运行 Python 技能。

加载社区技能

社区 open-skills 加载是**可选（opt-in）**的，通过skills配置开启。开启后，ZeroClaw 从配置的open_skills_dir加载技能；未设置目录时使用$HOME/open-skills。如果该目录不存在，ZeroClaw 可能克隆社区 open-skills 仓库；如果目录已存在且是 git checkout，则可能拉取更新（源码常量OPEN_SKILLS_REPO_URL、同步标记与 7 天同步间隔见 mod.rs）。仅对信任的社区来源开启此功能，或将open_skills_dir指向经过审查的本地副本。从社区加载的技能会被打上open-skills标签并默认作者归为besoeasy/open-skills（mod.rs）。

高级配置：提示词注入模式

默认的提示词注入模式是full——把完整技能指令放进系统提示词。设置为compact（全局或运行时 profile 中）后，普通技能只在上下文中保留元数据，指令通过read_skill按需加载（read_skill工具的实现见 read_skill.rs：按名精确匹配技能并读取其源文件，未知技能会返回可用技能名列表）。标记always: true的技能在 compact 模式下仍保留完整指令。

[skills] prompt_injection_mode = "compact" # 或 "full"（默认）

需要特别强调的是：compact 模式减少的是提示词体积，它不是针对不可信技能来源的隔离边界。配置结构上，[skills]段的prompt_injection_mode字段定义于 schema.rs，且运行时 profile 可覆盖全局值（见 schema.rs）。

自主技能创建：从执行痕迹到可复用技能

在一次成功的多步任务（至少两次工具调用）之后，ZeroClaw 可以把这次执行持久化为可复用技能。此功能默认关闭，需显式开启：

[skills.skill_creation] enabled = true # off by default max_skills = 500 # LRU cap: oldest auto-generated skill is evicted past this similarity_threshold = 0.85 # embedding-dedup cutoff; near-duplicate tasks are skipped

默认情况下，每个被创建出来的技能都是确定性的SKILL.toml，直接由工具调用痕迹生成，不涉及任何模型调用。max_skills是 LRU 上限，超过后最旧的自动生成技能被逐出；similarity_threshold是嵌入去重阈值，描述过于相似的任务会被跳过。配置的完整字段与默认值见 schema.rs。

Reflection（SKILL.md 综合）

开启 reflection 后，ZeroClaw 改为让 agent 配置的模型提供商从一段有界的执行切片（任务描述、工具调用痕迹、最终答案）综合出规范的SKILL.md。每个输入都独立截断到配置的字符预算，确保再大的执行也绝不会产生无界的 reflection 请求：

[skills.skill_creation] enabled = true reflection_enabled = true # opt-in; requires enabled = true max_task_chars = 1000 # task description budget max_tool_trace_chars = 4000 # tool-call trace budget max_final_answer_chars = 2000 # final assistant answer budget