实践教程：我如何用 n8n 自动化“软著申请”中最头疼的文档撰写工作

导语

编写技术文档，尤其是为了软件著作权申请而准备的用户说明书，是一项至关重要但又极其耗时的工作。它要求我们深入理解项目结构、梳理核心功能，并将其规范地呈现出来。那么，有没有可能让 AI 来为我们分担这份重担呢？

答案是肯定的。本文将向你展示一个非常适合用 n8n + 大模型 (LLM) 来解决的典型自动化场景。我们将从零开始，一步步搭建一个能够自动分析 GitHub 仓库、并生成一份结构完整、内容丰富的软件用户说明书的 n8n 工作流。

无论你是工作流新手，还是希望探索 AI 应用新场景的开发者，这个项目都将是一个极具价值的实践。

整体思路分析

我们的目标是创建一个能接收代码仓库地址，并最终输出一份 Markdown 格式说明书的工作流。我们可以将其拆解为以下几个关键步骤：

1. 触发与输入 (Trigger & Input)：工作流需要一个起点，用于接收用户提供的"代码仓库地址"和"软件名称"。

2. 代码信息获取 (Code Fetching)：我们需要让 n8n 从指定的仓库（如 GitHub）"读懂"项目。直接读取所有代码文件不仅数据量巨大，还可能超出大模型的上下文窗口限制。

   • 核心策略 ：我们不读取完整的代码内容，而是采用一种更高效的方式：先用 git clone 克隆仓库，然后生成一份文件目录树 。这份目录树，结合项目中的核心配置文件（如 package.json, requirements.txt），足以让大模型精准地把握项目的技术栈、结构和核心模块。

3. 智能指令构建 (Prompt Engineering)：这是整个工作流的"大脑"。我们将用户输入、文件目录树以及预设的文档模板，组合成一个清晰、详尽的指令（Prompt），用于指导大模型进行创作。

4. 调用大模型 (LLM Call)：通过 n8n 的 AI 节点，将构建好的 Prompt 发送给大模型。

5. 结果输出 (Output)：接收大模型返回的 Markdown 格式文档，并将其清晰地呈现出来。

准备工作：你的工具箱

在开始搭建之前，请确保你已具备以下条件：

1. n8n 环境: 一个可用的 n8n 实例 (n8n Desktop, Docker, 或 n8n Cloud 均可)。

2. 大模型 API Key : 一个兼容 OpenAI 标准的 API Key。n8n 的 OpenAI 节点支持配置 Base URL，可以轻松对接各类大模型服务。

3. Git 环境 : 确保你的 n8n 运行环境中已安装 git。

   • 快速验证 : 在 n8n 中创建一个 Execute Command 节点，执行 git --version。如果成功返回版本号，则说明环境配置无误。

   • Docker 用户注意 : 官方的 n8nio/n8n 镜像默认不包含 git。你需要基于它构建一个自定义镜像，或使用支持自定义库的 n8n-custom 镜像。

实战演练：一步步搭建 n8n 工作流

下面是每个节点的详细配置说明。

步骤 1: 模拟用户输入 (Set 节点)

在实际应用中，这可以是一个 Webhook 或 n8n 表单。为了方便测试，我们使用 Set 节点来硬编码输入信息。

• 节点名称 : 设置输入参数

• 配置:

  • software_name: 智能客服问答系统 (或任何你想要的名称)

  • repo_url: https://github.com/n8n-io/n8n.git (使用一个公开仓库进行测试)

<!-- 建议配图 -->

步骤 2: 克隆仓库与生成文件树 (Execute Command 节点)

这是获取代码信息的关键一步。我们使用 shell 命令来克隆仓库并生成文件列表。

• 节点名称 : 克隆仓库并列出文件结构

• Command:

  # 创建一个临时目录，如果已存在则先删除，避免冲突
  rm -rf /tmp/repo_for_doc
  # 克隆指定的仓库到该临时目录
  git clone {{ $json.repo_url }} /tmp/repo_for_doc
  # 生成文件结构树，并将结果输出
  echo "========= 代码文件结构如下 ========="
  ls -R /tmp/repo_for_doc

  提示 : /tmp/repo_for_doc 是 n8n 容器内的一个安全临时路径。ls -R 命令会递归地列出所有文件和目录。

步骤 3: 构建终极指令 (Set 节点)

这是整个工作流的灵魂。我们在这里精心设计一个 Prompt，将所有信息整合起来，喂给大模型。

• 节点名称 : 构建Prompt

• 配置:

  • 创建一个名为 prompt 的字段，并使用表达式 (Expression) 填入以下 JavaScript 代码：

  // 从上一个节点获取命令执行的标准输出 (stdout)
  const file_structure = $('克隆仓库并列出文件结构').item.json.stdout;
  // 从输入节点获取软件名称
  const software_name = $('设置输入参数').item.json.software_name;
  ​
  return `
  请你扮演一个专业的软件技术文档工程师。我需要你根据我提供的软件名称和代码仓库文件结构，为我的软件 "${software_name}" 编写一份符合中国软件著作权申请要求的用户说明书。
  ​
  请严格按照以下 Markdown 模板和要求进行撰写：
  ​
  **输入信息:**
  1.  **软件名称:** ${software_name}
  2.  **代码仓库文件结构:**
  \`\`\`
  ${file_structure}
  \`\`\`
  ​
  ---
  ​
  **输出模板:**
  ​
  \`\`\`markdown
  # ${software_name} 用户说明书
  ​
  ## 1、引言
  ​
  ### 1.1 编写目的
  本文档旨在详细介绍 "${software_name}" 的各项功能、操作流程及安装部署方法，帮助用户快速上手并充分利用本系统的各项功能，确保系统的稳定、高效运行。
  ​
  ### 1.2 开发背景
  (请根据软件名称和文件结构推断，例如：如果看到.py和机器学习库，可以写“随着人工智能技术的发展...”; 如果看到.js和react，可以写“随着Web应用的普及...”)
  ​
  ### 1.3 定义
  - **系统、本系统、该系统**: 指 "${software_name}" 软件。
  - **用户**: 指使用本系统的操作人员。
  ​
  ## 2、系统概述
  ​
  ### 2.1 系统用途
  (请根据软件名称和功能推断，简要描述该系统的核心价值和目标用户。)
  ​
  ### 2.2 系统功能及特点
  (请根据文件结构猜测并列出主要的功能模块，并描述其特点，如：用户管理、数据分析、任务调度等。)
  ​
  ### 2.3 编程语言与环境
  (请根据文件结构中的文件后缀、依赖文件如 package.json, requirements.txt, pom.xml 等来推断)
  - **编程语言**: (例如: JavaScript, Python, Java)
  - **主要框架/库**: (例如: React, Vue, Django, Spring Boot, TensorFlow)
  - **集成开发环境**: (例如: Visual Studio Code, IntelliJ IDEA, PyCharm)
  ​
  ## 3、系统安装
  ​
  ### 3.1 运行环境
  #### 1) 硬件环境
  - **最低要求**:
    - 处理器: Intel Core i3 或同等水平
    - 内存: 4 GB RAM
    - 硬盘: 10 GB 可用空间
  - **建议配置**:
    - 处理器: Intel Core i5 或更高
    - 内存: 8 GB RAM 或更高
    - 硬盘: 50 GB SSD 可用空间
  ​
  #### 2) 软件环境
  - **最低要求**:
    - 操作系统: (根据技术栈推断，如：Windows 10, Ubuntu 20.04, macOS Big Sur)
  - **建议配置**:
    - 操作系统: (同上，或更新版本)
    - **依赖软件**: (例如: Node.js v16+, Python 3.8+, Docker, Nginx)
  ​
  ### 3.2 系统安装
  (请根据常见技术栈，编写一个通用的安装步骤说明。例如，可以包含：1.环境准备 2.克隆代码 3.安装依赖 4.配置 5.启动服务。)
  ​
  ## 4、软件功能
  (这一部分是重点。请根据文件结构，挑选并详细描述 3-5 个核心功能模块。每个功能模块作为一个子章节。你需要“脑补”一下这个功能具体是如何操作的，并配上描述性的文字。)
  ​
  ### 4.1 功能模块一 (例如：用户登录与注册)
  (描述该功能的作用，并给出简要的操作步骤)
  ​
  ### 4.2 功能模块二 (例如：数据看板)
  (描述该功能的作用，并给出简要的操作步骤)
  ​
  ### 4.3 功能模块三 (例如：任务管理)
  (描述该功能的作用，并给出简要的操作步骤)
  ​
  ## 5、技术支持
  如在使用过程中遇到任何问题，请通过以下方式联系我们：
  - 邮箱: support@example.com
  - 电话: 400-123-4567
  \`\`\`
  ​
  **撰写要求:**
  - 语言流畅，专业，符合中文技术文档的写作风格。
  - **内容要基于你推断出的软件功能，进行合理、详细的扩写，使其看起来像一份真正的说明书，而不仅仅是模板的填充。**
  - 最终输出只需要 Markdown 内容，不要包含 "输出模板:" 等无关文字。
  `;

  关键点: 这个 Prompt 不仅提供了数据（文件名、软件名），更重要的是提供了角色（技术文档工程师）、格式（Markdown模板）和明确的质量要求，这能极大地提升生成结果的质量。

步骤 4: 调用大模型 (OpenAI Chat Model 节点)

将我们精心准备的 Prompt 发送给 AI。

• 节点名称 : 调用大模型生成说明书

• Authentication: 选择或配置你的 OpenAI API 凭证。

• Model : 建议选择 gpt-4 或 gpt-3.5-turbo-16k 等支持长文本的模型。

• Content : 使用表达式 {``{ $('构建Prompt').item.json.prompt }} 将上一步生成的 Prompt 填入。

• Temperature : 设置为 0.5 左右，以在创造性和一致性之间取得平衡。

步骤 5: 提取最终结果 (Set 节点)

从大模型返回的复杂 JSON 数据中，我们只提取最终生成的 Markdown 文本。

• 节点名称 : 提取最终结果

• 配置:

  • 创建一个名为 user_manual_markdown 的字段。

  • 使用表达式 {``{ $('调用大模型生成说明书').item.json.choices[0].message.content }}。

  • 勾选 Keep Only Set 选项，让输出结果更干净。

完整工作流代码 (JSON)

为了方便你快速上手，这里提供了完整的工作流 JSON。你只需在 n8n 画布中复制粘贴，然后配置一下你的 AI 凭证即可。

{
  "name": "AI生成软著用户说明书",
  "nodes": [
    {
      "parameters": {},
      "id": "28e7e1ef-b0d3-4e4b-a982-f54f73809edb",
      "name": "Start",
      "type": "n8n-nodes-base.start",
      "typeVersion": 1,
      "position": [
        240,
        300
      ]
    },
    {
      "parameters": {
        "values": {
          "string": [
            {
              "name": "software_name",
              "value": "智能客服问答系统"
            },
            {
              "name": "repo_url",
              "value": "https://github.com/n8n-io/n8n.git"
            }
          ]
        },
        "options": {}
      },
      "id": "e4f58de2-8c9e-4369-b5ef-1a357591e1d1",
      "name": "设置输入参数",
      "type": "n8n-nodes-base.set",
      "typeVersion": 1,
      "position": [
        460,
        300
      ]
    },
    {
      "parameters": {
        "command": "rm -rf /tmp/repo_for_doc\ngit clone {{ $json.repo_url }} /tmp/repo_for_doc\necho \"========= 代码文件结构如下 =========\"\nls -R /tmp/repo_for_doc"
      },
      "id": "c16d5571-0010-48e0-819a-9e11894a4c54",
      "name": "克隆仓库并列出文件结构",
      "type": "n8n-nodes-base.executeCommand",
      "typeVersion": 1,
      "position": [
        700,
        300
      ]
    },
    {
      "parameters": {
        "values": {
          "string": [
            {
              "name": "prompt",
              "value": "={{ \nconst file_structure = $('克隆仓库并列出文件结构').item.json.stdout;\nconst software_name = $('设置输入参数').item.json.software_name;\n\nreturn `\n请你扮演一个专业的软件技术文档工程师。我需要你根据我提供的软件名称和代码仓库文件结构，为我的软件 \"${software_name}\" 编写一份符合中国软件著作权申请要求的用户说明书。\n\n请严格按照以下 Markdown 模板和要求进行撰写：\n\n**输入信息:**\n1.  **软件名称:** ${software_name}\n2.  **代码仓库文件结构:**\n\`\`\`\n${file_structure}\n\`\`\`\n\n---\n\n**输出模板:**\n\n\`\`\`markdown\n# ${software_name} 用户说明书\n\n## 1、引言\n\n### 1.1 编写目的\n本文档旨在详细介绍 \"${software_name}\" 的各项功能、操作流程及安装部署方法，帮助用户快速上手并充分利用本系统的各项功能，确保系统的稳定、高效运行。\n\n### 1.2 开发背景\n(请根据软件名称和文件结构推断，例如：如果看到.py和机器学习库，可以写“随着人工智能技术的发展...”; 如果看到.js和react，可以写“随着Web应用的普及...”)\n\n### 1.3 定义\n- **系统、本系统、该系统**: 指 \"${software_name}\" 软件。\n- **用户**: 指使用本系统的操作人员。\n\n## 2、系统概述\n\n### 2.1 系统用途\n(请根据软件名称和功能推断，简要描述该系统的核心价值和目标用户。)\n\n### 2.2 系统功能及特点\n(请根据文件结构猜测并列出主要的功能模块，并描述其特点，如：用户管理、数据分析、任务调度等。)\n\n### 2.3 编程语言与环境\n(请根据文件结构中的文件后缀、依赖文件如 package.json, requirements.txt, pom.xml 等来推断)\n- **编程语言**: (例如: JavaScript, Python, Java)\n- **主要框架/库**: (例如: React, Vue, Django, Spring Boot, TensorFlow)\n- **集成开发环境**: (例如: Visual Studio Code, IntelliJ IDEA, PyCharm)\n\n## 3、系统安装\n\n### 3.1 运行环境\n#### 1) 硬件环境\n- **最低要求**:\n  - 处理器: Intel Core i3 或同等水平\n  - 内存: 4 GB RAM\n  - 硬盘: 10 GB 可用空间\n- **建议配置**:\n  - 处理器: Intel Core i5 或更高\n  - 内存: 8 GB RAM 或更高\n  - 硬盘: 50 GB SSD 可用空间\n\n#### 2) 软件环境\n- **最低要求**:\n  - 操作系统: (根据技术栈推断，如：Windows 10, Ubuntu 20.04, macOS Big Sur)\n- **建议配置**:\n  - 操作系统: (同上，或更新版本)\n  - **依赖软件**: (例如: Node.js v16+, Python 3.8+, Docker, Nginx)\n\n### 3.2 系统安装\n(请根据常见技术栈，编写一个通用的安装步骤说明。例如，可以包含：1.环境准备 2.克隆代码 3.安装依赖 4.配置 5.启动服务。)\n\n## 4、软件功能\n(这一部分是重点。请根据文件结构，挑选并详细描述 3-5 个核心功能模块。每个功能模块作为一个子章节。你需要“脑补”一下这个功能具体是如何操作的，并配上描述性的文字。)\n\n### 4.1 功能模块一 (例如：用户登录与注册)\n(描述该功能的作用，并给出简要的操作步骤)\n\n### 4.2 功能模块二 (例如：数据看板)\n(描述该功能的作用，并给出简要的操作步骤)\n\n### 4.3 功能模块三 (例如：任务管理)\n(描述该功能的作用，并给出简要的操作步骤)\n\n## 5、技术支持\n如在使用过程中遇到任何问题，请通过以下方式联系我们：\n- 邮箱: support@example.com\n- 电话: 400-123-4567\n\`\`\`\n\n**撰写要求:**\n- 语言流畅，专业，符合中文技术文档的写作风格。\n- **内容要基于你推断出的软件功能，进行合理、详细的扩写，使其看起来像一份真正的说明书，而不仅仅是模板的填充。**\n- 最终输出只需要 Markdown 内容，不要包含 \"输出模板:\" 等无关文字。\n`;\n }}"
            }
          ]
        },
        "options": {}
      },
      "id": "e457f078-d4a9-4673-98fe-d5e89a24c58f",
      "name": "构建Prompt",
      "type": "n8n-nodes-base.set",
      "typeVersion": 1,
      "position": [
        940,
        300
      ]
    },
    {
      "parameters": {
        "model": "gpt-3.5-turbo",
        "messages": [
          {
            "content": "={{ $('构建Prompt').item.json.prompt }}"
          }
        ],
        "options": {
          "temperature": 0.5
        }
      },
      "id": "d04e4c9e-5da8-406d-bd40-c115474ca801",
      "name": "调用大模型生成说明书",
      "type": "n8n-nodes-base.openAiChat",
      "typeVersion": 1,
      "position": [
        1180,
        300
      ],
      "credentials": {
        "openAiApi": {
          "id": "YOUR_CREDENTIAL_ID",
          "name": "Your OpenAI Credential Name"
        }
      }
    },
    {
      "parameters": {
        "values": {
          "string": [
            {
              "name": "user_manual_markdown",
              "value": "={{ $('调用大模型生成说明书').item.json.choices[0].message.content }}"
            }
          ]
        },
        "options": {
          "keepOnlySet": true
        }
      },
      "id": "1d6c8e31-50e5-4f32-8438-7f9996b5825d",
      "name": "提取最终结果",
      "type": "n8n-nodes-base.set",
      "typeVersion": 1,
      "position": [
        1400,
        300
      ]
    }
  ],
  "connections": {
    "Start": {
      "main": [
        [
          {
            "node": "设置输入参数",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "设置输入参数": {
      "main": [
        [
          {
            "node": "克隆仓库并列出文件结构",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "克隆仓库并列出文件结构": {
      "main": [
        [
          {
            "node": "构建Prompt",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "构建Prompt": {
      "main": [
        [
          {
            "node": "调用大模型生成说明书",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "调用大模型生成说明书": {
      "main": [
        [
          {
            "node": "提取最终结果",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  }
}

注意 : 粘贴后，请务必在 调用大模型生成说明书 节点中选择你自己的 API 凭证。

进阶与扩展

你现在已经拥有一个功能完备的自动化文档生成器！以下是一些可以让你更上一层楼的优化方向：

• 增强对技术栈的理解 : 修改步骤 2 的命令，除了列出文件树，还可以使用 cat 读取 package.json 或 requirements.txt 的内容，并将其一并加入到 Prompt 中，这将使 AI 对技术栈的分析更为精准。

• 支持私有仓库 : 通过在 Execute Command 节点中配置 SSH Key 或 Access Token，可以实现对私有代码仓库的克隆。

• 打造用户友好界面 : 将 Set 输入节点替换为 Webhook 节点，并配合一个简单的网页表单，或使用 n8n 内置的 Form Trigger（付费功能），让非技术人员也能方便地使用。

• 自动生成 Word/PDF : 虽然大模型不直接生成 .docx 文件，但你可以通过增加一个 Execute Command 节点并使用 pandoc 工具 (pandoc input.md -o output.docx) 来实现 Markdown 到 Word/PDF 的自动转换。这需要你的 n8n 环境支持安装 pandoc。

结语

通过这个项目，我们不仅解决了一个实际工作中的痛点，更体验了将自动化工作流（n8n）与生成式AI（LLM）相结合所带来的巨大潜力。希望这份指南能启发你构建更多有趣且实用的自动化流程。动手试试吧，创造属于你自己的 AI 助手！