From 22f0a2c88497f2143f3a329e92cc7858047ab537 Mon Sep 17 00:00:00 2001 From: Codex Date: Fri, 10 Jul 2026 11:51:30 +0200 Subject: [PATCH 1/4] feat: add unidesk hwpod operations skill --- .agents/skills/unidesk-hwpod-ops/SKILL.md | 64 +++++++++++++++++++ .../unidesk-hwpod-ops/agents/openai.yaml | 4 ++ .../references/python-ui-node.md | 64 +++++++++++++++++++ .../references/workspace-mdtodo.md | 56 ++++++++++++++++ 4 files changed, 188 insertions(+) create mode 100644 .agents/skills/unidesk-hwpod-ops/SKILL.md create mode 100644 .agents/skills/unidesk-hwpod-ops/agents/openai.yaml create mode 100644 .agents/skills/unidesk-hwpod-ops/references/python-ui-node.md create mode 100644 .agents/skills/unidesk-hwpod-ops/references/workspace-mdtodo.md diff --git a/.agents/skills/unidesk-hwpod-ops/SKILL.md b/.agents/skills/unidesk-hwpod-ops/SKILL.md new file mode 100644 index 00000000..55eb5bb0 --- /dev/null +++ b/.agents/skills/unidesk-hwpod-ops/SKILL.md @@ -0,0 +1,64 @@ +--- +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 读取时使用。 +--- + +# UniDesk HWPOD Ops + +以当前 HWLAB v0.3 Python UI node 为默认运维对象。旧 `$hwpod-ops` 中的 TypeScript/Bun `serve|connect` 只用于历史漂移调查，不作为新节点完成态。 + +## P0 Boundaries + +- 当前 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 与状态证据。 +- 调查可只读访问现场。安装、注册、更新、停止旧 runner 或改 MDTODO source 属于运行面变更，必须先加载 `$dad-dev`；部署/rollout 同时加载 `$unidesk-cicd`，YAML 变更同时加载 `$unidesk-ymalops`。 +- 远端操作走 `$unidesk-trans`。普通 `trans` 保持短连接；GUI 进程不得作为透传子进程长挂。 +- Python node 当前若没有 workspace allowlist/规范化、注册认证或 capability parity，不得把“WebSocket 已连接”报告为 HWPOD/MDTODO 可用。 + +## Read-Only Triage + +```bash +bun scripts/cli.ts cicd status --node NC01 +bun scripts/cli.ts hwlab nodes control-plane source-workspace status --node NC01 --lane v03 + +trans :win ps '[ordered]@{home=$HOME; python=(python --version 2>&1 | Out-String).Trim(); config=(Test-Path (Join-Path $HOME ".hwlab\\config.json")); log=(Test-Path (Join-Path $HOME ".hwlab\\logs\\hwlab-node.log"))} | ConvertTo-Json -Compress' +trans :win ps 'Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -match "hwlab-node|hwpod-node" } | Select-Object ProcessId,Name,CommandLine | ConvertTo-Json -Compress' +trans :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. + +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. + +## 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. Render/validate config before touching Windows. Keep nodeId, URL, workspace and retry/update settings out of generated helper code. +4. Install or update the published Python artifact by verified SHA. Resolve the target interactive user's Windows `python.exe`, record its path/version, and use it to launch the file in that Windows session so GUI and tray are visible; use a login-start mechanism only when declared by YAML. +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. + +## Stop Conditions + +- Stop before mutation if the selected lane/source authority is unclear or stale. +- 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. + +## 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). diff --git a/.agents/skills/unidesk-hwpod-ops/agents/openai.yaml b/.agents/skills/unidesk-hwpod-ops/agents/openai.yaml new file mode 100644 index 00000000..a68a1df1 --- /dev/null +++ b/.agents/skills/unidesk-hwpod-ops/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "UniDesk HWPOD 运维" + short_description: "运维 Python UI HWPOD 节点、连接、工作区与 MDTODO" + default_prompt: "使用 $unidesk-hwpod-ops 调查并运维指定 HWLAB Python UI HWPOD 节点。" diff --git a/.agents/skills/unidesk-hwpod-ops/references/python-ui-node.md b/.agents/skills/unidesk-hwpod-ops/references/python-ui-node.md new file mode 100644 index 00000000..8ed4c494 --- /dev/null +++ b/.agents/skills/unidesk-hwpod-ops/references/python-ui-node.md @@ -0,0 +1,64 @@ +# Python UI Node + +## 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¤t=`. +- Artifact: `GET /v1/hwlab-node/download/hwlab-node.py`; verify the metadata SHA before replacement. +- Node transport: active outbound `wss:///v1/hwpod-node/ws` registration and heartbeat. +- Node-ops contract: `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. + +## Desktop Configuration + +The current application exposes `serverUrl`, `nodeId`, `autoConnect`, update settings and logging settings. It intentionally accepts no CLI arguments or `HWLAB_*` environment variables. + +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. + +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. + +## Status Evidence + +Collect bounded, redacted facts: + +```powershell +$root = Join-Path $HOME ".hwlab" +[ordered]@{ + home = $HOME + configExists = Test-Path (Join-Path $root "config.json") + stateExists = Test-Path (Join-Path $root "state.json") + logExists = Test-Path (Join-Path $root "logs\hwlab-node.log") + interactiveShell = (Get-Process explorer -ErrorAction SilentlyContinue | Measure-Object).Count +} | 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. + +## 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. + +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. diff --git a/.agents/skills/unidesk-hwpod-ops/references/workspace-mdtodo.md b/.agents/skills/unidesk-hwpod-ops/references/workspace-mdtodo.md new file mode 100644 index 00000000..f587415f --- /dev/null +++ b/.agents/skills/unidesk-hwpod-ops/references/workspace-mdtodo.md @@ -0,0 +1,56 @@ +# Workspace And MDTODO + +## Required Declarations + +Add a node/workspace only through owning YAML/configRef. Keep these concepts distinct: + +| 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 | + +For a Windows Python UI node, `workspaceRootRef` must use the Windows path visible to that process. A WSL `/mnt//...` route may prove the same files exist, but it is not the Python node's path authority. + +## 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. Ensure the Python node enforces declared workspace roots with canonical-path containment; reject absolute paths outside them, `..`, symlink/junction escape and undeclared roots. +5. Configure registration authentication from SecretRef without printing credentials. +6. Install the SHA-verified Python artifact and launch in the selected interactive Windows user session. +7. Prove cloud registration and expected capabilities. +8. Run `node.inventory` against the declared root, then bounded `workspace.ls`/`workspace.cat` under the MDTODO root. +9. Save/probe/reindex the Project Management source and verify files/tasks in HWLAB Web. + +## MDTODO Acceptance + +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. + +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. + +## 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 | + +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. From 9bad83454e9546f33a9dd2be98f2a5fe9d20fd15 Mon Sep 17 00:00:00 2001 From: Codex Date: Fri, 10 Jul 2026 11:54:23 +0200 Subject: [PATCH 2/4] docs: require yaml first hwpod deployment --- .agents/skills/unidesk-hwpod-ops/SKILL.md | 6 ++++-- .../unidesk-hwpod-ops/references/python-ui-node.md | 14 ++++++++++++++ .../references/workspace-mdtodo.md | 13 +++++++------ 3 files changed, 25 insertions(+), 8 deletions(-) diff --git a/.agents/skills/unidesk-hwpod-ops/SKILL.md b/.agents/skills/unidesk-hwpod-ops/SKILL.md index 55eb5bb0..5ef8c735 100644 --- a/.agents/skills/unidesk-hwpod-ops/SKILL.md +++ b/.agents/skills/unidesk-hwpod-ops/SKILL.md @@ -15,6 +15,7 @@ description: UniDesk HWLAB HWPOD 节点运维技能，覆盖 Windows 单文件 P - 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 可用。 @@ -44,8 +45,8 @@ Read [references/python-ui-node.md](references/python-ui-node.md) for the curren 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. Render/validate config before touching Windows. Keep nodeId, URL, workspace and retry/update settings out of generated helper code. -4. Install or update the published Python artifact by verified SHA. Resolve the target interactive user's Windows `python.exe`, record its path/version, and use it to launch the file in that Windows session so GUI and tray are visible; use a login-start mechanism only when declared by YAML. +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. @@ -53,6 +54,7 @@ Read [references/python-ui-node.md](references/python-ui-node.md) for the curren ## 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. 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 8ed4c494..8c7d136e 100644 --- a/.agents/skills/unidesk-hwpod-ops/references/python-ui-node.md +++ b/.agents/skills/unidesk-hwpod-ops/references/python-ui-node.md @@ -46,6 +46,20 @@ $root = Join-Path $HOME ".hwlab" 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. +## 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: + +- 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". + +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. + ## Known Gaps To Check Never assume the newest published file has solved these items; inspect the selected source/version: diff --git a/.agents/skills/unidesk-hwpod-ops/references/workspace-mdtodo.md b/.agents/skills/unidesk-hwpod-ops/references/workspace-mdtodo.md index f587415f..812a464e 100644 --- a/.agents/skills/unidesk-hwpod-ops/references/workspace-mdtodo.md +++ b/.agents/skills/unidesk-hwpod-ops/references/workspace-mdtodo.md @@ -19,12 +19,13 @@ For a Windows Python UI node, `workspaceRootRef` must use the Windows path visib 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. Ensure the Python node enforces declared workspace roots with canonical-path containment; reject absolute paths outside them, `..`, symlink/junction escape and undeclared roots. -5. Configure registration authentication from SecretRef without printing credentials. -6. Install the SHA-verified Python artifact and launch in the selected interactive Windows user session. -7. Prove cloud registration and expected capabilities. -8. Run `node.inventory` against the declared root, then bounded `workspace.ls`/`workspace.cat` under the MDTODO root. -9. Save/probe/reindex the Project Management source and verify files/tasks in HWLAB Web. +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. ## MDTODO Acceptance From 7276278fe502d2149a8450e4b539ac06562deb47 Mon Sep 17 00:00:00 2001 From: Codex Date: Fri, 10 Jul 2026 11:59:06 +0200 Subject: [PATCH 3/4] =?UTF-8?q?docs:=20=E5=9B=BA=E5=8C=96=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E5=92=8C=E6=8A=80=E8=83=BD=E4=B8=AD=E6=96=87=E5=86=99?= =?UTF-8?q?=E4=BD=9C=E8=A7=84=E5=88=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agents/skills/unidesk-hwpod-ops/SKILL.md | 80 ++++++------- .../references/python-ui-node.md | 92 +++++++------- .../references/workspace-mdtodo.md | 84 ++++++------- AGENTS.md | 1 + docs/reference/agent-instruction-hygiene.md | 112 +++++++++--------- 5 files changed, 184 insertions(+), 185 deletions(-) diff --git a/.agents/skills/unidesk-hwpod-ops/SKILL.md b/.agents/skills/unidesk-hwpod-ops/SKILL.md index 5ef8c735..b77745c0 100644 --- a/.agents/skills/unidesk-hwpod-ops/SKILL.md +++ b/.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 :win ps 'Get-CimInstance Win32_Process | Where-Object { $_.Comma trans :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)。 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 8c7d136e..645de4f8 100644 --- a/.agents/skills/unidesk-hwpod-ops/references/python-ui-node.md +++ b/.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¤t=`. -- Artifact: `GET /v1/hwlab-node/download/hwlab-node.py`; verify the metadata SHA before replacement. -- Node transport: active outbound `wss:///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¤t=`。 +- 发布文件：`GET /v1/hwlab-node/download/hwlab-node.py`；替换前校验元数据给出的 SHA。 +- 节点传输：主动出站连接 `wss:///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` 流程。 diff --git a/.agents/skills/unidesk-hwpod-ops/references/workspace-mdtodo.md b/.agents/skills/unidesk-hwpod-ops/references/workspace-mdtodo.md index 812a464e..cd3e9cba 100644 --- a/.agents/skills/unidesk-hwpod-ops/references/workspace-mdtodo.md +++ b/.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//...` route may prove the same files exist, but it is not the Python node's path authority. +Windows Python 图形节点的 `workspaceRootRef` 必须使用该进程可见的 Windows 路径。WSL `/mnt//...` 路由可以证明同一批文件存在，但不是 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 兜底。 diff --git a/AGENTS.md b/AGENTS.md index 5d4b3cac..07b49c5b 100644 --- a/AGENTS.md +++ b/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: 最新要求、可见性与验证 diff --git a/docs/reference/agent-instruction-hygiene.md b/docs/reference/agent-instruction-hygiene.md index 17f6fae8..f7041c9a 100644 --- a/docs/reference/agent-instruction-hygiene.md +++ b/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`。 From 44187be70d6a2526b8e6015e190943ed69a524cf Mon Sep 17 00:00:00 2001 From: Codex Date: Fri, 10 Jul 2026 12:21:13 +0200 Subject: [PATCH 4/4] =?UTF-8?q?docs:=20=E7=BB=9F=E4=B8=80=E4=BD=BF?= =?UTF-8?q?=E7=94=A8=E4=B8=AD=E6=96=87=E7=BB=93=E6=9E=84=E5=8C=96=E5=AD=90?= =?UTF-8?q?=E5=88=97=E8=A1=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agents/skills/unidesk-hwpod-ops/SKILL.md | 119 ++++++++++--- .../references/python-ui-node.md | 102 ++++++++--- .../references/workspace-mdtodo.md | 59 +++++-- AGENTS.md | 114 +++++++++--- docs/reference/agent-instruction-hygiene.md | 113 +++++++++--- docs/reference/docs-governance.md | 162 +++++++++++++++--- 6 files changed, 534 insertions(+), 135 deletions(-) diff --git a/.agents/skills/unidesk-hwpod-ops/SKILL.md b/.agents/skills/unidesk-hwpod-ops/SKILL.md index b77745c0..c274a3a2 100644 --- a/.agents/skills/unidesk-hwpod-ops/SKILL.md +++ b/.agents/skills/unidesk-hwpod-ops/SKILL.md @@ -1,24 +1,54 @@ --- name: unidesk-hwpod-ops -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 读取时使用。 +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 运维 -以当前 HWLAB v0.3 Python 图形节点为默认运维对象。旧 `$hwpod-ops` 中的 TypeScript/Bun `serve|connect` 只用于历史漂移调查，不作为新节点完成态。 +- 运维对象： + + - 默认对象：当前 HWLAB v0.3 Python 图形节点； + - 历史调查：旧 `$hwpod-ops` 中的 TypeScript/Bun `serve|connect`； + - 禁止事项：旧运行器不得作为新节点完成态。 ## P0 边界 -- 当前 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 只披露是否存在、指纹和脱敏摘要。 +- 当前 HWLAB 固定运行面由 UniDesk `config/hwlab-node-lanes.yaml` 选择： + - 先运行 `cicd status` 和 `source-workspace status`； + - 不得复用旧 G14/v0.2 地址。 +- Python 图形节点的来源： + - 权威源码是选中 HWLAB 源工作区的 `tools/hwlab-node.py`； + - 发布版本由选中入口的 `/v1/hwlab-node/update` 给出； + - 发布文件和 SHA 由 `/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`。 +- Windows Python 图形节点启动规则： + - 优先使用目标 Windows 交互用户可见的原生 `python.exe`； + - 不得用 WSL Python、SSH 辅助程序自带解释器、Bun 运行器或非交互 Windows 服务替代； + - 解释器路径/版本必须进入节点配置和状态证据。 +- HWPOD 节点部署必须采用 YAML-first + 仓库自带 CLI： + - 只支持权威 YAML 已声明且 `trans` 路由可解析、可访问的节点； + - CLI 可以在内部使用 `trans` 作为传输层； + - 操作者不得用手写 `trans`/PowerShell/cmd 完成安装、更新、配置或自启动； + - 受控 CLI 缺失时先实现 CLI，不把手工部署当临时完成态。 +- 调查可只读访问现场；发生以下变更时加载对应 skill： + - 安装、注册、更新、停止旧运行器或修改 MDTODO 来源：`$dad-dev`； + - 部署/发布：同时加载 `$unidesk-cicd`； + - YAML 变更：同时加载 `$unidesk-ymalops`。 - 远端操作走 `$unidesk-trans`。普通 `trans` 保持短连接；图形进程不得作为透传子进程长挂。 -- Python 节点当前若没有工作区允许列表/规范化、注册认证或能力对齐，不得把“WebSocket 已连接”报告为 HWPOD/MDTODO 可用。 +- Python 节点可用性： + - 必须具备工作区允许列表/规范化； + - 必须具备注册认证和能力对齐； + - 缺失任一项时，不得把“WebSocket 已连接”报告为 HWPOD/MDTODO 可用。 ## 只读调查 @@ -31,36 +61,73 @@ trans :win ps 'Get-CimInstance Win32_Process | Where-Object { $_.Comma trans :win ps 'Get-ScheduledTask -ErrorAction SilentlyContinue | Where-Object { $_.TaskName -match "HWLAB|HWPOD" } | Select-Object TaskName,State | ConvertTo-Json -Compress' ``` -分别判断以下状态： +- 状态分类： -- `desktop-ready`：Python/tkinter 和交互式 Windows 会话可用。 -- `process-ready`：只有一个预期的 Python 图形进程存活，不存在冲突的 Bun 执行权威。 -- `registered`：云端注册表已确认预期 nodeId。 -- `workspace-ready`：`node.inventory` 和有界工作区读取指向 YAML 选中的根目录。 -- `mdtodo-ready`：项目管理来源通过公共 HWPOD 工作区操作完成保存、探测和重建索引。 + - `desktop-ready`：Python/tkinter 和交互式 Windows 会话可用。 + - `process-ready`：只有一个预期的 Python 图形进程存活，不存在冲突的 Bun 执行权威。 + - `registered`：云端注册表已确认预期 nodeId。 + - `workspace-ready`：`node.inventory` 和有界工作区读取指向 YAML 选中的根目录。 + - `mdtodo-ready`：项目管理来源通过公共 HWPOD 工作区操作完成保存、探测和重建索引。 -调查当前应用合同、更新流程和已知缺口时读 [references/python-ui-node.md](references/python-ui-node.md)。新增节点、绑定工作区或验收 HWLAB Web MDTODO 时读 [references/workspace-mdtodo.md](references/workspace-mdtodo.md)。 +- 当前应用合同、更新流程和已知缺口： + - 读 [references/python-ui-node.md](references/python-ui-node.md)。 +- 新增节点、绑定工作区或验收 HWLAB Web MDTODO： + - 读 [references/workspace-mdtodo.md](references/workspace-mdtodo.md)。 ## 变更流程 -1. 观察选中的 HWLAB 节点/通道、公共入口、Python 发布元数据、Windows 用户/会话、当前节点进程、任务/启动项、配置是否存在和旧运行器。 +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 正文或凭据。 +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 正文或凭据。 ## 停止条件 - 选中的通道/源权威不清晰或过期时，在变更前停止。 -- 目标未进入权威 YAML、没有可解析且可达的 `trans` 路由，或仓库自带规划/状态/应用 CLI 缺失时，在部署前停止。 +- 部署前停止条件： + - 目标未进入权威 YAML； + - 没有可解析且可达的 `trans` 路由； + - 仓库自带规划/状态/应用 CLI 缺失。 - 现有进程控制相同 nodeId/资源时，在启动第二个运行器前停止。 - 工作区未实施包含性约束或来源可能逃逸声明根目录时，在 MDTODO 写入/重建索引前停止。 -- 节点不匹配、认证失败、工作区缺失、能力不匹配、旧运行器漂移和来源投影失败必须作为不同阻塞项处理。 +- 必须区分以下阻塞项： + - 节点不匹配和认证失败； + - 工作区缺失和能力不匹配； + - 旧运行器漂移； + - 来源投影失败。 - 不得只凭进程健康关闭 HWPOD issue；必须使用用户原始的 HWLAB Web/CaseRun/MDTODO 入口。 ## 参考文档 -- Python 图形节点合同、本地文件、更新端点和漂移：[references/python-ui-node.md](references/python-ui-node.md)。 +- Python 图形节点合同、本地文件、更新端点和漂移： + - [references/python-ui-node.md](references/python-ui-node.md)。 - 节点接入、工作区绑定和 MDTODO 验收：[references/workspace-mdtodo.md](references/workspace-mdtodo.md)。 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 645de4f8..c78ef557 100644 --- a/.agents/skills/unidesk-hwpod-ops/references/python-ui-node.md +++ b/.agents/skills/unidesk-hwpod-ops/references/python-ui-node.md @@ -3,7 +3,9 @@ ## 当前权威来源 - HWLAB 源码：YAML 选中的 v0.3 源工作区内 `tools/hwlab-node.py`。 -- 应用形态：单文件 Python/tkinter 图形应用，包含 Windows 托盘、自动重连、日志轮转和自更新。 +- 应用形态：单文件 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¤t=`。 @@ -15,23 +17,33 @@ ## 桌面配置 -当前应用暴露 `serverUrl`、`nodeId`、`autoConnect`、更新设置和日志设置。应用有意不接受 CLI 参数或 `HWLAB_*` 环境变量。 +- 当前应用配置： + - 暴露 `serverUrl`、`nodeId` 和 `autoConnect`； + - 暴露更新设置和日志设置； + - 有意不接受 CLI 参数或 `HWLAB_*` 环境变量。 -必须使用目标 Windows 用户的原生解释器运行应用。从拥有 `%USERPROFILE%\.hwlab` 和托盘的同一交互登录上下文解析 `python.exe`，再把选中的解释器路径写入权威节点配置/启动声明。`python --version`、`Get-Command python` 和 tkinter 导入属于发现证据；WSL `/usr/bin/python`、SSH 侧辅助解释器或隐藏服务账号不能作为运行时。 +- Windows 原生解释器规则： -本地配置只表达操作者偏好。平台声明仍然拥有： + - 从拥有 `%USERPROFILE%\.hwlab` 和托盘的同一交互登录上下文解析 `python.exe`； + - 把选中的解释器路径写入权威节点配置/启动声明； + - 使用 `python --version`、`Get-Command python` 和 tkinter 导入作为发现证据； + - WSL `/usr/bin/python`、SSH 侧辅助解释器或隐藏服务账号不能作为运行时。 -- 节点/通道和唯一 nodeId； -- HWPOD 资源与能力绑定； -- 允许的工作区根目录； -- WebSocket/认证 Secret 来源引用； -- 受管登录/启动策略； -- Windows 解释器路径/版本和交互用户； -- 项目管理 MDTODO 来源。 +- 平台声明拥有： + + - 节点/通道和唯一 nodeId； + - HWPOD 资源与能力绑定； + - 允许的工作区根目录； + - WebSocket/认证 Secret 来源引用； + - 受管登录/启动策略； + - Windows 解释器路径/版本和交互用户； + - 项目管理 MDTODO 来源。 +- 本地配置边界： + - 只表达操作者偏好。 ## 状态证据 -只采集有界、脱敏的事实： +### 状态采集命令 ```powershell $root = Join-Path $HOME ".hwlab" @@ -44,25 +56,52 @@ $root = Join-Path $HOME ".hwlab" } | ConvertTo-Json -Compress ``` -只在需要时读取配置字段，并对未来可能出现的 Secret 字段脱敏。注册/运行证据优先使用云端 `node.health`、`node.version`、`node.inventory` 和 `node.diagnostics` 结果。 +- 配置和运行证据规则： + + - 只在需要时读取配置字段； + - 对未来可能出现的 Secret 字段脱敏； + - 注册/运行证据优先使用云端结果： + - `node.health` 和 `node.version`； + - `node.inventory` 和 `node.diagnostics`。 ## 受控部署 -部署属于 YAML-first UniDesk CLI 命令族，不属于操作者手工步骤。命令族必须提供有界的规划、状态和显式确认应用动作，并满足： +- 部署入口： -- 从权威 YAML/配置引用解析节点/通道、Windows 路由、交互用户、pythonPath、运行目录、文件/更新入口、nodeId、SecretRefs、允许的工作区根和登录自启动策略； -- 拒绝没有可解析且可达 `trans` 路由的目标； -- 仅在 CLI 传输适配器内部使用 `trans`； -- 写入前校验下载文件的 SHA； -- 保证应用幂等，并报告写入文件指纹、配置指纹、解释器版本、启动注册、进程/注册表状态和脱敏阻塞项； -- 避免把图形应用作为短 SSH/trans 请求的子进程启动； -- 保持交互式 Windows 用户会话，使界面/托盘可见，并区分“已安装”和“界面可见且已注册”。 + - 必须属于 YAML-first UniDesk CLI 命令族； + - 不得由操作者手工拼接步骤； + - 命令族必须提供有界的规划、状态和显式确认应用动作； + - 命令族必须满足下列要求。 -命令族不存在时只允许只读发现。人工下载、远端 PowerShell 写文件、临时计划任务和直接启动进程只属于诊断，不是部署证据。 +- 命令族要求： + - 从权威 YAML/配置引用解析： + - 节点/通道和 Windows 路由； + - 交互用户、pythonPath 和运行目录； + - 文件/更新入口、nodeId 和 SecretRefs； + - 允许的工作区根和登录自启动策略； + - 拒绝没有可解析且可达 `trans` 路由的目标； + - 仅在 CLI 传输适配器内部使用 `trans`； + - 写入前校验下载文件的 SHA； + - 保证应用幂等，并报告： + - 写入文件指纹和配置指纹； + - 解释器版本和启动注册； + - 进程/注册表状态和脱敏阻塞项； + - 避免把图形应用作为短 SSH/trans 请求的子进程启动； + - 保持交互式 Windows 用户会话： + - 确保界面/托盘可见； + - 区分“已安装”和“界面可见且已注册”。 + +- 命令族不存在时： + + - 只允许只读发现； + - 人工下载只属于诊断； + - 远端 PowerShell 写文件只属于诊断； + - 临时计划任务和直接启动进程只属于诊断； + - 上述操作都不是部署证据。 ## 每次必须检查的缺口 -不要假设最新发布文件已经解决以下事项；必须检查选中的源码/版本： +- 必须检查选中的源码/版本，不得假设最新发布文件已经解决以下事项： - 默认 nodeId 可能仍然绑定 D601。 - 工作区操作可能接受请求提供的绝对路径，但没有配置允许列表或包含性检查。 @@ -71,8 +110,21 @@ $root = Join-Path $HOME ".hwlab" - 图形窗口关闭到托盘不等于登录持久化；非交互会话中的计划任务可能隐藏界面/托盘。 - 另一个任务、启动项或运行目录中可能仍有旧 Bun 运行器活动。 -每个缺口必须分别暴露，不得增加本地兜底路径掩盖问题。 +- 缺口处置： + - 每个缺口必须分别暴露； + - 不得增加本地兜底路径掩盖问题。 ## 旧运行器漂移 -旧运行器证据包括 `bun.exe tools\hwpod-node.ts connect`、旧 IP/端口云端地址、`hwpod-node-runtime` 和旧计划任务名。停止任何进程前，先比较 nodeId、云端地址、资源绑定和活动硬件任务。可能中断硬件操作的变更必须有明确维护窗口，并遵循 `$dad-dev` 流程。 +- 旧运行器证据： + + - `bun.exe tools\hwpod-node.ts connect`； + - 旧 IP/端口云端地址； + - `hwpod-node-runtime`； + - 旧计划任务名。 + +- 停止旧运行器前： + + - 比较 nodeId、云端地址、资源绑定和活动硬件任务； + - 可能中断硬件操作的变更必须有明确维护窗口； + - 变更必须遵循 `$dad-dev` 流程。 diff --git a/.agents/skills/unidesk-hwpod-ops/references/workspace-mdtodo.md b/.agents/skills/unidesk-hwpod-ops/references/workspace-mdtodo.md index cd3e9cba..cad0366f 100644 --- a/.agents/skills/unidesk-hwpod-ops/references/workspace-mdtodo.md +++ b/.agents/skills/unidesk-hwpod-ops/references/workspace-mdtodo.md @@ -2,17 +2,34 @@ ## 必需声明 -只能通过权威 YAML/配置引用新增节点/工作区。以下概念必须分离： +- 新增节点/工作区规则： + - 只能通过权威 YAML/配置引用新增； + - 以下概念必须分离。 +- 桌面节点： + - HWLAB 节点/通道； + - 唯一 nodeId； + - Python 文件来源； + - Windows pythonPath/版本； + - 受管交互用户/启动策略。 +- HWPOD 资源： + - hwpodId/resourceId； + - nodeId； + - 能力； + - workspaceRootRef。 +- 工作区策略： + - 允许的 Windows 根目录； + - 包含性/规范化策略； + - 读写能力。 +- MDTODO 来源： + - sourceId 和 projectId； + - hwpodId 和 nodeId； + - workspaceRootRef 和 mdtodoRootRef。 +- 服务路由： + - 公共/服务节点操作配置引用； + - Secret 来源引用。 -| 概念 | 必需事实 | -| --- | --- | -| 桌面节点 | HWLAB 节点/通道、唯一 nodeId、Python 文件来源、Windows pythonPath/版本、受管交互用户/启动策略 | -| HWPOD 资源 | hwpodId/resourceId、nodeId、能力、workspaceRootRef | -| 工作区策略 | 允许的 Windows 根目录、包含性/规范化策略、读写能力 | -| MDTODO 来源 | sourceId、projectId、hwpodId、nodeId、workspaceRootRef、mdtodoRootRef | -| 服务路由 | 公共/服务节点操作配置引用和 Secret 来源引用 | - -Windows Python 图形节点的 `workspaceRootRef` 必须使用该进程可见的 Windows 路径。WSL `/mnt//...` 路由可以证明同一批文件存在，但不是 Python 节点的路径权威。 +Windows Python 图形节点的 `workspaceRootRef` 必须使用该进程可见的 Windows 路径。 +WSL `/mnt//...` 路由可以证明同一批文件存在，但不是 Python 节点的路径权威。 ## 接入顺序 @@ -20,17 +37,21 @@ Windows Python 图形节点的 `workspaceRootRef` 必须使用该进程可见的 2. 分配与 D601 和所有现有节点不同的 nodeId。 3. 增加桌面节点、HWPOD 资源/工作区策略和 MDTODO 来源的 YAML 声明。 4. 在节点配置中增加可解析的 `trans` Windows 路由，并通过受控 CLI 预检证明其可达。 -5. 确保 Python 节点对声明的工作区根实施规范路径包含性检查；拒绝根目录之外的绝对路径、`..`、符号链接/联接点逃逸和未声明根目录。 +5. 确保 Python 节点对声明的工作区根实施规范路径包含性检查；拒绝： + - 根目录之外的绝对路径； + - `..`； + - 符号链接/联接点逃逸； + - 未声明根目录。 6. 从 SecretRef 配置注册认证，不打印凭据。 -7. 使用仓库自带 YAML-first CLI 安装已校验 SHA 的 Python 文件，并应用选中的交互式 Windows 登录自启动策略。 +7. 使用仓库自带 YAML-first CLI： + - 安装已校验 SHA 的 Python 文件； + - 应用选中的交互式 Windows 登录自启动策略。 8. 证明云端注册和预期能力。 9. 对声明根目录运行 `node.inventory`，再对 MDTODO 根目录执行有界 `workspace.ls`/`workspace.cat`。 10. 保存/探测/重建项目管理来源索引，并在 HWLAB Web 验证文件/任务。 ## MDTODO 验收 -使用公共项目管理路径和选中的来源： - 1. 在 YAML 选中的入口打开 `/projects/mdtodo`。 2. 用声明的 `hwpodId`、`nodeId`、工作区根和相对 MDTODO 根保存来源。 3. 探测来源，并要求结构化就绪结果。 @@ -38,7 +59,10 @@ Windows Python 图形节点的 `workspaceRootRef` 必须使用该进程可见的 5. 确认直接 `.md` 文件及其任务可见。 6. 用户要求时，从一个任务启动 Workbench，并验证生成的任务/会话关联。 -等价 API 族是 `/v1/project-management/mdtodo/*`；仓库存在 web-probe 命令时使用它们。直接文件系统读取永远不能作为完成证据。 +- 等价入口规则： + - API 族是 `/v1/project-management/mdtodo/*`； + - 仓库存在 web-probe 命令时使用它们； + - 直接文件系统读取永远不能作为完成证据。 ## 失败分类 @@ -54,4 +78,7 @@ Windows Python 图形节点的 `workspaceRootRef` 必须使用该进程可见的 | source-projection | 来源读取后重建索引或数据库投影失败 | | web-visibility | API 状态存在，但 HWLAB Web 未正确展示 | -保留失败层的 requestId/traceId 和节点诊断。修复权威层，不得增加 SSH、直接文件系统、本地挂载或私有 API 兜底。 +- 失败处理： + - 保留失败层的 requestId/traceId 和节点诊断； + - 修复权威层； + - 不得增加 SSH、直接文件系统、本地挂载或私有 API 兜底。 diff --git a/AGENTS.md b/AGENTS.md index 07b49c5b..1e4c9306 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,54 +1,122 @@ # UniDesk Agent Index -UniDesk 以主 server 为统一入口。本文件只做自动加载的顶级索引；长期规则、流程和判定标准必须放到 skill 或 `docs/reference/*.md`。 +- UniDesk 顶级入口： + + - 主 server 是统一入口； + - 本文件只做自动加载的顶级索引； + - 长期规则、流程和判定标准必须放到 skill 或 `docs/reference/*.md`。 ## P0: 主 worktree 同步提交第一原则 -- P0: 发现固定主/目标 worktree 落后 remote 时，必须立刻先 `git stash push -u` 保存脏改（如有，含 untracked），再 `git pull --ff-only` 快进到最新 remote，然后 `git stash apply` 并按语义合并；主工作区恢复出的并行改动必须先直接提交，再继续后续任务；禁止用 reset、drop 或覆盖式 checkout 丢弃并行改动。 +- P0: 固定主/目标 worktree 落后 remote 时，必须按顺序处理： + - 用 `git stash push -u` 保存全部脏改，包括 untracked； + - 用 `git pull --ff-only` 快进到最新 remote； + - 用 `git stash apply` 恢复并按语义合并； + - 先直接提交主工作区恢复出的并行改动，再继续后续任务； + - 禁止用 reset、drop 或覆盖式 checkout 丢弃并行改动。 ## P0: 损害预防与文档治理 -- P0: 源码/CLI 超过 3000 行必须按职责拆到 2000 行以下；大段脚本放入 `.sh`/`.mjs`/`.py` 等原生文件。细则见 `docs/reference/devops-hygiene.md`。 -- 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: 源码/CLI 体积治理： + - 超过 3000 行必须按职责拆到 2000 行以下； + - 大段脚本放入 `.sh`/`.mjs`/`.py` 等原生文件； + - 细则见 `docs/reference/devops-hygiene.md`。 +- 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: Agent 指令体积规则： + - `AGENTS.md` 硬上限 10 KiB，只保留损害预防规则和索引； + - 文档修改先加载 `$docs-spec`； + - 细则见 `docs/reference/agent-instruction-hygiene.md` 与 `docs/reference/docs-governance.md`。 +- P0: 文档、skill 与 Agent 指令写作规则： + - 自然语言统一使用中文； + - 发现非中文先翻译； + - 过长单行随见随拆，且必须拆成结构化子列表，禁止自然换行； + - 命令、路径、代码字段、协议名和上游原文引用可保留原文； + - 细则见 `$docs-spec`。 +- P0: NC01 UniDesk server/backend-core 运行面规则： + - 只认 `config/unidesk-host-k8s.yaml` 选中的 k8s `unidesk` 运行面； + - 禁止用 Compose 替代； + - healthy 后非明确要求不扰动； + - 细则见 `docs/reference/nc01.md`。 ## P0: 最新要求、可见性与验证 -- P0: 用户最新明确要求优先于旧测试、旧门禁、旧预检、旧断言和旧 guard；阻碍最新目标的旧入口应删除，不做兼容保留。 -- P0: 缺失的已声明验证依赖按仓库包管理器和锁文件安装后继续；状态、耗时、失败或关键证据不可见时先修可见性。细则见 `docs/reference/devops-hygiene.md` 与 `docs/reference/observability.md`。 -- P0: CLI 改动、轻量语法验证和 compact text/显式 JSON 输出契约统一遵循 `docs/reference/cli.md`；默认不新增测试或运行裸 `tsc`。 +- P0: 用户最新明确要求优先于旧测试、旧门禁、旧预检、旧断言和旧 guard： + - 阻碍最新目标的旧入口应删除； + - 不做兼容保留。 +- P0: 验证依赖与可见性： + - 缺失的已声明验证依赖按仓库包管理器和锁文件安装后继续； + - 状态、耗时、失败或关键证据不可见时先修可见性； + - 细则见 `docs/reference/devops-hygiene.md` 与 `docs/reference/observability.md`。 +- P0: CLI 改动规则： + - 轻量语法验证和 compact text/显式 JSON 输出契约统一遵循 `docs/reference/cli.md`； + - 默认不新增测试； + - 默认不运行裸 `tsc`。 ## P0: 配置、Secret 与 YAML-first -- P0: UniDesk 可调运维事实以 owning YAML 为唯一真相，代码只校验/渲染，变更走受控 CLI；细则见 `docs/reference/yaml-first-ops.md`、`docs/reference/platform-infra.md` 和 `$unidesk-ymalops`。 -- P0: Secret 仅由 YAML `sourceRef`/`targetKey` 和受控 CLI 下发；禁止从运行面反解，输出只披露对象/key、presence、fingerprint 与摘要。 +- P0: UniDesk 可调运维事实规则： + - owning YAML 是唯一真相； + - 代码只负责校验/渲染； + - 变更走受控 CLI； + - 细则见 `docs/reference/yaml-first-ops.md`、`docs/reference/platform-infra.md` 和 `$unidesk-ymalops`。 +- P0: Secret 规则： + - 仅由 YAML `sourceRef`/`targetKey` 和受控 CLI 下发； + - 禁止从运行面反解； + - 输出只披露对象/key、presence、fingerprint 与摘要。 - P0: `hyueapi.com` / `.hyueapi.com` 必须保留在 `NO_PROXY` / `no_proxy`。 ## P0: 受控入口与技能路由 -- P0: 跨 host/lane 现场修复加载 `$dad-dev`，完成真实运行面探测、最小验证、持久化和原入口复测。 -- P0: CI/CD、GitOps、rollout、PipelineRun、Argo、git-mirror 和 AgentRun 部署走 `$unidesk-cicd` 与受控 CLI；原生工具仅限有界诊断。 -- P0: GitHub issue/PR 正式读写走 `$unidesk-gh` / `bun scripts/cli.ts gh ...`，禁止原生 `gh`/手写 API；写入默认中文。 -- P0: 远端文本修改优先走 `$unidesk-trans` 的 `trans apply-patch`；route/cwd 见 `docs/reference/cli.md`。 -- P0: Web/Workbench/Playwright/web-probe 走 `$unidesk-webdev`；OTel/Tempo/trace 走 `$unidesk-otel`；Web 哨兵和周期巡检走 `$unidesk-monitor`。 -- P0: “离线调查”只分析既有 trace/artifact/源码，不新开探针或改运行面；边界见 `docs/reference/observability.md`。 +- P0: 跨 host/lane 现场修复加载 `$dad-dev`： + - 完成真实运行面探测； + - 完成最小验证、持久化和原入口复测。 +- P0: CI/CD、GitOps、rollout、PipelineRun、Argo、git-mirror 和 AgentRun 部署： + - 走 `$unidesk-cicd` 与受控 CLI； + - 原生工具仅限有界诊断。 +- P0: GitHub issue/PR 正式读写： + - 走 `$unidesk-gh` / `bun scripts/cli.ts gh ...`； + - 禁止原生 `gh`/手写 API； + - 写入默认中文。 +- P0: 远端文本修改： + - 优先走 `$unidesk-trans` 的 `trans apply-patch`； + - route/cwd 见 `docs/reference/cli.md`。 +- P0: 专项技能路由： + - Web/Workbench/Playwright/web-probe 走 `$unidesk-webdev`； + - OTel/Tempo/trace 走 `$unidesk-otel`； + - Web 哨兵和周期巡检走 `$unidesk-monitor`。 +- P0: “离线调查”： + - 只分析既有 trace/artifact/源码； + - 不新开探针或改运行面； + - 边界见 `docs/reference/observability.md`。 ## P0: 固定开发与运行面 -- P0: HWLAB 固定使用 NC01/v03，AgentRun 固定使用 NC01/nc01-v02；workspace、route、配置真相、CI/CD 和原入口验收分别见 `docs/reference/hwlab.md` 与 `docs/reference/agentrun.md`。 +- P0: 固定运行面： + - HWLAB 固定使用 NC01/v03； + - AgentRun 固定使用 NC01/nc01-v02； + - HWLAB 的 workspace、route、配置真相、CI/CD 和原入口验收见 `docs/reference/hwlab.md`； + - AgentRun 对应规则见 `docs/reference/agentrun.md`。 - P0: D601 UniDesk workspace、任务 worktree 和 Master 构建边界见 `docs/reference/dev-environment.md`。 -- P0: 控之星、CONSTAR、71-FILTER、71-FREQ、PLC 项目及 PLC 控制器相关任务的固定工作区为 `G14-WSL:win/d/Work/CONSTAR_workspace`（Windows 路径 `D:\Work\CONSTAR_workspace`）。 -- P0: HWLAB 凭据脱敏和 issue 关闭遵循 `docs/reference/hwlab.md`；关闭前必须在选中 node/lane 走原入口真实验证，源码、PR 或构建通过不能替代。 +- P0: 控之星、CONSTAR、71-FILTER、71-FREQ、PLC 项目及 PLC 控制器相关任务的固定工作区： + - 透传路由：`G14-WSL:win/d/Work/CONSTAR_workspace`； + - Windows 路径：`D:\Work\CONSTAR_workspace`。 +- P0: HWLAB 凭据脱敏和 issue 关闭遵循 `docs/reference/hwlab.md`： + - 关闭前必须在选中 node/lane 走原入口真实验证； + - 源码、PR 或构建通过不能替代原入口验证。 ## P0: 长期参考入口 - CLI 与 route: `docs/reference/cli.md`。 - 文档治理与过程蒸馏: `docs/reference/docs-governance.md`。 - Agent 指令体积与分流: `docs/reference/agent-instruction-hygiene.md`。 -- DevOps hygiene、source truth、worktree 稳定本地状态、语义合并与清理: `docs/reference/devops-hygiene.md`。 +- DevOps hygiene 与 source truth：`docs/reference/devops-hygiene.md`。 + - 同一文档也负责 worktree 稳定本地状态、语义合并与清理。 - 开发环境和 D601/Master 边界: `docs/reference/dev-environment.md`。 - 主 server Codex profiles/resume: `docs/reference/master-server-ops.md`。 - HWLAB: `docs/reference/hwlab.md`。 diff --git a/docs/reference/agent-instruction-hygiene.md b/docs/reference/agent-instruction-hygiene.md index f7041c9a..61188a94 100644 --- a/docs/reference/agent-instruction-hygiene.md +++ b/docs/reference/agent-instruction-hygiene.md @@ -1,16 +1,37 @@ # Agent 指令治理 -本文是长期参考，用于保持自动加载的 Agent 指令文件精简、可导航且稳定。适用于本地和远端 `AGENTS.md`、`CLAUDE.md` 类别名，以及所有自动注入 Agent 上下文的仓库级指令文件。 +- 本文范围： + + - 目标：保持自动加载的 Agent 指令文件精简、可导航且稳定； + - 适用对象：本地和远端 `AGENTS.md`、`CLAUDE.md` 类别名； + - 扩展范围：所有自动注入 Agent 上下文的仓库级指令文件。 ## 体积预算 -`AGENTS.md` 是索引，不是知识库。任何本地或远端 `AGENTS.md` 的硬上限均为 10 KiB，使用 `wc -c AGENTS.md` 按字节计量。 +- 体积定义： -`AGENTS.md` 已超过 10 KiB 时，不得继续追加详细规则。必须先拆分，再只向 `AGENTS.md` 回填一行索引。 + - `AGENTS.md` 是索引，不是知识库； + - 本地或远端 `AGENTS.md` 的硬上限均为 10 KiB； + - 使用 `wc -c AGENTS.md` 按字节计量。 -修改 `AGENTS.md` 会导致其超过 10 KiB 时，把新内容分流到 skill 或 `docs/reference/*.md`，并保持 `AGENTS.md` 为短索引。 +`AGENTS.md` 已超过 10 KiB 时： -加载或输出 `AGENTS.md` 触发 CLI 输出转储或上下文膨胀时，将其视为可见性缺陷和指令治理缺陷。正确修复是拆分文件，不是提高输出上限或要求 Agent 绕过转储读取。 +- 不得继续追加详细规则； +- 必须先拆分； +- 只向 `AGENTS.md` 回填一行索引。 + +- 修改会导致 `AGENTS.md` 超过 10 KiB 时： + + - 把新内容分流到 skill 或 `docs/reference/*.md`； + - 保持 `AGENTS.md` 为短索引。 + +- 加载或输出 `AGENTS.md` 触发 CLI 输出转储或上下文膨胀时： + + - 将其视为可见性缺陷； + - 将其视为指令治理缺陷； + - 通过拆分文件修复； + - 不得提高输出上限； + - 不得要求 Agent 绕过转储读取。 ## AGENTS.md 应包含的内容 @@ -22,47 +43,89 @@ - 常用工作流必须加载的 skill 名称； - Secret、破坏性命令、目标工作区和构建禁令的短警告。 -不得放入长示例、命令记录、JSON 输出、issue 时间线、架构长文、provider 特定调试日志或一次性事故分析。 +- 禁止内容： + + - 长示例、命令记录或 JSON 输出； + - issue 时间线或架构长文； + - provider 特定调试日志； + - 一次性事故分析。 ## 超出内容的分流位置 -拆分 `AGENTS.md` 时按以下顺序分流： +- 分流顺序： -- 可复用工作流进入 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 评论或过程记录；进入长期参考前必须蒸馏。 + - 可复用工作流进入 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 评论或过程记录； + - 进入长期参考前必须蒸馏。 -规则既能跨项目复用、又依赖 UniDesk 当前目录或服务时，把可复用流程放入 skill，把 UniDesk 特定路径、通道名和验收边界放入 `docs/reference/*.md`，并双向交叉引用。 +- 规则既能跨项目复用、又依赖 UniDesk 当前目录或服务时： + + - 把可复用流程放入 skill； + - 把 UniDesk 特定路径、通道名和验收边界放入 `docs/reference/*.md`； + - 双向交叉引用。 ## 拆分步骤 -Agent 发现本地或远端 `AGENTS.md` 超过 10 KiB 时： - 1. 识别正在修改或扩展的详细领域。 2. 把详细内容移到权威 skill 或 `docs/reference/*.md`。 3. 用一条简短索引和权威链接替换原详细章节。 4. 在 `AGENTS.md` 保留 P0 损害预防警告，但压缩为一行路由规则。 -5. 不得把所有内容移入单个巨大溢出文档。临时迁移记录仅在立即指向各领域承接文档时可用。 -6. 用户未明确要求时，不为体积预算新增测试、保护代码或预检。默认控制方式是文档治理和简洁评审。 +5. 禁止创建巨大溢出文档： + - 不得把所有内容移入单个文件； + - 临时迁移记录仅在立即指向各领域承接文档时可用。 +6. 用户未明确要求时： + - 不为体积预算新增测试、保护代码或预检； + - 默认控制方式是文档治理和简洁评审。 -大型旧文件按领域逐步拆分。每次编辑都应让涉及领域更精简、引用更清晰。 +- 大型旧文件治理： + - 按领域逐步拆分； + - 每次编辑都应让涉及领域更精简； + - 每次编辑都应让引用更清晰。 ## 交叉引用要求 -`AGENTS.md` 中指向外部的每条索引必须注明权威目标。优先使用 `docs/reference/hwlab.md` 等直接路径或 `$unidesk-cicd` 等 skill 名称。 +- 外部索引规则： -不得在 `AGENTS.md`、skill 和长期参考之间重复完整规则。`AGENTS.md` 可以摘要，参考文档拥有细节。两个参考文档冲突时，更新职责更具体的文档，并只保留一个权威版本。 + - 每条索引必须注明权威目标； + - 优先使用 `docs/reference/hwlab.md` 等直接路径； + - 也可使用 `$unidesk-cicd` 等 skill 名称。 + +- 规则归属： + + - 不得在 `AGENTS.md`、skill 和长期参考之间重复完整规则； + - `AGENTS.md` 可以保留摘要； + - 参考文档拥有细节； + - 两个参考文档冲突时，更新职责更具体的文档； + - 冲突处理后只保留一个权威版本。 ## Secret 与输出治理 -指令文件不得包含 Secret、完整 API key、完整 DSN、base64 载荷、bearer token、SSH 私钥或可直接复用的凭据。 +- 指令文件不得包含： -不得把大段 CLI 输出、OTel trace 转储、JSON 数组或浏览器记录粘贴进 `AGENTS.md`。大输出证明可复用规则时，只保留规则摘要，并链接到拥有完整结论的 issue 或参考文档。 + - Secret、完整 API key 或完整 DSN； + - base64 载荷或 bearer token； + - SSH 私钥或可直接复用的凭据。 + +- 大输出治理： + + - 不得把大段 CLI 输出粘贴进 `AGENTS.md`； + - 不得粘贴 OTel trace 转储、JSON 数组或浏览器记录； + - 大输出证明可复用规则时，只保留规则摘要； + - 摘要必须链接到拥有完整结论的 issue 或参考文档。 ## 当前 UniDesk 路由图 diff --git a/docs/reference/docs-governance.md b/docs/reference/docs-governance.md index c010f848..50decde0 100644 --- a/docs/reference/docs-governance.md +++ b/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 审核为主； + - 只提交本次文档治理相关文件； + - 工作区存在并行修改时，不得把无关文件加入提交。