企业官网建设流程全解析

Agent Zero 共享与安全指南：决定"分享什么、分享到哪、什么必须保密"的完整实战手册

【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero

导读

Agent Zero 是一个开放的 AI Agent 框架，代码、插件、技能都可以对外分享，但并不是所有工作成果都适合进入公开仓库。本文基于 Agent Zero 仓库的 共享与安全指南 展开，为贡献者提供一套可操作的四步决策树：核心代码修复走主线贡献流程、独立插件发布到专属仓库、可复用技能走技能发布流程、而涉及凭据与客户资产的内容必须留在私有环境。读完本文，你将能正确判断每类产物的发布路径，理解公开 fork 与 PR 的安全操作规范，并学会如何通过usr/目录与.gitignore机制隔离私有内容，避免泄露密钥与内部数据。

一、先做判断：四步决策树

Agent Zero 的共享与安全指南给出的核心方法论是一棵决策树：任何工作成果在发布前，先依次回答四个问题，命中哪个答案就走哪条路径。

1. 这个改动是否属于 Agent Zero 核心仓库？

当改动直接改善框架本身时，应走主agent-zero贡献流程。典型场景包括：

• 修复webui/、helpers/、api/、tools/、extensions/或docs/目录下的缺陷；
• 与核心框架行为配套的测试用例；
• 为内置功能补充的文档。

如果答案"是"，则按以下步骤操作：

1. 公开 forkagent0ai/agent-zero；
2. 在本地克隆中添加upstream远程；
3. 从upstream/main（或当前使用的 upstream 目标分支）同步；
4. 创建一个聚焦的分支（一个修复对应一个分支）；
5. 跨 fork 打开 Pull Request。

完整的详细工作流见 贡献指南。该指南与共享安全文档互相印证：它同样强调"搜索已打开和最近关闭的 upstream PR 以避免重复工作""target 上游当前实际使用的基础分支，而非默认假设development""保持 fork 分支存活直到 PR 合并或关闭"。

2. 这是社区插件吗？

当工作成果是可独立安装的插件时，应使用独立的公开插件仓库。典型特征：

• 干净地存放在usr/plugins/<plugin_name>/目录下；
• 拥有自己的plugin.yaml；
• 可以独立于核心仓库演进；
• 应当能在 Plugin Hub 中被发现。

发布流程：

1. 将插件内容放到其专属仓库的根目录；
2. 包含plugin.yaml、README.md和LICENSE；
3. 从usr/plugins/本地测试；
4. 将其index.yaml条目提交到上游的 Plugin Index 仓库，以进入插件市场。

仓库内所有内置插件（如_a0_connector、_browser、_code_execution、_memory等）都遵循这一结构，可以作为参考样板。以 plugins/_a0_connector/plugin.yaml 为例，一个最小可用的plugin.yaml包含name、title、description、version等字段：

name: _a0_connector title: A0 Connector description: Current Agent Zero connector plugin for HTTP plus /ws integration, using session auth and handler activation through auth.handlers. version: "1.5" settings_sections: - external - developer per_project_config: false per_agent_config: false

同时，插件目录通常还包含api/、extensions/、helpers/、prompts/、skills/、tools/、webui/等子目录（参见 plugins/_a0_connector 的目录结构），以及一份面向开发者的AGENTS.md。独立插件仓库只需把插件内容置于根目录，再补齐README.md与LICENSE即可满足发布要求。

3. 这是可复用的技能（Skill）吗？

当工作成果主要是以SKILL.md形式呈现的过程性知识时，应走技能（Skills）工作流。典型特征：

• 它教 Agent 如何执行一项任务；
• 它可以跨 Agent Zero、Cursor、Claude Code、Copilot 等生态移植；
• 开发期自然存放于usr/skills/。

发布步骤：

1. 在本地usr/skills/下开发；
2. 校验结构与示例；
3. 若要贡献给 Agent Zero，则移动到skills/目录；也可以发布到专门的公开仓库或集合中。

技能的作者规范详见 技能贡献标准。该标准详细说明了SKILL.md的 YAML frontmatter 结构（name、description为必填字段，version、author、license、tags、triggers、allowed_tools、metadata为可选字段），并强调description直接参与语义匹配，应写成"Guides systematic debugging of Python applications..."这样的具体描述而非笼统的"Helps with debugging"。仓库中的技能样例可参见 skills/ 目录（如a0-create-plugin、a0-development等）。

4. 是否应该保持私有？

当工作成果包含以下任何内容时，必须将其排除在公开 fork 和 upstream PR 之外：

• 凭据、令牌、API Key、.env文件或客户机密；
• 仅限本地的实验、快照或临时分支考古；
• 客户特定的逻辑或数据；
• 机器特定的配置、缓存、本地虚拟环境或编辑器残留文件；
• 尚未准备好接受公开评审的插件或技能原型。

此类内容应保留在私有仓库、usr/目录或完全脱离公开贡献路径。

二、安全发布规则

确定路径之后，还需要遵守一系列与公开 fork 和 PR 相关的安全操作规范。

公开 fork 与 Pull Request

• 任何可能成为 upstream PR head 分支的分支，都必须使用公开、可推送的 fork；
• 在 PR 合并或有意关闭之前，保持源分支存活；
• 开新 PR 前，先搜索上游已打开和近期关闭的 PR，避免重复；
• 基础分支的选择应遵循上游当前实践，若现有活跃 PR 都 targetmain，就不要硬编码development；
• 记录你实际运行过的测试，作为评审依据。

"允许维护者编辑"选项

GitHub 允许贡献者勾选"允许维护者编辑你 fork 上的分支"。但如果 fork 分支中包含 GitHub Actions 工作流，GitHub 可能显示的是**"允许维护者编辑并访问 Secrets"**，这需要格外谨慎：

• 只有当你乐意让维护者编辑该分支上的工作流文件时，才启用此选项；
• 切勿在你打算公开分享的 fork 分支中遗留敏感值或私有自动化逻辑。

通常不应出现在公开贡献中的文件

以下文件类型在提交前应主动剔除：

• .env
• .venv/
• 编辑器设置，如.vscode/settings.json
• 临时笔记、草稿文件或机器特定备份
• 无关的格式改动（formatting churn）
• 私有报告或内部策略文档

这些约定在仓库的版本控制配置中有直接体现。根目录 .gitignore 全局忽略了**/.env、.venv/、**/__pycache__/、.DS_Store、IDE 目录（.cursor/、.windsurf/）等；而 conf/workdir.gitignore、conf/projects.default.gitignore 与 conf/skill.default.gitignore 则分别针对工作目录、项目与技能目录统一忽略了 Python 虚拟环境、缓存与 Node 依赖：

# Python environments & cache venv/** **/__pycache__/** # Node.js dependencies **/node_modules/** **/.npm/** # Version control metadata **/.git/**

值得一提的是，根 .gitignore 对usr/目录采用了"整体忽略、白名单放行"的策略：先忽略usr/**，再通过!usr/**/放行目录遍历、用!usr/**/.gitkeep仅保留占位文件。这意味着usr/天然是个人与本地实验的安全区，与共享安全指南"keep it in a private repository, inusr/, or outside the public contribution path entirely"的建议完全一致。

三、推荐的仓库模型：公私分离

对于同时承担私有研发与公开贡献的团队或维护者，指南推荐采用三仓库拆分模型，避免互相污染：

1. 私有工作区或备份仓库

• 插件实验；
• 客户特定工作；
• 快照与分支考古；
• 内部笔记与策略。

2. 仅做修复的干净克隆（面向 upstream）

• 只包含可能成为公开 PR 的分支；
• 从 upstream 同步；
• 不存放快照与无关实验。

3. 仅用于 PR head 分支的公开 fork

• 只保留聚焦、可评审的公开分支；
• 不放内部草稿分支。

这套模型与 贡献指南 中"Working With Forks Safely"一节的建议完全吻合：公开 fork、添加upstream远程、开工前定期同步、每个改动一个聚焦分支、跨 fork 打开 PR。

四、发布任何内容之前的检查清单

在最终发布前，逐项确认以下事项：

• 确认该成果属于所选发布路径的适用范围；
• 移除密钥与本地专属工件（secrets and local-only artifacts）；
• 检查是否与上游已有工作重叠；
• 确保 diff 范围狭窄、对评审者友好（reviewer-friendly）；
• 核实你打算引用的测试证据真实存在且可复现；
• 如果该分支将支撑 upstream PR，确保其源分支是公开的。

结语：一句话决策总结

对照决策树快速定位：改进框架本身 → 公开 fork + 跨 fork PR；独立插件 → 专属公开仓库 +plugin.yaml/README.md/LICENSE+ 提交 Plugin Index 条目；可复用技能 →usr/skills/开发、skills/贡献或独立发布；凭据、客户数据与本地实验 → 留在私有仓库或usr/。发布前再过一遍安全清单，即可在享受开源生态的同时，守住机密与代码质量的底线。如需进一步了解贡献全流程与技能创作规范，可继续阅读 贡献指南 与 技能贡献标准。

【免费下载链接】agent-zeroAgent Zero AI framework项目地址: https://gitcode.com/GitHub_Trending/ag/agent-zero