gurveervirk/deputy

# deputy Python 的代码智能 CLI。使用 [deproc](https://github.com/gurveervirk/deproc) 解析源文件，将实体（类、函数、导入等）存储在本地 SQLite 数据库中，并提供搜索、检查和解析符号的命令。 ## 安装说明 ``` pip install deputy # 或： uv tool install deputy ``` ## 快速开始 ``` deputy init # create database deputy sync # scan & index project deputy sync --sync-deps # also index dependencies from .venv deputy search "Model" # find entities matching regex deputy info deputy.core.create_context # inspect an entity deputy info --resolve deputy.utils.storage.FileMetadata # resolve through imports ``` ## 配置 deputy 使用位于项目根目录的键值对配置文件 (`.deputyconfig`)： ``` db_path=/absolute/path/to/custom.db venv_path=/path/to/venv sync_deps=true max_dep_files=5000 enable_cache=true auto_sync=true log_level=WARNING log_file=/path/to/deputy.log display_mode=table ``` 使用 `deputy config ` 管理设置。 缓存为**可选 (opt-in)**。符号解析结果 (`deputy info --resolve`) 会缓存在数据库中，以加快重复查找的速度。使用以下命令启用： ``` deputy config enable_cache true ``` 自动同步为**可选 (opt-in)**。启用后，`deputy search` 和 `deputy info` 会检查自上次同步以来源文件是否发生更改，并在查询前自动运行同步。使用以下命令启用： ``` deputy config auto_sync true ``` 搜索结果的显示模式通过 `.deputyconfig` 进行配置： ``` deputy config display_mode tree # tree grouped by hierarchy deputy config display_mode table # tabular (default) ``` ## 日志 deputy 会将结构化日志写入 `.deputy/deputy.log` 文件（项目本地）。日志级别包括：`DEBUG`、`INFO`、`WARNING`、`ERROR`。通过 `.deputyconfig` 进行配置： ``` deputy config log_level DEBUG # most verbose deputy config log_level WARNING # default deputy config log_level ERROR # errors only ``` 覆盖日志文件路径： ``` deputy config log_file /custom/path/deputy.log ``` 同时也支持 `DEPUTY_LOG_LEVEL` 环境变量。 ### CLI flags 所有命令都接受 `--verbose` / `-v`（将日志级别设置为 `DEBUG`）和 `--quiet` / `-q`（将日志级别设置为 `ERROR`）： ``` deputy -v sync deputy --quiet search "Model" ``` ## 命令 ### `deputy init [--path ]` 在给定路径（默认为 `.deputy.db`）创建一个 SQLite 数据库。将当前目录记录为项目根目录。自动检测处于活动状态的虚拟环境，并将 `venv_path` 写入 `.deputyconfig`。 ### `deputy sync [--force] [--sync-deps] [--no-sync-deps]` 扫描项目根目录下的所有 `.py` / `.pyi` 文件，使用 deproc 解析它们，并将所有发现的实体持久化到数据库中。默认采用增量同步：仅重新解析内容哈希发生变化的文件。`--force` 会重新处理所有内容。 `--sync-deps` 还会从项目的 `.venv` 中索引依赖包。每个包的顶层模块都会被解析并作为独立实体链接到数据库中（标记为 `source: "dependency"`）。可编辑的（基于路径的）依赖会自动跟随到其源目录。 即使配置中设置了 `sync_deps=true`，`--no-sync-deps` 也会跳过依赖索引。 以下目录和模式会被排除在发现和链接范围之外： - `__pycache__/`（硬编码） - `*.egg-info`、`*.dist-info` - `node_modules/` - `.git/`、`.venv/`、`.mypy_cache/`、`.pytest_cache/` - `build/`、`dist/` ### `deputy search [options] ` 在数据库中查询 `full_path` 或 `name` 匹配正则表达式的实体。支持显示过滤器和输出模式。 **过滤选项：** | Flag | 描述 | |------|-------------| | `--type` / `-t TEXT` | 按实体类型过滤（可重复：`FUNCTION`、`CLASS`、`MODULE`、`PACKAGE`、`CONSTANT`、`TYPE_ALIAS`、`IMPORT_ALIAS`） | | `--language` / `-l TEXT` | 按语言过滤（例如 `python`） | | `--limit INT` | 最大结果数 | | `--offset INT` | 结果偏移量 | | `--exact` / `-e` | 精确匹配 `full_path`（不使用正则表达式） | | `--name-only` / `-n` | 仅匹配 name，不匹配 `full_path` | **显示模式：** 由 `.deputyconfig` 中的 `display_mode` 配置键控制： - `table`（默认） — 带有 Name、Type、Language、Full Path 列的 `rich.table.Table` - `tree` — 按 package→module→entity 层级分组的 `rich.tree.Tree` 在 tree 模式下，`--fqn` / `-f` flag 会将完整路径附加到每个条目后： ``` deputy search "detect_venv" --fqn # Entities # └── src # └── deputy # └── venv # └── detect # └── FUNCTION detect_venv src.deputy.venv.detect.detect_venv ``` 该层级派生自以点分隔的 `full_path` 值，而不是实体类型 — 因此像 `--type` 这样的过滤器会保留树结构。 ### `deputy info [--resolve] [--all]` 通过其确切的 `full_path` 查找实体。如果不带 flags，则显示单个实体及其元数据 JSON。 `--resolve` 会跟随 import aliases 和 re-exports 以找到原始定义。例如，如果 `deputy.utils.storage.FileMetadata` 是从 `deputy.utils.storage.models` re-export 的，`--resolve` 会追踪 import 链并显示实际的类定义。 `--all` 返回匹配该 `full_path` 的所有实体（例如，在多个模块中定义的同一个类名）。 ### `deputy config [value]` 读取或写入配置键。如果带有 value，则将其持久化到 `.deputyconfig`。如果不带，则打印当前值。 ## 数据库 默认位置是项目根目录中的 `.deputy.db`。自定义位置会持久化在 `.deputyconfig` 中。 ### Schema | Table | 用途 | |---|---| | `entities` | 解析后的符号 — id、language、full_path、name、type、metadata_json | | `branch_entities` | 用于跨分支实体共享的 Branch 到 entity 映射 | | `branch_files` | 每个 branch 的文件跟踪 — 用于增量同步的内容哈希和 mtime | | `cache_entries` | 每个 (module_fqn, symbol_name) 的已解析符号缓存 | | `cache_module_links` | 用于失效处理的跨模块缓存链接 | | `dependencies` | 已索引的依赖包 — name、version、install_path、source | | `config` | 键值对存储（base_path、CLI version、sync_deps） | ### Entity Metadata 每个实体都存储一个带有特定类型字段的 `metadata_json` blob： | 字段 | 应用于 | 描述 | |---|---|---| | `lineno`、`end_lineno`、`col_offset`、`end_col_offset` | 所有实体 | 源码位置 | | `fqn` | 所有实体 | 全限定名 (Fully qualified name) | | `path` | Modules、packages | 相对文件路径 | | `visibility` | 函数、方法、类 | `public` / `private` | | `all_exports` | Modules | `__all__` 的内容 | | `exported` | 所有实体 | 是否通过 `__all__` 进行 re-export | | `original_name` | Import aliases | 别名前的名称 | | `alias` | Import aliases | 别名（如果有） | | `import_type`、`wildcard` | Import 语句 | Import 类型 | | `source` | 依赖实体 | `"dependency"`（项目实体则缺省） | | `package_name` | 依赖实体 | 源 package 名称 | ## 架构 ``` deputy CLI (typer) └─ tools/core.py ├─ init → open_database + init_schema + detect_venv ├─ sync → get_source_files → deproc parse/link → upsert_entities │ └─ --sync-deps → detect_venv → list_installed_packages → process_dependency ├─ search → SQLite REGEXP query on entities ├─ info → get_entity_by_path + optional SqlitePythonResolver.resolve() └─ config → read/write .deputyconfig ``` 依赖项：`deproc-core`、`deproc-python`、`typer`、`rich`。 ## 开发 ``` git clone https://github.com/gurveervirk/deputy cd deputy uv sync uv run pytest ```

标签：Python, SQLite, 云安全监控, 代码智能, 无后门, 逆向工具, 静态分析