@autobest-ui/agent 1.0.0

package/README.md

@@ -0,0 +1,182 @@
+# @autobest-ui/agent
+
+Autobest 面向 Codex 等智能体发布的 Skills、Plugins 和 MCP 服务集合。
+
+## Skills
+
+Common Skills 对当前用户全局生效，安装到 `~/.agents/skills`：
+
+```bash
+npx --yes --package=@autobest-ui/agent@latest autobest-agent-sync common
+```
+
+React Skills 只对单个项目生效。在项目根目录运行，安装到该项目的 `.agents/skills`：
+
+```bash
+npx --yes --package=@autobest-ui/agent@latest autobest-agent-sync react
+```
+
+也可以把项目绝对路径作为最后一个参数。完整的分类、Skill 清单和更新行为见 [Skills 使用说明](skills/README.md)。
+
+## MCP
+
+安装 Node.js 20 或更高版本后，无需在业务项目中安装依赖，可以直接通过 `npx` 启动 MCP：
+
+```bash
+npx --yes --package=@autobest-ui/agent@latest autobest-rag-mcp
+npx --yes --package=@autobest-ui/agent@latest autobest-azurepr-mcp
+```
+
+同一个 npm 包暴露两个独立命令：
+
+| 命令                   | 用途                           | 必需配置           |
+| ---------------------- | ------------------------------ | ------------------ |
+| `autobest-rag-mcp`     | 连接 PRD Knowledge RAG API     | `RAG_API_BASE_URL` |
+| `autobest-azurepr-mcp` | 读取 Azure DevOps Pull Request | `AZURE_DEVOPS_PAT` |
+
+Codex 配置示例分别位于：
+
+- [RAG MCP 配置](mcp/rag-mcp-bridge/config.toml.example)
+- [Azure PR MCP 配置](mcp/azurepr-mcp-bridge/config.toml.example)
+
+生产环境可将 `@latest` 替换为明确版本，以固定 MCP 行为。
+
+如果 `@autobest-ui` 发布在私有 npm registry，使用前需要在 npm 的 `.npmrc` 中配置该 scope 对应的 registry 和认证信息。
+
+## Plugin
+
+Autobest Delivery 将交付闭环 Skills 和隔离的 Playwright MCP 运行器作为一个 Codex Plugin 安装。需要 Node.js 20 或更高版本，以及支持 `codex plugin` 命令的 Codex CLI。
+
+安装或更新：
+
+```bash
+npx --yes --package=@autobest-ui/agent@latest autobest-delivery-setup
+```
+
+安装器会下载固定版本的运行依赖和 Chromium，将插件持久化到 `~/.autobest-agent/marketplaces/autobest-team`，注册 `autobest-team` 本地市场并安装 `autobest-delivery`。如果同名市场仍指向旧的源码仓库，安装器会自动迁移。完成后重启 Codex，并在新会话中使用插件。
+
+卸载：
+
+```bash
+npx --yes --package=@autobest-ui/agent@latest autobest-delivery-setup uninstall
+```
+
+生产环境可以把 `@latest` 替换为明确版本。插件能力、运行隔离和本地开发验证见 [Autobest Delivery 使用说明](plugins/autobest-delivery/README.md)。
+
+## 发布前本地联调
+
+尚未发布到 npm 时，建议先生成本地 tarball，再通过 `npx --package=<tarball>` 调用。该方式会使用 npm 最终发布的文件清单和 `bin` 配置，比直接运行源码更接近发布后的真实行为。
+
+### 1. 生成本地 npm 包
+
+进入本目录并生成 tarball：
+
+```bash
+cd /Users/autobest/repo-ui/AutobestFrontendCommon/packages/agents
+AGENT_TARBALL="$(npm pack --silent)"
+AGENT_TARBALL_PATH="$PWD/$AGENT_TARBALL"
+printf '%s\n' "$AGENT_TARBALL_PATH"
+```
+
+后续步骤都在同一个终端中执行，以便继续使用 `AGENT_TARBALL_PATH`。每次修改本包代码后，需要重新执行 `npm pack --silent` 并更新该变量。
+
+### 2. 联调 Plugin
+
+安装或更新 Autobest Delivery：
+
+```bash
+npx --yes \
+  --package="$AGENT_TARBALL_PATH" \
+  autobest-delivery-setup
+```
+
+该命令会真实修改当前用户的 Codex Plugin 配置，并把插件安装到 `~/.autobest-agent/marketplaces/autobest-team`。执行完成后重启 Codex，在新会话中验证插件。
+
+联调结束后如需卸载：
+
+```bash
+npx --yes \
+  --package="$AGENT_TARBALL_PATH" \
+  autobest-delivery-setup uninstall
+```
+
+### 3. 联调 Skills
+
+安装全局 Common Skills：
+
+```bash
+npx --yes \
+  --package="$AGENT_TARBALL_PATH" \
+  autobest-agent-sync common
+```
+
+在需要联调的项目根目录安装 React Skills：
+
+```bash
+cd /absolute/path/to/target-project
+npx --yes \
+  --package="$AGENT_TARBALL_PATH" \
+  autobest-agent-sync react
+```
+
+Common Skills 会写入 `~/.agents/skills`，React Skills 会写入目标项目的 `.agents/skills`。
+
+### 4. 直接启动 MCP
+
+RAG MCP：
+
+```bash
+RAG_API_BASE_URL=http://127.0.0.1:3000 \
+npx --yes \
+  --package="$AGENT_TARBALL_PATH" \
+  autobest-rag-mcp
+```
+
+Azure PR MCP：
+
+```bash
+AZURE_DEVOPS_PAT=your-token \
+npx --yes \
+  --package="$AGENT_TARBALL_PATH" \
+  autobest-azurepr-mcp
+```
+
+MCP 使用 stdio 协议，启动后持续等待客户端请求属于正常行为，可按 `Ctrl+C` 停止。
+
+### 5. 在 Codex 中联调 MCP
+
+Codex 的启动目录不固定，因此 `config.toml` 中必须填写 tarball 的绝对路径，不能使用 `AGENT_TARBALL_PATH` 变量或相对路径。将下面的 `/absolute/path/to/autobest-ui-agent-x.y.z.tgz` 替换为第 1 步输出的实际路径：
+
+```toml
+[mcp_servers.rag-mcp-bridge]
+command = "npx"
+args = [
+  "--yes",
+  "--package=/absolute/path/to/autobest-ui-agent-x.y.z.tgz",
+  "autobest-rag-mcp"
+]
+
+[mcp_servers.rag-mcp-bridge.env]
+RAG_API_BASE_URL = "http://127.0.0.1:3000"
+
+[mcp_servers.azurepr-mcp-bridge]
+command = "npx"
+args = [
+  "--yes",
+  "--package=/absolute/path/to/autobest-ui-agent-x.y.z.tgz",
+  "autobest-azurepr-mcp"
+]
+
+[mcp_servers.azurepr-mcp-bridge.env]
+AZURE_DEVOPS_PAT = "your-token"
+```
+
+修改 `config.toml` 后重启 Codex，再从新会话调用对应 MCP 工具。重新打包后如果 tarball 文件名或路径发生变化，需要同步更新 `config.toml`。
+
+## 本地验证
+
+在 `packages/agents` 目录安装依赖后运行：
+
+```bash
+npm test
+```

package/bin/sync-assets.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+
+import { access, cp, mkdir, readdir, stat } from "node:fs/promises";
+import { realpathSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  ".."
+);
+
+const usage = `Usage:
+  autobest-agent-sync common
+  autobest-agent-sync react [project-directory]
+
+Scopes:
+  common  Install shared skills to ~/.agents/skills
+  react   Install React skills to <project-directory>/.agents/skills`;
+
+async function skillDirectories(sourceRoot) {
+  const entries = await readdir(sourceRoot, { withFileTypes: true });
+  const names = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    try {
+      await access(path.join(sourceRoot, entry.name, "SKILL.md"));
+      names.push(entry.name);
+    } catch {
+      // Only directories containing SKILL.md are installable skills.
+    }
+  }
+
+  return names.sort((left, right) => left.localeCompare(right));
+}
+
+export function skillsTarget(scope, options = {}) {
+  if (scope === "common") {
+    return path.join(options.userHome ?? os.homedir(), ".agents", "skills");
+  }
+  if (scope === "react") {
+    return path.join(
+      path.resolve(options.projectDirectory ?? process.cwd()),
+      ".agents",
+      "skills"
+    );
+  }
+  throw new Error(`Unsupported skill scope: ${scope}`);
+}
+
+export async function syncSkills(scope, options = {}) {
+  if (scope !== "common" && scope !== "react") {
+    throw new Error(`Unsupported skill scope: ${scope}`);
+  }
+
+  const sourceRoot = path.join(packageRoot, "skills", scope);
+  const targetRoot = skillsTarget(scope, options);
+
+  if (scope === "react") {
+    const projectDirectory = path.resolve(
+      options.projectDirectory ?? process.cwd()
+    );
+    const projectStat = await stat(projectDirectory).catch(() => undefined);
+    if (!projectStat?.isDirectory()) {
+      throw new Error(`Project directory does not exist: ${projectDirectory}`);
+    }
+  }
+
+  const skills = await skillDirectories(sourceRoot);
+  if (skills.length === 0) {
+    throw new Error(`No skills found in package scope: ${scope}`);
+  }
+
+  await mkdir(targetRoot, { recursive: true });
+  for (const skill of skills) {
+    await cp(path.join(sourceRoot, skill), path.join(targetRoot, skill), {
+      recursive: true,
+      force: true,
+    });
+  }
+
+  return { scope, skills, targetRoot };
+}
+
+async function main(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(usage);
+    return;
+  }
+
+  const [scope, projectDirectory, ...extraArgs] = args;
+  if (
+    !scope ||
+    extraArgs.length > 0 ||
+    (scope === "common" && projectDirectory)
+  ) {
+    throw new Error(usage);
+  }
+
+  const result = await syncSkills(scope, { projectDirectory });
+  console.log(
+    `Installed ${result.scope} skills to ${
+      result.targetRoot
+    }: ${result.skills.join(", ")}`
+  );
+}
+
+let isCommandEntry = false;
+if (process.argv[1]) {
+  try {
+    isCommandEntry =
+      realpathSync(process.argv[1]) ===
+      realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    isCommandEntry = false;
+  }
+}
+
+if (isCommandEntry) {
+  main(process.argv.slice(2)).catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}

package/bin/sync-assets.test.mjs

@@ -0,0 +1,64 @@
+import assert from "node:assert/strict";
+import { access, mkdtemp, readFile, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { skillsTarget, syncSkills } from "./sync-assets.mjs";
+
+async function withTemporaryDirectory(run) {
+  const directory = await mkdtemp(path.join(os.tmpdir(), "autobest-agent-"));
+  try {
+    await run(directory);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+}
+
+test("installs common skills into the user-level skills directory", async () => {
+  await withTemporaryDirectory(async (userHome) => {
+    const result = await syncSkills("common", { userHome });
+
+    assert.equal(result.targetRoot, path.join(userHome, ".agents", "skills"));
+    assert.deepEqual(result.skills, ["figma-ui-capture", "ui-prd-scope"]);
+    await access(path.join(result.targetRoot, "figma-ui-capture", "SKILL.md"));
+    await access(
+      path.join(
+        result.targetRoot,
+        "ui-prd-scope",
+        "references",
+        "scope-schema.md"
+      )
+    );
+  });
+});
+
+test("installs React skills into one project", async () => {
+  await withTemporaryDirectory(async (projectDirectory) => {
+    const result = await syncSkills("react", { projectDirectory });
+
+    assert.equal(
+      result.targetRoot,
+      path.join(projectDirectory, ".agents", "skills")
+    );
+    assert.deepEqual(result.skills, ["react-code-standards"]);
+    assert.match(
+      await readFile(
+        path.join(result.targetRoot, "react-code-standards", "SKILL.md"),
+        "utf8"
+      ),
+      /name: react-code-standards/
+    );
+  });
+});
+
+test("rejects unsupported scopes and missing project directories", async () => {
+  assert.throws(() => skillsTarget("unknown"), /Unsupported skill scope/);
+  await withTemporaryDirectory(async (directory) => {
+    await assert.rejects(
+      syncSkills("react", {
+        projectDirectory: path.join(directory, "missing-project"),
+      }),
+      /Project directory does not exist/
+    );
+  });
+});

package/mcp/azurepr-mcp-bridge/README.md

@@ -0,0 +1,37 @@
+# azurepr-mcp-bridge
+
+`azurepr-mcp-bridge` 是用于读取 Azure DevOps Pull Request 的本地只读 STDIO MCP 服务。它返回 PR 元数据、评审意见、关联工作项、变更文件路径和文本文件的新增内容。
+
+## 配置
+
+先在启动 Codex 的环境中设置 PAT：
+
+```bash
+export AZURE_DEVOPS_PAT="your-personal-access-token"
+```
+
+PAT 至少需要目标项目的代码读取权限。不要把 PAT 直接写进 `config.toml` 或提交到仓库。将 [config.toml.example](config.toml.example) 中的 MCP 配置加入 Codex 配置后重启 Codex。
+
+服务只接受 `https://dev.azure.com/...` 和 `https://<organization>.visualstudio.com/...` PR 地址，避免将 PAT 转发给非 Azure DevOps 主机。
+
+## 使用
+
+Codex 将通过 npm 安装并启动发布包中的 MCP。也可以手动验证启动命令：
+
+```bash
+npx --yes --package=@autobest-ui/agent@latest autobest-azurepr-mcp
+```
+
+`@latest` 可以替换为明确版本，例如 `@1.0.0`。
+
+工具 `get_azure_pull_request` 接受 PR URL。可以使用 `path` 查询参数限制变更目录：
+
+```text
+https://dev.azure.com/org/project/_git/repo/pullrequest/123?path=/src
+```
+
+运行测试：
+
+```bash
+npm run test:mcp:azurepr
+```