@v587d/capital-generation 2.8.2 → 2.9.0

package/lib/watchlist/tools.js

@@ -1,22 +1,11 @@
 import { dayDistance, readClock } from '../time/tools.js';
 import { stripInvisibleText } from '../web-retriever/html-markdown.js';
 const jsonObject = (properties = {}, required = []) => ({ type: 'object', properties, required, additionalProperties: false });
-/** ToolOutputDefinition.render(args, value)：第一参是入参、第二参才是返回值。 */
 function render(_args, value) {
     return [{ type: 'text', text: JSON.stringify(value) }];
 }
 const WATCHLIST_DENIED = '这不是"用户没有自选股"：清单读不到，一条都不许猜。';
-/**
- * 一条记录 → 模型看见的那几格。**每个键都声明过**（§9.6：多一个未声明字段同样致命）。
- *
- * 两形态由 `held` 点名：未持仓的那一行**不出现** `weight_pct` / `holding_marked_*`——
- * "根本不是仓位"的时候谈"比例是 null 还是 0"没有意义，而把这三格摊给 30 行会让满载回包
- * 撞破体积预算（下面那条 6144 的闸门实测过）。三态仍然彼此可分：
- * `held:false` / `held:true` 且 `weight_pct:null`（标了没填） / `held:true` 且 `weight_pct:0`（真填 0）。
- *
- * 字段是照着"用户点名的四格 + 判断这句话还能信多久"选的，`added_age_days` 与 `pinned` 都不在这个
- * 问题里：添加日期就是事实本身，而清单**顺序**已经反映了置顶（服务端 `rowsOf` 给的读法）。
- */
+/** Held rows may carry weight/marked fields; `held:true` with `weight_pct:null` stays distinct from 0. */
 function rowOf(row, today) {
     const stripped = stripInvisibleText(String(row?.name ?? ''));
     const thscode = String(row?.thscode ?? '');
@@ -24,24 +13,20 @@ function rowOf(row, today) {
     const holding = row?.holding;
     const held = holding !== undefined;
     const markedAt = held && typeof holding?.marked_at === 'number' ? String(readClock(holding.marked_at).date) : null;
-    // 天数下界取 0：机器时钟回拨过会让"N 天前"变成负数，那是没有意义的一句话；
-    // 日期那一格仍给原值，所以异常照样看得见（不靠 clamp 把它藏起来）。
+    // Clamp the age at 0 so a clock rollback cannot produce a negative "days ago"; the date itself stays raw.
     const age = (date) => Math.max(0, dayDistance(date, today));
     return {
         thscode,
-        // 上游名字里的零宽 / 方向覆盖符肉眼看不见，却能让"用户核对的那句话"与 Agent 收到的不一样
-        // （设计文档 §3.2）；剥完为空就退回代码，不放一个空字符串上去。
+        // Strip invisible characters so the name the user sees matches what the agent reads; fall back to the code.
         name: stripped.length > 0 ? stripped : thscode,
         asset_type: String(row?.asset_type ?? ''),
         added_date: addedAt,
         held,
-        // ⛔ 持仓那一档里"没有这个数"就是 null，不是 0：用户在面板上勾了持仓、比例留空，
-        // 把它写成 0% 等于替用户说了一句他没说的话（域 schema 同一口径，见 change_pct 那段）。
+        // Empty weight stays null, not 0: writing 0 would put a claim in the user's mouth.
         ...(held ? { weight_pct: holding?.weight_pct ?? null } : {}),
         ...(markedAt !== null ? { holding_marked_date: markedAt, holding_marked_age_days: age(markedAt) } : {}),
     };
 }
-/** 成功回包。`limit` 只在宿主给了才带（那个数字归 `capital-watchlist` 所有，这里不抄一份）。 */
 export function watchlistReceipt(rows, limit, now) {
     const today = String(readClock(now).date);
     const items = rows.map((row) => rowOf(row, today));
@@ -84,7 +69,7 @@ export function watchlistToolDefinition(source) {
                 as_of_date: { type: 'string' },
                 items: {
                     type: 'array',
-                    // `required` 只列两种形态共有的五格；持仓那三格由 `held` 点名（§9.6 的多形态唯一姿势）。
+                    // `required` lists only the five shared fields; held-only fields are keyed by `held`.
                     items: jsonObject({
                         thscode: { type: 'string' },
                         name: { type: 'string' },
@@ -102,7 +87,7 @@ export function watchlistToolDefinition(source) {
         async execute() {
             const service = source();
             if (service === undefined || typeof service.list !== 'function') {
-                // ⛔ 绝不回空清单：装配里少了 host 平面那一行与"用户一条自选都没加"在回包上必须长得不一样。
+                // Never return an empty list: a missing host row must look different from "user has no watchlist".
                 return unavailable('watchlist_unavailable', `自选股服务没有挂载（capital-watchlist 那行没起来）。${WATCHLIST_DENIED}`);
             }
             let result;
@@ -121,21 +106,16 @@ export function watchlistToolDefinition(source) {
     };
 }
 /**
- * 注册 `get_watchlist`（主 Agent 的工具；`capital-generation-scope` 组里注册 = 主 Agent 与
- * 全部 child 都看得见，所以通用 `subagent` 行必须把它 deny 掉，见 preset 的 agent.patch.yml）。
- *
- * 会话级数据（Dataset / profile / chart）走 workspace，而自选股是**宿主级用户资产**：
- * 本工具不读 `{{cwd}}`、不碰 `~/.dsh/storages/` 那个文件，只调那一路唯一的宿主服务
- * （设计文档 §2.4：不允许另建一份存储）。
+ * Register get_watchlist (main agent + all children; the subagent row must deny it). Host-level user
+ * data: read it only through the host service, never a second store.
  */
 export function registerWatchlistTool(ctx) {
     const tools = ctx.get('tools');
     if (tools === undefined)
         return;
     ctx.effect(() => tools.register(watchlistToolDefinition(() => {
-        // ⛔ 服务只在**每次调用**时现取（AGENTS.md §9.7 ⑤）：`capital-watchlist` 是 host 平面行，
-        // 它的 provide 与本 preset 行的装配先后不由我们决定。装配期取一次，就等于把一次抢跑
-        // 钉成"用户的自选股整个进程读不到"（桌面端 2026-09-30 那 61 条能力缺席是同一族形状）。
+        // Resolve the service at call time: host-plane row order is not ours, and caching a startup miss
+        // would hide the user's watchlist for the whole process.
         try {
             return ctx.get('capitalWatchlist');
         }

package/lib/watchlist-entry.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `tools/watchlist` row: get_watchlist. User assets live in host storage-domain and only
+ * the main Agent mounts this row. Resolve the domain per call: memoizing an unready
+ * `storageDomain` as `store_unavailable` disables it for the whole process.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "capital-watchlist-tools";
+export declare const inject: string[];
+export declare function apply(ctx: Context): void;

package/lib/watchlist-entry.js

@@ -0,0 +1,6 @@
+import { registerWatchlistTool } from './watchlist/tools.js';
+export const name = 'capital-watchlist-tools';
+export const inject = ['tools'];
+export function apply(ctx) {
+    registerWatchlistTool(ctx);
+}

package/lib/web-retriever/engines.d.ts

@@ -1,8 +1,6 @@
 /**
- * AnySearch 的最小 REST 客户端。
- *
- * web_retriever 目前只支持一个后端，因此不预留多引擎注册表、动态 loader 或
- * provider 目录。未来真正接入第二个后端时，再根据实际差异抽象接口。
+ * Minimal AnySearch REST client. No multi-engine registry or provider directory
+ * exists until a second backend introduces a real abstraction need.
  */
 export interface SearchHit {
     url: string;
@@ -24,9 +22,9 @@ export interface FetchResult {
     truncated?: boolean;
     error?: string;
 }
-/** AnySearch 失败的结构化错误码。取值与拼写是下游回退判据的契约，勿随意改动。 */
+/** Structured error codes; spelling is part of the fallback contract. */
 export type AnySearchErrorCode = 'ABORTED' | 'TIMEOUT' | 'NETWORK' | 'AUTH' | 'RATE_LIMIT' | 'HTTP' | 'INVALID_RESPONSE' | 'INVALID_URL' | 'TARGET_BLOCKED' | 'CONTENT_TOO_LARGE' | 'UNSUPPORTED_CONTENT' | 'UPSTREAM';
-/** 带结构化错误码的 AnySearch 失败；message 沿用既有拼法，保证既有断言仍通过。 */
+/** Failure with a code; existing message wording remains part of the assertions. */
 export declare class AnySearchError extends Error {
     readonly code: AnySearchErrorCode;
     readonly upstreamCode?: string;
@@ -36,10 +34,7 @@ export declare class AnySearchError extends Error {
         status?: number;
     });
 }
-/**
- * AnySearch 失败后是否值得改走本机直连回退。
- * 只有调用方取消、URL 非法与内容类型不受支持三类不回退；其余都回退。
- */
+/** Fall back except for cancellation, invalid URL, and unsupported content type. */
 export declare function shouldFallbackToLocalFetch(code: AnySearchErrorCode): boolean;
 export interface AnySearchClient {
     search(request: {
@@ -57,5 +52,5 @@ export declare function normalizeSearchHit(raw: unknown): SearchHit | null;
 export declare function normalizeSearchResponse(query: string, raw: unknown): SearchResult;
 export declare function normalizeFetchResponse(url: string, raw: unknown): FetchResult;
 export declare function envKey(name: string): string | undefined;
-/** 创建 AnySearch REST 客户端；API key 每次请求重新解析，不缓存。 */
+/** Resolve the API key on every request; do not cache it. */
 export declare function createAnySearchClient(baseURL?: string, resolveApiKey?: () => Promise<string | undefined>): AnySearchClient;

package/lib/web-retriever/engines.js

@@ -1,13 +1,11 @@
 /**
- * AnySearch 的最小 REST 客户端。
- *
- * web_retriever 目前只支持一个后端，因此不预留多引擎注册表、动态 loader 或
- * provider 目录。未来真正接入第二个后端时，再根据实际差异抽象接口。
+ * Minimal AnySearch REST client. No multi-engine registry or provider directory
+ * exists until a second backend introduces a real abstraction need.
  */
-/** 第三方页面的正文与链接：与本机直抓共用同一份不可见字符剥离与可展示链接口径。 */
+/** Shared invisible-text and link presentation rules with local fetching. */
 import { stripInvisibleText } from './html-markdown.js';
 import { safeUrl } from './local-fetch.js';
-/** AnySearch 上游 error_code → 本地错误码映射。对齐官方 fetch-provider 的 webErrorCode 表。 */
+/** Map upstream error_code values, matching the official fetch-provider webErrorCode table. */
 const ERROR_CODE_MAP = {
     invalid_extract_url: 'INVALID_URL',
     extract_target_blocked: 'TARGET_BLOCKED',
@@ -15,7 +13,7 @@ const ERROR_CODE_MAP = {
     extract_unsupported_content: 'UNSUPPORTED_CONTENT',
     extract_timeout: 'TIMEOUT',
 };
-/** 带结构化错误码的 AnySearch 失败；message 沿用既有拼法，保证既有断言仍通过。 */
+/** Failure with a code; existing message wording remains part of the assertions. */
 export class AnySearchError extends Error {
     code;
     upstreamCode;
@@ -30,10 +28,7 @@ export class AnySearchError extends Error {
             this.status = extra.status;
     }
 }
-/**
- * AnySearch 失败后是否值得改走本机直连回退。
- * 只有调用方取消、URL 非法与内容类型不受支持三类不回退；其余都回退。
- */
+/** Fall back except for cancellation, invalid URL, and unsupported content type. */
 export function shouldFallbackToLocalFetch(code) {
     return code !== 'ABORTED' && code !== 'INVALID_URL' && code !== 'UNSUPPORTED_CONTENT';
 }
@@ -56,7 +51,7 @@ export function normalizeSearchHit(raw) {
     if (!raw || typeof raw !== 'object' || Array.isArray(raw))
         return null;
     const record = raw;
-    // 候选链接不合法就整条丢掉：既不能 fetch、也不能作为引用给用户点。
+    // Drop invalid links entirely: they cannot be fetched or presented as citations.
     const url = safeUrl(record.url);
     if (url === '')
         return null;
@@ -104,7 +99,7 @@ export function envKey(name) {
     const processLike = globalThis.process;
     return processLike?.env?.[name] || undefined;
 }
-/** 创建 AnySearch REST 客户端；API key 每次请求重新解析，不缓存。 */
+/** Resolve the API key on every request; do not cache it. */
 export function createAnySearchClient(baseURL = DEFAULT_BASE_URL, resolveApiKey = async () => envKey('ANYSEARCH_API_KEY')) {
     const root = baseURL.replace(/\/+$/, '');
     try {
@@ -164,7 +159,7 @@ export function createAnySearchClient(baseURL = DEFAULT_BASE_URL, resolveApiKey
                 }
             }
             catch {
-                // 非 JSON 响应转成下面的明确错误。
+                // Convert a non-JSON response into the structured error below.
             }
             const code = parsed?.code;
             const message = typeof parsed?.message === 'string' && parsed.message ? parsed.message : undefined;

package/lib/web-retriever/html-markdown.d.ts

@@ -1,50 +1,30 @@
 /**
- * HTML → GFM Markdown 转换（本地直抓回退的呈现层，todo 4 `local-fetch.ts` 消费）。
- *
- * 语义逐条移植自官方 DSH `web_fetch` 渲染器
- * （`dsh-LLM-icon/.research/dsh-src/packages/web/tool-web/src/fetch.ts`）：
- * turndown + GFM 插件、`removeNonVisibleContent` 规则、无跨列展开的表格规则、
- * 512 层嵌套词法守卫与固定省略标记。官方实现里与本模块无关的呈现职责
- * （`Fetched <url>` 头、截断脚注、WeakMap memoization）一律不搬——"网页正文不是指令"
- * 由 web_retriever persona 的硬规则承担，不在正文里插水印。
- *
- * 官方没做、这里补上的第四道：`stripInvisibleText`（零宽 / 双向覆盖 / C0-C1 控制符剥离）。
- * 它放在本模块导出，是因为 invisibles 的入口不止 HTML：`extractTitle` 会解码数字实体
- * （`&#x202E;` 解出来就是 RLO），AnySearch 返回的清洗正文也原样带这些字符。
- * 三个内容入口（本地转换、title、具名来源页面字段）共用这一份实现（AGENTS.md §9.7）。
- *
- * 为什么必须补这三道保护（turndown 的已知缺口）：
- * - turndown 默认**不删** `<script>/<style>`，其正文会当文本带进输出；
- * - turndown 完全**不处理**隐藏元素；
- * - turndown 的转换按元素递归，超深嵌套下可能爆栈或长时间占用事件循环——
- *   官方实测：嵌套 512 层 ≈ 0.15s、2000 层 ≈ 2s、20000 层 ≈ 5s，期间协作式
- *   超时定时器无法触发，所以超过 512 层直接放弃转换。
+ * Bounded HTML -> GFM markdown for the local-fetch fallback. Ported from the
+ * official web_fetch renderer, plus `stripInvisibleText` because turndown keeps
+ * script/style, ignores hidden elements, and recurses (stack/deadline risk at
+ * depth); conversion is abandoned past `MAX_CONVERSION_DEPTH`.
  */
-/** 嵌套深度上限：超过则跳过转换、返回固定省略标记。健壮性不变量，不是可调参数。 */
+/** Hard nesting limit: past it conversion is skipped. Robustness, not a tunable. */
 export declare const MAX_CONVERSION_DEPTH = 512;
-/** 转换结果：`title` 从原始 HTML 提取（源串截断不影响）；无 title 时缺省该字段。 */
+/** Result: title comes from the original HTML; omitted means conversion was skipped. */
 export interface HtmlMarkdownResult {
     title?: string;
-    /** 转换后的 GFM markdown；转换不安全时为固定省略标记。 */
+    /** GFM markdown, or the fixed omission marker when conversion is unsafe. */
     markdown: string;
-    /** 源串或输出曾被 `maxChars` 截断。 */
+    /** Source or output was cut by `maxChars`. */
     truncated: boolean;
-    /** true 表示转换被放弃（超深或 turndown 抛错），`markdown` 为省略标记。 */
+    /** Conversion was abandoned (too deep or turndown threw). */
     omitted: boolean;
 }
 export declare function stripInvisibleText(value: string): string;
 /**
- * 从 HTML 开头提取 `<title>` 并解码实体、压空白。找不到或解码后为空返回
- * `undefined`。注意：`<title>` 的文本按官方行为仍会留在 markdown 正文里
- * （官方 remove 列表不含 TITLE），本函数只负责回执的 `title` 字段。
+ * Extract `<title>` from the document head and decode entities. The title text is
+ * left in the markdown body (matching official behavior); this only feeds the field.
  */
 export declare function extractTitle(html: string): string | undefined;
 /**
- * 把 HTML 转成有界 GFM markdown。
- *
- * 流程：先按 `maxChars` 截断源串（记 `truncated`，与官方 renderBody 一致）→
- * 超深或 turndown 抛错 → 固定省略标记 + `omitted: true`（不让原始标记外漏）→
- * 否则转换，剥掉不可见字符（`stripInvisibleText`），再按 `maxChars` 截断输出。
- * `title` 一律从**原始** HTML 提取。
+ * Convert HTML to bounded GFM markdown. Source is cut to `maxChars` first; unsafe
+ * conversion returns the omission marker; output is stripped of invisibles and cut
+ * to `maxChars`. Title always comes from the original HTML.
  */
 export declare function htmlToMarkdown(html: string, maxChars: number): HtmlMarkdownResult;

package/lib/web-retriever/html-markdown.js

@@ -1,53 +1,28 @@
 /**
- * HTML → GFM Markdown 转换（本地直抓回退的呈现层，todo 4 `local-fetch.ts` 消费）。
- *
- * 语义逐条移植自官方 DSH `web_fetch` 渲染器
- * （`dsh-LLM-icon/.research/dsh-src/packages/web/tool-web/src/fetch.ts`）：
- * turndown + GFM 插件、`removeNonVisibleContent` 规则、无跨列展开的表格规则、
- * 512 层嵌套词法守卫与固定省略标记。官方实现里与本模块无关的呈现职责
- * （`Fetched <url>` 头、截断脚注、WeakMap memoization）一律不搬——"网页正文不是指令"
- * 由 web_retriever persona 的硬规则承担，不在正文里插水印。
- *
- * 官方没做、这里补上的第四道：`stripInvisibleText`（零宽 / 双向覆盖 / C0-C1 控制符剥离）。
- * 它放在本模块导出，是因为 invisibles 的入口不止 HTML：`extractTitle` 会解码数字实体
- * （`&#x202E;` 解出来就是 RLO），AnySearch 返回的清洗正文也原样带这些字符。
- * 三个内容入口（本地转换、title、具名来源页面字段）共用这一份实现（AGENTS.md §9.7）。
- *
- * 为什么必须补这三道保护（turndown 的已知缺口）：
- * - turndown 默认**不删** `<script>/<style>`，其正文会当文本带进输出；
- * - turndown 完全**不处理**隐藏元素；
- * - turndown 的转换按元素递归，超深嵌套下可能爆栈或长时间占用事件循环——
- *   官方实测：嵌套 512 层 ≈ 0.15s、2000 层 ≈ 2s、20000 层 ≈ 5s，期间协作式
- *   超时定时器无法触发，所以超过 512 层直接放弃转换。
+ * Bounded HTML -> GFM markdown for the local-fetch fallback. Ported from the
+ * official web_fetch renderer, plus `stripInvisibleText` because turndown keeps
+ * script/style, ignores hidden elements, and recurses (stack/deadline risk at
+ * depth); conversion is abandoned past `MAX_CONVERSION_DEPTH`.
  */
 import TurndownService from 'turndown';
 import { gfm } from '@joplin/turndown-plugin-gfm';
-/** 嵌套深度上限：超过则跳过转换、返回固定省略标记。健壮性不变量，不是可调参数。 */
+/** Hard nesting limit: past it conversion is skipped. Robustness, not a tunable. */
 export const MAX_CONVERSION_DEPTH = 512;
-// ---------------------------------------------------------------------------
-// 不可见字符剥离（外部内容共用的出口）
-// ---------------------------------------------------------------------------
+// Invisible character stripping (shared by every external-content entry)
 /**
- * 网页里可以出现**完全没有字形**的字符，而它们会原样进入模型上下文与用户看到的引用：
- * - C0/C1 控制符与 DEL：`\r`、`\x00` 之类能把一行截断或让后续文本覆盖已显示内容；
- * - 软连字符 `U+00AD`、零宽系列 `U+200B–U+200F`（含 LRM/RLM 方向标记）/ `U+2060–U+2064` / BOM：
- *   肉眼不可见，却能把 `忽略前面的指令` 写成关键词字面检查**认不出**的形状；
- * - 双向覆盖 `U+202A–U+202E` / 隔离符 `U+2066–U+2069`：改变一行的**显示顺序**
- *   （Trojan Source 一类攻击），回显给用户的就是假的文本；
- * - `U+2028` / `U+2029`：行/段分隔符，渲染上与 `\n` 等价、按行处理时又不算换行。
- *
- * 只删不替换成占位符：这些字符在合法正文里没有承载信息，删除是保序的。
- * 换行 `\n`、回车 `\r`、制表 `\t` 保留（markdown 呈现需要）。
+ * Some characters render as nothing yet reach the model and citations: C0/C1
+ * controls, soft hyphen/zero-width/BOM (keyword checks miss them), bidi overrides
+ * and isolates (Trojan Source display spoofing), U+2028/2029. Deleting preserves
+ * order; keep \n, \r and \t for markdown.
  */
 const INVISIBLE_PATTERN = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F\u00AD\u200B-\u200F\u2028\u2029\u202A-\u202E\u2060-\u2064\u2066-\u2069\uFEFF]/gu;
 export function stripInvisibleText(value) {
     return value.replace(INVISIBLE_PATTERN, '');
 }
 /**
- * 模块作用域唯一的 turndown 实例。官方注释明说该实例跨 `turndown()` 调用无状态、
- * 可共享；规则只注册一次，全部转换复用（测试用幂等用例钉住这一点）。
- * 规则注册顺序与官方一致：先 `use(gfm)`，再 remove 规则，最后表格规则——
- * turndown 按后注册先匹配解析规则，表格规则因此覆盖 gfm 插件自带的跨列展开实现。
+ * One module-scope turndown instance (stateless across calls). Rule order matters:
+ * gfm, then remove rules, then table rules; table rules must come last to override
+ * the plugin's colspan expansion.
  */
 const turndown = new TurndownService({
     headingStyle: 'atx',
@@ -55,7 +30,7 @@ const turndown = new TurndownService({
     bulletListMarker: '-',
 });
 turndown.use(gfm);
-/** 命中即整块删除（replacement 返回空串），脚本/样式/隐藏元素的内容不进输出。 */
+/** Match => drop the whole block; script/style/hidden content never reaches output. */
 turndown.addRule('removeNonVisibleContent', {
     filter(node) {
         if (['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEMPLATE', 'IFRAME', 'OBJECT', 'EMBED'].includes(node.nodeName))
@@ -79,13 +54,13 @@ turndown.addRule('removeNonVisibleContent', {
         return '';
     },
 });
-/** 渲染一个 GFM 表格单元格，不解释 HTML 的跨列计数。 */
+/** Render one GFM cell; HTML colspan is deliberately not interpreted. */
 function renderTableCell(content, index) {
     const prefix = index === 0 ? '| ' : ' ';
     const escaped = content.trim().replace(/\n\r/g, '<br>').replace(/\n/g, '<br>').replace(/\|+/g, '\\|').padEnd(3, ' ');
     return `${prefix}${escaped} |`;
 }
-/** 该行是否表格的 Markdown 表头行。 */
+/** Whether this row is the markdown header row of its table. */
 function isTableHeadingRow(row) {
     const cells = Array.from(row.cells);
     const section = row.parentElement;
@@ -93,7 +68,7 @@ function isTableHeadingRow(row) {
     return (section.nodeName === 'THEAD' || table.rows[0] === row)
         && cells.every(cell => cell.nodeName === 'TH');
 }
-/** 把 HTML 单元格对齐方式映射成 GFM 分隔符。 */
+/** Map HTML cell alignment to a GFM separator. */
 function tableBorder(cell) {
     const alignment = (cell.getAttribute('align') || cell.style.textAlign || '').toLowerCase();
     if (alignment === 'left')
@@ -109,8 +84,8 @@ turndown.addRule('tableCellWithoutSpanExpansion', {
     replacement(content, node) {
         const cell = node;
         const row = cell.parentNode;
-        // GFM 无法表达跨列。忽略 colspan 让转换工作量与输出和源成正比，
-        // 而不是跟数字属性走（gfm 插件自带规则会按 colspan 展开成多个空单元格）。
+        // GFM cannot express colspan; ignoring it keeps output proportional to source
+        // text instead of the numeric attribute (the gfm rule expands empty cells).
         return renderTableCell(content, Array.from(row.childNodes).indexOf(cell));
     },
 });
@@ -124,21 +99,19 @@ turndown.addRule('tableRowWithoutSpanExpansion', {
         return `\n${content}${border.length > 0 ? `\n${border}` : ''}`;
     },
 });
-// ---------------------------------------------------------------------------
-// 嵌套深度词法守卫（官方 fetch.ts:120-223 的移植）
-// ---------------------------------------------------------------------------
-/** 永不接收闭合标签的元素：不进词法栈。 */
+// Nesting-depth guard (ported from official fetch.ts)
+/** Elements that never take a closing tag: kept out of the lexical stack. */
 const VOID_ELEMENTS = new Set([
     'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
     'link', 'meta', 'param', 'source', 'track', 'wbr',
 ]);
-/** 正文按纯文本解析、直到匹配闭合标签的元素。 */
+/** Text until the matching close tag is raw text, not markup. */
 const RAW_TEXT_ELEMENTS = new Set(['script', 'style', 'noscript']);
-/** 一个字符能否出现在 raw-text 闭合标签名之后。 */
+/** Whether a char can follow a raw-text close tag name. */
 function isTagBoundary(char) {
     return char === undefined || char === '>' || char === '/' || /\s/.test(char);
 }
-/** 找 raw-text 元素的匹配闭合标签，不把正文里长得像标记的文本当标签。 */
+/** Find a raw-text close tag, ignoring markup-like text inside the body. */
 function findRawTextEnd(lowerHtml, name, from) {
     const prefix = `</${name}`;
     let candidate = lowerHtml.indexOf(prefix, from);
@@ -148,9 +121,9 @@ function findRawTextEnd(lowerHtml, name, from) {
     return candidate;
 }
 /**
- * 保守地拒绝词法元素栈超过转换深度上限的 HTML。单遍扫描：忽略注释里的闭合
- * 标签、跳过 raw-text 正文、尊重引号里的 `>`、只接受与栈顶同名的闭合标签——
- * 畸形输入因此只会多计嵌套，不会把嵌套藏掉。
+ * Reject HTML whose lexical element stack exceeds the depth limit. Single pass:
+ * ignores close tags in comments, skips raw text, respects quoted `>`, only pops a
+ * matching top-of-stack, so malformed input over-counts rather than hides nesting.
  */
 function exceedsConversionDepth(html) {
     const lowerHtml = html.toLowerCase();
@@ -228,10 +201,8 @@ function exceedsConversionDepth(html) {
     }
     return false;
 }
-// ---------------------------------------------------------------------------
-// title 提取
-// ---------------------------------------------------------------------------
-/** 只在开头固定窗口内找 `<title>`：title 位于 head、靠文档开头，窗口上限避免对超长正文全量扫描。 */
+// Title extraction
+/** Scan only the opening window: `<title>` lives in head, avoid full-document scans. */
 const TITLE_SCAN_CHARS = 2048;
 const TITLE_PATTERN = /<title[^>]*>([^<]*)<\/title>/i;
 const ENTITY_PATTERN = /&(?:amp|lt|gt|quot|nbsp|#[0-9]+|#[xX][0-9a-fA-F]+);/g;
@@ -242,7 +213,7 @@ const NAMED_ENTITIES = new Map([
     ['quot', '"'],
     ['nbsp', '\u00a0'],
 ]);
-/** 解码数字字符引用（十进制与十六进制）；非法码点返回 null（保留原文）。 */
+/** Decode a numeric character reference; invalid code point => null (keep text). */
 function decodeNumericEntity(body) {
     const hex = body[1] === 'x' || body[1] === 'X';
     const code = Number.parseInt(body.slice(hex ? 2 : 1), hex ? 16 : 10);
@@ -250,7 +221,7 @@ function decodeNumericEntity(body) {
         return null;
     return String.fromCodePoint(code);
 }
-/** 单遍解码实体：`&amp;lt;` 只解成 `&lt;`，不会第二轮再解成 `<`。 */
+/** Single-pass entity decode: `&amp;lt;` becomes `&lt;`, never `<`. */
 function decodeEntities(text) {
     return text.replace(ENTITY_PATTERN, (match) => {
         const body = match.slice(1, -1);
@@ -261,9 +232,8 @@ function decodeEntities(text) {
     });
 }
 /**
- * 从 HTML 开头提取 `<title>` 并解码实体、压空白。找不到或解码后为空返回
- * `undefined`。注意：`<title>` 的文本按官方行为仍会留在 markdown 正文里
- * （官方 remove 列表不含 TITLE），本函数只负责回执的 `title` 字段。
+ * Extract `<title>` from the document head and decode entities. The title text is
+ * left in the markdown body (matching official behavior); this only feeds the field.
  */
 export function extractTitle(html) {
     const match = TITLE_PATTERN.exec(html.slice(0, TITLE_SCAN_CHARS));
@@ -272,10 +242,8 @@ export function extractTitle(html) {
     const title = stripInvisibleText(decodeEntities(match[1])).replace(/\s+/g, ' ').trim();
     return title === '' ? undefined : title;
 }
-// ---------------------------------------------------------------------------
-// 入口
-// ---------------------------------------------------------------------------
-/** 转换不安全（超深或 turndown 抛错）时返回的固定省略标记。 */
+// Entry point
+/** Fixed marker returned when conversion is unsafe (too deep or turndown threw). */
 const OMITTED_MARKDOWN = '[HTML content omitted: unable to convert safely.]';
 function omittedResult(title, sourceTruncated, maxChars) {
     const outputTruncated = OMITTED_MARKDOWN.length > maxChars;
@@ -287,12 +255,9 @@ function omittedResult(title, sourceTruncated, maxChars) {
     };
 }
 /**
- * 把 HTML 转成有界 GFM markdown。
- *
- * 流程：先按 `maxChars` 截断源串（记 `truncated`，与官方 renderBody 一致）→
- * 超深或 turndown 抛错 → 固定省略标记 + `omitted: true`（不让原始标记外漏）→
- * 否则转换，剥掉不可见字符（`stripInvisibleText`），再按 `maxChars` 截断输出。
- * `title` 一律从**原始** HTML 提取。
+ * Convert HTML to bounded GFM markdown. Source is cut to `maxChars` first; unsafe
+ * conversion returns the omission marker; output is stripped of invisibles and cut
+ * to `maxChars`. Title always comes from the original HTML.
  */
 export function htmlToMarkdown(html, maxChars) {
     const title = extractTitle(html);
@@ -306,8 +271,7 @@ export function htmlToMarkdown(html, maxChars) {
         converted = turndown.turndown(content);
     }
     catch {
-        // turndown 的 DOM 遍历按元素递归；词法守卫建模不了的畸形标记仍可能抛
-        // RangeError。转换失败与超深走同一个省略标记，不把源标记带回模型上下文。
+        // The lexical guard cannot model every malformed tree; RangeError => same marker.
         return omittedResult(title, sourceTruncated, maxChars);
     }
     const sanitized = stripInvisibleText(converted);