Industry
/
aps-agent
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
aps-agent/PROJECT_OPERATING_RULES.md

8.3 KiB
Raw Permalink Blame History

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：

$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；不要把该类易变内容提交到仓库。