dsh-crwu-workbench 0.0.10

package/skills/crwu/crwu-audit-external-data/references/01-connector-access.md

@@ -0,0 +1,116 @@
+# references/01 · 取数路径发现与调用规程（crwu-audit-external-data）
+
+> 本文件只规定**怎么找到并调用**同花顺 iFinD 的取数入口，以及找不到时怎么办。
+> 本技能不启用万得。要核哪些数据项、每项的口径要求与结论档位由知识库
+> `06-规则库/M-外部数据核验/01-模块-外部数据核验`（表 A / 表 B / 表 C）规定，本文件不复制；
+> 库内表 D 为取数失败与降级口径（单源），双源复核不适用（见 §6）。
+
+## 1 唯一数据源 = 同花顺 iFinD，但入口随宿主而异
+
+同花顺 iFinD 在不同宿主以不同形态提供，**不要用一个宿主的事实推断另一个宿主**：
+
+| 宿主 | 取数路径 | 形态与调用 | 凭据归属 |
+| --- | --- | --- | --- |
+| WorkBuddy | 宿主内置连接器 | MCP 服务，连接器 id `ifind-mcp`（服务端授权）；会话可能直接暴露其 MCP 工具，否则读宿主连接器声明 | 宿主托管 |
+| DeepSeek Harness | 结构化 Tool `crwu_audit_ifind_query` | 由 Host 执行固定 iFinD MCP HTTP 协议；`operation=list_tools` 查权益内工具清单、`operation=query` 取数 | Host 按环境清单声明的固定位置读取（模型不可提交、不可读取、不可见） |
+
+- 两条宿主入口取的是**同一上游 iFinD 服务**，取回值可视为同一数据源；进入 `sources[]` 时统一写
+  `同花顺 iFinD`，本次实际走哪条路径写进 `note`。
+- DeepSeek Harness 侧**不再**调用任何第三方技能脚本：取数入口是宿主的结构化 Tool
+  `crwu_audit_ifind_query`（注册、审批、超时、取消、脱敏都在 DSH 的工具链里）。
+  服务地址与 `serverType` 映射是 Host 的内部固定表，模型只提交 `operation` / `serverType` /
+  `toolName` / `params`。**不得**搜索技能根（`~/.agents`、`~/.dsh`、`~/.codebuddy`、`~/.claude` 等）、
+  **不得**执行任何第三方技能自带的调用脚本、**不得**在第三方技能目录写临时脚本、
+  **不得**读取任何第三方技能的凭据配置文件。
+- 禁止把万得列为数据源，也禁止声称已做双源复核（本环境无万得）。
+
+## 2 发现顺序（逐级降级，不得跳级）
+
+| 级 | 动作 | 判据 |
+| --- | --- | --- |
+| L1 | 使用**当前会话已暴露的取数入口** | WorkBuddy：会话已暴露同花顺 iFinD 的 MCP 工具；DeepSeek Harness：`crwu_audit_ifind_query` 对当前 Agent 可见 |
+| L2 | 读**宿主声明**（仅 WorkBuddy；L1 未暴露时） | 见 §3（WorkBuddy 连接器声明）；命令：`<WorkBuddy 宿主可用的绝对 Python 路径> scripts/connector_probe.py --format json`。**DeepSeek Harness 无此级**——入口就是结构化 Tool 的可见性，不读宿主声明、也不运行本探测脚本 |
+| L3 | 入口存在但**未启用 / 未认证** | 按 §5 降级并在交付件声明 |
+| L4 | 完全不存在 | 按 §5 降级并在交付件声明 |
+
+**逐宿主判定，不得跨宿主推断。** WorkBuddy：L1 未暴露**不等于**数据源不可用——必须继续走 L2 读宿主声明，
+不得直接判"无数据源"。DeepSeek Harness：只有 L1（结构化 Tool 对当前 Agent 的可见性），
+没有 L2，也没有任何可读的声明文件。
+
+## 3 WorkBuddy：宿主连接器声明位置
+
+默认根 = 环境变量 `CRWU_CONNECTOR_ROOT`；未设置时 = `~/.workbuddy`（WorkBuddy 连接器宿主目录）。
+**本仓不提供这些连接器，也不随本技能安装**——它们是宿主侧外部工具。
+
+| 位置（相对根） | 内容 |
+| --- | --- |
+| `mcp.json` | 宿主 MCP 服务清单（`mcpServers`：连接器 id → 端点 / 启用标记） |
+| `connectors/*/mcp.json` | 按账号态分目录的连接器声明 |
+| `connectors/*/connector-states.json`、`connector-states.v3.json` | 启用状态（`enabled` 列表、`userDisabled` 映射、`everConnected`）与凭据引用（`headerOverrides` 的**键名**） |
+| `connectors-marketplace/.codebuddy-connector/connectors.json` | 连接器目录（id / 中英文名 / 是否需要授权），**不作为"已声明"依据** |
+
+已知连接器标识：同花顺 iFinD = `ifind-mcp`（服务端授权，宿主托管，无需本技能处理凭据）。
+
+## 4 DeepSeek Harness：结构化 Tool `crwu_audit_ifind_query`
+
+DeepSeek Harness 没有 WorkBuddy 连接器目录，**也不允许脚本例外**。同花顺 iFinD 取数统一走宿主注册的
+结构化 Tool `crwu_audit_ifind_query`：
+
+- **入口可见性**：`operation` 的「列工具」取值能返回工具清单即视为入口可用（枚举字面量见 Tool schema，本文件不复述）；Tool 不在本 Agent 的可见集里
+  → 按 §5 降级（记 capability gap 并写交付声明）。
+- **参数**：只有 `operation`（列工具 / 查询两个取值）、`serverType`（固定八元：`stock` / `fund` /
+  `edb` / `news` / `bond` / `global_stock` / `index` / `future`）、`toolName`（查询时必填）、
+  `params`（JSON 对象）。**没有** URL / token / 脚本路径 / 沙箱模式这类字段。
+- **凭据**：由 Host 从环境清单声明的固定位置读取；本技能**不读取、不输出、不落盘**任何令牌，
+  也**不**读取任何第三方技能的凭据配置文件。
+- **`toolName` 校验**：Host 会先用 MCP「列工具」方法的真实返回校验 `toolName`，不在清单里的名字不会被发出。
+- **失败语义**：未授权读凭据 → `policy`；缺令牌 → `capability-gap`；HTTP / 协议错误 → `infrastructure`；
+  服务端 JSON-RPC 错误 → `cli`；取消 → `cancelled`。一律按 §5 降级，**不得静默跳过**、
+  也不得把能力缺口写成被审件缺陷。
+- **禁止**（自包含安全边界）：搜索任何技能根、执行任何第三方技能自带的调用脚本、
+  在第三方技能目录写临时脚本、读取任何第三方技能的配置文件、用 `subprocess` / `child_process` 起进程。
+
+## 5 兜底：入口不可用时怎么办
+
+1. **不得静默跳过**，也不得事后补写结论。
+2. 按库内降级口径降级：命中关键参数 / 高风险的条目降为"单源 + 请说明"；其余记未检查项与能力缺口。
+   本环境无万得副源，**所有条目一律单源**，不得声称已复核。
+3. **在交付 HTML 的《外部数据核验》区显式声明**（字段 `externalDataVerification.sources[]`，
+   数据源统一写 `同花顺 iFinD`）：
+
+   | 情形 | `configured` | `authenticated` | 必须在 `note` 写明 |
+   | --- | --- | --- | --- |
+   | 所有宿主入口都不存在 | `false` | `false` | 未配置同花顺 iFinD 取数入口；相关条目未经外部数据核验 |
+   | 入口存在但未启用 | `false` | `false` | 取数入口未启用；相关条目未经外部数据核验 |
+   | 入口启用但未完成授权 | `true` | `false` | 取数入口未认证；相关条目未经外部数据核验 |
+   | 可用 | `true` | `true` | 本次取数路径（WorkBuddy 连接器 / 结构化 Tool `crwu_audit_ifind_query`）与取数时点、口径 |
+
+4. 声明措辞统一为："本次未配置 / 未认证 同花顺 iFinD，相关条目未经外部数据核验。"
+5. 降级不影响其他检查项与轴：外部数据核验失败不得短路方法判断、披露检查或表格勾稽。
+
+## 6 调用与留痕契约
+
+每次取数必须记录并回执：
+
+```yaml
+data_point:
+  metric: 【数据项名称】            # 与知识库表 B 的数据项一致
+  metric_key: EXT_【…】            # 可选，与库内稳定键一致
+  base_date: 【报告基准日】         # 全部取数的锚点
+  as_of_date: 【本次取数时点】       # 与基准日不同的必须说明
+  source: 同花顺 iFinD
+  access_path: 宿主连接器 / 结构化 Tool crwu_audit_ifind_query
+  query_params:                    # 口径参数，按库内表 B 要求的必填项逐项填
+    term / window / frequency / benchmark / adjustment / unit / …
+  value: 【取回值】
+  source_note: 【可选】取数路径（宿主连接器 / 结构化 Tool）或口径变更说明
+  snapshot_digest: 【快照摘要】      # 对取回内容做规范化摘要，供事后核验
+```
+
+- **基准日纪律**：`query_params` 的区间与窗口一律由 `base_date` 推导；禁止"截止最新 / 最近 N 周"这类
+  以取数时点为准的滚动窗口。
+- **单源纪律**：本环境不启用万得，数据源一律为同花顺 iFinD，**不得声称双源复核**；
+  取数路径与口径变更在 `source_note` 如实登记。
+- **凭据纪律**：只读连接器声明的**键名与启用状态**；不读取、不输出、不落盘任何令牌、Authorization 头
+  或含 token 的 URL。WorkBuddy 侧的 `scripts/connector_probe.py` 已按此实现（URL 只输出主机名）。
+- **快照纪律**：外部数据快照按本次审核工作目录落盘并登记摘要，供交付层引用；不写入知识库缓存。

package/skills/crwu/crwu-audit-external-data/references/02-verification-workflow.md

@@ -0,0 +1,78 @@
+# 02 · 核验流程与交付字段（crwu-audit-external-data）
+
+> 本文件是 external-data **前置适用性门禁、基准日锚定三档、核验步骤 0–7、口径与结论边界、
+> `externalDataVerification` 字段契约与详细禁止事项**的唯一落点。入口 `SKILL.md` 只保留调用
+> 门禁、输入三项、单源声明、宿主入口安全边界与必读导航。
+>
+> - **取数入口发现与调用**以 `01-connector-access.md` 为准；本文件不复制宿主连接器声明位置、
+>   Tool schema 或凭据规则。
+> - **要核哪些数据项、每项的口径要求与结论档位**仍以本次经 `crwu-dws` 实时下载的知识库正文为准。
+> - 唯一外部数据源仍为**同花顺 iFinD**，不启用万得、不声称双源复核。
+>
+> **导航**：§1 前置适用性门禁 → §2 核验步骤 0–7（含基准日锚定三档） → §3 交付层字段 → §4 禁止事项
+
+## 1. 前置适用性门禁
+
+前置适用性门禁：先按知识库表 A 核对业务线、资产线、方法线。三条未同时成立时，直接回执
+`applicability.status=not_applicable`、原因和表 A 依据；不探测连接器、不填写不可用声明，也不形成未检查项或 capability gap。
+只有三条同时成立时才执行以下取数流程，并回执 `applicability.status=required`。
+
+## 2. 核验步骤（0–7）
+
+0. **基准日锚定（先做）**：从 `route_profile.record_context` 取 `base_date` 与其状态，作为本次全部取数的
+   时点锚。**所有区间与窗口由基准日推导**（如"基准日前 2 年"）；禁止"截止最新/最近 N 周"这类
+   以取数时点为准的滚动窗口——否则同一项目不同日期复跑结果不同，比对与回归都不成立。
+   按基准日状态**分三档**处理（不得整线停载）：
+
+   | 基准日状态 | 取数行为 |
+   | --- | --- |
+   | 唯一确定 | 正常取数；全部时点参数由该基准日推导 |
+   | 多候选（ROUTE003 挂起，存在 2 个及以上候选日） | **条件性取数**：对每个候选日分别取数（或取覆盖全部候选日的区间段）。候选日结论一致 → 可出结论并注明"已在候选基准日下逐一核验，结论一致"；结论不一致 → 出"请说明"的**条件性结论**（注明取决于基准日确认），**不得判"不符合"**，转人工 |
+   | 缺失 / 不可解析 | 只核验**不依赖基准日**的数据项（公司属性事实、报告期已固定的财报数、政策文件现行有效性）；依赖时点的项记"未检查"并写明原因 |
+
+   本档只**消费** router 已给出的 `base_date` / `base_date_status`，**不自行判定 ROUTE 冲突**
+   （判定权在 `06-overlay-classification.md`）；也**不因基准日挂起而整线停载**——按
+   `08-union-dispatch-rules.md`，不依赖冲突字段的规则仍须执行。
+1. **抽取**：真实读取报告、评估说明与测算明细表，抽取"报告引用了哪些外部数据"——数据项、报告值、
+   报告位置、上下文（用途、方法章节）。**只针对报告实际引用的外部数据**，不凭空扩展核验范围。
+2. **定源**：按库内表 B（数据项触及表）与表 C（组合映射表）确定**要核哪些数据项、每项的口径要求**。
+   本环境唯一数据源为同花顺 iFinD，**不启用万得**：数据源一律按同花顺 iFinD 取数，
+   并如实留痕取数路径与口径变更。
+   表内未覆盖的数据项按库内 §9 员工补录机制登记后仍按默认规则核验，不跳过。
+3. **取数入口发现**：按 `references/01-connector-access.md` 的顺序逐宿主判定，**不得跨宿主推断**——
+   WorkBuddy 先看会话是否已暴露 iFinD MCP 工具，未暴露才读宿主连接器声明
+   （`<WorkBuddy 宿主可用的绝对 Python 路径> scripts/connector_probe.py --format json`，只读、不读凭据值）；
+   DeepSeek Harness 不读任何声明、也不运行 `connector_probe.py`，只看结构化 Tool
+   `crwu_audit_ifind_query` 对当前 Agent 是否可见，可见后以一次真实的 `operation=list_tools`
+   成功返回为准。
+4. **取数**：对每个数据项按报告声明的口径（期限、窗口、频率、基准、复权、单位）取数；
+   报告**未声明口径**的参数，只做披露检查（输出"请说明"），不取数比对。
+5. **口径标准化后比对**：把外部取值与报告值归一到同一口径再比；**口径无法统一时禁止作数值判定**，
+   只记录口径差异。事实型数据可判"不符合"；模型型数据只出"请说明"。
+6. **输出**：逐项 EXT 意见（结构以库内 §8 意见条目格式为准），并产出交付层
+   `externalDataVerification`（供 HTML《外部数据核验》区渲染）。
+7. **留痕**：每条核验记录保留库内 §6 要求的全部字段（数据项、数值、来源、取数时点、口径、单位、参数）。
+
+## 3. 交付层字段（供 HTML 体现）
+
+本技能向编排层回执 `externalDataVerification`（写入 AuditResult），结构见
+`crwu-audit/references/11-html-delivery-spec.md` 的《外部数据核验》区定义：
+
+- `applicability`：必填，含 `status`（`required` / `not_applicable`）、`reason` 与知识库表 A `basis`；
+- `baseDate`：本次基准日（全部核验的锚点时点）；
+- `sources[]`：数据源的可用性事实（`source` / `configured` / `authenticated` / `note`）——
+  本技能只申报**同花顺 iFinD** 一条（两条取数路径合并为同一数据源），并在 `note` 里写明本次走的是
+  哪条路径；**仅在 `applicability.status=required` 且取数路径不可用时**显式声明，并给出“相关条目未经外部数据核验”的措辞；
+- `checks[]`：逐项核验（数据项、报告值、各源取值与取数时点口径、`deviationAgainst`（与本项目报告值
+  出入较大的数据源）、`decision`、报告证据位置、说明）；
+- 只要有 `checks` 就**逐项写明正确与不正确**：判定为"符合"的条目同样入表，不得只列问题。
+
+## 4. 禁止事项
+
+1. 禁止用取数时点的滚动窗口代替基准日推导区间；
+2. 禁止在口径不一致时判"数据错误"，或仅凭外部取值与报告值的差异否定报告参数；
+3. 禁止未留痕取数口径即出数值判定；
+4. 禁止把外部数据用作规则依据（外部数据只进报告证据，不进 `rule_source`）；
+5. 禁止下方法适用性、参数合理性等专业判断（交方法轴技能与人工）；
+6. 禁止混淆“不适用”与“能力不可用”：不适用时不得探测或告警；需要核验但取数路径缺失/未认证时不得静默跳过，必须按库内降级口径降级并在交付件中显式声明；
+7. 禁止声称已做双源复核，或把万得列为本次数据源（本环境不启用万得）。

package/skills/crwu/crwu-audit-external-data/scripts/connector_probe.py

@@ -0,0 +1,374 @@
+#!/usr/bin/env python3
+"""外部数据源只读探测：同花顺 iFinD 的 WorkBuddy 宿主连接器（crwu-audit-external-data）。
+
+背景：本技能的唯一外部数据源是同花顺 iFinD，但不同宿主的取数入口不同——
+
+- **WorkBuddy**：宿主把同花顺 iFinD 做成内置连接器（MCP，连接器 id `ifind-mcp`，服务端授权）；
+  会话可能直接暴露对应 MCP 工具；未暴露时读宿主连接器声明。
+- **DeepSeek Harness**：取数入口是宿主的结构化 Tool `crwu_audit_ifind_query`，对当前 Agent 可见
+  即可用。它是宿主能力，**不表现为技能目录**，因此 Harness 侧没有可读的声明文件：本脚本不为它
+  搜索任何技能根，也不判断任何技能目录。
+
+所以本脚本只在会话未直接暴露取数入口时，读 WorkBuddy 宿主连接器的**声明**，回答"同花顺 iFinD
+是否存在、是否启用、有没有可核实的授权证据"。万得不在本技能范围内，不探测、不作为数据源。
+
+只读纪律：
+- 只读连接器声明的**键名与启用状态**；
+- 不读取、不输出任何令牌 / Authorization 值；URL 只输出主机名（去掉路径与查询串）；
+- 不发起任何网络请求。
+
+判定口径（重要）：
+- **只有宿主声明（`mcp.json` / `connectors/*/mcp.json`）才算"已声明"**；连接器市场目录
+  （`connectors-marketplace/.../connectors.json`）列出全部可安装连接器，**不作为已声明依据**。
+- 连接器声明只给出**预检**结论，**不断言凭据有效**；真正的判据是**运行时调用是否返回授权错误**。
+- 若运行时调用失败，按知识库表 D 降级并在交付件中声明（见 references/01-connector-access.md §4）。
+
+宿主侧外部工具说明：WorkBuddy 连接器由宿主提供，本仓库不提供、不随本技能安装。
+
+用法：
+  python3 scripts/connector_probe.py [--root <dir>] [--format json|text]
+
+退出码：0 = WorkBuddy 宿主连接器预检可用；2 = 未发现可用入口（仍输出 JSON 说明）。
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+SCHEMA = "crwu.external-data.connector-probe.v3"
+DEFAULT_ROOT_ENV = "CRWU_CONNECTOR_ROOT"
+DEFAULT_ROOT = "~/.workbuddy"
+
+IFIND_LABEL = "同花顺 iFinD"
+# 只在宿主已声明的连接器里匹配；id 命中权重高于名称。
+IFIND_ID_KEYS = ("ifind",)
+IFIND_NAME_KEYS = ("ifind", "同花顺")
+TOKEN_AUTH_MODES = ("token", "oauth", "apikey")
+
+_SECRET_KEY = re.compile(r"(?i)(authorization|token|secret|password|cookie|api[_-]?key)")
+# 宿主 mcp.json 用带命名空间前缀的 id（connector:ifind-mcp），状态文件用裸 id（ifind-mcp）——
+# 必须归一化，否则会误判为"未启用"。
+_ID_PREFIX = re.compile(r"^(?:connector|custom-mcp):")
+_URL_HOST = re.compile(r"^[a-z][a-z0-9+.-]*://([^/?#]+)")
+_TOKEN_QUERY = re.compile(r"(?i)([?&](?:token|access_token|api_key|apikey|key)=)[^&\s]+")
+CATALOG_REL = "connectors-marketplace/.codebuddy-connector/connectors.json"
+
+
+def normalize_id(name) -> str:
+    """去掉宿主的命名空间前缀，使 `connector:ifind-mcp` 与 `ifind-mcp` 归一到同一连接器。"""
+    return _ID_PREFIX.sub("", str(name or "").strip())
+
+
+def declaration_scope(rel: str) -> str:
+    """声明文件所属作用域：`connectors/<账号态>/…` → `connectors/<账号态>`；顶层文件 → ``。"""
+    parts = str(rel).split("/")
+    if len(parts) >= 2 and parts[0] == "connectors":
+        return parts[0] + "/" + parts[1]
+    return ""
+
+
+def redact_url(value: str) -> str:
+    """只保留主机名；去掉路径、查询串与任何 token。"""
+    if not isinstance(value, str) or not value:
+        return ""
+    match = _URL_HOST.match(value.strip())
+    host = match.group(1) if match else ""
+    host = host.rsplit("@", 1)[-1]  # 去掉 user:pass@
+    return host.split(":", 1)[0]
+
+
+def redact_text(value: str) -> str:
+    return _TOKEN_QUERY.sub(r"\1***", str(value))
+
+
+def load_json(path: Path):
+    try:
+        with path.open(encoding="utf-8") as handle:
+            return json.load(handle)
+    except (OSError, ValueError):
+        return None
+
+
+def _blank_entry(connector_id: str) -> dict:
+    return {
+        "connectorId": connector_id,
+        "displayName": connector_id,
+        "declaredAs": [],
+        "declaredIn": [],
+        "hostDeclared": False,
+        "catalogListed": False,
+        "endpointHost": "",
+        "disabledScopes": {},
+        "enabled": None,
+        "userDisabled": None,
+        "everConnected": None,
+        "authMode": None,
+        "hasStoredAuthorization": False,
+    }
+
+
+def collect(root: Path):
+    """返回 (connectors, declarations, active_scope)。只读键名与状态，不读取任何凭据值。
+
+    active_scope = 提供 `enabled` 列表的那个账号态目录（优先 connector-states.v3.json）；
+    只有该作用域的 disabled / enabled 事实参与判定，避免多账号态互相覆盖。
+    """
+    connectors: dict[str, dict] = {}
+    declarations: list[str] = []
+    active_scope = ""
+
+    def entry_for(connector_id: str) -> dict:
+        return connectors.setdefault(connector_id, _blank_entry(connector_id))
+
+    def note_declaration(connector_id, rel, raw):
+        entry = entry_for(normalize_id(connector_id))
+        entry["hostDeclared"] = True
+        if str(connector_id) not in entry["declaredAs"]:
+            entry["declaredAs"].append(str(connector_id))
+        if rel not in entry["declaredIn"]:
+            entry["declaredIn"].append(rel)
+        if isinstance(raw, dict):
+            url = raw.get("url") or raw.get("endpoint") or ""
+            if url:
+                entry["endpointHost"] = redact_url(url)
+            if isinstance(raw.get("disabled"), bool):
+                # disabled 是**账号态作用域**内的事实：connectors/<态>/mcp.json 与顶层 mcp.json 分开记，
+                # 否则另一账号态的 disabled=true 会覆盖当前态。
+                entry["disabledScopes"][declaration_scope(rel)] = raw["disabled"]
+            for key in raw:
+                if _SECRET_KEY.search(str(key)):
+                    entry["hasStoredAuthorization"] = True
+
+    # 1) 宿主 MCP 清单（顶层）
+    top = root / "mcp.json"
+    data = load_json(top)
+    if isinstance(data, dict) and isinstance(data.get("mcpServers"), dict):
+        declarations.append("mcp.json")
+        for name, raw in data["mcpServers"].items():
+            note_declaration(str(name), "mcp.json", raw)
+
+    # 2) 按账号态分目录的声明与状态
+    connectors_dir = root / "connectors"
+    if connectors_dir.is_dir():
+        for child in sorted(p for p in connectors_dir.iterdir() if p.is_dir()):
+            manifest = child / "mcp.json"
+            data = load_json(manifest)
+            if isinstance(data, dict) and isinstance(data.get("mcpServers"), dict):
+                rel = str(manifest.relative_to(root))
+                declarations.append(rel)
+                for name, raw in data["mcpServers"].items():
+                    note_declaration(str(name), rel, raw)
+            for state_name in ("connector-states.v3.json", "connector-states.json"):
+                state_path = child / state_name
+                state = load_json(state_path)
+                if not isinstance(state, dict):
+                    continue
+                rel = str(state_path.relative_to(root))
+                if rel not in declarations:
+                    declarations.append(rel)
+                enabled_list = state.get("enabled")
+                if active_scope == "" and isinstance(enabled_list, list):
+                    # 当前生效账号态 = 提供 enabled 列表的那个目录；只认第一个（v3 优先）。
+                    active_scope = declaration_scope(rel)
+                user_disabled = state.get("userDisabled") if isinstance(state.get("userDisabled"), dict) else {}
+                ever_list = state.get("everConnected") if isinstance(state.get("everConnected"), list) else []
+                overrides = state.get("headerOverrides") if isinstance(state.get("headerOverrides"), dict) else {}
+                names = {
+                    normalize_id(item)
+                    for item in list(connectors)
+                    + list(enabled_list or [])
+                    + list(user_disabled)
+                    + list(overrides)
+                    + list(ever_list)
+                }
+                for name in names:
+                    entry = entry_for(name)
+                    if isinstance(enabled_list, list):
+                        entry["enabled"] = name in enabled_list
+                    elif name in user_disabled:
+                        entry["enabled"] = not bool(user_disabled.get(name))
+                    if name in user_disabled:
+                        entry["userDisabled"] = bool(user_disabled.get(name))
+                    if ever_list:
+                        entry["everConnected"] = name in ever_list
+                    if name in overrides:
+                        entry["hasStoredAuthorization"] = True
+
+    # 3) 连接器市场目录（仅补名称与授权形态，不作为"已声明"依据）
+    catalog = load_json(root / CATALOG_REL)
+    if catalog is not None:
+        declarations.append(CATALOG_REL)
+        items = catalog.get("connectors") if isinstance(catalog, dict) else catalog
+        if isinstance(items, list):
+            for item in items:
+                if not isinstance(item, dict):
+                    continue
+                cid = str(item.get("id") or "")
+                if not cid:
+                    continue
+                entry = entry_for(cid)
+                entry["catalogListed"] = True
+                if CATALOG_REL not in entry["declaredIn"]:
+                    entry["declaredIn"].append(CATALOG_REL)
+                entry["displayName"] = str(item.get("name_zh") or item.get("name") or entry["displayName"])
+                if item.get("auth_mode"):
+                    entry["authMode"] = str(item["auth_mode"])
+
+    for entry in connectors.values():
+        if not entry.get("displayName"):
+            entry["displayName"] = entry["connectorId"]
+        entry["authEvidence"] = _auth_evidence(entry)
+    return list(connectors.values()), declarations, active_scope
+
+
+def _auth_evidence(entry) -> str:
+    if entry.get("hasStoredAuthorization"):
+        return "stored_authorization"
+    if (entry.get("authMode") or "").lower() == "server-side":
+        return "server_side"
+    if entry.get("everConnected"):
+        return "ever_connected"
+    return "none"
+
+
+def match_target(connectors, id_keys, name_keys):
+    """只在宿主已声明的连接器里匹配；目录条目仅作后备名称信息。"""
+    best, best_score, best_declared = None, 0, False
+    for entry in connectors:
+        cid = (entry.get("connectorId") or "").lower()
+        name = (entry.get("displayName") or "").lower()
+        score = 0
+        for key in id_keys:
+            if key in cid:
+                score += 3
+        for key in name_keys:
+            if key.lower() in name:
+                score += 2
+        if score == 0:
+            continue
+        declared = bool(entry.get("hostDeclared"))
+        if (declared, score) > (best_declared, best_score):
+            best, best_score, best_declared = entry, score, declared
+    return best
+
+
+def scoped_disabled(entry, active_scope: str):
+    """取当前账号态作用域的 disabled 事实；当前态没有该键时退回顶层 mcp.json。"""
+    scopes = entry.get("disabledScopes") or {}
+    if active_scope and active_scope in scopes:
+        return scopes[active_scope]
+    return scopes.get("")
+
+
+def classify_connector(entry, active_scope: str = ""):
+    """由宿主声明事实推连接器状态；不断言凭据有效性（见模块 docstring 判定口径）。"""
+    if entry is None:
+        return {"state": "not_declared", "reason": "宿主未声明同花顺 iFinD 连接器"}
+    if not entry.get("hostDeclared"):
+        return {
+            "state": "not_declared",
+            "reason": "同花顺 iFinD 仅出现在连接器市场目录中，宿主未声明该连接器",
+        }
+    if (
+        entry.get("userDisabled") is True
+        or entry.get("enabled") is False
+        or scoped_disabled(entry, active_scope) is True
+    ):
+        return {"state": "declared_disabled", "reason": "宿主已声明同花顺 iFinD 连接器但未启用"}
+    evidence = entry.get("authEvidence")
+    if (entry.get("authMode") or "").lower() in TOKEN_AUTH_MODES and evidence == "none":
+        return {
+            "state": "likely_unauthenticated",
+            "reason": "已声明且启用，但未见授权证据且从未连接成功；需在宿主侧完成授权",
+        }
+    return {
+        "state": "available",
+        "reason": "已声明且启用" + ("（授权证据：%s）" % evidence if evidence != "none" else ""),
+    }
+
+
+def probe(root: Path) -> dict:
+    """探测 WorkBuddy 宿主连接器声明。只接连接器根——不接收、也不推导任何技能根。"""
+    root_exists = root.is_dir()
+    if root_exists:
+        connectors, declarations, active_scope = collect(root)
+        entry = match_target(connectors, IFIND_ID_KEYS, IFIND_NAME_KEYS)
+        verdict = classify_connector(entry, active_scope)
+    else:
+        connectors, declarations, active_scope = [], [], ""
+        entry = None
+        verdict = {"state": "not_declared", "reason": "宿主连接器根目录不存在"}
+
+    target = {
+        "label": IFIND_LABEL,
+        "state": verdict["state"],
+        "reason": verdict["reason"],
+        "accessPath": "host_connector" if verdict["state"] == "available" else "",
+        "connectorId": entry.get("connectorId") if entry else None,
+        "displayName": entry.get("displayName") if entry else None,
+        "enabled": entry.get("enabled") if entry else None,
+        "userDisabled": entry.get("userDisabled") if entry else None,
+        "everConnected": entry.get("everConnected") if entry else None,
+        "authMode": entry.get("authMode") if entry else None,
+        "authEvidence": entry.get("authEvidence") if entry else None,
+        "endpointHost": entry.get("endpointHost") if entry else None,
+        "declaredIn": entry.get("declaredIn") if entry else [],
+        "connectorVerdict": verdict,
+    }
+
+    notes = []
+    if not root_exists:
+        notes.append("宿主连接器根目录不存在：未从宿主侧发现同花顺 iFinD 连接器")
+    return {
+        "schema": SCHEMA,
+        "root": str(root),
+        "rootExists": root_exists,
+        "activeStateScope": active_scope,
+        "declarations": declarations,
+        "connectors": connectors,
+        "targets": {"ifind": target},
+        "notes": notes,
+    }
+
+
+def render_text(result: dict) -> str:
+    lines = ["外部数据源探测（只读）· 同花顺 iFinD", "宿主连接器根：" + redact_text(result["root"])]
+    if result.get("rootExists"):
+        lines.append("声明文件：" + ("、".join(redact_text(d) for d in result["declarations"]) or "无"))
+    else:
+        lines.append("声明文件：无（宿主连接器根目录不存在）")
+    info = result["targets"]["ifind"]
+    lines.append("")
+    lines.append("状态：%s（取数路径：%s）" % (info.get("state") or "", info.get("accessPath") or "无可用路径"))
+    lines.append("说明：%s" % (info.get("reason") or ""))
+    for note in result.get("notes") or []:
+        lines.append("· " + note)
+    lines.append("提示：预检结论只作可用性提示；最终以运行时调用结果为准，失败时按表 D 降级并在交付件中声明。")
+    return "\n".join(lines)
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(description="同花顺 iFinD 取数路径只读探测（不读取凭据值）")
+    parser.add_argument(
+        "--root",
+        default=os.environ.get(DEFAULT_ROOT_ENV) or DEFAULT_ROOT,
+        help="宿主连接器根目录（默认 $%s 或 %s）" % (DEFAULT_ROOT_ENV, DEFAULT_ROOT),
+    )
+    parser.add_argument("--format", choices=("json", "text"), default="json")
+    args = parser.parse_args(argv)
+
+    root = Path(os.path.expanduser(args.root))
+    result = probe(root)
+    if args.format == "text":
+        print(render_text(result))
+    else:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0 if result["targets"]["ifind"]["state"] == "available" else 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())