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

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+记录客户可见变化、升级要求和兼容限制。发布时将 `Unreleased` 中属于本次版本的条目整理为 `## [版本号] - YYYY-MM-DD`，保留已发布条目。
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-04
+
+首个使用 `@aliyun-es/agentic-context` npm 包名的版本。新包采用独立版本序列，从 `0.1.0` 开始；原 `@aliyun-es/eke@0.1.1` 的受管理安装仍可通过新包升级，版本数字不代表对旧包的降级。
+
+### Changed
+
+- 对外名称统一为企业上下文引擎 / Agentic Context；npm 包名、插件、MCP 与 Skill 标识改为 `agentic-context`，保留 `eke` CLI 兼容入口。
+- 新安装使用 `.agentic-context`；已有受管理安装升级时沿用 `.eke`，保留连接配置、知识库列表、采集开关、安装时间边界及采集状态。目录迁移尚未包含在本次实现中。
+- 更新安装时保留省略的连接字段和可选设置；通过 `--clear-kbs`、`--no-auto-skill` 等选项显式调整。
+- 升级前检查旧配置与目标冲突，移除旧注册后再登记新标识；支持失败重试，以及使用新安装器查看或卸载旧安装。
+
+### Added
+
+- 标准迭代、兼容迁移、候选验证、npm 发布、稳定推广和恢复流程，以及逐版本发布记录模板。
+- 版本同步、发布元数据检查、自动验证和候选产物检查命令；发布默认使用 `next` 标签。
+
+### Fixed
+
+- 保留 OpenClaw 的 `eke` 子命令及旧 `search` 的 REST 调用和返回结构，避免升级破坏已有脚本；新命令继续提供联合检索。
+- 版本同步与发布检查覆盖 Hermes 的插件清单，避免 npm 升版后 Provider 仍报告旧版本。
+- 原生 marketplace 清理已生效但响应丢失时，通过确认原生清单恢复升级；无法确认已删除时保留错误和迁移状态。
+- 升级前独立检查 marketplace 清单；同名目标已存在或无法可靠读取清单时保留旧安装，避免清理旧注册后才发现冲突。
+- 对已安装插件执行 `--prepare` 时保留自定义宿主程序路径，后续更新和卸载继续复用。
+- 宿主配置写入失败时保留原恢复记录；首次安装写文件失败后可安全重试，并保留已选择的采集开关等可选设置。
+- 发布检查覆盖完整运行时文件，并从实际 npm 安装包验证五种宿主的准备安装、状态、运行时导入及卸载，阻止缺少运行时依赖的产物。
+
+### Upgrade notes
+
+- 按精确版本运行 `npx --yes @aliyun-es/agentic-context@0.1.0 install <agent> --json` 升级已有受管理安装；先结束活动任务，升级后按宿主要求重载、重新审查 Hook。升级沿用原状态目录，无本地数据格式迁移。
+- `eke` 命令别名不会将旧 npm 包自动更新到新包；包改名的完整操作见安装文档。
+- 全局 npm 安装用户需先移除旧命令包再安装新命令包，避免 `eke` 文件冲突；升级后不使用旧 `0.1.1` 安装器回写已迁移配置。
+- 当前尚无独立配置 `schemaVersion`、完整目录迁移和通用数据回滚机制。后续涉及本地数据格式变化的发布必须先满足发布流程中的迁移门槛。

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,3 @@
+Agentic Context Plugin
+
+Alibaba Cloud Elasticsearch Agentic Context integration for OpenClaw, Hermes, Codex and Claude Code.

package/README.md

@@ -1,3 +1,378 @@
-# 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.1.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 自动采集在首次安装时默认开启，更新时保留原设置**：插件生效后，会将新的用户和助手对话文本发送到所配置的企业上下文引擎服务，不补传历史会话，不自动对正文做通用敏感信息脱敏。如需关闭，使用 `--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 自身也须支持对应系统。
+
+#### Node.js 不存在、版本过低或终端找不到它
+
+先定位已有程序，避免重复安装：macOS/Linux 执行 `command -v node npm npx`，Windows PowerShell 执行 `Get-Command node,npm,npx -All -ErrorAction SilentlyContinue`。如果程序已安装但未进入 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.1.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 PowerShell 使用 `--cache "$env:LOCALAPPDATA\agentic-context-npm-cache"`。如果错误发生在 Agent 配置目录而不是 npm 缓存，应修正当前账号和配置路径，不能靠换缓存解决。
+
+企业网络必须使用代理时，复用企业批准的 `HTTP_PROXY`、`HTTPS_PROXY` 和 `NO_PROXY`。对 Node.js 24 的服务请求，macOS/Linux 执行 `export NODE_USE_ENV_PROXY=1`，PowerShell 执行 `$env: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)。
+
+#### 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.1.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.1.0` 替换为已确认的目标版本。
+
+**更新时保留未显式指定的配置**：不传 `--kb` 保留已有默认知识库；传入 `--kb` 时使用本次完整列表，清空使用 `--clear-kbs`。自动采集和 Skill 提取同样保留原开关，使用 `--auto-capture` / `--no-auto-capture`、`--auto-skill` / `--no-auto-skill` 显式调整。修改后重新加载并验证。
+
+`--kb` 指定自动检索的知识库，也作为 Agent 的默认查询指引，不是权限白名单。配置多个知识库时，自动检索分别调用 `hybrid_search` 并合并结果；没有默认知识库时，也可以在查询中指定知识库名称。
+
+#### 从旧版安装升级
+
+新版安装器兼容此前由 `@aliyun-es/eke` 创建的受管理安装。升级前结束正在执行的任务并退出或停止对应 Agent，避免旧进程在升级期间继续上传或修改采集进度。**不需要先卸载旧版**，也不要手工删除状态目录。
+
+在原账号和原配置目录执行以下命令；新包 `0.1.0` 可直接升级旧包 `0.1.1` 的受管理安装，无需先安装其他过渡版本：
+
+```bash
+npx --yes @aliyun-es/agentic-context@0.1.0 status <agent> --json
+npx --yes @aliyun-es/agentic-context@0.1.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.1.0
+agentic-context install <agent> --json
+```
+
+第一条只移除旧 npm 命令包，宿主中的插件配置和 `.eke` 状态仍保留；不要执行 `eke uninstall <agent>` 或使用 `--force` 覆盖其他命令。使用自定义 Agent 配置目录时，最后一条仍须追加原 `--config-dir`。
+
+旧 npm 包的弃用或下架将单独执行；已有插件通过新包升级，原配置和本地状态仍保留。下架不会删除本地已经安装或缓存的旧安装器，`npx` 升级也不会替换原全局 `eke` 可执行文件。升级后统一使用新包管理插件；旧 `0.1.1` 安装器不认识新插件标识，不能用于管理或降级已经迁移的安装。需要继续使用全局 `eke` 命令时，先按上面的步骤换成新 npm 包提供的兼容入口。
+
+升级会移除旧插件注册、MCP 入口和本插件拥有的旧 Hook、Skill，再注册 `agentic-context`；不会同时保留两套自动采集。原 `.eke` 状态目录继续使用，保存既有连接、安装时间边界、采集游标及失败或待发送记录；新安装才创建 `.agentic-context`。这是旧安装的存储兼容，不是另一个产品或插件。
+
+如果发现配置被外部修改、目标标识已被其他安装占用，安装器停止并保留相关配置。升级中途失败时，根据错误处理后，用相同账号、目录和 `install` 命令重试，不清空状态目录。旧版尚未升级也可以通过新命令执行 `status` 或 `uninstall`。旧安装升级不支持 `--prepare`，以免生成新文件却未完成注册切换。
+
+升级完成后，重新启动或重载 Agent，按 `nextSteps` 审查并授权新的 Hook 定义，再验证工具调用、自动检索及原有采集设置。插件改名不会继承宿主对旧 Hook 的信任。
+
+OpenClaw 中的新命令为 `openclaw agentic-context ...`；保留 `openclaw eke ...` 供已有脚本使用，其中旧 `eke search` 继续使用原 Memory REST 检索和返回结构，新 `agentic-context search` 使用联合检索。
+
+#### 卸载
+
+卸载命令：
+
+```bash
+npx --yes @aliyun-es/agentic-context@0.1.0 uninstall <agent> --json
+```
+
+返回 `UNINSTALLED` 后重载或重启 Agent；只移除本地 Agentic Context 配置与文件，不删除服务端 Memory、知识库或 Skill。若返回 `MANUAL_CLEANUP_REQUIRED`，只检查结果指出的被外部修改的配置，不删除整个 Agent 配置目录。