-
Notifications
You must be signed in to change notification settings - Fork 7
feat(gateway): RFC#420 全量落地（双产物发布、统一启动内核、第三方接入文档与CI验收） #423
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
phantom5099
merged 18 commits into
1024XEngineer:main
from
pionxe:release/v2.0-split-build
Apr 24, 2026
Merged
Changes from all commits
Commits
Show all changes
18 commits
Select commit
Hold shift + click to select a range
800967e
feat(gateway): 落地 RFC#420 双产物发布与第三方接入契约
pionxe fa8d483
fix(gateway): 修复回滚重拣后冲突代码与文档生成脚本构建冲突
pionxe 083d76a
fix(cli): restore UTF-8 Chinese comments in gateway commands
xgopilot 7885f7b
chore: resolve merge conflicts with main
xgopilot 06aa0f7
fix(makefile): align gateway docs check with generated artifact
xgopilot 222f2df
fix(conflict): resolve Makefile merge conflict with main
xgopilot d5633b7
fix(conflict): align gateway doc generator path with origin main
xgopilot 487b323
fix(conflict): align docs reference api file with origin main
xgopilot 891823b
fix(docs): regenerate gateway rpc reference examples
xgopilot a519771
Merge branch 'main' into release/v2.0-split-build
pionxe f461648
test(gateway): improve patch coverage for launcher entry paths
xgopilot 387ce5c
test(gateway): improve dispatcher path coverage with branch tests
xgopilot 0dd60a9
fix(gateway): align launcher fallback contract and dispatch launch args
xgopilot fa0541b
Merge pull request #8 from pionxe/fork-pr-423-1776999056
pionxe 9cf7099
fix(gateway): resolve remaining review risks and tighten checks
xgopilot 5413113
Merge pull request #9 from pionxe/fork-pr-423-1776999056
pionxe 57c314c
fix(conflict): resolve README merge conflict with main
xgopilot f32b04b
fix(conflict): align README with main and retain RFC#420 notes
xgopilot File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
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
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
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,11 +1,14 @@ | ||
| .PHONY: install-skills docs-gateway docs-gateway-check | ||
|
|
||
| GATEWAY_DOCS_GENERATOR := go run -tags gatewaydocgen ./scripts/generate_gateway_rpc_examples.go | ||
|
|
||
| install-skills: | ||
| @./scripts/install_skills.sh | ||
|
|
||
| docs-gateway: | ||
| @go run ./scripts/generate_gateway_rpc_examples | ||
| @$(GATEWAY_DOCS_GENERATOR) | ||
|
|
||
| docs-gateway-check: | ||
| @go run ./scripts/generate_gateway_rpc_examples | ||
| @git diff --exit-code -- docs/reference/gateway-rpc-api.md | ||
| @$(GATEWAY_DOCS_GENERATOR) | ||
| @go run ./scripts/check_gateway_docs | ||
| @git diff --exit-code -- docs/generated/gateway-rpc-examples.json | ||
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
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| package main | ||
|
|
||
| import ( | ||
| "context" | ||
| "fmt" | ||
| "os" | ||
|
|
||
| "neo-code/internal/cli" | ||
| ) | ||
|
|
||
| func main() { | ||
| if err := cli.ExecuteGatewayServer(context.Background(), os.Args[1:]); err != nil { | ||
| fmt.Fprintf(os.Stderr, "neocode-gateway: %v\n", err) | ||
| os.Exit(1) | ||
| } | ||
| } |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,48 @@ | ||
| package main | ||
|
|
||
| import ( | ||
| "bytes" | ||
| "errors" | ||
| "os" | ||
| "os/exec" | ||
| "strings" | ||
| "testing" | ||
| ) | ||
|
|
||
| func TestMainHelpPathDoesNotExit(t *testing.T) { | ||
| originalArgs := os.Args | ||
| defer func() { | ||
| os.Args = originalArgs | ||
| }() | ||
|
|
||
| os.Args = []string{"neocode-gateway", "--help"} | ||
| main() | ||
| } | ||
|
|
||
| func TestMainReturnsExitCodeOneOnCommandError(t *testing.T) { | ||
| if os.Getenv("NEOCODE_GATEWAY_MAIN_HELPER") == "1" { | ||
| os.Args = []string{"neocode-gateway", "--log-level", "trace"} | ||
| main() | ||
| return | ||
| } | ||
|
|
||
| command := exec.Command(os.Args[0], "-test.run=TestMainReturnsExitCodeOneOnCommandError") | ||
| command.Env = append(os.Environ(), "NEOCODE_GATEWAY_MAIN_HELPER=1") | ||
| var stderr bytes.Buffer | ||
| command.Stderr = &stderr | ||
|
|
||
| err := command.Run() | ||
| if err == nil { | ||
| t.Fatal("expected subprocess to exit with non-zero status") | ||
| } | ||
| var exitErr *exec.ExitError | ||
| if !errors.As(err, &exitErr) { | ||
| t.Fatalf("error type = %T, want *exec.ExitError", err) | ||
| } | ||
| if exitErr.ExitCode() != 1 { | ||
| t.Fatalf("exit code = %d, want %d", exitErr.ExitCode(), 1) | ||
| } | ||
| if !strings.Contains(stderr.String(), "neocode-gateway:") { | ||
| t.Fatalf("stderr = %q, want contains %q", stderr.String(), "neocode-gateway:") | ||
| } | ||
| } |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,53 @@ | ||
| # Gateway 兼容性与弃用策略 | ||
|
|
||
| 本文定义 Gateway 对外契约的版本兼容规则，适用于方法、字段、错误码与发布资产。 | ||
|
|
||
| ## 1. 兼容性分层 | ||
|
|
||
| 1. Stable（稳定层）：默认向后兼容，不做破坏性改动。 | ||
| 2. Experimental（实验层）：允许演进，但必须有显式标注与迁移说明。 | ||
|
|
||
| 当前分层： | ||
|
|
||
| 1. Stable Core：`gateway.authenticate`、`gateway.ping`、`gateway.bindStream`、`gateway.run`、`gateway.compact`、`gateway.cancel`、`gateway.listSessions`、`gateway.loadSession`、`gateway.resolvePermission`、`gateway.event` | ||
| 2. Experimental：`wake.openUrl` | ||
|
|
||
| ## 2. 字段弃用生命周期（必须遵守） | ||
|
|
||
| ### 2.1 标准流程 | ||
|
|
||
| 1. **v1.2 标记 Deprecated** | ||
| 字段继续可用；文档、日志、响应元信息中标记 `deprecated: true`（或等效说明）。 | ||
| 2. **v1.3 兼容保留期** | ||
| 新客户端 SHOULD 停止依赖该字段；服务端保持兼容读取/写出策略。 | ||
| 3. **v1.4 正式移除** | ||
| 字段从请求/响应契约中删除；若客户端仍发送，返回可诊断错误（通常 `invalid_frame` 或 `unsupported_action`，视场景而定）。 | ||
|
|
||
| ### 2.2 示例 | ||
|
|
||
| 若字段 `params.legacy_x` 计划移除： | ||
|
|
||
| 1. v1.2：文档标记 Deprecated，并在 release notes 给迁移路径。 | ||
| 2. v1.3：继续接受 `legacy_x`，但服务端优先使用新字段。 | ||
| 3. v1.4：拒绝 `legacy_x`，返回明确错误与替代字段提示。 | ||
|
|
||
| ## 3. 破坏性变更门禁 | ||
|
|
||
| 以下变更 MUST 走 RFC 流程并通过灰度窗口： | ||
|
|
||
| 1. 删除 Stable 方法。 | ||
| 2. 修改 Stable 方法必填字段语义。 | ||
| 3. 修改稳定 `gateway_code` 含义。 | ||
| 4. 改变资产命名规则（下载 URL / checksum 路径）。 | ||
|
|
||
| ## 4. 双产物发布兼容承诺 | ||
|
|
||
| 1. `neocode`：保留现有主入口行为。 | ||
| 2. `neocode-gateway`：仅承载网关服务语义。 | ||
| 3. 同参条件下，`neocode gateway` 与 `neocode-gateway` MUST 行为等价（参数归一化、错误语义、关键日志字段）。 | ||
|
|
||
| ## 5. 回滚原则 | ||
|
|
||
| 1. 升级失败时 SHOULD 先回滚二进制版本，再恢复配置。 | ||
| 2. 回滚版本 MUST 与当前稳定协议兼容（至少同主版本）。 | ||
| 3. 回滚步骤必须在发布说明中提供可执行命令与验证点（`/healthz`、`/rpc` 最小请求）。 |
Oops, something went wrong.
Oops, something went wrong.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
docs-gateway-check现在只校验docs/generated/gateway-rpc-examples.json，不再覆盖面向用户的 RPC 文档文件（例如docs/gateway-rpc-api.md/ 旧 reference 文档）。这会让“生成产物正确但主文档描述过期”无法在 CI 被拦截。建议把用户可读文档的一致性校验也纳入该目标。