weichen
048bbe4a5e
Adopt the approved workflow with explicit dev baselines, serialized candidate integration, scoped validation and safe cleanup. Keep automation work tracked separately from the active policy.
145 lines
5.8 KiB
Markdown
145 lines
5.8 KiB
Markdown
# Agent-System 项目地图
|
||
|
||
> 通用 Agent 工作方式见 [AGENTS.md](./AGENTS.md)。
|
||
> Claude Code 入口见 [CLAUDE.md](./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|main/` | 各环境对话与工作区（隔离） |
|
||
| `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](./.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` 提交创建 `feature/*` / `fix/*`，在 `.worktrees/` 内完成；主目录保留给集成与运行。任务创建、串行集成、部署和清理遵守 [AGENTS.md](./AGENTS.md) §6 及 [worktree 工作规范](./.doc/ops/2026-09-21-agent-worktree-workflow.md)。
|
||
|
||
---
|
||
|
||
## 5. 文档地图（SSOT）
|
||
|
||
| 用途 | 路径 |
|
||
|------|------|
|
||
| 文档总地图 | [.doc/README.md](./.doc/README.md) |
|
||
| 协作会话 / 当前焦点 | [.doc/ops/CURRENT.md](./.doc/ops/CURRENT.md) |
|
||
| 模块完成度 | [.doc/status/FEATURE-MATRIX.md](./.doc/status/FEATURE-MATRIX.md) |
|
||
| 发布/审计缺口 | [.doc/remediation/gap-matrix.md](./.doc/remediation/gap-matrix.md) |
|
||
| 问题分析 | [.doc/audit/INDEX.md](./.doc/audit/INDEX.md) |
|
||
| 整改方案 | [.doc/remediation/INDEX.md](./.doc/remediation/INDEX.md) |
|
||
| 测试报告归档 | [.doc/test-reports/](./.doc/test-reports/) |
|
||
| 测试报告规范 | [.cursor/rules/test-reports-standard.mdc](./.cursor/rules/test-reports-standard.mdc) |
|
||
| Herdr 角色与备援 | [.doc/ops/2026-09-13-herdr-agent-roster.md](./.doc/ops/2026-09-13-herdr-agent-roster.md) |
|
||
|
||
---
|
||
|
||
## 6. 常用命令
|
||
|
||
```bash
|
||
# 环境
|
||
./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`](./scripts/git-push-dev.sh)
|
||
- **凭证文件**：`${HOME}/.secrets/gitea`
|
||
- **字段**：
|
||
```text
|
||
- ACCESS_TOKEN=<token>
|
||
- URL_PREFIX=<host>
|
||
```
|
||
- **用法**：`./scripts/git-push-dev.sh dev`（或 test/main 分支名）
|
||
|
||
---
|
||
|
||
## 8. 测试与验收铁律
|
||
|
||
- 涉及产品 Agent/工作流的业务交付：开发可用 stub，**交付前验收**必须真实产品 PI Agent Runner + MiniMax-M2.7-highspeed 全链路。纯工程规范/文档变更执行对应一致性检查，不调用产品 PI
|
||
- 报告必须归档至 `.doc/test-reports/`，遵循 test-reports-standard
|
||
- 禁止 stub 输出冒充最终验收数据
|
||
|
||
---
|
||
|
||
## 9. 当前焦点（动态）
|
||
|
||
见 **[.doc/ops/CURRENT.md](./.doc/ops/CURRENT.md)**。
|
||
|
||
- 发布缺口 SSOT：[gap-matrix](./.doc/remediation/gap-matrix.md)
|
||
- 模块完成度：[FEATURE-MATRIX](./.doc/status/FEATURE-MATRIX.md)
|
||
- 历史里程碑测试报告：[2026-09-13-codex-audit-p0-remediation-test-report.md](./.doc/test-reports/2026-09-13-codex-audit-p0-remediation-test-report.md)（P0 收口快照；持续更新的测试报告见 `.doc/test-reports/` 与 CURRENT）
|
||
- **发布门禁**：`production_ready=yes`（gap-matrix B1–B4 已签，[发布门禁区段](./.doc/remediation/gap-matrix.md)）。**无剩余发布 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](./.doc/ops/2026-09-13-herdr-agent-roster.md)。
|
||
|
||
## 11. 语言与提交
|
||
|
||
- 对用户：**简体中文**
|
||
- 提交：Conventional Commits；在 `feature/*` 或 `fix/*` 上渐进式分批提交，集成遵守 AGENTS §6.3 的已验证合并候选流程（禁止在三大主干直接开发 commit）
|