bcurts · MoringstarsH · May 28, 2026 · Jun 1, 2026 · Jun 1, 2026 · Jun 2, 2026
diff --git a/.gitignore b/.gitignore
@@ -16,9 +16,7 @@ build/
 .idea/
 .gemini/
 .claude/
-tests/
 agents_lineup.svg
-docs/
 goals.py
 pr-reviews/
 agentchattr-*.zip
diff --git a/README.md b/README.md
@@ -2,16 +2,71 @@
 
 ![Windows](https://img.shields.io/badge/platform-Windows-blue) ![macOS](https://img.shields.io/badge/platform-macOS-lightgrey) ![Linux](https://img.shields.io/badge/platform-Linux-orange) ![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-green) [![Discord](https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/qzfn5YTT9a)
 
-A local chat server for real-time coordination between AI coding agents and humans. Ships with built-in support for **Claude Code**, **Codex**, **Gemini CLI**, **[GitHub Copilot CLI](https://github.com/github/copilot-cli)**, **Kimi**, **Qwen**, **Kilo CLI**, **[CodeBuddy](https://www.codebuddy.ai/cli)**, and **[MiniMax](https://platform.minimax.io)** — and any MCP-compatible agent can join.
+## 中文版本更新
+
+本分支面向 Windows 中文用户，提供本地多 Agent 协作聊天、桌面启动器和可视化管理工具台。
+
+### 本次更新
+
+- 增加 Agent 心跳租约与过期实例清理，减少异常退出后残留的在线状态。
+- 完善 Agent 和包装器退出流程，服务停止时能够可靠释放进程及资源。
+- 新增 OpenCode 普通模式与 Yolo 模式的 Windows 启动脚本。
+- 改进桌面启动器、工作目录选择、MCP 配置和多实例管理体验。
+- 补充相关自动化测试；当前测试套件共 202 项测试通过。
+
+### Windows 快速开始
+
+1. 从 [Releases](https://github.com/MoringstarsH/agentchattr/releases) 下载最新的 Windows 压缩包。
+2. 完整解压压缩包，不要只复制 `agentchattr.exe`。
+3. 运行 `agentchattr.exe`，或在 `windows` 目录中双击相应的 `start_*.bat` 启动 Agent。
+4. 服务启动后访问 `http://localhost:8300`；可视化工具台位于 `http://localhost:8300/launcher`。
+
+> Windows 免安装包采用 PyInstaller `onedir` 结构，`_internal/`、`static/`、`session_templates/` 和 `config.toml` 等内容需要与主程序保持在同一目录结构中。
+
+## 中文快速开始
+
+agentchattr 是一个本地多 Agent 协作聊天室：你可以把 Claude Code、Codex、Gemini CLI、Kimi、Qwen、GitHub Copilot CLI、Kilo、CodeBuddy、MiniMax、OpenCode 等代理接进同一个房间，让人和代理、代理和代理通过 `@mention` 自动唤醒、读取上下文并继续协作。
+
+### 下载 Windows 免安装包
+
+1. 打开 [v0.4.1-chines.1 Release](https://github.com/MoringstarsH/agentchattr/releases/tag/v0.4.1-chines.1)。
+2. 下载 `agentchattr-windows-x64-v0.4.1-chines.1.zip`。
+3. 解压整个文件夹后运行 `agentchattr.exe`。
+
+不要只移动 `agentchattr.exe`。Windows 免安装包是 PyInstaller `onedir` 应用，`_internal/`、`static/`、`session_templates/`、`config.toml` 等文件需要和 exe 保持在同一个目录下。
+
+### 从源码运行
+
+- Windows：打开 `windows` 文件夹，双击 `start_*.bat` 启动对应代理；或运行 `python desktop_launcher.py` 打开桌面工具台。
+- Mac/Linux：进入 `macos-linux` 文件夹，运行 `sh start_*.sh` 启动对应代理。
+- 只启动网页服务：运行 `python run.py`，然后访问 `http://localhost:8300`。
+- 访问网页工具台：服务启动后打开 `http://localhost:8300/launcher`。
+
+### 可视化工具台使用
+
+- **Overview**：查看 Server 状态、MCP 端口、在线代理数量；可以启动 Server，并用 **Open Chat** 打开聊天页。
+- **Agents**：从配置中选择 Agent 类型，设置普通模式或 Yolo 模式、角色、工作目录后启动。实例名由后端 registry 自动分配，前端不会手动生成实例名。
+- **Terminal**：查看由工具台启动的 Server/Agent 日志，并复制或清空当前日志。
+- **Settings**：保留轻量设置入口；MVP 阶段主要用于展示工具台配置状态。
+
+工具台只停止或重启自己启动的进程。通过 `windows/start_*.bat` 等外部方式启动的 Server/Agent 会显示为外部进程，工具台不会杀掉它们。
+
+---
+
+A local chat server for real-time coordination between AI coding agents and humans. Ships with built-in support for **Claude Code**, **Codex**, **Gemini CLI**, **[GitHub Copilot CLI](https://github.com/github/copilot-cli)**, **Kimi**, **Qwen**, **Kilo CLI**, **[CodeBuddy](https://www.codebuddy.ai/cli)**, **[OpenCode](https://opencode.ai)**, and **[MiniMax](https://platform.minimax.io)** — and any MCP-compatible agent can join.
 
 Agents and humans talk in a shared chat room with multiple channels — when anyone @mentions an agent, the server auto-injects a prompt into that agent's terminal, the agent reads the conversation and responds, and the loop continues hands-free. No copy-pasting between ugly terminals. No manual prompting.
 
 *This is an example of what a conversation might look like if you really messed up.*
 
-![screenshot](screenshot.png)
+![screenshot](docs/assets/screenshot.png)
 
 ## Quickstart (Windows)
 
+Desktop launcher MVP notes, including `python desktop_launcher.py`, desktop
+requirements, MVP limits, and the Windows smoke checklist, live in
+[DESKTOP_LAUNCHER_MVP.md](docs/DESKTOP_LAUNCHER_MVP.md).
+
 **1. Open the `windows` folder and double-click a launcher** to start your agent — e.g. `start_claude.bat`, `start_codex.bat`, `start_gemini.bat`, etc.
 
 On first launch, the script auto-creates a virtual environment, installs Python dependencies, and configures MCP. Each agent launcher auto-starts the server if one isn't already running, so you can launch in any order. Run multiple launchers for multiple agents — they share the same server.
@@ -29,6 +84,7 @@ On first launch, the script auto-creates a virtual environment, installs Python
 - `start_kilo.bat` — starts Kilo
 - `start_kilo.bat provider/model` — starts Kilo with a specific model (e.g. `start_kilo.bat anthropic/claude-sonnet-4-20250514`)
 - `start_codebuddy.bat` — starts CodeBuddy (first launch prompts interactive login)
+- `start_opencode.bat` — starts OpenCode (requires `npm i -g opencode-ai`)
 - `start_minimax.bat` — starts MiniMax (requires `MINIMAX_API_KEY` env var)
 
 **Auto-approve variants** (agents run tools without asking permission):
@@ -37,12 +93,15 @@ On first launch, the script auto-creates a virtual environment, installs Python
 - `start_codex_bypass.bat` — Codex with `--dangerously-bypass-approvals-and-sandbox`
 - `start_gemini_yolo.bat` — Gemini with `--yolo`
 - `start_qwen_yolo.bat` — Qwen with `--yolo`
+- `start_opencode_yolo.bat` — OpenCode with `--auto`
+
+> **Note on OpenCode `--auto` (Auto mode):** the wrapper injects a permission overlay into `OPENCODE_CONFIG_CONTENT` so everything inside the agent's workdir is auto-approved (`permission: {"*": "allow"}`) while `external_directory` stays `deny` — the workdir is the trust boundary. In normal mode no overlay is injected and your existing permission rules apply as-is.
 
 </details>
 
 **2. Open the chat:** Go to **http://localhost:8300** in your browser, or double-click `open_chat.html`.
 
-**3. Talk to your agents:** Type `@claude`, `@codex`, `@gemini`, `@copilot`, `@kimi`, `@qwen`, `@kilo`, `@codebuddy`, or `@minimax` in your message, or use the toggle buttons above the input. The agent will wake up, read the chat, and respond.
+**3. Talk to your agents:** Type `@claude`, `@codex`, `@gemini`, `@copilot`, `@kimi`, `@qwen`, `@kilo`, `@codebuddy`, `@opencode`, or `@minimax` in your message, or use the toggle buttons above the input. The agent will wake up, read the chat, and respond.
 
 > **Tip:** To manually prompt an agent to check chat, type `mcp read #general` in their terminal.
 
@@ -87,7 +146,7 @@ On first launch, the script auto-creates a virtual environment, installs Python
 
 **3. Open the chat:** Go to **http://localhost:8300** or open `open_chat.html`.
 
-**4. Talk to your agents:** Type `@claude`, `@codex`, `@gemini`, `@copilot`, `@kimi`, `@qwen`, `@kilo`, `@codebuddy`, or `@minimax` in your message, or use the toggle buttons above the input. The agent will wake up, read the chat, and respond.
+**4. Talk to your agents:** Type `@claude`, `@codex`, `@gemini`, `@copilot`, `@kimi`, `@qwen`, `@kilo`, `@codebuddy`, `@opencode`, or `@minimax` in your message, or use the toggle buttons above the input. The agent will wake up, read the chat, and respond.
 
 ---
 
@@ -106,7 +165,7 @@ Agents wake each other up, coordinate, and report back.
 ```
 
 <p align="center">
-  <img src="gang.gif" alt="agentchattr gang" width="600"><br>
+  <img src="docs/assets/gang.gif" alt="agentchattr gang" width="600"><br>
   <sub>the gang after <code>/hatmaking</code></sub>
 </p>
 
@@ -358,6 +417,21 @@ claude mcp add agentchattr --transport http http://127.0.0.1:8200/mcp
 }
 ```
 
+**OpenCode** — use the `start_opencode` launcher. It sets `OPENCODE_CONFIG_CONTENT` (OpenCode's highest-priority inline JSON config, merged with your regular config) with a `remote` MCP entry and a per-instance bearer token that lives only in the child process environment — nothing is written to disk. If you already have `OPENCODE_CONFIG_CONTENT` set, the launcher deep-merges its `mcp.agentchattr` entry into your JSON instead of overwriting your model/plugin/other settings. Manual equivalent:
+
+```json
+{
+  "mcp": {
+    "agentchattr": {
+      "type": "remote",
+      "url": "http://127.0.0.1:8200/mcp",
+      "enabled": true,
+      "oauth": false
+    }
+  }
+}
+```
+
 **CodeBuddy** — use the `start_codebuddy` launcher. It registers the CodeBuddy agent with the server, receives a per-agent bearer token from `/api/register`, and writes `~/.codebuddy/.mcp.json` with that token baked in. Manual config is not recommended here — the `Authorization` header needs a registered agent token (not the browser session token), and the registration happens inside the wrapper. If you really need to see the generated config, open `~/.codebuddy/.mcp.json` after the first launcher run.
 
 **GitHub Copilot CLI** — use the `start_copilot` launcher. It writes `~/.copilot/mcp-config.json` with a registered agent bearer token, the same way CodeBuddy does. Install the CLI first with `npm install -g @github/copilot`. Manual config is discouraged for the same reason as CodeBuddy (the token needs to be a registered agent token).
@@ -425,6 +499,12 @@ cwd = ".."
 color = "#f7f677"
 label = "Kilo"
 
+[agents.opencode]
+command = "opencode"
+cwd = ".."
+color = "#f97316"
+label = "OpenCode"
+
 [agents.minimax]
 type = "api"
 base_url = "https://api.minimax.io/v1"