@v587d/capital-generation 2.7.12 → 2.8.1

package/lib/data-collector/tools.js

@@ -47,8 +47,20 @@ function render(_args, value) {
     // ToolOutputDefinition.render(args, value)：第一参是入参、第二参才是返回值。
     return [{ type: 'text', text: JSON.stringify(value) }];
 }
-function tool(name, description, parameters, schema, execute) {
-    return { name, description, parameters, output: { schema, render }, execute };
+function tool(name, description, parameters, schema, execute, options = {}) {
+    return {
+        name,
+        description,
+        parameters,
+        output: { schema, render },
+        execute,
+        // 与 `dataset-tools.ts` 的 `describe_dataset` 同一机制：框架把同一条消息里的多个调用
+        // 放进有界并发池，N 份结果在同一个下一步一起返回（宿主 fail-closed：不标就串行，2026-10-16
+        // 一次性 headless 探针核过，账本 L30）。⛔ 只给**纯读**的发现面开：
+        // `request_data` 刻意不标——Hub 的执行器是 FIFO 串行（`hub.ts` 的 Phase 1 注释），
+        // 让模型并行发取数等于把上游节流与 in-flight 合并放在我们没承诺过的位置上。
+        ...(options.concurrencySafe === true ? { isConcurrencySafe: () => true } : {}),
+    };
 }
 /**
  * 调用方 Agent session（官方注入，不可由模型伪造）。请求归属恒为当前调用者，
@@ -151,8 +163,8 @@ export function registerDataCollectorTools(ctx, hub, diagnostics) {
                 throw requestParamsError(error, requestedCapability) ?? error;
             }
         }),
-        tool('list_capabilities', '列出当前已注册的数据能力目录：**纯文本，一行一条** `capability|summary|paginated`，paginated 为 1（分页）/ 0（不分页）。名字或摘要里的 `|`、换行会转义成 `\\|`、`\\n`，所以一行就是一条能力，不要按冒号或空格拆分。目录是发现入口，**一个任务只需调用一次**：同一 session 的历史里已经保有这份目录，重复调用只会白占上下文。目录刻意不含参数与输出结构（完整 schema 约 23KB，会被剪枝截断）；确定要用的能力后，用 describe_capability 单独取那一个能力的 input_schema 后即可 request_data。request_data 的 capability 必须以本目录为准，不要自行编造。', jsonObject(), { type: 'string' }, async (_args, exec) => { delegatedSession(exec, 'list_capabilities'); return hub.capabilityDirectory(); }),
-        tool('describe_capability', '读取**一个**能力的完整契约：description（单位、null 语义、时间与分页口径）、input_schema（params 的取值与约束）、output_fields（返回字段的逐行字典 `路径:类型[:说明]`，类型后缀 `?` 为可为 null、`[].` 为数组元素的字段）与 paginated。request_data 的 params 必须按这里返回的 input_schema 填写；request_data 若返回 request_params_invalid，应回到这里重新读取后再重试。一个能力描述一次即可：结果已在本 session 历史里，重复描述同一个能力只会白占上下文；需要几个能力就分别调用几次，不要用逗号把多个名字塞进一次调用。错误按 code 引导：capability_required（没给名字，先 list_capabilities()）、capability_invalid（不是字符串/超长/含逗号，改为目录中的单个名字）、capability_catalog_empty（数据源未注册，别重试，回告主 Agent）、capability_unknown（名字不存在，错误里会列出全部可用能力名并要求原样复制）。', jsonObject({ capability: { type: 'string' } }, ['capability']), jsonObject({
+        tool('list_capabilities', '列出当前已注册的数据能力目录：**纯文本，一行一条** `capability|summary|paginated`，paginated 为 1（分页）/ 0（不分页）。名字或摘要里的 `|`、换行会转义成 `\\|`、`\\n`，所以一行就是一条能力，不要按冒号或空格拆分。目录是发现入口，**一个任务只需调用一次**：同一 session 的历史里已经保有这份目录，重复调用只会白占上下文。目录刻意不含参数与输出结构（完整 schema 约 23KB，会被剪枝截断）；确定要用的能力后，用 describe_capability 单独取那一个能力的 input_schema 后即可 request_data。request_data 的 capability 必须以本目录为准，不要自行编造。', jsonObject(), { type: 'string' }, async (_args, exec) => { delegatedSession(exec, 'list_capabilities'); return hub.capabilityDirectory(); }, { concurrencySafe: true }),
+        tool('describe_capability', '读取**一个**能力的完整契约：description（单位、null 语义、时间与分页口径）、input_schema（params 的取值与约束）、output_fields（返回字段的逐行字典 `路径:类型[:说明]`，类型后缀 `?` 为可为 null、`[].` 为数组元素的字段）与 paginated。request_data 的 params 必须按这里返回的 input_schema 填写；request_data 若返回 request_params_invalid，应回到这里重新读取后再重试。一个能力描述一次即可：结果已在本 session 历史里，重复描述同一个能力只会白占上下文；需要几个能力就**在同一条消息里一次发出多个调用**（本工具是纯读、可并发执行，框架会把它们放进并发池、在同一个下一步一起返回），但一次仍只传**一个**名字，不要用逗号把多个名字塞进一条调用。错误按 code 引导：capability_required（没给名字，先 list_capabilities()）、capability_invalid（不是字符串/超长/含逗号，改为目录中的单个名字）、capability_catalog_empty（数据源未注册，别重试，回告主 Agent）、capability_unknown（名字不存在，错误里会列出全部可用能力名并要求原样复制）。', jsonObject({ capability: { type: 'string' } }, ['capability']), jsonObject({
             capability: { type: 'string' },
             summary: { type: 'string' },
             paginated: { type: 'boolean' },
@@ -166,7 +178,7 @@ export function registerDataCollectorTools(ctx, hub, diagnostics) {
             if (!detail)
                 throw capabilityError('capability_unknown', `未注册的能力 "${capability}"。`);
             return detail;
-        }),
+        }, { concurrencySafe: true }),
         ...(diagnostics ? [
             tool('dc_status', '诊断工具：返回数据管道运行状态 —— at/call 为本次真实执行的时间戳与计数（防伪）、api_key 为**本次调用现取**的凭据解析结果（present/source，不含密钥值）、registered_capabilities 为当前已注册 capability 列表、root_tool_policy 为根 Agent 工具收敛的现场记录（preset_id / outcome / denied / failed，排查"主 Agent 为什么看得见本该收敛掉的工具"用）。数据源注册不依赖 key：api_key.present=false 时同花顺能力仍在目录里，但每次取数会点名 FUYAO_API_KEY 失败。排障时优先调用。', jsonObject(), jsonObject({
                 at: { type: 'integer' },

package/lib/index.d.ts

@@ -86,6 +86,8 @@ export interface Config {
     selectedSkills?: SelectedSkillSelection;
     /** Fuyao credentials 引用名；空值回退到 FUYAO_API_KEY。 */
     fuyaoCredentialRef?: string;
+    /** FTShare（非凸科技）credentials 引用名；空值回退到 FTSHARE_API_KEY。 */
+    ftshareCredentialRef?: string;
     /** web_retriever 配置（可选；缺省使用 AnySearch 默认地址与凭据名）。 */
     retriever?: RetrieverConfig;
 }
@@ -98,6 +100,7 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
         [k: string]: z<boolean, boolean, "defined">;
     }>>, "defined">;
     fuyaoCredentialRef: z<string, string, "defined">;
+    ftshareCredentialRef: z<string, string, "defined">;
     retriever: z<Schemastery.ObjectS<NoInfer<{
         baseURL: z<string, string, "defined">;
         credentialRef: z<string, string, "defined">;
@@ -183,6 +186,7 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
         [k: string]: z<boolean, boolean, "defined">;
     }>>, "defined">;
     fuyaoCredentialRef: z<string, string, "defined">;
+    ftshareCredentialRef: z<string, string, "defined">;
     retriever: z<Schemastery.ObjectS<NoInfer<{
         baseURL: z<string, string, "defined">;
         credentialRef: z<string, string, "defined">;

package/lib/index.js

@@ -4,6 +4,7 @@ import { WorkspaceDatasetStore } from './data-collector/store.js';
 import { resolveFuyaoApiKey, createFuyaoRestSources } from './sources/fuyao-rest.js';
 import { createTencentSources } from './sources/tencent-http.js';
 import { createEastmoneySources } from './sources/eastmoney-http.js';
+import { createFtshareSources, resolveFtshareApiKey } from './sources/ftshare-rest.js';
 import { createWindSources } from './sources/wind-mcp.js';
 import { registerDataCollectorTools } from './data-collector/tools.js';
 import { registerDatasetTools } from './data-collector/dataset-tools.js';
@@ -11,7 +12,7 @@ import { registerTimeTool } from './time/tools.js';
 import { registerWatchlistTool } from './watchlist/tools.js';
 import { registerChartTool } from './chart/tool.js';
 import { createChartEventPublisher } from './chart/events.js';
-import { registerRootToolPolicy, rootPolicyProbes } from './agents/root-tool-policy.js';
+import { registerRootToolPolicy, registerFsWriteGuard, rootPolicyProbes } from './agents/root-tool-policy.js';
 import { registerBashGuard } from './agents/bash-guard.js';
 import { registerRootSelectedSkills, SELECTED_SKILL_CATALOG } from './agents/selected-skills-provider.js';
 import { ChartSourceTokenStore, registerChartSourceTool } from './chart/source-token.js';
@@ -147,6 +148,9 @@ export const Config = z.object({
     fuyaoCredentialRef: z.string()
         .default('FUYAO_API_KEY')
         .description('Fuyao credentials 引用名，空 = FUYAO_API_KEY'),
+    ftshareCredentialRef: z.string()
+        .default('FTSHARE_API_KEY')
+        .description('FTShare（非凸科技）credentials 引用名，空 = FTSHARE_API_KEY'),
     retriever: RetrieverSchema.default({ baseURL: '', credentialRef: 'ANYSEARCH_API_KEY', windDocs: { endpoint: '', credentialRef: 'WIND_API_KEY', timeoutMs: 60000 }, localFetch: { ...LOCAL_FETCH_DEFAULTS }, paddleOcr: { ...PADDLE_OCR_DEFAULTS } })
         .description('web_retriever 配置（可选；缺省使用 AnySearch 默认地址与凭据名）'),
 });
@@ -362,16 +366,22 @@ export function apply(ctx, config) {
         chartEvents: () => createChartEventPublisher(chartEventContext),
     });
     // 根 Agent 工具收敛：`agent/created` 里对**主 Agent**（无 parentSession）在其自己的
-    // scope 上 deny render_chart / subagent_visualization_specialist / prepare_chart_source。
+    // scope 上逐名 deny `ROOT_AGENT_DENIED_TOOLS`（出图三件套 + 十三个出网工具 + `write` /
+    // `edit`；2026-10-15 用户决策「开 read、同时保留 bash」后 shell 名已移出名单）。
     // 子 Agent 的 scope parent 是 standing key（兄弟），因此不受影响。
     registerRootToolPolicy(ctx);
-    // data_junior 的 bash 闸门：对**本 preset 的每个 agent** 在其自己的 scope 上装一次单调 guard。
-    // 两层可靠判定——A 只对**被委派**子会话开放（镜像 tool-exec.ts 的 delegatedSession）；
-    // B 拦掉必然失败的 `sandbox_permissions`（委派会话的审批策略由框架固定为 never，
-    // answerer 根本不会被调用），并给出正确路径。**不解析命令内容**：正则挡不住
-    // `node -e`，而 node/python 正是引入 bash 的目的；禁区纪律走 data_junior 的 persona。
-    // 理由全文见 src/agents/bash-guard.ts 与 docs/dev/bash-gate.md §1.6「data_junior 的 bash 闸门」。
+    // shell 闸门：对**本 preset 的每个 agent**（含主 Agent）在其自己的 scope 上装一次单调 guard，
+    // 只拦**必然失败的沙箱升级**（`sandbox_permissions` / `justification`：被委派会话的审批策略
+    // 由框架固定为 never，answerer 根本不会被调用），并给出正确路径。主 Agent 的 shell 保留
+    // （2026-10-15 决策），它的升级走正常 ask 审批。**不解析命令内容**：正则挡不住 `node -e`，
+    // 而 node/python 正是引入 bash 的目的；禁区纪律走 data_junior 的 persona。
+    // 理由全文见 src/agents/bash-guard.ts 与 docs/dev/bash-gate.md §1.6。
     registerBashGuard(ctx);
+    // fs 写口闸门：**全局**装一次（guard 按 `exec.agent` 取链路，与实例绑哪层无关——
+    // docs/dev/bash-gate.md §1.6 里声明的备选方向在写口上落地），调用期拦本 preset 的
+    // `write` / `edit`；`read` 开放给主 Agent 读 skill 分册与工作区文件。判据 fail-open
+    // （别的 preset 的会话照常读写），见 src/agents/root-tool-policy.ts。
+    registerFsWriteGuard(ctx);
     ctx.effect(() => {
         const sources = createTencentSources();
         const disposers = sources.map((dataSource) => hub.registerSource(dataSource));
@@ -398,6 +408,15 @@ export function apply(ctx, config) {
         return () => { for (const dispose of disposers)
             dispose(); };
     }, 'capital-generation.fuyao-sources()');
+    // FTShare（非凸科技）——同花顺资金流那一族的第二家上游。注册同样只看结构，key 每次调用现取（§9.7）；
+    // 免费档限流 10 QPS / burst 20 由 src/sources/ftshare-rest.ts 的进程级节流链兜住。
+    ctx.effect(() => {
+        const sources = createFtshareSources(() => resolveFtshareApiKey(ctx, effectiveConfig.ftshareCredentialRef || 'FTSHARE_API_KEY'));
+        const disposers = sources.map((dataSource) => hub.registerSource(dataSource));
+        ctx.logger.info(`capital-generation: 已注册 ${disposers.length} 个 FTShare 数据源（ftshare_*，key 每次调用现取）`);
+        return () => { for (const dispose of disposers)
+            dispose(); };
+    }, 'capital-generation.ftshare-sources()');
     // ── web_retriever 域：anysearch（广度）+ wind_docs（public_document 精准）──────
     const retriever = effectiveConfig.retriever ?? {};
     const credentialRef = retriever.credentialRef || 'ANYSEARCH_API_KEY';

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

@@ -0,0 +1,54 @@
+/**
+ * FTShare（非凸科技 `market.ft.tech/gateway`）REST source —— **资金流 + 行情/日 K 截面 + 快照与日历
+ * + 大宗与披露 + 申万行业**。
+ *
+ * 为什么接这一族（2026-10-15 逐条真报文实测）：
+ * - 同花顺 `capital-flow/*` 对我们是 `code=2004` 永久关闭，东财 `eastmoney_main_capital_snapshot`
+ *   实测**只有查询日一股一行**——个股资金流的历史序列在本仓一直是空的。这一族给到最近约 45 个交易日
+ *   （T-45 仍有 5199 行、T-50 起 total=0），主力五档更给到约 187 个交易日。
+ * - 板块（行业）资金滚动此前只有 `eastmoney_cashflow_rotation` 一条，上游一抖就没有第二家。
+ * - 北交所行情此前是**零**：腾讯那一路在参数层明确拒 BJ，而这一族实测含 349 只北证票。
+ * 上游分别是同花顺与同花顺 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` 是同一件事：能力级不可用，重试只白烧回合。
+ */
+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;
+    readonly status?: number;
+    readonly code?: number;
+    constructor(kind: FtshareFailureKind, message: string, details?: {
+        status?: number;
+        code?: number;
+    });
+}
+export interface FtshareRequester {
+    getJson(path: string, search: URLSearchParams, signal: AbortSignal): Promise<JsonRecord>;
+}
+/** key 每次调用现取（`resolveApiKey` 由装配层注入），构造客户端不依赖 key。 */
+export declare function createFtshareClient(resolveApiKey: () => Promise<string | undefined>, baseUrl?: string): FtshareRequester;
+/**
+ * key 每次调用现取（与 `resolveFuyaoApiKey` 同一口径）：credentials 优先、环境变量兜底。
+ * ⛔ 注册面**不得**以"装配期读到 key"为条件（AGENTS.md §9.7），也不要把这里的 rejection 缓存住——
+ * 一次装配期抢跑会把这个能力钉到进程结束。
+ */
+export declare function resolveFtshareApiKey(ctx: Context, credentialRef?: string): Promise<string | undefined>;
+export declare function createFtshareSources(resolveApiKey: () => Promise<string | undefined>): DataSource[];
+export {};