opc-agent-team-opensource

OPC-Fellows · hire occupations as members, then point them at your work A small kernel (shell, todos, contracts) plus occupation plugins you can enable or write.

English · 中文

Wire it to your business · Occupations · Download · Write a module · Architecture · Contributing

You are a developer who also is the company: sales, content, research, invoices. This README is not a product brochure. It is how you clone the repo, hire members onto your own folders and sites, and do real work the same day.

Business data stays in on-device userData. Model keys go through Settings → Model (safeStorage). No account, no upload, no telemetry. The default product catalog is empty — fill in *your* sites.

Wire it to your business in 15 minutes

Needs Node.js ^22.19.0 or >=24.0.0, and pnpm 10+. The first pnpm install downloads Electron and takes a while.

git clone git@github.com:Alfred-Lau/OPC-Fellows.git
cd OPC-Fellows
pnpm install
pnpm dev

The UI is still hardcoded Chinese. Then attach your business, in this order — do not start with the architecture docs:

1. Key — 设置 → 模型, paste a DeepSeek API Key. Or export DEEPSEEK_API_KEY=… (env wins). Members cannot speak without a key.
2. Hire — the open-source roster ships Host and Social ammo only. Opening a member is their home thread. The left-rail + currently reopens Social ammo (a singleton).
3. Bind a folder — set the identity directory when you hire. Default is ~/OPC-Fellows/agents/{title}. Better: bind the folder you actually edit. You can rebind later; files are not moved.
4. Register your sites — 设置 → 工作情况 → 添加产品. Social ammo reads this list, not the sample in the repo. Shape: examples/catalog.example.json.
5. Talk — the composer is 问 (read-only), 计划 (propose first; reply 「按计划执行」 before writes), 动手 (write in the workspace). Ask first, then act.

Optional:

cp .env.example .env          # never commit a real .env
pnpm test
pnpm dsh                      # local DeepSeek Harness CLI

Package with pnpm run pack (unpacked dir) or pnpm dist:mac. Do not run pnpm pack — that emits an npm tarball.

Vocabulary (member / project / identity directory / composer mode): CONTEXT.md.

Which member for which job

The public roster keeps two identities. Other occupation modules stay in the tree but start disabled and do not spawn members.

Your job · Who Read/edit the workspace, run commands, plan then act · Host (default lead on every project) Multi-platform copy from product capabilities · Social ammo (register your sites in 工作情况 first)

Social ammo reads the Work situation catalog. Env cheat sheet:

Variable · Use DEEPSEEK_API_KEY · Overrides Settings → Model; still reads legacy ~/.dsh OPC_USER_DATA · userData for the runtime

A project is one multi-member job. With no @, only the lead member hears you. Today is the global inbox, not a project.

Download a build

If you do not want source: v0.8.0 (macOS Apple Silicon only).

• dmg — drag into Applications
• zip

The build is signed and notarized by Apple, so it opens without any extra step. If the first launch is still blocked (for example while offline), run this once:

xattr -cr "/Applications/OPC-Fellows.app"

Then open the app. Upgrading from v0.7.3: this release builds under the name OPC-Fellows, so it starts with a fresh workspace — the previous build kept its data in ~/Library/Application Support/OPC Agent Team - Solokit and the new name does not read it. The same first-hour path applies: model key → hire → bind a folder → Work situation.

Extend the roster: add your own member

This tree ships two members, but that is the default set rather than a limit: a member is an occupation backed by a module, and nothing in the kernel is per-occupation. When a job is missing, add a member instead of patching the kernel.

If a built-in occupation does not cover your business, add an npm package. Do not grow kernel union types. The workbench reads ownworkbuddy (apply(ctx) + optional mount); the runtime reads dsh.bundle. Write both during the transition. Smallest sample: examples/hello-module.

{
  "main": "dsh-plugin.js",
  "ownworkbuddy": {
    "id": "hello",
    "title": "Hello",
    "kind": "view",
    "main": "index.js",
    "capabilities": [],
    "ui": "ui.js"
  },
  "dsh": {
    "bundle": { "patch": "./cordis.patch.yml" }
  }
}

export default function apply(ctx) {
  ctx.workbench.nav({ id: 'hello', title: 'Hello', mark: 'Hi', kind: 'view', order: 200 })
  ctx.bridge.handle('hello:ping', () => ({ ok: true, at: new Date().toISOString() }))
}

Install from a local folder or Git on the Extensions page. To join the Harness stack:

pnpm dsh plugin --profile opc add ./examples/hello-module

A module may call only capabilities in its manifest. Undeclared calls are rejected. subprocess and secrets confirm at install. Modules must not reach into each other's stores; cross-module traffic goes through kernel services (for example todos.ingestAgent).

Architecture

Electron is a thin shell. Chat and tools run on DeepSeek Harness; the roster, todos, and module registry hang on the same tree. Design: ADR 0005, docs/module-architecture-design.md. Shell mental model: docs/agent-workspace-design.md.

src/kernel/     boot, IPC, storage, todos, nav, module registry, members
src/modules/    built-in occupations (reference implementations)
examples/       smallest third-party module
server/         optional self-hosted reference backend (independent package)
docs/           architecture and ADRs

server/ is an optional, self-hosted reference backend for users who want to stand up their own full-stack app. It is deliberately outside the desktop build: its own package.json, not in any pnpm workspace, and nothing here imports it — see server/README.md.

Runtime: deepseek-ai/deepseek-harness. Peer desktop hosts: github.com/topics/dsh-plugin.

The author runs this workbench against SoloKit and 榆关. That is a configuration, not the trunk defaults.

Contributing

Public trunk: Alfred-Lau/OPC-Fellows. PRs against kernel services, manifests, capabilities, samples, and docs are welcome.

Do not weld personal site catalogs, signing identities, secret defaults, or machine-absolute paths into src/shared. The default identity directory is ~/OPC-Fellows/agents/{title}. Aligning a private reference tree copies mechanisms only — ADR 0007.

• CONTRIBUTING.en.md · CONTRIBUTING.md
• Code of Conduct · Security policy
• Good first cuts: English UI strings, an examples/ module, tests for one occupation

UI copy is still hardcoded Chinese. Plan: docs/i18n-plan.md. PRs are licensed under MIT.

Security

• Business data stays in on-device userData. There is no first-party backend for it. (server/ is an optional self-hosted sample *you* deploy and control; it never receives desktop data.)
• WeChat intel is a local read-only index. Mail triage writes local drafts and does not send.
• Third-party modules run on a capability allow-list.
• Report vulnerabilities in private. See SECURITY.md.

License

MIT License. Runtime depends on Cordis and DeepSeek Harness.

Site: OPC-Fellows