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

package/README.md

@@ -1,83 +1,87 @@
 # StarWork
 
-StarWork is an AI workspace protocol and toolkit for keeping long-running work organized across agents, projects, and sessions.
+StarWork 是一套面向 AI Agent 的工作台协议和工具集，用来帮助用户把长期工作、跨会话协作、多项目管理和 Agent 工作流组织清楚。
 
-It provides:
+它包含四个核心部分：
 
-- **Core**: workspace structures, roles, health checks, and project-state conventions.
-- **CLI**: commands for creating, checking, adapting, extending, and spawning workspaces.
-- **Packs**: scenario templates for common workflows.
-- **Skills**: Agent workflows that help Codex and other agents design StarWork workspaces.
+- **Core**：定义工作台应该长什么样，包括目录结构、角色边界、状态文件和健康检查规则。
+- **CLI**：提供 `init`、`doctor`、`spawn`、`adapt`、`pack install` 等命令，用来创建、检查和扩展工作台。
+- **Packs**：场景模板包。当前 A 测阶段默认使用通用 Pack。
+- **Skills**：给 Codex 等 Agent 使用的工作流说明，让 Agent 能更可靠地帮用户设计和生成 StarWork 工作台。
 
-StarWork is currently in early A-test. The current package is intended for installation testing, workflow validation, and product feedback.
+当前版本处于 A 测阶段，适合测试安装流程、基础命令、工作台结构和 Agent skill 使用体验。
 
-## Install
+## 安装 CLI
 
-Install the CLI globally:
+全局安装：
 
 ```bash
 npm install -g @jennie-shawn/starwork
 starwork --help
 ```
 
-Or run it without global installation:
+不全局安装，直接运行：
 
 ```bash
 npx @jennie-shawn/starwork --help
 ```
 
-## Install Skills
+## 安装 Skills
 
-StarWork skills are distributed through the `skills` CLI from the GitHub repository.
+StarWork skills 通过 GitHub 仓库和 `skills` CLI 分发。
 
-Install all StarWork skills for Codex:
+给 Codex 安装全部 StarWork skills：
 
 ```bash
 npx skills add jennie-shawn/starwork --skill '*' -g -a codex -y
 ```
 
-Install individual skills:
+单独安装某个 skill：
 
 ```bash
 npx skills add jennie-shawn/starwork --skill starworkInit -g -a codex -y
 npx skills add jennie-shawn/starwork --skill starworkSpawn -g -a codex -y
 ```
 
-Available skills:
+当前 skills：
 
-- `starworkInit`: helps an agent design a friendly `starwork init` plan for a new workspace.
-- `starworkSpawn`: helps an agent design a `starwork spawn --blueprint` plan for a satellite workspace.
+- `starworkInit`：帮助 Agent 判断工作台类型、语言、是否需要事项，并生成友好的 `starwork init` 初始化方案。
+- `starworkSpawn`：帮助 Agent 为已有 Hub 设计 `starwork spawn --blueprint` 工作台定制单。
 
-## Quick Start
+如果你希望让 Agent 帮你完成安装，可以把 [Agent 安装指南](docs/agent-install-guide.md) 里的提示词发给你的 Agent。
 
-Create a single-project workspace:
+## 快速开始
+
+创建一个长期单项目工作台：
 
 ```bash
 starwork init \
   --type single-matter \
   --pack general \
+  --language zh \
   --name "StarWork A Test" \
   --target ~/Desktop/starwork-a-test \
   --yes
 ```
 
-Check the workspace:
+检查工作台：
 
 ```bash
 starwork doctor --target ~/Desktop/starwork-a-test
 ```
 
-Create a multi-project Hub:
+创建一个多项目中枢：
 
 ```bash
 starwork init \
   --type hub \
+  --language zh \
   --name "StarWork Hub A Test" \
   --target ~/Desktop/starwork-hub-a-test \
   --yes
 ```
 
-Spawn a project from the Hub:
+从 Hub 生成一个项目：
 
 ```bash
 starwork spawn \
@@ -88,13 +92,13 @@ starwork spawn \
   --yes
 ```
 
-Check the spawned project:
+检查生成的项目：
 
 ```bash
 starwork doctor --target ~/Desktop/starwork-alpha-project
 ```
 
-## CLI Commands
+## CLI 能力
 
 ```text
 starwork init
@@ -104,49 +108,49 @@ starwork adapt
 starwork pack install
 ```
 
-Current capabilities:
+当前能力：
 
-- `init`: creates a local starter workspace, local matter workspace, or multi-project Hub.
-- `doctor`: checks workspace health, required files, Pack installation, and blueprint customization.
-- `spawn`: creates and registers a satellite project from an existing Hub.
-- `adapt`: generates Agent-specific adapter files for Claude Code, Cursor, and related tools.
-- `pack install`: installs supported Packs into compatible workspaces.
+- `init`：创建轻量单项目、长期事项型单项目或多项目 Hub。
+- `doctor`：检查工作台健康状态、必需文件、Pack 落地结果和 blueprint 定制结果。
+- `spawn`：从已有 Hub 创建并登记卫星项目。
+- `adapt`：生成 Claude Code、Cursor 等 Agent 的适配文件。
+- `pack install`：向兼容工作台安装支持的 Pack。
 
-## Repository Structure
+## 仓库结构
 
 ```text
 .
-├── core/       # StarWork Core protocol, kits, profiles, and presets
-├── cli/        # CLI implementation and command specifications
-├── packs/      # Scenario Packs
+├── core/       # StarWork Core 协议、Kit、Profile、Preset
+├── cli/        # CLI 实现和命令规格
+├── packs/      # 场景 Pack
 ├── skills/     # Agent skills
-├── schemas/    # Structured schemas
-├── adapters/   # Agent adapter rules
-├── examples/   # Examples and sample snippets
-└── docs/       # Product documentation and A-test guides
+├── schemas/    # 结构化 schema
+├── adapters/   # Agent 适配规则
+├── examples/   # 示例
+└── docs/       # 产品文档和 A 测指南
 ```
 
-## A-test Notes
+## A 测反馈重点
 
-This release is intended for early testers. Please focus feedback on:
+请优先反馈：
 
-- whether the CLI installs and runs cleanly;
-- whether generated workspace structures are easy to understand;
-- whether `doctor` explains problems clearly;
-- whether Hub + Satellite workflows feel natural;
-- whether `starworkInit` and `starworkSpawn` can be discovered and used by Codex.
+- CLI 是否能顺利安装和运行。
+- `init` 创建的工作台结构是否容易理解。
+- `doctor` 的检查结果是否能指导修复问题。
+- Hub + Satellite 工作流是否自然。
+- `starworkInit` 和 `starworkSpawn` 是否能被 Agent 正确识别和调用。
 
-For a fuller test script, see [docs/alpha-test-guide.md](docs/alpha-test-guide.md).
+更完整的测试脚本见 [A 测安装指南](docs/alpha-test-guide.md)。
 
-## Development
+## 开发
 
-Run the test suite:
+运行测试：
 
 ```bash
 npm test
 ```
 
-Preview the npm package contents:
+预览 npm 包内容：
 
 ```bash
 npm pack --dry-run

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