chatgpt-register/AGENTS.md

zhuce6 Project AGENTS

项目定位

• zhuce6 是自用 ChatGPT 注册与治理仓库.
• 当前主线是单池 + backend API.
• main.py 是统一入口, 负责 init / doctor / run / stop / status, FastAPI 路由, register loop, 以及 cleanup / validate / rotate / register 后台任务装配.
• 主 Dashboard 路径是 GET /zhuce6, 页面文件位于 dashboard/zhuce6.html.
• 支持两类 full backend:
  • cpa
  • sub2api
• cfmail 是默认 mailbox provider 主线.

首先阅读什么

1. README.md
2. docs/TROUBLESHOOTING.md
3. docs/CONFIG_REFERENCE.md
4. main.py
5. 再按任务进入 core/, ops/, platforms/chatgpt/, dashboard/

正确入口认知

所有实施 agent 都应从以下主线理解项目:

uv run python main.py init
uv run python main.py doctor --fix
uv run python main.py --mode lite
# 或
uv run python main.py --mode full

主线组合

• lite + cfmail + register
• full + cpa
• full + sub2api

不要再按旧叙事理解

以下内容不再是项目主线认知:

• 历史两阶段池叙事
• 旧后台同步任务
• 旧归档主线
• 容器优先入口认知
• CPA-only 的 full 模式理解

架构说明

核心模块职责

• main.py: 统一 CLI 入口, FastAPI 应用创建, runtime mode 切换, 生命周期命令.
• core/: settings, doctor, setup wizard, cfmail, proxy pool, mailbox 抽象, 路径与共享基础设施.
• platforms/chatgpt/: ChatGPT 注册链, HTTP / OAuth 客户端, pool 写入与平台适配.
• ops/: cleanup, validate, rotate 与相关治理逻辑.
• dashboard/: /zhuce6 页面与 API 输出.
• scripts/: 独立脚本, 例如 cfmail 自动化与辅助工具.
• tests/: pytest 测试集.

运行模式说明

• full: 启动 Dashboard / API, 并按配置启用治理任务与 register.
• dashboard: 只启动 Dashboard / API.
• lite: 轻量运行模式, 适合只跑注册主线.
• register-loop: 只运行持续注册循环.
• burst-scheduler: 只运行批次调度注册.

实施规则

• 文档与代码都要围绕唯一正确入口: init -> doctor --fix -> run.
• full 必须显式区分 backend=cpa 与 backend=sub2api.
• cfmail 配置优先最小输入, 自动推导 Cloudflare 资源.
• 不要把临时排障口径写回长期文档.
• 不要把外部部署背景重新写成 repo 主逻辑.

验证规则

cd <PROJECT_ROOT>

export ZHUCE6_BASE_URL="http://<dashboard-host>:<dashboard-port>"

PYTHONPATH=. uv run pytest -q -s
curl -sS "$ZHUCE6_BASE_URL/api/summary" | python3 -m json.tool | head -n 80
curl -sS "$ZHUCE6_BASE_URL/api/runtime" | python3 -m json.tool | head -n 80
curl -sS "$ZHUCE6_BASE_URL/api/health/dependencies" | python3 -m json.tool | head -n 80
python3 - <<'PY'
import json
import os
import urllib.request

base_url = os.environ["ZHUCE6_BASE_URL"].rstrip("/")
with urllib.request.urlopen(f"{base_url}/api/runtime") as resp:
    runtime = json.load(resp)
registered = set(runtime.get("registered_tasks") or [])
assert ("sy" + "nc") not in registered, sorted(registered)
assert "register" in registered or runtime.get("runtime_mode") in {"dashboard"}, runtime
print(sorted(registered))
PY
curl -sS "$ZHUCE6_BASE_URL/zhuce6" | head

文档维护范围

优先维护:

• README.md
• AGENTS.md
• docs/TROUBLESHOOTING.md
• docs/CONFIG_REFERENCE.md
• docs/CODEX_PROVIDER_PROTOCOL_NOTES.md

阶段性说明若已被长期文档吸收, 应及时清理.