See through ambiguity. Build consensus with evidence. Chongming is a protocol-driven, multi-agent requirements-review workbench—not an untraceable group chat.
Chongming accepts a Markdown requirement and a controlled local-repository reference. Product, project, frontend, and backend roles independently submit Claims; conflicts enter constrained debate; a Judge produces a Gate draft; a human makes the final decision.
The name comes from the Chongming bird (重明鸟) in Shi Yi Ji (Records of Gleaned Relics) by Jin-dynasty writer Wang Jia. Tradition describes the bird as having double pupils in both eyes, with a gaze bright enough to see through disguises and drive away evil. The text also calls it Shuangjing (双睛, “double-pupilled”), describing it as driving away beasts and harmful evils; its image at a doorway signifies keeping out what should not enter.
That is a project metaphor, not a claim about mythology as system design:
| Chongming image | Meaning in this project |
|---|---|
| Double pupils | The same requirement is examined through multiple independent professional lenses, rather than by a single model answer |
| Seeing through disguise | Claims must be challenged by evidence, counterarguments, and protocol checks; plausible wording is not enough |
| Keeping harm from the doorway | A Gate sits before implementation: unresolved risk is surfaced for human review instead of silently passing downstream |
| A bird, not a judge | Chongming illuminates disagreement. It does not replace the accountable human who makes the final Gate decision |
This is why the project motto is “See through ambiguity. Build consensus with evidence.” Four core roles—product, project, frontend, and backend—form the initial set of perspectives. Optional architecture, test, security, and performance roles can be activated when the review needs them. Their task is not to manufacture agreement; it is to make the disagreement, evidence, and decision path visible.
The source text is available in Shi Yi Ji: “the Chongming bird”. The mapping above is Chongming’s product interpretation.
| Typical agent demo | Chongming constraint |
|---|---|
| A conclusion appears when the chat ends | Claims, challenges, rebuttals, judgements, and Gates are typed domain objects |
| Agents choose their own identity and permissions | The server rebinds review, attempt, role, version, and idempotency keys |
| Model output changes the workflow directly | ReviewProtocolGuard validates the state, role, and action before a command is committed |
| Only the final answer is visible | Business events have a global sequence and can be replayed through SSE |
| AI approves a requirement | AI produces a draft only; HUMAN_REQUIRED waits for a versioned human decision |
The project draws from two production-oriented open-source directions: AgentScope Java's controlled tool use, observability, and runtime intervention; and LangGraph's durable state and human-in-the-loop workflow model. Chongming narrows those ideas into a review protocol for software delivery.
| Capability | Status | Notes |
|---|---|---|
| Markdown intake and review workbench | Ready for local integration | Create a review with POST /api/reviews; UI entry is /review/ (login-protected) |
| Login authentication | Implemented | Username/password + JWT; a preset admin account ships with the workbench (PLAN-025) |
| Requirement lifecycle platform | Implemented | Dashboard, requirement CRUD/lifecycle, and review/report lists under /api/dashboard, /api/requirements/**, /api/reviews, and /api/reports |
| State machine, role authorization, idempotent commands | Implemented | Invalid stages, unauthorized roles, and replayed commands are rejected or safely replayed server-side |
| OpenAI-compatible model gateway | Implemented | Per-role model profiles, timeouts/backoff, and Tool Calls; runtime model is set via environment config; reasoning/thinking is not enabled by default and provider hidden reasoning is never exposed on the public stream |
| Local repository reads | Connected to role Harness | Roles only receive opaque fileRef values for their authorized snapshot scope; unauthorized paths are neither exposed nor charged against the read budget |
| Context Scout | Connected to runtime | Snapshot-first conversational tool flow that persists a conclusion contract (summary, module roots, entry points, constraints, risks, evidence paths, role scopes); degrades gracefully on budget exhaustion or model failure |
| Initial review | Connected to runtime | Core roles submit five-state Assessments plus Claims; a balanced-review obligation requires each role to record a SUPPORT claim where justified; required checkpoints are enforced |
| Requirement defense and dispatch protocol | Connected to runtime | DEFENSE/CHALLENGE/REBUTTAL directed envelopes; server validates role, stage, topic round, and idempotency; TTL + dedup; the defender (PRODUCT or the nearest active role) answers objector challenges with a SUPPORT claim |
| Deterministic challenge/rebuttal issuance | Implemented (PLAN-046) | The server auto-issues CHALLENGE when an opposed topic opens and when a defense SUPPORT commits, and issues the REBUTTAL envelope after every committed challenge; the coordinator steers convergence only |
| Debate, Judge, and Gate draft | Connected to runtime | Topic-level rounds (each topic ≤ 2 rounds inside a single DEBATE stage); judging begins when every topic is terminal; the Judge rules per topic and drafts the Gate |
| Plan revision closed loop | Implemented (PLAN-036) | The coordinator writes plans/PLAN.md; the server promotes each content change into a PLAN_REVISED event, runtime notice, and revision card |
| Domain events and SSE | Implemented | Sequenced events, historical replay, heartbeat, and incremental reconnect |
| Human review, reports, notifications | Core flow available | Notification supports a mail destination (PLAN-030); external MCP and production contracts still need real integration |
| MySQL persistence | Implemented | Migrations through V29 cover users, requirement lifecycle, review aggregate/events, topics/turns/judgements, dispatch commands, and topic public titles |
| Multi-instance recovery | Not complete | Runtime lease and startup-scan recovery remain gaps (tracked by CM-REQ-2026-001); the aggregate and dispatcher still have in-process boundaries |
| Security audit, evaluation, fault injection | Not complete | These are release gates, not substitutes for a local demo |
| Regression baseline | Verified | Backend ./mvnw.cmd test → 783 tests, 0 failures/errors, 30 environment skips; frontend vitest → 159 passed |
flowchart LR
A["Markdown requirement"] --> B["Create review / freeze snapshot"]
B --> S["Context Scout explores the snapshot"]
S --> C["Director plans (PLAN.md)"]
C --> D["Core-role Assessments + Claims"]
D --> E["Conflict detection / register topics"]
E --> F["Topic debate: defense / challenge / rebuttal"]
F --> G["Judge per topic + Gate draft"]
G --> H["Human review, versioned decision"]
S -. "persisted conclusion" .-> I["SSE stream / workbench"]
D -. "committed business events" .-> I
F -. "server-issued envelopes, serialized wake-up" .-> C
G -. "HUMAN_REQUIRED" .-> H
The runtime does not rely on a model voluntarily following the process. A model can only select an exposed Tool Schema; every tool call is validated server-side before it changes domain state. ReviewWorkflowDispatcher listens only to committed business events and serializes the next Agent wake-up within a review, preventing concurrent execution of the same Director session.
The review protocol has evolved through PLAN-023 → PLAN-054. Key mechanisms beyond the base state machine:
- Context Scout contract. After the snapshot is frozen, a dedicated Scout agent explores the repository within a bounded read budget and persists a conclusion contract—summary, module roots, entry points, constraints, risks, evidence paths, and per-role scopes. If the budget is exhausted or the model fails, the Scout degrades gracefully and the review continues.
- Plan revision closed loop. The coordinator writes the public plan to
plans/PLAN.mdin plan mode. The server watches the document and promotes each content change into a singlePLAN_REVISEDevent that refreshes the workbench plan card and runtime stream. A boilerplate initial plan is created at start but is not shown; only real revisions render as cards. - Requirement defense topology. A topic with only objections still has an implicit defender: the requirement itself. The coordinator dispatches DEFENSE to the product role (or the nearest active role), which must answer each objection with a SUPPORT claim. The direction is fixed—objectors interrogate, the defender answers.
- Deterministic challenge/rebuttal issuance. Challenges are no longer left to model discretion. When an opposed topic opens, the server auto-issues CHALLENGE to every role holding an OPPOSE claim; when a defense SUPPORT commits, the server auto-issues CHALLENGE to the objectors; after each committed challenge the server issues the REBUTTAL envelope to the challenged role. The coordinator steers round progression and convergence only.
- Topic-level debate lifecycle. Rounds are per-topic, not global. Each topic advances up to two rounds independently inside a single DEBATE stage;
begin_second_round(topicId)opens a second round for one topic only; judging begins once every topic is terminal. - Workbench form. The UI follows a minimal, de-bubbled design: streaming agent answers, tool calls collapsed into groups (single calls included), topic tabs, a claim full-text modal, and per-phase fixed-height internal scrolling inside a full-viewport layout with no page-level scrollbar.
| Layer | Responsibility | Current implementation |
|---|---|---|
| Interaction | Workbench, intake, query APIs, SSE | Vue 3/Vite static assets + Spring MVC |
| Domain | Review state machine, Guard, Claim, Debate, Judge, Gate | Java 21, Spring Boot, typed commands |
| Agent runtime | Director/Scout/role/Judge Harness, restricted tools, runtime dispatch | AgentScope Java Harness + bound runtime context |
| Model adapter | OpenAI-compatible calls, streaming, Tool Calls, retry | Model Gateway adapter |
| Events and storage | Sequenced events, SSE replay, MyBatis event store | MySQL write model in place (migrations V1–V29); in-memory fallback for local demo |
- JDK 21
- A working Maven Wrapper
- MySQL 5.6+ (the migrations do not require JSON columns)
- A model endpoint compatible with OpenAI Chat Completions and Tool Calling
Configure your workstation in src/main/resources/application-local.yml. Use it locally only and never commit secrets. The minimal structure is:
review:
persistence:
enabled: true
jdbc-url: jdbc:mysql://127.0.0.1:3306/chongming?characterEncoding=UTF-8
username: your_user
password: your_password
model-gateway:
enabled: true
base-url: https://your-openai-compatible-endpoint/v1
model-name: your_actual_model_name
api-key: your_api_key
log-conversation: true # local diagnosis only; turn it off afterwards
repositories:
allowed:
- id: your-repository-id
root: E:\\your\\local\\repositoryDo not leave model-name as a chongming-*-placeholder; the provider will return HTTP 404. log-conversation is for a controlled local debugging session only.
If a local configuration file was committed or shared, remove its credentials and rotate the database and model-gateway secrets immediately. Documentation must never become a vehicle for copying live credentials.
.\mvnw.cmd test
.\mvnw.cmd spring-boot:runOpen http://localhost:8080/review/. The workbench is login-protected (PLAN-025): sign in with the preset admin account (initial password Admin@123 — change it on first login) or register a new user. The default landing page is the requirement Dashboard; the legacy direct-review form remains at /review/#/create.
Frontend sources are in frontend/. After frontend changes, rebuild and commit the matching assets under src/main/resources/static/review/:
Set-Location frontend
npm test
npm run build- Create a review in the workbench, upload a
.mdfile, and choose a configured repository ID. - Use
mainor the target branch. Commit is optional; when supplied, it must be a 40-character SHA. - Observe the workbench SSE state and server logs. For model-gateway 401/404 errors, check the API key,
base-url, and actual model name first. - When a review stalls, query its state and SSE events before changing any database record directly.
Useful endpoints:
GET /api/reviews/{reviewId}— review aggregate state.GET /api/reviews/{reviewId}/plans— plan snapshot.GET /api/reviews/{reviewId}/debates— debate state and turns.GET /api/reviews/{reviewId}/claims— persisted claims.GET /api/reviews/{reviewId}/events— SSE event stream.POST /api/reviews/{reviewId}/canceland/retry— lifecycle commands.
The current version is suitable for local integration, demonstrations, and protocol validation. It is not yet a multi-instance production service. MySQL command persistence and the review/event write model are in place (migrations through V29), but before release the following are still required:
- Implement cross-instance database leases, startup scanning, resumable Agent work, and failure-to-human escalation (tracked by CM-REQ-2026-001).
- Connect real read-only repository snapshot/evidence scopes and complete model smoke tests and authorization audit.
- Complete MySQL replay load tests, security audit, fault injection, and evaluation baselines.
- Master implementation roadmap
- Harness and role orchestration
- Debate, Judge, and Gate
- Domain events, SSE, and recovery
- Human review, reports, and notification
- Requirement lifecycle platform
- Requirement defender, balanced review, and conflict expansion
- Coordinator plan revision closed loop
- Chinese topic titles
- Deterministic challenge issuance
- Topic-level debate lifecycle
- Requirement platform verification record
- Development rules
| Project | What we adopt | Chongming application |
|---|---|---|
| AgentScope Java | Controlled tool calling, runtime intervention, observability, multi-agent collaboration | Harness hosts roles while the review protocol and whitelist narrow the authority boundary |
| LangGraph | Durable execution, human-in-the-loop, state visibility | Human Gates and event replay are implemented; durable recovery remains a release gate |
Using an agent framework is not evidence of production readiness. The next benchmark milestone is durable execution, auditability, and evaluation—not adding more roles.
src/main/java/ai/cc/chongming/ Java production code
src/main/resources/ Application configuration and embedded workbench assets
src/test/java/ Unit and integration tests
frontend/ Vue 3/Vite source and frontend tests
docs/ Technical design, integration contracts, and phased plans
.agentscope/workspace/ Local Agent workspace (not committed)
.learnings/ Errors, requests, and reusable learnings
Every implementation change should update its matching AIREVIEW-PLAN-xxx, test evidence, and .learnings/ entry. Run tests appropriate to the change before submitting; frontend changes must also rebuild the embedded static assets. See AGENTS.md for the detailed rules.