@xiaoailazy/coexistree-cli 0.2.0

package/README.md

@@ -0,0 +1,73 @@
+# @xiaoailazy/coexistree-cli
+
+CoExistree **Agent CLI**：产研任务、系统提问。配合 [`@xiaoailazy/coexistree-skills`](../skills) 供各类 Agent 使用。
+
+## 安装
+
+```bash
+npm install -g @xiaoailazy/coexistree-cli
+```
+
+一键（CLI + Skills）：`npm install -g @xiaoailazy/coexistree`
+
+本地开发：
+
+```bash
+cd packages/cli && npm install && npm link
+```
+
+## 配置（推荐）
+
+在 Web **密钥管理** 开启并复制 Agent Key，并确认目标系统的 **system code**。
+
+```bash
+coexistree config initial \
+  --api-key "ce_从Web复制" \
+  --system-code "order-service" \
+  --base-url http://localhost:8080
+```
+
+写入 **`~/.coexistree/config.json`**（权限 `600`）。之后所有子命令自动读取，**无需** `--env-file`。
+
+| 子命令 | 说明 |
+|--------|------|
+| `config initial` | 创建/覆盖配置（已有文件需 `--force`） |
+| `config show` | 查看配置（api-key 脱敏） |
+| `config path` | 打印配置文件路径 |
+| `task create` | 创建任务并上传需求 `.md` |
+| `task list` | 任务列表（`scope`: 待开发 / 待补用例） |
+| `task pull` | 拉取 REQUIREMENT / DESIGN / TEST_CASE 到本地 |
+| `task upload` | 上传 DESIGN / TEST_CASE（必填 `.md` 路径） |
+| `ask` | 向系统提问 |
+
+自定义路径：`coexistree --config /path/to/config.json ...`
+
+### 覆盖优先级（高→低）
+
+1. 已存在的环境变量  
+2. `--env-file`（仅填充尚未设置的变量）  
+3. 配置文件  
+4. 全局 `--base-url`
+
+## 使用
+
+```bash
+coexistree task create --title "迭代 1" docs/req.md
+coexistree task list
+coexistree task pull --task-id 42 --doc-type REQUIREMENT
+coexistree task upload --task-id 42 --doc-type DESIGN docs/superpowers/specs/...-design.md
+
+coexistree ask --question "变更批次失败时有哪些 stage？"
+```
+
+上传需求/设计**不会**自动合并进知识树；合并在 Web 对任务执行「应用变更」。
+
+## 发布
+
+```bash
+cd packages/cli
+npm test
+npm publish --access public
+```
+
+需已登录 npm 且对 `@xiaoailazy` 作用域有发布权限。

package/bin/coexistree.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+import { createRequire } from "module";
+import { parseGlobalArgv } from "../lib/argv.js";
+import { bootstrapConfig, defaultConfigPath } from "../lib/config.js";
+import { runAsk } from "../lib/commands/ask.js";
+import { runConfig } from "../lib/commands/config.js";
+import { runTask } from "../lib/commands/task.js";
+
+const require = createRequire(import.meta.url);
+const { version: CLI_VERSION } = require("../package.json");
+
+function printHelp() {
+  console.log(`coexistree — CoExistree Agent CLI
+
+用法:
+  coexistree config initial --api-key <k> --system-code <code> [--base-url <url>]
+  coexistree config show | path
+  coexistree task create --title <title> [--summary <text>] <requirement.md>
+  coexistree task list [--scope pending-development|needs-test-case] [--page 0] [--size 5]
+  coexistree task upload --task-id <id> --doc-type DESIGN|TEST_CASE <file.md>
+  coexistree task pull --task-id <id> --doc-type REQUIREMENT|DESIGN|TEST_CASE [--document-id <id>]
+  coexistree ask --question <text>
+
+先 config initial。配置: ${defaultConfigPath()}
+
+全局选项（写在子命令前）:
+  --config <path>       配置文件路径（默认 ~/.coexistree/config.json）
+  --env-file <path>     可选，临时覆盖配置
+  --base-url <url>      单次覆盖 API 地址
+  -v, --version         打印 CLI 版本并退出
+  --verbose             打印请求/响应调试信息到 stderr
+  -h, --help
+
+示例: coexistree task list
+       coexistree task pull --task-id 42 --doc-type REQUIREMENT
+       coexistree task upload --task-id 42 --doc-type DESIGN path/design.md
+`);
+}
+
+const { values, positionals } = parseGlobalArgv(process.argv.slice(2));
+
+if (values.version) {
+  console.log(`coexistree ${CLI_VERSION}`);
+  process.exit(0);
+}
+
+if (values.help && positionals.length === 0) {
+  printHelp();
+  process.exit(0);
+}
+
+const sub = positionals[0];
+const rest = positionals.slice(1);
+
+if (!sub || sub === "help" || values.help) {
+  printHelp();
+  process.exit(sub ? 0 : 1);
+}
+
+try {
+  if (sub === "config") {
+    await runConfig(rest, values);
+  } else if (sub === "task") {
+    bootstrapConfig(values);
+    await runTask(rest, values);
+  } else {
+    bootstrapConfig(values);
+    if (sub === "ask") {
+      await runAsk(rest, values);
+    } else {
+      console.error(`未知子命令: ${sub}`);
+      printHelp();
+      process.exit(1);
+    }
+  }
+} catch (err) {
+  console.error(err.message ?? String(err));
+  process.exit(err.exitCode ?? 1);
+}

package/lib/argv.js

@@ -0,0 +1,82 @@
+const GLOBAL_FLAGS = new Set([
+  "--config",
+  "--env-file",
+  "--base-url",
+  "-h",
+  "--help",
+  "-v",
+  "--version",
+  "--verbose",
+]);
+
+/**
+ * 仅解析子命令前的全局参数，其余原样交给子命令（避免顶层 parseArgs 拒绝 --api-key 等）。
+ */
+export function parseGlobalArgv(argv) {
+  const values = { help: false, version: false, verbose: false };
+  const positionals = [];
+  let i = 0;
+
+  while (i < argv.length) {
+    const arg = argv[i];
+    if (arg === "-h" || arg === "--help") {
+      values.help = true;
+      i++;
+      continue;
+    }
+    if (arg === "-v" || arg === "--version") {
+      values.version = true;
+      i++;
+      continue;
+    }
+    if (arg === "--verbose") {
+      values.verbose = true;
+      i++;
+      continue;
+    }
+    if (!arg.startsWith("-")) {
+      break;
+    }
+    if (!GLOBAL_FLAGS.has(arg) && !arg.startsWith("--config=") && !arg.startsWith("--env-file=") && !arg.startsWith("--base-url=")) {
+      break;
+    }
+
+    if (arg === "--config") {
+      values.config = argv[++i];
+      i++;
+      continue;
+    }
+    if (arg.startsWith("--config=")) {
+      values.config = arg.slice("--config=".length);
+      i++;
+      continue;
+    }
+    if (arg === "--env-file") {
+      values["env-file"] = argv[++i];
+      i++;
+      continue;
+    }
+    if (arg.startsWith("--env-file=")) {
+      values["env-file"] = arg.slice("--env-file=".length);
+      i++;
+      continue;
+    }
+    if (arg === "--base-url") {
+      values["base-url"] = argv[++i];
+      i++;
+      continue;
+    }
+    if (arg.startsWith("--base-url=")) {
+      values["base-url"] = arg.slice("--base-url=".length);
+      i++;
+      continue;
+    }
+    break;
+  }
+
+  while (i < argv.length) {
+    positionals.push(argv[i++]);
+  }
+
+  return { values, positionals };
+}

package/lib/commands/ask.js

@@ -0,0 +1,53 @@
+import { parseArgs } from "node:util";
+import { resolveConfigPath } from "../config.js";
+import { agentConfig, agentHeaders, die } from "../env.js";
+import { agentFetch, logVerbose, printApiResult } from "../http.js";
+
+export async function runAsk(positionals, globalValues) {
+  const { values } = parseArgs({
+    args: positionals,
+    options: {
+      question: { type: "string" },
+      help: { type: "boolean", short: "h", default: false },
+    },
+  });
+
+  if (values.help) {
+    console.log(`ask — 向系统提问（同步 JSON 回答）
+
+选项:
+  --question <text>   必填
+`);
+    return;
+  }
+
+  const question = values.question?.trim();
+  if (!question) {
+    die("ask 需要 --question");
+  }
+
+  const verbose = Boolean(globalValues.verbose);
+  const config = agentConfig(globalValues);
+  const url = `${config.baseUrl}/api/v1/agent/ask`;
+
+  logVerbose(verbose, `config file: ${resolveConfigPath(globalValues)}`);
+  logVerbose(
+    verbose,
+    `resolved: baseUrl=${config.baseUrl} systemCode=${config.systemCode} apiKey=${config.apiKey.slice(0, 4)}... (len=${config.apiKey.length})`,
+  );
+
+  const { body } = await agentFetch(
+    url,
+    {
+      method: "POST",
+      headers: {
+        ...agentHeaders(config),
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ question }),
+    },
+    { verbose, label: "ask" },
+  );
+
+  printApiResult(body);
+}

package/lib/commands/config.js

@@ -0,0 +1,130 @@
+import { existsSync } from "node:fs";
+import { parseArgs } from "node:util";
+import {
+  defaultConfigPath,
+  readConfigFile,
+  resolveConfigPath,
+  writeConfigFile,
+} from "../config.js";
+import { die } from "../env.js";
+
+function maskSecret(value) {
+  if (!value || value.length < 8) return "****";
+  return `${value.slice(0, 4)}...${value.slice(-4)}`;
+}
+
+export async function runConfig(positionals, globalValues) {
+  const action = positionals[0];
+  if (!action || action === "help") {
+    printConfigHelp();
+    return;
+  }
+
+  if (action === "initial") {
+    await runConfigInitial(positionals.slice(1), globalValues);
+    return;
+  }
+
+  if (action === "show") {
+    runConfigShow(globalValues);
+    return;
+  }
+
+  if (action === "path") {
+    console.log(resolveConfigPath(globalValues));
+    return;
+  }
+
+  die(`未知 config 子命令: ${action}（可用: initial, show, path）`);
+}
+
+async function runConfigInitial(args, globalValues) {
+  const { values } = parseArgs({
+    args,
+    options: {
+      "api-key": { type: "string" },
+      "system-code": { type: "string" },
+      "base-url": { type: "string" },
+      force: { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false },
+    },
+  });
+
+  if (values.help) {
+    printConfigInitialHelp();
+    return;
+  }
+
+  const configPath = resolveConfigPath(globalValues);
+  const saved = writeConfigFile(
+    configPath,
+    {
+      apiKey: values["api-key"],
+      systemCode: values["system-code"],
+      baseUrl: values["base-url"],
+    },
+    { force: values.force },
+  );
+
+  console.error(`已写入配置: ${configPath}`);
+  console.log(
+    JSON.stringify(
+      {
+        apiKey: maskSecret(saved.apiKey),
+        systemCode: saved.systemCode,
+        baseUrl: saved.baseUrl,
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+function runConfigShow(globalValues) {
+  const configPath = resolveConfigPath(globalValues);
+  if (!existsSync(configPath)) {
+    die(`尚未初始化，请运行: coexistree config initial --api-key ... --system-code ...`);
+  }
+  const config = readConfigFile(configPath);
+  console.log(
+    JSON.stringify(
+      {
+        path: configPath,
+        apiKey: maskSecret(config.apiKey),
+        systemCode: config.systemCode,
+        baseUrl: config.baseUrl ?? "http://localhost:8080",
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+function printConfigHelp() {
+  console.log(`config — 本地 CLI 配置（默认文件 ~/.coexistree/config.json）
+
+子命令:
+  initial   首次写入配置（必填 --api-key --system-code）
+  show      查看当前配置（api-key 脱敏）
+  path      打印配置文件路径
+
+全局可配合: --config <path>  指定配置文件路径
+`);
+}
+
+function printConfigInitialHelp() {
+  console.log(`config initial — 生成本地配置文件
+
+选项:
+  --api-key <string>        必填（Web「密钥管理」中复制）
+  --system-code <string>    必填（系统 code，如 order-service）
+  --base-url <url>          可选，默认 http://localhost:8080
+  --force                   覆盖已有配置文件
+
+示例:
+  coexistree config initial \\
+    --api-key "ce_xxxx" \\
+    --system-code order-service \\
+    --base-url http://localhost:8080
+`);
+}

package/lib/commands/task.js

@@ -0,0 +1,298 @@
+import { Blob } from "node:buffer";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { parseArgs } from "node:util";
+import { resolveConfigPath } from "../config.js";
+import { agentConfig, agentHeaders, die } from "../env.js";
+import { agentFetch, logVerbose, printApiResult } from "../http.js";
+import { readMdPath } from "../md-file.js";
+import { buildPullDefaultPath } from "../task-paths.js";
+function taskFetch(globalValues, method, path, options = {}) {
+  const verbose = Boolean(globalValues.verbose);
+  const config = agentConfig(globalValues);
+  const url = `${config.baseUrl}${path}`;
+  logVerbose(verbose, `config file: ${resolveConfigPath(globalValues)}`);
+  return agentFetch(
+    url,
+    {
+      method,
+      headers: { ...agentHeaders(config), ...options.headers },
+      body: options.body,
+    },
+    { verbose, label: options.label ?? "task" },
+  );
+}
+
+async function runTaskCreate(positionals, globalValues) {
+  const { values, positionals: files } = parseArgs({
+    args: positionals,
+    options: {
+      title: { type: "string" },
+      summary: { type: "string" },
+      help: { type: "boolean", short: "h", default: false },
+    },
+    allowPositionals: true,
+  });
+
+  if (values.help) {
+    console.log(`task create — 创建任务并上传需求 .md
+
+选项:
+  --title <string>      必填
+  --summary <string>    可选
+  <requirement.md>      必填，恰好 1 个本地文件
+`);
+    return;
+  }
+
+  if (!values.title?.trim()) {
+    die("task create 需要 --title");
+  }
+  if (files.length !== 1) {
+    die("task create 需要恰好 1 个 .md 文件路径");
+  }
+
+  const prepared = readMdPath(files[0]);
+  console.error(`上传需求: ${prepared.abs}`);
+
+  const form = new FormData();
+  form.append("title", values.title.trim());
+  if (values.summary?.trim()) {
+    form.append("summary", values.summary.trim());
+  }
+  form.append("file", new Blob([prepared.data], { type: "text/markdown" }), prepared.name);
+
+  const { body } = await taskFetch(globalValues, "POST", "/api/v1/agent/tasks", {
+    body: form,
+    label: "task create",
+  });
+  printApiResult(body);
+}
+
+async function runTaskList(positionals, globalValues) {
+  const { values } = parseArgs({
+    args: positionals,
+    options: {
+      scope: { type: "string", default: "pending-development" },
+      page: { type: "string", default: "0" },
+      size: { type: "string", default: "5" },
+      help: { type: "boolean", short: "h", default: false },
+    },
+  });
+
+  if (values.help) {
+    console.log(`task list — 分页列出任务
+
+选项:
+  --scope <name>   pending-development（默认）| needs-test-case
+  --page <n>       页码，从 0 起，默认 0
+  --size <n>       每页条数，默认 5
+`);
+    return;
+  }
+
+  const scope = values.scope?.trim() || "pending-development";
+  if (!["pending-development", "needs-test-case"].includes(scope)) {
+    die("task list --scope 须为 pending-development 或 needs-test-case");
+  }
+  const qs = new URLSearchParams({
+    scope,
+    page: values.page ?? "0",
+    size: values.size ?? "5",
+  });
+  const { body } = await taskFetch(globalValues, "GET", `/api/v1/agent/tasks?${qs}`, {
+    label: "task list",
+  });
+  printApiResult(body);
+}
+
+const UPLOAD_DOC_TYPES = {
+  DESIGN: { label: "设计" },
+  TEST_CASE: { label: "测试用例" },
+};
+
+async function runTaskUpload(positionals, globalValues) {
+  const { values, positionals: files } = parseArgs({
+    args: positionals,
+    options: {
+      "task-id": { type: "string" },
+      "doc-type": { type: "string" },
+      help: { type: "boolean", short: "h", default: false },
+    },
+    allowPositionals: true,
+  });
+
+  if (values.help) {
+    console.log(`task upload — 为任务上传 Markdown（设计或测试用例）
+
+选项:
+  --task-id <id>       必填（变更批次 ID / taskId）
+  --doc-type <type>    必填：DESIGN | TEST_CASE
+  <file.md>            必填
+`);
+    return;
+  }
+
+  const taskId = values["task-id"]?.trim();
+  if (!taskId || !/^\d+$/.test(taskId)) {
+    die("task upload 需要 --task-id <数字>");
+  }
+
+  const docType = values["doc-type"]?.trim()?.toUpperCase();
+  if (!docType || !UPLOAD_DOC_TYPES[docType]) {
+    die("task upload 需要 --doc-type DESIGN 或 TEST_CASE");
+  }
+  if (files.length !== 1) {
+    die(`task upload --doc-type ${docType} 需要恰好 1 个 .md 文件路径`);
+  }
+
+  const spec = UPLOAD_DOC_TYPES[docType];
+  const sourcePath = files[0];
+  const prepared = readMdPath(sourcePath);
+  console.error(`上传${spec.label}到任务 ${taskId}: ${prepared.abs}`);
+
+  const form = new FormData();
+  form.append("file", new Blob([prepared.data], { type: "text/markdown" }), prepared.name);
+  form.append("docContentType", docType);
+
+  const { body } = await taskFetch(
+    globalValues,
+    "POST",
+    `/api/v1/agent/tasks/${taskId}/documents`,
+    { body: form, label: `task upload ${docType}` },
+  );
+  printApiResult(body);
+}
+
+const PULL_DOC_TYPES = {
+  REQUIREMENT: { kind: "prd", dir: "prd" },
+  DESIGN: { kind: "design", dir: "specs" },
+  TEST_CASE: { kind: "testcase", dir: "testcases" },
+};
+
+async function runTaskPull(positionals, globalValues) {
+  const { values } = parseArgs({
+    args: positionals,
+    options: {
+      "task-id": { type: "string" },
+      "doc-type": { type: "string" },
+      "document-id": { type: "string" },
+      output: { type: "string" },
+      force: { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false },
+    },
+  });
+
+  if (values.help) {
+    console.log(`task pull — 拉取 Markdown 到本地
+
+选项:
+  --task-id <id>         必填
+  --doc-type <type>      REQUIREMENT | DESIGN | TEST_CASE
+  --document-id <id>     可选，省略则拉该类型最新
+  --output <path>        可选
+  --force                覆盖已存在文件
+
+默认: docs/superpowers/{prd|specs|testcases}/{suggestedBasename}-{kind}-{documentId}.md
+`);
+    return;
+  }
+
+  const taskId = values["task-id"]?.trim();
+  if (!taskId || !/^\d+$/.test(taskId)) {
+    die("task pull 需要 --task-id <数字>");
+  }
+
+  const docType = values["doc-type"]?.trim()?.toUpperCase();
+  if (!docType || !PULL_DOC_TYPES[docType]) {
+    die("task pull 需要 --doc-type REQUIREMENT、DESIGN 或 TEST_CASE");
+  }
+
+  const documentId = values["document-id"]?.trim();
+  const qs = new URLSearchParams({ docContentType: docType });
+  const path = documentId
+    ? `/api/v1/agent/tasks/${taskId}/documents/${documentId}?${qs}`
+    : `/api/v1/agent/tasks/${taskId}/documents/latest?${qs}`;
+
+  const { body } = await taskFetch(globalValues, "GET", path, {
+    label: `task pull ${docType}`,
+  });
+
+  if (body.success === false) {
+    printApiResult(body);
+    return;
+  }
+
+  const data = body.data;
+  if (!data || typeof data.content !== "string") {
+    die("pull 响应缺少 data.content");
+  }
+
+  const customOutput = values.output?.trim();
+  const spec = PULL_DOC_TYPES[docType];
+  if (data.documentId == null || data.documentId === "") {
+    die("pull 响应缺少 data.documentId");
+  }
+  const outPath =
+    customOutput ||
+    buildPullDefaultPath({
+      suggestedBasename: data.suggestedBasename,
+      kind: spec.kind,
+      dir: spec.dir,
+      documentId: data.documentId,
+      taskId: data.taskId ?? taskId,
+    });
+
+  if (!values.force && existsSync(outPath)) {
+    die(`文件已存在: ${outPath}，请使用 --force 或另选 --output`);
+  }
+
+  mkdirSync(dirname(outPath), { recursive: true });
+  writeFileSync(outPath, data.content, "utf8");
+  console.error(`已写入: ${outPath}`);
+  if (body?.data && typeof body.data === "object") {
+    body.data.outputPath = outPath;
+  }
+  printApiResult(body);
+}
+
+function printTaskHelp() {
+  console.log(`task — 产研任务（合并进知识树须在 Web「应用变更」）
+
+  create   --title <t> [--summary <s>] <requirement.md>
+  list     [--scope pending-development|needs-test-case] [--page 0] [--size 5]
+  pull     --task-id <id> --doc-type REQUIREMENT|DESIGN|TEST_CASE [--document-id <id>]
+  upload   --task-id <id> --doc-type DESIGN|TEST_CASE <file.md>
+`);
+}
+
+export async function runTask(positionals, globalValues) {
+  const action = positionals[0];
+  const rest = positionals.slice(1);
+
+  if (!action || action === "help") {
+    printTaskHelp();
+    return;
+  }
+
+  if (action === "create") {
+    await runTaskCreate(rest, globalValues);
+    return;
+  }
+  if (action === "list") {
+    await runTaskList(rest, globalValues);
+    return;
+  }
+  if (action === "upload") {
+    await runTaskUpload(rest, globalValues);
+    return;
+  }
+  if (action === "pull") {
+    await runTaskPull(rest, globalValues);
+    return;
+  }
+
+  die(
+    `未知 task 子命令: ${action}（可用: create, list, upload, pull）`,
+  );
+}

package/lib/config.js

@@ -0,0 +1,108 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { die, loadEnvFile } from "./env.js";
+
+const CONFIG_DIR = join(homedir(), ".coexistree");
+const DEFAULT_CONFIG_FILE = join(CONFIG_DIR, "config.json");
+
+export function defaultConfigPath() {
+  return DEFAULT_CONFIG_FILE;
+}
+
+export function resolveConfigPath(cliValues) {
+  const custom = cliValues.config?.trim();
+  return custom ? resolve(custom) : DEFAULT_CONFIG_FILE;
+}
+
+export function readConfigFile(configPath) {
+  if (!existsSync(configPath)) {
+    return null;
+  }
+  let raw;
+  try {
+    raw = readFileSync(configPath, "utf8");
+  } catch (err) {
+    die(`无法读取配置文件 ${configPath}: ${err.message}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    die(`配置文件不是合法 JSON: ${configPath}`);
+  }
+  return normalizeConfig(parsed);
+}
+
+export function normalizeConfig(obj) {
+  if (!obj || typeof obj !== "object") {
+    die("配置文件格式无效");
+  }
+  const apiKey = pickString(obj, ["apiKey", "api_key", "COEXISTREE_API_KEY"]);
+  const systemCode = pickString(obj, ["systemCode", "system_code", "COEXISTREE_SYSTEM_CODE"]);
+  const baseUrl = pickString(obj, ["baseUrl", "base_url", "COEXISTREE_BASE_URL"]);
+  return { apiKey, systemCode, baseUrl };
+}
+
+function pickString(obj, keys) {
+  for (const k of keys) {
+    const v = obj[k];
+    if (v !== undefined && v !== null && String(v).trim() !== "") {
+      return String(v).trim();
+    }
+  }
+  return undefined;
+}
+
+/** Apply config file values only where process.env is not already set. */
+export function applyConfigToEnv(config) {
+  if (!config) return;
+  if (config.apiKey && process.env.COEXISTREE_API_KEY === undefined) {
+    process.env.COEXISTREE_API_KEY = config.apiKey;
+  }
+  if (config.systemCode && process.env.COEXISTREE_SYSTEM_CODE === undefined) {
+    process.env.COEXISTREE_SYSTEM_CODE = config.systemCode;
+  }
+  if (config.baseUrl && process.env.COEXISTREE_BASE_URL === undefined) {
+    process.env.COEXISTREE_BASE_URL = config.baseUrl;
+  }
+}
+
+/** 优先级（低→高）：配置文件 → --env-file → 已有环境变量 → 命令行 --base-url */
+export function bootstrapConfig(cliValues) {
+  const configPath = resolveConfigPath(cliValues);
+  applyConfigToEnv(readConfigFile(configPath));
+  if (cliValues["env-file"]) {
+    loadEnvFile(cliValues["env-file"]);
+  }
+  return configPath;
+}
+
+export function writeConfigFile(configPath, config, { force = false } = {}) {
+  const missing = [];
+  if (!config.apiKey) missing.push("--api-key");
+  if (!config.systemCode) missing.push("--system-code");
+  if (missing.length > 0) {
+    die(`config initial 缺少必填项: ${missing.join(", ")}`);
+  }
+
+  const normalized = {
+    apiKey: config.apiKey.trim(),
+    systemCode: config.systemCode.trim(),
+    baseUrl: (config.baseUrl?.trim() || "http://localhost:8080").replace(/\/$/, ""),
+  };
+
+  if (existsSync(configPath) && !force) {
+    die(`配置文件已存在: ${configPath}\n若要覆盖请加 --force`);
+  }
+
+  mkdirSync(dirname(configPath), { recursive: true });
+  const body = JSON.stringify(normalized, null, 2) + "\n";
+  writeFileSync(configPath, body, { encoding: "utf8", mode: 0o600 });
+  try {
+    chmodSync(configPath, 0o600);
+  } catch {
+    /* Windows 等环境可能不支持，忽略 */
+  }
+  return normalized;
+}

package/lib/env.js

@@ -0,0 +1,56 @@
+import { existsSync, readFileSync } from "node:fs";
+
+export function die(message, code = 1) {
+  const err = new Error(message);
+  err.exitCode = code;
+  throw err;
+}
+
+export function loadEnvFile(envPath) {
+  if (!existsSync(envPath)) {
+    die(`找不到 env 文件: ${envPath}`);
+  }
+  const text = readFileSync(envPath, "utf8");
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq <= 0) continue;
+    const key = line.slice(0, eq).trim();
+    let val = line.slice(eq + 1).trim();
+    if (
+      (val.startsWith('"') && val.endsWith('"')) ||
+      (val.startsWith("'") && val.endsWith("'"))
+    ) {
+      val = val.slice(1, -1);
+    }
+    if (process.env[key] === undefined) {
+      process.env[key] = val;
+    }
+  }
+}
+
+export function requireEnv(name) {
+  const v = process.env[name];
+  if (v === undefined || v.trim() === "") {
+    die(`缺少 ${name}：请先运行 coexistree config initial，或设置环境变量 / --env-file`);
+  }
+  return v.trim();
+}
+
+export function agentConfig(cliValues) {
+  const baseUrl = (cliValues["base-url"] ?? process.env.COEXISTREE_BASE_URL ?? "http://localhost:8080").replace(
+    /\/$/,
+    "",
+  );
+  const apiKey = requireEnv("COEXISTREE_API_KEY");
+  const systemCode = requireEnv("COEXISTREE_SYSTEM_CODE");
+  return { baseUrl, apiKey, systemCode };
+}
+
+export function agentHeaders(config) {
+  return {
+    "X-Api-Key": config.apiKey,
+    "X-System-Code": config.systemCode,
+  };
+}

package/lib/http.js

@@ -0,0 +1,86 @@
+import { die } from "./env.js";
+
+function maskKey(key) {
+  if (!key || key.length < 8) return "(empty or too short)";
+  return `${key.slice(0, 4)}...${key.slice(-4)} (len=${key.length})`;
+}
+
+export function logVerbose(verbose, ...lines) {
+  if (!verbose) return;
+  for (const line of lines) {
+    console.error(`[coexistree] ${line}`);
+  }
+}
+
+export async function agentFetch(url, options, { verbose = false, label = "request" } = {}) {
+  logVerbose(verbose, `${label}: ${options.method ?? "GET"} ${url}`);
+  if (verbose && options.headers) {
+    const h = { ...options.headers };
+    if (h["X-Api-Key"]) h["X-Api-Key"] = maskKey(h["X-Api-Key"]);
+    logVerbose(verbose, `${label} headers: ${JSON.stringify(h)}`);
+  }
+  if (verbose && options.body && typeof options.body === "string") {
+    const preview = options.body.length > 200 ? `${options.body.slice(0, 200)}...` : options.body;
+    logVerbose(verbose, `${label} body: ${preview}`);
+  }
+
+  const res = await fetch(url, options);
+
+  logVerbose(
+    verbose,
+    `${label} response: HTTP ${res.status} ${res.statusText}`,
+    `${label} response headers: content-type=${res.headers.get("content-type") ?? "(none)"}`,
+  );
+
+  const { body, rawText } = await readJsonResponse(res, { verbose, label });
+  interpretAuthHint(verbose, res.status, body);
+  return { res, body, rawText };
+}
+
+function interpretAuthHint(verbose, status, body) {
+  if (!verbose || status !== 401) return;
+  const msg = body?.message ?? "";
+  if (msg === "Unauthorized") {
+    logVerbose(
+      verbose,
+      "hint: 若后端日志已有 Agent auth OK 仍返回 Unauthorized，多为异步 dispatch 未带上 SecurityContext，请重建含最新 AgentApiKeyAuthFilter 的后端。",
+      "hint: 若日志无 Agent auth request，则检查 AGENT_API_ENABLED、URL、Nginx 是否转发 X-Api-Key 等头。",
+    );
+  } else if (msg === "Invalid API key") {
+    logVerbose(verbose, "hint: X-Api-Key 无效或已关闭，请在 Web「密钥管理」核对 key 与开关状态。");
+  } else if (msg === "Missing X-Api-Key") {
+    logVerbose(verbose, "hint: 服务端未收到 X-Api-Key（可能被反向代理剥离）。");
+  }
+  if (body?.code === "PERMISSION_DENIED") {
+    logVerbose(
+      verbose,
+      "hint: 该 userId 不是 systemId 的成员。请在 Web 端把用户加入系统，或 config initial 改用 SUPER_ADMIN 用户 ID（通常是 admin）。",
+    );
+  }
+}
+
+export async function readJsonResponse(res, { verbose = false, label = "response" } = {}) {
+  const text = await res.text();
+  if (verbose) {
+    const preview = text.length > 800 ? `${text.slice(0, 800)}...` : text;
+    logVerbose(verbose, `${label} body raw: ${preview || "(empty)"}`);
+  }
+  let body;
+  try {
+    body = text ? JSON.parse(text) : {};
+  } catch {
+    die(`服务器返回非 JSON (${res.status}): ${text.slice(0, 500)}`, 2);
+  }
+  return { res, body, rawText: text };
+}
+
+export function printApiResult(body) {
+  console.log(JSON.stringify(body, null, 2));
+  if (body.success === false) {
+    die(body.message ?? body.code ?? "request failed", 2);
+  }
+  const data = body.data;
+  if (data && typeof data === "object" && data.success === false) {
+    die(data.error ?? data.stage ?? "operation failed", 2);
+  }
+}

package/lib/md-file.js

@@ -0,0 +1,21 @@
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, basename } from "node:path";
+import { die } from "./env.js";
+
+export const MAX_MD_BYTES = 10 * 1024 * 1024;
+
+export function readMdPath(filePath) {
+  const abs = resolve(filePath);
+  if (!existsSync(abs)) {
+    die(`文件不存在: ${abs}`);
+  }
+  const data = readFileSync(abs);
+  if (data.length > MAX_MD_BYTES) {
+    die(`单文件超过 10MB: ${abs}`);
+  }
+  const name = basename(abs);
+  if (!name.endsWith(".md") || name.includes("..")) {
+    die(`文件名须为安全的 .md basename: ${abs}`);
+  }
+  return { abs, name, data };
+}

package/lib/task-paths.js

@@ -0,0 +1,34 @@
+import { join } from "node:path";
+
+const SLUG_MAX = 40;
+
+export function slugFromTitle(title) {
+  if (!title || !String(title).trim()) return "untitled";
+  let s = String(title).trim().toLowerCase();
+  s = s.replace(/[\s_.,;:!?/\\]+/g, "-");
+  s = s.replace(/[^\p{L}\p{N}-]/gu, "");
+  s = s.replace(/-+/g, "-").replace(/^-|-$/g, "");
+  if (!s) return "untitled";
+  const chars = [...s];
+  if (chars.length > SLUG_MAX) {
+    s = chars.slice(0, SLUG_MAX).join("").replace(/-+$/, "");
+  }
+  return s || "untitled";
+}
+
+export function formatDateLocal(d = new Date()) {
+  const y = d.getFullYear();
+  const m = String(d.getMonth() + 1).padStart(2, "0");
+  const day = String(d.getDate()).padStart(2, "0");
+  return `${y}-${m}-${day}`;
+}
+
+export function buildBasename({ taskId, title, date = new Date() }) {
+  return `${formatDateLocal(date)}-${slugFromTitle(title)}-task${taskId}`;
+}
+
+export function buildPullDefaultPath({ suggestedBasename, kind, dir, documentId, taskId }) {
+  const base = suggestedBasename?.trim() || `untitled-task${taskId}`;
+  return join("docs/superpowers", dir, `${base}-${kind}-${documentId}.md`);
+}
+

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@xiaoailazy/coexistree-cli",
+  "version": "0.2.0",
+  "description": "CoExistree Agent CLI — tasks, documents, and knowledge-tree ask via HTTP",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xiaoailazy/coexistree.git",
+    "directory": "packages/cli"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "coexistree",
+    "cli",
+    "agent",
+    "knowledge-tree"
+  ],
+  "bin": {
+    "coexistree": "./bin/coexistree.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/**/*.test.js"
+  }
+}