@aikdna/kdna-cli 0.15.0 → 0.16.0

package/README.md

@@ -4,24 +4,24 @@
 
 KDNA CLI 是 AI Agent 加载、验证、组合、测试和治理领域判断的运行控制平面。
 
-CLI 不是 Studio，不是 Chat，不是 Governance Console。它是这些产品共同依赖的底层协议接口。
-
 Part of the [KDNA](https://github.com/knowledge-dna/KDNA) ecosystem.
 
 ## Install
 
 ```bash
 npm install -g @aikdna/kdna-cli
+kdna setup
 ```
 
-## Quick Start
+## Quick Start (5 minutes)
 
 ```bash
-kdna install @aikdna/writing    # Install a domain
-kdna verify @aikdna/writing     # 3-layer verification
-kdna available                  # List installed domains
-kdna match "improve this post"  # Find relevant domains
-kdna load @aikdna/writing       # Load for agent consumption
+npm install -g @aikdna/kdna-cli
+kdna setup
+kdna install @aikdna/writing
+kdna verify @aikdna/writing --judgment
+kdna compare @aikdna/writing --input "help me improve this post"
+kdna doctor --agents
 ```
 
 ## Commands by Role
@@ -34,7 +34,8 @@ kdna load @aikdna/writing       # Load for agent consumption
 | `kdna validate <path>` | Validate domain structure |
 | `kdna validate --schema <path>` | Schema-only validation |
 | `kdna pack <path>` | Pack into .kdna container |
-| `kdna unpack <file>` | Unpack .kdna container |
+| `kdna pack <path> --encrypt --license <file>` | Pack encrypted .kdnae container |
+| `kdna unpack <file>` | Unpack .kdna or .kdnae container |
 | `kdna inspect <path>` | Inspect domain or .kdna file |
 | `kdna publish <path>` | Pack + sign + publish to registry |
 | `kdna publish --check <path>` | Quality gate check only |
@@ -47,15 +48,42 @@ kdna load @aikdna/writing       # Load for agent consumption
 | `kdna available [--json]` | List installed domains with v2.1 fields |
 | `kdna match "<task>" [--json]` | Signal matching — find relevant domains |
 | `kdna load <name> [--as=prompt\|json\|raw]` | Emit domain in agent-ready format |
+| `kdna postvalidate <name> --output <file>` | Post-generation judgment check |
 
 ### Testing & Verification
 
 | Command | Description |
 |---------|-------------|
-| `kdna verify <name>` | 3-layer verification: structure + trust + judgment |
+| `kdna verify <name>` | 3-layer: structure + trust + judgment |
 | `kdna compare <name> --input "..."` | With/without KDNA reasoning diff |
+| `kdna compare <name> --input "..." --report-md` | Markdown report with scoring |
+| `kdna compare <name> --input "..." --report-json` | JSON report with scoring |
 | `kdna diff <name>@<v1> <name>@<v2>` | Judgment-level diff between versions |
-| `kdna doctor` | Check runtime environment health |
+
+### Diagnostics & Trace
+
+| Command | Description |
+|---------|-------------|
+| `kdna doctor` | System health check |
+| `kdna doctor --agents` | Agent integration check (Codex/Claude/OpenCode/Cursor/Gemini) |
+| `kdna doctor --json` | Machine-readable health report |
+| `kdna trace` | View recent load/postvalidate traces |
+| `kdna trace --json` | Machine-readable trace output |
+| `kdna trace --export <file>` | Export traces for audit |
+| `kdna trace --since 7d\|30d\|90d` | Filter by time range |
+| `kdna history` | Recent domain usage (last 20) |
+| `kdna history --stats` | Aggregate by domain and agent |
+| `kdna history --domain <name>` | Filter by domain |
+
+### License & Authorization
+
+| Command | Description |
+|---------|-------------|
+| `kdna license generate <domain> --to <email>` | Generate signed license |
+| `kdna license install <license.json>` | Register license for auto-decrypt |
+| `kdna license verify <license.json>` | Verify license signature and validity |
+| `kdna license bind <license.json>` | Bind license to this machine |
+| `kdna license show <license.json>` | Display license details |
 
 ### Cluster Composition
 
@@ -68,6 +96,8 @@ kdna load @aikdna/writing       # Load for agent consumption
 | Command | Description |
 |---------|-------------|
 | `kdna install <name>` | Install domain from registry |
+| `kdna install ./file.kdna` | Install from local .kdna file |
+| `kdna install ./file.kdnae` | Install from encrypted .kdnae (auto-decrypt with license) |
 | `kdna remove <name>` | Uninstall a domain |
 | `kdna update <name>` | Update installed domain |
 | `kdna info <name>` | Show domain metadata and trust status |
@@ -90,6 +120,14 @@ kdna load @aikdna/writing       # Load for agent consumption
 |---------|-------------|
 | `kdna setup` | One-command setup: CLI + skill + data root |
 
+### Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `KDNA_AGENT` | Override agent name in trace logs (e.g. `claude_code`, `codex`, `opencode`) |
+| `KDNA_REGISTRY_URL` | Override canonical registry URL |
+| `KDNA_IDENTITY_DIR` | Override identity key directory |
+
 ## Exit Codes
 
 | Code | Name | Meaning |
@@ -111,10 +149,10 @@ Machine-consumable commands support `--json` for structured output:
 ```bash
 kdna verify @aikdna/writing --json
 kdna available --json
-kdna match "help me write" --json
-kdna search writing --json
-kdna info @aikdna/writing --json
-kdna doctor --json
+kdna doctor --agents --json
+kdna trace --json
+kdna history --json
+kdna license verify --json <file>
 ```
 
 ## Product Matrix
@@ -123,14 +161,12 @@ kdna doctor --json
 |-------|---------|---------------|
 | Protocol | KDNA SPEC | Define judgment asset format |
 | Core Library | @aikdna/kdna-core | load / validate / compose / render |
-| Runtime | @aikdna/kdna-cli | Agent runtime + compile + verify + test + publish |
+| Runtime | @aikdna/kdna-cli | Agent runtime + compile + verify + test + publish + license |
 | Authoring | KDNA Studio | Human-led judgment production |
 | Consumption | KDNAChat | Load, use, compare |
 | Governance | KDNA Governance Console | Approve, release, audit |
 | Distribution | Registry | Discover, install, trade |
 
-CLI 不应该成为一个"命令行 Studio"，而是所有 KDNA 产品共同依赖的协议控制平面。
-
 ## Development
 
 ```bash
@@ -144,6 +180,7 @@ npm test
 
 - [@aikdna/kdna-core](https://github.com/knowledge-dna/KDNA/tree/main/packages/kdna-core) — Pure logic library
 - [KDNA Registry](https://github.com/knowledge-dna/kdna-registry) — Domain catalog
+- [KDNA SPEC](https://github.com/knowledge-dna/KDNA) — Protocol specification
 - [aikdna.com](https://aikdna.com) — Website
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aikdna/kdna-cli",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "KDNA CLI — create, validate, install, and manage domain cognition packages for AI agents.",
   "type": "commonjs",
   "bin": {

package/src/agent.js

@@ -34,6 +34,10 @@ const path = require('path');
 const { parseName } = require('./registry');
 const { recordTrace } = require('./cmds/trace');
 
+function detectAgent() {
+  return process.env.KDNA_AGENT || 'cli';
+}
+
 const USER_KDNA_DIR = path.join(process.env.HOME || process.env.USERPROFILE || '.', '.kdna');
 const INSTALL_DIR = path.join(USER_KDNA_DIR, 'domains');
 
@@ -367,7 +371,7 @@ function cmdLoad(input, args = []) {
   // JSON format
   if (format === 'json') {
     process.stdout.write(JSON.stringify({ manifest, core, patterns: pat }, null, 2) + '\n');
-    recordTrace({ timestamp: new Date().toISOString(), agent: 'cli', domain: parsed.full, format: 'json' });
+    recordTrace({ timestamp: new Date().toISOString(), agent: detectAgent(), domain: parsed.full, format: 'json' });
     return;
   }
 
@@ -380,20 +384,20 @@ function cmdLoad(input, args = []) {
         process.stdout.write(fs.readFileSync(p, 'utf8'));
       }
     }
-    recordTrace({ timestamp: new Date().toISOString(), agent: 'cli', domain: parsed.full, format: 'raw' });
+    recordTrace({ timestamp: new Date().toISOString(), agent: detectAgent(), domain: parsed.full, format: 'raw' });
     return;
   }
 
   // Load profiles
   if (profile) {
     emitProfile(parsed, manifest, core, pat, profile, profileInput);
-    recordTrace({ timestamp: new Date().toISOString(), agent: 'cli', domain: parsed.full, format: `profile:${profile}` });
+    recordTrace({ timestamp: new Date().toISOString(), agent: detectAgent(), domain: parsed.full, format: `profile:${profile}` });
     return;
   }
 
   // Default: --as=prompt — compact text optimized for system-prompt injection.
   emitCompact(parsed, manifest, core, pat);
-  recordTrace({ timestamp: new Date().toISOString(), agent: 'cli', domain: parsed.full, format: 'prompt' });
+  recordTrace({ timestamp: new Date().toISOString(), agent: detectAgent(), domain: parsed.full, format: 'prompt' });
 }
 
 // ─── Load profiles ─────────────────────────────────────────────────────
@@ -821,7 +825,7 @@ function cmdPostvalidate(args = []) {
     console.log(JSON.stringify(result, null, 2));
     recordTrace({
       timestamp: new Date().toISOString(),
-      agent: 'cli',
+      agent: detectAgent(),
       domain: parsed.full,
       type: 'postvalidate',
       postvalidate: { result: results.violations.length ? 'fail' : 'pass', violations: results.violations.length, passed: results.passed.length },
@@ -851,7 +855,7 @@ function cmdPostvalidate(args = []) {
 
   recordTrace({
     timestamp: new Date().toISOString(),
-    agent: 'cli',
+    agent: detectAgent(),
     domain: parsed.full,
     type: 'postvalidate',
     postvalidate: { result: results.violations.length ? 'fail' : 'pass', violations: results.violations.length, passed: results.passed.length },

package/src/cmds/license.js

@@ -81,7 +81,9 @@ function cmdLicenseGenerate(args) {
 }
 
 function cmdLicenseVerify(args) {
-  const licensePath = args[0];
+  const jsonMode = args.includes('--json');
+  const filtered = args.filter(a => !a.startsWith('--'));
+  const licensePath = filtered[0];
   if (!licensePath) error('Usage: kdna license verify <license.json>', EXIT.INPUT_ERROR);
 
   let license;
@@ -96,8 +98,6 @@ function cmdLicenseVerify(args) {
   const fp = machineFingerprint();
   const result = verifyLicense(license, publicKey, fp);
 
-  const jsonMode = args.includes('--json');
-
   if (jsonMode) {
     console.log(JSON.stringify({
       domain: license.domain,
@@ -135,7 +135,8 @@ function cmdLicenseVerify(args) {
 }
 
 function cmdLicenseBind(args) {
-  const licensePath = args[0];
+  const filtered = args.filter(a => !a.startsWith('--'));
+  const licensePath = filtered[0];
   if (!licensePath) error('Usage: kdna license bind <license.json>', EXIT.INPUT_ERROR);
 
   let license;
@@ -165,7 +166,8 @@ function cmdLicenseBind(args) {
 }
 
 function cmdLicenseShow(args) {
-  const licensePath = args[0];
+  const filtered = args.filter(a => !a.startsWith('--'));
+  const licensePath = filtered[0];
   if (!licensePath) {
     const local = path.join(process.cwd(), 'license.json');
     if (fs.existsSync(local)) return cmdLicenseVerify([local, ...args.slice(1)]);