Google Forms AI Research Filler

A Chrome MV3 research extension for Google Forms. It reads supported choice questions, asks an OpenAI-compatible model for an answer decision, and fills the selected option. It never submits a form.

中文文档 | English Documentation

中文文档

项目定位

Google Forms AI Research Filler 是一个技术研究用途的 Chrome 扩展。它面向受控测试表单、内部研究表单和自动化能力验证场景，帮助开发者研究：

Google Forms 页面结构解析
Chrome MV3 content script 与 service worker 协作
OpenAI-compatible API 的答案选择工作流
本地浏览器扩展配置、权限和测试策略

它不是考试、作业或任何学术诚信规避工具。当前实现不会自动点击 Submit，也不会绕过 Google 登录、验证码、权限控制或表单限制。

当前能力

能力	状态
Chrome Manifest V3 扩展	已支持
GUI 配置页	已支持
`baseUrl` / `apiKey` / `model` 配置	已支持
默认无 OAuth 的 DOM mode	已支持
GUI 中切换 API-assisted mode	已支持，位于 Advanced options
Popup 开启/关闭点击作答模式	已支持
Google Forms 单选题	已支持
Google Forms 下拉题	已支持
多选 checkbox	已支持
JSON code block 配置编辑器	暂未支持
自动提交表单	不支持，且刻意禁止

架构概览

flowchart LR
  A["Google Forms page"] --> B["Content script"]
  B --> C["Background service worker"]
  C --> D["OpenAI-compatible API"]
  C -. "optional readonly structure" .-> E["Google Forms API"]
  F["Options GUI"] --> G["chrome.storage.local"]
  C --> G

Content script 只读取页面中的题目和选项，并只接收答案索引或多选索引。
API key 保存在 chrome.storage.local，不传给 content script。
Background service worker 负责 provider 调用和可选 Forms API-assisted 结构读取。
默认 DOM mode 不需要 Google OAuth。
API-assisted mode 是高级选项，需要配置 Chrome OAuth client id 后才可使用。
Popup 只控制“点击题目空白处自动作答”模式，不提供整表一键填充按钮。

安装和使用

1. 安装依赖

npm install

2. 构建扩展

npm run build

构建产物会输出到：

dist/

3. 在 Chrome 加载扩展

打开 chrome://extensions
开启 Developer mode
点击 Load unpacked
选择本项目的 dist 目录

4. 配置模型服务

打开扩展的 Options 页面，填写：

Base URL，例如 https://api.openai.com/v1
API key
Model，例如 gpt-4.1-mini
Temperature，默认 0
勾选 research-only use 确认

默认模式是 DOM mode，不需要 Google OAuth。

如果你使用本地 OpenAI-compatible 服务，可以使用：

http://localhost:8000/v1

出于安全考虑，HTTP provider 只允许 localhost、127.0.0.1 或 ::1。

5. 开启点击作答模式

打开一个 Google Forms respondent 页面
点击浏览器工具栏中的扩展图标
点击 Enable click answer
回到表单，单击某个题目卡片内的空白区域
扩展只会为被点击的这一题作答
检查填充结果
如需提交，必须由用户手动点击 Submit

扩展不会自动提交表单。

点击选项、按钮、输入框、链接或题卡外空白区域不会触发自动作答。已作答题会被跳过。

Advanced options

Options GUI 中的 Advanced options 提供：

Mode
- DOM mode：默认模式，无需 OAuth，直接解析页面
- API-assisted mode：可选增强模式，通过 Google Forms API 读取表单结构辅助匹配
Confidence threshold：低于阈值的模型答案会跳过

API-assisted mode 需要在 public/manifest.json 中替换：

"client_id": "__GOOGLE_CLIENT_ID_CONFIGURED_BY_DEVELOPER__"

替换为你自己的 Chrome extension OAuth client id。

开发者维护指南

常用命令

npm run build
npm run typecheck
npm run lint
npm test
npm run test:coverage
npm run test:e2e
npm run test:e2e:live
npm run security:check
npm audit

目录说明

src/background/   service worker、消息边界、provider 调用
src/content/      Google Forms 页面脚本、点击题卡空白监听、DOM 填充
src/forms/        Forms DOM parser 和 Forms API readonly client
src/options/      Options GUI
src/popup/        Popup GUI 和状态入口
src/provider/     OpenAI-compatible API client
src/runtime/      runtime message contracts
src/ui/           配置存储和 provider 权限请求
tests/e2e/        Playwright 本地 fixture 测试
fixtures/         Google Forms-like 本地测试页面
scripts/          构建、fixture server、安全扫描脚本

真实表单烟测

项目包含一个手动触发的 live smoke test，使用当前研究表单验证真实 Google Forms 页面能加载并暴露选择题结构：

npm run test:e2e:live

该测试不会自动提交表单，只检查页面可访问、radio 选项存在、Submit 没有被触发。默认 npm run test:e2e 不运行 live test。

维护题型支持

当前支持 radio、dropdown 和 checkbox。维护或扩展题型时：

在 src/types.ts 扩展 question type 和 answer shape
在 src/forms/formsParser.test.ts 先添加 RED 测试
更新 src/forms/formsParser.ts 的提取和填充逻辑
更新 provider prompt 和 answer normalization
增加 E2E fixture，确认不会点击 Submit
跑完整 verification gate

修改 provider 协议

Provider 入口在 src/provider/openAiCompatibleClient.ts。保持这些约束：

API key 不进入 content script
请求只从 background 发起
模型输出必须是 JSON
越界 option index、低 confidence、非 JSON 都跳过
错误消息不要泄露 provider response body 或密钥

发布前检查清单

npm run build 成功
npm run typecheck 成功
npm run lint 成功
npm run test:coverage 达到 80%+
npm run test:e2e 成功
npm run security:check 成功
npm audit 无漏洞
git diff 中没有 API key、OAuth secret、测试账号或真实表单数据
手动确认扩展不会点击 Submit

Git 约定

使用 Conventional Commits：

feat(forms): add checkbox extraction
fix(provider): handle empty model output
test(e2e): cover click answer mode
docs(readme): update installation guide
chore: verify extension release baseline

每个可回滚阶段单独提交。不要 squash TDD checkpoint，除非团队明确决定整理历史。

English Documentation

Product Scope

Google Forms AI Research Filler is a Chrome extension for technical research. It is designed for controlled test forms, internal research workflows, and automation experiments where engineers need to study:

Google Forms page parsing
Chrome MV3 content script and service worker coordination
OpenAI-compatible answer-selection workflows
Local extension configuration, permissions, and test strategy

It is not a tool for exams, assignments, or academic-integrity bypass. The extension never clicks Submit and does not bypass Google login, CAPTCHA, access control, or form restrictions.

Current Capabilities

Capability	Status
Chrome Manifest V3 extension	Supported
GUI options page	Supported
`baseUrl` / `apiKey` / `model` configuration	Supported
OAuth-free DOM mode by default	Supported
API-assisted mode switch in GUI	Supported, under Advanced options
Popup enable/disable click-answer mode	Supported
Google Forms radio questions	Supported
Google Forms dropdown questions	Supported
Checkbox multi-select	Supported
Editable JSON code block config	Not yet supported
Automatic form submission	Not supported by design

Architecture

flowchart LR
  A["Google Forms page"] --> B["Content script"]
  B --> C["Background service worker"]
  C --> D["OpenAI-compatible API"]
  C -. "optional readonly structure" .-> E["Google Forms API"]
  F["Options GUI"] --> G["chrome.storage.local"]
  C --> G

The content script reads prompts/options and receives answer indices or multi-select indices only.
The API key is stored in chrome.storage.local and is never sent to the content script.
The background service worker owns provider calls and optional Forms API-assisted reads.
DOM mode is the default and does not require Google OAuth.
API-assisted mode is an advanced option and requires a real Chrome extension OAuth client id.
The popup controls click-answer mode. It does not expose a whole-form fill button.

Installation and Usage

1. Install dependencies

npm install

2. Build the extension

npm run build

The unpacked extension is generated at:

dist/

3. Load in Chrome

Open chrome://extensions
Enable Developer mode
Click Load unpacked
Select this project's dist directory

4. Configure the provider

Open the extension Options page and fill in:

Base URL, for example https://api.openai.com/v1
API key
Model, for example gpt-4.1-mini
Temperature, default 0
Research-only use confirmation

DOM mode is the default and does not require Google OAuth.

For local OpenAI-compatible services, use a localhost endpoint such as:

http://localhost:8000/v1

For safety, HTTP provider URLs are limited to localhost, 127.0.0.1, or ::1.

5. Enable Click Answer

Open a Google Forms respondent page
Click the extension icon in the browser toolbar
Click Enable click answer
Return to the form and click blank space inside one question card
The extension answers only the clicked question
Review the filled result
Submit manually if appropriate

The extension never submits a form automatically.

Clicks on options, buttons, inputs, links, or page space outside a question card do not trigger AI answering. Already answered questions are skipped.

Advanced Options

The Options GUI exposes Advanced options:

Mode
- DOM mode: default, no OAuth, parses the page directly
- API-assisted mode: optional, reads readonly form structure through Google Forms API
Confidence threshold: model answers below the threshold are skipped

To use API-assisted mode, replace the placeholder in public/manifest.json:

"client_id": "__GOOGLE_CLIENT_ID_CONFIGURED_BY_DEVELOPER__"

Use your own Chrome extension OAuth client id.

Developer Maintenance Guide

Commands

npm run build
npm run typecheck
npm run lint
npm test
npm run test:coverage
npm run test:e2e
npm run test:e2e:live
npm run security:check
npm audit

Project Layout

src/background/   service worker, message boundary, provider calls
src/content/      Google Forms content script, blank question-card click listener, DOM filling
src/forms/        Forms DOM parser and readonly Forms API client
src/options/      Options GUI
src/popup/        Popup GUI and status entrypoint
src/provider/     OpenAI-compatible API client
src/runtime/      runtime message contracts
src/ui/           config storage and provider permission requests
tests/e2e/        Playwright local fixture tests
fixtures/         local Google Forms-like test page
scripts/          build, fixture server, and security scan scripts

Live Form Smoke Test

The project includes an opt-in live smoke test that uses the current research form to verify that a real Google Forms page loads and exposes choice-question structure:

npm run test:e2e:live

The test never submits the form. It checks page accessibility, radio option presence, and that no /formResponse POST is triggered. The default npm run test:e2e command does not run live tests.

Maintaining Question Type Support

The current implementation supports radio, dropdown, and checkbox. When maintaining or adding question types:

Extend question and answer types in src/types.ts
Add failing tests in src/forms/formsParser.test.ts
Update extraction and filling in src/forms/formsParser.ts
Update provider prompt and answer normalization
Add an E2E fixture that proves Submit is never clicked
Run the full verification gate

Changing Provider Behavior

The provider entrypoint is src/provider/openAiCompatibleClient.ts. Preserve these rules:

API keys never enter the content script
Provider requests are made only from the background service worker
Model output must be JSON
Out-of-range indices, low confidence, and non-JSON output are skipped
Error messages must not expose provider response bodies or secrets

Release Checklist

npm run build passes
npm run typecheck passes
npm run lint passes
npm run test:coverage stays above 80%
npm run test:e2e passes
npm run security:check passes
npm audit reports no vulnerabilities
git diff contains no API keys, OAuth secrets, test accounts, or real form data
Manual check confirms the extension does not click Submit

Git Convention

Use Conventional Commits:

feat(forms): add checkbox extraction
fix(provider): handle empty model output
test(e2e): cover click answer mode
docs(readme): update installation guide
chore: verify extension release baseline

Keep each rollback point in its own commit. Do not squash TDD checkpoints unless the team explicitly chooses to rewrite history.

Name		Name	Last commit message	Last commit date
.agents/skills		.agents/skills
.claude		.claude
.github		.github
fixtures		fixtures
public		public
release		release
scripts		scripts
src		src
tests/e2e		tests/e2e
.gitignore		.gitignore
.gitmessage		.gitmessage
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
README.md		README.md
eslint.config.js		eslint.config.js
image.png		image.png
package-lock.json		package-lock.json
package.json		package.json
playwright.config.js		playwright.config.js
skills-lock.json		skills-lock.json
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts
vitest.setup.ts		vitest.setup.ts

Latest commit

History

Folders and files

Repository files navigation