feat: 支持多语言提示词本地化和界面优化
- 添加 prompt_locale 参数支持简体中文、繁体中文和英文提示词本地化 - 移除内置 agents 配置以简化系统架构 - 更新 ContextBuilder 使用动态提示词模板而非硬编码内容 - 在 AgentLoop、Web 接口和 AgentService 中传递 locale 参数 - 添加输出语言指令确保用户界面内容按指定语言生成 - 扩展前端 LanguageSwitcher 组件支持三种语言选项 - 优化 Header 和侧边栏组件的响应式布局和文本截断处理 - 更新测试用例验证不同语言环境下的提示词正确性
This commit is contained in:
439
docs/product-discovery/beaver/product-architecture-brief.md
Normal file
439
docs/product-discovery/beaver/product-architecture-brief.md
Normal file
@ -0,0 +1,439 @@
|
||||
# Beaver Product Architecture Brief
|
||||
|
||||
Date: 2026-06-09
|
||||
|
||||
Audience: product, engineering, delivery, security, and pilot stakeholders.
|
||||
|
||||
## 1. Architecture Summary
|
||||
|
||||
Beaver is built as a private-deployable, multi-instance Agent workspace.
|
||||
|
||||
At the top level, it has five deployment components:
|
||||
|
||||
```text
|
||||
Browser
|
||||
-> auth-portal
|
||||
-> authz-service
|
||||
-> deploy-control
|
||||
-> router-proxy
|
||||
-> app-instance
|
||||
```
|
||||
|
||||
Each `app-instance` contains the user-facing product:
|
||||
|
||||
```text
|
||||
app-instance container
|
||||
-> Nginx
|
||||
-> Next.js frontend
|
||||
-> Beaver backend
|
||||
-> mounted beaver-home
|
||||
-> config
|
||||
-> workspace
|
||||
-> skills
|
||||
-> runtime data
|
||||
```
|
||||
|
||||
The key product architecture choice is instance-level sandboxing. Each user or team can receive a separate app instance with its own config, workspace, files, skills, and runtime data.
|
||||
|
||||
## 2. Product-Level System Map
|
||||
|
||||
```text
|
||||
Auth and onboarding
|
||||
auth-portal
|
||||
-> register/login
|
||||
-> model provider onboarding
|
||||
authz-service
|
||||
-> account and backend identity
|
||||
deploy-control
|
||||
-> create/configure/remove app-instance
|
||||
router-proxy
|
||||
-> route instance host to app-instance container
|
||||
|
||||
User workspace
|
||||
app-instance/frontend
|
||||
-> chat workbench
|
||||
-> tasks
|
||||
-> files
|
||||
-> skills
|
||||
-> marketplace
|
||||
-> MCP/tools
|
||||
-> notifications/cron
|
||||
-> connectors
|
||||
-> settings/status/logs
|
||||
|
||||
Agent runtime
|
||||
app-instance/backend
|
||||
-> interfaces
|
||||
-> services
|
||||
-> engine
|
||||
-> coordinator
|
||||
-> tools
|
||||
-> skills
|
||||
-> memory
|
||||
-> integrations
|
||||
```
|
||||
|
||||
## 3. Deployment Components
|
||||
|
||||
### Auth Portal
|
||||
|
||||
Responsibility:
|
||||
|
||||
- User login and registration entry.
|
||||
- Provider onboarding after registration.
|
||||
- Handoff into the user app instance.
|
||||
|
||||
Product value:
|
||||
|
||||
- Gives non-technical users a clean entry point.
|
||||
- Separates account onboarding from the per-instance app.
|
||||
|
||||
Key risk:
|
||||
|
||||
- Provider configuration must be understandable and recoverable for non-engineer users.
|
||||
|
||||
### AuthZ Service
|
||||
|
||||
Responsibility:
|
||||
|
||||
- Account and backend identity orchestration.
|
||||
- Internal token-protected coordination.
|
||||
|
||||
Product value:
|
||||
|
||||
- Centralizes identity relationships between portal and app backends.
|
||||
|
||||
Key risk:
|
||||
|
||||
- Misconfigured issuer/internal URL can break new app instances.
|
||||
|
||||
### Deploy Control
|
||||
|
||||
Responsibility:
|
||||
|
||||
- Create, configure, and manage app instances.
|
||||
- Call `app-instance/create-instance.sh`.
|
||||
- Write provider config and restart instance when needed.
|
||||
|
||||
Product value:
|
||||
|
||||
- Makes private instance provisioning repeatable.
|
||||
|
||||
Key risk:
|
||||
|
||||
- Must not be exposed publicly.
|
||||
- Needs health checks and lifecycle operations for pilot scale.
|
||||
|
||||
### Router Proxy
|
||||
|
||||
Responsibility:
|
||||
|
||||
- Route hostnames to the correct app instance container.
|
||||
|
||||
Product value:
|
||||
|
||||
- Lets each instance have a stable public URL.
|
||||
|
||||
Key risk:
|
||||
|
||||
- Domain, wildcard DNS, HTTPS, and route reload errors can block access.
|
||||
|
||||
### App Instance
|
||||
|
||||
Responsibility:
|
||||
|
||||
- The user-facing Beaver workspace.
|
||||
- Runs frontend, backend, and Nginx in one container.
|
||||
- Mounts the instance's `beaver-home` as config and workspace boundary.
|
||||
|
||||
Product value:
|
||||
|
||||
- Provides practical sandboxing for early private deployments.
|
||||
|
||||
Key risk:
|
||||
|
||||
- Instance lifecycle, backup, restore, and resource limits need productized operations.
|
||||
|
||||
## 4. App Instance Product Modules
|
||||
|
||||
### Frontend Modules
|
||||
|
||||
| Module | Route | Product Job |
|
||||
| --- | --- | --- |
|
||||
| Chat workbench | `/` | Main workspace for conversation, attachments, task cards, and acceptance |
|
||||
| Tasks | `/tasks`, `/tasks/[taskId]` | Track ordinary and scheduled task lifecycle, timeline, evidence, artifacts |
|
||||
| Notifications | `/notifications` | Review proactive or scheduled outputs |
|
||||
| Cron | `/cron` | Manage scheduled jobs |
|
||||
| Files | `/files` | Browse, upload, preview, download, delete workspace files |
|
||||
| Skills | `/skills` | Manage published skills, candidates, drafts, safety/eval, review, publish |
|
||||
| Marketplace | `/marketplace` | Discover and install skills |
|
||||
| MCP/tools | `/mcp` | Manage tool servers, tool details, test, add, edit, delete |
|
||||
| Agents | `/agents` | Manage Agent definitions and roles |
|
||||
| Outlook/connectors | `/outlook`, settings connector panels | Connect external systems |
|
||||
| Settings/status/logs | `/settings`, `/status`, `/logs` | Configure providers, runtime, channels, health, and debugging |
|
||||
|
||||
### Backend Modules
|
||||
|
||||
| Module | Responsibility |
|
||||
| --- | --- |
|
||||
| `foundation` | Shared config, errors, events, utilities, base models |
|
||||
| `engine` | Unified Agent runtime used by main Agent and sub-agents |
|
||||
| `coordinator` | Multi-agent sequence/parallel/DAG execution |
|
||||
| `tools` | Built-in and MCP tool registration/execution |
|
||||
| `skills` | Skill loading, resolution, drafts, learning, review, publish |
|
||||
| `memory` | Long-term memory and run/skill stores |
|
||||
| `permissions` | Governance and policy surface |
|
||||
| `services` | Application orchestration, tasks, cron, process projection |
|
||||
| `interfaces` | Web, CLI, Gateway, channels, MCP servers |
|
||||
| `integrations` | AuthZ, MCP, external protocols, connector clients |
|
||||
|
||||
## 5. Core Product Flows
|
||||
|
||||
### Flow A: New User Registration And First Workspace
|
||||
|
||||
```text
|
||||
Browser
|
||||
-> auth-portal register
|
||||
-> authz-service /portal/register
|
||||
-> deploy-control /api/instances/register
|
||||
-> create app-instance container
|
||||
-> app-instance backend registers user/backend
|
||||
-> provider onboarding
|
||||
-> deploy-control configures provider
|
||||
-> user enters app-instance URL
|
||||
```
|
||||
|
||||
Product requirements:
|
||||
|
||||
- Clear success/failure state during provisioning.
|
||||
- Provider setup can be skipped but instance must explain missing model config later.
|
||||
- Internal control-plane endpoints stay private.
|
||||
|
||||
### Flow B: Chat To Managed Task
|
||||
|
||||
```text
|
||||
User message
|
||||
-> chat workbench
|
||||
-> backend task router
|
||||
-> ordinary chat or task mode
|
||||
-> task created
|
||||
-> Agent execution
|
||||
-> tool calls and artifacts
|
||||
-> task timeline
|
||||
-> user accepts / asks revision / abandons
|
||||
```
|
||||
|
||||
Product requirements:
|
||||
|
||||
- The user must understand when a message became a task.
|
||||
- The task must be recoverable from chat, task list, and details page.
|
||||
- Acceptance feedback must influence future learning.
|
||||
|
||||
### Flow C: Complex Task With Agent Team
|
||||
|
||||
```text
|
||||
Task request
|
||||
-> TaskExecutionPlanner
|
||||
-> ExecutionGraph
|
||||
-> sequence / parallel / DAG nodes
|
||||
-> TaskSkillResolver binds skills or ephemeral guidance
|
||||
-> LocalAgentRunner executes nodes
|
||||
-> main Agent synthesizes final answer
|
||||
-> evidence saved
|
||||
```
|
||||
|
||||
Product requirements:
|
||||
|
||||
- Team execution should be visible without overwhelming users.
|
||||
- Failed subtasks should be diagnosable.
|
||||
- Final synthesis should cite or summarize subtask evidence.
|
||||
|
||||
### Flow D: Skill Learning Loop
|
||||
|
||||
```text
|
||||
Accepted task
|
||||
-> skill learning candidate
|
||||
-> draft synthesis
|
||||
-> safety report
|
||||
-> eval report
|
||||
-> human review
|
||||
-> publish
|
||||
-> future skill retrieval
|
||||
```
|
||||
|
||||
Product requirements:
|
||||
|
||||
- Only accepted or otherwise high-signal work should become skill candidates.
|
||||
- Publishing requires review and gates.
|
||||
- Skill quality must be traceable over versions.
|
||||
|
||||
### Flow E: File And Tool Work
|
||||
|
||||
```text
|
||||
User uploads file or Agent needs file/tool
|
||||
-> workspace file API or tool registry
|
||||
-> Agent tool execution
|
||||
-> result returned to context
|
||||
-> event/evidence saved
|
||||
-> artifact available in task or files
|
||||
```
|
||||
|
||||
Product requirements:
|
||||
|
||||
- User-visible file roots must stay simple.
|
||||
- Tool calls must be recorded.
|
||||
- Dangerous tools need policy and review.
|
||||
|
||||
### Flow F: Scheduled Work And Notifications
|
||||
|
||||
```text
|
||||
User creates scheduled job
|
||||
-> cron service stores job
|
||||
-> scheduled run triggers task/notification
|
||||
-> user reviews output
|
||||
-> output can become normal task continuation
|
||||
```
|
||||
|
||||
Product requirements:
|
||||
|
||||
- Scheduled outputs need the same acceptance path as manual tasks.
|
||||
- Failed scheduled runs need alerts and retry/recovery.
|
||||
|
||||
### Flow G: External Connectors
|
||||
|
||||
```text
|
||||
Connector setup
|
||||
-> channel/connector config
|
||||
-> sidecar or external provider
|
||||
-> inbound event or outbound action
|
||||
-> Beaver task/runtime
|
||||
-> response or notification
|
||||
```
|
||||
|
||||
Product requirements:
|
||||
|
||||
- External writes need clear user/admin control.
|
||||
- Connector onboarding must show state, errors, and reconnect steps.
|
||||
- Multi-instance callback routing must be explicit.
|
||||
|
||||
## 6. Governance Boundaries
|
||||
|
||||
### Instance Boundary
|
||||
|
||||
Each app instance owns:
|
||||
|
||||
- `config.json`
|
||||
- `web_auth_users.json`
|
||||
- `workspace/`
|
||||
- skills and runtime state
|
||||
- provider configuration
|
||||
|
||||
Risk:
|
||||
|
||||
- Cross-instance leakage would be a critical incident.
|
||||
|
||||
### Control Plane Boundary
|
||||
|
||||
Public exposure should be limited to:
|
||||
|
||||
- Auth portal.
|
||||
- Router proxy for app instances.
|
||||
|
||||
Do not expose:
|
||||
|
||||
- `deploy-control`.
|
||||
- `authz-service`.
|
||||
|
||||
### Tool Boundary
|
||||
|
||||
Tools are the action surface. Policy should distinguish:
|
||||
|
||||
- Read-only tools.
|
||||
- Workspace-scoped write tools.
|
||||
- External write tools.
|
||||
- Destructive tools.
|
||||
- Credential/permission/payment tools.
|
||||
|
||||
### Skill Boundary
|
||||
|
||||
Skills guide Agent behavior and tool use. Publishing a bad skill can create repeated bad behavior. Skill publishing therefore needs:
|
||||
|
||||
- Candidate quality signal.
|
||||
- Safety report.
|
||||
- Eval/replay evidence where possible.
|
||||
- Human review.
|
||||
- Version rollback.
|
||||
|
||||
### Memory Boundary
|
||||
|
||||
Memory creates long-term product value but also trust risk. Productization should include:
|
||||
|
||||
- Source.
|
||||
- Confidence.
|
||||
- Last used.
|
||||
- Edit/delete/freeze controls.
|
||||
- Task evidence showing when memory was used.
|
||||
|
||||
## 7. Architecture Maturity
|
||||
|
||||
| Area | Maturity | Notes |
|
||||
| --- | --- | --- |
|
||||
| Multi-instance deployment | Pilot-ready | Needs lifecycle and health automation |
|
||||
| Chat workbench | Pilot-ready | UI docs show tested states |
|
||||
| Task lifecycle | Strong | Core product loop exists |
|
||||
| Task evidence | Strong foundation | Needs narrative/summary layer |
|
||||
| Agent team | Functional | Needs product explanation and failure UX |
|
||||
| Files | Pilot-ready | UI docs show tested workflows |
|
||||
| Tools/MCP | Functional | Needs policy hardening and admin clarity |
|
||||
| Skills | Functional | Needs stronger quality gates and reuse metrics |
|
||||
| Memory | Backend foundation | Needs visible product controls |
|
||||
| Scheduled work | Basic product capability | Needs stability and clearer run handling |
|
||||
| Connectors | Mixed maturity | Need pilot-safe connector list |
|
||||
| Operations | Basic | Needs health console, backup/restore, runbook |
|
||||
|
||||
## 8. Architecture Risks
|
||||
|
||||
| Risk | Severity | Mitigation |
|
||||
| --- | --- | --- |
|
||||
| Control-plane service exposed publicly | Critical | Deployment checks and docs; firewall/proxy validation |
|
||||
| Instance data leakage | Critical | Path isolation tests, authz tests, MinIO/user-files policy checks |
|
||||
| Tool side effects without review | High | Tool policy profiles, evidence logs, connector sandbox |
|
||||
| Provider misconfiguration blocks first use | High | Onboarding checks and settings diagnostics |
|
||||
| Product surface becomes hard to operate | High | Admin health console and staged pilot scope |
|
||||
| Memory trust gap | High | Memory control center before broad memory activation |
|
||||
| Skill quality drift | High | Safety/eval/replay and publish gates |
|
||||
|
||||
## 9. Recommended Architecture Roadmap
|
||||
|
||||
### Next 30 Days
|
||||
|
||||
- Rehearse clean deployment and record missing steps.
|
||||
- Add pilot health checklist for auth portal, authz, deploy control, router, and app instance.
|
||||
- Define pilot-safe tools and connectors.
|
||||
- Add task evidence narrative summary.
|
||||
- Track accepted task, skill candidate, and skill reuse events.
|
||||
|
||||
### Next 90 Days
|
||||
|
||||
- Memory Control Center MVP.
|
||||
- Admin Health Console MVP.
|
||||
- Instance suspend/resume/backup/restore runbook or tooling.
|
||||
- Connector sandboxing and side-effect policy.
|
||||
- Skill replay/eval as part of skill governance.
|
||||
- Organization/team-level roadmap decision.
|
||||
|
||||
## 10. Product Architecture Principle
|
||||
|
||||
Beaver should keep its product architecture centered on controlled Agent work:
|
||||
|
||||
```text
|
||||
private workspace
|
||||
+ task lifecycle
|
||||
+ tool/file execution
|
||||
+ evidence
|
||||
+ acceptance
|
||||
+ skill/memory reuse
|
||||
+ operational governance
|
||||
```
|
||||
|
||||
New features should strengthen this loop. Features that do not improve execution, evidence, acceptance, reuse, or governance should be treated as secondary until the pilot motion is proven.
|
||||
Reference in New Issue
Block a user