docs-sync

name	docs-sync
description	当 QuantSage 任务修改代码、数据库 schema、API 契约、策略规则、数据源、调度任务、前端页面、部署配置或验证方式时，用于同步项目文档、实施计划和长期规则。

docs-sync

目标

在 QuantSage 的实现或方案调整完成后，检查本次改动是否需要同步更新文档，避免代码、数据库、API、策略和执行计划脱节。

重点同步对象：

• docs/superpowers/specs/ai_stock_analysis_database_technical_proposal.md
• docs/superpowers/plans/2026-04-27-quantsage-v1-implementation-plan.md
• docs/api/ 下后续新增的接口文档
• docs/architecture/ 下后续新增的运行、部署、架构说明
• README.md
• 仓库根或相关目录下的 AGENTS.md / AGENTS.override.md

触发条件

满足以下任一条件时执行本技能：

• 修改数据库 schema、迁移文件、表字段、索引、TimescaleDB hypertable、pgvector 维度或数据保留策略
• 修改统一 API 响应结构、错误码、toast 文案、分页结构、HTTP 路径、请求/响应 DTO
• 修改数据源行为，包括 sample datasource、Tushare 接入、无 Token 降级、数据质量校验或补数逻辑
• 修改任务调度、任务名称、执行顺序、幂等逻辑、job_run_log 状态语义或手动任务 API
• 修改指标计算、事件标签、固定策略信号、评分模型、回测默认语义或后续 DSL 边界
• 修改前端页面、路由、工作台信息结构、K 线/信号/任务状态展示方式
• 修改 Docker Compose、环境变量、配置文件、Makefile、构建/测试/运行命令
• 任务产生新的长期工程规则、禁止项、验证要求、目录边界或 Agent 协作约定

纯分析、纯问答、未改文件的任务不需要执行。

同步前输入

执行前先明确：

1. 本次改动涉及哪些目录和文件
2. 是否改变运行行为、数据语义或外部契约
3. 是否改变 V1 里程碑、任务顺序或验收标准
4. 已执行哪些验证命令，结果如何
5. 哪些验证未覆盖，是否需要在文档中标注风险

文档映射

按改动类型选择同步目标：

• 数据库 / 数据模型

  • 更新技术方案的“数据模型设计”“数据分层设计”“数据质量设计”
  • 更新 V1 实施计划的数据库 schema、迁移任务和验证关口

• API / 错误码 / DTO

  • 更新技术方案的“API 设计”
  • 更新 V1 实施计划的 API 契约、错误码文件、DTO 文件和接口任务
  • 若已有 docs/api/，同步具体接口文档

• 数据源 / 同步任务

  • 更新技术方案的“数据源设计”“核心业务流程”“任务调度设计”
  • 更新 V1 实施计划的数据源、导入任务、样例数据和冒烟流程

• 指标 / 策略 / 回测

  • 更新技术方案的“指标与买卖点信号设计”“策略规则 DSL 设计”“回测系统设计”
  • 更新 V1 实施计划的指标计算、固定策略、评分模型、回测默认语义

• AI / RAG

  • 更新技术方案的“AI 分析层设计”“公告财报 RAG”
  • 若只是保留表结构、不实现链路，应明确仍属于 V1 范围外或预留能力

• 前端 / 工作台

  • 更新技术方案的“前端功能设计”
  • 更新 V1 实施计划的页面、路由、API client 和构建验证

• 部署 / 配置 / 运行

  • 更新技术方案的“部署架构”“可观测性与运维”
  • 更新 V1 实施计划的 Docker Compose、环境变量、Makefile、local runbook
  • 更新 README.md 或 docs/architecture/ 下运行说明

规则回写

只有当本次改动形成长期规则时，才更新 AGENTS.md / AGENTS.override.md。

可以回写的长期规则包括：

• 新的必须验证命令
• 新的禁止项或高风险操作边界
• 新的目录职责边界
• 新的 API / 错误码 / schema 维护约定
• 新的文档同步映射关系
• 新的 Agent 并行协作或任务拆分约束

不要为了“显得完整”机械修改 Agent 规则文件。

回写内容要求

文档更新至少覆盖以下信息中与本次改动相关的部分：

1. 改动目标
2. 影响范围
3. 核心行为或契约变化
4. 数据库/API/配置/任务/页面的精确变更点
5. 风险、兼容性影响和 V1 范围变化
6. 已执行验证
7. 未覆盖验证和后续建议

避免无效同步

不要做以下事情：

• 只改标题、不补实质内容
• 把文档写成空泛总结
• 代码没有改变契约，却硬改技术方案
• 没有新长期规则，却修改 AGENTS.md
• 忽略 V1 范围外清单，偷偷把后续阶段能力写进 V1 必交付
• 让技术方案、实施计划、README 中的命令或路径互相矛盾

输出要求

完成后，在最终总结中明确列出：

• 本次更新了哪些文档
• 本次是否更新了 AGENTS.md / AGENTS.override.md
• 哪些候选文档判断为无需更新，以及理由
• 已执行的验证命令；如果未验证，说明原因