@kespace/ks-cli-openclaw 0.1.28

package/bin/ks

@@ -0,0 +1,2 @@
+#!/bin/sh
+exec "$HOME/.agents/skills/ks/bin/ks" "$@"

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@kespace/ks-cli-openclaw",
+  "version": "0.1.28",
+  "description": "KnowledgeSpace CLI + SKILL installer for OpenClaw",
+  "ksAgent": "openclaw",
+  "bin": {
+    "ks": "./bin/ks"
+  },
+  "scripts": {
+    "postinstall": "node ./scripts/postinstall.mjs",
+    "preuninstall": "node ./scripts/preuninstall.mjs"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "files": [
+    "bin/",
+    "binaries/",
+    "scripts/",
+    "skills/"
+  ],
+  "engines": {
+    "node": ">=16"
+  }
+}

package/scripts/agent-config.mjs

@@ -0,0 +1,53 @@
+import { join } from 'path';
+
+/** @typedef {'cc' | 'openclaw' | 'hermes' | 'kepaw'} AgentId */
+
+/** @type {Record<AgentId, { packageName: string, label: string, globalSkillsDirs: (home: string) => string[], projectSkillsDir: ((projectDir: string) => string) | null }>} */
+export const AGENTS = {
+  cc: {
+    packageName: '@ke/ks-cli',
+    label: 'Claude Code',
+    globalSkillsDirs: (home) => [join(home, '.claude', 'skills')],
+    projectSkillsDir: (projectDir) => join(projectDir, '.claude', 'skills'),
+  },
+  openclaw: {
+    packageName: '@ke/ks-cli-openclaw',
+    label: 'OpenClaw',
+    globalSkillsDirs: (home) => [join(home, '.openclaw', 'skills')],
+    projectSkillsDir: (projectDir) => join(projectDir, '.agents', 'skills'),
+  },
+  hermes: {
+    packageName: '@ke/ks-cli-hermes',
+    label: 'Hermes',
+    globalSkillsDirs: (home) => [join(home, '.hermes', 'skills')],
+    projectSkillsDir: null,
+  },
+  kepaw: {
+    packageName: '@ke/ks-cli-kepaw',
+    label: 'Kepaw',
+    globalSkillsDirs: (home) => [
+      join(home, '.kepaw', 'skills'),
+      join(home, '.kepaw', 'workspace', '.agents', 'skills'),
+    ],
+    projectSkillsDir: null,
+  },
+};
+
+/**
+ * @param {{ name?: string, ksAgent?: string }} pkgJson
+ * @returns {AgentId}
+ */
+export function resolveAgentId(pkgJson) {
+  if (pkgJson.ksAgent && AGENTS[pkgJson.ksAgent]) {
+    return /** @type {AgentId} */ (pkgJson.ksAgent);
+  }
+  const name = (pkgJson.name || '').toLowerCase();
+  if (name === '@ke/ks-cli' || name === '@kespace/ks-cli' || name.includes('ke-cc')) return 'cc';
+  if (name.includes('openclaw')) return 'openclaw';
+  if (name.includes('hermes')) return 'hermes';
+  if (name.includes('kepaw')) return 'kepaw';
+  throw new Error(
+    `ks: unknown agent package "${pkgJson.name || '(unnamed)'}". ` +
+    'Expected @ke/ks-cli or @kespace/ks-cli (and -openclaw / -hermes / -kepaw variants).',
+  );
+}

package/scripts/install-lib.mjs

@@ -0,0 +1,250 @@
+import {
+  copyFileSync,
+  mkdirSync,
+  symlinkSync,
+  unlinkSync,
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  chmodSync,
+  rmSync,
+} from 'fs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+import { AGENTS, resolveAgentId } from './agent-config.mjs';
+
+const SHARED_SKILL_DIR_NAME = 'ks';
+
+export function readPackageMeta(packageDir) {
+  const pkgJson = JSON.parse(readFileSync(join(packageDir, 'package.json'), 'utf8'));
+  const agentId = resolveAgentId(pkgJson);
+  const agent = AGENTS[agentId];
+  return {
+    agentId,
+    agent,
+    pkgName: pkgJson.name,
+    pkgVersion: pkgJson.version,
+  };
+}
+
+export function install(packageDir) {
+  const { agentId, agent, pkgName, pkgVersion } = readPackageMeta(packageDir);
+  const home = homedir();
+  const isGlobal = process.env.npm_config_global === 'true';
+  const projectDir = process.env.INIT_CWD || process.cwd();
+  const sharedSkillDir = join(home, '.agents', 'skills', SHARED_SKILL_DIR_NAME);
+
+  try { chmodSync(join(packageDir, 'bin', 'ks'), 0o755); } catch {}
+
+  ensureSharedSkill(packageDir, sharedSkillDir, pkgVersion);
+  registerRef(sharedSkillDir, agentId, pkgName, pkgVersion);
+  updateSkillLock(sharedSkillDir, pkgName, pkgVersion);
+
+  for (const skillsDir of agent.globalSkillsDirs(home)) {
+    linkSkillDir(sharedSkillDir, skillsDir);
+  }
+  console.log(`ks: ${agent.label} skill ready`);
+
+  if (!isGlobal && agent.projectSkillsDir) {
+    linkSkillDir(sharedSkillDir, agent.projectSkillsDir(projectDir));
+  }
+
+  if (!isGlobal) {
+    linkGlobalBin(home, sharedSkillDir);
+    injectLocalBinPath(home);
+  }
+
+  console.log('ks: Run `ks login <your-appkey>` to configure authentication.');
+  console.log('ks: Get your key at https://space.ke.com/tokens');
+}
+
+export function uninstall(packageDir) {
+  const { agentId, agent } = readPackageMeta(packageDir);
+  const home = homedir();
+  const isGlobal = process.env.npm_config_global === 'true';
+  const projectDir = process.env.INIT_CWD || process.cwd();
+  const sharedSkillDir = join(home, '.agents', 'skills', SHARED_SKILL_DIR_NAME);
+
+  for (const skillsDir of agent.globalSkillsDirs(home)) {
+    removeSkillSymlink(skillsDir);
+  }
+
+  if (!isGlobal && agent.projectSkillsDir) {
+    removeSkillSymlink(agent.projectSkillsDir(projectDir));
+  }
+
+  const refs = unregisterRef(sharedSkillDir, agentId);
+  if (Object.keys(refs).length === 0) {
+    try {
+      rmSync(sharedSkillDir, { recursive: true, force: true });
+      console.log(`ks: removed ${sharedSkillDir}`);
+    } catch {}
+    removeSkillLockEntry(home);
+  } else {
+    console.log(`ks: shared skill kept for other agents (${Object.keys(refs).join(', ')})`);
+  }
+}
+
+function ensureSharedSkill(packageDir, sharedSkillDir, pkgVersion) {
+  mkdirSync(join(sharedSkillDir, 'bin'), { recursive: true });
+
+  const installedVersion = getInstalledVersion(sharedSkillDir);
+  if (installedVersion === pkgVersion) {
+    return;
+  }
+
+  copyFileSync(join(packageDir, 'skills', 'SKILL.md'), join(sharedSkillDir, 'SKILL.md'));
+
+  const binaryName = resolveBinaryName();
+  if (binaryName) {
+    copyFileSync(join(packageDir, 'binaries', binaryName), join(sharedSkillDir, 'bin', 'ks'));
+    chmodSync(join(sharedSkillDir, 'bin', 'ks'), 0o755);
+  }
+
+  writeInstalledVersion(sharedSkillDir, pkgVersion);
+  const action = installedVersion
+    ? `upgraded ${installedVersion} → ${pkgVersion}`
+    : `installed @${pkgVersion}`;
+  console.log(`ks: ${action} → ${sharedSkillDir}`);
+}
+
+function resolveBinaryName() {
+  const os = process.platform;
+  const arch = process.arch;
+  if (os === 'darwin' && arch === 'arm64') return 'ks-darwin-arm64';
+  if (os === 'darwin') return 'ks-darwin-amd64';
+  if (os === 'linux') return 'ks-linux-amd64';
+  console.warn(`ks: unsupported platform ${os}/${arch}, skipping binary install`);
+  return null;
+}
+
+function linkSkillDir(sourceDir, skillsParentDir) {
+  mkdirSync(skillsParentDir, { recursive: true });
+  const symlinkPath = join(skillsParentDir, SHARED_SKILL_DIR_NAME);
+  try { unlinkSync(symlinkPath); } catch {}
+  symlinkSync(sourceDir, symlinkPath);
+  console.log(`ks: symlinked → ${symlinkPath}`);
+}
+
+function removeSkillSymlink(skillsParentDir) {
+  const symlinkPath = join(skillsParentDir, SHARED_SKILL_DIR_NAME);
+  try {
+    unlinkSync(symlinkPath);
+    console.log(`ks: removed ${symlinkPath}`);
+  } catch {}
+}
+
+function refsPath(sharedSkillDir) {
+  return join(sharedSkillDir, '.refs.json');
+}
+
+function readRefs(sharedSkillDir) {
+  const path = refsPath(sharedSkillDir);
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function writeRefs(sharedSkillDir, refs) {
+  try {
+    writeFileSync(refsPath(sharedSkillDir), JSON.stringify(refs, null, 2));
+  } catch {}
+}
+
+function registerRef(sharedSkillDir, agentId, pkgName, pkgVersion) {
+  const refs = readRefs(sharedSkillDir);
+  refs[agentId] = { package: pkgName, version: pkgVersion };
+  writeRefs(sharedSkillDir, refs);
+}
+
+function unregisterRef(sharedSkillDir, agentId) {
+  const refs = readRefs(sharedSkillDir);
+  delete refs[agentId];
+  writeRefs(sharedSkillDir, refs);
+  return refs;
+}
+
+function linkGlobalBin(home, sharedSkillDir) {
+  const globalBin = join(sharedSkillDir, 'bin', 'ks');
+  const localBinDir = join(home, '.local', 'bin');
+  const localBinLink = join(localBinDir, 'ks');
+
+  if (!existsSync(globalBin)) {
+    console.warn('ks: global binary not found, skipping bin link');
+    return;
+  }
+
+  mkdirSync(localBinDir, { recursive: true });
+  try { unlinkSync(localBinLink); } catch {}
+  symlinkSync(globalBin, localBinLink);
+  console.log(`ks: linked → ${localBinLink}`);
+}
+
+function injectLocalBinPath(home) {
+  const profiles = ['.zshrc', '.bashrc', '.bash_profile', '.profile'].map((f) => join(home, f));
+  const line = 'export PATH="$HOME/.local/bin:$PATH"';
+  const marker = '# added by ks (knowledgespace)';
+  const written = [];
+
+  for (const p of profiles) {
+    if (!existsSync(p)) continue;
+    const content = readFileSync(p, 'utf8');
+    if (content.includes('.local/bin')) continue;
+    try {
+      writeFileSync(p, `${content}\n${marker}\n${line}\n`);
+      written.push(p);
+    } catch {}
+  }
+
+  if (written.length > 0) {
+    console.log(`ks: PATH updated for ~/.local/bin in ${written.join(', ')}`);
+    console.log('ks: 请执行 source ~/.zshrc 或重开终端使配置生效');
+  }
+}
+
+function updateSkillLock(skillPath, pkgName, pkgVersion) {
+  const lockPath = join(homedir(), '.agents', '.skill-lock.json');
+  let lock = { version: 3, skills: {} };
+  if (existsSync(lockPath)) {
+    try { lock = JSON.parse(readFileSync(lockPath, 'utf8')); } catch {}
+  }
+  if (!lock.skills) lock.skills = {};
+  const now = new Date().toISOString();
+  lock.skills[SHARED_SKILL_DIR_NAME] = {
+    source: SHARED_SKILL_DIR_NAME,
+    sourceType: 'npm',
+    sourceUrl: `${pkgName}@${pkgVersion}`,
+    skillPath,
+    version: pkgVersion,
+    installedAt: lock.skills[SHARED_SKILL_DIR_NAME]?.installedAt || now,
+    updatedAt: now,
+  };
+  try { writeFileSync(lockPath, JSON.stringify(lock, null, 2)); } catch {}
+}
+
+function removeSkillLockEntry(home) {
+  const lockPath = join(home, '.agents', '.skill-lock.json');
+  if (!existsSync(lockPath)) return;
+  try {
+    const lock = JSON.parse(readFileSync(lockPath, 'utf8'));
+    if (lock.skills) delete lock.skills[SHARED_SKILL_DIR_NAME];
+    writeFileSync(lockPath, JSON.stringify(lock, null, 2));
+  } catch {}
+}
+
+function getInstalledVersion(skillDir) {
+  try {
+    return readFileSync(join(skillDir, '.version'), 'utf8').trim();
+  } catch {
+    return null;
+  }
+}
+
+function writeInstalledVersion(skillDir, version) {
+  try {
+    writeFileSync(join(skillDir, '.version'), version);
+  } catch {}
+}

package/scripts/postinstall.mjs

@@ -0,0 +1,6 @@
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { install } from './install-lib.mjs';
+
+const packageDir = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+install(packageDir);

package/scripts/preuninstall.mjs

@@ -0,0 +1,6 @@
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { uninstall } from './install-lib.mjs';
+
+const packageDir = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+uninstall(packageDir);

package/skills/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: ks
+description: >
+  Bridge CLI to the team's shared knowledge store via KnowledgeSpace API.
+  Team files, documentation, and shared project knowledge live on remote
+  shared storage; ks lets agents read, write, search, and execute there
+  as if working locally.
+  Use when accessing SHARED team files or knowledge — NOT for local files
+  (use Read/Write/Bash for local operations instead).
+  Use `ks list` to discover available spaces, then pass --space-root per command.
+  Triggers: "shared files", "team knowledge base", "project docs on server",
+  "shared storage", "team notes", "find in knowledge base",
+  "check the shared codebase", "read from team storage",
+  "upload to knowledge base", "delete from shared", "remove from team docs",
+  "clean up shared files", "overwrite on server".
+allowed-tools: Bash(ks:*)
+---
+
+# ks — KnowledgeSpace CLI
+
+Every command requires `--task-id` and `--space-root`:
+
+```bash
+ks list   # discover space names — no other flags needed
+```
+
+**`--task-id`**: scopes staleness tracking to a task. Pick a short stable ID (8 chars, e.g. `$(uuidgen | cut -c1-8)`) and **reuse the same ID for all ks calls within the same task**. Different tasks may use different IDs. Changing the ID mid-task means the server loses your read history — staleness warnings will stop working.
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `ks list` | List available spaces |
+| `ks read file <path>` | Read file — text/image/PDF/notebook auto-detected |
+| `ks read raw <path>` | Read full file without pagination |
+| `ks write file <path> <content>` | Write or append to file |
+| `ks write patch <path>` | Edit file via string replace — safer than full write |
+| `ks search <query>` | Search file contents or filenames |
+| `ks exec cmd "<cmd>"` | Run shell command on server |
+| `ks exec code "<code>" --lang python\|js\|bash` | Run code snippet on server |
+| `ks upload <paths...>` | Upload files or folders to space |
+| `ks delete <paths...>` | Delete files or folders from space |
+
+Run `ks <command> --help` for flag details.
+
+## Space Context
+
+Each space may contain an optional `SPACE.md` at its root. Read it first to understand what the space contains and how to search it effectively. **Never write or modify it** — it is maintained by the space owner.
+
+```bash
+ks read file SPACE.md --task-id <id> --space-root <space>
+```
+
+If the file does not exist (`FILE_NOT_FOUND`), proceed without it — `SPACE.md` is optional.
+
+### What SPACE.md typically contains
+
+- **Purpose** — what domain or topic this space covers
+- **Directory structure** — key subdirectories and what each holds
+- **Search hints** — useful keywords, terminology, or query patterns for this space
+
+## Non-obvious Behaviors
+
+### mtime conflict detection
+
+All write/patch commands accept `--mtime`. Pass the `mtime` from your last read response — the server returns `CONFLICT` instead of overwriting silently if the file changed in between. Always use it after reading.
+
+```bash
+out=$(ks read file script.py --task-id <id> --space-root <space> --json)
+mtime=$(echo "$out" | jq '.mtime')
+ks write patch script.py --task-id <id> --space-root <space> \
+  --old "old text" --new "new text" --mtime "$mtime"
+```
+
+### Response fields to act on
+
+| Field | When it appears | What to do |
+|-------|----------------|------------|
+| `hint` | Errors + truncated results | Follow it — gives exact recovery step or next `--offset` |
+| `warning` | After write/patch | File changed since your last read; re-read before writing |
+| `similar_files` | `FILE_NOT_FOUND` | Try these paths before retrying |
+| `unchanged: true` | Read with `--mtime` | File unchanged; skip processing |
+| `truncated: true` | Large result sets | Use `--offset` value from `hint` to page |
+| `lint.status` | After writing `.py`/`.js` | Check `lint.output` if `error` |
+
+### REPEATED_SEARCH_BLOCKED
+
+Running the same search 4 times in a row is blocked. You already have the information — stop re-searching and proceed with your task.
+
+### `ks write patch` errors
+
+- `OLD_STRING_NOT_FOUND` — `--old` text not present; re-read the file before retrying
+- `CONFLICT` — file changed since your `--mtime`; re-read and patch again
+
+## Temp Directory
+
+`.ks_tmp/` inside the space root is for scripts that must exist on disk before `ks exec cmd`. Excluded from search. Clean up after use.
+
+## Destructive Operations (Upload & Delete)
+
+Both `ks upload` and `ks delete` are destructive. They share the same confirmation pattern.
+
+### Agent Confirmation Rule (MANDATORY)
+
+Before calling any destructive command, you MUST follow this exact sequence — no shortcuts:
+
+1. **Preview first**: Run with `--dry-run`
+2. **Display results**: Show the user what will happen (files, sizes, types, targets)
+3. **Wait for explicit confirmation**: Ask yes/no. **Do NOT proceed even if the user previously expressed intent.** Prior statements like "delete these" or "upload them" are NOT confirmation.
+4. **Execute only after confirmation**: Run with `--yes`
+
+**Red flags — you are about to skip confirmation:**
+- Thinking "the user clearly wants this"
+- Treating an ambiguous reply as yes
+- Skipping dry-run because the operation "looks safe"
+- Proceeding because the user is repeating a prior request
+
+**What counts as confirmation:** Only an unambiguous "yes" (or "no") reply to the dry-run preview shown in step 2. If the reply is ambiguous, re-ask: "Please confirm yes or no."
+
+**What does NOT count as confirmation:**
+- Any message before the dry-run output was shown
+- Prior statements of intent ("delete those", "upload them")
+- Ambiguous replies: "go ahead", "sure", "ok", "sounds good", "proceed", "do it"
+- Conditional pre-authorizations ("if fewer than X files, just do it")
+
+---
+
+## Upload
+
+### Space Resolution Rule (MANDATORY)
+
+If the user says vague phrases like "upload to knowledge base", "upload to team docs", "save to shared storage" without specifying a space:
+1. Call `ks list` to discover available spaces
+2. Present the space list to the user with descriptions
+3. Ask the user to select a specific space
+4. Proceed only after the user explicitly names a space
+
+If the user does not specify a destination directory (`--dest-dir`):
+1. Ask the user which folder to upload to
+2. Suggest reasonable defaults based on file type or context
+3. Use `/` (root) only if the user explicitly agrees
+
+### Upload-specific confirmation
+
+Apply the [Agent Confirmation Rule](#agent-confirmation-rule-mandatory) with:
+- **Preview command**: `ks upload <paths> --space-root <space> --dest-dir <dir> --dry-run`
+- **Display**: file list, target space, target directory, total size
+- **Not confirmation**: user providing paths or destination without being asked after preview
+
+### Overwrite Rule (MANDATORY)
+
+If the initial upload returns conflicts (files already exist):
+1. Display the conflicting files to the user
+2. Ask for overwrite confirmation
+3. Only if user confirms, re-upload with `--overwrite`
+
+### Examples
+
+```bash
+# Preview (agent use)
+ks upload ./src --space-root myspace --dest-dir docs/ --dry-run
+
+# Upload after user confirms
+ks upload ./src --space-root myspace --dest-dir docs/ --yes
+
+# Overwrite after user confirms conflicts
+ks upload ./src --space-root myspace --dest-dir docs/ --yes --overwrite
+```
+
+## Delete
+
+### Delete-specific confirmation
+
+Apply the [Agent Confirmation Rule](#agent-confirmation-rule-mandatory) with:
+- **Preview command**: `ks delete <paths> --space-root <space> --dry-run`
+- **Display**: paths, types (file/folder), total items to be deleted
+- **Not confirmation**: user listing paths to delete without being asked after preview
+
+Deletion is destructive and cannot be undone. Never skip confirmation.
+
+### What can be deleted
+
+`ks delete` removes files and folders that were created via the files API (`ks upload` or the web file manager). Files created by `ks write` (tools API) do not have database records and cannot be deleted with this command — use `ks exec cmd "rm ..."` for those.
+
+### Examples
+
+```bash
+# Preview (agent use)
+ks delete docs/old/ temp.txt --space-root myspace --dry-run
+
+# Delete after user confirms
+ks delete docs/old/ temp.txt --space-root myspace --yes
+```