mimir

# Mimir **您的进化工程指南** Mimir 通过提供结构化的指南来帮助您更高效地工作，这些指南可以直接在您的IDE中由AI助手访问。获取指导，生成工作计划，跟踪进度，并不断改进您的开发过程。 > 有关架构和设计详情，请参阅 [docs/architecture/SAO.md](docs/architecture/SAO.md) ## 核心实体 Mimir 使用 **7个核心实体** 来组织您的指南： 1. **指南** - 顶级方法容器（例如，“FDD”，“Scrum”） 2. **工作流程** - 过程中的活动序列（例如，“构建功能”） 3. **阶段** *(可选)* - 工作流中活动的分组（例如，“启动”，“建设”） 4. **活动** - 具有指导的工作单元（例如，“创建屏幕模型”） 5. **制品** - 活动的输入/输出（例如，“组件规范”，“单元测试”） 6. **角色** - 执行活动的人员（例如，“前端工程师”，“UX设计师”） 7. **操作指南** - 具体实施说明（例如，“使用Figma创建模型”） ## Mimir 可以做什么？ ### 通过MCP回答指南问题 您的AI助手可以直接在IDE中查询Mimir： ``` 您： “我如何根据FDD指南构建TSX组件？” AI：→ 查询Mimir → 返回活动指导和相关操作指南 ``` ### 生成工作计划 在GitHub或Jira中自动创建任务分解： ``` 您： “计划场景LOG1.1和屏幕LOG的实现，按照FDD” AI：→ 从指南生成工作订单 → 创建GitHub问题 ``` ### 评估项目进度 检查是否已完成某个阶段所需的所有制品： ``` 您： “我下周应该完成启动阶段。 我是否已生成所有必需的制品？” AI：→ 扫描代码库和问题 → 报告状态和差距 ``` ### 通过经验演进 当AI在工作中遇到问题时，它可以提出指南改进建议： ``` AI：→ 检测到重复的纠正 → 创建指南改进提案（PIP） 您：→ 在Web UI中审查PIP → 批准并附上说明 → 创建新的指南版本 ``` ### 访问指南库 根据您的访问级别，从HOMEBASE下载指南： - **基于家庭**：软件工程，UX设计，测试等 - **版本层级**：LITE（基础版），FULL（标准版），EXTENDED（高级版） ## 快速入门Docker 两个容器：**FOB** （Django Web UI + API）和 **MCP Facade** （将您的AI IDE连接到FOB）。 ### 步骤1 — 运行FOB ```bash # 认证到ECR（一次性） aws ecr get-login-password --region us-east-1 \ | docker login --username AWS --password-stdin \ 411113550285.dkr.ecr.us-east-1.amazonaws.com # 运行并持久存储（可选：传递GITHUB_TOKEN + GITHUB_BUG_REPO以启用反馈→问题） docker run -d \ --name mimir-fob \ -p 8000:8000 \ -v ~/mimir-data:/app/data \ -e MIMIR_USER=admin \ -e MIMIR_PASSWORD=changeme \ -e MIMIR_EMAIL=admin@localhost \ 411113550285.dkr.ecr.us-east-1.amazonaws.com/mimir:latest open http://localhost:8000 ``` ### 步骤2 — 获取您的API令牌 ```bash curl -s -X POST http://localhost:8000/api/auth/token/ \ -d "username=admin&password=changeme" | python3 -c \ "import sys,json; print(json.load(sys.stdin)['token'])" ``` ### 步骤3 — 在您的IDE中配置MCP MCP facade作为一个**公共Docker Hub镜像**发布（`featurefactory/mimir-mcp`）- 无需注册登录。 **Windsurf** (`~/.codeium/windsurf/mcp_config.json`)，**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`)，**Cursor** (`~/.cursor/mcp.json`): ```json { "mcpServers": { "mimir": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "MIMIR_DEV_ROOT=/Users/you/GitHub", "-v", "/Users/you/GitHub:/Users/you/GitHub", "-e", "MIMIR_SERVER_URL=http://localhost:8000", "-e", "MIMIR_TOKEN=<your-token>", "-e", "MCP_TRANSPORT=stdio", "featurefactory/mimir-mcp:latest" ] } } } ``` 用步骤2中的令牌替换`<your-token>`。保存后重启您的IDE。 > **导出/导入**：文件系统MCP工具需要`MIMIR_DEV_ROOT`和匹配的Docker卷挂载 - 参见 [docs/DOCKER_QUICK_START.md](docs/DOCKER_QUICK_START.md#filesystem-tools-export--import)。 > **多平台**：amd64 + arm64 · **数据安全**：挂载卷中的SQLite · **托管FOB**：更改 `MIMIR_SERVER_URL` 为 `https://mimir.featurefactory.io` 参见 [docs/DOCKER_QUICK_START.md](docs/DOCKER_QUICK_START.md) 了解docker-compose设置和完整参考。 ### 问题报告 → GitHub问题 **反馈**选项卡（和MCP `report_bug` / HTTP facade）会在GitHub上创建结构化的问题。在 **FOB（Web）主机** 上设置： | 变量 | 描述 | |----------|-------------| | `GITHUB_TOKEN` | 经典或细粒度PAT，具有目标仓库的**Issues: write**权限 | | `GITHUB_BUG_REPO` | 可选；默认为`FeatureFactory-io/mimir` | | `BUG_REPORT_DRY_RUN` | 可选；`1` / `true`跳过API（烟雾测试） | Docker Compose：将其添加到`web`服务环境（参见[.env.example](.env.example)）。**不要**将`GITHUB_TOKEN`放在MCP facade容器上 - 它调用Web API，使用令牌。 由CI从`DOCKERHUB_USERNAME`和`DOCKERHUB_TOKEN`**维护人员发布的**配置GitHub Actions secrets **`DOCKERHUB_USERNAME`**和**`DOCKERHUB_TOKEN`**，工作流在每次合格推送时构建`Dockerfile.mcp`为 **`featurefactory/mimir-mcp`**。遗留Azure容器注册表 **`acrmimir`** 已从管道中删除；当它未被使用时，在Azure中将其删除（例如`az login`然后`az acr delete --name acrmimir --yes`）并删除GitHub secrets **`ACR_USERNAME`** / **`ACR_PASSWORD`**（如果仍然存在）。 ### 先决条件 - Python 3.11或更高版本 - **Graphviz** （系统`dot`二进制文件 - 需要用于工作流活动图；仅`graphviz` pip包不够） - macOS：`brew install graphviz` - Debian/Ubuntu：`sudo apt-get install graphviz` - 支持MCP的IDE（Claude Desktop，Cursor，Windsurf等） - HOMEBASE的访问凭证（可选，用于同步） - **Playwright browsers** （可选 - 仅限E2E测试）：在`pip install`后运行`playwright install` ### 设置步骤 1. **克隆仓库** ```bash git clone https://github.com/petelind/mimir.git cd mimir ``` 2. **配置环境** ```bash cp .env.example .env # 根据需要编辑值（电子邮件，API密钥等） ``` `.env.example` 将 `MIMIR_DB_PATH=mimir.dev.db` 设置为每天工作的**个人SQLite文件** （gitignored）。 提交的 `mimir.db` 仅保留为共享种子。 没有本地 `.env` ，开发默认值可能与 `.env.example` 不同（例如，通过AWS SES控制台后端发送电子邮件）。 3. **创建虚拟环境** ```bash python -m venv .venv source .venv/bin/activate # 在Windows上：.venv\Scripts\activate ``` 4. **安装依赖项** ```bash pip install -r requirements.txt ``` 5. **初始化数据库** ```bash python manage.py migrate make dev-db-init # 一次：复制种子 → mimir.dev.db ``` **注意：** 提交的 `mimir.db` 包含 **FeatureFactory** 指南（用于构建Mimir的工作流）。在 `.env` 中设置 `MIMIR_DB_PATH=mimir.dev.db` 后， `make run` 和 `make mcp` 使用您的个人副本；git不会跟踪本地用户或实验。 在 `git pull` 更新种子后，刷新您的沙箱： `make refresh-dev-db`. 6. **确保本地超级用户** 创建或恢复用于MCP/ facade测试的约定开发超级用户： ```bash python manage.py create_default_admin ``` 在本地实验后重新运行此命令（推荐在运行 `pytest` facade测试之前）。 **对于生产或共享环境：** ```bash python manage.py createsuperuser ``` 您将被提示输入： - 用户名（必填） - 电子邮件（可选，用于密码重置） - 密码（至少8个字符） 7. **运行测试** 运行单元测试和集成测试： ```bash pytest tests/ ``` E2E测试（可选）需要先安装Playwright浏览器： ```bash playwright install pytest tests/e2e/ -v ``` > **注意**： `docs/features/act-*/`中的BDD功能文件作为综合UI规格（46个文件，涵盖Act 0-15）。开发过程中将实现步骤定义。 ## 快速参考 ### 运行应用程序 ```bash # 启动Web UI（在终端中保持运行） make run # → 打开 http://localhost:8000 # 手动测试MCP服务器（不同的终端） make mcp # → 按Ctrl+C停止 # 个人数据库（ .env中MIMIR_DB_PATH=mimir.dev.db） make dev-db-init # 一次：复制种子 → mimir.dev.db make refresh-dev-db # 拉取后：重新同步提交的mimir.db make dev-db-reset # 清除个人数据库并从种子重新创建 # 运行所有测试 pytest tests/ ``` ### MCP配置文件 - **Windsurf**: `~/.codeium/windsurf/mcp_config.json` - **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Cursor**: `~/.cursor/mcp.json` 参见上面的配置代码段。 ## 如何使用 Mimir作为两个进程运行，它们一起工作： ### 1. 启动Web界面 ```bash python manage.py runserver 8000 ``` 在浏览器中打开 http://localhost:8000 并使用您的凭证登录。 登录后，您可以： - **浏览指南**：查看活动、工作流、阶段、制品、角色和操作指南 - **审查PIP**：批准或拒绝指南改进提案 - **比较版本**：查看指南版本之间的更改 - **本地编辑**：自定义指南以适应您的团队 ### 2. 在您的IDE中配置MCP 在 [mimir.featurefactory.io](https://mimir.featurefactory.io/auth/register/) 注册并获取令牌，然后添加到您的IDE配置中： **Windsurf** (`~/.codeium/windsurf/mcp_config.json`) · **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`) · **Cursor** (`~/.cursor/mcp.json`): ```json { "mcpServers": { "mimir": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "MIMIR_DEV_ROOT=/Users/you/GitHub", "-v", "/Users/you/GitHub:/Users/you/GitHub", "-e", "MIMIR_SERVER_URL=https://mimir.featurefactory.io", "-e", "MIMIR_TOKEN=<your-token>", "-e", "MCP_TRANSPORT=stdio", "featurefactory/mimir-mcp:latest" ] } } ``` 对于本地FOB，请设置 `MIMIR_SERVER_URL=http://localhost:8000`。保存后重启您的IDE。 导出/导入文件系统工具需要 `MIMIR_DEV_ROOT` 和匹配的 `-v` 绑定挂载 - 参见 [docs/DOCKER_QUICK_START.md](docs/DOCKER_QUICK_START.md#filesystem-tools-export--import). ### 3. 在您的IDE中使用MCP工具 配置后，您的AI助手可以访问 **16个Mimir MCP工具** 来管理指南、工作流和活动： #### 指南管理（5个工具） - **`create_playbook`** - 创建新的指南草案 - **`list_playbooks`** - 列出指南（按状态筛选：草案/发布/全部） - **`get_playbook`** - 获取详细的指南信息，包含嵌套的工作流 - **`update_playbook`** - 更新指南详情（自动递增版本） - **`delete_playbook`** - 删除指南草案 #### 工作流管理（5个工具） - **`create_workflow`** - 向指南添加工作流 - **`list_workflows`** - 列出指南的工作流 - **`get_workflow`** - 获取工作流详情，包含活动 - **`update_workflow`** - 更新工作流详情 - **`delete_workflow`** - 从指南中删除工作流 #### 活动管理（6个工具） - **`create_activity`** - 向工作流添加活动 - **`list_activities`** - 列出工作流中的活动 - **`get_activity`** - 获取活动详情，包含依赖项 - **`update_activity`** - 更新活动指南、名称、阶段 - **`delete_activity`** - 删除活动 - **`set_predecessor`** - 定义活动依赖项（验证无循环依赖） **示例用法：** ``` "创建一个名为“Frontend Best Practices”的新指南" "在指南5中添加一个名为“组件开发”的工作流" "列出工作流3中的所有活动" "更新活动7以添加更详细的指南" ``` 所有工具都支持异步操作并自动验证用户权限。 ## 典型工作流 ### 每天开发 1. **配置您的IDE**（一次性设置） 将Mimir添加到您的IDE的MCP配置（参见上面的第2节）： - **Windsurf:** `~/.codeium/windsurf/mcp_config.json` - **Claude Desktop:** `~/Library/Application Support/Claude/claude_desktop_config.json` - **Cursor:** 工作区设置或 `.cursorrules` 配置后，通过您的IDE的AI助手与Mimir交互： ``` "Mimir，列出可用的指南" "Mimir，显示Build Page工作流" "Mimir，计划FOB-LOGIN-1按照BPE1 Plan Feature" "Mimir，执行BPE2" ``` 2. **开始使用Mimir** 配置后，通过IDE的AI助手与Mimir交互： ``` "Mimir，列出可用的指南" "Mimir，显示Build Page工作流" "Mimir，计划FOB-LOGIN-1按照BPE1 Plan Feature" "Mimir，执行BPE2" ``` 3. **可选：Web UI进行管理** 启动Web界面以可视化管理指南： ```bash python manage.py runserver 8000 ``` 打开 http://localhost:8000： - 浏览和编辑指南 - 查看工作流和活动 - 管理方法论内容 **注意：** 如果指南处于草稿状态，可以直接修改" ``` ### 故障排除 #### MCP 服务器无响应 1. **验证令牌是否有效：** ```bash curl -s -H "Authorization: Token <your-token>" \ http://localhost:8000/api/playbooks/ ``` 2. **手动测试MCP facade：** ```bash docker run --rm -i \ -e MIMIR_SERVER_URL=http://localhost:8000 \ -e MIMIR_TOKEN=<your-token> \ -e MCP_TRANSPORT=stdio \ featurefactory/mimir-mcp:latest ``` 发送 `{"jsonrpc":"2.0","method":"tools/list","id":1}` — 您应该会看到53个工具的列表。 3. **检查IDE日志：** - **Windsurf**：在MCP设置面板中查看日志 - **Claude Desktop**：检查 `~/Library/Logs/Claude/` - **Cursor**：检查IDE控制台中的MCP连接错误 4. **常见问题：** - **"Image not found"**: 运行 `docker pull featurefactory/mimir-mcp:latest` - **"Unauthorized"**: 令牌过期 — 在个人资料页面重新生成 - **"Connection refused"**: FOB未运行 — 检查 `docker ps | grep mimir-fob` ### 数据库锁定 如果您看到“数据库已锁定”的错误： ```bash # 确保只有一个Web服务器正在运行 pkill -f "manage.py runserver" # 重启Web服务器 python manage.py runserver 8000 ``` ## 项目结构 > **注意**：内部代码使用`methodology`作为术语来提高准确性（例如Django应用名称、模型、命令），而用户端术语使用“指南”来提高可访问性。这是有意的 - 参见 [SAO.md](docs/architecture/SAO.md) 了解详情。 ``` mimir/ ├── docs/ │ ├── architecture/ │ │ └── SAO.md # 系统架构与设计 │ ├── features/ # BDD规范（46+文件） │ │ ├── act-0-auth/ # 身份验证、注册、导航 │ │ ├── act-2-playbooks/ # 指南CRUDLF（5个文件） │ │ ├── act-3-workflows/ # 工作流CRUDLF（5个文件） │ │ ├── act-4-phases/ # 阶段CRUDLF（5个文件，可选） │ │ ├── act-5-activities/ # 活动CRUDLF（5个文件） │ │ ├── act-6-artifacts/ # 制品CRUDLF（5个文件） │ │ ├── act-7-roles/ # 角色CRUDLF（5个文件） │ │ ├── act-8-howtos/ # 操作指南CRUDLF（5个文件） │ │ ├── act-9-15/ # PIP、导入/导出、家庭、同步、MCP、设置、错误 │ │ └── act-13-mcp/ # MCP集成规范（4个文件） │ ├── mcp/ # MCP文档 │ │ ├── README.md # MCP概述 │ │ └── *.md # 实现状态文档 │ └── ux/ │ ├── user_journey.md # 完整的Acts 0-15叙事 │ └── 2_dialogue-maps/ │ └── screen-flow.drawio # 视觉MVP流程图 ├── mimir/ # Django项目 │ ├── methodology/ # 核心应用（内部名称） │ │ ├── models/ # 指南、工作流、活动等 │ │ ├── services/ # 业务逻辑（指南服务等） │ │ ├── repository/ # 存储抽象层 │ │ └── views/ # Web UI视图 │ └── mcp_integration/ # MCP服务器集成（Django应用） │ ├── tools.py # 16个MCP工具函数（异步） │ ├── context.py # 用户上下文管理 │ └── management/ │ └── commands/ │ └── mcp_server.py # Django命令：mcp_server ├── tests/ │ ├── unit/ # 单元测试（服务、模型） │ ├── integration/ # 集成测试（MCP工具、工作流） │ └── e2e/ # 端到端测试（Playwright） ├── manage.py └── requirements.txt # 包括fastmcp、pytest-asyncio ``` ## 贡献 我们欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解指南。 ### IDE特定规则 Mimir在两种格式中维护项目规则以支持不同的AI驱动的IDE： - **`.windsurf/rules/*.md`** - 适用于Windsurf IDE - **`.cursor/rules/*.mdc`** - 适用于Cursor IDE 这两个规则集都包含相同的内容，但格式不同。 **如果您使用Cursor并修改规则**，请要求您的IDE在两个格式之间保持同步，以保持一致。 ## 许可证 https://github.com/FeatureFactory-io/mimir#Apache-2.0-1-ov-file ## 学习资源 ### Django 新手？ **快速阅读** （20分钟）： [Django 概览](https://docs.djangoproject.com/en/stable/intro/overview/) - 官方 Django - 涵盖模型、视图、模板、URL 路由 - 在深入 Mimir 的代码库之前完美的入门读物 **视频教程** （30分钟）： [Django For Everybody - Introduction](https://www.youtube.com/watch?v=o0XbHvKxw7Y) - 查克博士的易懂介绍 - 涵盖请求/响应循环和 MTV 模式 - 来自热门的"Django for Everybody"课程 **奖励快速参考** ： [Django Cheat Sheet](https://github.com/lucrae/django-cheat-sheet) - 常见模式的单页参考 - 模型、视图、模板、表单一览 ### HTMX 新手？ **快速阅读** （15分钟）： [ 文档 - 介绍](https://.org/docs/) - 官方文档涵盖核心概念 - 使用 HTML 属性的 AJAX 请求 - 交换事件处理 **视频教程** （25分钟）： [HTMX 速成课程](https://www.youtube.com/watch?v=r-GSGH2RxJs) - HTMX 实际应用的例子 - 无 JavaScript 的渐进增强 - Mimir 服务器端方法的完美补充 **交互式示例** （10分钟）： [HTMX 示例](https://htmx.org/examples/) - 点击删除行、编辑行、无限滚动示例 - 显示 Mimir 用于 CRUD 操作的模式 - 可以检查的实时演示 ### Mimir 如何使用这些技术 - **Django**：自定义视图（无 Django 表单）、存储库模式、pytest 测试 - **HTMX**：部分页面更新、表单提交、动态内容加载 - **结合使用**：服务器渲染的 UI，具有流畅的交互性，无需浏览器自动化即可测试 请参阅 [docs/architecture/SAO.md](docs/architecture/SAO.md) 以获取 Mimir 的特定实现模式。 --- ## 了解更多 - **架构**： [docs/architecture/SAO.md](docs/architecture/SAO.md) - 完整的系统设计 - **用户旅程**：/features/user_journey.md](docs/features/user_journey.md) - 完整的 Act 0-15 叙述，包含所有屏幕 - **功能文件**： [docs/features/](docs/features/) - 46 个 BDD 规范，涵盖所有实体的完整 CRUDLF - **屏幕流程**： [docs/ux/2_dialogue-maps/screen-flow.drawio](docs/ux/2_dialogue-maps/screen-flow.drawio) - 视觉 MVP 流程图 - **UI 指南**： [docs/ux/IA_guidelines.md](docs/ux/IA_guidelines.md) - Bootstrap 设计系统、表单、验证、toast 通知 - **GitHub 问题**： [MVP 里程碑](https://github.com/petelind/mimir/milestone/2) - 跟踪开发进度 - **MCP 协议**： [模型上下文协议规范](https://spec.modelcontextprotocol.io/) ## 支持 - **问题**： [GitHub 问题](https://github.com/petelind/mimir/issues) - **讨论**： [GitHub 讨论](https://github.com/petelind/mimir/discussions) - **项目面板**： [MVP 里程碑](https://github.com/petelind/mimir/milestone/2)