maind 0.1.0__tar.gz

maind-0.1.0/.dockerignore

@@ -0,0 +1,13 @@
+.git
+.idea
+.mypy_cache
+.pytest_cache
+.ruff_cache
+.venv
+.vscode
+__pycache__
+*.py[cod]
+*.egg-info
+build
+dist
+htmlcov

maind-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+
+# Build
+dist/
+build/
+
+# Virtualenv / uv
+.venv/
+
+# Test / tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Editor / OS
+.DS_Store
+
+# SDD controller scratch (briefs, reports, diffs, ledger)
+.superpowers/
+.vscode
+.idea

maind-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

maind-0.1.0/.woodpecker/backend-build.yml

@@ -0,0 +1,63 @@
+# =========================================================================
+# Mai CLI 镜像构建 Workflow (amd64 + arm64 并行)
+# =========================================================================
+clone:
+  git:
+    image: harbor.mindreon.com/ops/woodpeckerci/plugin-git:latest
+    environment:
+      CI_NETRC_MACHINE: gitlab.mindreon.com
+      CI_NETRC_USERNAME: { from_secret: gitlab_username }
+      CI_NETRC_PASSWORD: { from_secret: gitlab_password }
+
+matrix:
+  include:
+    - PLATFORM: linux/amd64
+      ARCH: amd64
+    - PLATFORM: linux/arm64
+      ARCH: arm64
+
+labels:
+  platform: ${PLATFORM}
+
+steps:
+  build-cli-branch:
+    image: harbor.mindreon.com/ops/woodpeckerci/plugin-docker-buildx:6.0
+    privileged: true
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+    settings:
+      dockerfile: Dockerfile
+      repo: harbor.mindreon.com/baize/mai-cli
+      registry: harbor.mindreon.com
+      username: { from_secret: harbor_username }
+      password: { from_secret: harbor_password }
+      cache: true
+      daemon_off: true
+      platforms:
+        - ${PLATFORM}
+      provenance: false
+      auto_tag: false
+      tags:
+        - ${CI_COMMIT_BRANCH//\//-}-${ARCH}
+    when:
+      event: [push, manual]
+
+  build-cli-tag:
+    image: harbor.mindreon.com/ops/woodpeckerci/plugin-docker-buildx:6.0
+    privileged: true
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+    settings:
+      dockerfile: Dockerfile
+      repo: harbor.mindreon.com/baize/mai-cli
+      registry: harbor.mindreon.com
+      username: { from_secret: harbor_username }
+      password: { from_secret: harbor_password }
+      cache: true
+      daemon_off: true
+      platforms:
+        - ${PLATFORM}
+      provenance: false
+      tags: ${CI_COMMIT_TAG}-${ARCH}
+    when:
+      event: tag

maind-0.1.0/.woodpecker/backend-manifest.yml

@@ -0,0 +1,40 @@
+depends_on:
+  - backend-build
+
+skip_clone: true
+
+labels:
+  platform: linux/amd64
+
+steps:
+  manifest-cli-branch:
+    image: harbor.mindreon.com/ops/woodpeckerci/plugin-docker-buildx:6.0
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+    environment:
+      HARBOR_USER: { from_secret: harbor_username }
+      HARBOR_PWD: { from_secret: harbor_password }
+      REGISTRY: harbor.mindreon.com
+      REPO: harbor.mindreon.com/baize/mai-cli
+    commands:
+      - echo $HARBOR_PWD | docker login $REGISTRY -u $HARBOR_USER --password-stdin
+      - docker manifest create --amend $REPO:${CI_COMMIT_BRANCH//\//-} $REPO:${CI_COMMIT_BRANCH//\//-}-amd64 $REPO:${CI_COMMIT_BRANCH//\//-}-arm64
+      - docker manifest push $REPO:${CI_COMMIT_BRANCH//\//-}
+    when:
+      event: [push, manual]
+
+  manifest-cli-tag:
+    image: harbor.mindreon.com/ops/woodpeckerci/plugin-docker-buildx:6.0
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+    environment:
+      HARBOR_USER: { from_secret: harbor_username }
+      HARBOR_PWD: { from_secret: harbor_password }
+      REGISTRY: harbor.mindreon.com
+      REPO: harbor.mindreon.com/baize/mai-cli
+    commands:
+      - echo $HARBOR_PWD | docker login $REGISTRY -u $HARBOR_USER --password-stdin
+      - docker manifest create --amend $REPO:$CI_COMMIT_TAG $REPO:$CI_COMMIT_TAG-amd64 $REPO:$CI_COMMIT_TAG-arm64
+      - docker manifest push $REPO:$CI_COMMIT_TAG
+    when:
+      event: tag

maind-0.1.0/Dockerfile

@@ -0,0 +1,72 @@
+FROM harbor.mindreon.com/ops/python:3.12-slim AS builder
+
+COPY --from=harbor.mindreon.com/ops/astral/uv:latest /uv /uvx /bin/
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    PATH=/opt/venv/bin:$PATH \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple \
+    PIP_TRUSTED_HOST=pypi.tuna.tsinghua.edu.cn \
+    UV_PROJECT_ENVIRONMENT=/opt/venv
+
+WORKDIR /opt/mai-cli
+
+RUN sed -i \
+      -e 's#http://deb.debian.org/debian#https://mirrors.tuna.tsinghua.edu.cn/debian#g' \
+      -e 's#http://deb.debian.org/debian-security#https://mirrors.tuna.tsinghua.edu.cn/debian-security#g' \
+      /etc/apt/sources.list.d/debian.sources && \
+    apt-get update && apt-get install -y --no-install-recommends \
+    bash \
+    ca-certificates \
+    git \
+    make \
+    openssh-client \
+    skopeo \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY pyproject.toml uv.lock README.md ./
+COPY src ./src
+
+RUN uv sync --frozen --no-dev --no-editable --no-cache
+
+RUN mai --help >/dev/null && \
+    python -m mai --help >/dev/null && \
+    python -c "import dvc.repo, huggingface_hub, modelscope_hub, botocore" && \
+    dvc version >/dev/null && \
+    hf --help >/dev/null && \
+    ms -V >/dev/null 2>&1 && \
+    modelscope -V >/dev/null 2>&1 && \
+    skopeo --version >/dev/null && \
+    git --version >/dev/null
+
+FROM harbor.mindreon.com/ops/python:3.12-slim AS runtime
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    PATH=/opt/venv/bin:$PATH \
+    PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1
+
+RUN sed -i \
+      -e 's#http://deb.debian.org/debian#https://mirrors.tuna.tsinghua.edu.cn/debian#g' \
+      -e 's#http://deb.debian.org/debian-security#https://mirrors.tuna.tsinghua.edu.cn/debian-security#g' \
+      /etc/apt/sources.list.d/debian.sources && \
+    apt-get update && apt-get install -y --no-install-recommends \
+    bash \
+    ca-certificates \
+    git \
+    openssh-client \
+    skopeo \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=builder /opt/venv /opt/venv
+
+RUN ln -sf /opt/venv/bin/mai /usr/local/bin/mai && \
+    ln -sf /opt/venv/bin/dvc /usr/local/bin/dvc && \
+    ln -sf /opt/venv/bin/hf /usr/local/bin/hf && \
+    ln -sf /opt/venv/bin/ms /usr/local/bin/ms && \
+    ln -sf /opt/venv/bin/modelscope /usr/local/bin/modelscope && \
+    mkdir -p /workspace
+
+WORKDIR /workspace
+
+CMD ["mai", "--help"]

maind-0.1.0/HANDOFF.md

@@ -0,0 +1,110 @@
+# 交接文档 —— Mindreon Python SDK + CLI
+
+> 更新时间: 2026-07-03
+> 目的: 把当前上下文完整交接,任何人(或新会话)据此可无缝接手。
+
+## 一句话概况
+
+把现有的 `mindreon-cli`(Node.js) 重构为 **Python 的 SDK + CLI 二合一** 包,放进后端仓库既能 `import` 当 SDK、又能命令行当 CLI。**设计与实施计划已完成并提交;代码实现尚未开始(0/8 任务)。**
+
+## 背景与动机
+
+- 原始诉求: 维护者是 **Python 后端工程师(不会 Node)**,本想做一个放进后端仓库的 **Python SDK,同时具备 SDK 和 CLI 能力**。
+- 现状问题: 现有 `../mindreon-cli` 是 Claude Code 迭代中"跑偏"用 **Node.js** 写出来的(已发布 npm、有 Docker 镜像、v0.1.26)。维护者驾驭不了 Node,且 Node 包无法被 Python 后端 import。
+- 结论: 用 Python 重写。**不是语言偏好,而是**(1) 维护者不会 Node = Node 版是不可维护的黑盒;(2) 目标是"SDK 放后端仓库",Node 架构上做不到。
+
+## 关键决策(已定)
+
+| # | 决策点 | 结论 |
+|---|--------|------|
+| 1 | 定位 | Python,**SDK 为核心 + CLI 是薄壳**;业务逻辑只写一遍 |
+| 2 | 后端环境 | FastAPI (async) |
+| 3 | sync/async | **双客户端一次到位**:同步核心 + `MindreonClient` / `AsyncMindreonClient`;异步用 `anyio.to_thread` 包同步实现(不追求 git/dvc 的"真异步") |
+| 4 | 认证/配置 | 显式参数 + 环境变量(OpenAI 式)+ `from_config_file()`;`~/.config/mindreon/config.json` 读写**归 CLI 层**,SDK 不碰家目录 |
+| 5 | 外部工具 | git/git-lfs/dvc/modelscope/skopeo 全部 **subprocess + 运行时检测**;核心 SDK 只依赖 httpx/pyyaml(轻);dvc/modelscope 库调用留作未来可选 extras |
+| 6 | 仓库形态 | **单包 `mindreon`**,SDK + CLI 同包 |
+
+三个方法级默认(可推翻,已写进 spec 的"默认决策"节):
+- `create_model` / `create_dataset` **分开**(不合并成 `create(kind,...)`)
+- `ref` 用字符串 `"model:name"` 为主,也接受 `ResourceRef(kind,name)`
+- 工作区用 **`Workspace` 对象**封装 `status/add/commit/push`
+
+## 架构(三层)
+
+```
+返回结构化对象 ← SDK 门面(sync + async) ← CLI 薄壳(Typer)
+        ↑                  ↑                      ↑
+   dataclass         MindreonClient          解析参数→调门面→打印
+                     AsyncMindreonClient
+                          ↑
+                   _core 内部实现(同步纯逻辑:httpx / subprocess)
+```
+
+目标目录结构(尚未落地,见 spec):`src/mindreon/{client,async_client,models,errors}.py` + `_core/{settings,transport,routes,resources,workspace,tools,operations/}` + `cli/{app,commands/,config_file}`。
+
+## 已产出物(均在本仓库,已提交)
+
+| 路径 | 内容 |
+|------|------|
+| `docs/superpowers/specs/2026-07-03-mindreon-sdk-design.md` | 完整设计规格(架构/双客户端/认证/错误/测试/迁移/6 项决策) |
+| `docs/superpowers/plans/2026-07-03-mindreon-sdk-foundation.md` | **实施计划 1**:8 个 TDD 任务,打通架构基座 + login/status 端到端 |
+| `src/mindreon_cli/` + `tests/` | 早期**骨架**(见下),包名仍是旧的 `mindreon_cli`,计划 Task 1 会改名为 `mindreon` |
+
+### 现有骨架能干什么(已可运行)
+
+- `uv sync` 装环境;`uv run mindreon --help` 列出全部 16 命令;`uv run mindreon status`/`login` 已真实现;其余命令注册为 stub(报 "not yet implemented")。
+- 已通过: `pytest`(15 passed)、`ruff`、`mypy --strict`。
+- ⚠️ 注意: 这套骨架是**按"CLI 移植"思路搭的**,不是 SDK-first。计划 1 会把它重构成三层架构。
+
+## 当前状态(精确)
+
+- **分支**: `master` (⚠️ 还没开 feature 分支;按 subagent-driven 流程,实现前必须开)
+- **提交历史**:
+  - `192cda0` docs: add SDK foundation implementation plan
+  - `63e726c` docs: add Mindreon Python SDK + CLI design spec
+  - `bc3f989` chore: scaffold Python port skeleton
+- **未提交改动**: `docs/.../2026-07-03-mindreon-sdk-foundation.md` 有一处**已做但未提交**的修正 —— 给 Task 1 补了"改名后同步替换 `tests/` 里对 `mindreon_cli` 的绝对导入"(原计划漏了,会导致 Task 1 测试失败)。
+- **实现进度**: **0 / 8 任务**。尚未执行计划 1 的任何 Task,包名仍为 `mindreon_cli`。
+- **进度 ledger**: 尚未创建(`.superpowers/sdd/progress.md`)。
+
+## 下一步(接手就做)
+
+1. **提交那处计划修正**,创建功能分支,初始化 ledger:
+   ```bash
+   cd mindreon-cli-py
+   git add docs && git commit -m "docs: fix Task 1 to rewrite test imports on rename"
+   git checkout -b feature/sdk-foundation
+   mkdir -p .superpowers/sdd && printf '# SDD Progress\n\n' > .superpowers/sdd/progress.md
+   ```
+2. **按 `superpowers:subagent-driven-development` 流程执行计划 1** 的 Task 1→8:
+   每个 Task 派一个全新 implementer 子代理(计划里含完整代码,多为机械转录,用便宜模型即可),完成后派 reviewer 子代理审(spec 合规 + 代码质量),有 Critical/Important 问题派 fix 子代理,再复审,通过后记 ledger、下一个 Task。全程连续执行,不中途 check-in。
+3. **计划 1 完成后**,做整分支 code review,然后用 `superpowers:finishing-a-development-branch` 收尾。
+4. **后续计划(各自独立成文再执行)**:
+   - 计划 2: `project` + `create`
+   - 计划 3: `connect` + `download` + `repo`(首次引入 `Workspace` / subprocess / `tools.py`)
+   - 计划 4: `publish` + `file` + `image` + `seed`
+
+## 快速上手(验证环境)
+
+```bash
+cd mindreon-cli-py
+uv sync
+uv run mindreon --help
+MAI_CONFIG_DIR=/tmp/mr uv run mindreon status
+uv run pytest -q          # 现有骨架 15 passed
+```
+
+调试: VS Code 用 `.vscode/launch.json`(有 `mindreon: status` / `login` / `pytest` 配置)。
+
+## 注意事项 / 坑
+
+- **Python 版环境变量**: 统一使用 `MAI_*`，例如 `MAI_API_URL`、`MAI_AUTH_TOKEN`、`MAI_CONFIG_DIR`。不要再兼容 Node 版旧前缀。
+- **计划 Task 1 的 `perl -pi -e` 命令**用于替换 tests 引用;macOS 上 `perl` 比 `sed -i` 稳。
+- **不要在 `master` 上直接实现**(subagent-driven 硬规则)。
+- **Node 版参考源**: `../mindreon-cli/src/`。计划里标注 `upload_file`/`seed_*`/`build_image` 的确切参数需在实现对应命令时读 Node 源码(`file.js`/`seed.js`/`image.js`)对齐 —— 但这些属于后续计划 2-4,计划 1 不涉及。
+- **协调者工具怪癖**(本会话所用): `TaskCreate`/`TaskUpdate` 是单条操作(每次一个 `subject`/`taskId`),不接受数组批量。
+
+## 参考
+
+- 目标产物: 可 `pip install mindreon` → `from mindreon import MindreonClient` / `mindreon <cmd>`。
+- 流程链路: `brainstorming`(设计)→ `writing-plans`(计划)→ `subagent-driven-development`(执行)→ `finishing-a-development-branch`(收尾)。

maind-0.1.0/Makefile

@@ -0,0 +1,113 @@
+IMAGE_NAME ?= mindreon/mai-cli
+IMAGE_TAG ?= latest
+IMAGE ?= $(IMAGE_NAME):$(IMAGE_TAG)
+PLATFORMS ?= linux/amd64,linux/arm64
+BUILDER ?= mai-cli-builder
+TWINE ?= uv run --with twine twine
+
+.PHONY: help install dev run test cov lint format typecheck build package-check release-check publish-pypi publish-testpypi publish-pip clean buildx-create image-build-local image-push image-build-push image-buildx image-buildx-push image-run-help
+
+help: ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
+		awk 'BEGIN {FS = ":.*?## "}; {printf "  %-12s %s\n", $$1, $$2}'
+
+install: ## Create venv and install package + dev deps (editable)
+	uv sync
+
+dev: install ## Alias for install
+
+run: ## Run the CLI, e.g. make run ARGS="status"
+	uv run mai $(ARGS)
+
+test: ## Run the test suite
+	uv run pytest
+
+cov: ## Run tests with coverage report
+	uv run pytest --cov=mai --cov-report=term-missing
+
+lint: ## Lint with ruff
+	uv run ruff check src tests
+
+format: ## Auto-format with ruff
+	uv run ruff format src tests
+
+typecheck: ## Static type check with mypy
+	uv run mypy
+
+build: ## Build wheel + sdist into dist/
+	uv build
+
+package-check: build ## Check dist/* package metadata
+	$(TWINE) check dist/*
+
+release-check: lint typecheck test package-check ## Run all checks before publishing
+
+publish-pypi: package-check ## Publish dist/* to PyPI using PYPI_USERNAME/PYPI_PASSWORD
+	@username="$${PYPI_USERNAME:-$${TWINE_USERNAME:-}}"; \
+	password="$${PYPI_PASSWORD:-$${TWINE_PASSWORD:-}}"; \
+	if [ -z "$$username" ] || [ -z "$$password" ]; then \
+		echo "Set PYPI_USERNAME and PYPI_PASSWORD before publishing."; \
+		exit 1; \
+	fi; \
+	TWINE_USERNAME="$$username" TWINE_PASSWORD="$$password" $(TWINE) upload --verbose dist/*
+
+publish-testpypi: package-check ## Publish dist/* to TestPyPI
+	@username="$${PYPI_USERNAME:-$${TWINE_USERNAME:-}}"; \
+	password="$${PYPI_PASSWORD:-$${TWINE_PASSWORD:-}}"; \
+	if [ -z "$$username" ] || [ -z "$$password" ]; then \
+		echo "Set PYPI_USERNAME and PYPI_PASSWORD before publishing."; \
+		exit 1; \
+	fi; \
+	TWINE_USERNAME="$$username" TWINE_PASSWORD="$$password" \
+		TWINE_REPOSITORY_URL="https://test.pypi.org/legacy/" \
+		$(TWINE) upload --verbose dist/*
+
+publish-pip: package-check ## Publish dist/* to custom PYPI_REPOSITORY_URL
+	@username="$${PYPI_USERNAME:-$${TWINE_USERNAME:-}}"; \
+	password="$${PYPI_PASSWORD:-$${TWINE_PASSWORD:-}}"; \
+	url="$${PYPI_REPOSITORY_URL:-$${TWINE_REPOSITORY_URL:-}}"; \
+	if [ -z "$$url" ]; then \
+		echo "Set PYPI_REPOSITORY_URL for custom pip repository publishing."; \
+		exit 1; \
+	fi; \
+	if [ -z "$$username" ] || [ -z "$$password" ]; then \
+		echo "Set PYPI_USERNAME and PYPI_PASSWORD before publishing."; \
+		exit 1; \
+	fi; \
+	TWINE_USERNAME="$$username" TWINE_PASSWORD="$$password" TWINE_REPOSITORY_URL="$$url" \
+		$(TWINE) upload --verbose dist/*
+
+clean: ## Remove build/venv artifacts
+	rm -rf dist build .pytest_cache .ruff_cache .mypy_cache **/__pycache__
+
+buildx-create: ## Create or select Docker buildx builder
+	@if ! docker buildx inspect $(BUILDER) >/dev/null 2>&1; then \
+		docker buildx create --name $(BUILDER) --use; \
+	else \
+		docker buildx use $(BUILDER); \
+	fi
+	docker buildx inspect --bootstrap >/dev/null
+
+image-build-local: ## Build local Docker image
+	docker build -t $(IMAGE) .
+
+image-push: ## Push Docker image
+	docker push $(IMAGE)
+
+image-build-push: image-build-local image-push ## Build and push Docker image
+
+image-buildx: buildx-create ## Build multi-platform image without pushing
+	docker buildx build \
+		--platform $(PLATFORMS) \
+		-t $(IMAGE) \
+		.
+
+image-buildx-push: buildx-create ## Build and push multi-platform image
+	docker buildx build \
+		--platform $(PLATFORMS) \
+		-t $(IMAGE) \
+		--push \
+		.
+
+image-run-help: ## Run mai --help in Docker image
+	docker run --rm $(IMAGE) mai --help