Metadata-Version: 2.4
Name: mindcode
Version: 0.5.1
Summary: codex-style interactive coding agent on top of mindagent
Author: mindcode
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mindagent>=0.5.3
Requires-Dist: agent-client-protocol>=0.12
Requires-Dist: rich>=13
Requires-Dist: openai>=1.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: typer>=0.12
Requires-Dist: prompt-toolkit>=3.0.30

# mindcode

一个能够自我进化的交互式 Coding Agent CLI，构建在 [mindagent](../) 之上。

## 核心能力

- workspace 内的代码读取、编辑和命令执行
- 交互式会话与一次性任务
- 可选 master/coder subagent 协作（`--subagents`）
- 支持注入 Skills 与 MCP server 工具（`build_runtime(..., skills=..., mcp_clients=...)`）
- 前台/后台任务记录和进程重启后的语义恢复
- 本地持久终端和 SSH 远程命令
- mini、SWE-bench 和 Terminal-Bench 评测入口
- 配套 VS Code 聊天插件（`vscode-extension/`）

## 特性

- **顶层 Agent 入口**：`mindcode [PROMPT] [选项]` 直接进入交互或 one-shot 模式；`chat` / `status` / `config` 等保留为公开子命令
- **可选 Subagent 模式**：`mindcode --subagents` 启用受限的 master/coder 协作；master 仅能委派，coder 才能访问 workspace
- 全屏 TUI：顶部 logo/会话信息、可滚动 Markdown 消息区、固定带边框多行输入框与状态栏
- 顶部信息栏显示本会话累计 token 消耗；provider 未返回 usage 时显示 `tokens —`
- Rich 富渲染：Markdown、彩色工具面板、file_edit diff 高亮和流式 LLM 输出
- TUI 内选择菜单：`/models`、`/permissions` 用方向键选择
- REPL 权限模式：`ask_user`（默认，写入和危险操作逐项询问）/ `full_accept`（接受权限上限内的操作风险）
- 会话持久化与恢复：基于 `LocalConversationStore`，存到 `~/.cache/mindcode/sessions/`
- OpenAI-compatible Provider 配置：首次启动时在 `~/.cache/mindcode/config.toml` 生成 rotor 示例
- 丰富 slash 命令：`/models` `/compact` `/permissions` `/status` `/resume` `/clear` `/help` `/exit`

## VS Code 插件

与 CLI 配套的 VS Code 聊天插件位于 [`vscode-extension/`](vscode-extension/)。
进入该目录并按其 README 构建后，可在 VS Code 中按 `F5` 启动 Extension Development Host。

```bash
cd vscode-extension
npm install        # 首次
npm run build:all  # 构建 webview 与插件
npm test           # vitest 单测
```

## 安装

要求 Python >= 3.10。在 mindcode 目录执行安装：

```bash
cd /path/to/mindagent/app/mindcode
pip install -e .

mindcode --version   # 0.5.0
```

`pip install -e .` 会根据项目依赖自动从 PyPI 安装 `mindagent>=0.5.3`。

## 文档

- `docs/command.md` — TUI slash 命令规范（状态合同：Implemented / Removed / Proposed / Blocked）
- `docs/usage.md` — 配置与日常命令示例
- `docs/design/architecture.md` — 架构设计
- `docs/devlog/` — 需求、roadmap 与各功能设计记录
- `docs/wiki/` — channels、remote、terminal sessions 等专题
- `docs/buglist.md` — 已知问题清单
- `../../docs/guides/policies-and-approval.md` — mindagent 侧策略与审批详解

## 命令结构

```
mindcode [PROMPT] [选项]              # 交互式 REPL；提供 PROMPT 时为 one-shot
mindcode chat -m "..." [选项]         # 一次性 prompt（参数与顶层入口基本一致）
mindcode status                       # 显示全局状态
mindcode task <subcmd>                # 任务：run / resume / list / status / tail / cancel
mindcode terminal <subcmd>            # 本地终端：open / new / list / send / tail / close
mindcode remote <subcmd>              # SSH 远程：add / list / show / remove / exec / tail
mindcode bench <subcmd>               # 评测：list / run / report / inspect / swe-eval / terminal-eval
mindcode config <subcmd>              # 配置管理
  mindcode config providers           # 列出所有 provider
  mindcode config models <provider>   # 列出 provider 的模型
  mindcode config models-set <p> ...  # 设置 model_list；第一个模型成为 default_model
  mindcode config api-key <p> <k>     # 设置 api_key
  mindcode config get <p> <field>     # 读取字段
  mindcode config set <p> <f> <v>     # 修改字段
  mindcode config list                # 显示完整配置（脱敏）
  mindcode config path                # 显示配置文件路径
mindcode --version
mindcode --help
```

## 配置

首次启动 `mindcode` 会自动在 `~/.cache/mindcode/config.toml` 创建一个
OpenAI-compatible rotor 示例。默认地址是本机 `http://127.0.0.1:8000/v1`，使用前应按实际网关修改。

模板节选：

```toml
default_provider = "rotor"

[providers.rotor]
protocol = "openai"
api_key = ""
base_url = "http://127.0.0.1:8000/v1"
default_model = "glm-5.2"
models = ["glm-5.2", "glm-5.1", "glm-4.7"]
```

### 方式 A：命令行（脚本化）

```bash
mindcode config api-key rotor sk-xxxxxxxxxxxx     # 设置密钥
mindcode config providers                         # 列出所有 provider
mindcode config models rotor                      # 列出 rotor 的模型
mindcode config set rotor default_model glm-5.1
mindcode config list                              # 完整配置（脱敏）
```

### 方式 B：REPL 内 slash 命令（交互式）

```
/models                                         # 方向键选择切换
/compact                                        # 生成摘要以压缩会话上下文
/permissions                                    # Ask User / Full Accept
/resume                                         # 列出并恢复本地保存的历史 session
/status                                         # 当前历史 session 状态与上下文使用
/help                                           # 完整命令列表
```

也可直接编辑 `~/.cache/mindcode/config.toml`。

## 使用

### 一次性模式

```bash
mindcode chat -m "读取 README.md 的前 5 行并总结"
# 或
mindcode "读取 README.md 的前 5 行并总结"
# 需要 master/coder 协作时（默认仍为单 agent）
mindcode --subagents "审查当前改动并运行相关测试"
```

### 交互模式

- `Enter` 发送；`Esc` + `Enter` 插入换行；多行输入框会自动增高。
- 输入 `/` 显示全部 slash 命令；继续输入会筛选。`↑` / `↓` 选择，`Enter` 先填入默认第一项，再按一次才执行。
- `/models` 与 `/permissions` 使用统一的灰阶选择框：`↑` / `↓` 切换，`Enter` 应用，`Esc` 取消；需要自由输入参数时仍在底部输入框内编辑和粘贴。
- `Page Up` / `Page Down` 或鼠标滚轮滚动消息；`End` 回到底部。
- 鼠标拖选消息会复制所选文本；`Ctrl` + `Y` 复制最新一条助手回复。
- 单行文字在输入框和用户消息卡片内上下居中；多行内容向下撑开。
- 用户消息会以与输入框相同的边框卡片进入对话，助手消息保留 Markdown 排版。
- Agent 运行时显示 `Working…`，输入框仍可提交后续消息并按顺序排队。
- 工具状态使用简洁标签：`Edit`、`Command`、`Read`、`Search`、`Context`、`Memory`、`Image`、`Time`、`Calculate`、`Delegate`；完成或失败时原地更新。

```bash
mindcode                                     # 默认进 shell
› 在 workspace 创建 hello.txt 写入 hi
   › file_edit (create) hello.txt [WRITE]
   ask_user 将在执行前询问；也可切换到 /permissions full_accept
   ┌─ diff: hello.txt ──────────────────────┐
   │ +hi                                     │
   └─────────────────────────────────────────┘
› /resume
› /exit
```

### 恢复会话

```bash
mindcode -r sess-1718530000
› 我刚才创建了什么文件？
```

### 顶层 `mindcode` 参数

```
mindcode [PROMPT] [-w WORKSPACE] [-a {ask_user,full_accept}]
                  [-p PROVIDER] [-m MODEL]
                  [-r SESSION_ID] [-s SESSION_ID] [--no-stream] [--subagents]
                  [--max-steps N] [--step-timeout SECONDS]
                  [--total-timeout SECONDS]
```

| 参数 | 说明 |
|---|---|
| `PROMPT` | 一次性 prompt；省略进入交互模式 |
| `-w, --workspace` | workspace 根目录（默认 `.`） |
| `-a, --approve-mode` | 权限模式：`ask_user`（默认，写入和危险操作逐项询问）或 `full_accept`（接受权限上限内的操作风险）；`ask`/`full`/`auto` 为兼容别名 |
| `-p, --provider` | 覆盖 config.toml 中的 default_provider |
| `-m, --model` | 覆盖 provider 中的 default_model |
| `-r, --resume` | 恢复指定 session_id |
| `-s, --session` | 指定新 session_id |
| `--no-stream` | 关闭流式输出 |
| `--subagents` | 启用 master/coder 委派模式。master 只允许 `agent_delegate`，coder 负责 workspace 工具调用；委派固定等待结果，不会启动后台任务。 |
| `--max-steps` | 单个 run 的最大 ReAct step 数（默认 50） |
| `--step-timeout` | 单步超时秒数（默认 300）；`0` 表示禁用 |
| `--total-timeout` | 绝对总时长上限；普通单代理交互默认禁用，one-shot/Subagent 默认 1800 秒；`0` 表示禁用 |

## 常用命令示例

### task（可后台运行、可恢复）

```bash
mindcode task run "重构 tests/test_config.py 并保持测试通过" -w /path/to/proj
mindcode task run "长任务..." --background          # 后台运行（-b）
mindcode task list                                  # 列出任务
mindcode task status <task_id>                      # 查看单个任务状态
mindcode task tail <task_id> -n 50                  # 查看最近事件；-f 持续追踪
mindcode task resume <task_id> -m "继续完成剩余步骤"  # 追加消息后语义恢复
mindcode task cancel <task_id>                      # 取消任务
```

### terminal（本地持久终端）

```bash
mindcode terminal new                    # 新建持久终端 session
mindcode terminal list                   # 列出 session
mindcode terminal send <id> "npm test"   # 向 session 写入命令
mindcode terminal tail <id> -n 40        # 查看输出；-f 持续追踪
mindcode terminal close <id>             # 关闭 session
mindcode terminal open -C /path/to/proj  # 在 Ghostty.app 中打开目录
```

### remote（SSH 远程）

```bash
mindcode remote add prod --host root@10.0.0.5 --workdir /srv/app
mindcode remote add pi --host pi@192.168.1.20 --workdir ~ --port 2222 --key ~/.ssh/id_ed25519
mindcode remote list                                     # 列出 remote
mindcode remote show prod                                # 查看配置（脱敏）
mindcode remote exec prod "systemctl status app"         # 远程执行命令
mindcode remote tail prod /var/log/app.log -n 80 --follow # 追踪远程日志
mindcode remote remove prod                              # 删除 remote
```

### bench（评测）

```bash
mindcode bench list                                  # 列出 suite 与 case 数
mindcode bench run --suite mini_gaia --limit 5       # 运行评测
mindcode bench report <run_id>                       # 汇总评分
mindcode bench inspect <run_id>                      # 查看逐 case 详情
mindcode bench swe-eval --predictions pred.jsonl     # SWE-bench 官方评测
mindcode bench terminal-eval --dataset ./tasks       # Terminal-Bench 评测
```

内置 suite：`mini_bfcl`、`mini_gaia`、`mini_terminal`（仓库 `benchmarks/` 自带 mini cases）、
`swe_bench`、`terminal_bench`。run 产物默认写入 `bench_runs/`。

## 测试

```bash
# 仓库根目录执行
PYTHONPATH=src:app/mindcode python -m pytest -q app/mindcode/tests

# 或在 app/mindcode 目录内
python -m pytest -q
```

## 模块结构

```
mindcode/
├── _version.py             # __version__, __logo__
├── config.py               # MindcodeConfig + ProviderConfig + load/save
├── config/                 # 内置 model.toml / settings.toml 模板
├── runtime.py              # build_runtime / build_master_worker_system + DiffingFileEditTool
├── approval.py             # 审批描述、shell 审批与外部文件只读授权回调
├── subagents.py            # MasterWorkerSystem 生命周期边界
├── policy.py               # ApprovalMode + AskUserPolicy/FullAcceptPolicy + ActionAuthorizer
├── render.py               # RichRenderer（event handler，TUI 工具面板渲染）
├── skills.py               # Skill / SkillRegistry / SkillLoader（front-matter 指令块）
├── mcp.py                  # MCPClient 协议 + MCPToolAdapter
├── tasking.py              # TaskStore / TaskEventRecorder（本地任务记录与事件持久化）
├── terminal_core.py        # TerminalManager + worker 协议（本地持久终端）
├── terminal/               # python -m mindcode.terminal 终端 worker 入口
├── remote.py               # RemoteStore + SSHCommandBuilder + RemoteExecutor
├── bench/                  # benchmark adapters、runner、scorers、report
└── cli/
    ├── __init__.py         # typer app + DefaultShellGroup（顶层默认入口）
    ├── _shared.py          # 共享 console + find_config_file
    ├── commands/
    │   ├── shell.py        # 顶层 `mindcode` 默认入口 handler
    │   ├── chat.py         # `mindcode chat -m "..."`
    │   ├── status.py       # `mindcode status`
    │   ├── config_cmd.py   # `mindcode config providers/models/api-key/models-set/...`
    │   ├── task.py         # `mindcode task run/resume/list/status/tail/cancel`
    │   ├── terminal.py     # `mindcode terminal open/new/list/send/tail/close`
    │   ├── remote.py       # `mindcode remote add/list/show/remove/exec/tail`
    │   └── bench.py        # `mindcode bench list/run/report/inspect/swe-eval/terminal-eval`
    └── shell/
        ├── repl.py         # Shell 类 + REPL 主循环
        ├── slash.py        # slash 命令注册与分发
        ├── completion.py   # `/` 前缀补全与筛选
        ├── tui.py          # 全屏布局、Markdown 消息流与状态栏
        ├── menu.py         # interactive_menu（ChoiceInput 包装）
        └── startup.py      # build_welcome_banner（Rich Panel）
```

## 设计要点

- `DiffingFileEditTool` 包装 mindagent 的 `FileEditTool`，在调用前后捕获文件内容，生成 unified diff 注入到 `Observation.result["mindcode_diff"]`。
- diff 渲染监听 `OBSERVATION_CREATED` 事件而非 `ACTION_FINISHED`，因为 result payload 只在前者。
- REPL 的 `/permissions` 通过重建当前 runtime 切换 `ask_user` 与 `full_accept`；前者对写入和危险操作逐项询问，后者接受权限上限内的操作风险，切换只影响当前会话。
- typer app 用自定义 `TyperGroup.parse_args`：无公开子命令时自动注入隐藏的内部 Shell handler，顶层 `mindcode` 因而复用完整参数解析；旧的 `mindcode shell` 语法会返回迁移提示。
- 全屏 TUI 用 Prompt Toolkit 管理固定输入框和消息视口；Rich 负责 Markdown 与工具输出渲染。
- ChoiceInput 失败时（旧版 prompt_toolkit）会自动 fallback 到序号输入。

## 文件访问与审批

- `SessionPolicy` 与 `RunConfig` 是 Core 检查的权限上限，自定义 Policy、审批回调与
  `full_accept` 都不能绕过。纯 Policy 判断范围，`MindCodeActionAuthorizer` 负责等待 UI。
- `ask_user` 与 `full_accept` 读取 workspace 外文件时，都需要确认精确路径的此次只读
  访问。授权绑定 session/run/action、完整参数及文件对象，默认 120 秒内有效且只消费
  一次；写入、编辑与外部命令工作目录不适用。
- SDK 可为 `build_runtime()` / `build_master_worker_system()` 注入
  `file_access_callback(context, request)`，返回绑定 `request_id` 的
  `ExternalFileReadDecision`。普通 `approval_callback` 或聊天中的“允许”不能签发它。
- 外部文件授权审计默认保存在内存，可通过 `file_access_audit_sink(event)` 接入宿主
  持久化；运行结束会清理未消费的授权，不自动新增磁盘审计文件。
- 普通问答使用 `USER_INPUT_REQUIRED` 与 `submit_user_input()`；旧 `approve_run()`
  因未绑定授权请求而被拒绝。
- `exec_command` 只限制 `cwd`，不会隔离子进程访问的文件。`sed`、`find`、`git diff`
  等命令保守按写风险审批，具体范围见
  [策略与权限](../../docs/guides/policies-and-approval.md)。

## 局限

- 不支持 `/undo`：`exec_command` 的副作用可能不可逆，回滚复杂。
- 会话恢复只续聊 user/assistant 历史，不恢复 TaskState / Evidence / pending continuation。
- `task resume` 是重新观察 workspace 后创建新 Run，不会重放未确认的旧 Action。
- 后台任务目前依赖本机 PID；不提供跨主机监督或精确进程身份恢复。
- `bench run` 第一版仅支持串行（concurrency=1）；`exec_command` 无沙箱，
  SWE-bench / Terminal-Bench 评测依赖本机对应的评测环境。
