v3.0.0

定位升级：从"会记账的助手"变成"能管仓位的财务部门"。
三条主线都是确定性计算 + 可复核输出，没有一处让模型自己算数。

新增：投资策略引擎（app/calculations/{portfolio_risk,strategy,valuation}.py）

纯标准库实现，零新增依赖。所有指标口径写进 docstring，样本不足时返回
null 并标注原因，绝不返回看起来合理的假数值。

能力	内容
组合风险	年化波动率、夏普、索提诺、最大回撤、Calmar、Beta/Alpha、历史模拟法 VaR(95%)、上涨天数占比、单日最佳/最差
基准对比	沪深300/上证/深成/创业板四条基准，净值曲线双线归一化对比，超额收益
再平衡	目标配置 + 容忍带（3/5/8/10%），输出买/卖金额与整手股数；A 股卖出可零股、买入必须整手
估值温度计	当前价在近 750 个交易日区间中的位置分位，五档分区（低位区/偏低/中枢/偏高/高位区）
定投	月/周计划、累计投入、份额、成本线、当前盈亏、下一期扣款日；数据覆盖前的定投日不补记
FIRE	目标本金（年支出/提取率）、完成度、储蓄率、复利年限；不可达时返回 reachable=false 而不是一个假年限

新增 6 个 REST 端点（/api/strategy/*）、5 个 agent 工具、5 个 MCP 工具
（外部 AI 也能调用），以及前端「投资策略」页（风险指标条 + 净值曲线 +
再平衡表 + 估值色阶 + 定投表 + FIRE 进度）。

新增：审计底稿导出（M6.1）

GET /api/audit-report 把 provenance 链路渲染成可归档 HTML：每条记录带
来源徽标、操作人、before/after 只列变化字段的差异表。浏览器内一键
打印为 PDF。输出 HTML 而不是 PDF 是为了不引入几十 MB 的渲染依赖；
所有动态内容经 html.escape，并附 CSP 头禁用外部资源。

新增：模型评测题库与判分器（M6.3）

app/eval_bank.py 50 道题，覆盖记账解析/预算/负债/持仓/策略/口径推理六类。
app/model_eval.py 用确定性判据打分（数值按容差、文本按关键结论），
不让 LLM 给自己打分。端点：/api/eval/{questions,run,score,leaderboard}。
未配置模型时明确返回未评分，不生成假成绩。

性能：后端预聚合（M5.3）

/api/dashboard 本月现金流改走 SQL GROUP BY（db.month_cashflow），
流水明细限 500 条 + 独立总数；加 10 秒 TTL 缓存（键含 DB 路径与租户），
所有写路径（记账/持仓/负债/订阅/目标/预算/设置/确认执行/对话记账）
统一失效。账本十万行时不再把整库搬进内存。

修复：界面口径与真实缺陷（截图审查发现，全部有回归测试）

• 持仓编辑成本价放大 100 倍：positions[].cost 是总成本，编辑框要每股成本；
  新增 cost_per_share 字段，前端与"追加持仓"都改用它。
• 占比双口径打架：by_asset 同时给 pct（相对总市值，合计 100%，
  供饼图与占比列）与 investable_pct（相对非现金，供集中度判定）；
  此前现金行也用非现金分母，导致占比列合计 126%、风险提示 50.4% 与
  集中度 63.6% 同屏并存。
• 今日盈亏恒为 +0.00%：分母把已是总额的 cost 又乘了一次股数。
• 健康评分两套值（51 vs 50）：/api/calculations/health 改走
  analysis.health_check 单一实现。
• 亏损写成"浮盈"：文案按盈亏正负切换浮盈/浮亏。
• 总资产两个值（282,540 vs 264,884）：/api/calculations/net-worth
  与健康评分都改用实时行情，与总览同源。
• 手机端：设置项 Row 改上下堆叠（供应商选择器不再横向溢出）；
  对话上下文条改 sticky top-0（不再被顶栏裁切）。
• 饼图中心文字被扇区覆盖：环孔从 0% 改为 48%。
• 命令面板补「去投资策略」入口。
• 表格/统计格：占比列合计归 100%；平板宽度下大数字不再断行。

仓库与文档

• 删除入库的 frontend/coverage/（48 个产物文件）与零引用的 docs/demo/（980KB 旧图）。
• scripts/push-all.sh 重写：5 目标真实可用，支持 --dry-run/--only，
  凭据只从环境读取、打码输出。
• README 补 Release/CI/Docker badge、30 秒上手、Why Xiaoman 对比、策略页截图；
  测试数统一为真实值。
• PROGRESS 同步到 3.0.0；ROADMAP-v3 标注为历史快照；三份旧审计文档加
  「历史快照，不代表当前状态」声明并归入「质量与审计（历史）」分组。

验证

• 后端 906 passed（原 791 + 新增 115）；ruff check app tests 全过。
• 前端 111 单测 + tsc + vite build 全过。
• 截图审查 15 张（桌面/手机/平板/暗色/空库/降级），逐张人工核对，无
  undefined/NaN/空白/裁切。

说明

组合风险曲线是按当前持仓回溯的模拟净值，不是实盘历史成交净值；
接口用 basis: "backtest" 与 basis_note 明确标注，前端在卡片上展示该提示。

v2.9.1

界面最后一层：让对话里的数字"能操作"，而不是只读文本。

富回答块（components/chat/FinanceBlocks.tsx）

后端一直有 card 事件带完整的 market / ledger / flags，但前端只画了个静态四宫格。
现在按数据的实际内容渲染三种可操作块：

• 持仓概览：总市值 + 盈亏/收益率，列出前三大非现金持仓；
  点任一行展开该标的 60 日走势（纯 SVG，不引图表库）；底部提示超限项。
• 本月收支：收入/支出/结余/储蓄率四指标 + 支出分类条形（按金额排序）。
• 需要注意：风控 flags 列表，每条带「去处理」跳转到对应页面。

去重

同一信息此前会重复三遍（风险块 / SummaryBlock 的等级徽章 / Action 按钮）：

• 有富回答块时 SummaryBlock 只保留「小满的理解」（意图识别），不重复指标与等级。
• 有块时不再渲染 action 按钮（块内已有「查看 →」）。
• 风险块跳过集中度条目（持仓块底部已提示）。

上下文条

对话顶部新增一行：本地数据 · 3 项持仓 · 2 条消息 · 更新于 16:59。
没有它，回答里的数字缺少可信度锚点，用户不知道助手看的是哪份数据、多久之前。

验证

• 前端 111 单测 + 21 e2e 通过；后端 786 通过；
• 截图确认：持仓块可展开走势、收支块分类条形、风险块跳转、上下文条按实际数据渲染。

v2.9.0

按「设置里该有的四类能力」逐项核对：Skill 已有、Prompt 只读、Plugin 缺失、知识库缺失。
补完后 Agent harness 的三个缺口（循环、输出上限、重试）也一并补上。

四类能力盘点与补齐

能力	补齐前	现在
Skill	4 个内置 + 自定义可增删、可绑定时	不变（已完备）
Prompt	agents/<name>/instructions.md 文件驱动，设置页不能改	新增「系统提示词」分区：可视化编辑、留空回落默认、4000 字上限、即时生效
Plugin	缺失：外部 MCP 服务器只能手改 backend/data/mcp.json，格式错一处整份失效	新增「插件（MCP）」分区：增删、测试连接、显示已发现工具；URL 凭据打码；写工具仍被禁止
知识库	缺失：附件只能附在单条消息上，不参与检索	新增「知识库」分区：上传文档→切片→BM25 检索→注入 system 消息；可逐个开关、删除

知识库实现（app/knowledge.py）

• 切片：段落优先 + 长段落带重叠滑窗（400 字 / 80 字重叠），避免把句子切断。
• 检索：复用 rank-bm25（与长期记忆同一套中文双字+单字分词），只保留 score > 0 的命中。
• 注入：拼成带文件名的片段，2400 字预算内按得分顺序截断。
• 开关：knowledge_enabled（默认 on），关闭后完全不检索。
• 为什么不上向量库：与「本地优先、零外网」冲突（embedding 需外部 API 或几百 MB 本地模型）；
  接口按 retriever 设计，将来换向量实现只需替换 rank_chunks。

Agent harness 加固

• 工具循环检测：连续 3 次用相同参数调同一工具时中断并告知模型「结果不会变化」。
  此前只有 turn_cap 兜底，要烧满 5 轮才停。
• 输出上限：工具循环的模型调用补 max_tokens=2048，防超长生成拖到超时。
• 重试与超时：非流式调用补 num_retries=2 + timeout=60（与流式路径对齐）。

验证

• 后端 786 通过（新增：MCP 管理 8、知识库纯函数 9、知识库接线 3、循环保护 6）。
• 知识库接线测试断言「入库文档的原文确实出现在 system 消息里」，非入库文档不出现。
• 前端 111 单测 + 21 e2e 通过；设置页 16 个分区逐页截图无报错。

v2.8.6

• Windows exe 双击闪退（Critical，CI 实测复现）：run.py 打印中文横幅时，
  Windows 控制台默认编码是 cp936/cp1252，UnicodeEncodeError: 'charmap' codec can't encode characters → 未捕获异常 → 进程退出。现在启动时把 stdout/stderr 切成 UTF-8
  并带 errors="replace" 兜底。
• 移除 spec 里无效的 croniter hidden import（项目未使用该依赖，PyInstaller 报
  Hidden import 'croniter' not found，在 CI 中只是警告，但会干扰真实错误定位）。

v2.8.5

逐个分区走查设置页，修的都是"用户会踩到但不会报错"的逻辑问题。

• 未保存改动静默丢失：改完设置点「关闭」直接丢弃修改，没有任何提示。
  现在关闭前弹确认（放弃并关闭 / 继续编辑）。
• 访问口令页自相矛盾：输入框说明"后端 API_TOKEN 相同时才生效"，下面又说
  "未设置时无需口令"，用户填完无从判断是否生效。现在 /api/health 返回
  auth_mode（token / accounts / local），页面顶部直接显示当前实例的真实鉴权模式，
  并区分「需要口令 / 已启用账号体系 / 本机免登录」三种情况下的操作指引。
• 默认配置只读且无指引：「Agent 与技能」底部展示默认语言/模型/审批阈值/工具轮次，
  用户看到数值却不知道去哪改。现在每项下方标注实际修改位置。
• 危险操作无区分：「清空全部历史」与普通按钮同样式。改为危险色描边，
  并把「备份与恢复」独立成段，与危险操作分开。
• 「恢复」按钮文案改为「加载示例数据」，明确它做的是覆盖式载入演示数据。
• 设置页内容区放宽（max-w-5xl → 6xl 并改为 flex 布局），1440 下不再出现右侧大片空白。

验证

• 后端 760 通过（新增 3 项 auth_mode 回归）；前端 111 单测 + 21 e2e 通过。
• 设置页 13 个分区逐页截图 + 无 console/page error。

v2.8.4

界面

• 设置页改为真正的左右分段导航：桌面左侧固定导航栏（三组：基础设置 / AI 与自动化 /
  数据与安全），右侧内容区独立滚动；手机端改为顶部横向分段条（一次一段，单次点击到达），
  替代原先需要两次点击的两层折叠。
• 分段控件与标签在 390px 下不再被挤压换行。

打包

• xiaoman.exe 嵌入图标（backend/app.ico，7 个尺寸）与版本资源
  （FileVersion / ProductName / FileDescription 来自 version.py 单一真源）。
• 实测：FileVersion 2.8.3、ProductName Xiaoman，运行首页 200 / API 正常 / MCP 正常。

v2.0.0

[2.0.0] — 2026-10-09

Added

• devkit-doctor.py — CLI health check tool covering skills/scaffolds/mcp/hooks/env
• tests/test_devkit_doctor.py — self-contained integration tests
• scaffolds/scaffold-runner.py — flat-scaffold execution engine
• scaffolds/scaffold-protocol.md — Scaffold Protocol v2.0
• scenarios/programming/fullstack/{bootstrap.sh,bootstrap.ps1}
• context/architecture.md (ADR-001)
• docs/requirements/devkit-doctor.md + docs/design/devkit-doctor.md
• AGENTS.md — 跨平台统一指令（官方 AGENTS.md 标准，含平台自省声明）
• platforms/ — 平台能力矩阵 + 自省机制（复用平台原生能力，不重复造轮子）
• framework/ — 通用能力层（skills 通用技能库 33+ / agents 多角色 / mcp 全集）
• framework/skills 新增 10 个通用技能：code-review、debugging、test-strategy、api-design、secret-scanner、performance-optimization、documentation-writing、architecture-design、requirements-analysis、commit-conventions

Changed

• scaffold-runner：修复 opencode Windows shim 调用（.cmd/.ps1 经 cmd /c + stdin 传参），并完成真实端到端验证（scaffold-runner→opencode→读 AGENTS.md+skill→产物门禁→完工强制）
• scaffold-runner：新增 opencode provider、每步强制产物校验（outputs gate）、完工强制门禁（enforce_active）、skills 路径指向 framework 通用层
• .gitignore 忽略 logs/sessions/（session 产物不入库）
• 新增 hooks/scripts/enforce_active.py 强制门禁（机制层，跨平台）：上下文/doctor/测试/密钥/CHANGELOG 校验
• hooks/config.yaml 挂载开工（--pre）与完工强制门禁
• AGENTS.md / platforms/README 增加「提示层 vs 机制层」分层说明与按平台强制接入
• devkit-doctor 支持带参数的脚本引用（如 script.py --pre）
• 版本统一为 2.0.0（README/plugin/expert/docs/CHANGELOG 一致）
• devkit-doctor 技能检查增强：扫描所有场景 skills 并集 + 校验「技能名 == 目录名」
• AGENTS.md 增加「强制主动使用能力」机制（Skills/Agents/MCP 必须主动调用，禁止闲置）
• 通用技能从 scenarios/programming/fullstack/skills 提升至 framework/skills（去重、解耦场景）
• fullstack/lib 提升为 framework/lib（通用脚本库）
• devkit-doctor.py 支持检查 framework/skills 通用技能层
• bootstrap 检查 framework/skills
• scaffold.yaml split sequential/parallel (YAML dup-key bug) → flat v2.0
• platforms/ 重构：删除 17 个重复平台 README，改为单一平台能力矩阵 + 自省声明（复用平台原生能力）
• AGENTS.md 增加平台自省机制（识别平台 → 用平台原生能力 → 只补缺失）
• fullstack/scaffolds/*.yaml rewritten in v2.0
• hooks/scripts/{error-alert.sh,pre-task.sh} bash JSON parsing → Python inline
• mcp/config/awesome-servers.json 28 servers → 12 (removed duplicate-key hack)
• .env.example 140+ vars → 8 core vars
• README.md repositioning

Removed

• fullstack/tools/ (26 Python utilities)
• fullstack/validation/ (5 scripts)
• hooks/scripts/middleware/ (6 orphaned middleware files)
• tools/README.md
• docs/PLATFORMS.md（内容并入 platforms/README.md）
• platforms/ 下 17 个冗余平台 README（保留官方必需入口）

Fixed

• YAML duplicate key silently dropping steps
• pre-task.sh nested $() syntax error
• error-alert.sh JSON parsing failure in Git Bash
• Cross-platform bootstrap path + Python invocation

---

相关资源

• 官网: https://x33834.github.io/awesome-ai-devkit/
• 问题反馈: https://github.com/X33834/awesome-ai-devkit/issues
• 变更详情: CHANGELOG.md