openkms

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

1. 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.

2. 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.

3. 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   # first time only
python scripts/cli.py ping

4. 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                      # auto: installs to whichever runtimes are present
./install.sh --target opencode    # OpenCode only  → ~/.config/opencode/skills/openkms/
./install.sh --target claude-code # Claude Code only → ~/.claude/skills/openkms/
./install.sh --target both        # both runtimes
./install.sh --dest /custom/path  # explicit destination

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

Write tasks

Mutating commands below use -y/--yes and --dry-run like ontology writes (non-TTY without --yes exits 2).

Ontology objects + links

Same confirmation rules as other writes.

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
# pick the doc id you want from the response
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                      # find the KB id
python scripts/cli.py kb ask --id <kb_id> --question "既往症的判定标准是什么？"

C. NL question against the ontology graph.

python scripts/cli.py ontology ask --question "列出与'重疾豁免'触发条件相关的合规通函"
# returns {question, cypher, explanation, columns, rows, answer}

D. Tight-loop content discovery + read.

# list all "claims" articles, then pull markdown of every one matching a regex
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
# → JobResponse with "id"; worker runs kb-index --wiki-space-id …

F. Improve an article using the latest content review.

python scripts/cli.py articles reviews latest --id <art_id>
# → .result.suggestions[], .result.criteria[] (scores + notes), .result.pass, .result.summary
# If 404: channel needs review_model_id — run review first:
python scripts/cli.py articles review run --id <art_id> --yes
python scripts/cli.py articles markdown --id <art_id>   # read body, apply suggestions, edit locally

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)