Build layered multi-agent rule artifacts

Author: ly

Makefile

@@ -1,4 +1,4 @@
-.PHONY: all bootstrap sync update plan self-update smoke ui help doctor detect fetch-models status cleanup unlock backups-list backups\:list restore backups\:restore logs rules-sync rules\:sync skills-link skills\:link skills\:upgrade mcp-sync mcp\:sync mcp-prepare mcp\:prepare tools-sync tools\:sync terminal-sync terminal\:sync dry-run clean-logs offline
+.PHONY: all bootstrap sync update plan self-update smoke ui help doctor detect fetch-models status cleanup unlock backups-list backups\:list restore backups\:restore logs rules-build rules\:build rules-sync rules\:sync skills-link skills\:link skills\:upgrade mcp-sync mcp\:sync mcp-prepare mcp\:prepare tools-sync tools\:sync terminal-sync terminal\:sync dry-run clean-logs offline
 
 # 默认目标：显示帮助，不执行任何同步操作
 .DEFAULT_GOAL := help
@@ -86,6 +86,12 @@ clean-logs:
 	@./manage.sh clean-logs
 
 # 独立同步任务
+rules-build:
+	@./manage.sh rules:build
+
+rules\:build:
+	@./manage.sh rules:build
+
 rules-sync:
 	@./manage.sh rules:sync
 

README.md

@@ -54,6 +54,12 @@
 - **安全入口**：直接执行 `./manage.sh` 只显示帮助，不触发同步。
 - **终端配置默认关闭**：`sync` / `update` / `bootstrap` 默认不会改写 `~/.zshrc`、`~/.tmux.conf` 或 iTerm2 动态配置；如需启用，请在 `config/manager.local.json` 中设置 `"terminal": { "enabled": true }`。
 
+### 6. Rules 源码与分发分层
+- **可编辑源码**：跨 Agent 的共享规则片段维护在 `agent-rule/rules/src/`。
+- **生成产物**：面向各 Agent 实际分发的规则文件维护在 `agent-rule/rules/dist/`，由构建脚本生成。
+- **分发清单**：`config/rules-targets.list` 只引用 `rules/dist/*` 产物，不直接引用源码片段。
+- **维护入口**：修改 `agent-rule/rules/src/` 后，先执行 `make rules-build`，再执行 `make rules:sync`。
+
 ## 平台支持 (Platform Support)
 
 - 本项目当前以 **macOS** 为主要验证平台；**Linux** 路径保持 POSIX 兼容设计，但仍建议在目标环境自行回归验证。  
@@ -71,6 +77,8 @@
 - `make self-update`: 仅更新 agent-manager 仓库自身逻辑。
 - `make smoke`: 运行跨平台安全预演 smoke 校验，基于最小策略文件 `config/manager.smoke.json` 验证主入口命令的 dry-run / preview 契约。
 - `make doctor` / `make status`: 执行全系统深度体检，并把 warning 细分为 `可选工具未就绪` 与 `托管产物尚未生成` 两类提示项；追加 `--json` 可输出机器可读诊断报告。
+- `make rules-build`: 从 `agent-rule/rules/src/` 生成 `agent-rule/rules/dist/` 下的可分发规则产物。
+- `make rules:sync`: 将 `agent-rule/rules/dist/` 中的规则产物分发到各 Agent 规则目录。
 - `make fetch-models`: 探测并获取 API 端点支持的模型列表 (支持 OpenAI / Anthropic 格式)。
 - `make restore`: 交互式回滚历史快照。
 - `make ui`: 启动交互式配置管理中心。

agent-rule/rules/dist/.gitkeep

@@ -0,0 +1,30 @@
+<!-- Generated by agent-rule/scripts/build-agent-rules.py. Edit files in agent-rule/rules/src/ instead. -->
+
+# Agent Behavior Guidelines
+
+## 1. Core Mandates
+
+- Use Chinese (Simplified) for interactions and generated content. Keep technical terms in English only when translation would reduce clarity.
+
+## 2. Tool Strategy & Workflow
+
+- **Primary Semantic Search:** Use `codebase-retrieval` first when file locations or ownership are unclear.
+- **Plan Before Editing:** Explore context and impact before making non-trivial edits.
+- **Exact Match Search:** Use local file tools or `rg` for exact identifiers, config keys, logs, and generated text.
+- **Verification is CRITICAL:** Run the narrowest relevant verification after changes and report any skipped checks or missing automation.
+
+## 3. Domain Rules (Progressive Disclosure)
+
+Before executing work in a matching domain, read the corresponding module with your file-reading tools.
+
+- **Architecture & System Design:** For new modules, shared interfaces, or dependency-boundary changes, read `modules/architecture.md`.
+
+- **Code Style & Integrity:** For code, config, data contracts, or comments, read `modules/style.md`.
+
+- **Frontend Development & Verification:** For UI, user flows, frontend validation, or browser automation, read `modules/frontend.md`.
+
+- **Generated Output & Artifact Hygiene:** For Playwright, generators, generated artifacts, or temporary debug output, read `modules/artifact-hygiene.md`.
+
+# Claude Adapter
+
+Keep project memory concise and project-specific. Do not duplicate shared standing policy in Claude-specific memory files unless the repository needs a local override.

agent-rule/rules/dist/claude/main.md

@@ -0,0 +1,30 @@
+<!-- Generated by agent-rule/scripts/build-agent-rules.py. Edit files in agent-rule/rules/src/ instead. -->
+
+# Agent Behavior Guidelines
+
+## 1. Core Mandates
+
+- Use Chinese (Simplified) for interactions and generated content. Keep technical terms in English only when translation would reduce clarity.
+
+## 2. Tool Strategy & Workflow
+
+- **Primary Semantic Search:** Use `codebase-retrieval` first when file locations or ownership are unclear.
+- **Plan Before Editing:** Explore context and impact before making non-trivial edits.
+- **Exact Match Search:** Use local file tools or `rg` for exact identifiers, config keys, logs, and generated text.
+- **Verification is CRITICAL:** Run the narrowest relevant verification after changes and report any skipped checks or missing automation.
+
+## 3. Domain Rules (Progressive Disclosure)
+
+Before executing work in a matching domain, read the corresponding module with your file-reading tools.
+
+- **Architecture & System Design:** For new modules, shared interfaces, or dependency-boundary changes, read `modules/architecture.md`.
+
+- **Code Style & Integrity:** For code, config, data contracts, or comments, read `modules/style.md`.
+
+- **Frontend Development & Verification:** For UI, user flows, frontend validation, or browser automation, read `modules/frontend.md`.
+
+- **Generated Output & Artifact Hygiene:** For Playwright, generators, generated artifacts, or temporary debug output, read `modules/artifact-hygiene.md`.
+
+# Codex Adapter
+
+Use the shared rule core as the default policy. Prefer direct local verification, explicit file edits, and deterministic command usage over speculative narration.

agent-rule/rules/dist/codex/main.md

@@ -0,0 +1,30 @@
+<!-- Generated by agent-rule/scripts/build-agent-rules.py. Edit files in agent-rule/rules/src/ instead. -->
+
+# Agent Behavior Guidelines
+
+## 1. Core Mandates
+
+- Use Chinese (Simplified) for interactions and generated content. Keep technical terms in English only when translation would reduce clarity.
+
+## 2. Tool Strategy & Workflow
+
+- **Primary Semantic Search:** Use `codebase-retrieval` first when file locations or ownership are unclear.
+- **Plan Before Editing:** Explore context and impact before making non-trivial edits.
+- **Exact Match Search:** Use local file tools or `rg` for exact identifiers, config keys, logs, and generated text.
+- **Verification is CRITICAL:** Run the narrowest relevant verification after changes and report any skipped checks or missing automation.
+
+## 3. Domain Rules (Progressive Disclosure)
+
+Before executing work in a matching domain, read the corresponding module with your file-reading tools.
+
+- **Architecture & System Design:** For new modules, shared interfaces, or dependency-boundary changes, read `modules/architecture.md`.
+
+- **Code Style & Integrity:** For code, config, data contracts, or comments, read `modules/style.md`.
+
+- **Frontend Development & Verification:** For UI, user flows, frontend validation, or browser automation, read `modules/frontend.md`.
+
+- **Generated Output & Artifact Hygiene:** For Playwright, generators, generated artifacts, or temporary debug output, read `modules/artifact-hygiene.md`.
+
+# Gemini Adapter
+
+Prefer concise CLI-oriented guidance. Keep standing instructions short and use task-triggered modules for low-frequency detail.

agent-rule/rules/dist/gemini/main.md

@@ -0,0 +1,30 @@
+<!-- Generated by agent-rule/scripts/build-agent-rules.py. Edit files in agent-rule/rules/src/ instead. -->
+
+# Agent Behavior Guidelines
+
+## 1. Core Mandates
+
+- Use Chinese (Simplified) for interactions and generated content. Keep technical terms in English only when translation would reduce clarity.
+
+## 2. Tool Strategy & Workflow
+
+- **Primary Semantic Search:** Use `codebase-retrieval` first when file locations or ownership are unclear.
+- **Plan Before Editing:** Explore context and impact before making non-trivial edits.
+- **Exact Match Search:** Use local file tools or `rg` for exact identifiers, config keys, logs, and generated text.
+- **Verification is CRITICAL:** Run the narrowest relevant verification after changes and report any skipped checks or missing automation.
+
+## 3. Domain Rules (Progressive Disclosure)
+
+Before executing work in a matching domain, read the corresponding module with your file-reading tools.
+
+- **Architecture & System Design:** For new modules, shared interfaces, or dependency-boundary changes, read `modules/architecture.md`.
+
+- **Code Style & Integrity:** For code, config, data contracts, or comments, read `modules/style.md`.
+
+- **Frontend Development & Verification:** For UI, user flows, frontend validation, or browser automation, read `modules/frontend.md`.
+
+- **Generated Output & Artifact Hygiene:** For Playwright, generators, generated artifacts, or temporary debug output, read `modules/artifact-hygiene.md`.
+
+# IDE Adapter
+
+Keep editor-facing guardrails short. Retain only high-value behavioral constraints and leave detailed workflow guidance to shared modules.

agent-rule/rules/dist/ide/main.md

@@ -0,0 +1,15 @@
+# Architecture Guidelines
+
+Read this rule before introducing new modules, changing shared interfaces, or altering dependency boundaries.
+
+## Required Checks
+
+- Prefer the smallest local change that satisfies the task. Do not introduce a new abstraction unless there are at least two real consumers or a clear boundary problem.
+- Keep dependency direction explicit. UI or CLI may depend on application or service code; application code may depend on domain code; infrastructure must stay behind adapters instead of leaking inward.
+- Shared modules must expose a narrow interface, have a clear owner, and justify their existence with a concrete caller or test.
+- Config, schema, and workflow changes must define defaults, failure mode, rollback path, and whether migration is required.
+
+## Before Completion
+
+- Verify every changed entry point still has an obvious dependency path and no new circular dependency.
+- Run the narrowest relevant verification for the affected boundary. If automation is missing, state that gap explicitly instead of implying coverage.

agent-rule/rules/dist/modules/architecture.md

@@ -0,0 +1,41 @@
+# Artifact Hygiene Guidelines
+
+Prefer the target project's existing conventions over universal output rules. Choose output locations based on whether the files are maintained by the team or consumed by project workflows.
+
+## Output Classification
+
+- **Project assets:** files intentionally maintained by the team or expected to be reused, such as source code, shared helpers, stable fixtures, maintained config, approved snapshots, and durable documentation.
+- **Workflow-consumed artifacts:** generated files that may be transient but are already expected by repository workflows such as config, scripts, or CI, or that the user explicitly asked to standardize as a reusable project convention.
+- **Disposable run artifacts:** ad hoc debug scripts, copied reports, temporary screenshots, traces, videos, downloads, storage state, JSON/HTML dumps, and investigation notes that only serve the current run and are not referenced by project workflows.
+
+## Required Workflow
+
+1. Classify the expected output before running the tool.
+2. If the project already defines a location or naming convention for that output, follow it.
+3. If the output is a project asset, store it in the maintained project path and keep it cleanly reviewable.
+4. If the output is generated and already consumed by repository workflows, prefer the project's standard gitignored output directory inside the working tree.
+5. If the repository does not already consume that output, establish a new project-local convention only when the user explicitly asks for one.
+6. If reuse or workflow consumption is uncertain, classify the output as a disposable run artifact.
+7. If the output is disposable and no workflow depends on a working-tree path, use `mktemp -d`, `$TMPDIR`, or `/tmp`.
+8. Do not create or widen `.gitignore`, config conventions, or repository directories just to host disposable outputs for the current task.
+9. If a disposable artifact must temporarily land in a project-local ignored directory, delete it before completion unless the user explicitly asks to keep it.
+10. Never place disposable artifacts in tracked paths or likely-to-be-committed locations such as the repository root, `docs/`, `scripts/`, `tests/fixtures/`, or ad hoc folders created for a single run.
+
+## Playwright-Specific Rules
+
+Before invoking `playwright-cli` or Playwright test commands, classify the expected output as a project asset, workflow-consumed artifact, or disposable run artifact.
+
+- **Usually project assets:** test specs, page objects, shared fixtures, helper utilities, stable config changes, and intentionally maintained visual snapshots.
+- **Usually workflow-consumed artifacts:** `playwright-report/`, `test-results/`, `blob-report/`, JUnit or JSON result files, and other outputs explicitly referenced by project scripts or CI.
+- **Usually disposable run artifacts:** one-off traces, videos, screenshots, downloads, copied reports, temporary auth state, and ad hoc HAR, JSON, or storage dumps created only for a local investigation.
+
+## Playwright Defaults
+
+- Start from the repository's Playwright config, CI pipeline, and reporting conventions before adding output paths.
+- Treat standard ignored directories such as `playwright-report/`, `test-results/`, and `blob-report/` as workflow-consumed locations only when repository workflows actually use them, not as storage for one-off investigation files.
+- Do not update the target project's `.gitignore` or invent a repository output convention just to preserve disposable Playwright artifacts.
+- If a disposable experiment is worth keeping, promote it into a maintained project asset and delete the disposable original.
+
+## Decision Rule
+
+When unsure, prefer established project conventions. Use project-local ignored output directories only for workflow-consumed artifacts already used by repository workflows, or when the user explicitly asks to create a reusable project convention. Otherwise, treat the output as disposable and use OS temp directories unless a working-tree path is required.

agent-rule/rules/dist/modules/artifact-hygiene.md

@@ -0,0 +1,9 @@
+# Frontend Guidelines
+
+Focus on performance and accessibility. Ensure all dynamic data is validated.
+
+## Playwright Execution Rules
+- **Default to Headless**: All Playwright CLI invocations MUST use headless mode by default. This is essential for CI/CD environments, batch execution, and minimizing resource usage without disrupting the user's workspace.
+- **Headed for Debugging Only**: Only explicitly append `--headed` (or use `headless: false` in configurations) when visually debugging complex interactions or UI state issues, or when specifically requested by the user. Ensure this is reverted before final completion unless it's a specific requirement (like testing browser extensions).
+
+When frontend validation uses Playwright or browser automation, follow `artifact-hygiene.md` for output placement and cleanup instead of creating ad hoc repository artifacts.