panic/general_agent_cli
2
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions
No description
3 commits 1 branch 0 tags 38 KiB
Find a file
Exact
berbercai 836f403f96 更新 README.md
2026-07-23 23:23:52 +08:00
general agent cli.md 上传文件至 / 2026-06-24 12:09:30 +08:00
README.md 更新 README.md 2026-07-23 23:23:52 +08:00

README.md

GACLI · 你的过河小兵

小、专、能过河。

象棋里的兵，走不了几步、只会一步一格；可一旦过了河，就能横着走、能吃老将。 GACLI 就是这样一个"过河小兵"——单进程、零依赖也能跑、每个工具只做一件事； 一旦接上大模型（DeepSeek），这些小兵就在你桌面上横着走： 帮你查日程、开应用、调音量、截屏、记笔记、翻剪贴板……一句人话搞定。

产品提案见 PROPOSAL_v0.2.md。

🚀 一键安装（任何 macOS，30 秒）

bash <(curl -fsSL https://gitee.com/nurosub/gagli/raw/main/gacli/install.sh)

安装脚本会自动帮你：

  1. 检查 Python 3 环境（顺便提示 tkinter 是否可用）
  2. 从 Gitee 拉取最新代码到 ~/.gacli
  3. 装可选的 Python 依赖（rich / requests / PyYAML）
  4. 交互式提示你输入 DeepSeek API Key（回车可跳过，走离线规则模式）
  5. 软链 gacli 到 /usr/local/bin 或 ~/.local/bin，任何目录都能直接敲

装完就能玩：

gacli                  # 打开对话框（Agent 模式）
gacli chat --cli       # 终端 Agent
gacli demo             # 自动演示
gacli 明天有什么会      # 直接一句话

DeepSeek Key 申请：https://platform.deepseek.com/api_keys

🔄 已经装过？两种升级姿势

# 姿势 A（推荐）：一条子命令，原地升级
gacli update

# 姿势 B：重跑一键安装脚本（自动检测已装 → 更新 + 升依赖）
bash <(curl -fsSL https://gitee.com/nurosub/gagli/raw/main/gacli/install.sh)

两种都会：

  • 自动 git stash 保护你的本地改动（升级完再 stash pop 恢复）
  • 更新代码 + 升级 Python 依赖
  • 不动 .env（你的 API Key）和 config.yaml（你的自定义配置）
  • gacli update 完会显示当前版本 commit 和标题，方便确认

万一 git stash pop 报冲突：

cd ~/.gacli
git stash list      # 看看有几个暂存
git stash show -p   # 看具体冲突
git stash drop      # 确认能丢弃时清理

彻底重装（保留 .env）：

cp ~/.gacli/.env /tmp/gacli.env.bak
rm -rf ~/.gacli
bash <(curl -fsSL https://gitee.com/nurosub/gagli/raw/main/gacli/install.sh)
cp /tmp/gacli.env.bak ~/.gacli/.env

已经 clone 到本地？

cd gacli

./gacli                # ⭐ 图形对话框（推荐，Agent 自主调工具）
./gacli chat --cli     # 终端里的 Agent（无 GUI，纯文本）
./gacli demo           # 自动演示 5 个场景（路演推荐）
./gacli 明天有什么会    # 直接一句话跑
./gacli eval           # 跑准确率评测（48 条用例）

./gacli install        # 装到全局，任何目录直接 gacli

零 API Key 也能跑——L0 规则层用零成本吃掉高频固定任务；把 .env 或 config.yaml 里的 DeepSeek key 填上，才启用 Agent Loop 让大模型自主调工具。

三种打开姿势

方式 命令 适合 底层
🖼 对话框 ./gacli 日常用、路演展示 tkinter + Agent Loop
💻 终端 Agent ./gacli chat --cli 命令行党、SSH 环境 Agent Loop
⚡ 单命令 ./gacli 一句话 快捷键触发、脚本调用 三级路由（走 L0 规则最快）
🎬 自动演示 ./gacli demo 3 分钟走完全流程 三级路由

对话框模式会在启动时提示 ● LLM 已连接 (DeepSeek) 或 ● 离线规则模式； 断网/无 Key 自动降级，功能不残缺。

20 个小兵（已全部注册可用）

分类 工具 一句话
🖥 系统 (10) sys.open sys.volume sys.brightness sys.sleep sys.wifi sys.dnd sys.battery sys.process_kill sys.screenshot sys.darkmode 打开应用/音量/亮度/锁屏/WiFi/勿扰/电量/关进程/截屏/切外观
📁 文件 (1) file.search 关键词搜本地文件（mdfind）
📝 剪贴板 (2) clipboard.read clipboard.write 读/写系统剪贴板
📒 笔记 (1) note.add 追加到 ~/gacli_notes.md
🗓 日程 (1) calendar.list 未来 N 天日程 · macOS 真实读取（AppleScript 并发查询 + 60s 缓存 + 四级降级）
⏰ 时间 (2) world_clock countdown 世界时钟 / 倒计时
🔤 文本 (3) text.count text.case json2md 字数/大小写/JSON→MD

每个工具都实现了统一的 Tool Manifest 协议（tools/base.py）： 一处定义，三处消费——规则匹配、API function calling、参数校验共用同一份 schema， 不重复不漂移。

路线图（下一波过河的小兵）：网络类（天气/翻译/汇率/短链/搜索）· Git 类（status/log/commit/push）· 文件类补齐（open/reveal/recent/trash）。这些原计划要一次做完，但为了保证已有工具真的稳，先合并这一波。

架构一览

main.py            入口 / 路由调度（GUI/CLI/单命令/demo/eval）
config.yaml        配置（路由开关、模型、安全）
.env               DeepSeek API Key（gitignore，不入库）

tools/             CLI 工具层（核心竞争力）
  base.py            Tool Manifest 协议 · 一处定义三处消费
  *_tool.py          20 个小兵，真实对接 macOS

router/            三级路由（单命令模式）
  rules.py           L0 规则匹配（主力，~0ms）
  cache.py           L1 精确缓存（SQLite）
  router.py          调度 + 可观测决策记录

models/
  api_model.py       L2 API 模型（OpenAI 兼容 function calling）
  agent.py           Agent Loop：LLM 自主判断→调工具→回传→自然语言回复

ui/
  tui.py             rich 界面（单命令模式，可视化路由层级/耗时）
  chat.py            tkinter 对话框（Agent 模式，非阻塞后台线程）

两种"大脑"

单命令模式（gacli 明天有什么会）走三级路由：

L0 规则(~0ms) → L1 SQLite 缓存(~0ms) → L2 DeepSeek API(300-800ms) → L3 本地兜底

简单指令 L0 就搞定，零成本零延迟；复杂长尾才走 API。缓存路由不缓存参数—— 「明天」和「后天」路由到同一个 calendar.list，但参数每次重新提取，杜绝错配。

对话框模式走 Agent Loop：

你说一句人话 → LLM 判断要调什么工具 → 执行 → 结果回传 LLM → LLM 组织自然语言回复

LLM 可以连续调多个工具（例如：查电量 → 顺手截屏），过程中 UI 实时显示 🔧 正在xxx。 写/执行类操作（截屏、清空剪贴板、关进程）会弹窗二次确认，防止误操作。

用数据说话

python3 eval/run_eval.py        # 48 条真实口语指令评测

L0 规则层实测（macOS）：

指标 结果
🎯 意图分类准确率 100% (48/48)
🎯 参数提取准确率 100% (41/41)
⚡ 平均路由延迟 0.007 ms
💰 每次调用成本 ¥0 · 0 token
🪶 进程常驻内存 14.2 MB
📦 第三方依赖 0（rich/PyYAML 可选）

哲学：简单固定任务该 100% 做对，而不是"90% 概率做对"。 L0 规则层用零成本吃掉高频固定任务，只把复杂长尾交给模型—— 这才是过河小兵的用兵之道。

已知问题 & 兜底

  • 对话框可能白屏（macOS 自带 tkinter 版本较老时会出现窗口不重绘） → 直接用终端 Agent 兜底：./gacli chat --cli，体验一致、启动更快。
  • 启动稍慢（Python 冷启动 + tk 初始化约 500ms） → 单命令模式没有这个问题；GUI 模式建议常驻或用全局快捷键唤起。
  • 日历首次调用慢 + 需要授权：macOS Tahoe 起 Calendar 走 TCC 保护，首次调 calendar.list 会弹权限窗（点"好"即可）；受 EventKit IPC 限制，冷启动约 12 秒（并发查多日历取 max），60 秒内再问会走缓存 <1ms。批权限拒绝或 Calendar.app 里没日历时自动降级为示例数据，Agent 仍可用。

全局快捷键（macOS，可选）

用 skhd 绑定，~/.skhdrc 加一行：

alt - space : /usr/bin/open -a Terminal /Users/你/Desktop/SW3/gacli/ui/launcher.sh

配套启动脚本见 ui/launcher.sh。

已验证

  • ✅ 20 个工具端到端跑通（macOS）
  • ✅ 意图分类 100% / 参数提取 100%（48 条评测集）
  • ✅ L0 规则命中 ~0.007ms、L1 缓存命中 ~0ms
  • ✅ 「明天/后天」参数正确区分，缓存不错配
  • ✅ Agent Loop 接入 DeepSeek，自主选工具/多轮调用
  • ✅ 缺 rich / 缺网络 / 缺 API Key / 缺权限 均优雅降级
  • ✅ 日历工具在 macOS Tahoe 上读到真实事件（AppleScript L1 · 并发 + 缓存 + 四级降级）
  • ✅ gacli update 一键升级；git stash 保护本地改动，.env 永不被覆盖

写在最后

小兵不是没本事，是懂得每一步都稳。 不追求一个模型解决所有事，而是让每个工具都值得信任、每次路由都可复现—— 这样，当你说"打开飞书"，它就真的会打开飞书，不会去写诗。