msdevflow 0.6.1 → 0.7.0

package/README.md

@@ -1,12 +1,12 @@
 # msdevflow
 
-`msdevflow` 是一个用于 GitCode 的 Claude Code Agent Skill，可以把已授权的 Issue 安全推进到代码实现、普通 PR、CI、检视意见闭环和最终合入，也可以通过显式 `action` 只执行其中一个能力。
+`msdevflow` 是一个用于 GitCode 的 Agent Skill，可以把已授权的 Issue 安全推进到代码实现、普通 PR、CI、检视意见闭环和最终合入，也可以通过显式 `action` 只执行其中一个能力。正式支持 Claude Code、Codex 和 OpenCode；Trae 的 Skills 安装与兼容机制尚未完成可靠验证，因此当前不宣称支持。
 
 ## 安装
 
 环境要求：
 
-- Claude Code，且支持 Agent Skills；
+- Claude Code、Codex 或 OpenCode 中至少一个；
 - Node.js `>=18` 和 npm；
 - Git；
 - Python `>=3.10` 和 pip；
@@ -19,40 +19,55 @@
 npx msdevflow setup
 ```
 
-`setup` 会先展示完整计划，确认后在同一次运行中：
+`setup` 默认检测 PATH 中的 Claude Code、Codex 和 OpenCode，展示完整计划并在确认后：
 
-1. 安装或更新 `msdevflow` skill；
+1. 把同一份 `msdevflow` skill 原子安装或更新到所需目标；
 2. 安装或升级官方 `@gitcode-cli/cli@latest`；
 3. 安装受审的 Python Playwright 依赖；
 4. 验收 Issue、PR、结构化评论、行内评论、JSON、显式仓库和正文文件等 CLI 能力；
 5. GitCode CLI 未认证时打开官方浏览器登录。
 
-可选的只读预检：
+显式选择客户端或只读预检：
 
 ```bash
-npx msdevflow setup --dry-run
+npx msdevflow setup --targets claude
+npx msdevflow setup --targets codex,opencode
+npx msdevflow setup --targets all
+npx msdevflow setup --dry-run --targets all
 ```
 
-自定义 Claude Code skills 目录：
+安装目录映射：
+
+```text
+Claude Code                 -> ~/.claude/skills/msdevflow
+Codex                       -> ~/.agents/skills/msdevflow
+仅 OpenCode                 -> ~/.agents/skills/msdevflow
+OpenCode + Claude Code      -> 复用 ~/.claude/skills/msdevflow
+OpenCode + Codex            -> 复用 ~/.agents/skills/msdevflow
+Claude Code + Codex         -> 两个受管副本
+三者同时安装                -> 两个受管副本，并提示 OpenCode 可从两处发现同名 skill
+```
+
+自定义目录：
 
 ```bash
-npx msdevflow setup --skills-dir "<skills-directory>"
+npx msdevflow setup --skills-dir "<claude-skills-directory>"
+npx msdevflow setup --agents-skills-dir "<shared-agent-skills-directory>"
 ```
 
-安装完成后重新启动 Claude Code 会话。如果机器已有 Python 版本的 `gitcode`，setup 会保留它，并为 npm CLI 创建 `gitcode-npm` 命令；否则使用 `gitcode`。
+`--skills-dir` 未配合 `--targets` 使用时保留旧语义，只安装 Claude Code 目标。没有检测到客户端时，交互运行会要求选择目标；非交互运行必须提供 `--targets`。安装完成后重启或重新加载对应客户端。如果机器已有 Python 版本的 `gitcode`，setup 会保留它，并为 npm CLI 创建 `gitcode-npm` 命令；否则使用 `gitcode`。
 
 ## 完整端到端流程
 
-从目标仓库目录启动 Claude Code：
+从目标仓库目录启动已安装目标中的任一客户端，然后调用 skill：
 
-```bash
-claude
-```
+- Claude Code：输入 `/msdevflow`；
+- Codex：使用 `$msdevflow`、`/skills` 选择，或让 Codex 按描述隐式匹配；
+- OpenCode：通过其 skill 工具选择，或让 OpenCode 按描述隐式匹配。
 
-然后输入：
+客户端 UI 和命令入口可能随版本变化，但传给 skill 的任务正文相同：
 
 ```text
-/msdevflow
 处理 https://gitcode.com/<canonical-owner>/<repo>/issues/<number>。
 本地仓库：<local-repository-absolute-path>
 canonical：<canonical-owner>/<repo>
@@ -160,14 +175,18 @@ Agent 写入的 PR/Issue 正文、评论和 discussion 回复末尾会附加：
 
 ## 常见阻塞
 
-### `/msdevflow` 不存在
+### 客户端找不到 `msdevflow`
 
-确认以下文件存在，然后重启 Claude Code：
+按目标确认至少一个受支持的 manifest 存在，然后重启或重新加载客户端：
 
 ```text
-~/.claude/skills/msdevflow/SKILL.md
+Claude Code: ~/.claude/skills/msdevflow/SKILL.md
+Codex:       ~/.agents/skills/msdevflow/SKILL.md
+OpenCode:    上述任一路径（按 setup 计划）
 ```
 
+可运行 `npx msdevflow setup --dry-run --targets <clients>` 检查目标映射。
+
 ### `blocked: bootstrap-required`
 
 重新运行：

package/lib/bootstrap.js

@@ -25,6 +25,7 @@ const REGISTRY = "https://registry.npmjs.org";
 const GITCODE_PACKAGE = "@gitcode-cli/cli@latest";
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const BUNDLED_SKILL_DIR = path.join(PACKAGE_ROOT, "skill", "msdevflow");
+const SUPPORTED_CLIENTS = ["claude", "codex", "opencode"];
 const REQUIRED_SCHEMAS = {
   "auth login": ["web"],
   "auth status": ["json"],
@@ -56,11 +57,18 @@ export function usage() {
   msdevflow setup [options]
 
 Options:
-  --skills-dir <path>   Installed skills directory (default: ~/.claude/skills)
-  --dry-run             Diagnose and print the plan without changing the environment
-  --yes                 Apply the displayed plan without an interactive confirmation
-  --json                Print the final result as JSON
-  -h, --help            Show this help
+  --targets <clients>          Comma-separated: claude,codex,opencode,all
+  --skills-dir <path>          Claude skills directory (default: ~/.claude/skills)
+  --agents-skills-dir <path>   Shared Agent Skills directory (default: ~/.agents/skills)
+  --dry-run                    Diagnose and print the plan without changing the environment
+  --yes                        Apply the displayed plan without an interactive confirmation
+  --json                       Print the final result as JSON
+  -h, --help                   Show this help
+
+Without --targets, setup detects Claude Code, Codex, and OpenCode on PATH. If no
+client is detected, interactive setup asks which clients to install; non-interactive
+setup requires --targets. OpenCode reuses a Claude or shared Agent Skills target
+instead of creating a third copy.
 
 The setup installs or updates the bundled msdevflow skill, installs or upgrades
 the official GitCode npm CLI, and installs all reviewed Python runtime
@@ -69,6 +77,24 @@ authenticated, it starts the CLI's official browser login; setup never reads or
 prints a token.`;
 }
 
+export function parseTargets(value) {
+  const requested = value.split(",").map((target) => target.trim().toLowerCase()).filter(Boolean);
+  if (requested.length === 0) {
+    throw new BootstrapError("--targets requires at least one client.", 2);
+  }
+  const unsupported = requested.filter(
+    (target) => target !== "all" && !SUPPORTED_CLIENTS.includes(target),
+  );
+  if (unsupported.length) {
+    throw new BootstrapError(
+      `Unsupported client target: ${unsupported.join(", ")}. Supported targets: ${SUPPORTED_CLIENTS.join(", ")}, all.`,
+      2,
+    );
+  }
+  const expanded = requested.includes("all") ? SUPPORTED_CLIENTS : requested;
+  return [...new Set(expanded)];
+}
+
 export function parseArgs(argv) {
   if (argv.includes("--help") || argv.includes("-h")) {
     return { help: true };
@@ -78,13 +104,25 @@ export function parseArgs(argv) {
   }
 
   const options = {
+    targets: [],
+    targetsSpecified: false,
     skillsDir: "",
+    agentsSkillsDir: "",
     dryRun: false,
     yes: false,
     json: false,
   };
   for (let index = 1; index < argv.length; index += 1) {
     const argument = argv[index];
+    if (argument === "--targets") {
+      index += 1;
+      if (!argv[index]) {
+        throw new BootstrapError("--targets requires a comma-separated client list.", 2);
+      }
+      options.targets = parseTargets(argv[index]);
+      options.targetsSpecified = true;
+      continue;
+    }
     if (argument === "--skills-dir") {
       index += 1;
       if (!argv[index]) {
@@ -93,6 +131,14 @@ export function parseArgs(argv) {
       options.skillsDir = argv[index];
       continue;
     }
+    if (argument === "--agents-skills-dir") {
+      index += 1;
+      if (!argv[index]) {
+        throw new BootstrapError("--agents-skills-dir requires a path.", 2);
+      }
+      options.agentsSkillsDir = argv[index];
+      continue;
+    }
     if (argument === "--dry-run") {
       options.dryRun = true;
       continue;
@@ -110,16 +156,25 @@ export function parseArgs(argv) {
   return options;
 }
 
-function defaultSkillsDir(environment) {
-  return environment.CLAUDE_SKILLS_DIR || path.join(homedir(), ".claude", "skills");
+function defaultClaudeSkillsDir(options, environment, platform) {
+  return options.skillsDir
+    || environment.CLAUDE_SKILLS_DIR
+    || path.join(environmentHome(environment, platform), ".claude", "skills");
 }
 
-export function resolveLayout(options, environment = process.env, bundledSkillDir = BUNDLED_SKILL_DIR) {
-  const skillsDir = path.resolve(options.skillsDir || defaultSkillsDir(environment));
-  const workflowDir = path.join(skillsDir, "msdevflow");
+function defaultAgentsSkillsDir(options, environment, platform) {
+  return options.agentsSkillsDir
+    || path.join(environmentHome(environment, platform), ".agents", "skills");
+}
+
+function createSkillLayout(kind, clients, skillsDir, bundledSkillDir) {
+  const resolvedSkillsDir = path.resolve(skillsDir);
+  const workflowDir = path.join(resolvedSkillsDir, "msdevflow");
   const bundledWorkflowDir = path.resolve(bundledSkillDir);
   return {
-    skillsDir,
+    kind,
+    clients,
+    skillsDir: resolvedSkillsDir,
     workflowDir,
     workflowManifest: path.join(workflowDir, "SKILL.md"),
     pythonRequirements: path.join(workflowDir, "scripts", "requirements.txt"),
@@ -129,6 +184,58 @@ export function resolveLayout(options, environment = process.env, bundledSkillDi
   };
 }
 
+export function resolveLayout(options, environment = process.env, bundledSkillDir = BUNDLED_SKILL_DIR) {
+  return createSkillLayout(
+    "claude",
+    ["claude"],
+    defaultClaudeSkillsDir(options, environment, process.platform),
+    bundledSkillDir,
+  );
+}
+
+export function resolveLayouts(
+  options,
+  clients,
+  environment = process.env,
+  bundledSkillDir = BUNDLED_SKILL_DIR,
+  platform = process.platform,
+) {
+  const layouts = [];
+  const openCodeUsesClaude = clients.includes("opencode") && clients.includes("claude");
+  if (clients.includes("claude")) {
+    layouts.push(createSkillLayout(
+      "claude",
+      openCodeUsesClaude ? ["claude", "opencode"] : ["claude"],
+      defaultClaudeSkillsDir(options, environment, platform),
+      bundledSkillDir,
+    ));
+  }
+  if (clients.includes("codex") || (clients.includes("opencode") && !openCodeUsesClaude)) {
+    const sharedClients = clients.includes("codex") ? ["codex"] : [];
+    if (clients.includes("opencode")) {
+      sharedClients.push("opencode");
+    }
+    layouts.push(createSkillLayout(
+      "agents",
+      sharedClients,
+      defaultAgentsSkillsDir(options, environment, platform),
+      bundledSkillDir,
+    ));
+  }
+  const unique = new Map();
+  for (const layout of layouts) {
+    const key = normalizedPath(layout.workflowDir, platform);
+    const existing = unique.get(key);
+    if (existing) {
+      existing.clients = [...new Set([...existing.clients, ...layout.clients])];
+      existing.kind = "shared";
+    } else {
+      unique.set(key, layout);
+    }
+  }
+  return [...unique.values()];
+}
+
 function namedCommand(command, args, platform) {
   return executableCommand(platform === "win32" && command === "npm" ? "npm.cmd" : command, args, platform);
 }
@@ -386,6 +493,51 @@ export function resolveExecutable(name, run, platform) {
   return result.status === 0 ? firstOutputLine(result.stdout) : "";
 }
 
+export function detectClients(run, platform) {
+  return SUPPORTED_CLIENTS.filter((client) => Boolean(resolveExecutable(client, run, platform)));
+}
+
+async function selectClientTargets(input, output, promptOutput = output) {
+  if (!input.isTTY || !output.isTTY) {
+    throw new BootstrapError(
+      "No supported agent client was detected. Non-interactive setup requires --targets <clients>.",
+      2,
+    );
+  }
+  promptOutput.write("No supported agent client was detected. Available targets: claude, codex, opencode, all.\n");
+  const terminal = createInterface({ input, output: promptOutput });
+  try {
+    const answer = await terminal.question("Install msdevflow for: ");
+    return parseTargets(answer);
+  } finally {
+    terminal.close();
+  }
+}
+
+async function resolveClientTargets(options, run, platform, selectClients) {
+  if (options.targetsSpecified) {
+    return { clients: options.targets, source: "explicit", detected: [] };
+  }
+  if (options.skillsDir) {
+    return { clients: ["claude"], source: "legacy-skills-dir", detected: [] };
+  }
+  const detected = detectClients(run, platform);
+  if (detected.length) {
+    return { clients: detected, source: "detected", detected };
+  }
+  const clients = await selectClients();
+  return { clients, source: "selected", detected: [] };
+}
+
+function clientTargetWarnings(clients, layouts) {
+  if (clients.includes("opencode") && layouts.length > 1) {
+    return [
+      "OpenCode can discover msdevflow from both installed paths; keep both copies managed by this setup to prevent version drift.",
+    ];
+  }
+  return [];
+}
+
 function normalizedPath(value, platform) {
   const normalized = value.replaceAll("\\", "/").replace(/\/+$/, "");
   return platform === "win32" ? normalized.toLowerCase() : normalized;
@@ -677,10 +829,16 @@ function safeAuthStatus(output) {
 
 function printPlan(plan, write) {
   write("Setup plan (no changes made yet):");
-  write(`  Skills directory: ${plan.layout.skillsDir}`);
-  write(`  Bundled skill: ${plan.skillInstall.source}`);
-  write(`  Skill target: ${plan.skillInstall.target}`);
-  write(`  Skill action: ${plan.skillInstall.status}`);
+  write(`  Client targets: ${plan.clientTargets.clients.join(", ")} (${plan.clientTargets.source})`);
+  write(`  Bundled skill: ${plan.skillInstalls[0].details.source}`);
+  for (const { layout, details } of plan.skillInstalls) {
+    write(`  Skill target: ${details.target}`);
+    write(`    Clients: ${layout.clients.join(", ")}`);
+    write(`    Action: ${details.status}`);
+  }
+  for (const warning of plan.clientTargets.warnings) {
+    write(`  Warning: ${warning}`);
+  }
   write(`  Existing gitcode: ${plan.diagnosis.classification}`);
   if (plan.diagnosis.existingExecutable) {
     write(`  Existing executable: ${plan.diagnosis.existingExecutable}`);
@@ -781,7 +939,13 @@ function authenticateGitcode(cliExecutable, authentication, run, platform, write
 
 function textResult(result, write) {
   write("Setup completed:");
-  write(`  Skill: ${result.skill.status} at ${result.skill.target}`);
+  write(`  Client targets: ${result.clients.join(", ")}`);
+  for (const skill of result.skills) {
+    write(`  Skill: ${skill.status} at ${skill.target} (${skill.clients.join(", ")})`);
+  }
+  for (const warning of result.warnings) {
+    write(`  Warning: ${warning}`);
+  }
   write(`  Workflow CLI command: ${result.gitcode.command}`);
   write(`  GitCode CLI: ${result.gitcode.version}`);
   write(`  Required capabilities: ${result.gitcode.capabilities}`);
@@ -800,8 +964,31 @@ export async function runSetup(options, dependencies = {}) {
   const run = dependencies.run || execute;
   const write = dependencies.write || ((line) => console.log(line));
   const writePlan = dependencies.writePlan || write;
-  const layout = resolveLayout(options, environment, dependencies.bundledSkillDir);
-  const skillInstall = skillInstallDetails(layout);
+  const targetSelection = await resolveClientTargets(
+    options,
+    run,
+    platform,
+    dependencies.selectClients || (() => selectClientTargets(
+      process.stdin,
+      process.stdout,
+      options.json ? process.stderr : process.stdout,
+    )),
+  );
+  const layouts = resolveLayouts(
+    options,
+    targetSelection.clients,
+    environment,
+    dependencies.bundledSkillDir,
+    platform,
+  );
+  const skillInstalls = layouts.map((layout) => ({
+    layout,
+    details: skillInstallDetails(layout),
+  }));
+  const clientTargets = {
+    ...targetSelection,
+    warnings: clientTargetWarnings(targetSelection.clients, layouts),
+  };
 
   if (Number(process.versions.node.split(".")[0]) < 18) {
     throw new BootstrapError(`Node.js >=18 is required; found ${process.version}.`, 2);
@@ -830,11 +1017,12 @@ export async function runSetup(options, dependencies = {}) {
   run({ command: python.executable, args: ["-m", "pip", "--version"] });
   const pipInvocation = {
     command: python.executable,
-    args: ["-m", "pip", "install", "-r", layout.bundledPythonRequirements],
+    args: ["-m", "pip", "install", "-r", layouts[0].bundledPythonRequirements],
   };
   const plan = {
-    layout,
-    skillInstall,
+    clientTargets,
+    layouts,
+    skillInstalls,
     diagnosis,
     installInvocation,
     gitcodeInstall,
@@ -872,14 +1060,19 @@ export async function runSetup(options, dependencies = {}) {
     options.json ? writePlan : write,
     options.json,
   );
-  const skillStatus = installBundledSkill(skillInstall);
-  return {
+  const skills = skillInstalls.map(({ layout, details }) => ({
+    kind: layout.kind,
+    clients: layout.clients,
+    status: installBundledSkill(details),
+    target: layout.workflowDir,
+  }));
+  const result = {
     state: "ready",
     git: gitVersion,
-    skill: {
-      status: skillStatus,
-      target: layout.workflowDir,
-    },
+    clients: clientTargets.clients,
+    targetSource: clientTargets.source,
+    warnings: clientTargets.warnings,
+    skills,
     gitcode,
     python: {
       executable: python.executable,
@@ -888,6 +1081,10 @@ export async function runSetup(options, dependencies = {}) {
       chromium: "not-downloaded",
     },
   };
+  if (skills.length === 1) {
+    result.skill = skills[0];
+  }
+  return result;
 }
 
 export async function main(argv, dependencies = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "msdevflow",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Install the msdevflow GitCode skill and its runtime dependencies",
   "type": "module",
   "bin": {

package/skill/msdevflow/README.md

@@ -55,6 +55,8 @@ discover -> issue -> develop -> pr -> ci
 
 ## 4. 调用示例
 
+以下示例使用 Claude Code 的 `/msdevflow` 形式。Codex 使用 `$msdevflow`、`/skills` 或隐式匹配；OpenCode 使用 skill 工具或隐式匹配。无论客户端入口如何，正文中的 `action=<name>` 和其余任务参数保持相同。
+
 ### 未指定 action：完整 E2E
 
 ```text
@@ -174,7 +176,7 @@ PR：https://gitcode.com/Ascend/example/pulls/456
 
 需要：
 
-- Claude Code 或其他兼容 Agent Skills 的客户端；
+- Claude Code、Codex 或 OpenCode；
 - `git`；
 - GitCode 官方 npm CLI；
 - GitCode CLI 已认证；
@@ -214,33 +216,46 @@ npm 包同时携带 `msdevflow` skill 和 setup 程序。标准安装只需要
 npx msdevflow setup
 ```
 
-`setup` 先展示 skill 目标、安装或更新状态、GitCode CLI 归属、registry、安装模式、Python 依赖命令和认证方式；用户确认后，在同一次运行中：
+`setup` 默认检测 PATH 中的 Claude Code、Codex 和 OpenCode，先展示客户端、物理 skill 目标、安装或更新状态、GitCode CLI 归属、registry、安装模式、Python 依赖命令和认证方式；用户确认后，在同一次运行中：
 
-1. 安装或更新 `~/.claude/skills/msdevflow`；
+1. 从 npm 包内唯一源码 `skill/msdevflow` 原子安装或更新所需受管副本；
 2. 安装或升级官方 GitCode npm CLI；
 3. 安装内置 `scripts/requirements.txt` 中的 Python Playwright 包；
 4. 验收 workflow 所需 schema/API；
 5. CLI 未认证时运行选定命令的 `auth login --web`。
 
-可选只读预检：
+客户端到物理目录的映射：
 
-```bash
-npx msdevflow setup --dry-run
+```text
+Claude Code            -> ~/.claude/skills/msdevflow
+Codex                  -> ~/.agents/skills/msdevflow
+仅 OpenCode            -> ~/.agents/skills/msdevflow
+OpenCode + Claude Code -> 复用 Claude 目标
+OpenCode + Codex       -> 复用 Agent Skills 目标
+Claude Code + Codex    -> 两个受管副本
+三者同时安装           -> 两个受管副本，并提示 OpenCode 双路径发现
 ```
 
-自定义 skills 目录时使用：
+显式选择客户端、只读预检或自定义目录：
 
 ```bash
-npx msdevflow setup --skills-dir "<skills-directory>"
+npx msdevflow setup --targets claude
+npx msdevflow setup --targets codex,opencode
+npx msdevflow setup --targets all
+npx msdevflow setup --dry-run --targets all
+npx msdevflow setup --skills-dir "<claude-skills-directory>"
+npx msdevflow setup --agents-skills-dir "<shared-agent-skills-directory>"
 ```
 
+没有检测到客户端时，交互运行要求选择目标，非交互运行要求 `--targets`。`--skills-dir` 单独使用时保留旧语义，只安装 Claude Code 目标。Trae 的目录与兼容细节尚未可靠验证，因此当前不属于支持目标。
+
 npm 包尚未发布时，可从当前源码/发布目录运行等价入口：
 
 ```bash
 node ./msdevflow/bin/msdevflow.js setup
 ```
 
-`setup` 不下载或启动 Chromium。凭证只由 GitCode CLI 和官方浏览器流程接收与保存；setup 不读取、输出或转存 Token，也不要求用户把 Token 传给 Agent。已有 skill 目标只有 manifest 明确标识为 `msdevflow` 时才允许更新，来源不明的目录、文件或符号链接会被拒绝覆盖。安装后建议重新启动 Claude Code 会话。
+`setup` 不下载或启动 Chromium。凭证只由 GitCode CLI 和官方浏览器流程接收与保存；setup 不读取、输出或转存 Token，也不要求用户把 Token 传给 Agent。每个已有 skill 目标只有 manifest 明确标识为 `msdevflow` 时才允许更新，来源不明的目录、文件或符号链接会被拒绝覆盖。安装后重启或重新加载对应客户端。
 
 ## 7. 仓库画像和 PR 模板
 

package/skill/msdevflow/SKILL.md

@@ -2,8 +2,9 @@
 name: msdevflow
 description: >
   通用 GitCode Issue 到 PR 合入工作流。未指定 action 时，从环境与仓库画像开始，按远端和本地证据幂等推进完整作者流程；也支持通过 action=discover、create-issue、issue、develop、pr、ci、openlibing-auth、feedback、code-review 或 merge 只执行单个能力。适用于发现、新建或接取 GitCode Issue、开发并创建 PR、处理 CI、验证 openLiBing OAuth、处理自己 PR 的检视意见、检视他人 PR，以及在独立审批和显式确认后合入。仅适用于已授权的 GitCode 仓库。
+compatibility: Requires Git, Node.js >=18, Python >=3.10, GitCode access, and the setup-installed GitCode CLI. Supports Claude Code, Codex, and OpenCode.
 metadata:
-  version: 1.9.0
+  version: 2.0.0
   source: msdevflow
 ---