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

package/cli/src/cli.js

@@ -143,6 +143,13 @@ const AGENT_DOCS_PLAN_SCHEMA = "starwork.agent_docs_plan.v0.1";
 const AGENT_DOCS_DRAFT_DIR = path.join(".starwork", "drafts");
 const LEGACY_AGENT_DOC_SIDECARS = ["AGENTS.starwork.md", "AGENTS.starwork-new.md", "README.starwork-new.md", "CLAUDE.starwork.md"];
 const MANUAL_HANDOFF_STATUS = "manual_handoff_required";
+const HOST_DELIVERY_STATUSES = new Set([
+  "delivered",
+  "delivered_via_codex_thread_tool",
+  "recorded_only",
+  MANUAL_HANDOFF_STATUS,
+  "failed"
+]);
 
 const KIT_BUNDLED_SKILLS = {
   hub: [
@@ -320,6 +327,11 @@ async function init(argv) {
     })
     : null;
 
+  if (options.json && options.dryRun) {
+    console.log(JSON.stringify(renderInitPlanJson(plan, true), null, 2));
+    return;
+  }
+
   printPlan(plan, options.dryRun);
   if (adapterHosts.length && options.dryRun) {
     console.log("");
@@ -351,7 +363,10 @@ async function init(argv) {
     applyPlan(adapterPlan);
   }
   console.log("");
-  console.log("StarWork 工作台已创建。");
+  console.log("StarWork 工作台已经创建好了。");
+  console.log("");
+  console.log("这次写入的是项目协作文件，不是业务代码。");
+  console.log("健康检查可以确认 AI 后续能找到项目说明、当前任务和协作规则。");
   console.log("");
   console.log("下一步建议：");
   console.log(`1. 运行 starwork doctor --target ${plan.targetDir}`);
@@ -361,14 +376,15 @@ async function init(argv) {
     console.log("4. 创建项目后，运行 starwork audit 巡检项目中心里的项目登记。");
   } else {
     if (hasAgentDocsDrafts(targetDir)) {
-      console.log("2. AI 入口文档需要 Skill 整合后再生效；请用 starworkInit 读取 .starwork/drafts/agent-docs-plan.json 和 proposed 草稿。");
+      console.log("2. 还有一步没有自动完成：你的项目已经有 AI 规则文件，所以 StarWork 只生成了待整合草稿，没有直接覆盖原文件。");
+      console.log("3. AI 入口文档需要 Skill 整合后再生效；请用 starworkInit 读取 .starwork/drafts/agent-docs-plan.json 和 proposed 草稿，确认后再合并最终入口。");
     } else {
       console.log("2. 打开 AGENTS.md，确认 AI 入口规则。");
     }
     if (adapterHosts.length) {
-      console.log(`3. 已生成 ${adapterHosts.join(", ")} 适配入口；运行 starwork doctor --target ${plan.targetDir} --host ${adapterHosts.length === 1 ? adapterHosts[0] : "all"} 再检查一次。`);
+      console.log(`4. 已生成 ${adapterHosts.join(", ")} 适配入口；运行 starwork doctor --target ${plan.targetDir} --host ${adapterHosts.length === 1 ? adapterHosts[0] : "all"} 再检查一次。`);
     } else {
-      console.log("3. 如需生成特定 AI 工具适配文件，运行 starwork adapt。");
+      console.log("3. 下一步你可以用 Codex / Claude Code / Cursor 打开这个目录，让 AI 先读项目规则。");
     }
   }
 }
@@ -750,8 +766,14 @@ function parseArgs(argv) {
       options.sessionName = readValue(argv, ++i, arg);
     } else if (arg === "--from") {
       options.from = readValue(argv, ++i, arg);
+    } else if (arg === "--to") {
+      options.to = readValue(argv, ++i, arg);
     } else if (arg === "--message") {
       options.message = readValue(argv, ++i, arg);
+    } else if (arg === "--delivery-tool") {
+      options.deliveryTool = readValue(argv, ++i, arg);
+    } else if (arg === "--host-delivery") {
+      options.hostDelivery = readValue(argv, ++i, arg);
     } else if (arg === "--turns") {
       options.turns = readValue(argv, ++i, arg);
     } else if (arg === "--timeout") {
@@ -899,6 +921,14 @@ async function lanesCommand(argv) {
     await lanesLaunch(argv.slice(1));
     return;
   }
+  if (subcommand === "message") {
+    await lanesMessage(argv.slice(1));
+    return;
+  }
+  if (subcommand === "request") {
+    await lanesRequest(argv.slice(1));
+    return;
+  }
   if (subcommand === "share") {
     await lanesShare(argv.slice(1));
     return;
@@ -1029,19 +1059,19 @@ async function lanesBind(argv) {
   if (!options.json) {
     printGenericPlan(options.dryRun ? "绑定 Lane 预览（dry run）：" : "绑定 Lane 计划：", plan.actions);
     if (sessionName) {
-      console.log(`将尝试同步宿主会话名：${sessionName}（best effort）`);
+      console.log(`宿主会话名需由 starworkMultiagent 在 Codex App 中调用 set_thread_title 后，再由本命令记录：${sessionName}`);
       console.log("");
     }
     if (options.pin) {
-      console.log("将尝试置顶 Codex thread（best effort；当前 Codex 版本可能不支持）。");
+      console.log("宿主置顶需由 starworkMultiagent 在 Codex App 中调用 set_thread_pinned；本命令只记录 StarWork binding。");
       console.log("");
     }
   }
   if (options.dryRun) return;
   await confirmOrThrow(options, `是否将当前会话绑定到 Lane ${laneId}？`);
   applyPlan(plan);
-  const sessionNameSync = await renameHostSessionBestEffort({ session, sessionName });
-  const pinSync = pinHostThreadBestEffort({ session, requested: Boolean(options.pin) });
+  const sessionNameSync = createSessionNameRecordOnlyResult({ sessionName });
+  const pinSync = createHostPinRecordOnlyResult({ requested: Boolean(options.pin) });
   if (options.json) {
     console.log(JSON.stringify(renderLanesBindResult({
       workspaceRoot,
@@ -1176,7 +1206,7 @@ function printLanesHostStatus(report) {
     console.log(`  ${item.host.adapter || "host"} observation: ${item.host.status}${item.host.name ? `；name=${item.host.name}` : ""}${item.host.cwd ? `；cwd=${item.host.cwd}` : ""}${Number.isInteger(item.host.turn_count) ? `；turns=${item.host.turn_count}` : ""}`);
     if (item.host.continue_command) console.log(`  Continue: ${item.host.continue_command}`);
     if (item.host.status === "notLoaded") {
-      console.log("  说明：notLoaded 表示 thread 可能存在于历史中，但当前 app-server 尚未加载；可显式使用 --load。");
+      console.log("  说明：notLoaded 表示 thread 可能存在于历史中，但当前宿主观察接口尚未加载；可显式使用 --load。");
     }
     if (item.host.warning) console.log(`  Warning: ${item.host.warning}`);
   }
@@ -1463,73 +1493,202 @@ async function lanesLaunch(argv) {
     launchResults.forEach((result) => console.log(`- ${result.lane}${result.session_name ? ` -> ${result.session_name}` : ""}`));
     return;
   }
-  await confirmOrThrow(options, `是否 launch ${lanes.length} 个 Codex lane thread？`);
-  let nextRegistryLanes = registry.lanes;
-  let lanesState = readAgentLanesState(workspaceRoot);
+  await confirmOrThrow(options, `是否生成 ${lanes.length} 个 Codex lane launch message？`);
   for (const lane of lanes) {
     const sessionName = buildLaneLaunchSessionName({ lane, workspaceRoot, explicitName: options.sessionName });
     const launchMessage = renderMultiagentLaunchMessage({ lane, fromLane: options.from || "user", workspaceRoot, collaboration });
-    const launch = await launchCodexLane({ message: launchMessage, workspaceRoot, timeout: parsePositiveInt(options.timeout, 90000) });
-    const launchedThreadId = launch.thread_id || launch.created_thread_id || "";
-    const session = launchedThreadId ? `codex:${launchedThreadId}` : "unbound";
-    const sessionNameSync = launchedThreadId
-      ? await renameHostSessionBestEffort({ session, sessionName })
-      : createSessionNameSyncResult({
-        requested: Boolean(sessionName),
-        supported: false,
-        status: sessionName ? "skipped" : "not_requested",
-        name: sessionName,
-        warning: sessionName ? "No host thread was created to rename." : null
-      });
-    const bindingStatus = launch.thread_id && launch.status === "completed" ? "bound" : "unbound";
-    if (launch.thread_id && launch.status === "completed") {
-      const pinSync = pinHostThreadBestEffort({ session, requested: Boolean(options.pin) });
-      nextRegistryLanes = nextRegistryLanes.map((item) => item.lane === lane.lane ? { ...item, current_session: session } : item);
-      lanesState = updateAgentLaneHostState(lanesState, lane.lane, {
-        host: "codex",
-        current_session: session,
-        thread_id: launch.thread_id,
-        session_name: sessionName,
-        pinned: pinSync.status === "ok",
-        pin_status: pinSync.status,
-        created_by: "starwork multiagent launch",
-        created_at: new Date().toISOString(),
-        last_host_status: {
-          type: launch.status,
-          observed_at: new Date().toISOString()
-        }
-      });
-      launch.session_name_sync = sessionNameSync;
-      launch.pin_sync = pinSync;
-    }
     launchResults.push({
       lane: lane.lane,
-      ...launch,
-      session,
-      session_id: launchedThreadId || undefined,
+      adapter: "codex",
+      status: MANUAL_HANDOFF_STATUS,
       session_name: sessionName,
-      launch_status: launch.status,
-      rename_status: sessionNameSync.status,
-      rename_warning: sessionNameSync.warning || undefined,
-      binding_status: bindingStatus,
-      session_name_sync: sessionNameSync
+      launch_status: MANUAL_HANDOFF_STATUS,
+      rename_status: sessionName ? "requires_starworkMultiagent_tool" : "not_requested",
+      binding_status: "unbound",
+      message: launchMessage,
+      instructions: "Codex App 标准路径必须由 starworkMultiagent 直接调用 create_thread；CLI 只生成 Launch Message，不创建或绑定 Codex thread。",
+      warning: "CLI no longer launches Codex threads directly."
     });
   }
-  actions.push(...buildLanesRegistryPlan(workspaceRoot, nextRegistryLanes).actions);
-  actions.push(stateFileAction(workspaceRoot, lanesState));
-  applyPlan({ targetDir: workspaceRoot, actions: dedupeActions(actions) });
   if (options.json) {
     console.log(JSON.stringify({ schema: "starwork.agent_lanes.launch.v0.3", launches: launchResults }, null, 2));
     return;
   }
   console.log("");
   launchResults.forEach((result) => {
-    console.log(`Lane ${result.lane}: ${result.status}${result.thread_id ? ` (${result.thread_id})` : ""}${result.session_name ? ` -> ${result.session_name}` : ""}${result.warning ? ` - ${result.warning}` : ""}`);
-    if (result.rename_warning) console.log(`  Warning: host session rename skipped: ${result.rename_warning}`);
-    if (result.binding_status !== "bound") console.log("  Warning: lane was not bound because launch did not complete.");
+    console.log(`Lane ${result.lane}: ${result.status}${result.session_name ? ` -> ${result.session_name}` : ""}${result.warning ? ` - ${result.warning}` : ""}`);
+    console.log("  需要在 starworkMultiagent Skill 中调用 create_thread，成功返回 threadId 后再运行 multiagent bind 记录绑定。");
+    console.log("");
+    console.log(result.message.trimEnd());
   });
 }
 
+async function lanesMessage(argv) {
+  const subcommand = argv[0];
+  if (!subcommand || subcommand === "--help" || subcommand === "-h") {
+    printLanesMessageHelp();
+    return;
+  }
+  if (subcommand === "launch") {
+    await lanesMessageLaunch(argv.slice(1));
+    return;
+  }
+  if (subcommand === "instruct") {
+    await lanesMessageInstruct(argv.slice(1));
+    return;
+  }
+  throw new Error(`未知 multiagent message 子命令：${subcommand}`);
+}
+
+async function lanesMessageLaunch(argv) {
+  const options = parseArgs(argv);
+  if (options.help) {
+    printLanesMessageLaunchHelp();
+    return;
+  }
+  const laneId = normalizeLaneId(options._?.[0], "lane");
+  const workspaceRoot = requireWorkspaceRoot(path.resolve(options.target || process.cwd()));
+  const state = readWorkspaceState(workspaceRoot);
+  const collaboration = getCollaborationPaths(state);
+  const registry = readLanesRegistry(workspaceRoot);
+  const lane = findLaneOrThrow(registry.lanes, laneId);
+  const sessionName = buildLaneLaunchSessionName({ lane, workspaceRoot, explicitName: options.sessionName });
+  const message = renderMultiagentLaunchMessage({ lane, fromLane: options.from || "user", workspaceRoot, collaboration });
+  const payload = {
+    schema: "starwork.agent_lanes.message.v0.1",
+    type: "launch",
+    lane: laneId,
+    session_name: sessionName,
+    message
+  };
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  console.log(message.trimEnd());
+}
+
+async function lanesMessageInstruct(argv) {
+  const options = parseArgs(argv);
+  if (options.help) {
+    printLanesMessageInstructHelp();
+    return;
+  }
+  const toLane = normalizeLaneId(options._?.[0], "to-lane");
+  const fromLane = normalizeLaneId(options.from || "user", "from lane");
+  if (!options.message) throw new Error("multiagent message instruct 需要 --message <text>。");
+  const workspaceRoot = requireWorkspaceRoot(path.resolve(options.target || process.cwd()));
+  const { requestId, message } = buildMultiagentInstructionPayload({
+    workspaceRoot,
+    toLane,
+    fromLane,
+    text: options.message,
+    requestId: options.id
+  });
+  const payload = {
+    schema: "starwork.agent_lanes.message.v0.1",
+    type: "instruction",
+    request_id: requestId,
+    from_lane: fromLane,
+    to_lane: toLane,
+    message
+  };
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  console.log(message.trimEnd());
+}
+
+async function lanesRequest(argv) {
+  const subcommand = argv[0];
+  if (!subcommand || subcommand === "--help" || subcommand === "-h") {
+    printLanesRequestHelp();
+    return;
+  }
+  if (subcommand === "record") {
+    await lanesRequestRecord(argv.slice(1));
+    return;
+  }
+  throw new Error(`未知 multiagent request 子命令：${subcommand}`);
+}
+
+async function lanesRequestRecord(argv) {
+  const options = parseArgs(argv);
+  if (options.help) {
+    printLanesRequestRecordHelp();
+    return;
+  }
+  const fromLane = normalizeLaneId(options.from || "user", "from lane");
+  const toLane = normalizeLaneId(options.to || options._?.[0], "to-lane");
+  if (!options.message) throw new Error("multiagent request record 需要 --message <text>。");
+  const hostDelivery = normalizeHostDeliveryStatus(options.hostDelivery || options.status || "");
+  const deliveryTool = normalizeMarkdownCell(options.deliveryTool || "manual");
+  const workspaceRoot = requireWorkspaceRoot(path.resolve(options.target || process.cwd()));
+  const state = readWorkspaceState(workspaceRoot);
+  const collaboration = getCollaborationPaths(state);
+  const registry = readLanesRegistry(workspaceRoot);
+  if (fromLane !== "user") findLaneOrThrow(registry.lanes, fromLane);
+  findLaneOrThrow(registry.lanes, toLane);
+  const requestId = options.id ? normalizeMarkdownCell(options.id) : buildLaneRequestId(toLane);
+  const shared = readSharedContext(workspaceRoot);
+  const requestRow = buildSharedRequestRow({
+    id: requestId,
+    from: fromLane,
+    to: toLane,
+    request: options.message,
+    status: hostDelivery,
+    hostDelivery,
+    link: collaboration.shared
+  });
+  const lanesState = readAgentLanesState(workspaceRoot);
+  const nextState = {
+    ...lanesState,
+    requests: [...(lanesState.requests || []), {
+      id: requestId,
+      from: fromLane,
+      to: toLane,
+      message_type: "instruction",
+      recorded_in: collaboration.shared,
+      host_delivery: {
+        status: hostDelivery,
+        delivery_tool: deliveryTool,
+        mode: "record_only"
+      }
+    }]
+  };
+  const actions = [
+    ...buildSharedContextPlan(workspaceRoot, {
+      outputs: shared.outputs,
+      requests: [...shared.requests, requestRow],
+      agreements: shared.agreements
+    }).actions,
+    stateFileAction(workspaceRoot, nextState)
+  ];
+  if (!options.json) printGenericPlan(options.dryRun ? "记录跨 lane 请求预览（dry run）：" : "记录跨 lane 请求计划：", actions);
+  if (options.dryRun) {
+    if (options.json) console.log(JSON.stringify({ schema: "starwork.agent_lanes.request_record.v0.1", dry_run: true, request: requestRow }, null, 2));
+    return;
+  }
+  await confirmOrThrow(options, `是否记录 ${fromLane} -> ${toLane} 的跨 lane 请求？`);
+  applyPlan({ targetDir: workspaceRoot, actions });
+  const result = {
+    schema: "starwork.agent_lanes.request_record.v0.1",
+    request: requestRow,
+    host_delivery: {
+      status: hostDelivery,
+      delivery_tool: deliveryTool,
+      mode: "record_only"
+    }
+  };
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log("");
+  console.log(`已记录跨 lane 请求：${requestId}`);
+}
+
 async function lanesShare(argv) {
   const options = parseArgs(argv);
   if (options.help) {
@@ -3818,6 +3977,25 @@ function getHubStatePathsForLanguage(language = "en") {
   };
 }
 
+function resolveWorkspaceRolePath(state, role, fallbackPath) {
+  const mappings = state?.upgrade?.core_role_mapping;
+  if (Array.isArray(mappings)) {
+    const mapping = mappings.find((item) => item?.role === role && item.path);
+    if (mapping) {
+      return {
+        role,
+        path: normalizeSafeRelativePath(mapping.path, `upgrade core_role_mapping.${role}`),
+        source: "upgrade.core_role_mapping"
+      };
+    }
+  }
+  return {
+    role,
+    path: normalizeRelativePath(fallbackPath),
+    source: "default"
+  };
+}
+
 function checkPackInstallations(result, workspaceRoot, state) {
   if (!Array.isArray(state.packs)) return;
   for (const installedPack of state.packs) {
@@ -3918,6 +4096,7 @@ function checkUpgradeRoleMappings(result, workspaceRoot, state) {
 
 function checkSkillInstallations(result, workspaceRoot, state) {
   const manifestPath = path.join(workspaceRoot, ".starwork", "skills.json");
+  let manifestSkills = [];
   const skills = {
     project_manifest: {
       exists: fs.existsSync(manifestPath),
@@ -3925,6 +4104,7 @@ function checkSkillInstallations(result, workspaceRoot, state) {
       count: 0
     },
     registry: null,
+    required: [],
     mounts: []
   };
   result.skills = skills;
@@ -3946,7 +4126,7 @@ function checkSkillInstallations(result, workspaceRoot, state) {
       } else {
         addCheck(result, "skills.project_manifest.schema", "fail", "项目 Skill 清单 schema 不正确。", ".starwork/skills.json");
       }
-      const manifestSkills = Array.isArray(manifest.skills) ? manifest.skills : [];
+      manifestSkills = Array.isArray(manifest.skills) ? manifest.skills : [];
       skills.project_manifest.count = manifestSkills.length;
       for (const skill of manifestSkills) {
         if (!skill?.id) {
@@ -3975,40 +4155,135 @@ function checkSkillInstallations(result, workspaceRoot, state) {
 
   if (state.workspace_type === "hub") {
     const hubPaths = getHubPaths(state);
-    const registryRelativePath = path.join(hubPaths.formalSkills, "registry.json");
+    const skillsRoot = resolveWorkspaceRolePath(state, "skills", hubPaths.formalSkills);
+    const registryRelativePath = path.join(skillsRoot.path, "registry.json");
     const registryPath = path.join(workspaceRoot, registryRelativePath);
     skills.registry = {
       exists: fs.existsSync(registryPath),
       path: registryRelativePath,
+      path_source: skillsRoot.source,
+      role: skillsRoot.role,
       count: 0
     };
     if (!skills.registry.exists) {
       addCheck(result, "skills.registry.exists", "warn", "项目中心缺少托管 Skill 注册表。", registryRelativePath);
-      return;
-    }
-    addCheck(result, "skills.registry.exists", "pass", "Project Center skill registry exists", registryRelativePath);
-    let registry;
-    try {
-      registry = JSON.parse(fs.readFileSync(registryPath, "utf8"));
-    } catch (error) {
-      addCheck(result, "skills.registry.parse", "fail", `无法解析项目中心 Skill registry：${error.message}`, registryRelativePath);
-      return;
-    }
-    if (registry.schema === "starwork.skill_registry.v0.1") {
-      addCheck(result, "skills.registry.schema", "pass", "Project Center skill registry schema is valid", registryRelativePath);
     } else {
-      addCheck(result, "skills.registry.schema", "fail", "项目中心 Skill registry schema 不正确。", registryRelativePath);
-    }
-    const registrySkills = Array.isArray(registry.skills) ? registry.skills : [];
-    skills.registry.count = registrySkills.length;
-    for (const skill of registrySkills) {
-      if (!skill?.id) {
-        addCheck(result, "skills.registry.id.exists", "fail", "项目中心 Skill registry 中存在缺少 id 的条目。", registryRelativePath);
-        continue;
+      addCheck(result, "skills.registry.exists", "pass", "Project Center skill registry exists", registryRelativePath);
+      let registry;
+      try {
+        registry = JSON.parse(fs.readFileSync(registryPath, "utf8"));
+      } catch (error) {
+        addCheck(result, "skills.registry.parse", "fail", `无法解析项目中心 Skill registry：${error.message}`, registryRelativePath);
+        registry = null;
+      }
+      if (registry) {
+        if (registry.schema === "starwork.skill_registry.v0.1") {
+          addCheck(result, "skills.registry.schema", "pass", "Project Center skill registry schema is valid", registryRelativePath);
+        } else {
+          addCheck(result, "skills.registry.schema", "fail", "项目中心 Skill registry schema 不正确。", registryRelativePath);
+        }
+        const registrySkills = Array.isArray(registry.skills) ? registry.skills : [];
+        skills.registry.count = registrySkills.length;
+        for (const skill of registrySkills) {
+          if (!skill?.id) {
+            addCheck(result, "skills.registry.id.exists", "fail", "项目中心 Skill registry 中存在缺少 id 的条目。", registryRelativePath);
+            continue;
+          }
+          checkPathExists(result, workspaceRoot, path.join(skillsRoot.path, skill.id), "skills.registry.source.exists", `Project Center skill source exists: ${skill.id}`, `项目中心托管 Skill 缺少目录：${path.join(skillsRoot.path, skill.id)}`);
+        }
       }
-      checkPathExists(result, workspaceRoot, path.join(hubPaths.formalSkills, skill.id), "skills.registry.source.exists", `Project Center skill source exists: ${skill.id}`, `项目中心托管 Skill 缺少目录：${path.join(hubPaths.formalSkills, skill.id)}`);
     }
   }
+
+  checkRequiredSkillInstallations(result, workspaceRoot, state, manifestSkills);
+}
+
+function collectRequiredSkills(state) {
+  if (state.workspace_type === "hub" && state.kit === "hub") {
+    return (KIT_BUNDLED_SKILLS.hub || []).map((skill) => ({
+      ...skill,
+      required_by: "kit:hub"
+    }));
+  }
+  return [];
+}
+
+function checkRequiredSkillInstallations(result, workspaceRoot, state, manifestSkills) {
+  const requiredSkills = collectRequiredSkills(state);
+  if (!requiredSkills.length) return;
+
+  const hubPaths = getHubPaths(state);
+  const skillsRoot = resolveWorkspaceRolePath(state, "skills", hubPaths.formalSkills);
+  const manifestIds = new Set(manifestSkills.map((skill) => skill?.id).filter(Boolean));
+  const reports = [];
+
+  for (const required of requiredSkills) {
+    const sourcePath = path.join(skillsRoot.path, required.id);
+    const skillFilePath = path.join(sourcePath, "SKILL.md");
+    const sourceExists = fs.existsSync(path.join(workspaceRoot, skillFilePath));
+    const frontmatter = sourceExists
+      ? parseSkillFrontmatter(fs.readFileSync(path.join(workspaceRoot, skillFilePath), "utf8"))
+      : {};
+    const frontmatterOk = sourceExists && Boolean(frontmatter.name) && Boolean(frontmatter.description);
+    const mounts = (required.install || [])
+      .filter((install) => install.agent !== "hub")
+      .map((install) => {
+        const mountPath = normalizeRelativePath(install.path);
+        return {
+          agent: install.agent,
+          path: mountPath,
+          status: fs.existsSync(path.join(workspaceRoot, mountPath)) ? "ok" : "missing"
+        };
+      });
+    const manifestStatus = manifestIds.has(required.id) ? "ok" : "missing";
+    const missingMount = mounts.some((mount) => mount.status !== "ok");
+    let status = "ok";
+    if (!sourceExists) {
+      status = "missing_source";
+    } else if (!frontmatterOk) {
+      status = "invalid_frontmatter";
+    } else if (manifestStatus !== "ok") {
+      status = "missing_manifest";
+    } else if (missingMount) {
+      status = "missing_mount";
+    }
+
+    const report = {
+      id: required.id,
+      required_by: required.required_by,
+      status,
+      source: {
+        path: sourcePath,
+        status: sourceExists ? "ok" : "missing",
+        path_source: skillsRoot.source
+      },
+      manifest: {
+        path: ".starwork/skills.json",
+        status: manifestStatus
+      },
+      mounts,
+      frontmatter: {
+        path: skillFilePath,
+        status: frontmatterOk ? "ok" : (sourceExists ? "invalid" : "missing")
+      },
+      repair_hint: "这是 Hub Kit 自带 Skill。请重新运行受控的 StarWork Hub Kit 安装/同步流程，或按文档补齐项目中心内的 Kit Skill；不要把它安装成全局系统 Skill。"
+    };
+    reports.push(report);
+
+    if (status === "ok") {
+      addCheck(result, `skills.required.${slugifyCheckId(required.id)}`, "pass", `Hub required Skill is installed: ${required.id}`, sourcePath);
+    } else {
+      const missingMounts = mounts.filter((mount) => mount.status !== "ok").map((mount) => mount.path);
+      const details = [
+        `应在项目中心内存在：${sourcePath}`,
+        `应登记在：.starwork/skills.json`,
+        ...missingMounts.map((mountPath) => `应挂载给宿主：${mountPath}`)
+      ].join("；");
+      addCheck(result, `skills.required.${slugifyCheckId(required.id)}`, "warn", `缺少 Hub 自带 Skill：${required.id}。${details}。建议：重新运行受控的 StarWork Hub Kit 安装/同步流程，或按文档补齐项目中心内的 Kit Skill。不要把它安装成全局系统 Skill。`, sourcePath);
+    }
+  }
+
+  result.skills.required = reports;
 }
 
 function checkPathExists(result, workspaceRoot, relativePath, id, passMessage, failMessage) {
@@ -4733,7 +5008,9 @@ function friendlyCheckLevel(level) {
 }
 
 function friendlyDoctorMessage(message) {
-  return String(message || "")
+  const text = String(message || "");
+  if (text.includes("缺少 Hub 自带 Skill")) return text;
+  return text
     .replace(/这是一个可升级的历史模板工作区，但缺少 \.starwork\/workspace\.json。/g, "这个目录像旧版工作区，但还缺少 StarWork 工作台身份证（.starwork/workspace.json）。")
     .replace(/检测到历史模板升级候选，置信度：(?:high|medium|low)。/g, "这个目录像旧版工作区，可以进一步判断如何整理。")
     .replace(/检测到主库 \/ Hub 候选，置信度：(?:high|medium|low)。/g, "这个目录像项目中心，可以进一步判断如何接入 StarWork。")
@@ -4819,10 +5096,17 @@ async function choosePack(workspaceType, workspaceConfig, options) {
 function printInitIntro(options, targetDir) {
   if (options.yes || !process.stdin.isTTY) return;
   console.log("");
-  console.log("StarWork 初始化向导");
+  console.log("可以，我先简单说清楚 StarWork 在做什么。");
+  console.log("");
+  console.log("StarWork 是给 AI 协作准备的项目工作台。它会把项目说明、当前任务、协作规则、交接记录和健康检查入口放到固定位置，让 AI 每次进入项目时不用从零猜上下文。");
+  console.log("");
+  console.log("这次我会带你做三件事：");
+  console.log("1. 确认这个工作台服务哪个项目；");
+  console.log("2. 预览 StarWork 准备补哪些协作文件；");
+  console.log("3. 你确认后再正式写入，并做一次检查。");
   console.log("");
   console.log(`目标目录：${targetDir}`);
-  console.log("我会先确认工作台类型、语言和 Pack，然后给出写入预览。");
+  console.log("我会先预览，不会直接改你的业务代码，也不会直接覆盖已有 AI 规则文件。");
 }
 
 async function chooseLanguage(options) {
@@ -7345,6 +7629,31 @@ ${message}
 `;
 }
 
+function buildMultiagentInstructionPayload({ workspaceRoot, toLane, fromLane, text, requestId = "" }) {
+  const state = readWorkspaceState(workspaceRoot);
+  const collaboration = getCollaborationPaths(state);
+  const registry = readLanesRegistry(workspaceRoot);
+  const targetLane = findLaneOrThrow(registry.lanes, toLane);
+  if (fromLane !== "user") findLaneOrThrow(registry.lanes, fromLane);
+  const resolvedRequestId = normalizeMarkdownCell(requestId || buildLaneRequestId(toLane));
+  return {
+    requestId: resolvedRequestId,
+    fromLane,
+    toLane,
+    targetLane,
+    collaboration,
+    message: renderMultiagentInstructionMessage({
+      requestId: resolvedRequestId,
+      fromLane,
+      toLane,
+      message: text,
+      collaboration,
+      targetLane,
+      workspaceRoot
+    })
+  };
+}
+
 function parseLaneList(value) {
   return String(value || "")
     .split(",")
@@ -7355,11 +7664,53 @@ function parseLaneList(value) {
 
 function buildLaneLaunchSessionName({ lane, workspaceRoot, explicitName }) {
   const requestedName = normalizeMarkdownCell(explicitName || "");
-  if (requestedName) return requestedName;
-  const roleName = normalizeMarkdownCell(lane?.purpose || lane?.lane || "");
+  if (requestedName) return sanitizeLaneSessionName(requestedName);
+  const roleName = deriveLaneRoleName(lane);
   return normalizeMarkdownCell(`${roleName || "Agent"} Agent`);
 }
 
+function deriveLaneRoleName(lane) {
+  const fallback = humanizeLaneId(lane?.lane || "agent");
+  const purpose = normalizeMarkdownCell(lane?.purpose || "");
+  if (/^(根据|只负责|用于)\s*/u.test(purpose)) {
+    return sanitizeLaneRoleName(fallback);
+  }
+  let roleName = purpose;
+  roleName = roleName.split(/[:：。；;，,、\n\r]/)[0].trim();
+  roleName = roleName.replace(/^(只负责|主要负责|负责|用于|协助|根据)\s*/u, "").trim();
+  if (!roleName || /^根据\s*/u.test(roleName) || /^(SPEC|spec|需求|任务)\b/.test(roleName)) {
+    roleName = fallback;
+  }
+  roleName = roleName.replace(/^(生成|实现|维护|处理)\s+/u, "").trim() || fallback;
+  return sanitizeLaneRoleName(roleName);
+}
+
+function humanizeLaneId(laneId) {
+  const normalized = normalizeMarkdownCell(laneId || "agent");
+  const parts = normalized.split(/[-_]+/).filter(Boolean);
+  if (!parts.length) return "Agent";
+  return parts.map((part) => {
+    if (/^[a-z]+$/i.test(part)) return `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`;
+    return part;
+  }).join(" ");
+}
+
+function sanitizeLaneRoleName(value) {
+  const sanitized = normalizeMarkdownCell(value)
+    .replace(/[:：。；;，,、\n\r].*$/u, "")
+    .replace(/\s+/g, " ")
+    .trim();
+  return sanitized.slice(0, 24).trim() || "Agent";
+}
+
+function sanitizeLaneSessionName(value) {
+  const sanitized = normalizeMarkdownCell(value)
+    .replace(/[\n\r]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  return sanitized.slice(0, 40).trim();
+}
+
 function resolveLaneLaunchHost({ options, lanes, workspaceRoot }) {
   const explicit = typeof options.host === "string" ? options.host : (options.agent || options.adapter || "");
   if (explicit) return normalizeAdapterHost(explicit);
@@ -7483,7 +7834,10 @@ async function observeHostSession(session, options = {}) {
     };
   }
   if (parsed.host === "codex") {
-    return observeCodexThread({ threadId: parsed.id, includeTurns: Boolean(options.includeTurns), load: Boolean(options.load), turnLimit: options.turnLimit || 0 });
+    return observeManualHostSession(parsed, {
+      status: "use_starworkMultiagent_tool",
+      warning: "Codex lane reading must be performed by starworkMultiagent with read_thread in the Codex App; CLI only reports the StarWork binding."
+    });
   }
   if (parsed.host === "claude-code") {
     return observeClaudeCodeSession(parsed, options);
@@ -8013,7 +8367,9 @@ function probeHostStandardSendCapability(host) {
     host,
     available: false,
     mode: null,
-    warning: `${host} standard background delivery capability is not available in this CLI runtime; low-level turn APIs are not used for multiagent instruct.`
+    warning: host === "codex"
+      ? "Codex delivery must be performed by starworkMultiagent with send_message_to_thread in the Codex App; CLI only records state and manual fallback."
+      : `${host} standard background delivery capability is not available in this CLI runtime; low-level turn APIs are not used for multiagent instruct.`
   };
 }
 
@@ -8122,6 +8478,17 @@ function createSessionNameSyncResult({ requested, supported, status, name = "",
   };
 }
 
+function createSessionNameRecordOnlyResult({ sessionName }) {
+  const requested = Boolean(sessionName);
+  return createSessionNameSyncResult({
+    requested,
+    supported: false,
+    status: requested ? "requires_starworkMultiagent_tool" : "not_requested",
+    name: sessionName,
+    warning: requested ? "Codex host title changes must be performed by starworkMultiagent with set_thread_title; CLI bind only records StarWork state." : null
+  });
+}
+
 function printSessionNameSyncResult(result) {
   if (!result.requested) return;
   if (result.status === "ok") {
@@ -8142,6 +8509,15 @@ function createHostPinResult({ requested, supported, status, warning = null }) {
   };
 }
 
+function createHostPinRecordOnlyResult({ requested }) {
+  return createHostPinResult({
+    requested: Boolean(requested),
+    supported: false,
+    status: requested ? "requires_starworkMultiagent_tool" : "not_requested",
+    warning: requested ? "Codex host pinning must be performed by starworkMultiagent with set_thread_pinned; CLI bind only records StarWork state." : null
+  });
+}
+
 function pinHostThreadBestEffort({ session, requested }) {
   if (!requested) {
     return createHostPinResult({ requested: false, supported: false, status: "not_requested" });
@@ -8765,6 +9141,14 @@ function buildSharedRequestRow({ id, from, to, request, status, hostDelivery, li
   };
 }
 
+function normalizeHostDeliveryStatus(value) {
+  const normalized = normalizeMarkdownCell(value || "");
+  if (!HOST_DELIVERY_STATUSES.has(normalized)) {
+    throw new Error(`--host-delivery 必须是 ${[...HOST_DELIVERY_STATUSES].join(" / ")}。`);
+  }
+  return normalized;
+}
+
 function parsePositiveInt(value, fallback) {
   if (value == null || value === "") return fallback;
   const parsed = Number.parseInt(value, 10);
@@ -9022,12 +9406,16 @@ function printGenericPlan(title, actions) {
 }
 
 function printPlan(plan, dryRun) {
-  const creates = plan.actions.filter((action) => action.mode === "create");
-  const emptyUpdates = plan.actions.filter((action) => action.mode === "overwrite-empty");
+  const creates = plan.actions.filter(actionCreatesFromUserView);
+  const updates = plan.actions.filter(actionUpdatesFromUserView);
   const createNew = plan.actions.filter((action) => action.mode === "create-new");
+  const isExistingProject = isExistingProjectTarget(plan);
 
   console.log("");
   console.log(dryRun ? "创建工作台预览：" : "创建工作台计划：");
+  if (dryRun) {
+    console.log("这是预览，不会写入文件。");
+  }
   console.log("");
   console.log(`工作台名称：${plan.workspaceName}`);
   console.log(`工作台类型：${plan.workspaceLabel}`);
@@ -9045,23 +9433,107 @@ function printPlan(plan, dryRun) {
     console.log(`会带上的 AI 使用说明：${plan.skills.map((skill) => skill.id).join("、")}`);
   }
   console.log("");
+  if (isExistingProject) {
+    console.log("检测到这是已有项目。");
+    console.log("StarWork 会保留现有文件，先生成待整合草稿，不直接覆盖已有 AI 规则文件。");
+    console.log("");
+  }
 
+  console.log("会创建：");
   if (creates.length) {
-    console.log("会创建这些文件或文件夹：");
-    creates.slice(0, 40).forEach((action) => console.log(`- ${action.relativePath}`));
-    if (creates.length > 40) console.log(`- ... 另有 ${creates.length - 40} 项`);
-    console.log("");
+    creates.forEach((action) => console.log(`- ${action.relativePath}`));
+  } else {
+    console.log("- 无");
   }
-  if (emptyUpdates.length) {
-    console.log("会补充这些空文件：");
-    emptyUpdates.forEach((action) => console.log(`- ${action.relativePath}`));
-    console.log("");
+  console.log("");
+
+  console.log("会更新：");
+  if (updates.length) {
+    updates.forEach((action) => console.log(`- ${action.relativePath}`));
+  } else {
+    console.log("- 无");
   }
+  console.log("");
+
+  console.log("不会改动：");
+  console.log("- 你的业务代码");
+  console.log("- 已有非空 AI 规则文件");
   if (createNew.length) {
-    console.log("发现已有同名文件，不会覆盖，会另存为：");
+    console.log("- 已有同名文件会保留，StarWork 会另存旁路文件");
     createNew.forEach((action) => console.log(`- ${path.relative(plan.targetDir, action.originalTarget)} -> ${action.relativePath}`));
-    console.log("");
   }
+  console.log("");
+
+  console.log("需要你确认：");
+  console.log("- 目标路径是否正确");
+  console.log("- 是否接受这些 StarWork 协作文件");
+  console.log("");
+}
+
+function renderInitPlanJson(plan, dryRun) {
+  return {
+    schema: "starwork.init.plan_result.v0.1",
+    target: plan.targetDir,
+    dry_run: Boolean(dryRun),
+    ok: true,
+    workspace_type: plan.workspaceType,
+    kit: plan.kit,
+    language: plan.language,
+    pack: plan.pack?.id || null,
+    actions: plan.actions.map((action) => ({
+      type: action.type,
+      mode: action.mode,
+      path: action.relativePath,
+      status: action.mode === "exists" ? "exists" : "planned"
+    })),
+    user_summary: buildInitUserSummary(plan, dryRun)
+  };
+}
+
+function buildInitUserSummary(plan, dryRun) {
+  const willCreate = plan.actions
+    .filter(actionCreatesFromUserView)
+    .map((action) => action.relativePath);
+  const willUpdate = plan.actions
+    .filter(actionUpdatesFromUserView)
+    .map((action) => action.relativePath);
+  return {
+    product_purpose: "把项目整理成 AI 协作工作台",
+    mode: dryRun ? "preview_no_write" : "write_after_confirmation",
+    target_kind: isExistingProjectTarget(plan) ? "existing_project" : "new_workspace",
+    will_create: willCreate,
+    will_update: willUpdate,
+    will_not_touch: [
+      "你的业务代码",
+      "已有非空 AI 规则文件"
+    ],
+    needs_confirmation: [
+      "目标路径是否正确",
+      "是否接受这些 StarWork 协作文件"
+    ]
+  };
+}
+
+function actionCreatesFromUserView(action) {
+  if (!action || action.mode === "exists" || action.mode === "skip") return false;
+  if (action.type === "directory") return action.mode === "create";
+  if (action.type === "symlink") return action.mode === "create" && !fs.existsSync(action.target);
+  if (action.type !== "file") return false;
+  if (action.mode === "create" || action.mode === "create-new") return true;
+  if (action.mode === "overwrite" || action.mode === "overwrite-empty") return !fs.existsSync(action.target);
+  return false;
+}
+
+function actionUpdatesFromUserView(action) {
+  if (!action || action.type !== "file") return false;
+  if (action.mode !== "overwrite" && action.mode !== "overwrite-empty") return false;
+  return fs.existsSync(action.target);
+}
+
+function isExistingProjectTarget(plan) {
+  if (!plan.targetExists || !fs.existsSync(plan.targetDir)) return false;
+  const entries = fs.readdirSync(plan.targetDir).filter((entry) => entry !== ".DS_Store");
+  return entries.length > 0;
 }
 
 function printSpawnPlan(plan, dryRun) {
@@ -9297,12 +9769,13 @@ function printInitHelp() {
 Usage:
   starwork init [options]
 
-创建一个 StarWork 工作台。v0.1 中，项目工作台默认加入通用工作能力；
-项目中心会自动加入项目中心管理能力。
+starwork init 会把一个目录整理成 StarWork 工作台，让 AI 能找到项目说明、当前任务、协作规则和交接记录。
+
+项目工作台默认加入通用工作能力；项目中心会自动加入项目中心管理能力。
 
 Options:
   --type <project|hub>
-      project 创建项目工作台；hub 创建项目中心
+      project 创建项目工作台；hub 创建项目中心。
   --pack <general|content-creator|hub-management|path>
   --language <zh|en>
   --name <name>
@@ -9313,11 +9786,13 @@ Options:
   --adapter <codex|claude-code|cursor|trae|all>
       初始化完成后继续生成对应 AI 工具适配入口。
   --agent-docs <draft|skip|write>
-      AI 入口文档策略。已有非空入口默认写入 .starwork/drafts 草稿，等待 starworkInit 整合。
+      已有 AI 规则文件时，先生成待整合草稿，不覆盖原文件。
   --target <path>
   --dry-run
+      预览将要写入的文件，不做真实改动。
   --no-skills
   --yes, -y
+      确认执行，会真实写入 StarWork 工作台文件。
 
 示例：
   starwork init --type project --pack general --language zh --target ./my-workspace --yes
@@ -9533,7 +10008,7 @@ function printLanesHelp() {
   console.log(`StarWork Multiagent
 
 Usage:
-  starwork multiagent <init|add|bind|release|status|read|instruct|handoff|continue|launch|share> [options]
+  starwork multiagent <init|add|bind|release|status|read|instruct|handoff|continue|launch|message|request|share> [options]
 
 Agent Lanes 用于同一项目内多个 Agent 会话按项目自定义职责位协作。
 
@@ -9547,7 +10022,9 @@ Subcommands:
   instruct   向另一个 lane 发送格式化跨会话指令。
   handoff    生成并记录人工交付消息，不后台发送。
   continue   输出继续某个 lane 宿主会话的人工命令或步骤。
-  launch     为已有 lane 创建并绑定独立宿主会话。
+  launch     旧入口：为 Codex 生成 Launch Message；实际创建由 starworkMultiagent 调用 create_thread。
+  message    生成标准 launch / instruction 消息模板，不写状态。
+  request    记录已由 Skill 或人工完成的跨 lane 请求投递状态。
   share      登记一个跨 lane 可读输出。
 
 示例：
@@ -9555,7 +10032,8 @@ Subcommands:
   starwork multiagent add review --purpose "审校和风险检查" --write "reviews/**,product/docs/**" --target ./my-workspace --yes
   starwork multiagent bind research --session codex:manual-research-1 --session-name "Research Agent" --target ./my-workspace --yes
   starwork multiagent status --host --target ./my-workspace --json
-  starwork multiagent instruct development --from product-planning --message "请根据 SPEC 开始实现。" --target ./my-workspace --yes
+  starwork multiagent message instruct development --from product-planning --message "请根据 SPEC 开始实现。" --target ./my-workspace --json
+  starwork multiagent request record --from product-planning --to development --message "请根据 SPEC 开始实现。" --host-delivery delivered_via_codex_thread_tool --delivery-tool send_message_to_thread --target ./my-workspace --yes
 `);
 }
 
@@ -9608,9 +10086,8 @@ Options:
   --yes, -y
 
 说明：
-  --session-name 会在绑定成功后 best-effort 同步宿主工具的会话名称。
-  --pin 会请求宿主置顶；不支持时只输出 warning，不回滚绑定。
-  instruct 的自动投递由 CLI 运行时判断；没有标准后台投递能力时返回 manual_handoff_required。
+  bind 只记录 StarWork lane binding，不调用 Codex host 工具。
+  --session-name / --pin 需要 starworkMultiagent 先在 Codex App 中调用 set_thread_title / set_thread_pinned，本命令只记录结果。
 `);
 }
 
@@ -9725,6 +10202,80 @@ Options:
   --json
   --dry-run
   --yes, -y
+
+说明：
+  Codex 标准路径下，CLI 不创建 thread、不改名、不置顶。请让 starworkMultiagent 调用 create_thread / set_thread_title / set_thread_pinned，成功后再用 bind 记录 StarWork 状态。
+`);
+}
+
+function printLanesMessageHelp() {
+  console.log(`StarWork Multiagent Message
+
+Usage:
+  starwork multiagent message <launch|instruct> [options]
+
+说明：
+  只生成 STARWORK:MULTIAGENT_MESSAGE 模板，不调用宿主、不写 shared/state。
+`);
+}
+
+function printLanesMessageLaunchHelp() {
+  console.log(`StarWork Multiagent Message Launch
+
+Usage:
+  starwork multiagent message launch <lane-id> [options]
+
+Options:
+  --target <path>
+  --from <lane-id>
+  --session-name <name>
+  --json
+`);
+}
+
+function printLanesMessageInstructHelp() {
+  console.log(`StarWork Multiagent Message Instruct
+
+Usage:
+  starwork multiagent message instruct <to-lane> --from <from-lane> --message <text> [options]
+
+Options:
+  --target <path>
+  --from <lane-id>
+  --message <text>
+  --id <request-id>
+  --json
+`);
+}
+
+function printLanesRequestHelp() {
+  console.log(`StarWork Multiagent Request
+
+Usage:
+  starwork multiagent request record [options]
+
+说明：
+  只记录已发生的跨 lane 请求投递状态，不调用宿主。
+`);
+}
+
+function printLanesRequestRecordHelp() {
+  console.log(`StarWork Multiagent Request Record
+
+Usage:
+  starwork multiagent request record --from <lane> --to <lane> --message <text> --host-delivery <status> --delivery-tool <tool> [options]
+
+Options:
+  --target <path>
+  --from <lane-id>
+  --to <lane-id>
+  --message <text>
+  --host-delivery <delivered_via_codex_thread_tool|recorded_only|manual_handoff_required|failed>
+  --delivery-tool <tool-name>
+  --id <request-id>
+  --json
+  --dry-run
+  --yes, -y
 `);
 }