mdk-skills 2.2.11 → 2.2.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdk-skills",
-  "version": "2.2.11",
+  "version": "2.2.13",
   "description": "mdk-engineer - 沉稳靠谱的前端开发助手 Claude Skills 配置包，一键注入 .claude/ 技能目录和 CLAUDE.md 人设配置",
   "author": "XiaoMa",
   "license": "MIT",

package/scripts/web-ui/server.js

@@ -497,10 +497,21 @@ async function handleApi(req, res) {
         }
       }
 
+      // README.md 缺失状态（独立于骨架文件）
+      let readmeStatus = null;
+      if (sourcePath) {
+        const skillsDir = path.join(sourcePath, ".claude", "skills");
+        readmeStatus = {
+          root: fs.existsSync(path.join(sourcePath, "README.md")),
+          skills: fs.existsSync(path.join(skillsDir, "README.md")),
+        };
+      }
+
       return sendJSON(res, {
         connected: !!sourcePath,
         path: sourcePath,
         needsInit,
+        readmeStatus,
       });
     }
 
@@ -668,7 +679,109 @@ async function handleApi(req, res) {
         }
       }
 
-      return sendJSON(res, { ok: true, ...created });
+      // README.md 缺失状态
+      const readmeStatus = {
+        root: fs.existsSync(path.join(sourcePath, "README.md")),
+        skills: fs.existsSync(path.join(skillsDir, "README.md")),
+      };
+
+      return sendJSON(res, { ok: true, ...created, readmeStatus });
+    }
+
+    // POST /api/readme/create — 创建 README.md 文档
+    if (method === "POST" && pathname === "/api/readme/create") {
+      const body = await parseBody(req);
+      const settings = readSettings();
+      const sourcePath = settings._skill_source;
+      if (!sourcePath) return sendJSON(res, { error: "未绑定本地源" }, 400);
+
+      const { root, skills, projectName, teamName } = body;
+      const name = projectName || "我的技能仓库";
+      const team = teamName || "未设定";
+      const created = [];
+      const skipped = [];
+
+      // 获取技能列表
+      const skillsDir = path.join(sourcePath, ".claude", "skills");
+      const skillNames = fs.existsSync(skillsDir)
+        ? core.listSkillDirs(skillsDir)
+        : [];
+      const skillsList = skillNames.length
+        ? skillNames.map((s) => `- \`${s}\``).join("\n")
+        : "<!-- 暂无技能 -->";
+
+      // 根目录 README.md
+      if (root) {
+        const rootPath = path.join(sourcePath, "README.md");
+        if (!fs.existsSync(rootPath)) {
+          const tmpl = `# ${name}
+
+> 维护团队：${team}
+
+## 简介
+
+<!--
+在这里写这个技能仓库的简介。
+
+示例：
+本仓库包含面向 mdk-engineer 的前端开发技能集，涵盖 Vue3 组件开发、Chrome DevTools 使用、性能优化等方向。
+-->
+
+## 技能列表
+
+${skillsList}
+
+## 使用方式
+
+本仓库通过 mdk-skills 管理技能，连接本地源后即可在 Web UI 中查看和安装技能。
+
+## License
+
+<!-- 许可证信息 -->
+`;
+          fs.writeFileSync(rootPath, tmpl, "utf-8");
+          created.push("README.md");
+        } else {
+          skipped.push("README.md");
+        }
+      }
+
+      // skills/README.md
+      if (skills) {
+        const skillsReadmePath = path.join(skillsDir, "README.md");
+        if (!fs.existsSync(skillsReadmePath)) {
+          const tmpl = `# 技能说明
+
+## 快速开始
+
+<!--
+安装 mdk-skills 后连接本仓库，即可在 Web UI 中查看所有技能。
+-->
+
+## 场景建议
+
+<!--
+这里可以写哪些技能适合一起使用，不同开发场景下的推荐组合。
+
+示例：
+- 日常开发：启用代码格式化、ESLint 校验、Git 辅助
+- 性能优化：启用 Lighthouse、Bundle Analysis
+-->
+
+## 注意事项
+
+<!--
+技能使用过程中的注意事项。
+-->
+`;
+          fs.writeFileSync(skillsReadmePath, tmpl, "utf-8");
+          created.push("skills/README.md");
+        } else {
+          skipped.push("skills/README.md");
+        }
+      }
+
+      return sendJSON(res, { ok: true, created, skipped });
     }
 
     // GET /api/diagnose — 健康检查

package/scripts/web-ui/src/App.vue

@@ -26,7 +26,9 @@
 
           <!-- 内容区 -->
           <n-layout-content class="app-content">
-            <router-view @refresh="loadStatus" />
+            <transition name="fade" mode="out-in">
+              <router-view @refresh="loadStatus" />
+            </transition>
           </n-layout-content>
         </n-layout>
       </n-config-provider>
@@ -100,4 +102,14 @@ onMounted(loadStatus);
 
 <style>
 @import "./styles/main.css";
+
+.fade-enter-active,
+.fade-leave-active {
+  transition: opacity 0.2s ease;
+}
+
+.fade-enter-from,
+.fade-leave-to {
+  opacity: 0;
+}
 </style>

package/scripts/web-ui/src/api/skills.js

@@ -101,3 +101,10 @@ export function getClaudeMd() {
 export function getSkillReadme(name) {
   return request("/skills/" + encodeURIComponent(name) + "/readme");
 }
+
+export function createReadme(data) {
+  return request("/readme/create", {
+    method: "POST",
+    body: JSON.stringify(data),
+  });
+}

package/scripts/web-ui/src/views/ReadmeView.vue

@@ -9,8 +9,10 @@
     </div>
 
     <n-spin :show="loading">
-      <div v-if="content" class="markdown-content" v-html="rendered" />
-      <n-empty v-else description="暂无 CLAUDE.md 文档" />
+      <transition name="fade">
+        <div v-if="content" class="markdown-content" v-html="rendered" />
+        <n-empty v-else-if="loaded" description="暂无 CLAUDE.md 文档" />
+      </transition>
     </n-spin>
   </div>
 </template>
@@ -45,6 +47,7 @@ marked.use({
 });
 
 const loading = ref(false);
+const loaded = ref(false);
 const content = ref(null);
 const rendered = ref("");
 
@@ -66,6 +69,7 @@ function renderMd(text) {
 
 async function loadClaudeMd() {
   loading.value = true;
+  loaded.value = false;
   try {
     const res = await getClaudeMd();
     if (res.content) {
@@ -79,6 +83,7 @@ async function loadClaudeMd() {
     content.value = null;
   } finally {
     loading.value = false;
+    loaded.value = true;
   }
 }
 
@@ -97,4 +102,14 @@ onMounted(loadClaudeMd);
   font-size: 20px;
   font-weight: 600;
 }
+
+.fade-enter-active,
+.fade-leave-active {
+  transition: opacity 0.2s ease;
+}
+
+.fade-enter-from,
+.fade-leave-to {
+  opacity: 0;
+}
 </style>

package/scripts/web-ui/src/views/Settings.vue

@@ -31,6 +31,18 @@
         >
           <template #prefix>📁</template>
         </n-input>
+
+        <!-- 独立于 init：仅 README.md 缺失时的创建入口 -->
+        <n-alert
+          v-if="sourceInfo.connected && sourceInfo.needsInit === false && hasReadmeMissing"
+          type="info"
+          :bordered="false"
+          class="init-alert"
+        >
+          <template #header>缺少 README.md 文档</template>
+          创建后将生成模板文件，可在对应目录中自行编辑
+        </n-alert>
+
         <div class="action-buttons">
           <n-button
             v-if="!sourceInfo.connected"
@@ -56,6 +68,13 @@
           >
             同步到仓库
           </n-button>
+          <n-button
+            v-if="sourceInfo.connected && sourceInfo.needsInit === false && hasReadmeMissing"
+            ghost
+            @click="onShowCreateReadme"
+          >
+            创建文档
+          </n-button>
           <n-button
             v-if="sourceInfo.connected"
             type="error"
@@ -69,6 +88,51 @@
       </div>
     </n-card>
 
+    <!-- 创建 README.md 对话框 -->
+    <n-modal
+      v-model:show="showReadmeDialog"
+      title="创建文档"
+      preset="card"
+      style="width: 520px"
+      :mask-closable="false"
+    >
+      <div class="readme-dialog-desc">检测到缺少以下文档，是否创建？</div>
+
+      <n-checkbox v-model:checked="readmeForm.root" class="readme-checkbox">
+        <div class="readme-checkbox-content">
+          <span class="readme-checkbox-title">根目录 README.md</span>
+          <span class="readme-checkbox-desc">仪表盘 → "仓库说明"折叠面板，适合写项目简介、维护团队、许可证</span>
+        </div>
+      </n-checkbox>
+
+      <n-checkbox v-model:checked="readmeForm.skills" class="readme-checkbox">
+        <div class="readme-checkbox-content">
+          <span class="readme-checkbox-title">.claude/skills/README.md</span>
+          <span class="readme-checkbox-desc">场景切换 → "技能说明"折叠面板，适合写使用指南、场景搭配建议</span>
+        </div>
+      </n-checkbox>
+
+      <n-divider />
+
+      <n-form label-placement="top">
+        <n-form-item label="项目名称（选填）">
+          <n-input v-model:value="readmeForm.projectName" placeholder="我的技能仓库" />
+        </n-form-item>
+        <n-form-item label="维护团队（选填）">
+          <n-input v-model:value="readmeForm.teamName" placeholder="未设定" />
+        </n-form-item>
+      </n-form>
+
+      <template #footer>
+        <n-space justify="end">
+          <n-button @click="showReadmeDialog = false">跳过</n-button>
+          <n-button type="primary" :loading="creatingReadme" @click="onCreateReadme">
+            创建
+          </n-button>
+        </n-space>
+      </template>
+    </n-modal>
+
     <!-- 健康检查 -->
     <n-card title="健康检查" size="small" class="section">
       <template #header-extra>
@@ -100,7 +164,7 @@
 </template>
 
 <script setup>
-import { ref, onMounted } from "vue";
+import { ref, computed, onMounted } from "vue";
 import { useMessage } from "naive-ui";
 import {
   CheckmarkCircleOutline,
@@ -113,6 +177,7 @@ import {
   syncSource,
   initSource,
   diagnose,
+  createReadme,
 } from "../api/skills";
 
 const emit = defineEmits(["refresh"]);
@@ -127,6 +192,21 @@ const disconnecting = ref(false);
 const diagnosing = ref(false);
 const diagnosis = ref([]);
 
+// 创建 README.md 对话框
+const showReadmeDialog = ref(false);
+const creatingReadme = ref(false);
+const readmeForm = ref({
+  root: true,
+  skills: true,
+  projectName: "",
+  teamName: "",
+});
+
+const hasReadmeMissing = computed(() => {
+  if (!sourceInfo.value.readmeStatus) return false;
+  return !sourceInfo.value.readmeStatus.root || !sourceInfo.value.readmeStatus.skills;
+});
+
 async function loadSource() {
   sourceInfo.value = await getSource();
 }
@@ -175,6 +255,17 @@ async function onInit() {
       if (res.settings) parts.push("settings.json");
       if (res.metaFiles > 0) parts.push(`${res.metaFiles} 个 .meta.json`);
       message.success(`初始化完成：${parts.join("、") || "无缺失文件"}`);
+
+      // 检测 README.md 缺失情况，弹创建对话框
+      if (res.readmeStatus) {
+        const anyMissing = !res.readmeStatus.root || !res.readmeStatus.skills;
+        if (anyMissing) {
+          readmeForm.value.root = !res.readmeStatus.root;
+          readmeForm.value.skills = !res.readmeStatus.skills;
+          showReadmeDialog.value = true;
+        }
+      }
+
       await loadSource();
       emit("refresh");
     } else {
@@ -187,6 +278,35 @@ async function onInit() {
   }
 }
 
+async function onCreateReadme() {
+  creatingReadme.value = true;
+  try {
+    const res = await createReadme({
+      root: readmeForm.value.root,
+      skills: readmeForm.value.skills,
+      projectName: readmeForm.value.projectName.trim(),
+      teamName: readmeForm.value.teamName.trim(),
+    });
+    if (res.ok) {
+      const parts = res.created || [];
+      message.success(`已创建：${parts.join("、") || "无"}`);
+      showReadmeDialog.value = false;
+    } else {
+      message.error(res.error || "创建失败");
+    }
+  } catch {
+    message.error("创建失败");
+  } finally {
+    creatingReadme.value = false;
+  }
+}
+
+function onShowCreateReadme() {
+  readmeForm.value.root = !sourceInfo.value.readmeStatus?.root;
+  readmeForm.value.skills = !sourceInfo.value.readmeStatus?.skills;
+  showReadmeDialog.value = true;
+}
+
 async function onDisconnect() {
   disconnecting.value = true;
   try {
@@ -259,4 +379,32 @@ onMounted(loadSource);
   color: #d03050;
   font-size: 13px;
 }
+
+.readme-dialog-desc {
+  margin-bottom: 16px;
+  font-size: 14px;
+  color: #555;
+}
+
+.readme-checkbox {
+  display: flex;
+  align-items: flex-start;
+  margin-bottom: 12px;
+}
+
+.readme-checkbox-content {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.readme-checkbox-title {
+  font-size: 14px;
+  font-weight: 500;
+}
+
+.readme-checkbox-desc {
+  font-size: 12px;
+  color: #999;
+}
 </style>