maias

Name: maias
Author: MAIAS-project

本地服务

github.com/MAIAS-project开发工具12 周前更新

代码仓库

关于 maias

MAIAS 是一种用 YAML 或 JSON 描述应用信息架构的规范与工具集，供产品团队和 Agent 共同编写、审阅及实现应用。它结合注释保留编辑、语义校验、MCP 工具和可视化预览；项目处于预发布阶段。

主要功能

01以单个文档描述界面、导航、流程和状态
02解析、序列化并保留注释
03校验结构与语义问题
04安全编辑并级联重命名引用
05CLI 格式化与线框图生成
06浏览器渲染文档并提供设计适配器

适用场景

01校验应用信息架构文档
02重命名屏幕并更新相关引用
03通过 Agent 查询或编辑文档
04将文档渲染为应用预览或线框图

MCP 相关

MAIAS 提供 MCP 服务，向兼容 Agent 暴露 validate、query、edit 和 edit_elements 工具。CLI 也可生成线框图。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "maias-project-maias": {
      "command": "npx",
      "args": [
        "-y",
        "@maias/mcp"
      ]
    }
  }
}

启动命令npx -y @maias/mcp

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@maias/mcp0.5.1stdio

工具

收录的工具列表 · 更新于 2 周前

参数	类型	必填	说明
file	string	是	MAIAS 文档的 .yaml 或 .json 路径

详细介绍

MAIAS — 移动应用信息架构模式

一项开放标准，用于描述应用的信息架构——屏幕、导航、流程、UI 元素、状态和数据依赖——将所有内容放在一份 YAML（或 JSON）文档中，人类易于阅读，Agent 也能据此执行操作。

maias: "0.3"
app:
  name: Todo List
  navigation:
    primary:
      screens: [home, settings]     # ← the tab bar, derived, not drawn
  flows:
    - name: main
      entry_screen: home
      screens: [home, task_detail, task_new]
screens:
  - id: home
    title: My Tasks
    type: list
    path: /tasks
    description: All tasks, newest first.
    elements:
      - label: Buy milk
        type: list_item
        target: task_detail          # ← references are validated, renames cascade

**原因：**为人类与 Agent 协作开发应用提供一种通用语言。Agent 可以根据文档构建所描述的应用（实现指南）、通过安全的机器操作（命令行、MCP）创建和编辑文档；人类也可以阅读和审核同一文件。

**初次接触？**观看简短的视频介绍，了解 MAIAS 是什么、它为何存在，以及插件的实际演示：TechPdM/maias-showcase。

此仓库包含什么


规范	docs/spec/ — 11 章 · llms.txt（适用于一个上下文窗口的 Agent 参考资料）· schema/maias.schema.json
`@maias/core`	packages/core — 解析 → 类型化模型 → 序列化，并保持往返保真度（编辑后注释仍会保留）、图形工具、安全编辑（级联重命名、元素批量操作）、规范格式化程序、兼容 Hermes 的验证
`maias` CLI	packages/cli — `maias validate`（模式 + 语义检查，`--json`）、`maias fmt`、`maias rename`
MCP 服务	packages/mcp — 为任何支持 MCP 的 Agent 提供 `validate` / `query` / `edit` / `edit_elements` 工具
MAIAS Browser	MAIAS_browser — Expo 应用，可在运行时打开并渲染任意 MAIAS 文档：动态标签栏、可插拔的设计系统适配器（线框图 · shadcn 风格 · 蓝图）、应用内验证错误
示例	examples/ — calculator · todo_list · social_network · ecommerce — 合计涵盖所有核心元素和屏幕类型
Claude 技能	.claude/skills/ — `maias-create`、`maias-edit`、`maias-review`、`maias-wireframe` · 可作为 maias plugin 安装到任何位置

快速开始

需要 Node.js 20.19.4+ / 22.13+ / 24.3+（CI 使用 22）。无需克隆或安装——这些软件包已发布到 npm：

# validate a document — schema + semantic lint (dangling targets, orphans,
# path collisions), with line numbers; add --json for machine-readable output
npx -y @maias/cli validate my-app.maias.yaml

# canonical formatting (idempotent; agent edits diff cleanly)
npx -y @maias/cli fmt my-app.maias.yaml --write

# rename a screen — cascades to flows, navigation, every target
npx -y @maias/cli rename my-app.maias.yaml old_screen new_screen

更喜欢直接使用 maias 命令？运行 npm i -g @maias/cli。

**在 Claude Code 中，**一次安装即可获得四项技能和 MCP 服务：

/plugin marketplace add MAIAS-project/maias-plugin
/plugin install maias@maias

**在任何 MCP 客户端中，**使用 claude mcp add maias -- npx -y @maias/mcp 添加服务（或使用对应的 JSON 配置——请参阅 packages/mcp）；该服务也已收录在官方 MCP 注册表中，标识为 io.github.MAIAS-project/maias。

MAIAS Browser（将任意文档渲染为可运行的应用，支持 Web/iOS/Android）需从克隆的仓库运行：

git clone https://github.com/MAIAS-project/maias.git && cd maias
npm install && npm run build
npx maias validate examples/todo_list/maias.yaml
npm run web --workspace maias-browser

在克隆的仓库中工作时，运行 npm run link-tools 会将工作区 CLI（以及 maias-mcp 服务）通过符号链接添加到 PATH，并跟踪本地构建；运行 npm rm -g @maias/cli @maias/mcp 可撤销此操作。

要编写文档，请从 docs/spec/llms.txt 开始——仅凭它就足够了——或者在 Claude Code 中直接提问：“为食谱应用创建一份 IA”（maias-create 技能会接手后续工作）。

项目文档

项目架构：docs/ARCHITECTURE.md · 浏览器的实际构建：MAIAS_browser/ARCHITECTURE.md · 本地 Agent 设置（MCP、离线验证）：docs/ARCHITECTURE_LOCAL_SETUP.md · 根据文档构建应用：docs/implementation-guide.md · 设计系统适配器：docs/adapters.md。

状态

预发布版。 MAIAS 尚未达到 1.0 版本：在 0.x 版本之间，格式和工具可能会发生不兼容变更。规范 v0.3（在 0.2 的基础上重命名 capabilities/deep_links，并新增元素优先的链接规则）；六项项目交付成果均已实现（规范 + schema、验证器/代码检查工具、浏览器、示例、技能、Agent 互操作工具包）。测试：npx vitest run（核心往返转换/代码检查/格式化、CLI、MCP）。请参阅下文的版本说明，了解项目的发展历程。

版本说明

各软件包独立定版本（预发布阶段：次版本号递增表示不兼容变更，修订版本号递增涵盖功能和修复），因此以下历史记录按里程碑从新到旧排列。对于格式本身，权威记录请参阅规范变更日志。

2026-10-12 — 示例审查、加载器加固、视频导览。 经过一轮审查，四份示例文档补充了更完整的使用流程、状态、数据连接和导航标签；如果编译内置的 schema 格式错误，@maias/core 现在会在加载时明确报错，并提供回归测试；发布辅助脚本已纳入版本控制，存放于 scripts/；简短的视频导览位于 TechPdM/maias-showcase。（仅源码有变更——没有发布新软件包：core/mcp 0.5.1 · cli 0.4.0 · plugin 0.5.1）
2026-07-25 — 确定性线框渲染器。 maias wireframe 可通过 CLI 和 MCP 服务将文档确定性地渲染为独立 HTML 线框图；maias-wireframe 技能负责协调渲染器，而不是手动绘制。（core/mcp 0.5.1 · cli 0.4.0 · plugin 0.5.1）
2026-07-24 — 规范 v0.3。 将屏幕的 actions: 重命名为 capabilities:，将 app.links 重命名为 app.deep_links，新增元素优先的链接规则和针对重命名键的版本门控代码检查，以及保留注释的 maias migrate 命令。（core 0.4.0 · cli 0.3.0 · mcp 0.4.0）
2026-07-23 — 预发布版本号调整。 规范版本从 1.0 和 1.1 分别调整为 0.1 和 0.2，不涉及语义变更，以反映项目尚未达到 1.0 版本的状态。
2026-07-19 — 首次发布。 @maias/core、@maias/cli 和 @maias/mcp 已发布到 npm；Claude Code 插件（技能 + MCP 服务）和官方 MCP 注册表条目（io.github.MAIAS-project/maias）正式上线。
2026-07-18 — 加固。 首次从全新克隆完成完整安装和测试：修复构建顺序和工作区链接问题，使格式化工具符合规范的规范形式，在代码检查工具中加入版本—功能门控，并将 Node 最低版本提升至 20.19.4+。
2026-07-07 — MAIAS 项目公开。 项目更名为 MAIAS（参见规范变更日志），并在文档头部键、schema、诊断代码、软件包名称和 CLI 二进制文件中统一更新；新增 Apache-2.0 许可证和 CI；代码仓库公开发布。
2026-07-05/06 — 初始规范和工具包。 从可运行的原型扩展而来，规范 v0.1（12 种屏幕类型、29 种元素类型、流程、两级导航、状态、数据依赖、规范形式）和 v0.2（声明式返回导航）相继推出，同时发布核心库、CLI、MCP 服务、MAIAS Browser、示例文档和 Claude 技能。