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

package/docs/multiagent-skill-friendly-onboarding-requirements.md

@@ -0,0 +1,354 @@
+# StarWork MultiAgent Skill 友好引导改进建议
+
+本文件面向产品设计和 Skill 后续改写，不是给终端用户阅读的安装说明。
+
+目标：让 `starworkMultiagent` 在真实用户使用时更像一个耐心的协作顾问，而不是一个把内部流程和命令直接暴露给用户的工程助手。
+
+## 当前主要问题
+
+`starworkMultiagent` 当前边界和安全规则已经比较完整，但交互体验仍偏工程化：
+
+- 第一屏仍然用了较多内部词，例如 `lane`、`write_scope`、`binding`、`thread`、`CLI`。
+- 执行步骤说明偏“我要调用什么工具”，不是“这一步对你有什么帮助”。
+- 对小白用户缺少“我会先检查、再设计、再预览、最后执行”的稳定承诺。
+- 当项目还没准备好时，容易让用户感觉“又跳到另一个流程”，而不是被顺滑带到安全接入。
+- 自动创建失败或需要人工交接时，容易显得像失败，而不是清楚解释为“当前工具能力不同，我帮你准备好可复制交接消息”。
+- 成功汇报需要更明确地区分“协作记录已建立”“消息已送达”“目标任务已完成”三件事。
+
+## 建议的用户语言原则
+
+对用户尽量使用这些词：
+
+| 内部词 | 面向用户的说法 |
+|---|---|
+| lane | AI 岗位 / 职责位 |
+| session / thread | 当前 AI 会话 |
+| write_scope | 允许整理或修改的范围 |
+| binding | 把这个会话登记到某个岗位 |
+| shared output | 共享给其他 AI 的成果 |
+| handoff | 交接消息 |
+| CLI | StarWork 命令工具 |
+| host / adapter | 你正在使用的 AI 工具 |
+| dry-run | 先预览，不真正写入 |
+
+除非用户主动追问，默认不要解释内部名词。
+
+## 推荐第一屏
+
+当用户说“帮我创建多个 Agent”“开启 MultiAgent”“创建 AI 团队”时，Skill 应先输出：
+
+```text
+可以。我会先帮你把这个项目拆成几个清楚的 AI 岗位。
+
+每个岗位会有三件事：
+1. 它负责什么；
+2. 它可以整理或修改哪些内容；
+3. 它完成后要怎么交接。
+
+我会按这个顺序来：
+1. 先检查当前项目是否准备好；
+2. 再给你设计岗位方案；
+3. 先预览要写入的协作记录；
+4. 等你确认后再正式创建。
+
+安装和检查阶段不会改你的项目文件。
+```
+
+这比直接说 `doctor -> init -> add -> bind` 更适合小白。
+
+## 推荐总流程
+
+Skill 应把整个流程解释成 4 步：
+
+### 1. 检查项目是否准备好
+
+用户可见说明：
+
+```text
+我先看看这个目录是不是已经可以让 StarWork 接手。这个检查只读取信息，不会改文件。
+```
+
+内部可执行：
+
+```bash
+starwork doctor --target <path> --json
+```
+
+### 2. 设计 AI 岗位
+
+用户可见说明：
+
+```text
+我会根据你的项目目标，建议 3 到 5 个岗位。每个岗位只负责一类事情，这样不会互相抢工作。
+```
+
+需要追问的信息：
+
+- 这个项目要完成什么？
+- 你希望 AI 帮你做哪些类型的工作？
+- 有没有哪些文件或内容不希望 AI 主动修改？
+
+不要一开始问：
+
+- lane id 是什么？
+- write_scope 怎么填？
+- session id 是什么？
+
+这些由 AI 根据用户回答翻译。
+
+### 3. 预览协作记录
+
+用户可见说明：
+
+```text
+我会先展示准备创建的岗位和边界。你确认后，我才会写入项目。
+```
+
+预览内容建议用表格：
+
+| AI 岗位 | 负责什么 | 可以整理的范围 | 交接方式 |
+|---|---|---|---|
+| 调研助手 | 整理资料和用户痛点 | 调研笔记、资料区 | 共享调研摘要 |
+| 写作助手 | 写初稿和改表达 | 草稿、文档区 | 提交草稿给检查助手 |
+| 检查助手 | 检查事实和风险 | 检查记录 | 给出修改建议 |
+
+然后再展示一句：
+
+```text
+如果这个方案没问题，我再创建这些协作记录。
+```
+
+### 4. 创建并汇报结果
+
+成功后不要只说“创建完成”。建议说：
+
+```text
+已经创建好了。
+
+现在这个项目里有 3 个 AI 岗位：
+1. 调研助手：负责资料和用户痛点；
+2. 写作助手：负责草稿和表达；
+3. 检查助手：负责事实、风险和清晰度。
+
+下一步你可以直接说：
+“请让调研助手先整理这个主题的用户痛点。”
+```
+
+如果只创建了岗位但没有创建独立会话，要说清楚：
+
+```text
+我已经先把岗位方案记录好了，但还没有为每个岗位创建独立 AI 会话。
+
+你可以选择：
+1. 现在继续创建独立会话；
+2. 先只保留岗位方案，等需要时再绑定具体会话。
+```
+
+## 推荐追问方式
+
+Skill 当前容易向用户索要内部字段。建议改成自然问题。
+
+### 创建团队时
+
+不要问：
+
+```text
+请输入 lane id、purpose、write_scope。
+```
+
+改成：
+
+```text
+这个项目主要想完成什么？
+你希望哪些事情交给不同 AI 分开做？
+有没有哪些文件或内容不希望 AI 主动修改？
+```
+
+AI 再把回答翻译成内部结构。
+
+### 绑定当前会话时
+
+不要问：
+
+```text
+请提供 codex:<thread-id>。
+```
+
+先说：
+
+```text
+我可以把当前这个 AI 会话登记成一个长期岗位。以后你就可以说“让写作助手继续处理”，而不是从头解释。
+```
+
+如果确实拿不到当前会话 ID，再说：
+
+```text
+我现在无法自动识别这个会话，需要你提供当前 AI 工具里的会话标识。找不到也没关系，我们可以先创建岗位，稍后再绑定。
+```
+
+### 跨岗位交接时
+
+不要说：
+
+```text
+send_message_to_thread 不可用，manual_handoff_required。
+```
+
+改成：
+
+```text
+当前这个 AI 工具不能自动把消息送到另一个会话。
+我已经帮你准备好一段交接消息，你复制给目标 AI 会话即可。
+```
+
+## 可选示例话术，不做内置模板
+
+Skill 不需要内置固定场景模板，也不应把内容创作、课程制作、产品开发等预设成默认选择。
+
+更合适的方式是：当用户不知道怎么分工时，AI 用少量示例帮助用户理解“可以怎样拆”，然后根据用户当前项目现场生成方案。示例只用于启发，不作为内置模板或固定流程。
+
+### 内容创作
+
+- 选题调研助手
+- 初稿写作助手
+- 审稿检查助手
+- 发布整理助手
+
+### 课程制作
+
+- 课程策划助手
+- 案例整理助手
+- 讲稿写作助手
+- 学员视角检查助手
+
+### 产品开发
+
+- 产品规划助手
+- 开发实现助手
+- 验收检查助手
+- 发布说明助手
+
+### 资料整理
+
+- 收集助手
+- 分类整理助手
+- 总结沉淀助手
+- 复查助手
+
+推荐表达：
+
+```text
+如果你还没想好怎么分工，我可以先举几个常见例子帮你找感觉。
+这些只是参考，我会根据你当前这个项目重新设计，不会直接套模板。
+```
+
+## 安全感设计
+
+每次写入前，Skill 都应明确：
+
+```text
+下面是预览，还不会真正写入。
+```
+
+每次写入后，Skill 都应说明：
+
+```text
+这次只写入了协作记录，没有改你的业务内容。
+```
+
+如果确实要修改项目正式文件，必须先说明：
+
+```text
+这一步会修改以下文件：
+- ...
+
+修改目的：
+- ...
+
+确认后我再继续。
+```
+
+## 状态汇报口径
+
+需要严格区分三种状态：
+
+| 状态 | 可以怎么说 | 不能怎么说 |
+|---|---|---|
+| 岗位已创建 | 已经创建了 AI 岗位 | Agent 已经开始工作 |
+| 会话已绑定 | 这个岗位已经有对应 AI 会话 | 任务已经完成 |
+| 消息已送达 | 交接消息已发送给目标会话 | 目标会话已经完成任务 |
+
+推荐成功汇报：
+
+```text
+交接消息已经发送给写作助手，并且已记录在项目协作记录里。
+这表示消息送达了，不表示写作助手已经完成任务。
+我可以接着帮你查看它的进展。
+```
+
+## 失败和降级口径
+
+不要把能力差异说成失败。推荐说：
+
+```text
+当前 AI 工具暂时不能自动完成这一步。
+我会换成更稳妥的方式：生成一段交接消息，让你复制给目标会话。
+这样项目记录仍然清楚，也不会误以为任务已经自动完成。
+```
+
+对于无法确认项目是否准备好：
+
+```text
+我还不能确认这个目录已经适合开启多 AI 分工。
+为了避免写错位置，我建议先完成项目接入检查。这个过程会先预览，不会直接改文件。
+```
+
+## 安装后的第一次使用引导
+
+当用户第一次安装后说“怎么用”时，不要展示命令，直接给提示词：
+
+```text
+你可以这样开始：
+
+“请帮我看看当前项目适不适合开启多 AI 分工。
+先不要写入，只帮我设计 3 个岗位，并说明每个岗位负责什么、可以整理哪些内容、怎么交接。”
+```
+
+如果用户说“我不会设计岗位”，给少量示例，不要进入内置模板选择器：
+
+```text
+没关系，我可以先按你的项目类型给一个初版。
+你告诉我这是内容创作、课程制作、产品开发，还是资料整理项目？
+```
+
+## 建议的 Skill 结构调整
+
+建议后续把 `starworkMultiagent/SKILL.md` 拆成更清晰的用户交互段落：
+
+1. 第一屏解释：用户看得懂的 MultiAgent 说明。
+2. 诊断阶段：只读检查和安全承诺。
+3. 方案阶段：自然语言采访和岗位示例。
+4. 预览阶段：用表格展示岗位、职责、范围、交接。
+5. 执行阶段：隐藏内部命令，只汇报用户关心的结果。
+6. 降级阶段：把自动不可用解释成人工交接，不说内部错误码。
+7. 完成阶段：给用户下一条可复制指令。
+
+## 可交给产品继续细化的问题
+
+- 第一次使用时，是否固定推荐 3 个岗位，而不是 3 到 5 个？
+- 是否需要提供项目类型示例话术，并明确“不直接套模板”？
+- 是否需要为 Codex、Claude Code、Cursor、Trae 分别设计不同的用户可见文案？
+- 是否需要设置默认安全模式：所有写入都先预览，除非用户明确关闭？
+- 是否需要把“AI 岗位”作为对外统一术语，替代所有 `lane` 露出？
+- 是否需要设计一套完成后固定回报卡片，例如“已创建 / 未完成 / 下一步”？
+
+## 最小改版验收标准
+
+后续改完 Skill 后，用这些场景验收：
+
+1. 用户说“帮我创建一个 AI 团队”，AI 第一屏不出现 `lane`、`write_scope`、`binding`。
+2. 用户没有说项目类型时，AI 会先问项目目标，而不是直接创建默认职责。
+3. 用户担心改文件时，AI 能明确说明“先预览，不写入”。
+4. 当前目录不是 StarWork 工作台时，AI 能自然切到安全接入，而不是抛出内部错误。
+5. 自动会话工具不可用时，AI 能给出人工交接消息，并解释这不是任务完成。
+6. 创建成功后，AI 给出下一条用户可以直接复制的使用提示词。

package/docs/multiagent-user-guide.md

@@ -0,0 +1,249 @@
+# StarWork MultiAgent 用户使用说明
+
+StarWork MultiAgent 可以帮你把多个 AI 会话变成一个有分工的小团队。
+
+它不是让 AI 自动乱跑，也不是一键替你完成所有工作。它做的是一件更踏实的事：让每个 AI 知道自己负责什么、能整理哪些内容、产出放在哪里、需要怎么交接。
+
+## 适合什么人
+
+如果你遇到过这些情况，就适合试试：
+
+- 一个项目开了好几个 AI 会话，后来分不清谁在做什么。
+- 调研、写作、修改、检查都混在一个聊天里，越聊越乱。
+- 换一个 AI 会话后，又要重新解释项目背景。
+- 想让一个 AI 负责调研，一个 AI 负责写作，一个 AI 负责检查，但不知道怎么安排。
+- 担心 AI 随便改项目文件，想先给它们划清楚边界。
+
+## 它能帮你做什么
+
+你可以把一个项目拆成几个 AI 岗位，例如：
+
+- 调研助手：帮你整理资料、提炼观点、找用户痛点。
+- 写作助手：帮你写文章、课程大纲、发布文案。
+- 检查助手：帮你检查事实、风险、表达是否夸大。
+- 开发助手：帮你处理代码或产品实现。
+- 发布助手：帮你整理对外说明、更新日志和传播素材。
+
+每个岗位都会有自己的职责说明和工作记录。这样你下次回来时，不需要从聊天记录里翻半天。
+
+## 先请 AI 帮你安装
+
+你不需要自己研究命令。把下面这段话复制给你正在使用的 AI：
+
+```text
+请帮我安装 StarWork MultiAgent。
+
+请先读取这份面向 AI 的安装说明：
+https://raw.githubusercontent.com/jennie-shawn/StarWork/main/docs/multiagent-ai-install-playbook.md
+
+请用非常友好的方式带我完成安装。
+安装阶段不要初始化项目，不要创建测试工作台，不要改动我的项目文件。
+如果我的电脑缺少必要环境，或者需要做会影响全局环境的操作，请先告诉我原因，并等我确认后再继续。
+
+安装完成后，请只告诉我：
+1. 是否安装成功；
+2. 是否需要我新开一个 AI 会话；
+3. 下一步我应该复制哪段提示词来开始使用。
+```
+
+如果 AI 无法打开链接，也可以让它先打开 StarWork 仓库里的：
+
+```text
+docs/multiagent-ai-install-playbook.md
+```
+
+## 安装完成后，第一句话怎么说
+
+安装完成后，新开一个 AI 会话，然后复制：
+
+```text
+请使用 StarWork MultiAgent 帮我看看当前项目是否适合开启多 AI 分工。
+
+请先只做检查和方案设计，不要直接写入。
+如果当前目录还没有准备好，请先引导我完成安全接入。
+如果已经准备好，请帮我设计 3 到 5 个适合这个项目的 AI 岗位，并说明每个岗位负责什么、可以整理哪些文件、需要如何交接。
+所有写入动作都请先预览，等我确认后再执行。
+```
+
+这句话的重点是：先检查、先设计、先预览，不要直接改文件。
+
+## AI 接下来应该怎么带你走
+
+正常情况下，它不会先让你填写内部字段，也不会直接把命令甩给你。
+
+它应该先说清楚：会把项目拆成几个 AI 岗位，每个岗位分别说明负责什么、可以整理或修改哪些内容、完成后怎么交接。
+
+然后它会按这个顺序来：
+
+1. 先检查当前项目是否准备好，这一步只读取信息；
+2. 再根据你的项目目标设计岗位方案；
+3. 用表格预览每个岗位的职责、范围和交接方式；
+4. 等你确认后再创建协作记录。
+
+如果你看到“下面是预览，还不会真正写入”，表示它还没有改文件。正式写入后，它也应该说明“这次只写入了协作记录，没有改你的业务内容”。
+
+## 使用场景 1：做一组自媒体内容
+
+你可以对 AI 说：
+
+```text
+请帮我为这个自媒体选题项目设计一个 AI 小团队。
+
+我希望至少有：
+- 一个负责找选题和资料；
+- 一个负责写初稿；
+- 一个负责检查表达是否夸大、事实是否可靠；
+- 一个负责整理发布文案。
+
+请先给我方案，不要直接写入。每个 AI 岗位都请用普通人能懂的话说明职责。
+```
+
+适合用来做：
+
+- 公众号文章
+- 小红书笔记
+- 视频脚本
+- 课程宣传内容
+- 直播大纲
+
+## 使用场景 2：做一门课程
+
+你可以说：
+
+```text
+请帮我为这门课程创建一个多 AI 协作方案。
+
+我希望有：
+- 课程策划助手：负责课程结构和学习路径；
+- 案例整理助手：负责收集案例和用户问题；
+- 讲稿助手：负责写课程脚本；
+- 审稿助手：负责检查内容是否清楚、是否过度承诺。
+
+请先说明每个助手负责什么，以及它们之间如何交接。
+不要直接写入，先让我确认。
+```
+
+## 使用场景 3：做产品发布
+
+你可以说：
+
+```text
+请帮我为这个产品发布项目设计一个 AI 团队。
+
+我需要：
+- 产品说明助手：负责把产品能力讲清楚；
+- 用户视角助手：负责检查小白用户能不能看懂；
+- 发布材料助手：负责整理 README、安装说明和对外文案；
+- 风险检查助手：负责检查有没有夸大、遗漏或不安全的表达。
+
+请先给出分工方案和下一步执行步骤。
+```
+
+## 使用场景 4：已有项目想整理清楚
+
+你可以说：
+
+```text
+这个项目已经做了一段时间，文件和聊天记录都有点乱。
+
+请先帮我检查当前项目是否适合开启 StarWork MultiAgent。
+不要直接改文件。
+如果适合，请建议我应该设置哪些 AI 岗位。
+如果不适合，请告诉我需要先做哪些准备。
+```
+
+## 使用场景 5：把一个 AI 的结果交给另一个 AI
+
+MultiAgent 不只是创建 AI 小团队，也可以帮你在不同 AI 会话之间交接工作。
+
+比如，调研助手已经整理了一份用户痛点，你想交给写作助手继续写成文章，可以说：
+
+```text
+请把调研助手刚整理的用户痛点交给写作助手。
+
+请帮我准备清楚的交接内容：
+- 调研助手已经完成了什么；
+- 写作助手接下来要做什么；
+- 写作时需要注意哪些边界；
+- 完成后应该如何回报。
+
+如果当前 AI 工具不能自动发送给写作助手，请帮我生成一段可以直接复制过去的交接消息。
+```
+
+如果你想让检查助手审核写作助手的草稿，可以说：
+
+```text
+请把写作助手的草稿交给检查助手。
+
+请让检查助手重点看：
+- 有没有事实不准确；
+- 有没有表达过度承诺；
+- 小白用户能不能看懂；
+- 哪些地方需要重写。
+
+请先告诉我这次交接会包含哪些内容，再继续。
+```
+
+有些 AI 工具可以自动把消息送到另一个会话；有些工具需要你手动复制。无论是哪种情况，AI 都应该把交接内容整理清楚，并告诉你是否已经送达。
+
+## 你可以要求 AI 保持安全
+
+如果你担心 AI 直接改东西，可以每次都加上：
+
+```text
+请先只做方案和预览，不要直接写入。
+任何会修改文件的动作，都先告诉我会改哪里、为什么改、改完有什么效果。
+等我确认后再执行。
+```
+
+这句话很管用。它会让 AI 先解释计划，再动手。
+
+## 使用时你会看到什么
+
+正常情况下，AI 会先做三件事：
+
+1. 看看当前项目是否已经准备好。
+2. 帮你设计几个 AI 岗位。
+3. 告诉你每个岗位负责什么，以及会整理哪些内容。
+
+你确认后，AI 才会正式创建协作记录。
+
+创建完成后，你可以继续说：
+
+```text
+请让调研助手先整理这个主题的用户痛点。
+```
+
+或者：
+
+```text
+请看看写作助手现在做到哪了。
+```
+
+或者：
+
+```text
+请把这份调研结果交给审稿助手检查。
+```
+
+## 它不会做什么
+
+StarWork MultiAgent 不会在安装阶段改你的项目。
+
+它也不会保证所有 AI 软件都能自动创建多个后台会话。不同 AI 工具能力不一样：有的可以自动创建和发送，有的需要你手动复制一段交接消息。遇到这种情况，AI 会把要复制的内容准备好。
+
+这不是失败，而是安全降级。
+
+## 给新手的建议
+
+第一次使用时，不要一上来创建很多岗位。
+
+建议先从 3 个开始：
+
+- 调研
+- 写作
+- 检查
+
+等你熟悉以后，再增加发布、开发、运营、资料整理等岗位。
+
+最重要的是：每个岗位只负责一类事情。这样多 AI 协作才会清楚，不会又变成一团乱麻。