chengmaandClaude Opus 4.8
c8a5e9ada8
- 新增 docs/cmhub-integration-design.md（v3.2）：对接 cmhub 生文/生图/余额/别名发现接口的设计、迁移策略、错误与重试、待确认项 - docs/06-tasks.md：新增 Phase 7（T-526~T-528）AI 网关对接任务，补充别名动态下拉与 fetch_cmhub_models helper；相关文档索引与工程/打包任务同步 - 同步 README/03-tech-stack/current-state/packaging/troubleshooting/ux-review 文档 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
57 lines
4.2 KiB
Markdown
57 lines
4.2 KiB
Markdown
# 项目文档导航
|
||
|
||
> cmshopee 的 harness coding 文档集合。agent 开始编程前从 [`00-ai-start-here.md`](00-ai-start-here.md) 进入。
|
||
|
||
## 一句话定位
|
||
|
||
cmshopee 是一个给**电商运营**使用的 Windows PySide6 桌面自动化工具，用于**管理多个 Shopee 卖家账号、并用 CDP 驱动 Chrome 批量修改商品标题、替换商品封面图**。V0 已验证单账号「改标题 + 换封面」闭环；当前 V1 目标是 5 Tab 流水线：导入采集 → AI 生成 → 点击「开始更新」并确认后批量提交 → 回写结果。
|
||
|
||
## 文档导航
|
||
|
||
- [`../AGENTS.md`](../AGENTS.md)：Codex / 通用 AI coding agent 的仓库级入口。
|
||
- [`../CLAUDE.md`](../CLAUDE.md)：Claude Code 的薄入口，具体规则以 `AGENTS.md` 为准。
|
||
- [`../progress.md`](../progress.md)：执行历史流水，只追加记录任务执行、验证、阻塞和决策。
|
||
- [AI 开发入口](00-ai-start-here.md)：agent 每次开始工作的入口、阅读顺序和任务领取规则。
|
||
- [项目愿景](01-vision.md)：为什么做、为谁做、产品原则、非目标。
|
||
- [需求](02-requirements.md)：要什么、用户故事、验收标准。
|
||
- [技术栈](03-tech-stack.md)：语言、运行平台、CDP 方案、GUI 选型和运行命令。
|
||
- [架构设计](04-architecture.md)：模块职责、账号与配置目录数据模型、CDP 已验证事实和开发顺序。
|
||
- [编码规则](05-coding-rules.md)：写代码前必须遵守的硬约束。
|
||
- [任务看板](06-tasks.md)：按依赖拆分的小任务，agent 每轮只做一个。
|
||
- [模块 / CLI 合约](api.md)：本地模块接口、Chrome 启动参数、账号配置 schema。
|
||
- [界面与流程结构](routes.md)：GUI 窗口、操作流程、按钮职责（无前端路由，用 GUI 流程替代）。
|
||
- [当前实现状态](current-state.md)：当前代码现实、可运行命令、下一步可做任务。
|
||
- [常见问题排查](troubleshooting.md)：本地配置、启动报错、敏感文件修复等排障记录。
|
||
- [产品与 UI 评估](ux-review.md)：以 PM + UI 设计视角评估 5 Tab 模块 / 组件合理性，含优化方案与优先级清单。
|
||
- [界面配色设计](ui-color-design.md)：语义色板与组件配色映射规范，指导给状态 / 按钮 / 校验 / 登录状态上色。
|
||
- [工程评估](engineering-review.md)：全栈视角评估工程基础设施与可维护性（依赖清单 / CI / 打包 / gui.py 拆分 / lint），含 P0-P2 与优先级。
|
||
- [打包与分发](packaging.md)：PyInstaller 免安装 exe 打包命令、排除本地数据规则和用户手动更新方式。
|
||
- [对接 cmhub AI 网关设计](cmhub-integration-design.md)：把生文/生图从本地直连改为对接 cmhub 计费网关的设计方案、改动边界与待确认问题。
|
||
|
||
## 运行环境安装
|
||
|
||
```powershell
|
||
python -m pip install -r requirements.txt
|
||
python -m compileall app main.py
|
||
python -m unittest discover -s tests
|
||
python -m pip install -r requirements-build.txt
|
||
powershell -ExecutionPolicy Bypass -File scripts\build_exe.ps1
|
||
```
|
||
|
||
`requirements.txt` 只锁定运行所需第三方依赖；打包环境使用 `requirements-build.txt` 安装 PyInstaller；`config.json`、`config/ai_models.json`、SQLite、图片、登录态和运营 Excel 仍是本地数据，不提交版本库。
|
||
|
||
GitHub Actions 工作流见 `.github/workflows/tests.yml`，在 push / pull_request 上使用 Windows + Python 3.11 安装 `requirements.txt`，并自动运行语法检查和全量单元/GUI 测试。
|
||
|
||
## 任务 / 进度 / 当前状态
|
||
|
||
- `06-tasks.md` 维护任务看板：任务 ID、依赖、验收要点和状态。
|
||
- `../progress.md` 维护执行进度：每轮实际做了什么、跑了什么验证、遇到什么阻塞、做了什么决策。
|
||
- `current-state.md` 维护当前快照：当前目录、可运行命令、已完成摘要和下一个可领取任务。
|
||
|
||
## 维护原则
|
||
|
||
- 需求变化先改文档，再改代码。
|
||
- CDP 交互的关键事实（选择器、就绪判断、上传/拖拽方式）一旦定稿，写入 `04-architecture.md`，代码不得另起一套。
|
||
- 涉及账号、登录凭证、Cookie 时，文档与代码只用占位符或路径引用，绝不写入真实值。
|
||
- agent 开始新任务前，必须从 `00-ai-start-here.md` 进入。
|