{"owner":"ZhuLinsen","repo":"daily_stock_analysis","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\n本文件用于约束本仓库的默认开发流程，目标是减少重复沟通、减少返工，并让改动和当前项目结构保持一致。\n\n如果本文件与仓库中的脚本、工作流、代码现状不一致，以实际可执行内容为准，并在相关改动中顺手修正文档，避免规则继续漂移。\n\n## 1. 硬规则\n\n- 遵循现有目录边界：\n  - 后端逻辑优先放在 `src/`、`data_provider/`、`api/`、`bot/`\n  - Web 前端改动在 `apps/dsa-web/`\n  - 桌面端改动在 `apps/dsa-desktop/`\n  - 部署与流水线改动在 `scripts/`、`.github/workflows/`、`docker/`\n- 未经明确确认，不执行 `git commit`、`git tag`、`git push`。\n- commit message 使用英文，不添加 `Co-Authored-By`。\n- 不写死密钥、账号、路径、模型名、端口或环境差异逻辑。\n- 优先复用现有模块、配置入口、脚本和测试，不新增平行实现。\n- 默认稳定性优先于“顺手优化”；非当前任务直接需要的重构、抽象和基础设施迁移一律克制。\n- 新增配置项时，必须同步更新 `.env.example` 和相关文档。\n- 涉及用户可见能力、CLI/API 行为、部署方式、通知方式、报告结构变化时，必须同步更新相关文档与 `docs/CHANGELOG.md`。\n- 修改报告格式、报告渲染效果或 Web UI 界面时，PR 描述必须附受影响报告 / 页面截图；涉及前后差异时优先附前后对比，无法截图时说明原因与替代可视证据。\n- Issue / PR 过程截图、审查截图、一次性验收截图和临时可视证据不得作为仓库文件合入；应放在 PR 描述、PR 评论、GitHub 附件、Actions artifact 或外部可访问证据链接中。产品长期文档确需保留的示意图除外，但文件名和文档语义必须脱离具体 issue / PR 编号。\n- `docs/CHANGELOG.md` 的 `[Unreleased]` 段使用**扁平格式**：每条独立一行，格式为 `- [类型] 描述`，类型取值：`新功能`/`改进`/`修复`/`文档`/`测试`/`chore`；**禁止在 `[Unreleased]` 内新增 `### 类目标题`**，以减少并发 PR 的 merge 冲突。发版时由 maintainer 汇总整理成带标题的正式格式。\n- `README.md` 只用于项目定位、核心能力总览、快速开始、主要入口、赞助/合作等首页级信息；非必要不更新 README，避免持续膨胀。\n- 更细的模块行为、页面交互、专题配置、排障说明、字段契约、实现语义和边界条件，优先更新对应 `docs/*.md` 或专题文档，不写入 README。\n- 变更中英双语文档之一时，需评估另一份是否需要同步；若未同步，交付说明里要写明原因。\n- 注释、docstring、日志文案以清晰准确为准，不强制要求英文，但应与文件语境保持一致。\n\n## 1.1 PR 标题规范（非阻断建议）\n\n- 推荐使用 `<类型>: <修改内容>` 作为 PR 标题，例如 `fix: 修复大盘分析历史记录丢失`，优先类型为 `fix`/`feat`/`refactor`/`docs`/`chore`/`test`/`ci`。\n- 标题应描述实际变更内容，建议不添加 `[codex]`、`codex`、`autocode`、`copilot` 或其他工具/agent 来源前缀。\n- 该规范仅用于协作可读性与一致性提示，不应单独作为 review process blocker。\n\n## 1.2 贡献质量底线\n\n- 本仓库不接受以堆叠代码量、扩大 diff 面、补丁式响应 review 来替代真实设计收敛的 PR。\n- 贡献质量以是否解决明确问题、是否最小化影响面、是否保持现有契约一致、是否覆盖真实风险路径为准；不以新增行数、文件数量、功能宣传或“看起来完整”为准。\n- 请不要把本仓库当作低成本试验场、简历展示场或 contribution farming 场所。任何 PR 都必须证明作者理解当前系统契约，并完成基本自审、集成和验证。\n- 使用 AI 辅助开发本身不是问题；问题是提交 AI 生成后未经人工语义审查、未验证、未收敛的代码。此类 PR 会按低质量提交处理。\n- review 反馈后，不接受只在被指出的位置追加局部 patch。作者必须重新检查同一业务语义涉及的所有入口、配置、测试、文档、workflow 和用户可见路径。\n- 如果一个 PR 在多轮 review 后仍持续出现同类契约漂移、重复 fallback、测试绕过真实风险层、PR body 与实际 diff 不一致等问题，维护者可以要求关闭重做，而不是继续逐点 review。\n\n## 2. AI 协作资产治理\n\n- `AGENTS.md` 是仓库内 AI 协作规则的唯一真源。\n- `CLAUDE.md` 必须是指向 `AGENTS.md` 的软链接，用于兼容 Claude 生态。\n- `.github/copilot-instructions.md` 与 `.github/instructions/*.instructions.md` 是 GitHub Copilot / Coding Agent 的镜像或分层补充；若与本文件冲突，以 `AGENTS.md` 为准。\n- 仓库协作 skill 存放在 `.claude/skills/`，分析产物存放在 `.claude/reviews/`；前者可以入库，后者默认视为本地产物。\n- 根目录 `SKILL.md` 与 `docs/openclaw-skill-integration.md` 属于产品或外部集成说明，不是仓库协作规则真源。\n- 若未来新增 `.agents/skills/` 或其他 agent 专用目录，必须先明确单一真源，再通过脚本或镜像同步；禁止手工长期维护多份同义内容。\n- 修改 AI 协作治理资产时，执行：\n\n```bash\npython scripts/check_ai_assets.py\n```\n\n## 3. 仓库速览\n\n- 项目定位：股票智能分析系统，覆盖 A 股、港股、美股。\n- 主流程：抓取数据 -> 技术分析/新闻检索 -> LLM 分析 -> 生成报告 -> 通知推送。\n- 关键入口：\n  - `main.py`：分析任务主入口\n  - `server.py`：FastAPI 服务入口\n  - `apps/dsa-web/`：Web 前端\n  - `apps/dsa-desktop/`：Electron 桌面端\n  - `.github/workflows/`：CI、发布、每日任务\n- 核心职责：\n  - `src/core/`：主流程编排\n  - `src/services/`：业务服务层\n  - `src/repositories/`：数据访问层\n  - `src/reports/`：报告生成\n  - `src/schemas/`：Schema / 数据结构\n  - `data_provider/`：多数据源适配与 fallback\n  - `api/`：FastAPI API\n  - `bot/`：机器人接入\n  - `scripts/`：本地脚本\n  - `.github/scripts/`：GitHub 自动化脚本\n  - `tests/`：pytest 测试\n  - `docs/`：文档与说明\n\n## 4. 常用命令\n\n### 运行应用\n\n```bash\npython main.py\npython main.py --debug\npython main.py --dry-run\npython main.py --stocks 600519,hk00700,AAPL\npython main.py --market-review\npython main.py --schedule\npython main.py --serve\npython main.py --serve-only\nuvicorn server:app --reload --host 0.0.0.0 --port 8000\n```\n\n### 后端验证\n\n```bash\npip install -r requirements.txt\npip install flake8 pytest\n./scripts/ci_gate.sh\npython -m pytest -m \"not network\"\npython -m py_compile <changed_python_files>\n```\n\n### Web / Desktop\n\n```bash\ncd apps/dsa-web\nnpm ci\nnpm run lint\nnpm run build\n\ncd ../dsa-desktop\nnpm install\nnpm run build\n```\n\n### PR / CI 证据\n\n```bash\ngh pr view <pr_number>\ngh pr checks <pr_number>\ngh run view <run_id> --log-failed\n```\n\n## 5. 默认工作流\n\n1. 先判断任务类型：`fix / feat / refactor / docs / chore / test / review`\n2. 先读现有实现、配置、测试、脚本、工作流和文档，再动手修改。\n3. 识别改动边界：后端 / API / Web / Desktop / Workflow / Docs / AI 协作资产。\n4. 先判断是否命中高风险区域：配置语义、API / Schema、数据源 fallback、报告结构、认证、调度、发布流程、桌面端启动链路。\n5. 只做和当前任务直接相关的最小改动，不顺手夹带无关重构。\n6. 如果发现文档、脚本、工作流描述不一致，优先信任实际代码与工作流，再决定是否顺手修正文档。\n7. 改完后按下面的验证矩阵执行检查。\n8. 最终交付默认要说明：\n   - 改了什么\n   - 为什么这么改\n   - 验证情况\n   - 未验证项\n   - 风险点\n   - 回滚方式\n\n## 6. 验证矩阵\n\n### CI 覆盖原则\n\n当前仓库 CI 主要包含：\n\n| 检查项 | 来源 | 说明 | 是否阻断 |\n| --- | --- | --- | --- |\n| `ai-governance` | `.github/workflows/ci.yml` | 校验 `AGENTS.md` / `CLAUDE.md` / `.github` 指令 / `.claude/skills` 关系 | 是 |\n| `backend-gate` | `.github/workflows/ci.yml` | 执行 `./scripts/ci_gate.sh` | 是 |\n| `docker-build` | `.github/workflows/ci.yml` | Docker 构建与关键模块导入 smoke | 是 |\n| `web-gate` | `.github/workflows/ci.yml` | 前端改动时执行 `npm run lint` + `npm run build` | 是（触发时） |\n| `network-smoke` | `.github/workflows/network-smoke.yml` | `pytest -m network` + `scripts/test.sh quick` | 否，观测项 |\n| `pr-review` | `.github/workflows/pr-review.yml` | PR 静态检查 + AI 审查 + 自动标签 | 否，辅助项 |\n\n若 PR 上已有对应 CI 结果，可直接引用 CI 结论；若 CI 未覆盖改动面，或本地与 CI 环境差异较大，需要补充说明本地验证与缺口。\n\n### 按改动面执行\n\n- Python 后端改动：\n  - 适用范围：`main.py`、`src/`、`data_provider/`、`api/`、`bot/`、`tests/`\n  - 优先执行：`./scripts/ci_gate.sh`\n  - 最低要求：`python -m py_compile <changed_python_files>`\n  - 若影响 API、任务编排、报告生成、通知发送、数据源 fallback、认证、调度，交付说明中要写明是否覆盖了对应路径。\n\n- Web 前端改动：\n  - 适用范围：`apps/dsa-web/`\n  - 默认执行：`cd apps/dsa-web && npm ci && npm run lint && npm run build`\n  - 若涉及 API 联调、路由、状态管理、Markdown/图表渲染或认证状态，交付说明中要明确说明联动面和未覆盖风险。\n\n- 桌面端改动：\n  - 适用范围：`apps/dsa-desktop/`、`scripts/run-desktop.ps1`、`scripts/build-desktop*.ps1`、`scripts/build-*.sh`、`docs/desktop-package.md`\n  - 默认执行：先构建 Web，再构建桌面端\n  - 如受平台限制未能完整验证，需要明确说明是否验证了 Web 构建产物、Electron 构建以及 Release 工作流影响。\n\n- API / Schema / 认证联动改动：\n  - 适用范围：`api/**`、`src/schemas/**`、`src/services/**`、`apps/dsa-web/**`、`apps/dsa-desktop/**`\n  - 至少覆盖对应后端验证 + 受影响客户端构建验证。\n  - 若涉及登录、Cookie、会话、轮询状态、字段增删或枚举变化，必须明确写出兼容性影响。\n\n- 文档与治理文件改动：\n  - 适用范围：`README.md`、`docs/**`、`AGENTS.md`、`.github/copilot-instructions.md`、`.github/instructions/**`、`.claude/skills/**`\n  - 不强制代码测试。\n  - 需确认命令、配置项、文件名、工作流名称与实际仓库一致。\n  - 改动 AI 协作治理资产时，执行 `python scripts/check_ai_assets.py`。\n\n- 工作流 / 脚本 / Docker 改动：\n  - 适用范围：`.github/**`、`scripts/**`、`docker/**`\n  - 运行最接近改动面的本地验证。\n  - 交付时说明影响了哪条流水线、发布路径或部署路径。\n  - 若未执行 Docker / GitHub Actions 相关验证，明确说明原因与潜在风险。\n\n- 网络或三方依赖相关改动：\n  - 先跑离线或确定性检查。\n  - 优先确认 timeout、retry、fallback、异常文案、降级路径是否仍然成立。\n  - 若未执行在线验证，必须明确写出原因。\n\n## 7. 稳定性护栏\n\n- 配置与运行入口：\n  - 修改 `.env` 语义、默认值、CLI 参数、服务启动方式、调度语义时，要同时评估本地运行、Docker、GitHub Actions、API、Web、Desktop 的影响。\n  - 新配置优先做到“不配置也可运行，配置后增强能力”，避免叠加开关和互斥模式。\n\n- 数据源与 fallback：\n  - 修改 `data_provider/` 时，要关注数据源优先级、失败降级、字段标准化、缓存与超时策略。\n  - 单一数据源失败不应拖垮整个分析流程，除非需求明确要求 fail-fast。\n\n- API / Web / Desktop 兼容：\n  - 改 API / Schema / 认证 / 报告载荷时，要同时检查后端、Web、Desktop 的兼容性。\n  - 默认优先追加字段、保留旧字段或提供兼容层，避免无提示破坏现有客户端。\n\n- 报告 / Prompt / 通知：\n  - 修改报告结构、Prompt、提取器、通知模板、机器人链路时，要检查上游输入与下游消费方是否仍兼容。\n  - 单一通知渠道失败不应拖垮整个分析主流程，除非需求明确要求 fail-fast。\n  - 修改 `src/services/image_stock_extractor.py` 中 `EXTRACT_PROMPT` 时，要在 PR 描述中附完整最新 prompt。\n\n- 工作流 / 发布 / 打包：\n  - 修改自动 tag、Release、Docker 发布、日常分析或桌面端打包流程时，要评估触发条件、产物路径、权限边界和回滚方式。\n  - 自动 tag 默认保持 opt-in：只有 commit title 含 `#patch`、`#minor`、`#major` 才触发版本号更新，除非需求明确要求改变发布策略。\n\n## 8. Issue / PR / Skill 工作流\n\n- 仓库内已有以下 skill，可优先复用：\n  - `.claude/skills/analyze-issue/SKILL.md`\n  - `.claude/skills/analyze-pr/SKILL.md`\n  - `.claude/skills/fix-issue/SKILL.md`\n- 如果任务明确是 issue 分析、PR 审查、issue 修复，优先按对应 skill 执行，并将产物保存到 `.claude/reviews/`。\n- skill 中的命令、模板、验证顺序和交付结构必须与 `AGENTS.md` 保持一致。\n- 每次进行 PR 创建 / 更新、PR 审查或 issue 分析前，必须先同步最新代码基线：先检查工作区状态并执行 `git fetch --all --prune`；若工作区干净且当前分支可 fast-forward，则执行 `git pull --ff-only`。如存在本地改动、冲突状态、未跟踪风险文件或无法 fast-forward，不得强行切分支、stash、reset 或覆盖本地状态；PR 审查 / issue 分析可改用已 fetch 的远端 refs/PR head 做分析，并在分析文档中明确记录未更新本地工作树的原因、当前本地 HEAD 与使用的远端基线；PR 创建 / 更新应先说明当前分支与目标基线差异，必要时请求用户确认 rebase、merge 或继续基于当前分支推进。\n- skill 默认优先读取 CI / 工作流证据，再决定是否补本地验证。\n- 除上述 PR 创建 / 更新、PR 审查 / issue 分析的安全 fast-forward 同步外，skill 不得默认执行 `git pull`、`git push`、`git tag`、`gh pr create` 等会改变远端或当前分支状态的操作；这些操作必须要求用户确认。\n- PR 审查默认顺序：\n  1. 必要性\n  2. 关联性\n  3. 标题建议（`<类型>: <修改内容>`，且不含工具/agent 前缀；不作为硬性阻断项）\n  4. 描述完整性（对照 `.github/PULL_REQUEST_TEMPLATE.md`）\n  5. 验证证据\n  6. 实现正确性\n  7. 合入判定\n- 对 `fix` 类 PR，必须说明：原问题、根因、修复点、回归风险。\n- 合入阻断条件：\n  - 正确性或安全性问题\n  - 阻断型 CI 未通过\n  - PR 描述与实际改动内容实质性矛盾\n  - 缺少回滚方案\n  - 反复出现未收敛的契约漂移、补丁堆叠或验证证据失真\n\n## 8.1 Review 反馈处理与补丁堆叠禁止\n\n当你处理 review 反馈时，禁止只在 reviewer 点名的位置追加局部 patch 后声称“已全部修复”。你必须先重新理解 reviewer 指出的业务契约，再检查同一语义涉及的所有入口、配置、测试、文档、workflow 和用户可见路径。\n\n收到 review 反馈后，必须按以下顺序处理：\n\n1. 逐条列出 reviewer 指出的原问题。\n2. 说明根因，不能只描述“改了哪几行”。\n3. 找出同一语义影响的所有相关路径，例如 runtime、API/Web、CLI、diagnostics、workflow、docs、tests。\n4. 修复完整契约，而不是只修复当前失败测试或当前评论行。\n5. 补充能覆盖 reviewer 反例的回归测试、最终入口验证，或明确说明无法验证的原因。\n6. 同步更新 PR body，保证 scope、验证结果、兼容性、风险和回滚方案与当前 head 一致。\n\n如果你无法完成上述收敛，不要继续堆叠补丁，不要声称 ready for merge。应主动说明当前 PR 需要拆分、关闭重做，或请求维护者确认新的最小范围。\n\n以下行为会被视为低质量 PR：\n\n- 用 broad fallback、静默降级、`return False/None/[]` 掩盖不清晰的契约。\n- 测试 mock 掉真实风险层，只证明局部实现通过。\n- CI 通过后声称问题已关闭，但没有覆盖 reviewer 指出的反例。\n- PR body 与实际 diff、验证结果或兼容风险不一致。\n- review 后继续追加零散 patch，而不是重新收敛完整语义。\n- 同一业务语义在 runtime、Web/API、docs、workflow、tests 中表现不一致。\n\nCI 通过只能说明自动检查通过，不能替代人工语义收敛，也不能单独证明 reviewer 指出的反例已经关闭。\n\n## 9. 交付与发布\n\n- 默认交付结构：\n  - `改了什么`\n  - `为什么这么改`\n  - `验证情况`\n  - `未验证项`\n  - `风险点`\n  - `回滚方式`\n- 如果是 `docs` 任务，可直接写：`Docs only, tests not run`，但仍需说明是否核对了命令和文件名。\n- 自动 tag 默认不触发，只有 commit title 包含 `#patch`、`#minor`、`#major` 才会触发版本号更新。\n- 手动打 tag 必须使用 annotated tag。\n- 用户可见变更优先通过 PR 合入，并补齐 label 与验证说明。\n"},"files":{"AGENTS.md":"# AGENTS.md\n\n本文件用于约束本仓库的默认开发流程，目标是减少重复沟通、减少返工，并让改动和当前项目结构保持一致。\n\n如果本文件与仓库中的脚本、工作流、代码现状不一致，以实际可执行内容为准，并在相关改动中顺手修正文档，避免规则继续漂移。\n\n## 1. 硬规则\n\n- 遵循现有目录边界：\n  - 后端逻辑优先放在 `src/`、`data_provider/`、`api/`、`bot/`\n  - Web 前端改动在 `apps/dsa-web/`\n  - 桌面端改动在 `apps/dsa-desktop/`\n  - 部署与流水线改动在 `scripts/`、`.github/workflows/`、`docker/`\n- 未经明确确认，不执行 `git commit`、`git tag`、`git push`。\n- commit message 使用英文，不添加 `Co-Authored-By`。\n- 不写死密钥、账号、路径、模型名、端口或环境差异逻辑。\n- 优先复用现有模块、配置入口、脚本和测试，不新增平行实现。\n- 默认稳定性优先于“顺手优化”；非当前任务直接需要的重构、抽象和基础设施迁移一律克制。\n- 新增配置项时，必须同步更新 `.env.example` 和相关文档。\n- 涉及用户可见能力、CLI/API 行为、部署方式、通知方式、报告结构变化时，必须同步更新相关文档与 `docs/CHANGELOG.md`。\n- 修改报告格式、报告渲染效果或 Web UI 界面时，PR 描述必须附受影响报告 / 页面截图；涉及前后差异时优先附前后对比，无法截图时说明原因与替代可视证据。\n- Issue / PR 过程截图、审查截图、一次性验收截图和临时可视证据不得作为仓库文件合入；应放在 PR 描述、PR 评论、GitHub 附件、Actions artifact 或外部可访问证据链接中。产品长期文档确需保留的示意图除外，但文件名和文档语义必须脱离具体 issue / PR 编号。\n- `docs/CHANGELOG.md` 的 `[Unreleased]` 段使用**扁平格式**：每条独立一行，格式为 `- [类型] 描述`，类型取值：`新功能`/`改进`/`修复`/`文档`/`测试`/`chore`；**禁止在 `[Unreleased]` 内新增 `### 类目标题`**，以减少并发 PR 的 merge 冲突。发版时由 maintainer 汇总整理成带标题的正式格式。\n- `README.md` 只用于项目定位、核心能力总览、快速开始、主要入口、赞助/合作等首页级信息；非必要不更新 README，避免持续膨胀。\n- 更细的模块行为、页面交互、专题配置、排障说明、字段契约、实现语义和边界条件，优先更新对应 `docs/*.md` 或专题文档，不写入 README。\n- 变更中英双语文档之一时，需评估另一份是否需要同步；若未同步，交付说明里要写明原因。\n- 注释、docstring、日志文案以清晰准确为准，不强制要求英文，但应与文件语境保持一致。\n\n## 1.1 PR 标题规范（非阻断建议）\n\n- 推荐使用 `<类型>: <修改内容>` 作为 PR 标题，例如 `fix: 修复大盘分析历史记录丢失`，优先类型为 `fix`/`feat`/`refactor`/`docs`/`chore`/`test`/`ci`。\n- 标题应描述实际变更内容，建议不添加 `[codex]`、`codex`、`autocode`、`copilot` 或其他工具/agent 来源前缀。\n- 该规范仅用于协作可读性与一致性提示，不应单独作为 review process blocker。\n\n## 1.2 贡献质量底线\n\n- 本仓库不接受以堆叠代码量、扩大 diff 面、补丁式响应 review 来替代真实设计收敛的 PR。\n- 贡献质量以是否解决明确问题、是否最小化影响面、是否保持现有契约一致、是否覆盖真实风险路径为准；不以新增行数、文件数量、功能宣传或“看起来完整”为准。\n- 请不要把本仓库当作低成本试验场、简历展示场或 contribution farming 场所。任何 PR 都必须证明作者理解当前系统契约，并完成基本自审、集成和验证。\n- 使用 AI 辅助开发本身不是问题；问题是提交 AI 生成后未经人工语义审查、未验证、未收敛的代码。此类 PR 会按低质量提交处理。\n- review 反馈后，不接受只在被指出的位置追加局部 patch。作者必须重新检查同一业务语义涉及的所有入口、配置、测试、文档、workflow 和用户可见路径。\n- 如果一个 PR 在多轮 review 后仍持续出现同类契约漂移、重复 fallback、测试绕过真实风险层、PR body 与实际 diff 不一致等问题，维护者可以要求关闭重做，而不是继续逐点 review。\n\n## 2. AI 协作资产治理\n\n- `AGENTS.md` 是仓库内 AI 协作规则的唯一真源。\n- `CLAUDE.md` 必须是指向 `AGENTS.md` 的软链接，用于兼容 Claude 生态。\n- `.github/copilot-instructions.md` 与 `.github/instructions/*.instructions.md` 是 GitHub Copilot / Coding Agent 的镜像或分层补充；若与本文件冲突，以 `AGENTS.md` 为准。\n- 仓库协作 skill 存放在 `.claude/skills/`，分析产物存放在 `.claude/reviews/`；前者可以入库，后者默认视为本地产物。\n- 根目录 `SKILL.md` 与 `docs/openclaw-skill-integration.md` 属于产品或外部集成说明，不是仓库协作规则真源。\n- 若未来新增 `.agents/skills/` 或其他 agent 专用目录，必须先明确单一真源，再通过脚本或镜像同步；禁止手工长期维护多份同义内容。\n- 修改 AI 协作治理资产时，执行：\n\n```bash\npython scripts/check_ai_assets.py\n```\n\n## 3. 仓库速览\n\n- 项目定位：股票智能分析系统，覆盖 A 股、港股、美股。\n- 主流程：抓取数据 -> 技术分析/新闻检索 -> LLM 分析 -> 生成报告 -> 通知推送。\n- 关键入口：\n  - `main.py`：分析任务主入口\n  - `server.py`：FastAPI 服务入口\n  - `apps/dsa-web/`：Web 前端\n  - `apps/dsa-desktop/`：Electron 桌面端\n  - `.github/workflows/`：CI、发布、每日任务\n- 核心职责：\n  - `src/core/`：主流程编排\n  - `src/services/`：业务服务层\n  - `src/repositories/`：数据访问层\n  - `src/reports/`：报告生成\n  - `src/schemas/`：Schema / 数据结构\n  - `data_provider/`：多数据源适配与 fallback\n  - `api/`：FastAPI API\n  - `bot/`：机器人接入\n  - `scripts/`：本地脚本\n  - `.github/scripts/`：GitHub 自动化脚本\n  - `tests/`：pytest 测试\n  - `docs/`：文档与说明\n\n## 4. 常用命令\n\n### 运行应用\n\n```bash\npython main.py\npython main.py --debug\npython main.py --dry-run\npython main.py --stocks 600519,hk00700,AAPL\npython main.py --market-review\npython main.py --schedule\npython main.py --serve\npython main.py --serve-only\nuvicorn server:app --reload --host 0.0.0.0 --port 8000\n```\n\n### 后端验证\n\n```bash\npip install -r requirements.txt\npip install flake8 pytest\n./scripts/ci_gate.sh\npython -m pytest -m \"not network\"\npython -m py_compile <changed_python_files>\n```\n\n### Web / Desktop\n\n```bash\ncd apps/dsa-web\nnpm ci\nnpm run lint\nnpm run build\n\ncd ../dsa-desktop\nnpm install\nnpm run build\n```\n\n### PR / CI 证据\n\n```bash\ngh pr view <pr_number>\ngh pr checks <pr_number>\ngh run view <run_id> --log-failed\n```\n\n## 5. 默认工作流\n\n1. 先判断任务类型：`fix / feat / refactor / docs / chore / test / review`\n2. 先读现有实现、配置、测试、脚本、工作流和文档，再动手修改。\n3. 识别改动边界：后端 / API / Web / Desktop / Workflow / Docs / AI 协作资产。\n4. 先判断是否命中高风险区域：配置语义、API / Schema、数据源 fallback、报告结构、认证、调度、发布流程、桌面端启动链路。\n5. 只做和当前任务直接相关的最小改动，不顺手夹带无关重构。\n6. 如果发现文档、脚本、工作流描述不一致，优先信任实际代码与工作流，再决定是否顺手修正文档。\n7. 改完后按下面的验证矩阵执行检查。\n8. 最终交付默认要说明：\n   - 改了什么\n   - 为什么这么改\n   - 验证情况\n   - 未验证项\n   - 风险点\n   - 回滚方式\n\n## 6. 验证矩阵\n\n### CI 覆盖原则\n\n当前仓库 CI 主要包含：\n\n| 检查项 | 来源 | 说明 | 是否阻断 |\n| --- | --- | --- | --- |\n| `ai-governance` | `.github/workflows/ci.yml` | 校验 `AGENTS.md` / `CLAUDE.md` / `.github` 指令 / `.claude/skills` 关系 | 是 |\n| `backend-gate` | `.github/workflows/ci.yml` | 执行 `./scripts/ci_gate.sh` | 是 |\n| `docker-build` | `.github/workflows/ci.yml` | Docker 构建与关键模块导入 smoke | 是 |\n| `web-gate` | `.github/workflows/ci.yml` | 前端改动时执行 `npm run lint` + `npm run build` | 是（触发时） |\n| `network-smoke` | `.github/workflows/network-smoke.yml` | `pytest -m network` + `scripts/test.sh quick` | 否，观测项 |\n| `pr-review` | `.github/workflows/pr-review.yml` | PR 静态检查 + AI 审查 + 自动标签 | 否，辅助项 |\n\n若 PR 上已有对应 CI 结果，可直接引用 CI 结论；若 CI 未覆盖改动面，或本地与 CI 环境差异较大，需要补充说明本地验证与缺口。\n\n### 按改动面执行\n\n- Python 后端改动：\n  - 适用范围：`main.py`、`src/`、`data_provider/`、`api/`、`bot/`、`tests/`\n  - 优先执行：`./scripts/ci_gate.sh`\n  - 最低要求：`python -m py_compile <changed_python_files>`\n  - 若影响 API、任务编排、报告生成、通知发送、数据源 fallback、认证、调度，交付说明中要写明是否覆盖了对应路径。\n\n- Web 前端改动：\n  - 适用范围：`apps/dsa-web/`\n  - 默认执行：`cd apps/dsa-web && npm ci && npm run lint && npm run build`\n  - 若涉及 API 联调、路由、状态管理、Markdown/图表渲染或认证状态，交付说明中要明确说明联动面和未覆盖风险。\n\n- 桌面端改动：\n  - 适用范围：`apps/dsa-desktop/`、`scripts/run-desktop.ps1`、`scripts/build-desktop*.ps1`、`scripts/build-*.sh`、`docs/desktop-package.md`\n  - 默认执行：先构建 Web，再构建桌面端\n  - 如受平台限制未能完整验证，需要明确说明是否验证了 Web 构建产物、Electron 构建以及 Release 工作流影响。\n\n- API / Schema / 认证联动改动：\n  - 适用范围：`api/**`、`src/schemas/**`、`src/services/**`、`apps/dsa-web/**`、`apps/dsa-desktop/**`\n  - 至少覆盖对应后端验证 + 受影响客户端构建验证。\n  - 若涉及登录、Cookie、会话、轮询状态、字段增删或枚举变化，必须明确写出兼容性影响。\n\n- 文档与治理文件改动：\n  - 适用范围：`README.md`、`docs/**`、`AGENTS.md`、`.github/copilot-instructions.md`、`.github/instructions/**`、`.claude/skills/**`\n  - 不强制代码测试。\n  - 需确认命令、配置项、文件名、工作流名称与实际仓库一致。\n  - 改动 AI 协作治理资产时，执行 `python scripts/check_ai_assets.py`。\n\n- 工作流 / 脚本 / Docker 改动：\n  - 适用范围：`.github/**`、`scripts/**`、`docker/**`\n  - 运行最接近改动面的本地验证。\n  - 交付时说明影响了哪条流水线、发布路径或部署路径。\n  - 若未执行 Docker / GitHub Actions 相关验证，明确说明原因与潜在风险。\n\n- 网络或三方依赖相关改动：\n  - 先跑离线或确定性检查。\n  - 优先确认 timeout、retry、fallback、异常文案、降级路径是否仍然成立。\n  - 若未执行在线验证，必须明确写出原因。\n\n## 7. 稳定性护栏\n\n- 配置与运行入口：\n  - 修改 `.env` 语义、默认值、CLI 参数、服务启动方式、调度语义时，要同时评估本地运行、Docker、GitHub Actions、API、Web、Desktop 的影响。\n  - 新配置优先做到“不配置也可运行，配置后增强能力”，避免叠加开关和互斥模式。\n\n- 数据源与 fallback：\n  - 修改 `data_provider/` 时，要关注数据源优先级、失败降级、字段标准化、缓存与超时策略。\n  - 单一数据源失败不应拖垮整个分析流程，除非需求明确要求 fail-fast。\n\n- API / Web / Desktop 兼容：\n  - 改 API / Schema / 认证 / 报告载荷时，要同时检查后端、Web、Desktop 的兼容性。\n  - 默认优先追加字段、保留旧字段或提供兼容层，避免无提示破坏现有客户端。\n\n- 报告 / Prompt / 通知：\n  - 修改报告结构、Prompt、提取器、通知模板、机器人链路时，要检查上游输入与下游消费方是否仍兼容。\n  - 单一通知渠道失败不应拖垮整个分析主流程，除非需求明确要求 fail-fast。\n  - 修改 `src/services/image_stock_extractor.py` 中 `EXTRACT_PROMPT` 时，要在 PR 描述中附完整最新 prompt。\n\n- 工作流 / 发布 / 打包：\n  - 修改自动 tag、Release、Docker 发布、日常分析或桌面端打包流程时，要评估触发条件、产物路径、权限边界和回滚方式。\n  - 自动 tag 默认保持 opt-in：只有 commit title 含 `#patch`、`#minor`、`#major` 才触发版本号更新，除非需求明确要求改变发布策略。\n\n## 8. Issue / PR / Skill 工作流\n\n- 仓库内已有以下 skill，可优先复用：\n  - `.claude/skills/analyze-issue/SKILL.md`\n  - `.claude/skills/analyze-pr/SKILL.md`\n  - `.claude/skills/fix-issue/SKILL.md`\n- 如果任务明确是 issue 分析、PR 审查、issue 修复，优先按对应 skill 执行，并将产物保存到 `.claude/reviews/`。\n- skill 中的命令、模板、验证顺序和交付结构必须与 `AGENTS.md` 保持一致。\n- 每次进行 PR 创建 / 更新、PR 审查或 issue 分析前，必须先同步最新代码基线：先检查工作区状态并执行 `git fetch --all --prune`；若工作区干净且当前分支可 fast-forward，则执行 `git pull --ff-only`。如存在本地改动、冲突状态、未跟踪风险文件或无法 fast-forward，不得强行切分支、stash、reset 或覆盖本地状态；PR 审查 / issue 分析可改用已 fetch 的远端 refs/PR head 做分析，并在分析文档中明确记录未更新本地工作树的原因、当前本地 HEAD 与使用的远端基线；PR 创建 / 更新应先说明当前分支与目标基线差异，必要时请求用户确认 rebase、merge 或继续基于当前分支推进。\n- skill 默认优先读取 CI / 工作流证据，再决定是否补本地验证。\n- 除上述 PR 创建 / 更新、PR 审查 / issue 分析的安全 fast-forward 同步外，skill 不得默认执行 `git pull`、`git push`、`git tag`、`gh pr create` 等会改变远端或当前分支状态的操作；这些操作必须要求用户确认。\n- PR 审查默认顺序：\n  1. 必要性\n  2. 关联性\n  3. 标题建议（`<类型>: <修改内容>`，且不含工具/agent 前缀；不作为硬性阻断项）\n  4. 描述完整性（对照 `.github/PULL_REQUEST_TEMPLATE.md`）\n  5. 验证证据\n  6. 实现正确性\n  7. 合入判定\n- 对 `fix` 类 PR，必须说明：原问题、根因、修复点、回归风险。\n- 合入阻断条件：\n  - 正确性或安全性问题\n  - 阻断型 CI 未通过\n  - PR 描述与实际改动内容实质性矛盾\n  - 缺少回滚方案\n  - 反复出现未收敛的契约漂移、补丁堆叠或验证证据失真\n\n## 8.1 Review 反馈处理与补丁堆叠禁止\n\n当你处理 review 反馈时，禁止只在 reviewer 点名的位置追加局部 patch 后声称“已全部修复”。你必须先重新理解 reviewer 指出的业务契约，再检查同一语义涉及的所有入口、配置、测试、文档、workflow 和用户可见路径。\n\n收到 review 反馈后，必须按以下顺序处理：\n\n1. 逐条列出 reviewer 指出的原问题。\n2. 说明根因，不能只描述“改了哪几行”。\n3. 找出同一语义影响的所有相关路径，例如 runtime、API/Web、CLI、diagnostics、workflow、docs、tests。\n4. 修复完整契约，而不是只修复当前失败测试或当前评论行。\n5. 补充能覆盖 reviewer 反例的回归测试、最终入口验证，或明确说明无法验证的原因。\n6. 同步更新 PR body，保证 scope、验证结果、兼容性、风险和回滚方案与当前 head 一致。\n\n如果你无法完成上述收敛，不要继续堆叠补丁，不要声称 ready for merge。应主动说明当前 PR 需要拆分、关闭重做，或请求维护者确认新的最小范围。\n\n以下行为会被视为低质量 PR：\n\n- 用 broad fallback、静默降级、`return False/None/[]` 掩盖不清晰的契约。\n- 测试 mock 掉真实风险层，只证明局部实现通过。\n- CI 通过后声称问题已关闭，但没有覆盖 reviewer 指出的反例。\n- PR body 与实际 diff、验证结果或兼容风险不一致。\n- review 后继续追加零散 patch，而不是重新收敛完整语义。\n- 同一业务语义在 runtime、Web/API、docs、workflow、tests 中表现不一致。\n\nCI 通过只能说明自动检查通过，不能替代人工语义收敛，也不能单独证明 reviewer 指出的反例已经关闭。\n\n## 9. 交付与发布\n\n- 默认交付结构：\n  - `改了什么`\n  - `为什么这么改`\n  - `验证情况`\n  - `未验证项`\n  - `风险点`\n  - `回滚方式`\n- 如果是 `docs` 任务，可直接写：`Docs only, tests not run`，但仍需说明是否核对了命令和文件名。\n- 自动 tag 默认不触发，只有 commit title 包含 `#patch`、`#minor`、`#major` 才会触发版本号更新。\n- 手动打 tag 必须使用 annotated tag。\n- 用户可见变更优先通过 PR 合入，并补齐 label 与验证说明。\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\n本文件用于约束本仓库的默认开发流程，目标是减少重复沟通、减少返工，并让改动和当前项目结构保持一致。\n\n如果本文件与仓库中的脚本、工作流、代码现状不一致，以实际可执行内容为准，并在相关改动中顺手修正文档，避免规则继续漂移。\n\n## 1. 硬规则\n\n- 遵循现有目录边界：\n  - 后端逻辑优先放在 `src/`、`data_provider/`、`api/`、`bot/`\n  - Web 前端改动在 `apps/dsa-web/`\n  - 桌面端改动在 `apps/dsa-desktop/`\n  - 部署与流水线改动在 `scripts/`、`.github/workflows/`、`docker/`\n- 未经明确确认，不执行 `git commit`、`git tag`、`git push`。\n- commit message 使用英文，不添加 `Co-Authored-By`。\n- 不写死密钥、账号、路径、模型名、端口或环境差异逻辑。\n- 优先复用现有模块、配置入口、脚本和测试，不新增平行实现。\n- 默认稳定性优先于“顺手优化”；非当前任务直接需要的重构、抽象和基础设施迁移一律克制。\n- 新增配置项时，必须同步更新 `.env.example` 和相关文档。\n- 涉及用户可见能力、CLI/API 行为、部署方式、通知方式、报告结构变化时，必须同步更新相关文档与 `docs/CHANGELOG.md`。\n- 修改报告格式、报告渲染效果或 Web UI 界面时，PR 描述必须附受影响报告 / 页面截图；涉及前后差异时优先附前后对比，无法截图时说明原因与替代可视证据。\n- Issue / PR 过程截图、审查截图、一次性验收截图和临时可视证据不得作为仓库文件合入；应放在 PR 描述、PR 评论、GitHub 附件、Actions artifact 或外部可访问证据链接中。产品长期文档确需保留的示意图除外，但文件名和文档语义必须脱离具体 issue / PR 编号。\n- `docs/CHANGELOG.md` 的 `[Unreleased]` 段使用**扁平格式**：每条独立一行，格式为 `- [类型] 描述`，类型取值：`新功能`/`改进`/`修复`/`文档`/`测试`/`chore`；**禁止在 `[Unreleased]` 内新增 `### 类目标题`**，以减少并发 PR 的 merge 冲突。发版时由 maintainer 汇总整理成带标题的正式格式。\n- `README.md` 只用于项目定位、核心能力总览、快速开始、主要入口、赞助/合作等首页级信息；非必要不更新 README，避免持续膨胀。\n- 更细的模块行为、页面交互、专题配置、排障说明、字段契约、实现语义和边界条件，优先更新对应 `docs/*.md` 或专题文档，不写入 README。\n- 变更中英双语文档之一时，需评估另一份是否需要同步；若未同步，交付说明里要写明原因。\n- 注释、docstring、日志文案以清晰准确为准，不强制要求英文，但应与文件语境保持一致。\n\n## 1.1 PR 标题规范（非阻断建议）\n\n- 推荐使用 `<类型>: <修改内容>` 作为 PR 标题，例如 `fix: 修复大盘分析历史记录丢失`，优先类型为 `fix`/`feat`/`refactor`/`docs`/`chore`/`test`/`ci`。\n- 标题应描述实际变更内容，建议不添加 `[codex]`、`codex`、`autocode`、`copilot` 或其他工具/agent 来源前缀。\n- 该规范仅用于协作可读性与一致性提示，不应单独作为 review process blocker。\n\n## 1.2 贡献质量底线\n\n- 本仓库不接受以堆叠代码量、扩大 diff 面、补丁式响应 review 来替代真实设计收敛的 PR。\n- 贡献质量以是否解决明确问题、是否最小化影响面、是否保持现有契约一致、是否覆盖真实风险路径为准；不以新增行数、文件数量、功能宣传或“看起来完整”为准。\n- 请不要把本仓库当作低成本试验场、简历展示场或 contribution farming 场所。任何 PR 都必须证明作者理解当前系统契约，并完成基本自审、集成和验证。\n- 使用 AI 辅助开发本身不是问题；问题是提交 AI 生成后未经人工语义审查、未验证、未收敛的代码。此类 PR 会按低质量提交处理。\n- review 反馈后，不接受只在被指出的位置追加局部 patch。作者必须重新检查同一业务语义涉及的所有入口、配置、测试、文档、workflow 和用户可见路径。\n- 如果一个 PR 在多轮 review 后仍持续出现同类契约漂移、重复 fallback、测试绕过真实风险层、PR body 与实际 diff 不一致等问题，维护者可以要求关闭重做，而不是继续逐点 review。\n\n## 2. AI 协作资产治理\n\n- `AGENTS.md` 是仓库内 AI 协作规则的唯一真源。\n- `CLAUDE.md` 必须是指向 `AGENTS.md` 的软链接，用于兼容 Claude 生态。\n- `.github/copilot-instructions.md` 与 `.github/instructions/*.instructions.md` 是 GitHub Copilot / Coding Agent 的镜像或分层补充；若与本文件冲突，以 `AGENTS.md` 为准。\n- 仓库协作 skill 存放在 `.claude/skills/`，分析产物存放在 `.claude/reviews/`；前者可以入库，后者默认视为本地产物。\n- 根目录 `SKILL.md` 与 `docs/openclaw-skill-integration.md` 属于产品或外部集成说明，不是仓库协作规则真源。\n- 若未来新增 `.agents/skills/` 或其他 agent 专用目录，必须先明确单一真源，再通过脚本或镜像同步；禁止手工长期维护多份同义内容。\n- 修改 AI 协作治理资产时，执行：\n\n```bash\npython scripts/check_ai_assets.py\n```\n\n## 3. 仓库速览\n\n- 项目定位：股票智能分析系统，覆盖 A 股、港股、美股。\n- 主流程：抓取数据 -> 技术分析/新闻检索 -> LLM 分析 -> 生成报告 -> 通知推送。\n- 关键入口：\n  - `main.py`：分析任务主入口\n  - `server.py`：FastAPI 服务入口\n  - `apps/dsa-web/`：Web 前端\n  - `apps/dsa-desktop/`：Electron 桌面端\n  - `.github/workflows/`：CI、发布、每日任务\n- 核心职责：\n  - `src/core/`：主流程编排\n  - `src/services/`：业务服务层\n  - `src/repositories/`：数据访问层\n  - `src/reports/`：报告生成\n  - `src/schemas/`：Schema / 数据结构\n  - `data_provider/`：多数据源适配与 fallback\n  - `api/`：FastAPI API\n  - `bot/`：机器人接入\n  - `scripts/`：本地脚本\n  - `.github/scripts/`：GitHub 自动化脚本\n  - `tests/`：pytest 测试\n  - `docs/`：文档与说明\n\n## 4. 常用命令\n\n### 运行应用\n\n```bash\npython main.py\npython main.py --debug\npython main.py --dry-run\npython main.py --stocks 600519,hk00700,AAPL\npython main.py --market-review\npython main.py --schedule\npython main.py --serve\npython main.py --serve-only\nuvicorn server:app --reload --host 0.0.0.0 --port 8000\n```\n\n### 后端验证\n\n```bash\npip install -r requirements.txt\npip install flake8 pytest\n./scripts/ci_gate.sh\npython -m pytest -m \"not network\"\npython -m py_compile <changed_python_files>\n```\n\n### Web / Desktop\n\n```bash\ncd apps/dsa-web\nnpm ci\nnpm run lint\nnpm run build\n\ncd ../dsa-desktop\nnpm install\nnpm run build\n```\n\n### PR / CI 证据\n\n```bash\ngh pr view <pr_number>\ngh pr checks <pr_number>\ngh run view <run_id> --log-failed\n```\n\n## 5. 默认工作流\n\n1. 先判断任务类型：`fix / feat / refactor / docs / chore / test / review`\n2. 先读现有实现、配置、测试、脚本、工作流和文档，再动手修改。\n3. 识别改动边界：后端 / API / Web / Desktop / Workflow / Docs / AI 协作资产。\n4. 先判断是否命中高风险区域：配置语义、API / Schema、数据源 fallback、报告结构、认证、调度、发布流程、桌面端启动链路。\n5. 只做和当前任务直接相关的最小改动，不顺手夹带无关重构。\n6. 如果发现文档、脚本、工作流描述不一致，优先信任实际代码与工作流，再决定是否顺手修正文档。\n7. 改完后按下面的验证矩阵执行检查。\n8. 最终交付默认要说明：\n   - 改了什么\n   - 为什么这么改\n   - 验证情况\n   - 未验证项\n   - 风险点\n   - 回滚方式\n\n## 6. 验证矩阵\n\n### CI 覆盖原则\n\n当前仓库 CI 主要包含：\n\n| 检查项 | 来源 | 说明 | 是否阻断 |\n| --- | --- | --- | --- |\n| `ai-governance` | `.github/workflows/ci.yml` | 校验 `AGENTS.md` / `CLAUDE.md` / `.github` 指令 / `.claude/skills` 关系 | 是 |\n| `backend-gate` | `.github/workflows/ci.yml` | 执行 `./scripts/ci_gate.sh` | 是 |\n| `docker-build` | `.github/workflows/ci.yml` | Docker 构建与关键模块导入 smoke | 是 |\n| `web-gate` | `.github/workflows/ci.yml` | 前端改动时执行 `npm run lint` + `npm run build` | 是（触发时） |\n| `network-smoke` | `.github/workflows/network-smoke.yml` | `pytest -m network` + `scripts/test.sh quick` | 否，观测项 |\n| `pr-review` | `.github/workflows/pr-review.yml` | PR 静态检查 + AI 审查 + 自动标签 | 否，辅助项 |\n\n若 PR 上已有对应 CI 结果，可直接引用 CI 结论；若 CI 未覆盖改动面，或本地与 CI 环境差异较大，需要补充说明本地验证与缺口。\n\n### 按改动面执行\n\n- Python 后端改动：\n  - 适用范围：`main.py`、`src/`、`data_provider/`、`api/`、`bot/`、`tests/`\n  - 优先执行：`./scripts/ci_gate.sh`\n  - 最低要求：`python -m py_compile <changed_python_files>`\n  - 若影响 API、任务编排、报告生成、通知发送、数据源 fallback、认证、调度，交付说明中要写明是否覆盖了对应路径。\n\n- Web 前端改动：\n  - 适用范围：`apps/dsa-web/`\n  - 默认执行：`cd apps/dsa-web && npm ci && npm run lint && npm run build`\n  - 若涉及 API 联调、路由、状态管理、Markdown/图表渲染或认证状态，交付说明中要明确说明联动面和未覆盖风险。\n\n- 桌面端改动：\n  - 适用范围：`apps/dsa-desktop/`、`scripts/run-desktop.ps1`、`scripts/build-desktop*.ps1`、`scripts/build-*.sh`、`docs/desktop-package.md`\n  - 默认执行：先构建 Web，再构建桌面端\n  - 如受平台限制未能完整验证，需要明确说明是否验证了 Web 构建产物、Electron 构建以及 Release 工作流影响。\n\n- API / Schema / 认证联动改动：\n  - 适用范围：`api/**`、`src/schemas/**`、`src/services/**`、`apps/dsa-web/**`、`apps/dsa-desktop/**`\n  - 至少覆盖对应后端验证 + 受影响客户端构建验证。\n  - 若涉及登录、Cookie、会话、轮询状态、字段增删或枚举变化，必须明确写出兼容性影响。\n\n- 文档与治理文件改动：\n  - 适用范围：`README.md`、`docs/**`、`AGENTS.md`、`.github/copilot-instructions.md`、`.github/instructions/**`、`.claude/skills/**`\n  - 不强制代码测试。\n  - 需确认命令、配置项、文件名、工作流名称与实际仓库一致。\n  - 改动 AI 协作治理资产时，执行 `python scripts/check_ai_assets.py`。\n\n- 工作流 / 脚本 / Docker 改动：\n  - 适用范围：`.github/**`、`scripts/**`、`docker/**`\n  - 运行最接近改动面的本地验证。\n  - 交付时说明影响了哪条流水线、发布路径或部署路径。\n  - 若未执行 Docker / GitHub Actions 相关验证，明确说明原因与潜在风险。\n\n- 网络或三方依赖相关改动：\n  - 先跑离线或确定性检查。\n  - 优先确认 timeout、retry、fallback、异常文案、降级路径是否仍然成立。\n  - 若未执行在线验证，必须明确写出原因。\n\n## 7. 稳定性护栏\n\n- 配置与运行入口：\n  - 修改 `.env` 语义、默认值、CLI 参数、服务启动方式、调度语义时，要同时评估本地运行、Docker、GitHub Actions、API、Web、Desktop 的影响。\n  - 新配置优先做到“不配置也可运行，配置后增强能力”，避免叠加开关和互斥模式。\n\n- 数据源与 fallback：\n  - 修改 `data_provider/` 时，要关注数据源优先级、失败降级、字段标准化、缓存与超时策略。\n  - 单一数据源失败不应拖垮整个分析流程，除非需求明确要求 fail-fast。\n\n- API / Web / Desktop 兼容：\n  - 改 API / Schema / 认证 / 报告载荷时，要同时检查后端、Web、Desktop 的兼容性。\n  - 默认优先追加字段、保留旧字段或提供兼容层，避免无提示破坏现有客户端。\n\n- 报告 / Prompt / 通知：\n  - 修改报告结构、Prompt、提取器、通知模板、机器人链路时，要检查上游输入与下游消费方是否仍兼容。\n  - 单一通知渠道失败不应拖垮整个分析主流程，除非需求明确要求 fail-fast。\n  - 修改 `src/services/image_stock_extractor.py` 中 `EXTRACT_PROMPT` 时，要在 PR 描述中附完整最新 prompt。\n\n- 工作流 / 发布 / 打包：\n  - 修改自动 tag、Release、Docker 发布、日常分析或桌面端打包流程时，要评估触发条件、产物路径、权限边界和回滚方式。\n  - 自动 tag 默认保持 opt-in：只有 commit title 含 `#patch`、`#minor`、`#major` 才触发版本号更新，除非需求明确要求改变发布策略。\n\n## 8. Issue / PR / Skill 工作流\n\n- 仓库内已有以下 skill，可优先复用：\n  - `.claude/skills/analyze-issue/SKILL.md`\n  - `.claude/skills/analyze-pr/SKILL.md`\n  - `.claude/skills/fix-issue/SKILL.md`\n- 如果任务明确是 issue 分析、PR 审查、issue 修复，优先按对应 skill 执行，并将产物保存到 `.claude/reviews/`。\n- skill 中的命令、模板、验证顺序和交付结构必须与 `AGENTS.md` 保持一致。\n- 每次进行 PR 创建 / 更新、PR 审查或 issue 分析前，必须先同步最新代码基线：先检查工作区状态并执行 `git fetch --all --prune`；若工作区干净且当前分支可 fast-forward，则执行 `git pull --ff-only`。如存在本地改动、冲突状态、未跟踪风险文件或无法 fast-forward，不得强行切分支、stash、reset 或覆盖本地状态；PR 审查 / issue 分析可改用已 fetch 的远端 refs/PR head 做分析，并在分析文档中明确记录未更新本地工作树的原因、当前本地 HEAD 与使用的远端基线；PR 创建 / 更新应先说明当前分支与目标基线差异，必要时请求用户确认 rebase、merge 或继续基于当前分支推进。\n- skill 默认优先读取 CI / 工作流证据，再决定是否补本地验证。\n- 除上述 PR 创建 / 更新、PR 审查 / issue 分析的安全 fast-forward 同步外，skill 不得默认执行 `git pull`、`git push`、`git tag`、`gh pr create` 等会改变远端或当前分支状态的操作；这些操作必须要求用户确认。\n- PR 审查默认顺序：\n  1. 必要性\n  2. 关联性\n  3. 标题建议（`<类型>: <修改内容>`，且不含工具/agent 前缀；不作为硬性阻断项）\n  4. 描述完整性（对照 `.github/PULL_REQUEST_TEMPLATE.md`）\n  5. 验证证据\n  6. 实现正确性\n  7. 合入判定\n- 对 `fix` 类 PR，必须说明：原问题、根因、修复点、回归风险。\n- 合入阻断条件：\n  - 正确性或安全性问题\n  - 阻断型 CI 未通过\n  - PR 描述与实际改动内容实质性矛盾\n  - 缺少回滚方案\n  - 反复出现未收敛的契约漂移、补丁堆叠或验证证据失真\n\n## 8.1 Review 反馈处理与补丁堆叠禁止\n\n当你处理 review 反馈时，禁止只在 reviewer 点名的位置追加局部 patch 后声称“已全部修复”。你必须先重新理解 reviewer 指出的业务契约，再检查同一语义涉及的所有入口、配置、测试、文档、workflow 和用户可见路径。\n\n收到 review 反馈后，必须按以下顺序处理：\n\n1. 逐条列出 reviewer 指出的原问题。\n2. 说明根因，不能只描述“改了哪几行”。\n3. 找出同一语义影响的所有相关路径，例如 runtime、API/Web、CLI、diagnostics、workflow、docs、tests。\n4. 修复完整契约，而不是只修复当前失败测试或当前评论行。\n5. 补充能覆盖 reviewer 反例的回归测试、最终入口验证，或明确说明无法验证的原因。\n6. 同步更新 PR body，保证 scope、验证结果、兼容性、风险和回滚方案与当前 head 一致。\n\n如果你无法完成上述收敛，不要继续堆叠补丁，不要声称 ready for merge。应主动说明当前 PR 需要拆分、关闭重做，或请求维护者确认新的最小范围。\n\n以下行为会被视为低质量 PR：\n\n- 用 broad fallback、静默降级、`return False/None/[]` 掩盖不清晰的契约。\n- 测试 mock 掉真实风险层，只证明局部实现通过。\n- CI 通过后声称问题已关闭，但没有覆盖 reviewer 指出的反例。\n- PR body 与实际 diff、验证结果或兼容风险不一致。\n- review 后继续追加零散 patch，而不是重新收敛完整语义。\n- 同一业务语义在 runtime、Web/API、docs、workflow、tests 中表现不一致。\n\nCI 通过只能说明自动检查通过，不能替代人工语义收敛，也不能单独证明 reviewer 指出的反例已经关闭。\n\n## 9. 交付与发布\n\n- 默认交付结构：\n  - `改了什么`\n  - `为什么这么改`\n  - `验证情况`\n  - `未验证项`\n  - `风险点`\n  - `回滚方式`\n- 如果是 `docs` 任务，可直接写：`Docs only, tests not run`，但仍需说明是否核对了命令和文件名。\n- 自动 tag 默认不触发，只有 commit title 包含 `#patch`、`#minor`、`#major` 才会触发版本号更新。\n- 手动打 tag 必须使用 annotated tag。\n- 用户可见变更优先通过 PR 合入，并补齐 label 与验证说明。\n","category":"root","tokens":2372}]}