create-deepagent-server 0.0.0-stage → 0.2.0

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 (204) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +292 -2
  3. package/bin/create-deepagent-server.js +27 -0
  4. package/package.json +50 -4
  5. package/src/args.js +195 -0
  6. package/src/cli.js +269 -0
  7. package/src/dependencies.js +34 -0
  8. package/src/prompts.js +86 -0
  9. package/src/registry.js +68 -0
  10. package/src/scaffold.js +181 -0
  11. package/src/setup.js +79 -0
  12. package/src/ui.js +43 -0
  13. package/src/version.js +1 -0
  14. package/src/versions.js +29 -0
  15. package/templates/deepagent/js/deployment/Dockerfile +19 -0
  16. package/templates/deepagent/js/scripts/check.js +97 -0
  17. package/templates/deepagent/js/scripts/dev.js +40 -0
  18. package/templates/deepagent/js/src/agents/factory.js +11 -0
  19. package/templates/deepagent/js/src/agents/index.js +4 -0
  20. package/templates/deepagent/js/src/agents/prompts/index.js +2 -0
  21. package/templates/deepagent/js/src/agents/prompts/loader.js +53 -0
  22. package/templates/deepagent/js/src/agents/prompts/subagents/analyst.md +17 -0
  23. package/templates/deepagent/js/src/agents/prompts/subagents/coder.md +17 -0
  24. package/templates/deepagent/js/src/agents/prompts/supervisor.js +21 -0
  25. package/templates/deepagent/js/src/agents/prompts/supervisor.md +41 -0
  26. package/templates/deepagent/js/src/agents/state/index.js +1 -0
  27. package/templates/deepagent/js/src/agents/state/types.js +11 -0
  28. package/templates/deepagent/js/src/agents/subagents/analyst.js +12 -0
  29. package/templates/deepagent/js/src/agents/subagents/coder.js +12 -0
  30. package/templates/deepagent/js/src/agents/subagents/index.js +9 -0
  31. package/templates/deepagent/js/src/agents/supervisor.js +64 -0
  32. package/templates/deepagent/js/src/api/app.js +29 -0
  33. package/templates/deepagent/js/src/api/middleware/auth.js +36 -0
  34. package/templates/deepagent/js/src/api/middleware/error.js +30 -0
  35. package/templates/deepagent/js/src/api/routes/agent.js +43 -0
  36. package/templates/deepagent/js/src/api/routes/health.js +40 -0
  37. package/templates/deepagent/js/src/api/routes/session.js +42 -0
  38. package/templates/deepagent/js/src/app.js +98 -0
  39. package/templates/deepagent/js/src/backends/composite.js +22 -0
  40. package/templates/deepagent/js/src/backends/filesystem.js +9 -0
  41. package/templates/deepagent/js/src/backends/index.js +60 -0
  42. package/templates/deepagent/js/src/backends/sandbox.js +26 -0
  43. package/templates/deepagent/js/src/config/agent.js +14 -0
  44. package/templates/deepagent/js/src/config/database.js +19 -0
  45. package/templates/deepagent/js/src/config/env.js +96 -0
  46. package/templates/deepagent/js/src/config/index.js +45 -0
  47. package/templates/deepagent/js/src/graph/checkpointer.js +28 -0
  48. package/templates/deepagent/js/src/graph/compile.js +9 -0
  49. package/templates/deepagent/js/src/graph/index.js +3 -0
  50. package/templates/deepagent/js/src/graph/store.js +28 -0
  51. package/templates/deepagent/js/src/index.js +39 -0
  52. package/templates/deepagent/js/src/memory/index.js +8 -0
  53. package/templates/deepagent/js/src/memory/manager.js +50 -0
  54. package/templates/deepagent/js/src/memory/store.js +43 -0
  55. package/templates/deepagent/js/src/middleware/approval.js +47 -0
  56. package/templates/deepagent/js/src/middleware/context.js +35 -0
  57. package/templates/deepagent/js/src/middleware/index.js +9 -0
  58. package/templates/deepagent/js/src/middleware/logging.js +70 -0
  59. package/templates/deepagent/js/src/middleware/security.js +58 -0
  60. package/templates/deepagent/js/src/model/config.js +38 -0
  61. package/templates/deepagent/js/src/model/index.js +9 -0
  62. package/templates/deepagent/js/src/model/openai-compatible.js +18 -0
  63. package/templates/deepagent/js/src/model/presets.js +71 -0
  64. package/templates/deepagent/js/src/sandbox/config.js +12 -0
  65. package/templates/deepagent/js/src/sandbox/index.js +3 -0
  66. package/templates/deepagent/js/src/sandbox/manager.js +161 -0
  67. package/templates/deepagent/js/src/sandbox/opensandbox.js +195 -0
  68. package/templates/deepagent/js/src/schemas/agent.js +40 -0
  69. package/templates/deepagent/js/src/schemas/common.js +24 -0
  70. package/templates/deepagent/js/src/schemas/locale.js +4 -0
  71. package/templates/deepagent/js/src/schemas/session.js +27 -0
  72. package/templates/deepagent/js/src/services/agent.js +136 -0
  73. package/templates/deepagent/js/src/services/memory.js +33 -0
  74. package/templates/deepagent/js/src/services/session.js +118 -0
  75. package/templates/deepagent/js/src/skills/index.js +21 -0
  76. package/templates/deepagent/js/src/skills/loader.js +75 -0
  77. package/templates/deepagent/js/src/storage/database/client.js +57 -0
  78. package/templates/deepagent/js/src/storage/database/migrations/001_init.sql +20 -0
  79. package/templates/deepagent/js/src/storage/logger/index.js +21 -0
  80. package/templates/deepagent/js/src/storage/redis/client.js +51 -0
  81. package/templates/deepagent/js/src/storage/shutdown/index.js +58 -0
  82. package/templates/deepagent/js/src/tools/database/index.js +1 -0
  83. package/templates/deepagent/js/src/tools/database/query.js +74 -0
  84. package/templates/deepagent/js/src/tools/filesystem/index.js +102 -0
  85. package/templates/deepagent/js/src/tools/index.js +25 -0
  86. package/templates/deepagent/js/src/tools/mcp/client.js +42 -0
  87. package/templates/deepagent/js/src/tools/mcp/connections.js +64 -0
  88. package/templates/deepagent/js/src/tools/mcp/index.js +10 -0
  89. package/templates/deepagent/js/src/tools/mcp/registry.js +36 -0
  90. package/templates/deepagent/js/src/utils/errors.js +73 -0
  91. package/templates/deepagent/js/src/utils/helpers.js +57 -0
  92. package/templates/deepagent/js/src/utils/validation.js +15 -0
  93. package/templates/deepagent/js/tests/agents/prompts.test.js +30 -0
  94. package/templates/deepagent/js/tests/agents/supervisor.test.js +42 -0
  95. package/templates/deepagent/js/tests/config/database.test.js +40 -0
  96. package/templates/deepagent/js/tests/integration/api.test.js +114 -0
  97. package/templates/deepagent/js/tests/middleware/security.test.js +27 -0
  98. package/templates/deepagent/js/tests/model/config.test.js +61 -0
  99. package/templates/deepagent/js/tests/sandbox/config.test.js +46 -0
  100. package/templates/deepagent/js/tests/sandbox/manager.test.js +236 -0
  101. package/templates/deepagent/js/tests/sandbox/opensandbox.test.js +173 -0
  102. package/templates/deepagent/js/tests/services/session.test.js +41 -0
  103. package/templates/deepagent/js/tests/tools/query.test.js +27 -0
  104. package/templates/deepagent/shared/README.md +249 -0
  105. package/templates/deepagent/shared/_editorconfig +12 -0
  106. package/templates/deepagent/shared/_env.example +86 -0
  107. package/templates/deepagent/shared/_gitignore +22 -0
  108. package/templates/deepagent/shared/deployment/docker-compose.yml +60 -0
  109. package/templates/deepagent/shared/resources/AGENTS.md +32 -0
  110. package/templates/deepagent/shared/resources/knowledge/README.md +5 -0
  111. package/templates/deepagent/shared/skills/analysis/SKILL.md +28 -0
  112. package/templates/deepagent/shared/skills/coding/SKILL.md +28 -0
  113. package/templates/deepagent/shared/workspaces/README.md +5 -0
  114. package/templates/deepagent/ts/deployment/Dockerfile +25 -0
  115. package/templates/deepagent/ts/scripts/check.ts +99 -0
  116. package/templates/deepagent/ts/scripts/copy-assets.ts +37 -0
  117. package/templates/deepagent/ts/scripts/dev.ts +40 -0
  118. package/templates/deepagent/ts/src/agents/factory.ts +11 -0
  119. package/templates/deepagent/ts/src/agents/index.ts +4 -0
  120. package/templates/deepagent/ts/src/agents/prompts/index.ts +2 -0
  121. package/templates/deepagent/ts/src/agents/prompts/loader.ts +53 -0
  122. package/templates/deepagent/ts/src/agents/prompts/subagents/analyst.md +17 -0
  123. package/templates/deepagent/ts/src/agents/prompts/subagents/coder.md +17 -0
  124. package/templates/deepagent/ts/src/agents/prompts/supervisor.md +41 -0
  125. package/templates/deepagent/ts/src/agents/prompts/supervisor.ts +33 -0
  126. package/templates/deepagent/ts/src/agents/state/index.ts +1 -0
  127. package/templates/deepagent/ts/src/agents/state/types.ts +13 -0
  128. package/templates/deepagent/ts/src/agents/subagents/analyst.ts +18 -0
  129. package/templates/deepagent/ts/src/agents/subagents/coder.ts +14 -0
  130. package/templates/deepagent/ts/src/agents/subagents/index.ts +9 -0
  131. package/templates/deepagent/ts/src/agents/supervisor.ts +82 -0
  132. package/templates/deepagent/ts/src/api/app.ts +48 -0
  133. package/templates/deepagent/ts/src/api/middleware/auth.ts +38 -0
  134. package/templates/deepagent/ts/src/api/middleware/error.ts +33 -0
  135. package/templates/deepagent/ts/src/api/routes/agent.ts +48 -0
  136. package/templates/deepagent/ts/src/api/routes/health.ts +47 -0
  137. package/templates/deepagent/ts/src/api/routes/session.ts +47 -0
  138. package/templates/deepagent/ts/src/app.ts +111 -0
  139. package/templates/deepagent/ts/src/backends/composite.ts +34 -0
  140. package/templates/deepagent/ts/src/backends/filesystem.ts +19 -0
  141. package/templates/deepagent/ts/src/backends/index.ts +76 -0
  142. package/templates/deepagent/ts/src/backends/sandbox.ts +33 -0
  143. package/templates/deepagent/ts/src/config/agent.ts +37 -0
  144. package/templates/deepagent/ts/src/config/database.ts +21 -0
  145. package/templates/deepagent/ts/src/config/env.ts +106 -0
  146. package/templates/deepagent/ts/src/config/index.ts +84 -0
  147. package/templates/deepagent/ts/src/graph/checkpointer.ts +29 -0
  148. package/templates/deepagent/ts/src/graph/compile.ts +15 -0
  149. package/templates/deepagent/ts/src/graph/index.ts +3 -0
  150. package/templates/deepagent/ts/src/graph/store.ts +29 -0
  151. package/templates/deepagent/ts/src/index.ts +39 -0
  152. package/templates/deepagent/ts/src/memory/index.ts +11 -0
  153. package/templates/deepagent/ts/src/memory/manager.ts +76 -0
  154. package/templates/deepagent/ts/src/memory/store.ts +59 -0
  155. package/templates/deepagent/ts/src/middleware/approval.ts +49 -0
  156. package/templates/deepagent/ts/src/middleware/context.ts +37 -0
  157. package/templates/deepagent/ts/src/middleware/index.ts +9 -0
  158. package/templates/deepagent/ts/src/middleware/logging.ts +71 -0
  159. package/templates/deepagent/ts/src/middleware/security.ts +61 -0
  160. package/templates/deepagent/ts/src/model/config.ts +56 -0
  161. package/templates/deepagent/ts/src/model/index.ts +14 -0
  162. package/templates/deepagent/ts/src/model/openai-compatible.ts +21 -0
  163. package/templates/deepagent/ts/src/model/presets.ts +82 -0
  164. package/templates/deepagent/ts/src/sandbox/config.ts +30 -0
  165. package/templates/deepagent/ts/src/sandbox/index.ts +7 -0
  166. package/templates/deepagent/ts/src/sandbox/manager.ts +176 -0
  167. package/templates/deepagent/ts/src/sandbox/opensandbox.ts +216 -0
  168. package/templates/deepagent/ts/src/schemas/agent.ts +48 -0
  169. package/templates/deepagent/ts/src/schemas/common.ts +26 -0
  170. package/templates/deepagent/ts/src/schemas/locale.ts +4 -0
  171. package/templates/deepagent/ts/src/schemas/session.ts +31 -0
  172. package/templates/deepagent/ts/src/services/agent.ts +170 -0
  173. package/templates/deepagent/ts/src/services/memory.ts +43 -0
  174. package/templates/deepagent/ts/src/services/session.ts +158 -0
  175. package/templates/deepagent/ts/src/skills/index.ts +26 -0
  176. package/templates/deepagent/ts/src/skills/loader.ts +90 -0
  177. package/templates/deepagent/ts/src/storage/database/client.ts +65 -0
  178. package/templates/deepagent/ts/src/storage/database/migrations/001_init.sql +20 -0
  179. package/templates/deepagent/ts/src/storage/logger/index.ts +25 -0
  180. package/templates/deepagent/ts/src/storage/redis/client.ts +57 -0
  181. package/templates/deepagent/ts/src/storage/shutdown/index.ts +82 -0
  182. package/templates/deepagent/ts/src/tools/database/index.ts +5 -0
  183. package/templates/deepagent/ts/src/tools/database/query.ts +79 -0
  184. package/templates/deepagent/ts/src/tools/filesystem/index.ts +110 -0
  185. package/templates/deepagent/ts/src/tools/index.ts +43 -0
  186. package/templates/deepagent/ts/src/tools/mcp/client.ts +54 -0
  187. package/templates/deepagent/ts/src/tools/mcp/connections.ts +68 -0
  188. package/templates/deepagent/ts/src/tools/mcp/index.ts +10 -0
  189. package/templates/deepagent/ts/src/tools/mcp/registry.ts +45 -0
  190. package/templates/deepagent/ts/src/utils/errors.ts +95 -0
  191. package/templates/deepagent/ts/src/utils/helpers.ts +57 -0
  192. package/templates/deepagent/ts/src/utils/validation.ts +17 -0
  193. package/templates/deepagent/ts/tests/agents/prompts.test.ts +30 -0
  194. package/templates/deepagent/ts/tests/agents/supervisor.test.ts +42 -0
  195. package/templates/deepagent/ts/tests/config/database.test.ts +40 -0
  196. package/templates/deepagent/ts/tests/integration/api.test.ts +122 -0
  197. package/templates/deepagent/ts/tests/middleware/security.test.ts +27 -0
  198. package/templates/deepagent/ts/tests/model/config.test.ts +61 -0
  199. package/templates/deepagent/ts/tests/sandbox/config.test.ts +46 -0
  200. package/templates/deepagent/ts/tests/sandbox/manager.test.ts +241 -0
  201. package/templates/deepagent/ts/tests/sandbox/opensandbox.test.ts +188 -0
  202. package/templates/deepagent/ts/tests/services/session.test.ts +45 -0
  203. package/templates/deepagent/ts/tests/tools/query.test.ts +27 -0
  204. package/templates/deepagent/ts/tsconfig.json +19 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 create-deepagent-server contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,293 @@
1
- # Temporary Holding Version
1
+ # create-deepagent-server
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ 几秒钟内创建一个面向生产的 [Deep Agents](https://docs.langchain.com/oss/javascript/deepagents/overview) 项目。
4
+
5
+ 内置主 Agent、专职子 Agent、挂载式文件系统、长期记忆、Skills、MCP 工具、Express API、测试和 Docker 配置,依赖版本在生成时自动解析到最新发布版。
6
+
7
+ - **默认 JavaScript**,传 `--ts` 切换 TypeScript
8
+ - **仅使用 ESM**,现代 ES6+ 语法,相对导入显式带 `.js`
9
+ - **可选 OpenSandbox 沙箱**:`SANDBOX_ENABLED=true` 时按会话(threadId)惰性创建并复用远程沙箱,命令执行与 `/workspace/` 都在隔离环境中;`execute` 使用持久 bash session,支持 `OPEN_SANDBOX_ID` 共享已有沙箱
10
+ - **模型统一走 OpenAI 兼容协议**:`src/model/` 负责配置,默认 MiniMax M3(国内站),切换 OpenAI / DeepSeek / Kimi / MiniMax / 通义千问 / 智谱 / OpenRouter / vLLM / Ollama 只改环境变量
11
+ - **`deepagents` + LangGraph**:checkpointer/store 默认内存,可切换 PostgreSQL
12
+ - **Zod** 校验、**pino** 日志、优雅关闭、SSE 流式输出
13
+ - CLI 本身零运行时依赖
14
+
15
+ ## 使用
16
+
17
+ ```bash
18
+ # npm
19
+ npm create deepagent-server@latest my-agent
20
+
21
+ # 或直接运行 CLI
22
+ npx create-deepagent-server@latest my-agent
23
+
24
+ # TypeScript + pnpm,跳过依赖安装
25
+ npm create deepagent-server@latest my-agent -- --ts --pm pnpm --no-install
26
+ ```
27
+
28
+ ### 交互式提示
29
+
30
+ 在终端中运行(包括 `npx` / `npm create`)时,CLI 会依次询问所有选项,并把推荐项作为默认值:
31
+
32
+ ```text
33
+ ? 项目目录 (my-deepagent)
34
+ ? 项目语言
35
+ ❯ 1. JavaScript — 推荐
36
+ 2. TypeScript — 类型检查
37
+ ? 包管理器
38
+ ❯ 1. npm — 已检测
39
+ 2. pnpm
40
+ 3. yarn
41
+ 4. bun
42
+ ? 是否立即安装依赖?(Y/n)
43
+ ? 是否初始化 Git 仓库?(Y/n)
44
+ ```
45
+
46
+ 直接回车使用默认值。传入对应参数会跳过该项提问(`--ts` 跳过语言、`--no-install` 跳过安装确认等)。传 `-y` 跳过全部提问,使用默认值:JavaScript、自动检测的包管理器、安装依赖、初始化 Git。
47
+
48
+ 只有未传项目名时才会出现“项目目录”提问。
49
+
50
+ ### 选项
51
+
52
+ | 参数 | 说明 |
53
+ | --- | --- |
54
+ | `-t, --template <name>` | 项目模板(目前只有 `deepagent`) |
55
+ | `--js` | JavaScript 项目(默认) |
56
+ | `--ts, --typescript` | TypeScript 项目 |
57
+ | `--pm <name>` | `npm`、`pnpm`、`yarn`、`bun` |
58
+ | `--no-install` | 跳过依赖安装 |
59
+ | `--no-git` | 跳过 `git init` |
60
+ | `--no-latest` | 使用 CLI 内置版本,不解析 npm 最新版 |
61
+ | `-y, --yes` | 使用默认值并跳过所有提问 |
62
+ | `-f, --force` | 允许写入非空目录 |
63
+ | `-h, --help` | 显示帮助 |
64
+ | `-v, --version` | 显示 CLI 版本 |
65
+
66
+ 生成项目时会从 npm registry 并行解析所有模板依赖的最新版本(5 秒超时);无法访问 registry 时回退到 `src/versions.js` 中的内置版本。
67
+
68
+ ## 生成的项目
69
+
70
+ ```text
71
+ my-agent/
72
+ ├── src/
73
+ │ ├── index.(js|ts) # 服务入口
74
+ │ ├── app.(js|ts) # 配置 → 基础设施 → Agent → HTTP
75
+ │ ├── config/ # 环境变量与 Agent 配置
76
+ │ ├── model/ # 模型配置:OpenAI 兼容接入 + 服务商预设
77
+ │ ├── agents/
78
+ │ │ ├── factory.ts # createDeepAgent 封装
79
+ │ │ ├── supervisor.ts # 主 Agent
80
+ │ │ ├── subagents/ # coder、analyst
81
+ │ │ ├── prompts/ # supervisor.md + subagents/*.md
82
+ │ │ └── state/ # 自定义 LangGraph 状态
83
+ │ ├── tools/ # SQL、工作区文件、MCP
84
+ │ ├── middleware/ # 日志、安全、审批、上下文
85
+ │ ├── backends/ # 文件系统、沙箱、组合后端
86
+ │ ├── sandbox/ # OpenSandbox 远程沙箱(可选)
87
+ │ ├── memory/ # 长期记忆 store 与管理器
88
+ │ ├── skills/ # SKILL.md 发现与校验
89
+ │ ├── graph/ # 编译、checkpointer、store
90
+ │ ├── services/ # Agent、会话、记忆服务
91
+ │ ├── api/ # Express 应用、路由、中间件
92
+ │ ├── schemas/ # Zod 结构
93
+ │ ├── storage/ # PostgreSQL、Redis、日志、优雅关闭
94
+ │ └── utils/
95
+ ├── resources/
96
+ │ ├── AGENTS.md # Agent 记忆 → /resources/AGENTS.md
97
+ │ └── knowledge/
98
+ ├── skills/ # coding / analysis SKILL.md
99
+ ├── workspaces/ # Agent 可写沙箱 → /workspace/
100
+ ├── tests/ # agents、tools、middleware、integration
101
+ ├── scripts/ # 交互终端 + 预检脚本
102
+ ├── deployment/ # Dockerfile + docker-compose
103
+ ├── .editorconfig
104
+ ├── .env.example
105
+ ├── package.json
106
+ └── tsconfig.json # 仅 TypeScript
107
+ ```
108
+
109
+ ### Agent 是如何装配的
110
+
111
+ `createSupervisorAgent` 构建一个 Deep Agent:
112
+
113
+ - **模型** —— `src/model/` 统一用 OpenAI 兼容协议接入:`resolveModelConfig()` 解析 `MODEL_*` 环境变量,`createChatModel()` 返回指向任意兼容地址的 `ChatOpenAI`。切换服务商只改 `.env`,不用动代码。
114
+ - **后端** —— `CompositeBackend` 把 `/workspace/`、`/resources/`、`/skills/` 挂载到磁盘,把 `/memories/` 挂载到 LangGraph store。`ENABLE_SHELL=true` 时默认后端切换为 `LocalShellBackend` 并暴露 `execute`;`SANDBOX_ENABLED=true` 时后端按 `threadId` 切换为对应会话的 OpenSandbox,`/workspace/` 与 `execute` 都落在该会话的远程沙箱内。
115
+ - **子 Agent** —— `coder`(工作区改代码)、`analyst`(只读 SQL)。每个都是声明式 `SubAgent`,拥有独立提示词与技能挂载。
116
+ - **提示词** —— `supervisor.md`、`subagents/*.md` 等 Markdown 文件,由 `loadPrompt()` 加载,`renderPrompt()` 填充 `{{占位符}}`(例如团队列表)。
117
+ - **中间件** —— 调用日志、危险命令拦截(返回 `ToolMessage` 错误)、按请求注入租户/用户上下文。
118
+ - **审批** —— `APPROVAL_MODE=sensitive`(默认)通过 `interruptOn` 暂停修改类工具;用同一个 `thread_id` 恢复。
119
+ - **记忆** —— 启动时注入 `AGENTS.md`,`/memories/` 配合 `MemoryManager` 持久化长期事实。
120
+ - **API** —— `/health`、`/health/ready`、`POST /api/agents/invoke`、`POST /api/agents/stream`(SSE)、`POST /api/agents/resume`、会话 CRUD、可选 Bearer 鉴权。
121
+
122
+ ### 生成项目的脚本
123
+
124
+ | 脚本 | JavaScript | TypeScript |
125
+ | --- | --- | --- |
126
+ | `npm run dev` | `node --watch src/index.js` | `tsx watch src/index.ts` |
127
+ | `npm start` | `node src/index.js` | `node dist/index.js` |
128
+ | `npm run agent` | 交互式终端会话 | 同左 |
129
+ | `npm run check` | 预检 | 同左 |
130
+ | `npm test` | `node --test` | `node --import tsx --test` |
131
+ | `npm run build` | — | `tsc` + `scripts/copy-assets.ts` |
132
+ | `npm run typecheck` | — | `tsc --noEmit` |
133
+
134
+ ## 沙箱(OpenSandbox)
135
+
136
+ 生成的项目默认直接读写宿主机的 `workspaces/`。需要把命令执行和文件读写放进隔离环境时,打开可选的 OpenSandbox 沙箱:`SANDBOX_ENABLED=true` 后,该会话的文件工具与 `execute` 都落在远程沙箱内,宿主机不再暴露执行能力。
137
+
138
+ 关闭状态下不会连接任何远程服务,也不会创建沙箱。
139
+
140
+ ### 1. 启动 OpenSandbox 服务
141
+
142
+ ```bash
143
+ uvx opensandbox-server init-config ~/.sandbox.toml --example docker
144
+ uvx opensandbox-server # 默认监听 http://127.0.0.1:8080
145
+ ```
146
+
147
+ ### 2. 在生成项目的 `.env` 中启用
148
+
149
+ ```bash
150
+ SANDBOX_ENABLED=true
151
+ OPEN_SANDBOX_DOMAIN=localhost:8080
152
+ OPEN_SANDBOX_PROTOCOL=http
153
+ OPEN_SANDBOX_API_KEY= # 服务开启鉴权时填写
154
+ SANDBOX_IMAGE=python:3.12 # 沙箱镜像,需要自带 bash
155
+ SANDBOX_WORKSPACE_ROOT=/workspace
156
+ SANDBOX_TIMEOUT_SECONDS=1800 # 默认 30 分钟;使用中按 TTL/3 自动续期,0 表示不过期
157
+ ```
158
+
159
+ `@alibaba-group/opensandbox` 已在生成项目的依赖中,无需额外安装。改完配置先跑 `npm run check`,它会打印解析后的沙箱地址、镜像或共享沙箱 ID,用来确认变量没拼错。
160
+
161
+ ### 3. 运行时的行为
162
+
163
+ | 场景 | 行为 |
164
+ | --- | --- |
165
+ | 创建时机 | 每个 `threadId` 第一次运行 Agent(第一次模型调用)时惰性创建,进程启动、`npm run check`、`POST /api/sessions` 都不会创建;同一会话后续的消息、工具调用和子 Agent 复用同一个后端;创建失败会移出缓存,下次调用重试 |
166
+ | 隔离范围 | 不同 `threadId` 各自一个沙箱,互不影响 |
167
+ | 文件与命令 | 该会话的 `ls` / `read` / `write` / `edit` / `grep` / `glob` 与 `execute` 都在沙箱内执行,`execute` 的默认 cwd 为 `SANDBOX_WORKSPACE_ROOT` |
168
+ | 持久 shell | `execute` 在沙箱内维持一个持久 bash session,`cd`、`export`、函数定义跨命令保留;同一会话的命令串行排队,避免并发覆盖 shell 状态 |
169
+ | 输出上限 | 单次命令输出截断到 10 万字符,并标记 `truncated` |
170
+ | 与宿主机 shell | `SANDBOX_ENABLED=true` 时 `ENABLE_SHELL` 不再生效,宿主机的 `execute` 不会被暴露 |
171
+ | 提示词与记忆 | `AGENTS.md`、`SKILL.md` 仍在启动时从本地读取并注入提示词,`/memories/` 继续走 LangGraph store,都不经过沙箱 |
172
+ | 释放 | `DELETE /api/sessions/:threadId` 销毁该会话的沙箱;进程退出(`closeAll`)时销毁所有沙箱 |
173
+ | 共享模式 | 设置 `OPEN_SANDBOX_ID` 后所有会话连接同一个已有沙箱,退出时只关闭连接、不会 kill 它 |
174
+ | 过期与续期 | 默认 TTL 1800 秒:每次使用间隔超过 TTL/3 会调用 `renew` 续期,活跃会话不会到期;空闲超过 TTL 由服务端回收,下次访问自动重建(沙箱内文件丢失);`0` 关闭 TTL |
175
+
176
+ ### 4. 验证一次
177
+
178
+ ```bash
179
+ curl -s -X POST http://localhost:3000/api/agents/invoke \
180
+ -H 'content-type: application/json' \
181
+ -d '{"message":"在 /workspace 下执行 pwd 和 uname -a,把输出贴给我"}'
182
+ ```
183
+
184
+ 返回的命令输出来自沙箱容器;宿主机的 `workspaces/` 不会被写入。
185
+
186
+ ### 5. 注意事项
187
+
188
+ - 沙箱只在该会话真正跑起来时才创建,但仍然「按会话」而不是「按命令」:deepagents 要在第一次模型调用时解析后端来判断是否暴露 `execute`,所以即使这轮只聊天、没有执行命令,也会为该 `threadId` 建一个沙箱。默认 TTL 是 30 分钟且活跃会话会自动续期,闲置的沙箱由服务端回收。
189
+ - 服务端回收沙箱后再访问会重建一个空沙箱,里面的文件随之丢失;需要长期保留的产物要在会话结束前取回(或用 host 卷把 `/workspace` 落到本地)。
190
+ - 把 `SANDBOX_TIMEOUT_SECONDS` 设为 `0` 就关闭服务端 TTL,完全靠 `DELETE /api/sessions/:threadId` 和进程退出清理;进程崩溃时这种沙箱会一直留着,生产环境不建议。
191
+ - `SANDBOX_IMAGE` 要自带 bash 和常用工具链。精简镜像缺少命令时,`execute` 会返回非零退出码而不是报连接错误。
192
+ - `SANDBOX_WORKSPACE_ROOT` 建议保持 `/workspace`,与工具使用的虚拟路径一致;改成别的目录只会改变 `execute` 的默认 cwd。
193
+
194
+ 实现位于生成项目的 `src/sandbox/`:`OpenSandboxBackend` 继承 deepagents 的 `BaseSandbox`,只实现 `execute` 与文件上传/下载,`ls`、`read`、`grep` 等由 `BaseSandbox` 复用同一个 session 完成;`SandboxManager` 负责按 `threadId` 缓存、续期与销毁,续期发现沙箱已被回收时会自动重建。
195
+
196
+ ## 本 CLI 的仓库结构
197
+
198
+ ```text
199
+ bin/create-deepagent-server.js 可执行入口
200
+ src/
201
+ ├── cli.js 主流程
202
+ ├── args.js 零依赖参数解析
203
+ ├── prompts.js readline 交互
204
+ ├── registry.js 最新版本解析 + 回退
205
+ ├── scaffold.js 模板合并 + package.json 生成
206
+ ├── setup.js 安装 / git 辅助
207
+ ├── dependencies.js 按语言划分的依赖列表
208
+ └── versions.js 内置兜底版本
209
+ templates/deepagent/
210
+ ├── shared/ 两种语言共用的文件
211
+ ├── ts/ TypeScript 源码(唯一事实来源)
212
+ └── js/ 由 ts/ 转译生成(已提交)
213
+ test/cli.test.js
214
+ ```
215
+
216
+ ### 模板生成
217
+
218
+ `src/`、`scripts/`、`tests/` 下的 TypeScript 是唯一源码。JavaScript 模板通过 TypeScript 编译器做类型擦除生成(不打包):
219
+
220
+ ```bash
221
+ npm install
222
+ npm run build:templates
223
+ ```
224
+
225
+ `templates/deepagent/js` 已提交到仓库,发布后的包不需要 TypeScript 运行时。共享文件(`README.md`、`.env.example`、resources、skills、docker-compose 等)在生成项目时合并,因此仓库中只保留一份;每种语言各自保留自己的 `deployment/Dockerfile`,因为 TypeScript 镜像需要构建阶段。
226
+
227
+ 修改 TypeScript 模板后,请执行 `npm run build:templates` 并提交更新后的 `js/` 产物。
228
+
229
+ ## 开发
230
+
231
+ ```bash
232
+ npm install
233
+ npm run build:templates
234
+ npm run lint # ES6+ 语法守卫
235
+ npm test
236
+ node bin/create-deepagent-server.js /tmp/demo-js --js --no-install --no-git --no-latest
237
+ node bin/create-deepagent-server.js /tmp/demo-ts --ts --no-install --no-git --no-latest
238
+ ```
239
+
240
+ CLI 没有运行时依赖;开发依赖只有 TypeScript(生成模板、解析语法)和 Prettier(统一代码风格)。
241
+
242
+ ### 代码风格:ES6+ 优先
243
+
244
+ 仓库内所有 `.js` / `.ts` 文件(`bin/`、`src/`、`scripts/`、`test/` 与 `templates/deepagent/`)遵循同一套 ES6+ 优先约定:
245
+
246
+ | 约定 | 用 | 不用 |
247
+ | --- | --- | --- |
248
+ | 变量声明 | `const` / `let` | `var` |
249
+ | 模块 | `import` / `export`(ESM) | `require` / `module.exports` |
250
+ | 函数 | 箭头函数(具名导出用 `const name = (...) => {}`)、方法简写 | `function` 声明 / 表达式、`key: function () {}` |
251
+ | 字符串 | 模板字符串 | `+` 拼接 |
252
+ | 参数 | 剩余参数 `...args`、默认值 | `arguments` |
253
+ | 对象 | 展开 `{ ...source }`、属性简写 | `Object.assign({}, ...)`、`key: key` |
254
+ | 继承 | `class` | 原型链 |
255
+ | 私有成员 | `private` 修饰符、普通字段 | `#field` |
256
+ | 数组 | 字面量、`includes()` | `new Array()`、`indexOf() === -1` |
257
+
258
+ 统一使用箭头函数:具名导出也写成 `const name = (...) => {}`,不再使用 `function` 声明;箭头函数没有提升,调用必须出现在定义之后。
259
+
260
+ 相对导入优先走目录的 `index.js`(例如 `import { createCheckpointer } from "./graph/index.js"`);只有同一目录内部的模块之间才直接引用具体文件,避免通过 barrel 形成循环依赖。
261
+
262
+ 错误处理优先用 Promise 的 `.then(onFulfilled, onRejected)`、`.catch()`、`.finally()` 表达分支;只有必须同步捕获(`JSON.parse`、`readFileSync`)或事务/资源清理时才使用 `try/catch`。不要用 `try/catch` 单纯转发错误 —— Express 5 会自动把 async handler 的拒绝交给错误中间件。
263
+
264
+ 用空行分隔逻辑段落:初始化、校验、主流程、返回值之间留一行;紧耦合的几行(如声明与紧随其后的使用)保持紧凑。
265
+
266
+ 三目运算尽量写在同一行:条件或分支过长时,优先提取局部变量、常量或提前返回,而不是让 Prettier 把 `? :` 拆成多行。
267
+
268
+ `npm run lint`(`scripts/check-es6.js`)用 TypeScript 编译器 API 解析语法树做校验,不会误伤注释和字符串,也不需要额外依赖;`npm test` 前会自动执行,违反约定会直接失败。
269
+
270
+ ## 环境要求
271
+
272
+ - Node.js **22.6+**(生成项目的测试脚本使用 `node --test` glob 参数,并使用 ESM `NodeNext` 解析)
273
+ - 模型 API Key:`MODEL_API_KEY`(任何兼容 OpenAI 协议的服务,服务地址由 `MODEL_PROVIDER` 或 `MODEL_BASE_URL` 决定)
274
+
275
+ `deepagents` 把 LangChain 运行时声明为 **peer dependencies**。npm 7+ 和 pnpm 8+ 会自动安装;**Yarn 用户需要显式添加**:
276
+
277
+ ```bash
278
+ yarn add @langchain/core @langchain/langgraph @langchain/langgraph-checkpoint @langchain/langgraph-sdk langchain langsmith
279
+ ```
280
+
281
+ ## 发布
282
+
283
+ ```bash
284
+ npm run build:templates # 重新生成 templates/deepagent/js
285
+ npm test
286
+ npm publish
287
+ ```
288
+
289
+ `files` 白名单包含 `bin`、`src`、`templates`;`.npmignore` 会额外排除本地测试/构建文件、编辑器目录和 lockfile,同时保留模板内部的 `scripts/`、`tests/`、`deployment/` 目录。
290
+
291
+ ## 许可证
292
+
293
+ MIT
@@ -0,0 +1,27 @@
1
+ #!/usr/bin/env node
2
+
3
+ import { main } from "../src/cli.js";
4
+
5
+ process.on("SIGINT", () => {
6
+ process.stdout.write("\n");
7
+ process.exit(130);
8
+ });
9
+
10
+ try {
11
+ const code = await main();
12
+ process.exitCode = code ?? 0;
13
+ } catch (error) {
14
+ if (error?.name === "AbortError" || error?.code === "ABORT_ERR") {
15
+ process.stderr.write("\n已取消。\n");
16
+ process.exitCode = 130;
17
+ } else {
18
+ const message = error instanceof Error ? error.message : String(error);
19
+ process.stderr.write(`\n✖ ${message}\n`);
20
+
21
+ if (process.env.DEBUG) {
22
+ console.error(error);
23
+ }
24
+
25
+ process.exitCode = 1;
26
+ }
27
+ }
package/package.json CHANGED
@@ -1,6 +1,52 @@
1
1
  {
2
2
  "name": "create-deepagent-server",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.0",
4
+ "description": "快速创建生产可用的 Deep Agents(deepagents + LangGraph)项目,支持 JavaScript/TypeScript,仅使用 ESM。",
5
+ "type": "module",
6
+ "bin": {
7
+ "create-deepagent-server": "bin/create-deepagent-server.js",
8
+ "create-deepagent": "bin/create-deepagent-server.js"
9
+ },
10
+ "files": [
11
+ "bin",
12
+ "src",
13
+ "templates"
14
+ ],
15
+ "engines": {
16
+ "node": ">=22.6.0"
17
+ },
18
+ "scripts": {
19
+ "build:templates": "node scripts/build-templates.js",
20
+ "lint": "node scripts/check-es6.js",
21
+ "pretest": "node scripts/check-es6.js",
22
+ "test": "node --test \"test/**/*.test.js\"",
23
+ "prepublishOnly": "npm run build:templates && npm test",
24
+ "format": "prettier --write \"src/**/*.js\" \"scripts/**/*.js\" \"test/**/*.js\" \"templates/deepagent/ts/**/*.ts\" \"templates/deepagent/js/**/*.js\" \"templates/deepagent/ts/tsconfig.json\" package.json .prettierrc.json",
25
+ "format:check": "prettier --check \"src/**/*.js\" \"scripts/**/*.js\" \"test/**/*.js\" \"templates/deepagent/ts/**/*.ts\" \"templates/deepagent/js/**/*.js\" \"templates/deepagent/ts/tsconfig.json\" package.json .prettierrc.json"
26
+ },
27
+ "keywords": [
28
+ "deepagents",
29
+ "deep-agents",
30
+ "langgraph",
31
+ "langchain",
32
+ "ai",
33
+ "agent",
34
+ "agents",
35
+ "cli",
36
+ "scaffold",
37
+ "create",
38
+ "starter",
39
+ "template",
40
+ "typescript",
41
+ "javascript",
42
+ "esm"
43
+ ],
44
+ "license": "MIT",
45
+ "publishConfig": {
46
+ "access": "public"
47
+ },
48
+ "devDependencies": {
49
+ "prettier": "^3.6.2",
50
+ "typescript": "^5.9.3"
51
+ }
52
+ }
package/src/args.js ADDED
@@ -0,0 +1,195 @@
1
+ export class UsageError extends Error {
2
+ constructor(message) {
3
+ super(message);
4
+ this.name = "UsageError";
5
+ }
6
+ }
7
+
8
+ export const TEMPLATES = ["deepagent"];
9
+ export const PACKAGE_MANAGERS = ["npm", "pnpm", "yarn", "bun"];
10
+
11
+ export const HELP_TEXT = `create-deepagent-server —— 快速创建 Deep Agents 项目
12
+
13
+ 用法:
14
+ create-deepagent-server [项目名] [选项]
15
+ npm create deepagent-server@latest -- [项目名] [选项]
16
+
17
+ 选项:
18
+ -t, --template <name> 项目模板(默认:deepagent)
19
+ --js JavaScript 项目(默认)
20
+ --ts, --typescript TypeScript 项目
21
+ --pm <name> 包管理器:npm、pnpm、yarn、bun
22
+ --no-install 跳过依赖安装
23
+ --no-git 跳过 git 初始化
24
+ --no-latest 使用 CLI 内置版本,不解析 npm 最新版本
25
+ -y, --yes 使用默认值并跳过所有交互
26
+ -f, --force 允许写入非空目录
27
+ -h, --help 显示帮助
28
+ -v, --version 显示版本
29
+
30
+ 示例:
31
+ npm create deepagent-server@latest my-agent
32
+ npm create deepagent-server@latest my-agent -- --ts --pm pnpm
33
+ npx create-deepagent-server@latest my-agent --no-install
34
+
35
+ 生成的项目结构:
36
+ my-agent/
37
+ ├── src/
38
+ │ ├── index.(js|ts) # 服务入口
39
+ │ ├── app.(js|ts) # 应用装配
40
+ │ ├── config/ # 环境变量与 Agent 配置
41
+ │ ├── model/ # 模型配置与 OpenAI 兼容接入
42
+ │ ├── agents/ # 主 Agent、子 Agent、提示词与状态
43
+ │ ├── tools/ # 数据库、文件系统、MCP
44
+ │ ├── middleware/ # 日志、安全、审批、上下文
45
+ │ ├── backends/ # 文件系统 / 沙箱 / 组合后端
46
+ │ ├── sandbox/ # OpenSandbox 远程沙箱执行
47
+ │ ├── memory/ # 长期记忆存储与管理
48
+ │ ├── skills/ # SKILL.md 发现与校验
49
+ │ ├── graph/ # LangGraph 编译、checkpointer、store
50
+ │ ├── services/ # Agent、会话与记忆服务
51
+ │ ├── api/ # Express 路由与中间件
52
+ │ ├── schemas/ # Zod 请求/响应结构
53
+ │ ├── storage/ # PostgreSQL、Redis、日志与优雅关闭
54
+ │ └── utils/
55
+ ├── resources/ # AGENTS.md 与知识库
56
+ ├── skills/ # coding、analysis 技能
57
+ ├── workspaces/ # Agent 工作目录
58
+ ├── tests/ # 单元测试与集成测试
59
+ ├── scripts/ # 交互终端与预检脚本
60
+ └── deployment/ # Dockerfile 与 docker-compose`;
61
+
62
+ const isValueFlag = (flag) => ["-t", "--template", "--pm"].includes(flag);
63
+
64
+ const readValue = (argv, index, flag, inlineValue) => {
65
+ if (inlineValue !== undefined) {
66
+ if (inlineValue === "") throw new UsageError(`${flag} 缺少参数值。`);
67
+ return { value: inlineValue, index };
68
+ }
69
+ const next = argv[index + 1];
70
+ if (next === undefined || (next.startsWith("-") && next !== "-")) {
71
+ throw new UsageError(`${flag} 缺少参数值。`);
72
+ }
73
+ return { value: next, index: index + 1 };
74
+ };
75
+
76
+ /**
77
+ * 不依赖第三方库解析命令行参数。
78
+ * 显式支持否定形式的参数(--no-install、--no-git、--no-latest)。
79
+ */
80
+ export const parseArgs = (argv) => {
81
+ const options = {
82
+ template: "deepagent",
83
+ language: undefined,
84
+ pm: undefined,
85
+ install: undefined,
86
+ git: undefined,
87
+ latest: true,
88
+ yes: false,
89
+ force: false,
90
+ help: false,
91
+ version: false,
92
+ };
93
+ const provided = new Set();
94
+ const positionals = [];
95
+
96
+ for (let i = 0; i < argv.length; i += 1) {
97
+ const raw = argv[i];
98
+
99
+ if (raw === "--") {
100
+ positionals.push(...argv.slice(i + 1));
101
+ break;
102
+ }
103
+
104
+ if (!raw.startsWith("-") || raw === "-") {
105
+ positionals.push(raw);
106
+ continue;
107
+ }
108
+
109
+ const equalsIndex = raw.indexOf("=");
110
+ const flag = equalsIndex === -1 ? raw : raw.slice(0, equalsIndex);
111
+ const inlineValue = equalsIndex === -1 ? undefined : raw.slice(equalsIndex + 1);
112
+
113
+ if (isValueFlag(flag)) {
114
+ const parsed = readValue(argv, i, flag, inlineValue);
115
+ i = parsed.index;
116
+
117
+ if (flag === "-t" || flag === "--template") {
118
+ if (!TEMPLATES.includes(parsed.value)) {
119
+ throw new UsageError(`未知模板 "${parsed.value}"。可用模板:${TEMPLATES.join("、")}。`);
120
+ }
121
+ options.template = parsed.value;
122
+ provided.add("template");
123
+ } else {
124
+ if (!PACKAGE_MANAGERS.includes(parsed.value)) {
125
+ throw new UsageError(
126
+ `未知包管理器 "${parsed.value}"。可选值:${PACKAGE_MANAGERS.join("、")}。`,
127
+ );
128
+ }
129
+ options.pm = parsed.value;
130
+ provided.add("pm");
131
+ }
132
+ continue;
133
+ }
134
+
135
+ switch (flag) {
136
+ case "-h":
137
+ case "--help":
138
+ options.help = true;
139
+ break;
140
+ case "-v":
141
+ case "--version":
142
+ options.version = true;
143
+ break;
144
+ case "-y":
145
+ case "--yes":
146
+ options.yes = true;
147
+ break;
148
+ case "-f":
149
+ case "--force":
150
+ options.force = true;
151
+ break;
152
+ case "--js":
153
+ options.language = "js";
154
+ provided.add("language");
155
+ break;
156
+ case "--ts":
157
+ case "--typescript":
158
+ options.language = "ts";
159
+ provided.add("language");
160
+ break;
161
+ case "--install":
162
+ options.install = true;
163
+ provided.add("install");
164
+ break;
165
+ case "--no-install":
166
+ options.install = false;
167
+ provided.add("install");
168
+ break;
169
+ case "--git":
170
+ options.git = true;
171
+ provided.add("git");
172
+ break;
173
+ case "--no-git":
174
+ options.git = false;
175
+ provided.add("git");
176
+ break;
177
+ case "--latest":
178
+ options.latest = true;
179
+ break;
180
+ case "--no-latest":
181
+ options.latest = false;
182
+ break;
183
+ default:
184
+ throw new UsageError(
185
+ `未知选项:${flag}\n\n运行 "create-deepagent-server --help" 查看用法。`,
186
+ );
187
+ }
188
+ }
189
+
190
+ if (positionals.length > 1) {
191
+ throw new UsageError(`多余的参数:${positionals[1]}`);
192
+ }
193
+
194
+ return { options, positionals, provided };
195
+ };