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/installation/faq.md DELETED Viewed

@@ -1,611 +0,0 @@
-<!-- 翻译：zh-CN 原文：/docs/installation/faq.md 最后同步：2026-02-22 -->
-# SINAPSE 常见问题
-> 🌐 [EN](../../installation/faq.md) | [PT](../pt/installation/faq.md) | [ES](../es/installation/faq.md)
-**版本:** 2.1.0
-**最后更新:** 2025-01-24
----
-## 目录
-- [安装相关问题](#安装相关问题)
-- [更新与维护](#更新与维护)
-- [离线与隔离环境使用](#离线与隔离环境使用)
-- [IDE 与配置](#ide-与配置)
-- [代理与工作流](#代理与工作流)
-- [Squad](#squad)
-- [高级用法](#高级用法)
----
-## 安装相关问题
-### 问题 1：为什么使用 npx 而不是 npm install -g？
-**答案:** 我们推荐使用 `npx @sinapse/sinapse-ai install` 而不是全局安装，原因如下：
-1. **始终最新版本**: npx 自动获取最新版本
-2. **无全局污染**: 不会添加到全局 npm 包
-3. **项目隔离**: 每个项目可以拥有自己的版本
-4. **无权限问题**: 避免常见的全局 npm 权限问题
-5. **CI/CD 友好**: 在自动化管道中无缝工作
-**如果您更喜欢全局安装：**
-```bash
-npm install -g @sinapse/sinapse-ai
-@sinapse/sinapse-ai install
-```
----
-### 问题 2：系统要求是什么？
-**答案:**
-| 组件          | 最小版本                        | 推荐版本    |
-| ------------- | ------------------------------- | ----------- |
-| **Node.js**   | 18.0.0                          | 20.x LTS    |
-| **npm**       | 9.0.0                           | 10.x        |
-| **磁盘空间**  | 100 MB                          | 500 MB      |
-| **RAM**       | 2 GB                            | 8 GB        |
-| **OS**        | Windows 10, macOS 12, Ubuntu 20.04 | 最新版本 |
-**检查您的系统：**
-```bash
-node --version  # 应为 18+
-npm --version   # 应为 9+
-```
----
-### 问题 3：我可以在现有项目中安装 SINAPSE 吗？
-**答案:** 可以！SINAPSE 为绿地和棕地项目设计。
-**对于现有项目：**
-```bash
-cd /path/to/existing-project
-npx @sinapse/sinapse-ai install
-```
-安装程序将：
-- 创建 `.sinapse-ai/` 目录（框架文件）
-- 创建 IDE 配置（`.claude/`、`.cursor/` 等）
-- 不修改您的现有源代码
-- 不覆盖现有文档，除非您选择
-**重要:** 如果您有现有的 `.claude/` 或 `.cursor/` 目录，安装程序会在修改前询问。
----
-### 问题 4：安装需要多长时间？
-**答案:**
-| 场景                | 时间          |
-| ------------------- | ------------- |
-| **首次安装**        | 2-5 分钟      |
-| **更新现有安装**    | 1-2 分钟      |
-| **仅安装启动 Squad** | 30-60 秒     |
-影响安装时间的因素：
-- 互联网连接速度
-- npm 缓存状态
-- 选中的 IDE 数量
-- 选中的启动 Squad 数量
----
-### 问题 5：SINAPSE 在我的项目中创建了哪些文件？
-**答案:** SINAPSE 创建以下结构：
-```
-your-project/
-├── .sinapse-ai/                 # 框架核心（200+ 文件）
-│   ├── agents/                 # 11+ 个代理定义
-│   ├── tasks/                  # 60+ 个任务工作流
-│   ├── templates/              # 20+ 个文档模板
-│   ├── checklists/             # 验证清单
-│   ├── scripts/                # 实用脚本
-│   └── core-config.yaml        # 框架配置
-│
-├── .claude/                    # Claude Code（如果选中）
-│   └── commands/SINAPSE/agents/   # 代理斜杠命令
-│
-├── .cursor/                    # Cursor（如果选中）
-│   └── rules/                  # 代理规则
-│
-├── docs/                       # 文档结构
-│   ├── stories/                # 开发故事
-│   ├── architecture/           # 架构文档
-│   └── prd/                    # 产品需求
-│
-└── Squads/            # （如果安装）
-    └── hybrid-ops/             # HybridOps 包
-```
----
-## 更新与维护
-### 问题 6：如何将 SINAPSE 更新到最新版本？
-**答案:**
-```bash
-# 通过 npx 更新（推荐）
-npx @sinapse/sinapse-ai update
-# 或重新安装最新版本
-npx @sinapse/sinapse-ai install --force-upgrade
-# 检查当前版本
-npx @sinapse/sinapse-ai status
-```
-**更新的内容：**
-- `.sinapse-ai/` 文件（代理、任务、模板）
-- IDE 配置
-- 启动 Squad（如果安装）
-**保留的内容：**
-- `core-config.yaml` 中的自定义修改
-- 您的文档（`docs/`）
-- 您的源代码
----
-### 问题 7：应该多久更新一次？
-**答案:** 我们建议：
-| 更新类型        | 频率       | 命令                           |
-| --------------- | ---------- | ------------------------------ |
-| **安全补丁**    | 立即       | `npx @sinapse/sinapse-ai update` |
-| **次要更新**    | 每月       | `npx @sinapse/sinapse-ai update` |
-| **主要版本**    | 每季度     | 先查看变更日志                 |
-**检查更新：**
-```bash
-npm show @sinapse/sinapse-ai version
-npx @sinapse/sinapse-ai status
-```
----
-### 问题 8：我可以回滚到之前的版本吗？
-**答案:** 可以，有多个选项：
-**选项 1：重新安装特定版本**
-```bash
-npx @sinapse/sinapse-ai@1.1.0 install --force-upgrade
-```
-**选项 2：使用 Git 恢复**
-```bash
-# 如果 .sinapse-ai 在 git 中跟踪
-git checkout HEAD~1 -- .sinapse-ai/
-```
-**选项 3：从备份恢复**
-```bash
-# 安装程序创建备份
-mv .sinapse-ai .sinapse-ai.failed
-mv .sinapse-ai.backup .sinapse-ai
-```
----
-## 离线与隔离环境使用
-### 问题 9：我可以在没有互联网的情况下使用 SINAPSE 吗？
-**答案:** 可以，但需要一些准备：
-**初始设置（需要互联网）：**
-```bash
-# 联网时安装一次
-npx @sinapse/sinapse-ai install
-# 打包以供离线使用
-tar -czvf sinapse-offline.tar.gz .sinapse-ai/ .claude/ .cursor/
-```
-**在隔离机器上：**
-```bash
-# 解压软件包
-tar -xzvf sinapse-offline.tar.gz
-# SINAPSE 代理可在没有互联网的情况下工作
-# （它们不需要外部 API 调用）
-```
-**没有互联网的限制：**
-- 无法更新到新版本
-- MCP 集成（ClickUp、GitHub）将不工作
-- 无法获取库文档（Context7）
----
-### 问题 10：我如何将 SINAPSE 转移到隔离环境？
-**答案:**
-1. **在联网机器上：**
-   ```bash
-   # 安装并打包
-   npx @sinapse/sinapse-ai install
-   cd your-project
-   tar -czvf sinapse-transfer.tar.gz .sinapse-ai/ .claude/ .cursor/ docs/
-   ```
-2. **通过 USB、安全传输等转移归档文件**
-3. **在隔离机器上：**
-   ```bash
-   cd your-project
-   tar -xzvf sinapse-transfer.tar.gz
-   ```
-4. **如果需要，手动配置 IDE**（路径可能不同）
----
-## IDE 与配置
-### 问题 11：SINAPSE 支持哪些 IDE？
-**答案:**
-| IDE                | 状态       | 代理激活           |
-| ------------------ | ---------- | ------------------- |
-| **Claude Code**    | 完全支持   | `/dev`、`/qa` 等   |
-| **Cursor**         | 完全支持   | `@dev`、`@qa` 等   |
-| **Gemini CLI**     | 完全支持   | 在提示中提及       |
-| **GitHub Copilot** | 完全支持   | 聊天模式           |
-**为新 IDE 添加支持:** 使用 IDE 的代理/规则规范打开 GitHub 问题。
----
-### 问题 12：我可以为多个 IDE 配置 SINAPSE 吗？
-**答案:** 可以！在安装过程中选择多个 IDE：
-**交互式：**
-```
-? Which IDE(s) do you want to configure?
-❯ ◉ Cursor
-  ◉ Claude Code
-```
-**命令行：**
-```bash
-npx @sinapse/sinapse-ai install --ide cursor,claude-code
-```
-每个 IDE 获得其自己的配置目录：
-- `.cursor/rules/` 用于 Cursor
-- `.claude/commands/` 用于 Claude Code
----
-### 问题 13：我如何为新团队成员配置 SINAPSE？
-**答案:**
-如果 `.sinapse-ai/` 已提交到您的仓库：
-```bash
-# 新团队成员只需克隆
-git clone your-repo
-cd your-repo
-# 可选择配置他们喜欢的 IDE
-npx @sinapse/sinapse-ai install --ide cursor
-```
-如果 `.sinapse-ai/` 未提交：
-```bash
-git clone your-repo
-cd your-repo
-npx @sinapse/sinapse-ai install
-```
-**最佳实践:** 将 `.sinapse-ai/` 提交到您的仓库以共享一致的代理配置。
----
-## 代理与工作流
-### 问题 14：包含了哪些代理？
-**答案:** SINAPSE 包括 11+ 个专门代理：
-| 代理           | 角色             | 最适合的工作                      |
-| -------------- | ---------------- | --------------------------------- |
-| `dev`          | 全栈开发者       | 代码实现、调试                    |
-| `qa`           | QA 工程师        | 测试、代码审查                    |
-| `architect`    | 系统架构师       | 设计、架构决策                    |
-| `pm`           | 项目经理         | 规划、跟踪                        |
-| `po`           | 产品所有者       | 积压工作、需求                    |
-| `sm`           | Scrum 主管       | 便利化、冲刺管理                  |
-| `analyst`      | 业务分析师       | 需求分析                         |
-| `ux-expert`    | UX 设计师        | 用户体验设计                      |
-| `data-engineer` | 数据工程师       | 数据管道、ETL                     |
-| `devops`       | DevOps 工程师    | CI/CD、部署                       |
-| `db-sage`      | 数据库架构师     | 模式设计、查询                    |
----
-### 问题 15：如何创建自定义代理？
-**答案:**
-1. **复制现有代理：**
-   ```bash
-   cp .sinapse-ai/agents/dev.md .sinapse-ai/agents/my-agent.md
-   ```
-2. **编辑 YAML 前置：**
-   ```yaml
-   agent:
-     name: MyAgent
-     id: my-agent
-     title: My Custom Agent
-     icon: 🔧
-   persona:
-     role: Expert in [your domain]
-     style: [communication style]
-   ```
-3. **添加到 IDE 配置：**
-   ```bash
-   npx @sinapse/sinapse-ai install --ide claude-code
-   ```
-4. **激活:** `/my-agent` 或 `@my-agent`
----
-### 问题 16：什么是"yolo 模式"？
-**答案:** Yolo 模式是自主开发模式，其中代理：
-- 不需分步确认即可实现故事任务
-- 根据故事需求自主做出决策
-- 在 `.ai/decision-log-{story-id}.md` 中记录所有决策
-- 可随时停止
-**启用 yolo 模式：**
-```bash
-/dev
-*develop-yolo docs/stories/your-story.md
-```
-**何时使用：**
-- 对于需求明确、接受条件清晰的故事
-- 当您信任代理的决策制定时
-- 对于重复性任务
-**何时不使用：**
-- 对于复杂的架构变更
-- 当需求模糊时
-- 对于生产关键代码
----
-## Squad
-### 问题 17：什么是 Squad？
-**答案:** 启动 Squad 是可选的扩展，用于扩展 SINAPSE 功能：
-| 包            | 功能                                                      |
-| -------------- | --------------------------------------------------------- |
-| **hybrid-ops** | ClickUp 集成、流程自动化、专门工作流 |
-**安装 Squad：**
-```bash
-npx @sinapse/sinapse-ai install --Squads hybrid-ops
-```
-**列出可用的 Squad：**
-```bash
-npx @sinapse/sinapse-ai install
-```
----
-### 问题 18：我可以创建自己的 Squad 吗？
-**答案:** 可以！启动 Squad 遵循此结构：
-```
-my-expansion/
-├── pack.yaml           # 包清单
-├── README.md           # 文档
-├── agents/             # 自定义代理
-│   └── my-agent.md
-├── tasks/              # 自定义任务
-│   └── my-task.md
-├── templates/          # 自定义模板
-│   └── my-template.yaml
-└── workflows/          # 自定义工作流
-    └── my-workflow.yaml
-```
-**pack.yaml 示例：**
-```yaml
-name: my-expansion
-version: 1.0.0
-description: My custom Squad
-dependencies:
-  sinapse-ai: ">=1.0.0"
-agents:
-  - my-agent
-tasks:
-  - my-task
-```
----
-## 高级用法
-### 问题 19：如何将 SINAPSE 与 CI/CD 集成？
-**答案:**
-**GitHub Actions 示例：**
-```yaml
-name: CI with SINAPSE
-on: [push]
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
-        with:
-          node-version: "18"
-      - run: npx @sinapse/sinapse-ai install --full --ide claude-code
-      - run: npm test
-```
-**GitLab CI 示例：**
-```yaml
-test:
-  image: node:18
-  script:
-    - npx @sinapse/sinapse-ai install --full
-    - npm test
-```
----
-### 问题 20：如何自定义 core-config.yaml？
-**答案:** `core-config.yaml` 文件控制框架行为：
-```yaml
-# 文档分片
-prd:
-  prdSharded: true
-  prdShardedLocation: docs/prd
-# 故事位置
-devStoryLocation: docs/stories
-# dev 代理加载的文件
-devLoadAlwaysFiles:
-  - docs/framework/coding-standards.md
-  - docs/framework/tech-stack.md
-# Git 配置
-git:
-  showConfigWarning: true
-  cacheTimeSeconds: 300
-# 代理问候语中的项目状态
-projectStatus:
-  enabled: true
-  showInGreeting: true
-```
-**编辑后，重启 IDE 以应用更改。**
----
-### 问题 21：我如何为 SINAPSE 做贡献？
-**答案:**
-1. **Fork 仓库:** https://github.com/SinapseAI/sinapse-ai
-2. **创建功能分支：**
-   ```bash
-   git checkout -b feature/my-feature
-   ```
-3. **按照编码标准做出更改：**
-   - 阅读 `docs/framework/coding-standards.md`
-   - 为新功能添加测试
-   - 更新文档
-4. **提交 pull request：**
-   - 描述您的更改
-   - 链接到相关问题
-   - 等待审查
-**欢迎的贡献类型：**
-- 错误修复
-- 新代理
-- 文档改进
-- 启动 Squad
-- IDE 集成
----
-### 问题 22：我可以在哪里获得帮助？
-**答案:**
-| 资源            | 链接                                                   |
-| --------------- | ------------------------------------------------------ |
-| **文档**        | `docs/` 在您的项目中                                   |
-| **故障排除**    | [troubleshooting.md](./troubleshooting.md)             |
-| **GitHub Issues** | https://github.com/SinapseAI/sinapse-ai/issues |
-| **源代码**      | https://github.com/SinapseAI/sinapse-ai        |
-**在寻求帮助之前：**
-1. 检查此 FAQ
-2. 检查 [故障排除指南](./troubleshooting.md)
-3. 搜索现有 GitHub 问题
-4. 在您的问题中包含系统信息和错误消息
----
-## 相关文档
-- [故障排除指南](./troubleshooting.md)
-- [编码标准](../../framework/coding-standards.md)