Skip to content

系统命令集成使用指南.md

Latest commit

 

History

History
411 lines (292 loc) · 9.22 KB

系统命令集成使用指南.md

File metadata and controls

411 lines (292 loc) · 9.22 KB

系统命令集成使用指南

🎉 新功能概述

HarmonySafeAgent 交互模式现已集成强大的系统命令执行功能，支持：

  • ✅ 智能补全：命令补全 + 文件/目录路径补全
  • ✅ 跨平台兼容：Windows 和 Unix/Linux 统一体验
  • ✅ 安全防护：危险命令自动拦截
  • ✅ 常用命令：cat, ls, cd, pwd, mvn, python 等全面支持

🚀 快速开始

启动交互模式

java -jar target/harmony-agent.jar interactive

基本用法

所有系统命令使用 $ 前缀：

# 查看当前目录
❯ $ pwd

# 列出文件
❯ $ ls
❯ $ ls -la
❯ $ ls src

# 切换目录
❯ $ cd src
❯ $ cd ../
❯ $ cd ~

# 查看文件内容
❯ $ cat README.md
❯ $ cat pom.xml

💡 智能补全功能

1. 命令补全

输入 $ 然后按 Tab 键，查看所有可用命令：

❯ $ c<Tab>
$ cat       # 显示文件内容
$ cd        # 切换目录
$ cp        # 复制文件

2. 文件/目录路径补全

输入命令后按 Tab 自动补全路径：

# cd 命令只显示目录
❯ $ cd s<Tab>
src/    scripts/

# cat 命令显示文件和目录
❯ $ cat R<Tab>
README.md    run.sh

3. 动态目录跟踪

补全会自动跟随当前工作目录：

❯ $ cd src/main
❯ $ ls <Tab>          # 显示 src/main 下的内容
java/    resources/

❯ $ cd ../../
❯ $ ls <Tab>          # 现在显示项目根目录内容
src/    pom.xml    README.md

📋 支持的命令清单

目录操作

命令 说明 示例
$ pwd 打印当前工作目录 $ pwd
$ cd <path> 切换目录 $ cd src, $ cd ~/, $ cd ../
$ ls [options] 列出目录内容 (跨平台) $ ls, $ ls -la, $ ls src
$ dir Windows目录列表 $ dir
$ mkdir <name> 创建目录 $ mkdir build

文件操作

命令 说明 示例
$ cat <file> 显示文件内容 $ cat pom.xml
$ head <file> 显示文件前几行 $ head README.md
$ tail <file> 显示文件最后几行 $ tail logs/app.log
$ more <file> 分页显示文件 $ more LICENSE
$ less <file> 可滚动显示文件 $ less src/Main.java
$ cp <src> <dst> 复制文件 $ cp file1.txt file2.txt
$ mv <src> <dst> 移动/重命名文件 $ mv old.txt new.txt
$ touch <file> 创建空文件 $ touch test.txt
$ rm <file> ⚠️ 删除文件 $ rm temp.txt (有安全检查)

搜索命令

命令 说明 示例
$ find <path> 搜索文件 $ find . -name "*.java"
$ grep <pattern> <file> 在文件中搜索文本 $ grep "TODO" src/Main.java
$ which <cmd> 查找命令位置 $ which java

开发工具

命令 说明 示例
$ mvn <goal> Maven构建 $ mvn clean install
$ java <class> 运行Java程序 $ java -jar app.jar
$ javac <file> 编译Java代码 $ javac Test.java
$ python <script> 运行Python脚本 $ python script.py
$ python3 <script> 运行Python 3脚本 $ python3 app.py
$ node <script> 运行Node.js脚本 $ node server.js
$ npm <command> Node包管理器 $ npm install
$ git <command> Git版本控制 $ git status

其他命令

命令 说明 示例
$ echo <text> 打印文本 $ echo "Hello World"

🌍 跨平台支持

ls 命令统一

Windows 用户 可以直接使用 ls 命令，系统会自动转换为 dir：

# Windows 上执行
❯ $ ls         → 自动转换为 dir
❯ $ ls -la     → 自动转换为 dir /a
❯ $ ls src     → 自动转换为 dir src

路径分隔符

支持两种路径分隔符，自动适配：

# Unix/Linux 风格
❯ $ cd src/main/java

# Windows 风格
❯ $ cd src\main\java

# 两者都能正确处理！

Home 目录扩展

支持 ~ 快速访问用户目录：

❯ $ cd ~
❯ $ cd ~/Documents
❯ $ ls ~/.config

🛡️ 安全防护

危险命令拦截

以下危险命令会被自动拦截：

❯ $ rm -rf /
⚠️  Dangerous command blocked: rm -rf
This command could cause system damage

❯ $ format c:
⚠️  Dangerous command blocked: format c:
This command could cause system damage

完整黑名单

  • 文件删除: rm -rf, rm -r, del /f /s /q, rd /s /q
  • 磁盘操作: format, dd, mkfs, fdisk
  • 权限修改: chmod -R 777, chown -R
  • 系统破坏: > /dev/sda, :(){ :|:& };: (fork bomb)
  • 危险提权: sudo rm, sudo dd, sudo mkfs

🎯 使用技巧

1. 目录导航快捷键

# 返回上级目录
❯ $ cd ..

# 返回上上级目录
❯ $ cd ../../

# 切换到用户主目录
❯ $ cd ~

# 切换到上次访问的目录 (通过再次 cd 实现)
❯ $ pwd          # 记住当前路径
❯ $ cd /tmp
❯ $ cd -         # 返回之前路径 (需手动输入完整路径)

2. 查看项目结构

❯ $ pwd
E:\github\HarmonySafeAgent

❯ $ ls
src/    target/    pom.xml    README.md

❯ $ cd src/main/java
❯ $ ls<Tab>      # 补全查看 Java 源码结构

3. 快速查看文件

# 查看配置文件
❯ $ cat pom.xml

# 查看前10行
❯ $ head README.md

# 查看日志最后20行
❯ $ tail -20 logs/app.log

4. 开发工作流

# 查看 Git 状态
❯ $ git status

# 编译项目
❯ $ mvn clean compile

# 运行应用
❯ $ java -jar target/harmony-agent.jar

# 查看依赖树
❯ $ mvn dependency:tree

🔄 与其他功能结合

与 AI 聊天结合

# 使用系统命令
❯ $ ls src/main/java

# 切换到 AI 聊天
❯ 帮我分析这个项目的代码结构

# 执行内置命令
❯ /plan 实现新功能

与任务规划结合

# 创建任务计划
❯ /plan 优化项目构建流程

# 使用系统命令辅助执行
❯ $ mvn clean verify
❯ $ mvn dependency:analyze

# 标记任务完成
❯ /next

⚠️ 注意事项

1. 工作目录维护

  • 所有 $ cd 命令会改变内部工作目录
  • 但不会影响外部终端的工作目录
  • 重启交互模式会重置为初始目录

2. 长时间命令

长时间运行的命令（如 mvn clean install）会阻塞交互：

# 这会等待 Maven 完成
❯ $ mvn clean install
... (等待构建完成)

# 构建完成后才能继续输入
❯ $ ls

3. 命令输出

系统命令的输出直接显示在终端，没有额外格式化：

❯ $ ls
 目录: E:\github\HarmonySafeAgent

Mode                LastWriteTime         Length Name
----                -------------         ------ ----
d-----       2025-10-18     12:30                src
-a----       2025-10-18     10:15           3456 pom.xml

🆘 常见问题

Q: 为什么 cd 后路径没变？

A: cd 改变的是交互模式内部的工作目录，不影响外部终端。使用 $ pwd 可查看当前内部工作目录。

Q: Windows上能用Unix命令吗？

A: 部分命令如 ls 已经做了跨平台转换。其他命令如 grep、find 需要系统安装相应工具。

Q: 如何取消正在执行的命令？

A: 按 Ctrl+C 可以中断命令执行（部分命令可能无法中断）。

Q: 补全不工作怎么办？

A: 确保：

  1. 输入 $ 前缀后再按 Tab
  2. 路径存在且有权限访问
  3. 使用正确的路径分隔符

🎓 进阶用法

组合使用场景

# 场景1: 代码审查
❯ $ cd src/main/java/com/harmony/agent
❯ $ ls<Tab>           # 查看所有文件
❯ $ cat Main.java     # 查看主类
❯ What are the main security concerns in this code?  # AI分析

# 场景2: 依赖管理
❯ $ mvn dependency:tree > deps.txt
❯ $ cat deps.txt
❯ /plan 移除冗余依赖

# 场景3: 日志分析
❯ $ tail -100 logs/error.log
❯ $ grep "Exception" logs/error.log
❯ 帮我分析这些错误

📚 快捷参考卡

┌─────────────────────────────────────────────┐
│ 系统命令快捷参考                              │
├─────────────────────────────────────────────┤
│ 导航:    $ cd, $ pwd, $ ls                  │
│ 文件:    $ cat, $ head, $ tail              │
│ 搜索:    $ find, $ grep                     │
│ 构建:    $ mvn, $ java, $ python            │
│ 版本:    $ git                              │
│                                              │
│ 补全:    Tab 键                              │
│ 中断:    Ctrl+C                             │
│ 退出:    /exit 或 Ctrl+D                    │
└─────────────────────────────────────────────┘

🔗 相关文档

享受强大的系统命令集成功能！ 🚀