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

package/cli/src/cli.js

@@ -146,6 +146,7 @@ const MANUAL_HANDOFF_STATUS = "manual_handoff_required";
 const HOST_DELIVERY_STATUSES = new Set([
   "delivered",
   "delivered_via_codex_thread_tool",
+  "delivered_via_claude_code_session_tool",
   "recorded_only",
   MANUAL_HANDOFF_STATUS,
   "failed"
@@ -10270,7 +10271,7 @@ Options:
   --from <lane-id>
   --to <lane-id>
   --message <text>
-  --host-delivery <delivered_via_codex_thread_tool|recorded_only|manual_handoff_required|failed>
+  --host-delivery <delivered_via_codex_thread_tool|delivered_via_claude_code_session_tool|recorded_only|manual_handoff_required|failed>
   --delivery-tool <tool-name>
   --id <request-id>
   --json

package/cli/test/init.test.js

@@ -146,6 +146,15 @@ function skillDescription(skillText) {
   return skillText.match(/^description:\s*['"]?([\s\S]*?)['"]?\n---/m)?.[1] || "";
 }
 
+function markdownSection(markdown, heading) {
+  const marker = `## ${heading}\n`;
+  const start = markdown.indexOf(marker);
+  if (start === -1) return "";
+  const bodyStart = start + marker.length;
+  const next = markdown.indexOf("\n## ", bodyStart);
+  return markdown.slice(bodyStart, next === -1 ? undefined : next);
+}
+
 test("prints version and product-oriented help", () => {
   const version = runCommand(["--version"]);
   assert.equal(version.status, 0);
@@ -277,11 +286,77 @@ test("starworkMultiagent skill uses Codex standard session tools directly", () =
   assert.match(skill, /multiagent share/);
   assert.match(skill, /multiagent request record/);
   assert.match(skill, /delivered_via_codex_thread_tool/);
+  assert.match(skill, /delivered_via_claude_code_session_tool/);
+  assert.match(skill, /mcp__ccd_session_mgmt__send_message/);
+  assert.match(skill, /mcp__ccd_session_mgmt__search_session_transcripts/);
   assert.match(skill, /STARWORK:MULTIAGENT_MESSAGE v1/);
   assert.match(skill, /manual_handoff_required/);
   assert.match(skill, /pending_merge/);
 });
 
+test("starworkMultiagent skill presents friendly onboarding before internal workflow", () => {
+  const skill = fs.readFileSync(path.join(root, "skills", "starworkMultiagent", "SKILL.md"), "utf8");
+  const firstScreen = markdownSection(skill, "创建 AI 团队的第一屏");
+  const questionSection = markdownSection(skill, "自然追问");
+  const previewSection = markdownSection(skill, "预览与确认");
+  const fallbackSection = markdownSection(skill, "降级与安全接入");
+
+  assert.notEqual(firstScreen.trim(), "");
+  assert.match(firstScreen, /AI 岗位/);
+  assert.match(firstScreen, /负责什么/);
+  assert.match(firstScreen, /可以整理或修改哪些内容/);
+  assert.match(firstScreen, /交接/);
+  assert.match(firstScreen, /先检查当前项目是否准备好/);
+  assert.match(firstScreen, /先预览/);
+  assert.match(firstScreen, /确认后/);
+  assert.doesNotMatch(firstScreen, /lane|write_scope|binding|thread|CLI|doctor|multiagent init|multiagent add/);
+
+  assert.match(questionSection, /这个项目主要想完成什么/);
+  assert.match(questionSection, /希望哪些事情交给不同 AI 分开做/);
+  assert.match(questionSection, /哪些文件或内容不希望 AI 主动修改/);
+  assert.doesNotMatch(questionSection, /请输入 lane id|write_scope 怎么填|session id/);
+
+  assert.match(previewSection, /AI 岗位[\s\S]*负责什么[\s\S]*可以整理或修改的范围[\s\S]*交接方式/);
+  assert.match(previewSection, /如果这个方案没问题，我再创建这些协作记录/);
+  assert.match(previewSection, /下面是预览，还不会真正写入/);
+  assert.match(previewSection, /这次只写入了协作记录，没有改你的业务内容/);
+
+  assert.match(fallbackSection, /我还不能确认这个目录已经适合开启多 AI 分工/);
+  assert.match(fallbackSection, /当前这个 AI 工具暂时不能自动把消息送到另一个会话/);
+  assert.match(fallbackSection, /还没有自动送达/);
+  assert.doesNotMatch(fallbackSection, /已通知|已发送成功/);
+  assert.match(skill, /岗位已创建/);
+  assert.match(skill, /会话已绑定/);
+  assert.match(skill, /消息已送达/);
+  assert.match(skill, /目标任务已完成/);
+  assert.match(skill, /你可以这样开始/);
+  assert.match(skill, /这些只是参考/);
+  assert.match(skill, /不会直接套模板/);
+});
+
+test("multiagent user docs describe friendly onboarding instead of command-first workflow", () => {
+  const userGuide = fs.readFileSync(path.join(root, "docs", "multiagent-user-guide.md"), "utf8");
+  const alphaGuide = fs.readFileSync(path.join(root, "docs", "alpha-test-guide.md"), "utf8");
+  const registry = fs.readFileSync(path.join(root, "docs", "cli-skill-registry.html"), "utf8");
+  const planningSkill = fs.readFileSync(path.join(root, "planning", "features", "multiagent", "skill.md"), "utf8");
+
+  assert.match(userGuide, /安装完成后，第一句话怎么说/);
+  assert.match(userGuide, /请先只做检查和方案设计，不要直接写入/);
+  assert.match(userGuide, /AI 岗位/);
+  assert.match(userGuide, /先预览/);
+  assert.match(userGuide, /等我确认/);
+  assert.match(alphaGuide, /v0\.9 友好引导体验/);
+  assert.match(alphaGuide, /第一屏不出现内部词/);
+  assert.match(alphaGuide, /AI 岗位/);
+  assert.match(registry, /AI 岗位|职责位/);
+  assert.match(registry, /先预览/);
+  assert.match(registry, /交接消息/);
+  assert.doesNotMatch(registry, /翻译成 <code>multiagent init\/add\/bind\/read\/instruct\/launch\/status\/share<\/code> 命令组合/);
+  assert.match(planningSkill, /v0\.9/);
+  assert.match(planningSkill, /AI 岗位/);
+  assert.match(planningSkill, /v0\.8 调用边界/);
+});
+
 test("starworkInit skill keeps existing projects in agent-docs draft mode", () => {
   const skill = fs.readFileSync(path.join(root, "skills", "starworkInit", "SKILL.md"), "utf8");
 
@@ -305,9 +380,9 @@ test("init-family skills start with user-facing capability framing", () => {
   assert.match(knowledge, /项目知识库是让 AI 长期记住项目稳定理解的地方/);
   assert.match(knowledge, /不是原始资料文件夹/);
   assert.match(knowledge, /先检查当前项目是否已经有知识库/);
-  assert.match(multiagent, /多 Agent 分工是把一个项目里的不同 AI 会话按职责分开协作/);
-  assert.match(multiagent, /先设计职责/);
-  assert.match(multiagent, /再创建或绑定会话/);
+  assert.match(multiagent, /帮你把这个项目拆成几个清楚的 AI 岗位/);
+  assert.match(multiagent, /先检查当前项目是否准备好/);
+  assert.match(multiagent, /等你确认后再正式创建/);
   assert.match(doctor, /诊断是先看清当前目录的事实/);
   assert.match(doctor, /升级是无损补齐 StarWork 工作台规则/);
   assert.match(doctor, /不会移动、删除或覆盖你的历史文件/);
@@ -1809,6 +1884,36 @@ test("multiagent request record supports Codex thread-tool delivery status", ()
   assert.equal(state.requests[0].host_delivery.delivery_tool, "send_message_to_thread");
 });
 
+test("multiagent request record supports Claude Code Desktop session-tool delivery status", () => {
+  const dir = tempDir();
+  runInit(["--type", "single-light", "--pack", "general", "--target", dir, "--yes"]);
+  runCommand(["multiagent", "init", "--target", dir, "--yes"]);
+  runCommand(["multiagent", "add", "product-planning", "--purpose", "产品规划", "--write", "product/planning/**", "--target", dir, "--yes"]);
+  runCommand(["multiagent", "add", "development", "--purpose", "功能开发", "--write", "product/cli/**", "--target", dir, "--yes"]);
+
+  const record = runCommand([
+    "multiagent", "request", "record",
+    "--from", "product-planning",
+    "--to", "development",
+    "--message", "请开始实现 Claude Code Desktop 投递。",
+    "--host-delivery", "delivered_via_claude_code_session_tool",
+    "--delivery-tool", "ccd_session_mgmt_send_message",
+    "--target", dir,
+    "--json",
+    "--yes"
+  ]);
+  const recordResult = JSON.parse(record.stdout);
+  const shared = fs.readFileSync(path.join(dir, "_系统", "协作", "shared.md"), "utf8");
+  const state = readJson(path.join(dir, ".starwork", "agent-lanes", "state.json"));
+
+  assert.equal(record.status, 0);
+  assert.equal(recordResult.host_delivery.status, "delivered_via_claude_code_session_tool");
+  assert.equal(recordResult.host_delivery.delivery_tool, "ccd_session_mgmt_send_message");
+  assert.match(shared, /product-planning \| development \| 请开始实现 Claude Code Desktop 投递。 \| delivered_via_claude_code_session_tool \| delivered_via_claude_code_session_tool/);
+  assert.equal(state.requests[0].host_delivery.status, "delivered_via_claude_code_session_tool");
+  assert.equal(state.requests[0].host_delivery.delivery_tool, "ccd_session_mgmt_send_message");
+});
+
 test("multiagent request record accepts recorded-only Codex boundary status", () => {
   const dir = tempDir();
   runInit(["--type", "single-light", "--pack", "general", "--target", dir, "--yes"]);

package/docs/README.md

@@ -7,6 +7,10 @@
 - [product-direction.md](product-direction.md)：StarWork 产品方向、四层结构和关键约束
 - [ai-consultant-brief.md](ai-consultant-brief.md)：给外部 AI 顾问快速了解 StarWork 产品、当前状态和目录结构的简报
 - [agent-install-guide.md](agent-install-guide.md)：面向用户 Agent 的 StarWork CLI 与 Skills 安装指导
+- [starwork-multiagent-install-guide.md](starwork-multiagent-install-guide.md)：仅安装 StarWork MultiAgent Skill、配套 CLI 和最小必要 Skills 的说明，含可复制给 AI 的安装提示词
+- [multiagent-ai-install-playbook.md](multiagent-ai-install-playbook.md)：面向 AI 助手读取的 StarWork MultiAgent 安装执行说明，强调友好沟通、宿主自适应和安装边界
+- [multiagent-user-guide.md](multiagent-user-guide.md)：面向普通用户的 StarWork MultiAgent 使用说明，包含场景案例和可复制给 AI 的引导提示词
+- [multiagent-skill-friendly-onboarding-requirements.md](multiagent-skill-friendly-onboarding-requirements.md)：面向产品设计的 MultiAgent Skill 友好引导改进建议
 - [alpha-test-guide.md](alpha-test-guide.md)：StarWork A 测 CLI 与 Skills 安装、测试和反馈指南
 - [issue-feedback-tracking-guide.md](issue-feedback-tracking-guide.md)：Issue 反馈与跟踪机制搭建指南，供用户项目和 Agent 模仿构建
 - [cli-skill-registry.html](cli-skill-registry.html)：当前 CLI 与 StarWork 自研 Skill 的能力注册表、分发边界和配合链路

package/docs/alpha-test-guide.md

@@ -192,6 +192,24 @@ starwork doctor --target ~/Desktop/starwork-alpha-project
 
 这一步适合希望测试多个 Agent 职责位、独立会话创建和跨会话交付的用户。Codex App 正常路径由 `starworkMultiagent` Skill 直接调用标准线程工具；CLI 只记录项目内事实源。
 
+#### v0.9 友好引导体验
+
+在 Codex App 中先对 `starworkMultiagent` 说：
+
+```text
+请帮我创建一个 AI 团队。先不要写入，只帮我看看这个项目适合怎么分工。
+```
+
+预期：
+
+- 第一屏不出现内部词，例如 `lane`、`write_scope`、`binding`、`thread`、`CLI`、`doctor`、`multiagent init`、`multiagent add`。
+- 第一屏用“AI 岗位”解释流程，并说明每个岗位“负责什么 / 可以整理或修改哪些内容 / 怎么交接”。
+- 第一屏说明会先检查、再设计、先预览、确认后再正式创建。
+- 如果信息不够，优先问项目目标、希望哪些事情交给不同 AI 分开做、哪些文件或内容不希望 AI 主动修改。
+- 创建或调整岗位前，应显示“AI 岗位 / 负责什么 / 可以整理或修改的范围 / 交接方式”的表格，并出现“如果这个方案没问题，我再创建这些协作记录。”
+- 写入前应说明“下面是预览，还不会真正写入”；写入后应说明“这次只写入了协作记录，没有改你的业务内容”。
+- 自动线程工具不可用时，应解释为当前 AI 工具能力差异，输出完整可复制交接消息，并明确还没有自动送达。
+
 先初始化项目内的职责位：
 
 ```bash
@@ -355,6 +373,7 @@ Cursor / Trae 写入 Skill 目录后，宿主 UI 是否立即发现需要继续
 - `starwork doctor --host <host>` 是否能区分“工作台结构问题”和“宿主入口 / Skill 目录问题”。
 - Cursor / Trae 在写入 `.cursor/skills/` / `.trae/skills/` 后是否需要重启、刷新窗口或重新打开项目。
 - 返回 `manual_handoff_required` 时，用户是否能理解“已生成交付消息，不等于已自动送达”。
+- v0.9 友好引导体验是否能让新用户理解“AI 岗位 / 先预览 / 确认后创建”，而不是被内部命令和字段吓退。
 - 项目中心自带的 `starworkSpawn`、`starworkAudit` 与项目工作台自带的 `neat-freak` 是否能在对应工作台内被发现。
 
 ## 发布前检查

package/docs/cli-skill-registry.html

@@ -659,10 +659,10 @@
           </tr>
           <tr>
             <td><strong><code>starworkMultiagent</code></strong></td>
-            <td>L1 系统专家：多 AI 协作命令包装助手。</td>
-            <td>用户想把当前会话登记为常用智能体、管理 AI 职责位、绑定或释放 session、查看分工、登记共享输出、读取其他 lane 状态、向其他 lane 发指令或创建 lane thread。</td>
-            <td>判断用户语义；确认 lane ID、职责、写入范围、session、跨会话指令内容和回报方式；把请求翻译成 <code>multiagent init/add/bind/read/instruct/launch/status/share</code> 命令组合。</td>
-            <td>multiagent dry-run 命令、确认后的执行命令、当前分工解释、Codex host observation 解释、过程材料放置建议。</td>
+            <td>L1 系统专家：多 AI 协作顾问。</td>
+            <td>用户想创建 AI 团队、设计 AI 岗位 / 职责位、把当前 AI 会话登记到某个岗位、查看分工、登记共享成果、准备交接消息或查看其他岗位进展。</td>
+            <td>先用用户语言解释多 AI 分工；自然追问项目目标、分工需求和不希望主动修改的内容；先预览 AI 岗位表格，说明负责什么、可以整理或修改的范围和交接方式；确认后再写入协作记录。</td>
+            <td>岗位方案预览、写入影响说明、确认后的协作记录、交接消息、当前分工解释、Codex 标准线程工具动作结果、过程材料放置建议。</td>
             <td><code>starwork multiagent</code></td>
             <td><span class="status done">已实现</span></td>
           </tr>

package/docs/multiagent/session-control-support-matrix.md

@@ -7,7 +7,8 @@
 | 宿主软件 | 识别当前会话 | 自动命名会话 | 自动列出会话 | 自动读取历史 | 自动向其他会话发指令 | 自动归档会话 | 自动置顶会话 |
 | --- | --- | --- | --- | --- | --- | --- | --- |
 | Codex App / Desktop | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 | 支持 |
-| Claude Code | 支持 | 不支持 | 不支持 | 支持 | 不支持 | 不支持 | 不支持 |
+| Claude Code Desktop | 支持 | 不支持 | 支持 | 支持 | 支持¹ | 支持¹ | 不支持 |
+| Claude Code CLI | 支持 | 不支持 | 不支持 | 支持 | 不支持 | 不支持 | 不支持 |
 | Cursor | 不支持 | 支持 | 不支持 | 不支持 | 不支持 | 不支持 | 不支持 |
 | Trae IDE | 支持 | 不支持 | 不支持 | 不支持 | 不支持 | 不支持 | 不支持 |
 | Trae Solo App | 不支持 | 不支持 | 不支持 | 不支持 | 不支持 | 不支持 | 不支持 |
@@ -18,3 +19,5 @@
 | --- | --- |
 | 支持 | StarWork 可以让工具自动完成，不需要用户手动去宿主软件里操作 |
 | 不支持 | StarWork 不能自动完成，需要用户自己在宿主软件里手动操作 |
+
+注¹：Claude Code 桌面端的「发送指令」和「归档」由标准会话工具自动完成，但每次会弹出用户确认，且仅在有人值守（非 auto / bypass）会话可用。这是权限闸门，不是让用户去宿主软件里手动操作，仍记为「支持」。

package/docs/multiagent-ai-install-playbook.md

@@ -0,0 +1,277 @@
+# StarWork MultiAgent AI 安装执行说明
+
+本文件只给 AI 助手读取，用来帮助用户安装 StarWork MultiAgent。
+
+请用非常友好的方式和用户沟通。用户不需要理解命令、目录、运行环境这些细节；你负责检查、解释、执行和汇报。除非用户主动追问，不要把内部术语一股脑抛给用户。
+
+## 你的目标
+
+帮用户完成三件事：
+
+1. 确认这台电脑能运行 StarWork。
+2. 安装 StarWork MultiAgent 需要的命令工具。
+3. 给用户当前使用的 AI 软件安装 MultiAgent 相关能力。
+
+安装完成后，不要自动初始化项目，不要创建测试工作台，不要改动用户项目文件。
+
+## 先对用户这样说
+
+开始前，先用类似下面的话说明你要做什么：
+
+```text
+我会先帮你检查电脑上是否具备运行 StarWork 的基础环境，然后安装 MultiAgent 需要的工具和 AI 能力。
+
+安装阶段不会改你的项目文件，也不会创建新的工作台。
+如果需要安装电脑上的基础软件，或者要做会影响全局环境的操作，我会先告诉你并等你确认。
+```
+
+## 第一步：确认用户正在用哪个 AI 软件
+
+不同 AI 软件的能力目录不同，不要手动猜目录，也不要直接复制文件到你以为正确的位置。优先使用 `skills` 安装工具，让它把能力安装到对应的软件目录。
+
+先判断当前环境：
+
+- 如果你明确知道当前是 Codex，默认使用 `codex`。
+- 如果你明确知道当前是 Claude Code、Cursor、Trae 或其他工具，先向用户确认工具名称。
+- 如果你无法判断，就问用户一句：
+
+```text
+你现在希望把 MultiAgent 安装到哪个 AI 工具里？比如 Codex、Claude Code、Cursor 或 Trae。
+```
+
+如果用户不知道，就建议先按 Codex 路径安装；后续换工具时再补装对应工具。
+
+不要直接暴露“宿主软件”“Skill 目录”“agent 参数”这些词。可以说“安装到你正在使用的 AI 工具里”。
+
+## 第二步：检查基础环境
+
+运行：
+
+```bash
+node --version
+npm --version
+```
+
+如果两个命令都有版本号，告诉用户：
+
+```text
+你的电脑已经具备运行 StarWork 的基础环境，我继续安装 MultiAgent。
+```
+
+如果其中一个命令不可用，停止安装。不要擅自安装系统软件。对用户说：
+
+```text
+这台电脑还缺少运行 StarWork 需要的基础环境：Node.js。
+
+你需要先安装 Node.js LTS 版本。安装好以后重新打开终端，我再继续帮你安装 MultiAgent。
+```
+
+可以给用户温和建议：
+
+- macOS：从 https://nodejs.org 下载 LTS 安装包；如果用户已经熟悉 Homebrew，也可以用 `brew install node`。
+- Windows：从 https://nodejs.org 下载 LTS 安装包；如果用户已经熟悉 winget，也可以用 `winget install OpenJS.NodeJS.LTS`。
+- Linux：使用系统包管理器或 Node.js 官方 LTS 安装方式。
+
+不要替用户直接安装 Node.js，除非用户明确授权。
+
+## 第三步：安装 StarWork 命令工具
+
+先说明：
+
+```text
+接下来我会安装 StarWork 的命令工具。这个工具负责在项目里创建和检查 MultiAgent 需要的协作记录。
+```
+
+运行：
+
+```bash
+npm install -g @jennie-shawn/starwork@latest
+```
+
+验证：
+
+```bash
+starwork --version
+starwork multiagent --help
+```
+
+如果全局安装失败，但用户不想处理全局安装问题，可以先验证临时运行方式：
+
+```bash
+npx @jennie-shawn/starwork@latest --version
+npx @jennie-shawn/starwork@latest multiagent --help
+```
+
+友好解释：
+
+```text
+全局安装是为了以后可以直接输入 starwork。
+如果这一步因为电脑权限失败，我们也可以先用临时运行方式继续验证，不会影响你的项目文件。
+```
+
+## 第四步：查看可安装能力
+
+运行：
+
+```bash
+npx skills add jennie-shawn/StarWork -l
+```
+
+确认列表里能看到：
+
+- `starwork`
+- `starworkInit`
+- `starworkDoctor`
+- `starworkMultiagent`
+
+如果还看到 `starworkKnowledge`，这是正常的；但本次默认不安装知识库能力。
+
+## 第五步：安装最小能力组合
+
+默认安装四项：
+
+- `starwork`：让 AI 知道 StarWork 是什么，并能把用户请求引导到正确能力。
+- `starworkInit`：当用户当前项目还没准备好时，安全引导接入。
+- `starworkDoctor`：检查当前项目是否已经适合开启 MultiAgent，帮助 AI 在写入前先做安全判断。
+- `starworkMultiagent`：本次要发布的 MultiAgent 核心能力。
+
+如果当前目标 AI 工具是 Codex，运行：
+
+```bash
+npx skills add jennie-shawn/StarWork --skill starwork -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
+```
+
+如果目标不是 Codex：
+
+1. 不要手动猜目录。
+2. 先确认 `skills` 工具支持的目标名称。
+3. 把命令里的 `codex` 换成用户确认的目标 AI 工具名称。
+4. 如果无法确认，停止并告诉用户需要确认安装目标。
+
+不要默认安装：
+
+- `starworkKnowledge`
+- `starworkSpawn`
+- `starworkAudit`
+- `neat-freak`
+- `starworkKnowledgeProject`
+
+如果选择性安装失败，再运行：
+
+```bash
+npx skills add jennie-shawn/StarWork -l
+```
+
+确认名称是否写错。如果当前 `skills` 工具不支持单独安装，才向用户解释 fallback：
+
+```text
+当前安装工具可能不支持只安装单个能力。可以退一步安装 StarWork 的全局基础能力包，它会多安装知识库入口，但不会初始化项目，也不会改动你的项目文件。你要继续吗？
+```
+
+用户确认后再运行：
+
+```bash
+npx skills add jennie-shawn/StarWork -g -a codex -y
+```
+
+## 第六步：验证安装
+
+验证命令工具：
+
+```bash
+starwork --version
+starwork multiagent --help
+```
+
+验证 AI 能力：
+
+```bash
+npx skills ls -g -a codex --json
+```
+
+确认至少能看到：
+
+- `starwork`
+- `starworkInit`
+- `starworkDoctor`
+- `starworkMultiagent`
+
+如果安装目标不是 Codex，把 `codex` 替换成实际目标名称。
+
+如果安装成功但当前 AI 会话仍然不认识 MultiAgent，告诉用户：
+
+```text
+安装已经完成了。有些 AI 工具需要新开一个会话才会重新读取新能力。
+请你新开一个 AI 会话，然后把我接下来给你的提示词发过去。
+```
+
+## 完成后的汇报方式
+
+用简短、安心的方式汇报：
+
+```text
+StarWork MultiAgent 已安装完成。
+
+我已经确认：
+1. StarWork 命令可以运行。
+2. MultiAgent 需要的 AI 能力已经安装到你的 AI 工具里。
+3. 安装阶段没有初始化项目，也没有改动你的项目文件。
+
+下一步你可以新开一个 AI 会话，让它帮你检查当前项目是否适合开启多 Agent 分工。
+```
+
+然后给用户下一步提示词：
+
+```text
+请使用 StarWork MultiAgent 帮我看看当前项目是否适合开启多 AI 分工。
+
+请先只做检查和方案设计，不要直接写入。
+如果当前目录还没有准备好，请先引导我完成安全接入。
+如果已经准备好，请帮我设计 3 到 5 个适合这个项目的 AI 岗位，并说明每个岗位负责什么、可以整理哪些文件、需要如何交接。
+所有写入动作都请先预览，等我确认后再执行。
+```
+
+## 常见问题处理
+
+### `node` 或 `npm` 不存在
+
+说明电脑还没安装 Node.js。停止安装，指导用户先安装 Node.js LTS。
+
+### `npm install -g` 权限失败
+
+不要让用户盲目使用危险命令。先建议使用 Node.js 官方安装包重新安装，或使用临时运行方式 `npx @jennie-shawn/starwork@latest --version` 验证。
+
+### `starwork` 命令找不到
+
+可能是全局命令目录没有进入系统路径。先试：
+
+```bash
+npx @jennie-shawn/starwork@latest --version
+```
+
+如果临时运行可用，说明包本身可用，只是全局命令路径需要用户电脑环境修复。
+
+### AI 安装后仍不认识 MultiAgent
+
+请用户新开 AI 会话。很多工具只在新会话启动时读取新安装的能力。
+
+### 用户问“会不会改我的项目”
+
+回答：
+
+```text
+安装阶段不会改项目文件。真正给项目开启 MultiAgent 前，我会先检查并展示准备写入的内容，等你确认后才执行。
+```
+
+## 禁止事项
+
+- 不要在安装阶段运行 `starwork init --yes`。
+- 不要在安装阶段运行 `starwork multiagent init --yes`。
+- 不要创建测试项目。
+- 不要修改用户项目文件。
+- 不要静默安装 Node.js。
+- 不要手动猜测并写入某个 AI 工具的能力目录。
+- 不要向用户展示大量内部命令输出；只汇报关键结果和下一步。