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

package/core/capabilities/knowledge/capability.md

@@ -0,0 +1,72 @@
+# Knowledge Capability
+
+知识库是项目工作台的可选能力，不是 Project Kit 的默认目录。
+
+它用于让 Agent 长期维护当前项目的稳定理解。原始资料仍放在 Pack 定义的参考资料区，草稿和成果仍按 Pack 规则进入输出区。
+
+## Standard Paths
+
+中文项目开启后：
+
+```text
+知识库/
+├── README.md
+├── index.md
+├── schema.md
+├── log.md
+├── inbox/
+├── sources/
+├── pages/
+└── synthesis/
+```
+
+英文项目开启后：
+
+```text
+knowledge-base/
+├── README.md
+├── index.md
+├── schema.md
+├── log.md
+├── inbox/
+├── sources/
+├── pages/
+└── synthesis/
+```
+
+## Boundary
+
+- `参考资料/` or `references/`: raw source materials from the user.
+- `输出/` or `outputs/`: drafts and approved deliverables.
+- `知识库/` or `knowledge-base/`: long-term project knowledge organized by Agent.
+- Project Center shared knowledge is separate and is not defined by this capability.
+
+## Workspace State
+
+When enabled, `.starwork/workspace.json` records:
+
+```json
+{
+  "capabilities": {
+    "knowledge": {
+      "enabled": true,
+      "root": "知识库",
+      "language": "zh",
+      "mode": "local",
+      "version": "0.1",
+      "project_skill_ids": ["starworkKnowledgeProject"]
+    }
+  }
+}
+```
+
+This only means the current project has a local knowledge base. It does not imply Project Center submission or synchronization.
+
+After `starwork knowledge init` succeeds, StarWork also installs the project-local skill:
+
+```text
+.agents/skills/starworkKnowledgeProject/
+.claude/skills/starworkKnowledgeProject/
+```
+
+`starworkKnowledge` is the global entry skill. `starworkKnowledgeProject` is the project business skill and should only appear inside projects that have enabled this capability.

package/core/capabilities/knowledge/skills/starworkKnowledgeProject/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: starworkKnowledgeProject
+description: Maintain the current project's local StarWork knowledge base after it has been enabled by `starwork knowledge init`.
+---
+
+# starworkKnowledgeProject
+
+Use this skill only inside a project that already has a local knowledge base enabled.
+
+Before writing anything, run or inspect:
+
+```bash
+starwork knowledge status --json
+```
+
+Then read:
+
+1. `schema.md` in the knowledge base root.
+2. `index.md` in the knowledge base root.
+3. Relevant existing files under `pages/` and `synthesis/`.
+
+## What This Skill Does
+
+- Turn stable, reusable understanding into topic pages under `pages/`.
+- Turn cross-topic judgment, strategy, reviews, and decisions into files under `synthesis/`.
+- Keep `index.md` useful as a map, not a dumping ground.
+- Record meaningful maintenance changes in `log.md`.
+- Put unresolved knowledge fragments in `inbox/` with a short reason.
+- Keep source pointers in `sources/` when they help future review.
+
+## Boundaries
+
+- Do not put raw source files, meeting transcripts, command output, temporary drafts, or one-off task notes directly into the knowledge base.
+- Do not move, delete, or rename old `知识/`, `knowledge/`, or similar folders without a user-confirmed blueprint.
+- Do not submit anything to a Project Center shared knowledge area.
+- Do not write empty summaries without source context.
+- Do not use the knowledge base as the project's current task log or final output folder.
+
+## Pages Versus Synthesis
+
+Use `pages/` for stable subjects:
+
+- concepts
+- user groups
+- product modules
+- research topics
+- reusable methods
+
+Use `synthesis/` for connected thinking:
+
+- strategy
+- reviews
+- phase conclusions
+- tradeoff analysis
+- cross-topic decisions
+
+After updating either area, update `index.md` and `log.md`.

package/core/capabilities/knowledge/skills/starworkKnowledgeProject/agents/openai.yaml

@@ -0,0 +1,6 @@
+name: starworkKnowledgeProject
+summary: Maintain a local StarWork project knowledge base after it is enabled.
+instructions: |
+  Use the local knowledge base rules before editing. Read schema.md and index.md first.
+  Keep raw source material out of the knowledge base. Put stable topic knowledge in pages/
+  and cross-topic judgment in synthesis/. Update index.md and log.md after changes.

package/core/capabilities/knowledge/templates/en/README.md

@@ -0,0 +1,20 @@
+# Project Knowledge Base
+
+This is the local long-term knowledge base for the current project.
+
+It is not a raw materials folder. PDFs, webpages, screenshots, interview notes, and other source materials belong in the references area. This folder stores stable understanding, topic pages, and synthesized judgment maintained by the Agent.
+
+Read first:
+
+1. `schema.md`
+2. `index.md`
+
+## Structure
+
+- `index.md`: navigation map.
+- `schema.md`: maintenance rules.
+- `log.md`: knowledge maintenance log.
+- `inbox/`: candidates waiting to be organized.
+- `sources/`: source index.
+- `pages/`: stable topic pages.
+- `synthesis/`: cross-topic strategy, reviews, and synthesized judgment.

package/core/capabilities/knowledge/templates/en/index.md

@@ -0,0 +1,19 @@
+# Knowledge Map
+
+## Important Topic Pages
+
+None yet.
+
+## Synthesized Judgment
+
+None yet.
+
+## Waiting To Organize
+
+None yet.
+
+## Maintenance Notes
+
+- `pages/` stores stable long-term topics.
+- `synthesis/` stores judgment and insight formed from multiple topics.
+- After adding or updating knowledge, update this file and `log.md`.

package/core/capabilities/knowledge/templates/en/log.md

@@ -0,0 +1,16 @@
+# Knowledge Base Maintenance Log
+
+## Format
+
+```markdown
+## YYYY-MM-DD
+
+- Added:
+- Updated:
+- Sources:
+- Waiting:
+```
+
+## Records
+
+None yet.

package/core/capabilities/knowledge/templates/en/schema.md

@@ -0,0 +1,60 @@
+# Knowledge Base Maintenance Rules
+
+## What Belongs Here
+
+- Project understanding that will be useful again.
+- Important concepts, objects, methods, patterns, examples, and counterexamples.
+- Judgment supported by multiple sources or repeated project experience.
+- Knowledge the user explicitly wants to preserve long term.
+
+## What Does Not Belong Here
+
+- Raw PDFs, screenshots, full webpages, or meeting transcripts.
+- Temporary drafts, one-off task notes, or command output.
+- Final deliverables that the user has not approved.
+- Vague summaries without source or context.
+
+## `pages/` Rules
+
+`pages/` stores stable topic pages. Each page should focus on one topic, concept, object, or method.
+
+Suggested structure:
+
+```markdown
+# Topic
+
+## Current Understanding
+
+## Key Facts
+
+## Examples And Counterexamples
+
+## Related Topics
+
+## Sources
+```
+
+## `synthesis/` Rules
+
+`synthesis/` stores synthesized judgment. It should connect multiple topic pages, sources, and project experience.
+
+Good fits:
+
+- Stage reviews.
+- Strategy decisions.
+- Method summaries.
+- Relationships and tradeoffs across topics.
+
+## Source Rules
+
+- Important judgment should be traceable to sources.
+- Source summaries and locations belong in `sources/`.
+- Mark uncertain content as unverified.
+
+## Update Rules
+
+After maintaining the knowledge base:
+
+1. Update related `pages/` or `synthesis/`.
+2. Update `index.md`.
+3. Record the change in `log.md`.

package/core/capabilities/knowledge/templates/zh/README.md

@@ -0,0 +1,20 @@
+# 项目知识库
+
+这里是当前项目自己的长期知识库。
+
+它不是原始资料夹。用户提供的 PDF、网页、截图、访谈记录和素材应放在参考资料区；这里存放 Agent 整理后的稳定理解、主题知识和综合判断。
+
+开始维护前先读：
+
+1. `schema.md`
+2. `index.md`
+
+## 目录说明
+
+- `index.md`：知识地图，只做导航。
+- `schema.md`：整理规则，告诉 Agent 什么能进入知识库。
+- `log.md`：知识库维护记录。
+- `inbox/`：待判断和待整理的知识候选。
+- `sources/`：来源索引。
+- `pages/`：稳定主题页。
+- `synthesis/`：跨主题的策略、复盘和综合判断。

package/core/capabilities/knowledge/templates/zh/index.md

@@ -0,0 +1,19 @@
+# 知识地图
+
+## 重要主题页
+
+暂无。
+
+## 综合判断
+
+暂无。
+
+## 待整理
+
+暂无。
+
+## 维护提示
+
+- `pages/` 放一个个长期主题。
+- `synthesis/` 放基于多个主题形成的判断和洞察。
+- 新增或更新知识后，同步更新本文件和 `log.md`。

package/core/capabilities/knowledge/templates/zh/log.md

@@ -0,0 +1,16 @@
+# 知识库维护记录
+
+## 记录格式
+
+```markdown
+## YYYY-MM-DD
+
+- 新增：
+- 更新：
+- 来源：
+- 待处理：
+```
+
+## 记录
+
+暂无。

package/core/capabilities/knowledge/templates/zh/schema.md

@@ -0,0 +1,60 @@
+# 知识库整理规则
+
+## 什么内容值得进入知识库
+
+- 会在未来反复用到的项目理解。
+- 重要概念、对象、方法、规律、例子和反例。
+- 多次资料或多次项目经验共同支持的判断。
+- 用户明确希望长期保留的知识。
+
+## 什么内容不要直接放进知识库
+
+- 原始 PDF、截图、网页全文、会议逐字稿。
+- 临时草稿、一次性任务过程、命令输出。
+- 用户尚未确认的正式成果。
+- 没有来源、没有上下文的空泛总结。
+
+## `pages/` 写作规则
+
+`pages/` 存放稳定主题页。每页聚焦一个主题、概念、对象或方法。
+
+建议结构：
+
+```markdown
+# 主题名
+
+## 当前理解
+
+## 关键事实
+
+## 例子和反例
+
+## 相关主题
+
+## 来源
+```
+
+## `synthesis/` 写作规则
+
+`synthesis/` 存放综合判断。它需要连接多个主题页、来源和项目经验。
+
+适合内容：
+
+- 阶段复盘。
+- 策略判断。
+- 方法论整理。
+- 多主题之间的关系和取舍。
+
+## 来源规则
+
+- 重要判断要能追溯到来源。
+- 来源摘要和位置放入 `sources/`。
+- 不确定的内容要标记为待验证。
+
+## 更新规则
+
+每次维护知识库后：
+
+1. 更新相关 `pages/` 或 `synthesis/`。
+2. 更新 `index.md`。
+3. 在 `log.md` 记录本次维护。

package/core/capabilities/main-repo-sync/capability.md

@@ -1,43 +1,47 @@
 # Capability: main-repo-sync v0.1
 
-`main-repo-sync` 描述主库与卫星项目之间的 Hub + Satellite 模型。
+`main-repo-sync` 描述项目中心与中心管理项目工作台之间的同步模型。
 
 它不只是共享身份或共享教训，而是一整套协同模型：
 
-- Hub 是规则源、可复用知识源、项目注册表、skill 来源和消息路由层。
-- Satellites 是具体执行工作区。
+- 项目中心是规则源、可复用知识源、项目注册表、skill 来源和消息路由层。
+- 中心管理的项目工作台是具体执行工作区。
 - 初始化时复制稳定快照。
 - 部分资源以只读链接方式挂载。
-- 同步元数据记录在 `.core-sync.json`。
-- 项目发现依赖 Hub 的 registry。
+- 同步元数据优先记录在 `.starwork/sync.json`，legacy 工作台可继续使用 `.core-sync.json`。
+- 项目发现依赖项目中心的 registry。
 - 可复用更新通过 inbox / review 流程回写。
 
+`.starwork/` 的分层边界见：`product/core/starwork-runtime-layer-spec.md`。
+
 ## 核心模型
 
 一句话：
 
-> Hub 负责共享、可复用、可审计的公共机制；每个 Satellite 负责自己的项目事实和执行过程。
+> 项目中心负责共享、可复用、可审计的公共机制；每个项目工作台负责自己的项目事实和执行过程。
 
-这意味着 Hub 可以发现、初始化、同步和联络 Satellite，但 Hub 不会变成这些项目的进度数据库。
+这意味着项目中心可以发现、初始化、同步和联络项目工作台，但项目中心不会变成这些项目的进度数据库。
 
-## Hub 职责
+## 项目中心职责
 
-Hub 维护跨项目可复用资源：
+项目中心维护跨项目可复用资源：
 
 - `identity/`
 - `lessons/`
-- `.internal/` 协议
 - `knowledge/` 或语言 profile 映射后的知识入口
 - 共享 skills
 - 项目注册表
 - 跨项目消息路由
 - 可复用内容回写审核队列
+- 内部协议快照和同步机制状态
+
+项目中心不应该存放项目特定的执行内容。
 
-Hub 不应该存放项目特定的执行内容。
+其中 `identity/`、`lessons/`、`knowledge/`、`skills/` 是项目中心共享资产，不进入 `.starwork/`。项目注册表、跨项目消息路由、回写审核队列、同步状态和内部协议快照如果仅服务 StarWork 项目中心机制，优先放入 `.starwork/`。
 
-## Satellite 工作区职责
+## 中心管理项目工作台职责
 
-Satellite 工作区负责具体项目执行：
+中心管理的项目工作台负责具体项目执行：
 
 - 项目状态
 - 当前工作
@@ -45,43 +49,56 @@ Satellite 工作区负责具体项目执行：
 - 项目正式事实源
 - 项目专属决策和产出
 
-Satellite 可以包含来自主库的快照或链接，但这些资源默认仍然是共享参考层。
+项目工作台可以包含来自项目中心的快照或链接，但这些资源默认仍然是共享参考层。
 
-## Satellite 必需层
+## 中心管理项目的必需层
 
-一个由 Hub 管理的 Satellite 通常包含这些固定层：
+一个由项目中心管理的项目工作台通常包含这些固定层：
 
 - `AGENTS.md`
 - `CLAUDE.md`
 - `README.md`
-- `.core-sync.json`
+- `.starwork/workspace.json`
+- `.starwork/skills.json`
+- `.starwork/sync.json`
 - 一个可见的主库同步说明，例如 `_系统/主库同步/README.md` 或 `_system/hub-sync/README.md`
 - 主库身份快照，例如 `_系统/身份/`
 - 主库教训快照，例如 `_系统/教训/`
-- `.internal/`
+- `.starwork/internal/`
 - `.obsidian/`
 - `知识/` 或 `knowledge/` 作为只读链接
-- `_系统/上下文/当前项目.md` 或 `_system/context/current-projects.md`，作为项目状态事实源
+- `_系统/上下文/当前项目.md` 或 `_system/context/current-project.md`，作为项目状态事实源
 - `_系统/任务/` 或 `_system/tasks/`
-- `_系统/跨项目/` 或 `_system/cross-project/`
+- `.starwork/handoff/`
 
-中文卫星项目当前使用 `_系统/上下文/当前项目.md`，中文本地单项目使用 `_系统/上下文/项目状态.md`。两者都是同一个 Core 角色在不同 preset 下的映射，不能同时独立维护。
+legacy 工作台中的 `.core-sync.json` 和 `.internal/` 仍可被 CLI / doctor 读取，但新生成结构应优先使用 `.starwork/sync.json` 和 `.starwork/internal/`。
+
+中文中心管理项目当前使用 `_系统/上下文/当前项目.md`，中文本地单项目使用 `_系统/上下文/项目状态.md`。两者都是同一个 Core 角色在不同 preset 下的映射，不能同时独立维护。
 
 ## 同步语义
 
-| 资源 | 在 Satellite 中的形态 | 默认同步语义 |
+| 资源 | 在项目工作台中的形态 | 默认同步语义 |
 |---|---|---|
 | `identity/` | 复制快照 | 初始化自主库；后续更新需要手动确认。 |
 | `lessons/` | 复制快照 | 初始化自主库；项目特定教训先留在本地，确认可复用后再回写。 |
-| `.internal/` | 复制指定协议文件 | 只同步稳定协议，例如回写协议和合并策略。 |
+| `.starwork/internal/` | 复制指定协议文件 | 只同步稳定协议，例如回写协议和合并策略；legacy 路径为 `.internal/`。 |
 | `.obsidian/` | 复制配置 | 提供默认 Obsidian 本地行为。 |
 | `knowledge/` | 只读软链接 | 主库仍然是事实源。 |
-| `.core-sync.json` | 本地元数据 | 记录来源路径、版本、同步时间、挂载资源和 skills。 |
+| `.starwork/sync.json` | 本地元数据 | 记录来源路径、版本、同步时间、挂载资源和 skills；legacy 路径为 `.core-sync.json`。 |
+| `.starwork/handoff/` | 本地跨项目收发队列 | 记录消息信封、队列和投递状态，不承载项目业务材料正文。 |
 | shared skills | 软链接 | 不要把共享 skills 复制成项目内独立分叉。 |
 
 ## Registry 边界
 
-Hub 的 `项目/registry.json` 存放项目发现与同步元数据：
+项目中心的项目 registry 存放项目发现与同步元数据。推荐机制路径为：
+
+```text
+projects/registry.json
+```
+
+legacy 或用户可读目录可以继续提供说明或摘要，但机器事实源应避免散落成多份。
+
+registry 字段包括：
 
 - 项目 ID
 - 名称
@@ -95,10 +112,10 @@ Hub 的 `项目/registry.json` 存放项目发现与同步元数据：
 
 它不能存放项目进度正文。
 
-项目进度留在 Satellite 工作区内，通常位于：
+项目进度留在项目工作台内，通常位于：
 
 - `_系统/上下文/当前项目.md`
-- `_system/context/current-projects.md`
+- `_system/context/current-project.md`
 - 或 profile 声明的 Core v0.1 项目状态角色文件
 
 ## 状态读取顺序
@@ -107,7 +124,7 @@ Hub 的 `项目/registry.json` 存放项目发现与同步元数据：
 
 1. 工作区规则或 preset 声明的状态文件
 2. `_系统/上下文/当前项目.md`
-3. `_system/context/current-projects.md`
+3. `_system/context/current-project.md`
 4. `_系统/上下文/项目状态.md`
 5. `_system/context/project-status.md`
 
@@ -115,18 +132,24 @@ Hub 的 `项目/registry.json` 存放项目发现与同步元数据：
 
 ## 回写边界
 
-Satellite 工作区中出现的可复用建议，应通过主库审核流程回写，例如 `.incoming/`。
+项目工作台中出现的可复用建议，应通过项目中心审核流程回写。推荐机制路径为：
 
-跨项目 handoff 用于项目之间的请求、依赖、通知和交接。它不能替代主库的可复用知识审核队列。
+```text
+.incoming/
+```
 
-| 机制 | 用途 | 是否改变 Hub 正式内容 |
+跨项目 handoff 用于项目之间的请求、依赖、通知和交接。它不能替代项目中心的可复用知识审核队列。
+
+| 机制 | 用途 | 是否改变项目中心正式内容 |
 |---|---|---:|
-| `.incoming/` | Satellite 向 Hub 提交候选身份、教训、报告或知识更新。 | 只有 Hub 审核后才会改变。 |
-| cross-project handoff | 一个项目向另一个项目发送请求、同步、依赖或回复。 | 不会。 |
+| `.incoming/` | 项目工作台向项目中心提交候选身份、教训、报告或知识更新。 | 只有项目中心审核后才会改变。 |
+| `.starwork/handoff/` | 一个项目向另一个项目发送请求、同步、依赖或回复。 | 不会。 |
+
+候选内容一旦被审核通过，应进入项目中心共享资产目录，例如 `identity/`、`lessons/`、`knowledge/` 或 `skills/`。`.incoming/` 不应成为长期内容库。
 
 ## 生命周期
 
-| 状态 | 含义 | Hub 行为 |
+| 状态 | 含义 | 项目中心行为 |
 |---|---|---|
 | `active` | 项目正在推进。 | 纳入正常项目发现和状态读取。 |
 | `paused` | 项目有意暂停，但未来可能恢复。 | 保留 registry 记录和项目事实，不把沉默视为异常。 |

package/core/capabilities/skill-mount/capability.md

@@ -1,10 +1,12 @@
 # Capability: skill-mount v0.1
 
-`skill-mount` 描述主库共享 skills 如何提供给卫星项目使用。
+`skill-mount` 描述项目中心共享 skills 如何提供给中心管理的项目工作台使用。
+
+完整管理与分发协议见：`product/core/skill-management-spec.md`。
 
 ## 规则
 
-共享 skills 应通过软链接挂载，而不是复制成项目内独立分叉。
+共享 skills 应通过逐个软链接挂载，而不是复制成项目内独立分叉，也不应把项目中心的整个 `skills/` 目录无差别挂载给所有项目工作台。
 
 典型挂载方式：
 
@@ -13,12 +15,24 @@
 .claude/skills/<skill-name> -> /path/to/main-repo/skills/<skill-name>
 ```
 
+项目内应同时写入：
+
+```text
+.starwork/skills.json
+```
+
+用于记录本项目实际可用的 Skill、来源、挂载方式和放入原因。
+
+`.starwork/skills.json` 是 StarWork 机制 manifest，不存放 Skill 正文，也不替代 `.agents/skills/`、`.claude/skills/` 等工具入口。
+
 ## 边界
 
-- 共享 skills 仍然由主库拥有。
+- 共享 skills 仍然由项目中心拥有。
 - 项目专用 skill 修改必须放在项目专用 skill 路径中。
-- 卫星项目不能把软链接的共享 skill 当成本地项目代码来改。
+- 项目工作台不能把软链接的共享 skill 当成本地项目代码来改。
+- Kit manifest、Pack 声明和项目中心的 `skills/registry.json` 共同构成分发来源；项目工作台的 `.starwork/skills.json` 是项目已挂载清单。
+- 项目中心的 `skills/` 是共享资产库，不进入 `.starwork/`；`.starwork/skills.json` 只记录当前项目实际可用的 Skill 状态。
 
 ## CLI 职责
 
-CLI 应通过创建软链接安装共享 skills，并把挂载信息记录到 `.core-sync.json`。
+CLI 应通过创建逐个软链接安装共享 skills，并把挂载信息记录到 `.starwork/sync.json` 和 `.starwork/skills.json`。legacy 工作台中的 `.core-sync.json` 可以继续读取。

package/core/capabilities/starter-outputs/capability.md

@@ -1,8 +1,8 @@
-# Capability: starter-outputs v0.1
+# Legacy Capability: starter-outputs v0.1
 
-Starter Outputs 是面向不使用 Matter Mode 用户的轻量工作模式。
+Starter Outputs 已降级为历史说明。v0.1 当前由 General Pack 提供参考资料、草稿和确认成果目录，不再把这些目录作为 Core 基础能力。
 
-## 新增
+## 历史目录
 
 ```text
 references/
@@ -12,14 +12,12 @@ outputs/final/
 
 ## 规则
 
-- `references/` 存放原始资料，默认只读。
-- `outputs/drafts/` 存放等待审阅的 AI 草稿。
-- `outputs/final/` 存放用户确认后的成果。
-- 这个能力不要求存在 `matters/`。
+- `references/` / `参考资料/` 存放原始资料，默认只读。
+- `outputs/drafts/` / `输出/草稿/` 存放等待审阅的 AI 草稿。
+- `outputs/final/` / `输出/确认成果/` 存放用户确认后的成果。
+- 新工作台应通过 `packs/general/` 生成这些目录。
 
 ## 适合场景
 
-- 学员入门模板
-- 小型项目
-- 单次会话交付
-- 更喜欢简单文件夹、不想使用事项追踪的用户
+- 仅用于理解旧材料。
+- 新实现以 General Pack 为准。

package/core/capabilities/starter-outputs/templates/outputs/final/README.md

@@ -2,4 +2,4 @@
 
 这里放用户确认后的成果。
 
-项目可以选择其他正式事实源；但在 Starter Mode 中，本目录是默认确认成果位置。
+项目可以选择其他正式事实源；默认情况下，本目录是确认成果位置。