MagicAI 软件开发工作区智能会话助手
npm install @mmteam/magicchat--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/--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 端口。mchat initmchat chat "帮我梳理 README 要点" 或 echo "ls" | mchat chatmchat chat --system "@code-review"(默认从工作区根 public/code-review.agent.md 读取并写入 Front Matter 和 globalAgent,不回退 agents/)mchat llm-only(仅读取 .magicai/local-llm.yaml,不支持命令行参数覆盖)mchat db-onlymchat chat --session feature/bugfix-123 "继续上一条对话"mchat chat --temp 1.2 "写一段更有创意的文案"mchat test-proxymchat project --add git@server/repo.gitmchat project --new demomchat initmchat project --branch demo/feature-xmchat project --remove demomchat project --commit/.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/,各分支 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'
``