diff --git a/integrations/codex/README.md b/integrations/codex/README.md index d20d163b..7dcfae82 100644 --- a/integrations/codex/README.md +++ b/integrations/codex/README.md @@ -96,7 +96,7 @@ that your service is running. Next, try recording and recalling a memory. > **Screenshot placeholder — `mcp-settings.png`:** Actual native form with the address, capture switches, batch size, and the single ReMe status entry. ## 4. Try your first memory @@ -171,10 +171,10 @@ Open **ReMe status** from MCP settings and choose the tab for what you want to c Click **Refresh** for an updated view. If you prefer a text answer, ask Codex: “Call `reme_status` and summarize my connection, pending memories, and next consolidation.” -> **Screenshot placeholder — `plugin-status.png`:** Real ReMe status panel or `reme_status` output with connection health, queued turns, recent activity, and the next Dream run. +> **Screenshot placeholder — `plugin-status.png`:** Real ReMe status panel on Auto Memory, with queued turns and Recent activity expanded to show saved and recalled memories. Change options in **Open MCP settings**, then save. New settings apply to subsequent activity; you do diff --git a/integrations/codex/README_ZH.md b/integrations/codex/README_ZH.md index a4b98c21..df6a963d 100644 --- a/integrations/codex/README_ZH.md +++ b/integrations/codex/README_ZH.md @@ -92,7 +92,7 @@ codex plugin add reme@reme-codex > **截图槽位 — `mcp-settings.png`：** 真实原生表单，保留服务地址、自动开关、批次大小及唯一的 ReMe status 入口。 ## 4. 记录并召回第一条记忆 @@ -165,10 +165,10 @@ ReMe-Example-7319 的评审时间和项目关键词是什么？ 点击 **刷新** 更新状态。也可以在对话中要求：“调用 `reme_status`，用文字告诉我连接状态、 待保存记忆和下次整理时间。” -> **截图槽位 — `plugin-status.png`：** 真实 ReMe status 面板或 `reme_status` 输出，保留连接健康、待提交轮数、最近活动和下次 Dream 时间。 +> **截图槽位 — `plugin-status.png`：** 真实 ReMe status 面板的自动记忆页签，保留待提交轮数，并展开最近活动展示保存和召回记录。 需要调整时，回到 **Open MCP settings** 修改并保存。新设置对后续活动生效，无需重新安装。 diff --git a/integrations/codex/figures/README.md b/integrations/codex/figures/README.md index d640b6c1..f373bbb6 100644 --- a/integrations/codex/figures/README.md +++ b/integrations/codex/figures/README.md @@ -1,34 +1,210 @@ -# Codex screenshot checklist / 截图清单 +# Codex manual screenshot workflow / 手动截图流程 -Use real Codex screenshots only. The English and Chinese guides share these PNG files. -仅使用真实 Codex 界面截图；中英文说明共用以下 PNG 文件，不使用示意图或重绘的界面。 +仅使用真实 Codex 界面截图。按下面的顺序完成六张必需截图，中英文使用说明共用同一组 PNG。 +截图槽位在收到对应图片前保留；无需为两种语言各拍一套。 -| Filename / 文件名 | Capture / 拍摄内容 | +Use real Codex screenshots only. Follow the capture order below; the English and Chinese guides share +the same six PNGs. Keep each placeholder until its corresponding screenshot is available. + +## 开始前 / Before capture + +1. 按[中文使用指南](../README_ZH.md)或[English guide](../README.md)完成服务启动和安装。 + 已安装时无需重新安装；先在 Codex 的已安装插件中确认 ReMe 已启用。 + Keep your ReMe service running and confirm the installed ReMe plugin is enabled. +2. 使用 **Codex CLI >= 0.159.2** 和 **Codex 桌面端 >= 26.924.22138**。 + 原生 MCP 设置和状态面板需在桌面端拍摄；Hook 页面可使用桌面端或 CLI `/hooks`。 + Use the desktop app for native MCP settings and the status panel; CLI `/hooks` is also valid for the Hook image. +3. 在启动 Codex 的同一环境中检查 Python。需要 Python 3.11+、FastMCP >= 3.4.2； + 若终端默认 Python 版本较低，先切换到已安装这些依赖的环境。 + Check Python in the environment used to launch Codex: + + ```bash + codex --version + python3 -c "import sys, fastmcp; print(sys.version); print(fastmcp.__version__)" + ``` + +4. 为两次测试对话选择一个空目录作为 Codex 项目，例如： + Use an empty Codex project for both test conversations: + + ```bash + mkdir -p "$HOME/reme-codex-demo" + ``` + + 在 Codex 中打开该目录作为项目；若这个目录已有内容，使用另一个新目录。 + Open that directory as a Codex project; choose a new directory name if it already contains files. + 两个会话连接**同一个 ReMe 服务和记忆工作区**，但会话 B 必须是新建会话，不能接续或分叉会话 A。 + 空目录用于避免 Codex 从仓库里的示例文档读取答案；它与 ReMe 的记忆工作区是不同目录。 + Both conversations use the same ReMe endpoint and memory workspace. Start B as a new conversation, + without continuing or branching A. An empty project keeps repository examples out of the answer. +5. 调整窗口宽度和字体，让截图中的文字清晰可读，保留足够的 Codex 界面以辨认页面。 + macOS 可用 `Shift + Command + 4` 手动框选区域，再将 PNG 重命名并移到本目录。 + 裁去无关对话、账号信息和凭据；使用适合公开展示的服务地址。 + Keep text readable and enough Codex UI to identify the page; crop unrelated conversations and account details. + +## 六张必需截图 / Six required captures + +| 顺序 / Order | 文件名 / Filename | 页面 / Page | 拍摄前确认 / Ready when | +| --- | --- | --- | --- | +| 1 | `plugin-installed.png` | 已安装的 ReMe 插件详情 / Installed ReMe details | ReMe 图标、名称、已启用状态及 `reme` MCP 卡片可见 / Icon, name, enabled state, and MCP card visible | +| 2 | `hooks-trusted.png` | Hooks 设置或 CLI `/hooks` / Hook review | 七个 ReMe 条目均已启用、已信任 / All seven ReMe entries enabled and trusted | +| 3 | `mcp-settings.png` | 原生 **Open MCP settings** 表单 / Native settings | 已保存地址、自动开关、批次大小；**ReMe status** 入口可见 / Saved address, switches, batch size, and status action visible | +| 4 | `memory-recorded.png` | 独立会话 A / Conversation A | 测试事实和回复可见，后台已出现 `memory_saved` / Fact and reply visible, recording confirmed | +| 5 | `memory-recalled.png` | 新建会话 B / New conversation B | 问题、正确时间、校验词和来源路径可见，已出现 `recall_found` / Answer, source path, and automatic recall confirmed | +| 6 | `plugin-status.png` | **ReMe status → 自动记忆 / Auto Memory** | 最近活动已展开，可见保存和召回记录，待提交轮数为零 / Activity expanded, saved/recalled events visible, queue zero | + +### 1. 已安装并启用 / Installed and enabled + +打开 Codex 的已安装插件列表，进入 **ReMe** 详情。确认已启用后，截取名称、图标、启用状态和 +`reme` MCP 卡片，保存为 `plugin-installed.png`。若缺少 MCP 卡片或设置入口，先检查版本、启用状态， +再重启客户端；页面未加载完成时先不要截图。 + +Open the installed ReMe details. Capture the icon, name, enabled state, and `reme` MCP card. +If the card or settings action is missing, check the version and enablement, then restart the app. + +### 2. 审核并信任 Hook / Review and trust Hooks + +进入 Hooks 设置，或在新 CLI 会话输入 `/hooks`。逐一审核 ReMe 条目，并由你在 Codex 中启用、信任。 +当前共七个条目：`UserPromptSubmit`、`SessionStart`、`SessionEnd` 各一个，`Stop` 和 `SubagentStop` 各两个。 +保存为 `hooks-trusted.png`，保留事件名、ReMe 来源及信任状态。 +若单页放不下，可另拍 `hooks-trusted-more.png`，按补图步骤在对应位置追加第二张图片。 + +Review and trust the seven ReMe entries yourself. Capture their event names, plugin source, and trust state. +Use a second image if the list does not fit legibly; do not shrink the text just to fit everything. + +### 3. 保存 MCP 设置并检查连接 / Save settings and check the connection + +在 ReMe 详情的 **reme MCP server** 卡片中点击 **Open MCP settings**，保存以下值： +Open the native MCP form and save these values: + +| 字段 / Field | 测试值 / Test value | | --- | --- | -| `plugin-installed.png` | Installed ReMe plugin detail: name, enabled state, and `reme` MCP card. / 已安装的 ReMe 插件详情：名称、启用状态及 MCP 卡片。 | -| `hooks-trusted.png` | All seven ReMe handlers across five events enabled and trusted, in desktop settings or CLI `/hooks`. / 五类事件下的七个 ReMe Hook 条目均已启用、已信任，可使用桌面设置或 CLI。 | -| `mcp-settings.png` | Native MCP form: URL, auto switches, batch size, and the single ReMe status entry. / 原生 MCP 表单：地址、自动开关、批次大小及唯一的 ReMe status 入口。 | -| `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 来源路径。 | -| `plugin-status.png` | ReMe status panel opened from native settings, or a real `reme_status` call in Codex: queued turns, recent activity, and the next Dream run. / 从原生设置打开的 ReMe status 面板或真实 Codex 对话中的 `reme_status` 调用，保留待提交轮数、最近活动和下次 Dream 时间。 | +| ReMe MCP address | 当前服务的真实可达地址 / Your actual reachable endpoint | +| Automatic recall | 开启 / On | +| Automatic memory capture | 开启 / On | +| Capture batch size | `1` | +| Memory guidance language | `zh` 或 / or `en` | -## Add the screenshots / 补图步骤 +点击 **ReMe status**，等 **总览 / Overview** 显示 **健康 / Healthy** 和 ReMe 版本。 +返回设置表单，截取地址、两项自动开关、批次大小及 **ReMe status** 入口，保存为 `mcp-settings.png`。 +若字段分布在不同滚动位置，可补拍 `mcp-settings-more.png`，保留可读字号。 -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/` 执行上述检查，并预览中英文页面。 +Wait for Healthy and the ReMe version in Overview, then return to the settings form for this capture. +Connection health confirms connectivity; the following steps separately verify recording and recall. -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 信任和记忆交付分别验证；仅有确认回复不能证明写入成功。 +### 4. 在会话 A 记录事实 / Record a fact in conversation A -MCP settings require a desktop host that supports the native form; a CLI capture cannot substitute for this image. -MCP 设置图需在支持原生表单的桌面宿主中截取，不能用 CLI 输出代替。 +在空项目中新建会话 A，发送下面的中文或英文提示。两次对话使用同一个项目名和校验词。 +若已经测试过 `7319`，先将两个提示里的后缀统一改成一个未使用过的值。 +不要额外请求调用 `auto_memory`，让自动记录完成本次验证。 + +Start A in the empty project. Choose one prompt below; change the suffix in both prompts if it was used before. +Let automatic capture save the turn rather than requesting an explicit `auto_memory` call. + +```text +请记住这个项目决策：ReMe-Example-7319 每周五 16:45 UTC 进行评审， +项目关键词是 amber-lynx-7319。 +``` + +```text +Remember this project decision: ReMe-Example-7319 reviews happen Friday +at 16:45 UTC. The project keyword is amber-lynx-7319. +``` + +回复完成后保持 Codex 和 ReMe 运行，打开 **ReMe status → 自动记忆 / Auto Memory → 最近活动 / Recent activity**。 +点击 **刷新 / Refresh**，等待 **记忆已保存 / Memory saved**（`memory_saved`），并确认 **待提交轮数 / Queued turns** 为 `0`。 +然后回到会话 A，截取提示和完整回复，保存为 `memory-recorded.png`。 + +Keep Codex and ReMe running until Memory saved appears and queued turns reach zero. Then capture A's prompt and reply. +An acknowledgement alone does not establish that recording succeeded. + +### 5. 在新会话 B 召回 / Recall in a new conversation B + +在同一个空项目中另建会话 B，不复制 A 的内容，不在问题中泄露时间和校验词。发送： +Start a separate conversation in the same empty project. Do not copy A's answer or include the fact in the question: + +```text +ReMe-Example-7319 的评审时间和项目关键词是什么？ +请根据 ReMe 记忆回答，并附上来源路径。 +``` + +```text +For ReMe-Example-7319, when are the reviews and what is the project keyword? +Use ReMe memory and include the source path in your answer. +``` + +确认回答包含 **每周五 16:45 UTC**、**amber-lynx-7319** 和真实的 ReMe 来源路径，例如 `daily/...md`。 +再检查最近活动中出现 **已召回相关记忆 / Relevant memory recalled**（`recall_found`）。 +答复正确且自动召回活动已确认后，截取 B 的问题、回答和来源路径，保存为 `memory-recalled.png`。 + +Expect Friday at 16:45 UTC, `amber-lynx-7319`, and a real ReMe source path. Also confirm Relevant memory recalled +in Recent activity. A correct answer alone does not establish that automatic recall ran. + +### 6. 展示状态面板 / Capture the status panel + +再次从原生设置打开 **ReMe status**，选择 **自动记忆 / Auto Memory**，点击刷新并展开 **最近活动 / Recent activity**。 +等待会话 B 的记录也保存完成、待提交轮数回到 `0`，再截取标题、页签、自动记录与召回状态及本次保存和召回活动， +保存为 `plugin-status.png`。 +在最近活动仍保留这两条记录时拍摄，避免继续发送无关测试消息。 + +Open the real status panel, select Auto Memory, refresh, and expand Recent activity. Capture the tabs, +automatic switches, zero pending turns after B is also saved, and the saved/recalled events before unrelated activity replaces them. + +状态面板的总览、自动记忆和记忆整理是不同页签，不需要把所有内容挤到一张图里。 +可另拍以下真实页面；没有开启每日计划时，显示暂停或没有计划是有效状态，无需为截图改动计划或执行整理。 +The tabs show different information. Optional captures below can show connection health and Dream separately; +a paused schedule is valid, so there is no need to enable or run consolidation just for a screenshot. + +| 可选文件 / Optional file | 内容 / Content | +| --- | --- | +| `plugin-status-overview.png` | **总览 / Overview** 中的健康状态、ReMe 版本和待提交轮数 / Health, version, and queue | +| `plugin-status-dream.png` | **记忆整理 / Consolidation** 中的 cron、时区、下次运行和最近结果 / Schedule, timezone, next run, and last result | + +## 遇到失败时 / If a step fails + +| 现象 / Symptom | 下一步 / Next step | +| --- | --- | +| 找不到设置入口 / Missing settings action | 检查版本、ReMe 已启用状态，再重启 Codex / Check version and enablement, then restart | +| 状态卡片为空或加载失败 / Empty or failed status card | 先按使用指南的网络排查步骤检查宿主沙箱连接；不要用浏览器仿制页面代替 / Follow the guide's network troubleshooting | +| 回复确认但没有 `memory_saved` / Acknowledged but not saved | 检查全部 Hook 信任、批次为 `1`、模型配置及服务日志；未保存前不进行 B / Check Hook trust, batch size, model setup, and logs before B | +| 答对但没有 `recall_found` / Correct answer without recall event | 检查 Automatic recall 和 Hook 信任，确认 B 是独立会话，再用新后缀重试 / Check recall, trust, and fresh conversation | + +## 保存图片并接入文档 / Save and add the images + +从仓库根目录看，所有 PNG 放在 `integrations/codex/figures/`；六个必需文件为： +Save the PNGs in this directory with these exact names: + +```text +integrations/codex/figures/ +├── plugin-installed.png +├── hooks-trusted.png +├── mcp-settings.png +├── memory-recorded.png +├── memory-recalled.png +└── plugin-status.png +``` + +图片保存好后即可交给维护者接入文档；若自行完成，对每张已存在的图片依次执行： +Once the files are ready, hand them off for integration, or make these changes yourself for each supplied image: + +1. 在 `../README.md` 和 `../README_ZH.md` 中找到同名截图槽位，删除对应的可见占位引用块。 + Remove its visible screenshot-placeholder blockquote in both guides. +2. 移除对应图片行外的 ``，保留相对路径。例如： + Uncomment the matching image line, keeping its relative path: + + ```markdown + ![ReMe MCP settings in Codex](./figures/mcp-settings.png) + ``` + +3. 缺少图片的槽位继续保留。可选补图放在相关必需图片后，在中英文说明中分别加上对应图片行。 + Leave missing-image slots intact. Add optional images after their related required image, with captions in each language. +4. 从仓库根目录执行以下检查，再打开预览中的中英文 Codex 页面，确认图片加载、文字清晰且排版正常： + Run these checks from the repository root, then inspect both Codex guide pages in the preview: + + ```bash + npm --prefix github-pages test + npm --prefix github-pages run build + npm --prefix github-pages run preview + ``` + +不要提交服务日志、对话导出文件、配置凭据或临时记忆工作区。只提交已审核的 PNG 和对应文档修改。 +Commit the reviewed PNGs and documentation changes; keep logs, transcript exports, credentials, and demo memory out of the commit.