diff --git a/README.en.md b/README.en.md new file mode 100644 index 0000000..ae0f4d8 --- /dev/null +++ b/README.en.md @@ -0,0 +1,826 @@ +

OpenOPC: Build Your Personal AI-Native Company — Self-Built, Self-Run, Self-Grown

+ +

+ English | 简体中文 +

+ +🏗️ **Self-Built** — Fully automated to recruit role-specific AI employees and build the org. + +⚙️ **Self-Run** — Fully automated to assign tasks, drive handoffs, and keep moving toward your goal. + +🌱 **Self-Grown** — Learns from every task, builds organizational memory, always delivers smarter. + +

+ Python 3.10+ + Office UI + CLI and UI + License MIT + Feishu + WeChat +

+ +![OpenOPC hero banner](docs/assets/chat.png) + +## News + +- **Jul 14, 2026 — More resilient company runs:** Company-mode sessions now recover and resume more seamlessly while preserving agent identity, shared role context, delegation, and review progress. +- **Jul 13, 2026 — Smoother Office UI:** Faster live updates and chat scrolling improve long-running projects. +- **Jul 8, 2026 — Smarter approvals:** Session grants persist, low-risk actions flow automatically, and deferred decisions stay available. + +## Table Of Contents + +- [When To Use OpenOPC](#when-to-use-openopc) +- [Demos](#demos) +- [How OpenOPC Works](#how-openopc-works) +- [Quick Start](#quick-start) +- [Office UI Guide](#office-ui-guide) +- [CLI Guide](#cli-guide) +- [Configuration](#configuration) +- [Ecosystem And Sharing](#ecosystem-and-sharing) +- [Roadmap](#roadmap) +- [Acknowledgements](#acknowledgements) + +## When to Use OpenOPC + +**OpenOPC** covers nine core verticals — from AI development and software engineering to finance, sales, media, e-commerce, and education. Whatever the industry, OpenOPC assembles the right team and delivers end-to-end. + + + + + + + + + + + + + + + + + +
+
🤖 AI Tech & Research +
Model training & evaluation, Agent development, LLM apps & AI infrastructure + 		+
💻 Software Development +
Android apps, SaaS MVPs, websites, mini programs & game development + 		+
📈 Financial Investment +
Investment memos, market maps, due diligence & IC decision packages +
+ 🚀 Sales Growth +
Outbound sales, deal strategy, proposals & channel expansion + 		+ 🎬 Content & Media +
Video production, short-form content, scripts, storyboards & multi-platform cuts + 		+ 🤝 Industry Assistants +
Copilots for support, real estate, legal intake, HR onboarding, retail +
+ 🧾 Accounting & Finance +
Bookkeeping, financial reporting, tax compliance, budgeting & risk review + 		+ 🛍️ Brand & E-commerce +
Brand planning, product selection, store ops, user growth & retention + 		+ 🎓 Education & Training +
Curriculum design, knowledge base, learner management & content production +
+ +## Demos + + + + + + + +
+ + OpenOPC video production demo + +

+ 🎬 Video Production + 		+ + OpenOPC VC investment research demo + +

+ 📈 Investment Research + 		+ + OpenOPC game prototype demo + +

+ 🎮 Game Prototype +
+ +## How OpenOPC Works + +OpenOPC assembles a AI company around complex, real-world tasks — through three tightly coupled mechanisms: **Self-Built** staffs the organisation, **Self-Run** executes the work, and **Self-Grown** learns from the outcome. + +

+ An OpenOPC company: roles, reporting lines, and the employee staffed into each role +

+ +**1. Self-Built — Staffing the Organisation** + +Before any work begins, the right people must be in place. Given a goal, OpenOPC: + +- 🌿 Drafts the org chart — deriving the roles and reporting structure the task demands. +- 🎯 Fills each role — a recruiter agent chooses between reusing an existing employee (shaped by prior projects) and onboarding a fresh hire from the talent pool. + +💡 Experienced employees carry accumulated context; fresh hires offer a clean slate when a role demands it. + +**⚙️ 2. Self-Run — Executing the Work** + +With the team assembled, Self-Run orchestrates its members toward a finished deliverable. The central challenge is not raw execution but efficient collaboration under uncertainty, which manifests in two distinct problems. + +🔀 Dynamic collaboration orchestration. Real work cannot be fully planned upfront. OpenOPC addresses this through a work-item state machine, where each item's phase determines: + +- 📋 Its kanban column — where it stands in the workflow. +- 👑 Its owner — the role responsible at that phase. +- ✅ Its runnability — whether it is ready to proceed. + +A manager decomposes items, assigns, and reviews results — accepting, reworking, or escalating — across five modes: execute, delegate, review, integrate, and rework. Decomposition defines a dependency DAG, so: + +- ⚡ Independent items proceed in parallel. +- ⏳ Dependent items wait until prerequisites are resolved. + +🔗 Dependency resolution and rejection propagate as structured phase transitions, eliminating ad-hoc coordination. + +🛡️ Handling blockers surfacing mid-run. Not all obstacles are visible upfront. OpenOPC resolves them at two levels: + +- 💬 Within the team — a blocking message pauses the sender, activating the role best positioned to resolve it. +- 📡 Beyond the team — when a blocker exceeds the team's authority, the runtime escalates to the human owner, invoking human judgment precisely when needed. + +🖥️ The kanban and office views render this orchestration in real time. + +**🌱 3. Self-Grown — Learning from the Run** + +Execution generates raw experience; Self-Grown turns it into lasting improvement, guided by two principles. + +🏅 Attributing outcomes to the right roles. Crediting the whole company teaches nothing. Instead, OpenOPC: + +- 🔍 Resolves user feedback into per-employee evaluations. +- 🎯 Updates only roles that owned the relevant work items — credit and blame land where they were earned. + +📖 Distilling trajectories into knowledge. Execution traces are too noisy to learn from. OpenOPC therefore: +- 💡 Distils each role's tasks into high-signal lessons, stored in its private experience profile. +- 📚 Promotes recurring lessons into shared playbooks, which new hires inherit from the outset — compounding organisational knowledge over time. + +
+How this maps to the UI + +- `Org -> Team` edits the company architecture and roles. +- `Org -> Employees` hires talent into vacant roles. +- `Team Roster -> Deploy` turns a hired employee into a visible office agent. +- The Workspace composer selects the Task Mode execution agent. +- The role inspector can set runtime policy and preferred external agent for Company Mode roles. +- During execution, Workspace `Agents` and the Execution Progress panel show which role is active, which work item it owns, and which execution agent is doing the concrete work. +
+ +## Quick Start + +`uv` is the recommended setup path for OpenOPC. It can install/manage Python, create the project virtualenv, and run commands against that environment without mixing OpenOPC dependencies into your global Python. + +OpenOPC requires Python `>=3.10`; the examples below use Python `3.12`. + +For direct one-off work, OpenOPC also includes Task Mode, a LobeChat-like single-agent workspace using OpenOPC Native, Codex, Claude Code, Cursor, or OpenCode. + +
+Recommended: uv environment setup + +**macOS** + +```bash +# Install uv with Homebrew, or use the official standalone installer. +brew install uv +# curl -LsSf https://astral.sh/uv/install.sh | sh + +cd /path/to/OpenOPC +uv python install 3.12 +uv venv --python 3.12 +source .venv/bin/activate +``` + +**Linux** + +```bash +curl -LsSf https://astral.sh/uv/install.sh | sh +source "$HOME/.local/bin/env" + +cd /path/to/OpenOPC +uv python install 3.12 +uv venv --python 3.12 +source .venv/bin/activate +``` + +**Windows PowerShell** + +```powershell +powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" + +cd C:\path\to\OpenOPC +uv python install 3.12 +uv venv --python 3.12 +.\.venv\Scripts\Activate.ps1 +``` + +**Windows Command Prompt** + +```bat +winget install --id=astral-sh.uv -e +:: Or run the standalone installer from cmd: +:: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" + +cd C:\path\to\OpenOPC +uv python install 3.12 +uv venv --python 3.12 +.venv\Scripts\activate.bat +``` +
+ +```bash +# Install OpenOPC into the uv-managed environment +uv pip install -e . + +# Optional but recommended for browser tools +uv run python -m playwright install chromium + +# Initialize local config, memory, skills, projects, and workspace folders +uv run opc init + +# Add an API key in .opc/config/llm_config.yaml +# or configure the env var named by llm.api_key_env. + +# Launch the browser UI +uv run opc ui +``` + +Open `http://localhost:8765` by default. + +```bash +# Interactive CLI +uv run opc chat -p demo + +# One-shot task mode +uv run opc chat -p demo --mode task --agent codex "Refactor this module and run focused tests" + +# Company mode with the built-in Corporate architecture +uv run opc chat -p demo --mode company --company-profile corporate "Plan, implement, review, and document this feature" + +# Non-interactive scripting / CI style usage +uv run opc exec -p demo --mode task --agent native --json "Summarize the current repo status" +``` + +
+Install notes + +- Python: `>=3.10`. Current required dependencies do not all publish Python 3.9-compatible releases. +- `uv` is recommended for local development and release testing. If you prefer classic pip, create and activate a Python `>=3.10` virtualenv, then run `python -m pip install -e .`. +- If virtualenv activation is blocked, stay unactivated and run commands with `uv run ...`. +- See the official [`uv` installation](https://docs.astral.sh/uv/getting-started/installation/) and [Python management](https://docs.astral.sh/uv/guides/install-python/) docs for alternative package managers and managed Python details. +- Node.js: `>=18` is needed when the Office UI frontend must be built. +- `opc ui` auto-installs missing `aiohttp` / `aiosqlite` and auto-builds the frontend if needed. +- If you have not installed external agent CLIs yet, run `opc init --no-external-agent-preflight` to skip the first-run external-agent checks. +- Browser tools are native Playwright tools. Install Chromium with `python -m playwright install chromium` before asking agents to browse pages. +
+ +
+Development setup (build from source) + +```bash +python -m pip install -e . +python -m pytest + +cd opc/plugins/office_ui/frontend_src +npm install +npm run typecheck +npm run build +``` + +The frontend build output is served from `opc/plugins/office_ui/frontend_dist/`. +
+ +## Office UI Guide + +
+Expand the Office UI guide — visual tour, workspace, company mode, kanban, office, org + +Start it with: + +```bash +opc ui +opc ui --port 9000 --project demo +opc ui --rebuild +``` + +### Visual Tour + +Scroll horizontally to browse the Office UI walkthrough. Each screenshot keeps its short guide text attached. + +
+
+
+ Workspace project, chat, mode, organization, and agent controls +
Workspace And Setup. Choose or create a project, start New Chat, then select Company or Task plus the matching organization or agent. In Company Mode, pick role employees and execution agents, or let OpenOPC auto-recruit.
+
+
+ Execution Progress panel showing role status and execution records +
Execution Progress. Track every role's state, then click a role or work item to inspect detailed execution records, tool activity, handoffs, reviews, and runtime metadata.
+
+
+ Kanban board showing agent work items and status +
Kanban. Supervise each agent's concrete tasks and work items as they move through planning, execution, review, blockers, and completion.
+
+
+ Organization editor for tuning existing organizations and creating new ones +
Org Control. Tune existing organizations, adjust roles and reporting lines, review runtime policy, or create a new organization.
+
+
+ Talent market for browsing and recruiting employees +
Talent Market. Browse talent templates, inspect candidate details, and recruit employees into vacant roles when the company needs more capability.
+
+
+ Animated office view showing what each role is doing +
Office View. Watch the organization as an animated office, with each role/agent showing status, current task, active tool, seat, and runtime activity.
+
+
+
+ +The Office UI has three primary pages: + +| Page | What you do there | +|---|---| +| **Workspace** | Main working surface: session list, kanban board, chat, task details, role progress, comms, and team cockpit. | +| **Office** | Visual office map: agents appear as characters, can be selected, moved, assigned to seats, and inspected. | +| **Org** | Company architecture: switch corporate/saved orgs, create new organizations, edit roles, hire talent, apply architecture presets, and import/export configs. | + +### Workspace + +The Workspace page is the default screen. + +| Area | What to look for | +|---|---| +| Left sidebar | Project sessions, activity, unread counts, and new chat creation. | +| Center board | Kanban cards. In Task Mode, a card is normally one task-backed chat session. In Company Mode, the board follows the selected runtime session and shows delegated work items. | +| Right panel | Context panel with tabs such as `Chat`, `Agents`, `Info`, `Comms`, and `Team`. Collapse, resize, or maximize it while work is running. | +| Composer | Send messages, attach files, choose mode, choose company architecture, and in Task Mode choose the execution agent. | + +### Start Work From The UI + +1. Create or select a project from the top project selector. +2. In Workspace, click `New Chat`. +3. In the composer, choose `Task` or `Company`. +4. For Task Mode, choose the agent: `OpenOPC Native`, `Codex`, `Claude Code`, `Cursor`, or `OpenCode`. +5. For Company Mode, choose `Corporate` or a saved org architecture. +6. Send the brief. + +Once the first message is sent, the mode and task agent are locked for that chat. Use the locked-mode popover to continue in a new chat with a different mode. + +### Company Mode In The UI + +Company Mode turns one brief into a runtime session plus role-owned work items. + +| Tab | What it shows | +|---|---| +| `Chat` | Parent conversation, final responses, runtime progress cards, checkpoint replies, stop/continue/done controls, and links into work-item execution. | +| `Agents` | Role rollup: active/waiting/pending/done roles, current tool, role work items, filters, search, and links to detailed execution progress. | +| `Info` | Status, assignees, role identity, employee assignment, selected execution agent, timing, and developer details. | +| `Comms` | Role inboxes, unread/read/sent messages, meetings, decisions, and recent communication failures. | +| `Team` | Runtime cockpit: teams, seats, approvals, unread communication, run state, and stop controls for the current run. | + +To inspect the detailed workflow for a role, open a company-mode session and click a role/work item in the `Chat` progress card or `Agents` tab. The Execution Progress panel shows each work item, its status, activity sections, tool progress, handoffs, review targets, and execution turn metadata. + +### Kanban + +- Task Mode: the kanban is a project-level board. You can quick-create tasks in `Todo`, start them, and inspect each task from the right panel. +- Company Mode: the active board follows the selected runtime session. Cards represent company work items and move from planning/execution/review/done according to backend runtime state. +- Manual drag between status columns is intentionally restricted when runtime owns the state. Same-column reorder is supported where applicable. + +### Office + +Use the Office page when you want a visual view of the running team. + +- Click an agent character or row to inspect status, current tool, current task, role, office, and seat. +- Use the office/seat controls to move an agent. +- Sub-agents can be shown or hidden. +- Agents created from employees or templates appear in the office and are persisted in `.opc/ui_state.db`. + +### Org + +The Org page is where company structure becomes runnable. + +| Sub-tab | Purpose | +|---|---| +| `Team` | View/edit the role graph, table, role inspector, roster, saved org selector, export package flow, and deploy hired employees to the office. | +| `Runtime` | Tune runtime teams, seats, final decider, delegation strategy, and runtime policy. Corporate is read-only; saved orgs are editable. | +| `Architecture` | Browse built-in architecture presets, preview/apply packages, manage installed packages, and import/export YAML. | +| `Employees` | Search talent templates, view details, hire into vacant roles, and staff the company. | + +To create a new company: open `Org`, click `New organization`, enter a name, add at least two members with responsibilities and reporting lines, review, and create. OpenOPC saves it automatically and switches the composer to `Company / `. + +To recruit: import talent templates first, then open `Org -> Employees`, search a template, click `Hire`, choose a vacant role, and deploy the employee from `Team Roster` if you want it visible in the Office page. + +```bash +opc talent import /path/to/agency-agents +``` + +
+Where project files live + +OpenOPC separates runtime/config state from deliverable workspace files. + +| Path | Meaning | +|---|---| +| `.opc/config/` | Local config copied from `config/` by `opc init`. | +| `.opc/memory/` | Global and project markdown memory. | +| `.opc/projects//` | Project runtime metadata and task stores. | +| `.opc/ui_state.db` | Office UI chat, channels, and visual agent state. | +| `../OpenOPC_workplace//` | Default project workplace. Agents should write durable project files here. | +| `../OpenOPC_workplace//.opc-comms/` | Internal company-mode comms mailboxes, meetings, and tool-result scratch space. | + +Set `OPC_HOME=/path/to/opc-home` if you want config and runtime state outside the repo. +
+ +
+ +## CLI Guide + +
+Expand the CLI guide — common commands and interactive slash commands + +OpenOPC exposes both high-level natural-language commands and lower-level UI/service commands. + +Conceptually OpenOPC has two execution modes: `task` and `company`. Some lower-level CLI/service commands still expose `org` as a compatibility selector for Company Mode with a saved organization architecture; in the UI this appears as Company plus an architecture choice. + +### Common Commands + +```bash +# Chat +opc chat +opc chat -p demo --mode task --agent native "Inspect the failing tests" +opc chat -p demo --mode company --company-profile corporate "Ship this change with review" + +# Scriptable execution +opc exec -p demo --mode task --agent codex --stream-json "Run the migration check" +opc exec -p demo --mode company --company-profile corporate "Draft the research report" + +# Project lifecycle +opc project list +opc project create demo +opc project switch demo + +# Sessions +opc session list -p demo +opc session create "New feature" -p demo --mode company +opc session send "Continue with implementation" -p demo +opc session stop -p demo +opc session continue "Proceed after review" -p demo + +# Runtime inspection +opc runtime status -p demo +opc runtime logs -p demo +opc work-item list -p demo +opc work-item show -p demo +opc comms state -p demo + +# Recruitment +opc talent import /path/to/agency-agents +opc talent hire -p demo +``` + +### Interactive Slash Commands + +Run `opc chat`, then use slash commands: + +```text +/status +/mode task +/mode company corporate +/agent codex +/project switch demo +/session list +/runtime --full +/logs --full +/comms --full +/org +/talent list +/market list +``` + +See [`docs/cli-chat-slash.md`](docs/cli-chat-slash.md) for the full command table. + +
+CLI command groups + +| Group | Examples | +|---|---| +| `opc project` | `list`, `show`, `create`, `switch`, `rename`, `delete --yes` | +| `opc session` | `list`, `create`, `show`, `config`, `send`, `rename`, `delete --yes`, `stop`, `continue`, `resume`, `complete` | +| `opc mode` | `show`, `set task`, `set company --profile corporate`, `set org --org ` for a saved-org company run | +| `opc kanban` | `view`, `task create`, `task update`, `task move`, `task assign`, `task status`, `task delete --yes` | +| `opc agent` | `list`, `create`, `create-from-template`, `import-employee`, `detail`, `move`, `delete --yes` | +| `opc org` | `info`, `export`, `import`, `saved list/save/load/delete`, `role add/update/bulk-add/delete`, `policy update`, `strategy update`, `reset --yes` | +| `opc talent` | `list`, `employees`, `import`, `hire`, `scan`, `import-selected`, `employee-detail`, `import-agent` | +| `opc market` | `presets`, `browse`, `preview`, `apply-preset`, `export`, `install`, `list`, `uninstall --yes` | +| `opc runtime` | `status`, `checkpoints`, `logs`, `run` | +| `opc channels` | `status`, `login`, `start`, `stop` | + +Most service-style commands accept `--project/-p` and `--json`. + +For saved organization architectures, some CLI/service commands currently use `org` as a compatibility selector even though the conceptual runtime is still Company Mode: + +```bash +opc exec -p demo --mode org --org hku_research_lab "Draft the research report" +opc session create "Research sprint" -p demo --mode org --org hku_research_lab +``` +
+ +
+ +## Configuration + +Run `opc init` once from the repo root. It creates `.opc/`, copies the template config from `config/`, creates memory/skills/log folders, and optionally creates the first project. + +
+Expand configuration — config files, LLM keys, external agents, channels, browser/MCP, troubleshooting + +| File | Purpose | +|---|---| +| `.opc/config/llm_config.yaml` | Default model, LiteLLM/OpenRouter-compatible API base, API key, env var indirection, routing, fallback, temperature, token limit. | +| `.opc/config/system_config.yaml` | Runtime behavior, browser tools, native runtime, compaction, verification, permissions, sandbox, and safety settings. | +| `.opc/config/agent_config.yaml` | External agent command paths, preferred order, model flags, session modes, timeouts, approval modes, and native subagent profiles. | +| `.opc/config/channel_config.yaml` | External messaging providers and credentials. Inbound sender lists are deny-by-default. | +| `.opc/config/company_corporate_config.yaml` | Built-in corporate company architecture template. | +| `.opc/config/company_orgs/org__config.yaml` | Saved custom company architectures used by Company Mode. | +| `.opc/config/org_index.yaml` | Active saved company architecture selector. | + +### LLM Keys + +After `opc init`, edit `.opc/config/llm_config.yaml` in the repo-local OPC home. If you set `OPC_HOME`, edit `$OPC_HOME/config/llm_config.yaml` instead. + +The template leaves secrets empty. Write your key directly into the file: + +```yaml +llm: + default_model: "openai/gpt-5.4" + api_base: "https://openrouter.ai/api/v1" + api_key: "sk-or-v1-..." # your OpenRouter (or other provider) API key + + max_tokens: 32768 # max output tokens per request; lower it if your + # model's output cap is smaller + # context_window: 128000 # total input window. Usually auto-detected via + # litellm; unmapped models fall back to 128000. + # Uncomment and set only when the fallback is + # wrong for your model. +``` + +Then verify with `opc status`. + +If you prefer not to store the key in the file, leave `api_key` empty and set `api_key_env` to the name of an environment variable that holds it (e.g. `api_key_env: "OPENROUTER_API_KEY"`). + +### Approval & Agent Permissions + +The `autonomy` section of `.opc/config/system_config.yaml` controls how much an agent can do without asking. The key knob is `max_auto_approve_risk` — the highest risk level that can be auto-approved: + +```yaml +autonomy: + max_auto_approve_risk: medium # low | medium | high | critical + allow_native_tool_auto_approval: true + tool_first_use_approval: true # first use of each tool always asks +``` + +Every native tool call is risk-classified before it runs: known destructive commands (`rm -rf`, `drop table`, force-push, …) and sensitive keywords (credentials, deploys, …) are `high`/`critical` and always escalate to a human; allowlisted safe prefixes (`ls`, `git status`, …) are `low`; everything else is `medium` and goes through an LLM review before auto-approval. + +- `medium` (default): balanced — ordinary commands run without prompts; dangerous ones escalate. +- `low`: strict — anything not on the safe allowlist asks for approval. Recommended for shared or production machines. +- `high`/`critical`: permissive — only for throwaway sandboxes. + +The first time a tool is used you are always prompted (unless the tool is in `tool_approval_exemptions`), and your "Always allow" choices accumulate in a per-project allowlist. + +### External Agents + +Task Mode can explicitly select an execution agent: + +```bash +opc chat -p demo --mode task --agent codex "Implement the change" +``` + +Available values are `native`, `codex`, `claude_code`, `cursor`, and `opencode`. Configure command names, flags, timeouts, session reuse, and approval behavior in `.opc/config/agent_config.yaml`. + +In Company Mode, roles can prefer external agents through their role config or the Org role inspector. A role can use `auto`, `native`, or `external` execution strategy, with an optional preferred external agent. + +### Feishu Connection + +```bash +pip install -e .[channels-feishu] +opc init +opc channels login feishu +``` + +Edit `.opc/config/channel_config.yaml`: + +```yaml +channels: + feishu: + enabled: true + app_id: "cli_xxx" + app_secret: "..." + encrypt_key: "" + verification_token: "" + react_emoji: THUMBSUP + allow_from: + - "ou_xxx" +``` + +Then: + +```bash +opc channels status +opc channels start -p demo +# or run the long-lived engine + channel runtime: +opc run -p demo +``` + +Feishu uses the `lark-oapi` WebSocket client. `app_id` and `app_secret` are required; `encrypt_key` and `verification_token` are optional unless your tenant/app configuration requires them. Keep `allow_from` explicit; an empty list denies all inbound messages. + +
+Other channel providers + +| Provider | Install extra | Runtime | Required fields | +|---|---|---|---| +| Telegram | `channels-telegram` | polling | `token` | +| Slack | `channels-slack` | socket | `bot_token`, `app_token` | +| Discord | `channels-discord` | socket | `token` | +| DingTalk | `channels-dingtalk` | socket | `client_id`, `client_secret` | +| Email | `channels-email` | polling | IMAP/SMTP fields, `consent_granted` | +| Matrix | `channels-matrix` | sync/polling | `homeserver`, `access_token`, `user_id` | +| QQ | `channels-qq` | socket | `app_id`, `secret` | +| WhatsApp | `channels-whatsapp` | bridge | `bridge_url` | +| Mochat | `channels-mochat` | bridge | `base_url`, `claw_token`, `agent_user_id` | + +Useful commands: + +```bash +opc channels login slack +opc channels status +opc channels start -p demo +opc channels stop +opc run -p demo +``` + +See [`docs/channels.md`](docs/channels.md) and [`docs/channel-bridges.md`](docs/channel-bridges.md). +
+ +
+Browser tools and MCP servers + +Browser tools: + +```bash +python -m playwright install chromium +``` + +Configure launch behavior in `.opc/config/system_config.yaml`: + +```yaml +system: + browser: + mode: embedded # embedded | chrome | auto + headless: true + chrome_channel: chrome + user_data_dir: "" +``` + +Native browser tools include `browser_navigate`, `browser_snapshot`, `browser_click`, `browser_type`, `browser_wait_for`, `browser_scroll`, `browser_select_option`, `browser_evaluate`, `browser_take_screenshot`, and `browser_close`. + +MCP servers can be added under `mcp_servers` in `system_config.yaml`. Local servers use stdio commands; remote servers use HTTP/SSE-style URLs. Discovered tools are registered with a server prefix to avoid collisions. +
+ +### Troubleshooting + +
+Office UI does not open or looks stale + +```bash +opc ui --rebuild +``` + +If the browser still shows stale UI state, hard refresh the page. If a previous process died mid-run, restart `opc ui` first so in-memory locks are released. +
+ +
+A task appears stuck + +Start with a server restart and browser hard refresh. If persisted task state is still dirty, use the reset helper: + +```bash +python scripts/reset_stuck_task.py --project --session --apply +python scripts/reset_stuck_task.py --all --apply +``` +
+ +
+External agent is not available + +Run: + +```bash +opc status +``` + +Check `.opc/config/agent_config.yaml` for command names such as `codex`, `claude`, `cursor-agent`, and `opencode`. Disable or reprioritize agents you do not have installed. +
+ +
+Channel provider receives no messages + +Check: + +- The provider extra is installed, for example `pip install -e .[channels-feishu]`. +- The provider is `enabled: true`. +- Required credentials are filled. +- `allow_from` contains the sender IDs you expect. +- `opc channels status` reports the provider as configured and available. +
+ +
+ +## Ecosystem And Sharing + +Everything OpenOPC builds is yours to keep, reuse, and share — organizations, employees, talent templates, skills, and channels are just files. Import a popular talent library, reuse a team across projects, or package a whole company as a shareable `.opcpkg`. + +```bash +# Hire from a talent library (e.g. agency-agents) into a role +opc talent import /path/to/agency-agents +opc talent hire -p demo + +# Reuse or share a whole organization +opc org export --json > my-org.yaml +opc market export --id hku_lab --name "HKU Lab" --output-dir packages +opc market install packages/hku_lab.opcpkg +``` + + + +## Roadmap + +OpenOPC is moving quickly. The areas below reflect active development priorities — each grounded in real gaps identified during early usage. + +| Area | Planned direction | +|---|---| +| **Role-level skills** | Role config already carries `skill_refs`, and the Org UI surfaces skill metadata today. The next step is letting users select which skills mount to which roles directly from the Org page — feeding into a broader self-evolving skill ecosystem. | +| **Secretary settings** | The secretary will grow into a stronger configuration and memory steward: owning OPC system memory, analysing and comparing projects, and providing guided setup for OpenOPC YAML configuration. | +| **Company-mode channels** | External channels will evolve beyond simple chat entrypoints into richer company-mode workflows — with role-aware notifications, structured approvals, and cross-platform collaboration. | +| **CLI parity** | The CLI is functional today, but the Office UI remains the more complete surface. Upcoming work targets org editing, company-mode inspection, failure recovery, and long-running runtime control from the terminal. | +| **TUI** | A full terminal UI is under consideration once CLI parity matures. The Office UI remains the primary interface in the meantime. | +| **Market and presets** | More architecture presets, recruitable talent packs, import/export workflows, and a package marketplace for sharing and discovering community-built components. | +| **Runtime polish** | Continued improvements to recovery, checkpointing, execution-progress visibility, and visual documentation — making long company runs more observable and resilient. | + +## Acknowledgements + +OpenOPC is built with gratitude for several open-source projects that helped shape its agent design, skill structure, and talent template ecosystem: + +- [openai/codex](https://github.com/openai/codex/) for inspiring practical coding-agent workflows and execution patterns. +- [BloopAI/vibe-kanban](https://github.com/BloopAI/vibe-kanban) for inspiration around kanban-centered agent work management and task visibility. +- [msitarzewski/agency-agents](https://github.com/msitarzewski/agency-agents) for the talent-template foundation. All talent templates included in this repository are imported from `agency-agents`. +- [HKUDS/nanobot](https://github.com/HKUDS/nanobot) for inspiration around skill-oriented agent design and `SKILL.md`-style organization. +- [pixel-agents-hq/pixel-agents](https://github.com/pixel-agents-hq/pixel-agents) for inspiration around the animated pixel-art office visualization of agent activity. + +--- + +

+ ❤️ Thanks for visiting ✨ OpenOPC!

+ Views +

diff --git a/README.md b/README.md index d9b30ef..a43ea1f 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,14 @@ -

OpenOPC: Build Your Personal AI-Native Company — Self-Built, Self-Run, Self-Grown

+

OpenOPC：打造你的个人 AI 原生公司 — 自建、自营、自成长

- English | 简体中文 + English | 简体中文

-🏗️ **Self-Built** — Fully automated to recruit role-specific AI employees and build the org. +🏗️ **自建（Self-Built）** — 全自动招募各岗位的 AI 员工，搭建组织架构。 -⚙️ **Self-Run** — Fully automated to assign tasks, drive handoffs, and keep moving toward your goal. +⚙️ **自营（Self-Run）** — 全自动分派任务、驱动交接，持续朝你的目标推进。 -🌱 **Self-Grown** — Learns from every task, builds organizational memory, always delivers smarter. +🌱 **自成长（Self-Grown）** — 从每个任务中学习，沉淀组织记忆，交付越来越聪明。

Python 3.10+ @@ -21,182 +21,177 @@ ![OpenOPC hero banner](docs/assets/chat.png) -## News +## 目录 -- **Jul 14, 2026 — More resilient company runs:** Company-mode sessions now recover and resume more seamlessly while preserving agent identity, shared role context, delegation, and review progress. -- **Jul 13, 2026 — Smoother Office UI:** Faster live updates and chat scrolling improve long-running projects. -- **Jul 8, 2026 — Smarter approvals:** Session grants persist, low-risk actions flow automatically, and deferred decisions stay available. +- [何时使用 OpenOPC](#何时使用-openopc) +- [演示](#演示) +- [OpenOPC 如何工作](#openopc-如何工作) +- [快速开始](#快速开始) +- [Office UI 指南](#office-ui-指南) +- [CLI 指南](#cli-指南) +- [配置](#配置) +- [生态与分享](#生态与分享) +- [路线图](#路线图) +- [本地修改（与原仓库对比）](#本地修改与原仓库对比) +- [致谢](#致谢) -## Table Of Contents +## 何时使用 OpenOPC -- [When To Use OpenOPC](#when-to-use-openopc) -- [Demos](#demos) -- [How OpenOPC Works](#how-openopc-works) -- [Quick Start](#quick-start) -- [Office UI Guide](#office-ui-guide) -- [CLI Guide](#cli-guide) -- [Configuration](#configuration) -- [Ecosystem And Sharing](#ecosystem-and-sharing) -- [Roadmap](#roadmap) -- [Acknowledgements](#acknowledgements) - -## When to Use OpenOPC - -**OpenOPC** covers nine core verticals — from AI development and software engineering to finance, sales, media, e-commerce, and education. Whatever the industry, OpenOPC assembles the right team and delivers end-to-end. +**OpenOPC** 覆盖九大核心垂直领域 — 从 AI 开发、软件工程到金融、销售、媒体、电商与教育。无论哪个行业，OpenOPC 都会组建合适的团队并端到端交付。
-
🤖 AI Tech & Research -
Model training & evaluation, Agent development, LLM apps & AI infrastructure +
🤖 AI 技术与研究 +
模型训练与评估、Agent 开发、LLM 应用与 AI 基础设施 		-
💻 Software Development -
Android apps, SaaS MVPs, websites, mini programs & game development +
💻 软件开发 +
Android 应用、SaaS MVP、网站、小程序与游戏开发 		-
📈 Financial Investment -
Investment memos, market maps, due diligence & IC decision packages +
📈 金融投资 +
投资备忘录、市场图谱、尽职调查与投决会材料
- 🚀 Sales Growth -
Outbound sales, deal strategy, proposals & channel expansion + 🚀 销售增长 +
外呼销售、交易策略、方案书与渠道拓展 		- 🎬 Content & Media -
Video production, short-form content, scripts, storyboards & multi-platform cuts + 🎬 内容与媒体 +
视频制作、短视频内容、脚本、分镜与多平台剪辑 		- 🤝 Industry Assistants -
Copilots for support, real estate, legal intake, HR onboarding, retail + 🤝 行业助理 +
客服、房产、法律咨询、HR 入职、零售等场景的 Copilot
- 🧾 Accounting & Finance -
Bookkeeping, financial reporting, tax compliance, budgeting & risk review + 🧾 会计与财务 +
记账、财务报告、税务合规、预算与风险审查 		- 🛍️ Brand & E-commerce -
Brand planning, product selection, store ops, user growth & retention + 🛍️ 品牌与电商 +
品牌规划、选品、店铺运营、用户增长与留存 		- 🎓 Education & Training -
Curriculum design, knowledge base, learner management & content production + 🎓 教育与培训 +
课程设计、知识库、学员管理与内容生产
-## Demos +## 演示
- OpenOPC video production demo + OpenOPC 视频制作演示

- 🎬 Video Production + 🎬 视频制作 		- OpenOPC VC investment research demo + OpenOPC VC 投资研究演示

- 📈 Investment Research + 📈 投资研究 		- OpenOPC game prototype demo + OpenOPC 游戏原型演示

- 🎮 Game Prototype + 🎮 游戏原型
-## How OpenOPC Works +## OpenOPC 如何工作 -OpenOPC assembles a AI company around complex, real-world tasks — through three tightly coupled mechanisms: **Self-Built** staffs the organisation, **Self-Run** executes the work, and **Self-Grown** learns from the outcome. +OpenOPC 围绕复杂的真实任务组建一家 AI 公司 — 通过三个紧密耦合的机制：**自建**负责组织配员，**自营**负责执行工作，**自成长**负责从结果中学习。

- An OpenOPC company: roles, reporting lines, and the employee staffed into each role + 一家 OpenOPC 公司：角色、汇报关系，以及每个角色配备的员工

-**1. Self-Built — Staffing the Organisation** +**1. 自建 — 为组织配员** -Before any work begins, the right people must be in place. Given a goal, OpenOPC: +在任何工作开始之前，必须先把合适的人放到合适的位置。给定一个目标，OpenOPC 会： -- 🌿 Drafts the org chart — deriving the roles and reporting structure the task demands. -- 🎯 Fills each role — a recruiter agent chooses between reusing an existing employee (shaped by prior projects) and onboarding a fresh hire from the talent pool. +- 🌿 起草组织架构图 — 从任务需求推导出所需的角色与汇报结构。 +- 🎯 填补每个角色 — 由招聘 Agent 在「复用现有员工（带着以往项目塑造的经验）」与「从人才池中招募新人」之间做出选择。 -💡 Experienced employees carry accumulated context; fresh hires offer a clean slate when a role demands it. +💡 有经验的员工携带积累的上下文；当角色需要时，新员工则提供一张白纸。 -**⚙️ 2. Self-Run — Executing the Work** +**⚙️ 2. 自营 — 执行工作** -With the team assembled, Self-Run orchestrates its members toward a finished deliverable. The central challenge is not raw execution but efficient collaboration under uncertainty, which manifests in two distinct problems. +团队组建完成后，自营机制协调成员产出最终交付物。核心挑战不在于单纯执行，而在于不确定性下的高效协作，具体体现为两个问题。 -🔀 Dynamic collaboration orchestration. Real work cannot be fully planned upfront. OpenOPC addresses this through a work-item state machine, where each item's phase determines: +🔀 动态协作编排。真实工作无法完全提前规划。OpenOPC 通过工作项状态机来解决，每个工作项所处的阶段决定： -- 📋 Its kanban column — where it stands in the workflow. -- 👑 Its owner — the role responsible at that phase. -- ✅ Its runnability — whether it is ready to proceed. +- 📋 它在看板的哪一列 — 处于工作流的哪个位置。 +- 👑 它的负责人 — 该阶段由哪个角色负责。 +- ✅ 它的可执行性 — 是否已经具备推进条件。 -A manager decomposes items, assigns, and reviews results — accepting, reworking, or escalating — across five modes: execute, delegate, review, integrate, and rework. Decomposition defines a dependency DAG, so: +管理者负责拆解工作项、分派并评审结果 — 接受、返工或上报 — 覆盖五种模式：执行（execute）、委派（delegate）、评审（review）、集成（integrate）与返工（rework）。拆解定义了一个依赖 DAG，因此： -- ⚡ Independent items proceed in parallel. -- ⏳ Dependent items wait until prerequisites are resolved. +- ⚡ 相互独立的工作项并行推进。 +- ⏳ 有依赖的工作项等待前置项完成。 -🔗 Dependency resolution and rejection propagate as structured phase transitions, eliminating ad-hoc coordination. +🔗 依赖解除与驳回都作为结构化的阶段转换传播，消除了临时的人为协调。 -🛡️ Handling blockers surfacing mid-run. Not all obstacles are visible upfront. OpenOPC resolves them at two levels: +🛡️ 处理运行中途出现的阻塞。并非所有障碍都能提前预见。OpenOPC 在两个层面解决： -- 💬 Within the team — a blocking message pauses the sender, activating the role best positioned to resolve it. -- 📡 Beyond the team — when a blocker exceeds the team's authority, the runtime escalates to the human owner, invoking human judgment precisely when needed. +- 💬 团队内部 — 一条阻塞消息会暂停发送者，并激活最适合解决该问题的角色。 +- 📡 团队之外 — 当阻塞超出团队权限时，运行时会上报给人类所有者，在真正需要时引入人类判断。 -🖥️ The kanban and office views render this orchestration in real time. +🖥️ 看板与办公室视图实时呈现这一编排过程。 -**🌱 3. Self-Grown — Learning from the Run** +**🌱 3. 自成长 — 从运行中学习** -Execution generates raw experience; Self-Grown turns it into lasting improvement, guided by two principles. +执行产生原始经验；自成长把它转化为持久的改进，遵循两条原则。 -🏅 Attributing outcomes to the right roles. Crediting the whole company teaches nothing. Instead, OpenOPC: +🏅 把结果归因到正确的角色。把功劳记给整个公司学不到任何东西。因此 OpenOPC： -- 🔍 Resolves user feedback into per-employee evaluations. -- 🎯 Updates only roles that owned the relevant work items — credit and blame land where they were earned. +- 🔍 将用户反馈解析为针对每位员工的评估。 +- 🎯 只更新负责了相关工作项的角色 — 功与过都落到应得之处。 -📖 Distilling trajectories into knowledge. Execution traces are too noisy to learn from. OpenOPC therefore: -- 💡 Distils each role's tasks into high-signal lessons, stored in its private experience profile. -- 📚 Promotes recurring lessons into shared playbooks, which new hires inherit from the outset — compounding organisational knowledge over time. +📖 把执行轨迹提炼为知识。执行轨迹噪声太大，无法直接学习。因此 OpenOPC： +- 💡 把每个角色的任务提炼为高信号的经验教训，存入其私有经验档案。 +- 📚 把反复出现的经验提升为共享的作业手册（playbook），新员工从入职起即可继承 — 让组织知识随时间复利增长。
-How this maps to the UI +这些机制如何对应到 UI -- `Org -> Team` edits the company architecture and roles. -- `Org -> Employees` hires talent into vacant roles. -- `Team Roster -> Deploy` turns a hired employee into a visible office agent. -- The Workspace composer selects the Task Mode execution agent. -- The role inspector can set runtime policy and preferred external agent for Company Mode roles. -- During execution, Workspace `Agents` and the Execution Progress panel show which role is active, which work item it owns, and which execution agent is doing the concrete work. +- `Org -> Team` 编辑公司架构与角色。 +- `Org -> Employees` 为空缺角色招募人才。 +- `Team Roster -> Deploy` 把已录用的员工变成办公室中可见的 Agent。 +- Workspace 输入框可选择 Task 模式的执行 Agent。 +- 角色检查器可为 Company 模式的角色设置运行时策略与偏好的外部 Agent。 +- 执行期间，Workspace 的 `Agents` 页签与 Execution Progress 面板会显示哪个角色处于活动状态、它负责哪个工作项、以及由哪个执行 Agent 完成具体工作。
-## Quick Start +## 快速开始 -`uv` is the recommended setup path for OpenOPC. It can install/manage Python, create the project virtualenv, and run commands against that environment without mixing OpenOPC dependencies into your global Python. +推荐使用 `uv` 来安装 OpenOPC。它可以安装/管理 Python、创建项目虚拟环境，并在该环境中运行命令，而不会把 OpenOPC 的依赖混入全局 Python。 -OpenOPC requires Python `>=3.10`; the examples below use Python `3.12`. +OpenOPC 要求 Python `>=3.10`；下面的示例使用 Python `3.12`。 -For direct one-off work, OpenOPC also includes Task Mode, a LobeChat-like single-agent workspace using OpenOPC Native, Codex, Claude Code, Cursor, or OpenCode. +对于直接的一次性工作，OpenOPC 还提供 Task 模式 — 一个类 LobeChat 的单 Agent 工作台，可使用 OpenOPC Native、Codex、Claude Code、Cursor 或 OpenCode。
-Recommended: uv environment setup +推荐：uv 环境搭建 **macOS** ```bash -# Install uv with Homebrew, or use the official standalone installer. +# 使用 Homebrew 安装 uv，或使用官方独立安装脚本。 brew install uv # curl -LsSf https://astral.sh/uv/install.sh | sh @@ -229,11 +224,11 @@ uv venv --python 3.12 .\.venv\Scripts\Activate.ps1 ``` -**Windows Command Prompt** +**Windows 命令提示符** ```bat winget install --id=astral-sh.uv -e -:: Or run the standalone installer from cmd: +:: 或在 cmd 中运行独立安装脚本： :: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" cd C:\path\to\OpenOPC @@ -244,53 +239,53 @@ uv venv --python 3.12
```bash -# Install OpenOPC into the uv-managed environment +# 将 OpenOPC 安装到 uv 管理的环境中 uv pip install -e . -# Optional but recommended for browser tools +# 可选但推荐：安装浏览器工具所需的 Chromium uv run python -m playwright install chromium -# Initialize local config, memory, skills, projects, and workspace folders +# 初始化本地配置、记忆、技能、项目与工作区目录 uv run opc init -# Add an API key in .opc/config/llm_config.yaml -# or configure the env var named by llm.api_key_env. +# 在 .opc/config/llm_config.yaml 中填入 API key， +# 或配置 llm.api_key_env 指定的环境变量。 -# Launch the browser UI +# 启动浏览器 UI uv run opc ui ``` -Open `http://localhost:8765` by default. +默认打开 `http://localhost:8765`。 ```bash -# Interactive CLI +# 交互式 CLI uv run opc chat -p demo -# One-shot task mode +# 一次性 Task 模式 uv run opc chat -p demo --mode task --agent codex "Refactor this module and run focused tests" -# Company mode with the built-in Corporate architecture +# 使用内置 Corporate 架构的 Company 模式 uv run opc chat -p demo --mode company --company-profile corporate "Plan, implement, review, and document this feature" -# Non-interactive scripting / CI style usage +# 非交互脚本 / CI 风格用法 uv run opc exec -p demo --mode task --agent native --json "Summarize the current repo status" ```
-Install notes +安装说明 -- Python: `>=3.10`. Current required dependencies do not all publish Python 3.9-compatible releases. -- `uv` is recommended for local development and release testing. If you prefer classic pip, create and activate a Python `>=3.10` virtualenv, then run `python -m pip install -e .`. -- If virtualenv activation is blocked, stay unactivated and run commands with `uv run ...`. -- See the official [`uv` installation](https://docs.astral.sh/uv/getting-started/installation/) and [Python management](https://docs.astral.sh/uv/guides/install-python/) docs for alternative package managers and managed Python details. -- Node.js: `>=18` is needed when the Office UI frontend must be built. -- `opc ui` auto-installs missing `aiohttp` / `aiosqlite` and auto-builds the frontend if needed. -- If you have not installed external agent CLIs yet, run `opc init --no-external-agent-preflight` to skip the first-run external-agent checks. -- Browser tools are native Playwright tools. Install Chromium with `python -m playwright install chromium` before asking agents to browse pages. +- Python：`>=3.10`。当前必需依赖并非全部提供兼容 Python 3.9 的版本。 +- 本地开发与发布测试推荐使用 `uv`。如果你偏好经典 pip，请创建并激活一个 Python `>=3.10` 的虚拟环境，然后运行 `python -m pip install -e .`。 +- 如果虚拟环境激活被阻止，可以不激活，直接用 `uv run ...` 运行命令。 +- 关于其他包管理器与托管 Python 的细节，参见官方 [`uv` 安装文档](https://docs.astral.sh/uv/getting-started/installation/) 与 [Python 管理文档](https://docs.astral.sh/uv/guides/install-python/)。 +- Node.js：需要构建 Office UI 前端时要求 `>=18`。 +- `opc ui` 会自动安装缺失的 `aiohttp` / `aiosqlite`，并在需要时自动构建前端。 +- 如果你尚未安装外部 Agent CLI，运行 `opc init --no-external-agent-preflight` 可跳过首次运行的外部 Agent 检查。 +- 浏览器工具基于原生 Playwright。在让 Agent 浏览网页之前，先用 `python -m playwright install chromium` 安装 Chromium。
-Development setup (build from source) +开发环境搭建（从源码构建） ```bash python -m pip install -e . @@ -302,15 +297,15 @@ npm run typecheck npm run build ``` -The frontend build output is served from `opc/plugins/office_ui/frontend_dist/`. +前端构建产物从 `opc/plugins/office_ui/frontend_dist/` 提供服务。
-## Office UI Guide +## Office UI 指南
-Expand the Office UI guide — visual tour, workspace, company mode, kanban, office, org +展开 Office UI 指南 — 视觉导览、工作台、Company 模式、看板、办公室、组织 -Start it with: +启动方式： ```bash opc ui @@ -318,184 +313,184 @@ opc ui --port 9000 --project demo opc ui --rebuild ``` -### Visual Tour +### 视觉导览 -Scroll horizontally to browse the Office UI walkthrough. Each screenshot keeps its short guide text attached. +横向滚动浏览 Office UI 演示。每张截图都附有简短的说明文字。
- Workspace project, chat, mode, organization, and agent controls -
Workspace And Setup. Choose or create a project, start New Chat, then select Company or Task plus the matching organization or agent. In Company Mode, pick role employees and execution agents, or let OpenOPC auto-recruit.
+ Workspace 的项目、聊天、模式、组织与 Agent 控件 +
工作台与初始设置。选择或创建项目，点击 New Chat，然后选择 Company 或 Task 以及对应的组织或 Agent。在 Company 模式下，可以指定角色员工与执行 Agent，也可以让 OpenOPC 自动招募。
- Execution Progress panel showing role status and execution records -
Execution Progress. Track every role's state, then click a role or work item to inspect detailed execution records, tool activity, handoffs, reviews, and runtime metadata.
+ Execution Progress 面板显示角色状态与执行记录 +
执行进度。跟踪每个角色的状态，点击角色或工作项即可查看详细的执行记录、工具活动、交接、评审与运行时元数据。
- Kanban board showing agent work items and status -
Kanban. Supervise each agent's concrete tasks and work items as they move through planning, execution, review, blockers, and completion.
+ 看板展示 Agent 的工作项与状态 +
看板。监督每个 Agent 的具体任务与工作项，观察它们在规划、执行、评审、阻塞与完成之间流转。
- Organization editor for tuning existing organizations and creating new ones -
Org Control. Tune existing organizations, adjust roles and reporting lines, review runtime policy, or create a new organization.
+ 组织编辑器，可调整现有组织或新建组织 +
组织管理。调整现有组织、修改角色与汇报关系、查看运行时策略，或创建一个新组织。
- Talent market for browsing and recruiting employees -
Talent Market. Browse talent templates, inspect candidate details, and recruit employees into vacant roles when the company needs more capability.
+ 人才市场，可浏览并招募员工 +
人才市场。浏览人才模板，查看候选人详情，在公司需要更多能力时把员工招募到空缺角色上。
- Animated office view showing what each role is doing -
Office View. Watch the organization as an animated office, with each role/agent showing status, current task, active tool, seat, and runtime activity.
+ 动画办公室视图，展示每个角色正在做什么 +
办公室视图。以动画办公室的形式观察整个组织，每个角色/Agent 都会显示状态、当前任务、正在使用的工具、座位与运行时活动。
-The Office UI has three primary pages: +Office UI 有三个主要页面： -| Page | What you do there | +| 页面 | 在这里做什么 | |---|---| -| **Workspace** | Main working surface: session list, kanban board, chat, task details, role progress, comms, and team cockpit. | -| **Office** | Visual office map: agents appear as characters, can be selected, moved, assigned to seats, and inspected. | -| **Org** | Company architecture: switch corporate/saved orgs, create new organizations, edit roles, hire talent, apply architecture presets, and import/export configs. | +| **Workspace** | 主要工作界面：会话列表、看板、聊天、任务详情、角色进度、通讯与团队驾驶舱。 | +| **Office** | 可视化办公室地图：Agent 以角色形象出现，可以选中、移动、分配座位与查看详情。 | +| **Org** | 公司架构：切换 Corporate/已保存的组织、创建新组织、编辑角色、招募人才、应用架构预设、导入/导出配置。 | -### Workspace +### 工作台（Workspace） -The Workspace page is the default screen. +Workspace 页面是默认界面。 -| Area | What to look for | +| 区域 | 关注点 | |---|---| -| Left sidebar | Project sessions, activity, unread counts, and new chat creation. | -| Center board | Kanban cards. In Task Mode, a card is normally one task-backed chat session. In Company Mode, the board follows the selected runtime session and shows delegated work items. | -| Right panel | Context panel with tabs such as `Chat`, `Agents`, `Info`, `Comms`, and `Team`. Collapse, resize, or maximize it while work is running. | -| Composer | Send messages, attach files, choose mode, choose company architecture, and in Task Mode choose the execution agent. | +| 左侧边栏 | 项目会话、活动、未读计数与新建聊天。 | +| 中间看板 | 看板卡片。Task 模式下，一张卡片通常对应一个任务型聊天会话。Company 模式下，看板跟随所选的运行时会话，展示已委派的工作项。 | +| 右侧面板 | 上下文面板，包含 `Chat`、`Agents`、`Info`、`Comms`、`Team` 等页签。工作运行期间可以折叠、调整大小或最大化。 | +| 输入框 | 发送消息、附加文件、选择模式、选择公司架构；在 Task 模式下选择执行 Agent。 | -### Start Work From The UI +### 从 UI 开始工作 -1. Create or select a project from the top project selector. -2. In Workspace, click `New Chat`. -3. In the composer, choose `Task` or `Company`. -4. For Task Mode, choose the agent: `OpenOPC Native`, `Codex`, `Claude Code`, `Cursor`, or `OpenCode`. -5. For Company Mode, choose `Corporate` or a saved org architecture. -6. Send the brief. +1. 在顶部项目选择器中创建或选择一个项目。 +2. 在 Workspace 中点击 `New Chat`。 +3. 在输入框中选择 `Task` 或 `Company`。 +4. Task 模式下选择 Agent：`OpenOPC Native`、`Codex`、`Claude Code`、`Cursor` 或 `OpenCode`。 +5. Company 模式下选择 `Corporate` 或一个已保存的组织架构。 +6. 发送任务简报。 -Once the first message is sent, the mode and task agent are locked for that chat. Use the locked-mode popover to continue in a new chat with a different mode. +第一条消息发出后，该聊天的模式与任务 Agent 即被锁定。若需换用其他模式，可通过锁定模式的弹出提示在新聊天中继续。 -### Company Mode In The UI +### UI 中的 Company 模式 -Company Mode turns one brief into a runtime session plus role-owned work items. +Company 模式把一份简报变成一个运行时会话加一组由角色负责的工作项。 -| Tab | What it shows | +| 页签 | 展示内容 | |---|---| -| `Chat` | Parent conversation, final responses, runtime progress cards, checkpoint replies, stop/continue/done controls, and links into work-item execution. | -| `Agents` | Role rollup: active/waiting/pending/done roles, current tool, role work items, filters, search, and links to detailed execution progress. | -| `Info` | Status, assignees, role identity, employee assignment, selected execution agent, timing, and developer details. | -| `Comms` | Role inboxes, unread/read/sent messages, meetings, decisions, and recent communication failures. | -| `Team` | Runtime cockpit: teams, seats, approvals, unread communication, run state, and stop controls for the current run. | +| `Chat` | 父级对话、最终回复、运行时进度卡片、检查点回复、停止/继续/完成控件，以及跳转到工作项执行的链接。 | +| `Agents` | 角色汇总：活动/等待/待定/完成的角色、当前工具、角色工作项、筛选、搜索，以及详细执行进度的链接。 | +| `Info` | 状态、负责人、角色身份、员工分配、所选执行 Agent、时间信息与开发者详情。 | +| `Comms` | 角色收件箱、未读/已读/已发消息、会议、决策与最近的通讯故障。 | +| `Team` | 运行时驾驶舱：团队、座位、审批、未读通讯、恢复状态与当前运行的停止控件。 | -To inspect the detailed workflow for a role, open a company-mode session and click a role/work item in the `Chat` progress card or `Agents` tab. The Execution Progress panel shows each work item, its status, activity sections, tool progress, handoffs, review targets, and execution turn metadata. +要查看某个角色的详细工作流，打开一个 Company 模式会话，在 `Chat` 进度卡片或 `Agents` 页签中点击角色/工作项。Execution Progress 面板会展示每个工作项及其状态、活动分区、工具进度、交接、评审对象与执行轮次元数据。 -### Kanban +### 看板（Kanban） -- Task Mode: the kanban is a project-level board. You can quick-create tasks in `Todo`, start them, and inspect each task from the right panel. -- Company Mode: the active board follows the selected runtime session. Cards represent company work items and move from planning/execution/review/done according to backend runtime state. -- Manual drag between status columns is intentionally restricted when runtime owns the state. Same-column reorder is supported where applicable. +- Task 模式：看板是项目级面板。可以在 `Todo` 中快速创建任务、启动任务，并从右侧面板查看每个任务。 +- Company 模式：当前面板跟随所选运行时会话。卡片代表公司工作项，按照后端运行时状态在规划/执行/评审/完成之间流转。 +- 当运行时掌管状态时，跨状态列的手动拖拽会被有意限制。同列内重新排序在适用时是支持的。 -### Office +### 办公室（Office） -Use the Office page when you want a visual view of the running team. +当你想以可视化方式查看运行中的团队时，使用 Office 页面。 -- Click an agent character or row to inspect status, current tool, current task, role, office, and seat. -- Use the office/seat controls to move an agent. -- Sub-agents can be shown or hidden. -- Agents created from employees or templates appear in the office and are persisted in `.opc/ui_state.db`. +- 点击 Agent 角色形象或列表行，查看状态、当前工具、当前任务、角色、办公室与座位。 +- 使用办公室/座位控件移动 Agent。 +- 子 Agent 可以显示或隐藏。 +- 由员工或模板创建的 Agent 会出现在办公室中，并持久化在 `.opc/ui_state.db`。 -### Org +### 组织（Org） -The Org page is where company structure becomes runnable. +Org 页面是公司结构变得可运行的地方。 -| Sub-tab | Purpose | +| 子页签 | 用途 | |---|---| -| `Team` | View/edit the role graph, table, role inspector, roster, saved org selector, export package flow, and deploy hired employees to the office. | -| `Runtime` | Tune runtime teams, seats, final decider, delegation strategy, and runtime policy. Corporate is read-only; saved orgs are editable. | -| `Architecture` | Browse built-in architecture presets, preview/apply packages, manage installed packages, and import/export YAML. | -| `Employees` | Search talent templates, view details, hire into vacant roles, and staff the company. | +| `Team` | 查看/编辑角色图谱、表格、角色检查器、花名册、已保存组织选择器、导出打包流程，并把已录用员工部署到办公室。 | +| `Runtime` | 调整运行时团队、座位、最终决策者、委派策略与运行时策略。Corporate 为只读；已保存的组织可编辑。 | +| `Architecture` | 浏览内置架构预设、预览/应用包、管理已安装的包、导入/导出 YAML。 | +| `Employees` | 搜索人才模板、查看详情、招募到空缺角色、为公司配员。 | -To create a new company: open `Org`, click `New organization`, enter a name, add at least two members with responsibilities and reporting lines, review, and create. OpenOPC saves it automatically and switches the composer to `Company / `. +创建新公司：打开 `Org`，点击 `New organization`，输入名称，添加至少两名带职责与汇报关系的成员，检查并创建。OpenOPC 会自动保存，并把输入框切换为 `Company / <你的组织>`。 -To recruit: import talent templates first, then open `Org -> Employees`, search a template, click `Hire`, choose a vacant role, and deploy the employee from `Team Roster` if you want it visible in the Office page. +招募：先导入人才模板，然后打开 `Org -> Employees`，搜索模板，点击 `Hire`，选择一个空缺角色；若希望员工出现在 Office 页面，再从 `Team Roster` 部署。 ```bash opc talent import /path/to/agency-agents ```
-Where project files live +项目文件的位置 -OpenOPC separates runtime/config state from deliverable workspace files. +OpenOPC 把运行时/配置状态与交付物工作区文件分开存放。 -| Path | Meaning | +| 路径 | 含义 | |---|---| -| `.opc/config/` | Local config copied from `config/` by `opc init`. | -| `.opc/memory/` | Global and project markdown memory. | -| `.opc/projects//` | Project runtime metadata and task stores. | -| `.opc/ui_state.db` | Office UI chat, channels, and visual agent state. | -| `../OpenOPC_workplace//` | Default project workplace. Agents should write durable project files here. | -| `../OpenOPC_workplace//.opc-comms/` | Internal company-mode comms mailboxes, meetings, and tool-result scratch space. | +| `.opc/config/` | 由 `opc init` 从 `config/` 复制而来的本地配置。 | +| `.opc/memory/` | 全局与项目级 Markdown 记忆。 | +| `.opc/projects//` | 项目运行时元数据与任务存储。 | +| `.opc/ui_state.db` | Office UI 的聊天、频道与可视化 Agent 状态。 | +| `../OpenOPC_workplace//` | 默认项目工作区。Agent 应把持久的项目文件写到这里。 | +| `../OpenOPC_workplace//.opc-comms/` | Company 模式内部通讯信箱、会议与工具结果暂存区。 | -Set `OPC_HOME=/path/to/opc-home` if you want config and runtime state outside the repo. +若希望配置与运行时状态放在仓库之外，设置 `OPC_HOME=/path/to/opc-home`。
-## CLI Guide +## CLI 指南
-Expand the CLI guide — common commands and interactive slash commands +展开 CLI 指南 — 常用命令与交互式斜杠命令 -OpenOPC exposes both high-level natural-language commands and lower-level UI/service commands. +OpenOPC 同时提供高层的自然语言命令与更底层的 UI/服务命令。 -Conceptually OpenOPC has two execution modes: `task` and `company`. Some lower-level CLI/service commands still expose `org` as a compatibility selector for Company Mode with a saved organization architecture; in the UI this appears as Company plus an architecture choice. +概念上 OpenOPC 有两种执行模式：`task` 与 `company`。部分底层 CLI/服务命令仍将 `org` 作为「Company 模式 + 已保存组织架构」的兼容选择器；在 UI 中这表现为 Company 加一个架构选择。 -### Common Commands +### 常用命令 ```bash -# Chat +# 聊天 opc chat opc chat -p demo --mode task --agent native "Inspect the failing tests" opc chat -p demo --mode company --company-profile corporate "Ship this change with review" -# Scriptable execution +# 可脚本化执行 opc exec -p demo --mode task --agent codex --stream-json "Run the migration check" opc exec -p demo --mode company --company-profile corporate "Draft the research report" -# Project lifecycle +# 项目生命周期 opc project list opc project create demo opc project switch demo -# Sessions +# 会话 opc session list -p demo opc session create "New feature" -p demo --mode company opc session send "Continue with implementation" -p demo opc session stop -p demo opc session continue "Proceed after review" -p demo -# Runtime inspection +# 运行时检查 opc runtime status -p demo opc runtime logs -p demo opc work-item list -p demo opc work-item show -p demo opc comms state -p demo -# Recruitment +# 招募 opc talent import /path/to/agency-agents opc talent hire -p demo ``` -### Interactive Slash Commands +### 交互式斜杠命令 -Run `opc chat`, then use slash commands: +运行 `opc chat`，然后使用斜杠命令： ```text /status @@ -512,27 +507,27 @@ Run `opc chat`, then use slash commands: /market list ``` -See [`docs/cli-chat-slash.md`](docs/cli-chat-slash.md) for the full command table. +完整命令表见 [`docs/cli-chat-slash.md`](docs/cli-chat-slash.md)。
-CLI command groups +CLI 命令分组 -| Group | Examples | +| 分组 | 示例 | |---|---| -| `opc project` | `list`, `show`, `create`, `switch`, `rename`, `delete --yes` | -| `opc session` | `list`, `create`, `show`, `config`, `send`, `rename`, `delete --yes`, `stop`, `continue`, `resume`, `complete` | -| `opc mode` | `show`, `set task`, `set company --profile corporate`, `set org --org ` for a saved-org company run | -| `opc kanban` | `view`, `task create`, `task update`, `task move`, `task assign`, `task status`, `task delete --yes` | -| `opc agent` | `list`, `create`, `create-from-template`, `import-employee`, `detail`, `move`, `delete --yes` | -| `opc org` | `info`, `export`, `import`, `saved list/save/load/delete`, `role add/update/bulk-add/delete`, `policy update`, `strategy update`, `reset --yes` | -| `opc talent` | `list`, `employees`, `import`, `hire`, `scan`, `import-selected`, `employee-detail`, `import-agent` | -| `opc market` | `presets`, `browse`, `preview`, `apply-preset`, `export`, `install`, `list`, `uninstall --yes` | -| `opc runtime` | `status`, `checkpoints`, `logs`, `run` | -| `opc channels` | `status`, `login`, `start`, `stop` | +| `opc project` | `list`、`show`、`create`、`switch`、`rename`、`delete --yes` | +| `opc session` | `list`、`create`、`show`、`config`、`send`、`rename`、`delete --yes`、`stop`、`continue`、`resume`、`complete` | +| `opc mode` | `show`、`set task`、`set company --profile corporate`、以及用于已保存组织公司运行的 `set org --org ` | +| `opc kanban` | `view`、`task create`、`task update`、`task move`、`task assign`、`task status`、`task delete --yes` | +| `opc agent` | `list`、`create`、`create-from-template`、`import-employee`、`detail`、`move`、`delete --yes` | +| `opc org` | `info`、`export`、`import`、`saved list/save/load/delete`、`role add/update/bulk-add/delete`、`policy update`、`strategy update`、`reset --yes` | +| `opc talent` | `list`、`employees`、`import`、`hire`、`scan`、`import-selected`、`employee-detail`、`import-agent` | +| `opc market` | `presets`、`browse`、`preview`、`apply-preset`、`export`、`install`、`list`、`uninstall --yes` | +| `opc runtime` | `status`、`checkpoints`、`logs`、`run` | +| `opc channels` | `status`、`login`、`start`、`stop` | -Most service-style commands accept `--project/-p` and `--json`. +大多数服务类命令都支持 `--project/-p` 与 `--json`。 -For saved organization architectures, some CLI/service commands currently use `org` as a compatibility selector even though the conceptual runtime is still Company Mode: +对于已保存的组织架构，部分 CLI/服务命令目前将 `org` 作为兼容选择器使用，尽管概念上的运行时仍是 Company 模式： ```bash opc exec -p demo --mode org --org hku_research_lab "Draft the research report" @@ -542,79 +537,78 @@ opc session create "Research sprint" -p demo --mode org --org hku_research_lab
-## Configuration +## 配置 -Run `opc init` once from the repo root. It creates `.opc/`, copies the template config from `config/`, creates memory/skills/log folders, and optionally creates the first project. +在仓库根目录运行一次 `opc init`。它会创建 `.opc/`、从 `config/` 复制模板配置、创建记忆/技能/日志目录，并可选地创建第一个项目。
-Expand configuration — config files, LLM keys, external agents, channels, browser/MCP, troubleshooting +展开配置 — 配置文件、LLM 密钥、外部 Agent、频道、浏览器/MCP、故障排查 -| File | Purpose | +| 文件 | 用途 | |---|---| -| `.opc/config/llm_config.yaml` | Default model, LiteLLM/OpenRouter-compatible API base, API key, env var indirection, routing, fallback, temperature, token limit. | -| `.opc/config/system_config.yaml` | Runtime behavior, browser tools, native runtime, compaction, verification, permissions, sandbox, and safety settings. | -| `.opc/config/agent_config.yaml` | External agent command paths, preferred order, model flags, session modes, timeouts, approval modes, and native subagent profiles. | -| `.opc/config/channel_config.yaml` | External messaging providers and credentials. Inbound sender lists are deny-by-default. | -| `.opc/config/company_corporate_config.yaml` | Built-in corporate company architecture template. | -| `.opc/config/company_orgs/org__config.yaml` | Saved custom company architectures used by Company Mode. | -| `.opc/config/org_index.yaml` | Active saved company architecture selector. | +| `.opc/config/llm_config.yaml` | 默认模型、兼容 LiteLLM/OpenRouter 的 API base、API key、环境变量间接引用、路由、回退、temperature、token 限制。 | +| `.opc/config/system_config.yaml` | 运行时行为、浏览器工具、原生运行时、压缩、验证、权限、沙箱与安全设置。 | +| `.opc/config/agent_config.yaml` | 外部 Agent 命令路径、优先顺序、模型参数、会话模式、超时、审批模式与原生子 Agent 配置。 | +| `.opc/config/channel_config.yaml` | 外部消息提供方与凭据。入站发送者列表默认拒绝。 | +| `.opc/config/company_corporate_config.yaml` | 内置 Corporate 公司架构模板。 | +| `.opc/config/company_orgs/org__config.yaml` | Company 模式使用的自定义公司架构。 | +| `.opc/config/org_index.yaml` | 当前生效的已保存公司架构选择器。 | -### LLM Keys +### LLM 密钥 -After `opc init`, edit `.opc/config/llm_config.yaml` in the repo-local OPC home. If you set `OPC_HOME`, edit `$OPC_HOME/config/llm_config.yaml` instead. +运行 `opc init` 后，编辑仓库本地 OPC home 中的 `.opc/config/llm_config.yaml`。如果设置了 `OPC_HOME`，则改为编辑 `$OPC_HOME/config/llm_config.yaml`。 -The template leaves secrets empty. Write your key directly into the file: +模板中的密钥留空。直接把 key 写入文件： ```yaml llm: default_model: "openai/gpt-5.4" api_base: "https://openrouter.ai/api/v1" - api_key: "sk-or-v1-..." # your OpenRouter (or other provider) API key + api_key: "sk-or-v1-..." # 你的 OpenRouter（或其他提供方）API key - max_tokens: 32768 # max output tokens per request; lower it if your - # model's output cap is smaller - # context_window: 128000 # total input window. Usually auto-detected via - # litellm; unmapped models fall back to 128000. - # Uncomment and set only when the fallback is - # wrong for your model. + max_tokens: 32768 # 每次请求的最大输出 token；如果你的模型 + # 输出上限更小，请调低 + # context_window: 128000 # 总输入窗口。通常由 litellm 自动检测； + # 未收录的模型回退为 128000。仅当回退值 + # 不适合你的模型时才取消注释并设置。 ``` -Then verify with `opc status`. +然后用 `opc status` 验证。 -If you prefer not to store the key in the file, leave `api_key` empty and set `api_key_env` to the name of an environment variable that holds it (e.g. `api_key_env: "OPENROUTER_API_KEY"`). +如果不想把密钥存在文件里，可以将 `api_key` 留空，并把 `api_key_env` 设置为持有密钥的环境变量名（例如 `api_key_env: "OPENROUTER_API_KEY"`）。 -### Approval & Agent Permissions +### 审批与 Agent 权限 -The `autonomy` section of `.opc/config/system_config.yaml` controls how much an agent can do without asking. The key knob is `max_auto_approve_risk` — the highest risk level that can be auto-approved: +`.opc/config/system_config.yaml` 的 `autonomy` 部分控制 Agent 无需询问即可执行多少操作。关键旋钮是 `max_auto_approve_risk` — 可被自动批准的最高风险等级： ```yaml autonomy: max_auto_approve_risk: medium # low | medium | high | critical allow_native_tool_auto_approval: true - tool_first_use_approval: true # first use of each tool always asks + tool_first_use_approval: true # 每个工具首次使用时总是询问 ``` -Every native tool call is risk-classified before it runs: known destructive commands (`rm -rf`, `drop table`, force-push, …) and sensitive keywords (credentials, deploys, …) are `high`/`critical` and always escalate to a human; allowlisted safe prefixes (`ls`, `git status`, …) are `low`; everything else is `medium` and goes through an LLM review before auto-approval. +每次原生工具调用在运行前都会做风险分级：已知的破坏性命令（`rm -rf`、`drop table`、force-push 等）与敏感关键词（凭据、部署等）为 `high`/`critical`，总是上报给人类；白名单中的安全前缀（`ls`、`git status` 等）为 `low`；其余为 `medium`，在自动批准前会经过 LLM 审查。 -- `medium` (default): balanced — ordinary commands run without prompts; dangerous ones escalate. -- `low`: strict — anything not on the safe allowlist asks for approval. Recommended for shared or production machines. -- `high`/`critical`: permissive — only for throwaway sandboxes. +- `medium`（默认）：平衡 — 普通命令无提示运行；危险命令上报。 +- `low`：严格 — 不在安全白名单中的任何操作都需要审批。推荐用于共享或生产机器。 +- `high`/`critical`：宽松 — 仅用于可随时丢弃的沙箱。 -The first time a tool is used you are always prompted (unless the tool is in `tool_approval_exemptions`), and your "Always allow" choices accumulate in a per-project allowlist. +每个工具首次使用时总会提示（除非该工具在 `tool_approval_exemptions` 中），你的「始终允许」选择会累积到项目级白名单。 -### External Agents +### 外部 Agent -Task Mode can explicitly select an execution agent: +Task 模式可以显式选择执行 Agent： ```bash opc chat -p demo --mode task --agent codex "Implement the change" ``` -Available values are `native`, `codex`, `claude_code`, `cursor`, and `opencode`. Configure command names, flags, timeouts, session reuse, and approval behavior in `.opc/config/agent_config.yaml`. +可用值有 `native`、`codex`、`claude_code`、`cursor` 与 `opencode`。在 `.opc/config/agent_config.yaml` 中配置命令名、参数、超时、会话复用与审批行为。 -In Company Mode, roles can prefer external agents through their role config or the Org role inspector. A role can use `auto`, `native`, or `external` execution strategy, with an optional preferred external agent. +在 Company 模式下，角色可以通过角色配置或 Org 角色检查器指定偏好的外部 Agent。角色的执行策略可以是 `auto`、`native` 或 `external`，并可选地指定偏好的外部 Agent。 -### Feishu Connection +### 飞书接入 ```bash pip install -e .[channels-feishu] @@ -622,7 +616,7 @@ opc init opc channels login feishu ``` -Edit `.opc/config/channel_config.yaml`: +编辑 `.opc/config/channel_config.yaml`： ```yaml channels: @@ -637,33 +631,33 @@ channels: - "ou_xxx" ``` -Then: +然后： ```bash opc channels status opc channels start -p demo -# or run the long-lived engine + channel runtime: +# 或运行常驻引擎 + 频道运行时： opc run -p demo ``` -Feishu uses the `lark-oapi` WebSocket client. `app_id` and `app_secret` are required; `encrypt_key` and `verification_token` are optional unless your tenant/app configuration requires them. Keep `allow_from` explicit; an empty list denies all inbound messages. +飞书使用 `lark-oapi` WebSocket 客户端。`app_id` 与 `app_secret` 为必填；`encrypt_key` 与 `verification_token` 为可选，除非你的租户/应用配置要求。请保持 `allow_from` 显式配置；空列表会拒绝所有入站消息。
-Other channel providers +其他频道提供方 -| Provider | Install extra | Runtime | Required fields | +| 提供方 | 安装 extra | 运行方式 | 必填字段 | |---|---|---|---| | Telegram | `channels-telegram` | polling | `token` | -| Slack | `channels-slack` | socket | `bot_token`, `app_token` | +| Slack | `channels-slack` | socket | `bot_token`、`app_token` | | Discord | `channels-discord` | socket | `token` | -| DingTalk | `channels-dingtalk` | socket | `client_id`, `client_secret` | -| Email | `channels-email` | polling | IMAP/SMTP fields, `consent_granted` | -| Matrix | `channels-matrix` | sync/polling | `homeserver`, `access_token`, `user_id` | -| QQ | `channels-qq` | socket | `app_id`, `secret` | +| 钉钉 | `channels-dingtalk` | socket | `client_id`、`client_secret` | +| 邮件 | `channels-email` | polling | IMAP/SMTP 字段、`consent_granted` | +| Matrix | `channels-matrix` | sync/polling | `homeserver`、`access_token`、`user_id` | +| QQ | `channels-qq` | socket | `app_id`、`secret` | | WhatsApp | `channels-whatsapp` | bridge | `bridge_url` | -| Mochat | `channels-mochat` | bridge | `base_url`, `claw_token`, `agent_user_id` | +| Mochat | `channels-mochat` | bridge | `base_url`、`claw_token`、`agent_user_id` | -Useful commands: +常用命令： ```bash opc channels login slack @@ -673,19 +667,19 @@ opc channels stop opc run -p demo ``` -See [`docs/channels.md`](docs/channels.md) and [`docs/channel-bridges.md`](docs/channel-bridges.md). +参见 [`docs/channels.md`](docs/channels.md) 与 [`docs/channel-bridges.md`](docs/channel-bridges.md)。
-Browser tools and MCP servers +浏览器工具与 MCP 服务器 -Browser tools: +浏览器工具： ```bash python -m playwright install chromium ``` -Configure launch behavior in `.opc/config/system_config.yaml`: +在 `.opc/config/system_config.yaml` 中配置启动行为： ```yaml system: @@ -696,27 +690,27 @@ system: user_data_dir: "" ``` -Native browser tools include `browser_navigate`, `browser_snapshot`, `browser_click`, `browser_type`, `browser_wait_for`, `browser_scroll`, `browser_select_option`, `browser_evaluate`, `browser_take_screenshot`, and `browser_close`. +原生浏览器工具包括 `browser_navigate`、`browser_snapshot`、`browser_click`、`browser_type`、`browser_wait_for`、`browser_scroll`、`browser_select_option`、`browser_evaluate`、`browser_take_screenshot` 与 `browser_close`。 -MCP servers can be added under `mcp_servers` in `system_config.yaml`. Local servers use stdio commands; remote servers use HTTP/SSE-style URLs. Discovered tools are registered with a server prefix to avoid collisions. +MCP 服务器可添加到 `system_config.yaml` 的 `mcp_servers` 下。本地服务器使用 stdio 命令；远程服务器使用 HTTP/SSE 风格的 URL。发现的工具会以服务器前缀注册，避免命名冲突。
-### Troubleshooting +### 故障排查
-Office UI does not open or looks stale +Office UI 无法打开或界面陈旧 ```bash opc ui --rebuild ``` -If the browser still shows stale UI state, hard refresh the page. If a previous process died mid-run, restart `opc ui` first so in-memory locks are released. +如果浏览器仍显示陈旧的 UI 状态，强制刷新页面。如果之前的进程在运行中途崩溃，先重启 `opc ui` 以释放内存中的锁。
-A task appears stuck +任务看起来卡住了 -Start with a server restart and browser hard refresh. If persisted task state is still dirty, use the reset helper: +先重启服务器并强制刷新浏览器。如果持久化的任务状态仍然异常，使用重置工具： ```bash python scripts/reset_stuck_task.py --project --session --apply @@ -725,102 +719,101 @@ python scripts/reset_stuck_task.py --all --apply
-External agent is not available +外部 Agent 不可用 -Run: +运行： ```bash opc status ``` -Check `.opc/config/agent_config.yaml` for command names such as `codex`, `claude`, `cursor-agent`, and `opencode`. Disable or reprioritize agents you do not have installed. +检查 `.opc/config/agent_config.yaml` 中的命令名，例如 `codex`、`claude`、`cursor-agent` 与 `opencode`。禁用或调整你未安装的 Agent 的优先级。
-Channel provider receives no messages +频道提供方收不到消息 -Check: +检查： -- The provider extra is installed, for example `pip install -e .[channels-feishu]`. -- The provider is `enabled: true`. -- Required credentials are filled. -- `allow_from` contains the sender IDs you expect. -- `opc channels status` reports the provider as configured and available. +- 已安装对应的 extra，例如 `pip install -e .[channels-feishu]`。 +- 该提供方为 `enabled: true`。 +- 必填凭据已填写。 +- `allow_from` 包含你期望的发送者 ID。 +- `opc channels status` 显示该提供方已配置且可用。
-## Ecosystem And Sharing +## 生态与分享 -Everything OpenOPC builds is yours to keep, reuse, and share — organizations, employees, talent templates, skills, and channels are just files. Import a popular talent library, reuse a team across projects, or package a whole company as a shareable `.opcpkg`. +OpenOPC 构建的一切都归你所有，可以保留、复用与分享 — 组织、员工、人才模板、技能与频道都只是文件。你可以导入一个流行的人才库、跨项目复用一个团队，或者把整个公司打包成可分享的 `.opcpkg`。 ```bash -# Hire from a talent library (e.g. agency-agents) into a role +# 从人才库（例如 agency-agents）招募到某个角色 opc talent import /path/to/agency-agents opc talent hire -p demo -# Reuse or share a whole organization +# 复用或分享整个组织 opc org export --json > my-org.yaml opc market export --id hku_lab --name "HKU Lab" --output-dir packages opc market install packages/hku_lab.opcpkg ``` - - -## Roadmap - -OpenOPC is moving quickly. The areas below reflect active development priorities — each grounded in real gaps identified during early usage. - -| Area | Planned direction | +| 领域 | 计划方向 | |---|---| -| **Role-level skills** | Role config already carries `skill_refs`, and the Org UI surfaces skill metadata today. The next step is letting users select which skills mount to which roles directly from the Org page — feeding into a broader self-evolving skill ecosystem. | -| **Secretary settings** | The secretary will grow into a stronger configuration and memory steward: owning OPC system memory, analysing and comparing projects, and providing guided setup for OpenOPC YAML configuration. | -| **Company-mode channels** | External channels will evolve beyond simple chat entrypoints into richer company-mode workflows — with role-aware notifications, structured approvals, and cross-platform collaboration. | -| **CLI parity** | The CLI is functional today, but the Office UI remains the more complete surface. Upcoming work targets org editing, company-mode inspection, failure recovery, and long-running runtime control from the terminal. | -| **TUI** | A full terminal UI is under consideration once CLI parity matures. The Office UI remains the primary interface in the meantime. | -| **Market and presets** | More architecture presets, recruitable talent packs, import/export workflows, and a package marketplace for sharing and discovering community-built components. | -| **Runtime polish** | Continued improvements to recovery, checkpointing, execution-progress visibility, and visual documentation — making long company runs more observable and resilient. | +| **角色级技能** | 角色配置已支持 `skill_refs`，Org UI 目前也展示技能元数据。下一步是让用户直接在 Org 页面选择哪些技能挂载到哪些角色 — 汇入更广泛的自演化技能生态。 | +| **秘书设置** | 秘书将成长为更强的配置与记忆管家：负责 OPC 系统记忆、分析与对比项目，并为 OpenOPC YAML 配置提供引导式设置。 | +| **Company 模式频道** | 外部频道将从简单的聊天入口演进为更丰富的 Company 模式工作流 — 支持角色感知的通知、结构化审批与跨平台协作。 | +| **CLI 对齐** | CLI 目前可用，但 Office UI 仍是更完整的界面。后续工作聚焦于从终端进行组织编辑、Company 模式检查、故障恢复与长时运行时控制。 | +| **TUI** | CLI 对齐成熟后将考虑完整的终端 UI。在此期间 Office UI 仍是主要界面。 | +| **市场与预设** | 更多架构预设、可招募的人才包、导入/导出工作流，以及用于分享与发现社区组件的包市场。 | +| **运行时打磨** | 持续改进恢复、检查点、执行进度可见性与可视化文档 — 让长时间的公司运行更可观察、更有韧性。 | -## Acknowledgements +## 本地修改（与原仓库对比） -OpenOPC is built with gratitude for several open-source projects that helped shape its agent design, skill structure, and talent template ecosystem: +本仓库是上游 [OpenOPC](https://github.com/HKUDS/OpenOPC) 项目的**镜像/托管副本**，由 **Gitinbox** 组织托管，用于内部 AI Agent 平台使用与本地化协作。 -- [openai/codex](https://github.com/openai/codex/) for inspiring practical coding-agent workflows and execution patterns. -- [BloopAI/vibe-kanban](https://github.com/BloopAI/vibe-kanban) for inspiration around kanban-centered agent work management and task visibility. -- [msitarzewski/agency-agents](https://github.com/msitarzewski/agency-agents) for the talent-template foundation. All talent templates included in this repository are imported from `agency-agents`. -- [HKUDS/nanobot](https://github.com/HKUDS/nanobot) for inspiration around skill-oriented agent design and `SKILL.md`-style organization. -- [pixel-agents-hq/pixel-agents](https://github.com/pixel-agents-hq/pixel-agents) for inspiration around the animated pixel-art office visualization of agent activity. +### 与原仓库的差异（[`HKUDS/OpenOPC`](https://github.com/HKUDS/OpenOPC/tree/main)） + +| 领域 | 原仓库 | 本仓库 | +|---|---|---| +| **默认 README** | `README.md`（英文） | **中文**（本文件），英文版保留为 [`README.en.md`](README.en.md) | +| **代码与功能** | 原版 | **与原仓库一致**，暂无额外代码修改 | +| **许可证文件** | 徽章标注 MIT，但仓库**未包含 `LICENSE` 文件** | 同上游（未添加） | + +> ⚠️ 上游仓库徽章显示 MIT 许可，但截至同步日期，仓库根目录**没有** `LICENSE` 文件。使用前请自行确认授权条款。 + +与上游保持同步： + +```bash +git remote add upstream https://github.com/HKUDS/OpenOPC.git # 仅首次 +git fetch upstream && git merge upstream/main +``` + +**上游仓库：** + +> 英文版：请查看 [README.en.md](README.en.md) + +--- + +## 致谢 + +OpenOPC 的 Agent 设计、技能结构与人才模板生态受益于多个开源项目，在此致谢： + +- [openai/codex](https://github.com/openai/codex/) 启发了实用的编码 Agent 工作流与执行模式。 +- [BloopAI/vibe-kanban](https://github.com/BloopAI/vibe-kanban) 启发了以看板为中心的 Agent 工作管理与任务可见性。 +- [msitarzewski/agency-agents](https://github.com/msitarzewski/agency-agents) 提供了人才模板的基础。本仓库包含的所有人才模板均导入自 `agency-agents`。 +- [HKUDS/nanobot](https://github.com/HKUDS/nanobot) 启发了面向技能的 Agent 设计与 `SKILL.md` 风格的组织方式。 +- [pixel-agents-hq/pixel-agents](https://github.com/pixel-agents-hq/pixel-agents) 启发了以像素动画办公室可视化 Agent 活动的方式。 ---

- ❤️ Thanks for visiting ✨ OpenOPC!

+ ❤️ 感谢访问 ✨ OpenOPC！

Views

diff --git a/README.zh-CN.md b/README.zh-CN.md deleted file mode 100644 index fe78cc3..0000000 --- a/README.zh-CN.md +++ /dev/null @@ -1,791 +0,0 @@ -

OpenOPC：打造你的个人 AI 原生公司 — 自建、自营、自成长

- -

- English | 简体中文 -

- -🏗️ **自建（Self-Built）** — 全自动招募各岗位的 AI 员工，搭建组织架构。 - -⚙️ **自营（Self-Run）** — 全自动分派任务、驱动交接，持续朝你的目标推进。 - -🌱 **自成长（Self-Grown）** — 从每个任务中学习，沉淀组织记忆，交付越来越聪明。 - -

- Python 3.10+ - Office UI - CLI and UI - License MIT - Feishu - WeChat -

- -![OpenOPC hero banner](docs/assets/chat.png) - -## 目录 - -- [何时使用 OpenOPC](#何时使用-openopc) -- [演示](#演示) -- [OpenOPC 如何工作](#openopc-如何工作) -- [快速开始](#快速开始) -- [Office UI 指南](#office-ui-指南) -- [CLI 指南](#cli-指南) -- [配置](#配置) -- [生态与分享](#生态与分享) -- [路线图](#路线图) -- [致谢](#致谢) - -## 何时使用 OpenOPC - -**OpenOPC** 覆盖九大核心垂直领域 — 从 AI 开发、软件工程到金融、销售、媒体、电商与教育。无论哪个行业，OpenOPC 都会组建合适的团队并端到端交付。 - - - - - - - - - - - - - - - - - -
-
🤖 AI 技术与研究 -
模型训练与评估、Agent 开发、LLM 应用与 AI 基础设施 - 		-
💻 软件开发 -
Android 应用、SaaS MVP、网站、小程序与游戏开发 - 		-
📈 金融投资 -
投资备忘录、市场图谱、尽职调查与投决会材料 -
- 🚀 销售增长 -
外呼销售、交易策略、方案书与渠道拓展 - 		- 🎬 内容与媒体 -
视频制作、短视频内容、脚本、分镜与多平台剪辑 - 		- 🤝 行业助理 -
客服、房产、法律咨询、HR 入职、零售等场景的 Copilot -
- 🧾 会计与财务 -
记账、财务报告、税务合规、预算与风险审查 - 		- 🛍️ 品牌与电商 -
品牌规划、选品、店铺运营、用户增长与留存 - 		- 🎓 教育与培训 -
课程设计、知识库、学员管理与内容生产 -
- -## 演示 - - - - - - - -
- - OpenOPC 视频制作演示 - -

- 🎬 视频制作 - 		- - OpenOPC VC 投资研究演示 - -

- 📈 投资研究 - 		- - OpenOPC 游戏原型演示 - -

- 🎮 游戏原型 -
- -## OpenOPC 如何工作 - -OpenOPC 围绕复杂的真实任务组建一家 AI 公司 — 通过三个紧密耦合的机制：**自建**负责组织配员，**自营**负责执行工作，**自成长**负责从结果中学习。 - -

- 一家 OpenOPC 公司：角色、汇报关系，以及每个角色配备的员工 -

- -**1. 自建 — 为组织配员** - -在任何工作开始之前，必须先把合适的人放到合适的位置。给定一个目标，OpenOPC 会： - -- 🌿 起草组织架构图 — 从任务需求推导出所需的角色与汇报结构。 -- 🎯 填补每个角色 — 由招聘 Agent 在「复用现有员工（带着以往项目塑造的经验）」与「从人才池中招募新人」之间做出选择。 - -💡 有经验的员工携带积累的上下文；当角色需要时，新员工则提供一张白纸。 - -**⚙️ 2. 自营 — 执行工作** - -团队组建完成后，自营机制协调成员产出最终交付物。核心挑战不在于单纯执行，而在于不确定性下的高效协作，具体体现为两个问题。 - -🔀 动态协作编排。真实工作无法完全提前规划。OpenOPC 通过工作项状态机来解决，每个工作项所处的阶段决定： - -- 📋 它在看板的哪一列 — 处于工作流的哪个位置。 -- 👑 它的负责人 — 该阶段由哪个角色负责。 -- ✅ 它的可执行性 — 是否已经具备推进条件。 - -管理者负责拆解工作项、分派并评审结果 — 接受、返工或上报 — 覆盖五种模式：执行（execute）、委派（delegate）、评审（review）、集成（integrate）与返工（rework）。拆解定义了一个依赖 DAG，因此： - -- ⚡ 相互独立的工作项并行推进。 -- ⏳ 有依赖的工作项等待前置项完成。 - -🔗 依赖解除与驳回都作为结构化的阶段转换传播，消除了临时的人为协调。 - -🛡️ 处理运行中途出现的阻塞。并非所有障碍都能提前预见。OpenOPC 在两个层面解决： - -- 💬 团队内部 — 一条阻塞消息会暂停发送者，并激活最适合解决该问题的角色。 -- 📡 团队之外 — 当阻塞超出团队权限时，运行时会上报给人类所有者，在真正需要时引入人类判断。 - -🖥️ 看板与办公室视图实时呈现这一编排过程。 - -**🌱 3. 自成长 — 从运行中学习** - -执行产生原始经验；自成长把它转化为持久的改进，遵循两条原则。 - -🏅 把结果归因到正确的角色。把功劳记给整个公司学不到任何东西。因此 OpenOPC： - -- 🔍 将用户反馈解析为针对每位员工的评估。 -- 🎯 只更新负责了相关工作项的角色 — 功与过都落到应得之处。 - -📖 把执行轨迹提炼为知识。执行轨迹噪声太大，无法直接学习。因此 OpenOPC： -- 💡 把每个角色的任务提炼为高信号的经验教训，存入其私有经验档案。 -- 📚 把反复出现的经验提升为共享的作业手册（playbook），新员工从入职起即可继承 — 让组织知识随时间复利增长。 - -
-这些机制如何对应到 UI - -- `Org -> Team` 编辑公司架构与角色。 -- `Org -> Employees` 为空缺角色招募人才。 -- `Team Roster -> Deploy` 把已录用的员工变成办公室中可见的 Agent。 -- Workspace 输入框可选择 Task 模式的执行 Agent。 -- 角色检查器可为 Company 模式的角色设置运行时策略与偏好的外部 Agent。 -- 执行期间，Workspace 的 `Agents` 页签与 Execution Progress 面板会显示哪个角色处于活动状态、它负责哪个工作项、以及由哪个执行 Agent 完成具体工作。 -
- -## 快速开始 - -推荐使用 `uv` 来安装 OpenOPC。它可以安装/管理 Python、创建项目虚拟环境，并在该环境中运行命令，而不会把 OpenOPC 的依赖混入全局 Python。 - -OpenOPC 要求 Python `>=3.10`；下面的示例使用 Python `3.12`。 - -对于直接的一次性工作，OpenOPC 还提供 Task 模式 — 一个类 LobeChat 的单 Agent 工作台，可使用 OpenOPC Native、Codex、Claude Code、Cursor 或 OpenCode。 - -
-推荐：uv 环境搭建 - -**macOS** - -```bash -# 使用 Homebrew 安装 uv，或使用官方独立安装脚本。 -brew install uv -# curl -LsSf https://astral.sh/uv/install.sh | sh - -cd /path/to/OpenOPC -uv python install 3.12 -uv venv --python 3.12 -source .venv/bin/activate -``` - -**Linux** - -```bash -curl -LsSf https://astral.sh/uv/install.sh | sh -source "$HOME/.local/bin/env" - -cd /path/to/OpenOPC -uv python install 3.12 -uv venv --python 3.12 -source .venv/bin/activate -``` - -**Windows PowerShell** - -```powershell -powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" - -cd C:\path\to\OpenOPC -uv python install 3.12 -uv venv --python 3.12 -.\.venv\Scripts\Activate.ps1 -``` - -**Windows 命令提示符** - -```bat -winget install --id=astral-sh.uv -e -:: 或在 cmd 中运行独立安装脚本： -:: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" - -cd C:\path\to\OpenOPC -uv python install 3.12 -uv venv --python 3.12 -.venv\Scripts\activate.bat -``` -
- -```bash -# 将 OpenOPC 安装到 uv 管理的环境中 -uv pip install -e . - -# 可选但推荐：安装浏览器工具所需的 Chromium -uv run python -m playwright install chromium - -# 初始化本地配置、记忆、技能、项目与工作区目录 -uv run opc init - -# 在 .opc/config/llm_config.yaml 中填入 API key， -# 或配置 llm.api_key_env 指定的环境变量。 - -# 启动浏览器 UI -uv run opc ui -``` - -默认打开 `http://localhost:8765`。 - -```bash -# 交互式 CLI -uv run opc chat -p demo - -# 一次性 Task 模式 -uv run opc chat -p demo --mode task --agent codex "Refactor this module and run focused tests" - -# 使用内置 Corporate 架构的 Company 模式 -uv run opc chat -p demo --mode company --company-profile corporate "Plan, implement, review, and document this feature" - -# 非交互脚本 / CI 风格用法 -uv run opc exec -p demo --mode task --agent native --json "Summarize the current repo status" -``` - -
-安装说明 - -- Python：`>=3.10`。当前必需依赖并非全部提供兼容 Python 3.9 的版本。 -- 本地开发与发布测试推荐使用 `uv`。如果你偏好经典 pip，请创建并激活一个 Python `>=3.10` 的虚拟环境，然后运行 `python -m pip install -e .`。 -- 如果虚拟环境激活被阻止，可以不激活，直接用 `uv run ...` 运行命令。 -- 关于其他包管理器与托管 Python 的细节，参见官方 [`uv` 安装文档](https://docs.astral.sh/uv/getting-started/installation/) 与 [Python 管理文档](https://docs.astral.sh/uv/guides/install-python/)。 -- Node.js：需要构建 Office UI 前端时要求 `>=18`。 -- `opc ui` 会自动安装缺失的 `aiohttp` / `aiosqlite`，并在需要时自动构建前端。 -- 如果你尚未安装外部 Agent CLI，运行 `opc init --no-external-agent-preflight` 可跳过首次运行的外部 Agent 检查。 -- 浏览器工具基于原生 Playwright。在让 Agent 浏览网页之前，先用 `python -m playwright install chromium` 安装 Chromium。 -
- -
-开发环境搭建（从源码构建） - -```bash -python -m pip install -e . -python -m pytest - -cd opc/plugins/office_ui/frontend_src -npm install -npm run typecheck -npm run build -``` - -前端构建产物从 `opc/plugins/office_ui/frontend_dist/` 提供服务。 -
- -## Office UI 指南 - -
-展开 Office UI 指南 — 视觉导览、工作台、Company 模式、看板、办公室、组织 - -启动方式： - -```bash -opc ui -opc ui --port 9000 --project demo -opc ui --rebuild -``` - -### 视觉导览 - -横向滚动浏览 Office UI 演示。每张截图都附有简短的说明文字。 - -
-
-
- Workspace 的项目、聊天、模式、组织与 Agent 控件 -
工作台与初始设置。选择或创建项目，点击 New Chat，然后选择 Company 或 Task 以及对应的组织或 Agent。在 Company 模式下，可以指定角色员工与执行 Agent，也可以让 OpenOPC 自动招募。
-
-
- Execution Progress 面板显示角色状态与执行记录 -
执行进度。跟踪每个角色的状态，点击角色或工作项即可查看详细的执行记录、工具活动、交接、评审与运行时元数据。
-
-
- 看板展示 Agent 的工作项与状态 -
看板。监督每个 Agent 的具体任务与工作项，观察它们在规划、执行、评审、阻塞与完成之间流转。
-
-
- 组织编辑器，可调整现有组织或新建组织 -
组织管理。调整现有组织、修改角色与汇报关系、查看运行时策略，或创建一个新组织。
-
-
- 人才市场，可浏览并招募员工 -
人才市场。浏览人才模板，查看候选人详情，在公司需要更多能力时把员工招募到空缺角色上。
-
-
- 动画办公室视图，展示每个角色正在做什么 -
办公室视图。以动画办公室的形式观察整个组织，每个角色/Agent 都会显示状态、当前任务、正在使用的工具、座位与运行时活动。
-
-
-
- -Office UI 有三个主要页面： - -| 页面 | 在这里做什么 | -|---|---| -| **Workspace** | 主要工作界面：会话列表、看板、聊天、任务详情、角色进度、通讯与团队驾驶舱。 | -| **Office** | 可视化办公室地图：Agent 以角色形象出现，可以选中、移动、分配座位与查看详情。 | -| **Org** | 公司架构：切换 Corporate/已保存的组织、创建新组织、编辑角色、招募人才、应用架构预设、导入/导出配置。 | - -### 工作台（Workspace） - -Workspace 页面是默认界面。 - -| 区域 | 关注点 | -|---|---| -| 左侧边栏 | 项目会话、活动、未读计数与新建聊天。 | -| 中间看板 | 看板卡片。Task 模式下，一张卡片通常对应一个任务型聊天会话。Company 模式下，看板跟随所选的运行时会话，展示已委派的工作项。 | -| 右侧面板 | 上下文面板，包含 `Chat`、`Agents`、`Info`、`Comms`、`Team` 等页签。工作运行期间可以折叠、调整大小或最大化。 | -| 输入框 | 发送消息、附加文件、选择模式、选择公司架构；在 Task 模式下选择执行 Agent。 | - -### 从 UI 开始工作 - -1. 在顶部项目选择器中创建或选择一个项目。 -2. 在 Workspace 中点击 `New Chat`。 -3. 在输入框中选择 `Task` 或 `Company`。 -4. Task 模式下选择 Agent：`OpenOPC Native`、`Codex`、`Claude Code`、`Cursor` 或 `OpenCode`。 -5. Company 模式下选择 `Corporate` 或一个已保存的组织架构。 -6. 发送任务简报。 - -第一条消息发出后，该聊天的模式与任务 Agent 即被锁定。若需换用其他模式，可通过锁定模式的弹出提示在新聊天中继续。 - -### UI 中的 Company 模式 - -Company 模式把一份简报变成一个运行时会话加一组由角色负责的工作项。 - -| 页签 | 展示内容 | -|---|---| -| `Chat` | 父级对话、最终回复、运行时进度卡片、检查点回复、停止/继续/完成控件，以及跳转到工作项执行的链接。 | -| `Agents` | 角色汇总：活动/等待/待定/完成的角色、当前工具、角色工作项、筛选、搜索，以及详细执行进度的链接。 | -| `Info` | 状态、负责人、角色身份、员工分配、所选执行 Agent、时间信息与开发者详情。 | -| `Comms` | 角色收件箱、未读/已读/已发消息、会议、决策与最近的通讯故障。 | -| `Team` | 运行时驾驶舱：团队、座位、审批、未读通讯、恢复状态与当前运行的停止控件。 | - -要查看某个角色的详细工作流，打开一个 Company 模式会话，在 `Chat` 进度卡片或 `Agents` 页签中点击角色/工作项。Execution Progress 面板会展示每个工作项及其状态、活动分区、工具进度、交接、评审对象与执行轮次元数据。 - -### 看板（Kanban） - -- Task 模式：看板是项目级面板。可以在 `Todo` 中快速创建任务、启动任务，并从右侧面板查看每个任务。 -- Company 模式：当前面板跟随所选运行时会话。卡片代表公司工作项，按照后端运行时状态在规划/执行/评审/完成之间流转。 -- 当运行时掌管状态时，跨状态列的手动拖拽会被有意限制。同列内重新排序在适用时是支持的。 - -### 办公室（Office） - -当你想以可视化方式查看运行中的团队时，使用 Office 页面。 - -- 点击 Agent 角色形象或列表行，查看状态、当前工具、当前任务、角色、办公室与座位。 -- 使用办公室/座位控件移动 Agent。 -- 子 Agent 可以显示或隐藏。 -- 由员工或模板创建的 Agent 会出现在办公室中，并持久化在 `.opc/ui_state.db`。 - -### 组织（Org） - -Org 页面是公司结构变得可运行的地方。 - -| 子页签 | 用途 | -|---|---| -| `Team` | 查看/编辑角色图谱、表格、角色检查器、花名册、已保存组织选择器、导出打包流程，并把已录用员工部署到办公室。 | -| `Runtime` | 调整运行时团队、座位、最终决策者、委派策略与运行时策略。Corporate 为只读；已保存的组织可编辑。 | -| `Architecture` | 浏览内置架构预设、预览/应用包、管理已安装的包、导入/导出 YAML。 | -| `Employees` | 搜索人才模板、查看详情、招募到空缺角色、为公司配员。 | - -创建新公司：打开 `Org`，点击 `New organization`，输入名称，添加至少两名带职责与汇报关系的成员，检查并创建。OpenOPC 会自动保存，并把输入框切换为 `Company / <你的组织>`。 - -招募：先导入人才模板，然后打开 `Org -> Employees`，搜索模板，点击 `Hire`，选择一个空缺角色；若希望员工出现在 Office 页面，再从 `Team Roster` 部署。 - -```bash -opc talent import /path/to/agency-agents -``` - -
-项目文件的位置 - -OpenOPC 把运行时/配置状态与交付物工作区文件分开存放。 - -| 路径 | 含义 | -|---|---| -| `.opc/config/` | 由 `opc init` 从 `config/` 复制而来的本地配置。 | -| `.opc/memory/` | 全局与项目级 Markdown 记忆。 | -| `.opc/projects//` | 项目运行时元数据与任务存储。 | -| `.opc/ui_state.db` | Office UI 的聊天、频道与可视化 Agent 状态。 | -| `../OpenOPC_workplace//` | 默认项目工作区。Agent 应把持久的项目文件写到这里。 | -| `../OpenOPC_workplace//.opc-comms/` | Company 模式内部通讯信箱、会议与工具结果暂存区。 | - -若希望配置与运行时状态放在仓库之外，设置 `OPC_HOME=/path/to/opc-home`。 -
- -
- -## CLI 指南 - -
-展开 CLI 指南 — 常用命令与交互式斜杠命令 - -OpenOPC 同时提供高层的自然语言命令与更底层的 UI/服务命令。 - -概念上 OpenOPC 有两种执行模式：`task` 与 `company`。部分底层 CLI/服务命令仍将 `org` 作为「Company 模式 + 已保存组织架构」的兼容选择器；在 UI 中这表现为 Company 加一个架构选择。 - -### 常用命令 - -```bash -# 聊天 -opc chat -opc chat -p demo --mode task --agent native "Inspect the failing tests" -opc chat -p demo --mode company --company-profile corporate "Ship this change with review" - -# 可脚本化执行 -opc exec -p demo --mode task --agent codex --stream-json "Run the migration check" -opc exec -p demo --mode company --company-profile corporate "Draft the research report" - -# 项目生命周期 -opc project list -opc project create demo -opc project switch demo - -# 会话 -opc session list -p demo -opc session create "New feature" -p demo --mode company -opc session send "Continue with implementation" -p demo -opc session stop -p demo -opc session continue "Proceed after review" -p demo - -# 运行时检查 -opc runtime status -p demo -opc runtime logs -p demo -opc work-item list -p demo -opc work-item show -p demo -opc comms state -p demo - -# 招募 -opc talent import /path/to/agency-agents -opc talent hire -p demo -``` - -### 交互式斜杠命令 - -运行 `opc chat`，然后使用斜杠命令： - -```text -/status -/mode task -/mode company corporate -/agent codex -/project switch demo -/session list -/runtime --full -/logs --full -/comms --full -/org -/talent list -/market list -``` - -完整命令表见 [`docs/cli-chat-slash.md`](docs/cli-chat-slash.md)。 - -
-CLI 命令分组 - -| 分组 | 示例 | -|---|---| -| `opc project` | `list`、`show`、`create`、`switch`、`rename`、`delete --yes` | -| `opc session` | `list`、`create`、`show`、`config`、`send`、`rename`、`delete --yes`、`stop`、`continue`、`resume`、`complete` | -| `opc mode` | `show`、`set task`、`set company --profile corporate`、以及用于已保存组织公司运行的 `set org --org ` | -| `opc kanban` | `view`、`task create`、`task update`、`task move`、`task assign`、`task status`、`task delete --yes` | -| `opc agent` | `list`、`create`、`create-from-template`、`import-employee`、`detail`、`move`、`delete --yes` | -| `opc org` | `info`、`export`、`import`、`saved list/save/load/delete`、`role add/update/bulk-add/delete`、`policy update`、`strategy update`、`reset --yes` | -| `opc talent` | `list`、`employees`、`import`、`hire`、`scan`、`import-selected`、`employee-detail`、`import-agent` | -| `opc market` | `presets`、`browse`、`preview`、`apply-preset`、`export`、`install`、`list`、`uninstall --yes` | -| `opc runtime` | `status`、`checkpoints`、`logs`、`run` | -| `opc channels` | `status`、`login`、`start`、`stop` | - -大多数服务类命令都支持 `--project/-p` 与 `--json`。 - -对于已保存的组织架构，部分 CLI/服务命令目前将 `org` 作为兼容选择器使用，尽管概念上的运行时仍是 Company 模式： - -```bash -opc exec -p demo --mode org --org hku_research_lab "Draft the research report" -opc session create "Research sprint" -p demo --mode org --org hku_research_lab -``` -
- -
- -## 配置 - -在仓库根目录运行一次 `opc init`。它会创建 `.opc/`、从 `config/` 复制模板配置、创建记忆/技能/日志目录，并可选地创建第一个项目。 - -
-展开配置 — 配置文件、LLM 密钥、外部 Agent、频道、浏览器/MCP、故障排查 - -| 文件 | 用途 | -|---|---| -| `.opc/config/llm_config.yaml` | 默认模型、兼容 LiteLLM/OpenRouter 的 API base、API key、环境变量间接引用、路由、回退、temperature、token 限制。 | -| `.opc/config/system_config.yaml` | 运行时行为、浏览器工具、原生运行时、压缩、验证、权限、沙箱与安全设置。 | -| `.opc/config/agent_config.yaml` | 外部 Agent 命令路径、优先顺序、模型参数、会话模式、超时、审批模式与原生子 Agent 配置。 | -| `.opc/config/channel_config.yaml` | 外部消息提供方与凭据。入站发送者列表默认拒绝。 | -| `.opc/config/company_corporate_config.yaml` | 内置 Corporate 公司架构模板。 | -| `.opc/config/company_orgs/org__config.yaml` | Company 模式使用的自定义公司架构。 | -| `.opc/config/org_index.yaml` | 当前生效的已保存公司架构选择器。 | - -### LLM 密钥 - -运行 `opc init` 后，编辑仓库本地 OPC home 中的 `.opc/config/llm_config.yaml`。如果设置了 `OPC_HOME`，则改为编辑 `$OPC_HOME/config/llm_config.yaml`。 - -模板中的密钥留空。直接把 key 写入文件： - -```yaml -llm: - default_model: "openai/gpt-5.4" - api_base: "https://openrouter.ai/api/v1" - api_key: "sk-or-v1-..." # 你的 OpenRouter（或其他提供方）API key - - max_tokens: 32768 # 每次请求的最大输出 token；如果你的模型 - # 输出上限更小，请调低 - # context_window: 128000 # 总输入窗口。通常由 litellm 自动检测； - # 未收录的模型回退为 128000。仅当回退值 - # 不适合你的模型时才取消注释并设置。 -``` - -然后用 `opc status` 验证。 - -如果不想把密钥存在文件里，可以将 `api_key` 留空，并把 `api_key_env` 设置为持有密钥的环境变量名（例如 `api_key_env: "OPENROUTER_API_KEY"`）。 - -### 审批与 Agent 权限 - -`.opc/config/system_config.yaml` 的 `autonomy` 部分控制 Agent 无需询问即可执行多少操作。关键旋钮是 `max_auto_approve_risk` — 可被自动批准的最高风险等级： - -```yaml -autonomy: - max_auto_approve_risk: medium # low | medium | high | critical - allow_native_tool_auto_approval: true - tool_first_use_approval: true # 每个工具首次使用时总是询问 -``` - -每次原生工具调用在运行前都会做风险分级：已知的破坏性命令（`rm -rf`、`drop table`、force-push 等）与敏感关键词（凭据、部署等）为 `high`/`critical`，总是上报给人类；白名单中的安全前缀（`ls`、`git status` 等）为 `low`；其余为 `medium`，在自动批准前会经过 LLM 审查。 - -- `medium`（默认）：平衡 — 普通命令无提示运行；危险命令上报。 -- `low`：严格 — 不在安全白名单中的任何操作都需要审批。推荐用于共享或生产机器。 -- `high`/`critical`：宽松 — 仅用于可随时丢弃的沙箱。 - -每个工具首次使用时总会提示（除非该工具在 `tool_approval_exemptions` 中），你的「始终允许」选择会累积到项目级白名单。 - -### 外部 Agent - -Task 模式可以显式选择执行 Agent： - -```bash -opc chat -p demo --mode task --agent codex "Implement the change" -``` - -可用值有 `native`、`codex`、`claude_code`、`cursor` 与 `opencode`。在 `.opc/config/agent_config.yaml` 中配置命令名、参数、超时、会话复用与审批行为。 - -在 Company 模式下，角色可以通过角色配置或 Org 角色检查器指定偏好的外部 Agent。角色的执行策略可以是 `auto`、`native` 或 `external`，并可选地指定偏好的外部 Agent。 - -### 飞书接入 - -```bash -pip install -e .[channels-feishu] -opc init -opc channels login feishu -``` - -编辑 `.opc/config/channel_config.yaml`： - -```yaml -channels: - feishu: - enabled: true - app_id: "cli_xxx" - app_secret: "..." - encrypt_key: "" - verification_token: "" - react_emoji: THUMBSUP - allow_from: - - "ou_xxx" -``` - -然后： - -```bash -opc channels status -opc channels start -p demo -# 或运行常驻引擎 + 频道运行时： -opc run -p demo -``` - -飞书使用 `lark-oapi` WebSocket 客户端。`app_id` 与 `app_secret` 为必填；`encrypt_key` 与 `verification_token` 为可选，除非你的租户/应用配置要求。请保持 `allow_from` 显式配置；空列表会拒绝所有入站消息。 - -
-其他频道提供方 - -| 提供方 | 安装 extra | 运行方式 | 必填字段 | -|---|---|---|---| -| Telegram | `channels-telegram` | polling | `token` | -| Slack | `channels-slack` | socket | `bot_token`、`app_token` | -| Discord | `channels-discord` | socket | `token` | -| 钉钉 | `channels-dingtalk` | socket | `client_id`、`client_secret` | -| 邮件 | `channels-email` | polling | IMAP/SMTP 字段、`consent_granted` | -| Matrix | `channels-matrix` | sync/polling | `homeserver`、`access_token`、`user_id` | -| QQ | `channels-qq` | socket | `app_id`、`secret` | -| WhatsApp | `channels-whatsapp` | bridge | `bridge_url` | -| Mochat | `channels-mochat` | bridge | `base_url`、`claw_token`、`agent_user_id` | - -常用命令： - -```bash -opc channels login slack -opc channels status -opc channels start -p demo -opc channels stop -opc run -p demo -``` - -参见 [`docs/channels.md`](docs/channels.md) 与 [`docs/channel-bridges.md`](docs/channel-bridges.md)。 -
- -
-浏览器工具与 MCP 服务器 - -浏览器工具： - -```bash -python -m playwright install chromium -``` - -在 `.opc/config/system_config.yaml` 中配置启动行为： - -```yaml -system: - browser: - mode: embedded # embedded | chrome | auto - headless: true - chrome_channel: chrome - user_data_dir: "" -``` - -原生浏览器工具包括 `browser_navigate`、`browser_snapshot`、`browser_click`、`browser_type`、`browser_wait_for`、`browser_scroll`、`browser_select_option`、`browser_evaluate`、`browser_take_screenshot` 与 `browser_close`。 - -MCP 服务器可添加到 `system_config.yaml` 的 `mcp_servers` 下。本地服务器使用 stdio 命令；远程服务器使用 HTTP/SSE 风格的 URL。发现的工具会以服务器前缀注册，避免命名冲突。 -
- -### 故障排查 - -
-Office UI 无法打开或界面陈旧 - -```bash -opc ui --rebuild -``` - -如果浏览器仍显示陈旧的 UI 状态，强制刷新页面。如果之前的进程在运行中途崩溃，先重启 `opc ui` 以释放内存中的锁。 -
- -
-任务看起来卡住了 - -先重启服务器并强制刷新浏览器。如果持久化的任务状态仍然异常，使用重置工具： - -```bash -python scripts/reset_stuck_task.py --project --session --apply -python scripts/reset_stuck_task.py --all --apply -``` -
- -
-外部 Agent 不可用 - -运行： - -```bash -opc status -``` - -检查 `.opc/config/agent_config.yaml` 中的命令名，例如 `codex`、`claude`、`cursor-agent` 与 `opencode`。禁用或调整你未安装的 Agent 的优先级。 -
- -
-频道提供方收不到消息 - -检查： - -- 已安装对应的 extra，例如 `pip install -e .[channels-feishu]`。 -- 该提供方为 `enabled: true`。 -- 必填凭据已填写。 -- `allow_from` 包含你期望的发送者 ID。 -- `opc channels status` 显示该提供方已配置且可用。 -
- -
- -## 生态与分享 - -OpenOPC 构建的一切都归你所有，可以保留、复用与分享 — 组织、员工、人才模板、技能与频道都只是文件。你可以导入一个流行的人才库、跨项目复用一个团队，或者把整个公司打包成可分享的 `.opcpkg`。 - -```bash -# 从人才库（例如 agency-agents）招募到某个角色 -opc talent import /path/to/agency-agents -opc talent hire -p demo - -# 复用或分享整个组织 -opc org export --json > my-org.yaml -opc market export --id hku_lab --name "HKU Lab" --output-dir packages -opc market install packages/hku_lab.opcpkg -``` - -## 路线图 - -OpenOPC 正在快速迭代。以下领域反映当前的开发重点 — 每一项都源自早期使用中发现的真实缺口。 - -| 领域 | 计划方向 | -|---|---| -| **角色级技能** | 角色配置已支持 `skill_refs`，Org UI 目前也展示技能元数据。下一步是让用户直接在 Org 页面选择哪些技能挂载到哪些角色 — 汇入更广泛的自演化技能生态。 | -| **秘书设置** | 秘书将成长为更强的配置与记忆管家：负责 OPC 系统记忆、分析与对比项目，并为 OpenOPC YAML 配置提供引导式设置。 | -| **Company 模式频道** | 外部频道将从简单的聊天入口演进为更丰富的 Company 模式工作流 — 支持角色感知的通知、结构化审批与跨平台协作。 | -| **CLI 对齐** | CLI 目前可用，但 Office UI 仍是更完整的界面。后续工作聚焦于从终端进行组织编辑、Company 模式检查、故障恢复与长时运行时控制。 | -| **TUI** | CLI 对齐成熟后将考虑完整的终端 UI。在此期间 Office UI 仍是主要界面。 | -| **市场与预设** | 更多架构预设、可招募的人才包、导入/导出工作流，以及用于分享与发现社区组件的包市场。 | -| **运行时打磨** | 持续改进恢复、检查点、执行进度可见性与可视化文档 — 让长时间的公司运行更可观察、更有韧性。 | - -## 致谢 - -OpenOPC 的 Agent 设计、技能结构与人才模板生态受益于多个开源项目，在此致谢： - -- [openai/codex](https://github.com/openai/codex/) 启发了实用的编码 Agent 工作流与执行模式。 -- [BloopAI/vibe-kanban](https://github.com/BloopAI/vibe-kanban) 启发了以看板为中心的 Agent 工作管理与任务可见性。 -- [msitarzewski/agency-agents](https://github.com/msitarzewski/agency-agents) 提供了人才模板的基础。本仓库包含的所有人才模板均导入自 `agency-agents`。 -- [HKUDS/nanobot](https://github.com/HKUDS/nanobot) 启发了面向技能的 Agent 设计与 `SKILL.md` 风格的组织方式。 -- [pixel-agents-hq/pixel-agents](https://github.com/pixel-agents-hq/pixel-agents) 启发了以像素动画办公室可视化 Agent 活动的方式。 - ---- - -

- ❤️ 感谢访问 ✨ OpenOPC！

- Views -