| name | openkms |
| description | Operates and queries an openKMS deployment over its HTTP API using a personal API key. Read paths: global search across documents/articles/wiki/KBs; list & fetch markdown for documents and articles; list & get markdown for articles; **article LLM content review** (latest rubric scores + suggestions); list & get wiki pages by path; **wiki page substring/semantic search**; list wiki space stored files (vault .md, assets, uploads) and linked channel documents; KB semantic search and grounded Q&A; list glossaries and terms, export/import term payloads; Knowledge Map tree and resource links; document lineage (relationships) and policy lifecycle fields; article↔article relationship list/create/delete; list evaluations, items, and runs (including wiki content coverage when a wiki space is linked); run Cypher (or natural-language questions) against the ontology graph. Write paths: create channels, upload documents, create articles (incl. from URL), **run article content review**, upsert wiki pages, delete wiki stored files (incl. vault .md), link/unlink wiki↔documents, create KB FAQs and evaluations (update evaluation metadata and items in place), trigger evaluation runs; **re-index one linked wiki space into a KB** (or queue full KB index); glossary and term CRUD, bulk import, AI term suggest; knowledge map nodes and channel/wiki mappings; document lifecycle PATCH and relationship create/delete; article relationship create/delete; ontology object/link CRUD and Neo4j index (bulk or per-type). Use when the user wants an agent — or any external tool — to read content from or push content to openKMS without the web UI. Agents must use the bundled `scripts/cli.py` only (no ad-hoc curl or custom HTTP). Do not modify skill source files; only `config.yml` may be created/updated for credentials when the user asks. |
openKMS skill
Mandatory for agents: use scripts/cli.py only
Do not implement openKMS access with hand-written curl, ad-hoc httpx/requests/fetch, or throwaway scripts that call /api/… directly. Do not treat reference.md as something to copy into new code—it documents how each existing CLI subcommand maps to HTTP for operators and code review, not as a second implementation path.
Every read and write against this deployment must go through python scripts/cli.py …. That preserves Bearer auth, mutation gates (--yes / --dry-run), multipart uploads, path encoding, and error handling in one place. If a workflow is missing from the CLI, extend openkms-skill in the repository (or ask the user to)—do not bypass the bundled scripts.
Dependencies (requirements.txt)
- Installed into an openKMS project (Agents → Skills → install): the platform runs
pip install -r requirements.txt once when the skill is copied into .openkms/skills/openkms/. Do not run pip install again on each CLI call. If python …/scripts/cli.py fails with ModuleNotFoundError, ask the user to reinstall or update the skill in project settings — do not patch deps by hand.
- Standalone copy (OpenCode, Claude Code, manual
install.sh, or dev checkout): run pip install -r requirements.txt once after copying the skill tree, then use the CLI as usual. Still not before every command.
- Smoke check —
python …/scripts/cli.py ping verifies auth and that imports work; that is enough. No separate install step per session.
openKMS project agents (workspace under {project_id}/)
When this skill is installed at .openkms/skills/openkms/ inside a project workspace:
- Shell cwd is the project root. Run one command — no
cd, no pip install:
python .openkms/skills/openkms/scripts/cli.py wiki-spaces list
OPENKMS_API_KEY, OPENKMS_API_BASE_URL, and OPENKMS_SKILL_ROOT are injected by the agent runtime; config.yml is optional.- Example:
python .openkms/skills/openkms/scripts/cli.py ping
Standalone / OpenCode / Claude installs: see Dependencies above and Before you act §3.
Evaluations. To change an evaluation’s name, description, or wiki link, use evaluations update. To add, edit, or remove question rows, use evaluations items add, evaluations items update, and evaluations items delete. Do not delete an evaluation and evaluations create a replacement just to “refresh” data—that drops saved runs and changes the evaluation id (bad for bookmarks, scripts, and comparisons). Reserve evaluations create for when the user explicitly wants a new evaluation.
Do not modify this skill’s shipped files. Never edit, delete, or add files under this skill directory except config.yml — and only to set api_base_url and api_key when the user explicitly asks you to store them (see Before you act §2). Do not touch SKILL.md, README.md, reference.md, scripts/, install.sh, requirements.txt, tests, or any other path here; do not patch or extend the CLI inside the install tree. Changes belong in the openKMS repository with a normal human review, not in the agent’s copy of the skill.
Before you act
-
Config — The runtime reads config.yml in this directory (next to SKILL.md). It must include:
api_base_url — backend origin only, e.g. http://127.0.0.1:8102 (no trailing slash).api_key — personal key from Settings → API keys in openKMS (user menu Settings; okms.{uuid}.{secret}).- Optional:
default_document_channel_id / default_article_channel_id — UUID strings; when set, documents list|upload and articles list|create|from-url may omit --channel-id and use these defaults (see config.yml.example).
- Optional:
default_pipeline_id — pipeline id string (e.g. pipeline_baidu_doc_parse); when set, document-channels create assigns it as the channel's default parse pipeline unless --pipeline-id is passed.
-
If either value is missing — In a project agent session, OPENKMS_API_KEY and OPENKMS_API_BASE_URL are usually already set; you do not need config.yml. Otherwise ask the user for the backend URL and a new key from Settings (they see the full token once when creating it). Then write or update config.yml in this skill directory. Never echo the key back in full unless the user explicitly asks.
-
Run the bundled CLI
Project agent (skill at .openkms/skills/openkms/, cwd = project root; deps already installed — see Dependencies):
python .openkms/skills/openkms/scripts/cli.py ping
Standalone install (skill directory is cwd; run pip install -r requirements.txt once after copying — not before every command):
pip install -q -r requirements.txt
python scripts/cli.py ping
- Auth header — The CLI sends
Authorization: Bearer <api_key>. Same permissions as the user who created the key.
Install (OpenCode and Claude Code)
From the repo:
./install.sh
./install.sh --target opencode
./install.sh --target claude-code
./install.sh --target both
./install.sh --dest /custom/path
Auto mode picks targets based on which dirs exist (~/.config/opencode/, ~/.claude/). Re-run after pulling repo changes. An existing config.yml in any destination is preserved (not overwritten by the fresh tree).
How to use this skill
The skill is a thin Python CLI over openKMS's HTTP API. Every command JSON-prints the raw API response (json.dumps, indented). You parse it, then drive the next call. There is no client-side magic — pagination, retries, follow-ups are all yours.
Some practical guidance:
- Document channels need a pipeline for PDF parse. Uploading PDFs/images/Office to a channel without a default pipeline leaves documents stuck at
uploaded — Process is disabled in the UI and POST /api/jobs fails. Before creating a channel for parseable files: run pipelines list (or pipelines list --table) to pick an active pipeline id, then document-channels create --pipeline-id … or set default_pipeline_id in config.yml. XLSX/XMind previews do not need a pipeline. To fix an existing channel: document-channels update --id DC_ID --pipeline-id … --yes.
- Discover before you fetch. Most agent workflows start with
search (or documents list --search … / articles list --search …) to find candidates by name, then a get / markdown to pull content. Don't fetch a whole channel just to grep — server-side --search is keyword-substring against names/titles.
- Article content review. Channels can configure an LLM rubric (
review_model_id, review_prompt, review_criteria). After a review exists, articles reviews latest --id ART_ID returns result.pass, result.overall_score, per-criterion scores/notes, and result.suggestions — use these to revise markdown. 404 means no review yet; run articles review run --id ART_ID --yes (needs channel review model). Review does not edit the article; you apply suggestions yourself.
kb ask vs kb search. ask proxies to the QA agent and returns a grounded answer (with citations). search is now hybrid (BM25 + dense + RRF + cross-encoder rerank) and returns raw chunks + FAQ matches with confidence scores. Lexical tokens like product codes (e.g. WWY, MIL) are heavily weighted via BM25, so kb search --q "WWY 年化收益" returns WWY-specific chunks even when the embedding alone wouldn't. First call per KB cold-starts the BM25 index (paginates all chunks/FAQs); subsequent calls are fast. Use ask when the user wants an answer; use search when you need source material to reason over yourself.- KB wiki indexing. After
wiki put-page (or bulk wiki edits), re-chunk into a linked KB with kb wiki-spaces reindex --kb-id KB_ID --space-id SP_ID --yes — replaces prior wiki chunks for that space only (one page ≈ one chunk when ≤8000 chars). Use kb wiki-spaces list --kb-id KB_ID to see linked spaces. Full document + all wiki spaces: kb index --id KB_ID --yes. Both return a JobResponse (id, status, …); poll /api/jobs/{id} or the Job runs UI for completion.
ontology ask is a 3-call chain. It runs text-to-cypher → explore → answer for you. Use when the question is graph-shaped and you don't want to chain by hand. Use the individual subcommands when you need to inspect or rewrite the Cypher.- Permission model is enforced server-side. API key carries the user's scope. List endpoints filter to readable channels; per-id GET returns 404 (not 403) when out of scope. Don't try to bypass — surface the error.
- Write commands and confirm gating. Every mutating CLI subcommand uses the same pattern as ontology objects/links:
--dry-run prints the planned [METHOD] path + body (upload uses a JSON summary with channel_id and file path, not file bytes) and exits 0 without HTTP; -y / --yes skips the prompt; without either on a TTY you get Proceed? [y/N]; on a non-TTY without --yes the command exits 2 — agents must pass --yes deliberately.
- Ontology read vs write.
ontology cypher/text-to-cypher/answer/ask go through /api/ontology/* and are read-only (server regex-blocks CREATE/MERGE/DELETE/SET/REMOVE/DETACH/DROP/CALL/apoc/dbms). To enrich the graph, use ontology objects ... and ontology links ... (Postgres ontology layer) and then ontology objects sync-neo4j / ontology links sync-neo4j (all indexable types) or sync-neo4j-type on one type id to MERGE into Neo4j.
wiki files is the whole space file store, not “attachments only”. wiki files list / wiki files delete operate on /api/wiki-spaces/…/files: vault imports (including mirrored .md and images/PDFs), uploads, etc. Deleting a row removes that stored object (DB + storage). To change wiki page body (the page entity), use wiki put-page (or the app editor) — do not treat “files” as only sidecar attachments.- Knowledge map (
knowledge-map). Mirrors Console Knowledge Map under /api/knowledge-map/*: term tree, node CRUD, and mapping document/article channels or wiki spaces to nodes. Requires knowledge_map:read / knowledge_map:write when the server enforces those permissions (same as the SPA).
- Output is verbose. Each list response can include long arrays. If you're scanning many records, pipe through
jq to project just the fields you need rather than dumping everything into context.
Read / query tasks
| Goal | Command |
|---|
| Verify connectivity | python scripts/cli.py ping |
| Global search across content | python scripts/cli.py search --q "乳腺癌" --types documents,articles --limit 20 |
| List document channels as indented tree (human-readable) | python scripts/cli.py document-channels list --tree |
| List document processing pipelines | python scripts/cli.py pipelines list (or --table for id / name / active) |
| List article channels as indented tree (human-readable) | python scripts/cli.py article-channels list --tree |
| List documents (filter by channel/keyword) | python scripts/cli.py documents list --channel-id ID --search "心梗" --limit 50 |
| Get document metadata + body | python scripts/cli.py documents get --id DOC_ID |
| List document lineage (outgoing + incoming edges) | python scripts/cli.py documents relationships list --id DOC_ID |
| Save just the document markdown to a file | python scripts/cli.py documents markdown --id DOC_ID --out ./case.md |
| List articles (filter by channel/keyword) | python scripts/cli.py articles list --channel-id ID --search "豁免" |
| List article lineage (outgoing + incoming edges) | python scripts/cli.py articles relationships list --id ART_ID |
| Get article markdown | python scripts/cli.py articles markdown --id ART_ID |
| Latest LLM content review (scores + suggestions) | python scripts/cli.py articles reviews latest --id ART_ID |
| List recent content reviews | python scripts/cli.py articles reviews list --id ART_ID --limit 10 |
| List wiki pages in a space | python scripts/cli.py wiki list-pages --space-id SP_ID |
| Search wiki pages (substring or semantic when indexed) | python scripts/cli.py wiki pages semantic-matches --space-id SP_ID --q "onboarding" --top-k 10 |
| List wiki space stored files (vault .md, assets, uploads; not attachments-only) | python scripts/cli.py wiki files list --space-id SP_ID |
| List channel documents linked to a wiki space (UI “linked documents”) | python scripts/cli.py wiki-spaces documents list --space-id SP_ID |
| Get one wiki page by Obsidian path | python scripts/cli.py wiki get-page --space-id SP_ID --path notes/onboarding |
| List knowledge bases | python scripts/cli.py kb list |
| List wiki spaces linked to a KB | python scripts/cli.py kb wiki-spaces list --kb-id KB_ID |
| Semantic search over KB chunks + FAQs | python scripts/cli.py kb search --id KB_ID --q "既往症定义" --limit 10 |
| Ask the KB a question (grounded answer) | python scripts/cli.py kb ask --id KB_ID --question "..." |
| List FAQs on a KB | python scripts/cli.py kb-faq list --kb-id KB_ID |
| List glossaries | python scripts/cli.py glossaries list |
| Get one glossary | python scripts/cli.py glossaries get --id GL_ID |
| List terms in a glossary (optional search) | python scripts/cli.py glossaries terms list --glossary-id GL_ID --search "心梗" |
| Get one glossary term | python scripts/cli.py glossaries terms get --glossary-id GL_ID --term-id TERM_ID |
| Export glossary terms (JSON) | python scripts/cli.py glossaries export --glossary-id GL_ID |
| Run a Cypher query against the ontology graph | python scripts/cli.py ontology cypher --query "MATCH (n:Customer) RETURN n LIMIT 10" |
| NL question → Cypher (just the translation) | python scripts/cli.py ontology text-to-cypher --question "..." |
| NL question → Cypher → results → NL answer (3-call chain) | python scripts/cli.py ontology ask --question "..." |
| List object types | python scripts/cli.py ontology objects list [--master-data-only] [--count-from-neo4j] |
| Get one object type | python scripts/cli.py ontology objects get --id OT_ID |
| List instances of a type | python scripts/cli.py ontology objects instances list --type-id OT_ID --limit 50 |
| Get one instance | python scripts/cli.py ontology objects instances get --type-id OT_ID --id OI_ID |
| List link types | python scripts/cli.py ontology links list |
| Get one link type | python scripts/cli.py ontology links get --id LT_ID |
| List instances of a link type | python scripts/cli.py ontology links instances list --type-id LT_ID --limit 50 |
| Get one evaluation's metadata | python scripts/cli.py evaluations get --id DS_ID |
| List items in an evaluation | python scripts/cli.py evaluations items list --id DS_ID --limit 50 |
| List runs for an evaluation | python scripts/cli.py evaluation-runs list --evaluation-id DS_ID |
| Get one run with per-item results | python scripts/cli.py evaluation-runs get --evaluation-id DS_ID --run-id RUN_ID |
| Compare two runs | python scripts/cli.py evaluation-runs compare --evaluation-id DS_ID --run-a A --run-b B |
| Get Knowledge Map tree | python scripts/cli.py knowledge-map nodes tree |
| List all knowledge map resource links | python scripts/cli.py knowledge-map resource-links list |
Write tasks
Mutating commands below use -y/--yes and --dry-run like ontology writes (non-TTY without --yes exits 2).
| Goal | Command |
|---|
| List document channels (tree) | python scripts/cli.py document-channels list |
| Create document channel | python scripts/cli.py document-channels create --name "Inbox" --yes |
| Create document channel with parse pipeline | python scripts/cli.py pipelines list --table then document-channels create --name "Insurance" --pipeline-id pipeline_baidu_doc_parse --yes |
| Update document channel | python scripts/cli.py document-channels update --id DC_ID --name "Renamed" --yes |
| Set channel parse pipeline | python scripts/cli.py document-channels update --id DC_ID --pipeline-id pipeline_baidu_doc_parse --yes |
| Upload a file to a channel | python scripts/cli.py documents upload --channel-id ID --file /path/to/doc.pdf --yes (or omit --channel-id if default_document_channel_id is set in config.yml) |
| Patch document lifecycle (series, dates, status) | python scripts/cli.py documents lifecycle patch --id DOC_ID --lifecycle-status in_force --series-id SER_UUID --yes |
| Add lineage edge (this doc → other) | python scripts/cli.py documents relationships create --id DOC_ID --target-id OTHER_ID --relation-type supersedes --yes |
| Remove an outgoing lineage edge | python scripts/cli.py documents relationships delete --id DOC_ID --relationship-id REL_ID --yes |
| List article channels (tree) | python scripts/cli.py article-channels list |
| Create article channel | python scripts/cli.py article-channels create --name "Internal Wiki" --yes |
| Update article channel | python scripts/cli.py article-channels update --id AC_ID --parent-id PARENT_UUID --yes |
| Create article from a markdown file | python scripts/cli.py articles create --channel-id ID --name "Title" --markdown-file ./x.md --yes |
| Import article from a URL (HTML → text heuristic) | python scripts/cli.py articles from-url --channel-id ID --url https://example.com/a --yes |
| Run LLM content review (persist) | python scripts/cli.py articles review run --id ART_ID --yes |
| Add article lineage edge (this article → other) | python scripts/cli.py articles relationships create --id ART_ID --target-id OTHER_ID --relation-type supersedes --yes |
| Remove an outgoing article lineage edge | python scripts/cli.py articles relationships delete --id ART_ID --relationship-id REL_ID --yes |
| List wiki spaces | python scripts/cli.py wiki-spaces list |
| Create wiki space | python scripts/cli.py wiki-spaces create --name "Field Notes" --yes |
| Link a channel document to a wiki space | python scripts/cli.py wiki-spaces documents link --space-id SP_ID --document-id DOC_ID --yes |
| Unlink a document from a wiki space (does not delete the document) | python scripts/cli.py wiki-spaces documents unlink --space-id SP_ID --document-id DOC_ID --yes |
| Upsert wiki page from file | python scripts/cli.py wiki put-page --space-id ID --path my/page --title "T" --file ./note.md --yes |
| Re-index one linked wiki space into a KB | python scripts/cli.py kb wiki-spaces reindex --kb-id KB_ID --space-id SP_ID --yes |
| Queue full KB reindex (documents + all linked wiki spaces) | python scripts/cli.py kb index --id KB_ID --yes |
| Delete one wiki stored file by id (vault .md or any stored path; DB + storage) | python scripts/cli.py wiki files delete --space-id SP_ID --file-id FILE_ID --yes |
| Create FAQ on a KB | python scripts/cli.py kb-faq create --kb-id ID --question "Q" --answer "A" --yes |
| List evaluations | python scripts/cli.py evaluations list |
| Create evaluation | python scripts/cli.py evaluations create --name "…" --kb-id KB_ID --wiki-space-id SP_ID --yes |
| Update evaluation (name / description / KB or wiki link; same id, keeps runs) | python scripts/cli.py evaluations update --id EV_ID --name "…" --yes (optional --description, --knowledge-base-id ID, --wiki-space-id ID, or --clear-wiki-space) |
| Add one evaluation item | python scripts/cli.py evaluations items add --id EV_ID --query "…" --expected-answer "…" --yes (optional --topic, --sort-order) |
| Update one evaluation item | python scripts/cli.py evaluations items update --id EV_ID --item-id ITEM_ID --query "…" --yes (any of --query, --expected-answer, --topic, --sort-order) |
| Delete one evaluation item | python scripts/cli.py evaluations items delete --id EV_ID --item-id ITEM_ID --yes |
| Trigger an evaluation run | python scripts/cli.py evaluations run --id EV_ID --type qa_answer --yes (use --type wiki_content_coverage when the evaluation has a linked wiki space; expected_answer is the checklist text for the judge) |
| Create glossary | python scripts/cli.py glossaries create --name "Product terms" --yes |
| Update / delete glossary | python scripts/cli.py glossaries update --id GL_ID --description "…" --yes / glossaries delete --id GL_ID --yes |
| Create / update / delete term | python scripts/cli.py glossaries terms create --glossary-id GL_ID --primary-en "MI" --primary-cn "心梗" --yes (and terms update / terms delete) |
| Bulk-import terms from JSON file | python scripts/cli.py glossaries import --glossary-id GL_ID --terms-file ./terms.json --mode replace --yes |
| AI suggest for a term (uses default LLM) | python scripts/cli.py glossaries terms suggest --glossary-id GL_ID --primary-en "STEMI" --yes |
| Create knowledge map node | python scripts/cli.py knowledge-map nodes create --name "Claims" --yes |
| Patch / delete knowledge map node | python scripts/cli.py knowledge-map nodes patch --id NODE_ID --name "Renamed" --yes / knowledge-map nodes delete --id NODE_ID --yes |
| Map a channel or wiki space to a map node | python scripts/cli.py knowledge-map resource-links put --knowledge-map-node-id NODE --resource-type document_channel --resource-id CHAN_ID --yes |
| Unmap a resource from the knowledge map | python scripts/cli.py knowledge-map resource-links delete --resource-type wiki_space --resource-id WS_ID --yes |
Ontology objects + links
Same confirmation rules as other writes.
| Goal | Command |
|---|
| Create object type | python scripts/cli.py ontology objects create-type --name "Disease" --properties-json '[{"name":"icd","type":"string","required":true}]' --yes |
| Update object type | python scripts/cli.py ontology objects update-type --id OT --display-property name --yes |
| Delete object type | python scripts/cli.py ontology objects delete-type --id OT --yes |
| Create object instance | python scripts/cli.py ontology objects instances create --type-id OT --data-json '{"icd":"C50"}' --yes |
| Update object instance | python scripts/cli.py ontology objects instances update --type-id OT --id OI --data-json '{"icd":"C50.1"}' --yes |
| Delete object instance | python scripts/cli.py ontology objects instances delete --type-id OT --id OI --yes |
| MERGE all indexable object types into Neo4j | python scripts/cli.py ontology objects sync-neo4j --neo4j-data-source-id DS --yes |
| MERGE one object type into Neo4j | python scripts/cli.py ontology objects sync-neo4j-type --type-id OT_ID --neo4j-data-source-id DS --yes |
| Create link type | python scripts/cli.py ontology links create-type --name covers --source-type-id OT_PROD --target-type-id OT_DIS --cardinality many-to-many --yes |
| Update link type | python scripts/cli.py ontology links update-type --id LT --description "..." --yes |
| Delete link type | python scripts/cli.py ontology links delete-type --id LT --yes |
| Create link instance | python scripts/cli.py ontology links instances create --type-id LT --source-object-id OI_A --target-object-id OI_B --yes |
| Delete link instance | python scripts/cli.py ontology links instances delete --type-id LT --id LI --yes |
| MERGE all indexable link types into Neo4j | python scripts/cli.py ontology links sync-neo4j --neo4j-data-source-id DS --yes |
| MERGE one link type into Neo4j | python scripts/cli.py ontology links sync-neo4j-type --type-id LT_ID --neo4j-data-source-id DS --yes |
When a link type is many-to-many and dataset-backed, the server is the source of truth via the junction table — ontology links instances create/delete will return 4xx. Surface that error rather than trying to bypass.
Workflow recipes
A. Find a doc by phrase, fetch its markdown.
python scripts/cli.py search --q "乳腺癌" --types documents --limit 5
python scripts/cli.py documents markdown --id <doc_id> --out ./case.md
B. Ask the KB a question (grounded with citations).
python scripts/cli.py kb list
python scripts/cli.py kb ask --id <kb_id> --question "既往症的判定标准是什么？"
C. NL question against the ontology graph.
python scripts/cli.py ontology ask --question "列出与'重疾豁免'触发条件相关的合规通函"
D. Tight-loop content discovery + read.
python scripts/cli.py articles list --channel-id <ch_id> --limit 200 \
| jq -r '.items[] | select(.name | test("乳腺癌")) | .id' \
| while read id; do python scripts/cli.py articles markdown --id "$id" --out "./$id.md"; done
E. After wiki page edits, refresh KB search for one linked space.
python scripts/cli.py kb wiki-spaces list --kb-id <kb_id>
python scripts/cli.py kb wiki-spaces reindex --kb-id <kb_id> --space-id <space_id> --yes
F. Improve an article using the latest content review.
python scripts/cli.py articles reviews latest --id <art_id>
python scripts/cli.py articles review run --id <art_id> --yes
python scripts/cli.py articles markdown --id <art_id>
Reference
- Per-command JSON shapes & curl equivalents: reference.md
- Canonical route list: project
docs/features/api-reference.md
- Tests:
tests/ — pytest -v against an httpx mock transport (see dev-requirements.txt)
