# README 架构入口重写

日期：2026-08-14

# 目标

将仓库 README 从按功能堆叠的启动说明，收敛为以 Java v1 主链路为中心的项目入口：先说明稳定内核与产品层的边界，再说明运行、验证和扩展方式。

# 变更

• 重写根目录 README.md，以 Pi Agent 的单 Agent Runtime 定位作为开场。
• 新增两张 Mermaid 图：
• 分层架构图：piagent.core 的协议、循环与三个端口，及模型、工具、会话、Web/CLI 等外围适配关系；
• 时序图：输入、状态读取、流式模型、工具回灌、SSE/Trace 和持久化的请求生命周期。
• 以当前工作树行数标注 Java 主模块（5,093 行）和 core（763 行），避免复用其他项目的规模结论。
• 明确 Java v1 + web/ 是项目的主链路，避免把额外实验运行时写入默认启动说明。
• 保留一键启动、模型配置、核心 API、工具边界、验证命令和扩展落点，并改为对应当前包结构与端口抽象的描述。

# 验证

• 以 find ... | xargs wc -l 核对 README 中的 Java 总行数和 core 行数。
• 以源码核对 Mermaid 中的依赖方向：AgentLoop 只依赖 ModelExecutor / ToolExecutor，SessionStore 使用 ContextCompressor，Model 和 ToolRegistry 在 core 外适配端口；会话状态文件名为 agent-state.json。
• 执行 git diff --check，确认 Markdown 改动没有空白错误。

# 边界

• Mermaid 图是架构说明而不是自动从源码生成的图；新增模块或调整依赖时，应同步更新节点与箭头。
• README 仅提供 v1 的常用 API 入口，不替代 docs/tasks/ITERATION_PLAN.md 的完整验收清单。