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

package/skills/starworkInit-spec.md

@@ -6,8 +6,8 @@
 - 所属模块：StarWork Skills
 - Skill 名称：`starworkInit`
 - 相关命令：`starwork init`
-- 实现状态：未实现
-- 目标：帮助 Agent 把用户“我想建一个工作台”的模糊需求，整理成可预览、可执行、可解释的 StarWork 初始化方案
+- 实现状态：已实现第一版，M2.6 继续优化采访口径
+- 目标：帮助 Agent 把用户“我想建一个工作台”的模糊需求，整理成可预览、可执行、可解释、并最终落地验证的 StarWork 初始化流程
 
 ## 一句话定义
 
@@ -22,7 +22,7 @@ starworkInit skill 追问和判断
   ↓
 初始化方案 / init blueprint
   ↓
-starwork init 或未来 starwork init --blueprint
+starwork init 或 starwork init --blueprint
   ↓
 可用 StarWork 工作台
 ```
@@ -31,8 +31,7 @@ starwork init 或未来 starwork init --blueprint
 
 `init` 处在用户最早期的入口。此时用户往往还没想清楚：
 
-- 是要单项目，还是多项目中枢
-- 是轻量工作台，还是长期事项型工作台
+- 是要具体项目工作台，还是多项目中枢
 - 使用中文工作台，还是英文工作台
 - 正式成果应该放哪里
 - 当前推进过程应该放哪里
@@ -43,9 +42,9 @@ starwork init 或未来 starwork init --blueprint
 
 所以本 SPEC 的主角是：
 
-> Agent 如何判断、如何追问、如何输出初始化方案。
+> Agent 如何判断、如何追问、如何输出初始化方案，并在用户确认落地时继续执行和验证。
 
-CLI 的 `init --blueprint` 只是未来承接这个方案的执行入口。
+CLI 的 `init --blueprint` 是承接定制方案的执行入口。Skill 不能把 blueprint 文件本身当作最终交付物。
 
 ## 与 `starworkSpawn` 的关系
 
@@ -75,7 +74,7 @@ CLI 的 `init --blueprint` 只是未来承接这个方案的执行入口。
 - “帮我建一个 StarWork 工作台”
 - “我要初始化一个内容创作工作台”
 - “我想建一个多项目管理系统”
-- “我想用 StarWork 管一个长期项目”
+- “我想用 StarWork 管一个项目”
 - “这个工作台的目录我想定制一下”
 - “init 有没有类似 spawn blueprint 的定制能力”
 
@@ -90,19 +89,19 @@ skill 应在这些场景下启动。
 当用户还在讨论阶段，输出一份人能读懂的建议：
 
 ```text
-建议使用：single-matter
-基础 Kit：local-matter
+建议使用：project
+基础结构：Project
 语言：zh
-Pack：general
-正式成果：发布记录/
-当前工作：事项/
-额外目录：账号定位/、选题池/、素材库/
-原因：这是长期内容工作台，需要事项追踪和内容生产闭环。
+场景能力：general
+正式成果：输出/确认成果/
+当前工作：输出/草稿/
+额外目录：按用户需求另行定制
+原因：用户当前只描述了一个明确项目，先用普通项目工作台降低复杂度。
 ```
 
 ### 2. 初始化定制单
 
-当用户要求落地方案时，生成：
+当用户要求定制目录或规则时，先生成：
 
 ```text
 <workspace>-init/
@@ -115,9 +114,11 @@ Pack：general
     └── ...
 ```
 
+生成定制单不是结束。用户的目标是创建工作台时，Agent 必须继续执行 `starwork init --blueprint` 的 dry-run、确认和正式写入。
+
 ### 3. 执行指令
 
-当用户准备测试时，给出命令：
+当用户准备测试或明确要求创建时，执行命令：
 
 ```bash
 starwork init --target <workspace-path> --blueprint <init-blueprint.json> --dry-run
@@ -125,7 +126,7 @@ starwork init --target <workspace-path> --blueprint <init-blueprint.json> --yes
 starwork doctor --target <workspace-path>
 ```
 
-注意：当前 CLI 尚未实现 `init --blueprint`，因此在实现前应说明这是目标命令形态；当前可执行路径仍是普通 `starwork init` 加后续手工调整或未来 CLI 实现。
+注意：定制初始化必须先 dry-run。只有 dry-run 结果里的绝对目标路径、文件夹名和目录计划都被用户确认后，才执行 `--yes`。如果 dry-run 显示会创建用户明确不要的目录，应回到 blueprint 修正，不要强行执行。
 
 ## 交互流程
 
@@ -138,23 +139,19 @@ starwork doctor --target <workspace-path>
 ```text
 Step 1 判断工作台类型
   ├─ hub：继续判断语言，然后直接进入 Hub 初始化建议
-  └─ single：继续判断语言和事项
+  └─ project：继续判断语言和是否需要定制目录
 
 Step 2 判断语言
   ├─ 中文：language=zh
   └─ English：language=en
 
-Step 3 判断是否需要事项
-  ├─ 需要：single-matter
-  └─ 不需要：single-light
-
-Step 4 判断是否需要定制工作台
+Step 3 判断是否需要定制工作台
   ├─ 不需要：输出标准初始化建议
-  └─ 需要：进入 Step 5-7 的友好采访
+  └─ 需要：进入 Step 4-6 的友好采访
 
-Step 5 采访正式成果放哪里
-Step 6 采访日常工作在哪里发生
-Step 7 采访额外固定区域和 Agent 规则
+Step 4 采访正式成果放哪里
+Step 5 采访日常工作在哪里发生
+Step 6 采访额外固定区域和 Agent 规则
 ```
 
 ### Step 1：判断工作台类型
@@ -169,14 +166,13 @@ Step 7 采访额外固定区域和 Agent 规则
 
 | 用户意图 | 推荐工作区 |
 |---|---|
-| 一个具体项目、资料整理、轻量输出 | `single-light` |
-| 一个长期项目、跨会话推进、需要事项 | `single-matter` |
+| 一个具体项目、一个阶段目标、一次成果交付 | `project` |
 | 管理多个项目、统一身份/教训/知识/skills | `hub` |
 
 如果用户说“以后可能会有很多项目”，但当前只是一个项目，优先建议：
 
 ```text
-先用 single-matter；等多项目需求明确后再建 Hub。
+先用 Project；等多项目需求明确后再建立 Hub。
 ```
 
 除非用户明确要建立多项目中枢。
@@ -197,10 +193,10 @@ Hub 的核心不是一个项目怎么推进，而是统一维护：
 
 ```text
 建议类型：hub
-基础 Kit：hub
+基础结构：Hub
 语言：使用 Step 2 的选择
-Pack：无须选择；Hub 使用中枢管理结构
-事项：不作为 Hub 初始化必选项
+场景能力：无须选择；Hub 使用中枢管理结构
+事项：已封存，不作为 Hub 初始化选项
 下一步：确认 Hub 名称、项目注册区域、是否需要预置 skills/ 和 .incoming/
 ```
 
@@ -222,22 +218,24 @@ Pack：无须选择；Hub 使用中枢管理结构
 
 语言会影响目录名称、模板文字和 Agent 规则表达方式，因此不要跳过。
 
-### Step 3：判断是否需要事项
+### Step 3：判断是否需要定制工作台
 
-仅当 Step 1 判断为 `single-light` 或 `single-matter` 候选时，才进入这一步。
+仅当 Step 1 判断为 `project` 时，才进入这一步。
 
 问：
 
 ```text
-这个工作会不会持续数周以上，或者需要多次接力？
+你想先用标准结构，还是希望我帮你按自己的工作习惯稍微改一下目录和规则？
 ```
 
 判断：
 
-- 需要长期推进、复盘、交接：`single-matter`
-- 只是放资料、写草稿、收成果：`single-light`
+- 不需要、不确定、只有一个明确目标：使用标准 `project`
+- 明确有稳定目录偏好：继续采访正式成果、日常工作区和额外目录
 - 管理多个项目：返回 Step 1，改为 `hub`
 
+不要再询问 matter、长期/短期、多线事项等已封存分类。
+
 ### Pack 选择规则
 
 v0.1 不采访用户选择场景 Pack。
@@ -269,7 +267,7 @@ v0.1 不采访用户选择场景 Pack。
 
 | 用户选择 | 后续动作 |
 |---|---|
-| 标准结构就行 | 输出标准 Kit + Pack 初始化建议 |
+| 标准结构就行 | 输出标准项目结构初始化建议 |
 | 想改一下 | 进入 Step 5-7 |
 | 不确定 | 给 2-3 个具体例子帮用户判断 |
 
@@ -282,7 +280,7 @@ v0.1 不采访用户选择场景 Pack。
 
 v0.1 的定制边界：
 
-- 只支持基于 `general` Pack 做目录和规则定制
+- 只支持基于 `general` 场景能力做目录和规则定制
 - 不支持定制 Hub 的中枢结构
 - 不把单次定制升级成新 Pack
 
@@ -307,7 +305,7 @@ v0.1 的定制边界：
 |---|---|
 | 最终成果、交付物、确认版本 | `输出/确认成果/` 或 `交付物/确认版本/` |
 | 已发布内容、发布记录 | `发布记录/` |
-| 项目清单、项目注册 | `项目/` |
+| 项目清单、项目注册 | Hub 使用 `projects/`；单项目不单独创建项目注册目录 |
 
 如果用户答不上来，可以先给默认建议：
 
@@ -334,16 +332,14 @@ v0.1 的定制边界：
 
 | 工作方式 | business_work_area |
 |---|---|
-| 事项推进 | `事项/` |
 | 轻量资料整理 | `参考资料/` |
-| 内容草稿推进 | `草稿与脚本/` 或 `事项/` |
-| Hub 管理 | `项目/` |
+| 内容草稿推进 | `输出/草稿/` 或用户明确指定的草稿目录 |
+| Hub 管理 | `projects/` |
 
 如果用户说“就是普通项目”，默认：
 
 ```text
-single-light：参考资料/
-single-matter：事项/
+project：输出/草稿/
 ```
 
 ### Step 7：采访额外目录和 Agent 规则
@@ -375,7 +371,7 @@ single-matter：事项/
 
 - 含义重叠的目录
 - 只为好看创建的目录
-- 与 Pack 已有目录重复的目录
+- 与通用结构已有目录重复的目录
 
 至少考虑两类规则：
 
@@ -395,7 +391,7 @@ rules/handoff.md
 
 - 哪类信息放哪里
 - 什么时候写正式成果
-- 什么时候写事项
+- 什么时候写当前工作记录
 - 哪些目录只读
 - 哪些内容需要用户确认
 
@@ -415,7 +411,7 @@ Step 5-7 的采访要避免抽象词，尽量用“你平时怎么做”的语
 例如：
 
 ```text
-我先按“正式成果放在 输出/确认成果/，日常推进放在 事项/”理解。
+我先按“正式成果放在 输出/确认成果/，日常推进放在 输出/草稿/”理解。
 这样草稿和确认版不会混在一起。你看这个分法顺不顺手？
 ```
 
@@ -427,19 +423,43 @@ Step 5-7 的采访要避免抽象词，尽量用“你平时怎么做”的语
 {
   "schema": "starwork.init_blueprint.v0.1",
   "name": "我的项目工作台",
-  "workspace_type": "single-matter",
-  "kit": "local-matter",
+  "workspace_type": "project",
+  "kit": "project",
   "language": "zh",
   "pack": "general",
   "paths": {
-    "formal_source": "输出/确认成果/",
-    "business_work_area": "事项/"
+    "formal_source": "定稿/",
+    "business_work_area": "工作稿/"
   },
+  "directories": [
+    {
+      "path": "资料库/",
+      "purpose": "存放用户提供的原始资料和参考信息",
+      "write_policy": "read_only_by_default"
+    },
+    {
+      "path": "工作稿/",
+      "purpose": "存放 AI 生成的草稿、方案和中间版本",
+      "write_policy": "writable"
+    },
+    {
+      "path": "定稿/",
+      "purpose": "存放用户确认后的最终成果",
+      "write_policy": "confirm_before_write"
+    }
+  ],
   "folders": [
+    "资料库/",
+    "工作稿/",
+    "定稿/",
     "会议纪要/",
     "客户沟通/",
     "版本记录/"
   ],
+  "removals": [
+    "参考资料/",
+    "输出/"
+  ],
   "agent_rules": [
     {
       "slot": "workspace.file_boundaries",
@@ -467,13 +487,14 @@ Step 5-7 的采访要避免抽象词，尽量用“你平时怎么做”的语
 | `schema` | 固定为 `starwork.init_blueprint.v0.1`。 |
 | `name` | 工作台名称。 |
 | `description` | 工作台说明，可写入项目状态。 |
-| `workspace_type` | `single-light`、`single-matter` 或 `hub`。 |
-| `kit` | `local-starter`、`local-matter` 或 `hub`。 |
+| `workspace_type` | `project` 或 `hub`。`single-light` 只作为旧别名兼容，不再主动推荐。 |
+| `kit` | `project` 或 `hub`。 |
 | `language` | `zh` 或 `en`；必须由用户选择，不确定时默认 `zh`。 |
 | `pack` | v0.1 单项目默认 `general`；Hub 不让用户选择 Pack。 |
 | `paths.formal_source` | 正式成果位置。 |
 | `paths.business_work_area` | 当前工作区。 |
 | `folders` | 额外目录。 |
+| `removals` | 用户明确不要的默认目录；只用于跳过本次 init 将创建的默认路径，不删除已有用户文件。 |
 | `agent_rules` | 要注入的规则文件。 |
 | `seed` | 初始化占位文件。 |
 
@@ -510,6 +531,23 @@ Kit 是基础骨架，不服务于单次定制。
 
 Blueprint 可以描述“工作台是什么”，不应该擅自决定“写到机器哪里”。
 
+执行 `--yes` 前，skill 必须复述最终绝对路径和文件夹名，并等待用户确认。AI 可以建议文件夹名，但必须说明它可编辑。
+
+文件夹名建议规则：
+
+- 同一个项目名在同一语言下应得到同一个建议，避免每次会话随机换名。
+- 中文项目可用简短拼音或用户给出的英文名；英文项目使用小写单词和连字符。
+- 建议名只能作为草案。用户改名后，dry-run 和正式执行必须使用用户最终确认的路径。
+- 不要把 StarWork 内部词、Pack 名、Kit 名写进用户文件夹名，除非用户明确要求。
+
+示例：
+
+| 项目名 | 建议文件夹名 |
+| --- | --- |
+| 产品发布计划 | `product-launch-plan` |
+| 2026 客户交付资料整理 | `2026-client-delivery` |
+| Research Notes | `research-notes` |
+
 ## 输出模板
 
 当用户要求“先说方案”时：
@@ -518,9 +556,11 @@ Blueprint 可以描述“工作台是什么”，不应该擅自决定“写到
 ## 初始化建议
 
 - 工作区类型：
-- Kit：
+- 基础结构：
 - 语言：
-- Pack：
+- 场景能力：
+- 目标目录：
+- 文件夹名：
 - 正式成果：
 - 当前工作区：
 - 额外目录：
@@ -532,11 +572,7 @@ Blueprint 可以描述“工作台是什么”，不应该擅自决定“写到
 
 ## 后续执行
 
-当前可用：
-...
-
-未来 blueprint 执行：
-...
+如果用户确认创建，下一步是 dry-run、确认、正式执行和 doctor 检查；不要停在方案。
 ```
 
 当用户要求“生成定制单”时：
@@ -551,28 +587,23 @@ Blueprint 可以描述“工作台是什么”，不应该擅自决定“写到
 
 ## 与 CLI 的关系
 
-`starworkInit` 的第一目标不是运行 CLI，而是生成正确方案。
+`starworkInit` 的第一目标是把用户需求变成正确方案；用户要求创建时，必须继续运行 CLI。
 
-CLI 后续应支持：
+当前 CLI 支持：
 
 ```bash
 starwork init --target <path> --blueprint <init-blueprint.json> --dry-run
 starwork init --target <path> --blueprint <init-blueprint.json> --yes
 ```
 
-但在 CLI 实现前，skill 应该诚实说明：
-
-```text
-当前 CLI 还没有 init --blueprint 执行能力；这份定制单先作为实现依据。
-```
+Agent 必须先执行 dry-run；如果预览里仍出现用户明确不要的默认目录，先修正 `removals` 或 `paths`，不要执行 `--yes`。
 
 ## 待确认问题
 
-1. `starworkInit` 是否需要先落成 skill，再实现 CLI `init --blueprint`？
-2. 是否允许一个 Init Blueprint 安装多个 Pack？
-3. Hub 初始化是否需要专门的 Hub Init Blueprint 子模式？
-4. 是否要把 `init_blueprint` 和 `spawn_blueprint` 抽出共享字段规范？
-5. `starworkInit` 生成的 blueprint 是否应能被后续升级为 Pack preset？
+1. 是否允许一个 Init Blueprint 安装多个 Pack？
+2. Hub 初始化是否需要专门的 Hub Init Blueprint 子模式？
+3. 是否要把 `init_blueprint` 和 `spawn_blueprint` 抽出共享字段规范？
+4. `starworkInit` 生成的 blueprint 是否应能被后续升级为 Pack preset？
 
 ## 结论
 

package/skills/starworkKnowledge/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: starworkKnowledge
+description: 'Create, inspect, and maintain a local StarWork project knowledge base with `starwork knowledge`, focused on long-term stable project knowledge.'
+---
+
+# starworkKnowledge
+
+使用这个 skill，帮助用户开启和维护“项目知识库”。
+
+项目知识库不是资料夹。它用于让 AI 长期整理当前项目里会反复用到的稳定理解。原始资料仍放在参考资料区，草稿和成果仍按工作台规则进入输出区。
+
+## 主入口边界
+
+如果用户只是询问产品总览、起步路径、安装入口或该用哪个 StarWork 能力，回到 `starwork` 主入口。普通资料整理、README 整理和阶段收尾不属于本 skill；只有长期稳定知识沉淀、知识库开启和知识库维护才使用 `starworkKnowledge`。
+
+## 开启知识库的第一屏
+
+当用户说“开启知识库”“初始化知识库”“让 AI 记住项目知识”时，先讲清楚这一步是什么，不要直接抛 CLI 命令：
+
+```text
+项目知识库是让 AI 长期记住项目稳定理解的地方。
+
+它不是原始资料文件夹，也不是草稿区。原始材料仍放在参考资料区，临时想法仍放在草稿区；知识库只沉淀会反复用到、已经比较稳定的判断，比如客户背景、产品规则、术语解释、长期策略和复盘结论。
+
+接下来我会分三步带你开启：
+1. 先检查当前项目是否已经有知识库；
+2. 再预览 StarWork 准备创建哪些知识库文件；
+3. 你确认后再正式开启，并做一次结构检查。
+
+我不会把旧资料整包搬进知识库，也不会在你确认前改动原始资料。
+```
+
+## 边界
+
+```text
+starwork knowledge = 创建和检查知识库结构
+starworkKnowledge skill = 判断、采访、整理、写入知识内容
+starworkKnowledgeProject = 项目开启知识库后安装到当前项目里的维护助手
+```
+
+必须优先使用 CLI：
+
+- 开启知识库：先运行 `starwork knowledge init --dry-run`，用户确认后再运行 `starwork knowledge init --yes`。
+- 查看状态：运行 `starwork knowledge status --json`。
+- 检查结构：运行 `starwork knowledge check`。
+- 涉及旧 `知识/`、`knowledge/` 或定制路径：先生成 `starwork.knowledge` blueprint，再运行 `starwork knowledge apply --blueprint <file> --dry-run`，用户确认后执行。
+
+不要绕过 CLI 手写另一套目录结构。
+
+`starwork knowledge init` 成功后，CLI 会把 `starworkKnowledgeProject` 安装进当前项目。不要让用户把这个项目内业务 Skill 装到全局。
+
+## 宿主适配
+
+知识库开启后，如果当前工作台已经适配了 Codex、Claude Code、Cursor 或 Trae，要确认对应宿主入口也能说明知识库边界。
+
+可运行：
+
+```bash
+starwork doctor --target <path> --host all --json
+```
+
+如果用户明确说“让 Cursor / Trae / Claude Code 也能正确使用知识库”，先用：
+
+```bash
+starwork adapt <host> --target <path> --dry-run
+```
+
+解释会更新哪个入口文件。用户确认后再执行 `--yes`，然后运行 `starwork doctor --host <host>`。
+
+各宿主入口必须让 Agent 明白：
+
+- 知识库是长期理解层。
+- 参考资料是输入材料。
+- 草稿和输出是过程与成果。
+- 宿主 transcript、summary、memory 不是 StarWork 知识库。
+
+Claude Code transcript 可以作为候选资料来源，但必须用户确认后才能吸收。Cursor / Trae 内部历史没有稳定官方导出时，不建议直接吸收。
+
+## 工作流程
+
+### 1. 用户想开启知识库
+
+先确认当前目录：
+
+```bash
+starwork knowledge status --json
+```
+
+如果还没开启，用人话解释：
+
+```text
+知识库是让 AI 长期整理稳定知识的地方，不是放原始资料的文件夹。原始资料仍然留在参考资料区。
+```
+
+然后执行：
+
+```bash
+starwork knowledge init --dry-run
+```
+
+用户确认后：
+
+```bash
+starwork knowledge init --yes
+starwork knowledge check
+```
+
+### 2. 用户给了新资料
+
+先读：
+
+1. `schema.md`
+2. `index.md`
+
+判断资料里是否有长期价值。
+
+- 单个稳定主题：更新或创建 `pages/`。
+- 跨多个主题形成的策略、复盘、方法或判断：更新或创建 `synthesis/`。
+- 重要来源：记录到 `sources/`。
+- 暂时无法归类：放入 `inbox/`，并写清楚为什么待整理。
+
+最后更新 `index.md` 和 `log.md`。
+
+### 3. 用户询问长期知识相关问题
+
+先读 `index.md`，再读相关 `pages/` 和 `synthesis/`。
+
+回答用户后，如果产生了可长期复用的新判断，先告诉用户你建议沉淀到知识库哪里；用户确认后再更新。
+
+### 4. 用户要求策略、复盘或阶段判断
+
+优先写入或更新 `synthesis/`。
+
+`synthesis/` 应连接多个主题页、来源和项目经验。不要把一份原始资料直接改写成 synthesis。
+
+必要时反向更新 `pages/`，再更新 `index.md` 和 `log.md`。
+
+### 5. 用户已有旧知识目录
+
+如果看到旧 `知识/`、`knowledge/`、`资料库/` 或类似目录，不要直接搬迁、改名或删除。
+
+先判断它更像：
+
+- 原始资料区
+- 旧知识草稿
+- 旧版项目知识库
+- 项目中心共享知识链接
+- 普通历史目录
+
+然后和用户确认，再生成 blueprint。blueprint 只能做结构性动作，不能让 CLI 生成知识正文，也不能默认提交到项目中心。
+
+v0.1 blueprint 只使用这些动作：
+
+- `create_knowledge_base`
+- `create_dir`
+- `write_template`
+- `append_agents_rule`
+- `install_project_skill`
+- `copy_preserved_file`
+- `record_workspace_capability`
+
+复制旧文件时必须使用 `copy_preserved_file`，并设置 `confirmed: true`。它只能复制，不能移动原文件。
+
+## `pages/` 和 `synthesis/`
+
+最简单的区别：
+
+```text
+pages/      = 知识卡片
+synthesis/  = 思考成果
+```
+
+`pages/` 适合：
+
+- 用户画像
+- 标题结构
+- 产品模块
+- 客户需求
+- 竞品账号
+
+`synthesis/` 适合：
+
+- 30 天冷启动策略
+- 阶段复盘
+- 增长方法论
+- 定位调整建议
+
+## 禁止事项
+
+- 不把原始资料整包搬进知识库。
+- 不把宿主 transcript、memory、summary 直接当成知识库。
+- 不把临时草稿、命令输出、单次任务过程放进知识库。
+- 不默认提交到项目中心。
+- 不自动移动、删除或改名旧 `知识/` / `knowledge/`。
+- 不写没有来源、没有上下文的空泛总结。

package/skills/starworkKnowledge/agents/openai.yaml

@@ -0,0 +1,3 @@
+name: starworkKnowledge
+description: Help users create and maintain a local StarWork project knowledge base by using `starwork knowledge` CLI commands first.
+entry: SKILL.md