@v587d/capital-generation 2.8.2 → 2.9.0

package/lib/data-collector/tools.js

@@ -1,3 +1,6 @@
+// Session reading and authorization have one implementation (src/tool-exec.ts); do not re-implement here.
+import { authorizedSession, sessionIdentityDecisions } from '../tool-exec.js';
+import { DATA_COLLECTION_PRESET_IDS } from '../preset-ids.js';
 const jsonObject = (properties = {}, required = []) => ({ type: 'object', properties, required, additionalProperties: false });
 const freeObject = { type: 'object', additionalProperties: true };
 const MAX_ID_LENGTH = 256;
@@ -25,10 +28,7 @@ function boundedParams(value) {
         throw new Error(`params exceeds maximum size ${MAX_PARAMS_BYTES} bytes`);
     return value;
 }
-/**
- * DatasetRef 输出结构（模型可见协议）：只有元数据。任何 raw rows、内部
- * data_key、绝对路径字段都不允许出现。
- */
+/** Model-visible DatasetRef: metadata only; no raw rows, data_key or absolute paths. */
 const datasetRefSchema = () => jsonObject({
     dataset_id: { type: 'string' },
     task_id: { oneOf: [{ type: 'string' }, { type: 'null' }] },
@@ -44,7 +44,7 @@ const datasetRefSchema = () => jsonObject({
     params_digest: { type: 'string' },
 }, ['dataset_id', 'task_id', 'session_id', 'artifact_ref', 'format', 'capability', 'source_label', 'schema', 'row_count', 'captured_at', 'retention_until', 'params_digest']);
 function render(_args, value) {
-    // ToolOutputDefinition.render(args, value)：第一参是入参、第二参才是返回值。
+    // ToolOutputDefinition.render(args, value): the first parameter is the input, the second the output.
     return [{ type: 'text', text: JSON.stringify(value) }];
 }
 function tool(name, description, parameters, schema, execute, options = {}) {
@@ -54,32 +54,11 @@ function tool(name, description, parameters, schema, execute, options = {}) {
         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 合并放在我们没承诺过的位置上。
+        // Framework concurrency pool: mark pure-read discovery tools only. request_data stays serial
+        // because the Hub executes FIFO and upstream throttling/merging is not promised under parallelism.
         ...(options.concurrencySafe === true ? { isConcurrencySafe: () => true } : {}),
     };
 }
-/**
- * 调用方 Agent session（官方注入，不可由模型伪造）。请求归属恒为当前调用者，
- * 不存在"代理请求"概念。workspace cwd 由 session.header.cwd 提供。
- */
-const callerSession = (exec) => {
-    const session = exec.agent?.session;
-    if (session)
-        return session;
-    throw new Error('this tool requires a calling agent session (exec.agent.session was undefined)');
-};
-const delegatedSession = (exec, toolName) => {
-    const session = callerSession(exec);
-    if (typeof session.header?.parentSession !== 'string' || session.header.parentSession.length === 0) {
-        throw new Error(`${toolName} is restricted to delegated data agents; the main Agent must delegate this request`);
-    }
-    return session;
-};
-/** dc_status 真实执行计数（进程内递增，返回给模型可见）。 */
 const dcStatusCalls = { current: 0 };
 function capabilityError(code, detail) {
     const error = new Error(`${code}: ${detail}`);
@@ -91,11 +70,7 @@ function errorCode(error) {
         ? error.code
         : undefined;
 }
-/**
- * 数据源在 normalizeParams 阶段抛出的错误对模型来说都是可修正的参数错误。
- * 保留数据源的字段级原因，同时把恢复动作固定成一次 describe -> 修正 -> 重试，
- * 避免子 Agent 只看到 "must be ..." 后凭记忆反复猜参数。
- */
+/** normalizeParams errors are model-fixable: keep the field reason and pin recovery to describe -> fix -> retry. */
 function requestParamsError(error, capability) {
     if (errorCode(error))
         return undefined;
@@ -145,7 +120,7 @@ export function registerDataCollectorTools(ctx, hub, diagnostics) {
             task_id: { type: 'string' },
         }, ['capability', 'params', 'task_id']), datasetRefSchema(), async (args, exec) => {
             const requestedCapability = boundedString(args.capability, 'capability', MAX_ID_LENGTH);
-            const session = delegatedSession(exec, 'request_data');
+            const session = authorizedSession(ctx, exec, 'request_data', DATA_COLLECTION_PRESET_IDS);
             try {
                 const params = boundedParams(args.params);
                 // Fail early with the same catalog guidance as describe_capability instead of
@@ -163,7 +138,7 @@ 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(); }, { concurrencySafe: true }),
+        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) => { authorizedSession(ctx, exec, 'list_capabilities', DATA_COLLECTION_PRESET_IDS); 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' },
@@ -172,7 +147,7 @@ export function registerDataCollectorTools(ctx, hub, diagnostics) {
             input_schema: freeObject,
             output_fields: { oneOf: [{ type: 'string' }, { type: 'null' }] },
         }, ['capability', 'summary', 'paginated', 'description', 'input_schema', 'output_fields']), async (args, exec) => {
-            delegatedSession(exec, 'describe_capability');
+            authorizedSession(ctx, exec, 'describe_capability', DATA_COLLECTION_PRESET_IDS);
             const capability = resolveCapability(hub, args.capability);
             const detail = hub.describeCapability(capability);
             if (!detail)
@@ -180,28 +155,36 @@ export function registerDataCollectorTools(ctx, hub, diagnostics) {
             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({
+            tool('dc_status', '诊断工具：返回数据管道运行状态 —— at/call 为本次真实执行的时间戳与计数（防伪）、api_key 为**本次调用现取**的凭据解析结果（present/source，不含密钥值）、registered_capabilities 为当前已注册 capability 列表、agent_tool_policy 为工具面收敛的现场记录（preset_id / root / outcome / allowed / denied / failed：`outcome=restricted` 是组合期那次减名字的账，`guard-denied` 是一次调用真的被调用级闸门拦下（`ocr` 的 url 形态、`write` / `edit`、角色的 `interrupt_agent`），`not-capital` / `skipped` / `unavailable` / `pending` 是四种没生效的原因；`root=true` 是用户手开出来的会话。工具面本身由该 preset 挂的工具行决定，allowed 恒为空。排查"某个 Agent 为什么看得见、或为什么用不了某颗工具"用）、session_identity 为最近的工具授权判据现场（tool / via=preset|topology / preset_id / allowed；`via:"topology"` 表示 registry 读不到身份、回落到"必须是被委派的子会话"这一旧判据）。数据源注册不依赖 key：api_key.present=false 时同花顺能力仍在目录里，但每次取数会点名 FUYAO_API_KEY 失败。排障时优先调用。', jsonObject(), jsonObject({
                 at: { type: 'integer' },
                 call: { type: 'integer' },
                 api_key: jsonObject({ present: { type: 'boolean' }, source: { oneOf: [{ type: 'string' }, { type: 'null' }] }, error: { oneOf: [{ type: 'string' }, { type: 'null' }] } }, ['present']),
                 registered_capabilities: { type: 'array', items: { type: 'string' } },
-                root_tool_policy: { type: 'array', items: jsonObject({
+                agent_tool_policy: { type: 'array', items: jsonObject({
                         agent_id: { oneOf: [{ type: 'string' }, { type: 'null' }] },
                         root: { type: 'boolean' },
                         preset_id: { type: 'string' },
                         outcome: { type: 'string' },
+                        allowed: { type: 'array', items: { type: 'string' } },
                         denied: { type: 'array', items: { type: 'string' } },
                         failed: { type: 'array', items: { type: 'string' } },
-                    }, ['agent_id', 'root', 'preset_id', 'outcome', 'denied', 'failed']) },
+                    }, ['agent_id', 'root', 'preset_id', 'outcome', 'allowed', 'denied', 'failed']) },
+                session_identity: { type: 'array', items: jsonObject({
+                        tool: { type: 'string' },
+                        via: { type: 'string' },
+                        preset_id: { oneOf: [{ type: 'string' }, { type: 'null' }] },
+                        allowed: { type: 'boolean' },
+                    }, ['tool', 'via', 'preset_id', 'allowed']) },
             }, ['at', 'call', 'api_key', 'registered_capabilities']), async (_args, exec) => {
-                delegatedSession(exec, 'dc_status');
+                authorizedSession(ctx, exec, 'dc_status', DATA_COLLECTION_PRESET_IDS);
                 const apiKey = await diagnostics.probeApiKey();
                 const capabilities = hub.capabilityNames();
-                const rootPolicy = diagnostics.rootPolicy?.()?.map((probe) => ({
+                const agentToolPolicy = diagnostics.rootPolicy?.()?.map((probe) => ({
                     agent_id: probe.agentId ?? null,
                     root: probe.root,
                     preset_id: probe.presetId,
                     outcome: probe.outcome,
+                    allowed: probe.allowed ?? [],
                     denied: probe.denied,
                     failed: probe.failed,
                 }));
@@ -212,7 +195,15 @@ export function registerDataCollectorTools(ctx, hub, diagnostics) {
                     call: snapshot.call,
                     api_key: apiKey,
                     registered_capabilities: capabilities,
-                    ...(rootPolicy === undefined ? {} : { root_tool_policy: rootPolicy }),
+                    ...(agentToolPolicy === undefined ? {} : { agent_tool_policy: agentToolPolicy }),
+                    // Authorization decision trail: preset identity vs fallback to session topology; without
+                    // it, "identity unavailable" and "identity confirmed" look identical to the model.
+                    session_identity: sessionIdentityDecisions().map((record) => ({
+                        tool: record.tool,
+                        via: record.via,
+                        preset_id: record.presetId,
+                        allowed: record.allowed,
+                    })),
                 };
             }),
         ] : []),
@@ -220,7 +211,7 @@ export function registerDataCollectorTools(ctx, hub, diagnostics) {
     for (const definition of registrations)
         ctx.effect(() => tools.register(definition), `capital-generation.tool(${definition.name})`);
 }
-/** 供测试与宿主侧断言复用：模型可见的 DatasetRef 字段白名单。 */
+/** Model-visible DatasetRef field whitelist (tests and host assertions). */
 export const DATASET_REF_FIELDS = [
     'dataset_id', 'task_id', 'session_id', 'artifact_ref', 'format',
     'capability', 'source_label', 'schema', 'row_count', 'captured_at',

package/lib/dataset-read-entry.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `tools/dataset-read` row: describe / inspect / profile / query_dataset.
+ * Each row builds its own store (no shared memory state; a shared hub would collide).
+ * Raw rows never leave these tools — only summaries, structure and controlled aggregates.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "capital-dataset-read-tools";
+export declare const inject: string[];
+export declare function apply(ctx: Context): void;

package/lib/dataset-read-entry.js

@@ -0,0 +1,7 @@
+import { registerDatasetTools } from './data-collector/dataset-tools.js';
+import { capitalDatasetStore } from './runtime.js';
+export const name = 'capital-dataset-read-tools';
+export const inject = ['tools'];
+export function apply(ctx) {
+    registerDatasetTools(ctx, capitalDatasetStore(ctx));
+}

package/lib/index.d.ts

@@ -1,97 +1,19 @@
 import { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import { type SelectedSkillSelection } from './agents/selected-skills-provider.js';
-/** Internal plugin name used by the Capital mode preset. */
+import { type RetrieverConfig } from './retriever-config.js';
+export { LOCAL_FETCH_DEFAULTS, PADDLE_OCR_DEFAULTS, resolveLocalFetchConfig, type LocalFetchConfig, type PaddleOcrConfig, type RetrieverConfig, type WindDocsConfig, } from './retriever-config.js';
+export { resolveUserCustomizationSection } from './user-customization.js';
 export declare const name = "capital-generation";
-/**
- * 取数配置所在的 **profile 条目 id**（随包的 `capital-config` 行）。0.1.7 的 settings 面
- * 以条目 id 为命名空间，本插件经 `settings.describe()` 按它读回用户配的引用名与开关。
- *
- * 这个字符串有三处必须一致：`cordis.patch.yml` 的行 id、`config/index.js` 的
- * `SETTINGS_ENTRY_ID`、以及浏览器半边 `client.src.cjs` 的 `ENTRY_ID`；由
- * `test/capital-config.test.mjs` 逐一对齐（漂移的表现为卡片静默消失）。
- */
+/** Entry id shared by `cordis.patch.yml`, `config/index.js` and `client.src.cjs`; drift hides the settings card. */
 export declare const CAPITAL_CONFIG_ENTRY_ID = "capital-config";
-/** Wind 文档检索配置：JSON-RPC 端点与凭据名（线格式为 MCP 线协议，零依赖适配）。 */
-export interface WindDocsConfig {
-    endpoint?: string;
-    credentialRef?: string;
-    timeoutMs?: number;
-}
-/** 本地直连回退配置（AnySearch 明确失败后改由本机直连抓取公开文本页面）。 */
-export interface LocalFetchConfig {
-    enabled?: boolean;
-    timeoutMs?: number;
-    maxBytes?: number;
-    maxContentChars?: number;
-    maxRedirects?: number;
-    userAgent?: string;
-}
-/**
- * PaddleOCR 文档解析（`ocr` 工具）配置。
- *
- * `endpoint` / `model` 空值 = 用 `src/ocr/client.ts` 里的官方端点与模型名（真值只在那一处，
- * 与 `windDocs.endpoint` 同一口径）。`pollBudgetMs` 是**工具内部**等作业的自有预算，
- * 必须小于工具声明的 `timeoutMs: 240000`——余量留给"决定回 pending 之后把回执写出去"，
- * 撞上框架超时就没有 `doc_id` 可续查了。
- */
-export interface PaddleOcrConfig {
-    endpoint?: string;
-    credentialRef?: string;
-    model?: string;
-    pollBudgetMs?: number;
-}
-/** web_retriever 会话配置：anysearch（广度）+ wind_docs（public_document 精准）+ 文档解析。 */
-export interface RetrieverConfig {
-    baseURL?: string;
-    credentialRef?: string;
-    windDocs?: WindDocsConfig;
-    localFetch?: LocalFetchConfig;
-    paddleOcr?: PaddleOcrConfig;
-}
-/**
- * 本地直连回退的默认值（唯一真值来源）：schema 的 `.default()` 与消费点
- * `resolveLocalFetchConfig()` 都引用它，两处不再各写一份字面量。
- *
- * 数值口径对齐官方 `dsh-web-fetch-http`（DSH 自己的同类本机抓取器）：
- * - `timeoutMs` = 30000（官方默认）。2026-09 实测：环境代理的故障转移慢路径约
- *   15.2–15.4s，15s 预算会把证券业协会官网这类站点误判成 TIMEOUT。
- * - `maxContentChars` = 100000（官方 `maxBodyChars` 默认值）。注意它切的是**转换前的
- *   原始 HTML**（见 `html-markdown.ts`），而 markdown 输出只有 HTML 的 12–33%，
- *   所以这个数必须按 HTML 体积给足；20,000 会把 109KB 的页面腰斩到 18%。
- *
- * `userAgent` 默认是产品标识（`@v587d/capital-generation`）：裸版本号是
- * WAF 眼里的典型爬虫特征。显式配成空串时消费点回落到 `LOCAL_FETCH_CLIENT_VERSION`
- * （版本号真值仍只有一处，由测试守着等于 `package.json` 的 version）。
- */
-export declare const LOCAL_FETCH_DEFAULTS: Required<LocalFetchConfig>;
-/**
- * `ocr`（PaddleOCR 文档解析）配置的默认值：与 `LOCAL_FETCH_DEFAULTS` 同一口径，
- * schema 的 `.default()` 与消费点都引用它，字面量只有一处。
- *
- * `endpoint` / `model` 留空是把真值让给 `src/ocr/client.ts`（那边还有 `PADDLE_OCR_MAX_PAGES`
- * 这类跟着端点走的常数）；`pollBudgetMs: 0` 同理让给客户端的 `DEFAULT_WAIT_BUDGET_MS`。
- */
-export declare const PADDLE_OCR_DEFAULTS: Required<PaddleOcrConfig>;
-/**
- * 消费点独立补齐默认值。`apply()` 在无 settings 的宿主/测试里拿到的是**未过 schema**
- * 的原始对象，`retriever.localFetch` 可能是 `undefined`，因此消费点不能依赖 schema 补默认值。
- */
-export declare function resolveLocalFetchConfig(config?: LocalFetchConfig): Required<LocalFetchConfig>;
-/** Configuration accepted by the Capital Generation plugin. */
 export interface Config {
-    /** Optional additive persona override; core safety guidance is preserved. */
     customPersona?: string;
-    /** Community experiments explicitly selected for the Capital root Agent only. */
     selectedSkills?: SelectedSkillSelection;
-    /** Fuyao credentials 引用名；空值回退到 FUYAO_API_KEY。 */
     fuyaoCredentialRef?: string;
-    /** FTShare（非凸科技）credentials 引用名；空值回退到 FTSHARE_API_KEY。 */
     ftshareCredentialRef?: string;
-    /** web_retriever 配置（可选；缺省使用 AnySearch 默认地址与凭据名）。 */
     retriever?: RetrieverConfig;
 }
-/** DSH 0.1.2-rc.1 configuration schema. */
 export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     customPersona: z<string, string, "defined">;
     selectedSkills: z<Schemastery.ObjectS<NoInfer<{
@@ -266,44 +188,12 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     }>>, "defined">;
 }>>, "plain">;
 export type CapitalSettingsSource = 'settings-describe' | 'config-editor' | 'preset';
-/**
- * 读取 `capital-config` 条目的生效配置。三级取数、逐级兜底：
- *  1. `settings.describe()`：活动条目的已应用视图（0.1.7 官方读回面）；
- *  2. `configEditor.entries()` 的条目保存层：设置卡写入的就是这层（complete raw config）。
- *     describe() 在条目 fiber 未挂好的窗口会**整个跳过条目**，用户已保存的值仍然在这里可读；
- *  3. preset 配置兜底，且必须可辨认（`source === 'preset'`）——"读不到"不许伪装成"用户全关"。
- *
- * ⛔ 服务引用一律**调用期现取**（AGENTS.md §9.7）：装配期 `ctx.get()` 押的是"宿主服务已注册"
- * 这个外部时刻——boot 里各 fiber 并行 apply，settings / configEditor 晚于本插件注册时，装配期
- * 捕获到 undefined，整场进程会静默降级成 preset 默认。2026-10-13 复盘（session-bb8635a1：
- * 07:51 保存 10 个开关、07:54 建会话读到全关、08:30 重组后同一条读取路径立刻读对）就是这一族。
- */
+/** Fallback order: settings.describe → configEditor.entries → boot preset, so unreadable never
+ * reads as "all toggles off". Resolve services per call: boot fibers apply in parallel. */
 export declare function readCapitalSettings(ctx: Context, bootConfig: Config): {
     config: Config;
     source: CapitalSettingsSource;
 };
-/**
- * 把可选的用户人设文本转成独立 system-prompt section（官方 systemPrompt
- * registry 的注册对象）。空白输入返回 undefined（不注册）；超长抛错；
- * 追加不可覆盖的安全提醒。只影响表达风格与呈现。
- */
-export declare function resolveUserCustomizationSection(customPersona?: string): {
-    name: string;
-    order: number;
-    text: string;
-} | undefined;
-/** The system-prompt service is a hard dependency for the optional section. */
+/** `systemPrompt` is a hard dependency of the optional persona section. */
 export declare const inject: string[];
-/**
- * Register the Capital mode data services and tools.
- *
- * 人设文本全部由 preset 组合承载（dsh-persona 行 + 两个委派行 config.persona），
- * 不在插件代码中。本包只装配服务与工具：
- *  - datasetStore（workspace-local Dataset 持久化，7 天保留，权限失败显式报错）
- *  - dataCollectorHub（阻塞 FIFO + in-flight 合并，成功后由 store 立即落盘，
- *    只回传 DatasetRef，不保留长期 raw 缓存）
- *  - 无状态 AnySearch 网页检索（单查询 search + 单 URL fetch）
- *  - 无状态 Wind 文档检索客户端（public_document：公告/年报/招股书与权威新闻）
- *  - 各自的模型工具；时间工具。
- */
 export declare function apply(ctx: Context, config: Config): void;