mens

Agent framework with built-in tools, MCP integration, and CLI.

这个项目为什么存在

mens 为两件事而生，不是为了和通用 coding agent 竞争：

1. 一个完全自持、核心简单、方便做实验的 agent —— 所有构造自己设计，任何模块可替换、 任何实现可改动，内部无黑盒；核心保持小是为了让后续想法低成本长出来。
2. agent 安全围栏（flowlens）的实验场 —— 用某个提示词让 agent 输出/执行不安全内容时， 能方便监控到，并能方便干预到（通过 flowlens）。

心智模型：agent = 一个人，安全围栏 = 审核老师，两者在内容层双向沟通。flowlens 只审核/ 改写模型的输入与输出（改写危险指令、返回拒绝、或追加建议让 agent 在循环里看到），不对接任何 mens 专用接口——所以 mens 天然消费"老师改写后的内容"，拦截与沟通都无需为它开接口。

安全靶场与复现脚本在 lab/（不随发布，仅服务实验）。

Install

pip install mens

装完即是完整功能（含 chat-web 的 Terminal 页与 MCP 集成）。mens[all] / mens[serve] / mens[mcp] 仍可安装，但已是空别名——依赖都在核心里。

需要 Python 3.12+ 才能在 TUI 里显示图片（textual-image 的下界）；3.10/3.11 上 图片降级成文本占位，其余功能不受影响。

本地开发

只有一套环境：conda py12，mens 和 flexllm 都 editable 装在里面——改 flexllm 的代码 立刻在 mens 里生效，两个项目能联调（mens 的语音、多模态、网关信号都依赖 flexllm 的 新能力）。

conda activate py12
pip install -e ".[all,dev]"    # 只做一次
pytest -q
make env                       # mens / flexllm 都应指向 ~/github/…

依赖下界（flexllm>=x.y.z 这类约束是真是假）由 CI 在发版时验证：release.yml 里 uv 不带 lock 文件，直接按 pyproject.toml 的约束从 PyPI 解析安装再跑测试，装出来的 就是用户 pip install mens 拿到的组合。本地不再维护第二套 PyPI 环境——它不会自动跟随 pyproject.toml，陈旧之后带来的是"新代码 + 旧依赖"的假故障，而不是真信号。

Quick Start

from flexllm import LLMClient
from mens import AgentClient

llm = LLMClient(model="gpt-4o")
agent = AgentClient(llm)
result = await agent.run("读取 main.py 并分析")

CLI

mens run "查一下 cpu 使用率"          # 非交互执行（支持 stdin 管道）
mens run --tools code "读取 main.py"
mens chat                             # 交互式全屏 TUI
mens chat -c                          # 恢复最近会话
mens sessions list                    # 会话管理

程序 / AI Agent 调用

mens run 是给自动化用的入口：stdout 是结果、stderr 是过程，退出码表达成败。

mens info                                          # 自描述：工具/skill/退出码（JSON）
mens run "任务" --format json                       # 完整执行记录
mens run "任务" --format json || echo "失败: $?"    # 0 成功 / 2 参数错 / 5 未完成

跨调用多轮：--session <id> 新建会话、--resume <id> 续接（分开是为了让"撞上同名旧会话" 报错而不是静默接上陌生上下文）。

退出码与 JSON 字段的完整契约见 docs/agent-cli.md。

给 Claude Code 等 AI agent 用时，先装 skill 让它一次拿到心智模型，不必逐层 --help 摸索：

mens install-skill                 # → Claude Code（默认）
mens install-skill --target codex  # → Codex ~/.agents/skills/mens/

Claude Code 使用软链接，升级 mens 后 skill 自动更新；Codex 使用普通文件副本，升级后 重新执行 mens install-skill --target codex 即可刷新。

交互式 TUI（mens chat）

全屏终端界面：流式输出、工具调用卡片、斜杠命令（/help /clear /compact /model /resume …）、 运行中多次提交合并为下一轮输入（↑ 撤回全部合并内容，Esc 中断并立即发送）、↑/↓ 输入历史、 Tab @路径 补全（界面显示短路径，发给模型时展开成绝对路径）。

• 权限：默认 default 模式（只读放行，写操作弹窗审批），Shift+Tab 随时轮转 default → acceptEdits → bypass → plan（plan = 只读调查并输出计划）；"总是允许"会把规则持久化到 .mens/settings.json（如 bash(git commit:*)）。详见 docs/permissions.md
• 会话：每轮自动持久化（flaxkv2），-c/--resume 或 TUI 内 /resume 恢复。详见 docs/sessions.md
• 后台任务：Ctrl+B / /background 把当前 bash/task 原地转为 job；Ctrl+T / /detach 脱离整个 turn，job_* 管理进程与子代理，长驻宿主还支持 schedule。详见 docs/background-jobs.md
• 能力：/skill 搜索并切换当前会话的 Skill，正文按需加载；/mcp 查看、激活或重连 本进程已配置的 MCP server，激活后才向模型暴露其工具。Skill 随会话恢复，MCP 状态属于 当前进程；chat-web 的 Chat 页也有同一套能力面板。

完整文档见 docs/。