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
|
@@ -9,9 +9,9 @@ OWFA has three layers, and only one of them is "installed":
|
|
|
9
9
|
| Layer | What it is | Where it lives | Installed? |
|
|
10
10
|
|---|---|---|---|
|
|
11
11
|
| **OWFA CLI** | the installer / upgrader (`init`, `upgrade`, `doctor`, `add`, `list`, `pkg`) | npm package, run via `npx` or a global install | no — it stays outside the workspace |
|
|
12
|
-
| **OWFA Core** | the framework body: plugins, commands, protocols, kernel, skill copies | `.
|
|
13
|
-
| **kernel** | the deterministic Python engine (`validate`, `inject`, `registry`, `deploy`, `install`) | `.
|
|
14
|
-
| **packages** | optional domain extensions (course, lark, email, bili, project…) | `.
|
|
12
|
+
| **OWFA Core** | the framework body: plugins, commands, protocols, kernel, skill copies | `.owfa/` + `.agents/skills/` | yes — copied into the workspace |
|
|
13
|
+
| **kernel** | the deterministic Python engine (`validate`, `inject`, `registry`, `deploy`, `install`) | `.owfa/scripts/owfa_kernel.py` | no — it ships **inside** Core; there is no separate kernel install |
|
|
14
|
+
| **packages** | optional domain extensions (course, lark, email, bili, project…) | `.owfa/plugins/domains/<pkg>/` | on demand |
|
|
15
15
|
| **instance** | the workspace you own: `vault/`, `wiki/`, `AGENTS.md`, the framework body | your directory | — |
|
|
16
16
|
|
|
17
17
|
The call chain is one direction:
|
|
@@ -29,12 +29,11 @@ my-workspace/
|
|
|
29
29
|
├── wiki/ # the markdown world
|
|
30
30
|
│ ├── notes/ sessions/ vault/
|
|
31
31
|
│ └── index.md tags.md hot.md log.md # derived, rebuilt by the pipeline
|
|
32
|
-
├── .
|
|
33
|
-
│ ├── VERSION # framework anchor (0.
|
|
32
|
+
├── .owfa/ # OWFA Core (kernel-only tree since the v0.4 split)
|
|
33
|
+
│ ├── VERSION # framework anchor (0.4.0)
|
|
34
34
|
│ ├── scripts/ # kernel + pipeline + wikilib
|
|
35
|
-
│ ├── plugins/
|
|
36
|
-
│ ├──
|
|
37
|
-
│ ├── command/ # command masters
|
|
35
|
+
│ ├── plugins/domains/ # installed packages — the embedded personal suite (21 members) lands here on init; the channel itself ships no plugins
|
|
36
|
+
│ ├── command/ # framework command masters (suite-owned commands ride with their package)
|
|
38
37
|
│ └── docs/ # this guide and friends
|
|
39
38
|
└── .agents/skills/ # deployed command/connector skill copies
|
|
40
39
|
```
|
|
@@ -62,7 +61,7 @@ All channels deploy the same Core tree; pick by environment, not by feature.
|
|
|
62
61
|
| npm, target name | `npx owfa init my-workspace` | **name application pending** (npm froze `owfa` as too similar to `ow`/`ora`) |
|
|
63
62
|
| npm, fallback name | `npx owfadev init my-workspace` | same CLI, bins `owfa` + `owfadev`; to be published if the name is not granted |
|
|
64
63
|
| git, clone-as-instance | `git clone https://github.com/owfadev/owfa.git my-workspace` | works today |
|
|
65
|
-
| git, embed into an existing vault | clone the template elsewhere, copy `.
|
|
64
|
+
| git, embed into an existing vault | clone the template elsewhere, copy `.owfa/` + `.agents/skills/` | works today |
|
|
66
65
|
| template + instance (developers) | a template clone + a separate instance | see [CONTRIBUTING.md](../../CONTRIBUTING.md) |
|
|
67
66
|
|
|
68
67
|
> Until the npm name is served by the registry, the git channel is the working path. Do not treat `npx owfa` as live before `npm view owfa version` returns a version.
|
|
@@ -84,13 +83,14 @@ npx owfadev doctor # fallback: same check through the fallback
|
|
|
84
83
|
|
|
85
84
|
**Command forms.** `npx <package> <verb>` needs no global install. A global install (`npm i -g owfa` or `npm i -g owfadev`) puts **both** `owfa` and `owfadev` on `PATH`. The rest of this guide writes `owfa <verb>` for the CLI and `kernel …` for the Python engine; substitute `npx owfa` / `npx owfadev` if you are not installing globally.
|
|
86
85
|
|
|
87
|
-
`init`
|
|
86
|
+
`init` is two-stage by default (the v0.4 final shape — this is the only shape the channel ships):
|
|
88
87
|
|
|
89
|
-
1. copies `.
|
|
90
|
-
2. creates `vault/`, `wiki/notes/`, `wiki/sessions/`, `wiki/vault
|
|
88
|
+
1. copies `.owfa/` and `.agents/skills/` from the tarball and runs `python .owfa/scripts/owfa_kernel.py all` (validate → inject → registry → deploy) over the kernel-only tree;
|
|
89
|
+
2. installs the embedded **personal suite** (the 21 former core plugins, a vetted copy of the **owfa-personal** package at `payloads/personal/`) offline — its `PKG.yaml` `skeleton:` declaration creates `vault/`, `wiki/notes/`, `wiki/sessions/`, `wiki/vault/`, and its command masters (`owfa-map`, `owfa-profile`, `owfa-save`) deploy with it;
|
|
91
90
|
3. writes `AGENTS.md` from the seed, or appends **only the injection region** to an existing one (the handwritten part is preserved; half-present markers are refused);
|
|
92
|
-
4.
|
|
93
|
-
|
|
91
|
+
4. optionally installs packages (`--packages cuhksz,lark`), stopping at the first package that stages a semantic migration.
|
|
92
|
+
|
|
93
|
+
`--core none` skips stage 2 (a kernel-only instance: no skeleton, no suite); `--core <pkg-id>` takes the suite from the registry instead of the embedded copy.
|
|
94
94
|
|
|
95
95
|
Useful flags:
|
|
96
96
|
|
|
@@ -98,7 +98,7 @@ Useful flags:
|
|
|
98
98
|
- `--packages a,b` — install packages from the registry during init;
|
|
99
99
|
- `--force` — re-copy the framework trees over an existing instance, preserving the kernel's migration ledger, journal and registry cache. Instance data (`vault/`, `wiki/`) is never touched.
|
|
100
100
|
|
|
101
|
-
If the directory already contains `.
|
|
101
|
+
If the directory already contains `.owfa/`, `init` refuses; use `owfa upgrade` (or `--force` deliberately).
|
|
102
102
|
|
|
103
103
|
### 4.2 git channel — the five manual steps
|
|
104
104
|
|
|
@@ -114,30 +114,35 @@ rm -rf .git && git init
|
|
|
114
114
|
**Embed into an existing vault**: clone the template somewhere else, then copy the two trees into the target root:
|
|
115
115
|
|
|
116
116
|
```bash
|
|
117
|
-
cp -R /path/to/owfa/.
|
|
117
|
+
cp -R /path/to/owfa/.owfa /path/to/my-workspace/
|
|
118
118
|
cp -R /path/to/owfa/.agents/skills /path/to/my-workspace/.agents/
|
|
119
119
|
```
|
|
120
120
|
|
|
121
|
+
Since the v0.4 split the copied tree carries the kernel only — no plugins. Install the embedded suite (it ships inside the clone at `payloads/personal/`) and the skeleton with it:
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
python3 .owfa/scripts/owfa_kernel.py install personal --path /path/to/owfa/payloads/personal
|
|
125
|
+
```
|
|
126
|
+
|
|
121
127
|
Then, at the workspace root:
|
|
122
128
|
|
|
123
129
|
1. **Write `AGENTS.md`** — one identity paragraph, one layout paragraph, and the injection markers verbatim from [agents-example.md](agents-example.md). If an `AGENTS.md` already exists, paste in only the marker block (or let `owfa init` append it).
|
|
124
|
-
2. **
|
|
125
|
-
3. **Converge**:
|
|
130
|
+
2. **Converge**:
|
|
126
131
|
|
|
127
132
|
```bash
|
|
128
|
-
python .
|
|
133
|
+
python .owfa/scripts/owfa_kernel.py all
|
|
129
134
|
```
|
|
130
135
|
|
|
131
|
-
Expected:
|
|
136
|
+
Expected: the personal suite's 21 members validate, package rosters reconcile, the injection region is rebuilt, command copies are in sync. The four skeleton directories (`vault/`, `wiki/notes/`, `wiki/sessions/`, `wiki/vault/`) came with the suite install — its `PKG.yaml` `skeleton:` declares them; the channel hardcodes no instance layout.
|
|
132
137
|
|
|
133
138
|
### 4.3 "Installing the kernel"
|
|
134
139
|
|
|
135
|
-
There is nothing separate to install. The kernel is the file `.
|
|
140
|
+
There is nothing separate to install. The kernel is the file `.owfa/scripts/owfa_kernel.py` inside Core; Python 3.9+ runs it. Verify it:
|
|
136
141
|
|
|
137
142
|
```bash
|
|
138
|
-
python3 .
|
|
139
|
-
python3 .
|
|
140
|
-
python3 .
|
|
143
|
+
python3 .owfa/scripts/owfa_kernel.py validate # structural check, read-only
|
|
144
|
+
python3 .owfa/scripts/owfa_kernel.py ls # the personal suite's 21 members (the framework tree itself carries none)
|
|
145
|
+
python3 .owfa/scripts/owfa_kernel.py pkg # installed packages + the unclaimed core remainder
|
|
141
146
|
```
|
|
142
147
|
|
|
143
148
|
On Windows, `python` may be `py -3`; the CLI probes `python3`, `python`, then `py -3`. Set `OWFA_PYTHON=/path/to/python3` to override. If the kernel is missing, the Core copy is incomplete — recopy the tree, do not "pip install" anything.
|
|
@@ -175,7 +180,7 @@ The daily loops — library keeping, course learning, collaborative development
|
|
|
175
180
|
|
|
176
181
|
## 7. Packages — finding and installing
|
|
177
182
|
|
|
178
|
-
Core
|
|
183
|
+
Core itself is two-stage since v0.4: the kernel payload lands first, then `init` installs the embedded **blessed suite** — the former framework plugins, now shipped as the **owfa-personal** package (a vetted copy bundled inside the tarball) — by default (`--core none` skips it, `--core <pkg>` installs a different core package). External systems arrive the same way, as **packages**: one directory `.owfa/plugins/domains/<pkg>/` with a `PKG.yaml` roster, plugin masters, commands and connectors.
|
|
179
184
|
|
|
180
185
|
### 7.1 Find what exists
|
|
181
186
|
|
|
@@ -185,28 +190,28 @@ Run these inside the instance:
|
|
|
185
190
|
owfa list # registry catalog: versions, compat floors, installed marks
|
|
186
191
|
owfa pkg # what is installed here: members, connectors, core remainder
|
|
187
192
|
# the same through the kernel:
|
|
188
|
-
python3 .
|
|
189
|
-
python3 .
|
|
193
|
+
python3 .owfa/scripts/owfa_kernel.py list-remote
|
|
194
|
+
python3 .owfa/scripts/owfa_kernel.py pkg
|
|
190
195
|
```
|
|
191
196
|
|
|
192
|
-
The registry is the GitHub index at `owfadev/registry`; before installing, it is also readable directly as `INDEX.yaml` in that repository. Each row shows the package version, the framework compat floor, the member plugins and the trust level.
|
|
197
|
+
The registry is the GitHub index at `owfadev/owfa-registry`; before installing, it is also readable directly as `INDEX.yaml` in that repository. Each row shows the package version, the framework compat floor, the member plugins and the trust level.
|
|
193
198
|
|
|
194
199
|
### 7.2 Install a package
|
|
195
200
|
|
|
196
201
|
```bash
|
|
197
202
|
owfa add cuhksz # wraps kernel install + convergence
|
|
198
203
|
# equivalent, and more explicit:
|
|
199
|
-
python3 .
|
|
204
|
+
python3 .owfa/scripts/owfa_kernel.py install cuhksz --yes
|
|
200
205
|
```
|
|
201
206
|
|
|
202
207
|
This is also what the agent's **plugin** command does: you can ask the agent to install a package by name, and it drives the same kernel. The CLI is the human/script equivalent.
|
|
203
208
|
|
|
204
|
-
What lands: plugin masters under `.
|
|
209
|
+
What lands: plugin masters under `.owfa/plugins/domains/<pkg>/`, command masters, in-repo connectors, skill copies, injection blocks, registry rows. Then the kernel converges. If the package declares a **first-run semantic migration** (root packages such as `project` do), the install stages it and `validate` stays red until an agent performs the semantic step:
|
|
205
210
|
|
|
206
211
|
```bash
|
|
207
|
-
python3 .
|
|
212
|
+
python3 .owfa/scripts/owfa_kernel.py migrate <pkg>
|
|
208
213
|
# read the printed page, create the declaration/identity page, then:
|
|
209
|
-
python3 .
|
|
214
|
+
python3 .owfa/scripts/owfa_kernel.py migrate <pkg> --clear
|
|
210
215
|
```
|
|
211
216
|
|
|
212
217
|
The CLI stops and reports this instead of pretending convergence. `owfa add` exits non-zero in that state.
|
|
@@ -216,16 +221,16 @@ Other forms:
|
|
|
216
221
|
- `kernel install <pkg>@<tag>` — pin a release tag;
|
|
217
222
|
- `kernel install <owner>/<repo> --yes` — an unindexed repository (trust: unknown; `--yes` is the trust gate);
|
|
218
223
|
- `kernel install <pkg> --path ./local-pkg` — a local package (channel C, no registry);
|
|
219
|
-
- `--without a,b` — subset grammar is reserved; v1 reports not-yet-open. Offline alternative: copy `domains/<pkg>/` into `.
|
|
224
|
+
- `--without a,b` — subset grammar is reserved; v1 reports not-yet-open. Offline alternative: copy `domains/<pkg>/` into `.owfa/plugins/domains/` and rerun `all`.
|
|
220
225
|
|
|
221
226
|
Trust levels are visible in `owfa list`: `framework-bundled` and `reviewed-3rd-party` install without a prompt; anything else needs `--yes` and is reported as unknown.
|
|
222
227
|
|
|
223
228
|
### 7.3 Upgrade and uninstall packages
|
|
224
229
|
|
|
225
230
|
```bash
|
|
226
|
-
python3 .
|
|
227
|
-
python3 .
|
|
228
|
-
python3 .
|
|
231
|
+
python3 .owfa/scripts/owfa_kernel.py upgrade # reconciliation report (read-only)
|
|
232
|
+
python3 .owfa/scripts/owfa_kernel.py upgrade <pkg> --yes # silent reinstall, per package, never cascaded
|
|
233
|
+
python3 .owfa/scripts/owfa_kernel.py uninstall <pkg> --yes
|
|
229
234
|
```
|
|
230
235
|
|
|
231
236
|
- Package versions are release ordinals riding their own tags; member plugin versions do not lockstep.
|
|
@@ -237,30 +242,30 @@ python3 .meta/scripts/wiki_plugin_kernel.py uninstall <pkg> --yes
|
|
|
237
242
|
### npm channel
|
|
238
243
|
|
|
239
244
|
```bash
|
|
240
|
-
npx owfa upgrade # replace .
|
|
245
|
+
npx owfa upgrade # replace .owfa/ + .agents/skills/ with the channel's version
|
|
241
246
|
npx owfa upgrade --check # read-only report
|
|
242
247
|
npx owfa upgrade --backup # keep a copy under .owfa/backup/<version>-<timestamp>/
|
|
243
248
|
```
|
|
244
249
|
|
|
245
|
-
`upgrade` preserves the instance-local kernel state (`.
|
|
250
|
+
`upgrade` preserves the instance-local kernel state (`.owfa/migrations/pending.json`, `.owfa/kernel-journal.log`, `.owfa/registry-cache.yaml`), replaces local edits under the two framework trees (instance hotfixes belong in git), and reruns `all`. A pending semantic migration blocks convergence and is reported with the exact `migrate` command.
|
|
246
251
|
|
|
247
252
|
### git channel
|
|
248
253
|
|
|
249
|
-
Re-copy `.
|
|
254
|
+
Re-copy `.owfa/` and `.agents/skills/` from the new template revision (review the diff, do not blind-copy over pending migrations), then `kernel all`. The instance git snapshot is the rollback path.
|
|
250
255
|
|
|
251
|
-
Framework versions are anchored by `.
|
|
256
|
+
Framework versions are anchored by `.owfa/VERSION` (0.4.0); a target-side semantic migration can be staged by an upgrade, with the same tri-face warning and `kernel migrate` flow.
|
|
252
257
|
|
|
253
258
|
## 9. Uninstall
|
|
254
259
|
|
|
255
260
|
- **A package**: `kernel uninstall <pkg> --yes`; data zones stay, credentials are only reminded, never deleted.
|
|
256
|
-
- **The whole framework**: delete `.
|
|
261
|
+
- **The whole framework**: delete `.owfa/`, `.agents/skills/`, and the `AGENTS.md` injection region block. `vault/` and `wiki/` are yours; dispose of them as you see fit. Nothing else is installed.
|
|
257
262
|
|
|
258
263
|
## 10. Troubleshooting
|
|
259
264
|
|
|
260
265
|
| Symptom | Cause / fix |
|
|
261
266
|
|---|---|
|
|
262
267
|
| `Python 3.9+ not found` | install Python 3, or set `OWFA_PYTHON`; the installer is Node-only, the runtime is Python |
|
|
263
|
-
| `already contains .
|
|
268
|
+
| `already contains .owfa/` | it is an instance — `owfa upgrade`; `--force` re-copies the trees |
|
|
264
269
|
| `npx` runs an old version | `npx owfa@latest …`; npm caches by version range |
|
|
265
270
|
| `publish` / `npx` 403 on `owfa` | the name is frozen on similarity grounds; use the `owfadev` fallback or wait for the application |
|
|
266
271
|
| upgrade blocked by pending migrations | run `kernel migrate <pkg>`, perform the semantic step, then `--clear` |
|
|
@@ -276,11 +281,11 @@ Framework versions are anchored by `.meta/VERSION` (0.3); a target-side semantic
|
|
|
276
281
|
| `vault/` | real assets | yes — the human owns it |
|
|
277
282
|
| `wiki/` | markdown world, proxies, notes, sessions | yes, via commands; derived pages are rebuilt |
|
|
278
283
|
| `wiki/index.md`, `tags.md`, `hot.md`, `log.md` | derived layer | no — the pipeline rewrites them |
|
|
279
|
-
| `.
|
|
280
|
-
| `.
|
|
281
|
-
| `.
|
|
284
|
+
| `.owfa/plugins/` | Core plugins + installed packages | no — framework authoring |
|
|
285
|
+
| `.owfa/scripts/` | kernel, pipeline, wikilib | no — framework authoring |
|
|
286
|
+
| `.owfa/command/` | command masters | no |
|
|
282
287
|
| `.agents/skills/` | deployed skill copies | no — `kernel deploy` syncs them |
|
|
283
|
-
| `.
|
|
288
|
+
| `.owfa/migrations/` | staged semantic migrations + ledger | no — kernel zone |
|
|
284
289
|
| `projects/` | project containers (if the project package is installed) | yes — project-owned |
|
|
285
290
|
|
|
286
291
|
## 12. FAQ
|
|
@@ -7,8 +7,8 @@
|
|
|
7
7
|
| Your plugin is… | It lands… | Trust gate |
|
|
8
8
|
|---|---|---|
|
|
9
9
|
| a **domain member** (depends chain reaches a domain root, e.g. bb-family) | that domain package's repo — PR there. Not a choice: the family closure claims it mechanically (`PKG.members` must include you or validate errors) | package maintainers |
|
|
10
|
-
| a **new domain** of its own | your own repo as a package (`PKG.yaml`, see [packages.md](packages.md)) + a one-line PR to the [registry](https://github.com/owfadev/registry) | the registry PR — the human-review gate (inject text and connectors are the security faces, #12) |
|
|
11
|
-
| **cross-cutting / non-domain** (global piece) | the
|
|
10
|
+
| a **new domain** of its own | your own repo as a package (`PKG.yaml`, see [packages.md](packages.md)) + a one-line PR to the [registry](https://github.com/owfadev/owfa-registry) | the registry PR — the human-review gate (inject text and connectors are the security faces, #12) |
|
|
11
|
+
| **cross-cutting / non-domain** (global piece) | the core suite package repo (**owfa-personal**, since the v0.4 split) — PR there | owner review (charter-level, highest bar) |
|
|
12
12
|
|
|
13
13
|
A single plugin never ships bare — the package is the distribution unit. A lone plugin is a single-member package (12 lines of PKG.yaml, see email/bili/project). Users prune with `--without` (subset grammar), so contributing into a big package never forces users to install all of it.
|
|
14
14
|
|
|
@@ -19,8 +19,8 @@ A single plugin never ships bare — the package is the distribution unit. A lon
|
|
|
19
19
|
3. **Integration-test without a monorepo**: in the sandbox (or any instance),
|
|
20
20
|
```
|
|
21
21
|
cd test-repo
|
|
22
|
-
python .
|
|
23
|
-
python .
|
|
22
|
+
python .owfa/scripts/owfa_kernel.py install <pkg> --path /path/to/your/clone
|
|
23
|
+
python .owfa/scripts/owfa_kernel.py validate --scope <pkg>
|
|
24
24
|
```
|
|
25
25
|
`--path` installs the local clone (channel C); iterate freely — reinstall after uninstalling, or just re-copy
|
|
26
26
|
4. **PR** — one thing per commit, `模块: 概述`; self-check per [CONTRIBUTING](../../CONTRIBUTING.md) (framework root: `validate`; sandbox: `all`)
|
|
@@ -22,14 +22,15 @@ The npm tarball is the framework body, byte-for-byte what the git channel copies
|
|
|
22
22
|
|
|
23
23
|
| Path | Contents | In tarball |
|
|
24
24
|
|---|---|---|
|
|
25
|
-
| `.
|
|
26
|
-
| `.agents/skills/` | command/connector skill copies | yes |
|
|
25
|
+
| `.owfa/` | kernel, framework commands, protocol, docs — no plugins (the v0.4 split) | yes |
|
|
26
|
+
| `.agents/skills/` | framework command/connector skill copies | yes |
|
|
27
|
+
| `payloads/personal/` | the embedded **blessed suite** — the owfa-personal package (21 plugin masters + its command masters) that a default init installs offline | yes |
|
|
27
28
|
| `templates/AGENTS.template.md` | the instance shell with the injection markers | yes |
|
|
28
29
|
| `bin/owfa.js` | CLI (zero dependencies) | yes |
|
|
29
30
|
| `README.md`, `LICENSE` | — | yes |
|
|
30
31
|
| `test/`, `scripts/`, `CONTRIBUTING.md`, `.github/` | development-only | no |
|
|
31
32
|
|
|
32
|
-
Local state never ships: `__pycache__`, `*.pyc`, `.
|
|
33
|
+
Local state never ships: `__pycache__`, `*.pyc`, `.owfa/kernel-journal.log`, `.owfa/migrations/pending.json`, `.owfa/registry-cache.yaml`, `test-repo/`. The release gate (`scripts/verify-release.js`) refuses to publish if any of them would be packed.
|
|
33
34
|
|
|
34
35
|
## Commands
|
|
35
36
|
|
|
@@ -43,13 +44,13 @@ owfa pkg
|
|
|
43
44
|
owfa version
|
|
44
45
|
```
|
|
45
46
|
|
|
46
|
-
**init** — additive deployment, the
|
|
47
|
+
**init** — additive deployment, the manual steps in [deployment.md](deployment.md) mechanized, two-stage by default:
|
|
47
48
|
|
|
48
|
-
1. copies `.
|
|
49
|
-
2.
|
|
50
|
-
3.
|
|
51
|
-
4.
|
|
52
|
-
5. optionally installs packages from the registry (`--packages cuhksz,lark`)
|
|
49
|
+
1. copies `.owfa/` and `.agents/skills/` from the tarball
|
|
50
|
+
2. writes `AGENTS.md` from the template when absent; when one exists, **appends only the injection region** (handwritten content before it is preserved byte-for-byte); refuses if the markers are half-present
|
|
51
|
+
3. runs `python .owfa/scripts/owfa_kernel.py all` (validate → inject → registry → deploy) over the kernel-only tree
|
|
52
|
+
4. installs the embedded personal suite offline (`payloads/personal/`) — its `skeleton:` declaration creates `vault/`, `wiki/notes/`, `wiki/sessions/`, `wiki/vault/`; `--core none` skips this stage, `--core <pkg-id>` takes the suite from the registry
|
|
53
|
+
5. optionally installs further packages from the registry (`--packages cuhksz,lark`)
|
|
53
54
|
|
|
54
55
|
A package may declare a **first-run semantic migration** (root packages such as `project` do). Installing it stages the migration, and the CLI stops there with the exact `kernel migrate` command — clearing it is an agent act (create the identity/declaration page), not something a mechanical installer may fake. `init --packages` therefore exits non-zero in that state: the workspace is installed but not converged.
|
|
55
56
|
|
|
@@ -57,9 +58,10 @@ A package may declare a **first-run semantic migration** (root packages such as
|
|
|
57
58
|
|
|
58
59
|
**upgrade** — tree replacement plus convergence:
|
|
59
60
|
|
|
60
|
-
- compares the instance's `.
|
|
61
|
-
- preserves instance-local kernel state: `.
|
|
62
|
-
- **replaces** local edits under `.
|
|
61
|
+
- compares the instance's `.owfa/VERSION` with the tarball's; refuses downgrades unless `--force`
|
|
62
|
+
- preserves instance-local kernel state: `.owfa/migrations/pending.json`, `.owfa/kernel-journal.log`, `.owfa/registry-cache.yaml`
|
|
63
|
+
- **replaces** local edits under `.owfa/` and `.agents/skills/` — instance hotfixes belong in the instance's git history, which is the rollback path (the `--backup` flag also drops a copy under `.owfa/backup/<version>-<timestamp>/`)
|
|
64
|
+
- **converts** an in-tree core (every 0.3 / compat-era instance) into the personal suite package on the way in — the parked masters are rescued from the attic and adopted mechanically (`kernel upgrade personal` later swaps in the canonical suite)
|
|
63
65
|
- reruns `all`; a pending semantic migration blocks convergence and is reported with the exact `kernel migrate` command
|
|
64
66
|
- `--check` is a read-only report
|
|
65
67
|
|
|
@@ -67,13 +69,13 @@ A package may declare a **first-run semantic migration** (root packages such as
|
|
|
67
69
|
|
|
68
70
|
**add** — thin wrapper over `kernel install` plus convergence. Registry trust rules still apply; `--yes` is forwarded. A staged first-run migration stops the command with the exact `migrate` hint (exit non-zero) instead of a false "done".
|
|
69
71
|
|
|
70
|
-
**list** — `kernel list-remote`: the registry catalog with package versions, framework compat floors, member plugins, trust levels and installed marks. **pkg** — `kernel pkg`: what is installed in this instance (packages, members, connectors,
|
|
72
|
+
**list** — `kernel list-remote`: the registry catalog with package versions, framework compat floors, member plugins, trust levels and installed marks. **pkg** — `kernel pkg`: what is installed in this instance (packages, members, connectors, and plugins unclaimed by any package).
|
|
71
73
|
|
|
72
74
|
## Version invariant
|
|
73
75
|
|
|
74
|
-
The
|
|
76
|
+
The version equation is exact equality across five carriers: `.owfa/VERSION` == `package.json` == git tag `vA.B.C` == the published npm version == the GitHub Release. `.owfa/VERSION` carries the **full release number** (`A.B.C`, e.g. `0.4.0`) — not a two-segment anchor riding the package's `major.minor`. The release gate (`scripts/verify-release.js`) refuses any drift: a tag that does not match the package version exactly, a `.owfa/VERSION` that diverges from either, or a publish that would break the equation all fail closed. A patch release therefore bumps all five carriers together in one commit. `.owfa/VERSION` still tracks the kernel contract, not product maturity (stage labels live in the README).
|
|
75
77
|
|
|
76
|
-
Install identification is therefore trivial: `.
|
|
78
|
+
Install identification is therefore trivial: `.owfa/VERSION` says which framework a workspace is on; `owfa version` says which channel the CLI is on.
|
|
77
79
|
|
|
78
80
|
## Release runbook
|
|
79
81
|
|
|
@@ -88,8 +90,8 @@ Every release:
|
|
|
88
90
|
|
|
89
91
|
```bash
|
|
90
92
|
# 1. the framework contract and the package version move together
|
|
91
|
-
$EDITOR .
|
|
92
|
-
$EDITOR package.json # "version": "0.4.0"
|
|
93
|
+
$EDITOR .owfa/VERSION # full A.B.C, e.g. 0.3.0 -> 0.4.0 — VERSION carries the full release number
|
|
94
|
+
$EDITOR package.json # "version": "0.4.0" — must equal .owfa/VERSION exactly
|
|
93
95
|
git commit -am "release: framework 0.4.0"
|
|
94
96
|
git tag v0.4.0 && git push --follow-tags
|
|
95
97
|
```
|
|
@@ -125,8 +127,8 @@ npm pack --dry-run
|
|
|
125
127
|
| Symptom | Cause / fix |
|
|
126
128
|
|---|---|
|
|
127
129
|
| `Python 3.9+ not found` | install Python 3, or set `OWFA_PYTHON=/path/to/python3`; the installer itself is Node-only |
|
|
128
|
-
| `already contains .
|
|
130
|
+
| `already contains .owfa/` | the directory is already an instance — use `owfa upgrade`; `--force` re-copies the trees |
|
|
129
131
|
| `npx` runs an old version | `npx owfa@latest …`; npm caches by version range |
|
|
130
|
-
| upgrade blocked by pending migrations | run `python .
|
|
132
|
+
| upgrade blocked by pending migrations | run `python .owfa/scripts/owfa_kernel.py migrate <pkg>` and follow the printed page before upgrading again |
|
|
131
133
|
| publish fails: name too similar | npm froze `owfa` (similar to `ow`/`ora`); use the `owfadev` fallback or wait for the application; do not retry the same name |
|
|
132
134
|
| Windows: `python` opens the Store | install Python 3 and ensure `py -3` or `python3` works; `OWFA_PYTHON` overrides detection |
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# Machine substrate: `~/.owfa` — connector homes and workspace bindings
|
|
2
|
+
|
|
3
|
+
> v0.4 work order #56 (B1-B3). One machine hosts many OWFA workspaces; connector
|
|
4
|
+
> state must not collide across them. This is the shared contract every OWFA
|
|
5
|
+
> connector inherits by importing `.owfa/scripts/owfa_home.py` — no connector
|
|
6
|
+
> invents its own layout.
|
|
7
|
+
|
|
8
|
+
## Layout
|
|
9
|
+
|
|
10
|
+
```
|
|
11
|
+
~/.owfa/ # machine substrate (env: OWFA_HOME)
|
|
12
|
+
└── connectors/<name>/
|
|
13
|
+
├── bindings.json # registry: [{id, root, home, bot?, installed_at}]
|
|
14
|
+
└── homes/<id>/ # one state dir per binding — credentials,
|
|
15
|
+
# spool, logs; 0600/0700, never in any repo
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
- `<id>` = human alias + 2-byte hash (`repo-a1b2`); the singleton case is
|
|
19
|
+
literally `default`.
|
|
20
|
+
- Homes are **machine-global, not per-instance**: a connector does not read the
|
|
21
|
+
workspace; only its binding records which workspace drains it.
|
|
22
|
+
|
|
23
|
+
## Resolution order
|
|
24
|
+
|
|
25
|
+
`--root/--home` argument → `OWFA_ROOT` env → cwd reverse-lookup in the registry
|
|
26
|
+
→ `homes/default` (single-workspace machines: zero configuration).
|
|
27
|
+
|
|
28
|
+
On a machine with **two or more bindings**, a workspace matching none of them
|
|
29
|
+
still falls through to `homes/default` (degraded-but-healthy) but emits a loud
|
|
30
|
+
stderr warning: default is unregistered there, and two unmatched workspaces
|
|
31
|
+
sharing it would be invisible to `exclusivity_violations`. Remove the ambiguity
|
|
32
|
+
by binding the root explicitly or setting `OWFA_ROOT`.
|
|
33
|
+
|
|
34
|
+
## Invariants
|
|
35
|
+
|
|
36
|
+
1. **One home, one active binding.** Two workspaces draining one spool is a
|
|
37
|
+
semantic error (`exclusivity_violations` → error, the only error-level health
|
|
38
|
+
state in the substrate).
|
|
39
|
+
2. **Unbound workspace = degraded-but-healthy** (warning in domain checks): the
|
|
40
|
+
domain is installed, the skill answers with guidance, nothing drains.
|
|
41
|
+
3. **Unbind detaches, never deletes.** `homes/<id>/` holds credentials and
|
|
42
|
+
spool data — deletion is a human act, confirmed.
|
|
43
|
+
4. **Stale bindings** (workspace root gone) are reported and cleaned on
|
|
44
|
+
confirmation — same rhythm as the tmp zone's stale_after.
|
|
45
|
+
|
|
46
|
+
## Migration from pre-0.4 scattered homes
|
|
47
|
+
|
|
48
|
+
`owfa_home.migrate_legacy_home("qq-cli", "~/.qq-cli")` **moves** the legacy
|
|
49
|
+
directory into `homes/<id>` (move, never copy — credentials must not exist in
|
|
50
|
+
two places) and leaves a symlink at the old path so old absolute references keep
|
|
51
|
+
resolving; the symlink is the 0.5-cleanup item. Version-gated per connector: a
|
|
52
|
+
connector that finds its legacy home on first run offers the migration instead
|
|
53
|
+
of silently creating a second home.
|
|
54
|
+
|
|
55
|
+
## Harness scope
|
|
56
|
+
|
|
57
|
+
Connector manifests (PKG.yaml `connectors[]`) may declare `home:` for external
|
|
58
|
+
connectors whose state lives outside this substrate (declared, not migrated).
|
|
59
|
+
The registry mirrors per-package `harness:` — `universal` connectors are the
|
|
60
|
+
first class; harness-locked ones register honestly and health checks surface the
|
|
61
|
+
mismatch.
|
|
@@ -47,10 +47,10 @@ A minimal chronology: 2026-08 the personal vault founded; 09-08 the prototype la
|
|
|
47
47
|
|---|---|
|
|
48
48
|
| Constitution and collaboration red lines | `AGENTS.md` |
|
|
49
49
|
| Mechanics overview | the kernel reference skill |
|
|
50
|
-
| How the mechanics work | `.
|
|
51
|
-
| Daily usage | `.
|
|
52
|
-
| Using the sandbox | `.
|
|
50
|
+
| How the mechanics work | `.owfa/docs/mechanics.md` |
|
|
51
|
+
| Daily usage | `.owfa/docs/usage.md` |
|
|
52
|
+
| Using the sandbox | `.owfa/docs/sandbox.md` |
|
|
53
53
|
| Why a plugin is designed this way | that plugin's `PLUGIN.md` |
|
|
54
|
-
| Research basis | `.
|
|
55
|
-
| Deployment guide | `.
|
|
54
|
+
| Research basis | `.owfa/docs/research-*.md` |
|
|
55
|
+
| Deployment guide | `.owfa/docs/deployment.md` (five-minute path: `.owfa/docs/quickstart.md`) |
|
|
56
56
|
| Run history and current state | `log.md` |
|
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
```markdown
|
|
6
6
|
# 运行日志
|
|
7
7
|
|
|
8
|
-
> 置顶追加、只增不删;条目 = `- YYYY-MM-DD <类型> [<域>]:一句话`(域标可缺省——无域事务,log 桥)。规则见
|
|
8
|
+
> 置顶追加、只增不删;条目 = `- YYYY-MM-DD <类型> [<域>]:一句话`(域标可缺省——无域事务,log 桥)。规则见 personal 套件(owfa-personal,内嵌副本 `payloads/personal/log/`)的 log 插件,写走 `pipeline.py log`。
|
|
9
9
|
|
|
10
10
|
- 2026-10-12 other:<one sentence: what happened, from which domain, with what outcome>
|
|
11
11
|
- 2026-10-12 map:<one sentence per mapping transaction>
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Docs map — what to read when
|
|
2
2
|
|
|
3
|
-
> The routing table for `.
|
|
3
|
+
> The routing table for `.owfa/docs/` (framework) and package-repo docs. The entry index for agents; skills point here, the documents stay the source of truth.
|
|
4
4
|
|
|
5
5
|
| Situation | Read |
|
|
6
6
|
|---|---|
|
|
@@ -12,12 +12,13 @@
|
|
|
12
12
|
| Installing/upgrading the framework body; npm channel; release runbook | [distribution.md](distribution.md) |
|
|
13
13
|
| The name: OWFA expansion, two names two jobs, collision policy | [naming.md](naming.md) |
|
|
14
14
|
| Converting a legacy (pre-split flat) instance to the package era | [conversion.md](conversion.md) — the eight-step drill walked on a real instance |
|
|
15
|
-
| Instance git usage (snapshots, red lines, recovery) | the
|
|
15
|
+
| Instance git usage (snapshots, red lines, recovery) | the instance-git plugin (personal suite member; canonical repo [owfa-personal](https://github.com/owfadev/owfa-personal), embedded copy at `payloads/personal/instance-git/`) |
|
|
16
16
|
| Framework mechanics: projections, bridges, injection, inject tiers | [mechanics.md](mechanics.md) |
|
|
17
17
|
| (Un)install history, package lifecycle | [mechanics.md](mechanics.md) §7 + [packages.md](packages.md) |
|
|
18
|
+
| Third-party view: develop → publish → install → update → uninstall; name governance | [plugin-lifecycle.md](plugin-lifecycle.md) |
|
|
18
19
|
| Experiments: sandbox or local | [sandbox.md](sandbox.md) |
|
|
19
20
|
| Development rules, commit flow, template + instance workflow | [CONTRIBUTING.md](../../CONTRIBUTING.md) — template-repo root (an instance reads it there, never keeps a copy) |
|
|
20
21
|
| Day-to-day usage loops | [usage.md](usage.md) |
|
|
21
22
|
| What the framework is, intro | [intro.md](intro.md) |
|
|
22
|
-
| Package-side plugin docs (bb family, lark family, …) | the owning `
|
|
23
|
+
| Package-side plugin docs (bb family, lark family, …) | the owning `owfa-*` repo's plugin masters |
|
|
23
24
|
| AGENTS.md seed / log seed examples | [agents-example.md](agents-example.md), [log-example.md](log-example.md) |
|
|
@@ -1,17 +1,17 @@
|
|
|
1
1
|
# Mechanics in Detail
|
|
2
2
|
|
|
3
|
-
> Audience: members and contributors who will modify the framework. The authoritative source of mechanical rules is the kernel reference skill and the `.
|
|
3
|
+
> Audience: members and contributors who will modify the framework. The authoritative source of mechanical rules is the kernel reference skill and the `.owfa/` source code. This document expands the master outline by one level — principles, instance walkthroughs, and hands-on procedures — without copying rule text; where it conflicts with the source, the source prevails. Written 2026-10-04.
|
|
4
4
|
|
|
5
5
|
## 0. One Source, Five Projections
|
|
6
6
|
|
|
7
|
-
Each plugin is one directory, living at `.
|
|
7
|
+
Each plugin is one directory, living at `.owfa/plugins/<id>/`. `PLUGIN.yaml` is the machine-readable body — the manifest. From the manifest, the kernel script mechanically projects into five places:
|
|
8
8
|
|
|
9
9
|
| Projection | Landing point | Source key | Who reads it |
|
|
10
10
|
|---|---|---|---|
|
|
11
11
|
| AGENTS injection region | `<!-- plugin:<id> v<x> -->` marker block | `inject` | The agent of every session; constitution-level disclosure |
|
|
12
12
|
| check inspection block | the `check-inject` block inside the check command | `checks` | The check command; semantic items |
|
|
13
13
|
| command usage block | the `cmd-inject` block inside each command | `usage`, in consumes order | Command execution sites; write-side rules |
|
|
14
|
-
| registry plugin section | `.
|
|
14
|
+
| registry plugin section | `.owfa/protocol/registry.yaml` | `fields` | Commands consulting the field vocabulary before writing pages |
|
|
15
15
|
| skill copy | `.agents/skills/<command>/` | command and connector masters | Deployment-side agents |
|
|
16
16
|
|
|
17
17
|
The key property is idempotent rebuilding. Hand-editing inside marker blocks is forbidden — a rebuild overwrites; prose outside the blocks belongs to humans. There is no second source of truth: changing a rule means changing the manifest, after which the single command `all` converges everything. The whole class of documentation-drift problems is eliminated wholesale — projections and the body cannot disagree, because they are not two separate things.
|
|
@@ -38,7 +38,7 @@ Seven required manifest keys, illustrated with real values from bb-quiz v0.2:
|
|
|
38
38
|
|
|
39
39
|
Four optional keys. `commands` declares the commands this plugin drives; `usage` is the write-side rule list; `checks` is the inspection rules; `bridge` is the bridge declaration, which only global pieces may hold.
|
|
40
40
|
|
|
41
|
-
A fifth optional key `inject_tier` (full|member, default full) carries the **tier law** (issue #12 layer discipline): member exits the AGENTS injection region — exposure rides on the family root's roster line, the skill catalog, and on-demand reads of the manifest, and validate requires a member to reach a full-tier domain root through depends. The projected region carries a byte budget (
|
|
41
|
+
A fifth optional key `inject_tier` (full|member, default full) carries the **tier law** (issue #12 layer discipline): member exits the AGENTS injection region — exposure rides on the family root's roster line, the skill catalog, and on-demand reads of the manifest, and validate requires a member to reach a full-tier domain root through depends. The projected region carries a byte budget (16 KiB), keeping the A layer pointer-dense: pointers and red lines, never procedures or formats (contract in `protocol/experiments.md`). Each full-tier inject line also has a 256 B pointer-density guideline (issue #49) — over it, validate warns: keep the line to path + read/write trigger + the one easy-to-break invariant + a pointer to PLUGIN.md.
|
|
42
42
|
|
|
43
43
|
attachment deserves a closer look. bb-quiz declares three entries:
|
|
44
44
|
|
|
@@ -52,7 +52,7 @@ The first is ownership; the latter two are borrows: the territory belongs to ano
|
|
|
52
52
|
|
|
53
53
|
`depends` declares dependencies. validate checks two things: dependencies exist, and there are no cycles — cycles are detected via DFS.
|
|
54
54
|
|
|
55
|
-
A domain piece is any plugin whose depends chain reaches `domain`. Those connecting to domain directly are domain bases — the
|
|
55
|
+
A domain piece is any plugin whose depends chain reaches `domain`. Those connecting to domain directly are domain bases — the six pieces vault, lark, project, email, bb, bili; pieces inside a domain belong to it transitively, without connecting directly. bb-quiz does not connect to domain directly: it arrives via `bb-quiz → bb-track → bb-map → bb → domain`, and is thus a domain piece.
|
|
56
56
|
|
|
57
57
|
Injection order = dependency topology plus alphabetical order within a batch: dependees are injected first; same-batch pieces sort by name. Look at the bb family's depends and the real order in the injection region:
|
|
58
58
|
|
|
@@ -69,8 +69,8 @@ This guarantees one thing: when a consumer-side plugin is injected, the disclosu
|
|
|
69
69
|
|
|
70
70
|
Suppose you want to add one discipline to bb-quiz's write-side rules — here is what happens:
|
|
71
71
|
|
|
72
|
-
1. Edit the `usage:` list in `.
|
|
73
|
-
2. Run `python .
|
|
72
|
+
1. Edit the `usage:` list in `.owfa/plugins/bb-quiz/PLUGIN.yaml` and add a line. While at it, bump `version` and refresh `updated`; add a line to PLUGIN.md's Changelog
|
|
73
|
+
2. Run `python .owfa/scripts/owfa_kernel.py all`. In sequence: validate goes first — failure blocks, fix and rerun; if the inject line changed too, the AGENTS injection region is rebuilt; the cmd-inject blocks of the two command SKILL masters bb-quiz and bb-track are rebuilt — the usage appears in every command whose consumes includes bb-quiz; the registry plugin section is rebuilt; skill copies are synced
|
|
74
74
|
3. Self-review the diff. Changes should land only in the manifest, the two command SKILL masters, and the `.agents/skills/` copies; if inject or fields changed, AGENTS and registry change as well. Any change beyond these is an anomaly
|
|
75
75
|
4. Commit in the format `plugin: bb-quiz …`; one commit does one thing
|
|
76
76
|
|
|
@@ -105,7 +105,7 @@ Division of labor: the bridge holds validation and declaration — who may attac
|
|
|
105
105
|
|
|
106
106
|
## 6. The Derived Layer
|
|
107
107
|
|
|
108
|
-
The kernel governs the
|
|
108
|
+
The kernel governs the mechanisms and projections — the plugin graph, manifest compliance, and everything derived from them (since the v0.4 split, plugin *content* travels with packages; the kernel's authority over it is mechanical, not editorial); pipeline governs the data area — wiki derived pages. The commands are `python .owfa/scripts/pipeline.py index / tags / hot / log / verify`:
|
|
109
109
|
|
|
110
110
|
- **index / tags**: directory indexes and the tag reverse index. Pure-function rebuilds that only aggregate, never inventing structure; when an index list overflows the window, split the subdirectory into its own index — the cure is more subdirectories, not editing the index
|
|
111
111
|
- **hot**: the recent-change hot cache. At most 25 entries, within 5 days, each entry under 200 characters; agents read it first on entering the vault
|
|
@@ -116,9 +116,9 @@ Derived pages and projections are two applications of one philosophy: projection
|
|
|
116
116
|
|
|
117
117
|
## 7. (Un)install Lifecycle
|
|
118
118
|
|
|
119
|
-
The semantic flow of (un)installing goes through the plugin command, where the agent does the semantic part; the mechanical steps are this CLI. Since the split (2026-10-12) **packages are the install unit and this lifecycle is kernel-driven** — the authoritative accounts live in [packages.md](packages.md) (package model, the migrations algebra, the uninstall contract) and in `.
|
|
119
|
+
The semantic flow of (un)installing goes through the plugin command, where the agent does the semantic part; the mechanical steps are this CLI. Since the split (2026-10-12) **packages are the install unit and this lifecycle is kernel-driven** — the authoritative accounts live in [packages.md](packages.md) (package model, the migrations algebra, the uninstall contract) and in `.owfa/command/plugin/SKILL.md` (the wizard protocol). What follows is the historical per-plugin flow, retained for the record; the install steps still describe authoring a new plugin inside the framework repo.
|
|
120
120
|
|
|
121
|
-
Install, five steps: prepare the three pieces under `.
|
|
121
|
+
Install, five steps: prepare the three pieces under `.owfa/plugins/<id>/`; `validate` — errors block; `all` — projections arrive; smoke test — `audit <id>`, plus a walk-through of the key flows per PLUGIN.md; log a plugin line.
|
|
122
122
|
|
|
123
123
|
Upgrade, three steps: edit the plugin, bump `version`, add a Changelog line; `all`; log line. Package-level upgrades (`kernel upgrade`) additionally stage semantic migrations — see packages.md.
|
|
124
124
|
|
|
@@ -165,7 +165,7 @@ A two-way split inside the domain. Process products live in the domain workspace
|
|
|
165
165
|
|
|
166
166
|
### Connectors
|
|
167
167
|
|
|
168
|
-
Connectors live in `connectors/` — the domain's deployment-side CLI de-facto interface plus usage disclosure: `connectors/<name>/SKILL.md` lands as the `.agents/skills/` copy via kernel `deploy`. The difference from commands: commands are pure wiki operations, masters in `.
|
|
168
|
+
Connectors live in `connectors/` — the domain's deployment-side CLI de-facto interface plus usage disclosure: `connectors/<name>/SKILL.md` lands as the `.agents/skills/` copy via kernel `deploy`. The difference from commands: commands are pure wiki operations, masters in `.owfa/command/`; connectors are data-fetching channels to external systems — credentials stay on the local machine, never committed, never persisted to disk. Domain plugins declare territory and discipline; connectors provide the de-facto interface. Discipline and tooling are separate.
|
|
169
169
|
|
|
170
170
|
## 9. Scenario Quick Reference
|
|
171
171
|
|
|
@@ -11,7 +11,7 @@ Use the expansion exactly as written. Do not expand it as *One Wiki For All* or
|
|
|
11
11
|
|
|
12
12
|
- 中文:**一个工作区,装下你所有的 agent。**
|
|
13
13
|
- 一句话:OWFA gives every agent you use one workspace to re-enter — your assets, your wiki, your instructions — instead of re-introducing yourself every session.
|
|
14
|
-
- Agent-facing: "This is an OWFA workspace: `vault/` holds real assets, `wiki/` holds the md world, `.
|
|
14
|
+
- Agent-facing: "This is an OWFA workspace: `vault/` holds real assets, `wiki/` holds the md world, `.owfa/` + `.agents/skills/` are the framework body. Read AGENTS.md, then work from the indexes."
|
|
15
15
|
|
|
16
16
|
## What each word commits to
|
|
17
17
|
|
|
@@ -28,11 +28,11 @@ The name answers the project's actual starting pain: an agent that must be re-in
|
|
|
28
28
|
| Layer | Name | Lives in | Job |
|
|
29
29
|
|---|---|---|---|
|
|
30
30
|
| Product | **OWFA** | README, npm page, docs | the brand |
|
|
31
|
-
| Framework | **OWFA Core** (proposed) | `.
|
|
31
|
+
| Framework | **OWFA Core** (proposed) | `.owfa/` + `.agents/skills/` | the body that is installed into a workspace |
|
|
32
32
|
| Installer | **OWFA CLI** | `bin/owfa.js` (npm package) | fetch the tree, `init`, `upgrade`, `doctor`, `add` |
|
|
33
|
-
| Engine | **kernel** | `.
|
|
34
|
-
| Plugin tier | **core** |
|
|
35
|
-
| Extension | **package** | `.
|
|
33
|
+
| Engine | **kernel** | `.owfa/scripts/owfa_kernel.py` | validate / inject / registry / deploy / install mechanics |
|
|
34
|
+
| Plugin tier | **core** | the owfa-personal suite package (embedded at `payloads/personal/` in the channel) | the 21 former framework plugins |
|
|
35
|
+
| Extension | **package** | `.owfa/plugins/domains/<pkg>/` | domain families (cuhksz, lark, email, bili, project…) |
|
|
36
36
|
| Unit | **instance** | the user's directory | a deployed workspace |
|
|
37
37
|
|
|
38
38
|
The call chain is the reason the names must stay distinct:
|
|
@@ -107,7 +107,7 @@ The order is not bureaucratic: npm support evaluates a project by its public hom
|
|
|
107
107
|
- `package.json` — `"name": "owfa"` (target) with `"bin": { "owfa": "bin/owfa.js" }`; the fallback is the same file with `"name": "owfadev"` and bins `owfa` + `owfadev`
|
|
108
108
|
- `README.md` — first line, the *Name* section, and the install note (never announce a command the registry does not serve)
|
|
109
109
|
- `templates/AGENTS.template.md` — the identity paragraph a new instance starts from
|
|
110
|
-
- `.
|
|
111
|
-
- `scripts/verify-release.js` — the release gate (name/bin agreement, version rides `.
|
|
110
|
+
- `.owfa/docs/distribution.md` — the channel's version invariant, fallback and release runbook
|
|
111
|
+
- `scripts/verify-release.js` — the release gate (name/bin agreement, version rides `.owfa/VERSION`, tag matches)
|
|
112
112
|
|
|
113
113
|
Update 2026-10-26: the repository itself is renamed to `owfa` (`owfadev/owfa`), and the public copy uses OWFA / OWFA Core; `vault-wiki` survives only in history and old links. Nothing in the kernel, plugin IDs, or registry depends on the brand.
|