codexmate 0.0.13 → 0.0.15

package/README.md

@@ -1,413 +1,214 @@
-# Codex Mate
+<div align="center">
 
-<div align="center">
+# Codex Mate
 
-<img src="res/logo.png" alt="Codex Mate logo" width="110">
+**Codex / Claude Code / OpenClaw 的本地配置与会话管理工具**
 
-[![Build](https://img.shields.io/github/actions/workflow/status/ymkiux/codexmate/release.yml?label=build)](https://github.com/ymkiux/codexmate/actions/workflows/release.yml)
+> 当前版本：`v0.0.15`
+
+[![Build](https://img.shields.io/github/actions/workflow/status/SakuraByteCore/codexmate/release.yml?label=build)](https://github.com/SakuraByteCore/codexmate/actions/workflows/release.yml)
 [![Version](https://img.shields.io/npm/v/codexmate?label=version&registry_uri=https%3A%2F%2Fregistry.npmjs.org)](https://www.npmjs.com/package/codexmate)
 [![Downloads](https://img.shields.io/npm/dt/codexmate?label=downloads)](https://www.npmjs.com/package/codexmate)
-[![Status](https://img.shields.io/badge/status-alpha-orange)](https://github.com/ymkiux/codexmate)
-[![Maintain](https://img.shields.io/github/commit-activity/m/ymkiux/codexmate?label=maintain%2Fmonth)](https://github.com/ymkiux/codexmate/commits)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%3E%3D14.0.0-green.svg)](https://nodejs.org)
 
-**A lightweight AI configuration assistant: quickly switch Codex providers/models and Claude Code configs, with a unified session browser**
+[快速开始](#快速开始) · [命令速查](#命令速查) · [Web 界面](#web-界面) · [MCP](#mcp) · [English](README.en.md)
 
 </div>
 
 ---
 
-<p align="center">English · <a href="README.zh-CN.md">中文版</a></p>
-
-![Codex Mate Web UI](res/screenshot.png)
-
-## Overview
+## 这是什么？
 
-One tool to switch Codex/Claude Code providers & models and manage/browse local sessions in one click.
+Codex Mate 提供一套本地优先的 CLI + Web UI，用于统一管理：
 
-## What You Get
+- Codex 的 provider / model 切换与配置写入
+- Claude Code 配置方案（写入 `~/.claude/settings.json`）
+- OpenClaw JSON5 配置与 Workspace `AGENTS.md`
+- Codex / Claude 本地会话浏览、筛选、导出、删除
+- `codexmate qwen` 快捷透传命令
 
-- One-command provider/model switching
-- Local config control with backups
-- Lightweight Web UI instead of heavy clients
-- Unified session browser (view/export/resume when available)
-- Session management: list/filter/export/delete local sessions; keyword search supports Codex and Claude
-- New in 0.0.10: Claude sessions are searchable by keywords (e.g., `claude code`, `claude-code`, numeric tokens)
+项目不依赖云端托管，配置写入你的本地文件，便于审计和回滚。
 
-## Feature Overview
+## 为什么选择 Codex Mate？
 
-| Module | Problem | Key Capabilities |
+| 维度 | Codex Mate | 手动维护配置 |
 | --- | --- | --- |
-| Codex Config | Switching providers/models is painful | Provider/model switching, model management, CLI + Web entry points, template-confirmed writes |
-| Claude Code Config | Multiple profiles and inconsistent write paths | Profile management, default write to `~/.claude/settings.json` |
-| OpenClaw Config | OpenClaw configs are scattered | JSON5 profiles, apply to `~/.openclaw/openclaw.json`, AGENTS workspace management |
-| Session Browser | Local sessions are hard to track | List/filter sessions, keyword search (Codex + Claude), export to Markdown, copy resume command (when available), delete and batch cleanup |
-| Utilities | Compression/extraction requires extra tools | 7-Zip preferred, JS fallback |
-
-## Why Codex Mate
-
-- Focused on three jobs: Codex provider/model switching + Claude Code config apply + OpenClaw config apply
-- Local-first: configs and API keys are written to local files, not the cloud
-- Lightweight: CLI + Web, no desktop app required
-- Reversible: auto-backup before first takeover
-
-## Use Cases
-
-- Frequent provider/model switching, want a one-command flow
-- Use both Codex and Claude Code, want a single entry point
-- Need to browse/export local Codex + Claude Code sessions and copy resume commands when available
-- Use OpenClaw with multiple profiles, want quick switching
-- Multi-project or multi-environment setups that need quick config changes
-- Want a visual UI without a heavy client
-
-## Scope and Boundaries
-
-- Only configuration management for Codex, Claude Code, and OpenClaw, not a full all-in-one tool suite
-- No built-in proxy/relay/billing dashboard/cloud sync (kept lightweight)
-- Web UI runs only when you start it (`codexmate run`)
-
-## 30-Second Start (No Install)
-
-```bash
-npx codexmate@latest status
-```
+| 多工具管理 | Codex + Claude Code + OpenClaw 统一入口 | 多文件、多目录分散修改 |
+| 使用方式 | CLI + 本地 Web UI | 纯手改 TOML / JSON / JSON5 |
+| 会话处理 | 支持浏览、导出、批量清理 | 需要手动定位和处理文件 |
+| 可回滚性 | 首次接管前自动备份 | 易误覆盖、回滚成本高 |
+| 自动化接入 | 提供 MCP stdio（默认只读） | 需自行封装脚本 |
+
+## 核心特性
+
+**配置管理**
+- provider / model 切换（`switch` / `use`）
+- Codex `config.toml` 模板确认后写入
+- Claude Code 多配置方案管理与一键应用
+- OpenClaw JSON5 配置方案管理
+
+**会话管理**
+- 同页查看 Codex 与 Claude 会话
+- 关键词搜索、来源筛选、cwd 路径筛选
+- 会话导出 Markdown
+- 会话与消息级删除（支持批量）
+
+**工程能力**
+- MCP stdio 能力（tools/resources/prompts）
+- 内建代理配置与状态控制（`proxy`）
+- 认证档案管理（`auth`）
+- `codexmate qwen` 兼容启动入口（默认透传 `--yolo`）
+- Zip 压缩/解压（优先系统工具，失败回退 JS 库）
+
+## 架构总览
+
+```mermaid
+flowchart LR
+    A[CLI: codexmate] --> B[本地配置文件]
+    A --> C[本地 Web UI]
+    C --> D[内建 HTTP API]
+    D --> B
+    D --> E[会话索引与导出]
+    A --> F[MCP stdio server]
+
+    subgraph Local Files
+      B1[~/.codex/config.toml]
+      B2[~/.claude/settings.json]
+      B3[~/.openclaw/openclaw.json]
+      B4[sessions/*.jsonl]
+    end
+
+    B --> B1
+    B --> B2
+    B --> B3
+    E --> B4
+```
+
+## 快速开始
+
+### npm 全局安装
 
-```bash
-npx codexmate@latest run
-```
-
-Then open `http://localhost:3737` in your browser.
-
-## Quick Start
-
-1. Install (global):
 ```bash
 npm install -g codexmate
-```
-
-Or run once without install:
-```bash
-npx codexmate@latest status
-```
-
-2. Run the interactive setup:
-```bash
 codexmate setup
-```
-
-3. Check status:
-```bash
 codexmate status
-```
-
-4. Start the Web UI:
-```bash
 codexmate run
 ```
 
-Then open `http://localhost:3737` in your browser.
-
-## Alternatives
-
-- cc-switch: https://github.com/farion1231/cc-switch
-
-## Install
-
-### Global (Recommended)
-
-```bash
-npm install -g codexmate
-```
-
-Package name on npm: `codexmate`.
-
-Want to update to the latest effects features each time? Install from GitHub (re-run to update):
-
-```bash
-npm install -g ymkiux/codexmate
-```
-
-### Run with npx (No Install)
-
-```bash
-npx codexmate@latest status
-```
-
-```bash
-npx codexmate@latest run
-```
+默认监听 `127.0.0.1:3737`，并尝试自动打开浏览器。
 
-### From Source
+### 从源码运行
 
 ```bash
-git clone https://github.com/ymkiux/codexmate.git
+git clone https://github.com/SakuraByteCore/codexmate.git
 cd codexmate
 npm install
 npm link
-```
-
-### Requirements
-
-- Node.js >= 14
-- Windows / macOS / Linux
-
-## CLI Cheat Sheet
-
-| Command | Description |
-| --- | --- |
-| `codexmate` | Show help and available commands |
-| `codexmate setup` | Interactive configuration wizard |
-| `codexmate status` | Show current status |
-| `codexmate list` | List all providers |
-| `codexmate switch <provider>` | Switch provider |
-| `codexmate use <model>` | Switch model |
-| `codexmate add <name> <URL> [API key]` | Add a provider |
-| `codexmate delete <provider>` | Delete a provider |
-| `codexmate claude <BaseURL> <API key> [model]` | Write Claude Code config to `~/.claude/settings.json` |
-| `codexmate models` | List all models |
-| `codexmate add-model <model>` | Add a model |
-| `codexmate delete-model <model>` | Delete a model |
-| `codexmate run` | Start the Web UI |
-| `codexmate mcp [serve] [--transport stdio] [--allow-write\|--read-only]` | Start MCP server over stdio (default read-only) |
-| `codexmate export-session --source <codex|claude> (--session-id <ID>|--file <PATH>) [--output <PATH>] [--max-messages <N|all|Infinity>]` | Export a session to Markdown |
-
-## MCP (stdio)
-
-- Transport: `stdio` only
-- Default mode: read-only tool set
-- Write tools: enable by `--allow-write` or `CODEXMATE_MCP_ALLOW_WRITE=1`
-- Sensitive fields in `codexmate.claude.settings.get` are returned as masked values
-
-```bash
-# Read-only (recommended for external agents)
-codexmate mcp serve --read-only
-
-# Enable write tools explicitly
-codexmate mcp serve --allow-write
-```
-
-Provided MCP domains:
-
-- `tools`: status/provider/model/session/auth/proxy and config operations
-- `resources`: status/providers/sessions snapshots
-- `prompts`: built-in diagnose/switch/export templates
-
-## Web UI
-
-Start the Web UI (auto opens browser):
-
-```bash
-codexmate run
-```
-
-### Codex Config Mode
-
-- View current provider and model status
-- Quickly switch provider and model
-- Manage available model list
-- Edit `~/.codex/AGENTS.md` instruction file (same level as `config.toml`)
-- Add/delete custom providers
-- Supports Codex config management on Linux/Windows
-
-### Claude Code Config Mode (Windows / macOS / Linux)
-
-- Manage multiple Claude Code profiles
-- Configure API key, Base URL, and model
-- Default write to `env` in `~/.claude/settings.json`: `env.ANTHROPIC_API_KEY` / `env.ANTHROPIC_BASE_URL` / `env.ANTHROPIC_MODEL`
-- One-liner apply via CLI:
-
-```bash
-codexmate claude https://api.example.com/v1 sk-ant-xxx claude-3-7-sonnet
-```
-
-- In the Web UI, each Claude configuration card now has a "Share Import Command" button that copies a one-click import command (for example: `codexmate claude <BaseURL> <API Key> <Model>`).
-
-### OpenClaw Config Mode
-
-- Manage multiple OpenClaw JSON5 profiles
-- Apply to `~/.openclaw/openclaw.json`
-- Manage `AGENTS.md` under the OpenClaw Workspace (default: `~/.openclaw/workspace/AGENTS.md`)
-
-### Session Browser
-
-- View local Codex and Claude Code sessions in one page
-- Filter by source (Codex / Claude / All)
-- Filter by session path (cwd), auto refresh on selection
-- Export selected sessions to Markdown
-- Copy resume command when available
-- Delete single sessions (local jsonl records)
-- Batch delete multiple sessions with partial failure summary
-- Delete individual records or multi-select within session details (writes back to original jsonl)
-
-### Codex Template Confirmation Mode
-
-- Codex config changes in Web UI go to a `config.toml` template editor first
-- Only writes to `config.toml` after you click "Confirm Apply Template"
-- Prevents direct one-click overwrites from the UI
-
-## Configuration Files
-
-Config directory: `~/.codex/`
-
-- `config.toml` - Codex main config
-- `auth.json` - API auth info
-- `models.json` - Available model list
-- `provider-current-models.json` - Per-provider current model config
-- `codexmate-init.json` - First-run marker
-- `config.toml.codexmate-backup-*.bak` - Backup created on first takeover
-
-Claude Code config files:
-
-- `~/.claude/settings.json` - Runtime config (default write target)
-- `~/.claude/settings.json.codexmate-backup-*.bak` - Backup before first overwrite
-
-OpenClaw config files:
-
-- `~/.openclaw/openclaw.json` - OpenClaw config (JSON5)
-- `~/.openclaw/workspace/AGENTS.md` - OpenClaw workspace instructions
-
-## First Run Initialization
-
-When you run `codexmate` for the first time and an existing `~/.codex/config.toml` is detected that is not managed by Codex Mate:
-
-- The original file is backed up as `config.toml.codexmate-backup-<timestamp>.bak`
-- The original `config.toml` is preserved, and a first-run marker is written
-- Only when `CODEXMATE_FORCE_RESET_EXISTING_CONFIG=1` is set will the default config be rebuilt
-- Subsequent runs will not repeat this process
-
-## Examples
-
-### Add a Custom API Provider
-
-```bash
-codexmate add myapi https://api.example.com/v1 sk-your-api-key
-codexmate switch myapi
-```
-
-### Switch to a Different Model
-
-```bash
-codexmate use gpt-4-turbo
-```
-
-### Export a Session (CLI)
-
-```bash
-codexmate export-session --source codex --session-id 123456
-codexmate export-session --source claude --file "~/.claude/projects/demo/session.jsonl" --max-messages=all
-```
-
-By default, exports are capped at 1000 messages. Use `--max-messages=all` (or `Infinity`) to export everything.
-
-### Configure Claude Code (Cross-Platform)
-
-1. Start the Web UI: `codexmate run`
-2. Switch to "Claude Code Config" mode in the browser
-3. Add a profile (example Zhipu GLM): Name=ZhipuGLM, API Key=your API key, Base URL=`https://open.bigmodel.cn/api/anthropic`, Model=`glm-4.7`
-4. Click the card to apply, or use "Save & Apply to Claude Config" in the editor
-5. Default write to `~/.claude/settings.json`
-6. Restart Claude Code to apply
-
-### Start the Web UI
-
-```bash
 codexmate run
 ```
 
-By default it binds to `127.0.0.1`. To expose on LAN, use `--host` or `CODEXMATE_HOST`:
+### 测试 / CI（只启动服务）
 
 ```bash
-codexmate run --host 0.0.0.0
+codexmate run --no-browser
 ```
 
-Then open `http://localhost:3737` (or your chosen host). Note: binding to `0.0.0.0` is unsafe on untrusted networks.
-
-## FAQ
+> 约定：自动化测试仅验证服务与 API，不依赖打开页面。
 
-### Q: Which operating systems are supported?
+## 命令速查
 
-A: Codex features support Windows and Linux (CLI and Web). Claude Code config applies to Windows / macOS / Linux (writes to `~/.claude/settings.json`).
+| 命令 | 说明 |
+| --- | --- |
+| `codexmate status` | 查看当前配置状态 |
+| `codexmate setup` | 交互式初始化 |
+| `codexmate list` / `codexmate models` | 查看提供商 / 模型 |
+| `codexmate switch <provider>` / `codexmate use <model>` | 切换 provider / model |
+| `codexmate add <name> <URL> [API_KEY]` | 添加提供商 |
+| `codexmate delete <name>` | 删除提供商 |
+| `codexmate claude <BaseURL> <API_KEY> [model]` | 写入 Claude Code 配置 |
+| `codexmate auth <list\|import\|switch\|delete\|status>` | 认证档案管理 |
+| `codexmate proxy <status\|set\|apply\|enable\|start\|stop>` | 内建代理管理 |
+| `codexmate workflow <list\|get\|validate\|run\|runs>` | MCP 工作流管理 |
+| `codexmate qwen [args...]` | Qwen CLI 透传入口 |
+| `codexmate run [--host <HOST>] [--no-browser]` | 启动 Web UI |
+| `codexmate mcp serve [--read-only\|--allow-write]` | 启动 MCP stdio 服务 |
+| `codexmate export-session --source <codex\|claude> ...` | 导出会话为 Markdown |
+| `codexmate zip <path> [--max:0-9]` / `codexmate unzip <zip> [out]` | 压缩 / 解压 |
 
-### Q: Where are API keys stored?
+## Web 界面
 
-A: API keys are stored locally in `~/.codex/config.toml` and are not uploaded.
+### Codex 配置模式
+- provider / model 切换
+- 模型管理
+- `~/.codex/AGENTS.md` 编辑
+- `~/.codex/skills` 管理（筛选、批量删除、跨应用导入）
 
-### Q: Is the Web UI safe?
 
-A: The Web UI runs locally; all operations happen on your machine. API keys are masked in the UI.
+### Claude Code 配置模式
+- 多配置方案管理
+- 默认写入 `~/.claude/settings.json`
+- 支持复制分享导入命令
 
-### Q: How do Claude Code configs take effect?
+### OpenClaw 配置模式
+- JSON5 多方案管理
+- 应用到 `~/.openclaw/openclaw.json`
+- 管理 `~/.openclaw/workspace/AGENTS.md`
 
-A: After clicking "Apply to Claude Config", it writes to `~/.claude/settings.json`. Restart Claude Code to apply.
+### 会话模式
+- Codex + Claude 会话统一列表
+- 搜索、筛选、导出、删除、批量清理
 
-### Q: How to uninstall?
+## MCP
 
-A: Run `npm uninstall -g codexmate`.
+> 传输：`stdio`
 
-## Extras: Compression/Extraction
+- 传输：仅 `stdio`
+- 默认：只读工具集
+- 写入开启：`--allow-write` 或 `CODEXMATE_MCP_ALLOW_WRITE=1`
+- 包含域：`tools`、`resources`、`prompts`
 
-Prefer 7-Zip for multithreaded zip/unzip. Fallback to the built-in JS library when unavailable.
+示例：
 
 ```bash
-# Compress file or folder (default compression level 5)
-codexmate zip <path>
-
-# Set compression level (0-9, 0=store only, 9=max)
-codexmate zip <path> --max:9
-
-# Unzip a zip file (default to same-level folder)
-codexmate unzip <zip path>
-
-# Unzip to a specific output directory
-codexmate unzip <zip path> <output dir>
+codexmate mcp serve --read-only
+codexmate mcp serve --allow-write
 ```
 
-Examples:
+## 配置文件
 
-```bash
-# Compress a project folder
-codexmate zip ./my-project
-
-# Max compression
-codexmate zip ./my-project --max:9
+- `~/.codex/config.toml`
+- `~/.codex/auth.json`
+- `~/.codex/models.json`
+- `~/.codex/provider-current-models.json`
+- `~/.claude/settings.json`
+- `~/.openclaw/openclaw.json`
+- `~/.openclaw/workspace/AGENTS.md`
 
-# Store only (fast)
-codexmate zip ./large-folder --max:0
+## 环境变量
 
-# Unzip
-codexmate unzip ./my-project.zip
-
-# Unzip to a target location
-codexmate unzip ./backup.zip D:/restored
-```
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `CODEXMATE_PORT` | `3737` | Web 服务端口 |
+| `CODEXMATE_HOST` | `127.0.0.1` | Web 服务监听地址 |
+| `CODEXMATE_NO_BROWSER` | 未设置 | 设为 `1` 后不自动打开浏览器 |
+| `CODEXMATE_MCP_ALLOW_WRITE` | 未设置 | 设为 `1` 后默认允许 MCP 写工具 |
+| `CODEXMATE_FORCE_RESET_EXISTING_CONFIG` | `0` | 设为 `1` 时首次可强制重建托管配置 |
 
-Note: 7-Zip is optional. If missing, the built-in JS library is used. `--max` only applies to 7-Zip.
+## 技术栈
 
-## Tech Stack
+- Node.js
+- Vue.js 3（Web UI）
+- 原生 HTTP Server
+- `@iarna/toml`、`json5`
 
-- **Node.js** - Runtime
-- **@iarna/toml** - TOML parser
-- **Vue.js 3** - Web UI framework
-- **Native HTTP** - Built-in Web server
+## 参与贡献
 
-## Release (GitHub Actions)
+欢迎提交 Issue 和 Pull Request。
 
-Create a tag that matches `package.json` (for example `v0.0.9`). Then run the `release` workflow in GitHub Actions and input that tag. It will create a GitHub Release and attach the `npm pack` `.tgz` artifact.
+- 英文更新日志：`doc/CHANGELOG.md`
+- 中文更新日志：`doc/CHANGELOG.zh-CN.md`
 
 ## License
 
-Apache-2.0 © [ymkiux](https://github.com/ymkiux)
-
-## Contributing
-
-Issues and pull requests are welcome.
-
-## Changelog
-
-See [doc/CHANGELOG.md](doc/CHANGELOG.md) for the English version.
-See [doc/CHANGELOG.zh-CN.md](doc/CHANGELOG.zh-CN.md) for the Chinese version.
-
----
-
-Made with [ymkiux](https://github.com/ymkiux)
+Apache-2.0