@ccoalm/ccl-skills 0.1.0

package/dist/assets/marketplace/plugins/ccl-skills/skills/multi-perspective-research/references/public-disclosure-channels.md

@@ -0,0 +1,97 @@
+# 组织调研场景：披露渠道的起点清单与三个数据陷阱
+
+配套 `SKILL.md` 的覆盖预检与硬规则。
+
+**本文只覆盖“具体组织”这一种调研场景，不是 `multi-perspective-research` 的能力边界。** 主题、政策、技术、市场等其他场景必须按自己的载重主张枚举来源类别，不能照抄本文清单。
+
+**本文不定义状态、不定义闭合、不裁决穷尽。** 闭合与降级全部归 `SKILL.md` 的覆盖矩阵——那里问的是"哪条载重主张 × 哪类证据"。本文只提供两样东西：一份**用来防"没想到"的组织披露渠道起点清单**，和三个**已实证的数据处理陷阱**。
+
+这条边界是刻意的：在这里另立任何一套状态词或闭合语义，都会与覆盖矩阵冲突，并给"表填满了所以走完了"提供借口。
+
+## 一、渠道起点清单
+
+调研对象是一个具体组织时，四类证据（用户线索 / 一手官方 / 独立外部 / 反例）问的是"证据是什么种类"，不问"渠道有没有走过"。只查官网与年报**可以正当关闭"一手/官方"那一格**，而信息量更大的几类渠道一次都没被想到。
+
+失效形状：调研者连续多轮自行宣布"公开渠道挖完了"，每次被追问后都命中一个**此前没想到的渠道类别**（不是同类里的又一个来源）。这不是勤奋问题——是类别维度从未被过一遍。
+
+**这是起点清单，不是全集**——按常见的营利性组织与常见辖区归纳。别的类别是否存在取决于对象类型与所涉辖区：公共采购与补贴披露、游说与政治献金披露、非营利组织税务申报、行业许可与检查记录、集体协商与工会申报、信息公开申请、认证与审计报告、调查报道等。**走完这 10 类不构成任何终局判断。**
+
+| # | 渠道类别 | 典型内容 | 判断要点 |
+|---|---|---|---|
+| 1 | **组织自述** | 官网、年报、董事会材料、招聘站、技术博客、官方讲座 | 最易得也最易止步于此；招聘站与官方讲座常含组织结构的一手信号 |
+| 2 | **证券／投资者法定披露** | 年报、股东会材料、法定高管申报、结构化财务标签接口 | 标签定义与申报口径经过核验时，结构化接口比 PDF 更便于跨年跨主体对比 |
+| 3 | **强制披露制度** | 达阈值的集中裁员通知、用工构成报送、薪酬差距报告、环境与安全报送 | **最常被漏掉的一类**；法定义务，覆盖面与可比性都强；部分由组织自愿公开在自己站点上 |
+| 4 | **劳动力与移民监管数据** | 用工许可申报、职位分级与薪酬报送、批准量逐年统计 | 常有逐案明细；只覆盖受该制度约束的人群 |
+| 5 | **他国／多辖区法定登记** | 各辖区工商登记的法定账目；**部分**辖区对达到规模阈值的主体要求披露平均员工数与人力成本明细 | 命中时是拿到单一法人实体人数与成本构成的少数途径；义务、门槛、可得性与费用逐辖区差异极大 |
+| 6 | **知识产权与技术产出** | 专利、论文、标准提案 | 部分接口需密钥或注册；实体消歧质量是前提（见陷阱三） |
+| 7 | **归档／历史快照** | 网页归档站 | 用途限于**官方已下架、已替换或需要历史版本**；某源仍在提供该文件、只是拒绝自动访问时**不得改走归档规避**——那属于绕过访问限制（见 `public-data-acquisition.md` §1.2、§1.4） |
+| 8 | **开放数据门户** | 各级政府的数据集接口 | 常有无需密钥的查询接口；用目录检索比逐个猜网址高效 |
+| 9 | **司法与监管处置** | 诉讼卷宗、处罚决定、监管问询 | 命中率低但单条信息量可能很大；通常需要确切案号 |
+| 10 | **第三方聚合与社区** | 商业数据库、点评与社区平台 | 按 provenance、方法透明度、覆盖与偏差、可复算性分级——不按"第三方"身份一律封顶 |
+
+**一份材料只算一个证据来源。** 同一份年报可以同时被"组织自述"和"证券法定披露"引用，从归档站取回也不额外增加一个来源——记录时写清底层 artifact、发布者与取得路径，别让一份材料在渠道维度上刷出四个命中，制造广度与独立性的错觉。
+
+**先说清目标是谁。** 单一法人、合并集团、品牌或业务单元、还是某个网络？依据与截至日期是什么？依据不足时只能称"有界的工作口径"，且人数与比例类结论不得进入承重结论——把品牌、母集团、单一法人与历史子组织混成"这家组织"，之后每张表都可能形式正确而 estimand 从一开始就被偷换。
+
+**写事实，不写"穷尽"。** 不要对渠道集合使用"穷尽 / 挖完了 / 已无更多"，也不要写"查过了确实没有"——后者读起来像不存在证明，实际只能支持**"在所声明的检索边界内未命中"**。改成逐条写：走了哪些类别、各自的检索边界（登记机关或数据库、用了哪些别名、时间窗、有没有翻页或结果上限）、哪些没走、哪些走不动及原因。这两种写法的差别可检验：前者不可证伪，后者逐条可核。
+
+**清单走完不等于没得找——沿五个维度把已走过的类别再实例化一遍。** 上面回答"有哪些类别"，这一条回答"类别走完之后怎么继续产生候选"。实证的增量几乎都来自**在同一类别上换一个维度取值**，而不是发明第 11 类：
+
+| 维度 | 换法 | 为什么有增量 |
+|---|---|---|
+| **辖区** | 同一类披露义务换一个国家／州／省 | 义务、阈值、登记机关逐辖区不同；类别 5 尤其如此，命中时是拿到**单一法人口径**的少数途径 |
+| **制度** | 同一主题往往受多个独立法定报送覆盖 | 集中裁员通知、用工构成报送、薪酬差距报告各是独立制度，口径与阈值互不相同，不能互相替代 |
+| **载体** | 同一份材料换可机读程度 | 结构化接口 > 带文本层的 PDF > 仅图像的 PDF；**仅图像的 PDF 自行 OCR 仍是正当取回**，与绕过访问限制无关（后者见 `public-data-acquisition.md` §1.2） |
+| **实体主键** | 同一组织在不同数据集里主键不同 | 法人登记号、雇主名、专利权人、学术机构标识、招聘主体——换主键即换数据集，但换完必须重做实体消歧（见陷阱三） |
+| **聚合层** | 母体拿不到就分别取子实体再配平；反之亦然 | 阈值型披露常只对子实体生效；聚合方向变了，配平与边界核对要重做（见陷阱一） |
+
+两条约束：**每换一个维度取值都是一次新的检索边界**，按上一条逐条记录，不得合并成一句"已扩展检索"；沿维度轮换取回的新源**同样要过 §二 的三个陷阱**，不因为"是补充来源"而降低处理标准。
+
+**启动时点是自己认为"没得找了"的那一刻，不是被追问之后。** 本节开头记的失效形状——连续多轮自行宣布挖完了，每次被追问后都命中一个此前没想到的类别——反过来说明方法本身有效、只是不自启动。把"我认为挖完了"当作本轮换的触发条件，而不是结论。
+
+## 二、三个数据陷阱
+
+三者的共同点：**即使 `grounded` 的全部条件都满足**（来源链接、实际取回的摘录、会话内可回查的调用位置），错误依然存在——它发生在**取到之后的处理**。
+
+### 陷阱一：把配平当成验证
+
+法定报表里，一行常同时含分项与该行合计；把整行数字全加一遍就得到 2 倍值。
+
+**失效形状**：把某报表每行的分项与行合计一起求和，得出的"某国用工人数"比该组织**全球总人数**还大。反向也发生过：一个看不懂来源的数被判为"解析噪声"丢弃，实际它是几个子项的合计。
+
+**配平只证明"我没读错这张表"，不是独立验证**——分项与合计常出自同一口径、同一生成程序，必然相等。而且它只在存在**与派生值同 estimand、同范围、同期间、同单位，且分类互斥可加**的控制总数时才可比；不满足这些条件的"总数"拿来配平，会逼人把非互斥分类硬加总，或错误否决一个本来合法的派生值。
+
+配平通过之后仍要单独看：单位、期间、法人与地理范围、唯一键重复、缺失分区是真零还是未填报。
+
+配不上时先查解析、单位、舍入、版本——**有来源格式或模式证据支持的解析修正是正当的**（括号负数、千分位、脚注单位），留下改前改后的差异与依据。被禁止的是**为了得到目标数字而反复调参**。仍不能解释就如实报告冲突，不让它以确定值的形态进入结论。
+
+### 陷阱二：跨期不可比被当成"数据坏了"
+
+**失效形状**：跨不同性质的申报期直接相加比较，得出"该字段填报不一致、不可用"的结论；实际是干净的周期性，只需同期比同期。
+
+**形式同口径不等于可比**：并购或重组改变了法人范围，同财季对同财季仍是假趋势。至少看一眼期间、字段定义、单位、币种与价格基准、地理与法人范围、覆盖阈值、修订版本、测量方法。
+
+有官方 bridge／映射表时要**评估**它能不能用（覆盖是否完整、是否多对多、误差能否量化、是不是为监管过渡而非本分析设计），不能无理由忽略；评估后拒绝 harmonize 是正当结论。
+
+一个字段塌到接近零而另一字段同期跳升，**提出编码迁移这个待验证假设**——但合并成一个语义桶要凭字段定义、申报说明、版本变更记录或正式映射。**数值上"两列之和跨期守恒"只是信号不是依据**：语义不同的两列一降一升而其和恰好稳定完全可能。缺语义依据时并列报告。
+
+期间长度不同时按测量语义选同期值、单位暴露率、年化值或占比——"改用占比"不普遍正确（存量类分母、强季节性流量、分子分母覆盖期不同时，占比一样不可比）。
+
+口径修复要落成**后续步骤会复用的东西**（本次分析里可复算的转换、查询或版本化映射即可，不要求改共享规则）；只写进交付物脚注时，同一次调研的后半段会再犯一次。
+
+### 陷阱三：信任数据集自带的实体消歧
+
+聚合型数据集会把名称相近的组织或同名个人合并成同一个实体条目。用实体 ID 过滤会一次性引入整批无关记录。
+
+**失效形状**：某学术库的组织条目挂着与该组织业务完全无关领域的文献；某作者条目挂着上千个机构、数千篇论文（同名个人被合并）。
+
+- 用实体 ID 过滤前先抽样核对原始字段（原始署名串、原始机构名）。**抽样框、选择方法与接受条件要在看结果之前定**，否则"样本量 1"也形式合规；便利样本只能用来发现错误，不能授权总体聚合
+- 两个方向都查：**merge**（不同对象被并成一个）与 **split**（同一对象被拆成多个），带上别名与历史沿革
+- **只报精确率是最常见的假安全**：挑几条明显正确的记录能得到 100% 精确率，而目标实体可能被拆成多个 ID、旧名或子组织，召回只有一半，样本全对而总量系统性低估
+- **召回率的分母不好来**：只在该 ID 已返回的记录里抽样看不到没被返回的那些；两条"互不依赖"路径取并集只能给出**观测到的唯一对象数**，它是总体规模下界而不是召回率下界——召回是比例，分母未知时可以任意接近 0，而且两条入口还可能共享同一上游索引或同样的语言、时间、地域、收录偏差。拿不出有完备性依据的候选全集或 gold set 时记"召回未知"，**不存在可报告的召回下界，也不要发布总体规模与比例**
+- 换一条实现路径重算，若两条路径读的是同一份预处理结果，那只是**一致性复算**，共同上游的错误发现不了
+- 消歧不可靠时不得用该数据估算原总体的比率；人工逐条确认过的子集仍可支持**重新定义 estimand 并明示选择偏差后**的窄结论，但要写清它估的已不是原总体
+
+## 三、走过而无产出的渠道要留下原因
+
+写清是哪一种：**在声明的检索边界内未命中**、**取到但不足以关闭**（只有标题摘要、正文删节、字段范围不足、版本冲突、真实性无法核验）、**被挡住**（需要密钥或账号、接口下线、被反爬拦截）、还是**没走**。只写"无产出"会把后三种伪装成第一种。这四种都不是闭合判断——按 `SKILL.md` 的覆盖矩阵去裁决哪条主张还差什么。

package/dist/assets/marketplace/plugins/ccl-skills/skills/multi-perspective-research/references/research-prompts.md

@@ -0,0 +1,66 @@
+# 多视角调研提示词模板
+
+四步模板。`[TOPIC]` 为研究主题，`[ROLE]` 为用户角色/立场。既可由 agent 自己按步执行（推荐，可结合真实检索），也可作为独立 prompt 交给任意 LLM——**独立 prompt 模式下没有可回查的工具调用记录，全部发现强制 `ungrounded`，产出一律按探索性草稿交付**。执行时遵守 SKILL.md 的证据落地纪律：模拟视角输出是假设级证据，载重结论须真实核验。
+
+## 1. 多视角枚举
+
+```text
+我要研究 [TOPIC]。请用 5 个不同的专家视角分别分析：
+
+1. 实践者——每天与 [TOPIC] 打交道的人。学院派漏掉了什么？哪些现实约束总被忽略？
+2. 研究者——多年研究该领域。同行评审证据实际说明什么？证据在哪里与流行认知矛盾？
+3. 怀疑者——认为主流观点有误。最强的反方论证是什么？支持者刻意回避了什么证据？
+4. 利益追踪者——追踪资金与激励。谁从当前叙事获利？哪些激励在塑造研究/舆论方向？
+5. 历史对照者——见过类似规律。存在哪些历史先例？那些先例的走向能告诉我们什么？
+
+每个视角输出三项：
+- 核心立场（2 句话）
+- 支撑该立场的最强证据
+- 只有这个视角会告诉我、其他视角不会说的一件事
+```
+
+视角可按主题替换（监管者、终端用户、竞争者、安全研究员等），标准是：替换后的视角必须会给出与其余视角**不同**的答案。
+
+## 2. 矛盾图
+
+```text
+基于以上 5 个视角，绘制矛盾图：
+
+1. 哪些视角的主张直接冲突？逐条列出冲突双方的具体主张。
+2. 哪个视角证据最强？哪个最弱？为什么？
+3. 哪一个问题被回答后，能化解最大的矛盾？
+4. 所有视角都同意什么？（连对手都确认的，大概率为真。）
+5. 没有任何视角提及什么？（整个领域的盲区，常是最有价值的发现。）
+```
+
+## 3. 合成简报
+
+```text
+把 5 个视角与矛盾图合成为一份研究简报：
+
+1. 一段话总结：向只有 60 秒、但需要 nuance 而非标题的决策者汇报 [TOPIC]。（轻量模式：不得用"向决策者汇报"框架，改为探索性概览，且开头标注"未分析：跳过矛盾图/自评"）
+2. 关键发现（≤5 条；仅四步全跑时按可靠性排序，轻量模式给不排序列表）：每条标注哪些视角支持、哪些视角质疑。
+3. 隐藏关联：一个只有合看全部视角才会显现的非显然联系。
+4. （仅四步全跑时）可操作建议：基于全部证据，[ROLE] 应该做出什么具体的不同行动？
+5. 前沿问题：哪一个问题被回答后，会改变我们对 [TOPIC] 的整体理解？
+```
+
+轻量模式（只跑 1+3）使用本模板时**删去第 4 项**，第 2 项改为不排序、且**不带"支持/质疑视角"标注**的发现列表（排序与视角冲突标注都依赖第 2 步矛盾图），并在产出开头带"未分析（跳过矛盾图/自评），探索性草稿"标注：可操作建议、载重结论、可靠性排序、视角冲突标注只允许出现在跑完第 2、4 步并附待核验清单的完整交付里。
+
+## 4. 自评（同行评审）
+
+```text
+以严格审稿人的标准评审上面这份简报：
+
+1. 给每条关键发现打置信度（高/中/低），并说明依据的证据强度。
+2. 整份简报最弱的环节在哪里？
+3. 是否有某个视角被过度代表、拉偏了结论？
+4. 是否漏了第 6 个应该纳入的视角？是谁？
+5. 哪些结论目前只有推理支撑、没有可核验来源？逐条列出，作为人工核验清单。
+```
+
+## 使用提示
+
+- 快速了解：只跑 1 + 3，产出只作探索性概览（附 grounded/ungrounded 标注），不得输出可操作建议、载重结论或可靠性排序。支撑重要决策：四步全跑，且第 4 步列出的"待核验清单"必须在行动前用真实检索/一手来源关闭。
+- agent 有检索能力时，第 1 步每个视角先做真实检索再作答，把结论从 `ungrounded` 升级为 `grounded`。
+- 方法出处与完整实现参见 `github.com/stanford-oval/storm`（MIT）——作为方法论参考；若要实际运行该第三方系统（它会发起检索与 LLM 调用），走团队常规的第三方代码审查/沙箱授权路径，不要默认直接执行。

package/dist/assets/marketplace/plugins/ccl-skills/skills/multi-perspective-research/scripts/AGENTS.md

@@ -0,0 +1,32 @@
+# skills/multi-perspective-research/scripts Agent Contract
+
+This directory contains deterministic regression checks for executable recipes
+embedded in the multi-perspective research references. The repository-wide
+contract remains authoritative: [root `AGENTS.md`](../../../AGENTS.md). This
+file only narrows that contract; it does not relax its safety, authority,
+owner-routing, worktree-isolation, or validation gates.
+
+Rules:
+
+- Execute snippets extracted from the owning reference instead of maintaining a
+  second implementation that can drift from the published recipe.
+- Keep the inline `MANIFEST` in
+  `test-public-data-acquisition-recipes.sh` exhaustive: every runnable code
+  block must be marked as executed or explicitly exempt with a concrete
+  environment or integration reason, and an unregistered block must fail the
+  check.
+- Use synthetic fixtures and local stubs. Do not require live network access,
+  production data, credentials, or private endpoints.
+- Preserve fail-closed assertions for acquisition, parsing, completeness, and
+  cleanup behavior. A failed check must return non-zero.
+- Keep shell checks portable across supported macOS and Linux environments.
+  Use trap-based cleanup on normal, failed, and catchable interrupted exits.
+
+Validation, run from the repository root:
+
+- `bash skills/multi-perspective-research/scripts/test-public-data-acquisition-recipes.sh`
+- `shellcheck -S warning skills/multi-perspective-research/scripts/test-public-data-acquisition-recipes.sh`
+- `bash skills/product-rd-workflow/scripts/check-agent-contract-coverage.sh --repo . --enforce`
+
+If `shellcheck` is unavailable, report that validation as inconclusive rather
+than passing.

package/dist/assets/marketplace/plugins/ccl-skills/skills/multi-perspective-research/scripts/test-public-data-acquisition-recipes.sh

@@ -0,0 +1,379 @@
+#!/usr/bin/env bash
+# 回归测试：把 references/public-data-acquisition.md 里的可运行片段**原样抽出来**跑。
+#
+# 为什么按原样抽而不是照着意思重写：这份 reference 的价值在于读者会照抄它。
+# 如果测试跑的是另一份等价实现，文档退化了测试也不会红。
+#
+# 不联网：curl 被替换成本地 stub，所以可以在 CI 里跑。
+set -uo pipefail
+
+HERE=$(cd "$(dirname "$0")" && pwd)
+DOC="$HERE/../references/public-data-acquisition.md"
+[ -r "$DOC" ] || { echo "找不到 $DOC" >&2; exit 1; }
+
+WORK=$(mktemp -d) || { echo "无法创建测试临时目录" >&2; exit 1; }
+trap 'rm -rf -- "$WORK"' EXIT
+trap 'exit 129' HUP
+trap 'exit 130' INT
+trap 'exit 143' TERM
+pass=0; fail=0
+ok()   { pass=$((pass+1)); printf '  ok   %s\n' "$1"; }
+bad()  { fail=$((fail+1)); printf '  FAIL %s — %s\n' "$1" "${2:-}"; }
+check(){ if [ "$2" = "$3" ]; then ok "$1"; else bad "$1" "期望 $3，实得 $2"; fi; }
+
+# ---- 块清单：每个可运行片段必须**显式**声明是被执行还是被豁免 ----
+# 硬编码 sh[0]/py[0] 的老做法会让新加的可运行块悄悄不被覆盖（评审 P2）。
+# 这里按内容指纹认块；出现未登记的块就红，逼作者要么覆盖它、要么写明为何不可执行。
+cat > "$WORK/check-block-manifest.py" <<'PY'
+import re,sys
+doc,work=sys.argv[1],sys.argv[2]
+t=open(doc,encoding='utf-8').read()
+# 枚举所有 fence，而不是只枚举认识的语言；新标签/无标签块也必须进入处置。
+blocks=[(m.group(1).strip(),m.group(2))
+        for m in re.finditer(r'^```([^\n]*)\n(.*?)^```[ \t]*$',t,re.S|re.M)]
+
+# 每项：(标识, 判据, 处置)。exec=本测试真的执行它；exempt=写明为何不执行。
+MANIFEST=[
+ ("fetch/accept",  lambda l,b: l=='bash'   and 'fetch()' in b,                 "exec"),
+ ("curl-size-log", lambda l,b: l=='' and 'Exceeded the maximum allowed file size' in b, "exempt: 实测命令输出，不是可执行片段"),
+ ("curl-fail-log", lambda l,b: l=='' and '<当时返回 504 的接口>' in b,          "exempt: 实测命令输出，不是可执行片段"),
+ ("cdx",           lambda l,b: l=='bash'   and 'cdx/search/cdx' in b,          "exempt: 需要真实归档站，属联网集成"),
+ ("catalog",       lambda l,b: l=='bash'   and 'api/catalog/v1' in b and 'while' not in b, "exempt: 需要真实目录接口，属联网集成"),
+ ("paging",        lambda l,b: l=='bash'   and 'OFF=' in b and 'while' in b,   "exec"),
+ ("pdf-probe",     lambda l,b: l=='bash'   and 'pdftotext' in b,               "exempt: 依赖 poppler，非本机保证"),
+ ("pdf-render",    lambda l,b: l=='bash'   and 'pdftoppm' in b,                "exempt: 依赖 poppler，非本机保证"),
+ ("alias-parse",   lambda l,b: l=='python' and 'ALIAS' in b,                   "exec"),
+ ("col-attrib",    lambda l,b: l=='python' and 'totA' in b,                    "exempt: 三行示意式恒等式，无控制流"),
+ ("ocr",           lambda l,b: l=='swift' and 'VNRecognizeTextRequest' in b,    "exempt: 需 macOS Vision + swiftc，另行手测"),
+ ("tag-fallback",  lambda l,b: l=='javascript' and 'concept(t)' in b,           "exempt: 需真实结构化接口"),
+]
+unmatched=[]
+for lang,body in blocks:
+    if not any(pred(lang,body) for _,pred,_ in MANIFEST):
+        unmatched.append((lang,body.strip().split('\n')[0][:70]))
+if unmatched:
+    print("未登记的可运行块（要么覆盖它，要么在 MANIFEST 里写明豁免理由）：")
+    for lang,head in unmatched: print(f"   [{lang}] {head}")
+    sys.exit(1)
+# 抽出要执行的块
+for name,pred,how in MANIFEST:
+    if how!="exec": continue
+    hit=[b for l,b in blocks if pred(l,b)]
+    if len(hit)!=1:
+        print(f"块 {name} 命中 {len(hit)} 个，判据需更新"); sys.exit(1)
+    ext="py" if name=="alias-parse" else "sh"
+    open(f"{work}/{name.replace('/','_')}.{ext}","w").write(hit[0])
+print(f"块清单：共 {len(blocks)} 个，执行 {sum(1 for _,_,h in MANIFEST if h=='exec')} 类，其余已登记豁免")
+PY
+python3 "$WORK/check-block-manifest.py" "$DOC" "$WORK"
+[ $? -eq 0 ] || { echo "块清单校验失败" >&2; exit 1; }
+mkdir -p "$WORK/negative-extract"
+cat > "$WORK/unregistered-block.md" <<'BAD'
+```bash
+echo "unregistered"
+```
+BAD
+if python3 "$WORK/check-block-manifest.py" "$WORK/unregistered-block.md" "$WORK/negative-extract" >/dev/null 2>&1; then
+  bad "块清单能报未登记代码块" "坏输入被放行"
+else
+  ok "块清单能报未登记代码块"
+fi
+cat > "$WORK/unknown-fence.md" <<'BAD'
+```sh
+echo "unknown language tag"
+```
+BAD
+if python3 "$WORK/check-block-manifest.py" "$WORK/unknown-fence.md" "$WORK/negative-extract" >/dev/null 2>&1; then
+  bad "块清单能报未知 fence 标签" "未知标签被忽略"
+else
+  ok "块清单能报未知 fence 标签"
+fi
+cp "$WORK/fetch_accept.sh" "$WORK/fetch.sh" 2>/dev/null || { echo "抽取 fetch 块失败" >&2; exit 1; }
+cp "$WORK/alias-parse.py" "$WORK/parse.py" 2>/dev/null || { echo "抽取 ALIAS 块失败" >&2; exit 1; }
+cp "$WORK/paging.sh" "$WORK/page.sh" 2>/dev/null || { echo "抽取分页块失败" >&2; exit 1; }
+
+echo "== 语法 =="
+if bash -n "$WORK/fetch.sh"; then ok "bash -n"; else bad "bash -n"; fi
+
+# 变量名紧跟全角标点会被 shell 吃进名字（set -u 下 unbound variable）。
+# 这类错误几乎只出现在错误分支的提示语里，手测极难碰到 → 全文静态扫。
+cat > "$WORK/check-fullwidth-var.py" <<'PY'
+import re,sys
+t=open(sys.argv[1],encoding='utf-8').read()
+hits=[]
+for blk in re.findall(r'```bash\n(.*?)```',t,re.S):
+    for line in blk.split('\n'):
+        # Bash 的 ${v#prefix} 自带 #，不能用 split('#') 粗暴截断，否则会吞掉
+        # 同一行后面的真问题。只略过整行注释；行内误报宁可要求显式 ${var}。
+        if line.lstrip().startswith('#'):
+            continue
+        if re.search(r'\$[A-Za-z_][A-Za-z0-9_]*(?![A-Za-z0-9_])[^\x00-\x7f]',line):
+            hits.append(f"bash: {line.strip()}")
+for h in hits: print("   "+h)
+sys.exit(1 if hits else 0)
+PY
+if python3 "$WORK/check-fullwidth-var.py" "$DOC"
+then ok "代码块里没有 \$var 紧跟全角标点"; else bad "代码块里有 \$var 紧跟全角标点（改用 \${var}）"; fi
+cat > "$WORK/fullwidth-var-bad.md" <<'BAD'
+```bash
+echo "${name#prefix}" "$mime，"
+```
+BAD
+if python3 "$WORK/check-fullwidth-var.py" "$WORK/fullwidth-var-bad.md" >/dev/null 2>&1; then
+  bad "全角标点检查器能报坏输入" "坏输入被放行"
+else
+  ok "全角标点检查器能报坏输入"
+fi
+
+# ---- curl stub：按 URL 决定行为，不出网 ----
+mkdir -p "$WORK/bin"
+cat > "$WORK/bin/curl" <<'STUB'
+#!/usr/bin/env bash
+# 只实现测试需要的部分：--version、-o <file>、URL 里的关键字决定产物
+if [ "${1:-}" = "--version" ]; then
+  echo "curl ${CURL_STUB_VERSION:-8.7.1} (test-stub)"
+  exit 0
+fi
+out=""; url=""; max_bytes=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -o) out=$2; shift 2 ;;
+    --max-filesize) max_bytes=$2; shift 2 ;;
+    http*|https*) url=$1; shift ;;
+    *) shift ;;
+  esac
+done
+[ -z "${CURL_ARGS_LOG:-}" ] || printf '%s\n' "$max_bytes" > "$CURL_ARGS_LOG"
+case "$url" in
+  *slowA*|*slowB*)
+    if [ -n "${CURL_BARRIER_DIR:-}" ]; then
+      : > "$CURL_BARRIER_DIR/ready.$$"
+      tries=0
+      while [ "$(find "$CURL_BARRIER_DIR" -name 'ready.*' -type f | wc -l | tr -d ' ')" -lt 2 ]; do
+        tries=$((tries+1))
+        [ "$tries" -lt 1000 ] || exit 70
+        sleep 0.01
+      done
+    fi
+    ;;
+esac
+case "$url" in
+  *fail500*)  echo 'curl: (22) HTTP response code said error' >&2; exit 22 ;;
+  *html*)     printf '<html><body>blocked</body></html>' > "$out" ;;
+  *empty*)    : > "$out" ;;
+  *oversize*) printf '%s\n' '[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]' > "$out" ;;
+  *slowA*)    sleep 1; printf '{"who":"A"}' > "$out" ;;
+  *slowB*)    sleep 1; printf '{"who":"B"}' > "$out" ;;
+  *)          printf '{"ok":true}' > "$out" ;;
+esac
+exit 0
+STUB
+chmod +x "$WORK/bin/curl"
+
+run_fetch() {  # 在受控 PATH 下 source 文档片段并调用 fetch
+  local log=${FETCH_LOG:-/dev/null}
+  ( export PATH="$WORK/bin:$PATH" UA="regression-test test@example.invalid"
+    [ -z "${CURL_BARRIER_DIR:-}" ] || export CURL_BARRIER_DIR
+    cd "$WORK/run" || exit 9
+    # shellcheck disable=SC1090
+    . "$WORK/fetch.sh"
+    OUT=$PWD; export OUT
+    fetch "$@"
+  ) >"$log" 2>&1
+  rc=$?
+  echo "$rc"
+}
+
+echo "== fetch 行为 =="
+rm -rf "$WORK/run"; mkdir -p "$WORK/run"
+check "正常下载返回 0"        "$(run_fetch "$WORK/run/a.json" 'https://x/data')"     0
+check "已存在则 SKIP 返回 0"  "$(run_fetch "$WORK/run/a.json" 'https://x/data')"     0
+check "curl 失败返回 1"       "$(FETCH_LOG="$WORK/curl-fail.log" run_fetch "$WORK/run/b.json" 'https://x/fail500')" 1
+check "curl 失败原因匹配"     "$(grep -Fq 'curl: (22)' "$WORK/curl-fail.log" && echo matched || echo missing)" matched
+check "curl 失败不留成品"     "$([ -e "$WORK/run/b.json" ] && echo present || echo absent)" absent
+check "curl < 8.4.0 被拒绝"   "$(FETCH_LOG="$WORK/oldcurl.log" CURL_STUB_VERSION=8.3.0 run_fetch "$WORK/run/oldcurl.json" 'https://x/data')" 1
+check "旧 curl 失败原因匹配"  "$(grep -Fq '< 8.4.0' "$WORK/oldcurl.log" && echo matched || echo missing)" matched
+check "旧 curl 不留成品"      "$([ -e "$WORK/run/oldcurl.json" ] && echo present || echo absent)" absent
+check "类型不符返回 1"        "$(FETCH_LOG="$WORK/type.log" run_fetch "$WORK/run/c.json" 'https://x/html')" 1
+check "类型不符原因匹配"      "$(grep -Fq '类型不符' "$WORK/type.log" && echo matched || echo missing)" matched
+check "类型不符不留成品"      "$([ -e "$WORK/run/c.json" ] && echo present || echo absent)" absent
+check "空响应返回 1"          "$(FETCH_LOG="$WORK/empty.log" run_fetch "$WORK/run/d.json" 'https://x/empty')" 1
+check "空响应原因匹配"        "$(grep -Fq '空响应' "$WORK/empty.log" && echo matched || echo missing)" matched
+mkdir -p "$WORK/run/adir" && : > "$WORK/run/adir/keep"
+check "目标是目录返回 2"      "$(run_fetch "$WORK/run/adir" 'https://x/data')"       2
+check "目录内容未被动"        "$([ -e "$WORK/run/adir/keep" ] && echo kept || echo GONE)" kept
+check "无 .part 残留"         "$(find "$WORK/run" -name '*.part.*' | wc -l | tr -d ' ')" 0
+
+run_fetch_smallcap() {  # 把 MAX_BYTES 压到很小，用来触发体积上限分支
+  local log=${FETCH_LOG:-/dev/null}
+  ( export PATH="$WORK/bin:$PATH" UA="regression-test test@example.invalid"
+    [ -z "${CURL_ARGS_LOG:-}" ] || export CURL_ARGS_LOG
+    cd "$WORK/run" || exit 9
+    # shellcheck disable=SC1090
+    . "$WORK/fetch.sh" >/dev/null 2>&1
+    # MAX_BYTES 被文档里的 accept() 读取，shellcheck 看不到跨 source 的使用
+    # shellcheck disable=SC2034
+    MAX_BYTES=${MAXOVERRIDE:-32}; OUT=$PWD; export OUT
+    fetch "$@"
+  ) >"$log" 2>&1
+  rc=$?
+  echo "$rc"
+}
+
+echo "== 已存在的文件也要过验收，不能因 SKIP 绕过（评审 P1）=="
+rm -rf "$WORK/run"; mkdir -p "$WORK/run"
+printf '<html>上一轮/别的工具留下的非空垃圾</html>' > "$WORK/run/stale.json"
+check "残留 HTML 被拒收(1)" "$(run_fetch "$WORK/run/stale.json" 'https://x/data')" 1
+printf '{"ok":true}' > "$WORK/run/good.json"
+check "残留合法 JSON 走 SKIP(0)" "$(run_fetch "$WORK/run/good.json" 'https://x/data')" 0
+# 已存在文件从没经过 curl --max-filesize，所以体积必须由 accept 自己查（评审 P1）
+python3 -c "open('$WORK/run/huge.json','w').write('['+'0,'*60+'0]')"
+check "超上限的残留文件被拒收(1)" "$(FETCH_LOG="$WORK/stale-size.log" MAXOVERRIDE=32 run_fetch_smallcap "$WORK/run/huge.json" 'https://x/data')" 1
+check "残留超限原因匹配" "$(grep -Fq '超过体积上限' "$WORK/stale-size.log" && echo matched || echo missing)" matched
+check "超上限的新下载被拒收(1)" "$(FETCH_LOG="$WORK/new-size.log" MAXOVERRIDE=32 run_fetch_smallcap "$WORK/run/oversize.json" 'https://x/oversize')" 1
+check "新下载超限原因匹配" "$(grep -Fq '超过体积上限' "$WORK/new-size.log" && echo matched || echo missing)" matched
+check "小上限下载返回 0" "$(CURL_ARGS_LOG="$WORK/max-bytes.log" MAXOVERRIDE=32 run_fetch_smallcap "$WORK/run/capped.json" 'https://x/data')" 0
+check "curl 与 accept 使用同一上限" "$(cat "$WORK/max-bytes.log")" 32
+
+cat > "$WORK/bin/ln" <<'S'
+#!/usr/bin/env bash
+exit 1
+S
+chmod +x "$WORK/bin/ln"
+check "硬链接不受支持时下载前失败" "$(FETCH_LOG="$WORK/no-hardlink.log" run_fetch "$WORK/run/no-hardlink.json" 'https://x/data')" 1
+check "硬链接探针失败原因匹配" "$(grep -Fq '成品目录不支持硬链接' "$WORK/no-hardlink.log" && echo matched || echo missing)" matched
+rm -f "$WORK/bin/ln"
+
+echo "== accept 的外部命令失败必须 fail-closed（评审 P1）=="
+rm -rf "$WORK/run"; mkdir -p "$WORK/run" "$WORK/nofile"
+cat > "$WORK/nofile/file" <<'S'
+#!/usr/bin/env bash
+exit 127          # 冒充 file 不可用/执行失败
+S
+chmod +x "$WORK/nofile/file"; cp "$WORK/bin/curl" "$WORK/nofile/curl"
+rc=$( export PATH="$WORK/nofile:/usr/bin:/bin" UA="t t@example.invalid"
+      cd "$WORK/run" || exit 9; . "$WORK/fetch.sh" >/dev/null 2>&1; OUT=$PWD; export OUT
+      fetch "$WORK/run/e.json" 'https://x/data' >/dev/null 2>&1; echo $? )
+check "file 失败时返回非 0" "$([ "$rc" != 0 ] && echo nonzero || echo zero)" nonzero
+check "file 失败时不发布"   "$([ -e "$WORK/run/e.json" ] && echo present || echo absent)" absent
+
+echo "== 并发写同一目标、内容不同，不得静默覆盖（评审 P1）=="
+rm -rf "$WORK/run" "$WORK/barrier"; mkdir -p "$WORK/run" "$WORK/barrier"
+( CURL_BARRIER_DIR="$WORK/barrier" run_fetch "$WORK/run/race.json" 'https://x/slowA' > "$WORK/rcA" ) &
+( CURL_BARRIER_DIR="$WORK/barrier" run_fetch "$WORK/run/race.json" 'https://x/slowB' > "$WORK/rcB" ) &
+wait
+rcA=$(cat "$WORK/rcA"); rcB=$(cat "$WORK/rcB")
+winners=0; [ "$rcA" = 0 ] && winners=$((winners+1)); [ "$rcB" = 0 ] && winners=$((winners+1))
+check "恰好一个调用发布成功" "$winners" 1
+losers=0; for r in "$rcA" "$rcB"; do [ "$r" = 3 ] && losers=$((losers+1)); done
+check "另一个报并发冲突(3)"  "$losers" 1
+check "成品是完整的单方内容" "$(python3 -c "
+import json,sys
+d=json.load(open('$WORK/run/race.json'))
+print('single' if d.get('who') in ('A','B') and len(d)==1 else 'MIXED')" 2>/dev/null || echo BROKEN)" single
+check "并发后无 .part 残留"  "$(find "$WORK/run" -name '*.part.*' | wc -l | tr -d ' ')" 0
+
+echo "== 分页循环：解析失败必须非零终止，不得空转（评审 P1/P2）=="
+# 只跑 sh[0] 会漏掉这一块——分页块里 N=$(...) 失败时 OFF 不前进，会反复读同一页。
+cat > "$WORK/pagerun.sh" <<'SH'
+set -euo pipefail
+UA="t t@example.invalid"; OUT=$PWD; export UA OUT
+DOMAIN=example.invalid; ID=ds; PAGE=2
+# shellcheck disable=SC1090
+. "$WORKDIR/fetch.sh" >/dev/null 2>&1
+fetch() {
+  case "$1" in
+    *-p0.json) printf '%s' "$BADBODY" > "$1" ;;
+    *) printf '%s' "${NEXTBODY:-$BADBODY}" > "$1" ;;
+  esac
+  FETCHED=1
+  if [ "${CONFLICT_ONCE:-0}" = 1 ] && [ ! -e "$WORKDIR/conflict-returned" ]; then
+    : > "$WORKDIR/conflict-returned"
+    return 3
+  fi
+  return 0
+}   # 绕开网络，直接给受控分页内容
+# shellcheck disable=SC1090
+. "$WORKDIR/page.sh"
+SH
+run_pager() {
+  python3 - "$WORK/pagerun.sh" <<'PY'
+import subprocess,sys
+try:
+    p=subprocess.run(["bash",sys.argv[1]],stdout=subprocess.DEVNULL,
+                     stderr=subprocess.STDOUT,timeout=20)
+    print(p.returncode)
+except subprocess.TimeoutExpired:
+    print(124)
+PY
+}
+rm -rf "$WORK/pg"; mkdir -p "$WORK/pg"
+rc=$( cd "$WORK/pg" || exit 9
+      export WORKDIR="$WORK" BADBODY='{ this is not json'
+      run_pager )
+check "JSON 损坏时非零终止" "$([ "$rc" != 0 ] && [ "$rc" != 124 ] && echo nonzero || echo "bad:$rc")" nonzero
+rm -rf "$WORK/pg2"; mkdir -p "$WORK/pg2"
+rc2=$( cd "$WORK/pg2" || exit 9
+       export WORKDIR="$WORK" BADBODY='[]'
+       run_pager )
+check "空页正常收尾(0)" "$rc2" 0
+rm -rf "$WORK/pg-full"; mkdir -p "$WORK/pg-full"
+rc_full=$( cd "$WORK/pg-full" || exit 9
+           export WORKDIR="$WORK" BADBODY='[1,2]' NEXTBODY='[]'
+           run_pager )
+check "set -e 下满页后继续到空页" "$rc_full" 0
+rm -f "$WORK/conflict-returned"
+rm -rf "$WORK/pg-conflict"; mkdir -p "$WORK/pg-conflict"
+rc_conflict=$( cd "$WORK/pg-conflict" || exit 9
+               export WORKDIR="$WORK" BADBODY='[]' CONFLICT_ONCE=1
+               run_pager )
+check "并发已发布返回 3 时继续处理该页" "$rc_conflict" 0
+rm -rf "$WORK/pg3"; mkdir -p "$WORK/pg3"
+rc3=$( cd "$WORK/pg3" || exit 9
+       export WORKDIR="$WORK" BADBODY='{"error":"not an array page"}'
+       run_pager )
+check "JSON 对象不能冒充数组页" "$([ "$rc3" != 0 ] && [ "$rc3" != 124 ] && echo nonzero || echo "bad:$rc3")" nonzero
+
+echo "== ALIAS 解析必须 fail-closed =="
+# 直接判命令，不用 $?——间接读退出码正是本 reference §3.6 点名的坑
+if python3 - "$WORK/parse.py" "$WORK" <<'PY'
+import re,sys,openpyxl,os
+code=open(sys.argv[1],encoding='utf-8').read()
+def variant(alias_literal):
+    c=re.sub(r'ALIAS = \{.*?\n\}', alias_literal, code, count=1, flags=re.S)
+    assert c!=code, "ALIAS 字面量替换失败——文档结构变了，请更新本测试"
+    return c.replace('SHEET_NAME','"DATA"').replace('...','pass')
+two   = variant('ALIAS = {"A":["New Name","Old Name"],"B":["BEE","B_OLD"]}')
+share = variant('ALIAS = {"person":["NAME"],"organization":["NAME"]}')
+tmp=os.path.join(sys.argv[2],"alias-fixtures")
+os.mkdir(tmp)
+def wb(name,hdr,rows=((1,2),)):
+    w=openpyxl.Workbook(); s=w.active; s.title="DATA"
+    if hdr is not None: s.append(hdr)
+    for r in rows: s.append(list(r))
+    p=os.path.join(tmp,name+".xlsx"); w.save(p); return p
+cases=[
+ ("新名(大小写/空白不同)命中", two,   wb("c1",["New   name","BEE"]),      "ok"),
+ ("旧名走别名命中",           two,   wb("c2",["Old Name","B_OLD"]),      "ok"),
+ ("新旧候选同时命中",         two,   wb("c3",["New Name","Old Name","BEE"]), "closed"),
+ ("候选全不在表头",           two,   wb("c4",["ZZZ","BEE"]),             "closed"),
+ ("表头重复",                 two,   wb("c5",["New Name","New Name","BEE"]), "closed"),
+ ("空表无表头行",             two,   wb("c6",None,rows=()),              "closed"),
+ ("两语义绑同一物理列",       share, wb("c7",["NAME","OTHER"]),          "closed"),
+]
+bad=0
+for tag,src,path,want in cases:
+    ns={'openpyxl':openpyxl,'path':path}
+    try:
+        exec(compile(src,'<doc>','exec'),ns); got="ok"
+    except SystemExit: got="closed"
+    except Exception as e: got=f"UNEXPECTED {type(e).__name__}: {e}"
+    if got==want: print(f"  ok   {tag}")
+    else: print(f"  FAIL {tag} — 期望 {want}，实得 {got}"); bad+=1
+sys.exit(1 if bad else 0)
+PY
+then ok "ALIAS 七种输入"; else bad "ALIAS 七种输入"; fi
+
+printf '\n通过 %d，失败 %d\n' "$pass" "$fail"
+[ "$fail" -eq 0 ] || exit 1
+echo "public_data_acquisition_recipes_ok"