From e48941806fbd2663a9964d79ea7c19d4860c4420 Mon Sep 17 00:00:00 2001 From: QLHazyCoder <2825305047@qq.com> Date: Fri, 17 Apr 2026 02:01:13 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=E9=A1=B9=E7=9B=AE?= =?UTF-8?q?=E5=AE=8C=E6=95=B4=E9=93=BE=E8=B7=AF=E8=AF=B4=E6=98=8E=E5=92=8C?= =?UTF-8?q?=E5=BC=80=E5=8F=91=E8=A7=84=E8=8C=83=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/Hotmail双模式适配开发方案及开发记录.md | 431 -------------------- docs/仓库协作者AI分析PR与合并标准流程.md | 33 +- 项目完整链路说明.md | 394 ++++++++++++++++++ 项目开发规范（AI协作）.md | 190 +++++++++ 项目文件结构说明.md | 159 ++++++++ 5 files changed, 775 insertions(+), 432 deletions(-) delete mode 100644 docs/Hotmail双模式适配开发方案及开发记录.md create mode 100644 项目完整链路说明.md create mode 100644 项目开发规范（AI协作）.md create mode 100644 项目文件结构说明.md diff --git a/docs/Hotmail双模式适配开发方案及开发记录.md b/docs/Hotmail双模式适配开发方案及开发记录.md deleted file mode 100644 index d8ab2ee..0000000 --- a/docs/Hotmail双模式适配开发方案及开发记录.md +++ /dev/null @@ -1,431 +0,0 @@ -# Hotmail 鍙屾ā寮忛€傞厤寮€鍙戞柟妗? -## 1. 鑳屾櫙涓庨棶棰樺垎鏋? -褰撳墠浠撳簱鐨?Hotmail 鎺ョ爜璺緞宸茬粡鍥為€€鍒扳€滅涓夋柟閰嶇疆鈥濈増鏈紝鏍稿績鐗圭偣鏄細 - -- 璐﹀彿姹犵户缁娇鐢?`閭 / 瀹㈡埛绔?ID / 鍒锋柊浠ょ墝` 浣滀负鎵归噺瀵煎叆鏍煎紡 -- 鎵╁睍褰撳墠娲昏穬閫昏緫鐩存帴璇锋眰绗笁鏂?HTTP 鎺ュ彛璇诲彇閭欢 -- 渚ц竟鏍忛澶栨毚闇蹭簡 `API 鍦板潃 / 鍝嶅簲绫诲瀷 / 鏀朵欢绠卞弬鏁?/ 鍨冨溇绠卞弬鏁癭 杩欑粍鍗忚缁嗚妭閰嶇疆 - -杩欑増铏界劧鑳藉伐浣滐紝浣嗗凡缁忔毚闇插嚭涓や釜缁撴瀯鎬ч棶棰橈細 - -1. **杩滅▼鍗忚鍜屾湰鍦板崗璁苟涓嶄竴鑷?* - - `#10` 鏄繙绋嬬涓夋柟鏈嶅姟妯″紡锛屾牳蹇冩槸涓€涓浐瀹氭枃妗ｆ帴鍙?`https://apple.882263.xyz/api.html` - - `#42` 鏄湰鍦?helper 妯″紡锛屾牳蹇冩槸鏈湴 Python 鑴氭湰鏆撮湶 `/messages`銆乣/code` 绛夋帴鍙? - 涓よ€呭彧鏄骇鍝佸叆鍙ｇ浉浼硷紝涓嶆槸鍚屼竴鍗忚锛屼笉鑳界‖缁熶竴鎴愪竴濂椻€滈€氱敤 API 鍙傛暟閰嶇疆鍣ㄢ€? -2. **褰撳墠 UI 鏆撮湶浜嗚繃澶氬崗璁粏鑺?* - - `鍝嶅簲绫诲瀷` - - `鏀朵欢绠卞弬鏁癭 - - `鍨冨溇绠卞弬鏁癭 - - 杩欎簺瀛楁瀵硅繙绋嬫彁渚涘晢鍗忚鏉ヨ鏄浐瀹氱殑锛屽鏈湴 helper 鍗忚鏉ヨ鍙堟牴鏈笉閫傜敤 - - 鎶婅繖浜涚粏鑺傛毚闇茬粰鏈€缁堢敤鎴凤紝浼氭妸鐣岄潰鍙樻垚鈥滄帴鍙ｈ皟璇曞櫒鈥濓紝澧炲姞閿欒閰嶇疆椋庨櫓 - -3. **鐢ㄦ埛鐪熷疄闇€姹備笉鏄氦浜掓巿鏉冿紝鑰屾槸鎵归噺璐﹀彿姹?* - - 闇€瑕佺户缁敮鎸?`璐﹀彿----瀵嗙爜----瀹㈡埛绔疘D----鍒锋柊浠ょ墝` - - 闇€瑕佹敮鎸佸嚑鍗佷釜璐﹀彿鐨勬壒閲忓鍏ヤ笌鑷姩杞 - - 鍥犳褰撳墠闃舵涓嶅簲鍒囧埌鈥滃井杞氦浜掓巿鏉冣€濅富璺嚎 - -## 2. 宸查獙璇佸弬鑰冩潵婧? -### 2.1 PR #10锛氳繙绋嬬涓夋柟鏈嶅姟妯″紡 - -宸茬‘璁ょ壒寰侊細 - -- 鎵╁睍鐩存帴璇锋眰杩滅▼鎺ュ彛 -- 鎺ュ彛鏂囨。宸插叕寮€锛歚https://apple.882263.xyz/api.html` -- 鏍稿績鎺ュ彛鏄?`/api/mail-new` -- 鎵╁睍浼犲叆锛? - `client_id` - - `refresh_token` - - `email` - - `mailbox` - - `response_type` - -璁捐鐗圭偣锛? -- 鍗忚鐢辨彁渚涘晢鍥哄畾锛屼笉鍙兘涓哄綋鍓嶉」鐩崟鐙慨鏀?- 鎵╁睍搴旇鍋氣€滃崗璁€傞厤鈥濓紝鑰屼笉鏄鐢ㄦ埛鎵嬪～涓€鍫嗗簳灞傚弬鏁? -### 2.2 PR #42锛氭湰鍦?helper 妯″紡 - -宸茬‘璁ょ壒寰侊細 - -- 鎵╁睍璇锋眰鏈湴 helper锛歚http://127.0.0.1:17373` -- helper 鑴氭湰浣嶄簬锛? - `scripts/hotmail_helper.py` - - `start-hotmail-helper.bat` -- 鎵╁睍浣跨敤鐨勬牳蹇冩帴鍙ｆ槸锛? - `/messages` - - `/code` - -璁捐鐗圭偣锛? -- 鎵╁睍鍜岄偖绠卞崗璁В鑰?- 鏈湴鑴氭湰鎵挎媴 token 鍒锋柊銆佸彇淇°€侀獙璇佺爜绛涢€?- 鏇撮€傚悎鏈湴鐢ㄦ埛鑷帶鐜 - -## 3. 鏈€缁堣璁″彇鑸? -### 3.1 鐩爣鏂规 - -Hotmail 鍖烘敼鎴?*鍙屾ā寮忛€傞厤**锛? -- `杩滅▼鏈嶅姟` -- `鏈湴鍔╂墜` - -涓ょ妯″紡缁х画鍏辩敤鍚屼竴濂楄处鍙锋睜涓庢壒閲忓鍏ユ牸寮忥細 - -```text -璐﹀彿----瀵嗙爜----瀹㈡埛绔疘D----鍒锋柊浠ょ墝 -``` - -### 3.2 涓嶉噰鐢ㄧ殑鏂规 - -#### 涓嶉噰鐢ㄢ€滃井杞氦浜掓巿鏉冣€濅富鏂规 - -鍘熷洜锛? -- 涓嶉€傚悎鍑犲崄涓处鍙风殑鎵归噺浣跨敤鍦烘櫙 -- 浼氱牬鍧忕幇鏈夋壒閲忓鍏ラ摼璺?- 涓庡綋鍓嶇敤鎴烽渶姹傚啿绐? -#### 涓嶉噰鐢ㄢ€滈€氱敤 API 鍙傛暟閰嶇疆鍣ㄢ€? -鍘熷洜锛? -- 杩滅▼鍗忚鍜屾湰鍦板崗璁湰灏变笉鍚?- 缁х画淇濈暀 `鍝嶅簲绫诲瀷 / 鏀朵欢绠卞弬鏁?/ 鍨冨溇绠卞弬鏁癭 浼氬鍔犻厤缃鏉傚害 -- 杩欎簺瀛楁涓嶅簲鎴愪负鏈€缁堢敤鎴风殑甯歌閰嶇疆鍏ュ彛 - -## 4. 鐩爣浜や簰璁捐 - -### 4.1 Hotmail 鍖虹晫闈㈢粨鏋? -鍦ㄧ幇鏈?`Hotmail 璐﹀彿姹燻 鍖哄潡涓柊澧烇細 - -1. `Hotmail 妯″紡` 鎸夐挳缁? - `杩滅▼鏈嶅姟` - - `鏈湴鍔╂墜` - -2. `鏈嶅姟鍦板潃` 杈撳叆妗? - 褰撴ā寮忎负 `杩滅▼鏈嶅姟` 鏃舵樉绀鸿繙绋嬫湇鍔″湴鍧€ - - 褰撴ā寮忎负 `鏈湴鍔╂墜` 鏃舵樉绀烘湰鍦板姪鎵嬪湴鍧€ - -3. 淇濈暀璐﹀彿姹犺〃鍗? - 閭 - - 瀹㈡埛绔?ID - - 閭瀵嗙爜澶囨敞 - - 鍒锋柊浠ょ墝 - - 娣诲姞璐﹀彿 - -4. 淇濈暀鎵归噺瀵煎叆 - - 浠嶇劧鏀寔 `璐﹀彿----瀵嗙爜----瀹㈡埛绔疘D----鍒锋柊浠ょ墝` - -5. 淇濈暀璐﹀彿鎿嶄綔 - - 浣跨敤姝よ处鍙? - 鏍囪宸茬敤 / 鏈敤 - - 鏍￠獙 - - 澶嶅埗鏈€鏂伴獙璇佺爜 - - 鍒犻櫎 - -### 4.2 瑕佸垹闄ょ殑鏃?UI - -鍒犻櫎褰撳墠绗笁鏂归厤缃噷杩欏嚑涓粏椤癸細 - -- `Hotmail API 鍦板潃` -- `鍝嶅簲绫诲瀷` -- `鏀朵欢绠卞弬鏁癭 -- `鍨冨溇绠卞弬鏁癭 - -鍘熷洜锛? -- 杩欎簺灞炰簬鍗忚缁嗚妭锛屼笉閫傚悎鏅€氫娇鐢ㄨ€?- 鍙屾ā寮忔柟妗堥噷鍙渶瑕侀厤缃€滄湇鍔″湴鍧€鈥? -## 5. 鍚庡彴璁捐 - -### 5.1 鎸佷箙鍖栭厤缃」 - -鏂板骞朵娇鐢ㄤ互涓嬫寔涔呭寲瀛楁锛? -- `hotmailServiceMode` - - 鍊硷細`remote` / `local` -- `hotmailRemoteBaseUrl` - - 榛樿锛氳繙绋嬫湇鍔℃枃妗ｆ墍鍦ㄥ煙鍚?- `hotmailLocalBaseUrl` - - 榛樿锛歚http://127.0.0.1:17373` - -鍒犻櫎褰撳墠浠呮湇鍔′簬绗笁鏂归€氱敤閰嶇疆鍣ㄧ殑瀛楁锛? -- `hotmailApiUrl` -- `hotmailApiResponseType` -- `hotmailApiInboxMailbox` -- `hotmailApiJunkMailbox` - -### 5.2 璇锋眰閫傞厤灞? -鏂板缁熶竴鐨勬ā寮忓垎鍙戝眰锛屼絾**涓嶇粺涓€搴曞眰鍗忚**銆? -#### 杩滅▼妯″紡 - -鐩存帴鍏煎 PR #10 鏂囨。鍗忚锛? -- 璋冪敤杩滅▼ `baseUrl + /api/mail-new` -- 鎵╁睍绔繚鎸佺幇鏈夆€滄媺娑堟伅鍚庢湰鍦扮瓫楠岃瘉鐮佲€濈殑妯″紡 - -#### 鏈湴妯″紡 - -鐩存帴鍏煎 PR #42 helper 鍗忚锛? -- `/messages` -- `/code` - -鎵╁睍绔€昏緫锛? -- `鏍￠獙` / `娴嬭瘯鏀朵俊` 璧?`/messages` -- 楠岃瘉鐮佽疆璇紭鍏堣蛋 `/code` - -### 5.3 闇€瑕佹柊澧炴垨璋冩暣鐨勫悗鍙板嚱鏁? -1. 閰嶇疆褰掍竴鍖? - `normalizeHotmailServiceMode` - - `normalizeHotmailRemoteBaseUrl` - - `normalizeHotmailLocalBaseUrl` - - `getHotmailServiceSettings` - -2. 杩滅▼妯″紡閫傞厤 - - `requestHotmailRemoteMailbox` - - `fetchHotmailRemoteMessages` - -3. 鏈湴妯″紡閫傞厤 - - `requestHotmailLocalMessages` - - `requestHotmailLocalCode` - - `fetchHotmailLocalMessages` - -4. 缁熶竴鍒嗗彂鍏ュ彛 - - `fetchHotmailMailboxMessages` - - `pollHotmailVerificationCode` - - 鏍规嵁妯″紡鍒嗘祦 - -## 6. 鏈湴 helper 鏂囦欢绛栫暐 - -鐩存帴寮曞叆骞堕€傞厤 PR #42 宸查獙璇佺殑鏈湴鑴氭湰鏂规锛? -- `scripts/hotmail_helper.py` -- `start-hotmail-helper.bat` - -寮曞叆鍘熷垯锛? -- 浼樺厛淇濇寔鍗忚鍏煎锛屼笉鍋氭棤蹇呰閲嶆瀯 -- 鍙帴鍏ュ綋鍓嶆墿灞曢渶瑕佺敤鍒扮殑鎺ュ彛涓庡惎鍔ㄦ柟寮?- 涓嶅湪鏈疆鎵╁睍寮€鍙戜腑缁х画寮曞叆涓?Hotmail 妯″紡鍒囨崲鏃犲叧鐨勫ぇ瑙勬ā鐘舵€侀€昏緫 - -## 7. 涓庣幇鏈夐€昏緫鐨勫吋瀹硅姹? -### 7.1 蹇呴』淇濇寔涓嶅彉鐨勮涓? -- `Mail = Hotmail` 鏃朵粛鐒剁敱璐﹀彿姹犲垎閰嶉偖绠?- `璐﹀彿----瀵嗙爜----瀹㈡埛绔疘D----鍒锋柊浠ょ墝` 鎵归噺瀵煎叆鏍煎紡蹇呴』缁х画鍙敤 -- `鏍￠獙` / `澶嶅埗鏈€鏂伴獙璇佺爜` / `Auto` 鐨勭敤鎴峰叆鍙ｄ笉鍙?- Hotmail 璐﹀彿鐨?`used / status / lastError / lastAuthAt / lastUsedAt` 閫昏緫淇濇寔鐜版湁璇箟 - -### 7.2 蹇呴』閬垮厤鐨勯棶棰? -- 涓嶈兘鎶婅繙绋嬪拰鏈湴寮鸿鎶芥垚涓€濂楀亣缁熶竴鍗忚 -- 涓嶈兘鎶婄涓夋柟鏈嶅姟瑕佹眰鏀规垚 `/messages` `/code` -- 涓嶈兘鍒犻櫎鎵归噺瀵煎叆 refresh token 鐨勮兘鍔?- 涓嶈兘鍙敼 UI锛屼笉鎺ュ悗鍙板垎鍙?- 涓嶈兘鍙帴鍚庡彴锛屼笉鍚屾 README 涓庤鏄? -## 8. 鏂规鑷涓庡畬鏁存€у垎鏋? -### 8.1 鏂规鏄惁绗﹀悎闇€姹? -绗﹀悎銆? -鍘熷洜锛? -- 淇濈暀鎵归噺瀵煎叆 -- 涓嶅己杩敤鎴疯蛋寰蒋浜や簰鎺堟潈 -- 鍚屾椂鏀寔宸查獙璇佺殑杩滅▼涓庢湰鍦颁袱绉嶈矾寰? -### 8.2 鏂规鏄惁瀹屾暣 - -瀹屾暣銆? -宸茬粡瑕嗙洊锛? -- 閰嶇疆妯″瀷 -- 鐣岄潰鍙樻洿 -- 鍚庡彴鍒嗗彂 -- helper 寮曞叆 -- 鏂囨。鏇存柊 -- 鑷椤? -### 8.3 鏂规鏄惁瀛樺湪鍐呴儴鍐茬獊 - -褰撳墠鏃犳槑鏄惧啿绐併€? -鍞竴闇€瑕佷弗鏍兼帶鍒剁殑鏄細 - -- 杩滅▼妯″紡涓庢湰鍦版ā寮忚櫧鐒跺叆鍙ｇ粺涓€锛屼絾鍗忚涓嶈兘娣风敤 -- 瀹炵幇鏃跺繀椤绘槑纭垎灞傦紝涓嶈鍋氭垚鈥滄牴鎹厤缃嫾涓嶅悓 query 鍙傛暟鈥濈殑鏉傜硡閫昏緫 - -### 8.4 鏂规娼滃湪缂洪櫡 - -1. 鏈湴 helper 鍙兘渚濊禆 Python 鐜 - - 闇€瑕佸湪 README 涓槑纭鏄庡浣曞惎鍔? -2. 杩滅▼鏈嶅姟鏂囨。鑻ユ湭鏉ュ彉鏇? - 褰撳墠浠嶄緷璧栨湇鍔″晢鎺ュ彛绋冲畾鎬? -3. 褰撳墠浠撳簱鏄棫椤圭洰 - - Hotmail 閫昏緫鍛ㄨ竟宸叉湁杈冨鐘舵€佸瓧娈? - 瀹炵幇鏃跺繀椤昏皑鎱庢鏌?`verify/test/poll/auto-run` 鍥涙潯閾炬槸鍚︾粺涓€鎸夋ā寮忓垎鍙? -## 9. 寮€鍙戞竻鍗? -### 闃舵 1锛氶厤缃ā鍨嬩笌鏂规钀界洏 - -- 鏂板缓鏈柟妗堟枃妗?- 鏂板 Hotmail 鍙屾ā寮忔寔涔呭寲瀛楁 -- 鍒犻櫎鏃х殑绗笁鏂瑰崗璁粏椤瑰瓧娈? -鑷锛? -- 閰嶇疆椤瑰懡鍚嶆槸鍚︾粺涓€ -- 榛樿鍊兼槸鍚﹀畬鏁?- import/export 鏄惁浠嶅彲宸ヤ綔 - -### 闃舵 2锛欻otmail UI 鏀归€? -- 鏂板 `杩滅▼鏈嶅姟 / 鏈湴鍔╂墜` 妯″紡鎸夐挳 -- 鏂板 `鏈嶅姟鍦板潃` 杈撳叆妗?- 鍒犻櫎鏃х殑 `鍝嶅簲绫诲瀷 / 鏀朵欢绠卞弬鏁?/ 鍨冨溇绠卞弬鏁癭 杈撳叆妗?- 淇濈暀璐﹀彿姹犺〃鍗曚笌鎵归噺瀵煎叆 - -鑷锛? -- 鍒囨崲妯″紡鍚庢樉绀烘槸鍚︽纭?- 鑷姩淇濆瓨鏄惁浠嶆甯?- 涓嶅悓妯″紡鐨勫湴鍧€鏄惁涓嶄細浜掔浉瑕嗙洊 - -### 闃舵 3锛氬悗鍙板弻妯″紡閫傞厤 - -- 瀹炵幇杩滅▼妯″紡璇锋眰閫傞厤 -- 瀹炵幇鏈湴妯″紡 helper 璇锋眰閫傞厤 -- 淇敼 `fetchHotmailMailboxMessages` -- 淇敼 `pollHotmailVerificationCode` -- 鏍￠獙 `verify / test / auto-run` 涓夋潯閾? -鑷锛? -- 杩滅▼妯″紡鏄惁浠嶅吋瀹?`#10` -- 鏈湴妯″紡鏄惁鍏煎 `#42` -- 閿欒淇℃伅鏄惁浠嶄細鍐欏洖 `lastError` - -### 闃舵 4锛氬紩鍏ユ湰鍦?helper - -- 寮曞叆 `scripts/hotmail_helper.py` -- 寮曞叆 `start-hotmail-helper.bat` -- 妫€鏌ユ湰鍦板崗璁笌鎵╁睍璋冪敤涓€鑷? -鑷锛? -- helper 璺緞鏄惁姝ｇ‘ -- 绔彛涓庢枃妗ｆ槸鍚︿竴鑷?- 鎵╁睍璇锋眰璺緞鏄惁鍖归厤 helper - -### 闃舵 5锛氭枃妗ｆ敹灏? -- 鏇存柊 README 涓?Hotmail 浣跨敤璇存槑 -- 鏄庣‘杩滅▼妯″紡涓庢湰鍦版ā寮忕殑鍖哄埆 -- 鏄庣‘鏈湴 helper 鍚姩鏂瑰紡 - -鑷锛? -- README 鏄惁鍜岀湡瀹?UI 涓€鑷?- 鐢ㄦ埛鏄惁鑳界湅鏂囨。瀹屾垚閰嶇疆 - -## 10. 瀹炴柦椤哄簭 - -鏈疆寮€鍙戜弗鏍兼寜浠ヤ笅椤哄簭鎵ц锛? -1. 鍏堝啓鏈柟妗堟枃妗?2. 鍐嶆敼閰嶇疆妯″瀷 -3. 鍐嶆敼 UI -4. 鍐嶆敼鍚庡彴鍙屾ā寮忓垎鍙?5. 鍐嶅紩鍏ユ湰鍦?helper -6. 鏈€鍚庣粺涓€鍋氶潤鎬佽嚜妫€骞舵彁閱掔敤鎴锋墜娴? -## 11. 瀹為檯寮€鍙戣褰? -### 11.1 宸插畬鎴愭敼鍔? -鏈疆宸插疄闄呭畬鎴愪互涓嬪紑鍙戝唴瀹癸細 - -1. Hotmail 閰嶇疆妯″瀷浠庘€滅涓夋柟閫氱敤缁嗛」閰嶇疆鈥濆垏鎹负鈥滃弻妯″紡 + 鍦板潃閰嶇疆鈥? - 鍒犻櫎鍘熸湰闈㈠悜绗笁鏂圭粏椤圭殑鎬濊矾锛? - `hotmailApiUrl` - - `hotmailApiResponseType` - - `hotmailApiInboxMailbox` - - `hotmailApiJunkMailbox` - - 鏀逛负锛? - `hotmailServiceMode` - - `hotmailRemoteBaseUrl` - - `hotmailLocalBaseUrl` - -2. Sidepanel Hotmail 鍖哄凡鏀归€犳垚鍙屾ā寮?UI - - 鏂板 `杩滅▼鏈嶅姟 / 鏈湴鍔╂墜` 鎸夐挳缁? - 鏂板杩滅▼鏈嶅姟鍦板潃杈撳叆妗? - 鏂板鏈湴鍔╂墜鍦板潃杈撳叆妗? - 淇濈暀鍘熸湁璐﹀彿姹犺〃鍗曞拰鎵归噺瀵煎叆鏍煎紡 - -3. 鍚庡彴 Hotmail 璇锋眰閾惧凡鎸夋ā寮忓垎娴? - 杩滅▼妯″紡锛? - 鐩存帴鍏煎 `#10` - - 浣跨敤 `baseUrl + /api/mail-new` - - 鏈湴妯″紡锛? - 鐩存帴鍏煎 `#42` - - 浣跨敤 `/messages` - - 浣跨敤 `/code` - -4. 鏈湴 helper 鏂囦欢宸茶惤鍦? - `scripts/hotmail_helper.py` - - `start-hotmail-helper.bat` - -5. README 宸插悓姝ユ洿鏂颁负鍙屾ā寮忚鏄? -### 11.2 瀹為檯淇敼鏂囦欢 - -鏈疆瀹為檯鏀瑰姩鏂囦欢濡備笅锛? -- `background.js` -- `sidepanel/sidepanel.html` -- `sidepanel/sidepanel.js` -- `README.md` -- `scripts/hotmail_helper.py` -- `start-hotmail-helper.bat` - -鏈疆鏂板浣嗕笉涓€瀹氳繘鍏?Git 鐨勬枃妗ｏ細 - -- `docs/md/Hotmail鍙屾ā寮忛€傞厤寮€鍙戞柟妗?md` - -### 11.3 瀹為檯瀹炵幇涓庡師鏂规鐨勫樊寮? -褰撳墠瀹炵幇涓庡師鏂规鐩告瘮锛屽瓨鍦ㄨ繖浜涘疄闄呭樊寮傦細 - -1. 鏈湴 helper 娌℃湁鏁翠唤鐓ф惉 `#42` - - 褰撳墠鏄寜 `#42` 鐨勫崗璁€濊矾钀戒簡涓€涓畝鍖栫増 - - 鐩爣鏄厛婊¤冻鎵╁睍鐜伴樁娈电殑 `/messages` 涓?`/code` - - 娌℃湁缁х画寮曞叆 `#42` 閲屾洿閲嶇殑澶辫触鐘舵€併€佹寔涔呭凡鐢ㄩ偖绠便€佸苟鍙戜繚鎶ょ瓑鏁村鎵╁睍閫昏緫 - -2. 杩滅▼妯″紡鐩墠浠嶆部鐢ㄦ墿灞曠鏈湴绛涢獙璇佺爜 - - 鍏煎 `#10` 鐨勫崟鎺ュ彛 `/api/mail-new` - - 鏈澶栧鎺?`mail-all`銆乣process-inbox`銆乣process-junk` - -3. 娴嬭瘯鏂囦欢鏈疆娌℃湁缁х画琛ラ綈 - - 褰撳墠涓昏瀹屾垚鐨勬槸鏂规钀藉湴鍜屼富閾炬敼閫? - 灏氭湭琛ラ拡瀵瑰弻妯″紡鐨勬渶灏忓洖褰掓祴璇曟々 - -### 11.4 褰撳墠宸茬煡鏈畬鎴愰」 - -浠ヤ笅鍐呭褰撳墠浠嶆湭瀹屾垚鎴栨湭楠岃瘉锛? -1. 鏈ˉ Hotmail 鍙屾ā寮忓搴旂殑娴嬭瘯妗? - 杩滅▼妯″紡楠岃瘉閫昏緫 - - 鏈湴妯″紡 `/messages` 涓?`/code` 鍒嗗彂閫昏緫 - - 妯″紡鍒囨崲鍚庣殑 UI 鐘舵€佸洖濉? -2. 鏈 helper 鍋氳繍琛岀骇瀹炴祴 - - 褰撳墠鍙畬鎴愪唬鐮佹帴鍏? - 灏氭湭纭鏈満 Python 鐜涓?`imaplib + XOAUTH2 + login.live.com/oauth20_token.srf` 鏄惁鑳界ǔ瀹氬伐浣? -3. 鏈獙璇佽繙绋嬫湇鍔″湴鍧€鐨勪笉鍚岃緭鍏ュ舰寮? - 渚嬪鐢ㄦ埛濉細 - - 鏍瑰煙鍚? - `/api.html` - - `/api/mail-new` - - 鐩墠浠ｇ爜鍋氫簡璺緞褰掍竴鍖栵紝浣嗛渶瑕佷汉宸ユ墜娴嬬‘璁? -4. 鏈ˉ README 涓洿缁嗙殑鏈湴 helper 鍚姩鎺掗敊璇存槑 - - 褰撳墠鍙啓浜嗗叆鍙ｈ鏄? - 杩樻病鍐欌€滃惎鍔ㄥけ璐ユ€庝箞鐪嬨€佺鍙ｅ崰鐢ㄦ€庝箞鍔炪€丳ython 涓嶅瓨鍦ㄦ€庝箞鍔炩€? -### 11.5 褰撳墠鎵嬫祴閲嶇偣 - -鍚庣画浼樺厛鎵嬫祴浠ヤ笅鍐呭锛? -1. 杩滅▼妯″紡 - - `Mail = Hotmail` - - 妯″紡鍒囧埌 `杩滅▼鏈嶅姟` - - 鍦板潃濉?`https://apple.882263.xyz` - - 娴嬶細 - - `鏍￠獙` - - `澶嶅埗鏈€鏂伴獙璇佺爜` - - `Auto` - -2. 鏈湴妯″紡 - - 鍏堣繍琛?`start-hotmail-helper.bat` - - 妯″紡鍒囧埌 `鏈湴鍔╂墜` - - 鍦板潃淇濇寔 `http://127.0.0.1:17373` - - 娴嬶細 - - `鏍￠獙` - - `澶嶅埗鏈€鏂伴獙璇佺爜` - - `Auto` - -3. 妯″紡鍒囨崲 - - 浠?`杩滅▼鏈嶅姟` 鍒囧埌 `鏈湴鍔╂墜` - - 浠?`鏈湴鍔╂墜` 鍒囧埌 `杩滅▼鏈嶅姟` - - 鐪嬪湴鍧€鏄惁鍒嗗埆淇濈暀 - - 鐪?Hotmail 璐﹀彿姹犳槸鍚︿笉鍙楀奖鍝? -4. 鎵归噺瀵煎叆 - - 瀵煎叆鏍煎紡锛? - `璐﹀彿----瀵嗙爜----瀹㈡埛绔疘D----鍒锋柊浠ょ墝` - - 妫€鏌ユā寮忓垏鎹㈠悗瀵煎叆鑳藉姏鏄惁浠嶆甯? -### 11.6 褰撳墠椋庨櫓缁撹 - -褰撳墠鏈€澶ч闄╀笉鍦?UI锛岃€屽湪杩欎袱涓偣锛? -1. 鏈湴 helper 鐨勭湡瀹炲彲杩愯鎬? - 浠ｇ爜宸茬粡鎺ヤ笂 - - 浣嗘湭缁忓疄闄呰繍琛岄獙璇? -2. 杩滅▼涓庢湰鍦扮殑杩斿洖缁撴瀯鍏煎鎬? - 杩滅▼妯″紡璧?`#10` 椋庢牸 - - 鏈湴妯″紡璧?`#42` 椋庢牸 - - 铏界劧鍚庡彴宸茬粡鍋氫簡閫傞厤锛屼絾浠嶉渶瑕佸疄闄呰繑鍥炴牱鏈獙璇? -### 11.7 褰撳墠闃舵缁撹 - -褰撳墠鐘舵€佸彲浠ョ悊瑙ｄ负锛? -- 鏂规宸茶惤鐩?- 鍙屾ā寮忎富缁撴瀯宸插紑鍙戝畬鎴?- 杩滅▼ / 鏈湴涓ゆ潯鍗忚宸叉帴鍏?- 璐﹀彿姹犱笌鎵归噺瀵煎叆浠嶄繚鐣?- 浣嗗皻鏈粡杩囩湡瀹炶繍琛岄獙璇? -鍥犳鏈疆寮€鍙戠粨鏋滃睘浜庯細 - -- **浠ｇ爜缁撴瀯宸插埌浣?* -- **杩愯绋冲畾鎬у緟浜哄伐楠岃瘉** - -## 12. 本地 helper 运行说明补充 - -### 12.1 启动命令 - -Windows： - -```powershell -.\start-hotmail-helper.bat -``` - -macOS： - -```bash -chmod +x ./start-hotmail-helper.command -./start-hotmail-helper.command -``` - -如果不使用启动脚本，也可以直接运行： - -```bash -python scripts/hotmail_helper.py -``` - -或： - -```bash -python3 scripts/hotmail_helper.py -``` - -### 12.2 启动成功标志 - -启动成功后，终端应输出： - -```text -Hotmail helper listening on http://127.0.0.1:17373 -``` - -### 12.3 最小排错说明 - -- 若提示 `Python 3 not found`，说明当前机器没有可用的 Python 3.10+。 -- 若 helper 已启动但扩展仍连不上，先确认 Hotmail 模式切到了 `本地助手`。 -- 再确认侧边栏中的本地助手地址与终端输出一致，默认应为 `http://127.0.0.1:17373`。 -- 若地址一致仍失败，再检查终端中是否已经打印异常，或是否有端口占用。 diff --git a/docs/仓库协作者AI分析PR与合并标准流程.md b/docs/仓库协作者AI分析PR与合并标准流程.md index 078d164..fee0d39 100644 --- a/docs/仓库协作者AI分析PR与合并标准流程.md +++ b/docs/仓库协作者AI分析PR与合并标准流程.md @@ -4,6 +4,12 @@ 本文件用于给仓库协作者自己电脑上的 AI 一个固定、完整、可重复执行的 PR 处理流程。 +执行本流程时，AI 必须同时把下面三份根目录文档作为审查依据一起阅读： + +- [项目文件结构说明.md](c:/Users/projectf/Downloads/codex注册扩展/项目文件结构说明.md) +- [项目完整链路说明.md](c:/Users/projectf/Downloads/codex注册扩展/项目完整链路说明.md) +- [项目开发规范（AI协作）.md](c:/Users/projectf/Downloads/codex注册扩展/项目开发规范（AI协作）.md) + 下次只要告诉 AI： - 本仓库根目录 @@ -28,6 +34,14 @@ 12. 如果流程执行过程中，PR 的实时目标分支被别人改掉，或者不再是 `dev`，AI 必须停止当前合并流程，重新拉取信息后再决定下一步。 13. 进入“阶段 2：分析与审查”时，AI 必须先给当前 PR 添加 `审查中` 标签，并在开始正式审查前确认该标签已经在线上生效。 14. 审查结束后，AI 必须根据实际结论把 PR 标签从 `审查中` 切换为 `完成` 或 `等待修改`，并同时把受理人设置为自己；在确认线上状态已更新前，不允许声称审查已完成。 +15. 审查时必须检查该 PR 是否遵守 [项目开发规范（AI协作）.md](c:/Users/projectf/Downloads/codex注册扩展/项目开发规范（AI协作）.md)，不能只检查功能是否可用。 +16. 如果 PR 功能本身没问题，但明显违反开发规范，例如： + - 把大段逻辑重新堆回主文件 + - 没补测试或破坏测试边界 + - 没同步文档 + - 破坏共享步骤定义/注册表 + - 引入可见乱码 + 则也必须判定为“需要修改后再继续”，不能直接给出可合并结论。 ## 输入要求 @@ -127,6 +141,7 @@ gh pr edit --add-label "审查中" --repo - 这些改动是否合理 - 是否存在 bug / 风险 / 逻辑冲突 - PR 当前是否可直接合并，例如 `mergeable`、`mergeStateStatus` + - 是否遵守项目开发规范 6. 如果发现问题，结论必须按严重级别排序，优先写真正会影响功能、合并或后续维护的问题。 7. 如果没有发现明确问题，也要说明剩余风险，例如： - 未运行测试 @@ -136,6 +151,12 @@ gh pr edit --add-label "审查中" --repo - PR 仍然是打开状态 - PR 不是 draft - `baseRefName` 仍然是 `dev` +9. 审查输出中必须单独包含一节“开发规范符合性检查”，至少明确说明： + - 是否违反 [项目开发规范（AI协作）.md](c:/Users/projectf/Downloads/codex注册扩展/项目开发规范（AI协作）.md) + - 是否需要补测试 + - 是否需要补文档 + - 是否发现可见乱码或编码异常 + - 是否存在把逻辑重新堆回主文件的情况 ## 分析后评论规则 @@ -144,7 +165,7 @@ gh pr edit --add-label "审查中" --repo 如果发现需要作者或维护者注意的问题，AI 必须自动发 PR 评论，并且评论格式必须固定如下： ```text -（自动回复）AI分析结果（不一定完全正确，请仓库协作者确认无问题后再继续）： +（自动回复）AI分析结果（不一定完全正确，请进行确认，若无问题后请评论回复）： <这里写正式评论内容> ``` @@ -160,6 +181,12 @@ gh pr edit --add-label "审查中" --repo 7. 如果结论是“当前不能通过审查”，AI 必须明确写出“需要修改后再继续”，不能只写模糊提醒。 8. 如果当前环境支持正式 PR review，且问题足以阻止合并，优先使用带“要求更改（Request changes）”语义的审查，而不是只留普通闲聊式评论。 9. 行级评论是对总评论的补充，不得用零散行级评论替代总评论结论。 +10. 如果问题属于“开发规范不符合”，总评论中必须明确写出违反的是哪类规范，例如： + - 模块边界不符合 + - 测试缺失 + - 文档未同步 + - 出现乱码 + - 共享步骤定义未同步 ### 没问题时 @@ -252,6 +279,10 @@ git merge --no-ff --no-commit origin/dev 6. 要重新拉取一次实时 PR 元数据，确认该 PR 的 `baseRefName` 仍然是 `dev`；如果不是，停止后续合并并先反馈用户。 7. 要确认 PR 当前已经回到可继续处理的状态，例如不再是 `draft`，且 `mergeable` / `mergeStateStatus` 没有出现新的阻塞。 8. 默认不编译测试，最后提醒用户自行测试。 +9. 如果本地代修过程中涉及结构调整、功能链路变化或开发边界变化，必须同时检查并在必要时更新： + - [项目文件结构说明.md](c:/Users/projectf/Downloads/codex注册扩展/项目文件结构说明.md) + - [项目完整链路说明.md](c:/Users/projectf/Downloads/codex注册扩展/项目完整链路说明.md) + - [项目开发规范（AI协作）.md](c:/Users/projectf/Downloads/codex注册扩展/项目开发规范（AI协作）.md) ## 合并提交信息规则 diff --git a/项目完整链路说明.md b/项目完整链路说明.md new file mode 100644 index 0000000..45a5fb3 --- /dev/null +++ b/项目完整链路说明.md @@ -0,0 +1,394 @@ +# 项目完整链路说明 + +本文档面向 AI 与开发者，目标是让阅读者在最短时间内理解“项目做什么、怎么跑、数据怎么流、功能链路怎么串”，从而在新增功能时不漏逻辑、不误改边界。 + +使用建议： + +1. 先阅读 [项目文件结构说明.md](c:/Users/projectf/Downloads/codex注册扩展/项目文件结构说明.md) +2. 再阅读本文 +3. 最后阅读 [项目开发规范（AI协作）.md](c:/Users/projectf/Downloads/codex注册扩展/项目开发规范（AI协作）.md) + +## 1. 项目目标 + +这是一个 Chrome 扩展，用于自动执行一整套 OpenAI / ChatGPT OAuth 注册与登录流程。 + +它的核心价值不是“打开一个页面点几个按钮”，而是把下面这些环节串成一条完整可恢复的自动化链路： + +- 生成或选取注册邮箱 +- 打开 ChatGPT / OpenAI 注册入口 +- 提交邮箱和密码 +- 轮询注册验证码 +- 填写姓名和生日 +- 刷新 OAuth 链接并登录 +- 轮询登录验证码 +- 自动确认 OAuth 同意页 +- 把 localhost 回调提交到 CPA 或 SUB2API + +## 2. 核心运行参与者 + +### 2.1 Sidepanel + +[sidepanel/sidepanel.html](c:/Users/projectf/Downloads/codex注册扩展/sidepanel/sidepanel.html) + [sidepanel/sidepanel.js](c:/Users/projectf/Downloads/codex注册扩展/sidepanel/sidepanel.js) + +职责： + +- 展示配置与步骤状态 +- 接收用户输入 +- 向后台发送命令 +- 接收后台广播并更新 UI +- 动态渲染步骤列表 + +### 2.2 Background Service Worker + +[background.js](c:/Users/projectf/Downloads/codex注册扩展/background.js) + +职责： + +- 扩展后台入口 +- 装配所有模块 +- 统一承接 runtime message +- 协调步骤执行 +- 管理状态、自动运行、标签页与内容脚本通信 + +### 2.3 Content Scripts + +[content](c:/Users/projectf/Downloads/codex注册扩展/content) + +职责： + +- 在目标网页上执行 DOM 交互 +- 读取邮件内容或页面状态 +- 将步骤成功/失败状态上报给后台 + +### 2.4 Helper / Utils / Provider Logic + +分布在根目录和 `background/` 下。 + +职责： + +- 抽离第三方邮箱 provider 的纯逻辑 +- 抽离邮件匹配与验证码提取 +- 抽离共享验证码流程、自动运行流程和运行时基础设施 + +## 3. 入口与装配关系 + +### 3.1 扩展入口 + +[manifest.json](c:/Users/projectf/Downloads/codex注册扩展/manifest.json) 声明： + +- `background.service_worker = background.js` +- `side_panel.default_path = sidepanel/sidepanel.html` +- 多组内容脚本自动注入规则 + +### 3.2 背景层装配 + +[background.js](c:/Users/projectf/Downloads/codex注册扩展/background.js) 通过 `importScripts(...)` 依次加载： + +- 共享数据与纯工具 +- provider 纯逻辑 +- 后台桥接层 +- 后台共享流程层 +- 后台运行时与消息路由层 +- 步骤执行模块 + +因此 `background.js` 现在更像： + +- 常量定义中心 +- 模块依赖装配器 +- 极少量保留函数 +- Chrome 事件挂接入口 + +### 3.3 步骤注册 + +[data/step-definitions.js](c:/Users/projectf/Downloads/codex注册扩展/data/step-definitions.js) 提供共享步骤元数据。 +[background/steps/registry.js](c:/Users/projectf/Downloads/codex注册扩展/background/steps/registry.js) 负责把“步骤元数据”映射到“步骤执行器”。 + +这意味着： + +- 步骤顺序靠 `order` +- 步骤文件名靠语义 +- 新增步骤时不需要重命名后续文件 + +## 4. 状态与存储链路 + +### 4.1 `chrome.storage.session` + +保存运行态： + +- 当前步骤状态 +- OAuth 链接 +- 当前邮箱 / 密码 +- localhost 回调地址 +- 自动运行轮次信息 +- 标签注册表 +- 最近打开的来源地址 +- LuckMail 当前运行时选择 + +### 4.2 `chrome.storage.local` + +保存持久配置： + +- CPA / SUB2API 配置 +- 邮箱 provider 配置 +- Hotmail 账号池 +- Cloudflare / Temp Email 设置 +- iCloud 相关偏好 +- LuckMail API 配置 +- 自动运行默认配置 + +### 4.3 状态广播 + +后台通过 runtime message 向 sidepanel 广播： + +- `LOG_ENTRY` +- `STEP_STATUS_CHANGED` +- `DATA_UPDATED` +- `AUTO_RUN_STATUS` +- `ICLOUD_LOGIN_REQUIRED` +- `ICLOUD_ALIASES_CHANGED` + +## 5. 内容脚本通信链路 + +### 5.1 READY 机制 + +[content/utils.js](c:/Users/projectf/Downloads/codex注册扩展/content/utils.js) 在脚本加载后会发送 `CONTENT_SCRIPT_READY`。 + +后台收到后会： + +- 注册当前来源对应的 tab +- 标记 ready +- 冲刷排队命令 + +### 5.2 队列与重试 + +[background/tab-runtime.js](c:/Users/projectf/Downloads/codex注册扩展/background/tab-runtime.js) 负责： + +- `queueCommand` +- `flushCommand` +- `sendTabMessageWithTimeout` +- `sendToContentScriptResilient` +- `sendToMailContentScriptResilient` + +这保证了： + +- 页面切换导致脚本暂时失联时，后台不会立刻误判彻底失败 +- 邮箱页或注册页能在注入恢复后继续执行 + +## 6. 手动步骤完整链路 + +### Step 1 + +文件： + +- [background/steps/open-chatgpt.js](c:/Users/projectf/Downloads/codex注册扩展/background/steps/open-chatgpt.js) +- [content/signup-page.js](c:/Users/projectf/Downloads/codex注册扩展/content/signup-page.js) + +流程： + +1. 后台打开 ChatGPT 官网 +2. 等待注册入口页内容脚本就绪 +3. 标记 Step 1 完成 + +### Step 2 + +文件： + +- [background/steps/submit-signup-email.js](c:/Users/projectf/Downloads/codex注册扩展/background/steps/submit-signup-email.js) + +流程： + +1. 解析本轮应使用的邮箱 +2. 打开或复用注册页 +3. 点击注册入口并提交邮箱 +4. 等待跳转到密码页 + +### Step 3 + +文件： + +- [background/steps/fill-password.js](c:/Users/projectf/Downloads/codex注册扩展/background/steps/fill-password.js) + +流程： + +1. 生成或读取密码 +2. 更新运行态密码 +3. 记录账号快照 +4. 让内容脚本填写密码并继续 + +### Step 4 / Step 7 + +文件： + +- [background/steps/fetch-signup-code.js](c:/Users/projectf/Downloads/codex注册扩展/background/steps/fetch-signup-code.js) +- [background/steps/fetch-login-code.js](c:/Users/projectf/Downloads/codex注册扩展/background/steps/fetch-login-code.js) +- [background/verification-flow.js](c:/Users/projectf/Downloads/codex注册扩展/background/verification-flow.js) + +这两步共享验证码主流程： + +1. 确定 provider +2. 必要时重发验证码 +3. 轮询邮箱或 API +4. 提取验证码 +5. 回填页面 +6. 若页面拒绝，则重试或回退 + +### Step 5 + +文件： + +- [background/steps/fill-profile.js](c:/Users/projectf/Downloads/codex注册扩展/background/steps/fill-profile.js) + +流程： + +1. 生成随机姓名和生日 +2. 内容脚本填写资料 +3. 如果页面跳到 ChatGPT onboarding，则执行跳过链路 + +### Step 6 + +文件： + +- [background/steps/oauth-login.js](c:/Users/projectf/Downloads/codex注册扩展/background/steps/oauth-login.js) + +流程： + +1. 清理登录前 Cookie +2. 通过 CPA / SUB2API 刷新 OAuth 地址 +3. 打开最新 OAuth 链接 +4. 登录 +5. 确保真正进入验证码页 +6. 如果未进入验证码页，则按可恢复逻辑重试 + +### Step 8 + +文件： + +- [background/steps/confirm-oauth.js](c:/Users/projectf/Downloads/codex注册扩展/background/steps/confirm-oauth.js) + +流程： + +1. 监听 localhost callback +2. 准备 OAuth 同意页 +3. 尝试多轮点击“继续” +4. 一旦捕获 localhost callback，写入状态并完成步骤 + +### Step 9 + +文件： + +- [background/steps/platform-verify.js](c:/Users/projectf/Downloads/codex注册扩展/background/steps/platform-verify.js) + +流程： + +1. 校验 localhost callback 是否有效 +2. 判断是 CPA 还是 SUB2API +3. 打开相应后台 +4. 提交回调地址 +5. 完成平台侧验证 +6. 做成功后的清理与标记 + +## 7. 邮箱与 provider 链路 + +### 7.1 生成邮箱 + +文件： + +- [background/generated-email-helpers.js](c:/Users/projectf/Downloads/codex注册扩展/background/generated-email-helpers.js) + +支持： + +- Duck +- Cloudflare +- Cloudflare Temp Email +- iCloud 隐私邮箱 + +### 7.2 Hotmail + +组成： + +- [hotmail-utils.js](c:/Users/projectf/Downloads/codex注册扩展/hotmail-utils.js) +- [microsoft-email.js](c:/Users/projectf/Downloads/codex注册扩展/microsoft-email.js) +- [scripts/hotmail_helper.py](c:/Users/projectf/Downloads/codex注册扩展/scripts/hotmail_helper.py) + +模式： + +- API 对接 +- 本地 helper + +### 7.3 LuckMail + +组成： + +- [luckmail-utils.js](c:/Users/projectf/Downloads/codex注册扩展/luckmail-utils.js) +- LuckMail 相关后台领域逻辑仍在 [background.js](c:/Users/projectf/Downloads/codex注册扩展/background.js) + +### 7.4 iCloud + +组成： + +- [icloud-utils.js](c:/Users/projectf/Downloads/codex注册扩展/icloud-utils.js) +- [content/icloud-mail.js](c:/Users/projectf/Downloads/codex注册扩展/content/icloud-mail.js) + +## 8. 自动运行完整链路 + +文件： + +- [background/auto-run-controller.js](c:/Users/projectf/Downloads/codex注册扩展/background/auto-run-controller.js) + +流程： + +1. 读取总轮数与模式 +2. 计算是否从中断点继续 +3. 每轮执行前重置必要运行态 +4. 执行 `runAutoSequenceFromStep` +5. 如果失败，根据设置决定： + - 立即停止 + - 当前轮重试 + - 下一轮继续 +6. 如果配置了线程间隔，则挂计时计划 +7. 所有轮次结束后输出汇总 + +## 9. 新增功能时最容易漏掉的地方 + +### 新增步骤 + +必须同时检查： + +1. [data/step-definitions.js](c:/Users/projectf/Downloads/codex注册扩展/data/step-definitions.js) +2. [background/steps](c:/Users/projectf/Downloads/codex注册扩展/background/steps) +3. [background/steps/registry.js](c:/Users/projectf/Downloads/codex注册扩展/background/steps/registry.js) +4. 自动运行链路是否需要纳入 +5. Step 状态传播和侧边栏展示是否需要适配 +6. 测试是否要补 + +### 新增 provider + +必须同时检查： + +1. provider 纯工具 +2. 后台 provider 调度分支 +3. 侧边栏配置项 +4. 动态邮箱生成逻辑 +5. Step 4 / 7 的验证码流 +6. 成功收尾逻辑 + +### 新增配置项 + +必须同时检查： + +1. `PERSISTED_SETTING_DEFAULTS` +2. `normalizePersistentSettingValue` +3. 导入导出逻辑 +4. sidepanel 表单与状态恢复 +5. 结构文档 / 开发规范是否需要更新 + +## 10. 文档联动规则 + +修改下列内容时，必须同步更新文档： + +- 文件结构变更 + 更新 [项目文件结构说明.md](c:/Users/projectf/Downloads/codex注册扩展/项目文件结构说明.md) +- 运行链路变更 + 更新 [项目完整链路说明.md](c:/Users/projectf/Downloads/codex注册扩展/项目完整链路说明.md) +- 规范、边界、步骤接入方式变更 + 更新 [项目开发规范（AI协作）.md](c:/Users/projectf/Downloads/codex注册扩展/项目开发规范（AI协作）.md) diff --git a/项目开发规范（AI协作）.md b/项目开发规范（AI协作）.md new file mode 100644 index 0000000..7feed42 --- /dev/null +++ b/项目开发规范（AI协作）.md @@ -0,0 +1,190 @@ +# 项目开发规范（AI协作） + +本文档是面向 AI 与开发者的项目开发规范。 + +阅读顺序要求： + +1. [项目文件结构说明.md](c:/Users/projectf/Downloads/codex注册扩展/项目文件结构说明.md) +2. [项目完整链路说明.md](c:/Users/projectf/Downloads/codex注册扩展/项目完整链路说明.md) +3. 当前文件 + +原则： + +- 目标是“让项目更清晰、更可维护、更可测试”，不是单纯把代码拆碎。 +- 重构优先考虑稳定性、职责边界与可理解性。 +- 任何新增功能都必须沿现有分层接入，禁止重新堆回巨石文件。 + +## 1. 架构原则 + +### 1.1 背景层原则 + +- [background.js](c:/Users/projectf/Downloads/codex注册扩展/background.js) 应尽量保持为入口壳、装配层和少量保留函数。 +- 业务流程优先放到： + - `background/steps/` + - `background/*.js` 的共享模块 +- 不要把新 provider、大段自动运行逻辑、大段消息分发逻辑直接写回 `background.js`。 + +### 1.2 步骤原则 + +- 每个步骤必须有清晰边界。 +- 步骤文件应优先使用语义化名称，不再使用 `stepX.js` 命名。 +- 步骤顺序统一由： + - [data/step-definitions.js](c:/Users/projectf/Downloads/codex注册扩展/data/step-definitions.js) + - [background/steps/registry.js](c:/Users/projectf/Downloads/codex注册扩展/background/steps/registry.js) + 共同管理。 + +### 1.3 前后端步骤定义共享原则 + +- 任何步骤标题、顺序、key 变更，必须优先改 [data/step-definitions.js](c:/Users/projectf/Downloads/codex注册扩展/data/step-definitions.js) +- 不允许只改 sidepanel 文案而不改共享定义 +- 不允许只改 registry 而不改共享定义 + +## 2. 模块边界规则 + +### 2.1 可以继续增长的文件 + +允许增长，但必须保持边界清晰： + +- provider 领域实现文件 +- 某个单独步骤文件 +- 某个单独 manager 文件 + +### 2.2 不应该继续膨胀的文件 + +- [background.js](c:/Users/projectf/Downloads/codex注册扩展/background.js) +- [sidepanel/sidepanel.js](c:/Users/projectf/Downloads/codex注册扩展/sidepanel/sidepanel.js) + +如果在这两个文件里新增了大段逻辑，应优先判断是否应该下沉到模块。 + +## 3. 新增功能接入规范 + +### 3.1 新增步骤 + +必须同步检查： + +1. 新增步骤文件到 `background/steps/` +2. 更新 [data/step-definitions.js](c:/Users/projectf/Downloads/codex注册扩展/data/step-definitions.js) +3. 更新 [background/steps/registry.js](c:/Users/projectf/Downloads/codex注册扩展/background/steps/registry.js) +4. 检查 sidepanel 动态步骤渲染是否已自动覆盖 +5. 检查 auto-run 是否需要纳入此步骤 +6. 检查状态流、回退流、日志流是否完整 +7. 补测试 + +### 3.2 新增 provider + +必须同步检查： + +1. 是否有纯工具模块 +2. 是否需要 background provider 调度逻辑 +3. 是否需要 sidepanel 配置项 +4. 是否需要 Step 4 / 7 验证码链路接入 +5. 是否需要成功收尾逻辑 +6. 是否需要 README 与完整链路文档更新 + +### 3.3 新增配置项 + +必须同步检查： + +1. 默认值 +2. 归一化 +3. 导入导出 +4. state restore +5. sidepanel UI +6. 文档 + +## 4. 测试规范 + +### 4.1 原则 + +- 任何结构性重构都必须伴随测试迁移或新增。 +- 优先测试： + - 模块是否接入 + - 核心纯函数是否仍可验证 + - 回退/停止/异常传播是否仍正确 + +### 4.2 不允许的做法 + +- 修改结构后不补测试 +- 只跑局部测试，不跑全量回归 +- 为了通过测试而破坏实际运行边界 + +### 4.3 最低要求 + +完成一次结构性改动后，至少执行： + +```bash +bun test +``` + +## 5. 文档更新规范 + +### 5.1 必须更新文档的场景 + +- 文件新增/删除/重命名 + 更新 [项目文件结构说明.md](c:/Users/projectf/Downloads/codex注册扩展/项目文件结构说明.md) +- 功能链路变化 + 更新 [项目完整链路说明.md](c:/Users/projectf/Downloads/codex注册扩展/项目完整链路说明.md) +- 开发流程、边界、约束变化 + 更新当前文件 + +### 5.2 文档更新要求 + +- 不能只改代码不改文档 +- 不能只改文档标题不改正文细节 +- 不能让结构文档漏文件 +- 不能让链路文档落后于真实实现 + +## 6. 命名规范 + +### 6.1 文件命名 + +- 步骤文件使用语义化名称 +- 工具文件按职责命名 +- 不要再新增 `misc.js`、`temp.js`、`new.js`、`helper2.js` 这种模糊文件名 + +### 6.2 key 命名 + +- 步骤 key 使用短语义英文 kebab-case +- message type 保持稳定，新增时优先语义化大写常量风格 + +## 7. 代码风格与实现要求 + +- 优先复用现有模块，不重复发明一套新流程 +- 共享逻辑先提公共层，再让步骤层调用 +- 代码新增后应尽量减少主文件体积，而不是只做“形式拆分” +- 保留少量兼容型薄包装是允许的，但必须有明确目的： + - 运行时装配 + - 测试迁移过渡 +- 如果某个薄包装已经没有存在意义，应在后续重构中清掉 + +## 8. AI 开发时的自检清单 + +每次修改后至少自问： + +1. 我这次新增逻辑是不是应该下沉到模块？ +2. 我有没有破坏共享步骤定义？ +3. 我有没有漏掉 auto-run / sidepanel / message-router 其中之一？ +4. 我有没有补或迁移测试？ +5. 我有没有更新三份根目录文档？ +6. 我新增或修改的文件是否有可见乱码？ + +## 9. 完成标准 + +当满足以下条件时，可以视为一次合格开发完成： + +- 代码职责边界清晰 +- 新旧功能链路完整 +- 全量测试通过 +- 三份根目录文档已同步 +- 没有可见乱码 + +## 10. 特别要求 + +以后每次开发，如果影响到项目结构、功能链路或开发边界： + +- 必须同步检查并在必要时更新： + - [项目文件结构说明.md](c:/Users/projectf/Downloads/codex注册扩展/项目文件结构说明.md) + - [项目完整链路说明.md](c:/Users/projectf/Downloads/codex注册扩展/项目完整链路说明.md) + - [项目开发规范（AI协作）.md](c:/Users/projectf/Downloads/codex注册扩展/项目开发规范（AI协作）.md) + +这是硬要求，不是建议。 diff --git a/项目文件结构说明.md b/项目文件结构说明.md new file mode 100644 index 0000000..35a9722 --- /dev/null +++ b/项目文件结构说明.md @@ -0,0 +1,159 @@ +# 项目文件结构说明 + +本文档列出当前仓库中所有“非忽略文件”，并说明每个文件的作用。 + +不纳入本清单的忽略目录： + +- `.github/` +- `_metadata/` +- `docs/md/` +- `.vscode/` +- `.git/` + +更新规则： + +- 新增、删除、重命名非忽略文件后，必须同步更新本文件。 +- 如果文件职责发生明显变化，也必须同步更新本文件中的说明。 + +## 根目录 + +- `.gitignore`：定义仓库忽略规则，当前忽略 `docs/md/`、`.github/`、`_metadata/`、`.vscode/` 等目录。 +- `LICENSE`：项目许可证文件。 +- `README.md`：面向使用者的项目介绍、安装说明、能力清单与操作指引。 +- `background.js`：扩展后台 Service Worker 入口壳，负责模块装配、初始化、全局常量、少量保留的领域函数与运行入口。 +- `cloudflare-temp-email-utils.js`：Cloudflare Temp Email 相关的纯工具函数，负责 URL、域名、邮件内容与 MIME 数据归一化。 +- `hotmail-utils.js`：Hotmail 账号与验证码提取相关的纯工具函数，负责账号筛选、验证码匹配、第三方接口数据归一化。 +- `icloud-utils.js`：iCloud 隐私邮箱相关的纯工具函数，负责 host、别名列表、保留状态、已用状态等归一化。 +- `luckmail-utils.js`：LuckMail 相关的纯工具函数，负责邮箱购买记录、标签、邮件 cursor、验证码匹配等归一化。 +- `manifest.json`：Chrome 扩展清单，声明权限、背景脚本、侧边栏、内容脚本与规则集。 +- `microsoft-email.js`：Microsoft Graph / Outlook 邮件读取辅助模块，负责刷新令牌换 token、邮箱夹轮询和验证码提取。 +- `package.json`：仓库最小 Node 包配置，目前主要提供测试脚本定义。 +- `rules.json`：静态 DNR 规则，主要处理 iCloud 相关请求头。 +- `start-hotmail-helper.bat`：Windows 下启动本地 Hotmail helper 的脚本。 +- `start-hotmail-helper.command`：macOS 下启动本地 Hotmail helper 的脚本。 +- `开发者AI开发与PR提交流程.md`：仓库现有的 AI 开发与 PR 提交流程说明。 +- `项目文件结构说明.md`：当前文件，维护整个仓库非忽略文件的结构与职责索引。 +- `项目完整链路说明.md`：面向 AI/开发者的完整功能链路说明，用于快速理解系统整体运行过程。 +- `项目开发规范（AI协作）.md`：面向 AI/开发者的项目开发规范、约束与变更检查清单。 + +## `background/` + +- `background/auto-run-controller.js`：自动运行主控制器，封装多轮执行、重试、轮次摘要、线程间隔与倒计时恢复逻辑。 +- `background/generated-email-helpers.js`：生成邮箱辅助层，封装 Duck、Cloudflare、Cloudflare Temp Email、iCloud 隐私邮箱的获取逻辑。 +- `background/logging-status.js`：后台日志、步骤状态、错误信息和若干状态判断的公共工具层。 +- `background/message-router.js`：后台消息路由层，负责处理 `chrome.runtime.onMessage` 进入的所有业务消息。 +- `background/navigation-utils.js`：导航与 URL 判断工具层，负责 callback、入口页、CPA/SUB2API 地址、步骤跳转相关判断。 +- `background/panel-bridge.js`：CPA / SUB2API 面板桥接层，封装 OAuth 地址获取所需的页面打开、脚本注入和通信。 +- `background/signup-flow-helpers.js`：注册页辅助层，负责打开注册入口、等待密码页以及解析当前流程所用邮箱。 +- `background/tab-runtime.js`：标签页与内容脚本运行时基础设施，封装标签注册、冲突清理、消息超时、注入重试与队列。 +- `background/verification-flow.js`：注册/登录验证码共享流程层，封装重发、轮询、提交、失败回退与自定义邮箱跳过逻辑。 + +## `background/steps/` + +- `background/steps/confirm-oauth.js`：步骤 8 实现，负责 OAuth 同意页按钮定位、点击、localhost 回调监听与回调完成。 +- `background/steps/fetch-login-code.js`：步骤 7 实现，负责登录验证码阶段的邮箱轮询与回退控制。 +- `background/steps/fetch-signup-code.js`：步骤 4 实现，负责注册验证码阶段的页面准备与验证码流程入口。 +- `background/steps/fill-password.js`：步骤 3 实现，负责密码生成、保存、回填与提交。 +- `background/steps/fill-profile.js`：步骤 5 实现，负责姓名、生日填写与 ChatGPT onboarding 跳过流程。 +- `background/steps/oauth-login.js`：步骤 6 实现，负责刷新 OAuth 链接、登录和确保进入验证码页。 +- `background/steps/open-chatgpt.js`：步骤 1 实现，负责打开 ChatGPT 官网并确认入口就绪。 +- `background/steps/platform-verify.js`：步骤 9 实现，负责 CPA / SUB2API 回调验证。 +- `background/steps/registry.js`：步骤注册表工厂，负责用稳定的步骤元数据映射到执行器。 +- `background/steps/submit-signup-email.js`：步骤 2 实现，负责注册入口点击、邮箱提交与密码页等待。 + +## `content/` + +- `content/activation-utils.js`：内容脚本通用激活策略工具，负责按钮点击方式判断等轻量辅助逻辑。 +- `content/duck-mail.js`：DuckDuckGo Email Protection 页面脚本，负责生成或读取 `@duck.com` 地址。 +- `content/gmail-mail.js`：Gmail 邮箱轮询脚本，负责在 Gmail 页面中匹配验证码邮件。 +- `content/icloud-mail.js`：iCloud 邮箱页面脚本，负责在 iCloud Mail 页面中读取邮件详情和验证码。 +- `content/inbucket-mail.js`：Inbucket 邮箱轮询脚本，负责在 Inbucket 页面中读取/删除验证码邮件。 +- `content/mail-163.js`：163 / 163 VIP 邮箱轮询脚本，负责网页邮箱验证码读取和邮件清理。 +- `content/mail-2925.js`：2925 邮箱页面脚本，负责 2925 邮箱收件轮询与验证码匹配。 +- `content/qq-mail.js`：QQ 邮箱轮询脚本，负责网页邮箱验证码读取。 +- `content/signup-page.js`：注册/登录/授权主内容脚本，负责 OpenAI / ChatGPT 页面上的步骤执行。 +- `content/sub2api-panel.js`：SUB2API 后台内容脚本，负责获取 OAuth 地址和提交 localhost 回调。 +- `content/utils.js`：内容脚本公共工具层，负责日志、READY/COMPLETE/ERROR 上报、元素等待、输入与点击。 +- `content/vps-panel.js`：CPA 面板内容脚本，负责获取 OAuth 地址和提交回调 URL。 + +## `data/` + +- `data/names.js`：随机姓名、生日等测试数据源。 +- `data/step-definitions.js`：共享步骤元数据，前后台共同使用，用于动态渲染和步骤注册。 + +## `docs/` + +- `docs/Hotmail双模式适配开发方案及开发记录.md`：Hotmail 双模式接入的历史方案和开发记录。 +- `docs/仓库协作者AI分析PR与合并标准流程.md`：仓库协作者进行 AI 分析 PR 与合并时的流程说明。 +- `docs/images/交流群.jpg`：README 中展示的交流群图片资源。 +- `docs/images/十轮自动.png`：README 中展示的自动运行效果图。 +- `docs/images/微信.png`：README 中展示的微信收款码图片。 +- `docs/images/支付宝.jpg`：README 中展示的支付宝收款码图片。 +- `docs/refactor/2026-04-16-architecture-refactor-plan.md`：本轮重构阶段的结构设计与迁移计划记录。 +- `docs/superpowers/plans/2026-04-10-hotmail-oauth-mail-pool.md`：Hotmail OAuth 邮箱池实现计划文档。 +- `docs/superpowers/specs/2026-04-10-hotmail-oauth-design.md`：Hotmail OAuth + Graph Mail 的设计规格文档。 + +## `icons/` + +- `icons/icon128.png`：扩展 128 像素图标。 +- `icons/icon16.png`：扩展 16 像素图标。 +- `icons/icon48.png`：扩展 48 像素图标。 + +## `scripts/` + +- `scripts/hotmail_helper.py`：本地 Hotmail helper 服务，负责通过本地接口协助获取邮件和验证码。 + +## `sidepanel/` + +- `sidepanel/hotmail-manager.js`：侧边栏 Hotmail 账号池管理器，负责列表、导入、验证、测试收信和批量操作。 +- `sidepanel/icloud-manager.js`：侧边栏 iCloud 隐私邮箱管理器，负责列表、筛选、保留、删除和批量操作。 +- `sidepanel/luckmail-manager.js`：侧边栏 LuckMail 管理器，负责邮箱列表、筛选、启停、保留与批量操作。 +- `sidepanel/sidepanel.css`：侧边栏样式文件。 +- `sidepanel/sidepanel.html`：侧边栏页面结构，当前步骤列表已改为动态容器。 +- `sidepanel/sidepanel.js`：侧边栏主入口脚本，负责 UI 状态同步、动态步骤渲染、按钮交互与广播接收。 +- `sidepanel/update-service.js`：侧边栏更新检查服务，负责 GitHub Releases 查询与版本展示。 + +## `tests/` + +- `tests/activation-utils.test.js`：测试内容脚本激活策略与 Step 9 可恢复错误判断。 +- `tests/auto-run-fresh-attempt-reset.test.js`：测试自动运行在新一轮开始前会重置旧运行时上下文。 +- `tests/auto-step-random-delay.test.js`：测试自动运行步间延迟与旧配置键兼容解析。 +- `tests/background-auto-run-module.test.js`：测试自动运行控制器模块已接入且导出工厂。 +- `tests/background-generated-email-module.test.js`：测试生成邮箱辅助模块已接入且导出工厂。 +- `tests/background-icloud.test.js`：测试 iCloud 相关后台纯函数与别名收尾逻辑。 +- `tests/background-icloud-mail-provider.test.js`：测试 iCloud 邮箱 provider 配置解析。 +- `tests/background-logging-status-module.test.js`：测试日志/状态模块已接入且导出工厂。 +- `tests/background-luckmail.test.js`：测试 LuckMail 相关后台逻辑，如购买、复用、标记已用与重置。 +- `tests/background-message-router-module.test.js`：测试消息路由模块已接入且导出工厂。 +- `tests/background-navigation-utils-module.test.js`：测试导航工具模块已接入且导出工厂。 +- `tests/background-panel-bridge-module.test.js`：测试面板桥接模块已接入且导出工厂。 +- `tests/background-signup-flow-module.test.js`：测试注册页辅助模块已接入且导出工厂。 +- `tests/background-step-modules.test.js`：测试步骤模块文件都已由后台入口加载。 +- `tests/background-step-registry.test.js`：测试后台步骤注册表和共享步骤定义已接入。 +- `tests/background-tab-runtime-module.test.js`：测试标签运行时模块已接入且导出工厂。 +- `tests/background-verification-flow-module.test.js`：测试验证码流程模块已接入且导出工厂。 +- `tests/cloudflare-temp-email-provider.test.js`：测试 Cloudflare Temp Email provider 的轮询与目标邮箱选择逻辑。 +- `tests/cloudflare-temp-email-utils.test.js`：测试 Cloudflare Temp Email 工具层的 URL、域名、邮件解析逻辑。 +- `tests/hotmail-api-mode.test.js`：测试 Hotmail API 模式相关文案和集成方式。 +- `tests/hotmail-cors-headers.test.js`：测试 Microsoft token 请求相关 DNR 配置。 +- `tests/hotmail-utils.test.js`：测试 Hotmail 工具层的账号筛选、验证码提取和消息匹配逻辑。 +- `tests/icloud-mail-content.test.js`：测试 iCloud Mail 内容脚本读取邮件正文和选中状态逻辑。 +- `tests/icloud-utils.test.js`：测试 iCloud 工具层的 host、别名列表、保留状态与筛选逻辑。 +- `tests/luckmail-utils.test.js`：测试 LuckMail 工具层的购买记录、邮件、游标和验证码匹配逻辑。 +- `tests/microsoft-email.test.js`：测试 Microsoft 邮件拉取与验证码提取逻辑。 +- `tests/sidepanel-hotmail-manager.test.js`：测试侧边栏 Hotmail 管理器模块接线与空态渲染。 +- `tests/sidepanel-icloud-manager.test.js`：测试侧边栏 iCloud 管理器模块接线与空态渲染。 +- `tests/sidepanel-icloud-provider.test.js`：测试侧边栏 iCloud 登录地址解析逻辑。 +- `tests/sidepanel-luckmail-manager.test.js`：测试侧边栏 LuckMail 管理器模块接线与空态渲染。 +- `tests/signup-page-tab-cleanup.test.js`：测试注册页来源标签的冲突清理逻辑。 +- `tests/step-definitions-module.test.js`：测试共享步骤定义模块及侧边栏脚本加载顺序。 +- `tests/step5-chatgpt-onboarding.test.js`：测试 Step 5 的 ChatGPT onboarding 判断与跳过逻辑。 +- `tests/step5-chatgpt-redirect-race.test.js`：测试 Step 5 跨域跳转 race 下的 chatgpt.com 兜底判断。 +- `tests/step6-login-state.test.js`：测试 Step 6 登录状态判断逻辑。 +- `tests/step8-callback-handling.test.js`：测试 Step 8 回调地址捕获逻辑。 +- `tests/step8-debugger-stop.test.js`：测试 Step 8 调试器点击在 Stop 场景下的中止行为。 +- `tests/step8-state-timeout-retry.test.js`：测试 Step 8 通信错误是否可判定为可重试。 +- `tests/step8-stop-cleanup.test.js`：测试 Step 8 在 Stop 后能正确清理监听器与挂起状态。 +- `tests/step9-cpa-mode.test.js`：测试本地 CPA Step 9 策略判断。 +- `tests/step9-localhost-cleanup-scope.test.js`：测试 Step 9 仅清理精确命中的 localhost callback 和路径前缀残留页。 +- `tests/verification-stop-propagation.test.js`：测试验证码流程在 Stop 场景下的错误传播与不中途降级。