pikasTech-unidesk/.agents/skills/unidesk-daddev/SKILL.md

---
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) 规范（精简版，仅保留与流程相关的硬约束）。

- `$unidesk-devlevel` 定义 L0-L3 四种可反复使用的开发方式：
  - 本 skill 只在某一级需要跨 host 观察、最小可逆实验、故障收敛或真实入口复测时接管现场闭环；
  - 不把现场修复过程解释成等级变化。
  - 遇到 L2/L3 问题时，优先把根因缩小到可复现的最低等级做小回环；修复后再逐级回归到原问题运行面。

## 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。
  - 公共运行面事故最短路径
    - 适用范围
      - 两个及以上业务、消费者、Provider 或受控通道在相近时间出现连接失败、超时或拒绝连接；
      - Kubernetes API、公共 registry、共享入口、跨节点隧道或 backend-core 等公共依赖出现故障；
      - 用户明确要求只恢复公共运维，不要求继续处理具体业务。
    - 共性输入
      - 节点、lane、route、namespace、service、endpoint 和网络参数必须来自 owning YAML；
      - 运行面对象、阈值和重试预算必须来自对应领域受控 CLI；
      - 不把本次节点名、Provider id、地址、端口、issue 或日期写入通用流程。
    - 最短证据链
      - 先确认公共服务进程或 systemd unit 是否 active；
      - 再确认公共服务自己的 readiness、API 或受控 status 是否可读；
      - 最后确认一条共享网络路径及至少两条独立消费者通道；
      - 三层证据已能定位共享故障时，停止逐个探测业务和 Provider。
    - 分类与恢复
      - 多个独立消费者同时失败时，优先分类为共享控制面、共享入口、registry 或跨节点网络故障；
      - Kubernetes API 明确拒绝连接时，先恢复 API authority，再解释依赖它的业务读失败；
      - k3s 明确报告 `server/cred/passwd` 新于 datastore 时，将其视为可重建派生凭据漂移：
        - 只通过 owning k3s 受控恢复入口把该文件移动到受保护备份；
        - 重启 k3s 并等待 readiness；
        - 禁止删除 datastore、重置集群或把派生文件反向当作配置真相。
      - WireGuard unit active 不能单独证明数据通道健康：
        - 同时检查最近握手和 owning YAML 声明的最小连通探针；
        - 只有握手过期且探针失败时，才通过受控入口重启对应接口；
        - 网络恢复后不得顺带重启或重配具体 Provider。
      - 公共 registry `connection refused` 与运行镜像 `ImagePullBackOff` 同时出现时，先恢复 registry；
        - runner、claim、Provider 未启动属于下游症状；
        - 不先归因于 Provider 执行耗时或业务调度。
    - 变更边界
      - 只做能恢复共享面的最小、可逆动作；
      - 不使用全量 apply 代替已存在的窄域恢复入口；
      - 临时运行面 patch 必须记录备份或回退方式，且不能成为第二 authority；
      - 需要修改 owning YAML、公共 CLI 或 renderer 时，转入 P3 的独立 worktree、PR 和声明式交付；
      - 用户未授权具体业务或 Provider 时，不修改它们的配置、进程、数据或交付链。
    - 验收与停止条件
      - 公共服务 active 且 readiness 成功；
      - 共享网络探针成功；
      - 至少两条原先同时失败的独立受控通道成功，或 owning CLI 提供等价聚合证据；
      - 满足上述条件后，公共运维任务立即结束；
      - 业务仍有问题时只记录为独立业务故障，不继续扩大当前公共运维范围。
  - 项目适配器
    - 本 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/<task>`，后续编辑、验证、提交、推送和受控 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)。紧凑流程不足以支撑任务时读取该文件。