Agents（智能体）

Agent 是由 codet 服务端驱动的 LLM 智能体，通过 Gitea Actions runner 执行任务。您只需创建一次 Agent，选择它执行的动作以及触发它的事件，它就会分析 Issue 与合并请求、编写代码、创建并维护 PR、审查代码，或扫描仓库中的安全问题。

Agents 自 Gitea Enterprise v27 起提供。

工作原理

每个 Agent 都绑定一个独立的 Bot 账号，Agent 名称即该 Bot 的用户名。因此它可以像普通用户一样被提及（@名称）、被指派到 Issue 或 PR、被请求作为评审人。
每个 Agent 只执行一个动作（分析、生成并维护 PR、审查代码或安全扫描），并响应您为它选择的事件。如果需要既写代码又审查代码的 Agent，请分别创建两个 Agent。
Agent 有三个管理作用域：全局（站点管理员）、个人（用户）和组织。作用域决定谁可以创建和管理 Agent，以及 Agent 在哪些仓库上生效。
职责划分为两部分：Runner 负责修改代码并把分支推送到目标仓库，Gitea 负责记录结果并执行后续动作，例如创建或更新 PR、评论、评审与合并。
事件触发时，仓库所有者作用域的 Agent 与全局作用域的 Agent 都会被找到。也就是说，全局 Agent 可作用于实例内所有仓库，个人 Agent 只作用于该用户名下的仓库，组织 Agent 只作用于该组织名下的仓库。
Agent 之间可以接力传递工作，但接力是有上限的：一次运行会统计在没有人工介入的情况下已经互相响应了多少轮，达到配置的 Agent 自动接力轮次后即停止。

前置条件

在创建 Agent 之前，请确认：

已启用 Gitea Actions，并且至少有一个在线 Runner，其标签与 Runner 标签设置一致（默认 ubuntu-latest）。
至少有一个可用的 Agent Connection，即可访问的 codet 服务端地址及其 Token。
Runner 能够下载 codet CLI。内网/离线部署时，可将下载地址指向内部镜像。

启用与配置 Agents

Agents 拥有独立的后台菜单，打开 Site Administration > Agents > General。此页面在 Agents 关闭时仍可访问，因为启用开关就在这里。

设置	默认值	说明
启用 Agents	关闭	关闭后，用户与组织的 Agent 页面隐藏且不可访问。
Runner 标签	`ubuntu-latest`	生成的 Agent 工作流所使用的 Runner 标签。
每个工单每小时的运行次数	200	同一个 Issue 或 PR 一小时内最多可以启动多少次 Agent 运行，用于防止 Agent 之间互相触发。取值为 1 至 1000 的整数。
Agent 自动接力轮次	20	在没有人参与的情况下，Agent 之间最多可以互相触发多少轮，例如编码 Agent 推送代码、评审 Agent 再评审。达到上限后自动接力停止，新的人工请求会重新开始计数。取值为 1 至 50 的整数。
失败后的自动重试次数	0	同一个请求在运行失败后最多自动重新启动多少次。失败原因如果出在运行本身，每次重试都会再次失败，因此填 `0` 表示不自动重试，由人工决定是否再试。手动重试和 `@agent redo` 始终可以执行。取值为 0 至 20 的整数。
失败记忆时长	1 小时	统计重试次数时，失败记录保留多长时间。超过该时长后，同一请求会以干净的历史重新开始。取值为 1 至 168 小时的整数。
排队请求有效期	24 小时	等待运行结束的请求超过该时长后将被丢弃，而不是继续启动。取值为 1 至 168 小时的整数。
Checkout action	`actions/checkout@v7`	生成的工作流用于检出仓库的 action。Runner 无法访问外部 action 时，可使用完整的内部地址，例如 `https://gitea.example/actions/checkout@v7`。
每个提交的自动 CI 修复次数	3	Agent 针对同一个提交的失败检查最多响应多少次。达到上限说明修复没有产生任何新提交，Agent 会停止并请求人工介入。取值 1 到 20 的整数。
阻塞请求的提醒时间	168 小时	等待阻塞工单的 Coder 请求在这段时间后会收到一条提醒评论，请求继续等待，阻塞解除后自动启动。取值 24 到 720 小时。
阻塞请求的过期时间	0（关闭）	等待阻塞工单超过该时间的 Coder 请求会被丢弃并留下一条评论。`0` 表示一直等待，否则取值 24 到 8760 小时。
Codet CLI 版本	`v0.5.1`	Runner 安装的 codet CLI 版本。
Codet CLI 下载地址	`https://corp.gitea.com/copilot/codet-cli/releases/download/{version}/codet-{version}-{os}-{arch}.tar.gz`	支持 `{version}`、`{os}`、`{arch}` 占位符，可指向内部镜像。`.tar.gz` 会自动解压，也支持直接下载可执行文件。
Codet CLI 校验值	空	可选，用逗号分隔的 `arch:sha256` 列表，例如 `amd64:<sha256>,arm64:<sha256>`。配置后 Runner 会在使用前校验下载的压缩包或可执行文件。

这些配置由后台管理界面写入数据库（动态配置），不是 app.ini 配置项，无法通过配置文件设置。

连接、Agent 列表与实例级 Agent 机密是同一个 Agents 菜单下的其它入口，在启用 Agents 后显示。

Agent Connection（连接）

Connection 描述一个 codet 服务端：地址与 Token。Agent 选择 Connection 后，会通过 codet-sdk 从该服务端发现可用模型与工作语言。

字段	必填	说明
Agent Connection 名称	是	在 Agent 表单中显示的名字。
Agent Connection URL	是	例如 `https://codet.example.com`。
Agent Connection Token	是	加密存储，保存后只能替换，无法再读取。

作用域

全局连接：由站点管理员在 Site Administration > Agents > Connections 创建，可按访问模式开放给用户与组织。
本地连接：由用户或组织在各自的设置页创建，仅对该作用域可见可用；继承自全局的连接在本地只读。

访问模式

仅全局连接可配置访问模式，用户访问与组织访问分别设置。

访问模式	含义
不开放	保持私有，仅全局（站点管理）作用域可用。
全部	向该作用域内的所有用户或组织开放。
指定	仅允许访问列表中列出的用户、用户组或组织使用。

访问列表支持三种主体：用户、用户组、组织。用户组按成员的有效成员（含嵌套用户组继承的成员）展开匹配。

模型与语言发现

Agent 表单中的模型下拉框通过 codet-sdk 从所选 Connection 加载，不再维护手工列表。
同一 Connection 的模型与语言结果会被缓存（成功 5 分钟，失败 30 秒）；连接被创建、修改或删除时缓存立即失效。
发现失败时表单会给出提示，并允许手动输入模型名称；语言则回退到内置列表（自动 / 英语 / 简体中文 / 繁体中文）。

创建与编辑 Agent

字段	说明
名称	必填，最长 40 字符。同时作为 Bot 用户名，必须符合 Gitea 用户名规则且全局唯一。
Agent Connection	必填。没有可用 Connection 时保存按钮不可用，并提示先创建连接。
模型	必填。列表由所选 Connection 通过 `codet-sdk` 加载；加载失败时可手动输入。
描述	可选，会同时作为 Bot 账号的描述。
工作语言	Agent 在评审、评论、PR 标题与描述中使用的语言。`自动（跟随对话语言）`表示跟随触发的 Issue、合并请求或评论的语言；无法判断时使用英文。代码、标识符、commit SHA 与命令输出保持原样。
系统提示词	不在表单中编辑，见提示词、技能与 MCP。表单里只显示该 Agent 的 `.agent` 仓库链接。
头像	可选。可选择与 Agent 能力相符的内置图标、让图标随所选动作自动匹配，或上传自定义图片（不支持 SVG）。
动作与触发事件	Agent 执行的单个动作及其触发事件，见动作与触发事件。

Agent 列表会为每个 Agent 显示由其动作推导出的角色标签（规划、代码、审查或安全），以及模型与工作语言。

创建 Agent 时系统会自动：

创建一个 Bot 账号（已激活、邮箱私有、禁止创建组织）；
保存动作与触发事件配置。

此外，每次触发运行（定时扫描除外）都会确保该 Bot 作为写权限协作者加入目标仓库，使 Agent 自身在仓库内的操作始终受其真实权限约束。

每个作用域都可以创建多个 Agent，并可分别编辑、删除。删除 Agent 会同时清理其 Bot 账号、命令名单以及历史版本可能遗留的长期凭据。

动作与触发事件

每个 Agent 只执行一个动作，且动作在 Agent 创建后不可更改；其动作设置和触发事件仍可编辑。表单会列出各个动作及其支持的事件：先选择动作，再选择触发它的事件。只能选择所选动作支持的事件，并且至少需要选择其中一个事件。

动作

动作	说明	触发事件
分析	分析请求，自行判断是直接回复分析结果，还是拆分成多个子任务工单（每个子任务会开启独立的 Agent 会话）。	创建 Issue、被指派、被提及、有回复、默认分支 CI 失败
生成并维护 PR	在需要时创建初始 PR，并在后续继续更新维护同一个 PR，包括处理并解决相关的评审评论对话。还可以修复安全发现和失败的默认分支。	创建 Issue、被指派、被提及、有回复、已提交评审、收到代码评审评论、新的代码扫描发现、针对发现发起请求、已确认的代码扫描发现、默认分支 CI 失败
审查代码	审查最新代码变更，确认要求的修复是否完成，并在 Gitea 中提交更新后的评审结果。	创建 PR、请求评审、被指派、被提及
安全扫描	扫描仓库代码与历史，识别高可信度安全问题，并将可操作的问题报告为工单或仓库安全页面上的发现；也可以判断各类扫描器发现的误报。	定时安全扫描、主分支有新提交、创建 PR、请求评审、被指派、被提及、新的代码扫描发现、针对发现发起请求

说明：

解决评审评论不是独立动作，已并入「生成并维护 PR」。
合并也不是独立动作，通过「审查代码」的所有检查和审批通过后允许合并开关启用；该开关仅表示允许，实际合并仍需满足必需检查与分支保护审批要求。

触发事件

事件	触发时机
所有事件	虚拟事件，表示在后台处理该动作支持的所有事件。
被指派	Bot 账号被指派到 Issue 或 PR。
被提及	Bot 账号在 Issue 或 PR 评论中被提及。
有回复	已指派给该 Agent 的 Issue 或 PR 出现新回复。
请求评审	Bot 账号被请求作为 PR 评审人。
已提交评审	PR 收到已提交的评审，且该 Agent 被指派继续跟进该 PR。
收到代码评审评论	PR 收到新的行级代码评审评论，且该 Agent 被指派继续跟进该 PR。
创建 Issue	当前用户或组织名下仓库创建新 Issue。
创建 Pull Request	当前用户或组织名下仓库创建新 PR。
定时安全扫描	按设定周期扫描 Bot 账号拥有 Issue 读取权限的所有仓库。
主分支有新提交	主分支收到提交时触发，只扫描本次改动相关的代码。
新的代码扫描发现	扫描为默认分支保存了新的发现（任意扫描器）。
针对发现发起请求	具有安全写权限的用户在发现页面上请求该 Agent。
已确认的代码扫描发现	分诊 Agent 确认某个高危或严重发现为真实问题。
默认分支 CI 失败	默认分支上的某个工作流在上一次运行通过后失败。Agent 会诊断原因（分析），或创建修复 PR（生成并维护 PR）。

注意：

每个动作只支持上表列出的部分事件；界面不会提供不支持的组合，保存时会被拒绝，运行时也会被过滤。因此「所有事件」只代表「该动作支持的所有事件」。
所选动作至少需要选择一个触发事件，否则保存失败。

动作附属设置

所属动作	设置	说明
生成并维护 PR	为此 PR 请求 Agent 评审	可选。受管理的 PR 创建或更新时，自动请求一个或多个已选 Agent 作为评审人。
生成并维护 PR	为此 PR 请求用户评审	可选。在创建或更新此托管 PR 时，请求一个或多个用户作为评审人。用户与 Agent 可以同时配置。
生成并维护 PR	自动维护此 PR 的失败 CI	可选。启用后，当该受管理 PR 的后续工作流运行失败时，自动再次触发 Agent 尝试修复 CI。
生成并维护 PR	PR 自动维护最大重试次数	默认 5，取值为不小于 1 的整数。
生成并维护 PR	让此 PR 与基础分支保持最新	可选。分支落后时把基础分支合并进 head 分支。只做合并，不会变基或强制推送，因此不会改写他人的提交。
生成并维护 PR	自动解决此 PR 的合并冲突	可选。与基础分支冲突的 PR 会启动一次运行，合并基础分支并解决冲突；无法解决的冲突会通过评论交还给人。
生成并维护 PR	冲突解决最大重试次数	默认 3。针对基础分支同一状态的尝试次数，基础分支有新提交后重新计数。
生成并维护 PR	PR 合并后删除 head 分支	可选。仍被其他打开的 PR 使用的分支会被保留。
生成并维护 PR	代码推送方式	Agent 提交成果的方式。自动（默认）在 Bot 有写权限时向仓库推送分支，否则回退到 AGit；分支始终推送分支；AGit 不在仓库留下分支，只需读权限；Fork 在 Agent 账号的 Fork 中工作；直接提交到目标分支不创建 PR，仅用于无需评审的仓库。
生成并维护 PR	将大型请求拆分为交付计划	可选。Agent 可判断请求无法放进一个便于评审的 PR，转而提交交付计划。
生成并维护 PR	交付计划审批	决定计划在第一步开始前何时需要人工批准：始终；仅当计划涉及其他仓库或超过 3 步；仅当计划把私有仓库移入更宽的可见范围；从不。
生成并维护 PR	修复安全发现	具有安全写权限的用户在发现页面请求时，为任意扫描器的发现创建修复 PR。
生成并维护 PR	自动修复新发现	为默认分支上不低于指定最低严重级别的新发现创建修复 PR；最多同时打开的修复 PR 数达到上限时暂停自动修复。
生成并维护 PR	等待误报检测	其他扫描器的发现只有在分诊 Agent 确认后才会被自动修复；安全扫描 Agent 报告的发现会立即修复。
审查代码	所有检查和审批通过后允许合并	见上一节说明。
分析 / 安全扫描	将创建的工单指派给 Agent	每个新建工单指派给所选 Agent，从而各自开启独立的 Agent 会话。当前作用域内没有其它 Agent 时，选择器会给出提示，但仍会显示以便发现该能力。
分析 / 安全扫描	将创建的工单指派给用户	可选。同时把生成的工单指派给这些用户。指派用户不会启动 Agent 会话，只是为工作指定负责人。
安全扫描	扫描间隔	可选 `6h`、`12h`、`24h`、`72h`、`168h`，默认 `24h`。仅当勾选「定时安全扫描」事件后生效；取消该事件即关闭定时扫描，间隔配置不再起作用。
安全扫描	发现的报告方式	整个仓库扫描的报告位置：每个发现一个新工单或仓库安全页面上的发现。PR 的扫描始终报告在该 PR 上。
安全扫描	检测误报	判断各类扫描器（代码扫描、依赖、机密）的发现是真实问题还是误报，并把结论记录在发现上。具有安全写权限的用户随时可在发现页面请求。
安全扫描	自动判断新发现	从指定最低严重级别起（严重、高及以上、中及以上、低及以上）判断默认分支的每个新发现。
安全扫描	自动驳回高可信度误报	高可信度的误报结论会驳回该发现。需要 Agent 账号具有安全写权限，驳回后可像普通驳回一样重新打开。
安全扫描	可信度级别	可选 `medium`（中高及以上）、`high`（仅高可信度）、`low`（低可信度及以上），默认 `medium`。

访问控制

每个 Agent 都可单独配置「谁可以命令它」。打开 Agent 列表并选择访问控制，或使用编辑页的访问控制按钮。

谁可以命令	含义
所有对仓库有写权限的人（默认）	只要拥有目标仓库写权限即可命令该 Agent。
仅所有者与名单内的主体	在仓库写权限之上，额外要求匹配命令名单。
仅所有者	仅 Agent 所有者可命令。

命令名单支持用户、组织团队与用户组三类主体，按名称解析后保存。名单只会收紧权限：

命令 Agent 始终需要目标仓库的写权限；
Agent 自身能做什么，仍取决于它的 Bot 账号在该仓库中的权限。

Agent 机密（Agent secrets）

Agent 运行时可读取机密，例如用于 MCP 服务器鉴权。引用方式为 MCP 声明中的 ${{ secrets.NAME }}。

作用域与继承

作用域	管理入口	可用范围
所有 Agent（实例级）	`Site Administration > Agents > Secrets`	此 Gitea 实例中的所有 Agent。
所有者	`User Settings > Agents > Secrets` 与 `Organization Settings > Agents > Secrets`	该用户或组织拥有的所有 Agent。
仓库	`Repository > Settings > Agent secrets`	为该仓库运行的所有 Agent。
Agent	各作用域下 Agent 编辑页的「机密」按钮	仅该 Agent。

继承顺序（从宽到窄）：实例 → 所有者 → 仓库 → Agent。同名机密由更具体的作用域覆盖，Agent 级配置优先级最高。每个页面也会列出从更宽作用域继承的机密，便于确认 Agent 实际可见的机密。

使用限制

值加密存储，只写不读，保存后只能替换，并会在运行日志中打码。
目标仓库的 .gitea/agents/mcp.json 可以覆盖 Agent 配置仓库中的 MCP 配置；其引用的机密名同样按上述作用域解析。

提示词、技能与 MCP

Agent 的系统提示词、技能与 MCP 服务不在 Agent 表单中编辑，而是通过 Git 仓库配置，因此每次改动都可追溯、可评审、可复现：每次运行都会记录所使用的配置提交，表单里只显示该仓库的链接。

Agent 配置仓库 `<agent-bot>/.agent`

每个 Agent 的配置来自它自己 Bot 账号下的私有仓库 .agent。运行令牌对它没有写权限，因此 Agent 无法改写自己的指令。

路径	作用
`system-prompt.md`	Agent 的系统提示词。
`skills/<名称>/SKILL.md`	Agent 可加载的技能，采用 Agent Skills 布局：每个技能一个目录，`SKILL.md` 以 YAML frontmatter 开头。
`mcp.json`	Agent 可使用的 MCP 服务，采用 Claude Desktop / Cursor / VS Code 共享的 `mcpServers` 结构。机密不写入此处，只以 `${{ secrets.NAME }}` 引用。
`settings.yml`	选择启用哪些已声明的技能与 MCP 服务。

settings.yml 示例：

version: v1
skills:
  - code-review
  - security-audit
# 为空表示启用 mcp.json 中声明的全部服务
mcp:
  - internal-docs

目标仓库 `.gitea/agents/<agent>.yml`

目标仓库可以为自己追加技能、关闭继承的技能、使用自己的 MCP 声明并追加提示词，文件名使用 Agent 名称：

# .gitea/agents/<agent 名称>.yml
# 追加仓库自己的技能
skills:
  - repo-conventions
# 关闭从 Agent 继承的技能
disable_skills:
  - security-audit
# 选择使用哪个 MCP 声明
mcp:
  - repo-tools
# 追加提示词，无法替换 Agent 提示词
prompt_append: |
  本仓库使用 Conventional Commits。

路径	作用
`.gitea/agents/<agent>.yml`	仓库级 Agent 配置，支持 `skills`、`disable_skills`、`mcp`、`prompt_append`。
`.gitea/agents/skills/<名称>/SKILL.md`	仓库自己的技能。
`.gitea/agents/mcp.json`	仓库自己的 MCP 声明。

限制与容错：

仓库只能追加提示词，不能替换 Agent 的提示词。
配置缺失或损坏不会导致运行失败，Agent 表单中的内联配置仍作为兜底。

运行机制与会话

事件发生，Gitea 找出处理该事件的 Agent（仓库所有者作用域 + 全局作用域），并为每个 Agent 创建会话。
Gitea 为本次运行生成工作流，并在标签匹配的 Runner 上启动 Actions run。
Runner 检出代码、安装 codet CLI、准备提示词与技能/MCP 配置，然后运行 Agent。
Agent 修改代码并推送分支；Gitea 将会话结果作为后续动作应用，例如创建或更新 PR、评论、评审与合并，并把进度实时展示在 Issue/PR 时间线中。

凭据

由人发起的运行会获得 Agent Bot 的会话令牌（session token）。它的有效期与该次运行的 Actions 任务一致，不存储、无需撤销，禁用 Agents 会让所有令牌立即失效。Agent Bot 没有长期凭据：它的个人访问令牌和 OAuth2 令牌都会被拒绝。
每个请求的有效权限是 Bot 权限、触发者权限与令牌范围（仓库、工单、包的写权限，不含管理与设置）的交集。因此 Agent 可以读取相关仓库，但绝不会做触发者本人做不到的事。
运行期间的搜索与列表只会显示 Bot 与触发者都能看到的仓库。
.agent 配置仓库对运行是只读的，因此 Agent 无法改写自己的指令。
无人发起的运行（例如定时扫描）没有会话令牌，仅受 Agent 账号本身的权限约束。
写请求超过 500 次的循环运行会被停止。

会话

会话将 codet 对话与 Gitea 上下文（仓库、Issue/PR，以及触发它的用户）绑定在一起。
同一 Issue 上的后续运行会续接同一个 codet 对话；仓库级运行（如定时扫描）以及会话仍在忙碌时会另开新会话。
每个后续动作都以「触发用户的权限」与「Agent 权限」的交集进行授权。
如果 Agent 正在运行，新请求会作为排队请求等待，并在当前运行结束后启动。等待时间超过排队请求有效期设置的请求会被丢弃，而不是继续启动。
当会话所属 PR 被合并或关闭、Issue 被关闭，或有更新的请求取代它时，会话会自动取消；用户也可以手动取消或重试。
Issue/PR 时间线会展示会话卡片及进度，并实时推送运行中会话的输出。
在评论中使用 @agent stop（也可用 cancel、abort）可以停止正在运行的 Agent，使用 @agent redo（也可用 restart、rerun、retry）可以丢弃本次运行并重新开始。
运行日志详细程度可通过仓库或组织的 Actions 变量 AGENT_LOG_EVENTS 控制：summary（默认）、verbose 或 off。

内置 `gitea` MCP 服务

每次运行都带有一个名为 gitea 的内置 MCP 服务，由 Gitea 针对该会话提供。它为 Agent 提供只读工具，例如失败的作业与日志、PR 差异与检查、评审线程、工单评论与引用、代码搜索与仓库上下文，以及推送规则校验等检查。gitea* 为保留名称，mcp.json 中声明的服务不能使用。工具调用仅限该会话，并与运行的其余部分采用相同的授权方式。

交付计划

为“生成并维护 PR”Agent 启用将大型请求拆分为交付计划后，Agent 可以用最多 12 步的计划回应大型请求，而不是提交一个过大的 PR。Gitea 每次调度一步，每一步有自己的 PR。

依赖前序步骤的步骤会基于前序步骤的分支，这些 PR 会在 PR 页面显示为堆叠（“堆叠中第 2 个，共 3 个”）。
根据交付计划审批设置，计划可能需要人工批准。步骤可以指向其他仓库。
计划进行期间，源工单上的提及或回复会让 Agent 修订计划，而不是另起一个单独的 PR。
所有步骤合并后，会由一次只读运行验证请求是否完成（验证中），随后计划变为完成。
计划卡片提供暂停计划、恢复计划、取消计划、标记完成，以及针对阻塞步骤的重试。步骤被阻塞的原因包括缺少权限、运行预算耗尽、父 PR 未合并即关闭等。

故障排查

现象	排查方向
保存按钮不可用或提示需要连接	当前作用域没有可用且已配置（URL 与 Token 均非空）的 Agent Connection；请先创建连接，或让管理员开放全局连接。
模型列表加载失败	检查 Connection 的 URL 与 Token 是否有效、网络是否可达；也可临时手动填写模型名称。
创建 Agent 时提示名称不可用	Agent 名称即 Bot 用户名，需符合用户名规则且全局唯一（含与已有用户重名）。
事件发生后没有运行	依次确认：Agents 开关已启用、Agent 属于该仓库所有者作用域或全局作用域、Agent 已选择正确的动作与事件、命令用户拥有仓库写权限、Runner 标签有在线 Runner。
需要 Agent 评审但未触发	确认「请求评审」或「被指派」事件已绑定到审查代码动作；请求 Agent 作为评审人时同时会指派该 Agent。
合并未执行	合并要求必需检查与分支保护审批全部满足；分支落后时需先更新分支，再等待检查通过后合并。
关闭 Agents 后页面 404	这是预期行为，用户与组织的 Agent 页面在关闭后隐藏且不可访问。

可用性

Agents 于 Gitea Enterprise v27 中引入。