autosnippet 1.7.4 → 2.0.2

package/README.md

@@ -1,4 +1,4 @@
-# AutoSnippet
+# AutoSnippet — Project Knowledge Engine
 
 连接开发者、AI 与项目知识库：人工审核沉淀标准，知识库存储 Recipe + Snippet，AI 按规范生成代码。基于 SPM，打通 Xcode 补全与 Cursor 按需检索。
 
@@ -22,6 +22,8 @@
 
 ### 1. 安装 AutoSnippet
 
+> **要求**：Node.js ≥ 20
+
 ```bash
 npm install -g autosnippet
 ```
@@ -48,13 +50,14 @@ asd ui                     # 启动 Dashboard + watch
 
 `asd ui` 会启动 Web 管理后台并后台 watch；首次运行若前端不存在会自动构建。浏览器会自动打开 Dashboard。
 
-![Dashboard 概览](./images/20260205232116_66_167.png)
+![Dashboard 概览](https://cdn.jsdelivr.net/gh/GxFn/blog-images@main/autosnippet-manual/20260205232116_66_167.png)
+
 
 ## 核心流程
 
 **智能 AI 优先 → 前端操作 → 命令行补充**
 
-1. **Cursor AI 快捷扫描**（推荐）：在 Cursor 中输入自然语言（如「扫描这个 Target」、「批量提取代码候选」），AI 智能触发 `autosnippet-batch-scan` 等 Skill，通过 MCP 工具 `autosnippet_get_targets` → `autosnippet_get_target_files` → 按文件提取 → `autosnippet_submit_candidates` 一键批量扫描，自动提交候选到 Dashboard Candidates
+1. **Cursor AI 智能扫描**（推荐）：在 Cursor 中输入自然语言（如「扫描这个 Target」、「批量提取代码候选」），AI 智能触发 `autosnippet-candidates` Skill，通过 MCP 工具 `autosnippet_get_targets` → `autosnippet_get_target_files` → 按文件提取 → `autosnippet_submit_candidates` 一键批量扫描，自动提交候选到 Dashboard Candidates
 2. **前端审核与入库**：Dashboard Candidates 页面人工审核 → 保存 Recipe 入库（优先前端操作，无需命令行）
 3. **依赖关系**（可选）：Dashboard 刷新自动分析，或使用 `asd spm-map` 命令行更新
 4. **语义索引**（自动）：`asd ui` 启动时自动 embed；也可手动 `asd embed`
@@ -96,23 +99,14 @@ Cursor 在编辑器内通过自然语言交互触发 Skill，使用 MCP 工具
 | `asd ais [Target]` | AI 扫描 Target → Candidates |
 | `asd search [keyword] --copy` | 搜索并复制第一条到剪贴板 |
 | `asd search [keyword] --pick` | 交互选择后复制/插入 |
+| `asd sync` | 增量同步 `recipes/*.md` → DB（.md = Source of Truth） |
+| `asd compliance` | 生成宪法合规评估报告（P1-P4 加权评分） |
+| `asd upgrade` | 升级 IDE 集成文件（MCP/Skills/Cursor Rules/Copilot） |
 | `asd install:cursor-skill --mcp` | 安装 Skills、Cursor 规则（`.cursor/rules/*.mdc`）并配置 MCP。配置时可运行；MCP 工具使用时需 `asd ui` 已启动 |
-| `asd install:full` | 全量安装；`--parser` 含 Swift 解析器 |
+| `asd install:full` | 全量安装（Skills、MCP、Native UI） |
 | `asd embed` | 手动构建语义向量索引（`asd ui` 启动时也会自动执行） |
 | `asd spm-map` | 刷新 SPM 依赖映射（依赖关系图数据来源） |
 
-## 可选依赖
-
-### Swift 解析器（可选）
-
-AutoSnippet 默认使用 `swift package dump-package` 解析 SPM 依赖。如需更准确的解析，可安装 Swift 解析器：
-
-```bash
-asd install:full --parser    # 全量安装（含 Swift 解析器）
-```
-
-构建后会在 `tools/parse-package/.build/release/` 生成解析器，SPM 解析将更准确可靠。未安装时自动回退到 `dump-package`，功能正常。
-
 ## 配置
 
 - **AI**：项目根 `.env`，参考 `.env.example` 配置 `ASD_GOOGLE_API_KEY` 等。可选 `ASD_AI_PROVIDER`、代理等。
@@ -131,9 +125,11 @@ asd install:full --parser    # 全量安装（含 Swift 解析器）
 | **watch** | 文件监听进程（`asd ui` 或 `asd watch` 启动），保存时触发 `as:create`、`as:audit`、`as:search` |
 | **Guard** | 按 Recipe 知识库对代码做 AI 审查；`// as:audit` 触发 |
 | **embed** | 语义向量索引构建；`asd embed` 或 `asd ui` 启动时自动执行，供语义检索与 MCP 使用 |
-| **MCP** | Model Context Protocol；Cursor 通过 MCP 调用 `autosnippet_context_search` 等工具 |
+| **MCP** | Model Context Protocol；Cursor 通过 MCP 调用 31 个工具（7 个写操作经 Gateway 权限保护） |
 | **Skills** | Cursor Agent Skills（`.cursor/skills/`），描述何时用、如何用 AutoSnippet 能力 |
 | **trigger** | Snippet 触发前缀，默认 `@`，输入后 Xcode 联想补全 |
+| **Gateway** | V2 控制平面，统一调度 27 个 Action：validate → permission → constitution → plugin → dispatch → audit |
+| **Constitution** | 宪法体系：6 角色、P1-P4 四优先级、能力探测，见 `config/constitution.yaml` |
 | **项目根** | 含 `AutoSnippetRoot.boxspec.json` 的目录 |
 | **Target** | SPM 模块/编译单元；`asd ais <Target>` 扫描该 Target 下的源码提取候选 |
 

package/bin/api-server.js

@@ -1,84 +1,98 @@
+#!/usr/bin/env node
+
 /**
- * API Server 启动脚本
- * 
- * 用法：
- *   node bin/api-server.js [options]
- * 
- * 选项：
- *   --port <port>     API 服务器端口 (默认: 8080)
- *   --host <host>     API 服务器主机 (默认: localhost)
- *   --config <path>   配置文件路径
+ * HTTP API 服务器启动脚本
+ * 用于开发和测试 REST API
  */
 
-const { APIGateway } = require('../lib/api/APIGateway');
-const { Agent } = require('../lib/agent/Agent');
-const { RecipeHub } = require('../lib/business/recipe/RecipeHub');
-const { SearchHub } = require('../lib/business/search/SearchHub');
-const { MetricsHub } = require('../lib/business/metrics/MetricsHub');
+import HttpServer from '../lib/http/HttpServer.js';
+import Bootstrap from '../lib/bootstrap.js';
+import Logger from '../lib/infrastructure/logging/Logger.js';
+import { getServiceContainer } from '../lib/injection/ServiceContainer.js';
 
-/**
- * 解析命令行参数
- */
-function parseArgs() {
-  const args = process.argv.slice(2);
-  const options = {
-  port: 8080,
-  host: 'localhost',
-  };
-
-  for (let i = 0; i < args.length; i++) {
-  if (args[i] === '--port') {
-    options.port = parseInt(args[++i], 10);
-  } else if (args[i] === '--host') {
-    options.host = args[++i];
-  }
-  }
+async function main() {
+  const logger = Logger.getInstance();
+  const port = process.env.PORT || 3000;
+  const host = process.env.HOST || 'localhost';
 
-  return options;
-}
+  try {
+    logger.info('Initializing AutoSnippet HTTP API Server...', {
+      port,
+      host,
+      timestamp: new Date().toISOString(),
+    });
 
-/**
- * 启动 API 服务器
- */
-async function startServer() {
-  const options = parseArgs();
+    // 初始化应用程序引导
+    const bootstrap = new Bootstrap({ env: process.env.NODE_ENV || 'development' });
+    const components = await bootstrap.initialize();
+    logger.info('Bootstrap initialized successfully');
 
-  // 创建 Agent
-  const agent = new Agent({ name: 'APIAgent' });
+    // 初始化 DI 容器，注入 Bootstrap 组件
+    const container = getServiceContainer();
+    await container.initialize({
+      db: components.db,
+      auditLogger: components.auditLogger,
+      gateway: components.gateway,
+      reasoningLogger: components.reasoningLogger,
+      roleDriftMonitor: components.roleDriftMonitor,
+      complianceEvaluator: components.complianceEvaluator,
+      sessionManager: components.sessionManager,
+    });
+    logger.info('Service container initialized successfully');
 
-  // 注册 Hub
-  agent.registerHub('recipe', new RecipeHub());
-  agent.registerHub('search', new SearchHub());
-  agent.registerHub('metric', new MetricsHub());
+    // 创建和启动 HTTP 服务器
+    const httpServer = new HttpServer({ port, host });
+    await httpServer.initialize(); // 改为 async 调用
+    await httpServer.start();
 
-  // 创建 API Gateway
-  const gateway = new APIGateway(agent, {
-  port: options.port,
-  host: options.host,
-  });
+    logger.info('HTTP API Server is running', {
+      url: `http://${host}:${port}`,
+      documentation: `http://${host}:${port}/api-spec`,
+      health: `http://${host}:${port}/api/v1/health`,
+    });
 
-  // 启动服务器
-  try {
-  await gateway.start();
-  console.log(`✨ API 服务器运行中...`);
-  console.log(`📝 API 文档: http://${options.host}:${options.port}/api/docs`);
-  console.log(`🏥 健康检查: http://${options.host}:${options.port}/api/health`);
-  console.log(`\n按 Ctrl+C 停止服务器`);
+    // 优雅关闭
+    const handleShutdown = async (signal) => {
+      logger.info(`Received ${signal}, shutting down gracefully...`, {
+        timestamp: new Date().toISOString(),
+      });
+
+      await httpServer.stop();
+      await bootstrap.shutdown();
+
+      logger.info('HTTP API Server shut down successfully', {
+        timestamp: new Date().toISOString(),
+      });
+
+      process.exit(0);
+    };
+
+    process.on('SIGTERM', () => handleShutdown('SIGTERM'));
+    process.on('SIGINT', () => handleShutdown('SIGINT'));
+
+    // 处理未捕获的异常
+    process.on('uncaughtException', (error) => {
+      logger.error('Uncaught Exception', {
+        message: error.message,
+        stack: error.stack,
+      });
+      process.exit(1);
+    });
+
+    process.on('unhandledRejection', (reason, promise) => {
+      logger.error('Unhandled Rejection', {
+        reason,
+        promise,
+      });
+      process.exit(1);
+    });
   } catch (error) {
-  console.error('❌ 启动服务器失败:', error);
-  process.exit(1);
+    logger.error('Failed to start HTTP API Server', {
+      message: error.message,
+      stack: error.stack,
+    });
+    process.exit(1);
   }
-
-  // 处理信号
-  process.on('SIGINT', async () => {
-  console.log('\n🛑 停止服务器...');
-  await gateway.stop();
-  console.log('✅ 服务器已停止');
-  process.exit(0);
-  });
 }
 
-startServer().catch(error => {
-  console.error('Fatal error:', error);
-  process.exit(1);
-});
+main();