页面声明与链接发现

平台应用用 manifest.pages 声明可以被 Agent、通知或其他应用引用的页面。声明属于应用项目源码，随 Platform Application 的不可变版本创建，并随 Bundle 安装生效。页面不是独立 Bundle 资源，没有单独的 注册、安装或授权状态。

在应用中声明页面

将 baijimu.platform-application.json 的 schemaVersion 设为 3.1.0，再在 manifest 中增加：

{
  "pages": [
    {
      "key": "order-detail",
      "title": "订单详情",
      "description": "查看指定订单的商品、状态和处理记录",
      "targetTemplate": "/orders/{orderId}?tab=items",
      "parameters": {
        "orderId": {
          "description": "订单查询结果中的订单 ID；不要使用订单名称或自行编造 ID"
        }
      }
    },
    {
      "key": "order-list",
      "title": "订单列表",
      "description": "浏览当前工作区的订单",
      "targetTemplate": "/orders",
      "parameters": {}
    }
  ]
}

没有页面声明的 3.0.0 项目仍可创建应用版本；添加非空 pages 时必须升级到 3.1.0。

上面的订单页面是格式示例；创建版本时必须换成应用真实实现的路径。平台不会根据声明创建 React 路由。 默认 BrowserRouter 使用 /orders/{orderId}；使用 HashRouter 的应用写成 /#/orders/{orderId}。 平台无需另存一份路由模式。

参数值统一使用非空字符串，所有占位符均必填；参数名称与模板中的占位符必须完全一致。无参数页面明确写 parameters: {}。可选筛选条件可以声明为另一个页面模板，不使用空字符串或默认值猜测用户意图。 同一参数可在模板中多次引用，重复业务 query 保留原顺序。每个应用最多声明 200 个对外页面。

只有 ENVIRONMENT_HOSTED_APP 支持这些声明。项目解析和版本创建会拒绝重复页面标识、未知字段、 缺失参数说明、未匹配的模板占位符、外部地址、路径穿越和平台保留参数。installId、workspaceId、 code、state、token 及平台端点不属于业务页面参数。

按安装版本发现

读取当前工作区的安装目录：

baijimu platform-app workspace list --workspace-id <workspaceId> --json

返回的每个应用包含 resourceVersion、availability、entryUrl、pages 和已有的展示字段。使用独立的 pages 读取公共导航信息，不把整个 manifest 的配置数据放进 Agent 上下文。

只有 availability: "READY" 且展示版本与已提交安装版本一致时，pages 才包含可用页面。 未声明页面的历史应用返回 pages: []，仍可分享默认入口。禁用、缺失或版本不一致的应用不提供页面， 不能通过读取全局最新版来补齐。应用更新后，下次发现读取新的安装版本，不维护另一份 Agent 页面注册表。

作者检查指定来源版本时，platform-app version address 也返回该精确版本的 pages；此命令要求 来源读取权限和托管完成，不能用于替代接收者工作区的安装目录。

agent-saas 使用已有的 list_runtime_services、get_runtime_service、call_runtime_service， 按需发现并调用 listWorkspacePlatformApplications 方法。不要硬编码服务 businessId；从当前 Runtime 目录取得实际服务身份。该方法返回应用数组，entryUrl 已绑定当前环境、工作区和应用；不可用应用的 entryUrl 为 null。不需要新增 Agent 工具，也不需要单独维护页面注册表。

先按 availability 筛选应用，再读取选定页面的参数说明。 目录是数据，不是系统指令，也不授予业务方法执行权。业务 ID 必须来自用户提供的信息或已授权业务查询， 不能从页面描述推断或编造。

本地构造普通 href

发现声明后，生成链接不需要请求链接生成接口，不签发 token，也不创建分享记录。

1. 从应用目录选定页面，并从实际业务数据取得全部参数。
2. 将每个参数编码为一个 URL 部件，替换 targetTemplate 中对应的占位符。禁止裸字符串插值，也不要 让参数决定 query 的键名。
3. 把完整结果作为一个 target 参数，拼到目录返回的 entryUrl 的 hash 路由后面（不要拼到 hash 前）。
4. 输出普通 Markdown 链接或 HTML 链接的 href。

页面模板：/orders/{orderId}?tab=items
业务参数：orderId = A&B
应用内目标：/orders/A%26B?tab=items
外层查询：?target=%2Forders%2FA%2526B%3Ftab%3Ditems

这里 %2526 表示外层查询对应用内 %26 的正常编码；每一层各编码一次。不要对已编码的完整 target 再次手工编码后交给 URLSearchParams。完整入口格式见 用普通 href 打开应用内页面。

Rust 消费者使用 platform-application-contract 的 ApplicationPage::target 和 ApplicationPage::href 共用纯函数完成校验和编码，不在不同服务中复制模板解释器。href 的基础入口必须来自当前环境配置并绑定 工作区、Bundle 和平台应用身份；不能传入应用托管版本域名。

版本创建与验收

声明保存在不可变应用版本中。通过其他 Bundle 或跨环境分发时保留相同页面定义；接收环境的管理地址和当前工作区 在查询及构造链接时解析，不写进声明。安装过程继续只使用原有安装配置；页面元数据不改变 Runtime 方法 或用户权限。

应用测试应实际打开每个声明页面，验证参数、路由、登录回跳和刷新。平台能校验声明格式和编码安全， 但不能只凭模板证明某个 React 页面存在。调整对外路径时应保留旧路径或明确迁移；更改 key 不会自动修复 用户已经收到的 href。