@jennie-shawn/starwork 0.1.0-alpha.3 → 0.1.0-alpha.6

package/cli/README.md

@@ -25,10 +25,15 @@ v0.1 只覆盖最小可用安装和适配能力：
 
 - `starwork init` 第一版：可以初始化轻量单项目、长期单项目和多项目管理中枢，并通过 Pack 语言配置组装通用工作、内容创作者和中枢管理场景。
 - `starwork spawn` 第一版：可以从健康 Hub 生成 `satellite-starter` / `satellite-matter` 项目工作台，支持 `--blueprint` 定制目录、路径、规则和 seed，并回写 Hub 项目注册表。
-- `starwork doctor` 第一版：可以检查 workspace state、Core 必需角色、Kit 文件、正式事实源、业务工作区和 Pack 落地结果，并支持 `--json` 输出。
+- `starwork doctor` 第一版：可以检查 workspace state、Core 必需角色、Kit 文件、正式事实源、业务工作区和 Pack 落地结果，并支持 `--json` 输出；alpha.4 开始可识别历史模板候选；alpha.5 开始输出目录 `inventory` 与语义 `signals`，供 `starworkDoctor` skill 判断。
+- `starwork upgrade` 第一版：可以读取 `starworkUpgrade` skill 生成的升级蓝图，把历史模板或非标准目录安全升级为 StarWork 工作台；v0.1 只支持 `--blueprint`，不自动判断升级方案。
 - `starwork adapt` 第一版：可以为 Codex、Claude Code、Cursor、Trae 生成或登记轻量适配入口。
 - `starwork pack install` 第一版：可以在健康工作台上补装 Pack，并更新路径、规则、模板和 workspace state。
 
+后续规划：
+
+- `starwork update`：面向已经是 StarWork 的工作台，处理未来 Core / Kit / Pack 版本迁移；与 `upgrade` 分开设计。
+
 CLI 不在 v0.1 阶段处理账号、授权、消息平台 gateway 或复杂商业系统。
 
 ## 命令规格
@@ -39,6 +44,7 @@ CLI 不在 v0.1 阶段处理账号、授权、消息平台 gateway 或复杂商
 - [`starwork pack install` SPEC](./pack-install-spec.md)
 - [`starwork spawn` SPEC](./spawn-spec.md)
 - [`starwork spawn --blueprint` SPEC](./spawn-blueprint-spec.md)
+- [`starwork upgrade` SPEC](./upgrade-spec.md)
 
 ## 本地运行
 
@@ -46,6 +52,7 @@ CLI 不在 v0.1 阶段处理账号、授权、消息平台 gateway 或复杂商
 node cli/bin/starwork.js init --type single-light --pack general --dry-run
 node cli/bin/starwork.js spawn --hub ./my-hub --name "新项目" --target ./new-project --mode matter --dry-run
 node cli/bin/starwork.js spawn --hub ./my-hub --target ./new-project --blueprint ./blueprint.json --dry-run
+node cli/bin/starwork.js upgrade --target ./old-workspace --blueprint ./upgrade-blueprint.json --dry-run
 node cli/bin/starwork.js doctor --target ./my-workspace
 node cli/bin/starwork.js adapt claude --target ./my-workspace --yes
 node cli/bin/starwork.js pack install content-creator --target ./my-workspace --yes

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,41 @@ 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` | 存在 `事项/` 或 `matters/` 时推断为 `single-matter`，否则推断为 `single-light`。 |
+输出内容：
+
+- `upgrade.candidate: true`
+- `upgrade.source: legacy-template`
+- `upgrade.inferred.language`
+- `upgrade.inferred.workspace_type`
+- 检测到的参考资料目录和输出目录
+
+注意：`doctor --json` 不输出 `next_steps`，也不输出 Pack 建议，避免影响 `starworkDoctor` 基于上下文做独立判断。在没有正式 `starwork upgrade` 命令前，`doctor` 只提供事实和信号，不执行迁移。
+
 ### Step 2：读取 workspace state
 
 读取 `.starwork/workspace.json`。
@@ -388,6 +424,7 @@ Result:
     "language": "zh",
     "packs": ["content-creator"]
   },
+  "upgrade": null,
   "summary": {
     "pass": 18,
     "info": 1,
@@ -405,6 +442,29 @@ 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": "single-matter",
+      "references": ["参考资料"],
+      "outputs": ["输出"]
+    }
+  }
+}
+```
+
 ## 检查 ID 命名
 
 检查 ID 应稳定，方便测试、文档和后续自动化使用。
@@ -419,6 +479,7 @@ capability.*
 pack.*
 content.*
 adapter.*
+legacy.*
 ```
 
 示例：
@@ -435,6 +496,9 @@ adapter.*
 - `pack.paths.exist`
 - `pack.templates.installed`
 - `content.current_work.too_long`
+- `legacy.template.detected`
+- `legacy.references.detected`
+- `legacy.outputs.detected`
 
 ## 与其他命令的关系
 
@@ -503,6 +567,8 @@ adapter.*
 - 删除正式事实源目录后返回 fail。
 - 删除 Pack seed 文件后返回 fail。
 - 非 StarWork 目录返回 fail，并提示先运行 `starwork init`。
+- 对存在 `references/outputs` 的英文历史模板返回 fail，但输出 `upgrade` 候选信号，不输出 `next_steps` 或 Pack 建议。
+- 对存在 `参考资料/输出/事项` 的中文历史模板返回 fail，但推断为 `single-matter` + `zh`。
 - `--json` 输出稳定结构。
 - 没有 fail 时退出码为 `0`，有 fail 时退出码为 `1`。