maogeigei
c48902f063
配置收敛：
- 端口/DB名/产出根/榜单目录单源化到 mcn-work-shop/config.json，代码层统一经 load-config.js 读取
- 新增 get-port.js 供 start.bat 读端口（bat 内嵌 node -e 会被 cmd 截断，读到的是兜底值）
- start.bat 修复失效的 managed node 路径（原写死 22.22.2 已不存在），改为遍历 versions 自动探测
复盘诊断页（真 bug 修复）：
- 问题清单严重度全部显示成绿色 + 修改建议不显示：模型输出 {sev:'high',fix} 与前端读取 {severity:'高',suggestion} 字段名与取值均不匹配
- 前端新增 normIssue 归一化，兼容 sev/severity/level 与中英取值，并回补所属维度显示
- 在 submit-review-tasks 与诊断/复盘 prompt 中固化 issues_json 字段契约，从源头防 schema 漂移
分镜提示词：
- 原创选题（video_id 为空）原本无生成入口（分镜按 video_id 查询）
- listStoryboards 支持按 rewrite_id 查询，前端放开入口、切版本重查，并补落库指令（此前入库靠模型自由发挥）
榜单展示：
- 期号改为显示区间「08/31 ~ 09/06」，避免被误读为单日（期号=该周周一）
- 后端新增 collectRanges，从落盘文件读真实 dateStart/dateEnd 随 API 返回（日榜 start=end 不显区间）
其他：
- 清理 dsh 环境废弃后的历史叙述类废话（16 文件约 18 处），文末变更记录区保留
- 新增 docs/工作台UI规范.md（设计 token / 布局 / 8 页面路由 / 12 类组件 / 9 条已知坑）
60 lines
5.5 KiB
Markdown
60 lines
5.5 KiB
Markdown
# 路径引用规范（相对路径铁律，P0）
|
||
|
||
> 适用：本技能树（主技能 + references/references-add + scripts + 全部 subskills 及嵌套 subskills）。技能会被部署到 **开发机 / 用户环境** 两种机器，**绝对路径随机器变化必然失效**，故技能内一切文件引用一律使用**相对路径**。
|
||
|
||
## 一、铁律（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/...` | 外部资源 |
|
||
| 环境判别锚点 | 「技能目录是否处于 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-work-shop/`），内部可保留开发机路径 |
|
||
| 环境判别/路径配置文档 | `路径配置.md`、SKILL.md 环境判定节——锚点 git 检出特征是**规则内容**不是引用，保留 |
|
||
| 示例/教学文本 | `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 分发；各技能副本内容一致，升级时批量同步）。*
|
||
*2026-09-10 修订：环境判别锚点由写死盘符 `D:\AgentSkill` 改为**仓库特征**（git 检出判定），并在「允许项」明确「锚点禁止用写死盘符」——避免仓库搬移/改名后判定失效。*
|
||
*2026-09-10 再修订：dsh 部署环境废弃（`~/.dsh/skills/` 与 `D:\dshworkspace` 均不存在），环境模型由三环境精简为**两环境**（开发机 / 用户环境）；「允许项」锚点与「豁免表」同步去掉 `.dsh` 路径段与 `D:\dshworkspace\...` 表述。*
|