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

name, description

name	description
unidesk-daddev	UniDesk 分布式敏捷开发流程，覆盖真实运行面探测、最小可逆 patch/热补实验、YAML/Git/自动 CI/CD 持久化和原入口验收。处理跨节点、跨 host、跨 lane 的 bug、HotFix、运行面调试、临时恢复或对接 HWLAB/AgentRun/UniDesk 真实运行面时必须使用。

分布式敏捷开发流程

遵循规范: 本 Skill 遵循 Skill(cli-spec) 规范（精简版，仅保留与流程相关的硬约束）。

• $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。紧凑流程不足以支撑任务时读取该文件。