Skip to content

Commit 67f55c8

Browse files
ranxiangleiranxianglei
authored
Merge pull request #363 from ranxianglei/2026-09-04_readme-which-do-i-need
docs: add "Which do I need?" section to READMEs (EN+ZH)
2 parents 7a36180 + 4f68e39 commit 67f55c8

4 files changed

Lines changed: 147 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,19 @@ This brings two concrete effects:
4141

4242
---
4343

44+
## Which do I need?
45+
46+
Pick by your client:
47+
48+
| Client | Use |
49+
|---|---|
50+
| **pi** | [`billion-context-pi`](https://github.com/ranxianglei/billion-context-pi) (in-process extension) |
51+
| **opencode** | [`opencode-acp`](https://github.com/ranxianglei/opencode-acp) (in-process extension) |
52+
| **omp** | [`billion-context`](https://github.com/ranxianglei/billion-context) via `bili omp` (built-in plugin) |
53+
| **everything else** (no context hook) | [`billion-context`](https://github.com/ranxianglei/billion-context) — `bili <client>` (launcher, preferred) or `/bili/` prefix |
54+
55+
---
56+
4457
## Proven at scale
4558

4659
Real engineering context, in practice.

‎README.zh-CN.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,19 @@ ACP 将上下文管理的所有权限全部交给模型自己，而不依靠外
3333

3434
---
3535

36+
## 该选哪个?
37+
38+
按客户端选:
39+
40+
| 客户端 | 用这个 |
41+
|---|---|
42+
| **pi** | [`billion-context-pi`](https://github.com/ranxianglei/billion-context-pi)(进程内扩展) |
43+
| **opencode** | [`opencode-acp`](https://github.com/ranxianglei/opencode-acp)(进程内扩展) |
44+
| **omp** | [`billion-context`](https://github.com/ranxianglei/billion-context),`bili omp`(内置插件) |
45+
| **其余所有**(没有上下文 hook) | [`billion-context`](https://github.com/ranxianglei/billion-context) —— `bili <client>`(启动器,优先)或 `/bili/` 前缀 |
46+
47+
---
48+
3649
## 实战验证
3750

3851
真实工程中的上下文情况。

‎devlog/2026-09-04_readme-which-do-i-need/REQ.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# REQ - README 增加「该选哪个?」一节
2+
3+
- Task ID: `2026-09-04_readme-which-do-i-need`
4+
- Home Repo: `opencode-acp`
5+
- Created: 2026-09-04
6+
- Status: Done
7+
- Priority: P2
8+
- Owner: ranxianglei
9+
- References: https://github.com/ranxianglei/opencode-acp/issues/362 · 来源 ranxianglei/billion-context#511(同节已在 billion-context PR #512 定稿)
10+
11+
## 1. Background & Problem Statement
12+
13+
- **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 也加同一节,跨仓库保持一致、方便用户互相跳转。
14+
- **Current behavior (symptom)**: `opencode-acp` 的 `README.md` / `README.zh-CN.md` 目前没有这一节。
15+
- **Expected behavior**: 两个 README 各加一节「Which do I need? / 该选哪个?」,内容为 owner 在 #511 中定稿的四行表格(pi / opencode / omp / 其余所有),每个项目带各自 GitHub 链接。位置:**放在「## Why ACP / ## 为什么选择 ACP」之后**(2026-09-05 owner 修订;最初要求放在 Installation 之前)。
16+
- **Impact**: 纯文档;用户跨仓库选型时可互相跳转,口径统一。
17+
- **修订记录**: 2026-09-05 owner 反馈「放在 为什么选择 ACP 后面吧」——节位置由「## Installation 之前」改为「## Why ACP / ## 为什么选择 ACP 之后」。表格内容不变(仍与 billion-context 逐字一致)。
18+
19+
## 2. Reproduction (if applicable)
20+
21+
不适用(文档改动)。
22+
23+
## 3. Constraints & Non-Goals
24+
25+
- **Constraints**:
26+
- Backward compatibility: 不涉及代码/状态/配置,无兼容性影响。
27+
- 内容必须与 billion-context README(PR #512 落定版)逐字一致(表格 + GitHub 链接),只按本仓库风格补 `---` 分隔线。
28+
- EN/ZH 两个 README 同步修改。
29+
- 不动 `package.json` version。
30+
- **Non-Goals**:
31+
- 不解释三者原理/关系(billion-context 侧已删掉冗长解释,owner 明确「只需说什么时候选什么即可」)。
32+
- 不改其他章节。
33+
34+
## 4. Acceptance Criteria (must be testable)
35+
36+
- **Correctness**:
37+
- [x] `README.md` 在「## Why ACP」之后新增「## Which do I need?」节,表格四行(pi / opencode / omp / everything else),每个项目带 GitHub 链接
38+
- [x] `README.zh-CN.md` 在「## 为什么选择 ACP」之后新增「## 该选哪个?」节,内容与 EN 对应、与 billion-context ZH README 一致
39+
- [x] 表格内容与 billion-context master README 中已合入的同节逐字一致
40+
- **Performance / Stability**: 不适用
41+
- **Regression**:
42+
- [ ] 无源码改动,typecheck/build/test 不受影响(仍跑一次确认)
43+
44+
## 5. Proposed Approach (optional)
45+
46+
- **Affected modules & entry files**:
47+
- `README.md`(EN)
48+
- `README.zh-CN.md`(ZH)
49+
- `devlog/2026-09-04_readme-which-do-i-need/`(本目录)
50+
- **Risks**: 无(纯 markdown)。
51+
- **Rollback strategy**: revert 单个 commit。

‎devlog/2026-09-04_readme-which-do-i-need/WORKLOG.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# WORKLOG - README 增加「该选哪个?」一节(EN+ZH)
2+
3+
- Task ID: `2026-09-04_readme-which-do-i-need`
4+
- Home Repo: `opencode-acp`
5+
- Status: Done
6+
- Updated: 2026-09-05
7+
8+
## 1. Summary
9+
10+
- **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 链接。
11+
- **Why** (1–3 sentences): 三个包(billion-context / billion-context-pi / opencode-acp)经常被一起问「我该怎么选」。billion-context README 已有同节(PR #512),owner 要求跨仓库保持一致、方便用户互相跳转(issue #362)。
12+
- **Behavior / compatibility changes**: No — 纯文档改动,不涉及代码、状态格式、配置或内部命名。
13+
- **Risk level**: Low
14+
15+
## 2. Change Log
16+
17+
### Commits
18+
19+
| Commit | Description |
20+
|--------|-------------|
21+
| `6fd6875` | docs: add "Which do I need?" section to READMEs (EN+ZH) |
22+
| _(this commit)_ | docs: move "Which do I need?" section to after "Why ACP" (owner feedback, #363) |
23+
24+
### Key Files
25+
26+
- `README.md` — 「## Why ACP」与「## Proven at scale」之间插入「## Which do I need?」节(按本仓库风格以 `---` 分隔)。
27+
- `README.zh-CN.md` — 「为什么选择 ACP」与「实战验证」之间插入「## 该选哪个?」节,内容与 EN 对应。
28+
- `devlog/2026-09-04_readme-which-do-i-need/REQ.md` — 需求记录。
29+
30+
## 3. Design & Implementation Notes
31+
32+
- **表格内容来源**: 与 billion-context master `README.md` L115-124 / `README.zh-CN.md` L53-62 已合入的同节逐字一致(通过 GitHub API 核对);仅在本仓库中补了 `---` 分隔线以匹配本仓库章节排版。
33+
- **位置**: 最初按 issue 放在「## Installation」之前;2026-09-05 owner 反馈「放在 为什么选择 ACP 后面吧」,改为放在「## Why ACP / ## 为什么选择 ACP」之后(先让读者选到正确的包,再看实战数据与安装)。表格内容不受影响,仍与 billion-context 逐字一致(billion-context 无 Why 章节,结构不同,故不强求绝对位置对齐)。
34+
- **口径**: 只回答「什么时候选什么」,不展开三者原理/关系 —— owner 在 #511 floor 9 明确「写的太啰嗦…只需说什么时候选什么即可」,floor 13 确认精简版「这个可以了」。
35+
36+
## 4. Testing & Verification
37+
38+
### Build & Test Commands
39+
40+
```sh
41+
npm run typecheck # pass
42+
npm run build # pass (dist/index.js 425.45 KB)
43+
npm run test # 1077 pass / 0 fail
44+
```
45+
46+
### Test Coverage
47+
48+
- New/modified test files: 无(纯 markdown,无源码改动)
49+
- Test count: 1077 total, 1077 pass, 0 fail(全量回归确认无副作用)
50+
51+
### Results
52+
53+
- **PASS/FAIL**: PASS
54+
- Markdown 结构核对: EN/ZH 两节均位于 Why ACP / 为什么选择 ACP 之后、Proven at scale / 实战验证 之前;表格四行完整;四个 GitHub 链接齐全;无重复 `---`。
55+
56+
## 5. Risk Assessment & Rollback
57+
58+
- **Risk points**: 无。
59+
- **Rollback method**:
60+
- Revert commit(s): 本 PR 的单个 docs commit
61+
- Rollback impact: 无
62+
- **Compatibility notes** (data format, config schema): No
63+
64+
## 6. Lessons Learned (optional)
65+
66+
- 跨仓库同步文案时,直接通过 GitHub API(`Accept: application/vnd.github.raw+json`)拉取对方 master 的已合入版本做逐字比对,比凭 issue 正文更可靠(raw.githubusercontent.com 在本环境不可达,api.github.com 可达)。
67+
68+
## 7. Follow-ups (optional)
69+
70+
- [ ] billion-context-pi 侧的同款 issue(ranxianglei/billion-context-pi#290)由该仓库的 agent 处理,不在本 PR 范围。

0 commit comments

Comments
 (0)