Repository navigation
Releases
v0.3.0 — Remote knowledge sources (git remotes, sync log, self-origin guard)
v0.3.0 — Remote knowledge sources
Team-distribution channel for OKF knowledge bases: the KB author pushes to git, every agent pulls automatically.
New
remotesconfig — 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_writerefuses remote bundles (the next sync'sreset --hardwould 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: truemirrors 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 syncCLI — force-updates all remotes (exit 1 on failure — CI gate); otherokfcommands clone on first use then run from cache (--sync/--no-syncto 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
opencodesession (manifest injection + remoteokf_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 syncCLI:强制更新全部 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
English
okfCLI — 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 --allas a repo gate). Read intake control (--fields/--section/--max-chars), read-only by default (--writeto enable writes), CI-friendly exit codes. Note: installing viaopencode plugindoes NOT putokfon PATH — it comes fromnpm 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.afterTurns2→4,keepRecent1→2,nudge.threshold6000→25000. Reloads are expensive; hold concepts a little longer and only nudge when retained knowledge is genuinely large. okf_searchoutputs 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.
中文
okfCLI——包内新增独立命令行工具,与 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)调优——
afterTurns2→4、keepRecent1→2、nudge.threshold6000→25000:重读有成本,概念多留几轮;提醒只在滞留量真正大时触发。 - 检索输出参与去重与老化——同词重复搜索只保留最新结果,旧检索结果像读取一样按轮次占位化,长会话滞留斜率从 ~2.7K 降至 ~1.3K 字符/问。
- 附基准测试与 opt-in 真实 LLM 测试套件(压测 / 命中率 / 压缩抗性 / 读效率)。146 项测试全绿。
v0.1.8 — .opencode is scanned, dead scan.ignore removed
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.
中文摘要
.opencode目录参与扫描——此前所有隐藏目录一律跳过,放在.opencode/skill/下的知识 bundle 无法被自动发现。现在.opencode与普通目录一样被遍历(走正常 bundle 判定:okf_version显式标记,或 index/log + 带type的 concept)。黑名单目录(node_modules、.git、dist等 11 个)在任意深度仍然生效——包括.opencode内部;其余隐藏目录与隐藏文件依旧跳过。- 移除从未实现的
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
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.
中文摘要
四项实战打磨出的修复:
- 版本自报——manifest、
okf_list概览、okf_validate报告头都会标注当前运行版本(如v0.1.7)。opencode 的@latest包缓存可能不刷新(有用户实际跑着 0.1.4 却以为是 0.1.6,排查花了数天);现在一次工具调用即可确认实际加载的构建。 - 嵌套 bundle——自己的
index.md声明了okf_version的目录,即使位于另一个被识别的 bundle 内部,也会作为独立 bundle 被发现,且其子树从外层 bundle 的 concepts 中排除。此前误判的项目根(例如 AI 按 validate 建议创建了根 index.md)会把真正的知识 bundle 整个吞掉。 - 卸载占位符防reload循环——旧文案 "unloaded — reload with okf_read" 会被模型当作指令,触发 读→卸载→重读 死循环(实测烧掉 3 分钟/50K token)。新文案明确"例行上下文管理、无需操作、仅在确实需要全文时再 okf_read"。
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
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
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 变更。
- Bundle-root 误判修复:扫描启发式之前用递归累积的 index/type 计数判断 bundle root,导致普通项目根(有带 type 的 README + 子目录恰好有 index.md)被误判为 bundle。现在只看根目录直接子文件的标志。
- Validate 修复命令误导修复:报告统一提示"用 okf_write 修复",但 bundle 级的 okf_version 问题不能用 okf_write 修(index.md 是保留文件)。这导致 AI 给每个 concept 文件加了 okf_version。现在 footer 区分两类修复路径,fix 命令用真实路径 + 明确声明保留文件限制。
- okf_list type 过滤:列表现在只显示有
type的 concept,无 type 的普通 MD 文档不再列出(与 references 注释、okf_refs 的守卫一致)。无 type 文件仍被发现(validate 能报),只是列表隐藏。
v0.1.4 — Bidirectional reference graph (okf_refs + read annotations)
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
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_searchbefore guessing.
Details:
- Manifest (
indexing.ts): added reactive + proactive trigger conditions, bilingual (zh/en) trigger phrases, and a quick decision guide so the agent picksokf_searchfirst when it hears a term instead of always starting fromokf_list. okf_searchdescription (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
forcefield inokf.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 级校验 + 删除模式 + 批量读取
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。
v0.1.1 — 校验工具 + 智能修复 + 元数据优先搜索 + 工具路由强化
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 (
typerequired;title/description/tagswell-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
updatemode, 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/readfor 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_readwithout 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: trueArchive contents
okf.js— self-contained plugin (all deps bundled; zero runtime dependencies)okf.schema.json— plugin config schemaINSTALL.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— 插件配置 schemaINSTALL.txt— 中文安装说明
升级
替换 ~/.config/opencode/plugin/okf.js 后重启 opencode 即可。
测试
54 个测试全部通过(新增 validate + search 共 23 个测试);tsc --noEmit 干净。