From 6e6f69f461cdd98b7bb9e0a0520544dbb3f5c355 Mon Sep 17 00:00:00 2001 From: 520wheat <2058672418@qq.com> Date: Sat, 11 Apr 2026 20:48:32 +0800 Subject: [PATCH 01/10] docs(architecture): regenerate module docs and interfaces --- docs/bytemind-architecture/README.md | 226 ++++++++++++++++++ docs/bytemind-architecture/agent/README.md | 39 +++ docs/bytemind-architecture/agent/interface.go | 144 +++++++++++ docs/bytemind-architecture/app/README.md | 30 +++ docs/bytemind-architecture/app/interface.go | 64 +++++ docs/bytemind-architecture/context/README.md | 32 +++ .../context/interface.go | 110 +++++++++ docs/bytemind-architecture/core/README.md | 21 ++ docs/bytemind-architecture/core/interface.go | 47 ++++ .../extensions/README.md | 32 +++ .../extensions/interface.go | 104 ++++++++ docs/bytemind-architecture/policy/README.md | 29 +++ .../bytemind-architecture/policy/interface.go | 82 +++++++ docs/bytemind-architecture/provider/README.md | 32 +++ .../provider/interface.go | 102 ++++++++ docs/bytemind-architecture/runtime/README.md | 33 +++ .../runtime/interface.go | 108 +++++++++ docs/bytemind-architecture/session/README.md | 30 +++ .../session/interface.go | 108 +++++++++ docs/bytemind-architecture/storage/README.md | 29 +++ .../storage/interface.go | 66 +++++ docs/bytemind-architecture/tools/README.md | 32 +++ docs/bytemind-architecture/tools/interface.go | 109 +++++++++ 23 files changed, 1609 insertions(+) create mode 100644 docs/bytemind-architecture/README.md create mode 100644 docs/bytemind-architecture/agent/README.md create mode 100644 docs/bytemind-architecture/agent/interface.go create mode 100644 docs/bytemind-architecture/app/README.md create mode 100644 docs/bytemind-architecture/app/interface.go create mode 100644 docs/bytemind-architecture/context/README.md create mode 100644 docs/bytemind-architecture/context/interface.go create mode 100644 docs/bytemind-architecture/core/README.md create mode 100644 docs/bytemind-architecture/core/interface.go create mode 100644 docs/bytemind-architecture/extensions/README.md create mode 100644 docs/bytemind-architecture/extensions/interface.go create mode 100644 docs/bytemind-architecture/policy/README.md create mode 100644 docs/bytemind-architecture/policy/interface.go create mode 100644 docs/bytemind-architecture/provider/README.md create mode 100644 docs/bytemind-architecture/provider/interface.go create mode 100644 docs/bytemind-architecture/runtime/README.md create mode 100644 docs/bytemind-architecture/runtime/interface.go create mode 100644 docs/bytemind-architecture/session/README.md create mode 100644 docs/bytemind-architecture/session/interface.go create mode 100644 docs/bytemind-architecture/storage/README.md create mode 100644 docs/bytemind-architecture/storage/interface.go create mode 100644 docs/bytemind-architecture/tools/README.md create mode 100644 docs/bytemind-architecture/tools/interface.go diff --git a/docs/bytemind-architecture/README.md b/docs/bytemind-architecture/README.md new file mode 100644 index 00000000..0e8d8cd8 --- /dev/null +++ b/docs/bytemind-architecture/README.md @@ -0,0 +1,226 @@ +# bytemind 总体架构设计文档（Go 生态） + +## 1. 文档目标 +本文档定义 bytemind 的总体架构基线，用于技术评审、研发实施和演进治理。 + +## 2. 既定约束 +- 单入口 TUI，无 Gateway。 +- 无长期 Memory，无跨会话语义记忆。 +- 会话与任务不依赖数据库。 + +## 3. 架构目标 +- 支持 coding agent 主闭环：理解任务、调用工具、修改代码、执行验证、返回结果。 +- 支持长任务与并发：任务系统、后台执行、多代理协作。 +- 支持扩展：MCP、Skills。 +- 支持安全可控：权限分层、沙箱执行、风险拦截。 +- 支持工程治理：可恢复、可追踪、可测试。 + +## 4. 非目标 +- 不做多入口统一接入层。 +- 不做向量检索与长期知识记忆。 +- 不绑定中心化数据库部署。 + +## 5. 架构原则 +- Secure by Default：默认最小权限，高风险操作显式确认。 +- 单一职责：原子能力优先，复杂行为通过编排组合。 +- 显式状态：关键状态可持久化、可回放、可恢复。 +- 流式优先：事件级输出，避免黑盒执行。 +- 低耦合扩展：核心稳定，扩展通过标准契约接入。 +- 可验证性：核心机制均有可执行测试与验收指标。 + +## 6. 模块拆分（10 模块 + 1 共享内核） +- 业务模块（10）：`app/agent/session/context/provider/tools/runtime/policy/storage/extensions` +- 共享内核（1）：`core`（仅放跨模块公共类型与最小错误契约） + +## 7. 目录结构（Go） +```text +bytemind/ + cmd/ + bytemind/ + internal/ + core/ + app/ + agent/ + session/ + context/ + provider/ + tools/ + runtime/ + policy/ + storage/ + extensions/ +``` + +## 8. 模块职责（做什么 / 不做什么） +### core +- 做：跨模块共享基础类型（SessionID/TaskID/Role/Decision/RiskLevel/TaskStatus）与通用错误契约。 +- 不做：业务流程、模块专属请求结构、具体实现。 + +### app +- 做：配置加载、依赖注入、生命周期管理。 +- 不做：业务编排与策略判断。 + +### agent +- 做：用户消息处理、模型交互编排、工具调用协调、结果归并。 +- 不做：工具实现细节、权限规则实现、持久化细节。 + +### session +- 做：会话创建/关闭、模式切换、会话快照与事件回放。 +- 不做：模型调用、任务调度、长期记忆。 + +### context +- 做：上下文拼装、预算计算、压缩裁剪与不变量校验。 +- 不做：模型请求发送、权限判定、工具执行。 + +### provider +- 做：供应商抽象、模型路由、流式事件统一、错误语义化。 +- 不做：会话持久化、业务调度、权限判定。 + +### tools +- 做：工具 schema 校验、执行调度、事件标准化输出。 +- 不做：会话级策略决策。 + +### runtime +- 做：任务状态机、超时/取消/重试、多代理调度与归并。 +- 不做：权限规则定义。 + +### policy +- 做：allow/deny/ask 决策、风险分级、路径/命令/敏感文件防护。 +- 不做：业务动作执行。 + +### storage +- 做：会话/任务日志写入、回放恢复、幂等去重。 +- 不做：业务决策与调度。 + +### extensions +- 做：MCP/Skills 通过统一契约接入 tools。 +- 不做：主循环控制。 + +## 9. 强制依赖约束 +- 禁止循环依赖。 +- `app` 只做装配，不承载业务逻辑。 +- `agent` 仅通过接口访问 `session/context/provider/tools/runtime/policy/storage`。 +- `extensions` 不可直接读写 `agent` 内部状态。 +- `policy` 必须可独立测试，不依赖 `agent` 具体实现。 +- 公共类型只允许放在 `core`，模块接口只放本模块特有结构。 + +## 10. 模块交付标准 +每个模块固定两个文件： +- `README.md`：定位、边界、依赖、实现逻辑、测试策略。 +- `interface.go`：仅暴露接口与核心类型，不放实现。 + +## 11. 统一接口约束 +- 接口按调用方视角定义，避免泄漏实现细节。 +- 所有阻塞操作必须接收 `context.Context`。 +- 错误优先语义化（可判断、可测试）。 +- 事件流统一使用 channel/迭代器风格。 +- 接口层禁止引入具体 provider/tool 实现类型。 + +## 12. 核心执行流程 +### 12.1 单代理主闭环 +1. 用户提交消息到 `agent`。 +2. `agent` 读取 `session` 快照。 +3. `context` 构建上下文并计算预算。 +4. `provider` 执行流式推理。 +5. 工具调用前经 `policy` 决策。 +6. `tools/runtime` 执行并返回结果事件。 +7. `storage` 写入会话/任务日志，`session` 更新状态。 +8. `agent` 返回最终响应。 + +### 12.2 自动压缩（无 Memory） +- warning `>= 85%`，critical `>= 95%`。 +- `tool_use` 与 `tool_result` 成对保留。 +- `prompt_too_long` 触发一次 reactive compact + 重试。 + +### 12.3 任务系统 +- 状态机：`pending -> running -> completed|failed|killed`。 +- 机制：超时、取消传播、最大重试次数、终态回收。 +- 输出：任务日志按 offset 增量读取。 + +### 12.4 子代理 +- 同步子代理：父代理等待返回。 +- 异步后台代理：父代理继续执行，后续归并。 +- worktree 隔离代理：独立工作区执行，避免污染主工作区。 + +## 13. Tools 体系 +### 13.1 三层结构 +- 原子工具层：ReadFile/EditFile/WriteFile/Glob/Grep/Bash +- 组合工具层：TestRunner/GitWorkflow/TaskOutputReader +- 协作工具层：AgentTool/MCPTool/SkillTool/TeamTool + +### 13.2 统一契约 +```go +type Tool interface { + Name() string + Description() string + Schema() json.RawMessage + Execute(ctx context.Context, args json.RawMessage, tctx ToolUseContext) (<-chan ToolEvent, error) +} +``` + +### 13.3 强制规范 +- 参数 schema 强校验。 +- 显式声明副作用级别与幂等级别。 +- 支持超时、取消、重试语义。 +- 统一事件流：start/chunk/result/error。 +- 每个工具必须有 mock/contract 单测。 + +## 14. 权限与安全架构 +### 14.1 五层权限模型 +- 会话模式层：default/acceptEdits/bypassPermissions(受控)/plan +- 工具白黑名单层：allowedTools/deniedTools +- 工具级策略层：读默认放行，写与命令默认询问 +- 风险层：low/medium/high +- 路径命令层：allowedWritePaths/deniedWritePaths/allowedCommands/deniedCommands + +### 14.2 决策优先级（固定） +`explicit deny > explicit allow > risk rule > mode default > fallback ask` + +### 14.3 安全基线 +- Prompt Injection：系统指令优先，工具输出隔离。 +- 路径安全：resolve + realpath + allowlist。 +- 命令安全：白名单 + 高危规则。 +- 敏感文件保护：密钥/凭证默认拒绝读取。 +- 沙箱策略：网络开关、路径白名单、资源限额。 + +## 15. 文件存储与恢复（不落库） +### 15.1 文件布局 +- `~/.bytemind/sessions/.jsonl` +- `~/.bytemind/tasks/.log` + +### 15.2 一致性策略 +- append-only 写入。 +- 单记录原子落盘（tmp+rename 或 fsync）。 +- 会话级文件锁，避免并发乱序。 +- 事件携带 `event_id`，恢复时幂等去重。 + +## 16. 可观测性 +### 16.1 指标 +- 请求成功率、工具成功率、任务成功率。 +- 首字节时延（模型/工具/存储分层）。 +- token 消耗与单位任务成本。 +- 权限拒绝率与高危拦截率。 +- 压缩触发率与恢复成功率。 + +### 16.2 Trace +链路贯穿：`agent -> session -> context -> provider -> policy -> tools -> runtime -> storage` + +## 17. 测试与治理要求（强制） +- Contract Test：工具 schema、事件流一致性。 +- Replay Test：session/task 回放一致性。 +- Policy Test：规则冲突、优先级、边界样例。 +- Failure Test：超时、取消、崩溃恢复、重试风暴。 +- Multi-Agent Test：并发配额、资源争用、冲突归并。 +- 安全回归：高危命令、敏感文件、路径逃逸。 + +## 18. 主要风险与应对 +- 工具误操作风险。应对：多层权限 + 高危确认 + 沙箱。 +- 上下文膨胀风险。应对：预算器 + 自动压缩。 +- 多代理复杂度风险。应对：依赖图调度 + 配额控制 + 终态约束。 +- 文件一致性风险。应对：原子写 + 锁 + 幂等回放。 + +## 19. 去冗余收敛（本次调整） +- 删除独立审计子系统，避免与会话/任务日志重复写入。 +- 删除 `TurnRequest.HistoryOverride`，统一历史来源为 `session` 快照。 +- 抽取 `core` 共享内核，消除跨模块重复定义。 + diff --git a/docs/bytemind-architecture/agent/README.md b/docs/bytemind-architecture/agent/README.md new file mode 100644 index 00000000..352d7db8 --- /dev/null +++ b/docs/bytemind-architecture/agent/README.md @@ -0,0 +1,39 @@ +# agent 模块设计 + +## 1. 模块定位 +`agent` 是 coding agent 的主闭环编排层，负责请求处理、模型交互、工具协调和结果归并。 + +## 2. 职责边界 +做什么： +- 接收用户输入并读取会话快照。 +- 调用 `context` 构建模型请求并执行预算/压缩。 +- 调用 `provider` 消费流式模型事件。 +- 工具调用前走 `policy` 决策，再调度 `tools`。 +- 与 `runtime` 协作执行子代理。 + +不做什么： +- 不实现工具细节。 +- 不实现权限规则本身。 +- 不实现任务状态机与底层存储细节。 + +## 3. 对外接口 +- `Engine`：单轮主入口，处理 `TurnRequest` 并输出 `TurnEvent` 流。 +- `SessionGateway`：获取会话快照并追加 turn 结果。 +- `ContextGateway`：将输入和会话快照构建为模型请求。 +- `ModelGateway`：统一模型流式调用入口。 +- `PolicyGateway`：执行工具调用前权限决策。 +- `ToolGateway`：执行工具并返回工具结果事件流。 +- `RuntimeGateway`：创建和等待子代理任务。 + +## 4. 主闭环 +1. 读取 `session` 快照。 +2. 构建 `context`。 +3. 调用 `provider`。 +4. 工具意图先过 `policy`。 +5. 调用 `tools/runtime`。 +6. 写入 `session/storage` 并返回终态。 + +## 5. 测试策略 +- 主循环契约测试：事件顺序与终态一致性。 +- 压缩测试：阈值触发与配对保留。 +- 工具编排测试：超时、取消、重试、并发上限。 diff --git a/docs/bytemind-architecture/agent/interface.go b/docs/bytemind-architecture/agent/interface.go new file mode 100644 index 00000000..469c4c3e --- /dev/null +++ b/docs/bytemind-architecture/agent/interface.go @@ -0,0 +1,144 @@ +package agent + +import ( + "context" + "encoding/json" + "time" + + "bytemind/internal/core" +) + +type ErrorCode string + +const ( + ErrCodePromptTooLong ErrorCode = "prompt_too_long" + ErrCodeModelUnavailable ErrorCode = "model_unavailable" + ErrCodeModelStream ErrorCode = "model_stream_error" + ErrCodeToolExecute ErrorCode = "tool_execute_error" + ErrCodePermissionDenied ErrorCode = "permission_denied" + ErrCodePersistFailed ErrorCode = "persist_failed" +) + +type Message struct { + Role core.Role + Content string + Name string // message source name, e.g. tool or sub-agent name + ToolCallID string + CreatedAt time.Time +} + +type TurnRequest struct { + SessionID core.SessionID + Input string + MaxInputTokens int + MaxOutputTokens int + Metadata map[string]string +} + +type TurnEventType string + +const ( + TurnEventStart TurnEventType = "start" + TurnEventDelta TurnEventType = "delta" + TurnEventToolUse TurnEventType = "tool_use" + TurnEventToolOut TurnEventType = "tool_result" + TurnEventComplete TurnEventType = "complete" + TurnEventError TurnEventType = "error" +) + +type TurnEvent struct { + Type TurnEventType + TurnID string + SessionID core.SessionID + TaskID core.TaskID + Payload json.RawMessage + ErrorCode string + Timestamp time.Time +} + +type ToolCall struct { + CallID string + Name string + Args json.RawMessage +} + +type PermissionDecision struct { + Decision core.Decision + ReasonCode string +} + +type Engine interface { + HandleTurn(ctx context.Context, req TurnRequest) (<-chan TurnEvent, error) +} + +type SessionSnapshot struct { + SessionID core.SessionID + Mode string + Messages []Message + Metadata map[string]string +} + +type SessionGateway interface { + Snapshot(ctx context.Context, sessionID core.SessionID) (SessionSnapshot, error) + AppendTurn(ctx context.Context, sessionID core.SessionID, event TurnEvent) error +} + +type ContextBuildInput struct { + Request TurnRequest + Session SessionSnapshot +} + +type ModelRequest struct { + Messages []Message + ToolsSchemaJSON json.RawMessage + MaxOutputTokens int +} + +type ContextGateway interface { + Build(ctx context.Context, in ContextBuildInput) (ModelRequest, error) +} + +type ModelEvent struct { + Type string + Payload json.RawMessage +} + +type ModelGateway interface { + Stream(ctx context.Context, req ModelRequest) (<-chan ModelEvent, error) +} + +type PolicyGateway interface { + EvaluateToolUse(ctx context.Context, sessionID core.SessionID, call ToolCall) (PermissionDecision, error) +} + +type ToolResultEvent struct { + Type string + Payload json.RawMessage +} + +type ToolGateway interface { + Execute(ctx context.Context, call ToolCall, sessionID core.SessionID) (<-chan ToolResultEvent, error) +} + +type RuntimeGateway interface { + SpawnSubAgent(ctx context.Context, req SubAgentRequest) (SubAgentHandle, error) + WaitSubAgent(ctx context.Context, handle SubAgentHandle) (SubAgentResult, error) +} + +type SubAgentRequest struct { + ParentSessionID core.SessionID + Mode string + Prompt string + Background bool +} + +type SubAgentHandle struct { + SubTaskID core.TaskID +} + +type SubAgentResult struct { + SubTaskID core.TaskID + Output string + ErrorCode string +} + diff --git a/docs/bytemind-architecture/app/README.md b/docs/bytemind-architecture/app/README.md new file mode 100644 index 00000000..61b058fd --- /dev/null +++ b/docs/bytemind-architecture/app/README.md @@ -0,0 +1,30 @@ +# app 模块设计 + +## 1. 模块定位 +`app` 是系统装配根，负责配置加载、依赖注入和进程生命周期管理。 + +## 2. 职责边界 +做什么： +- 加载并校验配置。 +- 装配 `agent/session/context/provider/tools/runtime/policy/storage/extensions`。 +- 管理启动、就绪、优雅退出。 + +不做什么： +- 不承载业务编排逻辑。 +- 不实现权限、任务、工具、存储的业务细节。 + +## 3. 对外接口 +- `ConfigLoader`：加载并归一化配置源（文件/环境变量/参数）。 +- `Component`：统一组件生命周期（`Start/Stop/Ready`）。 +- `Bootstrapper`：根据配置构建模块集合 `ModuleSet`。 +- `LifecycleManager`：按依赖拓扑启动和关闭模块。 +- `Application`：应用进程入口（`Run/Shutdown`）。 + +## 4. 启停策略 +- 启动顺序建议：`storage -> session -> policy -> tools/extensions -> context -> provider -> runtime -> agent`。 +- 关闭顺序建议：按启动逆序关闭并刷盘。 + +## 5. 测试策略 +- 配置测试：默认值与非法配置校验。 +- 装配测试：依赖缺失与回滚完整性。 +- 生命周期测试：幂等启动/关闭、超时退出。 diff --git a/docs/bytemind-architecture/app/interface.go b/docs/bytemind-architecture/app/interface.go new file mode 100644 index 00000000..efef8b11 --- /dev/null +++ b/docs/bytemind-architecture/app/interface.go @@ -0,0 +1,64 @@ +package app + +import "context" + +type ErrorCode string + +const ( + ErrCodeInvalidConfig ErrorCode = "invalid_config" + ErrCodeBuildFailed ErrorCode = "build_failed" + ErrCodeStartFailed ErrorCode = "start_failed" + ErrCodeStopFailed ErrorCode = "stop_failed" + ErrCodeShutdownTimeout ErrorCode = "shutdown_timeout" +) + +type ConfigSource struct { + FilePath string + EnvPrefix string + Args []string + WorkingDir string +} + +type Config struct { + WorkspaceRoot string + SessionMode string + LogLevel string +} + +type ConfigLoader interface { + Load(ctx context.Context, source ConfigSource) (Config, error) +} + +type Component interface { + Name() string + Start(ctx context.Context) error + Stop(ctx context.Context) error + Ready() <-chan struct{} +} + +type ModuleSet struct { + Storage Component + Session Component + Policy Component + Tools Component + Extensions Component + Context Component + Provider Component + Runtime Component + Agent Component +} + +type Bootstrapper interface { + Build(ctx context.Context, cfg Config) (ModuleSet, error) +} + +type LifecycleManager interface { + Start(ctx context.Context, modules ModuleSet) error + Stop(ctx context.Context, modules ModuleSet) error +} + +type Application interface { + Run(ctx context.Context) error + Shutdown(ctx context.Context) error +} + diff --git a/docs/bytemind-architecture/context/README.md b/docs/bytemind-architecture/context/README.md new file mode 100644 index 00000000..31cec654 --- /dev/null +++ b/docs/bytemind-architecture/context/README.md @@ -0,0 +1,32 @@ +# context 模块设计 + +## 1. 模块定位 +`context` 负责模型输入上下文工程：拼装、预算、压缩、约束校验。 + +## 2. 职责边界 +做什么： +- 组合系统指令、会话历史、用户输入、工具 schema、运行时提示。 +- 计算 token 预算并输出预算计划。 +- 按 warning/critical/reactive 策略执行压缩。 +- 校验工具调用配对和系统约束不变量。 + +不做什么： +- 不直接请求模型。 +- 不直接写入会话存储。 +- 不执行权限判定与工具调用。 + +## 3. 对外接口 +- `Builder`：上下文构建入口，支持一次性结果与流式构建事件。 +- `Budgeter`：token 预算规划。 +- `Compactor`：上下文压缩策略执行。 +- `InvariantChecker`：压缩后语义不变量校验。 + +## 4. 关键规则 +- warning：`>= 85%`。 +- critical：`>= 95%`。 +- `prompt_too_long` 时允许一次 reactive compact + 重试。 + +## 5. 测试策略 +- 预算测试：不同模型上限下稳定。 +- 压缩测试：阈值触发、配对保留。 +- 构建测试：同输入可复现构建结果。 diff --git a/docs/bytemind-architecture/context/interface.go b/docs/bytemind-architecture/context/interface.go new file mode 100644 index 00000000..573744db --- /dev/null +++ b/docs/bytemind-architecture/context/interface.go @@ -0,0 +1,110 @@ +package context + +import ( + stdctx "context" + "encoding/json" + "time" + + "bytemind/internal/core" +) + +type ErrorCode string + +const ( + ErrCodeInvalidInput ErrorCode = "invalid_input" + ErrCodeBudgetExceeded ErrorCode = "budget_exceeded" + ErrCodeCompactionFailed ErrorCode = "compaction_failed" + ErrCodeInvariantViolated ErrorCode = "invariant_violated" +) + +type Message struct { + Role core.Role + Content string + Name string + ToolCallID string + CreatedAt time.Time +} + +type ToolDescriptor struct { + Name string + Description string + Schema json.RawMessage +} + +type RuntimeHint struct { + ActiveTaskID core.TaskID + TaskStatus core.TaskStatus + Metadata map[string]string +} + +type ProviderLimit struct { + ModelID string + MaxInputTokens int + MaxOutputTokens int +} + +type BuildRequest struct { + SessionID core.SessionID + UserInput string + History []Message + SystemPrompts []Message + Tools []ToolDescriptor + RuntimeHints []RuntimeHint + ProviderLimits ProviderLimit + Metadata map[string]string +} + +type BuildResult struct { + Messages []Message + Tools []ToolDescriptor + InputTokens int + OutputTokens int + UsageRatio float64 + CompactApplied bool + CompactMode string +} + +type BuildEventType string + +const ( + BuildEventStart BuildEventType = "start" + BuildEventPlan BuildEventType = "budget_plan" + BuildEventCompact BuildEventType = "compact" + BuildEventResult BuildEventType = "result" + BuildEventError BuildEventType = "error" +) + +type BuildEvent struct { + Type BuildEventType + EventID string + Payload json.RawMessage + ErrorCode string + Timestamp time.Time +} + +type BudgetPlan struct { + InputTokens int + MaxInputTokens int + UsageRatio float64 + NeedCompact bool + CompactMode string + PreserveToolPairs bool +} + +type Builder interface { + Build(ctx stdctx.Context, req BuildRequest) (BuildResult, error) + BuildStream(ctx stdctx.Context, req BuildRequest) (<-chan BuildEvent, error) +} + +type Budgeter interface { + Plan(ctx stdctx.Context, req BuildRequest) (BudgetPlan, error) +} + +type Compactor interface { + Compact(ctx stdctx.Context, history []Message, mode string, preserveToolPairs bool) ([]Message, error) +} + +type InvariantChecker interface { + Check(ctx stdctx.Context, messages []Message) error +} + diff --git a/docs/bytemind-architecture/core/README.md b/docs/bytemind-architecture/core/README.md new file mode 100644 index 00000000..d92d5f8e --- /dev/null +++ b/docs/bytemind-architecture/core/README.md @@ -0,0 +1,21 @@ +# core 模块设计（共享内核） + +## 1. 模块定位 +`core` 提供跨模块稳定共享的基础领域类型和通用错误契约，避免在各模块重复定义同义类型。 + +## 2. 职责边界 +做什么： +- 承载跨模块通用词汇：`SessionID`、`TaskID`、`Role`、`TaskStatus`、`Decision`、`RiskLevel`。 +- 提供最小通用错误契约：`SemanticError`。 + +不做什么： +- 不承载业务流程接口。 +- 不承载模块专属请求/响应结构。 +- 不依赖任何业务模块。 + +## 3. 对外接口（契约） +- `SemanticError`：统一错误抽象，约束 `Code()` 与 `Retryable()`，供上层判断与测试。 + +## 4. 设计约束 +- 仅当类型被两个及以上模块复用时，才允许进入 `core`。 +- 模块专属错误码、请求结构保留在模块内部。 diff --git a/docs/bytemind-architecture/core/interface.go b/docs/bytemind-architecture/core/interface.go new file mode 100644 index 00000000..f9cea6c2 --- /dev/null +++ b/docs/bytemind-architecture/core/interface.go @@ -0,0 +1,47 @@ +package core + +type SessionID string +type TaskID string + +type Role string + +const ( + RoleSystem Role = "system" + RoleUser Role = "user" + RoleAssistant Role = "assistant" + RoleTool Role = "tool" +) + +type TaskStatus string + +const ( + TaskPending TaskStatus = "pending" + TaskRunning TaskStatus = "running" + TaskCompleted TaskStatus = "completed" + TaskFailed TaskStatus = "failed" + TaskKilled TaskStatus = "killed" +) + +type Decision string + +const ( + DecisionAllow Decision = "allow" + DecisionDeny Decision = "deny" + DecisionAsk Decision = "ask" +) + +type RiskLevel string + +const ( + RiskLow RiskLevel = "low" + RiskMedium RiskLevel = "medium" + RiskHigh RiskLevel = "high" +) + +// SemanticError is the shared minimum contract for testable errors. +type SemanticError interface { + error + Code() string + Retryable() bool +} + diff --git a/docs/bytemind-architecture/extensions/README.md b/docs/bytemind-architecture/extensions/README.md new file mode 100644 index 00000000..37ea4104 --- /dev/null +++ b/docs/bytemind-architecture/extensions/README.md @@ -0,0 +1,32 @@ +# extensions 模块设计 + +## 1. 模块定位 +`extensions` 是外部能力接入层，负责将 MCP/Skills 通过统一契约桥接到 `tools`。 + +## 2. 职责边界 +做什么： +- 发现、加载、卸载扩展。 +- 校验扩展元数据、版本兼容与能力声明。 +- 将扩展能力映射为标准工具并注册到 `tools`。 +- 维护扩展健康状态和故障隔离。 + +不做什么： +- 不直接读写 `agent` 内部状态。 +- 不承担主循环控制和权限定义。 + +## 3. 对外接口 +- `Extension`：扩展生命周期契约（激活/停用/健康检查）。 +- `ExtensionTool`：扩展暴露的工具执行契约。 +- `ToolProvider`：获取扩展提供的工具集合。 +- `Manager`：扩展加载、卸载、查询管理。 +- `Resolver`：扩展能力到工具集合的解析器。 + +## 4. 生命周期流程 +1. 发现扩展。 +2. 校验元数据。 +3. 激活并桥接工具。 +4. 健康检查。 +5. 异常降级或卸载回滚。 + +## 5. 测试策略 +- 契约映射测试、生命周期测试、安全边界测试。 diff --git a/docs/bytemind-architecture/extensions/interface.go b/docs/bytemind-architecture/extensions/interface.go new file mode 100644 index 00000000..82cf81e5 --- /dev/null +++ b/docs/bytemind-architecture/extensions/interface.go @@ -0,0 +1,104 @@ +package extensions + +import ( + "context" + "encoding/json" + "time" + + "bytemind/internal/core" +) + +type ExtensionKind string + +const ( + ExtensionMCP ExtensionKind = "mcp" + ExtensionSkill ExtensionKind = "skill" +) + +type ExtensionStatus string + +const ( + StatusLoaded ExtensionStatus = "loaded" + StatusActive ExtensionStatus = "active" + StatusDegraded ExtensionStatus = "degraded" + StatusStopped ExtensionStatus = "stopped" +) + +type ErrorCode string + +const ( + ErrCodeInvalidManifest ErrorCode = "invalid_manifest" + ErrCodeIncompatible ErrorCode = "incompatible_version" + ErrCodeLoadFailed ErrorCode = "load_failed" + ErrCodeActivateFailed ErrorCode = "activate_failed" + ErrCodeToolBridge ErrorCode = "tool_bridge_failed" +) + +type ExtensionInfo struct { + ID string + Name string + Kind ExtensionKind + Version string + Status ExtensionStatus + Description string + UpdatedAt time.Time +} + +type Capability struct { + Name string + Description string + SideEffects []string +} + +type ActivateOptions struct { + WorkspaceRoot string + ConfigPath string + Env map[string]string +} + +type Extension interface { + Info() ExtensionInfo + Capabilities() []Capability + Activate(ctx context.Context, opts ActivateOptions) error + Deactivate(ctx context.Context) error + Health(ctx context.Context) (ExtensionStatus, error) +} + +type ToolUseContext struct { + SessionID core.SessionID + TaskID core.TaskID + Workspace string + Metadata map[string]string +} + +type ToolEvent struct { + Type string + CallID string + EventID string + Payload json.RawMessage + ErrorCode string + Timestamp time.Time +} + +type ExtensionTool interface { + Name() string + Description() string + Schema() json.RawMessage + Execute(ctx context.Context, args json.RawMessage, tctx ToolUseContext) (<-chan ToolEvent, error) +} + +type ToolProvider interface { + Tools(ctx context.Context) ([]ExtensionTool, error) +} + +type Manager interface { + Load(ctx context.Context, source string) (ExtensionInfo, error) + Unload(ctx context.Context, extensionID string) error + List(ctx context.Context) ([]ExtensionInfo, error) + Get(ctx context.Context, extensionID string) (ExtensionInfo, bool, error) +} + +type Resolver interface { + ResolveTools(ctx context.Context, extensionID string) ([]ExtensionTool, error) +} + diff --git a/docs/bytemind-architecture/policy/README.md b/docs/bytemind-architecture/policy/README.md new file mode 100644 index 00000000..2498b73a --- /dev/null +++ b/docs/bytemind-architecture/policy/README.md @@ -0,0 +1,29 @@ +# policy 模块设计 + +## 1. 模块定位 +`policy` 是权限与安全决策中心，输出 `allow/deny/ask` 及风险等级。 + +## 2. 职责边界 +做什么： +- 执行五层权限模型。 +- 按固定优先级处理规则冲突。 +- 进行路径、命令、敏感文件风险判定。 + +不做什么： +- 不执行业务动作。 +- 不承担主循环和任务调度。 + +## 3. 对外接口 +- `Engine`：策略决策主入口。 +- `Rule`：可组合原子规则。 +- `RuleSet`：规则注册与枚举。 +- `PathGuard`：路径访问安全判定。 +- `CommandGuard`：命令执行安全判定。 +- `SensitiveFileGuard`：敏感文件读取防护。 + +## 4. 决策优先级 +`explicit deny > explicit allow > risk rule > mode default > fallback ask` + +## 5. 测试策略 +- 冲突优先级与边界样例。 +- 高危命令、敏感文件、路径逃逸回归。 diff --git a/docs/bytemind-architecture/policy/interface.go b/docs/bytemind-architecture/policy/interface.go new file mode 100644 index 00000000..9ac1422f --- /dev/null +++ b/docs/bytemind-architecture/policy/interface.go @@ -0,0 +1,82 @@ +package policy + +import ( + "context" + + "bytemind/internal/core" +) + +type PermissionDecision struct { + Decision core.Decision + ReasonCode string + RiskLevel core.RiskLevel +} + +type SessionMode string + +const ( + ModeDefault SessionMode = "default" + ModeAcceptEdits SessionMode = "acceptEdits" + ModeBypassPermissions SessionMode = "bypassPermissions" + ModePlan SessionMode = "plan" +) + +type OperationKind string + +const ( + OpRead OperationKind = "read" + OpWrite OperationKind = "write" + OpExec OperationKind = "exec" + OpNet OperationKind = "network" + OpSpawn OperationKind = "spawn_agent" + OpCustom OperationKind = "custom" +) + +type PermissionRequest struct { + SessionID core.SessionID + TaskID core.TaskID + SessionMode SessionMode + ToolName string + Operation OperationKind + TargetPaths []string + Command string + Arguments []string + RequestedBy string + Metadata map[string]string +} + +type ErrorCode string + +const ( + ErrCodeInvalidRequest ErrorCode = "invalid_request" + ErrCodeRuleConflict ErrorCode = "rule_conflict" + ErrCodeRuleNotFound ErrorCode = "rule_not_found" +) + +type Engine interface { + Evaluate(ctx context.Context, req PermissionRequest) (PermissionDecision, error) +} + +type Rule interface { + Name() string + Priority() int + Evaluate(ctx context.Context, req PermissionRequest) (PermissionDecision, bool, error) +} + +type RuleSet interface { + Register(ctx context.Context, rule Rule) error + List(ctx context.Context) ([]Rule, error) +} + +type PathGuard interface { + CheckPaths(ctx context.Context, req PermissionRequest) (PermissionDecision, error) +} + +type CommandGuard interface { + CheckCommand(ctx context.Context, req PermissionRequest) (PermissionDecision, error) +} + +type SensitiveFileGuard interface { + CheckSensitiveRead(ctx context.Context, req PermissionRequest) (PermissionDecision, error) +} + diff --git a/docs/bytemind-architecture/provider/README.md b/docs/bytemind-architecture/provider/README.md new file mode 100644 index 00000000..f2a59bd1 --- /dev/null +++ b/docs/bytemind-architecture/provider/README.md @@ -0,0 +1,32 @@ +# provider 模块设计 + +## 1. 模块定位 +`provider` 是模型供应商抽象层，对上提供统一流式推理能力。 + +## 2. 职责边界 +做什么： +- 管理 provider 客户端注册与模型目录。 +- 路由选择 provider/model。 +- 执行流式模型调用并统一事件语义。 +- 归一化供应商错误（鉴权、限流、超时、不可用）。 + +不做什么： +- 不负责会话持久化。 +- 不负责权限决策。 +- 不负责工具编排。 + +## 3. 对外接口 +- `Client`：单个 provider 的统一调用契约（模型列表 + 流式推理）。 +- `Registry`：provider 注册与查询。 +- `Router`：按策略选择 provider 与模型。 +- `HealthChecker`：provider 健康探测。 + +## 4. 失败处理 +- 限流/超时：可重试错误。 +- 鉴权失败：不可重试错误。 +- 模型不可用：允许路由降级。 + +## 5. 测试策略 +- 契约测试：多 provider 事件语义一致。 +- 故障测试：401/429/超时/连接中断。 +- 压测：并发流式请求的首字节与吞吐。 diff --git a/docs/bytemind-architecture/provider/interface.go b/docs/bytemind-architecture/provider/interface.go new file mode 100644 index 00000000..f6e77d2c --- /dev/null +++ b/docs/bytemind-architecture/provider/interface.go @@ -0,0 +1,102 @@ +package provider + +import ( + "context" + "encoding/json" + "time" + + "bytemind/internal/core" +) + +type ProviderID string +type ModelID string + +type ErrorCode string + +const ( + ErrCodeUnauthorized ErrorCode = "unauthorized" + ErrCodeRateLimited ErrorCode = "rate_limited" + ErrCodeTimeout ErrorCode = "timeout" + ErrCodeUnavailable ErrorCode = "unavailable" + ErrCodeBadRequest ErrorCode = "bad_request" +) + +type Message struct { + Role core.Role + Content string + Name string + ToolCallID string +} + +type ToolSpec struct { + Name string + Description string + Schema json.RawMessage +} + +type Request struct { + SessionID core.SessionID + ModelID ModelID + Messages []Message + Tools []ToolSpec + MaxOutputTokens int + Temperature float64 + Metadata map[string]string +} + +type EventType string + +const ( + EventStart EventType = "start" + EventDelta EventType = "delta" + EventToolCall EventType = "tool_call" + EventUsage EventType = "usage" + EventResult EventType = "result" + EventError EventType = "error" +) + +type Usage struct { + InputTokens int + OutputTokens int + TotalTokens int + CostUSD float64 +} + +type Event struct { + Type EventType + EventID string + Payload json.RawMessage + Usage *Usage + ErrorCode string + Timestamp time.Time +} + +type ModelInfo struct { + ProviderID ProviderID + ModelID ModelID + DisplayName string + MaxInputTokens int + MaxOutputTokens int + SupportsTools bool +} + +type Client interface { + ProviderID() ProviderID + ListModels(ctx context.Context) ([]ModelInfo, error) + Stream(ctx context.Context, req Request) (<-chan Event, error) +} + +type Registry interface { + Register(ctx context.Context, client Client) error + Get(ctx context.Context, id ProviderID) (Client, bool) + List(ctx context.Context) ([]ProviderID, error) +} + +type Router interface { + Route(ctx context.Context, requestedModel ModelID, metadata map[string]string) (ProviderID, ModelID, error) +} + +type HealthChecker interface { + Check(ctx context.Context, id ProviderID) error +} + diff --git a/docs/bytemind-architecture/runtime/README.md b/docs/bytemind-architecture/runtime/README.md new file mode 100644 index 00000000..0b3c0de5 --- /dev/null +++ b/docs/bytemind-architecture/runtime/README.md @@ -0,0 +1,33 @@ +# runtime 模块设计 + +## 1. 模块定位 +`runtime` 是任务与并发执行内核，负责任务状态机、多代理调度和日志增量读取。 + +## 2. 职责边界 +做什么： +- 管理任务状态机：`pending -> running -> completed|failed|killed`。 +- 处理超时、取消传播、最大重试、终态回收。 +- 调度同步/异步子代理与 worktree 隔离执行。 +- 管理并发配额和资源争用。 + +不做什么： +- 不定义权限策略。 +- 不实现模型主循环。 +- 不处理存储落盘细节。 + +## 3. 对外接口 +- `TaskManager`：任务提交、查询、取消、重试、事件流订阅。 +- `Scheduler`：任务排队、暂停、恢复。 +- `LogReader`：任务日志按 offset 增量读取。 +- `SubAgentCoordinator`：子代理创建、等待、后台结果收集。 +- `QuotaManager`：并发配额申请与释放。 + +## 4. 多代理模式 +- 同步子代理：父任务阻塞等待。 +- 异步子代理：父任务继续执行，后续归并。 +- worktree 隔离：子任务独立工作区执行。 + +## 5. 测试策略 +- 状态机测试：合法/非法迁移。 +- 并发测试：配额、公平性、争用。 +- 失败测试：超时、取消、重试、崩溃恢复。 diff --git a/docs/bytemind-architecture/runtime/interface.go b/docs/bytemind-architecture/runtime/interface.go new file mode 100644 index 00000000..fd6e9fe6 --- /dev/null +++ b/docs/bytemind-architecture/runtime/interface.go @@ -0,0 +1,108 @@ +package runtime + +import ( + "context" + "time" + + "bytemind/internal/core" +) + +type ErrorCode string + +const ( + ErrCodeInvalidTransition ErrorCode = "invalid_transition" + ErrCodeTaskNotFound ErrorCode = "task_not_found" + ErrCodeTaskTimeout ErrorCode = "task_timeout" + ErrCodeTaskCanceled ErrorCode = "task_canceled" + ErrCodeRetryExhausted ErrorCode = "retry_exhausted" + ErrCodeQuotaExceeded ErrorCode = "quota_exceeded" +) + +type TaskSpec struct { + SessionID core.SessionID + Name string + Kind string + Input []byte + ParentTaskID core.TaskID + Timeout time.Duration + MaxRetries int + Background bool + IsolatedWorktree bool +} + +type Task struct { + ID core.TaskID + Spec TaskSpec + Status core.TaskStatus + Attempt int + CreatedAt time.Time + StartedAt *time.Time + FinishedAt *time.Time + ErrorCode string +} + +type TaskResult struct { + TaskID core.TaskID + Status core.TaskStatus + Output []byte + ErrorCode string + FinishedAt time.Time +} + +type TaskLogEntry struct { + TaskID core.TaskID + Offset int64 + Level string + Message string + EventID string + Timestamp time.Time +} + +type TaskEventType string + +const ( + TaskEventStatus TaskEventType = "status" + TaskEventLog TaskEventType = "log" + TaskEventResult TaskEventType = "result" + TaskEventError TaskEventType = "error" +) + +type TaskEvent struct { + Type TaskEventType + TaskID core.TaskID + Status core.TaskStatus + Log *TaskLogEntry + Result *TaskResult + ErrorCode string + Timestamp time.Time +} + +type TaskManager interface { + Submit(ctx context.Context, spec TaskSpec) (core.TaskID, error) + Get(ctx context.Context, id core.TaskID) (Task, error) + Cancel(ctx context.Context, id core.TaskID, reason string) error + Retry(ctx context.Context, id core.TaskID) (core.TaskID, error) + Stream(ctx context.Context, id core.TaskID) (<-chan TaskEvent, error) +} + +type Scheduler interface { + Enqueue(ctx context.Context, id core.TaskID) error + Pause(ctx context.Context, id core.TaskID) error + Resume(ctx context.Context, id core.TaskID) error +} + +type LogReader interface { + ReadIncrement(ctx context.Context, id core.TaskID, fromOffset int64, limit int) ([]TaskLogEntry, int64, error) +} + +type SubAgentCoordinator interface { + Spawn(ctx context.Context, parent core.TaskID, spec TaskSpec) (core.TaskID, error) + Wait(ctx context.Context, id core.TaskID) (TaskResult, error) + CollectBackground(ctx context.Context, parent core.TaskID) ([]TaskResult, error) +} + +type QuotaManager interface { + Acquire(ctx context.Context, key string, n int) error + Release(ctx context.Context, key string, n int) error +} + diff --git a/docs/bytemind-architecture/session/README.md b/docs/bytemind-architecture/session/README.md new file mode 100644 index 00000000..cd79c370 --- /dev/null +++ b/docs/bytemind-architecture/session/README.md @@ -0,0 +1,30 @@ +# session 模块设计 + +## 1. 模块定位 +`session` 负责会话生命周期、会话模式、会话快照与回放能力。 + +## 2. 职责边界 +做什么： +- 创建、读取、关闭会话。 +- 管理会话模式（default/acceptEdits/bypassPermissions/plan）。 +- 记录 turn 历史与会话元信息。 +- 提供快照与事件流读取。 + +不做什么： +- 不调用模型。 +- 不执行工具。 +- 不承担权限决策。 + +## 3. 对外接口 +- `Manager`：会话写操作入口（创建、模式切换、追加 turn、任务绑定、关闭）。 +- `Reader`：会话读操作入口（快照读取、增量读取、回放）。 + +## 4. 一致性策略 +- append-only 写入。 +- 会话级串行锁避免乱序。 +- 基于 `event_id` 去重，支持幂等回放。 + +## 5. 测试策略 +- 生命周期测试：创建/关闭幂等。 +- 并发测试：多 turn 追加顺序一致。 +- 回放测试：快照重建一致。 diff --git a/docs/bytemind-architecture/session/interface.go b/docs/bytemind-architecture/session/interface.go new file mode 100644 index 00000000..423e2d41 --- /dev/null +++ b/docs/bytemind-architecture/session/interface.go @@ -0,0 +1,108 @@ +package session + +import ( + "context" + "time" + + "bytemind/internal/core" +) + +type SessionMode string + +const ( + ModeDefault SessionMode = "default" + ModeAcceptEdits SessionMode = "acceptEdits" + ModeBypassPermissions SessionMode = "bypassPermissions" + ModePlan SessionMode = "plan" +) + +type SessionStatus string + +const ( + StatusActive SessionStatus = "active" + StatusClosing SessionStatus = "closing" + StatusClosed SessionStatus = "closed" +) + +type ErrorCode string + +const ( + ErrCodeSessionNotFound ErrorCode = "session_not_found" + ErrCodeSessionClosed ErrorCode = "session_closed" + ErrCodeInvalidMode ErrorCode = "invalid_mode" + ErrCodeReplayFailed ErrorCode = "replay_failed" +) + +type Message struct { + ID string + Role core.Role + Content string + CreatedAt time.Time +} + +type TurnRecord struct { + TurnID string + Input Message + Outputs []Message + StartedAt time.Time + EndedAt time.Time +} + +type UsageStat struct { + InputTokens int64 + OutputTokens int64 + TotalRequests int64 +} + +type SessionSnapshot struct { + ID core.SessionID + Mode SessionMode + Status SessionStatus + Messages []Message + Usage UsageStat + ActiveTasks []core.TaskID + CreatedAt time.Time + LastActiveAt time.Time +} + +type SessionEventType string + +const ( + SessionEventCreated SessionEventType = "created" + SessionEventMode SessionEventType = "mode_changed" + SessionEventTurn SessionEventType = "turn_appended" + SessionEventClosed SessionEventType = "closed" + SessionEventError SessionEventType = "error" +) + +type SessionEvent struct { + Type SessionEventType + SessionID core.SessionID + EventID string + Offset int64 + Payload []byte + ErrorCode string + Timestamp time.Time +} + +type CreateRequest struct { + Mode SessionMode + Metadata map[string]string +} + +type Manager interface { + Create(ctx context.Context, req CreateRequest) (SessionSnapshot, error) + Get(ctx context.Context, id core.SessionID) (SessionSnapshot, error) + SwitchMode(ctx context.Context, id core.SessionID, mode SessionMode) error + AppendTurn(ctx context.Context, id core.SessionID, turn TurnRecord) error + AttachTask(ctx context.Context, id core.SessionID, taskID core.TaskID) error + DetachTask(ctx context.Context, id core.SessionID, taskID core.TaskID) error + Close(ctx context.Context, id core.SessionID, reason string) error +} + +type Reader interface { + Snapshot(ctx context.Context, id core.SessionID) (SessionSnapshot, error) + ReadEvents(ctx context.Context, id core.SessionID, fromOffset int64, limit int) ([]SessionEvent, int64, error) + Replay(ctx context.Context, id core.SessionID, fromOffset int64) (<-chan SessionEvent, error) +} + diff --git a/docs/bytemind-architecture/storage/README.md b/docs/bytemind-architecture/storage/README.md new file mode 100644 index 00000000..e846fc9e --- /dev/null +++ b/docs/bytemind-architecture/storage/README.md @@ -0,0 +1,29 @@ +# storage 模块设计 + +## 1. 模块定位 +`storage` 是无数据库场景下的文件持久化与恢复层，提供会话与任务日志可靠读写和回放。 + +## 2. 职责边界 +做什么： +- 写入会话事件：`~/.bytemind/sessions/.jsonl`。 +- 写入任务日志：`~/.bytemind/tasks/.log`。 +- 支持增量读取、回放恢复、幂等去重。 + +不做什么： +- 不做业务决策与调度。 +- 不承担权限规则与工具编排。 + +## 3. 对外接口 +- `SessionStore`：会话事件追加与增量读取。 +- `TaskStore`：任务日志追加与增量读取。 +- `Locker`：会话/任务级锁控制。 +- `Deduplicator`：基于 `event_id` 去重。 +- `Replayer`：会话/任务事件流回放。 + +## 4. 一致性策略 +- append-only。 +- 单记录原子落盘（tmp+rename 或 fsync）。 +- 文件锁避免并发乱序。 + +## 5. 测试策略 +- 原子写测试、并发写测试、去重测试、回放一致性测试。 diff --git a/docs/bytemind-architecture/storage/interface.go b/docs/bytemind-architecture/storage/interface.go new file mode 100644 index 00000000..bd08f7e5 --- /dev/null +++ b/docs/bytemind-architecture/storage/interface.go @@ -0,0 +1,66 @@ +package storage + +import ( + "context" + "time" + + "bytemind/internal/core" +) + +type ErrorCode string + +const ( + ErrCodeNotFound ErrorCode = "not_found" + ErrCodeConflict ErrorCode = "conflict" + ErrCodeCorruptedRecord ErrorCode = "corrupted_record" + ErrCodeWriteFailed ErrorCode = "write_failed" + ErrCodeReadFailed ErrorCode = "read_failed" + ErrCodeLockTimeout ErrorCode = "lock_timeout" +) + +type SessionEvent struct { + SessionID core.SessionID + EventID string + Offset int64 + Type string + Payload []byte + CreatedAt time.Time +} + +type TaskLogRecord struct { + TaskID core.TaskID + EventID string + Offset int64 + Level string + Message string + Payload []byte + CreatedAt time.Time +} + +type SessionStore interface { + Append(ctx context.Context, event SessionEvent) error + ReadFrom(ctx context.Context, sessionID core.SessionID, offset int64, limit int) ([]SessionEvent, int64, error) +} + +type TaskStore interface { + AppendLog(ctx context.Context, record TaskLogRecord) error + ReadLogFrom(ctx context.Context, taskID core.TaskID, offset int64, limit int) ([]TaskLogRecord, int64, error) +} + +type Locker interface { + LockSession(ctx context.Context, sessionID core.SessionID) (UnlockFunc, error) + LockTask(ctx context.Context, taskID core.TaskID) (UnlockFunc, error) +} + +type UnlockFunc func() error + +type Deduplicator interface { + Seen(ctx context.Context, stream string, eventID string) (bool, error) + Mark(ctx context.Context, stream string, eventID string) error +} + +type Replayer interface { + ReplaySession(ctx context.Context, sessionID core.SessionID, fromOffset int64) (<-chan SessionEvent, error) + ReplayTask(ctx context.Context, taskID core.TaskID, fromOffset int64) (<-chan TaskLogRecord, error) +} + diff --git a/docs/bytemind-architecture/tools/README.md b/docs/bytemind-architecture/tools/README.md new file mode 100644 index 00000000..09b6c646 --- /dev/null +++ b/docs/bytemind-architecture/tools/README.md @@ -0,0 +1,32 @@ +# tools 模块设计 + +## 1. 模块定位 +`tools` 是统一工具执行平面，负责工具契约、参数校验、执行调度和标准事件流输出。 + +## 2. 职责边界 +做什么： +- 注册与发现工具。 +- 执行 schema 强校验。 +- 处理超时、取消、重试、并发控制。 +- 输出统一事件流：`start/chunk/result/error`。 + +不做什么： +- 不做权限决策（由 `policy` 负责）。 +- 不做主闭环编排（由 `agent` 负责）。 + +## 3. 对外接口 +- `Tool`：单工具统一执行契约。 +- `ToolMetadataProvider`：暴露工具副作用与幂等元信息。 +- `Registry`：工具注册、查询、枚举。 +- `Validator`：参数与 schema 校验。 +- `Executor`：工具执行调度与事件流封装。 + +## 4. 三层体系 +- 原子层：ReadFile/EditFile/WriteFile/Glob/Grep/Bash。 +- 组合层：TestRunner/GitWorkflow/TaskOutputReader。 +- 协作层：AgentTool/MCPTool/SkillTool/TeamTool。 + +## 5. 测试策略 +- Contract Test：schema 与事件流一致性。 +- 执行测试：超时/取消/重试语义。 +- 并发测试：配额限制与事件顺序。 diff --git a/docs/bytemind-architecture/tools/interface.go b/docs/bytemind-architecture/tools/interface.go new file mode 100644 index 00000000..768884e9 --- /dev/null +++ b/docs/bytemind-architecture/tools/interface.go @@ -0,0 +1,109 @@ +package tools + +import ( + "context" + "encoding/json" + "time" + + "bytemind/internal/core" +) + +type Tool interface { + Name() string + Description() string + Schema() json.RawMessage + Execute(ctx context.Context, args json.RawMessage, tctx ToolUseContext) (<-chan ToolEvent, error) +} + +type SideEffectLevel string + +const ( + SideEffectNone SideEffectLevel = "none" + SideEffectRead SideEffectLevel = "read" + SideEffectWrite SideEffectLevel = "write" + SideEffectExec SideEffectLevel = "exec" +) + +type IdempotencyLevel string + +const ( + IdempotencyStrong IdempotencyLevel = "strong" + IdempotencyWeak IdempotencyLevel = "weak" + IdempotencyUnknown IdempotencyLevel = "unknown" +) + +type ToolMetadata struct { + Layer string + SideEffectLevel SideEffectLevel + IdempotencyLevel IdempotencyLevel + DefaultTimeout time.Duration + MaxRetries int +} + +type ToolMetadataProvider interface { + Metadata() ToolMetadata +} + +type ToolUseContext struct { + SessionID core.SessionID + TaskID core.TaskID + Workspace string + Invoker string + Attempt int + Deadline time.Time + Metadata map[string]string +} + +type ToolEventType string + +const ( + ToolEventStart ToolEventType = "start" + ToolEventChunk ToolEventType = "chunk" + ToolEventResult ToolEventType = "result" + ToolEventError ToolEventType = "error" +) + +type ToolEvent struct { + Type ToolEventType + ToolName string + CallID string + EventID string + Offset int64 + Payload json.RawMessage + ErrorCode string + Timestamp time.Time +} + +type ErrorCode string + +const ( + ErrCodeInvalidArgument ErrorCode = "invalid_argument" + ErrCodeSchemaViolation ErrorCode = "schema_violation" + ErrCodeTimeout ErrorCode = "timeout" + ErrCodeCanceled ErrorCode = "canceled" + ErrCodeExecutionFailed ErrorCode = "execution_failed" + ErrCodeUnavailable ErrorCode = "unavailable" +) + +type ToolDescriptor struct { + Name string + Description string + Schema json.RawMessage + Metadata ToolMetadata +} + +type Registry interface { + Register(ctx context.Context, tool Tool) error + Unregister(ctx context.Context, name string) error + Get(ctx context.Context, name string) (Tool, bool) + List(ctx context.Context) ([]ToolDescriptor, error) +} + +type Validator interface { + Validate(ctx context.Context, schema json.RawMessage, args json.RawMessage) error +} + +type Executor interface { + Run(ctx context.Context, tool Tool, args json.RawMessage, tctx ToolUseContext) (<-chan ToolEvent, error) +} + From 8edf7ebcbc570dc4f80f50544c3e8c5657c863b6 Mon Sep 17 00:00:00 2001 From: LOUO <3129185766@qq.com> Date: Sun, 12 Apr 2026 01:41:22 +0800 Subject: [PATCH 02/10] =?UTF-8?q?=E5=8A=A0=E4=BA=86=E5=AE=A1=E8=AE=A1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/bytemind-architecture/README.md | 90 +++++++++++++++++++--------- 1 file changed, 61 insertions(+), 29 deletions(-) diff --git a/docs/bytemind-architecture/README.md b/docs/bytemind-architecture/README.md index 0e8d8cd8..64c7ff5d 100644 --- a/docs/bytemind-architecture/README.md +++ b/docs/bytemind-architecture/README.md @@ -1,19 +1,20 @@ # bytemind 总体架构设计文档（Go 生态） ## 1. 文档目标 -本文档定义 bytemind 的总体架构基线，用于技术评审、研发实施和演进治理。 +本文档定义 bytemind 的总体架构基线。 ## 2. 既定约束 - 单入口 TUI，无 Gateway。 -- 无长期 Memory，无跨会话语义记忆。 +- 无长期语义 Memory（不做跨会话记忆注入） - 会话与任务不依赖数据库。 ## 3. 架构目标 - 支持 coding agent 主闭环：理解任务、调用工具、修改代码、执行验证、返回结果。 -- 支持长任务与并发：任务系统、后台执行、多代理协作。 +- 支持长任务与并发：任务系统、后台执行、子代理协作。 - 支持扩展：MCP、Skills。 - 支持安全可控：权限分层、沙箱执行、风险拦截。 - 支持工程治理：可恢复、可追踪、可测试。 +- 支持最小审计闭环：关键决策与关键执行可追溯、可回放。 ## 4. 非目标 - 不做多入口统一接入层。 @@ -28,10 +29,37 @@ - 低耦合扩展：核心稳定，扩展通过标准契约接入。 - 可验证性：核心机制均有可执行测试与验收指标。 -## 6. 模块拆分（10 模块 + 1 共享内核） -- 业务模块（10）：`app/agent/session/context/provider/tools/runtime/policy/storage/extensions` -- 共享内核（1）：`core`（仅放跨模块公共类型与最小错误契约） +## 6. 总体架构图 +```mermaid +flowchart TB + U["TUI"] --> APP["app"] --> AG["agent"] + + subgraph S1["核心服务层"] + SE["session"] + CTX["context"] + PV["provider"] + PO["policy"] + RT["runtime"] + TO["tools"] + end + + subgraph S2["扩展与存储层"] + EX["extensions (MCP/Skills)"] + ST["storage (session/task/audit)"] + end + + CORE["core(shared types)"] + + AG --> SE + AG --> CTX + AG --> PV + AG --> PO + AG --> RT + AG --> TO + RT --> ST + TO --> EX +``` ## 7. 目录结构（Go） ```text bytemind/ @@ -52,6 +80,7 @@ bytemind/ ``` ## 8. 模块职责（做什么 / 不做什么） + ### core - 做：跨模块共享基础类型（SessionID/TaskID/Role/Decision/RiskLevel/TaskStatus）与通用错误契约。 - 不做：业务流程、模块专属请求结构、具体实现。 @@ -104,11 +133,6 @@ bytemind/ - `policy` 必须可独立测试，不依赖 `agent` 具体实现。 - 公共类型只允许放在 `core`，模块接口只放本模块特有结构。 -## 10. 模块交付标准 -每个模块固定两个文件： -- `README.md`：定位、边界、依赖、实现逻辑、测试策略。 -- `interface.go`：仅暴露接口与核心类型，不放实现。 - ## 11. 统一接口约束 - 接口按调用方视角定义，避免泄漏实现细节。 - 所有阻塞操作必须接收 `context.Context`。 @@ -117,6 +141,7 @@ bytemind/ - 接口层禁止引入具体 provider/tool 实现类型。 ## 12. 核心执行流程 + ### 12.1 单代理主闭环 1. 用户提交消息到 `agent`。 2. `agent` 读取 `session` 快照。 @@ -128,7 +153,7 @@ bytemind/ 8. `agent` 返回最终响应。 ### 12.2 自动压缩（无 Memory） -- warning `>= 85%`，critical `>= 95%`。 +- `warning >= 85%`，`critical >= 95%`。 - `tool_use` 与 `tool_result` 成对保留。 - `prompt_too_long` 触发一次 reactive compact + 重试。 @@ -143,10 +168,11 @@ bytemind/ - worktree 隔离代理：独立工作区执行，避免污染主工作区。 ## 13. Tools 体系 + ### 13.1 三层结构 -- 原子工具层：ReadFile/EditFile/WriteFile/Glob/Grep/Bash -- 组合工具层：TestRunner/GitWorkflow/TaskOutputReader -- 协作工具层：AgentTool/MCPTool/SkillTool/TeamTool +- 原子工具层：`ReadFile/EditFile/WriteFile/Glob/Grep/Bash` +- 组合工具层：`TestRunner/GitWorkflow/TaskOutputReader` +- 协作工具层：`AgentTool/MCPTool/SkillTool/TeamTool` ### 13.2 统一契约 ```go @@ -162,39 +188,50 @@ type Tool interface { - 参数 schema 强校验。 - 显式声明副作用级别与幂等级别。 - 支持超时、取消、重试语义。 -- 统一事件流：start/chunk/result/error。 +- 统一事件流：`start/chunk/result/error`。 - 每个工具必须有 mock/contract 单测。 ## 14. 权限与安全架构 + ### 14.1 五层权限模型 -- 会话模式层：default/acceptEdits/bypassPermissions(受控)/plan -- 工具白黑名单层：allowedTools/deniedTools +- 会话模式层：`default/acceptEdits/bypassPermissions(受控)/plan` +- 工具白黑名单层：`allowedTools/deniedTools` - 工具级策略层：读默认放行，写与命令默认询问 -- 风险层：low/medium/high -- 路径命令层：allowedWritePaths/deniedWritePaths/allowedCommands/deniedCommands +- 风险层：`low/medium/high` +- 路径命令层：`allowedWritePaths/deniedWritePaths/allowedCommands/deniedCommands` ### 14.2 决策优先级（固定） -`explicit deny > explicit allow > risk rule > mode default > fallback ask` +`hard_deny > explicit_deny > risk_rule > explicit_allow(仅低中风险可生效) > mode_default > fallback_ask` ### 14.3 安全基线 - Prompt Injection：系统指令优先，工具输出隔离。 -- 路径安全：resolve + realpath + allowlist。 +- 路径安全：`resolve + realpath + allowlist`。 - 命令安全：白名单 + 高危规则。 - 敏感文件保护：密钥/凭证默认拒绝读取。 - 沙箱策略：网络开关、路径白名单、资源限额。 ## 15. 文件存储与恢复（不落库） + ### 15.1 文件布局 - `~/.bytemind/sessions/.jsonl` - `~/.bytemind/tasks/.log` +- `~/.bytemind/audit/.jsonl` ### 15.2 一致性策略 - append-only 写入。 -- 单记录原子落盘（tmp+rename 或 fsync）。 +- 单记录原子落盘（`tmp+rename` 或 `fsync`）。 - 会话级文件锁，避免并发乱序。 - 事件携带 `event_id`，恢复时幂等去重。 +- 审计记录采用 append-only，与会话/任务日志一致的原子写策略。 +- 每条审计事件包含 `event_id/session_id/task_id/trace_id/timestamp`，启动恢复时按 `event_id` 幂等去重。 + +### 15.3 最小审计范围 +- 必记事件：`permission_decision`、`permission_ask_resolved`、`tool_execute_start`、`tool_execute_result`、`task_state_changed`。 +- 必记字段：`event_id`、`session_id`、`task_id`、`trace_id`、`actor`、`action`、`decision`、`reason_code`、`risk_level`、`result`、`latency_ms`。 +- 脱敏要求：命令参数和文件内容中的密钥/凭证必须脱敏后写入。 ## 16. 可观测性 + ### 16.1 指标 - 请求成功率、工具成功率、任务成功率。 - 首字节时延（模型/工具/存储分层）。 @@ -212,15 +249,10 @@ type Tool interface { - Failure Test：超时、取消、崩溃恢复、重试风暴。 - Multi-Agent Test：并发配额、资源争用、冲突归并。 - 安全回归：高危命令、敏感文件、路径逃逸。 +- Audit Replay Test：基于 `audit + session/task` 可还原关键执行链路，且重复回放结果一致。 ## 18. 主要风险与应对 - 工具误操作风险。应对：多层权限 + 高危确认 + 沙箱。 - 上下文膨胀风险。应对：预算器 + 自动压缩。 - 多代理复杂度风险。应对：依赖图调度 + 配额控制 + 终态约束。 - 文件一致性风险。应对：原子写 + 锁 + 幂等回放。 - -## 19. 去冗余收敛（本次调整） -- 删除独立审计子系统，避免与会话/任务日志重复写入。 -- 删除 `TurnRequest.HistoryOverride`，统一历史来源为 `session` 快照。 -- 抽取 `core` 共享内核，消除跨模块重复定义。 - From 7c52f66587dd849e282e10f229c708e7502c5d39 Mon Sep 17 00:00:00 2001 From: LOUO <3129185766@qq.com> Date: Sun, 12 Apr 2026 02:17:13 +0800 Subject: [PATCH 03/10] Update README with new transitions in architecture Added additional transitions to the architecture diagram. --- docs/bytemind-architecture/README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/bytemind-architecture/README.md b/docs/bytemind-architecture/README.md index 64c7ff5d..0596256b 100644 --- a/docs/bytemind-architecture/README.md +++ b/docs/bytemind-architecture/README.md @@ -58,6 +58,10 @@ flowchart TB AG --> TO RT --> ST TO --> EX + AG --> ST + RT --> ST + SE --> ST + ``` ## 7. 目录结构（Go） From 49c79aa0538d13dba8312c797cb2673abd91d9c6 Mon Sep 17 00:00:00 2001 From: LOUO <3129185766@qq.com> Date: Sun, 12 Apr 2026 03:34:04 +0800 Subject: [PATCH 04/10] Update README.md for architecture clarity --- docs/bytemind-architecture/README.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/docs/bytemind-architecture/README.md b/docs/bytemind-architecture/README.md index 0596256b..e61ef864 100644 --- a/docs/bytemind-architecture/README.md +++ b/docs/bytemind-architecture/README.md @@ -40,15 +40,17 @@ flowchart TB PV["provider"] PO["policy"] RT["runtime"] - TO["tools"] + TO["tools (SkillTool/MCPTool/...)"] end subgraph S2["扩展与存储层"] - EX["extensions (MCP/Skills)"] + EX["extensions/plugins"] + SK["skill registry"] + MCP["MCP client/server"] ST["storage (session/task/audit)"] end - CORE["core(shared types)"] + CORE["core (shared types)"] AG --> SE AG --> CTX @@ -56,12 +58,19 @@ flowchart TB AG --> PO AG --> RT AG --> TO - RT --> ST - TO --> EX + + EX --> SK + EX --> MCP + + TO --> SK + TO --> MCP + AG --> ST RT --> ST SE --> ST + CORE --- AG + CORE --- TO ``` ## 7. 目录结构（Go） From 309ced3a0e0c300fb27eda39eb7a69ed8f5385d2 Mon Sep 17 00:00:00 2001 From: LOUO <3129185766@qq.com> Date: Sun, 12 Apr 2026 10:31:22 +0800 Subject: [PATCH 05/10] Refactor README structure and update sections --- docs/bytemind-architecture/README.md | 68 +++++++++++++--------------- 1 file changed, 31 insertions(+), 37 deletions(-) diff --git a/docs/bytemind-architecture/README.md b/docs/bytemind-architecture/README.md index e61ef864..db3b9e74 100644 --- a/docs/bytemind-architecture/README.md +++ b/docs/bytemind-architecture/README.md @@ -4,9 +4,8 @@ 本文档定义 bytemind 的总体架构基线。 ## 2. 既定约束 -- 单入口 TUI，无 Gateway。 -- 无长期语义 Memory（不做跨会话记忆注入） -- 会话与任务不依赖数据库。 +- 单入口 TUI。 +- 会话与任务写入文件。 ## 3. 架构目标 - 支持 coding agent 主闭环：理解任务、调用工具、修改代码、执行验证、返回结果。 @@ -14,14 +13,9 @@ - 支持扩展：MCP、Skills。 - 支持安全可控：权限分层、沙箱执行、风险拦截。 - 支持工程治理：可恢复、可追踪、可测试。 -- 支持最小审计闭环：关键决策与关键执行可追溯、可回放。 +- 支持最小审计闭环：关键决策与关键执行可追溯、可回放 -## 4. 非目标 -- 不做多入口统一接入层。 -- 不做向量检索与长期知识记忆。 -- 不绑定中心化数据库部署。 - -## 5. 架构原则 +## 4. 架构原则 - Secure by Default：默认最小权限，高风险操作显式确认。 - 单一职责：原子能力优先，复杂行为通过编排组合。 - 显式状态：关键状态可持久化、可回放、可恢复。 @@ -29,7 +23,7 @@ - 低耦合扩展：核心稳定，扩展通过标准契约接入。 - 可验证性：核心机制均有可执行测试与验收指标。 -## 6. 总体架构图 +## 5. 总体架构图 ```mermaid flowchart TB U["TUI"] --> APP["app"] --> AG["agent"] @@ -73,7 +67,7 @@ flowchart TB CORE --- TO ``` -## 7. 目录结构（Go） +## 6. 目录结构（Go） ```text bytemind/ cmd/ @@ -92,7 +86,7 @@ bytemind/ extensions/ ``` -## 8. 模块职责（做什么 / 不做什么） +## 7. 模块职责（做什么 / 不做什么） ### core - 做：跨模块共享基础类型（SessionID/TaskID/Role/Decision/RiskLevel/TaskStatus）与通用错误契约。 @@ -138,7 +132,7 @@ bytemind/ - 做：MCP/Skills 通过统一契约接入 tools。 - 不做：主循环控制。 -## 9. 强制依赖约束 +## 8. 强制依赖约束 - 禁止循环依赖。 - `app` 只做装配，不承载业务逻辑。 - `agent` 仅通过接口访问 `session/context/provider/tools/runtime/policy/storage`。 @@ -146,16 +140,16 @@ bytemind/ - `policy` 必须可独立测试，不依赖 `agent` 具体实现。 - 公共类型只允许放在 `core`，模块接口只放本模块特有结构。 -## 11. 统一接口约束 +## 9. 统一接口约束 - 接口按调用方视角定义，避免泄漏实现细节。 - 所有阻塞操作必须接收 `context.Context`。 - 错误优先语义化（可判断、可测试）。 - 事件流统一使用 channel/迭代器风格。 - 接口层禁止引入具体 provider/tool 实现类型。 -## 12. 核心执行流程 +## 10. 核心执行流程 -### 12.1 单代理主闭环 +### 10.1 单代理主闭环 1. 用户提交消息到 `agent`。 2. `agent` 读取 `session` 快照。 3. `context` 构建上下文并计算预算。 @@ -165,29 +159,29 @@ bytemind/ 7. `storage` 写入会话/任务日志，`session` 更新状态。 8. `agent` 返回最终响应。 -### 12.2 自动压缩（无 Memory） +### 10.2 自动压缩（无 Memory） - `warning >= 85%`，`critical >= 95%`。 - `tool_use` 与 `tool_result` 成对保留。 - `prompt_too_long` 触发一次 reactive compact + 重试。 -### 12.3 任务系统 +### 10.3 任务系统 - 状态机：`pending -> running -> completed|failed|killed`。 - 机制：超时、取消传播、最大重试次数、终态回收。 - 输出：任务日志按 offset 增量读取。 -### 12.4 子代理 +### 10.4 子代理 - 同步子代理：父代理等待返回。 - 异步后台代理：父代理继续执行，后续归并。 - worktree 隔离代理：独立工作区执行，避免污染主工作区。 -## 13. Tools 体系 +## 11. Tools 体系 -### 13.1 三层结构 +### 11.1 三层结构 - 原子工具层：`ReadFile/EditFile/WriteFile/Glob/Grep/Bash` - 组合工具层：`TestRunner/GitWorkflow/TaskOutputReader` - 协作工具层：`AgentTool/MCPTool/SkillTool/TeamTool` -### 13.2 统一契约 +### 11.2 统一契约 ```go type Tool interface { Name() string @@ -197,40 +191,40 @@ type Tool interface { } ``` -### 13.3 强制规范 +### 11.3 强制规范 - 参数 schema 强校验。 - 显式声明副作用级别与幂等级别。 - 支持超时、取消、重试语义。 - 统一事件流：`start/chunk/result/error`。 - 每个工具必须有 mock/contract 单测。 -## 14. 权限与安全架构 +## 12. 权限与安全架构 -### 14.1 五层权限模型 +### 12.1 五层权限模型 - 会话模式层：`default/acceptEdits/bypassPermissions(受控)/plan` - 工具白黑名单层：`allowedTools/deniedTools` - 工具级策略层：读默认放行，写与命令默认询问 - 风险层：`low/medium/high` - 路径命令层：`allowedWritePaths/deniedWritePaths/allowedCommands/deniedCommands` -### 14.2 决策优先级（固定） +### 12.2 决策优先级（固定） `hard_deny > explicit_deny > risk_rule > explicit_allow(仅低中风险可生效) > mode_default > fallback_ask` -### 14.3 安全基线 +### 12.3 安全基线 - Prompt Injection：系统指令优先，工具输出隔离。 - 路径安全：`resolve + realpath + allowlist`。 - 命令安全：白名单 + 高危规则。 - 敏感文件保护：密钥/凭证默认拒绝读取。 - 沙箱策略：网络开关、路径白名单、资源限额。 -## 15. 文件存储与恢复（不落库） +## 13. 文件存储与恢复（不落库） -### 15.1 文件布局 +### 13.1 文件布局 - `~/.bytemind/sessions/.jsonl` - `~/.bytemind/tasks/.log` - `~/.bytemind/audit/.jsonl` -### 15.2 一致性策略 +### 13.2 一致性策略 - append-only 写入。 - 单记录原子落盘（`tmp+rename` 或 `fsync`）。 - 会话级文件锁，避免并发乱序。 @@ -238,24 +232,24 @@ type Tool interface { - 审计记录采用 append-only，与会话/任务日志一致的原子写策略。 - 每条审计事件包含 `event_id/session_id/task_id/trace_id/timestamp`，启动恢复时按 `event_id` 幂等去重。 -### 15.3 最小审计范围 +### 13.3 最小审计范围 - 必记事件：`permission_decision`、`permission_ask_resolved`、`tool_execute_start`、`tool_execute_result`、`task_state_changed`。 - 必记字段：`event_id`、`session_id`、`task_id`、`trace_id`、`actor`、`action`、`decision`、`reason_code`、`risk_level`、`result`、`latency_ms`。 - 脱敏要求：命令参数和文件内容中的密钥/凭证必须脱敏后写入。 -## 16. 可观测性 +## 14. 可观测性 -### 16.1 指标 +### 14.1 指标 - 请求成功率、工具成功率、任务成功率。 - 首字节时延（模型/工具/存储分层）。 - token 消耗与单位任务成本。 - 权限拒绝率与高危拦截率。 - 压缩触发率与恢复成功率。 -### 16.2 Trace +### 14.2 Trace 链路贯穿：`agent -> session -> context -> provider -> policy -> tools -> runtime -> storage` -## 17. 测试与治理要求（强制） +## 15. 测试与治理要求（强制） - Contract Test：工具 schema、事件流一致性。 - Replay Test：session/task 回放一致性。 - Policy Test：规则冲突、优先级、边界样例。 @@ -264,7 +258,7 @@ type Tool interface { - 安全回归：高危命令、敏感文件、路径逃逸。 - Audit Replay Test：基于 `audit + session/task` 可还原关键执行链路，且重复回放结果一致。 -## 18. 主要风险与应对 +## 16. 主要风险与应对 - 工具误操作风险。应对：多层权限 + 高危确认 + 沙箱。 - 上下文膨胀风险。应对：预算器 + 自动压缩。 - 多代理复杂度风险。应对：依赖图调度 + 配额控制 + 终态约束。 From 6845c2b0afacb6c60600739a837df080d8d054ac Mon Sep 17 00:00:00 2001 From: LOUO <3129185766@qq.com> Date: Sun, 12 Apr 2026 10:55:58 +0800 Subject: [PATCH 06/10] Rename Multi-Agent Test to Sub-Agent Test --- docs/bytemind-architecture/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/bytemind-architecture/README.md b/docs/bytemind-architecture/README.md index db3b9e74..40e8d234 100644 --- a/docs/bytemind-architecture/README.md +++ b/docs/bytemind-architecture/README.md @@ -254,12 +254,12 @@ type Tool interface { - Replay Test：session/task 回放一致性。 - Policy Test：规则冲突、优先级、边界样例。 - Failure Test：超时、取消、崩溃恢复、重试风暴。 -- Multi-Agent Test：并发配额、资源争用、冲突归并。 +- Sub-Agent Test：并发配额、资源争用、冲突归并。 - 安全回归：高危命令、敏感文件、路径逃逸。 - Audit Replay Test：基于 `audit + session/task` 可还原关键执行链路，且重复回放结果一致。 ## 16. 主要风险与应对 - 工具误操作风险。应对：多层权限 + 高危确认 + 沙箱。 - 上下文膨胀风险。应对：预算器 + 自动压缩。 -- 多代理复杂度风险。应对：依赖图调度 + 配额控制 + 终态约束。 +- 子代理复杂度风险。应对：依赖图调度 + 配额控制 + 终态约束。 - 文件一致性风险。应对：原子写 + 锁 + 幂等回放。 From 98288722fd294c5bea6b4dbe03a575ef47e40761 Mon Sep 17 00:00:00 2001 From: LOUO <3129185766@qq.com> Date: Mon, 13 Apr 2026 17:37:21 +0800 Subject: [PATCH 07/10] Update architecture documentation with session and runtime details --- docs/bytemind-architecture/README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/bytemind-architecture/README.md b/docs/bytemind-architecture/README.md index 40e8d234..fa8e51a8 100644 --- a/docs/bytemind-architecture/README.md +++ b/docs/bytemind-architecture/README.md @@ -103,6 +103,8 @@ bytemind/ ### session - 做：会话创建/关闭、模式切换、会话快照与事件回放。 - 不做：模型调用、任务调度、长期记忆。 +- 边界硬约束： +1. session 是“语义状态 owner”，storage 是“持久化正确性 owner”。 ### context - 做：上下文拼装、预算计算、压缩裁剪与不变量校验。 @@ -119,6 +121,10 @@ bytemind/ ### runtime - 做：任务状态机、超时/取消/重试、多代理调度与归并。 - 不做：权限规则定义。 +- 边界硬约束： +1. TaskStatus 只允许由 runtime 写入和迁移。 +2. agent 只能“发起任务/取消任务/查询任务”，不能直接改 TaskStatus。 + ### policy - 做：allow/deny/ask 决策、风险分级、路径/命令/敏感文件防护。 From 52dc00258c5cda6dac0c1b026cdd588fc85e4c46 Mon Sep 17 00:00:00 2001 From: Lwwww1 <3129185766@qq.com> Date: Mon, 13 Apr 2026 18:36:32 +0800 Subject: [PATCH 08/10] docs(architecture): align module contracts and add multimodal message parts --- docs/bytemind-architecture/agent/README.md | 4 +- docs/bytemind-architecture/agent/interface.go | 33 +++++++--- docs/bytemind-architecture/app/README.md | 1 + docs/bytemind-architecture/app/interface.go | 9 ++- docs/bytemind-architecture/context/README.md | 3 +- .../context/interface.go | 42 ++++++++----- docs/bytemind-architecture/core/README.md | 28 +++++---- docs/bytemind-architecture/core/interface.go | 43 ++++++++++++- .../extensions/README.md | 1 + .../extensions/interface.go | 16 +++-- docs/bytemind-architecture/policy/README.md | 14 ++++- .../bytemind-architecture/policy/interface.go | 60 +++++++++++++------ docs/bytemind-architecture/provider/README.md | 5 +- .../provider/interface.go | 17 ++++-- docs/bytemind-architecture/runtime/README.md | 1 + .../runtime/interface.go | 17 +++--- docs/bytemind-architecture/session/README.md | 5 +- .../session/interface.go | 31 ++++------ docs/bytemind-architecture/storage/README.md | 7 ++- .../storage/interface.go | 46 +++++++++----- docs/bytemind-architecture/tools/README.md | 2 + docs/bytemind-architecture/tools/interface.go | 6 +- 22 files changed, 269 insertions(+), 122 deletions(-) diff --git a/docs/bytemind-architecture/agent/README.md b/docs/bytemind-architecture/agent/README.md index 352d7db8..b725a06e 100644 --- a/docs/bytemind-architecture/agent/README.md +++ b/docs/bytemind-architecture/agent/README.md @@ -6,6 +6,7 @@ ## 2. 职责边界 做什么： - 接收用户输入并读取会话快照。 +- 支持多模态消息（text/image/file/audio）进入主闭环。 - 调用 `context` 构建模型请求并执行预算/压缩。 - 调用 `provider` 消费流式模型事件。 - 工具调用前走 `policy` 决策，再调度 `tools`。 @@ -24,6 +25,7 @@ - `PolicyGateway`：执行工具调用前权限决策。 - `ToolGateway`：执行工具并返回工具结果事件流。 - `RuntimeGateway`：创建和等待子代理任务。 +- `StorageGateway`：写入任务日志与审计事件。 ## 4. 主闭环 1. 读取 `session` 快照。 @@ -31,7 +33,7 @@ 3. 调用 `provider`。 4. 工具意图先过 `policy`。 5. 调用 `tools/runtime`。 -6. 写入 `session/storage` 并返回终态。 +6. 写入 `session/storage/audit` 并返回终态。 ## 5. 测试策略 - 主循环契约测试：事件顺序与终态一致性。 diff --git a/docs/bytemind-architecture/agent/interface.go b/docs/bytemind-architecture/agent/interface.go index 469c4c3e..4247b669 100644 --- a/docs/bytemind-architecture/agent/interface.go +++ b/docs/bytemind-architecture/agent/interface.go @@ -21,15 +21,16 @@ const ( type Message struct { Role core.Role - Content string - Name string // message source name, e.g. tool or sub-agent name + Parts []core.MessagePart + Name string ToolCallID string CreatedAt time.Time } type TurnRequest struct { SessionID core.SessionID - Input string + TraceID core.TraceID + InputParts []core.MessagePart MaxInputTokens int MaxOutputTokens int Metadata map[string]string @@ -49,11 +50,9 @@ const ( type TurnEvent struct { Type TurnEventType TurnID string - SessionID core.SessionID - TaskID core.TaskID + Meta core.EventMeta Payload json.RawMessage ErrorCode string - Timestamp time.Time } type ToolCall struct { @@ -65,6 +64,7 @@ type ToolCall struct { type PermissionDecision struct { Decision core.Decision ReasonCode string + RiskLevel core.RiskLevel } type Engine interface { @@ -73,7 +73,7 @@ type Engine interface { type SessionSnapshot struct { SessionID core.SessionID - Mode string + Mode core.SessionMode Messages []Message Metadata map[string]string } @@ -127,7 +127,9 @@ type RuntimeGateway interface { type SubAgentRequest struct { ParentSessionID core.SessionID - Mode string + ParentTaskID core.TaskID + TraceID core.TraceID + Mode core.SessionMode Prompt string Background bool } @@ -142,3 +144,18 @@ type SubAgentResult struct { ErrorCode string } +type AuditRecord struct { + Meta core.EventMeta + Actor string + Action string + Decision core.Decision + ReasonCode string + RiskLevel core.RiskLevel + Result string + LatencyMS int64 +} + +type StorageGateway interface { + WriteAudit(ctx context.Context, record AuditRecord) error + WriteTaskLog(ctx context.Context, taskID core.TaskID, payload json.RawMessage) error +} diff --git a/docs/bytemind-architecture/app/README.md b/docs/bytemind-architecture/app/README.md index 61b058fd..dee9af01 100644 --- a/docs/bytemind-architecture/app/README.md +++ b/docs/bytemind-architecture/app/README.md @@ -19,6 +19,7 @@ - `Bootstrapper`：根据配置构建模块集合 `ModuleSet`。 - `LifecycleManager`：按依赖拓扑启动和关闭模块。 - `Application`：应用进程入口（`Run/Shutdown`）。 +- 配置中的会话模式复用 `core.SessionMode`，避免跨模块常量漂移。 ## 4. 启停策略 - 启动顺序建议：`storage -> session -> policy -> tools/extensions -> context -> provider -> runtime -> agent`。 diff --git a/docs/bytemind-architecture/app/interface.go b/docs/bytemind-architecture/app/interface.go index efef8b11..061c3e4e 100644 --- a/docs/bytemind-architecture/app/interface.go +++ b/docs/bytemind-architecture/app/interface.go @@ -1,6 +1,10 @@ package app -import "context" +import ( + "context" + + "bytemind/internal/core" +) type ErrorCode string @@ -21,7 +25,7 @@ type ConfigSource struct { type Config struct { WorkspaceRoot string - SessionMode string + SessionMode core.SessionMode LogLevel string } @@ -61,4 +65,3 @@ type Application interface { Run(ctx context.Context) error Shutdown(ctx context.Context) error } - diff --git a/docs/bytemind-architecture/context/README.md b/docs/bytemind-architecture/context/README.md index 31cec654..f059fcba 100644 --- a/docs/bytemind-architecture/context/README.md +++ b/docs/bytemind-architecture/context/README.md @@ -5,7 +5,7 @@ ## 2. 职责边界 做什么： -- 组合系统指令、会话历史、用户输入、工具 schema、运行时提示。 +- 组合系统指令、会话历史、多模态用户输入、工具 schema、运行时提示。 - 计算 token 预算并输出预算计划。 - 按 warning/critical/reactive 策略执行压缩。 - 校验工具调用配对和系统约束不变量。 @@ -25,6 +25,7 @@ - warning：`>= 85%`。 - critical：`>= 95%`。 - `prompt_too_long` 时允许一次 reactive compact + 重试。 +- 压缩后必须保留 `tool_use` / `tool_result` 成对语义。 ## 5. 测试策略 - 预算测试：不同模型上限下稳定。 diff --git a/docs/bytemind-architecture/context/interface.go b/docs/bytemind-architecture/context/interface.go index 573744db..821221d4 100644 --- a/docs/bytemind-architecture/context/interface.go +++ b/docs/bytemind-architecture/context/interface.go @@ -8,6 +8,12 @@ import ( "bytemind/internal/core" ) +const ( + WarningBudgetThreshold = 0.85 + CriticalBudgetThreshold = 0.95 + ReactiveRetryLimit = 1 +) + type ErrorCode string const ( @@ -19,7 +25,7 @@ const ( type Message struct { Role core.Role - Content string + Parts []core.MessagePart Name string ToolCallID string CreatedAt time.Time @@ -43,9 +49,18 @@ type ProviderLimit struct { MaxOutputTokens int } +type CompactionMode string + +const ( + CompactionWarning CompactionMode = "warning" + CompactionCritical CompactionMode = "critical" + CompactionReactive CompactionMode = "reactive" +) + type BuildRequest struct { SessionID core.SessionID - UserInput string + TraceID core.TraceID + UserInputParts []core.MessagePart History []Message SystemPrompts []Message Tools []ToolDescriptor @@ -55,13 +70,14 @@ type BuildRequest struct { } type BuildResult struct { - Messages []Message - Tools []ToolDescriptor - InputTokens int - OutputTokens int - UsageRatio float64 - CompactApplied bool - CompactMode string + Messages []Message + Tools []ToolDescriptor + InputTokens int + OutputTokens int + UsageRatio float64 + CompactApplied bool + CompactMode CompactionMode + ReactiveRetryUse int } type BuildEventType string @@ -76,10 +92,9 @@ const ( type BuildEvent struct { Type BuildEventType - EventID string + Meta core.EventMeta Payload json.RawMessage ErrorCode string - Timestamp time.Time } type BudgetPlan struct { @@ -87,7 +102,7 @@ type BudgetPlan struct { MaxInputTokens int UsageRatio float64 NeedCompact bool - CompactMode string + CompactMode CompactionMode PreserveToolPairs bool } @@ -101,10 +116,9 @@ type Budgeter interface { } type Compactor interface { - Compact(ctx stdctx.Context, history []Message, mode string, preserveToolPairs bool) ([]Message, error) + Compact(ctx stdctx.Context, history []Message, mode CompactionMode, preserveToolPairs bool) ([]Message, error) } type InvariantChecker interface { Check(ctx stdctx.Context, messages []Message) error } - diff --git a/docs/bytemind-architecture/core/README.md b/docs/bytemind-architecture/core/README.md index d92d5f8e..8de3d8d0 100644 --- a/docs/bytemind-architecture/core/README.md +++ b/docs/bytemind-architecture/core/README.md @@ -1,21 +1,29 @@ # core 模块设计（共享内核） ## 1. 模块定位 -`core` 提供跨模块稳定共享的基础领域类型和通用错误契约，避免在各模块重复定义同义类型。 +`core` 提供跨模块稳定共享的领域类型与通用错误契约，统一所有模块的基础语义。 ## 2. 职责边界 做什么： -- 承载跨模块通用词汇：`SessionID`、`TaskID`、`Role`、`TaskStatus`、`Decision`、`RiskLevel`。 -- 提供最小通用错误契约：`SemanticError`。 +- 定义跨模块复用类型：`SessionID`、`TaskID`、`EventID`、`TraceID`、`Role`、`SessionMode`、`TaskStatus`、`Decision`、`RiskLevel`。 +- 定义多模态消息载荷：`MessagePart`（text/image/file/audio）。 +- 定义统一事件元信息：`EventMeta`。 +- 提供通用错误语义契约：`SemanticError`。 不做什么： -- 不承载业务流程接口。 -- 不承载模块专属请求/响应结构。 -- 不依赖任何业务模块。 +- 不定义模块专属业务请求/响应结构。 +- 不定义业务流程编排接口。 +- 不依赖任何业务模块实现。 ## 3. 对外接口（契约） -- `SemanticError`：统一错误抽象，约束 `Code()` 与 `Retryable()`，供上层判断与测试。 +- `EventMeta`：所有流式事件共享元字段（`event_id/trace_id/session_id/task_id/timestamp`）。 +- `SemanticError`：错误可判定、可测试的最小接口（`Code()`、`Retryable()`）。 -## 4. 设计约束 -- 仅当类型被两个及以上模块复用时，才允许进入 `core`。 -- 模块专属错误码、请求结构保留在模块内部。 +## 4. 架构对齐点 +- `SessionMode` 在 `core` 定义，避免 `session/policy/app` 重复声明。 +- `TaskStatus` 统一定义在 `core`，但迁移权仅属于 `runtime`。 +- 任何被两个及以上模块复用的基础类型必须下沉到 `core`。 + +## 5. 测试策略 +- 类型稳定性检查：常量值变更需要显式评审。 +- 错误语义检查：`SemanticError` 的 `Code/Retryable` 在上层可稳定断言。 diff --git a/docs/bytemind-architecture/core/interface.go b/docs/bytemind-architecture/core/interface.go index f9cea6c2..7ab04196 100644 --- a/docs/bytemind-architecture/core/interface.go +++ b/docs/bytemind-architecture/core/interface.go @@ -1,7 +1,11 @@ package core +import "time" + type SessionID string type TaskID string +type EventID string +type TraceID string type Role string @@ -12,6 +16,35 @@ const ( RoleTool Role = "tool" ) +type MessagePartType string + +const ( + PartText MessagePartType = "text" + PartImage MessagePartType = "image" + PartFile MessagePartType = "file" + PartAudio MessagePartType = "audio" +) + +// MessagePart is the shared multimodal payload unit. +// Text part uses Text; media part uses URI/MIMEType/Name. +type MessagePart struct { + Type MessagePartType + Text string + URI string + MIMEType string + Name string + Metadata map[string]string +} + +type SessionMode string + +const ( + SessionModeDefault SessionMode = "default" + SessionModeAcceptEdits SessionMode = "acceptEdits" + SessionModeBypassPermissions SessionMode = "bypassPermissions" + SessionModePlan SessionMode = "plan" +) + type TaskStatus string const ( @@ -38,10 +71,18 @@ const ( RiskHigh RiskLevel = "high" ) +// EventMeta is the shared envelope carried by every stream event. +type EventMeta struct { + EventID EventID + TraceID TraceID + SessionID SessionID + TaskID TaskID + Timestamp time.Time +} + // SemanticError is the shared minimum contract for testable errors. type SemanticError interface { error Code() string Retryable() bool } - diff --git a/docs/bytemind-architecture/extensions/README.md b/docs/bytemind-architecture/extensions/README.md index 37ea4104..e88238bd 100644 --- a/docs/bytemind-architecture/extensions/README.md +++ b/docs/bytemind-architecture/extensions/README.md @@ -9,6 +9,7 @@ - 校验扩展元数据、版本兼容与能力声明。 - 将扩展能力映射为标准工具并注册到 `tools`。 - 维护扩展健康状态和故障隔离。 +- 统一桥接 MCP 与 Skills 两类扩展。 不做什么： - 不直接读写 `agent` 内部状态。 diff --git a/docs/bytemind-architecture/extensions/interface.go b/docs/bytemind-architecture/extensions/interface.go index 82cf81e5..ae589fb6 100644 --- a/docs/bytemind-architecture/extensions/interface.go +++ b/docs/bytemind-architecture/extensions/interface.go @@ -34,13 +34,13 @@ const ( ErrCodeToolBridge ErrorCode = "tool_bridge_failed" ) -type ExtensionInfo struct { +type Manifest struct { ID string Name string Kind ExtensionKind Version string - Status ExtensionStatus Description string + Entry string UpdatedAt time.Time } @@ -50,6 +50,12 @@ type Capability struct { SideEffects []string } +type ExtensionInfo struct { + Manifest Manifest + Status ExtensionStatus + Capabilities []Capability +} + type ActivateOptions struct { WorkspaceRoot string ConfigPath string @@ -58,7 +64,6 @@ type ActivateOptions struct { type Extension interface { Info() ExtensionInfo - Capabilities() []Capability Activate(ctx context.Context, opts ActivateOptions) error Deactivate(ctx context.Context) error Health(ctx context.Context) (ExtensionStatus, error) @@ -67,6 +72,7 @@ type Extension interface { type ToolUseContext struct { SessionID core.SessionID TaskID core.TaskID + TraceID core.TraceID Workspace string Metadata map[string]string } @@ -74,10 +80,9 @@ type ToolUseContext struct { type ToolEvent struct { Type string CallID string - EventID string + Meta core.EventMeta Payload json.RawMessage ErrorCode string - Timestamp time.Time } type ExtensionTool interface { @@ -101,4 +106,3 @@ type Manager interface { type Resolver interface { ResolveTools(ctx context.Context, extensionID string) ([]ExtensionTool, error) } - diff --git a/docs/bytemind-architecture/policy/README.md b/docs/bytemind-architecture/policy/README.md index 2498b73a..d69e5711 100644 --- a/docs/bytemind-architecture/policy/README.md +++ b/docs/bytemind-architecture/policy/README.md @@ -15,15 +15,23 @@ ## 3. 对外接口 - `Engine`：策略决策主入口。 -- `Rule`：可组合原子规则。 +- `Rule`：按阶段归属的可组合原子规则。 - `RuleSet`：规则注册与枚举。 +- `PriorityResolver`：固定优先级决策归并器。 - `PathGuard`：路径访问安全判定。 - `CommandGuard`：命令执行安全判定。 - `SensitiveFileGuard`：敏感文件读取防护。 ## 4. 决策优先级 -`explicit deny > explicit allow > risk rule > mode default > fallback ask` +`hard_deny > explicit_deny > risk_rule > explicit_allow(仅低中风险可生效) > mode_default > fallback_ask` -## 5. 测试策略 +## 5. 五层权限模型 +- 会话模式层：`default/acceptEdits/bypassPermissions(受控)/plan`。 +- 工具白黑名单层：`allowedTools/deniedTools`。 +- 工具级策略层：读默认放行，写与命令默认询问。 +- 风险层：`low/medium/high`。 +- 路径命令层：`allowedWritePaths/deniedWritePaths/allowedCommands/deniedCommands`。 + +## 6. 测试策略 - 冲突优先级与边界样例。 - 高危命令、敏感文件、路径逃逸回归。 diff --git a/docs/bytemind-architecture/policy/interface.go b/docs/bytemind-architecture/policy/interface.go index 9ac1422f..9a9a6526 100644 --- a/docs/bytemind-architecture/policy/interface.go +++ b/docs/bytemind-architecture/policy/interface.go @@ -6,21 +6,6 @@ import ( "bytemind/internal/core" ) -type PermissionDecision struct { - Decision core.Decision - ReasonCode string - RiskLevel core.RiskLevel -} - -type SessionMode string - -const ( - ModeDefault SessionMode = "default" - ModeAcceptEdits SessionMode = "acceptEdits" - ModeBypassPermissions SessionMode = "bypassPermissions" - ModePlan SessionMode = "plan" -) - type OperationKind string const ( @@ -32,19 +17,54 @@ const ( OpCustom OperationKind = "custom" ) +type DecisionStage string + +const ( + StageHardDeny DecisionStage = "hard_deny" + StageExplicitDeny DecisionStage = "explicit_deny" + StageRiskRule DecisionStage = "risk_rule" + StageExplicitAllow DecisionStage = "explicit_allow" + StageModeDefault DecisionStage = "mode_default" + StageFallbackAsk DecisionStage = "fallback_ask" +) + +type ToolPolicy struct { + AllowedTools []string + DeniedTools []string +} + +type PathCommandPolicy struct { + AllowedWritePaths []string + DeniedWritePaths []string + AllowedCommands []string + DeniedCommands []string +} + type PermissionRequest struct { SessionID core.SessionID TaskID core.TaskID - SessionMode SessionMode + TraceID core.TraceID + SessionMode core.SessionMode ToolName string Operation OperationKind TargetPaths []string Command string Arguments []string RequestedBy string + ToolPolicy ToolPolicy + PathPolicy PathCommandPolicy Metadata map[string]string } +type PermissionDecision struct { + Decision core.Decision + ReasonCode string + RiskLevel core.RiskLevel + Stage DecisionStage + RequireUserConfirm bool + CanBypassWithSession bool +} + type ErrorCode string const ( @@ -59,7 +79,7 @@ type Engine interface { type Rule interface { Name() string - Priority() int + Stage() DecisionStage Evaluate(ctx context.Context, req PermissionRequest) (PermissionDecision, bool, error) } @@ -68,6 +88,11 @@ type RuleSet interface { List(ctx context.Context) ([]Rule, error) } +type PriorityResolver interface { + Order() []DecisionStage + Resolve(ctx context.Context, candidates []PermissionDecision) (PermissionDecision, error) +} + type PathGuard interface { CheckPaths(ctx context.Context, req PermissionRequest) (PermissionDecision, error) } @@ -79,4 +104,3 @@ type CommandGuard interface { type SensitiveFileGuard interface { CheckSensitiveRead(ctx context.Context, req PermissionRequest) (PermissionDecision, error) } - diff --git a/docs/bytemind-architecture/provider/README.md b/docs/bytemind-architecture/provider/README.md index f2a59bd1..bc992563 100644 --- a/docs/bytemind-architecture/provider/README.md +++ b/docs/bytemind-architecture/provider/README.md @@ -7,7 +7,7 @@ 做什么： - 管理 provider 客户端注册与模型目录。 - 路由选择 provider/model。 -- 执行流式模型调用并统一事件语义。 +- 执行流式模型调用并统一事件语义（支持多模态消息）。 - 归一化供应商错误（鉴权、限流、超时、不可用）。 不做什么： @@ -18,13 +18,14 @@ ## 3. 对外接口 - `Client`：单个 provider 的统一调用契约（模型列表 + 流式推理）。 - `Registry`：provider 注册与查询。 -- `Router`：按策略选择 provider 与模型。 +- `Router`：按策略选择 provider/model，并提供降级候选。 - `HealthChecker`：provider 健康探测。 ## 4. 失败处理 - 限流/超时：可重试错误。 - 鉴权失败：不可重试错误。 - 模型不可用：允许路由降级。 +- 统一流式事件必须携带 `event_id/trace_id` 元信息，便于链路追踪与回放。 ## 5. 测试策略 - 契约测试：多 provider 事件语义一致。 diff --git a/docs/bytemind-architecture/provider/interface.go b/docs/bytemind-architecture/provider/interface.go index f6e77d2c..5f6caede 100644 --- a/docs/bytemind-architecture/provider/interface.go +++ b/docs/bytemind-architecture/provider/interface.go @@ -23,7 +23,7 @@ const ( type Message struct { Role core.Role - Content string + Parts []core.MessagePart Name string ToolCallID string } @@ -36,6 +36,7 @@ type ToolSpec struct { type Request struct { SessionID core.SessionID + TraceID core.TraceID ModelID ModelID Messages []Message Tools []ToolSpec @@ -64,11 +65,11 @@ type Usage struct { type Event struct { Type EventType - EventID string + Meta core.EventMeta Payload json.RawMessage Usage *Usage ErrorCode string - Timestamp time.Time + Retryable bool } type ModelInfo struct { @@ -78,6 +79,13 @@ type ModelInfo struct { MaxInputTokens int MaxOutputTokens int SupportsTools bool + UpdatedAt time.Time +} + +type RouteResult struct { + ProviderID ProviderID + ModelID ModelID + Fallbacks []ModelID } type Client interface { @@ -93,10 +101,9 @@ type Registry interface { } type Router interface { - Route(ctx context.Context, requestedModel ModelID, metadata map[string]string) (ProviderID, ModelID, error) + Route(ctx context.Context, requestedModel ModelID, metadata map[string]string) (RouteResult, error) } type HealthChecker interface { Check(ctx context.Context, id ProviderID) error } - diff --git a/docs/bytemind-architecture/runtime/README.md b/docs/bytemind-architecture/runtime/README.md index 0b3c0de5..e2848379 100644 --- a/docs/bytemind-architecture/runtime/README.md +++ b/docs/bytemind-architecture/runtime/README.md @@ -9,6 +9,7 @@ - 处理超时、取消传播、最大重试、终态回收。 - 调度同步/异步子代理与 worktree 隔离执行。 - 管理并发配额和资源争用。 +- 作为 `TaskStatus` 唯一写入与迁移 owner。 不做什么： - 不定义权限策略。 diff --git a/docs/bytemind-architecture/runtime/interface.go b/docs/bytemind-architecture/runtime/interface.go index fd6e9fe6..43ac06fa 100644 --- a/docs/bytemind-architecture/runtime/interface.go +++ b/docs/bytemind-architecture/runtime/interface.go @@ -20,6 +20,7 @@ const ( type TaskSpec struct { SessionID core.SessionID + TraceID core.TraceID Name string Kind string Input []byte @@ -28,6 +29,7 @@ type TaskSpec struct { MaxRetries int Background bool IsolatedWorktree bool + Metadata map[string]string } type Task struct { @@ -50,12 +52,11 @@ type TaskResult struct { } type TaskLogEntry struct { - TaskID core.TaskID - Offset int64 - Level string - Message string - EventID string - Timestamp time.Time + TaskID core.TaskID + Offset int64 + Level string + Message string + Meta core.EventMeta } type TaskEventType string @@ -73,8 +74,8 @@ type TaskEvent struct { Status core.TaskStatus Log *TaskLogEntry Result *TaskResult + Meta core.EventMeta ErrorCode string - Timestamp time.Time } type TaskManager interface { @@ -82,6 +83,7 @@ type TaskManager interface { Get(ctx context.Context, id core.TaskID) (Task, error) Cancel(ctx context.Context, id core.TaskID, reason string) error Retry(ctx context.Context, id core.TaskID) (core.TaskID, error) + Wait(ctx context.Context, id core.TaskID) (TaskResult, error) Stream(ctx context.Context, id core.TaskID) (<-chan TaskEvent, error) } @@ -105,4 +107,3 @@ type QuotaManager interface { Acquire(ctx context.Context, key string, n int) error Release(ctx context.Context, key string, n int) error } - diff --git a/docs/bytemind-architecture/session/README.md b/docs/bytemind-architecture/session/README.md index cd79c370..52edc14e 100644 --- a/docs/bytemind-architecture/session/README.md +++ b/docs/bytemind-architecture/session/README.md @@ -7,13 +7,15 @@ 做什么： - 创建、读取、关闭会话。 - 管理会话模式（default/acceptEdits/bypassPermissions/plan）。 -- 记录 turn 历史与会话元信息。 +- 记录多模态 turn 历史与会话元信息。 - 提供快照与事件流读取。 +- 维护“语义状态 owner”职责。 不做什么： - 不调用模型。 - 不执行工具。 - 不承担权限决策。 +- 不承担持久化原子性与文件锁正确性（由 `storage` 负责）。 ## 3. 对外接口 - `Manager`：会话写操作入口（创建、模式切换、追加 turn、任务绑定、关闭）。 @@ -23,6 +25,7 @@ - append-only 写入。 - 会话级串行锁避免乱序。 - 基于 `event_id` 去重，支持幂等回放。 +- 会话模式统一复用 `core.SessionMode`，避免多处定义漂移。 ## 5. 测试策略 - 生命周期测试：创建/关闭幂等。 diff --git a/docs/bytemind-architecture/session/interface.go b/docs/bytemind-architecture/session/interface.go index 423e2d41..253dc0e4 100644 --- a/docs/bytemind-architecture/session/interface.go +++ b/docs/bytemind-architecture/session/interface.go @@ -7,15 +7,6 @@ import ( "bytemind/internal/core" ) -type SessionMode string - -const ( - ModeDefault SessionMode = "default" - ModeAcceptEdits SessionMode = "acceptEdits" - ModeBypassPermissions SessionMode = "bypassPermissions" - ModePlan SessionMode = "plan" -) - type SessionStatus string const ( @@ -34,10 +25,12 @@ const ( ) type Message struct { - ID string - Role core.Role - Content string - CreatedAt time.Time + ID string + Role core.Role + Parts []core.MessagePart + Name string + ToolCallID string + CreatedAt time.Time } type TurnRecord struct { @@ -56,11 +49,12 @@ type UsageStat struct { type SessionSnapshot struct { ID core.SessionID - Mode SessionMode + Mode core.SessionMode Status SessionStatus Messages []Message Usage UsageStat ActiveTasks []core.TaskID + Metadata map[string]string CreatedAt time.Time LastActiveAt time.Time } @@ -77,23 +71,21 @@ const ( type SessionEvent struct { Type SessionEventType - SessionID core.SessionID - EventID string + Meta core.EventMeta Offset int64 Payload []byte ErrorCode string - Timestamp time.Time } type CreateRequest struct { - Mode SessionMode + Mode core.SessionMode Metadata map[string]string } type Manager interface { Create(ctx context.Context, req CreateRequest) (SessionSnapshot, error) Get(ctx context.Context, id core.SessionID) (SessionSnapshot, error) - SwitchMode(ctx context.Context, id core.SessionID, mode SessionMode) error + SwitchMode(ctx context.Context, id core.SessionID, mode core.SessionMode) error AppendTurn(ctx context.Context, id core.SessionID, turn TurnRecord) error AttachTask(ctx context.Context, id core.SessionID, taskID core.TaskID) error DetachTask(ctx context.Context, id core.SessionID, taskID core.TaskID) error @@ -105,4 +97,3 @@ type Reader interface { ReadEvents(ctx context.Context, id core.SessionID, fromOffset int64, limit int) ([]SessionEvent, int64, error) Replay(ctx context.Context, id core.SessionID, fromOffset int64) (<-chan SessionEvent, error) } - diff --git a/docs/bytemind-architecture/storage/README.md b/docs/bytemind-architecture/storage/README.md index e846fc9e..80d0245c 100644 --- a/docs/bytemind-architecture/storage/README.md +++ b/docs/bytemind-architecture/storage/README.md @@ -7,6 +7,7 @@ 做什么： - 写入会话事件：`~/.bytemind/sessions/.jsonl`。 - 写入任务日志：`~/.bytemind/tasks/.log`。 +- 写入审计日志：`~/.bytemind/audit/.jsonl`。 - 支持增量读取、回放恢复、幂等去重。 不做什么： @@ -16,14 +17,18 @@ ## 3. 对外接口 - `SessionStore`：会话事件追加与增量读取。 - `TaskStore`：任务日志追加与增量读取。 +- `AuditStore`：审计事件追加与按日增量读取。 - `Locker`：会话/任务级锁控制。 - `Deduplicator`：基于 `event_id` 去重。 -- `Replayer`：会话/任务事件流回放。 +- `Replayer`：会话/任务/审计事件流回放。 ## 4. 一致性策略 - append-only。 - 单记录原子落盘（tmp+rename 或 fsync）。 - 文件锁避免并发乱序。 +- 审计事件与会话/任务事件统一遵循原子写入语义。 +- 审计最小字段覆盖：`event_id/session_id/task_id/trace_id/actor/action/decision/reason_code/risk_level/result/latency_ms`。 ## 5. 测试策略 - 原子写测试、并发写测试、去重测试、回放一致性测试。 +- 审计回放测试：基于 `audit + session/task` 可还原关键执行链路。 diff --git a/docs/bytemind-architecture/storage/interface.go b/docs/bytemind-architecture/storage/interface.go index bd08f7e5..51c5c61c 100644 --- a/docs/bytemind-architecture/storage/interface.go +++ b/docs/bytemind-architecture/storage/interface.go @@ -19,22 +19,30 @@ const ( ) type SessionEvent struct { - SessionID core.SessionID - EventID string - Offset int64 - Type string - Payload []byte - CreatedAt time.Time + Meta core.EventMeta + Offset int64 + Type string + Payload []byte } type TaskLogRecord struct { - TaskID core.TaskID - EventID string - Offset int64 - Level string - Message string - Payload []byte - CreatedAt time.Time + Meta core.EventMeta + Offset int64 + Level string + Message string + Payload []byte +} + +type AuditEvent struct { + Meta core.EventMeta + Actor string + Action string + Decision core.Decision + ReasonCode string + RiskLevel core.RiskLevel + Result string + LatencyMS int64 + Payload []byte } type SessionStore interface { @@ -47,20 +55,26 @@ type TaskStore interface { ReadLogFrom(ctx context.Context, taskID core.TaskID, offset int64, limit int) ([]TaskLogRecord, int64, error) } +type AuditStore interface { + Append(ctx context.Context, event AuditEvent) error + ReadFrom(ctx context.Context, day time.Time, offset int64, limit int) ([]AuditEvent, int64, error) +} + type Locker interface { LockSession(ctx context.Context, sessionID core.SessionID) (UnlockFunc, error) LockTask(ctx context.Context, taskID core.TaskID) (UnlockFunc, error) + LockAuditDay(ctx context.Context, day time.Time) (UnlockFunc, error) } type UnlockFunc func() error type Deduplicator interface { - Seen(ctx context.Context, stream string, eventID string) (bool, error) - Mark(ctx context.Context, stream string, eventID string) error + Seen(ctx context.Context, stream string, eventID core.EventID) (bool, error) + Mark(ctx context.Context, stream string, eventID core.EventID) error } type Replayer interface { ReplaySession(ctx context.Context, sessionID core.SessionID, fromOffset int64) (<-chan SessionEvent, error) ReplayTask(ctx context.Context, taskID core.TaskID, fromOffset int64) (<-chan TaskLogRecord, error) + ReplayAudit(ctx context.Context, day time.Time, fromOffset int64) (<-chan AuditEvent, error) } - diff --git a/docs/bytemind-architecture/tools/README.md b/docs/bytemind-architecture/tools/README.md index 09b6c646..fc8d96db 100644 --- a/docs/bytemind-architecture/tools/README.md +++ b/docs/bytemind-architecture/tools/README.md @@ -20,11 +20,13 @@ - `Registry`：工具注册、查询、枚举。 - `Validator`：参数与 schema 校验。 - `Executor`：工具执行调度与事件流封装。 +- 统一事件元字段复用 `core.EventMeta`，支持 trace 贯通。 ## 4. 三层体系 - 原子层：ReadFile/EditFile/WriteFile/Glob/Grep/Bash。 - 组合层：TestRunner/GitWorkflow/TaskOutputReader。 - 协作层：AgentTool/MCPTool/SkillTool/TeamTool。 +- 该分层用于架构分类与文档沟通，不作为 `Tool` 运行时必填字段。 ## 5. 测试策略 - Contract Test：schema 与事件流一致性。 diff --git a/docs/bytemind-architecture/tools/interface.go b/docs/bytemind-architecture/tools/interface.go index 768884e9..95972208 100644 --- a/docs/bytemind-architecture/tools/interface.go +++ b/docs/bytemind-architecture/tools/interface.go @@ -33,7 +33,6 @@ const ( ) type ToolMetadata struct { - Layer string SideEffectLevel SideEffectLevel IdempotencyLevel IdempotencyLevel DefaultTimeout time.Duration @@ -47,6 +46,7 @@ type ToolMetadataProvider interface { type ToolUseContext struct { SessionID core.SessionID TaskID core.TaskID + TraceID core.TraceID Workspace string Invoker string Attempt int @@ -67,11 +67,10 @@ type ToolEvent struct { Type ToolEventType ToolName string CallID string - EventID string + Meta core.EventMeta Offset int64 Payload json.RawMessage ErrorCode string - Timestamp time.Time } type ErrorCode string @@ -106,4 +105,3 @@ type Validator interface { type Executor interface { Run(ctx context.Context, tool Tool, args json.RawMessage, tctx ToolUseContext) (<-chan ToolEvent, error) } - From f3cb66184d7a97c525aab57ae3363e771070e5a0 Mon Sep 17 00:00:00 2001 From: Lwwww1 <3129185766@qq.com> Date: Mon, 13 Apr 2026 18:41:59 +0800 Subject: [PATCH 09/10] fix(ci): ignore architecture interface docs during build --- docs/bytemind-architecture/agent/interface.go | 2 ++ docs/bytemind-architecture/app/interface.go | 2 ++ docs/bytemind-architecture/context/interface.go | 2 ++ docs/bytemind-architecture/core/interface.go | 2 ++ docs/bytemind-architecture/extensions/interface.go | 2 ++ docs/bytemind-architecture/policy/interface.go | 2 ++ docs/bytemind-architecture/provider/interface.go | 2 ++ docs/bytemind-architecture/runtime/interface.go | 2 ++ docs/bytemind-architecture/session/interface.go | 2 ++ docs/bytemind-architecture/storage/interface.go | 2 ++ docs/bytemind-architecture/tools/interface.go | 2 ++ 11 files changed, 22 insertions(+) diff --git a/docs/bytemind-architecture/agent/interface.go b/docs/bytemind-architecture/agent/interface.go index 4247b669..a03df5ad 100644 --- a/docs/bytemind-architecture/agent/interface.go +++ b/docs/bytemind-architecture/agent/interface.go @@ -1,3 +1,5 @@ +//go:build ignore + package agent import ( diff --git a/docs/bytemind-architecture/app/interface.go b/docs/bytemind-architecture/app/interface.go index 061c3e4e..eef9fe31 100644 --- a/docs/bytemind-architecture/app/interface.go +++ b/docs/bytemind-architecture/app/interface.go @@ -1,3 +1,5 @@ +//go:build ignore + package app import ( diff --git a/docs/bytemind-architecture/context/interface.go b/docs/bytemind-architecture/context/interface.go index 821221d4..f290473d 100644 --- a/docs/bytemind-architecture/context/interface.go +++ b/docs/bytemind-architecture/context/interface.go @@ -1,3 +1,5 @@ +//go:build ignore + package context import ( diff --git a/docs/bytemind-architecture/core/interface.go b/docs/bytemind-architecture/core/interface.go index 7ab04196..6b8afdb5 100644 --- a/docs/bytemind-architecture/core/interface.go +++ b/docs/bytemind-architecture/core/interface.go @@ -1,3 +1,5 @@ +//go:build ignore + package core import "time" diff --git a/docs/bytemind-architecture/extensions/interface.go b/docs/bytemind-architecture/extensions/interface.go index ae589fb6..400f8acc 100644 --- a/docs/bytemind-architecture/extensions/interface.go +++ b/docs/bytemind-architecture/extensions/interface.go @@ -1,3 +1,5 @@ +//go:build ignore + package extensions import ( diff --git a/docs/bytemind-architecture/policy/interface.go b/docs/bytemind-architecture/policy/interface.go index 9a9a6526..871f6f66 100644 --- a/docs/bytemind-architecture/policy/interface.go +++ b/docs/bytemind-architecture/policy/interface.go @@ -1,3 +1,5 @@ +//go:build ignore + package policy import ( diff --git a/docs/bytemind-architecture/provider/interface.go b/docs/bytemind-architecture/provider/interface.go index 5f6caede..1bb49568 100644 --- a/docs/bytemind-architecture/provider/interface.go +++ b/docs/bytemind-architecture/provider/interface.go @@ -1,3 +1,5 @@ +//go:build ignore + package provider import ( diff --git a/docs/bytemind-architecture/runtime/interface.go b/docs/bytemind-architecture/runtime/interface.go index 43ac06fa..7cbc0e32 100644 --- a/docs/bytemind-architecture/runtime/interface.go +++ b/docs/bytemind-architecture/runtime/interface.go @@ -1,3 +1,5 @@ +//go:build ignore + package runtime import ( diff --git a/docs/bytemind-architecture/session/interface.go b/docs/bytemind-architecture/session/interface.go index 253dc0e4..fa75096b 100644 --- a/docs/bytemind-architecture/session/interface.go +++ b/docs/bytemind-architecture/session/interface.go @@ -1,3 +1,5 @@ +//go:build ignore + package session import ( diff --git a/docs/bytemind-architecture/storage/interface.go b/docs/bytemind-architecture/storage/interface.go index 51c5c61c..a50a86fd 100644 --- a/docs/bytemind-architecture/storage/interface.go +++ b/docs/bytemind-architecture/storage/interface.go @@ -1,3 +1,5 @@ +//go:build ignore + package storage import ( diff --git a/docs/bytemind-architecture/tools/interface.go b/docs/bytemind-architecture/tools/interface.go index 95972208..3e90b275 100644 --- a/docs/bytemind-architecture/tools/interface.go +++ b/docs/bytemind-architecture/tools/interface.go @@ -1,3 +1,5 @@ +//go:build ignore + package tools import ( From 7d7df9632144cc99e9a0964d96c4d73bcc60ef0b Mon Sep 17 00:00:00 2001 From: LOUO <3129185766@qq.com> Date: Mon, 13 Apr 2026 18:44:44 +0800 Subject: [PATCH 10/10] Revise architecture diagram and user flow Updated the architecture diagram and added user interactions. --- docs/bytemind-architecture/README.md | 58 +++++++++++++++------------- 1 file changed, 31 insertions(+), 27 deletions(-) diff --git a/docs/bytemind-architecture/README.md b/docs/bytemind-architecture/README.md index fa8e51a8..62ad2290 100644 --- a/docs/bytemind-architecture/README.md +++ b/docs/bytemind-architecture/README.md @@ -26,45 +26,49 @@ ## 5. 总体架构图 ```mermaid flowchart TB - U["TUI"] --> APP["app"] --> AG["agent"] + U["用户"] - subgraph S1["核心服务层"] + subgraph ORCH["主编排"] + AG["agent"] + end + + subgraph STATE["会话与存储"] SE["session"] + ST["storage"] + end + + subgraph MODEL["上下文与模型"] CTX["context"] PV["provider"] - PO["policy"] - RT["runtime"] - TO["tools (SkillTool/MCPTool/...)"] end - subgraph S2["扩展与存储层"] - EX["extensions/plugins"] - SK["skill registry"] - MCP["MCP client/server"] - ST["storage (session/task/audit)"] + subgraph EXEC["安全与执行"] + PO["policy"] + TO["tools"] + RT["runtime"] end - CORE["core (shared types)"] - - AG --> SE - AG --> CTX - AG --> PV - AG --> PO - AG --> RT - AG --> TO + U -->|提交请求| AG + AG -->|输出最终回复| U - EX --> SK - EX --> MCP + AG -->|读取快照| SE + AG -->|写回会话| SE + SE <--> |会话日志读写| ST + AG -->|审计事件写入| ST - TO --> SK - TO --> MCP + AG -->|构建上下文| CTX + CTX -->|上下文结果| AG + AG -->|发送模型请求| PV + PV -->|返回流式事件| AG - AG --> ST - RT --> ST - SE --> ST + AG -->|发起权限评估| PO + PO -->|返回决策| AG + AG -->|执行工具| TO + TO -->|返回工具事件| AG - CORE --- AG - CORE --- TO + AG -->|提交任务/子代理| RT + RT -->|返回任务结果| AG + RT -->|任务日志写入| ST ``` ## 6. 目录结构（Go）