deepspider 0.1.0

package/.claude/skills/deepagents-guide/SKILL.md

@@ -0,0 +1,428 @@
+---
+name: deepagents-guide
+description: DeepAgents JS 框架使用指南，包含 Agent 创建、后端存储、子代理、中间件、技能和人机交互配置。
+---
+
+# DeepAgents JS 使用指南
+
+## 概述
+
+DeepAgents 是基于 LangGraph 的 Agent 框架，提供：
+- 模块化中间件架构
+- 多种后端存储方案
+- 子代理任务委派
+- 人机交互审批流程
+- 长期记忆持久化
+- 技能系统
+
+## 快速开始
+
+### 安装
+
+```bash
+npm install deepagents @langchain/core @langchain/anthropic zod
+```
+
+### 基础 Agent
+
+```typescript
+import { createDeepAgent, StateBackend } from "deepagents";
+import { tool } from "@langchain/core/tools";
+import { z } from "zod";
+
+// 定义工具
+const myTool = tool(
+  async ({ input }) => {
+    return `处理结果: ${input}`;
+  },
+  {
+    name: "my_tool",
+    description: "工具描述",
+    schema: z.object({
+      input: z.string().describe("输入参数"),
+    }),
+  }
+);
+
+// 创建 Agent
+const agent = createDeepAgent({
+  name: "my-agent",
+  model: "claude-sonnet-4-20250514",
+  tools: [myTool],
+  systemPrompt: "你是一个助手。",
+  backend: new StateBackend(),
+});
+
+// 调用
+const config = { configurable: { thread_id: "session-1" } };
+const result = await agent.invoke(
+  { messages: [{ role: "user", content: "你好" }] },
+  config
+);
+```
+
+## 后端存储
+
+### StateBackend（默认）
+
+临时存储，数据保存在 Agent 状态中，线程结束后丢失。
+
+```typescript
+import { StateBackend } from "deepagents";
+
+const agent = createDeepAgent({
+  backend: new StateBackend(),
+});
+```
+
+### FilesystemBackend
+
+基于本地文件系统的持久化存储。
+
+```typescript
+import { FilesystemBackend } from "deepagents";
+
+const agent = createDeepAgent({
+  backend: new FilesystemBackend({
+    rootDir: "./agent-data",
+  }),
+});
+```
+
+### StoreBackend
+
+基于 LangGraph Store 的持久化存储，支持跨线程访问。
+
+```typescript
+import { StoreBackend } from "deepagents";
+import { InMemoryStore } from "@langchain/langgraph-checkpoint";
+
+const store = new InMemoryStore();
+
+const agent = createDeepAgent({
+  store,
+  backend: (config) => new StoreBackend(config),
+});
+```
+
+### CompositeBackend（混合存储）
+
+组合多个后端，按路径前缀路由。
+
+```typescript
+import { CompositeBackend, StateBackend, StoreBackend } from "deepagents";
+
+const agent = createDeepAgent({
+  store: new InMemoryStore(),
+  backend: (config) => new CompositeBackend(
+    new StateBackend(config),           // 默认：临时存储
+    { "/memories/": new StoreBackend(config) }  // /memories/ 路径：持久化
+  ),
+});
+```
+
+**路径路由规则：**
+- `/memories/*` → 持久化存储（跨线程）
+- 其他路径 → 临时存储（仅当前线程）
+
+## 中间件
+
+`createDeepAgent` 默认附加三个中间件：
+- `TodoListMiddleware` - 任务规划
+- `FilesystemMiddleware` - 文件操作
+- `SubAgentMiddleware` - 子代理委派
+
+### TodoList 中间件
+
+提供 `write_todos` 工具用于任务管理。
+
+```typescript
+import { createAgent, todoListMiddleware } from "langchain";
+
+const agent = createAgent({
+  model: "claude-sonnet-4-20250514",
+  middleware: [
+    todoListMiddleware({
+      systemPrompt: "使用 write_todos 工具来...",
+    }),
+  ],
+});
+```
+
+### Filesystem 中间件
+
+提供四个文件操作工具：
+- `ls` - 列出文件
+- `read_file` - 读取文件
+- `write_file` - 创建文件
+- `edit_file` - 编辑文件
+
+```typescript
+import { createFilesystemMiddleware } from "deepagents";
+
+const agent = createAgent({
+  middleware: [
+    createFilesystemMiddleware({
+      backend: undefined,  // 可选自定义后端
+      systemPrompt: "当需要保存信息时写入文件系统...",
+      customToolDescriptions: {
+        ls: "使用 ls 工具来...",
+        read_file: "使用 read_file 工具来...",
+      },
+    }),
+  ],
+});
+```
+
+### SubAgent 中间件
+
+启用任务委派给专门的子代理。
+
+```typescript
+import { createSubAgentMiddleware } from "deepagents";
+
+const agent = createAgent({
+  middleware: [
+    createSubAgentMiddleware({
+      defaultModel: "claude-sonnet-4-20250514",
+      defaultTools: [],
+      subagents: [
+        {
+          name: "weather",
+          description: "获取城市天气信息",
+          systemPrompt: "使用 get_weather 工具获取天气",
+          tools: [getWeather],
+          model: "gpt-4o",  // 可选：覆盖默认模型
+        },
+      ],
+    }),
+  ],
+});
+```
+
+## 子代理 (Subagents)
+
+子代理用于任务委派，保持主代理上下文清洁。
+
+### 使用场景
+
+**适合使用：**
+- 多步骤任务（避免主上下文膨胀）
+- 需要专门指令/工具的领域
+- 需要不同模型能力的任务
+
+**不适合：**
+- 简单单步任务
+- 需要中间上下文的场景
+
+### 字典式子代理
+
+```typescript
+const researchSubagent = {
+  name: "research-agent",
+  description: "深度研究问题",
+  systemPrompt: "你是一个优秀的研究员",
+  tools: [internetSearch],
+  model: new ChatAnthropic({ model: "claude-sonnet-4-20250514" }),
+};
+
+const agent = createDeepAgent({
+  model: new ChatAnthropic({ model: "claude-sonnet-4-20250514" }),
+  subagents: [researchSubagent],
+});
+```
+
+### CompiledSubAgent
+
+使用预构建的 LangGraph 图作为子代理：
+
+```typescript
+import { CompiledSubAgent } from "deepagents";
+
+const customSubagent: CompiledSubAgent = {
+  name: "data-analyzer",
+  description: "复杂数据分析任务",
+  runnable: customGraph.compile(),
+};
+```
+
+### 通用子代理
+
+DeepAgents 自动提供 `general-purpose` 子代理：
+- 共享主代理的系统提示
+- 访问相同工具
+- 用于上下文隔离
+
+## 人机交互 (Human-in-the-Loop)
+
+配置敏感工具需要人工审批。
+
+### 配置
+
+```typescript
+import { MemorySaver } from "@langchain/langgraph";
+
+const agent = createDeepAgent({
+  model: "claude-sonnet-4-20250514",
+  tools: [deleteFile, sendEmail],
+  interruptOn: {
+    delete_file: true,
+    send_email: { allowedDecisions: ["approve", "reject"] },
+  },
+  checkpointer: new MemorySaver(),  // 必需！
+});
+```
+
+### 决策类型
+
+- `approve` - 使用原参数执行
+- `edit` - 修改参数后执行
+- `reject` - 跳过工具调用
+
+### 处理中断
+
+```typescript
+import { Command } from "@langchain/langgraph";
+
+let result = await agent.invoke({
+  messages: [{ role: "user", content: "删除 temp.txt" }]
+}, config);
+
+if (result.__interrupt__) {
+  const decisions = [{ type: "approve" }];
+  result = await agent.invoke(
+    new Command({ resume: { decisions } }),
+    config
+  );
+}
+```
+
+## 长期记忆
+
+使用 `CompositeBackend` 实现跨线程持久化。
+
+### 配置
+
+```typescript
+const agent = createDeepAgent({
+  store: new InMemoryStore(),
+  backend: (config) => new CompositeBackend(
+    new StateBackend(config),
+    { "/memories/": new StoreBackend(config) }
+  ),
+});
+```
+
+### 跨线程访问
+
+```typescript
+// 线程 1: 写入
+await agent.invoke({
+  messages: [{ role: "user", content: "保存偏好到 /memories/prefs.txt" }],
+}, { configurable: { thread_id: "thread-1" } });
+
+// 线程 2: 读取（不同会话）
+await agent.invoke({
+  messages: [{ role: "user", content: "读取我的偏好" }],
+}, { configurable: { thread_id: "thread-2" } });
+```
+
+### 用例
+
+- **用户偏好**: `/memories/user_preferences.txt`
+- **自改进指令**: `/memories/instructions.txt`
+- **知识库**: `/memories/research/notes.txt`
+
+## 技能系统 (Skills)
+
+技能是可复用的 Agent 能力，遵循 Agent Skills 标准。
+
+### 目录结构
+
+```
+skills/
+├── langgraph-docs/
+│   └── SKILL.md
+└── arxiv_search/
+    ├── SKILL.md
+    └── arxiv_search.ts
+```
+
+### SKILL.md 格式
+
+```markdown
+---
+name: skill-name
+description: 技能描述
+---
+
+# 技能标题
+
+详细使用说明...
+```
+
+### 配置技能
+
+```typescript
+const agent = await createDeepAgent({
+  skills: ["/skills/"],
+});
+```
+
+### 技能 vs 工具
+
+| 场景 | 选择 |
+|------|------|
+| 大量上下文需要减少 token | 技能 |
+| 多能力捆绑 | 技能 |
+| 简单原子操作 | 工具 |
+
+## 最佳实践
+
+### 子代理描述
+
+```typescript
+// ✅ 好
+"分析财务数据并生成投资建议"
+
+// ❌ 差
+"处理财务"
+```
+
+### 最小化工具集
+
+```typescript
+// ✅ 好: 专注
+const emailAgent = {
+  name: "email-sender",
+  tools: [sendEmail, validateEmail],
+};
+
+// ❌ 差: 分散
+tools: [sendEmail, webSearch, databaseQuery]
+```
+
+### 按任务选模型
+
+```typescript
+const subagents = [
+  { name: "contract-reviewer", model: "claude-sonnet-4-20250514" },
+  { name: "quick-lookup", model: "gpt-4o-mini" },
+];
+```
+
+### 生产环境存储
+
+```typescript
+import { PostgresStore } from "@langchain/langgraph-checkpoint-postgres";
+
+const store = new PostgresStore({
+  connectionString: process.env.DATABASE_URL,
+});
+```
+
+## 参考链接
+
+- [DeepAgents 文档](https://docs.langchain.com/oss/javascript/deepagents)
+- [LangGraph JS](https://langchain-ai.github.io/langgraphjs/)
+- [Agent Skills 标准](https://agentskills.io/)

package/.cursor/commands/trellis-before-backend-dev.md

@@ -0,0 +1,13 @@
+Read the backend development guidelines before starting your development task.
+
+Execute these steps:
+1. Read `.trellis/spec/backend/index.md` to understand available guidelines
+2. Based on your task, read the relevant guideline files:
+   - Database work → `.trellis/spec/backend/database-guidelines.md`
+   - Error handling → `.trellis/spec/backend/error-handling.md`
+   - Logging → `.trellis/spec/backend/logging-guidelines.md`
+   - Type questions → `.trellis/spec/backend/type-safety.md`
+3. Understand the coding standards and patterns you need to follow
+4. Then proceed with your development plan
+
+This step is **mandatory** before writing any backend code.

package/.cursor/commands/trellis-before-frontend-dev.md

@@ -0,0 +1,13 @@
+Read the frontend development guidelines before starting your development task.
+
+Execute these steps:
+1. Read `.trellis/spec/frontend/index.md` to understand available guidelines
+2. Based on your task, read the relevant guideline files:
+   - Component work → `.trellis/spec/frontend/component-guidelines.md`
+   - Hook work → `.trellis/spec/frontend/hook-guidelines.md`
+   - State management → `.trellis/spec/frontend/state-management.md`
+   - Type questions → `.trellis/spec/frontend/type-safety.md`
+3. Understand the coding standards and patterns you need to follow
+4. Then proceed with your development plan
+
+This step is **mandatory** before writing any frontend code.

package/.cursor/commands/trellis-break-loop.md

@@ -0,0 +1,107 @@
+# Break the Loop - Deep Bug Analysis
+
+When debug is complete, use this command for deep analysis to break the "fix bug -> forget -> repeat" cycle.
+
+---
+
+## Analysis Framework
+
+Analyze the bug you just fixed from these 5 dimensions:
+
+### 1. Root Cause Category
+
+Which category does this bug belong to?
+
+| Category | Characteristics | Example |
+|----------|-----------------|---------|
+| **A. Missing Spec** | No documentation on how to do it | New feature without checklist |
+| **B. Cross-Layer Contract** | Interface between layers unclear | API returns different format than expected |
+| **C. Change Propagation Failure** | Changed one place, missed others | Changed function signature, missed call sites |
+| **D. Test Coverage Gap** | Unit test passes, integration fails | Works alone, breaks when combined |
+| **E. Implicit Assumption** | Code relies on undocumented assumption | Timestamp seconds vs milliseconds |
+
+### 2. Why Fixes Failed (if applicable)
+
+If you tried multiple fixes before succeeding, analyze each failure:
+
+- **Surface Fix**: Fixed symptom, not root cause
+- **Incomplete Scope**: Found root cause, didn't cover all cases
+- **Tool Limitation**: grep missed it, type check wasn't strict
+- **Mental Model**: Kept looking in same layer, didn't think cross-layer
+
+### 3. Prevention Mechanisms
+
+What mechanisms would prevent this from happening again?
+
+| Type | Description | Example |
+|------|-------------|---------|
+| **Documentation** | Write it down so people know | Update thinking guide |
+| **Architecture** | Make the error impossible structurally | Type-safe wrappers |
+| **Compile-time** | TypeScript strict, no any | Signature change causes compile error |
+| **Runtime** | Monitoring, alerts, scans | Detect orphan entities |
+| **Test Coverage** | E2E tests, integration tests | Verify full flow |
+| **Code Review** | Checklist, PR template | "Did you check X?" |
+
+### 4. Systematic Expansion
+
+What broader problems does this bug reveal?
+
+- **Similar Issues**: Where else might this problem exist?
+- **Design Flaw**: Is there a fundamental architecture issue?
+- **Process Flaw**: Is there a development process improvement?
+- **Knowledge Gap**: Is the team missing some understanding?
+
+### 5. Knowledge Capture
+
+Solidify insights into the system:
+
+- [ ] Update `.trellis/spec/guides/` thinking guides
+- [ ] Update `.trellis/spec/backend/` or `frontend/` docs
+- [ ] Create issue record (if applicable)
+- [ ] Create feature ticket for root fix
+- [ ] Update check commands if needed
+
+---
+
+## Output Format
+
+Please output analysis in this format:
+
+```markdown
+## Bug Analysis: [Short Description]
+
+### 1. Root Cause Category
+- **Category**: [A/B/C/D/E] - [Category Name]
+- **Specific Cause**: [Detailed description]
+
+### 2. Why Fixes Failed (if applicable)
+1. [First attempt]: [Why it failed]
+2. [Second attempt]: [Why it failed]
+...
+
+### 3. Prevention Mechanisms
+| Priority | Mechanism | Specific Action | Status |
+|----------|-----------|-----------------|--------|
+| P0 | ... | ... | TODO/DONE |
+
+### 4. Systematic Expansion
+- **Similar Issues**: [List places with similar problems]
+- **Design Improvement**: [Architecture-level suggestions]
+- **Process Improvement**: [Development process suggestions]
+
+### 5. Knowledge Capture
+- [ ] [Documents to update / tickets to create]
+```
+
+---
+
+## Core Philosophy
+
+> **The value of debugging is not in fixing the bug, but in making this class of bugs never happen again.**
+
+Three levels of insight:
+1. **Tactical**: How to fix THIS bug
+2. **Strategic**: How to prevent THIS CLASS of bugs
+3. **Philosophical**: How to expand thinking patterns
+
+30 minutes of analysis saves 30 hours of future debugging.

package/.cursor/commands/trellis-check-backend.md

@@ -0,0 +1,13 @@
+Check if the code you just wrote follows the backend development guidelines.
+
+Execute these steps:
+1. Run `git status` to see modified files
+2. Read `.trellis/spec/backend/index.md` to understand which guidelines apply
+3. Based on what you changed, read the relevant guideline files:
+   - Database changes → `.trellis/spec/backend/database-guidelines.md`
+   - Error handling → `.trellis/spec/backend/error-handling.md`
+   - Logging changes → `.trellis/spec/backend/logging-guidelines.md`
+   - Type changes → `.trellis/spec/backend/type-safety.md`
+   - Any changes → `.trellis/spec/backend/quality-guidelines.md`
+4. Review your code against the guidelines
+5. Report any violations and fix them if found