RFC Proposal: 新增 `neocode-gateway` 发布物并固化角色边界、运维契约与安全基线

[pionxe]

1. Summary

• 当前发布仅提供 neocode 单一二进制，客户端入口与网关服务端入口混在同一产物中。
• 本提案引入双产物发布：neocode（客户端）+ neocode-gateway（服务端）。
• 本提案同时固化三类契约：CLI 角色边界、运维/发布命名稳定性、安全默认值与验收测试。

2. Background and Problems

• 观察事实：internal/cli/root.go 在根命令注册了 gateway 子命令，说明当前“单二进制多角色”是既有模式。
• 观察事实：.goreleaser.yaml 当前仅构建 ./cmd/neocode/main.go，二进制名仅 neocode。
• 观察事实：scripts/install.sh 与 scripts/install.ps1 默认只安装 neocode / neocode.exe。
• 观察事实：internal/tui/services/gateway_rpc_client.go 存在基于当前可执行文件的自动拉起网关逻辑（exec.Command(executablePath, "gateway")）。
• 观察事实：网关默认监听地址与校验机制已偏保守（回环监听）。
• 问题：第三方仅需网关时仍需分发“含客户端语义”的二进制，服务端组件边界不清晰，审计与运维解释成本高。
• 问题：若仅“多一个可执行文件”但不定义一致性测试与命名契约，后续高概率出现双入口行为漂移与发布脚本断裂。

3. Goals

• 提供官方 neocode-gateway 发布物，覆盖与 neocode 相同平台矩阵。
• 明确 CLI 角色边界：neocode-gateway 仅承担网关服务端职责，不承载 TUI 入口语义。
• 保证双入口共享执行内核，不复制逻辑，并具备一致性测试。
• 固化安装与资产命名契约，支持显式 flavor 选择并保持脚本长期兼容。
• 将网关默认安全基线与最小可接入链路纳入 CI 自动验收。

4. Non-Goals

• 不修改 Gateway 协议与 JSON-RPC 方法语义。
• 不移除现有 neocode gateway 子命令。
• 不在本提案内引入 SDK 或多租户授权模型重构。

5. Design

5.1 CLI 角色边界契约

• 新增 cmd/neocode-gateway/main.go，产出独立服务端二进制。
• neocode-gateway 仅暴露网关服务相关命令与参数。
• neocode 保持现有客户端主入口与 gateway 子命令兼容行为。

5.2 入口分离、执行内核共享

• 通过 internal/cli 抽取网关命令构建与执行路径复用点。
• neocode gateway 与 neocode-gateway 调用同一套参数解析与启动函数。
• 禁止复制一份“平行网关启动逻辑”。

5.3 默认安全基线

• neocode-gateway 默认监听维持保守策略（本地回环）。
• 对外暴露能力必须显式配置，并在文档中标注风险与最小鉴权/ACL模板。
• 认证与 ACL 默认策略保持最小权限原则。

5.4 发布与安装契约

• 在 .goreleaser.yaml 增加 neocode-gateway build。
• 资产命名、平台后缀、checksum 输出规则形成稳定约定并写入文档。
• 安装脚本支持显式参数：--flavor gateway（默认保留现有 flavor）。

5.5 CI 与可接入验收

• CI 除构建外，新增 gateway-only 冒烟链路：
  • 启动 neocode-gateway
  • 探活（/healthz / /version）
  • 最小 /rpc 或 /ws 请求校验
  • 进程退出与资源清理
• 增加双入口一致性测试：关键参数下响应语义、错误码、关键日志字段一致。

6. Acceptance Criteria

• Release 产物中同时存在 neocode 与 neocode-gateway，平台矩阵一致。
• neocode-gateway 不提供 TUI 启动语义，仅提供网关服务端能力。
• neocode gateway 与 neocode-gateway 在同参场景下行为等价：
  • 关键响应语义一致
  • 错误码一致
  • 关键日志字段一致
• 默认安全基线具备自动化测试：
  • 默认监听地址策略
  • 鉴权缺失时失败行为
• 安装链路具备回归测试：
  • flavor 选择
  • 下载 URL 组装
  • checksum 校验流程
• 文档补齐两类运维内容：
  • 部署拓扑建议（本地内嵌网关 vs 独立网关服务）
  • 升级与回滚步骤

7. Dependencies and Impact

• 受影响模块：
  • cmd/
  • internal/cli/
  • .goreleaser.yaml
  • scripts/install.sh
  • scripts/install.ps1
  • README.md
  • 网关运维与接入文档
• Assumption: 第三方接入方存在“仅部署网关”的高频场景。
• Assumption: 双入口一致性测试需新增专门测试文件，现有测试不足以覆盖该类回归。

8. Implementation Changes

• 新增：cmd/neocode-gateway/main.go
• 调整：internal/cli 网关命令构建与执行路径，形成共享执行内核
• 调整：.goreleaser.yaml 增加 gateway-only 构建与产物命名规则
• 调整：安装脚本引入 --flavor gateway 并校验资产/checksum
• 新增：双入口行为一致性测试与 gateway-only 冒烟测试
• 调整：README 与网关文档新增部署拓扑、最小安全模板、升级回滚说明

[pionxe]

@xgopilot 请你针对该issue，提出你独特地见解与意见！

[fennoai]

对 RFC #420 的建议

我支持“双产物发布（neocode + neocode-gateway）”，方向正确。我的核心意见是：该提案不只是“多一个二进制”，而是应借机把“角色边界 + 运维契约 + 安全默认值”一次性固化下来。

我认为最关键的 5 点

1. 角色边界要体现在 CLI 契约里，而不只是命名
   neocode-gateway 应仅保留网关相关命令与参数，避免任何 TUI 入口语义。这样第三方审计可以直接把该二进制视为“服务端组件”，减少解释成本。

2. 避免实现分叉：做“入口分离”，不做“逻辑复制”
   建议把 gateway 启动参数解析与执行路径收敛到同一套内部函数，由 neocode gateway 与 neocode-gateway 共同调用，并增加“行为一致性测试”（同参同结果）。

3. 把“最小权限”前移到默认行为
   neocode-gateway 默认监听应偏保守（例如仅本地回环），对外暴露需要显式配置；同时在文档中明确 ACL/鉴权最小配置模板，避免用户把 Gateway-Only 误当“默认可公网暴露服务”。

4. 安装与资产命名要考虑脚本长期兼容
   install 脚本的 flavor 参数建议显式化（如 --flavor gateway），并对资产命名、checksum、平台后缀制定稳定规则，避免后续发布改名导致自动化脚本断裂。

5. CI 验收建议从“可构建”提升到“可接入”
   除了 build 成功，至少要有 gateway-only 冒烟链路：启动进程 -> 探活 -> /rpc 或 /ws 最小请求 -> 退出清理。这样才能覆盖你提案里的“第三方接入可用性”目标。

建议补充到 Acceptance Criteria 的条目

• neocode gateway 与 neocode-gateway 在关键参数下行为等价（含错误码与日志关键字段）。
• neocode-gateway 默认安全基线有自动化测试（监听地址、鉴权缺失时的失败行为）。
• 安装脚本 flavor 选择、下载 URL、checksum 校验均有回归测试。
• 文档新增“部署拓扑建议”（本地内嵌网关 vs 独立网关服务）与“升级回滚步骤”。

风险提醒

• 最大风险不是代码复杂度，而是“双入口后行为漂移”。
• 解决手段是“共享执行内核 + 一致性测试 + 发布命名稳定策略”，而不是额外抽象层。

本次执行说明

已完成需求分析与建议输出；未进行代码修改、未创建 PR。

View job run

[pionxe]

@xgopilot 我根据你的意见进行了更新，我请你针对该issue，再提出你独特地见解与意见！如果无需再度更改，请你回复我“可落地执行！”

[fennoai]

结论

当前这版 RFC 已覆盖我上一轮提出的关键点（双产物、角色边界、共享执行内核、一致性测试、安全默认值、安装/发布契约、CI 冒烟验收）。

可落地执行！

补充建议（不阻塞本 RFC）

1. 建议在实现阶段补一个“网关可执行发现顺序”约定（例如：优先外部 neocode-gateway，回退 neocode gateway），避免客户端自动拉起在不同安装形态下出现行为分叉。
2. 建议在一致性测试中固定“日志关键字段白名单”（如 listen addr、auth mode、request id），防止后续日志格式微调导致回归测试不稳定。

本次执行说明

已完成二次评审与结论输出；未进行代码修改。

View job run