@iamsamyiok/omniagent-cli

通用多 Agent 系统的终端版。Governor（调度者）分析任务、规划步骤、调度 6 类 Worker（Researcher / Coder / Analyst / Writer / Reviewer / Operator）协作执行，最后整合交付报告。零运行时依赖，Node.js >= 18.17。

安装

# 全局安装
npm install -g @iamsamyiok/omniagent-cli

# 或不安装直接运行
npx @iamsamyiok/omniagent-cli "你的任务"

配置

最简单的方式——终端内直接配置（保存到 ~/.omniagent/config.json，文件权限 600）：

# 交互式配置（依次询问端点、模型、Key，回车保留当前值）
omniagent config set

# 或一条命令完成，保存后自动测试连接
omniagent config set --base-url https://api.openai.com/v1 --model gpt-4o-mini --api-key your-key

# 查看当前生效配置及来源
omniagent config show

# 测试连通性
omniagent config test

也支持环境变量或工作区 .env 文件：

export USER_LLM_API_KEY=your-api-key
export USER_LLM_BASE_URL=https://api.openai.com/v1
export USER_LLM_MODEL=gpt-4o-mini

配置优先级：命令行参数 > 环境变量/.env > 全局配置文件（~/.omniagent/config.json）> 默认值。

使用

# 执行单个任务
omniagent "分析 data.csv 里的销售数据并把报告写入 report.md"

# 交互模式（支持连续对话：本轮问答自动带入下一轮上下文）
omniagent

# 指定工具工作区
omniagent -w /path/to/project "审查这个项目的 README 并提出改进建议"

交互模式支持连续对话：每轮问答历史自动注入后续轮次（直答与规划均感知上下文）；需要跨进程持久的长期事实，直接让 Agent「记住 XX」即可写入持久记忆。任务复杂度 ≤ 2 时 Governor 直接回答；更高复杂度自动拆解为最多 5 个步骤。执行采用目标清单跟踪（参考 Claude Code 的 todo 机制）：规划后生成清单，每步开始/结束实时刷新状态（[待办]→[进行中]→[完成]/[失败]），同一时刻只允许一项进行中，「完成」状态只能由系统核验后的真实结果标记；最终的目标达成情况作为客观记录交给整合器，存在失败项时报告禁止宣称全部完成。

交互模式本地命令（不消耗模型调用）：/help /clear（清对话历史）/history /memory /sessions。多步骤任务的步骤间上下文有 24000 字符预算，超限自动省略最早依赖并在提示中引导用 read_file 查看落盘文件。

最终报告有机械兜底：整合器若遗漏任何步骤（执行摘要不完整），系统按真实执行记录自动追加「整合器遗漏步骤」段落；整合器返回空内容时自动重试，仍为空则生成客观摘要。步骤产出核验采用声明式检查：Worker 在 final 中以 files 数组声明写入的文件（协议字段），配合任务指令中的目标路径与输出中的显式写入声称（如「已写入 X」）三源合并核验，叙述性引用的资料路径（如第三方系统的文件、URL）不参与核验。对「已更新/已修改」类声称，系统将声明与工具轨迹中的 edit_file/write_file 成功记录交叉对账，防止假声称完成修改。

edit_file 支持行内精确替换：old_text 为行内片段时仅替换该片段并保留行内其余内容；write_file 与 edit_file 对 .json 文件在写入前做 JSON 语法校验，语法损坏的写入被拒绝且原文件保持不变。

工具集（Worker 可调用）

| 工具 | 说明 | |------|------| | list_files / read_file / write_file | 工作区沙箱内文件操作，路径越界即拒绝 | | edit_file | 对已有文件做精确文本替换（借鉴 pi 的 edit 设计）：一次可提交多处不重叠替换，old_text 唯一性校验，自动兼容缩进/空白差异的模糊匹配，保留 BOM 与 CRLF；修改既有文件优先用它，避免整文件重写 | | run_js | 隔离子进程执行 Node.js 代码（默认 20s 超时） | | run_python | 隔离子进程执行 Python 代码 | | run_shell | 白名单只读命令（ls/cat/grep/git 等），高风险命令需用户确认 | | web_search | 免 key 多后端搜索：Keenable 全网搜索（官方 keyless 通道）→ Hacker News → Wikipedia（中英）→ DuckDuckGo，自动降级，结果标注来源后端 | | fetch_url / verify_url | 抓取网页正文与 URL 存活核验 | | memory | 持久记忆维护（借鉴 Hermes 记忆系统）：memory 目标存环境/项目/工具事实，user 目标存用户偏好；add/replace/remove 三动作 + 整库字符预算 + 漂移检测备份 | | session_search | 按需检索历史任务会话（目标、策略、结论），回答「上次做了什么」类问题 |

持久记忆（借鉴 Hermes Agent）

跨会话记忆分三层，零依赖实现：

1. 策划记忆：~/.omniagent/memory/MEMORY.md（Agent 笔记，2200 字符预算）+ USER.md（用户画像，1375 字符预算），条目以 § 分隔。每次任务开始时以冻结快照注入 Worker 系统提示。
2. 会话日志：每次任务自动追加到 ~/.omniagent/sessions.jsonl，session_search 工具按需全文检索（英文词 + 中文 bigram 评分 + 时间新近加权）。
3. 工程保障：整库预算超限拒绝写入并回报用量；外部改动漂移检测（自动备份 .bak.<时间戳> 并拒绝变更）；原子写（临时文件 + rename）；记忆只有 add/replace/remove 没有 read——记忆本身就在提示词里。

管理命令：

# 查看 Agent 笔记与用户画像
omniagent memory show

# 浏览最近 20 条历史会话
omniagent memory sessions

记忆写入意图（"记住 XX"）的任务会强制走 Worker 执行——直答路径没有工具，禁止口头声称"已记住"。

安全护栏

• 文件工具严格限制在工作区内，.. 越界直接拒绝
• 代码执行在隔离子进程，环境变量中的 KEY/SECRET/TOKEN/PASSWORD/CREDENTIAL 一律剥离，代码中出现 process.env、os.environ 等即拦截
• shell 仅白名单命令，管道/重定向/拼接拦截，rm -rf、mkfs、shutdown 等破坏性命令直接拒绝，git push 等高风险操作需交互确认
• 禁止读取环境变量中的密钥类请求

真实性护栏

• 引用的 URL 必须逐字来自工具返回，可用 verify_url 核验；无法核验的链接禁止出现
• 内容来自模型内部知识时必须标注「来源未验证（模型内部知识）」，禁止伪装成检索结果
• Worker 提交空结果会被系统拒绝并重试
• 声称「已保存文件」但文件系统核验不存在时，步骤判失败
• 最终报告的执行摘要基于真实工具调用记录生成，禁止虚构调用次数

环境要求

• Node.js >= 18.17（内置 fetch）
• run_python 需要系统安装 python3（可选）

License

MIT