docs: describe the unified Agent topology and link controls

Align architecture, protocol, API, storage, security and deployment documentation with default mutual measurements and the Agent link board.
This commit is contained in:
justme committed 2026-10-21 11:55:55 +08:00
1 parent 15f0023614
commit c9beeee8e3
16 files changed
+363 -383

No files matched your search

+6 -6
View File
@@ -34,7 +34,7 @@
- 契约和领域值使用 `sealed record` 或 `readonly record struct`,并且不可变。
- 热路径上的计数器和缓冲区使用可变 `struct` 或 `sealed class`,所有权要写清楚(谁创建、谁归还池)。
- ID 使用强类型(`readonly record struct ProbeId(string Value)`),不直接传裸 `string`。
- ID 使用强类型(`readonly record struct NodeId(string Value)`),不直接传裸 `string`。
- 枚举序列化成 snake_case 字符串(`JsonStringEnumConverter<T>` + `JsonStringEnumMemberName`);新增枚举值不属于破坏性变更,但所有消费方都必须能处理未知值。
- 可空性:公共成员必须标注;使用 `!` 抑制警告时,同一行要写注释说明理由。
@@ -61,19 +61,19 @@
- 序列化只使用 `System.Text.Json` 源生成上下文(或手写的二进制编解码);禁用无上下文的 `JsonSerializer.Serialize<T>(T)` 重载。
- 不做程序集扫描、`Activator.CreateInstance`、`Type.GetType(string)`、动态代理或 `Reflection.Emit`。
- Probe/Agent:不使用 DI 容器,在 `Program.cs` 中手工组装对象,依赖关系一眼可见;不使用 LINQ;不使用 `HttpClient`(Agent 的 WebSocket 使用 `ClientWebSocket`)。
- Agent:不使用 DI 容器,在 `Program.cs` 中手工组装对象,依赖关系一眼可见;不使用 LINQ;不使用 `HttpClient`(Agent 的 WebSocket 使用 `ClientWebSocket`)。
- Backend:使用 `CreateSlimBuilder` + Minimal API;只能通过 `Microsoft.Data.Sqlite` 执行手写的参数化 SQL,禁止字符串拼接 SQL。
- 热路径:使用 `Span<T>`、`stackalloc`(≤ 256 B)、`ArrayPool<byte>.Shared`;每个包的处理过程中不分配内存、不写日志。
- 新增任何第三方包之前,需要先更新 [project-layout.md](project-layout.md) 第 3 节的依赖表,并在 PR 中说明理由。
## 8. 日志
- 统一使用 logfmt 字段名:`ts`、`level`、`msg`、`agent`、`probe`、`session`、`task`、`result`、`err`。
- Backend 使用 `Microsoft.Extensions.Logging` 源生成的 `[LoggerMessage]`;Probe/Agent 使用 `NodeLog`,两者输出的字段名相同。
- 统一使用 logfmt 字段名:`ts`、`level`、`msg`、`agent`、`dialer`、`session`、`task`、`result`、`err`。
- Backend 使用 `Microsoft.Extensions.Logging` 源生成的 `[LoggerMessage]`;Agent 使用 `NodeLog`,两者输出的字段名相同。
- 令牌、`session_key` 和 MAC 不能出现在日志里;IP 地址可以记录。
- 每个会话或连接的生命周期事件记录为 Info;逐包事件不记录,只累加计数。
## 9. 节点能力边界(Probe/Agent 与 Fleet 节点侧)
## 9. 节点能力边界(Agent 与 Fleet 节点侧)
- 由 `BannedSymbols.Node.txt` 在编译期强制:禁止启动进程、动态加载程序集或本机库、使用 `HttpClient`、在配置目录以外写文件。唯一的豁免点是 `Fleet.Hosting.ConfigStore`,豁免必须写 `#pragma` 并附上理由注释。注册在 `fleet-enroll` 中完成,更新由节点宿主机上的更新器完成,常驻进程当前不需要这些能力。
- 节点不能新增任何“由远端触发的非采集动作”对应的 RPC 方法。凡是新增 RPC 方法的 PR,都要在描述中说明它不会扩大权限边界。
@@ -106,6 +106,6 @@
## 12. 提交与评审
- 提交信息使用 `<范围>: <摘要>` 格式,范围取 `probe`、`agent`、`backend`、`shared`、`web`、`docs`、`scripts`;是否触发 CI 的标记见 [AGENTS.md](../../AGENTS.md)。
- 提交信息使用 `<范围>: <摘要>` 格式,范围取 `dialer`、`agent`、`backend`、`shared`、`web`、`docs`、`scripts`;是否触发 CI 的标记见 [AGENTS.md](../../AGENTS.md)。
- 修改 `backend/shared/MoShiro.Protocol` 的 PR 必须说明兼容性影响(新增字段、行为变化、需要升级版本)。
- 修改 `backend/openapi/v1.json` 的 PR 必须按照 [api.md](../api/api.md) 第 7 节的「版本与兼容性」判断是否属于破坏性变更。