maogeigei
f77735b206
1. 目录 mcn-work-shop -> mcn-workshop（空间分组名取会话 cwd 的目录名，只改字符串无效，必须真改名） 2. 全仓替换 mcn-work-shop -> mcn-workshop：37 文件 121 处；历史日志按沿革句规矩保留当时目录名 3. 任务进度可见：/api/run/status 产出 已运行时长/工具调用/最近动作/停滞判定（读会话日志尾部），前端新增右下角常驻面板，四处任务入口接入 4. 会话归属目录配置化：新增 config.sessionCwd（留空=工作台自身目录），现指向 D://AI技能//mcn-workshop，使任务显示为命名分组而非「未分组任务」 5. 修前端轮询静默缺陷：连续 3 次查询失败即提示服务断开（原逻辑静默空转到 15 分钟超时，用户零感知）
4.9 KiB
4.9 KiB
路径引用规范（相对路径铁律，P0）
适用：本技能树（主技能 + references/references-add + scripts + 全部 subskills 及嵌套 subskills）。技能会被部署到 开发机 / 用户环境 两种机器，绝对路径随机器变化必然失效，故技能内一切文件引用一律使用相对路径。
一、铁律（3 条）
- 技能包内引用一律相对：md 链接、代码文件操作、配置路径，只允许相对路径，禁止绝对路径（Windows 盘符
C:\、D:\… 与 Unix/Users/、/home/… 均禁）。 - md 链接相对「该 md 文件自身」所在目录解析（不是相对技能根）；链接目标必须在技能包内，或用 URL 指向外部。
- 引用不得越级出技能根：禁止
../跳出本技能根引用技能包外文件（技能包外文件不存在于部署环境）。确实需要的包外文件 → 要么移入技能包，要么改为 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/... |
外部资源 |
| 环境判别锚点 | 「技能目录是否处于 git 检出内」 | 仅作是否存在的判定条件，禁止将其作为实际读写路径；锚点必须用仓库特征（git 检出），禁止用写死盘符 |
| 动态产出目录占位 | 桌面 MCNSkill项目/{账号名}/ |
由各技能 references(-add)/路径配置.md 运行时判定，允许出现于规则文档 |
三、禁令项（这些绝对禁止）
- Windows 盘符绝对路径：
C:\Users\maidou\...、D:\MyRepo\...（含正反斜杠两种写法）——除「环境判别锚点/路径配置规则表」语境外的任何引用位置。 - Unix 绝对路径：
/Users/maidou/...、/home/...、/tmp/...（shebang#!/usr/bin/env python3除外）。 - 越级引用：
../../..跳出技能根指向包外文件。 - 引用技能包外文档：md 链接指向不存在于包内的本地文件（如仓库根的维护文档）——部署环境无此文件即断链。
- 硬编码用户名/盘符到产出路径：
C:\Users\maidou\Desktop\...必须写{用户名}占位 + 运行时解析。
四、例外（明确豁免）
| 场景 | 说明 |
|---|---|
| 仅开发机工具 | 不随技能分发的目录（如 mcn-workshop/），内部可保留开发机路径 |
| 环境判别/路径配置文档 | 路径配置.md、SKILL.md 环境判定节——锚点 git 检出特征是规则内容不是引用，保留 |
| 示例/教学文本 | C:/Videos/demo.mp4、C:/path/to/file 等明确示例（path/to、demo 字样） |
| 历史日志 | .workbuddy/memory/ 既有日志保留原样，不改写历史 |
| 第三方整包 | 整包拷贝的第三方技能（如 browser-harness/lieflat-charts/参考skills/）内部自带约定不重写；但本技能对它们的引用仍须相对路径 |
五、设置引用时的操作要点
- 新建/修改任何 md 引用或代码路径：先问「这段代码/文档会被部署到用户环境吗？」——会 → 用相对路径或允许项写法。
- Python 脚本读写文件：统一用
__file__推导技能根常量（如BASE_DIR），再os.path.join(BASE_DIR, ...)拼子路径；禁止字符串拼接盘符。 - md 链接加完必须自检：确认目标文件真实存在（相对自身文件解析），
../层数不超过技能根。 - 引用技能包外但必需的本地文件：先评估移入包内；无法移入 → 去掉链接改为语义描述并注明「仅开发机维护场景」。
六、自检方法（交付前跑一遍）
- 盘符/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 分发；各技能副本内容一致，升级时批量同步）。