From 6fd6875be52f474d298ff72a781db691126b260e Mon Sep 17 00:00:00 2001 From: ework-agent Date: Fri, 4 Sep 2026 14:22:39 +0800 Subject: [PATCH 1/3] docs: add "Which do I need?" section to READMEs (EN+ZH) Add the cross-repo client-selection table (pi / opencode / omp / everything else) before "## Installation" in both READMEs, matching the section finalized in ranxianglei/billion-context#511 (PR #512) so all three package READMEs stay consistent. Each project links to its own GitHub repo. Pure docs change; no code, state, or config impact. Fixes #362 --- README.md | 13 ++++ README.zh-CN.md | 13 ++++ .../2026-09-04_readme-which-do-i-need/REQ.md | 50 ++++++++++++++ .../WORKLOG.md | 69 +++++++++++++++++++ 4 files changed, 145 insertions(+) create mode 100644 devlog/2026-09-04_readme-which-do-i-need/REQ.md create mode 100644 devlog/2026-09-04_readme-which-do-i-need/WORKLOG.md diff --git a/README.md b/README.md index d859840b..873d0962 100644 --- a/README.md +++ b/README.md @@ -67,6 +67,19 @@ across all other sessions. --- +## Which do I need? + +Pick by your client: + +| Client | Use | +|---|---| +| **pi** | [`billion-context-pi`](https://github.com/ranxianglei/billion-context-pi) (in-process extension) | +| **opencode** | [`opencode-acp`](https://github.com/ranxianglei/opencode-acp) (in-process extension) | +| **omp** | [`billion-context`](https://github.com/ranxianglei/billion-context) via `bili omp` (built-in plugin) | +| **everything else** (no context hook) | [`billion-context`](https://github.com/ranxianglei/billion-context) — `bili ` (launcher, preferred) or `/bili/` prefix | + +--- + ## Installation ```bash diff --git a/README.zh-CN.md b/README.zh-CN.md index 54c38a6e..c4b45b92 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -54,6 +54,19 @@ ACP 将上下文管理的所有权限全部交给模型自己，而不依靠外 --- +## 该选哪个? + +按客户端选: + +| 客户端 | 用这个 | +|---|---| +| **pi** | [`billion-context-pi`](https://github.com/ranxianglei/billion-context-pi)(进程内扩展) | +| **opencode** | [`opencode-acp`](https://github.com/ranxianglei/opencode-acp)(进程内扩展) | +| **omp** | [`billion-context`](https://github.com/ranxianglei/billion-context),`bili omp`(内置插件) | +| **其余所有**(没有上下文 hook) | [`billion-context`](https://github.com/ranxianglei/billion-context) —— `bili `(启动器,优先)或 `/bili/` 前缀 | + +--- + ## 安装 ```bash diff --git a/devlog/2026-09-04_readme-which-do-i-need/REQ.md b/devlog/2026-09-04_readme-which-do-i-need/REQ.md new file mode 100644 index 00000000..17b873d1 --- /dev/null +++ b/devlog/2026-09-04_readme-which-do-i-need/REQ.md @@ -0,0 +1,50 @@ +# REQ - README 增加「该选哪个?」一节 + +- Task ID: `2026-09-04_readme-which-do-i-need` +- Home Repo: `opencode-acp` +- Created: 2026-09-04 +- Status: InProgress +- Priority: P2 +- Owner: ranxianglei +- References: https://github.com/ranxianglei/opencode-acp/issues/362 · 来源 ranxianglei/billion-context#511(同节已在 billion-context PR #512 定稿) + +## 1. Background & Problem Statement + +- **Context**: 三个包(`billion-context` / `billion-context-pi` / `opencode-acp`)经常被一起问「我该怎么选」。billion-context 的 README 已统一了一节「Which do I need? / 该选哪个?」(ranxianglei/billion-context#511),owner 要求 opencode-acp 与 billion-context-pi 的 README 也加同一节,跨仓库保持一致、方便用户互相跳转。 +- **Current behavior (symptom)**: `opencode-acp` 的 `README.md` / `README.zh-CN.md` 目前没有这一节。 +- **Expected behavior**: 两个 README 各加一节「Which do I need? / 该选哪个?」,放在「## Installation / ## 安装」之前(与 billion-context 的位置一致),内容为 owner 在 #511 中定稿的四行表格(pi / opencode / omp / 其余所有),每个项目带各自 GitHub 链接。 +- **Impact**: 纯文档;用户跨仓库选型时可互相跳转,口径统一。 + +## 2. Reproduction (if applicable) + +不适用(文档改动)。 + +## 3. Constraints & Non-Goals + +- **Constraints**: + - Backward compatibility: 不涉及代码/状态/配置,无兼容性影响。 + - 内容必须与 billion-context README(PR #512 落定版)逐字一致(表格 + GitHub 链接),只按本仓库风格补 `---` 分隔线。 + - EN/ZH 两个 README 同步修改。 + - 不动 `package.json` version。 +- **Non-Goals**: + - 不解释三者原理/关系(billion-context 侧已删掉冗长解释,owner 明确「只需说什么时候选什么即可」)。 + - 不改其他章节。 + +## 4. Acceptance Criteria (must be testable) + +- **Correctness**: + - [x] `README.md` 在「## Installation」之前新增「## Which do I need?」节,表格四行(pi / opencode / omp / everything else),每个项目带 GitHub 链接 + - [x] `README.zh-CN.md` 在「## 安装」之前新增「## 该选哪个?」节,内容与 EN 对应、与 billion-context ZH README 一致 + - [x] 表格内容与 billion-context master README 中已合入的同节逐字一致 +- **Performance / Stability**: 不适用 +- **Regression**: + - [ ] 无源码改动,typecheck/build/test 不受影响(仍跑一次确认) + +## 5. Proposed Approach (optional) + +- **Affected modules & entry files**: + - `README.md`(EN) + - `README.zh-CN.md`(ZH) + - `devlog/2026-09-04_readme-which-do-i-need/`(本目录) +- **Risks**: 无(纯 markdown)。 +- **Rollback strategy**: revert 单个 commit。 diff --git a/devlog/2026-09-04_readme-which-do-i-need/WORKLOG.md b/devlog/2026-09-04_readme-which-do-i-need/WORKLOG.md new file mode 100644 index 00000000..8feda2f6 --- /dev/null +++ b/devlog/2026-09-04_readme-which-do-i-need/WORKLOG.md @@ -0,0 +1,69 @@ +# WORKLOG - README 增加「该选哪个?」一节(EN+ZH) + +- Task ID: `2026-09-04_readme-which-do-i-need` +- Home Repo: `opencode-acp` +- Status: Done +- Updated: 2026-09-04 + +## 1. Summary + +- **What was done** (1–3 sentences): 在 `README.md` 与 `README.zh-CN.md` 各新增一节「Which do I need? / 该选哪个?」,放在「## Installation / ## 安装」之前。内容为 owner 在 ranxianglei/billion-context#511 中定稿的四行选型表(pi / opencode / omp / 其余所有),每个项目带各自 GitHub 链接。 +- **Why** (1–3 sentences): 三个包(billion-context / billion-context-pi / opencode-acp)经常被一起问「我该怎么选」。billion-context README 已有同节(PR #512),owner 要求跨仓库保持一致、方便用户互相跳转(issue #362)。 +- **Behavior / compatibility changes**: No — 纯文档改动,不涉及代码、状态格式、配置或内部命名。 +- **Risk level**: Low + +## 2. Change Log + +### Commits + +| Commit | Description | +|--------|-------------| +| _(见 PR)_ | docs: add "Which do I need?" section to READMEs (EN+ZH) | + +### Key Files + +- `README.md` — 「## Proven at scale」与「## Installation」之间插入「## Which do I need?」节(按本仓库风格以 `---` 分隔)。 +- `README.zh-CN.md` — 「实战验证」与「安装」之间插入「## 该选哪个?」节,内容与 EN 对应。 +- `devlog/2026-09-04_readme-which-do-i-need/REQ.md` — 需求记录。 + +## 3. Design & Implementation Notes + +- **表格内容来源**: 与 billion-context master `README.md` L115-124 / `README.zh-CN.md` L53-62 已合入的同节逐字一致(通过 GitHub API 核对);仅在本仓库中补了 `---` 分隔线以匹配本仓库章节排版。 +- **位置**: issue 明确要求放在「## Installation」之前(与 billion-context 的位置一致)。 +- **口径**: 只回答「什么时候选什么」,不展开三者原理/关系 —— owner 在 #511 floor 9 明确「写的太啰嗦…只需说什么时候选什么即可」,floor 13 确认精简版「这个可以了」。 + +## 4. Testing & Verification + +### Build & Test Commands + +```sh +npm run typecheck # pass +npm run build # pass (dist/index.js 425.45 KB) +npm run test # 1077 pass / 0 fail +``` + +### Test Coverage + +- New/modified test files: 无(纯 markdown,无源码改动) +- Test count: 1077 total, 1077 pass, 0 fail(全量回归确认无副作用) + +### Results + +- **PASS/FAIL**: PASS +- Markdown 结构核对: EN/ZH 两节均位于 Installation/安装 之前;表格四行完整;四个 GitHub 链接齐全。 + +## 5. Risk Assessment & Rollback + +- **Risk points**: 无。 +- **Rollback method**: + - Revert commit(s): 本 PR 的单个 docs commit + - Rollback impact: 无 +- **Compatibility notes** (data format, config schema): No + +## 6. Lessons Learned (optional) + +- 跨仓库同步文案时,直接通过 GitHub API(`Accept: application/vnd.github.raw+json`)拉取对方 master 的已合入版本做逐字比对,比凭 issue 正文更可靠(raw.githubusercontent.com 在本环境不可达,api.github.com 可达)。 + +## 7. Follow-ups (optional) + +- [ ] billion-context-pi 侧的同款 issue(ranxianglei/billion-context-pi#290)由该仓库的 agent 处理,不在本 PR 范围。 From 156660daa19a1cb480286e2e7b51a6f18c493c55 Mon Sep 17 00:00:00 2001 From: ework-agent Date: Fri, 4 Sep 2026 14:22:49 +0800 Subject: [PATCH 2/3] docs: record commit sha in WORKLOG for readme-which-do-i-need --- devlog/2026-09-04_readme-which-do-i-need/WORKLOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/devlog/2026-09-04_readme-which-do-i-need/WORKLOG.md b/devlog/2026-09-04_readme-which-do-i-need/WORKLOG.md index 8feda2f6..53b6a0e5 100644 --- a/devlog/2026-09-04_readme-which-do-i-need/WORKLOG.md +++ b/devlog/2026-09-04_readme-which-do-i-need/WORKLOG.md @@ -18,7 +18,7 @@ | Commit | Description | |--------|-------------| -| _(见 PR)_ | docs: add "Which do I need?" section to READMEs (EN+ZH) | +| `6fd6875` | docs: add "Which do I need?" section to READMEs (EN+ZH) | ### Key Files From 4f68e392caefc48ac179a26f69e696cbe5d72c05 Mon Sep 17 00:00:00 2001 From: ework-agent Date: Sat, 5 Sep 2026 09:16:47 +0800 Subject: [PATCH 3/3] docs: move "Which do I need?" section to after "Why ACP" --- README.md | 26 +++++++++---------- README.zh-CN.md | 26 +++++++++---------- .../2026-09-04_readme-which-do-i-need/REQ.md | 9 ++++--- .../WORKLOG.md | 13 +++++----- 4 files changed, 38 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 873d0962..4405f071 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,19 @@ This brings two concrete effects: --- +## Which do I need? + +Pick by your client: + +| Client | Use | +|---|---| +| **pi** | [`billion-context-pi`](https://github.com/ranxianglei/billion-context-pi) (in-process extension) | +| **opencode** | [`opencode-acp`](https://github.com/ranxianglei/opencode-acp) (in-process extension) | +| **omp** | [`billion-context`](https://github.com/ranxianglei/billion-context) via `bili omp` (built-in plugin) | +| **everything else** (no context hook) | [`billion-context`](https://github.com/ranxianglei/billion-context) — `bili ` (launcher, preferred) or `/bili/` prefix | + +--- + ## Proven at scale Real engineering context, in practice. @@ -67,19 +80,6 @@ across all other sessions. --- -## Which do I need? - -Pick by your client: - -| Client | Use | -|---|---| -| **pi** | [`billion-context-pi`](https://github.com/ranxianglei/billion-context-pi) (in-process extension) | -| **opencode** | [`opencode-acp`](https://github.com/ranxianglei/opencode-acp) (in-process extension) | -| **omp** | [`billion-context`](https://github.com/ranxianglei/billion-context) via `bili omp` (built-in plugin) | -| **everything else** (no context hook) | [`billion-context`](https://github.com/ranxianglei/billion-context) — `bili ` (launcher, preferred) or `/bili/` prefix | - ---- - ## Installation ```bash diff --git a/README.zh-CN.md b/README.zh-CN.md index c4b45b92..b95f9439 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -33,6 +33,19 @@ ACP 将上下文管理的所有权限全部交给模型自己，而不依靠外 --- +## 该选哪个? + +按客户端选: + +| 客户端 | 用这个 | +|---|---| +| **pi** | [`billion-context-pi`](https://github.com/ranxianglei/billion-context-pi)(进程内扩展) | +| **opencode** | [`opencode-acp`](https://github.com/ranxianglei/opencode-acp)(进程内扩展) | +| **omp** | [`billion-context`](https://github.com/ranxianglei/billion-context),`bili omp`(内置插件) | +| **其余所有**(没有上下文 hook) | [`billion-context`](https://github.com/ranxianglei/billion-context) —— `bili `(启动器,优先)或 `/bili/` 前缀 | + +--- + ## 实战验证 真实工程中的上下文情况。 @@ -54,19 +67,6 @@ ACP 将上下文管理的所有权限全部交给模型自己，而不依靠外 --- -## 该选哪个? - -按客户端选: - -| 客户端 | 用这个 | -|---|---| -| **pi** | [`billion-context-pi`](https://github.com/ranxianglei/billion-context-pi)(进程内扩展) | -| **opencode** | [`opencode-acp`](https://github.com/ranxianglei/opencode-acp)(进程内扩展) | -| **omp** | [`billion-context`](https://github.com/ranxianglei/billion-context),`bili omp`(内置插件) | -| **其余所有**(没有上下文 hook) | [`billion-context`](https://github.com/ranxianglei/billion-context) —— `bili `(启动器,优先)或 `/bili/` 前缀 | - ---- - ## 安装 ```bash diff --git a/devlog/2026-09-04_readme-which-do-i-need/REQ.md b/devlog/2026-09-04_readme-which-do-i-need/REQ.md index 17b873d1..cb7d0d29 100644 --- a/devlog/2026-09-04_readme-which-do-i-need/REQ.md +++ b/devlog/2026-09-04_readme-which-do-i-need/REQ.md @@ -3,7 +3,7 @@ - Task ID: `2026-09-04_readme-which-do-i-need` - Home Repo: `opencode-acp` - Created: 2026-09-04 -- Status: InProgress +- Status: Done - Priority: P2 - Owner: ranxianglei - References: https://github.com/ranxianglei/opencode-acp/issues/362 · 来源 ranxianglei/billion-context#511(同节已在 billion-context PR #512 定稿) @@ -12,8 +12,9 @@ - **Context**: 三个包(`billion-context` / `billion-context-pi` / `opencode-acp`)经常被一起问「我该怎么选」。billion-context 的 README 已统一了一节「Which do I need? / 该选哪个?」(ranxianglei/billion-context#511),owner 要求 opencode-acp 与 billion-context-pi 的 README 也加同一节,跨仓库保持一致、方便用户互相跳转。 - **Current behavior (symptom)**: `opencode-acp` 的 `README.md` / `README.zh-CN.md` 目前没有这一节。 -- **Expected behavior**: 两个 README 各加一节「Which do I need? / 该选哪个?」,放在「## Installation / ## 安装」之前(与 billion-context 的位置一致),内容为 owner 在 #511 中定稿的四行表格(pi / opencode / omp / 其余所有),每个项目带各自 GitHub 链接。 +- **Expected behavior**: 两个 README 各加一节「Which do I need? / 该选哪个?」,内容为 owner 在 #511 中定稿的四行表格(pi / opencode / omp / 其余所有),每个项目带各自 GitHub 链接。位置:**放在「## Why ACP / ## 为什么选择 ACP」之后**(2026-09-05 owner 修订;最初要求放在 Installation 之前)。 - **Impact**: 纯文档;用户跨仓库选型时可互相跳转,口径统一。 +- **修订记录**: 2026-09-05 owner 反馈「放在 为什么选择 ACP 后面吧」——节位置由「## Installation 之前」改为「## Why ACP / ## 为什么选择 ACP 之后」。表格内容不变(仍与 billion-context 逐字一致)。 ## 2. Reproduction (if applicable) @@ -33,8 +34,8 @@ ## 4. Acceptance Criteria (must be testable) - **Correctness**: - - [x] `README.md` 在「## Installation」之前新增「## Which do I need?」节,表格四行(pi / opencode / omp / everything else),每个项目带 GitHub 链接 - - [x] `README.zh-CN.md` 在「## 安装」之前新增「## 该选哪个?」节,内容与 EN 对应、与 billion-context ZH README 一致 + - [x] `README.md` 在「## Why ACP」之后新增「## Which do I need?」节,表格四行(pi / opencode / omp / everything else),每个项目带 GitHub 链接 + - [x] `README.zh-CN.md` 在「## 为什么选择 ACP」之后新增「## 该选哪个?」节,内容与 EN 对应、与 billion-context ZH README 一致 - [x] 表格内容与 billion-context master README 中已合入的同节逐字一致 - **Performance / Stability**: 不适用 - **Regression**: diff --git a/devlog/2026-09-04_readme-which-do-i-need/WORKLOG.md b/devlog/2026-09-04_readme-which-do-i-need/WORKLOG.md index 53b6a0e5..57942c95 100644 --- a/devlog/2026-09-04_readme-which-do-i-need/WORKLOG.md +++ b/devlog/2026-09-04_readme-which-do-i-need/WORKLOG.md @@ -3,11 +3,11 @@ - Task ID: `2026-09-04_readme-which-do-i-need` - Home Repo: `opencode-acp` - Status: Done -- Updated: 2026-09-04 +- Updated: 2026-09-05 ## 1. Summary -- **What was done** (1–3 sentences): 在 `README.md` 与 `README.zh-CN.md` 各新增一节「Which do I need? / 该选哪个?」,放在「## Installation / ## 安装」之前。内容为 owner 在 ranxianglei/billion-context#511 中定稿的四行选型表(pi / opencode / omp / 其余所有),每个项目带各自 GitHub 链接。 +- **What was done** (1–3 sentences): 在 `README.md` 与 `README.zh-CN.md` 各新增一节「Which do I need? / 该选哪个?」,放在「## Why ACP / ## 为什么选择 ACP」之后(2026-09-05 按 owner 反馈从最初的「Installation 之前」改到此处)。内容为 owner 在 ranxianglei/billion-context#511 中定稿的四行选型表(pi / opencode / omp / 其余所有),每个项目带各自 GitHub 链接。 - **Why** (1–3 sentences): 三个包(billion-context / billion-context-pi / opencode-acp)经常被一起问「我该怎么选」。billion-context README 已有同节(PR #512),owner 要求跨仓库保持一致、方便用户互相跳转(issue #362)。 - **Behavior / compatibility changes**: No — 纯文档改动,不涉及代码、状态格式、配置或内部命名。 - **Risk level**: Low @@ -19,17 +19,18 @@ | Commit | Description | |--------|-------------| | `6fd6875` | docs: add "Which do I need?" section to READMEs (EN+ZH) | +| _(this commit)_ | docs: move "Which do I need?" section to after "Why ACP" (owner feedback, #363) | ### Key Files -- `README.md` — 「## Proven at scale」与「## Installation」之间插入「## Which do I need?」节(按本仓库风格以 `---` 分隔)。 -- `README.zh-CN.md` — 「实战验证」与「安装」之间插入「## 该选哪个?」节,内容与 EN 对应。 +- `README.md` — 「## Why ACP」与「## Proven at scale」之间插入「## Which do I need?」节(按本仓库风格以 `---` 分隔)。 +- `README.zh-CN.md` — 「为什么选择 ACP」与「实战验证」之间插入「## 该选哪个?」节,内容与 EN 对应。 - `devlog/2026-09-04_readme-which-do-i-need/REQ.md` — 需求记录。 ## 3. Design & Implementation Notes - **表格内容来源**: 与 billion-context master `README.md` L115-124 / `README.zh-CN.md` L53-62 已合入的同节逐字一致(通过 GitHub API 核对);仅在本仓库中补了 `---` 分隔线以匹配本仓库章节排版。 -- **位置**: issue 明确要求放在「## Installation」之前(与 billion-context 的位置一致)。 +- **位置**: 最初按 issue 放在「## Installation」之前;2026-09-05 owner 反馈「放在 为什么选择 ACP 后面吧」,改为放在「## Why ACP / ## 为什么选择 ACP」之后(先让读者选到正确的包,再看实战数据与安装)。表格内容不受影响,仍与 billion-context 逐字一致(billion-context 无 Why 章节,结构不同,故不强求绝对位置对齐)。 - **口径**: 只回答「什么时候选什么」,不展开三者原理/关系 —— owner 在 #511 floor 9 明确「写的太啰嗦…只需说什么时候选什么即可」,floor 13 确认精简版「这个可以了」。 ## 4. Testing & Verification @@ -50,7 +51,7 @@ npm run test # 1077 pass / 0 fail ### Results - **PASS/FAIL**: PASS -- Markdown 结构核对: EN/ZH 两节均位于 Installation/安装 之前;表格四行完整;四个 GitHub 链接齐全。 +- Markdown 结构核对: EN/ZH 两节均位于 Why ACP / 为什么选择 ACP 之后、Proven at scale / 实战验证 之前;表格四行完整;四个 GitHub 链接齐全;无重复 `---`。 ## 5. Risk Assessment & Rollback