docs: codify host proxy bootstrap governance

.agents/skills/unidesk-ymalops/SKILL.md

@@ -29,6 +29,8 @@ description: UniDesk YAML-first 运维正规化技能。用户提到 ymal-first/
 - YAML 文件名、YAML 解析函数名和 YAML 渲染函数名不得携带具体 node/lane 名称或版本实例（例如 `JD01`、`D601`、`v03`、`jd01-v03`）。node/lane/version 只能作为 YAML 变量、selector、target key、template value 或 CLI 参数参与渲染；可复用文件和代码入口必须按职责命名。
 - 避免“超级配置”。当一个能力同时涉及 target/lane、runtime、scenario、prompt、report、publicExposure、Secret、CI/CD 等不同职责时，按职责拆分到 owning YAML；root YAML 只保存归属和 `configRefs`/path 引用，不承载全部细节。
 - 跨 YAML 引用应使用稳定的 `path/to/file.yaml#object.path` 或当前 domain parser 明确支持的等价语法。parser 只解析引用、校验存在性/类型/形状和冲突，不生成隐藏默认值，也不把合并后的大对象写成新的 source of truth。
+- 新 VPS 或裸节点 bootstrap 的出网必须优先走 YAML-first 声明的 0 依赖 host proxy client：通过 `trans` 分发零依赖客户端，先让 host route 能出网，再安装 k3s、containerd、Docker、包管理器依赖和 Git/gitrepo 同步；不得把 provider-gateway WebSocket egress 当作大二进制或依赖下载的数据面。
+- YAML 配置必须可复用、可继承、可组合；节点/lane 只能作为变量或 YAML value 参与渲染，禁止把具体 node/lane 写入 YAML 文件名、parser/renderer/helper 函数名或长期 schema 名。发现不同节点复制大段配置时，先抽 baseline/configRef/override，再继续扩展节点。
 - CLI `plan/status` 应输出 redacted 配置引用图：每个 ref 的文件、path、presence、摘要 hash、缺失字段和下一步 drill-down 命令。不要默认 dump 展开后的完整 YAML 或 Secret。
 - Secret 只能通过 YAML 的 `sourceRef`/`targetKey` 声明和受控 CLI 下发；禁止从运行面 Secret、pod env、日志或数据库状态反推、解码、回填本地凭据。
 - 受控 CLI 输出只能披露对象名、key 名、sourceRef、targetKey、缺失项、fingerprint、字节数和执行摘要；不得打印 base64 payload、解码值、完整 DSN、API key 或可复制凭据。

docs/reference/platform-infra.md

@@ -8,6 +8,7 @@
 - Runtime Secrets and local `~/.codex/config.toml*` / `auth.json*` files are inputs or generated local state, not committed truth. CLI output may show Secret paths, byte counts, fingerprints, and short previews only; it must not print complete API keys.
 - Code that reads platform YAML must validate object shape, field types, required fields, Kubernetes names, image strings, and ports before mutating G14 k3s or local consumer files.
 - Do not hide image versions, namespace names, endpoint URLs, FRP ports, or profile lists in Python/TOML/JSON helper constants when they are UniDesk-owned choices. External tools may still require their own TOML/JSON/env file formats at the edge.
+- Fresh node outbound bootstrap uses the zero-dependency host proxy boundary defined in `docs/reference/yaml-first-ops.md`. Platform-infra egress proxy settings may provide the benchmark-validated proxy source and workload consumer settings, but a new node must not depend on Docker, k3s, containerd or package-manager network access to install the initial host proxy client.
 
 ## Secret Distribution Boundary
 
@@ -174,6 +175,8 @@ For an externally backed active target, client traffic reaches PK01 Caddy, PK01
 
 When target-level `egressProxy.enabled=true`, the D601 target renders an in-cluster HTTP/mixed proxy client from the proxy source declared in YAML. The current mature external-egress shape is `sourceType: master-shadowsocks`: master Docker runs `shadowsocks-rust` from `config/platform-infra/sub2api-master-egress-proxy.compose.yaml`, while D601 runs `sing-box` to expose the ClusterIP proxy consumed by Sub2API and, when requested by YAML, the Codex account sentinel. A subscription-backed source is still just another YAML-declared source type; long-term prose must not duplicate the current endpoint, port, password, image tag, or health URL values from YAML/compose.
 
+For a fresh VPS that does not yet have reliable Docker or k3s egress, the same benchmark-validated proxy source may be consumed by a host proxy client distributed over `trans` and configured from YAML before k3s installation. This host client is the bootstrap egress path for k3s installer downloads, containerd image pulls, package managers, Git and git-mirror operations. It is not a replacement for service-specific proxy declarations; once k3s is available, each workload must still declare whether it consumes host proxy env, an in-cluster proxy Service, or direct egress.
+
 `platform-infra egress-proxy traffic --target <id> --sample-seconds <n>` is the proxyserver-side observation entry. It reads the sing-box Clash API through the proxy Pod loopback, reports current per-client rate plus bounded-window cumulative bytes, and includes proxy process cumulative bytes when sing-box reports them. Use this together with k3s CI/CD build benchmarks when diagnosing whether a workload is currently traversing the proxy; client-side timings alone are not enough evidence.
 
 The egress proxy Deployment may opt into `hostNetwork: true` per target via `config/platform-infra/sub2api.yaml` `targets[].egressProxy.hostNetwork`. When enabled, the manifest renders `hostNetwork: true`, `dnsPolicy: ClusterFirstWithHostNet`, and a RollingUpdate strategy of `maxSurge=0`/`maxUnavailable=1` so the sing-box client bypasses the pod overlay and connects the master upstream directly from the node network; this is the durable fix for a target whose pod-overlay path to the upstream is the throughput bottleneck. It is a per-target YAML decision, not a D601-only default: a target whose pod overlay is already fast enough must keep `hostNetwork: false`, and the `no-host-network` policy check only permits `hostNetwork: true` on the single YAML-declared egress proxy Deployment for a target whose `egressProxy.hostNetwork=true`. Do not generalize one target's hostNetwork experiment to other nodes, and do not leave a one-off `kubectl patch` as the final state; promote or demote hostNetwork only by editing the target YAML and running `platform-infra sub2api apply --target <id>`.

docs/reference/yaml-first-ops.md

@@ -73,6 +73,25 @@ The domain CLI resolves the target from YAML, calls shared helpers and prints st
 
 Runtime mutation goes through UniDesk CLI and `trans` route execution. Direct `kubectl`, raw SSH, hand-written Caddy edits, direct GitHub API calls or ad hoc shell scripts may be diagnostic or emergency recovery tools only. Repeated operational writes must be promoted into a controlled CLI command that reads YAML and reports redacted structured output.
 
+## Host Bootstrap And Zero-Dependency Proxy
+
+Fresh VPS bootstrap has one allowed host-level exception before the node can become a clean k3s runtime: a zero-dependency host proxy client distributed and configured by YAML-first ops through `trans`. The client must not require Docker, k3s, containerd, Node, Python, Bun, Go, Rust, or package-manager network access to install. Its purpose is to provide outbound connectivity for those dependencies, including k3s installer downloads, container image pulls, `apk`, `apt`, `npm`, Go modules, Git and git-mirror sync/flush.
+
+The proxy source, upstream server identity, local listen address, local port, systemd unit, environment injection targets, health probe and secret source references must be declared in YAML. The target node should receive only rendered artifacts and redacted summaries over `trans`; it must not fetch the proxy client from the public internet before the proxy exists. Values such as proxy server host, credentials, bind port and benchmark profile belong in YAML or Secret source files, not in prose or code defaults.
+
+The default bootstrap order for a new node is:
+
+1. establish provider-gateway only long enough to make `trans` reachable;
+2. distribute the zero-dependency proxy client through `trans`;
+3. start and validate the host proxy client from YAML-rendered systemd or equivalent host control;
+4. configure host egress for k3s/containerd/package managers and Git through that proxy;
+5. install k3s and deploy workloads through YAML-first control paths;
+6. keep later workload proxy settings as YAML-declared consumers of the host route unless a domain explicitly owns a different proxy boundary.
+
+For fresh VPS bring-up, do not use provider-gateway WebSocket egress as the bulk path for large installers, images or dependency downloads. Provider-gateway and `trans` are the bootstrap control channel; the host proxy client is the data egress path once installed.
+
+Host proxy use has a privacy boundary. A plain `http_proxy=http://...` proxy can observe destination hosts, request metadata and any proxy credential embedded in the URL or process environment; TLS protects encrypted request bodies from the proxy but does not hide the destination metadata from the proxy operator. Do not place private API keys in proxy URLs, logs or CLI output. `NO_PROXY`/`no_proxy` must preserve local, cluster, metadata and explicitly declared direct domains, including `hyueapi.com` and `.hyueapi.com` for Codex direct API access.
+
 ## Cross-Repository Operational Truth
 
 When UniDesk prepares or supervises runtime data for another repository, the owning YAML still belongs in UniDesk if the data is part of node/lane operations rather than that repository's application source. Examples include HWLAB test/admin account inventories, operator-only API key source references, runtime DB sync inputs, public exposure targets and cross-node workbench preparation. The service repository may contain application code and app-native migrations, but it must not become a second desired-state truth for UniDesk-operated accounts, credentials, nodes, lanes, namespaces or sourceRef bindings.
@@ -109,6 +128,16 @@ External database consumers must reference the YAML-owned platform database sour
 
 Probes are validation data, not hidden policy. YAML should declare what endpoint or runtime object proves the operation for that service. CLI code may execute the probe, bound output and classify failure, but should not hard-code current URLs, credentials, namespaces or service paths.
 
+## Reuse, Composition And Variable Rendering
+
+YAML-first does not mean one ever-growing file per node. Reusable configuration should be expressed as small owning YAML documents that can be inherited, composed or referenced by `configRefs`. A node-specific file should normally select a baseline, provide only the concrete overrides for that node, and reference shared blocks for proxy, public exposure, Secret distribution, source truth, runtime dependencies, probes and rollout policy.
+
+Config composition must keep one durable source of truth for each fact. Rendered plans may merge defaults, baselines and overrides for execution, but the merged object must not be written back as a second editable truth. CLI `plan/status --full` should show the reference chain, effective owner, variable inputs, redacted source fingerprints and missing fields instead of dumping all expanded YAML by default.
+
+Variable rendering is allowed for node/lane/service-specific artifact generation. Node and lane identifiers must be data variables, not part of YAML filenames, parser function names, renderer names, TypeScript helper names or long-term schema names. For example, use a neutral template plus `NODE`/`LANE` variables instead of adding files or functions named after a concrete node. Concrete node names may appear only as YAML values, CLI parameters, rendered runtime object names where the external system needs them, or legacy adapters that are explicitly classified.
+
+When a configuration area starts to repeat whole blocks across nodes, treat that as a design smell. Promote the common block into a baseline or shared reference before adding more node copies, and keep node overrides short enough to review. If the owning YAML still grows without a clear owner boundary, split by responsibility: bootstrap host dependencies, proxy, k3s install, platform services, app lane, public exposure, Secret sourceRefs, probes and sentinel schedules should not be forced into one file merely because they target the same node.
+
 ## Refactoring Rule
 
 When adding YAML-first ops to an existing domain, follow this order:

project-management/PJ2026-01/specs/PJ2026-010603-yaml-first-ops.md

@@ -42,6 +42,8 @@ YAML运维负责 HWLAB/UniDesk 自有平台配置的真相源、解析、渲染
 - AgentRun lane 的 runner retention、idle timeout、egress proxy 和 cancel lifecycle policy 等运行策略配置读取、解释和下发。
 - FRP、Caddy、public URL、public health、Kubernetes Secret 和平台资源渲染所需的配置投递边界。
 - 可复用 ops primitive，包括 YAML path 捕获、字段解析、fingerprint、摘要输出、Secret 引用、有界默认输出和命令输出约束。
+- 新节点 host bootstrap 的 0 依赖出网代理、`trans` 分发、host route 注入和 k3s 安装前置控制。
+- YAML 配置的基线继承、configRef 组合、变量渲染和节点覆盖治理，避免为不同 node/lane 重复复制大段配置。
 
 ### 2.3 范围外
 
@@ -67,6 +69,8 @@ YAML运维负责 HWLAB/UniDesk 自有平台配置的真相源、解析、渲染
 | ops primitive | 平台运维 CLI 共享的底层能力，例如字段解析、fingerprint、Secret 引用、摘要输出和 YAML path 捕获。 |
 | 配置解释输出 | CLI 将 YAML 解析后的默认值、来源和目标以非敏感摘要展示给操作人员的输出。 |
 | 有界默认输出 | CLI 在未显式请求机器输出或完整输出时返回的短摘要、表格和 drill-down 命令集合。 |
+| host proxy client | 新节点 k3s 安装前由 `trans` 分发的 0 依赖出网代理客户端，用于给 Docker、k3s、containerd、包管理器、Git 和 git-mirror 提供初始出网。 |
+| 配置组合 | 通过 baseline、configRef、继承、覆盖和变量渲染生成有效计划的配置方式；组合结果是执行视图，不是第二份可编辑真相源。 |
 
 ## 4. 系统边界和接口
 
@@ -75,9 +79,9 @@ YAML运维负责 HWLAB/UniDesk 自有平台配置的真相源、解析、渲染
 | 边界项 | 内容 |
 | --- | --- |
 | 外部使用者 | 平台管理员、发布操作人员、Agent编排维护者、Sub2API/Codex pool 维护者和自动化运维任务。 |
-| 外部输入 | YAML 配置文件、target/lane/node/service 声明、Secret sourceRef、providerCredential、publicExposure、运行目标选择和配置解释请求。 |
+| 外部输入 | YAML 配置文件、target/lane/node/service 声明、Secret sourceRef、providerCredential、publicExposure、host proxy 声明、baseline/configRef、运行目标选择和配置解释请求。 |
-| 受控资源 | 配置解析器、公共 ops helper、Sub2API/Codex pool 配置、AgentRun lane 配置、Kubernetes Secret 声明、FRP/Caddy 渲染、public health 和 CLI 输出摘要。 |
+| 受控资源 | 配置解析器、公共 ops helper、Sub2API/Codex pool 配置、AgentRun lane 配置、host proxy client 分发和 systemd 渲染、Kubernetes Secret 声明、FRP/Caddy 渲染、public health 和 CLI 输出摘要。 |
-| 外部输出 | 配置解释结果、计划摘要、同步摘要、Secret presence/fingerprint、publicExposure 渲染结果、运行目标解析结果、有界默认输出和错误诊断。 |
+| 外部输出 | 配置解释结果、计划摘要、同步摘要、Secret presence/fingerprint、host proxy health、publicExposure 渲染结果、运行目标解析结果、有界默认输出和错误诊断。 |
 | 用户接口 | `bun scripts/cli.ts platform-infra ...`、`bun scripts/cli.ts agentrun ...`、受控 Secret 同步命令、配置解释命令和平台状态查询命令。 |
 | 系统边界 | YAML运维负责让配置从 YAML 可解释、可校验并受控进入运行面；不定义业务策略数值、不替代 Agent/用户/客户端语义，也不把运行面观测反向变成本地配置真相。 |
 
@@ -93,6 +97,10 @@ YAML运维负责 HWLAB/UniDesk 自有平台配置的真相源、解析、渲染
 | PJ2026-01060306 | 公共原语 | 本规格 6.6 | 字段解析、fingerprint、摘要输出、Secret 引用和 YAML path 捕获复用 | 各平台 CLI 实现 | 全部平台运维 CLI |
 | PJ2026-01060307 | 控制面模块化 | [PJ2026-01060307 控制面模块化](PJ2026-01060307-control-plane-modularity.md) | CI/CD、YAML-first 和平台运维 CLI 源码入口的职责拆分、兼容入口和模块边界 | 发布流水、源码同步、公共原语 | 全部平台运维 CLI |
 | PJ2026-01060308 | YAML目标治理 | [PJ2026-01060308 CI/CD YAML目标治理](PJ2026-01060308-cicd-yaml-first-target-governance.md) | CI/CD、HWLAB lane、AgentRun、platform-infra、Secret 和 public exposure 的 target/configRef/sourceRef 解析治理 | 控制面模块化、发布流水、源码同步 | CI、deploy、artifact-registry、HWLAB、AgentRun、platform-infra、secrets |
+| PJ2026-01060309 | 跨节点代理基准 | [PJ2026-01060309 跨节点代理CI基准](PJ2026-01060309-cross-node-proxy-ci-benchmark.md) | 通过基准验证代理方案和跨节点依赖拉取能力 | public egress、proxy source | host proxy、k3s deps、CI/CD |
+| PJ2026-01060310 | 真实依赖基准 | [PJ2026-01060310 Real K3s Dependency Proxy Benchmark](PJ2026-01060310-real-k3s-deps-proxy-benchmark.md) | 使用真实 k3s 镜像、apk、npm、Go 和 Git mirror 依赖验证代理路径 | 跨节点代理基准、platform-infra proxy | k3s 构建、git-mirror、节点引导 |
+| PJ2026-01060311 | Host引导代理 | 本规格 6.9 | 0 依赖 host proxy client、`trans` 分发、host route 注入和 k3s 安装前出网控制 | 代理基准、目标解析、密钥绑定 | 新节点纯净 k3s 部署、package manager、git-mirror |
+| PJ2026-01060312 | 配置组合 | 本规格 6.10 | baseline、configRef、继承、覆盖、变量渲染和重复块治理 | 配置真相、目标解析、公共原语 | 多节点 YAML 复用、长期维护 |
 
 ## 6. 原子需求
 
@@ -193,3 +201,27 @@ YAML运维应约束 CI、deploy、artifact-registry、HWLAB node/lane、AgentRun
 公共 option parser 不得内置 domain target 默认。未显式传入目标时，调用 domain 可以从自身 YAML default 解析，并必须输出默认来源路径；已显式传入 node/lane/target 时，解析器只校验和解释该目标，不得用全局 default 覆盖。
 
 跨 YAML 的运行目标事实应使用 `path/to/file.yaml#object.path` configRef，CLI `plan/status --full` 应显示引用链、resolved target、presence、摘要 hash 和缺失字段，不打印 Secret 值。代码中保留的 `G14`、`D601`、`v02`、`v03` 等目标名必须被 hardcode inventory 分类为 legacy adapter、help example、test fixture 或真实领域特例；隐藏默认必须迁移到 YAML。
+
+### 6.9 OPS-YAML-REQ-009 Host 引导代理
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| OPS-YAML-REQ-009 | Host引导代理 | PJ2026-01060311 Host引导代理 | [发布流水](PJ2026-010601-controlled-release.md)、[源码同步](PJ2026-010602-source-sync.md)、[平台运维](PJ2026-0106-platform-ops.md) |
+
+YAML运维应为新节点提供 k3s 安装前可用的 host proxy client 能力。该 client 必须是 0 依赖分发对象，不能依赖 Docker、k3s、containerd、Node、Python、Bun、Go、Rust 或需要出网的包管理器安装步骤；它通过 `trans` 进入目标 host，并从 YAML 渲染本地监听、上游代理、Secret sourceRef、systemd 或等价 host 控制、健康探针和环境注入目标。
+
+host proxy client 的职责是给 k3s installer、containerd image pull、包管理器、Git、git-mirror sync/flush 和受控 host 依赖安装提供初始出网。provider-gateway 和 `trans` 是控制通道，不应承载大二进制和大量依赖下载的长期数据通道。k3s 安装、Argo/git-mirror/web-probe/哨兵等后续运行面必须通过 YAML 声明是否使用 host proxy route、in-cluster proxy Service 或 direct egress。
+
+host proxy 输出必须保持敏感信息边界。CLI 可以展示监听地址、端口、service 状态、sourceRef、fingerprint、probe 摘要和 `NO_PROXY` 覆盖状态；不得打印代理凭据、订阅内容、完整 URL credential、API key 或可复制密钥。`NO_PROXY` 必须保留本地、集群、metadata 和显式直连域，包括 `hyueapi.com` 与 `.hyueapi.com`。
+
+### 6.10 OPS-YAML-REQ-010 YAML 配置组合
+
+| 编号 | 短名 | 主责模块 | 关联模块 |
+| --- | --- | --- | --- |
+| OPS-YAML-REQ-010 | 配置组合 | PJ2026-01060312 配置组合 | [控制面模块化](PJ2026-01060307-control-plane-modularity.md)、[YAML目标治理](PJ2026-01060308-cicd-yaml-first-target-governance.md) |
+
+YAML运维应支持可复用、可继承、可组合的配置结构，使多个 node/lane 可以从公共 baseline、共享 configRef 和短 override 得到具体运行计划，而不是复制整段配置到每个节点文件。组合后的 effective plan 只作为执行和解释视图存在，不得写回为第二份可编辑真相源。
+
+变量渲染只能把 node、lane、service 等作为数据变量传入模板。YAML 文件名、解析函数名、渲染函数名、helper 名和 schema 名不得带具体 node/lane 名；具体 node/lane 只能出现在 YAML value、CLI 参数、外部系统要求的运行对象名或已分类 legacy adapter 中。
+
+当配置文件因重复 node/lane 块持续膨胀时，YAML运维应先拆出职责和公共 baseline，再继续新增目标。拆分边界包括 host bootstrap、proxy、k3s install、platform-infra、HWLAB lane、AgentRun lane、Secret sourceRefs、publicExposure、probes 和 sentinel schedules。超过 3000 行的代码、运维脚本或配置文件应先按职责拆分，再继续承载新能力。