@geminilight/mindos 0.5.8 → 0.5.10

package/app/lib/mcp-agents.ts

@@ -93,6 +93,87 @@ export const MCP_AGENTS: Record<string, AgentDef> = {
     presenceCli: 'claude-internal',
     presenceDirs: ['~/.claude-internal/'],
   },
+  'iflow-cli': {
+    name: 'iFlow CLI',
+    project: '.iflow/settings.json',
+    global: '~/.iflow/settings.json',
+    key: 'mcpServers',
+    preferredTransport: 'stdio',
+    presenceCli: 'iflow',
+    presenceDirs: ['~/.iflow/'],
+  },
+  'kimi-cli': {
+    name: 'Kimi Code',
+    project: '.kimi/mcp.json',
+    global: '~/.kimi/mcp.json',
+    key: 'mcpServers',
+    preferredTransport: 'stdio',
+    presenceCli: 'kimi',
+    presenceDirs: ['~/.kimi/'],
+  },
+  'opencode': {
+    name: 'OpenCode',
+    project: null,
+    global: '~/.config/opencode/config.json',
+    key: 'mcpServers',
+    preferredTransport: 'stdio',
+    presenceCli: 'opencode',
+    presenceDirs: ['~/.config/opencode/'],
+  },
+  'pi': {
+    name: 'Pi',
+    project: '.pi/settings.json',
+    global: '~/.pi/agent/mcp.json',
+    key: 'mcpServers',
+    preferredTransport: 'stdio',
+    presenceCli: 'pi',
+    presenceDirs: ['~/.pi/'],
+  },
+  'augment': {
+    name: 'Augment',
+    project: '.augment/settings.json',
+    global: '~/.augment/settings.json',
+    key: 'mcpServers',
+    preferredTransport: 'stdio',
+    presenceCli: 'auggie',
+    presenceDirs: ['~/.augment/'],
+  },
+  'qwen-code': {
+    name: 'Qwen Code',
+    project: '.qwen/settings.json',
+    global: '~/.qwen/settings.json',
+    key: 'mcpServers',
+    preferredTransport: 'stdio',
+    presenceCli: 'qwen',
+    presenceDirs: ['~/.qwen/'],
+  },
+  'trae-cn': {
+    name: 'Trae CN',
+    project: '.trae/mcp.json',
+    global: process.platform === 'darwin'
+      ? '~/Library/Application Support/Trae CN/User/mcp.json'
+      : '~/.config/Trae CN/User/mcp.json',
+    key: 'mcpServers',
+    preferredTransport: 'stdio',
+    presenceCli: 'trae-cli',
+    presenceDirs: [
+      '~/Library/Application Support/Trae CN/',
+      '~/.config/Trae CN/',
+    ],
+  },
+  'roo': {
+    name: 'Roo Code',
+    project: '.roo/mcp.json',
+    global: process.platform === 'darwin'
+      ? '~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json'
+      : '~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json',
+    key: 'mcpServers',
+    preferredTransport: 'stdio',
+    presenceDirs: [
+      '~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/',
+      '~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/',
+    ],
+  },
 };
 
 /* ── MindOS MCP Install Detection ──────────────────────────────────────── */

package/bin/lib/gateway.js

@@ -1,9 +1,10 @@
 import { execSync } from 'node:child_process';
-import { existsSync, writeFileSync, rmSync, mkdirSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, rmSync, mkdirSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { homedir } from 'node:os';
-import { MINDOS_DIR, LOG_PATH, CLI_PATH, NODE_BIN } from './constants.js';
-import { green, red, dim, cyan } from './colors.js';
+import { MINDOS_DIR, LOG_PATH, CLI_PATH, NODE_BIN, CONFIG_PATH } from './constants.js';
+import { green, red, dim, cyan, yellow } from './colors.js';
+import { isPortInUse } from './port.js';
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
@@ -25,6 +26,18 @@ export async function waitForService(check, { retries = 10, intervalMs = 1000 }
   return check();
 }
 
+/**
+ * Wait until a port is free (no process listening).
+ * Returns true if port is free, false on timeout.
+ */
+export async function waitForPortFree(port, { retries = 30, intervalMs = 500 } = {}) {
+  for (let i = 0; i < retries; i++) {
+    if (!(await isPortInUse(port))) return true;
+    await new Promise(r => setTimeout(r, intervalMs));
+  }
+  return !(await isPortInUse(port));
+}
+
 export async function waitForHttp(port, { retries = 120, intervalMs = 2000, label = 'service' } = {}) {
   process.stdout.write(cyan(`  Waiting for ${label} to be ready`));
   for (let i = 0; i < retries; i++) {
@@ -194,10 +207,37 @@ const launchd = {
     console.log(green('\u2714 Service started'));
   },
 
-  stop() {
+  async stop() {
+    // Read ports before bootout so we can wait for them to be freed
+    let webPort = 3000, mcpPort = 8787;
+    try {
+      const config = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8'));
+      if (config.port) webPort = Number(config.port);
+      if (config.mcpPort) mcpPort = Number(config.mcpPort);
+    } catch {}
+
     try {
       execSync(`launchctl bootout gui/${launchctlUid()} ${LAUNCHD_PLIST}`, { stdio: 'inherit' });
     } catch { /* may not be running */ }
+
+    // launchctl bootout is async — wait for ports to actually be freed
+    let [webFree, mcpFree] = await Promise.all([
+      waitForPortFree(webPort),
+      waitForPortFree(mcpPort),
+    ]);
+    if (!webFree || !mcpFree) {
+      console.log(yellow('Ports still in use after bootout, force-killing...'));
+      const { stopMindos } = await import('./stop.js');
+      stopMindos();
+      // stopMindos() sends SIGTERM synchronously — wait for processes to exit
+      [webFree, mcpFree] = await Promise.all([
+        waitForPortFree(webPort),
+        waitForPortFree(mcpPort),
+      ]);
+      if (!webFree || !mcpFree) {
+        console.error(red('Warning: ports still in use after force-kill. Continuing anyway.'));
+      }
+    }
     console.log(green('\u2714 Service stopped'));
   },
 

package/bin/lib/mcp-agents.js

@@ -100,6 +100,87 @@ export const MCP_AGENTS = {
     presenceCli: 'claude-internal',
     presenceDirs: ['~/.claude-internal/'],
   },
+  'iflow-cli': {
+    name: 'iFlow CLI',
+    project: '.iflow/settings.json',
+    global: '~/.iflow/settings.json',
+    key: 'mcpServers',
+    preferredTransport: 'stdio',
+    presenceCli: 'iflow',
+    presenceDirs: ['~/.iflow/'],
+  },
+  'kimi-cli': {
+    name: 'Kimi Code',
+    project: '.kimi/mcp.json',
+    global: '~/.kimi/mcp.json',
+    key: 'mcpServers',
+    preferredTransport: 'stdio',
+    presenceCli: 'kimi',
+    presenceDirs: ['~/.kimi/'],
+  },
+  'opencode': {
+    name: 'OpenCode',
+    project: null,
+    global: '~/.config/opencode/config.json',
+    key: 'mcpServers',
+    preferredTransport: 'stdio',
+    presenceCli: 'opencode',
+    presenceDirs: ['~/.config/opencode/'],
+  },
+  'pi': {
+    name: 'Pi',
+    project: '.pi/settings.json',
+    global: '~/.pi/agent/mcp.json',
+    key: 'mcpServers',
+    preferredTransport: 'stdio',
+    presenceCli: 'pi',
+    presenceDirs: ['~/.pi/'],
+  },
+  'augment': {
+    name: 'Augment',
+    project: '.augment/settings.json',
+    global: '~/.augment/settings.json',
+    key: 'mcpServers',
+    preferredTransport: 'stdio',
+    presenceCli: 'auggie',
+    presenceDirs: ['~/.augment/'],
+  },
+  'qwen-code': {
+    name: 'Qwen Code',
+    project: '.qwen/settings.json',
+    global: '~/.qwen/settings.json',
+    key: 'mcpServers',
+    preferredTransport: 'stdio',
+    presenceCli: 'qwen',
+    presenceDirs: ['~/.qwen/'],
+  },
+  'trae-cn': {
+    name: 'Trae CN',
+    project: '.trae/mcp.json',
+    global: process.platform === 'darwin'
+      ? '~/Library/Application Support/Trae CN/User/mcp.json'
+      : '~/.config/Trae CN/User/mcp.json',
+    key: 'mcpServers',
+    preferredTransport: 'stdio',
+    presenceCli: 'trae-cli',
+    presenceDirs: [
+      '~/Library/Application Support/Trae CN/',
+      '~/.config/Trae CN/',
+    ],
+  },
+  'roo': {
+    name: 'Roo Code',
+    project: '.roo/mcp.json',
+    global: process.platform === 'darwin'
+      ? '~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json'
+      : '~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json',
+    key: 'mcpServers',
+    preferredTransport: 'stdio',
+    presenceDirs: [
+      '~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/',
+      '~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/',
+    ],
+  },
 };
 
 export function detectAgentPresence(agentKey) {

package/bin/lib/mcp-install.js

@@ -3,7 +3,7 @@ import { resolve } from 'node:path';
 import { CONFIG_PATH } from './constants.js';
 import { bold, dim, cyan, green, red, yellow } from './colors.js';
 import { expandHome } from './utils.js';
-import { MCP_AGENTS } from './mcp-agents.js';
+import { MCP_AGENTS, detectAgentPresence } from './mcp-agents.js';
 
 export { MCP_AGENTS };
 
@@ -76,7 +76,7 @@ async function interactiveSelect(title, options) {
 async function interactiveMultiSelect(title, options) {
   return new Promise((resolve) => {
     let cursor = 0;
-    const selected = new Set();
+    const selected = new Set(options.map((o, i) => o.preselect ? i : -1).filter(i => i >= 0));
     const { stdin, stdout } = process;
 
     function render() {
@@ -85,7 +85,7 @@ async function interactiveMultiSelect(title, options) {
     }
 
     function draw() {
-      stdout.write(`${bold(title)}  ${dim('(↑↓ move, Space select, A all, Enter confirm)')}\n`);
+      stdout.write(`${bold(title)}  ${dim('(↑↓ move, Space select, D detected, A all, Enter confirm)')}\n`);
       for (let i = 0; i < options.length; i++) {
         const o = options[i];
         const check = selected.has(i) ? green('✔') : dim('○');
@@ -120,6 +120,10 @@ async function interactiveMultiSelect(title, options) {
         if (selected.size === options.length) selected.clear();
         else options.forEach((_, i) => selected.add(i));
         render();
+      } else if (key === 'd' || key === 'D') { // select detected only
+        selected.clear();
+        options.forEach((o, i) => { if (o.preselect) selected.add(i); });
+        render();
       } else if (key === '\r' || key === '\n') { // enter
         cleanup();
         const result = [...selected].sort().map(i => options[i]);
@@ -178,9 +182,35 @@ export async function mcpInstall() {
       agentKeys = keys;
     } else {
       rl.close(); // close readline so raw mode works
+
+      // Build options with detected status and preselect
+      const agentOptions = keys.map(k => {
+        const agent = MCP_AGENTS[k];
+        const present = detectAgentPresence(k);
+        // Check if already configured
+        let installed = false;
+        for (const cfgPath of [agent.global, agent.project]) {
+          if (!cfgPath) continue;
+          const abs = expandHome(cfgPath);
+          if (!existsSync(abs)) continue;
+          try {
+            const config = JSON.parse(readFileSync(abs, 'utf-8'));
+            if (config[agent.key]?.mindos) { installed = true; break; }
+          } catch {}
+        }
+        const hint = installed ? 'configured' : present ? 'detected' : 'not found';
+        return { label: agent.name, hint, value: k, preselect: installed || present };
+      });
+
+      // Sort: configured > detected > not found
+      agentOptions.sort((a, b) => {
+        const rank = (o) => o.hint === 'configured' ? 0 : o.preselect ? 1 : 2;
+        return rank(a) - rank(b);
+      });
+
       const picked = await interactiveMultiSelect(
         'Which Agents to configure?',
-        keys.map(k => ({ label: MCP_AGENTS[k].name, hint: k, value: k })),
+        agentOptions,
       );
       if (picked.length === 0) {
         console.log(dim('\nNo agents selected. Exiting.\n'));

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@geminilight/mindos",
-  "version": "0.5.8",
+  "version": "0.5.10",
   "description": "MindOS — Human-Agent Collaborative Mind System. Local-first knowledge base that syncs your mind to all AI Agents via MCP.",
   "keywords": [
     "mindos",
     "mcp",
     "knowledge-base",
+    "knowledge-management",
     "ai-agent",
     "local-first",
+    "markdown",
     "second-brain"
   ],
   "type": "module",

package/scripts/setup.js

@@ -429,7 +429,8 @@ function isPortInUse(port) {
   return new Promise((resolve) => {
     const sock = createConnection({ port, host: '127.0.0.1' });
     const cleanup = (result) => { sock.destroy(); resolve(result); };
-    sock.setTimeout(500, () => cleanup(true));
+    // On localhost, timeout means no response — treat as free (same as bin/lib/port.js)
+    sock.setTimeout(500, () => cleanup(false));
     sock.once('connect', () => cleanup(true));
     sock.once('error', (err) => {
       // ECONNREFUSED = nothing listening → free; other errors = treat as in-use
@@ -628,6 +629,12 @@ async function runMcpInstallStep(mcpPort, authToken) {
     };
   });
 
+  // Sort: configured > detected > not found (stable within each group)
+  options.sort((a, b) => {
+    const rank = (o) => o.hint.includes('configured') || o.hint.includes('已配置') ? 0 : o.preselect ? 1 : 2;
+    return rank(a) - rank(b);
+  });
+
   // Multi-select using raw mode
   const selected = await (async () => {
     return new Promise((resolveSelected) => {
@@ -636,7 +643,7 @@ async function runMcpInstallStep(mcpPort, authToken) {
 
       const render = (first = false) => {
         if (!first) write(`\x1b[${options.length + 2}A\x1b[J`);
-        write(`${c.bold(uiLang === 'zh' ? '选择 Agent：' : 'Select agents:')}  ${c.dim(uiLang === 'zh' ? '(↑↓ 移动  空格 切换  A 全选  Enter 确认)' : '(↑↓ move  Space toggle  A all  Enter confirm)')}\n`);
+        write(`${c.bold(uiLang === 'zh' ? '选择 Agent：' : 'Select agents:')}  ${c.dim(uiLang === 'zh' ? '(↑↓ 移动  空格 切换  D 已检测  A 全选  Enter 确认)' : '(↑↓ move  Space toggle  D detected  A all  Enter confirm)')}\n`);
         for (let i = 0; i < options.length; i++) {
           const o = options[i];
           const check   = chosen.has(i) ? c.green('✔') : c.dim('○');
@@ -665,6 +672,11 @@ async function runMcpInstallStep(mcpPort, authToken) {
           if (chosen.size === options.length) chosen.clear();
           else options.forEach((_, i) => chosen.add(i));
           render();
+        } else if (key === 'd' || key === 'D') {
+          // Select only detected/configured agents
+          chosen.clear();
+          options.forEach((o, i) => { if (o.preselect) chosen.add(i); });
+          render();
         } else if (key === '\r' || key === '\n') {
           cleanup();
           resolveSelected([...chosen].sort().map(i => options[i].value));
@@ -733,6 +745,12 @@ const AGENT_NAME_MAP = {
   'trae': 'trae',
   'openclaw': 'openclaw',
   'codebuddy': 'codebuddy',
+  'iflow-cli': 'iflow-cli',
+  'pi': 'pi',
+  'augment': 'augment',
+  'qwen-code': 'qwen-code',
+  'trae-cn': 'trae-cn',
+  'roo': 'roo',
 };
 
 /**
@@ -840,19 +858,38 @@ async function startGuiSetup() {
       process.exit(0);
     }
     // Service not running — start on existing port
-    usePort = await isPortInUse(existingPort)
-      ? await findFreePort(9100)  // existing port occupied by another process
-      : existingPort;
+    if (await isPortInUse(existingPort)) {
+      // Port occupied — try stopping leftover MindOS processes first
+      try {
+        const { stopMindos } = await import('../bin/lib/stop.js');
+        stopMindos();
+        // stopMindos() sends SIGTERM synchronously — wait for both web and mcp
+        // ports to free, since `start` will assertPortFree on both.
+        const { waitForPortFree } = await import('../bin/lib/gateway.js');
+        const mcpPort = config.mcpPort || 8787;
+        const [webFreed, mcpFreed] = await Promise.all([
+          waitForPortFree(existingPort),
+          waitForPortFree(mcpPort),
+        ]);
+        usePort = webFreed ? existingPort : await findFreePort(9100);
+      } catch {
+        usePort = await findFreePort(9100);
+      }
+    } else {
+      usePort = existingPort;
+    }
   }
 
   write(c.yellow(t('guiStarting') + '\n'));
 
   // Start the server in the background
+  // Pass MINDOS_WEB_PORT (not PORT) so loadConfig() won't override with the
+  // config file port — this is critical when we need a temporary port.
   const cliPath = resolve(__dirname, '../bin/cli.js');
   const child = spawn(process.execPath, [cliPath, 'start'], {
     detached: true,
     stdio: 'ignore',
-    env: { ...process.env, PORT: String(usePort) },
+    env: { ...process.env, MINDOS_WEB_PORT: String(usePort) },
   });
   child.unref();
 

package/skills/project-wiki/SKILL.md

@@ -34,15 +34,72 @@ description: "组织和维护 Vibe Coding 项目的 wiki 文档体系。当用
 
 ## 文件体系
 
+### 编号体系：十位 = 层级，个位 = 序号
+
+编号按**"战略 → 架构 → 规范 → 阶段 → 运维 → 日志"**分层，均匀分布，奇数十位留空备用。
+
+```
+wiki/
+├── 0x  战略 Strategy       — 全局视角，不看代码也能读懂
+│   ├── 00-product-proposal.md
+│   ├── 01-project-roadmap.md
+│   ├── 02-business-model.md          # 有商业化需求时
+│   └── 03-technical-pillars.md       # 有技术壁垒/研究方向时
+│
+├── 2x  架构 Architecture   — 系统是怎么建的（描述事实）
+│   ├── 20-system-architecture.md
+│   └── 21-design-principle.md        # 有自定义视觉语言时
+│
+├── 3x  （空，留给接口/API 文档）
+│
+├── 4x  规范 Conventions    — 怎么参与开发（约束行为）
+│   ├── 40-conventions.md
+│   └── 41-dev-pitfall-patterns.md    # 踩坑经验
+│
+├── 5x  （空）
+│
+├── 6x  阶段 Stages         — 各阶段详细 spec（按需查阅）
+│   ├── 60-stage-a.md
+│   ├── 61-stage-b.md
+│   └── ...
+│
+├── 7x  （空）
+│
+├── 8x  运维 Operations     — 坑、复盘、backlog
+│   ├── 80-known-pitfalls.md
+│   ├── 81-postmortem-*.md
+│   ├── 84-design-exploration.md      # 有 UI 探索时
+│   └── 85-backlog.md
+│
+├── 9x  日志 Log
+│   └── 90-changelog.md
+│
+├── specs/                   — 任务 spec（活跃的，完成后归档）
+│   └── task-spec-xxx.md
+├── refs/                    — 参考资料（外部机制说明、技术调研）
+└── archive/                 — 已完结的 spec 和历史文档
+```
+
+| 区段 | 用途 | 扩展性 |
+|------|------|--------|
+| `0x` | 战略：产品方向、路线图、商业、壁垒 | 最多 10 个全局文档 |
+| `2x` | 架构：系统设计 + 设计系统 | 可加 22-data-model 等 |
+| `3x` | 留空 | 未来放 API reference、协议文档 |
+| `4x` | 规范：开发流程 + 踩坑经验 | 可加 42-testing-standards 等 |
+| `5x` | 留空 | 未来按需定义 |
+| `6x` | 阶段：各功能的详细 spec | 最多 10 个阶段 |
+| `7x` | 留空 | 未来按需定义 |
+| `8x` | 运维：已知坑、复盘、backlog | 可加 82-xxx、83-xxx |
+| `9x` | 日志 | changelog、release notes |
+
 ### 核心模型：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` — 视觉语言 | — |
+| **What** | `01-project-roadmap.md` — 功能索引 | `6X-stage-X.md` — 设计决策 |
+| **How** | `20-system-architecture.md` — 架构 + 类型 | `6X-stage-X.md` — API、数据模型、受影响文件 |
+| **Look** | `21-design-principle.md` — 视觉语言 | — |
 
 **关键规则：** stage 文件同时包含 What 和 How。一个功能的设计决策、API 契约、数据模型放在一个文件里。全局文件只做索引和导航，不重复 stage 的细节。
 
@@ -62,58 +119,29 @@ description: "组织和维护 Vibe Coding 项目的 wiki 文档体系。当用
 |------|------|--------|---------|
 | 00 | `product-proposal.md` | Agent + 你 | 产品愿景、产品定位、**不做什么**、目标用户、功能矩阵、路线图叙事 |
 | 01 | `project-roadmap.md` | Agent + 你 | 阶段总览表、全量功能索引（功能×状态×stage链接）、里程碑 |
-| 02 | `system-architecture.md` | Agent | 技术栈、目录结构、数据流、核心类型、环境变量（300-500 行） |
+| 20 | `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 文件 |
+| 02 | `business-model.md` | 有商业化/变现需求时 |
+| 03 | `technical-pillars.md` | 有明确的技术壁垒或研究方向时 |
+| 21 | `design-principle.md` | 有自定义视觉语言时（非默认 UI 库样式） |
+| 30 | `api-reference.md` | API 超过 5 条路由，或 stage 归档后仍需查 API 细节 |
+| 40 | `conventions.md` | 有明确的编码偏好/约束（库选择、命名、错误处理模式等） |
+| 41 | `dev-pitfall-patterns.md` | 踩坑积累到需要系统性记录时 |
+| 6X | `stage-X.md` | 功能复杂度超过一句话能说清（150-300 行） |
+| — | `specs/task-spec-xxx.md` | 小功能 / 改进点的 spec；实现完成后归档到 `archive/` |
+| — | `refs/xxx.md` | 外部机制说明、技术调研、协议文档 |
 | 80 | `known-pitfalls.md` | 踩坑即记，不等阶段结束 |
-| 81 | `development-guide.md` | 有非显而易见的配置要求时 |
-| 82 | `postmortem-*.md` | 多个 bug 互相关联、暴露系统性问题时（单点问题用 pitfalls，系统性问题用 postmortem） |
+| 81 | `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]`。
@@ -126,11 +154,11 @@ wiki/
 
 | 场景 | 路径 |
 |------|------|
-| 新对话 / 新功能 | `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` |
+| 新对话 / 新功能 | `00-product-proposal` → `20-system-architecture` → 当前 `6X-stage-X` |
+| 修 Bug | `20-system-architecture` → `80-known-pitfalls` → 相关 `6X-stage-X` |
+| 修 Bug（反复出现） | `81-postmortem-*` → `20-system-architecture` → `80-known-pitfalls` → 相关 `6X-stage-X` |
+| UI 调整 | `21-design-principle` → `20-system-architecture`（目录结构）→ 相关组件 |
+| 了解全貌 | `00-product-proposal` → `01-project-roadmap` → `20-system-architecture` |
 
 ---
 
@@ -177,20 +205,21 @@ Skill 触发时生成 wiki 结构，但 wiki 的日常同步发生在每次开
 
 | 当你做了这件事 | 更新哪个文件 |
 |--------------|------------|
-| 新增/修改 API 路由 | `wiki/04-api-reference.md` 追加或修改对应条目 |
+| 新增/修改 API 路由 | `wiki/30-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` 更新对应章节 |
+| 多个 bug 互相关联、暴露系统性问题 | 新建 `wiki/81-postmortem-*.md`（单点问题用 pitfalls，系统性问题用 postmortem） |
+| 架构变更（新模块、新数据流） | `wiki/20-system-architecture.md` 更新对应章节 |
 | 阶段全部交付 | `wiki/90-changelog.md` 补一笔（从 backlog 已完成条目整理） |
 | 发现 bug / 技术债 / 改进想法 | `wiki/85-backlog.md` 追加一条 |
-| 新增设计 token / 动效 | `wiki/03-design-principle.md` 追加对应条目 |
+| 新增设计 token / 动效 | `wiki/21-design-principle.md` 追加对应条目 |
 | 出现新领域术语 | `wiki/05-glossary.md` 追加定义，防止 Agent 后续用词混乱 |
 | 重命名 / 移动 wiki 文件 | 同步更新所有引用该文件的链接 |
 
 **新建文件时机：**
-- 新功能复杂度超过一句话说清 → 新建 `wiki/1X-stage-X.md`
-- 小功能 / 改进点需要 spec → 新建 `wiki/task-spec-xxx.md`（实现完成后归档或合并进 stage 文件）
+- 新功能复杂度超过一句话说清 → 新建 `wiki/6X-stage-X.md`
+- 小功能 / 改进点需要 spec → 新建 `wiki/specs/task-spec-xxx.md`（实现完成后归档到 `archive/`）
+- 外部机制调研 → 新建 `wiki/refs/xxx.md`
 
 **定期检查（每个阶段开始时）：**
 - 扫描 wiki/ 下所有文件，更新 `Last verified` 日期
@@ -209,15 +238,15 @@ Skill 触发时生成 wiki 结构，但 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` |
+| `business-model.tmpl.md` | `02-business-model.md` |
+| `technical-pillars.tmpl.md` | `03-technical-pillars.md` |
+| `system-architecture.tmpl.md` | `20-system-architecture.md` |
+| `design-principle.tmpl.md` | `21-design-principle.md` |
+| `api-reference.tmpl.md` | `30-api-reference.md` |
+| `conventions.tmpl.md` | `40-conventions.md` |
+| `stage-x.tmpl.md` | `6X-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` |
+| `postmortem.tmpl.md` | `81-postmortem-*.md` |
 | `design-exploration.tmpl.md` | `84-design-exploration.md` |
 | `backlog.tmpl.md` | `85-backlog.md` |
 | `changelog.tmpl.md` | `90-changelog.md` |