@linnlabs/linnkit 0.8.0

package/docs/integration/02-quickstart.md

@@ -0,0 +1,104 @@
+# Quickstart · 5 分钟跑通 hello agent
+
+> **What** · 用 `defineAgent` + `runAgent` 写 hello agent 最小骨架，5 分钟跑通一轮对话。
+> **When to read** · 装包成功后立刻读；想试用 quickstart helper；写第一个 demo。
+> **Prerequisites** · [`01-installation.md`](./01-installation.md)（装包鉴权已通过）。
+> **Key exports** · `defineAgent` / `runAgent` / `defineConfig` from `@linnlabs/linnkit/quickstart`。
+> **Related** · [`tool-development-guide.md`](./tool-development-guide.md) ⭐ · [`agent-registration-guide.md`](./agent-registration-guide.md) ⭐ · [`llm-provider.md`](./llm-provider.md)
+
+本页是 **试用入口**：目标是让你装包后立刻跑通一轮 agent 对话，确认包、配置、LLM adapter 和 graph runtime 能正常工作。
+
+它不是生产接入方案。生产 host 仍然应该按后续主题手册逐项替换 LLM provider、工具系统、持久化、实时通道、审计和上下文工程策略：
+
+- [llm-provider.md](./llm-provider.md)
+- [tools.md](./tools.md)
+- [context-fences.md](./context-fences.md)
+- [persistence.md](./persistence.md)
+- [run-supervisor.md](./run-supervisor.md)
+- [audit.md](./audit.md)
+- [testing.md](./testing.md)
+
+## 1. 创建 demo host
+
+```bash
+npm install -g @linnlabs/linnkit
+linnkit init hello-linnkit
+cd hello-linnkit
+cp .env.example .env
+npm install
+```
+
+`linnkit init <name>` 会在**当前执行命令的目录**下创建一个同名子目录。例如你在 `/Users/you/projects` 执行 `linnkit init hello-linnkit`，最终路径就是 `/Users/you/projects/hello-linnkit`。如果目标目录已存在且非空，CLI 会直接报错，不会覆盖你的文件。
+
+如果你不想全局安装，也可以在任意已安装 `@linnlabs/linnkit` 的项目里用：
+
+```bash
+npx linnkit init hello-linnkit
+```
+
+## 2. 配置 LLM
+
+编辑 `.env`：
+
+```bash
+OPENAI_API_KEY=sk-...
+OPENAI_BASE_URL=https://api.openai.com/v1
+OPENAI_MODEL=gpt-4.1-mini
+```
+
+quickstart 模板不依赖 OpenAI SDK，只用 Node 20 原生 `fetch` 调 OpenAI-compatible Chat Completions streaming API。你也可以把 `OPENAI_BASE_URL` 指向任何兼容服务。
+
+## 3. 检查环境
+
+```bash
+npx linnkit doctor
+```
+
+`doctor` 会检查：
+
+- Node.js >= 20
+- npm registry 配置（如果检测到旧 GitHub Packages registry override，会提示删除）
+- `OPENAI_API_KEY`
+- `linnkit.config.mjs` 能加载
+- agent id 唯一
+- LLM adapter 是否符合 `AgentAiEngine` 形状
+
+## 4. 跑 hello agent
+
+```bash
+npx linnkit run hello --input "你好，介绍一下你自己"
+```
+
+你会看到实时 final answer chunk，结束后会打印：
+
+```text
+[linnkit] runId=...
+[linnkit] tokens input=... output=...
+```
+
+## 6. 生成项目里有什么
+
+```text
+hello-linnkit/
+├── agents/hello.mjs
+├── adapters/openai-compatible.mjs
+├── linnkit.config.mjs
+├── .env.example
+└── package.json
+```
+
+关键点：
+
+- `agents/hello.mjs` 用 `defineAgent()` 声明一个无工具 agent。
+- `linnkit.config.mjs` 用 `defineConfig()` 声明 agent 列表、默认模型和 LLM adapter。
+- `adapters/openai-compatible.mjs` 是 demo adapter，只证明 `AgentAiEngine` 怎么接；生产接入建议维护自己的 provider adapter。
+- `linnkit run` 内部用 `runAgent()` 自动装配内存版 EventStore / Checkpointer / RunSupervisor，只适合 quickstart 和小型 smoke test。
+
+## 7. 下一步
+
+- 接你自己的 provider：看 [llm-provider.md](./llm-provider.md)
+- 注册工具：看 [tools.md](./tools.md)
+- 精细控制上下文 token：看 [context-fences.md](./context-fences.md)、[tool-history.md](./tool-history.md)
+- 接持久化和恢复：看 [persistence.md](./persistence.md)
+- 接 run 管理：看 [run-supervisor.md](./run-supervisor.md)
+- 写集成测试：看 [testing.md](./testing.md)

package/docs/integration/README.md

@@ -0,0 +1,223 @@
+# `@linnlabs/linnkit` Integration Guide
+
+这是 `@linnlabs/linnkit` 的**接入文档集**——回答一件事：
+
+> 你在自己的仓库装了 `@linnlabs/linnkit`，要把一个 Agent 跑起来，至少要写什么、应该从哪里开始抄。
+
+**读者画像**：在外部独立仓库（如 daemon、桌面应用、Web 服务、知识库 agent 或任意自研 agent host）通过 `npm install @linnlabs/linnkit` 装包，准备从零接入的开发者。
+
+---
+
+## 1. 它是什么
+
+`@linnlabs/linnkit` 是 **vendor-neutral 的 Agent 框架**：它只提供 runtime kernel + context manager + ports + testkit，**不内置任何具体业务实现**。
+
+一句大白话：
+
+> 你装的这个包负责"agent 怎么跑、上下文怎么治理"，不负责"用哪个 LLM 提供商、工具集长什么样、消息怎么落库、SSE 怎么推、产品里有哪些 agent"。这些通通是你（host）要自己写的。
+
+## 2. 你必须自己写的（接入面）
+
+按重要度排序：
+
+
+| 你必须自己写的                                 | linnkit 给的接入合同（type/symbol）                                                                             | 从哪里 import                          |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| 1. LLM provider 适配器                     | `AgentAiEngine`                                                                                         | `@linnlabs/linnkit/ports`           |
+| 2. 工具集                                  | `BaseTool` / `ToolRuntimePort`                                                                          | `@linnlabs/linnkit/runtime-kernel`  |
+| 3. 上下文围栏（fence）注册 + 注入适配                | `FenceRegistry` / `FenceDescriptor` / `FenceInjection` / `MustKeepPolicy` / `FenceLifetimePreprocessor` | `@linnlabs/linnkit/context-manager` |
+| 4. 持久化适配器                               | `Checkpointer` / `EventStore` / `RunRegistryStore`                                                      | `@linnlabs/linnkit/runtime-kernel`  |
+| 5. 实时通道（SSE/WebSocket/MQTT）             | linnkit 不规定接口；从 `RuntimeEvent` 自己映射                                                                     | `@linnlabs/linnkit/contracts`       |
+| 6. graph executor 装配 + 默认 LLM/Tool node | `runtimeKernel.graph.GraphExecutor` 等                                                                   | `@linnlabs/linnkit/runtime-kernel`  |
+| 7. agent / chat / task 注册表              | `promptKey` 是 opaque string，linnkit 不认识你的产品菜单                                                           | （host 自定义）                          |
+| 8.（可选）telemetry                         | `TelemetryPort`                                                                                         | `@linnlabs/linnkit/runtime-kernel`  |
+
+
+## 3. 推荐目录形态（host 仓库内）
+
+```text
+app-hosts/<your-app>/
+├── adapters/
+│   ├── runtime-assembly/   # 把 GraphExecutor / LlmNode / ToolRuntime 拼起来
+│   ├── context-injection/  # context builder + 注入 host 请求字段为 fences
+│   ├── flow/               # history 读取 / pre-run policy / host session
+│   ├── realtime/           # SSE / WebSocket / MQTT
+│   ├── persistence/        # Checkpointer / EventStore / RunRegistryStore 实现
+│   └── tools/              # 默认 ToolManager 装配
+├── agent-registry/         # 你的 agent / chat / system 定义
+├── context/
+│   ├── agent/              # host invoke request shape + fence 注册 + injection adapter
+│   └── chat/               # （只在你还要兼容 chat 时需要）
+├── context-policies/       # MustKeepPolicy / provider registry / 截断比例
+└── testkit/                # host-bound harness（依赖你的默认 adapter）
+```
+
+这是建议而不是强制。下面的术语全部按这个分层取名。
+
+## 4. 公开 API surface（8 个稳定子入口）
+
+`package.json#exports` 写死的子入口当前是 8 个。任何不在这张表里的"deep import"（比如 `@linnlabs/linnkit/context-manager/shared/preprocessors/...` 或 `@linnlabs/linnkit/shared/...`）都不算公开 API，下个 minor 升级随时可能挪。
+
+
+| 子入口                                       | 适用环境                                           | 你能从这里 import 到什么                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| ----------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@linnlabs/linnkit`                       | **Node-only**                                  | `runtimeKernel` / `ports` / `contracts` 三个 namespace；`generateMessageId` / `generateRunId` / `withLLMTelemetryContext` / `setLlmAuditRecorder`                                                                                                                                                                                                                                                                                                                   |
+| `@linnlabs/linnkit/ports`                 | **Node-only**                                  | `AgentInvocationRequest` / `AgentAiEngine` / `AgentAiEngineStreamContent` / `LlmCallOptions` / `LlmRequestMessage` / `ToolCall` / `TokenizerPort` 等 host 必须实现的合同                                                                                                                                                                                                                                                                                                 |
+| `@linnlabs/linnkit/contracts`             | **Node-only**                                  | 长期稳定的合同：`AiMessage` / `SystemMessage` / `UserMessage` / `AssistantMessage` / `ToolMessage` / `RuntimeEvent` / `EventEnvelope` / `SSEEvent` / 默认执行常量                                                                                                                                                                                                                                                                                                              |
+| `@linnlabs/linnkit/runtime-kernel`        | **Node-only**（含 `node:async_hooks` / `crypto`） | 全套 runtime：`graph` / `tools` / `execution` / `events` / `runContext` / `llm` / `childRuns` / `childRunTrace` / `runSupervisor` / `telemetry` 等 namespace + 扁平 `BaseTool` / `ToolExecutionContext` / `ENGINE_ERROR_CODES` 等符号 + `createGraphLoopHarness` / `createDefaultGraphExecutor`（仅测试用）                                                                                                                                                                     |
+| `@linnlabs/linnkit/runtime-kernel/events` | **浏览器安全**                                      | events governance 纯函数：`shouldPersistRuntimeEvent` / `shouldEnterAgentContext` / `shouldEmitRuntimeEventToSse` / `shouldReplayRuntimeEventToUi` / `getRuntimeEventUiProjectionKind` / `eventMapper`，外加 `AnyAgentEvent` / `RuntimeEventLifecycleDecision` 类型                                                                                                                                                                                                       |
+| `@linnlabs/linnkit/context-manager`       | **Node-only**                                  | context core：`createMessageFormatter` / `formatAgentLlmMessages` / `messageFormatter` / `createFenceRegistry` / `FenceDescriptor` / `FenceInjection` / `FenceRegistry` / `FenceLifetimePreprocessor` / `MustKeepPolicy` / `DEFAULT_MUST_KEEP_POLICY` / `BaseContextProvider` / `AGENT_CONSTANTS` / agent profile namespace。chat 兼容层只剩下少量扁平导出（`ChatMessageOrchestrator` / `BaseConversationalTask` / `chatMessageToAiMessage` 等），新接入方应只用 agent profile + fence 机制 |
+| `@linnlabs/linnkit/testkit`               | **测试专用**                                       | scripted AI engine harness、graph loop harness、tool context fixture、replay harness、断言、`createRunSupervisorHarness` / `createCollectingAuditPort` / `createMockTelemetryPort` / `createMockTokenizerPort` / 15 条 run 不变量 + 12 条 context policy 不变量校验。`AGENT-GUARD-10-no-testkit-in-production` 强制守门——生产代码不能 import                                                                                                                                                 |
+| `@linnlabs/linnkit/quickstart`            | **试用 / demo**                                  | `defineAgent` / `runAgent` / `defineConfig`，用于 5 分钟跑通 hello agent；生产 host 接入仍按本目录主题手册逐项装配                                                                                                                                                                                                                                                                                                                                                                        |
+
+
+## 5. 浏览器使用规则（硬约束）
+
+**前端代码（renderer / browser bundle）禁止 import `@linnlabs/linnkit/runtime-kernel`**——这条入口是 namespace 全展开，会把 `node:async_hooks` / `crypto` 等 Node-only 子树拖进 frontend bundle。
+
+前端如果只是要做事件展示决策（"这条 RuntimeEvent 该不该回放给 UI？"），从 `**@linnlabs/linnkit/runtime-kernel/events**` 这个 slim seam 取纯函数：
+
+```ts
+// renderer/src/agentEventPolicy.ts
+import {
+  shouldReplayRuntimeEventToUi,
+  getRuntimeEventUiProjectionKind,
+} from '@linnlabs/linnkit/runtime-kernel/events';
+import type { RuntimeEvent } from '@linnlabs/linnkit/contracts';
+```
+
+`@linnlabs/linnkit/contracts` 是纯 zod schema + 类型，技术上前端也可 import；但 zod 体积非零，前端按需。
+
+## 6. import 选择决策
+
+```text
+要决定一条 import 应该走哪个子入口？
+├── 我在前端 bundle 里？
+│   └── 是 ──▶ 只能是 /runtime-kernel/events 或 /contracts
+├── 我在测试代码里？
+│   └── 是 ──▶ 可以 /testkit；其它子入口照常用
+├── 我要类型/合同？
+│   └── 是 ──▶ /ports（host 实现合同）或 /contracts（消息/事件合同）
+├── 我要 context 和 fence 机制？
+│   └── 是 ──▶ /context-manager
+└── 其它（runtime 装配、graph、tool runtime、LLM caller 骨架）─▶ /runtime-kernel
+```
+
+不要 `import { something } from '@linnlabs/linnkit/runtime-kernel/<deep>'`。`exports` 字段没声明的路径在 Node 16+ ESM 解析下会直接报错，且任何 deep path 都不在稳定 API 范围。
+
+---
+
+## 7. 文档索引
+
+### 7.1 起步必读（按顺序）
+
+
+| #   | 文档                                         | 内容                                   |
+| --- | ------------------------------------------ | ------------------------------------ |
+| 1   | 本文 §1-§6                                   | 它是什么 / 你要写什么 / 8 个公开 API 子入口 / 浏览器规则 |
+| 2   | [01-installation.md](./01-installation.md) | 装包 / `.npmrc` 鉴权 / 验证                |
+| 3   | [02-quickstart.md](./02-quickstart.md)     | 5 分钟最小 host 骨架                       |
+
+
+### 7.2 单点接入（按你需要的功能查）
+
+
+| 主题                                                                                    | 文档                                                                                                                          |
+| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| 接 LLM provider（OpenAI / Anthropic / DeepSeek / OpenRouter）                            | [llm-provider.md](./llm-provider.md)                                                                                        |
+| 工具集接入面（`ToolRuntimePort` / `ObservationPreviewPort`）                                  | [tools.md](./tools.md)                                                                                                      |
+| **工具开发规范**（`BaseTool` 设计哲学 / `data`-`observation` 分层 / 错误处理 / `getExecutionSummary`）⭐ | [tool-development-guide.md](./tool-development-guide.md)                                                                    |
+| **Agent 注册与装配**（`AgentSpec` 静态蓝图 / `defineAgent` quickstart helper / 多 agent 协作）⭐     | [agent-registration-guide.md](./agent-registration-guide.md)                                                                |
+| **上下文工程总览**（所有作用在 messages 上的机制 + `contextPolicy` / `ContextTrace` 可观测闭环）⭐            | [context-engineering.md](./context-engineering.md)                                                                          |
+| **接 context engineering（fence 注册 + 注入）⭐ 一等接入面**                                       | [context-fences.md](./context-fences.md)                                                                                    |
+| 自定义 token 估算（`TokenizerPort` 替换默认 tokenizer · 0.8.0+）                                 | [context-engineering.md §9.4](./context-engineering.md) / [agent-registration-guide.md](./agent-registration-guide.md) §4.1 |
+| 配置工具历史压缩策略（per-pair / per-run / none）                                                 | [tool-history.md](./tool-history.md)                                                                                        |
+| 接持久化（Checkpointer / EventStore / RunRegistryStore）                                    | [persistence.md](./persistence.md)                                                                                          |
+| 接 RunSupervisor + RunHandle                                                           | [run-supervisor.md](./run-supervisor.md)                                                                                    |
+| 同步嵌入 vs 异步后台子 agent                                                                   | [child-runs.md](./child-runs.md)                                                                                            |
+| 接 AuditPort（决策账本）                                                                     | [audit.md](./audit.md)                                                                                                      |
+| 接 telemetry                                                                           | [telemetry.md](./telemetry.md)                                                                                              |
+| 实时通道（SSE / WebSocket / IPC）                                                           | [realtime.md](./realtime.md)                                                                                                |
+
+
+### 7.3 测试 / 边界 / 速查
+
+
+| 主题                                     | 文档                                                           |
+| -------------------------------------- | ------------------------------------------------------------ |
+| 测试与 testkit（两层架构）                      | [testing.md](./testing.md)                                   |
+| 硬约束 + 不建议做的事 + FAQ                     | [constraints-and-pitfalls.md](./constraints-and-pitfalls.md) |
+| 术语对照（Checkpoint / Event / Fence 的不同含义） | [glossary.md](./glossary.md)                                 |
+
+
+### 7.4 推荐阅读顺序
+
+**第一次接入（最少 30 分钟）**：
+
+1. 本文 §1-§6 → 先把"我装了啥、它给我啥"看清
+2. [01-installation.md](./01-installation.md) → 装包鉴权跑通 smoke
+3. [02-quickstart.md](./02-quickstart.md) → 写一个能跑的最小骨架
+4. [tool-development-guide.md](./tool-development-guide.md) ⭐ → **写工具**：`BaseTool` 设计哲学、`data` / `observation` 分层、错误处理协议
+5. [agent-registration-guide.md](./agent-registration-guide.md) ⭐ → **注册 Agent**：`AgentSpec` 静态蓝图 / `defineAgent` quickstart helper / 多 agent 协作
+6. [context-engineering.md](./context-engineering.md) ⭐ → **鸟瞰**：所有作用在 messages 上的机制是什么、如何声明 `contextPolicy`、如何用 `ContextTrace` 解释最终 token 决策
+7. [context-fences.md](./context-fences.md) ⭐ → **实操**：fence 注册与注入是 linnkit 一等接入面
+8. 按需读单点接入文档
+
+**续作（按需）**：
+
+- 写测试 → [testing.md](./testing.md)
+- 上线前 → [constraints-and-pitfalls.md](./constraints-and-pitfalls.md) + [glossary.md](./glossary.md)
+
+### 7.5 按问题查文档（FAQ-style · AI agent 友好）
+
+> 当 AI 助手 / 新接入者用自然语言提问时，这里把"我想……"映射到具体文档段落。每个条目精确到文件 + 段号，避免泛指。
+
+
+| 我想……                                                  | 看这个                                                                                                                                                            |
+| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ……装包跑通最小骨架                                            | [01-installation.md](./01-installation.md) → [02-quickstart.md](./02-quickstart.md)                                                                            |
+| ……换一个 LLM 模型 / 接 OpenAI / Anthropic / DeepSeek        | [llm-provider.md](./llm-provider.md)                                                                                                                           |
+| ……写一个自定义工具（怎么定义 `data` / `observation` / 错误处理）        | [tool-development-guide.md](./tool-development-guide.md) ⭐                                                                                                     |
+| ……把工具注册到 agent 上                                      | [tools.md](./tools.md) + [agent-registration-guide.md §2](./agent-registration-guide.md) ⭐                                                                     |
+| ……让工具产生的超长 observation 不占满上下文                         | [tools.md §5](./tools.md)（`ObservationPreviewPort`）+ [context-engineering.md §6](./context-engineering.md)                                                     |
+| ……定义一个新 agent / 写 `AgentSpec`                         | [agent-registration-guide.md](./agent-registration-guide.md) ⭐                                                                                                 |
+| ……配 token 预算 / 控制每个 token                             | [agent-registration-guide.md](./agent-registration-guide.md) §4.1（`contextPolicy.budget` / 默认 tokenizer）+ [context-engineering.md](./context-engineering.md) ⭐ |
+| ……用真实的 Claude / Gemini tokenizer 替代默认                 | [context-engineering.md §9.4](./context-engineering.md)（`TokenizerPort`）+ [agent-registration-guide.md](./agent-registration-guide.md) §4.1                    |
+| ……被动摘要：先注册摘要 agent、再填 `summarization.agentId`         | [agent-registration-guide.md](./agent-registration-guide.md) §4.2 + [context-engineering.md](./context-engineering.md) §5.4                                    |
+| ……把 host 的"当前文件 / 项目状态 / 引用段落"喂给 agent                | [context-fences.md](./context-fences.md) ⭐                                                                                                                     |
+| ……让关键信息（如 user prefs）永远不被裁掉                           | [context-fences.md](./context-fences.md) ⭐（`mustKeep` policy）                                                                                                  |
+| ……工具调用反复占满上下文要压缩                                      | [tool-history.md](./tool-history.md)（`per-pair` / `per-run` / `none`）                                                                                          |
+| ……配 fence 生命周期（current-turn / persisted / boot-only）  | [context-fences.md §3](./context-fences.md) ⭐                                                                                                                  |
+| ……让 run 跨进程崩溃后恢复                                      | [persistence.md](./persistence.md) + [run-supervisor.md](./run-supervisor.md)（`recoverOnBoot`）                                                                 |
+| ……让用户能取消正在跑的 agent                                    | [run-supervisor.md](./run-supervisor.md)（`RunHandle.cancel`）                                                                                                   |
+| ……agent 里调另一个 agent / 多 agent 协作                      | [child-runs.md](./child-runs.md) + [agent-registration-guide.md](./agent-registration-guide.md) §8 ⭐                                                           |
+| ……做后台异步长任务 / spawn detached run                       | [child-runs.md §2](./child-runs.md)（`spawnDetached`）                                                                                                           |
+| ……把 agent 进度推到前端 / SSE / WebSocket / Electron IPC     | [realtime.md](./realtime.md)                                                                                                                                   |
+| ……前端 import linnkit 报错（`node:async_hooks` / `crypto`） | [README §5](./README.md)（browser rules）+ [realtime.md](./realtime.md)                                                                                          |
+| ……监控 token usage / 时延 / 接 Datadog / Otel              | [telemetry.md](./telemetry.md)                                                                                                                                 |
+| ……做合规审计 / 追溯"agent 为什么这么做"                            | [audit.md](./audit.md)                                                                                                                                         |
+| ……写第一个 agent 单测 / mock LLM                            | [testing.md](./testing.md)                                                                                                                                     |
+| ……mock 自定义 tokenizer 验证 budget                        | [testing.md](./testing.md) + [context-engineering.md §9.4.6](./context-engineering.md)（`createMockTokenizerPort`）                                              |
+| ……review 别人的接入是否符合 linnkit 边界                         | [constraints-and-pitfalls.md](./constraints-and-pitfalls.md) + [glossary.md](./glossary.md)                                                                    |
+| ……同事说"Checkpoint" / "Fence" / "Run" 我搞混了              | [glossary.md](./glossary.md)                                                                                                                                   |
+
+
+> **找不到匹配的问题？** 优先查 [context-engineering.md](./context-engineering.md) ⭐（上下文工程总览） / [agent-registration-guide.md](./agent-registration-guide.md) ⭐（agent 配置入口）；仍找不到，是真正的"linnkit 不直接做"——见 [constraints-and-pitfalls.md](./constraints-and-pitfalls.md) §2。
+
+---
+
+## 8. 当前版本与稳定性
+
+- 当前版本：以 `package.json#version` 为准
+- 0.x = pre-release 期：**任何加 export / 改既有签名都 bump minor**，patch 兼容
+- 8 个稳定子入口已在 `package.json#exports` 锁定；任何 deep import 都不在稳定面
+- 公开版本变化见仓根 `CHANGELOG.md`
+
+---
+
+## 9. 与其他文档的关系
+
+- **包根 [README.md](../../README.md)**：包级总览
+- **[docs/README.md](../README.md)**：框架总览（运行时分层、数据流、术语速查）
+- **[CHANGELOG.md](../../CHANGELOG.md)**：公开版本更新记录
+- **本目录**：接入手册（你正在读的）