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 兜底。