devassist-agent 1.0.0

package/src/cli/commands/init.js

@@ -0,0 +1,431 @@
+/**
+ * devassist init - Initialize project
+ *
+ * Creates:
+ *   .devassist/
+ *   ├── conventions.json       (empty, with examples commented out)
+ *   ├── schema-registry.json   (empty)
+ *   ├── tech-debt.json         (empty)
+ *   ├── version-manifest.json  (empty)
+ *   ├── deploy-manifest.json   (generated)
+ *   ├── ai-config.json         (template)
+ *   └── dependency-graph.json  (generated on first check)
+ *
+ * With --base-code flag, also installs:
+ *   lib/
+ *   ├── core/          (EventBus, FSM, Logger, RuleEngine)
+ *   ├── runtime/       (ToolRegistry, ChannelAgent, ChannelMiddleware,
+ *   │                   InfrastructureGuard, NotificationCenter, SchemaGatekeeper)
+ *   └── index.js       (unified exports)
+ *   server.js          (template server with everything wired up)
+ *
+ * Also creates a pre-commit hook if git is detected.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+module.exports = function init(projectRoot, args, ui) {
+  const { printHeader, c } = ui;
+  printHeader('初始化项目');
+
+  const configDir = path.join(projectRoot, '.devassist');
+  const hasExisting = fs.existsSync(configDir);
+  const installBaseCode = args.includes('--base-code') || args.includes('--full');
+
+  if (hasExisting && !args.includes('--force')) {
+    console.log(`  ${c.yellow('项目已初始化。')} 使用 ${c.bold('--force')} 覆盖现有配置。\n`);
+    return;
+  }
+
+  // Create config directory
+  if (!fs.existsSync(configDir)) {
+    fs.mkdirSync(configDir, { recursive: true });
+  }
+
+  // 1. conventions.json
+  const conventions = {
+    conventions: [
+      // Example convention (commented out by using _ prefix)
+      {
+        _example: true,
+        id: 'naming-list-key',
+        category: 'api',
+        rule: '列表响应数据必须使用键名 "list"，不用 "items" 或 "records"',
+        description: '防止三变体问题：data.list/data.items/data.records',
+        appliesTo: ['js', 'ts', 'json'],
+        severity: 'block',
+        forbid: 'data\\.(items|records)\\s*[=:]',
+      },
+    ],
+    adrs: [],
+  };
+  fs.writeFileSync(path.join(configDir, 'conventions.json'), JSON.stringify(conventions, null, 2), 'utf-8');
+  console.log(`  ${c.green('已创建')} conventions.json`);
+
+  // 2. schema-registry.json
+  const schemaRegistry = { schemas: {}, apiContracts: {} };
+  fs.writeFileSync(path.join(configDir, 'schema-registry.json'), JSON.stringify(schemaRegistry, null, 2), 'utf-8');
+  console.log(`  ${c.green('已创建')} schema-registry.json`);
+
+  // 3. tech-debt.json
+  const techDebt = { history: [], thresholds: {
+    maxFileLines: 800,
+    maxFunctionLines: 150,
+    maxCyclomaticComplexity: 20,
+    maxDuplicateBlocks: 3,
+    maxCouplingScore: 10,
+  }};
+  fs.writeFileSync(path.join(configDir, 'tech-debt.json'), JSON.stringify(techDebt, null, 2), 'utf-8');
+  console.log(`  ${c.green('已创建')} tech-debt.json`);
+
+  // 4. version-manifest.json
+  fs.writeFileSync(path.join(configDir, 'version-manifest.json'), '[]', 'utf-8');
+  console.log(`  ${c.green('已创建')} version-manifest.json`);
+
+  // 4.5. config.json (project-level configuration)
+  const projectConfig = {
+    maxFileLines: 800,
+    todoThreshold: 3,
+    consoleLogThreshold: 5,
+    rules: {},
+    ai: {
+      autoAnalyze: false,
+      maxFindingsToAI: 20,
+    },
+    _comment: '在此自定义规则阈值、启用/禁用规则、覆盖严重级别。例如: rules: { "cq-magic-numbers": { enabled: false } }',
+  };
+  fs.writeFileSync(path.join(configDir, 'config.json'), JSON.stringify(projectConfig, null, 2), 'utf-8');
+  console.log(`  ${c.green('已创建')} config.json`);
+
+  // 5. ai-config.json
+  const aiConfig = {
+    provider: '',  // 'qwen' | 'openai' | 'claude' | 'hunyuan'
+    apiKey: '',    // 或设置环境变量: DASHSCOPE_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY / HUNYUAN_API_KEY
+    model: '',
+    baseUrl: '',
+    enabled: false,
+    _comment: '设置 provider 和 apiKey，然后将 enabled 设为 true。也可使用环境变量。',
+    _envVars: {
+      qwen: 'DASHSCOPE_API_KEY',
+      openai: 'OPENAI_API_KEY',
+      claude: 'ANTHROPIC_API_KEY',
+      hunyuan: 'HUNYUAN_API_KEY',
+    },
+    _models: {
+      qwen: 'qwen-plus',
+      openai: 'gpt-4o-mini',
+      claude: 'claude-sonnet-4-20250514',
+      hunyuan: 'hy3-preview',
+    },
+  };
+  fs.writeFileSync(path.join(configDir, 'ai-config.json'), JSON.stringify(aiConfig, null, 2), 'utf-8');
+  console.log(`  ${c.green('已创建')} ai-config.json`);
+
+  // 6. deploy-manifest.json (placeholder)
+  const deployManifest = { generatedAt: '', totalFiles: 0, files: [] };
+  fs.writeFileSync(path.join(configDir, 'deploy-manifest.json'), JSON.stringify(deployManifest, null, 2), 'utf-8');
+  console.log(`  ${c.green('已创建')} deploy-manifest.json`);
+
+  // 7. Create backups directory
+  const backupDir = path.join(configDir, 'backups');
+  if (!fs.existsSync(backupDir)) fs.mkdirSync(backupDir, { recursive: true });
+  console.log(`  ${c.green('已创建')} backups/`);
+
+  // 7.5. Create reports directory
+  const reportDir = path.join(configDir, 'reports');
+  if (!fs.existsSync(reportDir)) fs.mkdirSync(reportDir, { recursive: true });
+  console.log(`  ${c.green('已创建')} reports/`);
+
+  // 7.6. Create history directory
+  const historyDir = path.join(configDir, 'history');
+  if (!fs.existsSync(historyDir)) fs.mkdirSync(historyDir, { recursive: true });
+  console.log(`  ${c.green('已创建')} history/`);
+
+  // 7.5. Create .devassistignore
+  const ignorePath = path.join(projectRoot, '.devassistignore');
+  if (!fs.existsSync(ignorePath) || args.includes('--force')) {
+    const ignoreContent = `# DevAssist 忽略文件 — 类似 .gitignore
+# 此处列出的目录在扫描时将被跳过。
+# 每行一个模式。目录以 / 结尾，通配符使用 *。
+
+# 备份/归档目录
+*_backup/
+*_old/
+*_archive/
+*backup*/
+
+# 依赖
+node_modules/
+
+# 构建产物
+dist/
+build/
+
+# 无脚本的设计文档（取消注释可跳过所有 HTML）
+# *.html
+`;
+    fs.writeFileSync(ignorePath, ignoreContent, 'utf-8');
+    console.log(`  ${c.green('已创建')} .devassistignore`);
+  }
+
+  // 8. Git pre-commit hook
+  const gitDir = path.join(projectRoot, '.git');
+  if (fs.existsSync(gitDir)) {
+    const hookDir = path.join(gitDir, 'hooks');
+    if (!fs.existsSync(hookDir)) fs.mkdirSync(hookDir, { recursive: true });
+    const hookPath = path.join(hookDir, 'pre-commit');
+    const hookContent = `#!/bin/sh
+# DevAssist pre-commit hook
+# Runs devassist check before allowing a commit
+echo "[DevAssist] Running pre-commit checks..."
+node "${path.join(__dirname, '..', '..', '..', 'bin', 'devassist.js')}" check --pre-commit
+if [ $? -ne 0 ]; then
+  echo "[DevAssist] Commit blocked by check failures. Fix issues or use --no-verify to bypass."
+  exit 1
+fi
+exit 0
+`;
+    fs.writeFileSync(hookPath, hookContent, 'utf-8');
+    try { fs.chmodSync(hookPath, 0o755); } catch (_) {}
+    console.log(`  ${c.green('已创建')} .git/hooks/pre-commit`);
+  }
+
+  // 9. Install base code (Layer 2 runtime infrastructure) if requested
+  if (installBaseCode) {
+    console.log(`\n  ${c.cyan('正在安装基础代码（运行时基础设施）...')}`);
+    installBaseCodeModules(projectRoot, c);
+  }
+
+  console.log(`\n  ${c.bold(c.green('项目初始化完成！'))}\n`);
+  console.log(`  ${c.gray('后续步骤：')}`);
+  if (installBaseCode) {
+    console.log(`    1. 查看 lib/server.js 了解模板服务器配置`);
+    console.log(`    2. 编辑 .devassist/conventions.json 添加项目约定`);
+    console.log(`    3. 编辑 .devassist/ai-config.json 启用 AI 分析（可选）`);
+    console.log(`    4. 运行 ${c.bold('devassist check')} 扫描代码库`);
+    console.log(`    5. 运行 ${c.bold('devassist schema import <file.sql>')} 注册数据库模式\n`);
+  } else {
+    console.log(`    1. 编辑 .devassist/conventions.json 添加项目约定`);
+    console.log(`    2. 编辑 .devassist/ai-config.json 启用 AI 分析（可选）`);
+    console.log(`    3. 编辑 .devassist/config.json 自定义规则阈值（可选）`);
+    console.log(`    4. 运行 ${c.bold('devassist check')} 扫描代码库`);
+    console.log(`    5. 运行 ${c.bold('devassist schema import <file.sql>')} 注册数据库模式`);
+    console.log(`    6. 运行 ${c.bold('devassist init --base-code')} 安装运行时基础设施\n`);
+  }
+};
+
+/**
+ * Install base code modules into the target project's lib/ directory.
+ * Copies core and runtime modules, adjusting require paths.
+ */
+function installBaseCodeModules(projectRoot, c) {
+  const devassistRoot = path.join(__dirname, '..', '..', '..');
+  const libDir = path.join(projectRoot, 'lib');
+  const coreDir = path.join(libDir, 'core');
+  const runtimeDir = path.join(libDir, 'runtime');
+
+  // Create directories
+  for (const dir of [coreDir, runtimeDir]) {
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  }
+
+  // Copy core modules (no path adjustment needed — they have no relative requires)
+  const coreFiles = ['event-bus.js', 'fsm.js', 'logger.js', 'rule-engine.js'];
+  for (const file of coreFiles) {
+    const src = path.join(devassistRoot, 'src', 'core', file);
+    if (fs.existsSync(src)) {
+      fs.copyFileSync(src, path.join(coreDir, file));
+      console.log(`  ${c.green('已创建')} lib/core/${file}`);
+    }
+  }
+
+  // Copy runtime modules (adjust require paths: ../../core/ -> ../core/)
+  const runtimeFiles = [
+    'tool-registry.js', 'channel-agent.js', 'channel-middleware.js',
+    'infrastructure-guard.js', 'notification-center.js', 'schema-gatekeeper.js',
+    'index.js',
+  ];
+  for (const file of runtimeFiles) {
+    const src = path.join(devassistRoot, 'src', 'modules', 'runtime', file);
+    if (fs.existsSync(src)) {
+      let content = fs.readFileSync(src, 'utf-8');
+      // Adjust require paths for target project structure
+      content = content.replace(/require\('\.\.\/\.\.\/core\//g, "require('../core/");
+      content = content.replace(/require\('\.\.\/\.\.\/modules\//g, "require('../");
+      fs.writeFileSync(path.join(runtimeDir, file), content, 'utf-8');
+      console.log(`  ${c.green('已创建')} lib/runtime/${file}`);
+    }
+  }
+
+  // Create lib/index.js (unified entry point)
+  const libIndex = `/**
+ * Base code entry point — installed by devassist init --base-code
+ *
+ * This gives your project the zero-upgrade architecture foundation:
+ *   - ToolRegistry for dynamic tool registration
+ *   - ChannelAgent for protocol-level communication
+ *   - ChannelMiddleware for request/response processing
+ *   - InfrastructureGuard for runtime health monitoring
+ *   - NotificationCenter for multi-channel alerting
+ *   - SchemaGatekeeper for runtime data validation
+ */
+
+module.exports = {
+  // Core
+  EventBus: require('./core/event-bus'),
+  FSM: require('./core/fsm'),
+  Logger: require('./core/logger'),
+
+  // Runtime
+  ...require('./runtime'),
+};
+`;
+  fs.writeFileSync(path.join(libDir, 'index.js'), libIndex, 'utf-8');
+  console.log(`  ${c.green('已创建')} lib/index.js`);
+
+  // Create server.js template
+  const serverTemplate = `/**
+ * Server template — installed by devassist init --base-code
+ *
+ * This template shows how to wire up all the base code modules.
+ * Customize it for your project's needs.
+ */
+
+const http = require('http');
+const {
+  EventBus: { bus },
+  FSM: { FSM, STATES },
+  Logger: { Logger },
+  ToolRegistry: { registry, MODULE_TYPES },
+  ChannelAgent: { ChannelAgent, PROTOCOL_VERSION, PRIORITY },
+  ChannelMiddleware: { compose, requestLogger, authGuard, rateLimiter, schemaValidator, errorHandler },
+  InfrastructureGuard: { InfrastructureGuard, HEALTH_STATE },
+  NotificationCenter: { center },
+  SchemaGatekeeper: { gatekeeper },
+} = require('./lib');
+
+const log = new Logger('Server');
+
+// --- Initialize InfrastructureGuard ---
+const guard = new InfrastructureGuard();
+guard.addHttpProbe({ url: 'http://localhost:8080/health', interval: 30000 });
+guard.addMemoryProbe({ maxHeapMB: 512, interval: 30000 });
+guard.addDiskProbe({ path: process.cwd(), minFreeMB: 500, interval: 60000 });
+guard.start();
+
+// --- Initialize ChannelAgent ---
+const agent = new ChannelAgent({ registry, secret: process.env.CHANNEL_SECRET || null });
+agent.init();
+
+// --- Register your tools here ---
+// Example:
+// agent.route('chat.send', 'chat-tool-id', { priority: PRIORITY.NORMAL });
+// agent.route('voice.tts', 'voice-tts-tool-id', { priority: PRIORITY.NORMAL });
+
+// --- Build middleware chain ---
+const middleware = compose([
+  errorHandler(),
+  requestLogger(),
+  corsHandler?.() || ((ctx, next) => next()),
+  rateLimiter({ windowMs: 60000, max: 100 }),
+  authGuard({ exclude: ['heartbeat.ping', 'channel.state', 'config.greetings'] }),
+]);
+
+// --- HTTP Server ---
+const server = http.createServer(async (req, res) => {
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204, {
+      'Access-Control-Allow-Origin': '*',
+      'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+    });
+    res.end();
+    return;
+  }
+
+  // Health endpoint
+  if (req.url === '/health') {
+    const status = guard.getStatus();
+    res.writeHead(status.state === HEALTH_STATE.HEALTHY ? 200 : 503, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(status));
+    return;
+  }
+
+  // Tool manifest endpoint
+  if (req.url === '/api/tools') {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(registry.getManifest()));
+    return;
+  }
+
+  // Main API endpoint
+  if (req.url === '/api' || req.url.startsWith('/api/')) {
+    let body = '';
+    req.on('data', chunk => body += chunk);
+    req.on('end', async () => {
+      let parsedBody;
+      try {
+        parsedBody = body ? JSON.parse(body) : {};
+      } catch (e) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ code: 400, message: 'Invalid JSON' }));
+        return;
+      }
+
+      const ctx = {
+        body: parsedBody,
+        ip: req.socket.remoteAddress,
+        headers: req.headers,
+        url: req.url,
+      };
+
+      await middleware(ctx, async () => {
+        // If middleware set a response (e.g. auth failure), use it
+        if (ctx.response) {
+          res.writeHead(ctx.response.code === 200 ? 200 : ctx.response.code, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify(ctx.response));
+          return;
+        }
+
+        // Hand off to ChannelAgent
+        const result = await agent.handleRequest(parsedBody, ctx);
+        res.writeHead(result.code === 200 ? 200 : result.code, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(result));
+      });
+    });
+    return;
+  }
+
+  res.writeHead(404, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify({ code: 404, message: 'Not found' }));
+});
+
+const PORT = process.env.PORT || 8080;
+server.listen(PORT, () => {
+  log.info(\`Server running on port \${PORT}\`);
+  log.info(\`Protocol: \${PROTOCOL_VERSION}\`);
+  log.info(\`Tools registered: \${registry.getStats().totalTools}\`);
+  center.info('Server started', \`Listening on port \${PORT}\`, 'server');
+});
+
+// Graceful shutdown
+process.on('SIGTERM', () => {
+  log.info('SIGTERM received, shutting down...');
+  guard.stop();
+  agent.destroy();
+  server.close(() => process.exit(0));
+});
+
+process.on('SIGINT', () => {
+  log.info('SIGINT received, shutting down...');
+  guard.stop();
+  agent.destroy();
+  server.close(() => process.exit(0));
+});
+`;
+  fs.writeFileSync(path.join(projectRoot, 'server.js'), serverTemplate, 'utf-8');
+  console.log(`  ${c.green('已创建')} server.js`);
+
+  console.log(`\n  ${c.cyan('基础代码安装完成！')} lib/ 目录 10 个文件 + server.js 模板`);
+}

package/src/cli/commands/inject.js

@@ -0,0 +1,254 @@
+/**
+ * devassist inject - 生成约定注入文件
+ *
+ * 核心差异化能力：让 Trae/WorkBuddy/Cursor 等 AI Agent 在写代码时
+ * 自动获取项目约定，从根源防止"AI遗忘早期约定"（32/88 故障根因）。
+ *
+ *   devassist inject                              生成 .devassist/CONVENTIONS.md
+ *   devassist inject --format cursor              生成 .cursorrules
+ *   devassist inject --format trae                生成 .traerules
+ *   devassist inject --format markdown            生成 .devassist/CONVENTIONS.md
+ *   devassist inject --format stdout              输出到终端（用于管道）
+ *   devassist inject --format all                 生成所有格式
+ *
+ * 原理：AI Agent 在开始写代码前会读取项目根目录的规则文件
+ * （.cursorrules / .traerules / CONVENTIONS.md 等）。
+ * 本命令将 .devassist/conventions.json 中的约定自动同步到这些文件，
+ * 确保约定始终是最新的。
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { ConventionStore } = require('../../modules/dev-time/convention-store');
+
+module.exports = function inject(projectRoot, args, ui) {
+  const { printHeader, c } = ui;
+  printHeader('约定注入');
+
+  const format = getArg(args, '--format') || 'markdown';
+  const store = new ConventionStore(projectRoot);
+  const { conventions, adrs } = store.list();
+
+  // Filter out example conventions
+  const realConventions = conventions.filter(conv => !conv._example);
+
+  if (realConventions.length === 0 && adrs.length === 0) {
+    console.log(`  ${c.yellow('尚未注册任何约定。')}\n`);
+    console.log(`  ${c.gray('先添加约定：')}`);
+    console.log(`    devassist convention add --id <标识> --rule "<规则描述>"\n`);
+    return;
+  }
+
+  console.log(`  ${c.gray('约定数量：')} ${realConventions.length} 条约定，${adrs.length} 条 ADR`);
+  console.log(`  ${c.gray('输出格式：')} ${format}\n`);
+
+  const content = generateContent(realConventions, adrs, format);
+
+  if (format === 'stdout') {
+    console.log(content);
+    return;
+  }
+
+  if (format === 'all') {
+    // Generate all formats
+    const formats = ['markdown', 'cursor', 'trae'];
+    for (const fmt of formats) {
+      const fmtContent = generateContent(realConventions, adrs, fmt);
+      const filePath = getFilePath(projectRoot, fmt);
+      writeToFile(filePath, fmtContent, c);
+    }
+    console.log(`\n  ${c.green('全部约定文件已生成！')}\n`);
+    console.log(`  ${c.gray('AI Agent 现在会自动读取这些约定。')}\n`);
+    return;
+  }
+
+  const filePath = getFilePath(projectRoot, format);
+  writeToFile(filePath, content, c);
+
+  console.log(`\n  ${c.green('约定文件已生成！')}\n`);
+
+  // Print usage hint based on format
+  switch (format) {
+    case 'cursor':
+      console.log(`  ${c.gray('Cursor 会自动读取项目根目录的 .cursorrules 文件。')}`);
+      break;
+    case 'trae':
+      console.log(`  ${c.gray('Trae 会自动读取项目根目录的 .traerules 文件。')}`);
+      break;
+    case 'markdown':
+      console.log(`  ${c.gray('WorkBuddy / Trae / 其他 AI Agent 会读取 .devassist/CONVENTIONS.md。')}`);
+      console.log(`  ${c.gray('建议在项目根目录的 README 中引用此文件。')}`);
+      break;
+  }
+
+  console.log(`\n  ${c.gray('提示：每次更新约定后重新运行此命令以同步文件。')}`);
+  console.log(`  ${c.gray('     可在 git pre-commit hook 中自动执行。')}\n`);
+};
+
+function generateContent(conventions, adrs, format) {
+  switch (format) {
+    case 'cursor':
+      return generateCursorRules(conventions, adrs);
+    case 'trae':
+      return generateTraeRules(conventions, adrs);
+    case 'markdown':
+    case 'stdout':
+      return generateMarkdown(conventions, adrs);
+    default:
+      return generateMarkdown(conventions, adrs);
+  }
+}
+
+function getFilePath(projectRoot, format) {
+  switch (format) {
+    case 'cursor':
+      return path.join(projectRoot, '.cursorrules');
+    case 'trae':
+      return path.join(projectRoot, '.traerules');
+    case 'markdown':
+      return path.join(projectRoot, '.devassist', 'CONVENTIONS.md');
+    default:
+      return path.join(projectRoot, '.devassist', 'CONVENTIONS.md');
+  }
+}
+
+function writeToFile(filePath, content, c) {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(filePath, content, 'utf-8');
+  const relPath = path.relative(process.cwd(), filePath);
+  console.log(`  ${c.green('已生成：')} ${relPath}`);
+}
+
+/**
+ * 生成 Markdown 格式的约定文档
+ */
+function generateMarkdown(conventions, adrs) {
+  let md = `# 项目约定（必须遵守）\n\n`;
+  md += `> 本文件由 DevAssist 自动生成，请勿手动编辑。\n`;
+  md += `> 修改约定请使用：devassist convention add --id <标识> --rule "<规则>"\n`;
+  md += `> 然后重新运行：devassist inject\n\n`;
+
+  // Group conventions by category
+  const categories = {};
+  for (const conv of conventions) {
+    const cat = conv.category || 'general';
+    if (!categories[cat]) categories[cat] = [];
+    categories[cat].push(conv);
+  }
+
+  for (const [cat, convs] of Object.entries(categories)) {
+    const catName = CATEGORY_NAMES[cat] || cat;
+    md += `## ${catName}\n\n`;
+    for (const conv of convs) {
+      const sevIcon = conv.severity === 'block' ? '🚫' : conv.severity === 'warn' ? '⚠️' : 'ℹ️';
+      md += `### ${sevIcon} ${conv.id}\n\n`;
+      md += `**规则：** ${conv.rule}\n\n`;
+      if (conv.description) md += `**说明：** ${conv.description}\n\n`;
+      if (conv.examples && conv.examples.length > 0) {
+        md += `**示例：**\n`;
+        for (const ex of conv.examples) md += `- ${ex}\n`;
+        md += `\n`;
+      }
+      if (conv.forbid) md += `**禁止模式：** \`${conv.forbid}\`\n\n`;
+      if (conv.require) md += `**要求模式：** \`${conv.require}\`\n\n`;
+    }
+  }
+
+  if (adrs.length > 0) {
+    md += `## 架构决策记录（ADR）\n\n`;
+    for (const adr of adrs) {
+      md += `### ${adr.id}: ${adr.title || adr.decision}\n\n`;
+      if (adr.context) md += `**背景：** ${adr.context}\n\n`;
+      if (adr.decision) md += `**决策：** ${adr.decision}\n\n`;
+      if (adr.consequences) md += `**后果：** ${adr.consequences}\n\n`;
+      md += `*记录时间：${adr.date}*\n\n`;
+    }
+  }
+
+  md += `---\n\n`;
+  md += `*最后更新：${new Date().toISOString().split('T')[0]} | 由 DevAssist 生成*\n`;
+
+  return md;
+}
+
+/**
+ * 生成 .cursorrules 格式
+ * Cursor 读取项目根目录的 .cursorrules 文件作为 AI 上下文
+ */
+function generateCursorRules(conventions, adrs) {
+  let rules = `# 项目约定 - AI Agent 必须遵守\n\n`;
+  rules += `## 重要：以下约定是项目的硬性规则，违反将导致 bug。\n`;
+  rules += `## 在生成或修改代码时，必须检查是否符合以下约定。\n\n`;
+
+  const categories = {};
+  for (const conv of conventions) {
+    const cat = conv.category || 'general';
+    if (!categories[cat]) categories[cat] = [];
+    categories[cat].push(conv);
+  }
+
+  for (const [cat, convs] of Object.entries(categories)) {
+    const catName = CATEGORY_NAMES[cat] || cat;
+    rules += `### ${catName}\n\n`;
+    for (const conv of convs) {
+      const prefix = conv.severity === 'block' ? '[必须]' : conv.severity === 'warn' ? '[建议]' : '[提示]';
+      rules += `- ${prefix} **${conv.id}**: ${conv.rule}\n`;
+      if (conv.description) rules += `  - 说明: ${conv.description}\n`;
+      if (conv.forbid) rules += `  - 禁止: /${conv.forbid}/\n`;
+      if (conv.require) rules += `  - 要求: /${conv.require}/\n`;
+    }
+    rules += `\n`;
+  }
+
+  if (adrs.length > 0) {
+    rules += `### 架构决策记录\n\n`;
+    for (const adr of adrs) {
+      rules += `- **${adr.id}**: ${adr.decision}\n`;
+      if (adr.context) rules += `  - 背景: ${adr.context}\n`;
+    }
+    rules += `\n`;
+  }
+
+  rules += `## 通用规则\n\n`;
+  rules += `1. 修改代码前，先理解当前文件的完整上下文，不要只看局部\n`;
+  rules += `2. 不要大幅缩减文件行数（AI 覆盖是 88 条故障中的 #1 根因）\n`;
+  rules += `3. 修改函数签名前，搜索所有调用方\n`;
+  rules += `4. 保持 API 响应格式一致（字段名、结构）\n`;
+  rules += `5. 所有 async 调用必须有错误处理\n`;
+  rules += `6. 不要引入新的外部依赖，除非明确讨论过\n\n`;
+  rules += `# 由 DevAssist 自动生成 | ${new Date().toISOString().split('T')[0]}\n`;
+
+  return rules;
+}
+
+/**
+ * 生成 .traerules 格式
+ * Trae 读取项目根目录的 .traerules 文件
+ */
+function generateTraeRules(conventions, adrs) {
+  let rules = generateCursorRules(conventions, adrs);
+  // Trae-specific additions
+  rules += `\n## Trae 专用规则\n\n`;
+  rules += `- 在生成代码后，运行 \`devassist check\` 验证是否符合约定\n`;
+  rules += `- 如果 devassist check 报告 BLOCK 级别问题，必须修复后再提交\n`;
+  rules += `- 修改文件前，先运行 \`devassist diff --staged\` 查看变更影响\n`;
+  return rules;
+}
+
+const CATEGORY_NAMES = {
+  'api': 'API 约定',
+  'naming': '命名约定',
+  'architecture': '架构约定',
+  'code-style': '代码风格',
+  'security': '安全约定',
+  'database': '数据库约定',
+  'error-handling': '错误处理约定',
+  'general': '通用约定',
+};
+
+function getArg(args, flag) {
+  const idx = args.indexOf(flag);
+  if (idx >= 0 && args[idx + 1]) return args[idx + 1];
+  return null;
+}