Release v1.0.69: input/output data dirs

development/DATA_PATHS.md

@@ -1,6 +1,6 @@
 # 用户数据目录与文件路径黄金标准
 
-> 本文是 skill **读写本地文件** 的权威约定。凡涉及下载、导入、导出、缓存、RPA 存证等路径，复制模板后须遵守本文；Agent 实现业务 skill 时也应先读本文。
+> 本文是 skill **读写本地文件** 的权威约定。凡涉及输入、输出、缓存、RPA 存证等路径，复制模板后须遵守本文；Agent 实现业务 skill 时也应先读本文。
 
 ---
 
@@ -30,11 +30,17 @@ D:\jiangchang-data\12500\download-video-baidu-haokan\
 
 ## 2. 标准子目录树
 
+用户可见目录（数据管理侧栏只挂这两个）按 **上行 / 下行** 划分：
+
+| 子目录 | 方向 | 用途 | 默认 helper |
+|--------|------|------|-------------|
+| `input/` | 上行 | 用户/Agent 放入的待处理材料（urls.txt、batch.json、CSV、产品表…） | `get_input_dir()` |
+| `output/` | 下行 | 技能/宿主交给用户拿走的结果（视频、回单、xlsx/csv/json…） | `get_output_dir()` |
+
+内部 / 可选目录（**不上侧栏**）：
+
 | 子目录 | 用途 | 默认 helper |
 |--------|------|-------------|
-| `downloads/` | 从外部拉取的原始文件（视频、回单、PDF…） | `get_downloads_dir()` |
-| `imports/` | 用户/Agent 放入的待处理清单（urls.txt、batch.json、CSV） | `get_imports_dir()` |
-| `exports/` | 导出给用户的结果（xlsx/csv/json） | `get_exports_dir()` |
 | `uploads/` | 待发布到外部平台的 staging（可选） | `get_uploads_dir()` |
 | `cache/` | 可再生缓存（页面快照、解析中间结果） | `get_cache_dir()` |
 | `temp/` | 单次任务 scratch，任务结束可删 | `get_temp_dir()` |
@@ -45,6 +51,15 @@ D:\jiangchang-data\12500\download-video-baidu-haokan\
 
 复制后若业务不需要某目录，可不创建；**但一旦写入该类文件，必须走对应 helper**。
 
+**开发者硬规则：**
+
+- 用户/Agent **放进来**的文件 → `input/`（`get_input_dir()`）
+- 技能/宿主 **交给用户拿走**的文件 → `output/`（`get_output_dir()`）
+- 禁止再引入业务侧栏第三目录（如旧的 `downloads` / `imports` / `exports` 三分法）
+- 缓存、临时、RPA 录屏用 `cache` / `temp` / `videos`，不要当成用户可见的「输出目录」
+
+宿主约定（与本模板对齐）：工具栏「导入」默认从 `input/` 取文件；「导出」默认写到 `output/`。
+
 ---
 
 ## 3. 两类路径
@@ -54,6 +69,7 @@ D:\jiangchang-data\12500\download-video-baidu-haokan\
 技能**创建或更新**的文件：下载结果、导出报表、失败截图、队列 sidecar 等。
 
 - **默认**必须在 `{skill_data_dir}/<子目录>/` 下。
+- 用户可拿走的业务产出 → **`output/`**。
 - **必须**通过 `resolve_data_path()` 或 `get_*_dir()` 解析，**禁止** `os.path.abspath(config.get(...))` 相对 CWD。
 
 ### B. 用户显式输入（user-owned）
@@ -61,7 +77,7 @@ D:\jiangchang-data\12500\download-video-baidu-haokan\
 用户在 CLI / Agent 对话中给出的**已有文件**绝对路径，例如「发布这个视频 `D:\素材\x.mp4`」。
 
 - 技能**只读**，路径可以是用户磁盘任意位置。
-- 使用 `resolve_input_path()`：绝对路径原样；**相对路径**解析为 `{skill_data_dir}/imports/<相对路径>`，**不**相对 workspace/CWD。
+- 使用 `resolve_input_path()`：绝对路径原样；**相对路径**解析为 `{skill_data_dir}/input/<相对路径>`，**不**相对 workspace/CWD。
 
 ---
 
@@ -72,9 +88,8 @@ D:\jiangchang-data\12500\download-video-baidu-haokan\
 ```ini
 # ── 数据目录子路径（见 development/DATA_PATHS.md）──
 # 相对路径相对于 {JIANGCHANG_DATA_ROOT}/{USER_ID}/{slug}/，不是 workspace
-# SKILL_DOWNLOAD_DIR=downloads/videos
-# SKILL_IMPORT_DIR=imports
-# SKILL_EXPORT_DIR=exports
+# SKILL_INPUT_DIR=input
+# SKILL_OUTPUT_DIR=output/videos
 # SKILL_UPLOAD_DIR=uploads
 # SKILL_CACHE_DIR=cache
 # SKILL_TEMP_DIR=temp
@@ -83,8 +98,8 @@ D:\jiangchang-data\12500\download-video-baidu-haokan\
 | 规则 | 说明 |
 |------|------|
 | 未配置 | `{skill_data_dir}/{default_subdir}` |
-| 相对值 `downloads/videos` | `{skill_data_dir}/downloads/videos` |
-| 绝对值 `D:\nas\exports` | 高级用户/NAS 挂载，原样使用 |
+| 相对值 `output/videos` | `{skill_data_dir}/output/videos` |
+| 绝对值 `D:\nas\output` | 高级用户/NAS 挂载，原样使用 |
 | **禁止** `./outputs/...` | 会随 CWD 漂移，不得作为 `.env.example` 活跃配置行 |
 
 业务专属路径 env key 须带 **`SKILL_` 前缀**（或技能 slug 前缀），避免污染全局命名空间。
@@ -95,20 +110,20 @@ D:\jiangchang-data\12500\download-video-baidu-haokan\
 
 ```python
 from util.runtime_paths import (
-    get_downloads_dir,
-    get_imports_dir,
+    get_input_dir,
+    get_output_dir,
     resolve_data_path,
     resolve_input_path,
     list_resolved_data_paths,
 )
 
-# 下载保存（A 类）
-dest = os.path.join(get_downloads_dir(), f"{vid}.mp4")
+# 下行产出（A 类）——视频、报表等
+dest = os.path.join(get_output_dir(), f"{vid}.mp4")
 
 # 或带 env 覆盖
-out_dir = resolve_data_path("SKILL_DOWNLOAD_DIR", "downloads")
+out_dir = resolve_data_path("SKILL_OUTPUT_DIR", "output")
 
-# CLI -i urls.txt（B 类，相对路径 → imports/）
+# CLI -i urls.txt（B 类，相对路径 → input/）
 manifest = resolve_input_path(args.input_path)
 
 # health 诊断
@@ -123,6 +138,8 @@ os.path.abspath(config.get("DOWNLOAD_OUTPUT_DIR"))
 
 # ❌ .env.example 里写 ./outputs/videos
 DOWNLOAD_OUTPUT_DIR=./outputs/videos
+
+# ❌ 再拆 downloads / imports / exports 三个用户目录
 ```
 
 ---
@@ -138,7 +155,7 @@ DOWNLOAD_OUTPUT_DIR=./outputs/videos
 - 失败截图、录屏中间文件：`rpa-artifacts/{batch_id}/`（见 [`RPA.md`](RPA.md) §5.1）
 - 录屏成片：`videos/`（见 [`RPA.md`](RPA.md) §5.3）
 
-业务 `downloads/` 与 RPA `videos/` **分工不同**：前者是业务产出文件，后者是操作过程录屏。
+业务 `output/` 与 RPA `videos/` **分工不同**：前者是业务产出文件，后者是操作过程录屏。
 
 ---