owfadev 0.3.2 → 0.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/skills/owfa-check/SKILL.md +49 -0
- package/.agents/skills/{docs → owfa-docs}/SKILL.md +5 -5
- package/.agents/skills/{wiki_plugin_kernel → owfa-kernel}/SKILL.md +13 -12
- package/{.meta/command/plugin → .agents/skills/owfa-plugin}/SKILL.md +10 -10
- package/.agents/skills/{query → owfa-query}/SKILL.md +5 -6
- package/.owfa/VERSION +1 -0
- package/.owfa/command/owfa-check/SKILL.md +49 -0
- package/{.meta/command/docs → .owfa/command/owfa-docs}/SKILL.md +5 -5
- package/{.meta/command/wiki_plugin_kernel → .owfa/command/owfa-kernel}/SKILL.md +13 -12
- package/{.agents/skills/plugin → .owfa/command/owfa-plugin}/SKILL.md +10 -10
- package/{.meta/command/query → .owfa/command/owfa-query}/SKILL.md +5 -6
- package/{.meta → .owfa}/docs/agent-behavior.md +3 -2
- package/{.meta → .owfa}/docs/agents-example.md +1 -1
- package/{.meta → .owfa}/docs/conversion.md +2 -2
- package/{.meta → .owfa}/docs/deployment.md +51 -46
- package/{.meta → .owfa}/docs/developer.md +4 -4
- package/{.meta → .owfa}/docs/distribution.md +21 -19
- package/.owfa/docs/home.md +61 -0
- package/{.meta → .owfa}/docs/intro.md +5 -5
- package/{.meta → .owfa}/docs/log-example.md +1 -1
- package/{.meta → .owfa}/docs/map.md +4 -3
- package/{.meta → .owfa}/docs/mechanics.md +11 -11
- package/{.meta → .owfa}/docs/naming.md +7 -7
- package/{.meta → .owfa}/docs/packages.md +80 -15
- package/.owfa/docs/plugin-lifecycle.md +70 -0
- package/{.meta → .owfa}/docs/quickstart.md +12 -12
- package/{.meta → .owfa}/docs/research-user-profile.md +1 -1
- package/{.meta → .owfa}/docs/sandbox.md +3 -3
- package/{.meta → .owfa}/docs/usage.md +1 -1
- package/{.meta → .owfa}/protocol/actions.md +6 -6
- package/.owfa/protocol/registry.yaml +34 -0
- package/.owfa/scripts/owfa_home.py +273 -0
- package/{.meta/scripts/wiki_plugin_kernel.py → .owfa/scripts/owfa_kernel.py} +521 -77
- package/{.meta → .owfa}/scripts/pipeline.py +9 -9
- package/.owfa/scripts/wiki_plugin_kernel.py +15 -0
- package/{.meta → .owfa}/scripts/wikilib.py +2 -2
- package/.owfa/tests/test_capabilities.py +311 -0
- package/{.meta → .owfa}/tests/test_install_preflight.py +11 -7
- package/.owfa/tests/test_owfa_home.py +127 -0
- package/.owfa/tests/test_version_scheme.py +68 -0
- package/README.md +32 -24
- package/README.zh-CN.md +32 -24
- package/bin/owfa.js +483 -65
- package/package.json +3 -2
- package/payloads/personal/PKG.yaml +15 -0
- package/payloads/personal/README.md +7 -0
- package/{.meta/plugins/core → payloads/personal}/calendar/PLUGIN.md +1 -0
- package/{.meta/plugins/core → payloads/personal}/calendar/PLUGIN.yaml +3 -3
- package/{.agents/skills/map → payloads/personal/command/owfa-map}/SKILL.md +9 -9
- package/{.meta/command/profile → payloads/personal/command/owfa-profile}/SKILL.md +11 -11
- package/{.agents/skills/save → payloads/personal/command/owfa-save}/SKILL.md +10 -10
- package/{.meta/plugins/core → payloads/personal}/cron/PLUGIN.md +2 -0
- package/{.meta/plugins/core → payloads/personal}/cron/PLUGIN.yaml +3 -3
- package/{.meta/plugins/core → payloads/personal}/device/PLUGIN.md +1 -0
- package/{.meta/plugins/core → payloads/personal}/device/PLUGIN.yaml +3 -3
- package/{.meta/plugins/core → payloads/personal}/domain/PLUGIN.md +2 -0
- package/payloads/personal/domain/PLUGIN.yaml +8 -0
- package/{.meta/plugins/core → payloads/personal}/hot/PLUGIN.yaml +1 -1
- package/{.meta/plugins/core → payloads/personal}/index/PLUGIN.md +1 -0
- package/{.meta/plugins/core → payloads/personal}/index/PLUGIN.yaml +4 -4
- package/{.meta/plugins/core → payloads/personal}/instance-git/PLUGIN.md +5 -0
- package/{.meta/plugins/core → payloads/personal}/instance-git/PLUGIN.yaml +3 -3
- package/{.meta/plugins/core → payloads/personal}/language/PLUGIN.md +1 -0
- package/{.meta/plugins/core → payloads/personal}/language/PLUGIN.yaml +4 -4
- package/{.meta/plugins/core → payloads/personal}/link/PLUGIN.md +1 -0
- package/{.meta/plugins/core → payloads/personal}/link/PLUGIN.yaml +3 -3
- package/{.meta/plugins/core → payloads/personal}/link/scripts/check.py +1 -1
- package/{.meta/plugins/core → payloads/personal}/log/PLUGIN.md +1 -0
- package/{.meta/plugins/core → payloads/personal}/log/PLUGIN.yaml +4 -4
- package/{.meta/plugins/core → payloads/personal}/mapping/PLUGIN.yaml +1 -1
- package/{.meta/plugins/core → payloads/personal}/notes/PLUGIN.md +1 -0
- package/{.meta/plugins/core → payloads/personal}/notes/PLUGIN.yaml +4 -4
- package/{.meta/plugins/core → payloads/personal}/sessions/PLUGIN.md +2 -1
- package/{.meta/plugins/core → payloads/personal}/sessions/PLUGIN.yaml +5 -5
- package/{.meta/plugins/core → payloads/personal}/structure/PLUGIN.md +2 -0
- package/{.meta/plugins/core → payloads/personal}/structure/PLUGIN.yaml +3 -3
- package/{.meta/plugins/core → payloads/personal}/structure/scripts/check.py +1 -1
- package/{.meta/plugins/core → payloads/personal}/tag/PLUGIN.md +2 -0
- package/{.meta/plugins/core → payloads/personal}/tag/PLUGIN.yaml +3 -3
- package/{.meta/plugins/core → payloads/personal}/tag/scripts/check.py +3 -1
- package/{.meta/plugins/core → payloads/personal}/tmp/PLUGIN.md +1 -0
- package/{.meta/plugins/core → payloads/personal}/tmp/PLUGIN.yaml +3 -3
- package/{.meta/plugins/core → payloads/personal}/todo/PLUGIN.md +2 -0
- package/{.meta/plugins/core → payloads/personal}/todo/PLUGIN.yaml +6 -5
- package/payloads/personal/todo/scripts/check.py +51 -0
- package/{.meta/plugins/core → payloads/personal}/trust/PLUGIN.md +1 -0
- package/{.meta/plugins/core → payloads/personal}/trust/PLUGIN.yaml +3 -3
- package/{.meta/plugins/core → payloads/personal}/user-profile/PLUGIN.md +2 -0
- package/{.meta/plugins/core → payloads/personal}/user-profile/PLUGIN.yaml +7 -6
- package/payloads/personal/user-profile/scripts/check.py +20 -0
- package/{.meta/plugins/core → payloads/personal}/vault/PLUGIN.md +1 -0
- package/payloads/personal/vault/PLUGIN.yaml +13 -0
- package/{.meta/plugins/core → payloads/personal}/wiki/PLUGIN.md +1 -0
- package/payloads/personal/wiki/PLUGIN.yaml +8 -0
- package/templates/AGENTS.template.md +2 -2
- package/.agents/skills/check/SKILL.md +0 -130
- package/.agents/skills/profile/SKILL.md +0 -75
- package/.meta/VERSION +0 -1
- package/.meta/command/check/SKILL.md +0 -130
- package/.meta/command/map/SKILL.md +0 -72
- package/.meta/command/save/SKILL.md +0 -94
- package/.meta/plugins/core/domain/PLUGIN.yaml +0 -8
- package/.meta/plugins/core/vault/PLUGIN.yaml +0 -13
- package/.meta/plugins/core/wiki/PLUGIN.yaml +0 -8
- package/.meta/protocol/registry.yaml +0 -75
- /package/{.meta → .owfa}/command/asset-read/SKILL.md +0 -0
- /package/{.meta → .owfa}/docs/research-landscape.md +0 -0
- /package/{.meta → .owfa}/protocol/experiments.md +0 -0
- /package/{.meta/plugins/core → payloads/personal}/device/scripts/check.py +0 -0
- /package/{.meta/plugins/core → payloads/personal}/hot/PLUGIN.md +0 -0
- /package/{.meta/plugins/core → payloads/personal}/instance-git/scripts/check.py +0 -0
- /package/{.meta/plugins/core → payloads/personal}/language/scripts/check.py +0 -0
- /package/{.meta/plugins/core → payloads/personal}/log/scripts/check.py +0 -0
- /package/{.meta/plugins/core → payloads/personal}/mapping/PLUGIN.md +0 -0
- /package/{.meta/plugins/core → payloads/personal}/mapping/scripts/check.py +0 -0
- /package/{.meta/plugins/core → payloads/personal}/sessions/scripts/check.py +0 -0
- /package/{.meta/plugins/core → payloads/personal}/trust/scripts/check.py +0 -0
package/README.md
CHANGED
|
@@ -6,11 +6,19 @@
|
|
|
6
6
|
|
|
7
7
|
**OWFA** (One Workspace For All agents) is an open-source agent workspace: out-of-the-box on first install, continuously maintainable over time, and pluginized end to end. One workspace — the directory you own, holding `vault/` (real assets), `wiki/` (md proxies and native notes) and `AGENTS.md` (the constitution) — is the standing context that every agent you use re-enters instead of being re-introduced each session. The agent reads and writes with zero priors per the SASU-L disclosure order; md plus plain files are the foundation, and Obsidian and friends are replaceable viewers. Behavior is personalizable through a living user profile, and new capabilities land as plugins — every plugin ships through the registry with a human-review gate, so contributions are welcome: build a domain plugin for the sources you use and file a one-line PR to list it (see [Contributing](#contributing)).
|
|
8
8
|
|
|
9
|
-
> Status: **alpha** — capability-wise a prototype matured by six weeks of real daily use (born 2026-09-08, validated by two rounds of real operation plus a cold-start disclosure audit, the bb course family live across four courses); distribution-wise v0.3 is the first shape others can install — covered by exactly one fresh-instance acceptance run, zero outside users. Beta gate: behavior contracts (#34) landed · both members running real installs · the legacy-instance conversion walked through · the acceptance script replayable green. `.
|
|
9
|
+
> Status: **alpha** — capability-wise a prototype matured by six weeks of real daily use (born 2026-09-08, validated by two rounds of real operation plus a cold-start disclosure audit, the bb course family live across four courses); distribution-wise v0.3 is the first shape others can install — covered by exactly one fresh-instance acceptance run, zero outside users. Beta gate: behavior contracts (#34) landed · both members running real installs · the legacy-instance conversion walked through · the acceptance script replayable green. `.owfa/VERSION` tracks the kernel contract, not product maturity — stage labels live here and in release notes. Universalization and matrix testing remain deferred. Converted from personal use to a team project on 2026-10-02. Docs language switched to English on 2026-10-06 (historical Chinese log entries preserved as-is). 2026-10-12: repo transferred to the GitHub org **AIE3905-Wuwa**; the standardization-and-split improvement phase opened — package binding landed (core 20 + 5 domain packages, see [.owfa/docs/packages.md](https://github.com/owfadev/owfa/blob/master/.owfa/docs/packages.md)); dev rules now live in [CONTRIBUTING.md](https://github.com/owfadev/owfa/blob/master/CONTRIBUTING.md). 2026-10-13: VERSION 0.3 (tag v0.3) — registry discovery/install, subset installs (--without), upgrade chaining, teardown (x->0) closing the migration algebra, the instance git contract; validated end-to-end by a fresh-instance acceptance run. 2026-10-25: the framework body gets a distribution channel of its own — npm CLI `owfa` (`init` / `upgrade` / `doctor` / `add`), closing the "clone + copy two trees + hand-write AGENTS.md" gap (issues #45/#46); the npm name `owfa` is frozen under the registry's similarity policy and is under application, with `owfadev` as the fallback namespace.
|
|
10
|
+
## Why OWFA
|
|
11
|
+
|
|
12
|
+
Two conveniences, one principle.
|
|
13
|
+
|
|
14
|
+
**Stop hand-pointing.** Without a workspace, every session you re-explain: where the files are, what that course page means, which video you watched, what you decided last week. OWFA inverts this — information registers itself into the wiki (map, save, domain packages), and the agent goes and finds it. The value is convenience in the plainest sense: the pointing you used to do by hand becomes retrieval the agent does itself.
|
|
15
|
+
|
|
16
|
+
**Any harness, your context.** OWFA ships as AGENTS.md + skills, not as a service — so it is indifferent to which agent harness reads them. Run it in one harness today, switch tomorrow, or run two at once: the workspace, the memory and the plugins come with you. The plugin line makes this concrete: the \`bili\` package (with its autonomous agent member) turns Bilibili into a queryable archive — raised in one harness, it runs just as well in any other that reads AGENTS.md. You are renting a harness, not adopting a walled garden.
|
|
17
|
+
|
|
10
18
|
|
|
11
19
|
## The name
|
|
12
20
|
|
|
13
|
-
**OWFA — One Workspace For All (agents).** One workspace — the directory you own, holding `vault/`, `wiki/`, `AGENTS.md` and the framework body — that every agent you use re-enters instead of being re-introduced each session. *All* means all of *your* agents, not all people and not a hosted service; the human stays the owner and the audit anchor. `vault-wiki` retires from the public surface: public copy says **OWFA** (or **OWFA Core**), the GitHub home moves to **`owfadev/owfa`**, and `owfa` is the name the CLI ships under. That last address is not free yet — npm froze `owfa` as too similar to `ow`/`ora`; an application is in progress, and `owfadev` is the fallback package. Full rationale, layers and collision policy: [`.
|
|
21
|
+
**OWFA — One Workspace For All (agents).** One workspace — the directory you own, holding `vault/`, `wiki/`, `AGENTS.md` and the framework body — that every agent you use re-enters instead of being re-introduced each session. *All* means all of *your* agents, not all people and not a hosted service; the human stays the owner and the audit anchor. `vault-wiki` retires from the public surface: public copy says **OWFA** (or **OWFA Core**), the GitHub home moves to **`owfadev/owfa`**, and `owfa` is the name the CLI ships under. That last address is not free yet — npm froze `owfa` as too similar to `ow`/`ora`; an application is in progress, and `owfadev` is the fallback package. Full rationale, layers and collision policy: [`.owfa/docs/naming.md`](https://github.com/owfadev/owfa/blob/master/.owfa/docs/naming.md).
|
|
14
22
|
|
|
15
23
|
## What it does
|
|
16
24
|
|
|
@@ -39,17 +47,17 @@ Let an AI coding agent run a "personal wiki" for you:
|
|
|
39
47
|
|
|
40
48
|
| Directory | Contents |
|
|
41
49
|
|------|------|
|
|
42
|
-
| `.
|
|
50
|
+
| `.owfa/` | Framework tree, kernel-only since the v0.4 split: `plugins/domains/<pkg>/` (one package per directory: `PKG.yaml` + family masters — the embedded **personal** suite of 21 former core plugins lands here on a default init; then cuhksz 8, lark 4, email, bili, project on demand). Directory boundary == tier boundary == package boundary; `PKG.yaml` declares the roster and the kernel reconciles it against the family closure; `.owfa/VERSION` anchors the framework version (package `compat` floors checked against it). Injection order = dependency topology + alphabetical; the AGENTS injection region is tiered — member-tier domain pieces exit it (family roster + skills + on-demand manifest reads carry exposure) under a kernel byte budget; global plugins may declare bridges, and mandatory bridges are kernel-verified. Also 6 framework command masters (suite-owned commands ride with their package), protocol artifacts — registry, actions, experiments — and the mechanical scripts owfa-kernel, pipeline, wikilib, pure stdlib with zero deps; the canonical suite repo is owfa-personal, embedded at `payloads/personal/` |
|
|
43
51
|
| `connectors/` | Connector masters: deployment-side CLI factual interface + skill usage disclosure. `connectors/*/SKILL.md` lands in `.agents/skills/` via kernel deploy; currently bb-cli, sis-cli, mail-cli, bili-cli. Connectors ride with their packages in `PKG.yaml` — physical relocation into the per-package repos happens at the split round |
|
|
44
52
|
| Packages | The index lives in the [registry](https://github.com/owfadev/registry) (Obsidian-model: self-hosted packages, one-line PR is the listing gate). `kernel install`/`list-remote` resolve against it; unindexed repos stay installable with `--yes` (trust: unknown). The org repos `pkg-cuhksz` / `pkg-lark` / `pkg-email` / `pkg-bili` / `pkg-project` / `pkg-github` hold the packages, split with full file lineage |
|
|
45
53
|
| `.agents/skills/` | Deployment copies of command & connector skills (framework commands after the split; connector skills arrive with their packages) |
|
|
46
54
|
| `bin/` + `templates/` + `package.json` | The npm channel: `owfa` CLI, AGENTS seed, package manifest. `test/` and `scripts/` are development-only and never ship |
|
|
47
|
-
| `test-repo/` | Local test sandbox — untracked since 2026-10-13 (owner re-ruling; a fresh clone carries none of it). A scratch deployment for experiments needing an AGENTS.md context; setup and rules in [`.
|
|
48
|
-
| `.
|
|
55
|
+
| `test-repo/` | Local test sandbox — untracked since 2026-10-13 (owner re-ruling; a fresh clone carries none of it). A scratch deployment for experiments needing an AGENTS.md context; setup and rules in [`.owfa/docs/sandbox.md`](https://github.com/owfadev/owfa/blob/master/.owfa/docs/sandbox.md). The framework repo itself carries no AGENTS.md — library posture; dev rules live in [CONTRIBUTING.md](https://github.com/owfadev/owfa/blob/master/CONTRIBUTING.md) |
|
|
56
|
+
| `.owfa/docs/` | Human docs: `intro.md` introduction, `mechanics.md` mechanics, `usage.md` usage guide, `deployment.md` full guide / `quickstart.md` five-minute path, `instance-git.md` the instance-side git minimal contract, `research-*.md` research files — direct links at the end. Authoritative mechanics live in the kernel reference skill; docs do not mirror mechanics |
|
|
49
57
|
|
|
50
58
|
## Contributing
|
|
51
59
|
|
|
52
|
-
Contributions are welcome, and plugins are the intended surface: a new capability is a new plugin, not a fork of the framework. Three paths, smallest first — a connector skill for a CLI you use, a domain plugin that adapts an external source to the wiki (see [`developer.md`](https://github.com/owfadev/owfa/blob/master/.
|
|
60
|
+
Contributions are welcome, and plugins are the intended surface: a new capability is a new plugin, not a fork of the framework. Three paths, smallest first — a connector skill for a CLI you use, a domain plugin that adapts an external source to the wiki (see [`developer.md`](https://github.com/owfadev/owfa/blob/master/.owfa/docs/developer.md) for the three-path table and the dev loop), or an improvement to core. Domain packages self-host in their own repos; listing is a one-line PR to the [registry](https://github.com/owfadev/registry), which is the human-review trust gate. Bug reports and behavior questions go through issues; the framework body itself takes PRs.
|
|
53
61
|
|
|
54
62
|
## Collaboration
|
|
55
63
|
|
|
@@ -57,15 +65,15 @@ This repository is a team project: three members with write access, everything t
|
|
|
57
65
|
|
|
58
66
|
## Getting started
|
|
59
67
|
|
|
60
|
-
Two ways in. **Channel (recommended):** `npx owfa init my-workspace` — Node 16.7+ for the installer, Python 3.9+ for Core; nothing to clone (`npx owfadev init` is the fallback while the npm name is under application). **Manual:** clone this repository and follow the five steps in [quickstart.md](https://github.com/owfadev/owfa/blob/master/.
|
|
68
|
+
Two ways in. **Channel (recommended):** `npx owfa init my-workspace` — Node 16.7+ for the installer, Python 3.9+ for Core; nothing to clone (`npx owfadev init` is the fallback while the npm name is under application). **Manual:** clone this repository and follow the five steps in [quickstart.md](https://github.com/owfadev/owfa/blob/master/.owfa/docs/quickstart.md), then `python .owfa/scripts/owfa_kernel.py all`. Full guide, including packages and upgrades: [deployment.md](https://github.com/owfadev/owfa/blob/master/.owfa/docs/deployment.md).
|
|
61
69
|
|
|
62
70
|
Prerequisites: Python 3.9+, pure stdlib, no install needed for the framework itself (connectors carry their own deps); Node 16.7+ only for the npm channel; git recommended (instance snapshots); an agent environment that reads AGENTS.md and skills, e.g. ZCode; Obsidian optional, viewer only.
|
|
63
71
|
|
|
64
|
-
Open an agent session at the repository root. AGENTS.md is the constitution, containing the plugin injection region; the thirteen commands trigger by natural language: **map / save / profile / query / check / plugin / lark-map / bb-map / asset-read / kernel reference / teach / quiz / track** — map, save, profile, query, check, plugin, lark-map, bb-map, asset-read,
|
|
72
|
+
Open an agent session at the repository root. AGENTS.md is the constitution, containing the plugin injection region; the thirteen commands trigger by natural language: **owfa-map / owfa-save / owfa-profile / owfa-query / owfa-check / owfa-plugin / lark-map / bb-map / asset-read / kernel reference / teach / quiz / track** — owfa-map, owfa-save, owfa-profile, owfa-query, owfa-check, owfa-plugin, lark-map, bb-map, asset-read, owfa-kernel, bb-teach, bb-quiz, bb-track; masters live in `.owfa/command/`. Put a file into `vault/` and say "owfa-map" to the agent — that is the first use.
|
|
65
73
|
|
|
66
74
|
## Deployment
|
|
67
75
|
|
|
68
|
-
OWFA has three layers: **OWFA CLI** (the installer, never copied into the workspace), **OWFA Core** (`.
|
|
76
|
+
OWFA has three layers: **OWFA CLI** (the installer, never copied into the workspace), **OWFA Core** (`.owfa/` + `.agents/skills/`, the thing that is installed), and the **kernel** (a pure-stdlib Python script inside Core — there is no separate kernel install; Python 3.9+ runs it). Domain packages under `.owfa/plugins/domains/<pkg>/` are optional.
|
|
69
77
|
|
|
70
78
|
```bash
|
|
71
79
|
npx owfa init my-workspace # target name; npx owfadev init while the application is pending
|
|
@@ -78,25 +86,25 @@ npx owfa upgrade # later: replace the framework trees, preserve
|
|
|
78
86
|
|
|
79
87
|
While the name is under application, substitute `npx owfadev` for every `npx owfa` command above (or install either package globally; both expose the `owfa` bin).
|
|
80
88
|
|
|
81
|
-
`init` is additive: existing content is untouched, an existing `AGENTS.md` is preserved and only the injection region is appended. `upgrade` replaces `.
|
|
89
|
+
`init` is additive: existing content is untouched, an existing `AGENTS.md` is preserved and only the injection region is appended. `upgrade` replaces `.owfa/` and `.agents/skills/` (instance data is never touched) and keeps the kernel's migration ledger, journal and registry cache.
|
|
82
90
|
|
|
83
|
-
- Full deployment guide (components, channels, packages, upgrades, troubleshooting): [`.
|
|
84
|
-
- Five-minute path: [`.
|
|
85
|
-
- Channel design and release runbook: [`.
|
|
91
|
+
- Full deployment guide (components, channels, packages, upgrades, troubleshooting): [`.owfa/docs/deployment.md`](https://github.com/owfadev/owfa/blob/master/.owfa/docs/deployment.md)
|
|
92
|
+
- Five-minute path: [`.owfa/docs/quickstart.md`](https://github.com/owfadev/owfa/blob/master/.owfa/docs/quickstart.md)
|
|
93
|
+
- Channel design and release runbook: [`.owfa/docs/distribution.md`](https://github.com/owfadev/owfa/blob/master/.owfa/docs/distribution.md)
|
|
86
94
|
|
|
87
95
|
## Doc pointers
|
|
88
96
|
|
|
89
|
-
- [.
|
|
90
|
-
- [.
|
|
91
|
-
- [.
|
|
92
|
-
- [.
|
|
93
|
-
- [.
|
|
94
|
-
- [.
|
|
95
|
-
- [.
|
|
96
|
-
- [.
|
|
97
|
-
- [.
|
|
98
|
-
- [.
|
|
99
|
-
- `.
|
|
97
|
+
- [.owfa/docs/deployment.md](https://github.com/owfadev/owfa/blob/master/.owfa/docs/deployment.md) — deployment guide: components, channels, first run, packages, upgrades, troubleshooting
|
|
98
|
+
- [.owfa/docs/naming.md](https://github.com/owfadev/owfa/blob/master/.owfa/docs/naming.md) — the name: canonical expansion, what each word commits to, two names two jobs, objections, collision policy
|
|
99
|
+
- [.owfa/docs/distribution.md](https://github.com/owfadev/owfa/blob/master/.owfa/docs/distribution.md) — the npm channel: commands, artifacts, version invariant, release runbook, security posture
|
|
100
|
+
- [.owfa/docs/packages.md](https://github.com/owfadev/owfa/blob/master/.owfa/docs/packages.md) — package mechanism and design rationale: layout, PKG.yaml, invariants, versions, uninstall contract, decision ledger
|
|
101
|
+
- [.owfa/docs/developer.md](https://github.com/owfadev/owfa/blob/master/.owfa/docs/developer.md) — developer guide: where a plugin lands (the three-path table), the dev loop, registration and discovery
|
|
102
|
+
- [.owfa/docs/agents-example.md](https://github.com/owfadev/owfa/blob/master/.owfa/docs/agents-example.md) / [.owfa/docs/log-example.md](https://github.com/owfadev/owfa/blob/master/.owfa/docs/log-example.md) — instance seeds for AGENTS.md and log.md (the framework repo itself carries neither)
|
|
103
|
+
- [.owfa/docs/intro.md](https://github.com/owfadev/owfa/blob/master/.owfa/docs/intro.md) — introduction: why this framework, narrative & lineage
|
|
104
|
+
- [.owfa/docs/mechanics.md](https://github.com/owfadev/owfa/blob/master/.owfa/docs/mechanics.md) — mechanics: each mechanism one level deeper, with a bb-family walkthrough; read before touching the framework
|
|
105
|
+
- [.owfa/docs/usage.md](https://github.com/owfadev/owfa/blob/master/.owfa/docs/usage.md) — usage guide: the three work loops (library keeping, course learning, collaborative development)
|
|
106
|
+
- [.owfa/docs/quickstart.md](https://github.com/owfadev/owfa/blob/master/.owfa/docs/quickstart.md) — five-minute path: one command or the manual five steps, then first run
|
|
107
|
+
- `.owfa/protocol/` — field registry, action discipline, disclosure paradigm
|
|
100
108
|
|
|
101
109
|
## License
|
|
102
110
|
|
package/README.zh-CN.md
CHANGED
|
@@ -6,11 +6,19 @@
|
|
|
6
6
|
|
|
7
7
|
**OWFA**（One Workspace For All agents）是一个开源的 agent 工作区：开箱即用、可持续维护、端到端插件化。一个工作区——你拥有的那个目录，装着 `vault/`（真实资产）、`wiki/`（md 投影与原生笔记）和 `AGENTS.md`（章程）——是你所有 agent 反复进入的常驻上下文，而不是每次会话重新自我介绍。agent 按 SASU-L 披露次序零先验地读写；md 与纯文本文件是地基，Obsidian 等只是可替换的查看器。行为通过一份活的用户画像个性化，新能力以插件落地——每个插件都经 registry 的人工审核门发布，欢迎贡献：为你使用的信息源写一个域插件，向 registry 提一行 PR 即可上架（见[参与贡献](#参与贡献)）。
|
|
8
8
|
|
|
9
|
-
> 状态：**alpha**——能力面是经六周真实日常使用打磨出的原型（生于 2026-09-08，经两轮实际运营与一次冷启动披露审计检验，bb 课程家族在四门课真实运行）；分发面 v0.3 是首个可安装形态——经一次全新实例验收，尚无外部用户。Beta 门槛：行为契约（#34）落地 · 两位成员真实装机 · 旧实例转换走通 · 验收脚本可重放绿。`.
|
|
9
|
+
> 状态：**alpha**——能力面是经六周真实日常使用打磨出的原型（生于 2026-09-08，经两轮实际运营与一次冷启动披露审计检验，bb 课程家族在四门课真实运行）；分发面 v0.3 是首个可安装形态——经一次全新实例验收，尚无外部用户。Beta 门槛：行为契约（#34）落地 · 两位成员真实装机 · 旧实例转换走通 · 验收脚本可重放绿。`.owfa/VERSION` 锚定的是内核契约而非产品成熟度——阶段标签在这里与 release notes。2026-10-02 转为团队项目。文档语言 2026-10-06 起切换为英文。2026-10-25：框架本体有了自己的分发通道——npm CLI `owfa`（`init` / `upgrade` / `doctor` / `add`），补上「clone + 拷两棵树 + 手写 AGENTS.md」的缺口（issues #45/#46）；npm 名 `owfa` 因相似性策略冻结，申请中，`owfadev` 为兜底命名空间。
|
|
10
|
+
## 为什么是 OWFA
|
|
11
|
+
|
|
12
|
+
两重便利，一条原则。
|
|
13
|
+
|
|
14
|
+
**别再用手指数路。** 没有工作区时，每次会话你都在重新解释：文件在哪、那门课的页面什么意思、哪个视频看过了、上周定了什么。OWFA 把这个方向倒过来——信息自己登记进 wiki（map、save、域包），agent 自己去找。价值就是最朴素的那种便利：原本需要你手动指向的信息，变成 agent 自己能找到的答案。
|
|
15
|
+
|
|
16
|
+
**任意 harness，你的上下文。** OWFA 以 AGENTS.md + 技能的形态交付，不是一项服务——所以它不挑哪个 agent harness 来读。今天在一个 harness 里跑，明天换一个，或者同时跑两个：工作区、记忆与插件都跟着你走。插件线把这点说得最具体：`bili` 包（含其自主 agent 成员）把 B 站变成可查询的档案——在一个 harness 里养起来的东西，在任何读 AGENTS.md 的 harness 里同样养得起来。你租用的是 harness，不是投进一座围墙花园。
|
|
17
|
+
|
|
10
18
|
|
|
11
19
|
## 关于命名
|
|
12
20
|
|
|
13
|
-
**OWFA — One Workspace For All (agents)。** 一个工作区——你拥有的目录，装着 `vault/`、`wiki/`、`AGENTS.md` 与框架本体——你使用的每一个 agent 都重新进入它，而不是每次会话重新认识它。*All* 指的是*你的*所有 agent，不是所有人，也不是托管服务；人始终是所有者与审计锚点。`vault-wiki` 退出公开面：公开文案称 **OWFA**（或 **OWFA Core**），GitHub 家在 **`owfadev/owfa`**，CLI 以 `owfa` 之名发布。npm 地址尚未空闲——npm 以「与 `ow`/`ora` 过于相似」冻结了 `owfa`，申诉进行中，`owfadev` 为兜底包。完整的理据、分层与撞名对策：[`.
|
|
21
|
+
**OWFA — One Workspace For All (agents)。** 一个工作区——你拥有的目录，装着 `vault/`、`wiki/`、`AGENTS.md` 与框架本体——你使用的每一个 agent 都重新进入它，而不是每次会话重新认识它。*All* 指的是*你的*所有 agent，不是所有人，也不是托管服务；人始终是所有者与审计锚点。`vault-wiki` 退出公开面：公开文案称 **OWFA**（或 **OWFA Core**），GitHub 家在 **`owfadev/owfa`**，CLI 以 `owfa` 之名发布。npm 地址尚未空闲——npm 以「与 `ow`/`ora` 过于相似」冻结了 `owfa`，申诉进行中，`owfadev` 为兜底包。完整的理据、分层与撞名对策：[`.owfa/docs/naming.md`](https://github.com/owfadev/owfa/blob/master/.owfa/docs/naming.md)。
|
|
14
22
|
|
|
15
23
|
## 它做什么
|
|
16
24
|
|
|
@@ -39,17 +47,17 @@
|
|
|
39
47
|
|
|
40
48
|
| 目录 | 内容 |
|
|
41
49
|
|------|------|
|
|
42
|
-
| `.
|
|
50
|
+
| `.owfa/` | 框架树，v0.4 分仓后只随内核：`plugins/domains/<pkg>/`（一包一目录：`PKG.yaml` + 家族母本——默认 init 落地内嵌 **personal** 套件即 21 个前 core 插件；随后按需 cuhksz 8、lark 4、email、bili、project）。目录边界 == 层级边界 == 包边界；`PKG.yaml` 声明名册，内核对账家族闭包；`.owfa/VERSION` 锚定框架版本（包 `compat` 下限对它校验）。注入次序 = 依赖拓扑 + 字典序；AGENTS 注入区分层——成员级域件退出注入区（家族名册 + 技能 + 按需 manifest 读取承担曝光），受内核字节预算约束；全局插件可声明桥，必依桥由内核校验。另有 6 个框架命令母本（套件自有命令随包落地）、协议工件（registry、actions、experiments）与机械脚本 owfa_kernel、pipeline、wikilib——纯标准库零依赖；套件正仓为 owfa-personal，内嵌副本在 `payloads/personal/` |
|
|
43
51
|
| `connectors/` | 连接器母本：部署侧 CLI 事实接口 + 技能使用披露。`connectors/*/SKILL.md` 经内核 deploy 落入 `.agents/skills/`；现有 bb-cli、sis-cli、mail-cli、bili-cli。连接器随各自包的 `PKG.yaml` 走 |
|
|
44
52
|
| Packages | 索引在 [registry](https://github.com/owfadev/registry)（Obsidian 模式：包自托管于各自仓，一行 PR 即上架门）。`kernel install`/`list-remote` 对它解析；未入索引的仓 `--yes` 可装（trust: unknown）。组织仓 `pkg-cuhksz` / `pkg-lark` / `pkg-email` / `pkg-bili` / `pkg-project` / `pkg-github` 承载各包，带完整文件谱系拆分 |
|
|
45
53
|
| `.agents/skills/` | 命令与连接器技能的部署副本（拆分后框架命令在此；连接器技能随包到达） |
|
|
46
54
|
| `bin/` + `templates/` + `package.json` | npm 通道：`owfa` CLI、AGENTS 种子、包清单。`test/` 与 `scripts/` 仅供开发，不随包发布 |
|
|
47
|
-
| `test-repo/` | 本地测试沙盒——2026-10-13 起不入 git（owner 裁定；全新 clone 不含它）。需要 AGENTS.md 上下文的实验用临时部署；设置与规则见 [`.
|
|
48
|
-
| `.
|
|
55
|
+
| `test-repo/` | 本地测试沙盒——2026-10-13 起不入 git（owner 裁定；全新 clone 不含它）。需要 AGENTS.md 上下文的实验用临时部署；设置与规则见 [`.owfa/docs/sandbox.md`](https://github.com/owfadev/owfa/blob/master/.owfa/docs/sandbox.md)。框架仓自身不带 AGENTS.md——库姿态；开发规则在 [CONTRIBUTING.md](https://github.com/owfadev/owfa/blob/master/CONTRIBUTING.md) |
|
|
56
|
+
| `.owfa/docs/` | 人读文档：`intro.md` 导论、`mechanics.md` 机制、`usage.md` 使用指南、`deployment.md` 全指南 / `quickstart.md` 五分钟路径、`instance-git.md` 实例侧 git 最小契约、`research-*.md` 研究文件——文末直链。权威机制在内核参考 skill；文档不复写机制 |
|
|
49
57
|
|
|
50
58
|
## 参与贡献
|
|
51
59
|
|
|
52
|
-
欢迎贡献，插件是预定贡献面：新能力是新插件，不是 fork 框架。三条路径，由小到大——为你使用的 CLI 写一个连接器技能；写一个把外部信息源适配进 wiki 的域插件（三路径表与开发循环见 [`developer.md`](https://github.com/owfadev/owfa/blob/master/.
|
|
60
|
+
欢迎贡献，插件是预定贡献面：新能力是新插件，不是 fork 框架。三条路径，由小到大——为你使用的 CLI 写一个连接器技能；写一个把外部信息源适配进 wiki 的域插件（三路径表与开发循环见 [`developer.md`](https://github.com/owfadev/owfa/blob/master/.owfa/docs/developer.md)）；或改进 core。域包自托管于各自仓；上架 = 向 [registry](https://github.com/owfadev/registry) 提一行 PR，那是人工审核的信任门。Bug 与行为问题走 issues；框架本体收 PR。
|
|
53
61
|
|
|
54
62
|
## 协作
|
|
55
63
|
|
|
@@ -57,15 +65,15 @@
|
|
|
57
65
|
|
|
58
66
|
## 快速开始
|
|
59
67
|
|
|
60
|
-
两条入口。**通道（推荐）：** `npx owfa init my-workspace`——安装器要 Node 16.7+，Core 要 Python 3.9+；无需 clone（npm 名申请期间用 `npx owfadev init` 兜底）。**手动：** clone 本仓并按 [quickstart.md](https://github.com/owfadev/owfa/blob/master/.
|
|
68
|
+
两条入口。**通道（推荐）：** `npx owfa init my-workspace`——安装器要 Node 16.7+，Core 要 Python 3.9+；无需 clone（npm 名申请期间用 `npx owfadev init` 兜底）。**手动：** clone 本仓并按 [quickstart.md](https://github.com/owfadev/owfa/blob/master/.owfa/docs/quickstart.md) 的五步走，然后 `python .owfa/scripts/owfa_kernel.py all`。含包与升级的全指南：[deployment.md](https://github.com/owfadev/owfa/blob/master/.owfa/docs/deployment.md)。
|
|
61
69
|
|
|
62
70
|
前提：Python 3.9+，纯标准库，框架本身免安装（连接器自带依赖）；仅 npm 通道要 Node 16.7+；推荐 git（实例快照）；一个会读 AGENTS.md 与 skills 的 agent 环境，如 ZCode；Obsidian 可选，仅查看器。
|
|
63
71
|
|
|
64
|
-
在仓库根开一个 agent 会话。AGENTS.md 是章程，含插件注入区；十三个命令经自然语言触发：**map / save / profile / query / check / plugin / lark-map / bb-map / asset-read / 内核参考 / teach / quiz / track**——map、save、profile、query、check、plugin、lark-map、bb-map、asset-read、
|
|
72
|
+
在仓库根开一个 agent 会话。AGENTS.md 是章程，含插件注入区；十三个命令经自然语言触发：**owfa-map / owfa-save / owfa-profile / owfa-query / owfa-check / owfa-plugin / lark-map / bb-map / asset-read / 内核参考 / teach / quiz / track**——owfa-map、owfa-save、owfa-profile、owfa-query、owfa-check、owfa-plugin、lark-map、bb-map、asset-read、owfa-kernel、bb-teach、bb-quiz、bb-track；母本在 `.owfa/command/`。丢一个文件进 `vault/`，对 agent 说「owfa-map」——这就是第一次使用。
|
|
65
73
|
|
|
66
74
|
## 部署
|
|
67
75
|
|
|
68
|
-
OWFA 有三层：**OWFA CLI**（安装器，绝不拷入工作区）、**OWFA Core**（`.
|
|
76
|
+
OWFA 有三层：**OWFA CLI**（安装器，绝不拷入工作区）、**OWFA Core**（`.owfa/` + `.agents/skills/`，被安装之物）与 **kernel**（Core 内的纯标准库 Python 脚本——没有单独的内核安装；Python 3.9+ 即可运行）。`.owfa/plugins/domains/<pkg>/` 下的域包是可选的。
|
|
69
77
|
|
|
70
78
|
```bash
|
|
71
79
|
npx owfa init my-workspace # 目标名；申请期间用 npx owfadev init
|
|
@@ -78,25 +86,25 @@ npx owfa upgrade # 日后：替换框架树，保留实例状
|
|
|
78
86
|
|
|
79
87
|
名字申请期间，把上面每条 `npx owfa` 换成 `npx owfadev` 即可（或全局安装任一包；两者都暴露 `owfa` 命令）。
|
|
80
88
|
|
|
81
|
-
`init` 是加法的：既有内容不动，已有 `AGENTS.md` 保留、只追加注入区。`upgrade` 替换 `.
|
|
89
|
+
`init` 是加法的：既有内容不动，已有 `AGENTS.md` 保留、只追加注入区。`upgrade` 替换 `.owfa/` 与 `.agents/skills/`（实例数据永不触碰），保留内核迁移台账、journal 与 registry 缓存。
|
|
82
90
|
|
|
83
|
-
- 全部署指南（组件、通道、包、升级、故障）：[`.
|
|
84
|
-
- 五分钟路径：[`.
|
|
85
|
-
- 通道设计与发布手册：[`.
|
|
91
|
+
- 全部署指南（组件、通道、包、升级、故障）：[`.owfa/docs/deployment.md`](https://github.com/owfadev/owfa/blob/master/.owfa/docs/deployment.md)
|
|
92
|
+
- 五分钟路径：[`.owfa/docs/quickstart.md`](https://github.com/owfadev/owfa/blob/master/.owfa/docs/quickstart.md)
|
|
93
|
+
- 通道设计与发布手册：[`.owfa/docs/distribution.md`](https://github.com/owfadev/owfa/blob/master/.owfa/docs/distribution.md)
|
|
86
94
|
|
|
87
95
|
## 文档索引
|
|
88
96
|
|
|
89
|
-
- [.
|
|
90
|
-
- [.
|
|
91
|
-
- [.
|
|
92
|
-
- [.
|
|
93
|
-
- [.
|
|
94
|
-
- [.
|
|
95
|
-
- [.
|
|
96
|
-
- [.
|
|
97
|
-
- [.
|
|
98
|
-
- [.
|
|
99
|
-
- `.
|
|
97
|
+
- [.owfa/docs/deployment.md](https://github.com/owfadev/owfa/blob/master/.owfa/docs/deployment.md) — 部署指南：组件、通道、首跑、包、升级、故障
|
|
98
|
+
- [.owfa/docs/naming.md](https://github.com/owfadev/owfa/blob/master/.owfa/docs/naming.md) — 命名：本义展开、每个词的承诺、两名两职、异议与撞名对策
|
|
99
|
+
- [.owfa/docs/distribution.md](https://github.com/owfadev/owfa/blob/master/.owfa/docs/distribution.md) — npm 通道：命令、工件、版本不变量、发布手册、安全姿态
|
|
100
|
+
- [.owfa/docs/packages.md](https://github.com/owfadev/owfa/blob/master/.owfa/docs/packages.md) — 包机制与设计理据：布局、PKG.yaml、不变量、版本、卸载契约、决策台账
|
|
101
|
+
- [.owfa/docs/developer.md](https://github.com/owfadev/owfa/blob/master/.owfa/docs/developer.md) — 开发者指南：插件落位三路径表、开发循环、注册与发现
|
|
102
|
+
- [.owfa/docs/agents-example.md](https://github.com/owfadev/owfa/blob/master/.owfa/docs/agents-example.md) / [.owfa/docs/log-example.md](https://github.com/owfadev/owfa/blob/master/.owfa/docs/log-example.md) — AGENTS.md 与 log.md 的实例种子（框架仓自身两者都不带）
|
|
103
|
+
- [.owfa/docs/intro.md](https://github.com/owfadev/owfa/blob/master/.owfa/docs/intro.md) — 导论：为什么是这个框架，叙事与谱系
|
|
104
|
+
- [.owfa/docs/mechanics.md](https://github.com/owfadev/owfa/blob/master/.owfa/docs/mechanics.md) — 机制：每个机制再深一层，附 bb 家族走查；动框架前先读
|
|
105
|
+
- [.owfa/docs/usage.md](https://github.com/owfadev/owfa/blob/master/.owfa/docs/usage.md) — 使用指南：三种工作循环（库务、课程学习、协作开发）
|
|
106
|
+
- [.owfa/docs/quickstart.md](https://github.com/owfadev/owfa/blob/master/.owfa/docs/quickstart.md) — 五分钟路径：一条命令或手动五步，然后首跑
|
|
107
|
+
- `.owfa/protocol/` — 字段注册表、行动纪律、披露范式
|
|
100
108
|
|
|
101
109
|
## 许可
|
|
102
110
|
|