@linnlabs/linnkit 0.8.0

package/dist/toolContracts-CLkQmhTG.d.cts

@@ -0,0 +1,463 @@
+import { e as RuntimeEvent, g as SubRunTraceEvent, a as AgentTodoSnapshot } from './todo-B1PmDlp3.cjs';
+
+interface ToolContextConversationView {
+    /**
+     * 当前工具执行可见的 working history
+     *
+     * 中文备注：
+     * - 该视图允许工具读取“本轮 run 中已产生、但可能尚未持久化”的最新事实事件；
+     * - ToolNode / graph runtime 后续只应更新这一层背后的 source，而不是覆写顶层 getter。
+     */
+    getWorkingHistoryEvents(): ReadonlyArray<RuntimeEvent>;
+    /**
+     * run 启动时的 persisted history 视图
+     *
+     * 中文备注：
+     * - 该视图对应 EventStore 回放得到的稳定历史；
+     * - 与 working history 显式区分，避免调用方误把“最新运行态”当成“已持久化事实”。
+     */
+    getPersistedHistoryEvents(): ReadonlyArray<RuntimeEvent>;
+}
+
+/**
+ * 子 run trace 的“业务无关”发布载荷。
+ *
+ * 说明：
+ * - 该结构刻意只包含 subrun_trace 的 payload 字段（不包含 conversation_id/turn_id 等基础字段）
+ * - parent_tool_call_id/subrun_id 是发布器构造时绑定的，不需要每次 publish 重复提供
+ */
+interface SubRunTraceEnvelope {
+    /** 分片类型 */
+    kind: SubRunTraceEvent['kind'];
+    /** 增量文本（kind=*_delta 时使用） */
+    delta?: string;
+    /** 完整文本（kind=*_complete/final_answer 时使用） */
+    content?: string;
+    /** 关联工具名（kind=tool_call_decision/tool_process/tool_output 时使用） */
+    tool_name?: string;
+    /** 关联工具调用 ID（子 run 内部的 tool_call_id，用于展示步骤） */
+    tool_call_id?: string;
+    /** 工具调用阶段（kind=tool_call_decision/tool_process 时使用） */
+    phase?: SubRunTraceEvent['phase'];
+    /** 工具调用状态（kind=tool_call_decision/tool_process/tool_output 时使用） */
+    status?: SubRunTraceEvent['status'];
+    /** 工具参数（结构不做强约束，避免与业务强耦合） */
+    args?: unknown;
+    /** 工具输出（结构不做强约束，避免与业务强耦合） */
+    output?: unknown;
+    /** 执行耗时（毫秒） */
+    duration_ms?: number;
+    /** 可选调试/渲染元信息 */
+    meta?: Record<string, unknown>;
+}
+/**
+ * 子 run trace 发布器接口（面向业务工具层）。
+ *
+ * 约束：
+ * - 发布器必须确保生成的 RuntimeEvent 为 `type='subrun_trace'` 且 `ephemeral=true`
+ * - 发布器应保证每条事件的 id 唯一（用于前端 processedEvents 幂等去重）
+ */
+interface SubRunTracePublisher {
+    publish(envelope: SubRunTraceEnvelope): void;
+}
+
+/**
+ * @file src/agent/runtime-kernel/run-context/types.ts
+ * @description 统一运行上下文定义
+ *
+ * 核心目标：
+ * - 统一管理跨 Run（Graph执行）的链路追踪信息
+ * - 支持父子任务（SubAgent）与审阅等长程业务的上下文贯穿
+ * - 替代散落在各处的 review_run_id 等专用字段
+ */
+interface RunContext {
+    /**
+     * 当前 Run 的唯一标识（对应一次 Graph 执行 / 一次 conversation turn）
+     * - 通常对应 `turnId` 或 `messageId`
+     */
+    runId: string;
+    /**
+     * 链路追踪 ID（贯穿业务全流程）
+     * - Review场景：对应 review_run_id（一次审阅包含多次 AI 调用）
+     * - 简单对话场景：可与 conversationId 或 runId 相同
+     */
+    traceId: string;
+    /**
+     * 父级 Run ID（用于子 Agent / 嵌套图）
+     * - 如果是顶层任务，则为 undefined
+     */
+    parentId?: string;
+    /**
+     * 根 Run ID（业务发起的原点）
+     */
+    rootRunId?: string;
+    /**
+     * 业务标签/元数据（业务特定的上下文挂载点）
+     * - 例如：{ agentId: 'logicCheck', chunkIndex: 0 }
+     * - 替代原先散落在 ToolContext 顶层的 loose fields
+     */
+    tags: Record<string, string | number | boolean | undefined>;
+}
+/**
+ * 创建默认的 RunContext
+ */
+declare function createDefaultRunContext(overrides?: Partial<RunContext>): RunContext;
+
+interface ToolContextCompatibilityFields {
+    /**
+     * 兼容字段：原始用户请求
+     *
+     * 中文备注：
+     * - 当前由 host context injection 写入；
+     * - 仍有少量 deep_search 调用方在读取；
+     * - 后续应继续收窄，不再扩散新的读取点。
+     */
+    user_query?: string;
+    /**
+     * 兼容字段：当前 run 选定模型 ID
+     *
+     * 中文备注：
+     * - 当前主要给 child-run 调用方继承父模型选择；
+     * - 后续应继续收窄到显式 child-run execution policy。
+     */
+    modelId?: string;
+    /**
+     * 兼容字段：当前 runContext
+     *
+     * 中文备注：
+     * - 当前主要由 host 注入；尚未在工具侧广泛直接读取；
+     * - 保留显式字段是为了停止继续依赖 string-index loose access。
+     */
+    run_context?: RunContext;
+}
+type CompatibilityCarrier = ToolContextCompatibilityFields | Record<string, unknown> | undefined;
+declare function readToolContextUserQuery(context: CompatibilityCarrier): string | undefined;
+declare function readToolContextModelId(context: CompatibilityCarrier): string | undefined;
+declare function readToolContextRunContext(context: CompatibilityCarrier): RunContext | undefined;
+
+/**
+ * child-run 父上下文的 runtime-owned 最小合同
+ *
+ * 中文备注：
+ * - 这里只声明 child-run 协议真正需要的 runtime capability / compatibility fields；
+ * - 不显式依赖完整 ToolContext，避免 child-run 主链编译期吃进整套 host/product 服务类型；
+ * - 仍保留 index signature，用于在创建 child ToolContext 时透传宿主/产品层 patch。
+ */
+interface ChildRunParentContext extends ToolExecutionContext, ToolContextCompatibilityFields {
+    deepSearchDepth?: number;
+    [key: string]: unknown;
+}
+interface ChildRunHistoryPolicy {
+    inheritTurns: number;
+    eventFilter?: (event: RuntimeEvent) => boolean;
+}
+interface ChildRunTracePolicy {
+    parentToolCallId?: string;
+    subrunId?: string;
+    source?: string;
+    metadata?: Record<string, unknown>;
+    persistForReplay?: boolean;
+}
+interface ChildRunExecutionPolicy {
+    /**
+     * 显式 child-run runId。默认由 host adapter 取 subrunId。
+     */
+    runId?: string;
+    /**
+     * 父 runId。默认从 parentToolContext.runId 继承。
+     */
+    parentRunId?: string;
+    maxSteps?: number;
+    modelId?: string;
+    abortSignal?: AbortSignal;
+}
+interface ChildRunRequest<TParentToolContext = ChildRunParentContext> {
+    userMessage: string;
+    parentToolContext: TParentToolContext;
+    historyPolicy?: ChildRunHistoryPolicy;
+    tracePolicy?: ChildRunTracePolicy;
+    executionPolicy?: ChildRunExecutionPolicy;
+}
+interface ChildRunResult {
+    runId?: string;
+    parentRunId?: string;
+    subrunId: string;
+    success: boolean;
+    finalAnswer: string;
+    events: RuntimeEvent[];
+    stepCount: number;
+    error?: string;
+    judgeToolOutput?: string;
+}
+interface ChildRunInvokerPort<TRequest extends ChildRunRequest = ChildRunRequest, TResult extends ChildRunResult = ChildRunResult> {
+    invoke(params: TRequest): Promise<TResult>;
+}
+
+/**
+ * runtime-owned 工具执行上下文最小合同
+ *
+ * 中文备注：
+ * - 这里只保留 graph-engine / tool runtime / child-run 真正需要解释执行的字段；
+ * - 不包含 KnowledgeBase / Workspace / DB 等宿主服务类型；
+ * - 不包含 deepSearch / research / workspaceProject 等产品语义字段。
+ */
+interface ToolExecutionContext {
+    /**
+     * 当前对话 run 的唯一标识（由 FlowOrchestrator 注入）
+     * 说明：Workspace 工具 vNext 协议已不再依赖 index 快照，但 runId 仍可用于其他链路的追踪/调试。
+     */
+    runId?: string;
+    /**
+     * 父级 run 标识。
+     *
+     * 中文备注：
+     * - 顶层 run 通常为空；
+     * - 同步 child-run 会把自己的 `runId` 设为子 run / subrun ID，同时把父 run 写到这里；
+     * - Telemetry / Audit / Cost 聚合依赖这个字段建立父子关系，但 graph-engine 不解释产品语义。
+     */
+    parentRunId?: string;
+    /**
+     * 🔥 引用编号偏移量（用于多次工具调用时的连续编号）
+     *
+     * 工作原理：
+     * - 每次调用知识库工具时,由 ToolNode 传入当前轮次已使用的引用数量
+     * - 工具在格式化 observation 和构建 citations 时使用此偏移量
+     * - 确保 AI 看到的编号和引用元数据的编号都是连续且一致的
+     *
+     * @default 0 - 表示从 1 开始编号
+     */
+    citationOffset?: number;
+    /**
+     * 🔥 取消信号（贯穿一次对话请求）
+     *
+     * 约定：
+     * - 工具实现必须在合适的边界检查 `abortSignal.aborted` 并尽快退出；
+     * - 该字段属于“执行期上下文”，不应被写入持久化事件。
+     */
+    abortSignal?: AbortSignal;
+    /**
+     * 🔥 当前这次工具调用的 tool_call_id（由 ToolNode 在执行前注入）
+     *
+     * 说明：
+     * - tool_call_id 属于“事件层/执行层”的稳定关联键；
+     * - 工具内部如果需要发布 subrun_trace（子 run 过程），必须使用该字段作为 parent_tool_call_id。
+     * - 该字段仅在工具执行期间有效，不应被工具写入持久化历史。
+     */
+    parentToolCallId?: string;
+    /**
+     * 🔥 当前对话 ID（由 GraphExecutor/ToolNode 注入，用于工具内部做链路追踪）
+     */
+    conversationId?: string;
+    /**
+     * 🔥 当前轮次 ID（由 GraphExecutor/ToolNode 注入，用于工具内部做链路追踪）
+     */
+    turnId?: string;
+    /**
+     * 🔥 Agent ToDo（working memory）快照（对话级）
+     *
+     * 设计说明：
+     * - ToDo 的权威状态应落到 RuntimeEvent（todo_updated）以便截断/回放一致；
+     * - 但工具执行期间需要“读到本轮最新状态”（尚未落库），因此把最新快照同时缓存到 ToolContext。
+     * - AgentRunnerService 会在每次 run 开始时用历史事件回放的最后一条 todo_updated 为其初始化。
+     */
+    agentTodo?: AgentTodoSnapshot;
+    /**
+     * 🔥 显式会话视图 capability
+     *
+     * 中文备注：
+     * - `conversationView` 是后续统一承载 working/persisted history 的稳定协议面；
+     * - 迁移期仍保留 `getConversationHistoryEvents()` 兼容旧工具。
+     */
+    conversationView?: ToolContextConversationView;
+    /**
+     * 🔥 获取父会话的历史事件（兼容 getter）
+     *
+     * 约束：
+     * - 返回值必须被视为只读：工具不得修改数组内容；
+     * - 迁移期该 getter 语义固定为 `conversationView.getWorkingHistoryEvents()`；
+     * - 新代码优先直接使用 `conversationView`，避免继续把 working/persisted history 混为一个概念。
+     */
+    getConversationHistoryEvents?: () => ReadonlyArray<RuntimeEvent>;
+    /**
+     * 🔥 发布 todo_updated RuntimeEvent（低耦合注入）
+     */
+    publishAgentTodoUpdated?: (snapshot: AgentTodoSnapshot) => void;
+    /**
+     * 🔥 SubRun Trace Channel：为工具提供 publisher 工厂（低耦合）
+     */
+    createSubRunTracePublisher?: (opts: {
+        parentToolCallId: string;
+        subrunId: string;
+        subrunParentId?: string;
+        source?: string;
+        metadata?: Record<string, unknown>;
+        persistForReplay?: boolean;
+    }) => SubRunTracePublisher;
+    /**
+     * 显式 child-run invoker 注入（迁移期优先入口）
+     */
+    registeredChildRunInvoker?: ChildRunInvokerPort;
+    /**
+     * 与 ConversationArtifactContext 等「可扩展宿主字段」交织时的结构兼容：
+     * - 运行期 toolContext 常为普通对象，可能携带 sharedMemory / research 等附加键；
+     * - 无此索引签名时，`ToolExecutionContext` 无法赋给 `ToolExecutionContext & ConversationArtifactContext`（strict 下报错）。
+     */
+    [key: string]: unknown;
+}
+
+/**
+ * @file src/agent/runtime-kernel/tools/ui-types.ts
+ *
+ * @brief 定义工具在前端UI展示时所需的元数据类型
+ *
+ * @description
+ * 这个文件中的类型专门用于 "后端驱动UI (Backend-Driven UI)" 架构。
+ * 当后端Agent执行一个工具时，它会附带这些UI元数据。
+ * 前端则根据这些元数据，动态地、智能地渲染出对应的UI组件，
+ * 从而实现工具展示逻辑与前端渲染逻辑的解耦。
+ */
+interface ToolLayoutOptions {
+    contentPadding?: boolean;
+    showBorder?: boolean;
+    showBackground?: boolean;
+}
+interface ToolDisplayOptions {
+    viewType: string;
+    titleTemplate?: string;
+    icon?: string;
+    layout?: ToolLayoutOptions;
+}
+interface ToolControlInfo {
+    requireUser?: boolean;
+    questionnaireId?: string;
+    resumeStrategy?: 'continue';
+    terminateRun?: boolean;
+    reason?: string;
+}
+interface StructuredToolResult<T = Record<string, unknown>> {
+    data: T;
+    observation?: string;
+    control?: ToolControlInfo;
+}
+
+type ToolIdempotencyScope = 'conversation' | 'turn';
+type ToolIdempotencyPolicy = {
+    scope: ToolIdempotencyScope;
+};
+declare function computeToolIdempotencyKey(params: {
+    policy: ToolIdempotencyPolicy;
+    toolName: string;
+    args: Record<string, unknown>;
+    context: ToolExecutionContext;
+}): string;
+declare function findCachedToolOutputByIdempotencyKey(params: {
+    history: ReadonlyArray<RuntimeEvent>;
+    toolName: string;
+    idempotencyKey: string;
+}): {
+    output: string;
+} | undefined;
+
+type ToolArgs = Record<string, unknown>;
+type JsonObjectSchema = Record<string, unknown>;
+interface ToolParameterProperty {
+    type: string;
+    description: string;
+    default?: unknown;
+    enum?: string[];
+    properties?: Record<string, ToolParameterProperty>;
+    items?: ToolParameterProperty;
+    required?: string[];
+}
+interface ToolParameterSchema {
+    type: 'object';
+    properties: Record<string, ToolParameterProperty>;
+    required?: string[];
+    additionalProperties?: boolean;
+}
+interface ToolResult {
+    success: boolean;
+    data: string;
+    metadata?: Record<string, unknown>;
+}
+type UnifiedToolResult = {
+    kind: 'ok';
+    output: unknown;
+} | {
+    kind: 'need_user';
+    spec: unknown;
+} | {
+    kind: 'async';
+    run_id: string;
+};
+declare abstract class BaseTool<TArgs extends ToolArgs = ToolArgs, TResult extends string = string> {
+    abstract readonly name: string;
+    abstract readonly description: string;
+    abstract readonly parameters: ToolParameterSchema;
+    readonly idempotency?: ToolIdempotencyPolicy;
+    readonly displayOptions?: ToolDisplayOptions;
+    getExecutionSummary?(output: string): string;
+    abstract run(args: TArgs, context: ToolExecutionContext): Promise<TResult>;
+    protected validateArguments(args: TArgs): {
+        success: boolean;
+        error?: string;
+    };
+    getMetadata(): {
+        name: string;
+        description: string;
+        parameters: ToolParameterSchema;
+    };
+}
+interface ToolRegistryEntry {
+    name: string;
+    toolClass: new () => BaseTool<ToolArgs, string>;
+    metadata: ReturnType<BaseTool['getMetadata']>;
+}
+declare const CommonParameterTypes: {
+    readonly docId: {
+        readonly type: "string";
+        readonly description: "The unique ID of the document";
+    };
+    readonly query: {
+        readonly type: "string";
+        readonly description: "The search query text";
+    };
+    readonly topK: {
+        readonly type: "integer";
+        readonly description: "The maximum number of results to return";
+        readonly default: 5;
+    };
+    readonly blockId: {
+        readonly type: "string";
+        readonly description: "The unique ID of a content block";
+    };
+    readonly pageNumber: {
+        readonly type: "integer";
+        readonly description: "Page number (1-indexed)";
+        readonly default: 1;
+    };
+};
+interface AgentTool<TArgs extends ToolArgs = ToolArgs, TResult = unknown> {
+    name: string;
+    description: string;
+    parameters: JsonObjectSchema;
+    execute(args: TArgs): Promise<TResult>;
+}
+interface OpenAIToolSchema {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: JsonObjectSchema;
+    };
+}
+interface ToolCallResult<TResult = unknown> {
+    toolName: string;
+    args: ToolArgs;
+    result: TResult;
+    success: boolean;
+    error?: string;
+    durationMs: number;
+}
+
+export { type AgentTool as A, BaseTool as B, CommonParameterTypes as C, type JsonObjectSchema as J, type OpenAIToolSchema as O, type RunContext as R, type StructuredToolResult as S, type ToolExecutionContext as T, type UnifiedToolResult as U, type ToolArgs as a, type ToolParameterSchema as b, type ToolParameterProperty as c, type ToolContextConversationView as d, type ToolCallResult as e, type ToolContextCompatibilityFields as f, type ToolControlInfo as g, type ToolDisplayOptions as h, type ToolLayoutOptions as i, type ToolRegistryEntry as j, type ToolResult as k, computeToolIdempotencyKey as l, findCachedToolOutputByIdempotencyKey as m, readToolContextRunContext as n, readToolContextUserQuery as o, createDefaultRunContext as p, type ChildRunParentContext as q, readToolContextModelId as r, type SubRunTracePublisher as s, type ChildRunHistoryPolicy as t, type ChildRunInvokerPort as u, type ChildRunRequest as v, type ChildRunResult as w, type SubRunTraceEnvelope as x, type ToolIdempotencyPolicy as y };

package/docs/README.md

@@ -0,0 +1,76 @@
+# linnkit Docs
+
+`linnkit` 是一个通用 Agent 框架。它提供 runtime、context engineering、ports、testkit 和 quickstart；具体 LLM provider、工具集、存储、实时通道、权限、业务上下文都由 host 自己装配。
+
+这份目录只保留公开接入者需要长期阅读的内容。内部路线图、研究笔记和历史 runbook 不属于公开文档面。
+
+## 推荐阅读顺序
+
+1. [包根 README](../README.md)
+   先看 linnkit 的定位、能力边界和 quickstart。
+2. [Integration Guide](./integration/README.md)
+   按主题接入 LLM、工具、上下文、持久化、RunSupervisor、AuditPort、Telemetry 和测试。
+3. [Changelog](../CHANGELOG.md)
+   查看公开版本变化和兼容性说明。
+
+## 公开 API
+
+`package.json#exports` 锁定当前公开入口。任何没有出现在 exports 里的 deep import 都不稳定。
+
+| 子入口 | 用途 | 环境 |
+|---|---|---|
+| `@linnlabs/linnkit` | 根入口，常用 namespace 与 helper | Node-only |
+| `@linnlabs/linnkit/ports` | host 需要实现的接口 | Node-only |
+| `@linnlabs/linnkit/contracts` | 消息、事件、SSE 等稳定合同 | Node-only |
+| `@linnlabs/linnkit/runtime-kernel` | graph、tool、run、llm 等 runtime 能力 | Node-only |
+| `@linnlabs/linnkit/runtime-kernel/events` | 浏览器安全的事件治理函数 | Browser-safe |
+| `@linnlabs/linnkit/context-manager` | context pipeline、fence、profile 能力 | Node-only |
+| `@linnlabs/linnkit/testkit` | 测试夹具与协议不变量 | Test-only |
+| `@linnlabs/linnkit/quickstart` | `defineAgent` / `runAgent` / `defineConfig` demo helper | Node-only |
+
+## 分层边界
+
+| 层 | linnkit 负责 | host 负责 |
+|---|---|---|
+| runtime-kernel | graph loop、tool runtime、run lifecycle、事件治理 | 默认工具、SSE/WebSocket/IPC、业务执行策略 |
+| context-manager | 上下文窗口构建、预算裁剪、fence、摘要、checkpoint、trace | 业务上下文注入、must-keep 策略、provider registry 配置 |
+| ports | 稳定接入接口 | 具体 LLM、存储、tokenizer、telemetry、audit 实现 |
+| testkit | 通用 fixture、harness、不变量校验 | host-bound harness 与生产装配回归 |
+
+## 关键约束
+
+1. 生产代码不要 import `@linnlabs/linnkit/testkit`。
+2. 浏览器代码不要 import `@linnlabs/linnkit/runtime-kernel`，只用 `@linnlabs/linnkit/runtime-kernel/events` 或按需使用 contracts。
+3. 不要 deep import。公开入口以 `package.json#exports` 为准。
+4. 不要把 provider/tool/adapter 写回 linnkit。它们应该留在 host 仓库，通过 ports 和 registry 接入。
+5. 业务上下文走 fence 机制注册，linnkit 不硬编码任何产品词汇。
+
+## 文档地图
+
+### 起步
+
+- [installation](./integration/01-installation.md)
+- [quickstart](./integration/02-quickstart.md)
+- [constraints and pitfalls](./integration/constraints-and-pitfalls.md)
+- [glossary](./integration/glossary.md)
+
+### 接入主题
+
+- [LLM provider](./integration/llm-provider.md)
+- [tools](./integration/tools.md)
+- [tool development guide](./integration/tool-development-guide.md)
+- [agent registration](./integration/agent-registration-guide.md)
+- [context engineering](./integration/context-engineering.md)
+- [context fences](./integration/context-fences.md)
+- [tool history](./integration/tool-history.md)
+- [persistence](./integration/persistence.md)
+- [run supervisor](./integration/run-supervisor.md)
+- [child runs](./integration/child-runs.md)
+- [audit](./integration/audit.md)
+- [telemetry](./integration/telemetry.md)
+- [realtime](./integration/realtime.md)
+- [testing](./integration/testing.md)
+
+## 维护说明
+
+公开文档只写长期稳定的接入事实。一次性升级计划、内部取舍、调研笔记和发布 runbook 不放进公开仓；公开版本变化统一写到仓根 `CHANGELOG.md`。

package/docs/integration/01-installation.md

@@ -0,0 +1,94 @@
+# Installation · 装包
+
+> **What** · 把 `@linnlabs/linnkit` 装到自己仓库 + 跑通装包 smoke。
+> **When to read** · 第一次接入 linnkit；新加 CI 环境；遇到 `Missing tiktoken_bg.wasm` 类装包错误想排查。
+> **Prerequisites** · 无（这是接入第 1 篇）。
+> **Key exports** · 无（本文不涉及 import）。
+> **Related** · [`02-quickstart.md`](./02-quickstart.md) · [`constraints-and-pitfalls.md`](./constraints-and-pitfalls.md)
+
+## 1. 这个包发布在哪
+
+`@linnlabs/linnkit` 发布到 **npmjs.com 公开 registry**（`https://registry.npmjs.org/`），scope 是 `@linnlabs`。正常 npm 项目不需要额外 `.npmrc`。
+
+如果你以前接过 GitHub Packages 私有版本，请删除项目 `.npmrc` 里的旧配置：
+
+```ini
+@linnlabs:registry=https://npm.pkg.github.com/
+```
+
+这条旧 registry override 会让 npm 继续去 GitHub Packages 找包，公开版本反而装不到。
+
+## 2. 安装
+
+```bash
+npm install @linnlabs/linnkit
+```
+
+如果你只想先跑 quickstart，也可以全局安装 CLI：
+
+```bash
+npm install -g @linnlabs/linnkit
+linnkit init hello-linnkit
+```
+
+CLI v0 只包含三个命令：
+
+| 命令 | 用途 |
+|---|---|
+| `linnkit init <name>` | 生成一个自包含 demo host（JS ESM + OpenAI-compatible fetch adapter + memory runtime） |
+| `linnkit doctor [--config linnkit.config.mjs]` | 检查 Node / npm registry 配置 / env / config / LLM adapter 形状 |
+| `linnkit run <agent-id> --input "..." [--model "..."]` | 运行 quickstart config 里的 agent，打印 final answer 和 cost 摘要 |
+
+`replay` / `inspect` 不在 CLI v0 范围内。真要做生产级 replay / inspect，请接入自己的 EventStore / RunSupervisor，并按 [testing.md](./testing.md) 与 [run-supervisor.md](./run-supervisor.md) 做 host 侧工具。
+
+`peerDependencies`：
+
+| peer | 说明 |
+|---|---|
+| `zod` (`^3.22.0`) | 必需。`@linnlabs/linnkit/contracts` 用 zod 定义所有消息/事件 schema，运行时也会校验 |
+| `vitest` (`^2 \|\| ^3`) | 可选。**只有当你打算 import `@linnlabs/linnkit/testkit` 写测试时才需要装** |
+
+`@linnlabs/linnkit/testkit` 在源码顶层 `import { vi, expect } from 'vitest'`，所以生产代码 **绝对不能** import 这个子入口（详见 [constraints-and-pitfalls.md](./constraints-and-pitfalls.md)）。
+
+## 3. 验证装包成功
+
+新建一个 `smoke.ts`：
+
+```ts
+import { runtimeKernel, generateMessageId } from '@linnlabs/linnkit';
+import type { AgentInvocationRequest, AgentAiEngine } from '@linnlabs/linnkit/ports';
+import type { AiMessage, RuntimeEvent } from '@linnlabs/linnkit/contracts';
+
+console.log(generateMessageId());
+console.log(typeof runtimeKernel.graph);
+```
+
+`tsc --noEmit` 通过 + 运行无报错 = 装包成功。如果你在前端项目里这么写会拖进 `node:async_hooks`，请先看 [README.md §5 浏览器规则](./README.md#5-浏览器使用规则硬约束)。
+
+如果想验证 CLI：
+
+```bash
+npx linnkit --help
+```
+
+---
+
+## 常见装包问题（FAQ）
+
+**Q：我装的是 `@linnlabs/linnkit`，但 npm/yarn 报 401 / 404？**
+
+优先检查项目或用户级 `.npmrc` 是否还把 `@linnlabs` 指到了旧的 GitHub Packages：
+
+```bash
+npm config get @linnlabs:registry
+```
+
+如果输出是 `https://npm.pkg.github.com/`，请删掉这条配置，让 npm 回到默认的 `https://registry.npmjs.org/`。
+
+**Q：我能不能 fork linnkit、改它内部然后用我自己的 fork？**
+
+技术上可以，但你要自己负担"和上游同步 + boundary guard 自维护"的成本。99% 你想做的事都能通过依赖注入在 host 层完成；如果你发现某个改动只能 fork 才能做，那大概率说明你应该来跟 linnkit 维护方提 issue / PR。
+
+**Q：import `@linnlabs/linnkit/runtime-kernel` 报 "Missing tiktoken_bg.wasm"？**
+
+确认你装的版本 ≥ `0.1.3`。0.1.0~0.1.2 三个版本里 tiktoken wasm 被错误 inline 进 dist，已在 0.1.3 修复（external + 在 `dependencies` 声明）。