docs: 固化文档和技能中文写作规则

.agents/skills/unidesk-hwpod-ops/SKILL.md

@@ -1,26 +1,26 @@
 ---
 name: unidesk-hwpod-ops
-description: UniDesk HWLAB HWPOD 节点运维技能，覆盖 Windows 单文件 Python UI `hwlab-node.py` 的发现、安装、GUI/托盘、连接、更新、日志、诊断、nodeId、workspace、HWPOD node-ops、MDTODO source 和 legacy Bun runner 漂移。用户提到 hwpod-node、hwlab-node、Python UI node、HWPOD 节点上下线、D601/G14-WSL 硬件节点、workspace 绑定或 HWLAB Web MDTODO 读取时使用。
+description: UniDesk HWLAB HWPOD 节点运维技能，覆盖 Windows 单文件 Python 图形节点 `hwlab-node.py` 的发现、安装、界面/托盘、连接、更新、日志、诊断、nodeId、工作区、HWPOD 节点操作、MDTODO 来源和旧 Bun 运行器漂移。用户提到 hwpod-node、hwlab-node、Python 图形节点、HWPOD 节点上下线、D601/G14-WSL 硬件节点、工作区绑定或 HWLAB Web MDTODO 读取时使用。
 ---
 
-# UniDesk HWPOD Ops
+# UniDesk HWPOD 运维
 
-以当前 HWLAB v0.3 Python UI node 为默认运维对象。旧 `$hwpod-ops` 中的 TypeScript/Bun `serve|connect` 只用于历史漂移调查，不作为新节点完成态。
+以当前 HWLAB v0.3 Python 图形节点为默认运维对象。旧 `$hwpod-ops` 中的 TypeScript/Bun `serve|connect` 只用于历史漂移调查，不作为新节点完成态。
 
-## P0 Boundaries
+## P0 边界
 
-- 当前 HWLAB 固定运行面由 UniDesk `config/hwlab-node-lanes.yaml` 选择；先运行 `cicd status` 和 `source-workspace status`，不要复用旧 G14/v0.2 URL。
-- Python UI node 权威源码是选中 HWLAB source workspace 的 `tools/hwlab-node.py`；发布版本和 SHA 由选中 origin 的 `/v1/hwlab-node/update` 与 `/v1/hwlab-node/download/hwlab-node.py` 给出。
-- 节点、workspace、HWPOD resource、MDTODO source、endpoint 和 Secret 都必须进入 owning YAML/configRef。`~/.hwlab/config.json` 是桌面应用配置，不是平台资源真相。
-- Secret 只通过 YAML `sourceRef`/`targetKey` 和受控入口下发。状态、日志和 issue 只披露 presence、fingerprint 和脱敏摘要。
-- Windows 节点使用主动出站 WebSocket；不要为用户 PC 增加入站端口或 direct-url fallback。
-- Windows Python UI node 必须优先用目标 Windows 交互用户可见的原生 `python.exe` 启动。不要用 WSL Python、SSH helper 自带解释器、Bun runner 或非交互 Windows service 替代；解释器路径/版本必须进入 node profile 与状态证据。
-- HWPOD node 部署必须是 YAML-first + repo-owned CLI。只支持 owning YAML 已声明且 `trans` route 可解析、可访问的 node；CLI 可以在内部使用 `trans` 作为 transport，但操作者不得用手写 `trans`/PowerShell/cmd 完成安装、更新、配置或自启动。受控 CLI 缺失时先实现 CLI，不把手工部署当临时完成态。
-- 调查可只读访问现场。安装、注册、更新、停止旧 runner 或改 MDTODO source 属于运行面变更，必须先加载 `$dad-dev`；部署/rollout 同时加载 `$unidesk-cicd`，YAML 变更同时加载 `$unidesk-ymalops`。
-- 远端操作走 `$unidesk-trans`。普通 `trans` 保持短连接；GUI 进程不得作为透传子进程长挂。
-- Python node 当前若没有 workspace allowlist/规范化、注册认证或 capability parity，不得把“WebSocket 已连接”报告为 HWPOD/MDTODO 可用。
+- 当前 HWLAB 固定运行面由 UniDesk `config/hwlab-node-lanes.yaml` 选择；先运行 `cicd status` 和 `source-workspace status`，不要复用旧 G14/v0.2 地址。
+- Python 图形节点权威源码是选中 HWLAB 源工作区的 `tools/hwlab-node.py`；发布版本和 SHA 由选中入口的 `/v1/hwlab-node/update` 与 `/v1/hwlab-node/download/hwlab-node.py` 给出。
+- 节点、工作区、HWPOD 资源、MDTODO 来源、端点和 Secret 都必须进入权威 YAML/配置引用。`~/.hwlab/config.json` 是桌面应用配置，不是平台资源真相。
+- Secret 只通过 YAML `sourceRef`/`targetKey` 和受控入口下发。状态、日志和 issue 只披露是否存在、指纹和脱敏摘要。
+- Windows 节点使用主动出站 WebSocket；不要为用户电脑增加入站端口或直连地址兜底。
+- Windows Python 图形节点必须优先用目标 Windows 交互用户可见的原生 `python.exe` 启动。不要用 WSL Python、SSH 辅助程序自带解释器、Bun 运行器或非交互 Windows 服务替代；解释器路径/版本必须进入节点配置和状态证据。
+- HWPOD 节点部署必须采用 YAML-first + 仓库自带 CLI。只支持权威 YAML 已声明且 `trans` 路由可解析、可访问的节点；CLI 可以在内部使用 `trans` 作为传输层，但操作者不得用手写 `trans`/PowerShell/cmd 完成安装、更新、配置或自启动。受控 CLI 缺失时先实现 CLI，不把手工部署当临时完成态。
+- 调查可只读访问现场。安装、注册、更新、停止旧运行器或修改 MDTODO 来源属于运行面变更，必须先加载 `$dad-dev`；部署/发布同时加载 `$unidesk-cicd`，YAML 变更同时加载 `$unidesk-ymalops`。
+- 远端操作走 `$unidesk-trans`。普通 `trans` 保持短连接；图形进程不得作为透传子进程长挂。
+- Python 节点当前若没有工作区允许列表/规范化、注册认证或能力对齐，不得把“WebSocket 已连接”报告为 HWPOD/MDTODO 可用。
 
-## Read-Only Triage
+## 只读调查
 
 ```bash
 bun scripts/cli.ts cicd status --node NC01
@@ -31,36 +31,36 @@ trans <provider>:win ps 'Get-CimInstance Win32_Process | Where-Object { $_.Comma
 trans <provider>:win ps 'Get-ScheduledTask -ErrorAction SilentlyContinue | Where-Object { $_.TaskName -match "HWLAB|HWPOD" } | Select-Object TaskName,State | ConvertTo-Json -Compress'
 ```
 
-Classify results separately:
+分别判断以下状态：
 
-- `desktop-ready`: Python/tkinter and an interactive Windows session are available.
-- `process-ready`: exactly one intended Python UI process is alive; no conflicting Bun authority.
-- `registered`: cloud registry acknowledges the expected nodeId.
-- `workspace-ready`: `node.inventory` and bounded workspace read target the YAML-selected root.
-- `mdtodo-ready`: Project Management source save/probe/reindex succeeds through public HWPOD workspace ops.
+- `desktop-ready`：Python/tkinter 和交互式 Windows 会话可用。
+- `process-ready`：只有一个预期的 Python 图形进程存活，不存在冲突的 Bun 执行权威。
+- `registered`：云端注册表已确认预期 nodeId。
+- `workspace-ready`：`node.inventory` 和有界工作区读取指向 YAML 选中的根目录。
+- `mdtodo-ready`：项目管理来源通过公共 HWPOD 工作区操作完成保存、探测和重建索引。
 
-Read [references/python-ui-node.md](references/python-ui-node.md) for the current application contract, update flow and known gaps. Read [references/workspace-mdtodo.md](references/workspace-mdtodo.md) when adding a node, binding a workspace or validating HWLAB Web MDTODO.
+调查当前应用合同、更新流程和已知缺口时读 [references/python-ui-node.md](references/python-ui-node.md)。新增节点、绑定工作区或验收 HWLAB Web MDTODO 时读 [references/workspace-mdtodo.md](references/workspace-mdtodo.md)。
 
-## Change Workflow
+## 变更流程
 
-1. Observe the selected HWLAB node/lane, public origin, Python release metadata, Windows user/session, current node process, task/Run key, config presence and legacy runners.
-2. Update the owning spec first when node identity, workspace root, resource binding, authentication, capabilities or MDTODO source changes.
-3. Use the repo-owned `hwlab nodes hwpod-node` plan/status/apply command family selected by current CLI help. Require its preflight to resolve the YAML node profile and prove the node's `trans` route is reachable before mutation. If this command family does not exist, implement it before deployment.
-4. Let the controlled CLI render/validate config, fetch the published Python artifact, verify SHA, resolve the target interactive user's Windows `python.exe`, install files and apply the YAML-declared login-start policy. Keep nodeId, URL, workspace and retry/update settings out of generated helper code.
-5. Prove one active authority, expected version/nodeId, registration, `node.health`, `node.inventory`, bounded workspace read and structured diagnostics.
-6. Validate MDTODO through the HWLAB Web-equivalent path: source save, probe, reindex, files/tasks visible. Direct `trans cat` is only P1 diagnosis.
-7. Record source commit, artifact SHA, nodeId, workspace fingerprint/path summary, registration state, operation request/trace IDs and MDTODO source/reindex result. Never record raw Markdown or credentials by default.
+1. 观察选中的 HWLAB 节点/通道、公共入口、Python 发布元数据、Windows 用户/会话、当前节点进程、任务/启动项、配置是否存在和旧运行器。
+2. 节点身份、工作区根、资源绑定、认证、能力或 MDTODO 来源变化时，先更新权威规格。
+3. 使用当前 CLI 帮助选定的仓库自带 `hwlab nodes hwpod-node` 规划/状态/应用命令族。变更前要求预检解析 YAML 节点配置，并证明节点的 `trans` 路由可达；命令族不存在时先实现它。
+4. 由受控 CLI 渲染并校验配置、获取已发布 Python 文件、校验 SHA、解析目标交互用户的 Windows `python.exe`、安装文件并应用 YAML 声明的登录自启动策略。nodeId、地址、工作区和重连/更新设置不得硬编码进生成的辅助代码。
+5. 证明单一执行权威、预期版本/nodeId、注册、`node.health`、`node.inventory`、有界工作区读取和结构化诊断。
+6. 通过 HWLAB Web 等价路径验收 MDTODO：来源保存、探测、重建索引、文件/任务可见。直接 `trans cat` 只属于 P1 诊断。
+7. 记录源提交、文件 SHA、nodeId、工作区指纹/路径摘要、注册状态、操作 request/trace 标识和 MDTODO 来源/重建索引结果。默认不得记录 Markdown 正文或凭据。
 
-## Stop Conditions
+## 停止条件
 
-- Stop before mutation if the selected lane/source authority is unclear or stale.
-- Stop before deployment if the target is absent from owning YAML, has no resolvable/reachable `trans` route, or the repo-owned plan/status/apply CLI is missing.
-- Stop before starting a second runner if an existing process controls the same nodeId/resource.
-- Stop before MDTODO write/reindex if workspace containment is not enforced or the source can escape its declared root.
-- Treat node mismatch, auth failure, missing workspace, capability mismatch, legacy drift and source projection failure as different blockers.
-- Do not close an HWPOD issue on process health alone; use the user's original HWLAB Web/CaseRun/MDTODO entrypoint.
+- 选中的通道/源权威不清晰或过期时，在变更前停止。
+- 目标未进入权威 YAML、没有可解析且可达的 `trans` 路由，或仓库自带规划/状态/应用 CLI 缺失时，在部署前停止。
+- 现有进程控制相同 nodeId/资源时，在启动第二个运行器前停止。
+- 工作区未实施包含性约束或来源可能逃逸声明根目录时，在 MDTODO 写入/重建索引前停止。
+- 节点不匹配、认证失败、工作区缺失、能力不匹配、旧运行器漂移和来源投影失败必须作为不同阻塞项处理。
+- 不得只凭进程健康关闭 HWPOD issue；必须使用用户原始的 HWLAB Web/CaseRun/MDTODO 入口。
 
-## References
+## 参考文档
 
-- Python UI node contract, local files, update endpoints and drift: [references/python-ui-node.md](references/python-ui-node.md).
-- Node onboarding, workspace binding and MDTODO verification: [references/workspace-mdtodo.md](references/workspace-mdtodo.md).
+- Python 图形节点合同、本地文件、更新端点和漂移：[references/python-ui-node.md](references/python-ui-node.md)。
+- 节点接入、工作区绑定和 MDTODO 验收：[references/workspace-mdtodo.md](references/workspace-mdtodo.md)。

.agents/skills/unidesk-hwpod-ops/references/python-ui-node.md

@@ -1,37 +1,37 @@
-# Python UI Node
+# Python 图形节点
 
-## Current Source
+## 当前权威来源
 
-- HWLAB source: `tools/hwlab-node.py` on the YAML-selected v0.3 source workspace.
-- Application: single-file Python/tkinter GUI with Windows tray, reconnect loop, rotating log and self-update.
-- Local state: `%USERPROFILE%\.hwlab\config.json`, `state.json`, `logs\hwlab-node.log`, `update\`.
-- Default public origin: `https://hwlab.pikapython.com`.
-- Update metadata: `GET /v1/hwlab-node/update?platform=windows&channel=stable&current=<version>`.
-- Artifact: `GET /v1/hwlab-node/download/hwlab-node.py`; verify the metadata SHA before replacement.
-- Node transport: active outbound `wss://<origin>/v1/hwpod-node/ws` registration and heartbeat.
-- Node-ops contract: `hwpod-node-ops-v1`.
+- HWLAB 源码：YAML 选中的 v0.3 源工作区内 `tools/hwlab-node.py`。
+- 应用形态：单文件 Python/tkinter 图形应用，包含 Windows 托盘、自动重连、日志轮转和自更新。
+- 本地状态：`%USERPROFILE%\.hwlab\config.json`、`state.json`、`logs\hwlab-node.log`、`update\`。
+- 默认公共入口：`https://hwlab.pikapython.com`。
+- 更新元数据：`GET /v1/hwlab-node/update?platform=windows&channel=stable&current=<version>`。
+- 发布文件：`GET /v1/hwlab-node/download/hwlab-node.py`；替换前校验元数据给出的 SHA。
+- 节点传输：主动出站连接 `wss://<origin>/v1/hwpod-node/ws`，完成注册和心跳。
+- 节点操作合同：`hwpod-node-ops-v1`。
 
-Do not copy version numbers or SHA values into long-lived instructions. Read them from the selected runtime/source during each operation.
+不要把版本号或 SHA 写入长期指令。每次操作从选中的运行面/源码重新读取。
 
-## Desktop Configuration
+## 桌面配置
 
-The current application exposes `serverUrl`, `nodeId`, `autoConnect`, update settings and logging settings. It intentionally accepts no CLI arguments or `HWLAB_*` environment variables.
+当前应用暴露 `serverUrl`、`nodeId`、`autoConnect`、更新设置和日志设置。应用有意不接受 CLI 参数或 `HWLAB_*` 环境变量。
 
-Run the application with the target Windows user's native interpreter. Resolve `python.exe` from the same interactive login context that owns `%USERPROFILE%\.hwlab` and the tray, then persist the selected interpreter path in the owning node profile/start declaration. `python --version`, `Get-Command python` and a tkinter import are discovery evidence; a WSL `/usr/bin/python`, SSH-side helper interpreter or hidden service account is not an acceptable runtime.
+必须使用目标 Windows 用户的原生解释器运行应用。从拥有 `%USERPROFILE%\.hwlab` 和托盘的同一交互登录上下文解析 `python.exe`，再把选中的解释器路径写入权威节点配置/启动声明。`python --version`、`Get-Command python` 和 tkinter 导入属于发现证据；WSL `/usr/bin/python`、SSH 侧辅助解释器或隐藏服务账号不能作为运行时。
 
-Treat local config as operator preference only. Platform declarations still own:
+本地配置只表达操作者偏好。平台声明仍然拥有：
 
-- node/lane and unique nodeId;
-- HWPOD resource and capability binding;
-- allowed workspace roots;
-- WebSocket/auth Secret sourceRef;
-- managed login/start policy;
-- Windows interpreter path/version and interactive user;
-- Project Management MDTODO sources.
+- 节点/通道和唯一 nodeId；
+- HWPOD 资源与能力绑定；
+- 允许的工作区根目录；
+- WebSocket/认证 Secret 来源引用；
+- 受管登录/启动策略；
+- Windows 解释器路径/版本和交互用户；
+- 项目管理 MDTODO 来源。
 
-## Status Evidence
+## 状态证据
 
-Collect bounded, redacted facts:
+只采集有界、脱敏的事实：
 
 ```powershell
 $root = Join-Path $HOME ".hwlab"
@@ -44,35 +44,35 @@ $root = Join-Path $HOME ".hwlab"
 } | ConvertTo-Json -Compress
 ```
 
-Read config fields only when needed and redact any unknown future Secret-bearing field. Prefer cloud `node.health`, `node.version`, `node.inventory` and `node.diagnostics` results for registration/runtime evidence.
+只在需要时读取配置字段，并对未来可能出现的 Secret 字段脱敏。注册/运行证据优先使用云端 `node.health`、`node.version`、`node.inventory` 和 `node.diagnostics` 结果。
 
-## Controlled Deployment
+## 受控部署
 
-Deployment belongs to a YAML-first UniDesk CLI command family, not to an operator recipe. The command family must provide bounded `plan`, `status` and confirmed `apply` actions and must:
+部署属于 YAML-first UniDesk CLI 命令族，不属于操作者手工步骤。命令族必须提供有界的规划、状态和显式确认应用动作，并满足：
 
-- resolve node/lane, Windows route, interactive user, pythonPath, runtime root, artifact/update origin, nodeId, SecretRefs, allowed workspace roots and login-start policy from owning YAML/configRefs;
-- reject targets without a resolvable and reachable `trans` route;
-- use `trans` only inside the CLI transport adapter;
-- verify downloaded artifact SHA before writing;
-- make apply idempotent and report written file fingerprints, config fingerprint, interpreter version, start registration, process/registry state and redacted blockers;
-- avoid launching the GUI as a child of the short SSH/trans request;
-- preserve an interactive Windows user session for GUI/tray and distinguish "installed" from "visible and registered".
+- 从权威 YAML/配置引用解析节点/通道、Windows 路由、交互用户、pythonPath、运行目录、文件/更新入口、nodeId、SecretRefs、允许的工作区根和登录自启动策略；
+- 拒绝没有可解析且可达 `trans` 路由的目标；
+- 仅在 CLI 传输适配器内部使用 `trans`；
+- 写入前校验下载文件的 SHA；
+- 保证应用幂等，并报告写入文件指纹、配置指纹、解释器版本、启动注册、进程/注册表状态和脱敏阻塞项；
+- 避免把图形应用作为短 SSH/trans 请求的子进程启动；
+- 保持交互式 Windows 用户会话，使界面/托盘可见，并区分“已安装”和“界面可见且已注册”。
 
-Until this command family exists, only read-only discovery is allowed. Manual download, remote PowerShell file writes, ad hoc Scheduled Tasks and direct process launch are diagnostics, not deployment evidence.
+命令族不存在时只允许只读发现。人工下载、远端 PowerShell 写文件、临时计划任务和直接启动进程只属于诊断，不是部署证据。
 
-## Known Gaps To Check
+## 每次必须检查的缺口
 
-Never assume the newest published file has solved these items; inspect the selected source/version:
+不要假设最新发布文件已经解决以下事项；必须检查选中的源码/版本：
 
-- Default nodeId may still be D601-specific.
-- Workspace operations may accept request-provided absolute paths without a configured allowlist or containment check.
-- WebSocket registration may lack a node credential even when cloud-api supports a token.
-- Capabilities may lag the cloud contract, especially apply-patch, UART write/JSON-RPC, Keil and structured blockers.
-- GUI close-to-tray is not equivalent to login persistence; a scheduled task in a non-interactive session can hide the UI/tray.
-- A legacy Bun runner may remain active under another task, Run key or runtime directory.
+- 默认 nodeId 可能仍然绑定 D601。
+- 工作区操作可能接受请求提供的绝对路径，但没有配置允许列表或包含性检查。
+- 即使 cloud-api 支持 token，WebSocket 注册也可能仍然缺少节点凭据。
+- 实际能力可能落后于云端合同，尤其是 apply-patch、UART 写入/JSON-RPC、Keil 和结构化阻塞项。
+- 图形窗口关闭到托盘不等于登录持久化；非交互会话中的计划任务可能隐藏界面/托盘。
+- 另一个任务、启动项或运行目录中可能仍有旧 Bun 运行器活动。
 
-Surface each gap separately. Do not add local fallback paths to conceal it.
+每个缺口必须分别暴露，不得增加本地兜底路径掩盖问题。
 
-## Legacy Drift
+## 旧运行器漂移
 
-Legacy evidence includes `bun.exe tools\hwpod-node.ts connect`, old IP/port cloud URLs, `hwpod-node-runtime`, and old scheduled task names. Before stopping anything, compare nodeId, cloud URL, resource binding and active hardware work. Any change that can interrupt a hardware operation requires an explicit maintenance window and `$dad-dev` workflow.
+旧运行器证据包括 `bun.exe tools\hwpod-node.ts connect`、旧 IP/端口云端地址、`hwpod-node-runtime` 和旧计划任务名。停止任何进程前，先比较 nodeId、云端地址、资源绑定和活动硬件任务。可能中断硬件操作的变更必须有明确维护窗口，并遵循 `$dad-dev` 流程。

.agents/skills/unidesk-hwpod-ops/references/workspace-mdtodo.md

@@ -1,57 +1,57 @@
-# Workspace And MDTODO
+# 工作区与 MDTODO
 
-## Required Declarations
+## 必需声明
 
-Add a node/workspace only through owning YAML/configRef. Keep these concepts distinct:
+只能通过权威 YAML/配置引用新增节点/工作区。以下概念必须分离：
 
-| Concept | Required fact |
+| 概念 | 必需事实 |
 | --- | --- |
-| Desktop node | HWLAB node/lane, unique nodeId, Python artifact source, Windows pythonPath/version, managed interactive user/start policy |
-| HWPOD resource | hwpodId/resourceId, nodeId, capabilities, workspaceRootRef |
-| Workspace policy | allowed Windows roots, containment/normalization policy, read/write capabilities |
-| MDTODO source | sourceId, projectId, hwpodId, nodeId, workspaceRootRef, mdtodoRootRef |
-| Service routing | public/service node-ops configRef and Secret sourceRef |
+| 桌面节点 | HWLAB 节点/通道、唯一 nodeId、Python 文件来源、Windows pythonPath/版本、受管交互用户/启动策略 |
+| HWPOD 资源 | hwpodId/resourceId、nodeId、能力、workspaceRootRef |
+| 工作区策略 | 允许的 Windows 根目录、包含性/规范化策略、读写能力 |
+| MDTODO 来源 | sourceId、projectId、hwpodId、nodeId、workspaceRootRef、mdtodoRootRef |
+| 服务路由 | 公共/服务节点操作配置引用和 Secret 来源引用 |
 
-For a Windows Python UI node, `workspaceRootRef` must use the Windows path visible to that process. A WSL `/mnt/<drive>/...` route may prove the same files exist, but it is not the Python node's path authority.
+Windows Python 图形节点的 `workspaceRootRef` 必须使用该进程可见的 Windows 路径。WSL `/mnt/<drive>/...` 路由可以证明同一批文件存在，但不是 Python 节点的路径权威。
 
-## Onboarding Sequence
+## 接入顺序
 
-1. Confirm the Windows path exists, is a directory and contains the intended MDTODO root.
-2. Allocate a nodeId distinct from D601 and all existing nodes.
-3. Add YAML declarations for desktop node, HWPOD resource/workspace policy and MDTODO source.
-4. Add a resolvable `trans` Windows route to the node profile and prove it is reachable with the controlled CLI preflight.
-5. Ensure the Python node enforces declared workspace roots with canonical-path containment; reject absolute paths outside them, `..`, symlink/junction escape and undeclared roots.
-6. Configure registration authentication from SecretRef without printing credentials.
-7. Use the repo-owned YAML-first CLI to install the SHA-verified Python artifact and apply the selected interactive Windows login-start policy.
-8. Prove cloud registration and expected capabilities.
-9. Run `node.inventory` against the declared root, then bounded `workspace.ls`/`workspace.cat` under the MDTODO root.
-10. Save/probe/reindex the Project Management source and verify files/tasks in HWLAB Web.
+1. 确认 Windows 路径存在、是目录并包含预期 MDTODO 根目录。
+2. 分配与 D601 和所有现有节点不同的 nodeId。
+3. 增加桌面节点、HWPOD 资源/工作区策略和 MDTODO 来源的 YAML 声明。
+4. 在节点配置中增加可解析的 `trans` Windows 路由，并通过受控 CLI 预检证明其可达。
+5. 确保 Python 节点对声明的工作区根实施规范路径包含性检查；拒绝根目录之外的绝对路径、`..`、符号链接/联接点逃逸和未声明根目录。
+6. 从 SecretRef 配置注册认证，不打印凭据。
+7. 使用仓库自带 YAML-first CLI 安装已校验 SHA 的 Python 文件，并应用选中的交互式 Windows 登录自启动策略。
+8. 证明云端注册和预期能力。
+9. 对声明根目录运行 `node.inventory`，再对 MDTODO 根目录执行有界 `workspace.ls`/`workspace.cat`。
+10. 保存/探测/重建项目管理来源索引，并在 HWLAB Web 验证文件/任务。
 
-## MDTODO Acceptance
+## MDTODO 验收
 
-Use the public Project Management path and selected source:
+使用公共项目管理路径和选中的来源：
 
-1. Open `/projects/mdtodo` on the YAML-selected origin.
-2. Save the source with its declared `hwpodId`, `nodeId`, workspace root and relative MDTODO root.
-3. Probe the source and require a structured ready result.
-4. Reindex and record document/task counts plus fingerprint, not raw Markdown.
-5. Confirm direct `.md` files and their tasks are visible.
-6. When requested, launch Workbench from one task and verify the resulting task/session link.
+1. 在 YAML 选中的入口打开 `/projects/mdtodo`。
+2. 用声明的 `hwpodId`、`nodeId`、工作区根和相对 MDTODO 根保存来源。
+3. 探测来源，并要求结构化就绪结果。
+4. 重建索引，记录文档/任务数量和指纹，不记录 Markdown 正文。
+5. 确认直接 `.md` 文件及其任务可见。
+6. 用户要求时，从一个任务启动 Workbench，并验证生成的任务/会话关联。
 
-The equivalent API family is `/v1/project-management/mdtodo/*`; use the repo-owned web-probe commands when available. Never make direct filesystem reads the completion evidence.
+等价 API 族是 `/v1/project-management/mdtodo/*`；仓库存在 web-probe 命令时使用它们。直接文件系统读取永远不能作为完成证据。
 
-## Failure Classification
+## 失败分类
 
-| Code family | Meaning |
+| 错误族 | 含义 |
 | --- | --- |
-| node-offline | Python process absent or WebSocket not registered |
-| node-id-mismatch | plan targets a different node identity |
-| node-auth | credential missing/rejected |
-| workspace-policy | root absent, outside allowlist or containment failure |
-| capability-mismatch | node cannot execute the requested public operation |
-| workspace-op | bounded operation failed inside an allowed root |
-| source-probe | Project Management could not read/parse the source |
-| source-projection | reindex or DB projection failed after source read |
-| web-visibility | API state exists but HWLAB Web does not expose it correctly |
+| node-offline | Python 进程不存在或 WebSocket 未注册 |
+| node-id-mismatch | 计划指向不同节点身份 |
+| node-auth | 凭据缺失或被拒绝 |
+| workspace-policy | 根目录缺失、不在允许列表或包含性校验失败 |
+| capability-mismatch | 节点无法执行请求的公共操作 |
+| workspace-op | 允许根目录内的有界操作失败 |
+| source-probe | 项目管理无法读取/解析来源 |
+| source-projection | 来源读取后重建索引或数据库投影失败 |
+| web-visibility | API 状态存在，但 HWLAB Web 未正确展示 |
 
-Preserve requestId/traceId and node diagnostics for the failing layer. Fix the owning layer instead of adding SSH, direct filesystem, local mount or private API fallbacks.
+保留失败层的 requestId/traceId 和节点诊断。修复权威层，不得增加 SSH、直接文件系统、本地挂载或私有 API 兜底。

AGENTS.md

@@ -12,6 +12,7 @@ UniDesk 以主 server 为统一入口。本文件只做自动加载的顶级索
 - P0: `/root/unidesk` 主 worktree 固定停留在 `master`；未预期修改默认属于并行任务，禁止 reset/checkout/删除，非 `master` 开发、语义合并和 worktree 清理由 `docs/reference/devops-hygiene.md` 约束。
 - P0: Master server 禁止通用 Docker/Rust/Go/前端重型构建；执行面和受控例外见 `docs/reference/dev-environment.md`。
 - P0: `AGENTS.md` 硬上限 10 KiB，只保留损害预防规则和索引；文档修改先加载 `$docs-spec`，细则见 `docs/reference/agent-instruction-hygiene.md` 与 `docs/reference/docs-governance.md`。
+- P0: 仓库内文档、skill 与 Agent 指令的自然语言标题和正文统一使用中文；读取时发现非中文内容必须先翻译再继续，新写内容不得使用非中文自然语言。命令、路径、代码字段、协议名和上游原文引用可保留原文。
 - P0: NC01 UniDesk server/backend-core 只认 `config/unidesk-host-k8s.yaml` 选中的 k8s `unidesk` 运行面；禁止用 Compose 替代，healthy 后非明确要求不扰动。细则见 `docs/reference/nc01.md`。
 
 ## P0: 最新要求、可见性与验证

docs/reference/agent-instruction-hygiene.md

@@ -1,83 +1,81 @@
-# 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.
+本文是长期参考，用于保持自动加载的 Agent 指令文件精简、可导航且稳定。适用于本地和远端 `AGENTS.md`、`CLAUDE.md` 类别名，以及所有自动注入 Agent 上下文的仓库级指令文件。
 
-## Size Budget
+## 体积预算
 
-`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`.
+`AGENTS.md` 是索引，不是知识库。任何本地或远端 `AGENTS.md` 的硬上限均为 10 KiB，使用 `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`.
+`AGENTS.md` 已超过 10 KiB 时，不得继续追加详细规则。必须先拆分，再只向 `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` 会导致其超过 10 KiB 时，把新内容分流到 skill 或 `docs/reference/*.md`，并保持 `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` 触发 CLI 输出转储或上下文膨胀时，将其视为可见性缺陷和指令治理缺陷。正确修复是拆分文件，不是提高输出上限或要求 Agent 绕过转储读取。
 
-## What Belongs In AGENTS.md
+## AGENTS.md 应包含的内容
 
-Keep only always-needed routing information in `AGENTS.md`:
+`AGENTS.md` 只保留始终需要的路由信息：
 
-- 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.
+- 项目标识和真相源边界；
+- 防止直接损害的一行 P0 规则；
+- 各领域权威长期参考文档链接；
+- 常用工作流必须加载的 skill 名称；
+- Secret、破坏性命令、目标工作区和构建禁令的短警告。
 
-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`.
+不得放入长示例、命令记录、JSON 输出、issue 时间线、架构长文、provider 特定调试日志或一次性事故分析。
 
-## Where Overflow Content Goes
+## 超出内容的分流位置
 
-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.
+- 可复用工作流进入 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 评论或过程记录；进入长期参考前必须蒸馏。
 
-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.
+规则既能跨项目复用、又依赖 UniDesk 当前目录或服务时，把可复用流程放入 skill，把 UniDesk 特定路径、通道名和验收边界放入 `docs/reference/*.md`，并双向交叉引用。
 
-## Split Procedure
+## 拆分步骤
 
-When an agent sees a local or remote `AGENTS.md` over 10 KiB:
+Agent 发现本地或远端 `AGENTS.md` 超过 10 KiB 时：
 
-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.
+1. 识别正在修改或扩展的详细领域。
+2. 把详细内容移到权威 skill 或 `docs/reference/*.md`。
+3. 用一条简短索引和权威链接替换原详细章节。
+4. 在 `AGENTS.md` 保留 P0 损害预防警告，但压缩为一行路由规则。
+5. 不得把所有内容移入单个巨大溢出文档。临时迁移记录仅在立即指向各领域承接文档时可用。
+6. 用户未明确要求时，不为体积预算新增测试、保护代码或预检。默认控制方式是文档治理和简洁评审。
 
-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
+## 交叉引用要求
 
-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`.
+`AGENTS.md` 中指向外部的每条索引必须注明权威目标。优先使用 `docs/reference/hwlab.md` 等直接路径或 `$unidesk-cicd` 等 skill 名称。
 
-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.
+不得在 `AGENTS.md`、skill 和长期参考之间重复完整规则。`AGENTS.md` 可以摘要，参考文档拥有细节。两个参考文档冲突时，更新职责更具体的文档，并只保留一个权威版本。
 
-## Secrets And Output Hygiene
+## Secret 与输出治理
 
-Instruction files must not contain secrets, full API keys, full DSNs, base64 payloads, bearer tokens, SSH private keys or copy-pastable credentials.
+指令文件不得包含 Secret、完整 API key、完整 DSN、base64 载荷、bearer token、SSH 私钥或可直接复用的凭据。
 
-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.
+不得把大段 CLI 输出、OTel trace 转储、JSON 数组或浏览器记录粘贴进 `AGENTS.md`。大输出证明可复用规则时，只保留规则摘要，并链接到拥有完整结论的 issue 或参考文档。
 
-## Current UniDesk Routing Map
+## 当前 UniDesk 路由图
 
-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`.
+- 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`。