Agent-System/PROJECT.md

Agent-System 项目入口

工作边界见 AGENTS.md。本仓库是 Go + React/Vite + PostgreSQL/pgvector 的多用户工作流与对话平台，产品执行器为容器中的产品 PI Agent Runner。

仓库地图

路径	用途
cmd/、internal/	服务入口与 Go 模块
web/	React/Vite 前端
deploy/postgres/goose/	Goose 数据库迁移
configs/、templates/	运行配置、提示词与工作流模板（变更可能需要运行验收）
scripts/	工程、环境与推送工具
.doc/	文档地图、任务与证据
data/dev、data/test、data/main	各环境独立业务数据与工作区

模块编码/接口调整前读 模块开发标准，遵守既有接口、事件和表写者边界。

环境与操作入口

环境	分支	Compose	HTTP	DB 端口	数据路径
开发	dev	agent-dev	8080	5433	data/dev
测试	test	agent-test	8081	5434	data/test
生产	main	agent-main	8000	5435	data/main
共享 KB	跨环境	agent-infra	-	5432	data/shared/kb

这是拓扑约定，实际端口/制品/config/schema 由目标环境收据核实。知识库共享；对话、工作区、审计及业务 DB 严格隔离，禁止跨环境读写。

创建任务、合入、环境写操作与清理前读 worktree 操作规范，使用其机器入口及持锁流程。只读环境查询入口为 ./scripts/env-service.sh all status；共享服务写操作在主运行入口执行。晋升到 test/main 单独授权。

验证入口

按 验证契约 选测试、精确用例、模型证据和报告层级。普通文档只做差异/链接/状态一致性；运行模板/提示词按运行内容验收。

• Go：./scripts/arch-check.sh --mode block、go vet ./...、go test -short ./...；按范围追加 PG/鉴权负例。
• 前端：在 web/ 执行 npm test、npm run build；交互变更追加受影响真实浏览器测试。
• 产品 Agent/工作流：真实产品 PI Agent Runner；nightly 入口 仅覆盖 U8 与 FullNoneMixedChain 基线，按范围追加精确测试及 UI 验收。模型按目标环境已批准配置核验，不固定跨环境模型，不自行切换配置。

状态与文档权威

• 活跃工作/协调快照：CURRENT。
• 能力声明与剩余条件：FEATURE-MATRIX。
• 发布门禁：gap-matrix，以有日期、提交和制品身份的证据作判断；项目入口不缓存“无 blocker”或当前 schema。
• 问题与方案：audit、remediation。
• 规范状态与生效版本：规范登记。

凭证与推送

用户明确授权 push/同步远端后，使用 git-push-dev.sh 的分支参数；先核对目标分支。凭证查找 ${HOME}/.secrets/gitea，所需字段为 ACCESS_TOKEN 与 URL_PREFIX（文件按脚本支持格式填写）。不向用户索要值，不把凭证写入仓库/git config；缺失只记录路径与缺字段。

Herdr 工程协作

仅在任务需要 Herdr 时读 角色、审批与备援 SSOT；使用 启动脚本 / 派发脚本。context_pi 是协作终端的 PI CLI，不能替代产品 PI Agent Runner 验收。实际客户端/模型/在线状态记录在本次运行证据中。