From ac55132249c04282b960db40f7cbd176afd9f3ac Mon Sep 17 00:00:00 2001 From: huangsen Date: Wed, 30 Sep 2026 15:33:14 +0800 Subject: [PATCH] docs(codex): expand setup guide and reserve screenshot slots --- .github/workflows/ci-docs.yml | 1 + .github/workflows/deploy-docs.yml | 1 + github-pages/scripts/generate-content.mjs | 16 + github-pages/tests/generated-content.test.mjs | 1 + integrations/codex/README.md | 342 +++++++++++------- integrations/codex/README_ZH.md | 282 ++++++++++----- integrations/codex/figures/README.md | 33 ++ 7 files changed, 463 insertions(+), 213 deletions(-) create mode 100644 integrations/codex/figures/README.md diff --git a/.github/workflows/ci-docs.yml b/.github/workflows/ci-docs.yml index 6c9e238e..52e1af31 100644 --- a/.github/workflows/ci-docs.yml +++ b/.github/workflows/ci-docs.yml @@ -16,6 +16,7 @@ on: - 'integrations/claude_code/README_ZH.md' - 'integrations/codex/README.md' - 'integrations/codex/README_ZH.md' + - 'integrations/codex/figures/**' - 'integrations/hermes_agent/README.md' - 'reme_studio/README*.md' - 'reme_studio/figures/**' diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index c20988af..8ed04dc1 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -11,6 +11,7 @@ on: - "integrations/claude_code/README_ZH.md" - "integrations/codex/README.md" - "integrations/codex/README_ZH.md" + - "integrations/codex/figures/**" - "integrations/hermes_agent/README.md" - "README.md" - "README_ZH.md" diff --git a/github-pages/scripts/generate-content.mjs b/github-pages/scripts/generate-content.mjs index 4c643253..475420dc 100644 --- a/github-pages/scripts/generate-content.mjs +++ b/github-pages/scripts/generate-content.mjs @@ -54,6 +54,18 @@ const externalDocumentRewrites = { ['src="docs/figure/', 'src="../figure/'], ["(docs/zh/", "(./"], ], + "integrations/codex/README.md": [ + ["(./README_ZH.md)", "(/zh/integrations/codex)"], + ["(../../docs/en/configuration.md)", "(/en/configuration)"], + ["(./figures/README.md)", "(https://github.com/agentscope-ai/ReMe/blob/main/integrations/codex/figures/README.md)"], + ["(./figures/", "(/figures/codex/"], + ], + "integrations/codex/README_ZH.md": [ + ["(./README.md)", "(/en/integrations/codex)"], + ["(../../docs/zh/configuration.md)", "(/zh/configuration)"], + ["(./figures/README.md)", "(https://github.com/agentscope-ai/ReMe/blob/main/integrations/codex/figures/README.md)"], + ["(./figures/", "(/figures/codex/"], + ], "integrations/dsh/README.md": [ ["(./README_ZH.md)", "(/zh/integrations/dsh)"], ["(./figures/", "(/figures/dsh/"], @@ -235,6 +247,10 @@ for (const [destination, source] of externalDocuments) { sourceMap[destination] = source; } +await cp(path.join(repoDir, "integrations/codex/figures"), path.join(outputDir, "public/figures/codex"), { + recursive: true, + filter: (source) => !source.endsWith(".md"), +}); await cp(path.join(repoDir, "integrations/dsh/figures"), path.join(outputDir, "public/figures/dsh"), { recursive: true, }); diff --git a/github-pages/tests/generated-content.test.mjs b/github-pages/tests/generated-content.test.mjs index f77f16f6..1434c2c1 100644 --- a/github-pages/tests/generated-content.test.mjs +++ b/github-pages/tests/generated-content.test.mjs @@ -148,6 +148,7 @@ test("tracks every generated input in documentation CI and deployment", async () "integrations/claude_code/README_ZH.md", "integrations/codex/README.md", "integrations/codex/README_ZH.md", + "integrations/codex/figures/**", "integrations/hermes_agent/README.md", "integrations/dsh/README*.md", "integrations/dsh/figures/**", diff --git a/integrations/codex/README.md b/integrations/codex/README.md index 87ef7fcf..dca06c23 100644 --- a/integrations/codex/README.md +++ b/integrations/codex/README.md @@ -2,167 +2,261 @@ [中文说明](./README_ZH.md) -Start a ReMe service, then install the ReMe plugin in Codex. This is the supported integration -for this host. The plugin bundles automatic recall, completed-turn recording, MCP tools, and the -`reme-memory` skill in one installation. ReMe manages durable memory and consolidation in your workspace. +Give Codex memory across conversations: start your own ReMe service, install the ReMe plugin, and +configure it through the native MCP settings form. The plugin recalls relevant history before a +prompt and records completed conversations. Your ReMe workspace owns the durable memory files. -The plugin and its marketplace are maintained in `integrations/codex/` and installed from -this checkout. Keep the ReMe service running while using the plugin. +## Before you start -```text -Start ReMe → Install the ReMe plugin → Use memory in Codex +- **Codex:** a client supporting local plugins, command hooks, and hook trust review. The native + settings form also requires the `openai/settings` MCP extension. CLI 0.145.0 supports hooks and + tools but does not render that form. +- **Plugin runtime:** Python 3.11+ available as `python3`, with FastMCP >= 3.4.2. Both the bundled + MCP server and the hooks use this environment, even if ReMe runs elsewhere. +- **ReMe:** a running HTTP service with MCP enabled and `search`, `auto_memory`, and `health_check` + exposed. Configure a model for memory extraction using the [ReMe configuration guide](../../docs/en/configuration.md). + Default BM25 recall does not require an embedding model. +- **Source:** a local checkout of this repository. The plugin and its marketplace live in + `integrations/codex/`; install from that checkout. + +Check the Python environment from which you launch Codex: + +```bash +python3 -c "import sys, fastmcp; print(sys.version); print(fastmcp.__version__)" ``` -## Requirements - -- Python 3.11+ available as `python3` in the host's environment, with FastMCP >= 3.4.2 (included with ReMe). -- Codex CLI 0.145.0 or a compatible client supporting local plugins, command hooks, and hook trust review. -- A graphical host supporting the `openai/settings` MCP extension for the native settings UI. CLI 0.145.0 supports hooks and tools but does not render this UI. -- A running ReMe HTTP service exposing `search`, `auto_memory`, and `health_check`, with MCP enabled. -- A working model configuration on the ReMe server for memory extraction. Default BM25 recall does not need embeddings. +If the host environment does not include FastMCP, install it there with +`python3 -m pip install "fastmcp>=3.4.2"`. ## 1. Start ReMe ```bash pip install "reme-ai[core]" -reme start workspace_dir=/absolute/path/to/workspace service.backend=http +reme start \ + workspace_dir=/absolute/path/to/reme-workspace \ + service.backend=http \ + service.host=127.0.0.1 \ + service.port=2333 ``` -The default endpoint is `http://127.0.0.1:2333`, with MCP at `/mcp`. Keep the unauthenticated HTTP -service on loopback or behind a protected proxy. Different workspaces isolate different memory -scopes; sharing one workspace between hosts is intentional cross-agent recall. +Keep this service running. Its MCP address is `http://127.0.0.1:2333/mcp`. If you choose a different +port, set the same address in the plugin in step 3. The address must be reachable **from the machine +running Codex**; `127.0.0.1` refers to that machine. -## 2. Install the plugin +The plugin does not start ReMe. Keep the unauthenticated HTTP service on loopback or behind a +protected proxy. The service's `workspace_dir` determines which memory files it reads and writes. -Register this repository-local marketplace, then install its plugin: +## 2. Install the plugin and trust its hooks + +Register the marketplace using the absolute path to your checkout, then install the plugin: ```bash codex plugin marketplace add /absolute/path/to/ReMe/integrations/codex codex plugin add reme@reme-codex ``` -Start Codex and review and trust the four ReMe hooks (`SessionStart`, `SessionEnd`, -`UserPromptSubmit`, and `Stop`) in `/hooks`, then open a new conversation. -The installation loads the bundled hooks, MCP connection, and skill together. After plugin updates, -reinstall it and review any changed hook definitions. +> **Screenshot placeholder — `plugin-installed.png`:** Capture the actual plugin detail page with the ReMe name, enabled state, and `reme` MCP server card. -This package uses the supported `.codex-plugin/plugin.json` and `.mcp.json` layout. -Codex 0.159.2 and desktop runtime 0.158.0-alpha.2.1 omit this plugin's hooks when a root -`plugin.json` selects the portable loader, even with an explicit hook declaration. Keep the -Codex layout until native hook discovery is verified with the portable loader. + -## 3. Use memory in Codex +Restart the desktop client, or start a new Codex CLI session. Open the host's Hook settings +(`/hooks` in the CLI), find **ReMe / `reme@reme-codex`**, and review all four hooks: -In a new conversation, ask “Check whether ReMe is available.” The installed plugin's tools check -the running service; `/mcp` shows the plugin's connection status. Then use Codex normally: -the plugin recalls relevant memory before prompts and records completed turns in batches of five. -For an explicit query, ask “What did we decide about Project Juniper? Cite the memory sources.” - -Automatic recording sends completed user/assistant text to the configured ReMe service. -Set `auto_memory` to `false` for recall-only use. - -## Configure through MCP settings - -Open the installed ReMe MCP server's settings in a host that supports `openai/settings`. -The native form exposes the service address, automatic recall and memory switches, batch size, -recall limits, timeouts, and timezone. Save changes, then use **Check connection** to call -`health_check` on the saved address without sending conversation content. The settings remain -available when ReMe is offline, so a wrong address can be corrected there. - -Settings are atomically saved to `${CODEX_HOME:-$HOME/.codex}/reme/config.json`, outside the plugin -cache. The next MCP tool call and hook invocation use the new values without a reconnect or reinstall. -An in-flight call keeps its original endpoint and settings. Disabling `auto_memory` pauses capture -and queued retries; explicit memory tools remain available. - -| Option | Default | Meaning | +| Hook | What it does | Required state | | --- | --- | --- | -| `mcp_url` | `http://127.0.0.1:2333/mcp` | MCP address for both explicit tools and automatic hooks; custom paths are supported | +| `UserPromptSubmit` | Recalls relevant memory before your prompt | Enabled and trusted | +| `Stop` | Captures the completed turn and submits due memory batches | Enabled and trusted | +| `SessionStart` | Retries pending batches from earlier sessions | Enabled and trusted | +| `SessionEnd` | Attempts a short final flush | Enabled and trusted | + +> **Screenshot placeholder — `hooks-trusted.png`:** Show all four ReMe hooks and their enabled/trusted state in the desktop settings or CLI `/hooks`. + + + +Installing a plugin does not automatically trust its hooks. Until reviewed, the MCP connection can +work while automatic recall and recording remain inactive. See the [Codex hook trust guide](https://learn.chatgpt.com/docs/hooks#review-and-trust-hooks). + +After updating the checkout, run `codex plugin add reme@reme-codex` again and restart the host. +Review changed hook definitions if prompted, then open a new conversation. User settings are stored +outside the plugin cache and survive upgrades. + +## 3. Configure the ReMe MCP connection + +In the desktop client's plugin directory, open the **installed ReMe plugin**. Find its `reme` MCP +server card and select the settings control labeled **Open MCP settings**. Open that connection's +ReMe settings form. Labels and placement can vary by host version; this is the MCP connection's +settings entry, separate from the plugin enable switch and Hook trust settings. + +For a first test: + +1. Set **ReMe MCP address** (`mcp_url`) to your service's full MCP URL, including `/mcp`. +2. Enable **Automatic recall** (`auto_recall`) and **Automatic memory** (`auto_memory`). +3. Set **Turns per memory batch** (`memory_interval`) to `1` so one completed turn triggers a write. +4. Save the form, then select **Check connection**. In the tested desktop client, the result appears + in a tooltip on the button; hover over it to see the ReMe version and `healthy` status. + +> **Screenshot placeholder — `mcp-settings.png`:** Show the MCP URL, automatic switches, batch size, and the Check connection result tooltip in the native form. + + + +**A healthy connection verifies service access. It does not verify Hook loading, trust, or memory +extraction.** Continue with the two-conversation test below. The connection check does not send +conversation content to ReMe. + +If you cannot find the form, confirm that you opened the installed plugin's MCP connection and that +its process started successfully. A client without `openai/settings` support has no native form; +see [Configuration reference](#configuration-reference) for the user-owned settings file. + +## 4. Verify recording and recall in separate conversations + +Keep both automatic switches enabled and use `memory_interval=1`. Choose a unique test project +name so an older test cannot satisfy the recall check. + +**Conversation A — record a fact:** + +```text +Remember this confirmed decision for ReMe-Hook-Local-6502: +release reviews happen Friday at 16:45 UTC; +the verification phrase is amber-lynx-6502. +Do not use tools or skills or write files yourself; just acknowledge the facts. +``` + +Wait for the final reply and the Stop hook to finish. Check the local plugin log: + +```bash +tail -n 10 "${CODEX_HOME:-$HOME/.codex}/reme/hooks.log" +``` + +A `memory_saved` event means ReMe acknowledged the batch. Also inspect the ReMe workspace's `daily/` +notes. A successful batch leaves `.done` receipts under the plugin's `reme/queue/` directory; +pending `.json` files remain until acknowledged. Do not delete pending files to clear an error. + +> **Screenshot placeholder — `memory-recorded.png`:** Capture conversation A with its fact and final reply. This shows the conversation; verify delivery separately with `memory_saved` and a receipt as described above. + + + +**Conversation B — start a new conversation, then recall:** + +```text +For ReMe-Hook-Local-6502, what is the review time and verification phrase? +Cite only supplied memory, including its source path. +Do not use tools or skills; if no memory is supplied, say you do not know. +``` + +The expected result includes **Friday at 16:45 UTC**, **amber-lynx-6502**, and a source path from +ReMe. Use a new conversation so the answer cannot come from the first conversation's context. + +> **Screenshot placeholder — `memory-recalled.png`:** Capture conversation B with its question, recalled review time, verification phrase, and ReMe source path. + + + +After testing, keep `memory_interval=1` for per-turn writes or restore the default `5` to batch turns. +For explicit retrieval, ask “What did we decide about this project? Cite ReMe sources.” The bundled +`reme-memory` skill and MCP tools remain available alongside automatic hooks. + +## Configuration reference + +Change settings in the MCP form. The next hook or MCP tool call uses saved changes without a +reconnect; an in-flight call keeps its original settings. The form remains available when the +upstream ReMe service is offline, so you can correct its address. + +| Setting | Default | Effect | +| --- | --- | --- | +| `mcp_url` | `http://127.0.0.1:2333/mcp` | Shared MCP URL for explicit tools and hooks; custom paths supported | | `auto_recall` | `true` | Search before a user prompt | -| `auto_memory` | `true` | Queue and submit completed turns; false also disables retries | -| `recall_limit` | `5` | Search result limit | +| `auto_memory` | `true` | Capture and submit completed turns; false also pauses queued retries | +| `memory_interval` | `5` | Completed turns per batch; `1` submits each turn | +| `recall_limit` | `5` | Maximum search results | | `recall_min_score` | `0` | Minimum recall score | -| `recall_timeout` | `5` | Foreground MCP timeout in seconds, at most 10 | -| `request_timeout` | `600` | Memory-write and MCP request timeout in seconds, at most 600 | -| `memory_interval` | `5` | Completed turns per batch; use 1 for immediate per-turn writes | -| `shutdown_timeout` | `2` | Total best-effort exit drain budget in seconds, at most 2 | | `context_max_chars` | `8000` | Maximum recalled payload characters | +| `recall_timeout` | `5` | Recall timeout in seconds; greater than 0, at most 10 | +| `request_timeout` | `600` | Memory/tool timeout in seconds; greater than 0, at most 600 | +| `shutdown_timeout` | `2` | Exit flush budget in seconds; greater than 0, at most 2 | | `timezone` | `Asia/Shanghai` | Daily batch timezone; match the ReMe workspace | -The JSON file remains user-owned and can also be edited directly; only overrides are required. -See [config.example.json](plugins/reme/config.example.json) for a complete example. Remove a field -from the file to restore its default. Unknown fields and invalid values fail validation; hooks skip -work and log `hook_failed` instead of falling back to another service. UI updates reject invalid -values without replacing the saved file. +For recall-only use, turn off `auto_memory` and leave `auto_recall` on. To pause both automatic +behaviors, turn off both switches. Explicit MCP tools remain available. -Existing configurations keep working. The deprecated `api_url` field is accepted on read but is -no longer used and is removed on the next UI save. All operations use `mcp_url`. Standard `/mcp` -endpoints retain existing queue and receipt identities. Pending queues from a custom legacy -`api_url` remain untouched: they are not automatically retargeted. Address changes never forward -old pending conversations to the new service; switch back to the original endpoint to retry its queue. +Settings are saved atomically to `${CODEX_HOME:-$HOME/.codex}/reme/config.json`. You can also edit +this user-owned file directly; only overrides are needed. See [config.example.json](plugins/reme/config.example.json). +Remove a field to restore its default. Invalid values and unknown keys are rejected; failed UI +saves leave the previous file intact. Do not edit the installed plugin cache to configure ReMe. -Both the host-managed MCP server and short-lived hooks require FastMCP in the host's `python3` -environment. If ReMe runs elsewhere, install it with `python3 -m pip install "fastmcp>=3.4.2"`. -The plugin does not launch ReMe. Its native form follows the pinned -[OpenAI MCP Extensions settings contract](https://github.com/openai/mcp-extensions/blob/node-v0.1.0/docs/spec.md#structured-settings). -Clients without that extension can still use tools and hooks, but have no native settings form. +Changing `mcp_url` never forwards old queued conversations to the new service. Switch back to the +original address to retry its queue. The legacy `api_url` key is accepted on read, no longer used, +and removed on the next UI save. Existing standard `/mcp` queue identities are preserved; custom +legacy HTTP queues remain untouched. -## Lifecycle and failure behavior +## Troubleshooting -- `UserPromptSubmit` calls `search` synchronously with a short timeout. Results are bounded and - wrapped in `` as untrusted historical evidence. A failure does not reject the prompt. -- Synchronous `Stop` hooks extract only the completed user/final-assistant text from the - hook's local transcript, then submit `auto_memory` batches through MCP. Tool output, - reasoning, and injected ReMe context are excluded. The server does not need access to host files. -- Session and message IDs are stable and host-scoped. Repeated Stops are deduplicated. Per-session - process locks serialize writes; batches never mix dates. Subagent events and hook continuations - are excluded. No extra background daemon, package download, or ReMe process is started. -- Queues and acknowledgement receipts live under the host's `reme/queue/`, separate from the - plugin cache and namespaced by endpoint. A failed or timed-out write stays queued. `SessionStart` - retries pending work synchronously; `SessionEnd` attempts a short drain. -- Codex 0.145.0 skips hooks marked `async`, so this adapter deliberately uses synchronous hooks. - A due memory batch or a startup retry can delay completion by up to `request_timeout`. - Claude Code uses its own native asynchronous adapter. -- Shutdown and delivery are best-effort. A host killed before the Stop hook captures a turn can - lose that turn. A lost MCP acknowledgement can cause a retry; stable message IDs prevent duplicate - source messages, but memory extraction is **at least once**, not exactly once. Short residual - batches survive for the next session when shutdown has insufficient time. -- Queue files contain source conversation text; retain them until delivery completes. Logs in - `reme/hooks.log` contain event/error types only. Disabling `auto_memory` retains pending files. -- Daily `auto_dream` consolidation remains owned by the ReMe service. Unlike OpenClaw's long-lived - Gateway adapter, these short-lived hook processes do not run their own scheduler. +Work through **connection → Hook state → recording → fresh-conversation recall** in that order. -## Verify and troubleshoot +| Symptom | Check or action | +| --- | --- | +| Cannot find ReMe settings | Open the installed plugin's `reme` MCP card → **Open MCP settings**. Confirm the host supports the native form and the MCP process starts. | +| Check connection shows a spinner but no chat reply | Hover over the button for the result tooltip. `healthy` and the ReMe version indicate a successful service check. | +| Connection is healthy, but nothing is recorded or recalled | Check that all four ReMe hooks are listed, enabled, and trusted. Installation and MCP health do not grant hook trust. | +| ReMe is absent from the Hook list | Update the checkout, reinstall the plugin, and restart the host. See the compatibility notes below. | +| Hook is listed but awaiting review | Review and trust its current definition, then start a new conversation. | +| `hook_failed` or MCP startup failure | Check the host's Python 3.11+/FastMCP environment, saved configuration, service reachability, and ReMe server logs. | +| No note after one turn | Set `memory_interval=1`, enable `auto_memory`, and wait for the final reply and Stop hook. ReMe also needs a working extraction model. | +| `capture_skipped` | Update to the current plugin. The hook needs a supported local transcript and final assistant message; current and legacy Codex event formats are supported. | +| `retry_failed` or pending queue files | Restore the original service/model connection and open a new session to retry. Keep the pending files. | +| Notes exist but recall misses them | Use a new conversation, enable `auto_recall`, check the service address/workspace, allow indexing to finish, and inspect recall limits and score filters. Try an explicit ReMe search to isolate retrieval from the hook. | -1. Check that `/hooks` lists all four ReMe hooks and that each is enabled and trusted. Then use - **Check connection** in the MCP settings. A healthy result verifies the service connection; - it does not verify hook loading or execution. -2. For a quick test, set `memory_interval` to `1`, then start a new conversation and ask the agent to - remember a synthetic fact, such as “Project Juniper reviews are on Thursday.” -3. Wait for the write and inspect `reme/hooks.log` for `memory_saved` and the ReMe workspace's `daily/`. -4. Start a separate conversation and ask for that fact. Confirm recall is from ReMe, with source paths. +The log records status and exception types, not conversation text. Successful recall and idle +hooks do not necessarily create log entries; the absence of `hooks.log` alone does not prove +that no hook ran. Queue files do contain the source conversation text. -The installed plugin provides both automatic memory and explicit search/read and health checks. -If its tools are missing, check that the plugin is installed and enabled, the service is running, -and `service.jobs` exposes the required jobs. If ReMe is missing from `/hooks`, reinstall the current -plugin and restart the host. If listed but awaiting review, trust its current definitions. -If trusted hooks fail, check that the hook environment's `python3` is Python 3.11+ with FastMCP installed. +## Memory behavior and compatibility -Capture reads Codex rollout JSONL `event_msg` records: legacy `user_message` / final `agent_message`, -and newer `item_completed` events containing `UserMessage` / final `AgentMessage` text blocks. -`response_item` records are excluded, including injected context and duplicate messages. The hook requires -`transcript_path` and `last_assistant_message`. Missing or unsupported transcripts are skipped rather -than guessed. Codex transcript formats are not a stable public interface. Check `capture_skipped` or -`hook_failed` events when recall works but recording does not. +- Recalled text is bounded and wrapped in `` as untrusted historical evidence. + Only completed user/final-assistant text is recorded; tools, reasoning, subagents, commentary, + and injected memory are excluded. ReMe does not need access to Codex transcript files. +- Stable session/message IDs, per-session locks, and receipts prevent repeated Stops from + duplicating delivered source messages. Failed writes remain queued by service and session. +- Hooks are synchronous for compatibility with Codex 0.145.0, which skips asynchronous hooks. + A due batch or startup retry can delay completion up to `request_timeout`. Session exit has a + short, best-effort drain budget; remaining batches survive for the next session. +- Delivery is best-effort and extraction is at least once. Killing the host before capture can + lose a turn; a lost acknowledgement can cause extraction to be retried. +- Durable memory and daily consolidation belong to the ReMe service. The plugin starts no + separate daemon or scheduler. -In Codex 0.145.0, an unattended `codex exec` MCP call can return `user cancelled MCP tool call` -when approval cannot be collected. Verify explicit tools in an interactive session and approve the -specific call. Trusted automatic hooks act as MCP clients themselves; they do not request per-call model tool approval. +This package uses `.codex-plugin/plugin.json` and `.mcp.json`. In native checks, Codex 0.159.2 and +desktop runtime 0.158.0-alpha.2.1 omitted these hooks when a root portable `plugin.json` was present, +even with explicit hook declarations. Retain the current Codex package layout. The parser supports +both legacy `user_message` / final `agent_message` and newer `item_completed` conversation events; +`response_item` records are excluded. See the [hook adapter](plugins/reme/hooks/auto_memory.py). -## Source and validation +CLI 0.145.0 may return `user cancelled MCP tool call` for an explicit tool call when an unattended +session cannot collect approval. Verify such calls interactively. Automatic hooks use the trust +review described above. -Run `pytest tests/unit/test_coding_agent_plugins.py tests/unit/test_codex_plugin_mcp.py -v` from the ReMe checkout. Tests isolate host -state and mock service calls. With a runtime supporting `hooks/list`, run -`REME_CODEX_BIN=/path/to/codex pytest tests/integration/test_codex_plugin_install.py -v` -to install into an isolated profile and verify hook discovery before trust, without model calls or hook execution. -Native hook behavior is described in the [Codex hook reference](https://learn.chatgpt.com/docs/hooks). +## Maintainer checks + +See the [screenshot checklist](./figures/README.md) for the five genuine screenshot slots and replacement steps. +Both languages share the same PNG files; text placeholders remain visible until screenshots are added. + +```bash +pytest tests/unit/test_coding_agent_plugins.py tests/unit/test_codex_plugin_mcp.py -v +REME_CODEX_BIN=/path/to/codex pytest tests/integration/test_codex_plugin_install.py -v +``` + +The native installation test requires `hooks/list`, uses an isolated profile, and verifies all +four hooks before trust without model calls or hook execution. For documentation changes, run +`npm test` and `npm run build` in `github-pages/`. + +References: [Codex hooks](https://learn.chatgpt.com/docs/hooks), +[OpenAI MCP settings contract](https://github.com/openai/mcp-extensions/blob/node-v0.1.0/docs/spec.md#structured-settings). ReMe is developed at [agentscope-ai/ReMe](https://github.com/agentscope-ai/ReMe) under Apache-2.0. diff --git a/integrations/codex/README_ZH.md b/integrations/codex/README_ZH.md index e6c635be..0f4a39b0 100644 --- a/integrations/codex/README_ZH.md +++ b/integrations/codex/README_ZH.md @@ -2,138 +2,242 @@ [English](./README.md) -先启动 ReMe 服务，再在 Codex 中安装 ReMe 插件，即可使用长期记忆。这是本宿主支持的集成方式。 -插件统一安装自动召回、完成轮次记录、MCP 工具和内置 `reme-memory` Skill；ReMe 服务负责工作区中的记忆存储与整理。 +先启动自己的 ReMe 服务，再安装 ReMe 插件，通过原生 MCP 设置界面配置，即可让 Codex 跨会话使用记忆。 +插件在提交消息前召回相关历史，在完成对话后自动记录。持久记忆保存在你掌控的 ReMe 工作区文件中。 -插件与本地 marketplace 维护在 `integrations/codex/`，从仓库安装。 -使用插件期间，保持 ReMe 服务运行。 +## 开始前准备 -```text -启动 ReMe 服务 → 安装 ReMe 插件 → 在 Codex 中使用记忆 +- **Codex：**宿主需支持本地插件、命令 Hook 和 Hook 信任审核。原生配置表单还需支持 + `openai/settings` MCP 扩展。CLI 0.145.0 支持 Hook 和工具，但不渲染该表单。 +- **插件运行环境：**宿主的 `python3` 为 Python 3.11+，已安装 FastMCP >= 3.4.2。 + 插件内的 MCP Server 和 Hook 都使用此环境，即使 ReMe 服务运行在其他环境或机器上。 +- **ReMe：**HTTP 服务已启动并启用 MCP，开放 `search`、`auto_memory` 和 `health_check`。 + 按 [ReMe 配置指南](../../docs/zh/configuration.md) 配置记忆提取模型。默认 BM25 召回不需要 Embedding 模型。 +- **源码：**本地有 ReMe 仓库副本。插件及 marketplace 位于 `integrations/codex/`，从该目录安装。 + +在启动 Codex 的 Python 环境中检查依赖： + +```bash +python3 -c "import sys, fastmcp; print(sys.version); print(fastmcp.__version__)" ``` -## 环境要求 - -- 宿主环境中有 Python 3.11+，可通过 `python3` 执行，并已安装 FastMCP >= 3.4.2（ReMe 自带此依赖）。 -- Codex CLI 0.145.0 或兼容版本，支持插件、`UserPromptSubmit`、`Stop`、同步命令 Hook 和 `last_assistant_message`。 -- 原生配置界面需要支持 `openai/settings` MCP 扩展的图形宿主；CLI 0.145.0 支持 Hook 和工具，但不渲染该界面。 -- 已启动 ReMe HTTP 服务，开放 `search`、`auto_memory`、`health_check`，并启用 MCP。 -- ReMe 服务端有可用于自动记忆提取的模型配置。默认 BM25 召回不要求 Embedding。 +如果宿主环境缺少 FastMCP，在该环境执行 `python3 -m pip install "fastmcp>=3.4.2"`。 ## 1. 启动 ReMe 服务 ```bash pip install "reme-ai[core]" -reme start workspace_dir=/absolute/path/to/workspace service.backend=http +reme start \ + workspace_dir=/absolute/path/to/reme-workspace \ + service.backend=http \ + service.host=127.0.0.1 \ + service.port=2333 ``` -默认地址为 `http://127.0.0.1:2333`，MCP 路径为 `/mcp`。HTTP 服务没有内建 API Key 鉴权， -应保持 loopback 监听或部署受保护的代理。不同 workspace 隔离记忆；不同宿主使用同一 workspace 时会共享召回。 +保持服务运行，MCP 地址为 `http://127.0.0.1:2333/mcp`。如果使用其他端口，在第 3 步填写对应地址。 +地址必须能**从运行 Codex 的机器访问**；`127.0.0.1` 指向的是这台机器。 -## 2. 安装 ReMe 插件 +插件不会启动 ReMe。HTTP 服务没有内建鉴权，请保持 loopback 监听或置于受保护的代理之后。 +服务的 `workspace_dir` 决定读写哪一份记忆文件。 -添加仓库内的本地 marketplace，再安装插件： +## 2. 安装插件并信任 Hook + +使用仓库的绝对路径添加 marketplace，再安装插件： ```bash codex plugin marketplace add /absolute/path/to/ReMe/integrations/codex codex plugin add reme@reme-codex ``` -启动 Codex，在 `/hooks` 中检查并信任 ReMe 的四个 Hook（`SessionStart`、`SessionEnd`、 -`UserPromptSubmit`、`Stop`），然后新建会话。 -插件安装会一并加载 Hook、MCP 连接和内置 Skill。更新后重新安装插件，并审核有变化的 Hook。 +> **截图待补 — `plugin-installed.png`:** 截取真实 Codex 插件详情，保留 ReMe 名称、启用状态和 `reme` MCP Server 卡片。 -本插件使用受支持的 `.codex-plugin/plugin.json` 与 `.mcp.json` 布局。 -在 Codex 0.159.2 和桌面运行时 0.158.0-alpha.2.1 中，根目录 `plugin.json` 会选择 portable -加载器，导致本插件的 Hook 被遗漏，显式声明 Hook 路径也不能解决。确认 portable 加载器能通过 -原生 Hook 发现验证前，保留 Codex 布局。 + -## 3. 在 Codex 中使用记忆 +重启桌面客户端，或启动新的 Codex CLI 会话。打开宿主的 Hook 设置（CLI 中使用 `/hooks`）， +找到 **ReMe / `reme@reme-codex`**，审核以下四个 Hook： -在新会话中询问“检查 ReMe 是否可用”，由已安装插件的工具检查服务连接；也可通过 `/mcp` 查看插件连接状态。 -之后正常使用 Codex：插件在消息提交前自动召回相关记忆，每完成五轮对话分批记录一次。 -需要主动查询时，可以询问“之前关于 Juniper 项目做了什么决定？请附上记忆来源”。 +| Hook | 作用 | 所需状态 | +| --- | --- | --- | +| `UserPromptSubmit` | 在提交消息前召回相关记忆 | 已启用、已信任 | +| `Stop` | 捕获已完成的对话轮次，提交达到条件的记忆批次 | 已启用、已信任 | +| `SessionStart` | 重试之前会话中尚未提交的批次 | 已启用、已信任 | +| `SessionEnd` | 在短时间预算内尝试最后一次刷新 | 已启用、已信任 | -自动记录会把完成的用户/助手文本发送到配置的 ReMe 服务；仅需召回时，将 `auto_memory` 设为 `false`。 +> **截图待补 — `hooks-trusted.png`:** 截取四个 ReMe Hook 及其已启用、已信任状态；桌面设置页或 CLI `/hooks` 均可。 -## 通过 MCP 设置界面配置 + -在支持 `openai/settings` 的宿主中，打开已安装的 ReMe MCP Server 设置。 -原生表单提供服务地址、自动召回与记录开关、批次大小、召回限制、超时和时区。 -保存后点击 **Check connection**，会在已保存地址调用 `health_check`，不发送对话内容。 -ReMe 服务离线时仍可读取和修改设置，因此可以在此修正错误地址。 +安装插件不会自动授予 Hook 信任。未完成审核时，MCP 连接可能正常，但自动召回和记录不会执行。 +宿主规则见 [Codex Hook 信任说明](https://learn.chatgpt.com/docs/hooks#review-and-trust-hooks)。 -配置原子保存到 `${CODEX_HOME:-$HOME/.codex}/reme/config.json`，位于插件缓存之外，升级后保留。 -下一次 MCP 工具调用和 Hook 调用直接使用新配置，无需重新连接或重装。 -正在执行的调用继续使用原来的地址与配置。关闭 `auto_memory` 会暂停自动捕获与队列重试，显式工具仍可使用。 +更新仓库后，再执行一次 `codex plugin add reme@reme-codex`，重启宿主；如提示 Hook 定义有变化， +重新审核后新建会话。用户配置保存在插件缓存之外，升级会保留。 + +## 3. 配置 ReMe MCP 连接 + +在桌面客户端的插件目录中打开**已安装的 ReMe 插件**，找到 `reme` MCP Server 卡片， +点击标为 **Open MCP settings** 的设置入口，再打开该连接的 ReMe 配置表单。 +不同宿主版本的文字和位置可能不同；这里调整的是 MCP 连接的配置，插件启用开关和 Hook 信任位于各自的设置入口。 + +首次验证时： + +1. 将 **ReMe MCP address**（`mcp_url`）设为完整的 ReMe MCP 地址，包括 `/mcp`。 +2. 开启 **Automatic recall**（`auto_recall`）和 **Automatic memory**（`auto_memory`）。 +3. 将 **Turns per memory batch**（`memory_interval`）设为 `1`，使一轮完成的对话即可触发写入。 +4. 保存后点击 **Check connection**。已验证的桌面客户端通过按钮上的提示浮层显示结果； + 将鼠标停在按钮上，可看到 ReMe 版本和 `healthy` 状态。 + +> **截图待补 — `mcp-settings.png`:** 截取原生设置表单，保留 MCP 地址、两个自动开关、批次大小和 Check connection 的健康结果浮层。 + + + +**连接健康仅代表服务可达，不代表 Hook 已加载、已信任或记忆提取成功。** +继续执行下方的双会话验证。连接检查不会向 ReMe 发送对话内容。 + +找不到表单时，先确认进入的是已安装插件的 MCP 连接，并确认 MCP 进程启动成功。 +不支持 `openai/settings` 的客户端没有原生表单；用户配置文件的位置见[配置项参考](#配置项参考)。 + +## 4. 在两个独立会话中验证记录与召回 + +保持两个自动开关开启，并设 `memory_interval=1`。每次验证使用一个新的测试项目名， +避免旧测试的记忆让本次召回看似成功。 + +**会话 A：记录一条事实。** + +```text +请记住 ReMe-Hook-Local-6502 的已确认决定： +发布评审在每周五 16:45 UTC，校验短语为 amber-lynx-6502。 +不要调用工具、使用 Skill 或自行写入文件，只需确认这些事实。 +``` + +等待最终回复和 Stop Hook 执行完成，查看本机插件日志： + +```bash +tail -n 10 "${CODEX_HOME:-$HOME/.codex}/reme/hooks.log" +``` + +`memory_saved` 表示 ReMe 已确认收到该批次，同时检查 ReMe 工作区 `daily/` 下的笔记。 +成功提交后，插件的 `reme/queue/` 目录会留下 `.done` 收据；未确认的批次仍为 `.json` 文件。 +不要通过删除待提交文件来消除错误。 + +> **截图待补 — `memory-recorded.png`:** 截取会话 A 的测试事实及最终回复。此图展示对话；是否交付成功仍需以上述 `memory_saved` 和收据为准。 + + + +**会话 B：新建独立会话后召回。** + +```text +ReMe-Hook-Local-6502 的评审时间和校验短语是什么？ +只引用已提供的记忆，并附来源文件路径。 +不要调用工具或使用 Skill；没有提供记忆就说不知道。 +``` + +预期回答包含**每周五 16:45 UTC**、**amber-lynx-6502** 和 ReMe 来源路径。 +必须使用新会话，避免直接从会话 A 的上下文得到答案。 + +> **截图待补 — `memory-recalled.png`:** 截取独立会话 B 的提问和回答，保留评审时间、校验短语及 ReMe 来源路径。 + + + +验证后，可保留 `memory_interval=1` 逐轮提交，或恢复默认值 `5` 批量提交。 +需要主动查询时，可询问“之前关于这个项目做了什么决定？请附上 ReMe 来源”。 +内置 `reme-memory` Skill 和 MCP 工具也可用于显式检索。 + +## 配置项参考 + +在 MCP 表单中修改并保存。下一次 Hook 或 MCP 工具调用即使用新配置，无需重新连接； +正在执行的调用沿用原配置。上游 ReMe 服务离线时，表单仍可用，可以修正连接地址。 | 配置项 | 默认值 | 作用 | | --- | --- | --- | -| `mcp_url` | `http://127.0.0.1:2333/mcp` | 显式工具和自动 Hook 共用的 MCP 地址，支持自定义路径 | -| `auto_recall` | `true` | 用户提交消息时自动检索 | -| `auto_memory` | `true` | 自动捕获与提交；关闭后也不重试已有队列 | +| `mcp_url` | `http://127.0.0.1:2333/mcp` | 显式工具和 Hook 共用的 MCP 地址，支持自定义路径 | +| `auto_recall` | `true` | 用户提交消息前自动检索 | +| `auto_memory` | `true` | 自动捕获和提交已完成轮次；关闭后也暂停队列重试 | +| `memory_interval` | `5` | 每批完成的对话轮数；设为 `1` 则逐轮提交 | | `recall_limit` | `5` | 检索结果上限 | | `recall_min_score` | `0` | 自动召回最低分数 | -| `recall_timeout` | `5` | 前台 MCP 超时秒数，最大 10 | -| `request_timeout` | `600` | 写入与 MCP 请求超时秒数，最大 600 | -| `memory_interval` | `5` | 每批完成的对话轮数；设为 1 则逐轮提交 | -| `shutdown_timeout` | `2` | 退出时尽力刷新队列的总秒数，最大 2 | | `context_max_chars` | `8000` | 召回正文字符上限 | -| `timezone` | `Asia/Shanghai` | 批次按此时区分日，应与 ReMe workspace 一致 | +| `recall_timeout` | `5` | 召回超时秒数，大于 0、最大 10 | +| `request_timeout` | `600` | 记忆写入和工具调用超时秒数，大于 0、最大 600 | +| `shutdown_timeout` | `2` | 退出刷新预算秒数，大于 0、最大 2 | +| `timezone` | `Asia/Shanghai` | 批次按此时区分日，应与 ReMe 工作区一致 | -JSON 配置仍由用户掌控，也可直接编辑，只需写入要覆盖的选项。 -完整示例见 [config.example.json](plugins/reme/config.example.json)；从文件移除某项即可恢复其默认值。 -未知字段和无效值会使校验失败，Hook 跳过并记录 `hook_failed`，不会回退到其他服务。 -界面保存无效值时会返回错误，保留原配置文件。 +只需召回时，关闭 `auto_memory` 并保持 `auto_recall` 开启。暂停所有自动行为时，关闭两个开关。 +显式 MCP 工具仍然可用。 -已有配置仍可读取。旧 `api_url` 字段不再参与请求，下次在界面保存时会移除；所有操作统一使用 `mcp_url`。 -标准 `/mcp` 地址继续使用原来的队列和收据标识。自定义旧 `api_url` 下的待提交记录原样保留， -不会自动迁移目标地址。切换地址不会把旧对话发往新服务；切回原地址可继续重试该地址的队列。 +配置原子保存到 `${CODEX_HOME:-$HOME/.codex}/reme/config.json`。该文件由用户掌控，也可直接编辑， +只需保存要覆盖的选项，完整示例见 [config.example.json](plugins/reme/config.example.json)。 +移除配置项即可恢复默认值。无效值和未知字段会被拒绝，界面保存失败时保留原文件。 +请通过此配置调整插件，不要修改安装缓存。 -宿主管理的 MCP Server 和短生命周期 Hook 都依赖宿主 `python3` 环境中的 FastMCP。 -如果 ReMe 运行在其他环境，请执行 `python3 -m pip install "fastmcp>=3.4.2"`。插件不会启动 ReMe 服务。 -原生表单遵循固定版本的 -[OpenAI MCP Extensions 设置协议](https://github.com/openai/mcp-extensions/blob/node-v0.1.0/docs/spec.md#structured-settings)。 -不支持该扩展的宿主仍可使用工具和 Hook，但不会显示原生设置表单。 +修改 `mcp_url` 不会把旧队列中的对话发往新服务；切回原地址后可以继续重试。 +旧 `api_url` 字段仍可读取，但不再使用，下次界面保存时会移除。标准 `/mcp` 的队列标识保持兼容， +自定义旧 HTTP 地址下的队列原样保留。 -## 生命周期与失败行为 +## 常见问题 -- `UserPromptSubmit` 在短超时范围内同步调用 `search`，用 `` 包裹有长度限制的结果，明确其为不可信历史数据。失败不阻止用户消息。 -- 同步 `Stop` Hook 从本地 transcript 提取完成轮次的用户与最终助手文本，通过 MCP 分批调用 `auto_memory`。工具输出、推理内容和注入的 ReMe 上下文不作为对话来源。服务端无需读取宿主文件。 -- 使用带宿主命名空间的稳定会话和消息 ID，重复 Stop 去重；每个会话串行提交，跨日拆分批次。排除子 Agent 事件和 Hook 续写。插件不启动独立守护进程，也不自动下载依赖或启动 ReMe。 -- 队列与确认收据保存在宿主的 `reme/queue/`，按服务地址隔离；失败或超时不会丢弃队列。`SessionStart` 同步重试，`SessionEnd` 在短时间预算内同步尝试刷新。 -- 退出刷新是尽力而为：宿主在捕获前被强制结束时可能丢失该轮。MCP 确认丢失时可能重复提取；稳定消息 ID 避免重复存储来源，但记忆提取是至少一次语义。未满批次或未及时完成的任务留待下次会话处理。 -- 队列包含原始对话文本，请在交付完成前保留。`reme/hooks.log` 仅记录事件及异常类型。关闭 `auto_memory` 保留队列且停止重试。 -- `auto_dream` 整理继续由 ReMe 服务管理。与 OpenClaw 常驻 Gateway 不同，短生命周期 Hook 不另建定时调度器。 +按**服务连接 → Hook 状态 → 记录 → 新会话召回**的顺序排查。 -Codex 0.145.0 会跳过设置了 `async` 的 hook，因此本适配器使用同步 hook。达到批次阈值时的写入和启动时的重试，最多会等待 `request_timeout` 秒；Claude Code 则使用其独立的原生异步适配器。 +| 现象 | 检查或处理 | +| --- | --- | +| 找不到 ReMe 设置 | 打开已安装插件的 `reme` MCP 卡片 → **Open MCP settings**，确认宿主支持原生表单且 MCP 进程启动成功。 | +| Check connection 转圈后没有聊天回复 | 将鼠标停在按钮上查看提示浮层；ReMe 版本与 `healthy` 表示服务检查成功。 | +| 连接 healthy，但记录和召回都没发生 | 检查四个 ReMe Hook 是否均已加载、启用且信任。安装插件和连接健康不会自动授予 Hook 信任。 | +| Hook 列表中没有 ReMe | 更新仓库，重新安装插件并重启宿主；兼容性说明见下文。 | +| Hook 已列出但等待审核 | 审核并信任当前定义，再新建会话。 | +| `hook_failed` 或 MCP 启动失败 | 检查宿主的 Python 3.11+/FastMCP 环境、保存的配置、服务连通性和 ReMe 服务端日志。 | +| 对话一轮后没有笔记 | 设 `memory_interval=1`，开启 `auto_memory`，等待最终回复及 Stop Hook。ReMe 还需要可用的记忆提取模型。 | +| `capture_skipped` | 升级到当前插件。记录需要本地 transcript 和最终助手消息；当前支持新旧 Codex 对话事件格式。 | +| `retry_failed` 或存在待提交队列 | 恢复原服务及模型连接，新建会话触发重试，保留待提交文件。 | +| 已有笔记，但新会话没有召回 | 开启 `auto_recall`，核对地址和工作区，等待索引更新，检查召回数量及分数过滤。可显式调用 ReMe 搜索，区分检索问题和 Hook 问题。 | -## 验证与排查 +日志只记录状态和异常类型，不记录对话内容。成功召回或空闲 Hook 不一定写日志； +仅凭 `hooks.log` 不存在，不能判断 Hook 从未执行。队列文件则包含来源对话文本。 -1. 在 `/hooks` 中确认 ReMe 的四个 Hook 均已加载、启用且信任，再在 MCP 设置中点击 - **Check connection**。健康结果只验证服务连接，不代表 Hook 已加载或执行。 -2. 快速验证时把 `memory_interval` 设为 `1`，新建会话，要求记住一条合成事实，例如“Juniper 项目每周四评审”。 -3. 等待写入，检查 `reme/hooks.log` 的 `memory_saved`，以及 ReMe workspace 的 `daily/` 笔记。 -4. 再新建一个独立会话，询问该事实，并确认回答附有 ReMe 来源路径。 +## 记忆行为与兼容性 -自动记忆和显式检索、阅读、健康检查均由已安装的插件提供。工具缺失时，检查插件是否已安装并启用、 -ReMe 服务是否运行，以及 `service.jobs` 是否开放所需 Job。`/hooks` 中没有 ReMe 时，重新安装当前插件并 -重启宿主；已列出但待审核时，信任当前 Hook 定义。已信任的 Hook 执行失败时，检查 Hook 环境中的 -`python3` 是否为 Python 3.11+，并已安装 FastMCP。 +- 召回内容有长度上限，以 `` 包裹并标为不可信历史证据。 + 只记录完成轮次的用户与最终助手文本；排除工具输出、推理、子 Agent、中间回复和注入的记忆。 + ReMe 不需要访问 Codex 的 transcript 文件。 +- 稳定的会话／消息 ID、会话锁和收据避免重复 Stop 再次交付同一条来源消息。 + 写入失败时，队列按服务地址及会话保留。 +- 为兼容会跳过异步 Hook 的 Codex 0.145.0，插件采用同步 Hook。 + 达到批次条件或启动重试时，可能等待至 `request_timeout`。退出时仅尽力刷新，剩余批次留待下一会话。 +- 交付是尽力而为，记忆提取采用至少一次语义。宿主在捕获前被强制结束可能丢失该轮； + 确认响应丢失可能导致再次提取。 +- 持久记忆和每日整理由 ReMe 服务管理，插件不启动额外守护进程或调度器。 -记录要求 Hook 提供 `transcript_path` 和 `last_assistant_message`，读取 rollout 的 `event_msg`： -旧版 `user_message` / 最终 `agent_message`，以及新版 `item_completed` 中的 -`UserMessage` / 最终 `AgentMessage` 文本块。排除 `response_item` 中的注入上下文和重复消息，不读取私有推理。 -Codex transcript 不是稳定公开接口；未知格式或缺失文件会跳过并记录状态，不猜测对话。 -召回正常但未记录时，检查 `capture_skipped`、`hook_failed`。 +插件采用 `.codex-plugin/plugin.json` 与 `.mcp.json` 布局。原生验证发现，Codex 0.159.2 和 +桌面运行时 0.158.0-alpha.2.1 在存在根目录 portable `plugin.json` 时会遗漏本插件的 Hook， +显式声明也无效，因此保留当前 Codex 布局。解析器同时支持旧版 `user_message` / 最终 `agent_message` +和新版 `item_completed` 对话事件，排除 `response_item`。实现见 [Hook 适配器](plugins/reme/hooks/auto_memory.py)。 -在 Codex 0.145.0 中，无人值守的 `codex exec` 无法收集工具审批时，MCP 调用可能返回 `user cancelled MCP tool call`。请在交互会话中批准具体调用来验证显式工具。已信任的自动 Hook 自身作为 MCP 客户端调用服务，不逐次请求模型工具审批。 +CLI 0.145.0 无人值守会话无法收集显式工具调用审批时，可能返回 `user cancelled MCP tool call`。 +请在交互会话中验证这类调用；自动 Hook 使用前文所述的信任审核机制。 -## 源码与验证 +## 维护者验证 -在 ReMe 仓库运行 `pytest tests/unit/test_coding_agent_plugins.py tests/unit/test_codex_plugin_mcp.py -v`。测试使用隔离目录和模拟服务。 -使用支持 `hooks/list` 的运行时，执行 -`REME_CODEX_BIN=/path/to/codex pytest tests/integration/test_codex_plugin_install.py -v`， -可在隔离配置目录安装插件，验证信任前的 Hook 发现行为，不调用模型或执行 Hook。 -宿主行为以 [Codex Hook 文档](https://learn.chatgpt.com/docs/hooks) 为准。 +五个真实截图槽位及替换方式见[截图清单](./figures/README.md)。中英文说明共用同一组 PNG； +补图前保留文字槽位，不显示缺失图片。 + +```bash +pytest tests/unit/test_coding_agent_plugins.py tests/unit/test_codex_plugin_mcp.py -v +REME_CODEX_BIN=/path/to/codex pytest tests/integration/test_codex_plugin_install.py -v +``` + +原生安装测试需要运行时支持 `hooks/list`，使用隔离配置目录，验证信任前的四个 Hook 发现行为， +不调用模型或执行 Hook。文档修改后，在 `github-pages/` 运行 `npm test` 和 `npm run build`。 + +参考：[Codex Hook 文档](https://learn.chatgpt.com/docs/hooks)、 +[OpenAI MCP 设置协议](https://github.com/openai/mcp-extensions/blob/node-v0.1.0/docs/spec.md#structured-settings)。 ReMe 在 [agentscope-ai/ReMe](https://github.com/agentscope-ai/ReMe) 开发，采用 Apache-2.0 许可证。 diff --git a/integrations/codex/figures/README.md b/integrations/codex/figures/README.md new file mode 100644 index 00000000..78ef87ac --- /dev/null +++ b/integrations/codex/figures/README.md @@ -0,0 +1,33 @@ +# Codex screenshot checklist / 截图清单 + +Use real Codex screenshots only. The English and Chinese guides share these PNG files. +仅使用真实 Codex 界面截图；中英文说明共用以下 PNG 文件，不使用示意图或重绘的界面。 + +| Filename / 文件名 | Capture / 拍摄内容 | +| --- | --- | +| `plugin-installed.png` | Installed ReMe plugin detail: name, enabled state, and `reme` MCP card. / 已安装的 ReMe 插件详情：名称、启用状态及 MCP 卡片。 | +| `hooks-trusted.png` | All four ReMe hooks enabled and trusted, in desktop settings or CLI `/hooks`. / 四个 ReMe Hook 均已启用、已信任，可使用桌面设置或 CLI。 | +| `mcp-settings.png` | Native MCP form: URL, auto switches, batch size, and successful Check connection tooltip. / 原生 MCP 表单：地址、自动开关、批次大小及连接健康浮层。 | +| `memory-recorded.png` | Conversation A: the test fact and final acknowledgement, without explicit tool calls. / 会话 A：测试事实及最终确认，不显式调用工具。 | +| `memory-recalled.png` | Separate conversation B: recall question, correct fact, and ReMe source path. / 独立会话 B：召回问题、正确事实和 ReMe 来源路径。 | + +## Add the screenshots / 补图步骤 + +1. Save the original PNG files in this directory using the names above. Keep text readable; + include enough of the Codex interface to identify the page. Crop unrelated conversations and account details. + 将 PNG 原图按以上文件名放入本目录，保持文字清晰并保留可辨认的 Codex 界面，裁去无关对话和账号信息。 +2. In both `../README.md` and `../README_ZH.md`, find the matching screenshot placeholder, + remove its visible blockquote, and remove the `` around the image line. + 在两份说明中找到对应槽位，删除可见的占位引用块，并移除图片行外的 HTML 注释标记。 +3. Keep the Markdown image path relative, such as `./figures/mcp-settings.png`. + The documentation build copies these files and rewrites the path for the website. + 保留相对图片路径；文档构建会复制图片并转换为站点路径。 +4. From `github-pages/`, run `npm test` and `npm run build`, then preview both language pages. + 在 `github-pages/` 执行上述检查，并预览中英文页面。 + +Use the same unique test project and facts for both conversation screenshots. Keep the +connection, trust, and memory checks separate: an acknowledgement alone does not prove a successful write. +两张对话截图使用同一组独立测试事实。连接健康、Hook 信任和记忆交付分别验证；仅有确认回复不能证明写入成功。 + +MCP settings require a desktop host that supports the native form; a CLI capture cannot substitute for this image. +MCP 设置图需在支持原生表单的桌面宿主中截取，不能用 CLI 输出代替。