@aliyun-es/agentic-context 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,408 @@
-# Temporary Holding Version
+# Agent 接入阿里云 Elasticsearch 企业上下文引擎 (Agentic Context) 指南
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+将阿里云 Elasticsearch 企业上下文引擎接入 Agent，可赋予 Agent 强大的云上 agent memory, skill, knowledge base, agentic wiki 等核心能力。现已支持 Codex、OpenClaw、Hermes、Claude Code 和 Qoder 等主流 Agent。
+
+本文的安装、验证和升级命令固定使用 `@aliyun-es/agentic-context@0.2.0`。新 npm 包采用独立版本序列，从 `0.1.0` 开始；此前由 `@aliyun-es/eke@0.1.1` 创建的受管理安装仍可按下文升级。
+
+## 前置条件：在阿里云开通 Elasticsearch 企业上下文引擎
+
+登录 [阿里云 Elasticsearch 控制台](https://elasticsearch.console.aliyun.com/)，按需购买并进入 Elasticsearch 实例详情页，然后授权并初始化企业上下文引擎即可。
+
+## 接入指南：安装并接入插件
+
+收到用户的接入请求后，执行以下步骤，完成环境检查、安装、启用和验证。能够通过工具完成的操作直接执行；仅在缺少必要信息、需要用户授权或操作超出当前工具能力时，请用户完成具体步骤。
+
+### 1. 确认目标 Agent 和接入参数
+
+根据用户请求确认目标 Agent，并读取用户提供的接入参数。缺少接入信息时先询问用户，不猜测服务地址、用户 ID 或凭证。
+
+| 目标 Agent | 命令中的 `<agent>` | 必须具备的能力 |
+| --- | --- | --- |
+| OpenClaw | `openclaw` | 本地插件安装和 `mcp.servers` 配置 |
+| Hermes | `hermes` | 支持 `MemoryProvider` 和 `spawn_context_thread` 的 Python 环境 |
+| Codex | `codex` | `codex plugin add` 命令，且允许插件 hooks |
+| Claude Code | `claude-code` | `claude plugin` 命令，且允许插件 hooks |
+| Qoder 桌面版（New Qoder）、Qoder CLI、Qoder IDE | `qoder` | 一次安装，分别配置 MCP 入口，共用生命周期 Hooks、Skill 和 Agentic Context 连接 |
+
+#### 首次安装必填参数
+
+已有受管理安装可省略以下参数，安装器复用原连接配置；显式传入的字段覆盖原值。
+
+| 参数 | 首次安装必填 | 取值 |
+| --- | --- | --- |
+| `--endpoint` | 是 | 企业上下文引擎数据访问服务的基础地址，例如 `https://<服务域名>`。不是 ES 地址或管控 API 地址，不附加 `/v1/...` 等路径 |
+| `--workspace` | 是 | 已开通的 workspace 名称，不是 workspace ID |
+| `--user_id` | 是 | 代表当前业务用户的稳定 ID，由业务系统或负责人确定；使用不含空格的 ASCII 字符，最长 256 字符；不要用 Agent 名称代替，也不要每次安装随机生成 |
+| `--api_key` | 是 | 该服务的 API Key，不是 ES 密码、阿里云 AK/SK 或 npm Token |
+
+#### 常用可选参数
+
+以下参数用于 `install` 命令。首次安装使用下表默认值；更新已有安装时，省略参数会保留原设置。
+
+| 参数 | 首次安装默认设置 | 说明 |
+| --- | --- | --- |
+| `--kb <知识库名称>` | 不指定默认知识库 | 可重复指定；显式传入时替换为本次完整列表。API 中的 `kb_id` 就是知识库名称 |
+| `--clear-kbs` | 不清空已有列表 | 显式清空默认知识库；与 `--kb` 互斥 |
+| `--auto-capture` | 自动采集开启 | 显式开启 Memory 自动采集，通常无需填写 |
+| `--no-auto-capture` | 不传时自动采集开启 | 关闭 Memory 自动采集；与 `--auto-capture` 互斥 |
+| `--auto-skill` | 自动提取关闭 | 开启自动 Skill 提取，仅 OpenClaw 支持；会上传相关新对话 |
+| `--no-auto-skill` | 不传时自动提取关闭 | 显式关闭自动 Skill 提取；与 `--auto-skill` 互斥 |
+| `--replace-memory-provider` | 不替换其他 Provider | 允许替换 Hermes 已有的 Memory Provider，仅在确认替换时使用 |
+| `--accept-capabilities` | 不自动授权 | 仅 OpenClaw；审查并同意 Agentic Context 的插件能力后，将授权传给支持该参数的宿主版本 |
+
+#### 环境与排障参数
+
+常规安装无需填写这些参数。
+
+| 参数 | 适用命令 | 默认设置与用途 |
+| --- | --- | --- |
+| `--config-dir <目录>` | `install`、`status`、`uninstall` | 默认按宿主环境变量或默认位置定位；用于指定 Agent 配置根目录，不是 `.agentic-context` 子目录。后续操作使用同一目录 |
+| `--agent-bin <程序路径>` | `install`、`uninstall` | 安装时默认自动查找宿主程序，卸载时优先使用安装记录中的路径；仅在自定义位置或程序路径变化时指定。Hermes、Qoder 不需要 |
+| `--skip-check` | `install` | 默认检查服务连接；传入后跳过安装前的 MCP 连接与工具列表检查，不代表服务可用 |
+| `--prepare` | `install` | 默认完成插件注册和配置；传入后只生成本地文件，不注册或启用插件。旧版安装升级不支持此选项。仍检查服务连接，除非同时传入 `--skip-check` |
+
+#### 状态检查与输出参数
+
+| 参数 | 适用命令 | 默认设置与用途 |
+| --- | --- | --- |
+| `--check` | `status` | 默认只检查本地配置；传入后额外检查 MCP 连接和工具列表，不执行业务调用 |
+| `--json` | `install`、`status`、`uninstall` | 默认输出带缩进的 JSON；传入后输出紧凑 JSON。警告和错误仍可能写入 stderr，须同时检查退出码 |
+| `--help` | 独立使用 | 显示命令帮助后退出，无需 Agent 名称或接入参数 |
+| `--version` | 独立使用 | 显示 Agentic Context 版本后退出，无需 Agent 名称或接入参数 |
+
+同一业务用户跨 Agent 共享 Memory 时，使用相同的 endpoint、workspace 和 `user_id`。不同用户不要共用同一个 `user_id`。`user_id` 和 `--kb` 不作为授权凭证；使用前需确认 API Key 具有对应的服务访问权限。
+
+**Memory 自动采集在首次安装时默认开启，更新时保留原设置**：插件生效后，会通过 MCP `memory_add` 将新的用户和助手对话文本提交到所配置的企业上下文引擎服务，不补传历史会话，不自动对正文做通用敏感信息脱敏。如需关闭，使用 `--no-auto-capture`。关闭自动采集不禁止 Agent 根据明确请求调用 Memory 写入工具。该安装配置面向单个业务用户，不能用一个固定 `user_id` 代表多用户应用中的所有人。
+
+**自动检索**：Hook 或 Provider 启用后，插件会将当前请求发送到 `hybrid_search`，将召回内容补充到 Agent 上下文。未配置 `--kb` 时仅检索 Memory 和 Skill；配置后同时检索指定知识库，支持多个知识库。检索失败不阻断任务。`--no-auto-capture` 只关闭自动采集，不关闭自动检索。
+
+新安装的 API Key 保存在 Agent 配置目录下的 `.agentic-context/connection.json` 和所需 MCP 配置中，OpenClaw/Hermes/Qoder 的安装记录也可能含凭证，应保护配置目录及其备份，勿共享给其他用户。以下文件路径以全新安装为例；旧安装升级沿用原状态目录，以安装结果和 `nextSteps` 中的实际路径为准。
+
+### 2. 检查并准备运行环境
+
+**在运行目标 Agent 的同一台机器、同一个操作系统账号和同一个环境中执行。** 远程 Agent 在服务器中安装，容器内的 Agent 在容器中安装，WSL 中的 Agent 在 WSL 中安装。不要通过切换为 root 或管理员账号来绕过安装问题，否则可能安装到错误的用户目录。
+
+先检查运行环境：
+
+```bash
+node --version
+npm --version
+node -p "JSON.stringify({platform:process.platform,arch:process.arch,node:process.execPath,home:require('node:os').homedir()})"
+```
+
+要求 **Node.js 22+**，且 npm/npx 可用。已有符合要求的环境直接复用；需要新装时可使用 [Node.js 24 LTS](https://nodejs.org/en/download)。安装器适配 macOS、Linux 和 Windows，但目标 Agent 自身也须支持对应系统。
+
+Windows 安装器不依赖 PowerShell。在 **命令提示符（cmd.exe）** 中将本文安装命令的 `npx` 写为 `npx.cmd`，其余参数保持一致；检查 npm 时使用 `npm.cmd --version`。从 `0.1.1` 起，Windows Codex 的三个本地插件 Hook 也直接通过宿主的 cmd 调用安装时定位的 Node.js，不再启动 PowerShell。
+
+#### Node.js 不存在、版本过低或终端找不到它
+
+先定位已有程序，避免重复安装：macOS/Linux 执行 `command -v node npm npx`，Windows 命令提示符执行 `where node`、`where npm.cmd`、`where npx.cmd`。如果程序已安装但未进入 PATH，将已确认的安装目录加入**当前终端**的 PATH，再检查版本。
+
+按当前环境选择一种处理方式，不同时安装多套 Node.js：
+
+| 当前环境 | 处理方式 |
+| --- | --- |
+| 已使用 nvm | 在当前 shell 加载已有 nvm，执行 `nvm install 24`、`nvm use 24`，不修改其他项目的默认版本 |
+| macOS 已安装 Homebrew | 执行 `brew install node@24`，然后执行 `export PATH="$(brew --prefix node@24)/bin:$PATH"`。已安装时只需设置 PATH；[该包为 keg-only](https://formulae.brew.sh/formula/node@24) |
+| Linux/macOS，没有可用的 Node.js 或版本管理器 | 使用下方 nvm 步骤在当前用户下安装，不覆盖系统 Node.js |
+| 原生 Windows，已安装 winget | 执行 `winget install --id OpenJS.NodeJS.LTS --exact --source winget`；若已有旧版，使用 `winget upgrade --id OpenJS.NodeJS.LTS --exact --source winget`，然后重新打开终端检查版本 |
+| 原生 Windows，没有 winget | 从 [Node.js 官方下载页](https://nodejs.org/en/download) 选择与系统架构一致的 LTS 安装包，完成安装后重开终端；按系统提示完成安装授权 |
+
+Linux/macOS 安装 nvm 的步骤如下，适用于 bash/zsh。先下载并检查官方脚本，再执行；已有 nvm 时跳过下载和安装。来源：[nvm 官方安装说明](https://github.com/nvm-sh/nvm#installing-and-updating)。
+
+```bash
+NVM_INSTALL_SCRIPT="$(mktemp)"
+curl --fail --show-error --location https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.7/install.sh --output "$NVM_INSTALL_SCRIPT"
+```
+
+确认下载成功、内容是官方安装脚本后执行：
+
+```bash
+bash "$NVM_INSTALL_SCRIPT"
+if [ -z "${NVM_DIR:-}" ]; then
+  if [ -n "${XDG_CONFIG_HOME:-}" ]; then
+    export NVM_DIR="$XDG_CONFIG_HOME/nvm"
+  else
+    export NVM_DIR="$HOME/.nvm"
+  fi
+fi
+. "$NVM_DIR/nvm.sh"
+nvm install 24
+nvm use 24
+node --version
+npm --version
+```
+
+安装 Node.js 或调整用户 shell 配置属于环境变更，应遵守当前环境的授权要求。下载或安装失败时不要继续运行后面的命令；记录失败步骤及错误，使用企业允许的软件源或由有权限的管理员完成安装。
+
+插件会记录安装时使用的 Node.js 可执行文件路径。不要使用会被清理的临时 Node.js；后续更换或删除该 Node.js 时，需要重新安装 Agentic Context。
+
+#### 目标 Agent 或配置目录未识别
+
+常规安装**不需要 `--agent-bin` 和 `--config-dir`**。安装器会查找 PATH、常用安装目录和受支持的宿主环境变量。先确认目标 Agent 能正常启动，再继续。
+
+遇到 `Could not find ...` 时，按下面顺序处理：
+
+1. 确认当前机器、账号、容器或 WSL 与目标 Agent 一致。环境不一致时，切换到正确环境重新执行，不复制另一账号的配置。
+2. 查找目标程序：macOS/Linux 使用 `command -v openclaw`、`command -v codex` 或 `command -v claude`；PowerShell 使用对应的 `Get-Command <程序名> -All`。Hermes、Qoder 通过配置目录接入，不需要 `--agent-bin`，也不要求额外安装 CLI。
+3. 非标准安装目录下已找到程序时，将其完整路径作为 `--agent-bin "<宿主程序完整路径>"` 传给安装器。确实未安装目标 Agent 时，先完成其官方安装。
+4. 需要指定已有自定义配置时，使用 `--config-dir "<Agent配置根目录>"`，不是 `.agentic-context` 子目录。安装、状态检查、卸载都使用同一个目录。
+
+PATH 中找不到时，继续检查 `npm prefix -g` 返回的目录：macOS/Linux 的可执行文件通常在其 `bin` 子目录，Windows 在该目录本身。macOS 的 Codex 桌面安装还可检查 `/Applications/Codex.app/Contents/Resources/codex` 和用户 `Applications` 下的相同路径。只使用实际存在的程序；桌面安装未提供 CLI 时，不能把应用图标路径当作 `--agent-bin`。
+
+配置目录遵循 Codex 的 `CODEX_HOME`、Claude Code 的 `CLAUDE_CONFIG_DIR`、Hermes 的 `HERMES_HOME`、Qoder 的 `QODER_CONFIG_DIR`，以及 OpenClaw 的 `OPENCLAW_HOME`、`OPENCLAW_PROFILE`、`OPENCLAW_STATE_DIR`、`OPENCLAW_CONFIG_PATH`。显式 `--config-dir` 优先。
+
+### 3. 执行安装
+
+将 `<agent>` 替换成上表中的一个名称，将其余占位符替换为真实接入信息，只执行这一条安装命令：
+
+```bash
+npx --yes @aliyun-es/agentic-context@0.2.0 install <agent> --endpoint "<服务地址>" --workspace "<workspace名称>" --user_id "<业务用户ID>" --api_key "<API Key>" --json
+```
+
+无需全局安装 npm 包。`--yes` 仅跳过 npx 下载包的确认，不跳过 Agent 的信任和工具授权。
+
+按需在命令末尾追加步骤 1 中的可选参数。例如，追加 `--kb "product_docs" --kb "team_handbook"` 指定两个默认知识库；追加 `--no-auto-capture` 关闭 Memory 自动采集。
+
+安装器会先连接服务并检查 MCP 工具列表，再注册插件和保存配置。这一步不调用业务工具、不写入测试 Memory。退出码为 `0` 且结果为 `CONFIGURED` 才表示配置完成；不能仅根据退出码判定后续验证通过。
+
+#### npm 下载或命令执行失败
+
+| 错误或现象 | 检查与修复 |
+| --- | --- |
+| PowerShell 提示禁止运行 `npm.ps1` 或 `npx.ps1` | 将命令中的 `npm`/`npx` 换成 `npm.cmd`/`npx.cmd`，其他参数不变，不关闭执行策略；企业明确禁止执行时交由管理员处理 |
+| 包找不到、E404 | 执行 `npm config get registry` 和 `npm config get @aliyun-es:registry`；若是镜像未同步且允许公共 npm，使用下方命令核对。公共 registry 仍 E404 时，确认包名、版本和访问限制 |
+| npm 缓存报 EACCES/EPERM | 使用下方独立缓存目录重试，不使用 `sudo npm`，不递归修改整个用户目录权限 |
+| ENOTFOUND、ETIMEDOUT、ECONNRESET | 确认失败的是 npm registry 还是企业上下文引擎域名；先执行 `npm ping` 检查当前 registry。企业要求代理时使用已批准的代理 |
+| TLS/证书错误 | 检查系统时间和证书链；企业代理证书必须通过企业批准的 CA 配置，不关闭证书验证，也不回退到 HTTP |
+| 宿主提示插件子命令或配置不支持 | 核对“确认目标 Agent 和接入参数”中的能力要求；使用该宿主的官方更新方式升级，再重新安装 Agentic Context |
+
+在允许直接访问公共 npm 的环境中，以下命令只检查包是否可下载，不带 API Key、不修改全局 registry：
+
+```bash
+npm view @aliyun-es/agentic-context version --registry=https://registry.npmjs.org --@aliyun-es:registry=https://registry.npmjs.org
+```
+
+成功后，可将这两个 registry 参数放在原 `npx` 命令的包名之前重试。`@aliyun-es` 的专用 registry 配置可能覆盖默认 registry，因此两者都要检查。
+
+缓存无写入权限时，在原 `npx` 命令的包名之前加入一个新缓存路径：macOS/Linux 使用 `--cache "$HOME/.cache/agentic-context-npm"`，Windows 命令提示符使用 `--cache "%LOCALAPPDATA%\agentic-context-npm-cache"`。如果错误发生在 Agent 配置目录而不是 npm 缓存，应修正当前账号和配置路径，不能靠换缓存解决。
+
+企业网络必须使用代理时，复用企业批准的 `HTTP_PROXY`、`HTTPS_PROXY` 和 `NO_PROXY`。对 Node.js 24 的服务请求，macOS/Linux 执行 `export NODE_USE_ENV_PROXY=1`，Windows 命令提示符执行 `set "NODE_USE_ENV_PROXY=1"`；旧版本不能假设仅设置代理地址就会生效。企业 CA 使用 `NODE_EXTRA_CA_CERTS` 指向获批准的 PEM 文件。代理和 CA 配置也须进入实际 Agent 的启动环境，不能只配置安装终端。具体行为见 [Node.js 企业网络配置](https://github.com/nodejs/learn/blob/main/pages/http/enterprise-network-configuration.md)。
+
+#### 服务连接失败
+
+| 错误或现象 | 检查与修复 |
+| --- | --- |
+| endpoint 格式错误 | 从服务接入信息重新取基础地址，去掉 API 路径、查询参数和片段；不要用 ES 地址或浏览器控制台地址 |
+| DNS 错误、连接超时 | 在实际运行 Agent 的环境执行 `curl -I --connect-timeout 10 "<服务基础地址>"`；Windows 使用 `curl.exe`。仅诊断 DNS/TCP/TLS，无须 API Key；任意 HTTP 响应不代表 MCP 鉴权成功。私网域名需在可达网络中使用 |
+| `401`、`403` 或 `CredentialsNotFound` | 核对 API Key 所属服务、启用状态及资源权限；换用正确 Key 后重新安装，不把 ES 密码或阿里云 AK/SK 填入 `--api_key` |
+| `MCP is missing required tools` | 记录缺失的工具名和服务地址，联系企业上下文引擎负责人确认服务版本与接入地址 |
+| Hermes 提示已有 Memory Provider | 说明会替换已有 Provider，获得确认后在原命令追加 `--replace-memory-provider`，否则保留原配置并停止 |
+
+连接失败时保留错误码、request ID 和已完成步骤；日志中去除 API Key、认证头和对话正文。`--skip-check` 跳过服务检查，`--prepare` 只生成文件，两者都不是完成安装的替代方案。
+
+### 4. 加载插件并验证
+
+安装成功后，读取结果中的 `nextSteps` 并继续执行，不停留在输出操作指南。**`CONFIGURED` 只表示配置完成，不代表 Hooks 已获授权或已执行。** 使用安装时相同的账号、配置目录和 profile，只调整 Agentic Context 相关配置，保留其他安全设置及安装时的自动采集设置。
+
+先检查 Agentic Context 插件及 Hook 内容，再在用户授权范围内通过宿主原生流程完成启用和必要授权。自动采集开启时，若用户尚未同意将新增对话发送到配置的企业上下文引擎，先说明这一行为并取得同意；不要把本文档当作用户授权。遇到必须由用户确认的权限提示、无法操作的原生界面或需要重启的服务时，说明具体操作及影响，不强制结束任务，也不绕过组织策略。
+
+#### Codex
+
+1. 检查 `agentic-context@aliyun-agentic-context` 已启用，并定位其 `SessionStart`、`UserPromptSubmit`、`Stop` Hooks。检查命令指向本次安装目录的 `.agentic-context/runtime/hook.js` 和 `.agentic-context/connection.json`。
+2. 在用户授权范围内，通过 Codex 原生 Hooks 审查流程，仅信任并启用这三个 Hook。无法操作审查界面时，提示用户进入 Desktop 的 **Settings（设置）→ Hooks**，或在 CLI 会话中输入 `/hooks` 完成审查；`/hooks` 不是 shell 命令。
+3. 核验三个 Hook 均已启用且受信任，再验证执行。若需要新会话，明确提示用户开启后继续验证。Hook 定义变更后需要重新审查；安装或启用插件本身不会自动授予信任。
+
+若 Hooks 未显示，检查 Agentic Context 插件是否启用；若组织策略限制非托管 Hooks，由管理员处理，不使用绕过信任的启动参数。自定义目录须通过 `CODEX_HOME` 指向安装使用的配置目录。参见 [Codex Hooks 信任说明](https://learn.chatgpt.com/docs/hooks#review-and-trust-hooks)。
+
+##### Windows 管理员策略阻止 Hook（错误 786）
+
+Windows 错误 `786 (0x312)` 对应 `ERROR_ACCESS_DISABLED_NO_SAFER_UI_BY_POLICY`，表示管理员策略限制访问。若报错指向 `powershell.exe -EncodedCommand`，只能确认该次启动被阻止；不能仅凭错误码判定是 PowerShell 整体被禁用，还是某条进程或命令规则拒绝了本次调用。参见 [Microsoft 系统错误码 500–999](https://learn.microsoft.com/en-us/windows/win32/debug/system-error-codes--500-999-)。
+
+`0.1.0` 的 Windows Codex Hook 会额外启动 PowerShell。`0.1.1` 已去除这一依赖，执行链为 **Codex → cmd.exe → 安装时定位的 node.exe → hook.js**；Node 使用绝对路径，不要求 Desktop 的 PATH 包含 Node。升级时在命令提示符执行 `npx.cmd --yes --registry=https://registry.npmjs.org @aliyun-es/agentic-context@0.2.0 install codex --json`，保留原账号、配置目录和安装参数；随后重新加载插件，按 Codex 提示审查这三个已修改的 Hook。若原来使用自定义配置目录，命令须继续传入同一 `--config-dir`。
+
+分别记录以下三层结果，不将前两层通过写成自动功能已验证：
+
+| 验证层 | 通过所需证据 |
+| --- | --- |
+| MCP 连接与工具调用 | Codex 实际发现并成功调用工具；这不依赖本地 Hook 成功启动 |
+| Codex Hook 审查 | `SessionStart`、`UserPromptSubmit`、`Stop` 已受信任且启用；这不代表 Windows 允许启动其进程 |
+| 宿主触发与业务结果 | 真实会话触发自动检索并注入上下文；自动采集还须在用户同意后，用无敏感测试对话确认提交、异步处理完成和结果可检索 |
+
+去掉插件主动启动的 PowerShell 不会修改管理员策略。若新版执行链中的 `cmd.exe` 或 `node.exe` 仍被组织策略限制，再由管理员按组织流程处理；保留完整启动错误、被阻止程序及规则，去除凭证和对话正文。不修改注册表、安全策略或使用 `ExecutionPolicy Bypass`。
+
+升级后仍需完成第三层验证。在取得宿主执行和业务结果证据前，报告“自动检索／自动采集待端到端验证”，不要用手动运行检索或采集代码代替。参见 [Codex 插件 Hook 的更新与信任规则](https://learn.chatgpt.com/docs/hooks#plugin-bundled-hooks)。本次启动方式调整仅适用于 Windows Codex；其他 Agent 的 Hook 启动方式保持不变。
+
+#### Claude Code
+
+1. 检查 `agentic-context@aliyun-agentic-context` 的启用状态；未启用时，通过 shell 执行 `claude plugin enable agentic-context@aliyun-agentic-context`，使用安装时的配置目录和作用域。
+2. 使当前会话加载插件变更。无法通过工具重载当前会话时，提示用户输入 `/reload-plugins`；需要重启时，待任务结束并确认后操作。不要在 shell 中执行会话斜杠命令。
+3. 检查 Agentic Context 的 `SessionStart`、`UserPromptSubmit`、`Stop`、`PreCompact` Hooks 是否加载及其命令与来源。需要用户查看原生界面时，提示输入 `/hooks`；该界面只读，不是 Codex 的逐项信任流程。
+
+若 Hooks 被禁用，检查 `disableAllHooks` 和组织的 Hooks 策略，不修改其他插件的权限。参见 [Claude Code 插件加载说明](https://code.claude.com/docs/en/discover-plugins#apply-plugin-changes-without-restarting)和 [Hooks 检查说明](https://code.claude.com/docs/en/hooks#the-hooks-menu)。
+
+#### OpenClaw
+
+请使用新版 OpenClaw。自动检索使用 `before_prompt_build`，通过 `prependContext` 注入当前轮次上下文，不再适配旧版 `before_agent_start`。
+
+安装器通过当前版本的 `openclaw plugins install --help` 自动区分安装参数：旧版使用 `--link`；支持本地来源确认的新版使用 `--link --force`。无需额外传入 `--yes`；这不代替宿主要求的插件能力授权。
+
+在安装时相同的 OpenClaw profile 中执行；先用 `openclaw config file` 核对路径与安装结果一致。使用自定义目录时，确保 `OPENCLAW_STATE_DIR`、`OPENCLAW_CONFIG_PATH` 指向该 profile。
+
+```bash
+openclaw plugins enable agentic-context
+```
+
+若当前版本要求确认插件能力，先审查 Agentic Context 的能力声明，在取得相应用户授权后按原生流程确认；支持 `--accept-capabilities` 的版本可在确认后将其追加到上述命令。参见 [OpenClaw 插件能力授权](https://docs.openclaw.ai/plugins/manage-plugins#capability-consent)。
+
+若 Agentic Context 安装命令因能力授权未完成而失败，审查本次生成的 `.agentic-context/marketplace/plugins/agentic-context` 后，在原 Agentic Context 安装命令追加 `--accept-capabilities` 重试，安装器会分别传给宿主安装和启用命令；不支持该参数的版本会在修改配置前报错。也可以在同一 profile 中先完成 OpenClaw 原生安装授权，再重跑原 Agentic Context 命令：安装器确认插件来源仍为本次 Agentic Context 目录后继续配置，不重复安装，不接管其他目录中的同名插件。
+
+对于要求显式授权会话访问的版本，执行以下命令，仅授权 Agentic Context：
+
+```bash
+openclaw config set plugins.entries.agentic-context.hooks.allowConversationAccess true --strict-json
+```
+
+若宿主提示字段不支持，按该版本的插件权限机制处理，不手动写入未知配置；若组织策略拒绝授权，告知用户具体限制。等待 Gateway 自动重载；没有重载时，说明重启会影响该 Gateway 上的任务，经用户确认后在空闲时执行 `openclaw gateway restart`。然后检查插件加载及 Hook 警告：
+
+```bash
+openclaw plugins inspect agentic-context --runtime --json
+```
+
+检查命令成功不等于正在运行的 Gateway 已执行 Hook，仍需完成下方验证。参见 [OpenClaw Hooks 权限说明](https://docs.openclaw.ai/plugins/hooks#permissions-and-scope)。
+
+#### Hermes
+
+需要重启 Hermes 才能加载 Provider 时，待任务结束并取得用户确认后重启，再执行 `hermes memory status` 确认当前 Provider 为 `agentic-context`。Hermes 使用 Memory Provider，不需要执行 Codex 的 `/hooks` 信任操作。
+
+#### Qoder 桌面版、Qoder CLI、Qoder IDE
+
+三者统一使用 `install qoder`，同一用户、同一配置目录只需安装一次，不需要分别安装三个插件。三者共享 Agentic Context 的 workspace、user ID、API Key 和自动采集开关；重装会同时更新两个 MCP 配置入口，卸载会同时清理 Agentic Context 项并保留其他配置。这里的 Qoder 桌面版指 New Qoder，不是旧 QoderWork。
+
+New Qoder 的远程 MCP 地址必须使用 **HTTPS**。安装时将 `--endpoint` 设置为服务提供的 HTTPS 地址；若地址不可访问或证书校验失败，先解决服务连接问题，不关闭证书校验。已有安装出现 `MCP_PROFILE_URL_INSECURE` 时，使用 HTTPS 地址重新执行安装命令。
+
+默认写入当前用户的 `~/.qoder`：
+
+| 内容 | 安装位置 | 使用方 |
+| --- | --- | --- |
+| MCP 连接 | `settings.json` → `mcpServers.agentic-context` | Qoder 桌面版、CLI |
+| MCP 连接 | `mcp.json` → `mcpServers.agentic-context` | Qoder IDE |
+| 自动检索和采集 Hook | `settings.json` → `hooks` | 三者共用，每个事件只注册一次 |
+| 接入 Skill | `skills/agentic-context/SKILL.md` | 三者共用 |
+| Agentic Context 连接及采集进度 | `.agentic-context/` | 共用连接，采集进度按会话及 transcript 路径隔离 |
+
+`--config-dir` 只指定安装目标目录，不会修改宿主的配置目录。CLI 支持 `QODER_CONFIG_DIR`；桌面版和 IDE 使用自定义目录时，须确认宿主实际读取该目录。默认目录下不需要额外路径参数。
+
+1. Qoder 桌面版：在 **Settings → Hooks** 检查 Hook，在 **Extensions → Connectors** 检查 MCP，然后新建任务。
+2. Qoder CLI：会话内使用 `/mcp` 查看连接，使用 `/mcp reload` 重载；修改 Hook 后新建会话。
+3. Qoder IDE：在 **Qoder IDE Settings → MCP** 检查连接；修改 Hook、Skill 后需要重启 IDE，待任务结束并取得用户确认后操作。
+
+共用 `SessionStart`、`UserPromptSubmit`、`Stop`、`PreCompact` 四个事件。Hook 使用完整命令调用安装时定位的 Node.js，无需宿主 PATH 中存在 `node`。默认自动采集开启，仅提交安装后的新增对话，不回填历史。按宿主提示完成必要授权，不修改全局工具信任设置。配置可见不代表 Hook 已执行，需要在各宿主分别验证。
+
+工具或 Hook 未加载时，检查目录、项目配置覆盖和组织策略。Hook 注入了上下文不代表 MCP 工具已加载，应分别验证；检索超时或返回服务端错误时，检查 Agentic Context 服务响应。旧版本不支持上述配置时先升级，不套用 Codex 的信任配置。参见 [桌面版 Hooks](https://docs.qoder.com/qoder/hooks)、[IDE Hooks 与 transcript 格式](https://docs.qoder.com/extensions/hooks)、[IDE Skills](https://docs.qoder.com/extensions/skills) 和 [CLI MCP 配置](https://docs.qoder.com/cli/mcp-reference)。
+
+#### 验证连接与实际调用
+
+使用相同的 Agent 名称和配置目录检查连接；`status` 的 `nextSteps` 可再次查看加载指引：
+
+```bash
+npx --yes @aliyun-es/agentic-context@0.2.0 status <agent> --check --json
+```
+
+结果需要同时满足以下条件，其他字段略：
+
+```json
+{
+  "status": "CONFIGURED",
+  "drift": [],
+  "hostExecution": "NOT_VERIFIED",
+  "connection": {
+    "connected": true,
+    "missingTools": []
+  }
+}
+```
+
+`hostExecution: NOT_VERIFIED` 表示安装器尚未验证 Agent 实际执行工具，不是连接错误。当前会话可能尚未加载新工具，需要重载后在新会话中验证。
+
+通过已加载的 Agentic Context 工具执行一次有权限的实际查询：已配置知识库时，查询一个非敏感问题并检查返回来源。
+
+没有知识库时，执行一次当前用户的 Memory 查询或 Skill 查询。确认实际调用了 Agentic Context 工具；数据为空不等于安装失败。只在明确要求验证写入时保存非敏感测试信息，Memory 异步写入应通过 `memory_event_status_get` 确认完成。自动采集开启时，新会话中的测试对话也会按配置上传。
+
+**验证自动采集**：在启用 Hooks 后完成一轮新的非敏感对话，在宿主日志中查找 `Agentic Context memory submission accepted` 及对应 event ID，并查询事件确认处理结果。`PENDING` 仅表示已接收；手动调用 `memory_add` 成功不代表 Hook 已触发。使用 `--no-auto-capture` 时无需做这一步，启用 Hooks 也不会改变该设置。
+
+OpenClaw 采集提交失败时，会在配置目录的 `.agentic-context/failed-captures/` 保留待处理内容，日志给出文件位置；不会自动扫描或重放这些文件。
+
+Hermes 先将新对话保存到 `.agentic-context/pending-captures/`，再后台发送。`*.pending.json` 尚未发送，开启自动采集后会在启动时继续发送；`*.sending.json` 已开始发送，服务端返回接收成功的 `event_id` 后删除。退出最多等待当前请求 12 秒，其余未发送记录保留到下次启动。请求失败、结果不确定或进程退出留下的 `sending` 记录不会自动重发，需确认服务端是否接收后再人工处理。恢复发送只处理与当前 endpoint、workspace 和 userId 一致的记录；关闭自动采集时不恢复发送。
+
+这些文件包含对话正文，不保存接入配置中的 API Key，目录和文件分别使用 `0700`、`0600` 权限（Windows 受本机 ACL 控制），应按敏感数据保管。卸载前先处理或备份；Hermes 的落盘失败会记录警告并跳过该次发送，未完成写入的 `.tmp` 文件需人工检查。
+
+| 状态或现象 | 下一步 |
+| --- | --- |
+| `NOT_INSTALLED` | 核对当前 Agent、账号和 profile；环境正确时重新执行安装 |
+| `PREPARED` | 尚未注册插件，重新执行正常安装命令，不加 `--prepare` |
+| `FAILED` / `CONFIGURATION_CHANGED` | 根据错误或 `drift` 定位文件及配置项；保留用户改动，解决冲突后重新安装，不清空整个配置目录 |
+| 配置和连接正常，但没有工具 | 完成宿主授权、重载并开启新会话；继续查看宿主的 Agentic Context 加载错误，不重复安装到别的目录 |
+
+向用户报告配置、连接、实际工具调用及自动采集的验证结果。自动采集关闭时标记为“已关闭”；尚需新会话或未取得执行日志时标记为“未验证”，说明下一步，不声称全部完成。
+
+### 5. 调整配置、更新和卸载
+
+增加知识库、修改连接信息或更新插件，都重新执行 `install`，无需先卸载。已有安装可以省略连接参数，只传需要修改的选项。`install` 会将指定版本的文件安装到 Agent，仅下载 npm 包不会更新已安装插件。升级到后续版本时，将命令中的 `0.2.0` 替换为已确认的目标版本。
+
+**更新时保留未显式指定的配置**：不传 `--kb` 保留已有默认知识库；传入 `--kb` 时使用本次完整列表，清空使用 `--clear-kbs`。自动采集和 Skill 提取同样保留原开关，使用 `--auto-capture` / `--no-auto-capture`、`--auto-skill` / `--no-auto-skill` 显式调整。修改后重新加载并验证。
+
+`--kb` 指定自动检索的知识库，也作为 Agent 的默认查询指引，不是权限白名单。配置多个知识库时，自动检索分别调用 `hybrid_search` 并合并结果；没有默认知识库时，也可以在查询中指定知识库名称。
+
+#### `context` URL 升级
+
+从 `0.1.1` 起，请求使用 `context` 路径。`0.2.0` 中，五种 Agent 的自动检索和 Memory 自动采集统一通过 `/v1/context/mcp` 调用 `hybrid_search` 和 `memory_add`；Agent 主动执行的 Memory、Skill、知识库工具也使用 MCP。
+
+仅 OpenClaw 的可选自动 Skill 提取继续调用 `/v3/openapi/workspaces/{workspace}/context/skills/add`，因为现有 MCP 工具尚未提供从会话异步抽取 Skill 的等价能力。自动 Skill 提取默认关闭，更新时保留原开关；本次不修改服务端，也不新增文件上传能力。服务端须支持上述路径；连接失败时保留错误，不自动回退旧路径。
+
+已安装 `0.1.x` 的客户需重新执行目标版本的 `install` 完成覆盖升级，并按宿主要求重新加载插件；仅下载新版 npm 包不会更新已安装的运行时和 MCP 配置。省略连接参数会保留原 endpoint、workspace、用户身份、API Key、知识库列表及采集开关；采集进度与待处理记录继续沿用。旧配置中的 `serviceId` 不再决定请求路径。
+
+URL 升级不改变 Windows 管理员策略，也不代表自动检索或采集已通过端到端验证。
+
+#### 从旧版安装升级
+
+新版安装器兼容此前由 `@aliyun-es/eke` 创建的受管理安装。升级前结束正在执行的任务并退出或停止对应 Agent，避免旧进程在升级期间继续上传或修改采集进度。**不需要先卸载旧版**，也不要手工删除状态目录。
+
+在原账号和原配置目录执行以下命令；`agentic-context@0.2.0` 可直接升级 `agentic-context@0.1.0`、`agentic-context@0.1.1` 或旧包 `eke@0.1.1` 的受管理安装，无需先安装其他过渡版本：
+
+```bash
+npx --yes @aliyun-es/agentic-context@0.2.0 status <agent> --json
+npx --yes @aliyun-es/agentic-context@0.2.0 install <agent> --json
+```
+
+自定义配置目录时，两条命令均追加原来的 `--config-dir "<Agent配置根目录>"`。省略连接参数会复用原 endpoint、workspace、user ID 和 API Key；省略可选参数会保留知识库列表、自动采集和 Skill 提取开关。
+
+如果此前通过 `npm install -g @aliyun-es/eke` 全局安装，仍可直接使用上面的 `npx` 命令升级宿主插件。需要把全局命令包也换成新包时，两个包都提供 `eke` 命令，直接并装会报 `EEXIST`。在原 npm prefix 下依次执行：
+
+```bash
+npm uninstall -g @aliyun-es/eke
+npm install -g @aliyun-es/agentic-context@0.2.0
+agentic-context install <agent> --json
+```
+
+第一条只移除旧 npm 命令包，宿主中的插件配置和 `.eke` 状态仍保留；不要执行 `eke uninstall <agent>` 或使用 `--force` 覆盖其他命令。使用自定义 Agent 配置目录时，最后一条仍须追加原 `--config-dir`。
+
+旧 npm 包的弃用或下架将单独执行；已有插件通过新包升级，原配置和本地状态仍保留。下架不会删除本地已经安装或缓存的旧安装器，`npx` 升级也不会替换原全局 `eke` 可执行文件。升级后统一使用新包管理插件；旧 `0.1.1` 安装器不认识新插件标识，不能用于管理或降级已经迁移的安装。需要继续使用全局 `eke` 命令时，先按上面的步骤换成新 npm 包提供的兼容入口。
+
+对于仍使用旧 `eke` 标识的安装，升级会移除旧插件注册、MCP 入口和本插件拥有的旧 Hook、Skill，再注册 `agentic-context`；不会同时保留两套自动采集。旧 EKE 安装的 `.eke` 状态目录继续使用，保存既有连接、安装时间边界、采集游标及失败或待发送记录；已有 `agentic-context@0.1.x` 安装沿用自己的 `.agentic-context` 或 `.eke` 目录，新安装创建 `.agentic-context`。这是旧安装的存储兼容，不是另一个产品或插件。
+
+如果发现配置被外部修改、目标标识已被其他安装占用，安装器停止并保留相关配置。升级中途失败时，根据错误处理后，用相同账号、目录和 `install` 命令重试，不清空状态目录。旧版尚未升级也可以通过新命令执行 `status` 或 `uninstall`。旧 `eke` 标识迁移不支持 `--prepare`，以免生成新文件却未完成注册切换。已有 `agentic-context` 标识的覆盖升级不属于该限制。
+
+升级完成后，重新启动或重载 Agent，按 `nextSteps` 审查并授权新的 Hook 定义，再验证工具调用、自动检索及原有采集设置。插件改名不会继承宿主对旧 Hook 的信任。
+
+**`0.2.0` 移除了 OpenClaw 的手动业务子命令**：`openclaw eke` 和 `openclaw agentic-context` 下的 `search`、`get`、`update`、`forget`、`event` 均不再提供。依赖这些命令的脚本需改用对应 MCP 工具；自动检索、Memory 自动采集和可选自动 Skill 提取继续由宿主生命周期事件触发。npm 包的 `agentic-context` 与 `eke` 安装器入口仍保留，`install`、`status`、`uninstall` 的用法不变。
+
+#### 卸载
+
+卸载命令：
+
+```bash
+npx --yes @aliyun-es/agentic-context@0.2.0 uninstall <agent> --json
+```
+
+返回 `UNINSTALLED` 后重载或重启 Agent；只移除本地 Agentic Context 配置与文件，不删除服务端 Memory、知识库或 Skill。若返回 `MANUAL_CLEANUP_REQUIRED`，只检查结果指出的被外部修改的配置，不删除整个 Agent 配置目录。