update

Author: ty19880929

AGENTS.md

@@ -0,0 +1,32 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+`deeptrade/` contains the Python package and CLI framework. Core services live in `deeptrade/core/`, public plugin-facing contracts live in `deeptrade/plugins_api/`, and command modules are split across `cli.py`, `cli_config.py`, `cli_data.py`, and `cli_plugin.py`. Database migrations are stored under `deeptrade/core/migrations/core/`. Tests mirror the package layout under `tests/core/`, `tests/cli/`, and `tests/plugins_api/`. Build and tool configuration lives in `pyproject.toml`, `pytest.ini`, `ruff.toml`, `mypy.ini`, and `.pre-commit-config.yaml`.
+
+## Build, Test, and Development Commands
+
+- `uv sync --all-extras` installs runtime, dev, and plugin-runtime dependencies.
+- `uv run pre-commit install` enables local hooks for Ruff, formatting, mypy, and basic file checks.
+- `uv run pytest` runs the full test suite.
+- `uv run pytest tests/core/test_db.py::test_name` runs one focused test.
+- `uv run pytest -m "not manual"` skips tests marked `manual`.
+- `uv run ruff check . && uv run ruff format .` lints and formats the repository.
+- `uv run mypy deeptrade` type-checks the package; CI checks `deeptrade/`, not `tests/`.
+- `uv run python -m build` builds distribution artifacts.
+
+## Coding Style & Naming Conventions
+
+Target Python 3.11. Use 4-space indentation, double quotes, and Ruff formatting with a 100-character line length. Ruff checks `E`, `F`, `I`, `UP`, `B`, and `W`; `B008` is intentionally ignored because Typer options use call expressions in defaults. Keep public plugin APIs in `deeptrade/plugins_api/` stable and minimal. Do not add business strategies or Tushare-derived business tables to this framework repository; strategies belong in separate plugins.
+
+## Testing Guidelines
+
+Use pytest. Name tests `test_*.py` and place them near the relevant area under `tests/`. Prefer isolated unit tests for core services and CLI routing. Tests that touch secrets must avoid the real OS keyring; follow the existing fixtures in `tests/conftest.py`. Mark manually verified cases with `@pytest.mark.manual` so they can be skipped with `-m "not manual"`.
+
+## Commit & Pull Request Guidelines
+
+Recent history uses Conventional Commit-style subjects, for example `feat(plugins): ...`, `docs(claude): ...`, and `release(v0.4.2): ...`. Keep commits scoped and imperative. Pull requests should describe behavior changes, list tests run, link related issues, and include screenshots or terminal output when CLI behavior changes.
+
+## Security & Configuration Tips
+
+Do not commit credentials, local DuckDB files, generated reports, or plugin installs. Use `DEEPTRADE_HOME` or `DEEPTRADE_DB_PATH` to isolate local test data. Secrets belong in the configured secret store, not in `app_config` or source files.

README.md

@@ -4,7 +4,7 @@
 
 > 📖 **在线文档**：[deeptrade.tiey.ai](https://deeptrade.tiey.ai) — 用户手册 + 开发者手册 + 官方插件目录
 
-[![tests](https://img.shields.io/badge/tests-passing-brightgreen)](#) [![python](https://img.shields.io/badge/python-3.11+-blue)](#) [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE) [![version](https://img.shields.io/badge/version-0.3.0-blue)](CHANGELOG.md)
+[![tests](https://img.shields.io/badge/tests-passing-brightgreen)](#) [![python](https://img.shields.io/badge/python-3.11+-blue)](#) [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE) [![version](https://img.shields.io/badge/version-0.4.2-blue)](CHANGELOG.md)
 
 ## ✨ 主要特性
 
@@ -75,6 +75,13 @@ deeptrade volume-anomaly evaluate         # T+N 自动回测闭环
 deeptrade volume-anomaly stats            # 收益统计聚合
 ```
 
+> **插件 Python 依赖（v0.4.0+）**：`deeptrade_plugin.yaml::dependencies` 中以 PEP 508 形式声明的依赖，会在 `plugin install` / `plugin upgrade` 期间被框架自动装入当前 Python 解释器（探测顺序 `uv pip install` → `python -m pip install`，已满足条件的 spec 跳过）。
+>
+> - `--no-deps`：跳过依赖安装步骤（适合离线环境，需自行 `pip install` 准备运行环境）
+> - `--reinstall-deps`：对全部声明的 spec 强制重跑 installer（带 `--upgrade`）
+> - 失败时框架会在错误信息中归因到"框架核心依赖"或具体已装插件，便于排查 spec 冲突
+> - 超时阈值（默认 300s）可用 `DEEPTRADE_DEP_INSTALL_TIMEOUT` 覆盖
+
 > **第三方 / 本地开发插件**：`deeptrade plugin install <SOURCE>` 三种来源统一处理，判定顺序为 *本地目录存在 → git URL → 注册表短名*：
 >
 > - `deeptrade plugin install ./path/to/my-plugin` — 本地目录
@@ -95,11 +102,11 @@ deeptrade volume-anomaly stats            # 收益统计聚合
 | `deeptrade db init` / `db upgrade` | 显式建库 / 应用待执行迁移 |
 | `deeptrade config {show, set, set-tushare, set-llm, list-llm, test-llm}` | 全局配置 |
 | `deeptrade plugin search [keyword] [--no-cache]` | 浏览官方注册表 |
-| `deeptrade plugin install <SOURCE> [--ref <REF>] [-y]` | 注册表短名 / GitHub URL / 本地路径 |
+| `deeptrade plugin install <SOURCE> [--ref <REF>] [--no-deps] [--reinstall-deps] [-y]` | 注册表短名 / GitHub URL / 本地路径；依赖按 PEP 508 自动解析装入框架解释器 |
 | `deeptrade plugin list` / `info <id>` | 列表 / 详情（未安装时回退注册表条目） |
 | `deeptrade plugin enable <id>` / `disable <id>` | 启 / 停 |
-| `deeptrade plugin uninstall <id> [--purge]` | 卸载（`--purge` 才 DROP 表） |
-| `deeptrade plugin upgrade <SOURCE> [--ref <REF>]` | 升级（SemVer 比较，禁止降级；增量 migrations） |
+| `deeptrade plugin uninstall <id> [--purge]` | 卸载（`--purge` 才 DROP 表；依赖**不**反向卸载） |
+| `deeptrade plugin upgrade <SOURCE> [--ref <REF>] [--no-deps] [--reinstall-deps]` | 升级（SemVer 比较，禁止降级；只跑增量 migrations + 依赖） |
 | `deeptrade data sync ...` | （暂停用，下版本恢复；改用插件自带的 sync 子命令） |
 
 保留字（不可作为 plugin_id）：`init / config / plugin / data / db`。
@@ -139,6 +146,20 @@ deeptrade volume-anomaly stats            # 收益统计聚合
 
 每个插件通过自己的 migrations 声明并拥有 `<prefix>_*` 业务表；`tushare_sync_state` / `tushare_calls` / `llm_calls` 按 `plugin_id` 维度隔离，`__framework__` 为框架自身保留 sentinel。
 
+## 🛠️ Troubleshooting / 环境变量
+
+框架行为通过环境变量调节；以下几个在排错与隔离测试时最常用：
+
+| 变量 | 默认 | 行为 |
+|---|---|---|
+| `DEEPTRADE_DEBUG` | unset | 置 `1` / `true` / `yes` / `on` 时，插件 dispatch 报错改为输出完整 `traceback`（含 `__cause__` 链）；否则只打一行 `✘ {ExcType}: {msg}` |
+| `DEEPTRADE_SKIP_AUTO_MIGRATE` | unset | 逃生通道：置 `1` 时跳过 `Database()` 构造时的自动 `apply_core_migrations`。仅用于"一次失败迁移把所有 CLI 命令都堵住"的恢复场景，正常流程**不要**用 |
+| `DEEPTRADE_DEP_INSTALL_TIMEOUT` | `300` | 单次 `uv pip install` / `python -m pip install` 子进程的秒级超时上限 |
+| `DEEPTRADE_HOME` | `~/.deeptrade` | 本地工件根目录覆盖（DuckDB 文件、插件安装目录、注册表缓存、reports 都在这下） |
+| `DEEPTRADE_DB_PATH` | `<DEEPTRADE_HOME>/deeptrade.duckdb` | 单独覆盖 DuckDB 文件路径（不影响其他工件） |
+
+凡 `Database()` 构造时（即任何 `deeptrade <…>` 命令首次落地）都会跑一次 `apply_core_migrations`，所以 0.4.2+ 的用户升级后无需再手动 `deeptrade db upgrade`。
+
 ## 📖 参考
 
 - [CHANGELOG.md](CHANGELOG.md) — 版本变更与历次 breaking change 记录