不把项目当作控制对象，
而是陪在身边照料，让它一起成长。
[](README.md) [](README.en.md) [](README.zh-CN.md) [](README.ja.md)
版本元数据详情
- Base README: [README.md](README.md)
- README version: `1.1-doc.12`
- Package version: see [package.json](package.json)
- Adapter JSON contract: `0.1`
- Base language: `ko`
- Translation source of truth: `README.md` (`ko`)
如果本译文落后，请以韩文 README 为准。README version、package version 和 Adapter JSON contract version 是彼此独立的版本轴。
[](https://www.npmjs.com/package/orange-hyper) [](https://github.com/KoreanCode/orange-hyper/actions/workflows/ci.yml) [](LICENSE) [](package.json)
## 问题 · 思考 · 方向
| 问题 | 思考 | 方向 |
| --- | --- | --- |
| 强 harness 会把过重流程压到小任务上。 | 无 harness 很轻，但 memory、验证和 boundary 都偏弱。 | Orange Hyper 只让必要的记忆通过 proposal -> review -> accept 成长。 |
## 问题定义
强 SDD harness 对大型任务有帮助。但如果小任务也必须走 branch、spec、review、verification、PR loop，很快就会产生疲劳。
无 harness 的流程很轻。它也很难长期维持 memory、验证、重复学习和 context boundary。
顺序式 SPEC 不适合协作和非线性思考。决策、约束、验证和风险不是排成一条直线，而是互相连接。
用户想轻松对话。项目却不能失去记忆和验证。
## 对 Harness 的思考
harness 可以建立流程，流程可以带来安全感。但如果所有任务都套同一种流程，用户就会为了运转 harness 而工作。
Orange Hyper 不会一开始就打开强 harness。它也不会像无 harness 流程那样把一切都交给模型指令。
需要的是两者之间的地带。小请求应该小结束。更大的工作应该留下意图、约束、memory 和验证证据。
## 选择的方向
- Intent 应该被编译。
- 工作应该按 level 和 layer 划分。
- Verification 应该随工作 level 变强。
- Memory 应该像 node graph 一样成长，而不是顺序 SPEC 链。
- role、MCP、hook、subagent 不会从一开始启用。
- role、MCP、hook、subagent 只从重复证据中成长。
- 轻量开始，逐步成长。
- 不自动 accept durable/shared memory。
- 在已激活的 supported host 中，Orange 可以在 activation policy 范围内自动管理 local runtime state、Quest、Capsule、evidence、working memory 和 pending proposal candidate。
- 只从 completed Quest 创建 Memory Delta Proposal。
- 只有用户 accept 的 proposal 才会成为 graph node candidate。
- 只有匹配当前 `project_id` 的 memory 才是当前项目 memory。
- CLI 是 skill、agent、adapter 调用的 kernel interface，不是最终用户 UX。
## Core Flow
用户请求会成为 Quest，再经过 Route Contract 和 Capsule，走向经过验证的完成状态。只有 completed Quest 才能成为 Memory Delta Proposal 的起点。
## Orange Hyper 是什么？
Orange Hyper 是面向 coding agent 的 repo-local project-memory kernel。
用户请求会被整理成 Quest 和 Route Contract。结果和验证证据会记录在 completed Quest 中。需要时，completed Quest 可以生成 Memory Delta Proposal，只有用户批准的 proposal 才会成为 project memory candidate。
目标不是巨大的自动化系统。用户继续轻松提出请求。项目只记住需要记住的内容，并按工作需要的 level 增强验证。
## 安装
默认安装方式不是把 Orange Hyper 加进当前项目的 npm dev dependency。Orange Hyper 优先使用 standalone binary，避免非 Node 项目因为使用 Orange 而生成 `package.json`、`package-lock.json` 或 `node_modules`。
安装优先级：
1. Standalone binary：从 GitHub Release 安装平台对应的 `orange` 执行文件到 user-local 目录。
2. Future package manager：Homebrew、Scoop 等用户范围 package manager 是后续渠道。
3. `npx` exact-version fallback：只用于临时确认，并指定 `orange-hyper@1.1.0-beta.2` 或 `@beta`。
4. Project-local npm install：只有用户明确要求时才使用的 advanced/manual option。
macOS/Linux user-local 安装：
```bash
curl -fsSL https://github.com/KoreanCode/orange-hyper/releases/download/v1.1.0-beta.2/install.sh | sh
"$HOME/.local/bin/orange" --version
```
Windows PowerShell user-local 安装：
```powershell
$Installer = Join-Path $env:TEMP "orange-install.ps1"
Invoke-WebRequest "https://github.com/KoreanCode/orange-hyper/releases/download/v1.1.0-beta.2/install.ps1" -OutFile $Installer
powershell -NoProfile -ExecutionPolicy Bypass -File $Installer -Version "1.1.0-beta.2" -AddToPath
& (Join-Path $env:LOCALAPPDATA "OrangeHyper\bin\orange.exe") --version
```
Windows 使用 `-AddToPath` 后，新的 PowerShell 窗口可以从 PATH 运行 `orange --version`。安装器会验证 SHA-256 checksum，验证失败会停止安装。它不使用 npm，不创建 package 文件，不创建 `node_modules`，也不修改当前项目。
私有技术 beta 参与者应在 [Closed Beta Program](docs/28_CLOSED_BETA_PROGRAM.md) 中查看 onboarding 和安全诊断边界，并用 [Beta Test Checklist](docs/29_BETA_TEST_CHECKLIST.md) 记录实际测试结果。
如果只想用 fallback 快速确认包是否可用，请指定 exact version：
```bash
npx -y --package orange-hyper@1.1.0-beta.2 orange --help
```
这不是默认安装方式。AI 不应该自动运行 `npm init -y` 或 `npm install -D orange-hyper`。npm package 继续作为 developer/fallback channel 保留。
## Closed Beta 渠道
当前推荐测试渠道是 `v1.1.0-beta.2`。这个 build 是官方 Closed Beta prerelease，不是 npm `latest` stable 渠道。
Primary validated 环境是 macOS arm64、Codex CLI、standalone binary、user-scoped Codex Host Binding、project-scoped Activation，以及 interactive Codex `/hooks` review。macOS x64、Linux x64、Windows x64 和其他 Codex minor version 在积累真实用户验证前仍是 exploratory 环境。
在这个 Beta 中，用户不需要直接运营 Orange，而是继续像平常一样向 AI 提出工作请求。AI 会在用户环境中安装一次 Codex Host Binding，并只激活需要使用 Orange 的 repository。Codex `/plugins` 中安装并 enable plugin，再在 Codex `/hooks` 中 review current definition 后，lifecycle 会自动连接。L0/L1 工作会安静通过；L2 以上工作会在 policy 范围内管理 Quest、Capsule 和 verification evidence。如果没有观察到 verification evidence，Stop 只请求一次 continuation。Working memory 和 pending Memory Proposal 可以创建，但 durable memory accept 不会自动化。
Beta quick start:
1. 将 standalone `v1.1.0-beta.2` 安装到 user-local 位置。
2. 安装 Codex Host Binding。
3. 在 Codex `/plugins` 中安装并 enable Orange plugin。
4. 在 Codex `/hooks` 中 review current definition。
5. 在需要使用 Orange 的 repository 中应用 project activation。
6. 用 `orange activate status --host codex --json` 确认 `active` 状态。
7. 之后继续像平常一样向 AI 提出工作请求。
更长的命令和状态解释放在 [Closed Beta Program](docs/28_CLOSED_BETA_PROGRAM.md)、[Activation Runtime](docs/26_ACTIVATION_RUNTIME.md)、[Codex Binding E2E Checklist](docs/27_CODEX_BINDING_E2E.md)。
不会自动化的安全边界：
- Memory Proposal accept
- MCP 安装或执行
- project-specific Skill/Agent 创建
- subagent 执行
- branch/PR/SPEC workflow
- telemetry 或 network upload
- raw prompt 和 transcript 存储
Beta 参与者应使用 [Closed Beta Program](docs/28_CLOSED_BETA_PROGRAM.md)、[Beta Test Checklist](docs/29_BETA_TEST_CHECKLIST.md)、[Beta Bug](.github/ISSUE_TEMPLATE/beta-bug.yml)、[Beta Feedback](.github/ISSUE_TEMPLATE/beta-feedback.yml)、[Codex Binding E2E Checklist](docs/27_CODEX_BINDING_E2E.md)。
如果你使用过 alpha.8，安装 beta.1 后，由于 plugin version 和 binding fingerprint 变化，可能需要在 Codex `/hooks` 中重新 review hook definition。现有 accepted project memory 不会自动删除或 reset。alpha.8 不会重新发布；beta.1 是新的 Closed Beta 分发渠道。
## 第一次告诉 AI 的 Prompt
在新项目或已有 repo 里想使用 Orange Hyper 时，可以把下面这段直接贴给 AI。
```text
请在这个项目中使用 Orange Hyper。
Install the Orange Codex Host Binding once.
Activate Orange in the repositories where you want it.
Then work normally.
首先确认 PATH 中的 `orange --version` 和 `orange env --json` 是否可以运行。
如果没有 `orange`，请先建议 standalone binary 安装；只有在我批准后，才安装到 user-local 位置。
不要运行 `npm init -y`。不要把 `npm install -D orange-hyper` 当作默认安装方式。不要创建或修改项目的 `package.json`、`package-lock.json`、`node_modules`。
只有在我明确要求时才使用 npm fallback；使用时也要指定 `orange-hyper@beta` 或 `orange-hyper@1.1.0-beta.2`。
如果当前 Codex 环境还没有 Orange Host Binding，请先运行 `orange binding plan --host codex --scope user --json`，把 read-only binding plan 给我看。
如果我批准，请运行 `orange binding install --host codex --scope user --json`。这个命令只能准备 user-scoped marketplace 和 plugin source；不要把 marketplace 注册说成 plugin 已安装、已 enable、hook 已 review 或 operational。
然后运行 `orange activate plan --host codex --scope project --json`，把 read-only project activation plan 给我看。
如果我批准，请运行 `orange activate apply --host codex --scope project --json` 激活这个项目。实际 lifecycle heartbeat 出现之前，不要报告 active。
然后运行 `orange sync plan --json` 给我看 diff；我批准后，再运行 `orange sync apply --json` 和 `orange sync status --json` 来刷新 generated Structure Graph 和 Identity HTML。
我不会直接管理 CLI 命令。需要时，请你调用 orange ... --json kernel command。
不要把小问题或简单说明变成 Quest。真正开始推进工作时，请记录 intent 和 verification evidence。
如果有值得记住的决定、约束、风险或验证结果，请作为 Memory Proposal 提出。在我批准之前，不要 accept proposal。
不要自动安装 MCP。只在有需要时提出建议。Hook、Growth、Eval 只作为警告和摘要使用，不要作为自动修复。
不要直接编辑 .orange-hyper 文件。请使用 Orange Kernel command。
需要时，请刷新 Identity HTML，让我可以查看 Knowledge Graph。
```
## 和 AI 一起使用的实际流程
先用对话开始，而不是先找 CLI 命令。
**示例 1**
用户：这个任务请用 Orange Hyper 管理着推进。
AI：这个任务值得记录为 Quest。我会把 intent 和验证标准记录到 Orange Hyper，然后开始推进。
**示例 2**
用户：这个决定以后应该记住。
AI：我会把它作为 Memory Proposal 提出。你批准后，它可以成为 accepted memory。
**示例 3**
用户：看看这个项目现在是怎么成长的。
AI：我会刷新 Identity HTML，并查看 Knowledge Graph 与 Growth/Eval summary。
**示例 4**
用户：我可能需要这个库的最新文档。
AI：我会用 MCP Advisor 建议合适的工具。不会自动安装。
## Orange Hyper 会静静留下什么
比起功能列表，用产物来理解 Orange Hyper 更容易。
- Quest：工作意图和范围。
- Evidence：工作确实经过验证的依据。
- Memory Proposal：值得记住的决定、约束、风险或验证结果候选。
- Accepted Memory：用户批准后的项目记忆。
- Knowledge Graph：把 accepted memory 作为 decision、constraint、risk、verification、component node 来读取的图。
- Identity HTML：在一个 HTML 中查看项目记忆、accepted memory graph、growth signal 和 eval summary。
- Hook Warning：不会自动修复的警告。
- Activation Runtime：用户批准的 supported-host lifecycle binding。仅安装并不等于 active；需要 heartbeat。
- MCP Suggestion：不会安装的工具建议。
- Growth Signal：不会自动 unlock 的成长候选。
- Eval Report：local-only 评价报告。
## Identity HTML / Knowledge Graph
Orange Hyper 的 Knowledge Graph 不是 code dependency graph。它是 accepted project memory graph。
它展示用户批准过的 decision、constraint、risk、verification、component memory。pending/rejected proposal 不会包含在内。
对 AI 说“刷新 Identity HTML”时，AI 可以通过 Orange Kernel 更新这个文件：
```text
.orange-hyper/identity/orange-hyper.html
```
Identity HTML 是 Orange Hyper Identity 的 primary product surface。v1.1 的目标是让第一屏成为 full-screen Knowledge Graph Dashboard，而不是 document-style report。
当前 Identity HTML 提供 read-only full-screen Knowledge Graph Dashboard。第一屏是 Canvas graph stage，把 generated Structure Graph 和 accepted memory 合成在一起，并提供 floating action dock、search popover、selected-node badge、minimap，以及 click-to-inspect node drawer。除了默认的 Combined 视图，也可以选择 Structure 和 Memory 视图。layout 坐标在 build 时确定，所以同一 revision 会保持同一初始位置；search/view filter 以及 fit/reset/pan/zoom 都不会修改 source state。它不是 graph editor；Obsidian/JSON Canvas export 是 future interoperability layer，不是默认产品体验。
## 详细文档链接
- [Project Definition](docs/00_PROJECT_DEFINITION.md)
- [Architecture](docs/01_ARCHITECTURE.md)
- [Memory Graph Spec](docs/02_MEMORY_GRAPH_SPEC.md)
- [Route Level System](docs/04_ROUTE_LEVEL_SYSTEM.md)
- [Development Roadmap](docs/10_DEVELOPMENT_ROADMAP.md)
- [Identity Dashboard Spec](docs/14_IDENTITY_DASHBOARD_SPEC.md)
- [Minimal Hook Preview](docs/17_MINIMAL_HOOK_PREVIEW.md)
- [MCP Advisor](docs/18_MCP_ADVISOR.md)
- [Growth Signal Preview](docs/19_GROWTH_SYSTEM.md)
- [Eval and Reports](docs/21_EVAL_AND_REPORTS.md)
- [v1 Stabilization Readiness](docs/22_V1_STABILIZATION.md)
- [Project Sync](docs/24_PROJECT_SYNC.md)
- [Standalone Distribution](docs/25_STANDALONE_DISTRIBUTION.md)
- [Activation Runtime](docs/26_ACTIVATION_RUNTIME.md)
- [Codex Binding E2E Checklist](docs/27_CODEX_BINDING_E2E.md)
- [Closed Beta Program](docs/28_CLOSED_BETA_PROGRAM.md)
- [Beta Test Checklist](docs/29_BETA_TEST_CHECKLIST.md)
- [Release Notes](RELEASE_NOTES.md)
## Manual fallback / Kernel command reference
普通用户通常不直接运行 CLI。只有在 AI 没有工具访问权限，或需要手动确认时，才参考 [Manual fallback](docs/23_MANUAL_FALLBACK.md)。
- For AI / Adapter authors: [Adapter Layer](docs/20_ADAPTER_LAYER.md)
- Kernel command reference: [Adapter JSON Contract](docs/16_ADAPTER_CONTRACT.md)
- Manual fallback: [Manual Fallback](docs/23_MANUAL_FALLBACK.md)
下面不是长篇使用说明，而是供 AI 和 adapter 参考的 top-level kernel surface。
- `init`
- `activate`
- `lifecycle`
- `host`
- `quest`
- `route`
- `capsule`
- `remember`
- `graph`
- `hook`
- `mcp`
- `growth`
- `adapter`
- `binding`
- `eval`
- `sync`
- `env`
- `doctor`
- `identity`