Skip to content

Releases

v0.3.0 — Remote knowledge sources (git remotes, sync log, self-origin guard)

Choose a tag to compare

@likai-hust likai-hust released this 10 Sep 09:24

v0.3.0 — Remote knowledge sources

Team-distribution channel for OKF knowledge bases: the KB author pushes to git, every agent pulls automatically.

New

  • remotes config — point at git-hosted knowledge bases; they are shallow-cloned/updated into a shared local cache (~/.cache/opencode-okf/remotes/<hash(url+ref)>) before discovery and registered like local bundles (same L0/L1/L2 disclosure, same unload semantics). Multi-bundle repos register one bundle per root.
  • Failures never break the session — an unreachable origin degrades to the existing cache (stderr warning); a first-clone failure skips that remote.
  • Read-only by design — okf_write refuses remote bundles (the next sync's reset --hard would clobber local edits). The git repo is the source of truth.
  • Auth — auth: "env:VARNAME" reads tokens from the environment at sync time; tokens never live in okf.jsonc. ssh URLs use your ssh agent.
  • Sync log — every sync appends to ~/.cache/opencode-okf/sync.log ($OKF_SYNC_LOG): status, duration, pulled commit, registered bundles — success included. Lines never contain the remote URL (ssh URLs embed user@host); git errors are sanitized. debug: true mirrors lines to stderr.
  • Self-origin guard — a remote that IS the current project's own git origin is detected (protocol/git@/.git-insensitive comparison) and skipped: no redundant clone, no duplicate bundle.
  • okf sync CLI — force-updates all remotes (exit 1 on failure — CI gate); other okf commands clone on first use then run from cache (--sync / --no-sync to override).
  • Hardening — git subprocesses run with BatchMode=yes + ConnectTimeout=10 + GIT_TERMINAL_PROMPT=0: unreachable hosts and interactive prompts fail in seconds instead of hanging the session.

Quality

  • 168 tests (was 146), including real-git-repo E2E for the sync lifecycle; verified in a live opencode session (manifest injection + remote okf_read + sync.log).

Full Changelog: v0.2.0...v0.3.0


v0.3.0 — 远程知识源

OKF 知识库的团队分发通道:知识库作者 push 到 git,所有 agent 自动拉取。

  • remotes 配置:git 托管知识库在发现前被浅克隆/更新到共享本地缓存,并像本地 bundle 一样注册(同样的 L0/L1/L2 渐进披露与卸载语义);多 bundle 仓库按根目录各注册一个。
  • 故障绝不阻断会话:源不可达时降级用缓存;首次 clone 失败跳过该 remote。
  • 设计上只读:okf_write 拒绝 remote bundle(下次同步的 reset --hard 会冲掉本地改动),git 仓库是唯一事实源。
  • 鉴权:auth: "env:VARNAME" 同步时从环境变量读 token,绝不落进 okf.jsonc;ssh URL 走 ssh agent。
  • 同步日志:~/.cache/opencode-okf/sync.log 记录每次同步的状态/耗时/commit/注册 bundle(成功也留痕);日志行绝不包含 remote URL,git 报错已消毒;debug: true 镜像到 stderr。
  • 自仓库守卫:把当前项目自己的 origin 配成 remote 会被识别并跳过——不冗余克隆、不重复注册。
  • okf sync CLI:强制更新全部 remote(失败退出码 1,可作 CI 门禁);其余命令首次 clone 后走缓存(--sync/--no-sync 可覆盖)。
  • 加固:git 子进程带 BatchMode=yes + ConnectTimeout=10 + GIT_TERMINAL_PROMPT=0,不可达主机与交互提示秒级失败,不再挂起会话。

质量:168 个测试(原 146),含真实 git 仓库同步全流程 E2E;已在真实 opencode 会话中验证(manifest 注入 + 远程 okf_read + 同步日志)。

v0.2.0: okf CLI + large-context defaults + search dedup/aging

Choose a tag to compare

@likai-hust likai-hust released this 06 Sep 08:56

English

  • okf CLI — the package now ships a standalone binary with the same operations as the okf_* tools, for non-opencode agents (via their shell tool), humans, and CI (okf validate --all as a repo gate). Read intake control (--fields / --section / --max-chars), read-only by default (--write to enable writes), CI-friendly exit codes. Note: installing via opencode plugin does NOT put okf on PATH — it comes from npm install -g opencode-okf-context.
  • Shared operations layer (src/operations.ts) — plugin tool output is byte-identical to v0.1.8; the CLI renders shell-style hints and a read footer that never mentions okf_unload (no unload exists outside opencode).
  • Defaults tuned for large (256K-token) context windows — unload.afterTurns 2→4, keepRecent 1→2, nudge.threshold 6000→25000. Reloads are expensive; hold concepts a little longer and only nudge when retained knowledge is genuinely large.
  • okf_search outputs are now deduped and aged out like reads (same query keeps only the latest results) — cuts the retained-context slope from ~2.7K to ~1.3K chars per question in long sessions.
  • Benchmarks + opt-in live-LLM test suites (stress / hit-rate / compaction / read-efficiency; reload, compaction & efficiency E2E gates). 146 tests green.

中文

  • okf CLI——包内新增独立命令行工具,与 okf_* 工具同一套内核,面向非 opencode 的 Agent、人和 CI(okf validate --all 可作仓库门禁)。读取摄入控制(--fields / --section / --max-chars),默认只读(--write 显式开启写),退出码 CI 友好。注意:opencode plugin 安装不提供 CLI 命令,需另行 npm install -g opencode-okf-context。
  • 共享操作层(src/operations.ts)——插件侧工具输出与 v0.1.8 逐字节一致;CLI 侧输出为 shell 风格提示,read 页脚不会提及 okf_unload(opencode 之外没有卸载机制,不做虚假承诺)。
  • 默认参数按大上下文窗口(256K)调优——afterTurns 2→4、keepRecent 1→2、nudge.threshold 6000→25000:重读有成本,概念多留几轮;提醒只在滞留量真正大时触发。
  • 检索输出参与去重与老化——同词重复搜索只保留最新结果,旧检索结果像读取一样按轮次占位化,长会话滞留斜率从 ~2.7K 降至 ~1.3K 字符/问。
  • 附基准测试与 opt-in 真实 LLM 测试套件(压测 / 命中率 / 压缩抗性 / 读效率)。146 项测试全绿。

v0.1.8 — .opencode is scanned, dead scan.ignore removed

Choose a tag to compare

@likai-hust likai-hust released this 02 Sep 06:06

opencode-okf-context v0.1.8

1. .opencode is now scanned

Auto-scan previously skipped every hidden directory — including .opencode, where opencode users commonly keep skill/knowledge bundles (e.g. .opencode/skill/). Such bundles are now auto-discovered through the normal heuristic (a root index.md declaring okf_version, or index.md/log.md + a typed concept). The build/VCS blacklist (node_modules, .git, .hg, .svn, dist, build, out, .next, .turbo, .cache, coverage) still applies at any depth — including inside .opencode — and all other hidden directories remain skipped. Hidden files (.foo.md) are skipped as before.

2. Removed the never-implemented scan.ignore config key

scan.ignore was accepted in okf.jsonc and described in the schema, but the discovery code never read it — a dead knob. It has been removed from the config interface, defaults, JSON schema, and README examples.

Verified: 114 tests pass (new: H5 ×4 — explicit-marker and heuristic discovery under .opencode, other hidden dirs still skipped, node_modules inside .opencode still skipped). tsc --noEmit clean.


中文摘要

  1. .opencode 目录参与扫描——此前所有隐藏目录一律跳过,放在 .opencode/skill/ 下的知识 bundle 无法被自动发现。现在 .opencode 与普通目录一样被遍历(走正常 bundle 判定:okf_version 显式标记,或 index/log + 带 type 的 concept)。黑名单目录(node_modules、.git、dist 等 11 个)在任意深度仍然生效——包括 .opencode 内部;其余隐藏目录与隐藏文件依旧跳过。
  2. 移除从未实现的 scan.ignore 配置——该键在 okf.jsonc 里被接受、schema 里也有描述,但发现代码从未读取,纯死配置;已从接口、默认值、schema 和 README 示例中全部移除。

验证:114 测试全过(新增 4 个 H5 测试锁定行为),tsc --noEmit 无错误。

v0.1.7 — Version self-report, nested bundles, reload-loop fix, bundle overview

Choose a tag to compare

@likai-hust likai-hust released this 02 Sep 02:44

opencode-okf-context v0.1.7

Four fixes hardened by real-world debugging sessions.

1. Version self-reporting (diagnosability)

The plugin now stamps its version into the L0 manifest, the okf_list bundle overview, and the okf_validate report header: opencode-okf-context v0.1.7. opencode's @latest package cache can go stale — one user ran 0.1.4 while believing they were on 0.1.6, and diagnosing it took days. Now "which build is actually loaded" is answerable in one tool call.

2. Nested explicit bundles

A directory whose own index.md declares okf_version (spec §12) is now accepted as its own bundle even when nested inside another detected bundle root, and its subtree is excluded from the outer bundle's concepts. Previously an accidentally-detected project root (e.g. one whose index.md was created by an AI following a validate fix suggestion) swallowed the real nested knowledge bundle — doca/wiki could never surface as its own bundle.

3. Anti-reload-loop unload placeholders

Unload placeholders previously read as directives ("unloaded — reload with okf_read"), and models dutifully re-read after every unload — a read→unload→reload loop that burned minutes and tens of thousands of tokens when verifying long documents. New wording states the unload is routine context management, no action is needed, and okf_read is only for when the full text is genuinely required again.

4. okf_list without a bundle arg shows an overview

Calling okf_list with no arguments now lists all available bundles (name, concept count, root preview, browse hint) instead of erroring with Bundle not found: (none). Also: validate's bundle-level fix commands now warn against creating a root index.md on accidentally-detected directories (declare bundles in okf.jsonc instead).

Verified: 110 tests pass (new: version sync gate, nested-bundle H4, overview). E2E trigger hit-rate re-measured at 100% (5/5 positive + 1/1 negative) on deepseek-v4-flash after the manifest change.


中文摘要

四项实战打磨出的修复:

  1. 版本自报——manifest、okf_list 概览、okf_validate 报告头都会标注当前运行版本(如 v0.1.7)。opencode 的 @latest 包缓存可能不刷新(有用户实际跑着 0.1.4 却以为是 0.1.6,排查花了数天);现在一次工具调用即可确认实际加载的构建。
  2. 嵌套 bundle——自己的 index.md 声明了 okf_version 的目录,即使位于另一个被识别的 bundle 内部,也会作为独立 bundle 被发现,且其子树从外层 bundle 的 concepts 中排除。此前误判的项目根(例如 AI 按 validate 建议创建了根 index.md)会把真正的知识 bundle 整个吞掉。
  3. 卸载占位符防reload循环——旧文案 "unloaded — reload with okf_read" 会被模型当作指令,触发 读→卸载→重读 死循环(实测烧掉 3 分钟/50K token)。新文案明确"例行上下文管理、无需操作、仅在确实需要全文时再 okf_read"。
  4. okf_list 无参概览——不带 bundle 参数时列出全部可用 bundle 概览而非报错;validate 的 bundle 级修复命令也加了警告:误判目录不要创建根 index.md,改用 okf.jsonc 声明。

验证:110 测试全过;manifest 改动后 E2E 触发命中率复测 100%。

v0.1.6 — Fix authored index bypassing type filter in okf_list

Choose a tag to compare

@likai-hust likai-hust released this 04 Aug 13:43

opencode-okf-context v0.1.6

Bugfix release.

Fix: authored index.md lines bypassed the type filter in okf_list

The hand-written index.md content was passed through verbatim to okf_list output, bypassing the scheme-B type filter that only applied to the ## Concepts section. When an index.md linked to plain docs like AGENTS.md / README.md (no type frontmatter), those files appeared in the listing even on v0.1.5+.

Fix: readAuthoredIndex now filters out lines whose markdown links resolve to in-bundle concepts without a type. Non-link lines (headings, descriptive text) and links to typed concepts are preserved.


中文

Bug 修复:okf_list 会原样透传手写 index.md 的内容,绕过了 v0.1.5 加的 type 过滤。当 index.md 里有指向 AGENTS.md/README.md(无 type)的链接时,这些普通文档会出现在列表里。现已修复:手写 index 中指向无 type 文件的链接行会被过滤,标题和正文保留。

v0.1.5 — Bundle-root detection + validate fix-command clarity + list type filter

Choose a tag to compare

@likai-hust likai-hust released this 04 Aug 08:22

opencode-okf-context v0.1.5

Three robustness fixes found through real-world usage. No API changes.

1. Bundle-root false positive (discovery)

The bundle-root heuristic used recursive scan totals to decide if a directory is a bundle. A plain project root with a typed README.md + a sub-directory that happened to have an index.md was mis-detected as a bundle, swallowing unrelated files into a spurious bundle.

Fix: ScanHit now tracks root-level-only markers (rootHasIndex, rootHasLog, rootTypedCount — depth=0 files only). isBundleRoot reads only these, so sub-directory index.md files or deeply nested typed concepts can no longer trick the heuristic.

2. Validate fix commands were misleading (caused okf_version pollution)

The okf_validate report footer told the model to "Run the suggested okf_write calls to fix" for all issues — including bundle-level ones (okf_version) that okf_write cannot fix (index.md is a reserved file). This misled the model into adding okf_version to every individual concept file.

Fix: The footer now splits concept-level fixes (use okf_write) vs bundle-level fixes (direct edit of reserved files). bundleIssueFix emits real absolute paths and explicit "okf_write cannot touch reserved files" warnings.

3. okf_list showed plain .md docs without type

okf_list listed every .md file in a bundle, including plain docs (README, drafts, notes) without a type field. This cluttered the index and confused the model about which entries were real OKF concepts.

Fix: okf_list now filters to typed concepts only — consistent with the scheme-B guard already used in reference annotations and okf_refs. Plain docs are still discovered (so okf_validate can report type-missing) and still participate in the backlink index; only the list view hides them.

Tests

6 new regression tests (105 total, all pass):

  • M7 (×3): validate fix-command wording + footer clarity + single-concept mode never mentions okf_version
  • M8 (×1): list filter hides untyped docs but validate still sees them
  • H3 (×2): project root not mis-detected + sibling bundles discovered independently

中文摘要

三个鲁棒性修复,无 API 变更。

  1. Bundle-root 误判修复:扫描启发式之前用递归累积的 index/type 计数判断 bundle root,导致普通项目根(有带 type 的 README + 子目录恰好有 index.md)被误判为 bundle。现在只看根目录直接子文件的标志。
  2. Validate 修复命令误导修复:报告统一提示"用 okf_write 修复",但 bundle 级的 okf_version 问题不能用 okf_write 修(index.md 是保留文件)。这导致 AI 给每个 concept 文件加了 okf_version。现在 footer 区分两类修复路径,fix 命令用真实路径 + 明确声明保留文件限制。
  3. okf_list type 过滤:列表现在只显示有 type 的 concept,无 type 的普通 MD 文档不再列出(与 references 注释、okf_refs 的守卫一致)。无 type 文件仍被发现(validate 能报),只是列表隐藏。

v0.1.4 — Bidirectional reference graph (okf_refs + read annotations)

Choose a tag to compare

@likai-hust likai-hust released this 02 Aug 04:38

opencode-okf-context v0.1.4

This release adds bidirectional reference awareness — the model can now see who a concept links to AND who links back to it, without loading full bodies or making extra okf_list calls.

What's new

okf_read now annotates both directions. When you read a concept, the output shows:

  • Outgoing references — what this concept links to
  • Incoming references — which other concepts link back to it

Each neighbor is shown as metadata only (title + type + description + a ready-to-run okf_read reload command). The model can decide whether a cross-link is worth following without another tool call.

New okf_refs tool queries a concept's reference graph without loading any body — purpose-built for impact analysis ("who depends on this table?", "what breaks if I change X?"). It is not tracked by the unload mechanism, so it never occupies context.

How it works

buildBacklinkIndex does a real-time scan over the in-memory concept map (bodies are already loaded at discovery time), so there is zero extra I/O and no cache to invalidate. A freshly written concept is visible immediately. The index records the raw link facts; a scheme-B filter (concept must have a type) applies only at presentation, so plain .md docs don't clutter the graph.

E2E verified

The release was validated end-to-end against deepseek-v4-flash:

  • Trigger hit-rate: 100% (5/5 positive cases fired okf_*, 1/1 negative correctly did not) — the new manifest entry didn't regress triggers.
  • okf_refs in action: on an impact-analysis query ("如果修改 orders 表会影响哪些概念?"), the model spontaneously reached for okf_refs, read the incoming/outgoing neighbors, and produced a structured dependency assessment — without ever loading a concept body.

Docs

README, README.zh-CN, and AGENTS.md updated in sync (7 tools, okf_refs row, reference-annotation mention). Test count grew to 99 pass.


中文摘要

本次发布新增双向引用感知能力。

  • okf_read 读取 concept 时,现在同时附上出边(它引用了谁)和入边(谁引用了它)的邻居元数据,模型无需额外调用即可判断交叉链接值不值得展开。
  • 新工具 okf_refs 查询某个 concept 的引用图谱,不加载正文——专为影响分析设计("改这个表会影响谁?")。它不被卸载机制跟踪,绝不占用上下文。

核心机制 buildBacklinkIndex 对内存中的 concept 映射做实时扫描(正文在发现阶段已加载),零额外 I/O、无需缓存失效处理,写完立即可见。已通过 deepseek-v4-flash 端到端验证:触发命中率 100%,模型在影响分析场景下主动调用了 okf_refs。

v0.1.3 — Better knowledge-exploration triggers + nudge force fix

Choose a tag to compare

@likai-hust likai-hust released this 01 Aug 00:11

opencode-okf-context v0.1.3

This release makes the plugin fire reliably when an agent needs to explore knowledge (not just when the user explicitly asks), and fixes a config option that was silently a no-op.

Prompt improvements (cover proactive exploration)

The plugin now triggers in both situations:

  • Reactive — the user asks to understand/explain a concept, metric, or term.
  • Proactive — the agent itself needs domain context while writing code (e.g. it hits a metric name it's unsure about, or is about to hardcode a value the bundle defines). When unsure, it now reaches for okf_search before guessing.

Details:

  • Manifest (indexing.ts): added reactive + proactive trigger conditions, bilingual (zh/en) trigger phrases, and a quick decision guide so the agent picks okf_search first when it hears a term instead of always starting from okf_list.
  • okf_search description (tools.ts): rewritten to lead with the use case — "THE entry point when you hear a term" — instead of implementation detail, so the model selects it as the first action.

Bug fix (nudge force config was a no-op)

  • messages.ts: force: "strong" now emits a directive tone (frames unloading as a context-quality necessity); "soft" keeps the suggestion tone. Previously both ternary branches produced identical text, so the option did nothing.
  • Added a regression test guarding that the two tones differ.
  • Documented the force field in okf.schema.json.

Tests

68 tests pass (1 new regression test for nudge tone); tsc --noEmit clean.

Upgrade

npm install opencode-okf-context@0.1.3

No breaking changes; config and tool APIs are unchanged.


Full changes: commit 624d90e under tag v0.1.3.


中文说明

opencode-okf-context v0.1.3

本次发布让插件在 agent 主动探索知识时也能可靠触发(不只是用户明确提问时),并修了一个静默失效的配置项。

提示词优化(覆盖主动探索场景)

插件现在在两种情况下触发:

  • 被动触发 —— 用户要求理解/解释某个概念、指标或术语。
  • 主动触发 —— agent 自己写代码时需要领域上下文(例如遇到不确定的指标名、或准备硬编码一个 bundle 里可能已定义的值)。现在它会先 okf_search 查证,而不是靠参数知识硬猜。

细节:

  • Manifest(indexing.ts):新增被动+主动双触发条件、中英双语触发短语、决策流指引(听到术语时优先 okf_search,而不是总从 okf_list 兜圈)。
  • okf_search 描述(tools.ts):改为"场景优先"开头——"听到术语时的第一入口"——而非实现细节,让模型把它选为第一动作。

Bug 修复(nudge force 配置静默失效)

  • messages.ts:force: "strong" 现在产出指令性文案(把卸载框定为上下文质量必需);"soft" 保持建议性语气。之前两个三元分支文案完全相同,该配置项实际不生效。
  • 新增回归测试,守护两种语气互不相同。
  • 在 okf.schema.json 中补全了 force 字段说明。

测试

68 个测试通过(新增 1 个 nudge 语气回归测试);tsc --noEmit 无错。

升级

npm install opencode-okf-context@0.1.3

无破坏性变更;配置和工具 API 均不变。


完整变更:tag v0.1.3 下的 commit 624d90e。

v0.1.2 — 健壮性修复 + bundle 级校验 + 删除模式 + 批量读取

Choose a tag to compare

@likai-hust likai-hust released this 31 Jul 10:32

opencode-okf-context v0.1.2

This release fixes two robustness issues and adds three enhancements.

High-priority fixes

  • H1: malformed YAML no longer breaks the bundle. A concept with broken frontmatter YAML used to crash discovery and disable every okf_* tool. Now it loads with empty frontmatter and okf_validate reports a yaml-error instead.
  • H2: bundle detection matches the spec. Auto-scan now also accepts a dir with index.md/log.md + at least one typed concept, even without okf_version (the spec's MAY). Plain markdown dirs are still not mis-classified.

Enhancements

  • okf_validate bundle-level checks (all:true): bundle-okf-version-missing (error, fixable), bundle-log-missing (warning, fixable), link-broken (warning, not fixable). Cross-links are normalized (dot segments; escapes dropped).
  • okf_write mode:"delete": removes the file, its parent index.md entry, appends a log.md deletion entry, refreshes the cache.
  • okf_read ids:[...]: batch loads several concepts; the batch unloads as a unit via the existing placeholder mechanism.

Tests

67 tests pass (13 new in tests/robustness.test.ts); tsc --noEmit clean.

Offline install (air-gapped)

tar -xzf opencode-okf-context-0.1.2-offline.tar.gz -C ~/.config/opencode/plugin okf.js
opencode debug agent build | grep okf    # 6 tools

Replace ~/.config/opencode/plugin/okf.js and restart opencode.


Full changes: commit history under tag v0.1.2 (0f27b9d to 802c9ce).


中文说明

opencode-okf-context v0.1.2

本次发布修复两个健壮性问题,并新增三项增强。

高优先级修复

  • H1: 坏 YAML 不再拖垮整个 bundle。 之前某个 concept 的 frontmatter YAML 语法损坏会导致发现崩溃、所有 okf_* 工具不可用。现在它降级为空 frontmatter 加载,okf_validate 会报告 yaml-error。
  • H2: bundle 识别与规范对齐。 自动扫描现在也接受"有 index.md/log.md + 至少一个带 type 的 concept"的目录,即使没有 okf_version(规范中为 MAY)。普通 markdown 目录仍不会被误判。

新增增强

  • okf_validate bundle 级校验(all:true):bundle-okf-version-missing(error,可修复)、bundle-log-missing(warning,可修复)、link-broken(warning,不可修复)。交叉链接会做点段规范化(逃逸根目录的丢弃)。
  • okf_write mode:"delete":删除文件、移除父级 index.md 条目、向 log.md 追加删除记录、刷新缓存。
  • okf_read ids:[...]:批量加载多个 concept;整个批次作为整体卸载(复用现有占位符机制)。

测试

67 个测试全部通过(tests/robustness.test.ts 新增 13 个);tsc --noEmit 干净。

离线安装(内网)

tar -xzf opencode-okf-context-0.1.2-offline.tar.gz -C ~/.config/opencode/plugin okf.js
opencode debug agent build | grep okf    # 6 个工具

替换 ~/.config/opencode/plugin/okf.js 后重启 opencode。


完整变更:见 tag v0.1.2 对应的提交历史(0f27b9d 到 802c9ce)。

v0.1.1 — 校验工具 + 智能修复 + 元数据优先搜索 + 工具路由强化

Choose a tag to compare

@likai-hust likai-hust released this 31 Jul 06:50

opencode-okf-context v0.1.1

This release ships 4 improvements centered on making OKF knowledge bundles more standardized, more token-efficient, and more likely to be used by the model.

✨ New: okf_validate read-only validation tool

  • Validates OKF concept documents against 7 concept-level rules (type required; title/description/tags well-formed; body non-empty)
  • Each issue comes with a ready-to-run okf_write(...) fix command; auto-fixable issues are pre-filled, content issues emit <placeholder> templates
  • Tool count: 5 → 6

🔧 Enhanced: okf_write partial update

  • In update mode, only passed fields change — the rest are preserved from disk, so you can fix a single field without restating the whole document
  • This is the core mechanism that makes okf_validate's fix commands safe to run

🔍 Improved: okf_search metadata-first, body-fallback

  • Before: searched title/description/tags/body in one pass — the body was scanned every time, violating progressive disclosure
  • Now: searches metadata (title/description/tags) first; returns without scanning any body when metadata matches enough, and only falls back to the body when metadata yields nothing
  • Results are tagged [metadata: field] or [body]; metadata hits always rank above body hits

🧭 Improved: stronger L0 manifest so the model prefers OKF tools

  • Previously the model often defaulted to glob/read for knowledge lookups unless explicitly told to use OKF tools
  • The manifest intro is now an explicit routing instruction: for knowledge/documentation/concept lookups, MUST prefer the OKF toolchain (okf_list → okf_read)
  • Live-tested: a vague "read the customer-table knowledge" request auto-routes through okf_list + okf_read without mentioning OKF

Offline install (air-gapped)

See INSTALL.txt inside the archive. Quick steps:

tar -xzf opencode-okf-context-0.1.1-offline.tar.gz -C ~/.config/opencode/plugin okf.js
opencode debug agent build | grep okf    # should show 6 tools incl. okf_validate: true

Archive contents

  • okf.js — self-contained plugin (all deps bundled; zero runtime dependencies)
  • okf.schema.json — plugin config schema
  • INSTALL.txt — install guide (Chinese)

Upgrade

Replace ~/.config/opencode/plugin/okf.js and restart opencode.

Tests

All 54 tests pass (23 new tests for validate + search); tsc --noEmit clean.


Full changes: see the commit history under git tag v0.1.1 (4ed5307 → 0f27b9d).


中文说明

opencode-okf-context v0.1.1

本次发布包含 4 项重要改进,围绕"让 OKF 知识库更规范、更省 token、更容易被模型用上"。

✨ 新增:okf_validate 只读校验工具

  • 按 7 条概念级规则校验 OKF concept 文档(type 必填、title/description/tags 格式、正文非空)
  • 每个问题附带可直接运行的 okf_write(...) 修复命令;可自动修复项预填好值,需内容判断项给 <占位符> 模板
  • 工具数 5 → 6

🔧 增强:okf_write 部分更新

  • update 模式下只改传入字段,其余从磁盘保留 —— 可只修一个字段而无需重述整篇文档
  • 这是让 okf_validate 的修复命令安全可行的核心机制

🔍 改进:okf_search 元数据优先 + 正文回退

  • 之前:title/description/tags/body 一锅搜,正文每次都被翻,违背渐进式披露
  • 现在:先搜元数据(title/description/tags),够数就返回不碰正文;仅当元数据无果才回退搜正文
  • 结果带来源标记 [metadata: 字段] 或 [body],元数据命中优先于正文命中

🧭 改进:强化 L0 manifest,模型主动用 OKF 工具

  • 之前模型常默认用 glob/read 读知识,除非显式要求才用 OKF 工具
  • 强化 manifest 措辞为主动路由指令:查知识/文档/概念时 MUST 优先 OKF 工具链
  • 实测:不提 OKF,只说"读一下 XX 知识",模型会主动走 okf_list → okf_read

离线安装(内网)

见压缩包内 INSTALL.txt。简要步骤:

tar -xzf opencode-okf-context-0.1.1-offline.tar.gz -C ~/.config/opencode/plugin okf.js
opencode debug agent build | grep okf    # 应看到 6 个工具,含 okf_validate: true

压缩包内容

  • okf.js — 自包含插件(已 bundle 所有依赖,零运行时依赖)
  • okf.schema.json — 插件配置 schema
  • INSTALL.txt — 中文安装说明

升级

替换 ~/.config/opencode/plugin/okf.js 后重启 opencode 即可。

测试

54 个测试全部通过(新增 validate + search 共 23 个测试);tsc --noEmit 干净。


完整变更:见下方 git tag v0.1.1 对应的提交历史(4ed5307 → 0f27b9d)。