AI Knowledge Center

Local AI workflow dashboard for project knowledge, gate metadata, commands, and Markdown previews.

It is designed to be installed as a single global npm CLI. After installation, one command starts one HTTP server that serves both the UI and API from the same port.

Features

• Project menu with search and status filters.
• Document-first workspace with project context kept in a side panel.
• Focused project context view for Git status, knowledge assets, MCP, telemetry, Dagger, gates, and commands.
• Knowledge list sorted by references, updated time, or created time.
• Knowledge search and Markdown preview.
• Gate and command declarations are displayed as metadata for humans; automation and AI agents can consume the API separately.
• Single exposed port in production: UI and /api/* are served by Fastify.

Install

From npm:

npm install -g ai-knowledge-center

From a local checkout:

cd C:\Users\youni\Documents\GitHub\ai-knowledge-center
npm install
npm run build
npm install -g .

Verify the CLI:

aikc --help

One-Command Project Setup

Copy this complete one-sentence prompt to an AI Agent while it is working in the target project directory, including projects that do not have .aikc or ai-knowledge yet:

In this target project directory, initialize or upgrade the AI Knowledge Center workflow by first actively trying to update the global CLI with `npm install -g ai-knowledge-center@latest`, if that fails because of permission or locked files run `aikc stop` and retry `npm install -g ai-knowledge-center@latest` once, if it still fails report the failure and give the user the manual retry commands `aikc stop`, `npm install -g ai-knowledge-center@latest`, and `aikc`, then run `aikc upgrade --project . --write --ai` or `npx -y ai-knowledge-center@latest upgrade --project . --write --ai` if the global `aikc` command is unavailable, read `ai-knowledge/LOAD.md`, `ai-knowledge/core/LOAD.md`, and `ai-knowledge/ai/LOAD.md` when present, read `.aikc/upgrade/AI_UPGRADE_PROMPT.md` if it exists, semantically merge any `*.aikc-upgrade.md` candidates without overwriting human docs, config, package scripts, existing AI workflows, or uncommitted work, keep AIKC-maintained workflow in `ai-knowledge/core`, keep AI workflow scripts in `ai-knowledge/scripts` with human usage notes in `ai-knowledge/scripts/README.md` instead of polluting the host `package.json`, keep project-specific reusable knowledge in `ai-knowledge/skills` or project references, follow `ai-knowledge/core/script-automation-policy.md`, `ai-knowledge/core/token-efficiency.md`, `ai-knowledge/core/project-capabilities.md`, `ai-knowledge/core/open-source-usage.md`, `ai-knowledge/core/code-review-policy.md`, and `ai-knowledge/core/human-friendly-task-summary.md`, run `node ai-knowledge/scripts/doctor.cjs --json`, `node ai-knowledge/scripts/eval-workflow.cjs`, `node ai-knowledge/scripts/code-review.cjs`, `node ai-knowledge/scripts/knowledge-check.cjs`, and all applicable gates until they pass, and make the final reply include changed files, global CLI update result, code review result, validation, remaining risk, knowledge-capture decision, and reusable automation/token-efficiency decision when applicable.

The command embedded in the prompt is:

npx -y ai-knowledge-center@latest upgrade --project . --write --ai

Update Another Project Workflow

Copy this one-sentence prompt to an AI Agent while it is working in any target project directory to update that project's AIKC workflow to the latest package templates:

In this target project directory, initialize or upgrade the AI Knowledge Center workflow by first actively trying to update the global CLI with `npm install -g ai-knowledge-center@latest`, if that fails because of permission or locked files run `aikc stop` and retry `npm install -g ai-knowledge-center@latest` once, if it still fails report the failure and give the user the manual retry commands `aikc stop`, `npm install -g ai-knowledge-center@latest`, and `aikc`, then run `aikc upgrade --project . --write --ai` or `npx -y ai-knowledge-center@latest upgrade --project . --write --ai` if the global `aikc` command is unavailable, read `ai-knowledge/LOAD.md`, `ai-knowledge/core/LOAD.md`, and `ai-knowledge/ai/LOAD.md` when present, read `.aikc/upgrade/AI_UPGRADE_PROMPT.md` if it exists, semantically merge any `*.aikc-upgrade.md` candidates without overwriting human docs, config, package scripts, existing AI workflows, or uncommitted work, keep AIKC-maintained workflow in `ai-knowledge/core`, keep AI workflow scripts in `ai-knowledge/scripts` with human usage notes in `ai-knowledge/scripts/README.md` instead of polluting the host `package.json`, keep project-specific reusable knowledge in `ai-knowledge/skills` or project references, follow `ai-knowledge/core/script-automation-policy.md`, `ai-knowledge/core/token-efficiency.md`, `ai-knowledge/core/project-capabilities.md`, `ai-knowledge/core/open-source-usage.md`, `ai-knowledge/core/code-review-policy.md`, and `ai-knowledge/core/human-friendly-task-summary.md`, run `node ai-knowledge/scripts/doctor.cjs --json`, `node ai-knowledge/scripts/eval-workflow.cjs`, `node ai-knowledge/scripts/code-review.cjs`, `node ai-knowledge/scripts/knowledge-check.cjs`, and all applicable gates until they pass, and make the final reply include changed files, global CLI update result, code review result, validation, remaining risk, knowledge-capture decision, and reusable automation/token-efficiency decision when applicable.

This generates the AIKC workflow in the current project:

• ai-knowledge/core/** for AIKC-maintained core workflow;
• ai-knowledge/skills/** for project-owned reusable skills;
• ai-workflow.yaml, AGENTS.md, and internal AI workflow scripts under ai-knowledge/scripts;
• .aikc/upgrade/AI_UPGRADE_PROMPT.md for semantic merge guidance.
• a user-level registry entry in ~/.ai-knowledge-center/config/projects.json so the dashboard can find the project after initialization.
• a closeout rule that asks the Agent to package repeated operations as scripts, skills, MCP/server tools, or references when doing so reduces future token and command-discovery cost.
• ai-knowledge/core/token-efficiency.md with rules for minimal context loading, summaries before raw logs, structured output, caches, operations indexes, doctor commands, and compact closeout.
• ai-knowledge/core/bounded-loop-policy.md with rules that Agent loops must define input, output, validation, budget, stop condition, and human escalation.
• ai-knowledge/core/human-readable-knowledge-policy.md with the two-layer knowledge rule: compact AI-facing knowledge first, human-readable companions under ai-knowledge/human/** only when meaning changes or missing companions are backfilled.
• ai-knowledge/core/project-capabilities.md with AIKC manifest, dashboard, gates, commands, MCP, telemetry, Dagger, API automation, project discovery, upgrade, and release behavior.
• ai-knowledge/scripts/doctor.cjs, context-pack.cjs, and eval-workflow.cjs for compact diagnostics, token-aware context planning, and workflow smoke evals.
• ai-workflow.yaml loops metadata for bounded task, upgrade, and release workflows.
• ai-knowledge/core/open-source-usage.md with rules for preferring mature packages over custom implementations when doing so improves reliability and reduces repeated agent work.
• ai-knowledge/core/code-review-policy.md with rules that code review and all applicable gates must pass before completion.

When an operation will be repeated, ask the Agent to package it with explicit local host OS and remote target OS boundaries. Use scripts for deterministic command sequences, skills for judgment-heavy workflows, and MCP/server tools for structured repeated operations.

When a task wastes context, ask the Agent to follow ai-knowledge/core/token-efficiency.md and prefer summaries, structured tool output, caches, operations indexes, or doctor commands instead of rereading large files or logs.

When a task creates or changes an Agent loop, ask the Agent to follow ai-knowledge/core/bounded-loop-policy.md so the loop has clear inputs, outputs, validation, budget, stop condition, and human escalation.

When a task changes AI-facing knowledge or skills, ask the Agent to follow ai-knowledge/core/human-readable-knowledge-policy.md: keep Agent files compact, update the human-readable companion only when meaning changes, and backfill missing companions under ai-knowledge/human/**.

When a task touches AIKC setup or dashboard behavior, ask the Agent to follow ai-knowledge/core/project-capabilities.md before changing manifests, gates, MCP, telemetry, Dagger, API automation, project discovery, upgrade behavior, or release flow.

When maintaining older projects, run the latest upgrade command again. AIKC safely adds missing workflow files, scripts, human-readable companions, evals, and manifest commands/gates/loops without overwriting project-specific knowledge. Differing files still become *.aikc-upgrade.md candidates for semantic merge.

When a task would require hand-rolled infrastructure, ask the Agent to follow ai-knowledge/core/open-source-usage.md and evaluate mature packages first.

After setup, normal project work starts with:

按 ai-knowledge/LOAD.md 执行, 任务：<一句话描述任务>

Start

Run the global CLI from anywhere. By default this starts the server in the background and keeps request logs quiet:

aikc

Open:

http://127.0.0.1:4318

The production CLI exposes only one port. The same server serves:

• http://127.0.0.1:4318/ for the SPA UI
• http://127.0.0.1:4318/api/health for health
• http://127.0.0.1:4318/api/projects for project data

Use another port:

aikc --port 5188

Run in the current terminal for debugging:

aikc --foreground --log-level info

Stop the background server:

aikc stop

Bind another host:

aikc --host 0.0.0.0 --port 4318

Start AI Knowledge Center automatically when you log in:

aikc autostart install

Check or remove the startup entry:

aikc autostart status
aikc autostart uninstall

Autostart is supported on Windows and macOS. It starts the same local CLI with any startup options you pass to autostart install, such as --port, --projects, or --config-dir.

Configure Projects

The CLI loads projects in this order:

1. --projects or AIKC_PROJECTS
2. --config-dir or AIKC_CONFIG_DIR
3. ~/.ai-knowledge-center/config/projects.json
4. Auto-discovery from the current working directory, --workspace / AIKC_WORKSPACE, and common local code folders such as ~/Documents/GitHub, ~/Documents/Projects, ~/GitHub, ~/Projects, and ~/source/repos

Auto-discovery accepts a project root itself or one direct child folder containing ai-workflow.yaml, ai-workflow.yml, or ai-knowledge/LOAD.md.

aikc upgrade --project . --write --ai also registers the target project in ~/.ai-knowledge-center/config/projects.json without replacing existing entries. This is the preferred persistent discovery path for initialized projects.

Option 1: Pass Projects Directly

aikc --projects "C:/Users/youni/Documents/GitHub/dota-legion-clean;C:/Users/youni/Documents/GitHub/my-tool"

PowerShell environment variable:

$env:AIKC_PROJECTS = "C:/repo/a;C:/repo/b"
aikc

Option 2: Use config/projects.json

Create ~/.ai-knowledge-center/config/projects.json:

{
  "projects": [
    {
      "path": "C:/Users/youni/Documents/GitHub/dota-legion-clean"
    },
    {
      "path": "C:/Users/youni/Documents/GitHub/my-new-ai-project",
      "id": "my-new-ai-project",
      "name": "My New AI Project",
      "description": "AI workflow project",
      "packageManager": "npm"
    }
  ]
}

Run with an explicit workspace:

aikc --workspace C:\Users\youni\Documents\GitHub

Run with an explicit config directory:

aikc --config-dir C:\Users\youni\Documents\GitHub\ai-config

Project Manifest

Each project can expose knowledge, gates, commands, dashboard links, MCP, telemetry, and Dagger through ai-workflow.yaml.

Minimal example:

schemaVersion: 1
id: my-project
name: My Project
knowledge:
  load: ai-knowledge/LOAD.md
  core: ai-knowledge/core
  aiLoad: ai-knowledge/ai/LOAD.md
  skills: ai-knowledge/skills
  skillIndex: ai-knowledge/skills/SKILL_INDEX.md
  closeoutPrompt: ai-knowledge/core/LOAD-END.md
  agentsFile: AGENTS.md
gates:
  - id: typecheck
    label: Typecheck
    script: typecheck
    packageManager: npm
    category: typecheck
commands:
  - id: closeout
    label: AI Closeout
    script: ai:closeout
    packageManager: npm
dashboard:
  watch:
    - ai-knowledge
    - src
  links:
    - label: Repo
      url: https://github.com/example/my-project

Use command when you need exact shell control:

gates:
  - id: tests
    label: Tests
    command: pnpm test
    category: test

Use dangerous: true for commands that should require explicit confirmation when called through the API:

commands:
  - id: deploy
    label: Deploy
    command: pnpm deploy
    dangerous: true

Upgrade Existing Projects

Use the CLI as a scanner and distributor. Let an AI Agent do the semantic merge when a project already has templates, skills, prompts, or reply rules.

From inside the target project, give the Agent this complete one-sentence prompt:

In this target project directory, initialize or upgrade the AI Knowledge Center workflow by first actively trying to update the global CLI with `npm install -g ai-knowledge-center@latest`, if that fails because of permission or locked files run `aikc stop` and retry `npm install -g ai-knowledge-center@latest` once, if it still fails report the failure and give the user the manual retry commands `aikc stop`, `npm install -g ai-knowledge-center@latest`, and `aikc`, then run `aikc upgrade --project . --write --ai` or `npx -y ai-knowledge-center@latest upgrade --project . --write --ai` if the global `aikc` command is unavailable, read `ai-knowledge/LOAD.md`, `ai-knowledge/core/LOAD.md`, and `ai-knowledge/ai/LOAD.md` when present, read `.aikc/upgrade/AI_UPGRADE_PROMPT.md` if it exists, semantically merge any `*.aikc-upgrade.md` candidates without overwriting human docs, config, package scripts, existing AI workflows, or uncommitted work, keep AIKC-maintained workflow in `ai-knowledge/core`, keep AI workflow scripts in `ai-knowledge/scripts` with human usage notes in `ai-knowledge/scripts/README.md` instead of polluting the host `package.json`, keep project-specific reusable knowledge in `ai-knowledge/skills` or project references, follow `ai-knowledge/core/script-automation-policy.md`, `ai-knowledge/core/token-efficiency.md`, `ai-knowledge/core/project-capabilities.md`, `ai-knowledge/core/open-source-usage.md`, `ai-knowledge/core/code-review-policy.md`, and `ai-knowledge/core/human-friendly-task-summary.md`, run `node ai-knowledge/scripts/doctor.cjs --json`, `node ai-knowledge/scripts/eval-workflow.cjs`, `node ai-knowledge/scripts/code-review.cjs`, `node ai-knowledge/scripts/knowledge-check.cjs`, and all applicable gates until they pass, and make the final reply include changed files, global CLI update result, code review result, validation, remaining risk, knowledge-capture decision, and reusable automation/token-efficiency decision when applicable.

Dry-run first:

aikc upgrade --project C:\Users\youni\Documents\GitHub\dota-legion-clean

Apply safe scaffolding and write upgrade candidates:

aikc upgrade --project C:\Users\youni\Documents\GitHub\dota-legion-clean --write

This command:

• creates missing AI workflow files;
• keeps existing project files unchanged when they differ;
• writes candidate files next to conflicts as *.aikc-upgrade.md;
• writes .aikc/upgrade/AI_UPGRADE_PROMPT.md for the Agent;
• registers the project in ~/.ai-knowledge-center/config/projects.json without replacing existing entries;
• merges missing package.json scripts without replacing existing scripts.

If you already ran the command and only need the semantic merge step, ask the Agent in that project:

Read .aikc/upgrade/AI_UPGRADE_PROMPT.md and upgrade this project's AI knowledge workflow by semantic merge.

After a project has the current template, normal task invocation also performs an automatic safe update. When the user says:

按 ai-knowledge/LOAD.md 执行, 任务：...

the Agent reads ai-knowledge/ai/LOAD.md and runs:

node ai-knowledge/scripts/ensure-aikc-cli.cjs --upgrade
node ai-knowledge/scripts/ai-workflow-start.cjs --task "<任务一句话>"

ensure-aikc-cli.cjs --upgrade checks whether the global aikc CLI exists and is current, actively tries to install or update it when needed, stops and restarts a running background Web process around the update, prints manual retry commands if npm global update still fails, then runs:

aikc upgrade --project . --write

If an aikc background Web process is already running when the global CLI is updated, the ensure script restarts that process automatically so the dashboard serves the newly installed version.

This keeps ongoing projects fresh without overwriting existing knowledge templates. Conflicts become *.aikc-upgrade.md candidates plus .aikc/upgrade/AI_UPGRADE_PROMPT.md for AI semantic merge.

Use --ai to force writing the handoff prompt even when no conflicts are detected:

aikc upgrade --project C:\repo\app --write --ai

--force exists for rare maintenance cases, but it overwrites conflicting templates after writing backups. Prefer AI semantic merge for real projects.

CLI Options

  aikc [options]
  aikc stop
  aikc autostart <install|uninstall|status> [options]
  aikc upgrade --project <path> [--write] [--ai] [--force]

Options:
  --host <host>          Bind host. Default: 127.0.0.1
  --port <port>          HTTP port. Default: 4318
  --projects <paths>     Project paths separated by semicolon or newline
  --workspace <path>     Workspace root used for project auto-discovery. Default: user home
  --config-dir <path>    Directory containing projects.json
  --log-level <level>    Fastify log level. Default: warn
  --foreground           Run the server in the current terminal for debugging
  --help                 Show help

Autostart:
  install                Start AI Knowledge Center when the user logs in
  uninstall              Remove the login startup entry
  status                 Show whether the startup entry exists

Upgrade options:
  --project <path>       Target project root. Default: current directory
  --write                Create missing files, candidate templates, and an AI handoff prompt
  --ai                   Write the AI handoff prompt even when no conflict is detected
  --force                Overwrite conflicting templates after writing backups; use rarely

Environment variables:

| Variable | Purpose | | --- | --- | | AIKC_HOST | Bind host | | AIKC_PORT | HTTP port | | AIKC_PROJECTS | Semicolon or newline separated project paths | | AIKC_HOME | AIKC state root. Default: ~/.ai-knowledge-center | | AIKC_WORKSPACE | Workspace root for project auto-discovery. Default: user home | | AIKC_CONFIG_DIR | Directory containing projects.json | | AIKC_LOG_LEVEL | Fastify log level. Default: warn | | AIKC_TELEMETRY_EXPORTER | Set to none to disable telemetry export | | AIKC_TELEMETRY_SERVICE_NAME | OpenTelemetry service name |

Development

Development uses two local processes because Vite provides HMR:

npm install
npm run dev

Open:

http://127.0.0.1:5177

In development only:

• Vite serves the SPA on 5177
• Fastify serves the API on 4318
• Vite proxies /api to Fastify

Production/global install uses one port.

Build

npm run build

This creates:

• dist/client for the SPA
• dist/server for Fastify
• dist/cli/aikc.js for the global CLI

Run the built version locally:

npm start -- --port 4318

Publish

Before publishing:

npm run typecheck
npm run lint
npm run build
npm pack --dry-run

Publish:

npm publish

After publishing:

npm install -g ai-knowledge-center
aikc

API

Useful endpoints:

GET  /api/health
GET  /api/projects
GET  /api/projects/:projectId
GET  /api/projects/:projectId/knowledge?sort=references
GET  /api/projects/:projectId/knowledge/search?q=keyword
GET  /api/projects/:projectId/knowledge/preview?path=ai-knowledge/LOAD.md
POST /api/projects/:projectId/run/:commandId

The UI is intentionally document-first and does not expose manual run buttons. The run endpoint remains available for trusted local automation or AI workflows that already understand the project manifest.

Notes

• The tool reads project files from local checkouts; it does not copy knowledge into an internal database.
• Command execution is allowlisted by each project's manifest.
• Global install defaults to the directory where aikc is executed, not the package installation directory.
• Use --host 0.0.0.0 only when you intentionally want LAN access.