@jennie-shawn/starwork 0.1.0-alpha.2 → 0.1.0-alpha.21

package/docs/m2.8-workspace-naming-optimization-spec.md

@@ -0,0 +1,633 @@
+# M2.8 工作台命名体系优化 SPEC
+
+## 背景
+
+本 SPEC 来自 StarWork 产品规划会话对 `satellite`、`hub`、`kit`、`project` 等概念的重新梳理。
+
+当前产品事实已经逐渐清楚：
+
+- StarWork 面向用户不应该暴露三四种工作台类型。
+- `Satellite` 不应作为独立产品类型存在。
+- `Kit` 是内部结构模板，不适合作为普通用户理解产品时的核心词。
+- `Hub / 中枢` 对普通用户来说偏工程化，不够生活化。
+
+因此需要统一 StarWork 的命名体系，让用户只需要理解两个一目了然的对象：
+
+1. 项目工作台
+2. 项目中心
+
+## 目标
+
+本轮优化目标是统一产品语言、内部协议字段和文档表达，降低用户理解成本。
+
+最终用户应该能用一句话理解 StarWork：
+
+> 你可以创建一个项目工作台；如果你有很多项目，可以创建一个项目中心，用它统一管理多个项目工作台、共享资料、常用 Skill 和跨项目协作记录。
+
+## 核心决策
+
+### 决策 1：正式对外名称使用“项目中心”
+
+`Hub` 的用户侧表达统一改为：
+
+```text
+项目中心
+```
+
+原因：
+
+- 比“中枢”更生活化。
+- 比“主库”更不技术化。
+- 比“多项目管理中枢”更短。
+- 和“项目工作台”天然成对。
+
+内部协议字段仍可保留：
+
+```text
+hub
+```
+
+但对外文档、CLI 文案、Skill 交互应优先说“项目中心”。
+
+### 决策 2：StarWork 对外只讲两种工作台
+
+正式对外概念：
+
+| 用户看到的名称 | 含义 | 内部字段 |
+|---|---|---|
+| 项目工作台 | 一个具体项目的日常工作区 | `workspace_type: project` |
+| 项目中心 | 管理多个项目工作台的共享管理区 | `workspace_type: hub` |
+
+不要再把以下内容作为对外工作台类型：
+
+- Satellite
+- 卫星项目
+- starter
+- local starter
+- matter kit
+- satellite starter
+
+### 决策 3：Satellite 只是关系，不是类型
+
+原来的 `Satellite` 应改为关系描述：
+
+```text
+项目中心里的项目工作台
+```
+
+或更短：
+
+```text
+中心管理的项目工作台
+```
+
+产品解释：
+
+```text
+项目工作台可以独立存在，也可以加入项目中心。
+加入项目中心后，它仍然是项目工作台，只是多了项目中心同步关系。
+```
+
+内部表达可以是：
+
+```text
+Project Workspace + Hub Binding = Hub-managed Project Workspace
+```
+
+中文产品表达：
+
+```text
+项目工作台 + 加入项目中心 = 中心管理的项目工作台
+```
+
+### 决策 4：Kit 是内部模板，不作为用户主概念
+
+用户不需要理解 `Kit`。
+
+对外应使用：
+
+- 创建项目工作台
+- 创建项目中心
+- 从项目中心创建项目工作台
+- 安装场景能力
+- 自定义工作台结构
+
+内部仍可使用：
+
+- `kit: project`
+- `kit: hub`
+- `pack: general`
+- `hub binding`
+- `hub sync overlay`
+
+文档中如必须出现 Kit，应解释为：
+
+```text
+Kit 是 StarWork 内部用来生成工作台基础结构的模板。普通用户通常不需要直接理解或选择 Kit。
+```
+
+## 推荐命名表
+
+### 中文
+
+| 旧说法 | 新说法 | 使用范围 |
+|---|---|---|
+| Hub | 项目中心 | 用户文案、文档、Skill 交互 |
+| 中枢 | 项目中心 | 用户文案、文档、Skill 交互 |
+| 多项目中枢 | 项目中心 | 用户文案、文档、Skill 交互 |
+| Project | 项目工作台 | 用户文案、文档、Skill 交互 |
+| Satellite | 中心管理的项目工作台 | 用户文案、解释性文档 |
+| 卫星项目 | 中心管理的项目工作台 | 用户文案、解释性文档 |
+| Spawn | 从项目中心创建项目工作台 | 文档和 Skill 交互 |
+| Hub Binding | 加入项目中心 / 连接到项目中心 | 文档和 Skill 交互 |
+| Hub Sync | 项目中心同步 | 文档和状态说明 |
+| Kit | 基础模板 / 内部模板 | 仅必要时解释 |
+| Pack | 场景能力 | 用户文案、安装说明 |
+
+### 英文
+
+| Internal | User-facing |
+|---|---|
+| Hub | Project Center |
+| Project | Project Workspace |
+| Satellite | Project Workspace in a Project Center |
+| Hub-managed Project | Hub-managed Project Workspace |
+| Hub Binding | Project Center connection |
+| Hub Sync | Project Center sync |
+| Kit | Internal workspace template |
+| Pack | Scenario Pack / Scenario capability |
+
+## 用户流程文案
+
+### init 选择工作台类型
+
+推荐文案：
+
+```text
+你想创建哪种工作台？
+
+1. 项目工作台
+   适合一个具体项目。比如写作项目、产品项目、客户交付、资料整理。
+
+2. 项目中心
+   适合同时管理多个项目。它会保存共享资料、项目清单、常用 Skill 和跨项目协作记录。
+```
+
+默认推荐：
+
+```text
+如果你只是开始一个具体项目，建议先选“项目工作台”。
+```
+
+不要再说：
+
+```text
+单事务项目
+多事务项目
+卫星项目
+多项目中枢
+starter
+```
+
+### spawn 说明
+
+推荐文案：
+
+```text
+从项目中心创建一个新的项目工作台。
+创建后，项目中心会记录这个项目的位置、名称和协作信息。
+```
+
+不要说：
+
+```text
+生成卫星项目
+创建 satellite starter
+spawn starter
+```
+
+CLI 命令名 `spawn` 可暂时保留，因为它已经是内部和高级用户命令。但文档中要解释为：
+
+```text
+spawn = 从项目中心创建项目工作台
+```
+
+### doctor / audit 说明
+
+对项目工作台：
+
+```text
+检查这个项目工作台的结构是否清楚，AI 是否知道项目状态、当前工作、资料区和成果区在哪里。
+```
+
+对项目中心：
+
+```text
+检查项目中心是否能正确管理项目清单、共享资料、常用 Skill 和跨项目协作记录。
+```
+
+对中心管理的项目工作台：
+
+```text
+检查这个项目工作台是否正确连接到项目中心。
+```
+
+不要让普通用户先理解：
+
+```text
+Hub-like
+Satellite
+Binding
+Overlay
+Preset
+```
+
+这些词可以留在 JSON 或开发 SPEC 中。
+
+## 产品结构调整
+
+### 正式工作台类型
+
+正式保留：
+
+```text
+project
+hub
+```
+
+对应用户表达：
+
+```text
+project = 项目工作台
+hub = 项目中心
+```
+
+### 中心管理项目的判断方式
+
+不再通过 `kit` 或 `workspace_type` 判断是否为 Satellite。
+
+判断逻辑：
+
+```text
+workspace_type: project
++ .starwork/workspace.json 中存在 hub/project center 连接信息
+= 中心管理的项目工作台
+```
+
+推荐内部字段逐步统一为：
+
+```json
+{
+  "workspace_type": "project",
+  "kit": "project",
+  "project_center": {
+    "path": "/path/to/project-center",
+    "project_id": "example-project"
+  }
+}
+```
+
+兼容期可以继续读取旧字段：
+
+```json
+{
+  "hub": {
+    "path": "/path/to/hub",
+    "project_id": "example-project"
+  }
+}
+```
+
+但用户侧文案不展示 `hub`。
+
+### `satellite-starter` 处理
+
+产品判断：
+
+```text
+satellite-starter 不应作为正式 Kit 继续维护。
+```
+
+原因：
+
+- 它会让用户误以为 StarWork 有第三种工作台。
+- 它与 `project` Kit 大量重复。
+- 中心管理关系应该由 `project + project_center binding` 表达，而不是由另一个 Kit 表达。
+
+调整方向：
+
+1. 保留 `project` Kit 作为唯一项目工作台基础模板。
+2. `spawn` 使用 `project` Kit 创建项目工作台。
+3. `spawn` 额外叠加项目中心同步层。
+4. `satellite-starter` 目录从正式 Core Kit 中移除或降级为 legacy fixture。
+5. 文档中不再把 `satellite-starter` 作为用户可选结构。
+
+## 需要调整的模块
+
+### 1. Core
+
+需调整：
+
+- `product/core/kits/kit-structure-reference.md`
+- `product/core/kits/two-kit-architecture-spec.md`
+- `product/core/kits/README.md`
+- `product/core/kits/hub/README.md`
+- `product/core/kits/hub/AGENTS.md`
+- `product/core/capabilities/main-repo-sync/capability.md`
+- `product/core/capabilities/skill-mount/capability.md`
+- `product/core/presets/README.md`
+- `product/core/presets/hub.yaml`
+- `product/core/presets/satellite-starter.yaml`
+
+目标：
+
+- 对外全部改为“项目中心 / 项目工作台”。
+- 明确 `satellite-starter` 不再是正式结构。
+- 将 Satellite 解释为“中心管理关系”，不是 Kit。
+- 把 `Hub` 保留为内部字段和英文协议词。
+
+### 2. CLI
+
+需调整：
+
+- `product/cli/init-spec.md`
+- `product/cli/spawn-spec.md`
+- `product/cli/spawn-blueprint-spec.md`
+- `product/cli/doctor-spec.md`
+- `product/cli/audit-spec.md`
+- `product/cli/repair-spec.md`
+- `product/cli/src/cli.js`
+- `product/cli/test/init.test.js`
+
+目标：
+
+- `init` 用户文案改为“项目工作台 / 项目中心”。
+- `spawn` 文案改为“从项目中心创建项目工作台”。
+- `doctor` / `audit` 报告中减少 `hub`、`satellite`、`starter` 等术语。
+- `spawn --mode starter` 保留为兼容别名，但帮助文案不主推。
+- 新生成的 workspace state 逐步增加 `project_center` 字段。
+- 兼容读取旧 `hub` 字段。
+
+### 3. Skills
+
+需调整：
+
+- `product/skills/starworkInit/SKILL.md`
+- `product/skills/starworkInit-spec.md`
+- `product/skills/starworkDoctor/SKILL.md`
+- `product/skills/starworkDoctor-spec.md`
+- `product/skills/starworkAudit-spec.md`
+- `product/kit-skills/starworkSpawn/SKILL.md`
+- `product/kit-skills/starworkAudit/SKILL.md`
+
+目标：
+
+- Skill 面向用户时说“项目中心”，不说“Hub / 中枢”。
+- `starworkSpawn` 可在内部引用 `spawn`，但对用户解释为“从项目中心创建项目工作台”。
+- `starworkDoctor` 输出升级建议时，避免让用户先理解 `Hub-like`、`Satellite`、`Overlay`。
+- `starworkAudit` 说明为“项目中心巡检它管理的项目工作台”。
+
+### 4. Docs
+
+需调整：
+
+- `README.md`
+- `AGENTS.md`
+- `product/docs/roadmap.md`
+- `product/docs/roadmap.html`
+- `product/docs/product-direction.md`
+- `product/docs/alpha-test-guide.md`
+- `product/docs/agent-install-guide.md`
+- `product/docs/cli-capabilities.html`
+- `product/docs/cli-skill-registry.html`
+- `product/docs/hub-management.html`
+- `product/docs/index.html`
+
+目标：
+
+- 对外统一“项目中心 / 项目工作台”。
+- 删除五类 Kit 的旧说法。
+- 删除或降级 `satellite-starter` 的正式地位。
+- HTML 文档中心也同步新命名。
+
+## 不做的事
+
+本 SPEC 不要求立刻改 CLI 命令名。
+
+暂不改：
+
+```text
+starwork spawn
+starwork audit
+starwork repair
+workspace_type: hub
+kit: hub
+```
+
+原因：
+
+- 命令名和内部字段已有测试和实现依赖。
+- 当前优先级是用户理解和文案一致。
+- 等产品语言稳定后，再考虑是否新增更生活化的命令别名。
+
+可以未来讨论：
+
+```text
+starwork center create
+starwork project create
+starwork center add-project
+```
+
+但 v0.1 不引入。
+
+## 兼容策略
+
+### 旧字段兼容
+
+继续读取：
+
+```text
+hub
+satellite-starter
+starter
+single-light
+```
+
+但新写入和新文案优先使用：
+
+```text
+project
+hub
+project_center
+项目工作台
+项目中心
+```
+
+### 旧文档兼容
+
+历史文档如必须保留旧词，应加说明：
+
+```text
+旧文档中的 Hub / 中枢，在当前产品命名中对应“项目中心”。
+旧文档中的 Satellite / 卫星项目，在当前产品命名中对应“中心管理的项目工作台”。
+```
+
+### 旧 CLI 参数兼容
+
+保留：
+
+```bash
+starwork init --type hub
+starwork spawn --mode starter
+```
+
+但帮助文案改为：
+
+```text
+--type hub      创建项目中心
+--mode starter 兼容旧参数，等同于创建项目工作台
+```
+
+## 实施计划
+
+### Phase 1：产品语言事实源
+
+1. 新增本 SPEC。
+2. 在 `product/docs/README.md` 登记本 SPEC。
+3. 在产品方向文档中写入两类工作台命名。
+4. 确认术语表。
+
+验收：
+
+- 有一个清晰文档能解释“项目中心 / 项目工作台 / 中心管理的项目工作台”。
+- 文档明确 `Satellite` 不再是正式类型。
+
+### Phase 2：文档清理
+
+1. 清理 README 和 roadmap 中的旧五类 Kit 说法。
+2. 清理 HTML 文档标题和导航中的 Hub/Satellite 用户侧表达。
+3. 将 `hub-management.html` 改名或标题改为“项目中心管理”。
+4. alpha 测试文档改成“创建项目中心 / 从项目中心创建项目工作台”。
+
+验收：
+
+- 用户从 README 到 alpha test guide 不需要理解 Satellite。
+- 不再出现 `local-starter`、`local-matter`、`satellite-matter` 作为当前正式结构。
+
+### Phase 3：Skill 交互文案
+
+1. `starworkInit` 改用“项目工作台 / 项目中心”。
+2. `starworkSpawn` 改用“从项目中心创建项目工作台”。
+3. `starworkDoctor` 改用用户可理解的诊断语言。
+4. `starworkAudit` 改为“项目中心巡检项目工作台”。
+
+验收：
+
+- Skill 描述和输出不再要求用户理解 Hub/Satellite/Kit。
+- 给新用户看 Skill 输出时，能直接知道下一步要选什么。
+
+### Phase 4：CLI 文案和状态模型
+
+1. `init --help` 和 dry-run 文案改为“项目工作台 / 项目中心”。
+2. `spawn --help` 和 dry-run 文案改为“从项目中心创建项目工作台”。
+3. `doctor` / `audit` 的人类可读输出减少内部术语。
+4. 新建中心管理项目时，在 workspace state 中增加 `project_center` 字段。
+5. 继续兼容旧 `hub` 字段。
+
+验收：
+
+- CLI 输出可以给非技术用户直接看。
+- JSON 仍保留机器可读内部字段，不破坏旧测试。
+- 新 workspace state 能表达“加入项目中心”关系。
+
+### Phase 5：Kit 结构收敛
+
+1. 将 `satellite-starter` 从正式 Core Kit 体系中移除或移到 legacy/fixtures。
+2. `spawn` 改为始终基于 `project` Kit。
+3. 项目中心同步说明作为 overlay 生成。
+4. 清理 `product/core/presets/satellite-starter.yaml`。
+
+验收：
+
+- Core 正式 Kit 只剩 `project` 和 `hub`。
+- `spawn` 生成的是 `project` Kit + 项目中心连接。
+- `doctor` 能识别旧 `satellite-starter`，但不推荐新建。
+
+## 验收标准
+
+### 产品验收
+
+- 用户只需要理解“项目工作台”和“项目中心”。
+- “中心管理的项目工作台”能自然解释旧 Satellite。
+- 文档不再把 Satellite 当成第三种工作台。
+- Kit 不作为用户选择项出现。
+
+### 文档验收
+
+- README、roadmap、alpha-test-guide、CLI 能力文档中不再出现旧五类 Kit 作为当前事实。
+- `hub-management` 类文档改为项目中心表达。
+- 所有用户流程文案都能用“项目中心 / 项目工作台”解释。
+
+### CLI 验收
+
+- `starwork init --help` 使用“项目工作台 / 项目中心”。
+- `starwork init --type hub --dry-run` 显示“项目中心”。
+- `starwork spawn --dry-run` 显示“从项目中心创建项目工作台”。
+- `doctor` / `audit` 人类可读输出避免暴露 `Satellite` 和 `starter`。
+- JSON 输出允许继续保留内部字段。
+
+### Skill 验收
+
+- `starworkInit` 不问用户是否要 Hub，而是问是否要“项目中心”。
+- `starworkSpawn` 不说“卫星项目”，而说“从项目中心创建项目工作台”。
+- `starworkDoctor` 解释旧结构时能把 Hub-like 翻译成“像项目中心的旧工作区”。
+- `starworkAudit` 解释为“项目中心巡检它管理的项目工作台”。
+
+## 风险
+
+### 风险 1：内部字段和用户文案不一致
+
+短期内内部仍会保留 `hub` 字段，用户文案使用“项目中心”。
+
+应对：
+
+- 文档明确 `hub` 是内部字段。
+- CLI JSON 保留内部字段，人类可读输出使用用户词。
+
+### 风险 2：旧文档残留造成二次混乱
+
+项目里历史文档很多，容易出现 `satellite-starter`、`卫星项目`、`中枢` 残留。
+
+应对：
+
+- 用 `rg` 建立术语清理清单。
+- 先清用户入口文档，再清内部 SPEC。
+- 内部历史判断文档可以保留旧词，但必须标注“旧称”。
+
+### 风险 3：过早改 CLI 命令名
+
+如果现在直接改 `spawn`，会影响测试、README、用户命令和已发布包。
+
+应对：
+
+- v0.1 只改文案，不改命令名。
+- 未来如需更生活化命令，新增别名，不删除旧命令。
+
+## 待确认问题
+
+1. `项目中心` 是否最终定名。
+2. 英文对外是否统一使用 `Project Center`。
+3. `project_center` 是否作为新 workspace state 字段进入 v0.1，还是先只做文案调整。
+4. `hub-management.html` 是否要重命名为 `project-center.html`。
+5. `satellite-starter` 是直接删除，还是移入 `legacy/fixtures` 便于回归测试。
+
+## 推荐下一步
+
+建议先执行 Phase 1-2：
+
+1. 确认“项目中心”为正式对外名称。
+2. 清理 README、roadmap、alpha-test-guide 和 docs index。
+3. 将 `hub-management.html` 的标题和导航改成“项目中心管理”。
+4. 保留内部 `hub` 字段和 `spawn` 命令不动。
+
+这一步收益最大、风险最低，可以先解决用户理解成本，再进入 CLI/Skill 文案和结构收敛。