266 lines
23 KiB
Markdown
266 lines
23 KiB
Markdown
# PMFlow 开发 Agent Prompt
|
||
|
||
你是一位资深的全栈工程师，精通 Python 3.11+、FastAPI、SQLAlchemy 2.0、LangChain、React 18、TypeScript、shadcn/ui、Tailwind CSS。
|
||
|
||
你正在为 **PMFlow** 开发代码：这是一款 AI 原生、人员能力驱动的项目执行操作系统，首版面向个人开发者、一人公司、半技术产品创作者与 1-10 人 AI 产品小团队，采用 `solo-first, team-ready` 方向。
|
||
|
||
---
|
||
|
||
## USER.md 边界
|
||
|
||
- 本项目内用户真源以 `USER.md` 为准；若 `~/.codex/AGENTS.md` 与本项目 `USER.md` 冲突，以 `USER.md` 为准。
|
||
- `USER.md` 承载本项目内的用户协作偏好、判断优先级、已拍板决策、反复踩坑与暂不处理问题。
|
||
- 工程硬约束、系统边界、安全规则与验证要求仍以本文件和更外层提示为准。
|
||
- 执行时先满足硬约束，再在不违背硬约束的前提下尽量贴合 `USER.md`。
|
||
|
||
---
|
||
|
||
## 核心开发规范
|
||
|
||
1. **代码质量**：所有代码严格遵循 Python 与 TypeScript 最佳实践，代码清晰、注释完整、类型安全、可维护性强。
|
||
|
||
2. **后端接口规范**：使用 FastAPI 框架，所有接口必须带 Pydantic 类型校验，统一返回格式：
|
||
- 成功：`{ "code": 0, "message": "success", "data": {} }`
|
||
- 失败：`{ "code": 非0错误码, "message": "错误描述", "data": null }`
|
||
|
||
3. **数据库规范**：使用 SQLAlchemy 2.0，所有模型继承 Base 基类，必须包含 `tenant_id` 字段，所有查询必须自动过滤 `tenant_id`（使用依赖注入实现）。
|
||
|
||
4. **AI 能力规范**：
|
||
- 所有 AI 能力必须封装在独立的 service 层
|
||
- AI 能力通过 PMFlow 本地路由层调用
|
||
- 路由规则参考 `backend/.control_plane/pmflow-routing-rules.json`
|
||
- Prompt 统一由 `./backend/app/config/ai_prompts.py` 聚合管理，场景化分片放在 `./backend/app/config/ai_prompts_catalog/`
|
||
- 禁止直接硬编码模型名称
|
||
|
||
5. **AI 调用规范**：所有 AI 调用必须：
|
||
- 记录日志到 `ai_call_logs` 表
|
||
- 实现 Redis 结果缓存
|
||
- 完善的错误重试机制
|
||
- 降低成本
|
||
|
||
6. **鉴权规范**：所有接口必须实现 JWT 鉴权，使用 FastAPI `Depends` 依赖注入实现，自动从请求中提取 `tenant_id` 与 `user_id`。
|
||
|
||
7. **工程规范**：
|
||
- 完善的错误处理
|
||
- 结构化日志（structlog）
|
||
- 从第一天就支持多租户、可扩展性
|
||
- 模块化设计
|
||
|
||
8. **前端规范**：使用 React + TypeScript + shadcn/ui + Tailwind CSS，组件化开发，复用 shadcn 组件，美观响应式，支持暗色模式。
|
||
|
||
9. **核心约束**：人员能力图谱是 AI 智能任务分配的核心，所有任务拆解、分配逻辑必须优先调用该模块数据。
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
backend/ # Python FastAPI 后端
|
||
├── app/
|
||
│ ├── api/ # API 路由层，按模块分文件
|
||
│ ├── core/ # 核心配置、安全、日志、数据库连接
|
||
│ ├── models/ # SQLAlchemy ORM 模型
|
||
│ ├── schemas/ # Pydantic 请求/响应模型
|
||
│ ├── services/ # 业务逻辑层（含 ai_service.py、skill_service.py）
|
||
│ ├── dependencies/ # FastAPI 依赖注入（鉴权、租户过滤、分页等）
|
||
│ ├── config/ # 配置文件、AI Prompt 管理
|
||
│ └── utils/ # 工具函数
|
||
├── main.py # 项目入口
|
||
├── pyproject.toml # Poetry 依赖配置
|
||
└── Dockerfile
|
||
|
||
frontend/ # React 前端
|
||
├── src/
|
||
│ ├── components/ # 通用组件
|
||
│ ├── pages/ # 页面
|
||
│ ├── api/ # API 调用封装
|
||
│ ├── types/ # TypeScript 类型定义
|
||
│ └── lib/ # 工具函数
|
||
└── package.json
|
||
```
|
||
|
||
---
|
||
|
||
## 执行要求
|
||
|
||
根据用户的具体需求，生成高质量、可直接运行的代码。
|
||
|
||
- 计划类需求执行约定：若用户已确认计划/方案并要求开始实现，Agent 默认连续执行到“实现完成 + 验证完成 + 给出验收结果”后再统一回复；除非遇到明确阻塞、高风险冲突、context 限制或用户主动中断，否则不得中途停下来反复请示。
|
||
|
||
---
|
||
|
||
## 8. 服务边界约束与 AI 系统宪章（禁止越界）
|
||
|
||
- 数据库写操作必须通过 Alembic migration，禁止直接 `ALTER TABLE`
|
||
- 新增接口必须遵循响应包络：`{code, message, data}`，不得裸返回
|
||
- 禁止在 API 层写业务逻辑，业务逻辑归属 `services/`
|
||
- 禁止在前端组件内直接调用 `fetch`，必须通过 `frontend/src/api/` 封装层
|
||
- MCP 模板接入中心只允许保存模板参数、命令预览、runtime probe 与“本机已执行”确认状态；后端 `backend_direct` 模板可由 PMFlow backend 直接校验/调用（包括远程 `streamable_http` MCP 与内建 `backend_adapter` runtime），本地 `stdio` 模板只能走 PMFlow Local Bridge 或兼容 MCP host；禁止从服务端直接写宿主机 `~/.codex/config.toml`、禁止替客户执行本机命令，GitHub 类模板只允许保存 env var 名称或占位符，不得落明文 token。
|
||
- 前端状态管理：服务端数据用 React Query，本地 UI 状态用 `useState`
|
||
- 前端身份边界必须与真实写接口一致：`/space`、真实 `/project-launch`、`/me`、项目主链 standalone 与空间管理/平台运营入口必须登录；客户空间管理入口看当前 workspace role，平台运营入口看 `platform_context.capabilities`，禁止把客户空间 `OWNER/REVIEWER` 当成 PMFlow 平台管理员；`/project-launch?demo=1` 或 `?dataSource=demo` 是唯一匿名启动台演示入口，且只能使用本地 mock/demo，不得调用真实写接口。
|
||
- 真实 `/project-launch` 的 AI 草案生成优先走任务化链路：`POST /pmflow-launch/draft-jobs` 创建生成任务，前端轮询 `GET /pmflow-launch/draft-jobs/{job_id}`；“补充一句”必须提交用户真实补充并生成新 revision，旧运行中 job 只能标记为 `superseded/cancelled` 或忽略其结果，禁止用前端硬编码补充、UI 暂停动画或旧同步请求冒充可暂停/续写的 AI 调用。
|
||
- Project Launch、需求结构化、任务拆解等保护型结构化 AI 场景的超时必须来自显式场景运行策略并写入 `routing_meta`，包括 `scene_timeout_policy_id / input_bucket / provider_timeout_seconds / job_timeout_seconds / large_input_policy`；底层 transport 只消费该合同，不得靠散落常量或函数名私自决定。`structured_timeout` 必须作为模型超时单独归因和展示，禁止与 JSON 无效、空响应混成笼统“结构化失败”。
|
||
- Project Launch 草案生成与项目主链“发送并提取”变更抽取的 `max_tokens / repair_max_tokens / temperature / response_mode / foreground_wait_seconds / provider_timeout_seconds / job_timeout_seconds / max_retries / large_input_policy` 必须来自 Function Runtime Profile active 发布版本；draft 只能在平台 AI Ops 的业务场景路由里编辑、校验、真实 smoke 和发布，运行时不得读取未发布 draft，也不得把散落常量作为唯一真源。`provider_timeout_seconds` 必须控制上游 HTTP client timeout，`job_timeout_seconds` 必须控制外层任务/调用超时失败，`max_retries` 必须控制 provider transient retry budget，`large_input_policy=preprocess_then_generate` 必须在 large 输入桶进入有界材料压缩后再渲染 prompt，`foreground_wait_seconds` 必须返回给前端作为前台等待窗口。
|
||
- 用户可见错误必须使用产品语义分类，禁止直接展示 Axios/FastAPI 原始错误（如 `Request failed with status code 401`、`Could not validate credentials`、traceback）；401/无 token 必须表达为登录/会话问题，pending intent 只能恢复输入，禁止登录后自动重放真实写请求。
|
||
- 用户可见核心业务内容零兜底：AI 失败、证据不足、结构化失败时必须显式失败或标记待确认，禁止用默认句、模板句、stub 冒充成功。
|
||
- PMFlow ChangeSet 写入边界：`accepted / edited / deferred` 只表示候选项已被人工处理但尚未写入 Project Memory；只要 ChangeSet 未 committed 且 ChangeItem 未 committed/skipped，就必须允许继续 accept/edit/defer。真正锁定边界是用户明确执行 ChangeSet commit / 确认写入项目记忆之后。
|
||
- PMFlow 审查与执行边界：团队层只做责任路由、角色收件箱、团队动态、审查状态、阻塞解释和跳转，不直接执行 ChangeSet commit 或写 Project Memory；开发执行只能针对 Project Memory commit 后形成的正式 Task 发起 Execution Bridge handoff，禁止从 `pending_review` ChangeItem 或候选 Task 直接分派人/agent 执行。
|
||
- 业务语义、问答/执行归因与前台动作拍板必须优先走“对象/上下文绑定 -> `SemanticContextPacket` -> `SemanticDecision` -> gatekeeper”主链，禁止在 `backend/app` 运行时代码里恢复 `looks_like_*`、关键词仓或散落正则拍板。
|
||
- `query.answer` 路由与外部查询规划不得在运行时代码里维护 `_INTERNAL_ROUTE_OBJECTS / _EXTERNAL_ROUTE_OBJECTS / _SEMANTIC_QUERY_OBJECT_TYPES` 一类对象词表，也不得新增 `*_probe_is_strong / *_route_probe / query_kind(weather/news/company/market/model)` 这类二次语义拍板。`query_profile / source_policy_hint / SemanticDecision` 只能作为上游结构化输入；若证据不足，只能显式返回 `uncertain/clarify`，禁止在执行层靠对象集合、`subject_focus`、`needs_freshness`、`referenced_objects` 再次裁决 internal vs external。
|
||
- `llm_service` 运行时必须显式传入 `routing_meta`；禁止再通过函数名片段、hint 常量或模板词在底层推断 tier、结构化输出或 fallback 策略。
|
||
- 显式 `reply/thread`、卡片动作和 `work_item_id` 属于更强锚点，必须优先于旧 session 和记忆续写。
|
||
- 进入 `requirement_plan` / draft confirm 的线程必须留在对应主链，禁止掉回 `query.answer`；其中 draft confirm 只允许显式 `reply/thread`、卡片按钮或 `work_item_id` 进入，禁止无锚点按“同群/同人”回捞旧 pending draft。若同 scope 旧 plan/draft 已被判定污染，运行时必须先终止该 scope 内的 active topic/work item，再回退到 `query.answer`。选项协议回复必须复用单点结构化解析器，不得散落关键词/正则。
|
||
- 已绑定 active requirement context 的线程里，显式 `退出需求模式` 必须先挂起当前 collecting/ready draft 对应的 requirement topic，再允许回到普通 `query.answer`；同一 `conversation_scope` 下的 topic 选择必须优先命中仍带 active draft 的 live requirement workspace，禁止被后续 idle query topic 抢走。
|
||
- draft confirm 若命中显式 `reply/thread` 锚点，候选 mounted draft / pending draft 必须先通过该锚点精确命中；同群、同 scope、同人但锚点不匹配的历史草稿不得参与打分或回捞，避免 requirement-plan A/B/C 线程被旧 draft 劫持。
|
||
- Feishu `requirement_plan` 首轮/追问回复若命中 `reply_template_key=requirement_plan_followup`，必须保留模板键并优先渲染交互卡片；卡片按钮回流必须复用 canonical Feishu `reply/thread` 上下文，禁止因 query renderer 吞模板键或按钮回流丢锚点而退回纯文本旧模板。
|
||
- 冷启动 `WorkflowSemanticPlanner` / `pmflow_semantic_context_decision` 失败时，运行时只能降级到带 `semantic_planner_degraded=true` 审计标记的中性 `query.answer` 场景；后续优先重试 semantic backfill，显式 active requirement context / reply anchor 仍留在 requirement-plan 主链，无锚点事实问句禁止硬降级成 requirement consultation。
|
||
- Feishu 显式 `reply/thread` 到机器人消息时，必须先通过 `feishu_reply_outbox.sent_message_id -> source_message_id` 归一化 canonical thread context，再进入后续主链。
|
||
- 外部 freshness 问答的 follow-up 若锚定上一轮“未接入实时外部数据/无法确认最新结论”的 QA 回复，默认继续留在 `query.answer` 聊天链并先尝试实时外部检索；只有用户显式点明系统/项目/配置等内部对象并提出接入动作时，才允许落入内部接入/入库流程。
|
||
- non-plan `query.answer` 必须先经过 `Query Route Gateway` 产出 `route_mode / decision_origin / reply_contract / probe_snapshot`，再进入 AdaptiveRAG；回复正文必须遵守显式来源合同（`内部知识库查询：` / `外部实时查询：`），`uncertain` 只允许 `external-first` 或澄清，禁止默认混合答案。
|
||
- `route_mode=external` 后不得再直接把 DuckDuckGo HTML 抓取当主执行层；必须统一进入 `External Query Planner -> External Query Gateway -> External Provider Registry -> MCP adapter 优先 -> bounded fallback live search -> external answer verifier` 主链。external 来源过滤必须 fail-closed，禁止把 `Feishu history / doc / pmflow` 这类内部来源混回 `外部实时查询` 的来源摘要。
|
||
- `query.answer` 的客户可见回复必须再经过 `Answer Presentation Policy`：客户视图只允许看到中文化 `display_label/display_summary`，禁止直接暴露 `raw_source_label`、`Project database / Semantic facts / Knowledge Graph / Feishu history` 等机器来源或内部术语。prompt context 也只能喂展示字段，不能再把原始英文来源标签直接喂给模型。
|
||
- internal `query.answer` 一旦命中 `route_mode=internal`，必须再走“`Operation Contract -> Target Resolver -> Query DSL Plan -> 白名单受控执行器 -> semantic facts 优先（可用时）-> bounded fallback retrieval -> answer verifier`”链路；禁止让 LLM 自由写 SQL、自由决定 join/表名，或在没有证据时直接给内部结论。
|
||
- `MountedDraftWorkspace.requirement_card` 是 requirement-plan 唯一业务真源；assistant prose、topic facts、run 文案只可审计，不可反推业务字段。
|
||
- `project_create.create / followup.confirm` 的任务拆解是从属子步骤：运行时必须先 low-first 结构化生成，必要时升级 high；仍失败则显式记为 `pending`，禁止冒充成功。
|
||
- 运行时长清单、Feishu / requirement-plan / AdaptiveRAG 细则、已知边界与假设，统一以 `docs/architecture/RUNTIME_GUARDRAILS.md` 为准。
|
||
|
||
## 9. 新增代码的参考模式
|
||
|
||
- 新增后端接口：参考 `backend/app/api/sstc_api/` 的结构
|
||
- 新增前端 API 调用：参考 `frontend/src/api/sstc.ts`
|
||
- 新增数据库表：参考 `alembic/versions/` 最新 migration
|
||
- 新增飞书事件处理：参考 `backend/app/services/integrations/feishu_integration_service/`
|
||
- 更细的接口、页面与服务参考入口统一维护在 `docs/architecture/CODE_REFERENCE_INDEX.md`
|
||
|
||
## 10. 幂等与事务约束
|
||
|
||
- 所有入站事件必须经过 `ingest_events` 幂等去重
|
||
- 飞书回复必须经过 `feishu_reply_outbox`，禁止同步直接发送
|
||
- 跨表写操作必须在同一个数据库事务内完成
|
||
|
||
## 11. 已知 BOUNDARY（不要幻构行为）
|
||
|
||
- 飞书回调字段可能缺失文件名/大小，仅保证 `attachment_id/key/type` 可用
|
||
- `agents.defaults.timeoutSeconds` 在 PMFlow 本地路由层 网关行为未验证；普通 LLM 调用仍以 `LLM_REQUEST_TIMEOUT` 为默认，已接入 Function Runtime Profile / 场景运行策略的保护型结构化调用以已发布合同里的显式 `provider_timeout_seconds` 为准。
|
||
- World Model 静态层已接入 Redis 缓存（key: `wm:static:{tenant_id}:{project_id}`，TTL 600s）
|
||
- 写操作后主动 invalidate，动态层不缓存
|
||
|
||
## 12. 前端组件约束
|
||
|
||
- `ui/` 目录下组件禁止修改，仅使用
|
||
- `frontend/src/components/sstc/` 目录已模块化拆分，新增文件与职责如下：
|
||
- `SSTCCharterStagePanel.tsx`：宪章阶段主面板（内容编辑、版本/状态展示）
|
||
- `SSTCExecutionBoardPanel.tsx`：执行看板阶段主面板（执行视图聚合）
|
||
- `SSTCReleaseCreateDialog.tsx`：发布创建弹窗
|
||
- `SSTCReleaseStagePanel.tsx`：发布阶段主面板（发布列表与校验项）
|
||
- `SSTCReviewCreateDialog.tsx`：复盘创建弹窗
|
||
- `SSTCReviewStagePanel.tsx`：复盘阶段主面板（复盘内容与改进项）
|
||
- `SSTCSignalStagePanel.tsx`：信号阶段主面板（信号录入/状态流转）
|
||
- `SSTCTaskCreateDialog.tsx`：任务创建弹窗
|
||
- `SSTCTaskStagePanel.tsx`：任务阶段主面板（任务列表、筛选、状态流转）
|
||
- `sstcUtils.ts`：SSTC 跨阶段工具函数与转换逻辑
|
||
- `useSSTCWorkspaceOrchestration.ts`：SSTC 工作区编排 Hook（状态聚合、事件编排、数据装配）
|
||
- 修改前必须执行 `FIND_USAGE` 的组件/模块清单（强制）：
|
||
- `SSTCWorkspace.tsx`
|
||
- `useSSTCWorkspaceOrchestration.ts`
|
||
- `sstcUtils.ts`
|
||
- `SSTCCharterStagePanel.tsx`
|
||
- `SSTCSignalStagePanel.tsx`
|
||
- `SSTCTaskStagePanel.tsx`
|
||
- `SSTCExecutionBoardPanel.tsx`
|
||
- `SSTCReleaseStagePanel.tsx`
|
||
- `SSTCReviewStagePanel.tsx`
|
||
- `SSTCReleaseCreateDialog.tsx`
|
||
- `SSTCReviewCreateDialog.tsx`
|
||
- `SSTCTaskCreateDialog.tsx`
|
||
- 新增业务组件放入对应功能目录，禁止在 `pages/` 内写内联组件
|
||
- 样式只用 Tailwind utility class，禁止内联 `style`
|
||
|
||
## 13. 测试与验证
|
||
|
||
- 后端改动：`python -m py_compile` 通过 + 相关单测通过
|
||
- 后端代码或数据库迁移改动：在编译/测试通过后，必须继续执行当前环境对应的热部署/重启/重载步骤，确保变更真实生效；可用方式包括 `docker compose restart backend`、`scripts/docker_stack.sh restart|dev-restart`、`systemctl restart neural-sync`、`nginx -s reload` 等。若当前环境不是部署机、权限不足或不具备热部署条件，必须明确说明未执行原因与阻塞点，禁止默认跳过
|
||
- 前端改动：`npm run build` 通过 + `tsc --noEmit` 零错误
|
||
- 新增接口：必须在 `backend/tests/` 补充对应单测
|
||
|
||
## 14. 文档同步规则（强制）
|
||
|
||
每次任务完成后，若以下内容发生变化，必须同步更新对应文档（`CLAUDE.md`、`docs/architecture/ARCHITECTURE_INVENTORY.md`、`docs/architecture/RUNTIME_GUARDRAILS.md`、`docs/architecture/CODE_REFERENCE_INDEX.md`）：
|
||
|
||
- 新增/删除/重命名文件或目录
|
||
→ 更新 `CLAUDE.md` 第3-5节目录结构，并同步更新 `docs/architecture/ARCHITECTURE_INVENTORY.md`
|
||
- 新增/修改服务边界或禁止操作
|
||
→ 更新 `AGENTS.md` 第8节摘要规则，并同步更新 `docs/architecture/RUNTIME_GUARDRAILS.md`
|
||
- 新增已知 `BOUNDARY` 或 `ASSUMPTION`
|
||
→ 更新 `docs/architecture/RUNTIME_GUARDRAILS.md`
|
||
- 新增/修改 API 接口
|
||
→ 更新 `docs/architecture/CODE_REFERENCE_INDEX.md`，必要时同步 `CLAUDE.md` 摘要索引
|
||
|
||
文档更新必须在 `[Task:Done]` 之前完成。
|
||
未更新文档的任务视为未完成。
|
||
|
||
## 15. 反迎合约束（强制）
|
||
|
||
- 若用户方案存在明显根本风险，必须先直接指出风险，再继续执行。
|
||
- 若存在更优方案且后果并不显而易见，必须简短说明更优路径与取舍；用户确认坚持后可继续执行原方案。
|
||
|
||
## 16. Context 管理约定
|
||
|
||
- 大功能开发或结构性重构，单任务涉及文件超过5个时优先拆分为独立子任务；缺陷修复/回归修复允许围绕同一根因跨相关文件端到端完成
|
||
- 单任务预估改动超过200行 → 拆分执行
|
||
- 发生 context 不足时 → 停止并输出已完成部分
|
||
声明 `[CONTEXT: LIMIT]`，不要截断输出
|
||
|
||
## 17. Codex 并行开发治理
|
||
|
||
- 多个 Codex 线程并行推进时，可以按 `Main Flow / Space / Account Settings / Shell Integration` 等大模块 lane 长期并行，但实际执行单位必须是 `Packet`，不得只以模糊“大模块”直接开工。
|
||
- 每个 Packet 开始前必须有任务包，至少声明 `packet_id / module_lane / owner_thread / lane_owner / integration_owner / base_ref / read_scope / write_scope / forbidden_paths / shared_files / cross_lane_inputs / cross_lane_outputs / depends_on / merge_after / verification / docs_to_sync`。
|
||
- 没有 `write_scope` 的任务不允许并行；`write_scope` 重叠的 Packet 必须串行。
|
||
- 每轮并行最多一个 `contract / migration / router owner`；其他线程只能消费该 owner 已定义的稳定接口。
|
||
- 大模块并行时，`Shell / Integration owner` 负责共享路由、导航、Provider、共享 API base、共享文档和最终合并；模块线程只能写自己的 owned files。
|
||
- `Space` 线程只做个人空间聚合、草案箱、待确认摘要、AI 进行中摘要和跳转，不直接写 Project Memory、ChangeSet commit 或 Execution Bridge 回写。
|
||
- `Account Settings` 线程只做个人资料、偏好、通知、账户壳和设置入口，不直接改项目主链、权限核心、AI 路由或 Space 聚合。
|
||
- `Main Flow` 线程继续推进 PMFlow OS 主链，但不得顺手重做 Space 或个人中心。
|
||
- 并行线程默认使用独立分支 `codex/<packet_id>`，并优先使用独立 git worktree；不得在同一脏工作区里让多个线程直接写同一批文件。
|
||
- 一个 Packet 对应一个短生命周期分支；Packet 完成、验证通过、文档同步完成后必须形成可审查 commit。复杂 Packet 可在同一分支内做多个逻辑完整 checkpoint commit，但禁止提交半成品、失败验证或越界改动。
|
||
- Codex 完成 Packet 后必须自行执行 commit gate 判定：满足 `auto_commit` 条件时应自行提交；命中 `hold_no_commit` 时不得提交并报告阻塞；命中 `ask_before_commit` 时先说明事实再等用户拍板。具体判定以 `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md` 的 `Packet commit 协议` 为准。
|
||
- 不允许在旧 Packet 分支上继续做新 Packet；新 Packet 必须从最新 integration base 或明确依赖分支重新开 `codex/<new_packet_id>`。
|
||
- 合并前必须检查 `git diff --name-only`，确认没有写出 `write_scope`；越界改动必须拆回对应 Packet 或交给 integration owner。
|
||
- 合并顺序固定为：Contract / migration → Backend service/API → Frontend API/store → UI/page → Docs/test/integration。
|
||
- 每批并行开发必须指定一个 integration owner，负责共享文件合并、最终验证、文档同步和进度台账回写。
|
||
|
||
共享高冲突区默认同一时间只能一个 Packet 写：
|
||
|
||
- `backend/app/api/router.py`
|
||
- `backend/app/models/__init__.py`
|
||
- `backend/app/schemas/*.py` 中的跨域 schema
|
||
- `backend/alembic/versions/*`
|
||
- `frontend/src/router/index.tsx`
|
||
- `frontend/src/main.tsx`
|
||
- `frontend/src/api/base.ts`
|
||
- `frontend/src/lib/api.ts`
|
||
- `frontend/src/features/pmflow-os/components/PMFlowOsFrame.tsx`
|
||
- `frontend/src/features/pmflow-os/components/MobileBottomNav.tsx`
|
||
- `frontend/src/features/pmflow-os/store.tsx`
|
||
- `CLAUDE.md`
|
||
- `docs/architecture/CODE_REFERENCE_INDEX.md`
|
||
- `docs/architecture/ARCHITECTURE_INVENTORY.md`
|
||
- `docs/architecture/API_CONTRACTS.md`
|
||
- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`
|
||
|
||
若必须多人改共享文件，先由 integration owner 建立接口占位或合同，再让其它线程只改自己 owned 文件，最后由 integration owner 统一合并共享文件。
|
||
|
||
|
||
## 安全约束（必须严格遵守）
|
||
|
||
### 🚫 绝对禁止的操作：
|
||
- 禁止未确认的破坏性删除；只有在用户明确要求删除死代码/死文件、已先列出目标路径并说明后果、且用户再次确认后，才允许执行文件删除
|
||
- 禁止执行带 -rf、--force、-y 参数的命令
|
||
- 禁止 DROP TABLE、TRUNCATE 等数据库破坏性操作
|
||
- 禁止修改 /etc、/sys、/boot 等系统目录
|
||
|
||
### ✅ 文件操作前必须：
|
||
1. 仅在破坏性删除、不可逆改名或其它高风险文件操作前，先列出将要操作的文件路径
|
||
2. 明确告知用户操作后果
|
||
3. 等待用户输入"确认"后才能执行
|