docs: workspace-only testing — README, schema/CI reference, add-package skill, design doc

Also retires two-generations-stale CI descriptions (detect/smoke-examples/
run_example.sh) from docs/repository-and-schema.md.

Author: Sunrisepeak

.agents/docs/2026-07-18-workspace-only-module-testing.md

@@ -0,0 +1,61 @@
+# workspace-only 模块包测试(mcpp 0.0.97 / R6 落地)
+
+日期:2026-07-18 · PR:feat/mcpp-097-workspace-only-ci
+
+## 背景
+
+公开模块包(namespace = "",即内建 mcpplibs 默认命名空间:imgui/ffmpeg/opencv/
+tinyhttps)此前无法像 compat.* 一样经 `[indices] <ns> = { path }` 指回本仓 checkout
+——mcpp 没有重定向**默认命名空间**的语法。合并前验证只能走每包一个的 reseeding
+smoke shell(临时 MCPP_HOME + 物理拷贝 checkout 覆盖默认索引落盘位置)+ 专属 CI
+job,是 zero-shell 立仓哲学下唯一的例外通道。
+
+mcpp 0.0.97 落地了 `[indices] default = { path = ... }`(亦接受 `""` 键;url 形式
+显式报错),并且根级 `[indices]` 的相对 path 按 **workspace 根**解析、成员自动继承
+(#224)。例外通道的存在理由消失。
+
+## 变更
+
+1. **mcpp pin 0.0.96 → 0.0.97**(env + 3 平台矩阵)。
+2. **成员级 default 重定向**(根级集中化被 mcpp#238 挡住,见下"过程发现"):
+   每个成员保持/新增恰好一条 `[indices]`;模块包成员用
+   `default = { path = "../../.." }`(V0 spike 实证:假版本号 999.0.0 只存在于
+   本地副本仍可解析,`""`/`default` 两种键均可)。
+3. **4 个模块包 smoke → workspace 成员**:
+   - tests/examples/tinyhttps(已有工程,登记成员;三平台描述符,不门控);
+   - tests/examples/imgui-module(cfg(linux) 门控——描述符虽三平台,但只有
+     linux 被 CI 验证过,按已验证面转换;老 smoke 的 llvm@20.1.7 钉不再携带:
+     它早于 gcc16 模块支持,imgui-m 上游 CI 现以 gcc@16.1.0 构建模块层);
+   - tests/examples/ffmpeg-module、tests/examples/opencv-module(包本身 linux-only,
+     cfg(linux) 门控 + 非 linux no-op main)。
+   测试源码逐行移植自对应 smoke 的消费工程(断言不变)。
+4. **删除**:tests/smoke_{tinyhttps,imgui,ffmpeg,opencv}_module.sh、validate.yml 的
+   imgui-module/ffmpeg-module/opencv-module 三个 job 与 workspace job 里的 tinyhttps
+   smoke 步骤、`mcpp index update` 前置步骤(#232 已修,V0 冷环境实证:无 PATH/apt
+   nasm 时从沙箱同步解析)。
+5. **文档**:README 贡献段、docs/repository-and-schema.md(布局 + CI 行为两节,
+   顺带清掉两代前的 detect/smoke-examples 残留描述)、add-mcpp-index-package skill
+   (成员化流程、`mcpp test -p` 本地验证)。
+
+## 过程发现:xlings 多项目级 repo 静默失败(mcpp#238)
+
+首版实现走的是 #224 根级集中化(根一次声明 5 个命名空间、删全部 per-member
+块)。本地验证发现:成员沙箱 .xlings.json 一旦注册 ≥2 个项目级 index repo,
+`xlings interface install_packages` 对任意包静默 exit 1(无 error 事件)——与
+repo 名、URL 无关,纯数量触发。既有成员从未暴露(每成员恰好 1 条);根级继承让
+每个成员变成 5 条,全部未缓存安装即挂。已提 mcpp#238(含最小复现矩阵);本 PR
+退回单条声明形态,修复后再集中化。连带影响:模块成员的传递 compat 依赖
+(opencv → compat.opencv5)从**已发布**的全局 compat 索引解析,而非本 checkout
+(compat 描述符的合并前验证由其专属成员覆盖,见成员注释)。
+
+## 语义差异(接受)
+
+smoke 曾额外覆盖"物理重播默认索引"这一机制本身;成员形态覆盖的是我们真正关心的
+**合并前描述符正确性**,消费的仍是真实已发布 tarball(Form A 下载源不变)。
+选择性成员测试机制对新成员零配置生效(pkgs/<x>/<lib>.lua → grep 引用成员)。
+
+## 效果
+
+- CI job 数 8 → 5(lint、mirror-cn-reachable、workspace×3);模块包验证并入
+  `mcpp test --workspace`,新模块包只需加成员目录,不再复制 shell。
+- 后续 compat.opencv 合一(B0)、opencv 0.0.3 升版等改动的回归 = 改一行 + CI。

.agents/skills/add-mcpp-index-package/SKILL.md

@@ -60,20 +60,26 @@ description: Use when adding a new third-party library/package to the mcpp-index
    - `xpm` 须覆盖三平台(linux/macosx/windows),每个版本包含 `url = { GLOBAL=…, CN=… }` 与 `sha256`。
    - 版本号采用**裸版本**(如 `"1.2.3"`),不含前导 `v`;下载 URL 中可保留上游的 `…/v1.2.3.tar.gz` 形式。
 5. **识别可门控的可选组件并实现 feature**(参见下文“feature 机制”)。feature 仅能门控 **sources**。
-6. **编写最小工程** `tests/examples/<short>/`(`short` 为包名去除 `compat.`/`mcpplibs.` 前缀后的结果)。
-   - 包含 `mcpp.toml`(其 `[indices].compat = { path = "../../.." }` 指回仓根)与一个 `src/main.*`,
-     后者须包含**可失败的有效断言**(`return ok ? 0 : 1`)。
+6. **编写测试工程(workspace 成员)** `tests/examples/<short>/`(`short` 为包名去除 `compat.`/`mcpplibs.`
+   前缀后的结果;公开模块包用 `<name>-module`),并把它加进仓根 `mcpp.toml` 的 `[workspace].members`。
+   - 包含 `mcpp.toml` 与 `tests/*.cpp`,后者须包含**可失败的有效断言**(`return ok ? 0 : 1`)。
+   - 成员声明**恰好一条** `[indices] <ns> = { path = "../../.." }`,把所消费命名空间重定向到
+     本 checkout(公开模块包用 `default`,即内建 mcpplibs 命名空间;mcpp ≥ 0.0.97)。
+     单条是硬约束:xlings 对 >1 个项目级 index repo 静默失败(mcpp#238);根级集中化待其修复。
+   - 非全平台包按 `[target.'cfg(...)'.dependencies]` 门控依赖,测试源码在被门控掉的平台上
+     编译为 no-op `main`(`#ifdef __linux__ … #else int main(){return 0;} #endif` 模式)。
    - 如需测试 feature,依赖采用长式声明 `name = { version = "…", features = ["…"] }`。
-7. **本地验证**(使用与 CI 相同版本的 mcpp,详见下文“本地验证”)。必须实际执行 `mcpp build` 与 `mcpp run` 并通过。
+7. **本地验证**(使用与 CI 相同版本的 mcpp,详见下文“本地验证”)。必须实际执行 `mcpp test -p <member>` 并通过。
 8. **更新 README**:在对应分类表中新增一条记录。
 9. **撰写设计文档** `.agents/docs/<YYYY-MM-DD>-add-<lib>-plan.md`,记录形态判定、镜像、feature 评估、验证结论
    与注意事项。
 10. **本地 lint**:在本地复现 `validate.yml` 的 lint 检查(语法、必填字段、无前导 v、镜像表校验)。详见
     [docs/repository-and-schema.md](../../../docs/repository-and-schema.md)。
 11. **提交变更**:由 `main` 切出新分支,依次 commit、push、开 PR(不应直接推送 `main`)。PR 描述应载明形态、镜像、
     feature 与验证结论。
-12. **确认 CI 通过**:`detect` 应仅选中本库对应的 example(`smoke-full-linux` 与 `smoke-portable` 显示 `skipping`),
-    `smoke-examples (<short>)` 通过,`mirror-cn-reachable` 覆盖新增 CN url。合并由维护者执行。
+12. **确认 CI 通过**:`workspace (linux|macos|windows)` 的选择性成员测试应仅选中本库对应成员并通过
+    (日志中 `selected members: <member>`),`lint`(含 `mcpp xpkg parse`)与 `mirror-cn-reachable`
+    覆盖新增描述符与 CN url。合并由维护者执行。
 
 ## feature 机制
 
@@ -113,13 +119,13 @@ root="$PWD/mcpp-$MV-linux-x86_64"
 mkdir -p ~/.mcpp/registry && cp -a "$root/registry/." ~/.mcpp/registry/
 export MCPP="$root/bin/mcpp"
 export MCPP_VENDORED_XLINGS="$root/registry/bin/xlings"
-export MCPP_INDEX_MIRROR=GLOBAL          # CI example 使用 GLOBAL;CN 由 mirror-cn-reachable 单独校验
-MCPP="$MCPP" bash tests/run_example.sh <short>
+export MCPP_INDEX_MIRROR=GLOBAL          # CI 使用 GLOBAL;CN 由 mirror-cn-reachable 单独校验
+rm -rf "tests/examples/<member>/target" "tests/examples/<member>/.mcpp"   # 冷验证:自干净状态走完整管线
+"$MCPP" test -p <member>
 ```
 
-- 输出末尾应包含断言行与 `OK: <short>`。
-- `run_example.sh` 会执行 `rm -rf target .mcpp`,自干净状态走完整管线(fetch、generate、compile、link、run)。
-- 如需查看头文件或源码,解包结果位于 `tests/examples/<short>/.mcpp/.xlings/data/xpkgs/<idx>-x-<name>/<ver>/<wrap>/`。
+- 输出末尾应为 `test result ok`(测试二进制退出码非 0 即失败)。
+- 如需查看头文件或源码,解包结果位于 `tests/examples/<member>/.mcpp/.xlings/data/xpkgs/<idx>-x-<name>/<ver>/<wrap>/`。
 
 ## 常见错误与规避
 

README.md

@@ -48,8 +48,8 @@ mcpp self config --mirror CN   # 切换至国内镜像,默认使用 GLOBAL 上
 ```text
 参考本仓 skill `.agents/skills/add-mcpp-index-package`,将 <库名 / 仓库URL> @<版本> 收录进 mcpp-index:
 判定形态;配置 CN 镜像(无 mcpp-res 权限时使用 plain-string 上游 url);编写 pkgs/<首字母>/<包名>.lua;
-添加 tests/examples/<库>/ 最小工程;使用与 CI 同版本的 mcpp 本地执行 `mcpp build && run` 进行验证;
-更新 README 与在线索引;提交 PR 并确认 CI 通过。
+添加 tests/examples/<库>/ 测试工程并登记为 workspace 成员;使用与 CI 同版本的 mcpp 本地执行
+`mcpp test -p <成员>` 进行验证;更新 README 与在线索引;提交 PR 并确认 CI 通过。
 ```
 
 细节文档位于 [`docs/`](docs/),供人工与 agent 共同使用:
@@ -59,7 +59,9 @@ mcpp self config --mirror CN   # 切换至国内镜像,默认使用 GLOBAL 上
 - [仓库结构与 schema 与 CI](docs/repository-and-schema.md):字段速查、选跑机制与本地 lint。
 - 字段规范见 [mcpp 扩展字段文档](https://github.com/mcpp-community/mcpp/blob/main/docs/04-schema-xpkg-extension.md)。
 
-> 提交 PR 后,`validate` 自动执行 lint 并按改动库选跑示例;合并后,`deploy-site` 将其发布至在线浏览站。
+> 提交 PR 后,`validate` 自动执行 lint 并按改动库选跑对应 workspace 成员(整个测试面是一个 mcpp
+> workspace,公开模块包 `imgui`/`ffmpeg`/`opencv`/`tinyhttps` 也是普通成员——各成员经 `[indices]`
+> 把所消费命名空间重定向到 checkout,零 shell 驱动);合并后,`deploy-site` 将其发布至在线浏览站。
 
 ## 相关链接
 

docs/repository-and-schema.md

@@ -4,18 +4,22 @@
 
 ```
 pkgs/<x>/<name>.lua          描述符。<x> 取完整包名首字母(compat.* → c,nlohmann.json → n,imgui → i)
-tests/examples/<short>/      每库最小工程(<short> 为包名去除 compat./mcpplibs. 前缀后的结果)
-  mcpp.toml                  [indices].compat = { path = "../../.." }
-  src/main.{cpp,c}
-tests/run_example.sh <short> 通用 runner:rm -rf target .mcpp,继而 mcpp build 与 mcpp run
-tests/smoke_compat_*.sh      旧全量 smoke,已降级为 nightly/dispatch 保障
+mcpp.toml                    workspace 清单(members 列表)
+tests/examples/<member>/     每库测试工程(workspace 成员;<member> 为包名去前缀,模块包为
+  mcpp.toml                  <name>-module)。恰好一条 [indices] <ns> = { path = "../../.." }
+                             把所消费命名空间重定向到本 checkout(模块包用 default,
+                             mcpp ≥ 0.0.97;单条是硬约束——xlings 多项目级 repo 静默失败,
+                             mcpp#238,修复后再做根级集中化)。依赖按平台自门控
+                             ([target.'cfg(...)'])
+  tests/*.cpp                行为断言(独立 main,退出码非 0 即失败)
 tests/check_mirror_urls.lua  lint:GLOBAL+CN 表完整性,以及 CN 指向 mcpp-res
 tests/list_cn_urls.lua       抽取 CN url,供 mirror-cn-reachable 使用
 README.md                    索引说明与贡献入口
-.github/workflows/validate.yml   CI:lint / mirror-cn-reachable / detect / smoke-examples / smoke-full-linux / smoke-portable
+.github/workflows/validate.yml   CI:lint / mirror-cn-reachable / workspace(3 平台矩阵)
 .agents/docs/<date>-*.md     设计文档惯例
 docs/                        贡献者参考文档(本目录)
 tools/gtc                    gitcode CLI,见 cn-mirror.md
+tools/compat-ffmpeg/ 等      compat 大包的描述符再生成流水线
 .xpkgindex.json              站点配置(标题、链接、install 模板),通常无需改动
 ```
 
@@ -72,13 +76,16 @@ mcpp 跑 `xpkg parse`(strict:未知键即失败),所以需要更新文法/键的
 - 触发条件:PR(改动 `pkgs/**/*.lua`、`tests/**`、`README.md` 或本 workflow)、push 至 main、nightly cron、手动触发。
 - `env.MCPP_VERSION` 为全部 job 使用的 mcpp 版本,本地验证应与之对齐。
 - `lint`(始终运行):lua 语法 `loadfile(f,'t')`;须含 `spec=`/`name=`/`xpm=`;禁止前导 v 版本;执行
-  `check_mirror_urls.lua`。
+  `check_mirror_urls.lua`;再用 CI pin 的 mcpp 对每个描述符跑 `mcpp xpkg parse`(strict,未知键即失败)。
 - `mirror-cn-reachable`(始终运行):逐个 `curl` CN url,均须返回 200。
-- `detect`:PR 时由 `git diff` 取改动的 `pkgs/*/*.lua`,对 basename 去除 `compat.`,若存在
-  `tests/examples/<short>/` 则仅运行该示例;改动 scaffolding/CI 或无对应 example 时,执行全量回归。
-- `smoke-examples (<short>)`:在干净 runner 上运行 `run_example.sh`,`MCPP_INDEX_MIRROR=GLOBAL`。
-- `smoke-full-linux` 与 `smoke-portable`(mac/win):全量回归,仅在 push、nightly、dispatch 或脚手架变更时运行;
-  常规单库 PR 应显示 `skipping`。
+- `workspace (linux|macos|windows)`:整个测试面就是一个 mcpp workspace,**唯一的构建/运行通道**——
+  没有任何 shell 驱动的例外(公开模块包 imgui/ffmpeg/opencv/tinyhttps 也是普通成员,经成员级
+  `[indices] default = { path = "../../.." }` 从 checkout 解析,mcpp ≥ 0.0.97)。
+  - 选择性成员测试:PR 时由 `git diff` 将改动文件映射到受影响成员
+    (`pkgs/<x>/<lib>.lua` → mcpp.toml 引用 `<lib>` 的成员;`tests/examples/<m>/**` → 成员 `<m>`),
+    仅 `mcpp test -p <member>` 这些成员;workflow 本身、workspace 清单非成员部分、`tools/` 等
+    全局性改动 → `mcpp test --workspace` 全量。push/nightly/dispatch 恒为全量。
+  - `~/.mcpp/registry` 缓存携带工具链与已构建的 compat 包,重复运行增量很快。
 
 ## 本地 lint 复现(等价于 CI lint job)