devassist-agent 1.0.0

package/src/modules/runtime/tool-registry.js

@@ -0,0 +1,329 @@
+/**
+ * ToolRegistry - Dynamic tool registration center (零升级架构核心)
+ *
+ * Design from 零升级架构设计.md:
+ *   - 3 module types: resident (built-in), dynamic (hot-loaded), remote (external)
+ *   - 8 standard interfaces: register, unregister, get, list, invoke,
+ *     healthCheck, reload, getManifest
+ *   - Each tool has: id, name, version, type, category, schema, handler
+ *
+ * This is the runtime base code that gets installed into projects via
+ * `devassist init`. It provides the zero-upgrade architecture foundation:
+ * new features are added as tool modules, never requiring app recompilation.
+ */
+
+const { bus } = require('../../core/event-bus');
+const { Logger } = require('../../core/logger');
+
+const log = new Logger('ToolRegistry');
+
+const MODULE_TYPES = {
+  RESIDENT: 'resident',   // Built-in, always loaded
+  DYNAMIC:  'dynamic',    // Hot-loaded at runtime
+  REMOTE:   'remote',     // External service proxy
+};
+
+/**
+ * Standard tool schema definition.
+ * Every tool module must export an object with these fields.
+ */
+const TOOL_INTERFACE = {
+  id:        'string',           // Unique identifier (e.g. 'weather.query')
+  name:      'string',           // Human-readable name
+  version:   'string',           // Semver version
+  type:      'string',           // MODULE_TYPES
+  category:  'string',           // Grouping (e.g. 'chat', 'voice', 'config')
+  schema:    'object',           // { input: JSONSchema, output: JSONSchema }
+  handler:   'function',         // async (input, ctx) => output
+  init:      'function?',        // async () => {} called on register
+  destroy:   'function?',        // async () => {} called on unregister
+  healthCheck: 'function?',      // async () => { healthy, details }
+};
+
+class ToolRegistry {
+  constructor() {
+    this._tools = new Map();
+    this._categories = new Map(); // category -> Set of tool ids
+    this._invocationCount = new Map();
+    this._errorCount = new Map();
+  }
+
+  /**
+   * Register a tool module.
+   * Validates the tool interface, calls init() if present.
+   * @param {object} tool - Tool module conforming to TOOL_INTERFACE
+   * @returns {Promise<void>}
+   */
+  async register(tool) {
+    // --- Validate interface ---
+    const required = ['id', 'name', 'version', 'type', 'category', 'schema', 'handler'];
+    for (const field of required) {
+      if (tool[field] === undefined || tool[field] === null) {
+        throw new Error(`Tool registration failed: missing required field '${field}'`);
+      }
+    }
+    if (typeof tool.handler !== 'function') {
+      throw new Error(`Tool '${tool.id}': handler must be a function`);
+    }
+    if (!Object.values(MODULE_TYPES).includes(tool.type)) {
+      throw new Error(`Tool '${tool.id}': invalid type '${tool.type}'. Must be one of: ${Object.values(MODULE_TYPES).join(', ')}`);
+    }
+    if (this._tools.has(tool.id)) {
+      throw new Error(`Tool '${tool.id}' is already registered. Unregister it first.`);
+    }
+
+    // --- Validate schema structure ---
+    if (!tool.schema.input || !tool.schema.output) {
+      throw new Error(`Tool '${tool.id}': schema must have 'input' and 'output'`);
+    }
+
+    // --- Register ---
+    this._tools.set(tool.id, {
+      ...tool,
+      registeredAt: Date.now(),
+      lastInvokedAt: null,
+      lastErrorAt: null,
+    });
+
+    // Category index
+    if (!this._categories.has(tool.category)) {
+      this._categories.set(tool.category, new Set());
+    }
+    this._categories.get(tool.category).add(tool.id);
+
+    // Init counters
+    this._invocationCount.set(tool.id, 0);
+    this._errorCount.set(tool.id, 0);
+
+    // Call init() if present
+    if (typeof tool.init === 'function') {
+      try {
+        await tool.init();
+        log.info(`工具已注册并初始化：${tool.id} v${tool.version} (${tool.type})`);
+      } catch (err) {
+        // Rollback registration on init failure
+        this._tools.delete(tool.id);
+        this._categories.get(tool.category)?.delete(tool.id);
+        this._invocationCount.delete(tool.id);
+        this._errorCount.delete(tool.id);
+        throw new Error(`Tool '${tool.id}' init() failed: ${err.message}`);
+      }
+    } else {
+      log.info(`工具已注册：${tool.id} v${tool.version} (${tool.type})`);
+    }
+
+    bus.emit('tool:registered', { id: tool.id, version: tool.version, type: tool.type });
+  }
+
+  /**
+   * Unregister a tool module.
+   * Calls destroy() if present.
+   */
+  async unregister(toolId) {
+    const tool = this._tools.get(toolId);
+    if (!tool) {
+      throw new Error(`Tool not found: ${toolId}`);
+    }
+
+    if (typeof tool.destroy === 'function') {
+      try {
+        await tool.destroy();
+      } catch (err) {
+        log.warn(`工具 '${toolId}' destroy() 错误：${err.message}`);
+      }
+    }
+
+    this._tools.delete(toolId);
+    this._categories.get(tool.category)?.delete(toolId);
+    this._invocationCount.delete(toolId);
+    this._errorCount.delete(toolId);
+
+    log.info(`工具已注销：${toolId}`);
+    bus.emit('tool:unregistered', { id: toolId });
+  }
+
+  /**
+   * Get a tool by id (without invoking).
+   */
+  get(toolId) {
+    return this._tools.get(toolId) || null;
+  }
+
+  /**
+   * List all registered tools.
+   * @param {object} opts - { category, type } filters
+   */
+  list(opts = {}) {
+    let tools = Array.from(this._tools.values());
+    if (opts.category) {
+      tools = tools.filter(t => t.category === opts.category);
+    }
+    if (opts.type) {
+      tools = tools.filter(t => t.type === opts.type);
+    }
+    return tools.map(t => ({
+      id: t.id,
+      name: t.name,
+      version: t.version,
+      type: t.type,
+      category: t.category,
+      registeredAt: t.registeredAt,
+      lastInvokedAt: t.lastInvokedAt,
+      invocations: this._invocationCount.get(t.id) || 0,
+      errors: this._errorCount.get(t.id) || 0,
+    }));
+  }
+
+  /**
+   * Invoke a tool by id.
+   * This is the main execution path — all tool calls go through here.
+   *
+   * @param {string} toolId - Tool identifier
+   * @param {object} input - Input data (validated against tool.schema.input)
+   * @param {object} ctx - Request context (token, user, requestId, etc.)
+   * @returns {Promise<object>} Tool output (validated against tool.schema.output)
+   */
+  async invoke(toolId, input = {}, ctx = {}) {
+    const tool = this._tools.get(toolId);
+    if (!tool) {
+      throw new Error(`Tool not found: ${toolId}`);
+    }
+
+    const startTime = Date.now();
+    this._invocationCount.set(toolId, (this._invocationCount.get(toolId) || 0) + 1);
+    tool.lastInvokedAt = startTime;
+
+    try {
+      // --- Input validation (lightweight — SchemaGatekeeper does deep validation) ---
+      if (tool.schema.input && tool.schema.input.required) {
+        for (const field of tool.schema.input.required) {
+          if (input[field] === undefined || input[field] === null) {
+            throw new Error(`Missing required input field: '${field}' for tool '${toolId}'`);
+          }
+        }
+      }
+
+      // --- Invoke handler ---
+      const result = await tool.handler(input, ctx);
+
+      const elapsed = Date.now() - startTime;
+      bus.emit('tool:invoked', {
+        id: toolId,
+        success: true,
+        elapsed,
+        ctx: { requestId: ctx.requestId },
+      });
+
+      return result;
+
+    } catch (err) {
+      this._errorCount.set(toolId, (this._errorCount.get(toolId) || 0) + 1);
+      tool.lastErrorAt = Date.now();
+
+      const elapsed = Date.now() - startTime;
+      bus.emit('tool:invoked', {
+        id: toolId,
+        success: false,
+        elapsed,
+        error: err.message,
+        ctx: { requestId: ctx.requestId },
+      });
+
+      log.error(`工具 '${toolId}' 调用失败：${err.message}`);
+      throw err;
+    }
+  }
+
+  /**
+   * Health check for all or specific tools.
+   * @param {string} toolId - If provided, check only this tool
+   * @returns {Promise<object>} { healthy: boolean, tools: [{ id, healthy, details }] }
+   */
+  async healthCheck(toolId) {
+    const tools = toolId
+      ? [this._tools.get(toolId)].filter(Boolean)
+      : Array.from(this._tools.values());
+
+    const results = [];
+    let allHealthy = true;
+
+    for (const tool of tools) {
+      try {
+        if (typeof tool.healthCheck === 'function') {
+          const result = await tool.healthCheck();
+          results.push({ id: tool.id, healthy: result.healthy, details: result.details || {} });
+          if (!result.healthy) allHealthy = false;
+        } else {
+          results.push({ id: tool.id, healthy: true, details: { note: 'no healthCheck defined' } });
+        }
+      } catch (err) {
+        results.push({ id: tool.id, healthy: false, details: { error: err.message } });
+        allHealthy = false;
+      }
+    }
+
+    return { healthy: allHealthy, tools: results };
+  }
+
+  /**
+   * Reload a dynamic tool (unregister + re-register).
+   * Only works for 'dynamic' type tools.
+   */
+  async reload(toolId) {
+    const tool = this._tools.get(toolId);
+    if (!tool) {
+      throw new Error(`Tool not found: ${toolId}`);
+    }
+    if (tool.type !== MODULE_TYPES.DYNAMIC) {
+      throw new Error(`Tool '${toolId}' is type '${tool.type}', only 'dynamic' tools can be reloaded`);
+    }
+
+    log.info(`正在重新加载工具：${toolId}`);
+    const toolDef = { ...tool };
+    delete toolDef.registeredAt;
+    delete toolDef.lastInvokedAt;
+    delete toolDef.lastErrorAt;
+
+    await this.unregister(toolId);
+    await this.register(toolDef);
+    bus.emit('tool:reloaded', { id: toolId });
+  }
+
+  /**
+   * Get a manifest of all tools (for client discovery).
+   * Returns a compact list suitable for sending to clients.
+   */
+  getManifest() {
+    return this.list().map(t => ({
+      id: t.id,
+      name: t.name,
+      version: t.version,
+      category: t.category,
+      type: t.type,
+    }));
+  }
+
+  /**
+   * Get statistics for monitoring.
+   */
+  getStats() {
+    const tools = Array.from(this._tools.values());
+    return {
+      totalTools: tools.length,
+      byType: Object.values(MODULE_TYPES).reduce((acc, type) => {
+        acc[type] = tools.filter(t => t.type === type).length;
+        return acc;
+      }, {}),
+      byCategory: Object.fromEntries(
+        Array.from(this._categories.entries()).map(([cat, set]) => [cat, set.size])
+      ),
+      totalInvocations: Array.from(this._invocationCount.values()).reduce((a, b) => a + b, 0),
+      totalErrors: Array.from(this._errorCount.values()).reduce((a, b) => a + b, 0),
+    };
+  }
+}
+
+// Singleton instance
+const registry = new ToolRegistry();
+
+module.exports = { ToolRegistry, registry, MODULE_TYPES, TOOL_INTERFACE };

package/templates/ci/github-actions.yml

@@ -0,0 +1,60 @@
+# DevAssist GitHub Actions CI 模板
+# 复制到 .github/workflows/devassist.yml 使用
+
+name: DevAssist Check
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  devassist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # 完整历史，用于 diff 检查
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install DevAssist
+        run: npm install -g devassist
+
+      - name: Initialize DevAssist (if not already)
+        run: devassist init --force
+        continue-on-error: true
+
+      - name: Run diff check (only changed files)
+        run: devassist diff --base origin/${{ github.base_ref || 'main' }} --json --fail-on block
+        id: diff-check
+        continue-on-error: true
+
+      - name: Run full check
+        if: steps.diff-check.outcome != 'success'
+        run: devassist check --json
+
+      - name: Generate report
+        if: always()
+        run: devassist report
+
+      - name: Upload report artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: devassist-report
+          path: .devassist/reports/latest.html
+          retention-days: 30
+
+      # 可选：AI 分析（需要 API Key）
+      # - name: AI Analysis
+      #   if: always() && env.DASHSCOPE_API_KEY != ''
+      #   env:
+      #     DASHSCOPE_API_KEY: ${{ secrets.DASHSCOPE_API_KEY }}
+      #   run: |
+      #     devassist ai --setup --provider qwen --key $DASHSCOPE_API_KEY
+      #     devassist ai --analyze

package/templates/ci/gitlab-ci.yml

@@ -0,0 +1,30 @@
+# DevAssist GitLab CI 模板
+# 复制到 .gitlab-ci.yml 的相应位置使用
+
+devassist-check:
+  stage: test
+  image: node:20
+  before_script:
+    - npm install -g devassist
+    - devassist init --force || true
+  script:
+    # 检查变更文件
+    - devassist diff --staged --json --fail-on block || EXIT_CODE=$?
+    # 如果 diff 失败，运行完整检查
+    - if [ "$EXIT_CODE" != "0" ]; then devassist check --json; fi
+    # 生成报告
+    - devassist report
+  after_script:
+    - |
+      if [ -f .devassist/reports/latest.html ]; then
+        echo "DevAssist 报告已生成：.devassist/reports/latest.html"
+      fi
+  artifacts:
+    when: always
+    paths:
+      - .devassist/reports/
+    expire_in: 30 days
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH == "main"
+    - if: $CI_COMMIT_BRANCH == "develop"

package/templates/ci/pre-commit-hook.sh

@@ -0,0 +1,18 @@
+#!/bin/sh
+# DevAssist pre-commit hook 模板
+# 安装方法：cp templates/ci/pre-commit-hook.sh .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit
+
+echo "[DevAssist] 正在运行提交前检查..."
+
+# 运行变更文件检查（只检查暂存文件，速度更快）
+node "$(dirname "$0")/../../node_modules/devassist/bin/devassist.js" diff --staged --fail-on block
+
+if [ $? -ne 0 ]; then
+  echo ""
+  echo "[DevAssist] 提交已阻断。修复上述问题后重试。"
+  echo "[DevAssist] 或使用 git commit --no-verify 跳过检查（不推荐）。"
+  exit 1
+fi
+
+echo "[DevAssist] 检查通过。"
+exit 0

package/templates/git-hooks/pre-commit

@@ -0,0 +1,61 @@
+#!/bin/sh
+# DevAssist pre-commit hook
+#
+# This hook runs devassist check before allowing a commit.
+# It catches code quality issues, convention violations, and impact analysis
+# problems BEFORE they enter your codebase.
+#
+# To bypass: git commit --no-verify (use sparingly!)
+#
+# Installation:
+#   Method 1: devassist init (auto-installs if .git exists)
+#   Method 2: cp this file to .git/hooks/pre-commit && chmod +x
+
+set -e
+
+# Find the devassist binary
+DEVASSIST_BIN=""
+candidates=(
+  "./node_modules/.bin/devassist"
+  "devassist"
+  "npx devassist"
+)
+
+for cmd in "${candidates[@]}"; do
+  if command -v "$cmd" &>/dev/null || [ -x "$cmd" ]; then
+    DEVASSIST_BIN="$cmd"
+    break
+  fi
+done
+
+# Fall back to direct node execution
+if [ -z "$DEVASSIST_BIN" ]; then
+  SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+  DEVASSIST_JS="$SCRIPT_DIR/../../devassist/bin/devassist.js"
+  if [ -f "$DEVASSIST_JS" ]; then
+    DEVASSIST_BIN="node $DEVASSIST_JS"
+  fi
+fi
+
+if [ -z "$DEVASSIST_BIN" ]; then
+  echo "[DevAssist] Warning: devassist not found. Skipping pre-commit checks."
+  echo "[DevAssist] Install with: npm install -g devassist"
+  exit 0
+fi
+
+echo "[DevAssist] Running pre-commit checks..."
+
+# Run check in pre-commit mode (faster, skips AI analysis)
+$DEVASSIST_BIN check --pre-commit 2>&1
+RESULT=$?
+
+if [ $RESULT -ne 0 ]; then
+  echo ""
+  echo "[DevAssist] ❌ Commit BLOCKED — check failures detected."
+  echo "[DevAssist] Fix the issues above, or bypass with: git commit --no-verify"
+  echo ""
+  exit 1
+fi
+
+echo "[DevAssist] ✅ All checks passed."
+exit 0