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

package/adapters/trae/rules.md

@@ -0,0 +1,7 @@
+# Trae Adapter Rules
+
+Trae uses `.trae/rules/starwork.md` as the StarWork entry.
+
+Trae can discover project Skills from `.trae/skills/` and `.agents/skills/`. When the same Skill exists in both locations, `.trae/skills/` wins. StarWork still treats `.starwork/skills.json` as the project Skill fact source.
+
+Trae is a manual-operation host in v0.2. StarWork should not read Trae private session storage, enumerate Trae sessions, or describe Trae as supporting automatic background cross-session delivery.

package/adapters/trae/safety.md

@@ -0,0 +1,7 @@
+# Trae Adapter Safety
+
+- Do not read or write encrypted `database.db`.
+- Do not read `state.vscdb` or other Trae private workspace storage as MultiAgent session state.
+- Do not write Trae private state.
+- Do not rely on snapshot history as StarWork memory.
+- MultiAgent delivery should degrade to manual handoff unless a future stable API is confirmed.

package/cli/README.md

@@ -9,25 +9,42 @@ v0.1 只覆盖最小可用安装和适配能力：
 - `starwork init`
 - `starwork spawn`
 - `starwork doctor`
+- `starwork knowledge`
+- `starwork upgrade`
 - `starwork adapt`
-- `starwork pack install content-creator`
+- `starwork pack install`
+- `starwork multiagent`
+- `starwork audit`
+- `starwork repair`
 
 第一阶段重点：
 
 - 能从空文件夹初始化 StarWork 工作台
-- 能从多项目中枢生成被管理的新项目工作台
+- 能从项目中心创建被管理的新项目工作台
 - 能检查工作区结构是否完整
 - 能生成或更新当前 Agent 所需适配文件
-- 能安装自媒体内容创作者 Pack
+- 能为同一项目建立多 Agent 职责位、绑定会话并登记跨 lane 共享输出
+- 能安装兼容 Pack，并在 A 测阶段优先验证通用工作与项目中心管理流程
 - 安装和更新时不覆盖用户已有内容
 
 当前 M2 CLI v0.1 最小闭环已落地：
 
-- `starwork init` 第一版：可以初始化轻量单项目、长期单项目和多项目管理中枢，并通过 Pack 语言配置组装通用工作、内容创作者和中枢管理场景。
-- `starwork spawn` 第一版：可以从健康 Hub 生成 `satellite-starter` / `satellite-matter` 项目工作台，支持 `--blueprint` 定制目录、路径、规则和 seed，并回写 Hub 项目注册表。
-- `starwork doctor` 第一版：可以检查 workspace state、Core 必需角色、Kit 文件、正式事实源、业务工作区和 Pack 落地结果，并支持 `--json` 输出。
-- `starwork adapt` 第一版：可以为 Codex、Claude Code、Cursor、Trae 生成或登记轻量适配入口。
+- `starwork init` 第一版：可以初始化项目工作台和项目中心；`single-light` / `project` 作为兼容别名映射为 `project`；项目中心自动使用 `hub-management` Pack，项目工作台 v0.1 默认使用 `general` Pack，不主动推荐未定稿场景 Pack。
+- `starwork spawn` 第一版：可以从健康项目中心创建项目工作台，支持 `--language zh|en`、`--blueprint` 定制目录、路径、规则和 seed，并回写项目中心项目注册表；`starter` / `project` mode 作为兼容别名映射为 `project`。
+- `starwork doctor` 第一版：可以检查 workspace state、Core 必需角色、Kit 文件、正式事实源、业务工作区和 Pack 落地结果，并支持 `--json` 输出；alpha.4 开始可识别历史模板候选；alpha.5 开始输出目录 `inventory` 与语义 `signals`；alpha.9 开始补齐类似项目中心的旧主库识别，供 `starworkDoctor` skill 判断。
+- `starwork knowledge` 第一版：可以为项目工作台开启本地知识库，支持 `init`、`status --json`、`check` 和 `apply --blueprint`；成功开启后把项目内业务 Skill `starworkKnowledgeProject` 安装到当前项目；默认不创建知识库，不迁移或删除旧 `知识/knowledge`。
+- `starwork upgrade` 第一版：可以读取 `starworkDoctor` skill 生成的升级蓝图，把历史模板、非标准目录或类似项目中心的旧主库安全升级为 StarWork 工作台；alpha.9 支持 `hub + preserve-names + pack:null`，旧主库接入时不会创建重复标准目录；v0.1 只支持 `--blueprint`，不自动判断升级方案。
+- `starwork adapt` Host Adapter v0.1：可以读取 Codex、Claude Code、Cursor、Trae 的宿主能力 profile；`--capabilities` 只输出能力不写文件；正式适配会写入 `.starwork/adapters.json`，并保留 `.starwork/workspace.json.adapters` 摘要。
 - `starwork pack install` 第一版：可以在健康工作台上补装 Pack，并更新路径、规则、模板和 workspace state。
+- `starwork multiagent` v0.2+Host Adapter：在原有 Agent Lanes 基础上增加宿主分支；Codex 支持自动读取和 launch；Claude Code 支持 `CLAUDE_CODE_SESSION_ID` 绑定、`claude --resume` 继续命令和 transcript 摘要；Cursor 只支持 `agent-transcripts/<uuid>/<uuid>.jsonl` 的只读摘要，用于 `read/status --host`；Trae 不做会话读取或自动化，默认返回人工交付消息或 unsupported。
+- `starwork audit` 第一版：可以从项目中心读取语言映射后的项目注册表，批量巡检中心管理的项目工作台，并复用 `doctor` 聚合健康事实。
+- `starwork repair` 第一版：可以执行 `starworkAudit` 生成的保守 repair blueprint，支持补目录、补缺失文件、重写 sync、更新 registry 和更新 workspace state。
+- Skill 管理与分发第一版：工作台模板可以自带 Skill，项目中心可以托管用户常用 Skill；`init` 写入 `.starwork/skills.json`，`spawn` 按项目中心 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 或复杂商业系统。
 
@@ -35,18 +52,42 @@ CLI 不在 v0.1 阶段处理账号、授权、消息平台 gateway 或复杂商
 
 - [`starwork init` SPEC](./init-spec.md)
 - [`starwork doctor` SPEC](./doctor-spec.md)
+- [`Knowledge Base Capability SPEC`](../planning/features/knowledge-base/specs/v0.1.md)
 - [`starwork adapt` SPEC](./adapt-spec.md)
+- [`Host Adapter v0.1 Implementation SPEC`](../planning/features/host-adapters/specs/v0.1-implementation.md)
 - [`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)
+- [`starwork audit` SPEC](./audit-spec.md)
+- [`starwork repair` SPEC](./repair-spec.md)
+- [`starwork multiagent` SPEC](../core/agent-lanes-spec.md)
+- [`Agent Lanes 宿主会话命名增强 SPEC`](../core/agent-lanes-session-naming-spec.md)
+- [`MultiAgent v0.2 Codex 多会话编排 SPEC`](../planning/features/multiagent/specs/v0.2-codex-orchestration.md)
 
 ## 本地运行
 
 ```bash
-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 --version
+node cli/bin/starwork.js --help
+node cli/bin/starwork.js init --type project --pack general --dry-run
+node cli/bin/starwork.js spawn --hub ./my-hub --name "新项目" --target ./new-project --language zh --dry-run
 node cli/bin/starwork.js spawn --hub ./my-hub --target ./new-project --blueprint ./blueprint.json --dry-run
+node cli/bin/starwork.js audit --hub ./my-hub --json
+node cli/bin/starwork.js repair --blueprint ./repair-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 init --type project --language zh --target ./cursor-workspace --adapter cursor --yes
+node cli/bin/starwork.js knowledge init --target ./my-workspace --dry-run
+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 --session-name "Research Agent" --target ./my-workspace --yes
+node cli/bin/starwork.js multiagent status --host --target ./my-workspace --json
+node cli/bin/starwork.js multiagent instruct development --from product-planning --message "请根据 SPEC 开始实现。" --target ./my-workspace --dry-run
+node cli/bin/starwork.js multiagent handoff development --from product-planning --message "请手动处理这条指令。" --target ./my-workspace --dry-run
+node cli/bin/starwork.js multiagent continue research --target ./my-workspace --json
+node cli/bin/starwork.js adapt all --capabilities --json
+node cli/bin/starwork.js adapt cursor --check --target ./my-workspace --json
 node cli/bin/starwork.js adapt claude --target ./my-workspace --yes
+node cli/bin/starwork.js doctor --target ./my-workspace --host all --json
 node cli/bin/starwork.js pack install content-creator --target ./my-workspace --yes
 ```

package/cli/audit-spec.md

@@ -0,0 +1,403 @@
+# `starwork audit` SPEC
+
+## 状态
+
+- 版本：v0.1 draft
+- 所属模块：StarWork CLI / StarWork Hub
+- 命令：`starwork audit`
+- 实现状态：待实现
+- 相关对象：`hub`、`project`、Hub binding、legacy satellite、`starwork doctor`、`starworkAudit`、`starwork repair`
+- 目标：从 Hub 视角批量扫描已登记的 Satellite，暴露结构事实、同步事实和健康风险；不做主观判断，不直接修复
+
+## 一句话定义
+
+`starwork audit` 是 Hub 对旗下 Satellite 的只读巡检命令。
+
+它不替代 `doctor`。`doctor` 检查一个工作台；`audit` 从 Hub 读取项目注册表，再对多个 Satellite 做聚合检查。
+
+```text
+项目中心
+  ↓ 读取项目注册表（中文默认 项目/registry.json，英文默认 projects/registry.json）
+starwork audit
+  ↓ 对每个已登记项目工作台复用 doctor
+audit-result.json
+  ↓
+starworkAudit skill 判断和生成 repair blueprint
+  ↓
+starwork repair --blueprint
+```
+
+## 产品边界
+
+| 命令 / Skill | 面向对象 | 负责 | 不负责 |
+|---|---|---|---|
+| `doctor` | 单个工作台 | 检查一个目录是否健康 | 批量巡检、修复建议 |
+| `audit` | Hub 和多个 Satellite | 读取 Hub registry，批量暴露事实 | 判断怎么修、写文件 |
+| `starworkAudit` | audit 结果 | 解释、分级、追问、生成修复蓝图 | 直接改文件 |
+| `repair` | 已是 StarWork 的工作台 | 按确认过的 repair blueprint 修复 | 自行判断业务语义 |
+| `upgrade` | 历史模板 / 非 StarWork 目录 | 按 upgrade blueprint 接入 StarWork | 修复已有 StarWork 工作台 |
+| `spawn` | 新 Satellite | 从 Hub 创建并登记项目 | 巡检已有项目 |
+
+一句话：
+
+> `audit` 负责看清楚，`starworkAudit` 负责想清楚，`repair` 负责按确认方案做清楚。
+
+## 为什么不能直接自动修复
+
+Satellite 巡检中会出现大量需要语义判断的问题：
+
+- registry 里的路径失效，是项目移动、删除，还是已经归档？
+- Satellite 的 `knowledge/` 或 `知识/` 断链，是应该重建软链接，还是改为本地副本？
+- `AGENTS.md` 使用旧规则，是应该覆盖、追加，还是保持项目特例？
+- Satellite doctor 失败，是结构真的损坏，还是用户进行了合理定制但 state 没同步？
+- 项目长期未更新，是健康沉睡，还是需要归档？
+
+这些问题不应由 CLI 硬编码判断。`audit` 只输出事实和信号，后续由 `starworkAudit` 结合上下文和用户确认生成修复蓝图。
+
+## 命令形式
+
+```bash
+starwork audit
+starwork audit --hub <hub-path>
+starwork audit --hub ~/my-hub --project content-site
+starwork audit --hub ~/my-hub --json
+starwork audit --hub ~/my-hub --inventory-depth all
+```
+
+## 参数
+
+| 参数 | 说明 |
+|---|---|
+| `--hub <path>` | Hub 工作台路径。未提供时默认当前目录或向上查找当前 Hub。 |
+| `--project <project-id>` | 只巡检指定项目。未提供时巡检 registry 中所有项目。 |
+| `--json` | 输出机器可读 JSON。 |
+| `--strict` | 将部分 warning 汇总为失败，适合发布前巡检。 |
+| `--inventory-depth <number\|all>` | 传递给每个 Satellite 的 doctor inventory 探测深度。 |
+| `--inventory-limit <number>` | 控制每个 Satellite doctor inventory 输出规模。 |
+| `--help` | 显示帮助。 |
+
+v0.1 不支持：
+
+- `--fix`
+- 自动修改 registry
+- 自动修改 Satellite
+- 自动安装或删除 Skill
+- 自动归档项目
+- 自动合并 `.incoming/`
+
+## 执行流程
+
+### Step 1：定位 Hub
+
+优先级：
+
+1. 使用 `--hub <path>`。
+2. 没有 `--hub` 时，从当前目录向上查找 `.starwork/workspace.json`。
+3. 读取 state，确认 `workspace_type === "hub"`。
+
+如果目标不是 Hub，直接失败。
+
+### Step 2：Hub 自检
+
+检查 Hub 必需结构：
+
+| 路径 | 说明 |
+|---|---|
+| `.starwork/workspace.json` | Hub 工作台身份证。 |
+| 项目注册表 | 中文默认 `项目/registry.json`，英文默认 `projects/registry.json`。 |
+| 项目协作路由 | 中文默认 `项目/协作/`，英文默认 `projects/coordination/`。 |
+| `.starwork/handoff/` | Hub 本地收发队列。 |
+| `.incoming/` | 回写候选区。 |
+| 共享身份 | 中文默认 `身份/`，英文默认 `identity/`。 |
+| 共享教训 | 中文默认 `教训/`，英文默认 `lessons/`。 |
+| 共享知识 | 中文默认 `知识/`，英文默认 `knowledge/`。 |
+| 托管 Skill 注册表 | 中文默认 `技能/registry.json`，英文默认 `skills/registry.json`。 |
+| 草稿和实验区 | 中文默认 `工作区/`，英文默认 `workspace/`。 |
+
+Hub 自检可以复用 `doctorCollect(hubPath)`，但 `audit` 还需要读取 registry 和聚合项目结果。
+
+### Step 3：读取项目注册表
+
+读取语言映射后的项目注册表：
+
+```text
+zh: 项目/registry.json
+en: projects/registry.json
+```
+
+检查：
+
+- JSON 是否可解析。
+- `projects` 是否是数组。
+- `project_id` 是否缺失或重复。
+- `name` 是否缺失。
+- `path` 是否缺失。
+- `status` 是否属于允许值。
+
+建议状态值：
+
+| 状态 | 含义 |
+|---|---|
+| `active` | 正常推进。 |
+| `paused` | 暂停。 |
+| `archived` | 已归档。 |
+| `unknown` | 旧 registry 或不完整记录。 |
+
+v0.1 对 `archived` 项目默认仍做轻量存在性检查，但不把 doctor warning 计入整体失败；是否深度检查由后续参数扩展。
+
+### Step 4：逐个 Satellite 可达性检查
+
+对每个项目记录检查：
+
+- `path` 是否存在。
+- `path` 是否是目录。
+- 是否存在 `.starwork/workspace.json`。
+- workspace state 是否可解析。
+- `workspace_type` 是否为 `project`。
+- `kit` 是否为 `project`。
+- 是否存在 `hub.path` 与 `hub.project_id`。
+- `hub.path` 是否指向当前 Hub。
+- `hub.project_id` 是否等于 registry 中的 `project_id`。
+
+兼容期内，`satellite-starter` 只作为旧 Satellite signal 输出。旧事项目录只作为普通历史内容信号，不作为可兼容的工作区类型。
+
+路径不存在或不是目录为 `fail`。
+
+### Step 5：复用 doctor 检查 Satellite
+
+对可达 Satellite 调用现有 `doctorCollect(projectPath)`。
+
+`audit` 不重写单项目检查逻辑，只做聚合：
+
+- `doctor.ok`
+- `doctor.summary`
+- 关键 fail / warn checks
+- workspace type / kit / language / packs
+- skills facts
+
+`audit --json` 可以嵌入 doctor 摘要，但不应默认完整嵌入每个项目的大型 inventory，除非用户传入 `--inventory-depth all` 或 `--verbose`。
+
+### Step 6：检查 Hub 绑定和同步关系
+
+读取 Satellite：
+
+```text
+.core-sync.json
+.starwork/workspace.json
+```
+
+检查：
+
+- `.core-sync.json` 是否存在。
+- `.core-sync.json` 是否可解析。
+- `.core-sync.json` 中记录的 Hub 路径是否指向当前 Hub。
+- `.starwork/workspace.json` 中 `hub.project_id` 是否匹配 registry。
+- registry 中记录的 path 是否和 Satellite 实际路径一致。
+- Satellite 的 language 是否和 Hub 预期或 registry metadata 冲突。
+
+这些问题通常是高风险，但不一定都阻塞。`starworkAudit` 需要根据上下文判断修复方式。
+
+### Step 7：检查共享资源挂载
+
+按 Satellite language 判断路径：
+
+| 资源 | 中文 Satellite | 英文 Satellite | Hub 来源 |
+|---|---|---|---|
+| knowledge | `知识/` | `knowledge/` | 中文项目中心 `知识/`，英文 Project Center `knowledge/` |
+| identity | `_系统/身份/` | `_system/identity/` | 中文项目中心 `身份/`，英文 Project Center `identity/` |
+| lessons | `_系统/教训/` | `_system/lessons/` | 中文项目中心 `教训/`，英文 Project Center `lessons/` |
+| skills | `.agents/skills/`、`.claude/skills/` | 同左 | 中文项目中心 `技能/`，英文 Project Center `skills/`，或 Kit 自带 Skill |
+
+检查：
+
+- 路径是否存在。
+- 如果是软链接，软链接目标是否存在。
+- 如果是复制快照，是否有 `.core-sync.json` 或 README 说明来源。
+- Hub 托管 Skill 是否仍能从 registry 找到。
+
+### Step 8：检查联络队列
+
+新版本地收发队列：
+
+```text
+.starwork/handoff/
+```
+
+检查：
+
+- `inbox/`
+- `outbox/`
+- `sent/`
+- `archived/`
+- `state.json`
+
+旧路径：
+
+```text
+_系统/跨项目/
+_system/cross-project/
+```
+
+旧路径只作为 legacy signal 输出，不作为新版标准路径。
+
+### Step 9：检查规则版本信号
+
+轻量扫描 `AGENTS.md`：
+
+- 是否提到新版 `.starwork/handoff/`。
+- 是否仍把 `_系统/跨项目/` 作为标准路径。
+- 是否能找到当前项目状态和当前工作入口。
+- 是否明确 Satellite 不把项目进度正文写回 Hub。
+- 是否明确项目中心中央路由在语言映射后的协作目录中。
+
+v0.1 只输出信号，不做复杂自然语言判定。
+
+## JSON 输出
+
+### 最小结构
+
+```json
+{
+  "schema": "starwork.audit.result.v0.1",
+  "ok": false,
+  "strict_ok": false,
+  "hub": {
+    "path": "/Users/example/my-hub",
+    "ok": true,
+    "workspace": {
+      "core": "0.1",
+      "workspace_type": "hub",
+      "kit": "hub",
+      "language": "zh"
+    },
+    "doctor": {
+      "ok": true,
+      "summary": {
+        "pass": 12,
+        "info": 2,
+        "warn": 0,
+        "fail": 0
+      }
+    }
+  },
+  "registry": {
+    "path": "项目/registry.json",
+    "ok": true,
+    "projects_total": 2,
+    "duplicate_ids": [],
+    "missing_paths": []
+  },
+  "summary": {
+    "projects_total": 2,
+    "projects_checked": 2,
+    "projects_reachable": 2,
+    "pass": 1,
+    "warn": 1,
+    "fail": 0
+  },
+  "projects": [
+    {
+      "project_id": "content-site",
+      "name": "内容官网",
+      "status": "active",
+      "path": "/Users/example/projects/content-site",
+      "reachable": true,
+      "workspace_type": "project",
+      "kit": "project",
+      "language": "zh",
+      "doctor_ok": true,
+      "sync_ok": true,
+      "checks": [
+        {
+          "id": "satellite.path.exists",
+          "level": "pass",
+          "message": "Satellite path exists",
+          "trace": "/Users/example/projects/content-site"
+        }
+      ],
+      "legacy_signals": []
+    }
+  ],
+  "checks": []
+}
+```
+
+### 项目结果字段
+
+| 字段 | 说明 |
+|---|---|
+| `project_id` | Hub registry 中的项目 ID。 |
+| `name` | 项目名称。 |
+| `status` | registry 状态。 |
+| `path` | registry 记录的 Satellite 路径。 |
+| `reachable` | 路径是否存在且可读。 |
+| `workspace_type` | Satellite workspace type。 |
+| `language` | Satellite language。 |
+| `doctor_ok` | 复用 doctor 后的健康结果。 |
+| `sync_ok` | Hub 绑定与 `.core-sync.json` 是否一致。 |
+| `checks` | 针对该项目的巡检项。 |
+| `legacy_signals` | 旧路径或旧规则信号。 |
+
+## 检查等级
+
+| 级别 | 含义 | 是否影响 `ok` |
+|---|---|---|
+| `pass` | 通过。 | 否 |
+| `info` | 补充事实。 | 否 |
+| `warn` | 有风险，但需要 AI 判断是否修复。 | 默认不影响；`--strict` 下影响 |
+| `fail` | 阻塞问题，Hub 或 Satellite 巡检不可信。 | 是 |
+
+## 输出原则
+
+`audit --json` 不允许输出：
+
+- `next_steps`
+- `suggestions`
+- `recommended_actions`
+- Pack 推荐
+- 自动修复建议
+
+这些内容属于 `starworkAudit`。
+
+## 和 `starworkAudit` 的接口
+
+`starworkAudit` 应优先运行：
+
+```bash
+starwork audit --hub <hub-path> --json --inventory-depth all
+```
+
+然后基于 JSON 做：
+
+- 整体健康解读。
+- 项目问题分级。
+- 需要用户确认的问题。
+- 修复蓝图设计。
+
+## 和 `repair` 的接口
+
+`audit` 不生成 repair blueprint，但它的 JSON 是 repair blueprint 的事实来源。
+
+repair blueprint 应记录：
+
+```json
+{
+  "source": {
+    "audit_schema": "starwork.audit.result.v0.1",
+    "hub": "/Users/example/my-hub"
+  }
+}
+```
+
+## 验收测试
+
+第一版至少覆盖：
+
+1. 健康 Hub + 两个健康 Satellite，`audit` 返回 ok。
+2. `--project` 只巡检指定项目。
+3. registry 中项目路径不存在，项目结果为 fail。
+4. Satellite doctor fail，audit 聚合 fail。
+5. `.core-sync.json` 指向错误 Hub，audit 输出 sync warning 或 fail。
+6. Satellite 缺 `.starwork/handoff/`，audit 输出 warning。
+7. 旧 `_系统/跨项目/` 只作为 legacy signal。
+8. `audit --json` 不包含 next steps 或建议字段。