docs: include JSDoc in website API markers

website/zh-CN/api/harness/compact.md

@@ -11,6 +11,21 @@ Abstract compaction service. Implementations own trigger policy, retention, and
 ### ctx.compact.compactIfNeeded(agent, fullSystemPrompt, sessionPrefix, signal)
 
 ```ts website-api
+/**
+ * Check token pressure and compact if the conversation is too large.
+ * Estimate the next request, including its session prefix, derived history,
+ * and system prompt. Above threshold, compact a head-anchored range ending at
+ * a balanced tool boundary and reconsolidate any prior automatic checkpoint.
+ * Return `null` when no compaction is needed or an open tail leaves no safe
+ * cutoff. A single oversized retained unit or prefix cannot be repaired here.
+ *
+ * @param agent - agent context owning the session surface and model options.
+ * @param fullSystemPrompt - assembled system prompt, counted toward the estimate.
+ * @param sessionPrefix - the instance's composed session prefix, counted toward the
+ *   estimate.
+ * @param signal - cancellation signal; model-backed implementations must forward it.
+ * @returns the compaction result, or `null` if no compaction was needed.
+ */
 abstract compactIfNeeded( agent: CompactAgentContext, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal, ): Promise<CompactionResult | null>
 ```
 
@@ -28,6 +43,23 @@ Check token pressure and compact if the conversation is too large. Estimate the
 ### ctx.compact.compactRegion(start, end, agent, signal?)
 
 ```ts website-api
+/**
+ * Forcibly compact a range of surface nodes into a single summary node.
+ * `start` and `end` name an inclusive span by surface position, not numeric seq
+ * order; replacements can make visible seqs non-monotonic. Both edges must be
+ * balanced so assistant tool calls remain paired with their results. A model-
+ * backed implementation forwards cancellation and rejects active, missing,
+ * reversed, or unbalanced ranges. The target session is `agent.session`.
+ * Use {@link toolPairingBalancedBefore} and {@link toolPairingBalancedAfter}
+ * for the edge checks.
+ *
+ * @param start - first surface seq, inclusive.
+ * @param end - last surface seq, inclusive.
+ * @param agent - context whose session is mutated and whose routing options guide summarization.
+ * @param signal - optional cancellation; model-backed implementations must forward it.
+ * @throws when compaction is active or the range is missing, reversed, or unbalanced.
+ * @returns the appended event seqs, summary, replaced range, and token accounting.
+ */
 abstract compactRegion( start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>
 ```