Metadata-Version: 2.4
Name: mens
Version: 0.1.4
Summary: Agent framework with built-in tools, MCP integration, and CLI
Project-URL: Homepage, https://github.com/KenyonY/mens
Project-URL: Repository, https://github.com/KenyonY/mens
Project-URL: Issues, https://github.com/KenyonY/mens/issues
Author-email: kunyuan <beidongjiedeguang@gmail.com>
License: Apache-2.0
License-File: LICENSE
Keywords: agent,cli,llm,mcp,tool-use
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: flatlatex>=0.15
Requires-Dist: flaxkv2>=0.2.5
Requires-Dist: flexllm>=0.9.0
Requires-Dist: httpx>=0.24
Requires-Dist: pillow>=10.3
Requires-Dist: psutil>=5.9.0
Requires-Dist: pylatexenc>=2.10
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=12.0.0
Requires-Dist: textual-image>=0.13.2; python_version >= '3.12'
Requires-Dist: textual>=8.2.8
Requires-Dist: trafilatura>=1.9
Requires-Dist: typer>=0.9.0
Provides-Extra: all
Requires-Dist: aiohttp>=3.8.0; extra == 'all'
Requires-Dist: mcp>=1.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.20.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: serve
Requires-Dist: aiohttp>=3.8.0; extra == 'serve'
Description-Content-Type: text/markdown

# mens

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

## Install

```bash
pip install mens[all]
```

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

### 本地开发

**日常开发用 conda `py12`**，它同时 editable 装了 mens 和 flexllm——改 flexllm 的代码
立刻在 mens 里生效，两个项目能联调（mens 的语音、多模态都依赖 flexllm 的新能力）。

```bash
conda activate py12
pip install -e ".[all,dev]"    # 只做一次
pytest -q                      # 500 passed
```

**`.venv`（uv）只用于发版前验证**，别拿它做日常开发：

```bash
uv sync && uv run pytest -q
```

两者测的不是同一件事：py12 里依赖是本地 editable 的，验证"我改的代码对不对"；`.venv`
按 `uv.lock` 装 PyPI 版本，验证"用户 `pip install mens` 拿到的组合能不能跑"——
`flexllm>=0.9.0` 这类**下界是真是假，只有后者测得出来**。CI（`release.yml`）跑的也是 uv。

代价是两套环境会漂移，而且症状是功能静默降级、不是报错：flexllm 本地加了新功能而
`.venv` 里还是 PyPI 旧版，两边版本号却一样。**动手前先确认自己在哪个环境**：

```bash
python -c "import flexllm, mens; print(flexllm.__file__); print(mens.__file__)"
# 指向 ~/github/... = py12（可联调）；指向 .venv/site-packages = 发布形态
```

## Quick Start

```python
from flexllm import LLMClient
from mens import AgentClient

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

## CLI

```bash
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 是过程，退出码表达成败。

```bash
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](docs/agent-cli.md)。

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

```bash
mens install-skill        # → 软链到 ~/.claude/skills/mens/（重开会话后生效）
```

软链而非复制：升级 mens 后 skill 自动跟着更新，不必记得重装。

### 交互式 TUI（mens chat）

全屏终端界面：流式输出、工具调用卡片、斜杠命令（`/help` `/clear` `/compact` `/model` `/resume` …）、
Esc 中断当前任务、↑/↓ 输入历史、Tab `@路径` 补全（界面显示短路径，发给模型时展开成绝对路径）。

- **权限**：默认 `default` 模式（只读放行，写操作弹窗审批），**Shift+Tab** 随时轮转
  `default → acceptEdits → bypass`（bypass = 不再询问）；"总是允许"会把规则持久化到
  `.mens/settings.json`（如 `bash(git commit:*)`）。详见 [docs/permissions.md](docs/permissions.md)
- **会话**：每轮自动持久化（flaxkv2），`-c/--resume` 或 TUI 内 `/resume` 恢复。详见 [docs/sessions.md](docs/sessions.md)

完整文档见 [docs/](docs/README.md)。
