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

package/README.md

@@ -1,219 +1,165 @@
 # StarWork
 
-StarWork 是一套面向 AI 的工作台协议和工具集，用来帮助用户把长期工作、跨会话协作、多项目管理和 AI 工作流组织清楚。
+StarWork 是给 AI 协作准备的项目工作台。
 
-它包含四个核心部分：
+它帮你把一个普通项目目录整理成 AI 能长期理解和接手的工作环境：项目是什么、现在在做什么、哪些文件能改、重要资料在哪里、上一个 AI 会话交接了什么，都有固定位置可读。
 
-- **Core**：定义工作台应该长什么样，包括目录结构、角色边界、状态文件和健康检查规则。
-- **CLI**：提供 `init`、`doctor`、`knowledge`、`spawn`、`upgrade`、`adapt`、`pack install`、`multiagent` 等命令，用来创建、检查、升级、协作和扩展工作台。
-- **Packs**：场景模板包。当前 A 测阶段默认使用通用工作能力。
-- **Skills**：给 Codex 等 AI 工具使用的工作流说明，让 AI 能更可靠地帮用户设计和生成 StarWork 工作台。
+如果你经常遇到这些情况，StarWork 就是为你准备的：
 
-当前版本处于 A 测阶段。npm `latest` 为 `@jennie-shawn/starwork@0.1.0-alpha.20`，适合测试安装流程、基础命令、工作台结构、AI Skill 使用体验和 MultiAgent 会话协作链路。
+- 每次打开 AI，都要重新解释项目背景。
+- 换一个 AI 会话后，上下文又断了。
+- 项目资料、草稿、最终版本混在一起，AI 也分不清。
+- 想让多个 AI 分工协作，但不知道谁负责什么。
+- 项目做久了，重要判断、经验和交接记录散落在聊天里。
 
-## 安装 CLI
+StarWork 做的事情很简单：把项目变成一个 AI 看得懂、你也放心的工作台。
 
-全局安装：
+## StarWork 能帮你做什么
 
-```bash
-npm install -g @jennie-shawn/starwork
-starwork --version
-starwork --help
-```
+### 让 AI 先读懂项目
 
-不全局安装，直接运行：
+StarWork 会给项目补上清晰的项目说明、当前任务、协作规则和健康检查入口。AI 进入项目时，不需要从零猜上下文。
 
-```bash
-npx @jennie-shawn/starwork --version
-npx @jennie-shawn/starwork --help
-```
+### 保护你的项目文件
 
-## 安装 Skills
+第一次接入项目时，StarWork 会先预览将要写入的协作文件，不会直接改业务代码，也不会直接覆盖已有 AI 规则文件。
 
-StarWork skills 分两类管理：
+### 留住长期知识
 
-- 系统 Skill 通过 GitHub 仓库和 `skills` CLI 安装到 AI 工具的全局环境。
-- 工作台自带 Skill 跟着工作台走，例如项目中心自带 `starworkSpawn`，项目工作台自带 `neat-freak`。
+你可以开启项目知识库，把客户背景、产品规则、术语解释、长期策略和复盘结论沉淀下来。原始资料仍放在资料区，临时草稿仍放在草稿区。
 
-给 Codex 安装全部 StarWork 系统级 Skills：
+### 支持多个 AI 分工
 
-```bash
-npx skills add jennie-shawn/StarWork -g -a codex -y
-```
+你可以给一个项目创建产品规划、开发、验收、资料整理等不同 Agent。StarWork 会记录每个 Agent 的职责、可写范围、共享输出和交接状态。
 
-上面这条命令只安装 StarWork 系统级 Skills。当前默认面向 Codex；如果你使用其他 AI 工具，把 `-a codex` 换成对应名称。
+### 管理多个项目
 
-当前系统级 Skills：
+如果你有很多项目，可以建立一个项目中心，再从项目中心创建新的项目工作台，统一登记和巡检。
 
-- `starworkInit`：帮助 AI 判断是创建项目工作台还是项目中心，选择语言；用户确认创建时，会带着 `starwork init` dry-run、执行并用 `doctor` 验证。
-- `starworkDoctor`：帮助 AI 基于 `starwork doctor --json` 解释目录问题、识别旧模板或类似项目中心的旧工作区；用户明确要求升级时，生成可预览、可确认的升级方案。
-- `starworkMultiagent`：帮助 AI 把“登记当前会话为常用智能体”“管理多 AI 分工”“跨会话指令”“读取其他 lane 状态”等请求转换成 `starwork multiagent` 命令组合。
-- `starworkKnowledge`：帮助 AI 开启和维护项目本地知识库；创建结构时先调用 `starwork knowledge`，整理内容时区分主题页和综合判断。
+## 它不是什么
 
-说明：`starworkKnowledge` 是全局入口 Skill。项目开启知识库后，CLI 会把 `starworkKnowledgeProject` 安装到当前项目的 `.agents/skills/` 和 `.claude/skills/`，它不属于全局安装清单。
+StarWork 不是另一个笔记软件，也不是自动替你写完整项目的黑盒。
 
-Kit 随附 Skills 不走全局安装命令，它们跟着具体工作台走：
+它更像一套项目协作底座：帮 AI 找到正确上下文，帮你保留规则、边界、任务、知识和交接记录。
 
-- `starworkSpawn`：项目中心自带 Skill，帮助已有项目中心设计 `starwork spawn --blueprint` 工作台定制单。
-- `starworkAudit`：项目中心自带 Skill，帮助项目中心解读 `starwork audit --json`，判断它管理的项目工作台健康状况，并生成保守的 `starwork repair --blueprint` 修复蓝图。
-- `neat-freak`：项目工作台自带 Skill，帮助项目收尾、整理和归档。
+## 第一次使用
 
-## 让 Agent 帮你安装
+最推荐的方式：让你的 AI 助手带你完成。
 
-如果你希望让 AI 帮你完成安装，可以把下面这段提示词发给 Codex、Claude Code 或其他能操作终端的 AI：
+把下面这段话发给 Codex、Claude Code、Cursor 或你正在使用的 AI 工具：
 
 ```text
-请帮我安装并验证 StarWork。
+请用 `starwork` 主入口帮我开始使用 StarWork。
+
+请先阅读 StarWork 引导文档，理解 StarWork 是什么：
+https://raw.githubusercontent.com/jennie-shawn/StarWork/main/README.md
 
-请先阅读 StarWork 的 Agent 安装指南，再按文档执行：
+如果本机还没有安装 StarWork CLI 或 Skills，请先按这份 Agent 安装指南完成安装：
 https://raw.githubusercontent.com/jennie-shawn/StarWork/main/docs/agent-install-guide.md
 
-请先只完成 CLI 和 Skills 的安装验证，不要默认创建工作区。安装完成后，先询问我是否需要继续创建或测试 StarWork 工作区；如果需要，再进入 starworkInit 流程。
+请先说明 StarWork 是什么、能帮我做什么、接下来我应该走哪个能力。
+然后先预览将要写入的文件，不要直接写入。
+等我确认后，再正式初始化并运行健康检查。
 ```
 
-更完整的 Agent 操作流程见 [Agent 安装指南](docs/agent-install-guide.md)。
-
-## 快速开始
-
-创建一个项目工作台：
+如果你想自己在终端试用，也可以先用 `npx` 预览，不需要全局安装：
 
 ```bash
-starwork init \
+npx @jennie-shawn/starwork init \
   --type project \
   --pack general \
   --language zh \
-  --name "StarWork A Test" \
-  --target ~/Desktop/starwork-a-test \
-  --yes
+  --target ~/Desktop/my-starwork-project \
+  --dry-run
 ```
 
-检查工作台：
+确认预览没问题后再写入：
 
 ```bash
-starwork doctor --target ~/Desktop/starwork-a-test
+npx @jennie-shawn/starwork init \
+  --type project \
+  --pack general \
+  --language zh \
+  --target ~/Desktop/my-starwork-project \
+  --yes
 ```
 
-可选：给项目开启知识库：
+最后检查工作台：
 
 ```bash
-starwork knowledge init --target ~/Desktop/starwork-a-test --dry-run
-starwork knowledge init --target ~/Desktop/starwork-a-test --yes
-starwork knowledge status --target ~/Desktop/starwork-a-test --json
+npx @jennie-shawn/starwork doctor --target ~/Desktop/my-starwork-project
 ```
 
-创建一个项目中心：
+## 三种常见用法
 
-```bash
-starwork init \
-  --type hub \
-  --language zh \
-  --name "StarWork Project Center A Test" \
-  --target ~/Desktop/starwork-hub-a-test \
-  --yes
-```
+### 我只是想试试
 
-从项目中心创建一个项目工作台：
+创建一个新的空项目工作台。StarWork 会生成一套推荐结构，你可以安全体验。
 
-```bash
-starwork spawn \
-  --hub ~/Desktop/starwork-hub-a-test \
-  --name "Alpha Project" \
-  --target ~/Desktop/starwork-alpha-project \
-  --language zh \
-  --yes
-```
+### 我已经有一个真实项目
 
-检查生成的项目：
+把现有项目接入 StarWork。它会保留已有文件，先预览要补充的协作结构；如果项目里已经有 AI 规则文件，会先生成待整合草稿，不直接覆盖。
 
-```bash
-starwork doctor --target ~/Desktop/starwork-alpha-project
-```
+### 我有很多项目
 
-从项目中心巡检项目：
+创建项目中心。项目中心用来登记多个项目，再为每个项目创建自己的工作台。
 
-```bash
-starwork audit --hub ~/Desktop/starwork-hub-a-test
-```
+## 你还可以开启的功能
 
-## CLI 能力
+StarWork 的基础能力是“让 AI 读懂并安全接手项目”。在此基础上，你可以按需要开启更多功能。
 
-```text
-starwork init
-starwork doctor
-starwork knowledge
-starwork spawn
-starwork upgrade
-starwork adapt
-starwork pack install
-starwork multiagent
-```
+### 项目知识库
 
-## 产品规划资料
+适合资料多、规则多、需要长期复用背景的项目。你可以把客户信息、产品规则、术语解释、复盘结论和长期判断沉淀到项目知识库里，让后续 AI 不再只依赖聊天记录。
 
-StarWork 的功能规划、版本 SPEC、讨论沉淀、参考资料和验收材料统一放在：
+### 多智能体分工
 
-```text
-product/planning/
-```
+适合一个项目里有多类工作要同时推进的情况。你可以把产品规划、开发、验收、资料整理等职责分给不同 Agent，StarWork 会记录每个 Agent 负责什么、能改哪里、要交接什么。
 
-其中独立功能按功能点归档：
+### 项目中心
 
-```text
-product/planning/features/<feature>/
-```
+适合同时管理多个项目的用户。项目中心可以登记多个项目工作台，帮助你从一个入口创建、查看和巡检不同项目。
 
-正式用户文档和 HTML 阅读稿仍放在 `product/docs/`。
+### 旧项目诊断
 
-当前能力：
+适合已经有很多历史文件、AI 规则或旧模板的目录。StarWork 可以先诊断目录状态，再给出保守的接入或升级建议。
 
-- `init`：创建项目工作台或项目中心；交互默认推荐项目工作台。
-- `doctor`：检查工作台是否完整、关键文件是否还在；也会为旧模板和类似项目中心的旧工作区列出目录线索，交给 `starworkDoctor` 判断。
-- `knowledge`：开启、检查和按确认方案整理项目本地知识库；成功开启后安装项目内知识库助手，默认不会移动旧 `知识/` 或 `knowledge/`。
-- `spawn`：从已有项目中心创建并登记项目工作台，支持中文或英文目录镜像。
-- `upgrade`：按 `starworkDoctor` skill 生成的升级蓝图，把历史模板或类似项目中心的旧工作区安全接入 StarWork 工作台。
-- `adapt`：生成 Claude Code、Cursor 等 AI 工具的适配文件；Cursor 仅支持只读 transcript 摘要，Trae 仅支持人工操作入口。
-- `pack install`：向兼容工作台安装支持的场景能力。
-- `multiagent`：为同一项目建立自定义 AI 职责位、绑定会话、登记跨 lane 共享输出，并支持会话观察、launch 和格式化跨会话指令；`instruct` 由 CLI 运行时判断宿主能力，不能标准投递时返回 `manual_handoff_required`。Cursor 绑定只用于 `read/status --host` 的只读摘要，Trae 绑定会转人工或 unsupported。
+## 给 AI 工具安装 StarWork Skills
 
-## 仓库结构
+如果你希望 AI 更懂 StarWork 的使用流程，可以安装 StarWork Skills。安装后，普通请求先交给 `starwork` 主入口；明确的知识库、多智能体、诊断或初始化场景，也可以直接点名对应专家能力。
 
-```text
-.
-├── core/       # StarWork Core 协议、Kit、Profile、Preset
-├── cli/        # CLI 实现和命令规格
-├── packs/      # 场景 Pack
-├── skills/     # 系统级 AI skills
-├── kit-skills/ # Kit 自带 AI skills
-├── schemas/    # 结构化 schema
-├── adapters/   # AI 工具适配规则
-├── examples/   # 示例
-├── docs/       # 产品文档和 A 测指南
-└── planning/   # 功能规划、版本 SPEC、讨论、参考和验收
+当前默认面向 Codex：
+
+```bash
+npx skills add jennie-shawn/StarWork -g -a codex -y
 ```
 
-## A 测反馈重点
+安装后，AI 会拥有一个 StarWork 主入口和几个专家 Skills，可以更自然地帮你：
 
-请优先反馈：
+- 判断你现在应该走哪个 StarWork 能力。
+- 创建或接入项目工作台。
+- 诊断旧目录能否升级为 StarWork 工作台。
+- 开启和维护项目知识库。
+- 创建多个 Agent 分工协作。
 
-- CLI 是否能顺利安装和运行。
-- `init` 创建的工作台结构是否容易理解。
-- `doctor` 的检查结果是否能指导修复问题。
-- 项目中心创建和管理项目工作台的流程是否自然。
-- 系统 Skill 是否能被 AI 正确识别和调用。
-- 项目中心自带的 `starworkSpawn`、项目工作台自带的 `neat-freak` 是否能在对应工作台内被正确发现。
+更完整的安装说明见 [Agent 安装指南](docs/agent-install-guide.md)。
 
-更完整的测试脚本见 [A 测安装指南](docs/alpha-test-guide.md)。
+## 当前状态
 
-## 开发
+StarWork 目前处于 alpha 测试阶段，适合愿意尝鲜、愿意反馈体验问题的用户。
 
-运行测试：
+当前版本重点关注：
 
-```bash
-npm test
-```
+- 第一次初始化是否容易理解。
+- 预览和写入是否让人放心。
+- AI 是否能正确读取项目规则。
+- 知识库和多 Agent 分工是否真的减少重复解释。
+- 项目中心是否适合管理多个项目。
 
-预览 npm 包内容：
+如果你正在试用，欢迎重点反馈：哪里看不懂、哪里不放心、哪里不像一个普通用户会说的话。
 
-```bash
-npm pack --dry-run
-```
+## 继续了解
+
+- [A 测安装指南](docs/alpha-test-guide.md)
+- [Agent 安装指南](docs/agent-install-guide.md)
+- [CLI 与 Skill 能力表](docs/cli-skill-registry.html)