contact-congress完整指南：12个变量占位符让国会表单填写自动化不再头疼

contact-congress完整指南：12个变量占位符让国会表单填写自动化不再头疼

【免费下载链接】contact-congressSending electronic written messages to members of Congress by reverse engineering their contact forms.项目地址: https://gitcode.com/gh_mirrors/co/contact-congress

想给美国国会议员发送电子信件，却要挨个访问几百个风格各异的联系表单？contact-congress正是为解决这个问题而生的开源项目：它通过逆向工程国会议员的网页联系表单，用人类可读的 YAML 数据格式描述"如何成功填完一张表单"，让国会表单填写自动化变得简单、免费且可维护。本指南将带你认识这个项目，并重点拆解其中最核心的12 个变量占位符，让你快速上手。

为什么国会表单填写自动化如此困难？🤔

国会议员并没有公开的电子邮箱地址，想在线联系他们，唯一途径就是填写各自官网上的联系表单。问题在于：

• 全美共有540 多位国会议员（100 位参议员 + 众议员），每个人的表单结构、字段名、CSS 选择器都不一样；
• 表单可能包含验证码、下拉框、单选按钮甚至 iframe，普通脚本很难统一处理；
• 请第三方服务商代发费用高昂，对小型公益组织并不友好。

contact-congress 的思路是：把"填表流程"本身变成一份开放数据。任何组织或个人都能免费使用这份数据，构建自己的自动化发送工具，不必再为追踪议员网站改版而头疼。

contact-congress 如何工作：YAML + 变量占位符 🔧

项目用 YAML 描述填表的完整步骤，顶层只有两个字段：bioguide（议员的 Bioguide ID，用于关联其他数据源）和contact_form（表单填写的核心细节）。完整的字段规范见 documentation/schema.md。

一份表单 YAML 大致长这样（以模板support/template.yaml为参考）：

bioguide: S000033 contact_form: method: POST action: https://www.sanders.senate.gov/contact/contact-form/ steps: - visit: https://www.sanders.senate.gov/contact/contact-form/ - fill_in: - name: FirstName selector: "input[name='FirstName']" value: "$NAME_FIRST" required: Yes - click_on: - selector: ".wpcf7-submit" success: body: contains: "Thank you"

注意value字段里的$NAME_FIRST——它就是一个变量占位符。占位符让同一份表单数据可以复用到任意用户身上：填表时，程序只需把每个占位符替换成真实用户的信息即可，无需为每个用户重写表单定义。

12 个核心变量占位符详解 📋

以下是你在support/variables.yaml中会经常用到的 12 个变量占位符，覆盖了绝大多数表单的必填字段：

除了这 12 个，support/variables.yaml里还定义了$ADDRESS_STREET_2（地址第二行）、$ADDRESS_COUNTY（县）、$ADDRESS_STATE_FULL（州全名）、$ADDRESS_ZIP4、$PHONE_PARENTHESES（带括号区号的电话）、$TOPIC（议题）、$SUBJECT（邮件主题）、$CAPTCHA_SOLUTION（验证码答案）、$CAMPAIGN_UUID（活动标识）等，总共 20 余个，按需取用即可。

一个真实案例：自动填写参议员联系表单 ✅

以members/S000033.yaml（伯尼·桑德斯议员的表单）为例，可以看到占位符是如何被组合使用的：

- fill_in: - name: FirstName selector: "input[name='FirstName']" value: "$NAME_FIRST" - name: LastName selector: "input[name='LastName']" value: "$NAME_LAST" - name: Address1 selector: "input[name='Address1']" value: "$ADDRESS_STREET" - name: City selector: "input[name='City']" value: "$ADDRESS_CITY" - name: ZipCode selector: "input[name='ZipCode']" value: "$ADDRESS_ZIP5" - name: your-email selector: "input[name='your-email']" value: "$EMAIL" - name: your-message selector: "textarea[name='your-message']" value: "$MESSAGE"

一个姓名、地址、邮箱、信件正文的完整组合就这样完成了。填写完毕后，再用click_on点击提交按钮，并通过success字段校验是否成功（例如响应正文包含 "Thank you"）。

特殊场景：验证码与复杂控件怎么处理？🛡️

表单自动化最大的拦路虎是验证码。contact-congress 对此也有约定：

• 传统验证码：用$CAPTCHA_SOLUTION占位符标记验证码输入框，并通过captcha_selector指定验证码图片的位置，交由实现方去识别或人工处理；
• Google ReCAPTCHA：提供recaptcha指令，放在最终提交步骤之前，配合support/recaptcha-noscript.yaml中的示例使用；
• 重试机制：表单定义支持retry数组，当验证码错误等特定失败信号出现时，重新提交相应字段。

此外，choose可以处理单选/多选按钮，select处理下拉框。当某些下拉选项在不同议员的表单中高度一致时，还可以引用support/constants.yaml中的常量（如 50 个州加华盛顿特区的缩写列表US_STATES），避免重复维护。

如何开始使用 contact-congress ？🚀

想立刻开始探索这份国会表单数据集，只需克隆仓库：

git clone https://gitcode.com/gh_mirrors/co/contact-congress

克隆后你可以：

1. 查看数据：members/目录下是按 Bioguide ID 命名的 YAML 文件，如A000360.yaml、S000033.yaml，覆盖了几乎全部参议员与大部分众议员；
2. 了解规范：阅读documentation/schema.md掌握所有字段含义，参考support/template.yaml快速开始；
3. 贡献数据：如果你发现某位议员表单缺失或已失效，可以参考documentation/how_to_contribute.md，编写 YAML 后提交 Pull Request——每一份文件都可能帮助成千上万的公民联系到他们的代表；
4. 构建工具：这份数据是纯格式描述，你可以用它驱动自己的自动化填表程序，实现批量、定制的国会表单填写自动化。

常见问题 ❓

Q：项目现在还维护吗？A：众议院部分已逐渐转向使用国会官方的 CWC API 发送消息，但参议院 YAML 数据仍在维护，且众议院文件依然欢迎提交 PR。

Q：这份数据能直接发送邮件吗？A：不能。contact-congress 只是数据层，你需要自己构建发送与错误处理系统，但它帮你省去了最痛苦的逆向工程环节。

Q：怎么关联议员的更多资料？A：通过每个文件顶层的bioguide字段，可以轻松关联到其他开源数据集中的议员详细信息。

Q：字段太多记不住怎么办？A：常用字段集中在support/variables.yaml，占位符以$开头，与表单中可能出现的全大写字符串天然区分，不用担心混淆。

现在，打开support/variables.yaml和members/下的示例文件，亲手体验一把这份"议员联系表单说明书"吧——让繁琐的国会表单填写自动化从此不再头疼！🎉

【免费下载链接】contact-congressSending electronic written messages to members of Congress by reverse engineering their contact forms.项目地址: https://gitcode.com/gh_mirrors/co/contact-congress