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

package/cli/doctor-spec.md

@@ -6,8 +6,8 @@
 - 所属模块：StarWork CLI
 - 命令：`starwork doctor`
 - 前置状态：Core v0.1 已封版，`starwork init` 第一版已落地
-- 实现状态：v0.1 最小实现已落地
-- 目标：检查一个 StarWork 工作台是否健康，并告诉用户问题在哪里、严重到什么程度、下一步该做什么
+- 实现状态：v0.1 最小实现已落地；历史模板升级诊断、目录 inventory 和 signals 已进入 alpha
+- 目标：检查一个 StarWork 工作台是否健康，并把结构事实、风险和候选信号暴露出来；对历史模板用户只输出可供 AI 判断的诊断信号，不直接生成行动建议
 
 ## 一句话定义
 
@@ -15,6 +15,8 @@
 
 它不负责创建工作台，不负责升级工作台，也不默认修复文件。它只做一件事：把 Core、Kit、Pack 和 Agent 适配文件之间的不一致检查出来，用人能看懂的方式报告。
 
+从 alpha.4 起，`doctor` 还承担一个轻量探测入口职责：当目录不是标准 StarWork 工作台，但看起来像用户正在使用的历史模板时，它不会只说“不是工作台”，而是输出历史模板识别结果、目录 inventory 和 semantic signals，交给 `starworkDoctor` 做后续判断。
+
 ## 为什么先做 doctor
 
 Core v0.1 已封版后，项目进入 M2：CLI v0.1 最小闭环。
@@ -90,6 +92,8 @@ starwork doctor --verbose
 | `--json` | 输出机器可读 JSON。 |
 | `--strict` | 将部分 warning 视为失败，适合测试和发布前检查。 |
 | `--verbose` | 显示通过项、检查来源和路径解析细节。 |
+| `--inventory-depth <number\|all>` | 控制目录结构探测深度，默认用于保护过大的工作区。 |
+| `--inventory-limit <number>` | 控制最多输出多少个目录和文件条目。 |
 | `--help` | 显示帮助。 |
 
 v0.1 暂不提供 `--fix`。修复动作后续可以单独设计为 `starwork doctor --fix` 或 `starwork repair`，但第一版不要混入。
@@ -142,7 +146,7 @@ v0.1 暂不提供 `--fix`。修复动作后续可以单独设计为 `starwork do
 结果：
 
 - 找到：使用该目录作为工作区根目录。
-- 未找到但当前目录有 StarWork 痕迹：报告 `fail` 或 `warn`，提示运行 `starwork init` 或手动补齐 state。
+- 未找到但当前目录有 StarWork 或历史模板痕迹：报告缺少 workspace state，同时输出历史模板候选信号。
 - 未找到且无 StarWork 痕迹：报告不是 StarWork 工作台。
 
 v0.1 判断标准：
@@ -150,9 +154,42 @@ v0.1 判断标准：
 | 情况 | 结果 |
 |---|---|
 | 找到 `.starwork/workspace.json` | 继续检查。 |
-| 未找到 state，但有 `AGENTS.md` 和 `_系统/` / `_system/` | `fail`：缺少 workspace state。 |
+| 未找到 state，但有 `AGENTS.md` 和 `_系统/` / `_system/` | `fail`：缺少 workspace state，并输出候选信号。 |
+| 未找到 state，但有 `references/outputs` 或 `参考资料/输出` | `fail`：识别为历史模板升级候选。 |
 | 完全没有 StarWork 痕迹 | `fail`：不是 StarWork 工作台。 |
 
+### Step 1.5：历史模板升级诊断
+
+历史模板诊断只读文件结构，不移动、不复制、不写入任何文件。
+
+识别信号：
+
+| 信号 | 示例 |
+|---|---|
+| Agent 入口规则 | `AGENTS.md`、`CLAUDE.md`、`.cursorrules` |
+| 系统目录 | `_系统/`、`_system/` |
+| 事项目录 | `事项/`、`matters/` |
+| 参考资料目录 | `参考资料/`、`资料/`、`素材/`、`references/`、`reference/` |
+| 输出目录 | `输出/`、`成果/`、`outputs/`、`output/` |
+| 身份和教训 | `identity/`、`lessons/`、`_系统/身份/`、`_system/identity/` |
+
+推断规则：
+
+| 推断项 | 规则 |
+|---|---|
+| `language` | 中文路径多则 `zh`，英文路径多则 `en`，不确定时默认为 `zh`。 |
+| `workspace_type` | Hub 信号充分时推断为 `hub`；其他历史项目候选统一推断为 `project`。`事项/` 或 `matters/` 只作为历史内容信号。 |
+输出内容：
+
+- `upgrade.candidate: true`
+- `upgrade.source: legacy-template`
+- `upgrade.inferred.language`
+- `upgrade.inferred.workspace_type`
+- `upgrade.inferred.reasons`
+- 检测到的参考资料目录和输出目录
+
+注意：`doctor --json` 不输出 `next_steps`，也不输出 Pack 建议，避免影响 `starworkDoctor` 基于上下文做独立判断。正式升级仍由 `starworkDoctor` 生成 blueprint，再交给 `starwork upgrade --blueprint` 执行。
+
 ### Step 2：读取 workspace state
 
 读取 `.starwork/workspace.json`。
@@ -161,7 +198,7 @@ v0.1 判断标准：
 
 - `schema` 是否为 `starwork.workspace.v0.1`
 - `core` 是否兼容 `0.1`
-- `workspace_type` 是否为 `single-light`、`single-matter` 或 `hub`
+- `workspace_type` 是否为 `single-light`、`project` 或 `hub`
 - `kit` 是否存在
 - `language` 是否存在
 - `packs` 是否是数组
@@ -174,8 +211,8 @@ v0.1 判断标准：
 {
   "schema": "starwork.workspace.v0.1",
   "core": "0.1",
-  "workspace_type": "single-matter",
-  "kit": "local-matter",
+  "workspace_type": "project",
+  "kit": "project",
   "packs": [
     {
       "id": "content-creator",
@@ -253,7 +290,7 @@ Core v0.1 必需角色：
 | `workspace_type` | 允许 Kit |
 |---|---|
 | `single-light` | `local-starter` |
-| `single-matter` | `local-matter` |
+| `project` | `project` |
 | `hub` | `hub` |
 
 卫星项目 Kit 目前不是 `init` 的普通入口，但 `doctor` 应能识别：
@@ -261,7 +298,7 @@ Core v0.1 必需角色：
 | Kit | 说明 |
 |---|---|
 | `satellite-starter` | 接入主库的轻量卫星项目。 |
-| `satellite-matter` | 接入主库的事项型卫星项目。 |
+| `project` | 接入主库的项目卫星项目。 |
 
 ### Step 6：Capability 检查
 
@@ -270,7 +307,6 @@ v0.1 先检查确定性 capability。
 | capability | 检查项 |
 |---|---|
 | `starter-outputs` | 参考资料目录、草稿目录、确认成果目录存在。 |
-| `matter-mode` | 事项注册表存在；事项模板存在。 |
 | `decisions` | 决策文件存在时检查位置；不强制所有工作区都有。 |
 | `local-identity` | 本地身份目录存在。 |
 | `local-lessons` | 本地教训目录存在。 |
@@ -305,6 +341,20 @@ v0.1 先检查确定性 capability。
 - 数据复盘 / analytics-review
 - content brief、publish record、weekly review 模板
 
+对新版 `hub` 工作台，v0.1 应至少检查：
+
+- 项目注册表：中文默认 `项目/registry.json`，英文默认 `projects/registry.json`
+- 项目协作路由：中文默认 `项目/协作/`，英文默认 `projects/coordination/`
+- `.incoming/`
+- 共享身份：中文默认 `身份/`，英文默认 `identity/`
+- 共享教训：中文默认 `教训/`，英文默认 `lessons/`
+- 共享知识：中文默认 `知识/`，英文默认 `knowledge/`
+- 托管 Skill 注册表：中文默认 `技能/registry.json`，英文默认 `skills/registry.json`
+- 草稿和实验区：中文默认 `工作区/`，英文默认 `workspace/`
+- `.starwork/handoff/`
+
+Hub 不再检查单项目式的项目状态和当前工作入口。
+
 对 `hub-management` Pack，v0.1 应至少检查：
 
 - 项目 / projects
@@ -327,7 +377,7 @@ v0.1 不做复杂语义判断，但可以做轻量启发式 warning。
 - 正式事实源路径指向草稿目录。
 - 业务工作区路径指向只读参考资料目录。
 - 参考资料目录中出现明显生成成果文件名，例如 `final`、`发布稿`、`确认版`。
-- Matter 草稿目录被 workspace state 声明为正式事实源。
+- 历史过程目录被 workspace state 声明为正式事实源。
 
 这些检查只能给 warning，不应作为 fail。
 
@@ -342,8 +392,8 @@ StarWork Doctor
 
 Workspace: /path/to/workspace
 Core: 0.1
-Type: single-matter
-Kit: local-matter
+Type: project
+Kit: project
 Packs: content-creator@0.1.0
 
 Summary:
@@ -383,11 +433,12 @@ Result:
   "workspace_root": "/path/to/workspace",
   "workspace": {
     "core": "0.1",
-    "workspace_type": "single-matter",
-    "kit": "local-matter",
+    "workspace_type": "project",
+    "kit": "project",
     "language": "zh",
     "packs": ["content-creator"]
   },
+  "upgrade": null,
   "summary": {
     "pass": 18,
     "info": 1,
@@ -405,6 +456,41 @@ Result:
 }
 ```
 
+历史模板升级候选的 JSON 示例：
+
+```json
+{
+  "schema": "starwork.doctor.result.v0.1",
+  "ok": false,
+  "strict_ok": false,
+  "workspace_root": null,
+  "workspace": null,
+  "upgrade": {
+    "candidate": true,
+    "source": "legacy-template",
+    "confidence": "high",
+    "inferred": {
+      "language": "zh",
+      "workspace_type": "project",
+      "references": ["参考资料"],
+      "outputs": ["输出"],
+      "reasons": {
+        "language": ["_系统 是中文工作区信号"],
+        "workspace_type": ["事项 表示存在事项或多线推进推进结构"],
+        "references": ["参考资料 命中参考资料候选信号"],
+        "outputs": ["输出 命中成果或输出候选信号"]
+      }
+    }
+  },
+  "signals": {
+    "project_status_files": ["_系统/上下文/项目状态.md"],
+    "current_work_files": ["_系统/任务/当前工作.md"],
+    "readonly_candidate_dirs": ["参考资料"],
+    "writable_candidate_dirs": ["事项", "输出"]
+  }
+}
+```
+
 ## 检查 ID 命名
 
 检查 ID 应稳定，方便测试、文档和后续自动化使用。
@@ -419,6 +505,7 @@ capability.*
 pack.*
 content.*
 adapter.*
+legacy.*
 ```
 
 示例：
@@ -430,11 +517,14 @@ adapter.*
 - `core.current_work.exists`
 - `core.formal_source.exists`
 - `kit.files.complete`
-- `capability.matter.registry_exists`
+- `capability.事项.registry_exists`
 - `pack.source.exists`
 - `pack.paths.exist`
 - `pack.templates.installed`
 - `content.current_work.too_long`
+- `legacy.template.detected`
+- `legacy.references.detected`
+- `legacy.outputs.detected`
 
 ## 与其他命令的关系
 
@@ -497,12 +587,14 @@ adapter.*
 `starwork doctor` v0.1 可验收，至少满足：
 
 - 对 `starwork init --type single-light --pack general` 生成的工作台返回成功。
-- 对 `starwork init --type single-matter --pack content-creator` 生成的工作台返回成功。
+- 对 `starwork init --type project --pack content-creator` 生成的工作台返回成功。
 - 对 `starwork init --type hub` 生成的工作台返回成功。
 - 删除 `AGENTS.md` 后返回 fail。
 - 删除正式事实源目录后返回 fail。
 - 删除 Pack seed 文件后返回 fail。
 - 非 StarWork 目录返回 fail，并提示先运行 `starwork init`。
+- 对存在 `references/outputs` 的英文历史模板返回 fail，但输出 `upgrade` 候选信号，不输出 `next_steps` 或 Pack 建议。
+- 对存在 `参考资料/输出/事项` 的中文历史模板返回 fail，但推断为 `project` + `zh`。
 - `--json` 输出稳定结构。
 - 没有 fail 时退出码为 `0`，有 fail 时退出码为 `1`。
 

package/cli/init-spec.md

@@ -20,7 +20,7 @@
 3. Kit 负责通用 AI 工作区结构，Pack 负责场景定制结构。
 4. 通用场景也是一个 Pack，不存在“无 Pack”的最终工作台。
 5. 初始化可以创建和补充文件，但不能静默覆盖用户已有内容。
-6. 多项目管理中枢是 `init` 的一种工作区类型；卫星项目创建不属于本命令。
+6. 项目中心是 `init` 的一种工作区类型；从项目中心创建项目工作台不属于本命令。
 
 ## 术语边界
 
@@ -33,9 +33,9 @@ Kit 是 AI 工作区的通用模板。
 - Agent 入口文件在哪里
 - 项目状态在哪里
 - 当前工作索引在哪里
-- 是否启用事项机制
+- 是否使用 Project 标准结构
 - 是否启用本地身份和教训
-- 是否是多项目管理中枢
+- 是否是项目中心
 
 Kit 不决定具体业务场景。
 
@@ -104,61 +104,72 @@ v0.1 不在 `init` 中处理升级。
 ```text
 你要建立哪种工作区？
 
-1. 轻量单项目
-   适合放资料、写草稿、整理最终成果。
+1. 项目工作台（推荐）
+   适合一个具体项目的持续执行；可独立使用，也可后续接入项目中心。
 
-2. 长期单项目
-   适合需要事项追踪、跨会话接力、长期沉淀过程的项目。
-
-3. 多项目管理中枢
-   适合你有多个长期项目，希望统一管理身份、教训、知识、skills 和项目联络。
+2. 项目中心
+   适合你有多个项目，希望统一管理身份、教训、知识、skills 和项目登记。
 ```
 
 内部映射：
 
 | 用户选择 | Kit / Preset | 说明 |
 |---|---|---|
-| 轻量单项目 | `local-starter` | 不启用事项机制，使用轻量输入输出结构。 |
-| 长期单项目 | `local-matter` | 启用 Matter Mode 和决策记录。 |
-| 多项目管理中枢 | `hub` | 建立主库 / 中枢，不创建卫星项目。 |
+| 项目工作台 | `project` | 默认推荐入口。 |
+| 项目中心 | `hub` | 建立项目中心，不创建具体项目工作台。 |
 
-注意：Core 中的 `satellite-matter` 更接近卫星项目 Kit，不应被 `init` 的“多项目管理中枢”入口直接使用。`init` 应使用独立的 Hub Kit / Hub Preset。
+注意：Core 中的 `project` 是项目工作台基础模板；是否由项目中心管理，通过 `project_center` 连接信息表达。
 
-### Step 2：选择 Pack
+### Step 2：选择语言
 
-如果用户选择单项目工作区，继续提问：
+CLI 应在交互模式下明确询问语言：
 
 ```text
-你准备用这个工作台做什么？
+第 2 步：工作台使用哪种语言？
 
-1. 通用工作
-   默认 Pack，适合资料整理、草稿输出、项目推进。
+1. 中文（推荐）
+   目录、规则和 Pack 内容使用中文。
 
-2. 自媒体内容创作
-   安装内容创作者 Pack，包含账号定位、选题、素材、草稿、发布、复盘等结构。
+2. English
+   Pack 内容使用英文；当前 Core Kit 仍以中文结构为主。
 ```
 
-内部映射：
+参数模式可通过 `--language zh|en` 指定。非交互和 `--yes` 默认使用 `zh`。
+
+### Step 3：选择 Pack
+
+v0.1 交互模式下不主动展示未定稿的场景 Pack。
+
+```text
+第 3 步：v0.1 单项目先使用通用工作 Pack（general）。
+内容创作者等场景 Pack 还在定稿中，暂不在交互流程里主动推荐。
+```
+
+单项目默认使用：
 
-| 用户选择 | Pack | 说明 |
+| 工作区类型 | Pack | 说明 |
 |---|---|---|
-| 通用工作 | `general` | 默认 Pack。不是“无 Pack”。 |
-| 自媒体内容创作 | `content-creator` | 首个场景 Pack。 |
+| 项目工作台 | `general` | 默认 Pack。不是“无 Pack”。 |
+
+高级参数仍可显式传入兼容 Pack：
 
-如果用户选择多项目管理中枢，不展示业务 Pack 列表。
+```bash
+starwork init --type project --pack content-creator
+```
+
+如果用户选择项目中心，不展示业务 Pack 列表，也不询问场景 Pack。
 
-多项目管理中枢应使用自己的管理 Pack：
+项目中心应使用自己的管理 Pack：
 
 | 工作区类型 | Pack | 说明 |
 |---|---|---|
-| 多项目管理中枢 | `hub-management` | 定义项目注册、共享身份、共享教训、知识库、skills 和跨项目联络。 |
+| 项目中心 | `hub-management` | 定义项目注册、共享身份、共享教训、知识库、skills 和跨项目联络。 |
 
-### Step 3：确认基本信息
+### Step 4：确认基本信息
 
 CLI 询问或自动推断：
 
 - 工作台名称：默认使用当前目录名。
-- 语言：v0.1 默认中文；高级参数可选择英文。
 - 正式成果位置：默认由 Kit + Pack 合并后决定。
 - 是否继续预览：默认是。
 
@@ -176,28 +187,41 @@ _系统/任务/当前工作.md
 
 但业务工作实际推进位置可以由 Pack 覆盖，例如自媒体 Pack 可以把单篇内容推进到内容事项或内容生产目录。
 
-### Step 4：预览计划
+### Step 4：确认目标路径
+
+写入前必须展示最终落点，而不只是展示内部参数。
+
+预览至少包含：
+
+```text
+目标目录：/absolute/path/to/my-workspace
+是否新建目录：是/否
+工作台名称：my-workspace
+```
+
+如果用户通过 skill 引导初始化，AI 可以建议文件夹名，但必须说明可修改，并在执行 `--yes` 前让用户确认最终绝对路径。
+
+### Step 5：预览计划
 
 在写入前展示计划：
 
 ```text
 将创建 StarWork 工作台：
 
-工作区类型：长期单项目
-Kit：local-matter
-Pack：content-creator
-工作台名称：my-content-workspace
+目标目录：/Users/example/my-workspace
+是否新建目录：是
+工作区类型：项目工作台
+Kit：project
+Pack：general
+工作台名称：my-workspace
 
 将创建：
 - AGENTS.md
-- _系统/上下文/项目状态.md
+- _系统/上下文/当前项目.md
 - _系统/任务/当前工作.md
-- 事项/注册表.md
-- 选题池/
-- 素材库/
-- 草稿与脚本/
-- 发布记录/
-- 数据复盘/
+- 参考资料/
+- 输出/草稿/
+- 输出/确认成果/
 
 不会覆盖：
 - README.md 已存在，将保留
@@ -208,7 +232,7 @@ Pack：content-creator
 
 用户确认后才执行。
 
-### Step 5：执行初始化
+### Step 6：执行初始化
 
 执行顺序：
 
@@ -305,10 +329,10 @@ Pack 可以改变业务流向，但不能移除工作区仪表盘。
 {
   "schema": "starwork.workspace.v0.1",
   "core": "0.1",
-  "workspace_type": "single-matter",
-  "kit": "local-matter",
+  "workspace_type": "single-light",
+  "kit": "project",
   "packs": [
-    "content-creator"
+    "general"
   ],
   "language": "zh",
   "formal_source": "由 pack 或用户选择决定",
@@ -328,22 +352,26 @@ Pack 可以改变业务流向，但不能移除工作区仪表盘。
 ```bash
 starwork init
 starwork init --type single-light --pack general
-starwork init --type single-matter --pack content-creator
+starwork init --type project --pack content-creator
 starwork init --type hub
 starwork init --name "我的内容工作台"
 starwork init --formal-source outputs/final
 starwork init --target ./my-workspace
+starwork init --target ./custom-workspace --blueprint ./init-blueprint.json --dry-run
 starwork init --dry-run
 starwork init --yes
+starwork init --language en
 ```
 
 参数说明：
 
 | 参数 | 说明 |
 |---|---|
-| `--type` | 工作区类型：`single-light`、`single-matter`、`hub`。 |
-| `--pack` | Pack ID；单项目默认 `general`，自媒体为 `content-creator`。 |
+| `--type` | 工作区类型：`single-light`、`project`、`hub`。 |
+| `--pack` | Pack ID；单项目交互默认 `general`，高级参数可传入兼容 Pack。 |
+| `--language` | 工作台语言：`zh` 或 `en`；交互模式会询问，非交互默认 `zh`。 |
 | `--name` | 工作台名称。 |
+| `--blueprint` | 读取 `starworkInit` 生成的初始化定制单；支持覆盖正式成果/当前工作路径、额外目录、规则注入、seed 和跳过明确不要的默认目录。 |
 | `--formal-source` | 覆盖默认正式成果位置。 |
 | `--target` | 指定初始化目标目录；默认是当前目录。 |
 | `--dry-run` | 只预览，不写入。 |
@@ -391,7 +419,7 @@ v0.1 暂不建议直接暴露 `--preset` 给普通用户。可以保留内部或
 
 v0.1 `init` 不处理：
 
-- 卫星项目创建
+- 从项目中心创建项目工作台
 - 账号系统
 - 云端登录
 - 付费授权
@@ -407,7 +435,7 @@ v0.1 `init` 不处理：
 
 1. `general` 默认 Pack 的声明。
 2. `content-creator` Pack 的声明文件。
-3. Hub Kit / Hub Preset，避免把多项目管理中枢误映射到卫星项目 Kit。
+3. 项目中心 Kit / Preset，避免把项目中心误映射到项目工作台 Kit。
 4. `hub-management` Pack。
 5. `.starwork/workspace.json` 最小状态文件。
 6. 写入计划、dry-run 预览和冲突旁路文件策略。
@@ -428,8 +456,8 @@ v0.1 `init` 不处理：
 - 普通用户无需理解 Kit / Pack / preset，也能完成初始化。
 - 用户能在写入前看懂将创建什么。
 - 初始化不会静默覆盖已有内容。
-- 轻量单项目、长期单项目、多项目管理中枢三种入口边界清楚。
+- 项目工作台、项目中心两种入口边界清楚；默认推荐项目工作台。
 - 通用工作和自媒体内容创作都通过 Pack 表达。
-- 多项目管理中枢不安装业务 Pack。
+- 项目中心不安装业务 Pack。
 - 初始化结果可被 `starwork doctor` 检查。
 - 后续可以通过 `starwork pack install` 补装 Pack。