From 3336e3a20c156d32324c394f43df2f18b68ea8d2 Mon Sep 17 00:00:00 2001 From: yeuimu <2197651308@qq.com> Date: Thu, 10 Sep 2026 06:43:04 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20AGENTS.md=20=E7=B2=BE=E7=AE=80=E4=BE=9D?= =?UTF-8?q?=E8=B5=96=E7=AE=A1=E7=90=86,=20=E8=BF=90=E8=A1=8C=E7=8E=AF?= =?UTF-8?q?=E5=A2=83=E4=B8=8E=E9=83=A8=E7=BD=B2=E6=A8=A1=E5=9E=8B=E5=90=88?= =?UTF-8?q?=E5=B9=B6=E4=B8=BA=E9=83=A8=E7=BD=B2=E6=B5=81=E7=A8=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 38 ++++++++------------------------------ 1 file changed, 8 insertions(+), 30 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7828e4b..ff63089 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,26 +12,11 @@ ETL 工作流项目,使用 [Prefect](https://docs.prefect.org.cn/v3/get-started) - 新增系统是加法式:加一个 `api/<系统>/` + 一个 flow,不碰旧代码。 - 详细架构说明见 [`docs/dev/systematic-design.md`](docs/dev/systematic-design.md)。 -## 依赖管理:使用 uv(不要用 requirements.txt) +## 依赖管理 -本项目用 [uv](https://docs.astral.sh/uv/) 管理依赖,锁定文件为 `uv.lock`。 -**没有 requirements.txt,也不要新建。** +用 [uv](https://docs.astral.sh/uv/) 管理依赖(锁定文件 `uv.lock`,Python `>=3.12`):`uv sync` 装依赖,`uv add/remove` 增删包,一切命令用 `uv run ...` 前缀,不要直接用系统 `python` / `pip`。提交时一并提交 `pyproject.toml` 和 `uv.lock`;不要新建 requirements.txt,不要提交 `.venv/`。 -```bash -uv sync # 按 uv.lock 安装依赖到 .venv(首次/拉取代码后执行) -uv add # 添加依赖(自动写入 pyproject.toml + 更新 uv.lock) -uv add --dev # 添加开发依赖 -uv remove # 移除依赖 -uv lock --upgrade # 升级所有依赖的锁定版本 -uv run python # 在项目环境中运行(无需手动激活 venv) -uv run prefect # 运行 prefect CLI -``` - -- Python 版本固定为 `>=3.12`(见 `pyproject.toml`)。 -- 所有命令都用 `uv run ...` 前缀,**不要**直接用系统 `python` / `pip`。 -- 提交代码时一并提交 `pyproject.toml` 和 `uv.lock`;**不要提交 `.venv/`**。 - -## 运行环境 +## 部署流程 - **Prefect server + worker**:自托管,通过 Docker Compose 运行(server + worker 容器),数据持久化。 ```bash @@ -40,18 +25,11 @@ uv run prefect # 运行 prefect CLI docker compose logs -f prefect-worker # 看 worker 日志 docker compose down # 停止 ``` -- **API 地址**:`http://localhost:4200/api`(本机)/ `http://192.168.124.92:4200`(局域网)。 -- 客户端已配置:`uv run prefect config set PREFECT_API_URL="http://localhost:4200/api"`。 - -## 部署模型:Work Pool + Git 拉取(推送即生效) - -- 代码托管在自托管 Gitea:`ssh://git@gitea.inkreach.cc:2222/inkreachhub/inkreach-prefect.git`。分支:`main`(主干,worker 拉取)、`develop`(开发)、`deploy`(部署)。 -- worker 是 **Docker 容器**(`prefect-worker` 服务,基于 `Dockerfile`),镜像只装依赖(git + uv 按锁文件装),**不烤业务代码**。 -- 每个 flow run 执行前,pull 步骤从 Gitea **clone 最新代码**(token 存 `gitea-token` Secret Block,运行时解析)。 -- **改 flow 代码 → `git push` → 下次 run 自动用新代码**(worker 不重启、不 redeploy)。 -- 改 deployment 配置(cron/参数)才需重跑:`uv run prefect deploy --all`(读取 `prefect.yaml`)。 -- **日常开发流程**:本地开发机 clone Gitea 仓库 → 改代码 → `git push` → 自动生效。 -- 旧远程 Gitee(`git@gitee.com:inkreachZLL/inkreach-prefect.git`)已退役,保留作历史快照,不再推送。 +- **API 地址**:`http://localhost:4200/api`(本机)/ `http://192.168.124.92:4200`(局域网);客户端已配置 `PREFECT_API_URL`。 +- 代码托管在自托管 Gitea:`ssh://git@gitea.inkreach.cc:2222/inkreachhub/inkreach-prefect.git`。分支:`main`(主干,worker 拉取)、`develop`(开发)、`deploy`(部署);旧远程 Gitee(`git@gitee.com:inkreachZLL/inkreach-prefect.git`)已退役保留。 +- worker 是 **Docker 容器**(`prefect-worker` 服务,基于 `Dockerfile`),镜像只装依赖(git + uv 按锁文件装),**不烤业务代码**;每个 flow run 执行前,pull 步骤从 Gitea **clone 最新代码**(token 存 `gitea-token` Secret Block,运行时解析)。 +- **改 flow 代码 → `git push` → 下次 run 自动用新代码**(worker 不重启、不 redeploy);改 deployment 配置(cron/参数)才需重跑 `uv run prefect deploy --all`(读取 `prefect.yaml`)。 +- **日常开发流程**:clone Gitea 仓库 → 改代码 → `git push` → 自动生效。 ## 密钥管理(标准做法) -- 2.54.0