crewbee 0.1.9 → 0.1.11

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 (158) hide show
  1. package/README.md +448 -233
  2. package/README.zh-CN.md +334 -127
  3. package/dist/opencode-plugin.mjs +406 -210
  4. package/dist/src/adapters/opencode/bootstrap.js.map +1 -1
  5. package/dist/src/adapters/opencode/chat-message-hook.d.ts.map +1 -1
  6. package/dist/src/adapters/opencode/chat-message-hook.js +2 -1
  7. package/dist/src/adapters/opencode/chat-message-hook.js.map +1 -1
  8. package/dist/src/adapters/opencode/config-hook.d.ts.map +1 -1
  9. package/dist/src/adapters/opencode/config-hook.js +12 -5
  10. package/dist/src/adapters/opencode/config-hook.js.map +1 -1
  11. package/dist/src/adapters/opencode/defaults.d.ts +3 -0
  12. package/dist/src/adapters/opencode/defaults.d.ts.map +1 -0
  13. package/dist/src/adapters/opencode/defaults.js +5 -0
  14. package/dist/src/adapters/opencode/defaults.js.map +1 -0
  15. package/dist/src/adapters/opencode/index.d.ts +1 -0
  16. package/dist/src/adapters/opencode/index.d.ts.map +1 -1
  17. package/dist/src/adapters/opencode/index.js +3 -1
  18. package/dist/src/adapters/opencode/index.js.map +1 -1
  19. package/dist/src/adapters/opencode/plugin.d.ts.map +1 -1
  20. package/dist/src/adapters/opencode/plugin.js +1 -1
  21. package/dist/src/adapters/opencode/plugin.js.map +1 -1
  22. package/dist/src/adapters/opencode/prompt-builder.d.ts.map +1 -1
  23. package/dist/src/adapters/opencode/prompt-builder.js +7 -17
  24. package/dist/src/adapters/opencode/prompt-builder.js.map +1 -1
  25. package/dist/src/adapters/opencode/system-transform-hook.d.ts +2 -1
  26. package/dist/src/adapters/opencode/system-transform-hook.d.ts.map +1 -1
  27. package/dist/src/adapters/opencode/system-transform-hook.js +17 -3
  28. package/dist/src/adapters/opencode/system-transform-hook.js.map +1 -1
  29. package/dist/src/agent-teams/canonical-agent-id.d.ts.map +1 -1
  30. package/dist/src/agent-teams/canonical-agent-id.js +3 -0
  31. package/dist/src/agent-teams/canonical-agent-id.js.map +1 -1
  32. package/dist/src/agent-teams/diagnostics.d.ts +10 -0
  33. package/dist/src/agent-teams/diagnostics.d.ts.map +1 -0
  34. package/dist/src/agent-teams/diagnostics.js +29 -0
  35. package/dist/src/agent-teams/diagnostics.js.map +1 -0
  36. package/dist/src/agent-teams/embedded/coding-team/agent-helpers.d.ts +1 -3
  37. package/dist/src/agent-teams/embedded/coding-team/agent-helpers.d.ts.map +1 -1
  38. package/dist/src/agent-teams/embedded/coding-team/agent-helpers.js +4 -14
  39. package/dist/src/agent-teams/embedded/coding-team/agent-helpers.js.map +1 -1
  40. package/dist/src/agent-teams/embedded/coding-team/agent-profile-builder.d.ts +4 -0
  41. package/dist/src/agent-teams/embedded/coding-team/agent-profile-builder.d.ts.map +1 -0
  42. package/dist/src/agent-teams/embedded/coding-team/agent-profile-builder.js +17 -0
  43. package/dist/src/agent-teams/embedded/coding-team/agent-profile-builder.js.map +1 -0
  44. package/dist/src/agent-teams/embedded/coding-team/agents/codebase-explorer.js +5 -5
  45. package/dist/src/agent-teams/embedded/coding-team/agents/codebase-explorer.js.map +1 -1
  46. package/dist/src/agent-teams/embedded/coding-team/agents/coding-executor.js +4 -4
  47. package/dist/src/agent-teams/embedded/coding-team/agents/coding-executor.js.map +1 -1
  48. package/dist/src/agent-teams/embedded/coding-team/agents/coding-leader.js +8 -8
  49. package/dist/src/agent-teams/embedded/coding-team/agents/coding-leader.js.map +1 -1
  50. package/dist/src/agent-teams/embedded/coding-team/agents/coordination-leader.js +8 -8
  51. package/dist/src/agent-teams/embedded/coding-team/agents/coordination-leader.js.map +1 -1
  52. package/dist/src/agent-teams/embedded/coding-team/agents/multimodal-looker.js +2 -2
  53. package/dist/src/agent-teams/embedded/coding-team/agents/multimodal-looker.js.map +1 -1
  54. package/dist/src/agent-teams/embedded/coding-team/agents/principal-advisor.js +5 -5
  55. package/dist/src/agent-teams/embedded/coding-team/agents/principal-advisor.js.map +1 -1
  56. package/dist/src/agent-teams/embedded/coding-team/agents/reviewer.js +6 -6
  57. package/dist/src/agent-teams/embedded/coding-team/agents/reviewer.js.map +1 -1
  58. package/dist/src/agent-teams/embedded/coding-team/agents/web-researcher.js +5 -5
  59. package/dist/src/agent-teams/embedded/coding-team/agents/web-researcher.js.map +1 -1
  60. package/dist/src/agent-teams/filesystem.d.ts +4 -0
  61. package/dist/src/agent-teams/filesystem.d.ts.map +1 -1
  62. package/dist/src/agent-teams/filesystem.js +134 -21
  63. package/dist/src/agent-teams/filesystem.js.map +1 -1
  64. package/dist/src/agent-teams/index.d.ts +1 -0
  65. package/dist/src/agent-teams/index.d.ts.map +1 -1
  66. package/dist/src/agent-teams/index.js +5 -1
  67. package/dist/src/agent-teams/index.js.map +1 -1
  68. package/dist/src/agent-teams/library.d.ts +5 -1
  69. package/dist/src/agent-teams/library.d.ts.map +1 -1
  70. package/dist/src/agent-teams/library.js +31 -8
  71. package/dist/src/agent-teams/library.js.map +1 -1
  72. package/dist/src/agent-teams/parsers.js +3 -3
  73. package/dist/src/agent-teams/parsers.js.map +1 -1
  74. package/dist/src/agent-teams/types.d.ts +6 -0
  75. package/dist/src/agent-teams/types.d.ts.map +1 -1
  76. package/dist/src/agent-teams/validation.d.ts.map +1 -1
  77. package/dist/src/agent-teams/validation.js +50 -3
  78. package/dist/src/agent-teams/validation.js.map +1 -1
  79. package/dist/src/cli/doctor.d.ts.map +1 -1
  80. package/dist/src/cli/doctor.js +53 -7
  81. package/dist/src/cli/doctor.js.map +1 -1
  82. package/dist/src/cli/install.d.ts.map +1 -1
  83. package/dist/src/cli/install.js +8 -3
  84. package/dist/src/cli/install.js.map +1 -1
  85. package/dist/src/cli/parse-install-options.d.ts.map +1 -1
  86. package/dist/src/cli/parse-install-options.js +31 -0
  87. package/dist/src/cli/parse-install-options.js.map +1 -1
  88. package/dist/src/cli/parse-setup-options.d.ts +3 -0
  89. package/dist/src/cli/parse-setup-options.d.ts.map +1 -0
  90. package/dist/src/cli/parse-setup-options.js +102 -0
  91. package/dist/src/cli/parse-setup-options.js.map +1 -0
  92. package/dist/src/cli/render-help.d.ts.map +1 -1
  93. package/dist/src/cli/render-help.js +12 -4
  94. package/dist/src/cli/render-help.js.map +1 -1
  95. package/dist/src/cli/run-cli.d.ts.map +1 -1
  96. package/dist/src/cli/run-cli.js +27 -1
  97. package/dist/src/cli/run-cli.js.map +1 -1
  98. package/dist/src/cli/setup.d.ts +7 -0
  99. package/dist/src/cli/setup.d.ts.map +1 -0
  100. package/dist/src/cli/setup.js +70 -0
  101. package/dist/src/cli/setup.js.map +1 -0
  102. package/dist/src/cli/uninstall-user.d.ts.map +1 -1
  103. package/dist/src/cli/uninstall-user.js +2 -1
  104. package/dist/src/cli/uninstall-user.js.map +1 -1
  105. package/dist/src/cli/validate.d.ts +6 -0
  106. package/dist/src/cli/validate.d.ts.map +1 -0
  107. package/dist/src/cli/validate.js +90 -0
  108. package/dist/src/cli/validate.js.map +1 -0
  109. package/dist/src/core/index.d.ts +1 -0
  110. package/dist/src/core/index.d.ts.map +1 -1
  111. package/dist/src/install/config-writer.d.ts +2 -18
  112. package/dist/src/install/config-writer.d.ts.map +1 -1
  113. package/dist/src/install/config-writer.js +9 -94
  114. package/dist/src/install/config-writer.js.map +1 -1
  115. package/dist/src/install/doctor.d.ts.map +1 -1
  116. package/dist/src/install/doctor.js +28 -19
  117. package/dist/src/install/doctor.js.map +1 -1
  118. package/dist/src/install/index.d.ts +6 -4
  119. package/dist/src/install/index.d.ts.map +1 -1
  120. package/dist/src/install/index.js +20 -11
  121. package/dist/src/install/index.js.map +1 -1
  122. package/dist/src/install/install.d.ts.map +1 -1
  123. package/dist/src/install/install.js +50 -33
  124. package/dist/src/install/install.js.map +1 -1
  125. package/dist/src/install/opencode-cli.d.ts +14 -0
  126. package/dist/src/install/opencode-cli.d.ts.map +1 -0
  127. package/dist/src/install/opencode-cli.js +58 -0
  128. package/dist/src/install/opencode-cli.js.map +1 -0
  129. package/dist/src/install/opencode-config-file.d.ts +26 -0
  130. package/dist/src/install/opencode-config-file.d.ts.map +1 -0
  131. package/dist/src/install/opencode-config-file.js +131 -0
  132. package/dist/src/install/opencode-config-file.js.map +1 -0
  133. package/dist/src/install/package-installation.d.ts +19 -0
  134. package/dist/src/install/package-installation.d.ts.map +1 -0
  135. package/dist/src/install/package-installation.js +95 -0
  136. package/dist/src/install/package-installation.js.map +1 -0
  137. package/dist/src/install/package-manager.d.ts +1 -14
  138. package/dist/src/install/package-manager.d.ts.map +1 -1
  139. package/dist/src/install/package-manager.js +8 -79
  140. package/dist/src/install/package-manager.js.map +1 -1
  141. package/dist/src/install/plugin-entry.d.ts +3 -1
  142. package/dist/src/install/plugin-entry.d.ts.map +1 -1
  143. package/dist/src/install/plugin-entry.js +11 -22
  144. package/dist/src/install/plugin-entry.js.map +1 -1
  145. package/dist/src/install/setup.d.ts +6 -0
  146. package/dist/src/install/setup.d.ts.map +1 -0
  147. package/dist/src/install/setup.js +72 -0
  148. package/dist/src/install/setup.js.map +1 -0
  149. package/dist/src/install/types.d.ts +41 -0
  150. package/dist/src/install/types.d.ts.map +1 -1
  151. package/dist/src/install/uninstall.d.ts.map +1 -1
  152. package/dist/src/install/uninstall.js +30 -18
  153. package/dist/src/install/uninstall.js.map +1 -1
  154. package/dist/src/render/prompt-document-renderer.d.ts +4 -0
  155. package/dist/src/render/prompt-document-renderer.d.ts.map +1 -0
  156. package/dist/src/render/prompt-document-renderer.js +19 -0
  157. package/dist/src/render/prompt-document-renderer.js.map +1 -0
  158. package/package.json +5 -2
package/README.zh-CN.md CHANGED
@@ -6,20 +6,25 @@
6
6
  <img src="assets/crewbee-intro.png" alt="Turn scattered agents into real teams" width="100%" />
7
7
  </p>
8
8
 
9
- <p align="center"><strong>面向真实宿主运行时的 Team-first Agent 工程框架。</strong></p>
9
+ <p align="center"><strong>面向 OpenCode 的 Agent Team 框架。</strong></p>
10
10
 
11
- CrewBee 是一个 **Team-first(团队优先)** 的 Agent Team 框架。
11
+ CrewBee 支持为不同任务 / 项目设计不同的 **Agent Team**,并根据任务复杂度灵活切换 **单 Agent 执行** 与 **多 Agent 协作**。
12
12
 
13
- 它提供一套面向 Team 的定义、投影与宿主适配方式,用来把零散的 Agent prompt、规则和协作约定沉淀为可维护、可迁移、可运行的 Team 资产。
13
+ 它不是提示词包,也不是强制多 Agent 仪式,而是把 Agent 的角色分工、协作方式、上下文管理、review 方式、验收标准和宿主适配整理成可维护、可运行、可复用的 Team 工程资产。
14
14
 
15
15
  **当前重点:**让 Team 级 Agent 系统能够被稳定定义、跨宿主投影,并真正运行在 OpenCode 中。
16
16
 
17
+ ---
18
+
17
19
  ## 为什么是 CrewBee
18
20
 
19
- - **Team-first,而不是 prompt-first** —— Leader、members、workflow、policy 都是可维护的工程对象。
20
- - **宿主无关核心** —— Team 定义不被某一个运行时绑死。
21
- - **基于 Projection 的运行模型** —— 一套 Team 定义可以稳定映射到具体宿主。
22
- - **今天就能接入 OpenCode** —— 已具备插件、agent 投影、安装、doctor 和 release 链路。
21
+ * **为不同任务 / 项目设计不同 Agent Team** —— 不同工作可以拥有不同角色分工、规则、流程和完成标准。
22
+ * **根据任务复杂度切换单 Agent 与多 Agent 协作模式** —— 简单任务保持敏捷,复杂任务启用团队协作、支援、review 和验证。
23
+ * **主 Agent 持有最完整上下文** —— 由主 Agent 统一持有用户目标、项目约束、支援结论、review 意见和验证结果,保证关键决策依据更全面。
24
+ * **上下文隔离式委派** —— 支援 Agent 在独立上下文中完成探索、研究和审查,只把高信号结论回传给主 Agent,降低主 Agent 的上下文与注意力负担。
25
+ * **内置成熟 Coding Team** —— 内置 Coding Team 包含清晰角色分工、review 方式与验收标准,适合代码开发、修复、调试、重构和验证。
26
+ * **跨会话 Project Context 方向** —— 下一阶段将增强自动维护 project context 的能力,让长期项目持续保有项目定位、框架设计、历史记录、当前状态与计划等摘要信息。
27
+ * **可复制、可修改、可贡献的 Team 模板体系** —— Team 是可以沉淀、版本化和分享的工程资产。
23
28
 
24
29
  当前版本已经打通了 **CrewBee → OpenCode** 的完整 MVP 链路:
25
30
 
@@ -34,12 +39,19 @@ CrewBee 是一个 **Team-first(团队优先)** 的 Agent Team 框架。
34
39
  >
35
40
  > **CrewBee = Agent Team 定义框架 + Runtime Projection 层 + 宿主适配层(当前为 OpenCode)**
36
41
 
42
+ ---
43
+
37
44
  ## 快速入口
38
45
 
39
- - [CrewBeeLab 官网](https://crewbeelab.github.io)
40
- - [安装指南](docs/guide/installation.md)
41
- - [自定义 Agent Team 指南](docs/guide/custom-agent-team.md)
42
- - [发布指南](docs/guide/release.md)
46
+ * [CrewBeeLab 官网](https://crewbeelab.github.io)
47
+ * [安装指南](docs/guide/installation.zh-CN.md)
48
+ * [自定义 Agent Team 指南](docs/guide/custom-agent-team.md)
49
+ * [项目级 Team 配置指南](docs/guide/project-team-config.md)
50
+ * [发布指南](docs/guide/release.zh-CN.md)
51
+
52
+ 英文文档请从 [README.md](README.md) 进入,并优先阅读 `docs/guide` 下的英文指南文件。
53
+
54
+ ---
43
55
 
44
56
  ## OpenCode 中的 Agent ID
45
57
 
@@ -47,11 +59,11 @@ CrewBee 统一使用单一的 **canonical agent id**,贯穿投影、默认选
47
59
 
48
60
  例如:
49
61
 
50
- - `coding-leader`
51
- - `coding-executor`
52
- - `coding-reviewer`
62
+ * `coding-leader`
63
+ * `coding-executor`
64
+ * `coding-reviewer`
53
65
 
54
- 同一个 id 会同时用于 OpenCode `default_agent`、session 中显式选择的 agent、delegation 目标,以及用户可见的运行时/配置 id。
66
+ 同一个 id 会同时用于 OpenCode `default_agent`、session 中显式选择的 agent、delegation 目标,以及用户可见的运行时 / 配置 id。
55
67
 
56
68
  ---
57
69
 
@@ -65,15 +77,18 @@ CrewBee 统一使用单一的 **canonical agent id**,贯穿投影、默认选
65
77
  * [Agent Team 与 Agent Profile 定义方式](#agent-team-与-agent-profile-定义方式)
66
78
  * [OpenCode 运行时是如何工作的](#opencode-运行时是如何工作的)
67
79
  * [内置 Coding Team 的设计思想](#内置-coding-team-的设计思想)
80
+ * [下一步:Project Context](#下一步project-context)
68
81
  * [配置、安装与运维脚本](#配置安装与运维脚本)
69
82
  * [卸载](#卸载)
83
+ * [致谢](#致谢)
70
84
 
71
85
  ---
72
86
 
73
87
  ## CrewBee 是什么
74
88
 
75
- 在 CrewBee 里,真正的一等对象不是单个 Agent,而是 **Team**。
76
- 一个 Team 不是几段 prompt 的拼接,而是一个有结构的定义单元,至少包含:
89
+ CrewBee 是一个面向真实宿主运行时的 Agent Team 框架。
90
+
91
+ 在 CrewBee 里,真正的一等对象不是单个 Agent,而是 **Team**。一个 Team 不是几段 prompt 的拼接,而是一个有结构的定义单元,至少包含:
77
92
 
78
93
  * Team 身份与定位
79
94
  * formal leader
@@ -84,61 +99,235 @@ CrewBee 统一使用单一的 **canonical agent id**,贯穿投影、默认选
84
99
  * Prompt Projection
85
100
  * 宿主运行时映射
86
101
 
87
- CrewBee 当前不会强行替你自动选择 Team,也不会替你自动判断“应该走什么组织结构”。
102
+ CrewBee 的目标是把零散的 Agent prompt、规则和协作约定沉淀为可维护、可迁移、可运行的 Team 资产。
103
+
88
104
  当前阶段的基本使用方式是:
89
105
 
90
106
  * 用户在宿主中选择 Team 的入口 Agent
91
107
  * CrewBee 负责把 Team 定义稳定投影到宿主中运行
92
108
  * 运行时通过 session binding、delegation 与系统提示注入维持 Team 语义
93
109
 
110
+ CrewBee 当前不会强行替你自动选择 Team,也不会替你自动判断所有任务的组织结构。它优先把 Team 定义、Team 投影、运行时绑定和 OpenCode 适配做扎实。
111
+
94
112
  ---
95
113
 
96
114
  ## CrewBee 解决什么问题
97
115
 
98
- CrewBee 主要解决三类问题:
116
+ CrewBee 主要解决七类问题。
117
+
118
+ ### 1. 为不同任务 / 项目设计不同 Agent Team
119
+
120
+ Coding、调研、写作、分析、推广、长期项目维护并不是同一种工作。它们需要不同的角色结构、工作规则、工具边界、review 方式和完成标准。
121
+
122
+ CrewBee 允许你为不同任务 / 项目设计不同 Agent Team,而不是用一套越来越长的通用 prompt 处理所有工作。
123
+
124
+ ### 2. 根据任务复杂度灵活切换单 Agent 与多 Agent 协作模式
125
+
126
+ 简单任务需要快速响应、少 token、少步骤;复杂任务才需要支援 Agent、独立 review、验证和更明确的完成闸门。
127
+
128
+ CrewBee 的设计目标不是默认让所有任务都变成多 Agent 协作,而是支持根据任务复杂度选择合适的执行方式。
129
+
130
+ ### 3. 主 Agent 持有最完整上下文,保证决策依据的全面性
99
131
 
100
- ### 1. 把零散 Agent 实践沉淀为可维护的 Team 资产
132
+ 复杂任务中,代码探索、外部调研、review 和验证都可能产生关键信息。
101
133
 
102
- 很多 Agent 实践仍然散落在 prompt、宿主配置和临时约定里,难以复用、迁移和长期维护。CrewBee 用 Team 定义把这些内容收敛成稳定的工程对象。
134
+ CrewBee 强调由主 Agent / formal leader 持有最完整的任务上下文,统一汇总用户目标、项目约束、支援结论、review 意见和验证结果,再进行关键判断与最终收口。
103
135
 
104
- ### 2. 让不同任务场景使用不同 Team,而不是一套 prompt 通吃
136
+ ### 4. 上下文隔离式委派,降低主 Agent 的上下文与注意力负担
105
137
 
106
- Coding、调研、写作、分析和流程执行的最佳行为方式并不相同。CrewBee 的核心思路是按场景定义不同 Team,而不是默认复用一套通用规则。
138
+ 复杂任务不应该把所有搜索过程、支线探索、失败路径和低信号材料都塞进主 Agent 上下文。
107
139
 
108
- ### 3. 让执行方式可选择、可管理
140
+ CrewBee 通过 delegation 让支援 Agent 在独立上下文中完成代码探索、资料研究、review 或多模态解读,再把高信号结论回传给主 Agent。这可以减少主上下文污染,也降低主 Agent 的注意力负担。
109
141
 
110
- 很多系统关注“能不能执行”,但较少关注“应该如何执行”。CrewBee 更强调根据任务复杂度选择合适的组织方式,并让入口、协作和运行过程更清晰。
142
+ ### 5. 内置成熟 Coding Team,含 review 方式与验收标准
143
+
144
+ 代码任务不只需要生成实现,还需要代码定位、外部资料、独立 review、验证证据和完成标准。
145
+
146
+ CrewBee 内置 Coding Team 用直接职责命名组织角色,并强调 review 与验收标准,帮助复杂代码任务更可靠地收口。
147
+
148
+ ### 6. 跨会话 Project Context 方向
149
+
150
+ 长期项目不应该每次新会话都从零解释项目定位、框架设计、历史记录、当前状态和下一步计划。
151
+
152
+ CrewBee 下一阶段将增强跨会话自动维护 project context 的能力,让 Agent 能基于项目摘要启发式阅读代码,减少完整阅读工程代码带来的上下文消耗。
153
+
154
+ ### 7. 可复制、可修改、可贡献的 Team 模板体系
155
+
156
+ Team 不只是内部配置,也是可以复制、修改、版本化和贡献的工程资产。
157
+
158
+ 这让用户可以从内置 Team 或模板出发,逐步沉淀自己的 Agent 工作方式。
111
159
 
112
160
  ---
113
161
 
114
162
  ## 核心特性
115
163
 
116
- ### 1. Team-first 静态模型
164
+ ### 1. 为不同任务 / 项目设计不同 Agent Team
117
165
 
118
166
  CrewBee 把 Team 当成一等对象,而不是只关心一个个散落的 agent prompt。
119
- 这意味着:
120
167
 
121
- * Team 有 formal leader
122
- * Team 有 policy
123
- * Team 有 members 和 workflow
124
- * Team 有宿主无关骨架
168
+ 一个 Team 可以拥有自己的:
169
+
170
+ * 任务定位
171
+ * 默认入口 Agent
172
+ * 成员分工
173
+ * 工作流程
174
+ * 共享规则
175
+ * 工具边界
176
+ * review 方式
177
+ * 完成标准
178
+ * 输出风格
179
+
180
+ 这意味着你可以为不同任务 / 项目分别设计不同 Team,例如:
181
+
182
+ * `CodingTeam`:代码开发、修复、调试、重构、验证
183
+ * `GeneralTeam`:调研、分析、写作、方案
184
+ * `ResearchOpsTeam`:证据检索、资料整理、结论收束
185
+ * `MarketingOpsTeam`:开源发布、推广、社区反馈
186
+ * `ProjectContextTeam`:项目上下文维护、状态更新、跨会话 handoff
187
+ * `WukongTeam`:高不确定性、强探索、长周期复杂任务
188
+
189
+ ### 2. 根据任务复杂度灵活切换单 Agent 与多 Agent 协作模式
190
+
191
+ CrewBee 不把多 Agent 协作做成默认仪式,而是支持根据任务复杂度选择不同执行方式。
192
+
193
+ **单 Agent 执行模式** 适合:
194
+
195
+ * 简单问答
196
+ * 小范围代码修改
197
+ * 局部解释
198
+ * 快速整理
199
+ * 低风险任务
200
+ * 已经有明确上下文和明确目标的任务
201
+
202
+ **多 Agent 协作模式** 适合:
125
203
 
126
- ### 2. 宿主无关的 Runtime Projection
204
+ * 跨文件实现
205
+ * 复杂 bug 修复
206
+ * 外部资料调研
207
+ * 架构判断
208
+ * 独立 review
209
+ * 需要验证证据的任务
210
+ * 长周期项目工作
211
+
212
+ 简单任务保持敏捷,复杂任务启用团队协作。
213
+
214
+ ### 3. 主 Agent 持有最完整上下文,保证决策依据的全面性
215
+
216
+ CrewBee 的 Team 以主 Agent / formal leader 作为任务入口、主线 owner 和最终收口者。
217
+
218
+ 主 Agent 负责持有最完整的任务上下文,包括:
219
+
220
+ * 用户目标
221
+ * 项目约束
222
+ * 当前任务状态
223
+ * 支援 Agent 回传的结论
224
+ * review 意见
225
+ * 验证结果
226
+ * 风险与未决事项
227
+
228
+ 关键决策由主 Agent 基于这些信息完成,而不是由只掌握局部信息的支援 Agent 独立做全局判断。
229
+
230
+ ### 4. 上下文隔离式委派,降低主 Agent 的上下文与注意力负担
231
+
232
+ CrewBee 的支援型协作强调上下文隔离式委派:
233
+
234
+ ```text
235
+ 主 Agent 持有主线任务上下文。
236
+ 支援 Agent 在独立上下文中完成专项任务。
237
+ 支援 Agent 只把高信号结论回传给主 Agent。
238
+ 主 Agent 基于回流结论继续决策和收口。
239
+ ```
240
+
241
+ 支援任务包括:
242
+
243
+ * 代码库探索
244
+ * 外部资料检索
245
+ * 证据整理
246
+ * 多模态资料解读
247
+ * 独立 review
248
+ * 高阶架构建议
249
+
250
+ 这样可以避免支线搜索、失败路径、低信号材料和审查过程污染主上下文。
251
+
252
+ ### 5. 内置成熟 Coding Team,含 review 方式与验收标准
253
+
254
+ CrewBee 当前最重要的方法论样板是内置 Coding Team。
255
+
256
+ 它不是单个 Coder Agent,而是一支面向软件工程任务设计的 Agent Team,推荐结构包括:
257
+
258
+ ```text
259
+ coding-leader
260
+ coding-executor
261
+ codebase-explorer
262
+ web-researcher
263
+ reviewer
264
+ principal-advisor
265
+ multimodal-looker
266
+ task-orchestrator
267
+ ```
268
+
269
+ 内置 Coding Team 采用直接职责命名,让用户快速理解每个 Agent 负责什么。
270
+
271
+ | 内置 Coding Team 角色 | 职责 |
272
+ | ------------------- | --------------------- |
273
+ | `coding-leader` | 默认入口、任务 owner、最终收口者 |
274
+ | `coding-executor` | 执行明确实现、修复、调试与局部重构 |
275
+ | `codebase-explorer` | 定位代码入口、调用链、相似实现和历史线索 |
276
+ | `web-researcher` | 查官方资料、外部文档、开源实现和版本差异 |
277
+ | `reviewer` | 独立审查风险、遗漏、验证证据和完成标准 |
278
+ | `principal-advisor` | 提供架构、性能、复杂度等高阶判断和主建议 |
279
+ | `multimodal-looker` | 解读截图、图表、PDF、界面图和视觉资料 |
280
+ | `task-orchestrator` | 处理大型计划、多波次任务和统一 QA 编排 |
281
+
282
+ Coding Team 的完成不应只依赖“Agent 认为完成了”,而应尽量包含明确验收标准,例如:
283
+
284
+ ```text
285
+ - 目标问题已定位
286
+ - 修改点有明确依据
287
+ - 已完成必要实现或修复
288
+ - 已运行可用的 diagnostics / build / tests
289
+ - reviewer 未发现真实阻塞
290
+ - 已说明未验证项和残余风险
291
+ ```
292
+
293
+ ### 6. Host-agnostic 定义与 OpenCode Runtime Projection
127
294
 
128
295
  CrewBee 先把 Team-first 结构转换成统一的中间表示,再映射到具体宿主。
129
- 这让 Team / Agent 的定义尽量保持宿主无关,适合长期维护和后续扩展。
130
296
 
131
- ### 3. OpenCode 适配器与插件运行时
297
+ 当前重点宿主是 OpenCode。
298
+
299
+ 当前 OpenCode MVP 链路包括:
300
+
301
+ * Team Library loading
302
+ * Team / Agent validation
303
+ * Runtime Projection
304
+ * formal leader default selection
305
+ * projected agent generation
306
+ * OpenCode config patch
307
+ * session binding
308
+ * delegation tooling
309
+ * plugin entry
310
+ * user-level install
311
+ * doctor verification
312
+
313
+ 这使 CrewBee 不只是一个 prompt 文件夹,而是一个可以真实接入 OpenCode 的运行框架。
314
+
315
+ ### 7. 可复制、可修改、可贡献的 Team 模板体系
316
+
317
+ CrewBee 的 Team 是文件型工程资产,可以被复制、修改、版本化和贡献。
132
318
 
133
- 当前已经打通 Team / Agent 定义到 OpenCode 可运行 Agent 的完整投影链路,包括:
319
+ 用户可以:
134
320
 
135
- * projected agent → OpenCode agent config
136
- * Team / Agent prompt 构造
137
- * config patch 输出
138
- * 宿主事件接入
139
- * delegation 工具挂接
321
+ * 使用内置 Team
322
+ * 复制 Team 模板
323
+ * 修改角色结构
324
+ * 调整共享规则
325
+ * 固化自己的工作方式
326
+ * 为社区贡献 Team
140
327
 
141
- ### 4. Prompt 既低耦合,又保留执行语义
328
+ 很多用户不一定会修改 CrewBee core,但可以基于模板改出自己的 Team。
329
+
330
+ ### 8. Prompt 既低耦合,又保留执行语义
142
331
 
143
332
  CrewBee 没有回退到“每个字段一个 schema / 一个 renderer”的旧路,也没有退化成“top-level block 全透明 dump”。
144
333
 
@@ -177,7 +366,7 @@ CrewBee 没有回退到“每个字段一个 schema / 一个 renderer”的旧
177
366
  * 完成标准是什么
178
367
  * 失败时如何恢复
179
368
 
180
- ### 5. Collaboration 会生成可直接委派的 Agent 清单
369
+ ### 9. Collaboration 会生成可直接委派的 Agent 清单
181
370
 
182
371
  当前生成的 `Collaboration` 不再只是简单列 profile 里的协作绑定,而是会结合:
183
372
 
@@ -193,7 +382,7 @@ CrewBee 没有回退到“每个字段一个 schema / 一个 renderer”的旧
193
382
 
194
383
  便于在运行时直接委派。
195
384
 
196
- ### 6. Team Contract 压缩为可执行手册
385
+ ### 10. Team Contract 压缩为可执行手册
197
386
 
198
387
  Team prompt 最终不是直接渲染整块治理配置,而是收敛为:
199
388
 
@@ -202,7 +391,7 @@ Team prompt 最终不是直接渲染整块治理配置,而是收敛为:
202
391
 
203
392
  这让 Team 合同更适合模型消费,也避免了治理字段机械展开。
204
393
 
205
- ### 7. 用户级安装与运维链路
394
+ ### 11. 用户级安装与运维链路
206
395
 
207
396
  CrewBee 已经具备完整的本地构建、用户级安装、doctor 校验和卸载链路,能够作为 OpenCode 的用户级插件稳定接入。
208
397
 
@@ -210,94 +399,44 @@ CrewBee 已经具备完整的本地构建、用户级安装、doctor 校验和
210
399
 
211
400
  ## 安装
212
401
 
213
- ### 给人类的最短路径
214
-
215
- 如果你在用 LLM Agent,直接把下面这段发给它:
216
-
217
- ```text
218
- 请按照当前仓库中的 docs/guide/installation.md 完成 CrewBee 安装。
219
- 只使用 OpenCode 用户级安装流程,不要使用旧的 project-local 安装方式。
220
- ```
221
-
222
- 或者你自己阅读:
223
-
224
- * [安装指南](docs/guide/installation.md)
225
-
226
- ### 给 LLM Agent 的最短路径
227
-
228
- 直接读取并执行:
229
-
230
- ```text
231
- docs/guide/installation.md
232
- docs/guide/release.md
233
- ```
234
-
235
- ### Windows 一键本地安装脚本
236
-
237
- 仓库已经提供:
238
-
239
- ```bat
240
- scripts\install-local-user.bat
241
- ```
242
-
243
- 它会自动执行:
244
-
245
- 1. `npm install`
246
- 2. `npm run install:local:user`
247
- 3. `npm run doctor`
248
-
249
- ---
250
-
251
- ## 快速开始
252
-
253
- ### 开发构建
402
+ 用一条命令为 OpenCode 安装 CrewBee:
254
403
 
255
404
  ```bash
256
- npm install
257
- npm run typecheck
258
- npm run build
405
+ npx crewbee@latest setup --with-opencode
259
406
  ```
260
407
 
261
- ### 本地用户级安装
262
-
263
- 推荐从仓库根目录执行:
408
+ 如果你已经安装 OpenCode:
264
409
 
265
410
  ```bash
266
- npm install
267
- npm run install:local:user
411
+ npx crewbee@latest setup
268
412
  ```
269
413
 
270
- 这会做四件事:
414
+ CrewBee 会安装到 OpenCode 用户级 workspace,写入标准 plugin entry `"crewbee"`,运行 doctor 检查,并且不会修改业务仓库文件。
271
415
 
272
- 1. 构建 CrewBee
273
- 2. 打包稳定本地 tarball 到 `.artifacts/local/crewbee-local.tgz`
274
- 3. 安装到 OpenCode 用户级 package workspace(`~/.cache/opencode`)
275
- 4. 重写 OpenCode config 为 canonical 插件入口 `crewbee`
416
+ 完整说明见:[安装指南](docs/guide/installation.zh-CN.md)
276
417
 
277
- ### 已发布后的 registry 安装
418
+ ---
278
419
 
279
- 当 `crewbee` 发布到 npm 后,可以直接执行:
420
+ ## 快速开始
280
421
 
281
422
  ```bash
282
- npm run install:registry:user
423
+ cd /path/to/project
424
+ opencode
283
425
  ```
284
426
 
285
- OpenCode 配置也可以直接写插件包名:
427
+ 选择 `coding-leader`,然后运行第一个真实任务:
286
428
 
287
- ```json
288
- {
289
- "plugin": ["crewbee"]
290
- }
429
+ ```text
430
+ 使用 CrewBee Coding Team 修复这个问题,并在完成前进行 review 与验证。
291
431
  ```
292
432
 
293
- ### 验证安装
433
+ 随时验证:
294
434
 
295
435
  ```bash
296
- npm run doctor
297
- npm run version
436
+ npx crewbee@latest doctor
298
437
  ```
299
438
 
300
- `npm run version`(或 `crewbee version`)会直接从 `package.json` 读取当前包版本和已安装包版本。
439
+ 本地开发仍可使用 `npm run install:local:user`,但不要把这条路径放进首次用户 onboarding。
301
440
 
302
441
  ### 在 OpenCode 中使用
303
442
 
@@ -307,10 +446,14 @@ npm run version
307
446
  2. 选择 CrewBee 投影出的 agent(例如 `coding-leader`)
308
447
  3. 正常发送请求
309
448
 
449
+ ---
450
+
310
451
  ## Agent Team 与 Agent Profile 定义方式
311
452
 
312
453
  如果你要设计并注册自己的文件型 Team,请先阅读 [自定义 Agent Team 指南](docs/guide/custom-agent-team.md)。它会说明真实可运行的目录结构、`crewbee.json` 注册方式、Team policy 设计、Agent 职责边界和验证清单。
313
454
 
455
+ 如果你需要让项目级 Team 覆盖或补充全局 Team,请继续阅读 [项目级 Team 配置指南](docs/guide/project-team-config.md)。
456
+
314
457
  ### 文件型 Team 的实际结构
315
458
 
316
459
  当前真实可运行的文件型 Team 结构是:
@@ -522,14 +665,33 @@ package.json
522
665
 
523
666
  CrewBee 当前最重要的方法论样板,就是内置 Coding Team。
524
667
 
525
- 它的核心判断包括:
668
+ ### 1. 主 Agent 持有最完整上下文
669
+
670
+ Coding Team 的主 Agent / formal leader 是默认入口、主线 owner 和最终收口责任人。
671
+
672
+ 它负责汇总:
526
673
 
527
- ### 1. Leader 不等于 Planner,不等于纯 Orchestrator
674
+ * 用户目标
675
+ * 仓库约束
676
+ * 代码探索结果
677
+ * 外部研究结论
678
+ * reviewer 意见
679
+ * 验证结果
680
+ * 风险与未决事项
528
681
 
529
- Leader 是默认入口、主链路 owner 和最终收口责任人。
530
- 但 Leader 不被预设为“只能编排、不能执行”的角色。
682
+ 关键判断由主 Agent 基于完整上下文完成。
531
683
 
532
- ### 2. 最值得独立出去的通常不是 Planner,而是 Reviewer
684
+ ### 2. 简单任务不强制复杂协作
685
+
686
+ CrewBee 认为:
687
+
688
+ * **简单任务** 应该轻
689
+ * **复杂但常规的工程任务** 适合 Team 协作结构化介入
690
+ * **极难问题** 应保持上下文集中、试错快速、人类主导清晰
691
+
692
+ 因此,Coding Team 不应把所有任务都变成完整团队流程。
693
+
694
+ ### 3. 最值得独立出去的通常不是 Planner,而是 Reviewer
533
695
 
534
696
  在 Coding 场景里,计划、执行、验证是强耦合回路。
535
697
  真正值钱的是:
@@ -547,22 +709,51 @@ Leader 是默认入口、主链路 owner 和最终收口责任人。
547
709
 
548
710
  而不是 O / P / E 三权平分。
549
711
 
550
- ### 3. 简单任务不强制复杂协作,难题也不默认走重仪式
712
+ ### 4. 支援 Agent 独立上下文,主 Agent 统一收口
551
713
 
552
- CrewBee 认为:
714
+ 对于代码任务,CrewBee 更强调:
553
715
 
554
- * **简单任务** 应该轻
555
- * **极难问题** 应该尽量保持上下文集中、试错快速、人类主导清晰
556
- * **复杂但常规的工程任务** 才更适合 Team 协作结构化介入
716
+ * 主 Agent 长期持有主上下文
717
+ * Codebase Explorer 独立定位代码证据
718
+ * Web Researcher 独立查外部资料
719
+ * Reviewer 独立审查风险和完成标准
720
+ * Principal Advisor 按需提供高阶判断
721
+ * 主 Agent 接收高信号结论后统一决策和收口
557
722
 
558
- ### 4. 主执行 owner + research + review 是当前更重要的样板结构
723
+ ---
724
+
725
+ ## 下一步:Project Context
726
+
727
+ Project Context 是 CrewBee 下一阶段的重要产品力方向。
728
+
729
+ 它的目标是跨会话自动维护项目上下文,使长期项目持续持有高信号摘要信息,包括:
730
+
731
+ * 项目定位
732
+ * 框架设计
733
+ * 架构摘要
734
+ * 关键历史记录
735
+ * 当前实现状态
736
+ * 当前计划
737
+ * 已知风险
738
+ * 决策记录
739
+ * 下一步行动
740
+ * handoff 摘要
741
+
742
+ Project Context 不应只是一次性生成项目摘要,而应在项目推进过程中持续更新:
743
+
744
+ ```text
745
+ 会话开始:读取 project context,恢复项目定位、框架、历史记录和当前计划。
746
+ 任务执行:根据当前目标阅读必要代码和资料。
747
+ 会话结束:自动更新 project context,记录新的实现状态、决策、风险和下一步计划。
748
+ 下一次会话:基于最新 project context 继续工作。
749
+ ```
750
+
751
+ 它可以减少两类成本:
559
752
 
560
- 对于代码任务,CrewBee 当前更强调:
753
+ 1. **减少手动提示补充**:用户不需要每次重新解释项目定位、历史决策和当前计划。
754
+ 2. **减少完整阅读工程代码带来的上下文消耗**:Agent 可以先根据 project context 理解项目结构、关键模块和当前任务相关区域,再进行针对性代码阅读。
561
755
 
562
- * formal leader 不等于纯管理者
563
- * 主执行 owner 可以长期持有主上下文
564
- * 专项研究、评审、顾问按需插入
565
- * reviewer 独立存在,质量视角独立于主执行链路
756
+ > 当前说明:Project Context 是下一阶段重点增强方向,不应理解为当前已经完整实现的成熟能力。
566
757
 
567
758
  ---
568
759
 
@@ -577,9 +768,12 @@ npm run test
577
768
  npm run pack:local
578
769
  npm run pack:release
579
770
  npm run release:registry:dry-run
771
+ npm run setup
580
772
  npm run install:local:user
581
773
  npm run install:registry:user
774
+ npm run update
582
775
  npm run doctor
776
+ npm run uninstall
583
777
  npm run uninstall:user
584
778
  npm run simulate:opencode
585
779
  npm run simulate:compact
@@ -593,10 +787,13 @@ npm run simulate:compact
593
787
  * `pack:local`:打包本地 tarball
594
788
  * `pack:release`:打包版本化 release tarball
595
789
  * `release:registry:dry-run`:在本地执行 registry 发布预检但不真正发布
790
+ * `setup`:面向用户的产品化安装;必要时安装 OpenCode,安装 CrewBee,写入配置并运行 doctor
596
791
  * `install:local:user`:执行完整用户级安装
597
792
  * `install:registry:user`:把已发布的 npm 包安装到用户级 workspace
793
+ * `update`:从 registry 重装 CrewBee 并运行 doctor
598
794
  * `doctor`:校验 OpenCode 配置与安装状态
599
795
  * `version`:显示当前包版本与已安装包版本
796
+ * `uninstall`:从 OpenCode config 和用户级 workspace 中移除 CrewBee
600
797
  * `uninstall:user`:卸载用户级安装
601
798
  * `simulate:opencode`:运行本地 OpenCode runtime simulator
602
799
  * `simulate:compact`:运行 compact 场景验证脚本
@@ -617,7 +814,7 @@ crewbee
617
814
  发布手册:
618
815
 
619
816
  ```text
620
- docs/guide/release.md
817
+ docs/guide/release.zh-CN.md
621
818
  ```
622
819
 
623
820
  Windows 下默认仍优先使用:
@@ -648,3 +845,13 @@ npm run uninstall:user
648
845
  ```bash
649
846
  npm run doctor
650
847
  ```
848
+
849
+ ---
850
+
851
+ ## 致谢
852
+
853
+ CrewBee 受 OpenCode 以及 oh-my-openagent 等社区项目启发。这些项目探索了 Agent Team 工作流在真实开发环境中的价值,也让更多开发者看到了多 Agent 协作的潜力。
854
+
855
+ 感谢这些项目的开发者与维护者。
856
+
857
+ CrewBee 在这个方向上继续推进:把 Agent Team 从一组提示词或角色配置,进一步整理为可管理、可投影、可配置、可复用的工程资产,使不同任务 / 项目下的 Agent Team 能够更清晰地定义、运行和演化。