企业官网建设流程全解析

• 人工智能
• AI Agent
• AI 应用
• 前端
• 后端
• 即时通讯
• 交互助手
• 工具调用

holaOS 的应用构建 Agent 并非通用软件生成器：一个 App 只有完成注册、被运行时识别、托管进程启动并上报ready: true，才真正算构建成功。本文基于仓库内设计文档 docs/plans/2026-05-09-workspace-app-builder-deterministic-tools.md，系统阐述"确定性工具层（deterministic tool surface）"的动机、工具划分原则、完整 v1 工具面、行为约束与分阶段落地路线，并结合runtime/api-server的实际实现（scaffold / register / ensure_running / get_status / get_ports 等已落地）说明这些工具在真实运行时中的执行语义。读完本文，你将掌握 holaOS 如何把"模型自由设计 + 平台确定性操作"拆成两层，以及每个工具对应的 HTTP 端点、请求参数、失败语义与底层状态来源。

0. 状态与决策摘要

该文档是一份设计草案（status: draft），核心决策为：

• 应用 UI、工作流与领域逻辑保持模型驱动（model-driven），不改为工具；
• 工作区契约类操作抽为确定性工具（deterministic tools）；
• 让 Agent 构建的是工作区应用（workspace apps），而不是通用软件项目；
• 首批工具围绕五个方向优化：应用脚手架（scaffolding）、注册（registration）、生命周期控制（lifecycle control）、就绪验证（readiness verification）、工作区数据检查（workspace data inspection）。

文档的定位不是取代 "vibe coding"，而是"把 vibe coding 中平台关键环节的猜测性工作移除"。

从当前仓库源码看，该方向已从草案演进到实质落地：runtime/api-server/src/runtime-agent-tools.ts中已实现scaffoldWorkspaceApp、registerWorkspaceApp、getWorkspaceAppStatus、getWorkspaceAppPorts、ensureWorkspaceAppsRunning、buildWorkspaceApp等方法，并在runtime/api-server/src/app.ts中暴露为 HTTP 能力端点（详见下文第 4、5 节）。

1. 为什么需要确定性工具层

holaOS 应用生成与通用应用生成不是同一个问题。

通用生成器可以停在"文件写完、dev server 能跑、浏览器预览能渲染"。holaOS 应用构建不能停在这里，成功标准是：

• 应用已在工作区中注册（写入workspace.yaml）；
• 运行时识别该应用；
• 托管应用进程成功启动；
• 应用上报ready: true；
• 应用在需要时正确参与工作区数据、MCP、集成（integrations）与输出（outputs）。

差异的根源在于：模型目前被要求即兴编写本应是确定性的平台胶水（platform glue）。文档列举了把太多内容留给自由生成导致的典型失败：

• 应用文件写好了，但workspace.yaml没有更新；
• 应用在独立预览中正常，却从未成为受管理的（managed）工作区应用；
• 应用代码被修改，但正在运行的托管进程从未重启，继续提供旧代码；
• Agent 凭空发明第二个集成，而不是复用已安装应用的数据；
• Agent 猜测共享数据库的使用方式，而不是遵循工作区契约。

这些不是创造力失败，而是契约失败（contract failures），因此正是确定性工具的候选对象。

源码佐证：runtime/api-server/src/runtime-agent-tools.ts中的scaffoldWorkspaceApp（约 L8400-L8474）在检测到apps/<app_id>已存在且未传overwrite=true时会抛出409 / workspace_app_scaffold_exists；registerWorkspaceApp（约 L8476-L8599）在 manifest 文件不存在时抛出404 / workspace_app_manifest_not_found——这正是"失败要响亮、不要静默 best-effort"这一设计意图的实现体现。

2. 设计原则：确定性在外，灵活性在内

正确的分工是：

确定性工具负责（deterministic tools own）：

• 工作区注册（workspace registration）
• 托管生命周期控制（managed lifecycle control）
• 状态与就绪检查（status and readiness checks）
• 共享数据检查（shared data inspection）
• 集成声明校验（integration declaration validation）
• 输出发布辅助（output publishing helpers）

模型仍然负责（model owns）：

• 应用概念与产品形态
• 页面与 UI 设计
• 工作流与交互设计
• 领域专属业务逻辑
• 自定义分析逻辑
• 满足平台契约后的应用内部代码

这样既保留模型的创造力，又系统性减少重复的平台性错误。该原则与同期架构文档 docs/plans/2026-05-09-universal-block-package-architecture.md 中"strict outside, flexible inside"的思路一致：平台在身份、持久化、绑定、权限、执行边界、版本化上严格，在渲染、交互设计、领域逻辑上灵活。

3. 抽取准则：什么该变成工具

把一个行为抽成确定性工具，当它满足：

1. 跨大多数应用重复出现（Repetitive across most apps）；
2. 容易做到"几乎正确"但出错代价高（Easy to do almost-right but costly to get wrong）；
3. 创造性价值低（Low in creative value）；
4. 平台耦合度高（High in platform coupling）；
5. 易于用清晰的输入/输出契约描述（Easy to describe with a clear input/output contract）。

不应抽取为确定性工具的行为主要是：

• 产品设计
• 呈现设计（presentation design）
• 领域推理
• 应用专属逻辑
• 一次性编排（one-off composition）

换言之：凡是模型明显更有价值的地方，工具层只应支撑其推理，而非替代。

4. 应该变成工具的能力清单

4.1 工作区契约工具（最高优先级的第一批工具）

落地现状（源码证据）：workspace_apps_scaffold、workspace_apps_register、workspace_apps_get_status已实现并注册为运行时能力。对应 HTTP 端点见 app.ts：

• POST /api/v1/capabilities/runtime-tools/workspace-apps/scaffold
• POST /api/v1/capabilities/runtime-tools/workspace-apps/register
• GET /api/v1/capabilities/runtime-tools/workspace-apps
• GET /api/v1/capabilities/runtime-tools/workspace-apps/:appId/status

scaffold 实际生成的受管文件清单（runtime-agent-tools.ts）：

• app.runtime.yaml
• package.json
• tsconfig.json
• src/server.ts

registerWorkspaceApp通过updateWorkspaceApplications幂等地写入workspace.yaml：若app_id、config_path、lifecycle与现有条目完全一致则不改写（changed: false），否则新增或更新，并返回registered: true（runtime-agent-tools.ts）。

4.2 生命周期工具（消除代价最高的运行时错配错误）

落地现状（源码证据）：ensureWorkspaceAppsRunning（runtime-agent-tools.ts）会先校验目标 app 均已注册（否则抛404），随后走lifecycle.ensureAllAppsRunning/ensureAppRunning，并在启动后对比 MCP registry 前后的 server 集合、执行 smoke tests、返回最新状态。HTTP 端点（app.ts）：

• POST .../workspace-apps/ensure-running
• POST .../workspace-apps/:appId/restart
• POST .../workspace-apps/:appId/restart-and-wait-ready
• POST .../workspace-apps/:appId/wait-until-ready
• GET .../workspace-apps/ports（单应用端口可通过app_id参数获取）

getWorkspaceAppPorts（runtime-agent-tools.ts）经由listWorkspaceApplicationPorts读取端口分配：默认按应用在workspace.yaml中的索引推导（http与mcp各有一个基准端口 + index，见 workspace-apps.ts，MCP 基准为 13100），当启用了嵌入运行时端口隔离时则改从 state store 分配/读取持久化端口（workspace-apps.ts）。

4.3 工作区数据检查工具（生命周期之后的下一批高价值工具）

4.4 集成与输出工具（有价值，但比生命周期与数据检查稍后）

4.5 可选的文件导入辅助工具

说明：上述workspace_data.*、workspace.outputs.*、文件导入类工具在本文所查的runtime/api-server源码中尚未发现对应实现，属于文档规划的后续阶段（Phase 2/3），引用时应以"规划"而非"已实现"来表述。

5. 推荐的 v1 工具面

如果只构建一个精简首集，应为以下 10 个工具：

1. workspace.apps.scaffold
2. workspace.apps.register
3. workspace.apps.ensure_running
4. workspace.apps.restart
5. workspace.apps.wait_until_ready
6. workspace.apps.get_status
7. workspace.apps.get_ports
8. workspace_data.list_tables
9. workspace_data.describe_table
10. workspace_data.sample_rows

这是"在移除最痛苦的契约失败、同时让产品/UI 生成保持灵活"前提下的最小集合。当前仓库的实现面与之高度重合：scaffold、register、ensure_running、restart、restart_and_wait_ready、wait_until_ready、get_status、get_ports、build、probe_endpoints 均已作为workspace_apps_*运行时工具注册（参见 claimed-input-executor.ts 中列出的运行时工具 id 集合，以及 app.test.ts 对 scaffold/build/restart_and_wait_ready/wait_until_ready 工具暴露的断言）。

6. 什么应保持模型驱动

以下内容不应在 v1 中变成确定性工具：

• "给我设计一个仪表盘布局"
• "把它做成一个干净的 KPI 页面"
• "做一个更好的 CSV 可视化器"
• "为团队进度跟踪选择正确的工作流"
• "写出对这个领域真正重要的分析逻辑"
• "决定这应该是一个 tracker、dashboard 还是混合工具"

这些正是模型创造价值的地方。工具层应支撑这种推理，而不是取代它。这也呼应了 2026-05-09-universal-block-package-architecture.md 的结论：平台拥有 pages、resources、bindings、permissions、runtime、versioning 等结构原语，而块（block）的实现、UI 与行为保持灵活——"一个扩展模型，多个包，强组合原语"。

7. 确定性工具的行为规则

这些工具默认应以工作区为锚（workspace-grounded），分四组规则：

7.1 作用域规则（Scope rules）

• 每个工具必须针对所选工作区执行；
• 不得静默作用于不同的工作区根目录；
• 结果负载中必须返回结构化的workspace id与app id。

源码佐证：所有workspace_apps_*处理函数都调用this.requireWorkspace(params.workspaceId)/requireAppBuilderRuntimeToolSession(...)，返回对象一律包含workspace_id与app_id字段（如 runtime-agent-tools.ts、L8709-L8734）。

7.2 真相规则（Truth rules）

• 状态工具必须报告运行时真相（runtime truth），而非推断真相；
• 就绪状态必须来自受管运行时状态，而非浏览器预览；
• 数据检查必须读取共享工作区 DB，而非应用本地猜测。

源码佐证：workspaceAppStatusEntry的状态来自运行时对注册条目的解析；getWorkspaceAppPorts读取的是workspace.yaml+ state store 中的端口分配；健康检查目标解析自 manifest 的healthchecks字段（mcp/api二选一，默认优先mcp，见 workspace-apps.ts）。

7.3 失败规则（Failure rules）

• 应用未注册时响亮失败（Fail loudly when the app is unregistered）；
• 运行时无法启动应用时响亮失败；
• 所需表缺失时响亮失败；
• 对平台关键操作不要静默"尽力而为"。

源码佐证：ensureWorkspaceAppsRunning在目标 app 未注册时抛RuntimeAgentToolsServiceError(404, "workspace_apps_empty" / "app not found")（runtime-agent-tools.ts）；scaffold目标已存在且未传 overwrite 时抛409；manifest 缺失时抛404。

7.4 幂等规则（Idempotency rules）

在合理范围内：

• scaffold应能检测已有文件，结构化地拒绝或更新；
• register应幂等；
• ensure_running应可安全重复调用；
• wait_until_ready超时应返回最新的已知结构化状态。

源码佐证：registerWorkspaceApp对app_id + config_path + lifecycle完全一致的条目直接返回changed: false，不写文件（runtime-agent-tools.ts）；scaffoldWorkspaceApp在overwrite=false时逐文件检查存在性并拒绝（runtime-agent-tools.ts）。

8. 示例：模型与工具的职责拆分

8.1 模型决定什么

用户请求：

用已安装的 Twitter 应用为我的 Twitter 帖子构建一个仪表盘。

模型职责：

• 决定这应该是一个工作区应用；
• 决定应复用已安装的 Twitter 数据；
• 决定第一版 UI 形态；
• 决定是否需要 MCP 工具；
• 决定是否需要应用自有表来存偏好或保存视图。

8.2 确定性工具做什么

工具职责（典型调用序列）：

1. workspace_data.list_tables
2. workspace_data.describe_table("twitter_posts")
3. workspace.apps.scaffold("twitter-dashboard")
4. 模型编写应用专属代码
5. workspace.apps.register("twitter-dashboard")
6. workspace.apps.ensure_running("twitter-dashboard")
7. workspace.apps.wait_until_ready("twitter-dashboard")
8. workspace.apps.get_ports("twitter-dashboard")
9. 模型在运行时托管端口上验证受管表面

这比要求模型自己即兴完成每一步平台操作要好得多。作为补充，仓库还提供workspace_apps_build（执行npm run build，支持timeout_ms参数，无 build script 时返回skipped: true / reason: "no_build_script"）与workspace_apps_probe_endpoints（探测应用端点）等增强工具，进一步压缩"模型猜测应用是否可用"的空间。

9. 为什么这对可靠性重要

该工具层从三方面直接改善应用构建体验：

9.1 更少的假成功完成（Fewer false-success completions）

Agent 不能再停在"文件写完了、预览能跑"，必须验证：

• 已注册（registered）
• 受管（managed）
• 运行中（running）
• 就绪（ready）

9.2 更好的工作区锚定（Better workspace grounding）

Agent 可以基于以下事实推理，而非假设：

• 实际安装的应用
• 实际的工作区表
• 实际的运行时应用状态

9.3 更低的提示词负担（Less prompt burden）

skill 不再需要用散文教每一个操作细节，可以聚焦于：

• 决策规则
• 何时使用哪个工具
• 哪些仍需要模型判断

这与仓库中 skill 能力的组织方式一致：agent-runtime-prompt.test.ts与agent-capability-registry.test.ts都在验证运行时工具 id（如workspace_apps_get_status）如何进入 agent 的能力清单与 prompt，说明工具面已被纳入 Agent 的运行时能力注册机制。

10. 建议的落地顺序

Phase 1（生命周期与注册先行）

• workspace.apps.scaffold
• workspace.apps.register
• workspace.apps.ensure_running
• workspace.apps.restart
• workspace.apps.wait_until_ready
• workspace.apps.get_status
• workspace.apps.get_ports

Phase 2（数据检查）

• workspace_data.list_tables
• workspace_data.describe_table
• workspace_data.sample_rows
• workspace_data.table_exists

Phase 3（集成校验与输出）

• workspace.apps.validate_integrations
• workspace.outputs.create
• workspace.outputs.update
• 可选文件导入辅助工具

从当前仓库看，Phase 1 的大部分已实现并进入运行时工具注册表；Phase 2/3 的workspace_data.*与workspace.outputs.*尚未在runtime/api-server中发现对应实现，属于规划中的后续阶段。

11. 结论与建议

不应把 holaOS 应用构建当作通用 vibe coding，而应视为：

• 模型驱动的应用设计（model-driven app design）
• 叠加在
• 确定性工作区操作（deterministic workspace operations）之上

最高价值的首批抽取对象是：

• 生命周期（lifecycle）
• 注册（registration）
• 就绪（readiness）
• 工作区数据检查（workspace data inspection）

其余内容可以在系统证明下一个最大的可靠性缺口之前继续保持灵活。配套的运行时契约参考：workspace-apps.ts（workspace.yaml读写、manifest 解析、端口分配、MCP registry 管理）、runtime-agent-tools.ts（工具实现）、app.ts（HTTP 端点），以及 workspace-apps.test.ts 与 runtime-agent-tools.test.ts 中的行为验证。

• 人工智能
• AI Agent
• AI 应用
• 前端
• 后端
• 即时通讯
• 交互助手
• 工具调用