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

package/core/kits/kit-structure-reference.md

@@ -3,251 +3,164 @@
 ## 状态
 
 - 版本：v0.1 draft
-- 日期：2026-05-15
-- 范围：记录当前 `product/core/kits/` 下所有 Kit 的实际结构
-- 用途：作为后续梳理 Kit 边界、目录命名、语言一致性和 CLI 生成逻辑的事实依据
+- 日期：2026-05-25
+- 范围：记录 `product/core/kits/` 下正式 Kit 的目标结构和 `.starwork/` 分层边界
 
-本文件记录当前已确认的 Kit 结构快照。后续如果调整 Kit，必须同步更新本文件。
+## 正式 Kit
 
-## Kit 列表
+v0.1 只保留两类正式 Kit：
 
 | Kit | 定位 |
 |---|---|
-| `local-starter` | 轻量单项目 Kit。 |
-| `local-matter` | 单项目事项型 Kit。 |
-| `hub` | 多项目管理中枢 Kit。 |
-| `satellite-starter` | 轻量卫星项目 Kit，不启用事项。 |
-| `satellite-matter` | 事项型卫星项目 Kit，启用事项。 |
+| `project` | 项目工作台；可独立使用，也可加入项目中心。 |
+| `hub` | 项目中心；维护共享身份、教训、知识、skills、项目注册和联络路由。 |
 
-命名原则：Kit 名称不携带语言标签，只表达工作区形态。当前 `product/core/kits/` 下的结构默认以中文 profile 落地。英文 profile 的参考样例放在 `product/core/profiles/en/reference-kits/`，不进入正式 Kit 列表。
+旧事项分叉不再作为 Kit、Preset 或 CLI 兼容入口保留。历史项目里如果已经有 `事项/` 或 `matters/`，Doctor 只把它暴露为历史内容信号，后续由 AI 判断如何无损整理。
 
-## `local-starter`
+## 分层原则
 
-定位：轻量单项目 Kit。适合单项目、无事项机制、使用参考资料和输出目录的轻量工作区。
+| 层级 | 放什么 | 不放什么 |
+|---|---|---|
+| `.starwork/` | StarWork 机制运行状态、manifest、队列、安装记录、缓存和报告。 | 项目业务事实、草稿、正式成果、项目中心共享资产正文。 |
+| `_系统/` 或 `_system/` | 项目协作事实，例如项目状态、当前工作、身份、教训、决策和协作索引。中心管理的项目可额外包含项目中心同步说明。 | StarWork 机制缓存、投递队列、安装 manifest。 |
+| Pack 业务目录 | 由 Pack 定义的项目输入、草稿、成果或场景流程目录。默认 General Pack 会创建 `参考资料/` / `references/` 与 `输出/` / `outputs/`。 | Core Kit 固定结构、StarWork 机制报告或 CLI 缓存。 |
+| `identity/`、`lessons/`、`knowledge/`、`skills/` | 项目中心共享资产或项目本地上下文资产。 | 机制队列和缓存。 |
+| `.agents/`、`.claude/`、`.obsidian/` | 外部工具入口和配置。 | StarWork 自有机制事实源。 |
+
+## 通用 `.starwork/`
+
+所有由 StarWork CLI 初始化、生成或升级后的工作台推荐包含：
 
 ```text
-.
-├── AGENTS.md
-├── README.md
-├── _系统/
-│   ├── 上下文/
-│   │   └── 项目状态.md
-│   ├── 任务/
-│   │   └── 当前工作.md
-│   ├── 身份/
-│   │   └── README.md
-│   └── 教训/
-│       └── README.md
-├── 参考资料/
-│   └── README.md
-└── 输出/
-    ├── 草稿/
-    │   └── README.md
-    └── 确认成果/
-        └── README.md
+.starwork/
+├── workspace.json
+├── skills.json
+├── packs/
+├── reports/
+└── cache/
 ```
 
-不包含：
+加入项目中心的 Project 额外包含：
 
 ```text
-事项/
-_系统/上下文/决策.md
+.starwork/
+├── handoff/
+├── sync.json
+└── internal/
 ```
 
-## `local-matter`
+其中：
+
+- `handoff/` 是本地跨项目收发队列。
+- `sync.json` 是项目中心同步元数据，替代 legacy `.core-sync.json`。
+- `internal/` 是项目中心内部协议快照，替代 legacy `.internal/`。
 
-定位：单项目事项型 Kit。适合需要长期事项追踪、跨会话接力和过程沉淀的单项目工作区。
+## `project`
+
+中文目标结构：
 
 ```text
 .
 ├── AGENTS.md
 ├── README.md
+├── CLAUDE.md
+├── .starwork/
+├── .obsidian/
+├── .agents/skills/
+├── .claude/skills/
 ├── _系统/
 │   ├── 上下文/
-│   │   ├── 项目状态.md
-│   │   └── 决策.md
+│   │   └── 当前项目.md
 │   ├── 任务/
 │   │   └── 当前工作.md
 │   ├── 身份/
-│   │   └── README.md
 │   └── 教训/
-│       └── README.md
-├── 参考资料/
-│   └── README.md
-├── 输出/
-│   ├── 草稿/
-│   │   └── README.md
-│   └── 确认成果/
-│       └── README.md
-└── 事项/
-    ├── 注册表.md
-    └── _事项模板/
-        ├── README.md
-        ├── 进度.md
-        ├── 笔记.md
-        ├── 交接.md
-        └── 草稿/
-            └── .gitkeep
 ```
 
-## `hub`
-
-定位：多项目管理中枢 Kit。用于建立主库 / 中枢，不直接创建卫星项目。
+英文镜像结构：
 
 ```text
 .
 ├── AGENTS.md
 ├── README.md
-├── .incoming/
-│   └── README.md
-├── _系统/
-│   ├── 上下文/
-│   │   └── 项目状态.md
-│   └── 任务/
-│       └── 当前工作.md
-├── identity/
-│   └── README.md
-├── lessons/
-│   └── README.md
-├── 知识/
-│   └── README.md
-├── skills/
-│   └── README.md
-└── 项目/
-    ├── README.md
-    ├── registry.json
-    └── 联络/
-        └── README.md
+├── CLAUDE.md
+├── .starwork/
+├── .obsidian/
+├── .agents/skills/
+├── .claude/skills/
+├── _system/
+│   ├── context/
+│   │   └── current-project.md
+│   ├── tasks/
+│   │   └── current-work.md
+│   ├── identity/
+│   └── lessons/
 ```
 
-说明：
+Project 不默认创建事项目录。需要多推进线时，先通过 Pack、Skill 或用户自定义目录表达，不再切 Kit。
+
+Project Kit 也不直接拥有 `参考资料/` / `references/` 或 `输出/` / `outputs/`。普通初始化仍会看到这些目录，是因为默认安装的 General Pack 负责创建它们。
+
+Project Kit 也不默认拥有 `知识/` / `knowledge/` / `知识库/` / `knowledge-base/`。需要长期沉淀项目知识时，由 Knowledge Capability 通过 `starwork knowledge init` 另行开启。
 
-- `identity/`、`lessons/` 保留在中枢根目录，因为它们是主库重点维护的项目。
-- `项目/` 使用当前默认中文 profile 的目录名。
-- `skills/` 和 `.incoming/` 暂保留英文名，因为它们更像工具 / 协议入口。
+独立 Project 也不默认创建 `_系统/主库同步/`、`_system/main-repo-sync/`、`.core-sync.json` 或 `.internal/`。这些只在项目中心创建项目工作台或升级接入项目中心时由 CLI 叠加。
 
-## `satellite-starter`
+## `hub`
+
+项目中心 Kit 的机制目录保持英文，用户可见目录按工作台语言生成。源码中的 `core/kits/hub/` 保留一套英文基准路径，CLI 会在中文项目中心生成时映射为中文可见目录。
 
-定位：轻量卫星项目 Kit。适合接入主库，但不启用事项机制的项目。
+中文项目中心目标结构：
 
 ```text
 .
 ├── AGENTS.md
-├── CLAUDE.md
 ├── README.md
-├── .core-sync.json
+├── .starwork/
+│   ├── workspace.json
+│   ├── skills.json
+│   └── handoff/
+├── .incoming/
 ├── .internal/
-│   └── README.md
-├── .obsidian/
-│   └── README.md
-├── .agents/
-│   └── skills/
-│       └── README.md
-├── .claude/
-│   └── skills/
-│       └── README.md
-├── _系统/
-│   ├── 上下文/
-│   │   └── 当前项目.md
-│   ├── 任务/
-│   │   └── 当前工作.md
-│   ├── 身份/
-│   │   └── README.md
-│   ├── 教训/
-│   │   └── README.md
-│   ├── 主库同步/
-│   │   └── README.md
-│   └── 跨项目/
-│       ├── README.md
-│       ├── inbox/
-│       │   └── README.md
-│       └── outbox/
-│           └── README.md
+├── 身份/
+├── 教训/
 ├── 知识/
-│   └── README.md
-├── 参考资料/
-│   └── README.md
-└── 输出/
-    ├── 草稿/
-    │   └── README.md
-    └── 确认成果/
-        └── README.md
+├── 项目/
+│   ├── README.md
+│   ├── registry.json
+│   └── 协作/
+├── 技能/
+│   ├── README.md
+│   └── registry.json
+└── 工作区/
+    └── README.md
 ```
 
-不包含：
-
-```text
-事项/
-_系统/上下文/决策.md
-```
-
-## `satellite-matter`
-
-定位：事项型卫星项目 Kit。适合接入主库，并启用事项机制的项目。
+英文 Project Center 目标结构：
 
 ```text
 .
 ├── AGENTS.md
-├── CLAUDE.md
 ├── README.md
-├── .core-sync.json
+├── .starwork/
+│   ├── workspace.json
+│   ├── skills.json
+│   └── handoff/
+├── .incoming/
 ├── .internal/
-│   └── README.md
-├── .obsidian/
-│   └── README.md
-├── .agents/
-│   └── skills/
-│       └── README.md
-├── .claude/
-│   └── skills/
-│       └── README.md
-├── _系统/
-│   ├── 上下文/
-│   │   ├── 当前项目.md
-│   │   └── 决策.md
-│   ├── 任务/
-│   │   └── 当前工作.md
-│   ├── 身份/
-│   │   └── README.md
-│   ├── 教训/
-│   │   └── README.md
-│   ├── 主库同步/
-│   │   └── README.md
-│   └── 跨项目/
-│       ├── README.md
-│       ├── inbox/
-│       │   └── README.md
-│       └── outbox/
-│           └── README.md
-├── 知识/
-│   └── README.md
-├── 参考资料/
-│   └── README.md
-├── 输出/
-│   ├── 草稿/
-│   │   └── README.md
-│   └── 确认成果/
-│       └── README.md
-└── 事项/
-    ├── 注册表.md
-    └── _事项模板/
-        ├── README.md
-        ├── 进度.md
-        ├── 笔记.md
-        ├── 交接.md
-        └── 草稿/
-            └── .gitkeep
+├── identity/
+├── lessons/
+├── knowledge/
+├── projects/
+│   ├── README.md
+│   ├── registry.json
+│   └── coordination/
+├── skills/
+│   ├── README.md
+│   └── registry.json
+└── workspace/
+    └── README.md
 ```
 
-## 已确认的结构原则
-
-1. 当前正式 Kit 的结构描述默认使用中文 profile。
-2. `AGENTS.md`、`README.md`、`CLAUDE.md` 暂保留工具生态约定文件名。
-3. 单项目 Kit 中，`身份/` 和 `教训/` 属于 `_系统/`。
-4. 卫星项目 Kit 中，`身份/` 和 `教训/` 也放在 `_系统/`，表示它们是主库快照或项目内候选沉淀，不是主库本体。
-5. Hub Kit 中，`identity/`、`lessons/` 保留在根目录，因为它们是中枢重点维护对象。
-6. `日记/` 不进入 v0.1 Kit。
-7. 通用卫星项目不默认包含 `product/`；默认确认成果位置是 `输出/确认成果/`。
-8. `knowledge/` 在默认中文 profile 中落地为 `知识/`。
-9. 卫星项目分为 no-matter 与 matter 两类：`satellite-starter` 和 `satellite-matter`。
-10. 默认中文 profile 的决策文件使用 `_系统/上下文/决策.md`，当前工作文件使用 `_系统/任务/当前工作.md`。
+项目中心不维护具体项目状态和当前工作入口。项目中心只记录项目在哪里、共享资源在哪里、跨项目联络如何路由。
+
+同一语义只能有一个可见目录：中文项目中心不应同时出现 `知识/` 和 `knowledge/`，英文 Project Center 不应同时出现 `knowledge/` 和 `知识/`。

package/core/kits/project/.agents/skills/README.md

@@ -0,0 +1,5 @@
+# Agents Skills
+
+这里放当前项目可用的 Agent skill。
+
+独立项目可以使用 Kit 自带 skill；接入 Hub 后，也可以由 CLI 挂载 Hub 分发的共享 skill。

package/core/kits/project/.claude/skills/README.md

@@ -0,0 +1,5 @@
+# Claude Skills
+
+这里放当前项目可用的 Claude skill。
+
+独立项目可以使用 Kit 自带 skill；接入 Hub 后，也可以由 CLI 挂载 Hub 分发的共享 skill。

package/core/kits/project/.obsidian/README.md

@@ -0,0 +1,5 @@
+# Obsidian 配置
+
+这里放当前项目的 Obsidian 本地配置。
+
+项目可以按自己的使用习惯调整；只有确认可跨项目复用的配置，才需要再沉淀到 Hub 或共享规则中。

package/core/kits/project/.starwork/handoff/archived/.gitkeep

@@ -0,0 +1 @@
+

package/core/kits/project/.starwork/handoff/inbox/.gitkeep

@@ -0,0 +1 @@
+

package/core/kits/project/.starwork/handoff/outbox/.gitkeep

@@ -0,0 +1 @@
+

package/core/kits/project/.starwork/handoff/sent/.gitkeep

@@ -0,0 +1 @@
+

package/core/kits/project/.starwork/handoff/state.json

@@ -0,0 +1,5 @@
+{
+  "schema": "starwork.handoff_state.v0.1",
+  "project_id": null,
+  "items": {}
+}

package/core/kits/project/AGENTS.md

@@ -0,0 +1,38 @@
+# StarWork 工作区规则
+
+## 开始前先读
+
+1. `_系统/上下文/当前项目.md`
+2. `_系统/任务/当前工作.md`
+3. 如果存在 `.starwork/rules/index.md`，再按索引读取扩展规则
+
+## 相关时再读
+
+- 涉及用户偏好、沟通方式、领域背景或长期上下文时，读 `_系统/身份/README.md`
+- 做重复性、风险较高或容易踩坑的工作前，读 `_系统/教训/README.md`
+- 如果项目已开启知识库，并且任务需要复用长期项目知识，读知识库规则和索引
+- 只有当工作台明确接入项目中心时，才读取项目中心同步说明
+
+## 文件边界
+
+- 项目状态写入 `_系统/上下文/当前项目.md`
+- 当前执行记录写入 `_系统/任务/当前工作.md`
+- 用户偏好、沟通方式和长期背景写入 `_系统/身份/README.md`
+- 会改变未来行为的复用经验写入 `_系统/教训/README.md`
+- 项目知识库不是默认目录；需要长期沉淀项目知识时，先用 `starwork knowledge init` 开启
+- 具体业务目录由已安装 Pack 或用户定制目录决定
+- 原始资料、AI 草稿和确认成果按 Pack 规则或 `.starwork/workspace.json` 中的路径映射处理
+- StarWork 机制状态放入 `.starwork/`
+
+## 工作方式
+
+- 不把初始化日志、命令执行结果或临时解释写入项目事实源
+- 不创建含义重叠的顶层目录；新增长期目录前先确认用途
+- 如果 `.starwork/rules/` 中有扩展规则，按索引读取，不把规则文件当作项目进度
+
+## 需要确认
+
+- 修改身份或稳定偏好
+- 将候选教训提升为稳定教训
+- 将草稿晋升为正式事实源
+- 改变工作台结构或顶层业务目录

package/core/kits/project/README.md

@@ -0,0 +1,44 @@
+# StarWork 项目工作台
+
+类型：项目工作台
+
+适合具体项目执行层。默认形态是独立项目工作台；如果由项目中心通过 `spawn` 创建，CLI 会额外叠加项目中心同步说明。
+
+## 包含
+
+- 默认中文路径 profile
+- 本地身份和教训模板
+- 项目事实源和当前工作入口
+- Kit 自带 skill 挂载能力
+
+## 规则
+
+项目工作台是具体项目执行层。独立项目本地维护身份和教训；知识库是可选能力，需要长期沉淀项目知识时再开启。由项目中心创建的管理关系由 `starwork spawn` 额外生成，不是项目工作台的默认可见结构。
+
+本 kit 预期包含：
+
+- `_系统/上下文/当前项目.md`：项目状态事实源
+- `_系统/任务/当前工作.md`：当前工作入口
+- `_系统/身份/`：项目本地长期背景和偏好模板
+- `_系统/教训/`：项目本地可复用经验模板
+- `.agents/skills/`、`.claude/skills/`：按需挂载项目可用 skill
+
+具体业务目录由 Pack 或用户定制目录决定。默认的 General Pack 会生成 `参考资料/`、`输出/草稿/` 和 `输出/确认成果/`；它们不是 Project Kit 的基础结构。
+
+如果用户需要让 AI 长期整理项目知识，运行 `starwork knowledge init` 开启 `知识库/` 能力。
+
+## 不默认包含
+
+- `参考资料/`
+- `输出/`
+- `事项/`
+- `_系统/上下文/决策.md`
+- `_系统/主库同步/`
+- `.core-sync.json`
+- `.internal/`
+
+项目特定事实进入项目自己的正式事实源，不写回项目中心正式目录。
+
+`_系统/上下文/当前项目.md` 是项目状态事实源。不要同时维护另一份 `_系统/上下文/项目状态.md`。
+
+注意：`.starwork/`、`.obsidian/` 是隐藏路径，很多文件管理器默认看不到。独立项目用户日常先关注 `AGENTS.md`、`_系统/` 和已安装 Pack 创建的业务目录。

package/core/kits/project/_/347/263/273/347/273/237//344/270/212/344/270/213/346/226/207//345/275/223/345/211/215/351/241/271/347/233/256.md

@@ -0,0 +1,25 @@
+# 当前项目
+
+## 目标
+
+待填写。
+
+## 当前阶段
+
+待填写。
+
+## 近期重点
+
+- 待填写。
+
+## 主要事实源
+
+- 待填写。
+
+## 风险
+
+- 待填写。
+
+## 下一步
+
+- 待填写。

package/core/kits/project/_/347/263/273/347/273/237//344/273/273/345/212/241//345/275/223/345/211/215/345/267/245/344/275/234.md

@@ -0,0 +1,17 @@
+# 当前工作
+
+## 现在
+
+- 待填写。
+
+## 下一步
+
+- 待填写。
+
+## 等待确认
+
+- 待填写。
+
+## 给下一个 AI 的备注
+
+- 待填写。

package/core/kits/project/_/347/263/273/347/273/237//346/225/231/350/256/255/README.md

@@ -0,0 +1,17 @@
+# 教训
+
+记录会改变未来行为的可复用经验。
+
+## 已确认教训
+
+- 待填写。
+
+## 候选教训
+
+- 待填写。
+
+## 写入规则
+
+好的教训应该具体、可复用，并能改变后续行为。
+不要把普通进度摘要写到这里。
+将候选教训提升为稳定教训前需要确认。

package/core/kits/project/_/347/263/273/347/273/237//350/272/253/344/273/275/README.md

@@ -0,0 +1,24 @@
+# 身份
+
+## 长期背景
+
+- 项目负责人 / 用户：
+- 工作习惯：
+- 领域背景：
+- 长期偏好：
+
+## 沟通偏好
+
+- 常用语言：
+- 语气：
+- 细节程度：
+
+## 稳定约束
+
+- 应该：
+- 避免：
+
+## 更新规则
+
+当任务涉及用户偏好、领域背景或长期上下文时读取本文件。
+修改稳定身份和偏好前必须确认。