Imported from zdfy123456/Visibility-Private (
AGENTS.md). Install upstream withnpx skills add zdfy123456/Visibility-Private. Copyright stays with the author.
AGENTS.md — 银发AI项目协作说明
本文件给后续 AI Agent 使用。请把它当作项目入口说明，而不是需求文档。不要把未核对的信息写成事实；遇到冲突时，以当前代码、测试和规约文件为准。
1. 基本工作原则
不要假设
- 不确定时明确说出不确定点，不要静默选择一种解释。
- 需求有多种解释时，先列出解释和取舍；风险较高时先问用户。
- 如果发现更简单的实现方式，要直接指出。
- 如果上下文矛盾或缺失，停止推进并说明哪里不清楚。
简单优先
- 写能解决当前问题的最少代码。
- 不为单次使用增加抽象。
- 不增加用户没有要求的“灵活性”“可配置性”或额外功能。
- 不为不可能发生的场景增加复杂错误处理。
- 如果 200 行能变成 50 行，应优先简化。
外科手术式改动
- 只改完成任务必须改的文件和行。
- 不顺手重构、不顺手改格式、不清理无关代码。
- 匹配项目已有风格，即使个人偏好不同。
- 如果发现无关死代码，提出来，不要擅自删除。
- 只清理自己改动造成的未使用 import、变量、函数或文件。
目标驱动
- 把任务转成可验证目标。
- 修 bug 时优先复现，再修复，再验证。
- 加功能时先明确验收标准，再实现，再跑对应检查。
- 多步骤任务要写简短计划，并给每步配验证方式。
2. 项目概览
- 项目名：银发行程风险裁判系统 / Silver Travel Risk。
- 目标：AI 驱动的银发旅游行程风险评估平台。
- 核心流程：上传行程文件或文本 -> 解析/结构化提取 -> 规则引擎评估风险 -> 生成可解释报告。
- 目标用户：旅行社产品经理、计调、银发旅游平台、个人裁判顾问。
- 核心原则：规则引擎是最终裁判，LLM 只提供结构化提取、建议或增强分析，不能替代规则判定。
3. 代码入口和目录
- 当前仓库根目录：
G:\银发AI项目。 - 主应用目录：
silver-travel-risk/。 - 后端：
silver-travel-risk/backend/，FastAPI + Python。 - 前端：
silver-travel-risk/frontend/，Next.js 15 + TypeScript + TailwindCSS + shadcn/ui/Radix。 - Prompt：根目录
prompts/和silver-travel-risk/prompts/下均有历史/当前提示词内容；改动前先确认调用方。 - 规约：
silver-travel-risk/backend/specs/，包含 OpenAPI、规则 schema、LLM 输出 schema、接口规约和验收标准。 - 规则库：
silver-travel-risk/backend/data/rules.yaml，是风险规则的主要配置入口。 - 旧版接口草稿：
modules/，包含 input_parser、risk_engine、travel_agent、report_generator 的历史 Agent 接口草稿。 - 共享类型/样例：
shared/。 - 项目说明与路线图：
README.md、CLAUDE.md、docs/、reviews/。
4. 已确认技术栈
后端
- Python
>=3.12。 - FastAPI async。
- SQLAlchemy 2.0 async。
- PostgreSQL 15 + pgvector。
- Redis。
- Alembic migrations。
- Ruff。
- mypy strict。
- pytest + pytest-asyncio。
- DashScope/Qwen，通过 OpenAI 兼容 SDK 调用。
- 文档解析使用 Word/PDF 相关工具，代码中已有
document_parser.py、word_parser.py、llm_extractor.py。
前端
- Next.js
^15.1.0。 - React
^19.0.0。 - TypeScript
^5.7.0。 - TailwindCSS
^3.4.0。 - Radix UI、lucide-react、recharts、sonner。
- Vitest、Testing Library、Playwright。
部署与基础设施
- Docker Compose 是本地和 MVP 部署主路径。
silver-travel-risk/docker-compose.yml启动 nginx、frontend、backend、postgres、redis。- PostgreSQL 本地映射端口为
5433:5432。 - Redis 映射端口为
6379:6379。 - Frontend 默认端口
3000。 - Backend API 默认端口
8000。
5. 架构事实
- 后端入口：
silver-travel-risk/backend/app/main.py。 - API 路由在
silver-travel-risk/backend/app/api/。 - Agent 编排在
silver-travel-risk/backend/app/agent/。 - 规则引擎在
silver-travel-risk/backend/app/engine/。 - 服务工具在
silver-travel-risk/backend/app/services/。 - 数据库模型在
silver-travel-risk/backend/app/models/。 - 事件系统在
silver-travel-risk/backend/app/events/，基于 Redis Streams + WebSocket。 - MCP 工具系统在
silver-travel-risk/backend/app/mcp/。 - RAG 知识库系统在
silver-travel-risk/backend/app/rag/。 - 多层缓存系统在
silver-travel-risk/backend/app/cache/，包含 L1 memory、L2 Redis、L3 PostgreSQL。 - 可观测性在
silver-travel-risk/backend/app/observability/和silver-travel-risk/backend/observability/。 - 前端主要页面在
silver-travel-risk/frontend/src/app/。 - 前端通用组件在
silver-travel-risk/frontend/src/components/。 - 前端 API 客户端与类型在
silver-travel-risk/frontend/src/lib/和silver-travel-risk/frontend/src/services/。
6. 风险评估领域规则
- 5 个风险维度：体力、医疗、尊严、责任、体验。
- 规则流程按项目文档描述为：数据加载 -> Kill Rules 一票否决 -> 5 维评分 -> 风险叠加 -> 总分和等级映射 -> 可选 LLM 增强分析。
rules.yaml已扩展为 V2 风险规则库，包含 kill rules、dimension rules、stacking rules 和 fix suggestions。- 新增风险规则时优先改 YAML 和对应测试；不要先改引擎代码，除非现有 schema/引擎无法表达。
- LLM 结果必须经过 schema 验证和规则引擎复核。
7. 安全与合规红线
- 健康数据、身份证、手机号、姓名等敏感信息不得写入日志。
- 发送给 LLM 前必须进行 PII 剥离。
- 健康数据存储需要加密；代码中已有加密和审计相关模块，改动前先核对现有实现。
- 项目文档要求仅使用阿里云 DashScope/Qwen 处理敏感健康数据；不要把健康数据发给 OpenAI 或境外 API。
- 不要提交
.env、密钥、真实用户数据、真实健康数据。 - 自动化决策必须保留可解释报告和人工复核路径。
8. 常用命令
在本项目里，用户提供的 C:\Users\Administrator\.codex\RTK.md 要求 shell 命令加 rtk 前缀。PowerShell cmdlet 不能直接被 rtk 解析时，使用：
rtk powershell -NoProfile -Command "<PowerShell 命令>"本地启动
cd G:\银发AI项目\silver-travel-risk
rtk docker compose up -d后端检查
cd G:\银发AI项目\silver-travel-risk\backend
rtk python -m pytest
rtk python -m ruff check .
rtk python -m mypy app前端检查
cd G:\银发AI项目\silver-travel-risk\frontend
rtk npm run test
rtk npm run build
rtk npm run test:e2e注意：package.json 里有 npm run lint，但 Next.js 15 项目中 next lint 可能需要核对当前可用性；失败时不要假设是代码错误，先看报错。
9. 测试与验证策略
- 后端单元测试在
silver-travel-risk/backend/tests/。 - RAG 测试在
silver-travel-risk/backend/tests/test_rag/。 - 前端组件测试在
silver-travel-risk/frontend/src/components/__tests__/。 - 前端 service/lib 测试在对应
__tests__目录。 - E2E 测试在
silver-travel-risk/frontend/e2e/。 - 改规则引擎时优先跑 assessor、kill_rules、dimension_scorer、stacking_engine 相关测试。
- 改 Agent 编排时优先跑 agent_runner、agent_state、langgraph、supervisor 相关测试。
- 改上传/报告 API 时优先跑 api_upload、upload_input、api_errors、integration 相关测试。
- 改前端上传、评估、报告页面时优先跑相关组件测试和 Playwright golden path。
10. OpenWolf 项目约定
本项目使用 OpenWolf 管理上下文。
- 每次会话先读
.wolf/OPENWOLF.md。 - 读文件前先查
.wolf/anatomy.md，如果摘要足够，不要读取全文。 - 生成或修改代码前读
.wolf/cerebrum.md，尤其是 User Preferences、Key Learnings、Do-Not-Repeat、Decision Log。 - 重大操作后按
.wolf/OPENWOLF.md要求记录.wolf/memory.md。 - 学到可复用项目知识时更新
.wolf/cerebrum.md。 - 发现/修复 bug、测试失败、构建失败或运行错误时按要求记录
.wolf/buglog.json。 - 不要重复读取本会话已经读取且未修改的文件。
11. Git 与工作区注意事项
- 当前项目可能存在大量未提交修改和未跟踪文件；默认假设它们是用户或其他 Agent 的工作。
- 不要使用
git reset --hard、git checkout --等破坏性命令，除非用户明确要求。 - 不要回滚自己没有制造的修改。
- 提交前先用
git status --short核对只包含本任务相关文件。
12. 修改建议
- 修改后端 API 时，保持 API 响应信封和错误处理风格一致。
- 修改业务规则时，优先保证规则解释性和测试覆盖。
- 修改 Prompt 时，先确认 PromptLoader 调用路径和变量占位符，不要只改文本不跑回归测试。
- 修改前端 UI 时，遵循现有组件、Tailwind、Radix/shadcn 风格；不要把工具型页面改成营销页。
- 新增依赖前先确认标准库或现有依赖是否已能满足需求。
- 大范围重构前必须先说明动机、范围、风险和验证方式。
13. 不确定和待核对
- 根目录和
silver-travel-risk/下都存在 Docker、prompt、配置相关文件；改动前必须确认当前运行路径。 CLAUDE.md中部分内容描述 MVP 设计，实际代码已经包含更多 V2/Phase C 能力；不要只按 MVP 摘要判断现状。modules/目录看起来是历史接口草稿，不应默认作为当前运行代码入口。- 前端
coverage/、.next/、node_modules/是生成物或依赖目录，通常不要人工编辑。
