From 85466d8d3eb65357cf07569a21313476adab3f8c Mon Sep 17 00:00:00 2001 From: forthfate Date: Mon, 9 Nov 2026 11:55:54 +0900 Subject: [PATCH] docs: explain persona operation model --- README.md | 86 +++++++++++++++++++++++++++++++++++++---------- i18n/ko/README.md | 54 ++++++++++++++++++++++------- 2 files changed, 110 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 594e9a2..5610005 100644 --- a/README.md +++ b/README.md @@ -6,14 +6,17 @@ # What is OpenOrbit? -> **A local workspace where AI personas find product work, AI coding agents -> prepare changes, and your team reviews the result.** +> **A local control room where persistent AI personas express real user intent, +> bounded action agents gather evidence, and coding agents prepare safe, +> reviewable improvements.** OpenOrbit is a local-first web service for running the work around an AI -product—not only evaluating the agent itself. Personas explore a product, -report problems and tasks, and preserve the evidence. Your selected AI coding -agent can prepare a change in an isolated Git worktree; your team reviews the -diff, evidence, and decision in one control room. +product—not only evaluating the agent itself. Each Persona speaks from its own +perspective and retained public history. A separate action agent turns that +message into bounded tool work using only safe, rendered choices. OpenOrbit +retains the public conversation, sanitized evidence, and proposed code change +so your team can review it—or optionally auto-commit a tightly scoped proposal +branch without pushing, merging, or deploying it. It also supports repeatable AI-agent evaluation and self-improvement. Every run, proposal, decision, and approved change becomes retained operational @@ -28,28 +31,31 @@ reviewable improvement: ```mermaid flowchart LR - A[AI persona explores
the product] - B[Problem, task, and
retained evidence] - C[AI coding agent prepares
a worktree change] - D[Review the diff, evidence,
and proposal] - E[Human decision] - F[Improved product or
AI agent] + A[Persistent AI Persona
expresses user intent] + B[Bounded action agent
uses safe tools] + C[Public conversation
and retained evidence] + D[AI coding agent prepares
an isolated proposal] + E[Review or constrained
proposal-branch auto-commit] + F[Human integration
decision] A --> B --> C --> D --> E --> F --> A ``` -OpenOrbit keeps this work visible and reversible: AI can propose and prepare -work, while people decide what is applied. +OpenOrbit keeps this work visible and reversible: AI can express intent, +prepare evidence and proposals, while people decide what is integrated. ## What you can do - **Develop reported problems with worktrees.** When AI reports a concrete - problem, let a coding agent prepare an isolated change, then review its diff - and evidence before deciding what to apply. + problem, let a coding agent prepare an isolated change. Review its diff and + evidence before integration, or opt in to a tightly bounded proposal-branch + auto-commit policy. - **Use your preferred AI coding agent.** Connect the coding agent your team already uses instead of being tied to one provider. -- **Give AI personas work to do.** Personas explore from a defined point of - view, surface tasks and problems, and keep their work connected to evidence. +- **Operate persistent AI personas.** Personas express a defined user + perspective and use their retained public history. A separate action role + performs bounded tool work, while their public conversation and evidence + remain connected to each task. - **Improve AI agents over time.** Repeated evaluations retain responses, feedback, proposals, and decisions so an AI agent can improve safely. - **Manage personas and reusable assets.** Keep personas, model profiles, @@ -115,6 +121,31 @@ supervisor feedback and any proposed improvement. ![OpenOrbit Runs showing a completed workflow and its retained evidence](docs/images/evaluation-result-approved.png) +### Follow a Persona conversation from intent to evidence + +For compatible Persona journey runners, the **Conversation** tab shows each +Persona session and iteration. A Persona speaker produces the natural, +first-person message; a separate action-planning role receives that message and +the rendered safe choices, then selects bounded tool work. This keeps the +Persona's user perspective separate from the operating role without requiring +separate model providers. + +```mermaid +flowchart LR + A[Persona speaker
public user intent] + B[Action planner
safe rendered choices] + C[Bounded tool action] + D[Sanitized evidence
and next Persona turn] + + A --> B --> C --> D --> A +``` + +The transcript retains only public Persona messages, tool-AI replies, and +sanitized tool results. Private prompts, hidden reasoning, credentials, and raw +browser payloads are excluded. Select a Persona and iteration to inspect its +conversation; expandable tool results can open the retained screenshot or HTML +evidence for that step. + ### Follow improvement and persona activity Compare feedback, decisions, scores, run health, and persona journeys across @@ -132,6 +163,21 @@ applied without a decision. ![OpenOrbit Improvements reviewing an AI-created change and its isolated worktree diff](docs/images/ai-created-proposal-review.png) +### Choose how AI proposals are committed + +Each Build chooses an agent proposal policy: + +| Policy | What OpenOrbit does | +| --- | --- | +| **Require review** (default) | Keeps the isolated worktree proposal and its evidence for a human to review before integration. | +| **Auto-commit proposal branch** | Commits an eligible proposal only to its isolated proposal branch when every changed file matches an explicit allowed-path glob. | + +Auto-commit is a bounded proposal-preparation option, not unrestricted +self-modification: an empty allowed-path list disables it, sensitive paths stay +blocked even when listed, and it never pushes, merges, applies the change to the +evaluated repository, or deploys it. Human review remains the integration +boundary. + ### Ask Orbit Assistant about the current screen Configure a System AI model to use Orbit Assistant for questions about the @@ -280,6 +326,10 @@ that contains a secret, never the secret itself. Review workflow commands, approved workspace boundaries, and network exposure before connecting a production AI system. +Conversation records follow the same boundary: OpenOrbit retains public +messages and sanitized tool results needed to review a run, not private prompts, +hidden reasoning, credentials, or raw browser payloads. + ## API and extensibility OpenOrbit exposes a local, versioned API: diff --git a/i18n/ko/README.md b/i18n/ko/README.md index 4619937..bb8bce3 100644 --- a/i18n/ko/README.md +++ b/i18n/ko/README.md @@ -12,10 +12,11 @@ # OpenOrbit이란? -> **AI 페르소나가 제품의 일을 찾고, AI 코딩 에이전트가 변경안을 준비하며, -> 팀이 결과를 검토하는 로컬 워크스페이스입니다.** +> **지속되는 AI 페르소나가 실제 사용자 의도를 표현하고, 제한된 행동 +> 에이전트가 증거를 수집하며, 코딩 에이전트가 안전하고 검토 가능한 개선안을 +> 준비하는 로컬 컨트롤룸입니다.** -OpenOrbit은 AI 에이전트 자체를 평가하는 데 그치지 않고, AI 제품을 둘러싼 일을 운영하는 로컬 우선 웹서비스입니다. 페르소나는 제품을 탐색하며 문제와 과제를 보고하고 증거를 남깁니다. 여러분이 선택한 AI 코딩 에이전트는 격리된 Git worktree에서 변경안을 준비하고, 팀은 하나의 컨트롤룸에서 diff·증거·결정을 검토합니다. +OpenOrbit은 AI 에이전트 자체를 평가하는 데 그치지 않고, AI 제품을 둘러싼 일을 운영하는 로컬 우선 웹서비스입니다. 각 페르소나는 자신의 관점과 보존된 공개 이력을 바탕으로 발화합니다. 별도의 행동 에이전트가 그 메시지와 화면에 렌더링된 안전한 선택지만 사용해 제한된 도구 작업으로 바꿉니다. OpenOrbit은 공개 대화, 정제된 증거, 제안된 코드 변경을 보존하므로 팀이 검토할 수 있고, 선택적으로 엄격히 제한된 제안 브랜치에 자동 커밋할 수도 있습니다. 이 자동 커밋은 push, 병합, 배포를 수행하지 않습니다. 반복적인 AI Agent 평가와 자가 개선도 지원합니다. 실행, 제안, 의사결정, 승인된 변경은 모두 보존되는 운영 이력이 됩니다. 모든 것은 로컬에서 실행되고 기록은 AppData에 남습니다. @@ -25,23 +26,23 @@ AI 기능이나 웹 제품은 데모에서는 정상으로 보이더라도 프 ```mermaid flowchart LR - A[AI 페르소나가
제품을 탐색] - B[문제, 과제, 보존된 증거] - C[AI 코딩 에이전트가
worktree 변경안을 준비] - D[diff, 증거, 제안 검토] - E[사람의 결정] - F[개선된 제품 또는
AI Agent] + A[지속되는 AI 페르소나가
사용자 의도를 표현] + B[제한된 행동 에이전트가
안전한 도구를 사용] + C[공개 대화와
보존된 증거] + D[AI 코딩 에이전트가
격리된 제안을 준비] + E[검토 또는 제한된
제안 브랜치 자동 커밋] + F[사람의 통합
결정] A --> B --> C --> D --> E --> F --> A ``` -OpenOrbit은 이 일을 투명하고 되돌릴 수 있게 남깁니다. AI는 일을 제안하고 준비할 수 있지만, 적용 여부는 사람이 결정합니다. +OpenOrbit은 이 일을 투명하고 되돌릴 수 있게 남깁니다. AI는 의도를 표현하고, 증거와 제안을 준비할 수 있지만, 통합 여부는 사람이 결정합니다. ## 할 수 있는 일 -- **보고된 문제를 worktree로 개발합니다.** AI가 구체적인 문제를 보고하면 코딩 에이전트가 격리된 변경안을 준비하게 하고, 적용 전에 diff와 증거를 검토합니다. +- **보고된 문제를 worktree로 개발합니다.** AI가 구체적인 문제를 보고하면 코딩 에이전트가 격리된 변경안을 준비합니다. 통합 전에 diff와 증거를 검토하거나, 엄격히 제한된 제안 브랜치 자동 커밋 정책을 선택할 수 있습니다. - **원하는 AI 코딩 에이전트를 사용합니다.** 특정 제공자에 묶이지 않고 팀이 이미 사용하는 코딩 에이전트를 연결합니다. -- **AI 페르소나에게 일을 맡깁니다.** 페르소나는 정해진 관점에서 제품을 탐색하고, 과제와 문제를 발견하며, 그 일을 증거와 연결합니다. +- **지속되는 AI 페르소나를 운영합니다.** 페르소나는 정해진 사용자 관점과 보존된 공개 이력에 따라 발화합니다. 별도의 행동 역할이 제한된 도구 작업을 수행하고, 공개 대화와 증거는 각 과제에 연결된 채 남습니다. - **AI Agent를 지속적으로 개선합니다.** 반복 평가가 응답, 피드백, 제안, 결정을 보존하므로 AI Agent를 안전하게 개선할 수 있습니다. - **페르소나와 재사용 가능한 자산을 관리합니다.** 다음 작업에 사용할 페르소나, 모델 프로필, 프롬프트, 테스트 케이스, 환경, 워크플로를 관리합니다. - **Orbit Assistant로 질문하고 조작합니다.** 현재 보고 있는 화면에 관해 묻고, 컨트롤룸을 조작하는 데 도움을 받습니다. @@ -94,6 +95,22 @@ OpenOrbit의 웹 컨트롤룸은 문제 발견부터 결정까지의 일을 한 ![OpenOrbit Runs showing a completed workflow and its retained evidence](../../docs/images/evaluation-result-approved.png) +### 사용자 의도에서 증거까지 페르소나 대화 따라가기 + +호환되는 페르소나 여정 러너에서는 **대화** 탭에서 각 페르소나 세션과 이터레이션을 확인할 수 있습니다. 페르소나 발화 역할이 자연스러운 1인칭 메시지를 만들고, 별도의 행동 계획 역할은 그 메시지와 화면에 렌더링된 안전한 선택지를 받은 뒤 제한된 도구 작업을 선택합니다. 따라서 별도의 모델 제공자를 강제하지 않으면서도 페르소나의 사용자 관점과 조작 역할을 분리합니다. + +```mermaid +flowchart LR + A[페르소나 발화 역할
공개 사용자 의도] + B[행동 계획 역할
안전하게 렌더링된 선택지] + C[제한된 도구 행동] + D[정제된 증거와
다음 페르소나 차례] + + A --> B --> C --> D --> A +``` + +대화 기록에는 공개된 페르소나 발화, 도구 AI 응답, 정제된 도구 결과만 남습니다. 비공개 프롬프트, 내부 추론, 자격 증명, 원시 브라우저 payload는 제외합니다. 페르소나와 이터레이션을 선택해 대화를 살피고, 펼칠 수 있는 도구 결과에서 해당 단계의 보존된 스크린샷 또는 HTML 증거를 열 수 있습니다. + ### 개선과 페르소나 활동 살펴보기 여러 빌드에 걸쳐 피드백, 의사결정, 점수, 실행 상태, 페르소나 여정을 비교하세요. 이 이력은 제품 또는 AI Agent 워크플로가 시간에 따라 나아지고 있는지 보여줍니다. @@ -106,6 +123,17 @@ OpenOrbit의 웹 컨트롤룸은 문제 발견부터 결정까지의 일을 한 ![OpenOrbit Improvements reviewing an AI-created change and its isolated worktree diff](../../docs/images/ai-created-proposal-review.png) +### AI 제안을 커밋하는 방식 선택하기 + +각 Build에서 에이전트 제안 정책을 선택합니다. + +| 정책 | OpenOrbit의 동작 | +| --- | --- | +| **검토 필요** (기본값) | 사람이 통합 전에 검토할 수 있도록 격리된 worktree 제안과 증거를 보존합니다. | +| **제안 브랜치 자동 커밋** | 변경된 모든 파일이 명시적인 허용 경로 glob과 일치할 때에만, 격리된 제안 브랜치에 적격 제안을 커밋합니다. | + +자동 커밋은 무제한 자기 수정이 아니라 제한된 제안 준비 옵션입니다. 허용 경로 목록이 비어 있으면 자동 커밋하지 않고, 민감한 경로는 목록에 넣어도 계속 차단되며, push·병합·평가 대상 저장소에 변경 적용·배포를 수행하지 않습니다. 사람의 검토는 통합 경계로 남습니다. + ### 현재 화면에 관해 Orbit Assistant에게 묻기 System AI 모델을 구성하면 Orbit Assistant에게 현재 보고 있는 화면을 질문하고 컨트롤룸 조작을 도움받을 수 있습니다. 여러분의 AI 에이전트도 OpenOrbit의 MCP 서버 또는 버전 관리 API를 통해 같은 로컬 운영 데이터와 함께 작업할 수 있습니다. @@ -227,6 +255,8 @@ OpenOrbit는 로컬 우선입니다. 기본적으로 운영 상태는 저장소 `orbit run PATH`를 사용하면 `PATH/.orbit`에 데이터를 보관합니다. 이 경로는 해당 실행에서 기존에 선택한 데이터 위치와 `ORBIT_APP_DATA`보다 우선합니다. Git으로 관리하지 않을 데이터라면 대상 프로젝트의 `.gitignore`에 `.orbit/`을 추가하세요. 명령줄 경로 없이 다른 위치를 사용하려면 `ORBIT_APP_DATA`를 설정하세요. 모델 프로필은 비밀 값이 담긴 환경 변수의 이름을 저장하며, 비밀 값 자체는 절대 저장하지 않습니다. 프로덕션 AI 시스템을 연결하기 전에 워크플로 명령, 승인된 워크스페이스 경계, 네트워크 노출을 검토하세요. +대화 기록에도 같은 경계가 적용됩니다. OpenOrbit은 실행 검토에 필요한 공개 메시지와 정제된 도구 결과만 보존하며, 비공개 프롬프트, 내부 추론, 자격 증명, 원시 브라우저 payload는 보존하지 않습니다. + ## API 및 확장성 OpenOrbit는 로컬의, 버전이 관리되는 API를 노출합니다.