用 Codewhale plugin-creator 技能搭建本地插件 Bundle清单、Skill 与信任流程实战【免费下载链接】CodewhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/Codewhale本篇技术指南围绕 Codewhale 内置的plugin-creator技能crates/tui/assets/skills/plugin-creator/SKILL.md展开讲解如何在终端中从零搭建一个本地 Codewhale 插件 bundle包括plugin.toml版本化清单的字段语义、Skills 与 MCP 服务器的命名空间与声明约束、/plugin命令族的校验-审查-信任-启用全流程以及为什么 bundle 默认处于 untrusted/disabled 状态。读完本文你将能够独立创建、校验、审查并启用一个安全的本地插件 bundle并理解 Codewhale 插件加载器有界装载、显式信任的底层机制。插件加载器的边界v0.9.1 的有界装载模型Codewhale v0.9.1 的插件加载器是**刻意有界deliberately bounded**的一个被信任且启用的 bundle只能通过既有引擎向 Codewhale 添加两类声明式组件声明式 Skills以SKILL.md形式挂载的、可被 Agent 调用的技能文档MCP 服务器通过既有 MCP 引擎接入的 stdio 或远程服务。其他组件类型命令、子代理、钩子、LSP、原生扩展、文件系统根、生命周期变更在当前构建中仅作清单登记inventory-only不会被执行。这一边界同时存在于命令面和源码策略中在 crates/tui/src/plugins/activation.rs 中PluginActivationPolicy::current()激活策略版本 v3把Skills、McpStdio、McpRemote以及声明式的Commands、Agents、Hooks列为受支持适配器而Lsp、Native、FilesystemRoots、LifecycleMutation明确列为 inactive激活策略还通过capability_hash把这份策略本身绑定进信任凭证未来任何一次适配器策略变更都会让旧的信任凭证以CapabilitiesChanged方式失败关闭fail closed。从源码结构看这意味着插件系统的安全模型是最小可执行面 显式审查你能装进去的东西不多但每一样都会被严格校验、逐项审查后才可能生效。第一步选择 Bundle 归属位置与命名按plugin-creator技能的工作流首先选择一个 Codewhale 拥有的位置存放 bundle二选一用户级 bundle~/.codewhale/plugins/plugin-name/对所有工作区生效工作区级 bundleworkspace/.codewhale/plugins/plugin-name/仅对当前工作区生效。随后将 bundle 名称规范化为小写连字符形式lowercase hyphen-case。这不是风格建议而是硬性校验规则在 crates/tui/src/plugins/manifest.rs 的validate_plugin_name中名称必须为 164 个字符只能由小写 ASCII 字母、数字和内部连字符组成且首尾字符不能是连字符plugin.jsonAgent Plugins v1.0.0 格式清单则额外允许内部点号但禁止--与..。从源码看PluginManifest支持plugin.tomlCodewhale 原生/遗留格式与plugin.json 兄弟文件mcp.jsonAgent Plugins 标准格式以及 Kimi 兼容格式三种编码解析后统一为同一个PluginManifest结构。plugin-creator技能采用最直接的plugin.toml方式。第二步编写版本化清单 plugin.toml在 bundle 根目录创建plugin.toml。技能给出了最小可运行骨架schema_version 1 [plugin] name my-plugin version 0.1.0 description What this bundle provides [skills] path skills结合 crates/tui/src/plugins/manifest.rs 中PluginManifest/PluginMeta的结构体定义我们可以把这份清单的字段语义完整展开字段位置含义与约束schema_version顶层当前支持的最高版本为1CURRENT_SCHEMA_VERSION声明超过上限会报错。缺省会被视为遗留清单/plugin validate会提示补写schema_version 1[plugin].name插件元信息bundle 名称规则同上小写连字符[plugin].version插件元信息必须是合法SemVer如0.1.0Version::parse校验失败即报错遗留清单缺失版本时显示0.0.0并告警[plugin].description插件元信息可选最长 1024 字符不含控制字符与双向排版字符[plugin].author插件元信息可选最长 256 字符[plugin].display_name插件元信息可选当发布用name因标准名规则被 slug 化时保留人类可读名[plugin].homepage/repository/license/keywords插件元信息可选分别有长度上限homepage/repository 2048、license 128、keyword 128 且去重[skills].path组件路径指向 Skill 目录相对 bundle 根也可用paths数组把同一种组件拆到多个目录[commands]/[agents]/[hooks]/[lsp]/[native]组件路径声明式组件位置结构与[skills]相同path/paths[mcp_servers.name]MCP 服务器见下文专节[capabilities]能力声明filesystem_roots、network_hosts、lifecycle_mutation仅登记不执行[when]宿主条件os支持windows/linux/macos/freebsd/openbsd/netbsd/android/ios与binaries裸可执行名禁止路径分隔符与 Windows 绝对路径仓库自带了一个真实样例 crates/tui/assets/plugins/rust-toolkit/plugin.toml展示了author与[when]的用法[plugin] name rust-toolkit description Rust development toolkit with cargo check integration version 0.1.0 author Codewhale Team [skills] path skills [when] os [windows, linux, macos] binaries [cargo]注意组件路径必须是相对路径禁止绝对路径、禁止..逃逸、禁止穿越符号链接resolve_contained_path会逐级做symlink_metadata检查并canonicalize后确认仍位于 bundle 根内。清单本身也必须是普通文件而非符号链接大小上限 1 MiB。第三步挂载 Skill 并理解命名空间把每个 Skill 放到skills/skill-name/SKILL.md。Codewhale 会将其暴露为my-plugin:skill-name这种带命名空间的限定名称绝不会作为不带前缀的裸命令出现。这一点同样有源码支撑在 crates/tui/src/commands/groups/skills/skills.rs 中/skills inspect会输出技能的source与插件来源plugin provenance让用户一眼看出某个 Skill 究竟来自哪个 bundle而非全局命令空间。这样的设计带来两个实际收益一是避免不同 bundle 之间的技能名冲突二是让信任边界清晰——你启用的是某个插件带来的技能审查对象始终指向明确的来源。第四步声明 MCP 服务器仅当确实需要只有 bundle 确实需要既有 MCP 引擎时才添加[mcp_servers.name]。Codewhale 对 MCP 声明的校验异常严格全部实现在 crates/tui/src/plugins/manifest.rs 的validate_mcp_servers中并且把 stdio 与远程两类服务器区分管理因为它们在审查界面上的威胁模型不同。stdio MCP本地子进程[mcp_servers.my-tool] command bin/my-tool # 必须是裸可执行名或 bundle 内的相对路径 args [--config, config.json] env { API_KEY ${MY_API_KEY} } # 只允许精确的 ${SOURCE_ENV} 引用 cwd . enabled true required false核心约束command与url二选一必须恰好声明其一stdio 服务器不得声明远程传输或鉴权字段transport、headers、env_headers、bearer_token_env_var、scopes、oauth等全部禁止args禁止绝对路径、禁止..逃逸出 bundle 根且不得内嵌字面量凭据——源码会对token、api-key、secret等敏感键名及sk-、ghp_、AKIA等凭据形态做启发式拦截并要求改为经审查的环境映射env的值只允许精确的${SOURCE_ENV}引用exact_environment_placeholder会要求字符串严格形如${VAR}不允许字面量秘密、不允许拼接表达式其余限额args≤ 64、env≤ 64、enabled_tools/disabled_tools各 ≤ 256超限报错。远程 MCPHTTP/HTTPS[mcp_servers.remote-api] url https://api.example.com/mcp transport sse # 显式设置时只接受 sse env_headers { Authorization ${AUTH_TOKEN} } bearer_token_env_var AUTH_TOKEN enabled true核心约束URL 必须使用HTTPS或仅当目标是localhost/回环地址时才允许明文 HTTPURL禁止内嵌用户信息userinfo/password、查询参数与 fragment禁止字面量headers鉴权一律走env_headers环境变量名来源或bearer_token_env_var远程服务器不得声明cwd、args、env等 stdio 专属字段OAuth 字段当前被禁用报错提示改用环境变量鉴权[capabilities].network_hosts必须精确等于所有远程 MCP 端点归一化后的主机集合——源码会取出每个 URL 的 host 做规范化转小写、拒绝带端口/路径/凭据的主机串与声明值逐一比对不一致直接校验失败清单中任何位置都不得出现凭据无论是 URL 内嵌、字面量 header 还是参数值一律以经审查的环境变量引用方式注入。第五步其他组件类型——只登记、不激活如果 bundle 需要声明命令、代理agents、钩子hooks、LSP、原生扩展、文件系统根或生命周期变更plugin-creator技能的原则是仅在为未来工作做清单登记时声明它们。Codewhale 会把它们显示为 inactive未激活同时仍然激活同一 bundle 中受支持的 Skills 与 MCP——即混合 bundle 部分激活。从 crates/tui/src/plugins/manifest.rs 的PluginInventory::compatibility()可以看出三种兼容性结论full所有声明面都有适配器或 bundle 为空——可完整激活partial支持适配器可激活其余声明面保持 inactive——可部分激活unsupported只声明了当前构建无法激活的面如仅含 LSP/原生扩展——该 bundle 无法被启用。这就是技能中只声明那些不受支持表面的 bundle 不能被启用的源码依据can_activate_supported_components()在兼容性为unsupported时返回 false/plugin enable会直接拒绝。第六步校验、审查与信任——先 validate再 trust后 enableplugin-creator技能规定了一个不执行 bundle 内容的校验与审查流程全部命令由 crates/tui/src/commands/groups/plugins/mod.rs 的/plugin分发器实现/plugin validate plugin-name # 校验清单与组件报告 warning/error 诊断 /plugin show plugin-name # 查看 bundle 详情组件、能力、兼容性、哈希 /plugin enable plugin-name # 打开内容/能力审查界面未信任时 /plugin trust plugin-name token # 运行审查后给出的精确确认命令 /plugin enable plugin-name # 再次启用几个关键机制值得展开审查令牌绑定完整哈希review_token()生成的确认令牌形如content_hash.capability_hash——content_hash是对整个 bundle含所有文件字节与可执行位的 SHA-256capability_hash则把激活策略与能力清单一起哈希。用户必须逐字运行界面给出的精确确认命令而不是拍脑袋输入任何文本trust 只登记、不激活从 crates/tui/src/plugins/registry.rs 的trust()实现看信任操作会先把 bundle 内容**暂存stage**为运行时快照写入TrustReceipt含两个哈希、被审查能力清单、审查时间并记录进 review history关键点entry.enabled false被强制置位——即使旧状态曾启用重新审查后也绝不会隐式重新激活enable 需要完整前置条件enable()依次检查——已受信任、存在已验证的运行时快照staged、[when]条件适用于当前宿主、且至少有一个受支持的声明组件。任何一项不满足都会报错enable 立即重建目录启用成功后会立即重建当前工作区的 Skill/MCP 目录AppAction::PluginRegistryChanged无需重启或手动刷新。最后用以下命令做闭环验证/skills inspect # 检查 Skill 的插件来源plugin provenance /plugin list # 检查预期的信任与激活状态若 bundle 内容在信任后被更新/plugin update其内容哈希必然变化旧信任凭证不再匹配——必须重新走审查 → trust → enable流程这正是内容即身份哈希设计的自愈机制。安全基线默认 untrusted、默认 disabled每个用户级与工作区级 bundle 在创建之初都是未信任且未启用的。plugin-creator技能最后明确划定了 v0.9.1 的功能边界不要添加 marketplace市场、下载器、更新器、兼容性扫描、可执行扩展运行时或自动信任流程这些表面surface超出 v0.9.1 范围不应出现在 bundle 设计中。这一约束与整个插件信任模型一脉相承能力边界刻意收窄信任必须显式、逐次、绑定内容哈希杜绝任何装上即运行或自动放行的路径。对需要更强的插件分发、更新或自动化的场景应等待 Codewhale 后续版本对相应适配器与流程的正式支持而不是绕过审查机制自行扩展。小结借助内置的plugin-creator技能搭建 Codewhale 本地插件 bundle 的完整路径可以归纳为四步定位置与命名 → 写版本化plugin.toml→ 挂载命名空间 Skills / 声明受约束的 MCP → 用/plugin命令族完成 validate → show → trust → enable 的显式审查闭环。整个过程由 crates/tui/src/plugins/manifest.rs 的清单校验、crates/tui/src/plugins/activation.rs 的激活策略、crates/tui/src/plugins/registry.rs 的信任状态机共同保障内容以 SHA-256 绑定身份能力以策略哈希防漂移信任与激活彻底分离最终让可扩展性与可审计性在同一个有界加载器内达成平衡。【免费下载链接】CodewhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/Codewhale创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考