trae-coding-engine 0.1.0

package/templates/.agents/skills/coding-docs-audit/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: coding-docs-audit
+description: 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-docs-audit: Stable Docs vs Implementation Audit
+
+Read-only audit for stable project documentation. The final output is a Chinese report containing only mismatches between stable documentation and the current implementation. Every formal finding must be attributed to specific people from `git blame` / `git log` evidence.
+
+## Output Contract
+
+- Final report language: Chinese. Keep severity labels in English: `[Critical]`, `[Major]`, `[Minor]`, `[Suggestion]`.
+- Final report destination: write the complete final report to repo-root `docs-audit-report.md`. Overwrite stale audit output only when the user asks to run this audit; do not write elsewhere.
+- Report only discrepancies. Do not list correct checks, matched claims, "PASS" items, or documents with no findings.
+- Every formal finding must name specific responsible person(s): author name, email when available, commit short SHA, date, and commit subject. For CI issue routing, always prefer `xxx@bytedance.com` email in owner/task headings when git history provides it; do not output only a Chinese display name.
+- End the report with a per-person task summary derived from formal findings. Each task must reference the finding title/severity and state what that person should do.
+- If a suspected mismatch cannot be attributed to at least one specific person from git history, do not include it in `## 差异点`; put it in `## 待确认问题`.
+- Do not modify documentation or code.
+
+## Scope
+
+Audit:
+
+```bash
+{
+  find docs -type f -name '*.md' \
+    ! -path 'docs/adr/*' \
+    ! -path 'docs/openapi/*' \
+    ! -path 'docs/assets/*'
+  printf '%s\n' README.md README.zh-CN.md onboarding.html vibe-coding.html
+} | sort
+```
+
+Exclude:
+
+- `docs/adr/` - ADRs are historical decision records; do not treat old decisions as required current behavior unless a stable doc repeats the claim.
+- `docs/openapi/` - interface docs are owned by `coding-http-api` / `make check-openapi`.
+- `docs/assets/` and generated images.
+- `AGENTS.md` - not part of this audit scope for now; it is the agent routing layer, not stable product/operator documentation.
+
+This skill never edits docs or code. It only reads files, runs search/blame commands, and writes the final report to `docs-audit-report.md`.
+
+## Severity
+
+Use exactly these labels:
+
+| Severity | Meaning |
+|---|---|
+| `[Critical]` | Documentation promises behavior, security, API, deployment, data durability, migration, or operational safety that code contradicts or lacks; users/operators could make unsafe decisions. |
+| `[Major]` | Material feature/lifecycle/config/data-model mismatch that can mislead implementers or operators, but does not create an immediate unsafe path. |
+| `[Minor]` | Local outdated detail, renamed package/file, small behavior nuance, stale example, or incomplete status marker with low blast radius. |
+| `[Suggestion]` | Documentation is technically true but could point to newer code, clearer terminology, or useful missing context. |
+
+If unsure between two severities, choose the lower one unless the mismatch can cause broken operations, data loss, security exposure, or incorrect API usage.
+
+## Workflow
+
+### 0. Timebox and stop rules
+
+This audit must be bounded. Do not run an open-ended "check everything until nothing remains" loop.
+
+Default budget for one run:
+
+| Budget | Limit |
+|---|---|
+| Stable doc files scanned | all stable docs, outline only |
+| Candidate claims selected | max 90 |
+| Formal findings | max 40 |
+| Open questions | max 20 |
+| `rg` searches | max 250 |
+| `git blame` / `git log` calls | max 150 |
+| Wall-clock target | about 60 minutes; stop at 90 minutes |
+
+Stop immediately when any limit is reached. In `docs-audit-report.md`, add a short `## 审计边界` section saying which limit stopped the run and that remaining claims were not checked. Do not keep expanding scope.
+
+### 1. Build the audit inventory
+
+List stable docs:
+
+```bash
+{
+  find docs -type f -name '*.md' \
+    ! -path 'docs/adr/*' \
+    ! -path 'docs/openapi/*' \
+    ! -path 'docs/assets/*'
+  printf '%s\n' README.md README.zh-CN.md onboarding.html vibe-coding.html
+} | sort
+```
+
+Inventory pass is outline-only:
+
+```bash
+rg -n '^#{1,4} |<h[1-4][ >]|\\[(已实现|部分实现|规划中)\\]|`[A-Za-z0-9_./:-]+`' \
+  docs README.md README.zh-CN.md onboarding.html vibe-coding.html \
+  --glob '*.md' \
+  --glob '*.html' \
+  --glob '!docs/adr/**' \
+  --glob '!docs/openapi/**' \
+  --glob '!docs/assets/**'
+```
+
+Do not read every document end to end in the first pass. For each file, inspect headings/status markers and pick only concrete, high-risk claims.
+
+Prioritize claims that name concrete implementation surfaces:
+
+- components, packages, binaries, ports, adapters, runtimes
+- config keys, env vars, Helm values, K8s resources, secrets
+- DB tables/columns/indexes and persistence behavior
+- lifecycle/error/retry/idempotency semantics
+- Redis keys/commands, event names, queues, topics
+- public CLI commands and user-visible workflows
+
+Ignore purely explanatory prose unless it asserts current behavior.
+
+Candidate selection rules:
+
+- Take at most 3 candidate claims per doc file in one run.
+- Prefer `[已实现]` and `[部分实现]` claims over `[规划中]`.
+- Prefer higher-risk surfaces first: lifecycle/events, config/deploy, data model, runtime cleanup, security/credentials, API behavior.
+- Skip claims whose identifiers are not concrete enough for targeted `rg`.
+- Record skipped lower-priority areas only in `## 审计边界`, not as findings.
+
+### 2. Turn doc claims into code checks
+
+For each concrete claim, search the implementation using identifiers from the doc. Prefer `rg`:
+
+```bash
+rg -n "<identifier|config_key|type|action|resource>" internal api cmd configs deployments pkg tests
+```
+
+Use structured sources over prose when possible:
+
+| Claim type | Primary evidence |
+|---|---|
+| HTTP / TOP Action behavior | `api/idl/*.thrift`, handlers, service methods |
+| Config / deployment behavior | `configs/engine.yaml.example`, `internal/bootstrap/app/engine_config.go`, `deployments/` |
+| DB schema | GORM PO models and `ensureSchema` wiring |
+| Runtime adapter behavior | adapter `config.go`, `executor.go`, `controller.go`, bootstrap registration |
+| Redis behavior | Redis adapter code and tests for key-slot/hash-tag constraints |
+| Component lifecycle | `cmd/`, `internal/bootstrap/`, component packages |
+
+If the doc names behavior but there is no searchable code evidence, report it only after checking nearby terminology and likely renamed concepts.
+
+Per-claim search cap:
+
+- Max 3 targeted `rg` searches per claim.
+- Max 2 code files inspected per claim.
+- Max 1 negative-search finding per claim. Do not chase every synonym.
+- If the first 3 searches are inconclusive, move the claim to `## 待确认问题` or skip it if low risk.
+
+### 3. Validate before reporting
+
+Every finding needs both:
+
+- **Doc evidence**: exact doc file/line and the claim being contradicted.
+- **Code evidence**: exact code/config file/line showing the current implementation, or a documented negative search when code is absent.
+
+Do not report a mismatch from memory. If evidence is ambiguous, put it under `## 待确认问题` instead of forcing a finding. Do not output "checked and correct" evidence.
+
+Validation cap:
+
+- Spend proof effort only on candidate mismatches, not on correct claims.
+- Once a candidate is proven correct, stop investigating that claim and do not mention it in the report.
+- Once a mismatch has enough doc/code evidence for one finding, stop expanding related sub-issues unless they change severity.
+
+### 4. Attribute with git blame
+
+For every finding, run blame on the doc line(s) and the code line(s):
+
+```bash
+git blame -L <start>,<end> -- <path>
+git log -1 --format='%H%n%an <%ae>%n%ad%n%s' -- <commit>
+```
+
+Mandatory attribution rule:
+
+- **Doc owner**: author of the blamed doc line containing the outdated/current claim.
+- **Code owner**: author of the blamed implementation line proving current behavior.
+- **Responsible person(s)**: every finding must include at least one concrete person from doc blame, code blame, or removal/rename history.
+- **Primary responsible person**: the side most likely responsible for the drift:
+  - stale doc vs newer code: primary = doc owner if doc line is newer than the code behavior it misstates; otherwise primary = code owner if implementation changed after the doc claim.
+  - removed/renamed code with unchanged doc: primary = code owner of the removal/rename when identifiable from `git log -S` / `git log -- <path>`; otherwise primary = doc owner with "implementation removal not isolated".
+  - both sides changed recently or causality unclear: mark both as "joint/unclear" and explain.
+
+For deleted or renamed code paths, use pickaxe/history:
+
+```bash
+git log --follow -- <old-or-current-path>
+git log -S '<identifier>' --all -- <likely-path-or-directory>
+```
+
+If blame returns an all-zero commit for uncommitted changes, attribute that side to `working tree (uncommitted)` and say final ownership requires commit history.
+
+If the investigation cannot produce a specific person for either side, the item is not a formal finding. Move it to `## 待确认问题` with the missing attribution step.
+
+Attribution cap:
+
+- Run blame only after a mismatch is validated.
+- Use one blame range for the doc claim and one blame range for the code evidence.
+- Use `git log -S` / `--follow` only for deleted/renamed code evidence, max 2 commands per finding.
+- Do not blame every supporting line; attribute the line that best represents the drift.
+
+### 5. Write `docs-audit-report.md`
+
+Write the final report to repo-root `docs-audit-report.md` using this Chinese structure. Do not add a section for correct results or executed commands.
+
+```markdown
+## 文档实现一致性审计
+
+范围：稳定 `docs/` Markdown 加根目录 `README.md`、`README.zh-CN.md`、`onboarding.html`、`vibe-coding.html`；排除 `docs/adr/`、`docs/openapi/`、`docs/assets/` 和 `AGENTS.md`。
+版本：`<git rev-parse --short HEAD>`
+
+## 摘要
+- Critical: N
+- Major: N
+- Minor: N
+- Suggestion: N
+- 仅统计差异点；未列出的文档/检查项表示未发现需要报告的问题。
+
+## 审计边界
+- 候选 claim：N / 90
+- 正式差异点：N / 40
+- 待确认问题：N / 20
+- 搜索/归因预算：说明是否触达上限。
+- 未覆盖范围：仅在触达预算上限或主动跳过高成本区域时填写。
+
+## 差异点
+
+### [Severity] 简短标题
+- 文档证据：`<doc path>:<line>` - 用中文概括文档声称了什么。
+- 实现证据：`<path>:<line>` - 用中文概括当前代码/配置实际是什么；如果是缺失，写明负向搜索命令和范围。
+- 差异说明：一句话说明文档与实现如何不一致。
+- 责任归因：
+  - 主要责任人：`<姓名> <email>`，`<commit short>`，`<date>`，`<commit subject>` - 用中文说明为什么归到此人/此提交。
+  - 文档 blame：`<姓名> <email>`，`<commit short>`，`<date>`，`<commit subject>`。
+  - 实现 blame：`<姓名> <email>`，`<commit short>`，`<date>`，`<commit subject>`；若实现缺失，改为 `删除/重命名历史` 并给出 `git log -S` 或 `git log --follow` 定位到的提交。
+- 建议处理：用中文说明应该让人更新文档、核实实现，或补充代码；不要直接修改。
+
+## 按人员整理的任务
+
+### `<姓名> <email>` 或 `<email>`
+- `[Severity] <差异点标题>`：该人员需要完成的动作。明确是更新文档、核实实现、补代码、补配置，还是协调另一侧 owner。
+- 证据：引用对应差异点里的文档/实现证据路径，不重新展开完整 blame。
+
+## 待确认问题
+- 只放证据不足、实现语义不明确、或无法归因到具体人员的疑似问题。不要混入正式差异点。
+```
+
+If there are no discrepancies, output only:
+
+```markdown
+## 文档实现一致性审计
+
+范围：稳定 `docs/` Markdown 加根目录 `README.md`、`README.zh-CN.md`、`onboarding.html`、`vibe-coding.html`；排除 `docs/adr/`、`docs/openapi/`、`docs/assets/` 和 `AGENTS.md`。
+版本：`<git rev-parse --short HEAD>`
+
+未发现需要报告的文档/实现差异。
+
+## 审计边界
+- 候选 claim：N / 90
+- 搜索/归因预算：未触达上限 / 触达上限。
+```
+
+Sort findings by severity, then by document path.
+
+Build `## 按人员整理的任务` after finalizing `## 差异点`:
+
+- Group by `主要责任人`; if a finding is marked joint/unclear but has concrete people, list the task under every named person and say "共同确认".
+- Task group headings must include a bytedance email whenever available from blame/log output, because `docs-audit-to-issues.py` uses that email to resolve the Codebase assignee. A display name alone is not enough for automation.
+- Do not create tasks for `## 待确认问题` unless a concrete next owner is known from blame/history; otherwise leave them only in `## 待确认问题`.
+- Do not include people from correct checks, because correct checks must not be reported.
+- Keep task wording action-oriented and specific enough for assignment.
+
+## Quality Bar
+
+- Audit must follow the fixed budget in §0; do not exceed it to chase completeness.
+- No finding without line-level doc evidence.
+- No finding without line-level implementation evidence or an explicit negative-search note.
+- No finding without a named responsible person backed by `git blame` / `git log` evidence.
+- No final report with formal findings unless it also contains `## 按人员整理的任务`.
+- Final report must be written to repo-root `docs-audit-report.md`.
+- No output of correct/matched checks.
+- Final report must be Chinese, except fixed severity labels and file/command names.
+- Do not blame authors for historical ADR drift; ADRs are out of scope.
+- Do not modify documentation as part of this skill.

package/templates/.agents/skills/coding-docs-audit-autofix/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: coding-docs-audit-autofix
+description: 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-autofix
+
+This skill is the docs-audit split stage. It does two things:
+
+1. Fix only findings that are clearly documentation drift after reading the cited docs and implementation.
+2. Write `docs-audit-notification-report.md` by removing the fixed documentation-only findings from the original report, so notification can send that file without doing its own semantic filtering.
+
+## Required References
+
+Read these references before acting:
+
+- `.agents/skills/coding-docs-audit-autofix/references/autofix-docs.md` - how to judge and fix documentation-only findings.
+- `.agents/skills/coding-docs-audit-autofix/references/notification-report.md` - how to derive the notification report from the original report.
+
+Only read `.agents/skills/coding-docs-audit-autofix/references/open-mr.md` when changing the CI MR-opening script or pipeline flow.
+
+## Hard Boundaries
+
+- Do not edit code, config, deployment YAML, migrations, API contracts, ADRs, OpenAPI docs, or generated assets.
+- Do not classify by keyword rules alone. Use the finding's actual meaning, the cited documentation, and the cited implementation/config evidence.
+- Be conservative: if a finding could require implementation work, leave it in `docs-audit-notification-report.md`.
+- Keep `docs-audit-report.md` as the immutable original audit output. Write the derived notification copy to `docs-audit-notification-report.md`.
+
+## Expected Outputs
+
+- Stable doc edits only within the docs-audit stable-document scope owned by `scripts/lib/docs-audit-scope.sh`, only when safe.
+- `docs-audit-notification-report.md` always exists after the skill runs.
+- If no findings were fixed, `docs-audit-notification-report.md` is an exact semantic copy of `docs-audit-report.md`.

package/templates/.agents/skills/coding-http-api/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: coding-http-api
+description: 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-http-api: API / IDL / Handler Contract
+
+## Trigger — does this skill apply?
+
+YES if your change touches any of:
+
+- `api/idl/*.thrift` (any field, struct, service method, or annotation)
+- `internal/adapters/inbound/http/thrift_gen/` (this is generated — touch the IDL instead)
+- `internal/adapters/inbound/http/handlers/<aggregate>_handler.go`
+- `internal/application/<aggregate>/dto.go` or `mapper.go` if the application boundary type is changing
+- `web/` and the change you're making affects API requests/responses
+- A field's `optional` ↔ `required` flip in any IDL struct
+- `docs/openapi/coding-engine-api.html` (Redocly-rendered page; regenerated from the IDL together with `docs/openapi/openapi.yaml` by `make check-openapi`; Makefile pins Redocly to the same `@redocly/cli@2.31.6` version used by CI because HTML output changes across Redocly versions)
+
+NO if you're only touching internal domain logic that doesn't reach the wire.
+
+
+## The Pipeline
+
+```
+api/idl/<aggregate>.thrift   ← single source of truth (Thrift IDL)
+        │
+        │  make gen-thrift        (hz model — uses api/idl/server.thrift as umbrella)
+        ▼
+internal/adapters/inbound/http/thrift_gen/<aggregate>/   ← generated, never hand-edit
+        │
+        │  imported by handlers
+        ▼
+internal/adapters/inbound/http/handlers/<aggregate>_handler.go   ← Hertz handler, implements httpserver.<Service>
+        │
+        │  calls application use cases
+        ▼
+internal/application/<aggregate>/   ← service, DTO, mapper
+        │
+        │  uses domain types
+        ▼
+internal/domain/<aggregate>/   ← entity, repository
+```
+
+A change at the IDL surface must be rolled forward through every layer in the same PR. Single-layer edits are caught at compile time only when handlers `var _ httpserver.AgentService = (*AgentHandler)(nil)` — but field semantics (rename without compile-break) won't be.
+
+
+## IDL Conventions
+
+Scope: current `api/idl/*.thrift` files are all TOP / Hertz HTTP API contracts. `make gen-thrift` consumes `api/idl/server.thrift` as the umbrella and generates HTTP models under `internal/adapters/inbound/http/thrift_gen/`. There are no internal RPC / non-HTTP-exposed IDL exceptions today. If a future non-HTTP IDL surface is introduced, it must use a separate directory or an explicitly documented file boundary before this convention can diverge.
+
+```thrift
+struct CreateAgentRequest {
+    1:  required string WorkspaceID            (go.tag = 'json:"WorkspaceID"')
+    2:  required string Name                   (go.tag = 'json:"Name"')
+    3:  optional string Description            (go.tag = 'json:"Description,omitempty"')
+    4:  optional string ModelID                (go.tag = 'json:"ModelID,omitempty"')
+}
+```
+
+Mandatory rules:
+
+| Rule | Why |
+|---|---|
+| Field IDs are stable. **Never reuse** a field ID for a different field even after removal | Thrift wire compatibility — old clients sending the old id at the new struct corrupts decoding |
+| `optional` fields ALWAYS carry `,omitempty` in their `go.tag` JSON spec | Prevents `null` / zero values from being sent over the wire when the caller didn't set them |
+| `required` fields NEVER use `,omitempty` | The whole point of required is that it must serialize |
+| Request structs do not expose transport identity fields; user and tenant data come from `requestctx` | Keeps identity handling in the HTTP dispatcher/middleware layer |
+| Field ID `255` is reserved for legacy compatibility | Don't reuse field id 255 for anything else |
+| Field name in PascalCase (Thrift), JSON key also in PascalCase via `go.tag` for all `api/idl/*.thrift` files | Project HTTP API convention; keep request/response wire shape aligned with generated frontend types. Run `make lint-thrift` to validate IDL syntax; it does not enforce JSON casing, so keep casing manually consistent or add a regen-time check |
+| Service / response struct names match across the file | `AgentService.CreateAgent → CreateAgentRequest → AgentResponse` |
+
+After editing IDL, regenerate:
+
+```bash
+make gen-thrift           # Hertz HTTP models (writes thrift_gen/)
+```
+
+The IDL → Go pipeline is HTTP-only: Hertz `hz model` consumes `api/idl/server.thrift` and writes `internal/adapters/inbound/http/thrift_gen/<aggregate>/`. There is no RPC stub codegen and no top-level generated RPC package — handlers depend only on the HTTP models above.
+
+Never hand-edit `internal/adapters/inbound/http/thrift_gen/` — the next regen wipes it.
+
+
+## Compatibility — Required ↔ Optional Flips
+
+| Direction | Wire impact | Cleanup required |
+|---|---|---|
+| `optional → required` | **Breaking**: callers that omit it now fail validation | Audit every caller (frontend, SDK, internal); the field must be guaranteed-present at the application layer first |
+| `required → optional` | **Non-breaking** for callers, but breaks consumers if the response side: clients reading the field expecting non-null break | Audit response readers; ensure handler still produces it when available |
+| Add new `optional` field | Non-breaking | Frontend can choose to populate over time |
+| Add new `required` field | **Breaking** | Must coordinate with all clients; ship as `optional` first, flip later |
+| Remove field | **Breaking** | Same audit as required→optional, plus remove all DTO/mapper/handler/event references |
+
+History — the `Agent.Name optional → required` flip in commit `66b0ea5`:
+> 将 Agent Name 字段从 optional 改为 required，使 IDL 定义与业务层校验保持一致；同时清理 DisplayName 字段在 domain/dto/mapper/handler/events 中的遗留引用
+
+That commit touched 6 layers: IDL, DTO, mapper, handler, domain entity, event payload. The Cross-Layer Cleanup Checklist below codifies that audit.
+
+
+## Cross-Layer Cleanup Checklist (rename / remove / type-change)
+
+When a field is **renamed**, **removed**, or **type-changed**, every following file class needs an audit:
+
+- [ ] `api/idl/<aggregate>.thrift` — request, response, list-response, and any nested input struct
+- [ ] `internal/adapters/inbound/http/thrift_gen/<aggregate>/` — regenerated via `make gen-thrift`
+- [ ] `internal/adapters/inbound/http/handlers/<aggregate>_handler.go` — every method that reads/writes the field
+- [ ] `internal/adapters/inbound/http/handlers/<aggregate>_handler_test.go` — table cases
+- [ ] `internal/application/<aggregate>/dto.go` — request/response DTO struct
+- [ ] `internal/application/<aggregate>/mapper.go` — domain ↔ DTO conversion
+- [ ] `internal/application/<aggregate>/service.go` (or use-case files) — direct field reads/writes
+- [ ] `internal/domain/<aggregate>/entity.go` — aggregate root field
+- [ ] `internal/domain/events/*.go` — event payloads if the field appears
+- [ ] `internal/adapters/outbound/persistence/rdb/po/<aggregate>.go` — GORM model
+- [ ] `web/` — frontend request/response types (TypeScript or generated client)
+- [ ] `docs/openapi/openapi.yaml` + `docs/openapi/coding-engine-api.html` — regenerated by `make check-openapi` so the new/renamed/removed `paths` and `components.schemas` are reflected; commit both
+- [ ] `docs/0N-*.md` — component doc API tables
+- [ ] `docs/07-data-model.md` — if the field shows in the data-model description
+- [ ] If breaking and persistent: ADR 0003 entry under `docs/adr/`
+
+Verification — single grep before merging:
+
+```bash
+grep -rn "<old_field_name>" api/ internal/ web/ docs/
+# Expected: zero hits OR explicit rationale per remaining hit
+```
+
+
+## Cross-Layer Plumbing Checklist (field-add)
+
+Adding a new field to a Request or Response struct **does not wire itself up** — `make gen-thrift` produces getters and setters, not the application boundary. Without an end-to-end pass the field is silently dropped: compile passes, request body parses, persisted entity holds the zero value.
+
+History — `fix(agent): plumb SystemPrompt through CreateAgent/UpdateAgent HTTP API` (commit c6c45d7): `SystemPrompt` was added to `CreateAgentRequest` / `UpdateAgentActionRequest` / `AgentResponse` in IDL, but the handler never called `req.GetSystemPrompt()`, the command struct did not carry it, and the response mapper did not set it back. Persisted agents had empty system prompts and `GetAgent` returned an empty field.
+
+Audit every layer a new field must traverse:
+
+- [ ] `api/idl/<aggregate>.thrift` — fresh field ID; `,omitempty` matches optional/required (see §IDL Conventions)
+- [ ] `make gen-thrift` regenerated
+- [ ] `internal/adapters/inbound/http/handlers/<aggregate>_handler.go` — **read `req.GetXxx()` and pass into the application command**; **populate `resp.Xxx` in the response mapper** (`agentResponseFromDTO` and equivalents)
+- [ ] `internal/adapters/inbound/http/handlers/<aggregate>_handler_test.go` — round-trip case: send the field in the request, assert it on the persisted entity AND in the response payload
+- [ ] `internal/application/<aggregate>/dto.go` — Command / Query DTO carries the field; for Update commands, use `*string` (or matching pointer type) so callers can express "unchanged"
+- [ ] `internal/application/<aggregate>/service.go` — read from the command; write onto the entity (Create) or thread through the existing dirty-flag helper (Update — `optionalStringValue` / `hasAgentChanges` pattern)
+- [ ] `internal/domain/<aggregate>/entity.go` — aggregate root field
+- [ ] Persistent storage, if any — load `coding-db-schema` for PO, migration, repository, and data-model rules
+- [ ] `web/` — frontend request/response TypeScript types
+- [ ] `docs/openapi/openapi.yaml` + `docs/openapi/coding-engine-api.html` — regenerated by `make check-openapi` so the new field's parent schema is included; commit both
+
+### Audit-field seeding (Create use cases)
+
+GORM PO audit columns in this repo are **all hand-seeded**, not GORM-managed:
+
+| Column | PO type | Auto-managed? |
+|---|---|---|
+| `created_by` | `string`, no DB default | No — Go entity value persists verbatim, including `""` |
+| `updated_by` | `string`, no DB default | No — same |
+| `created_at` | `int64` (epoch ms), `not null` | No — POs use `int64` not `time.Time`, no `autoCreateTime` tag |
+| `updated_at` | `int64` (epoch ms), `not null` | No — same |
+
+The Go entity-construction site in `internal/application/<aggregate>/service.go` is the **only** place these get populated.
+
+On every `Create`:
+
+- [ ] Set `entity.CreatedBy = cmd.CreatedBy`
+- [ ] **Set `entity.UpdatedBy = cmd.CreatedBy`** — otherwise rows persist with `UpdatedBy=""` until the first `Update` call (`fix(agent,gateway): seed UpdatedBy on CreateAgent`, commit 56d7a12). `ListAgents` / `GetAgent` will return an empty `UpdatedBy` for freshly created records
+- [ ] Seed `entity.CreatedAt` and `entity.UpdatedAt` from `s.deps.Now().UTC()` — both fields, same timestamp
+- [ ] If the Create transaction also constructs nested child entities (e.g. channels, MCPs, skills), apply the same four-field seeding rule to each
+- [ ] Handler test asserts the persisted entity has all four audit fields populated, not just `CreatedBy`
+
+
+## Handler Pattern (Hertz)
+
+Canonical handler shape — `internal/adapters/inbound/http/handlers/agent_handler.go`:
+
+```go
+type AgentHandler struct {
+    service      agent.Service
+    userResolver port.UserResolver
+}
+
+var _ httpserver.AgentService = (*AgentHandler)(nil)   // compile-time contract pin
+
+func NewAgentHandler(service agent.Service, userResolver port.UserResolver) *AgentHandler {
+    return &AgentHandler{
+        service:      service,
+        userResolver: userResolver,
+    }
+}
+
+func (h *AgentHandler) CreateAgent(ctx context.Context, req *httpagent.CreateAgentRequest) (*httpagent.CreateAgentResponse, error) {
+    if req == nil {
+        return nil, toHTTPError(invalid("req is required"))
+    }
+    tenantID, workspaceID, err := tenantAndWorkspaceID(ctx, req.GetWorkspaceID())
+    if err != nil {
+        return nil, toHTTPError(err)
+    }
+    // ... map Thrift req → application DTO, call h.service.CreateAgent(ctx, agent.CreateAgentCommand{...}), map result → Thrift resp
+}
+```
+
+Mandatory rules:
+
+- `var _ httpserver.<Service> = (*<Aggregate>Handler)(nil)` — compile-time interface check; never remove
+- All errors flow through `toHTTPError(err)` (defined in `helpers.go`); never return raw `error`
+- All validation errors use `invalid(msg)`; never `errors.New`
+- Pull `tenantID` / `workspaceID` from request context via `tenantAndWorkspaceID(ctx, ...)` — never trust request body fields alone
+
+
+## Frontend Alignment Trigger
+
+Whenever a request or response struct changes shape (field added, removed, renamed, required-flipped, or type-changed), the frontend must be aligned. History: `feat: align coding frontend with updated APIs` was a single PR retrofitting many drift items at once — exactly the situation this skill prevents.
+
+Practical workflow:
+
+1. Make the IDL + handler + tests change in one branch
+2. In the same PR (or a paired PR): update `web/` API client types and any UI code that reads removed/renamed fields
+3. CI should fail loudly if frontend types drift — if no such CI exists, treat the audit as manual and run a grep across `web/`
+
+
+## Templates (copy and adapt)
+
+| Need | Template |
+|------|----------|
+| New IDL service + struct skeleton | `.agents/skills/coding-http-api/templates/new-service.thrift` |
+| New Hertz handler skeleton | `.agents/skills/coding-http-api/templates/new-handler.go` |
+| Pre-merge cross-layer grep | `.agents/skills/coding-http-api/templates/grep-field.sh` |
+
+
+## Done Checklist
+
+- [ ] IDL change applied; field IDs unchanged for existing fields; new fields use fresh IDs
+- [ ] `make gen-thrift` run; `thrift_gen/` regenerated
+- [ ] Handler updated; `var _ httpserver.<Service> = ...` still compiles
+- [ ] DTO and mapper updated; domain entity updated if the field is persistent
+- [ ] If persistent: GORM PO / AutoMigrate schema update via `coding-db-schema`
+- [ ] If breaking: ADR 0003 entry; doc updated
+- [ ] Frontend aligned in the same PR (or explicit paired PR linked)
+- [ ] Cross-layer grep returns clean (rename / remove / type-change)
+- [ ] If field-add: §Cross-Layer Plumbing Checklist passes (`req.GetXxx()` → command → entity → response, round-trip handler test)
+- [ ] If Create use case: all four audit fields seeded (`CreatedBy`, `UpdatedBy`, `CreatedAt`, `UpdatedAt`); nested child entities seeded the same way
+- [ ] `docs/openapi/openapi.yaml` + `docs/openapi/coding-engine-api.html` regenerated by `make check-openapi` (green, working tree clean) and committed (mandatory whenever `api/idl/*.thrift` changed; use the Makefile default pinned Redocly version unless intentionally matching a CI version bump)
+- [ ] Handler tests updated — see `coding-testing` Strategy 4
+
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| Hand-edit a file under `internal/adapters/inbound/http/thrift_gen/` | Lost on next `make gen-thrift`. Edit the `.thrift` and regen |
+| Reuse a removed field's ID for a new field | Old clients sending old data populate the new field with garbage. Use a fresh ID |
+| Add `optional` field but forget `,omitempty` in `go.tag` | Zero values serialize as `null`, frontend dispatches false truthy paths |
+| Flip `required → optional` without auditing response readers | Frontend code reading `.field` without nil-check breaks — required field-flip needs explicit handling |
+| Rename a field, update IDL + handler, forget `web/` | "Works locally" until first frontend request fails 400/422 |
+| Update Thrift but skip `make gen-thrift` | `thrift_gen/` is stale; `var _ httpserver.<Service>` still compiles against old shape |
+| Add new endpoint to IDL but forget to add it to `httpserver.<Service>` interface assertion | Compile passes (interface assertion only checks declared methods); endpoint exists but routing missed. Always re-pin the interface |
+| Drop a field from `events/*.go` payload but leave domain entity carrying it | Event consumers receive zero-value; tests pass but downstream breaks |
+| Use `errors.New("invalid")` in handler | Use `invalid("descriptive message")`; the helper sets correct HTTP status |
+| Skip handler test update — only update the use-case test | Handler tests catch mapper / Thrift binding regressions; both are required |
+| Add new IDL field, run `make gen-thrift`, but handler skips `req.GetXxx()` or response mapper does not set `resp.Xxx` | Silent drop — compile passes, request parses, persisted entity holds the zero value. Wire end-to-end (cmd → entity → response) and add a round-trip handler test |
+| On `Create`, set only `CreatedBy` (leave `UpdatedBy` / `CreatedAt` / `UpdatedAt` zero) | PO columns have no DB default and `int64` timestamps are not GORM-managed — rows persist with `UpdatedBy=""` and `UpdatedAt=0` until first `Update`. Seed all four from the requesting user + `s.deps.Now()` |
+
+
+## Cross-references
+
+- `Makefile` — `gen-thrift` target is authoritative (HTTP-only; no RPC codegen)
+- `coding-architecture` — the layer map (handler → service → domain → adapter) and DTO/mapper conventions
+- `coding-testing` Strategy 4 — handler tests with Hertz test client
+- `coding-db-schema` — when the field is persistent, GORM schema ownership must be updated alongside
+- `coding-deploy-config` — when an endpoint changes port, probe path, or Service contract
+- `docs/CONVENTIONS.md` — `[已实现]` / `[规划中]` status markers for component-doc updates