trae-coding-engine 0.1.0

package/templates/AGENTS.md

@@ -0,0 +1,179 @@
+# Coding Engine — AI Agent Guidelines
+
+Enterprise multi-tenant distributed digital-employee agent platform. Go. Hexagonal architecture (Ports & Adapters).
+
+> This file is the **routing layer** — what gates apply, which skill owns each path. Procedural detail lives in skills; load the matching skill **before** editing its paths.
+
+## See also
+
+- Dev SOP (humans) → `vibe-coding.html` · Onboarding → `onboarding.html` · Claude Code entry map → `CLAUDE.md`
+
+## Architecture
+
+```
+cmd/                          binary entrypoints (thin; coding-engine dispatches components)
+internal/
+  domain/                     core models & interfaces (zero production external deps)
+  application/                use cases & orchestration
+  adapters/{in,out}bound/     HTTP/gRPC inbound; DB/runtime/eventbus outbound
+  components/                 in-process component runtimes (e.g. gateway/)
+  platform/                   component-private infra (no business semantics)
+  bootstrap/                  fx wiring per component
+api/ deployments/ configs/    contracts · unified Helm + helmfile · local *.yaml(.example)
+docs/ pkg/ tests/             component docs/ADRs · exported helpers (pkg/platform) · build-tagged integration
+```
+
+Dependency rule: `domain` ← `application` ← `adapters` ← `bootstrap`.
+Imports point inward only; never import outward to adapters/bootstrap or concrete implementations.
+
+## Done Gates
+
+A task is **not** done until every applicable gate runs. Gates are independent and non-substitutable.
+
+| # | Gate | Triggers on | See |
+|---|---|---|---|
+| 1 | Docs Verification (incl. OpenAPI HTML sync) | API / IDL / env / resource naming / lifecycle changes; any `api/idl/*.thrift` surface change (TOP Action add/remove/rename, request/response struct, field) additionally requires `make check-openapi` | §Docs Verification Gate |
+| 2 | Deployment Config Sync | YAML key add/remove/rename, default change, image repo/tag, probe/service port, DSN, credential / Secret field, runtime adapter config struct | skill `coding-deploy-config` |
+| 3 | Testing Done Checklist | Any code change | skill `coding-testing` |
+| 4 | Redis Deployment Compatibility | Any Redis command/key/Lua/Streams change | §Redis Deployment Compatibility Gate |
+
+## Docs Verification Gate
+
+If the change touches API endpoints, TOP Action IAM registration, IDL/protobuf/thrift, config keys, K8s resource naming, or important lifecycle (startup/shutdown/error flow):
+
+```bash
+grep -r "<changed identifier / interface / resource name>" docs/
+```
+
+1. For each hit: update outdated doc; add it if missing.
+2. No hits: decide whether the change *should* appear in docs (new features usually should).
+3. Significant architectural decision → check whether `docs/adr/` needs a new ADR.
+4. TOP Action: verify IAM registration lives in `deployments/coding-engine/templates/server/iam-register-codingserver.yaml`; `Proxy`/`Action`/`Version`/resource/roles/audit must match the endpoint. Gateway-served actions are still registered in the server IAM template, with `Proxy` pointing at the rendered gateway Service.
+
+Doc conventions: `docs/CONVENTIONS.md` (status markers `[已实现]` / `[部分实现]` / `[规划中]` required on every `docs/NN-*.md`), `docs/adr/CONVENTIONS.md` (ADR format / numbering / immutability). Markdown only, UTF-8/LF, one language per file, code blocks specify language. Minor refactors, test additions, internal renames → no doc update required.
+
+Before final commit, re-check whether staged code/config/API/deploy changes conflict with stable docs. The pre-commit `docs-verification-reminder` is a non-blocking nudge only; if docs are not updated, be ready to explain why the change is internal-only or otherwise does not affect documented behavior.
+
+**OpenAPI HTML sync (mandatory):** any change to the `api/idl/*.thrift` TOP Action surface (method, request/response struct, field name/type/requiredness, description) must keep both `docs/openapi/openapi.yaml` and the Redocly-rendered `docs/openapi/coding-engine-api.html` (the shipped human-readable page) in lockstep. `make check-openapi` regenerates both from the IDL, overwriting the committed files; commit the output. CI re-runs the same pinned `@redocly/cli@2.31.6` and fails the pipeline if anything changed (`git status` must be clean). Procedure → skill `coding-http-api`.
+
+## Deployment Config Sync Gate
+
+**Load skill `coding-deploy-config` before touching deploy/config.** It owns the 5-surface table, the verification grep template, image/DSN patterns, and TOP Action IAM rules.
+
+**Load-bearing rule (never delegate):** Credentials live in Secret, never ConfigMap. Any field matching `password`, `secret_key`, `access_key`, `ak`, `sk`, `token`, `apikey`, `api_key` **must** come from a K8s `Secret` (Secret-mounted config file, `envFrom`, or `valueFrom.secretKeyRef`). Rendered ConfigMaps carry references/placeholders only — plaintext credentials in ConfigMap fail the gate.
+
+**Narrow exception (do not generalize):** existing platform-owned `platform-info` env credentials may be read from the `platform-info` ConfigMap only for the established contracts — `AIGW_AK`/`AIGW_SK` on coding components, `UP_AK`/`UP_SK` on inner MCP / workspace init / workspace hot-sync / MCP config sync paths, and `IAM_AK`/`IAM_SK`/`iamEndpoint` for IAM UserResolver display-name lookup — per ADR 0022 and ADR 0048. SK values are encrypted whether from `platform-info` env or Secret-backed YAML; the exception exists because IAM Server owns the automatic `platform-info` ConfigMap update path. Do not extend it to new credentials or application config.
+
+## Redis Deployment Compatibility Gate
+
+All Redis-backed code must work with `redis.mode` = `single`, `sentinel`, and `cluster`. Sentinel behaves like a single primary; Cluster adds key-slot constraints. The load-bearing invariant:
+
+- Any multi-key command, transaction, or Lua script must keep every key in one hash slot via an explicit hash tag, e.g. `foo:{id}` and `foo:{id}:gen`.
+- Lua scripts pass all keys through `KEYS` — never synthesize undeclared key names inside the script.
+- Pipelines are for independent single-key ops only; Streams ops target one stream key per command.
+
+Cluster-safe key-naming assertions → skill `coding-testing` (`strategies/s3-redis.md`).
+
+## Coding Conventions
+
+- **Hexagonal boundaries are hard**: production domain code has zero external imports except approved value-type exceptions; `_test.go` and generated mocks may use test infra. Application code depends on domain and ports, not adapters or concrete external clients. Outside production domain, shared value/helper packages such as `pkg/platform/logger`, `pkg/platform/errno`, `pkg/platform/uuid`, `pkg/platform/retry`, and `pkg/platform/validate` are not hexagonal-boundary violations by themselves. Concrete infrastructure packages such as `pkg/platform/redis`, `pkg/platform/gormdb`, `pkg/platform/telemetrydb`, SDKs, DB, Redis, Kubernetes, and HTTP clients must still be hidden behind domain repositories or `application/port` interfaces. Adapters implement domain/port interfaces and own framework, SDK, DB, Redis, and HTTP client details.
+- **Immutability**: return new values, never mutate in-place.
+- **Errors**: always explicit; never swallow silently.
+- **File size**: 200–400 lines typical, 800 max.
+- **No hardcoded config**: constants or env-driven.
+- **Schema**: coding-engine main DB schema is owned by explicit SQL migrations under top-level `migration/`; server startup must not run GORM `AutoMigrate` or hand-written DDL. Keep GORM PO definitions and migration SQL in sync. Published source SQL files are immutable, including comment-only edits; same-version changes append the next `NNN.sql`, and new-version changes create a new `vX.Y.Z/` directory starting at `001.sql`.
+- **Tests**: table-driven, next to code under test (`_test.go`).
+
+### Comment Conventions
+
+- **Go source** comments are **English** — no CJK in `.go` comments, enforced by `make check-comment-i18n`. External-facing API contracts stay Chinese (out of scope): IDL `.thrift` comments, generated OpenAPI (`docs/openapi/*`), and `pkg/errors/*.json` `Comment` fields.
+- Be **concise**: delete comments restating self-evident code; keep "why", design rationale, pitfalls, and boundary conditions.
+- Reference ADRs by **topic or number**, not by quoting Chinese section titles: `ADR-0018 (local-mode behavior)`; use `ADR-00XX §N` only when the ADR has genuinely numbered sections (verify `§N` resolves).
+
+## Layer File Conventions
+
+```
+internal/
+  domain/<agg>/                    entity.go · repository.go (no aggregate-local errors.go)
+  application/<agg>/               service.go · dto.go · mapper.go
+  application/port/                <capability>.go (//go:generate mockgen) · mocks/ — infra capability ports only
+  application/<ctx>/{port,acl}/    consumer-owned cross-context ports + ACL adapters (ADR 0058)
+  adapters/outbound/persistence/rdb/repository/<agg>_repository.go
+  adapters/outbound/<runtime>/     executor.go · controller.go
+  bootstrap/<binary>/              module.go (fx.Module for server, manual for worker)
+```
+
+Service constructor — always `ServiceDeps`-style:
+```go
+type ServiceDeps struct {
+    Repo   domain.Repository
+    SomePt port.SomePort
+}
+func NewService(deps ServiceDeps) Service { ... }
+```
+
+Detailed checklists: adding aggregates/ports lives in `coding-architecture`; adding runtime providers lives in `coding-runtime-adapter`.
+
+## Testing
+
+**No QA team.** Every feature, fix, and refactor ships with tests. Load skill `coding-testing` for the 5 strategies, layer→strategy mapping, race rules, and common mistakes.
+
+Commands: `make test` (always, `-race`, unless only web folder changed), `make generate` (when mocks need refresh), `make gen-thrift` (when IDL changed).
+
+## Code Review (cross-CLI)
+
+**Mandatory before creating or updating an MR.** After committing the intended changes, use the `coding-code-review` skill with a clean worktree; it reviews the committed branch delta, not uncommitted edits. Coding agents must invoke `coding-code-review` through their current tool's native skill/subagent mechanism, not by shelling out to `make cr`, `scripts/cr.sh`, or `coco -p`. `make cr` remains only as a human / legacy compatibility wrapper for invoking `/coding-code-review` from compatible CLIs (installs+retries if missing). Times out after 8 minutes by default; override via `CODING_CR_TIMEOUT_SECONDS=<seconds>`.
+
+The review skill owns report generation; `coding-merge-request` owns what happens after review: `cr-fix-loop` or `cr-to-issues`.
+
+**Manual-trigger only.** Each run is expensive: do **not** add `coding-code-review` to §Skill Router; do **not** wire it into PostToolUse / commit / pre-commit / pre-push hooks.
+
+## Commit Scope Whitelist
+
+```
+# Cross-cutting / infra
+deploy | config | env | ci | scripts | docs
+# Binaries / components
+server | gateway | worker | daemon | aigw | mcp
+# Adapters / contracts
+hermes | runtime | http-api | idl | web
+# Domain features
+agent | session | model | skill | channel | chat
+```
+
+`fix:` without a scope is allowed only for cross-cutting fixes touching ≥3 scopes. Typo'd or unlisted scopes should be questioned in review; expand the whitelist deliberately, not silently.
+
+## MR description
+
+**Load skill `coding-merge-request` before creating, updating, validating, or preparing an MR.** It owns `make open-mr`, `mr-hygiene`, issue trailers, issue-driven delivery, and review disposition after `coding-code-review`.
+
+Fast path: target `release`, commit intended changes, run `coding-code-review`, generate an MR description from the actual diff and validation evidence using `.gitlab/merge_request_templates/Default.md`, then `make open-mr TITLE="<conventional-commit title>" ARGS="--body-file /tmp/mr-desc.md"`. Never inline an MR body with `bytedcli` / `codebase mr create --body`; the shared path creates with title only so the template loads before `scripts/open-mr.sh` applies the model-written description.
+
+## Skill Router
+
+Consult this table **before** editing files in the listed paths and load the matching skill. How each CLI reaches this table (and how to bridge a new tool) → `.agents/skills/REGISTRY.md` §Tool bridges.
+
+Some skills are path-triggered; others are task-triggered or gates. When
+multiple skills apply, load only the relevant combination. Cross-layer
+checklists do not replace the owning surface's skill: persisted API fields
+still use `coding-db-schema`; runtime/collector config changes still use
+`coding-deploy-config`.
+
+| If you're about to edit | Load skill | Why |
+|---|---|---|
+| `internal/domain/**`, `internal/application/port/**`, `internal/application/*/service.go` | `coding-architecture` | DDD layer map, port/adapter contracts, fx wiring, ServiceDeps shape |
+| `internal/adapters/outbound/{hermes,workspacejob}/**`, `internal/bootstrap/worker/registry.go` | `coding-runtime-adapter` + `coding-deploy-config` | Runtime adapter quad, worker provider wiring, and config sync gate |
+| `internal/adapters/outbound/**/redis*.go`, `internal/adapters/outbound/{eventbus,messagebus,presence,lane/redislane,sessionlease}/**`, `pkg/platform/redis/**` | `coding-architecture` + `coding-testing` | Redis single / sentinel / cluster compatibility, Lua hash tags, miniredis strategy |
+| `**/*_test.go`, `tests/**` | `coding-testing` | 5 test strategies, `t.Parallel`, race rules |
+| `deployments/**`, `configs/engine.yaml*`, `internal/bootstrap/app/engine_config.go`, `internal/adapters/outbound/*/config.go` | `coding-deploy-config` | 5-surface sync gate, image / DSN / Secret patterns |
+| `internal/adapters/outbound/persistence/rdb/po/**`, `migration/**` | `coding-db-schema` | SQL migration ownership for coding-engine main DB, RDB repository behavior, forward-only safety, ADR 0003 trigger |
+| `api/idl/*.thrift`, `internal/adapters/inbound/http/handlers/**`, `docs/openapi/coding-engine-api.html` | `coding-http-api` | IDL field-tag conventions, required↔optional compatibility, cross-layer cleanup, OpenAPI YAML + HTML sync (`make check-openapi`) |
+| `internal/observability/**`, `pkg/platform/telemetrydb/**`, `coding-otelcol/**`, `configs/otel*.yaml*`, `build/docker/otelcol.Dockerfile`, `deployments/coding-engine/templates/collector/**` | `coding-observability` | Metric catalogue + smoke guard, 3-place add rule, `port.Metrics` DI with `NoopMetrics` fallback, ocb collector build pipeline (ADR-0023) |
+
+**This table is the source of truth.** Update it first, then mirror into `.cursor/rules/skill-router.mdc` and `scripts/skill-router-hook.sh`; `make check-skill-router-sync` (in `make check` + pre-commit) fails the build if the three drift. The per-tool bridges in `REGISTRY.md` follow. Default for unlisted paths: `coding-architecture`. Task-triggered skills (`coding-code-review`, `coding-cve-remediation`, `coding-docs-audit`, `coding-merge-request`, `coding-refactor-insight`, `coding-release-merge`) are deliberately unrouted — invoke them by intent, not path.
+
+**Intent route (not a path→skill row, not a skill).** When you're oncall / debugging a production incident / paged, read `docs/runbooks/README.md` first — the triage front-door for coding-engine oncall. On the way out: if you helped resolve an incident — including an ops-only fix with no code change (quota bump, secret patch, PVC delete, `migrate adopt`, pod restart) that the `fix(*)` commit-msg reminder can never catch — proactively offer to sediment it into `docs/runbooks/` before closing the session, whenever it's a recurring failure class.
+
+**ADR trigger.** When an edit introduces an *architectural decision* — a new bounded context, a new `port` interface under `internal/application/port/**`, a new `api/idl/*.thrift` contract, or a reversal of a prior ADR — record it as an ADR under `docs/adr/` (see `docs/adr/CONVENTIONS.md`, Mode A/B). This is a **rule every agent follows**, reinforced by the path-triggered router nudge (mirrored across `scripts/skill-router-hook.sh` and `.cursor/rules/skill-router.mdc`). It is a prompt, not a gate: `coding-code-review` is the human backstop.
+
+Per-skill descriptions (auto-generated from each `SKILL.md` frontmatter) and the ~90-day skill-lifecycle cadence (`make check-skills` / `skill-propose` / `skill-impact`) live in **`.agents/skills/REGISTRY.md`**, regenerated by `make regen-agent-md` (enforced by pre-commit `check-agent-md`). Promote a `HOT` skill into this file as a top-level rule; retire `DEAD` ones there.

package/templates/MR-Template-Default.md

@@ -0,0 +1,33 @@
+## 变更说明
+
+<!-- 用简洁 bullet 分点说明这个 MR 做了什么，以及为什么；不要写成一整段长段落 -->
+
+**类型:** `feat` / `fix` / `refactor` / `docs` / `test` / `chore` / `perf`
+
+---
+
+## Docs as Code
+
+- [ ] 无需更新文档（原因：__________）
+- [ ] 已审查文档影响（docs grep / 相关文档检索：__________）
+- [ ] 已更新 `docs/NN-*.md`
+- [ ] 已更新或新增 `docs/adr/`
+- [ ] 已同步 OpenAPI 文档（`make check-openapi`：__________）
+- [ ] 已更新 `AGENTS.md`
+
+---
+
+## 测试
+
+- [ ] `make check`：__________
+- [ ] `make test`：__________
+- [ ] `make test-integration` / 受影响集成测试：__________
+- [ ] 代码生成/契约生成（`make generate` / `make gen-thrift`）：__________
+- [ ] 其它验证：__________
+- [ ] 未执行测试（原因：__________）
+
+---
+
+## Reviewer 关注点
+
+<!-- 可选：指出需要重点 review 的地方，或有意为之的设计取舍 -->

package/templates/Makefile

@@ -0,0 +1,370 @@
+DOCKER_COMPOSE ?= docker compose
+GOLANGCI_LINT ?= golangci-lint
+GOLANGCI_CONFIG ?= .golangci.yml
+THRIFTGO ?= thriftgo
+REDOCLY_VERSION ?= 2.31.6
+REDOCLY ?= npx --yes @redocly/cli@$(REDOCLY_VERSION)
+YAMLLINT ?= scripts/yamllint.sh
+BIN_DIR := bin
+VERSION ?= dev
+COMMIT ?= $(shell git rev-parse --short HEAD 2>/dev/null || printf "unknown")
+BUILD_DATE ?= $(shell date -u +"%Y-%m-%dT%H:%M:%SZ")
+TOP_VERSION ?= 2026-04-23
+VERSION_PKG := code.byted.org/epscp/coding_engine/pkg/version
+LDFLAGS_COMMON := -X $(VERSION_PKG).version=$(VERSION) -X $(VERSION_PKG).commit=$(COMMIT) -X $(VERSION_PKG).buildDate=$(BUILD_DATE)
+.PHONY: help fmt generate baseline-sql migrate-sql check-migrate-sql check-migration-sql-immutability check-migrate-sql-syntax go-mod-tidy check-context-propagation check-context-nil check-repository-transactions check-rdb-structured-queries check-iam-actions test test-root test-otelcol test-hijackprocessor test-integration test-e2e lint lint-yaml clean \
+	gen-thrift gen-thrift-engine gen-thrift-http gen-mocks gen-collector check-openapi helmlint helm-smoke \
+	build build-all build-engine build-allinone build-cli build-inner-mcp-sidecar build-artifact-downloader build-collector \
+	compose-up compose-down compose-logs local-dev-env-from-container local-dev-up local-dev-down local-dev-reset local-dev-logs local-dev-ps verify-scaffold \
+	check-skill check-skill-testing check-skill-all propose-skill skill-impact skill-graph check-skill-router-sync check-adr check-docs \
+	regen-adr-index check-adr-index test-adr runbook \
+	cr fill-mr-desc open-mr open-issue next-issue cr-to-issues test-scripts check-mr-desc check-mr-title check-mr-size check-mr-target-merged
+
+help:
+	@printf "可用目标:\n"
+	@printf "  make lint                               # 运行 code/yaml/helm/thrift 全部 lint\n"
+	@printf "  make lint-code                          # Go fmt/lint\n"
+	@printf "  make lint-yaml                          # YAML lint\n"
+	@printf "  make lint-helm                          # Helm chart lint\n"
+	@printf "  make lint-thrift                        # Thrift IDL parse/check via thriftgo\n"
+	@printf "  make generate                           # 运行 go:generate 产物（不含 Thrift）\n"
+	@printf "  make baseline-sql ARGS=--force          # 覆盖生成 v0.2.0 基线 SQL；仅初始基线重建时使用\n"
+	@printf "  make migrate-sql                        # 聚合 migration/ 到 deployments/coding-engine/sql\n"
+	@printf "  make check-migrate-sql                  # 验证 migration 聚合产物没有漂移\n"
+	@printf "  make check-migration-sql-immutability   # 校验已有 migration SQL 不被修改/删除/重命名（可用 SQL_IMMUTABILITY_BASE=origin/<branch> 指定基线）\n"
+	@printf "  make check-migrate-sql-syntax           # 静态检查 mysql/postgres/dm migration SQL 语法和文件边界\n"
+	@printf "  make go-mod-tidy                        # 对 workspace 内 Go modules 执行 go mod tidy\n"
+	@printf "  make check-context-propagation          # 检查生产 Go 代码不要新增未审查的 Background/TODO 根\n"
+	@printf "  make check-context-nil                  # 检查 context.Context 参数不要传 nil（含测试）\n"
+	@printf "  make check-repository-transactions      # 检查 repository 层不打开/控制事务\n"
+	@printf "  make check-rdb-structured-queries       # 检查 RDB repository 使用结构化 GORM 查询\n"
+	@printf "  make gen-thrift                         # 由 api/idl/*.thrift 生成模型\n"
+	@printf "  make check-openapi                      # 从 Thrift 生成 OpenAPI YAML/HTML\n"
+	@printf "  make check-iam-actions                  # 校验 Thrift TOP Action 与 IAM 注册双向同步\n"
+	@printf "  make gen-collector                      # 生成 OpenTelemetry Collector 二进制\n"
+	@printf "  make test                               # 运行全部 Go 测试\n"
+	@printf "  make test-root                          # 测试根 Go module\n"
+	@printf "  make test-otelcol                       # 测试 coding-otelcol Go module\n"
+	@printf "  make test-hijackprocessor               # 测试 hijackprocessor Go module\n"
+	@printf "  make test-integration                   # 运行 tests/integration 下的真实依赖集成测试\n"
+	@printf "  make test-e2e                           # 运行 tests/e2e 下的外部 API 端到端测试（需 CODING_E2E_* 环境变量）\n"
+	@printf "  make test-helm                          # 测试 helm template 后的关键 RBAC / 配置不回归\n"
+	@printf "  make check                              # 运行 docs / skills / Helm 渲染语义检查\n"
+	@printf "  make check-docs                         # 检查 docs 编号/标题与 ADR 状态\n"
+	@printf "  make check-runbooks                     # 检查 docs/runbooks/ 链接、锚点与源码引用\n"
+	@printf "  make runbook kw=<keyword>               # 按关键字检索 docs/runbooks/（只读 grep）\n"
+	@printf "  make check-skills                       # 检查 coding-* skills 结构、引用漂移、测试策略覆盖\n"
+	@printf "  make check-skill-router-sync            # 校验 §Skill Router 在 AGENTS.md / .cursor mirror / hook 三处一致\n"
+	@printf "  make build                              # 构建后端入口、allinone 和 CLI\n"
+	@printf "  make build-engine                       # 构建统一后端入口 bin/coding-engine\n"
+	@printf "  make build-allinone                     # 构建 allinone 独立入口 bin/coding-allinone\n"
+	@printf "  make build-cli VERSION=v0.1.0           # 覆盖版本信息注入\n"
+	@printf "  make build-inner-mcp-sidecar            # 构建 Hermes Pod 内 MCP sidecar 入口\n"
+	@printf "  make build-artifact-downloader          # 构建 workspace sync artifact 下载入口\n"
+	@printf "  make build-collector                    # 构建 OpenTelemetry Collector 二进制\n"
+	@printf "  make compose-up                         # 启动本地依赖与占位服务\n"
+	@printf "  make compose-down                       # 停止本地依赖与占位服务\n"
+	@printf "  make compose-logs                       # 查看 compose 日志\n"
+	@printf "  make local-dev-env-from-container       # 从当前 allinone 容器导出本地联调密钥到 .env.local\n"
+	@printf "  make local-dev-up                       # 通过 kubevpn 直连 k8s 服务，启动 allinone + 本地前端 dev stack\n"
+	@printf "  make local-dev-down                     # 停止本地 dev stack\n"
+	@printf "  make local-dev-reset                    # 停止本地 dev stack 并清理前端依赖卷\n"
+	@printf "  make local-dev-logs                     # 查看本地 dev stack 日志\n"
+	@printf "  make local-dev-ps                       # 查看本地 dev stack 容器状态\n"
+	@printf "  make verify-scaffold                    # 验证脚手架文件与 compose 配置\n"
+	@printf "  make helmlint                           # 校验 coding-engine chart\n"
+	@printf "  make helm-smoke                         # helm template 渲染并校验关键 RBAC / 配置不回归\n"
+	@printf "  make check-skill                        # 运行全部 skill 校验（coding-testing 覆盖率 + 结构完整性）\n"
+	@printf "  make check-skill-testing                # 仅检查 coding-testing Layer→Strategy 覆盖率\n"
+	@printf "  make check-skill-all                    # 仅检查全部 skill 的 frontmatter 与引用路径完整性\n"
+	@printf "  make propose-skill                      # 生成缺失 skill 条目的草案文件\n"
+	@printf "  make skill-impact                       # 统计每个 skill 在提交记录中的引用度，标注 retire / promote 候选\n"
+	@printf "  make skill-graph                        # 渲染 skill 互引图到 docs/assets/skill-graph.dot (.png if graphviz present)\n"
+	@printf "  make check-adr                          # 检查 docs/adr/ 状态字段（禁止 Proposed 进主干）\n"
+	@printf "  make regen-adr-index                    # regenerate docs/adr/INDEX.md from ADR metafields\n"
+	@printf "  make check-adr-index                    # verify docs/adr/INDEX.md is in sync (dry-run)\n"
+	@printf "  make check-comment-i18n                 # 校验注释为英文（无 CJK）\n"
+	@printf "  make test-adr                           # run ADR tooling fixture tests\n"
+	@printf "  make check-docs                         # 检查 docs/ 文件名 / 标题 / 编号唯一性\n"
+	@printf "  make cr                                 # 人类/兼容入口：封装调用 coding-code-review（默认 8min 超时）\n"
+	@printf "  make open-mr TITLE=\"...\" ARGS=\"--body-file ...\" # 推分支 → 创建/刷新 MR → 应用模型生成的正文\n"
+	@printf "  make open-issue TITLE=\"...\" [ARGS=...]  # 从 .codebase/issue_templates 模板创建 AI 可执行 issue；首选入口\n"
+	@printf "  make next-issue [ARGS=...]              # 列出可认领的 todo issue；ARGS=\"--claim N\" 认领并转 in_progress + 自指派\n"
+	@printf "  make cr-to-issues [ARGS=...]            # 把 make cr 的 deferred findings 去重沉淀成 issue（默认 dry-run；ARGS=--apply 才真建）\n"
+	@printf "  make test-scripts                       # 运行全部 scripts/test/*.test.sh 离线 fixture/workflow 回归测试\n"
+	@printf "  make check-mr-desc FILE=path/to/desc.md  # 本地校验一份 MR 描述是否能通过 GitLab CI 的 mr:hygiene\n"
+	@printf "  make check-mr-title TITLE=\"feat(ci): ...\" # 本地校验 MR 标题（Conventional Commits 中等档）\n"
+	@printf "  make check-mr-size [BASE=origin/release] # 本地校验 MR diff 行数是否超过 8000 行硬上限\n"
+	@printf "  make check-mr-target-merged [TARGET=origin/release] # 校验当前分支已合入目标分支最新提交；默认读取 MR_TARGET_REF / CI_MERGE_REQUEST_TARGET_BRANCH\n"
+
+lint: lint-code lint-yaml lint-helm lint-thrift
+
+lint-code: go-mod-tidy
+	./scripts/check-go-names.sh
+	$(GOLANGCI_LINT) fmt --config $(GOLANGCI_CONFIG) ./...
+	$(GOLANGCI_LINT) run --config $(GOLANGCI_CONFIG) ./...
+
+lint-yaml:
+	YAMLLINT_RETRY_HINT="make $(if $(MAKECMDGOALS),$(MAKECMDGOALS),lint-yaml)" $(YAMLLINT) -c .yamllint.yml .
+
+lint-helm:
+	helm lint deployments/coding-engine
+
+lint-thrift:
+	@for f in api/idl/*.thrift; do \
+		echo "==> thriftgo $$f"; \
+		$(THRIFTGO) -i api/idl -g go:skip_go_gen "$$f"; \
+	done
+
+generate:
+	go generate ./...
+
+baseline-sql:
+	go run scripts/generate-baseline-sql.go $(ARGS)
+
+migrate-sql:
+	bash scripts/generate-migration-sql.sh
+
+check-migrate-sql: migrate-sql
+	git diff --exit-code HEAD -- migration deployments/coding-engine/sql
+	@test -z "$$(git ls-files --others --exclude-standard -- migration deployments/coding-engine/sql)" || \
+		(printf 'untracked generated migration files:\n' >&2; git ls-files --others --exclude-standard -- migration deployments/coding-engine/sql >&2; exit 1)
+
+check-migration-sql-immutability:
+	bash scripts/check-migration-sql-immutability.sh
+
+check-migrate-sql-syntax:
+	go run scripts/check-migrate-sql-syntax.go --dialect=mysql
+	go run scripts/check-migrate-sql-syntax.go --dialect=postgres
+	go run scripts/check-migrate-sql-syntax.go --dialect=dm
+
+go-mod-tidy:
+	@for dir in $$(go list -m -f '{{.Dir}}'); do \
+		echo "==> go mod tidy ($$dir)"; \
+		(cd "$$dir" && go mod tidy); \
+	done
+
+gen-thrift: gen-thrift-engine
+
+gen-thrift-engine:
+	hz model \
+		--rm_tag query \
+		--rm_tag form \
+		--idl api/idl/server.thrift \
+		--model_dir internal/adapters/inbound/http/thrift_gen \
+		--thriftgo 'go:package_prefix=code.byted.org/epscp/coding_engine/internal/adapters/inbound/http/thrift_gen,reserve_comments,enable_nested_struct,template=slim,no_default_serdes,no_processor'
+
+check-openapi:
+	@python3 scripts/check-openapi.py --idl api/idl/server.thrift --yaml docs/openapi/openapi.yaml --html docs/openapi/coding-engine-api.html --top-version "$(TOP_VERSION)" --thriftgo "$(THRIFTGO)" --redocly "$(REDOCLY)"
+
+gen-collector:
+	# 首次使用需先安装 ocb（OpenTelemetry Collector Builder）
+	# 各平台下载地址：https://github.com/open-telemetry/opentelemetry-collector-releases/releases
+	# 找到对应版本的 cmd/builder/vX.Y.Z，下载与本机匹配的二进制并放到 PATH 中
+	# 例如 macOS arm64：
+	# wget -O ocb "https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/cmd%2Fbuilder%2Fv0.152.0/ocb_0.152.0_darwin_arm64"
+	@command -v ocb >/dev/null 2>&1 || GO111MODULE=on go install go.opentelemetry.io/collector/cmd/builder@v0.151.0
+	@ocb --config ./configs/otelcol-build-config.yaml
+
+test:
+	@set -e; \
+	for dir in $$(go list -m -f '{{.Dir}}'); do \
+		echo "==> go test ($$dir)"; \
+		(cd "$$dir" && go test -race ./...); \
+	done
+
+test-root:
+	go test -race ./...
+
+test-otelcol:
+	cd coding-otelcol && go test -race ./...
+
+test-hijackprocessor:
+	cd coding-otelcol/processor/hijackprocessor && go test -race ./...
+
+test-helm:
+	@echo "==> Testing Helm rendered RBAC and config invariants..."
+	@bash scripts/test-helm.sh
+
+test-integration:
+	go test --tags=integration ./tests/integration/...
+
+test-e2e:
+	go test --tags=e2e ./tests/e2e/...
+
+clean:
+	rm -rf $(BIN_DIR)
+
+build: build-engine build-allinone build-cli build-inner-mcp-sidecar build-artifact-downloader
+
+# build-all is the alias referenced by onboarding.html / CLAUDE.md;
+# kept as a thin shim so the documented command keeps working.
+build-all: build
+
+build-engine:
+	@mkdir -p $(BIN_DIR)
+	CGO_ENABLED=0 go build -ldflags "$(LDFLAGS_COMMON) -X $(VERSION_PKG).appName=coding-engine" -o $(BIN_DIR)/coding-engine ./cmd/coding-engine
+
+build-allinone:
+	@mkdir -p $(BIN_DIR)
+	CGO_ENABLED=0 go build -ldflags "$(LDFLAGS_COMMON) -X $(VERSION_PKG).appName=coding-allinone" -o $(BIN_DIR)/coding-allinone ./cmd/coding-allinone
+
+build-cli:
+	@mkdir -p $(BIN_DIR)
+	CGO_ENABLED=0 go build -ldflags "$(LDFLAGS_COMMON) -X $(VERSION_PKG).appName=coding-cli" -o $(BIN_DIR)/coding-cli ./cmd/coding-cli
+
+build-inner-mcp-sidecar:
+	@mkdir -p $(BIN_DIR)
+	CGO_ENABLED=0 go build -ldflags "$(LDFLAGS_COMMON) -X $(VERSION_PKG).appName=coding-inner-mcp-sidecar" -o $(BIN_DIR)/coding-inner-mcp-sidecar ./cmd/coding-inner-mcp-sidecar
+
+build-artifact-downloader:
+	@mkdir -p $(BIN_DIR)
+	CGO_ENABLED=0 go build -ldflags "$(LDFLAGS_COMMON) -X $(VERSION_PKG).appName=coding-artifact-downloader" -o $(BIN_DIR)/coding-artifact-downloader ./cmd/coding-artifact-downloader
+
+build-collector:
+	@mkdir -p $(BIN_DIR)
+	cd coding-otelcol && CGO_ENABLED=0 go build -ldflags "$(LDFLAGS_COMMON)" -o ../$(BIN_DIR)/coding-collector .
+
+compose-up:
+	$(DOCKER_COMPOSE) up -d --build
+
+compose-down:
+	$(DOCKER_COMPOSE) down
+
+compose-logs:
+	$(DOCKER_COMPOSE) logs -f coding-gateway coding-server coding-worker coding-daemon
+
+local-dev-env-from-container:
+	@docker inspect coding-allinone-docker --format '{{range .Config.Env}}{{println .}}{{end}}' \
+		| grep -E '^(AIGW_AK|AIGW_SK|AIGW_REGION|IAM_AK|IAM_SK|IAM_REGION|UP_AK|UP_SK|iamEndpoint)=' \
+		| perl -pe 's/\x24/\x24\x24/g' > .env.local
+	@printf "Wrote .env.local from coding-allinone-docker\n"
+
+local-dev-up:
+	@test -f .env.local || (printf "Missing .env.local. Run: make local-dev-env-from-container, or copy deployments/local-dev.env.example to .env.local and fill it.\n" && exit 1)
+	@docker rm -f coding-allinone-docker coding-web-dev platform-web-dev >/dev/null 2>&1 || true
+	$(DOCKER_COMPOSE) -f deployments/docker-compose.local-dev.yml up -d --build
+
+local-dev-down:
+	$(DOCKER_COMPOSE) -f deployments/docker-compose.local-dev.yml down
+
+local-dev-reset:
+	$(DOCKER_COMPOSE) -f deployments/docker-compose.local-dev.yml down -v
+
+local-dev-logs:
+	$(DOCKER_COMPOSE) -f deployments/docker-compose.local-dev.yml logs -f
+
+local-dev-ps:
+	$(DOCKER_COMPOSE) -f deployments/docker-compose.local-dev.yml ps
+
+check: check-docs check-runbooks check-skills check-skill-router-sync check-agent-md check-adr-index check-comment-i18n check-context-propagation check-context-nil check-migrate-sql check-migration-sql-immutability check-migrate-sql-syntax check-repository-transactions check-rdb-structured-queries check-iam-actions test-adr test-scripts test-helm
+
+check-docs:
+	@echo "==> Checking docs filenames, titles, numbering, and ADR statuses..."
+	@bash scripts/check-docs.sh
+	@bash scripts/check-adr.sh
+	@bash scripts/check-doc-refs.sh
+
+check-runbooks:
+	@echo "==> Checking docs/runbooks/ links, anchors, and source citations..."
+	@bash scripts/check-runbooks.sh
+
+runbook:
+	@bash scripts/runbook.sh $(if $(strip $(kw)),"$(kw)")
+
+check-adr:
+	@echo "==> Checking ADR integrity (status, supersede, references, numbering, topic)..."
+	@bash scripts/check-adr.sh
+
+check-skills:
+	@echo "==> Checking coding-* skill structure, references, and strategy coverage..."
+	@bash scripts/check-skills.sh
+
+check-skill-router-sync:
+	@echo "==> Checking §Skill Router consistency across AGENTS.md, .cursor mirror, and hook..."
+	@python3 scripts/check-skill-router-sync.py
+
+regen-agent-md:
+	@echo "==> Regenerating skill registry in AGENTS.md from .agents/skills/coding-*/SKILL.md..."
+	@bash scripts/regen-agent-md.sh
+
+check-agent-md:
+	@echo "==> Checking AGENTS.md skill registry is in sync with .agents/skills/coding-*/SKILL.md..."
+	@bash scripts/regen-agent-md.sh --check
+
+regen-adr-index:
+	@echo "==> Regenerating docs/adr/INDEX.md from ADR metafields..."
+	@bash scripts/gen-adr-index.sh
+
+check-adr-index:
+	@echo "==> Checking docs/adr/INDEX.md is in sync with ADR metafields..."
+	@bash scripts/gen-adr-index.sh --check
+
+check-comment-i18n:
+	@bash scripts/check-comment-i18n.sh .
+
+check-context-propagation:
+	@python3 scripts/check-context-propagation.py .
+
+check-context-nil:
+	@go run scripts/check-context-nil.go ./... ./coding-otelcol/... ./coding-otelcol/processor/hijackprocessor/...
+
+check-repository-transactions:
+	@bash scripts/check-repository-transactions.sh .
+
+check-rdb-structured-queries:
+	@bash scripts/check-rdb-structured-queries.sh .
+
+check-iam-actions:
+	@python3 scripts/check-iam-actions.py
+
+test-adr:
+	@echo "==> Running ADR tooling fixture tests..."
+	@bash tests/adr/lib.test.sh
+	@bash tests/adr/gen-adr-index.test.sh
+	@bash tests/adr/check-adr.test.sh
+
+skill-propose:
+	@echo "==> Generating skill evolution proposals..."
+	@bash scripts/skill-propose.sh
+
+skill-impact:
+	@bash scripts/skill-impact.sh
+
+skill-graph:
+	@echo "==> Generating skill cross-reference graph..."
+	@bash scripts/skill-graph.sh
+
+cr:
+	@bash scripts/cr.sh
+
+open-mr:
+	@bash scripts/open-mr.sh $(if $(TITLE),--title "$(TITLE)") $(ARGS)
+
+open-issue:
+	@bash scripts/open-issue.sh $(if $(TITLE),--title "$(TITLE)") $(ARGS)
+
+next-issue:
+	@bash scripts/next-issue.sh $(ARGS)
+
+cr-to-issues:
+	@bash scripts/cr-to-issues.sh $(ARGS)
+
+test-scripts:
+	@set -e; \
+	for f in $$(find scripts/test -maxdepth 1 -type f -name '*.test.sh' | sort); do \
+		printf '==> %s\n' "$$f"; \
+		env SHELLOPTS= bash "$$f"; \
+	done
+
+check-mr-desc:
+	@bash scripts/check-mr-desc.sh $(if $(FILE),--description-file "$(FILE)") $(ARGS)
+
+check-mr-title:
+	@bash scripts/check-mr-title.sh $(if $(TITLE),--title "$(TITLE)") $(ARGS)
+
+check-mr-size:
+	@bash scripts/check-mr-size.sh $(if $(BASE),--base "$(BASE)") $(ARGS)
+
+check-mr-target-merged:
+	@bash scripts/check-mr-target-merged.sh $(if $(TARGET),--target "$(TARGET)") $(if $(HEAD),--head "$(HEAD)") $(ARGS)

package/templates/REGISTRY.md

@@ -0,0 +1,53 @@
+# Skill Registry & Lifecycle
+
+Reference index for the coding-* skills. The **path→skill routing table is in `AGENTS.md` §Skill Router** (the source of truth, read inline by every CLI). This file holds the verbose per-skill descriptions and the maintenance cadence — consulted when picking or pruning skills, not on every edit.
+
+## Tool bridges
+
+How each CLI reaches the `AGENTS.md` §Skill Router table:
+
+| Tool | Entry | Bridge in repo |
+|---|---|---|
+| Codex / Antigravity / Trae | Root `AGENTS.md` (native) | — |
+| Gemini | `GEMINI.md` → `AGENTS.md` | Thin bridge |
+| Claude Code | `CLAUDE.md` → `AGENTS.md` | `.claude/settings.json` PostToolUse hook via `scripts/skill-router-hook.sh` |
+| Cursor | `.cursor/rules/skill-router.mdc` | Mirror of §Skill Router (auto-injected by glob) |
+
+Adopting a new tool? Add a row and a bridge (mirror file, hook, or symlink) — do not rely on contributors to manually `@AGENTS.md`.
+
+## Skill Registry
+
+Per-skill descriptions sourced from each `.agents/skills/coding-*/SKILL.md` frontmatter. Auto-regenerated by `make regen-agent-md` (enforced by pre-commit `check-agent-md`). **Do not hand-edit between the markers.**
+
+<!-- skills:start (auto-generated by make regen-agent-md) -->
+
+| Skill | When to use |
+|---|---|
+| `coding-architecture` | Use when adding features, new aggregates, new ports, or architecture-level adapters to coding_engine. |
+| `coding-code-review` | General-purpose diff-based code review orchestration for clean canonical diff generation, reviewer dispatch, and report consolidation without re-reviewing code. |
+| `coding-cve-remediation` | 处理 coding_engine 的 Codebase 镜像漏洞扫描结果。适用于查看 scan-image-* 镜像扫描 job、读取 image-scanner 报告、分类 CVE，并只修复 coding-engine、coding-inner-mcp-sidecar、coding-collector 中可由 Go 依赖升级解决的漏洞；OS/base image 漏洞只报告为范围外。 |
+| `coding-db-schema` | Use when adding, modifying, or removing a database schema element in coding_engine — new column, dropped column, renamed column, new table, new index, type change, or new GORM model under `internal/adapters/outbound/persistence/rdb/` or `mem-svc/internal/adapters/outbound/persistence/rdb/`. Encodes explicit migration SQL ownership for the coding-engine main DB, GORM PO / SQL alignment, mem-svc AutoMigrate ownership, RDB repository behavior checks, soft-delete vs physical-delete rules, forward-only safety rules, and the breaking-change ADR trigger. |
+| `coding-deploy-config` | Use when changing any deployment/runtime/config item in coding_engine — Helm values, vecompass-override, configs/engine.yaml.example, Go config struct, image repo/tag, DSN, K8s probe/service port, Secret/ConfigMap field. |
+| `coding-docs-audit-autofix` | Use after coding-docs-audit has produced docs-audit-report.md to conservatively fix obvious stable-doc drift and write a focused notification report for the findings that still need code/config/implementation follow-up. |
+| `coding-docs-audit` | Use when performing a bounded, read-only audit of stable docs under docs/ plus root README.md, README.zh-CN.md, onboarding.html, and vibe-coding.html against current code implementation, excluding ADRs and OpenAPI/interface docs, and writing docs-audit-report.md with a Chinese discrepancy-only report, Critical/Major/Minor/Suggestion severity, mandatory git blame attribution to specific people, and a final per-person task summary. Enforces fixed phases, budgets, and stop conditions to avoid open-ended scans. |
+| `coding-http-api` | Use when changing any HTTP API surface in coding_engine — adding/modifying/removing a Thrift IDL field or service method under `api/idl/*.thrift`, editing a Hertz handler under `internal/adapters/inbound/http/handlers/`, or aligning generated clients/frontends with backend changes. Encodes the IDL field-tag conventions, required↔optional compatibility rules, the codegen/regen step, the handler→service→domain dispatch shape, the cross-layer cleanup checklist for renames/removals, and the frontend-alignment trigger. |
+| `coding-issue-autodev` | "Use when taking over a specific coding_engine Codebase issue and driving it end-to-end in either human or agent mode: read the issue, claim it for the current bytedcli user or BOT_NAME, optionally force-claim from another assignee, follow the normal coding development flow, run required gates and coding-code-review, commit with an issue-closing trailer, and open or refresh the MR through make open-mr." |
+| `coding-merge-request` | Use when creating, updating, validating, or preparing a coding_engine merge request, including MR title/description hygiene, target branch freshness, diff size limits, code review handoff, issue trailers, and make open-mr workflows. |
+| `coding-observability` | Use when changing any observability surface in coding_engine — adding/removing a metric in `internal/observability/`, emitting via `port.Metrics`, editing the OTel Collector build manifest (`configs/otelcol-build-config.yaml`), the collector runtime config (`configs/otel-config.yaml.example`), the collector Helm templates under `deployments/coding-engine/templates/collector/`, or the telemetry DB clients in `pkg/platform/telemetrydb/`. |
+| `coding-refactor-insight` | 识别 coding_engine 中高收益重构机会，并输出中文 Top 5 架构洞察报告。聚焦 Module 深度、Interface 宽度、Seam、Adapter 泄漏、Locality、重复实现、fan-out 与 Leverage，而不是输出 lint 明细清单。 |
+| `coding-release-merge` | Use when merging the latest release branch into the current coding_engine feature branch, resolving conflicts, and reconciling newly introduced shared conventions such as API contracts, error handling rules, common helpers, config patterns, or cross-cutting refactors across both sides of the merge. |
+| `coding-runtime-adapter` | Use when adding a new runtime provider to coding_engine, modifying runtime adapter code under `internal/adapters/outbound/{hermes,workspacejob}/**`, or changing worker provider registry wiring. |
+| `coding-testing` | Use when writing, reviewing, fixing, or running any test in coding_engine, including unit tests, integration tests, external-service manual checks, and deployed-environment coverage (E2E P0/P1/P2 smoke & regression, DFX stability/load, Eval quality). There is no QA team — Claude owns test correctness. Covers which strategy applies to each layer, required tooling, mandatory test run commands, and what "done" means before marking work complete. |
+<!-- skills:end -->
+
+## Skill lifecycle
+
+Skills are not eternal. Periodically (~90d):
+
+```bash
+make check-skills    # hard gate: structural integrity + drift + Layer→Strategy coverage
+make skill-propose   # soft suggestion: auto-drafts proposals for detected gaps
+make skill-impact    # classifies skills NEW / WATCH / DEAD / COLD / WARM / HOT
+```
+
+Retire `DEAD` (≥90d, 0 refs/year). Promote `HOT` (≥20 refs/year) into `AGENTS.md` as a top-level rule. Thresholds tunable in `scripts/skill-impact.sh`.