架构设计

[Lwwww1]

No description provided.

[fennoai]

Found 3 noteworthy issues in this PR:

1. New .go interface docs under docs/bytemind-architecture/*/interface.go currently do not compile.
2. Policy decision-priority documentation is internally inconsistent.
3. Storage/audit ownership is inconsistent between overview and module docs.

Please address these to keep the architecture docs executable/consistent.

[fennoai]

This priority order conflicts with the top-level architecture doc (docs/bytemind-architecture/README.md:204). The two versions disagree on both hard_deny existence and the ordering of risk_rule vs explicit_allow, which changes enforcement semantics. Please define one canonical order and reuse it everywhere.

[Nomikfk1215]

@xgopilot 我看了 docs/bytemind-architecture/README.md 这个：
1.子代理这部分：异步后台子代理和worktree部分是不是很难做
2.tools五层权限：五层权限是全做吗 还有这个bypasspermission
3.每个工具都统一事件流，是不是太复杂了
4.每条记录都强一直落盘是不是有问题

[fennoai]

结论（针对你提的 4 个点）

1. 子代理（异步后台 + worktree）
   是难点，尤其是“异步归并 + 隔离工作区”这两块。当前文档把它放在 runtime（docs/bytemind-architecture/README.md:172、docs/bytemind-architecture/runtime/README.md:10、docs/bytemind-architecture/runtime/interface.go:29），建议分阶段：

• Phase 1：只做同步子代理（Spawn + Wait），不做后台归并、不做 worktree。
• Phase 2：再加 Background（CollectBackground）
• Phase 3：最后上 IsolatedWorktree，并加资源配额和冲突策略。

2. tools 五层权限要不要全做？bypassPermissions 怎么办？
   不建议一次性全做。可以按“最小可用安全闭环”先落 3 层：

• 必做：会话模式层、工具白黑名单层、路径/命令层（README.md:203-208）
• 后做：风险层细分、工具级策略细化
  bypassPermissions 必须保留“受控”语义（README.md:204、policy/interface.go:20）：只允许在受信场景开启，且仍保留 hard deny（敏感文件/高危命令/越界路径不能绕过）。

3. 每个工具统一事件流会不会太复杂？
   统一事件流本身是必要复杂度，不建议取消（README.md:198、tools/README.md:11、tools/interface.go:60）。建议控制复杂度的方法是：

• 工具层只强制 result/error
• start/chunk 设为可选
• 由 Executor 做统一封装，工具作者只填最小事件
  这样能保留可观测和回放能力，同时降低实现负担。

4. 每条记录都强制落盘是否有问题？
   有性能风险，特别是高频 chunk 事件。文档目前是“单记录原子落盘 + append-only”（README.md:227-233、storage/README.md:24-26），建议拆级：

• 强一致落盘：权限决策、任务状态变化、最终结果、审计关键事件（README.md:236-237）
• 弱一致/批量：中间 chunk/log（按阈值或时间窗口批量 flush）
• 崩溃恢复靠 event_id 去重（storage/interface.go:57）

额外提醒

当前文档内有一处优先级冲突，建议先统一：

• 总览写的是 hard_deny > explicit_deny > risk_rule > explicit_allow ...（README.md:211）
• policy 子文档写的是 explicit deny > explicit allow > risk rule ...（policy/README.md:25）
  这会直接影响 bypassPermissions 和风险规则的真实行为。

本次处理范围

• 已完成：基于 PR 文档逐条回答你的 4 个问题，并给出可落地分阶段方案。
• 未执行：未修改代码/文档。

View job run

[520wheat]

补充一次任务流程图、core层的职责、agent读取session快照的补充解释

[520wheat]

agent在处理这次的新提交时，需要先拿到该会话的“完整状态”（历史消息，build/plan模式，计划进行状态，元数据……）。
agent用来继续上下文，而不是将每次请求作为新对话，即使程序重启，也能从持久化状态恢复，不丢上下文

[520wheat]

这一层主要记录一些统一的契约规范
任务状态码均为：pending/running/completed/failed/killed
权限决策值：allow/deny/ask
……

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!