全技能树相对路径审计+路径引用规范固化(P0)
- 审计 V1.0 全树(主技能+references+全部subskills及嵌套)Windows/Unix 绝对路径与 md 断链
- 豁免判定: 环境判别锚点/路径配置表/示例路径保留; browser-harness/envs 由 gitignore 兜底不随分发
- 修复: SKILL.md 七节越级引用 ../../../失误与规避记录.md 改语义说明(仅开发机维护场景); mcn-dou-analysis 内嵌 nuwa-skill-main 断链(多语言/社区/评分卡/示例 LICENSE)改官方 GitHub URL(源+dsh 副本同步)
- 新增 references/规则/路径引用规范.md(相对路径铁律: 允许项~占位/__file__推导/URL + 禁令盘符/Unix/越级 + 豁免 + 自检), 模板同步 V1.0+4 自有 subskills+dsh 4 副本
- 5 源 SKILL.md + 4 dsh SKILL.md 挂 🔴 路径引用引用行
- 自有内容 md 断链复验=0; 临时审计脚本已清理
This commit is contained in:
maogeigei committed
1 parent
ca009c095e
commit
061bbb64fb
21 files changed
+437
-23
No files matched your search
@@ -0,0 +1,104 @@
|
||||
# 自动化任务清理规范（09-03 定稿）
|
||||
|
||||
> **用途**：后台自动化任务（一次性任务）积攒过多时，安全清理**过期 / 执行失败**的任务。
|
||||
> **适用环境**：WorkBuddy 全环境通用（开发机 / dsh 部署环境 / 用户环境）——automations 表是 WorkBuddy 宿主自带（`~/.workbuddy/workbuddy.db`），不依赖 MCN 工作台，任何装了本技能的 WorkBuddy 都能执行。
|
||||
> **红线（用户明确）**：**只能清理「过期」或「错误/失败」的任务**，禁止清理未来任务 / 周期任务 / 运行中任务。
|
||||
|
||||
## 一、触发场景
|
||||
|
||||
用户表达以下任一意图时，按本文档执行（不需要走创作流程）：
|
||||
- 「后台在执行什么任务？」
|
||||
- 「没用的任务可以清空吗 / 清一下后台任务 / 把过期任务删掉」
|
||||
- 「清理自动化任务 / 任务太多了」
|
||||
|
||||
执行前先**只读盘点 → 列出清单 → 用户确认 → 再删**，禁止未经确认批量删除。
|
||||
|
||||
## 二、判定标准（只清这两类）
|
||||
|
||||
自动化任务表 `automations` 存储任务定义，运行记录在 `automation_runs`，运行状态在 `automation_runtime_state`。
|
||||
|
||||
| 类别 | 可清理条件（全部满足） | 典型 |
|
||||
|---|---|---|
|
||||
| 🟢 **过期历史任务** | `schedule_type='once'`（一次性）且计划时间已过，且**已跑完**（有 run 记录且终态 ACCEPTED、`result_success=1`） | 工作台批量创作/复盘跑完后的任务定义 |
|
||||
| 🔴 **错误/失败任务** | `schedule_type='once'` 且已终结但**未成功**：run 终态 PENDING_REVIEW / `result_success=0` / runtime_state 有 `last_error`（如 user_cancel 中断） | 被用户取消的导入、出错的复盘 |
|
||||
| ⚪ **死任务**（可选，需用户点头） | `schedule_type='once'` 且**从未运行**（无 run 记录）且计划时间已过期（如 >24h 前），确认不会被调度器补跑 | 旧版重复任务、被新版取代的任务 |
|
||||
|
||||
### 禁止清理（硬性）
|
||||
|
||||
| 情形 | 原因 |
|
||||
|---|---|
|
||||
| `schedule_type='recurring'`（周期任务） | 未来还会按 rrule 触发 |
|
||||
| 计划时间在**未来**（`scheduled_at` / `next_run_at` 未到） | 还没执行 |
|
||||
| `automation_runtime_state.running=1` | 正在执行 |
|
||||
| run 状态 QUEUED / IN_PROGRESS（排队/进行中） | 尚未终结 |
|
||||
| `deleted_at` 已非空 | 已删过，无需处理 |
|
||||
|
||||
## 三、执行步骤
|
||||
|
||||
### 第 1 步：只读盘点（SQL 查询，只读不改）
|
||||
|
||||
数据库：`~/.workbuddy/workbuddy.db`（Windows: `C:\Users\<用户名>\.workbuddy\workbuddy.db`；macOS/Linux: `~/.workbuddy/workbuddy.db`）。**只用只读模式打开**（SQLite URI `mode=ro`），任务表可能被宿主进程占用，只读查询不受影响。
|
||||
|
||||
```bash
|
||||
# 审计三表：automations（任务定义）/ automation_runs（运行历史）/ automation_runtime_state（运行状态）
|
||||
python3 -c "
|
||||
import sqlite3, os, datetime, json
|
||||
db = os.path.expanduser('~/.workbuddy/workbuddy.db')
|
||||
con = sqlite3.connect(f'file:{db}?mode=ro', uri=True)
|
||||
con.row_factory = sqlite3.Row
|
||||
cur = con.cursor()
|
||||
def ts(v):
|
||||
if v is None: return None
|
||||
try: return datetime.datetime.fromtimestamp(int(v)/1000).strftime('%m-%d %H:%M')
|
||||
except: return v
|
||||
|
||||
print('=== 1) 真正在跑（running=1，禁止清理）===')
|
||||
for r in cur.execute('SELECT automation_id, running, last_error FROM automation_runtime_state WHERE running=1').fetchall():
|
||||
print(dict(r))
|
||||
|
||||
print()
|
||||
print('=== 2) 每个任务：类型/计划时间/是否已跑/是否成功 ===')
|
||||
rows = cur.execute('''
|
||||
SELECT a.id, a.name, a.status, a.schedule_type, a.scheduled_at, a.next_run_at, a.last_run_at,
|
||||
COUNT(r.automation_id) AS run_cnt,
|
||||
SUM(CASE WHEN r.result_success=1 THEN 1 ELSE 0 END) AS ok_cnt,
|
||||
MAX(CASE WHEN r.status IN ('QUEUED','IN_PROGRESS') THEN 1 ELSE 0 END) AS active_run
|
||||
FROM automations a LEFT JOIN automation_runs r ON r.automation_id = a.id
|
||||
WHERE a.deleted_at IS NULL
|
||||
GROUP BY a.id ORDER BY a.created_at
|
||||
''').fetchall()
|
||||
for r in rows:
|
||||
d = dict(r)
|
||||
d['scheduled_at'] = ts(d['scheduled_at']); d['next_run_at'] = ts(d['next_run_at']); d['last_run_at'] = ts(d['last_run_at'])
|
||||
print(json.dumps(d, ensure_ascii=False))
|
||||
"
|
||||
```
|
||||
|
||||
### 第 2 步：按判定标准归档
|
||||
|
||||
对上面输出逐条归档到三类：**🟢 过期已完成** / **🔴 错误失败** / **⚪ 从未运行的死任务**（这三类之外的：未来任务 / recurring / running / QUEUED / IN_PROGRESS → 一律保留）。
|
||||
|
||||
### 第 3 步：列清单给用户确认
|
||||
|
||||
用表格呈现：`任务名 | ID | 计划时间 | 归档类别 | 建议动作（删除/保留）`，等用户明确同意后再删。
|
||||
|
||||
### 第 4 步：删除（走宿主工具，禁止直改数据库）
|
||||
|
||||
删除必须通过 WorkBuddy 宿主自动化工具逐条执行（`automation_update`，mode=delete），**严禁**用 SQL `DELETE` / `UPDATE` 直写 automations 表（宿主可能正持有连接；且工具删除是受支持的软删，会正确置 `deleted_at`）。
|
||||
|
||||
> 工具删除幂等安全：对已删除任务重复删会返回 `already deleted or does not exist`（success:true），不会报错。
|
||||
|
||||
### 第 5 步：复核
|
||||
|
||||
```python
|
||||
# 只读复核：有效任务应为 0 或仅剩应保留项
|
||||
SELECT COUNT(*) FROM automations WHERE deleted_at IS NULL;
|
||||
SELECT COUNT(*) FROM automation_runtime_state WHERE running=1; -- 应为 0
|
||||
```
|
||||
|
||||
## 四、补充事实（实测，便于判断）
|
||||
|
||||
- **宿主不会自动清理**：一次性任务跑完（ACCEPTED）后任务定义保留、状态仍 ACTIVE，调度器只扫未来时间，不会再触发——但也不会自动删除 → 需人工/按本规范清理
|
||||
- **删除不影响任何产物**：已生成的脚本/复盘/会话历史在 `automation_runs`（保留），删任务定义只移除调度入口，不影响历史记录与产出文件
|
||||
- 工具删除为**软删**（置 `deleted_at`），表行物理保留，逻辑上不可见
|
||||
- 命名线索：`创作指令`/`复盘指令`/`重写-xxx(videoID)`/`修复-videoID`/`解析视频-xxx` 均为一次性任务；带明确未来重复意图（周报/日报）才会是 recurring
|
||||
@@ -0,0 +1,57 @@
|
||||
# 路径引用规范（相对路径铁律，P0）
|
||||
|
||||
> 适用：本技能树（主技能 + references/references-add + scripts + 全部 subskills 及嵌套 subskills）。技能会被部署到 **开发机 / dsh 环境 / 用户环境** 三种机器，**绝对路径随机器变化必然失效**，故技能内一切文件引用一律使用**相对路径**。
|
||||
|
||||
## 一、铁律（3 条）
|
||||
|
||||
1. **技能包内引用一律相对**：md 链接、代码文件操作、配置路径，只允许相对路径，禁止绝对路径（Windows 盘符 `C:\`、`D:\`… 与 Unix `/Users/`、`/home/`… 均禁）。
|
||||
2. **md 链接相对「该 md 文件自身」所在目录解析**（不是相对技能根）；链接目标必须在技能包内，或用 URL 指向外部。
|
||||
3. **引用不得越级出技能根**：禁止 `../` 跳出本技能根引用技能包外文件（技能包外文件不存在于部署环境）。确实需要的包外文件 → 要么移入技能包，要么改为 URL / 语义描述。
|
||||
|
||||
## 二、允许项（这些可以写）
|
||||
|
||||
| 写法 | 示例 | 说明 |
|
||||
|------|------|------|
|
||||
| 相对技能根路径 | `references/创作流程规范.md`、`scripts/fetch.py` | 引用包内文件 |
|
||||
| md 相对链接（示例写法） | `[规范](../接口调用/某文件.md)` | 相对该 md 所在文件解析，目标在包内 |
|
||||
| 用户级路径（`~`/占位） | `~/.workbuddy/workbuddy.db`、`{主目录}/.dsh/...` | 用户级，跨机器一致；Windows 用 `%USERPROFILE%` 语义的 `{用户名}` 占位 |
|
||||
| `__file__` 动态推导 | `BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))` | 脚本定位技能根，跨环境可迁移 |
|
||||
| 环境变量 | `os.getenv("REDFOX_API_KEY")`、`MCN_RANKING_DIR` | 值由外部注入 |
|
||||
| URL | `https://github.com/...` | 外部资源 |
|
||||
| 环境判别锚点 | 「本机是否存在 `D:\AgentSkill`」「技能路径是否含 `.dsh`」 | 仅作**是否存在/是否包含**的判定条件，**禁止**将其作为实际读写路径 |
|
||||
| 动态产出目录占位 | 桌面 `MCNSkill项目/{账号名}/`、`D:\dshworkspace\创作任务\` | 由各技能 `references(-add)/路径配置.md` 运行时判定，允许出现于规则文档 |
|
||||
|
||||
## 三、禁令项（这些绝对禁止）
|
||||
|
||||
- **Windows 盘符绝对路径**：`C:\Users\maidou\...`、`D:\AgentSkill\...`（含正反斜杠两种写法）——除「环境判别锚点/路径配置规则表」语境外的任何引用位置。
|
||||
- **Unix 绝对路径**：`/Users/maidou/...`、`/home/...`、`/tmp/...`（shebang `#!/usr/bin/env python3` 除外）。
|
||||
- **越级引用**：`../../..` 跳出技能根指向包外文件。
|
||||
- **引用技能包外文档**：md 链接指向不存在于包内的本地文件（如仓库根的维护文档）——部署环境无此文件即断链。
|
||||
- **硬编码用户名/盘符到产出路径**：`C:\Users\maidou\Desktop\...` 必须写 `{用户名}` 占位 + 运行时解析。
|
||||
|
||||
## 四、例外（明确豁免）
|
||||
|
||||
| 场景 | 说明 |
|
||||
|------|------|
|
||||
| 仅开发机工具 | 不随技能分发的目录（如 `mcn-work-shop/`），内部可保留开发机路径 |
|
||||
| 环境判别/路径配置文档 | `路径配置.md`、SKILL.md 环境判定节——锚点 `D:\AgentSkill`、`.dsh`、`D:\dshworkspace\...` 是**规则内容**不是引用，保留 |
|
||||
| 示例/教学文本 | `C:/Videos/demo.mp4`、`C:/path/to/file` 等明确示例（`path/to`、`demo` 字样） |
|
||||
| 历史日志 | `.workbuddy/memory/` 既有日志保留原样，不改写历史 |
|
||||
| 第三方整包 | 整包拷贝的第三方技能（如 browser-harness/lieflat-charts/参考skills/）内部自带约定不重写；但**本技能对它们的引用**仍须相对路径 |
|
||||
|
||||
## 五、设置引用时的操作要点
|
||||
|
||||
1. **新建/修改任何 md 引用或代码路径**：先问「这段代码/文档会被部署到用户环境吗？」——会 → 用相对路径或允许项写法。
|
||||
2. **Python 脚本读写文件**：统一用 `__file__` 推导技能根常量（如 `BASE_DIR`），再 `os.path.join(BASE_DIR, ...)` 拼子路径；禁止字符串拼接盘符。
|
||||
3. **md 链接加完必须自检**：确认目标文件真实存在（相对自身文件解析），`../` 层数不超过技能根。
|
||||
4. **引用技能包外但必需的本地文件**：先评估移入包内；无法移入 → 去掉链接改为语义描述并注明「仅开发机维护场景」。
|
||||
|
||||
## 六、自检方法（交付前跑一遍）
|
||||
|
||||
- **盘符/Unix 绝对路径扫描**：对技能包文本文件搜 `[A-Za-z]:[\\/]`、`/(Users|home|tmp|opt|etc|var|root|usr|Applications)/`，人工复核命中行是否属「允许/豁免」类别。
|
||||
- **md 断链校验**：正则 `\]\(([^)]+)\)` 提取相对链接 → 相对文件目录解析 → 目标不存在即断链；跳过 http/https/file/mailto/# 锚点、含空格/`<>`/`$`/`|` 的命令示例、`workUrl/url/link/链接` 等 API 字段伪链接。
|
||||
- **越级检查**：任何解析后超出技能根的链接即违规。
|
||||
|
||||
---
|
||||
|
||||
*变更记录：2026-09-03 初建（全技能树相对路径审计定稿，随 V1.0 与各 subskills 分发；各技能副本内容一致，升级时批量同步）。*
|
||||
Reference in new issue
Block a user