简介

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

命令行子命令（mchat [options]）

- 全局选项：--no-sandbox（跳过容器环境检测，默认要求在 docker 内运行；未检测到容器且未加此参数会退出）。
- chat [message...]：会话子命令（默认）。message... 为首条用户输入；缺省时从 stdin 读取，仍为空会报错退出。
- --session ：指定会话目录（相对 .magicai/chat-sessions/，禁止绝对路径与 ..）。未指定：存在 latest 则复用；携带 --system 时强制新建会话。
- --system ：追加系统提示词，可直接写字符串或 @路径（默认从工作区根的 public/agents/ 读取并补 .agent.md）。新会话时会把 YAML Front Matter（user/createTime/session）置于最前并追加 globalAgent 对应的 agent 作为独立 system 消息。
- --temp ：覆盖配置的温度（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//.repo 裸仓库 + 并列 worktree）
- --add ：克隆远程仓库为裸仓库 projects//.repo，自动检测默认分支（远程空仓库则使用 main），将默认分支以 worktree 检出到 projects///，并自动在根仓库注册为子模块。
- --new ：在 projects// 下创建裸仓库 .repo，初始化默认分支 main 的 worktree（未生成提交，供后续关联远程或直接开发）。
- --remove ：移除指定项目及其 worktree，需所有 worktree 处于干净状态。
- --commit：遍历 projects/ 下各项目 worktree，自动 git add + git commit。提交信息由模型生成，500 字内可多行，包含功能/行为摘要、主要修改文件与内容要点及潜在影响；无改动则输出跳过。
- --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

- 位置：/.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//，最新会话软链为 latest；每轮消息按序号+角色命名。用量信息会输出到 stderr，并累计写入 usage.json。

工作区目录结构（建议）

- public/：系统提示词仓库，作为 git 子模块管理（默认仓库 ssh://git@git.magicmind.cn:22222/ai/public.git，若缺失可手动创建或覆盖配置）。
- projects/：业务子项目根目录，由 mchat project 管理（裸仓库置于 projects//.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 仓库进行操作