mirrors/pikasTech-HWLAB
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add code agent provider profiles

Browse Source
This commit is contained in:
Codex
2026-05-26 01:47:11 +08:00
parent c0d1dac33d
commit 83cf496fcd
11 changed files with 469 additions and 136 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/reference/dev-runtime-boundary.md
+30 -49
View File
@@ -3,75 +3,56 @@
This reference defines the stable DEV environment, port, k3s, and runtime
substitution rules.
## Public DEV Ports
## Public G14 Runtime Ports
| Surface | URL |
| --- | --- |
| Cloud Web browser entry | `http://74.48.78.17:16666/` |
| API/edge entry | `http://74.48.78.17:16667/` |
| API/live health | `http://74.48.78.17:16667/health/live` |
| Surface | DEV URL | PROD URL |
| --- | --- | --- |
| Cloud Web browser entry | `http://74.48.78.17:17666/` | `http://74.48.78.17:18666/` |
| API/edge entry | `http://74.48.78.17:17667/` | `http://74.48.78.17:18667/` |
| API/live health | `http://74.48.78.17:17667/health/live` | `http://74.48.78.17:18667/health/live` |
Public `:6666` and `:6667` are deprecated as browser/API acceptance targets.
Internal k3s services may still listen on `6667`; do not rewrite that as a
public endpoint.
Public `:16666` and `:16667` are D601 legacy DEV endpoints. They can be used only for migration comparison or incident replay, not as the current HWLAB runtime acceptance target. Internal k3s services may still listen on `6667`; do not rewrite that as a public endpoint.
## Route Shape
The public route is:
The current G14 DEV route is:
```text
master hwlab-frps-dev :16666/:16667
-> D601 hwlab-frpc in namespace hwlab-dev
master hwlab-frps-dev :17666/:17667
-> G14 hwlab-g14-frpc in namespace hwlab-dev
-> hwlab-cloud-web on internal :8080 for browser traffic
-> hwlab-edge-proxy / hwlab-cloud-api on internal :6667 for API and health
```
`deploy/deploy.json` is the source for public endpoint and FRP mapping drift
checks. Use:
G14 PROD is rendered by GitOps as namespace `hwlab-prod` and Argo CD application `hwlab-g14-prod`; it uses the `:18666/:18667` public endpoints when enabled. G14 desired state is generated into `deploy/gitops/g14/runtime-dev` and `deploy/gitops/g14/runtime-prod` and promoted through the `G14-gitops` branch.
## G14 k3s Source Of Truth
G14 native k3s is the HWLAB DEV/PROD runtime source of truth. Commands that observe or mutate current HWLAB runtime must go through UniDesk route `G14:k3s`, for example:
```sh
node scripts/deploy-contract-plan.mjs --check
tran G14:k3s kubectl -n hwlab-dev get deploy,svc,pod -o wide
tran G14:k3s kubectl -n argocd get application hwlab-g14-dev hwlab-g14-prod
```
## D601 k3s Source Of Truth
Do not use D601 kubeconfig, D601 `dev-cd-apply`, old JS `ci-publish`, Docker Desktop Kubernetes, or master-server local checks as G14 runtime acceptance evidence. D601 remains a legacy migration/reference surface until the branch-role migration is complete.
D601 native k3s is the DEV runtime source of truth. Commands that observe or
roll a DEV workload must specify:
## Branch Role Migration
The target branch model is: G14 becomes the `main` runtime source branch, and the former D601-oriented `main` behavior moves to a D601 legacy/maintenance line. Until that branch governance operation is explicitly completed and verified, `/root/hwlab` on G14 continues to use the `G14` branch and must merge the latest `origin/main` business updates before G14-specific runtime work.
## Distributed Passthrough Hygiene
When running more than one command on G14, keep all commands inside one remote `script` block:
```sh
KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl -n hwlab-dev get deploy,svc,pod -o wide
tran G14:/root/hwlab script <<'SCRIPT'
sed -n '1,80p' docs/reference/dev-runtime-boundary.md
sed -n '1,80p' AGENTS.md
SCRIPT
```
Do not trust the default `kubectl` context as a DEV runtime signal. On D601 it
may point at another cluster such as `docker-desktop`. The 2026-05-23 control
plane incident is tracked in
[pikasTech/unidesk#138](https://github.com/pikasTech/unidesk/issues/138), with
hotfix context in
[pikasTech/unidesk#118](https://github.com/pikasTech/unidesk/issues/118):
Docker Desktop Kubernetes has been disabled and cleaned, but the default
`/home/ubuntu/.kube/config` may still point at the dead
`docker-desktop`/`127.0.0.1:11700` entry. Treat that as residual bad config, not
as DEV runtime evidence.
Before any DEV deploy, rollback, smoke, or manual k3s observation, confirm the
native node explicitly:
```sh
KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl get nodes -o jsonpath='{.items[*].metadata.name}'
```
The result must contain `d601`. Seeing `desktop-control-plane`,
`docker-desktop`, or `127.0.0.1:11700` means the command is on the wrong
control-plane path and must stop before mutation or acceptance.
Use the read-only preflight when a runner needs to report k3s visibility:
```sh
node scripts/d601-k3s-readonly-observability.mjs
```
The preflight must not print secret values, kubeconfig material, ConfigMap
values, or token content.
Do not write `tran G14:/root/hwlab sed ... && sed ...` unless the second command is intentionally local. Shell operators such as `&&`, `;`, and pipes outside the `tran` invocation are evaluated by the local shell; this can make later commands run on the master server and look like a missing-file or truncation bug.
## Cloud API DB Readiness Authority
docs/reference/g14-gitops-cicd.md
+17 -2
View File
@@ -1,6 +1,6 @@
# G14 GitOps CI/CD
G14 是 HWLAB 的旁路 DEV 集群目标。G14 CI/CD 必须只作用于 G14 k3s，不接管 D601 生产，不使用 UniDesk Code Queue 作为调度器，也不把 UniDesk backend、provider-gateway 或 microservice proxy 当作 HWLAB runtime。
G14 是 HWLAB 当前 DEV/PROD 原生 k8s 与 GitOps 运行面目标。G14 CI/CD 必须只作用于 G14 k3s，不接管 D601 legacy 运行面，不使用 UniDesk Code Queue 作为调度器，也不把 UniDesk backend、provider-gateway 或 microservice proxy 当作 HWLAB runtime。
## 目标模型
@@ -8,7 +8,7 @@ G14 是 HWLAB 的旁路 DEV 集群目标。G14 CI/CD 必须只作用于 G14 k3s
- CI：Tekton 在 G14 k3s 内运行 `hwlab-g14-ci-image-publish` Pipeline，读取 `CI.json` 命令，按 source commit 构建镜像并推送到 G14 registry。
- Artifact：镜像使用 commit tag，例如 `127.0.0.1:5000/hwlab/hwlab-cloud-api:<shortCommit>`；digest 由 registry 返回，CI report 只作为审计证据，不作为 CD 真相。
- Branch split：`G14` 是源码监控分支；`G14-gitops` 是 Tekton promotion 写入的生成分支，保存 `deploy/gitops/g14/**` desired state。
- CD：Argo CD 只消费 `G14-gitops:deploy/gitops/g14/runtime` 的 Git desired state，不重新构建镜像，不读取 D601 状态，不获取 legacy DEV CD Lease。
- CD：Argo CD 只消费 `G14-gitops:deploy/gitops/g14/runtime-dev` 与 `deploy/gitops/g14/runtime-prod` 的 Git desired state，不重新构建镜像，不读取 D601 状态，不获取 legacy DEV CD Lease。
- 并行性：不同 source commit 的 CI build 不共享发布锁；并行安全由 immutable commit tag/digest 和 Git desired state 保证。最终运行版本由 Argo CD 当前同步的 Git revision 决定。
## 生成入口
@@ -24,6 +24,7 @@ G14 是 HWLAB 的旁路 DEV 集群目标。G14 CI/CD 必须只作用于 G14 k3s
- 默认 registry prefix 是 `127.0.0.1:5000/hwlab`，用于 G14 单节点 k3s 的 node-local registry。
- 默认 CI/CD proxy 是 G14 本机 `http://127.0.0.1:10808` / `socks5h://127.0.0.1:10808`。Tekton CI step、Docker-in-Docker sidecar 和 publish step 都注入 proxy/no_proxy；publish step 必须先在 DIND 内 `docker pull $HWLAB_DEV_BASE_IMAGE`，再进入 DEV base-image preflight、build 和 registry push，保证 npm、base image 拉取和 registry push 走 G14 本机代理边界。
- `ci-json` 不允许每次运行时重新 `apt-get install` 或 `npx playwright install --with-deps`。它必须使用已经预热的 CI 基础镜像，当前默认由 `scripts/g14-gitops-render.mjs` 固定为 `mcr.microsoft.com/playwright@sha256:b0ab6f3cb99aa7803adbc14d9027ec1785fc6e433b97e134e0f8fe61683b6b53`；该镜像在 G14 k3s/containerd 中已缓存，包含 Node、npm、Git、Python3、OpenSSH、curl、Playwright 系统依赖和 `/ms-playwright/chromium-1217`。脚本启动时必须输出 `ci-base-image` 和 `playwright-cache-check` 结构化日志；缺少工具或 Chromium cache 时直接失败并修基础镜像，不能回退到 runtime apt 下载。若以后需要 Node 22 固定版本，先构建并推送 G14 registry 内的 Node22+Playwright runner 镜像，再修改 `HWLAB_G14_CI_JSON_IMAGE`/render 默认值。
- G14 host 只用于 source workspace、GitOps render、k3s 控制和轻量语法/静态合同检查；不要把 host 当成浏览器执行面。当前 G14 host OS 可能比 Playwright 官方 browser 包支持矩阵更新，`npx playwright install chromium` 会失败或 browser executable 不存在。`web:check` 默认允许这类明确的 Playwright/browser runtime 环境限制作为 `environment_blocker`/`skip` 通过源码合同；真正的布局、移动端和交互 browser smoke 必须在 G14 k3s/Tekton 的 Playwright 基础镜像内运行，不能用 host 上强装 browser 作为长期方案。
- Poller、control-plane reconciler 和 image publish step 也不允许每次运行时 `apk add`。当前 G14 registry 固定工具镜像是 `127.0.0.1:5000/hwlab/hwlab-ci-node-tools:node22-alpine-v1`，包含 Node 22、npm、Git、OpenSSH、curl、Python3 和 Docker CLI；生成的脚本只做 proxy preflight 与工具存在性检查。若需要升级工具，先在 G14 构建/推送新的工具镜像，再修改 `HWLAB_G14_CI_TOOLS_IMAGE`/render 默认值并由 reconciler apply。
- 服务镜像构建的默认 parent/base image 不得从 Docker Hub 反复拉取。当前 `node:20-bookworm-slim` 已镜像到 G14 registry 的 allowlist 名称：`127.0.0.1:5000/hwlab/hwlab-node20-base:20-bookworm-slim`，render 默认 `base-image` 和 poller `BASE_IMAGE` 都指向这个本地镜像。需要升级 parent image 时，先通过 G14 proxy 拉取并推送到 G14 registry，再修改 `HWLAB_G14_DEV_BASE_IMAGE`/render 默认值；image publish step 只允许从本地 registry pull base image，且 tag 必须符合 publish gate 的 `hwlab-node20-base`/`hwlab-dev-base`/`hwlab-node-runtime-base` allowlist。
- 任何依赖下载阶段都必须有可观测诊断。生成的 Tekton 脚本在 apt/apk、npm、Playwright browser、Docker base image pull 和 GitOps promote 之前输出结构化 `dependency-proxy-probe`、`dependency-curl-probe` 或 `dependency-download-*` 日志，至少包含 phase、目标 URL/镜像、脱敏 proxy、首包耗时、总耗时、下载字节数和速度。CI/CD 卡在下载时，先用这些日志判断是 proxy 不可达、目标源慢、DNS/首包慢还是下载吞吐低，再决定是否切换 G14 代理节点或预热镜像；不能只凭 PipelineRun Running 时长判断业务测试失败。
@@ -35,6 +36,20 @@ npm run g14:gitops:render -- --source-revision <sourceCommit>
npm run g14:gitops:check
```
## Code Agent Provider Profiles
G14 Code Agent 通过同一个 repo-owned Codex app-server stdio runner 承载多个 OpenAI-compatible Responses profile。Cloud Web 每次请求都发送 `providerProfile`，后端按 profile 生成本次请求的 env overlay；不得把某一个模型通道硬写死到全局运行态而删除另一个通道。
| Profile | 默认 | Model | Base URL | 说明 |
| --- | --- | --- | --- | --- |
| `deepseek` | 是 | `HWLAB_CODE_AGENT_DEEPSEEK_MODEL`，默认 `deepseek-chat` | `HWLAB_CODE_AGENT_DEEPSEEK_BASE_URL`，默认 `http://hwlab-deepseek-proxy.<namespace>.svc.cluster.local:4000/v1/responses` | G14 集群内 LiteLLM DeepSeek bridge。 |
| `codex-api` | 否 | `HWLAB_CODE_AGENT_CODEX_API_MODEL`，默认 `gpt-5.5` | `HWLAB_CODE_AGENT_CODEX_API_BASE_URL`，默认 `http://172.26.26.227:17680/v1/responses` | 保留旧 Codex/OpenAI-compatible Responses API 通道。 |
`hwlab-cloud-api` 仍以 `HWLAB_CODE_AGENT_PROVIDER=codex-stdio` 运行。`HWLAB_CODE_AGENT_MODEL` 与 `HWLAB_CODE_AGENT_OPENAI_BASE_URL` 可作为 runtime-default 兜底，但前端默认 profile 是 `deepseek`，用户可以切到 `codex-api`。Codex app-server 启动参数必须同时设置 provider base URL、`model` 和 `review_model`，否则 LiteLLM `/v1/responses` 会收到 `model=None`。旧 `codex-api` profile 指向 `172.26.26.227`，cloud-api 的 `NO_PROXY/no_proxy` 必须包含该 host 或私网段，避免旧通道被 G14 外网代理误拦截。
DeepSeek proxy manifest 是 GitOps desired state 的一部分，DEV/PROD 分别生成在 `runtime-dev/deepseek-proxy.yaml` 和 `runtime-prod/deepseek-proxy.yaml`。DeepSeek key 仍通过 `hwlab-code-agent-provider/openai-api-key` Secret 注入到 proxy 容器；文档、trace、health、issue 和日志不得打印 Secret 值。
## Polling 触发
G14 不要求 GitHub webhook 或 GitHub Actions 配置。`hwlab-ci/hwlab-g14-branch-poller` CronJob 每 5 分钟通过 Git SSH 拉取 `G14` HEAD，并用 source commit 的前 12 位生成 PipelineRun 名称 `hwlab-g14-ci-poll-<short12>`。