@v587d/capital-generation 2.8.2 → 2.9.0

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,5 @@
 import type { SessionLike } from '../data-collector/store.js';
-/** Dataset/profile 的一跳 scope 规则；token 让 nested child 复用这个 owner scope。 */
+/** One-hop scope: a token lets a nested child reuse its owner's scope. */
 export declare function chartSessionScopeId(session: SessionLike): string;
 export interface ChartArtifactRef {
     chart_ref: string;
@@ -23,13 +23,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;

package/lib/chart/artifact-ref.js

@@ -8,19 +8,14 @@ function defaultChartRef() {
         : `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`;
     return `chart_${suffix}`;
 }
-/** Dataset/profile 的一跳 scope 规则；token 让 nested child 复用这个 owner scope。 */
+/** One-hop scope: a token lets a nested child reuse its owner's scope. */
 export function chartSessionScopeId(session) {
     const parent = session.header?.parentSession;
     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();

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;
+}

package/lib/chart/events.d.ts

@@ -1,17 +1,11 @@
 import type { SessionLike } from '../data-collector/store.js';
-/**
- * 登记本轮交付物用的官方事件名。
- *
- * 必须留在 `KNOWN_SESSION_EVENT_TYPES` 内——它是 `dsh-tool-present` 追加的同一类型，
- * 因此在**任何** harness 版本上都能被读回。改这里等于改会话日志契约，
- * `test/chart-turn-events.test.mjs` 有一条断言把它钉在 first-party 词汇表上。
- */
+/** Must stay in `KNOWN_SESSION_EVENT_TYPES`; test/chart-turn-events.test.mjs pins it. */
 export declare const CHART_DELIVERABLE_EVENT = "deliverables/presented";
-/** `callId` 前缀：交付事件里携带的图表句柄（官方契约只要求非空字符串）。 */
+/** `callId` only needs to be a non-empty string; carries the chart handle for log tracing. */
 export declare const CHART_CALL_ID_PREFIX = "capital-chart:";
-/** 同一 (session, turn) 的事件上限：防模型循环，超出只告警。 */
+/** Per (session, turn) cap: stops model loops; overflow warns only. */
 export declare const MAX_CHARTS_PER_TURN = 8;
-/** 向上找根会话的最大跳数（main → data_junior → specialist 只有一跳，留余量）。 */
+/** Root lookup cap (main → data_junior → specialist is one hop, plus headroom). */
 export declare const MAX_OWNER_HOPS = 4;
 interface AppendableSession extends SessionLike {
     append(type: string, data: unknown): unknown;
@@ -19,102 +13,51 @@ interface AppendableSession extends SessionLike {
 interface SessionsService {
     get(id: string): unknown;
 }
-/** 宿主 ctx 里本模块用到的部分；focused 结构类型便于单测注入假实现。 */
+/** Subset of host ctx used here; structural so tests can inject fakes. */
 export interface ChartEventContext {
     get(name: string): unknown;
-    /** 监听会话事件（`turn/start`，仅作**兜底**冲刷）。必须注册在未打 scope 标签的 root context 上。 */
+    /** Fallback flush listener; must be registered on the unscoped root context. */
     on?(event: string, listener: (...args: unknown[]) => void): unknown;
-    /**
-     * 监听 `agent/turn-stopping`：**首选的冲刷时机**。
-     *
-     * 为什么必须是它而不是 `turn/start`：一轮是否"最终"在事件发生的那一刻不可知——子 Agent 的
-     * 结算随时会再触发新一轮。实测（2026-09-20 真机 session `38bad3f9`）：图表在 turn 4 与 5 之间
-     * 寄存，旧规则在下一次 `turn/start` 立刻冲刷，于是交付行落进了**空的过程轮** turn 5，而主 Agent
-     * 写下总结答复的是 turn 6——卡片出现在中间步骤。`agent/turn-stopping` 是官方"该轮即将关闭"的
-     * 钩子（`@mode serial`，轮仍打开、可安全 append），在它上面冲刷，交付行就落进**消费这份图的那一轮**。
-     *
-     * 必须注册在未打 scope 标签的 root context 上：`dsh-scope` 的准入规则会让 standing-scope 的
-     * 监听器收不到子 Agent 的事件，而我们要的正是 owner 自己那轮关闭的事实。
-     */
+    /** Preferred flush hook: open-but-closing turn, on the unscoped root ctx (scoped listeners miss
+     * child events). A missing disposer must keep the turn/start fallback active. */
     onTurnStopping?(listener: (...args: unknown[]) => void): unknown;
     effect?(callback: () => unknown, label?: string): unknown;
-    /** Root context（未打标签）；拿不到时退回自身（宿主平面行即未打标签）。 */
+    /** Unscoped root context; falls back to self when absent. */
     readonly root?: ChartEventContext;
     logger?: {
         warn(message: string): void;
     };
 }
 export interface ChartTurnEventInput {
-    /** 出图时 chart_ref 的 owner scope（与 ChartArtifactRegistry 同一套语义）。 */
+    /** chart_ref owner scope (same semantics as ChartArtifactRegistry). */
     ownerSessionId: string;
     chart_id: string;
     title: string;
-    /** 工作区相对的 chart.html 路径（官方 preview 按 session.cwd 解析它）。 */
+    /** Workspace-relative chart.html path; the official preview resolves it against session.cwd. */
     html_path: string;
 }
 export interface ChartEventPublisher {
-    /**
-     * 记录一张图。
-     * @returns 是否已受理：立即写入、或已寄存等下一个回合都算受理。
-     */
     publish(input: ChartTurnEventInput): boolean;
-    /** 诊断：还没拿到回合、寄存中的图表数。 */
+    /** Diagnostics: queued charts not yet written. */
     pendingCount?(ownerSessionId?: string): number;
-    /**
-     * 诊断：最近一次 publish 的逐步结论（给回执/落盘用）。
-     *
-     * 为什么需要它：交付行"静默不出现"是本项目最难查的故障，而宿主终端并不总能拿到
-     * （cordis logger 只进内存；stderr 也可能落在用户看不到的地方）。把结论带回
-     * `render_chart` 的回执 / 落盘产物，就能**从磁盘**定位，不必依赖终端。
-     */
+    /** Diagnostics: last publish trace, surfaced in receipts / disk so failures are visible without a terminal. */
     lastTrace?(): string;
 }
-/** 只读：最近一次 publish 轨迹。 */
 export declare function chartEventPublishTrace(): string;
-/**
- * 交付通道的**诊断开关**：`CAPITAL_CHART_TRACE=1` 时才输出进度日志与落盘 trace。
- *
- * 默认关闭——对外发布不该往用户终端刷进度、也不该往 workspace 写调试文件。
- * 排查"图表/交付行不出现"时打开它（见 `deliverable-trace.txt` 与 docs/dev/chart-delivery-events.md §6.3 的说明）。
- */
+/** Diagnostic switch; off by default to keep terminals and workspaces clean. */
 export declare function chartTraceEnabled(): boolean;
-/**
- * 从 owner scope 出发向上走到根会话：用户看的是根会话的对话流，卡片必须挂在它上面。
- * 找不到（会话已回收）时返回 undefined，调用方静默跳过。
- */
+/** Walk up to the root session — the user watches the root conversation. Missing session → undefined. */
 export declare function resolveOwnerSession(sessions: SessionsService, ownerSessionId: string, maxHops?: number): AppendableSession | undefined;
-/**
- * 官方 `deliverables/presented` 载荷。
- *
- * 形状与 `dsh-tool-present` 逐字段对齐（那边是 `{ turn, callId, files }`，
- * 客户端 `isPresentedData()` 要求 `turn` 是 >=1 的安全整数、`callId` 非空字符串、
- * `files` 是数组）。`files[].path` 必须是**工作区相对**路径：官方打开动作会拿它去
- * `workspaceFiles.stat({ sessionId, workspaceRoot: session.cwd })` 解析，绝对路径过不了
- * 「Presented file has no verified Host path」这一关。
- *
- * `callId` 只是官方契约里的一个非空字符串句柄，没有配对约束（`present` 那边用来关联
- * tool/result），这里借它携带 `chart_id`，便于在日志里把一条交付回溯到具体图表。
- */
+/** Matches `dsh-tool-present` ({ turn, callId, files }); files[].path must be workspace-relative
+ * because the official open action resolves it against session.cwd. */
 export declare function buildChartEventPayload(input: ChartTurnEventInput, turn: number): Record<string, unknown>;
-/**
- * 进程内待登记条目的总量上限（安全阀）。
- *
- * 正常流程下条目会在 owner 那一轮关闭时被冲刷清空；但如果冲刷时机始终没接上
- * （上游事件名消失、监听注册失败且 turn/start 也没来），模块级 Map 会一直攒着。
- * 这是纯内存元数据（只有 chart_id / 标题 / 相对路径），上限只为防无界增长，
- * 与 `MAX_CHARTS_PER_TURN` 的"防模型循环"是两件事。
- */
+/** Safety valve if flushing never fires; metadata only, bounded against unbounded growth. */
 export declare const MAX_PENDING_CHARTS = 64;
-/**
- * 只给测试用：清空待登记队列。
- *
- * `pending` 是模块级的（必须跨发布器实例存活，见下方说明），因此进程内所有测试
- * 共享它。测试之间要隔离，就在用例开始时调用一次。
- */
+/** Test-only: clear the shared queue between cases. */
 export declare function resetChartEventPending(): void;
 export declare function createChartEventPublisher(ctx: ChartEventContext): ChartEventPublisher | undefined;
-/** 只给测试用：丢弃单例缓存（配合 resetChartEventPending 做用例隔离）。 */
+/** Test-only: drop the singleton cache. */
 export declare function resetChartEventPublisher(): void;
-/** 出图时的 owner scope：与 chart_ref 同源（specialist 出图时正好是主会话）。 */
+/** Owner scope at render time; same source as chart_ref (specialist renders land on the main session). */
 export declare function chartEventOwnerSessionId(session: SessionLike, sourceSession?: SessionLike): string;
 export {};