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

package/core/core-v0.1-protocol.md

@@ -71,7 +71,23 @@ _系统/上下文/当前项目.md
 
 Core 不强制正式事实源必须叫 `product/`。
 
-过程材料不能被悄悄当成正式事实源。比如 matter 草稿、会议笔记、AI 草稿，都必须经过用户确认或明确晋升，才能进入正式事实源。
+过程材料不能被悄悄当成正式事实源。比如 事项 草稿、会议笔记、AI 草稿，都必须经过用户确认或明确晋升，才能进入正式事实源。
+
+## `.starwork/` 机制运行层
+
+`.starwork/` 是 StarWork 机制运行层，不是隐藏的项目内容目录。
+
+它只存放在 StarWork Core、CLI、Pack、Skill、Adapter 等机制下才需要的状态、索引、manifest、队列、安装记录、缓存和报告，例如：
+
+- `.starwork/workspace.json`
+- `.starwork/skills.json`
+- `.starwork/packs/`
+- `.starwork/handoff/`
+- `.starwork/sync.json`
+
+项目状态、当前工作、参考资料、草稿、正式成果、知识、身份、教训和协作记录，即使由 StarWork 创建或由 Agent 读写，也不进入 `.starwork/`。`.starwork/` 可以引用这些内容的路径，但不拥有这些内容。
+
+详细边界见：[StarWork Runtime Layer SPEC](./starwork-runtime-layer-spec.md)。
 
 ## v0.1 可选能力
 
@@ -80,23 +96,20 @@ Core v0.1 把额外功能做成 capabilities。能力可以组合，但不能改
 | 能力 | 作用 |
 |---|---|
 | `starter-outputs` | 提供 `references/`、`outputs/drafts/`、`outputs/final/` 的轻量工作流。 |
-| `matter-mode` | 提供事项机制，适合长期项目和跨会话接力；具体路径由语言 profile 决定。 |
 | `decisions` | 提供高影响决策记录，不记录普通会议流水；具体文件名由语言 profile 决定。 |
 | `local-identity` | 在项目内维护本地身份信息。 |
 | `local-lessons` | 在项目内维护本地可复用教训。 |
 | `main-repo-sync` | 支持主库 + 多个卫星项目的 Hub + Satellite 模型。 |
 | `skill-mount` | 通过软链接挂载主库共享 skills。 |
+| `agent-lanes` | 支持同一项目内多个 Agent 会话按职责位分工协作。 |
 
-## 五种首批形态
+## 两种正式形态
 
-v0.1 先保留五种工作区形态。Kit 名称不携带语言标签；当前正式 Kit 默认以中文 profile 落地，其他语言通过 profile 扩展。
+v0.1 只保留两种正式工作区形态。Kit 名称不携带语言标签；当前正式 Kit 默认以中文 profile 落地，其他语言通过 profile 扩展。
 
 | Preset | 面向谁 | 默认特点 |
 |---|---|---|
-| `local-starter` | 学员、轻量单项目用户 | 本地身份/教训，轻量输入输出工作流，不启用事项。 |
-| `local-matter` | 单项目长期用户 | 本地身份/教训，启用 Matter Mode 和高影响决策。 |
-| `satellite-starter` | 接入主库的轻量卫星项目 | 主库分发身份、教训、知识、skills；卫星项目不默认启用事项。 |
-| `satellite-matter` | 主库 + 多卫星项目用户 | 主库分发身份、教训、知识、skills；卫星项目维护自己的事项和正式事实源。 |
+| `project` | 具体项目用户 | 项目状态、当前工作、参考资料、草稿、确认成果；可独立使用，也可由 Hub 管理。 |
 | `hub` | 多项目管理中枢用户 | 统一维护身份、教训、知识、skills、项目注册表和跨项目联络。 |
 
 Preset 是配方，不是协议本身。它选择 profile、capabilities 和默认正式事实源。
@@ -148,22 +161,12 @@ Core 支持单项目工作区，也支持主库 + 多卫星项目。
 多项目工作区中，采用 Hub + Satellite 模型：
 
 - Hub 维护跨项目共享身份、教训、知识、skills、项目注册表、跨项目联络和回写审核。
-- Satellite 维护自己的项目状态、当前工作、事项过程、项目决策和正式事实源。
+- Satellite 维护自己的项目状态、当前工作、项目决策和正式事实源。
 
 Hub 可以读取 Satellite 的项目状态，但不能把项目进度正文复制进 registry。
 
 Satellite 也不能把主库快照、共享知识或软链接 skills 当成本地内容随意改写。
 
-## 事项机制
-
-Matter Mode 是增强能力，不是所有用户必需能力。
-
-学员或轻量用户可以只使用 `references/outputs`。
-
-长期项目、跨会话接力、复杂推进过程更适合使用事项机制。中文 Kit 使用 `事项/`，英文 Kit 可使用 `matters/`。
-
-启用 Matter Mode 时，应配套事项维护规则或 skill。否则目录存在了，但创建、更新、暂停、归档的动作仍然容易混乱。
-
 ## 决策记录
 
 决策记录是可选能力，不是必需文件。中文 Kit 使用 `_系统/上下文/决策.md`，英文 Kit 可使用 `decisions.md`。
@@ -183,9 +186,8 @@ Core v0.1 可以封版，至少需要满足：
 
 - 普通人能读懂 Core 是什么、不是什么。
 - Agent 能知道开始前读哪里、当前工作写哪里、正式事实源在哪里。
-- 五种首批工作区形态边界清楚。
+- Project 和 Hub 两种正式工作区形态边界清楚。
 - 单项目和多项目不互相污染。
-- Matter Mode 是可选增强，不强迫所有用户使用。
 - Kit 被定位为参考实现或 CLI 输出，不被误认为协议事实源。
 - CLI 的职责被清楚留出，但不在 Core 中实现。
 

package/core/kits/README.md

@@ -1,6 +1,6 @@
 # Core Kits
 
-Kits 是由 presets 组装出来、可供用户复制使用的工作区模板包。
+Kits 是由 presets 组装出来的内部工作区模板包。普通用户通常只需要理解“项目工作台”和“项目中心”。
 
 它们不是协议事实源。事实源是：
 
@@ -10,6 +10,14 @@ baseline/ + profiles/ + capabilities/ + presets/
 
 在 v0.1 阶段，kits 可以手工组装。后续 `starwork init` 应根据 presets 生成 kits。
 
+## v0.1 正式 Kit
+
+- `project/`：项目工作台基础结构。
+- `hub/`：项目中心基础结构。
+
+旧 `satellite-starter` 已移入 `core/legacy/`，不再作为正式 Kit。中心管理的项目工作台由 `project` Kit 加 `project_center` 连接信息表达。
+
 ## 结构参考
 
 - [Kit Structure Reference](./kit-structure-reference.md)
+- [Two-Kit Architecture SPEC](./two-kit-architecture-spec.md)

package/core/kits/hub/.incoming/README.md

@@ -1,5 +1,7 @@
 # Incoming
 
-这里存放等待审核的共享内容候选。
+这里存放等待 Hub 审核的共享内容候选。
 
-候选内容确认后，才能进入正式身份、教训、知识或 skills。
+可进入这里的内容包括身份、教训、知识、skill 和跨项目报告候选。
+
+不要直接把候选内容写入正式共享资源；先审核，再合并到 `identity/`、`lessons/`、`knowledge/` 或 `skills/`。

package/core/kits/hub/.incoming/reports/.gitkeep

@@ -0,0 +1 @@
+

package/core/kits/hub/.incoming/skills/.gitkeep

@@ -0,0 +1 @@
+

package/core/kits/hub/.internal/twin-bot-merge-policy.md

@@ -0,0 +1,5 @@
+# Merge Policy
+
+Hub formal sources are cautious-write areas.
+
+Project-specific material stays in the originating project. Drafts, experiments, and unfinished common capabilities belong in `workspace/`.

package/core/kits/hub/.internal/twin-bot-writeback-protocol.md

@@ -0,0 +1,5 @@
+# Writeback Protocol
+
+Candidate updates from satellite projects must enter `.incoming/` first.
+
+Only reviewed, cross-project reusable material may be merged into `identity/`, `lessons/`, `knowledge/`, or `skills/`.

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1 @@
+

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

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

package/core/kits/hub/AGENTS.md

@@ -1,23 +1,29 @@
-# StarWork 多项目中枢规则
+# StarWork 项目中心规则
 
 ## 开始前先读
 
-1. `_系统/上下文/项目状态.md`
-2. `_系统/任务/当前工作.md`
-3. `项目/registry.json`
+1. `projects/registry.json`
+2. `projects/coordination/README.md`
+3. `skills/registry.json`
+4. `.incoming/`
+5. `workspace/README.md`
 
-## 中枢职责
+## 项目中心职责
 
-- 维护跨项目共享身份、教训、知识和 skills。
-- 维护项目注册表和跨项目联络机制。
-- 审核候选回写内容。
+- 维护跨项目共享身份、教训、知识和正式 skills。
+- 维护项目注册表和跨项目联络中央路由。
+- 审核中心管理项目工作台的回写候选。
+- 在 `workspace/` 中开发通用规则草稿、实验和 skill 原型。
 
 ## 写入边界
 
-- 项目注册信息写入 `项目/registry.json`。
-- 跨项目联络写入 `项目/联络/`。
-- 候选共享内容先写入 `.incoming/`。
-- 具体项目的进度正文留在各自项目内，不复制进中枢。
+- 项目注册信息写入 `projects/registry.json`。
+- 跨项目中央路由写入 `projects/coordination/`。
+- 项目中心自己的本地收发队列写入 `.starwork/handoff/`。
+- 候选共享内容先写入 `.incoming/`，审核后再合并。
+- 草稿、实验和未定稿通用能力只能先写入 `workspace/`。
+- 正式共享资产写入 `identity/`、`lessons/`、`knowledge/`、`skills/`。
+- 具体项目的进度正文留在各自项目工作台内，不复制进项目中心。
 
 ## 需要确认
 

package/core/kits/hub/README.md

@@ -1,25 +1,33 @@
-# 多项目管理中枢 Kit
+# 项目中心 Kit
 
 Preset: `hub`
 
-适合希望建立主库 / 中枢的用户。
+适合希望统一管理多个项目工作台的用户。项目中心是共享资产、项目注册、跨项目路由、回写审核和通用能力草稿的管理层，不是具体项目工作台。
 
 ## 包含
 
 - `AGENTS.md`
-- `_系统/上下文/项目状态.md`
-- `_系统/任务/当前工作.md`
+- `.starwork/workspace.json`
+- `.starwork/skills.json`
+- `.starwork/handoff/`
+- `.internal/`
+- `.incoming/`
+- `projects/registry.json`
+- `projects/coordination/`
 - `identity/`
 - `lessons/`
-- `知识/`
+- `knowledge/`
 - `skills/`
-- `项目/`
-- `.incoming/`
+- `workspace/`
+
+`.starwork/` 是 StarWork 机制运行层。项目中心的 `identity/`、`lessons/`、`knowledge/`、`skills/`、`projects/` 和 `.incoming/` 都是可理解、可审核的工作区内容，不放进 `.starwork/`。
 
 ## 不包含
 
 - 业务项目的正式事实源
-- 卫星项目初始化
+- 直接承载具体项目进度正文
+- 单项目的当前项目状态和当前工作入口
+- `templates/`
 - 自媒体、产品经理等业务 Pack
 
-卫星项目创建应由后续专门命令完成。
+从项目中心创建项目工作台应由 `starwork spawn` 完成。

package/core/kits/hub/identity/README.md

@@ -1,5 +1,5 @@
 # 身份信息
 
-这里存放跨项目共享身份、偏好和长期背景。
+这里维护项目中心层面的跨项目身份、偏好和长期上下文。
 
-修改前需要用户确认。
+具体项目中的临时偏好不要写入这里。确认具有跨项目复用价值后，先进入 `.incoming/identity/` 等待审核。

package/core/kits/hub/knowledge/README.md

@@ -0,0 +1,5 @@
+# 共享知识库
+
+这里是项目中心的跨项目共享知识事实源。
+
+中心管理的项目工作台默认只读引用本目录；需要沉淀公共知识时，先通过 `.incoming/knowledge/` 提交候选内容。

package/core/kits/hub/lessons/README.md

@@ -1,5 +1,5 @@
 # 教训库
 
-这里存放跨项目可复用教训。
+这里维护跨项目可复用教训。
 
-只有能改变未来行为的经验才进入这里。
+具体项目中的一次性复盘不要直接写入这里。确认可复用后，先进入 `.incoming/lessons/` 等待审核。

package/core/kits/hub/projects/README.md

@@ -0,0 +1,5 @@
+# 项目注册
+
+这里记录项目中心管理的项目清单和跨项目协调层。
+
+`registry.json` 只记录项目发现、路径、状态和同步元数据，不存放项目进度正文。

package/core/kits/hub/projects/coordination/README.md

@@ -0,0 +1,5 @@
+# 跨项目协调层
+
+这里是跨项目联络单的中央路由层。
+
+`messages/` 记录 queued、delivered、acknowledged、closed 等状态；项目中心自己的本地收发队列在 `.starwork/handoff/`。

package/core/kits/hub/projects/coordination/messages/acknowledged/.gitkeep

@@ -0,0 +1 @@
+

package/core/kits/hub/projects/coordination/messages/closed/.gitkeep

@@ -0,0 +1 @@
+

package/core/kits/hub/projects/coordination/messages/delivered/.gitkeep

@@ -0,0 +1 @@
+

package/core/kits/hub/projects/coordination/messages/queued/.gitkeep

@@ -0,0 +1 @@
+

package/core/kits/hub/projects/coordination/reports/.gitkeep

@@ -0,0 +1 @@
+

package/core/kits/hub/skills/README.md

@@ -1,5 +1,7 @@
 # Skills
 
-这里存放跨项目共享 skills。
+这里存放项目中心正式通用 skill。
 
-项目专用 skill 应留在项目内；确认通用后再回写到中枢。
+新的通用 skill 先在 `workspace/` 中开发和打磨。成熟后再进入这里，并登记到 `registry.json`。
+
+项目专用 skill 应留在项目内；确认通用后先进入 `.incoming/skills/` 等待审核。

package/core/kits/hub/skills/registry.json

@@ -0,0 +1,6 @@
+{
+  "schema": "starwork.skill_registry.v0.1",
+  "owner": "hub",
+  "updated_at": null,
+  "skills": []
+}

package/core/kits/hub/workspace/README.md

@@ -0,0 +1,5 @@
+# 项目中心工作区
+
+这里是项目中心内唯一的草稿、实验和通用能力开发区。
+
+新的通用 skill、规则草稿和临时实验先放在这里；成熟后再进入 `skills/`、`lessons/`、`identity/` 或 `knowledge/`。