DeepCode 本地插件Local Plugins完整指南Agent Plugins 1.0 包格式、CLI 生命周期与安全模型【免费下载链接】DeepCodeDeepCode: Open Agentic Coding (Agent Harness Loop Engineering Multi-Agent Orchestration)项目地址: https://gitcode.com/GitHub_Trending/deepc/DeepCode本文以 docs/LOCAL_PLUGINS.md 为核心脉络结合 DeepCode 仓库中 cli/plugin_cli.py、core/plugins 与 tests/test_plugins.py 的源码实现系统讲解本地插件的包格式、注册表、运行生命周期与安全边界。读完本文你将掌握如何编写符合 Agent Plugins 1.0 规范的插件包、通过deepcode plugin命令注册与管理本地插件并理解插件 Skills 与 MCP 组件如何在 Session 中安全生效。一、定位Plugin 是 Skill 生态的可选扩展而非替代品在 DeepCode 中Skill 始终是一等资源first-class resource。它可以独立存在于.agents/skills、~/.agents/skills或受支持的兼容根目录下拥有完整的独立生命周期。Plugin 则是一个可选打包单元其作用是向同一个 Skill 目录catalog贡献额外的 Skills——它不会取代独立 Skill 的存在方式。Standalone Skill ─┐ ├── SkillCatalog → SkillRuntime Plugin Skill ─────┘这一设计的直接推论是本地 Skills 的优先级规则当 Plugin 贡献的 Skill 与本地 Skill 同名时本地 Skill 保持优先Plugin 中的同名副本不会覆盖正在生效的本地工作流而是以shadowed遮蔽元数据的形式继续可见。在 tests/test_plugins.py 的test_standalone_and_plugin_skills_share_catalog_with_local_precedence中可以验证这一行为同名plugin-review的记录 authority 为本地LOCAL_SKILL_AUTHORITY而 Plugin 副本的状态为SkillStatus.SHADOWED且shadowed_by指向本地记录的 ID。二、支持的包格式Agent Plugins 1.0.0DeepCode 目前识别Agent Plugins 1.0.0规范并采用固定 Skill 目录的布局约定review-tools/ ├── plugin.json ├── skills/ │ ├── review/SKILL.md │ └── verify/SKILL.md └── mcp.json # optional Agent Plugins 1.0 MCP component2.1 最小 manifest最小的plugin.json只有两个必填字段{ $schema: https://agent-plugins.org/schemas/1.0.0/plugin.schema.json, name: review-tools }version与description为可选元数据源码中还可选author、homepage、repository、license、keywords、extensions。不存在任何实验性的 DeepCode manifest 回退方案$schema必须精确标识 Agent Plugins 1.0.0。在 core/plugins/formats/agent_plugins_v1.py 中定义常量AGENT_PLUGIN_SCHEMA解析器 core/plugins/resolver.py 仅通过该 schema 值选择适配器其余 schema 一律抛出Unsupported Agent Plugins schema错误。2.2 manifest 名称规则name字段受正则约束见 core/plugins/formats/agent_plugins_v1.py^(?!.*(?:--|\.\.))a-z0-9?$即164 个字符仅允许小写字母、数字、点号与连字符必须以字母数字开头和结尾且不得包含..与--子串。违反规则的包会被整体判定为无效。2.3 未知字段与 extensions未知 manifest 字段解析器会逐个报告agent_plugins.unknown_manifest_field诊断WARNING 级别并忽略不会导致解析失败。未知extensions命名空间作为不透明数据保留仅记录命名空间名称DeepCode 不校验其内容——这符合 Agent Plugins 规范禁止客户端校验扩展内容的要求见 core/plugins/formats/agent_plugins_v1.py 与 tests/test_plugins.py 的验证用例。2.4 Skills 的发现规则Skills只从固定skills/目录的直接子目录发现manifest 中不会也不允许列出 Skill 路径。发现算法见 core/plugins/formats/agent_plugins_v1.py 与 core/plugins/skill_provider.py要求每个直接子目录下存在可解析的SKILL.md且解析后的路径必须位于插件根目录之内防止符号链接逃逸。skills/SKILL.md这样的根级 Skill 文件不会被加载——只有直接子目录才构成 Skill 候选。2.5 Plugin Skills 的严格契约Plugin 内的 Skills 遵循Agent Skills 契约frontmatter 中的name为必填必须是小写 slug必须与其父目录名完全一致。校验 profile 为SkillValidationProfile.AGENT_SKILLS_V1见 core/plugins/skill_provider.py比独立 DeepCode Skill 使用的兼容性解析器更严格。一个无效的 Skill 会被单独跳过并产生诊断其余 Skills 与组件继续正常加载而独立 DeepCode Skills 保留其原有兼容解析器这套更严格的包边界不会迁移或破坏用户已有的 Skill 目录。测试test_plugin_skills_are_direct_children_and_strictly_validatedtests/test_plugins.py验证了根级 Skill 文件、目录名与声明名不一致的 Skill 均不会进入活动目录。三、mcp.json可选的 MCP 组件mcp.json是 Agent Plugins 1.0 的可选组件DeepCode独立于 manifest 与 Skills 对其进行校验。合法的组件可以向会话级 MCP 运行时贡献三类服务器stdiotype: stdio字段command、args、env、cwdSSEtype: sse字段url、headersStreamable HTTPtype: streamable-http字段url、headers一个合法但含无效条目的示例某个 server 声明非法该条目被独立跳过并生成agent_plugins.invalid_mcp_server诊断不会禁用其他合法条目更不会使该 Plugin 的有效 Skills 失效见 tests/test_plugins.py。从源码看core/plugins/mcp.py 的校验远比表面严格mcp.json最大 256 KBMAX_MCP_CONFIG_BYTES且只允许$schema与mcpServers两个顶层键重复 JSON 键含env、headers内部的重复键一律拒绝stdiocommand必须是裸命令名或以./开头的包内相对路径不允许占位符展开且不能越出插件根目录cwd默认${PLUGIN_ROOT}仅允许./、${PLUGIN_ROOT}、${PLUGIN_DATA}三种前缀HTTP(S) URL 必须是绝对地址且不得内嵌用户名/密码或 fragment非 loopback 地址强制要求 HTTPSheader 名必须合法且大小写折叠后不重复值中禁止 CR/LFstdioenv不得覆盖保留变量PLUGIN_ROOT与PLUGIN_DATAWindows 下大小写不敏感。每个解析出的服务器会被附加默认approvalMode: writes并映射为可移植的运行时 IDplugin_name--server_name最长 80 字符超限或含特殊字符时以 SHA-256 摘要截断保证稳定唯一见 core/plugins/mcp.py。3.1 凭证安全警告[!WARNING]切勿在mcp.json中放置凭证。env与headers的字面量属于纯文本包数据它们可能随 Plugin 被提交、复制或泄露。应通过credentialEnv、bearerTokenCredential或其他受支持的环境引用在运行时从用户配置中绑定密钥。源码对此并非简单放行解析器会以正则扫描env/headers中疑似凭证的字段名与值模式如sk-...、github_pat_...、AKIA...、Bearer token、Authorization、api_key等生成agent_plugins.possible_plaintext_credential警告诊断——只警告字段位置而不回显值本身见 core/plugins/mcp.py。占位符${OPENAI_API_KEY}、runtime-injected、your-...与无嫌疑的名称则不会触发警告测试 tests/test_plugins.py 对这两类情况均有覆盖。四、发现的惰性边界注册 ≠ 执行发现discovery是惰性的列出或注册一个 Plugin 时DeepCode绝不导入 Python 代码、绝不启动任何进程——resolve_plugin只读取并校验 manifest、Skills 元数据与mcp.json文本见 core/plugins/resolver.py 与 core/plugins/host.py 的 docstring。真正的激活发生在Agent Session 首次使用该包时DeepCode 提供不可变的PLUGIN_ROOT指向插件根目录与安装专属的PLUGIN_DATA路径持久化私有数据目录位于注册表同级的data/installation_id下权限受限应用工具过滤tool filters与权限策略之后才启动 MCP 服务器进程。启动失败是非致命的除非用户策略显式将某个服务器标记为必需required否则失败的服务器只产生诊断不会拖垮 Session。五、本地生命周期CLI 操作核心管理命令如下deepcode plugin add ./review-tools deepcode plugin list deepcode plugin disable review-tools deepcode plugin enable review-tools deepcode plugin remove review-tools --yes5.1 命令细节对应 cli/plugin_cli.pyadd path注册本地插件目录。重复注册同名插件或同一目录会报ConflictError路径不存在或不是目录会被拒绝。list列出已注册插件、状态active/disabled/invalid、版本、名称、路径及诊断信息支持--json结构化输出含revision、components明细与 diagnostics。enable|disable plugin_id切换启用状态。选择器既支持plg_...安装 ID也支持插件名见 core/plugins/registry.py 的_select。remove plugin_id [--yes]注销注册。非交互终端必须携带--yes否则会提示确认输出明确说明源文件保留在原位。5.2 注册表与安装标识注册表位于$DEEPCODE_HOME/plugins/registry.json默认~/.deepcode/plugins/registry.jsonadd会分配一个不透明的plg_24位hex安装 IDplg_[0-9a-f]{24}并链接到规范化的源目录——不会复制包内容remove只注销注册记录不删除源目录注册表文件本身以schemaVersion: 1结构写入最大支持 256 个注册项MAX_REGISTERED_PLUGINS写入采用临时文件 fsync 原子os.replace并加文件锁POSIXfcntl/ Windowsmsvcrt与0600权限保护见 core/plugins/registry.py。Desktop 应用同样基于安装 ID在 Plugins 工作区中暴露上述相同操作CLI 与桌面端共享同一注册表与服务层core/application/plugin_service.py。5.3 插件内容的调用入口Plugin Skills沿用普通的/skill、$name、--skill以及 Desktop Composer 调用流程不需要特殊前缀Plugin MCP 工具沿用普通mcp__server__tool的目录catalog、审批approval、超时与取消流程禁用语义禁用某个 Plugin 会使空闲 Session 失效而正在运行的 Turn会持有其不可变的 Skill 与工具快照继续执行完毕不会被中途改写tests/test_plugins.py 验证了这一点。六、用户配置绑定窄化而不替换Plugin 包本身不能嵌入 DeepCode 凭证引用。但用户可以在自己的配置中绑定凭证并缩小某个活动 Plugin 服务器的能力范围——且这种覆盖不会替换包的 command、URL、参数或工作目录{ pluginMcpServers: { review-tools/analyzer: { enabledTools: [inspect], approvalMode: writes, credentialEnv: { SERVICE_API_KEY: { credentialRef: provider:service } } } } }键名格式为插件名/服务器名的策略键plugin_policy_key对服务器名做 URL 编码保证可逆且日志安全见 core/plugins/mcp.pyenabledTools限制可用工具集approvalMode控制写入类操作的审批模式credentialEnv通过凭证引用在运行时注入环境变量替代包内明文。七、安全边界拒绝清单与阶段限制DeepCode 会在解析期拒绝超大或畸形的 manifestplugin.json上限 64 KBUTF-8 且必须为 JSON 对象重复的 JSON 键manifest 与mcp.json均适用不支持的 schema$schema非 Agent Plugins 1.0.0指向包外的符号链接目标manifest、skills/、mcp.json及每个 Skill 文件均做resolve后的relative_to(root)检查authority / package 不匹配如注册后源目录的name被改动。故障隔离是这套安全模型的显著特征无效的包不贡献任何 Skills无效的固定组件skills/或mcp.json与个别无效 Skill 会独立报告在任何情况下独立与捆绑的 Skills 都继续正常工作tests/test_plugins.py 验证了 manifest 损坏不影响本地 Skill。本阶段明确不提供Marketplace、Git 下载、远程更新、签名、回滚、Hook、App或任意 Plugin 代码的 Hook 执行。Plugin 声明在合法mcp.json中的 MCP 子进程属于可执行代码因此只能作为会话能力session capability运行——进程环境最小化且受明确的用户策略约束见 core/plugins/host.py 中 Session 组装时才物化PLUGIN_DATA、交由McpSessionRuntime启动的调用链。八、源码阅读路线图若想深入验证本文结论可按以下路径继续阅读关注点文件包格式解析与 schema 适配core/plugins/formats/agent_plugins_v1.py惰性解析与 manifest 大小/重复键校验core/plugins/resolver.pyMCP 组件解析、凭证扫描与策略键core/plugins/mcp.py注册表持久化与安装 IDcore/plugins/registry.py会话级生命周期快照、监控、MCP 贡献core/plugins/host.pyPlugin Skill 提供者与遮蔽语义core/plugins/skill_provider.py服务层与 CLI 的桥接core/application/plugin_service.py命令行实现cli/plugin_cli.py覆盖上述全部行为的测试套件tests/test_plugins.py适用前提以上行为以当前仓库实现为准。使用deepcode plugin前请确保环境变量$DEEPCODE_HOME默认~/.deepcode可写且插件目录遵循 Agent Plugins 1.0.0 的固定布局引入任何携带mcp.json的第三方插件前务必核对其中env/headers是否存在明文凭证风险。【免费下载链接】DeepCodeDeepCode: Open Agentic Coding (Agent Harness Loop Engineering Multi-Agent Orchestration)项目地址: https://gitcode.com/GitHub_Trending/deepc/DeepCode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考