agent space preview 是 workspace 构建与调试阶段的静态结构校验界面，仅展示配置文件中模型、知识、skill、workflow 的绑定关系，不承载运行时状态，用于提前发现知识库未绑定、skill 参数错位或 workflow 节点断连等设计态错误。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
Agent Space Preview 是 Workspace 在构建与调试阶段的可视化快照，它不承载运行时状态，仅反映当前配置下资源绑定关系的静态结构。缺少这层预览，团队常在发布后才发现知识库未绑定、Skill 参数错位或 Workflow 节点断连。
Preview 本质是 Workspace 的结构校验界面
打开 Agent Space Preview 时，系统会扫描当前 Workspace 目录下的所有配置文件（agent.yaml、skills/、knowledge/、workflows/），提取模型路由、知识来源、Skill 输入输出字段、Workflow 分支条件等元信息，生成一张依赖图。这张图不执行任何工具调用，也不读取实时数据库内容。
这一步操作起来很简单，直接点击控制台右上角“Preview”按钮即可加载，但加载失败往往意味着 workspace/skills/ 下某个 Markdown 技能文件语法错误，或 workflows/order_approval.json 缺少 required 字段。
Preview 和 Workspace 的数据流向
Workspace 是实际运行环境，所有 Agent 执行都基于其磁盘文件；Preview 只读取这些文件，不做任何写入。修改 workspace/knowledge/product_v3.md 后，Preview 页面刷新即显示新版本摘要；但若未提交 Git 或未触发重部署，线上 Agent 仍使用旧版缓存。
Preview 不同步运行时状态：比如某次 Workflow 执行中因超时中断，该状态不会出现在 Preview 中；它只展示“设计态”，不反映“运行态”。
用 Preview 发现三类典型绑定错误
方法一：检查知识库是否被正确挂载到 Agent
使用 Pi Coding Agent（@earendil-works/pi-coding-agent）进行 AI 辅助编程。Pi 是一个可扩展的终端编程助手，支持多种模块。
在 Preview 页面左侧选择目标 Agent → 查看 “Knowledge Sources” 标签页 → 确认列出的知识库路径与 workspace/knowledge/ 下真实目录名完全一致（包括大小写和下划线）。【路径名大小写不匹配会导致 RAG 检索始终返回空】
方法二：验证 Skill 是否接入 Workflow 节点
进入 “Workflows” 标签页 → 展开 checkout_process.yaml → 查看 payment_validation 节点 → 确认 skill_ref 字段值（如 validate_card_v2）能在 skills/ 目录下找到同名 .md 文件。若文件存在但 Preview 显示 “Not found”，说明该技能未在 skills/index.json 中注册。
方法三：定位模型凭据未生效问题
切换到 “Models” 标签页 → 检查 default_model 字段是否指向 workspace/models/ 下已配置的模型 ID；再点击右侧 “Routing Rules” → 查看规则中指定的凭据 scope 是否与 workspace/credentials/azure_openai_v2.json 中的 tenant_id 完全匹配。不匹配将导致调用时返回 401 错误，但 Agent 日志只报 “model unavailable”，不会提示凭据范围错位。
