@v587d/capital-generation 0.0.0-stage → 2.6.0

package/lib/web-retriever/wind-client.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Wind 金融文档检索客户端（JSON-RPC over HTTP，零依赖）。
+ *
+ * 线格式为 JSON-RPC 2.0（即 MCP 线协议）：initialize → tools/call，无会话态、
+ * 无 SDK、无框架依赖——与 fuyao-rest / anysearch engines 同构的普通 HTTP 客户端。
+ * 协议蓝本（Wind 官方 CLI）：github.com/Wind-Alice/AliceMarket 的
+ * skills/wind-mcp-skill/scripts/cli.mjs（本地参考副本在 docs/reference/，不入库）。
+ */
+export declare const DEFAULT_WIND_ENDPOINT = "https://mcp.wind.com.cn/vserver_financial_docs/mcp/";
+export declare const WIND_REQUEST_TIMEOUT_MS = 60000;
+export declare const WIND_MAX_CONTENT_CHARS = 20000;
+/**
+ * 七台托管 MCP server 的端点（`server_type` → URL）。
+ *
+ * 这里是**事实**（端点常量），不是代码搬运：上游仓库未声明 LICENSE，蓝本
+ * （官方 CLI 的 `SERVERS` 表）按惯例只作本地参考副本、不入库，见
+ * `docs/design/wind-market-source.md` §1.1。
+ *
+ * `analytics_data` 一并列出是为了记下"它存在但不可用"：2026-10-05 实测连 `initialize`
+ * 都挂满 60 秒（同文档 §6.1），所以数据源侧不接它。
+ */
+export declare const WIND_SERVER_ENDPOINTS: {
+    readonly stock_data: "https://mcp.wind.com.cn/vserver_stock_data/mcp/";
+    readonly fund_data: "https://mcp.wind.com.cn/vserver_fund_data/mcp/";
+    readonly index_data: "https://mcp.wind.com.cn/vserver_index_data/mcp/";
+    readonly bond_data: "https://mcp.wind.com.cn/vserver_bond_data/mcp/";
+    readonly financial_docs: "https://mcp.wind.com.cn/vserver_financial_docs/mcp/";
+    readonly economic_data: "https://mcp.wind.com.cn/vserver_economic_data/mcp/";
+    readonly analytics_data: "https://mcp.wind.com.cn/vserver_analytics_data/mcp/";
+};
+export type WindServerType = keyof typeof WIND_SERVER_ENDPOINTS;
+/**
+ * 错误分类（persona/主 Agent 依据它决定 fallback）：
+ * AUTH=Key 缺失或无效；RATE_LIMIT=429；NETWORK=网络错误/5xx/超时；
+ * BACKEND=接口层与业务错误；INVALID=响应不可解析。
+ */
+export type WindErrorCode = 'AUTH' | 'RATE_LIMIT' | 'NETWORK' | 'BACKEND' | 'INVALID';
+export interface WindCallResult {
+    ok: boolean;
+    /** 成功且正文可解析为 JSON 时：Wind 返回结果（字符串字段裁剪到 WIND_MAX_CONTENT_CHARS）。 */
+    data?: unknown;
+    /** 成功但正文非 JSON 时：原文透传（≤WIND_MAX_CONTENT_CHARS）。 */
+    content?: string;
+    content_chars?: number;
+    error?: string;
+    code?: WindErrorCode;
+}
+/**
+ * 报给 Wind 的客户端版本（`initialize.clientInfo.version` 与 `tools/call._meta.clientVersion`）。
+ *
+ * ⚠️ 必须与 `package.json` 的 `version` 一致：嵌套包 `chart-ui/package.json` 的版本由
+ * `test/chart-composition.test.mjs` 守着（会因漂移而失败），这里原本是写死的第二处，
+ * 一次发版就得记得改两遍。所以本常量由测试一并核对（见 `test/wind-client.test.mjs`）。
+ */
+export declare const WIND_CLIENT_VERSION = "2.6.0";
+export interface WindClient {
+    callTool(toolName: string, args: Record<string, unknown>, signal?: AbortSignal): Promise<WindCallResult>;
+}
+export interface WindClientOptions {
+    endpoint?: string;
+    /** 每次调用重新解析 Key，不缓存（与 anysearch engines 同策略）。 */
+    resolveApiKey: () => Promise<string | undefined>;
+    /** 单次请求超时毫秒（initialize 与 tools/call 各自适用）；默认 60000。 */
+    timeoutMs?: number;
+    /** 网络错误重试间隔毫秒；默认 [300, 1000]，仅供测试注入缩短。 */
+    retryDelaysMs?: number[];
+}
+/** 创建 Wind 文档检索客户端；端点在构造时校验（配置错误立即暴露，与 anysearch 同策略）。 */
+export declare function createWindClient(options: WindClientOptions): WindClient;

package/lib/web-retriever/wind-client.js

@@ -0,0 +1,311 @@
+/**
+ * Wind 金融文档检索客户端（JSON-RPC over HTTP，零依赖）。
+ *
+ * 线格式为 JSON-RPC 2.0（即 MCP 线协议）：initialize → tools/call，无会话态、
+ * 无 SDK、无框架依赖——与 fuyao-rest / anysearch engines 同构的普通 HTTP 客户端。
+ * 协议蓝本（Wind 官方 CLI）：github.com/Wind-Alice/AliceMarket 的
+ * skills/wind-mcp-skill/scripts/cli.mjs（本地参考副本在 docs/reference/，不入库）。
+ */
+export const DEFAULT_WIND_ENDPOINT = 'https://mcp.wind.com.cn/vserver_financial_docs/mcp/';
+export const WIND_REQUEST_TIMEOUT_MS = 60_000;
+export const WIND_MAX_CONTENT_CHARS = 20_000;
+/**
+ * 七台托管 MCP server 的端点（`server_type` → URL）。
+ *
+ * 这里是**事实**（端点常量），不是代码搬运：上游仓库未声明 LICENSE，蓝本
+ * （官方 CLI 的 `SERVERS` 表）按惯例只作本地参考副本、不入库，见
+ * `docs/design/wind-market-source.md` §1.1。
+ *
+ * `analytics_data` 一并列出是为了记下"它存在但不可用"：2026-10-05 实测连 `initialize`
+ * 都挂满 60 秒（同文档 §6.1），所以数据源侧不接它。
+ */
+export const WIND_SERVER_ENDPOINTS = {
+    stock_data: 'https://mcp.wind.com.cn/vserver_stock_data/mcp/',
+    fund_data: 'https://mcp.wind.com.cn/vserver_fund_data/mcp/',
+    index_data: 'https://mcp.wind.com.cn/vserver_index_data/mcp/',
+    bond_data: 'https://mcp.wind.com.cn/vserver_bond_data/mcp/',
+    financial_docs: DEFAULT_WIND_ENDPOINT,
+    economic_data: 'https://mcp.wind.com.cn/vserver_economic_data/mcp/',
+    analytics_data: 'https://mcp.wind.com.cn/vserver_analytics_data/mcp/',
+};
+/**
+ * 报给 Wind 的客户端版本（`initialize.clientInfo.version` 与 `tools/call._meta.clientVersion`）。
+ *
+ * ⚠️ 必须与 `package.json` 的 `version` 一致：嵌套包 `chart-ui/package.json` 的版本由
+ * `test/chart-composition.test.mjs` 守着（会因漂移而失败），这里原本是写死的第二处，
+ * 一次发版就得记得改两遍。所以本常量由测试一并核对（见 `test/wind-client.test.mjs`）。
+ */
+export const WIND_CLIENT_VERSION = '2.6.0';
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+class WindTransportError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/** HTTP 状态 → 错误分类（蓝本 HTTP_ERROR_MAP；其余状态一律 NETWORK）。 */
+const HTTP_ERROR_CODES = {
+    401: 'AUTH',
+    429: 'RATE_LIMIT',
+    500: 'NETWORK',
+    502: 'NETWORK',
+    503: 'NETWORK',
+    504: 'NETWORK',
+};
+const RETRY_ATTEMPTS = 3;
+const DEFAULT_RETRY_DELAYS_MS = [300, 1_000];
+function normalizeEndpoint(endpoint) {
+    const raw = (endpoint ?? DEFAULT_WIND_ENDPOINT).trim();
+    try {
+        const url = new URL(raw);
+        if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+            throw new Error('endpoint must use http or https');
+        }
+    }
+    catch (error) {
+        throw new Error(`invalid Wind endpoint: ${errorText(error)}`);
+    }
+    return raw;
+}
+/** 响应可能是纯 JSON 或 SSE（取最后一个 data: 行）；蓝本 parseSSE 的等价实现。 */
+function parseResponsePayload(text) {
+    const trimmed = text.trim();
+    if (trimmed.startsWith('{')) {
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch {
+            // 非 JSON 对象落到下面的 SSE 解析。
+        }
+    }
+    let last;
+    for (const line of text.split(/\r?\n/)) {
+        if (line.startsWith('data: '))
+            last = line.slice('data: '.length);
+    }
+    if (last !== undefined) {
+        try {
+            return JSON.parse(last);
+        }
+        catch (error) {
+            throw new Error(`SSE data 行 JSON 解析失败：${errorText(error)}；原文前 200 字符：${text.slice(0, 200)}`);
+        }
+    }
+    throw new Error(`响应格式无法识别（既非 JSON 也非 SSE）；原文前 200 字符：${text.slice(0, 200)}`);
+}
+/** 深度裁剪：对象/数组内的字符串字段超过上限时截断（保持结构；超长响应另有 harness 剪枝兜底）。 */
+function trimDeep(value, maxChars) {
+    if (typeof value === 'string')
+        return value.length > maxChars ? value.slice(0, maxChars) : value;
+    if (Array.isArray(value))
+        return value.map((item) => trimDeep(item, maxChars));
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [key, item] of Object.entries(value)) {
+            out[key] = trimDeep(item, maxChars);
+        }
+        return out;
+    }
+    return value;
+}
+function firstContentText(result) {
+    const content = result.content;
+    if (!Array.isArray(content) || content.length === 0)
+        return undefined;
+    const first = content[0];
+    if (first && typeof first === 'object' && !Array.isArray(first)) {
+        const record = first;
+        if (record.type === 'text' && typeof record.text === 'string')
+            return record.text;
+    }
+    return undefined;
+}
+/** JSON-RPC error 字段 → 可读文本。 */
+function rpcErrorText(payload) {
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload))
+        return undefined;
+    const record = payload;
+    if (record.error === undefined || record.error === null)
+        return undefined;
+    const error = record.error;
+    if (typeof error === 'string' && error)
+        return error;
+    if (error && typeof error === 'object' && !Array.isArray(error)) {
+        const message = error.message;
+        if (typeof message === 'string' && message)
+            return message;
+    }
+    return JSON.stringify(error).slice(0, 2_000);
+}
+/**
+ * 三层业务错误解包（蓝本 mcpRequest 后半段）：Wind 把业务错误包在 content[0].text
+ * 的 JSON 字符串里，必须二次解析——mcp_tool_error_code / error{} / data.code 三种形态。
+ */
+function innerBusinessError(data) {
+    if (!data || typeof data !== 'object' || Array.isArray(data))
+        return undefined;
+    const record = data;
+    const toolErrorCode = record.mcp_tool_error_code;
+    if (typeof toolErrorCode === 'number' && toolErrorCode !== 0) {
+        return typeof record.mcp_tool_error_msg === 'string' && record.mcp_tool_error_msg
+            ? record.mcp_tool_error_msg
+            : JSON.stringify(record).slice(0, 2_000);
+    }
+    if (record.error && typeof record.error === 'object' && !Array.isArray(record.error)) {
+        const nested = record.error;
+        if (nested.code !== undefined || nested.message !== undefined) {
+            return (typeof nested.message === 'string' && nested.message) || JSON.stringify(nested).slice(0, 2_000);
+        }
+    }
+    if (record.data && typeof record.data === 'object' && !Array.isArray(record.data)) {
+        const nested = record.data;
+        const numeric = typeof nested.code === 'number'
+            ? nested.code
+            : typeof nested.code === 'string' && /^\d+$/.test(nested.code.trim())
+                ? Number(nested.code.trim())
+                : null;
+        const success = numeric === null || numeric === 0 || (numeric >= 200 && numeric < 300);
+        if (!success) {
+            return (typeof nested.message === 'string' && nested.message) || JSON.stringify(nested).slice(0, 2_000);
+        }
+    }
+    return undefined;
+}
+/** JSON-RPC result → WindCallResult：含 isError 与内层业务错误解包。 */
+function interpretResult(payload) {
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+        return { ok: false, code: 'INVALID', error: 'Wind 返回不可解析（非 JSON-RPC 对象）' };
+    }
+    const rpcError = rpcErrorText(payload);
+    if (rpcError)
+        return { ok: false, code: 'BACKEND', error: rpcError };
+    const result = payload.result;
+    if (!result || typeof result !== 'object' || Array.isArray(result)) {
+        return { ok: false, code: 'INVALID', error: 'Wind 返回缺少 result' };
+    }
+    const resultRecord = result;
+    if (resultRecord.isError === true) {
+        const text = firstContentText(resultRecord);
+        return { ok: false, code: 'BACKEND', error: text ?? JSON.stringify(resultRecord).slice(0, 2_000) };
+    }
+    const innerText = firstContentText(resultRecord);
+    if (innerText === undefined) {
+        return { ok: false, code: 'INVALID', error: 'Wind 返回缺少 content[0].text 文本' };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(innerText);
+    }
+    catch {
+        parsed = undefined;
+    }
+    if (parsed === undefined) {
+        const content = innerText.slice(0, WIND_MAX_CONTENT_CHARS);
+        return { ok: true, content, content_chars: content.length };
+    }
+    const businessError = innerBusinessError(parsed);
+    if (businessError)
+        return { ok: false, code: 'BACKEND', error: businessError };
+    return { ok: true, data: trimDeep(parsed, WIND_MAX_CONTENT_CHARS) };
+}
+/** 创建 Wind 文档检索客户端；端点在构造时校验（配置错误立即暴露，与 anysearch 同策略）。 */
+export function createWindClient(options) {
+    const endpoint = normalizeEndpoint(options.endpoint);
+    const timeoutMs = options.timeoutMs && options.timeoutMs > 0 ? options.timeoutMs : WIND_REQUEST_TIMEOUT_MS;
+    const retryDelaysMs = options.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS;
+    let nextId = 1;
+    async function postOnce(method, params, apiKey, signal) {
+        if (signal?.aborted)
+            throw new WindTransportError('NETWORK', 'Wind 请求已取消');
+        const controller = new AbortController();
+        const onExternalAbort = () => controller.abort(signal?.reason);
+        signal?.addEventListener('abort', onExternalAbort, { once: true });
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort(new Error('Wind request timed out'));
+        }, timeoutMs);
+        try {
+            const response = await fetch(endpoint, {
+                method: 'POST',
+                redirect: 'error',
+                headers: {
+                    accept: 'application/json, text/event-stream',
+                    'content-type': 'application/json',
+                    authorization: `Bearer ${apiKey}`,
+                },
+                body: JSON.stringify({ jsonrpc: '2.0', id: nextId++, method, params }),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                await response.text().catch(() => '');
+                throw new WindTransportError(HTTP_ERROR_CODES[response.status] ?? 'NETWORK', `Wind HTTP ${response.status}`);
+            }
+            return parseResponsePayload(await response.text());
+        }
+        catch (error) {
+            if (timedOut)
+                throw new WindTransportError('NETWORK', `Wind 请求超时（${timeoutMs}ms）`);
+            throw error;
+        }
+        finally {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onExternalAbort);
+        }
+    }
+    /** 网络级错误按退避重试；HTTP 状态错误与调用方取消不重试（蓝本同款行为）。 */
+    async function postRpc(method, params, apiKey, signal) {
+        let lastError;
+        for (let attempt = 1; attempt <= RETRY_ATTEMPTS; attempt += 1) {
+            try {
+                return await postOnce(method, params, apiKey, signal);
+            }
+            catch (error) {
+                if (error instanceof WindTransportError)
+                    throw error;
+                if (signal?.aborted)
+                    throw error;
+                lastError = error;
+                if (attempt < RETRY_ATTEMPTS) {
+                    const delayMs = retryDelaysMs[Math.min(attempt - 1, retryDelaysMs.length - 1)];
+                    if (delayMs > 0)
+                        await new Promise((resolve) => setTimeout(resolve, delayMs));
+                }
+            }
+        }
+        throw new WindTransportError('NETWORK', `Wind 请求失败（已重试 ${RETRY_ATTEMPTS - 1} 次）：${errorText(lastError)}`);
+    }
+    return {
+        async callTool(toolName, args, signal) {
+            try {
+                const apiKey = await options.resolveApiKey();
+                if (!apiKey) {
+                    return { ok: false, code: 'AUTH', error: 'Wind API Key 未配置（credentials 与环境变量均未提供）' };
+                }
+                const initialized = await postRpc('initialize', {
+                    protocolVersion: '2025-03-26',
+                    capabilities: {},
+                    clientInfo: { name: 'capital-generation', version: WIND_CLIENT_VERSION },
+                }, apiKey, signal);
+                const initError = rpcErrorText(initialized);
+                if (initError)
+                    return { ok: false, code: 'BACKEND', error: initError };
+                const payload = await postRpc('tools/call', {
+                    name: toolName,
+                    arguments: args,
+                    _meta: { clientVersion: WIND_CLIENT_VERSION },
+                }, apiKey, signal);
+                return interpretResult(payload);
+            }
+            catch (error) {
+                if (error instanceof WindTransportError) {
+                    return { ok: false, code: error.code, error: error.message };
+                }
+                return { ok: false, code: 'INVALID', error: `Wind 调用失败：${errorText(error)}` };
+            }
+        },
+    };
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Capital Generation",
+    "description": "Securities research plugin for A-share investors: market and financial data, filings, news, analysis and charts. Choose Capital mode in a new session."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Capital Generation（证券研究）",
+    "description": "面向 A 股个人投资者的证券研究插件：查行情与财务数据、看公告和新闻、做分析、出图表。安装后在新会话选择 Capital 模式。"
+  }
+}

package/package.json

@@ -1,6 +1,78 @@
 {
   "name": "@v587d/capital-generation",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.6.0",
+  "description": "Capital Generation：面向中国散户的 AI 投资助手插件(Capital mode Agent Preset）",
+  "icon": "assets/cg-icon.png",
+  "author": "v587d",
+  "license": "MIT",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json"
+  },
+  "files": [
+    "lib",
+    "locale",
+    "chart-ui",
+    "capital-config",
+    "capital-watchlist",
+    "preset",
+    "cordis.patch.yml",
+    "assets/cg-icon.png",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": [
+        "./cordis.patch.yml",
+        "./preset/capital-generation/agent.patch.yml"
+      ]
+    }
+  },
+  "scripts": {
+    "clean": "node -e \"import('node:fs').then(({ rmSync }) => rmSync('lib', { recursive: true, force: true }))\"",
+    "build": "npm run clean && tsc && node scripts/copy-assets.mjs && npm run build:client && npm run build:config-client && npm run build:watchlist-client",
+    "build:client": "node scripts/build-client.mjs",
+    "build:config-client": "node scripts/build-capital-config-client.mjs",
+    "build:watchlist-client": "node scripts/build-capital-watchlist-client.mjs",
+    "dev": "tsc -w",
+    "vendor:charts": "node scripts/vendor-lightweight-charts.mjs",
+    "check:dsh": "node scripts/check-dsh-compat.mjs",
+    "demo:chart": "npm run build && node scripts/chart-demo.mjs",
+    "smoke:boot": "node scripts/smoke-boot.mjs",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepublishOnly": "npm run build",
+    "smoke:fuyao": "node scripts/smoke-fuyao.mjs",
+    "smoke:wind": "node scripts/smoke-wind.mjs",
+    "smoke:local-fetch": "node scripts/smoke-local-fetch.mjs",
+    "docs:capabilities": "npm run build && node scripts/gen-capability-table.mjs",
+    "verify:sessions": "node scripts/verify-sessions.mjs",
+    "audit:tool-errors": "node scripts/audit-tool-errors.mjs"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.2.0-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.4",
+    "esbuild": "^0.28.2",
+    "js-yaml": "^5.4.1",
+    "lightweight-charts": "5.2.1",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.4",
+    "@joplin/turndown-plugin-gfm": "^1.0.68",
+    "turndown": "^7.2.4",
+    "zod": "^4.5.4"
+  }
+}

package/preset/capital-generation/README.md

@@ -0,0 +1,161 @@
+# Capital 模式 preset：组合设计说明
+
+本文件是 `agent.patch.yml`（那颗 `@deepseek-ai/dsh-agent-preset` 声明行）的**维护者文档**（人类可读），
+不是模型可见内容：`skill-filesystem` 只扫 `skills/`，本文件既不会进 skill 目录，也不会被注入上下文。
+组合文件里只留"就地必需"的一行注（realm、`!!js`、disabled 行），其余设计理由都在这里。
+
+- 本目录由 `@v587d/capital-generation` 随包分发，`agent.patch.yml` 走 `package.json` 的
+  `dsh.bundle.patch`（**数组**：主 patch + 这颗）以 `trust=system` 挂载；**不要**手抄进
+  `~/.dsh/.agent-presets`。
+- 长协议在 `skills/`（同目录），由本 preset 自己的 `skill-filesystem` 行发现；`capital-visualization-protocol` 同时供 data_junior 的 gate 和 visualization_specialist 按需加载。
+- visualization_specialist 是 data_junior 创建的 one-shot 前台子 Agent，不进入主 Agent 的 direct-child 复用清单；它只消费 chart_source_ref 并使用受控 render_chart。
+- 验证方式与"改 preset 前后的必做检查"见仓库根 `AGENTS.md` §8.3；设计理由与「不许改」全表见
+`docs/dev/preset-persona.md`。
+
+## 1. 平面纪律（plane discipline）
+
+- `subagents` 注册表与它的 spawn/fork 后端住在 **host 组合**；本 preset 只贡献模型侧的
+  委派工具行，它们解析 host 那一份注册表。本文件**没有**挂 `subagent_fork` 行，所以委派
+  永远是 continuable 的 `spawn` provider。
+- 本 preset 拥有的服务必须落在组行的 `isolate` realm 内（见第 4 节）；只消费 host 能力的
+  行必须留在 realm 外，否则解析不到服务。
+
+## 2. 人设（persona）承载与官方语义
+
+实测 `dsh 0.1.5-rc.1`，`0.1.7-rc.2` 复核字段未变（`test/persona.test.mjs` 对着本机 dsh 核对），
+三层载体注册的是**同一个 system-prompt 节名**：
+
+| 载体 | 位置 | 字段 | 生效范围 |
+|---|---|---|---|
+| `dsh-system-prompt` 行 | 部署（web profile） | `personaPrefix` / `personaSuffix` | 全局 |
+| `dsh-persona` 行 | 本 preset | `prefix`（必填）/ `suffix` / `complete` / `includeRuntimeContext` | preset 内全部 agent（主 + 子） |
+| `dsh-tool-subagent` 行 | 本 preset 委派行 | `config.persona` | 该子 Agent 自己 |
+
+- 节名是 `deployment:persona-prefix`（order 0）与 `deployment:persona-suffix`（order
+  10200）。**最近 scope 胜出 ⇒ 是覆盖不是追加**；`dsh-subagent` 把 `config.persona` 注册进
+  子 Agent 自己的 scope，所以子人设**替换**（不是扩展）主 persona。
+- `prefix`/`suffix` 是模板，渲染时对 `{{…}}` **严格插值**：未注册或 undefined 的变量会抛错。
+  `provider` / `model` / `cwd` 由 `dsh-agent-loop` 全局注册，可以直接用。
+- 本 preset **不设 `suffix`**：按官方语义，空模板**仍然遮蔽**部署级后缀，所以部署那句
+  `Your working directory is {{cwd}}.` 在 Capital 会话里不出现（主 persona 自己写了
+  `{{cwd}}`）。这是有意为之，不是漏配。
+- `complete: true` 会把其余所有段落（身份、工具引导、后缀）一并抑制；`includeRuntimeContext:
+  false` 全有全无地关掉沙箱/审批/委派等 runtime context。本 preset 都不用。
+- 成本：persona 正文每个请求都重复；`prefix` 变化会让 KV cache 从第一个变化 token 起失效。
+  所以正文按"每轮都要生效"的门槛收，参考材料一律外置。
+
+## 3. 按需协议：什么进 persona、什么进 skills/
+
+- **必须常驻 persona**：每轮预检、复用/创建判定、路由、权限边界、叶子边界、安全底线、
+  第一条 duty（先加载协议）、最小载荷骨架。这些要在"模型还不知道本轮要做什么"之前生效，
+  而 skill 只在模型决定加载时才生效。
+- **按需进 `skills/`**：载荷 JSON 样例、字段级规则、`error/code → 处置`表、四态事实怎么读、
+  QuerySpec 细则、检索收敛法则、官方域名核验清单、回传格式范例。
+- **子 Agent 也能按需加载**：子行的 `toolFilter.allow` 里写了 `skill`，子 Agent 就同时拿到
+  目录与加载器。判据在 `dsh-tools` 的 `view()`：restriction 过滤**继承层（全局 + 全部祖先
+  scope，含 preset 层）**，只豁免"本 scope 自己注册的"工具；而 `dsh-tool-skill` 发布目录的
+  条件正是 `ctx.tools.get('skill', agent) === 该注册对象`。源码注释里记着这段历史坑
+  （"Once presets moved them onto the agent plane they became an ANCESTOR contribution, so a
+  child's filter silently stopped constraining anything it was given"）——它既是"子 Agent
+  默认看不到 skill"的原因，也是放开它的唯一开关。
+- **维护者理由不进 `skills/`**：任何放在 `skills/` 的东西都会拿到一条常驻目录项
+  （name + ≤500 字 description）并可被模型加载。设计理由写在本文件。
+
+## 4. realm 与服务归属
+
+- `capital-generation-scope`（`cordis:group` + `isolate: { dataCollectorHub: true,
+  datasetStore: true }`）：插件 `apply` 里 `ctx.provide` 的两个服务是进程级名字，
+  必须按 session 隔离，否则第二个 Capital 会话注册时冲突。
+- `compaction` 组（`isolate: { compaction: true, toolResultPruner: true }`）：
+  `compaction-basic` 通过 `ctx.get` 读 `toolResultPruner`，两者必须同处一个 realm；
+  `tokenMeter` 留在宿主平面。
+- skills 注册表在 **host 平面并按 scope 分层**：`skill-filesystem` / `tool-skill` 只注册进
+  本 preset 那一层，**不需要** realm。
+- **图表前端组件（`capital-charts` 行）刻意在 host 平面、且不在任何 realm 里**：
+  客户端 bundle 必须在页面启动时就存在（boot graph 在 index.html 渲染时确定），
+  所以它不能是本 preset 的行。反过来，本插件的 `apply` 通过 `ctx.get('capitalCharts')`
+  消费它——`isolate` 只重映射**列出**的服务名（`cordis-plugin-loader/src/config/isolate.ts`：
+  `if (!label) return`），其余名字沿原型链向外解析，因此跨平面消费成立。
+  这一条与"realm 里的行不能消费外面的服务"并不矛盾：那条规则说的是**提供方**在 realm 内、
+  消费方在 realm 外的情况。
+- **时间轴换算不在 preset 里，在宿主插件里**（`src/data-collector/time-axis.ts`）。理由与
+  "为什么这几个服务归宿主"同源：它是**确定性计算**，且**有三个入口**必须共用同一份答案——
+  profile 写出的 `time_facts`（`store.ts`）、工具边界收到的日期筛选值（`dataset-tools.ts`）、
+  `resolve_data_time_range` 的 Dataset 形态（`time/tools.ts`）。写进 persona 或 skill 只会变成
+  "请模型自己算"的口头约定（实测单步思考 41,961 字符全是时间戳算术）；在 preset 侧再定义一个
+  模型工具则会把同一套偏移推断实现第二遍。放进宿主后，模型只需要写 `2026-08-23`。
+
+## 5. 各行的作用与坑
+
+- `agent-instructions`：注入 `AGENTS.md` / `CLAUDE.md`（宿主行在本 profile 被关，由 preset
+  自持，`maxBytes: 16384`）。没有它，工作区约定对 Capital 会话不可见。
+- `tool-result-pruner`：`thresholdChars: 8192`（head 4096 + tail 1024）。真实后果是
+  **能力目录与工具结果超过阈值时中间段被剪掉**；`test/data-collector-hub.test.mjs` 因此用
+  "目录 6144 + 单能力详情 4096"两道测试预算，让测试先失败而不是运行时静默截断。该阈值
+  **不能按 Agent 区分**（全仓只有这一个 pruner 实例），主/子 Agent 共用。
+- `toolFilter.allow` 只能写**真实注册**的全局工具名：`tools.restrict()` 对未知名字直接报错，
+  且它在**子 Agent 创建窗口**执行——写错的表现是"创建子 Agent 失败"，不是挂载失败。
+- **通用 `subagent` 行必须写 `toolFilter.deny`（2026-09 review）**：`dsh-subagent` 只在
+  `composition.toolFilter !== void 0` 时才 `restrict`，而 child 用 `composeFrom(childCtx,
+  parent.ctx)` 加入父 Agent **同一份 standing composition**，因此没有 filter 的通用 child
+  会继承 standing 的全部工具——只带 `parentSession` 的 child 就能自己 `prepare_chart_source`
+  再 `render_chart`，把"出图只有一个入口"降级成 persona 建议。这里的 `deny` 与子角色的
+  `allow` 不冲突：`allow`/`deny` 都只是继承层交集过滤，专用行各自的白名单照常生效。
+  通用行只能有一个 filter，所以用 `deny` 列全敏感工具（数据管线 + Dataset 系列 + 出图 +
+  专用角色创建工具）；`deny` 里的名字同样必须真实注册。回归断言见
+  `test/persona.test.mjs` 的「通用 subagent 行」用例。
+- **同一份 `deny` 也覆盖出网（2026-09-24）**：本插件 14 个检索 / 来源 / 文档解析工具全部列进来，否则只带
+  `parentSession` 的通用 child 能自己抓网页，「外部检索只经 web_retriever」又是一条 persona 文案。
+  名字的唯一事实来源是 `src/agents/root-tool-policy.ts` 的 `RETRIEVAL_DENIED_TOOLS`（根 Agent 逐名
+  deny 用的就是它），测试把两处对齐成同一份名单。**`ocr` 是根侧收敛的唯一例外（2026-09-26）**：它
+  不进 `RETRIEVAL_DENIED_TOOLS`（主 Agent 要能解析用户 `@` 进来的本地文档），改由调用级 guard 只拒
+  `url` 形态；但通用 child 的这份 `deny` 里它**必须在**——连本地形态一起拿掉，否则通用 child
+  继承它能自己解析文档（见 §4.3 → `docs/dev/web-retriever.md`）。**宿主自己挂的 `web_search` / `web_fetch` 绝不能
+  写进这里的 `deny`**：它们不由本插件注册，未注册名字在 `deny` 里的表现是"创建子 Agent 失败"；
+  它们只出现在根侧 `ROOT_AGENT_DENIED_TOOLS`（逐名 `restrict` 的 try/catch 容忍"这个 scope 里没有"）。
+- 不用 `dsh-time-context` 行：它每个 step 自动注入时钟读数，与自研 `get_local_datetime`
+  重复；时间读数只来自后者（会话组作用域内注册，主 Agent 与全部子 Agent 共享，支持
+  `timezone` 换算）。
+- `data_analyst` 行保持 `disabled`。启用前置条件（缺一不可）：宿主先实现 Python runner 与
+  coding 工具；插件注册 `read_profile`（allow 里的名字必须先真实存在）；更新 `AGENTS.md` 与 `docs/dev/data-roles.md`
+  的角色边界与 `test/persona.test.mjs` 的预留期断言。
+
+## 5.1 bash：为什么只给 data_junior，以及它到底能做什么
+
+- **动机**：`query_dataset` 只有 `count/min/max/avg/sum`，变化量 / 增幅 / CAGR / 比值这类派生
+  指标没有宿主工具；模型只能拿 `time_facts.first/last` 心算——那正是 §1.3 那次 41,961 字符
+  时间戳心算的同型浪费。所以给 data_junior 一个纯计算兜底。**不是**给它开取数通道。
+- **为什么主 Agent 不给**：主 Agent 今天没有任何通用执行 / 文件 / 网络工具（Web 平面把 host 层
+  的 `tool-bash` / `tool-fs` / `tool-web` 都 `disabled` 了，本 preset 也不挂回来）。这是一条
+  结构性事实，不是 persona 约定：主 Agent 唯一对用户说话、又会读到子 Agent 回传（含网页材料），
+  一旦拥有 bash 就等于拿到"注入 → 执行 → 读凭据 → 出网"的完整链路。收敛靠
+  `ROOT_AGENT_DENIED_TOOLS`（含 `bash` / `pwsh`）。
+- **平台成对挂载**：Windows 上 host 层挂的是 `pwsh-sandbox`，没有 `bash-sandbox`；只挂
+  `tool-bash` 会让名为 bash 的工具实际执行 PowerShell。所以两行互补 `disabled`，allow / deny
+  里的名字用 `!!js` 三元表达式按平台选。`tools.restrict()` 对未注册名字报错，所以表达式与行必须
+  同进同退（回归：`test/persona.test.mjs`「shell 行：平台成对挂载……」）。
+- **不给后台执行**：`enableRunInBackground: false`。本 preset 不挂 `tool-jobs`，开着后台只会让
+  模型拿到一个永远读不回来的 jobId（`job_output` / `job_kill` 不在任何 allow 里）。
+- **闸门只有两层，且都不是安全边界**（`src/agents/bash-guard.ts`）：
+  ① 只对**被委派**子会话开放（镜像 `tool-exec.ts` 的 `delegatedSession`，执行层兜住可见性被改坏）；
+  ② 拦掉 `sandbox_permissions`——委派会话的审批策略由框架固定为 `never`，升级必然失败，而且模型
+  会收到「the user rejected…」这种把系统拒绝说成用户拒绝的文案。
+  **刻意不解析 `command`**：本仓实测沙箱只拦写、不拦读（`~/.dsh/.credentials.yaml` 与
+  `sessions/**` 整机可读）、不拦网络（`curl` 直连 200），而正则挡不住 `node -e` / `python3 -c`
+  ——那正是引入 bash 的目的。禁区与出网纪律是 data_junior persona 的 `# BASH DISCIPLINE` 软约束。
+- **写边界收不窄**：`store.writeContext()` 用**调用方 session** 的 policy 且要求
+  `mode ∈ {workspace-write, danger-full-access}`，而 `describe_dataset` 会用 data_junior 的会话写
+  `profile.json`；把它的会话钉成 `read-only` 会直接打断 describe_dataset。bash 与 Dataset 管线
+  共用同一把尺子（session policy）。
+- **要真正收紧**只有两条路：换掉 `ctx.shell`（容器 / 微 VM / 远端执行器），或给 dsh 进程做出网
+  限制。两者都不是 `ctx.sandbox` 能提供的。
+
+## 6. 改动流程
+
+1. 先判断内容属于"每轮硬规则"（→ persona）还是"按需协议"（→ `skills/`）。
+2. 专用角色六处齐改（判据与顺序见 `docs/dev/preset-persona.md` §8.5）：委派行（provider /
+   toolName / backgroundMode / persona / toolFilter，allow 必须含 `skill`）、子 persona（骨架 +
+   第一条 duty `skill <name>`）、`skills/<name>/SKILL.md`、主 persona 的路由与复用规则、
+   `docs/dev/data-roles.md` §1.1 的角色边界、测试断言。
+3. `npm test` 全绿 + `agentPresets.resolve('capital-generation')` 结果里没有 `broken`（挂载成功），
+   再开一个 Capital 会话确认工具表、首轮预检，以及子 Agent 是否真的按第一条 duty 先加载 skill。