Skip to content

docs: 勾选 roadmap #15,并补上家族级 config 键支持总表 - #56

Merged
skyzhao1223 merged 1 commit into
mainfrom
docs/config-overlay-family-table
Oct 9, 2026
Merged

skyzhao1223 merged 1 commit into
mainfrom
docs/config-overlay-family-table

Conversation

@skyzhao1223

Copy link
Copy Markdown
Owner

#15 的收尾。8 个专项 scanner 现在全部接入 config.json 覆盖层(#47 → #52 → #54),所以 roadmap 复选框从「[ ] + 注解」改成打勾,两个 README 都改。

skills/README.md 的家族总表

这是唯一能说清全局的地方——各 skill 自己的 SKILL.md 只能讲自己。总表要说明的是:键集不统一,而且 whitelist_dirs 在 5 个 scanner 里有 4 种不同效果:

Skill 命中白名单后具体发生什么 可观测计数键
file-sorter 等价于自动加 --keep-dir;文件仍计入 stats,归入 protected stats.protected
photo-organizer 整棵子树跳过,不计入 stats.files stats.config.skipped_files
music-organizer 整棵子树跳过(同 photo) stats.config.skipped_files
work-organizer 只豁免目录名,子树里的文件照扫照报 无
portfolio-organizer 「这个目录不算项目」,文件仍计入 无
download-cleaner / backup-auditor / dedup-finder skip_dirs:整棵不进入(backup-auditor 作用在三层) stats.config.skipped_dirs

这些效果与计数键是从各 scanner 代码里读出来的,不是从 PR 描述里转述的——例如 work / portfolio 两处代码注释都明确写着「这里没有 photo/music 那个 skipped_files」,而 download-cleaner / backup-auditor / dedup-finder 三处都有 _cfg_skipped_dirs。

同时记录了为什么 whitelist_dirs 与 skip_dirs 不合并成一个键:前者语义是「这块是有意的结构,别判为不合规」,只存在于做目录名合规判定的 5 个 scanner;后者语义是「这块别扫」。同一个键给两种含义,会让「在 skill 之间复制一份 config」产生静默的意外行为。

另外把第 4 条家族规则显式写出来:内置条目只增不删,全家族唯一会「删」的是 extension_overrides——它把扩展名从所有内置表里摘掉再放进指定那一张,这是改判所必需的(分类是有序阶梯,只加不删等于静默无效)。

docs/CONTRIBUTION_IDEAS.md 搬迁四条

原条目 处理
🟡 Resumable sliced upload 移入 Shipped(#53)。并更正原文两处过期说法:① 不需要「本地持久化 {uuid,target,finished}」,因为会话 uuid 本地可重算;② 「参数集未知、naive guesses 返回 N001212」已不成立,path + uuid 就够
🟡 Parallel slice upload 标为「已否证、刻意不实现」而不是 Shipped(issue #11)。保留实测数据(逆序 → N001530 + 产物仍可下载但 MD5 不对),并明确标注仍未测的场景:这条本来针对的高延迟中继
🟢 Post-upload integrity check 移入 Shipped(zs up --verify)。注明没用 POST /v2/file/hash——它在 app.asar 里有定义但全 bundle 从未被调用,契约未知
🟢 Port the config.json overlay to the other 7 skills 移入 Shipped,并说明键集为何不统一

「这份清单已经漂移过 N 次」的提示从三次改成四次——#15 自己漂移了两回:#47 部分交付时一次,现在一次。

验证

检查 结果
ruff check skills src tests ✅ All checks passed
pytest -q ✅ 201 passed(3.12)
9 个 smoke.sh ✅ 全过
两份 skills/README.md 镜像 ✅ 逐字节一致;全部 skill 副本同步
ci.yml「documented skill counts」断言 ✅ 原样跑过
5 个改动文件的 CRLF ✅ 0 个 CR 字节
本次新增的相对 .md 链接 ✅ 全部能解析到真实文件

纯文档改动,不含任何代码变更。

All eight scanners now carry the config.json overlay (#47 file-sorter +
photo-organizer, #52 music/work/portfolio-organizer, #54 download-cleaner /
backup-auditor / dedup-finder), so the roadmap item is done and gets ticked in
both READMEs instead of staying "[ ] with an annotation".

skills/README.md gains the family table. It is the one place that can say
plainly what the per-skill docs cannot: the key set is NOT uniform, and
`whitelist_dirs` has four distinct effects across the five scanners that have
it — file-sorter still counts the files as `protected`; photo- and
music-organizer skip the whole subtree and report `stats.config.skipped_files`;
work-organizer exempts only the directory *name* while still scanning and
reporting the subtree; portfolio-organizer means "this directory is not a
project" and still counts the files. `skip_dirs` is uniform across its three.
The effects and the count keys were read out of each scanner rather than
summarised from the PR descriptions.

Also records why `whitelist_dirs` and `skip_dirs` were not merged into one key:
the first means "this structure is intentional, don't flag it" and only exists
where a scanner judges directory-name compliance; the second means "don't
descend". Handing the same key two meanings would make a config copied between
skills behave surprisingly. A fourth family-wide rule is stated explicitly —
built-ins are only ever appended to, and the sole deletion anywhere is
`extension_overrides` discarding an extension from every built-in table before
adding it to the named one, which re-classification requires because the tables
are an ordered ladder.

docs/CONTRIBUTION_IDEAS.md moves four entries out of the open list:
- resumable sliced upload, shipped in #53 — with the correction that no local
  state needs persisting, since the session uuid is recomputable, and that the
  old "parameter set unknown / naive guesses return N001212" note is obsolete;
- parallel slice upload, marked answered-no rather than shipped, keeping the
  measurement (reverse order yields N001530 plus a file that still downloads
  with the wrong MD5) and the one scenario that remains untested, the
  high-latency relay this entry was actually about;
- post-upload integrity check, shipped as `zs up --verify`, noting that
  /v2/file/hash was not used because it is defined but never called in the
  bundle, so its contract is unknown;
- the config.json overlay port.

The "this list has drifted" note goes from three times to four, since #15
drifted twice: once when #47 partly shipped it and again now.

Verified: ruff clean; pytest 153 passed (3.12); all 9 smoke.sh pass; both
mirrored skills/README.md byte-identical and every skill copy in sync;
ci.yml's documented-skill-count assertion re-run verbatim and still passing;
no changed file contains CRLF; every relative .md link introduced here resolves
to an existing file.
@skyzhao1223
skyzhao1223 merged commit 9334cd1 into main Oct 9, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant