npm - sinapse-ai - Versions diffs - 5.0.8 → 6.0.1 - Mend

sinapse-ai 5.0.8 → 6.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (660) hide show

package/docs/zh/architecture/tech-stack.md DELETED Viewed

@@ -1,808 +0,0 @@
-<!-- 翻译: ZH-CN | 原文: /docs/en/architecture/tech-stack.md | 同步: 2026-02-22 -->
-# SINAPSE 技术栈
-> 🌐 [EN](../../architecture/tech-stack.md) | [PT](../../pt/architecture/tech-stack.md) | **ZH** | [ES](../../es/architecture/tech-stack.md)
----
-> ⚠️ **已弃用**: 本文件仅为向后兼容性而维护。
->
-> **官方版本:** [docs/framework/tech-stack.md](../framework/tech-stack.md)
->
-> 本文件将在 2026 Q2 完成 `docs/framework/` 整合后移除。
----
-# SINAPSE 技术栈
-**版本:** 1.1
-**最后更新:** 2025-12-14
-**状态:** 已弃用 - 参见 docs/framework/tech-stack.md
-**迁移通知:** 本文档将在 2026 Q2 迁移到 `SinapseAI/sinapse-ai` 仓库 (参见决策 005)
----
-## 📋 目录
-- [概述](#概述)
-- [核心运行时](#核心运行时)
-- [语言和转译器](#语言和转译器)
-- [核心依赖](#核心依赖)
-- [开发工具](#开发工具)
-- [测试框架](#测试框架)
-- [构建和部署](#构建和部署)
-- [外部集成](#外部集成)
-- [迁移后的未来栈](#迁移后的未来栈)
----
-## 概述
-SINAPSE 构建在现代 JavaScript/TypeScript 和 Node.js 运行时上，优化用于开发具有交互式 UX 和代理编排功能的跨平台 CLI。
-**理念:**
-- 尽可能使用**成熟技术** (经过验证和稳定的依赖)
-- 仅在必要时选择**创新技术** (性能、DX 改进)
-- 最小化依赖 (降低供应链风险)
-- 优先跨平台 (Windows、macOS、Linux)
----
-## 核心运行时
-### Node.js
-```yaml
-版本: 18.0.0+
-LTS: 是 (LTS 有效期至 2025 年 4 月)
-原因: 稳定的 async/await 支持、fetch API、ES2022
-```
-**为什么选择 Node.js 18+:**
-- ✅ 原生 `fetch()` API (无需 axios/node-fetch)
-- ✅ 对 ES2022 模块的支持 (顶级 await)
-- ✅ V8 10.2+ (性能改进)
-- ✅ 活跃的 LTS 支持 (安全补丁)
-- ✅ 跨平台 (Windows/macOS/Linux)
-**包管理器:**
-```yaml
-主要: npm 9.0.0+
-备选: yarn/pnpm (用户选择)
-锁定文件: package-lock.json
-```
----
-## 语言和转译器
-### JavaScript (主要)
-```yaml
-标准: ES2022
-模块系统: CommonJS (require/module.exports)
-未来: 计划迁移到 ESM (故事 6.2.x)
-```
-**为什么选择 ES2022:**
-- ✅ 类字段和私有方法
-- ✅ 顶级 await
-- ✅ 错误 cause
-- ✅ 数组 Array.at() 方法
-- ✅ Object.hasOwn()
-### TypeScript (类型定义)
-```yaml
-版本: 5.9.3
-用途: 仅类型定义 (.d.ts 文件)
-编译: 不使用 (纯 JS 运行时)
-未来: 考虑完全迁移到 TypeScript (Q2 2026)
-```
-**当前的 TypeScript 用途:**
-```typescript
-// index.d.ts - API 公开的类型定义
-export interface AgentConfig {
-  id: string;
-  name: string;
-  enabled: boolean;
-  dependencies?: string[];
-}
-export function executeAgent(agentId: string, args: Record<string, any>): Promise<any>;
-```
-**TypeScript 配置:**
-```json
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "commonjs",
-    "lib": ["ES2022"],
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "declaration": true,
-    "outDir": "./dist"
-  }
-}
-```
----
-## 核心依赖
-### CLI 和交互式 UX
-#### @clack/prompts (^0.11.0)
-**目的:** 现代化的 CLI 提示，具有优雅的 UX
-**用途:** 交互式向导、用户输入收集
-**优势:** 世界级的 UX、微调动画、进度条
-```javascript
-import { select, confirm, spinner } from '@clack/prompts';
-const agent = await select({
-  message: '选择代理:',
-  options: [
-    { value: 'dev', label: '💻 Developer' },
-    { value: 'qa', label: '🧪 QA Engineer' },
-  ],
-});
-```
-#### chalk (^4.1.2)
-**目的:** 终端字符串样式化
-**用途:** 彩色输出、格式化
-**优势:** 跨平台、零依赖、API 稳定
-```javascript
-const chalk = require('chalk');
-console.log(chalk.green('✅ 代理激活成功'));
-console.log(chalk.red('❌ 任务失败'));
-```
-#### picocolors (^1.1.1)
-**目的:** 轻量级颜色库 (比 chalk 更快的替代品)
-**用途:** 性能关键的彩色输出
-**优势:** 比 chalk 小 14 倍，快 2 倍
-```javascript
-const pc = require('picocolors');
-console.log(pc.green('✅ 快速输出'));
-```
-#### ora (^5.4.1)
-**目的:** 终端加载动画
-**用途:** 加载指示器、异步操作
-**优势:** 美观的加载动画、可定制、广泛使用
-```javascript
-const ora = require('ora');
-const spinner = ora('加载代理中...').start();
-await loadAgent();
-spinner.succeed('代理已加载');
-```
-### 文件系统和路径操作
-#### fs-extra (^11.3.2)
-**目的:** 改进的文件系统操作
-**用途:** 文件复制、目录创建、JSON 读/写
-**优势:** 基于 Promise、相对于原生 `fs` 的额外工具
-```javascript
-const fs = require('fs-extra');
-await fs.copy('source', 'dest');
-await fs.ensureDir('path/to/dir');
-await fs.outputJson('config.json', data);
-```
-#### glob (^11.0.3)
-**目的:** 文件模式匹配
-**用途:** 按模式查找文件 (例: `*.md`、`**/*.yaml`)
-**优势:** 快速、支持 gitignore 模式
-```javascript
-const { glob } = require('glob');
-const stories = await glob('docs/stories/**/*.md');
-```
-### YAML 处理
-#### yaml (^2.8.1)
-**目的:** YAML 解析和序列化
-**用途:** 代理配置、工作流、模板
-**优势:** 快速、符合规范、保留注释
-```javascript
-const YAML = require('yaml');
-const agent = YAML.parse(fs.readFileSync('agent.yaml', 'utf8'));
-```
-#### js-yaml (^4.1.0)
-**目的:** 替代 YAML 解析器 (旧版支持)
-**用途:** 解析旧的 YAML 文件
-**优势:** API 不同、用于旧代码
-```javascript
-const yaml = require('js-yaml');
-const doc = yaml.load(fs.readFileSync('config.yaml', 'utf8'));
-```
-**迁移说明:** 整合为单个 YAML 库 (故事 6.2.x)
-### Markdown 处理
-#### @kayvan/markdown-tree-parser (^1.5.0)
-**目的:** 将 markdown 解析为 AST
-**用途:** 故事解析、文档结构分析
-**优势:** 轻量级、快速、支持 GFM
-```javascript
-const { parseMarkdown } = require('@kayvan/markdown-tree-parser');
-const ast = parseMarkdown(markdownContent);
-```
-### 流程执行
-#### execa (^9.6.0)
-**目的:** 改进的 child_process
-**用途:** 执行 git、npm、外部 CLI 工具
-**优势:** 跨平台、基于 Promise、更好的错误处理
-```javascript
-const { execa } = require('execa');
-const { stdout } = await execa('git', ['status']);
-```
-### 命令行解析
-#### commander (^14.0.1)
-**目的:** CLI 框架
-**用途:** 命令行参数解析、子命令
-**优势:** 行业标准、功能丰富、TypeScript 支持
-```javascript
-const { Command } = require('commander');
-const program = new Command();
-program
-  .command('agent <name>')
-  .description('激活一个代理')
-  .action((name) => {
-    console.log(`激活代理: ${name}`);
-  });
-```
-#### inquirer (^8.2.6)
-**目的:** 交互式命令行提示
-**用途:** 用户输入收集、向导
-**优势:** 丰富的提示类型、验证支持
-```javascript
-const inquirer = require('inquirer');
-const answers = await inquirer.prompt([
-  {
-    type: 'list',
-    name: 'agent',
-    message: '选择代理:',
-    choices: ['dev', 'qa', 'architect'],
-  },
-]);
-```
-### 沙箱和安全
-#### isolated-vm (^5.0.4)
-**目的:** V8 隔离区用于沙箱 JavaScript 执行
-**用途:** 安全执行用户脚本、任务执行
-**优势:** 安全隔离、内存限制、超时控制
-```javascript
-const ivm = require('isolated-vm');
-const isolate = new ivm.Isolate({ memoryLimit: 128 });
-const context = await isolate.createContext();
-```
-### 验证
-#### validator (^13.15.15)
-**目的:** 字符串验证和清理
-**用途:** 输入验证 (URL、邮箱等)
-**优势:** 全面、测试充分、无依赖
-```javascript
-const validator = require('validator');
-if (validator.isURL(url)) {
-  // URL 有效
-}
-```
-#### semver (^7.7.2)
-**目的:** 语义版本解析和比较
-**用途:** 版本检查、依赖解析
-**优势:** NPM 标准、充分测试
-```javascript
-const semver = require('semver');
-if (semver.satisfies('1.2.3', '>=1.0.0')) {
-  // 版本兼容
-}
-```
----
-## 开发工具
-### Linting
-#### ESLint (^9.38.0)
-**目的:** JavaScript/TypeScript 代码检查
-**配置:** `.eslintrc.json`
-**插件:**
-- `@typescript-eslint/eslint-plugin` (^8.46.2)
-- `@typescript-eslint/parser` (^8.46.2)
-**主要规则:**
-```javascript
-{
-  "rules": {
-    "no-console": "off",           // CLI 中允许 console
-    "no-unused-vars": "error",
-    "prefer-const": "error",
-    "no-var": "error",
-    "eqeqeq": ["error", "always"]
-  }
-}
-```
-### 格式化
-#### Prettier (^3.5.3)
-**目的:** 代码格式化
-**配置:** `.prettierrc`
-```json
-{
-  "printWidth": 100,
-  "tabWidth": 2,
-  "useTabs": false,
-  "semi": true,
-  "singleQuote": true,
-  "trailingComma": "es5"
-}
-```
-#### yaml-lint (^1.7.0)
-**目的:** YAML 文件检查
-**用途:** 验证代理配置、工作流、模板
-### Git Hooks
-#### husky (^9.1.7)
-**目的:** Git hooks 管理
-**用途:** 提交前 linting、推送前测试
-```json
-{
-  "husky": {
-    "hooks": {
-      "pre-commit": "lint-staged",
-      "pre-push": "npm test"
-    }
-  }
-}
-```
-#### lint-staged (^16.1.1)
-**目的:** 在暂存文件上运行 linters
-**配置:**
-```json
-{
-  "lint-staged": {
-    "**/*.md": ["prettier --write"],
-    "**/*.{js,ts}": ["eslint --fix", "prettier --write"]
-  }
-}
-```
----
-## 测试框架
-### Jest (^30.2.0)
-**目的:** 测试框架
-**用途:** 单元测试、集成测试、覆盖率
-```javascript
-// 测试示例
-describe('AgentExecutor', () => {
-  it('should load agent configuration', async () => {
-    const agent = await loadAgent('dev');
-    expect(agent.name).toBe('developer');
-  });
-});
-```
-**配置:**
-```json
-{
-  "jest": {
-    "testEnvironment": "node",
-    "coverageThreshold": {
-      "global": {
-        "branches": 80,
-        "functions": 80,
-        "lines": 80,
-        "statements": 80
-      }
-    }
-  }
-}
-```
-#### @types/jest (^30.0.0)
-**目的:** Jest 的 TypeScript 类型定义
-**用途:** 使用类型安全的方式编写测试
----
-## 构建和部署
-### 版本化和发布
-#### semantic-release (^25.0.2)
-**目的:** 自动化的语义版本化和发布
-**用途:** 自动发布到 NPM、生成 changelog
-**插件:**
-- `@semantic-release/changelog` (^6.0.3) - 生成 CHANGELOG.md
-- `@semantic-release/git` (^10.0.1) - 提交发布资源
-```json
-{
-  "release": {
-    "branches": ["main"],
-    "plugins": [
-      "@semantic-release/commit-analyzer",
-      "@semantic-release/release-notes-generator",
-      "@semantic-release/changelog",
-      "@semantic-release/npm",
-      "@semantic-release/git"
-    ]
-  }
-}
-```
-### 构建脚本
-```bash
-# 包构建
-npm run build                  # 构建所有包
-npm run build:agents           # 仅构建代理
-npm run build:teams            # 仅构建团队
-# 版本化
-npm run version:patch          # 增加补丁版本
-npm run version:minor          # 增加次要版本
-npm run version:major          # 增加主要版本
-# 发布
-npm run publish:dry-run        # 测试发布
-npm run publish:preview        # 发布为 preview 标签
-npm run publish:stable         # 发布为 latest 标签
-```
----
-## 外部集成
-### MCP 服务器
-SINAPSE 与 Model Context Protocol (MCP) 服务器集成:
-```yaml
-MCP 服务器:
-  - clickup-direct: ClickUp 集成 (任务管理)
-  - context7: 文档查找
-  - exa-direct: Web 搜索
-  - desktop-commander: 文件操作
-  - docker-mcp: Docker 管理
-  - ide: VS Code/Cursor 集成
-```
-**配置:** `.claude.json` 或 `.cursor/settings.json`
-### CLI 工具
-代理使用的外部 CLI 工具:
-```yaml
-GitHub CLI (gh):
-  版本: 2.x+
-  用途: 仓库管理、PR 创建
-  安装: https://cli.github.com
-Railway CLI (railway):
-  版本: 3.x+
-  用途: 部署自动化
-  安装: npm i -g @railway/cli
-Supabase CLI (supabase):
-  版本: 1.x+
-  用途: 数据库迁移、schema 管理
-  安装: npm i -g supabase
-Git:
-  版本: 2.30+
-  用途: 版本控制
-  必需: 是
-```
-### 云服务
-```yaml
-Railway:
-  目的: 应用部署
-  API: Railway CLI
-Supabase:
-  目的: PostgreSQL 数据库 + 身份验证
-  API: Supabase CLI + REST API
-GitHub:
-  目的: 仓库托管、CI/CD
-  API: GitHub CLI (gh) + Octokit
-CodeRabbit:
-  目的: 自动化代码审查
-  API: GitHub App 集成
-```
----
-## 迁移后的未来栈
-**计划于 2026 Q2-Q4** (仓库重组后):
-### ESM 迁移
-```javascript
-// 当前: CommonJS
-const agent = require('./agent');
-module.exports = { executeAgent };
-// 未来: ES Modules
-import { agent } from './agent.js';
-export { executeAgent };
-```
-### 完整的 TypeScript
-```typescript
-// 从 JS + .d.ts 迁移到完整的 TypeScript
-// 优势: 类型安全、更好的重构、改进的 DX
-```
-### 构建工具
-```yaml
-Bundler: esbuild 或 tsup
-原因: 快速构建、树摇晃、最小化
-目标: 单个 CLI 可执行文件 (可选)
-```
-### 测试改进
-```yaml
-E2E 测试: Playwright (浏览器自动化测试)
-性能测试: Benchmark.js (工作流计时)
-```
----
-## 依赖管理
-### 安全审计
-```bash
-# 运行安全审计
-npm audit
-# 自动修复漏洞
-npm audit fix
-# 检查过期的包
-npm outdated
-```
-### 更新策略
-```yaml
-主要更新: 季度审查 (Q1, Q2, Q3, Q4)
-安全补丁: 立即 (48 小时内)
-次要更新: 月度审查
-依赖减少: 持续工作
-```
-### 依赖树
-```bash
-# 查看依赖树
-npm ls --depth=2
-# 查找重复的包
-npm dedupe
-# 分析 bundle 大小
-npx cost-of-modules
-```
----
-## 版本兼容性矩阵
-| 组件       | 版本    | 兼容性   | 说明                  |
-| ---------- | ------- | -------- | --------------------- |
-| **Node.js**      | 18.0.0+ | 必需     | 活跃 LTS              |
-| **npm**          | 9.0.0+  | 必需     | 包管理器              |
-| **TypeScript**   | 5.9.3   | 推荐     | 类型定义              |
-| **ESLint**       | 9.38.0  | 必需     | Linting               |
-| **Prettier**     | 3.5.3   | 必需     | 格式化                |
-| **Jest**         | 30.2.0  | 必需     | 测试                  |
-| **Git**          | 2.30+   | 必需     | 版本控制              |
-| **GitHub CLI**   | 2.x+    | 可选     | 仓库管理              |
-| **Railway CLI**  | 3.x+    | 可选     | 部署                  |
-| **Supabase CLI** | 1.x+    | 可选     | 数据库管理            |
----
-## 性能考虑
-### Bundle 大小
-```bash
-# 生产 bundle 大小 (最小化)
-总计: ~5MB (包括所有依赖)
-# 关键依赖 (总是加载):
-- commander: 120KB
-- chalk: 15KB
-- yaml: 85KB
-- fs-extra: 45KB
-# 可选依赖 (延迟加载):
-- inquirer: 650KB (仅交互模式)
-- @clack/prompts: 180KB (仅向导模式)
-```
-### 初始化时间
-```yaml
-冷启动: ~200ms (初始加载)
-热启动: ~50ms (模块缓存)
-Yolo 模式: ~100ms (跳过验证)
-优化策略:
-  - 延迟加载重型依赖
-  - 缓存解析的 YAML 配置
-  - 有条件地使用 require()
-```
-### 内存使用
-```yaml
-基线: 30MB (Node.js + SINAPSE core)
-代理执行: +10MB (每个代理)
-故事处理: +20MB (markdown 解析)
-峰值: ~100MB (典型工作流)
-```
----
-## 特定平台说明
-### Windows
-```yaml
-路径分隔符: 反斜杠 (\) - 规范化为正斜杠 (/)
-行尾: CRLF - Git 配置自动转换
-Shell: PowerShell 或 CMD - execa 处理跨平台
-Node.js: 来自 nodejs.org 的 Windows 安装程序
-```
-### macOS
-```yaml
-路径分隔符: 正斜杠 (/)
-行尾: LF
-Shell: zsh (默认) 或 bash
-Node.js: Homebrew (brew install node@18) 或 nvm
-```
-### Linux
-```yaml
-路径分隔符: 正斜杠 (/)
-行尾: LF
-Shell: bash (默认) 或 zsh
-Node.js: nvm、apt、yum 或官方二进制文件
-```
----
-## 环境变量
-```bash
-# SINAPSE 配置
-SINAPSE_DEBUG=true                    # 启用调试日志
-SINAPSE_CONFIG_PATH=/custom/path      # 自定义配置位置
-SINAPSE_YOLO_MODE=true               # 强制 yolo 模式
-# Node.js
-NODE_ENV=production                # 生产模式
-NODE_OPTIONS=--max-old-space-size=4096  # 增加内存限制
-# 外部服务
-CLICKUP_API_KEY=pk_xxx            # ClickUp 集成
-GITHUB_TOKEN=ghp_xxx              # GitHub API 访问
-RAILWAY_TOKEN=xxx                 # Railway 部署
-SUPABASE_ACCESS_TOKEN=xxx         # Supabase CLI 身份验证
-```
----
-## 相关文档
-- [编码标准](./coding-standards.md)
-- [源树](./source-tree.md)
----
-## 版本历史
-| 版本 | 日期       | 更改                                                                          | 作者             |
-| ---- | ---------- | ----------------------------------------------------------------------------- | ---------------- |
-| 1.0  | 2025-01-15 | 初始技术栈文档                                                                | Aria (architect) |
-| 1.1  | 2025-12-14 | 更新对 SinapseAI/sinapse-ai 的迁移通知、semantic-release 到 v25.0.2 [故事 6.10] | Dex (dev)        |
----
-_这是 SINAPSE 框架的官方模式。所有技术选择应与本栈保持一致。_