内容
# n8n 代理工具
Ferramenta global instalável para代理人 de IA trabalharem com projetos n8n versionáveis sem copiar `tools/` para cada repo.
O objetivo é simples: cada projeto n8n vira um repositório Git próprio, com workflows em JSON, contexto local, MCP configurado e credenciais fora do repositório. A CLI global `n8n-agent` é instalada uma vez e usada por Codex, Claude, Gemini, Copilot e IDEs com agentes.
## O Que Este Repo Entrega
- CLI global: `n8n-agent`.
- 服务器 MCP: `n8n-agent mcp`.
- 初始化项目: `n8n-agent project init`.
- 读取和编辑本地 workflows JSON.
- 显式同步与 n8n 公共 API.
- 项目范围云端避免扫描整个实例.
- 配置文件和本地凭证库外.
- `local-only` 模式阻止云端.
- TOON 库真实节点示例.
- `plugins/n8n-agent-mcp` 中代理插件.
- 真实项目参考保存在 `examples/cs-pipeline`.
## 思维模型
消费者项目是本地工作源。n8n 云端仅在用户请求时查询或修改。
```text
n8n 项目仓库
n8n-agent.json
.mcp.json
context/
scripts/
.n8n-agent/cloud-scope.json
n8n-workflows/
用户机器
~/.config/n8n-agent/credentials.json
全局安装 n8n-agent
```
秘密永远不应进入仓库。n8n 公共 API 也不暴露 UI 文件夹，因此远程范围需要通过标签、正则表达式和 ID 清单声明。
## 安装
在开发过程中：
```bash
uv run --project . n8n-agent --help
uv run --project . n8n-agent mcp
```
发布仓库后：
```bash
uv tool install git+https://github.com/SoTahTech-Solucoes-Tecnologicas-LTDA/n8n-agent-mcp.git
n8n-agent --help
```
## 创建 n8n 项目
```bash
mkdir meu-projeto-n8n
cd meu-projeto-n8n
n8n-agent project init \
--name "meu-projeto-n8n" \
--workflows-dir n8n-workflows \
--profile prod \
--host https://n8n.example.com \
--with-readme \
--with-mcp \
--with-context
```
命令创建：
```text
n8n-agent.json
.mcp.json
.gitignore
README.md
context/n8n-agent/*.md
scripts/README.md
.n8n-agent/cloud-scope.json
n8n-workflows/
```
它不初始化 Git。请在需要时手动运行 `git init`。
## 凭证和配置文件
在仓库外保存凭证：
```bash
printf "$N8N_API_KEY" | n8n-agent project credentials set \
--profile prod \
--host https://n8n.sotahtech.com/ \
--api-key-stdin
```
在不透露值的情况下检查状态：
```bash
n8n-agent project credentials list
n8n-agent project config show --with-secrets-status
```
显式测试凭证：
```bash
n8n-agent project credentials test --profile prod
```
版本控制配置文件保存在 `n8n-agent.json`；秘密保存在 `~/.config/n8n-agent/credentials.json`。
切换活动配置文件：
```bash
n8n-agent project profile list
n8n-agent project profile set-active staging --host https://staging-n8n.example.com
```
`N8N_AGENT_PROFILE` 作为当前进程的重写：
```bash
N8N_AGENT_PROFILE=staging n8n-agent cloud status --scope
```
## 云端范围
无范围时，n8n 实例可以有多个公司和项目的 workflows。在批量列出、拉取或比较之前使用范围。
```bash
n8n-agent project scope init --tag "项目 X"
n8n-agent project scope show
```
版本控制文件：
```json
{
"version": 1,
"mode": "manifest",
"tags": ["项目 X"],
"nameRegex": "^\\[项目 X\\]",
"workflowIds": [],
"includeInactive": true
}
```
接受 `--scope` 的命令：
```bash
n8n-agent cloud list --scope --profile prod
n8n-agent cloud status --scope --profile prod
n8n-agent cloud diff --scope --profile prod
n8n-agent cloud pull --scope --profile prod
```
## 工作流
1. 全局安装 `n8n-agent`。
2. 创建 n8n 项目 Git 仓库。
3. 运行 `n8n-agent project init`。
4. 为配置文件设置凭证。
5. 通过标签、正则表达式或 ID 定义云端范围。
6. 仅拉取范围内的初始内容。
7. 生成 TOON 示例。
8. 使用 MCP 打开 IDE。
9. 本地优先工作。
10. 显式推送到云端。
命令：
```bash
n8n-agent cloud list --scope --profile prod
n8n-agent cloud pull --scope --profile prod
n8n-agent local list
n8n-agent examples ingest --all
n8n-agent local validate --all
```
## 本地工作
本地工具：
```bash
n8n-agent local list
n8n-agent local index <workflow>
n8n-agent local get-node <workflow> --name "Node"
n8n-agent local get-connections <workflow>
n8n-agent local search --type httpRequest
n8n-agent local edit-node <workflow> --name "Node" --set parameters.foo=bar
n8n-agent local validate <workflow>
```
编辑针对代理人：先 dry-run，然后 `--apply`，最后验证。
## 本地-only 模式
当用户请求仅在本地工作：
```bash
n8n-agent project mode local-only --reason "trabalho local divergente do remoto"
```
在活动时，云端命令失败，在查找凭证或调用 API 之前。
释放：
```bash
n8n-agent project mode cloud-ok
```
在 MCP 中，代理人应首选 `project_mode_set scope=session mode=local-only` 以仅阻止当前聊天。
## MCP 和 IDE
服务器命令：
```bash
n8n-agent mcp
```
通用配置：
```json
{
"mcpServers": {
"n8n-agent": {
"command": "n8n-agent",
"args": ["mcp"],
"env": {
"N8N_AGENT_ROOT": "."
}
}
}
}
```
在此开发仓库中，`.mcp.json` 使用 `uv run --project . n8n-agent mcp`。在消费者项目中，请使用 `n8n-agent mcp`。
## TOON 示例库
从真实工作流中生成净化示例：
```bash
n8n-agent examples ingest --all
n8n-agent examples search --type httpRequest
n8n-agent examples read <example-id>
```
示例存储在 `.n8n-agent/examples` 中。它们帮助代理人使用真实参数创建节点，特别是社区节点和特定凭证。
## 仓库布局
```text
.
├── pyproject.toml # 全局 Python 包
├── uv.lock # 开发锁
├── README.md # 主要文档
├── docs/ # 使用指南和架构
├── prompts/ # 打包主提示
├── tools/ # 包代码
│ ├── n8n_agent/ # CLI 分发器和模板
│ ├── n8n_project/ # init/config/profile/credentials/scope/mode/context
│ ├── n8n_local/ # 本地读取、编辑和验证
│ ├── n8n_cloud/ # n8n 公共 API
│ ├── n8n_examples/ # TOON 库
│ ├── paths/ # 辅助实用程序
│ └── common/ # 共享基础设施
├── tests/ # 主要烟雾测试和合约
├── plugins/n8n-agent-mcp/ # 初始代理插件
├── examples/cs-pipeline/ # 保留真实项目作为参考
└── .github/workflows/ci.yml # CI
```
## 文档
- [快速入门](docs/QUICKSTART.md)
- [创建版本化的 n8n 项目](docs/CRIANDO_PROJETO_VERSIONAVEL.md)
- [多个实例和公司](docs/MULTIPLAS_INSTANCIAS.md)
- [代理人和 IDE](docs/AGENTES_E_IDES.md)
- [MCP 工具指南](docs/GUIA_FERRAMENTAS.md)
- [本地-only 模式](docs/LOCAL_ONLY.md)
- [云范围、标签和路径规则](docs/CLOUD_SCOPE.md)
- [TOON 示例库](docs/EXEMPLOS_TOON.md)
- [安全拉取和推送](docs/PUBLISH_PULL_PUSH_SEGURO.md)
- [仓库布局](docs/REPOSITORY_LAYOUT.md)
## 开发
主要验证：
```bash
python3 -m compileall -q tools prompts tests
uv run --project . --group dev pytest -q
uv build --sdist --wheel
```
CI 运行编译、测试和构建。
在创建 Git 仓库之前，请确保本地工件不存在：
```bash
find . -maxdepth 3 \( -name '.venv' -o -name '__pycache__' -o -name 'dist' -o -name 'build' -o -name '*.egg-info' -o -name '.pytest_cache' \) -print
```
## 仓库外内容
默认情况下忽略：
- `.env`, `tools/.env`, `*.local.json`
- `~/.config/n8n-agent/credentials.json`
- `.n8n-agent/state/`
- `.n8n-agent/tmp/`
- `.n8n-agent/mode.json`
- `.venv/`, `dist/`, `build/`, `*.egg-info/`, 缓存
- `.claude/`, `.idea/`, `.vscode/`
n8n 项目的旧敏感文件，如 `env.json` 和 `n8nac-config.json`，也会被忽略。
