Skip to content

AGENTS.md

Latest commit

 

History

History
135 lines (111 loc) · 8.24 KB

AGENTS.md

File metadata and controls

135 lines (111 loc) · 8.24 KB
Raw

AGENTS.md — OpenKB Codex Instructions

This file is the highest-priority project instruction for Codex or any coding agent working in this repository.

Project identity

OpenKB is a Markdown-first, Yuque-like, self-hostable knowledge base system. It supports document editing, Yuque-style permissions, file import to Markdown, Milvus-based retrieval, Dify External Knowledge compatibility, and a user-bound MCP server.

Non-negotiable rules

  1. Markdown follows Milkdown exactly.

    • Do not invent a custom OpenKB Markdown dialect.
    • The supported Markdown set is the round-trippable Markdown supported by the locked Milkdown version and the enabled Milkdown plugins.
    • If a feature cannot be parsed, rendered, and serialized through Milkdown, it is not supported as editable body Markdown.

  2. The editor must feel close to Yuque.

    • Left document tree, center document editor, right outline.
    • Markdown-rich-text editing through Milkdown.
    • Reading mode, edit mode, source mode.
    • Collaboration, sharing, invitations, and visibility controls should be exposed in Yuque-like places.

  3. Permissions must align with Yuque-style product logic.

    • Workspace/space, knowledge base, document, collaborators, invitation links, share links, approval, password, member-only access, and close-share behaviors.
    • Do not introduce LDAP, SCIM, OpenFGA, Casbin, OPA, or custom ABAC in v0.x.
    • External identity systems may be added later only as login/user import sources, not as replacements for the Yuque-style object permissions.

  4. Admin configuration is not content permission.

    • system_admin / tenant_admin can access admin configuration pages.
    • Admin status can grant metadata visibility and management over workspaces/knowledge bases in scope, but does not automatically grant read access to private document bodies.
    • Private content access by an admin must be an explicit audited takeover action that grants a normal collaborator role before content is read.
    • Any emergency content access must be an explicit audited action, not default behavior.

  5. Knowledge base owners cannot configure models.

    • Workspace owners, knowledge base owners, knowledge base managers, and document owners cannot configure embedding/rerank/LLM models.
    • Model and Milvus index configuration is admin-only.

  6. Embedding and rerank belong to Milvus-native capabilities whenever supported.

    • Use Milvus 2.6+ Functions such as TEXTEMBEDDING, BM25, and RERANK/Model Ranker when compatible with the deployment.
    • OpenKB may store instance-level encrypted model secrets only when a system_admin configures them and OPENKB_CONFIG_ENCRYPTION_KEY is set.
    • Never store model API keys in plaintext, never write raw model secrets to audit logs, and never add knowledge-base-level model configuration.
    • Provider credentials and endpoints should be configured in Milvus deployment configuration, environment variables, or the provider service deployment.

  7. Complex import tools are system-level infrastructure.

    • PDF/Office/image conversion tools such as MarkItDown, MinerU, Pandoc, and OCR adapters can be configured only by system_admin.
    • Store import tool API keys only as instance-level encrypted secrets when OPENKB_CONFIG_ENCRYPTION_KEY is set.
    • Never store import tool secrets in plaintext, never write raw tool secrets to audit logs, and never add tenant/workspace/knowledge-base-level import tool configuration.

  8. Embedding model replacement uses Milvus-native blue/green indexing.

    • Do not mix vectors generated by different embedding models/dimensions in one active collection.
    • Create a new collection with the new schema/functions, rebuild from PostgreSQL chunks, load and health-check it, then switch the Milvus alias.
    • Keep old collections temporarily for rollback.

  9. PostgreSQL is the content and permission truth.

    • Markdown content, document versions, directories, users, collaborators, share links, invitations, audit logs, and permission decisions live in PostgreSQL.
    • Milvus never becomes the final authorization source.

  10. Milvus is a retrieval index.

    • Milvus stores chunk text, metadata, access principals, vector/sparse search indexes, and collection aliases.
    • If Milvus and PostgreSQL disagree about access, PostgreSQL wins.

  11. MCP is user-bound; Dify is app-key-bound.

    • MCP tokens must resolve to a real user and use that user's document permissions.
    • Dify External Knowledge API keys are scoped to specific knowledge bases and cannot impersonate arbitrary users.

  12. Every retrieval result must pass final permission check.

    • Web search, MCP, Dify, export, and attachment reads must call the same permission service before returning sensitive content.

Tech baseline

  • Monorepo: pnpm workspaces + Turborepo.
  • Frontend: Next.js, React, TypeScript, Milkdown, Tailwind CSS, shadcn/ui.
  • API: NestJS with Fastify adapter, REST + OpenAPI.
  • Database: PostgreSQL.
  • ORM/migrations: Prisma plus SQL migrations where Prisma is insufficient.
  • Queue/cache: Redis + BullMQ.
  • Object storage: S3-compatible storage, MinIO for self-hosted.
  • Vector/search index: Milvus Server 2.6+ by default.
  • Import worker: Python worker for MinerU and conversion adapters.
  • Index worker: TypeScript worker that reads chunks from PostgreSQL and writes raw text/metadata to Milvus collections.
  • MCP: Streamable HTTP primary; do not implement arbitrary stdio command execution.
  • Dify: External Knowledge compatible /retrieval endpoint.

Suggested package layout

apps/
  web/
  api/
  mcp-server/
  dify-adapter/
workers/
  import-worker/
  index-worker/
packages/
  auth/
  db/
  editor/
  markdown/
  milvus/
  permissions/
  retrieval/
  shared/
deploy/
  docker-compose/
  helm/
docs/
prompts/

Implementation discipline

  • Read docs/00-index.zh-CN.md, docs/18-decision-overrides-v0.3.zh-CN.md, docs/21-v0.3.2-clarifications.zh-CN.md, and docs/22-v0.3.3-clarifications.zh-CN.md before coding.
  • Implement in phases. Do not attempt the whole product in one patch.
  • Prefer domain services over controller-heavy logic.
  • Put authorization checks in service layer, not only in route handlers.
  • Write permission tests before convenience features.
  • Keep async jobs idempotent.
  • Keep editor behavior deterministic: Markdown in, Milkdown-normalized Markdown out.
  • Do not bypass the feature registry when adding editor features.
  • Do not add per-knowledge-base model configuration.
  • Instance-level model configuration is system_admin only; tenant_admin may inspect retrieval state but cannot save model settings or secrets.
  • Instance-level import tool configuration is system_admin only; tenant_admin and content owners cannot save MarkItDown/MinerU/Pandoc/OCR routes or secrets.
  • Treat share links as read-only only in v0.x; do not add link-edit capabilities.
  • Treat folders as documents.type = folder; do not create a separate folders table unless the spec is explicitly changed.
  • Do not use browser-native window.prompt, window.confirm, or window.alert for app interactions. Use OpenKB Web dialog components instead; beforeunload is the only allowed native prompt for browser tab close/refresh with unsaved drafts.
  • Admin-created accounts use a welcome setup-password email (account_setup) rather than a temporary password or generic reset message. Setup and reset links are one-time tokens; issuing a new setup/reset link invalidates older unused setup/reset links.

v0.3.3 clarifications

  • Workspace membership roles are owner/admin/member/guest and live in workspace_members.
  • Content collaborator roles are owner/manager/editor/viewer and live in collaborators for knowledge_base and document only.
  • Workspace invitations grant admin/member/guest; content invitations grant manager/editor/viewer; ordinary invitations do not grant owner.
  • Milvus collection primary key is id; chunk_id is a regular field. In v0.x both values equal the PostgreSQL document_chunks.id string.
  • Implement auth_settings, MCP OAuth/PAT tables, and Dify scoped API key tables from docs/07-data-model.zh-CN.md.
  • Do not implement knowledge-base-level embedding/rerank fallback provider secrets. Instance-level encrypted model secrets are allowed only through the system-admin Models control plane.