Yuxi

Appearance

0.7.3 发布决策变更记录 ​

本页汇总 v0.7.3 发布前生效的全部 86 份工程决策记录（2026-08-16 至 2026-09-08），按主题归并为 14 组；原文件随发布移动到本目录，状态统一改写为 archived，正文未改写。各记录保存当时的问题、决策、替代方案、后果与验证；机制的当前行为由代码、机制详解与仍在 implemented/ 的后续记录拥有，本页不构成运行时事实源。生命周期约定见工程决策记录。

归档边界以决策日期为准：v0.7.3 正式 tag 创建于 2026-09-09，发布日期当天作出的候选发布验证与 CLI 独立发布与QA 之外的书籍分块采样修复两份记录保留在 implemented/，进入下一个发布周期。日期早于 2026-09-02（v0.7.2 正式 tag）的记录多数随 v0.7.2 交付，2026-09-03 之后的记录属于 0.7.3 周期；用户可见变更的发布口径以版本变更记录为准。

工程信任与文档体系 ​

这一组建立 0.7.x 开发流程的基座：以语义 Owner 与 verifier 派生工程契约、以 Spec Loop 约束非平凡变更、以 Diátaxis 四类页面与证据强度词约束文档写作；首页品牌刷新是该信息架构的视觉落地，四份流程记录共享同一工程信任机制。

  • 2026-08-16-agent-first-engineering-trust — 以语义 Owner 为权威，verify_engineering_contracts.py 从代码、测试、workflow 与决策记录派生审计投影，每项检查配负向测试，trust.yml 在 main 与 PR 上无路径过滤阻塞。
  • 2026-08-16-yuxi-spec-loop — Spec Loop 统一 Scope、权威重建、Propose、实现、Verify、独立 Review、Converge 与 Learn；非平凡变更实现前先建 tracked proposed，与 PR 共用同一组验收字段。
  • 2026-08-17-documentation-information-architecture — 文档按教程、参考、机制、治理、决策与事故分层，机制页从真实装配链说明状态、权限与失败语义；公开路径保持不变。
  • 2026-08-26-human-centered-documentation — 采用面向读者的四类文档与 Passed/Inspected/Not run/Inferred 证据强度词，站点启用严格站内链接检查。
  • 2026-09-04-docs-home-brand-refresh — 文档首页以 #f3ba32 品牌色重构为七类任务入口；大图与 OG 图由项目 OSS 交付，交互尊重 reduced motion。

依赖治理与供应链 ​

审计 gate 与更新策略成对拥有依赖治理：前者拥有漏洞与许可证审计，后者拥有常规版本更新（Dependabot 常规 PR 关闭、安全更新保留）；工具链刷新与漏洞修复是该策略的两次执行落地。

发布工程与部署面 ​

两份记录收敛交付面：第三方镜像的版本钉位与许可边界，以及发布脚本对活动文档版本入口的定点同步。

  • 2026-08-17-thirdparty-image-license-boundary — Neo4j 与 Redis 引用钉版为 neo4j:5.26.29 与 redis:7.4.10-alpine；许可证、离线再分发与商业替代由部署指南「第三方组件和许可证」拥有。
  • 2026-08-26-beta2-version-bump-coverage — bump-version.sh 正式模式定点更新活动文档的版本说明、clone 分支与部署 checkout 目标；changelog 历史版本不参与替换。

测试体系 ​

清理基础设施先行，随后一轮审计先精简测试、再复核证据边界；确立「删除测试须先指出语义 Owner、现存独立 oracle 与负向覆盖」的规则，测试运行器改用 readiness gate。

  • 2026-08-19-test-conversation-cleanup — 真实 HTTP 测试创建的 Conversation 统一 YUXI_TEST_CONVERSATION_ 前缀，E2E 与 integration 共享两阶段 SHARE 锁 teardown，删除前阻止非终态 Run。
  • 2026-09-07-test-suite-simplification — 保留语义 Owner 或观察边界不同的 unit、provider 探针与 E2E 三层，只删除无独立断言的实例与低信息量单测；readiness 检查 /api/system/ready 而非 liveness。
  • 2026-09-07-test-suite-audit-follow-up — 精简后的证据边界收敛：prompt 负向断言、benchmark 事件同步、512 token 分块精确 oracle，Web 测试按实际观察边界取舍。

存储与 Workdir 单域收敛 ​

该线从多存储域收敛到 UserWorkspace 单根：进程权限与挂载解耦，Workdir 收敛为 UserWorkspace 相对路径，共享 no-follow 目录原语与 1000:1000 统一运行身份作为基础设施，随后完成 Workspace 代码 Owner 与预览 Owner 的收敛；迁移契约从 v0.7.1 一次性边界演进为版本化 Schema Owner。前三份前置记录是收敛前的早期存储方向，已被 Workdir 归属 UserWorkspace 的决定取代。

Project 资源与生命周期 ​

Project 先成为持久化业务资源，随后补齐 Project 内写审批豁免、软删除与侧边栏组织入口，最后闭合 SubAgent 与并发场景的生命周期旁路。

知识库目录与解析 ​

知识库先建立真实目录树与历史虚拟目录迁移；解析侧固定 docling-slim 依赖，并修复 QA 分块边界与统计刷新缓存两个缺陷。新目录上传的自动实体化仍在 proposed/ 跟踪，未随本版本发布。

Agent 运行时与执行边界 ​

先以不可变 attempt 历史与 manifest 指纹建立 Run 的执行事实，再收敛取消、约束与跨行校验四条执行边界；DeepAgents 0.7 升级及其暴露的 Sandbox 异步读取、checkpoint 连接池两类缺陷构成稳定性收尾，用户级 Memory 与上下文压缩是运行时能力的两块独立拼图。

  • 2026-08-16-agent-run-attempt-facts — 不可变 agent_run_attempts 表拥有执行历史与失败事实，恢复与 reconciler 只读不改写；历史 Run 无 attempt 行即 legacy。
  • 2026-08-16-agent-run-manifest-fingerprint — Run 行 write-once 固化实际采用的配置、模型、工具与 Skill 的 SHA-256 指纹；固化失败执行不开始，历史 Run 不从当前配置反推。
  • 2026-08-20-run-execution-boundary-convergence — 执行树按 root→descendants 单事务取消，数据库 CHECK ... NOT VALID 约束非终态 Run 同行形状，worker 执行前复核 scope，K8s inventory 以 selector 枚举。
  • 2026-08-23-deepagents-07-migration — 升级 deepagents>=0.7.7 与 LangChain 底座并批量升级 26+ 依赖；每 Run 构造独享 CompositeBackend，middleware 不再接受 backend factory。
  • 2026-08-23-langgraph-checkpoint-pool-recovery — LangGraph 连接池在 checkout 边界启用 check_connection，PostgreSQL 恢复后 worker 无需重启；Agent 层不重试整次执行。
  • 2026-08-23-sandbox-native-async-read — Sandbox 异步读取改用原生异步文件 API，不再依赖 shell stdout JSON 与临时 base64 文件；二进制类型保持拒绝。
  • 2026-08-23-user-memory-mvp — enable_memory 是用户级 Memory 唯一开关，写入固定操作当前 uid 的 MEMORY.md 并原子发布；Memory 与历史为低信任数据，SubAgent 无用户级 Memory。
  • 2026-09-02-context-compression-pressure-and-manual-action — summary_threshold 成为唯一压缩阈值（删除 summary_l2_trigger_ratio），完整工具结果先写 Workdir 再替换模型可见消息；手动压缩持 Conversation 行锁，忙时 409。

Skill 运行时、资源选择与 CLI 检查 ​

先定共享/个人 Skill 的存储与授权 Owner，再收敛运行时解析 Owner；预加载与共享智能体资源选择在两者之上建立首轮可见性与写边界。完整资源选择协议由仍在 implemented/ 的统一资源选择决策继续拥有。

  • 2026-08-18-skill-source-convergence — 共享 Skill 只存 YUXI_SKILL_DATA_DIR/shared/<slug>，个人 Skill 始终由 UserWorkspace 拥有；投影只读，同 slug 个人版本逻辑覆盖共享版本。
  • 2026-08-20-skill-runtime-module-boundary — agents/skills/runtime.py 统一拥有 Skill 解析与激活包派生，Middleware 只保留请求包装与注入；删除无消费者 Python API 且不留 re-export。
  • 2026-08-17-skill-preload — preload_skills 允许智能体预加载少量 Skill，首轮注入完整说明；预加载文件不可读时 Graph 创建显式失败。
  • 2026-09-05-shared-agent-resource-selection — 共享智能体保存把 config_json.context 作为字段补丁，行锁内合并并保留不可见引用；运行期只使用操作者可访问资源的交集。
  • 2026-08-27-cli-agent-inspection — CLI 新增 yuxi agent list 与 yuxi agent show，经 discovery 能力声明拒绝不支持契约的旧服务端。

增量审计与调试可观测 ​

审计按阶段推进：先固化 trace 与 stream 基础事实（阶段一），再闭合 Model/AIMessage（阶段二）与 ToolMessage（阶段三）写入，随后修正大结果卸载下的终态对账，最后收紧读模型边界并统一读接口；调试面板与 Langfuse 跳转是同一线的消费端。

后台任务与定时调度 ​

通用后台任务以 PostgreSQL 行为持久执行意图，用户定时任务复用同一 worker reconciliation loop；两者都通过完整业务升级引入并依赖统一迁移契约。

  • 2026-08-25-durable-task-execution — tasks 行拥有执行意图、去重键、Handler 版本与 lease，API 退出后 pending Task 仍可执行；失联任务统一失败不自动重试，claim 上限 4。
  • 2026-08-26-user-agent-scheduled-tasks — 用户定时智能体任务（cron、时区、FOR UPDATE SKIP LOCKED 领取）每次触发创建绑定原 Project 的新 Conversation；停机错过多周期合并为一次。

并发容量与时延 ​

容量基线与协议先建立，前端消费同一套时延口径，随后的模型前时延优化在协议之上延伸并给出正式评测矩阵，同时接管更早的八份并发决策（已删除，不在本批）。

  • 2026-09-04-agent-concurrency-capacity — 默认容量基线（ARQ_MAX_JOBS=140、PostgreSQL max_connections=600）与 SSE 自适应轮询、取消协议、Sandbox 惰性创建（默认 core profile、独立地址池）；AgentRun write-once 持久保存五个阶段时间点。
  • 2026-09-05-frontend-optimization — History 独立返回 runs，消息经 run_id 关联并删除 Run 时间副本；调试面板统一时间轴，流式正文由 useStreamSmoother 缓冲播放；前后端须同步发布。
  • 2026-09-07-agent-concurrency-optimization — 按读取、派发、执行、收尾保留最小优化，新增 first_model_request_at 与正式主指标；3150 请求矩阵显示多 Worker 将 100 并发准备阶段 P50 从 4442ms 降至 138ms（4 Worker）。

表面收敛与能力移除 ​

两个整块能力移除与三批无消费者表面收敛；每项以「旧能力不存在 + 重新引入条件」验证，移除均不建兼容层。部署模式收敛是本组对升级者影响最大的部分。

  • 2026-09-03-remove-lite-mode — 取消 LITE 运行模式，Compose 始终声明完整知识拓扑；既有轻量安装升级前必须补齐 Milvus、etcd、Neo4j 及完整知识运行资源。
  • 2026-09-03-remove-content-guard — 完整移除内置内容审查能力及其配置入口与文档页；需要内容安全策略的部署须在模型供应商、网关等边界自行接入。
  • 2026-09-03-reduce-pipeline-redundancy — 解析能力由 capabilities.py 单一 Owner 派生，删除 AgentRun.last_event_id（业务 Schema v5 幂等迁移）与未消费 artifact。
  • 2026-09-03-remove-secondary-redundancy — 删除无消费者的 agent_runtime_service、message_feedback_repository、useMention 等内部表面；工具参数协议与 Run 取消信号各归单一 Owner。
  • 2026-09-04-remove-redundant-surfaces — 删除无生产消费者的组件、helper 与依赖（净减 2762 行），Web 测试收敛唯一正式根；被删 Compose no-op 变量不再表现为有效配置。

前端体验与交互 ​

Agent 面板与文件来源 ​

面板三篇构成「边界划分 → 结构承载 → 文件身份与刷新」的三段式；状态面板、输入区与交付物保存共享同一组选择器与授权原语。

Dashboard 与用户管理 ​

Dashboard 先定分层与数据能力，再统一组件与统计口径；用户管理以并存双契约引入服务端分页。

对话模型绑定与消息展示 ​

对话绑定模型、流式与推理展示构成「渲染节奏 → 数据保真与供应商协议 → 展示统一」的完整链路；子智能体工具边界在执行层强制。

独立前端修复与性能 ​

升级与部署影响索引 ​

影响点要求记录
部署资源LITE 移除，轻量安装须补齐 Milvus、etcd、Neo4jremove-lite-mode
内容安全内置审查移除，须在供应商或网关边界自行接入remove-content-guard
Sandbox 规格默认 core，浏览器自动化与完整服务须显式选择 profile；独立地址池 10.253.240.0/20 需自查冲突agent-concurrency-capacity
数据库迁移唯一 migrator 拥有双域版本，启动前必须执行；business 与 knowledge 多次幂等升级一次到位versioned-schema-migration-owner、workdir-in-user-workspace、durable-task-execution
运行身份数据面固定 1000:1000，旧目录身份由 root migrator 启动前收敛unified-workspace-runtime-identity
镜像与依赖docling-slim（XLS 需 LibreOffice Calc）；NLTK、unstructured、LlamaIndex、LangChain Community/Classic 移除docling-slim-office-parser、dependency-vulnerability-remediation、performance-and-bundle-optimization
接口契约History 独立返回 runs；/model-audits 404；/api/auth/users/page 新增；config_json.context 补丁语义frontend-optimization、unify-message-audit-read-api、user-management-server-pagination、shared-agent-resource-selection
消息内容推理内容进标准块，content 为块列表，纯文本消费者用 message.textprovider-reasoning-adapter
配置项summary_l2_trigger_ratio 删除，summary_threshold 为唯一阈值context-compression-pressure-and-manual-action
Langfuse跳转 URL 仅接受与 LANGFUSE_BASE_URL 同源的 HTTP(S)agent-run-langfuse-jump
前端依赖lucide-vue-next → @lucide/vue，依赖与导入 specifier 更名，图标名称与样式不变lucide-vue-package-migration

取代与吸收关系 ​

本项目基于 MIT License 开源，欢迎使用和贡献。

Copyright © 2025-present Yuxi