Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

tracking: 架构缺陷系列（9 项）—— 最小化嵌入不可达 + AG-UI 生产化受阻

Đang mở
  • Có gì không ổn?
#52 6 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
25/100
Loại issue
Tái cấu trúc
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
rust
Lĩnh vực
api, backend, build-system, documentation

Hướng nghiên cứu

Start by reviewing the linked child issues #53–#61 and the cited files, including docs/architecture/invariants.md, README.md, src/acp/session.rs, and the AG-UI handler. Run the stated cargo checks and invariant tests to confirm the baseline. Done means all child issues are closed and the listed feature, session, documentation, and CI acceptance conditions pass.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

记号说明：正文中的「不变量 #N」指 docs/architecture/invariants.md 的编号，不是 GitHub issue 编号。本系列各 issue 的引用一律使用完整链接（如 #53）。

Summary

这是一组架构缺陷的 tracking issue，共 9 项。来源：为评估「C 端 Agent 业务（仅 Skill 加载 + 轻量 CLI 调用，无文件系统）能否基于 recursive 落地」而对全仓做的架构审查。

所有结论均以 path:line 引用 + 实测命令验证，非静态推测。基线 HEAD = cee6279。

两条被阻塞的事：

  • (a) 无法构建任何最小化的 recursive 嵌入版本 —— README.md:38-39 承诺的 --no-default-features 在 HEAD 上完全不工作（8 个 feature 组合实测全部失败）。
  • (b) AG-UI 通道（前端对接协议）产生的会话在系统内是二等公民 —— 多副本部署、按用户计费、跨会话记忆全部受阻。

另有治理层缺陷：「八条不变量」在两份契约文档里不是同一套规则（#2/#4/#6 冲突）。

子 issue 清单

# 标题 优先级 依赖
#53 核心 Tool trait 依赖 acp::ToolKind（分层倒置） P0 —
#54 acp 无 feature gate + agent-client-protocol-schema 非可选 P1 #53
#55 --no-default-features 无法构建（8 组合实测），README 声明不成立 P0 #53,#54（短期可独立修）
#56 AG-UI 服务端未抽象成层：agui_run 654 行单函数 P0 —
#57 AG-UI 另起一套更弱的 session，对 session 系统整体不可见 P0 #56（建议同做）
#58 message.rs ⇄ llm/ 真实循环依赖 P1 —
#59 活文档指向已不存在的路径 P2 —
#60 src/tools/ 36,055 行、49 文件全平铺 P2 —（但与 #59 同做）
#61 「八条不变量」#2/#4/#6 在两份契约文档里冲突 P1 —

建议落地顺序：#53 → #55(短期) → #54 → #56+#57 → #61 → #58 → #59 → #60

这 9 项不是并列的

链条 A — 最小化嵌入不可达（根因在 #53）
#53  Tool trait 返回 acp::ToolKind              ← 根因
        ↓ 强制 acp 无条件编译
#54  acp 无 feature gate（6,953 行 + 非可选 acp-schema 依赖）
        ↓ 而 acp/session.rs:178 用了 crate::mcp::
#55  --no-default-features 8 个组合全部构建失败
        ↓ 于是
     README.md:38-39「可嵌入最小内核」的声明不成立

顺序不可交换：#53 不做，#54 做不了；#54 不做，#55 只能「表面修好」（编译过了，但仍被迫带上 6,953 行 acp + 2,933 行 mcp + agent-client-protocol-schema）。

链条 B — AG-UI 生产化受阻（#56 与 #57 互为表里）
#57  AG-UI 另起一套更弱的 session                 ← 代价
        ↑ 因为没有层去承载它
#56  AG-UI 服务端不是层，是 654 行 handler 函数    ← 成因

#56 是「为什么写成了这样」，#57 是「写成了这样的代价」。建议一个设计、两个 PR。

独立项
  • #58 message.rs ⇄ llm/ 循环依赖 —— 拆分 crate 时的硬路障
  • #59 活文档路径漂移 —— 与 #61 同类病（活文档无守卫）
  • #60 src/tools/ 36,055 行扁平 —— 认知负担；与不变量 #4 冲突，需先决策
  • #61 八条不变量自相矛盾 —— agent 的宪法有两套

规模与风险

# 量级 风险
#53 半天 低（机械移动）
#54 1 天 中（动 workspace feature 声明）
#55 1 小时 / 随 #54 低
#56 2-3 天 中（新增抽象层）
#57 2-3 天 中（新增抽象层）
#58 半天 低
#59 1 小时 无
#60 1-2 天 低（但与不变量 #4 冲突）
#61 需作者决策 低

调查后被排除的候选问题（勿重复立项）

审查过程中有若干项看起来是缺陷但经核实不是。记录在此，避免重复立项。

1. run_core.rs 3,870 行 —— 不是缺陷

初判：全仓最大文件，与不变量 #1「agent loop stays small」冲突。
核实结果：不变量 #1 被严格执行，且当前全绿。

tests/invariants/loop_size_orthogonality.rs 里有四道守卫：

守卫 限制 当前
kernel_loop_stays_small kernel.rs ≤ 1000 行 ✅
runtime_stays_manageable runtime.rs ≤ 3700 行 ✅
run_inner_function_body_stays_small run_inner 函数体 ≤ 150 行 ✅
run_core_production_stays_small run_core.rs 生产代码 ≤ 1500 行 ✅ 1,407 
$ cargo test --test invariants loop_size
test loop_size_orthogonality::run_core_production_stays_small ... ok
test loop_size_orthogonality::runtime_stays_manageable ... ok
test loop_size_orthogonality::kernel_loop_stays_small ... ok
test loop_size_orthogonality::run_inner_function_body_stays_small ... ok
test result: ok. 6 passed; 0 failed

3,870 行的构成：生产代码 1,407 行 + 内联测试 2,462 行（64%）。守卫只量生产代码，内联测试不违规。且该文件有清晰的演进史（loop_size_orthogonality.rs:69-84）：G219 基线 ~394 行 → P1-1 拆分降到 ~117 行。

结论：这是一个被良好守护的文件，不是债务。

2. 两个 doc-comment 假阳性 —— 不是依赖

静态 grep 曾报出两处「向上依赖」，逐行核对确认只是文档注释提到：

  • src/runtime.rs:110 注释里提到 crate::http::SessionState
  • src/skills.rs:616 注释里提到 crate::run_core::call_llm

对比之下，#58 的 message ⇄ llm 是真 use，已逐行确认。

3. metrics_handler 1,320 行 —— 不是缺陷

src/http/handlers.rs 里最大的函数，但绝大部分是 Prometheus format! 静态字符串。不要顺手重构它。

与既有流程的关系

  • 本系列是 defect（已在 HEAD 上验证存在），不是 feature request。C 端能力缺口（远程 SkillSource、RunCli/HttpCall 工具、按租户工具表 resolver）性质不同，应另外排期，不混入本系列。
  • 适合直接走自迭代流程的：#53、#55、#58、#59（机械、低风险、可独立验证）。
  • 需要先出设计/决策的：#54（动 workspace feature）、#56+#57（新增抽象层）、#60（与不变量 #4 冲突）、#61（需作者拍板八条还是十条）。

Acceptance

  • 9 个子 issue 各自关闭（含各自的验收条件）。
  • 链条 A 完成后：cargo check --no-default-features --lib 在不开 acp / mcp 的情况下通过，且 cargo clippy --no-default-features -- -D warnings 干净；CI 有 feature-matrix 守卫。
  • 链条 B 完成后：AG-UI 一轮对话产出 .meta.json，recursive sessions list 可见，episodic_recall 可检索，成本落盘，多副本（Redis/S3）可用。
  • #61 完成后：三份文档的编号 → 标题映射一致，且有自动化守卫。

depends-on: #53
depends-on: #54
depends-on: #55
depends-on: #56
depends-on: #57
depends-on: #58
depends-on: #59
depends-on: #60
depends-on: #61

Ngôn ngữ chính
Rust
Star
4
Fork
0
Merge trung bình
5 giờ 32 phút
Pull request đã merge (30 ngày)
7

Chuẩn bị môi trường

  • Có Dockerfile hoặc tệp Docker Compose
  • Không có mẫu pull request
  • Không có hướng dẫn đóng góp

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của jeffkit/recursive

Tất cả issue của jeffkit/recursive

Issue tương tự

Thêm issue về Rust

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.