@jspg-ai/coding-bb 0.0.2-beta.24 → 0.0.2-beta.26

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) {

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/openspec/config.yaml

@@ -7,20 +7,6 @@ context: |
   语言：中文（简体）
   所有文档必须使用中文简体编写，但技术术语保持英文，如 API、REST、RPC、MQ 等。
 
-  # Java 技术栈
-
-  ## 核心框架
-  - Java 1.8 或 Java 21
-  - Spring Boot 2.0.4.RELEASE
-  - Ironman 1.3.19
-
-  ## 中间件
-  - 数据库：Zebra 分库分表 (Ironman-SQL)
-  - RPC：Pigeon (Ironman-RPC)
-  - 消息队列：RocketMQ (Ironman-MQ)
-  - 缓存：Redis (Ironman-Redis)
-  - 配置中心：Lion (Ironman-Config)
-
   ## 文档写作原则
   - 每个章节先给结论或概览，再展开细节
   - 用业务语言描述目标和规则，用技术语言描述实现方式

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.24",
+  "version": "0.0.2-beta.26",
   "description": "整合业界热门且高价值的工具、框架与技能，为 AI CODING AGENT 提供统一的行为准则与工作流，辅助开发者将需求高效落地为符合规范的代码",
   "main": "cbb/lib/install/init.js",
   "bin": {