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

工作区与 MDTODO

必需声明

只能通过权威 YAML/配置引用新增节点/工作区。以下概念必须分离：

概念	必需事实
桌面节点	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 节点的路径权威。

接入顺序

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 验收

使用公共项目管理路径和选中的来源：

1. 在 YAML 选中的入口打开 /projects/mdtodo。
2. 用声明的 hwpodId、nodeId、工作区根和相对 MDTODO 根保存来源。
3. 探测来源，并要求结构化就绪结果。
4. 重建索引，记录文档/任务数量和指纹，不记录 Markdown 正文。
5. 确认直接 .md 文件及其任务可见。
6. 用户要求时，从一个任务启动 Workbench，并验证生成的任务/会话关联。

等价 API 族是 /v1/project-management/mdtodo/*；仓库存在 web-probe 命令时使用它们。直接文件系统读取永远不能作为完成证据。

失败分类

错误族	含义
node-offline	Python 进程不存在或 WebSocket 未注册
node-id-mismatch	计划指向不同节点身份
node-auth	凭据缺失或被拒绝
workspace-policy	根目录缺失、不在允许列表或包含性校验失败
capability-mismatch	节点无法执行请求的公共操作
workspace-op	允许根目录内的有界操作失败
source-probe	项目管理无法读取/解析来源
source-projection	来源读取后重建索引或数据库投影失败
web-visibility	API 状态存在，但 HWLAB Web 未正确展示

保留失败层的 requestId/traceId 和节点诊断。修复权威层，不得增加 SSH、直接文件系统、本地挂载或私有 API 兜底。