企业官网建设流程全解析

1. 为什么我要把 Jira 操作交给 Langchain v1.0 智能体

如果你每天在 Jira 里重复做三件事：建任务、改状态、补评论，那这篇文章就是写给你的。我用 Langchain v1.0 搭了一个 Jira 智能体，目标很直接——把「自然语言一句话」变成「Jira 里真实存在的任务和状态流转」。它适合三类人：一是想入门 AI 智能体但不知道拿什么场景练手的开发者；二是团队里被 Jira 流程拖慢节奏、想用自动化任务管理提效的工程同学；三是已经在用 Langchain，但还没跑通「工具调用 + 外部系统」闭环的人。

Langchain v1.0 相比早期版本，最大的变化是把状态管理和工具调用收敛得更清晰，配合 LangGraph 的图结构，你可以把「检索上下文 → 决策 → 调 Jira → 回执」拆成可观测的节点。Jira 智能体的本质，就是让大模型不再只聊天，而是能真正调用 Jira API 去创建 issue、转换状态、追加评论。这篇不堆概念，直接给你可复制的 config.toml、settings.json 骨架，以及一条统一的 Key/API 通道配置示例，最后用本地运行验证任务创建和流转是否真的成功。

我试过把 Jira 的 REST 调用直接塞进 prompt 让模型拼 URL，结果参数一多就崩，所以更稳的做法是：模型只负责「决定做什么」，真正的 Jira 操作交给工具函数或 MCP 风格的标准化接口。下面从环境准备开始，一步步跑通。

2. 前置准备：TaoToken 统一 Key 与 API 通道

在写 Jira 工具之前，先把模型调用这条链路固定下来。我用的方式是 TaoToken 作为统一入口，好处是 Key 和 API 地址集中管理，后面换模型或加工具不用到处改代码。官网地址是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 根地址是 https://taotoken.net/api （这个不加 UTM）。

你需要先拿到一个可用的 Key，然后把它写进环境变量，而不是硬编码在代码里。我习惯用.env加settings.json双层管理：.env放敏感值，settings.json放非敏感的结构化配置。这样本地跑和后面部署都不会因为改一个地址而翻遍代码。

注意：Jira 的 API Token 和模型 Key 是两套东西，别混在一个变量里。Jira 那边用的是 Atlassian 的邮箱 + API Token，模型这边用的是 TaoToken 的 Key。

如果你还没建 Key，可以到 API Keys 页面生成：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 。生成后复制保存，页面只显示一次。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，遇到参数不确定时对着看。

3. 可复制配置：config.toml 与 settings.json 骨架

先建项目目录，我习惯这样分：

mkdir jira-agent && cd jira-agent python -m venv .venv source .venv/bin/activate # Windows 用 .venv\Scripts\activate pip install langchain langchain-openai langgraph requests python-dotenv tomli

然后是config.toml，这个文件放模型和 Jira 的连接参数，注意不要把真实 Token 写进去，用占位符配合环境变量读取：

[model] provider = "openai-compatible" base_url = "https://taotoken.net/api" model_name = "gpt-4o-mini" temperature = 0.2 max_tokens = 1024 [jira] base_url = "https://your-domain.atlassian.net" project_key = "PROJ" default_issue_type = "Task" [agent] max_iterations = 6 verbose = true

接着是settings.json，这个文件描述工具能力和字段映射，方便后面扩展：

{ "tools": [ { "name": "create_jira_issue", "description": "在 Jira 中创建一个新任务", "parameters": { "summary": "string", "description": "string", "issue_type": "string", "assignee": "string" } }, { "name": "transition_jira_issue", "description": "转换 Jira 任务状态", "parameters": { "issue_key": "string", "transition_name": "string" } } ], "field_mapping": { "summary": "summary", "description": "description", "issue_type": "issuetype.name", "assignee": "assignee.name" } }

.env文件这样写：

TAOTOKEN_API_KEY=你的_TaoToken_Key JIRA_BASE_URL=https://your-domain.atlassian.net JIRA_USER_EMAIL=you@example.com JIRA_API_TOKEN=你的_Jira_API_Token

读取配置的代码：

import os, json, tomli from dotenv import load_dotenv load_dotenv() with open("config.toml", "rb") as f: config = tomli.load(f) with open("settings.json", "r", encoding="utf-8") as f: settings = json.load(f) config["model"]["api_key"] = os.getenv("TAOTOKEN_API_KEY") config["jira"]["user_email"] = os.getenv("JIRA_USER_EMAIL") config["jira"]["api_token"] = os.getenv("JIRA_API_TOKEN")

这样配置和代码分离，后面换模型或换 Jira 实例只改配置文件。

4. 核心实现：把 Jira 操作封装成 Langchain 工具

Langchain v1.0 里工具定义推荐用@tool装饰器，配合类型注解，模型能自动推断参数。先写 Jira 的底层调用：

import requests from requests.auth import HTTPBasicAuth from langchain_core.tools import tool JIRA_BASE = config["jira"]["base_url"] AUTH = HTTPBasicAuth(config["jira"]["user_email"], config["jira"]["api_token"]) HEADERS = {"Accept": "application/json", "Content-Type": "application/json"} @tool def create_jira_issue(summary: str, description: str, issue_type: str = "Task", assignee: str = "") -> str: """在 Jira 中创建一个新任务，返回任务 Key。""" payload = { "fields": { "project": {"key": config["jira"]["project_key"]}, "summary": summary, "description": description, "issuetype": {"name": issue_type}, } } if assignee: payload["fields"]["assignee"] = {"name": assignee} resp = requests.post(f"{JIRA_BASE}/rest/api/2/issue", json=payload, auth=AUTH, headers=HEADERS) if resp.status_code == 201: return f"创建成功，任务 Key: {resp.json()['key']}" return f"创建失败: {resp.status_code} {resp.text}" @tool def transition_jira_issue(issue_key: str, transition_name: str) -> str: """转换 Jira 任务状态，例如从 To Do 到 In Progress。""" url = f"{JIRA_BASE}/rest/api/2/issue/{issue_key}/transitions" resp = requests.get(url, auth=AUTH, headers=HEADERS) transitions = resp.json().get("transitions", []) target = next((t for t in transitions if t["name"].lower() == transition_name.lower()), None) if not target: return f"未找到状态转换: {transition_name}" requests.post(url, json={"transition": {"id": target["id"]}}, auth=AUTH, headers=HEADERS) return f"{issue_key} 已转换为 {transition_name}"

然后绑定模型和工具：

from langchain_openai import ChatOpenAI from langchain.agents import create_tool_calling_agent, AgentExecutor from langchain_core.prompts import ChatPromptTemplate llm = ChatOpenAI( model=config["model"]["model_name"], base_url=config["model"]["base_url"], api_key=config["model"]["api_key"], temperature=config["model"]["temperature"], ) tools = [create_jira_issue, transition_jira_issue] prompt = ChatPromptTemplate.from_messages([ ("system", "你是 Jira 助手，根据用户指令调用工具完成任务。"), ("human", "{input}"), ("placeholder", "{agent_scratchpad}"), ]) agent = create_tool_calling_agent(llm, tools, prompt) executor = AgentExecutor(agent=agent, tools=tools, verbose=True, max_iterations=6)

这里的关键点是：模型只输出「调用哪个工具、传什么参数」，真正的 HTTP 请求在工具函数里完成。这样即使模型幻觉，也不会直接拼出错误的 URL。

5. 验证请求：本地跑通任务创建与状态流转

先验证模型通道是否通，单独跑一句：

resp = llm.invoke("用一句话说明你能做什么") print(resp.content)

如果这里报 401，说明 TaoToken Key 没读到，检查.env是否被load_dotenv()正确加载。通道通了之后，跑智能体：

result = executor.invoke({ "input": "创建一个任务，标题是'优化登录页加载速度'，描述是'目标 FCP 小于 1.5 秒'，类型 Task" }) print(result["output"])

成功的话，终端会打印类似创建成功，任务 Key: PROJ-123。你可以打开 Jira 确认任务真的存在。接着验证状态流转：

result = executor.invoke({ "input": "把 PROJ-123 的状态改成 In Progress" }) print(result["output"])

如果返回PROJ-123 已转换为 In Progress，说明工具调用闭环跑通了。这一步是整个自动化任务管理的核心验证点——模型决策、工具执行、Jira 真实变更三者一致。

提示：如果 Jira 项目的工作流里没有In Progress这个转换名，会返回「未找到状态转换」。先去 Jira 项目设置里看实际的状态名，再传对应字符串。

6. 本篇常见错排查

报错一：401 Unauthorized（模型侧）多数是TAOTOKEN_API_KEY没生效。检查.env文件是否在项目根目录，load_dotenv()是否在读取配置之前调用。另外确认base_url写的是https://taotoken.net/api，不要多加斜杠或路径。

报错二：Jira 返回 400 Bad Request常见原因是project_key写错，或者issue_type名称和 Jira 里的不一致。Jira 默认项目里类型叫Task、Bug、Story，但有些团队改过名字。先用GET /rest/api/2/project/{key}确认。

报错三：工具没被调用，模型直接回答说明 prompt 里没有明确要求调用工具，或者模型不支持 tool calling。换支持 function calling 的模型，并在 system prompt 里强调「必须调用工具完成操作，不要凭空回答」。

报错四：状态转换找不到Jira 的 transition 名称依赖工作流配置，不是固定的。用GET /rest/api/2/issue/{key}/transitions列出所有可用转换，把返回的name字段抄进你的指令里。

报错五：中文描述乱码Jira REST API v2 对中文支持没问题，但如果你用了 v3 的 ADF 格式，description 需要结构化。简单起见先用 v2 接口，description 传纯字符串。

7. 继续往下走：从单次调用到长期编码助手

跑通上面这套之后，你已经有了一个能创建和流转 Jira 任务的智能体。但如果想让它长期挂在开发流程里，比如监听 Git 提交、自动更新任务状态，单次脚本就不够了。这时候可以考虑 Coding Plan 这类长期编码/Agent 场景的方案，把模型调用和工具编排做成可持续运行的服务：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。

如果你更想先在对话里验证模型对 Jira 指令的理解能力，可以到模型对话页面直接试：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 。把「创建一个高优先级 bug 并分配给张三」这类指令丢进去，看模型是否能稳定输出结构化参数，再决定要不要接真实 Jira。

我自己的经验是：先把工具函数的错误处理写扎实，再让模型去调。模型再聪明，也救不了一个返回 500 的接口。把create_jira_issue和transition_jira_issue的返回信息设计得足够清晰，模型下一轮决策的准确率会明显提升。