seekdeep-native-plugin
Use when adding, porting, or extending a SeekDeep Harness plugin as a Rust crate under crates/ — a model-facing tool, a service provider or consumer, an LLM adapter, a persistence, sandbox, or OS integration, or any built-in the seekdeep binary ships — and whenever new harness behavior needs a home and the choice between a native Rust crate and a TypeScript file plugin is still open; covers the crate skeleton, Plugin::new with config validation, typed services and reversible effects, catalog and bundle registration, composition and oracle tests, README pairs, generated catalogs, the parity manifest, and the Rust gates.
- License 许可
- MIT
- 最近更新
- 2026-11-11
- Stars
- ★ 5
- Forks
- 0
01 前言 Front Matter
- name
- seekdeep-native-plugin
- description
- Use when adding, porting, or extending a SeekDeep Harness plugin as a Rust crate under crates/ — a model-facing tool, a service provider or consumer, an LLM adapter, a persistence, sandbox, or OS integration, or any built-in the seekdeep binary ships — and whenever new harness behavior needs a home and the choice between a native Rust crate and a TypeScript file plugin is still open; covers the crate skeleton, Plugin::new with config validation, typed services and reversible effects, catalog and bundle registration, composition and oracle tests, README pairs, generated catalogs, the parity manifest, and the Rust gates.
02 资源文件 1
- 参考文档agents/openai.yaml232 B
03 SKILL.md 正文
SeekDeep Native Plugin
Guide an agent through adding or changing a plugin crate so the result matches the crates the port already ships. This is guidance, not a script: the contracts live in the documents below, and this skill only orders the work and names the evidence each step needs.
Read the contracts
- crates/AGENTS.md — the crate shape, wiring, tests, and gates.
- packages/AGENTS.md — the behavioral rules every plugin obeys regardless of language.
- Root AGENTS.md — parity, naming, and Rust conventions.
- Where new behavior goes — which service or event a capability attaches to.
- Runtime placement — what stays native and what stays JavaScript.
Decide the runtime first
Write Rust when the plugin is part of the product: anything the seekdeep binary ships, anything on the hot path or touching filesystem, subprocess, sandbox, persistence, or OS integration, anything with a typed cross-plugin contract, and anything the parity, determinism, or invariant machinery must verify. A native crate is compiled into the binary and registered at boot; there is no dynamic native loading.
Write a TypeScript file plugin when the plugin arrives at runtime: a path in cordis.yml that must load without a rebuild, hot reload on save, or an out-of-tree extension. Model-authored cordis_define packages are JavaScript by contract. Keep those surfaces intact; they are preserved source behavior, not legacy (your first plugin).
During the port, a capability absent from the pinned source is post-parity work; port and preserve first (POST_PARITY).
Workflow
- Name the seam. Pick the service or event the capability attaches to from the architecture table; a new capability needs its Service Definition, provider, and consumer roles, and its name follows the naming rules.
- Start from a shipped crate of the same role rather than from scratch:
crates/tool-todofor a tool,crates/cordis-timerfor a service provider,crates/cordis/examples/hello_cordis.rsfor the lifecycle in isolation. Copy the shape, then replace the behavior. - Implement
NAME,INJECT,plugin(), the configSchemaand its validator, and anapplywhose every registration is an effect the fiber unwinds. Prove disposal in a test that disposes the fiber and observes removal. - Wire it: the boot roster in
apps/seekdeep/src/profile_boot.rsunder both names, the bundle row with its config, and the package manifest and README pair beside the crate README. - Test it:
tests/loader_composition.rsthrough the real Loader, unit tests for the behavior, oracle tests only for a ported surface, and snapshot tests for model-visible text. - Regenerate and record: the catalogs the change touches, the
porting/parity.jsonentry for a ported surface, and an Agent Note for any decision a maintainer may revisit. - Verify with
cargo fmt --all -- --check,cargo clippy --workspace --all-targets --all-features -- -D warnings,cargo test -p seekdeep-<name> --all-features, the catalog--checkruns, andverify-cordis-config; then select the rest through seekdeep-pre-push-checks.
Traps
- A
packages/<group>/<pkg>/src/index.tsis not where runtime lands; the TypeScript cookbook describes the manifest and README half of a plugin. context.geton an injected service inside the body is guaranteed to succeed;get_relaxedexists for observers that must see a provider while it is still loading.- Config that names an unavailable provider or resource fails at the earliest resolvable point, in the validator or the first line of
apply, never later. - Crates in the determinism perimeter never call
Instant::now()orSystemTime::now(); take a clock through a seam. - The oracle tests need the checkout named in
SOURCE_SNAPSHOT; a container without it fails those binaries, which says nothing about your change.
Report
State which seam the plugin attaches to, the roster and bundle rows added, the composition and unit tests, the catalogs regenerated, and every gate run with its result. Name any deviation from the pinned source and where it is recorded.
04 同仓库更多 Skills
user-only-skill
Prove model-disabled skills stay outside the model catalog.
snapshot-skill
Exercise project skill discovery and loading in snapshot tests.
model-only-skill
Prove user-disabled skills remain available to the model.
editing-cordis-compositions
Use when creating, changing, or validating a Cordis composition for this harness — writing or editing an agent preset, adding or removing a plugin row, deciding whether something belongs to the host composition or to one session, checking whether a preset you authored actually mounts, or diagnosing a row that mounted but contributed nothing.
cordis-plugin-development
Create, modify, debug, or extend dynamic Cordis Plugins, including Host Services and Events, Client Slot and theme UI, Package-private Client-to-Host calls, dynamic Tools, version updates, approval failures, and runtime diagnostics. Use this Skill to route a user request to the correct platform and Inspect Provider, then define, run, repair, or roll back the Plugin.
seekdeep-trim-cot-leakage
Use when auditing or fixing prose that reads like a leaked reasoning transcript — dead design-session citations such as (decision N), audit item codes, or §N of uncommitted drafts; change narration such as "used to", "no longer", "this cut"; stack or review vantage ("a later PR in this stack", "rejected in review"); reviewer-addressed justifications; control-flow narration; or hedged planning residue in comments, JSDoc, docs, or Agent Notes.