@jspg-ai/coding-bb 0.0.2-beta.25 → 0.0.2-beta.27

package/cbb/lib/install/init.js

@@ -1024,9 +1024,10 @@ async function init(targetDir, options = {}) {
 /**
  * 为 workspace 根目录安装 AI 配置子集（由 cbb setup 调用）。
  *
- * 只装 worktree 生命周期管理（init/close/push）+ openspec 运行时配置，
- * 不装 base 工作流、编码规范、superpowers、版本检查 hook--这些属于 sandbox worktree
- * 内的开发配置，由 worktree 内 `cbbm init --yes` 完整模式安装。在 workspace 根目录
+ * 只装 worktree 生命周期管理（init/close/push）+ openspec 运行时配置 + 空间导航
+ * AGENTS.md（仅缺失时生成，永不覆盖），不装 base 工作流、编码规范、superpowers、
+ * 版本检查 hook--这些属于 sandbox worktree 内的开发配置，由 worktree 内
+ * `cbbm init --yes` 完整模式安装。在 workspace 根目录
  * （主分支）装 base 工作流会诱导绕过 worktree 直接在主分支做需求开发。
  */
 async function installWorkspaceConfig(targetDir, options = {}) {
@@ -1106,6 +1107,9 @@ async function installWorkspaceConfig(targetDir, options = {}) {
   const openspecRes = setupOpenSpec(isUpgrade, managedPaths);
   newPaths.add('openspec/config.yaml');
 
+  // 空间导航文件 AGENTS.md：仅缺失时生成，永不覆盖（不登记清单，卸载不删）
+  const agentsMdState = workspaces.ensureWorkspaceAgentsMd(TARGET_DIR);
+
   // 升级时清理旧路径（workspace 曾装过的 base 工作流等不属于此子集，删除）
   const cleaned = [];
   const keptDocs = [];
@@ -1139,6 +1143,7 @@ async function installWorkspaceConfig(targetDir, options = {}) {
   if (openspecRes.installed.length > 0) {
     parts.push(`openspec ${openspecRes.defaultSchema || openspecRes.installed.join('/')}`);
   }
+  if (agentsMdState === 'created') parts.push('AGENTS.md（空间导航）');
   const configLabel = 'AI 配置';
   step('✓', configLabel, parts.join(' · '));
   if (cleaned.length > 0) {
@@ -1155,16 +1160,16 @@ async function installWorkspaceConfig(targetDir, options = {}) {
 // ── cbb setup 命令 ──────────────────────────────────────
 
 /**
- * 若 targetDir 已安装（.cbb/.managed-by-cbb 存在），比较已装版本与当前包版本决定是否继续。
+ * 若 targetDir 已安装，比较已装版本与当前包版本决定是否继续安装。
  *  - 版本一致 → 返回 'skip'（不询问、不重复安装）
- *  - 版本不同 → 询问是否升级到当前包版本，用户拒绝返回 'cancel'
+ *  - 版本不同 → 返回 'install'（setup 已整体确认过，直接升级到当前包版本，不再二次询问）
  *  - 未安装 → 返回 'install'（不提示，直接继续）
  *
  * 注：只比较「已装版本 vs 当前包版本」——安装动作只能落盘当前包的产物，
  * registry 是否有更新由用户级版本检查 hook 提醒，不在此处联网查询。
- * @returns {Promise<'install'|'skip'|'cancel'>}
+ * @returns {'install'|'skip'}
  */
-async function confirmUpgradeIfInstalled(targetDir) {
+function decideUpgradeIfInstalled(targetDir) {
   const installed = version.readInstalledVersion(targetDir);
   if (!installed) return 'install'; // 未安装：不提示，直接继续
 
@@ -1177,11 +1182,6 @@ async function confirmUpgradeIfInstalled(targetDir) {
   }
 
   step('⏳', '版本', `v${installed} → v${pkg.version}`, { iconColor: 'cyan' });
-  const answer = await ask(`? 升级到 v${pkg.version}？(Y/n) `);
-  if (answer && answer.toLowerCase() === 'n') {
-    step('!', '版本', '已跳过安装/升级', { iconColor: 'yellow' });
-    return 'cancel';
-  }
   return 'install';
 }
 
@@ -1474,11 +1474,8 @@ async function initSingleWorkspace(w, opts = {}) {
     console.log(`      ${c('gray', `${names} → 编辑 workspace-config.json 填入真实仓库地址`)}`);
   }
 
-  // 5. 若已安装：版本未变化直接跳过；有新版本需用户确认；用户拒绝则跳过本 workspace
-  const decision = await confirmUpgradeIfInstalled(targetDir);
-  if (decision === 'cancel') {
-    return { ok: false, error: 'USER_CANCELLED', skipped: true };
-  }
+  // 5. 若已安装：版本未变化直接跳过；有新版本直接升级（setup 已整体确认过，不再二次询问）
+  const decision = decideUpgradeIfInstalled(targetDir);
   if (decision === 'skip') {
     return { ok: true, subdir: subdirName, upToDate: true };
   }
@@ -1501,7 +1498,6 @@ function describeBatchError(r) {
     case 'CLONE_FAILED':    return `git clone 失败：${r.message || ''}`.trim();
     case 'PULL_FAILED':     return `工作空间仓库同步失败：${r.message || ''}`.trim();
     case 'CONFIG_INVALID':  return `workspace-config.json 不合法：${r.message || ''}`.trim();
-    case 'USER_CANCELLED':  return '用户取消升级';
     case 'INIT_FAILED':     return `初始化失败：${r.message || ''}`.trim();
     default:                return r.error || '未知错误';
   }

package/cbb/lib/install/workspaces.js

@@ -8,6 +8,7 @@
  *  - 加载 + 校验
  *  - 归一化 remote URL（兼容 SSH / HTTPS 两种写法）
  *  - 检测当前目录是否已拉取指定 workspace 的仓库
+ *  - 空间种子文件生成（AGENTS.md 空间导航，仅缺失时）
  */
 
 const fs = require('fs');
@@ -16,6 +17,7 @@ const { execSync } = require('child_process');
 
 const DEFAULT_CONFIG = 'config/workspaces.json';
 const SAMPLE_CONFIG  = 'config/workspace-config.sample.json';
+const SAMPLE_AGENTS_MD = 'config/workspace-agents.sample.md';
 
 /**
  * 归一化 git remote URL：提取 "namespace/repo" 形式（去掉 .git 后缀）。
@@ -166,6 +168,24 @@ function validateWorkspaceConfig(configPath) {
   return { valid: true, config: raw };
 }
 
+/**
+ * 确保业务空间根目录存在 AGENTS.md（空间导航文件，讲清目录职责与协作约定）。
+ *
+ * 仅缺失时从包内模板复制；已存在（可能含团队自维护内容）一律不覆盖。
+ * 该文件不登记安装清单，升级 / 卸载均不触碰。
+ *
+ * @param {string} targetDir 业务空间根目录
+ * @returns {'exists' | 'created'}
+ */
+function ensureWorkspaceAgentsMd(targetDir) {
+  const agentsPath = path.join(targetDir, 'AGENTS.md');
+  if (fs.existsSync(agentsPath)) return 'exists';
+
+  const samplePath = path.resolve(__dirname, '..', '..', '..', SAMPLE_AGENTS_MD);
+  fs.copyFileSync(samplePath, agentsPath);
+  return 'created';
+}
+
 /**
  * 在指定目录执行 `git remote -v`，解析出 [{ name, url }] 列表。
  * 任何异常静默返回空数组，便于上层用 state 机判定。
@@ -259,10 +279,12 @@ function findSampleApps(apps) {
 module.exports = {
   DEFAULT_CONFIG,
   SAMPLE_CONFIG,
+  SAMPLE_AGENTS_MD,
   normalizeRepoUrl,
   matchesConfiguredRepo,
   loadWorkspaces,
   validateWorkspaceConfig,
+  ensureWorkspaceAgentsMd,
   readGitRemotes,
   detectRepo,
   extractRepoBasename,

package/config/workspace-agents.sample.md

@@ -0,0 +1,37 @@
+# 业务空间使用说明（AI Agent 导航）
+
+本目录是由 `@jspg-ai/coding-bb` 初始化的**多仓库联动开发业务空间**。
+进入本目录工作时，请先按本文件理解目录职责与协作约定，再动手。
+
+## 核心约定
+
+1. **本目录不做需求开发**。本目录（业务空间主分支）只负责组织与调度；所有需求开发都在 `.worktrees/worktree-<需求名>/` 隔离目录内进行。
+2. **接到新需求先建 worktree**：在本目录执行 `/cbb:worktree-init <需求名>`（opencode 写法：`/cbb-worktree-init`）。它会为 `workspace-config.json` 中的全量关联应用同步创建同名 worktree，并自动安装沙箱内的编码规范与 OpenSpec 工作流。
+3. **开发动作全部在 worktree 内**：需求提案 / 实现 / 验证 / 归档（`/opsx:propose` → `/opsx:apply` → `/opsx:verify` → `/opsx:archive`）在 worktree 沙箱内执行；跨仓库提交推送用 `/cbb:worktree-push`，需求收尾用 `/cbb:worktree-close`。
+4. **关联应用增减只改配置**：编辑 `workspace-config.json` 的 `apps` 数组（`name` / `repo` / `side` / `desc`），然后用同一需求名重跑 worktree 初始化即幂等补齐；不要手工 `git clone` 应用仓库。
+5. **不要绕过 worktree 直接修改 `.codespace/` 或本目录的代码**。`.codespace/` 是工具维护的基准代码，不是开发区。
+
+## 目录结构与职责
+
+| 路径 | 职责 | 维护方式 |
+|------|------|----------|
+| `workspace-config.json` | 关联应用清单，所有应用联动的唯一数据源 | 人工编辑 |
+| `.codespace/` | 各关联应用的基准代码（每个应用一个子目录） | `cbb setup` 与 worktree 流程自动 clone / fetch；**勿手动编辑**；已 gitignore，不提交 |
+| `.worktrees/` | 需求隔离开发区（每个需求一个 `worktree-<需求名>/` 目录） | worktree 命令自动创建 / 清理；不提交（首次执行 worktree 流程时自动加入 .gitignore） |
+| `openspec/` | OpenSpec 工作流配置（`config.yaml` + `schemas/`） | 由 cbb 安装；需求变更产物（`openspec/changes/` 等）在 worktree 内生成，随需求分支提交 |
+| `.claude/` `.qoder/` `.opencode/` | AI 工具适配目录：worktree 管理技能与命令；**故意不含**编码规范（防止在空间根直接开发） | 由 cbb 按 setup 时选择的工具安装；已 gitignore，不提交，勿手动改 |
+| `.cbb/` | cbb 安装清单，记录本包管理的全部路径 | 由 cbb 管理；**勿手动编辑** |
+
+## 典型流程
+
+```
+本目录：/cbb:worktree-init <需求名>
+  → .worktrees/worktree-<需求名>/ 内开发（/opsx:propose → /opsx:apply → /opsx:verify → /opsx:archive）
+  → /cbb:worktree-push 推送 → 合并后 /cbb:worktree-close 关闭
+```
+
+> 命令写法因 AI 工具而异：Claude Code / Qoder 为 `/cbb:worktree-init`，opencode 为 `/cbb-worktree-init`；`/opsx:*` 同理（opencode 为 `/opsx-*`）。
+
+---
+
+本文件由 `@jspg-ai/coding-bb` 生成（仅缺失时写入，之后不会覆盖或删除，可自由增补团队约定）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jspg-ai/coding-bb",
-  "version": "0.0.2-beta.25",
+  "version": "0.0.2-beta.27",
   "description": "整合业界热门且高价值的工具、框架与技能，为 AI CODING AGENT 提供统一的行为准则与工作流，辅助开发者将需求高效落地为符合规范的代码",
   "main": "cbb/lib/install/init.js",
   "bin": {