admin/workbuddy_skills
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(skills): 两包资源索引机制与双向对账脚本

Browse Source 
- product-planning：新建 references/manifest.md 作资源唯一登记处（资源／落点／引用点／口径）；
  顶层 SKILL 加两条硬规矩，design-capture、stage-delivery、execution-runbook、stage-requirements
  四处把散落路径改为「落点见 references/manifest.md」
- session-mechanism：01-文档索引 新增 §四「包内资源索引」，并说明不放 manifest.md 的理由
  （那份由 install.py 本机生成、被 .gitignore 挡着）
- 新增两包共用的 scripts/check_resource_index.py（双向对账）与 product-planning/scripts/check_figures.py（图片机检），
  selftest 补对应用例，06-技能优化规程 写入写法规矩
- .gitignore：新增 _留痕/ 不入库（改造前整包快照，180K／688K，库内从无先例）
This commit is contained in:
admin committed 2026-10-18 18:07:40 +08:00
1 parent a9d2adaf72
commit acfb252bee
14 files changed
+626 -39
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

session-mechanism/references/01-文档索引.md
+44
View File
@@ -39,6 +39,7 @@
| **判断「要不要做／怎么做／能不能先凑合」** | `04-决策方法论.md`（判据正文）＋ `dsh-decision-method/`（U／A／X 三份素材库） | — |
| **写语气／去 AI 味** | `作业规矩/04-去AI味与说话方式.md`（**会话场景加固版**，含交付前清单与质量评分）＋ `humanizer-en/SKILL.md`（**英文硬核版**：55 模式／5 语气档／0–100 打分） | — |
| **作业总规矩／工作区纪律／多棒接力** | `作业规矩/00-作业总规矩（原 agent-operating-rules）.md` ＋ `作业规矩/02-工作区纪律.md` ＋ `作业规矩/03-多棒接力编排.md` | — |
| **包内有哪些资源、谁在用、在哪**（脚本 / 看板 / 资产 / 子规程 · 要改路径前先看） | 本文件 §四「包内资源索引」 | — |
> 📌 **上表三行 2026-10-10 补齐**：`04-决策方法论.md`、`dsh-decision-method/`、`作业规矩/`、`humanizer-en/` 原先只被正文引用、没进本表
> ⇒ 换会话时会被当成孤儿（本包 §二 规则 1 要求「新增文档必须在这张表里登记」）。
@@ -70,3 +71,46 @@
⚠️ **10-04 的教训**：一条红线立在对的地方（工作区日志 197 KB），仍然等于没立
⇒ **凡是「下次必须做到」的事，必须落在 `references/` 或 `SKILL.md`，⛔ 不能只写日志。**
判据：`selftest.py::t_no_invented_consequence` 量的就是这个（红线在动手层**第一段**）。
## 四、🔴 包内资源索引（有哪些资源 · 谁在用 · 在哪）
> **这一节管什么**（2026-10-16 新增，用户原话：「产品规划 和 会话技能 都检查如何解决 资源索引的问题，避免资源到处引用」）：
> 回答「**某个资源被谁引用、引用点在哪**」，⛔ 不必靠 `grep` 全包找。
> **盘面分工（三层，⛔ 别混）**：`05-技能库盘点规程.md` 管**库层面**（技能根下有哪些技能、该不该入仓）｜
> `06-技能优化规程.md` 管**写法**（描述 / 结构 / 流程怎么写，其 §B #6 就是本节的规矩）｜**本节管包内资源索引**。
>
> 🔴 **本节为什么在这里、不在 `manifest.md`**：`references/manifest.md` 是 `install.py --manifest` 在本机生成的
> 逐文件 md5 表，**被仓根 `.gitignore` 挡着（不入库）** ⇒ 索引写那里＝别台机器取仓后**看不到**，机制静默失效。
> 本节放在**入库**的这份索引里；`product-planning` 没有同类入库载体，它的索引新建成 `references/manifest.md`。
>
> **机检**：`python scripts/check_resource_index.py --pkg "<本包根>" --index references/01-文档索引.md`
> （同一份实现也给 `product-planning` 用：`--pkg "<技能根>/product-planning"`，那边用默认 `--index`）。
> 四个闸门：落点是否存在 ／ 登记的引用点是否为真 ／ `口径=只写一次` 的资源有没有人绕开清单在别处抄路径 ／
> 有没有登记了却没人用的资源。
>
> **`口径` 列**：`只写一次` ＝ 该资源路径字面量只许出现在本清单与 `许可字面量` 列登记的文件里；
> `可多次` ＝ 只登记「谁在用、在哪」，不限字面量。🔴 **本包资源一律 `可多次`** —— 这里的资源是**代码与规程**，
> 引用必须精确到文件（写个模糊名字反而没法用）；「只写一次」那道闸门是给**资产 / 样式套**这类资源用的，
> 目前 `product-planning` 的「样式套目录」在用。
>
> 🔴 `被谁引用` 与 `许可字面量` 是两件事：前者「谁在用」（可由 `--sync-refs` 自动回写，超过 12 个只记个数）；
> 后者「谁被允许写路径字面量」（人工开的口子 —— ⛔ 自动回写会把它冲成「谁都许可」，闸门就空了）。
| 资源 | 落点 | 干什么 | 被谁引用 | 许可字面量 | 口径 | 入仓 |
|---|---|---|---|---|---|---|
| 机制脚本 | `scripts/` | 常驻与机制脚本（`collabd.py` / `collabctl.py` / `goalctl.py` / `supervise-launch.py` / `guard.py` / `deploy_code.py` 等） | SKILL.md、boards/会话看板/board-launch.py、boards/会话看板/board-launch.py.tpl、boards/会话看板/board.py、boards/项目看板/project-board.py、install.py、references/00-动手前必过.md、references/02-功能优先协作协议.md、references/03-回复排版-核心块.md、references/04-决策方法论.md、references/06-技能优化规程.md、references/architecture.md（共 44 个） | — | 可多次 | 是 |
| 宿主钩子 | `scripts/hooks/` | 挂在宿主事件上的钩子脚本 | SKILL.md、boards/会话看板/board.html、boards/会话看板/board.py、boards/会话看板/board_ext.py、install.py、references/03-回复排版-核心块.md、references/99-速查清单.md、references/architecture.md、references/collab-detail.md、references/collab.md、references/deploy.md、references/humanizer-en/SKILL.md（共 32 个） | — | 可多次 | 是 |
| 锁机制 | `scripts/lock/` | 锁原语与释放工具 | SKILL.md、boards/会话看板/board-render-probe.js、boards/会话看板/board.html、boards/会话看板/board.py、boards/会话看板/tmp/supervise-inbox/board.json、boards/项目看板/project-board.html、boards/项目看板/project-board.py、install.py、references/architecture.md、references/collab-detail.md、references/collab.md、references/deploy.md（共 38 个） | — | 可多次 | 是 |
| 取证工具 | `scripts/forensics/` | 取证 / 诊断工具 | SKILL.md、references/architecture.md、references/collab.md、references/forensics.md、references/manifest.md、references/pitfalls.md、references/作业规矩/00-作业总规矩（原 agent-operating-rules）.md、scripts/hooks/wb-result-hook.py | — | 可多次 | 是 |
| 资源索引机检 | `scripts/check_resource_index.py` | 本节与 `product-planning` 资源表的双向对账（两份技能共用这一份实现） | references/06-技能优化规程.md、references/manifest.md、scripts/check_resource_index.py | — | 可多次 | 是 |
| 会话看板 | `boards/会话看板/` | 会话架构看板（端口 20099）；页面与脚本同处一包 | SKILL.md、boards/会话看板/board-launch.py、boards/会话看板/board.py、boards/会话看板/board_ext.py、boards/会话看板/tmp/supervise-inbox/board.json、boards/项目看板/project-board.py、references/architecture.md、references/collab-detail.md、references/deploy.md、references/manifest.md、references/pitfalls.md、scripts/collabctl.py（共 14 个） | — | 可多次 | 是 |
| 项目看板 | `boards/项目看板/` | 项目＋任务看板（端口 20100）；页面与脚本同处一包 | SKILL.md、boards/项目看板/project-board-launch.py、boards/项目看板/project-board.html、boards/项目看板/project-board.py、references/manifest.md | — | 可多次 | 是 |
| 作业规矩 | `references/作业规矩/` | 作业总规矩等写法类规程 | SKILL.md、references/02-功能优先协作协议.md、references/03-回复排版-核心块.md、references/architecture.md、references/collab-detail.md、references/manifest.md、references/rules.md、scripts/check_resource_index.py、scripts/hooks/reply-style-guard.py、scripts/hooks/skill-load-guard.py、scripts/selftest.py | — | 可多次 | 是 |
| 决策方法论 | `references/dsh-decision-method/` | `04-决策方法论.md` 背后的素材库（U / A / X 条目） | references/02-功能优先协作协议.md、references/04-决策方法论.md、references/dsh-decision-method/素材库-A-AI推理.md、references/dsh-decision-method/素材库-U-用户决策.md、references/dsh-decision-method/素材库-反例-X.md、references/manifest.md、references/pitfalls.md、scripts/hooks/decision-rules-hook.py、scripts/hooks/skill-load-guard.py、scripts/session-rules-check.py | — | 可多次 | 是 |
| 英文文案判据 | `references/humanizer-en/` | 英文版文案判据（中文版在 `humanizer` 技能） | SKILL.md、references/collab-detail.md、references/manifest.md、references/作业规矩/04-去AI味与说话方式.md、scripts/selftest.py | — | 可多次 | 是 |
| 输出阶梯 | `references/karpathy-output-ladder/` | 输出阶梯判据 | references/karpathy-output-ladder/SKILL.md、references/manifest.md | — | 可多次 | 是 |
| 规程与背景文档 | `references/` | 顶层 `*.md`：`00`–`06` 规程 ＋ `99-速查清单` ＋ 本文件 ＋ `architecture` / `rules` / `pitfalls` / `taskgraph` / `collab` / `collab-detail` / `deploy` / `forensics` / `supervise-persistence` | SKILL.md、boards/会话看板/board-launch.py.tpl、boards/会话看板/board_ext.py、install.py、references/02-功能优先协作协议.md、references/03-回复排版-核心块.md、references/04-决策方法论.md、references/05-技能库盘点规程.md、references/06-技能优化规程.md、references/99-速查清单.md、references/architecture.md、references/collab-detail.md（共 40 个） | — | 可多次 | 是 |
| 留痕 | `references/_留痕/` | 改动前快照（append-only，⛔ 不进机检扫描范围） | SKILL.md、boards/会话看板/board-launch.py、boards/会话看板/board.html、boards/会话看板/board.py、boards/会话看板/board_ext.py、boards/项目看板/project-board.py、install.py、references/02-功能优先协作协议.md、references/architecture.md、references/collab.md、references/dsh-decision-method/素材库-A-AI推理.md、references/manifest.md（共 31 个） | — | 可多次 | 是 |
| 设计令牌 | `assets/design-tokens.css` | 包内静态样式令牌（看板页面用） | SKILL.md、references/manifest.md | — | 可多次 | 是 |
| 装机脚本 | `install.py` | 一键配置；`--manifest` 重算 `references/manifest.md` 那张逐文件表 | SKILL.md、boards/会话看板/board.py、boards/会话看板/board_ext.py、boards/项目看板/project-board.py、install.py、references/06-技能优化规程.md、references/deploy.md、references/manifest.md、references/pitfalls.md、references/rules.md、scripts/check_resource_index.py、scripts/collabctl.py（共 29 个） | — | 可多次 | 是 |
| 本机配置 | `env/roots.env` | 每台机器一份的工作区 roots（`*.example` 入仓，实体不入仓） | SKILL.md、boards/会话看板/board-launch.py、boards/会话看板/board-launch.py.tpl、boards/会话看板/board.py、boards/会话看板/board_ext.py、boards/项目看板/project-board-launch.py、boards/项目看板/project-board.py、install.py、references/deploy.md、references/manifest.md、references/pitfalls.md、references/rules.md（共 34 个） | — | 可多次 | 否 |
session-mechanism/references/06-技能优化规程.md
+18 -2
View File
@@ -47,6 +47,21 @@
⚠️ 只写进 `references/` 等着回头查 ⇒ 等于没立；机核脚本只作**兜底**，⛔ 不当主手段。
（用户 2026-10-16 令：「要生成的时候 就按照要求，不是事后再修复」。）
**6 资源路径只在资源清单写一次**
单包资源索引。本包有什么资源（脚本 / 看板 / 资产 / 子规程 / 同根技能依赖）、落在哪、被谁引用，**唯一登记处**是该包里
**入库的那份索引文件**（本包＝`references/01-文档索引.md §四`；`product-planning`＝`references/manifest.md`）；
别的文字里**只写资源名**，⛔ 不把路径抄进散文、段文档、脚本注释与模板。
🔴 **索引文件必须放入库的那份** —— 实测踩过：本包 `references/manifest.md` 被仓根 `.gitignore` 挡着
（`install.py --manifest` 在本机生成、随机器变）⇒ 索引写那里＝别台机器取仓后看不到，机制静默失效。
判据：**改一次目录，要改几个文件** —— 一处以上 ⇒ 那是照抄，不是引用。
机检：`python scripts/check_resource_index.py --pkg "<本包根>" --index references/01-文档索引.md`
（`product-planning` 用默认 `--index`）—— 四项（落点是否存在 / 登记的引用点是否为真 /
有没有人绕开清单在别处抄路径 / 有没有登记了却没人用的资源）；⛔ 有 🔴 不算改完，不静默放过。
⚠️ 何时把资源设成 `只写一次`：**资产 / 样式套**这类「换个落点也不影响怎么用」的（现例：`product-planning` 的样式套目录）；
**代码与规程**设成 `可多次` —— 引用必须精确到文件，写模糊名字反而没法用。
（用户 2026-10-16 原话：「为什么这么多地方引用 一个样式库，是不是技能中没有统一索引机制」＋
「产品规划 和 会话技能 都检查如何解决 资源索引的问题，避免资源到处引用」。）
### C 流程层（→ 流程顺畅 · 功能正常）
> 来路：2026-08-10 另一工作区对创作流程做全量审计归纳的 13 项里，9 项属这一层；
@@ -86,10 +101,10 @@
---
## 技能优化描述 · 总表（17 条，三层）
## 技能优化描述 · 总表（18 条，三层）
> **怎么来的**：① B／C／D 三层判据（＝本规程正文）；② 另一工作区的 `技能审计检查清单.md`（`E:/ProgramData/AIProject/mcn-short-video/技能审计检查清单.md`，2026-08-10 创作流程全量审计的 13 项；跨根引用，仅作来路说明）。
> **用法**：按 **1 → 17** 逐条过。**分级**：**P0 ＝ 会让人出事或断链**（#13 产物链）／**P1 ＝ 不一致或冗余**（B 层 ＋ C 层其余）／**P2 ＝ 效果差**（D 层）。
> **用法**：按 **1 → 18** 逐条过。**分级**：**P0 ＝ 会让人出事或断链**（#13 产物链）／**P1 ＝ 不一致或冗余**（B 层 ＋ C 层其余）／**P2 ＝ 效果差**（D 层）。
> 🔴 **判据正本 ＝ 本规程正文的对应项**，表里只给锚点与反例；⛔ **本表只收通用要求** —— `env/` 怎么放、
> 路径怎么写、什么不入仓这类**专有配置规则不在本表**，见 `01-文档索引.md` 的「技能环境配置规范」。
@@ -112,3 +127,4 @@
| 15 | D 表述 | 说人话 | 见 §D #15 | 四种 AI 味：三段式排比连用／"…着"结尾的肤浅分析／模糊归因／拆成加粗小标题＋竖排碎句 |
| 16 | D 表述 | 一页纸 | 见 §D #16 | 一份 300 行的"速查" |
| 17 | B 结构 | 要求落在生成时看得见的面上 | 见 §B #5 | 只写进 `references/` 等着回头查 ⇒ 等于没立 |
| 18 | B 结构 | 资源路径只在资源清单写一次 | 见 §B #6 | 同一资源路径抄在 6 个文件 20 处，改目录漏改不报错 |