Starworkdoctor

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 工作台”“整理旧工作区”“修复旧模板”时，先讲清楚诊断和升级的区别：

诊断是先看清当前目录的事实，升级是无损补齐 StarWork 工作台规则。

我会先检查这个目录里已经有哪些项目说明、任务记录、资料区、成果区和 AI 入口规则，再判断它离 StarWork 工作台还差什么。

接下来我会分三步走：
1. 先运行 doctor 只读诊断；
2. 再把可升级线索和不确定点讲清楚；
3. 你确认后才生成升级方案并预览写入。

这个过程不会移动、删除或覆盖你的历史文件；升级目标是保留原目录，只补必要的 StarWork 规则和状态。

MultiAgent preflight 第一屏

当用户从 starworkMultiagent 过来，或用户问“这个项目适不适合开启多 AI 协作 / 多 Agent 分工”时，先做 MultiAgent preflight。第一屏先回答三个问题，再解释细节：

多 AI 协作准备度：

结论：我会先检查这个项目现在是否适合继续创建 AI 岗位。
文件影响：这次只是检查，不会改项目文件。
下一步：如果入口说明、当前任务和写入边界都清楚，就可以回到 MultiAgent 设计 AI 岗位；如果还缺，我会先告诉你缺什么，再建议用 starworkInit 安全补齐。

检查阶段必须明确只读，不自动 repair、upgrade 或写入文件。用户明确说“帮我补齐 / 修复 / 接入”时，才转入 starworkInit 或升级方案流程，并且仍要先预览、再确认。

MultiAgent preflight 至少解释这些用户能听懂的影响：

诊断结论层放在“我看到的事实 / 我推测的角色 / 需要你确认的地方”之前：

诊断结论：

多 AI 协作准备度：可以继续 / 需要先补入口 / 需要先确认边界 / 不建议继续。

这次是否会改文件：不会，这只是检查。

下一步建议：
- 如果你要创建 AI 岗位：先补齐 ...
- 如果你只是想了解现状：目前主要缺 ...

缺失项不要只输出内部检查名，要翻译成人话：

现在缺少“当前任务入口”。这不代表项目有问题，但另一个 AI 接手时可能不知道你现在要它接哪一步。

现在还没有 StarWork 工作台身份证。CLI 还不能稳定判断这个目录的类型和写入边界，所以不建议直接创建多个 AI 岗位。

现在草稿和确认版边界还不够清楚。多个 AI 同时协作时，可能把草稿当成最终成果，或误改已经确认的内容。

参考

需要完整边界、输出格式和后续 CLI 要求时，读取：

../starworkDoctor-spec.md

需要更产品化的回复模板、术语翻译或项目中心候选示例时，读取：

references/response-guide.md
references/hub-upgrade.md
references/rules-extraction-guide.md
references/agent-rules-template.md

不要在 skill 内重复维护完整 schema，避免和 SPEC 漂移。

产品边界

starwork doctor = 探测器
starworkDoctor skill = 诊断师 + 升级蓝图设计师
starwork upgrade = 蓝图执行器

话术原则

starworkDoctor 的产品气质是“温和诊断师”，不是严格 linter。

• 开场避免失败感：不要说“你的工作区不合格”，应说“这个目录还不是标准 StarWork 工作台，但已经有一些可升级信号”。
• 第一屏必须先给人话结论：能不能接入、会不会移动旧目录、下一步是什么。
• 第一次出现 workspace state 时，解释为“StarWork 工作台身份证”。
• 分开说明 Core fit 和 upgrade readiness：目录逻辑贴近不等于可以立刻升级。
• 所有判断分三类表达：我看到的事实、我推测的角色、需要你确认的地方。
• 角色映射写成“候选角色 + 依据 + 置信度 + 需要确认什么”。
• 低置信度判断必须用柔和措辞，例如“可能承担”“更像是”“还不能只凭目录名确认”。
• 缺失项要翻译成工作后果，例如“新 Agent 进来时会比较难判断先读哪里”。
• 升级建议围绕“无损补齐”：保留原目录名，只补 StarWork state 和 Agent 入口规则，不移动、不删除、不覆盖历史内容。
• 需要用户回答的问题最多 3 个，只问会影响 blueprint 的语义。

推荐开场：

我先把它当作“历史工作区候选”来看。当前它还不是标准 StarWork 工作台，但目录里已经有资料、成果或推进痕迹，适合先走无损诊断路线。

推荐不确定表达：

“成稿/”很可能是正式成果区，但我还不能只凭目录名确认。需要你确认：这里是否只放已经认可的最终版本？

推荐缺失表达：

现在缺少一个稳定的“当前工作入口”。这不代表目录有问题，只是新 Agent 进来时会比较难判断下一步该接哪里。

工作流程

Step 1：运行 doctor 探测

优先执行：

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 判断当作最终诊断。

如果用户指定了宿主，或你从目录里看到宿主痕迹，再追加宿主诊断：

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 工作台”时，才进入升级设计。

只问会影响升级蓝图的问题：

• 哪个目录是正式成果 / 确认事实源？
• 哪个目录是当前工作 / 日常推进区？
• 哪些目录是只读参考资料？
• 是否需要事项机制？
• 对项目中心候选：哪个目录是项目登记、跨项目协调和回写待审？
• 希望保留旧目录名，还是逐步标准化？

推荐问法：

未来你希望 Agent 把哪里当成“不能乱改的正式成果”？

你平时真正干活的地方在哪里？比如推进事项、写草稿、放待办、记录阶段判断。

Step 7：生成升级蓝图

默认策略：

preserve-names

也就是保留用户已有目录名，通过 .starwork/workspace.json 和 Agent 规则建立 StarWork Core 映射。

默认 base：

• 单项目旧模板：按 project + project + general 接入；如果 doctor 识别到 single-light 或 local-starter，只把它们当作历史信号
• 多线推进旧模板：project + project + general
• 项目中心候选：hub + hub + pack:null

推荐输出目录：

<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 写：

"generated_by": "starworkDoctor"

蓝图执行命令：

starwork upgrade --target <workspace> --blueprint <workspace>-upgrade/upgrade-blueprint.json --dry-run

用户确认后：

starwork upgrade --target <workspace> --blueprint <workspace>-upgrade/upgrade-blueprint.json --yes
starwork doctor --target <workspace>

报告结构

诊断模式：

## 诊断结论

## 我看到的事实

## 我推测的角色

## Core 逻辑贴近程度

## 缺失和风险

## 整理升级建议

## 需要你确认的问题

升级设计模式：

## 升级判断

## 用户已确认的目录语义

## 升级策略

## 生成的 blueprint 文件

## dry-run 命令

## 执行前请再次确认

机器可读建议

如果需要给 CLI 或后续流程使用，可以附加：

{
  "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；只生成可注入的短规则片段。
• 不把旧规则原文无筛选地塞进新规则槽；必须先提炼、分类和标注来源。

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

### 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

### 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

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.

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:

这个目录更像“主库 / 多项目中枢”候选，而不是普通单项目旧模板。它已经有共享身份、教训、知识、skills、项目登记和回写待审入口。建议按 Hub preserve-names 方式无损接入：保留 `projects/`、`knowledge/`、`skills/` 等原名，只补 StarWork 工作台身份证和 Agent 边界规则。

Avoid:

建议按 project 升级。

Blueprint Defaults

For a confirmed Hub-like main repository:

{
  "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:

[
  { "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:

[
  { "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.

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:

结论：这个目录可以接入 StarWork，但现在还缺“工作台身份证”。
安全性：建议无损接入，不移动、不改名、不覆盖历史目录。
下一步：如果你确认关键目录语义，我会先生成 dry-run blueprint，只预览不写入。

For an existing healthy StarWork workspace:

结论：这个目录已经是健康的 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:

- `projects/`：候选角色是项目登记区。依据是存在 `projects/registry.json`；置信度高。需要确认：这里是否仍是主库维护的项目总登记？

Do not write only:

- `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/ 是否继续作为回写待审区？

Rules Extraction Guide

Use this reference when generating an upgrade blueprint for a workspace that already has Agent-facing rule documents.

The goal is not to copy old rules into the new AGENTS.md. The goal is to preserve the user's useful intent while making StarWork rules shorter, clearer, and checkable.

Read These Sources

Read only likely rule documents:

AGENTS.md
CLAUDE.md
.cursorrules
.cursor/rules/*
.trae/rules/*
README.md sections that clearly describe Agent behavior

Do not scan all business documents just to find possible rules.

Classify Old Rules

Classify each meaningful rule into one of five buckets:

What Counts As A Rule

Valid rules usually say:

• Read this first.
• Write here, not there.
• Treat this folder as read-only.
• Ask before changing this type of file.
• Use this command before committing.
• Do not overwrite or delete this category of content.

Not rules:

• Project history.
• Product pitch.
• Meeting notes.
• Long explanations.
• Low-confidence guesses.
• Old implementation details that no longer affect behavior.

Required Upgrade Outputs

When generating an upgrade blueprint, produce:

rules/core-boundaries.md
rules/user-preserved-rules.md
rules/rule-conflicts.md
notes/original-rules-summary.md

If no useful old rules exist, say so clearly and omit the user.preserved.* injection action.

Injection Policy

Only inject concise rule fragments:

{
  "type": "inject_agent_rules",
  "target": "AGENTS.md",
  "from": "rules/user-preserved-rules.md",
  "slot": "user.preserved.original_rules"
}

Never generate a full replacement AGENTS.md.

Conflict Policy

Do not silently choose between conflicting rules.

Examples:

• Old rule says 输出/ is final, but user confirmed 成稿/ as final.
• Old rule says to edit knowledge/, but StarWork treats it as Hub read-only.
• Old rule says all project notes go into README.md, but StarWork requires current work entry.

Put these into rules/rule-conflicts.md and ask the user at most three questions.