MoonOS 是一个基于浏览器的 AI 操作系统：给定目标，Agent 自主完成感知 → 决策 → 执行循环直到任务结束。底层由 CloakBrowser（反检测 Chromium + Playwright 包装层）驱动，决策与视觉识别都可以跑在本地 LLM / VLM 上。
命中已知流程就走确定性执行，没命中就交给模型循环；跑成功的路径还会沉淀成经验，下次直接复用。
每一步都从页面读取事实，交给模型判断语义，再执行动作。感知不到可用元素时降级视觉模型看图决策。
click_at 坐标点击router 层维护 Playbook 注册表，两级匹配命中后走确定性流程；失败自动降级到通用 LLM 循环，成功轨迹还能反向晋升为新 Playbook。
每个实例拥有独立指纹种子与独立 profile，cookie 互相不可见。该能力仅用于合法授权范围内的多环境并行测试与兼容性验证。
ok / auth_failed / unreachableexperience 层把成功轨迹与失败现场持久化到 SQLite，遇到相似目标先检索复用；失败自动留档截图与 HTML 供人工复查。
scripts/diagnose.py 输出状态码、验证特征命中、可见输入框清单与元素尺寸core 层统一负责配置加载、日志与安全守卫。所有动作先过白名单与 URL/SSRF 校验，出站数据脱敏，密钥不落库不写日志。
下面是 MoonOS 轨迹记录的展示格式（感知到的事实、模型决策、执行动作、经验沉淀）。本页面为纯前端演示，不会真的打开浏览器或访问任何站点。
点左侧任意一层，查看它的职责与关键实现。目录均以 src/moonos/ 为根。
配置加载、日志与安全守卫。所有动作与 URL 在到达浏览器之前先经过这一层的校验。
Windows 环境，Python 3.11 起。CloakBrowser 为本地 editable 依赖，需单独安装。
用 .venv 隔离依赖，避免污染系统 Python。
二进制落在 bin/cloakbrowser/（约 536MB，不入库）；刻意不设 CLOAKBROWSER_BINARY_PATH，以免锁死版本。
只补装 socksio 与 geoip2 两个传递依赖。socksio 缺失会让 webrtc_ip=auto 被静默摘除，导致宿主真实 IP 泄露。
config.example.json → config.json（已被 gitignore）。本地 vLLM 一类服务可把 api_key 填 EMPTY；同名环境变量优先覆盖配置文件。
CLI 单次任务跑完即退，GUI 模式带主控制台与实例控制面板（窗口吸附）。
# 1. 独立虚拟环境
python -m venv .venv
.venv\Scripts\activate
# 2. 安装 CloakBrowser（按你的实际路径）
pip install -e [CLOAKBROWSER_PATH]
python -m cloakbrowser install
# 3. 安装本项目
pip install -e .
# 4. GeoIP extra：设备用代理 / WebRTC IP=auto 时必需
pip install "socksio>=1.0" "geoip2>=4.0"// config.json（已被 .gitignore 忽略，不入库）
{
"llm": { "base_url": "[BASE_URL]",
"model": "Qwen/Qwen3-VL-30B-A3B-Instruct-FP8",
"api_key": "EMPTY" },
"vision": { "enabled": true,
"base_url": "[BASE_URL]",
"model": "Qwen/Qwen3-VL-30B-A3B-Instruct-FP8" }
}
# 临时切换端点/模型/密钥走环境变量（优先级高于配置文件）
set MOONOS_LLM_BASE_URL=[BASE_URL]
set MOONOS_LLM_MODEL=openai/gpt-oss-120b
set MOONOS_VISION_BASE_URL=[BASE_URL]# 单次任务（跑完即退）
python -m moonos --goal "帮我搜索 MoonOS"
# 图形界面：主控制台 + 每窗口吸附的实例控制面板
python -m moonos --gui
# 代理链路自检（端口 / 隧道 / 出口 IP / 住宅性 / 设备时区一致性）
python scripts/probe_local_proxy.py [PORT] --device dev_xxx
python scripts/probe_chain_relay.py# 遇到「元素不可用 / 动作失败 / 疑似反爬」，先取证据再下结论
python scripts/diagnose.py [URL]
python scripts/diagnose.py [URL] -s "#kw" --out .cache/diag.png
# 输出：HTTP 状态 / 最终 URL / 标题、验证特征词命中、正文预览、
# 全页可见输入框清单、指定 selector 的可见性与盒子尺寸
# 单元测试（标准库 unittest，浏览器与 LLM 均 mock，可离线跑）
python -m unittest discover -s tests -p "test_*.py"以下场景均以「合法授权范围内」为前提；超出授权的使用一律不适用。
多实例并行、互不可见的 profile 与代理出口，用来在不同环境下重复验证同一套流程是否一致。
跨站点的固定动作——查询、填表、翻页、截图——用一句目标描述代替手写脚本，命中 Playbook 后走确定性流程。
验证出口 IP 是否真按预期生效、代理失效时会不会静默回落直连——这类最隐蔽的失效点正是它重点防护的。
感知—决策—执行循环、Router 分流、经验检索与失败降级都是可读可跑的完整实现，带单测与规范体系。
使用本项目即视为已阅读、理解并同意遵守项目 README 中的免责声明。
仅供学习、研究，以及在合法授权范围内开展浏览器自动化、兼容性测试、安全评估与个人效率提升。
须自行遵守目标站点服务条款、robots.txt、隐私政策及所在司法辖区法律法规。
环境一致性仅用于授权范围内模拟真实环境、多环境并行测试；人机验证自动处理仅限本人拥有或已获书面授权的站点，默认失败转人工兜底。
不得用于破解他人账号、批量注册 / 薅羊毛 / 刷量、抓取受法律或合同保护的数据、对抗第三方风控、非法爬虫。
不用于绕过访问控制与授权机制；作者不对使用者的违规违法行为及后果承担责任。
文档中提及的第三方产品名称仅作能力类比与技术说明，不代表关联、赞助或背书关系，商标归各自权利人所有。
fallback.enabled = true。出站数据经过脱敏，密钥不落库、不写日志。ok（可正常启动）、auth_failed（检查账号口令、套餐有效期、出口 IP 白名单）、unreachable（服务端不可用、端口未开放或被防火墙丢弃）。预检不通过会直接阻断启动、不创建浏览器——因为代理不通时 Chromium 仍能打开网页，但 WebRTC 伪装会被静默摘除，宿主真实 IP 会泄露却无人察觉。WebRTC IP=auto 是伪装上报的 IP，不是转发 UDP。若不禁用有代理时的 QUIC，UDP 旁路会造成出口 IP 不一致，所以 MoonOS 在该场景下直接关闭 QUIC。ok=false、目标数量不足、坐标非法或越出画布）。越界坐标一律不点击、直接转人工，绝不"乱点碰运气"。语义模态 quiz / imageClick / dragSort 由 DOM 读取事实、文本 LLM 只判语义：答复映射不到候选集合或数量不符即转人工——imageClick 点错一格即失败、dragSort 错拖一次即失败，不允许"先试试再说"。确定性模态 math / rotate / slider / sliderDecoy 不触网，不受影响。python scripts/diagnose.py [URL]，可加 -s "#kw" --out .cache/diag.png 查看指定 selector 的可见性与盒子尺寸。失败任务还会自动留档截图与 HTML，可从 experience 层回看。unittest，不依赖真实浏览器与 LLM（均 mock），覆盖安全护栏、router 匹配、配置加载与 Agent 主循环，可在无网络环境离线运行。本地模型、可审计的护栏、能沉淀经验的执行循环。在合法授权范围内，从一条 --goal 开始。
商业与生产用途请事先取得书面授权：lplulu@foxmail.com