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

package/docs/m2.10-core-kit-pack-boundary-cleanup-spec.md

@@ -0,0 +1,567 @@
+# M2.10 Core Kit / Pack 边界清理 SPEC
+
+## 背景
+
+本 SPEC 来自对当前 `product/core/` 的检查。用户指出三个问题：
+
+1. `project` Kit 不适合固定 `参考资料/` 和 `输出/` 两个结构；这些更像通用工作场景的目录，应由通用 Pack 定义。
+2. `hub` / 项目中心 Kit 中英混杂。
+3. 项目中心 Kit 里出现了 `knowledge` 和 `知识` 这种同义目录重复。
+
+这三个问题的共同根因是：
+
+> Core Kit 和 Pack 的职责边界还没有切干净。
+
+当前结构把“工作台基础骨架”和“通用工作场景目录”混在了一起，导致用户侧看起来不清楚，开发侧也容易把目录写死。
+
+## 本 SPEC 不处理什么
+
+本 SPEC 暂不展开知识相关专题。
+
+也就是说：
+
+- 不在本 SPEC 中判断 Project Kit 的 `知识/knowledge` 最终归属。
+- 不在本 SPEC 中设计知识目录结构。
+- 不在本 SPEC 中讨论配套 Skill。
+
+本 SPEC 只处理两件事：
+
+1. `参考资料/` 和 `输出/` 应从 Project Kit 下移到 General Pack。
+2. 项目中心 Kit 的用户可见目录应语言一致，且同一语义只能有一个目录。
+
+## 目标
+
+本轮优化目标是重新划清两层边界：
+
+| 层级 | 应该负责什么 | 不应该负责什么 |
+|---|---|---|
+| Core Kit | 工作台最小骨架、系统入口、状态文件、Agent 入口规则。 | 具体业务目录和场景流程。 |
+| Pack | 某类工作场景下的目录、规则、流程和默认工作区映射。 | 工作台底层机制和项目中心协议。 |
+
+最终用户应看到：
+
+```text
+项目工作台 = 基础骨架
++ 通用工作场景 = 参考资料 / 输出
+```
+
+而不是：
+
+```text
+Project Kit = 固定包含参考资料、输出
+```
+
+## 核心判断
+
+### 判断 1：Project Kit 只定义基础工作台，不固定通用工作目录
+
+`project` Kit 是一个具体项目的基础工作台，不应该预设用户一定用：
+
+```text
+参考资料/
+输出/
+```
+
+这些目录属于“通用工作场景”，而不是所有项目的底层结构。
+
+因此：
+
+```text
+Project Kit 不直接拥有 参考资料/ 和 输出/
+General Pack 拥有 参考资料/ 和 输出/
+```
+
+Project Kit 应只表达基础工作台角色：
+
+- 项目状态入口。
+- 当前工作入口。
+- Agent 入口规则。
+- 系统层目录。
+- StarWork 运行状态。
+- Skill 挂载位置。
+
+具体“资料放哪里、草稿放哪里、成果放哪里”，应由 Pack 或用户自定义目录决定。
+
+### 判断 2：General Pack 才是 `参考资料/` 和 `输出/` 的来源
+
+通用 Pack 的定位应改清楚：
+
+> General Pack 是 StarWork 默认的普通工作场景能力，用于资料输入、草稿推进和确认成果沉淀。
+
+它负责定义：
+
+```text
+参考资料/
+输出/草稿/
+输出/确认成果/
+```
+
+英文镜像：
+
+```text
+references/
+outputs/drafts/
+outputs/final/
+```
+
+这些路径应从 `product/packs/general/` 的 manifest、language files、seed 或规则中生成，而不是来自 `product/core/kits/project/`。
+
+### 判断 3：项目中心 Kit 不应中英混杂
+
+当前曾有一个产品判断：Hub / 项目中心可统一使用英文协议路径，中文用户通过中文 README 和 AGENTS 理解。
+
+这在开发上稳定，但用户侧会看到中英混杂，尤其是项目中心作为可见工作台时，会让人困惑。
+
+新的判断建议：
+
+> `.starwork/`、`.incoming/`、`.internal/` 等机制目录可以保持英文；用户可见的项目中心目录应跟随语言镜像。
+
+也就是说：
+
+中文项目中心：
+
+```text
+.
+├── AGENTS.md
+├── README.md
+├── .starwork/
+├── .incoming/
+├── .internal/
+├── 身份/
+├── 教训/
+├── 项目/
+├── 技能/
+└── 工作区/
+```
+
+英文 Project Center：
+
+```text
+.
+├── AGENTS.md
+├── README.md
+├── .starwork/
+├── .incoming/
+├── .internal/
+├── identity/
+├── lessons/
+├── projects/
+├── skills/
+└── workspace/
+```
+
+说明：
+
+- 隐藏机制目录保持英文，用户一般不会直接关注。
+- 可见目录保持语言一致。
+- JSON schema 字段仍可使用英文。
+- CLI 内部可通过 language profile 映射路径，不要求真实目录名固定为英文。
+
+### 判断 4：项目中心 Kit 不应同时出现 `knowledge` 和 `知识`
+
+同一语义只能有一个事实源。
+
+不能同时存在：
+
+```text
+knowledge/
+知识/
+```
+
+本 SPEC 不判断知识目录的最终形态，只要求：
+
+- 如果项目中心保留某个共享知识入口，则中文项目中心只能使用中文路径，英文 Project Center 只能使用英文路径。
+- 同一工作台内不能同时存在两个同义目录。
+- CLI / doctor / audit 需要能识别旧结构中的同义重复，并给出整理建议。
+
+## 目标结构
+
+### Project Kit 目标结构
+
+中文项目工作台基础 Kit 的核心结构：
+
+```text
+.
+├── AGENTS.md
+├── README.md
+├── CLAUDE.md
+├── .starwork/
+│   ├── workspace.json
+│   ├── skills.json
+│   └── handoff/
+├── .agents/skills/
+├── .claude/skills/
+├── .obsidian/
+└── _系统/
+    ├── 上下文/
+    │   └── 当前项目.md
+    ├── 任务/
+    │   └── 当前工作.md
+    ├── 身份/
+    └── 教训/
+```
+
+英文 Project Kit 的核心结构：
+
+```text
+.
+├── AGENTS.md
+├── README.md
+├── CLAUDE.md
+├── .starwork/
+│   ├── workspace.json
+│   ├── skills.json
+│   └── handoff/
+├── .agents/skills/
+├── .claude/skills/
+├── .obsidian/
+└── _system/
+    ├── context/
+    │   └── current-project.md
+    ├── tasks/
+    │   └── current-work.md
+    ├── identity/
+    └── lessons/
+```
+
+本 SPEC 明确要求：
+
+- Project Kit 不含 `参考资料/`。
+- Project Kit 不含 `输出/`。
+- Project Kit 的 README 和 AGENTS 不写死通用工作目录。
+
+本 SPEC 暂不判断：
+
+- `知识/knowledge` 是否继续属于 Project Kit。
+- 知识库是否迁移为独立能力。
+
+Project Kit 的 README 和 AGENTS 应改为：
+
+```text
+具体工作区由 Pack 或用户定制目录决定。
+```
+
+不能写死：
+
+```text
+原始资料放入 参考资料/
+AI 草稿放入 输出/草稿/
+```
+
+### General Pack 目标结构
+
+中文 General Pack 应生成：
+
+```text
+参考资料/
+输出/
+├── 草稿/
+└── 确认成果/
+```
+
+英文 General Pack 应生成：
+
+```text
+references/
+outputs/
+├── drafts/
+└── final/
+```
+
+General Pack 负责写入或注入：
+
+- 目录 README。
+- AGENTS / `.starwork/rules/` 中关于资料、草稿、确认成果的规则。
+- `.starwork/workspace.json` 中的 `formal_source`、`business_work_area`、`paths` 映射。
+
+### Project Center Kit 目标结构
+
+中文项目中心基础 Kit 的用户可见目录应使用中文：
+
+```text
+.
+├── AGENTS.md
+├── README.md
+├── .starwork/
+│   ├── workspace.json
+│   ├── skills.json
+│   └── handoff/
+├── .incoming/
+├── .internal/
+├── 身份/
+├── 教训/
+├── 项目/
+│   ├── README.md
+│   ├── registry.json
+│   └── 协作/
+├── 技能/
+│   ├── README.md
+│   └── registry.json
+└── 工作区/
+    └── README.md
+```
+
+英文 Project Center Kit 的用户可见目录应使用英文：
+
+```text
+.
+├── AGENTS.md
+├── README.md
+├── .starwork/
+│   ├── workspace.json
+│   ├── skills.json
+│   └── handoff/
+├── .incoming/
+├── .internal/
+├── identity/
+├── lessons/
+├── projects/
+│   ├── README.md
+│   ├── registry.json
+│   └── coordination/
+├── skills/
+│   ├── README.md
+│   └── registry.json
+└── workspace/
+    └── README.md
+```
+
+关于 `knowledge/知识`：
+
+- 本 SPEC 不决定是否保留共享知识入口。
+- 如果保留，必须按语言只保留一个路径。
+- 如果中文项目中心使用 `知识/`，就不应同时出现 `knowledge/`。
+- 如果英文 Project Center 使用 `knowledge/`，就不应同时出现 `知识/`。
+
+## 影响范围
+
+### Core
+
+需要调整：
+
+- `product/core/kits/project/`
+- `product/core/kits/hub/`
+- `product/core/kits/kit-structure-reference.md`
+- `product/core/kits/two-kit-architecture-spec.md`
+- `product/core/profiles/zh/paths.json`
+- `product/core/profiles/en/paths.json`
+- `product/core/profiles/*/templates/AGENTS.md`
+- `product/core/presets/project.yaml`
+- `product/core/presets/hub.yaml`
+- `product/core/capabilities/README.md`
+- `product/core/capabilities/starter-outputs/`
+- `product/core/capabilities/main-repo-sync/`
+
+调整原则：
+
+- Core profiles 只维护系统层路径和语言映射。
+- `work.starter.references`、`work.starter.outputs_drafts`、`work.starter.outputs_final` 这类路径应移入 General Pack。
+- `starter-outputs` capability 应改名或降级为 General Pack 的场景能力，不再作为 Core 基础能力。
+- 项目中心可见目录应有 zh/en 两套路径映射。
+- 同义目录重复要作为 doctor/audit 信号识别。
+
+### Packs
+
+需要调整：
+
+- `product/packs/general/pack.json`
+- `product/packs/general/languages/zh.json`
+- `product/packs/general/languages/en.json`
+- `product/packs/general/rules/*`
+- 必要时新增 `product/packs/general/seed/`
+
+调整原则：
+
+- General Pack 显式拥有 `参考资料/`、`输出/草稿/`、`输出/确认成果/`。
+- Pack manifest 应能描述需要创建的目录、目录 README 和写入边界。
+- Pack 不依赖 Project Kit 预先创建这些目录。
+
+### CLI
+
+需要调整：
+
+- `product/cli/src/cli.js`
+- `product/cli/init-spec.md`
+- `product/cli/doctor-spec.md`
+- `product/cli/upgrade-spec.md`
+- `product/cli/spawn-spec.md`
+- `product/cli/test/init.test.js`
+
+调整原则：
+
+- `init --type project --pack general` 的最终结果仍应包含 `参考资料/` 和 `输出/`，但来源是 General Pack。
+- `init --type project` 若未来允许无 Pack，则只创建基础 Project Kit 或一个中性 `工作区/` fallback，不能创建 `参考资料/` 和 `输出/`。
+- `doctor` 对 `参考资料/` 和 `输出/` 的检查应基于已安装 Pack 或 workspace state，而非 Project Kit 固定结构。
+- `doctor` / `audit` 对项目中心同义目录重复输出 warning。
+
+### Skills
+
+需要调整：
+
+- `product/skills/starworkInit/SKILL.md`
+- `product/skills/starworkDoctor/SKILL.md`
+- `product/kit-skills/starworkSpawn/SKILL.md`
+- `product/kit-skills/starworkAudit/SKILL.md`
+
+调整原则：
+
+- 对用户解释：“项目工作台是基础骨架；通用工作场景会加入参考资料和输出。”
+- 不再说 `参考资料/` 和 `输出/` 是 Project Kit 自带结构。
+- 解释项目中心时，按用户语言说中文或英文目录，不混用。
+
+### Docs
+
+需要调整：
+
+- `README.md`
+- `product/docs/product-direction.md`
+- `product/docs/roadmap.md`
+- `product/docs/alpha-test-guide.md`
+- `product/docs/cli-capabilities.html`
+- `product/docs/hub-management.html`
+- `product/docs/cli-skill-registry.html`
+- `product/docs/index.html`
+
+调整原则：
+
+- 用户侧只看到“项目工作台 / 项目中心 / 场景能力”。
+- 不让用户以为参考资料、输出都是 Core 必备结构。
+- 明确 General Pack 是默认场景能力，因此普通 init 仍然会看到 `参考资料/` 和 `输出/`。
+
+## 实施阶段
+
+### Phase 1：产品文档和 SPEC 对齐
+
+1. 写入本 SPEC。
+2. 更新 docs 索引。
+3. 与 M2.8 命名体系 SPEC 保持一致。
+
+验收：
+
+- 能解释为什么 `参考资料/`、`输出/` 属于 General Pack。
+- 能解释为什么项目中心可见目录应语言一致。
+- 能解释为什么项目中心不能同时有 `knowledge/` 和 `知识/`。
+
+### Phase 2：Core Kit 结构清理
+
+1. 从 `product/core/kits/project/` 移除 `参考资料/`、`输出/`。
+2. 更新 Project Kit README / AGENTS，改为描述基础工作台和抽象工作区。
+3. 清理 Core profiles 中的 `work.starter.*` 命名。
+4. 清理 `starter-outputs` capability 的 Core 地位。
+
+验收：
+
+- 只看 Project Kit 时，不再看到通用 Pack 目录。
+- Project Kit 不再把 `参考资料/` 和 `输出/` 写成基础结构。
+
+### Phase 3：General Pack 接管通用目录
+
+1. General Pack manifest 增加目录声明。
+2. General Pack 生成 `参考资料/`、`输出/草稿/`、`输出/确认成果/`。
+3. 英文镜像生成 `references/`、`outputs/drafts/`、`outputs/final/`。
+4. 更新 Pack rules，让 AGENTS 的资料/草稿/成果规则来自 Pack。
+
+验收：
+
+- `init --type project --pack general` 的结果与用户当前习惯一致。
+- 但从生成计划中能追踪这些目录来源于 General Pack，而不是 Core Kit。
+
+### Phase 4：Project Center Kit 语言一致化
+
+1. 中文项目中心可见目录改为中文。
+2. 英文 Project Center 可见目录保持英文。
+3. 隐藏机制目录保持 `.starwork/`、`.incoming/`、`.internal/`。
+4. CLI 读取路径改为使用 profile / state，不硬编码英文可见目录。
+5. 同一语义目录只保留一个路径。
+
+验收：
+
+- 中文项目中心不再出现 `projects/`、`skills/`、`workspace/` 这类用户可见英文目录。
+- 英文 Project Center 不出现中文可见目录。
+- 不存在 `knowledge/` 与 `知识/` 这种同义目录双写。
+
+## 验收标准
+
+### 产品验收
+
+- 用户能理解：项目工作台是基础，通用 Pack 才带来参考资料和输出。
+- 用户能理解：项目中心目录语言应与工作台语言一致。
+- 用户不会在同一个项目中心看到两个同义目录。
+
+### 结构验收
+
+- `product/core/kits/project/` 不含 `参考资料/`、`输出/`。
+- `product/packs/general/` 明确声明并生成 `参考资料/` 和 `输出/`。
+- `product/core/kits/hub/` 不同时包含 `knowledge/` 和 `知识/`。
+- 中文项目中心可见目录不混用英文。
+- 英文 Project Center 可见目录不混用中文。
+
+### CLI 验收
+
+- `starwork init --type project --pack general --dry-run` 显示通用 Pack 将创建 `参考资料/` 和 `输出/`。
+- `starwork init --type project --pack general --yes` 结果仍能被现有普通用户使用。
+- `doctor` 对 `参考资料/`、`输出/` 的判断来自 Pack/state。
+- `doctor` / `audit` 能发现项目中心同义目录重复。
+
+### Skill 验收
+
+- `starworkInit` 不把 `参考资料/`、`输出/` 说成 Project Kit 自带结构。
+- `starworkSpawn` 说明项目中心创建项目工作台时，目录来自基础 Kit + Pack。
+- `starworkDoctor` / `starworkAudit` 能用人话解释同义目录重复。
+
+## 风险
+
+### 风险 1：用户以为普通项目没有参考资料和输出了
+
+说明：
+
+普通 init 仍默认安装 General Pack，所以结果仍包含 `参考资料/` 和 `输出/`。
+
+变化只是来源变了：
+
+```text
+以前：Project Kit 直接带
+以后：General Pack 带
+```
+
+### 风险 2：项目中心中文目录影响已有测试
+
+说明：
+
+当前 CLI 和测试可能硬编码 `projects/registry.json`、`skills/registry.json`、`workspace/`。
+
+应对：
+
+- 先增加 path mapping。
+- 再迁移项目中心 Kit。
+- 保留旧英文路径识别作为 legacy。
+
+### 风险 3：Pack 目录生成需要更明确 manifest
+
+说明：
+
+如果 General Pack 只是靠 rules 描述目录，CLI 仍然不知道应该创建哪些文件夹。
+
+应对：
+
+- Pack manifest 增加结构化目录声明。
+- CLI 从 Pack manifest 生成目录和 README。
+- 测试覆盖中文和英文镜像。
+
+## 待确认问题
+
+1. Project Kit 是否需要一个真实的中性 `工作区/` 目录作为 no-pack fallback？
+2. General Pack 的 `参考资料/` 和 `输出/` 是否继续放在根目录，还是放在 `工作区/` 下？
+3. 中文项目中心的 `projects/` 应翻译为 `项目/`、`项目清单/` 还是 `项目管理/`？
+4. 中文项目中心的 `skills/` 应翻译为 `技能/`、`AI技能/` 还是保留 `skills/`？
+5. 项目中心里的共享知识入口是否属于本轮一起规范命名，还是等待知识库专题继续讨论？
+
+## 推荐下一步
+
+建议先做产品确认，不立刻开发：
+
+1. 确认 General Pack 继续在根目录生成 `参考资料/` 和 `输出/`。
+2. 确认 Project Kit 不创建真实 `工作区/`，只保留抽象工作区角色；如未来无 Pack，再考虑 fallback。
+3. 确认中文项目中心可见路径使用中文。
+4. 确认项目中心里的 `knowledge/知识` 本轮只处理重复和语言一致性，不展开知识专题。
+5. 确认后再把本 SPEC 拆成开发 lane 可执行任务。