xxxn3m3s1sxxx/opencode-tools

# OpenCode Tools — 低延迟仓库分析与 AI 编程助手 [](https://github.com/xxxn3m3s1sxxx/opencode-tools/releases/tag/v0.5.3) [](https://github.com/xxxn3m3s1sxxx/opencode-tools/releases/tag/v0.5.3) [](https://github.com/xxxn3m3s1sxxx/opencode-tools/actions/workflows/ci.yml) [](https://github.com/xxxn3m3s1sxxx/opencode-tools) [](LICENSE) [](https://github.com/xxxn3m3s1sxxx/opencode-tools/releases/tag/v0.5.3) **20 个纯 Python stdlib 工具**，用于 AI 辅助开发：符号影响分析、文件依赖图、AST 重命名、哈希锚定编辑、lint 编排、健康摘要、工作区快照、秘密扫描、死代码检测、git 变更、预提交门控、格式化运行器等。除了 OpenCode 本身外，零 `pip install` —— 仅依赖 `os`、`ast`、`re`、`json`、`subprocess`。 运行 `pip install -e .` 后，每个工具都会成为**全局 CLI 命令** —— `graph`、`impact`、`lint`、`refactor`、`rename`、`search`、`verify`、`calltrace`、`changelog`、`hashline`、`health`、`snapshot`、`todo`、`tags`、`check`、`audit`、`fmt`、`churn`、`report`、`ghost`。全部通过 `pyproject.toml` 入口点实现，无需任何 shell 配置。 ## 快速开始 ``` git clone https://github.com/xxxn3m3s1sxxx/opencode-tools.git cd opencode-tools pip install -e . ``` 就这样。全部 20 个工具现在通过 `pyproject.toml` 入口点以**全局 CLI 命令**形式可用。无需别名，无需修改 PATH。 ## 性能 | 基准测试 | 典型耗时 | |-----------|---------| | 冷启动（任意工具，`--help`） | ~150ms | | `graph` 在单体仓库上（120 个源文件） | ~430ms | | `search` 在 5 万行代码上 | ~200ms | | `impact` 符号查找（单体仓库） | ~150ms | | 完整 CI（9 个矩阵变体） | ~5-8 分钟 | 关键设计决策：基于 `os.walk` 的文件发现（无 `glob`/`Path` 开销）、正则导入解析（非 Python 文件避免完整 AST）、哈希锚定编辑可在直接文本替换失败时处理空白/缩进不匹配。 ## 使用示例 | 类别 | 命令 | 功能说明 | |----------|---------|-------------| | **编辑** | `hashline_edit file.py --old "foo" --new "bar"` | 哈希锚定内容替换 —— 处理空白/缩进不匹配 | | | `hashline_patch file.py --diff "@@ path / + ANCHOR~text"` | 应用原始 hashline diff 格式 | | | `hashline_stats` | 显示 edit() 回退率 —— 直接匹配失败频率 | | **分析** | `impact def ` | 查找任意符号的定义（Python/C++/TS） | | | `impact refs ` | 查找符号的所有引用 | | | `impact tests ` | 查找使用该符号的测试文件 | | | `impact ` | 显示全部信息：定义 + 引用 + 测试 | | | `verify file.py` | 确认文件内容符合预期 | | | `verify file.py:42 --context 5` | 显示第 42 行附近的上下文 | | | `trace forward --down -d 3` | 递归调用链，深度 3 层 | | | `trace AtlasModel --up` | 谁调用了 AtlasModel？ | | | `graph src/main.py` | 显示文件的导入关系及依赖方 | | | `graph --circular` | 查找循环依赖 | | | `graph --stats` | 项目级依赖统计 | | | `search "def main" --include *.py` | 正则搜索，支持文件过滤 | | | `search "TODO|FIXME" --context 2` | 带上下文行显示 | | | `lint ruff` | 对当前项目运行 ruff | | | `lint tsc src/main.ts` | 对指定文件运行 tsc | | | `churn -n 10` | 变更最频繁的 Top 10 文件（最多提交） | | | `churn --since 2026-01-01` | 自指定日期以来的变更分析 | | | `tags --stats` | 项目级符号索引统计 | | | `tags ClassName` | 在索引中查找符号 | | | `ghost --lang py` | 查找未使用的 Python 函数/类 | | **重构** | `rename foo bar` | 跨所有源文件的词边界重命名 | | | `rename old_name new_name --lang py` | 仅处理 Python 文件 | | | `refactor foo bar` | **基于 AST** 的重命名 —— 对部分匹配无误报 | | | `refactor foo bar --dry-run` | 重命名前预览 | | **安全** | `audit` | 扫描秘密信息 —— API 密钥、密码、令牌 | | | `audit --json` | 输出 JSON 格式，适用于 CI | | | `check --quick` | 预提交门控 —— lint + mypy | | | `check` | 完整门控 —— lint + mypy + 测试 | | **格式化** | `fmt` | 对项目运行 ruff format | | | `fmt --check` | 检查模式（只读） | | **健康** | `health` | 完整项目健康检查 —— 测试、mypy、ruff、代码指标 | | | `health --quick` | 跳过运行测试（速度更快） | | | `health --check` | 仅当所有检查通过时退出 0 | | | `report` | 组合报告 —— 健康 + 审计 + 变更 + 格式 | | **历史** | `changelog` | 最近提交，按类别分组 | | | `changelog -n 50` | 最近 50 次提交 | | | `changelog --since 2024-01-01` | 自指定日期以来的提交 | | **工作区** | `snapshot` | 保存工作区快照至 `.opencode/snapshots/` | | | `snapshot --show` | 将快照打印到 stdout | | `snapshot --mine` | 保存并归档至 MemPalace | | | `todo` | 查找项目中的 TODO/FIXME/HACK 标记 | | | `todo --count` | 按类型汇总统计 | ## 快速安装 **Windows (PowerShell):** ``` .\install.ps1 ``` **Windows (cmd):** ``` install.bat ``` **Linux/macOS:** ``` chmod +x install.sh && ./install.sh ``` 或从 GitHub 下载： ``` curl -fsSL https://raw.githubusercontent.com/xxxn3m3s1sxxx/opencode-tools/main/install.sh | bash ``` ## 手动安装 ``` cp *.ts *.py ~/.config/opencode/plugins/ cp *.py /path/to/project/ ``` ## 所有工具 ### 核心编辑 | 工具 | 文件 | 描述 | |------|------|-------------| | `edit` | hashline.py | 通过精确匹配替换文本；自动使用哈希锚定回退重试 | | `hashline_edit` | hashline.py | 显式哈希锚定编辑 —— 处理空白、缩进、空行 | | `hashline_patch` | hashline.py | 应用原始 hashline diff 格式（`@@ path / + ANCHOR~payload`） | | `hashline_stats` | hashline.py | 显示 edit() 回退率 | ### 分析 | 工具 | 文件 | 描述 | |------|------|-------------| | `impact` | impact.py | 符号分析 —— 定义、引用、测试、调用者。Python AST + C++ 启发式 | | `verify` | verify.py | 编辑后验证 —— 确认内容、检查行、新旧对比 | | `calltrace` | calltrace.py | 递归调用链 —— 沿执行路径向上/向下追踪 | | `graph` | graph.py | 文件级依赖图 —— 导入、依赖方、循环。支持 Python/TS/C++ | | `search` | search.py | 强大的 grep —— 正则、文件过滤、上下文行、JSON 输出 | | `lint` | lint.py | 结构化 lint —— 解析 ruff/eslint/tsc/mypy/pylint 输出 | | `tags` | tags.py | ctags 样式符号索引器 —— 扫描项目定义 | | `churn` | churn.py | Git 变更分析 —— 更改最多的文件、热点 | | `ghost` | ghost.py | 死代码查找器 —— 未使用的函数、类、导入 | ### 重构 | 工具 | 文件 | 描述 | |------|------|-------------| | `rename` | rename.py | 跨所有源文件的 `\b` 词边界符号重命名 | | `refactor` | refactor.py | **基于 AST** 的重命名（Python）—— 不会因部分名称匹配而产生子串误报 | ### 安全与质量 | 工具 | 文件 | 描述 | |------|------|-------------| | `audit` | audit.py | 秘密扫描器 —— API 密钥、密码、令牌、私钥 | | `check` | check.py | 预提交门控 —— lint + mypy + 测试，仅当全部通过时退出 0 | | `fmt` | fmt.py | 格式化运行器 —— ruff format + 可选 prettier | ### 健康与工作区 | 工具 | 文件 | 描述 | |------|------|-------------| | `health` | health.py | 项目健康摘要 —— pytest、mypy、ruff、代码指标 | | `snapshot` | snapshot.py | 捕获工作区上下文，用于 MemPalace 自动保存 | | `todo` | todo.py | TODO/FIXME/HACK 标记扫描器，带计数 | | `report` | report.py | 组合报告 —— 健康 + 审计 + 变更 + 格式 | ### 历史 | 工具 | 文件 | 描述 | |------|------|-------------| | `changelog` | changelog.py | 格式化的 git 日志，含常规提交分组（feat/fix/docs/refactor） | ## 开发 ``` pip install -e . # Install all tools python -m pytest -q # Run all tests python smoke_test.py # Smoke test all tools ``` ## 测试状态（590+ 测试） | 套件 | 测试数 | 状态 | |-------|-------|--------| | hashline | 42 核心 + 22 回归 + 39 压力 + 27 深层 = 130 | ✅ 全部通过 | | impact | 63 | ✅ 全部通过 | | verify | 48 | ✅ 全部通过 | | calltrace | 28 | ✅ 全部通过 | | graph | 20 | ✅ 全部通过 | | changelog | 25 | ✅ 全部通过 | | search | 14 | ✅ 全部通过 | | lint | 17 | ✅ 全部通过 | | refactor | 21 | ✅ 全部通过 | | installers | 6 | ✅ 全部通过 | | regression | 19 | ✅ 全部通过 | | new tools | 32 | ✅ 全部通过 | | stress | 37 | ✅ 全部通过 | | deeper | 27 | ✅ 全部通过 | | health | —（运行实时检查） | ✅ 全部通过 | | snapshot | —（集成测试） | ✅ 全部通过 | | smoke | 74（自测全部 20 个工具） | ✅ 72 个通过 | ## 项目结构 ``` opencode-tools/ ├── src/ # 21 .py engines │ ├── common.py # Shared utilities (20 tools) │ ├── hashline.py # Hash-anchored editing │ ├── impact.py # Impact analysis │ ├── verify.py # Post-edit verification │ ├── calltrace.py # Recursive call chain │ ├── rename.py # Word-boundary rename │ ├── graph.py # Dependency graph │ ├── changelog.py # Formatted git log │ ├── search.py # Rich grep │ ├── lint.py # Lint runner │ ├── refactor.py # AST-based rename │ ├── health.py # Health summary │ ├── snapshot.py # Workspace snapshot │ ├── todo.py # TODO marker scanner │ ├── tags.py # Symbol indexer │ ├── check.py # Pre-commit gate │ ├── audit.py # Secret scanner │ ├── fmt.py # Format runner │ ├── churn.py # Git churn analysis │ ├── report.py # Combined report │ └── ghost.py # Dead code finder ├── plugins/ # 21 .ts OpenCode plugin wrappers │ ├── utils.ts │ ├── hashline.ts │ ├── impact.ts │ └── ... ├── tests/ # 17 test suites │ ├── test_hashline.py │ ├── test_impact.py │ ├── ... │ ├── smoke_test.py │ ├── stress_tools.py │ └── deeper_tests.py ├── install.sh # Linux/macOS installer ├── install.ps1 # Windows PowerShell installer ├── install.bat # Windows cmd installer ├── .github/workflows/ci.yml ├── pyproject.toml # Python packaging — 20 console_scripts ├── package.json # TS plugin metadata — 20 entries ├── CHANGELOG.md ├── QUALITY.md ├── LICENSE # MIT └── README.md ``` ## 技术栈 - **插件**: TypeScript, @opencode-ai/plugin v1.14.20 - **引擎**: Python 3.10+（仅 stdlib —— 零外部依赖） - **测试**: Python unittest + pytest ## 许可证 MIT

标签：AI辅助开发, AST操作, Git Churn, Git分析, Lint编排, WebSocket, 二进制发布, 云安全监控, 仓库分析, 代码分析, 代码格式化, 低延迟, 依赖分析, 凭证管理, 变更日志, 哈希锚点编辑, 安全扫描, 工作区快照, 开源工具, 性能优化, 时序注入, 检测绕过, 死代码检测, 秘密扫描, 符号影响分析, 纯Python, 自动化payload嵌入, 逆向工具, 重构工具, 零依赖, 静态分析, 预提交