docs: record provider profile online validation
Pipelines as Code CI / hwlab-web-probe-sentinel-nc01- Success
Pipelines as Code CI / hwlab-web-probe-sentinel-nc01- Success
This commit is contained in:
Codex
@@ -15,19 +15,7 @@ description: UniDesk Web 开发与浏览器验证技能。用户处理 UniDesk/H
|
||||
- 禁止在本地或 master server 直接跑 `vue-tsc` / 前端全量 typecheck 作为默认验证；本地只做语法级检查和真实入口复测，完整类型检查交给 CI、PipelineRun 或明确指定的受控构建运行面。
|
||||
- 桌面版 Web 截图、视觉复测和 web-probe 采样默认使用 `1920x1080` 视口；只有用户、issue 或 SPEC 明确指定其他尺寸时才覆盖，并在证据中写明覆盖原因。
|
||||
- Web probe 命令和历史判定口径见 [references/web-probe.md](references/web-probe.md)；Playwright/fake-server 复现见 [references/playwright.md](references/playwright.md)。
|
||||
- 前端改动遵循仓库既有设计系统和 `$frontend-design` 全局 UI 规则；不要做营销式落地页替代真实工具页面。
|
||||
|
||||
## 通用 Web 设计默认
|
||||
|
||||
- UniDesk/HWLAB 的工具页默认是工作界面，不是营销页：首屏直接呈现可操作对象、状态和主要任务流，避免 hero、装饰卡片和说明性大段文案。
|
||||
- 信息密度优先但要稳定：header 保持窄，source/file/project 等上下文选择放在顶部工具栏或状态栏下拉；计数、来源、taskRef、更新时间等元信息收敛到详情/感叹号弹窗，不长期占主版面。
|
||||
- 主内容区必须占优：树、大纲、列表和导航只作为左侧辅助视图，默认约 30% 或更小，并支持折叠或调整宽度；正文、报告、trace、消息或表格等主工作内容应占页面主要空间。
|
||||
- Workbench 类三栏/双栏工作区优先复用通用 bounded layout 组件或抽取通用组件后再接入新页面；不要为每个页面重新堆叠一套 `aside + main + report` CSS。根容器和 workspace 使用稳定高度、`min-height: 0` 和内部滚动，避免 document 级长页或外层横向溢出；窄桌面仍应保持可操作分栏，移动断点再退化为纵向布局。
|
||||
- 新建、配置、probe、reindex 等低频表单用对话框或抽屉承载；默认版面不要常驻新建框、配置表或调试面板。高频命令保留为稳定按钮或图标按钮，并配清晰状态。
|
||||
- 文档/任务类页面优先就地阅读和就地编辑：标题和正文双击或显式编辑态切换，不为常规查看单独铺满输入框；正文渲染态必须可见，不能只显示 taskRef、文件名或更新时间。
|
||||
- 报告、Markdown、日志和 JSON 片段要用成熟 Markdown/代码块渲染，代码块采用浅色 Workbench 风格、可滚动且不撑破布局；不要把裸 JSON 或长日志直接挤爆页面。
|
||||
- 页面状态要可深链：重要 source/file/task/report/session 选择进入 RESTful URL，并能刷新后恢复；联动其他功能只通过公共 API、稳定 id 和 URL，不把两个功能互相嵌入成强依赖。
|
||||
- 设计验收必须用截图或 web-probe 样本检查真实版面：正文是否可见、主区域是否足够、弹窗是否遮挡流程、长文本是否溢出、移动/窄屏是否仍可操作。桌面默认视口是 `1920x1080`；项目/MDTODO/报告类页面还应按风险覆盖紧凑桌面视口（例如 960x600）的深链默认态、左侧树折叠态、右侧报告关闭态。涉及报告渲染或布局重写时还必须覆盖右侧报告栏和报告全屏态。记录 document overflow、pane 宽高、正文/报告可见性、按钮是否被遮挡，以及截图 SHA。
|
||||
- 前端改动遵循仓库既有设计系统、[references/design.md](references/design.md) 和 `$frontend-design` 全局 UI 规则；不要做营销式落地页替代真实工具页面。
|
||||
|
||||
## web-probe 证据规则
|
||||
|
||||
@@ -42,6 +30,7 @@ description: UniDesk Web 开发与浏览器验证技能。用户处理 UniDesk/H
|
||||
- Workbench 性能卡顿调查优先用 `observe command --type performanceCapture` + `observe analyze` + `observe collect --view performance-summary`；`performance-summary` 必须保持首屏 bounded，只输出 LongTask/LoAF/event-loop gap 摘要、CPU profile hotspots/stacks 和 sourceFiles，下钻完整 profile/report 时再显式读取 artifact。
|
||||
- Project Management/MDTODO closeout 必须区分 `control` 页和被动 `observer` 页：显式 `observe command` 的 command result、control URL 和对应截图是用户动作证据；observer 周期刷新或 stop 后根路由空态只能作为对照信号，不能覆盖 command result。涉及报告的验收要同时记录 `reportPreviewVisible`、`reportFullscreenVisible`、报告 deep link 和截图 SHA。
|
||||
- MDTODO → Workbench launch 验收必须引用 `launchWorkbenchFromMdtodo` 的 command result，确认文件/任务选择、Workbench session、launch/chat 状态和 OTel trace header；不要只凭页面最终停在 Workbench URL 判断通过。
|
||||
- Workbench provider profile 验收使用 `observe command --type sendPrompt --provider <profile>` 时，command result 必须显示 `requestedProvider`、`providerSelection.selected`、`/v1/agent/chat` 202、traceId 和最终 `turn-summary`；只有 prompt 成功不够，必须确认浏览器控件实际选中目标 profile。
|
||||
- `observe analyze` 的 archive/history findings 可能包含旧样本或旧规则误判；关闭用户入口问题前同时核对最新 sample 字段、DOM 几何和截图。若 top-level findings、latest sample 和 archive red 冲突，说明冲突并补工具反馈 issue，不要只凭 archive red 或单张截图下结论。
|
||||
|
||||
## 高频工作流
|
||||
@@ -66,4 +55,5 @@ HWLAB Web probe、fixture 采集脱敏、Workbench/Performance 判定、Web E2E
|
||||
|
||||
- 需要 HWLAB Web probe 采集、observe/analyze、sentinel 或线上截图时，读 [references/web-probe.md](references/web-probe.md)。
|
||||
- 需要 fake-server 或 Playwright 复现时，读 [references/playwright.md](references/playwright.md)。
|
||||
- 需要做 UniDesk/HWLAB 页面布局、Workbench/Project Management 设计或视觉验收时，读 [references/design.md](references/design.md)。
|
||||
- 需要 Workbench/Performance 页判定口径时，读 [references/web-probe.md](references/web-probe.md)，不要凭经验补规则。
|
||||
|
||||
@@ -0,0 +1,13 @@
|
||||
# UniDesk Web Design Defaults
|
||||
|
||||
本文件记录 UniDesk/HWLAB Web 工具页的长期设计默认。`SKILL.md` 只保留入口索引；实际做前端布局、Workbench/Project Management 页面或视觉验收时读取本文件。
|
||||
|
||||
- UniDesk/HWLAB 的工具页默认是工作界面，不是营销页：首屏直接呈现可操作对象、状态和主要任务流，避免 hero、装饰卡片和说明性大段文案。
|
||||
- 信息密度优先但要稳定：header 保持窄，source/file/project 等上下文选择放在顶部工具栏或状态栏下拉；计数、来源、taskRef、更新时间等元信息收敛到详情/感叹号弹窗，不长期占主版面。
|
||||
- 主内容区必须占优：树、大纲、列表和导航只作为左侧辅助视图，默认约 30% 或更小，并支持折叠或调整宽度；正文、报告、trace、消息或表格等主工作内容应占页面主要空间。
|
||||
- Workbench 类三栏/双栏工作区优先复用通用 bounded layout 组件或抽取通用组件后再接入新页面；不要为每个页面重新堆叠一套 `aside + main + report` CSS。根容器和 workspace 使用稳定高度、`min-height: 0` 和内部滚动，避免 document 级长页或外层横向溢出；窄桌面仍应保持可操作分栏，移动断点再退化为纵向布局。
|
||||
- 新建、配置、probe、reindex 等低频表单用对话框或抽屉承载；默认版面不要常驻新建框、配置表或调试面板。高频命令保留为稳定按钮或图标按钮，并配清晰状态。
|
||||
- 文档/任务类页面优先就地阅读和就地编辑：标题和正文双击或显式编辑态切换，不为常规查看单独铺满输入框；正文渲染态必须可见，不能只显示 taskRef、文件名或更新时间。
|
||||
- 报告、Markdown、日志和 JSON 片段要用成熟 Markdown/代码块渲染，代码块采用浅色 Workbench 风格、可滚动且不撑破布局；不要把裸 JSON 或长日志直接挤爆页面。
|
||||
- 页面状态要可深链：重要 source/file/task/report/session 选择进入 RESTful URL，并能刷新后恢复；联动其他功能只通过公共 API、稳定 id 和 URL，不把两个功能互相嵌入成强依赖。
|
||||
- 设计验收必须用截图或 web-probe 样本检查真实版面：正文是否可见、主区域是否足够、弹窗是否遮挡流程、长文本是否溢出、移动/窄屏是否仍可操作。桌面默认视口是 `1920x1080`；项目/MDTODO/报告类页面还应按风险覆盖紧凑桌面视口（例如 960x600）的深链默认态、左侧树折叠态、右侧报告关闭态。涉及报告渲染或布局重写时还必须覆盖右侧报告栏和报告全屏态。记录 document overflow、pane 宽高、正文/报告可见性、按钮是否被遮挡，以及截图 SHA。
|
||||
@@ -107,7 +107,11 @@ AgentRun YAML-only lane 发布收口必须以当前 k8s git-mirror snapshot tip
|
||||
|
||||
YAML-only lane 的 `trigger-current` 会先确保目标 branch 已同步到 k8s git-mirror snapshot，再从 UniDesk YAML 声明的 image build、GitOps branch/path、runtime namespace、Secret、数据库和 manager env 渲染 artifact catalog 与 GitOps desired state。该路径会删除新 lane source branch 中的 `deploy/deploy.json`，因为部署真相已经迁入 UniDesk YAML；旧 `v0.2` branch 中历史文件只作为迁移前遗留产物存在，不能作为新 lane 的事实来源。Secret export 格式或外部数据库连接参数变化时，先用 `platform-db postgres export-secrets --confirm` 物化本地 Secret source，再用 `agentrun control-plane secret-sync --node <node> --lane <lane> --confirm` 下发，最后用 `agentrun control-plane restart --node <node> --lane <lane> --confirm` 让 manager Deployment 通过 rollout 读取新 Secret；不要手工删除 Pod 或直接 patch Secret。
|
||||
|
||||
Provider credential Secret 的 `auth.json` 和 `config.toml` 也必须按 NC01 lane 的 YAML `sourceRef` 下发，不能把指挥机全局 Codex 配置当成运行真相。lane 的模型、provider、endpoint 和 Codex runtime options 需要由 UniDesk YAML 拥有时，使用 `sourceMode: codex-config` 和同一 Secret spec 下的 `codexConfig` 渲染 `config.toml`；不要通过修改 `/root/.codex/config.toml` 或 `~/.codex/config.toml` 来改变 HWLAB/AgentRun 运行面模型。HWLAB 通过 NC01 `agentrun-v02` 使用 Codex profile 时，`config.toml` 应只携带该 lane 需要的 Codex CLI runtime options，例如 model、reasoning、context window、auto compact、storage 和 network 相关键；除非对应 `auth.json` / API key source 也由同一 lane 明确拥有并已验证，否则不要在 lane config 中覆盖 provider endpoint、`base_url`、`model_provider` 或其他 endpoint 绑定。常见回归有两类：同步到 runner 的 config 缺少 `model_context_window` / `model_auto_compact_token_limit`，导致多轮 tool/webSearch 后报 context-window failure；或者为了补参数误加不匹配的 provider endpoint，导致 provider auth failure。修复必须走 `agentrun control-plane secret-sync --node NC01 --lane nc01-v02` 的 dry-run/confirm，再用 `restart` 生效，并通过 HWLAB `hwlab-cli client agent send|trace|result` 原入口验证；不要从 Kubernetes Secret 反解配置内容或在 issue/trace 中打印 payload。
|
||||
Provider credential Secret 的 `auth.json` 和 `config.toml` 也必须按 NC01 lane 的 YAML `sourceRef` 下发，不能把指挥机全局 Codex 配置当成运行真相。lane 的模型、provider、endpoint 和 Codex runtime options 需要由 UniDesk YAML 拥有时，使用 `sourceMode: codex-config` 和同一 Secret spec 下的 `codexConfig` 渲染 `config.toml`；不要通过修改 `/root/.codex/config.toml` 或 `~/.codex/config.toml` 来改变 HWLAB/AgentRun 运行面模型。
|
||||
|
||||
AgentRun runtime provider profile 的标准在线配置入口是 `bun scripts/cli.ts agentrun provider-profile plan|status|apply|validate --node NC01 --lane nc01-v02 --profile <profile>`。`plan/status` 必须输出 YAML 声明的 profile、backendProfile、SecretRef/key、fingerprint、runner egress/NO_PROXY 和 `valuesPrinted=false`；`apply --confirm` 只同步选中 profile 的 Secret/config、复用当前 manager image 渲染 GitOps、刷新 Argo 并重启 manager，不触发 image rebuild 或 PipelineRun；`validate` 只能作为配置和运行面可见性预检，不能替代 HWLAB Web/CLI 原入口真实 turn。需要确认某个 profile 已上线时，先跑 `provider-profile status` 看 live Secret fingerprint 和 manager env，再用 HWLAB Web dispatcher 等价入口创建新 session 并发送一轮真实 prompt。Web 入口验证优先使用 `web-probe observe start` + `observe command --type newSession` + `observe command --type sendPrompt --provider <profile>`，证据应包含 providerSelection、`/v1/agent/chat` 202、traceId、terminal turn 和 Final Response。
|
||||
|
||||
HWLAB 通过 NC01 `agentrun-v02` 使用 Codex profile 时，`config.toml` 应只携带该 lane 需要的 Codex CLI runtime options，例如 model、reasoning、context window、auto compact、storage 和 network 相关键；除非对应 `auth.json` / API key source 也由同一 lane 明确拥有并已验证，否则不要在 lane config 中覆盖 provider endpoint、`base_url`、`model_provider` 或其他 endpoint 绑定。常见回归有两类：同步到 runner 的 config 缺少 `model_context_window` / `model_auto_compact_token_limit`，导致多轮 tool/webSearch 后报 context-window failure；或者为了补参数误加不匹配的 provider endpoint，导致 provider auth failure。修复必须走 `agentrun provider-profile apply --node NC01 --lane nc01-v02 --profile <profile> --confirm` 或对应 `control-plane secret-sync/restart`，并通过 HWLAB Web/CLI 原入口验证；不要从 Kubernetes Secret 反解配置内容或在 issue/trace 中打印 payload。
|
||||
|
||||
AgentRun resource/session client policy 也由 `config/agentrun.yaml` 声明。`client.sessionPolicy` 是未显式选择 node/lane 时 `agentrun send session/...` 和相关 session payload 生成的默认 `tenantId`、`projectId`、`providerId`、`backendProfile`、`workspaceRef` 和 execution policy 来源；显式 `--node <node> --lane <lane>` 后，`explain session-policy`、`send session`、resource primitives 和 AipodSpec render 都必须改用目标 lane 的 YAML 事实。lane `secrets[].providerCredential.profile` 声明 provider credential Secret 归属，UniDesk CLI 只按 YAML 聚合 Secret name/key，不再用代码拼接 provider Secret 名称。只读入口 `bun scripts/cli.ts agentrun explain session-policy` 用于查看选中目标 lane、policy 来源、实际 executionPolicy payload 和 provider credential binding 来源；输出只能包含 Secret metadata、key 名和 `valuesPrinted=false`，不得打印 Secret value。
|
||||
|
||||
|
||||
@@ -191,7 +191,7 @@ HWLAB 与 AgentRun 协同修复必须按 `docs/reference/agentrun.md` 的职责
|
||||
|
||||
本小节只适用于 NC01 `v0.3` provider profile。配置必须先按 `config/hwlab-node-lanes.yaml` 解析 NC01 运行面，再读取目标 HWLAB repo 的对应规则；AgentRun 内部 Secret 物化和 backend adapter 设计仍以 AgentRun 仓库自身为准。
|
||||
|
||||
Provider profile 必须通过已部署的 NC01 HWLAB Cloud API/CLI 管理，正式入口是 `hwlab-cli client provider-profiles`；不要把手工 patch AgentRun Secret、直接调用 AgentRun manager 或临时 runner job 当作正式配置路径或关闭证据。
|
||||
Provider profile 有两条不同职责的正式路径，不能混用。HWLAB 产品侧动态 profile 通过已部署的 NC01 HWLAB Cloud API/CLI 管理，入口是 `hwlab-cli client provider-profiles`。AgentRun runtime lane 自身的 provider credential、`config.toml`、`auth.json`、runner egress/NO_PROXY 和 GitOps 物化由 UniDesk `config/agentrun.yaml` 拥有，入口是 `bun scripts/cli.ts agentrun provider-profile plan|status|apply|validate --node NC01 --lane nc01-v02 --profile <profile>`；该路径支持在线配置 profile，不要求 image rebuild 或 PipelineRun。不要把手工 patch AgentRun Secret、直接调用 AgentRun manager、临时 runner job、修改 `~/.codex/config.toml` 或修改 `/root/.codex/config.toml` 当作正式配置路径或关闭证据。
|
||||
|
||||
当明确需要把当前 operator 的 Codex 凭据作为 AgentRun 动态 profile 提供给 HWLAB Code Agent 或 CaseRun 使用时，固定操作手册在 `$hwlab-code-agent` 的 `AgentRun 动态 sub2api profile` 小节。该场景是 AgentRun runtime profile 投影，不替代上面的 HWLAB provider-profiles 正式配置路径；默认 profile 名为 `sub2api`、模型为 `gpt-5.5`，优先使用 NC01 k3s 内受控 Sub2API ClusterIP 作为 `base_url`，并只记录 SecretRef、keyPresence、hash suffix 和原入口验收结果。
|
||||
|
||||
@@ -207,7 +207,7 @@ bun tools/hwlab-cli/bin/hwlab-cli.ts client provider-profiles list --no-session
|
||||
|
||||
AgentRun `v0.1` 运行面物化对象是 `agentrun-v01` namespace 中的 `agentrun-v01-provider-<profile>` Secret。基础 Codex profile 的稳定 key 是 `config.toml` 和 `auth.json`；需要本地模型目录的 profile 还必须按 AgentRun backend profile 声明补齐额外 key，例如 `dsflash-go` 必须同时具备 `model-catalog.json`，且 `config.toml` 中的 `model_catalog_json` 指向 runner 内 profile-local catalog 路径。文档、issue、trace 和 CLI 输出只能记录 profile 名、SecretRef、key 是否存在、字节数、redacted hash/hash suffix、resourceVersion 和验证结果；不得记录 Secret value、完整 `auth.json`、provider token、完整 API key 或可复用凭据命令。
|
||||
|
||||
profile 配置后的最小真实验收是通过同一 HWLAB v0.2 Cloud API/Web dispatcher 路径创建 Code Agent session 并完成一轮真实 turn：`client agent session create --provider-profile <profile>`，再 `client agent send --session-id <sessionId> --provider-profile <profile>`，最后用 `client agent result <traceId>` 和 `client agent trace <traceId> --render web` 确认终端状态和最终 assistant 文本。只看到 Secret 存在、AgentRun canary 通过、PipelineRun 成功或源码测试通过，都不能替代这一真实入口验收。对 profile-sensitive CaseRun 或 provider 修复，关闭证据还必须来自原入口 `case run`/Web 等价路径，结果中应同时显示 `requestedProviderProfile`、`resolvedBackendProfile`、AgentRun `backendProfile`、模型名和终端状态；涉及 ds-flash/Moon Bridge 时，还要确认 `deepseek-v4-flash`、1M context/model catalog 元数据生效，且归档中不再出现 `responses/compact 404` 或 `404 page not found`。当前 HY 凭据对的稳定 profile 名是 `hy`；复测时使用同一标准入口，不在任何长期文档或 issue 中记录凭据内容。
|
||||
profile 配置后的最小真实验收是通过同一 HWLAB Cloud API/Web dispatcher 路径创建 Code Agent session 并完成一轮真实 turn。CLI 路径使用 `client agent session create --provider-profile <profile>`，再 `client agent send --session-id <sessionId> --provider-profile <profile>`，最后用 `client agent result <traceId>` 和 `client agent trace <traceId> --render web` 确认终端状态和最终 assistant 文本。Web 路径使用 UniDesk `web-probe observe start --node NC01 --lane v03 --target-path /workbench`，再 `observe command --type newSession` 和 `observe command --type sendPrompt --provider <profile>`；证据必须包含新 session id、`providerSelection` 选中目标 profile、`/v1/agent/chat` 返回 202、traceId、terminal turn 和 Final Response。只看到 Secret 存在、AgentRun canary 通过、PipelineRun 成功或源码测试通过，都不能替代这一真实入口验收。对 profile-sensitive CaseRun 或 provider 修复，关闭证据还必须来自原入口 `case run`/Web 等价路径，结果中应同时显示 `requestedProviderProfile`、`resolvedBackendProfile`、AgentRun `backendProfile`、模型名和终端状态；涉及 ds-flash/Moon Bridge 时，还要确认 `deepseek-v4-flash`、1M context/model catalog 元数据生效，且归档中不再出现 `responses/compact 404` 或 `404 page not found`。当前 HY 凭据对的稳定 profile 名是 `hy`；复测时使用同一标准入口，不在任何长期文档或 issue 中记录凭据内容。
|
||||
|
||||
CaseRun 的 case/registry/aggregate、评价、回放、训练反馈和硬件证据闭环需求以 UniDesk OA 的 [PJ2026-0103 HarnessRL](../../project-management/PJ2026-01/specs/PJ2026-0103-harness-rl.md) 为权威；HWPOD 服务、AI 网关和 HWLAB 到 AgentRun 的装配接入分别以 [PJ2026-010103 HWPOD服务](../../project-management/PJ2026-01/specs/PJ2026-010103-hwpod-service.md)、[PJ2026-010104 AI网关](../../project-management/PJ2026-01/specs/PJ2026-010104-ai-gateway.md) 和 [PJ2026-010205 HWLAB接入](../../project-management/PJ2026-01/specs/PJ2026-010205-hwlab-dispatch.md) 为权威。HWLAB 仓库内 `docs/reference/spec-hwpod-harness.md` 只保留历史交叉引用 stub；UniDesk 指挥侧按 issue/CLI 选中的 node/lane 重新读取 HWLAB `AGENTS.md`、使用目标 workspace 原入口验证，并在关闭 issue 时记录 runId、traceId、provider profile、registry commit 和负向检索摘要。不要在 UniDesk reference 里复写 CaseRun prompt 细则或 `.agents/skills` 装配实现。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user