# metacode-cli

**Repository Path**: wii95/metacode-cli

## Basic Information

- **Project Name**: metacode-cli
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-23
- **Last Updated**: 2026-08-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MetaCode CLI

[![Java](https://img.shields.io/badge/Java-17+-orange.svg)](https://openjdk.org/)

MetaCode 是基于 [AgentScope Harness](https://github.com/agentscope-ai/agentscope) 的 Java 编码智能体 CLI，产品体验与配置心智对齐 **Claude Code**。在终端用自然语言描述任务，智能体即可读写、修改项目代码；支持 Anthropic / OpenAI 双模型通道，斜杠命令、MCP、技能扩展、计划模式与长期记忆。

## 打包与运行

仓库根目录（需 JDK 17+、Maven 3.9+）：

```powershell
.\package    # 一键打包并更新本机
.\metacode   # 开发态启动 CLI
```

发布包（含便携 JRE、无需预装 Java）：

```powershell
.\package -NoInstall -WithJre
```

![MetaCode CLI 启动界面](assets/metacode-screenshot.png)

## 安装使用

配置凭证：Claude Code `~/.claude`、Codex `~/.codex`（[CC Switch](https://ccswitch.io/) 等工具写入路径），或进程环境变量 `ANTHROPIC_*` / `OPENAI_*`。

安装后在新终端启动（三者等价）：

```text
matecode
meta
mc
```

| 命令 | 说明 |
|------|------|
| `matecode` | 正式命令 |
| `meta` / `mc` | 短别名 |

### Windows

```powershell
# 构建含 JRE 的发布目录 + zip
powershell -ExecutionPolicy Bypass -File scripts\package-release.ps1 -WithJre
# 或：.\package -NoInstall -WithJre

# 本机试装
powershell -ExecutionPolicy Bypass -File scripts\install.ps1 -LocalDist dist\matecode-0.1.0 -Force

# 在线安装（将 dist 托管到 BaseUrl 后；zip 内需含 jre\）
powershell -ExecutionPolicy Bypass -File scripts\install.ps1 -BaseUrl https://example.com/matecode/0.1.0/ -Force
```

一键远程安装（需同时托管 `install.ps1` 与发布包）：

```powershell
irm https://example.com/matecode/install.ps1 | iex
```

### macOS / Linux

```bash
./scripts/install.sh --local-dist dist/matecode-0.1.0
matecode   # 或 meta / mc
```

安装位置：Windows `%LOCALAPPDATA%\matecode`；Unix `~/.matecode`。

主分发渠道为 **install 脚本 + 含 JRE 发布包**（非 npm）。

## 配置

### MetaCode 本地配置（`~/.metacode/config.toml`）

**仅产品/runtime 项**（上下文窗口、压缩阈值等）；**不**用于 Provider 凭证。Anthropic / OpenAI 凭证与模型列表只读 `~/.claude` / `~/.codex`（CC Switch 切换后，在 MetaCode 执行 `/model openai` 或 `/model anthropic`，或打开 `/model` 菜单触发热同步）。

| 来源 | 路径 |
|------|------|
| 用户级 | `~/.metacode/config.toml` |
| 项目级 | `<workdir>/.metacode/config.toml`（覆盖用户级同名键） |

示例：

```toml
[context]
window_tokens = 200000

[compaction]
auto_threshold = 0.95
```

上下文窗口解析：当前 provider 的 `context_window` → `[context].window_tokens`（默认 **200000**）。占用达 `auto_threshold` 时自动压缩；亦可手动 `/compact`。

启动模型优先级：**CLI `--model` / `METACODE_MODEL`** → **Anthropic 列表第一项** → OpenAI 列表第一项（不持久化上次 `/model` 选择）。

### Anthropic / Claude Code（默认）

| 来源 | 路径 |
|------|------|
| 用户级 | `~/.claude/settings.json` |
| 项目级 | `<workdir>/.claude/settings.json` |
| 环境变量 | `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_BASE_URL`、`ANTHROPIC_MODEL` 等 |

### OpenAI / Codex

| 来源 | 路径 |
|------|------|
| 用户级 | `~/.codex/config.toml` + `auth.json` |
| 项目级 | `<workdir>/.codex/config.toml` |
| 环境变量 | `OPENAI_API_KEY`、`OPENAI_BASE_URL`、`OPENAI_MODEL` |

经 `/model openai` 或 `--model openai:gpt-4o` 切换。无配置时回退 `openai:gpt-4o`。

### 多 Provider 一览

| 厂商 | 凭证来源 | `/model` 示例 |
|------|----------|----------------|
| Anthropic（默认） | Claude Code `~/.claude` / `ANTHROPIC_*` | `anthropic:claude-sonnet-4-5` |
| OpenAI | Codex `~/.codex` / `OPENAI_*` | `openai:gpt-4o` |

文件系统模式：`METACODE_FS_MODE=UNRESTRICTED|ROOTED|SANDBOXED|DOCKER`（默认 **UNRESTRICTED**）。

### `.metacode` 目录

| 根 | 内容 |
|----|------|
| `~/.metacode/` | 全局 `skills/`、`mcp/servers.json`、`config.toml`、`logs/` |
| `<project>/.metacode/` | `sessions/`、`state/`（`-c` 续聊）、`workspace/`（含长期记忆） |

## 使用

常用参数：

| 参数 | 说明 |
|------|------|
| `--workdir <path>` | 项目根（默认当前目录） |
| `-c` / `--continue` | 续聊上一会话 |
| `-m` / `--model <id>` | 覆盖模型 |
| `--tui stdin\|jline\|tamboui` | 交互壳（终端默认 tamboui） |

### 响应速度（首条慢）

MetaCode 默认 **Lite Agent 先答、MCP 后台加载**：首条不再同步等待全部 MCP（stdio/npx 冷启动常拖慢 15s+）。TUI 顶栏 / footer 会显示 `Ready · model · MCP n/N`。

| 现象 | 处理 |
|------|------|
| 首条仍慢 | 看顶栏是否已 `Ready`；`/mcp doctor` 查看各 server 耗时 |
| npx MCP（如 kibana）超时 | `/mcp stop kibana` 或 `METACODE_MCP_SERVER_TIMEOUT_SEC=8` |
| 失败 server 反复拖慢 | 自动写入 `.metacode/mcp/disabled`（`METACODE_MCP_DISABLE_ON_FAIL=0` 可关） |
| 等 Lite 就绪再首问 | `METACODE_WAIT_PREWARM=1` |
| 恢复完整系统提示 | `METACODE_FULL_PROMPT=1` |
| 分段计时日志 | `METACODE_TIMING=1`（默认开）→ `~/.metacode/logs/metacode.log` |
| 对照 Claude Code | `powershell -File scripts\mc-vs-claude-benchmark.ps1 -Quick` |


斜杠命令（输入 `/` 展开菜单）：

- **Tool**：`/help` `/sessions` `/compact` `/model` `/skills` `/plan` `/agent` `/mcp` `/exit`
- **Skill**：已安装技能；`/skill <name>` 显式调用
- **Mcp**：已配置的 MCP server

`/mcp` 支持 `list|start|stop|reload [serverName]`。回合中按 **Esc** 打断。`/plan` 进入规划模式；选「开始执行」切回 Agent 模式。

可选环境变量：`TAVILY_API_KEY`、`METACODE_FS_MODE`、`METACODE_TUI`、`METACODE_SPINNER`、`METACODE_COLOR`、`NO_COLOR`。

终端默认 ANSI 真彩色；`NO_COLOR=1` 或 `METACODE_COLOR=0` 可关闭。品牌图标见 `assets/metacode-icon.png`。

## 架构

MetaCode 采用多模块 Maven 工程，依赖只允许向下：`spi` ← `toolkit-ext` ← `runtime` ← `tui` ← `cli`。

```mermaid
flowchart LR
  User[用户输入] --> Repl[TambouiChatRepl]
  Repl --> Runtime[AgentRuntime]
  Runtime --> Harness[HarnessAgent]
  Harness --> Events[AgentScope Events]
  Events --> Mapper[AgentEventMapper]
  Mapper --> UiEvent[UiEvent]
  UiEvent --> Repl
  Repl --> Terminal[终端渲染]
```

| 模块 | 职责 |
|------|------|
| `metacode-common-core` | 品牌色、终端、斜杠目录 |
| `metacode-common-tui` | 横幅、主题、对话渲染 |
| `metacode-spi` | 配置模型、产品事件 |
| `metacode-toolkit-ext` | 扩展工具（web、ask_user 等） |
| `metacode-runtime` | HarnessAgent 装配、会话、MCP |
| `metacode-tui` | REPL（TamboUI / JLine / stdin） |
| `metacode-cli` | 入口、shade 打包 |

## 开发

产物：`metacode/metacode-cli/target/metacode.jar`；发布目录 `dist/matecode-<ver>/`。

手动构建：

```powershell
mvn -q -pl metacode/metacode-cli -am package -DskipTests
powershell -File scripts/package-release.ps1 -WithJre
```

### 目录结构

```
metacode-common/          # 共用能力
metacode/                 # 产品模块（spi / runtime / tui / cli）
experiments/              # 非产品实验（如 ts-ink-migration 评估与 Ink spike）
bin/                      # 本地开发脚本
scripts/                  # install / package-release / 冒烟脚本
assets/                   # 品牌图标
package.cmd / metacode.cmd  # 根目录快捷入口（转发至 bin/）
```

### 质量门禁

仓库不引入 JUnit；回归靠冒烟脚本：

| 脚本 | 用途 |
|------|------|
| `scripts/acceptance-smoke.ps1` | 斜杠 / 横幅 / 模型菜单 |
| `scripts/e2e-full.ps1` | MCP + sessions |
| `scripts/ux-smoke-stdin.ps1` | stdin UX（需可用模型） |
| `scripts/coverage-gaps.ps1` | 覆盖空洞检查 |
| `scripts/tamboui-cc-parity.ps1` | TamboUI 结构冒烟 |
| `scripts/mc-vs-claude-benchmark.ps1` | MetaCode vs Claude 10 题对照（`-Quick` 仅冷启动） |
| `scripts/timing-smoke.ps1` | 首条响应 / TTFT 冒烟 |
| `scripts/ux-cursor-checklist.ps1` | TamboUI / HITL 手工清单 |

## 安全

默认文件系统 **UNRESTRICTED**（可访问项目外路径）；`execute` 需确认。详见 [SECURITY.md](SECURITY.md)。

## 贡献

欢迎提交 Issue 与 Pull Request。请先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。

## 友链

[Linux.do](https://linux.do) 社区 — 本项目获社区认可与支持。