# 工作区与 MDTODO

- 本文只记录遗留来源兼容面；任务管理迁移统一遵循 `$unidesk-tasktree`。

## 必需声明

- 新增节点/工作区规则：
  - 只能通过权威 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 兜底。
