npm package: @mmteam/magicchat
Description: MagicAI 软件开发工作区智能会话助手
Author: MM Team
Latest version: 0.1.36

# 简介
- 本项目是使用gemini pro 实现的快速智能体命令行工具
- 实现快速针对magic标准软件开发项目工程进行构建和处理

## 命令行子命令（mchat <command> [options]）
- 全局选项：`--no-sandbox`（跳过容器环境检测，默认要求在 docker 内运行；未检测到容器且未加此参数会退出）。
- `chat [message...]`：会话子命令（默认）。`message...` 为首条用户输入；缺省时从 stdin 读取，仍为空会报错退出。
  - `--session <name>`：指定会话目录（相对 `.magicai/chat-sessions/`，禁止绝对路径与 `..`）。未指定：存在 latest 则复用；携带 `--system` 时强制新建会话。
  - `--system <prompt>`：追加系统提示词，可直接写字符串或 `@路径`（默认从工作区根的 `public/agents/` 读取并补 `.agent.md`）。新会话时会把 YAML Front Matter（user/createTime/session）置于最前并追加 `globalAgent` 对应的 agent 作为独立 system 消息。
  - `--temp <number>`：覆盖配置的温度（0~2，超出范围会被截断），传入模型请求；未提供则使用配置的 `chat.temperature`，两者都缺省则使用模型默认。
- `init`：初始化当前目录为 workspace，生成/迁移 `.magicai/magicai.yaml`，补全 `user/globalAgent`，默认 provider=qwen（openai 兼容，baseUrl=https://dashscope.aliyuncs.com/compatible-mode/v1，model=qwen3-max）或沿用已有 provider；同时尝试 `git init` 并添加/更新 `public` 子模块（默认仓库 ssh://git@git.magicmind.cn:22222/ai/public.git），并在初始化后更新当前工作区的所有 git 子模块、检出各自默认分支。
- `test-proxy`：输出检测到的代理环境变量并 HEAD 访问 https://www.google.com （10s 超时）。
- `project`：项目管理（projects/<name>/.repo 裸仓库 + 并列 worktree）
  - `--add <repo>`：克隆远程仓库为裸仓库 `projects/<name>/.repo`，自动检测默认分支（远程空仓库则使用 main），将默认分支以 worktree 检出到 `projects/<name>/<branch>/`，并自动在根仓库注册为子模块。
  - `--new <name>`：在 `projects/<name>/` 下创建裸仓库 `.repo`，初始化默认分支 `main` 的 worktree（未生成提交，供后续关联远程或直接开发）。
  - `--remove <name>`：移除指定项目及其 worktree，需所有 worktree 处于干净状态。
  - `--commit`：遍历 `projects/` 下各项目 worktree，自动 `git add` + `git commit`。提交信息由模型生成，500 字内可多行，包含功能/行为摘要、主要修改文件与内容要点及潜在影响；无改动则输出跳过。
  - `--branch <project/branch>`：为指定项目创建/检出分支 worktree（依赖裸仓库 .repo），若已存在对应工作区则提示。
- `llm-only`：启动本地 LLM 组合（使用 `docker/llm-only.cuda.compose.yaml`），默认项目名 `mem-llm`，挂载当前工作区 `.magicai/` 与 `models/`，并按 `.magicai/local-llm.yaml` 配置模型文件和基础端口（默认 6660，embedding+1，reranker+2）。
- `db-only`：启动本地数据库组合（使用 `docker/db-only.compose.yaml`），数据存储在工作区 `.magicai/db/{数据库类型}/` 下，默认暴露 qdrant 6333/6334、neo4j 7474/7687 端口。
- 启动会在任何命令前应用系统代理环境（HTTPS_PROXY/http_proxy 等）。

## 使用示例
- 初始化：`mchat init`
- 普通对话：`mchat chat "帮我梳理 README 要点"` 或 `echo "ls" | mchat chat`
- 指定系统提示与新会话：`mchat chat --system "@code-review"`（默认从工作区根 `public/code-review.agent.md` 读取并写入 Front Matter 和 globalAgent，不回退 `agents/`）
- 启动本地 LLM：`mchat llm-only`（仅读取 `.magicai/local-llm.yaml`，不支持命令行参数覆盖）
- 启动本地数据库：`mchat db-only`
- 指定会话目录：`mchat chat --session feature/bugfix-123 "继续上一条对话"`
- 临时调整温度：`mchat chat --temp 1.2 "写一段更有创意的文案"`
- 代理测试：`mchat test-proxy`
- 添加项目：`mchat project --add git@server/repo.git`
- 新建项目：`mchat project --new demo`
- 同步子模块：`mchat init`
- 创建/检出分支：`mchat project --branch demo/feature-x`
- 移除项目：`mchat project --remove demo`
- 自动提交项目变更：`mchat project --commit`

## 配置文件 .magicai/magicai.yaml
- 位置：`<workspace>/.magicai/magicai.yaml`，运行时缺失会阻塞并提示先 `mchat --init`。旧格式 `gemini.apikey` 会自动迁移到 `providers.gemini.apiKey` 并写回。
- 顶层字段：
  - `user`: 当前使用者，初始化默认取系统用户。
  - `globalAgent`: 全局系统 agent 名称/路径（默认 `chat`，解析规则与 `--system` 相同），仅在携带 `--system` 创建新会话时追加。
  - `providers`: 各 provider 配置，键为名称（如 `gemini`/`qwen`）。每项支持：
    - `apiType`: `gemini` 或 `openai`（qwen 属于 openai 兼容）。
    - `apiKey`: 对应 Key，缺失时会在启动 chat 时提示输入并写回。
    - `baseUrl`: 仅 openai 类型需要，缺失会报错退出。
    - 其他自定义字段会被保留。
- `chat`: 会话默认配置，包含 `provider`（必填，对应 providers 键）、`model`（必填）、`temperature`（可空，0~2）。
  - `repo.public-repo`: public 子模块仓库地址，`mchat --init` 时用于添加/更新子模块。
- 默认示例：
```yaml
user: yourname
globalAgent: chat
providers:
  qwen:
    apiType: openai
    baseUrl: https://dashscope.aliyuncs.com/compatible-mode/v1
    apiKey: ""          # chat 启动时缺失会提示输入并写回
  gemini:
    apiType: gemini
    apiKey: ""
chat:
  provider: qwen
  model: qwen3-max
  temperature: 0.7      # 可省略，使用模型默认
repo:
  public-repo: ssh://git@git.magicmind.cn:22222/ai/public.git
```
- 本地 LLM 配置（`.magicai/local-llm.yaml`）：
  - `basePort`：基础端口（默认 6660，embedding +1，reranker +2）。
  - `hfEndpoint`：HF 下载源（默认 https://hf-mirror.com）。
- `models.llm`/`models.embedding`/`models.reranker`：模型 name/下载文件（file）。
- `models.*.file`：下载文件名（需与 Hugging Face resolve path 一致）。
- `models.*.alias`：模型别名，写入容器环境变量（默认 llm/embedding/reranker）。
- `models.*.mmproj_file`：可选的视觉投影器文件名（如需要）；
  本地命令会自动下载并通过 `--mmproj` 参数传给 LLM。
- 会话与日志：对话内容保存在 `.magicai/chat-sessions/<timestamp>/`，最新会话软链为 `latest`；每轮消息按序号+角色命名。用量信息会输出到 stderr，并累计写入 `usage.json`。

## 工作区目录结构（建议）
- `public/`：系统提示词仓库，作为 git 子模块管理（默认仓库 ssh://git@git.magicmind.cn:22222/ai/public.git，若缺失可手动创建或覆盖配置）。
- `projects/`：业务子项目根目录，由 `mchat project` 管理（裸仓库置于 `projects/<name>/.repo`，各分支 worktree 平行放在同级目录）。
- `.magicai/`：配置与会话存档（`magicai.yaml`、`chat-sessions/` 等）。
- `README.md`、`package.json`、`src/` 等：CLI 工程自身代码与文档。

## 全局使用
```
alias m='docker run -it --user $(id -u):$(id -g) --add-host host.docker.internal:host-gateway --rm -v "$(pwd)":/workspace zhfcode/magicai mchat'
```


## 多任务执行
执行任务针对 project 目录中的 git 仓库进行操作