这里的「内置 AI」指的是 ModPilot 应用里的 AgentLoop（/agent/chat 那条链路），不是 Cursor 里的 coding agent。

实际会进内置 AI 上下文的文档

只有一份仓库文档被代码读入并拼进 system prompt：

• docs/agent_workflow.md
  在 ModPilot/app/agent/prompts.py 里启动时整文件读入，再由 build_system_prompt() 按标题抽取片段注入，主要包括：Global Behavior Rules、Pipeline State Assessment Protocol、Phase Sequence、Phase 1–3 预处理块、Phase 3.5 / 4A / 4B / 5 / 6 等。
  进入 NEGOTIATING 阶段时，build_phase_prompt() 还会从同一份 agent_workflow.md 里再切当前 phase 的章节，作为 [Phase instructions] 放进对话。

路径在代码里是相对 prompts.py 解析到仓库根的 docs/agent_workflow.md（见 prompts.py 第 17–20 行附近的 _WORKFLOW_PATH）。

额外注入（不是 markdown 文档）

• physics_presets 字典（若启动时传入）：作为「Physics Presets Reference」拼在 system prompt 末尾（build_system_prompt 注释里写的 E19）。当前 main.py 里创建 AgentLoop 时未传该参数，则这一段不会出现，除非别处改过。
• 错误处理：error_handler.py 里固定的 _ERROR_SYSTEM、_CLASSIFY_SYSTEM 字符串，以及 build_error_prompt() 拼出的 user 内容——不是读 AGENTS.md / CLAUDE.md。

内置 AI 不会自动读这些

README.md、AGENTS.md、CLAUDE.md、docs/design.md、docs/backlog.md、docs/plan.md、docs/plugin_api.md 等 没有在 AgentLoop / prompts.py 里被加载；它们是给人和 IDE 里的 agent 用的规范，不等于 ModPilot 内置模型的知识库。

若你希望内置 AI 也遵守某份设计文档，需要像 agent_workflow.md 一样在 prompts.py（或等价配置）里显式加载或摘要注入。

ai是怎么知道当前是哪个Phase的

内置 ModPilot AI 并不直接读 Python 里的 _phase_idx；“当前在哪个 Phase”对模型来说是推断出来的，来源是下面几条链路。服务端用 _phase_idx + _PHASE_SEQUENCE 维护权威进度，并在部分回复里把进度写回对话。

1. 服务端维护的权威状态

AgentLoop 用整数 _phase_idx 指向固定列表 _PHASE_SEQUENCE（setup_validate → setup_import → phase_1 … → phase_6）。current_phase 就是 _PHASE_SEQUENCE[self._phase_idx]：

_PHASE_SEQUENCE: list[str] = [
    "setup_validate",   # SetupValidateScene
    "setup_import",     # SetupImportMHWilds
    "phase_1",
    "phase_2",
    "phase_3",
    "phase_35",
    "phase_4a",
    "phase_4b",
    "phase_5",
    "phase_6",          # BatchExport runs RE Mesh Tools cleanup internally before export
]

    def current_phase(self) -> str | None:
        if self._phase_idx >= len(_PHASE_SEQUENCE):
            return None
        return _PHASE_SEQUENCE[self._phase_idx]

2. 模型从对话里“知道”进度的方式

（1）成功且会推进 phase 的工具
advances_phase 为 True 时，工具返回里会写明刚完成的那一槽的 id（注意：是 completed 那一格，然后内部才把 _phase_idx +1）：

            if tool.advances_phase:
                completed = _PHASE_SEQUENCE[self._phase_idx]
                self._phase_idx += 1
                self._on_phase_advance()
                return f"Phase {completed} completed. Scene diff: {diff}", None
            else:
                return f"Tool {tool_name} succeeded (sub-step, phase not advanced). Result: {diff}", None

所以模型靠 global_history 里上一条 tool_result 的 “Phase xxx completed” / “phase not advanced” 对齐“做到哪一步了”。

（2）System prompt 里的全局流程
build_system_prompt() 会从 agent_workflow.md 抽出 Phase Sequence 以及各 phase 说明（prompts.py 里写得很明确：故意包含全部 phase，避免恢复会话时索引和上下文不一致）。模型因此始终有一份完整顺序表，用来对照 tool 结果推理“下一步该谁”。

（3）用户跳过失败 phase 时
会显式出现下一槽名称：Continuing to {self.current_phase}。

            case "skip":
                skipped = self.current_phase or "unknown"
                self._skipped_phases.add(skipped)
                self._phase_idx += 1
                self._on_phase_advance()
                ...
                return warning + f" Continuing to {self.current_phase}."

（4）NEGOTIATING 路径（若启用）
若某 phase 在 _NEGOTIATING_PHASES 里，进入协商态时会把 build_phase_prompt(self.current_phase) 塞进 phase_history 的 [Phase instructions]。当前代码里 _NEGOTIATING_PHASES 是空集合，所以这条路径实际上基本不会用到：

_NEGOTIATING_PHASES: frozenset[str] = frozenset()
# All phases run in RUNNING_PHASE so the LLM always has tool schemas visible.

3. 重要细节：没有“按 phase 裁剪工具列表”

_build_tool_list() 会把已注册的全部 phase 工具 + 查询工具都交给模型，没有按 _phase_idx 只开放当前步的工具。因此“当前 phase”对 API 来说不是通过 tool 可见性表达的，而是 workflow 文档 + 历史 tool 结果 + 模型遵守顺序的意愿。

一句话：真实现状在 AgentLoop._phase_idx；模型主要靠 system 里的全流程说明 + 每次 tool 返回里的 Phase … completed / phase not advanced（以及跳过时的 Continuing to …）来对齐自己处于流水线哪一段。 若你希望模型每轮都“硬绑定”当前 phase，需要在发 LLM 前额外注入一行 Current phase: … 或按 phase 过滤 tools（当前实现未做）。