@v587d/capital-generation 2.8.3 → 2.9.1

package/lib/agents/selected-skills-provider.js

@@ -3,49 +3,27 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { agentSessionId, isRootAgent } from './root-tool-policy.js';
-// The catalog is a shipped data file outside the TypeScript root; runtime keeps this
-// import so the published lib resolves the same metadata beside the pinned snapshots.
+// Catalog is package data outside the TS root; the runtime import keeps lib resolving it beside pinned snapshots.
 // @ts-expect-error catalog.js is intentionally maintained as package data.
 import { SELECTED_SKILL_CATALOG as CATALOG, SELECTED_SKILL_SKILL_DIRS, SELECTED_SKILL_TASK_IDS, selectedSkillsForTask } from '../../selected-skills/catalog.js';
 export const SELECTED_SKILL_CATALOG = CATALOG;
 const PROVIDER_NAME = 'capital-selected-skills';
-/** 本 preset 的身份：两条注册路径（`agent/created` 与 `agent-preset/selected`）共用一份。 */
 const CAPITAL_PRESET_ID = 'capital-generation';
-// skills 根按 catalog 的「仓库 → 上游 SKILL.md 相对路径」现算：第三颗快照的上游把 skill 放在
-// plugins/us-stock-analysis/skills，不在 <repo>/skills 底下。写死目录列表的表现不是报错，
-// 而是"用户在卡片上勾了那一格、技能永远不出现"（AGENTS.md §9.7）。
+// Derive roots from the catalog: a hardcoded list silently hides checked boxes (upstream layouts differ).
 const SKILL_ROOTS = Object.entries(SELECTED_SKILL_SKILL_DIRS).map(([repository, skillsDir]) => fileURLToPath(new URL(`../../selected-skills/${repository}/${skillsDir}`, import.meta.url)));
-/**
- * 任务型内置 skill 的根目录（`lib/agents/` → 包根 → `preset/capital-generation/skills`）。
- *
- * 索引**不改磁盘**：`preset/.../SKILL.md` 一个字节都不动，正文在 `get()` 读取期拼上索引块。
- * 三个理由，缺一都不是洁癖：装好的包常常整棵只读（全局安装更糟）；`skill-filesystem` 的 watcher
- * 会被写文件搅动，多会话并行时互相打架；`test/persona.test.mjs` 正钉着这些文件的 frontmatter 与
- * 体积，运行期改写会让那些闸门失去意义。
- */
+/** Built-in task skill root; the index is appended at read time, never written to disk:
+ * installs may be read-only, watchers would churn, and tests pin frontmatter and size. */
 const TASK_SKILL_ROOT = fileURLToPath(new URL('../../preset/capital-generation/skills', import.meta.url));
-/**
- * 遮蔽候选的 rank。DSH 的 `compareIndexedCandidates` 先比 rank 再比 provider 顺序，**小的赢**；
- * 同层自定义根是 `CUSTOM_RANK = 300`，这里取 150 保证同层时压过 fs provider。
- *
- * 跨层本来也轮不到 rank：`dsh-agent-preset-registry` 把 preset 的 standing scope 挂成
- * **agent scope 的 parent**（`standingKey = scopeParentOf(agentKey)`），而 `chainLayers` 的注释写明
- * "farthest ancestor first, the nearest scope has the final word"、`scopeChainOf(...).reverse()` 后
- * 逐层 `merged.set(name, ...)` —— 本 provider 注册在 agent scope 里，是最近的一层，同名天然覆盖。
- * 两条机制取其一即可，取两条是因为遮蔽失败的症状是"索引静默消失"，没有第二个人会发现。
- */
+/** Smaller rank wins: 150 beats the same-layer custom root (300). The agent scope usually
+ * shadows anyway; both are cheap insurance because failure is silent. */
 const TASK_SKILL_SHADOW_RANK = 150;
 const INDEX_HEADING = '## 附：本轮可用的外部精选 Skill（索引）';
-/**
- * 索引块的框。它把**外部方法论**塞进了**宿主契约 skill** 的正文里，框架被拉平了，所以这四句必须
- * 写在块内而不是别的文档里：冲突判据、不可动摇的三处边界、以及"这里只有摘要"。
- */
+/** Conflict precedence and the three untouchable boundaries must live inside the block. */
 const INDEX_FRAME = [
     '以下是你（用户）在设置里启用的外部精选 Skill，按能力标签与本次任务关联后列出。它们是**方法论材料**，',
     '需要正文时照常用 `skill` 工具按名加载。它们**不改变**本 skill 的证据门、工具委派路径、输出通道与报告形状；',
     '与本 skill 冲突时**以本 skill 为准**。这里只给名称与摘要，摘要不等于全文，未加载前不要照它行事。',
 ];
-/** 最小 frontmatter 读取：只要 `name` / `description` / 正文。完整策略解析仍归 fs provider。 */
 function readFrontmatter(raw) {
     const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(raw);
     if (match === null)
@@ -58,10 +36,7 @@ function readFrontmatter(raw) {
     }
     return { fields, body: raw.slice(match[0].length) };
 }
-/**
- * 载入三颗任务型 skill 的正文。**读不到就不遮蔽**：`list()` 不会列出这个候选，fs provider 照常
- * 供原文，用户看到的是"没有索引"，而不是"这颗 skill 不见了"（AGENTS.md §9.7 ⑤ 失败要留余地）。
- */
+/** Unreadable means no shadow, never a missing skill: the fs provider still serves the original. */
 function loadTaskSkillBases(root = TASK_SKILL_ROOT) {
     const bases = new Map();
     for (const name of SELECTED_SKILL_TASK_IDS) {
@@ -74,16 +49,11 @@ function loadTaskSkillBases(root = TASK_SKILL_ROOT) {
             bases.set(name, { name, description, content: parsed.body.trim(), directory: join(root, name) });
         }
         catch {
-            // 读不到是 fail-open，不是错误路径：默认态（一颗都没启用）本来就不遮蔽任何东西。
         }
     }
     return bases;
 }
-/**
- * 索引块正文。**唯一实现**：条目集合来自 catalog 的 `selectedSkillsForTask`（与目录、闸门同源），
- * 描述用**运行时那一份**（上游 frontmatter，也就是会话目录里模型看到的那句话），不是设置卡片里
- * 策展过的中文摘要——同一个 skill 在同一段上下文里出现两种描述，只会让模型两处对照。
- */
+/** Sole index renderer; descriptions use runtime frontmatter (what the model sees), not card summaries. */
 export function renderTaskSkillIndex(taskId, summaries) {
     if (summaries.length === 0)
         return undefined;
@@ -106,13 +76,11 @@ function selectedNames(selection) {
 function readSelection(source) {
     return typeof source === 'function' ? source() : source;
 }
-// 选择指纹只认 catalog 的 key 集合：pre-step 每轮拿它对比"上次交给注册表的选择"，
-// 变了才失效目录缓存，未变就零成本放行。
+// Fingerprint only the catalog key set: refresh the cache only when the selection changes.
 function selectionFingerprint(selection) {
     return SELECTED_SKILL_CATALOG.map(({ key }) => (selection[key] === true ? '1' : '0')).join('');
 }
-// agent/pre-step 是 dsh-agent 声明的事件，类型不在本包的 import 面里；按结构挂到注入后的
-// Agent context（其 scope tag 就是该 Agent，dispatch 的 scope filter 才放行这条监听）。
+// `agent/pre-step` belongs to dsh-agent; attach via the injected Agent context so scope filtering admits it.
 function onPreStepEvent(ctx, listener) {
     const events = ctx;
     return events.on?.('agent/pre-step', listener);
@@ -127,19 +95,16 @@ function strictCapitalPreset(ctx, agent) {
         return false;
     }
 }
-/** Register explicitly selected community experiments on the Capital root Agent only. */
+/** Registers selected community experiments on the Capital root Agent only. */
 export function registerRootSelectedSkills(ctx, selection, createFilesystemProvider = createFilesystemSkillProvider) {
-    // Static callers retain the cheap all-disabled fast path. The Capital plugin
-    // passes a reader so a settings toggle is observed at the next step of every
-    // live root Agent: list()/get() filter against the current selection, and the
-    // pre-step hook below refreshes the visible catalog when the selection changes.
+    // Static callers keep the all-off fast path; the plugin passes a reader so live toggles apply
+    // at the next step (list/get filter by selection, pre-step refreshes the visible catalog).
     if (typeof selection !== 'function' && selectedNames(selection).size === 0)
         return;
     const listenCtx = ctx.root ?? ctx;
     if (typeof listenCtx.on !== 'function')
         return;
-    // 一个 root Agent 只注册一次：下面两条事件路径会在同一个 Agent 上重叠（建会话时就带 Capital
-    // 预设 → `agent/created`；先按默认预设建、再 select 到 Capital → `agent-preset/selected`）。
+    // One registration per root Agent: both event paths can observe the same Agent.
     const registered = new WeakSet();
     const registerFor = async (agent) => {
         if (!agent || registered.has(agent))
@@ -154,8 +119,7 @@ export function registerRootSelectedSkills(ctx, selection, createFilesystemProvi
                 ctx.logger?.warn?.('capital-generation: selected skills are unavailable (root Agent cannot inject skills)');
                 return;
             }
-            // agent/created 是串行事件、DSH 等监听器 settle 才继续创建：await 注入 Fiber，
-            // provider 与 pre-step 钩子都在首轮 prompt 前落位（首轮 catalog 不与注册竞态）。
+            // agent/created is serial: DSH awaits listeners, so this inject lands before the first prompt.
             await agentCtx.inject(['skills'], (injectedCtx) => {
                 const skills = injectedCtx.skills;
                 if (typeof skills?.registerProvider !== 'function') {
@@ -164,9 +128,7 @@ export function registerRootSelectedSkills(ctx, selection, createFilesystemProvi
                 }
                 let filesystemProvider;
                 let control;
-                // 上次交给 skills 注册表的选择指纹。开关是 settings 偏好，不在 Agent 创建时定格：
-                // 全关也照常注册 provider（否则会话创建后打开开关永远不出现），靠下面的 pre-step
-                // 钩子每轮对齐设置。
+                // Register even when all toggles are off; otherwise a later enable would never surface. Pre-step aligns settings.
                 let served = selectionFingerprint(readSelection(selection));
                 injectedCtx.effect(() => {
                     const unregister = skills.registerProvider((registration) => {
@@ -177,15 +139,11 @@ export function registerRootSelectedSkills(ctx, selection, createFilesystemProvi
                             customSkillDirs: SKILL_ROOTS,
                             watch: true,
                         });
-                        // 遮蔽用的底稿只在注册时读一次（三份小文件，读不到就不遮蔽）。
                         const taskBases = loadTaskSkillBases();
-                        // 上一次 `list()` 看到的"已启用精选"运行时摘要。`get()` 拼索引时读它，避免为了几行摘要
-                        // 再枚举一遍快照目录；为空就退回"没有索引"，也就是把整颗让给 fs provider 的原文。
+                        // Summaries from the last `list()`; `get()` reuses them instead of rescanning dirs.
                         let runtimeSummaries = [];
                         const indexFor = (taskId) => {
                             const byName = new Map(runtimeSummaries.map((entry) => [entry.name, entry]));
-                            // 条目集合来自 catalog 的唯一实现（与目录、闸门同源），顺序取 catalog 顺序：
-                            // 同一仓库的几颗排在一起，读起来比按名字打散更像一份索引。
                             const summaries = selectedSkillsForTask(taskId, [...byName.keys()])
                                 .map((entry) => byName.get(entry.name))
                                 .filter((entry) => entry !== undefined);
@@ -194,11 +152,9 @@ export function registerRootSelectedSkills(ctx, selection, createFilesystemProvi
                         const provider = {
                             name: PROVIDER_NAME,
                             async list(options) {
-                                // 调用期现读：开关是 settings 偏好，不许在 Agent 创建时定格。
+                                // Read at call time: toggles are settings, not fixed at Agent creation.
                                 const enabled = selectedNames(readSelection(selection));
-                                // 全关是默认常态：短路掉，不碰快照目录（filesystem watcher 在它的 list()
-                                // 里才启动，短路保证默认关闭的会话不起任何 watcher），**也不遮蔽任何内置 skill**：
-                                // 一颗都没启用时用户看到的必须与没有这个 provider 时逐字相同。
+                                // All-off is the default: skip snapshot dirs (no watcher starts) and shadow nothing, matching no-provider output.
                                 if (enabled.size === 0) {
                                     runtimeSummaries = [];
                                     return [];
@@ -207,9 +163,7 @@ export function registerRootSelectedSkills(ctx, selection, createFilesystemProvi
                                 const candidates = Array.isArray(result) ? result : result.candidates;
                                 const selected = candidates.filter((candidate) => enabled.has(candidate.name));
                                 runtimeSummaries = selected.map((candidate) => ({ name: candidate.name, description: candidate.description }));
-                                // 任务型内置 skill 的遮蔽候选：只有当这颗**确实有索引可给**时才列出来。
-                                // 没有索引就整颗让给 fs provider（正文照旧），因此"索引缺失"永远不会演变成
-                                // "这颗 skill 不见了"——遮蔽是加法，不是替换。
+                                // Shadow a task skill only when it has an index; otherwise the fs provider's original wins.
                                 const shadows = [...taskBases.values()]
                                     .filter((base) => indexFor(base.name) !== undefined)
                                     .map((base) => ({
@@ -228,7 +182,6 @@ export function registerRootSelectedSkills(ctx, selection, createFilesystemProvi
                             get(candidate, options) {
                                 const base = taskBases.get(candidate.name);
                                 if (base !== undefined) {
-                                    // 索引在**读取期**算：开关是 settings 偏好，加载这一刻才是最新的。
                                     const index = indexFor(base.name);
                                     const content = index === undefined ? base.content : `${base.content}\n\n${index}`;
                                     return Promise.resolve({
@@ -250,11 +203,8 @@ export function registerRootSelectedSkills(ctx, selection, createFilesystemProvi
                         };
                         return provider;
                     });
-                    // 每轮 pre-step 重读开关：集合变了就调 provider control 的 invalidate()，失效
-                    // skills 的目录缓存（revision++），tool-skill 随后的 catalog 快照因此按最新开关
-                    // 重算；未变则 digest 不变、catalog 不重发。必须在放行 next() 之前做完——
-                    // waterfall 里 tool-skill 是 await next() 之后才快照，但监听器注册顺序不归我们
-                    // 管，先做完再放行在两种顺序下都赶得上本轮快照。设置读取失败只降级，不阻断本轮。
+                    // Invalidate before next() so this turn's snapshot sees the change regardless of listener order.
+                    // A settings read failure only degrades this hook.
                     const stopPreStep = onPreStepEvent(injectedCtx, (_payload, next) => {
                         try {
                             const fingerprint = selectionFingerprint(readSelection(selection));
@@ -279,20 +229,14 @@ export function registerRootSelectedSkills(ctx, selection, createFilesystemProvi
             });
         }
         catch (error) {
-            // selected skills 是可选能力：注入失败只降级告警，不能把整个 Agent 创建挡掉；
-            // 同时撤掉登记，让后面的事件（下一次 select、别的注册路径）还有重试的余地。
+            // Optional capability: degrade with a warning, never block Agent creation; clear so a later event can retry.
             registered.delete(agent);
             ctx.logger?.warn?.(`capital-generation: selected skills are unavailable (${String(error)})`);
         }
     };
     const stop = listenCtx.on('agent/created', ({ agent }) => registerFor(agent));
-    // 第二条路径：**先按默认预设建会话、再切到 Capital**（GUI 的真实顺序）。
-    // 2026-10-13 复核复现：会话（header `agentPreset: "cordis"`）建好后客户端才发
-    // `agentPresets.select('capital-generation')`，而 `agent/created` 在 select 之前就已经发完——
-    // 只挂那一条时本插件的 `apply()` 是在**这次 recompose 的 mount 里**才跑的，监听器出生就错过了
-    // 自己这个 Agent：设置卡 10 个开关全开、会话目录仍只有 preset 自带的 8 颗（真 boot graph 探针：
-    // create→select 8 颗 / 建会话时 mount 同一 preset 18 颗）。preset registry 在 mount 完成后才
-    // `session.append('agent-preset/selected')`，所以本行一定早于这条事件落位。
+    // Second path: GUI creates with the default preset, then selects Capital. `agent/created`
+    // already fired and apply() runs inside that remount, so `agent-preset/selected` arrives after mount.
     const onPresetEvent = listenCtx.on;
     const stopPreset = onPresetEvent?.('agent-preset/selected', (sessionId, agentPreset) => {
         if (agentPreset !== CAPITAL_PRESET_ID)
@@ -301,8 +245,7 @@ export function registerRootSelectedSkills(ctx, selection, createFilesystemProvi
         const agent = agents?.get?.(String(sessionId));
         if (agent === undefined)
             return;
-        // emit 型事件不等待监听器；返回 promise 只为让单测能等到注册落地。registerFor 内部
-        // 自兜异常（失败只降级告警并撤登记，下一次事件还有重试的余地），这里不会产生未处理拒绝。
+        // Emit-style event: the promise only lets tests await registration; errors are handled inside.
         return registerFor(agent);
     });
     ctx.effect?.(() => () => {

package/lib/capital-settings.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Sole reader of the bundled `capital-config` entry. The id must match the host row,
+ * settings card and preset row; drift is caught by the four-way assertion in
+ * `test/capital-config.test.mjs`. Unreadable returns `{}` and callers fill defaults;
+ * only reference names are read here, never resolved secrets.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { RetrieverConfig } from './retriever-config.js';
+import type { SelectedSkillSelection } from './agents/selected-skills-provider.js';
+export declare const CAPITAL_CONFIG_ENTRY_ID = "capital-config";
+/** Fields this repo consumes (the host half owns the rest). */
+export interface CapitalConfigSlice {
+    fuyaoCredentialRef?: string;
+    ftshareCredentialRef?: string;
+    customPersona?: string;
+    retriever?: RetrieverConfig;
+    selectedSkills?: SelectedSkillSelection;
+}
+export declare function readCapitalConfig(ctx: Context): CapitalConfigSlice;
+/** Flat credential refs needed by the collector domain (same shape as `CollectorConfig`). */
+export declare function readCollectorConfig(ctx: Context): {
+    fuyaoCredentialRef?: string;
+    ftshareCredentialRef?: string;
+    windCredentialRef?: string;
+};
+/** Retriever config slice (baseURL, credential ref, Wind endpoint, local fallback switch). */
+export declare function readRetrieverConfig(ctx: Context): RetrieverConfig;

package/lib/capital-settings.js

@@ -0,0 +1,23 @@
+export const CAPITAL_CONFIG_ENTRY_ID = 'capital-config';
+export function readCapitalConfig(ctx) {
+    try {
+        const settings = ctx.get('settings');
+        return settings?.describe?.().find((entry) => entry?.ns === CAPITAL_CONFIG_ENTRY_ID)?.value ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Flat credential refs needed by the collector domain (same shape as `CollectorConfig`). */
+export function readCollectorConfig(ctx) {
+    const config = readCapitalConfig(ctx);
+    return {
+        fuyaoCredentialRef: config.fuyaoCredentialRef,
+        ftshareCredentialRef: config.ftshareCredentialRef,
+        windCredentialRef: config.retriever?.windDocs?.credentialRef,
+    };
+}
+/** Retriever config slice (baseURL, credential ref, Wind endpoint, local fallback switch). */
+export function readRetrieverConfig(ctx) {
+    return readCapitalConfig(ctx).retriever ?? {};
+}

package/lib/chart/artifact-ref.d.ts

@@ -1,5 +1,8 @@
 import type { SessionLike } from '../data-collector/store.js';
-/** Dataset/profile 的一跳 scope 规则；token 让 nested child 复用这个 owner scope。 */
+/**
+ * Subagent children carry `origin: 'subagent'`; a user fork/branch root also has `parentSession`
+ * (seed lineage) and must stay its own scope. One hop: the token lets a nested child reuse its owner.
+ */
 export declare function chartSessionScopeId(session: SessionLike): string;
 export interface ChartArtifactRef {
     chart_ref: string;
@@ -10,6 +13,7 @@ export interface ChartArtifactRef {
     captured_at: number | null;
     kind: string;
     axis: 'time' | 'index';
+    title: string;
     chart_url: string | null;
     spec_path: string;
     series_path: string;
@@ -23,13 +27,8 @@ export interface ChartArtifactRegistryOptions {
     newRef?: () => string;
 }
 /**
- * In-process registry for chart_ref capabilities.
- *
- * The chart files live in the workspace, while this registry keeps the
- * session/task binding that makes a chart safe to present to its own session
- * (and to derive the `deliverables/presented` owner scope).
- * Process restart invalidates chart_ref capabilities; chart.html remains the
- * explicit offline fallback.
+ * In-process chart_ref capabilities: session/task/workspace binding and the deliverable owner
+ * scope. Process restart invalidates them; chart.html remains the offline fallback.
  */
 export declare class ChartArtifactRegistry {
     private readonly records;
@@ -47,6 +46,7 @@ export declare class ChartArtifactRegistry {
         captured_at?: number | null;
         kind: string;
         axis: 'time' | 'index';
+        title: string;
         chart_url: string | null;
         spec_path: string;
         series_path: string;
@@ -60,6 +60,11 @@ export declare class ChartArtifactRegistry {
         task_id?: string | null;
     }): ChartArtifactRef;
     revoke(chartRef: string): boolean;
+    /** Charts of one session scope, for the model's final-turn delivery step; newest last. */
+    list(input: {
+        session: SessionLike;
+        task_id?: string | null;
+    }): ChartArtifactRef[];
     size(): number;
     private publicRecord;
 }

package/lib/chart/artifact-ref.js

@@ -8,19 +8,17 @@ function defaultChartRef() {
         : `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`;
     return `chart_${suffix}`;
 }
-/** Dataset/profile 的一跳 scope 规则；token 让 nested child 复用这个 owner scope。 */
+/**
+ * Subagent children carry `origin: 'subagent'`; a user fork/branch root also has `parentSession`
+ * (seed lineage) and must stay its own scope. One hop: the token lets a nested child reuse its owner.
+ */
 export function chartSessionScopeId(session) {
-    const parent = session.header?.parentSession;
+    const parent = session.header?.origin === 'subagent' ? session.header.parentSession : undefined;
     return typeof parent === 'string' && parent.length > 0 ? parent : session.id;
 }
 /**
- * In-process registry for chart_ref capabilities.
- *
- * The chart files live in the workspace, while this registry keeps the
- * session/task binding that makes a chart safe to present to its own session
- * (and to derive the `deliverables/presented` owner scope).
- * Process restart invalidates chart_ref capabilities; chart.html remains the
- * explicit offline fallback.
+ * In-process chart_ref capabilities: session/task/workspace binding and the deliverable owner
+ * scope. Process restart invalidates them; chart.html remains the offline fallback.
  */
 export class ChartArtifactRegistry {
     records = new Map();
@@ -61,6 +59,7 @@ export class ChartArtifactRegistry {
             captured_at: input.captured_at ?? null,
             kind: input.kind,
             axis: input.axis,
+            title: input.title,
             chart_url: input.chart_url,
             spec_path: input.spec_path,
             series_path: input.series_path,
@@ -96,12 +95,30 @@ export class ChartArtifactRegistry {
     revoke(chartRef) {
         return this.records.delete(chartRef);
     }
+    /** Charts of one session scope, for the model's final-turn delivery step; newest last. */
+    list(input) {
+        const now = this.now();
+        this.purgeExpired(now);
+        const scope = chartSessionScopeId(input.session);
+        const cwd = input.session.header?.cwd ?? null;
+        const records = [];
+        for (const record of this.records.values()) {
+            if (record.owner_scope_id !== scope || record.owner_cwd !== cwd)
+                continue;
+            if (input.task_id !== undefined && input.task_id !== null && record.task_id !== input.task_id)
+                continue;
+            records.push(record);
+        }
+        return records
+            .sort((left, right) => left.created_at - right.created_at)
+            .map((record) => this.publicRecord(record));
+    }
     size() {
         this.purgeExpired(this.now());
         return this.records.size;
     }
     publicRecord(record) {
-        const { owner_scope_id: _ownerScope, ...publicRecord } = record;
+        const { owner_scope_id: _ownerScope, owner_cwd: _ownerCwd, ...publicRecord } = record;
         return publicRecord;
     }
 }

package/lib/chart/downsample.d.ts

@@ -1,8 +1,5 @@
 /**
- * Largest-Triangle-Three-Buckets 下采样：返回**保留下来的行下标**。
- *
- * 为什么返回下标而不是点：一张图上可能同时有主序列、K 线、成交量副图与标记点，
- * 它们必须**共用同一组时间轴**。若各自下采样，同一时刻会在不同子图上错位。
- * 于是只对"主序列"跑一次 LTTB 求下标，再把这组下标套用到所有子序列上。
+ * LTTB downsampling returning kept row indices. All subplots share one time axis, so indices
+ * are computed once from the primary series and applied everywhere.
  */
 export declare function largestTriangleThreeBuckets(values: readonly number[], threshold: number): number[];

package/lib/chart/downsample.js

@@ -1,9 +1,6 @@
 /**
- * Largest-Triangle-Three-Buckets 下采样：返回**保留下来的行下标**。
- *
- * 为什么返回下标而不是点：一张图上可能同时有主序列、K 线、成交量副图与标记点，
- * 它们必须**共用同一组时间轴**。若各自下采样，同一时刻会在不同子图上错位。
- * 于是只对"主序列"跑一次 LTTB 求下标，再把这组下标套用到所有子序列上。
+ * LTTB downsampling returning kept row indices. All subplots share one time axis, so indices
+ * are computed once from the primary series and applied everywhere.
  */
 export function largestTriangleThreeBuckets(values, threshold) {
     const count = values.length;
@@ -14,7 +11,6 @@ export function largestTriangleThreeBuckets(values, threshold) {
     let anchor = 0;
     sampled.push(anchor);
     for (let bucket = 0; bucket < threshold - 2; bucket += 1) {
-        // 下一个桶的均值，作为三角形的一个顶点。
         const averageStart = Math.floor((bucket + 1) * every) + 1;
         const averageEnd = Math.min(Math.floor((bucket + 2) * every) + 1, count);
         const averageLength = Math.max(averageEnd - averageStart, 1);
@@ -26,7 +22,6 @@ export function largestTriangleThreeBuckets(values, threshold) {
         }
         averageX /= averageLength;
         averageY /= averageLength;
-        // 当前桶里与 anchor、均值构成最大三角形面积的点。
         const rangeStart = Math.floor(bucket * every) + 1;
         const rangeEnd = Math.min(Math.floor((bucket + 1) * every) + 1, count);
         const anchorX = anchor;
@@ -44,7 +39,7 @@ export function largestTriangleThreeBuckets(values, threshold) {
         anchor = maxAreaIndex;
     }
     sampled.push(count - 1);
-    // 去重并保持升序：LTTB 的桶边界在极端阈值下可能产生重复下标。
+    // Bucket edges can yield duplicate indices at extreme thresholds; keep ascending order.
     const unique = [];
     for (const index of sampled)
         if (unique.length === 0 || index > unique[unique.length - 1])

package/lib/chart/errors.d.ts

@@ -1,16 +1,12 @@
 /**
- * 图表域的错误类型。
- *
- * 错误码是**模型可见契约**的一部分：模型据此修正一次即可重试（见
- * preset/capital-generation/skills/capital-chart-protocol/SKILL.md）。
- * 因此 detail 必须可操作（点名缺哪个字段、可用字段有哪些），而不是笼统的 invalid。
+ * Chart errors are model-visible contract: detail must name the missing field and list
+ * candidates, not merely say "invalid".
  */
 export type ChartErrorCode = 'chart_source_invalid' | 'chart_source_expired' | 'chart_source_scope_mismatch' | 'chart_source_not_found' | 'chart_ref_invalid' | 'chart_ref_scope_mismatch' | 'chart_ref_task_mismatch' | 'chart_spec_invalid' | 'chart_field_not_found' | 'chart_no_rows' | 'chart_too_large' | 'chart_write_failed' | 'chart_runtime_unavailable';
 export declare class ChartError extends Error {
     readonly code: ChartErrorCode;
-    /** 可选的机器可读补充（如 available 字段名列表），会随错误一起序列化回模型。 */
+    /** Machine-readable extras (e.g. available fields), serialized back to the model. */
     readonly details: Record<string, unknown>;
     constructor(code: ChartErrorCode, detail: string, details?: Record<string, unknown>);
-    /** 工具边界统一把错误转成结构化信封，让模型能一次修正。 */
     toEnvelope(): Record<string, unknown>;
 }

package/lib/chart/errors.js

@@ -1,6 +1,6 @@
 export class ChartError extends Error {
     code;
-    /** 可选的机器可读补充（如 available 字段名列表），会随错误一起序列化回模型。 */
+    /** Machine-readable extras (e.g. available fields), serialized back to the model. */
     details;
     constructor(code, detail, details = {}) {
         super(`${code}: ${detail}`);
@@ -8,7 +8,6 @@ export class ChartError extends Error {
         this.code = code;
         this.details = details;
     }
-    /** 工具边界统一把错误转成结构化信封，让模型能一次修正。 */
     toEnvelope() {
         return { error: this.code, detail: this.message.slice(this.message.indexOf(':') + 2), ...this.details };
     }

package/lib/chart/event-context.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Adapt a cordis ctx into ChartEventContext.
+ * Never spread ctx (`{ ...ctx }`): get/on/effect live on the prototype, so spreading drops them
+ * and delivery silently disappears. Forward each method with the original ctx as receiver.
+ * One assembly path serves both the monolith plugin and the tools/chart entry.
+ */
+import type { ChartEventContext } from './events.js';
+export declare function chartEventContextOf(ctx: unknown): ChartEventContext;

package/lib/chart/event-context.js

@@ -0,0 +1,39 @@
+export function chartEventContextOf(ctx) {
+    const raw = ctx;
+    const context = {
+        get: (name) => raw.get(name),
+        // Failed registration returns undefined so events.ts can fall back to turn/start.
+        on: (event, listener) => {
+            if (typeof raw.on !== 'function')
+                return undefined;
+            return raw.on.call(ctx, event, (...args) => { listener(...args); });
+        },
+        onTurnStopping: (listener) => {
+            if (typeof raw.on !== 'function')
+                return undefined;
+            try {
+                return raw.on.call(ctx, 'agent/turn-stopping', (...args) => { listener(...args); });
+            }
+            catch {
+                return undefined;
+            }
+        },
+    };
+    // root/effect are cordis getters: forward only when present.
+    try {
+        if (raw.root !== undefined) {
+            Object.defineProperty(context, 'root', { get: () => raw.root, enumerable: true });
+        }
+    }
+    catch { /* root unavailable: events.ts falls back to self */ }
+    try {
+        if (typeof raw.effect === 'function') {
+            Object.defineProperty(context, 'effect', {
+                value: (callback, label) => raw.effect.call(ctx, callback, label),
+                enumerable: true,
+            });
+        }
+    }
+    catch { /* no disposer support */ }
+    return context;
+}