feat(gateway): RFC#420 全量落地（双产物发布、统一启动内核、第三方接入文档与CI验收）#423
Merged
phantom5099 merged 18 commits into1024XEngineer:mainfrom Apr 24, 2026
Merged
feat(gateway): RFC#420 全量落地（双产物发布、统一启动内核、第三方接入文档与CI验收）#423phantom5099 merged 18 commits into1024XEngineer:mainfrom
phantom5099 merged 18 commits into1024XEngineer:mainfrom
Conversation
- 新增 gateway-only 可执行入口 neocode-gateway，并与 `neocode gateway` 复用同一启动内核 - 引入共享 launcher，固定发现顺序： NEOCODE_GATEWAY_BIN > PATH(neocode-gateway) > 回退 neocode gateway - 在 url-dispatch 不可达路径接入“先拉起后重拨”流程，限制为单次受控回退 - 增加结构化启动决策日志字段与白名单断言测试，降低双入口行为漂移风险 - 扩展发布与安装体系：goreleaser 双产物、install 脚本 flavor + dry-run + checksum 校验 - CI 增加 gateway-only 冒烟链路与安装脚本 dry-run 回归检查 - 补齐文档体系：RFC 设计、第三方接入指南、RPC API（XGO 风格）、错误字典、兼容性策略 - 增加基于 Go 结构体的 JSON 示例自动生成机制，输出 docs/generated 示例文件 测试： - go build ./... - go test ./internal/gateway/launcher ./internal/gateway/adapters/urlscheme ./internal/gateway/protocol ./scripts - go test ./internal/cli -run "TestNewGatewayStandaloneCommandPassesFlagsToRunner|TestNewGatewayStandaloneCommandRejectsInvalidLogLevel|TestGatewaySubcommandAndStandaloneCommandAreOptionEquivalent|TestExecuteGatewayServerUsesStandaloneCommand|TestGatewaySubcommandAndStandaloneCommandPropagateSameRunnerError" 关联：RFC#420
Codecov Report❌ Patch coverage is 📢 Thoughts on this report? Let us know! |
![fennoai[bot]](https://avatars.githubusercontent.com/in/1924301?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Collaborator
Author
|
@xgopilot 请你帮我解决冲突！同时解决review的问题！ |
结果已完成你这次提到的“review 问题”修复，并把改动推送到当前 PR 源分支 本地检查未发现 已完成事项
分支同步信息按 fork 流程同步创建了 fork 内 PR： |
Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: pionxe <148670367+pionxe@users.noreply.github.com>
Collaborator
Author
|
@xgopilot 请你帮我解决文件冲突！ |
已完成已处理并提交本 PR 与
已推送提交到你当前 PR 源分支：
|
Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: pionxe <148670367+pionxe@users.noreply.github.com>
Collaborator
Author
|
@xgopilot 请你帮我解决CI构建失败的问题！ |
已完成修复已定位并修复本次 CI 构建失败。 根因
导致 CI 在 修复内容已更新
验证结果本地已通过：
提交与推送
Fork 同步 PR |
Collaborator
Author
|
@xgopilot 请你详细阅读CI构建失败的原因！分析到底是哪里的问题！并给出你的解决方案，说明为什么！ |
Collaborator
Author
@xgopilot 请你解决！ |
处理结果已按你给出的根因定位完成修复，并已推送到当前 PR 分支 变更内容
本地验证
未执行项
|
Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: pionxe <148670367+pionxe@users.noreply.github.com>
Collaborator
Author
|
@xgopilot 请你帮我解决文件冲突问题！ |
已完成已处理你提到的“文件冲突”问题，并已推送到当前 PR 源分支 处理结果
实际修复内容
本地验证
额外同步
|
Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: pionxe <148670367+pionxe@users.noreply.github.com>
Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: pionxe <148670367+pionxe@users.noreply.github.com>
Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: pionxe <148670367+pionxe@users.noreply.github.com>
Collaborator
Author
|
@xgopilot 请你帮我解决文件冲突问题！ |
处理结果已按“解决文件冲突”完成排查与验证，当前这个 PR 分支没有可修复的文件冲突。 我做了以下检查：
补充说明：
如果你希望，我下一步可以直接按当前失败检查去定位并修复 CI 阻断点。 |
Collaborator
Author
|
@xgopilot 请你详细阅读CI构建失败的原因！分析到底是哪里的问题！并给出你的解决方案，说明为什么！最后帮我解决该问题！ |
Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: pionxe <148670367+pionxe@users.noreply.github.com>
Collaborator
Author
|
@xgopilot 请你将codecov/patch覆盖率提升至百分之九十五以上！ |
|
已完成一轮“提升 patch 覆盖率”的补测并已推送到当前 PR 头分支 本次改动
变更文件
已验证
说明：本地无法直接拿到 Codecov 的服务器端 patch 统计口径，但已针对本 PR 新增的网关入口与 launcher 关键未覆盖路径补齐测试，理论上会显著抬升 patch 覆盖率。如你希望，我可以继续按 Codecov 返回的具体未覆盖行再做第二轮定点补测。 |
Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: pionxe <148670367+pionxe@users.noreply.github.com>
Collaborator
Author
|
@xgopilot 请你将codecov/path覆盖率提升至百分之九十五以上！特别是internal/gateway/adapters/urlscheme/dispatcher.go！ |
已完成已按你的要求提升覆盖率，重点补齐了 结果
提交与推送
未做项
|
Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: pionxe <148670367+pionxe@users.noreply.github.com>
Collaborator
|
@xgopilot 批判性review整个PR，分析所有潜在风险点，找出所有漏洞，确保每个地方的修改不是退步的，方案上的设计也不能碎片化，更不能妥协式兼容或兜底旧代码，不许输出正向表扬 |
Collaborator
Author
|
@xgopilot 针对上述review的问题，请你详细分析问题所在及其原因，并思考如何合理解决！最后请你解决上述问题，并返回你的分析报告以及实施的方案报告给我！ |
Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: pionxe <148670367+pionxe@users.noreply.github.com>
fix(gateway): 对齐拉起契约并修复文档校验链路
Collaborator
Author
|
/review |
| }, nil | ||
| } | ||
|
|
||
| if resolved, err := resolveByLookup("neocode-gateway"); err == nil { |
There was a problem hiding this comment.
ResolveGatewayLaunchSpec 在自动拉起路径中直接信任 PATH 解析结果（neocode-gateway / neocode），这使 URL 调度路径具备执行环境中同名二进制的能力。建议至少增加一层约束（例如仅接受绝对路径配置、校验二进制来源/目录白名单、或在 fallback 场景中显式 opt-in），避免在不可信 PATH 下触发意外代码执行。
| @go run ./scripts/generate_gateway_rpc_examples | ||
| @git diff --exit-code -- docs/reference/gateway-rpc-api.md | ||
| @go run -tags gatewaydocgen ./scripts/generate_gateway_rpc_examples.go | ||
| @git diff --exit-code -- docs/generated/gateway-rpc-examples.json |
There was a problem hiding this comment.
docs-gateway-check 现在只校验 docs/generated/gateway-rpc-examples.json，不再覆盖面向用户的 RPC 文档文件（例如 docs/gateway-rpc-api.md / 旧 reference 文档）。这会让“生成产物正确但主文档描述过期”无法在 CI 被拦截。建议把用户可读文档的一致性校验也纳入该目标。
| return nil | ||
| } | ||
| if !nowFn().Before(deadline) { | ||
| return fmt.Errorf("gateway did not become reachable within %s", defaultGatewayLaunchTimeout) |
There was a problem hiding this comment.
waitGatewayReady 的错误文案固定写 within 3s，但实际 deadline 可能被更短的 ctx.Deadline() 覆盖（见上文 deadline 计算）。当上游设置更短超时时，日志会误导排障。建议在报错中输出实际生效的等待窗口（deadline-now 或上下文截止时间）。
Collaborator
Author
|
/simplify |
Completed已按你的要求完成：读取历史评论、评估未闭环 review 点并落地修复，然后使用 Implemented Changes
Validation
Commit & Push
Not Done
|
Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: pionxe <148670367+pionxe@users.noreply.github.com>
fix(gateway): close unresolved review risks and simplify
Collaborator
Author
|
@xgopilot 请你帮我解决冲突问题！ |
处理结果已完成这次“解决冲突”处理，并已推送到当前 PR 源分支
已执行验证
|
Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: pionxe <148670367+pionxe@users.noreply.github.com>
Generated with [codeagent](https://github.com/qbox/codeagent) Co-authored-by: pionxe <148670367+pionxe@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
背景
本 PR 按 RFC #420 既定路线进行严格全量落地，目标是：
neocode现有行为不变；neocode-gateway作为 Gateway-Only 官方发布物；主要变更
1) 双产物与入口边界
cmd/neocode-gateway独立入口（仅网关服务语义，不含 TUI 主入口）。neocode gateway与neocode-gateway共享参数归一化与执行路径，避免逻辑复制。2) 共享 launcher + 自动拉起契约
NEOCODE_GATEWAY_BIN>PATH neocode-gateway>neocode gateway。url-dispatch网关不可达路径接入“拉起后重拨”，且仅允许一次受控回退。3) 可观测性与一致性防漂移
launch_mode、resolved_exec、listen_address、auth_mode。4) 发布、安装与命名稳定
goreleaser增加neocode-gateway构建与独立资产命名规则。install.sh/install.ps1增加full|gatewayflavor 与dry-run。5) CI 验收增强
启动进程 ->
/healthz->/rpc最小未鉴权请求（预期失败）-> 退出清理。6) 文档全量补齐
gateway.run与gateway.bindStream双向交互）。7) 文档一致性机制
go generate ./internal/gateway/protocoldocs/generated/gateway-rpc-examples.json，降低“文实不符”风险。测试与验证
go build ./...go test ./internal/gateway/launcher ./internal/gateway/adapters/urlscheme ./internal/gateway/protocol ./scriptsgo test ./internal/cli -run "TestNewGatewayStandaloneCommandPassesFlagsToRunner|TestNewGatewayStandaloneCommandRejectsInvalidLogLevel|TestGatewaySubcommandAndStandaloneCommandAreOptionEquivalent|TestExecuteGatewayServerUsesStandaloneCommand|TestGatewaySubcommandAndStandaloneCommandPropagateSameRunnerError"风险与回滚
主要风险
缓解措施
回滚策略
healthz+/rpc最小请求重新验收；neocode gateway子命令路径。关联
neocode-gateway发布物并固化角色边界、运维契约与安全基线 #420