@olierjs/fugue-cli 0.0.0-stage → 0.1.0

package/bin/fugue-cli.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const platform = `${process.platform}-${process.arch}`;
+const supported = new Set(['darwin-x64', 'darwin-arm64', 'linux-x64', 'linux-arm64', 'win32-x64', 'win32-arm64']);
+
+if (!supported.has(platform)) {
+  console.error(`fugue-cli 不支持当前平台：${platform}`);
+  process.exitCode = 1;
+} else {
+  const filename = process.platform === 'win32' ? 'fugue-cli.exe' : 'fugue-cli';
+  const binary = fileURLToPath(new URL(`../dist/${platform}/${filename}`, import.meta.url));
+  const result = spawnSync(binary, process.argv.slice(2), { stdio: 'inherit' });
+  if (result.error) {
+    console.error(`无法运行 fugue-cli，请重新安装 @olierjs/fugue-cli：${result.error.message}`);
+    process.exitCode = 1;
+  } else if (result.signal) {
+    process.kill(process.pid, result.signal);
+  } else {
+    process.exitCode = result.status ?? 1;
+  }
+}

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@olierjs/fugue-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Fugue 需求交付工作指南与 Agent 技能",
+  "type": "module",
+  "bin": { "fugue-cli": "bin/fugue-cli.mjs" },
+  "files": [
+    "bin/",
+    "dist/",
+    "scripts/postinstall.mjs",
+    "scripts/skills.mjs",
+    "skills/",
+    "THIRD_PARTY_NOTICES"
+  ],
+  "engines": { "node": ">=22.19.0" },
+  "os": ["darwin", "linux", "win32"],
+  "cpu": ["x64", "arm64"],
+  "license": "Apache-2.0",
+  "repository": { "type": "git", "url": "git+https://github.com/TbhT/fugue-stack.git" },
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "test:go": "go test ./...",
+    "build": "node scripts/build.mjs",
+    "prepack": "node scripts/build.mjs",
+    "postinstall": "node scripts/postinstall.mjs"
+  }
+}

package/scripts/postinstall.mjs

@@ -0,0 +1,13 @@
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { syncSkills } from './skills.mjs';
+
+try {
+  const { version } = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+  const result = await syncSkills({ sourceDirectory: fileURLToPath(new URL('../skills/', import.meta.url)), version });
+  console.log(`fugue-cli：技能已同步到 ${result.directory}`);
+  if (result.backupDirectory) console.log(`旧技能备份：${result.backupDirectory}`);
+} catch (error) {
+  console.error(`fugue-cli 技能同步失败：${error.message}`);
+  process.exitCode = 1;
+}

package/scripts/skills.mjs

@@ -0,0 +1,104 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { cp, lstat, mkdir, readFile, readdir, readlink, rename, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const owner = '@olierjs/fugue-cli';
+const marker = '.fugue-cli.json';
+
+async function exists(path) {
+  try { return await lstat(path); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+
+async function managed(path) {
+  if (!(await exists(path))?.isDirectory()) return false;
+  try { return JSON.parse(await readFile(join(path, marker), 'utf8')).owner === owner; }
+  catch (error) {
+    if (['ENOENT', 'ENOTDIR'].includes(error.code) || error instanceof SyntaxError) return false;
+    throw error;
+  }
+}
+
+async function digest(path) {
+  const hash = createHash('sha256');
+  async function visit(current, relative) {
+    const info = await lstat(current);
+    hash.update(JSON.stringify([relative, info.mode & 0o777]));
+    if (info.isSymbolicLink()) hash.update(JSON.stringify(['link', await readlink(current)]));
+    else if (info.isDirectory()) {
+      hash.update('directory');
+      for (const name of (await readdir(current)).sort()) await visit(join(current, name), `${relative}/${name}`);
+    } else if (info.isFile()) {
+      hash.update('file');
+      hash.update(await readFile(current));
+    } else throw new Error(`技能包含不支持的文件类型：${current}`);
+  }
+  await visit(path, '');
+  return hash.digest('hex');
+}
+
+export async function syncSkills({ sourceDirectory, version, homeDirectory = homedir() }) {
+  const directory = join(homeDirectory, '.agents', 'skills');
+  const storage = join(homeDirectory, '.local', 'share', 'fugue-cli');
+  const batch = randomUUID();
+  const staging = join(storage, `.staging-${batch}`);
+  const backupDirectory = join(storage, 'backups', batch);
+  const names = (await readdir(sourceDirectory, { withFileTypes: true })).filter(entry => entry.isDirectory()).map(entry => entry.name).sort();
+  if (!names.length) throw new Error('安装包没有可用技能。');
+  for (const name of names) {
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name) || !(await exists(join(sourceDirectory, name, 'SKILL.md')))?.isFile()) {
+      throw new Error(`安装包技能无效：${name}`);
+    }
+  }
+  await mkdir(directory, { recursive: true });
+  await mkdir(staging, { recursive: true });
+  const result = { directory, installed: [], removed: [], unchanged: [], backupDirectory: null };
+  const changed = [];
+  const stale = [];
+  const backedUp = [];
+  const installed = [];
+  try {
+    for (const name of names) {
+      const prepared = join(staging, name);
+      await cp(join(sourceDirectory, name), prepared, { recursive: true, dereference: false, verbatimSymlinks: true });
+      await writeFile(join(prepared, marker), JSON.stringify({ owner, version }) + '\n');
+      const target = join(directory, name);
+      if (await exists(target) && await digest(target) === await digest(prepared)) result.unchanged.push(name);
+      else changed.push(name);
+    }
+    for (const name of await readdir(directory)) {
+      if (!names.includes(name) && await managed(join(directory, name))) stale.push(name);
+    }
+    for (const name of [...changed, ...stale]) {
+      const target = join(directory, name);
+      if (await exists(target)) {
+        await mkdir(backupDirectory, { recursive: true });
+        await rename(target, join(backupDirectory, name));
+        backedUp.push(name);
+        result.backupDirectory = backupDirectory;
+      }
+    }
+    for (const name of changed) {
+      await rename(join(staging, name), join(directory, name));
+      installed.push(name);
+    }
+    result.installed = changed;
+    result.removed = stale;
+    return result;
+  } catch (error) {
+    const failures = [];
+    for (const name of installed.reverse()) {
+      try { await rm(join(directory, name), { recursive: true, force: true }); }
+      catch (rollbackError) { failures.push(rollbackError.message); }
+    }
+    for (const name of backedUp.reverse()) {
+      try { await rename(join(backupDirectory, name), join(directory, name)); }
+      catch (rollbackError) { failures.push(rollbackError.message); }
+    }
+    if (failures.length) throw new Error(`${error.message}；恢复未完成，备份位于 ${backupDirectory}：${failures.join('；')}`, { cause: error });
+    throw error;
+  } finally {
+    await rm(staging, { recursive: true, force: true });
+  }
+}

package/skills/fugue-stack/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: fugue-stack
+description: 开始或继续个人需求交付时，通过 fugue-cli 获取当前工作指南，选择并衔接规划、编码、代码审查与验证或实现解释；不用于纯闲聊和普通知识问答。
+---
+
+# Fugue Stack
+
+每次开始或继续任务时，运行 `fugue-cli guide`，读取当前安装版本的总览，并遵循其中与本次用户目标对应的流程。
+
+工作路由和具体要求由本次命令输出提供。按需读取其中指向的技能与材料，保留已有规划会话和产物，在本次授权范围内完成工作。

package/skills/plan-with-remote/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: plan-with-remote
+description: 当用户需要通过远端服务制定开发方案、生成执行和验收文档、查看规划进展、补充需求或审阅修改方案时使用。
+---
+
+# 远端规划
+
+将用户需求交给规划服务，向用户呈现方案、待回答的问题和最终文档。规划交付不表示软件已经实现或验收。脚本由 Node 内置能力组成，不需要从 Reconcile 源码仓库构建或安装 npm 依赖。
+
+## 开始
+
+使用 Node 22.19.0 或更高版本及 Git。在目标 Git 仓库中调用：
+
+```sh
+node <skill-root>/scripts/client.mjs --help
+```
+
+服务地址由 `RECONCILE_BASE_URL` 或 `--config` 指定；首次配置、切换服务或调整等待时间时阅读[配置说明](references/configuration.md)。仓库必须已在服务中登记；匹配失败时报告缺项。
+
+先收集用户目标、范围、约束和需求来源。保留产品事实的原意；先读取来源正文，不把链接当成正文，也不把已有建议当成已批准决定。创建 `request.json`：
+
+```json
+{
+  "title": "修复切换对象后的状态显示",
+  "description": "切换到新对象后，旧请求的结果不能覆盖新对象的状态。保留正常加载行为。",
+  "sources": [{ "label": "用户补充", "content": "切换后应立即显示新对象的加载状态。" }]
+}
+```
+
+`sources` 可省略。两种规划方式都生成执行文档与验收文档，并等待最终批准：
+
+- `lightweight`：适合范围明确的局部改动，直接形成最终文档。
+- `standard`：先审阅方案方向，用户认可后继续生成文档并进行独立评审。
+
+按用户目标明确选择；不清楚是否需要先审方向时向用户确认。
+
+```sh
+node <skill-root>/scripts/client.mjs plan --input request.json --mode lightweight
+```
+
+## 处理结果
+
+脚本输出状态、文件路径、问题和下一步命令。保存返回的 `session` 和 `review` 路径，原样传回脚本；这些文件由脚本维护，无需打开、编辑或拼装其内容。
+
+| 返回状态 | Agent 的下一步 |
+| --- | --- |
+| `running` | 使用 `read --session <路径>` 继续查看，不重复创建任务。 |
+| `review_solution` | 阅读并呈现方案；用户认可后用 `accept --review <路径>`，有修改用 `feedback`。 |
+| `review_documents` | 阅读执行文档、验收文档及返回的问题文件；用户明确批准后用 `approve --review <路径>`。 |
+| `questions` | 向用户提出返回的问题，用 `answer --review <路径> --question <编号> --text <用户回答>` 提交。确认类问题在用户同意后使用 `--confirm`。 |
+| `changes_needed` | 呈现待解决问题，按用户修改要求使用 `feedback`；不能批准。 |
+| `submission_unconfirmed` | 用 `retry --session <路径>` 重试原请求，不另建任务。 |
+| `failed` | 报告失败；需要重试时用 `retry --session <路径>`。 |
+| `approved` / `stopped` | 交付返回的文档，或报告规划已停止。 |
+
+反馈用 `feedback --review <路径> --scope <范围> --change <修改要求> --preserve <保留要求>`。范围选需求 `requirements`、方案 `solution` 或验收设计 `verification`；方案总览还支持仅改表达的 `wording`。具体可用范围见 `--help`。
+
+决定来源通过配置或 `--actor` 提供。认可、批准、停止和确认重新规划必须有用户明确授权。已获得且仍适用于本次文档的授权不重复询问。版本变化时重新呈现，不将旧决定用于新文档。
+
+阅读并解释返回的正式文档。计划中的实现、测试或效果保持为计划，不写成已完成事实。文档可以提交审阅，不代表用户已批准。

package/skills/plan-with-remote/references/configuration.md

@@ -0,0 +1,43 @@
+# 配置
+
+运行时无需安装 npm 依赖。需要 Node >=22.19.0、Git、可访问的规划服务，以及已登记到该服务的目标仓库。
+
+配置优先级：命令行参数 > 环境变量 > `--config` 指定的 JSON 文件 > 默认值。也可用 `RECONCILE_CLIENT_CONFIG` 指定配置文件路径。不会自动读取或执行 `.env` 文件。
+
+| JSON 字段 | 环境变量 | 命令行 | 默认值 |
+| --- | --- | --- | --- |
+| `baseUrl` | `RECONCILE_BASE_URL` | `--base-url` | 必须配置，无内置 IP |
+| `remote` | `RECONCILE_REMOTE` | `plan --remote` | `origin` |
+| `agent` | `RECONCILE_AGENT` | `plan --agent` | 服务中配置的项目默认客户端 |
+| `actor` | `RECONCILE_ACTOR` | 决策、反馈、回答命令的 `--actor` | 无；需明确提供 |
+| `waitMs` | `RECONCILE_WAIT_MS` | `--wait-ms` | `60000` |
+| `requestTimeoutMs` | `RECONCILE_REQUEST_TIMEOUT_MS` | `--request-timeout-ms` | `30000` |
+
+例如将配置存入仓库外的 `reconcile.config.json`，把示例域名换成实际服务地址：
+
+```json
+{
+  "baseUrl": "https://planning.example.com",
+  "remote": "origin",
+  "actor": "user:your-name",
+  "waitMs": 60000,
+  "requestTimeoutMs": 30000
+}
+```
+
+`actor` 只声明决定来源，不代表登录或身份认证，不要编造真实人员身份。`agent` 仅在明确需要覆盖项目默认值时配置，可选 `traex` 或 `grok-build`，创建后不可切换。
+
+```sh
+node <skill-root>/scripts/client.mjs plan \
+  --config /absolute/path/reconcile.config.json \
+  --input request.json --mode standard \
+  --output-dir /absolute/path/planning-output
+```
+
+默认输出目录为目标仓库的 `.plan-with-remote/<任务编号>/`。可用 `--output-dir` 指定空目录；不要把需求材料、输出或配置提交到公开仓库。后续命令直接使用返回的绝对路径。
+
+任务会记住创建时的服务地址；继续任务不需要重复配置地址。显式配置了不同地址时命令会拒绝执行，不能把同一个任务切换到其他服务。
+
+`waitMs` 限制本轮等待，结束后返回当前进展；`read` 可以继续等待，远端任务不会因此停止。每次 HTTP 请求另外受 `requestTimeoutMs` 限制。网络结果不明确时保留任务文件，用 `retry` 重试同一个请求。
+
+只有 `plan --dry-run` 提供本地输入预览，不访问服务、不创建任务；它不证明服务可达或仓库已登记。其他命令拒绝 `--dry-run`。

package/skills/plan-with-remote/scripts/client.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { realpathSync } from 'node:fs';
+import { configuration } from './config.mjs';
+import { start, useSession } from './planning.mjs';
+
+const commandOptions = {
+  plan: ['input', 'mode', 'output-dir', 'remote', 'agent', 'dry-run'],
+  read: ['session'], retry: ['session'],
+  accept: ['review', 'actor'], approve: ['review', 'actor'], stop: ['review', 'actor'],
+  answer: ['review', 'question', 'text', 'confirm', 'actor'],
+  feedback: ['review', 'scope', 'change', 'preserve', 'actor'],
+};
+const globalOptions = ['config', 'base-url', 'wait-ms', 'request-timeout-ms', 'help'];
+const booleanOptions = new Set(['help', 'dry-run', 'confirm']);
+const help = `用法：node <skill-root>/scripts/client.mjs <命令> [参数]
+
+plan      --input request.json --mode lightweight|standard [--output-dir 目录] [--dry-run]
+read      --session <返回的任务文件>
+retry     --session <任务文件>                 重试原提交，或重新规划失败任务
+accept    --review <返回的审阅凭据>             用户认可方案，继续生成最终文档
+approve   --review <审阅凭据>                  用户批准最终文档
+stop      --review <审阅凭据>                  用户停止规划
+answer    --review <审阅凭据> --question <编号> --text <用户回答>
+          确认类问题使用 --confirm，代替 --text
+feedback  --review <审阅凭据> --scope <范围> --change <修改要求> --preserve <保留要求>
+          方案范围：requirements|solution|wording；最终文档：requirements|solution|verification
+
+决定、反馈和回答需要 --actor <决定来源>，也可通过配置提供。
+plan 支持 --remote <Git remote>、--agent traex|grok-build；通常使用项目默认客户端。
+通用配置：--config <JSON 文件>、--base-url <URL>、--wait-ms <毫秒>、--request-timeout-ms <毫秒>。
+配置优先级：命令行 > 环境变量 > 配置文件 > 内置默认值。配置说明见 references/configuration.md。
+只有 plan 支持 --dry-run，且不会访问网络。其他命令拒绝此参数。
+输出为 JSON：状态、文件路径、待回答问题和下一步命令。无需打开任务文件或审阅凭据。
+`;
+
+export async function main(argv = process.argv.slice(2), env = process.env) {
+  const [command, ...args] = argv;
+  if (!command || command === '--help' || command === '-h') return { help };
+  if (!Object.hasOwn(commandOptions, command)) throw new Error('未知命令，请使用 --help。');
+  const options = Object.fromEntries([...globalOptions, ...commandOptions[command]].map(key => [key, { type: booleanOptions.has(key) ? 'boolean' : 'string' }]));
+  const { values } = parseArgs({ args, options, strict: true, allowPositionals: false });
+  if (values.help) return { help };
+  const config = await configuration(values, env);
+  return command === 'plan' ? start(values, config) : useSession(command, values, config);
+}
+
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const [major, minor] = process.versions.node.split('.').map(Number);
+  if (major < 22 || (major === 22 && minor < 19)) {
+    console.error('请使用 Node 22.19.0 或更高版本。');
+    process.exitCode = 1;
+  } else {
+    main().then(result => console.log(result.help ?? JSON.stringify(result, null, 2))).catch(error => {
+      const message = error.message?.match(/[\u3400-\u9fff]/) ? error.message : '命令未完成。请检查参数或配置；已提交的任务请保留任务文件后继续。';
+      console.error(JSON.stringify({ status: 'error', message, ...(error.session ? { session: error.session } : {}), ...(error.diagnostic ? { diagnostic: error.diagnostic } : {}), ...(!error.session ? { detail: error.message } : {}) }, null, 2));
+      process.exitCode = 1;
+    });
+  }
+}

package/skills/plan-with-remote/scripts/config.mjs

@@ -0,0 +1,53 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+const settings = {
+  baseUrl: ['base-url', 'RECONCILE_BASE_URL'],
+  remote: ['remote', 'RECONCILE_REMOTE', 'origin'],
+  agent: ['agent', 'RECONCILE_AGENT'],
+  actor: ['actor', 'RECONCILE_ACTOR'],
+  waitMs: ['wait-ms', 'RECONCILE_WAIT_MS', 60000],
+  requestTimeoutMs: ['request-timeout-ms', 'RECONCILE_REQUEST_TIMEOUT_MS', 30000],
+};
+
+export async function configuration(flags, env = process.env) {
+  const path = flags.config ?? env.RECONCILE_CLIENT_CONFIG;
+  const file = path ? JSON.parse(await readFile(resolve(path), 'utf8')) : {};
+  if (!file || typeof file !== 'object' || Array.isArray(file)) throw new Error('配置文件必须是 JSON 对象。');
+  for (const key of Object.keys(file)) {
+    if (!(key in settings)) throw new Error(`未知配置：${key}`);
+  }
+  const config = {};
+  for (const [key, [flag, variable, fallback]] of Object.entries(settings)) {
+    config[key] = flags[flag] ?? env[variable] ?? file[key] ?? fallback;
+  }
+  if (config.baseUrl !== undefined) {
+    const url = new URL(config.baseUrl);
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+      throw new Error('服务地址必须是没有凭证、查询参数或片段的 HTTP(S) 地址。');
+    }
+    config.baseUrl = url.href.replace(/\/+$/, '');
+  }
+  for (const key of ['waitMs', 'requestTimeoutMs']) {
+    config[key] = Number(config[key]);
+    if (!Number.isSafeInteger(config[key]) || config[key] <= 0) throw new Error(`${key} 必须是正整数毫秒。`);
+  }
+  for (const key of ['remote', 'actor', 'agent']) {
+    if (config[key] !== undefined && (typeof config[key] !== 'string' || !config[key].trim())) {
+      throw new Error(`${key} 不能为空。`);
+    }
+  }
+  if (config.agent !== undefined && !['traex', 'grok-build'].includes(config.agent)) {
+    throw new Error('agent 只能是 traex 或 grok-build。');
+  }
+  return config;
+}
+
+export function serviceAddress(config, session) {
+  if (session && config.baseUrl && config.baseUrl !== session.baseUrl) {
+    throw new Error('当前配置指向另一服务。继续原任务时请使用创建任务的服务地址。');
+  }
+  const url = session?.baseUrl ?? config.baseUrl;
+  if (!url) throw new Error('请设置 RECONCILE_BASE_URL，或通过 --config / --base-url 配置服务地址。');
+  return url;
+}