| name | update-gateway-vendor |
| description | 修改 Kiro 网关本体逻辑（转换器/路由/流式/payload 处理等，即 app/kiro_gateway_tray/vendor/kiro 或 vendor/main.py 里的代码）时务必使用。核心铁律：禁止直接改 vendor/ 目录（它由 vendor_sync.py 从上游 fork 生成、且被 gitignore，手改会被覆盖）。正确流程：改上游 fork ../kiro-gateway 的源码并加/改测试 → 跑 pytest → 中文 commit 推 origin/main 发布（CI 产出 ghcr 镜像 main-<sha>）→ 回本仓同步更新 UPSTREAM_SHA 与 docker-compose 镜像 tag → 跑 vendor_sync.py 重新 vendor。当用户说"改网关"、"改转换逻辑"、"改 kiro 的 xxx"、"修一下工具调用/流式/payload"、"更新 vendor"、"升级网关依赖"等时触发。 |
更新网关本体（vendor）工作流
铁律：永远不要直接改 vendor/
app/kiro_gateway_tray/vendor/（含 kiro/、main.py、requirements.txt）是
生成产物：
- 由
app/scripts/vendor_sync.py 从上游 fork 在固定 SHA 处 clone 拷贝而来。
- 被
.gitignore 忽略（git status 看不到，本仓不跟踪它）。
- 任何手改都会在下次
vendor_sync.py 运行时被整目录删除重建而丢失。
所以网关本体的逻辑改动必须改上游源码，再走下面的同步流程落回本仓。
例外：只有当你确认改动仅用于一次性本地抓包/调试、且明确不打算保留时，
才可临时改 vendor；否则一律走上游流程。
涉及的两个仓库与两处 pin
- 上游 fork：
/Users/san/project/kiro-gateway
- 分支
main；remote origin = github.com/zhujunsan/kiro-gateway（我们的 fork），
upstream = jwadow/kiro-gateway（原始上游）。
- push 到
main 后，.github/workflows/docker.yml 会先跑 pytest，通过后构建并推
ghcr.io/zhujunsan/kiro-gateway:main-<短SHA>（多架构）。pytest 不过则不出镜像。
- 本仓（kiro-gateway-deploy）里两处必须同步指向同一个 SHA：
app/kiro_gateway_tray/__init__.py 的 UPSTREAM_SHA（PyInstaller 打包的 App 用，
vendor_sync.py 据此 clone）。docker/docker-compose.yml 的 image: ghcr.io/zhujunsan/kiro-gateway:main-<短SHA>
（docker 部署用）。
标准流程
1. 在上游 fork 改源码 + 测试
cd /Users/san/project/kiro-gateway
git switch main && git status
- 改
kiro/...（或 main.py）里的真实逻辑。
- 同步加/改
tests/unit/ 下的测试（CI 会跑 pytest，旧测试若断言被改的行为会失败）。
- 跑测试，必须全绿：
.venv/bin/python -m pytest -q
2. 提交并发布（push 到 origin/main）
- commit message 用中文 + conventional 前缀，与上游既有风格一致
（如
fix(tools): ...、fix(streaming): ...、fix(converters): ...）。
- 用 HEREDOC 写多行说明（讲清"为什么"）。
- 禁止强推 main。
git add <改动文件>
git commit -m "$(cat <<'EOF'
fix(<scope>): <一句话中文摘要>
<为什么这么改 / 根因 / 约束>
EOF
)"
git push origin main
git log -1 --format='%h'
- 可选确认 CI 已开始/通过：
gh run list --branch main --limit 3
（镜像 main-<SHA> 要等这次 run 成功后才存在；约几分钟）。
3. 回本仓更新两处 pin
把上一步的短 SHA 填进去（示例 SHA f3c8147）：
app/kiro_gateway_tray/__init__.py：UPSTREAM_SHA = "f3c8147"docker/docker-compose.yml：image: ghcr.io/zhujunsan/kiro-gateway:main-f3c8147
4. 重新 vendor（在 push 之后执行）
vendor_sync.py 会从 GitHub clone fork 到该 SHA 再拷贝，所以必须先 push。
cd /Users/san/project/kiro-gateway-deploy/app
.venv/bin/python scripts/vendor_sync.py
5. 校验
cd /Users/san/project/kiro-gateway-deploy
diff app/kiro_gateway_tray/vendor/kiro/converters_core.py ../kiro-gateway/kiro/converters_core.py && echo IDENTICAL
git status --short
完成之后
- 以上只更新了"网关依赖 + docker tag"。若用户还要发新版 App 安装包
（升
__version__、写 ChangeLog.md、打 v* tag），走 make-release skill。
- docker 部署侧用户重新
docker compose pull && up -d 即可（需 CI 已出镜像）。
常见坑
- 改了 vendor 没改上游 → 下次 sync 丢失。改上游。
- 只改了
__init__.py 没改 docker-compose（或反之）→ App 与 docker 跑的网关版本不一致。两处一起改。
- 没 push 就跑 vendor_sync → clone 不到新 SHA 而失败/拿到旧码。先 push 再 sync。
- 上游加了逻辑没加测试 → CI 的 pytest 可能因旧测试断言失败而挡住镜像构建。
