MediaWiki

Manual:创建一个机器人

This page is a translated version of the page Manual:Creating a bot and the translation is 53% complete.
Outdated translations are marked like this.
Languages:

MediaWiki机器人或简称机器人是与维基百科（和其他维基媒体项目）互动的自动程序，就像是人类编辑者一样。 本页试图解释如何在维基媒体项目中使用机器人进行开发，其中大部分内容也可用于其他基于MediaWiki的维基站点。 下列的解释主要是針對那些有一定编程经验、但不知道如何将这些知识应用于创建MediaWiki机器人的人。

我为什么需要创建机器人？

机器人可以自动执行任务，而且速度比人类快得多。 如果您有一项需要执行多次的简单任务（例如，在一个有1000个页面的分类中的所有页面上添加一個模板 ），那么这项任务就是机器人比人类更适合来完成。

创建机器人前的注意事项

重复使用既有的机器人

去向某個既有的机器人提出要求總是要简单得多。如果你的要求只是周期性的，或者你不擅长编程，这通常是最好的解决方案。某些维基有专门的页面可以提出此类请求。 此外，还有许多的工具可供任何人使用。 其中大部分都采用了具有MediaWiki專用功能的增强型网络浏览器的形式。 The most popular of these is Project:AutoWikiBrowser (AWB), a browser specifically designed to assist with editing on Wikipedia and other Wikimedia projects. 更完整的工具列表请参见英语维基百科上的w:Wikipedia:Tools/Editing tools。 有許多工具，例如AWB，通常可以在对编程知之甚少或一无所知的情况下进行操作。

  注意：

重覆使用代码库

如果由于需求的频繁性或新颖性，您决定需要一个自己的机器人，那么您不需要从头开始编写。 许多机器人都会公布自己的源代码，有时只需很少的额外开发时间就能重复使用。 此外，还有许多标准的机器人框架可供下载。 这些框架佔机器人代码的绝大部分。 由于这些机器人框架已被普遍使用，复杂的编码工作也已由他人完成并经过了大量测试，因此基于这些框架的机器人更容易获得批准使用。 The most popular and common of these frameworks is Pywikibot (PWB), a bot framework written in Python. It is thoroughly documented and tested and many standardized Pywikibot scripts (bot instructions) are already available. 机器人框架的其他示例可参见下文。 对于某些机器人框架（如PWB），只需熟悉脚本即可成功运行机器人（定期更新这些框架非常重要）。

重要问题

编写新机器人需要很强的编程能力。全新的机器人必须经过大量测试，才能获准正常运行。 规划对于获得无差错、高效率和高效益的计划至关重要。 以下的初步考虑非常重要：

  • 机器人是手动辅助还是全自动？
  • 您将独自创建机器人，还是在其他程序员的帮助下创建？
  • 将使用哪种语言来实现机器人？
  • 机器人的请求、编辑或其他操作是否会被记录？如果是，日志是存储在本地的媒体上，还是wiki的页面上？
  • 机器人是在网络浏览器中运行（例如用JavaScript编写），还是独立的程序？
  • If the bot is a standalone program, will it run on your local computer, or on a remote server such as the Toolforge?
  • 如果机器人是运行在远程服务器上，其他编辑者是否可以操作机器人或启动它？

MediaWiki机器人是如何工作的？

运行概览

MediaWiki机器人就像人类编辑一样，也会阅读wiki页面，并在它认为需要修改的地方进行修改。 不同之处在于，虽然机器人比人类速度更快、更不容易疲劳，但它们远没有我们聪明。 机器人擅长重复性任务，这些任务的模式很容易确定，不需要做太多决定。

在最典型的情况下，机器人登录自己的账户，以与浏览器大致相同的方式从维基请求页面--尽管它不会在屏幕上显示页面，而是在内存中运行--然后以编程方式检查页面代码，看是否需要进行任何更改。 然后，它就会以与浏览器大致相同的方式，进行并提交它所设计的任何编辑。

由于机器人访问网页的方式与人类相同，因此机器人也会遇到与人类用户相同的困难。 他们在申请页面或进行编辑时，可能会陷入编辑冲突、页面超时或遇到其他意想不到的复杂情况。 由于机器人的工作量大于真人，因此机器人更容易遇到这些问题。 因此，在编写机器人时必须考虑到这些情况。

机器人的应用程序接口

为了修改wiki页面，机器人必须从wiki中取回页面，然後将编辑内容发送回去。 有几种应用程序编程接口（API）可用于此目的。

某些网络服务器被配置为允许压缩（gzip）内容的请求。 这可以通过在HTTP请求头中加入一行“Accept-Encoding: gzip”来实现；如果HTTP回复头包含“Content-Encoding: gzip”，则文档为gzip格式，否则为普通的未压缩格式。 请注意，这是针对网络服务器而非MediaWiki软件的。 其他使用MediaWiki的网站可能没有这项功能。 如果您使用的是现有的机器人框架，它应该可以处理类似的底层操作。

登录

经批准的机器人需要登录后才能进行编辑。 虽然机器人可以在不登录的情况下提出读取请求，但已完成测试的机器人应登录所有活动。 通过带有机器人标志（见下文#机器人标志）的账户登录的机器人可以从 Mediawiki API (api.php) 中每次查询获得更多结果。 大多数的机器人框架都会自动处理登录和Cookie，但如果您没有使用现有框架，则需要按照以下步骤操作。

为了安全起见，必须使用HTTP POST方法传递登录数据。 由于在URL中HTTP GET所请求的参数很容易看到，因此通过GET登录已被禁止。

若要使用MediaWiki API 登录机器人，需要有2个POST的请求：

Request 1 – this is a GET request to obtain a login token

This will return a "logintoken" parameter in JSON form, as documented at API:登录 . 还提供其他输出格式。 它还会返回HTTP cookie，如下所述。

Request 2 – this is a POST to complete the login

其中，TOKEN 是上一个结果中的标记。 前一个请求的HTTP cookie也必须與第二个请求一起传递。

成功登录会导致维基媒体服务器设置多个HTTP cookie。 机器人必须保存这些 cookie，并在每次请求时将它们发送回来（这对编辑尤为重要）。 在英文维基百科上，应使用以下列cookie： enwikiUserID、enwikiToken和enwikiUserName。 The enwikisession cookie is required to actually send an edit or commit some change, otherwise the MediaWiki:Session fail preview error message will be returned.

Main-account login via action=login is deprecated and may stop working without warning. To continue using bot code which logs in with action=login, see Special:BotPasswords.

编辑；编辑令牌

MediaWiki uses a system of edit tokens for making edits to MediaWiki pages, as well as other operations that modify existing content such as rollback. The token looks like a long hexadecimal number followed by '+\', for example:

d41d8cd98f00b204e9800998ecf8427e+\

编辑令牌的作用是防止“编辑劫持”，即用户通过单击单个链接被诱骗进行编辑。

编辑过程涉及两个HTTP请求。 首先，必须发出编辑令牌的请求。 然后，必须发出第二个HTTP请求，该请求将页面的新内容与刚刚获得的编辑令牌一起发送。 无法在单个HTTP请求中进行编辑。 编辑令牌在登录会话期间保持不变，因此只需检索一次编辑令牌，即可用于所有后续编辑。

若要获取编辑令牌，请按照下列步骤操作：

If the edit token the bot receives does not have the hexadecimal string (i.e., the edit token is just '+\') then the bot most likely is not logged in. 这可能是由于多种因素造成的：服务器身份验证失败、连接断开、某种超时或存储或返回正确cookie时出错。 如果不是因为编程错误，只需重新登录即可刷新登录cookie。 The bots must use assertion to make sure that they are logged in.

编辑冲突

当在同一页面上进行多次重叠的编辑尝试时，会发生编辑冲突。 几乎每个机器人最终都会陷入这样或那样的编辑冲突中，并且应该包括一些机制来测试和适应这些问题。

Bots that use the Mediawiki API (api.php) should retrieve the edit token, along with the starttimestamp and the last revision "base" timestamp, before loading the page text in preparation for the edit; prop=info|revisions can be used to retrieve both the token and page contents in one query. Example:

api.php?titles=Wikipedia:Sandbox&prop=info&inprop=&intoken=edit&rvprop=timestamp [在Api沙盒中尝试]

When submitting the edit, set the starttimestamp and basetimestamp attributes, and check the server responses for indications of errors. For more details, see API:Edit - Create&Edit pages .

一般来说，如果编辑未能完成，机器人应在尝试进行新编辑之前再次检查页面，以确保编辑仍然合适。 此外，如果机器人重新检查页面以重新提交更改，则应注意避免任何可能导致无限循环的行为，以及任何可能类似于编辑战的行为。

机器人开发过程概述

实际上，编写机器人只是开发机器人的一部分。

下面的开发周期是英文维基百科的建议。

 
Overview of English Wikipedia bot development cycle

在维基媒体wiki上，确保您的机器人遵循wiki的任何潜在机器人政策。

建议

  • 创建MediaWiki机器人的首要任务是提取需求或提出想法。
  • 确保现有机器人尚未执行您认为机器人应该执行的操作。

规范

  • Specification is the task of precisely describing the software to be written, possibly in a rigorous way. 您应该提出一个详细的建议，说明您希望它做什么。 尝试与一些编者讨论此提案，并根据反馈对其进行完善。 即使是一个好主意，也可以通过结合其他编者的想法来变得更好。
  • 在最基本的形式中，您指定的机器人必须满足以下条件：
  • 机器人是无害的（它不得进行可能被认为破坏wiki平稳运行的编辑）
  • 机器人很有用（它比人工编辑更有效地提供有用的服务）
  • 机器人不会浪费服务器资源。

软件架构

  • Think about how you might create it and which programming language(s) and tools you would use. Architecture is concerned with making sure the software system will meet the requirements of the product as well as ensuring that future requirements can be addressed. 某些编程语言比其他编程语言更适合某些任务，有关详细信息，请参见下面的编程语言部分。

实现

实现（或编码）涉及将设计和规划转化为代码。 它可能是软件工程工作中最明显的部分，但不一定是最大的部分。 在实施阶段，您应该：

  • Create an account for your bot. Go to the sign up page when logged in to create the account, linking it to yours. (If you do not create the bot account while logged in, it might be blocked on some wikis according to their policies)
  • 为您的机器人创建一个用户页。 您的机器人的编辑不得在您自己的帐户下进行。 机器人将需要自己的帐户，并具有自己的用户名和密码。
  • 将相同的信息添加到机器人的用户页面。 最好为每个功能添加一个指向批准页面（无论是否批准）的链接。
  • 使用所选的编程语言对机器人进行编码。

测试

在开发过程中测试机器人的一个好方法是让它显示它对页面所做的更改（如果有），而不是实际编辑实时wiki。 Some bot frameworks (such as pywikibot) have pre-coded methods for showing diffs.

编写文档

一个重要的（经常被忽视的）任务是编写文档记录机器人的内部设计，以便将来进行维护和增强。 如果要允许克隆机器人，这一点尤其重要。 理想情况下，如果您希望其他人能够运行机器人的克隆，则应将机器人的源代码发布在其用户页面或版本控制系统中（请参阅#开源机器人）。 为了便于使用，此代码应有详细的文档记录（通常使用注释）。

查询/投诉

您应该准备好在用户讨论页上回复有关机器人的查询或异议，尤其是当它在潜在的敏感区域运行时。

维护

维护并增强机器人以应对新发现的错误或新要求可能比软件的初始开发花费更多的时间。 不仅可能有必要添加不适合原始设计的代码，而且仅仅确定软件在完成后的某个时候如何工作可能需要大量的工作（这是在编写过程中记录代码的另一个原因）。

运行机器人的一般准则

除了官方机器人政策（涵盖开发机器人时要考虑的要点）之外，在开发机器人时还需要考虑许多更一般的咨询要点。

机器人的最佳实践

  • Set a custom User-Agent header for your bot (per the Wikimedia User-Agent policy, if your bot will be operating on Wikimedia wikis). If you don't, your bot may encounter errors and may end up blocked at the server level.
  • Use the maxlag parameter with a maximum lag of 5 seconds. This will enable the bot to run quickly when server load is low, and throttle the bot when server load is high.
    • If writing a bot in a framework that does not support maxlag, limit the total requests (read and write requests together) to no more than 10/minute.
  • Use the MediaWiki API whenever possible, and set the query limits to the largest values that the server permits, to minimize the total number of requests that must be made.
  • Edit (write) requests are more expensive in server time than read requests. Be edit-light and design your code to keep edits to a minimum.
    • Try to consolidate edits. One single large edit is better than 10 smaller ones.
  • Enable HTTP persistent connections and compression in your HTTP client library, if possible.
  • Do not make multi-threaded requests. Wait for one server request to complete before beginning another
  • Back off upon receiving errors from the server. Errors such as timeouts are often an indication of heavy server load. Use a sequence of increasingly longer delays between repeated requests.
  • Make use of assertion to ensure your bot is logged in.
  • Test your code thoroughly before making large automated runs. Individually examine all edits on trial runs to verify they are perfect.

您应该考虑实现的常见机器人功能

人为协助

如果机器人正在执行任何需要判断或评估上下文（例如更正拼写）的操作，则应考虑人为协助机器人，这意味着人工会在保存所有编辑之前对其进行验证。 这大大降低了机器人的速度，但也大大减少了错误。

禁用机器人

如果要求的话，具有禁用机器人操作的功能是很好的机器人政策。 请记住，如果您的机器人宕机了，您有责任在进行善后处理！ You could have the bot refuse to run if a message has been left on its talk page, on the assumption that the message may be a complaint against its activities; this can be checked using the API meta=userinfo query. Example on English Wikipedia:

api.php?action=query&meta=userinfo&uiprop=hasmsg [在Api沙盒中尝试]

或者，您可以有一个页面，如果页面上的文本发生更改，该页面将关闭机器人（例如，要求页面为空，仅包含“True”一词或类似内容）;这可以通过在每次编辑之前加载页面内容来检查。

签名

就像人类一样，如果你的机器人在MediaWiki中编辑了一个讨论页，它应该用四个波浪号(~~~~)来签署它的提交。 签名通常仅出现在talk命名空间中。

机器人标识

A bot's edits will be visible at Special:RecentChanges, unless the edits are set to indicate a bot. Once the bot has been approved and given its bot flag permission, one can add the "bot=True" to the API call - see API:编辑 in order to hide the bot's edits in Special:RecentChanges.

In Python, using either mwclient or wikitools, then adding Bot=True to the edit/save command will set the edit as a bot edit - e.g. 
PageObject.edit(text=pagetext, bot=True, summary=pagesummary)

监视机器人状态

如果机器人是完全自动化的并执行定期编辑，则应定期检查其按指定方式运行，并且其行为未因软件更改而改变。

开源机器人

许多机器人作者选择将其代码开源，有时可能需要在批准特别复杂的机器人之前进行开源。 使代码开源有几个优点：

  • 它允许其他人检查您的代码以查找潜在的bug。 与散文一样，代码作者通常很难对其进行充分审查。
  • 其他人可以使用你的代码来构建自己的机器人。 不熟悉机器人编写的用户可能能够将你的代码用作他们自己的机器人的示例或模板。
  • 它鼓励良好的安全实践，而不是隐晦式安全。
  • 如果您离开了项目，则允许其他用户运行机器人任务，而无需编写新代码。

开源代码虽然很少被要求，但通常鼓励与wiki的开放和透明性质保持一致，尽管在某些情况下代码不应该公开。 例如，ProcseeBot可能被用于其他站点的恶意目的。

将代码开源会给编码增加一些额外的工作。 必须确保将密码等敏感信息分离到一个不公开的文件中。

对于希望打开其代码的用户，有几个选项可用。 一些用户选择将代码放在机器人用户空间的子页面中，尽管如果不自动化，维护起来可能会很麻烦，并且除了您可能指定的任何其他条款外，还会导致代码根据wiki的许可条款获得多重许可。 另一种解决方案是使用修订控制系统，例如 SVN、Git或Mercurial。 维基百科上有比较不同软件选择和 代码托管网站的文章，其中许多是免费的。 维基媒体还为其用户提供Git代码存储库托管，并通过维基媒体云服务。

编程语言和库

See also: API:客户端代码

机器人几乎可以用任何编程语言编写。 语言的选择通常取决于机器人编写者的经验（熟悉的语言）或预先开发的库的可用性来执行所需的任务。 以下列表包括一些具有相关库来帮助执行机器人任务的语言。

Awk

Perl

如果位于网络服务器上，则可以在程序运行时启动程序运行，并在程序运行时通过浏览器的通用网关接口与程序进行交互。 如果您的互联网服务提供商为您提供了网络空间，那么您很有可能可以在网络服务器上访问一个perl版本，您可以从中运行您的Perl程序。

相关库：

  • MediaWiki::API – Basic interface to the API, allowing scripts to automate editing and extraction of data from MediaWiki driven sites.
  • MediaWiki::Bot – A fairly complete MediaWiki bot framework written in Perl. Provides a higher level of abstraction than MediaWiki::API. Plugins provide administrator and steward functionality. Currently unsupported.

PHP

PHP也可用于机器人编程。 MediaWiki开发人员已经熟悉PHP，因为这是MediaWiki及其扩展的编写语言。 如果您希望为机器人提供基于web表单的界面，PHP是一个特别好的选择。 例如，假设您要创建一个用于重命名分类的机器人。 您可以创建一个HTML表单，在其中输入分类的当前名称和所需名称。 提交表单后，机器人可以读取这些输入，然后编辑当前分类中的所有文章并将它们移动到所需分类。 （显然，任何具有表单界面的机器人都需要以某种方式保护随机网络冲浪者。）

英语维基百科上的PHP机器人功能表可能会提供一些关于主要机器人框架功能的见解。

PHP Bot frameworks
Key people[php 1] Name PHP Version last update Uses API[php 2] Exclusion compliant Admin functions Plugins Repository Notes
Cyberpower678, Addshore, and Jarry1250 Peachy 5.2.1 2015 是 是 是 是 GitHub Large framework, currently undergoing rewrite. Documentation currently non-existent, so poke w:User:Cyberpower678 for help.
Addshore mediawiki-api-base 7.4+ 2021 是 N/A N/A extra libs GitHub Base library for interaction with the mediawiki api, provides you with ways to handle logging in, out and handling tokens as well as easily getting and posting requests.
Addshore mediawiki-api 7.4+ 2021 是 No some extra libs GitHub Build on top of mediawiki-api-base this adds more advanced services for the api such as RevisionGetter, UserGetter, PageDeleter, RevisionPatroller, RevisionSaver etc.
Kaspo Phpwikibot Unknown 2009 Partial No No No Google Code Uses a single class.
Jarry1250 Wikibot 5 2009 是 是 No No enwiki Used solely by LivingBot. A fork of Phpwikibot. Uses a single class.
Foxy Loxy PHPediaWiki 5 2009 是 No 是 No SourceForge Fork of SxWiki
Nzhamstar, Xymph, Waldyrious Wikimate 5.3-5.6,
7.x, 8.x		 2023 是 No No No GitHub Supports main article and file stuff. Authentication, checking if pages exist, reading and editing pages/sections. Getting file information, downloading and uploading files. Aims to be easy to use.
Kaleb Heitzman MediaWIkiBot 5 2012 是 No No No GitHub Supports the entire API including uploading and importing. Also supports Semantic MediaWiki. Single Class that creates dynamic methods to work with any of the API calls.
Edward Z. Yang Wikipedia Bot in PHP Unknown 2005 No No No No enwiki "Probably stale" source code
Cobi wikibot.classes 5 2010 是 是 No No enwiki Used by multiple large bots (e.g. ClueBot and SoxBot). Uses several classes.
Valerio Bozzolan boz-mw 5.6 2019 是 N/A 是 extra libs GitHub Object-oriented. 80+ classes also to handle Wikidata. Inline documentation. Support for file uploading.
  1. ↑ Does not include those who worked on frameworks forked to create listed framework.
  2. ↑ Where possible. Excludes uploading images and other such tasks which are not currently supported by the API.

Python

Python是一种流行的解释型语言，具有面向对象的功能。

Libraries
Please help update this table.
Python Bot frameworks
Key people[py 1] Name Python Version last update Uses API[py 2] Exclusion compliant Admin functions Plugins Repository Notes
xqt Pywikibot Python 3.7 or higher or PyPy 2023 是 是 是 是

最常用的Python机器人框架。包括现成的脚本。

Myst WikibaseIntegrator Python 3.7 or higher 2022 是 Not applicable 是 No GitHub Only to interact with Wikibase instances like Wikidata
Mr.Z-man wikitools 2 2016 GitHub Incompatible with Python 3. (downloads)
Bryan mwclient 2021 GitHub An API-based framework
The Earwig mwparserfromhell 2021 GitHub A Python parser for MediaWiki text
  1. ↑ Does not include those who worked on frameworks forked to create listed framework.
  2. ↑ Where possible. Excludes uploading images and other such tasks which are not currently supported by the API.

Microsoft .NET

Microsoft .NET是一组语言，包括C#、C++/CLI、Visual Basic .NET、J#、JScript .NET、IronPython和PowerShell。 Microsoft Visual Studio集成开发环境或者免费的Microsoft Visual Studio Express版本经常被用于相关开发。 使用Mono项目，.NET程序也可以在Linux、Unix、BSD、Solaris和Mac OS X以及Windows上运行。

相关库：

  • DotNetWikiBot Framework – a full-featured client API on .NET, that allows to build programs and web robots easily to manage information on MediaWiki-powered sites. Now translated to several languages. Detailed compiled documentation is available in English.
  • WikiFunctions .NET library – Bundled with AWB, is a library of stuff useful for bots, such as generating lists, loading/editing articles, connecting to the recent changes IRC channel and more.

Java

Java程序通常使用IDE开发，例如Eclipse或NetBeans；使用命令行控制台（通过javac和Java程序）进行开发也是一种选择。

相关库：

  • Java Wiki Bot Framework – A Java wiki bot framework
  • wiki-java – A Java wiki bot framework that is only one file
  • WPCleaner – The library used by the WPCleaner tool
  • jwiki – A simple and easy-to-use Java wiki bot framework

JavaScript（Node.js）

JavaScript是一种脚本语言，主要用于网页，例如添加到您的vector.js或您的monobook.js页面的用户脚本。 使用Node.js可以在服务器端使用JavaScript，例如用于开发机器人。

Please help to update this table.
NodeJS Bot frameworks
Key people[js 1] Name Nodejs Version last update Uses API[js 2] Exclusion compliant Admin functions Package Repository Notes
SD0001 mwn 10+ 2021 是 是 是 npm GitHub Large library with classes for working with page titles and wikitext. Works with TypeScript also. Promise-based API (async–await). Limited wikitext parsing capabilities.
kanashimi wikiapi 0.10–15.x 2021 是 是 Partial npm GitHub JavaScript MediaWiki API for node.js with modern ECMAScript 2016 async–await and wikitext parser.
MediaWiki module 2014 GitHub Provides a framework of standard requests (e.g. log in, log out, etc.) as well as a general wrapper method for the MediaWiki API and includes throttling. The module can also be added to your Wikimedia .js page and used as library for on-wiki JS calls.
  1. ↑ Does not include those who worked on frameworks forked to create listed framework.
  2. ↑ Where possible. Excludes uploading images and other such tasks which are not currently supported by the API.

Ruby

Ruby是一种流行的动态的、面向对象的编程语言。

相关库：

  • MediaWiki::Butt - Ruby framework for the API in active development. Tested with versions as up-to-date as CurseGamepedia is.
  • mediawiki/ruby/api, Ruby API client library. Last updated December 2017, no longer maintained, but still works.
  • MediaWiki::Gateway – Ruby framework for the API. Last updated January 2016. No longer in active development, tested up to MediaWiki 1.22, compatible with Wikimedia wikis. Unknown if still works.
  • wikipedia-client - Ruby framework using the API. Last updated March 2018. Unknown if still works.

Common Lisp

  • CL-MediaWiki implements MediaWiki API as a Common Lisp package. Is planned to use JSON as a query data format. Supports maxlag and assertion.

Haskell

VBScript

VBScript是一种基于Visual Basic编程语言的脚本语言。 VBScript没有已发布的机器人框架，但可以使用它的一些机器人示例如下：

示例：

Bash

Bash是一种Unix shell。

Retrieved from "https://www.mediawiki.org/w/index.php?title=Manual:Creating_a_bot/zh&oldid=6845353"