@xiaoailazy/coexistree-skills 0.2.0

package/README.md

@@ -0,0 +1,76 @@
+# @xiaoailazy/coexistree-skills
+
+CoExistree **Agent Skills**：供 Cursor、Claude Code、Codex 等支持 `SKILL.md` 的 Agent 使用。与 [`@xiaoailazy/coexistree-cli`](../cli) 配合。
+
+Skill **源文件**在本包的 `skills/` 目录；发布到 npm 后通过安装器复制到各 Agent 的技能目录。
+
+## 安装
+
+```bash
+# 仅 Skill
+npm install -g @xiaoailazy/coexistree-skills
+coexistree-skills-install
+
+# 或一键（CLI + Skill，见 meta 包）
+npm install -g @xiaoailazy/coexistree
+```
+
+还需 CLI：
+
+```bash
+npm install -g @xiaoailazy/coexistree-cli
+coexistree config initial --api-key "ce_..." --system-code "order-service"
+```
+
+## 安装器
+
+```bash
+coexistree-skills-install --help
+```
+
+| 选项 | 说明 |
+|------|------|
+| `--targets all` | 默认：cursor、claude、codex 的个人技能目录 |
+| `--targets cursor,claude` | 只装到指定 Agent |
+| `--project` | 同时写入当前项目的 `.cursor/skills` 等（适合仓库内协作） |
+| `--force` | 覆盖已有 `SKILL.md` |
+| `--dry-run` | 预览路径 |
+
+环境变量：`COEXISTREE_SKILLS_TARGETS`、`COEXISTREE_SKILLS_PROJECT=1`。
+
+### 安装路径
+
+| Agent | 个人目录 | 项目目录（`--project`） |
+|-------|----------|-------------------------|
+| Cursor | `~/.cursor/skills/` | `.cursor/skills/` |
+| Claude Code | `~/.claude/skills/` | `.claude/skills/` |
+| Codex | `~/.codex/skills/` | `.codex/skills/` |
+
+每个 skill 一个子目录，例如 `coexistree-task/SKILL.md`。
+
+## 包含的 Skill
+
+| name | 用途 |
+|------|------|
+| `coexistree-config` | 首次 `config initial`、`config show` |
+| `coexistree-task` | 产研任务：列表、拉取、上传 |
+| `coexistree-ask` | 知识树提问 |
+
+## 仓库开发
+
+从 monorepo 根目录同步到本机 Cursor（不发布 npm 时）：
+
+```bash
+node packages/skills/scripts/install-skills.js --targets cursor --project
+```
+
+**源文件以 `packages/skills/skills/` 为准**；`.cursor/skills/` 可继续 gitignore，由安装器生成。
+
+## 发布
+
+```bash
+cd packages/skills
+npm publish --access public
+```
+
+版本宜与 `@xiaoailazy/coexistree-cli` 对齐 major/minor。

package/lib/targets.js

@@ -0,0 +1,43 @@
+import { join } from "path";
+
+/** @typedef {'cursor' | 'claude' | 'codex'} AgentTargetId */
+
+/** @type {Record<AgentTargetId, { label: string; dirSegments: string[] }>} */
+export const AGENT_TARGETS = {
+  cursor: { label: "Cursor", dirSegments: [".cursor", "skills"] },
+  claude: { label: "Claude Code", dirSegments: [".claude", "skills"] },
+  codex: { label: "Codex", dirSegments: [".codex", "skills"] },
+};
+
+export const ALL_TARGET_IDS = /** @type {const} */ (Object.keys(AGENT_TARGETS));
+
+/**
+ * @param {string | undefined} raw  comma-separated, e.g. "cursor,claude" or "all"
+ * @returns {AgentTargetId[]}
+ */
+export function parseTargetIds(raw) {
+  const value = (raw ?? "all").trim().toLowerCase();
+  if (value === "all") {
+    return [...ALL_TARGET_IDS];
+  }
+  const ids = value
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  const unknown = ids.filter((id) => !(id in AGENT_TARGETS));
+  if (unknown.length > 0) {
+    throw new Error(
+      `Unknown target(s): ${unknown.join(", ")}. Valid: ${ALL_TARGET_IDS.join(", ")}, all`,
+    );
+  }
+  return /** @type {AgentTargetId[]} */ (ids);
+}
+
+/**
+ * @param {string} baseDir  home dir or project root
+ * @param {AgentTargetId} targetId
+ */
+export function skillsDirForTarget(baseDir, targetId) {
+  const { dirSegments } = AGENT_TARGETS[targetId];
+  return join(baseDir, ...dirSegments);
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@xiaoailazy/coexistree-skills",
+  "version": "0.2.0",
+  "description": "Agent Skills for CoExistree (Cursor, Claude Code, Codex, and compatible agents)",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xiaoailazy/coexistree.git",
+    "directory": "packages/skills"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "coexistree",
+    "agent-skills",
+    "cursor",
+    "claude",
+    "codex"
+  ],
+  "files": [
+    "skills",
+    "scripts",
+    "lib",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "coexistree-skills-install": "./scripts/install-skills.js"
+  },
+  "scripts": {
+    "test": "node --test test/**/*.test.js",
+    "install-skills": "node scripts/install-skills.js"
+  }
+}

package/scripts/install-skills.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+import { cpSync, existsSync, mkdirSync, readdirSync, statSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { AGENT_TARGETS, parseTargetIds, skillsDirForTarget } from "../lib/targets.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SKILLS_SRC = join(__dirname, "..", "skills");
+
+function printHelp() {
+  console.log(`coexistree-skills-install — install CoExistree Agent Skills
+
+用法:
+  coexistree-skills-install [options]
+
+选项:
+  --targets <list>   目标 Agent：cursor, claude, codex（逗号分隔），或 all（默认 all）
+  --project          同时安装到当前项目目录（各 Agent 的 .*/skills/）
+  --force            覆盖已存在的 SKILL.md
+  --dry-run          只打印将要复制的路径
+  -h, --help
+
+环境变量:
+  COEXISTREE_SKILLS_TARGETS   同 --targets
+  COEXISTREE_SKILLS_PROJECT=1  同 --project
+
+个人目录示例:
+  ~/.cursor/skills/coexistree-config/SKILL.md
+  ~/.claude/skills/coexistree-task/SKILL.md
+
+需配合 CLI: npm install -g @xiaoailazy/coexistree-cli
+`);
+}
+
+function parseArgv(argv) {
+  const opts = {
+    targets: process.env.COEXISTREE_SKILLS_TARGETS,
+    project: process.env.COEXISTREE_SKILLS_PROJECT === "1",
+    force: false,
+    dryRun: false,
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "-h" || arg === "--help") {
+      opts.help = true;
+    } else if (arg === "--project") {
+      opts.project = true;
+    } else if (arg === "--force") {
+      opts.force = true;
+    } else if (arg === "--dry-run") {
+      opts.dryRun = true;
+    } else if (arg === "--targets") {
+      opts.targets = argv[++i];
+    } else {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+  return opts;
+}
+
+function listSkillNames() {
+  if (!existsSync(SKILLS_SRC)) {
+    throw new Error(`Skills source missing: ${SKILLS_SRC}`);
+  }
+  return readdirSync(SKILLS_SRC).filter((name) => {
+    const p = join(SKILLS_SRC, name, "SKILL.md");
+    return existsSync(p) && statSync(join(SKILLS_SRC, name)).isDirectory();
+  });
+}
+
+/**
+ * @param {{ destRoot: string; force: boolean; dryRun: boolean }} ctx
+ */
+function installSkillBundle(ctx) {
+  const names = listSkillNames();
+  mkdirSync(ctx.destRoot, { recursive: true });
+  for (const name of names) {
+    const srcFile = join(SKILLS_SRC, name, "SKILL.md");
+    const destDir = join(ctx.destRoot, name);
+    const destFile = join(destDir, "SKILL.md");
+    if (existsSync(destFile) && !ctx.force) {
+      console.log(`skip (exists): ${destFile}`);
+      continue;
+    }
+    if (ctx.dryRun) {
+      console.log(`would install: ${destFile}`);
+      continue;
+    }
+    mkdirSync(destDir, { recursive: true });
+    cpSync(srcFile, destFile);
+    console.log(`installed: ${destFile}`);
+  }
+}
+
+function projectRoot() {
+  return process.env.INIT_CWD || process.cwd();
+}
+
+function main() {
+  const opts = parseArgv(process.argv.slice(2));
+  if (opts.help) {
+    printHelp();
+    return;
+  }
+
+  const targetIds = parseTargetIds(opts.targets);
+  const bases = [{ label: "personal", path: homedir() }];
+  if (opts.project) {
+    bases.push({ label: "project", path: projectRoot() });
+  }
+
+  for (const base of bases) {
+    for (const targetId of targetIds) {
+      const destRoot = skillsDirForTarget(base.path, targetId);
+      const agent = AGENT_TARGETS[targetId].label;
+      console.log(`\n# ${agent} (${base.label}) → ${destRoot}`);
+      installSkillBundle({
+        destRoot,
+        force: opts.force,
+        dryRun: opts.dryRun,
+      });
+    }
+  }
+}
+
+try {
+  main();
+} catch (err) {
+  console.error(err instanceof Error ? err.message : String(err));
+  printHelp();
+  process.exit(1);
+}

package/skills/coexistree-ask/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: coexistree-ask
+description: CoExistree 知识树提问。用于「问 coexistree」「系统信息查询」「coexistree 提问」。
+---
+
+# coexistree ask
+
+需已完成 **`coexistree config initial`**（见 `coexistree-config` skill）。
+
+通过终端执行 **`coexistree`**（先 `npm install -g @xiaoailazy/coexistree-cli`）。
+
+## 提问
+
+```bash
+coexistree ask --question "<问题>"
+```
+
+- `--question`：必填，向 CoExistree 知识树提问的内容
+
+## 结果
+
+- 成功：读 stdout JSON，向用户摘要。
+- 失败：非 0 退出码；看 stderr 与 JSON 的 `message` / `data.error`。

package/skills/coexistree-config/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: coexistree-config
+description: CoExistree 配置管理：初始化 API 密钥与 system code、查看当前配置。用于「配置 coexistree」「初始化密钥」「查看配置」。
+---
+
+# coexistree config
+
+通过终端执行 **`coexistree`**（先 `npm install -g @xiaoailazy/coexistree-cli`）。适用于 Cursor、Claude Code、Codex 等支持 Agent Skills 的环境。
+
+## 首次配置（只需一次）
+
+在 Web **密钥管理** 开启 Agent 密钥并复制；确认目标系统的 **system code**。
+
+```bash
+coexistree config initial \
+  --api-key "<从Web复制的 ce_ 密钥>" \
+  --system-code "<系统code>" \
+  [--base-url http://localhost:8080]
+```
+
+- `--api-key`：必填，Web 密钥管理中的 Agent 密钥（`ce_` 前缀）
+- `--system-code`：必填，目标系统唯一标识
+- `--base-url`：可选，默认官方/本地 API 地址
+
+之后**不要**再加 `--env-file`。
+
+## 查看配置
+
+```bash
+coexistree config show
+```
+
+用于核对 api-key（脱敏）、system-code、base-url。
+
+## 结果
+
+- 成功：读 stdout JSON，向用户摘要。
+- 失败：非 0 退出码；看 stderr 与 JSON 的 `message` / `data.error`。

package/skills/coexistree-task/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: coexistree-task
+description: CoExistree 产研任务：创建、列表、拉取、上传文档。
+---
+
+# coexistree task
+
+前置：`coexistree config initial`。通过终端执行 **`coexistree`**（先 `npm install -g @xiaoailazy/coexistree-cli`）。
+
+## 约定
+
+- **upload** 必须带 1 个 `.md` 路径；设计稿用 Agent 刚写完的文件，不确定则问用户。
+- **pull** 默认写入 `docs/superpowers/{prd|specs|testcases}/{suggestedBasename}-{prd|design|testcase}-{documentId}.md`。
+- 文档不会自动进知识树；须在 Web 对任务「应用变更」。
+
+## 命令
+
+| 意图 | 命令 |
+|------|------|
+| 待开发任务 | `task list --scope pending-development` |
+| 待补测试用例 | `task list --scope needs-test-case` |
+| 读需求 | `task pull --task-id <id> --doc-type REQUIREMENT` |
+| 读设计/用例 | `task pull --task-id <id> --doc-type DESIGN\|TEST_CASE [--document-id <id>]` |
+| 上传设计 | `task upload --task-id <id> --doc-type DESIGN <file.md>` |
+| 上传用例 | `task upload --task-id <id> --doc-type TEST_CASE <file.md>` |
+| 创建任务 | `task create --title "<标题>" [--summary "<说明>"] <requirement.md>` |
+
+`task list` 支持 `--page`、`--size`（默认 `0`、`5`）。
+
+## 流程
+
+`list` → `pull REQUIREMENT` → 写设计 → `upload DESIGN` →（可选）`upload TEST_CASE`
+
+stdout 为 JSON `{ success, code, message, data }`；失败时非 0 退出。