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

package/skills/starworkDoctor/SKILL.md

@@ -0,0 +1,435 @@
+---
+name: starworkDoctor
+description: 'Diagnose StarWork workspaces, legacy templates, and project-center-like repos from `starwork doctor --json`; explain issues and draft safe upgrade plans.'
+---
+
+# starworkDoctor
+
+使用这个 skill，把 `starwork doctor --json` 暴露的探测结果整理成清晰诊断；当用户明确要升级时，也由本 skill 继续采访用户并生成 `upgrade-blueprint.json`。
+
+`starworkDoctor` 不是 `starwork doctor` 命令本身，也不是 `starwork upgrade` 执行器。它负责在 CLI 探测之后做 AI 判断：
+
+- 当前目录是否已经具备 StarWork Core 的基本工作逻辑
+- 当前目录是否有清楚的入口规则、项目状态、当前工作、资料区、草稿区、正式成果区
+- 哪些非标准目录可能承担“参考资料”“正式成果”“草稿”“当前推进”等 Core 角色
+- 当前目录是否更像项目中心候选，而不是普通单项目旧模板
+- 当前目录缺少哪些 Core 必需结构
+- 应该如何整理、补齐或升级，且不破坏用户历史文件
+- 用户确认升级语义后，生成可 dry-run 的 `upgrade-blueprint.json` 和配套规则文件
+
+## 主入口边界
+
+如果用户只是询问产品总览、起步路径、安装入口或该用哪个 StarWork 能力，回到 `starwork` 主入口。`starworkDoctor` 只处理诊断、doctor 结果解释、旧目录整理和升级方案设计。
+
+历史上独立的 `starworkUpgrade` 系统 Skill 已取消；旧模板升级、旧宿主规则提炼和 upgrade blueprint 设计都由 `starworkDoctor` 承接。不要重新引导用户安装或调用独立 `starworkUpgrade` Skill。
+
+Kit / Pack 不是本 skill 的主线任务。只有在生成升级蓝图时，才选择 CLI 可执行的落地参数：单项目默认 `general` Pack；类似项目中心的旧工作区使用 `hub + preserve-names + pack:null`，避免创建重复标准目录。
+
+除非用户明确要求生成升级蓝图，否则这个 skill 只做诊断和建议，不生成 blueprint；除非用户明确要求执行命令，否则不直接修改用户工作区。
+
+## 升级旧目录的第一屏
+
+当用户说“把旧目录升级成 StarWork 工作台”“整理旧工作区”“修复旧模板”时，先讲清楚诊断和升级的区别：
+
+```text
+诊断是先看清当前目录的事实，升级是无损补齐 StarWork 工作台规则。
+
+我会先检查这个目录里已经有哪些项目说明、任务记录、资料区、成果区和 AI 入口规则，再判断它离 StarWork 工作台还差什么。
+
+接下来我会分三步走：
+1. 先运行 doctor 只读诊断；
+2. 再把可升级线索和不确定点讲清楚；
+3. 你确认后才生成升级方案并预览写入。
+
+这个过程不会移动、删除或覆盖你的历史文件；升级目标是保留原目录，只补必要的 StarWork 规则和状态。
+```
+
+## 参考
+
+需要完整边界、输出格式和后续 CLI 要求时，读取：
+
+```text
+../starworkDoctor-spec.md
+```
+
+需要更产品化的回复模板、术语翻译或项目中心候选示例时，读取：
+
+```text
+references/response-guide.md
+references/hub-upgrade.md
+references/rules-extraction-guide.md
+references/agent-rules-template.md
+```
+
+不要在 skill 内重复维护完整 schema，避免和 SPEC 漂移。
+
+## 产品边界
+
+```text
+starwork doctor = 探测器
+starworkDoctor skill = 诊断师 + 升级蓝图设计师
+starwork upgrade = 蓝图执行器
+```
+
+| 层 | 负责 | 不负责 |
+|---|---|---|
+| `doctor` CLI | 探测目录、列事实、输出 JSON、暴露信号和不确定性 | 做复杂语义判断、输出 next steps |
+| `starworkDoctor` skill | 解释、判断 Core 贴近度、追问、建议整理路径、生成 upgrade blueprint | 静默改文件、替用户做不可逆迁移 |
+| `starwork upgrade` CLI | 校验和执行用户确认过的 blueprint | 自行判断业务语义 |
+
+## 话术原则
+
+`starworkDoctor` 的产品气质是“温和诊断师”，不是严格 linter。
+
+- 开场避免失败感：不要说“你的工作区不合格”，应说“这个目录还不是标准 StarWork 工作台，但已经有一些可升级信号”。
+- 第一屏必须先给人话结论：能不能接入、会不会移动旧目录、下一步是什么。
+- 第一次出现 `workspace state` 时，解释为“StarWork 工作台身份证”。
+- 分开说明 `Core fit` 和 `upgrade readiness`：目录逻辑贴近不等于可以立刻升级。
+- 所有判断分三类表达：`我看到的事实`、`我推测的角色`、`需要你确认的地方`。
+- 角色映射写成“候选角色 + 依据 + 置信度 + 需要确认什么”。
+- 低置信度判断必须用柔和措辞，例如“可能承担”“更像是”“还不能只凭目录名确认”。
+- 缺失项要翻译成工作后果，例如“新 Agent 进来时会比较难判断先读哪里”。
+- 升级建议围绕“无损补齐”：保留原目录名，只补 StarWork state 和 Agent 入口规则，不移动、不删除、不覆盖历史内容。
+- 需要用户回答的问题最多 3 个，只问会影响 blueprint 的语义。
+
+推荐开场：
+
+```text
+我先把它当作“历史工作区候选”来看。当前它还不是标准 StarWork 工作台，但目录里已经有资料、成果或推进痕迹，适合先走无损诊断路线。
+```
+
+推荐不确定表达：
+
+```text
+“成稿/”很可能是正式成果区，但我还不能只凭目录名确认。需要你确认：这里是否只放已经认可的最终版本？
+```
+
+推荐缺失表达：
+
+```text
+现在缺少一个稳定的“当前工作入口”。这不代表目录有问题，只是新 Agent 进来时会比较难判断下一步该接哪里。
+```
+
+## 工作流程
+
+### Step 1：运行 doctor 探测
+
+优先执行：
+
+```bash
+starwork doctor --target <path> --json --inventory-depth all
+```
+
+如果用户没有给路径，先确认目标目录。不要默认扫描用户主目录或过大的上级目录。
+
+读取 JSON 后先判断：
+
+- 是否已有 `workspace`
+- 是否存在 `inventory`
+- 是否存在 `signals`
+- 是否缺少 workspace state
+- fail 是标准工作台损坏，还是历史模板缺少 state
+- 是否存在 `hub-like-main-repository`、`hub_candidate_paths`、`project_registry_files` 等项目中心候选信号
+
+`doctor` 输出只当作事实和信号，不把其中的 legacy 判断当作最终诊断。
+
+如果用户指定了宿主，或你从目录里看到宿主痕迹，再追加宿主诊断：
+
+```bash
+starwork doctor --target <path> --host <codex|claude-code|cursor|trae|all> --json
+```
+
+宿主痕迹包括：
+
+- `AGENTS.md` / `.agents/skills/`：Codex 或通用 Agent
+- `CLAUDE.md` / `.claude/skills/`：Claude Code
+- `.cursor/rules/` / `.cursor/skills/`：Cursor
+- `.trae/rules/` / `.trae/skills/` / `.trae/skill-config.json`：Trae
+
+解释时分开说：
+
+- StarWork 工作台结构问题
+- 宿主入口问题
+- Skill 目录问题
+- 同名 Skill 冲突
+- 宿主能力限制
+
+不要把宿主适配问题说成 Core 坏了。Cursor / Trae 不支持后台跨会话派活，也不是 StarWork 故障；那只是需要人工交付。
+
+### Step 2：读取少量关键文件
+
+只读取最能解释项目性质的文件：
+
+- `README.md`
+- `AGENTS.md`
+- `CLAUDE.md`
+- `.cursorrules`
+- `.cursor/rules/*`
+- `.trae/rules/*`
+- `_系统/上下文/项目状态.md`
+- `_系统/上下文/当前项目.md`
+- `_系统/任务/当前工作.md`
+- `matters/registry.md`
+- `事项/注册表.md`
+
+如果文件不存在，只记录缺失，不报错。
+
+读取入口规则时，目标不是把旧规则全文塞进新 `AGENTS.md`，而是识别其中仍有效的行为规则、写入边界、确认门槛和只读范围。规则提炼方法见 `references/rules-extraction-guide.md`。
+
+旧宿主规则文件也要纳入提炼范围：
+
+- `CLAUDE.md`
+- `.cursor/rules/**`
+- `.trae/rules/**`
+- 旧 `AGENTS.md`
+
+把旧规则分成三类：
+
+- 可保留：项目事实、工作边界、用户偏好。
+- 需要改写：旧目录路径、旧术语、旧工作流。
+- 应废弃：过期命令、冲突规则、污染业务目录的临时指令。
+
+升级后的入口不能出现 StarWork 内部占位符；旧规则原文应保留为证据，不要原样塞回新入口。
+
+### Step 3：建立 Core 角色映射
+
+基于 `inventory.directories`、`signals`、README 和少量关键文件，判断当前目录和 StarWork Core 角色的对应关系。
+
+输出时使用“候选 + 置信度 + 理由 + 是否需要确认”，不要把推断说成事实。
+
+核心角色包括：
+
+- Agent 入口规则
+- 项目状态
+- 当前工作
+- 参考资料 / 原始资料
+- 草稿 / 临时产物
+- 正式成果 / 事实源
+- 项目知识库是否已开启；旧 `知识/` 或 `knowledge/` 只作为线索，不默认当成新知识库
+- 事项推进
+- 决策记录
+- 身份偏好
+- 经验教训
+- 项目中心候选角色：项目登记、跨项目联络、回写待审、共享身份、共享教训、共享知识、共享 skills
+
+### Step 4：判断 Core 逻辑贴近程度
+
+主线判断不是像哪个 Kit / Pack，而是当前目录和 StarWork Core 的工作逻辑有多贴近。
+
+诊断矩阵必须覆盖：
+
+- 入口规则：Agent 进来先读什么？
+- 项目状态：项目现在是什么状态？
+- 当前工作：下一步正在推进什么？
+- 信息边界：资料、草稿、正式成果是否分开？
+- 长期记忆：身份、教训、决策是否有稳定位置？
+- 过程记录：项目工作台是否有过程记录和交接结构？
+- 写入风险：哪些目录应只读，哪些目录允许 Agent 写？
+- 知识库：如果未开启，不当作问题；如果存在旧 `知识/` / `knowledge/`，只说明它可能是什么，不能自动迁移或删除
+
+每项状态使用：
+
+- 清楚
+- 部分清楚
+- 缺失
+- 不确定
+
+整体贴近度使用：
+
+- 高
+- 中
+- 低
+- 不确定
+
+不要伪造精确分数。
+
+同时给出升级准备度：
+
+- `ready`：关键目录语义已确认，可以生成 blueprint。
+- `needs-confirmation`：目录逻辑贴近，但正式事实源、当前工作或项目中心映射还需要用户确认。
+- `not-recommended`：已经是健康 StarWork 工作台，或目标不是工作区。
+
+### Step 5：形成整理和升级建议
+
+建议应围绕 Core 逻辑补齐，而不是先围绕 Kit / Pack 分类。
+
+输出建议时回答：
+
+- 哪些现有目录应保留原名
+- 哪些目录应映射为 StarWork Core 角色
+- 哪些 Core 必需文件需要补齐
+- 是否需要事项机制
+- 是否是类似项目中心的旧工作区，应使用 `hub + preserve-names + pack:null`
+- 是否需要先保持旧模板，只补 state 和入口规则
+- 是否适合进入 `starwork upgrade --blueprint --dry-run`
+
+如果用户只是要诊断，到这里停止，不生成 blueprint。
+
+### Step 6：用户要求升级时，采访确认关键语义
+
+只有用户明确说“帮我升级”“生成 blueprint”“走 dry-run”“整理成 StarWork 工作台”时，才进入升级设计。
+
+只问会影响升级蓝图的问题：
+
+- 哪个目录是正式成果 / 确认事实源？
+- 哪个目录是当前工作 / 日常推进区？
+- 哪些目录是只读参考资料？
+- 是否需要事项机制？
+- 对项目中心候选：哪个目录是项目登记、跨项目协调和回写待审？
+- 希望保留旧目录名，还是逐步标准化？
+
+推荐问法：
+
+```text
+未来你希望 Agent 把哪里当成“不能乱改的正式成果”？
+```
+
+```text
+你平时真正干活的地方在哪里？比如推进事项、写草稿、放待办、记录阶段判断。
+```
+
+### Step 7：生成升级蓝图
+
+默认策略：
+
+```text
+preserve-names
+```
+
+也就是保留用户已有目录名，通过 `.starwork/workspace.json` 和 Agent 规则建立 StarWork Core 映射。
+
+默认 base：
+
+- 单项目旧模板：按 `project + project + general` 接入；如果 doctor 识别到 `single-light` 或 `local-starter`，只把它们当作历史信号
+- 多线推进旧模板：`project + project + general`
+- 项目中心候选：`hub + hub + pack:null`
+
+推荐输出目录：
+
+```text
+<workspace>-upgrade/
+├── upgrade-blueprint.json
+├── rules/
+│   ├── core-boundaries.md
+│   ├── user-preserved-rules.md
+│   └── rule-conflicts.md
+└── notes/
+    └── original-rules-summary.md
+```
+
+规则文件必须是短规则片段，不是完整 `AGENTS.md`。不要生成整篇入口规则，不要把项目背景、历史记录、会议纪要或低置信度推断写进规则片段。
+
+`rules/core-boundaries.md` 至少说明：
+
+- 正式成果目录
+- 当前工作目录
+- 参考资料目录
+- 保留历史命名的目录
+- Agent 不能覆盖、移动、删除的历史内容
+
+`rules/user-preserved-rules.md` 用来承接原有 `AGENTS.md`、`CLAUDE.md`、Cursor rules 等入口规则中仍有效的内容。如果没有发现可提炼规则，必须在回复中明确说明“未发现可提炼的原有规则”，不要生成空洞规则。
+
+`rules/rule-conflicts.md` 只记录冲突、过时或需要用户确认的规则，不直接注入 `AGENTS.md`。
+
+规则片段建议使用 `references/agent-rules-template.md` 的结构。
+
+`upgrade-blueprint.json` 中 `generated_by` 写：
+
+```json
+"generated_by": "starworkDoctor"
+```
+
+蓝图执行命令：
+
+```bash
+starwork upgrade --target <workspace> --blueprint <workspace>-upgrade/upgrade-blueprint.json --dry-run
+```
+
+用户确认后：
+
+```bash
+starwork upgrade --target <workspace> --blueprint <workspace>-upgrade/upgrade-blueprint.json --yes
+starwork doctor --target <workspace>
+```
+
+## 报告结构
+
+诊断模式：
+
+```text
+## 诊断结论
+
+## 我看到的事实
+
+## 我推测的角色
+
+## Core 逻辑贴近程度
+
+## 缺失和风险
+
+## 整理升级建议
+
+## 需要你确认的问题
+```
+
+升级设计模式：
+
+```text
+## 升级判断
+
+## 用户已确认的目录语义
+
+## 升级策略
+
+## 生成的 blueprint 文件
+
+## dry-run 命令
+
+## 执行前请再次确认
+```
+
+## 机器可读建议
+
+如果需要给 CLI 或后续流程使用，可以附加：
+
+```json
+{
+  "schema": "starwork.doctor_skill.recommendation.v0.1",
+  "target": "/path/to/workspace",
+  "diagnosis": "legacy-template",
+  "core_fit": "medium",
+  "upgrade_readiness": "needs-confirmation",
+  "core_role_mapping_candidates": {
+    "formal_source": [
+      {
+        "path": "成稿/",
+        "confidence": "high",
+        "reason": "目录名表示最终稿",
+        "needs_user_confirmation": true
+      }
+    ]
+  },
+  "blocking_risks": [
+    "缺少 workspace state，CLI 无法把目录识别为标准 StarWork 工作台。"
+  ],
+  "confirmation_questions": [
+    "成稿/ 是否就是你确认后的正式成果？",
+    "资料库/ 是否默认只读？"
+  ]
+}
+```
+
+## 约束
+
+- 不静默修改用户文件。
+- 不把低置信度判断说成事实。
+- 不把 Kit / Pack 贴近度当作主线诊断。
+- 不只根据一个目录名判断目录角色。
+- 不鼓励用户立即执行破坏性迁移。
+- 不读取大量内容文件，除非用户明确要求深入审计。
+- 不把 `doctor` 的 legacy 判断当作最终结论；它只是信号。
+- 不直接执行 `starwork upgrade --yes`，除非用户明确要求。
+- 不生成包含绝对路径、`..`、`.git/`、`node_modules/` 写入动作的 blueprint。
+- 不主动推荐未定稿业务 Pack；v0.1 单项目升级默认 `general`，项目中心候选默认 `pack:null`。
+- 不生成完整 `AGENTS.md`；只生成可注入的短规则片段。
+- 不把旧规则原文无筛选地塞进新规则槽；必须先提炼、分类和标注来源。

package/skills/starworkDoctor/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "StarWork Doctor"
+  short_description: "解释 StarWork 检查结果，识别旧模板或 Hub-like 主库，并按需生成升级蓝图"
+  default_prompt: "Use $starworkDoctor to explain starwork doctor output, diagnose legacy or Hub-like main repositories, and generate a safe upgrade blueprint when requested."
+
+policy:
+  allow_implicit_invocation: true

package/skills/starworkDoctor/references/agent-rules-template.md

@@ -0,0 +1,64 @@
+# Agent Rules Template
+
+Use this template for rule fragments that will be injected into `AGENTS.md` through `starwork upgrade`.
+
+Do not write a full `AGENTS.md`. Write only the body of one StarWork rule slot.
+
+## Template
+
+```markdown
+### Read First
+
+- ...
+
+### Write Boundaries
+
+- ...
+
+### Preserve
+
+- ...
+
+### Confirm Before
+
+- ...
+```
+
+## Style Rules
+
+- Keep each section short.
+- Use concrete paths.
+- Say whether a path is read-only, draft, working, or final.
+- Use "ask before" for risky operations.
+- Do not include project history, rationale, or meeting notes.
+- Do not write uncertain guesses as rules.
+
+## Good Example
+
+```markdown
+### Read First
+
+- Read `README.md` and `AGENTS.md` before changing project files.
+
+### Write Boundaries
+
+- Treat `资料库/` as read-only reference material.
+- Put draft work in `输出/草稿/`.
+- Treat `成稿/` as confirmed final output.
+
+### Preserve
+
+- Do not rename, move, or delete existing legacy folders during upgrade.
+
+### Confirm Before
+
+- Ask before changing final outputs, identity files, lessons, or shared knowledge.
+```
+
+## Bad Example
+
+```markdown
+This project started in 2024. The previous team used several folders and had many discussions about the writing process...
+```
+
+That is background, not an Agent rule.

package/skills/starworkDoctor/references/hub-upgrade.md

@@ -0,0 +1,73 @@
+# Hub-like Main Repository Upgrade
+
+Use this reference when `doctor --json` shows main-repository or Hub-like signals such as `identity/`, `lessons/`, `knowledge/`, `skills/`, `projects/registry.json`, `projects/coordination/`, or `.incoming/`.
+
+## Diagnosis Policy
+
+Treat the directory as a Hub-like main repository candidate, not as a normal `project` legacy template.
+
+Recommended wording:
+
+```text
+这个目录更像“主库 / 多项目中枢”候选，而不是普通单项目旧模板。它已经有共享身份、教训、知识、skills、项目登记和回写待审入口。建议按 Hub preserve-names 方式无损接入：保留 `projects/`、`knowledge/`、`skills/` 等原名，只补 StarWork 工作台身份证和 Agent 边界规则。
+```
+
+Avoid:
+
+```text
+建议按 project 升级。
+```
+
+## Blueprint Defaults
+
+For a confirmed Hub-like main repository:
+
+```json
+{
+  "base": {
+    "workspace_type": "hub",
+    "kit": "hub",
+    "language": "zh",
+    "pack": null
+  },
+  "strategy": "preserve-names",
+  "paths": {
+    "formal_source": "projects/",
+    "business_work_area": "projects/coordination/"
+  }
+}
+```
+
+`pack:null` is intentional. It prevents `starwork upgrade` from installing `hub-management` Pack seed files and creating duplicate standard paths. New Hub workspaces use standard paths such as `projects/` and `knowledge/`, but preserve-name upgrades should keep the user's existing Hub-like structure.
+
+## Required Role Mapping
+
+Include confirmed mappings when they exist:
+
+```json
+[
+  { "role": "projects", "path": "projects/", "confidence": "high", "reason": "用户确认这是项目总登记区" },
+  { "role": "project_registry", "path": "projects/registry.json", "confidence": "high", "reason": "用户确认这是项目注册表" },
+  { "role": "coordination", "path": "projects/coordination/", "confidence": "high", "reason": "用户确认这是跨项目协调入口" },
+  { "role": "incoming", "path": ".incoming/", "confidence": "high", "reason": "用户确认这是回写待审区" },
+  { "role": "identity", "path": "identity/", "confidence": "high", "reason": "用户确认这是共享身份事实源" },
+  { "role": "lessons", "path": "lessons/", "confidence": "high", "reason": "用户确认这是共享教训事实源" },
+  { "role": "knowledge", "path": "knowledge/", "confidence": "high", "reason": "用户确认这是共享知识事实源" },
+  { "role": "skills", "path": "skills/", "confidence": "high", "reason": "用户确认这是共享 skill 来源" }
+]
+```
+
+## Safe Actions
+
+Use only low-risk actions:
+
+```json
+[
+  { "type": "ensure_dir", "path": ".starwork/" },
+  { "type": "write_workspace_state" },
+  { "type": "copy_kit_missing_files" },
+  { "type": "inject_agent_rules", "target": "AGENTS.md", "from": "rules/hub-boundaries.md", "slot": "upgrade.hub_boundaries" }
+]
+```
+
+Do not add `copy_seed` for standard Hub Pack seed unless the user explicitly asks to create standard StarWork Hub directories.

package/skills/starworkDoctor/references/response-guide.md

@@ -0,0 +1,57 @@
+# starworkDoctor Response Guide
+
+Use this reference when the user says the diagnosis is hard to understand, asks for a friendlier explanation, or gives feedback about wording.
+
+## First Screen
+
+Start with three plain-language answers before detailed sections:
+
+```text
+结论：这个目录可以接入 StarWork，但现在还缺“工作台身份证”。
+安全性：建议无损接入，不移动、不改名、不覆盖历史目录。
+下一步：如果你确认关键目录语义，我会先生成 dry-run blueprint，只预览不写入。
+```
+
+For an existing healthy StarWork workspace:
+
+```text
+结论：这个目录已经是健康的 StarWork 工作台，不需要走 upgrade。
+下一步：如果要扩展能力，优先考虑 adapt、pack install 或后续 update。
+```
+
+## Term Translations
+
+- `workspace state` / `.starwork/workspace.json`：StarWork 工作台身份证，让 CLI 知道这个目录是什么类型、哪些地方能写、哪些地方要保护。
+- `preserve-names`：保留旧目录名，只补 StarWork 识别和边界规则。
+- `dry-run`：只预览计划，不写入文件。
+- `blueprint`：升级施工图，先由用户确认，再交给 CLI 执行。
+- `Core fit`：目录工作逻辑和 StarWork Core 有多接近。
+- `upgrade readiness`：现在是否已经具备生成升级施工图的条件。
+
+## Role Mapping Format
+
+Use this shape for inferred roles:
+
+```text
+- `projects/`：候选角色是项目登记区。依据是存在 `projects/registry.json`；置信度高。需要确认：这里是否仍是主库维护的项目总登记？
+```
+
+Do not write only:
+
+```text
+- `projects/` 是项目登记区。
+```
+
+## Question Limit
+
+Ask at most 3 questions. Prefer questions that directly affect blueprint fields:
+
+- 哪个目录要写入 `paths.formal_source`？
+- 哪个目录要写入 `paths.business_work_area`？
+- 哪些目录需要写进 `preserve`，确保不移动、不覆盖？
+
+For Hub-like repositories, ask:
+
+- `projects/` 是否就是项目总登记区？
+- `projects/coordination/` 是否就是跨项目协调入口？
+- `.incoming/` 是否继续作为回写待审区？