Metadata-Version: 2.5
Name: mens
Version: 0.1.8
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: ddgs>=9.0
Requires-Dist: flatlatex>=0.15
Requires-Dist: flaxkv2>=0.2.5
Requires-Dist: flexllm>=0.16.1
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'
Requires-Dist: ptyprocess>=0.7; 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'
Requires-Dist: watchfiles>=0.21; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: serve
Requires-Dist: aiohttp>=3.8.0; extra == 'serve'
Requires-Dist: ptyprocess>=0.7; extra == 'serve'
Description-Content-Type: text/markdown

# 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/`](lab/)（不随发布，仅服务实验）。

## Install

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

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

### 本地开发

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

```bash
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

```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)。
