server-distribution.cli-and-web

本文档说明 zcode 的命令行（CLI）、终端用户界面（TUI）与 Web 启动模式之间的入口分流规则。

Purpose and Scope

本页聚焦服务端分发入口如何根据命令行参数选择运行模式：无参数时进入 TUI、第一个参数为 --web 时启动 Web 模式、其他参数交由 Agent CLI 处理。

本文不展开 Web 服务内部路由、TUI 交互实现、Agent CLI 的具体命令语义或部署配置；当前已读取的源材料只确认入口分流行为，未提供这些子系统的实现细节。相关内容应由对应的独立文档覆盖。

Overview

zcode 的启动入口将命令行调用分为三类：

无参数调用：启动 TUI，适合交互式终端使用。
首个参数为 --web：启动 Web 模式，将运行交给 Web 侧入口。
其他参数：不被分流入口消费，而是交给 Agent CLI 处理。

这种分流方式把模式选择放在进程启动早期完成。--web 作为显式模式开关；没有模式开关时保留交互式默认行为；其他参数则保持 CLI 参数的原始语义，避免入口层重新解释 Agent CLI 的命令行协议。

Mode Dispatch

入口分流可以概括为以下决策顺序：

先检查是否存在命令行参数。
如果没有参数，选择 TUI。
如果存在参数，再检查第一个参数是否为 --web。
只有首个参数匹配 --web 时选择 Web 模式。
其他情况统一交给 Agent CLI。

需要注意的是，当前源材料只明确了“第一个参数为 --web”这一匹配条件；没有足够信息证明 --web 是否支持出现在其他位置、是否允许附加 Web 参数、或者 Web 模式如何处理后续参数。因此这些行为不应在本页中推断。

Core Flow

从可验证的行为看，入口层承担的是一次性的模式选择，而不是业务处理：

进程接收命令行参数。
入口根据参数数量和第一个参数进行判断。
入口选择 TUI、Web 或 Agent CLI 之一。
被选中的运行模式接管后续生命周期。

当前已读取的源材料没有提供各模式启动函数的名称、返回类型、异常处理、生命周期管理、并发模型或退出码约定，因此这些 API 与运行时细节暂无可靠的源代码依据。

Invocation Semantics

调用形态	选择的模式	已确认行为
`zcode`	TUI	无参数时进入 TUI
`zcode --web`	Web	第一个参数为 `--web` 时启动 Web
`zcode <其他参数>`	Agent CLI	其他参数交给 Agent CLI 处理

表中的 <其他参数> 仅表示“不满足前两种分流条件的参数集合”，并不代表某个已确认的具体命令或参数名称。

Design Boundaries

默认交互行为

将无参数调用映射到 TUI，使直接运行 zcode 时具有明确的交互式默认行为。当前资料没有说明 TUI 的初始化过程、终端检测或非交互环境下的处理方式。

显式 Web 开关

Web 模式需要通过首个参数 --web 显式选择。该规则将 Web 启动从默认路径中分离出来，避免普通无参数调用意外启动 Web 服务。

CLI 参数透传

不属于前两种情况的参数交给 Agent CLI 处理。由此可确认入口分流层至少保留了 Agent CLI 作为独立的参数处理边界；但当前资料没有说明参数是否原样透传、是否会剥离入口参数，或 Agent CLI 如何解析参数。

Usage Examples

当前源材料仅确认了调用规则，没有提供可安全摘录的源代码片段。因此本页不生成代码示例，也不虚构入口函数、参数签名或启动实现。

Configuration Options

当前已读取的源材料没有记录与该分流规则相关的配置键、环境变量、默认端口、监听地址或配置文件。实现细节不足，不能推断配置项及其默认值。

API Reference

当前资料没有提供公开 API、入口函数签名、返回值或异常声明。实现细节不在已读取源材料中，不能可靠地补充方法级 API 文档。

Failure Modes and Edge Cases

已确认的分流规则只覆盖参数分类，不足以确定以下边界行为：

--web 缺少后续参数时的处理方式；
--web 出现在第一个参数以外位置时的处理方式；
未知 Agent CLI 参数的错误响应；
Web 或 TUI 启动失败时的异常与退出码；
标准输入不是终端时是否仍然启动 TUI；
多次启动、信号处理和优雅退出行为。

这些行为需要进一步读取入口实现、Web 启动代码、TUI 初始化代码和 Agent CLI 解析代码后才能记录。

Operational Notes

运行模式的选择发生在命令行入口层，因此排查问题时应首先确认实际传入的参数列表及其顺序：尤其要确认 --web 是否确实位于第一个参数位置。若没有参数，应按 TUI 路径排查；若存在其他参数，应按 Agent CLI 路径排查。

当前资料没有提供 Web 端口、监听地址、日志、健康检查、资源限制或部署拓扑信息，因此本页不对 Web 服务的运维行为作进一步说明。

README.md：入口模式分流规则的已确认说明。

Source Limitations

本页基于当前已读取的 README.md 内容。源材料足以确认三路分流规则，但不足以提供可归属的代码片段、精确入口函数、完整调用链、配置项、错误处理或测试覆盖范围。后续若要扩展为实现级参考文档，应先读取实际入口文件，并交叉检查 Web、TUI 与 Agent CLI 的注册和调用关系。