mindcode 0.2.0__tar.gz → 0.5.1__tar.gz

mindcode-0.5.1/PKG-INFO

@@ -0,0 +1,347 @@
+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 评测依赖本机对应的评测环境。

mindcode-0.5.1/README.md

@@ -0,0 +1,331 @@
+# 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 评测依赖本机对应的评测环境。