Agent-System/PROJECT.md

Agent-System 项目地图

通用 Agent 工作方式见 AGENTS.md。
Claude Code 入口见 CLAUDE.md。

---

1. 产品一句话

面向企业与团队的多用户工作流与对话智能体平台：RAG 知识库、PI Agent 执行、项目治理、阶段门禁、文档审批、任务持久化与 SSE 流式交互。

---

2. 主要目录

路径	说明
cmd/	服务入口
internal/	Go 业务逻辑（server、coordinator、bizdev、chat、projectinstance 等）
web/	React + Vite 前端
deploy/postgres/goose/	PostgreSQL 迁移（Goose）
configs/	Agent 与提示词配置
templates/	工作流文档模板
.doc/	架构、审计、整改文档
.doc/ops/	活协作区（CURRENT、任务、checklist、handoff）
.doc/test-reports/	测试/验收报告（归档）
`data/dev	test
scripts/	运维与推送脚本

---

3. 技术栈

• 后端：Go HTTP API（~110 路由）
• 前端：React + Vite
• 数据库：PostgreSQL + pgvector（Goose 迁移）
• 产品执行器：容器内 PI Agent Runner（真实 / stub）
• 工程协作：Herdr 管理的 Claude / Codex / Cursor / Antigravity / PI / Kimi / Cline；其中 Herdr PI 与产品 PI Agent Runner 无关
• 工作流：main、product_manager、test_manager 三套正式定义

---

4. Git 三分支与三环境

详见 .cursor/rules/git-workflow-and-environments.mdc。

环境	分支	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

红线：知识库共享；对话与业务 DB 严格隔离，禁止跨环境读写。

分支红线：三大主干（dev/test/main）禁止直接开发 commit；一律从 dev 开 feature/* 或 fix/*，合回 dev 须占集成槽位（见 AGENTS.md §6）。

---

5. 文档地图（SSOT）

用途	路径
文档总地图	.doc/README.md
协作会话 / 当前焦点	.doc/ops/CURRENT.md
模块完成度	.doc/status/FEATURE-MATRIX.md
发布/审计缺口	.doc/remediation/gap-matrix.md
问题分析	.doc/audit/INDEX.md
整改方案	.doc/remediation/INDEX.md
测试报告归档	.doc/test-reports/
测试报告规范	.cursor/rules/test-reports-standard.mdc
Herdr 角色与备援	.doc/ops/2026-09-13-herdr-agent-roster.md

---

6. 常用命令

# 环境
./scripts/env-service.sh shared start
./scripts/env-service.sh dev start
./scripts/env-service.sh all status

# Go 质量门禁（默认）
go vet ./...
go test -short ./...

# PG 集成（需 TEST_DATABASE_URL）
TEST_DATABASE_URL=postgres://... go test ./internal/server/... -run 'TestE2E_WorkflowGovernance'

# 真实 PI E2E（显式开关）
RUN_PI_E2E=1 RUNNER_AUTH_TOKEN=... go test ./... -run 'PI'

# 前端
cd web && npm test && npm run build

# 数据库迁移
# 见 deploy/postgres/goose/

---

7. Git 推送（自主，勿索要 token）

• 脚本：scripts/git-push-dev.sh
• 凭证文件：${HOME}/.secrets/gitea
• 字段：

  - ACCESS_TOKEN=<token>
  - URL_PREFIX=<host>
  

• 用法：./scripts/git-push-dev.sh dev（或 test/main 分支名）

---

8. 测试与验收铁律

• 开发可用 stub；交付前验收必须真实 PI Agent + MiniMax-M2.7-highspeed 全链路
• 报告必须归档至 .doc/test-reports/，遵循 test-reports-standard
• 禁止 stub 输出冒充最终验收数据

---

9. 当前焦点（动态）

见 .doc/ops/CURRENT.md。

• 发布缺口 SSOT：gap-matrix
• 模块完成度：FEATURE-MATRIX
• 历史里程碑测试报告：2026-09-13-codex-audit-p0-remediation-test-report.md（P0 收口快照；持续更新的测试报告见 .doc/test-reports/ 与 CURRENT）
• 发布门禁：production_ready=yes（gap-matrix B1–B4 已签，发布门禁区段）。无剩余发布 blocker；U9–U12 扩面 / 纯软件项目自举 SWBOOT-10 / FAV live 放量 / D7 合规签字均为已知 deferred/需独立授权事项，不阻塞首发，详见 gap-matrix 与 FEATURE-MATRIX 各自行

---

10. Herdr 工程协作

• orchestrator_codex 负责拆解、方案、调度、风险控制和终审；主力实现默认交给 implementer_cursor。
• 启动实例用 scripts/herdr-agent-start.sh，派发与安全降级用 scripts/herdr-agent-dispatch.sh。
• 角色和备援 SSOT 见 Herdr Agent roster。

11. 语言与提交

• 对用户：简体中文
• 提交：Conventional Commits；在 feature/* 或 fix/* 上渐进式分批提交，合回 dev 用 --no-ff（禁止在三大主干直接 commit）