Skip to main content

MoAI Web Console

由六个区域(概览・工厂・SPEC・监视・设置・待办)构成的本地运维控制台 — 实时更新、只读观测、设置编辑。

更新 2026-10-03 11 分钟阅读 在 GitHub 上编辑 ↗

MoAI Web Console

MoAI Web Console 是用 moai web 启动的本地运维界面。它把项目的 SPEC 目录、工厂泳道、会话与目标、验证历史集中在一处,并且可以在同一界面里修改设置。浏览器只连接 127.0.0.1,既没有数据库,也没有登录。

信息
一句话概括: 控制台是把五个观测区域和一个设置区域用左侧导轨组织起来的运维外壳。观测区域只读取,设置区域使用与终端向导相同的校验与持久化层。

运维外壳 — 左侧导轨与顶栏

界面分为三块。左侧导轨纵向排列六个区域,上方顶栏承载当前界面标题与状态,其余是正文。无论处在哪个区域,导轨与顶栏都停留在同一位置。

区域路由作用
概览(Overview)/项目整体摘要 — 统计磁贴、进行中的 SPEC、注意列表、会话
工厂(Factory)/factory工厂泳道列表 + SPEC 流水线四列
SPEC(Specs)/specsSPEC 目录的搜索、筛选与详情,关闭欠账与 MUST-FIX drift
监视(Monitor)/monitor会话・目标・验证・史诗四个面板
设置(Settings)/settings配置文件偏好与项目章节的编辑
待办(Todo)/todo待办队列的只读视图 — 三种状态的卡片全部列出

顶栏右侧显示什么取决于区域。五个观测区域显示实时指示灯,设置区域显示保存簇(变更数量与保存按钮)。上下文标签(lang · model · effort · dev)只在设置区域渲染 — 因为它们的用途是在保存前用肉眼确认正在编辑的配置文件的关键取值。

导轨底部聚集了配置文件按钮、项目名称、界面语言选择器和退出按钮。按下配置文件按钮会打开一个浮层,切换、新建、重命名与删除都在这里完成。从任何界面打开的都是同一个浮层,因此整个控制台处理配置文件的入口只有一个。

flowchart TD
    Rail["左侧导轨
概览 · 工厂 · SPEC · 监视 · 设置 · 待办"] Top["顶栏
标题 · 实时指示灯 / 保存簇"] Body["正文
各区域界面"] Read["只读区域
概览 · 工厂 · SPEC · 监视 · 待办"] Write["设置区域
经由校验与持久化层"] Files["项目文件
.moai/ 下的状态与设置"] Rail --> Body Top --> Body Body --> Read Body --> Write Read -->|仅读取| Files Write -->|保存| Files style Read fill:#E3F2FD,stroke:#1565C0 style Write fill:#FFF3E0,stroke:#E65100

概览 — 项目现在处于什么状态

概览以四个统计磁贴开始:SPEC(总数与进行中的数量)、drift(MUST-FIX 数量)、session(PID 已确认数 / 注册表登记数)、verify(最近一次验证结果与键数量)。

其下是进行中的 SPEC 列表、需要注意面板(只收集 MUST-FIX drift、失败的验证与停滞的目标),右侧是会话面板。

工厂 — 泳道与流水线

工厂区域上下放置了两个性质不同的列表。

工厂泳道列表每个已注册的泳道占一行,记录其会话、卡片、SPEC 标识符与后端。阶段状态是从心跳推断出来的,因此会附带推断标记;模型、推理强度与上下文取自该会话自己的遥测记录,单元格留空则表示该会话还没有承载这个值的记录 — 不去填补正是这里的纪律。若某泳道的进程 id 找不到任何会话,或在任一注册表上无法指向唯一会话,该行会被标为无法确定,并且不携带任何值:一次在错误会话上完成的查找,会把另一个泳道的记录当作这个泳道的画出来,这比空行更糟。若没有已注册的泳道,列表会写明没有。

SPEC 流水线按 status 把 SPEC 排入四列(draft · in-progress · implemented · completed)。superseded · archived · rejected 不会出现在这个列表里,只能通过 SPEC 区域的筛选器查看。

SPEC — 目录与两个警示面板

SPEC 区域顶部是搜索框与 status 筛选标签。紧接着,两个警示面板排在列表之前。

  • 关闭欠账(Close debt) — 实现已经落地(implemented)但 lifecycle 从未关闭到 completed 的 SPEC。数量较多时只展示最近更新的若干条,并同时写明已截断的事实与总数。
  • MUST-FIX drift — 带有处置命令的 drift。命令只做复制。控制台不会在服务端执行任何命令 — 复制之后由你在自己的终端里执行。

两个面板排在列表上方的理由很简单:当目录达到数百行时,放在下方的内容会被挤到界面很靠下的位置,实际上等同于不存在。

列表由 ID、标题、status、Tier、era、更新日期与 drift 各列构成。选中某一行会在右侧展开详情面板,显示文档列表、文件路径与 drift 详情。

监视 — 四个观测面板

面板读取的内容
会话(Sessions)会话 id、SPEC、后端、心跳、工作目录
目标(Goals)已装载目标的条件、已进行的轮数、是否停滞、判定
验证(Verification)每个键的近期历史迷你图与是否通过
史诗(Epics)moai epic status 计算出的各史诗进度

待办 — 待办队列,只读

moai todo 写入的待办队列有了自己的地址。这个界面把三种状态的卡片全部列出 — queued、picked、dropped — 连同各自的 id、内容、状态徽标,以及若已产出 SPEC 则附上 SPEC id。不做任何过滤:这个界面要回答的问题是"那张卡片去哪了",只显示排队卡片的工作视图回答不了。

它只读取。新增、领取与丢弃都归 moai todo,控制台既不写入队列,也不获取队列的锁。在链接的工作树中打开也不会是空的,看到的是主检出的队列 — 队列是每个仓库唯一的通道,页头会写出解析到的目录,让你知道正在看哪个文件。

队列不存在,或成功读取的队列没有卡片时,返回 HTTP 200 并显示空队列提示。读取失败时也返回 HTTP 200,但显示无法读取的提示,不会显示 0 张卡片。页面不会暴露存储层的原始错误。

实时更新 — 只发信号,然后重新取回

观测区域会在监视的文件发生变化时更新。服务端通过 GET /events 保持 SSE 流,监视下表中的项目路径及解析后的主目录,并以 250 毫秒为单位合并文件变更通知。

关键在于事件不携带数据。服务端只发送「这个区域变了」这一名称,浏览器收到信号后重新取回当前界面,只替换正文。渲染的真实只留在服务端这一处,因此界面与文件不会出现互相矛盾的状态。

事件监视对象
spec.moai/specs
session.moai/state
goal.moai/state/goal
verify.moai/state/verify
factory.moai/state/todo、解析后的主目录 Todo 目录(~/.moai/db/<project-key>/todo)、解析后的 Factory 目录
config.moai/config/sections

只有 config 事件的处理方式不同。若在编辑设置的过程中界面被从底下改动,正在输入的值就会丢失,因此不做刷新,只弹出一条「配置文件已变更」的横幅。

启动时不存在的目录会每隔 1 秒重试注册监视。新目录注册成功后,即使 SSE 连接正常,也会发送刷新信号。连接断开后,顶栏指示灯会显示断开状态;重连失败 3 次后,浏览器改为每隔 30 秒轮询。

不把不知道的事写成知道的事

控制台恪守的一条纪律体现在界面的各处。

  • 会话是否活跃只把确认进程存活的项提升为活跃。注册表里留有记录但进程可能早已结束,因此未经确认的条目标记为陈旧。
  • 阶段状态是从心跳推断出的值,并把「这是推断」这一事实一并标注。
  • 没有记录的值(各角色的模型、推理强度、上下文使用量)不用看似合理的数值填补,而是留空。无法归属到唯一会话的工厂泳道也不会借用另一个泳道的记录,而是标为无法确定。
  • 空列表不会就那样空着,而是写明「没有」。否则空面板会被读作「尚未读取」。

设置 — 相同的检查,相同的文件

设置区域是控制台里唯一写文件的地方。控制台不设立自己的校验规则,而是调用与终端向导(moai profile、moai update -c)相同的校验与持久化层。这正是从任何一侧修改结果都一致的原因。

在导轨中选择设置后,其下会以纵向列表展开以下标签页。

  1. 身份(Identity) — 显示名称与项目级 identity 字段
  2. 语言(Language) — 对话、提交信息、代码注释与文档的语言
  3. CLAUDE 设置(Claude settings) — 权限模式、模型、推理强度
  4. GLM设置(GLM Settings) — 按层级的 GLM 模型、按层级的推理强度、GLM API 密钥
  5. Codex 设置(Codex settings) — 把分散的 分散的 codex 设置汇总到一屏的只读镜像:审计后端与 codex 固定值、是否启用 codex、以及检测到的可执行文件。这里不修改取值,每一行都链接到真正拥有该取值的标签页
  6. 工作流(Workflow) — 执行模式、默认模式、agentic-loop、loop-prevention
  7. Git·工作树(Git & Worktree) — git_strategy.mode、各配置文件的 merge_method、工作树与 branch-guard 开关
  8. 审计(Audit) — 审计模型与各后端的门禁
  9. 报告(Report) — 报告格式与输出偏好
  10. MCP — moai mcp-server 各工具的启用开关。可写工具带有区分标记
  11. 跨会话消息(Cross-Session) — 会话间消息收发的接收姿态 (posture):入站处理方式(accept · hold · refuse)、跨机发送隔离、保留对话的过期。编辑的是 crosssession.yaml,启动器从下一次 moai cc/glm 执行起把该值注入会话 —— 已在运行的会话保持启动时的姿态
  12. 反馈 — 反馈工作流提交 issue 的目标仓库,以及提交前的确认开关
  13. 质量门禁 — 提交时是否运行 heavy 门禁。运行器只在 MOAI_PRECOMMIT=1 下读取该取值

各标签页旁的数字是该标签页渲染的字段数量。存在错误的标签页会以警示标记取代数字,因此从列表本身就能看出该打开哪个标签页。

Codex 设置标签页为何只读

codex 的设置原本分散在审计标签页和 MCP 标签页。要回答「本项目是怎么用 codex 的」,得在两个标签页之间来回翻,读那些从不同时出现的取值。Codex 设置标签页把它们放在同一屏上。

只汇总不编辑是选定的取舍,而不是没做完。 设置区域的所有面板都在同一个 <form> 内,保存路径对同名提交的取值只读取第一个。因此把同一项设置在两个面板里都画成控件,后一个面板里的修改会被无声丢弃。bool 设置更糟:它随附的隐藏字段单独出现时会被读作显式的 false,于是仅仅打开这一页并保存,就会关掉六个 MCP 工具开关。

所以 Codex 设置标签页只渲染取值和链接,不生成任何带名字的输入元素。每一项设置仍然声明、渲染并编辑于它自己的标签页。日后把这一页「改成可编辑」,等于把上面那种丢失重新请回来。

没有新增任何配置。 没有新的配置键,没有新的持久化路径,.moai/config 下也没有新文件。设置本来就存在,新增的只是把它们放在一起看的地方。

MCP 工具开关在磁盘上常常是空的,而控制台把空值读作已启用。这一页不去自行解释这份空白(那会让它成为第二个分类器),而是写上 (未设置),并在分组标题里说明这一事实:取值为空即视为启用,只有显式的 false 才会关闭某个工具。

控件的诚实

字段会以匹配取值真实域的控件渲染。bool 字段画成两选项的单选组而非复选框 — 复选框会隐藏当前选择,成对的单选按钮则把它显露出来。execution_mode 或 audit.model 这类闭合集合使用下拉框或单选组,集合之外的值在保存时被拒绝。只有仓库路径或 API 密钥这类域确实开放的值才保留为自由文本。

GLM 诚实徽章

推理强度在运行时的传递通道只有一个会话级环境变量,因此按层级填写的推理强度是仅保存的。它们会留在配置里,但运行时只读取会话级的值。GLM设置标签页带有一枚标明实际生效来源的徽章,使这一事实成为明示而非暗示。

编辑范围

可编辑的范围由单一可信来源确定,控制台只在其中写入。user · language · quality · git-convention · git-strategy · llm 通过 typed 校验路径保存,workflow 与 report 通过保留文件内注释与行序的 seam 保存。机器与状态章节以及大型策略文件属于排除集,新的章节在被明确登记之前默认拒绝。各章节的键在 config 章节参考 中说明。

安全模型

仅回环。 控制台只绑定到 127.0.0.1,因此远程主机无法访问。不过回环端口并不按账户隔离,同一台机器上登录的其他账户仍然可以连接这个端口。

没有数据库。 不额外启动 DB。读写的取值全部位于当前项目的 .moai/ 之下。

没有认证。 没有登录或令牌层。绑定到回环能挡住远程主机,但挡不住同一台机器上的其他账户。在多人共用的机器上,控制台运行期间这些账户也能连接它。

不执行命令。 观测区域拒绝 GET 以外的方法,任何界面都不会在服务端执行命令。SPEC 的 status 迁移也不由控制台完成 — 迁移的所有者是各阶段的管理代理。

对所有请求的 Host 检查。 包括静态文件在内的所有路由,无论方法如何,只要 Host 头不是回环名称(localhost、127.0.0.1、[::1],是否带端口均可)或根本没有 Host 头,都会以 403 拒绝。仅绑定回环并不能阻止 DNS 重绑定 —— 另一个站点上的页面可以让浏览器连接到 127.0.0.1,同时把攻击者的域名带在 Host 里,这样浏览器就会让该页面读取响应。同源(Sec-Fetch-Site)检查仍然只适用于改变状态的请求。

信息
仅回环是没有认证的前提。通过反向代理或 0.0.0.0 绑定向外暴露的配置不受支持。若需要远程查看,请用 SSH 隧道转发本地端口。使用 SSH 隧道时,浏览器仍会以 localhost 地址打开控制台,因此在这项检查下也能继续使用。不过这一点是在模拟端口转发、而非真实 SSH 服务器的测试环境中确认的,请将其视为预期行为,而非已验证的保证。

四语言界面

界面语言从导轨底部的选择器中选取 English · 한국어 · 日本語 · 中文 之一。所选语言会保留在浏览器中,下次打开时从首次渲染起即生效。它与 docs-site 的四语言文档使用同一套语言集合,因此可以用同一种语言并排阅读界面与文档。

启动与停止

在项目目录中运行 moai web 会绑定 127.0.0.1:3041 并自动打开浏览器。

标志默认值行为
--port <int>3041要绑定的回环端口
--no-openfalse关闭浏览器的自动打开
--no-reusefalse不回收占用端口的陈旧 moai 实例,直接以冲突结束

停止方式是在终端按 Ctrl+C,或使用导轨底部的退出按钮。详细行为请参阅 CLI 参考 — moai web。

相关文档