docs: add architecture context diagrams#589
docs: add architecture context diagrams#589pionxe wants to merge 6 commits into1024XEngineer:mainfrom
Conversation
|
Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits. |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
![fennoai[bot]](https://avatars.githubusercontent.com/in/1924301?s=60&v=4){kind=small}
| **原生客户端（NeoCode 内置）：** | ||
| - **TUI**：终端交互界面（Bubble Tea），通过 RPC 连接 Gateway | ||
| - **Web**：React SPA，embed 到二进制中，由 Gateway 提供静态文件服务 | ||
| - **Desktop**：Electron 壳，内嵌 Web UI，提供系统托盘和原生通知等桌面能力 |
There was a problem hiding this comment.
The Electron shell in web/electron/main.ts only manages a BrowserWindow and the gateway subprocess; there is no tray or native notification integration in the current implementation. Documenting those desktop capabilities here as already supported will mislead readers about what the desktop client can actually do today.
| ### 3.4 边界规则 | ||
|
|
||
| 1. **代码数据不出本地**：所有文件系统操作限制在 `--workdir` 指定目录内，代码内容不经 Gateway 上传至任何云端服务。 | ||
| 2. **模型请求仅含必要上下文**：发送给模型厂商的请求仅包含 System Prompt + 对话历史 + 工具定义，不泄露本地路径、环境变量或密钥。 |
There was a problem hiding this comment.
This boundary rule is inaccurate for the current codebase. Provider requests are not limited to just system prompt + chat history + tool schema: sub-agent requests explicitly include local workdir and allowed_paths in internal/runtime/subagent_engine.go. Stating that model requests never leak local paths weakens the security section because it contradicts the implementation.
|
|
||
| 本节描述 NeoCode 与外部世界的交互关系，即 C4 模型中的 Level 1（系统上下文图）。 | ||
|
|
||
|  |
There was a problem hiding this comment.
The Markdown references only diagrams/system-context.svg, but this PR also adds system-context@2x.png as a 242 KB binary and nothing in the repo points to it. Unless an external publishing step consumes that PNG, it is dead weight in git history and should be omitted from the PR.
|
|
||
| #### 8.5.1 Checkpoint（代码版本快照） | ||
|
|
||
| NeoCode 实现了轻量级的本地代码版本快照系统。每次 AI 执行写操作前（`pre_write`）、Plan Mode 切换时、上下文压缩时（`compact`），系统会自动创建代码快照（Checkpoint），记录当时的文件状态。快照数据存储在 Session SQLite 数据库中，支持恢复（Restore）和过期修剪（Prune）。这套机制与 Git 并存：有 `.git` 目录时优先使用 Git 的版本追踪；无 `.git` 时 Checkpoint 提供独立的安全网。 |
There was a problem hiding this comment.
The checkpoint description overstates the current implementation. I could not find any runtime/checkpoint branch that prefers Git state when a .git directory exists; the code paths here use the SQLite/per-edit snapshot stores directly. Please either document the actual behavior or point to the code that makes the Git-preferred fallback real.
Cai-Tang-www
left a comment
Cai-Tang-www
left a comment
There was a problem hiding this comment.
没啥问题，作为架构文档相当好，但是如果要路演/why这样设计可能到时候再开文档吧
2 participants
编写系统架构文档
Closes #514