@v587d/capital-generation 2.8.3 → 2.9.0

package/lib/retriever-config.js

@@ -0,0 +1,36 @@
+/** web_retriever configuration surface: types, defaults, and consumer-side default filling.
+ * Kept free of Cordis imports so role entries can reuse it without cycling through `index.js`. */
+import { LOCAL_FETCH_CLIENT_VERSION } from './web-retriever/local-fetch.js';
+/** Sole default source for both the schema and `resolveLocalFetchConfig()`.
+ * timeoutMs 30000 matches dsh-web-fetch-http; 15s misreads slow proxy failover as TIMEOUT.
+ * maxContentChars applies to raw HTML before markdown conversion, so size it for HTML.
+ * userAgent is a product token: a bare version looks like a crawler to WAFs. */
+export const LOCAL_FETCH_DEFAULTS = {
+    enabled: true,
+    timeoutMs: 30_000,
+    maxBytes: 524_288,
+    maxContentChars: 100_000,
+    maxRedirects: 5,
+    userAgent: '@v587d/capital-generation',
+};
+/** Empty endpoint/model defer to `src/ocr/client.ts`; pollBudgetMs 0 defers to its DEFAULT_WAIT_BUDGET_MS. */
+export const PADDLE_OCR_DEFAULTS = {
+    endpoint: '',
+    credentialRef: 'PADDLE_OCR_TOKEN',
+    model: '',
+    pollBudgetMs: 0,
+};
+/** Consumers fill defaults themselves: `apply()` can receive a raw object that never passed the schema. */
+export function resolveLocalFetchConfig(config) {
+    const source = config ?? {};
+    // UA tri-state: unset → product default; empty string → plugin version; explicit value → as-is.
+    const userAgent = source.userAgent ?? LOCAL_FETCH_DEFAULTS.userAgent;
+    return {
+        enabled: source.enabled !== false,
+        timeoutMs: source.timeoutMs ?? LOCAL_FETCH_DEFAULTS.timeoutMs,
+        maxBytes: source.maxBytes ?? LOCAL_FETCH_DEFAULTS.maxBytes,
+        maxContentChars: source.maxContentChars ?? LOCAL_FETCH_DEFAULTS.maxContentChars,
+        maxRedirects: source.maxRedirects ?? LOCAL_FETCH_DEFAULTS.maxRedirects,
+        userAgent: userAgent || LOCAL_FETCH_CLIENT_VERSION,
+    };
+}

package/lib/retriever-runtime.d.ts

@@ -0,0 +1,31 @@
+import { type WindClient } from './web-retriever/wind-client.js';
+import { type PaddleOcrClient } from './ocr/client.js';
+import { WebRetriever, type LocalFetcherLike } from './web-retriever/retriever.js';
+import { type LocalFetchConfig, type RetrieverConfig } from './retriever-config.js';
+interface CredentialContext {
+    get(name: string): unknown;
+}
+/** credentials first, env var fallback; resolve per call, never cache (boot-time races). */
+export declare function resolveRetrieverCredential(ctx: CredentialContext, ref: string): Promise<string | undefined>;
+/** Wind ref + per-call resolver; `wind_docs` and `wind_*` market data share the key. */
+export declare function createWindCredentialResolver(ctx: CredentialContext, credentialRef?: string): {
+    credentialRef: string;
+    resolve: () => Promise<string | undefined>;
+};
+export interface RetrieverRuntime {
+    retriever: WebRetriever;
+    windClient: WindClient;
+    ocrClient: PaddleOcrClient;
+    localFetchConfig: Required<LocalFetchConfig>;
+    resolveWindApiKey: () => Promise<string | undefined>;
+    /** Reference name only (for logs/diagnostics), never the secret. */
+    windCredentialRef: string;
+    /** Present only when localFetch.enabled is true. */
+    localFetch?: LocalFetcherLike;
+}
+/**
+ * `config` is the raw, unvalidated object from preset/settings, so every default must be
+ * applied here rather than relying on Schemastery.
+ */
+export declare function createRetrieverRuntime(ctx: CredentialContext, config?: RetrieverConfig): RetrieverRuntime;
+export {};

package/lib/retriever-runtime.js

@@ -0,0 +1,82 @@
+/**
+ * Sole construction point for AnySearch / Wind / local fetch / PaddleOCR / WebRetriever.
+ * Search, source and OCR rows reuse it; copies would drift defaults, credential
+ * resolution and OCR budgets. Registers no tools or services.
+ */
+import { createAnySearchClient, envKey } from './web-retriever/engines.js';
+import { createHttpRequester, createLocalFetcher } from './web-retriever/local-fetch.js';
+import { createWindClient } from './web-retriever/wind-client.js';
+import { createPaddleOcrClient } from './ocr/client.js';
+import { WebRetriever } from './web-retriever/retriever.js';
+import { PADDLE_OCR_DEFAULTS, resolveLocalFetchConfig, } from './retriever-config.js';
+/** credentials first, env var fallback; resolve per call, never cache (boot-time races). */
+export async function resolveRetrieverCredential(ctx, ref) {
+    try {
+        const credentials = ctx.get('credentials');
+        const resolved = await credentials?.resolve?.(ref);
+        if (resolved?.value)
+            return resolved.value;
+    }
+    catch {
+        // Fall back to the env var when the credentials service is unavailable.
+    }
+    return envKey(ref);
+}
+/** Wind ref + per-call resolver; `wind_docs` and `wind_*` market data share the key. */
+export function createWindCredentialResolver(ctx, credentialRef = 'WIND_API_KEY') {
+    const ref = credentialRef || 'WIND_API_KEY';
+    return { credentialRef: ref, resolve: () => resolveRetrieverCredential(ctx, ref) };
+}
+/**
+ * `config` is the raw, unvalidated object from preset/settings, so every default must be
+ * applied here rather than relying on Schemastery.
+ */
+export function createRetrieverRuntime(ctx, config = {}) {
+    const credentialRef = config.credentialRef || 'ANYSEARCH_API_KEY';
+    const client = createAnySearchClient(config.baseURL || undefined, () => resolveRetrieverCredential(ctx, credentialRef));
+    const windDocs = config.windDocs ?? {};
+    const windCredential = createWindCredentialResolver(ctx, windDocs.credentialRef);
+    const windCredentialRef = windCredential.credentialRef;
+    const resolveWindApiKey = windCredential.resolve;
+    const windClient = createWindClient({
+        endpoint: windDocs.endpoint || undefined,
+        timeoutMs: windDocs.timeoutMs || undefined,
+        resolveApiKey: resolveWindApiKey,
+    });
+    const localFetchConfig = resolveLocalFetchConfig(config.localFetch);
+    const localFetch = localFetchConfig.enabled
+        ? createLocalFetcher({
+            timeoutMs: localFetchConfig.timeoutMs,
+            maxBytes: localFetchConfig.maxBytes,
+            maxContentChars: localFetchConfig.maxContentChars,
+            maxRedirects: localFetchConfig.maxRedirects,
+            userAgent: localFetchConfig.userAgent,
+        })
+        : undefined;
+    const paddleOcrConfig = config.paddleOcr ?? {};
+    const paddleOcrCredentialRef = paddleOcrConfig.credentialRef || PADDLE_OCR_DEFAULTS.credentialRef;
+    const ocrClient = createPaddleOcrClient({
+        endpoint: paddleOcrConfig.endpoint || undefined,
+        model: paddleOcrConfig.model || undefined,
+        ...(paddleOcrConfig.pollBudgetMs ? { waitBudgetMs: paddleOcrConfig.pollBudgetMs } : {}),
+        resolveToken: () => resolveRetrieverCredential(ctx, paddleOcrCredentialRef),
+        // Reuse the local-fetch requester (URL/IP gates, size and timeout caps). 120s because
+        // PDF multipart upload and whole-document JSONL exceed the 30s web-page budget.
+        request: createHttpRequester({
+            timeoutMs: 120_000,
+            maxBytes: 1_048_576,
+            maxContentChars: 1_048_576,
+            maxRedirects: localFetchConfig.maxRedirects,
+            userAgent: localFetchConfig.userAgent,
+        }).request,
+    });
+    return {
+        retriever: new WebRetriever(client, localFetch),
+        windClient,
+        ocrClient,
+        localFetchConfig,
+        resolveWindApiKey,
+        windCredentialRef,
+        ...(localFetch === undefined ? {} : { localFetch }),
+    };
+}

package/lib/root-extras-entry.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `tools/root-extras` row: root-only selected-skills provider and the `customPersona`
+ * system-prompt section. This row registers no tools; both pieces re-read settings
+ * every turn so saved changes apply on the next step.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type SelectedSkillSelection } from './agents/selected-skills-provider.js';
+export declare const name = "capital-root-extras";
+export declare const inject: string[];
+interface RootExtrasConfig {
+    customPersona?: string;
+    selectedSkills?: SelectedSkillSelection;
+}
+/** Re-read per turn so a settings save applies to the same session on the next step. */
+export declare function readRootExtrasConfig(ctx: Context): RootExtrasConfig;
+export declare function apply(ctx: Context): void;
+export {};

package/lib/root-extras-entry.js

@@ -0,0 +1,25 @@
+import { registerRootSelectedSkills } from './agents/selected-skills-provider.js';
+import { userCustomizationSection } from './user-customization.js';
+import { readCapitalConfig } from './capital-settings.js';
+export const name = 'capital-root-extras';
+export const inject = ['systemPrompt'];
+/** Re-read per turn so a settings save applies to the same session on the next step. */
+export function readRootExtrasConfig(ctx) {
+    const config = readCapitalConfig(ctx);
+    return { customPersona: config.customPersona, selectedSkills: config.selectedSkills };
+}
+export function apply(ctx) {
+    registerRootSelectedSkills(ctx, () => readRootExtrasConfig(ctx).selectedSkills ?? {});
+    let lastPersonaError;
+    const section = userCustomizationSection(() => readRootExtrasConfig(ctx).customPersona, (error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message === lastPersonaError)
+            return;
+        lastPersonaError = message;
+        ctx.logger?.warn?.(`capital-generation: customPersona 未加载（${message}）`);
+    });
+    ctx.effect(() => {
+        const dispose = ctx.systemPrompt.section(section);
+        return typeof dispose === 'function' ? dispose : () => { };
+    }, 'capital-generation.user-customization()');
+}

package/lib/runtime-entry.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Host-plane Capital runtime row. Chart source tokens are issued by data_junior and
+ * redeemed by the specialist, so both presets must see one registry; provide it here
+ * instead of per preset. The module-level cache still keys by root for older call sites.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type CapitalShared } from './runtime.js';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Shared by the Capital root, junior and specialist presets. */
+        capitalChartRuntime: CapitalShared;
+    }
+}
+export declare const name = "capital-runtime";
+export declare function apply(ctx: Context): void;

package/lib/runtime-entry.js

@@ -0,0 +1,5 @@
+import { capitalSharedRuntime } from './runtime.js';
+export const name = 'capital-runtime';
+export function apply(ctx) {
+    ctx.provide('capitalChartRuntime', capitalSharedRuntime(ctx));
+}

package/lib/runtime.d.ts

@@ -0,0 +1,21 @@
+import { WorkspaceDatasetStore } from './data-collector/store.js';
+import { ChartArtifactRegistry } from './chart/artifact-ref.js';
+import { ChartSourceTokenStore } from './chart/source-token.js';
+/** Structural type so tests can pass a fake ctx. */
+export interface RuntimeContext {
+    get(name: string): unknown;
+    root?: unknown;
+}
+export interface CapitalShared {
+    sourceTokens: ChartSourceTokenStore;
+    artifacts: ChartArtifactRegistry;
+}
+/**
+ * One Dataset store per mount, deliberately not a singleton: the hub registers source
+ * capabilities once per isolate realm, so a shared hub throws `data source capability
+ * already registered`. Stores only touch workspace via host fs, no state to synchronize.
+ */
+export declare function capitalDatasetStore(ctx: RuntimeContext): WorkspaceDatasetStore;
+export declare function capitalSharedRuntime(ctx: RuntimeContext): CapitalShared;
+/** Test-only: drop the per-root cache. */
+export declare function resetCapitalRuntime(): void;

package/lib/runtime.js

@@ -0,0 +1,33 @@
+import { WorkspaceDatasetStore } from './data-collector/store.js';
+import { ChartArtifactRegistry } from './chart/artifact-ref.js';
+import { ChartSourceTokenStore } from './chart/source-token.js';
+/**
+ * One Dataset store per mount, deliberately not a singleton: the hub registers source
+ * capabilities once per isolate realm, so a shared hub throws `data source capability
+ * already registered`. Stores only touch workspace via host fs, no state to synchronize.
+ */
+export function capitalDatasetStore(ctx) {
+    return new WorkspaceDatasetStore({
+        fs: ctx.get('fs'),
+        sandboxPolicy: ctx.get('sandboxPolicy'),
+    });
+}
+/**
+ * Process-wide state shared by every mounted preset; `apply()` runs once per role preset.
+ * Per-role token stores would make `render_chart` silently report `chart_source_expired`.
+ * Key by `ctx.root` (stable) because mount points differ per application.
+ */
+const cached = new Map();
+export function capitalSharedRuntime(ctx) {
+    const ref = ctx.root ?? ctx;
+    const existing = cached.get(ref);
+    if (existing !== undefined)
+        return existing;
+    const shared = { sourceTokens: new ChartSourceTokenStore(), artifacts: new ChartArtifactRegistry() };
+    cached.set(ref, shared);
+    return shared;
+}
+/** Test-only: drop the per-root cache. */
+export function resetCapitalRuntime() {
+    cached.clear();
+}

package/lib/search-entry.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `tools/retrieve-search` row: anysearch_search / web_retriever_fetch / wind_docs_*.
+ * Split from source and OCR rows; all share `retriever-runtime.ts` and resolve
+ * credentials per call.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "capital-retrieve-search-tools";
+export declare const inject: string[];
+export declare function apply(ctx: Context): void;

package/lib/search-entry.js

@@ -0,0 +1,9 @@
+import { createRetrieverRuntime } from './retriever-runtime.js';
+import { registerSearchTools } from './web-retriever/tools.js';
+import { readRetrieverConfig } from './capital-settings.js';
+export const name = 'capital-retrieve-search-tools';
+export const inject = ['tools'];
+export function apply(ctx) {
+    const runtime = createRetrieverRuntime(ctx, readRetrieverConfig(ctx));
+    registerSearchTools(ctx, runtime.retriever, runtime.windClient);
+}

package/lib/sources/eastmoney-http.js

@@ -99,16 +99,8 @@ function dateMs(value) { return Date.parse(`${value}T00:00:00+08:00`); }
 function textOrNull(value) { return value === undefined || value === null || value === '' ? null : String(value); }
 function sourceError(message, code = 'eastmoney_source_error') { const error = new Error(message); error.code = code; return error; }
 /**
- * 东财请求统一走**进程级共享**的东财客户端（`src/net/eastmoney-client.ts`）。
- *
- * 为什么必须共享：东财按**出口 IP** 风控（社区实测 >5 次/秒、1 分钟 ≥200 次、5 分钟 ≥300 次
- * 即临时封禁），而本仓曾经有**两份互不知情**的东财出口——数据面这里的裸 `fetch`，与
- * web_retriever 具名来源工具自己的一份。两份独立限流等于没有限流。
- * 现在两条数据面共用同一个节流器：数据面按"可复用性"分层（数值/分页走 Hub、流式文本走
- * web_retriever），但**网络面只有一份**。
- *
- * 本函数原有的错误码语义（`eastmoney_rate_limit` / `eastmoney_http_error` /
- * `eastmoney_invalid_response`）刻意保持不变——收敛的是网络面，不是调用方的契约。
+ * All Eastmoney calls use the process-wide client. Limits are per egress IP (>5/s, >=200/min,
+ * >=300/5min bans); two throttles mean no throttle. Error codes stay unchanged.
  */
 async function getJson(url, signal, context) {
     let payload;
@@ -116,7 +108,6 @@ async function getJson(url, signal, context) {
         payload = await sharedEastmoneyClient().fetchJson(url, { signal });
     }
     catch (error) {
-        // 调用方取消原样抛出；上游 HTTP 错误状态按既有口径归类。
         if (error instanceof Error && error.name === 'AbortError')
             throw error;
         const status = error instanceof EastmoneyTransportError ? error.status : undefined;
@@ -129,9 +120,7 @@ async function getJson(url, signal, context) {
     return payload;
 }
 function requireDatacenterResult(payload, context) {
-    // 上游用 code 9201 表示"返回数据为空"（success:false），这是**真实数据缺口**而非上游故障：
-    // 节假日、或该窗口确实没有任何记录。归类成 eastmoney_upstream_error 会诱导模型反复重试
-    // （§10.4 明令"数据缺口不要重试"），也与单票路径把 9201 判成"无记录"自相矛盾。
+    // code 9201 = empty result (holiday/no records), a real data gap; treating it as a failure invites retries.
     if (payload.success !== true && Number(payload.code) === 9201)
         return { data: [], pages: 0, count: 0 };
     if (payload.success !== true || Number(payload.code) !== 0 || !isRecord(payload.result))
@@ -201,9 +190,8 @@ function topFilter(params, ticker) {
     return code ? `${base}(SECURITY_CODE="${code}")` : base;
 }
 function parseTopRow(raw) {
-    // ⚠️ 上游 `MARKET` 是自由文本（实测存在 `SZ` 之外的写法），而 SECUCODE 自带市场后缀时
-    // 它是冗余信息：只有 SECUCODE 不带市场时才拿它做必填校验，否则原文喂进硬白名单会把
-    // 整页龙虎榜判成错误（护栏误杀真实数据，§10.2）。行里的 `market` 字段仍原样保留。
+    // MARKET is free text and redundant when SECUCODE has a suffix; only require it for bare codes,
+    // otherwise a whitelist rejects valid billboard pages. Keep the raw `market` field.
     const secucode = typeof raw.SECUCODE === 'string' ? raw.SECUCODE : '';
     const identity = secucode.includes('.')
         ? normalizeEastmoneySecurityIdentity({ secucode })
@@ -472,12 +460,7 @@ const MACRO_TABLES = [
         texts: [{ from: 'REMARK', to: 'announcement' }],
     },
 ];
-/**
- * 沪深港通六个渠道（`docs/dev/tool-schema.md` §10.6：上游给的是 `001`…`006` 这种数字码，
- * 模型侧只认语义名）。渠道身份由上游自己标注的 `MUTUAL_TYPE_NAME` 核对，并用同日的
- * `DEAL_AMT` 加法复核过：`001+003=005`（北向合计）、`002+004=006`（南向合计），实测 2026-09-30
- * 两条等式都精确成立。
- */
+/** Stock Connect channels: upstream codes 001–006; 001+003=005 (north) and 002+004=006 (south) verified. */
 const MUTUAL_CHANNELS = {
     sh_stock_connect: '001',
     hk_connect_sh: '002',
@@ -567,7 +550,7 @@ const mutualQuotaRow = {
     },
     additionalProperties: true,
 };
-/** 上游 `MUTUAL_TYPE_NAME` → 我们的渠道名（额度表只给单渠道，没有合计档）。 */
+/** Quota table has single channels only, no totals. */
 const MUTUAL_QUOTA_CHANNELS = { 沪股通: 'sh_stock_connect', 深股通: 'sz_stock_connect', '港股通(沪)': 'hk_connect_sh', '港股通(深)': 'hk_connect_sz' };
 const MUTUAL_QUOTA_CODE_CHANNELS = { '001': 'sh_stock_connect', '002': 'hk_connect_sh', '003': 'sz_stock_connect', '004': 'hk_connect_sz' };
 function parseMutualQuotaRow(raw) {
@@ -607,11 +590,7 @@ async function executeMutualQuota(params, signal) {
     const parsed = requireRows(result, 'mutual quota');
     return { data: { item: parsed.rows.map(parseMutualQuotaRow), pagination: pagination(1, 10, parsed.pages, parsed.total) }, schema: datacenterOutput(mutualQuotaRow) };
 }
-/**
- * 个股主力资金快照。上游 `RPT_DMSK_TS_STOCKNEW` 实测**只保留最近一个交易日**的全市场一行一股
- * （count=5199、TRADE_DATE 单一；带旧日期过滤器返回 9201 空），所以这不是时序能力：
- * 契约里必须写死"按日期循环取不到历史"，否则模型会拿它当序列反复请求。
- */
+/** Main-capital snapshot: latest trading day only, one row per stock (5199, single TRADE_DATE); older dates return 9201. */
 const MAIN_CAPITAL_SORTS = {
     main_net_inflow: 'PRIME_INFLOW',
     change_pct: 'CHANGE_RATE',
@@ -667,8 +646,7 @@ function parseMainCapitalRow(raw) {
     const tradeDate = String(raw.TRADE_DATE ?? '').slice(0, 10);
     if (!/^\d{4}-\d{2}-\d{2}$/.test(tradeDate))
         throw sourceError('Eastmoney main capital row has invalid TRADE_DATE', 'eastmoney_invalid_response');
-    // SECUCODE 自带市场后缀（实测 200/200 行都有），不做"按代码首位猜市场"的兜底：猜错就是把一只
-    // 股票的数据挂到另一只上。缺了就说明上游形状变了，响亮失败。
+    // SECUCODE always has a market suffix; never guess from the first digit. A missing suffix is a shape change.
     if (typeof raw.SECUCODE !== 'string' || !raw.SECUCODE.includes('.')) {
         throw sourceError('Eastmoney main capital row lost its market suffix in SECUCODE', 'eastmoney_invalid_response');
     }
@@ -719,12 +697,7 @@ async function executeMainCapital(params, signal) {
     const parsed = requireRows(result, 'main capital snapshot');
     return { data: { item: parsed.rows.map(parseMainCapitalRow), pagination: pagination(Number(params.page), Number(params.size), parsed.pages, parsed.total) }, schema: datacenterOutput(mainCapitalRow) };
 }
-/**
- * 分红送配方案：一行一个方案，按除权除息日过滤。`PRETAX_BONUS_RMB` / `BONUS_RATIO` / `IT_RATIO`
- * 的"每 10 股"标度由上游自己写在 `IMPL_PLAN_PROFILE` 原文里（实测 `10派280.2423元(含税)` 配
- * `PRETAX_BONUS_RMB=280.2423`、`10送4.00派3.00元` 配 `BONUS_RATIO=4`），所以照原值给出并保留原文。
- * `IS_KCB` 与 `PUBLISH_DATE` 实测 200/200 全为 null，不收录（描述里点名，免得当成取数失败）。
- */
+/** Dividend plans: per-10-share scale comes from `IMPL_PLAN_PROFILE` text; values kept as-is. `IS_KCB`/`PUBLISH_DATE` always null. */
 const dividendRow = {
     type: 'object',
     properties: {
@@ -751,7 +724,6 @@ const dividendRow = {
     },
     additionalProperties: true,
 };
-/** 日期键归一：`2026-06-26 00:00:00` → `2026-06-26`；空值保留 null（12/200 行没有股权登记日）。 */
 function dayValue(value) {
     const text = String(value ?? '').slice(0, 10);
     return /^\d{4}-\d{2}-\d{2}$/.test(text) ? text : null;
@@ -763,8 +735,7 @@ function parseDividendRow(raw) {
     const exDate = dayValue(raw.EX_DIVIDEND_DATE);
     if (exDate === null)
         throw sourceError('Eastmoney dividend row has invalid EX_DIVIDEND_DATE', 'eastmoney_invalid_response');
-    // 这三列实测 200/200 行都有值（缺了就是上游形状变了），所以按必填处理、缺一就响亮失败；
-    // equity_record_date 实测 12/200 为 null（方案还没定登记日），那一列才允许 null。
+    // These three are always populated; equity_record_date may be null until the plan sets one.
     const requiredDates = ['REPORT_DATE', 'PLAN_NOTICE_DATE', 'NOTICE_DATE'].map((key) => {
         const day = dayValue(raw[key]);
         if (day === null)
@@ -821,9 +792,8 @@ async function executeDividend(params, signal) {
     return { data: { item: parsed.rows.map(parseDividendRow), pagination: pagination(Number(params.page), Number(params.size), parsed.pages, parsed.total) }, schema: datacenterOutput(dividendRow) };
 }
 /**
- * 股东户数**最新一期截面**（`RPT_HOLDERNUMLATEST`）：一股一行，`END_DATE` 是**报告期**、
- * `HOLD_NOTICE_DATE` 才是披露日（实测茅台 END_DATE=2026-06-30 / 披露 2026-08-15），两者必须分开。
- * 新上市标的 `PRE_HOLDER_NUM=0` 且 `HOLDER_NUM_RATIO=null`（无上期可比），不是数据错误。
+ * Holder-count snapshot: `END_DATE` is the report period; `HOLD_NOTICE_DATE` is the disclosure date.
+ * New listings have `PRE_HOLDER_NUM=0` and null ratio (no prior period).
  */
 const holderRow = {
     type: 'object',
@@ -907,13 +877,8 @@ async function executeHolder(params, signal) {
     return { data: { item: parsed.rows.map(parseHolderRow), pagination: pagination(Number(params.page), Number(params.size), parsed.pages, parsed.total) }, schema: datacenterOutput(holderRow) };
 }
 /**
- * 两融个股明细（`RPTA_WEB_RZRQ_GGMX`）。45 列里绝大多数是同一族的"余额 / 买入 / 偿还 / 净买入 ×
- * 当日 / 3 / 5 / 10 日"，所以按映射表成对声明，不逐列写 JSON Schema。
- *
- * 口径靠算术核对，不靠记忆（实测 600519，2026-09-30）：`RZRQYE = RZYE + RQYE`、
- * `RZRQYECZ = RZYE - RQYE`、`RZJME = RZMRE - RZCHE`、`RQJMG = RQMCL - RQCHL` 四式精确成立，
- * `RZYEZB = RZYE / SZ`（0.8617% 对得上），所以这几列的含义可以写进契约。
- * 披露新鲜度**跨市场不一致**：实测沪市已到 2026-09-30，深市（000001）最新只有 2026-09-29。
+ * Margin detail: verified identities RZRQYE=RZYE+RQYE, RZRQYECZ=RZYE-RQYE, RZJME=RZMRE-RZCHE,
+ * RQJMG=RQMCL-RQCHL. Disclosure freshness differs by market (SH one day ahead of SZ).
  */
 const MARGIN_COLUMNS = [
     ['RZYE', 'margin_balance'], ['RQYE', 'short_balance'], ['RZRQYE', 'total_balance'], ['RZRQYECZ', 'balance_gap'],
@@ -943,8 +908,7 @@ function parseMarginRow(raw, requestedThscode) {
     const day = dayValue(raw.DATE);
     if (day === null)
         throw sourceError('Eastmoney margin row has invalid DATE', 'eastmoney_invalid_response');
-    // SCODE 不带市场后缀，市场由请求的 ticker 决定：行身份取调用方传入的 canonical 代码，
-    // 再与上游 SECUCODE 对照，对不上就是上游把明细串行了。
+    // SCODE has no market suffix, so identity comes from the requested ticker; a mismatched SECUCODE is a row mix-up.
     const secucode = typeof raw.SECUCODE === 'string' ? raw.SECUCODE : '';
     if (secucode && secucode !== requestedThscode) {
         throw sourceError(`Eastmoney margin row SECUCODE ${secucode} does not match requested ${requestedThscode}`, 'eastmoney_invalid_response');
@@ -982,15 +946,7 @@ async function executeMargin(params, signal) {
     const thscode = String(params.ticker);
     return { data: { item: parsed.rows.map((raw) => parseMarginRow(raw, thscode)), pagination: pagination(Number(params.page), Number(params.size), parsed.pages, parsed.total) }, schema: datacenterOutput(marginRow) };
 }
-/**
- * 可转债发行清单（`RPT_BOND_CB_LIST`，实测全库 1059 只、起息日 2007-07-02 起）。
- *
- * 72 列里只有**条款与日期**有值：`CONVERT_STOCK_PRICE` / `CURRENT_BOND_PRICE`(_NEW) /
- * `TRANSFER_PRICE` / `TRANSFER_PREMIUM_RATIO` / `RESALE_TRIG_PRICE` / `REDEEM_TRIG_PRICE` /
- * `PBV_RATIO` / `MARKET` / `CONVERT_STOCK_PRICEHQ` 实测 **1059/1059 恒为 null**（东财页面上那些
- * 行情数是另一条接口现算的），`TRANSFER_VALUE` 只是 `INITIAL_TRANSFER_PRICE` 的副本（1051/1059 相同
- * 却多 8 个 null）。所以这张表**不承诺行情**，也不把那些 null 当成取数失败。
- */
+/** Bond list: only terms/dates are populated; price and premium columns are always null (computed elsewhere). */
 const BOND_MARKET_SUFFIX = { CNSESH: 'SH', CNSESZ: 'SZ', STAS00: null };
 function bondStockIdentity(raw) {
     const digits = String(raw.CONVERT_STOCK_CODE ?? '');
@@ -999,9 +955,7 @@ function bondStockIdentity(raw) {
     return {
         stock_ticker: digits,
         stock_name: String(raw.SECURITY_SHORT_NAME ?? ''),
-        // 正股市场只取上游 TRADE_MARKET，**不按数字首位推**：实测 15 只 2007-2009 沪市老债代码是 126 开头
-        // （首位 1 也不等于沪），老三板退市债（STAS00）的正股 400266 更不是北交所标的——猜错就是把一只证券
-        // 挂到另一个市场名下。未知市场一律不给后缀（`stock_thscode` 为 null），不猜也不报错。
+        // Market only from TRADE_MARKET: 126-prefixed 2007–09 SH bonds and STAS00 stock 400266 would be misattributed. Unknown → null.
         stock_thscode: BOND_MARKET_SUFFIX[String(raw.TRADE_MARKET ?? '')] ? `${digits}.${BOND_MARKET_SUFFIX[String(raw.TRADE_MARKET ?? '')]}` : null,
     };
 }
@@ -1035,7 +989,6 @@ const bondRow = {
     additionalProperties: true,
 };
 function parseBondRow(raw) {
-    // 债券身份只认上游给的 SECUCODE（带 .SH/.SZ/.NQ 后缀）：本表 1059/1059 都有值，丢了后缀就是形状变了。
     if (typeof raw.SECUCODE !== 'string' || !raw.SECUCODE.includes('.')) {
         throw sourceError('Eastmoney convertible bond row lost its market suffix in SECUCODE', 'eastmoney_invalid_response');
     }
@@ -1075,7 +1028,7 @@ function parseBondRow(raw) {
         in_conversion_period: textOrNull(raw.IS_CONVERT_STOCK),
     };
 }
-/** 债市代码是 11/12/13/40 等六位数；后缀只用于收窄（实测出现 .SH/.SZ/.NQ），一律剥掉再过滤，不给市场推断留口子。 */
+/** Strip .SH/.SZ/.NQ suffixes; never infer a market. */
 function bondCode(value, name) {
     const raw = String(value).toUpperCase();
     const digits = raw.replace(/\.[A-Z]{2,3}$/u, '');
@@ -1100,8 +1053,7 @@ async function executeBondList(params, signal) {
     url.searchParams.set('columns', 'ALL');
     url.searchParams.set('source', 'WEB');
     url.searchParams.set('client', 'WEB');
-    // sortColumns 与过滤器都用 PUBLIC_START_DATE（实测该列可过滤、可排序，且与 VALUE_DATE 1059/1059 相同）；
-    // 只按其一是因为日期区间过滤实测只有这一列**从不为空**——LISTING_DATE 有 8 只未上市的债会被区间静默吞掉。
+    // Use PUBLIC_START_DATE: the only date filter never null (equals VALUE_DATE); LISTING_DATE would drop 8 unlisted bonds.
     url.searchParams.set('sortColumns', 'PUBLIC_START_DATE');
     url.searchParams.set('sortTypes', '-1');
     url.searchParams.set('pageNumber', String(params.page));

package/lib/sources/ftshare-rest.d.ts

@@ -1,37 +1,13 @@
 /**
- * FTShare（非凸科技 `market.ft.tech/gateway`）REST source —— **资金流 + 行情/日 K 截面 + 快照与日历
- * + 大宗与披露 + 申万行业 + 期货与贵金属**。
- *
- * 为什么接这一族（批次 A–E 逐条真报文实测于 2026-10-15，批次 F 于 2026-10-16）：
- * - 同花顺 `capital-flow/*` 对我们是 `code=2004` 永久关闭，东财 `eastmoney_main_capital_snapshot`
- *   实测**只有查询日一股一行**——个股资金流的历史序列在本仓一直是空的。这一族给到最近约 45 个交易日
- *   （T-45 仍有 5199 行、T-50 起 total=0），主力五档更给到约 187 个交易日。
- * - 板块（行业）资金滚动此前只有 `eastmoney_cashflow_rotation` 一条，上游一抖就没有第二家。
- * - 北交所行情此前是**零**：腾讯那一路在参数层明确拒 BJ，而这一族实测含 349 只北证票。
- * - 期货与贵金属此前在本仓是**整块空白**（`ticker_search` 只允许消歧到期货交易所，没有一条数据端点），
- *   所以批次 F 那十颗不是第二家，而是第一家：合约清单与要素、日/周/月/季 K 线、涨跌停价、每日结算参数、
- *   仓单日报、品种周报、南华商品指数、东财会员持仓排名、贵金属价格。
- * 上游分别是同花顺与同花顺 daec，与现有能力**不是同一条抓取路径**，才够称 plan B。
- *
- * ⛔ 本模块的 description 与注释**只允许写有原始报文可回查的数字**。2026-10-15 曾有一批"实测计数"
- * （行数在 3766/3864/5450/5574 之间跳、`ys` 返回 309 行、业务码 100605、页码回显谎报）事后逐条回查
- * **在任何一次真报文里都不存在**，是我把不同接口的读数串成了因果；据此撤掉的两颗能力已于当晚复验注册回来。
- * 教训写进 `docs/design/ftshare-source-survey.md` §7.5–§7.7：**没打进日志的数字不算实测**。
- *
- * ⛔ 免费档限流 **10 QPS / burst 20**（官方口径）。`DataCollectorHub` 的 FIFO 只保证同一时刻
- * 一个请求，**不含最小间隔**——串行 ≠ 节流（`src/net/eastmoney-client.ts` 同一条教训）。
- * 本模块用进程级节流链把上限压到 ~8 QPS，留突发余量。
- *
- * ⛔ 凭据一律**调用期解析**，注册只看结构（AGENTS.md §9.7，2026-09-30 桌面端 61 能力静默缺席
- * 那一族事故）。套餐外路由返回 403 `route_not_allowed`，归类成 `plan_closed` 且不重试——
- * 它和 Fuyao 的 `2004` 是同一件事：能力级不可用，重试只白烧回合。
+ * FTShare (非凸科技 `market.ft.tech/gateway`): capital flows, quote/K-line, calendars, block trades,
+ * SW industry, futures/metals; the only source for A-share flow history, BJ quotes and futures.
+ * ⛔ Only numbers verifiable in a logged raw response; free tier 10 QPS/burst 20 (we cap ~8 QPS).
+ * ⛔ Credentials resolve per call; 403 route_not_allowed = plan_closed, never retry (cf. Fuyao 2004).
  */
 import type { Context } from '@deepseek-ai/cordis';
 import type { DataSource } from '../data-collector/hub.js';
 type JsonRecord = Record<string, unknown>;
-/** 10 QPS 的 80% 上限：120ms 最小间隔 ⇒ 稳态 ~8.3 次/秒，突发也不会越过 20。 */
 export declare const FTSHARE_MIN_INTERVAL_MS = 120;
-/** 失败归类：与 `FuyaoFailureKind` 同一套语汇，`plan_closed` 对应 Fuyao 的 `capability_closed`。 */
 type FtshareFailureKind = 'credential_missing' | 'rate_limited' | 'plan_closed' | 'invalid_parameter' | 'http_error' | 'upstream_error' | 'invalid_response';
 export declare class FtshareError extends Error {
     readonly kind: FtshareFailureKind;
@@ -45,13 +21,9 @@ export declare class FtshareError extends Error {
 export interface FtshareRequester {
     getJson(path: string, search: URLSearchParams, signal: AbortSignal): Promise<JsonRecord>;
 }
-/** key 每次调用现取（`resolveApiKey` 由装配层注入），构造客户端不依赖 key。 */
+/** Key resolved per call; constructing the client touches no credentials. */
 export declare function createFtshareClient(resolveApiKey: () => Promise<string | undefined>, baseUrl?: string): FtshareRequester;
-/**
- * key 每次调用现取（与 `resolveFuyaoApiKey` 同一口径）：credentials 优先、环境变量兜底。
- * ⛔ 注册面**不得**以"装配期读到 key"为条件（AGENTS.md §9.7），也不要把这里的 rejection 缓存住——
- * 一次装配期抢跑会把这个能力钉到进程结束。
- */
+/** Credentials first, env fallback; never gate registration on key availability or cache a rejection. */
 export declare function resolveFtshareApiKey(ctx: Context, credentialRef?: string): Promise<string | undefined>;
 export declare function createFtshareSources(resolveApiKey: () => Promise<string | undefined>): DataSource[];
 export {};