owfadev 0.3.0 → 0.3.1

package/.meta/VERSION

@@ -1 +1 @@
-0.3
+0.3.1

package/.meta/docs/packages.md

@@ -82,7 +82,7 @@ uninstall:              # declaration, never executable hooks
 | `validate --scope <pkg>` | single-package tolerant mode (D3): deps absent outside the package degrade to warnings — the CI shape for package repos post-split, run with a framework checkout alongside |
 | `pkg` | package inventory: members, connectors, implicit core remainder |
 | `residual <pkg>` | D6 residual scan: greps handwritten AGENTS region + profile/language/calendar/todo/cron anchors for member references (the kernel-managed injection region is skipped — it is cleaned mechanically) |
-| `install <pkg>[@tag]` | resolve the [registry](https://github.com/owfadev/registry) index (members reconciled against PKG.yaml) → trust gate → clone → copy masters/connectors/commands → converge. `install <owner/repo> --yes` installs an unindexed repository (trust: unknown); `--path <dir>` installs a local one (channel C) |
+| `install <pkg>[@tag]` | resolve the [registry](https://github.com/owfadev/registry) index (members reconciled against PKG.yaml) → trust gate → clone → prospective manifest/budget preflight → copy masters/connectors/commands → converge. `install <owner/repo> --yes` installs an unindexed repository (trust: unknown); `--path <dir>` installs a local one (channel C) |
 | `uninstall <pkg> --yes` | D6 four-clear (masters/commands/connectors/skills) + convergence + residual scan + retains/credentials reminders — data never touched |
 | `list-remote` | index table with installed marks |
 | `plan <pkg>` | dependency disclosure before a package lands |
@@ -91,6 +91,16 @@ uninstall:              # declaration, never executable hooks
 
 *Why scope mode exists before the split:* after the split the framework repo and each package repo no longer contain the full graph — validate would be blind exactly where it matters most. Absence-tolerance turns "plugin missing" from an error into a listed warning, keeping every repo self-checkable.
 
+### Install failure handling
+
+Before copying into the instance, `install` stages the prospective masters in a temporary directory using the actual install filter (including `--without` and its dependent-member pruning). It combines them with installed manifests and checks manifest/dependency rules and the existing UTF-8 injection budget. A rejection returns exit 1 before changing package masters, commands, connectors, migration state, journal or projections. Registry lookup may still refresh its local index cache; downloaded temporary sources are discarded on preflight rejection, while a caller's `--path` source is retained.
+
+After copying, full binding/bridge/package validation and projection/deployment still run. Failure returns exit 1 with an incomplete-state warning; later projection steps stop when a preceding step returns failure. This is **not transactional rollback**: errors discovered after preflight, filesystem failures, or concurrent changes can leave files behind. Inspect the reported errors and run `kernel validate` before recovery; a successful diagnostic does not itself repair missing projection markers. Pending semantic init migrations retain the existing behavior: mechanical install can return 0 while explicitly reporting pending work, and `validate` stays red until the migration is completed and cleared.
+
+The 16 KiB limit and its calculation are unchanged (#48/#49). This does not make `upgrade` transactional: its existing uninstall/reinstall sequence can remove the old package before the install preflight runs. Uninstall's own return-code contract is unchanged.
+
+Offline regression suite: `python -m unittest discover -s .meta/tests -p test_install_preflight.py -v` (synthetic packages; no network or credentials).
+
 ## Uninstall contract (D6)
 
 No executable uninstall hooks — that would be a **third execution surface** (after inject text and connectors), running at a privileged moment; the security model declines. Instead the package *declares* its deletion semantics (`uninstall:` above) and the flow is: kernel mechanical four-clear (directory / injection / registry / projections) → residual scan output → agent semantic finish per the declaration (credential reminders, process stops, bridge registration lines) behind a confirmation gate. **Data and credentials are never auto-deleted** — the freedom to delete belongs to the human; retained data zones lapse into the deprecated posture.

package/.meta/scripts/wiki_plugin_kernel.py

@@ -220,10 +220,10 @@ def _plugin_dirs(base):
                     yield sub2, s2dir
 
 
-def load_plugins():
+def load_plugins(base=None):
     """Read all plugin manifests (flat / core/ / domains/<pkg>/ layouts); returns (plugins, errors)."""
     plugins, errors = {}, []
-    for name, pdir in _plugin_dirs(PLUGINS_DIR):
+    for name, pdir in _plugin_dirs(PLUGINS_DIR if base is None else base):
         yml = os.path.join(pdir, "PLUGIN.yaml")
         md = os.path.join(pdir, "PLUGIN.md")
         if not os.path.exists(md):
@@ -990,11 +990,48 @@ def converge(label):
         print(f"[{label}] validation failed ({len(errors)} errors) — fix before continuing")
         return False
     print(f"[{label}] validate: {len(plugins)} plugins green")
-    do_inject(plugins)
-    do_check_inject(plugins)
-    do_cmd_inject(plugins)
-    do_registry(plugins)
-    do_deploy()
+    for project in (do_inject, do_check_inject, do_cmd_inject, do_registry):
+        if not project(plugins):
+            print(f"[{label}] projection failed ({project.__name__}) — state may be partial")
+            return False
+    if not do_deploy():
+        print(f"[{label}] deployment failed — state may be partial")
+        return False
+    return True
+
+
+def _preflight_install(src, ignore):
+    """Validate the prospective manifest graph before writing installed package state.
+
+    Stage only masters using the same copy filter as install, including --without.
+    Binding/bridge/package checks still run after commands and connectors land.
+    This is a preflight, not a transaction or a replacement for convergence.
+    """
+    import tempfile
+
+    plugins, errors = load_plugins()
+    warns = []
+    try:
+        with tempfile.TemporaryDirectory(prefix="vw-preflight-") as stage:
+            shutil.copytree(src, os.path.join(stage, "package"), ignore=ignore)
+            incoming, load_errors = load_plugins(stage)
+            errors.extend(load_errors)
+            for name, manifest in incoming.items():
+                if name in plugins:
+                    errors.append(f"[error] {name}/: duplicate plugin id (already installed)")
+                else:
+                    plugins[name] = manifest
+            if not errors:
+                validate(plugins, errors, warnings=warns)
+    except (OSError, ValueError) as e:
+        errors.append(f"[error] install preflight: {e}")
+    for w in warns:
+        print(f"[warning] {w}")
+    for e in errors:
+        print(e)
+    if errors:
+        print("[install] preflight failed — package files and projections were not changed")
+        return False
     return True
 
 
@@ -1110,9 +1147,14 @@ def do_install(spec, args, prev_version=None):
     if os.path.exists(dst):
         print(f"[error] {pid} already installed — uninstall first (kernel uninstall {pid} --yes)")
         return 1
+    ignore = shutil.ignore_patterns(".git", ".meta", "connectors", "command", "README.md",
+                                   "__pycache__", "migrations", *sorted(pruned))
+    if not _preflight_install(src, ignore):
+        if not path:
+            shutil.rmtree(src, ignore_errors=True)
+        return 1
     os.makedirs(os.path.dirname(dst), exist_ok=True)
-    shutil.copytree(src, dst, ignore=shutil.ignore_patterns(".git", ".meta", "connectors", "command", "README.md", "__pycache__", "migrations",
-                                                            *sorted(pruned)))
+    shutil.copytree(src, dst, ignore=ignore)
     copied_conn, copied_cmd = [], []
     csrc = os.path.join(src, "connectors")
     if os.path.isdir(csrc):
@@ -1163,9 +1205,12 @@ def do_install(spec, args, prev_version=None):
           + (f"; connectors: {', '.join(copied_conn)}" if copied_conn else "")
           + (f"; commands: {', '.join(copied_cmd)}" if copied_cmd else ""))
     _journal("install", f"{pid} v{pkgm.get('version')}" + (f" subset(-{','.join(sorted(pruned))})" if pruned else "") + (f" staged={','.join(staged)}" if staged else ""))
-    converge("install")
+    converged = converge("install")
     if staged:
         print(f"[pending] semantic migration staged for {pid}: {', '.join(staged)} — kernel migrate {pid}; validate stays red until cleared")
+    if not converged:
+        print("[error] install incomplete — files may remain; run kernel validate before retrying")
+        return 1
     return 0
 
 

package/.meta/tests/test_install_preflight.py

@@ -0,0 +1,177 @@
+"""Offline install regressions; synthetic packages and disposable instances only.
+
+Run: python -m unittest discover -s .meta/tests -p test_install_preflight.py -v
+"""
+import hashlib
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+
+
+FRAMEWORK = Path(__file__).resolve().parents[2]
+
+
+class InstallPreflightTests(unittest.TestCase):
+    def setUp(self):
+        self.temp = tempfile.TemporaryDirectory(prefix="kernel-install-test-")
+        self.addCleanup(self.temp.cleanup)
+        self.root = Path(self.temp.name) / "instance"
+        self.root.mkdir()
+        for directory in (".meta", ".agents"):
+            shutil.copytree(FRAMEWORK / directory, self.root / directory,
+                            ignore=shutil.ignore_patterns("__pycache__", "tests", "smoke-tmp"))
+        (self.root / "AGENTS.md").write_text(
+            "# Synthetic instance\n<!-- wiki-inject:start -->\n<!-- wiki-inject:end -->\n",
+            encoding="utf-8")
+        self.source = Path(self.temp.name) / "source"
+        self.source.mkdir()
+        self.env = dict(os.environ, PYTHONDONTWRITEBYTECODE="1", PYTHONIOENCODING="utf-8")
+        self.env.pop("PYTHONPATH", None)
+        result = self.run_kernel("all")
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+
+    def run_kernel(self, *args):
+        return subprocess.run(
+            [sys.executable, str(self.root / ".meta/scripts/wiki_plugin_kernel.py"), *args],
+            cwd=self.root, env=self.env, capture_output=True, text=True, encoding="utf-8")
+
+    def run_code(self, code):
+        prefix = "import sys; sys.path.insert(0, '.meta/scripts'); import wiki_plugin_kernel as k; "
+        return subprocess.run([sys.executable, "-c", prefix + code], cwd=self.root,
+                              env=self.env, capture_output=True, text=True, encoding="utf-8")
+
+    def manifest(self, name, inject, depends="[domain, wiki, trust, log]", tier=None):
+        directory = self.source / name
+        directory.mkdir(exist_ok=True)
+        dependencies = "".join(f"  - {item.strip()}\n" for item in depends.strip("[]").split(","))
+        text = (f"id: {name}\nschema_version: 1\nversion: 0.1\nupdated: 2026-10-24\n"
+                f"depends:\n{dependencies}attachment: []\nfields:\n"
+                f"inject: {json.dumps(inject, ensure_ascii=False)}\n")
+        if tier:
+            text += f"inject_tier: {tier}\n"
+        (directory / "PLUGIN.yaml").write_text(text, encoding="utf-8")
+        (directory / "PLUGIN.md").write_text("# Synthetic test plugin\n", encoding="utf-8")
+
+    def package(self, inject="Synthetic test", members="[probe]"):
+        (self.source / "PKG.yaml").write_text(
+            "schema_version: 1\nid: probe\nversion: 0.1\ncompat: '>= 0.3'\n"
+            f"members: {members}\ndepends: [framework]\n", encoding="utf-8")
+        self.manifest("probe", inject)
+
+    def install(self, *extra):
+        return self.run_kernel("install", "probe", "--path", str(self.source), *extra)
+
+    def snapshot(self):
+        return {str(path.relative_to(self.root)): hashlib.sha256(path.read_bytes()).hexdigest()
+                for path in self.root.rglob("*") if path.is_file()}
+
+    def budget_text(self, extra=0):
+        result = self.run_code(
+            "p,e=k.load_plugins(); assert not e; b,_=k.build_inject_blocks(p); "
+            "print(k.INJECT_BUDGET-sum(len(x.encode('utf-8')) for x in b))")
+        self.assertEqual(result.returncode, 0, result.stderr)
+        overhead = len("<!-- plugin:probe v0.1 -->\n- \n<!-- /plugin:probe -->".encode("utf-8"))
+        room = int(result.stdout.strip()) - overhead + extra
+        return "界" * (room // 3) + "x" * (room % 3)
+
+    def test_over_budget_leaves_all_instance_state_unchanged(self):
+        self.package(self.budget_text(extra=1))
+        # These would all land or change if rejection happened after copy/staging.
+        for relative in ("connectors/test-connector/file.txt", "command/test-command/file.txt",
+                         "migrations/init.md"):
+            path = self.source / relative
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text("Synthetic payload", encoding="utf-8")
+        ledger = self.root / ".meta/migrations/pending.json"
+        ledger.parent.mkdir(exist_ok=True)
+        ledger.write_text(json.dumps({"probe": {"kind": "teardown", "items": []}}), encoding="utf-8")
+        before = self.snapshot()
+        result = self.install()
+        self.assertEqual(result.returncode, 1, result.stdout + result.stderr)
+        self.assertIn("over the 16384 B budget", result.stdout)
+        self.assertIn("preflight failed", result.stdout)
+        self.assertEqual(self.snapshot(), before)
+        self.assertTrue((self.source / "probe/PLUGIN.yaml").exists())
+
+    def test_exact_utf8_budget_installs_and_converges(self):
+        self.package(self.budget_text())
+        result = self.install()
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertIn("plugin:probe", (self.root / "AGENTS.md").read_text(encoding="utf-8"))
+        result = self.run_kernel("all")
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+
+    def test_without_cascade_uses_only_the_installed_subset(self):
+        self.package(members="[probe, optional, child]")
+        self.manifest("optional", "界" * 6000, depends="[probe]")
+        self.manifest("child", "界" * 6000, depends="[optional]")
+        result = self.install("--without", "optional")
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        installed = self.root / ".meta/plugins/domains/probe"
+        self.assertFalse((installed / "optional").exists())
+        self.assertFalse((installed / "child").exists())
+        self.assertEqual(self.run_kernel("validate").returncode, 0)
+
+    def test_member_tier_does_not_consume_injection_budget(self):
+        self.package(members="[probe, member]")
+        self.manifest("member", "界" * 6000, depends="[probe]", tier="member")
+        result = self.install()
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertNotIn("plugin:member", (self.root / "AGENTS.md").read_text(encoding="utf-8"))
+
+    def test_duplicate_installed_id_is_rejected_before_copy(self):
+        self.package(members="[probe, language]")
+        self.manifest("language", "Duplicate", depends="[probe]")
+        before = self.snapshot()
+        result = self.install()
+        self.assertEqual(result.returncode, 1, result.stdout + result.stderr)
+        self.assertIn("duplicate plugin id", result.stdout)
+        self.assertEqual(self.snapshot(), before)
+
+    def test_post_copy_binding_failure_returns_nonzero_and_warns(self):
+        self.package()
+        path = self.source / "probe/PLUGIN.yaml"
+        path.write_text(path.read_text(encoding="utf-8") + "commands:\n  - missing-command\n", encoding="utf-8")
+        result = self.install()
+        self.assertEqual(result.returncode, 1, result.stdout + result.stderr)
+        self.assertIn("install incomplete", result.stdout)
+        self.assertIn("missing command", result.stdout)
+        self.assertTrue((self.root / ".meta/plugins/domains/probe/PKG.yaml").exists())
+
+    def test_projection_failure_returns_nonzero(self):
+        self.package()
+        (self.root / "AGENTS.md").write_text("# Missing injection markers\n", encoding="utf-8")
+        result = self.install()
+        self.assertEqual(result.returncode, 1, result.stdout + result.stderr)
+        self.assertIn("projection failed (do_inject)", result.stdout)
+        self.assertIn("install incomplete", result.stdout)
+
+    def test_semantic_init_stays_pending_without_becoming_mechanical_failure(self):
+        self.package()
+        migration = self.source / "migrations/init.md"
+        migration.parent.mkdir()
+        migration.write_text("# Synthetic manual initialization\n", encoding="utf-8")
+        result = self.install()
+        self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+        self.assertIn("semantic migration staged", result.stdout)
+        result = self.run_kernel("validate")
+        self.assertEqual(result.returncode, 1, result.stdout + result.stderr)
+        self.assertIn("pending semantic migration", result.stdout)
+
+    def test_deploy_failure_is_propagated(self):
+        self.package()
+        result = self.run_code(
+            "k.do_deploy=lambda: False; "
+            f"sys.exit(k.do_install('probe', ['--path', {str(self.source)!r}]))")
+        self.assertEqual(result.returncode, 1, result.stdout + result.stderr)
+        self.assertIn("deployment failed", result.stdout)
+        self.assertIn("install incomplete", result.stdout)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/README.md

@@ -1,5 +1,7 @@
 # OWFA — One Workspace For All (agents)
 
+> English | [简体中文](README.zh-CN.md)
+
 > **OWFA** is the project; **OWFA Core** is the framework body (formerly `vault-wiki`); **OWFA CLI** is the installer. The public home is moving to **`owfadev/owfa`** — `github.com/owfa` is an unrelated organization. The npm name `owfa` is under application; see [The name](#the-name).
 
 **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)).
@@ -96,10 +98,6 @@ While the name is under application, substitute `npx owfadev` for every `npx owf
 - [.meta/docs/quickstart.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/quickstart.md) — five-minute path: one command or the manual five steps, then first run
 - `.meta/protocol/` — field registry, action discipline, disclosure paradigm
 
-## History
-
-2026-08-26 founded as a copy of the personal library's structure; 08-28 repositioned as this project; 09-08 the plugin-plus-command prototype landed directly, validated by real operation then frozen. 09-12 refactor: the conceptual pair wiki & vault established; the original vault plugin renamed mapping; layering abolished; identifiers anglicized. 09-19 the lark family and the calendar time territory established. 09-22 domainization: the domain conceptual root established; vault, lark, project compliant as instances. 09-29 profile became a standalone command; the email domain established; the connector slot established. 10-01 to 10-02 the bb domain suite landed and was validated across four courses; collaboration red lines set; converted to a team project. 10-04 the bb cognition-consumer refactor — bb-teach, bb-quiz, bb-track commands; mechanics docs opened; docs moved to `.meta/docs/`. 10-05 the cuhksz school domain established, bb demoted into the family, sis and registry sub-domains followed. 10-06 the bilibili domain established (query-and-answer + emergence archives, low-risk write whitelist), connector bili-cli first version; the cron time-automation territory established (declaration-as-source, one page per task), lark-calendar/bili/email migrated onto the bridge; bili 0.3 video-archival batch. Docs switched to English. Design-lineage discussions live in the personal library — see AGENTS.md pointers. 10-12 repo transferred to the GitHub org AIE3905-Wuwa; standardization-and-split improvement phase opened: package binding (directory == package, PKG.yaml reconciliation, scope validate, residual scan, VERSION 0.2 anchor + tag v0.2); the convergence record lives in issue #20. 10-13 discovery/download/update shipped (registry INDEX, owner/repo trust gate, silent-reinstall upgrades, --without subsets, VERSION 0.3 + tag v0.3), then teardown (x->0) closed the migration algebra (dormant staging, tri-face warning, residual gate, sweep symmetry); five packages re-released at v0.2; a fresh-instance acceptance run walked the full lifecycle green and fed back the cold-start doc fixes; the sandbox left git tracking (local-only, owner re-ruling); quickstart gained the two postures (clone-as-instance for users, template + instance for developers).
-
 ## License
 
 MIT — see [LICENSE](https://github.com/owfadev/owfa/blob/master/LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,103 @@
+# OWFA — One Workspace For All (agents)
+
+> [English](README.md) | 简体中文
+
+> **OWFA** 是项目名；**OWFA Core** 是框架本体（原 `vault-wiki`）；**OWFA CLI** 是安装器。公开主页为 **`owfadev/owfa`**——`github.com/owfa` 是无关组织。npm 包名 `owfa` 正在申请中，详见[「关于命名」](#关于命名)。
+
+**OWFA**（One Workspace For All agents）是一个开源的 agent 工作区：开箱即用、可持续维护、端到端插件化。一个工作区——你拥有的那个目录，装着 `vault/`（真实资产）、`wiki/`（md 投影与原生笔记）和 `AGENTS.md`（章程）——是你所有 agent 反复进入的常驻上下文，而不是每次会话重新自我介绍。agent 按 SASU-L 披露次序零先验地读写；md 与纯文本文件是地基，Obsidian 等只是可替换的查看器。行为通过一份活的用户画像个性化，新能力以插件落地——每个插件都经 registry 的人工审核门发布，欢迎贡献：为你使用的信息源写一个域插件，向 registry 提一行 PR 即可上架（见[参与贡献](#参与贡献)）。
+
+> 状态：**alpha**——能力面是经六周真实日常使用打磨出的原型（生于 2026-09-08，经两轮实际运营与一次冷启动披露审计检验，bb 课程家族在四门课真实运行）；分发面 v0.3 是首个可安装形态——经一次全新实例验收，尚无外部用户。Beta 门槛：行为契约（#34）落地 · 两位成员真实装机 · 旧实例转换走通 · 验收脚本可重放绿。`.meta/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` 为兜底命名空间。
+
+## 关于命名
+
+**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` 为兜底包。完整的理据、分层与撞名对策：[`.meta/docs/naming.md`](https://github.com/owfadev/owfa/blob/master/.meta/docs/naming.md)。
+
+## 它做什么
+
+让 AI 编码 agent 替你经营一座「个人 wiki」：
+
+- 资产随手丢进 `vault/`，任何格式——md、txt、csv、pdf、图片。**map** 命令把每件资产登记为 `wiki/vault/` 下的 md 投影页，带 SHA-256、元数据与链接
+- 对话中的洞见与决策由 **save** 命令蒸馏为 `wiki/notes/` 下的原生笔记；会话骨架页进 `wiki/sessions/`
+- **query** 命令先读热缓存与索引，再以 wikilink 引用作答
+- 索引、标签、热缓存与运行日志由派生层自动维护；**check** 命令体检库健康；**plugin** 命令装卸结构插件
+- 外部信息源以域接入：lark 与 email 落为指针或归档页；calendar 管时间线；project 管项目容器；bb 经 bb-cli 拉课件、作业与成绩；bilibili 经 bili-cli 按需应答（搜索/详情/收藏/UP 追更；视频摘要与评审经显式请求归档；低风险写白名单须用户显式动词）。翻译发生在域外；域内一切互链
+- **profile** 命令维护一份关于用户的活认知档案：断言带证据，偏好会过期；任何个性化决策前先读它
+- **teach** 命令按认知档案讲解——熟点略讲或抽测，生点拆解；重要问答沉淀进 ai notes
+- **quiz** 命令按范围加可选样本出题；批改结果回流认知档案
+- **track** 命令读写每门课的 user.md 学习状态；teach 与 quiz 的使用挂载于此
+
+## 核心概念
+
+| 概念 | 定义 |
+|---|---|
+| wiki | md 世界，内外之分的内侧：各域投影 + 原生笔记 + 派生层 |
+| domain | wiki 之外信息源的适配器契约。vault 是默认域；lark、project、email、bb、bili 也是域 |
+| vault | 默认域——真实资产仓库；命令侧只增不删，删除与修改的自由属于人 |
+| SASU-L | 披露范式：agent 只经系统提示、AGENTS.md、Skills、用户的话与循环来学习 |
+
+## 目录结构
+
+| 目录 | 内容 |
+|------|------|
+| `.meta/` | 原型核心，两级插件布局：`plugins/core/`（20 个框架插件——domain 与 wiki 两个概念根、横切件，以及 vault/mapping/structure 的明示章程例外）+ `plugins/domains/<pkg>/`（一包一目录：`PKG.yaml` + 家族母本——cuhksz 8、lark 4、email、bili、project）。目录边界 == 层级边界 == 包边界；`PKG.yaml` 声明名册，内核对账家族闭包；`.meta/VERSION` 锚定框架版本（包 `compat` 下限对它校验）。注入次序 = 依赖拓扑 + 字典序；AGENTS 注入区分层——成员级域件退出注入区（家族名册 + 技能 + 按需 manifest 读取承担曝光），受内核字节预算约束；全局插件可声明桥，必依桥由内核校验。另有 13 个命令母本、协议工件（registry、actions、experiments）与机械脚本 wiki_plugin_kernel、pipeline、wikilib——纯标准库零依赖 |
+| `connectors/` | 连接器母本：部署侧 CLI 事实接口 + 技能使用披露。`connectors/*/SKILL.md` 经内核 deploy 落入 `.agents/skills/`；现有 bb-cli、sis-cli、mail-cli、bili-cli。连接器随各自包的 `PKG.yaml` 走 |
+| 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` 承载各包，带完整文件谱系拆分 |
+| `.agents/skills/` | 命令与连接器技能的部署副本（拆分后框架命令在此；连接器技能随包到达） |
+| `bin/` + `templates/` + `package.json` | npm 通道：`owfa` CLI、AGENTS 种子、包清单。`test/` 与 `scripts/` 仅供开发，不随包发布 |
+| `test-repo/` | 本地测试沙盒——2026-10-13 起不入 git（owner 裁定；全新 clone 不含它）。需要 AGENTS.md 上下文的实验用临时部署；设置与规则见 [`.meta/docs/sandbox.md`](https://github.com/owfadev/owfa/blob/master/.meta/docs/sandbox.md)。框架仓自身不带 AGENTS.md——库姿态；开发规则在 [CONTRIBUTING.md](https://github.com/owfadev/owfa/blob/master/CONTRIBUTING.md) |
+| `.meta/docs/` | 人读文档：`intro.md` 导论、`mechanics.md` 机制、`usage.md` 使用指南、`deployment.md` 全指南 / `quickstart.md` 五分钟路径、`instance-git.md` 实例侧 git 最小契约、`research-*.md` 研究文件——文末直链。权威机制在内核参考 skill；文档不复写机制 |
+
+## 参与贡献
+
+欢迎贡献，插件是预定贡献面：新能力是新插件，不是 fork 框架。三条路径，由小到大——为你使用的 CLI 写一个连接器技能；写一个把外部信息源适配进 wiki 的域插件（三路径表与开发循环见 [`developer.md`](https://github.com/owfadev/owfa/blob/master/.meta/docs/developer.md)）；或改进 core。域包自托管于各自仓；上架 = 向 [registry](https://github.com/owfadev/registry) 提一行 PR，那是人工审核的信任门。Bug 与行为问题走 issues；框架本体收 PR。
+
+## 协作
+
+本仓是团队项目：三名成员有写权限，一切经 PR（1 个 approving review 可合，`enforce_admins` 开启）；owner 对仓库设置、权限与章程/内核变更有最终决定权。数据红线、提交流程与版本纪律 summarized 在 [CONTRIBUTING.md](https://github.com/owfadev/owfa/blob/master/CONTRIBUTING.md)——权威开发规则；变更轨迹是 git 历史 + PR + issues（本仓不留运行日志）。
+
+## 快速开始
+
+两条入口。**通道（推荐）：** `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/.meta/docs/quickstart.md) 的五步走，然后 `python .meta/scripts/wiki_plugin_kernel.py all`。含包与升级的全指南：[deployment.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/deployment.md)。
+
+前提：Python 3.9+，纯标准库，框架本身免安装（连接器自带依赖）；仅 npm 通道要 Node 16.7+；推荐 git（实例快照）；一个会读 AGENTS.md 与 skills 的 agent 环境，如 ZCode；Obsidian 可选，仅查看器。
+
+在仓库根开一个 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、wiki_plugin_kernel、bb-teach、bb-quiz、bb-track；母本在 `.meta/command/`。丢一个文件进 `vault/`，对 agent 说「map」——这就是第一次使用。
+
+## 部署
+
+OWFA 有三层：**OWFA CLI**（安装器，绝不拷入工作区）、**OWFA Core**（`.meta/` + `.agents/skills/`，被安装之物）与 **kernel**（Core 内的纯标准库 Python 脚本——没有单独的内核安装；Python 3.9+ 即可运行）。`.meta/plugins/domains/<pkg>/` 下的域包是可选的。
+
+```bash
+npx owfa init my-workspace        # 目标名；申请期间用 npx owfadev init
+cd my-workspace
+npx owfa doctor                   # 体检：python / 框架 / 标记 / kernel validate（兜底用 npx owfadev doctor）
+npx owfa list                     # registry 目录
+npx owfa add cuhksz               # 可选包
+npx owfa upgrade                  # 日后：替换框架树，保留实例状态
+```
+
+名字申请期间，把上面每条 `npx owfa` 换成 `npx owfadev` 即可（或全局安装任一包；两者都暴露 `owfa` 命令）。
+
+`init` 是加法的：既有内容不动，已有 `AGENTS.md` 保留、只追加注入区。`upgrade` 替换 `.meta/` 与 `.agents/skills/`（实例数据永不触碰），保留内核迁移台账、journal 与 registry 缓存。
+
+- 全部署指南（组件、通道、包、升级、故障）：[`.meta/docs/deployment.md`](https://github.com/owfadev/owfa/blob/master/.meta/docs/deployment.md)
+- 五分钟路径：[`.meta/docs/quickstart.md`](https://github.com/owfadev/owfa/blob/master/.meta/docs/quickstart.md)
+- 通道设计与发布手册：[`.meta/docs/distribution.md`](https://github.com/owfadev/owfa/blob/master/.meta/docs/distribution.md)
+
+## 文档索引
+
+- [.meta/docs/deployment.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/deployment.md) — 部署指南：组件、通道、首跑、包、升级、故障
+- [.meta/docs/naming.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/naming.md) — 命名：本义展开、每个词的承诺、两名两职、异议与撞名对策
+- [.meta/docs/distribution.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/distribution.md) — npm 通道：命令、工件、版本不变量、发布手册、安全姿态
+- [.meta/docs/packages.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/packages.md) — 包机制与设计理据：布局、PKG.yaml、不变量、版本、卸载契约、决策台账
+- [.meta/docs/developer.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/developer.md) — 开发者指南：插件落位三路径表、开发循环、注册与发现
+- [.meta/docs/agents-example.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/agents-example.md) / [.meta/docs/log-example.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/log-example.md) — AGENTS.md 与 log.md 的实例种子（框架仓自身两者都不带）
+- [.meta/docs/intro.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/intro.md) — 导论：为什么是这个框架，叙事与谱系
+- [.meta/docs/mechanics.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/mechanics.md) — 机制：每个机制再深一层，附 bb 家族走查；动框架前先读
+- [.meta/docs/usage.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/usage.md) — 使用指南：三种工作循环（库务、课程学习、协作开发）
+- [.meta/docs/quickstart.md](https://github.com/owfadev/owfa/blob/master/.meta/docs/quickstart.md) — 五分钟路径：一条命令或手动五步，然后首跑
+- `.meta/protocol/` — 字段注册表、行动纪律、披露范式
+
+## 许可
+
+MIT——见 [LICENSE](https://github.com/owfadev/owfa/blob/master/LICENSE)。

package/bin/owfa.js

@@ -62,8 +62,10 @@ function rel(root, p) {
   return path.relative(root, p) || ".";
 }
 
+const FLAG_VALUE = ["name", "packages", "without", "from", "path"];
+
 function parseArgs(argv) {
-  const args = { _: [], flags: new Set() };
+  const args = { _: [], flags: new Set(), used: new Set() };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--") {
@@ -72,7 +74,8 @@ function parseArgs(argv) {
     }
     if (a.startsWith("--")) {
       const [key, inline] = a.slice(2).split("=", 2);
-      const takesValue = ["name", "packages", "without", "from"].includes(key);
+      const takesValue = FLAG_VALUE.includes(key);
+      args.used.add(key);
       if (takesValue && inline === undefined) {
         args[key] = argv[++i];
       } else if (takesValue) {
@@ -80,6 +83,8 @@ function parseArgs(argv) {
       } else {
         args.flags.add(key);
       }
+    } else if (a.startsWith("-") && a !== "-") {
+      args.used.add(a.slice(1)); // short or mistyped flag — validated by the command
     } else {
       args._.push(a);
     }
@@ -344,7 +349,9 @@ function cmdInit(args) {
       .filter(Boolean)) {
       out("");
       out(`installing package ${pkg} from the registry`);
-      if (kernel(target, ["install", pkg, "--yes"]) !== 0) fail(`package ${pkg} failed to install (earlier packages stay installed)`);
+      const installArgs = ["install", pkg, "--yes"];
+      if (args.without) installArgs.push("--without", String(args.without));
+      if (kernel(target, installArgs) !== 0) fail(`package ${pkg} failed to install (earlier packages stay installed)`);
       installed++;
       if (reportPending(target)) fail(`framework and ${pkg} are installed, but the workspace is not converged until the semantic migration above is cleared`);
     }
@@ -506,6 +513,35 @@ notes:
 `);
 }
 
+const COMMAND_HELP = {
+  init: "usage: owfa init [dir] [--name NAME] [--packages a,b] [--without m,n] [--force]\n\n" +
+        "deploy a fresh workspace (additive: existing files and AGENTS.md are preserved).\n" +
+        "python 3.9+ required for the framework; node 16.7+ runs this installer only.\n" +
+        "--packages installs registry packages; --without prunes members from them (dependency-closed subsets only).\n" +
+        "--force re-copies the framework trees over an existing instance (instance data is never touched).",
+  upgrade: "usage: owfa upgrade [dir] [--check] [--backup] [--force]\n\n" +
+        "replace the framework trees with this channel's version and converge.\n" +
+        "--check (alias --dry-run) is read-only; --backup snapshots the current trees to .owfa/backup/.\n" +
+        "instance data, installed packages, pending migrations and standalone skills are preserved.",
+  doctor: "usage: owfa doctor [dir]\n\n" +
+        "health check: python, framework version, AGENTS.md injection markers, kernel validate.\n" +
+        "exits non-zero when any required condition fails.",
+  add: "usage: owfa add <pkg> [--yes] [--without m,n]  (run inside the instance)\n\n" +
+       "install a domain package from the registry, then converge.\n" +
+       "--without prunes members (dependency-closed subsets only); unindexed repos need --yes.",
+  list: "usage: owfa list\n\nregistry catalog: versions, compat floors, installed marks.",
+  pkg: "usage: owfa pkg\n\ninstalled package inventory: members, connectors, core remainder.",
+};
+
+const COMMAND_FLAGS = {
+  init: ["force", "help", "h", ...FLAG_VALUE],
+  upgrade: ["check", "dry-run", "backup", "force", "help", "h"],
+  doctor: ["help", "h"],
+  add: ["yes", "without", "path", "from", "help", "h", ...[]],
+  list: ["help", "h"],
+  pkg: ["help", "h"],
+};
+
 function main() {
   const argv = process.argv.slice(2);
   const cmd = argv[0];
@@ -517,7 +553,25 @@ function main() {
     out(`owfa ${PKG.version} (framework ${FRAMEWORK_VERSION})`);
     return 0;
   }
+  if (!(cmd in COMMAND_HELP)) {
+    out(`unknown command: ${cmd}`);
+    out("");
+    usage();
+    return 2;
+  }
+  if (argv.slice(1).includes("--help") || argv.slice(1).includes("-h")) {
+    out(`owfa ${PKG.version}`);
+    out(COMMAND_HELP[cmd]);
+    return 0;
+  }
   const args = parseArgs(argv.slice(1));
+  const known = new Set(COMMAND_FLAGS[cmd]);
+  const bad = [...args.used].filter((k) => !known.has(k));
+  if (bad.length) {
+    out(`unknown option${bad.length > 1 ? "s" : ""} for ${cmd}: ${bad.map((b) => "--" + b.replace(/^-+/, "")).join(", ")}`);
+    out(`see: owfa ${cmd} --help`);
+    return 2;
+  }
   switch (cmd) {
     case "init":
       return cmdInit(args);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "owfadev",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "OWFA — One Workspace For All (agents). Install, initialize and upgrade the owfa agent workspace framework.",
   "keywords": [
     "owfa",