Merge pull request #1686 from pikasTech/feat/unidesk-hwpod-ops

feat: 新增 Python UI HWPOD 节点运维 skill

docs/reference/agent-instruction-hygiene.md

@@ -1,83 +1,144 @@
-# Agent Instruction Hygiene
+# Agent 指令治理
 
-This document is the long-term reference for keeping always-loaded agent instruction files small, navigable and stable. It applies to local and remote `AGENTS.md`, `CLAUDE.md`-style aliases and any repo-level instruction file that is automatically injected into an agent context.
+- 本文范围：
 
-## Size Budget
+  - 目标：保持自动加载的 Agent 指令文件精简、可导航且稳定；
+  - 适用对象：本地和远端 `AGENTS.md`、`CLAUDE.md` 类别名；
+  - 扩展范围：所有自动注入 Agent 上下文的仓库级指令文件。
 
-`AGENTS.md` is an index, not a knowledge base. The hard size budget for any local or remote `AGENTS.md` is 10 KiB, measured as bytes with `wc -c AGENTS.md`.
+## 体积预算
 
-When an `AGENTS.md` is already over 10 KiB, do not append more detailed rules to it. Split first, then add only a one-line index entry back to `AGENTS.md`.
+- 体积定义：
 
-When editing an `AGENTS.md` would push it over 10 KiB, route the new content to a skill or a `docs/reference/*.md` document and keep `AGENTS.md` as a short pointer.
+  - `AGENTS.md` 是索引，不是知识库；
+  - 本地或远端 `AGENTS.md` 的硬上限均为 10 KiB；
+  - 使用 `wc -c AGENTS.md` 按字节计量。
 
-If loading or printing `AGENTS.md` triggers CLI output dump or context blow-up, treat that as a visibility bug and an instruction-hygiene bug. The fix is to split the file, not to increase output limits or ask agents to read around the dump.
+`AGENTS.md` 已超过 10 KiB 时：
 
-## What Belongs In AGENTS.md
+- 不得继续追加详细规则；
+- 必须先拆分；
+- 只向 `AGENTS.md` 回填一行索引。
 
-Keep only always-needed routing information in `AGENTS.md`:
+- 修改会导致 `AGENTS.md` 超过 10 KiB 时：
 
-- Project identity and source-of-truth boundaries.
-- P0 one-line rules that prevent immediate damage.
-- Links to the authoritative long-term reference document for each domain.
-- Skill names that must be loaded for common workflows.
-- Short warnings about secrets, destructive commands, target workspaces and build bans.
+  - 把新内容分流到 skill 或 `docs/reference/*.md`；
+  - 保持 `AGENTS.md` 为短索引。
 
-Do not put long examples, command transcripts, JSON output, issue timelines, architecture essays, provider-specific debugging logs or one-off incident analysis in `AGENTS.md`.
+- 加载或输出 `AGENTS.md` 触发 CLI 输出转储或上下文膨胀时：
 
-## Where Overflow Content Goes
+  - 将其视为可见性缺陷；
+  - 将其视为指令治理缺陷；
+  - 通过拆分文件修复；
+  - 不得提高输出上限；
+  - 不得要求 Agent 绕过转储读取。
 
-Use this routing order when splitting content out of `AGENTS.md`:
+## AGENTS.md 应包含的内容
 
-- Reusable workflow behavior belongs in a skill `SKILL.md`, for example `$dad-dev`, `$unidesk-cicd`, `$unidesk-gh`, `$unidesk-trans`, `$unidesk-otel`, `$unidesk-webdev` or `$unidesk-ymalops`.
-- Stable project constraints, workspace rules, architecture boundaries and validation criteria belong in `docs/reference/*.md`.
-- CLI shape, output style, route syntax and operator ergonomics belong in `docs/reference/cli.md` unless a narrower reference already owns them.
-- Deployment hygiene, fixed repo boundaries and source-of-truth rules belong in `docs/reference/devops-hygiene.md`.
-- Node/lane-specific HWLAB rules belong in `docs/reference/hwlab.md` and the target repo's own reference docs.
-- AgentRun source-truth and deployment-lane rules belong in `docs/reference/agentrun.md`.
-- Platform-infra and YAML-first operations belong in `docs/reference/platform-infra.md` and `docs/reference/yaml-first-ops.md`.
-- Process notes, temporary findings and dated investigation logs belong in GitHub issues, PR comments or process notes; they must be distilled before entering long-term reference.
+`AGENTS.md` 只保留始终需要的路由信息：
 
-If a rule is both reusable across projects and specific to UniDesk's current directories or services, put the reusable workflow in the skill and put UniDesk-specific paths, lane names and validation boundaries in `docs/reference/*.md`, then cross-reference both.
+- 项目标识和真相源边界；
+- 防止直接损害的一行 P0 规则；
+- 各领域权威长期参考文档链接；
+- 常用工作流必须加载的 skill 名称；
+- Secret、破坏性命令、目标工作区和构建禁令的短警告。
 
-## Split Procedure
+- 禁止内容：
 
-When an agent sees a local or remote `AGENTS.md` over 10 KiB:
+  - 长示例、命令记录或 JSON 输出；
+  - issue 时间线或架构长文；
+  - provider 特定调试日志；
+  - 一次性事故分析。
 
-1. Identify the detailed section being changed or expanded.
-2. Move the detailed content to the owning skill or `docs/reference/*.md` document.
-3. Replace the original section with one concise bullet and a link to the authoritative location.
-4. Preserve P0 damage-prevention warnings in `AGENTS.md`, but compress them to one-line routing rules.
-5. Do not create a single giant overflow archive as the normal solution. A temporary migration note is acceptable only if it immediately points to the domain documents that must absorb it.
-6. Do not add tests, guards or preflight checks just to enforce the size budget unless the user explicitly asks. The default control is documentation hygiene plus concise review.
+## 超出内容的分流位置
 
-For large legacy files, split incrementally by domain. Each new edit should leave the touched domain smaller and better referenced than before.
+- 分流顺序：
 
-## Cross-Reference Requirements
+  - 可复用工作流进入 skill `SKILL.md`，例如：
+    - `$dad-dev`、`$unidesk-cicd`、`$unidesk-gh`；
+    - `$unidesk-trans`、`$unidesk-otel`、`$unidesk-webdev`；
+    - `$unidesk-ymalops`。
+  - 稳定项目约束、工作区规则、架构边界和验收标准进入 `docs/reference/*.md`。
+  - CLI 相关内容：
+    - 形态、输出样式、路由语法和操作体验进入 `docs/reference/cli.md`；
+    - 已有更具体参考文档时进入具体文档。
+  - 部署治理、固定仓库边界和真相源规则进入 `docs/reference/devops-hygiene.md`。
+  - HWLAB 节点/通道规则进入 `docs/reference/hwlab.md` 和目标仓库自身参考文档。
+  - AgentRun 真相源和部署通道规则进入 `docs/reference/agentrun.md`。
+  - 平台基础设施和 YAML-first 运维：
+    - 进入 `docs/reference/platform-infra.md`；
+    - 同时由 `docs/reference/yaml-first-ops.md` 约束。
+  - 过程材料：
+    - 过程记录、临时发现和带日期调查日志进入 GitHub issue、PR 评论或过程记录；
+    - 进入长期参考前必须蒸馏。
 
-Every `AGENTS.md` index entry that points out of the file must name the authoritative target. Prefer direct paths such as `docs/reference/hwlab.md` or skill names such as `$unidesk-cicd`.
+- 规则既能跨项目复用、又依赖 UniDesk 当前目录或服务时：
 
-Avoid duplicated full rules between `AGENTS.md`, skills and long-term reference docs. `AGENTS.md` may summarize; the reference owns the detail. If two references conflict, update the narrower domain reference and keep only one authoritative version.
+  - 把可复用流程放入 skill；
+  - 把 UniDesk 特定路径、通道名和验收边界放入 `docs/reference/*.md`；
+  - 双向交叉引用。
 
-## Secrets And Output Hygiene
+## 拆分步骤
 
-Instruction files must not contain secrets, full API keys, full DSNs, base64 payloads, bearer tokens, SSH private keys or copy-pastable credentials.
+1. 识别正在修改或扩展的详细领域。
+2. 把详细内容移到权威 skill 或 `docs/reference/*.md`。
+3. 用一条简短索引和权威链接替换原详细章节。
+4. 在 `AGENTS.md` 保留 P0 损害预防警告，但压缩为一行路由规则。
+5. 禁止创建巨大溢出文档：
+   - 不得把所有内容移入单个文件；
+   - 临时迁移记录仅在立即指向各领域承接文档时可用。
+6. 用户未明确要求时：
+   - 不为体积预算新增测试、保护代码或预检；
+   - 默认控制方式是文档治理和简洁评审。
 
-Do not paste large CLI output, OTel trace dumps, JSON arrays or browser transcripts into `AGENTS.md`. If a large output demonstrates a durable rule, summarize the rule and link to the issue or reference that owns the conclusion.
+- 大型旧文件治理：
+  - 按领域逐步拆分；
+  - 每次编辑都应让涉及领域更精简；
+  - 每次编辑都应让引用更清晰。
 
-## Current UniDesk Routing Map
+## 交叉引用要求
 
-The current top-level routing map is:
+- 外部索引规则：
 
-- CLI behavior and output: `docs/reference/cli.md`.
-- YAML-first configuration: `docs/reference/yaml-first-ops.md` and `$unidesk-ymalops`.
-- Platform infrastructure: `docs/reference/platform-infra.md` and `$unidesk-sub2api` when Sub2API is involved.
-- Distributed field repair: `$dad-dev` plus `docs/reference/devops-hygiene.md`.
-- CI/CD and rollout: `$unidesk-cicd` plus `docs/reference/cli.md`.
-- GitHub issue and PR writes: `$unidesk-gh`.
-- Trans/remote patch transport: `$unidesk-trans` plus `docs/reference/cli.md`.
-- Web UI, Workbench and web-probe: `$unidesk-webdev`.
-- OpenTelemetry and Tempo: `$unidesk-otel` plus `docs/reference/observability.md`.
-- HWLAB node/lane operation: `docs/reference/hwlab.md`.
-- AgentRun: `docs/reference/agentrun.md`.
-- Master/D601 development environment: `docs/reference/dev-environment.md`.
-- Secretary work: `docs/reference/secretary-reference.md`.
+  - 每条索引必须注明权威目标；
+  - 优先使用 `docs/reference/hwlab.md` 等直接路径；
+  - 也可使用 `$unidesk-cicd` 等 skill 名称。
+
+- 规则归属：
+
+  - 不得在 `AGENTS.md`、skill 和长期参考之间重复完整规则；
+  - `AGENTS.md` 可以保留摘要；
+  - 参考文档拥有细节；
+  - 两个参考文档冲突时，更新职责更具体的文档；
+  - 冲突处理后只保留一个权威版本。
+
+## Secret 与输出治理
+
+- 指令文件不得包含：
+
+  - Secret、完整 API key 或完整 DSN；
+  - base64 载荷或 bearer token；
+  - SSH 私钥或可直接复用的凭据。
+
+- 大输出治理：
+
+  - 不得把大段 CLI 输出粘贴进 `AGENTS.md`；
+  - 不得粘贴 OTel trace 转储、JSON 数组或浏览器记录；
+  - 大输出证明可复用规则时，只保留规则摘要；
+  - 摘要必须链接到拥有完整结论的 issue 或参考文档。
+
+## 当前 UniDesk 路由图
+
+- 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`。
+- CI/CD 与发布：`$unidesk-cicd` 与 `docs/reference/cli.md`。
+- GitHub issue 与 PR 写入：`$unidesk-gh`。
+- Trans/远端补丁传输：`$unidesk-trans` 与 `docs/reference/cli.md`。
+- Web 界面、Workbench 和 web-probe：`$unidesk-webdev`。
+- OpenTelemetry 与 Tempo：`$unidesk-otel` 与 `docs/reference/observability.md`。
+- HWLAB 节点/通道运维：`docs/reference/hwlab.md`。
+- AgentRun：`docs/reference/agentrun.md`。
+- Master/D601 开发环境：`docs/reference/dev-environment.md`。
+- 秘书工作：`docs/reference/secretary-reference.md`。

docs/reference/docs-governance.md

@@ -1,53 +1,175 @@
 # 文档治理与过程蒸馏
 
-本文是 UniDesk 本机文档治理的长期参考，适用于 `AGENTS.md`、`CLAUDE.md` 类入口文档、`docs/reference/*.md`、skill 文档和过程文档蒸馏。具体任务仍先加载 `$docs-spec`；本文沉淀长期稳定规则和本仓判定标准。
+- 本文适用于：
+
+  - `AGENTS.md`、`CLAUDE.md` 类入口文档；
+  - `docs/reference/*.md`；
+  - skill 文档；
+  - 过程文档蒸馏。
+
+- 使用要求：
+
+  - 具体任务先加载 `$docs-spec`；
+  - 本文只沉淀长期稳定规则和本仓判定标准。
+
+## 中文与单行治理
+
+- 自然语言标题和正文统一使用中文；发现非中文内容时先翻译再继续。
+- 新写内容必须使用中文。
+- 一个自然语言单行不得堆叠多个独立约束、步骤、条件或并列事实。
+- 发现过长单行时立即处理，不等待集中清理。
+- 过长内容一律按语义拆成主项与下级列表；禁止只做自然换行或物理折行来伪装拆分。
+- 命令、路径、URL、代码、协议名、字段名和机器可读单值可以保留原文或长行。
 
 ## 顶级入口
 
-`AGENTS.md` 只作为项目级顶级索引，用于快速定位命令、入口、技能和长期参考文档。它不能承载实现细节、参数说明、长流程、历史排障、日志、JSON、trace dump 或一次性过程记录。
+- `AGENTS.md` 职责：
 
-与 `AGENTS.md` 具有同等作用的入口文档只保留一行 `@AGENTS.md`，避免 `CLAUDE.md`、`AGENTS.md` 或其他入口出现多套口径。
+  - 只作为项目级顶级索引；
+  - 用于快速定位命令、入口、技能和长期参考文档；
+  - 不承载实现细节、参数说明或长流程；
+  - 不承载历史排障、日志、JSON、trace dump 或一次性过程记录。
 
-每个命令或工作流在 `AGENTS.md` 中最多保留一条主索引；需要多个功能点时，用短子列表分别指向对应的 `docs/reference/*.md` 或 skill。子列表只写一句话摘要，不展开背景和用法。
+- 同级入口文档规则：
+  - 与 `AGENTS.md` 具有同等作用的入口文档只保留一行 `@AGENTS.md`；
+  - 避免 `CLAUDE.md`、`AGENTS.md` 或其他入口出现多套口径。
+
+- 命令与工作流索引：
+
+  - 每个命令或工作流最多保留一条主索引；
+  - 多个功能点使用短子列表；
+  - 子列表分别指向对应的 `docs/reference/*.md` 或 skill；
+  - 子列表只写一句话摘要；
+  - 不展开背景和用法。
 
 `AGENTS.md` 的体积、拆分和输出 dump 治理细则见 `docs/reference/agent-instruction-hygiene.md`。
 
 ## 长期参考
 
-`docs/reference/` 只记录长期稳定、可重复复用的入口、前置条件、约束、职责边界和判定标准。不要写日期、一次性执行记录、实测流水账、changelog 式内容或容易过时的临时结论。
+- `docs/reference/` 内容边界：
 
-详细说明优先进入职责明确的独立参考文档，再回到 `AGENTS.md` 维护一句话索引。跨文档重复时，选择或新建唯一权威出处，其他位置只交叉引用。
+  - 只记录长期稳定、可重复复用的入口、前置条件和约束；
+  - 记录职责边界和判定标准；
+  - 不写日期、一次性执行记录或实测流水账；
+  - 不写 changelog 式内容或容易过时的临时结论。
 
-知识更新按四类处理：增加新知识、删除过时知识、修正错误知识、合并重复知识。新旧材料冲突时，以新的稳定结论替换旧结论，并删除或压缩旧说法。
+- 详细说明归属：
 
-`docs/reference/` 不维护 YAML/config 已能表达的业务策略数值、阈值、冷却时间、退避窗口、容量或价格作为第二真相。长期参考只写“数值以 YAML/config 为准”以及同步、渲染、验证入口。
+  - 优先进入职责明确的独立参考文档；
+  - 再回到 `AGENTS.md` 维护一句话索引；
+  - 跨文档重复时，选择或新建唯一权威出处；
+  - 其他位置只交叉引用。
 
-长期参考不得要求为业务策略数值新增合同测试、代码硬范围或 schema 内容校验；配置校验只检查格式、类型、必填项和可渲染性。
+- 知识更新分为：
 
-涉及 skill 的长期参考必须写清该 skill 与当前项目代码、硬件、目录、运行面和判定标准的具体关系。通用安装、CLI 参数、子命令和完整用法直接引用对应 `SKILL.md`，不要在 reference 中复制一份。
+  - 增加新知识；
+  - 删除过时知识；
+  - 修正错误知识；
+  - 合并重复知识。
+
+- 新旧材料冲突时：
+
+  - 以新的稳定结论替换旧结论；
+  - 删除或压缩旧说法。
+
+`docs/reference/` 不维护 YAML/config 已能表达的以下内容作为第二真相：
+
+- 业务策略数值和阈值；
+- 冷却时间和退避窗口；
+- 容量或价格。
+
+- 长期参考只保留：
+
+  - “数值以 YAML/config 为准”；
+  - 同步入口；
+  - 渲染入口；
+  - 验证入口。
+
+- 业务策略数值规则：
+
+  - 不得要求新增合同测试；
+  - 不得增加代码硬范围；
+  - 不得增加 schema 内容校验；
+  - 配置校验只检查格式、类型、必填项和可渲染性。
+
+- 涉及 skill 的长期参考必须写清该 skill 与以下内容的具体关系：
+
+  - 当前项目代码和硬件；
+  - 当前目录和运行面；
+  - 当前判定标准。
+
+- 通用用法归属：
+
+  - 通用安装直接引用对应 `SKILL.md`；
+  - CLI 参数和子命令直接引用对应 `SKILL.md`；
+  - 完整用法直接引用对应 `SKILL.md`；
+  - 不得在 reference 中复制一份。
 
 ## Skill 文档
 
-`SKILL.md` 是短入口和路由表，不承载完整 runbook、历史排障、长命令矩阵或大段背景。内容变长时，拆到同 skill 的 `references/`。
+- `SKILL.md` 是短入口和路由表，不能承载：
 
-拆分后的 reference 必须按职责、生命周期和读取场景组织，例如部署、账号管理、公开暴露、验收、排障、禁止事项分别成文件。禁止把内容重新堆成 `references/full.md`、`all.md`、`guide.md` 或其他变相超级 Markdown。
+  - 完整 runbook；
+  - 历史排障；
+  - 长命令矩阵；
+  - 大段背景；
+  - 内容变长时，拆到同 skill 的 `references/`。
 
-`SKILL.md` 必须明确何时读取哪个 reference，让 agent 按任务加载最小必要文件。单个 reference 继续变长时，继续按职责拆分，并在旧文件保留短索引或迁移说明。
+- reference 拆分规则：
+
+  - 按职责、生命周期和读取场景组织；
+  - 部署、账号管理、公开暴露、验收、排障和禁止事项分别成文件；
+  - 禁止重新堆成 `references/full.md`、`all.md` 或 `guide.md`；
+  - 禁止创建其他变相超级 Markdown。
+
+- reference 路由规则：
+
+  - `SKILL.md` 必须明确何时读取哪个 reference；
+  - Agent 按任务加载最小必要文件；
+  - 单个 reference 继续变长时，继续按职责拆分；
+  - 在旧文件保留短索引或迁移说明。
 
 ## 过程文档蒸馏
 
-过程文档是开发过程中的一手历史资料，通常带有时间戳、阶段性判断和临时结论。蒸馏时不得篡改过程文档本身。
+- 过程文档定义：
+  - 属于开发过程中的一手历史资料；
+  - 通常带有时间戳、阶段性判断和临时结论；
+  - 蒸馏时不得篡改过程文档本身。
+- 蒸馏顺序：
+  - 从旧到新；
+  - 大文件采用滑动窗口；
+  - 读一段就更新一次长期参考；
+  - 不等全部读完再统一整理。
 
-蒸馏顺序从旧到新。大文件采用滑动窗口处理，读一段就更新一次长期参考，不等全部读完再统一整理。
+- 过程结论规则：
 
-新的稳定结论覆盖旧结论。长期参考只简述总体发展过程和关键节点，避免把发展过程写成流水账；越早期的过程越应压缩。
+  - 新的稳定结论覆盖旧结论；
+  - 长期参考只简述总体发展过程和关键节点；
+  - 避免把发展过程写成流水账；
+  - 越早期的过程越应压缩。
 
-重要过程节点可以交叉引用原始过程文档、issue 或 PR，但长期参考必须保留可直接复用的当前规则、边界和验证入口。
+- 重要过程节点：
+  - 可以交叉引用原始过程文档、issue 或 PR；
+  - 长期参考必须保留可直接复用的当前规则、边界和验证入口。
 
 ## 本机工作流
 
-单纯文档、`AGENTS.md`、`docs/reference/*.md`、skill 规则、runbook 和过程文档蒸馏可在当前主 worktree 处理，不需要新建 `.worktree` 或 PR。开始前必须按本仓 P0 规则快进到最新 `origin/master`，并保留并行脏改。
+- 以下工作可在当前主 worktree 处理，不需要新建 `.worktree` 或 PR：
 
-该例外只覆盖文档和规则本身。不得夹带源码、配置、部署、Secret、运行面变更或 issue lifecycle 写操作。
+  - 单纯文档；
+  - `AGENTS.md` 和 `docs/reference/*.md`；
+  - skill 规则和 runbook；
+  - 过程文档蒸馏。
 
-收尾检查以最小语法、链接、grep 和 diff 审核为主。完成后只提交本次文档治理相关文件；若工作区存在并行修改，不得把无关文件加入提交。
+开始前必须按本仓 P0 规则快进到最新 `origin/master`，并保留并行脏改。
+
+- 本机工作流例外边界：
+  - 只覆盖文档和规则本身；
+  - 不得夹带源码、配置、部署或 Secret；
+  - 不得夹带运行面变更或 issue lifecycle 写操作。
+
+- 收尾要求：
+
+  - 以最小语法、链接、grep 和 diff 审核为主；
+  - 只提交本次文档治理相关文件；
+  - 工作区存在并行修改时，不得把无关文件加入提交。