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

package/cli/README.md

@@ -25,7 +25,7 @@ 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 adapt` 第一版：可以为 Codex、Claude Code、Cursor、Trae 生成或登记轻量适配入口。
 - `starwork pack install` 第一版：可以在健康工作台上补装 Pack，并更新路径、规则、模板和 workspace state。
 

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`。
 

package/cli/src/cli.js

@@ -241,6 +241,10 @@ function parseArgs(argv) {
       options.strict = true;
     } else if (arg === "--verbose") {
       options.verbose = true;
+    } else if (arg === "--inventory-depth") {
+      options.inventoryDepth = readValue(argv, ++i, arg);
+    } else if (arg === "--inventory-limit") {
+      options.inventoryLimit = readValue(argv, ++i, arg);
     } else if (arg === "--agent") {
       options.agent = readValue(argv, ++i, arg);
     } else if (arg === "--hub") {
@@ -379,13 +383,23 @@ function doctor(argv) {
     return finishDoctor(result, options);
   }
 
+  result.inventory = collectInventory(targetDir, options);
+  result.signals = detectWorkspaceSignals(result.inventory);
+
   const workspaceRoot = findWorkspaceRoot(targetDir);
   if (!workspaceRoot) {
-    const trace = findStarWorkTrace(targetDir);
-    if (trace) {
-      addCheck(result, "workspace.state.exists", "fail", "疑似 StarWork 工作台，但缺少 .starwork/workspace.json。", trace);
+    const legacy = detectLegacyWorkspace(targetDir, result.signals);
+    if (legacy.candidate) {
+      result.upgrade = buildLegacySignals(legacy);
+      addCheck(result, "workspace.state.exists", "fail", "这是一个可升级的历史模板工作区，但缺少 .starwork/workspace.json。", legacy.primaryTrace);
+      addLegacyChecks(result, legacy);
     } else {
-      addCheck(result, "workspace.state.exists", "fail", "当前目录不是 StarWork 工作台。请先运行 starwork init。");
+      const trace = findStarWorkTrace(targetDir);
+      if (trace) {
+        addCheck(result, "workspace.state.exists", "fail", "疑似 StarWork 工作台，但缺少 .starwork/workspace.json。", trace);
+      } else {
+        addCheck(result, "workspace.state.exists", "fail", "当前目录不是 StarWork 工作台。请先运行 starwork init。");
+      }
     }
     return finishDoctor(result, options);
   }
@@ -461,6 +475,9 @@ function createDoctorResult(targetDir) {
     workspace_root: null,
     target: targetDir,
     workspace: null,
+    upgrade: null,
+    inventory: null,
+    signals: null,
     summary: {
       pass: 0,
       info: 0,
@@ -866,14 +883,352 @@ function normalizeSafeSourcePath(relativePath, sourceRoot, label) {
 function findStarWorkTrace(dir) {
   const traces = [
     "AGENTS.md",
+    "CLAUDE.md",
     "_系统",
     "_system",
     "事项",
-    "matters"
+    "matters",
+    "参考资料",
+    "references",
+    "输出",
+    "outputs"
   ];
   return traces.find((trace) => fs.existsSync(path.join(dir, trace))) || null;
 }
 
+function collectInventory(root, options = {}) {
+  const maxDepth = parseInventoryDepth(options.inventoryDepth);
+  const maxEntries = parseInventoryLimit(options.inventoryLimit);
+  const directories = [];
+  const files = [];
+  const omitted = {
+    directories: 0,
+    files: 0,
+    reason: null
+  };
+  let totalEntries = 0;
+
+  function walk(current, depth) {
+    if (totalEntries >= maxEntries) {
+      omitted.reason = "count_limit";
+      return;
+    }
+
+    let entries;
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true })
+        .filter((entry) => !shouldOmitInventoryEntry(entry.name))
+        .sort((a, b) => a.name.localeCompare(b.name, "zh-Hans-CN"));
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (totalEntries >= maxEntries) {
+        if (entry.isDirectory()) omitted.directories += 1;
+        else if (entry.isFile()) omitted.files += 1;
+        omitted.reason = "count_limit";
+        continue;
+      }
+
+      const absolute = path.join(current, entry.name);
+      const relativePath = normalizeRelativePath(path.relative(root, absolute));
+      if (!relativePath) continue;
+
+      if (entry.isDirectory()) {
+        const childCount = safeChildCount(absolute);
+        directories.push({
+          path: relativePath,
+          depth: depth + 1,
+          children_count: childCount
+        });
+        totalEntries += 1;
+        if (depth + 1 < maxDepth) {
+          walk(absolute, depth + 1);
+        } else if (childCount > 0) {
+          omitted.directories += 1;
+          omitted.reason = omitted.reason || "depth_limit";
+        }
+      } else if (entry.isFile()) {
+        files.push({
+          path: relativePath,
+          depth: depth + 1,
+          size: safeFileSize(absolute)
+        });
+        totalEntries += 1;
+      }
+    }
+  }
+
+  walk(root, 0);
+
+  return {
+    root,
+    max_depth: Number.isFinite(maxDepth) ? maxDepth : "all",
+    max_entries: maxEntries,
+    directories,
+    files,
+    omitted
+  };
+}
+
+function parseInventoryDepth(value) {
+  if (!value) return 8;
+  if (String(value).toLowerCase() === "all") return Infinity;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new Error("--inventory-depth 必须是正整数或 all。");
+  }
+  return parsed;
+}
+
+function parseInventoryLimit(value) {
+  if (!value) return 5000;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 100) {
+    throw new Error("--inventory-limit 必须是大于等于 100 的整数。");
+  }
+  return parsed;
+}
+
+function shouldOmitInventoryEntry(name) {
+  return [
+    ".git",
+    "node_modules",
+    ".DS_Store",
+    ".cache",
+    ".next",
+    "dist",
+    "build",
+    "coverage"
+  ].includes(name);
+}
+
+function safeChildCount(dir) {
+  try {
+    return fs.readdirSync(dir).filter((name) => !shouldOmitInventoryEntry(name)).length;
+  } catch {
+    return 0;
+  }
+}
+
+function safeFileSize(file) {
+  try {
+    return fs.statSync(file).size;
+  } catch {
+    return 0;
+  }
+}
+
+function detectWorkspaceSignals(inventory) {
+  const directories = inventory?.directories || [];
+  const files = inventory?.files || [];
+  return {
+    agent_entry: files.filter((file) => isAgentEntryFile(file.path)).map((file) => file.path),
+    system_dirs: directories.filter((dir) => isSystemDirectory(dir.path)).map((dir) => dir.path),
+    matter_dirs: directories.filter((dir) => isMatterDirectory(dir.path)).map((dir) => dir.path),
+    possible_reference_dirs: directories.filter((dir) => isPossibleReferenceDirectory(dir.path)).map((dir) => dir.path),
+    possible_output_dirs: directories.filter((dir) => isPossibleOutputDirectory(dir.path)).map((dir) => dir.path),
+    possible_draft_dirs: directories.filter((dir) => isPossibleDraftDirectory(dir.path)).map((dir) => dir.path),
+    possible_current_work_dirs: directories.filter((dir) => isPossibleCurrentWorkDirectory(dir.path)).map((dir) => dir.path),
+    identity_dirs: directories.filter((dir) => isIdentityDirectory(dir.path)).map((dir) => dir.path),
+    lessons_dirs: directories.filter((dir) => isLessonsDirectory(dir.path)).map((dir) => dir.path),
+    readme_files: files.filter((file) => /^README(\.[a-z0-9]+)?$/i.test(path.basename(file.path))).map((file) => file.path)
+  };
+}
+
+function isAgentEntryFile(relativePath) {
+  return ["AGENTS.md", "CLAUDE.md", ".cursorrules"].includes(relativePath)
+    || relativePath.endsWith("/AGENTS.md")
+    || relativePath.endsWith("/CLAUDE.md");
+}
+
+function isSystemDirectory(relativePath) {
+  const base = basenameLower(relativePath);
+  return ["_系统", "_system", "system"].includes(base);
+}
+
+function isMatterDirectory(relativePath) {
+  const base = basenameLower(relativePath);
+  return includesAny(base, ["事项", "matter", "matters"]);
+}
+
+function isPossibleReferenceDirectory(relativePath) {
+  const base = basenameLower(relativePath);
+  return includesAny(base, ["参考", "资料", "素材", "知识", "reference", "references", "ref", "source", "material", "materials", "knowledge"]);
+}
+
+function isPossibleOutputDirectory(relativePath) {
+  const base = basenameLower(relativePath);
+  return includesAny(base, ["输出", "成果", "成稿", "终稿", "交付", "发布", "确认", "output", "outputs", "final", "deliverable", "deliverables", "published", "release"]);
+}
+
+function isPossibleDraftDirectory(relativePath) {
+  const base = basenameLower(relativePath);
+  return includesAny(base, ["草稿", "初稿", "脚本", "draft", "drafts", "script", "scripts"]);
+}
+
+function isPossibleCurrentWorkDirectory(relativePath) {
+  const base = basenameLower(relativePath);
+  return includesAny(base, ["推进", "当前", "任务", "工作台", "work", "working", "tasks", "todo"]);
+}
+
+function isIdentityDirectory(relativePath) {
+  const base = basenameLower(relativePath);
+  return includesAny(base, ["身份", "identity", "profile", "persona"]);
+}
+
+function isLessonsDirectory(relativePath) {
+  const base = basenameLower(relativePath);
+  return includesAny(base, ["教训", "经验", "复盘", "lessons", "learning", "retrospective"]);
+}
+
+function basenameLower(relativePath) {
+  return path.basename(relativePath).toLowerCase();
+}
+
+function includesAny(value, needles) {
+  return needles.some((needle) => value.includes(needle));
+}
+
+function detectLegacyWorkspace(dir, signals = null) {
+  const groups = {
+    entryRules: ["AGENTS.md", "CLAUDE.md", ".cursorrules"],
+    system: ["_系统", "_system", "system"],
+    matters: ["事项", "matters"],
+    referencesZh: ["参考资料", "资料", "资料库", "素材", "素材库", "知识"],
+    referencesEn: ["references", "reference"],
+    outputsZh: ["输出", "成果", "成稿", "终稿", "交付物", "发布记录"],
+    outputsEn: ["outputs", "output"],
+    identityRoot: ["identity"],
+    lessonsRoot: ["lessons"],
+    identitySystemZh: ["_系统/身份"],
+    lessonsSystemZh: ["_系统/教训"],
+    identitySystemEn: ["_system/identity"],
+    lessonsSystemEn: ["_system/lessons"]
+  };
+  const found = {};
+  for (const [key, candidates] of Object.entries(groups)) {
+    found[key] = existingRelativePaths(dir, candidates);
+  }
+
+  const references = [...found.referencesZh, ...found.referencesEn];
+  const outputs = [...found.outputsZh, ...found.outputsEn];
+  const signalReferences = signals?.possible_reference_dirs || [];
+  const signalOutputs = signals?.possible_output_dirs || [];
+  const signalMatters = signals?.matter_dirs || [];
+  const signalEntries = signals?.agent_entry || [];
+  const signalSystems = signals?.system_dirs || [];
+  const signalIdentity = signals?.identity_dirs || [];
+  const signalLessons = signals?.lessons_dirs || [];
+  const hasSystem = found.system.length > 0;
+  const hasEntry = found.entryRules.length > 0;
+  const hasMatters = found.matters.length > 0;
+  const hasIdentityOrLessons = [
+    ...found.identityRoot,
+    ...found.lessonsRoot,
+    ...found.identitySystemZh,
+    ...found.lessonsSystemZh,
+    ...found.identitySystemEn,
+    ...found.lessonsSystemEn
+  ].length > 0;
+
+  const signalCount = [
+    hasEntry || signalEntries.length > 0,
+    hasSystem || signalSystems.length > 0,
+    hasMatters || signalMatters.length > 0,
+    references.length > 0 || signalReferences.length > 0,
+    outputs.length > 0 || signalOutputs.length > 0,
+    hasIdentityOrLessons || signalIdentity.length > 0 || signalLessons.length > 0
+  ].filter(Boolean).length;
+  const candidate = signalCount >= 2 || ((references.length > 0 || signalReferences.length > 0) && (outputs.length > 0 || signalOutputs.length > 0));
+  const language = inferLegacyLanguage(found);
+  const workspaceType = hasMatters || signalMatters.length > 0 ? "single-matter" : "single-light";
+  const primaryTrace = [
+    ...found.entryRules,
+    ...signalEntries,
+    ...found.system,
+    ...signalSystems,
+    ...found.matters,
+    ...signalMatters,
+    ...references,
+    ...signalReferences,
+    ...outputs,
+    ...signalOutputs
+  ][0] || null;
+
+  return {
+    candidate,
+    confidence: signalCount >= 4 ? "high" : "medium",
+    language,
+    workspaceType,
+    primaryTrace,
+    found,
+    references: uniqueList([...references, ...signalReferences]),
+    outputs: uniqueList([...outputs, ...signalOutputs])
+  };
+}
+
+function uniqueList(items) {
+  return [...new Set(items.filter(Boolean))];
+}
+
+function existingRelativePaths(root, candidates) {
+  return candidates.filter((relativePath) => fs.existsSync(path.join(root, relativePath)));
+}
+
+function inferLegacyLanguage(found) {
+  const zhScore = Number(found.system.includes("_系统"))
+    + Number(found.matters.includes("事项"))
+    + found.referencesZh.length
+    + found.outputsZh.length
+    + found.identitySystemZh.length
+    + found.lessonsSystemZh.length;
+  const enScore = Number(found.system.includes("_system"))
+    + Number(found.matters.includes("matters"))
+    + found.referencesEn.length
+    + found.outputsEn.length
+    + found.identitySystemEn.length
+    + found.lessonsSystemEn.length;
+  return enScore > zhScore ? "en" : "zh";
+}
+
+function buildLegacySignals(legacy) {
+  return {
+    candidate: true,
+    source: "legacy-template",
+    confidence: legacy.confidence,
+    inferred: {
+      language: legacy.language,
+      workspace_type: legacy.workspaceType,
+      references: legacy.references,
+      outputs: legacy.outputs
+    }
+  };
+}
+
+function addLegacyChecks(result, legacy) {
+  addCheck(result, "legacy.template.detected", "info", `检测到历史模板升级候选，置信度：${legacy.confidence}。`, legacy.primaryTrace);
+  addCheck(result, "legacy.language.inferred", "info", `推测语言：${legacy.language}。`);
+  addCheck(result, "legacy.workspace_type.inferred", "info", `推测工作区类型：${legacy.workspaceType}。`);
+
+  if (legacy.references.length) {
+    addCheck(result, "legacy.references.detected", "info", `检测到参考资料目录：${legacy.references.join(", ")}。`, legacy.references[0]);
+  } else {
+    addCheck(result, "legacy.references.detected", "warn", "未检测到常见参考资料目录，升级时可能需要手动指定资料区。");
+  }
+
+  if (legacy.outputs.length) {
+    addCheck(result, "legacy.outputs.detected", "info", `检测到输出目录：${legacy.outputs.join(", ")}。`, legacy.outputs[0]);
+  } else {
+    addCheck(result, "legacy.outputs.detected", "warn", "未检测到常见输出目录，升级时可能需要手动指定成果区。");
+  }
+
+  if (!legacy.found.entryRules.length) {
+    addCheck(result, "legacy.entry_rules.detected", "warn", "未检测到 AGENTS.md、CLAUDE.md 或 Cursor 规则文件，升级后需要补齐 Agent 入口规则。");
+  }
+}
+
 function addCheck(result, id, level, message, checkPath) {
   result.summary[level] += 1;
   result.checks.push({
@@ -897,7 +1252,7 @@ function finishDoctor(result, options) {
 }
 
 function doctorPublicResult(result) {
-  const { exitCode, target, ...publicResult } = result;
+  const { exitCode, ...publicResult } = result;
   return publicResult;
 }
 
@@ -934,6 +1289,14 @@ function printDoctorResult(result, options) {
     }
   }
 
+  if (result.upgrade?.candidate) {
+    console.log("Legacy signals:");
+    console.log(`  检测为：历史模板候选（${result.upgrade.confidence} confidence）`);
+    console.log(`  推测类型：${result.upgrade.inferred.workspace_type}`);
+    console.log(`  推测语言：${result.upgrade.inferred.language}`);
+    console.log("");
+  }
+
   console.log("Result:");
   if (result.summary.fail > 0) {
     console.log("  Workspace has blocking issues.");
@@ -1914,6 +2277,8 @@ Options:
   --json
   --strict
   --verbose
+  --inventory-depth <number|all>
+  --inventory-limit <number>
 `);
 }
 

package/cli/test/init.test.js

@@ -372,6 +372,66 @@ test("doctor fails outside a StarWork workspace", () => {
   assert.match(result.stdout, /不是 StarWork 工作台/);
 });
 
+test("doctor reports legacy signals for an English legacy template", () => {
+  const dir = tempDir();
+  fs.writeFileSync(path.join(dir, "AGENTS.md"), "# Legacy Agent Rules\n", "utf8");
+  fs.mkdirSync(path.join(dir, "references"), { recursive: true });
+  fs.mkdirSync(path.join(dir, "outputs", "drafts"), { recursive: true });
+  fs.mkdirSync(path.join(dir, "outputs", "final"), { recursive: true });
+
+  const result = runDoctor(["--target", dir, "--json"]);
+  const report = JSON.parse(result.stdout);
+
+  assert.equal(result.status, 1);
+  assert.equal(report.upgrade.candidate, true);
+  assert.equal(report.upgrade.source, "legacy-template");
+  assert.equal(report.upgrade.inferred.language, "en");
+  assert.equal(report.upgrade.inferred.workspace_type, "single-light");
+  assert.equal(Object.hasOwn(report.upgrade.inferred, "pack"), false);
+  assert.equal(Object.hasOwn(report.upgrade, "next_steps"), false);
+  assert.deepEqual(report.upgrade.inferred.references, ["references"]);
+  assert(report.upgrade.inferred.outputs.includes("outputs"));
+  assert(report.checks.some((check) => check.id === "legacy.references.detected" && check.level === "info"));
+});
+
+test("doctor exposes inventory and semantic signals for non-standard legacy folders", () => {
+  const dir = tempDir();
+  fs.writeFileSync(path.join(dir, "README.md"), "# Custom Workspace\n", "utf8");
+  fs.mkdirSync(path.join(dir, "资料库", "文章"), { recursive: true });
+  fs.mkdirSync(path.join(dir, "成稿"), { recursive: true });
+  fs.mkdirSync(path.join(dir, "推进"), { recursive: true });
+
+  const result = runDoctor(["--target", dir, "--json"]);
+  const report = JSON.parse(result.stdout);
+
+  assert.equal(result.status, 1);
+  assert.equal(report.target, path.resolve(dir));
+  assert(report.inventory.directories.some((item) => item.path === "资料库"));
+  assert(report.inventory.directories.some((item) => item.path === "成稿"));
+  assert(report.inventory.files.some((item) => item.path === "README.md"));
+  assert(report.signals.possible_reference_dirs.includes("资料库"));
+  assert(report.signals.possible_output_dirs.includes("成稿"));
+  assert(report.signals.possible_current_work_dirs.includes("推进"));
+  assert.equal(report.upgrade.candidate, true);
+});
+
+test("doctor reports legacy signals for a Chinese matter legacy template", () => {
+  const dir = tempDir();
+  fs.mkdirSync(path.join(dir, "_系统", "身份"), { recursive: true });
+  fs.mkdirSync(path.join(dir, "事项"), { recursive: true });
+  fs.mkdirSync(path.join(dir, "参考资料"), { recursive: true });
+  fs.mkdirSync(path.join(dir, "输出", "确认成果"), { recursive: true });
+
+  const result = runDoctor(["--target", dir]);
+
+  assert.equal(result.status, 1);
+  assert.match(result.stdout, /历史模板候选/);
+  assert.match(result.stdout, /推测类型：single-matter/);
+  assert.match(result.stdout, /推测语言：zh/);
+  assert.doesNotMatch(result.stdout, /--dry-run/);
+  assert.doesNotMatch(result.stdout, /下一步/);
+});
+
 test("adapt creates a Claude adapter and records it in workspace state", () => {
   const dir = tempDir();
   runInit(["--type", "single-light", "--pack", "general", "--target", dir, "--yes"]);

package/docs/README.md

@@ -8,6 +8,7 @@
 - [index.html](index.html)：StarWork HTML 文档中心，统一挂载所有 HTML 阅读稿
 - [hub-management.html](hub-management.html)：多项目中枢管理机制 HTML 阅读版，解释 Hub + Satellite、项目注册表和回写边界
 - [cli-capabilities.html](cli-capabilities.html)：StarWork CLI v0.1 能力说明 HTML 阅读版
+- [doctor-capabilities.html](doctor-capabilities.html)：StarWork Doctor 能力说明 HTML 阅读版，解释标准体检和历史模板升级诊断
 - [product-shape-business-model.html](product-shape-business-model.html)：StarWork 产品形态与商业模式 HTML 可视化阅读版
 - [roadmap.md](roadmap.md)：StarWork 从当前状态到 v0.1 发布、v0.2 扩展和 v1.0 稳定产品的里程碑
 - [roadmap.html](roadmap.html)：里程碑 HTML 阅读版，包含 SVG 总路线图和当前焦点图