From 4acac32b407a7a39d246e36416e5428c957cbd3c Mon Sep 17 00:00:00 2001 From: chengma Date: Wed, 8 Jul 2026 10:19:55 +0800 Subject: [PATCH] docs: move per-task progress into task files, stop per-task current-state overwrite MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - AGENTS.md: 收尾只更新对应任务文件（状态 + ## 执行记录），不再逐任务追加 progress.md / 覆盖 current-state.md（每任务共享写入=多 agent 抢占点） - docs/tasks/_template.md: 加 ## 执行记录 一节 - docs/tasks/README.md: 完成流程改为执行记录写进任务文件 - progress.md: 冻结为历史归档；新执行记录进任务文件 - docs/current-state.md: 不再逐任务覆盖，状态以 docs/tasks/ frontmatter 为准 Co-Authored-By: Claude Opus 4.8 --- AGENTS.md | 2 +- docs/current-state.md | 6 ++++-- docs/tasks/README.md | 3 ++- docs/tasks/_template.md | 5 +++++ progress.md | 28 +++++++++++++++------------- 5 files changed, 27 insertions(+), 17 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f019e85..43df081 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,7 +29,7 @@ - 只做当前任务范围内的事；T-504 已接入的多账号并行、dry-run、运行日志属于当前范围，其他 V2 / V3 功能只记录不实现。 - CDP 选择器 / 流程 / 配置 schema 变化，必须同步更新 `docs/04-architecture.md` 与相关任务。 - **新任务一任务一文件写进 `docs/tasks/T-<编号>.md`，不再手改 `docs/06-tasks.md`**（已冻结为 T-000~T-549 历史归档）；命名/frontmatter/领取规则见 `docs/tasks/README.md`。为避免多 agent 并发抢改同一文件、ID 撞号。 -- 改完后更新对应任务文件状态、追加 `progress.md`、覆盖 `docs/current-state.md`。 +- 改完后**只更新对应任务文件**：把状态改 `DONE`、执行记录写进该任务文件的 `## 执行记录` 一节。**不再逐任务追加 `progress.md`、不再逐任务覆盖 `docs/current-state.md`**（这两个是每任务共享写入点，多 agent 并发会互相抢/覆盖）。`progress.md` 冻结为历史归档；`docs/current-state.md` 不再手动逐任务维护，当前状态以 `docs/tasks/` 各任务 frontmatter 为准，后续可由脚本汇总生成。 ## 安全红线 diff --git a/docs/current-state.md b/docs/current-state.md index 6624768..a4aa665 100644 --- a/docs/current-state.md +++ b/docs/current-state.md @@ -1,7 +1,9 @@ # 当前实现状态 -> 本文是可覆盖的当前快照，记录代码与任务看板的现实状态。 -> 历史执行流水追加到 [`../progress.md`](../progress.md)，不在本文重复完整日志。 +> **⚠️ 本文不再逐任务手动覆盖维护**（每任务全量重写是多 agent 并发的重抢占点）。当前任务状态**以 `docs/tasks/` 各任务文件的 frontmatter（status/phase/deps）为准**；本文保留为阶段性快照，后续可由脚本从任务文件汇总生成。约定见 [`tasks/README.md`](tasks/README.md)。 +> +> 本文是阶段性快照，记录代码与任务的现实状态。 +> 历史执行流水见 [`../progress.md`](../progress.md)（已冻结归档）；新任务执行记录在各自任务文件的 `## 执行记录`。 ## 当前快照 diff --git a/docs/tasks/README.md b/docs/tasks/README.md index 7534de5..76b44a4 100644 --- a/docs/tasks/README.md +++ b/docs/tasks/README.md @@ -42,7 +42,8 @@ created: 2026-07-08 ## 状态与领取流程（同 `../06-tasks.md`「使用规则」） - 状态：`TODO` · `DOING`（同一时间最多 1 个）· `DONE` · `BLOCKED`。 -- 一次只领一个 `status: TODO` 且依赖全 `DONE` 的任务，取编号最靠前的；做完自测、改 `status: DONE`、追加 `../../progress.md`、覆盖 `../current-state.md`。 +- 一次只领一个 `status: TODO` 且依赖全 `DONE` 的任务，取编号最靠前的；做完自测、改 `status: DONE`。 +- **执行记录写进本任务文件的 `## 执行记录` 一节**（改了什么、跑了什么验证、结果、决策）——**不再逐任务追加 `../../progress.md`、不再逐任务覆盖 `../current-state.md`**（那两个是每任务共享写入点，多 agent 会抢/覆盖；`progress.md` 已冻结归档，`current-state.md` 不再手动逐任务维护、当前状态以各任务 frontmatter 为准）。 - **只改自己那个任务文件**；不要编辑别人正在做的任务文件。 ## 看板视图 diff --git a/docs/tasks/_template.md b/docs/tasks/_template.md index afb60bd..1e91425 100644 --- a/docs/tasks/_template.md +++ b/docs/tasks/_template.md @@ -22,3 +22,8 @@ created: 2026-07-08 ## 边界（不改什么） （明确不碰的模块/流程：DB schema、CDP/Shopee、Excel 等） + +## 执行记录 + +（做完在这里写：改了什么文件、跑了什么验证命令及结果、遇到的阻塞、关键决策。 +取代逐任务追加 `progress.md`——执行记录只写进本任务文件，避免多 agent 抢改共享文件。） diff --git a/progress.md b/progress.md index c56216e..b48a7a5 100644 --- a/progress.md +++ b/progress.md @@ -1,5 +1,7 @@ # 执行进度记录 +> **⚠️ 本文件已冻结为历史归档，不再逐任务追加。** 新任务的执行记录写进各自的任务文件 `docs/tasks/T-<编号>.md` 的 `## 执行记录` 一节——避免多 agent 并发抢改本共享文件。约定见 [`docs/tasks/README.md`](docs/tasks/README.md)。 +> > 本文件是只追加的历史流水，记录任务执行过程、验证命令、阻塞点和关键决策。 > 当前目录、当前命令、下一个可领取任务等可覆盖快照，写入 [`docs/current-state.md`](docs/current-state.md)。 > 历史条目里的“下一步”只代表当时判断，不作为当前任务领取依据；当前任务必须按 [`docs/06-tasks.md`](docs/06-tasks.md) 的顺序与 [`docs/current-state.md`](docs/current-state.md) 的快照执行。 @@ -1060,33 +1062,33 @@ - 代码：`app/editor.py` 在 `open_product()` 导航商品详情页前后安装 toast 观察器，缓存最近 toast 的文本、HTML、URL、可见状态和时间；`_wait_ready()` 超时或检测到失效 toast 时，将商品失效/商品不存在/无权限类文案上浮为 `商品失效：<原始toast>`，其他打开失败仍保持普通失败原因。 - GUI：①导入采集任务表只在 `last_error` 明确包含商品失效类错误时把“阶段”列显示为“商品失效”；底层 DB 不新增 stage 枚举，仍保持 `stage=imported/status=failed`，其他超时、网络、登录、风控类错误仍显示“失败”。 - 测试：`tests/test_editor_login.py` 覆盖隐藏 toast 捕获、失效 toast 错误上浮和 open_product 安装观察器；`tests/test_gui.py` 覆盖只有明确失效错误才显示“商品失效”。 -- 验证：已通过相关测试；全量验证见本轮最终结果。 +- 验证：已通过相关测试；全量验证见本轮最终结果。 ## 【2026-07-02】文档补充 · T-404b 商品失效失败 tab 清理 - 问题：商品 ID 失效时，`_wait_ready()` 在 `open_product()` 内部抛出 `商品失效：...`，上层 `collect()` / `apply_task()` 尚未拿到 `cdp`，因此上层 finally 无法关闭本轮自动新建的商品 tab。 - 方案：补充 T-404b 边界。`open_product()` 如果在返回 `cdp` 前失败，要自行清理：本轮自动新建 tab 先断开 CDP 再调用 `close_tab(target_id, host=...)`；复用用户原本打开的 tab 只断开 CDP，不关闭页面。进入编辑页后的更新失败仍按原设计保留现场。 - 文档：同步 `docs/02-requirements.md`、`docs/04-architecture.md`、`docs/routes.md`、`docs/api.md`、`docs/06-tasks.md`、`docs/current-state.md`。 -- 验证：文档-only 更新，未运行单元测试。 +- 验证：文档-only 更新，未运行单元测试。 ## 【2026-07-02】T-404b 补丁完成 · 商品失效失败 tab 自动清理 - 代码：`app/editor.py` 新增 `open_product()` 内部失败清理。若 `_wait_ready()` 因商品失效 toast 或其他打开页异常在返回 `cdp` 前抛错，会先断开 CDP；本轮自动新建的商品 tab 继续调用 `close_tab(target_id, host=...)` 关闭，复用用户已有 tab 不关闭。 - 边界：只处理 `open_product()` 内部打开失败导致的残留 tab；进入编辑页后的更新失败仍按原设计保留现场，成功提交后的关闭仍受 ⑤ `close_success_tab` 控制。 - 测试：`tests/test_editor_login.py` 增加自动新建 tab 商品失效时关闭、复用 tab 商品失效时不关闭的覆盖。 -- 验证：`python -m unittest discover -s tests -p "test_editor_login.py"` 通过（36 tests）。 +- 验证：`python -m unittest discover -s tests -p "test_editor_login.py"` 通过（36 tests）。 ## 【2026-07-02】文档 · T-103b 登录检测补充识别 Shopee accounts 登录页 - 需求：打开商品详情页或卖家中心时，未登录账号可能跳转到 `https://accounts.shopee.tw/seller/login...`。④「检测登录」以及①/③执行前账号预检应明确把该 URL 判为未登录，不能依赖模糊规则或误判为普通无 Cookie。 - 方案：新增 T-103b。登录页 URL marker 显式加入 `accounts.shopee.tw/seller/login` / Shopee accounts 域名下 `/seller/login`；`login_status()` 返回 `logged_in=false/reason=LOGIN_PAGE/url=<实际URL>`；④状态列显示“未登录”，①/③预检继续阻断并引导去④。 - 边界：不自动登录、不填密码、不绕过验证码；只增强登录页识别和测试覆盖，不改 CDP 商品页、上传、提交逻辑。 - 文档：同步 `docs/02-requirements.md`、`docs/04-architecture.md`、`docs/routes.md`、`docs/api.md`、`docs/06-tasks.md`、`docs/current-state.md`；当前下一个可领取任务改为 T-103b。 -- 验证：文档-only 更新，未运行单元测试。 +- 验证：文档-only 更新，未运行单元测试。 ## 【2026-07-02】T-103b 完成 · 登录检测补充识别 Shopee accounts 登录页 - 代码：`app/editor.py` 的 `LOGIN_PATH_MARKERS` 显式加入 `accounts.shopee.tw/seller/login`，`_is_login_url()` 增加 `accounts.shopee.*` 域名且路径以 `/seller/login` 开头的判断。 - 行为：`login_status()` 遇到 `https://accounts.shopee.tw/seller/login...` 立即返回 `logged_in=false/reason=LOGIN_PAGE/url=<实际URL>`，④状态列会显示未登录，①/③预检继续阻断并引导去④。 - 边界：不自动登录、不填密码、不绕过验证码；未改商品页、上传、提交逻辑。 - 测试：`tests/test_editor_login.py` 增加真实 accounts 登录 URL 覆盖。 -- 验证：`python -m unittest discover -s tests -p "test_editor_login.py"` 通过（37 tests）。 +- 验证：`python -m unittest discover -s tests -p "test_editor_login.py"` 通过（37 tests）。 ## 【2026-07-03】T-524 完成 · PyInstaller 打包为免安装 exe @@ -1134,7 +1136,7 @@ - 边界：只改②AI生成 UI、worker 事件处理和测试；未改 AI HTTP 协议、DB schema、Excel、Shopee/CDP 流程。 - 文档：`docs/06-tasks.md` 将 T-528 标为 DONE；同步 `docs/current-state.md`，下一个可领取任务回到 T-525 ruff。 - 测试：`python -m unittest discover -s tests -p test_gui.py` 通过（80 tests）；`python -m unittest discover -s tests -p test_ai.py` 通过（17 tests）；`python -m compileall app main.py` 通过；`python -m unittest discover -s tests` 通过（187 tests）；`git diff --check` 通过，仅有本机 LF/CRLF 提示。全量测试仍有本机 PySide6 字体目录提示，不影响结果。 -- 下一步：T-525「引入 ruff（lint + format）+ 可选 pre-commit」。 +- 下一步：T-525「引入 ruff（lint + format）+ 可选 pre-commit」。 ## 【2026-07-04】T-529 完成 · 默认 cmhub 网关并隐藏 AI 后端选择 - 状态：DONE @@ -1175,22 +1177,22 @@ - 边界：URL、配置键、API 字段、模型别名、第三方/Shopee 原始错误可保留原文，但外围必须给中文解释；不得直接把英文技术报错裸露给用户。 - 文档：同步 `AGENTS.md`、`docs/05-coding-rules.md`、`docs/current-state.md`。 - 代码：同步修正 T-531 设置未保存离开确认框，改用自定义中文按钮“保存 / 放弃 / 取消”，避免系统默认按钮显示英文。 -- 验证：`python -m py_compile app\gui\main_window.py tests\test_gui.py` 通过；`python -m unittest discover -s tests -p test_gui.py` 通过（86 tests）；`python -m compileall app main.py` 通过；`python -m unittest discover -s tests` 通过（195 tests）；`git diff --check` 通过，仅有本机 LF/CRLF 提示。 - +- 验证：`python -m py_compile app\gui\main_window.py tests\test_gui.py` 通过；`python -m unittest discover -s tests -p test_gui.py` 通过（86 tests）；`python -m compileall app main.py` 通过；`python -m unittest discover -s tests` 通过（195 tests）；`git diff --check` 通过，仅有本机 LF/CRLF 提示。 + ## 【2026-07-06】运行修正 · ②AI生成失败状态分阶段提示 - 现象：在②AI生成选择一个批次，列表都是“失败”状态时点击「开始生成」，状态栏提示“当前筛选结果没有可生成任务”。 - 排查：本地最新未删除批次 `20260702_171000_75bd2557` 的 5 条任务均为 `stage=imported/status=failed/collect_attempts=3/generate_attempts=0/apply_attempts=0`，属于①采集失败，不是 AI 生成失败；②没有旧标题/旧封面，不能直接生成。 - 修正：新增 `ai.is_generatable_task()` 统一 GUI/Worker/底层批处理口径；②状态列把失败细分显示为“采集失败 / 生成失败 / 更新失败”；「开始生成」无可重试任务时提示先到①完成旧数据采集。AI 生成失败可重试，③更新失败不会被②误重试。文档补充 `docs/troubleshooting.md` 的同名排查条目。 -- 测试：新增 `test_generate_batch_retries_failed_generation_record_after_existing_result`、`test_generate_batch_does_not_retry_apply_failed_records`、`test_generate_tab_explains_collect_failed_records_are_not_generatable`。 - +- 测试：新增 `test_generate_batch_retries_failed_generation_record_after_existing_result`、`test_generate_batch_does_not_retry_apply_failed_records`、`test_generate_tab_explains_collect_failed_records_are_not_generatable`。 + ## 【2026-07-06】文档建议 · 状态栏语义颜色 - 建议：左下角状态栏按 muted/info/success/warning/danger 做轻量文字色区分，普通/就绪保持 muted 或默认，进行中用 info，成功用 success，需用户处理但可恢复的问题用 warning，失败/阻断用 danger。 - 落地边界：状态栏只做辅助反馈，不做大面积背景，不替代弹窗、空状态、运行日志和按钮禁用；后续代码建议统一 `MainWindow.show_status(message, level)`，逐步替换直接 `statusBar().showMessage(...)`。 - 文档：同步 `docs/ui-color-design.md`、`docs/ux-review.md`、`docs/06-tasks.md`、`docs/current-state.md`。 -- 验证：文档-only 更新，未运行单元测试。 - +- 验证：文档-only 更新，未运行单元测试。 + ## 【2026-07-06】文档记录 · T-105b 启动登录复用已打开 Chrome - 现象：④账号管理同一账号重复点击「启动登录」会再次打开 Chrome 窗口，而不是复用已打开账号 Chrome 创建/激活 tab。 @@ -1219,7 +1221,7 @@ - 代码：`SettingsTab._on_cmhub_finished()` 成功文案会从 worker payload 的 `balance.user`、`balance.account`、顶层字段中提取 `name/account_name/username/email/id`，优先显示 `cmhub 账号「<账号名>」连接成功：...`；无账号信息时保留 `cmhub 连接成功：...`。 - 脱敏：新增 `appconfig.mask_email()`，`sanitize_for_log()` 对 `email` / `*_email` 字段脱敏，worker 返回和 run log summary 不保存完整邮箱；设置页展示邮箱时也使用脱敏格式。 - 边界：未改 cmhub HTTP 协议、配置 schema、保存逻辑、AI 生成流程或 Shopee/CDP 流程。 -- 测试：`python -m py_compile app\appconfig.py app\gui\tabs\settings.py tests\test_appconfig.py tests\test_gui.py` 通过；`python -m unittest discover -s tests -p test_appconfig.py` 通过（9 tests）；`python -m unittest discover -s tests -p test_gui.py -k cmhub` 通过（9 tests）。 +- 测试：`python -m py_compile app\appconfig.py app\gui\tabs\settings.py tests\test_appconfig.py tests\test_gui.py` 通过；`python -m unittest discover -s tests -p test_appconfig.py` 通过（9 tests）；`python -m unittest discover -s tests -p test_gui.py -k cmhub` 通过（9 tests）。 ## 【2026-07-06】T-532 补充 · 兼容 cmhub 当前账号返回结构