72 lines
8.3 KiB
Markdown
72 lines
8.3 KiB
Markdown
# APS Agent 工程操作规则（Project Operating Rules）
|
||
|
||
本文件只保留人工维护的项目规则。GitNexus 等工具生成的易变上下文（统计、索引、流程数量）不得写入本文件——那些内容只出现在 `AGENTS.md` / `CLAUDE.md` 的 `gitnexus:start/end` 块，或本地 ignored 文件 `.gitnexus/AGENTS.generated.md`。
|
||
|
||
## Platform Development Rules
|
||
|
||
完整规范见 `docs/README.md`（文档大管家）、`docs/architecture/harness.md`（门禁与权力矩阵）、`plan.md`（蓝图，细节以 `docs/` 落地为准）。所有开发者和 Agent 在修改产品路径、门禁、审批、证据链、契约、外部集成、求解引擎或验证链路时，必须遵守以下短规则：
|
||
|
||
- 产品路径不得依赖测试 fixture、demo、mock、stub、dry-run、历史试验入口或本机默认路径；演示数据（`APS_SEED_DEMO=1`）只允许在显式测试/本地演示启用。
|
||
- 后端不得用关键词规则把用户表达硬升级为未明确授权的工程动作；动作必须经 `server/agent_core/harness.py` 的 `_POWER_MAP` 白名单登记（未登记默认 P3 拒绝），P2/P3 必须出确认卡并在批准后由唯一执行通道执行。
|
||
- 任何会改变世界状态（项目、会话、订单、排产版本、主数据、MES/SAP/WMS、文件系统或外部资源）的行为，都必须有明确入口、状态记录、审计事件和验证方式；不得引入未设计的隐式副作用。
|
||
- 被用于后续决策的状态必须区分来源和提交语义：DRAFT 草稿、未批准、失败、中止、用户不可确认或仅用于调试的中间状态，不得当作已完成事实；写前必须建 checkpoints（成对快照）作为回滚锚点。
|
||
- 证据链统一协议：出卡冻结 `evidenceRefs`（含 `schedule-version:<id>`）/`beforeSnapshot`/`beforeFingerprint`；执行前 `verify_pending_evidence` 缺项拒绝（fail closed）；全部 P2/P3 写审计携带 `beforeSnapshot`+`evidenceRefs`；审计 append-only 哈希链，业务进程不得改写历史事件。
|
||
- 跨层契约三方一致：`shared/schemas/*.schema.json` ↔ `server/contracts.py` ↔ `apps/web/src/api/types.ts`；改契约必须同步并跑 `tests/golden/test_contract_sync.py`。
|
||
- mock、stub、demo、fixture、dry-run 必须显式启用、可识别、默认不进入产品运行路径，且不得被报告为真实工具成功。
|
||
- 工具失败、外部软件不可用、求解器 fatal、容量满、文件不存在、权限不足、模型失败、结果为空或操作中止必须显式报告，不得用泛化确认回复掩盖失败。
|
||
- 黄金测试是发布门禁：`tests/golden/`（固定运行时下全量通过）是最终真相层之一；开发报告和收口报告必须区分证据等级：代码修改、静态检查、单元测试、smoke、stub E2E、dry-run、真实外部工具、人工验证和 blocker 证据不能混写。
|
||
- 提交前检查是否引入测试样例、跨仓库 fixture、本机硬编码路径、后端意图硬规则、隐式副作用或失败不可见问题；必要时补 focused 验证和影响分析。未经用户授权不提交、不推送、不合并、不清理用户改动。
|
||
- 环境注意：默认 `python`（PATH 首位 Anaconda）会触发 `WinError 127`，不能作为发布运行时；求解器探针与发布验证必须使用固定 CPython（`.venv` / sidecar 冻结运行时）。
|
||
|
||
## Coding Tool Policy
|
||
|
||
Codex 是本仓库默认的规划、编辑、命令执行、集成和结果汇报 Agent。工具按目的选择，不能用工具输出替代最终验证。
|
||
|
||
- `rg` 和直接读文件用于文本、配置、日志、报错、文档、路径和小范围代码定位；日常探索优先使用它们。
|
||
- Serena 用于符号级代码工作：激活当前项目、读取 Serena 初始说明、查看文件符号概览、定位函数/类/方法、查找引用/实现，并在合适时执行符号级编辑或重命名。
|
||
- GitNexus 用于代码图谱和风险判断：执行流程理解、360 度符号上下文、公共 API 或共享模块变更前的影响分析（`impact`）、协同重命名（`rename`），以及 broad change 提交前的影响检查（`detect_changes`）。
|
||
- `git status`、`git diff`、`git diff --check`、focused tests、typecheck、build、CI 输出和真实运行验证是最终真相层；Serena/GitNexus 结果不能覆盖 live worktree 和验证结果。
|
||
|
||
默认工作流：
|
||
|
||
1. 先看当前 worktree 事实：检查 `git status`，再用 `rg` / 直接读文件理解当前任务所需的最小上下文。
|
||
2. 任务涉及函数、类、方法、引用关系或符号级修改时，先用 Serena 查看符号概览、引用和实现，再决定编辑范围。
|
||
3. 修改公共 API、共享模块、跨模块行为、门禁/审批/证据链/契约或影响不确定路径前，先用 Serena 查引用，再用 GitNexus `impact` 看影响面（HIGH/CRITICAL 必须先报告再动手）。
|
||
4. 修改后先跑最窄相关验证（focused pytest / ruff）；风险更大或影响更广时，再扩大到 `tests/golden/` 全量、typecheck、build、打包冒烟或真实运行验证（固定 CPython 运行时）。
|
||
5. 提交或关闭 broad change 前，检查 `git diff`，并在影响可能跨模块或跨流程时运行 GitNexus `detect_changes`。
|
||
|
||
避免过度使用：
|
||
|
||
- 不用 Serena/GitNexus 做普通文本、配置、日志、报错或文档搜索；这些优先交给 `rg`。
|
||
- 不为小型局部文档改动、低风险文本改动或明确孤立的局部修正运行 GitNexus。
|
||
- 不为普通找文件、读代码、扫报错把 GitNexus 当通用搜索工具。
|
||
- 不让索引、MCP 或工具摘要覆盖当前文件、diff、测试和真实运行结果。
|
||
|
||
## Frontend UI Map
|
||
|
||
修改前端 UI、交互、设计 token 或组件约束时，先阅读 `docs/product/features.md` 与 `docs/product/implementation-spec.md`；设计 token 与布局基础在 `apps/web/src/styles.css`。按边界定位代码（`apps/web/src/`）：`shell/` 负责桌面壳与导航，`chat/` 负责会话与 Composer，`viewport/` 负责左说右动视口（甘特/负荷/交期），`gov/` 负责门禁管理台与审批队列，`master/` 负责主数据，`orders/` 负责订单池，`projects/` 负责项目与会话，`knowledge/` 负责知识库面板，`skills/` 负责外部算法 Skill 管理，`timeline/` 负责检查点时间线，`auth/` 负责认证与租户，`api/` 负责类型化 API client（与后端契约同步）。先更新设计规范再改实现；修改后至少运行相关 focused tests、`npm run build`（或 typecheck）和 `git diff --check`，不得绕过契约同步直接改 `api/types.ts` 与后端字段不一致。
|
||
|
||
## Backend & Domain Map
|
||
|
||
- `server/agent_core/`：Harness 门禁（`_POWER_MAP`、确认卡、证据链）、意图识别、审批后端（文件/共享 database）、Plan 运行时、审计。
|
||
- `server/aps_domain/`：业务领域（workflow 编排、mes/sap/订单/柔性排产/约束/敏感性/方案优选等）。修改动作执行分支必须同步 `harness.md` 权力矩阵与 CHANGELOG。
|
||
- `server/gateway/`：FastAPI 入口与 SSE；`/api/actions/confirm` 是 P2/P3 唯一执行通道。
|
||
- `server/state/`：世界状态、checkpoints 成对快照、项目作用域；`store.py` 的 scoped store 缓存是审批输入指纹的读取边界。
|
||
- `server/db/`：模型、Alembic 迁移（版本文件 + 迁移顺序门禁）；DDL 必须显式 `mysql_engine="InnoDB"`，MySQL 引擎校验为启动门禁。
|
||
- `server/engines/` 与 `server/knowledge/`：求解引擎注册表与 RAG 知识资产；算法版本与证据引用要能串进证据链。
|
||
|
||
## GitNexus 刷新命令
|
||
|
||
运行 GitNexus 必须显式指定当前主仓库，避免旧 worktree 同名索引歧义；优先使用当前会话暴露的 GitNexus MCP 工具。若需要在终端刷新索引，必须使用 `--skip-agents-md`，避免把易变统计和工具提示写回 `AGENTS.md` 或 `CLAUDE.md`：
|
||
|
||
```powershell
|
||
$repo = (Resolve-Path (git rev-parse --show-toplevel)).Path
|
||
node .gitnexus/run.cjs analyze --skip-agents-md
|
||
node .gitnexus/run.cjs detect-changes --scope staged --repo "$repo"
|
||
```
|
||
|
||
- 不频繁运行 `analyze`。只有当 status 明确显示索引过期，且本次 impact 结果会影响决策时，才运行。
|
||
- 如果需要保留 GitNexus 生成的 agent-facing 说明，只能写入 ignored 本地文件，例如 `.gitnexus/AGENTS.generated.md`；不要把该类易变内容提交到仓库。
|
||
|
||
---
|