@geminilight/mindos 0.5.7 → 0.5.8

package/README.md

@@ -48,21 +48,23 @@ MindOS is a **Human-AI Collaborative Mind System**—a local-first knowledge bas
 > Help me execute the XXX SOP from MindOS.
 > ```
 
-## 🧠 Core Value: Human-AI Shared Mind
+## 🧠 Human-AI Shared Mind
 
-**1. Global Sync — Break Memory Silos**
+> No more fragmented memory, no more black-box behavior, no more lost experience.
 
-Traditional notes are scattered across tools and APIs, so agents miss your real context when it matters. MindOS turns your local knowledge into one MCP-ready source, so every agent can sync your Profile, SOPs, and live working memory.
+**1. Global Sync — Breaking Memory Silos**
 
-**2. Transparent and Controllable — Eliminate Memory Black Boxes**
+Each Agent keeps its own memory — switching tools means manually hauling context. **MindOS lets all Agents share one knowledge base via MCP and Skills — record once, reuse everywhere.**
 
-Most assistant memory lives in black boxes, leaving humans unable to inspect or correct how decisions are made. MindOS writes retrieval and execution traces into local plain text, so you can audit, intervene, and improve continuously.
+**2. Transparent & Controllable — No More Black Boxes**
+
+What did your Agent remember? Is it even correct? You have no way to know. **MindOS saves every read/write as local plain text — humans can audit, correct, and delete in the GUI.**
 
 **3. Symbiotic Evolution — Experience Flows Back as Instructions**
 
-Static documents are hard to synchronize and weak as execution systems in real human-agent collaboration. MindOS makes notes agent-ready and reference-linked, so daily writing naturally becomes executable workflows that evolve with you.
+All that experience from your conversations — gone the moment you close the window. **MindOS auto-distills conversation experience into Skills/SOPs. Notes are instructions. The knowledge base gets better with use.**
 
-> **Foundation:** Local-first by default - all data stays in local plain text for privacy, ownership, and speed.
+> **Foundation:** Local-first by default — all data stays in local plain text for privacy, ownership, and speed.
 
 ## ✨ Features
 
@@ -80,7 +82,7 @@ Static documents are hard to synchronize and weak as execution systems in real h
 
 **Infrastructure**
 
-- **Reference Sync**: keep cross-file status and context aligned via links/backlinks.
+- **Security**: Bearer Token auth, path sandboxing, INSTRUCTION.md write-protection, atomic writes.
 - **Knowledge Graph**: visualize relationships and dependencies across notes.
 - **Git Time Machine**: track every edit, audit history, and roll back safely.
 - **Cross-Device Sync**: auto-commit, push, and pull via Git — edits on one device appear on all others within minutes.

package/README_zh.md

@@ -48,19 +48,21 @@ MindOS 是一个**人机协同心智系统**——基于本地优先的协作知
 > 帮我执行 MindOS 里的 XXX 工作流。
 > ```
 
-## 🧠 核心价值：人机共享心智
+## 🧠 人机共享心智
+
+> 记忆不再割裂，行为不再黑箱，经验不再断流。
 
 **1. 全局同步 — 打破记忆割裂**
 
-传统笔记分散在不同工具和接口中，Agent 在关键时刻拿不到你的真实上下文。MindOS 把本地知识统一为 MCP 可读的单一来源，让所有 Agent 同步你的 Profile、SOP 与实时记忆。
+多个 Agent 各记各的，切换工具靠人工搬运上下文。**MindOS 通过 MCP 和 Skill 让所有 Agent 共享同一份知识库——一处记录，全局复用。**
 
 **2. 透明可控 — 消除记忆黑箱**
 
-多数助手记忆封闭在黑箱里，人类难以审查和纠正决策过程。MindOS 将检索与执行轨迹沉淀为本地纯文本，让你可以持续审计、干预与优化。
+Agent 记了什么、记对没有，用户无从知晓。**MindOS 将每次读写沉淀为本地纯文本，人类可在 GUI 中审查、修正、删除。**
 
 **3. 共生演进 — 经验回流为指令**
 
-静态文档难同步，也难在真实人机协作中承担执行系统角色。MindOS 让笔记天然成为 Agent 可执行的指令，通过引用链接组织知识，日常记录自然变成可执行工作流并持续进化。
+对话里攒下的经验，关掉窗口就散了。**MindOS 自动将对话经验沉淀为 Skill/SOP，笔记即指令，知识库越用越好。**
 
 > **底层原则：** 默认本地优先，全部数据以本地纯文本保存，兼顾隐私、主权与性能。
 
@@ -80,7 +82,7 @@ MindOS 是一个**人机协同心智系统**——基于本地优先的协作知
 
 **基础设施**
 
-- **引用同步**：通过引用与反向链接保持跨文件状态一致。
+- **安全防线**：Bearer Token 认证、路径沙箱、INSTRUCTION.md 写保护、原子写入。
 - **知识图谱**：可视化笔记间关系与依赖。
 - **Git 时光机**：记录修改历史，支持审计与安全回滚。
 - **跨设备同步**：通过 Git 自动 commit、push、pull —— 一台设备的编辑几分钟内同步到所有设备。

package/app/app/api/mcp/install-skill/route.ts

@@ -15,7 +15,7 @@ const UNIVERSAL_AGENTS = new Set([
 ]);
 
 // Agents that do NOT support Skills at all
-const SKILL_UNSUPPORTED = new Set(['claude-desktop']);
+const SKILL_UNSUPPORTED = new Set<string>([]);
 
 // MCP agent key → npx skills agent name (for non-universal agents)
 const AGENT_NAME_MAP: Record<string, string> = {

package/app/lib/mcp-agents.ts

@@ -29,16 +29,6 @@ export const MCP_AGENTS: Record<string, AgentDef> = {
     presenceCli: 'claude',
     presenceDirs: ['~/.claude/'],
   },
-  'claude-desktop': {
-    name: 'Claude Desktop',
-    project: null,
-    global: process.platform === 'darwin'
-      ? '~/Library/Application Support/Claude/claude_desktop_config.json'
-      : '~/.config/Claude/claude_desktop_config.json',
-    key: 'mcpServers',
-    preferredTransport: 'http',
-    presenceDirs: ['~/Library/Application Support/Claude/', '~/.config/Claude/'],
-  },
   'cursor': {
     name: 'Cursor',
     project: '.cursor/mcp.json',

package/bin/lib/build.js

@@ -65,6 +65,17 @@ function writeDepsStamp() {
   }
 }
 
+/** Critical packages that must exist after npm install for the app to work. */
+const CRITICAL_DEPS = ['next', '@next/env', 'react', 'react-dom'];
+
+function verifyDeps() {
+  const nm = resolve(ROOT, 'app', 'node_modules');
+  for (const dep of CRITICAL_DEPS) {
+    if (!existsSync(resolve(nm, dep, 'package.json'))) return false;
+  }
+  return true;
+}
+
 export function ensureAppDeps() {
   const appNext = resolve(ROOT, 'app', 'node_modules', 'next', 'package.json');
   const needsInstall = !existsSync(appNext) || depsChanged();
@@ -90,5 +101,19 @@ export function ensureAppDeps() {
     : 'Installing app dependencies (first run)...\n';
   console.log(yellow(label));
   run('npm install --prefer-offline --no-workspaces', resolve(ROOT, 'app'));
+
+  // Verify critical deps — npm tar extraction can silently fail (ENOENT race)
+  if (!verifyDeps()) {
+    console.log(yellow('Some dependencies are incomplete, retrying with clean install...\n'));
+    const nm = resolve(ROOT, 'app', 'node_modules');
+    rmSync(nm, { recursive: true, force: true });
+    run('npm install --no-workspaces', resolve(ROOT, 'app'));
+    if (!verifyDeps()) {
+      console.error(red('\n✘ Failed to install dependencies after retry.\n'));
+      console.error('  Try manually: cd ' + resolve(ROOT, 'app') + ' && rm -rf node_modules && npm install');
+      process.exit(1);
+    }
+  }
+
   writeDepsStamp();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geminilight/mindos",
-  "version": "0.5.7",
+  "version": "0.5.8",
   "description": "MindOS — Human-Agent Collaborative Mind System. Local-first knowledge base that syncs your mind to all AI Agents via MCP.",
   "keywords": [
     "mindos",
@@ -42,6 +42,16 @@
     "!app/.claude",
     "!app/__tests__",
     "!app/**/*.bak",
+    "!app/vitest.config.ts",
+    "!app/eslint.config.mjs",
+    "!app/tsconfig.tsbuildinfo",
+    "!app/data/pages",
+    "!assets/node_modules",
+    "!assets/package-lock.json",
+    "!assets/package.json",
+    "!assets/capture-demo.mjs",
+    "!assets/demo-flow.html",
+    "!assets/demo-flow-zh.html",
     "!mcp/node_modules",
     "!mcp/dist"
   ],

package/skills/project-wiki/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: project-wiki
+description: "组织和维护 Vibe Coding 项目的 wiki 文档体系。当用户要求初始化/重构 wiki 结构、进入新项目且 wiki/ 不存在、或需要诊断和修复文档腐化时触发。"
+---
+
+# Project Wiki Skill
+
+为 Vibe Coding 项目（人类描述意图，Agent 写代码）生成和维护结构化 wiki。wiki 是 Agent 的输入物料，直接决定输出质量。
+
+---
+
+## 执行流程
+
+### 初始化（wiki/ 不存在或为空）
+
+1. **扫描** `wiki/` 目录，列出已有文件
+2. **对照必要文件清单**（见下方"文件体系"），识别缺失项
+3. **与用户确认**将要创建的文件列表
+4. **生成骨架**：从本 Skill 的 `assets/` 目录读取对应模板，填入用户上下文（不确定的部分留 `<!-- TODO: ... -->` 占位）
+5. **更新导航**：如已有 `01-project-roadmap.md`，追加新阶段索引行
+6. **标记新鲜度**：每个生成的文件头部加 `<!-- Last verified: YYYY-MM-DD | Current stage: X -->`
+7. **注入维护规则**：检查项目 `CLAUDE.md` 中是否已有 wiki 维护规则。已有则跳过或合并差异；没有则**追加**（不替换整个文件）
+
+### 重构 / 更新（wiki/ 已有文件）
+
+1. **扫描** `wiki/` 下所有文件，检查编号前缀、新鲜度标记
+2. **诊断**：缺编号前缀？信息重叠？文件过大需拆分？已完结 stage 未归档？内容与代码不一致？
+3. **生成改动清单**（重命名 / 合并 / 拆分 / 归档 / 更新内容），与用户确认
+4. **执行改动**
+5. **验证一致性**：文件间引用链接有效、roadmap 索引与实际文件对应
+6. **检查维护规则**：确认项目 `CLAUDE.md` 中已有 wiki 维护规则，缺失则追加（不替换整个文件）
+
+---
+
+## 文件体系
+
+### 核心模型：Why / What / How / Look × 全局 / 阶段
+
+| | 全局（稳定，新阶段才改） | 阶段（增量更新） |
+|---|---|---|
+| **Why** | `00-product-proposal.md` | — |
+| **What** | `01-project-roadmap.md` — 功能索引 | `1X-stage-X.md` — 设计决策 |
+| **How** | `02-system-architecture.md` — 架构 + 类型 | `1X-stage-X.md` — API、数据模型、受影响文件 |
+| **API** | `04-api-reference.md` — 完整 API 参考 | `1X-stage-X.md` — 新增 API 的设计决策 |
+| **Look** | `03-design-principle.md` — 视觉语言 | — |
+
+**关键规则：** stage 文件同时包含 What 和 How。一个功能的设计决策、API 契约、数据模型放在一个文件里。全局文件只做索引和导航，不重复 stage 的细节。
+
+### 规划层级
+
+| | Roadmap (`01`) | Backlog (`85`) |
+|---|---|---|
+| 时间跨度 | 月 / 季度级 | 周 / 迭代级 |
+| 粒度 | 方向、里程碑、大功能 | 具体任务、bug、小需求 |
+| 回答 | 我们要去哪里？ | 下一步做什么？ |
+
+**使用时机：** 开始任务前先对照 roadmap 确认阶段匹配，再从 backlog 取具体任务执行。任务完成后在 backlog 打勾，发版时从已完成条目整理写入 changelog。
+
+### 必要文件（第一梯队）
+
+| 编号 | 文件 | 写给谁 | 核心内容 |
+|------|------|--------|---------|
+| 00 | `product-proposal.md` | Agent + 你 | 产品愿景、产品定位、**不做什么**、目标用户、功能矩阵、路线图叙事 |
+| 01 | `project-roadmap.md` | Agent + 你 | 阶段总览表、全量功能索引（功能×状态×stage链接）、里程碑 |
+| 02 | `system-architecture.md` | Agent | 技术栈、目录结构、数据流、核心类型、环境变量（300-500 行） |
+
+### 按需文件（第二梯队）
+
+| 编号 | 文件 | 何时需要 |
+|------|------|---------|
+| 03 | `design-principle.md` | 有自定义视觉语言时（非默认 UI 库样式） |
+| 04 | `api-reference.md` | API 超过 5 条路由，或 stage 归档后仍需查 API 细节 |
+| 05 | `glossary.md` | 项目有领域术语，Agent 容易用错词或混用近义词 |
+| 06 | `conventions.md` | 有明确的编码偏好/约束（库选择、命名、错误处理模式等） |
+| 1X | `stage-X.md` | 功能复杂度超过一句话能说清（150-300 行） |
+| — | `task-spec-xxx.md` | 小功能 / 改进点的 spec，包含需求描述和验收标准；实现完成后归档或合并进对应 stage 文件 |
+| 80 | `known-pitfalls.md` | 踩坑即记，不等阶段结束 |
+| 81 | `development-guide.md` | 有非显而易见的配置要求时 |
+| 82 | `postmortem-*.md` | 多个 bug 互相关联、暴露系统性问题时（单点问题用 pitfalls，系统性问题用 postmortem） |
+| 84 | `design-exploration.md` | 有 UI 设计探索、原型记录等创意过程产物时 |
+| 85 | `backlog.md` | 有临时 bug、技术债、改进想法需要追踪时 |
+| 8X | `external-*.md` | 依赖外部系统私有数据格式时 |
+| 90 | `changelog.md` | 发版时从 `85-backlog.md` 已完成条目整理写入，面向用户描述变更，不记内部实现细节 |
+
+> 每个文件的详细说明和"为什么需要"的论证见 `references/file-reference.md`。
+
+### 目录结构与编号规范
+
+```
+wiki/
+├── 00-product-proposal.md        # Why
+├── 01-project-roadmap.md         # What（全局索引）
+├── 02-system-architecture.md     # How（全局）
+├── 03-design-principle.md        # Look（全局）
+├── 04-api-reference.md           # API（全局）
+├── 05-glossary.md                # 术语表（有领域术语时）
+├── 06-conventions.md             # 编码约定（有明确偏好时）
+├── 10-stage-a.md                 # 阶段文件
+├── 11-stage-b.md
+├── ...
+├── 80-known-pitfalls.md          # 辅助参考
+├── 81-development-guide.md
+├── 82-postmortem-*.md            # 系统性问题复盘（多 bug 关联时）
+├── 84-design-exploration.md      # 设计探索/原型记录（有 UI 探索时）
+├── 85-backlog.md                 # Bug、技术债、改进想法
+├── 90-changelog.md               # 日志
+└── archive/                      # 已完结阶段归档
+```
+
+| 区段 | 用途 |
+|------|------|
+| `00-09` | 全局文件，按阅读优先级排列 |
+| `10-79` | 阶段文件，按时间递增 |
+| `80-89` | 辅助参考文件 |
+| `90-99` | 日志类文件 |
+
+### Stage 文件生命周期
+
+阶段完全交付且后续阶段不再引用其 API/数据模型时 → 移入 `wiki/archive/`，`01-project-roadmap.md` 中保留索引行并标注 `[archived]`。
+
+**归档判断标准：** 同时满足以下两条才归档：① 该 stage 已完结超过一个阶段；② 当前及未来 stage 文件中无对它的跨引用。不确定时保留，宁可冗余不要断链。
+
+---
+
+## Agent 阅读顺序
+
+| 场景 | 路径 |
+|------|------|
+| 新对话 / 新功能 | `00-product-proposal` → `02-system-architecture` → 当前 `stage-X` |
+| 修 Bug | `02-system-architecture` → `80-known-pitfalls` → 相关 `stage-X` |
+| 修 Bug（反复出现） | `82-postmortem-*` → `02-system-architecture` → `80-known-pitfalls` → 相关 `stage-X` |
+| UI 调整 | `03-design-principle` → `02-system-architecture`（目录结构）→ 相关组件 |
+| 了解全貌 | `00-product-proposal` → `01-project-roadmap` → `02-system-architecture` |
+
+---
+
+## 文档编写规范
+
+1. **写给 Agent 的文档用结构化格式。** 表格 > 段落，代码块 > 文字描述，类型定义 > 自然语言。
+2. **写给自己的文档记决策不记细节。** "为什么选 X 不选 Y" > "X 的安装命令"。
+3. **一个信息只在一个地方维护。** 两处记录同一信息必然不一致。
+4. **Stage 文件是功能的唯一权威来源。** 全局文件只做索引。
+5. **标记新鲜度：** `<!-- Last verified: YYYY-MM-DD | Current stage: X | May be outdated after Stage Y -->`
+6. **宁可不写，不要写了不维护。** 过时文档比没文档更危险。
+7. **文件间引用用相对路径。** wiki 文件之间互引用 `./XX-filename.md#锚点` 格式，引用源码用 `../server/src/xxx.ts` 格式。
+8. **追求信息密度，不追求篇幅。** 具体标准：
+
+**内容取舍——写什么、不写什么：**
+- 写决策和约束（"用 dayjs，因为 moment 已废弃"），不写 Agent 能从源码读到的事实（"LoginForm 接受 onSubmit prop"）
+- 写跨模块关系（"A 通过 WebSocket 推送给 B"），不写模块内部显而易见的逻辑
+- 写"为什么不"（"不用 SSR，因为纯内网工具"），当"为什么是"显而易见时不写
+
+**表达密度——同一信息用最少字数传达：**
+- 一行表格能说清的，不展开成一段话
+- 不写铺垫句（"在这一节中我们将讨论..."）、不写总结句（"综上所述..."）、不复述上下文
+- 每句话删到"再删就丢信息"为止
+
+**膨胀信号——出现以下情况说明写多了：**
+- 一个 section 超过 20 行却没有代码块或表格
+- 同一个概念在两个文件中都有段落级展开
+- 读完一段话后能概括成一行表格而不丢失关键信息
+
+> 文档维护的投入信号和时机指南见 `references/writing-guide.md`。
+
+---
+
+## 日常维护规则
+
+Skill 触发时生成 wiki 结构，但 wiki 的日常同步发生在每次开发对话中。以下规则应在初始化完成后写入项目 `CLAUDE.md`，使 Agent 在正常开发流程中自动维护 wiki，无需反复触发本 skill。
+
+写入 CLAUDE.md 的内容（根据项目实际存在的 wiki 文件裁剪，只保留已创建的文件对应的行）：
+
+```markdown
+## Wiki 维护
+
+开发过程中，以下操作需要同步更新对应 wiki 文件：
+
+| 当你做了这件事 | 更新哪个文件 |
+|--------------|------------|
+| 新增/修改 API 路由 | `wiki/04-api-reference.md` 追加或修改对应条目 |
+| 完成一个 stage 的功能 | `wiki/01-project-roadmap.md` 对应行状态改为 ✅ |
+| 遇到非显而易见的坑 | `wiki/80-known-pitfalls.md` 追加一条（现象、原因、解法） |
+| 多个 bug 互相关联、暴露系统性问题 | 新建 `wiki/82-postmortem-*.md`（单点问题用 pitfalls，系统性问题用 postmortem） |
+| 架构变更（新模块、新数据流） | `wiki/02-system-architecture.md` 更新对应章节 |
+| 阶段全部交付 | `wiki/90-changelog.md` 补一笔（从 backlog 已完成条目整理） |
+| 发现 bug / 技术债 / 改进想法 | `wiki/85-backlog.md` 追加一条 |
+| 新增设计 token / 动效 | `wiki/03-design-principle.md` 追加对应条目 |
+| 出现新领域术语 | `wiki/05-glossary.md` 追加定义，防止 Agent 后续用词混乱 |
+| 重命名 / 移动 wiki 文件 | 同步更新所有引用该文件的链接 |
+
+**新建文件时机：**
+- 新功能复杂度超过一句话说清 → 新建 `wiki/1X-stage-X.md`
+- 小功能 / 改进点需要 spec → 新建 `wiki/task-spec-xxx.md`（实现完成后归档或合并进 stage 文件）
+
+**定期检查（每个阶段开始时）：**
+- 扫描 wiki/ 下所有文件，更新 `Last verified` 日期
+- 标出内容可能已过时的章节（加 `<!-- May be outdated -->` 注释）
+
+不需要在每次 commit 时都更新——在功能完成、API 变更、架构调整这些"节点"时同步即可。
+```
+
+---
+
+## 模板
+
+所有模板位于本 Skill 的 `assets/` 目录。生成文件时读取对应模板，填入项目上下文。
+
+| 模板文件 | 对应 wiki 文件 |
+|---------|---------------|
+| `product-proposal.tmpl.md` | `00-product-proposal.md` |
+| `project-roadmap.tmpl.md` | `01-project-roadmap.md` |
+| `system-architecture.tmpl.md` | `02-system-architecture.md` |
+| `design-principle.tmpl.md` | `03-design-principle.md` |
+| `api-reference.tmpl.md` | `04-api-reference.md` |
+| `glossary.tmpl.md` | `05-glossary.md` |
+| `conventions.tmpl.md` | `06-conventions.md` |
+| `stage-x.tmpl.md` | `1X-stage-X.md` |
+| `known-pitfalls.tmpl.md` | `80-known-pitfalls.md` |
+| `development-guide.tmpl.md` | `81-development-guide.md` |
+| `postmortem.tmpl.md` | `82-postmortem-*.md` |
+| `design-exploration.tmpl.md` | `84-design-exploration.md` |
+| `backlog.tmpl.md` | `85-backlog.md` |
+| `changelog.tmpl.md` | `90-changelog.md` |

package/skills/project-wiki/assets/api-reference.tmpl.md

@@ -0,0 +1,49 @@
+<!-- Last verified: YYYY-MM-DD | Current stage: — -->
+
+# API 参考
+
+> 设计决策见各 stage 文件，本文件只记录活跃 API 的完整契约。
+
+## 概览
+
+| 方法 | 路径 | 用途 | 引入阶段 |
+|------|------|------|---------|
+| <!-- TODO --> | <!-- TODO --> | <!-- TODO --> | <!-- TODO --> |
+
+---
+
+## <!-- TODO: API 分组名称 -->
+
+### `METHOD /api/path`
+
+<!-- TODO: 一句话说明用途 -->
+
+**请求：**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| <!-- TODO --> | <!-- TODO --> | <!-- TODO --> | <!-- TODO --> |
+
+```json
+{
+  // <!-- TODO: 请求体示例 -->
+}
+```
+
+**响应：**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| <!-- TODO --> | <!-- TODO --> | <!-- TODO --> |
+
+```json
+{
+  // <!-- TODO: 响应体示例 -->
+}
+```
+
+**错误码：**
+
+| 状态码 | 含义 |
+|--------|------|
+| <!-- TODO --> | <!-- TODO --> |

package/skills/project-wiki/assets/backlog.tmpl.md

@@ -0,0 +1,15 @@
+<!-- Last verified: YYYY-MM-DD | Current stage: — -->
+
+# Backlog
+
+> 临时 bug、技术债、改进想法。解决后移除或转入对应 stage 文件。
+
+## Bug
+
+- [ ] <!-- TODO -->
+
+## 技术债
+
+## 改进想法
+
+## 待验证

package/skills/project-wiki/assets/changelog.tmpl.md

@@ -0,0 +1,16 @@
+<!-- Last verified: YYYY-MM-DD | Current stage: — -->
+
+# 变更日志
+
+## Stage A — <!-- TODO: 主题 -->
+
+**日期：** <!-- TODO: YYYY-MM-DD -->
+
+### 新增
+- <!-- TODO -->
+
+### 变更
+- <!-- TODO -->
+
+### 关键决策
+- <!-- TODO: 为什么这样做 -->

package/skills/project-wiki/assets/conventions.tmpl.md

@@ -0,0 +1,29 @@
+<!-- Last verified: YYYY-MM-DD | Current stage: — -->
+
+# 编码约定
+
+> 项目级编码偏好和约束。Agent 写代码前参考此文件。
+
+## 库选择
+
+| 用途 | 使用 | 不使用 | 原因 |
+|------|------|--------|------|
+| <!-- TODO: e.g., 日期处理 --> | <!-- TODO: e.g., dayjs --> | <!-- TODO: e.g., moment --> | <!-- TODO --> |
+
+## 命名规范
+
+| 对象 | 规范 | 示例 |
+|------|------|------|
+| <!-- TODO: e.g., React 组件 --> | <!-- TODO: e.g., PascalCase --> | <!-- TODO: e.g., UserProfile --> |
+
+## 代码模式
+
+### 错误处理
+<!-- TODO: e.g., 统一用 Result 模式 / try-catch + 自定义 Error 类 -->
+
+### 类型约束
+<!-- TODO: e.g., 禁止 any，使用 unknown + 类型守卫 -->
+
+## 禁止项
+
+- <!-- TODO: e.g., 不使用 console.log 做日志，统一用 logger -->

package/skills/project-wiki/assets/design-exploration.tmpl.md

@@ -0,0 +1,26 @@
+<!-- Last verified: YYYY-MM-DD | Current stage: — -->
+
+# 设计探索
+
+> 记录 UI 设计探索、原型迭代、视觉方案对比等创意过程产物。不追求完整，有就记。
+
+## <!-- TODO: 探索主题 -->
+
+### 背景 / 目标
+
+<!-- TODO: 为什么要探索这个方向 -->
+
+### 方案对比
+
+| 方案 | 描述 | 优点 | 缺点 |
+|------|------|------|------|
+| A | <!-- TODO --> | <!-- TODO --> | <!-- TODO --> |
+| B | <!-- TODO --> | <!-- TODO --> | <!-- TODO --> |
+
+### 最终选择
+
+<!-- TODO: 选了哪个、为什么 -->
+
+### 参考 / 截图
+
+<!-- TODO: 参考链接、截图路径、灵感来源 -->

package/skills/project-wiki/assets/design-principle.tmpl.md

@@ -0,0 +1,48 @@
+<!-- Last verified: YYYY-MM-DD | Current stage: — -->
+
+# 设计原则
+
+## 设计哲学
+
+<!-- TODO: 一句话定义视觉方向，如"CRT 终端美学"或"极简留白" -->
+
+## 调色板
+
+| Token | 值 | 语义用途 |
+|-------|-----|---------|
+| `--primary` | <!-- TODO --> | <!-- TODO --> |
+| `--bg` | <!-- TODO --> | <!-- TODO --> |
+| `--text` | <!-- TODO --> | <!-- TODO --> |
+| `--success` | <!-- TODO --> | 成功状态 |
+| `--warning` | <!-- TODO --> | 警告状态 |
+| `--error` | <!-- TODO --> | 错误状态 |
+
+## 字体系统
+
+| 属性 | 值 |
+|------|-----|
+| 字体族 | <!-- TODO --> |
+| 基础字号 | <!-- TODO --> |
+| 字号阶梯 | <!-- TODO: e.g., 12 / 14 / 16 / 20 / 24 / 32 --> |
+| 行高 | <!-- TODO --> |
+
+## 间距与布局
+
+| 属性 | 值 |
+|------|-----|
+| 基准单位 | <!-- TODO: e.g., 4px --> |
+| 间距阶梯 | <!-- TODO: e.g., 4 / 8 / 12 / 16 / 24 / 32 / 48 --> |
+| 栅格 | <!-- TODO --> |
+| 响应式断点 | <!-- TODO --> |
+
+## 动效规范
+
+| 属性 | 值 |
+|------|-----|
+| 过渡时长 | <!-- TODO: e.g., 150ms / 300ms --> |
+| 缓动函数 | <!-- TODO --> |
+| 关键帧动画 | <!-- TODO --> |
+
+## 组件模式
+
+<!-- TODO: 卡片、面板、按钮等的通用视觉约束 -->

package/skills/project-wiki/assets/development-guide.tmpl.md

@@ -0,0 +1,38 @@
+<!-- Last verified: YYYY-MM-DD | Current stage: — -->
+
+# 开发指南
+
+## 环境要求
+
+| 依赖 | 版本 |
+|------|------|
+| <!-- TODO --> | <!-- TODO --> |
+
+## 快速启动
+
+```bash
+# 安装依赖
+<!-- TODO -->
+
+# 启动开发环境
+<!-- TODO -->
+```
+
+## 特殊配置
+
+<!-- TODO: 代理地址、特殊环境变量、构建顺序依赖等非显而易见的配置 -->
+
+## 构建与部署
+
+```bash
+# 生产构建
+<!-- TODO -->
+
+# 部署
+<!-- TODO -->
+```
+
+## 常见问题
+
+### <!-- TODO: 问题标题 -->
+<!-- TODO: 解决方法 -->

package/skills/project-wiki/assets/glossary.tmpl.md

@@ -0,0 +1,9 @@
+<!-- Last verified: YYYY-MM-DD | Current stage: — -->
+
+# 术语表
+
+> 统一项目中的领域术语，防止 Agent 用错词或混用近义词。
+
+| 术语 | 定义 | 不要混淆 |
+|------|------|---------|
+| <!-- TODO --> | <!-- TODO --> | <!-- TODO: 容易混淆的近义词 --> |

package/skills/project-wiki/assets/known-pitfalls.tmpl.md

@@ -0,0 +1,21 @@
+<!-- Last verified: YYYY-MM-DD | Current stage: — -->
+
+# 踩坑记录
+
+## API 集成
+
+### <!-- TODO: 现象标题 -->
+- **现象：** <!-- TODO -->
+- **原因：** <!-- TODO -->
+- **解决方案：** <!-- TODO -->
+- **教训：** <!-- TODO: 可迁移到其他模块的规则 -->
+
+## 前端
+
+## 文件系统
+
+## 进程生命周期
+
+## 并发 / 性能
+
+## 构建 / 部署