# Agent-System 项目入口

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

## 仓库地图

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

模块编码/接口调整前读 [模块开发标准](./.doc/system-design/2026-09-20-module-development-standards.md)，遵守既有接口、事件和表写者边界。

## 环境与操作入口

| 环境 | 分支 | 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 操作规范](./.doc/ops/2026-09-21-agent-worktree-workflow.md)，使用其机器入口及持锁流程。只读环境查询入口为 `./scripts/env-service.sh all status`；共享服务写操作在主运行入口执行。晋升到 test/main 单独授权。

## 验证入口

按 [验证契约](./.doc/ops/2026-09-21-validation-contract.md) 选测试、精确用例、模型证据和报告层级。普通文档只做差异/链接/状态一致性；运行模板/提示词按运行内容验收。

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

## 状态与文档权威

- 活跃工作/协调快照：[CURRENT](./.doc/ops/CURRENT.md)。
- 能力声明与剩余条件：[FEATURE-MATRIX](./.doc/status/FEATURE-MATRIX.md)。
- 发布门禁：[gap-matrix](./.doc/remediation/gap-matrix.md)，以有日期、提交和制品身份的证据作判断；项目入口不缓存“无 blocker”或当前 schema。
- 问题与修复：[问题台账](./.doc/audit/ISSUES.md)；开发注意事项：[经验库](./.doc/ops/lessons/INDEX.md)，记录与复用遵循 [闭环规范](./.doc/ops/2026-09-23-issue-learning-workflow.md)。
- 问题与方案：[audit](./.doc/audit/INDEX.md)、[remediation](./.doc/remediation/INDEX.md)。
- 规范状态与生效版本：[规范登记](./.doc/ops/2026-09-21-policy-registry.md)。

## 凭证与推送

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

## Herdr 工程协作

仅在明确使用 Herdr 编排/启动/派发时读 [角色、审批与备援 SSOT](./.doc/ops/2026-09-13-herdr-agent-roster.md)；使用 [启动脚本](./scripts/herdr-agent-start.sh) / [派发脚本](./scripts/herdr-agent-dispatch.sh)。此时按 v1.2 资源预算与角色路由执行；普通 Codex/Claude/Cursor 会话不套用该分工。`context_pi` 是协作终端的 PI CLI，不能替代产品 PI Agent Runner 验收。实际客户端/模型/在线状态记录在本次运行证据中。