trae-coding-engine 0.1.0

package/templates/.agents/skills/coding-architecture/SKILL.md

@@ -0,0 +1,347 @@
+---
+name: coding-architecture
+description: Use when adding features, new aggregates, new ports, or architecture-level adapters to coding_engine.
+---
+
+# coding-architecture: DDD Architecture Reference
+
+## Layer Map
+
+```
+internal/
+  domain/<aggregate>/       ← pure production Go; no framework imports
+  application/<domain>/     ← orchestrates domain; owns ports
+  application/port/         ← secondary port interfaces (non-persistence)
+  adapters/inbound/http/    ← Hertz HTTP handlers
+  adapters/outbound/<name>/ ← concrete port/repository implementations
+  bootstrap/<binary>/       ← wiring: fx Module (server, gateway, worker, daemon, cli)
+```
+
+Dependency direction: `bootstrap` → `adapters` → `application` → `domain`.
+Imports point inward only. Never import outward/upward; in particular, never
+import `adapters` or concrete external clients from `application`.
+
+
+## Layer Responsibilities
+
+### `domain/<aggregate>/`
+| File | Contents |
+|------|----------|
+| `entity.go` | Aggregate root, entities, value objects |
+| `repository.go` | Persistence port interface (CRUD, List) |
+| `types.go` / `status.go` | Enums and type aliases |
+
+- No framework imports in production domain files — pure Go structs and interfaces. The only allowed
+  `pkg/platform/*` dependency is `pkg/platform/uuid` as the shared ID value
+  type; see ADR 0049.
+- `_test.go` files and generated mocks under `internal/domain/**` may depend
+  on test infrastructure such as `go.uber.org/mock`, `github.com/stretchr/testify`,
+  and `internal/testutil`; those dependencies must not leak into non-test
+  domain files.
+- Cross-cutting types (IDs, shared enums) live in `domain/shared/`.
+- Domain events live in `domain/events/`.
+- Domain-local validation or serialization failures use
+  `domain/shared.DomainError`; application/adapter boundaries map those errors
+  to `pkg/platform/errno`.
+- Do not create aggregate-local sentinel errors (`domain/<agg>/errors.go`,
+  `port.ErrXxx`, adapter-local `ErrXxx`) for business semantics.
+
+### `application/<domain>/`
+| File | Contents |
+|------|----------|
+| `service.go` | `Service` interface + `ServiceDeps` struct + `NewService(ServiceDeps) Service` |
+| `dto.go` | Request/response structs |
+| `mapper.go` | `domain ↔ DTO` conversion functions |
+
+Boundary review rule:
+- `application` code may use shared value/helper packages such as
+  `pkg/platform/logger`, `pkg/platform/errno`, `pkg/platform/uuid`,
+  `pkg/platform/retry`, and `pkg/platform/validate`. Do not flag those imports
+  alone as a hexagonal-architecture violation.
+- Flag a violation when application code imports `internal/adapters/**`,
+  concrete infrastructure packages such as `pkg/platform/redis`,
+  `pkg/platform/gormdb`, or `pkg/platform/telemetrydb`,
+  database/Redis/Kubernetes/HTTP SDK clients, or a third-party service SDK as
+  an external capability. Model that capability behind a domain repository or
+  `application/port` interface and implement it in an outbound adapter.
+
+Service constructor pattern (always this shape):
+```go
+type ServiceDeps struct {
+    Repo   domain.Repository
+    SomePt port.SomePort   // only what this service actually needs
+    Log    logger.Logger    // required when the service logs
+}
+func NewService(deps ServiceDeps) Service { ... }
+```
+
+Logger injection rule:
+- Application/business code must not silently replace a missing logger with `logger.NewNop()`.
+- If a service/use case needs logging, include `Log logger.Logger` in deps and fail fast in the constructor when it is nil.
+- Wire real loggers from `bootstrap/*`; tests may pass `logger.NewNop()` explicitly.
+- `make check-skills` fails on `logger.NewNop()` in non-test `internal/application/**` code.
+
+Context propagation rule:
+- Public service, port, repository, handler, and adapter methods that receive
+  `ctx context.Context` must pass that ctx through to helper methods, outbound
+  calls, logs, Redis/DB operations, and cleanup that still belongs to the same
+  request or worker message.
+- Do not introduce `context.Background()` or `context.TODO()` to bypass a
+  caller's cancellation, deadline, tenant/log fields, or trace values. For
+  cleanup that must outlive caller cancellation, prefer
+  `context.WithoutCancel(ctx)` plus a bounded timeout so values still propagate.
+- If a call chain loses ctx because an interface, port, callback wrapper, or
+  helper signature does not expose it, update that signature and its callers.
+  Do not add an allowlist entry just to preserve a ctx-less interface.
+- Allowed root contexts are narrow: binary entrypoints, component lifecycle
+  roots, detached periodic workers, third-party callbacks with no inbound Go
+  context, and best-effort shutdown/cleanup paths. New exceptions must be
+  explicitly allowlisted in `scripts/check-context-propagation.py` with a
+  rationale. Keep allowlist rules narrow (specific path + line pattern) and
+  delete them when the code can use `context.WithoutCancel(ctx)` instead.
+- Run `make check-context-propagation` after touching context flow, background
+  workers, lifecycle glue, or any new use of `context.Background()` /
+  `context.TODO()`.
+- `make check-context-nil` is a separate guard: it catches `nil` passed to
+  `context.Context` parameters, including tests. `golangci-lint` context
+  linters do not replace either custom guard.
+
+Error handling rule:
+- In this section, `should` / `prefer` mark the review default; `must` marks a hard gate.
+- `errno.BizError` is the only business error type crossing backend layers
+  outside `internal/domain/**`. Domain methods return
+  `shared.DomainError`; map them with the helper in
+  `internal/application/domainerr/errors.go` before crossing
+  application/adapter boundaries.
+- Do not define layered business errors and then translate them later. Repos,
+  adapters, ports, services, and handlers should use `errno.New`,
+  `errno.NewWithMessage`, `errno.WrapWithMessage`, or `errno.Ensure` when they
+  own stable business semantics.
+- Prefer converting raw errors at the lowest boundary where the semantics are
+  known. Log exactly once at that same boundary when a logger is available, then
+  return the `BizError`. If the lowest repo/helper has no logger, it can still
+  return an `errno.BizError`; the first owning service/adapter with a logger logs
+  it once.
+- Upper layers that receive an existing `BizError` should return it unchanged
+  unless they are intentionally changing business classification. Avoid wrapping
+  an already-classified `BizError` only to add context.
+- Go-native `fmt.Errorf("...: %w")` wrapping is acceptable for internal
+  control-flow errors, retry markers, redelivery / poison decisions, protocol
+  control errors, and debugging context where no stable business code is owned
+  yet. Debugging context means internal logs, audit fields, run metadata, and
+  similar internal carriers; it must not bypass `BizError` / generic-copy
+  boundaries at HTTP/TOP or user-visible payload exits.
+- Upper layers branch with `errno.IsCode(err, code)` / `errno.CodeOf(err)`;
+  never with `errors.Is(err, domain.ErrXxx)` for business semantics.
+- Use existing semantic codes first: `InvalidArgument`, `NotFound`, `Conflict`, module NotFound / Publisher / WebChat codes. Use broad infrastructure codes only when no domain code fits:
+  - `PersistenceError` for database / repository non-business failures.
+  - `RedisDependencyError` for Redis, Redis Streams, session lease / presence failures.
+  - `ModelDependencyError` for AIGW / LLM / model service failures.
+  - `ObjectStorageDependencyError` for artifact / object storage failures.
+  - `SkillHubDependencyError` for Ark Skill Hub failures.
+  - `ExecutionLaneDependencyError` for run dispatch lane failures.
+  - `FileDependencyError` for filesystem failures.
+  - `ChannelDependencyError` for Feishu / WeCom channel platform failures.
+  - `ExternalDependencyError` only as a temporary fallback for dependencies that are not yet split.
+  - `RuntimeProviderError` for runtime executor/controller/provider failures.
+  - `ConfigurationError` for runtime config missing/invalid.
+  - `SerializationError` for JSON/protobuf/thrift/event payload encode/decode failures.
+- Prefer `errno.Ensure(code, err)` at migration boundaries: it preserves an existing `BizError` and wraps only raw errors.
+- Prefer `errno.Log(ctx, log, msg, err, fields...)` for classified failures so logs carry consistent `error_code` / `biz_code` fields.
+- HTTP/TOP exits must not rewrite existing `BizError`; they return `BizError.Message`, or the code default message when empty. Non-`BizError` exits fall back to `InternalError`.
+- User-visible text must not expose raw dependency/provider/network error strings. Surface product-reviewed `BizError.Message` when available; otherwise use generic copy and keep the raw cause in logs or internal audit fields.
+
+### `application/port/`
+Secondary ports for external capabilities that are NOT persistence. Current inventory:
+
+| File | Interface | Used by |
+|------|-----------|---------|
+| `event_bus.go` | `Bus (+ Publisher, Subscriber)` | domain event fan-out |
+| `event_publisher.go` | `EventPublisher` | one-way event emission (decoupled from bus impl) |
+| `execution_lane.go` | `ExecutionLane` | run dispatch lane (locallane / redislane) |
+| `message_bus.go` | `MessageBus` | inbound/outbound message transport |
+| `message_reader.go` | `MessageReader` | read-side of the message bus |
+| `transaction.go` | `TransactionManager` | application service transaction boundary |
+| `artifact_server.go` | `ArtifactServer` | Artifact storage backed by UP SDK |
+| `aigw.go` | `AIGWProvider` | AIGW model gateway access |
+| `llm.go` | `LLM` | LLM invocation |
+| `session_lease.go` | `SessionLease` | session lease (Redis-backed) |
+| `trace_store.go` | `TraceStore` | run trace persistence |
+| `user_resolver.go` | `UserResolver` | resolve identity from request context |
+| `ark_skill_hub.go` | `ArkSkillHub` | Ark Skill Hub access |
+| `channel.go` | `ChannelInterface (+ StreamingChannel, WebhookChannel, BlockReplyChannel, GroupMemberProvider)` | gateway channel manager + feishu/wecom channel adapters |
+| `clawsentry.go` | `ClawSentry (+ ClawSentryFactory)` | security ClawSentry provisioner (OpenTOP API, per-agent credentials) |
+| `cron_event_publisher.go` | `CronEventPublisher` | agent + task services (cron-triggered event emission) |
+| `hiagent_up.go` | `HiAgentUPUploader` | evolution service (HiAgent UP artifact upload) |
+| `mcp.go` | `MCPConnectionTester` | mcp service (test MCP server connectivity) |
+| `metrics.go` | `Metrics (+ NoopMetrics)` | observability counters/histograms across worker, message buses, repos |
+| `presence.go` | `PresenceWriter`, `PresenceReader` | worker presence maintainer + agent ownership lookup (ADR 0018) |
+| `session_key_locker.go` | `SessionKeyLocker (+ NoopSessionKeyLocker)` | session service cross-replica session-key uniqueness (ADR 0069) |
+| `user_password_verifier.go` | `UserPasswordVerifier` | runtime API key handler + IAM adapter |
+| `workspace_spec.go` | `SpecCatalog` | env service + gateway spec resolution (ADR 0057) |
+
+Conventions:
+- Each interface file has `//go:generate go run go.uber.org/mock/mockgen ...` at the top.
+- Mocks land in `application/port/mocks/`. Run `make generate` after adding a new interface.
+- Helper-only files live alongside ports so callers don't reach into adapters.
+- Helper / type-only files in this directory carry no port interface (so no
+  mockgen): `channel_health.go` (shared `ChannelHealth` snapshot types +
+  `ClassifyChannelError` for the `channels.status` surface), `retryable.go`
+  (`Retryable` / `IsRetryable` markers tagging transient `ExecutionLane`
+  failures for redelivery), and `wakeup.go` (`Wakeup` signal type that nudges a
+  worker to drain a session's durable inbox — L2 ordering).
+- This directory holds **infrastructure capability ports only**. Cross-context
+  consumer ports live with the consumer context (see below).
+
+#### Cross-Context Consumer Ports (ADR 0058)
+
+When context A consumes context B's application service in-process (e.g.
+evolution → agent/message/skill), the port and its anti-corruption adapter are
+**consumer-owned** and live under the consumer:
+
+```
+application/<consumer>/port/   ← narrow interfaces + consumer-vocabulary types; mockgen → port/mocks/
+application/<consumer>/acl/    ← ACL adapters wrapping B's application service (forwarding + DTO→port mapping only)
+```
+
+Rules:
+- `acl/` is the only package in the consumer subtree allowed to import other
+  contexts' application packages; business files depend on `<consumer>/port`
+  interfaces only.
+- No Go `internal/` segment on `acl/` — bootstrap must import it for wiring.
+- Never inject another context's `Service` interface or domain repository
+  directly across a context boundary; never bypass B's service to write its
+  repositories.
+- Canonical example: `application/evolution/{port,acl}` wired in
+  `bootstrap/evoworker`.
+
+#### Artifact Skill Storage
+
+`port.ArtifactServer` is backed by the UP SDK. Skill artifacts are addressed by UP object ID / sha256, not by S3-style paths. Runtime workspace sync resolves enabled `agent_skills` bindings to presigned artifact download URLs and lets runtime init-container / hot-sync Job download zip packages directly into the agent PVC.
+
+Canonical example — `application/agent/workspace_sync.go`:
+```go
+type WorkspaceSyncDeps struct {
+    SkillStore port.ArtifactServer
+}
+```
+
+The factory that wires the right provider per binary is shared: `internal/bootstrap/app/storage.go`. Both server and worker call into it; do **not** re-derive provider selection logic in `bootstrap/server/module.go` or `bootstrap/worker/registry.go`.
+
+### `adapters/outbound/<name>/`
+Implements one or more domain/port interfaces.
+- RDB repos: `adapters/outbound/persistence/rdb/repository/<aggregate>_repository.go`
+- Repository test doubles belong in test packages or generated domain mocks, not under `adapters/outbound/persistence/`
+- Runtime provider adapter details live in `coding-runtime-adapter`.
+- Port impls: `adapters/outbound/<capability>/` (e.g. `artifact/`, `aigw/`, `arkskillhub/`)
+
+RDB repository transaction rule:
+- Repositories do not open, commit, roll back, or branch on transactions. All
+  SQL transaction boundaries belong in application services/use cases through
+  `port.TransactionManager`.
+- Main rdb repositories use one DB/context entrypoint: `rdb.DB(ctx, r.db)` or a
+  local `conn(ctx)` wrapper that delegates to it. Do not expose secondary
+  public helpers for transaction-aware DB selection.
+- Repository methods that require an existing transaction because they use row
+  locks or multi-statement read-modify-write must call
+  `rdb.RequireTransaction(ctx)` and use the returned DB handle.
+- Any rdb repository / PO / mapper / constructor change must run
+  `make check-repository-transactions`; see `coding-db-schema` and
+  `coding-testing` Strategy 5.
+
+#### Redis Deployment Compatibility
+
+Every Redis-backed adapter must support all configured Redis modes: `single`,
+`sentinel`, and `cluster`. Sentinel command semantics are single-primary, but
+Cluster enforces hash-slot rules.
+
+- Multi-key commands, transactions, and Lua scripts must keep all keys in the
+  same slot with an explicit hash tag, e.g. `lease:session:{sessionID}` and
+  `lease:session:{sessionID}:gen`.
+- Lua scripts must receive every Redis key through `KEYS`; do not build hidden
+  Redis key names inside the script body.
+- Pipelines may batch independent single-key operations, but must not assume
+  cross-key atomicity unless the keys share a hash tag and the command itself is
+  Cluster-safe.
+- Redis Streams commands should operate on one stream key per command. If a new
+  operation needs multiple streams/keys in one Redis command, add a shared hash
+  tag or redesign the operation.
+- Use `pkg/platform/redis` only for shared Redis invariants, not as a blanket
+  wrapper around go-redis:
+  - `Tagged(prefix, tag, suffix...)` for newly constructed hash-tagged keys when
+    invalid identity data should fail before Redis is called.
+  - `AssertSameSlot` for logical multi-key operations.
+  - `NewScript` for Lua scripts that should fail fast on cross-slot `KEYS`.
+- `Tagged` is strict by design: callers must handle `(string, error)` and must
+  not trim, normalize, hash, strip braces, or silently replace invalid tags.
+  Existing legacy key formats may stay local when changing them would split
+  locks, leases, channels, or live data during rolling upgrades; document that
+  compatibility reason near the helper.
+- Keep adapters close to `github.com/redis/go-redis/v9`. Direct go-redis imports
+  are fine; do not add platform-level type aliases or thin wrappers unless they
+  enforce a real shared invariant.
+- When adding or materially changing Redis Streams consumer logic, first check
+  whether it should share infrastructure with eventbus/messagebus. Do not copy
+  claim, retry, dead-letter, consumer group, or ordered-lane machinery into a
+  third implementation without an explicit reason.
+- Tests must assert cluster-safe key naming for Lua or any logical operation
+  that touches more than one Redis key.
+- Redis-backed code changes must also compile all integration tests and run the
+  corresponding `tests/integration/redis_*` coverage against real Redis
+  testcontainers; see `coding-testing` Strategy 3 and Strategy 5.
+
+#### Persistence Implementation Rule
+
+`persistence/rdb` is the canonical implementation of domain repository contracts. Do not add a second repository implementation under `internal/adapters/outbound/persistence/` for local mode or unit tests.
+
+Minimum bar:
+- New persisted aggregates implement the domain repository contract in `internal/adapters/outbound/persistence/rdb/repository/`.
+- RDB repository behavior is proved by integration coverage under `tests/integration/`.
+- Application unit tests use generated domain mocks or narrow same-package fakes for pure service validation. Use package-local RDB / sqlite fixtures only when the application workflow materially depends on persistence semantics such as transaction boundaries, SQL ordering/filtering, uniqueness, or cross-repository state. Do not add reusable persistence adapters or a shared application-level RDB testutil just for convenience.
+- Local / all-in-one runtime modes may use in-process buses and lanes, but still use the normal database for persistence.
+
+### `bootstrap/<binary>/`
+- **All binaries use `go.uber.org/fx`.** Each `bootstrap/<binary>/module.go` declares a root `var Module = fx.Module(...)` composed of sub-modules; `Build()` builds the graph via `fx.New(...)`, calls `Start`, and returns an `app.Hook` wrapping `Stop`. `provide*` functions return typed **interfaces**, not structs. The fx event logger is shared via `app.NewFxLogger`.
+- **coding-worker** has a local/distributed transport split: `LocalInfraModule` uses RDB repositories with in-process buses/lanes, while `DistributedInfraModule` uses RDB repositories with Redis buses/lanes. The split is picked at build time based on `cfg.Worker.Mode`. `ProvideProviderRegistry(...)` (in `registry.go`) is wrapped by an fx provider that binds the InstanceWatcher context to the fx Lifecycle; it stays directly callable from `registry_test.go`.
+- **coding-cli** wraps each cobra subcommand invocation in a per-process `fx.App` so config + logger (and any future deps) live on the same DI graph as the long-running services.
+- All binaries use `app.Runtime[C]` from `bootstrap/app/`. Config embeds `app.BaseConfig` by **value** (not pointer). Implement `app.Validator` for semantic validation.
+
+
+## Adding a New Aggregate Checklist
+
+- [ ] `domain/<agg>/entity.go` — aggregate root, no framework
+- [ ] `domain/<agg>/repository.go` — persistence interface
+- [ ] Use `domain/shared.DomainError` for domain-local errors; map to
+      `pkg/platform/errno` at application/adapter boundaries; do not add
+      `domain/<agg>/errors.go`
+- [ ] `adapters/outbound/persistence/rdb/po/<agg>.go` — GORM model, if this aggregate is persisted in SQL
+- [ ] `adapters/outbound/persistence/rdb/repository/<agg>_repository.go` — GORM impl
+- [ ] `tests/integration/<agg>_repository_test.go` — persisted behavior across supported DBs
+- [ ] `application/<agg>/service.go` — `Service` interface + `ServiceDeps` + `NewService`
+- [ ] `application/<agg>/dto.go` + `mapper.go`
+- [ ] `adapters/inbound/http/handlers/<agg>_handler.go` — Hertz handler
+- [ ] `bootstrap/server/module.go` — add `provide<Agg>Repository` + `provide<Agg>Service` + `provide<Agg>Handler` to `Module`
+
+
+## Adding a New Port Checklist
+
+- [ ] Define interface in `application/port/<capability>.go`
+- [ ] Add `//go:generate mockgen` directive; run `go generate ./internal/application/port/...`
+- [ ] Implement in `adapters/outbound/<capability>/<impl>/`
+- [ ] Wire in `bootstrap/server/module.go` with a `provide<Capability>` function
+
+For a **cross-context consumer port** (context A calling context B's
+application service), use `application/<consumer>/port/` +
+`application/<consumer>/acl/` instead — see "Cross-Context Consumer Ports"
+above (ADR 0058).
+
+
+## Key Types Quick Reference
+
+| Symbol | Package | Purpose |
+|--------|---------|---------|
+| `shared.TenantID` | `domain/shared` | Tenant identifier (string alias) |
+| `shared.AgentID` | `domain/shared` | Agent identifier (uuid.UUID alias) |
+| `app.Runtime[C]` | `bootstrap/app` | Entry point for all binaries |
+| `app.Component` | `bootstrap/app` | `Run(ctx) error` + `Shutdown(ctx) error` |
+| `app.BaseConfig` | `bootstrap/app` | Embed by value in every service `Config` |

package/templates/.agents/skills/coding-code-review/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: coding-code-review
+description: General-purpose diff-based code review orchestration for clean canonical diff generation, reviewer dispatch, and report consolidation without re-reviewing code.
+---
+
+# coding-code-review
+
+This file is only the orchestration layer. Keep the hot path short: prepare `code-review/`, generate the branch diff, canonicalize it, dispatch scoped reviewer subagents, then consolidate existing reviewer reports.
+
+## Default Entry
+
+Direct `/coding-code-review` runs a branch pre-MR review.
+
+Default input is the committed branch delta:
+
+- base: `origin/release`
+- scope: `merge-base(origin/release, HEAD)..HEAD`
+- worktree requirement: clean
+- artifacts:
+  - raw diff: `./code-review/raw-diff.txt`
+  - canonical diff: `./code-review/diff.txt`
+  - reviewer reports:
+    - `./code-review/correctness-code-review-report.md`
+    - `./code-review/architecture-code-review-report.md`
+    - `./code-review/compatibility-ops-code-review-report.md`
+    - `./code-review/test-code-review-report.md`
+  - final report: `./code-review/final-code-review-report.md`
+
+If the worktree has staged, unstaged, or untracked changes, `get-diff.sh` fails. Stop immediately. Do not auto-commit, stash, restore, clean, switch to `git diff`, or reuse old `code-review/` artifacts.
+
+## Workflow
+
+### 1. Prepare Diff
+
+Do not read old reports or inspect source before this step. Start by replacing the old `code-review/` directory and running the helper scripts:
+
+```bash
+rm -rf code-review
+mkdir -p code-review
+bash .agents/skills/coding-code-review/scripts/get-diff.sh --base-ref origin/release --output code-review/raw-diff.txt &&
+  cp code-review/raw-diff.txt code-review/diff.txt &&
+  bash .agents/skills/coding-code-review/scripts/canonical-diff.sh code-review/diff.txt
+```
+
+If `get-diff.sh` exits non-zero, stop. Do not continue to reviewer dispatch or final consolidation.
+
+If `raw-diff.txt` is empty, write `No changes to review` to `final-code-review-report.md` and stop. If `diff.txt` becomes empty after canonicalization, write `No reviewable changes after canonicalization` to `final-code-review-report.md` and stop.
+
+### 2. Dispatch Reviewers
+
+Load `references/reviewer-profiles.md` before dispatching reviewers. Reviewer identity is a review scope, not a model choice. Use these default reviewer profiles:
+
+- `correctness-code-reviewer`
+- `architecture-code-reviewer`
+- `compatibility-ops-code-reviewer`
+- `test-code-reviewer`
+
+Each scoped reviewer must focus on its assigned profile. Cross-scope findings are allowed only when needed to explain impact; otherwise mark unrelated dimensions as `N/A` or briefly defer to the responsible reviewer.
+
+For CLI environments with subagents:
+
+1. Dispatch every default reviewer profile in parallel against `./code-review/diff.txt`, then wait for all available reviewer reports or timeouts.
+2. Each reviewer must write only its own scoped report file listed above.
+3. Each reviewer report must be written in Chinese. Keep fixed severity labels (`[Critical]` / `[Major]` / `[Minor]` / `[Suggestion]`) and check status values (`PASS` / `RISK` / `N/A`) unchanged.
+4. Each reviewer has a 3 minute limit.
+
+For coco / Trae CLI:
+
+- List `.coco/agents/*-code-reviewer.md`; these files are tool-specific wrappers for the same reviewer profiles.
+- Do not dispatch reviewer agents named by model provider. Model selection belongs to the tool wrapper, not to reviewer identity.
+
+For Codex:
+
+- Use the project-scoped custom agents in `.codex/agents/*-code-reviewer.toml`.
+- Spawn the same default reviewer profiles in parallel, wait for all reviewer reports, then consolidate them.
+- Codex reviewer agents inherit the parent sandbox so they can write their own report artifact. They must not edit repository source files.
+
+For Claude Code:
+
+- Use the project-scoped custom agents in `.claude/agents/*-code-reviewer.md`.
+- Spawn the same default reviewer profiles in parallel, wait for all reviewer reports, then consolidate them.
+- Claude reviewer agents should use only read/search tools plus `Write` for their own report artifact. They must not edit repository source files.
+
+For CLI environments without subagents:
+
+- Load `references/reviewer-guidelines.md` and run one single-model review using the same artifact paths and output format.
+
+### 3. Consolidate Reports
+
+Only after reviewer reports exist, load `references/final-consolidation.md`.
+
+Final consolidation merges existing reviewer reports. It is not a new review pass. Do not re-read source, re-check the diff, search for new issues, or add findings not present in reviewer reports.
+
+Write the final report to `./code-review/final-code-review-report.md`.
+The final report must be written in Chinese, except for fixed severity labels and check status values.

package/templates/.agents/skills/coding-cve-remediation/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: coding-cve-remediation
+description: 处理 coding_engine 的 Codebase 镜像漏洞扫描结果。适用于查看 scan-image-* 镜像扫描 job、读取 image-scanner 报告、分类 CVE，并只修复 coding-engine、coding-inner-mcp-sidecar、coding-collector 中可由 Go 依赖升级解决的漏洞；OS/base image 漏洞只报告为范围外。
+---
+
+# coding-cve-remediation：镜像 CVE 修复
+
+当 coding_engine MR 中的 Codebase `scan-image-*` 镜像扫描 job 报告漏洞时使用本 skill。
+
+## CI 凭证
+
+CVE 报告读取只需要本 skill 自己的 `IMAGE_SCANNER_TOKEN`，作为 HTTP header `Image-Scanner-Token`。
+`bytedcli` / `codebase` 的 CI bot 凭证按仓库通用 Codebase 自动化约定配置，不在本 skill 中重复展开。
+
+## 范围
+
+只处理评分 `>= 7` 的漏洞。
+
+范围内：
+
+- 根模块、collector build manifest 中的 Go module 漏洞。
+
+范围外：
+
+- OS package、Debian/apt、发行版包、静态 base image 漏洞。
+- Dockerfile base image tag 修改。
+- 共享 base image 重建。
+
+如果评分 `>= 7` 的漏洞全部是 OS/base-image 类漏洞，输出：
+
+```text
+当前无可由 Go 依赖修复的 CVE
+```
+
+此时关闭第一步创建的 CVE 自动扫描 MR，不保留空 MR。
+
+除非用户另行明确要求，不要修改 Dockerfile 或 base image tag。
+
+## 创建扫描 MR
+
+先创建一个空的 CVE 修复 MR，用于触发 image build / scan-image 流水线：
+
+```bash
+bash scripts/cve-remediation-open-mr.sh
+```
+
+脚本会从 `origin/release` 创建唯一 bot 分支，并写入 `cve-remediation-mr.md`。后续修复必须继续推到这个 bot 分支对应的同一个 MR，不要另开第二个 MR。
+
+## 收集扫描报告
+
+1. 从 `cve-remediation-mr.md` 或 Codebase 响应中拿到 MR 号和 bot 分支。
+
+2. 查询 MR 状态和 checks：
+
+```bash
+bytedcli --json codebase mr status <mr>
+bytedcli --json codebase checks list --branch <branch> --mr <mr>
+```
+
+3. 定位三个扫描 job。
+   - `scan-image-coding-engine`
+   - `scan-image-coding-inner-mcp-sidecar`
+   - `scan-image-coding-collector`
+   - 自动等待目标扫描 job 完成；不要要求用户手工确认。
+   - 如果它依赖的 image build job 失败，报告对应镜像构建失败并停止处理该镜像。
+   - 从每个扫描 job 的输出 URL 中提取 `group_id`，URL 形态通常为 `.../task_center/report/<group_id>?original=1&fixed_version=0`。
+
+4. 拉取并汇总 image-scanner 报告：
+
+```bash
+python3 .agents/skills/coding-cve-remediation/scripts/image_scanner_report.py <group_id> --summary
+```
+
+CI 使用 `IMAGE_SCANNER_TOKEN`。本地调试仍兼容 `~/.config/image-scanner/token`。
+
+## 镜像到模块的映射
+
+固定使用以下修复映射：
+
+| 镜像 | 修复目标 |
+|---|---|
+| `coding-engine` | 根目录 `go.mod` |
+| `coding-inner-mcp-sidecar` | 根目录 `go.mod` |
+| `coding-collector` | `configs/otelcol-build-config.yaml` |
+
+对于 `coding-collector`，不要直接手改生成的 `coding-otelcol/go.mod`。
+
+## 修复 Go 依赖
+
+根模块：
+
+1. 从报告中确认漏洞涉及的模块和 fixed version，只升级相关模块。
+2. 在对应模块目录运行：
+
+```bash
+go get <module>@<fixed_version>
+go mod tidy
+```
+
+Collector：
+
+1. 在 `configs/otelcol-build-config.yaml` 中升级直接 collector component 版本。
+2. 如果传递依赖必须强制到 fixed version，在 manifest 的 `replaces` 中增加覆盖。
+3. 重新生成 collector：
+
+```bash
+make gen-collector
+```
+
+## 更新同一个 MR
+
+完成依赖修复和本地验证后，把修复 diff 推回第一步创建的 bot 分支：
+
+```bash
+bash scripts/cve-remediation-open-mr.sh --branch <bot/cve-remediation-...>
+```
+
+如果扫描后确认没有需要提交的 Go 依赖或 collector manifest 修复，也运行同一命令；脚本会关闭这个无需修复的 MR。不要重新创建新的 CVE 修复 MR。
+
+## 验证
+
+按变更面运行最窄必要检查：
+
+| 变更面 | 必跑检查 |
+|---|---|
+| 只改 CI YAML / skill | `make lint-yaml`、`make check-skills` |
+| 根目录 `go.mod` / `go.sum` | `make test` |
+| collector manifest | `make gen-collector`、`make build-collector` |
+
+运行 `make regen-agent-md` 后，确认 worktree 只有预期文件变化。
+
+## 自动提交 MR 脚本
+
+CI 场景使用 bot 提交 MR，不使用人类 credential，不运行 `bytedcli auth status`，也不走 `make open-mr`。
+
+第一次运行用于创建空提交 MR 并触发扫描；带 `--branch <bot/cve-remediation-...>` 再次运行用于更新同一个 MR。
+
+该脚本复用 `scripts/lib/codebase-mr-bot.sh`，行为边界：
+
+- 从 `origin/release` 创建唯一 bot 分支。
+- 只允许提交 CVE Go 依赖修复相关文件：根 `go.mod` / `go.sum`、`configs/otelcol-build-config.yaml`、`coding-otelcol` 生成的 Go module / Go 文件。
+- 用 Codebase bot 身份执行 `codebase mr create`，不检查人类登录态。
+- 有修复 diff 时提交修复；没有修复 diff 时提交空 commit 触发首次 scan-image。
+- `--branch` 且没有修复 diff 时关闭同一个 MR。
+- 后处理失败应写入 `cve-remediation-mr.md` 并报告，不要求人工介入。
+- Git author 固定为 `coding-cve-remediation-bot <coding-cve-remediation-bot@bytedance.com>`。
+
+推送后的 CI 验证：
+
+- 确认三个 image build job 都成功。
+- 确认三个 `scan-image-*` job 分别在对应 image build job 之后运行，且彼此不互相依赖。
+- 确认扫描报告中不再包含评分 `>= 7` 的 Go 依赖漏洞。
+
+## 最终输出
+
+最终只报告：
+
+- 评分 `>= 7` 的漏洞。
+- 分类：Go 依赖 / OS-base image / 未分类。
+- 修改过的文件。
+- 已执行的依赖升级。
+- 验证命令和结果。
+- 剩余阻塞项。