arthas/AGENTS.md

AGENTS.md

本仓库是 Arthas，包含 JVM 诊断工具的 Java 多模块源码、Web 控制台和 VuePress 文档站。以下约定适用于整个仓库。

工作原则

• 从第一性原理出发：先明确要解决的问题、输入输出和必须保持的约束，再定位相关实现与测试。
• 选择能完整满足当前需求的最小实现。优先直接的控制流和已有能力；新增抽象、依赖或配置必须有具体收益。
• 修复根因，避免用多层兜底、静默吞错、伪造默认值或反复重试掩盖错误。兼容与恢复逻辑只服务于已知场景，并明确触发条件、失败结果和终止条件。
• 在输入和系统边界校验，内部依赖明确的契约，避免层层重复防御。
• 保持修改聚焦，沿用附近代码的风格。保留用户已有改动，不顺带重构、格式化或清理无关文件。

工程入口

• core/：诊断命令、字节码增强、会话与结果渲染；命令实现在 core/src/main/java/com/taobao/arthas/core/command/。
• boot/、agent/、spy/：启动与 attach、类加载隔离、插桩回调。
• arthas-mcp-server/：MCP 接口；tunnel-client/、tunnel-server/：远程连接。
• web-ui/arthasWebConsole/：Vue Web 控制台。
• site/docs/doc/、site/docs/en/doc/：中英文用户文档；site/docs/.vuepress/：站点配置、导航、主题和静态资源。
• 各模块的 src/test/ 放单元测试；arthas-mcp-integration-test/、arthas-external-command-integration-test/ 和 integration-test/ 放集成测试。

必须保持的约束

• Java 默认兼容 JDK 8，模块覆盖设置以对应 pom.xml 为准。JDK 17+ 构建会额外启用 Tunnel Server、MCP 和外部命令集成测试模块；构建行为以根 pom.xml 和 .github/workflows/test.yaml 为准。
• Arthas 运行在目标 JVM 内。诊断异常不能影响业务线程；保留必要的异常隔离和类加载隔离，确保监听器、增强和线程等资源在结束或取消时正确释放。
• 命令沿用现有 Command → Model → View 分工，保持结果数据与终端渲染分离；修改输出时检查 HTTP/MCP 等调用方的兼容性。
• 命令行为、参数或输出变化时，同步相关测试和中英文文档。增删文档页面时检查导航与相对链接。
• 修改源码，不手工编辑 target/、node_modules/、VuePress 的 .temp/、.cache/、dist/ 等生成内容。

验证与交付

按改动选择能证明行为正确的最小验证范围；修复缺陷时优先补能复现问题的回归测试。跨模块或打包变更再扩大验证范围。

以下命令在仓库根目录执行：

# Java 模块测试：将 core 替换为受影响的模块
./mvnw -pl core -am test

# MCP 集成测试：需要 JDK 17+ 和 bash，verify 阶段才执行集成测试
./mvnw -pl arthas-mcp-integration-test -am verify

# 完整构建与测试
./mvnw clean install -P full

# 文档站构建：先按 site/README.md 安装依赖
npm --prefix site run docs:build

• 文档改动检查示例、链接和页面构建；纯说明文字调整无需运行全量 Java 测试。
• 提交前检查 git diff --check 和变更范围。只格式化修改涉及的文件，避免全仓库格式化。
• 交付时简要说明改了什么、验证结果及未验证项。环境或依赖阻塞时报告具体原因，不通过增加兜底或跳过检查来伪装成功。