From 633b41394cab70eb31620697286fbdea8eff9bb5 Mon Sep 17 00:00:00 2001 From: anonsaber Date: Tue, 29 Sep 2026 12:25:08 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=9B=9E=E7=AD=94=20hoststack.yaml=20?= =?UTF-8?q?=E7=9A=84=E6=9D=A5=E5=8E=86=E4=B8=8E=E5=AE=98=E6=96=B9=E5=81=9A?= =?UTF-8?q?=E6=B3=95=EF=BC=8C=E8=A1=A5=E4=B8=8A=E5=91=BD=E4=BB=A4=E5=AD=97?= =?UTF-8?q?=E6=AE=B5=E4=B8=8D=E5=9B=9E=E5=86=99=E7=9A=84=E8=AF=81=E6=8D=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 回答用户追问「这个文件哪里来的、官方推荐怎么做」。git 考古 + agent 源码两条路： 来历：a571033 自己手写的（2026-09-25），不是 HostStack 生成的。agent 镜像里既没有 init 类命令也没有内嵌模板 YAML（find 全仓 0 个 yaml 文件），只负责在仓库根读取 hoststack.yaml 或 hoststack.yml。所以"官方推荐怎么写"没有标准模板可抄，只有 schema。 官方做法：源码自己的定位是 Infrastructure-as-Code—— "hoststack.yaml is Infrastructure-as-Code: when the repo declares a command, it wins over whatever happens to be cached on the services row" 新证据，把"UI 更方便管理"这个前提彻底否掉：agent 里只有两个 YAML->DB 回写事件 （yaml_port_declared、yaml_disk_declared），**命令字段没有**。注释原文明说 "the two that need to reach the services row have their own handled frames"。 所以每次部署都是拿 YAML 临时覆盖 services 行里的旧值，DB 里永远是过期的 ./target/release/app。port 与 disk 要回写是因为 autoscaling 和 sleep-wake 直接 读那行；命令只有部署路径自己读，不值得持久化。 结论：控制台对命令字段永远是过期缓存，不存在"以 UI 为准"的稳态。 要删 hoststack.yaml，必须先改控制台那三条命令，文档里已有此前提。 audit_paths.py：hoststack.yml 加入 CONVENTIONAL allowlist——它是 yaml-parser 实际接受的第二种文件名，与已在白名单里的 docker-compose.yml 同类。 验证：GATE-DOCS PASS 6/6（PATH AUDIT 378 path-refs / 0）。 --- docs/deployment.md | 15 +++++++++++++++ scripts/docs_check/audit_paths.py | 3 +++ 2 files changed, 18 insertions(+) diff --git a/docs/deployment.md b/docs/deployment.md index f11ce40..334a6af 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -165,6 +165,21 @@ services 表里已存的值填进 payload，再用 `hoststack.yaml` 声明的值 > 但按上面的优先级，**这个前提不成立**——直接删 YAML 服务起不来。**当前决定：保留 > `hoststack.yaml`。** 保留的代价是双写（在控制台改命令不会生效，必须改 YAML）； > 保留的理由是部署命令进入 git 历史、可 review 可回滚，而控制台值散在平台侧、改动无痕迹。 +> +> **这个双写不是我们多此一举，命令字段从设计上就不回写控制台**：agent 源码里只有 +> `yaml_port_declared` 与 `yaml_disk_declared` 两个回写事件，**命令没有**——每次部署都是 +> 拿 YAML 临时覆盖 services 行里的旧值。`port` 与 `disk` 之所以要回写，是因为 +> autoscaling 与 sleep-wake 直接读那行；命令只有部署路径自己读，所以不值得持久化。 +> 结论是控制台对命令字段永远是过期缓存，**不存在"以 UI 为准"的稳态**——这也是 HostStack +> 把它叫 Infrastructure-as-Code 的原因（源码原文：*hoststack.yaml is +> Infrastructure-as-Code: when the repo declares a command, it wins over whatever happens +> to be cached on the services row*）。 +> +> **关于这个文件的来历**：它不是 HostStack 生成的，也没有官方模板可抄——agent 镜像里 +> 既没有 `init` 类命令也没有内嵌的模板 YAML，只负责在仓库根读取 `hoststack.yaml` 或 +> `hoststack.yml`。本文件是 `a571033` 手写的，所以"官方推荐怎么写"没有标准答案，只有 +> schema（见上一条的未知键行为）。 +> > **若日后确要移除**，必须**先在控制台把三条命令改对**（install = `cargo fetch --locked`、 > build = `cargo build --release --locked`、start = `./target/release/message-weave`）， > 再删本文件并重新部署一次验证；同时把本段连同该前提移到 `docs/retired.md` 并记下 diff --git a/scripts/docs_check/audit_paths.py b/scripts/docs_check/audit_paths.py index 8ab787f..dc4b857 100644 --- a/scripts/docs_check/audit_paths.py +++ b/scripts/docs_check/audit_paths.py @@ -113,6 +113,9 @@ CONVENTIONAL = { "docker-compose.yml": "docker compose's default filename; deployment.md " "states the repo ships no compose file and gives the " "image-based command instead", + "hoststack.yml": "second filename HostStack's yaml-parser accepts alongside " + "hoststack.yaml; deployment.md names both while the repo " + "ships only the .yaml variant", } # --- non-path shapes that look like paths -----------------------------------