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

package/README.md

@@ -5,7 +5,7 @@ StarWork 是一套面向 AI Agent 的工作台协议和工具集，用来帮助
 它包含四个核心部分：
 
 - **Core**：定义工作台应该长什么样，包括目录结构、角色边界、状态文件和健康检查规则。
-- **CLI**：提供 `init`、`doctor`、`spawn`、`adapt`、`pack install` 等命令，用来创建、检查和扩展工作台。
+- **CLI**：提供 `init`、`doctor`、`spawn`、`upgrade`、`adapt`、`pack install`、`multiagent` 等命令，用来创建、检查、升级、协作和扩展工作台。
 - **Packs**：场景模板包。当前 A 测阶段默认使用通用 Pack。
 - **Skills**：给 Codex 等 Agent 使用的工作流说明，让 Agent 能更可靠地帮用户设计和生成 StarWork 工作台。
 
@@ -17,46 +17,55 @@ StarWork 是一套面向 AI Agent 的工作台协议和工具集，用来帮助
 
 ```bash
 npm install -g @jennie-shawn/starwork
+starwork --version
 starwork --help
 ```
 
 不全局安装，直接运行：
 
 ```bash
+npx @jennie-shawn/starwork --version
 npx @jennie-shawn/starwork --help
 ```
 
 ## 安装 Skills
 
-StarWork skills 通过 GitHub 仓库和 `skills` CLI 分发。
+StarWork skills 分两类管理：
 
-给 Codex 安装全部 StarWork skills：
+- 系统 Skill 通过 GitHub 仓库和 `skills` CLI 安装到 Agent 全局环境。
+- Kit 自带 Skill 跟着工作台走，例如 Hub Kit 自带 `starworkSpawn`，单项目 Kit 自带 `neat-freak`。
+
+给 Codex 安装 StarWork 系统 Skill：
 
 ```bash
-npx skills add jennie-shawn/starwork --skill '*' -g -a codex -y
+npx skills add jennie-shawn/starwork --skill starworkInit -g -a codex -y
+npx skills add jennie-shawn/starwork --skill starworkDoctor -g -a codex -y
+npx skills add jennie-shawn/starwork --skill starworkMultiagent -g -a codex -y
 ```
 
-单独安装某个 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
 ```
 
 当前 skills：
 
 - `starworkInit`：帮助 Agent 判断工作台类型、语言、是否需要事项，并生成友好的 `starwork init` 初始化方案。
-- `starworkSpawn`：帮助 Agent 为已有 Hub 设计 `starwork spawn --blueprint` 工作台定制单。
+- `starworkDoctor`：帮助 Agent 基于 `starwork doctor --json` 做目录逻辑诊断；用户明确要求升级时，也负责生成 `starwork upgrade --blueprint` 升级蓝图。
+- `starworkMultiagent`：帮助 Agent 把“登记当前会话为常用智能体”“管理多 Agent 分工”“登记共享输出”等请求转换成 `starwork multiagent` 命令组合。
+- `starworkSpawn`：Hub Kit 自带 Skill，帮助已有 Hub 设计 `starwork spawn --blueprint` 工作台定制单。
+- `neat-freak`：单项目 Kit 自带 Skill，帮助项目收尾、整理和归档。
 
 如果你希望让 Agent 帮你完成安装，可以把 [Agent 安装指南](docs/agent-install-guide.md) 里的提示词发给你的 Agent。
 
 ## 快速开始
 
-创建一个长期单项目工作台：
+创建一个单事务项目工作台：
 
 ```bash
 starwork init \
-  --type single-matter \
+  --type single-light \
   --pack general \
   --language zh \
   --name "StarWork A Test" \
@@ -104,17 +113,21 @@ starwork doctor --target ~/Desktop/starwork-alpha-project
 starwork init
 starwork doctor
 starwork spawn
+starwork upgrade
 starwork adapt
 starwork pack install
+starwork multiagent
 ```
 
 当前能力：
 
-- `init`：创建轻量单项目、长期事项型单项目或多项目 Hub。
+- `init`：创建单事务项目、多事务项目或多项目 Hub；交互默认推荐单事务项目。
 - `doctor`：检查工作台健康状态、必需文件、Pack 落地结果和 blueprint 定制结果。
 - `spawn`：从已有 Hub 创建并登记卫星项目。
+- `upgrade`：按 `starworkDoctor` skill 生成的升级蓝图，把历史模板安全升级为 StarWork 工作台。
 - `adapt`：生成 Claude Code、Cursor 等 Agent 的适配文件。
 - `pack install`：向兼容工作台安装支持的 Pack。
+- `multiagent`：为同一项目建立自定义 Agent 职责位、绑定会话，并登记跨 lane 共享输出。
 
 ## 仓库结构
 
@@ -138,7 +151,8 @@ starwork pack install
 - `init` 创建的工作台结构是否容易理解。
 - `doctor` 的检查结果是否能指导修复问题。
 - Hub + Satellite 工作流是否自然。
-- `starworkInit` 和 `starworkSpawn` 是否能被 Agent 正确识别和调用。
+- 系统 Skill 是否能被 Agent 正确识别和调用。
+- Hub Kit 自带的 `starworkSpawn`、单项目 Kit 自带的 `neat-freak` 是否能在对应工作台内被正确发现。
 
 更完整的测试脚本见 [A 测安装指南](docs/alpha-test-guide.md)。
 

package/cli/README.md

@@ -9,8 +9,10 @@ v0.1 只覆盖最小可用安装和适配能力：
 - `starwork init`
 - `starwork spawn`
 - `starwork doctor`
+- `starwork upgrade`
 - `starwork adapt`
-- `starwork pack install content-creator`
+- `starwork pack install`
+- `starwork multiagent`
 
 第一阶段重点：
 
@@ -18,20 +20,24 @@ v0.1 只覆盖最小可用安装和适配能力：
 - 能从多项目中枢生成被管理的新项目工作台
 - 能检查工作区结构是否完整
 - 能生成或更新当前 Agent 所需适配文件
-- 能安装自媒体内容创作者 Pack
+- 能为同一项目建立多 Agent 职责位、绑定会话并登记跨 lane 共享输出
+- 能安装兼容 Pack，并在 A 测阶段优先验证通用工作与多项目中枢管理流程
 - 安装和更新时不覆盖用户已有内容
 
 当前 M2 CLI v0.1 最小闭环已落地：
 
-- `starwork init` 第一版：可以初始化轻量单项目、长期单项目和多项目管理中枢，并通过 Pack 语言配置组装通用工作、内容创作者和中枢管理场景。
+- `starwork init` 第一版：可以初始化单事务项目、多事务项目和多项目管理中枢；交互模式默认推荐单事务项目，先确认工作台类型和语言；Hub 自动使用 `hub-management` Pack，单项目 v0.1 默认使用 `general` Pack，不主动推荐未定稿场景 Pack。
 - `starwork spawn` 第一版：可以从健康 Hub 生成 `satellite-starter` / `satellite-matter` 项目工作台，支持 `--blueprint` 定制目录、路径、规则和 seed，并回写 Hub 项目注册表。
 - `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 upgrade` 第一版：可以读取 `starworkDoctor` skill 生成的升级蓝图，把历史模板或非标准目录安全升级为 StarWork 工作台；v0.1 只支持 `--blueprint`，不自动判断升级方案。
 - `starwork adapt` 第一版：可以为 Codex、Claude Code、Cursor、Trae 生成或登记轻量适配入口。
 - `starwork pack install` 第一版：可以在健康工作台上补装 Pack，并更新路径、规则、模板和 workspace state。
+- `starwork multiagent` 第一版：可以初始化 Agent Lanes、按项目自定义职责新增 lane、绑定 / 释放会话、查看状态，并登记跨 lane 可读输出。
+- Skill 管理与分发第一版：Kit 可以自带 Skill，Hub 可以托管用户常用 Skill；`init` 写入 `.starwork/skills.json`，`spawn` 按 Hub registry 选择性分发 Skill，`doctor` 暴露 Skill manifest / registry / mount 事实。
 
 后续规划：
 
+- Pack 自带 Skill 与 upgrade blueprint actions：按 [`StarWork Skill 管理与分发机制 SPEC`](../core/skill-management-spec.md) 继续扩展。
 - `starwork update`：面向已经是 StarWork 的工作台，处理未来 Core / Kit / Pack 版本迁移；与 `upgrade` 分开设计。
 
 CLI 不在 v0.1 阶段处理账号、授权、消息平台 gateway 或复杂商业系统。
@@ -45,15 +51,20 @@ CLI 不在 v0.1 阶段处理账号、授权、消息平台 gateway 或复杂商
 - [`starwork spawn` SPEC](./spawn-spec.md)
 - [`starwork spawn --blueprint` SPEC](./spawn-blueprint-spec.md)
 - [`starwork upgrade` SPEC](./upgrade-spec.md)
+- [`starwork multiagent` SPEC](../core/agent-lanes-spec.md)
 
 ## 本地运行
 
 ```bash
+node cli/bin/starwork.js --version
+node cli/bin/starwork.js --help
 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 multiagent init --lanes research,writing,review --target ./my-workspace --yes
+node cli/bin/starwork.js multiagent bind research --session codex:manual-research-1 --target ./my-workspace --yes
 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

@@ -185,9 +185,10 @@ v0.1 判断标准：
 - `upgrade.source: legacy-template`
 - `upgrade.inferred.language`
 - `upgrade.inferred.workspace_type`
+- `upgrade.inferred.reasons`
 - 检测到的参考资料目录和输出目录
 
-注意：`doctor --json` 不输出 `next_steps`，也不输出 Pack 建议，避免影响 `starworkDoctor` 基于上下文做独立判断。在没有正式 `starwork upgrade` 命令前，`doctor` 只提供事实和信号，不执行迁移。
+注意：`doctor --json` 不输出 `next_steps`，也不输出 Pack 建议，避免影响 `starworkDoctor` 基于上下文做独立判断。正式升级仍由 `starworkDoctor` 生成 blueprint，再交给 `starwork upgrade --blueprint` 执行。
 
 ### Step 2：读取 workspace state
 
@@ -459,8 +460,20 @@ Result:
       "language": "zh",
       "workspace_type": "single-matter",
       "references": ["参考资料"],
-      "outputs": ["输出"]
+      "outputs": ["输出"],
+      "reasons": {
+        "language": ["_系统 是中文工作区信号"],
+        "workspace_type": ["事项 表示存在事项或多事务推进结构"],
+        "references": ["参考资料 命中参考资料候选信号"],
+        "outputs": ["输出 命中成果或输出候选信号"]
+      }
     }
+  },
+  "signals": {
+    "project_status_files": ["_系统/上下文/项目状态.md"],
+    "current_work_files": ["_系统/任务/当前工作.md"],
+    "readonly_candidate_dirs": ["参考资料"],
+    "writable_candidate_dirs": ["事项", "输出"]
   }
 }
 ```

package/cli/init-spec.md

@@ -104,48 +104,65 @@ v0.1 不在 `init` 中处理升级。
 ```text
 你要建立哪种工作区？
 
-1. 轻量单项目
-   适合放资料、写草稿、整理最终成果。
+1. 单事务项目（推荐）
+   适合一个明确目标、一个阶段任务或一次成果交付。
 
-2. 长期单项目
-   适合需要事项追踪、跨会话接力、长期沉淀过程的项目。
+2. 多事务项目（进阶）
+   适合同一项目下有多个事项，需要推进、交接和复盘。
 
 3. 多项目管理中枢
-   适合你有多个长期项目，希望统一管理身份、教训、知识、skills 和项目联络。
+   适合你有多个项目，希望统一管理身份、教训、知识、skills 和项目登记。
 ```
 
 内部映射：
 
 | 用户选择 | Kit / Preset | 说明 |
 |---|---|---|
-| 轻量单项目 | `local-starter` | 不启用事项机制，使用轻量输入输出结构。 |
-| 长期单项目 | `local-matter` | 启用 Matter Mode 和决策记录。 |
+| 单事务项目 | `local-starter` | 默认推荐入口。不启用事项机制，使用轻量输入输出结构。 |
+| 多事务项目 | `local-matter` | 进阶入口。启用 Matter Mode 和决策记录。 |
 | 多项目管理中枢 | `hub` | 建立主库 / 中枢，不创建卫星项目。 |
 
 注意：Core 中的 `satellite-matter` 更接近卫星项目 Kit，不应被 `init` 的“多项目管理中枢”入口直接使用。`init` 应使用独立的 Hub Kit / Hub Preset。
 
-### 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”。 |
+| 多事务项目 | `general` | 默认 Pack。不是“无 Pack”。 |
+
+高级参数仍可显式传入兼容 Pack：
+
+```bash
+starwork init --type single-matter --pack content-creator
+```
 
-如果用户选择多项目管理中枢，不展示业务 Pack 列表。
+如果用户选择多项目管理中枢，不展示业务 Pack 列表，也不询问场景 Pack。
 
 多项目管理中枢应使用自己的管理 Pack：
 
@@ -153,12 +170,11 @@ v0.1 不在 `init` 中处理升级。
 |---|---|---|
 | 多项目管理中枢 | `hub-management` | 定义项目注册、共享身份、共享教训、知识库、skills 和跨项目联络。 |
 
-### Step 3：确认基本信息
+### Step 4：确认基本信息
 
 CLI 询问或自动推断：
 
 - 工作台名称：默认使用当前目录名。
-- 语言：v0.1 默认中文；高级参数可选择英文。
 - 正式成果位置：默认由 Kit + Pack 合并后决定。
 - 是否继续预览：默认是。
 
@@ -183,10 +199,10 @@ _系统/任务/当前工作.md
 ```text
 将创建 StarWork 工作台：
 
-工作区类型：长期单项目
-Kit：local-matter
-Pack：content-creator
-工作台名称：my-content-workspace
+工作区类型：单事务项目
+Kit：local-starter
+Pack：general
+工作台名称：my-workspace
 
 将创建：
 - AGENTS.md
@@ -305,10 +321,10 @@ Pack 可以改变业务流向，但不能移除工作区仪表盘。
 {
   "schema": "starwork.workspace.v0.1",
   "core": "0.1",
-  "workspace_type": "single-matter",
-  "kit": "local-matter",
+  "workspace_type": "single-light",
+  "kit": "local-starter",
   "packs": [
-    "content-creator"
+    "general"
   ],
   "language": "zh",
   "formal_source": "由 pack 或用户选择决定",
@@ -335,6 +351,7 @@ starwork init --formal-source outputs/final
 starwork init --target ./my-workspace
 starwork init --dry-run
 starwork init --yes
+starwork init --language en
 ```
 
 参数说明：
@@ -342,7 +359,8 @@ starwork init --yes
 | 参数 | 说明 |
 |---|---|
 | `--type` | 工作区类型：`single-light`、`single-matter`、`hub`。 |
-| `--pack` | Pack ID；单项目默认 `general`，自媒体为 `content-creator`。 |
+| `--pack` | Pack ID；单项目交互默认 `general`，高级参数可传入兼容 Pack。 |
+| `--language` | 工作台语言：`zh` 或 `en`；交互模式会询问，非交互默认 `zh`。 |
 | `--name` | 工作台名称。 |
 | `--formal-source` | 覆盖默认正式成果位置。 |
 | `--target` | 指定初始化目标目录；默认是当前目录。 |
@@ -428,7 +446,7 @@ v0.1 `init` 不处理：
 - 普通用户无需理解 Kit / Pack / preset，也能完成初始化。
 - 用户能在写入前看懂将创建什么。
 - 初始化不会静默覆盖已有内容。
-- 轻量单项目、长期单项目、多项目管理中枢三种入口边界清楚。
+- 单事务项目、多事务项目、多项目管理中枢三种入口边界清楚；默认推荐单事务项目，多事务项目作为进阶入口。
 - 通用工作和自媒体内容创作都通过 Pack 表达。
 - 多项目管理中枢不安装业务 Pack。
 - 初始化结果可被 `starwork doctor` 检查。

package/cli/spawn-spec.md

@@ -27,8 +27,8 @@ Satellite / 具体执行项目
 
 `init` 的职责是创建当前目录的工作台：
 
-- 轻量单项目
-- 长期单项目
+- 单事务项目
+- 多事务项目
 - 多项目管理中枢
 
 但 `spawn` 涉及两个工作区：
@@ -70,7 +70,7 @@ starwork spawn \
 ```bash
 starwork spawn --hub <hub-path> --name <project-name> --target <path>
 starwork spawn --hub ~/my-hub --name "新项目" --target ~/projects/new-project --mode starter
-starwork spawn --hub ~/my-hub --name "长期项目" --target ~/projects/long-project --mode matter
+starwork spawn --hub ~/my-hub --name "多阶段项目" --target ~/projects/multi-stage-project --mode matter
 starwork spawn --hub ~/my-hub --target ~/projects/custom-project --blueprint ./blueprint.json --dry-run
 starwork spawn --hub ~/my-hub --target ~/projects/custom-project --blueprint ./blueprint.json --yes
 starwork spawn --hub ~/my-hub --name "新项目" --target ~/projects/new-project --dry-run
@@ -101,7 +101,7 @@ starwork spawn --hub ~/my-hub --name "新项目" --target ~/projects/new-project
 
 v0.1 默认 `matter`。
 
-原因：卫星项目通常是长期项目，通常需要事项追踪、跨会话接力和过程沉淀。
+原因：由 Hub 生成的卫星项目通常比单事务项目更复杂，往往需要事项追踪、跨会话接力和过程沉淀。
 
 ## 执行流程