Skip to content

Commit 0023d94

Browse files
Her-xanadusisyphus-dev-ai
Her-xanadu
and
sisyphus-dev-ai
committed
docs: prepare bilingual 1.0 release
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
1 parent e3af09a commit 0023d94

File tree

6 files changed

+358
-5
lines changed

6 files changed

+358
-5
lines changed

‎INSTALL.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# Installation and Upgrade Guide
2+
3+
This project is designed to work with a local OpenCode + oh-my-opencode setup while keeping the experiment controller as the stable authority path.
4+
5+
## Fastest Local Install
6+
7+
### 1. Install JavaScript dependencies
8+
9+
```bash
10+
npm ci
11+
```
12+
13+
### 2. Install Python dependencies for controller and DVC path
14+
15+
```bash
16+
python3 -m pip install "dvc>=3,<4" "dvclive>=3,<4"
17+
```
18+
19+
### 3. Install OpenCode and oh-my-opencode
20+
21+
```bash
22+
npm install -g opencode-ai oh-my-opencode
23+
```
24+
25+
### 4. Configure environment variables
26+
27+
```bash
28+
cp .env.example .env
29+
```
30+
31+
Fill in:
32+
33+
- `KIMI_CODING_API_KEY`
34+
- `KIMI_CODING_BASE_URL`
35+
- optionally `INNOVATION_LOOP_AGENT_MODEL`
36+
37+
### 5. Verify installation
38+
39+
```bash
40+
npm run build
41+
npm test
42+
npm run test:smoke
43+
```
44+
45+
## Recommended Local Usage
46+
47+
### Mock controller path
48+
49+
```bash
50+
python3 scripts/innovation_loop.py bootstrap --config configs/goal.yaml --workspace . --mode mock
51+
python3 scripts/innovation_loop.py tick --config configs/goal.yaml --workspace . --mode mock
52+
python3 scripts/innovation_loop.py status --config configs/goal.yaml --workspace . --mode mock
53+
```
54+
55+
### Research-brain daily maintenance
56+
57+
```bash
58+
python3 scripts/kb/run_maintenance_cycle.py --vault-root ../vault --workspace-root . --config configs/research_brain.yaml
59+
```
60+
61+
### Research context generation
62+
63+
```bash
64+
python3 scripts/kb/run_inference_cycle.py --workspace-root . --config configs/research_brain.yaml --round 1
65+
```
66+
67+
## Stable Upgrade Strategy
68+
69+
To keep the research system stable when OpenCode or oh-my-opencode changes, use this policy:
70+
71+
1. Treat `scripts/innovation_loop.py` as the authority path.
72+
2. Keep plugin-facing TS code as a bridge layer, not a second controller.
73+
3. After every OpenCode / oh-my-opencode upgrade, run:
74+
75+
```bash
76+
npm run build
77+
npm test
78+
npm run test:smoke
79+
```
80+
81+
4. If real DVC is available, also run:
82+
83+
```bash
84+
npm test -- tests/e2e/python-controller-real-dvc.test.ts
85+
```
86+
87+
5. Do not change `opencode.json` and agent model wiring casually during the same upgrade as controller logic.
88+
89+
## Safe Upgrade Workflow
90+
91+
```bash
92+
# 1. update tools
93+
npm install -g opencode-ai oh-my-opencode
94+
95+
# 2. refresh local JS deps if needed
96+
npm ci
97+
98+
# 3. rebuild and test
99+
npm run build
100+
npm test
101+
npm run test:smoke
102+
```
103+
104+
If any of those fail, do not continue with experiments until the controller path is green again.
105+
106+
## Compatibility Rule of Thumb
107+
108+
- OpenCode / oh-my-opencode may change outer surfaces.
109+
- This repository stays stable by keeping:
110+
- Python controller as truth source
111+
- structured artifacts in `experiments/`
112+
- research-brain scripts under `scripts/kb/`
113+
- TypeScript tools as adapters
114+
115+
As long as those boundaries remain intact, upgrades are usually manageable.

‎README.md‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
1-
# OpenCode Auto Experiment
1+
[English](./README.md) | [简体中文](./README.zh-CN.md)
22

3-
OpenCode Auto Experiment is an experiment-optimization loop for OpenCode + oh-my-opencode.
3+
# OpenCode Auto Research
4+
5+
OpenCode Auto Research is a governed autonomous experimentation framework with a local innovation brain for OpenCode + oh-my-opencode.
46

57
It is designed for research and engineering workflows where you want an outer orchestrator to:
68

@@ -144,6 +146,12 @@ python3 -m pip install "dvc>=3,<4" "dvclive>=3,<4"
144146
npm install -g opencode-ai oh-my-opencode
145147
```
146148

149+
Or use the local bootstrap script:
150+
151+
```bash
152+
bash scripts/install-local.sh
153+
```
154+
147155
### 5. Configure environment variables
148156

149157
Copy the example file:
@@ -157,6 +165,8 @@ Then set the required values for your model provider. For the current default Ki
157165
- `KIMI_CODING_API_KEY`
158166
- `KIMI_CODING_BASE_URL`
159167

168+
For a fuller installation and upgrade workflow, see `INSTALL.md`.
169+
160170
## Configuration
161171

162172
### Agent models

‎README.zh-CN.md‎

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
[English](./README.md) | [简体中文](./README.zh-CN.md)
2+
3+
# OpenCode Auto Research
4+
5+
OpenCode Auto Research 是一个面向 OpenCode + oh-my-opencode 的、本地优先（local-first）的受治理自动化实验与创新性科研大脑工程系统。
6+
7+
它的目标不是简单“自动跑实验”，而是把下面几条能力真正接进一个统一系统里：
8+
9+
- 自动 baseline / candidate / judge 实验循环
10+
- 三专家提案机制（Apollo / Athena / Hermes）
11+
- 本地论文库驱动的 research brain
12+
- evidence pack 与 paper grounding
13+
- keep / discard 后验反馈学习
14+
- direction memory 与失败后改向
15+
16+
## 项目定位
17+
18+
这个项目当前最准确的定位是：
19+
20+
- 高质量研究工程原型
21+
- controller-first 的自动化实验系统
22+
- 本地 first 的创新性科研实验助理
23+
24+
## 核心能力
25+
26+
- Python controller 作为唯一 outer-loop authority path
27+
- `Sisyphus` 作为唯一外层编排器
28+
- `sisyphus-junior` 作为唯一代码执行者
29+
- `Apollo / Athena / Hermes` 作为 exploit / validity / orthogonal 三专家
30+
- `experiments/` 作为真相源工件目录
31+
- `scripts/kb/` 作为 research brain 维护与推理链
32+
33+
## 架构图
34+
35+
```mermaid
36+
flowchart TD
37+
A[goal.yaml + experiments state] --> B[Sisyphus orchestrator]
38+
C[research brain index + evidence pack] --> B
39+
B --> D[Apollo exploit proposal]
40+
B --> E[Hermes orthogonal proposal]
41+
B --> F[Athena validity guard]
42+
D --> G[primary hypothesis selection]
43+
E --> G
44+
F --> G
45+
G --> H[sisyphus-junior execution]
46+
H --> I[Python controller]
47+
I --> J[judge keep / discard / review_blocked]
48+
J --> K[feedback + direction memory]
49+
K --> C
50+
K --> B
51+
```
52+
53+
## 主路径说明
54+
55+
- `scripts/innovation_loop.py` 是唯一外层 authority path
56+
- TypeScript legacy orchestration 仅保留 internal/test-only 兼容语义
57+
- 真实状态以 `experiments/` 下的结构化工件为准，而不是 prompt 临时上下文
58+
59+
## 目录结构
60+
61+
```text
62+
opencode-auto-research/
63+
├── .opencode/ # 命令、技能、agent 文档
64+
├── configs/ # 目标与 research brain 配置
65+
├── dist/ # 构建产物
66+
├── experiments/ # 真相源工件与运行结果
67+
├── fixtures/ # 测试 fixture
68+
├── scripts/ # Python controller / research brain / docker smoke
69+
├── src/ # TypeScript 插件、agents、tools、bridge
70+
├── tests/ # 单测、集成、E2E
71+
├── AGENTS.md # 项目路由规则
72+
├── README.md
73+
├── README.zh-CN.md
74+
├── INSTALL.md
75+
├── GUIDE.md
76+
└── REMOTE_EXECUTION.md
77+
```
78+
79+
## 安装方式
80+
81+
### 最简单安装
82+
83+
```bash
84+
git clone <your-repo-url>
85+
cd opencode-auto-research
86+
bash scripts/install-local.sh
87+
```
88+
89+
这个脚本会：
90+
91+
- 安装 JS 依赖
92+
- 安装 Python controller 依赖
93+
- 检查 OpenCode / oh-my-opencode 是否存在
94+
- 跑 build / test / smoke 验证
95+
96+
### 手动安装
97+
98+
```bash
99+
npm ci
100+
python3 -m pip install "dvc>=3,<4" "dvclive>=3,<4"
101+
npm install -g opencode-ai oh-my-opencode
102+
cp .env.example .env
103+
```
104+
105+
然后填写：
106+
107+
- `KIMI_CODING_API_KEY`
108+
- `KIMI_CODING_BASE_URL`
109+
- 如需覆盖模型，可设置 `INNOVATION_LOOP_AGENT_MODEL`
110+
111+
## 使用方法
112+
113+
### 构建
114+
115+
```bash
116+
npm run build
117+
```
118+
119+
### 运行全部测试
120+
121+
```bash
122+
npm test
123+
```
124+
125+
### 运行 smoke
126+
127+
```bash
128+
npm run test:smoke
129+
```
130+
131+
### Python controller（mock）
132+
133+
```bash
134+
python3 scripts/innovation_loop.py bootstrap --config configs/goal.yaml --workspace . --mode mock
135+
python3 scripts/innovation_loop.py tick --config configs/goal.yaml --workspace . --mode mock
136+
python3 scripts/innovation_loop.py status --config configs/goal.yaml --workspace . --mode mock
137+
```
138+
139+
### OpenCode 命令
140+
141+
- `/innovate-loop`
142+
- `/experiment-init`
143+
- `/experiment-run`
144+
- `/experiment-status`
145+
- `/experiment-bootstrap`
146+
- `/research-context`
147+
148+
## 预期效果
149+
150+
这套系统的预期效果不是替代研究员，而是成为一个创新性自动化科研实验助理：
151+
152+
- 更快迭代实验
153+
- 用本地论文库给 proposal 做 grounding
154+
- 在实验失败后自动改向
155+
- 把 keep / discard 经验沉淀进 direction memory
156+
- 把实验循环、知识脑、三专家、反馈学习接成闭环
157+
158+
## 如何在 OpenCode / oh-my-opencode 更新后保持稳定
159+
160+
核心策略：
161+
162+
1. 始终把 Python controller 当作唯一 authority path
163+
2. TypeScript 层只做 bridge / adapter，不再承担第二控制面
164+
3. 每次升级 OpenCode 或 oh-my-opencode 后，固定运行：
165+
166+
```bash
167+
npm run build
168+
npm test
169+
npm run test:smoke
170+
```
171+
172+
如果你本机有真实 DVC，再额外运行：
173+
174+
```bash
175+
npm test -- tests/e2e/python-controller-real-dvc.test.ts
176+
```
177+
178+
这样能最快判断升级是否破坏 controller path、research brain 或 remote contract。
179+
180+
## 远端执行说明
181+
182+
远端执行不是第二个 controller，而是现有 Python controller 的后端执行方式。
183+
184+
- 外环 authority path 不变
185+
- stage command 可以包裹远端执行
186+
- 但 metrics / checkpoint / `--resume-from` 的 contract 必须保持稳定
187+
188+
详见：`REMOTE_EXECUTION.md`
189+
190+
## 文档建议阅读顺序
191+
192+
1. `README.md` / `README.zh-CN.md`
193+
2. `INSTALL.md`
194+
3. `GUIDE.md`
195+
4. `AGENTS.md`
196+
5. `REMOTE_EXECUTION.md`
197+
198+
## 当前版本说明
199+
200+
1.0 版本意味着：
201+
202+
- 主控制面已收敛
203+
- research brain 已稳定接入主链
204+
- 公开工程仓库与主仓库都已过 build + test + smoke 验证
205+
- 这是一个可以长期维护和继续迭代的稳定起点

‎package-lock.json‎

Lines changed: 2 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "opencode-auto-research",
3-
"version": "0.1.0",
3+
"version": "1.0.0",
44
"description": "Governed autonomous experiment loop with a local innovation brain.",
55
"type": "module",
66
"main": "dist/index.js",

0 commit comments

Comments
 (0)