Skip to content

docs: 补齐集成测试发现的 5 处文档缺口 - #779

Open
kingfs wants to merge 1 commit into
mainfrom
docs/itest-2026-10-14-gaps
Open

docs: 补齐集成测试发现的 5 处文档缺口#779
kingfs wants to merge 1 commit into
mainfrom
docs/itest-2026-10-14-gaps

Conversation

@kingfs

@kingfs kingfs commented Oct 14, 2026

Copy link
Copy Markdown
Collaborator

Summary

补齐集成测试中发现的 5 处文档缺口。来源是 agent-compose_sample 的
itest/2026-10-14-main-6200fcb7/FAILURES.md（被测区间 v2610.1.0..6200fcb7）。
只改 docs/pages（英文与 docs/pages/zh-CN 同步），未改动任何代码。

  • feat: Add DeepSeek provider with configurable default model #18 SKILL.md 的 frontmatter 是硬性要求但文档没写（agent-compose-yaml-manual.md 的 skills 一节）：
    原文只说「必须包含有效的 SKILL.md」。补齐首行 --- 围栏、name/description 必须非空、
    frontmatter 的 name 必须与配置一致，并给出三类内容问题的报错原文与报错时机对照表——
    它们只在 sandbox 启动期暴露，config/config --quiet 一律放过。
  • [Bug]: scheduler.exec() fails with "requires a request object" in v0.4.0-58 #12 microVM 驱动的 runtime base URL（driver 一节）：boxlite / microsandbox 会启动真正的内核、
    不加入 Docker 网络，因此既不解析 Docker Compose 服务名，也访问不到只发布在宿主回环上的 daemon。
    写明 AGENT_COMPOSE_RUNTIME_BASE_URL（或驱动级覆盖项）必须是 sandbox 自身可达的地址，
    且 daemon 要真的发布在该地址上，否则第一个 run --prompt 会以
    error sending request for url (http://<service-name>:<port>/api/runtime/…) 失败。
  • [Bug]: 智能体环境变量的信息排版问题 #32 sandbox_policy 的调用级选项陷阱（Scheduler 一节）：补上「任何调用级选项
    （title / driver / guestImage / workspaceId / env / volumes）都会让该次调用使用新的会话
    sandbox，sticky 绑定既不查也不写」。title 只是展示字段，所以给一个本来没变的调用加个标题，
    就会把 sticky 静默变成「每次一个新 sandbox」；而声明式 trigger 生成的是裸
    scheduler.agent(<prompt>)（仅在 trigger 自己声明策略时追加 { sandboxPolicy: … }），
    不受影响、仍在 sticky 路径上。
  • [Bug]: settings.json not updated after rebuilding guest image - source is embedded in daemon binary #21 down 会取消在飞的 scheduler run（command-line-manual.md）：被取消的 run 记为 failed
    • context canceled（若无法确认 guest 已停止还会带上 docker runtime could not confirm termination of guest execution），且 sandboxids 为空；关心 run 历史时应先等 scheduler 空闲再 down。
  • [Bug]: Daemon uses cached/stale image ID instead of latest rebuilt image #23 无签名无 token 的 webhook source（command-line-manual.md）：原文写「不能与另一个启用的
    source 共用 URL」，但实测 PUT 第二个源不会有任何预警（两次都 200）并会存下两个源，
    歧义直到真正投递时才以 409 {"error":"unsigned webhook source is ambiguous"} 暴露。
    改写为「不得共用」并说明实际的强制点。

Testing

$ task docs:build --force
✔ excludes temporary v1 migration fields from documentation coverage (3.0ms)
ℹ tests 1 / pass 1 / fail 0
Pages checks passed for 82 YAML schema fields and 12 public files

未运行 task lint / task build / task test：本 PR 只改 4 个 markdown 文件，这三个 gate 的范围是
Go / proto / installer / SDK，不覆盖 docs/pages；文档改动的适用 gate 是 task docs:build（已跑）。
未改动 pkg/compose/spec.go，因此没有 schema 覆盖面的新增与需要重新生成的产物。
5 处文案的每一条结论都来自区间内的实测记录，涉及的代码位置（pkg/schedulers/run_host.go:633-640、
pkg/schedulers/run_host_project_agent.go:99、pkg/agentcompose/adapters/scheduler_session_runner.go:139-140、
internal/projects/scheduler.go:62-65、pkg/skills/resolve.go:632）已逐条 sed/grep 复核。

Checklist

  • Documentation updated when behavior or configuration changed.
  • Tests added or updated for user-visible behavior.
  • No secrets, private endpoints, internal certificates, or local runtime state included.

第二条未勾选：本 PR 没有行为变更（纯文档），因此没有可新增或更新的用户可见行为测试；
文档自身的校验由 task docs:build 内的 schema-coverage.test.mjs 覆盖，已通过。

相关（本 PR 不关闭任何 issue）：#774 的文档面即本 PR 的 sandbox_policy 段落；其余产品侧问题见 #769–#778。

@kingfs
docs: 补齐集成测试发现的 5 处文档缺口
d1edae3 
来源：agent-compose_sample itest/2026-10-14-main-6200fcb7/FAILURES.md 的 12/18/21/23/32 条
（区间 v2610.1.0..6200fcb 的实测）。只改文档，不动代码；英文与 zh-CN 同步。

- #18 SKILL.md frontmatter（yaml-manual，skills 一节）：原文只说「必须包含有效的 SKILL.md」，
  未写 frontmatter 的存在、`---` 围栏、`name`/`description` 必须非空、frontmatter 的 `name`
  必须与配置一致，也没写这些内容规则**只在 sandbox 启动时**报错（`config` 一律放过）。
  补一段说明 + 三类报错与时机对照表。
- #12 microVM 驱动的 runtime base URL（yaml-manual，driver 一节）：boxlite/microsandbox
  启动真正的内核、不加入 Docker 网络，既不解析 Compose 服务名，也访问不到只发布在宿主回环上的
  daemon；`AGENT_COMPOSE_RUNTIME_BASE_URL` 必须是 sandbox 可达地址且 daemon 要发布在该地址上。
- #32 sandbox_policy 的实际作用域（yaml-manual，Scheduler 一节）：原文只写「sticky 允许绑定并
  复用 sandbox」。补的是**调用级选项**这个静默陷阱：`AgentRequestOverridesSession`
  （`pkg/schedulers/run_host.go:633-640`）把 `title`（纯展示字段）与
  `driver`/`guestImage`/`workspaceId`/`env`/`volumes` 一并算作 override，于是
  `useProjectAgentRun`（`run_host_project_agent.go:99`）返回 false、走会话路径且
  `forceNew=true`（`scheduler_session_runner.go:139-140`），sticky 绑定既不查也不写——
  给一个本来没变的调用加个 title 就会把 sticky 静默变成「每次一个新 sandbox」。
  声明式 trigger 生成的是裸 `scheduler.agent(<prompt>)`（`internal/projects/scheduler.go:62-65`），
  不带 override，因此仍在 sticky 路径上。（此结论修正了 FAILURES.md 原文把成因归为
  「脚本式 scheduler 无法 sticky」的判断；并行多 Agent 拒绝非 `new` 属有意限制，文档已有，未重复。）
- #21 `project down` 会取消在飞的 scheduler run（command-line-manual）：被取消的 run 记为
  `failed` + `context canceled`（可能附带无法确认 guest 终止），且 `sandboxids` 为空；
  关心 run 历史时应先等 scheduler 空闲。
- #23 无签名无 token 的 webhook source（command-line-manual）：原文写「不能与另一个启用的 source
  共用 URL」，实测 PUT 第二个源**不会预警**（两次 200），歧义在投递时以
  `409 unsigned webhook source is ambiguous` 报出。改写为「不得共用」+ 说明实际强制点。

校验：`task docs:build` 通过 —— `Pages checks passed for 82 YAML schema fields and 12 public files`
（含 schema-coverage 单测）。未改 `pkg/compose/spec.go`。
@kingfs kingfs added the documentation Improvements or additions to documentation label Oct 14, 2026
@monkeyscan

monkeyscan Bot commented Oct 14, 2026 •
edited
Loading

Copy link
Copy Markdown

评审任务执行失败。

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

documentation Improvements or additions to documentation

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@kingfs