From 9096fd70061e605f41eda2bded599f3002217cc5 Mon Sep 17 00:00:00 2001 From: ework-agent Date: Wed, 9 Sep 2026 20:19:29 +0800 Subject: [PATCH 1/2] docs: add messageFilters config reference + examples (EN/ZH) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Issue #369 showed the default-on OMO message filters are undiscoverable. Add the missing messageFilters documentation: - CONFIGURATION.md / CONFIGURATION.zh-CN.md: new messageFilters section (enabled, filters, builtin filter table, example) + a tuning/disabling recipe in Common Config Recipes - README.md / README.zh-CN.md: messageFilters entry in the default-config block Docs only — no code changes. Verified defaults against source (lib/config.ts, lib/messages/filter/builtin/*). typecheck/build/test pass (1112/1112). --- CONFIGURATION.md | 67 +++++++++++++++++ CONFIGURATION.zh-CN.md | 67 +++++++++++++++++ README.md | 15 ++++ README.zh-CN.md | 14 ++++ devlog/2026-09-09_message-filters-docs/REQ.md | 51 +++++++++++++ .../WORKLOG.md | 71 +++++++++++++++++++ 6 files changed, 285 insertions(+) create mode 100644 devlog/2026-09-09_message-filters-docs/REQ.md create mode 100644 devlog/2026-09-09_message-filters-docs/WORKLOG.md diff --git a/CONFIGURATION.md b/CONFIGURATION.md index 9bb392a..dd9f323 100644 --- a/CONFIGURATION.md +++ b/CONFIGURATION.md @@ -453,6 +453,51 @@ Post-compression quality evaluation. Runs after each compression to verify summa --- +### `messageFilters` + +Message filters strip or deduplicate third-party plugin injections (e.g. oh-my-opencode system reminders, context dumps, task directives) from the visible context **before** ACP processes them. Filtered content never gets a message ref and is never counted toward context usage or compression triggers. + +Since v1.14.8, ACP ships five built-in oh-my-opencode (OMO) filters, all enabled by default: + +| Filter | Version | Behavior | +|--------|---------|----------| +| `omo-system-reminder` | 1.3.0 | Keeps the last 2 OMO `` messages; for older ones, strips the `` blocks and `` markers but preserves your actual user content | +| `omo-context` | 1.0.0 | Keeps only the latest OMO `[CONTEXT]` injection; drops earlier duplicates | +| `omo-task-directive` | 1.0.0 | Keeps only the latest OMO `TASK:` / `## TASK` directive; drops earlier ones | +| `omo-todo-continuation` | 1.0.0 | Keeps only the latest OMO TODO CONTINUATION directive; drops earlier ones | +| `omo-mode-injection` | 1.1.0 | Strips leading mode blocks (``, `[search-mode]`, …) and preserves user content | + +#### `messageFilters.enabled` +- **Type:** `boolean` +- **Default:** `true` +- **Status:** ACTIVE +- **Description:** Master switch. When `false`, no filters run. + +#### `messageFilters.filters` +- **Type:** `object` — `Record` +- **Default:** all built-in filters enabled +- **Status:** ACTIVE +- **Description:** Per-filter configuration. `enabled` toggles a single filter on/off. `keepLast` (dedup filters only) sets how many of the most recent matching messages to keep — default `1`, except `omo-system-reminder` which defaults to `2`. + +Example: + +```jsonc +{ + "messageFilters": { + "enabled": true, + "filters": { + "omo-system-reminder": { "enabled": true, "keepLast": 2 }, + "omo-context": { "enabled": true }, + "omo-task-directive": { "enabled": true }, + "omo-todo-continuation": { "enabled": true }, + "omo-mode-injection": { "enabled": true } + } + } +} +``` + +--- + ## Common Config Recipes ### Aggressive compression (maximize context savings) @@ -557,6 +602,28 @@ See the [`compress.providers`](#compressproviders) reference for the full overri } ``` +### Tune or disable oh-my-opencode (OMO) injection filters +The five built-in OMO filters are on by default (see [`messageFilters`](#messagefilters)). Keep more recent system-reminders, disable a single filter, or turn the whole subsystem off: +```jsonc +{ + "messageFilters": { + "enabled": true, + "filters": { + // keep the last 3 OMO system-reminders instead of 2 + "omo-system-reminder": { "enabled": true, "keepLast": 3 }, + // disable one filter, keep the rest + "omo-task-directive": { "enabled": false } + } + } +} +``` +```jsonc +{ + // turn all message filters off + "messageFilters": { "enabled": false } +} +``` + --- ## Removed Parameters diff --git a/CONFIGURATION.zh-CN.md b/CONFIGURATION.zh-CN.md index 955a5f7..dda8bdd 100644 --- a/CONFIGURATION.zh-CN.md +++ b/CONFIGURATION.zh-CN.md @@ -453,6 +453,51 @@ ACP 从最多三层配置文件中读取（后加载的覆盖先加载的）： --- +### `messageFilters` + +消息过滤器在 ACP 处理之前，从可见上下文中**剥离或去重**第三方插件注入的内容（例如 oh-my-opencode 的 system reminder、上下文转储、任务指令）。被过滤的内容不会获得消息引用（message ref），也不会计入上下文使用量或压缩触发阈值。 + +自 v1.14.8 起，ACP 内置了 5 个 oh-my-opencode（OMO）过滤器，全部默认启用： + +| 过滤器 | 版本 | 行为 | +|--------|------|------| +| `omo-system-reminder` | 1.3.0 | 保留最近 2 条 OMO `` 消息；更早的会剥离 `` 块和 `` 标记，但**保留你的实际用户内容** | +| `omo-context` | 1.0.0 | 只保留最新的 OMO `[CONTEXT]` 注入；丢弃更早的重复项 | +| `omo-task-directive` | 1.0.0 | 只保留最新的 OMO `TASK:` / `## TASK` 指令；丢弃更早的 | +| `omo-todo-continuation` | 1.0.0 | 只保留最新的 OMO TODO CONTINUATION 指令；丢弃更早的 | +| `omo-mode-injection` | 1.1.0 | 剥离开头的模式块（``、`[search-mode]` 等），保留用户内容 | + +#### `messageFilters.enabled` +- **类型：** `boolean` +- **默认值：** `true` +- **状态：** ACTIVE +- **说明：** 主开关。设为 `false` 时不运行任何过滤器。 + +#### `messageFilters.filters` +- **类型：** `object` — `Record` +- **默认值：** 所有内置过滤器启用 +- **状态：** ACTIVE +- **说明：** 按过滤器配置。`enabled` 单独开关某个过滤器；`keepLast`（仅去重类过滤器）设置保留最近多少条匹配消息——默认 `1`，`omo-system-reminder` 除外（默认 `2`）。 + +示例： + +```jsonc +{ + "messageFilters": { + "enabled": true, + "filters": { + "omo-system-reminder": { "enabled": true, "keepLast": 2 }, + "omo-context": { "enabled": true }, + "omo-task-directive": { "enabled": true }, + "omo-todo-continuation": { "enabled": true }, + "omo-mode-injection": { "enabled": true } + } + } +} +``` + +--- + ## 常用配置模板 ### 激进压缩（最大化上下文节省） @@ -557,6 +602,28 @@ ACP 从最多三层配置文件中读取（后加载的覆盖先加载的）： } ``` +### 调整或禁用 oh-my-opencode（OMO）注入过滤器 +5 个内置 OMO 过滤器默认开启（见 [`messageFilters`](#messagefilters)）。可以保留更多最近的 system-reminder、单独禁用某个过滤器，或整体关闭： +```jsonc +{ + "messageFilters": { + "enabled": true, + "filters": { + // 保留最近 3 条 OMO system-reminder（默认 2 条） + "omo-system-reminder": { "enabled": true, "keepLast": 3 }, + // 只禁用一个过滤器，其余保持 + "omo-task-directive": { "enabled": false } + } + } +} +``` +```jsonc +{ + // 关闭所有消息过滤器 + "messageFilters": { "enabled": false } +} +``` + --- ## 已移除的参数 diff --git a/README.md b/README.md index b80744d..ba6cdab 100644 --- a/README.md +++ b/README.md @@ -425,6 +425,21 @@ Each level overrides the previous, so project settings take priority over global }, }, }, + // Message filters — strip/deduplicate third-party plugin injections + // (e.g. oh-my-opencode system reminders) from visible context before + // ACP processes them. Filtered content is never counted toward context + // usage. Five built-in OMO filters are on by default (v1.14.8+); + // per-filter reference and examples: CONFIGURATION.md → messageFilters + "messageFilters": { + "enabled": true, + "filters": { + "omo-system-reminder": { "enabled": true }, + "omo-context": { "enabled": true }, + "omo-task-directive": { "enabled": true }, + "omo-todo-continuation": { "enabled": true }, + "omo-mode-injection": { "enabled": true }, + }, + }, } ``` diff --git a/README.zh-CN.md b/README.zh-CN.md index be560ce..8064b71 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -376,6 +376,20 @@ ACP 使用自己的配置文件，按以下顺序搜索： }, }, }, + // 消息过滤器——在 ACP 处理之前，从可见上下文中剥离/去重第三方插件注入 + // （例如 oh-my-opencode 的 system reminder）。被过滤的内容不计入上下文使用量。 + // 5 个内置 OMO 过滤器默认开启（v1.14.8+）； + // 按过滤器的参考与示例见 CONFIGURATION.zh-CN.md → messageFilters + "messageFilters": { + "enabled": true, + "filters": { + "omo-system-reminder": { "enabled": true }, + "omo-context": { "enabled": true }, + "omo-task-directive": { "enabled": true }, + "omo-todo-continuation": { "enabled": true }, + "omo-mode-injection": { "enabled": true }, + }, + }, } ``` diff --git a/devlog/2026-09-09_message-filters-docs/REQ.md b/devlog/2026-09-09_message-filters-docs/REQ.md new file mode 100644 index 0000000..7308a3e --- /dev/null +++ b/devlog/2026-09-09_message-filters-docs/REQ.md @@ -0,0 +1,51 @@ +# REQ - Document messageFilters config (EN + ZH) + +- Task ID: `2026-09-09_message-filters-docs` +- Home Repo: `opencode-acp` +- Created: 2026-09-09 +- Status: InProgress +- Priority: P2 +- Owner: ranxianglei +- References: https://github.com/ranxianglei/opencode-acp/issues/369 + +## 1. Background & Problem Statement + +- **Context**: ACP ships 5 built-in oh-my-opencode (OMO) message filters since v1.14.8 (PRs #239, #242, #268, #271), all enabled by default. Issue #369 asked how to safely remove OMO's redundant injected prompts — the answer is "already on by default, configurable via `messageFilters`". +- **Current behavior (symptom)**: The `messageFilters` config surface (master switch, per-filter `enabled`, per-filter `keepLast`) is completely undocumented — not in README.md, README.zh-CN.md, CONFIGURATION.md, or CONFIGURATION.zh-CN.md. A default-on feature is undiscoverable. +- **Expected behavior**: Users can find the `messageFilters` reference and copy-paste examples in both English and Chinese docs. +- **Impact**: Users of ACP + oh-my-opencode cannot discover/tune/disable the filters; support burden on issue tracker. + +## 2. Reproduction (if applicable) + +Not applicable — documentation gap, verified by grep: `messageFilters` appears in 0 of the 4 doc files. + +## 3. Constraints & Non-Goals + +- **Constraints**: + - Backward compatibility: docs-only change, no code changes. + - EN and ZH docs must stay in sync (same sections, same examples). + - All documented defaults/behaviors must match the source (`lib/config.ts` defaults, `lib/messages/filter/builtin/*`). +- **Non-Goals** (explicitly out of scope): + - No code changes, no new filters, no schema changes. + - Not fixing the pre-existing `layer1MinRetentionPct` doc inconsistency (README says 1.0, CONFIGURATION.md table says 5.0) — out of scope, noted separately. + +## 4. Acceptance Criteria (must be testable) + +- **Correctness**: + - [ ] `CONFIGURATION.md` has a `### messageFilters` section with `messageFilters.enabled`, `messageFilters.filters` reference + per-filter table + example + - [ ] `CONFIGURATION.zh-CN.md` has the same section translated + - [ ] `README.md` default-config block includes `messageFilters` + - [ ] `README.zh-CN.md` default-config block includes `messageFilters` + - [ ] At least one "Common Config Recipes" example (EN + ZH) showing tuning/disabling + - [ ] Documented defaults match source (enabled: true, 5 builtin filters, keepLast 2 for omo-system-reminder, 1 for the rest) +- **Performance / Stability**: N/A (docs only) +- **Regression**: + - [ ] `npm run typecheck`, `npm run build`, `npm run test` still pass (no code touched, sanity check) + +## 5. Proposed Approach (optional) + +- **Affected modules & entry files**: + - `CONFIGURATION.md`, `CONFIGURATION.zh-CN.md` — new `### messageFilters` section after `qualityGate` + recipe in "Common Config Recipes" + - `README.md`, `README.zh-CN.md` — `messageFilters` entry in the Default Configuration block +- **Risks**: None (docs only). Risk of documenting wrong defaults — mitigated by verifying against source before writing. +- **Rollback strategy**: Revert the single commit. diff --git a/devlog/2026-09-09_message-filters-docs/WORKLOG.md b/devlog/2026-09-09_message-filters-docs/WORKLOG.md new file mode 100644 index 0000000..96b138d --- /dev/null +++ b/devlog/2026-09-09_message-filters-docs/WORKLOG.md @@ -0,0 +1,71 @@ +# WORKLOG - Document messageFilters config (EN + ZH) + +- Task ID: `2026-09-09_message-filters-docs` +- Home Repo: `opencode-acp` +- Status: InProgress +- Updated: 2026-09-09 20:40 + +## 1. Summary + +- **What was done** (1–3 sentences): Added the missing `messageFilters` documentation — a full parameter reference section with per-filter table and config examples in CONFIGURATION.md / CONFIGURATION.zh-CN.md, plus a `messageFilters` entry in the default-config blocks of README.md / README.zh-CN.md. +- **Why** (1–3 sentences): Issue #369 showed the default-on OMO message filters are undiscoverable; the owner asked for config examples in both EN and ZH. +- **Behavior / compatibility changes**: No (docs only). +- **Risk level**: Low + +## 2. Change Log + +### Commits + +| Commit | Description | +|--------|-------------| +| `` | docs: add messageFilters config reference + examples (EN/ZH) | + +### Key Files + +- `CONFIGURATION.md` — new `### messageFilters` section (enabled, filters, builtin filter table, example) + recipe in Common Config Recipes +- `CONFIGURATION.zh-CN.md` — same, translated +- `README.md` — `messageFilters` entry in Default Configuration block +- `README.zh-CN.md` — same, translated + +## 3. Design & Implementation Notes + +- **Entry point / key function**: N/A (docs only) +- **Key configuration items**: `messageFilters.enabled` (default `true`), `messageFilters.filters..enabled`, `messageFilters.filters..keepLast` +- **Key logic explanation** (if non-trivial): Filters run before `assignMessageRefs` (lib/hooks.ts:237) — filtered content never gets message refs and is never counted toward context usage. `keepLast` is read at lib/messages/filter/apply.ts:115-116 as `Math.max(1, configValue ?? filterDefault ?? 1)`. + +## 4. Testing & Verification + +### Build & Test Commands + +```sh +npm run typecheck +npm run build +node --import tsx --test tests/*.test.ts +``` + +### Test Coverage + +- New/modified test files: none (docs only) +- Test count: 1112 total, 1112 pass, 0 fail +- Key scenarios verified: documented defaults cross-checked against `lib/config.ts:285-294` and `lib/messages/filter/builtin/*.ts` + +### Results + +- **PASS/FAIL**: PASS (typecheck, build, full test suite) +- **Key logs/data** (optional): `# pass 1112 / # fail 0`; tsup build success + +## 5. Risk Assessment & Rollback + +- **Risk points**: documenting wrong defaults (mitigated: verified against source) +- **Rollback method**: + - Revert commit(s): `` + - Rollback impact: docs revert only +- **Compatibility notes** (data format, config schema): No + +## 6. Lessons Learned (optional) + +- Default-on features must ship with docs in the same release — #369 shows the discovery gap. + +## 7. Follow-ups (optional) + +- [ ] Pre-existing inconsistency: `qualityGate.algorithms.rouge-recall-v1.layer1MinRetentionPct` documented as 5.0 in CONFIGURATION.md table but 1.0 in README default block — needs a separate fix. From a432ebdc29cfb2e249501bef2fb4886965f3d85f Mon Sep 17 00:00:00 2001 From: ework-agent Date: Wed, 9 Sep 2026 20:20:04 +0800 Subject: [PATCH 2/2] docs: mark worklog done --- devlog/2026-09-09_message-filters-docs/WORKLOG.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/devlog/2026-09-09_message-filters-docs/WORKLOG.md b/devlog/2026-09-09_message-filters-docs/WORKLOG.md index 96b138d..24d733b 100644 --- a/devlog/2026-09-09_message-filters-docs/WORKLOG.md +++ b/devlog/2026-09-09_message-filters-docs/WORKLOG.md @@ -2,8 +2,8 @@ - Task ID: `2026-09-09_message-filters-docs` - Home Repo: `opencode-acp` -- Status: InProgress -- Updated: 2026-09-09 20:40 +- Status: Done +- Updated: 2026-09-09 21:05 ## 1. Summary