pr to main

README.md

@@ -18,7 +18,7 @@ Chinese documentation: [README.zh-CN.md](README.zh-CN.md)
 - Static analysis pipeline using Ruff and Bandit.
 - Repository archive storage through MinIO.
 - Python code chunk indexing with PostgreSQL persistence.
-- Local CLI for reviewing staged, unstaged, or all uncommitted changes.
+- Planned: local CLI for reviewing staged, unstaged, or all uncommitted changes.
 - Docker Compose environment for backend, MinIO, and PostgreSQL.
 
 ## Tech Stack
@@ -43,30 +43,41 @@ FastAPI Webhook Endpoint
         v
 GithubHandler
         |
-        +--> PR Summary Service --> PR Summary Agent --> GitHub Issue Comment
+        +--> PR Summary Service
+        |       +--> PR Summary Agent
+        |       +--> GitHub Issue Comment
         |
         +--> Code Indexing Service
         |       +--> Git Fetcher Container --> MinIO repo archive
         |       +--> SAT Runner Container --> MinIO SAT report
-        |       +--> Code Chunker --> PostgreSQL
+        |       +--> Code Chunker + Reference Parser --> PostgreSQL code index
+        |       +--> Embedding Builder --> PostgreSQL pgvector
+        |       +--> Convention Indexing --> Repository Convention KB
         |
         +--> Code Review Service
-                +--> SAT Summary Agent
-                +--> GitHub API Client
-                +--> Code Review Agent --> GitHub PR Review
+                +--> Workflow Run/Step State --> PostgreSQL
+                +--> SAT Summary JSON Agent
+                +--> Code Review Planning Agent
+                +--> Structural Evidence Agent --> Code index queries
+                +--> Convention Evidence Agent --> Convention KB + semantic search
+                +--> Evidence Validator
+                +--> Code Review Writer Agent
+                +--> Patch-line Review Output Validator
+                +--> GitHub PR Review
 ```
 
 Key backend modules:
 
 - `codehawk/api`: FastAPI routing and webhook endpoints.
 - `codehawk/handlers`: event routing from GitHub webhook payloads.
 - `codehawk/services`: workflow orchestration for PR summaries, reviews, and indexing.
-- `codehawk/agents`: AI agents and prompts.
+- `codehawk/agents`: PR summary, SAT summary, planning, evidence, and review writer agents.
 - `codehawk/github`: GitHub auth, token caching, and API client.
 - `codehawk/minio`: object storage URL generation.
-- `codehawk/postgresql`: database client and code chunk repository.
-- `codehawk/code_index`: repo fetching, SAT runner, and code chunking.
+- `codehawk/postgresql`: database clients and repositories for code index, embeddings, convention KB, and review workflow state.
+- `codehawk/code_index`: repo fetching, SAT runner, Python code chunking, reference parsing, and embedding generation.
 - `codehawk/models`: DTOs and normalized context models.
+- `codehawk/utils`: deterministic validators and OpenAI retry helpers.
 
 More design context is available in [dev_docs/high_level_architecture.md](dev_docs/high_level_architecture.md).
 

README.zh-CN.md

@@ -18,7 +18,7 @@ English documentation: [README.md](README.md)
 - 使用 Ruff 和 Bandit 运行静态分析。
 - 使用 MinIO 存储仓库归档和 SAT 报告。
 - 对 Python 代码进行 chunk indexing，并写入 PostgreSQL。
-- 提供本地 Go CLI，可审查 staged、unstaged 或全部未提交改动。
+- 待实现：本地 Go CLI，用于审查 staged、unstaged 或全部未提交改动。
 - 使用 Docker Compose 启动 backend、MinIO 和 PostgreSQL。
 
 ## 技术栈
@@ -43,30 +43,41 @@ FastAPI Webhook Endpoint
         v
 GithubHandler
         |
-        +--> PR Summary Service --> PR Summary Agent --> GitHub Issue Comment
+        +--> PR Summary Service
+        |       +--> PR Summary Agent
+        |       +--> GitHub Issue Comment
         |
         +--> Code Indexing Service
         |       +--> Git Fetcher Container --> MinIO repo archive
         |       +--> SAT Runner Container --> MinIO SAT report
-        |       +--> Code Chunker --> PostgreSQL
+        |       +--> Code Chunker + Reference Parser --> PostgreSQL code index
+        |       +--> Embedding Builder --> PostgreSQL pgvector
+        |       +--> Convention Indexing --> Repository Convention KB
         |
         +--> Code Review Service
-                +--> SAT Summary Agent
-                +--> GitHub API Client
-                +--> Code Review Agent --> GitHub PR Review
+                +--> Workflow Run/Step State --> PostgreSQL
+                +--> SAT Summary JSON Agent
+                +--> Code Review Planning Agent
+                +--> Structural Evidence Agent --> Code index queries
+                +--> Convention Evidence Agent --> Convention KB + semantic search
+                +--> Evidence Validator
+                +--> Code Review Writer Agent
+                +--> Patch-line Review Output Validator
+                +--> GitHub PR Review
 ```
 
 主要模块：
 
 - `codehawk/api`：FastAPI 路由和 webhook endpoint。
 - `codehawk/handlers`：GitHub webhook 事件分发。
 - `codehawk/services`：PR 摘要、代码审查、代码索引等工作流编排。
-- `codehawk/agents`：AI agents 和 system prompts。
+- `codehawk/agents`：PR 摘要、SAT 摘要、评审规划、证据检索和 Review 生成 agents。
 - `codehawk/github`：GitHub 认证、installation token 缓存和 GitHub API client。
 - `codehawk/minio`：对象存储 URL 生成。
-- `codehawk/postgresql`：数据库连接和代码 chunk 写入。
-- `codehawk/code_index`：仓库拉取、SAT runner 和代码 chunking。
+- `codehawk/postgresql`：数据库连接，以及代码索引、embedding、仓库规范知识库和 Review workflow 状态仓库。
+- `codehawk/code_index`：仓库拉取、SAT runner、Python 代码 chunking、引用解析和 embedding 生成。
 - `codehawk/models`：DTO 和上下文模型。
+- `codehawk/utils`：确定性校验器和 OpenAI 重试辅助工具。
 
 更多架构说明见 [dev_docs/high_level_architecture.md](dev_docs/high_level_architecture.md)。