docs: 统一使用中文结构化子列表

2026-07-10 12:21:13 +02:00
parent 7276278fe5
commit 44187be70d
6 changed files with 534 additions and 135 deletions
@@ -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 <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'
 ```

-分别判断以下状态：
+- 状态分类：

- `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)。
@@ -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&current=<version>`。
@@ -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` 流程。
@@ -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/<drive>/...` 路由可以证明同一批文件存在，但不是 Python 节点的路径权威。
+Windows Python 图形节点的 `workspaceRootRef` 必须使用该进程可见的 Windows 路径。
+WSL `/mnt/<drive>/...` 路由可以证明同一批文件存在，但不是 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 兜底。
@@ -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 <route> 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 <route> 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`。
@@ -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 路由图

@@ -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 审核为主；
+  - 只提交本次文档治理相关文件；
+  - 工作区存在并行修改时，不得把无关文件加入提交。