diff --git a/.agents/skills/unidesk-cicd/SKILL.md b/.agents/skills/unidesk-cicd/SKILL.md index bde8c7b7..faeeb049 100644 --- a/.agents/skills/unidesk-cicd/SKILL.md +++ b/.agents/skills/unidesk-cicd/SKILL.md @@ -91,7 +91,15 @@ bun scripts/cli.ts hwlab nodes control-plane legacy-cicd --help - 默认使用 `pipelines-as-code bootstrap --dry-run|--confirm`,不再人工串联 Gitea bootstrap 与 PaC apply; - `apply` 必须在任何 release、RBAC、Secret、Repository CR、Argo 或 webhook 写入前确认 YAML 匹配的 Gitea 仓库已存在; - source PR 合并后不得再次调用 bootstrap 或 apply;正常验收不串联 mirror/status/history,只有失败归因才逐层下钻。 -- 自动链路不通时必须修复自动链自身,并通过修复 PR 合并产生的新正常事件验收。禁止人工 mirror sync、直接 Gitea push、人工 PipelineRun、`trigger-current`、运行面 patch 或其他手段补齐当前交付;只读 status/history/events/logs/debug-step 可用于定位,但不得改变交付状态。`closeout` 只属于显式 compatibility diagnostics,不得进入默认观察或恢复路径。 +- 自动链路不通时必须修复自动链自身,并通过修复 PR 合并产生的新正常事件验收: + - 禁止人工 mirror sync、直接 Gitea push、人工 PipelineRun、`trigger-current` + 或其他手段补齐当前交付; + - 调试或临时恢复确需改变运行面时,允许按 `$unidesk-daddev` P2 实施最小、可逆 patch, + 但不得修改 source/ref authority、伪造交付成功或作为最终验收; + - P2 结论必须收敛到 owning YAML、controller 或源码, + 再由修复 PR 的正常自动事件交付;临时 patch 必须撤销或被声明式交付覆盖; + - 只读 status/history/events/logs/debug-step 仍是默认定位入口, + `closeout` 只属于显式 compatibility diagnostics,不得进入默认观察或恢复路径。 - CI/CD、GitOps、rollout、PipelineRun、Argo、git-mirror 和 AgentRun 的观察、诊断与 legacy 控制必须走受控 CLI;不要用裸 `kubectl`、`argo`、`tkn`、`curl` 当正式控制入口。PaC migrated consumer 仍只由 GitHub PR merge 触发,不得因“必须走 CLI”而额外调用写命令。 - CI/CD 校验默认不得阻塞交付: - 除非用户明确要求某项校验成为门禁,禁止新增会让 Pipeline、artifact、GitOps promote、Argo reconcile、runtime rollout 或 `/health` closeout 失败的配置一致性、版本、契约、schema、preflight 或跨对象校验; diff --git a/.agents/skills/unidesk-daddev/SKILL.md b/.agents/skills/unidesk-daddev/SKILL.md new file mode 100644 index 00000000..c807e0a0 --- /dev/null +++ b/.agents/skills/unidesk-daddev/SKILL.md @@ -0,0 +1,98 @@ +--- +name: unidesk-daddev +description: UniDesk 分布式敏捷开发流程,覆盖真实运行面探测、最小可逆 patch/热补实验、YAML/Git/自动 CI/CD 持久化和原入口验收。处理跨节点、跨 host、跨 lane 的 bug、HotFix、运行面调试、临时恢复或对接 HWLAB/AgentRun/UniDesk 真实运行面时必须使用。 +--- + + +# 分布式敏捷开发流程 + +> 遵循规范: 本 Skill 遵循 [Skill(cli-spec)](file:///root/.agents/skills/cli-spec/SKILL.md) 规范(精简版,仅保留与流程相关的硬约束)。 + +## DAD-DEV SPEC + +- 流程与交付 + - 现场闭环 + - unidesk-daddev 不是固定发布脚本,而是现场修复闭环。 + - P1 先在真实 provider / host / pod / lane 上观察事实,再判断根因。 + - P2 用最小、可撤、可解释的运行面实验或等价实验验证方向。 + - P2 允许按调试需要实施运行面 patch 或热补: + - 只用于验证根因、缩小故障面或临时恢复用户入口; + - 开始前记录目标对象、现状、预期、影响范围和回退方式; + - 选择最小变更,避免数据迁移、Secret 反解、不可逆写入和第二 authority; + - 不得把 patch 制造的状态当作 GitOps desired、自动交付成功或最终验收证据。 + - P3 把有效修复收敛回 Git、项目声明的交付路径和可审计 provenance。 + - P3 必须把 P2 中成立的变更收敛到正式交付: + - 写回 owning YAML、源码或受控 renderer; + - 通过正常 PR 和自动 CI/CD/GitOps 交付; + - 主动撤销临时 patch,或确认它已被声明式交付覆盖; + - 禁止长期保留隐藏运行面真相。 + - P4 用用户报告的同一入口或 Web 等价 CLI 验收;单测、PR、构建和理论推导不能单独关闭 issue。 + - 项目适配器 + - 本 skill 只规定阶段目标、边界和证据合同。 + - 分支、workspace、PR、rollout、git mirror、artifact、issue close 命令属于目标项目适配器。 + - 命令细节以目标仓库当前 `AGENTS.md`、`docs/reference/*.md` 和 CLI help/source 为准。 + - 发现 skill 示例与当前 CLI 不一致时,先修正引用或工具,不绕到原生命令。 + - UniDesk `trans` / `tran` 命令遵循当前 operation 合同: + - `script` 和 `shell` operation 已移除; + - 跨 host / k3s POSIX shell 示例必须显式使用 `sh` 或 `bash`; + - 检索含 Markdown 反引号的命令片段时使用单引号或 `rg -F -e`; + - 禁止让本地 shell command substitution 误触旧命令。 + - 固定主 repo 保护 + - 执行任何会产生源码、文档、配置、issue closeout、部署脚本或验收产物的 unidesk-daddev 工作前,必须先从目标 fixed repo 的最新 remote/base 创建独立 `.worktree/`,后续编辑、验证、提交、推送和受控 CLI 都在该 worktree 内执行。 + - fixed repo 只用于 `git fetch`、`git status`、`git worktree add` 和读取规则;禁止把 fixed repo 当 scratch 区直接编辑,也不要把其中既有未提交修改纳入当前任务。 + - fixed repo 若已有并行未提交修改,默认保持不动;用独立 worktree 隔离当前任务,除非用户明确要求合并、清理或提交这些修改。 + - 只有 P1 只读探测、运行面热补或目标项目明确声明可直接改 fixed repo 的轻量例外,才允许不创建新 `.worktree`;例外必须先说明理由并避免触碰并行修改。 + - 纯文档编辑可以按 `$git-spec` 的稳定分支快路径由主代理直接 commit/push,不要求独立 `.worktree` 或 PR;本地分支分叉、存在并行状态或涉及运行配置时不适用。 + - Skill 自身更新边界 + - 本 skill 是流程规范,不是普通任务产物;除非用户明确要求更新 `unidesk-daddev` / `SKILL.md`,不得在业务任务、文档收敛、issue closeout 或临时纠偏中自动修改本 skill。 + - 发现本 skill 与当前用户要求或项目规则冲突时,先按用户要求和项目规则完成任务;需要改 skill 的事项提 issue 或请示用户,不把 skill 更新夹带进默认交付。 + - 交付画像 + - 需要运行面发布 + - `pr-rollout`:独立 worktree → 分支 → PR → merge → CI/CD / rollout → runtime validation。 + - `artifact-deploy`:提交后由 CI 产出 commit-pinned artifact,CD 只消费 artifact,不从脏 worktree 构建。 + - 轻量或治理交付 + - `pr-lightweight`:无服务 CLI、helper、docs、config、CaseRun、trace 和治理类变更的标准画像;独立 worktree → 分支 → PR → 合并,可按项目规则自合并,合并后跳过 CI/CD/rollout。 + - `config-docs-only`:无运行面 rollout 的文档/配置治理,是 `pr-lightweight` 的子类;仍需 Git/PR 证据和必要的渲染、语法或引用验证。 + - 恢复后补账 + - `runtime-recovery-followup`:紧急运行面恢复后,必须回补 source、runbook 或 remediation issue,不能保留隐藏 runtime truth。 + - 无服务 / CI-CD SKIP + - 适用范围 + - 不涉及 cloud-api、web、gateway、GitOps、k3s runtime 或其他常驻服务的改动,默认走 `pr-lightweight`:独立 worktree、分支、PR,可自合并,可跳过 CI/CD/rollout。 + - 典型范围:markdown/reference/runbook/comments、CLI 工具、helper 脚本、CaseRun、harness、trace 语义化、case registry 产物整理、短连接调试 runner、无运行面影响的配置/治理。 + - 交付边界 + - 无服务任务必须直接运行和验证目标工具链;PR 合并后不走 CI/CD、rollout 或服务发布大回环。 + - `pr-lightweight` PR 合并后即视为交付完成;关闭 issue 时写明 `rollout=not-applicable` 或等价说明。 + - CaseRun 单步 + - CaseRun 卡在基础设施、hwpod-node、workspace prepare、编译、下载、串口或 artifact 收集时,先拆成同一目标运行面的单步命令验证。 + - 只有单步通过且需要验证完整编排、trace 和 registry 产物时,才启动一次完整 CaseRun。 + - 完整 CaseRun 仍遵循 cli-spec:异步启动、短轮询、可见 trace;不得把 evidence 自动评价、门禁或自动判断重新加回流程。 +- 路径与边界 + - 架构收敛 + - 分布式修复优先收敛到单一权威路径。 + - 先识别 source of truth,再删除或降级会制造分叉的派生缓存、旧入口、兼容路径和 fallback。 + - 不用多路径、fallback、feature flag、legacy mode 或额外 guard 掩盖根因。 + - 已有多路径造成状态污染、可见性歧义或反复修复无效时,把读写路径统一到权威状态;其他状态只作为可重建派生证据,或直接移除。 + - CLI/Web 同路径 + - 定位上下文 + - CLI 只能作为 Web 的非视觉等价入口,不能变成绕过 Web 的第二条业务路径。 + - 先识别 Web 原入口的 `origin/lane/account/workspace/session/conversation/trace` 和实际 route / API family / dispatcher。 + - 等价调用 + - 正式 CLI 必须调用同一 Web origin、同一后端 dispatcher、同一账号状态和同一 session / trace 语义。 + - CLI 输出必须包含 `baseUrl`、`route`、`method/path`、session/trace/job id、runtime endpoint 来源。 + - 长任务用 submit-and-poll;CLI 先提交,后续短查询 result / trace / inspect,不为 Web E2E 长挂单个远程命令。 + - 不一致处理 + - CLI 和 Web 结果不一致时,先分类为 `path-mismatch`、`state-mismatch`、`auth-mismatch`、`runtime-mismatch` 或 `visibility-gap`,把实际上下文写入 issue 证据,再补 CLI 同路径入口或可见性。 + - 内部 direct manager、手写 dispatcher、临时 runner job、裸 API、fixture、本地 DOM 结果只能作为 canary / 定位证据,不能替代 Web 同路径验收。 +- 证据与验证 + - Issue 评论 + - 正文先行 + - Issue 评论不是机器日志归档。 + - P1 进展、P2 闭环、P3 rollout、P4 closeout 和 blocker 评论,都先用自然语言说明用户现象、根因、修改、验证状态和剩余边界。 + - 审计证据 + - 正文之后再列命令、trace、job id、PR、PipelineRun、artifact、SHA 等证据。 + - 推荐结构:2-5 段短正文说明"发生了什么 / 怎么修 / 怎么验收 / 现在状态",再用 bullets 列关键命令、trace、job、commit、rollout 耗时和产物信息。 + - 阻塞说明 + +## 扩展参考 + +低频细节见 [references/details.md](references/details.md)。紧凑流程不足以支撑任务时读取该文件。 diff --git a/.agents/skills/unidesk-daddev/references/details.md b/.agents/skills/unidesk-daddev/references/details.md new file mode 100644 index 00000000..0bb96e6d --- /dev/null +++ b/.agents/skills/unidesk-daddev/references/details.md @@ -0,0 +1,206 @@ +# UniDesk 分布式敏捷开发扩展参考 + +本文件承载从 `SKILL.md` 拆出的低频细节,保持高频路由文件紧凑。 + + - 阻塞评论必须讲清"为什么这是阻塞、它和当前 issue 的关系、下一步怎么解阻"。 + - 不能只贴错误码、stack、JSON 摘抄或 ID 清单。 + - 两层验证 + - 源码层快速回归 + - P1 定位根因后,默认找最小代码路径,用单元测试、合同测试、fake store、fake HTTP request、fake runtime env 等复现 bug。 + - 修复后的目标行为必须固化成可重复运行的测试。 + - 能 mock 的 bug 必须补源码层测试再进入 PR。 + - 真实运行面验收 + - CLI / Web 等价 / 原入口层必须打到目标 lane / URL / namespace / provider / device-pod / trace dispatcher,证明已发布 runtime 真的修好。 + - 单元/mock 通过不能关闭 issue,关闭仍必须有 P4 原入口或真实 runtime 验收。 + - 缺层说明 + - 真实入口通过也不能替代可行的源码层回归测试。 + - 没补源码层测试时,PR/issue 必须说明硬件物理状态、第三方 provider 非确定行为、缺少可注入边界且本次不宜扩 scope 等具体原因,并考虑最小合同、parser、env/配置选择测试或 follow-up issue。 + - Closeout 必须同时写清两层证据;任一层不适用时写明原因。 + +## 4 阶段流程 + +``` +┌────────────────────────────────────────────────────────────────────┐ +│ P1 实地探测 → P2 最小运行面实验 → P3 持久化交付 → P4 原入口验收 │ +│ SSH 透传定位根因 热补丁/替代实验 Git/项目交付收敛 用户入口复测 │ +│ 只读优先,可控探针 能热补就热补 按项目适配器执行 证据落 issue │ +└────────────────────────────────────────────────────────────────────┘ +``` + +### P1:SSH 透传实地探测(只读优先,可控探针) + +目标:先用真实运行面数据定位根因。结束时必须能给出"症状 + 触发路径 + 根因 + 影响面 + 期望修复方向"。 + +| 子步骤 | 命令 / 动作 | 退出条件 | +|---|---|---| +| 1.1 重读目标 AGENTS.md | `trans :/ sh -- 'cat AGENTS.md'` + 相关 `docs/reference/*` | 取得目标仓库的当前任务约束(不靠主 server 记忆) | +| 1.2 grep 关键字定位 | `rg "" --type ts --type mjs` 等 | 找到嫌疑文件 + 行号 | +| 1.3 实测复现 | `trans sh -- ''` / 原入口 CLI / bounded logs / trace | 拿到真实 trace / error / argv,不靠理论推导 | +| 1.3b 临时探针(可选) | 只读证据不足时,最小 `apply-patch` 插入临时日志或旁路探针 | 记录目标、基线、diff、撤回方式和证据;不得混成正式修复 | +| 1.4 写根因小结 | 用 issue 原文 + 探测证据,先自然语言说明用户现象、触发路径、根因、影响面、期望修复方向和可行的单元/mock 复现点,再列关键 trace/argv/status | 可贴回 issue 评论区作为进展锚点,读者不看命令细节也能明白当前判断 | + +P1 强约束: + +- 证据边界 + - 事实优先:严禁以"理论推导"代替实地探测;外部 API、设备、provider 的行为可能在变,必须先复现再下结论。 + - 影响面:跨 lane / 跨 host 一致性问题,先在目标 lane 做最小真实闭环,再讨论通用解。 +- 写入边界 + - 探针:P1 默认只读;只有只读证据不足时才进入 1.3b 临时探针,且探针必须可撤、可解释、可审计。 + - 修复:P1 禁止写持久化修复;临时探针不算修复完成,也不能带入 P3 正式 diff。 + +--- + +### P2:最小运行面实验(热补丁优先,可解释跳过) + +目标:用最短反馈路径证明修复方向有效。能在目标运行面安全热补时,优先直接对 pod / host workspace 运行 `trans apply-patch`;不能热补时,必须写清不可热补原因和替代验证路径。结束时必须能给出"实验前状态 vs 实验后状态"的可比证据。 + +P2 决策树: + +- 热补判定 + - 必须热补:问题依赖真实 runtime config / Secret / env / proxy / provider / 硬件 / k3s 对象,且目标文件或配置能被安全、可撤地热修改。 + - 可跳过热补但不可跳过验证:编译型二进制、静态 bundle、schema/migration、构建产物、短连接 CLI、文档治理、测试修复或必须经 CI/CD 产物才能生效的改动。 + - 跳过记录:在进展评论或 closeout 中记录 `P2 disposition=not-hotpatchable`、原因、替代证据和后续 P3/P4 验证命令。 + +| 子步骤 | 命令 / 动作 | 退出条件 | +|---|---|---| +| 2.1 记录运行面基线 | 记录目标 pod / host / service、source commit 或镜像版本、修复前 trace / argv / status | 后续 P3 能对齐同一基线 | +| 2.2 设计最小运行面改动或替代实验 | 找到最小的代码 / 配置 / 命令行 / 单元或合同 mock 测试改动,能证明方向 | 热补丁优先;不可热补时替代路径可解释;可 mock 的 bug 必须同时设计快速回归测试 | +| 2.3 实地热实验补丁(适用时) | 直接对目标 pod / workspace 执行 `trans apply-patch` | 运行面只包含本次实验改动,可撤回 | +| 2.4 真实环境试跑 | 用目标运行面、原入口 CLI 或获批执行面直连真实 cloud-api / k3s / 设备 pod;不可热补时跑最小等价验证 | 修复路径在目标运行面或等价验证面走通 | +| 2.5 写闭环证据 | 先用正文说明实验验证了哪个修复方向、实验前后行为差异和是否可进入 P3,再列修复前/后 trace / argv / status | 能解释 P2 结论、P3 目标和是否仍需原入口复测 | + +P2 强约束: + +- 实验纪律 + - 热补真实性:不要把需要 CI/CD 重建或镜像重推才能验证的改动伪装成热补;这类任务记录不可热补原因并转入 P3 的受控交付验证。 + - 控制面冲突:热修复动作和标准 Tekton/Argo CD 打架,或被自动滚动覆盖时,创建旁路 pod 实验,不和标准 CI/CD 抢夺控制权。 + - 阶段边界:P2 热补通过前禁止 commit、push、开 PR、触发 CI/CD 或把运行面热补当成正式修复;不可热补任务必须先完成 P2 disposition 说明。 +- 证据纪律 + - 临时改动:P2 临时改动只作为 P3 持久化交付的证据来源;pod 内 sed、临时 apply-patch、单测 mock 通过都不是修复完成证据。 + - 外部依赖:第三方模型 / API / 硬件异常,必须用受控透传在真实 pod/host/provider 上复现后再下结论。 + +P2 推荐补丁方式: + +- 入口 + - 默认直接把 Codex `apply-patch` envelope 用 heredoc 投到目标运行面,不强制写临时 patch 文件。 +- 示例 + +```bash +trans G14:k3s:hwlab-v02:hwlab-cloud-api/app apply-patch <<'PATCH' +*** Begin Patch +*** Update File: internal/cloud/example.ts +@@ + old context +-old line ++new line + next context +*** End Patch +PATCH +``` + +- 特殊情况 + - 大补丁:可以临时落文件后 `< patch.diff`,但这只是便利手段,不是流程要求。 + - 路径映射:运行面路径与源码路径不一致时,P2 可以只写 runtime-specific envelope;P3 再把同一逻辑用源码路径落回 worktree,并在 issue 证据里说明路径映射和逻辑等价关系。 + - 禁止绕路:不要从 host/worktree 取 `git diff`、改路径、再用复杂 shell quoting 拼到 pod;文本热修优先走 `trans <目标运行面 route> apply-patch`,第一个 route token 直接定位到目标 pod / workspace。 + +--- + +### P3:持久化交付(落回 source truth + 项目适配器) + +目标:把 P2 验证有效的修复落到目标项目声明的 source truth,并通过项目适配器完成交付。结束时必须能给出可审计 provenance:commit / PR / artifact / PipelineRun / deploy job / runtime metadata 中与本次任务相符的一组证据。 + +P3 交付画像在上方 `DAD-DEV SPEC` 定义;3.1 必须从 `pr-rollout`、`pr-lightweight`、`artifact-deploy`、`config-docs-only`、`runtime-recovery-followup` 中选择一种,并写清选择理由。 + +| 子步骤 | 命令 / 动作 | 退出条件 | +|---|---|---| +| 3.1 选择交付画像 | 重读目标 `AGENTS.md` + 相关 `docs/reference/*`,确认分支、workspace、PR/CD 边界 | 明确本任务使用哪种 P3 画像和为什么 | +| 3.2 准备 source workspace | 按项目规则快进 fixed repo;从最新 remote/base 创建独立 `.worktree/`,后续只在该 worktree 内工作 | base、remote、branch、worktree 路径和 fixed repo 并行修改状态可审计 | +| 3.3 整理正式修改 | 用 `apply-patch` 对源码收敛最终修改 | diff 聚焦,不带 P1/P2 临时日志、探针或旁路脚本 | +| 3.4 验证 | 跑仓库声明且与本变更相关的 check / test / smoke;对已定位 bug 优先跑新增或修改的单元 / 合同 / mock 复现测试;缺依赖按 lockfile 安装后继续 | 相关验证通过;新增回归测试能在源码层表达目标行为;预存失败或不可运行有证据和分类 | +| 3.5 提交 / PR / merge | 按交付画像执行 commit、push、PR、merge;GitHub 写走项目受控 CLI | commit / PR / merge 可追溯 | +| 3.6 受控交付 | 按项目适配器执行 CI/CD、artifact、rollout、deploy 或跳过 CI/CD(pr-lightweight / config-docs-only) | 不用裸 `kubectl` / `argo` / 原生 `gh` / 手写 REST 作为长期正式入口 | +| 3.7 provenance 验证 | 用项目 status/health/target validation 查看目标 commit/artifact 是否进入运行面(若适用) | runtime provenance 与本任务 source truth 对齐 | + +P3 强约束: + +- 入口与执行面 + - 受控入口:GitHub 写、CI/CD 写、rollout 写一律走项目受控 CLI;具体命令以目标仓库当前 reference 和 CLI help/source 为准;CLI 字段不够先改 CLI 再用,不能把过期 skill 示例当成绕过理由。 + - 构建边界:禁止 master server 做 build / 镜像构建;master 只做轻量源码编辑、Git 和受控 CD 观察;CI/CD 编译产物在外部 builder 跑。 +- source truth + - 文本修改:源码和远端文本修改一律走 `apply-patch`(包括 `trans apply-patch`);禁止用 heredoc / sed / 复杂 shell quoting 拼接大段 patch;`apply-patch` 语法见 `AGENTS.md` Critical Apply Patch Syntax。 + - source / worktree:禁止把落后 fixed repo 或带并行修改的 fixed repo 当 scratch 区;必须先按项目规则 fetch、状态核查,再从最新 remote/base 创建 P3 独立 `.worktree/` / branch / PR;无服务任务也使用 `pr-lightweight` 的轻量 PR 形态。 + - P2/P3 对账:记录 P2 热实验基线和 P3 source base;若目标分支已推进,比较中间提交是否影响触发路径;有影响则 replay 后重跑必要 P2/P4,没影响则记录 targeted revalidation 依据。 +- 回归保护 + - 根因能稳定抽到代码路径、配置选择、请求/响应、parser、状态机、权限或 dispatcher 合同时,P3 PR 必须包含相应单元 / 合同 / mock 测试;没有补时,PR/issue 必须说明不可行原因和替代快速拦截方案。 + +### 项目适配器 + +本 skill 不复制项目 runbook。进入 P3/P4 前,按目标项目读取适配器: + +- HWLAB:以目标 HWLAB workspace 的 `AGENTS.md` 和 UniDesk `docs/reference/hwlab.md` 为准。无服务 CaseRun、短连接 CLI、trace、config、docs、helper 和配置治理类任务走 `pr-lightweight`;node、lane、自动 CI/CD、target validation、public endpoint 和 device-pod closeout 只由当前项目适配器与 owning YAML 决定,不是 unidesk-daddev 通用步骤。 +- AgentRun:以 `docs/reference/agentrun.md` 为准;目标 node、lane、source worktree 与自动 CI/CD authority 只从当前 owning YAML 和项目适配器解析。 +- UniDesk CLI/trans/helper:以 UniDesk `AGENTS.md`、`docs/reference/cli.md`、`docs/reference/dev-environment.md` 为准。无服务 CLI、trans/tran/helper、docs、config、trace 和治理类变更走 `pr-lightweight`(独立 worktree、分支、PR,可自合并,跳过 CI/CD/rollout);业务代码、运行面、发布链路、CI/CD、Secret、权限、数据迁移、PROD 等高风险改动按对应发布画像处理。仍不得在 master server 跑仓库级 check/build/smoke。 +- 其他项目:先从目标 repo 的 `AGENTS.md` 或 reference 提取:source truth、workspace、branch、交付画像、验证入口、issue close 规则和禁止动作。缺适配器时先写最小适配决策,再执行 P3。 + +--- + +### P4:交互式验收(原入口复测 + issue 关闭) + +目标:用与用户最初报告的相同入口(同一 CLI、同一 device pod、同一 job id)跑一遍验收清单,把能证明修复有效的运行面证据贴回 issue,再关 issue。 + +| 子步骤 | 命令 / 动作 | 退出条件 | +|---|---|---| +| 4.1 准备验收清单 | 梳理 issue 里的"复现步骤 / 验收清单" | 每条都可独立跑、可独立判定 | +| 4.2 原 CLI 跑全清单 | `hwpod ...` / `trans sh -- ''` | 每条"期望 vs 实际"都记录 | +| 4.3 关键步骤抽 trace | 抓取 job id + argv + status + blocker 全文 | argv 是修复是否生效的硬证据 | +| 4.4 写 closeout comment | 用项目受控 GitHub/issue CLI 写语义化 closeout:先用自然语言说明问题、根因、修复、验收结果和剩余边界,再列审计证据;长正文优先 `--body-file` 评论 | 读者能不解析 telemetry 就看懂结论,同时包含 PR/commit/artifact/rollout/provenance、耗时、原入口验收结果、已知未关项 | +| 4.5 关 issue | 按当前项目 CLI lifecycle 规则关闭;若 close 命令只接受短评论,先写长证据评论再用短引用关闭 | issue state=closed | + +P4 强约束: + +- closeout 文本 + - 语义正文:开头用自然语言讲清"这个 issue 原来坏在哪里、这次根因是什么、做了什么修改、为什么现在可以认为修好了、还有什么不属于本次范围";命令、trace、job id、commit、artifact stats 放在后面的证据区,不能用证据区替代正文说明。 + - provenance:不强制使用"修复前 / 修复后"配对表,也不强制所有任务列 image digest;必须列出与交付画像匹配的 provenance,例如 commit、PR、artifact、PipelineRun、deploy job、runtime metadata 或 docs/config validation。 + - scope:out-of-scope 项必须显式列出(D601 host stale / COM 漂移 / 等);不能"顺手发现就修",避免 scope creep。 +- 验收证据 + - 两层验证:必须区分源码层单元 / 合同 / mock 回归测试和 CLI / Web 等价 / 原入口复测;缺任一层必须写明不适用原因;只跑源码层证据不能关闭 issue,必须用原入口在真实运行面跑过。 + - 运行面审计:关键 argv 必须在验收报告里出现原文;关闭评论的"实际命令 / lane / URL / trace / session / job id"必须可被独立审计员复现。 + - rollout 耗时:PR/CI/CD/部署滚动实际耗时必须写入 issue 评论区,至少记录起止点、总耗时、明显等待段或重跑次数;无 rollout 的任务说明 `rollout=not-applicable`。 + +--- + +## 跨阶段强约束(贯穿 P1-P4) + +- 变更纪律 + - worktree:P3 默认先按项目规则更新 fixed repo,再从最新 remote/base 创建独立 `.worktree/` / branch / PR;所有会写文件、提交、推送、issue closeout 或受控部署的动作都在该 worktree 内执行,fixed repo 只做只读预检和 worktree anchor。 + - push 条件:worktree 干净且 P2 disposition 明确后才能 push;发现 P3 入口时 source commit 与 P2 运行面基线不一致,先做影响面对账。 + - 并行变更:fixed repo 或其他 worktree 中的并行变更默认保持原样;当前任务用独立 `.worktree` 隔离,必要时只 cherry-pick 明确相关提交,不要 stash / 丢弃 / `git reset --hard`。 +- 证据纪律 + - trace 落盘:issue 原始复现证据与最终验收 trace / job id / argv 要写到 issue 评论区;不要求逐条整理成配对表,但必须先有自然语言正文解释证据含义。 + - rollout 记录:PR/CI/CD/部署滚动的起止时间、总耗时、重跑次数或等待段必须写到 issue 评论区;无 rollout 的任务写明不适用,并用正文解释交付路径。 + - 进展锚点:用 issue 评论作进展锚点;不把 commit message、临时文件或 agent session memory 当进展锚点。 +- 治理纪律 + - 可见性优先:命令无输出、状态不可见、日志尾部缺失、trace 被截断或耗时不可见时,先修可见性再继续原任务;不用长日志全量 dump 代替结构化状态,优先补 CLI summary、job status、bounded tail 和 raw drill-down。 + - 门禁最小化:拦截当前最新任务目标的旧测试、旧门禁、旧合同检查、旧预检、旧断言和旧 guard 一律拆除;新增 gate 只覆盖当前目标下明确且高价值的风险,优先用证据、文档共识、代码结构和标准入口自然收敛。 + +## 禁止行为 + +- 阶段错位 + - 流程绕过:跳过 P1 实地探测直接改 pod 文件、跳过 P2 disposition 直接 P3 持久化、跳过 P3 持久化交付直接靠热修宣称"修好了",每次出现都强制回到 P1 重做。 + - 临时当正式:pod 内热修 / 临时 apply-patch / 单测 mock 通过 ≠ 修复完成;P2 的产物是"修复需求来源",P3 的 source truth + provenance 才是"修复证据"。 +- 入口绕过 + - master 构建:master 是生产入口,构建会拖垮生产;任何"在 master 跑 check 通过"都不能作为有效证据。 + - 原生命令写入:`kubectl apply` / 原生 `gh issue edit` / 手写 REST 写入 GitHub = 绕过项目受控 CLI,会失去 body guard、字段约束、token 轮换和审计日志;若项目允许某个 repo-owned merge path,必须在适配器里写明。 +- 验证反模式 + - 大回环试错:Tekton pipeline / Argo rollout 不是"兼容性探索工具";改一行 → push → 等 CI → 看结果 → 再改 → 再 push = 把 CI 当成编译器调试器用。 + - 缺依赖 skip:"因为 deps 没装所以跳过这个 check" = 把 noise 当 signal,必须按 lockfile 装上再验证。 + - 只做 CLI 交互验收:CLI/Web 等价入口能证明真实 runtime 修好,但不能提供快速回归拦截;可 mock 的 bug 不补源码层测试就关闭 issue = 把回归风险留给用户和慢速验收。 +- 边界污染 + - 旧路径:旧测试、旧合同检查、旧 guard、旧 gate 与当前任务目标冲突时,不允许继续修补、加例外、旁路兼容或长期双路径;删除旧门禁后只补最小必要的新验证。 + - scope creep:顺手修不在 issue scope 内的 bug、优化或命名会制造合并冲突并模糊本次修复证据;从 changeset 排除无关修改,若确认是自己刚引入的无关改动,用最小反向 patch 移除;不得回滚或删除他人并行变更。 + - 适配器泛化:HWLAB v0.2 的 git mirror、AgentRun v0.1 的 control-plane、UniDesk 的 CI/CD skip 规则等只在对应项目适配器内生效,不要复制到其他项目。 + - 基础设施缺陷混入业务 scope:monitor / cron / CLI 字段缺失 / 可见性不足等基础设施问题可先补最小能力解阻;长期恢复应单独 issue 跟踪,不能混入当前业务 PR。 +- 证据反模式 + - 无证据 close:在 issue 评论里说"应该修好了"不是证据;没有 trace / job id / argv / 截图 = 不能 close issue;证据必须是可被独立审计员复现的命令输出原文。 + - telemetry dump:只有 job id、trace、commit、PipelineRun、JSON 片段而没有自然语言正文说明,读者无法理解决策;必须先写语义化正文,再列审计证据。 + - session memory:agent session memory / 历史对话不可审计;证据必须落在 issue comment / git commit / PipelineRun / k8s object 这类可被外部引用的位置。 diff --git a/.agents/skills/unidesk-hwpod-ops/SKILL.md b/.agents/skills/unidesk-hwpod-ops/SKILL.md index 387b515c..13b47bf8 100644 --- a/.agents/skills/unidesk-hwpod-ops/SKILL.md +++ b/.agents/skills/unidesk-hwpod-ops/SKILL.md @@ -41,7 +41,7 @@ description: >- - 操作者不得用手写 `trans`/PowerShell/cmd 完成安装、更新、配置或自启动; - 受控 CLI 缺失时先实现 CLI,不把手工部署当临时完成态。 - 调查可只读访问现场;发生以下变更时加载对应 skill: - - 安装、注册、更新、停止旧运行器或修改 MDTODO 来源:`$dad-dev`; + - 安装、注册、更新、停止旧运行器或修改 MDTODO 来源:`$unidesk-daddev`; - 部署/发布:同时加载 `$unidesk-cicd`; - YAML 变更:同时加载 `$unidesk-ymalops`。 - 远端操作走 `$unidesk-trans`。普通 `trans` 保持短连接;图形进程不得作为透传子进程长挂。 diff --git a/.agents/skills/unidesk-hwpod-ops/references/python-ui-node.md b/.agents/skills/unidesk-hwpod-ops/references/python-ui-node.md index c78ef557..4d7dd76a 100644 --- a/.agents/skills/unidesk-hwpod-ops/references/python-ui-node.md +++ b/.agents/skills/unidesk-hwpod-ops/references/python-ui-node.md @@ -127,4 +127,4 @@ $root = Join-Path $HOME ".hwlab" - 比较 nodeId、云端地址、资源绑定和活动硬件任务; - 可能中断硬件操作的变更必须有明确维护窗口; - - 变更必须遵循 `$dad-dev` 流程。 + - 变更必须遵循 `$unidesk-daddev` 流程。 diff --git a/.agents/skills/unidesk-kafka/SKILL.md b/.agents/skills/unidesk-kafka/SKILL.md index a60c4250..81ad7665 100644 --- a/.agents/skills/unidesk-kafka/SKILL.md +++ b/.agents/skills/unidesk-kafka/SKILL.md @@ -142,5 +142,5 @@ bun scripts/cli.ts web-probe observe status \ - OTel trace 与跨服务 identity:`$unidesk-otel`。 - AgentRun durable resource/events:`$unidesk-code-queue`。 - Workbench 隔离 replay:`$unidesk-webdev`。 -- 跨 host/k3s 临时诊断通道:`$unidesk-trans` 与 `$dad-dev`。 +- 跨 host/k3s 临时诊断通道:`$unidesk-trans` 与 `$unidesk-daddev`。 - Kafka/YAML owner 或 Secret 变更:`$unidesk-ymalops`;本技能默认只读,不从运行面反解 Secret。 diff --git a/.agents/skills/unidesk-nginx/SKILL.md b/.agents/skills/unidesk-nginx/SKILL.md index 87ef18de..c6c25d3d 100644 --- a/.agents/skills/unidesk-nginx/SKILL.md +++ b/.agents/skills/unidesk-nginx/SKILL.md @@ -20,7 +20,7 @@ description: >- - PK01 边界:`docs/reference/pk01.md`。 涉及 YAML 职责拆分时同时加载 `$unidesk-ymalops`。 -涉及跨 host 现场修改或验证时同时加载 `$dad-dev` 与 `$unidesk-trans`。 +涉及跨 host 现场修改或验证时同时加载 `$unidesk-daddev` 与 `$unidesk-trans`。 ## 高频入口 diff --git a/.agents/skills/unidesk-selfmedia/SKILL.md b/.agents/skills/unidesk-selfmedia/SKILL.md index c6b03ab7..ef371c2b 100644 --- a/.agents/skills/unidesk-selfmedia/SKILL.md +++ b/.agents/skills/unidesk-selfmedia/SKILL.md @@ -40,7 +40,7 @@ description: UniDesk SelfMedia 工厂的 YAML-first 运维技能,覆盖 NC01 - Secret/YAML 归属或 renderer 修改同时使用 `$unidesk-ymalops`。 - PaC、Tekton、GitOps、Argo 或自动交付排障同时使用 `$unidesk-cicd`。 -- 跨节点现场闭环同时使用 `$dad-dev` 与 `$unidesk-trans`。 +- 跨节点现场闭环同时使用 `$unidesk-daddev` 与 `$unidesk-trans`。 - 公网页面、布局或浏览器原入口验收同时使用 `$unidesk-webdev`。 ## 详细入口 diff --git a/.agents/skills/unidesk-subagent/SKILL.md b/.agents/skills/unidesk-subagent/SKILL.md index 5254c607..945020fb 100644 --- a/.agents/skills/unidesk-subagent/SKILL.md +++ b/.agents/skills/unidesk-subagent/SKILL.md @@ -71,6 +71,11 @@ description: UniDesk 主代理调度子代理的必读技能。用户提到子 - 运行面故障、用户原入口不可用,或凭据/配置变更导致服务退化时,必须先恢复运行面,再完成工程化: - 主代理先冻结恢复判定标准,并保留恢复关键路径的控制权; - 优先用既有受控入口实施最小、可逆、可验证的恢复,只有受控入口本身缺失并直接阻塞恢复时,才在关键路径修改工具; + - 调试或临时恢复需要运行面 patch 时,按 `$unidesk-daddev` P2 执行: + - 先冻结对象、影响范围、预期与回退方式; + - patch 只用于验证或临时恢复,不得伪造 source/ref、GitOps 或交付终态; + - 最终必须写回 owning YAML、源码或 renderer,走正常 PR 与自动 CI/CD, + 并撤销 patch 或确认其已被声明式交付覆盖; - 通用抽象、输出优化、skill、报告和长期治理不得成为恢复门禁; - 恢复达到用户原入口可用的标准后,主代理不得把临时恢复当作任务完成,必须继续完成用户明确要求的根因修复、工程化、PR、验证和治理; - 与恢复根因解耦且具备独立 issue、MDTODO、worktree 和验收入口的工程化任务,必须在恢复期间立即并行派发,不得全部排到恢复之后串行执行。 diff --git a/.agents/skills/unidesk-subagent/references/gh-workflow.md b/.agents/skills/unidesk-subagent/references/gh-workflow.md index ebc6692a..93f55d8d 100644 --- a/.agents/skills/unidesk-subagent/references/gh-workflow.md +++ b/.agents/skills/unidesk-subagent/references/gh-workflow.md @@ -26,9 +26,13 @@ - 依赖图必须先标出运行面恢复关键路径和用户原入口恢复标准。主代理控制恢复关键路径,避免多个代理同时修改同一生产对象、恢复状态机或共享配置。 - 恢复优先指先让用户原入口通过既有受控路径恢复到可验证状态,不表示工程化任务整体串行: - 恢复关键路径上的最小诊断、配置修正和复测按真实依赖顺序执行; + - 必要的运行面 patch 由 `$unidesk-daddev` P2 约束,只证明方向或临时恢复; + 不得把 patch 状态当作 source authority、自动交付成功或最终验收; - 与根因解耦的 CLI、reference、报告、独立仓库修复和长期治理,在具备独立 issue、MDTODO、worktree、PR 与验收入口时立即并行; - 只有缺少受控恢复入口直接阻塞恢复时,才允许把工具修改放到恢复关键路径。 - 运行面恢复后,主代理继续完成根因修复、持久化配置、自动交付、原入口复测和治理收口;不得以临时恢复或单次手工成功代替用户要求的终态。 +- P2 patch 验证成立后,主代理必须把变化收敛到 owning YAML、源码或 renderer, + 通过正常 PR 与自动 CI/CD/GitOps 交付,并撤销 patch 或确认其已被声明式交付覆盖。 - 恢复期间降低并发必须有具名原因,例如共享生产对象、同一状态机、权限边界或运行面容量;原因解除后立即重新计算可安全并发窗口。 ## 模型与思考等级 diff --git a/.agents/skills/unidesk-ymalops/SKILL.md b/.agents/skills/unidesk-ymalops/SKILL.md index 689b5281..bf81a5cd 100644 --- a/.agents/skills/unidesk-ymalops/SKILL.md +++ b/.agents/skills/unidesk-ymalops/SKILL.md @@ -28,6 +28,11 @@ description: UniDesk YAML-first 运维正规化技能。用户提到 ymal-first/ - 先执行 `git status --short --branch` 和 `git pull --ff-only origin master`;保留并绕开无关并行修改。 - 源码、配置、部署类正规化默认在独立 `.worktree/` 中做;轻量 skill/docs/reference 收敛可按项目规则直接在主 worktree 做。 - YAML 是 source of truth。不得新增隐藏代码默认值、schema 数值硬限制、合同测试或测试硬编码策略。 +- `$unidesk-daddev` P2 调试例外不改变 YAML-first 终态: + - 可对运行面做最小、可逆 patch 以验证根因或临时恢复; + - patch 不得反向成为配置真相、第二 authority 或自动交付成功证据; + - 验证成立后必须把变化收敛到 owning YAML、parser/renderer 或源码, + 经正常 PR 与自动 CI/CD/GitOps 交付,并撤销 patch 或确认其已被声明式交付覆盖。 - 代码校验只保证字段能被正确读取和渲染:类型、必填、枚举键名、引用存在性。版本号、namespace、endpoint、容量、冷却时间、回退窗口等数值以 YAML 为准。 - 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 引用,不承载全部细节。 diff --git a/AGENTS.md b/AGENTS.md index 82845e64..fb0027ca 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -83,7 +83,7 @@ ## P0: 受控入口与技能路由 -- P0: 跨 host/lane 现场修复加载 `$dad-dev`: +- P0: 跨 host/lane 现场修复加载 `$unidesk-daddev`: - 完成真实运行面探测; - 完成最小验证、持久化和原入口复测。 - P0: CI/CD、GitOps、rollout、PipelineRun、Argo、git-mirror 和 AgentRun 部署: diff --git a/docs/reference/agent-instruction-hygiene.md b/docs/reference/agent-instruction-hygiene.md index 61188a94..a5dcba82 100644 --- a/docs/reference/agent-instruction-hygiene.md +++ b/docs/reference/agent-instruction-hygiene.md @@ -55,7 +55,7 @@ - 分流顺序: - 可复用工作流进入 skill `SKILL.md`,例如: - - `$dad-dev`、`$unidesk-cicd`、`$unidesk-gh`; + - `$unidesk-daddev`、`$unidesk-cicd`、`$unidesk-gh`; - `$unidesk-trans`、`$unidesk-otel`、`$unidesk-webdev`; - `$unidesk-ymalops`。 - 稳定项目约束、工作区规则、架构边界和验收标准进入 `docs/reference/*.md`。 @@ -132,7 +132,7 @@ - CLI 行为与输出:`docs/reference/cli.md`。 - YAML-first 配置:`docs/reference/yaml-first-ops.md` 与 `$unidesk-ymalops`。 - 平台基础设施:`docs/reference/platform-infra.md`;涉及 Sub2API 时使用 `$unidesk-sub2api`。 -- 分布式现场修复:`$dad-dev` 与 `docs/reference/devops-hygiene.md`。 +- 分布式现场修复:`$unidesk-daddev` 与 `docs/reference/devops-hygiene.md`。 - CI/CD 与发布:`$unidesk-cicd` 与 `docs/reference/cli.md`。 - GitHub issue 与 PR 写入:`$unidesk-gh`。 - Trans/远端补丁传输:`$unidesk-trans` 与 `docs/reference/cli.md`。 diff --git a/docs/reference/devops-hygiene.md b/docs/reference/devops-hygiene.md index 3d45a296..9ea44f7a 100644 --- a/docs/reference/devops-hygiene.md +++ b/docs/reference/devops-hygiene.md @@ -60,9 +60,31 @@ If a manual repair is needed to unblock the platform, the durable fix must be co ## 分布式敏捷流程 -“分布式敏捷”是 UniDesk 对 distributed agile field repair 的固定流程名;通用 P1/P2/P3/P4 阶段、禁止行为和证据边界由 `$dad-dev` skill 维护,本参考不再重复展开。UniDesk 项目内只保留下面的特有约束:必须使用结构化 `trans`/UniDesk CLI 进入真实 provider、pod、host bridge 或 service port;运行面热补只能证明方向或临时恢复,不能成为隐藏部署真相;持久化完成必须回到 Git/PR/CI/CD 后原入口复测。 +“分布式敏捷”是 UniDesk 对 distributed agile field repair 的固定流程名;通用 P1/P2/P3/P4 阶段、禁止行为和证据边界由 `$unidesk-daddev` skill 维护,本参考不再重复展开。UniDesk 项目内只保留下面的特有约束: -固定主 repo 是 source truth anchor,不是源码/运行面 scratch 区。会产生源码、配置、issue closeout、部署脚本、验收产物或高风险 dad-dev / post-task 交付的工作,执行前必须先从目标 fixed repo 的最新 remote/base 创建任务专属 `.worktree/`,后续编辑、验证、提交、push 和受控 CLI 写操作都在该 worktree 内完成。UniDesk 任务 worktree 必须通过 `bun scripts/cli.ts dev-env worktree add .worktree/ --branch [--from origin/master]` 创建,让 `.worktreecopy` 白名单内的本地配置自动复制到新 worktree;fixed repo 只用于 `git fetch`、`git status`、快进同步、读取规则和这个受控创建入口。其中已有的并行未提交修改默认保持不动,不纳入当前任务,也不要用 reset、checkout 或删除来“清理”。 +- 必须使用结构化 `trans`/UniDesk CLI 进入真实 provider、pod、host bridge 或 service port; +- P2 允许按调试需要实施最小、可逆的运行面 patch 或热补, + 但它只能证明方向或临时恢复,不能成为隐藏部署真相、第二 authority、 + GitOps desired、自动交付成功或最终验收证据; +- P3 必须把有效变化写回 owning YAML、源码或 renderer, + 经正常 PR 与自动 CI/CD/GitOps 交付;临时 patch 必须撤销, + 或由已确认的声明式交付覆盖; +- P4 使用用户原入口复测,不能用单次手工成功替代终态。 + +固定主 repo 是 source truth anchor,不是源码/运行面 scratch 区。 + +- 会产生源码、配置、issue closeout、部署脚本、验收产物, + 或高风险 unidesk-daddev / post-task 交付的工作, + 执行前必须从目标 fixed repo 的最新 remote/base + 创建任务专属 `.worktree/`; +- 后续编辑、验证、提交、push 和受控 CLI 写操作都在该 worktree 内完成; +- UniDesk 任务 worktree 必须通过 + `bun scripts/cli.ts dev-env worktree add .worktree/ --branch [--from origin/master]` + 创建,让 `.worktreecopy` 白名单内的本地配置自动复制到新 worktree; +- fixed repo 只用于 `git fetch`、`git status`、快进同步、读取规则 + 和这个受控创建入口; +- 其中已有的并行未提交修改默认保持不动,不纳入当前任务; +- 禁止用 reset、checkout 或删除来“清理”。 The root UniDesk checkout at `/root/unidesk` is the fixed main worktree and must stay on `master`. Non-`master` work belongs in a task-specific `.worktree/`. Unexpected local changes are presumed to belong to another concurrent task: preserve them, do not reset, checkout, delete or rewrite them, and scope the current task's commit to its own files. @@ -90,7 +112,7 @@ CONSTAR、控之星、71-FILTER、71-FREQ、PLC 项目和 PLC 控制器任务是 When UniDesk's own CLI, wrapper or controlled toolchain is repaired, merge the durable fix into `master` before relying on it for the original operation. The checkout that actually executes the tool must then contain that merged revision. If a fixed checkout cannot fast-forward because of unrelated changes, preserve it and run the tool from a clean worktree based on current `origin/master`; never reset or overwrite concurrent work to update the executable path. -在模型 provider、API provider、硬件链路、跨平台 bridge、CLI/trans/tran 或高频工具链问题上,判定外部 blocker 前仍需完成 UniDesk 的防误判核查:确认当前 runtime config / Secret key presence / env / proxy / NO_PROXY / endpoint / args,使用实际目标运行面复现,并尽量与 UniDesk/HWLAB 成熟实现对照。用户反馈或新证据推翻 blocker 判断时,立即切回 `$dad-dev` 的现场修复闭环。 +在模型 provider、API provider、硬件链路、跨平台 bridge、CLI/trans/tran 或高频工具链问题上,判定外部 blocker 前仍需完成 UniDesk 的防误判核查:确认当前 runtime config / Secret key presence / env / proxy / NO_PROXY / endpoint / args,使用实际目标运行面复现,并尽量与 UniDesk/HWLAB 成熟实现对照。用户反馈或新证据推翻 blocker 判断时,立即切回 `$unidesk-daddev` 的现场修复闭环。 如果某个现场步骤因为 quoting、route 定位、kubeconfig、输出体积或缺少 helper 而反复痛苦,优先改进 UniDesk passthrough / CLI 并在本文件的 `Distributed Command Passthrough` 或 `docs/reference/cli.md` 中记录稳定入口,不要沉淀一批一次性 shell 菜谱。 diff --git a/docs/reference/g14-observability-infra.md b/docs/reference/g14-observability-infra.md index 156526f6..f540867e 100644 --- a/docs/reference/g14-observability-infra.md +++ b/docs/reference/g14-observability-infra.md @@ -35,7 +35,7 @@ The shared Prometheus stack may discover application monitors across namespaces ## GitOps And Control Plane -Monitoring infrastructure must be declared as Git-backed desired state and applied through a controlled UniDesk or G14 GitOps path. A temporary `kubectl apply` may be used only as a `$dad-dev` P2 experiment; it must be followed by a durable source change and GitOps/CLI validation. +Monitoring infrastructure must be declared as Git-backed desired state and applied through a controlled UniDesk or G14 GitOps path. A temporary `kubectl apply` may be used only as a `$unidesk-daddev` P2 experiment; it must be followed by a durable source change and GitOps/CLI validation. Current durable control surface: @@ -92,7 +92,7 @@ Durable validation after rollout must prove: - No public HWLAB or UniDesk FRP endpoint exposes raw Prometheus, Grafana or application `/metrics`. - CLI or controlled proxy output can answer a bounded query and reports the target namespace/lane/source of the data. -Metrics are supporting observability evidence. They do not replace `$dad-dev` source-level tests, CI/CD provenance or original-entry validation for HWLAB issues. +Metrics are supporting observability evidence. They do not replace `$unidesk-daddev` source-level tests, CI/CD provenance or original-entry validation for HWLAB issues. ## Application Closeout Contract diff --git a/docs/reference/g14.md b/docs/reference/g14.md index 57ea592f..909598b9 100644 --- a/docs/reference/g14.md +++ b/docs/reference/g14.md @@ -6,7 +6,7 @@ - HWLAB 固定运行面、工作区、原入口验收与凭据边界:`docs/reference/hwlab.md`。 - Gitea source authority、PaC/Tekton、GitOps/Argo 与自动交付边界:`docs/reference/platform-infra.md#gitea-与-pipelines-as-code-边界`。 -- 跨节点现场调查、持久化和原入口复测:`$dad-dev`。 +- 跨节点现场调查、持久化和原入口复测:`$unidesk-daddev`。 - CI/CD 只读观察、scoped help 与 legacy 判定:`$unidesk-cicd` 及其按需 reference。 - 固定开发机、Master 构建限制和任务 worktree:`docs/reference/dev-environment.md`。 diff --git a/docs/reference/hwlab.md b/docs/reference/hwlab.md index 544a1480..0834e00c 100644 --- a/docs/reference/hwlab.md +++ b/docs/reference/hwlab.md @@ -7,7 +7,20 @@ - UniDesk 指挥侧 workspace:`/root/unidesk`,固定使用 `master`,开始前执行 `git status` 和 `git pull --ff-only origin master`。 - HWLAB 开发、部署和验证固定只使用 NC01。`config/hwlab-node-lanes.yaml` 是 node、lane、workspace、CI/CD repo、namespace、GitOps path、公网入口和 Secret sourceRef 的配置真相,当前默认目标必须是 `NC01/v03`。 - HWLAB 固定主 workspace 是 `NC01:/root/hwlab-v03`,固定跟踪 `v0.3`。源码修改、PR 准备、repo 内验证、GitOps render 和 rollout 修复都必须在该固定 workspace 下创建任务级 `.worktree/`;master server 本地 `/root/HWLAB`、一次性 clone、runner clone、pod 内副本或非 NC01 workspace 只能做只读对照,不能承担开发 source truth。 -- HWLAB v0.3 delivery authority 由 `config/hwlab-node-lanes.yaml`、`config/platform-infra/gitea.yaml` 与 `config/platform-infra/pipelines-as-code.yaml` 组合确认。NC01/v03 精确解析为 PaC consumer 后,目标 branch 的 GitHub PR merge 是唯一交付触发;完整自动链为 GitHub webhook -> Gitea controlled mirror -> immutable snapshot -> Gitea webhook -> PaC -> Tekton -> GitOps/Argo -> runtime。默认 help、status 与 Next 只给只读 status/history;自动链故障必须修 owning YAML、controller 或源码,不得用 trigger、refresh、mirror sync/flush、人工 PipelineRun 或直接 Gitea push 补齐。 +- HWLAB v0.3 delivery authority: + - 由 `config/hwlab-node-lanes.yaml`、`config/platform-infra/gitea.yaml` + 与 `config/platform-infra/pipelines-as-code.yaml` 组合确认; + - NC01/v03 精确解析为 PaC consumer 后, + 目标 branch 的 GitHub PR merge 是唯一交付触发; + - 完整自动链为 GitHub webhook -> Gitea controlled mirror -> immutable snapshot + -> Gitea webhook -> PaC -> Tekton -> GitOps/Argo -> runtime; + - 默认 help、status 与 Next 只给只读 status/history; + - 自动链故障必须修 owning YAML、controller 或源码, + 不得用 trigger、refresh、mirror sync/flush、人工 PipelineRun 或直接 Gitea push 补齐; + - 调试或临时恢复确需运行面 patch 时走 `$unidesk-daddev` P2; + - patch 不得改变交付 authority 或冒充终态; + - 结论必须写回 owning YAML/源码并由正常 PR 自动交付; + - 临时 patch 随后撤销或由声明式交付覆盖。 - 进入任何 HWLAB 工作前,按 `NC01/v03` 解析 route/workspace/sourceBranch/kubeRoute/runtime namespace 做预检、快进和验证:工作面是 `NC01:/root/hwlab-v03`、source branch 是 `v0.3`、k3s route 是 `NC01:k3s`、runtime namespace 是 `hwlab-v03`、公网入口由 YAML 的 NC01 target 声明。 - NC01 的 node-local registry 是 k3s workload/PVC,不是 host Docker registry。`hwlab nodes control-plane infra status --node NC01 --lane v03` 应显示 registry workload ready、PVC bound 和 endpoint ready;必须通过受控 `runtime-image preload` 和 `infra tools-image build/status` 补齐 BuildKit、runtime/base 和 tools image,再把 HWLAB/AgentRun status 与 web-probe smoke 作为可用性证据。 - HWLAB 项目内长期规则入口仍以目标 repo 的 `AGENTS.md` 为准。进入已解析的目标 workspace 后,必须重新读取该 workspace 的规则文件;不能只凭主 server 的压缩上下文继续操作。 diff --git a/docs/reference/platform-infra.md b/docs/reference/platform-infra.md index a4df1fda..71fb5999 100644 --- a/docs/reference/platform-infra.md +++ b/docs/reference/platform-infra.md @@ -15,7 +15,16 @@ - Gitea mirror 与 Pipelines-as-Code 是 UniDesk 运维的 CI source/trigger 服务。`config/platform-infra/gitea.yaml` 和 `config/platform-infra/pipelines-as-code.yaml` 分别拥有 mirror/webhook 与 PaC Repository/consumer 配置;repo URL、snapshot、webhook、public exposure、FRP/Caddy port、token sourceRef 和 PaC params 不得隐藏在代码特例中。 - Delivery authority resolver 必须组合上述两份 YAML,并按 consumer id、node、lane、upstream repository、branch 和 Gitea repository 精确关联。不得通过 URL 片段、repo 名称前缀或仓库专属 `if` 推断迁移状态。零匹配、多匹配和配置错误都必须返回 `unknown`、`mutation=false` 并停止生成或执行写操作。 - PaC consumer 的唯一正式触发是目标 source branch 的 GitHub PR merge。完整自动链固定为:GitHub PR merge -> GitHub webhook -> Gitea controlled mirror -> immutable snapshot -> Gitea webhook -> PaC/Pipelines-as-Code -> Tekton -> GitOps/Argo -> runtime 运行面。 -- PR 合并后,主代理、子代理和操作者都不得用 `apply`、`closeout`、`trigger-current`、`refresh`、`sync`、`flush`、`webhook-test`、人工 PipelineRun、直接 Gitea push、本地 mirror 写入或其他补跑完成当前交付。自动链不通时必须修 owning YAML、controller 或源码,并只用修复 PR 合并产生的新正常自动事件验收。 +- PR 合并后的交付边界: + - 主代理、子代理和操作者不得用 `apply`、`closeout`、`trigger-current`、 + `refresh`、`sync`、`flush`、`webhook-test`、人工 PipelineRun、 + 直接 Gitea push、本地 mirror 写入或其他补跑完成当前交付; + - 自动链不通时必须修 owning YAML、controller 或源码, + 并只用修复 PR 合并产生的新正常自动事件验收; + - 必要的运行面调试或临时恢复可以走 `$unidesk-daddev` P2 最小可逆 patch; + - patch 不得修改 source/ref authority、制造交付成功或替代终态; + - 成立的变化必须写回 owning YAML/源码并经正常 PR 自动交付; + - 临时 patch 随后撤销或由声明式交付覆盖。 - Migrated consumer 的默认 help、status、`Next` 与 `REPAIR` 只能给 `status`、`history`、`events`、`logs`、只读单步下钻以及本节稳定引用。CLI 必须省略 mutation command,而不是只给命令加警告文字。`unknown` authority 同样 fail-closed。 - 旧 `trigger-current`、`refresh` 和 mirror `sync|flush` 只允许在 owning YAML 明确解析为 `legacy-manual` 后执行,并且只在显式 `legacy-cicd` 或 `legacy-ops` scoped help 中可发现。平台 bootstrap、Secret 与配置维护属于独立职责,只在 `platform-bootstrap` 或 `platform-maintenance` scoped help 中展示,不能作为 source delivery recovery。 - `closeout` 仅保留只读历史/诊断兼容入口,并且只能从 `compatibility-diagnostics` scoped help 发现。会 POST hook test 的 `webhook-test` mutation 入口已经删除;连通性只能通过真正只读的 status、GET 与 readiness 观察,禁止制造伪 push。